Commands

Locating the repository

Every command except init locates archdoc.json by walking up from the working directory and fails if none is found. -C <dir>, --chdir <dir>, is a persistent flag that runs the command as if it had been started in that directory, applied before anything reads the working directory. Every command operates relative to root.

Exit codes: 0 on success, 1 on a usage or validation error, 2 when lint, a check or a link scan finds errors. Nothing under internal/ calls os.Exit; the status travels as an error type to the command layer.

Interaction

With a terminal on stdin, a command prompts for every value it was not given: required arguments, and optional flags whose value is written to a file. Flags that select a mode of operation (--json, --check, --suggest, --apply, --strict-warnings, --no-interaction, --yes) are never prompted for. A flag supplied on the command line is not prompted for. The prompts for one invocation form a single form, required arguments first, each optional pre-filled with its default. Without a terminal, or with --no-interaction, defaults apply and a missing required argument is a usage error. --no-interaction is a persistent flag. A terminal is detected with term.IsTerminal.

Output

Plain text on stdout. Findings take the form <path>:<line>: <severity>: <message> where a line is known and <path>: <severity>: <message> otherwise, with <path> relative to root. --json on lint, index --check, glossary --check and link emits the same findings as a bare JSON array of objects with path, line, severity, message and rule; line is omitted where unknown, and rule is the rule code, or index and glossary for the generated-file checks. Progress notices go to stderr.

archdoc init

Scaffolds a repository in the current directory.

Writes archdoc.json at the git repository root, or in the current directory where there is no repository, setting root to the path from there down to the current directory joined with any --root given, so the documents land where the command was run. Writes README.md, PROCESS.md, INDEX.md, GLOSSARY.md, rfc/.gitkeep, adr/.gitkeep, ref/.gitkeep, term/.gitkeep, LICENSE if requested, and AGENTS.md with agents/ if requested, under root; and .github/workflows/archdoc-lint.yml at the git repository root, or in the current directory where there is no repository. Every file is planned before any is written, collisions are tested with Lstat, and files are created with O_EXCL. Prints every path written. Refuses if archdoc.json already exists or any other planned file is in the way. Validates the configuration through the same path that loads one, after prompting and before writing. Does not initialise git and does not commit.

The generated workflow runs on push and pull request. It checks out the full history, uses archdochq/lint pinned to the version that ran init, which installs archdoc and reports each finding as an annotation on the line of the document that caused it, then runs archdoc index --check and archdoc glossary --check. Its working-directory is the path from the git repository root to the directory holding archdoc.json, as git reports it, and is omitted when the two are the same, which is every repository init scaffolds.

archdoc new <rfc|adr|ref> <title>

archdoc renumber <id|path> [new-id]

Changes a numbered document's identifier. Rewrites the filename keeping the slug, the front matter id, the H1, and every reference to the old identifier: the depends, updates, obsoletes and includes lists of every other document and the documents list of every group, [[...]] links naming it, and links, as the tool reads them, whose destination, resolved against the directory of the document holding it, is the renamed file. The renamed document's own references to itself are rewritten with it. Nothing inside code or an HTML comment is a reference, and neither is a mention of the identifier or the file name in prose. A rewritten destination keeps the directory and fragment as written, and takes the new file name. A destination whose file name, as written, does not decode to the old one is refused, naming its line. A mailto: link or a URL is not followed. With no target, the next free number for the type is taken.

When another document still carries the old identifier, the front matter lists and [[...]] links naming it are left unchanged, and each line holding one is listed on stderr as path:line: text, marked where the document is frozen, with the renamed document's own lines under its new path. Link destinations pointing at the renamed file are rewritten in either case.

The selector is an identifier or a path. Given an identifier carried by more than one document, the command lists the candidates and refuses. Refuses a frozen document, and refuses when any frozen document holds a reference it would rewrite. Nothing is written unless everything can be. The index is not regenerated, and the command says so.

archdoc update [--check] [--yes]

Regenerates PROCESS.md, the workflow, and the guides under agents/ where that directory exists. Shows a unified diff of everything that would change and asks before writing. --check shows and exits 2 without writing. --yes applies without asking. With neither and no terminal, it refuses.

AGENTS.md, README.md, archdoc.json, LICENSE, INDEX.md, GLOSSARY.md and every document are not touched. agents/ is refreshed and never created; where it is absent the command says that archdoc agents installs it.

The workflow's version pin is raised to the version doing the update. It is kept as it is only when the running binary's version is not a published release. A repository scaffolded before the workflow used archdochq/lint names its pin ARCHDOC_VERSION, and that spelling is read too, so the pin survives the change.

archdoc agents

Writes the guides under agents/, replacing what is there, and creates AGENTS.md only when it is absent. Reports, for each path, whether it was written, updated or kept. Creates agents/ where the repository was scaffolded without it.