Docs maintenance

Where docs content lives

This site's content lives in af-docs/content/docs, split into audience sections — developers (this section), admins, artisans, and legacy — each with its own meta.json controlling page order.

The screenshot pipeline

Screenshots embedded in these docs are captured automatically from a running instance of the main site, using tooling that lives in the artisanal-futures-site repo (not here). It never touches staging or production — every command layers .env.docs on top of .env, pinning the pipeline to the local Docker Postgres container, and the seed script refuses to run against any non-localhost database.

One-time setup

docker compose up -d
pnpm exec playwright install chromium

Refresh workflow

Start the local database:
```
docker compose up -d
```
Seed demo data:
```
pnpm docs:seed
```
This creates two demo users — demo-admin@artisanalfutures.org (role ADMIN) and demo-artisan@artisanalfutures.org (role ARTISAN) — through the real invite-gated sign-up flow, plus a demo shop, products, services, an event, and a forum community. It's idempotent: safe to re-run, and it writes into the local af_docs database only.
Capture the shot list:
```
pnpm docs:shots
```
This starts the dev server on port 3009 (via Playwright's webServer, so it never collides with a normal pnpm dev session on :3000) and runs the screenshots defined in e2e/shot-list.ts.

Publish shots directly into this site:

SHOTS_OUT_DIR=../af-docs/public/images pnpm docs:shots

Review the resulting diff in af-docs, then commit manually.

pnpm docs:seed runs tsx --env-file=.env --env-file=.env.docs scripts/docs/seed-demo.ts — the later --env-file wins, so .env.docs overrides DATABASE_URL to point at the local af_docs database. The seed script parses DATABASE_URL before importing anything else and exits immediately unless the host is localhost or 127.0.0.1, so it cannot accidentally run against a shared or remote database.

Files involved (in `artisanal-futures-site`)

playwright.config.ts — Playwright config; webServer runs pnpm dev -p 3009.
e2e/auth.setup.ts — logs the two demo users in once and saves storage state to e2e/.auth/.
e2e/shot-list.ts — the list of screenshots to capture. Edit this whenever the UI changes so screenshots stay accurate.
e2e/screenshots.spec.ts — the Playwright test that walks the shot list and takes the captures.
scripts/docs/seed-demo.ts — the demo-data seed script described above.
.env.docs — local-only, gitignored env overrides for the pipeline.

Editing content by hand

Everything else in content/docs is hand-written Markdown/MDX. When a feature changes, update the relevant audience section's pages directly, and update e2e/shot-list.ts if the change affects a screenshotted view.