chore: track Cursor agent rules in git

- .gitignore: ignore .cursor/* except .cursor/rules/*.mdc (no API keys in rules)
- Add docgen-tools-only and no-asset-edits (scene-spec / declarative Manim)

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: jmjava

.cursor/rules/docgen-tools-only.mdc

@@ -0,0 +1,18 @@
+---
+description: All doc/demo asset generation goes through docgen CLI and approved wrappers—never Cursor-authored outputs.
+alwaysApply: true
+---
+
+# Documentation and demo generation: tools only
+
+**Rule:** Anything that **generates** documentation assets, dogfood config, narration, scenes, audio, composed video, catalogs, or other pipeline outputs must be produced by **docgen** (CLI and library) plus **repo-documented scripts** that invoke it (e.g. `docs/demos/_regenerate-docgen-config.sh`, `_full-reset-regenerate.sh`). **Do not** use the editor to paste or rewrite generated files to “fix” the pipeline.
+
+**Allowed for Cursor / humans**
+
+- Edit **inputs** Git is meant to carry: **`docgen.yaml`** (review YAML diff after **`docgen yaml-generate`**), per-function manifests, hints, tests, fixtures, static `docs/*.md` that are not tool outputs.
+- Edit **docgen implementation** under `src/` (or equivalent package root): new flags, commands, merge logic, validators—so the **tool** can do what you need.
+- Run commands: `docgen …`, bundle shell scripts, tests.
+
+**Dogfood (`docs/demos`):** **`docgen.yaml`** is the only bundle config—same as downstream. Run **`docgen yaml-generate`** (this repo: **`docs/demos/_regenerate-docgen-config.sh`**) to merge tool defaults and sync **`manim_scene_generation.segments`** from **`visual_map`**; do not keep a second “source” YAML. Manim diagram segments: use **`docgen scene-spec-generate`** / **`scene-compile`** and committed **`animations/specs/*.scene.yaml`**, not hand-edited **`scenes.py`** for those blocks.
+
+**If the right command does not exist:** implement it in **docgen** (or a thin wrapper script committed to the repo), then use it—do not bypass with manual file edits.

.cursor/rules/no-asset-edits.mdc

@@ -0,0 +1,45 @@
+---
+description: Documentation assets are produced by docgen + OpenAI; Cursor never edits them by hand. No hardcoded segment numbers, scene classes, tape names, or fixture paths in `src/docgen/` or non-test docs.
+alwaysApply: true
+---
+
+# Tool-only asset generation; no hardcoded segment / fixture references
+
+## Three categories
+
+A. **Cursor edits OK** (code, tests, wrappers, rules, top-level docs):
+- `src/docgen/**`
+- `tests/**`
+- `docs/demos/_*.sh`
+- `.cursor/rules/**`
+- `AGENTS.md`, root `README.md`, `docs/demo-function.md`, `docs/yaml-generate.md`, `docs/session-notes*.md`
+- `milestones/**`
+
+B. **Hand-authored INPUTS / fixtures** (Cursor edits OK; **never** deleted by `clean-bundle` / reset; **not** LLM outputs):
+- `docs/demos/terminal/*.tape` — VHS sources
+- `docs/demos/scripts/*.py` — Playwright capture drivers (matched to segments by id-in-filename)
+- `fixtures/**` — Playwright/Vite/etc. test apps; presence and project-type detected generically. The raw `*.spec.{ts,tsx,js,jsx,mjs}` files inside are the **input** to `docgen per-function-generate`.
+- `docs/demos/narration/README.md`
+
+C. **LLM/tool OUTPUTS — Cursor MUST NOT edit; only `docgen` (CLI/library) + OpenAI may produce:**
+- `docs/demos/docgen.yaml` (owner: `docgen yaml-generate`)
+- `docs/demos/narration/*.md` excluding `README.md` (owner: `docgen narration-generate`)
+- `docs/demos/animations/scenes.py`, `docs/demos/animations/timing.json` (owner: `docgen scene-generate`, **`docgen scene-compile`**, **`docgen scene-spec-generate`**, pipeline)
+- `docs/demos/animations/specs/*.scene.yaml` — declarative Manim scene specs (owner: **`docgen scene-spec-generate`** with optional hand curation; compiled into `scenes.py` via **`docgen scene-compile`**)
+- `docs/demos/audio/*.mp3` (owner: `docgen tts`)
+- `docs/demos/per-function/*.docgen.yaml` and sibling `*.html` (owner: `docgen per-function-generate` — generated from raw Playwright specs in `fixtures/**`; wiped + regenerated each reset)
+- `docs/demos/recordings/**` including `recordings/per-function/<slug>/*` and top-level aliases (owner: `docgen generate-all` and `docgen demo-function` driven by `_rebuild-per-function.sh`)
+
+If a generator can't produce shippable output yet, **fix the generator** under `src/docgen/**`. Never paste/edit a category-C file to bridge the gap.
+
+## No hardcoded segments or fixtures
+
+`docgen` itself contains **no** hardcoded segment numbers, scene class names, tape filenames, or fixture paths. Discovery only:
+
+- Segments → from `narration/<NN>-*.md` filenames.
+- VHS → from `terminal/<segment_stem>.tape` presence.
+- Playwright capture → from `scripts/*.py` whose filename contains the segment id.
+- Manim → from `class …Scene` definitions in `animations/scenes.py`, in source order.
+- Playwright projects (for `discover_tests.roots`) → from any directory with `@playwright/test` / `playwright` in `package.json` or a `playwright.config.{js,ts,mjs,cjs}`.
+
+Tests are exempt: concrete ids and class names there are intentional test data.

.gitignore

@@ -15,7 +15,10 @@ build/
 
 .idea/
 .vscode/
-.cursor/
+# Cursor: track `.cursor/rules/*.mdc` only; ignore other workspace data (un-ignore must follow ignore)
+.cursor/*
+!.cursor/rules/
+!.cursor/rules/*.mdc
 *.swp
 *.swo