create-ailk 0.1.1 → 0.2.0

package/templates/apps/web/lib/__tests__/site-theme.test.ts

@@ -0,0 +1,112 @@
+/**
+ * Round trip: the real `content/_site.mdx` → the emitted CSS custom properties.
+ *
+ * This is the end-to-end claim the wiring makes — a site declares a theme and
+ * the built page renders in those colours — asserted on the actual repo file
+ * rather than a fixture, so deleting the `theme:` block would fail here.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { PartialColorPaletteSchema } from "@working-theory/site-config/schema";
+import { siteColorTokenMap, themeToCssVarsBothModes } from "@working-theory/theme";
+
+import { loadSiteBrandTokens } from "../site-theme";
+
+const REPO_CONTENT_ROOT = join(__dirname, "..", "..", "..", "..", "content");
+
+/** The light-mode `:root { … }` block, without the dark one. */
+function lightBlock(css: string): string {
+  return css.slice(0, css.indexOf(':root[data-theme="dark"]'));
+}
+
+/** The dark-mode `:root[data-theme="dark"] { … }` block. */
+function darkBlock(css: string): string {
+  return css.slice(css.indexOf(':root[data-theme="dark"]'));
+}
+
+describe("loadSiteBrandTokens — the real content/_site.mdx", () => {
+  const originalRoot = process.env.AILK_CONTENT_ROOT;
+
+  beforeEach(() => {
+    process.env.AILK_CONTENT_ROOT = REPO_CONTENT_ROOT;
+  });
+
+  afterEach(() => {
+    if (originalRoot === undefined) delete process.env.AILK_CONTENT_ROOT;
+    else process.env.AILK_CONTENT_ROOT = originalRoot;
+  });
+
+  it("translates the declared theme into the token overlay", () => {
+    expect(loadSiteBrandTokens()).toEqual({
+      colors: {
+        light: { bg: "#fdfcfa", fg: "#1c1917" },
+        dark: { bg: "#0c0a09" },
+      },
+    });
+  });
+
+  it("reaches the emitted CSS custom properties", () => {
+    const brand = loadSiteBrandTokens();
+    const css = themeToCssVarsBothModes(brand ? { brand } : {});
+
+    expect(lightBlock(css)).toContain("--color-bg: #fdfcfa;");
+    expect(lightBlock(css)).toContain("--color-fg: #1c1917;");
+    expect(darkBlock(css)).toContain("--color-bg: #0c0a09;");
+  });
+
+  it("changes exactly the declared variables and nothing else", () => {
+    const brand = loadSiteBrandTokens();
+    const themed = themeToCssVarsBothModes(brand ? { brand } : {});
+    const expected = themeToCssVarsBothModes()
+      // light block — the two declared light colours
+      .replace("--color-bg: #ffffff;", "--color-bg: #fdfcfa;")
+      .replace("--color-fg: #030712;", "--color-fg: #1c1917;")
+      // dark block — the one declared dark colour
+      .replace("--color-bg: #0a0a0a;", "--color-bg: #0c0a09;");
+
+    expect(themed).toBe(expected);
+  });
+
+  it("treats a bare `theme:` key as no theme, rather than throwing", () => {
+    // YAML parses a dangling `theme:` to null. It is what commenting out the
+    // block's children leaves behind, it means the same as an absent key, and
+    // it must not escape as a ZodError out of an async Server Component.
+    const root = mkdtempSync(join(tmpdir(), "ailk-site-theme-"));
+    writeFileSync(
+      join(root, "_site.mdx"),
+      ["---", "siteName: Test", "theme:", "---", ""].join("\n"),
+      "utf8",
+    );
+    process.env.AILK_CONTENT_ROOT = root;
+
+    expect(loadSiteBrandTokens()).toBeUndefined();
+  });
+
+  it("returns undefined — and so emits the default CSS — when no config is readable", () => {
+    process.env.AILK_CONTENT_ROOT = join(__dirname, "no-such-content-root");
+
+    const brand = loadSiteBrandTokens();
+    expect(brand).toBeUndefined();
+    expect(themeToCssVarsBothModes(brand ? { brand } : {})).toBe(
+      themeToCssVarsBothModes(),
+    );
+  });
+});
+
+/**
+ * The twelve customer-facing colour slots live in `@working-theory/site-config`
+ * and the map from them to token names lives in `@working-theory/theme`;
+ * neither package may import the other, so nothing inside either can notice
+ * the two lists drifting. `apps/web` imports both, so the cross-check lives
+ * here — without it, a slot added to the palette schema would parse cleanly
+ * and then throw "is not a theme colour" at render.
+ */
+describe("the two vocabularies agree on which slots exist", () => {
+  it("siteColorTokenMap covers exactly the schema's colour slots", () => {
+    expect(Object.keys(siteColorTokenMap).sort()).toEqual(
+      Object.keys(PartialColorPaletteSchema.shape).sort(),
+    );
+  });
+});

