harn docs

harn docs
harn docs meta <path> [key] [--json]
harn docs frontmatter-migrate [--repo <name>] [--yes]
harn docs lint [--fast] [--repo <name>]
harn docs sweep [--repo <name>]
harn docs index [--dry-run] [--repo <name>]

The docs command group gives an embedding host one documentation maintenance surface. The host supplies its repository root, submodule list, exclusions, and any project-specific root allowlist through HarneryProgramContext.

Read frontmatter

docs meta reads a markdown file’s leading YAML block:

harn docs meta docs/plans/cache-redesign.md
# {"status":"in-progress","date":"2026-07-13","tags":["cache"]}

harn docs meta docs/plans/cache-redesign.md status
# in-progress

Relative paths resolve from the configured repository root. Absolute paths also work. The command exits nonzero when the file, frontmatter block, or requested top-level key is missing. A requested scalar prints plainly in an interactive terminal; piped output and --json use JSON.

Migrate lifecycle files

docs frontmatter-migrate converts recognized opening bold fields in docs/plans, docs/issues, and docs/handoffs into leading YAML frontmatter. It scans archives too. The default is a dry-run:

harn docs frontmatter-migrate --repo .
harn docs frontmatter-migrate --repo . --yes

The converter leaves narrative bold labels and body examples alone, merges into existing frontmatter that has no status, and skips files that already carry YAML status:. Unsupported status values and conflicting fields are errors; the command exits nonzero without guessing or writing any file. --yes is the only mode that writes, and the apply is all-or-nothing for the selected repository set.

Other subcommands

• docs lint checks directory layout, filenames, and lifecycle status. --fast skips content checks for pre-commit use.
• docs sweep reports stalled plans, cold issues and handoffs, stale topic docs, and unverified runbooks.
• docs index rebuilds marker-delimited audit and issue index tables.
• Bare docs reports markdown freshness from Git history.

Lint, sweep, and index read lifecycle status: only from leading YAML frontmatter. Legacy **Status:** lines are accepted only as input to the explicit docs frontmatter-migrate conversion command.