Instruction file imported from aurintex/pai-os (.cursor/rules/docs-maintenance.mdc). Copyright stays with the author.

Documentation Maintenance Enforcer

Single Source of Truth: The maintenance procedures for the hybrid documentation system are defined in Documentation Maintenance (docs-maintenance.mdx).

Required Action

When modifying Rust code in the engine crate, Protocol Buffer files, or changing the documentation scripts:

1. Reference the Guide: Review docs-maintenance.mdx to understand the hybrid MDX/GitHub Pages approach.
2. Regenerate Local Docs: After API changes, run:
   • npm run gen:rustdoc (Rust MDX for Starlight)
   • npm run gen:proto (Protocol Buffer MDX)
3. Standard rustdoc HTML: Generated automatically via GitHub Actions (.github/workflows/rustdoc.yml) on push to main and deployed to GitHub Pages.
4. Validate Build: Run npm run build in the docs/ directory to ensure all paths and redirects are correctly generated.

Prevention of Regressions

• The /reference/rustdoc/ routes redirect to aurintex.github.io/pai-os/rustdoc/ (external GitHub Pages).
• When modifying .proto files, ensure proto-doc-gen.mjs can parse them correctly. The script supports both protoc-gen-doc (if available) and a built-in parser as fallback.

References:

• Maintenance Guide: docs-maintenance.mdx
• Rustdoc Workflow: rustdoc.yml
• Definition of Done: definition-of-done.mdc