AGENTS.md@docs git:20261007.d88f6abA

Immutable. This exact content never changes and is served at /api/v1/blob/5171f17c7a2a88d2.

# docs

## Context

gritframework.dev: the marketing site, the documentation, the changelog, the
blog, the courses and the tier tutorials. A Next.js App Router app, and the only
app in this repository that is a product rather than a template.

It is also the public record. The changelog here is what people read to find out
what a release did, and the homepage is what they read to find out what Grit is.

## Source of truth

- **The version**: `config/site.ts`, `GRIT_VERSION`. One of three spots that
  must agree (see `cmd/grit/AGENTS.md`). Nothing else in the docs hardcodes a
  version number: read it from here.
- **The changelog**: `app/docs/changelog/page.tsx`, newest first. Rolled up by
  `scripts/changelog-rollup.py`.
- **The tier tutorials**: generated by `scripts/tier-tutorials.py`.
- **`examples/commerce/TUTORIAL.md`**: generated by
  `scripts/tutorial-build.py`. **Never hand-edit its code blocks.**
- **The shared visual language**: `styles/` and the grid, crosshair, card and
  glow utilities. There is deliberately **no** shared docs layout component;
  pages compose the utilities.

## Boundary rules

1. **A shipped feature lands in three places, not one**: the changelog, the
   docs page for it, and the **homepage**. A feature that only reaches the
   changelog is a feature nobody discovers.

2. **No em dashes.** Anywhere: prose, headings, UI copy, code comments, commit
   messages. Use a colon, a comma or a full stop. This is the house anti-slop
   standard and it is not negotiable.

3. **Write the command the reader actually types.** Every tutorial and every
   quickstart includes `pnpm install`. Leaving it out was a real bug reported by
   a real reader, in every tier doc at once.

4. **Documented flags and commands must exist.** Check against `cmd/grit` before
   writing one down. A doc describing a flag that was renamed is worse than no
   doc, because the reader trusts it.

5. **The changelog entry says what changed for the reader**, not what changed in
   the code. "Bulk Create opens a grid on every admin list page", not "refactored
   the bulk writer".

6. **Dates are absolute.** "2026-10-07", never "last week".

## Validation workflow

```bash
cd docs && npx next build
```

`npx next build`, not `pnpm build`: the docs site has its own
`pnpm-workspace.yaml` and the root task graph does not reach it.

Then:

1. `npx next dev` and open the pages you changed, in **light and dark**.
2. Check the page at phone width. The grid utilities need a side gutter and no
   horizontal scroll.
3. If you touched the changelog: re-run `python scripts/changelog-rollup.py` and
   build again.
4. If you touched a tutorial that is generated: re-run its script and build.
   Editing the generated file directly means your change is lost on the next run.
5. Search your diff for an em dash before you commit.