docs: move the Choreo docs into the package READMEs and the gallery realm

.claude/skills/choreo-create/SKILL.md

@@ -42,11 +42,11 @@ composition idea) in `packages/choreo-gallery/realm/demos/<id>.json`. The test
 app keeps a copy in `packages/choreo-test-app/app/content/demo-lessons.json` for
 its guide pages; change both, since the realm check fails when they differ. The
 concept guides are `packages/choreo-test-app/app/content/guides/*.md`.
-`packages/choreo-gallery/docs/api-inventory.json` maps public APIs to concept
+`packages/choreo-gallery/tools/api-inventory.json` maps public APIs to concept
 guides; look up the relevant entries rather than loading it whole. For a
 tutorial, isolate one observable relationship and predict the result of a
 parameter change. The docs-only spatial/film studies in
-`packages/choreo-gallery/docs/docs-studies-plan.md` are planned, not shipped.
+`packages/choreo-gallery/realm/design/docs-studies-plan.md` are planned, not shipped.
 
 Every control must supply a named variable consumed by that example. Show units,
 use meaningful ranges, and retain source defaults. The test app's

.claude/skills/choreo-create/references/composition-recipes.md

@@ -24,4 +24,4 @@ Use the catalog to resolve the components named below. These are starting points
 - **Architectural film:** the `towers` and `sagrada` film routes and their film/score components. Reuse the Film graph: spine, chapters, shots, picture actors, type, voice, and joins. Distinguish exact seeking from the chased camera's cut mode.
 - **Guided gallery:** `packages/choreo-test-app/app/components/widget-room.gts`, and `widget-quick-tour.ts`, `widget-tour.ts` and `widget-narration.ts` in `packages/choreo-test-app/app/lib/`. Organize chapters around capabilities, score the camera and actions together, and budget live demos to the active view. Preserve a preview until the replacement is visibly ready.
 
-Read `packages/choreo-gallery/docs/film.md` for as-built Film contracts, `packages/choreo-gallery/docs/demo-recording.md` for ownership, and `packages/choreo-gallery/docs/dom-in-3d.md` for the DOM projection boundary. Design documents sometimes describe proposed capabilities; use exported source to confirm availability.
+Read `packages/choreo-gallery/realm/docs/film.md` for as-built Film contracts, `packages/choreo-gallery/realm/docs/demo-recording.md` for ownership, and `packages/choreo-gallery/realm/docs/dom-in-3d.md` for the DOM projection boundary. Design documents sometimes describe proposed capabilities; use exported source to confirm availability.

.claude/skills/choreo-create/references/spatial-and-film.md

@@ -4,17 +4,17 @@ Choose the boundary before choosing a demo. Read only the row needed for the tas
 Guide paths below are under `packages/choreo-test-app/app/content/guides/`;
 implementation exports remain the authority for accepted arguments.
 
-| Intent                                 | Read                                                 | Minimal source reference                                                        |
-| -------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------- |
-| Frame or pan across DOM                | spatial-frame.md                                     | examples/camera.gts; long-take/board.gts                                        |
-| Relative pose or coordinate conversion | spatial-relative.md; spatial-coordinates.md          | `packages/choreo/src/choreo.gts` vocabulary; `app/lib/css3d.ts`                 |
-| 3D camera path and look target         | spatial-camera3d.md; spatial-paths.md                | examples/mockup.gts; examples/long-take.gts                                     |
-| Place live DOM on a mesh plane         | spatial-dom.md; spatial-compositing.md               | examples/mockup.gts; `packages/choreo-gallery/docs/dom-in-3d.md`                |
-| Film graph, shots and picture actor    | film-graph.md; film-picture.md                       | tower-film.gts; sagrada-film.gts                                                |
-| Seek, pause or capture                 | film-transport.md; film-schedule.md                  | `packages/choreo-gallery/docs/demo-recording.md`; `packages/choreo-player/src/` |
-| Joins and readiness                    | film-joins.md; film-seam-readiness.md                | `packages/choreo/src/film/`                                                     |
-| Separate clips, audio and captions     | film-audio.md; film-audio-mix.md; film-typography.md | `app/lib/widget-narration.ts`; `@cardstack/choreo/film` exports                 |
-| World labels and adjustments           | film-world-annotations.md; film-adjustments.md       | picture capability implementation and its Film score                            |
+| Intent                                 | Read                                                 | Minimal source reference                                                              |
+| -------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| Frame or pan across DOM                | spatial-frame.md                                     | examples/camera.gts; long-take/board.gts                                              |
+| Relative pose or coordinate conversion | spatial-relative.md; spatial-coordinates.md          | `packages/choreo/src/choreo.gts` vocabulary; `app/lib/css3d.ts`                       |
+| 3D camera path and look target         | spatial-camera3d.md; spatial-paths.md                | examples/mockup.gts; examples/long-take.gts                                           |
+| Place live DOM on a mesh plane         | spatial-dom.md; spatial-compositing.md               | examples/mockup.gts; `packages/choreo-gallery/realm/docs/dom-in-3d.md`                |
+| Film graph, shots and picture actor    | film-graph.md; film-picture.md                       | tower-film.gts; sagrada-film.gts                                                      |
+| Seek, pause or capture                 | film-transport.md; film-schedule.md                  | `packages/choreo-gallery/realm/docs/demo-recording.md`; `packages/choreo-player/src/` |
+| Joins and readiness                    | film-joins.md; film-seam-readiness.md                | `packages/choreo/src/film/`                                                           |
+| Separate clips, audio and captions     | film-audio.md; film-audio-mix.md; film-typography.md | `app/lib/widget-narration.ts`; `@cardstack/choreo/film` exports                       |
+| World labels and adjustments           | film-world-annotations.md; film-adjustments.md       | picture capability implementation and its Film score                                  |
 
 Component paths are relative to `packages/choreo-test-app/app/components/`; `app/` paths
 are relative to `packages/choreo-test-app`. Other paths are repository-relative. Use the catalog
