Archestra Docs Writer

Archestra Docs Writer

This skill is the single source of truth for Archestra docs. Write and edit docs/pages/*.md by these rules.

Process

1. Open the docs page you are editing.
2. Use whatever browser-automation MCP you have available (e.g. claude-in-chrome) to navigate the platform (not the docs site) for the feature you are documenting. Walk related screens and primitives so the page reflects what the software actually does.
3. Document only the concepts, dependencies, and use cases. Skip anything the UI already shows on screen.

Tone of Voice

Every sentence states a fact: what a thing is, or what it does. If a sentence does neither, delete it.

Sentence rules:

1. One idea per sentence. If it contains "and… so…", split it.
2. If a sentence needs re-reading, rewrite it. Roughly 15 words is the ceiling.
3. Common words: "use", "go to", "write" — never "leverage", "reside", "comprise".
4. No metaphors, idioms, or rhetorical hooks.
5. Name a thing once, then rely on context. Never the same noun three times in one sentence.
6. Active voice, present tense.
7. Second person for user actions; impersonal for system behavior.
8. Friendly, not dry: speak to the reader ("You can add your own files too"), give one tiny concrete example in passing ("a report, for example" — one, never a list), and use a dash for rhythm where it helps. Facts stay the substance; friendliness is the delivery.
9. No emojis.

Content rules:

10. A benefit is stated as a plain consequence ("so you can review what the agent did") — at most one per section.
11. Cut any detail that doesn't change how someone uses the feature: size limits, edge cases, ownership caveats, internal tool names, permission mechanics. Link to a reference page instead.
12. Don't describe what the UI or the screenshot already shows.
13. Headers are Title Case and name the thing ("Scheduled Tasks"), never the benefit.
14. Each page has a use case section with concrete, fictional data (never real customer names). The scenario comes from the user — ask for it before writing.
15. No "Future Considerations" section and no generic "Best Practices" section.
16. Good docs are short docs. Keep every page as concise as the feature allows.

Calibration Examples

Reference page in this voice: docs/pages/platform-projects.md.

Screenshots

Every page should open with at least one screenshot; add more where they help. Capture them with your browser-automation MCP against the running platform at localhost:3000 (docs run at :3001 — never screenshot the docs site). Stage realistic data first: real project/team/file names from the page's use case scenario, forms pre-filled, scroll position checked so no important element is hidden. Save as docs/assets/automated_screenshots/{page-name}_{shot-name}.webp (convert PNG via the sharp package in platform/node_modules). Embed as ![alt](/docs/automated_screenshots/{page-name}_{shot-name}.webp).

Always Capture in Dark Mode

Every screenshot in the docs is dark. One light shot in a dark set reads as a different product, so the mode is not yours to pick — it is dark whatever the machine you are on happens to be showing.

The platform keeps the theme per browser in localStorage, so you must set it yourself before capturing:

localStorage.setItem("theme", "dark");

The key only takes effect on reload. Reload, confirm the rendered page is actually dark, then capture. Put the previous value back when you are done — it is the user's own preference, not yours.

Replacing an existing screenshot follows the same rule. A retake that comes back light is a regression even when the content is right.

Page Frontmatter

category and order place the page in the nav (categories derive from frontmatter; there is no registry). Check sibling pages for free order slots. Set lastUpdated to today. Create a worktree or branch from main, and open a PR when you are done.

Code References

Some pages are linked from the app through platform/shared/docs.ts (a DocsPage slug map). When you rename, delete, or add a page that code links to, update that file — a stale slug there is a dead "Learn more" link in the product. The .github/scripts/check-docs-links.py CI job fails if a docs.ts slug has no matching page, and if any internal doc link or asset embed doesn't resolve.