Skip to content

Scripts

One row per script under .act/scripts/; the per-script sections below are each script’s own --help output, not retyped by hand. Regenerate with python .act/scripts/script_docs.py after changing a script’s arguments — --check catches drift, and doctor.py reports it as a finding.

Script Purpose Call
act_local_tidy.py Keeps .act-local/ small. Throwaway material (probes, scratch projects, old backups, leftovers of earlier versions) piles up there without… direct (session start runs it daily in the background; --task is a step of skill act-commit)
act_profile.py The scope of the template inside one project — docs/ai/config.md § Scope: profile (minimal | standard | full) and exclude (a comma list… library
actlib.py Shared library for every script under .act/scripts/ and .act/hooks/ — the single place that knows how to resolve template vs. project… library
adopt.py Mechanical executor of an approved adoption table (skill act-adopt, steps 4 and 7). Runs from a template checkout or from a project… direct (used by skill act-adopt (stage 6); --carry packages takes the packages of the project it runs from into the target as resting folders (and zips), never active)
adopt_baseline.py Baseline check of an existing project before its first commit with this template (skill act-adopt). A project taken over has never been… direct (used by skill act-adopt (step 7b, before the first commit))
adopt_config.py Carry the settings of an older German AI-CONFIG.md (the predecessor template’s control file) over into the project’s docs/ai/config.md… direct (used by skill act-adopt (stage 6))
adopt_entries.py Batch writer for the content step of an adoption (skill act-adopt). The model reads the old material in whatever format it has and writes… direct (used by skill act-adopt (stage 6))
adopt_passages.py Mechanical insertion of an adopted project’s own passages into docs/project/coding_rules.md and docs/README.md (skill act-adopt, step 6… direct (used by skill act-adopt (stage 6))
adopt_scan.py Read-only sighting of an existing project’s documentation and AI-tooling material, before adoption (skill act-adopt). Walks the target… direct (used by skill act-adopt (stage 6); names the packages a target already has)
advisory.py Warnings from the template author to projects running an affected template version (“advisories”). The template source carries an orphan… direct (session start fetches daily in the background; --ack also by the chat sentences)
board.py Generate the board — a fully derived snapshot (current branch, last commit, dirty state, recent journal entries, one “Waiting for you” list… direct
compact_check.py Check the sections of the archive collection files (entries.py compact) against their full text, and the monthly overview against the ids… skill act-compact
config.py Show and set the settings in docs/ai/config.md without a model: the overview of every setting, one setting with its allowed values… direct (also answers /act-config through dispatch.py)
context_size.py Context size of the running Claude Code session, for the status line (“ctx 127k”) and for the one-time /clear hint… direct (also imported by the status line and the context hint)
doctor.py Mechanical half of the reconcile skill act-doctor — the cheap checks that run after every update and on demand, without a model in the… direct (judging the findings: skill act-doctor)
entries.py Create and account for the project’s short-lived entry files — tasks, backlog items, journal entries, and docs/ai/inbox/ entries (question… direct
feedback.py Voluntary feedback from a derived project to the template author — so real work in real projects turns into better default rules, scripts… skill act-feedback (--status/--due alone are direct)
feedback_privacy.py The privacy checks that decide whether a string may leave the project as part of a feedback payload (.act/scripts/feedback.py) — patterns… library
forge.py A small REST client for the project’s git host (GitHub, GitHub Enterprise, GitLab.com and self-hosted GitLab) — the one script the skills… skills act-pr, act-issue, act-integrations (reads are direct; every write shows a preview and needs --apply after the human’s “yes” (topics/live-systems.md))
frontmatter.py One shared frontmatter parser for every “—\n…\n—\n” block under .act/ and docs/ai/local/ – used to be two: tiers.py’s… library
handover.py Answer “can this session be left now?” mechanically, read-only: uncommitted changes, started tasks without a working-state line, inbox… skill act-handover
i18n_check.py Check a project’s translation files for completeness and consistency — the mechanical half of skill act-check-translations. Code-only… skill act-check-translations
id_links_install.py One-time, per-machine setup of the clickable entry ids (editor support). Copies the language server and its helper to a per-user folder… direct (optional editor support, see topics/id-links.md; writes only under ~/.act/id-links/)
id_links_lsp.py Language server that makes entry ids such as T12, B7, Q3 or U5 clickable in Markdown files opened in an editor (VS Code, IntelliJ with an… direct (language server over stdio, started by the editor from the copy id_links_install.py makes, not by hand)
ideas.py The per-person ideas file docs/ai/concept/ideas-<identity>.md — one versioned file for every person on a project, written by that person… direct (session start and init call it; run by hand to record entries as processed)
incidents.py The incident log. Hooks and scripts note what went wrong without stopping anyone and that the human should see later: a protected file a… library
info.py Show, in a compact block, which project this session works in and its state: project name, folder and host, the session name the project… skill act-info
init.py Turn a checkout of this template into a project (“here, in this clone”), or dock onto an existing/empty directory (“–target”). Ten steps… direct (--target from a project carries its packages resting (--carry packages: folder and zip, no lock entry) and loads the packages of the target’s own lock; it never activates a resting folder)
integrations.py Find out which ways lead from this project to its repo host and issue tracker (REST access through forge.py, MCP servers) and what each one… skill act-integrations (status alone is direct)
log.py Write one line to ai.log at the project root (AGENTS.md § “Logging (optional)”, .act/rules/topics/logging.md) and the small tools to read… direct
manifest.py Generate or verify .act/MANIFEST.json — a SHA-256 hash per file under .act/, used to detect local edits to the template before an update… direct
move_doc.py Moves a document (a file, or a folder with everything in it) below docs/ to a new place and pulls the references along, so a reorganisation… skill act-audit-docs
package_load.py Loading of the active packages (the lock’s packages record, folders under .act-local/packages/): what a package brings takes effect in… library
package_scan.py The static scan of a package folder: what in it can act on the project beyond text. It only reads the folder - it never imports, runs or… direct (reads the folder only, runs nothing in it)
packages.py Gets a package, reads it and makes it active or inactive: validates a package folder or zip against the template and prints what installing… direct (plan, list, index, settings without pairs and add/remove without --yes write nothing into the project; settings <id> <key>=<value> writes docs/ai/config.md only; fetch writes .act-local/packages/<id>-<version>.zip and .zip.sig only; add --yes also runs the package’s install.py)
rules.py Read the effective rules — the template’s rule sets after the project’s own checkboxes, replacements and additions are applied. One… direct
script_docs.py Generate .act/scripts/README.md — a reference for every script under .act/scripts/, built from each script’s own --help output plus a… direct
security_deep.py Security check “Art C”: a deep, cross-language scan with Semgrep over the files changed since a ref (default: the latest tag) or the whole… direct (used by skill act-release with security-check: full)
security_scan.py Security check Art B: a live library-vulnerability lookup against the lock files an ecosystem actually has, run either as a manual command… direct (also run before a commit that touches a lock file and daily at session start, with security-check: deps/full)
seo_check.py Code-only SEO checks over a project’s HTML, templates, Markdown pages and framework config — the mechanical half of skill act-seo. Reads… skill act-seo
seo_crawl.py Crawl of a running site — the crawl half of skill act-seo. Starts at one base URL, follows the internal links of the same origin (scheme… skill act-seo
seo_lighthouse.py Lighthouse measurement for the URLs of a running site — the lab-measurement half of skill act-seo. Runs a pinned Lighthouse version… skill act-seo
settings_export.py act-export-settings — write the project’s own rule deviations (and, with a switch, local scripts/checklists) to a portable settings file… skill act-export-settings
settings_format.py Data model, parser and serializer for the settings file (“settings.md”) — the portable snapshot of a project’s own rule deviations (and, in… library
settings_load.py act-load-settings — import a portable settings file (or several) into this project: the counterpart to settings_export.py. Runs the same… skill act-load-settings
skills.py List the project’s skills like a man page (name + one-line description from each SKILL.md’s frontmatter), or print one skill’s SKILL.md… direct (used by skill act and by dispatch.py’s /act fast path)
tiers.py Resolve a role’s tier/reasoning – never a real model name anywhere else under .act/ – into a concrete model alias/effort pair for one… library
unit_copies.py tool copies for a project’s own skills and roles — a skill written by hand under docs/ai/local/skills/<name>/ gets its copies under… direct (session start and update.py call it; run by hand to create the copies at once)
update.py Pull a newer state of the template into an already-initialized project. Ten steps, always in the same order: fetch the template into a temp… skill act-update (--plan and --versions alone are direct (skill act-version); names each active package’s requires-template and a newer zip, fetches no package and runs no package code)
usage.py Local usage counter — how often each role starts, at which tier/model; how often each skill, slash command, script and checklist is used… direct

Call: direct (session start runs it daily in the background; --task is a step of skill act-commit)

usage: act_local_tidy.py [-h] [--list | --apply | --task ID]
Keep .act-local/ small: removes tmp/ entries older than 7 days that belong to no open task, all
but the newest 5 backups, and unknown old entries. Without an option the plan is listed and
nothing is written.
options:
-h, --help show this help message and exit
--list list what would be removed (default); writes nothing
--apply remove per the plan, honouring `act-local-tidy` (block|warn|off) in
docs/ai/config.md and the report-first rule (removal only on a calendar day after a
report-only result was shown; a hand run that only reports counts as shown)
--task ID remove .act-local/tmp/<ID> and .act-local/tmp/<ID>-* of any age (the act-commit
step)

Call: direct (used by skill act-adopt (stage 6); --carry packages takes the packages of the project it runs from into the target as resting folders (and zips), never active)

usage: adopt.py [-h] --target DIR (--apply | --finish | --abort) [--plan] [--force]
[--confirm-no-targets] [--language-docs CODE] [--language-chat CODE]
[--update-channel {release,latest}] [--carry LIST]
Carry out an approved adoption table: move legacy sources, install the template, then bridge/remove adopted sources. Never commits.
options:
-h, --help show this help message and exit
--target DIR the project to adopt (a git repository)
--apply branch, legacy moves, init.py --target
--finish bridges, removals, settings entries, marks, references, doctor, inbox
report
--abort the way back after --apply: undo it, delete the branch
--plan validate and show what would happen, change nothing
--force with --abort: copy work done since --apply to .act-local/adopt/aborted/
first, then abort
--confirm-no-targets with --apply: the owner confirmed that adopt rows without a target are
applied although --finish's "content not adopted?" check cannot cover them
--language-docs CODE with --apply: language of docs/ (e.g. de), passed on to init.py; default
en
--language-chat CODE with --apply: chat language (a code, or auto), passed on to init.py
--update-channel {release,latest}
with --apply: update channel (release or latest), passed on to init.py;
default release
--carry LIST with --apply: what init.py carries over from the project this runs from,
comma-separated (skills, rules, exceptions, overrides, topics, agents,
packages; all = default, none), passed on to init.py --carry
TABLE <target>/.act-local/adopt/table.json — {"rows": [...]}, exactly one row per scan.json row:
path as in scan.json class as in scan.json (must match)
action adopt | legacy | keep | delete
target adopt only: destination path or list of paths (filled by the content step)
done adopt only: true once the content is at its target (required for --finish)
confirmed true: the owner confirmed this one row (see below) note free text
ALLOWED ACTIONS PER CLASS
log legacy, keep ai-machinery adopt, legacy, delete, keep
ai-config adopt, legacy, keep, delete work adopt, legacy, keep, delete
project-doc adopt, legacy, keep; delete only with confirmed
predecessor adopt, legacy, keep; delete only "template only" (scan origin) or with confirmed
unknown keep; adopt/legacy/delete only with confirmed
REFUSED (whole run, with a list) on: a path that is not plain relative posix or not on disk; a
path not in scan.json, or a scan.json row without a table row; a class differing from scan.json;
a disallowed action; a row whose note (scan's or table's) says "never bridge"/"git-ignored/local"
with action delete or legacy, or adopt into a bridge file; any non-keep action on a link or below
one; any non-keep action below a source/test/content tree (see below) without confirmed; a unit
folder holding untracked or git-ignored files that would be moved or removed, without confirmed
(with it, those files go to .act-local/adopt/rescued/ first); an adopt target equal to or below its own
source (unless the source moves before init) or below any path that is deleted, archived, removed
or bridged; a path segment ending in a dot or space; paths are compared case-insensitively where
the file system is; a scan.json that no longer matches a fresh scan (--apply); on Windows a
legacy path of 260 characters or more while the repository does not set core.longpaths
(`git config core.longpaths true`).
Source/test/content trees (first path segment): __tests__, app, apps, assets, client, components, content, e2e, fixtures, lib, packages, pages, public, server, spec, specs, src, static, test*.
--apply: clean tree (untracked only under .act-local/), new branch act-adopt (an existing branch
refuses; a recorded state prints it and exits 0), `legacy` rows moved byte-identical to
docs/ai/work/archive/legacy/<old path> (sha256 before = after) — with every AI-tool config path segment
renamed first (`.claude`/`.codex`/`.gemini`/`.cursor`/`.agents` -> `_claude`/…,
`.github/agents`/`.github/prompts` -> `_agents`/`_prompts`, `.github/copilot-instructions.md`
-> `….legacy`, a `CLAUDE.md`/`AGENTS.md`/`GEMINI.md` at any depth -> `….legacy`, so no tool
reads the archived copy as its own configuration) — then staged by path; a git
call that fails stops the run with no accounting. An old skill/agent carrying the name of a
template unit, or a file at a place init.py writes itself (docs/ai/ skeleton, docs/ai/rules.md,
docs/project/coding_rules.md, docs/README.md), moves there too unless it is a delete row
(removed) — a kept file at such a place stays and init leaves it. Then init.py --target
--non-interactive --no-commit (detected at runtime; only an init.py without that flag makes its
own first commit instead); existing CLAUDE.md/AGENTS.md stay until --finish.
--carry <list> goes on to init.py: when this runs from a project (not the template checkout), init.py
takes over that project's own skills, rules, exceptions, overrides, topics and agents (own roles and
own lines in the role bridges) and its active packages, carried resting (the folder under .act-local/packages/
and the zip with its signature where the project has them; no lock entry, check row or copy: the new project's
session start names each with `/act-packages add <id>`, and the owner says yes there; a package with neither
folder nor zip there is named in the inbox with the fetch) unless --carry names fewer.
A target equal to the project this runs from, or inside it (also through a symlink or junction), is
refused in every mode.
--finish: every adopt row done with its target on disk; adopted ai-config files that init has a
bridge for become that bridge (protected rows stay as they are), other adopted sources and
delete rows removed (git rm); an adopt target docs/ai/local/skills/<name>/... or
docs/ai/local/agents/<name>.md is an own unit and gets its tool copies/bridge like
act-load-settings writes them (skill copies recorded in .act-lock.json § copies) — refused if
<name> is a template unit's (that would be an override; a row note "override" leaves it to the
template's copy mechanism); doctor.py, references to moved/removed paths, report
docs/ai/inbox/report-<stamp>-adoption-report.md. A reference in docs/project/ and docs/README.md
to a path that is gone — or to a folder the adoption leaves without any file — is bent to its
new place (legacy copy, or the one successor of an adopt row), the link target only:
the target of a Markdown link or of a reference definition `[x]: path` (relative stays
relative, anchor kept); no other text changes, code blocks never. A path in backticks is text:
never changed, only listed ("mention in text — not changed") with both readings, relative to
the file and to the root. The full list, bent and left with the reason, goes to
.act-local/adopt/references.txt (--finish --plan: .act-local/adopt/references.plan.txt,
the terminal gets the counts); the report lists it inline up to 50 lines. Hook commands and
Bash(...) permission rules in .claude/settings.json whose executed script (the first word of a
command, or the word after python/bash/node/… or "$VAR"; bare, ./ or $CLAUDE_PROJECT_DIR/ path)
lies at or below a gone delete or legacy row are removed — an emptied hook group or event with
them, nothing else changes, line endings kept; a script that is only an argument, Read/Edit/
Write rules and entries on scripts still on disk never. Listed for removal by hand instead: a
file whose layout json.dumps cannot reproduce, an entry whose script was already missing before
the adoption or went with an adopt row, a statusLine, and .claude/settings.local.json.
An adopt target (or a file below one that changed since --apply) whose line 1 is
<!-- act:default --> loses that line — except docs/ai/config.md (values adopted, its text
stays scaffold to translate).
docs/ai/work/archive/legacy/_act-renames.md (act:default, old path -> renamed path table) is written when at least one
legacy path was renamed; nothing when none was.
--finish --plan shows all of it first. A second --finish says "already finished".
An adopt target that still has the content it had right after --apply, or that only
adopt_config.py changed since (its hash as recorded in .act-local/adopt/config-touched.json), is
refused ("content not adopted?").
--apply with an adopt row of class project-doc, ai-machinery, predecessor or unknown that has no
target: refused unless --confirm-no-targets is given (the owner's yes) — without a target recorded
at --apply, --finish cannot refuse a row whose content was never carried over. ai-config and work
rows never need one (their content becomes proposals and entries). --apply --plan prints the warning and goes on.
--apply --language-docs <code> --language-chat <code|auto>: passed on to init.py, so the
docs language and the init todos are right from the start. They are recorded in state.json
("languages") and adopt_config.py keeps them; it sets `language-docs` from an old AI-CONFIG.md
only where none was given.
--apply refuses a detached HEAD. It backs up .claude/settings.json (init.py merges hooks into it).
--abort: the way back after --apply or a stopped --apply, resumable (state.json is rewritten after
every step). Refused while act-adopt carries a commit other than init.py's, and while work was
done since --apply — a changed file init.py created, an uncommitted edit to a tracked file, a
new file where a moved unit returns — unless --force, which first copies those files to
.act-local/adopt/aborted/<path> and lists them. Then: removes the files init.py created that are
unchanged (or saved), puts moved units back only from a legacy copy that still holds the moved
content, puts rescued files back, checks out the base branch, restores the settings backup,
deletes act-adopt and the state. New files it did not create are left in place and listed.

Call: direct (used by skill act-adopt (step 7b, before the first commit))

usage: adopt_baseline.py [-h] --target TARGET [--write-gitignore] [--book]
Baseline check of an existing project before its first commit: missing secret-file patterns in
.gitignore, the commit scans run once over the tree, findings booked as backlog entries. Read-only
unless a switch says otherwise; never prints a secret value.
options:
-h, --help show this help message and exit
--target TARGET the project to check (a Git repository)
--write-gitignore append the missing patterns to .gitignore
--book create the backlog entries (default: list them)

Call: direct (used by skill act-adopt (stage 6))

usage: adopt_config.py [-h] --target DIR [--source FILE] [--plan]
Carry an old AI-CONFIG.md's settings into docs/ai/config.md; report everything else.
options:
-h, --help show this help message and exit
--target DIR the project (already set up by adopt.py --apply)
--source FILE the old AI-CONFIG.md (default: see Usage)
--plan show the report, write nothing

Call: direct (used by skill act-adopt (stage 6))

usage: adopt_entries.py [-h] --target DIR --from JSON [--plan]
Write a checked batch of adopted entries (tasks, backlog, questions, todos, reports, notes,
proposals) as entry files; the whole batch is refused on any conflict.
options:
-h, --help show this help message and exit
--target DIR the project (already set up by adopt.py --apply)
--from JSON the batch file (UTF-8 JSON)
--plan check and show what would be written, write nothing

Call: direct (used by skill act-adopt (stage 6))

usage: adopt_passages.py [-h] --target DIR --into {coding,readme} --from FILE [--plan]
Insert an adopted project's own passages into docs/project/coding_rules.md or docs/README.md,
heading levels shifted, target line endings preserved.
options:
-h, --help show this help message and exit
--target DIR the project (already set up by adopt.py --apply)
--into {coding,readme}
which file to insert into
--from FILE UTF-8 file holding the passage(s), cut byte-identical from the old source
--plan check and show what would change, write nothing

Call: direct (used by skill act-adopt (stage 6); names the packages a target already has)

usage: adopt_scan.py [-h] [--target DIR] [--json]
Read-only sighting of an existing project's documentation/AI-tooling sources before adoption.
options:
-h, --help show this help message and exit
--target DIR directory to scan (default: this project's root)
--json print the JSON payload instead of the human-readable table
ALLOW-LIST (exact, case-sensitive) — the only way into the four classes with a downstream action:
ai-config root AGENTS.md CLAUDE.md CLAUDE.local.md GEMINI.md CONVENTIONS.md AI-CONFIG.md
.aider.conf.yml .cursorrules .clinerules .windsurfrules .mcp.json;
.github/copilot-instructions.md, .github/instructions/*.instructions.md,
.claude/settings.json, .claude/settings.local.json (never bridge or delete),
.claude/settings.local.json.example, .claude/rules/*.md, .cursor/rules/,
.cursor/mcp.json, .gemini/settings.json, .junie/guidelines.md (never a nested one)
ai-machinery one row per unit under .claude/{agents,skills,commands,scripts,hooks}/,
.github/agents/, .github/prompts/, .codex/{agents,skills,commands,scripts,hooks}/,
.gemini/commands/, and .cursor/ except rules/ and mcp.json
log root ai.log, ai.log.*.bak, ai.log.state.json, ai.log.raw.jsonl; in a signed
docs/ai/: names with ledger/journal/protokoll/archive/archiv, template-feedback/sent/**;
a dated file (YYYY-MM-DD*) in journal(s)/ or docs/journal(s)/
work root TODO.md, TODO; in a signed docs/ai/: names with task(s)/aufgabe(n)/backlog/
question(s)/frage(n)/board/inbox
Signed docs/ai/: holds at least two of board.md, tasks.md, ledger.md, questions.md, backlog.md,
or the target has .claude/template.json. Any keyword hit elsewhere yields only "unknown" with a
hint ("log?"). The same goes for the words chatlog, umbau, weiter, handover (whole tokens, anywhere in
the path, "@" counts as a separator) and a folder named memory: unknown + hint "work?" and an info line
"possible home-made work system" — a hint for the owner, never a class. A symlink/junction at an allow-listed place is one "unknown" row ("link to …"),
never followed. Git-ignored rows keep their class and get a "git-ignored/local" note.
project-doc also covers ADR folders: adr/, adrs/, decisions/, decision-records/.
PREDECESSOR (the target has .claude/template.json): a row that would be "unknown" but is in the
base_commit tree, or is one of the predecessor's named parts (docs/ai/README.md, checklists.md,
config-guide.md, ai-config-hilfe.md, resources.md, template-feedback/, docs/project/coding_rules.d/,
.claude/mcp-katalog.md, .mcp.json.example) — including .claude/template.json, .claude/TEMPLATE-
LICENSE and .github/workflows/ci.yml, which no document extension lets the generic doc
scan reach, so they are sighted by name here too, proposed "legacy" (template.json,
TEMPLATE-LICENSE: never a blind delete) or, for ci.yml, "legacy" only while it still carries the
predecessor's own placeholder steps (an `echo "TODO` line naming create-project.py or
checklists.md), else "keep" — is class "predecessor". A row already "project-doc"
reclassifies to "predecessor" only for a curated file name (docs/ai/README.md etc.) or, under a
PREDECESSOR_PREFIXES directory (template-feedback/, coding_rules.d/), only when the path is
confirmed present in the base_commit tree — a file the project added on its own under that same
directory (docs/project/coding_rules.d/our-api.md, never part of any template) stays project-doc,
flagged with a note that its directory is otherwise the predecessor's. Every row gets an origin:
"template only" (each line is the base_commit's, after putting in the values of template.json §
values; lines removed since do not count), "own text: n lines", or "unknown" when the base_commit
is not in the history.
PROPOSED ACTION (column "-> …", JSON "proposed"; the owner decides): log, work -> legacy;
ai-config -> adopt, legacy if template only, keep for .claude/settings*.json and protected rows,
for .claude/settings.local.json.example of a predecessor delete if template only, else legacy;
ai-machinery -> delete if template only, keep if its origin is unknown, else adopt (a skill/agent
unit whose own name is free) or legacy (a skill/agent unit whose name collides, case-insensitively,
with the new template's own — its reserved "-<role>-high" variant included — adopt would be refused
at --finish; the row's note points at the manual override) or keep (the rest); a README/description
file directly under a MACHINERY_DIRS folder whose every OTHER sibling proposes delete/legacy follows
them by its own origin instead of the generic ai-machinery rule (a README only describing scripts
that are all gone is not current documentation either); project-doc -> keep (a root README.md too),
docs/README.md and docs/project/coding_rules.md adopt (legacy if template only); predecessor ->
delete (tooling, examples, docs/project/coding_rules.d/: template only), else legacy (docs, own
lines included — the origin shows them); unknown -> keep. A link or protected row is always keep.
Line breaks do not count: a line that is a stretch of a base paragraph (whitespace collapsed, at
least 20 characters) is the template's.

Call: direct (session start fetches daily in the background; --ack also by the chat sentences)

usage: advisory.py [-h] [--status | --ack [ID ...] | --check-file PATH | --refresh]
Warnings from the template author for the installed template version (advisories). Without an
option: --status.
options:
-h, --help show this help message and exit
--status show the installed version, the cache and each advisory as active, acked or
not affected (default)
--ack [ID ...] acknowledge the named advisories (no id: every active one); it then no longer
shows at session start, in the status line or on the board
--check-file PATH validate an advisories.json file: print the accepted ids and each rejection
with its reason, exit 1 if anything was rejected; works outside a project
--refresh fetch the source's advisories branch now (5 s limit per git call) instead of
waiting for the daily background check; needs `advisory-check` on

Call: direct

usage: board.py [-h] [--chat-language CODE] [--identity NAME] [--shared]
Write the board view chosen by `board` in docs/ai/config.md: docs/ai/board.md (docs, shared) or
.act-local/board-<branch>.md (local).
options:
-h, --help show this help message and exit
--chat-language CODE remember the chat language recognized for this person on this machine
(.act-local/identity.json) while language-chat is auto, then exit
--identity NAME set or change this checkout's identity (the short form of NAME, .act-
local/identity.json), keep its other keys, then exit; board and ideas
files of a former identity are not renamed
--shared with `board: shared`: also write the versioned docs/ai/board-<identity>.md
(act-commit calls it; a plain run never touches that file)

Call: skill act-compact

usage: compact_check.py [-h] [--root ROOT] [--month YYYY-MM] [--restore] [--no-overview]
Check archive collection sections and the monthly overview against the full text in Git.
options:
-h, --help show this help message and exit
--root ROOT project root (default: the current folder)
--month YYYY-MM check only the collections of this month
--restore write the full body back into every section that lost something
--no-overview skip the check of the monthly overview

Call: direct (also answers /act-config through dispatch.py)

usage: config.py [-h] [--root PATH] [KEY [VALUE ...] ...]
Show or set the settings in docs/ai/config.md. No arguments: every setting. One key: its value,
allowed values, default, effect and notes. A key and a value: write the value into that row
(nothing is committed).
positional arguments:
KEY [VALUE ...] the key, then the value (words are joined with one space)
options:
-h, --help show this help message and exit
--root PATH project root (default: the project this script belongs to)

Call: direct (also imported by the status line and the context hint)

usage: context_size.py [-h] [--transcript TRANSCRIPT] [--report] [--json]
Context size of the running session, from its transcript.
options:
-h, --help show this help message and exit
--transcript TRANSCRIPT
path of a transcript (.jsonl); default: this session's
(CLAUDE_CODE_SESSION_ID), else the newest of this project
--report whole-session report: base load, cache hit rate, cache breaks
--json print the whole-session report as JSON (implies --report)

Call: direct (judging the findings: skill act-doctor)

usage: doctor.py [-h] [--target DIR] [--json] [--inbox] [--accept ID] [--accept-all]
Mechanical project/template reconciliation — see the header comment for the full list of checks.
options:
-h, --help show this help message and exit
--target DIR check this project instead of the current checkout
--json machine-readable output
--inbox also write docs/ai/inbox/report-<YYYYMMDD-HHMM>-doctor.md if there are findings,
and one inbox question per new tier proposal and per check that refused workers
often
--accept ID accept the current template text for ID, a rule id or skill:<name> (repeatable)
--accept-all accept the current template text for every stale override/off

Call: direct

usage: entries.py [-h] {new,assign,state,start,list,check,archive,compact,purge} ...
Create and account for docs/ai/'s per-entry task/backlog/ledger/inbox files (inbox: question |
todo | report | note).
positional arguments:
{new,assign,state,start,list,check,archive,compact,purge}
new create a new entry file
assign hand out ids still missing ('team' mode: only on the default branch)
state append a working-state line for an open task to .act-local/state/ — needs
an id already assigned; in 'team' mode a task awaiting one (filename only)
has no `state` target yet. With --wait the line marks the task as waiting
(for the human, a review, an outside party) until the next plain state
line
start mark an open task as started (versioned `started:` header) without a state
line; `state` does the same on its first call
list list entries, optionally filtered by kind
check report a duplicate id or an entry file that isn't valid UTF-8
archive archive a finished task, backlog item or inbox entry, or a concept file
(directly in docs/ai/concept/ or anywhere below docs/project/concepts/),
by moving it to docs/ai/work/archive/ - an inbox entry gets `status:
done`, a task `finished: <timestamp>`, every file `archived: <date>`;
files an entry links beside itself (pasted images) move along, generic or
colliding names get the entry's id in front, links are rewritten; links to
a moved concept in other files follow it; `compact` folds the archive into
monthly files
compact merge archived entries older than 7 days (and journal entries) into one
collection file per kind and month in docs/ai/work/archive/ (Q-2026-09.md,
T-, B-, U-, other-, ledger-), one section per entry with an anchor such as
#<id>; links in the project are rewritten, the head of each collection
names the commit that holds the full text; concept files go into
other-<YYYY-MM>.md; each month's overview <YYYY-MM>.md gets one line per
Q, T, B and U entry; needs the entries committed; running it twice changes
nothing
purge retired: prints one line and exits 0, so an old call does not fail;
archived entries stay in docs/ai/work/archive/ until `compact` folds them
into their monthly file
options:
-h, --help show this help message and exit
usage: entries.py new [-h] [--id ID] [--formerly OLD_ID] [--status {open,answered}]
[--for IDENTITY] [--body-file PATH] [--triage]
{backlog,inbox,ledger,note,question,report,task,todo} title [title ...]
positional arguments:
{backlog,inbox,ledger,note,question,report,task,todo}
task | backlog | ledger | question | todo | report | note (inbox: alias
for todo)
title entry title — becomes the file's heading
options:
-h, --help show this help message and exit
--id ID keep this id (T/B/Q/U<n>, optional sub-letter); refused if taken or wrong
prefix
--formerly OLD_ID header line "formerly: <old id>"
--status {open,answered}
question/todo/report/note entry (default open)
--for IDENTITY task/todo/report/note entry: recipient (todo/report/note default all, task
default this identity; all = shared)
--body-file PATH body below the heading, copied verbatim (UTF-8); a question ends with an
empty answer label below it, unless --status answered or the text has one
already
--triage todo/note entry: write `triage: open` (a chat message captured by hand, to
be processed right after the answered entries)
usage: entries.py assign [-h]
options:
-h, --help show this help message and exit
usage: entries.py state [-h] [--wait] T-ID text [text ...]
append a working-state line for an open task to .act-local/state/ — needs an id already assigned;
in 'team' mode a task awaiting one (filename only) has no `state` target yet. With --wait the line
marks the task as waiting (for the human, a review, an outside party) until the next plain state
line
positional arguments:
T-ID the task's id, e.g. T12
text the state line's text, e.g. "step 3 running, next: ..."
options:
-h, --help show this help message and exit
--wait mark the task as waiting; a later plain `state` line ends the waiting
usage: entries.py start [-h] T-ID
mark an open task as started (versioned `started:` header) without a state line; `state` does the
same on its first call
positional arguments:
T-ID the task's id, e.g. T12
options:
-h, --help show this help message and exit
usage: entries.py list [-h] [{backlog,inbox,ledger,note,question,report,task,todo}]
positional arguments:
{backlog,inbox,ledger,note,question,report,task,todo}
task | backlog | ledger | question | todo | report | note (inbox: alias
for todo)
options:
-h, --help show this help message and exit
usage: entries.py check [-h]
options:
-h, --help show this help message and exit
usage: entries.py archive [-h] ID-OR-FILE
archive a finished task, backlog item or inbox entry, or a concept file (directly in
docs/ai/concept/ or anywhere below docs/project/concepts/), by moving it to docs/ai/work/archive/
- an inbox entry gets `status: done`, a task `finished: <timestamp>`, every file `archived:
<date>`; files an entry links beside itself (pasted images) move along, generic or colliding names
get the entry's id in front, links are rewritten; links to a moved concept in other files follow
it; `compact` folds the archive into monthly files
positional arguments:
ID-OR-FILE an id such as Q<n> or T<n>, the entry file's path, or a concept file's path (its
bare file name too, if it is unique in the two concept folders)
options:
-h, --help show this help message and exit
usage: entries.py compact [-h] [--plan] [--today YYYY-MM-DD]
merge archived entries older than 7 days (and journal entries) into one collection file per kind
and month in docs/ai/work/archive/ (Q-2026-09.md, T-, B-, U-, other-, ledger-), one section per
entry with an anchor such as #<id>; links in the project are rewritten, the head of each
collection names the commit that holds the full text; concept files go into other-<YYYY-MM>.md;
each month's overview <YYYY-MM>.md gets one line per Q, T, B and U entry; needs the entries
committed; running it twice changes nothing
options:
-h, --help show this help message and exit
--plan show what would be merged, write nothing
--today YYYY-MM-DD count the keep window from this day (tests)
usage: entries.py purge [-h]
retired: prints one line and exits 0, so an old call does not fail; archived entries stay in
docs/ai/work/archive/ until `compact` folds them into their monthly file
options:
-h, --help show this help message and exit

Call: skill act-feedback (--status/--due alone are direct)

usage: feedback.py [-h] [--status | --enable | --disable | --add | --plan | --send |
--direct TEXT | --due | --postpone DAYS | --clear | --discard-harvest]
[--contact EMAIL] [--target DIR]
[--kind {rule,script,skill,workflow,docs,bug,mcp,link}] [--title TITLE]
[--text TEXT] [--url URL] [--repo-url REPO_URL]
[--mode {off,confirm,automatic,manual,local}] [--force] [--yes]
Voluntary feedback to the template author - never without consent, never unseen.
options:
-h, --help show this help message and exit
--status show the current state
--enable set consent
--disable revoke consent
--add store a finding in the outbox; sends it at once with mode 'automatic' and
cadence 'immediate', or with --kind bug (consent and mode still apply);
refused with mode 'local'
--plan show the payload, send nothing (default)
--send send if consent, the privacy check and the cadence gate all allow it
--direct TEXT send a hand-written message at once - works even with feedback off, never
with local
--due report whether a reminder is due under the current cadence
--postpone DAYS pause the due reminder for this many days and count it as a postponement
--clear discard every waiting entry, send nothing
--discard-harvest remove --target's .act-local/adopt/harvest.md, add nothing to the outbox
--contact EMAIL with --direct: a reply address for this one message (never reused)
--target DIR act on the project at DIR instead of the current checkout (act-adopt)
--kind {rule,script,skill,workflow,docs,bug,mcp,link}
with --add
--title TITLE with --add: one line
--text TEXT with --add: two to six sentences
--url URL with --add --kind link: the public address
--repo-url REPO_URL with --enable: public repo URL (optional)
--mode {off,confirm,automatic,manual,local}
with --enable: off, confirm, automatic (default), manual, local (never
sends anything)
--force with --send: lift the cadence gate (not the consent gate)
--yes with --send and mode 'confirm': actually send after showing the payload

Call: skills act-pr, act-issue, act-integrations (reads are direct; every write shows a preview and needs --apply after the human’s “yes” (topics/live-systems.md))

usage: forge.py [-h] [--root ROOT] [--remote REMOTE] [--json] <command> ...
REST client for GitHub and GitLab issues and pull/merge requests (stdlib only). Writes only
preview unless --apply is given. The token comes from the environment or .env, never from the
command line.
positional arguments:
<command>
detect show host, kind, project, API base, where the access comes from and whether
the token may go to the host
whoami the user the token belongs to
project name, default branch, visibility and URL of the project
default-branch the project's default branch
target-branch branch for pull requests: config, remote default, or development/develop/main
issues list issues
issue show one issue
prs list pull/merge requests
releases list published releases
branch-name branch name for an issue
create-issue create an issue (preview without --apply)
comment comment on an issue (preview without --apply)
close-issue close an issue (preview without --apply)
create-pr create a pull/merge request (preview without --apply)
close-pr close a pull/merge request (preview without --apply)
create-release publish a release for an existing tag (preview without --apply)
options:
-h, --help show this help message and exit
--root ROOT project root (default: found from the current directory)
--remote REMOTE git remote to use (default: origin, else the only one)
--json print one JSON document instead of text

Call: skill act-handover

usage: handover.py [-h] [--root ROOT] [--json]
Check mechanically whether this session can be left (read-only).
options:
-h, --help show this help message and exit
--root ROOT project root (default: found upward from the working directory)
--json machine-readable output

Call: skill act-check-translations

usage: i18n_check.py [-h] [--root ROOT] [--base BASE] [--json] [--no-code] [--no-namespace]
Check translation files for missing, extra, empty and mismatching keys and for keys used in code
but not defined.
options:
-h, --help show this help message and exit
--root ROOT project root (default: current directory)
--base BASE base locale (default: en, else the largest)
--json print the report as JSON
--no-code skip the used/unused key check against source code
--no-namespace merge the files of one locale folder without a file-name prefix (Nuxt i18n
reading; detected on its own from nuxt.config.* with i18n and files)

Call: direct (optional editor support, see topics/id-links.md; writes only under ~/.act/id-links/)

usage: id_links_install.py [-h] [--home HOME]
Set up clickable entry ids for the editors: copies the language server to <home>/.act/id-links/,
packs the VS Code extension as a .vsix there and writes an import template for IntelliJ (LSP4IJ).
Installs nothing into an editor; prints the next steps and the way back. Safe to run again
(overwrites the same files).
options:
-h, --help show this help message and exit
--home HOME folder that takes the place of your home folder (default: your home folder)

Call: direct (language server over stdio, started by the editor from the copy id_links_install.py makes, not by hand)

usage: id_links_lsp.py [-h]
Language server (stdio) that turns entry ids such as T12 in Markdown files into links, go-to-
definition targets and hover cards for the matching entry under docs/ai/. Read-only, no network.
Started by an editor integration; without arguments it serves the Language Server Protocol on
stdin/stdout.
options:
-h, --help show this help message and exit

Call: direct (session start and init call it; run by hand to record entries as processed)

usage: ideas.py [-h] [--check | --seen | --ensure]
Entries of the per-person ideas file that are new or changed since they were last processed.
options:
-h, --help show this help message and exit
--check list new or changed entries (default)
--seen record every entry as processed
--ensure create the README.md and own file if missing

Call: skill act-info

usage: info.py [-h] [--limit N]
Show which project this session works in and its state: name, folder, host, session name, branch,
last commit, uncommitted changes, installed template version and channel, open tasks and what
waits for a human. Read-only, no network.
options:
-h, --help show this help message and exit
--limit N list at most N tasks and N waiting entries, then '+n more' (default 5)

Call: direct (--target from a project carries its packages resting (--carry packages: folder and zip, no lock entry) and loads the packages of the target’s own lock; it never activates a resting folder)

usage: init.py [-h] [--target TARGET] [--plan] [--non-interactive] [--no-commit] [--no-local]
[--carry LIST] [--no-profile] [--profile] [--language-docs CODE]
[--language-chat CODE] [--update-channel {release,latest}] [--methods LIST]
[--scope {minimal,standard,full}]
Turn a template checkout into a project, or dock onto an existing directory (--target). Inside a
project that is already set up, only --profile runs (see there); bringing .act/ up to date is
update.py's job.
options:
-h, --help show this help message and exit
--target TARGET create/dock in this directory instead of the current checkout
--plan show what would happen, change nothing
--non-interactive never prompt; take defaults, log open points to the inbox
--no-commit do everything except the final commit
--no-local --target only: don't carry over the source checkout's own rule/coding-rule
deviations and docs/ai/local/ (same as --carry none)
--carry LIST --target only: what to carry over from the source project, comma-separated
(default all): skills (own skills), rules (## Own rules), exceptions (rule
groups switched off, with reason), overrides (`replaces` lines and the
other docs/ai/local/ files: rule, script, checklist overrides), topics
(docs/ai/local/rules/topics/), agents (own roles in docs/ai/local/agents/
and own lines in the role bridges), packages (the source's active
packages, carried resting: folder and zip, no lock entry; `/act-packages
add <id>` activates each); none = nothing
--no-profile don't offer the owner profile at %APPDATA%\act\settings.md /
~/.config/act/settings.md (on by default)
--profile apply the owner profile without asking (its entries are shown first).
Inside a project that is already set up (no --target) this is the only
step that runs -- nothing else is touched, only what it wrote is committed
('catch up' path after a non-interactive first run); in a fresh clone or
with --target it is part of the full run
--language-docs CODE language of docs/ (e.g. de) instead of asking; default en (R-work-
language)
--language-chat CODE chat language (a code, or auto = follow the owner's messages) instead of
asking
--update-channel {release,latest}
what act-update follows: release = newest stable release tag (default),
latest = tip of the template's default branch; instead of asking
--methods LIST working methods to switch on (names from .act/methods/, comma-separated,
or none) instead of asking; default none
--scope {minimal,standard,full}
the scope profile of a new project (docs/ai/config.md § Scope) instead of
the detected one: full for a web project, standard for any other

Call: skill act-integrations (status alone is direct)

usage: integrations.py [-h] <command> ...
Find and probe (read-only) the ways to the repo host and issue tracker, and keep the result in
docs/project/integrations.md. Never writes to a live system.
positional arguments:
<command>
check detect, probe read-only, optionally write the file
status exit 0 if the file exists and is fresh, else 3
read-tools allow the read-only tools of a catalog server in .claude/settings.local.json
(--remove undoes it)
options:
-h, --help show this help message and exit

Call: direct

usage: log.py [-h] [--tail] [--grep PATTERN] [--lines N] [--no-color] [--status] [--reset]
[LEVEL] [AGENT] [TOPIC] ...
Write one line to ai.log (LEVEL agent topic text...), or --tail/--status/--reset it. See
.act/rules/topics/logging.md for when this runs and what a line looks like.
positional arguments:
LEVEL DEBUG|INFO|WARN|ERROR
AGENT who acted, e.g. orchestrator, builder#2
TOPIC one word, e.g. decision, commit, result
TEXT the line's message, joined with spaces (may itself start with '-')
options:
-h, --help show this help message and exit
--tail print the last lines of ai.log, then follow it
--grep PATTERN with --tail: only lines matching this pattern
--lines N with --tail: how many existing lines to print first (default: 20)
--no-color with --tail: plain text, no ANSI colors
--status show the effective config and label counters
--reset rename ai.log to ai.log.<timestamp>.bak

Call: direct

usage: manifest.py --write | --check

Call: skill act-audit-docs

usage: move_doc.py [-h] [--apply] [--root ROOT] source dest
Move a document below docs/ and pull its references along.
positional arguments:
source file or folder to move (project-relative)
dest new path (project-relative); must not exist
options:
-h, --help show this help message and exit
--apply do it; without it only the plan is printed
--root ROOT project root (default: current folder)

Call: direct (reads the folder only, runs nothing in it)

usage: package_scan.py <package folder>

Call: direct (plan, list, index, settings without pairs and add/remove without --yes write nothing into the project; settings <id> <key>=<value> writes docs/ai/config.md only; fetch writes .act-local/packages/<id>-<version>.zip and .zip.sig only; add --yes also runs the package’s install.py)

usage: packages.py [-h] {plan,fetch,index,add,remove,list,settings} ...
Validate a package zip or folder against the template and print the plan, fetch a package zip with
its signature into .act-local/packages/, list what a source's index offers, add a package (plan
and diff first, then --yes with the code shown), remove one, show or set a package's settings, or
list the packages the lock records and the folders resting there. Only `add --yes` runs package
code (its install.py).
positional arguments:
{plan,fetch,index,add,remove,list,settings}
plan stage a package zip or folder, check its origin and admission and print
what installing it would do (exit 1 with every reason when it is refused)
fetch download a package zip and its signature into .act-local/packages/ (never
unpacks, never activates) and print its origin
index list the packages of the first source whose index.json answers (id,
version, contents, tools, stack, RED reason), marking the active and
resting ones; writes nothing
add show what installing a package changes (plan, origin, a diff of every
project file) and with --yes <code> install it; the same id again is an
update
remove show what taking a package out changes and with --yes <id> do it
list packages in the lock (id, version, source, check) and folders resting
under .act-local/packages/ that the lock does not record
settings show or set the settings an active package asks for (its `## settings`
section), kept in docs/ai/config.md
options:
-h, --help show this help message and exit
usage: packages.py plan [-h] source
positional arguments:
source the package zip, or the package folder (package.md, pre-template/, post-template/,
install.py, install.md)
options:
-h, --help show this help message and exit
usage: packages.py fetch [-h] [--source SOURCE] id
positional arguments:
id the package id
options:
-h, --help show this help message and exit
--source SOURCE one place instead of `packages-sources`: an https:// address or a local folder
holding index.json
usage: packages.py index [-h] [--source SOURCE] [--json]
options:
-h, --help show this help message and exit
--source SOURCE one place instead of `packages-sources`: an https:// address or a local folder
holding index.json
--json print the same as JSON
usage: packages.py add [-h] [--yes CODE] source
positional arguments:
source a package zip (with <zip>.sig next to it), a package folder, or a package id: the
newest .act-local/packages/<id>-<version>.zip, else the resting folder .act-
local/packages/<id>/ (a folder named like an id: ./<name>)
options:
-h, --help show this help message and exit
--yes CODE install exactly the package whose code this is (the first 12 hex digits of its
sha256, shown by the run without --yes)
usage: packages.py remove [-h] [--keep] [--yes ID] id
positional arguments:
id the package id
options:
-h, --help show this help message and exit
--keep keep the folder .act-local/packages/<id>/ (it rests, nothing loads from it)
--yes ID take the package out; the value is the package id again
usage: packages.py list [-h]
options:
-h, --help show this help message and exit
usage: packages.py settings [-h] id [KEY=VALUE ...]
positional arguments:
id the package id
KEY=VALUE a key the package declares and its value (one line, no `|`); without any: show
options:
-h, --help show this help message and exit

Call: direct

usage: rules.py [-h] [--area {coding,core}] [--list | --validate | --add-missing |
--add-new-coding | --sync-methods | --imports | --worker] [--from FILE]
[id]
Read the effective coding/core rules after the project's checkboxes and replacements are applied.
positional arguments:
id print exactly this group/rule in full
options:
-h, --help show this help message and exit
--area {coding,core} which rule area to read (default: coding)
--list human overview, one line per set/group
--validate schema + cross-checks, exit 1 on findings
--add-missing enter the rules and rule files of the template that docs/ai/rules.md does
not know (--area core is implied); exit 1 if something could not be
entered
--add-new-coding list in docs/project/coding_rules.md the rule sets and groups of
.act/coding/ it does not know yet (--area coding is implied)
--sync-methods bring the methods section of docs/project/coding_rules.md in line with the
`methods` row of docs/ai/config.md (--area coding is implied); exit 1 if
something could not be entered
--imports files Claude Code loads through @-imports with their size in characters
and totals, exit 1 on any it cannot follow
--worker the parts a worker is handed instead of CLAUDE.md: size and sources per
part, total
--from FILE start file for --imports, root-relative (default: CLAUDE.md)

Call: direct

usage: script_docs.py [-h] [--check]
Generate .act/scripts/README.md from every script's own --help output.
options:
-h, --help show this help message and exit
--check compare disk against the generated text, write nothing, exit 1 on any difference

Call: direct (used by skill act-release with security-check: full)

usage: security_deep.py [-h] [--since REF | --all] [--json] [--force]
Deep security scan (Art C) over the files changed since a ref, via Semgrep.
options:
-h, --help show this help message and exit
--since REF scan files changed since REF instead of the latest tag
--all scan the whole tree instead of only changed files
--json print findings as a JSON array instead of text
--force run even when docs/ai/config.md's security-check is not 'full'

Call: direct (also run before a commit that touches a lock file and daily at session start, with security-check: deps/full)

usage: security_scan.py [-h] [--deps] [--json]
Security check Art B -- dependency-vulnerability scan via osv-scanner or an ecosystem's own audit
tool (npm audit / pnpm audit / composer audit / pip-audit). Read-only except for the chosen tool's
own network lookup; never installs or builds anything.
options:
-h, --help show this help message and exit
--deps run the scan and print a summary
--json with --deps: print the result as JSON instead of text

Call: skill act-seo

usage: seo_check.py [-h] [--root ROOT] [--json] [--dup-threshold DUP_THRESHOLD]
[--dup-min-words DUP_MIN_WORDS]
Code-only SEO checks: title, description, headings, lang, canonical, Open Graph, image alt,
internal links, robots.txt and sitemap.
options:
-h, --help show this help message and exit
--root ROOT project root (default: current directory)
--json print the report as JSON
--dup-threshold DUP_THRESHOLD
share of identical text from which two pages count as duplicates, 0 < x <=
1 (default 0.9)
--dup-min-words DUP_MIN_WORDS
pages with fewer words are not compared (default 25)

Call: skill act-seo

usage: seo_crawl.py [-h] [--max-pages MAX_PAGES] [--max-depth MAX_DEPTH] [--timeout TIMEOUT]
[--max-bytes MAX_BYTES] [--no-external] [--external-delay EXTERNAL_DELAY]
[--max-external MAX_EXTERNAL] [--max-time MAX_TIME] [--slow-ttfb SLOW_TTFB]
[--dup-threshold DUP_THRESHOLD] [--dup-min-words DUP_MIN_WORDS] [--public]
[--delay DELAY] [--max-assets MAX_ASSETS] [--json]
base_url
Crawl a running site from one base URL (same origin only): status codes, redirects, TTFB, broken
internal and external links, duplicate pages, then the seo_check.py page checks on the rendered
HTML. Starts no server and writes no file. Outgoing traffic: GET requests to the site itself and,
unless --no-external, one HEAD request per external link (throttled per host; GET only after a
405, headers only). No cookie, no page content leaves the machine.
positional arguments:
base_url http(s) URL of the running site, e.g. http://127.0.0.1:3100/
options:
-h, --help show this help message and exit
--max-pages MAX_PAGES
internal URLs fetched at most (default 500, with --public 100)
--max-depth MAX_DEPTH
link hops from the start page (default 10)
--timeout TIMEOUT seconds per request (default 10.0)
--max-bytes MAX_BYTES
largest response read; a larger page is not parsed (default 5000000)
--no-external do not check external links (nothing leaves the site)
--external-delay EXTERNAL_DELAY
seconds between two requests to one external host (default 1.0)
--max-external MAX_EXTERNAL
external links checked at most (default 200)
--max-time MAX_TIME seconds for the whole crawl, external links included (default 1800.0)
--slow-ttfb SLOW_TTFB
TTFB in ms from which a page is reported (default 600.0)
--dup-threshold DUP_THRESHOLD
share of identical text for the near-copy check of seo_check (default 0.9)
--dup-min-words DUP_MIN_WORDS
pages with fewer words are not compared (default 25)
--public the site is on the internet: read-only and throttled (--delay, default 1 s
between requests, 100 pages unless --max-pages), plus HTTP header checks
(HSTS, CSP, X-Content-Type-Options, Referrer-Policy), compression and
caching of HTML and assets, the http -> https redirect, and a real TTFB.
Extra requests: one GET for http:// and one per sampled asset, headers
only
--delay DELAY seconds between two requests to the site itself (default 0, with --public
1)
--max-assets MAX_ASSETS
scripts and stylesheets sampled for compression and caching with --public
(default 10)
--json machine-readable output

Call: skill act-seo

usage: seo_lighthouse.py [-h] [--runs RUNS] [--form-factor {mobile,desktop}] [--workdir WORKDIR]
[--root ROOT] [--keep-raw] [--timeout TIMEOUT]
[--from-json FILE [FILE ...]] [--pagespeed] [--json]
[urls ...]
Lighthouse median over several runs per URL, spread per value, axe findings, report by severity.
Takes URLs of an already running site; starts no server and fixes nothing.
positional arguments:
urls http(s) URLs to measure
options:
-h, --help show this help message and exit
--runs RUNS runs per URL (default 3, with --pagespeed 1)
--form-factor {mobile,desktop}
Lighthouse emulation (default mobile)
--workdir WORKDIR folder for Chrome profile, raw data and temp files (default <root>/.act-
local/tmp/<YYYYMMDD>-seo-lighthouse)
--root ROOT project root for the default workdir (default: current directory)
--keep-raw keep the raw Lighthouse JSON under <workdir>/raw
--timeout TIMEOUT seconds per run (default 240)
--from-json FILE [FILE ...]
evaluate existing Lighthouse JSON files instead of measuring
--pagespeed measure a PUBLIC url with Google PageSpeed Insights instead of local
Chrome: THE URL IS SENT TO GOOGLE, whose servers fetch the page. Same
evaluation, plus field data (CrUX) when Google has it. The API key is read
from the environment variable PAGESPEED_API_KEY only, never from an
argument; Google's quota without a key is 0 per day, so a key is needed.
No Node or Chrome needed
--json machine-readable output

Call: skill act-export-settings

usage: settings_export.py [-h] [--all] [--with-scripts] [--with-checklists] [--with-agents]
[--with-skills] [--with-topics] [--with-formats] [--with-files]
[--strict] [--out PATH] [--profile]
Write the project's rule deviations (and, with a switch, local scripts/checklists) to a portable
settings file.
options:
-h, --help show this help message and exit
--all include unchanged ('=') rules/groups too
--with-scripts include docs/ai/local/scripts/ (forces --with-files)
--with-checklists include docs/ai/local/checklists/ (forces --with-files)
--with-agents include docs/ai/local/agents/, the project's own roles (forces --with-files)
--with-skills include docs/ai/local/skills/, the project's own skills (forces --with-files)
--with-topics include docs/ai/local/rules/topics/, own topic rules and overrides of
template topics (forces --with-files)
--with-formats include the project's format files, docs/project/formats/ (forces --with-
files)
--with-files write a .zip even without --with-scripts/--with-checklists/--with-
agents/--with-skills/--with-topics/--with-formats
--strict abort on any finding instead of substituting a placeholder
--out PATH output path (default: .act-local/export/act-settings-<date>.md|.zip)
--profile write to the Owner's profile (platform config dir) instead of --out/the
default location; backs up an existing profile file first

Call: skill act-load-settings

usage: settings_load.py [-h] {plan,apply} ...
Import a settings file (act-export-settings' output) into this project.
positional arguments:
{plan,apply}
plan check only, write nothing to the project
apply check, then write what is mechanically clear or judged
options:
-h, --help show this help message and exit
usage: settings_load.py plan [-h] [--candidates-out PATH] [--json] [files ...]
positional arguments:
files settings.md or settings.zip file(s), in order; default: every .md/.zip in
.act-local/import/
options:
-h, --help show this help message and exit
--candidates-out PATH
write the candidate-pair list here as JSON
--json machine-readable output
usage: settings_load.py apply [-h] [--judgments PATH] [--yes] [--non-interactive]
[--resolve FILE=ACTION]
[files ...]
positional arguments:
files settings.md or settings.zip file(s), in order; default: every .md/.zip in
.act-local/import/ (moved to .act-local/import/done/ once processed)
options:
-h, --help show this help message and exit
--judgments PATH JSON verdicts for plan --candidates-out's pairs
--yes write bundled files without asking first
--non-interactive never prompt (same effect as omitting --yes when stdin is not a terminal)
--resolve FILE=ACTION
decide what happens to a not-fully-processed .act-local/import/ file
(repeatable); ACTION is keep (default, offered again), partial (close it,
keep what applied, discard the rest), ignore (move to import/ignored/,
never offered again), or delete (remove the file) — only with the default
no-argument .act-local/import/ discovery

Call: direct (used by skill act and by dispatch.py’s /act fast path)

usage: skills.py [-h] [--check] [name]
List the project's skills (name + description), or print one in full.
positional arguments:
name print this skill's SKILL.md in full; the act- prefix may be left out
options:
-h, --help show this help message and exit
--check lint every skill's description and body; exit 1 if there is an error

Call: direct (session start and update.py call it; run by hand to create the copies at once)

usage: unit_copies.py [-h]
Create the missing tool copies of the project's own skills (docs/ai/local/skills/) and roles
(docs/ai/local/agents/); idempotent, prints what happened.
options:
-h, --help show this help message and exit

Call: skill act-update (--plan and --versions alone are direct (skill act-version); names each active package’s requires-template and a newer zip, fetches no package and runs no package code)

usage: update.py [-h] [--source SOURCE] [--ref REF] [--channel {release,latest}] [--versions]
[--all] [--short] [--allow-downgrade] [--on-local-changes {rescue,discard,abort}]
[--yes] [--plan] [--no-commit] [--non-interactive] [--catch-up]
Pull a newer state of the template into this project.
options:
-h, --help show this help message and exit
--source SOURCE local directory or git URL/repo to update from (default: the source
recorded in .act-lock.json; a 'template' remote only when the lock names
none)
--ref REF tag or commit to update to (goes before the channel; default: what the
channel picks)
--channel {release,latest}
update channel for this run, overriding `update-channel` in
docs/ai/config.md (default: release): 'release' = the newest stable tag
vX.Y.Z, 'latest' = the tip of the source's default branch
--versions list the installed version, the channel, the source's releases and default
branch tip, and what an update would take (git ls-remote only, no clone;
writes only the local update note under .act-local/)
--all with --versions: list every release, not the five newest
--short with --versions: three lines only -- installed version and update date,
newest state of the source in the channel with its date, whether an update
is available (what /act-version shows); with --all the full list wins
--allow-downgrade apply the fetched state even when it is older than the installed template
commit, or when the installed commit is not in the source's history
(default: refuse, --plan only warns)
--on-local-changes {rescue,discard,abort}
skip the step-2 prompt
--yes skip the interactive consent prompt (step 4)
--plan show steps 1-3, describe 5-10; changes nothing in the project, only the
local update-check files under .act-local/ may be refreshed
--no-commit do everything except the final commit
--non-interactive never prompt
--catch-up skip the fetch/diff/replace; finish steps 6-10 from the .act/ already on
disk (e.g. after a plain 'git pull' of the template outside update.py) --
refuses unless that tree still matches its own MANIFEST.json

Call: direct

usage: usage.py [-h] [--show | --outcome ROLE TIER OUTCOME | --unused KEY | --reset |
--estimates | --backfill] [--reason WORD] [--transcripts-dir DIR]
Local usage counter: worker starts by role/tier/model, skill/command/script/checklist calls,
worker outcomes.
options:
-h, --help show this help message and exit
--show readable overview (default)
--outcome ROLE TIER OUTCOME
record accepted|reworked|escalated for one role/tier
--unused KEY exit 0 if KEY was never recorded, 1 if it was (see is_unused())
--reset delete every recorded count
--estimates measured runs per role/tier: median and 80th percentile of minutes and
tokens (fresh/cache), run count, last measurement
--backfill read this project's existing worker transcripts once (a second run adds
nothing twice)
--reason WORD with --outcome reworked|escalated: why - assignment, edge-case, worker or
decision; assignment, edge-case and decision (the orchestrator's) stay out
of the tier proposal window
--transcripts-dir DIR
with --backfill: the transcript folder to read instead of Claude Code's
folder for this project