Prepare release 0.2.1 (#36)

Author: jmclaughlin724

.agents/prompts/supaschema-install.md

@@ -0,0 +1,90 @@
+# supaschema Agent Install Prompt
+
+Use this prompt when an AI agent is asked to install, initialize, inspect, or use supaschema in a consuming project.
+
+## Role
+
+You are working in the consuming project, not in the supaschema source repository.
+
+Do not clone `jmclaughlin724/supaschema` into the project, run `npm ci` in a nested supaschema checkout, or validate supaschema by running its internal fixture suite unless the user explicitly asks you to develop supaschema itself. For normal use, install the npm package in the target project and work from that project root.
+
+## Install Command
+
+If supaschema is not installed, run this from the project root:
+
+```bash
+npm install supaschema
+```
+
+If install scripts did not run, or setup needs to be repaired, run:
+
+```bash
+npx supaschema init
+```
+
+Use `npx supaschema init --dry-run` when you need to preview setup before writing files.
+
+## What Install Provides
+
+The npm package provides:
+
+- the `supaschema` CLI and typed ESM library exports;
+- PostgreSQL parser/deparser runtime dependencies;
+- `supaschema-config.schema.json` for editor and config validation;
+- the shared agent prompt at `.agents/prompts/supaschema-install.md`;
+- the supaschema workflow skill at `.agents/skills/supaschema/SKILL.md`;
+- Claude rule, skill, and hooks under `.claude/`;
+- Codex rule, skill, hook scripts, and hook registration under `.codex/`.
+
+Public docs and examples are hosted in the supaschema documentation and source repository. They are not part of the normal `node_modules/supaschema` install payload, and you should not clone the source repository just to read them during consumer setup.
+
+The installer or `supaschema init` writes or merges these project files:
+
+- `supaschema.config.json` when the project does not already have one;
+- configured schema and migration directories;
+- `.supaschema/install.json` with detected paths and install metadata;
+- `AGENTS.md` and `CLAUDE.md` managed supaschema guidance blocks;
+- `.agents/prompts/supaschema-install.md`;
+- `.agents/skills/supaschema/SKILL.md`;
+- `.claude/rules/supaschema.md`, `.claude/skills/supaschema/SKILL.md`, and the three supaschema Claude hooks;
+- `.claude/settings.json` hook wiring;
+- `.codex/rules/supaschema.rules`, `.codex/skills/supaschema/SKILL.md`, the three supaschema Codex hooks, and `.codex/hooks.json`.
+
+Install does not edit schema files, generate migrations, connect to a database, apply migrations, install maintainer editor/MCP/FastMCP tooling, or copy supaschema source/test infrastructure into the consumer project.
+
+## First Tasks After Install
+
+1. Read the supaschema managed block in `AGENTS.md` or `CLAUDE.md`.
+2. Read `.agents/skills/supaschema/SKILL.md` and the matching rule file for the active agent runtime: `.claude/rules/supaschema.md` or `.codex/rules/supaschema.rules`.
+3. Inspect `supaschema.config.json` and `.supaschema/install.json`.
+4. If `.supaschema/install.json` has `pathConfirmationNeeded: true`, stop before diffing. Ask the user which detected schema and migration paths to use, then update `supaschema.config.json`.
+5. Run `npx supaschema --version`.
+6. Run `npx supaschema config validate --json` after config exists or paths are confirmed.
+
+## Schema Change Workflow
+
+For schema changes, edit only the configured declarative SQL tree from `schemaPaths`. Then run:
+
+```bash
+npx supaschema diff
+npx supaschema check
+```
+
+If installed hooks are trusted and fire after a schema-tree write, treat their returned migration name or `SUPA_*` diagnostic as authoritative. If they do not fire, run the commands manually.
+
+Generated migrations containing `-- supaschema: lineage` are artifacts. Do not hand-edit them; change the schema tree and regenerate.
+
+Do not run `npx supaschema sync --local` or `npx supaschema sync --remote` unless the user explicitly asks to apply migrations.
+
+## Completion Report
+
+When reporting installation or setup, summarize:
+
+- package install or `init` command used;
+- whether config exists and which schema/migration paths are configured;
+- whether path confirmation is pending;
+- `npx supaschema --version` result;
+- `npx supaschema config validate --json` result or why it was not run;
+- the next schema-change command.
+
+Do not include internal supaschema source checkout details, internal fixture diff output, or package development test output unless the user asked to work on supaschema itself.

.agents/skills/supaschema/SKILL.md

@@ -15,6 +15,8 @@ When the bundled PostToolUse hook is wired (`.claude/settings.json` / `.codex/ho
 
 The normal consumer setup is one package install: `npm install supaschema`. Treat `supaschema.config.json`, installed schema/migration directories, Claude/Codex rule and skill files, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addenda as the package-owned setup surface.
 
+If this skill was installed through `npx skills`, treat it as portable workflow context only. Agent Skills installs `SKILL.md`-based folders; it does not create `supaschema.config.json`, schema/migration directories, passive rule files, hook scripts, or hook registration. To install those project enforcement surfaces, run `npm install supaschema` from the consuming project root. If the package is already present but lifecycle scripts did not run, run `npx supaschema init` from the same root. The npm scaffold installs the rule and hooks; the `npx skills` lane does not.
+
 Before the first schema edit, check `.supaschema/install.json` if it exists. If it says `"pathConfirmationNeeded": true`, inspect its candidate `schemaPaths` and `migrationsDirs`, ask the user which `schemaPaths`, `sources.to`, and `migrationsDir` to use, update `supaschema.config.json`, then run the workflow. Do not generate a migration from a guessed path; the bundled hooks also skip auto-diff until all three fields are explicit.
 
 Use the configured `schemaPaths`, `sources`, and `migrationsDir` as the source of truth. Do not create a parallel schema tree, a second migrations directory, or a new config unless the user explicitly asks to change project layout.

.claude/rules/00-supaschema.md

@@ -4,6 +4,23 @@ description: Compatibility pointer for the canonical supaschema migration policy
 
 # Rule 00 — supaschema Policy Pointer
 
+## Contract
+
+This numbered file exists only to preserve rule-citation compatibility. The canonical migration policy owner is `.claude/rules/supaschema.md`.
+
+
 The canonical owner is `.claude/rules/supaschema.md`.
 
 This numbered file exists only for rule-citation compatibility. Do not add migration policy here; update `.claude/rules/supaschema.md` and keep `.codex/rules/supaschema.rules` as a Codex-native pointer to that owner.
+
+## Verification
+
+When migration policy changes, update `.claude/rules/supaschema.md`, then keep this file as a pointer only and run the rule/context sync check that applies to the repo.
+
+## Failure behavior
+
+Do not add unique migration policy here. Move any new policy to `.claude/rules/supaschema.md` and keep Codex pointers aligned.
+
+## Done means
+
+This file remains a compatibility pointer and contains no unique migration policy.

.claude/rules/01-operating-rules.md

@@ -1,6 +1,15 @@
+---
+description: Repo operating discipline: STOP gates, enforcement, technical decisions, npm-only package manager, and closeout behavior.
+---
+
 # Rule 01 — Operating rules
 
-The non-negotiable working agreement for any agent or contributor in this repo. The standing rules live in the root `AGENTS.md` and the per-concern files under `.claude/rules/`; this file states the operating discipline that governs how all of them are applied.
+## Contract
+
+This rule owns the repo-wide operating discipline that applies every other rule: gates are real, technical decisions are evidence-based, npm is the only package manager, and no standard ships without an executable enforcement path.
+
+
+The non-negotiable working agreement for any agent or contributor in this repo. Standing rules live in the per-concern files under `.claude/rules/`; `AGENTS.md` is the root route map that points agents to those owners.
 
 ## Hard rules
 
@@ -11,7 +20,7 @@ The non-negotiable working agreement for any agent or contributor in this repo.
 - **Stay inside the governed toolchain** (Rules 04/06/08): navigate and refactor via cclsp; format and lint with the one owner per concern — `ruff` for Python, Biome via Ultracite for JS/TS/JSON/CSS/HTML/GraphQL; analyze code structure with an AST, never ad hoc regex (Rule 07).
 - **Use Code Atlas for repo-wide graph claims** (Rule 10): build and query the atlas before broad owner, route, consumer, dependency, DB, API, worker, generated-surface, or rollout assertions, then prove exact behavior with cclsp and direct source reads.
 - **Keep agent surfaces synchronized.** After changing one of the six mirrored skills (`code-atlas`, `fastmcp`, `fastmcp-client-cli`, `supaschema`, `ultracite`, `upstream`), run `npm run sync:llm` so the `.codex/skills` and `.agents/skills` mirrors stay byte-identical to their `.claude/skills` owners (Rule 12). Codex hooks stay native; Codex rule files should hold executable command policy or short pointers to canonical rule owners, not duplicated long-form policy.
-- **Operator and agent guidance lives in `AGENTS.md` and `.claude/rules/`;** `README.md` is the npm package landing page and `docs/` is the Mintlify site. The published npm package boundary is the `package.json` `files` allowlist (Rule 13).
+- **Durable operator policy lives in `.claude/rules/`, not `AGENTS.md`.** `AGENTS.md` is a concise repo map and rule index; `README.md` is the npm package landing page and `docs/` is the Mintlify site. The published npm package boundary is the `package.json` `files` allowlist (Rule 13).
 - **The package manager is npm.** Never introduce pnpm, yarn, or an alternate lockfile; preserve `package-lock.json`. There is no Turborepo, no workspaces, and no `apps/` in this single-package repo.
 - **Commit only when asked; branch off the default branch first;** let lefthook run (never `--no-verify`).
 
@@ -20,3 +29,24 @@ The non-negotiable working agreement for any agent or contributor in this repo.
 - `npm run guard` (`scripts/guards/check-all.mjs`) is the umbrella gate — tooling stack, agent hooks, agent-surface parity, rule-citation integrity, dependency catalog, Code Atlas, LSP coverage, FastMCP surface, and no-regex-in-scripts. lefthook (`pre-commit` runs Biome on staged files; `pre-push` runs `npm run typecheck` + `npm run guard`) and the PreToolUse/PostToolUse hooks enforce in-loop.
 
 STOP if any STOP condition in `.claude/rules/*` is skipped, a guard or test is weakened instead of its cause being fixed, a standard ships without an executable enforcement path, the package manager is switched away from npm, or a technical decision ships on a guess when an authoritative upstream source was available.
+
+## Verification
+
+Run the narrowest command that proves the touched rule, then the umbrella gate when rule, hook, package, migration, toolchain, or CI behavior changed.
+
+Required closeout checks when this rule or a cross-cutting rule changes:
+
+```bash
+npm run guard
+npm run typecheck
+```
+
+`npm run guard` must finish with `ALL_GUARDS_OK`.
+
+## Failure behavior
+
+If any gate fails, fix the underlying cause and rerun the failed command. Do not weaken, disable, skip, comment out, baseline, or bypass a guard, test, hook, assertion, or STOP condition to make the run green.
+
+## Done means
+
+Every accepted instruction has a disposition: resolved with evidence, not applicable with evidence, or blocked by a concrete external constraint after investigation. Deferral and future cleanup are not closeout states.