@rig-c/create 0.0.0-stage → 1.0.1

package/docs/SOURCE.md

@@ -0,0 +1,225 @@
+# Source: the layer split and the cut
+
+Most bounces are decided before a bone exists: at the layer split (See-through)
+and at the cut. This page is what to do there, in what order, and why. Read it
+before `seethrough` and before `assemble`.
+
+It is the working order, not the machine contract. The contract — which fields,
+which lines `assemble` prints, which refusals fire — is in rig-c/parts
+[AUTHORING.md](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md)
+and its [README](https://github.com/rig-c/parts/blob/v2.37.0/README.md), linked
+here at the version a new project pins (2.37.0) and not copied. In a project, read
+the same files under `node_modules/@rig-c/parts/`.
+
+Every rule carries its source: a parts section, an owner ruling with its date,
+or a pilot measurement with its date.
+
+## The order
+
+1. [Upscale a small source](#upscale-a-small-source-first), before it goes into
+   `inputs/`.
+2. [Run the split twice](#two-passes-the-whole-figure-then-the-head): the whole
+   figure, then the head.
+3. [Check the split](#look-at-the-split-before-calling-it-good): pairs, hidden
+   surface, doubled outlines, specks and holes.
+4. [Re-run first](#re-run-first) when it is bad. Several runs before any cut.
+5. [Cut only for structure](#where-a-cut-is-allowed), and at a limb only at its
+   joint.
+6. [Edit in the image editor, with a receipt](#the-editor-rung), when re-runs
+   cannot fix a visible-pixel defect.
+7. [Check density](#density-the-split-against-the-rig) and
+   [mixed sources](#mixed-sources) before `assemble` is called done.
+
+## The layer split
+
+### Upscale a small source first
+
+A painting smaller than the rig needs is upscaled before the split, with a 4x
+anime upscaler: the RGB upscaled on a black matte, the alpha upscaled separately
+as grey, then the two recombined un-premultiplied and alpha below 8 clipped to 0.
+A painting already in `inputs/` gets its upscale as a new input; inputs are never
+edited.
+
+- **Why**: See-through and every later stage can only lose detail. Upscaling RGB
+  and alpha apart keeps the matte colour out of the edge, which an upscale of the
+  composited image does not.
+- **A light fringe is not from such an upscale.** When a light halo shows along
+  an edge, look for a step later in the chain that flattened the image on white.
+- *Source*: owner ruling, 2026-10-29/31 (recipe); pilot measurement, 2026-11-03
+  (the fringe).
+
+### Two passes: the whole figure, then the head
+
+Run See-through on the whole figure (`st_input_full.png`), then on the head crop
+on its own (`st_input_head.png`, cut by `rig-parts inputs` from
+`seethrough.head_box`).
+
+- **Why**: on every route that was read, the model's own head stage pastes the
+  face back at the full run's pixel density. The separate head run is what gives
+  the eyes their pixels.
+- *Source*: parts AUTHORING
+  [*See-through head-run source reading*](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md#see-through-head-run-source-reading);
+  the routes in the parts README,
+  [*Getting See-through layers*](https://github.com/rig-c/parts/blob/v2.37.0/README.md#getting-see-through-layers).
+
+### Resolution: check the memory first
+
+Read the model's memory requirement before raising the run's `resolution`. "The
+wrapper accepts it" is not "it fits": a 2048 run needs about 24 GB. Do not raise
+the full run's resolution to buy face detail; the face gets its density from the
+head pass.
+
+- **Why**: a run that does not fit fails or falls back silently, and the time is
+  lost either way; the head pass already does what the higher resolution was for.
+- *Source*: owner ruling, 2026-10-29/31; pilot measurement, 2026-11-03.
+
+### Look at the split before calling it good
+
+Before `assemble`, on the raw layers:
+
+- **Pairs** (left/right bust, eyes, hair ends, hem panels): both present,
+  comparable area, mirrored edge placement, measured on the layers and compared
+  with the same measure on the painting, so an asymmetry the painting has is not
+  flagged ([CRAFT.md G8](CRAFT.md#for-the-gates-not-the-interview)).
+- **Hidden surface**: under every part that will move over another, the part
+  behind is painted (amodal), not empty.
+- **No doubled outline**: an edge drawn twice, once on each of two layers, is a
+  ghost.
+- **Specks and holes**, counted on each layer PNG straight out of See-through, on
+  a sentinel colour ([LESSONS.md](LESSONS.md#specks-and-holes-in-the-split-layers),
+  [CRAFT.md G9](CRAFT.md#for-the-gates-not-the-interview)).
+- **Why**: every one of these is cheaper to fix here than after `assemble`,
+  where it is mixed with cut and draw-order effects.
+- *Source*: owner ruling, 2026-10-29/31; owner ruling, 2026-11-03 (specks and
+  holes).
+
+### Re-run first
+
+When the split is bad — an uneven pair, a poor hidden surface behind an arm, a
+ghost, specks or holes — re-run before anything else, and record what each run
+measured:
+
+1. another layer or run: `full` versus `head`, another tag, `assemble.alternates`;
+2. a tighter crop pass of the bad region, on its own;
+3. other settings (a resolution that fits in memory, another run of the same input).
+
+Several runs are cheaper than one bounce. Only when re-runs cannot fix a
+visible-pixel defect does the [editor rung](#the-editor-rung) come next.
+
+- **Why**: a defect in the split is a source problem, and a source problem
+  patched downstream comes back at every motion extreme.
+- *Source*: parts AUTHORING
+  [*Source before scissors*](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md#source-before-scissors)
+  (the repair ladder: another layer or run, a re-run, then config); owner ruling,
+  2026-10-29/31 (re-run first, several runs before a cut).
+
+## Cutting
+
+### Where a cut is allowed
+
+**Scissors are for structure, never for repair.** A cut (`assemble.cuts`, a patch,
+an `author:<label>` layer) is admitted only to separate something that must move
+or draw on its own and has no layer:
+
+- a joint (an arm or a leg, [below](#at-a-limb-joint));
+- an accessory still inside its parent's layer;
+- a rear piece that needs its own draw position;
+- **a draw-order split**: two arms on opposite sides of a held object are
+  separate parts, even though they never move apart.
+
+A tear, ghost, smudge, stray outline or seam is repaired from the source (the
+[re-run ladder](#re-run-first)), never by a cut-out or an under-piece. No hand
+polygon where the piece has no material past its joint: no source means stop and
+name the gap.
+
+- **Why**: a polygon cut supplies no material for the turn it is meant to allow,
+  so it tears at the edge in motion; a cut over a defect hides it at rest and
+  shows it moving.
+- *Source*: parts AUTHORING
+  [*Source before scissors*](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md#source-before-scissors)
+  (scissors for structure, the cases a cut fits, no material past the joint) and
+  its paragraph *A layer the author made*; owner ruling, 2026-10-29/31; pilot
+  measurement, 2026-11-03 (the draw-order split).
+
+### At a limb joint
+
+At an arm or leg joint, and only there: cut in the image editor and round the
+seam with its smudge tool. The limb is still separate rigid parts, one bone each;
+it is never one mesh bent across the joint (`LIMB_ONE_BONE`).
+
+- **Why**: a limb cut anywhere else, or bent as one mesh, shows a straight edge
+  or a grotesque bend.
+- *Source*: parts AUTHORING
+  [*Limbs: cut at their joints*](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md#limbs-cut-at-their-joints-limbs-issue-349);
+  [CRAFT.md A2](CRAFT.md#a2-limbs-that-bend-are-cut-at-the-joint-and-rounded);
+  owner ruling, 2026-10-29/31.
+
+### The editor rung
+
+The rung after re-runs: a piece taken from the painting along its painted
+outlines, in an image editor, with See-through's own alpha loaded as the
+selection where no line is painted. Refine the edge with a slight outward shift
+and feather 0. Missing material: content-aware fill, clone stamp, healing brush.
+Every edit leaves a receipt: the commands, the input and output hashes, and a
+layered file saved beside the PNG.
+
+**Never a polygon in code or config, and never a per-pixel repair in code.**
+See-through stays the source for hidden surface.
+
+One exception covers step-4 plates only: a receipted generative plate pass from a
+package command is a source, not a repair. The parts plate command removes the
+figure from the background, or mattes the foreground, using a mask from a source
+(See-through figure layers or the declared figure mask). Its
+`rig-parts-plate-receipt/1` receipt records the painting, mask, model, every
+parameter, the GPU and the output by hash. Character parts and joints never take
+this route.
+
+Measured limits:
+
+- an anti-aliased edge that sits inward reads light on white; the outward shift
+  fixes it;
+- a fill holds flat colour but does not continue an outline.
+
+- **Why**: an edit with a receipt can be checked and redone; a scripted edit
+  cannot be told from a defect ([CRAFT.md G6, G7](CRAFT.md#for-the-gates-not-the-interview)).
+- *Source*: owner ruling, 2026-10-29/31 (editor and receipt, the fill limit);
+  pilot measurement, 2026-11-03 (outline selection, alpha where no line, shift
+  outward, feather 0, the inward-edge limit).
+
+### Feather only continuous skin
+
+Feather a cut face only on continuous skin (a bare arm below a short sleeve);
+keep a designed cut face (a cuff, an armour plate) crisp.
+
+- *Source*: [CRAFT.md A3](CRAFT.md#a3-soften-a-cut-through-skin-not-a-designed-edge);
+  owner ruling, 2026-10-29/31.
+
+## Density: the split against the rig
+
+When the split's canvas is coarser than the rig, every split layer is upscaled
+into the rig and reads softer than the painting. Measure the edge rise width
+(10–90 % of the step, across an outline) on the parts and on the painting at the
+same place. A rig scale near the guide value (parts AUTHORING, `assemble.rig_scale`
+in [*`config.json`, field by field*](https://github.com/rig-c/parts/blob/v2.37.0/docs/AUTHORING.md#3-configjson-field-by-field):
+the figure about 1,100 to 1,200 rig px tall) can close it. When the guide value
+is at least as good on every figure measured, the guide value wins.
+
+- **Why**: softness is not a seam, so no bar reads it, and it shows only beside
+  the painting.
+- *Source*: pilot measurement, 2026-11-03.
+
+## Mixed sources
+
+When a plan mixes runs (`full` and `head`), keep every run's manifest
+(`layers.json`) entries listed, including the entries the plan does not take from
+that run. Do not unlist the other run's copies of those regions.
+
+- **Why**: an entry that no planned part takes still holds depth ownership
+  (`pixelOwners`) in its run, which stops a neighbouring planned part from
+  claiming its pixels. Measured on a pilot (`full` + `head`, same layer PNGs byte
+  for byte), unlisting the unused entries changed 12 of 24 planned parts (`face`
+  5,424 px, `hair_back` 2,679 px, `neck` 1,575 px, `hair_front` 402 px, and 8
+  parts under 100 px) and baked the face and eyes into the back hair, hair
+  strands into the face, and the chin line into the neck; with the entries kept
+  listed, all three were clean.
+- *Source*: pilot measurement, 2026-11-07.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@rig-c/create",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "type": "module",
+  "description": "Create a rig project: its folder, decision record, repository and pinned rig-c packages",
+  "license": "MIT",
+  "files": [
+    "src/",
+    "templates/",
+    "README.md",
+    "LICENSE",
+    "docs/PROJECT.md",
+    "docs/INTERVIEW.md",
+    "docs/CHECKS.md",
+    "docs/COLLECTIONS.md",
+    "docs/CRAFT.md",
+    "docs/SOURCE.md",
+    "docs/LESSONS.md"
+  ],
+  "bin": {
+    "rig-create": "src/cli.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@rig-c/core": "3.7.0",
+    "@rig-c/parts": "2.37.0",
+    "@rig-c/review": "4.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.0",
+    "eslint": "^10.11.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.70.1"
+  },
+  "engines": {
+    "bun": ">=1.4.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rig-c/create.git"
+  }
+}

package/src/agent-bounce.ts

@@ -0,0 +1,27 @@
+import { asArray, collectionQuestion, isObject, type Ctx } from './check.ts';
+import { AGENT_BOUNCE_SINCE } from './stages.ts';
+import type { JsonObject } from './templates.ts';
+
+/** A mid-step rejection is history, separate from human version verdicts. */
+export function checkAgentBounces(ctx: Ctx): void {
+  const records = new Map<string, JsonObject>();
+  for (const item of ctx.items) {
+    records.set(item.path.replace(/\.(answer|guide)$/, ''), item.record);
+    if (isObject(item.raw) && item.raw.basis === 'inherited' && isObject(item.raw.from) && typeof item.raw.from.question === 'string' && ctx.collection !== null) {
+      const question = collectionQuestion(ctx.collection, item.raw.from.question);
+      if (question !== undefined) records.set(`collection.interview[${item.raw.from.question}]`, question);
+    }
+  }
+  for (const [base, record] of records) asArray(record.history).forEach((entry, i) => {
+    if (!isObject(entry) || !('bounce' in entry)) return;
+    const bounce = entry.bounce;
+    if (isObject(bounce) && bounce.cause === 'agent' && ['failed', 'bar', 'replacement'].every((k) => typeof bounce[k] === 'string' && (bounce[k] as string).trim() !== '')) return;
+    const at = typeof entry.at === 'string' ? Date.parse(entry.at) : Number.NaN;
+    const legacy = !Number.isFinite(at) || at < Date.parse(AGENT_BOUNCE_SINCE);
+    const path = `${base}.history[${i}].bounce`;
+    (legacy ? ctx.warnings : ctx.refusals).push({
+      code: legacy ? 'AGENT_BOUNCE_LEGACY' : 'AGENT_BOUNCE_MALFORMED', path,
+      message: `${path}: needs { cause: 'agent', failed, bar, replacement } with non-empty text${legacy ? `; history entry predates ${AGENT_BOUNCE_SINCE} or has no readable at; kept as legacy` : ''}`,
+    });
+  });
+}

package/src/agent-guide.ts

@@ -0,0 +1,237 @@
+import { writeFileSync } from 'node:fs';
+import { readFileSync } from './check-reads.ts';
+import { join } from 'node:path';
+
+import { PINNED_PACKAGES } from './pins.ts';
+import { TEMPLATES_DIR } from './templates.ts';
+
+/**
+ * create's own docs are linked on GitHub at `main`: create is not installed in
+ * a project, it has no published version or tag to pin to, and init already
+ * points at `main` for the interview (init.ts). A commit pin would send every
+ * new project to docs that were already stale when it was made.
+ */
+export const CREATE_DOCS_BASE = 'https://github.com/rig-c/create/blob/main/';
+
+export type PinnedPackage = keyof typeof PINNED_PACKAGES;
+
+export interface PackageDoc {
+  package: PinnedPackage;
+  /** Path inside the installed package, as `npm pack --dry-run` lists it. */
+  path: string;
+  /** Why and when to read it. Says what the document is for, never what it says. */
+  why: string;
+}
+
+/**
+ * The installed packages' documents the guide links, checked against the files
+ * each pinned version ships (`npm pack --dry-run`). A pin bump is an edit here,
+ * and the network test fails if a listed path is not in the installed package.
+ *
+ * Shipped but left out on purpose:
+ * - core `docs/PROMPTING.md`: written for the person operating an agent; it
+ *   says the agent should read AUTHORING.md instead.
+ * - core `docs/SPEC_COVERAGE.md`: core's AUTHORING.md calls it not an
+ *   authoring input and leaves it unlinked.
+ */
+export const PACKAGE_DOCS: readonly PackageDoc[] = [
+  {
+    package: '@rig-c/parts',
+    path: 'README.md',
+    why: 'painting-to-rig pipeline and command order',
+  },
+  {
+    package: '@rig-c/parts',
+    path: 'docs/AUTHORING.md',
+    why: 'config fields, interview waypoints and refusal remedies',
+  },
+  {
+    package: '@rig-c/parts',
+    path: 'docs/PAINTING.md',
+    why: 'what makes a painting riggable, and the check to run on it before See-through',
+  },
+  {
+    package: '@rig-c/parts',
+    path: 'docs/DEPTH.md',
+    why: 'when the plan has a head turn driven by depth',
+  },
+  {
+    package: '@rig-c/parts',
+    path: 'docs/STABILITY.md',
+    why: 'stable commands, fields and outputs',
+  },
+  {
+    package: '@rig-c/parts',
+    path: 'docs/MIGRATION.md',
+    why: 'only when the pinned version is bumped',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'README.md',
+    why: 'rigc scope, commands and documentation',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'docs/AUTHORING.md',
+    why: 'rig/motion formats, build loop and failure remedies',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'docs/RIGGING.md',
+    why: 'bones and pivots at the bones waypoint',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'docs/MOTION.md',
+    why: 'key-pose motions at the motion waypoint',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'docs/FACE.md',
+    why: 'blink, gaze and head-turn plans',
+  },
+  {
+    package: '@rig-c/core',
+    path: 'docs/INGEST.md',
+    why: 'only when you were handed a skeleton this project did not author',
+  },
+];
+
+export interface CreateDoc {
+  /** Path in the rig-c/create repository. */
+  path: string;
+  why: string;
+}
+
+export const CREATE_DOCS: readonly CreateDoc[] = [
+  {
+    path: 'docs/PROJECT.md',
+    why: 'the folder, stages and sign-offs, the plan, versions, and `project.json` field by field',
+  },
+  {
+    path: 'docs/INTERVIEW.md',
+    why: 'how to ask, and the shape every answer, delegation and piece of feedback takes',
+  },
+  {
+    path: 'docs/CRAFT.md',
+    why: 'the default to propose at each waypoint',
+  },
+  {
+    path: 'docs/COLLECTIONS.md',
+    why: 'when this project is a member of a collection',
+  },
+];
+
+/** Links into create's docs that carry an anchor; the tests check each anchor is a heading. */
+export const RESUME_LINK = { path: 'docs/PROJECT.md', anchor: 'how-an-agent-resumes-a-project' } as const;
+export const DERIVED_LINK = { path: 'docs/INTERVIEW.md', anchor: 'derived-answers' } as const;
+export const GATES_LINK = { path: 'docs/CRAFT.md', anchor: 'for-the-gates-not-the-interview' } as const;
+export const DRAFTS_LINK = { path: 'docs/PROJECT.md', anchor: 'labelled-draft-rigs-and-structure-decisions' } as const;
+export const STAGES_LINK = { path: 'docs/PROJECT.md', anchor: 'stages' } as const;
+export const LIFETIME_LINK = { path: 'docs/PROJECT.md', anchor: 'data-is-split-by-lifetime' } as const;
+export const INTAKE_LINK = { path: 'docs/PROJECT.md', anchor: 'advisory-intake-reports' } as const;
+export const CG_GATES_LINK = { path: 'docs/CHECKS.md', anchor: 'cg-gates' } as const;
+export const APPEARANCE_LINK = { path: 'docs/CHECKS.md', anchor: 'appearance-bar-wording' } as const;
+export const BUST_LINK = { path: 'docs/CHECKS.md', anchor: 'the-bust-at-meshes' } as const;
+export const PROJECTION_LINK = { path: 'docs/CHECKS.md', anchor: 'projection-and-ground' } as const;
+/** The heading is "Parts-stage check at the parts → parts-review move": the arrow drops, leaving two hyphens. */
+export const PARTS_CHECK_LINK = { path: 'docs/CHECKS.md', anchor: 'parts-stage-check-at-the-parts--parts-review-move' } as const;
+
+/** The refusals `advance parts-review --parts-check` can give, all in one CHECKS.md table. */
+export const PARTS_CHECK_CODES = ['MISSING', 'UNREAD', 'INVALID', 'CHANGED', 'FAILED', 'STALE'].map((c) => `PARTS_CHECK_${c}`);
+
+export function createDocUrl(path: string, anchor?: string): string {
+  return `${CREATE_DOCS_BASE}${path}${anchor === undefined ? '' : `#${anchor}`}`;
+}
+
+function createLink(label: string, path: string, anchor?: string): string {
+  return `[${label}](${createDocUrl(path, anchor)})`;
+}
+
+/**
+ * The one ordered entry point (rig-c/create#24): what to read before each step,
+ * naming the page and the section. create's pages are absolute links (create is
+ * not installed in a project); the parts and core sections are named, not
+ * linked, because the package links below are exactly PACKAGE_DOCS.
+ */
+export const READ_FIRST = [
+  '1. **Before the interview**: INTERVIEW.md, and CRAFT.md for the default at each',
+  '   waypoint (both linked below); parts AUTHORING §3, *`config.json`, field by',
+  `   field*; ${createLink('CHECKS.md', 'docs/CHECKS.md')} before a sign-off.`,
+  '2. **Before `seethrough` and `assemble`**: SOURCE.md, the order of the split and',
+  `   the cut: ${createLink('re-running a bad split', 'docs/SOURCE.md', 're-run-first')},`,
+  `   ${createLink('where a cut is allowed', 'docs/SOURCE.md', 'where-a-cut-is-allowed')};`,
+  '   then parts AUTHORING *See-through head-run source reading*, *Source before',
+  '   scissors* and *Limbs: cut at their joints*.',
+  `3. **Before rigging**: ${createLink('CRAFT.md § For the gates', 'docs/CRAFT.md', 'for-the-gates-not-the-interview')}`,
+  '   (G1–G9); core RIGGING and MOTION; parts AUTHORING §7, the bars `check` enforces.',
+  `4. **Before showing the user**: ${createLink('LESSONS.md § The self-check', 'docs/LESSONS.md', 'the-self-check')},`,
+  `   the ${createLink('per-frame seam count', 'docs/LESSONS.md', 'count-the-seam-bar-over-every-frame')},`,
+  `   ${createLink('what to show first', 'docs/LESSONS.md', 'what-to-show-the-user-first')}.`,
+].join('\n');
+
+/**
+ * The check an agent runs before asking for the interview sign-off: since
+ * rig-c/create#3 it is `rig-create interview --check`, which refuses every
+ * `null` answer by name, so the line names the command, not the doc reference.
+ */
+export const INTERVIEW_CHECK_LINE = 'Before asking the user to sign the interview, run `rig-create interview --check`: it names every `null` answer.';
+
+export const GUIDE_TEMPLATE = 'agent-guide.md';
+
+/** CLAUDE.md is a pointer: Claude Code reads CLAUDE.md, and an `@path` line imports that file into it. */
+export const CLAUDE_MD = [
+  '@AGENTS.md',
+  '',
+  'The agent guide for this project is AGENTS.md, imported above. It is the only copy: change it there, not here.',
+  '',
+].join('\n');
+
+export function packageDocPath(doc: PackageDoc): string {
+  return `node_modules/${doc.package}/${doc.path}`;
+}
+
+function linkLine(label: string, href: string, why: string): string {
+  return `- [${label}](${href}): ${why}.`;
+}
+
+/** The text of AGENTS.md, from the template and the tables above. */
+export function renderAgentGuide(): string {
+  const fills: Record<string, string> = {
+    RESUME_LINK: `[PROJECT.md § How an agent resumes a project](${createDocUrl(RESUME_LINK.path, RESUME_LINK.anchor)})`,
+    INTERVIEW_CHECK: INTERVIEW_CHECK_LINE,
+    DERIVED_LINK: `[INTERVIEW.md § Derived answers](${createDocUrl(DERIVED_LINK.path, DERIVED_LINK.anchor)})`,
+    GATES_LINK: `[CRAFT.md G8](${createDocUrl(GATES_LINK.path, GATES_LINK.anchor)})`,
+    DRAFTS_LINK: `[PROJECT.md § Labelled draft rigs](${createDocUrl(DRAFTS_LINK.path, DRAFTS_LINK.anchor)})`,
+    STAGES_LINK: `[PROJECT.md § Stages](${createDocUrl(STAGES_LINK.path, STAGES_LINK.anchor)})`,
+    LIFETIME_LINK: `[PROJECT.md § Data is split by lifetime](${createDocUrl(LIFETIME_LINK.path, LIFETIME_LINK.anchor)})`,
+    INTAKE_LINK: `[PROJECT.md § Advisory intake reports](${createDocUrl(INTAKE_LINK.path, INTAKE_LINK.anchor)})`,
+    CG_GATES_LINK: `[CHECKS.md § CG gates](${createDocUrl(CG_GATES_LINK.path, CG_GATES_LINK.anchor)})`,
+    APPEARANCE_LINK: `[CHECKS.md § Appearance bar wording](${createDocUrl(APPEARANCE_LINK.path, APPEARANCE_LINK.anchor)})`,
+    BUST_LINK: `[CHECKS.md § The bust at meshes](${createDocUrl(BUST_LINK.path, BUST_LINK.anchor)})`,
+    PROJECTION_LINK: `[CHECKS.md § Projection and ground](${createDocUrl(PROJECTION_LINK.path, PROJECTION_LINK.anchor)})`,
+    PARTS_CHECK_LINK: `[${PARTS_CHECK_CODES.map((code) => `\`${code}\``).join(', ')}](${createDocUrl(PARTS_CHECK_LINK.path, PARTS_CHECK_LINK.anchor)})`,
+    READ_FIRST,
+    PACKAGE_DOCS: PACKAGE_DOCS.map((doc) =>
+      linkLine(`${doc.package} ${doc.path}`, packageDocPath(doc), doc.why),
+    ).join('\n'),
+    CREATE_DOCS: CREATE_DOCS.map((doc) => linkLine(doc.path, createDocUrl(doc.path), doc.why)).join('\n'),
+  };
+  const template = readFileSync(join(TEMPLATES_DIR, GUIDE_TEMPLATE), 'utf8');
+  return template.replace(/\{\{([A-Z_]+)\}\}/g, (marker, key: string) => {
+    const fill = fills[key];
+    if (fill === undefined) throw new Error(`${GUIDE_TEMPLATE}: unknown marker ${marker}`);
+    return fill;
+  });
+}
+
+/**
+ * Writes the guide an agent reads first in a project — AGENTS.md, and a
+ * CLAUDE.md that imports it — and returns the paths written (relative to the
+ * project) so init can add exactly those to git.
+ */
+export function writeAgentGuide(dir: string): string[] {
+  writeFileSync(join(dir, 'AGENTS.md'), renderAgentGuide());
+  writeFileSync(join(dir, 'CLAUDE.md'), CLAUDE_MD);
+  return ['AGENTS.md', 'CLAUDE.md'];
+}