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.

Markdown Formatting

Keep each prose paragraph on a single source line, matching the existing docs. Do not insert line breaks after every sentence or hard-wrap paragraphs at a fixed column width. Short-sentence guidance concerns wording, not line breaks. Use blank lines between paragraphs; preserve Markdown structure for headings, lists, tables, and code blocks.

Calibration Examples

Rejected	Accepted
A chat answers a question and scrolls away; a project is where agent work accumulates.	A project is a shared workspace for chats, files, instructions, and scheduled tasks.
Chats started in a project belong to it for their lifetime, and files the agent saves are owned by the project rather than the individual author.	Files saved in a project are available to everyone in it.
Files the agent saves in a project chat go to the project, and every chat in the project can read them.	Files the agent saves go to the project.
…so anyone with access can use them.	…available to everyone in it.
## Reports that write themselves: schedules	## Scheduled Tasks
Text and Markdown files are editable right in the panel, so a small fix doesn't need a re-upload.	Text and Markdown files are editable right in the panel.

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.