create-ailk 0.19.1 → 0.20.0

package/templates/apps/web/messages/en.json

@@ -57,7 +57,6 @@
   },
   "consent": {
     "title": "Cookie Preferences",
-    "body": "We use analytics to understand how visitors use this site. We don't sell your data.",
     "acceptLabel": "Accept",
     "rejectLabel": "Reject",
     "policyLinkLabel": "Privacy policy",
@@ -535,6 +534,7 @@
     "signUpSubmit": "Create account",
     "signUpFooterPrompt": "Already have an account?",
     "signUpFooterLink": "Sign in",
+    "signUpAgreementsLegend": "Agreements",
     "signUpNotConfiguredSubhead": "Sign-up is not configured for this site yet. Set a provider's environment variables to enable it.",
     "signUpFailed": "We couldn't create your account. Check your details and try again.",
     "providerFailed": "We couldn't start sign-up with that provider. Try again.",
@@ -622,6 +622,17 @@
           "rateLimited": "Too many requests. Try again later.",
           "failed": "We couldn't send your review. Try again."
         }
+      },
+      "proposal": {
+        "caption": "Proposal",
+        "price": "Price {amount}",
+        "approve": "Approve proposal",
+        "heading": "Your decision on version {version}",
+        "pay": "Pay now",
+        "paying": "Opening payment…",
+        "paid": "Paid {date}",
+        "paidPending": "Payment received — it may take a minute to show here.",
+        "payError": "We couldn't open the payment page. Try again."
       }
     },
     "frame": {
@@ -771,14 +782,32 @@
         "passwordUnavailable": "We couldn't check your password settings."
       },
       "notifications": {
-        "title": "Notifications"
+        "title": "Notifications",
+        "lead": "What we send you.",
+        "empty": "There's nothing to set here yet."
       },
       "signIn": {
         "lead": "How you sign in to this site."
       },
       "privacy": {
+        "title": "Privacy",
         "lead": "Cookies and your data.",
-        "cookies": "Cookie settings",
+        "summary": "How we use your data.",
+        "policyLink": "Read our privacy policy",
+        "cookiesTitle": "Cookies",
+        "cookiesAccepted": "Accepted",
+        "cookiesDeclined": "Declined",
+        "cookiesUnset": "Not chosen yet",
+        "cookiesChange": "Change",
+        "consentsTitle": "Data use",
+        "consentsEmpty": "This site asks for no other data-use consents.",
+        "agreementsTitle": "Agreements accepted",
+        "agreementsEmpty": "None yet",
+        "version": "Version {version}",
+        "given": "Given {date}",
+        "withdrawn": "Withdrawn {date}",
+        "accepted": "Accepted {date}",
+        "unavailable": "Your consent choices can't be shown right now.",
         "deletion": "Request account deletion",
         "deletionLead": "Ask the site owner to delete your account and its data. We'll confirm by email.",
         "deletionSentSite": "Sent to the site operator. They'll confirm by email.",
@@ -809,6 +838,12 @@
         }
       }
     },
+    "agreements": {
+      "titleNew": "Please accept our terms",
+      "titleUpdated": "We've updated our terms",
+      "accept": "Accept",
+      "error": "We couldn't save that. Try again."
+    },
     "gate": {
       "emptyHeadline": "Sign-in isn't available yet",
       "emptyDescription": "This site hasn't turned on sign-in for members yet. Check back soon, or contact the site owner.",
@@ -862,7 +897,26 @@
       "heading": "My messages",
       "sentAt": "Sent",
       "file": "File",
-      "download": "Download {filename}"
+      "download": "Download {filename}",
+      "openOnboarding": "Open onboarding"
+    },
+    "onboarding": {
+      "title": "Onboarding",
+      "unavailable": "Onboarding isn't open to you here right now.",
+      "back": "Back to your account",
+      "optional": "Optional",
+      "submit": "Send answers",
+      "submitting": "Sending…",
+      "sent": "Thank you — your answers were sent.",
+      "retry": "Retry",
+      "errors": {
+        "load": "We couldn't load your onboarding questions.",
+        "onboardingOff": "Onboarding isn't open to you here right now.",
+        "answersInvalid": "Some answers do not fit these questions. Check them and try again.",
+        "linkNotHttps": "A link must start with https://.",
+        "tooManyRequests": "Too many submissions. Try again later.",
+        "failed": "Your answers could not be sent. Try again."
+      }
     },
     "subscription": {
       "headline": "Your payment didn't go through",
@@ -1079,5 +1133,14 @@
     "sending": "Subscribing…",
     "success": "You're subscribed. Thanks for signing up!",
     "consentStatement": "I accept the [Terms](terms)."
+  },
+  "unsubscribe": {
+    "title": "Unsubscribe",
+    "lead": "Stop these emails?",
+    "button": "Unsubscribe",
+    "done": "You're unsubscribed from {description}.",
+    "already": "You were already unsubscribed.",
+    "invalid": "This link isn't valid.",
+    "unavailable": "Unsubscribing isn't available right now."
   }
 }

