Docs Phase 5: Add CI artifact generation for generated API docs

[MichaelFisher1997]

Parent: #609

Summary

Add CI artifact generation for API docs after the docs extractor prototype is stable.

Requirements

• Target the repo's dev workflow, not main.
• Run through Nix: nix develop --command zig build docs.
• Watch relevant paths such as modules/**/*.zig, src/**/*.zig, tools/docgen.zig, build.zig, and workflow files.
• Upload generated docs as a GitHub Actions artifact for the docs site or downstream publishing workflow.

Acceptance Criteria

• Workflow runs successfully on documentation-relevant changes.
• Artifact contains only generated docs output, not build cache or unrelated files.
• Failure mode is clear when docs generation breaks.

[github-actions]

Classification: Feature Request

Analysis:

This issue requests CI artifact generation for API docs via zig build docs, but the prerequisite tools don't exist yet:

1. build.zig: No docs step exists. Current steps are run, benchmark, test, test-integration, test-robustness, run-robust.
2. tools/docgen.zig: Referenced in requirements but does not exist. The parent issue Docs: Build a maintainable generated API documentation pipeline #609 outlines that the extractor is still in a prototype phase (Phase 3) before CI is added (Phase 5).
3. Workflow path: The existing build.yml already targets dev and has path filtering that could be extended to include docs-relevant paths once the generator exists.

Relationship to #609:

Parent issue #609 explicitly sequences this work:

• Phase 1–3: Evaluate approaches, define public API scope, prototype extractor
• Phase 4: Establish doc-comment standards
• Phase 5: Add CI artifact generation ← this issue

Recommendation:

This issue is not actionable until earlier phases complete. The clearest next steps from #609 are:

1. Finalize tools/docgen.zig prototype targeting modules/*/src/root.zig exports
2. Add a docs step to build.zig that produces output to a known directory (e.g., docs/api/)
3. Extend build.yml with a new docs job that runs nix develop --command zig build docs and uploads the output artifact, using path filters on modules/**/*.zig, src/**/*.zig, build.zig, and workflow files

Scope: This is a single, well-scoped feature once the generator exists. No need to break into sub-issues.

opencode session  |  github run