package/templates/apps/web/lib/site-brand.tsx

@@ -55,8 +55,11 @@ interface SiteFrontmatter {
  * levels up from cwd — `apps/web` in dev/build, so `../../content` lands on
  * the site/scaffold root's `content/` directory. Duplicated locally because
  * that resolver isn't part of `@working-theory/page-renderer`'s public API.
+ *
+ * Exported so `lib/site-theme.ts` resolves the same root rather than keeping
+ * a third copy of this four-line rule.
  */
-function resolveContentRoot(): string {
+export function resolveContentRoot(): string {
   const override = process.env.AILK_CONTENT_ROOT;
   if (override && override.length > 0) return override;
   return join(process.cwd(), "..", "..", "content");

package/templates/apps/web/lib/site-theme.ts

@@ -0,0 +1,74 @@
+/**
+ * Site theme — reads the `theme:` block out of `content/_site.mdx` and
+ * translates it into the token overlay `themeToCssVarsBothModes` accepts.
+ *
+ * The read is a local frontmatter parse rather than
+ * `@working-theory/site-config/server`'s `loadSiteConfig`, for the same
+ * reason `site-brand.tsx` reads locally (see its header, and #4157 D1) and
+ * one more: `architecture.yaml` forbids `apps/web` from importing that
+ * subpath at all, because it pulls `node:fs` into a tree that also carries
+ * edge routes (#1567). The `theme:` block is still validated against the
+ * canonical schema — `SiteThemeSchema` from the package's client-safe
+ * `/schema` entry — so the shape this app accepts and the shape the
+ * dashboard will write are one definition, not two.
+ *
+ * The translation itself lives in `@working-theory/theme`
+ * (`siteThemeToBrandTokens`) — the token vocabulary is that package's own.
+ *
+ * Returns `undefined` when the site declares no theme, so the layout passes
+ * no `brand` at all and the resolver emits byte-for-byte the CSS it emitted
+ * before this wiring existed.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { SiteThemeSchema } from "@working-theory/site-config/schema";
+import {
+  siteThemeToBrandTokens,
+  type BrandTokenOverrides,
+} from "@working-theory/theme";
+import { parse as parseYaml } from "yaml";
+
+import { resolveContentRoot } from "./site-brand";
+
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---/;
+
+const SOURCE = "content/_site.mdx theme";
+
+/**
+ * The `theme:` value as it appears in the frontmatter, or `undefined` when
+ * `_site.mdx` is absent, unreadable, or declares no theme. A site with no
+ * readable config has no theme to apply, and the default palette is the
+ * correct result — the same fallback `site-brand.tsx` takes.
+ *
+ * "Declares no theme" covers a bare `theme:` key with nothing under it, which
+ * YAML parses to `null`. That is the shape the most natural edit produces —
+ * commenting out the block's children leaves the key dangling — and it means
+ * exactly what an absent key means, so it takes the same path rather than
+ * reaching the schema and throwing out of a Server Component.
+ */
+function readThemeBlock(): unknown {
+  try {
+    const raw = readFileSync(join(resolveContentRoot(), "_site.mdx"), "utf8");
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) return undefined;
+
+    const parsed: unknown = parseYaml(match[1] ?? "");
+    if (!parsed || typeof parsed !== "object") return undefined;
+
+    return (parsed as Record<string, unknown>).theme ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function loadSiteBrandTokens(): BrandTokenOverrides | undefined {
+  const block = readThemeBlock();
+  if (block === undefined) return undefined;
+
+  // Validation failures and unsupported colours BOTH throw, deliberately: a
+  // customer who set a colour and saw no change would have been lied to.
+  const theme = SiteThemeSchema.parse(block);
+  return siteThemeToBrandTokens(theme, SOURCE);
+}

package/templates/apps/web/package.json

@@ -31,6 +31,7 @@
     "@working-theory/schema": "workspace:*",
     "@working-theory/schema-pack-registry": "workspace:*",
     "@working-theory/schema-validator": "workspace:*",
+    "@working-theory/site-config": "workspace:*",
     "@working-theory/templates": "workspace:*",
     "@working-theory/theme": "workspace:*",
     "@working-theory/ui": "workspace:*",

package/templates/content/_site.mdx

@@ -14,6 +14,13 @@ siteIdentity:
   sameAs: []
 analytics:
   vercelAnalytics: false
+theme:
+  colors:
+    light:
+      bg: "#fdfcfa"
+      text: "#1c1917"
+    dark:
+      bg: "#0c0a09"
 ---
 
 <!--
@@ -31,6 +38,11 @@ your LinkedIn company page, your GitHub org, your X profile. Answer engines use
 it to reconcile your site with the rest of your presence, so it is worth
 filling in.
 
+`theme.colors` is the site's colour overlay: each key names a customer-facing
+colour role (`bg`, `text`, `primary`, `accent`, …) per light/dark mode, and the
+build turns it into the CSS custom properties every component reads. Declare
+only what you change — an absent role keeps the platform default.
+
 For the agent-operator workflow, use the `set_site_identity` MCP tool rather
 than editing this file directly — it validates input and writes with optimistic
 locking.

package/templates/database/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @working-theory/database
 
+## 0.20.0
+
+### Minor Changes
+
+- [#5282](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/5282) [`49e6ba4`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/49e6ba470a0ff4a0e6d4f7d14147232e90a12259) Thanks [@claudio-planck](https://github.com/claudio-planck)! - Consent purposes and grants ([#5275](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/5275)): a site declares its consent purposes once, any form renders them as real checkboxes with inline policy links, and every answer produces a durable record carrying the exact wording the person read.
+
+  `@working-theory/validation` gains `consent-config.ts` — the per-site consent registry contract (`siteConsentConfigSchema`, `SITE_CONSENT_CONFIG_DEFAULTS`, `consentConfigFor`, `resolveConsentStatement`), following `SiteListingConfig`: a Zod-validated blob, platform defaults, and an unparseable blob that resolves to those defaults rather than to a failed form. A statement's links are markdown-shaped with a KEY target (`[Privacy Policy](privacy)`) resolved against the site's policy map, so a config string can never carry a URL or a scheme. `fieldInputTypeSchema` gains the `consent` kind, carrying `purposes: string[]` (ids only; `options`/`minLength` are refused on it). `projectListingStartSchema` keeps `consent: z.literal(true)` and gains an optional `consents: Record<purposeId, boolean>` and `locale`, so every existing caller (agent submission included) still parses. The listing application's contact step compiles its consent control as the `consent` kind (an optional `consentPurposes` list, defaulting to the platform's `service_terms`) instead of a `select` carrying one fake option.
+
+  `@working-theory/ui` gains two blocks: `ConsentStatement` (parses `[Label](key)` tokens; an unresolvable key renders as plain text, never a dead link; no code path renders an href taken from the statement string) and `ConsentGroup` (one `Checkbox` per purpose, every box unticked on first render, each named and described by its statement via `aria-labelledby`/`aria-describedby`, posting under a flat `<field>.<purposeId>` name). `ContactFormFields` accepts `type: "consent"`; `FlowStepper` gates advance on required purposes only and sends one `"true"`/`"false"` per purpose (a decline is a value, not an absent key); both take an optional `consentConfig` that defaults to the platform registry. `ListingApplicationFlow` now sends the founder's real grants (`consents` + `locale`) instead of a hardcoded `consent: true`.
+
+  `@working-theory/database` gains the append-only `ConsentGrant` model (`consent_grants`): subject as a type + id pair of plain scalars (no cross-namespace relation), declines stored as `granted: false`, the resolved statement denormalized with its hash and served locale, no `updatedAt` and no unique constraint on subject + purpose. The migration backfills one row per pre-existing listing marked wording-unrecoverable, stamped at the listing's own `consent_at`, and never touches `project_listings`.
+
+  Additive: a flow, form, or site declaring no consent config renders and parses exactly as before. The one deliberate behavior change is the listing application's consent control.
+
+- [#5294](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/5294) [`cf6b325`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/cf6b325298e92d22ab7edfe8538f5ca17f54ebfd) Thanks [@claudio-planck](https://github.com/claudio-planck)! - The founder application becomes data ([#5285](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/5285)): a published field contract, questions and screens as records, and override by exception.
+
+  `@working-theory/validation` gains `listing-application-contract.ts` — the fields the platform actually READS, each with the call site that reads it, which of them a published listing cannot do without, and the control a question writing one must declare. Two beliefs the design carried did not survive that grounding and are recorded in the module header: there is no `FAQPage` emission for a listing in this tree, and no resume-link email. `listing-application.ts` gains the question record (an id, a control, copy, options, validation, and either a `writesTo` naming a contract field or a `siteAnswer` destination carrying a visibility flag), the screen record (its own copy, an ordered list of question ids, and its own side-panel declaration), merge-by-id so a site rewording one question inherits every other default including ones added later, and a parse-time invariant: exactly one question writes each required contract field, with zero and two both named failures. The compiler emits ONE step per screen carrying every field its questions contribute — the generalization of the `contact` and `faqs` cases, not a third mechanism. `listing-application-defaults.ts` ships a complete default question set and a grouped arrangement following combine-selection, separate-composition; it deliberately reverses the ships-no-copy discipline and says why.
+
+  `@working-theory/ui` reaches two capabilities that already existed and were thrown away in one line. `ListingApplicationFlow` returned the live tile unconditionally on every step, ignoring the view `FlowStepper` handed it; a screen declares its own side panel now, and a screen declaring none renders a full-width question with `FlowFrame`'s side region collapsed. `FlowFrame` gains a side cell with the same padding, measure and centring the active cell's step card has, so side content no longer hand-rolls its own inset, and its side region gains `md:flex-1` — without it the region carried `md:w-1/2` against an active region carrying `flex-1`, so a caller's gap came out of the question column alone. `FlowStepper` measures the step card and sizes the side cell to the tallest card observed, never shrinking, capped at the VISIBLE slot height rather than the frame's declared `h-dvh` — a page mounting the frame below a header makes it taller than the viewport.
+
+  `@working-theory/database` gains the bounded site-answers store on `ProjectListing`, and the logo columns become writable from the application.
+
+  Additive, with two boundaries stated precisely. The flat `steps` config parses and compiles to the byte-identical `FlowConfig` — verified old-against-new on a fifteen-step config exercising every step kind — and `steps` is now optional, with a config declaring both shapes, or declaring `steps` as an explicit `undefined`, a named parse failure. What is NOT unchanged is the rendered frame: the side-cell container, the shared gap and the measured panel height are fixes to `FlowFrame` and `FlowStepper`, so they reach every consumer of those two components by design, not only the listing application.
+
+  A site that overrides one question's copy and declares no `screens` inherits every other default and renders new defaults added later. A site that declares its own `screens` inherits new defaults into its question set but does not render them — declared screens are that site's statement of what it asks, and inserting a screen into a live form is not something an upstream release should do. A new default that writes a REQUIRED contract field still fails that site's config at parse, by name.
+
+  The three fields the application gained — the two logo URLs and the requested window — are OPT-IN: they are excluded from the default collected-field mask, so adding them cannot widen what an anonymous caller may write on a site that never asked for them. A site that wants them names them.
+
+- [#5298](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/5298) [`57b0b04`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/57b0b047eb3f04d40f0712a893c89415b742c7f5) Thanks [@claudio-planck](https://github.com/claudio-planck)! - A verified owner link on a listing ([#5295](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/5295)): a founder who signs in can read their own submitted listings, and nobody else's.
+
+  `@working-theory/database` gains `ProjectListing.ownerUserId` / `ownerLinkedAt` — plain nullable scalars with no cross-namespace relation, exactly the shape `Lead.promotedUserId` / `promotedAt` already has (ADR 0009 invariant [#1](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/1)). A listing carried `founderEmail` and `leadId` and no user link, so the only join available for "the listings belonging to this signed-in person" was a session's email against `founderEmail`. That string is typed into an anonymous form and proves nothing: two people who type the same address are two people, and the join hands one of them the other's submission. These columns are the ownership claim a read may actually join on.
+
+  The link is stamped only when all three of these hold: the reconciling user's own email is VERIFIED; that verified address matches the row's `founderEmail`; and the row's site resolves to one of that user's own tenant workspaces. Any one failing writes nothing and returns a count rather than throwing — the reconciliation path would otherwise fail an unrelated request. The email comparison is exact equality against the same normalization the write path applies, deliberately not Prisma's `mode: "insensitive"`, which compiles to `ILIKE` and would make `_` and `%` in the caller's own address wildcards that capture a neighbour's row.
+
+  A fourth condition has no counterpart in the lead service: the match must be UNAMBIGUOUS. Two strangers can type the same address into the anonymous form, and when they do nothing says which of the two un-linked rows is whose — so a row is claimed only when it is the only un-linked row carrying that address at its site, and an ambiguous group stays null. The cost is a founder who legitimately submitted two applications at one site, which the concurrent limit allows: neither is linked. That is the deliberate trade, because nothing in the data separates their second application from a stranger's first. The write also repeats `ownerUserId: null`, making it a compare-and-swap, so two concurrent reconciliation runs cannot transfer a row away from whoever claimed it first.
+
+  Candidacy is also restricted to submitted rows — every stored status except `draft`. A draft is addressed by its resume token, which is cleared at submit, so the token and the owner link hand off to each other cleanly and a draft needs no link. It is also a security boundary: draft creation is anonymous with the quota enforced at submit, so a claimable draft would let one unauthenticated request either disclose a stranger's text or, under the ambiguity refusal, permanently block someone from claiming their own listing.
+
+  `@working-theory/validation` gains `projectListingMeResponseSchema` — an array of the existing founder-facing `projectListingDraftSchema`, reused rather than forked because the audience is the same person that shape already serves. Nothing existing changes.
+
+  No existing row is backfilled, now or later. Every row predates verification, so deriving a link from `founderEmail` would assert the thing nobody proved. A listing submitted by someone who never signs in stays null for the life of the row, which is a legitimate resting state rather than a backlog.
+
+  Additive throughout. Both columns are nullable with no default; the new schema export is new; the operator's `owner|admin` floor on the existing tenant-scoped listing routes is unchanged, and the founder reads their own rows through the owner link rather than through a relaxed floor.
+
+- [#5283](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/5283) [`a713ea7`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/a713ea78c12c1dc2519b80831deed197a4f227b4) Thanks [@claudio-planck](https://github.com/claudio-planck)! - A structured `address` field type in the flow vocabulary, and structured address storage for listings ([#5279](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/5279)).
+
+  `AddressFieldset` has shipped since [#4395](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/4395) and `StepFlow` has rendered it ever since, but `fieldInputTypeSchema` exposed six input types and `address` was not one of them — so a flow config could not name the composite, and the founder application collected a whole published business address in a single free-text box capped at 300 characters.
+
+  `fieldInputTypeSchema` gains `"address"`. The two cross-field rules already beneath that enum cover the new member without a new clause: `options` is select-only and `minLength` is text/textarea-only, so an address field declaring either is a named parse failure rather than a silently discarded setting. `flowAddressValueSchema` and `composeAddressLine` are new exports — the first declares the six-part value an address field submits, the second composes the single-line display string from those parts. There is deliberately no function that runs the conversion the other way.
+
+  `FlowStepper` reads, validates, gates, seeds and submits the composite against the six fixed keys `AddressFieldset` posts under, which is the handling `StepFlow` has carried since [#4395](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/4395). Required means every required sub-control has a value rather than that a key named `address` is non-empty. `ContactFormFields` already rendered the type and is unchanged, as are `AddressFieldset` and `ADDRESS_COUNTRIES`.
+
+  `ProjectListing` keeps `address` as the single-line display string and gains six nullable columns for the parts beside it. A new application composes its display string from the parts, server-side. An existing row keeps its display string exactly as the founder typed it and its parts stay null — no stored address is ever parsed, split, or rewritten, and the migration does not backfill.
+
+  Every change is additive: a flow config that declares no address field parses, renders and submits exactly as it did before, and a listing carrying only the legacy free-text address reads unchanged.
+
+### Patch Changes
+
+- Updated dependencies [[`49e6ba4`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/49e6ba470a0ff4a0e6d4f7d14147232e90a12259), [`cf6b325`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/cf6b325298e92d22ab7edfe8538f5ca17f54ebfd), [`767a35c`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/767a35ca83155f774667ea3f7a10eb0ce1c094ab), [`57b0b04`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/57b0b047eb3f04d40f0712a893c89415b742c7f5), [`65989b4`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/65989b4dc6915bf37608475ed6409f98cd5945e2), [`a713ea7`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/a713ea78c12c1dc2519b80831deed197a4f227b4)]:
+  - @working-theory/validation@0.20.0
+
 ## 0.19.0
 
 ### Minor Changes

package/templates/database/inbox/schema.prisma

@@ -460,8 +460,47 @@ model ProjectListing {
   // #5036 D6 — a legal control, not a contact detail: visitors answering this
   // founder's diagnostic are owed the identity and address of the party
   // collecting their data. Carried on the PUBLIC read for that reason.
+  //
+  // #5279 — still the single-line DISPLAY string. Where the six part columns
+  // below are written, this is COMPOSED from them server-side; where they are
+  // not, it is the line the founder typed, verbatim.
   address        String?
+  // #5279 — the structured parts of the address above, beside it rather than
+  // instead of it. Nullable for the same reason as the #5036 D1 block above: a
+  // row written before #5279 has no parts, and none may ever be GUESSED from
+  // its `address` string. Parts compose into a line deterministically; a line
+  // does not decompose into parts, and a wrong split silently corrupts the
+  // party identification the listing's privacy notice points at — so the
+  // migration deliberately backfills nothing and a null part stays null for
+  // the life of the row. Composition runs one way only, in `draftUpdateData`
+  // (apps/api/src/services/project-listings.ts).
+  addressLine1      String? @map("address_line1")
+  addressLine2      String? @map("address_line2")
+  addressCity       String? @map("address_city")
+  addressRegion     String? @map("address_region")
+  addressPostalCode String? @map("address_postal_code")
+  addressCountry    String? @map("address_country")
   questions      Json?
+  // #5285 — the answers to the site's OWN questions: one flat JSON object of
+  // `{ questionId: answer }` for everything a site asks that the PLATFORM does
+  // not read. The field contract (packages/validation/.../listing-
+  // application-contract.ts) names what the platform reads and therefore what
+  // earns a column; everything else was previously unaskable without a
+  // migration and a release, which is what this column removes.
+  //
+  // BOUNDED, not free-form, and that is the point: the write path is
+  // anonymous (a resume token and nothing else), so an unbounded JSON bag on
+  // it is a place for a stranger to park arbitrary text in the table. The
+  // server accepts only ids the SITE declared in its own `SiteListingConfig`,
+  // at that site's own count and length caps, and refuses the whole request
+  // otherwise — so what lands here is never larger than the questions the
+  // operator chose to ask. Null on every row written before #5285 and on
+  // every site that asks nothing of its own.
+  //
+  // Only the `public`-visibility subset rides the public read; an
+  // `operator-only` answer reaches the dashboard and the review payload and
+  // stops there.
+  siteAnswers    Json?     @map("site_answers")
   founderName    String    @map("founder_name")
   founderEmail   String    @map("founder_email")
   founderCompany String?   @map("founder_company")
@@ -512,6 +551,24 @@ model ProjectListing {
   // rolls back on a Slack failure).
   slackChannel   String?   @map("slack_channel")
   slackTs        String?   @map("slack_ts")
+  // Listing -> owner-user link (#5295). Plain scalars — no cross-namespace
+  // @relation into auth.User (ADR 0009 invariant #1), exactly as
+  // `Lead.promotedUserId` / `promotedAt` above. Set by
+  // apps/api/src/services/listing-promotion.ts once the reconciling user's own
+  // email is VERIFIED, that verified address matches `founderEmail`, and this
+  // row's `siteId` resolves to one of that user's own workspaces.
+  //
+  // `founderEmail` is an UNVERIFIED string typed into an anonymous form, so it
+  // can never by itself say who owns the row: two people who type the same
+  // address are two people. This column is the only ownership claim any read
+  // may join on, and nothing derives it from `founderEmail` at read time.
+  //
+  // Nullable PERMANENTLY, not pending a backfill. A listing submitted by
+  // someone who never signs in has no owner for the life of the row, and that
+  // is a legitimate resting state: a backfill from `founderEmail` would assert
+  // a link nobody proved, which is the bug this column exists to remove.
+  ownerUserId    String?   @map("owner_user_id")
+  ownerLinkedAt  DateTime? @map("owner_linked_at")
   createdAt      DateTime  @default(now()) @map("created_at")
   updatedAt      DateTime  @updatedAt @map("updated_at")
 
@@ -521,5 +578,46 @@ model ProjectListing {
   // rows on every submit, from an anonymous route. Indexed so a stranger
   // cannot make that count a table scan.
   @@index([siteId, founderEmail])
+  // The self-scoped read's whole WHERE clause (#5295) is `{ ownerUserId }` —
+  // the owner link IS the scope, so no site term joins it. Single-column by
+  // design: the promotion match (`founderEmail` + `siteId` + null owner) is
+  // already served by the (site_id, founder_email) index above.
+  @@index([ownerUserId])
   @@map("project_listings")
 }
+
+/// ConsentGrant — one person's answer to one consent purpose, with the exact
+/// wording they read (#5275). APPEND-ONLY: current state is the newest row
+/// per (subject, purpose), so a later withdrawal never destroys the evidence
+/// of the earlier grant (D9) — no `updatedAt`, and deliberately NO unique
+/// constraint on subject + purpose. DECLINES ARE STORED as `granted: false`
+/// (D8): an absent row cannot distinguish "they said no" from "we never
+/// asked", and on an optional purpose that distinction is the only thing the
+/// record is for. The subject is a type + id pair of plain scalars
+/// (`project_listing` / `subscriber` / …) with NO cross-namespace @relation
+/// (D10, ADR 0009 invariant 1) — which is what lets a new surface adopt
+/// consent with a service call and no migration. `statement` is the resolved
+/// text DENORMALIZED at write time (D7): a pointer into the site's config row
+/// would prove nothing once that row is edited, and `statementHash` groups
+/// identical wordings. `locale` is the locale the statement was actually
+/// served in, not the one requested. `purposeId` is the site-config registry
+/// id — the join key across surfaces. Written only by
+/// apps/api/src/services/consent.ts.
+model ConsentGrant {
+  id            String   @id @default(dbgenerated("('cnsnt_'::text || (uuidv7())::text)")) @db.Text
+  siteId        String   @map("site_id")
+  subjectType   String   @map("subject_type")
+  subjectId     String   @map("subject_id")
+  purposeId     String   @map("purpose_id")
+  granted       Boolean
+  locale        String
+  statement     String   @db.Text
+  statementHash String   @map("statement_hash")
+  createdAt     DateTime @default(now()) @map("created_at")
+
+  // "What did this subject agree to" — every row for one subject, newest last.
+  @@index([siteId, subjectType, subjectId])
+  // "Who agreed to this purpose" — the cross-surface count the id exists for (D1/D2).
+  @@index([siteId, purposeId])
+  @@map("consent_grants")
+}

package/templates/database/migrations/20260911140000_listing_structured_address/migration.sql

@@ -0,0 +1,32 @@
+-- The founder's address, in structured parts, on `project_listings` (#5279).
+--
+-- The application collected a whole business address in ONE free-text box
+-- (`address`, a single line). That line is a legal control rather than a
+-- contact detail — visitors answering a founder's diagnostic are owed the
+-- identity and address of the party collecting their data (#5036 D6) — and a
+-- notice that has to name a country or a region cannot reliably find one
+-- inside a line someone typed by hand.
+--
+-- These six columns carry the parts the fieldset now collects. They sit
+-- BESIDE `address`, not instead of it: `address` remains the single-line
+-- DISPLAY string, composed server-side from these columns when they are
+-- written, and left exactly as the founder typed it when they are not.
+--
+-- Every column is nullable, and there is DELIBERATELY NO BACKFILL. Parts
+-- compose into a line deterministically; a line does not decompose into
+-- parts. Address parsing guesses, and a wrong guess — a region read as a
+-- city, a house number read as a postcode — silently corrupts the party
+-- identification a listing's privacy notice points at, with nothing on the
+-- row to mark it as invented. A null part is honest; a guessed one is not.
+-- So every existing row keeps its `address` string byte-for-byte and keeps
+-- all six parts NULL, for the life of the row.
+--
+-- No index: every read of these columns is already keyed by the listing's own
+-- primary key or by an existing (site_id, …) index, and no query filters on a
+-- part.
+ALTER TABLE "project_listings" ADD COLUMN "address_line1" TEXT;
+ALTER TABLE "project_listings" ADD COLUMN "address_line2" TEXT;
+ALTER TABLE "project_listings" ADD COLUMN "address_city" TEXT;
+ALTER TABLE "project_listings" ADD COLUMN "address_region" TEXT;
+ALTER TABLE "project_listings" ADD COLUMN "address_postal_code" TEXT;
+ALTER TABLE "project_listings" ADD COLUMN "address_country" TEXT;

package/templates/database/migrations/20260911180000_consent_grants/migration.sql

@@ -0,0 +1,71 @@
+-- #5275 — ConsentGrant: one person's answer to one consent purpose, with the
+-- exact wording they read. Mirrors the shape of
+-- 20260907180000_add_listing_csv_send (CreateTable + CreateIndex immediately
+-- followed by the ADR-0031 rule-3 id-format completion applied in the SAME
+-- migration since the table is new, no retrofit needed), then the listing
+-- BACKFILL.
+--
+-- The table is APPEND-ONLY (D9): no updated_at, and deliberately NO unique
+-- constraint on (subject, purpose) — current state is the newest row per
+-- pair, so a later withdrawal never erases the earlier grant. Declines are
+-- stored as granted = false (D8). subject_type/subject_id are plain scalars
+-- with no cross-namespace FK (D10, ADR 0009). statement is denormalized (D7).
+--
+-- BACKFILL: one row per pre-existing project_listings row (D11, spec §5.3
+-- second boundary). Those founders ticked a consent box, but the system never
+-- RENDERED any statement to them — the control was a select carrying one fake
+-- option, and the client sent a hardcoded `consent: true` — so there is no
+-- per-listing wording to recover. Each backfilled row is therefore marked
+-- WORDING-UNRECOVERABLE rather than stamped with today's default statement:
+-- stamping current wording onto a grant nobody read would fabricate evidence.
+-- The sentinel is the exact `UNRECOVERABLE_CONSENT_STATEMENT` literal from
+-- apps/api/src/services/consent.ts, its hash is COMPUTED here rather than
+-- hand-typed, locale is BCP-47 `und` (undetermined), and created_at is the
+-- listing's own consent_at — the one fact about the act that IS recoverable.
+-- This migration never UPDATEs or ALTERs project_listings; consent_at is left
+-- exactly as it was (spec §2.3).
+
+-- CreateTable
+CREATE TABLE "consent_grants" (
+    "id" TEXT NOT NULL DEFAULT ('cnsnt_'::text || (uuidv7())::text),
+    "site_id" TEXT NOT NULL,
+    "subject_type" TEXT NOT NULL,
+    "subject_id" TEXT NOT NULL,
+    "purpose_id" TEXT NOT NULL,
+    "granted" BOOLEAN NOT NULL,
+    "locale" TEXT NOT NULL,
+    "statement" TEXT NOT NULL,
+    "statement_hash" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "consent_grants_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "consent_grants_site_id_subject_type_subject_id_idx" ON "consent_grants"("site_id", "subject_type", "subject_id");
+
+-- CreateIndex
+CREATE INDEX "consent_grants_site_id_purpose_id_idx" ON "consent_grants"("site_id", "purpose_id");
+
+-- ADR-0031 rule 3 — consent_grants: cnsnt_ (registered in
+-- packages/ids/src/registry.ts ENTITY_PREFIX.consentGrant; this migration's
+-- path is added to migration-sync.test.ts's PK_CHECK_MIGRATIONS).
+ALTER TABLE "consent_grants" ALTER COLUMN "id" TYPE text COLLATE "C";
+ALTER TABLE "consent_grants" ALTER COLUMN "id" SET DEFAULT ('cnsnt_'::text || (uuidv7())::text);
+ALTER TABLE "consent_grants" ADD CONSTRAINT "consent_grants_id_format" CHECK ("id" ~ '^cnsnt_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$');
+
+-- Backfill (D11): one wording-unrecoverable `service_terms` grant per
+-- pre-existing listing, stamped at the listing's own consent_at. Read-only
+-- against project_listings.
+INSERT INTO "consent_grants" ("site_id", "subject_type", "subject_id", "purpose_id", "granted", "locale", "statement", "statement_hash", "created_at")
+SELECT
+    "site_id",
+    'project_listing',
+    "id",
+    'service_terms',
+    TRUE,
+    'und',
+    '[unrecoverable: no statement was rendered by this system for this grant]',
+    encode(sha256(convert_to('[unrecoverable: no statement was rendered by this system for this grant]', 'UTF8')), 'hex'),
+    "consent_at"
+FROM "project_listings";

package/templates/database/migrations/20260911200000_listing_site_answers/migration.sql

@@ -0,0 +1,30 @@
+-- The site's own answers store on `project_listings` (#5285).
+--
+-- The founder application used to couple the platform to a QUESTION: a step
+-- kind rendered one control and wrote one column, so a site could not ask
+-- anything of its own without an upstream release. The field contract names
+-- the fields the platform actually READS — the ones that derive a slug,
+-- render a card, key the concurrency limit, build the operator's issue — and
+-- those keep their columns. Everything else a site wants to ask is editorial,
+-- and lands here instead: one JSON object of `{ questionId: answer }`.
+--
+-- BOUNDED, not free-form. The write path is ANONYMOUS — a resume token and
+-- nothing else — and an unbounded JSON bag on an anonymous surface is a place
+-- for a stranger to park arbitrary text in the table. So the server accepts
+-- only ids the site declared in its own `SiteListingConfig.data.siteAnswers`,
+-- at that site's own count and length caps, and refuses the WHOLE request
+-- otherwise: an answer for an id the site does not ask is a 400 and nothing
+-- is written. What can land in this column is therefore never larger than the
+-- questions an operator chose to ask.
+--
+-- Nullable with no default and no backfill: null means "this site asks
+-- nothing of its own", which is every existing row and every site that has
+-- declared no questions. An empty object would claim the founder was asked
+-- and answered nothing, which is a different fact.
+--
+-- No index, and no GIN index in particular. Nothing queries INTO this column:
+-- every read of it is already keyed by the listing's primary key or by an
+-- existing (site_id, …) index, and an answer the platform searched on would
+-- by definition be an answer the platform reads — which is what a contract
+-- field and a column of its own are for.
+ALTER TABLE "project_listings" ADD COLUMN "site_answers" JSONB;

package/templates/database/migrations/20260912120000_listing_owner_link/migration.sql

@@ -0,0 +1,49 @@
+-- The verified owner link on `project_listings` (#5295).
+--
+-- A listing carried `founder_email` and `lead_id` and no user link, so there
+-- was no query for "the listings belonging to this signed-in person". The only
+-- join available was a session's email against `founder_email` — and
+-- `founder_email` is an UNVERIFIED string typed into an anonymous form, so that
+-- join hands a stranger someone else's submission the first time two people
+-- type the same address. These two columns are the ownership claim instead.
+--
+-- Plain scalars, no foreign key into `users`: ADR 0009 invariant #1 forbids a
+-- relation across the namespace boundary, and `leads.promoted_user_id` /
+-- `promoted_at` (20260714000000_add_lead_promotion_fields) are the same shape
+-- for the same reason. The join is stable-id matching in the service layer.
+--
+-- `apps/api/src/services/listing-promotion.ts` is the sole writer, and it sets
+-- the pair only when all three of these hold:
+--   1. the reconciling user's OWN email is verified (`users.email_verified`) —
+--      never a claimed or session-asserted address;
+--   2. that verified address matches the row's `founder_email`;
+--   3. the row's `site_id` is one of that user's own tenant workspaces.
+-- Any one failing writes nothing.
+--
+-- NO BACKFILL, deliberately and permanently. Every existing row predates
+-- verification, so deriving `owner_user_id` from `founder_email` here would
+-- assert exactly the link nobody proved — the bug the column exists to remove.
+-- Existing rows stay null, and a listing submitted by someone who never signs
+-- in stays null for the life of the row: that is a legitimate resting state,
+-- not a backlog to clean up.
+--
+-- The index backs the self-scoped read's whole WHERE clause
+-- (`GET /v1/project-listings/me` — `owner_user_id = $1`, and nothing else: the
+-- owner link IS the scope, so no site term joins it). Single-column by design —
+-- the promotion match (`founder_email` + `site_id` + a null owner) is already
+-- served by the existing (site_id, founder_email) index.
+--
+-- Forward-additive only: both columns are nullable with no default, so every
+-- existing read and write is unaffected.
+--
+-- Rollback:
+--   DROP INDEX "project_listings_owner_user_id_idx";
+--   ALTER TABLE "project_listings" DROP COLUMN "owner_linked_at";
+--   ALTER TABLE "project_listings" DROP COLUMN "owner_user_id";
+
+-- AlterTable
+ALTER TABLE "project_listings" ADD COLUMN     "owner_user_id" TEXT,
+ADD COLUMN     "owner_linked_at" TIMESTAMP(3);
+
+-- CreateIndex
+CREATE INDEX "project_listings_owner_user_id_idx" ON "project_listings"("owner_user_id");

package/templates/database/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@working-theory/database",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"