@@ -31,6 +31,6 @@ nested cameras; independent hard-coded durations drift. A render barrier means
 the requested picture is ready, not merely that an arbitrary delay expired.
 
 For a tutorial, prefer a tiny procedural scene that isolates one relationship.
-Use `packages/choreo-gallery/docs/docs-studies-plan.md` for the planned docs-only studies. They are not
+Use `packages/choreo-gallery/realm/design/docs-studies-plan.md` for the planned docs-only studies. They are not
 shipped examples. Keep full museum films as composition references rather than
 forcing their assets, narration and lighting into every camera exercise.

.claude/skills/choreo-regions/SKILL.md

@@ -108,4 +108,4 @@ barrier between tests — required, or passes leak across tests.
 Ground truth: `packages/choreo-test-app/app/components/examples/far-match.gts`
 (three bays, the on/off switch is just id scoping) and its Deep Dive note
 `packages/choreo-test-app/app/components/notes/far.gts`; design in
-`packages/choreo-gallery/docs/nested-choreo.md`.
+`packages/choreo-gallery/realm/docs/nested-choreo.md`.

.claude/skills/choreo-scene/SKILL.md

@@ -102,7 +102,7 @@ document-global on purpose (chrome and outlet are separate regions).
 An inner `<Choreo>` is a separate scene — the outer region does not see its
 participants. Regions, far matching (an id leaving one region and appearing
 in another), and cross-region measurement: `choreo-regions`, and
-`packages/choreo-gallery/docs/nested-choreo.md`.
+`packages/choreo-gallery/realm/docs/nested-choreo.md`.
 
 ## When NOT
 
@@ -113,4 +113,4 @@ One element, no ordering, no cross-element measurement → `motion-element` /
 Canonical demos, in `packages/choreo-test-app/app/components/examples/`:
 `inbox.gts` (beacons), `sequence.gts`, `interrupt.gts`,
 `slides.gts`, `far-match.gts`, `split-view.gts` (function values),
-`lists.gts`. Design doc: `packages/choreo-gallery/docs/choreography.md`.
+`lists.gts`. Design doc: `packages/choreo-gallery/realm/docs/choreography.md`.

.claude/skills/motion-pattern/SKILL.md

@@ -68,10 +68,10 @@ Dives — the
 _reasoning_ behind each pattern choice (why the inbox uses beacons, how the
 interruption model holds, what the playhead samples). Read the note when
 modifying its demo.
-Docs: `packages/choreo-gallery/docs/guide.md` (tutorial), the package READMEs
+Docs: `packages/choreo-gallery/realm/docs/guide.md` (tutorial), the package READMEs
 `packages/glimmer-motion/README.md` and `packages/choreo/README.md` (API
-reference), `packages/choreo-gallery/docs/choreography.md` +
-`packages/choreo-gallery/docs/nested-choreo.md` (Choreo design).
+reference), `packages/choreo-gallery/realm/docs/choreography.md` +
+`packages/choreo-gallery/realm/docs/nested-choreo.md` (Choreo design).
 
 A card in a realm imports the same libraries through host's realm shims, under
 different rules (no direct motion-dom imports, state shared with host). For