package/templates/apps/web/next.config.mjs

@@ -5,6 +5,7 @@ import bundleAnalyzer from "@next/bundle-analyzer";
 import { withSentryConfig } from "@sentry/nextjs";
 import createNextIntlPlugin from "next-intl/plugin";
 import { legacyRedirects } from "@working-theory/templates/routes";
+import { parseStealth } from "@working-theory/web-i18n/stealth";
 
 // @next/bundle-analyzer — enabled when ANALYZE=true (set by ci-bundle.yml).
 // analyzerMode 'json' writes .next/analyze/client.json (and nodejs.json,
@@ -16,11 +17,16 @@ const withBundleAnalyzer = bundleAnalyzer({
   analyzerMode: "json",
 });
 
-// When STEALTH=true, every response carries X-Robots-Tag: noindex, nofollow,
+// When STEALTH is on, every response carries X-Robots-Tag: noindex, nofollow,
 // noarchive — paired with the <meta robots> tag in app/layout.tsx. Layer 2 of
 // the three-layer stealth posture (#884); new AILK installs default to
 // STEALTH=true so a forked instance doesn't ship indexable by accident.
-const STEALTH = process.env.STEALTH === "true";
+// parseStealth is the one shared parse (#8511): true, 1, yes or on turn it on;
+// false, 0, no, off, empty or unset leave it off; any other value throws here,
+// so `next build` (and a non-standalone `next start`) fails before a page
+// renders. A standalone server.js does not load this file, so there the
+// robots route and every page's <meta robots> throw per request instead.
+const STEALTH = parseStealth(process.env.STEALTH);
 
 // next-intl plugin — no explicit path: uses next-intl's default convention
 // lookup (./i18n/request.ts). We use `next build --webpack` (see package.json)

package/templates/database/CHANGELOG.md

@@ -1,5 +1,44 @@
 # @working-theory/database
 
