AUR-426 — `aurumcode docs`: run documentation generation from the command line

Documento histórico do board. Pode descrever componentes removidos; para uso atual, consulte o guia do produto.

aurumcode docs [--source <dir>] [--output <dir>] [--languages <list>] generates project documentation the same way cmd/regenerate-docs does, but through discoverable command-line flags instead of requiring the operator to already know the AURUMCODE_SOURCE_DIR / AURUMCODE_OUTPUT_DIR / AURUMCODE_LANGUAGES environment variables. aurumcode docs --help documents every flag and its default without the operator reading source or another spec first.

This subcommand reuses internal/pipeline.ExtractorPipeline and the internal/documentation/extractors/* language extractors — the exact engine cmd/regenerate-docs already wires — instead of reimplementing extraction. cmd/regenerate-docs itself is unchanged by this card and keeps working exactly as published; aurumcode docs is a second, flag-driven caller of the same reusable packages.

Command

aurumcode docs [--source <dir>] [--output <dir>] [--languages <list>]
aurumcode docs --help

Flag	Default	Meaning
`--source <dir>`	`.`	Directory to scan for documentable source code.
`--output <dir>`	`.aurumcode`	Directory to write generated markdown and site files (`index.md`, `_config.yml`).
`--languages <list>`	(empty = all)	Comma-separated language filter, exact lowercase names, e.g. `go,python`. An unrecognized or wrongly-cased name (`Go`, `GO`) matches nothing — it is not an error by itself, but it can drive the run to the zero-page failure below with no further diagnosis of why nothing matched.

These are the three flags the Outcome names ("origem, destino e linguagens"). aurumcode docs --help is the authoritative, always-current listing — this table is pinned to it and to the flag set actually registered in cmd/aurumcode/docs.go (tests/unit/AUR-426.go checks all three sources agree; see "MUT-001" below).

What is intentionally out of scope

Welcome-page LLM generation and Jekyll-build validation, which cmd/regenerate-docs additionally supports through its own AURUMCODE_-prefixed knobs, are not wired into this subcommand. Nothing aurumcode docs --help documents depends on a model call, so the sealed, network-denied acceptance profile always exercises the real, deterministic code path end to end — never a fixture substitute for the declared command itself.
Rust and C# extractors are not registered here, for the same reason cmd/regenerate-docs itself gates them behind AURUMCODE_ALLOW_REPO_CODE_EXECUTION: their toolchains execute code that lives in the documented repository (cmd/regenerate-docs/repo_code_execution.go). Wiring that second opt-in path is outside what this card's --help promises. Go, JavaScript, TypeScript, Python, C++, Bash and PowerShell are registered, matching cmd/regenerate-docs's own default (non-opt-in) set.
--incremental, --docs-dir, --base-url and the other cmd/regenerate-docs knobs are not exposed as flags. Adding one is a future card's job, not a silent extension of this one (see .board/AGENT_PLAYBOOK.md on the briefing not amplifying the card).

Exit codes

Code	Meaning
`0`	`--help` was requested: usage printed to stdout.
`0`	Documentation was generated: at least one page exists on disk after the run (fully, or partially with at least one page produced and a partial-run note on stderr).
`1`	`--source` does not exist or is not a directory.
`1`	The pipeline failed outright (no page could be produced for any structural reason the pipeline itself reports).
`1`	The run produced zero documentation pages — a filter that matches nothing, or a source tree with nothing documentable — `aurumcode docs: no documentation page was generated` on stderr. A green exit with zero pages does not exist for this command.
`2`	Usage error: an unknown flag or a value a flag cannot parse. Go's `flag` package usage text goes to stderr.

`--help`'s own convention

aurumcode docs --help (or -h) prints usage to stdout and exits 0: it is a request that was fulfilled, not a failure. This is a deliberate, declared convention for docs; it is not retroactively applied to aurumcode review --help, whose pre-existing behavior (usage on stderr, exit 2, via the generic flag.Parse error path documented in AUR-430) is unchanged — changing a previously published command is outside this card's paths and its Non-goals.

Example (no secrets)

$ aurumcode docs --help
usage: aurumcode docs [flags]

Generate project documentation from source code. Reuses the same
internal/pipeline and internal/documentation/extractors packages
cmd/regenerate-docs uses, driven by flags instead of environment
variables.

Flags:
  -languages string
        comma-separated language filter, exact lowercase names, e.g. go,python (default: all supported languages; an unrecognized or wrongly-cased name matches nothing)
  -output string
        directory to write generated markdown and site files (index.md, _config.yml) (default ".aurumcode")
  -source string
        directory to scan for documentable source code (default ".")
$ echo $?
0

Running it against this repository's own AUR-424 fixture project (a tiny Go package with real exported symbols and doc comments):

$ aurumcode docs --source ./tests/fixtures/docs/goproject --output /tmp/site
Generated 1 documentation page(s) in /tmp/site:
  - /tmp/site/go/root.md
$ echo $?
0
$ head -c 120 /tmp/site/go/root.md
---
title: Root - Go
layout: default
permalink: /go/root/
---

# Package goproject
...

/tmp/site/go/root.md documents the real Greeting type, NewGreeting, String, Add and Max — the same output AURUMCODE_SOURCE_DIR=... AURUMCODE_OUTPUT_DIR=... go run ./cmd/regenerate-docs produces for the same fixture (docs/specs/AUR-424.md), because both callers drive the same internal/pipeline engine.

No environment variable carrying a secret is read by this command path. A path derived from --source/--output (or from an extractor's underlying tool error) is passed through the AUR-009/AUR-432 redaction filter before it reaches stdout or stderr, exactly like aurumcode review's notices; a canary value present in a printed path is replaced by the filter's stable marker rather than echoed.

Failure diagnosis

aurumcode docs: source directory <path>: stat <path>: no such file or directory, exit 1 — --source does not exist. Check the path (relative paths resolve against the current working directory).
aurumcode docs: source directory <path> is not a directory, exit 1 — --source names a file, not a directory.
aurumcode docs: no documentation page was generated, exit 1 — the run completed without a structural error but left zero markdown pages under --output. Causes, most common first:
--languages names a language with the wrong case or an unsupported spelling (Go, GO, golang). Matching against the registered extractors is an exact, case-sensitive string compare inherited from internal/pipeline (the same behavior cmd/regenerate-docs's AURUMCODE_LANGUAGES already has); a name that does not match exactly excludes silently, with no separate "unknown language" error. Use the lowercase names in the flag table above.
--languages correctly names only languages absent from --source.
The tree has nothing any registered extractor recognizes (e.g. a Rust-only or C#-only project — see "What is intentionally out of scope" above).
aurumcode docs: partial run: N extraction error(s), M language(s) skipped on stderr, exit 0 — at least one page was still produced; the run is not fatal but did not fully succeed. This mirrors cmd/regenerate-docs's own result=partial case without reproducing its full site-scaffold/exclude-list diagnostics, which remain specific to that binary's Jekyll-publishing concerns.
flag provided but not defined: -x followed by usage on stderr, exit 2 — an unrecognized flag. Run aurumcode docs --help.

MUT-001 note

The skeptical mutation removes a flag documented in --help. Because aurumcode docs's usage text is generated by Go's flag.FlagSet from the actually-registered flags (fs.PrintDefaults() in cmd/aurumcode/docs.go's fs.Usage), deleting an fs.String(...) registration removes that flag from the real --help output by construction — there is no separately hand-authored help string that could drift from the registered set on its own. tests/unit/AUR-426.go closes the other side of that loop: it parses the flag names out of the built binary's actual --help output and asserts that set equals both the flag table above and (transitively, since this document is read by the acceptance script) the registered set — so a mutant that deletes a flag from the code is caught by the doc/help mismatch, and a mutant that edits only this document without touching the code is caught the same way.

Compatibility

aurumcode review in every form AUR-430/431/435/436 published is byte-for-byte unchanged. cmd/aurumcode/main.go's only edits are routing docs to a new subcommand and widening the zero-argument usage line from usage: aurumcode <review> [flags] to usage: aurumcode <review|docs> [flags]. No published spec or test asserts that any process actually invoked with zero arguments produces that exact text — the only place the string appeared before this card was one sample entry in cmd/aurumcode/redaction_wiring_test.go's TestStderrLinesSurviveTheRedactionWriter, which pins filter-identity for a list of representative lines, not this command's zero-argument behavior — and that entry is updated alongside the code in this same card.
cmd/regenerate-docs is untouched by this card (outside paths) and keeps generating documentation exactly as before, environment variables and all.

AUR-426 — aurumcode docs: run documentation generation from the command line