@classytic/arc 2.20.0 → 2.21.0

package/skills/arc-module-publishing/references/authoring-modules.md

@@ -0,0 +1,272 @@
+# Authoring: presets, plugins, and modules
+
+The three shapes a package exports, smallest surface first. All import arc through public
+subpaths only (`@classytic/arc/{permissions,scope,types,utils,factory,testing}`).
+
+---
+
+## Shape 1 — Action preset (add verbs to one resource)
+
+The smallest reusable unit: a function returning an `actions:` slice the host spreads into a
+resource. No lifecycle, no engine. Storage-agnostic via a **structural repository port** — an
+interface listing only the methods you call, satisfied by any kit repository without importing
+the kit.
+
+```ts
+import type { PermissionCheck } from "@classytic/arc/permissions";
+import { getOrgId, getUserId } from "@classytic/arc/scope";
+import type { ActionDefinition, RequestWithExtras } from "@classytic/arc/types";
+import { createDomainError, NotFoundError } from "@classytic/arc/utils";
+
+// Structural port — NOT a kit import. Any kit repo with these methods satisfies it.
+export interface SubjectRepository<TDoc> {
+  getById(id: string, o: { organizationId?: string; throwOnNotFound: false; lean: true }): Promise<TDoc | null>;
+  update(id: string, patch: Record<string, unknown>, o: { organizationId?: string; lean: true }): Promise<TDoc | null>;
+}
+
+export interface WithXConfig<TDoc> {
+  readonly repository: SubjectRepository<TDoc>;
+  readonly permissions: { readonly act: PermissionCheck };
+  // ...host policy injected here: resolvers, side-effect hooks, tenancy mode
+}
+
+export function withX<TDoc>(config: WithXConfig<TDoc>): Record<"do_x", ActionDefinition> {
+  return {
+    do_x: {
+      handler: async (id, data, req) => handler(config, id, data, req),
+      permissions: config.permissions.act,
+      description: "…",
+      schema: { type: "object", /* JSON Schema */ additionalProperties: false },
+    },
+  };
+}
+```
+
+Host composes it:
+
+```ts
+defineResource({
+  actions: {
+    ...withX({ repository, permissions, /* host policy */ }),
+    post: { /* subject-specific verbs stay here */ },
+  },
+});
+```
+
+**Rules that make a preset reusable:**
+- Inject **all policy** through config (permissions, resolvers, side-effect hooks). The preset
+  contributes *mechanism*; the host owns *policy*.
+- Take a **structural port**, never a concrete kit type. `SubjectRepository<TDoc>` with the two
+  methods you use — not `MongooseRepository`.
+- Read tenant/user via `getOrgId(req.scope)` / `getUserId(req.scope)`, never off `req.user`
+  directly. Honor a `tenancy: "required" | "off"` config so single-tenant hosts work too.
+- Ship schemas as **JSON Schema**. Map any domain errors to arc's `createDomainError(code, msg,
+  status)` so the wire contract stays consistent.
+- Model a **mode/source as a discriminated field, not a boolean flag**. `source: 'literal' |
+  'policy' | 'auto'` beats `useMatrix: boolean`: it's extensible (a third mode is a new enum
+  member, not a second conflicting flag), self-documenting, and makes contradictory inputs
+  (a literal payload sent with `source: 'policy'`) rejectable instead of silently dropped. If a
+  published boolean already exists, keep it as a `@deprecated` alias that bridges to the field
+  for one minor, then remove — don't strand consumers on a hard rename.
+
+---
+
+## Shape 2 — Plugin (cross-cutting decorator/hook)
+
+An `fp()`-wrapped Fastify plugin — the one documented exception to arc's no-default-exports
+rule. Ship **both** a default (for `app.register(import(...))`) and a named export.
+
+```ts
+import fp from "fastify-plugin";
+import type { FastifyInstance } from "fastify";
+
+async function xPlugin(app: FastifyInstance /*, opts */): Promise<void> {
+  app.decorate("x", createX(/* ... */));
+  // Set response headers at onRequest or preSerialization — NEVER onSend (races Fastify's flush).
+}
+
+export const x = fp(xPlugin, { name: "arc-x", fastify: "5.x" });
+export default x;   // fp() plugin entries MAY default-export (arc convention exception)
+```
+
+Host registers it in the `plugins:` slot or via `app.register`. If the plugin belongs to a
+domain module, register it in the module's `plugins` lifecycle slot instead (below).
+
+---
+
+## Shape 3 — Module (a whole domain as one value)
+
+Use `defineModule` when there's engine state to boot **and** multiple resources to register as
+a unit. The host lists it in `createApp({ modules: [...] })`; arc expands it into the same
+lifecycle phases a hand-wired app uses.
+
+```ts
+import { defineModule, getModuleExports } from "@classytic/arc/factory";
+import type { FastifyInstance } from "fastify";
+
+export interface AccountingEngine { post(entry: Entry): Promise<void>; }
+export interface AccountingDeps { permissions: PermissionMatrix; }
+
+// Factory takes host deps, returns an ArcModule. TExports inferred from bootstrap's return.
+export const accountingModule = (deps: AccountingDeps) =>
+  defineModule({
+    name: "accounting",                 // namespaced, unique across the host — the graph key
+    dependsOn: ["ledger"],              // composition order (see below), NOT lazy loading
+
+    plugins: (f) => {                   // register infra — runs after app plugins(), before bootstraps
+      f.register(/* db conn, sse, etc. */);
+    },
+
+    bootstrap: async (f) => {           // init engine — its return becomes the PUBLIC EXPORT
+      const ledger = getModuleExports<LedgerEngine>(f, "ledger"); // guaranteed live (dependsOn)
+      return createAccountingEngine(deps, ledger);                // → fastify.arc.modules.accounting
+    },
+
+    resources: (f) => {                 // factory form runs AFTER all bootstraps — engines are live
+      const engine = getModuleExports<AccountingEngine>(f, "accounting");
+      return [accountsResource(engine, deps.permissions), entriesResource(engine)];
+    },
+
+    afterResources: (f) => { /* cross-resource event subscriptions the module owns */ },
+    onClose: (f) => { /* stop timers, flush outbox, destroy engine */ },
+  });
+```
+
+### Lifecycle phases (module runs before app-level in each)
+
+```
+plugins        = app plugins()          → modules' plugins        (infra registration)
+bootstrap[]    = modules' bootstrap      → options.bootstrap       (engine init + export)
+resources[]    = modules' resources      → options.resources        (module routes register first)
+afterResources = modules' afterResources → options.afterResources
+onClose        = modules' onClose (REVERSE order) → options.onClose  (last composed, first closed)
+```
+
+A module's engine is live before app-level bootstrap; app `afterResources` can wire across
+modules; teardown mirrors init in reverse.
+
+### `dependsOn` is composition order, not lazy loading
+
+`dependsOn: ["ledger"]` guarantees ledger's `plugins`/`bootstrap` (and thus its public export)
+run **before** this module's — so `getModuleExports(f, "ledger")` is live. It does **not** delay
+*importing* the module. Every module input (including dynamic-import thunks) is resolved up
+front via `Promise.all`, then `dependsOn` orders the *composition*. It's a **stable topological
+sort**: modules with no edge between them keep list order, so adding `dependsOn` never silently
+reorders an unrelated module. Fail-fast at boot on unknown dep, self-reference, and cycles.
+
+### Cross-module wiring — `getModuleExports`, not a container
+
+A module's `bootstrap` return value is its **public export**, recorded at
+`fastify.arc.modules[name]`. Later modules read it with the typed accessor — no DI container,
+no proxy. For inferred types without an inline generic, augment the registry once:
+
+```ts
+declare module "@classytic/arc/factory" {
+  interface ArcModuleRegistry {
+    accounting: AccountingEngine;
+    ledger: LedgerEngine;
+  }
+}
+// then: getModuleExports(f, "accounting") infers AccountingEngine
+```
+
+`getModuleExports` **throws** (fail-fast) if the name isn't composed, is composed after the
+caller, or returned nothing — all wiring bugs that must surface at boot, not as `undefined`
+downstream.
+
+### Lazy / region packs — thunk of a dynamic import
+
+To gate *whether* a module is imported at all (region/tier packs), pass a thunk that returns a
+dynamic import. Only the selected pack enters the bundle path:
+
+```ts
+const taxPack =
+  region === "BD"
+    ? () => import("@classytic/bd-tax").then((m) => m.createBdTaxModule(deps))
+    : () => import("@classytic/us-tax").then((m) => m.createUsTaxModule(deps));
+
+await createApp({ modules: [coreModule(deps), taxPack] });
+// only the selected tax package is imported + composed
+```
+
+Thunk = *whether to import*; `dependsOn` = *order of already-selected modules*. Different tools.
+
+### One module per package
+
+A package exports **one** `createXModule` factory. To compose several domains, publish several
+packages (or several subpath exports) and let the host list them — don't return an array of
+modules from one factory. The host owns the flat `modules:` list and its ordering; keep that
+control theirs.
+
+---
+
+## Testing a package
+
+Boot a **real arc app** around your export and exercise it over HTTP — that's the only test
+that proves it *composes*. There are two harness layers, and the difference matters:
+
+| Harness | Persistence | Fidelity | Home |
+|---|---|---|---|
+| `@classytic/arc/testing` | none — you inject a repo (fake / `Map`-backed) | boot + wiring only | inside arc |
+| a **kit-backed testkit** (e.g. `@classytic/arc-testkit`) | real in-memory store (Mongo memory-server) | **prod-fidelity** | arc-ecosystem |
+
+**Why two layers, and why the testkit is kit-specific:** arc's non-negotiable rule is *no DB
+driver imports anywhere in arc*. So `@classytic/arc/testing` can boot the app but cannot give
+you real persistence — it hands you an injected/fake repository. A harness that persists for
+real **must** pick a concrete kit (mongokit + `mongodb-memory-server`, or sqlite in-memory).
+That's not a limitation to design around — it's the point: **a testkit's value is fidelity, so
+it should exercise the module the way it runs in production**, with the same adapter.
+
+**Don't "make the testkit DB-agnostic" by defaulting to a fake in-memory repo.** A `Map`-backed
+repo does not reproduce ObjectId-vs-string `_id`, `select`/projection semantics, query-operator
+translation, pagination cursor encoding, unique-index enforcement, or Mongoose strict-mode
+field dropping. A module that ships a real adapter will pass on the fake and break in prod — the
+test gets greener and less truthful. Agnostic *interface*, real *backend*:
+
+- **Agnostic seam:** the harness takes a **`TestBackend`** — `setup() → { ctx: { connection,
+  uri }, teardown }` — so the store is pluggable, not hard-wired.
+- **Real default, backend lives in the kit:** `@classytic/arc-testkit` is the thin generic core
+  (`bootModuleApp(modules, { backend })`); its default backend is `mongoMemoryBackend()` from
+  **`@classytic/mongokit/testkit`**, loaded via dynamic `import()` so mongokit +
+  `mongodb-memory-server` stay *optional* peers. This is the concrete "adapters/backends live in
+  their kits" split — mongokit owns the Mongo lifecycle, arc-testkit owns the arc boot. Add a
+  sibling (`@classytic/sqlitekit/testkit` → `sqliteMemoryBackend()`) only when a non-Mongo module
+  exists — YAGNI until the second consumer is real.
+
+```ts
+import { bootModuleApp } from "@classytic/arc-testkit";
+import { mongoMemoryBackend } from "@classytic/mongokit/testkit"; // only to override the default
+
+const t = await bootModuleApp(({ connection }) => [createOrderModule({ connection, permissions })]);
+// or point at a real cluster:  { backend: mongoMemoryBackend({ uri: process.env.ATLAS_TEST_URI }) }
+const res = await t.app.inject({ method: "GET", url: "/orders" });
+await t.close();
+```
+
+**Install contract (the part that bites on adoption):** because the harness declares its DB deps
+as *optional peers*, the consumer installs all three together —
+
+```bash
+npm i -D @classytic/arc-testkit @classytic/mongokit mongodb-memory-server
+```
+
+Miss `mongodb-memory-server` and the default backend throws at boot; pin `@classytic/mongokit`
+below the version that first shipped `/testkit` and the subpath won't resolve (a floating `^`
+range won't upgrade past a lockfile pin on its own — bump the devDep floor). This is the tradeoff
+of *not* bundling: the harness stays out of production, but the consumer owns the dev install.
+
+Whichever layer you use, cover these edges:
+
+- Boot a minimal app, register your preset/module, hit the routes with `app.inject`.
+- Test **both tenancy modes** (`required` and `off`) if you support them.
+- Avoid field names arc's query parser reserves (`page`, `limit`, `cursor`, `after`, `sort`,
+  `search`, `select`, `populate`) — a filter field colliding with one is silently unfilterable.
+  Arc emits a `filter-field-reserved-name` boot diagnostic; heed it. **This class of bug only
+  surfaces on a real backend** — another reason the fidelity harness earns its keep.
+- Pin devDeps at or above every peer floor so the suite exercises the version you promise.
+
+**Shared harness pattern:** the harness is published once — `@classytic/arc-testkit` (generic
+core, in the ecosystem repo, *not* a per-domain monorepo) + `@classytic/mongokit/testkit` (the
+Mongo backend, in the kit) — so every module author and third party reuses it. Depend on it via
+`devDependencies` (a version range from the registry; `workspace:*` only inside its own monorepo).
+"If your module boots green in the testkit, it composes" is the contract.

package/skills/arc-module-publishing/references/package-manifest.md

@@ -0,0 +1,155 @@
+# package.json + tsdown reference
+
+Copy-paste manifest for an arc ecosystem package, plus the dependency-field rules and the
+optional-peer typing pattern. Values below are the real shapes shipped by
+`@classytic/arc-approval` — adapt names, keep the structure.
+
+---
+
+## package.json
+
+```jsonc
+{
+  "name": "@classytic/arc-<domain>",
+  "version": "0.1.0",
+  "description": "<one line — what this contributes to an arc host>",
+  "type": "module",
+
+  // Public entry. Add subpaths ("./adapter", "./testing") the same way if you split surfaces.
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+
+  "sideEffects": false,       // pure ESM, tree-shakable — no import-for-effect modules
+  "files": ["dist"],          // ship only build output; never src/, tests/, configs
+  "publishConfig": { "access": "public" },
+  "engines": { "node": ">=22" },
+
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"
+  },
+
+  // CONTRACTS — what the host must provide. `>=`, never `^`.
+  "peerDependencies": {
+    "@classytic/arc": ">=2.20.0",
+    "@classytic/primitives": ">=0.9.0"
+  },
+
+  // Optional peers: declared here AND marked optional below. Host installs only if used.
+  // "peerDependencies": { ..., "zod": ">=3.23.0", "ioredis": ">=5.0.0" },
+  // "peerDependenciesMeta": {
+  //   "zod": { "optional": true },
+  //   "ioredis": { "optional": true }
+  // },
+
+  // TEST versions — pin with ^, floor >= each peer floor. Not shipped.
+  "devDependencies": {
+    "@classytic/arc": "^2.20.0",
+    "@classytic/primitives": "^0.9.1",
+    "@biomejs/biome": "^2.5.2",
+    "@types/node": "^22.19.21",
+    "tsdown": "^0.22.5",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.9"
+  },
+
+  "keywords": ["arc", "fastify", "<domain>", "classytic"],
+  "license": "MIT",
+  "author": "Classytic",
+  "repository": { "type": "git", "url": "https://github.com/classytic/arc-ecosystem.git", "directory": "packages/arc-<domain>" }
+}
+```
+
+In an **npm workspace**, devDeps common to all packages hoist to the root `package.json`; a
+package only lists devDeps unique to it. The peer-skew gate reads root + package devDeps
+together (see publishing-workflow.md).
+
+---
+
+## Dependency-field cheat sheet
+
+| Field | What goes here | Range style | Why |
+|---|---|---|---|
+| `dependencies` | (usually nothing) truly-private bundled helpers only | `^` | Ships with you; host can't override. Almost never needed. |
+| `peerDependencies` | arc, fastify, primitives, kits, zod, ioredis | **`>=`** | A contract/floor. Host resolves the real version; don't block their upgrades. |
+| `peerDependenciesMeta` | mark optional peers `{ optional: true }` | — | Host installs only if they use that path. |
+| `devDependencies` | concrete versions your tests run against | `^` | The version you actually exercise; floor must be `>=` peer floor. |
+
+**The trap:** putting `@classytic/arc` or `fastify` in `dependencies`, or writing a peer as
+`^2.20.0`. Both force the host into *your* version choice. A published arc package makes as
+few decisions for the host as possible — it states floors and gets out of the way.
+
+---
+
+## tsdown.config.ts
+
+```ts
+import { defineConfig } from "tsdown";
+
+export default defineConfig({
+  entry: ["src/index.ts"],   // add entries for extra subpaths: ["src/index.ts", "src/adapter.ts"]
+  format: ["esm"],           // ESM only — arc is ESM only
+  dts: true,                 // emit .d.mts
+  sourcemap: false,
+  clean: true,
+  treeshake: true,
+  target: "node22",
+  outDir: "dist",
+  deps: {
+    // Bundle NOTHING — same never-bundle contract as arc's own tsdown config.
+    skipNodeModulesBundle: true,
+    neverBundle: [/^@classytic\//],
+  },
+});
+```
+
+Why bundle nothing: if you inline `@classytic/arc` (or primitives, or a kit), the host ends up
+with two copies — yours frozen in `dist/`, theirs in `node_modules`. Arc's plugin registry,
+event transport, and scope decorators are identity-sensitive; two copies register twice and
+diverge. `neverBundle: [/^@classytic\//]` guarantees the host's single installed copy is the
+only one at runtime.
+
+---
+
+## Optional peers: keep their types out of your public surface
+
+If a peer is optional (a host might not install it), its types **must not** appear in your
+published `.d.mts` — otherwise a host without it gets a compile error importing your package.
+Use structural typing: describe the shape you need with a local interface, don't import the
+dependency's types into the public boundary.
+
+```ts
+// ❌ leaks zod into dist/index.d.mts — breaks hosts that didn't install zod
+import type { ZodType } from "zod";
+export function withValidation(schema: ZodType) { /* ... */ }
+
+// ✅ structural: the public signature owes nothing to zod's package
+export interface StandardSchemaLike<T> {
+  readonly "~standard": { validate: (v: unknown) => { value: T } | { issues: unknown[] } };
+}
+export function withValidation<T>(schema: StandardSchemaLike<T>) { /* ... */ }
+```
+
+For **shipped action/route schemas, use JSON Schema**, not zod objects. Arc converts JSON
+Schema natively; zod stays an *optional* convenience peer for hosts that prefer it. A package
+that hard-requires zod for its schemas has made zod a non-optional dependency by the back door.
+
+```ts
+schema: {
+  type: "object",
+  required: ["stepId", "decision"],
+  properties: {
+    stepId: { type: "string", minLength: 1 },
+    decision: { type: "string", enum: ["approved", "rejected"] },
+  },
+  additionalProperties: false,
+}
+```

package/skills/arc-module-publishing/references/publishing-workflow.md

@@ -0,0 +1,182 @@
+# Publishing workflow
+
+Monorepo layout, the release gates, and the classytic bot-identity publish steps.
+
+---
+
+## Monorepo layout (npm workspaces)
+
+Prefer **one workspace holding many small packages** over one repo per package — they release
+together and share tooling. The `@classytic/arc-ecosystem` layout:
+
+```
+arc-ecosystem/
+  package.json                 # workspaces: ["packages/*"], shared devDeps, verify script
+  scripts/
+    check-peer-skew.mjs        # gate: every peer floor covered by a devDep floor
+    prepublish-gate.mjs        # per-package publish gate
+  packages/
+    arc-approval/              # @classytic/arc-approval — one package, one surface
+      package.json
+      tsdown.config.ts
+      src/index.ts
+    arc-involvement/
+    arc-notifications/
+```
+
+Root `package.json` scripts:
+
+```jsonc
+{
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "npm run build --workspaces",
+    "typecheck": "npm run typecheck --workspaces",
+    "lint": "biome check packages/",
+    "test": "vitest run",
+    "check:peer-skew": "node scripts/check-peer-skew.mjs",
+    "verify": "npm run check:peer-skew && npm run typecheck && npm run lint && npm run test && npm run build"
+  }
+}
+```
+
+Shared devDeps (arc, primitives, biome, tsdown, typescript, vitest, fastify, @types/node) live
+in the **root** `package.json` so every package tests against one aligned set. During
+pre-publish development the root can carry `"@classytic/arc": "file:../arc"` to test against
+unreleased arc; **switch it to the published range (`"^2.20.0"`) once arc ships** and reinstall
+so packages resolve arc from the registry tarball, not the local symlink.
+
+**pnpm + turborepo + changesets** is the heavier-duty alternative to npm workspaces once the
+package count grows: turbo gives cached, topo-ordered builds (`dependsOn: ["^build"]`);
+changesets drive versioning + changelogs (`access: "public"`, `updateInternalDependencies:
+"patch"`). Wire the peer-skew gate into the release path so it can't be skipped — e.g.
+`"release": "pnpm run check:peer-skew && turbo typecheck test build && changeset publish"`.
+Local workspace links use `workspace:*` (pnpm) instead of `file:`; the peer-skew gate treats
+`workspace:` / `link:` / `file:` as covering any floor (the checked-out source *is* the version
+under development).
+
+### Supply-chain hygiene (.npmrc / pnpm-workspace.yaml)
+
+Belt-and-suspenders settings worth adopting for a published ecosystem:
+
+```ini
+# .npmrc
+auto-install-peers=false     # peers are the HOST's duty — never silently fetch them
+save-workspace-protocol=rolled
+```
+
+```yaml
+# pnpm-workspace.yaml
+onlyBuiltDependencies:       # allowlist packages permitted to run install scripts
+  - esbuild
+  - mongodb-memory-server
+minimumReleaseAgeExclude:    # cooldown on brand-new registry versions, with explicit escapes
+  - '@classytic/repo-core@0.7.0'
+```
+
+- `auto-install-peers=false` enforces the contract mechanically: if a host forgets a peer, they
+  get an error, not a silently-resolved wrong version. It also stops your *dev* environment from
+  masking a missing peer declaration.
+- `onlyBuiltDependencies` is a lifecycle-script allowlist — nothing runs `postinstall` unless you
+  named it. A cheap, real guard against a compromised transitive dep executing on `pnpm install`.
+- A `minimumReleaseAge` cooldown blunts the "malicious version published minutes ago" attack;
+  the `Exclude` list is your escape hatch for versions you've vetted.
+
+---
+
+## Gate 1 — peer-skew (monorepo)
+
+`scripts/check-peer-skew.mjs` fails the build if any package declares a peer floor higher than
+the devDep floor it actually tests against. Without it, a package can claim `">=2.20.0"` while
+its suite runs against 2.18 — a lie that ships. The gate reads root + package devDeps together
+(`file:` links count as covering any floor, since the link *is* the version under development).
+
+```js
+// Core check, per package, per peer:
+//   devFloor = floorOf(devDeps[name])         // from root + package devDeps merged
+//   peerFloor = floorOf(peers[name])
+//   if (devFloor < peerFloor) FAIL            // suite tests below what you promise
+// Optional peers (peerDependenciesMeta.optional) with no devDep are allowed to be absent.
+```
+
+Run it first in `verify` so a skew fails fast before the slower typecheck/test/build.
+
+---
+
+## Gate 2 — prepublish (per package)
+
+No package publishes without a green gate. No `--no-verify`, ever.
+
+- **Solo package:** `"prepublishOnly": "npm run typecheck && npm run lint && npm run test && npm run build"`.
+- **Workspace:** a shared `scripts/prepublish-gate.mjs` invoked from each package's
+  `prepublishOnly`, running the full workspace `verify` (peer-skew + typecheck + lint + test +
+  build) so no package ships against a skewed or broken tree.
+
+The gate is the contract with consumers: if it's green, the published `dist/` was typechecked,
+linted, tested, and built from the source in the same commit.
+
+---
+
+## Release — classytic packages (bot identity)
+
+Every commit in a classytic package is authored as **`classytic-bot[bot]`** — the maintainer
+identity, never an individual. **Per-invocation git env vars only; never `git config
+--global`; no `Co-Authored-By` trailers.**
+
+```bash
+GIT_AUTHOR_NAME="classytic-bot[bot]" \
+GIT_AUTHOR_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
+GIT_COMMITTER_NAME="classytic-bot[bot]" \
+GIT_COMMITTER_EMAIL="278929599+classytic-bot[bot]@users.noreply.github.com" \
+git commit -m "feat(arc-x): …"
+```
+
+Push through `@classytic/dev-tools` so the commit and pusher both carry the `[bot]` badge (it
+mints a short-lived GitHub App installation token, pushes, and never persists it):
+
+```bash
+npm run push -- main         # push current work to main
+```
+
+Publish to **public npm** (`publishConfig.access: "public"` is already set):
+
+```bash
+npm publish -w @classytic/arc-<domain>   # prepublishOnly gate runs automatically
+```
+
+Third-party (non-classytic) packages: normal git identity, same gates and same
+public/scoped-npm publish — only the bot identity and `classytic-push` are classytic-specific.
+
+---
+
+## Versioning a public export
+
+SemVer the **contract**, not the internals:
+
+| Change | Bump |
+|---|---|
+| New optional config field, new exported helper, new action | **minor** |
+| Raising a peer floor (e.g. now requires arc ≥2.21) | **minor** (it narrows the host set) |
+| Changing an exported function signature, removing an export, renaming an action/field | **major** |
+| Internal refactor, dep bump within range, doc/test-only | **patch** |
+
+The `ArcModule` shape you return, your exported function signatures, and your action/schema
+surface are the contract consumers pin against. Internals (private helpers, how the engine is
+built) are free to change under a patch.
+
+---
+
+## Common publish failures (and the fix)
+
+- **Peer written as `^` instead of `>=`** → blocks hosts on a newer major that still satisfies
+  your API. Fix: `">=X.Y.0"`.
+- **arc/fastify in `dependencies`** → host gets a bundled duplicate; plugin registry splits.
+  Fix: move to `peerDependencies`.
+- **Optional-peer types in `dist/*.d.mts`** → hosts without that peer fail to compile your
+  package. Fix: structural typing at the public boundary (see package-manifest.md).
+- **Deep import (`@classytic/arc/src/...`)** → breaks on any arc internal reorg. Fix: use a
+  public subpath, or file the missing export against arc.
+- **A back-edge: arc depending on your package** → un-publishable cycle. Fix: the abstraction
+  belongs in arc as a port/hook, not as a dependency on you.
+- **Skewed devDep below peer floor** → suite tests a version you claim to support but don't.
+  Fix: raise the devDep, reinstall, re-run peer-skew.