create-substrat 0.8.5 → 0.8.6

package/index.js

@@ -36,11 +36,11 @@ const TEMPLATE = join(HERE, 'template');
 // The runtime packages release together off one version line (the changesets `fixed`
 // group), so one constant is right for all of them. Engines do NOT share a line —
 // each versions on its own, so one pin per engine, deliberately.
-const SUBSTRAT = '^0.97.0';
-const ENGINE_WORKORDER = '^0.10.5';
-const ENGINE_INVOICING = '^0.9.13';
-const BOUNDARY_LINT = '^0.3.0';
-const DEV_ISSUER = '^0.1.12';
+const SUBSTRAT = '^0.98.0';
+const ENGINE_WORKORDER = '^0.10.6';
+const ENGINE_INVOICING = '^0.9.14';
+const BOUNDARY_LINT = '^0.4.0';
+const DEV_ISSUER = '^0.1.13';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-substrat",
-  "version": "0.8.5",
+  "version": "0.8.6",
   "description": "Scaffold a Substrat vertical — `npm create substrat <dir>`.",
   "license": "Apache-2.0",
   "repository": {

package/template/AGENTS.md

@@ -223,6 +223,21 @@ vertical done, boot the server and drive the real flow over HTTP as two personas
 should succeed and one who should be denied — and confirm the denial arrives as a denial
 (not a generic error).
 
+## When it breaks — symptom → fix
+
+Six failures that have each cost someone a day. What makes them expensive is that none of
+them names its own cause: the symptom points somewhere other than the fix, so an agent
+debugging from first principles walks away from the answer.
+
+| Symptom | Fix |
+|---|---|
+| `expected a Zod schema` at runtime, pointing nowhere useful | Two copies of Zod. Never add `zod` to `package.json` — import `z` from `@substrat-run/contracts`, so the schema you build and the one the host validates with are the same class. |
+| Killing the dev server kills unrelated ones too | `pkill -f 'tsx src/server.ts'` matches every Substrat project running on the machine, not just yours. Kill by port instead: `kill $(lsof -ti :<port>)`. |
+| Green locally, red in CI, with nothing in the diff that explains it | A warm build output hides it. Delete `dist`, reinstall from the lockfile (`--frozen-lockfile`), and re-run the gates before believing a local green. |
+| Green test suite, broken app | The scenario calls operations directly and never reaches `server.ts`, its routes, or the principal picker. Boot the server and drive the flow over HTTP as two personas — one who should succeed and one who should be denied. |
+| Permission denied after you widened a role | Roles are projected into a scope when that scope is provisioned, from `ROLES` in `src/provision.ts`. An existing scope keeps the projection it was born with — re-provision it (or re-seed onto a fresh data directory), then present the permission diff below. |
+| `pnpm install` dies compiling `better-sqlite3` | Take `better-sqlite3` out of `pnpm.onlyBuiltDependencies`. Since 13.x it ships prebuilt binaries and no install script, but it still ships a `binding.gyp` — so an allowlist entry makes pnpm run a `node-gyp rebuild` that nothing here needs. |
+
 ## Two human checkpoints — you may never self-approve
 
 Present these and stop: