Maintain public EAOS documentation

Maintain public EAOS documentation

Prerequisites

Read the ALNEAS documentation policy and the document-authoring skill before editing. Build public declarations before generating API reference. Keep local operator evidence, credentials, private business guides and migration scratchpads outside the public manifest.

Step-by-Step Implementation

1. Edit the owning package’s English source under docs/ or its README. Classify each page as tutorial, how-to, reference or explanation. Landing pages use Elevator Pitch → Why & Value → Key Highlights → Quickstart → Next Steps.
2. Add title, description, sidebar order, archetype, project and tags frontmatter. Examples include complete imports and use only synthetic values. Keep local paths and real host/tenant settings out of public content.
3. Keep this project’s canonical public guides in English. Japanese portal translations are owned by github-docs under src/data/translations/pages/eaos-workspace/ and rendered into its src/content/docs/ja/eaos-workspace/ routes. Do not register portal translations as upstream sourceJa entries. Preserve code snippets and identifiers; missing portal translations fall back to English. Existing Japanese runtime-help assets remain separate from portal translation ownership.
4. Regenerate API cards from built declarations and source export names. Do not edit generated reference cards. TypeScript/JSDoc and the package export map own these contracts.
5. In each developer feature guide, add a Public import section with a package installation command, exact exported subpath and a self-contained example. State the selected runtime, peers, stylesheet and provider requirements. Keep implementation instructions in developer guides; link to them from end-user operation guides. Check named exports against built declarations as well as the package export map.
6. Add only reviewed public pages to docs.manifest.json. Use relative source links; ingestion maps them to registered page routes. New files and private folders are excluded by default.

Run from the workspace root:

bun run docs:prepare
bun run docs:verify
bun run docs:sync
bun run docs:build

The public manifest is public/eaos/docs.manifest.json. docs:sync stages only its public entries, records content hashes and upstream revision provenance, and never copies an entire documentation directory. The local preview is disposable; github-docs remains the shared portal for ecosystem navigation and governance.

Verification

docs:verify checks manifest paths, visibility, frontmatter, archetypes, English root content, public links, API cards, landing sections and secret/path exclusions. docs:sync refuses invalid sources before replacing its generated content. Build verifies generated links for both locales and repository base paths.

The portal’s read-only preflight can also run from the owning checkout:

bun ../../../github-docs/scripts/ingest.ts --verify --project=docs.manifest.json

Run that command in public/eaos. It performs no publication. Shared ingestion remains one-way; fix errors here instead of editing generated portal pages.

Troubleshooting / Common Pitfalls

• Missing manifests or unlisted links fail verification; explicitly register the intended public page.
• Never mark a private guide public just to resolve a link. Write a separately reviewed public explanation when needed.
• The JSDoc audit checks source summaries, parameter/return/type-parameter tags and usage references through declared package exports, including public methods and inline parameter/result properties. Cross-package re-exports point to their owning reference. The audit does not prove semantic correctness, error completeness or the validity of an example. Review implementations and tests, and type-check source examples in an isolated installed-artifact consumer with bun run docs:examples --consumer=<consumer-directory>. This command performs type checking without executing examples or using sibling-source aliases.
• API drift requires rebuilding declarations and regenerating cards, not hand-editing reference files.
• Keep action skills distinct from human references and keep llms.txt as navigation only.
• Preserve private completion receipts and deployed state separately from documentation success.