create-ailk 0.13.0 → 0.15.0

package/site-templates/shapes/organization-service/TEMPLATE-MANIFEST.md

@@ -263,6 +263,24 @@ _Code route — no content, no sections._
 _Detail route over `content/en/PortfolioItem/` — 4 seed pages: `sample-four.mdx`, `sample-one.mdx`, `sample-three.mdx`, `sample-two.mdx`._
 <!-- generated:end -->
 
+`/team`:
+
+<!-- generated:begin page=/team -->
+
+| #   | Section                                 | Component | Copy (first line)             |
+| --- | --------------------------------------- | --------- | ----------------------------- |
+| 1   | `hero` (default · eyebrow "{Team}")     | `Hero`    | {The people behind the work.} |
+| 2   | `team` (with-large-images · members ×3) | `Team`    | {First team member's name}    |
+
+<!-- generated:end -->
+
+`/team/[slug]`:
+
+<!-- generated:begin page=/team/[slug] -->
+
+_Detail route over `content/en/TeamMember/` — 3 seed pages: `first-member.mdx`, `second-member.mdx`, `third-member.mdx`._
+<!-- generated:end -->
+
 ### 3a. Differences from the standard `organization-service` derivation
 
 The standard page set for this shape (`derive-roster.py --shape organization-service --primary-goal generate-leads --registry packages/schema/src/registry/entries.ts`, harness commit `7bdaf148e1b0e639cd90a80008955e55cc4aa2b5`) is 33 rows, `mainEntity: Organization`. This starter's roster is that set minus the standard rows the table below drops, plus the rows the table after it adds, each with a reason.
@@ -271,7 +289,6 @@ The standard page set for this shape (`derive-roster.py --shape organization-ser
 
 | Standard row                                                         | Reason                                                                                                           |
 | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `TeamList` · `TeamMember`                                            | a placeholder starter has no team to list; `/about` carries the people                                           |
 | `CareersList` · `JobPosting`                                         | a placeholder starter has no open roles                                                                          |
 | `PartnersList` · `Partner`                                           | a placeholder starter has no partners to list                                                                    |
 | `ProjectsList` · `Project`                                           | the portfolio pair (`/portfolio`) is the proof of past work; `/projects` is the signal-collectors sample listing |
@@ -289,7 +306,7 @@ The standard page set for this shape (`derive-roster.py --shape organization-ser
 | `BlogList`                        | every Free scaffold's nav links `/blog` unconditionally (`renderNavConfig`, operator ruling 2026-09-23); the Free teaser serves it, as on organization-product (§ 1.8)                                                        |
 | `LandingPage`                     | the Free `/meet` meeting-types hub is a LandingPage seed, the same generic `[slug]` route serves it through (#6897 D3); the four `/meet/[slug]` BookCall detail seeds ride the `BookCall` type already in the standard roster |
 
-`|S − D| = 13` and `|R| = 18`.
+`|S − D| = 15` and `|R| = 20`.
 
 `/sign-in` and `/sign-up` are also rostered (#6797) — code routes (`kind: route`) with no page type, so they sit outside this set equation: the locale layout's header links both, and the roster of record lists every page the scaffold serves.
 
@@ -326,6 +343,8 @@ organization-service:
     - { route: "/meet/[slug]",      kind: page, content: ["content/en/BookCall/book-a-call.mdx", "content/en/BookCall/onsite-estimate.mdx", "content/en/BookCall/start-project.mdx", "content/en/BookCall/onsite-service.mdx"] }
     - { route: "/portfolio",        kind: page, content: ["content/en/PortfolioList/portfolio.mdx"] }
     - { route: "/portfolio/[slug]", kind: page, contentDir: "content/en/PortfolioItem" }
+    - { route: "/team",             kind: page, content: ["content/en/TeamList/team.mdx"] }
+    - { route: "/team/[slug]",      kind: page, contentDir: "content/en/TeamMember" }
 ```
 
 <!-- generated:end -->
@@ -345,10 +364,10 @@ Every row is module-less: `requires` is `[marketing]` alone, so `mergeRoster` co
 
 <!-- generated:begin inventory -->
 
-| Tier     | Used by this template                                                                                                      |
-| -------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Shell    | `MarketingShell`                                                                                                           |
-| Chrome   | `Nav`, `Footer`, `Banner` (+ `BannerConsentIsland`, `BannerDismissIsland`)                                                 |
-| Sections | `BlogList`, `ContentBlock`, `CTA`, `DocumentChassis`, `FAQ`, `GlossaryIndex`, `Hero`, `Items`, `LogoCloud`, `Testimonials` |
+| Tier     | Used by this template                                                                                                              |
+| -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| Shell    | `MarketingShell`                                                                                                                   |
+| Chrome   | `Nav`, `Footer`, `Banner` (+ `BannerConsentIsland`, `BannerDismissIsland`)                                                         |
+| Sections | `BlogList`, `ContentBlock`, `CTA`, `DocumentChassis`, `FAQ`, `GlossaryIndex`, `Hero`, `Items`, `LogoCloud`, `Team`, `Testimonials` |
 
 <!-- generated:end -->

package/site-templates/shapes/organization-service/ailk-template.json

@@ -6,5 +6,5 @@
     "provenance.json": ".ailk-template.json",
     "TEMPLATE-MANIFEST.json": ".ailk-site-manifest.json"
   },
-  "postInstall": "Starter organization-service installed. Its /faq, /contact, /blog, /meet and its four /meet/<slug> seed pages came with the always-copied overlay; /glossary, /newsletter, /privacy and /terms with the base layer it extends (content/en/). This tree's own /, /about, /services (+ three engagements), /purchase-policy and /portfolio pages are its own compositions. Every line of copy is a placeholder \u2014 replace it before you launch."
+  "postInstall": "Starter organization-service installed. Its /faq, /contact, /blog, /meet and its four /meet/<slug> seed pages came with the always-copied overlay; /glossary, /newsletter, /privacy, /terms, /team and its three /team/<slug> profiles with the base layer it extends (content/en/). This tree's own /, /about, /services (+ three engagements), /purchase-policy and /portfolio pages are its own compositions. Every line of copy is a placeholder \u2014 replace it before you launch."
 }

package/templates/README.md

@@ -66,6 +66,8 @@ The pages of the Free `organization-product` shape, and where each one's copy li
 | `/meet/[slug]`      | `content/en/BookCall/book-a-call.mdx`, `content/en/BookCall/onsite-estimate.mdx`, `content/en/BookCall/start-project.mdx`, `content/en/BookCall/onsite-service.mdx` | every scaffold                 |
 | `/portfolio`        | `content/en/PortfolioList/portfolio.mdx`                                                                                                                            | `--shape organization-product` |
 | `/portfolio/[slug]` | — (a code route)                                                                                                                                                    | `--shape organization-product` |
+| `/team`             | `content/en/TeamList/team.mdx`                                                                                                                                      | `--shape organization-product` |
+| `/team/[slug]`      | — (a code route)                                                                                                                                                    | `--shape organization-product` |
 
 <!-- generated:end -->
 

package/templates/apps/api/CLAUDE.md

@@ -55,6 +55,7 @@ Routes are versioned under `/v1/*`:
 - `/v1/workspaces/:workspaceId/submissions` (GET, `?limit=&state=unhandled&magnetId=`), `/v1/workspaces/:workspaceId/submissions/:leadId` (GET, PATCH) — the Inbox submissions API (#7535, `src/routes/workspaces/submissions.ts` over `src/services/inbox-submissions.ts`): every flow completion and waitlist signup of the caller's active workspace, newest first and bounded (`?limit=` 1–200, default 50), the item read (handled or not), and the one-way idempotent handled stamp (`{ "handled": true }` only, `.strict()`; a second PATCH returns the first `handledAt`). Same registration, scope and tenant guard as the messages bullet above. A submission is a `Lead` whose `source` is a fixed submission source (`SUBMISSION_FIXED_SOURCE_LIST` in `@working-theory/validation`) or `flow:<slug>` for a NON-newsletter magnet of THIS workspace — decided only in `tenantDb(tenant).leads`, never in the route; a `flow:` row naming no magnet of the workspace never lists. The list row is seven keys — the message row's six plus `magnet: { slug, title } | null` — and never `payload`. `?magnetId=` narrows to one magnet (limit 1–50) and adds `answers`, `answersTruncated` and `deliverableSentAt` per row; the item read serves the same three. `answers` is `payload` narrowed by `toAnswers`: server-owned keys dropped, control and bidi characters stripped, every key, value and the entry count bounded. `?state=unhandled` filters `handledAt IS NULL` in the query (the Admin's For-you read); any other `state` is a 400. Every miss on the item read and the PATCH — a malformed, absent or foreign id, a message, an application, a newsletter-magnet lead — is the SAME `404 No such submission`; a `?magnetId=` that is absent, foreign or a newsletter magnet is `404 No such magnet`. Every success body is re-parsed against its own `.strict()` schema before it is sent. Role floor: `inbox-read` on the GETs and `inbox-act` on PATCH (`@working-theory/validation`'s permission table (#7636 D2) — every role, a member included), checked before any read or write. The handlers and the service never log a lead id, email, name or answer. No anonymous MCP twin — identity-bound tenant routes. Each route's twin is a signed-in tool on `/mcp/workspace` (#3591 D13): `list_inbox_submissions` (list), `get_inbox_submission` (item read) and `mark_inbox_submission_done` (PATCH).
 - `/v1/workspaces/:workspaceId/subscribers` (GET, `?limit=`) — the workspace's newsletter signups, read-only (#7535, `src/routes/workspaces/subscribers.ts`): `{ count, items }`, where `count` is every signup and `items` the newest (1–200, default 50), each `{ id, email, source, subscribedAt, magnet: { slug, title } | null }`. A signup is a `Subscriber` row of this workspace or the `Lead` a newsletter-kind magnet of this workspace wrote, both from `tenantDb(tenant).subscribers`, called directly. No item route and no write: a subscriber is never an item to open or mark handled. Same registration, scope, tenant guard and `inbox-read` floor as the submissions bullet above. No MCP twin — identity-bound tenant route (#3591 exception).
 - `/v1/workspaces/:workspaceId/members` (GET) — the org's member roster (`userId`, `name`, `email`, `role`), the Pro `workspace` module's Team tab (#5371). Read-only by design: granting a Membership is the invite flow, which is its own spec with a mandatory security review (§2.3), so no POST/PUT/DELETE is routed at this path. Scoped to `request.tenant.organizationId` — Membership is org-level — server-resolved from the validated session. Role floor: `members-read` (owner, admin — `@working-theory/validation`'s permission table (#7636 D2)): the roster carries every member's email, and who the other members are is not a member's job. No MCP twin — identity-bound tenant route (#3591 exception).
+- `/v1/workspaces/:workspaceId/agents` (GET `?userId=`, POST), `/v1/workspaces/:workspaceId/agents/:agentId/key` (POST), `/v1/workspaces/:workspaceId/agents/:agentId` (PATCH `{ enabled }`), `PUT /v1/workspaces/:workspaceId/agents/:agentId/grants` (`{ grants }`, #7864), and `/v1/agent/context` (GET) — the agent seat (#3591, `src/routes/workspaces/agents.ts` over `src/lib/agent-store.ts`, `// oss: false`). An agent is a stored delegate of one person, bound to one workspace. The five management routes refuse an agent caller outright (403), check `agents-manage` (owner, admin) before any read, and scope every read and write to `tenant.organizationId`, never a body or query value; an agent of another organization is the same 404 as a missing one. Create returns 201 with the key shown once; re-key returns the new key once. Each successful create, re-key, switch and grant change writes an `agents.*` audit record. **Grants (#7864, `docs/specs/7864-agent-key-grants-spec.md`).** An agent acts at `member`, plus any of five permissions an owner or admin granted it one by one — `content-edit`, `content-publish`, `assets-write`, `magnets-manage`, `meeting-types-manage` (`@working-theory/validation`'s `AGENT_GRANTABLE_PERMISSIONS`, held to that set by the `agents_grants_allowed` CHECK). The grant PUT replaces the whole set (an empty list removes every grant) and refuses a grant the agent's person's own role does not hold, `409 grant_exceeds_person`. The clamp is one function both tenant guards call (`services/default-tenant.ts`'s `agentTenant`): an agent holds a stored grant only while its person's role holds it, so a demoted person's agent keeps the row but not the permission. The routes for the five check `allows(tenant, "<permission>")`, which reads the grants; every other check keeps `can(tenant.role, …)`, so no other owner or admin permission is reachable. Every agent write on content, assets and meeting types writes one `recordAgentWrite` row naming the agent and its person (magnets already did); a person's writes there stay unaudited. No grant raises the ceiling. `/v1/agent/context` is the agent's own read, unchanged by grants, and needs no permission beyond the workspace guard. Same registration scope as the routes above (`workspace || multi-tenant`).
 - `/v1/workspaces/:workspaceId/content` (GET, POST), `/v1/workspaces/:workspaceId/content/:type/:slug` (GET, PATCH), `/v1/workspaces/:workspaceId/content/:type/:slug/{publish,unpublish}` (POST) — the tenant-guarded content editor's write surface (#5853, `src/routes/workspaces/content.ts`): list, create, read/save the draft tip (under `If-Match`), and publish/unpublish, all over `Artifact`/`ArtifactVersion`. `:type` is validated against the page-type registry (`z.enum(SCHEMA_ORG_TYPES)`) rather than accepted as a free string on every addressed operation — an unregistered type is a 400 before any lookup, since it is echoed back and passed to `notifyRevalidate` as the site's cache tag. Role floors from `@working-theory/validation`'s permission table (#7636 D2): publish and unpublish need `content-publish`, and create, read and save need `content-edit` (both owner, admin — an admin builds, a member operates). The list serves `content-edit` the editor's full view and a caller holding only `docs-read` (a member) a published-only projection (D4): draft rows dropped, every row `status: "published"`, `version: null`, `valid: true`, and a `published_with_draft` page's `type`/`tags` read from its PUBLISHED version — applied before every filter, so a member's `?status=draft` or a draft tip's `?tag=` matches nothing. **The GET list is a UNION of page artifacts and DOCUMENT assets** (#6093, D1/D9 — "one store, two views"): every row carries `tags: string[]` (never null, read from the draft tip's stored content for a page, from `Asset.tags` for a file) and a DERIVED `kind: "page" | "post" | "file"` (`BlogPosting` alone maps to `"post"`; an asset row is always `"file"`) — an optional `?tag=<slug>` filters the union AFTER it is built, so a file is returned under either its own tag or a shared one. The asset half of the union (`DOCUMENT_CONTENT_TYPES`, i.e. `application/pdf`) is skipped entirely when `locale`/`type` is supplied or `status` names anything but `"published"`, since a file row can never satisfy those. A foreign `:workspaceId` costs zero artifact **and** zero asset queries. No MCP twin — identity-bound tenant routes (#3591 exception, same shape as the sibling `/v1/workspaces/*` routes).
 - `/v1/workspaces/:workspaceId/assets` (GET, POST), `/v1/workspaces/:workspaceId/assets/:assetId` (PATCH, DELETE), `/v1/assets/:assetId` (GET, public/anonymous) — the workspace asset store (#5854 upload/read; #6093 list/PATCH/DELETE, `src/routes/assets/{index,upload,read,manage}.ts`). Upload accepts an allowlisted union of three named classes (`src/routes/assets/index.ts`): five RASTER images (`image/png`, `image/jpeg`, `image/gif`, `image/webp`, `image/avif`), one VECTOR image (`image/svg+xml`, admitted under the operator's 2026-09-18 `allow-svg-assets` ruling — issue #6093 comment `5731573595` — superseding #5854's original SVG exclusion) and one DOCUMENT type (`application/pdf`), all under the existing 20 MB cap; `?tags=<slug>[,<slug>…]` stores tags on the row. The public read serves a RASTER type `inline` exactly as before; every OTHER admitted type (SVG, PDF) is served `attachment`, with the filename's extension pinned to the stored content type (closing extension spoofing) and a five-directive `Content-Security-Policy` (`default-src 'none'; sandbox; frame-ancestors 'none'; form-action 'none'; base-uri 'none'`) that makes the bytes never a document on this origin — this is what makes admitting SVG safe with NO server-side sanitizer. `GET …/assets` (`assets-read` — every role, a member included) lists a workspace's assets, metadata only, never `bytes`, with an optional `?tag=<slug>` filter; this is what narrows the store's prior "nothing lists assets" premise to its precise form — no ANONYMOUS and no CROSS-TENANT enumeration, both still true. `PATCH …/assets/:assetId` updates `title`/`description`/`tags` (`assets-write`, owner and admin, the upload's permission too; `null` clears a text field to SQL `NULL`, `""` stores empty; the asset's `id` and public URL are untouched). `DELETE …/assets/:assetId` (`assets-write`) removes the row and the bytes at the ORIGIN only — already-cached copies elsewhere are not recallable under the year-long `immutable` promise, and no reference check protects a page that still embeds the URL; absent and foreign ids both take the same 404. Every tenant route here is identity-bound; no MCP twin (#3591 exception). The public read has no MCP twin either — it serves bytes to an `<img>`/download, the same boundary `upload.ts` records for its own sibling.
 - `/v1/billing` (GET), `/v1/billing/portal-session` (POST) — org-scoped billing read + Stripe customer-portal session creation. The read stays open to every member (the Admin's plan gate reads it); the portal needs `billing-manage` — the owner alone (`@working-theory/validation`'s permission table (#7636 D2); an admin is refused before any Stripe call). `/v1/billing/usage` (GET) needs `billing-read` (owner, admin).
@@ -161,7 +162,11 @@ sweep's own DB constraint (never a caller-side lock).
 - Don't put session state in `apps/api`. It's stateless.
 - Don't bundle `apps/api` (esbuild, rollup, webpack). Slice specifiers cannot survive it — see `## Deploy path`.
 
-Last updated: 2026-10-04 — doc-sync: the agent seat, step E (#7684) — the messages and submissions bullets now name each route's signed-in MCP twin on `/mcp/workspace` (#3591 D13) in place of the retired no-twin exception — verified against `apps/api/src/routes/workspaces/{messages,submissions}.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-08 — agent key grants (#7864): the agent-seat bullet names `PUT /v1/workspaces/:workspaceId/agents/:agentId/grants`, the five grantable permissions and the person clamp — verified against `apps/api/src/routes/workspaces/agents.ts`, `apps/api/src/services/default-tenant.ts` and `packages/validation/src/schemas/permissions.ts`.
+
+Prior: 2026-10-05 — doc-sync: added the agent seat routes (#3591, #7678) to Endpoint conventions — verified against `apps/api/src/routes/workspaces/agents.ts`.
+
+Prior: 2026-10-04 — doc-sync: the agent seat, step E (#7684) — the messages and submissions bullets now name each route's signed-in MCP twin on `/mcp/workspace` (#3591 D13) in place of the retired no-twin exception — verified against `apps/api/src/routes/workspaces/{messages,submissions}.ts`, `apps/mcp/src/workspace-server.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-04 — doc-sync: roles by job (#7636 PR-A, #7653) — every role floor on the routes above now names its row of `@working-theory/validation`'s permission table (`can(tenant.role, "<permission>")`, no route-local role constant): a member reads and acts on the inbox family, appointments, the waitlist dashboard and listing decisions, reads live-only docs, magnets and meeting types and the asset list, and is refused draft content, workspace settings (the config PUT gained its first check) and agent sessions; an admin manages the calendar connection (audited, other owners emailed) and is refused the billing portal — verified against `apps/api/src/routes/{workspaces,magnets,assets,billing,waitlist-experiments,project-listings}/*.ts`, `apps/api/src/routes/schedule/appointments.ts` and `apps/api/src/services/{leads-inbox,inbox-messages,inbox-submissions,waitlist-dashboard,waitlist-operator-reads,tenant-context}.ts`.
 

package/templates/apps/api/package.json

@@ -15,6 +15,7 @@
     "deliverable:resend": "tsx src/bin/deliverable-resend.ts",
     "seed:presets": "tsx src/bin/seed-presets.ts",
     "spokes": "tsx src/bin/spokes.ts",
+    "flows:copy": "tsx src/bin/flows-copy.ts",
     "build": "tsc",
     "build:vercel": "cd ../../database && pnpm exec prisma generate && cd ../.. && pnpm --filter @working-theory/validation build && pnpm --filter @working-theory/api build && mkdir -p apps/api/public && echo '{}' > apps/api/public/.vercel",
     "start": "node dist/cli.js",

package/templates/apps/api/src/__tests__/factories/agent-caller.ts

@@ -27,13 +27,15 @@ export interface AgentCaller {
   workspaceId: string;
   /** The person's own role; the guard clamps the agent to `member`. */
   role: "owner" | "admin" | "member";
+  /** The agent's stored grants (#7864); the guard keeps those `role` holds. */
+  grants: string[];
   headers: { authorization: string };
 }
 
 export function buildAgentCaller(
   scope: { organizationId: string; workspaceId: string },
   overrides: Partial<
-    Pick<AgentCaller, "agentId" | "userId" | "membershipId" | "role">
+    Pick<AgentCaller, "agentId" | "userId" | "membershipId" | "role" | "grants">
   > = {},
 ): AgentCaller & { key: string } {
   const key = mintAgentKey();
@@ -42,6 +44,7 @@ export function buildAgentCaller(
     userId: "user_00000000-0000-7000-8000-00000000a9e2",
     membershipId: "member_00000000-0000-7000-8000-00000000a9e3",
     role: "member",
+    grants: [],
     ...scope,
     ...overrides,
     key,
@@ -64,6 +67,7 @@ export function agentKeyLookup(
             workspaceId: caller.workspaceId,
             organizationId: caller.organizationId,
             permissionLevel: "member",
+            grants: caller.grants,
             enabled: true,
             keyIssuedToMembershipId: caller.membershipId,
             lastActiveAt: null,

package/templates/apps/api/src/lib/__mocks__/prisma.ts

@@ -70,8 +70,16 @@ export const prisma = {
     // #3591 — `lib/agent-store.ts`'s list names each agent's creator by id.
     findMany: jest.fn(),
     update: jest.fn(),
+    // #7803 — `activateWorkspace` records the remembered workspace on the
+    // caller's own row (tenant-context.ts, spec D3).
+    updateMany: jest.fn(),
     create: jest.fn(),
   },
+  // #7803 — `activateWorkspace` writes the session's active-workspace pointer
+  // in one `$transaction` with the `user.updateMany` above.
+  session: {
+    update: jest.fn(),
+  },
   apiToken: {
     create: jest.fn(),
     findMany: jest.fn(),
@@ -210,6 +218,8 @@ export const prisma = {
     findFirst: jest.fn(),
     findMany: jest.fn(),
     upsert: jest.fn(),
+    // #7844 D7 — `copyFlowDefinition`'s one create-only write.
+    create: jest.fn(),
   },
   // `deleteMany` — used by the FlowSession retention/cleanup sweep
   // (flow-engine.ts's `cleanupAbandonedSessions`, #3974 AC3).

package/templates/apps/api/src/lib/__tests__/agent-store.test.ts

@@ -13,7 +13,10 @@
  *     transaction, and refuses (not found) a workspace of another
  *     organization or a person with no membership there (SEC-3591-15);
  *   - re-keying and switching are scoped by organization: another
- *     organization's agent is "not found", and nothing is written.
+ *     organization's agent is "not found", and nothing is written;
+ *   - setting grants (#7864 D4, AC-4) collapses duplicates into D1 order,
+ *     refuses a grant its person's role does not hold, and is scoped by
+ *     organization like the other writes.
  *
  * Test fixtures never hold a key-shaped literal: every `ailk_agt_` value is
  * built at run time by `mintAgentKey()`, or the repo-wide secret scan flags it.
@@ -36,6 +39,7 @@ import {
   replaceServedAgentKey,
   setAgentEnabled,
   setServedAgentEnabled,
+  setServedAgentGrants,
   touchAgentLastActive,
 } from "../agent-store.js";
 import { prisma } from "../prisma.js";
@@ -71,6 +75,7 @@ const AGENT_ROW = {
   workspaceId: WS_A1,
   responsibleMembershipId: PERSON_MEMBERSHIP,
   permissionLevel: "member",
+  grants: [] as string[],
   enabled: true,
   lastActiveAt: null,
   createdAt: new Date("2026-10-04T00:00:00Z"),
@@ -129,6 +134,7 @@ describe("findAgentByKeyHash", () => {
       workspaceId: WS_A1,
       organizationId: ORG_A,
       permissionLevel: "member",
+      grants: ["content-edit"],
       enabled: true,
       keyIssuedToMembershipId: OWNER_MEMBERSHIP,
       lastActiveAt: null,
@@ -146,6 +152,7 @@ describe("findAgentByKeyHash", () => {
         workspaceId: true,
         organizationId: true,
         permissionLevel: true,
+        grants: true,
         enabled: true,
         keyIssuedToMembershipId: true,
         lastActiveAt: true,
@@ -157,6 +164,7 @@ describe("findAgentByKeyHash", () => {
       workspaceId: WS_A1,
       organizationId: ORG_A,
       permissionLevel: "member",
+      grants: ["content-edit"],
       enabled: true,
       keyIssuedToMembershipId: OWNER_MEMBERSHIP,
       lastActiveAt: null,
@@ -399,6 +407,110 @@ describe("the served writes (route-facing)", () => {
   });
 });
 
+describe("setServedAgentGrants (#7864 D4, AC-4)", () => {
+  /** The row the transaction reads: the agent with its person's role. */
+  function agentWithRole(role: string, grants: string[] = []) {
+    return { organizationId: ORG_A, grants, responsible: { role } };
+  }
+  let listGrants: string[];
+
+  beforeEach(() => {
+    listGrants = [];
+    (prisma.agent.updateMany as jest.Mock).mockImplementation(
+      ({ data }: { data: { grants: string[] } }) => {
+        listGrants = data.grants;
+        return Promise.resolve({ count: 1 });
+      },
+    );
+    (prisma.agent.findMany as jest.Mock).mockImplementation(() =>
+      Promise.resolve([
+        {
+          ...AGENT_ROW,
+          grants: listGrants,
+          responsible: { userId: PERSON, user: { name: "Pat", email: "pat@example.test" } },
+          keyIssuedTo: { userId: OWNER, user: { name: "Olive" } },
+        },
+      ]),
+    );
+    (prisma.user.findMany as jest.Mock).mockResolvedValue([{ id: OWNER, name: "Olive" }]);
+  });
+
+  it("writes the set in D1 order with duplicates collapsed, in one transaction, and serves the list row", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(agentWithRole("admin", ["assets-write"]));
+
+    const result = await setServedAgentGrants({
+      organizationId: ORG_A,
+      agentId: AGENT,
+      grants: ["magnets-manage", "content-edit", "magnets-manage"],
+    });
+
+    expect(prisma.$transaction).toHaveBeenCalledTimes(1);
+    expect(prisma.agent.findUnique).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      select: { organizationId: true, grants: true, responsible: { select: { role: true } } },
+    });
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: { grants: ["content-edit", "magnets-manage"] },
+    });
+    expect(result).toMatchObject({
+      ok: true,
+      agent: { id: AGENT, grants: ["content-edit", "magnets-manage"] },
+      previous: ["assets-write"],
+    });
+  });
+
+  it("an empty set removes every grant", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(
+      agentWithRole("owner", ["content-edit", "content-publish"]),
+    );
+    const result = await setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: [] });
+    expect(prisma.agent.updateMany).toHaveBeenCalledWith({
+      where: { id: AGENT, organizationId: ORG_A },
+      data: { grants: [] },
+    });
+    expect(result).toMatchObject({ ok: true, agent: { grants: [] }, previous: ["content-edit", "content-publish"] });
+  });
+
+  it("refuses a grant its person's role does not hold, and writes nothing", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValue(agentWithRole("member"));
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "exceeds-person" });
+    expect(prisma.agent.updateMany).not.toHaveBeenCalled();
+    expect(prisma.agent.findMany).not.toHaveBeenCalled();
+  });
+
+  it("is not-found for an unknown agent or one of another organization, and writes nothing", async () => {
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValueOnce(null);
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+
+    (prisma.agent.findUnique as jest.Mock).mockResolvedValueOnce({
+      ...agentWithRole("owner"),
+      organizationId: ORG_B,
+    });
+    await expect(
+      setServedAgentGrants({ organizationId: ORG_A, agentId: AGENT, grants: ["content-edit"] }),
+    ).resolves.toEqual({ ok: false, reason: "not-found" });
+    expect(prisma.agent.updateMany).not.toHaveBeenCalled();
+  });
+
+  it("the list row serves only the five, in D1 order, whatever the row holds", async () => {
+    (prisma.agent.findMany as jest.Mock).mockResolvedValue([
+      {
+        ...AGENT_ROW,
+        grants: ["meeting-types-manage", "content-edit", "agents-manage"],
+        responsible: { userId: PERSON, user: { name: "Pat", email: "pat@example.test" } },
+        keyIssuedTo: null,
+      },
+    ]);
+    const [row] = await listAgentsForOrganization(ORG_A);
+    expect(row?.grants).toEqual(["content-edit", "meeting-types-manage"]);
+  });
+});
+
 describe("listAgentsForOrganization", () => {
   beforeEach(() => {
     (prisma.agent.findMany as jest.Mock).mockResolvedValue([
@@ -423,6 +535,7 @@ describe("listAgentsForOrganization", () => {
         workspaceId: WS_A1,
         responsible: { userId: PERSON, name: "Pat", email: "pat@example.test" },
         permissionLevel: "member",
+        grants: [],
         enabled: true,
         lastActiveAt: null,
         createdAt: AGENT_ROW.createdAt,

package/templates/apps/api/src/lib/__tests__/site.test.ts

@@ -17,6 +17,9 @@
  * (#6228): the assertion's first arm now skips on any OTHER adapter, so a
  * case that means to exercise the REAL resolution must say which adapter it
  * is booting under rather than inherit whatever the ambient env holds.
+ *
+ * `describe("site stamp (#7868)")` covers the Checkout `metadata.site` stamp
+ * and the webhook's foreign-site test (spec D2/D7).
  */
 
 // eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); __mocks__/prisma.ts is the repo-standard test double for this boundary.
@@ -28,7 +31,9 @@ import {
   __resetSiteWorkspaceCacheForTests,
   assertSiteAliasResolves,
   currentSiteId,
+  isForeignSiteStamp,
   resolveSiteWorkspaceId,
+  siteStamp,
 } from "../site.js";
 
 const DEFAULT_ORG_ID = "org_00000000-0000-7000-8000-000000000001";
@@ -236,3 +241,52 @@ describe("assertSiteAliasResolves — the #6228 content-adapter carve-out (arm 0
     expect(prisma.workspace.findUnique).toHaveBeenCalled();
   });
 });
+
+describe("site stamp (#7868)", () => {
+  // Stripe types metadata values as strings; a non-string arrives only from a
+  // malformed payload, so the fixture is cast at this one boundary.
+  const nonStringStamp: Record<string, unknown> = { site: 42 };
+
+  it("siteStamp() with AILK_SITE_ID unset stamps the default alias", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(siteStamp()).toEqual({ site: "default" });
+  });
+
+  it("siteStamp() follows AILK_SITE_ID, read per call", () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    expect(siteStamp()).toEqual({ site: PINNED_WORKSPACE_ID });
+  });
+
+  it("siteStamp() is empty when AILK_SITE_ID is the empty string — Stripe is never sent an empty value (SEC-7868-5)", () => {
+    process.env.AILK_SITE_ID = "";
+    expect(siteStamp()).toEqual({});
+  });
+
+  it.each([
+    ["undefined metadata", undefined],
+    ["null metadata", null],
+    ["no stamp", {}],
+    ["an empty stamp", { site: "" }],
+    ["the own stamp", { site: "default" }],
+    ["a non-string stamp", nonStringStamp as Record<string, string>],
+  ])("isForeignSiteStamp is false for %s (unstamped is own, roadmap D4)", (_label, metadata) => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp(metadata)).toBe(false);
+  });
+
+  it("isForeignSiteStamp is true for another site's stamp", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp({ site: "samhenry" })).toBe(true);
+  });
+
+  it("isForeignSiteStamp compares exactly — a case-folded own alias is foreign", () => {
+    delete process.env.AILK_SITE_ID;
+    expect(isForeignSiteStamp({ site: "Default" })).toBe(true);
+  });
+
+  it("isForeignSiteStamp reads the alias per call, not once at import", () => {
+    process.env.AILK_SITE_ID = PINNED_WORKSPACE_ID;
+    expect(isForeignSiteStamp({ site: PINNED_WORKSPACE_ID })).toBe(false);
+    expect(isForeignSiteStamp({ site: "default" })).toBe(true);
+  });
+});

package/templates/apps/api/src/lib/agent-store.ts

@@ -27,13 +27,25 @@
  *     `findAgentByKeyHash` and `touchAgentLastActive` only;
  *   - the management routes (`routes/workspaces/agents.ts`) call the rest.
  *
- * Nothing caches a row: a switch-off, a re-key or a removed membership takes
- * effect on the next request.
+ * GRANTS (#7864, spec docs/specs/7864-agent-key-grants-spec.md D2–D4). An
+ * agent's row carries the permissions an owner or admin granted it one by one
+ * — only the five `AGENT_GRANTABLE_PERMISSIONS`. `setServedAgentGrants` is
+ * the column's only writer, and refuses a grant its person's own role does
+ * not hold; the tenant guards apply the same rule on every request, so a
+ * grant stored before a demotion is held to the person's current role.
+ *
+ * Nothing caches a row: a switch-off, a re-key, a grant change or a removed
+ * membership takes effect on the next request.
  */
 import { createHash, randomBytes } from "node:crypto";
 
 import type { Id } from "@working-theory/ids";
-import type { AgentPermissionLevel } from "@working-theory/validation";
+import {
+  AGENT_GRANTABLE_PERMISSIONS,
+  can,
+  type AgentGrantablePermission,
+  type AgentPermissionLevel,
+} from "@working-theory/validation";
 
 import { prisma } from "./prisma.js";
 
@@ -71,6 +83,21 @@ export interface AgentGrant {
   organizationId: Id<"organization">;
   responsibleMembershipId: Id<"membership">;
   permissionLevel: AgentPermissionLevel;
+  /**
+   * The grants stored on the row (#7864 D3). The tenant guards keep only
+   * those its person's role also holds (`agentTenant`).
+   */
+  grants: readonly string[];
+}
+
+/**
+ * A stored grant set in `AGENT_GRANTABLE_PERMISSIONS` order, without
+ * duplicates and without anything outside the five.
+ */
+function orderedGrants(
+  grants: readonly string[],
+): AgentGrantablePermission[] {
+  return AGENT_GRANTABLE_PERMISSIONS.filter((p) => grants.includes(p));
 }
 
 // ── The auth preHandler's three functions ────────────────────────────────────
@@ -80,6 +107,8 @@ export interface AgentKeyRow {
   workspaceId: string;
   organizationId: string;
   permissionLevel: AgentPermissionLevel;
+  /** `undefined` only from a test double; the auth preHandler reads it as none. */
+  grants: string[] | undefined;
   enabled: boolean;
   keyIssuedToMembershipId: string | null;
   lastActiveAt: Date | null;
@@ -97,6 +126,7 @@ export async function findAgentByKeyHash(
       workspaceId: true,
       organizationId: true,
       permissionLevel: true,
+      grants: true,
       enabled: true,
       keyIssuedToMembershipId: true,
       lastActiveAt: true,
@@ -180,6 +210,12 @@ interface SetAgentEnabledParams {
   enabled: boolean;
 }
 
+interface SetAgentGrantsParams {
+  organizationId: string;
+  agentId: string;
+  grants: readonly AgentGrantablePermission[];
+}
+
 /**
  * Add an agent for `responsibleUserId`, bound to `workspaceId`. The returned
  * `key` is the only copy that will ever exist: the caller shows it once.
@@ -280,6 +316,58 @@ export async function setServedAgentEnabled(
   });
 }
 
+/** A grant set the agent's person's own role does not wholly hold. */
+export type AgentGrantExceedsPerson = { ok: false; reason: "exceeds-person" };
+export type ServedAgentGrants = ServedAgent & {
+  /** The grants stored before this write, in D1 order — for the audit row. */
+  previous: AgentGrantablePermission[];
+};
+
+/**
+ * Replace an agent's grants with `grants` (#7864 D4) and answer with its list
+ * row. One transaction: the agent is read by id inside the caller's
+ * organization, with its responsible person's role; any requested grant that
+ * role does not hold refuses the whole set (`exceeds-person`) and writes
+ * nothing. An agent of another organization, or none, is `not-found`.
+ */
+export async function setServedAgentGrants(
+  params: SetAgentGrantsParams,
+): Promise<ServedAgentGrants | AgentNotFound | AgentGrantExceedsPerson> {
+  return prisma.$transaction(async (tx) => {
+    const current = await tx.agent.findUnique({
+      where: agentScope(params),
+      select: {
+        organizationId: true,
+        grants: true,
+        responsible: { select: { role: true } },
+      },
+    });
+    if (!current || current.organizationId !== params.organizationId) {
+      return { ok: false, reason: "not-found" } as const;
+    }
+    const grants = orderedGrants(params.grants);
+    if (!grants.every((grant) => can(current.responsible.role, grant))) {
+      return { ok: false, reason: "exceeds-person" } as const;
+    }
+    const { count } = await tx.agent.updateMany({
+      where: agentScope(params),
+      data: { grants },
+    });
+    if (count !== 1) return { ok: false, reason: "not-found" } as const;
+    const [agent] = await readAgentListRows(
+      { id: params.agentId, organizationId: params.organizationId },
+      tx,
+    );
+    return agent
+      ? ({
+          ok: true,
+          agent,
+          previous: orderedGrants(current.grants),
+        } as const)
+      : ({ ok: false, reason: "not-found" } as const);
+  });
+}
+
 /** The list row of a just-written agent, read on the write's own client. */
 async function servedWith(
   db: AgentDb,
@@ -392,6 +480,8 @@ export interface AgentListRow {
   workspaceId: string;
   responsible: { userId: string; name: string | null; email: string };
   permissionLevel: AgentPermissionLevel;
+  /** The stored grants (#7864 D4), in `AGENT_GRANTABLE_PERMISSIONS` order. */
+  grants: AgentGrantablePermission[];
   enabled: boolean;
   lastActiveAt: Date | null;
   createdAt: Date;
@@ -431,6 +521,7 @@ async function readAgentListRows(
       name: true,
       workspaceId: true,
       permissionLevel: true,
+      grants: true,
       enabled: true,
       lastActiveAt: true,
       createdAt: true,
@@ -466,6 +557,7 @@ async function readAgentListRows(
       email: r.responsible.user.email,
     },
     permissionLevel: r.permissionLevel,
+    grants: orderedGrants(r.grants),
     enabled: r.enabled,
     lastActiveAt: r.lastActiveAt,
     createdAt: r.createdAt,

package/templates/apps/api/src/lib/site.ts

@@ -20,6 +20,14 @@
  * `currentSiteId()` async would edit every one of its dozen non-test call
  * sites across routes/services/bins, including the two route files NFR1
  * requires to stay byte-unchanged.
+ *
+ * The Checkout site stamp (#7868, spec D1/D2): `SITE_STAMP_KEY`,
+ * `siteStamp()` and `isForeignSiteStamp()` are the one definition of the
+ * `metadata.site` key every hub-created Checkout session carries and the
+ * Stripe webhook reads. The stamp is `currentSiteId()`, so writer and reader
+ * cannot disagree inside one deployment. A session is foreign only when its
+ * stamp is a non-empty string other than `currentSiteId()`; an unstamped
+ * session is the hub's own (roadmap D4).
  */
 import { resolvedAdapterKind } from "@working-theory/content-adapters";
 import {
@@ -35,6 +43,35 @@ export function currentSiteId(): string {
   return process.env.AILK_SITE_ID ?? "default";
 }
 
+/** The Checkout session metadata key naming the site a session belongs to (#7868 D1). */
+export const SITE_STAMP_KEY = "site";
+
+/**
+ * The metadata a hub-created Checkout session carries (#7868 D1/D2):
+ * `{ [SITE_STAMP_KEY]: currentSiteId() }`, read per call. Empty when the alias
+ * is `""` (an `AILK_SITE_ID` set to the empty string), so Stripe is never sent
+ * an empty value (SEC-7868-5) — and the webhook treats that deployment's
+ * sessions as unstamped, exactly as today.
+ */
+export function siteStamp(): Record<string, string> {
+  const site = currentSiteId();
+  return site === "" ? {} : { [SITE_STAMP_KEY]: site };
+}
+
+/**
+ * True only when `metadata[SITE_STAMP_KEY]` is a non-empty string that is not
+ * `currentSiteId()` — a session another site on the shared Stripe account
+ * opened (#7868 D2). An absent, empty or non-string stamp is the hub's own
+ * (roadmap D4: Payment Links, invoices, the portal and pre-stamp sessions
+ * carry none). Exact, case-sensitive comparison, as the spokes' own check.
+ */
+export function isForeignSiteStamp(
+  metadata: Record<string, string> | null | undefined,
+): boolean {
+  const stamp: unknown = metadata?.[SITE_STAMP_KEY];
+  return typeof stamp === "string" && stamp !== "" && stamp !== currentSiteId();
+}
+
 /**
  * The resolved workspace id, memoized after the first SUCCESSFUL resolution
  * ("resolves the alias once at startup", ownership brief § Layer 2 / #6155