Edit Cratis Docs

Editing a Cratis documentation page

Scope this skill to source files under Documentation/** in the product or contributing repo. Site-level pages in Documentation/web are owned by the Documentation repo.

Cratis docs content lives in each product's own repo under that repo's Documentation/ folder; the published site (in the Documentation repo at Documentation/web/) aggregates them. Editing the wrong copy wastes the work — the per-product folders under web/src/content/docs/ are generated and overwritten.

1. Find the source of truth

Map the page URL to its owning repo:

Example: /chronicle/concepts/event-source/ → Chronicle/Documentation/concepts/event-source.md. If unsure, grep -rl "<a distinctive sentence>" */Documentation Documentation/web/src/content/docs/*.md*.

Never edit Documentation/web/src/content/docs/{chronicle,arc,components,cli,fundamentals,contributing}/ — generated and git-ignored.

2. Edit the source

• Match the page's Diátaxis type (tutorial / how-to / explanation / reference) and the tour voice (teach, don't dump) — see the writing-cratis-docs rule (the tour-voice checklist + Starlight authoring tools). Don't mix types.
• Verify every framework API in a code example against real source before writing it — readers paste them verbatim. (See the writing-correct-examples rule; grep Studio *.cs/*.tsx and the product Source/ trees.)
• Link rules: product .md may use ./foo.md; links to a .mdx page must be extension-less (./foo); site-level .mdx uses clean root-relative URLs (/arc/...).

3. Sync, preview, verify

cd Documentation/web
npm run dev      # serves http://localhost:4321 (re-syncs the product repos)
npm run check    # the gate: build + lint + link-check

npm run check MUST end 0 error(s) and 0 broken links (≈187 advisory style warnings are expected). Fix anything it flags. Restart npm run dev after running the gate — the gate's re-sync degrades a live dev server.

For visual changes, screenshot the page in light and dark and read the result — use the qa-cratis-docs skill.

4. Commit

Commit the change in the product repo that owns the page (the site repo only changes if you touched a site-level page, the nav buckets in sync-content.mjs, or the build). Keep commits to one logical unit; don't push without explicit approval.

→ Site build and rendering internals live in the Documentation repo. To create a new page (not edit an existing one), use the add-cratis-docs-page skill.