docs: fix API accuracy across user-guide, configuration, and library-api

Start with docs/user-guide.md, docs/configuration.md, docs/library-api.md, and docs/README.md, checking each claim against the Rust sources listed in the issue, especially the application result types, validation rules, frontmatter, CLI handlers, and wiki renderer. Done means the examples, field types, validation behavior, exit codes, generated filenames, and update date match those sources; review the referenced workflow bundle because the changes are already prepared there.

[!CAUTION]
Protected files were modified in this change.
This pull request is in request_review mode and requires explicit human scrutiny before merge.

Protected files: README.md

What

Corrects multiple documentation inaccuracies found by diffing the published docs against the actual Rust source code.

Changes

docs/user-guide.md

• Library usage example — with_theme("dark") → with_theme(Theme::Dark) (with correct use import); with_theme() accepts a Theme enum, not a string
• Validation required fields — removed status; it has #[serde(default)] and defaults to Proposed when absent or unrecognized — it is never an error
• Validation recommended fields — removed author and tags; RecommendedFieldsRule only checks description, created, and category
• Exit codes — removed non-existent exit code 2; handle_validate returns 0 (pass) or 1 (fail), never 2
• Wiki generated pages — replaced Home.md / ADR-XXXX.md / Status-Index.md / Category-Index.md / Timeline.md with the real output: ADR-Index.md, ADR-By-Status.md, ADR-By-Category.md, ADR-Timeline.md, ADR-Statistics.md, plus copied ADR source files

docs/configuration.md

• Validation rules — same required/recommended field corrections as above
• Wiki output structure — updated code block to match actual file names
• Exit codes — removed non-existent code 2

docs/library-api.md

• GenerateResult — added missing parse_errors: Vec<(PathBuf, Error)> field
• ValidateResult struct — replaced fabricated { report, adr_count } with the real struct: { reports, parse_errors, total_errors, total_warnings, passed }
• Validate example — replaced result.has_errors() / result.issues() / issue.file with result.passed / result.error_issues() / path.display() + issue.message
• StatsResult — renamed formatted_output → output; added parse_errors field; fixed inline example to match
• Wiki example — result.page_count → result.generated_files.len()
• Frontmatter struct — string fields (description, category, author, project) are plain String defaulting to "", not Option<String>; created/updated are Option<time::Date> not Option<String>; added doc_type and updated

docs/README.md

• Updated "Last Updated" date to 2026-06-12

Verification

All changes verified against source code in:

• src/application/generate.rs — GenerateResult, GenerateOptions::with_theme
• src/application/validate.rs — ValidateResult, ValidateOptions
• src/application/stats.rs — StatsResult
• src/application/wiki.rs — WikiResult
• src/domain/validation.rs — RequiredFieldsRule, RecommendedFieldsRule
• src/domain/frontmatter.rs — Frontmatter struct
• src/cli/handlers.rs — exit code behaviour
• src/infrastructure/renderer/wiki.rs — generated file names

Generated by Update Docs · 1.3K AIC · ⌖ 43.9 AIC · ⊞ 37.2K · ◷

gh aw add githubnext/agentics/workflows/update-docs.md@adea00ee5830135f24022f1000d706c7f5fa24c4

[!NOTE]
This was originally intended as a pull request, but the git push operation failed.

Workflow Run: View run details and download bundle artifact

The bundle file is available in the agent artifact in the workflow run linked above.

To create a pull request with the changes:

# Download the artifact from the workflow run
gh run download 27436737857 -n agent -D /tmp/agent-27436737857

# Fetch the bundle into a temporary ref, then update the local branch
git fetch /tmp/agent-27436737857/aw-docs-fix-api-accuracy-2026-06-12.bundle refs/heads/docs/fix-api-accuracy-2026-06-12:refs/bundles/create-pr-docs-fix-api-accuracy-2026-06-12-c28bc33053a9958f-d6b9c6c6
git update-ref refs/heads/docs/fix-api-accuracy-2026-06-12-c28bc33053a9958f refs/bundles/create-pr-docs-fix-api-accuracy-2026-06-12-c28bc33053a9958f-d6b9c6c6
git checkout docs/fix-api-accuracy-2026-06-12-c28bc33053a9958f
# Ensure the working tree matches the updated branch
git reset --hard
# Remove the temporary bundle ref
git update-ref -d refs/bundles/create-pr-docs-fix-api-accuracy-2026-06-12-c28bc33053a9958f-d6b9c6c6

# Push the branch to origin
git push origin docs/fix-api-accuracy-2026-06-12-c28bc33053a9958f

# Create the pull request
gh pr create --title 'docs: fix API accuracy across user-guide, configuration, and library-api' --base main --head docs/fix-api-accuracy-2026-06-12-c28bc33053a9958f --repo zircote/adrscope