+## 0.41.0
+
+### Minor Changes
+
+- [#8540](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8540) [`48ff411`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/48ff41198ef01163412118249f51d64b66d4ce42) Thanks [@claudio-planck](https://github.com/claudio-planck)! - The API's per-IP rate limiter counts in a shared database table when one is configured, so one visitor's limit holds across every concurrent isolate ([#5040](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/5040)).
+
+  New model `RateLimitCounter` (table `rate_limit_counters`, prefix `rlc`) in the `ops` namespace, holding one row per hashed bucket key. Run the migration before deploying the code that reads it — code deployed first falls back to the per-isolate in-process limiter, safely, until the table exists.
+
+- [#8545](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8545) [`41bc2df`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/41bc2df800c8fe69e2cbb528be68f579abfbd80d) Thanks [@claudio-planck](https://github.com/claudio-planck)! - The Person record redesign ([#8514](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/8514), docs/specs/8514-redesign-the-person-record-page-spec.md).
+
+  - **database** — `people` gains the team's private note on a client (`notes`, who last saved it, when, and which agent), with format and pairing CHECKs. The same migration then removes `people-read` and `member-pieces-manage` from agents of members, where they were inert; deploy it before the code.
+  - **validation** — members now hold `people-read`, `people-write` and `member-pieces-manage`. The new `AGENT_WITHHELD_PERMISSIONS` and `roleAllows` keep every agent off those three by role: an agent holds the grantable two only by an explicit grant, and `people-write` never. New `personNotes*` and `planOfferings*` schemas.
+  - **api-client** — `people.notes` and `people.setNotes`.
+  - **metadata** — two signed-in workspace tools, `get_person_notes` and `set_person_notes` (thirteen in all).
+  - **ui** — `PhoneNumberField` shows its country format as a "Format: …" caption under the field and no longer puts the example in the placeholder.
+  - **templates** — `ContactDetailsForm`, the one contact form the account page and the Admin share; Save stays disabled until something changes.
+
+- [#8574](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8574) [`83b7a96`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/83b7a96ccd115230f82e111a9776c8e2136b6bf9) Thanks [@claudio-planck](https://github.com/claudio-planck)! - Standard client onboarding diagnostic and Start onboarding ([#8515](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/8515), docs/specs/8515-standard-client-onboarding-diagnostic-and-spec.md).
+
+  - `@working-theory/database`: `interactions_outbound_shape` admits one outbound payload, `{"action": "onboarding"}` (migration `20261017120000_outbound_message_action`; no row is rewritten).
+  - `@working-theory/validation`: `ONBOARDING_FLOW_SLUG`, `ONBOARDING_FLOW_TITLE` and `onboardingFlowConfig`, the standard onboarding magnet every workspace holds; `OUTBOUND_MESSAGE_ACTIONS` and `onboardingStartBodySchema`; `memberMessageSchema` gains `action`; `memberOnboardingFormResponseSchema`, `memberOnboardingStepSchema`, `memberOnboardingReceiptSchema` and the `onboarding_off` member error code.
+  - `@working-theory/api-client`: `member.onboarding` and `member.submitOnboarding`.
+
+- [#8572](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8572) [`16abdb4`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/16abdb45ef60cc46aba35d4179960468b8df1a8b) Thanks [@claudio-planck](https://github.com/claudio-planck)! - Proposals as an artifact kind ([#8516](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/8516), docs/specs/8516-proposals-as-an-artifact-kind-spec.md).
+
+  - `@working-theory/database`: `pieces` gains `kind` (`deliverable` by default, so every existing piece is unchanged), a proposal's optional price, the client's Checkout Session and the paid stamp, with their CHECKs and one unique index (migration `20261016120000_piece_kind`, DDL only).
+  - `@working-theory/validation`: `PIECE_KINDS`, `pieceKindSchema`, `PROPOSAL_CURRENCIES`, `proposalPriceSchema`; `pieceSchema` serves `kind`; the new `proposals.ts` wire (`proposalCreateBodySchema`, `proposalSchema`, `proposalsListResponseSchema`, `proposalResultSchema`, `proposalPaymentsSchema`); `memberArtifactSchema` gains optional `kind`, `price` and `payment`; `isStripeCheckoutUrl`, `memberProposalPaymentResponseSchema` and three member error codes.
+  - `@working-theory/api-client`: `people.proposals`, `people.createProposal` and `member.payArtifact`.
+  - `@working-theory/metadata`: the `list_proposals` and `create_proposal` workspace tools.
+  - `@working-theory/stripe-client`: `createQuotedCheckoutSession` takes optional `expiresAt` and `paymentMethodTypes`; existing callers' sessions are unchanged.
+
+### Patch Changes
+
+- [#8551](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/pull/8551) [`13e1d6f`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/13e1d6f74ef3db02b9cdedb5f33f84ad1a9a0d66) Thanks [@samuelhenry](https://github.com/samuelhenry)! - Person gains a private team note (notes, notes_updated_at, notes_updated_by, notes_updated_by_agent) and tenant-db gains its one reader and writer ([#8514](https://github.com/working-theory-labs/ai-launch-kit-internal/issues/8514), PR 1 of 2 — the fence half; the API, MCP and Admin surfaces follow in PR 2).
+
+- Updated dependencies [[`1b0d07a`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/1b0d07acc0c97f519bf7a2dccf108d6b98c24065), [`48ff411`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/48ff41198ef01163412118249f51d64b66d4ce42), [`98b82b0`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/98b82b0e1cf29be3ba33886ebc7b8294ebff52f0), [`41bc2df`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/41bc2df800c8fe69e2cbb528be68f579abfbd80d), [`83b7a96`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/83b7a96ccd115230f82e111a9776c8e2136b6bf9), [`16abdb4`](https://github.com/Working-Theory-Labs/ai-launch-kit-internal/commit/16abdb45ef60cc46aba35d4179960468b8df1a8b)]:
+  - @working-theory/validation@0.41.0
+  - @working-theory/ids@0.14.0
+
 ## 0.40.0
 
 ### Minor Changes

package/templates/database/__tests__/outbound-message-action.db.test.ts

@@ -0,0 +1,80 @@
+/**
+ * @file outbound-message-action.db.test.ts
+ *
+ * LIVE-DATABASE proof of the replaced `interactions_outbound_shape` CHECK
+ * (#8515, spec docs/specs/8515-standard-client-onboarding-diagnostic-and-spec.md
+ * D6; AC-4). Requires DATABASE_URL pointing at a Postgres with the migrations
+ * applied — the suite SKIPS when DATABASE_URL is unset, keeping the workspace
+ * Jest run DB-free (the repo convention; the `apps/api Route Tests (Postgres)`
+ * workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `member-contract.db.test.ts` does. An
+ * outbound `message` may carry exactly `{"action": "onboarding"}` and no other
+ * payload; a payload-free outbound row still lands, and the payload-by-kind
+ * rule for inbound rows is unchanged.
+ */
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+describeDb("the outbound message action (#8515 D6, AC-4, live DB)", () => {
+  let db: Client;
+  const WS = "wksp_01920000-8515-7000-8000-0000000000c1";
+  const USER = "user_01920000-8515-7000-8000-0000000000c1";
+  let person: string;
+
+  const cleanup = async () => {
+    await db.query(`DELETE FROM "interactions" WHERE "workspace_id" = $1`, [WS]);
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = $1`, [WS]);
+  };
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+    person = (
+      await db.query<{ id: string }>(
+        `INSERT INTO "people" ("workspace_id", "email", "updated_at") VALUES ($1, 'cleo@example.com', now()) RETURNING "id"`,
+        [WS],
+      )
+    ).rows[0]!.id;
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  const insert = (direction: string, kind: string, payload: unknown) =>
+    db.query<{ id: string }>(
+      `INSERT INTO "interactions" ("workspace_id", "person_id", "channel", "direction", "kind", "subject", "body", "payload", "created_by")
+       VALUES ($1, $2, 'member', $3, $4, 'Your onboarding questions', 'Please answer a few questions.', $5, $6) RETURNING "id"`,
+      [WS, person, direction, kind, payload === null ? null : JSON.stringify(payload), USER],
+    );
+
+  it("an outbound message carrying the onboarding action lands", async () => {
+    const row = await insert("outbound", "message", { action: "onboarding" });
+    expect(row.rows[0]!.id).toMatch(/^intx_/);
+  });
+
+  it("an outbound payload-free message still lands", async () => {
+    const row = await insert("outbound", "message", null);
+    expect(row.rows[0]!.id).toMatch(/^intx_/);
+  });
+
+  it.each([
+    ["another action", { action: "invoice" }],
+    ["a link", { link: "https://x.example" }],
+    ["the action with an extra key", { action: "onboarding", href: "https://x.example" }],
+  ])("an outbound message carrying %s fails interactions_outbound_shape", async (_label, payload) => {
+    await expect(insert("outbound", "message", payload)).rejects.toMatchObject({
+      constraint: "interactions_outbound_shape",
+    });
+  });
+
+  it("an inbound quote without a payload still fails interactions_payload_by_kind", async () => {
+    await expect(insert("inbound", "quote", null)).rejects.toMatchObject({
+      constraint: "interactions_payload_by_kind",
+    });
+  });
+});

package/templates/database/__tests__/person-notes.db.test.ts

@@ -0,0 +1,249 @@
+/**
+ * @file person-notes.db.test.ts
+ *
+ * LIVE-DATABASE proof of the client record's private notes and the member
+ * agent grant reset (#8514, spec
+ * docs/specs/8514-redesign-the-person-record-page-spec.md D1, D2, D2b; AC-2
+ * and the migration half of AC-3). Requires DATABASE_URL pointing at a
+ * Postgres with the migrations applied — every live suite SKIPS when
+ * DATABASE_URL is unset (the repo convention; the `apps/api Route Tests
+ * (Postgres)` workflow exercises it).
+ *
+ * Uses the `pg` driver directly, as `person-contact.db.test.ts` does. What it
+ * proves that a mock cannot:
+ *   1. The notes column's width and the people table's four new CHECKs (the
+ *      editor's user-id format, the agent's id format, the edit pair, and an
+ *      agent edit naming its person).
+ *   2. The migration's grant-reset half (its own text) removes people-read and
+ *      member-pieces-manage from an agent of a member only, and a second run
+ *      changes no row.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { Client } from "pg";
+
+const describeDb = process.env.DATABASE_URL ? describe : describe.skip;
+
+const MIGRATION = join(
+  __dirname,
+  "..",
+  "migrations",
+  "20261015120000_person_notes",
+  "migration.sql",
+);
+const RESET_MARK =
+  "-- ===== #8514 D2b member agent grant reset (data only; runs after the DDL above) =====";
+
+/** The grant-reset half of the single person_notes migration. */
+function resetSql(): string {
+  const text = readFileSync(MIGRATION, "utf8");
+  const at = text.indexOf(RESET_MARK);
+  if (at < 0) throw new Error("the grant-reset marker is missing from the migration");
+  return text.slice(at);
+}
+
+const USER_ID = "user_01920000-8514-7000-8000-0000000000a1";
+const AGENT_ID = "agent_01920000-8514-7000-8000-0000000000a2";
+
+describe("the person_notes migration file (#8514 D2, D2b)", () => {
+  it("is the DDL, then the grant reset: data only, touching the agents table's grants alone", () => {
+    const text = readFileSync(MIGRATION, "utf8");
+    const at = text.indexOf(RESET_MARK);
+    expect(at).toBeGreaterThan(0);
+    expect(text.slice(0, at)).toMatch(/ALTER TABLE "people"/);
+    expect(text.slice(0, at)).not.toMatch(/UPDATE /);
+    const reset = resetSql()
+      .split("\n")
+      .filter((line) => !line.startsWith("--"))
+      .join("\n");
+    expect(reset).not.toMatch(/ALTER TABLE|DROP |CREATE /);
+    expect(reset).toMatch(/UPDATE "agents"/);
+  });
+});
+
+describeDb("the notes columns (#8514 D1, D2, AC-2, live DB)", () => {
+  let db: Client;
+  const WS = "wksp_01920000-8514-7000-8000-0000000000c1";
+
+  async function cleanup(): Promise<void> {
+    await db.query(`DELETE FROM "people" WHERE "workspace_id" = $1`, [WS]);
+  }
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    await cleanup();
+  });
+
+  afterAll(async () => {
+    await cleanup();
+    await db.end();
+  });
+
+  let counter = 0;
+  const email = () => `p8514-${(counter += 1)}@example.com`;
+
+  /** Insert one Person with the given notes columns on top of the required pair. */
+  const insertPerson = async (cols: Record<string, unknown> = {}) => {
+    const all: Record<string, unknown> = {
+      workspace_id: WS,
+      email: email(),
+      updated_at: new Date(),
+      ...cols,
+    };
+    const names = Object.keys(all);
+    return db.query<{ id: string }>(
+      `INSERT INTO "people" (${names.map((n) => `"${n}"`).join(", ")})
+       VALUES (${names.map((_, i) => `$${i + 1}`).join(", ")}) RETURNING "id"`,
+      names.map((n) => all[n]),
+    );
+  };
+
+  const AT = new Date("2026-10-15T12:00:00.000Z");
+
+  it("a Person without notes reads all four columns as NULL", async () => {
+    const { rows } = await insertPerson();
+    const read = await db.query(
+      `SELECT "notes", "notes_updated_at", "notes_updated_by", "notes_updated_by_agent" FROM "people" WHERE "id" = $1`,
+      [rows[0]!.id],
+    );
+    expect(read.rows[0]).toEqual({
+      notes: null,
+      notes_updated_at: null,
+      notes_updated_by: null,
+      notes_updated_by_agent: null,
+    });
+  });
+
+  it("a 5000-character note saves and a 5001-character one fails", async () => {
+    await expect(
+      insertPerson({ notes: "n".repeat(5000), notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({ notes: "n".repeat(5001), notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).rejects.toThrow(/value too long/);
+  });
+
+  it("a user_ editor with a timestamp succeeds; an agent_ editor fails the format CHECK", async () => {
+    await expect(
+      insertPerson({ notes: "x", notes_updated_at: AT, notes_updated_by: USER_ID }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({ notes: "x", notes_updated_at: AT, notes_updated_by: AGENT_ID }),
+    ).rejects.toThrow(/people_notes_updated_by_format/);
+  });
+
+  it("a timestamp without an editor, or the reverse, fails the edit pair", async () => {
+    await expect(insertPerson({ notes: "x", notes_updated_at: AT })).rejects.toThrow(
+      /people_notes_edit_pair/,
+    );
+    await expect(insertPerson({ notes: "x", notes_updated_by: USER_ID })).rejects.toThrow(
+      /people_notes_edit_pair/,
+    );
+  });
+
+  it("an agent edit carries an agent_ id and its person", async () => {
+    await expect(
+      insertPerson({
+        notes: "x",
+        notes_updated_at: AT,
+        notes_updated_by: USER_ID,
+        notes_updated_by_agent: AGENT_ID,
+      }),
+    ).resolves.toBeDefined();
+    await expect(
+      insertPerson({
+        notes: "x",
+        notes_updated_at: AT,
+        notes_updated_by: USER_ID,
+        notes_updated_by_agent: USER_ID,
+      }),
+    ).rejects.toThrow(/people_notes_updated_by_agent_format/);
+    await expect(insertPerson({ notes_updated_by_agent: AGENT_ID })).rejects.toThrow(
+      /people_notes_agent_has_person/,
+    );
+  });
+});
+
+describeDb("the member agent grant reset (#8514 D2b, AC-3, live DB)", () => {
+  let db: Client;
+  let organizationId: string;
+  let workspaceId: string;
+  let ownerUserId: string;
+  let ownerMembershipId: string;
+  let memberMembershipId: string;
+  let adminMembershipId: string;
+  let hashSeq = 0;
+
+  const nextHash = () => (hashSeq += 1).toString(16).padStart(64, "0");
+
+  async function one(sql: string, params: unknown[]): Promise<string> {
+    return (await db.query<{ id: string }>(sql, params)).rows[0]!.id;
+  }
+
+  const insertUser = (tag: string) =>
+    one(`INSERT INTO "users" ("email", "updated_at") VALUES ($1, now()) RETURNING "id"`, [
+      `grants8514-${tag}@example.test`,
+    ]);
+
+  const insertMembership = (userId: string, role: string) =>
+    one(
+      `INSERT INTO "memberships" ("organization_id", "user_id", "role") VALUES ($1, $2, $3::"Role") RETURNING "id"`,
+      [organizationId, userId, role],
+    );
+
+  const insertAgent = (responsibleMembershipId: string, grants: string[]) =>
+    one(
+      `INSERT INTO "agents" ("organization_id", "workspace_id", "responsible_membership_id", "created_by_user_id",
+         "key_issued_to_membership_id", "credential_hash", "grants", "name", "credential_prefix", "updated_at")
+       VALUES ($1, $2, $3, $4, $5, $6, $7, 'client helper', 'ailk_agt_abcdefgh', now()) RETURNING "id"`,
+      [organizationId, workspaceId, responsibleMembershipId, ownerUserId, ownerMembershipId, nextHash(), grants],
+    );
+
+  const grantsOf = async (id: string) =>
+    (await db.query<{ grants: string[] }>(`SELECT "grants" FROM "agents" WHERE "id" = $1`, [id])).rows[0]!.grants;
+
+  beforeAll(async () => {
+    db = new Client({ connectionString: process.env.DATABASE_URL });
+    await db.connect();
+    organizationId = await one(
+      `INSERT INTO "organizations" ("name", "slug", "updated_at") VALUES ($1, $1, now()) RETURNING "id"`,
+      ["grants8514-org"],
+    );
+    workspaceId = await one(
+      `INSERT INTO "workspaces" ("organization_id", "name", "slug", "updated_at") VALUES ($1, $2, $2, now()) RETURNING "id"`,
+      [organizationId, "grants8514-ws"],
+    );
+    ownerUserId = await insertUser("owner");
+    ownerMembershipId = await insertMembership(ownerUserId, "owner");
+    memberMembershipId = await insertMembership(await insertUser("member"), "member");
+    adminMembershipId = await insertMembership(await insertUser("admin"), "admin");
+  });
+
+  afterAll(async () => {
+    await db.query(`DELETE FROM "organizations" WHERE "slug" LIKE 'grants8514-%'`);
+    await db.query(`DELETE FROM "users" WHERE "email" LIKE 'grants8514-%'`);
+    await db.end();
+  });
+
+  it("removes the two client grants from a member's agent only, and is idempotent", async () => {
+    const membersAgent = await insertAgent(memberMembershipId, [
+      "people-read",
+      "member-pieces-manage",
+      "content-edit",
+    ]);
+    const adminsAgent = await insertAgent(adminMembershipId, ["people-read"]);
+    const sql = resetSql();
+
+    const first = await db.query(sql);
+    expect(first.rowCount).toBeGreaterThanOrEqual(1);
+    expect(await grantsOf(membersAgent)).toEqual(["content-edit"]);
+    expect(await grantsOf(adminsAgent)).toEqual(["people-read"]);
+
+    const second = await db.query(sql);
+    expect(second.rowCount).toBe(0);
+    expect(await grantsOf(membersAgent)).toEqual(["content-edit"]);
+    expect(await grantsOf(adminsAgent)).toEqual(["people-read"]);
+  });
+});

package/templates/database/__tests__/piece-kind-migration.test.ts

@@ -0,0 +1,67 @@
+/**
+ * @file piece-kind-migration.test.ts
+ *
+ * DB-free proof of the piece_kind migration's shape (#8516, spec
+ * docs/specs/8516-proposals-as-an-artifact-kind-spec.md D2, AC-1). Reads the
+ * migration's own text: it is DDL only — eight `ADD COLUMN`s on "pieces", one
+ * unique index and CHECKs added `NOT VALID` then `VALIDATE`d — with no
+ * `UPDATE`, `INSERT` or `DELETE`, so no existing row is rewritten, and `kind`
+ * defaults to `deliverable` as a constant. The live-database half is
+ * `piece-kind.db.test.ts`.
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const MIGRATION = join(__dirname, "..", "migrations", "20261016120000_piece_kind", "migration.sql");
+
+/** The migration's statements, comments stripped, whitespace collapsed. */
+function statements(): string[] {
+  const text = readFileSync(MIGRATION, "utf8")
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("--"))
+    .join("\n");
+  return text
+    .split(";")
+    .map((s) => s.replace(/\s+/g, " ").trim())
+    .filter((s) => s.length > 0);
+}
+
+describe("the piece_kind migration (#8516 D2, AC-1)", () => {
+  it("is only ADD COLUMN on pieces, one unique index, and NOT VALID CHECKs then VALIDATE", () => {
+    const shapes = statements().map((s) => {
+      if (/^ALTER TABLE "pieces" ADD COLUMN /.test(s)) return "add-column";
+      if (/^CREATE UNIQUE INDEX "pieces_checkout_session_id_key" ON "pieces"/.test(s)) return "index";
+      if (/^ALTER TABLE "pieces" ADD CONSTRAINT "pieces_[a-z_]+" CHECK \(.*\) NOT VALID$/.test(s)) {
+        return "check";
+      }
+      if (/^ALTER TABLE "pieces" VALIDATE CONSTRAINT "pieces_[a-z_]+"$/.test(s)) return "validate";
+      return `unexpected: ${s}`;
+    });
+    expect(shapes.filter((s) => s.startsWith("unexpected"))).toEqual([]);
+    expect(shapes.filter((s) => s === "add-column")).toHaveLength(1);
+    expect(shapes.filter((s) => s === "index")).toHaveLength(1);
+    expect(shapes.filter((s) => s === "check")).toHaveLength(11);
+    expect(shapes.filter((s) => s === "validate")).toHaveLength(11);
+  });
+
+  it("writes no row: no UPDATE, INSERT or DELETE", () => {
+    for (const s of statements()) expect(s).not.toMatch(/\b(UPDATE|INSERT|DELETE)\b/i);
+  });
+
+  it("adds kind as VARCHAR(16) NOT NULL DEFAULT 'deliverable' and seven nullable columns", () => {
+    const add = statements().find((s) => s.startsWith('ALTER TABLE "pieces" ADD COLUMN'));
+    expect(add).toContain(`"kind" VARCHAR(16) NOT NULL DEFAULT 'deliverable'`);
+    for (const column of [
+      `"price_amount" INTEGER`,
+      `"price_currency" CHAR(3)`,
+      `"checkout_session_id" TEXT`,
+      `"checkout_url" VARCHAR(2048)`,
+      `"checkout_expires_at" TIMESTAMP(3)`,
+      `"paid_at" TIMESTAMP(3)`,
+      `"paid_session_id" TEXT`,
+    ]) {
+      expect(add).toMatch(new RegExp(`${column.replace(/[()]/g, "\\$&")}(,|$)`));
+    }
+    expect(add).not.toMatch(/DEFAULT 'proposal'/);
+  });
+});