> ## Documentation Index
> Fetch the complete documentation index at: https://supaschema.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Bundle

> What the installed supaschema agent bundle provides for Claude, Codex, and AGENTS-compatible tools.

The agent bundle gives coding agents the same migration workflow that humans use: edit declarative SQL, generate with `diff`, check replay safety, and never hand-edit generated migration files.

`supaschema init` installs the package-owned enforcement bundle by default. The raw files also ship under `node_modules/supaschema/agent-bundle/` so agents can audit or repair files that init reported as skipped and read the complete public MDX documentation offline.

## Installed surfaces

The downloadable consumer agent bundle is intentionally narrow. Init installs only these package-owned surfaces and hook registrations; it does not copy maintainer-only tooling or write `AGENTS.md` / `CLAUDE.md`.

| Surface               | Files                                                                                                           |
| --------------------- | --------------------------------------------------------------------------------------------------------------- |
| Offline documentation | `agent-bundle/docs/index.md`, `agent-bundle/docs/**/*.mdx`                                                      |
| Shared install prompt | `agent-bundle/agents/prompts/supaschema-install.md`                                                             |
| Skills manifest       | `agent-bundle/skills-manifest.json` with the single `supaschema` skill                                          |
| Shared skill          | The recursive `agent-bundle/agents/skills/supaschema` directory, including its workflow references              |
| Claude skill and rule | The recursive `agent-bundle/claude/skills/supaschema` directory, plus `agent-bundle/claude/rules/supaschema.md` |
| Claude hook settings  | `agent-bundle/claude/settings.<manager>.json`                                                                   |
| Codex rule mirror     | `agent-bundle/codex/rules/supaschema.rules`                                                                     |
| Codex hook settings   | `agent-bundle/codex/hooks.<manager>.json`                                                                       |

## Install and repair

Run `supaschema init` after package install. It reads the packaged manifest, recursively copies missing Agent and Claude skill files, merges package-manager-specific `.claude/settings.json` and `.codex/hooks.json`, preserves and reports existing non-identical files, and reports skipped non-mergeable hook config. It never creates `.codex/skills/**`. Read `node_modules/supaschema/agent-bundle/INSTALL.md` when auditing the installed files or repairing skipped surfaces.

For offline product documentation, open `node_modules/supaschema/agent-bundle/docs/index.md`. Its entries are sorted package paths linked to their canonical `https://supaschema.com/docs/...` URLs. The MDX files are byte-for-byte projections of the hosted-doc sources; images, `docs.json`, and non-MDX files do not ship, and init does not scaffold the corpus.

The default scaffold does not run `npx skills`; npm package init is the activation path for project enforcement.

Supabase projects that already carry a `_bootstrap` schema inventory or a `supabase/AGENTS.md` owner brief marking `supabase/schemas/**` as non-generator inventory still receive `supaschema.config.json` from the detected Supabase paths. In that profile, `workflow.schema_diff` and `workflow.migration_sync` are set to `manual`, Supabase-managed schemas are added to `schemas.exclude`, and schema-source readers skip `_bootstrap` directories. When path ownership is genuinely ambiguous, `.supaschema/install.json` records detected candidates plus `agentInstructions`, and zero-source `diff` / zero-arg `check` stay blocked until `supaschema.config.json` names the real `schemaPaths` and `migrationsDir`.

If the consumer repo has `AGENTS.md` or `CLAUDE.md`, those files remain consumer-owned. Point them at `.agents/prompts/supaschema-install.md` only when the project wants that root routing.

## npx skills lane

The public `npx skills` source is intentionally narrower than the npm setup surface. Install the single curated directory:

```bash theme={null}
npx skills add https://github.com/jmclaughlin724/supaschema/tree/main/skills/supaschema
```

Do not use the repository root as the Skills source. The Skills CLI scans standard agent skill directories; the public source contains only that one curated directory.

The skill mirrors the canonical `.claude/skills/supaschema` tree, including its `references/` workflow guides for setup, migration, maintenance, and diagnostics. It installs Agent Skill context only into the location selected by the Skills CLI. It does not install rule files, hook scripts, hook registration, config, or schema directories.

Rules and hooks are included in the package bundle and activated by `supaschema init`.

## Hook behavior

The installed hooks are limited to Supaschema schema and migration behavior:

| Hook                                       | Event         | Purpose                                                                                                                                                                                                                                         |
| ------------------------------------------ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `supaschema hook generated-migration-edit` | `PreToolUse`  | Blocks edits to generated migration SQL when the lineage marker is present.                                                                                                                                                                     |
| `supaschema hook schema-write`             | `PostToolUse` | Watches schema-tree SQL writes. By default it runs `supaschema diff` then checks the generated migration files; when config enables automatic sync and exactly one selected target is resolved and approved, it delegates to `supaschema sync`. |

The bundle does not publish or register this repository's general Bash, Git, secret, branch, worktree, or deletion policy. Those guards are maintainer tooling for developing Supaschema itself.

`supaschema hook schema-write` triggers the default migration workflow after configured schema files are edited. It writes the migration when `workflow.schema_diff` is `"on_schema_write"` and runs the replay-safety check on those generated migration paths when `workflow.migration_check` is `"after_schema_diff"`. If `workflow.migration_sync` allows automatic sync, the hook first confirms exactly one selected `sync.targets` entry is `mode: "auto"`, its database URL reference resolves when its runner needs one, and any remote target has its configured approval variable set. Only then does it call `supaschema sync`, which owns the ordered source, diff, target-selection, history, check, generated-contract, schema-closure staging, source safety, runner, and reconciliation workflow.

If config or approval does not permit automatic sync, the hook stays on the non-mutating diff/check lane. If `check` or `sync` fails, the hook emits continuation feedback so Claude or Codex investigates the root source, searches for correlated migration failures, fixes the canonical owner, and reruns the failing command.

## Repo-local tooling

Maintainer Claude/Codex optimization infrastructure is not part of the public repository, npm package, or install scaffold by default.

Keep these private unless the consumer contract explicitly changes:

* `.claude/hooks/context-*`
* `.codex/hooks/context-*`
* optimizer skills
* internal rules
* `.claude/agents/**`
* `.codex/agents/**`
* `.codex/config.toml`
* MCP config
* advisor plans
* operator services

If one of these surfaces becomes part of the consumer contract, update the package allowlist, scaffold, package tests, and [Package Boundary](/docs/reference/package-boundary) in the same change.