create-substrat 0.11.9 → 0.12.1

package/index.js

@@ -36,12 +36,12 @@ 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.149.0';
-const ENGINE_WORKORDER = '^0.12.33';
-const ENGINE_INVOICING = '^0.11.33';
+const SUBSTRAT = '^0.151.0';
+const ENGINE_WORKORDER = '^0.12.35';
+const ENGINE_INVOICING = '^0.11.35';
 const BOUNDARY_LINT = '^0.8.0';
-const DEV_ISSUER = '^0.2.31';
-const ATTACHMENT_EXTRACTORS = '^0.2.10';
+const DEV_ISSUER = '^0.2.33';
+const ATTACHMENT_EXTRACTORS = '^0.2.12';
 
 const DOCS = 'https://substrat.net';
 

package/package.json

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

package/template/.substrat/playbook.md

@@ -163,7 +163,7 @@ stop. Do not scaffold.
 ## Step 3 — Write the design document
 
 **This is the deliverable.** Everything before now was learning; this is where it lands
-somewhere the user can hold. Write a **checked-in `spec/concept.md`** — beside
+somewhere the user can hold. Fill in the **checked-in `spec/concept.md`** (the scaffold ships it) — beside
 `spec/model.ts`, which is this same design one rung more concrete — in the user's own
 vocabulary — no Substrat internals, no decision refs, no cross-references to
 platform docs. Someone who has never heard of Substrat must be able to read it and recognise
@@ -175,6 +175,12 @@ their own business.
 Status: draft v0.1 · Last updated: <date> · For review before any code
 ```
 
+**The layout is fixed by the scaffold**: keep its seven headings and the `substrat:` markers —
+purpose and users, roles and permissions, entity model, processes, screens and dashboard,
+decisions log, open questions. Roles, entities and processes are generated from the code
+(Step 5); what follows describes the authored parts, and the denials preview below is prose that
+sits beside the generated roles table, not instead of it.
+
 **The template** — the coverage map (Step 2) is sections 3–4, already done; the rest is the
 interview written down. Two sections deliberately *preview* the code checkpoints of Step 7 in
 plain language, so nothing there is a surprise:
@@ -248,6 +254,19 @@ say so rather than letting them wave it through — a design nobody understands
 reproduces exactly the failure Substrat exists to prevent. Iterate the document until they
 can, and only then take explicit approval.
 
+**A change to a vertical that already has a `model.json`** goes through this same gate, and what
+the gate shows is the **concept delta**, not prose. Declare the change in `spec/model.ts` and
+its roles only — no handler, no screen — re-emit the artifacts, and run `substrat plan`. It
+prints the entities added, changed and removed (the model before and after), the lifecycle
+changes with the operation that triggers each transition, the permission-diff table, the
+spec-version impact (patch / minor / major, from the same classifier `substrat changeset`
+uses), and the decisions-log entry approval would write. Show it to the user as printed, walk
+them through it in their vocabulary, and **stop**. Only once they approve, run the
+`substrat plan --approve <digest> --by "<their name>" --why "<their reason>"` line it printed:
+that records the approval in the Decisions log of `spec/concept.md`. Never run `--approve`
+on your own judgement, and if the model moves after they read it, show the delta again — the
+old digest is refused.
+
 Approval of the design is what unlocks Step 5. Until you have it, you are still in design.
 
 ---
@@ -312,6 +331,19 @@ and event subjects all need one id, so naming such an entity in `parents`,
 compile error. It is still a full model member with migrations and a row type. A
 single-column key that is not called `id` stays fully pointable.
 
+**Run `substrat concept sync` after every change to the model.** It reads `model.json` beside
+`package.json`, which a scaffold does not write for you: write the exported model there
+(`JSON.stringify(<your emitModel result>, null, 2)`) first. Sync then rewrites the entity and
+process regions of `spec/concept.md` between the `<!-- substrat:entities -->` and
+`<!-- substrat:processes -->` markers (a Mermaid ER diagram, and one state diagram per lifecycle).
+The roles region is filled from a `PERMISSIONS.md` beside `model.json`; a scaffold has no command
+that writes one, so until it does the region says so and the roles live in your own prose. Never
+edit between the markers by hand, and run `substrat concept sync --check` before you hand the
+design over: it exits 1 while a region is stale. **Write the decisions-log entry yourself**, in
+the document's *Decisions log* section on every change to the model or a permission: the date,
+what changed, and why. No tool in a scaffold enforces it, so the reviewer reading the diff is the
+gate.
+
 Behaviour stays prose in `spec/concept.md`. Inventing a way to declare a state *transition*
 means the boundary slipped.
 

package/template/spec/concept.md

@@ -0,0 +1,40 @@
+Status: draft v0.1 · Last updated: <date> · For review before any code
+
+# <The name of the thing you are building>
+
+This is the readable description of the app, for the people who own it. Three sections are
+written by `substrat concept sync` from the code (entity model and processes from `model.json`;
+roles from a `PERMISSIONS.md` beside it, when there is one) and the rest by hand. Do not edit
+between the `substrat:` markers: the next sync overwrites it, and `substrat concept sync --check`
+exits 1 while one is stale.
+
+## 1. Purpose and users
+
+_Authored. Who this is for, what it does, in their words._
+
+## 2. Roles and permissions
+
+<!-- substrat:roles -->
+<!-- /substrat:roles -->
+
+## 3. Entity model
+
+<!-- substrat:entities -->
+<!-- /substrat:entities -->
+
+## 4. Processes
+
+<!-- substrat:processes -->
+<!-- /substrat:processes -->
+
+## 5. Screens and dashboard
+
+_Authored. What each person sees first, and what the dashboard answers._
+
+## 6. Decisions log
+
+_Authored, appended on every change to the model or to a permission: the date, what changed, and why._
+
+## 7. Open questions
+
+_Authored. What is not decided yet, and who decides it._

package/template/src/server.ts

@@ -3,6 +3,7 @@ import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { serve } from '@hono/node-server';
 import { Hono } from 'hono';
+import { invocationLog } from '@substrat-run/vertical-host';
 import type { Context } from 'hono';
 import { HTTPException } from 'hono/http-exception';
 import { platformActorId } from '@substrat-run/contracts';
@@ -71,6 +72,10 @@ const login = devLogin({
 });
 
 const app = new Hono();
+// The request's stamp: an id on every response (`x-substrat-request-id`) and, under
+// `substrat dev`, the HTTP half of its trace. FIRST, so it wraps every route below. Bare on
+// purpose: no router fronts this server, so there is nothing to verify and no line to write.
+app.use('*', invocationLog());
 
 // Login, callback, logout. Accounts and passwords live at the issuer; this vertical
 // runs no credential store of its own.