packages/choreo-film-app/app/components/films/sagrada-score.gts

@@ -2,7 +2,7 @@
  * SAGRADA FAMÍLIA, AS A GRAPH — the film's score in the film vocabulary.
  *
  * Generated from the beat table in `lib/films/sagrada.ts` by
- * `docs/film-graph/tograph.mjs` (PREFIX='@f.'), so every pose, phrase,
+ * `tools/tograph.mjs` (PREFIX='@f.'), so every pose, phrase,
  * stamp and trace is the table's; only the shape differs. It takes the
  * vocabulary as an argument so it can be rendered inside `<Film as |f|>`
  * and, in `tests/integration/film/graph-test.gts`, inside a bare

packages/choreo-film-app/app/components/films/towers-score.gts

@@ -2,7 +2,7 @@
  * TOWERS, AS A GRAPH — the film's score in the film vocabulary.
  *
  * Generated from the beat table in `lib/films/towers.ts` by
- * `docs/film-graph/tograph.mjs` (PREFIX='@f.'), so every pose, phrase,
+ * `tools/tograph.mjs` (PREFIX='@f.'), so every pose, phrase,
  * stamp and trace is the table's; only the shape differs. It takes the
  * vocabulary as an argument so it can be rendered inside `<Film as |f|>`
  * and, in `tests/integration/film/graph-test.gts`, inside a bare

packages/choreo-film-app/app/lib/films/sagrada.ts

@@ -17,7 +17,7 @@ import { hex, RAD } from '@cardstack/choreo/film/math';
 /**
  * SAGRADA — a film, at `/sagrada`.
  *
- * The second reference film for the film construct (notes/film-construct.md),
+ * The second reference film for the film construct (packages/choreo-gallery/realm/design/film-construct.md),
  * and the first one cut ON it: everything here is the shot list, the
  * script, the chapters, the year clock, the traces sampled off the model,
  * and the front and back matter. The engine — the chased lens, the joins,
@@ -167,7 +167,7 @@ export const VO_GAIN: Record<string, number> = {
  * files in `public/sagrada/vo/`. The kinetic type is paced against the VOICE,
  * not against the beat: the last cue should land as the line is finishing,
  * whether the read is four seconds or thirteen. Estimating this went wrong
- * once already (see notes/towers-vo.md) — so it is measured, and a re-record
+ * once already (see packages/choreo-gallery/realm/design/towers-vo.md) — so it is measured, and a re-record
  * means re-measuring. A beat missing from here paces against its own length.
  */
 export const VO_SECS: Record<string, number> = {

packages/choreo-film-app/app/lib/films/towers.ts

@@ -10,7 +10,7 @@ import { hex, RAD } from '@cardstack/choreo/film/math';
 /**
  * TOWERS — a film, at `/towers`.
  *
- * The first reference film for the film construct (notes/film-construct.md),
+ * The first reference film for the film construct (packages/choreo-gallery/realm/design/film-construct.md),
  * now cut ON it: what is left here is the shot list, the script, the
  * chapters, the six climates, the traces sampled off the keep, and the
  * front and back matter in the film's own Japanese voice. The engine —
@@ -226,7 +226,7 @@ export const VO_GAIN: Record<string, number> = {};
  * files in `public/towers/vo/`. The kinetic type is paced against the VOICE,
  * not against the beat: the last cue should land as the line is finishing,
  * whether the read is four seconds or thirteen. Estimating this went wrong
- * once already (see notes/towers-vo.md) — so it is measured, and a re-record
+ * once already (see packages/choreo-gallery/realm/design/towers-vo.md) — so it is measured, and a re-record
  * means re-measuring. A beat missing from here paces against its own length.
  */
 export const VO_SECS: Record<string, number> = {

packages/choreo-film-app/tests/integration/film/graph-test.gts

@@ -4,7 +4,7 @@
  * Both reference films exist twice on this branch: as the beat tables the
  * engine has always run (`lib/films/*.ts`) and as graphs written in the
  * film vocabulary (`components/films/*-score.gts`, generated from those
- * tables by `docs/film-graph/tograph.mjs`). These render each graph
+ * tables by `tools/tograph.mjs`). These render each graph
  * inside a bare `<FilmGraph>` and assert that what it compiles to is the
  * table — every row, every key — and the same measured reads. That is
  * the whole of Phase 2's first claim, and it is what lets the films