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

[github-actions]

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 · ◷

Add this agentic workflows to your repo

To install this agentic workflow, run

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