create-ailk 0.26.0 → 0.28.0

package/templates/apps/api/src/__tests__/vercel-handler.test.ts

@@ -633,4 +633,41 @@ describe('vercel-handler — the request log carries no query string (#5970)', (
     });
     expect(JSON.stringify(logger.info.mock.calls)).not.toContain('SUPERSECRETTOKEN');
   });
+
+  it.each([
+    '/v1/webhooks/stripe/whk_SECRETTOKEN123?x=1',
+    '/x/../v1/webhooks/stripe/whk_SECRETTOKEN123?x=1',
+    '/v1/./webhooks/stripe/whk_SECRETTOKEN123?x=1',
+  ])('logs a secret-bearing path segment redacted, and routes on the raw path: %s (#9969 D6)', async (target) => {
+    const inject = jest.fn().mockResolvedValue({
+      statusCode: 200,
+      headers: {},
+      body: 'ok',
+      rawPayload: Buffer.from('ok'),
+    });
+    jest.doMock('../server', () => ({ build: jest.fn().mockResolvedValue({ inject }) }));
+    const handler = loadHandler();
+
+    const req: MockVercelRequest = {
+      method: 'POST',
+      url: target,
+      headers: {},
+      body: undefined,
+      query: { x: '1' },
+    };
+    await handler(asRequest(req), asResponse(makeRes()));
+
+    const { logger } = require('@working-theory/observability') as {
+      logger: { info: jest.Mock };
+    };
+    const startCall = logger.info.mock.calls.find(
+      ([, msg]) => msg === '[Vercel Handler] Starting request',
+    );
+    expect(startCall?.[0]).toEqual({
+      method: 'POST',
+      pathname: '/v1/webhooks/stripe/:connectionToken',
+    });
+    expect(JSON.stringify(logger.info.mock.calls)).not.toContain('whk_SECRETTOKEN123');
+    expect(inject.mock.calls[0][0]).toMatchObject({ url: '/v1/webhooks/stripe/whk_SECRETTOKEN123' });
+  });
 });

package/templates/apps/api/src/vercel-handler.ts

@@ -4,6 +4,7 @@
  */
 
 import type { VercelRequest, VercelResponse } from "@vercel/node";
+import { redactLogPath } from "@working-theory/api";
 import { logger } from "@working-theory/observability";
 import type { InjectOptions } from "fastify";
 
@@ -169,11 +170,17 @@ export default async function handler(
     //
     // Derived once, above the first log line, and used by both — the pathname
     // was already computed below and logged safely there, three lines too late.
+    //
+    // The query strip is #5970's control; a credential in a path SEGMENT — a
+    // webhook connection token, a `cs_…` session id — is `redactLogPath`'s,
+    // the same function Fastify's request serializer calls (#9969 D6, #9262).
+    // It reads the RESOLVED `pathname`, the one the request is routed on, so a
+    // dot-segment target (`/x/../v1/webhooks/…`) cannot put a token past it.
     const url = new URL(req.url || "/", "http://localhost");
     const pathname = url.pathname;
 
     logger.info(
-      { method: req.method, pathname },
+      { method: req.method, pathname: redactLogPath(pathname) },
       "[Vercel Handler] Starting request",
     );
 

package/templates/apps/api/vercel.json

@@ -13,5 +13,11 @@
   ],
   "env": {
     "NODE_ENV": "production"
-  }
+  },
+  "crons": [
+    {
+      "path": "/v1/cron/prospect-channel-archive",
+      "schedule": "0 7 * * *"
+    }
+  ]
 }

package/templates/apps/mcp/CLAUDE.md

@@ -71,14 +71,19 @@ now mean `packages/mcp-server/src/<file>`.
   started from the repo root — anywhere else the file is absent and so is the tool, where it
   could not run anyway (no `dist/cli.js`). The scope FILE alone decides — a release-scope
   decision, never a licence check, and the CLI's `AILK_RELEASE_SCOPE=ignore` bypass is not
-  honoured; a missing or unreadable file fails closed with one stderr line. apps/web's
-  `/.well-known/mcp.json` drops it on the same read (`apps/web/lib/release-scope.ts`).
+  honoured; a missing or unreadable file fails closed with one stderr line. It is served over
+  **stdio only** (#9965 D13, #8584): it spawns a filesystem-writing CLI, so
+  `createMcpServer()` and `listRegisteredTools()` default to the HTTP transport, which never
+  registers it, and only `run.ts`'s stdio branch passes `{ transport: "stdio" }`; the
+  call-time gate asks for the transport the server was built with. apps/web's
+  `/.well-known/mcp.json` describes the HTTP surface, so it always drops it.
 
 ### What a spoke's MCP host on Vercel enforces
 
 - **The address is the caller's, behind exactly one proxy.** The Vercel entry trusts one hop
   (`trustOneHop`, `src/serverless-app.ts`), so the limits key on the address Vercel's edge
-  saw and a caller's own `X-Forwarded-For` cannot move the key. This holds when the MCP host
+  saw and a caller's own `X-Forwarded-For` cannot move the key. It trusts that hop only on
+  Vercel (`VERCEL=1`); reused anywhere else it trusts nothing and keys on the socket (#8080). This holds when the MCP host
   name points straight at the Vercel project; a second proxy in front keys every caller on
   that proxy. It is a function, not `trustProxy: 1`, because Fastify 5.12 treats a numeric
   hop count as trusting nothing. The long-running entry trusts no proxy.
@@ -116,11 +121,11 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 
 **Read (9):** `list_pages`, `read_content`, `search_content`, `get_site_info`, `get_business_hours`, `get_locations`, `get_offerings`, `get_pricing`, `get_faq`. The first three adopted their `apps/api` routes' arguments and results (#7167, #7168, #7169 — the operator's decision of 2026-10-19): `search_content` takes `q` and answers the route's `ItemList` (`query`, `items`, `totalItems`); `list_pages` requires `type`, takes `page`/`pageSize` and answers the paginated `ItemList` (`items`, `pagination`); `read_content` takes `include` and answers the page's JSON-LD at the root with `page`, plus `body` only with `include: "body"` — a miss is the not-found body. Each parses the same `@working-theory/validation` export its route parses with and answers through the same `@working-theory/content-adapters` builder, so the parity guard holds them as `twin`s
 **Conversion-write (3):** `capture_lead`, `subscribe_newsletter`, `request_callback` — each takes the body its `POST /v1/leads/{submit,subscribe,callback}` route parses (`leadSubmitBodySchema`: `source`, `email`, `consent`, `payload`; `leadSubscribeBodySchema`: `email`, `source`; `leadCallbackBodySchema`: `name`, `phone`, `preferredTime`, `payload`) and returns the route's 201 body `{ id, persisted, email }` unchanged (#7171, #7172, #7173 — the operator's decision of 2026-10-19), so the parity guard holds the three as `twin`s. `source` is the agent's to choose — `mcp` unless the operator says otherwise — and a consent-bearing source needs `consent: true`, exactly as a form does; `capture_lead` still spreads the spoke marker `payload.site` from `AILK_LEAD_SITE` last. The AbuseGuard reads the first two's `email` at the top level, else inside `payload` (the route lifts it from there), so a malformed address is refused wherever it sits
-**Maintenance (2):** `audit`, `create_project`
+**Maintenance (2):** `audit`, `create_project` (stdio only, #9965 D13)
 **Flow (2):** `get_flow`, `submit_flow_step` — module-gated (`module: "signal-collectors"`, D-48, #5366) and licence-feature-tagged (`feature: "flows-deliverables"`, #7136): identity-blind like every tool in this list, registered only when the signal-collectors module is present, and gated on the deployment's `flows-deliverables` licence feature under `MCP_FEATURE_GATE_MODE`, the same shape Booking below has. `submit_flow_step` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_SUBMIT_FLOW_STEP_DAILY_CAP`, default 50 — #8071)
 **Booking (4):** `list_availability`, `get_event_meta`, `list_meetings`, `create_booking` — module-gated (`module: "scheduling"`) and licence-feature-tagged (`feature: "scheduling"`, #7136), gated on the deployment's `scheduling` licence feature under `MCP_FEATURE_GATE_MODE`. `create_booking` takes the HTTP write branch (its own daily cap, `MCP_ABUSE_CREATE_BOOKING_DAILY_CAP`, default 20, and an `attendee.email` format check — #8071). `list_meetings` (#8843 D5) twins `GET /v1/schedule/meetings`: it takes no argument and returns the site's Live meetings — slug, visibility, position and whether each can be booked, plus a bookable one's calLink, title, length, description and price; `private` means unlisted, not secret
 
-### Why the parity test counts 21 and a keyless server registers 19 (20 once Free is released)
+### Why the parity test counts 21 and a keyless server registers 19 (20 over stdio once Free is released)
 
 - **21 in the `TOOLS` array / parity test**: the `TOOLS` array in
   `packages/metadata/src/mcp-tool-catalog.ts` defines 21 anonymous tools; the
@@ -128,16 +133,17 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   workspace tools (#3591), which no anonymous view returns — see § The
   signed-in workspace surface below.
 - **19 registered on a KEYLESS deployment, 20 on a commerce-claimed one,
-  while the Free level is held — 20 and 21 once it is released**
-  (#5971, #9534): `createMcpServer` (`apps/mcp/src/server.ts`) registers
+  while the Free level is held or over HTTP — 20 and 21 over stdio once it is
+  released** (#5971, #9534, #9965 D13): `createMcpServer` (`apps/mcp/src/server.ts`) registers
   `getMcpToolRegistrations()` minus the topology seam's `UNSERVED_MCP_TOOLS`,
   minus `create_project` while create-ailk's `release-scope.json` holds
-  `levels.free` (the release-scope filter, #9534), minus `OSS_DISABLED_TOOLS`
+  `levels.free` (the release-scope filter, #9534) and on any transport but
+  stdio (the transport filter, #9965 D13), minus `OSS_DISABLED_TOOLS`
   (now empty), minus module-gated tools whose module is off, minus any
   `addon`-tagged tool whose claim this deployment does not hold.
   `start_purchase` carries `addon: "commerce"`, so it is the one entry whose
   presence depends on the licence — one fewer without the claim.
-- **19 free anonymous tools while Free is held (20 released)**: since #5853 retired the three content-write
+- **19 free anonymous tools while Free is held or over HTTP (20 over stdio once released)**: since #5853 retired the three content-write
   tools, every registered tool remains anonymous — call-time gating checks a
   licence claim, never an identity. The six carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
@@ -277,7 +283,9 @@ Example (lead routing):
 - Don't add a tool without the matching `apps/api` endpoint.
 - Don't put business logic in tool handlers — they're adapters.
 
-Last updated: 2026-10-24 — #9749: `get_slack_connection_status` (`mcp-workspace`'s `slack_connection.ts`) and `get_prospect_channel_settings` / `set_prospect_channel_settings` (`mcp-scheduling`'s `prospect_channel_settings.ts`, the first signed-in handlers outside `mcp-workspace`) twin the Slack status read and the prospect-channel settings pair — the signed-in workspace surface is thirty-one tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts`, `packages-paid/mcp-scheduling/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+Last updated: 2026-10-26 — #9965 (D12, D13): `create_project` is served over stdio only — the HTTP transport, the default, never registers it, and the web manifest always drops it — and `trustOneHop` trusts its hop only on Vercel — verified against `packages/mcp-server/src/{server,run,serverless-app}.ts` and `apps/web/app/.well-known/mcp.json/route.ts`.
+
+Prior: 2026-10-24 — #9749: `get_slack_connection_status` (`mcp-workspace`'s `slack_connection.ts`) and `get_prospect_channel_settings` / `set_prospect_channel_settings` (`mcp-scheduling`'s `prospect_channel_settings.ts`, the first signed-in handlers outside `mcp-workspace`) twin the Slack status read and the prospect-channel settings pair — the signed-in workspace surface is thirty-one tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts`, `packages-paid/mcp-scheduling/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
 
 Prior: 2026-10-24 — #9714: `list_people` (`people_list.ts`) twins `GET /v1/workspaces/:workspaceId/people` in both its modes — the signed-in workspace surface is twenty-eight tools — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
 

package/templates/apps/web/.env.example

@@ -47,6 +47,28 @@ CONTENT_ADAPTER=mdx
 # NEXT_PUBLIC_; see the repo-root .env.example, #7394). A cross-site post is
 # refused before the hub is called.
 #
+# THE BOT CHECK (#9889, #9255). On Vercel, every public write a visitor sends
+# asks Vercel BotID for a verdict before the hub is called: the relay's
+# POST /v1/leads/submit, /v1/leads/subscribe, /v1/leads/callback and
+# /v1/schedule/book, and the site's lead, flow and checkout Server Actions
+# (contact, careers, newsletter, flow step, flow checkout, saved
+# recommendation, /dev/purchase). A bot is refused (403 bot_detected on the
+# relay; the form's own error from an action), so no lead, booking or Slack
+# invite exists. A real visitor sees no extra step, except that a form posted
+# before the page has finished loading (or with JavaScript off) carries no
+# challenge and is refused like a bot; resubmitting works. It is ON by
+# default: set AILK_BOT_CHECK to `off` to turn every check off, or
+# AILK_BOOKING_BOT_CHECK to `off` to turn off the booking's alone (any other
+# value leaves a check on). Off Vercel it cannot run, so it is inert and the
+# server logs that once. On Vercel it needs the project's OIDC token (on by
+# default): without it every checked write is refused as unavailable (503
+# bot_check_unavailable on the relay), as when BotID cannot answer. A
+# self-hosted or local `next start` must not carry VERCEL=1 (as `vercel env
+# pull` writes it), or every checked write is refused. Basic or Deep Analysis
+# is the Vercel project's own setting; Deep Analysis is billed per check.
+# AILK_BOT_CHECK=
+# AILK_BOOKING_BOT_CHECK=
+#
 # EDGE PRECONDITION: the relay forwards x-forwarded-for exactly as this site
 # received it, so run the site behind an edge that OVERWRITES the client-address
 # headers (as Vercel does), not one that appends to them. Otherwise a caller
@@ -155,6 +177,11 @@ CONTENT_ADAPTER=mdx
 # passes its own origin check and the emailed reset link is built on the
 # attacker's host. It is a conjunct of resetSendConfigured(), so a deployment
 # that has not pinned its origin does not offer reset at all.
+#
+# REQUIRED in production (#8620, #9965 D10): apps/web/auth.ts THROWS when
+# Better Auth is first built without it, outside the build phase, as it does
+# without BETTER_AUTH_SECRET. Every page that reads the session then fails, not
+# only sign-in. It must be an https: URL (http: only on a loopback host).
 # BETTER_AUTH_URL=http://localhost:3000
 #
 # Secret used to sign session cookies AND the email-verification tokens.

package/templates/apps/web/CLAUDE.md

@@ -14,7 +14,7 @@ Inherits root `CLAUDE.md`. This file adds web-specific rules.
 
 ## Always do first
 
-- For any UI work: read § Theme & styling and § Iterate visually below before writing code. To add a whole page, run the `/ailk:add-page` skill.
+- For any UI work: read § Theme & styling and § Iterate visually below before writing code. To add a whole page, run `/ailk:growth-ops page add`.
 - For any page-rendering or schema-emission work: read `packages/schema/README.md` (catalog) and `packages/schema/CLAUDE.md` (operational layer + component map) if you haven't this session.
 - For content authoring questions: read `content/CLAUDE.md` first.
 - For a full page build, follow the per-page loop (Content intent → Layout → Author content → Visual iterate). The visual-iterate step uses `screenshots/` as scratch (see § Iterate visually).
@@ -43,7 +43,7 @@ Raw HTML is allowed only when no `@working-theory/ui` component fits. Flag it in
 - Animations: only `transform` and `opacity`. Never `transition-all`.
 - Every interactive element needs hover, focus-visible, and active states.
 
-The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`.
+The four widths above are the responsive contract. Brand reference files (logos, photos, colour and type notes) live in `brand_assets/` at the repo root; the site's own brand colours and fonts are set in `content/_site.mdx` under `brand.colors` and `brand.fonts`. The signed-out header button is set there too, as `header.cta` (`label`, `href`), with `header.signIn: link | hidden` choosing whether Sign in stays beside it as a text link — never by editing `app/[locale]/layout.tsx`. Each page's chrome is set there too (#10049, resolved by `lib/page-chrome.ts`): `header.style` (`full | bare | none`), `footer.style` (`columns | centered | closing | none`), `layout` (`deck | default`, the home's) and one `{ header, footer }` key per route family (`blog`, `docs`, `services`, …), with a page's own `header:` / `footer:` / `layout:` frontmatter winning over all of them.
 
 ## Local dev
 
@@ -149,6 +149,21 @@ exists, deleting the user if that write fails. A request with no `metadata`
 between the user and grant inserts leaves a user with no grant, whom the
 account interstitial stops.
 
+**The hub asks once per spoke before it signs a person in to it (#9966 D2).**
+`app/api/auth/hub/authorize/route.ts`'s GET never says yes for anyone: when
+the API answers `403 consent_required` — no unrevoked grant for that
+(person, spoke) carrying the `consent` scope — it seals the six authorize
+keys and 303s to `(authed)/account/connect?ref=…`. That page names the spoke
+from the registry (`hubSignIn.clientInfo`), renders its form only when the
+ref's `redirect_uri` is on the registry's origin, answers `referrer:
+same-origin`, and 404s on a spoke build. Its Continue is a form POST of `ref`
+to the same route, which accepts only `Sec-Fetch-Site: same-origin` with the
+pinned `Origin` (a missing or `null` one is refused) and is the one call site
+that sends `consent: true` — beside `x-internal-auth` under the Offerings buy
+route's rule, since the API honours consent only with it where
+`OSS_API_INTERNAL_SECRET` is set. A password reset or a sign-out revokes the
+grant, so the next sign-in asks again. `ref` is in both telemetry scrub lists.
+
 ## Contact page
 
 The contact page (`apps/web/app/[locale]/contact/page.tsx`) renders the
@@ -305,7 +320,9 @@ records (#8849):
   `noindex, follow` and full-screen. Next.js serves the static `apply`
   segment first, the `[slug]/[detail]` idiom; every other action 404s. Lead
   capture is never-gate, so every tier takes an application. Both apply pages
-  read the posting's title through `lib/posting-title.ts`.
+  read the posting's title through `lib/posting-title.ts`. A posting's
+  `applicationFlow: <magnet slug>` picks the magnet both pages run (#10054);
+  an unknown slug falls back to the Job application and is logged.
 
 ## Meeting pages
 
@@ -489,10 +506,12 @@ one `[offerings-checkout] refused reason=<reason>` warning; no response or
 log line carries the key. It sends `OSS_API_INTERNAL_SECRET` as
 `x-internal-auth` only from a site that is not a spoke and only to an
 `https:` or loopback API, so the hub's own `apps/web` must hold the API's
-value when the API sets it. A spoke never holds that secret: it sells only
-when its hub lists the spoke's origin in `AILK_TRUSTED_ORIGINS` and does not
-set `OSS_API_INTERNAL_SECRET`, and otherwise every spoke buy returns to
-`/pricing`.
+value when the API sets it. A spoke never holds that secret: on a hub that
+sets `OSS_API_INTERNAL_SECRET` its spoke key authenticates the buy, which
+sells when the spoke's hub sign-in client is enabled with its callback on the
+spoke's own origin (#9910); on a hub that does not set it, the buy sells when
+the hub lists the spoke's origin in `AILK_TRUSTED_ORIGINS`. Otherwise every
+spoke buy returns to `/pricing`.
 
 An existing scaffold adopts the new page by bringing
 `lib/offerings-pricing.ts`, `app/api/offerings/checkout/[lookupKey]/route.ts`
@@ -552,8 +571,29 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - **No cross-site POST.** A `Sec-Fetch-Site` other than `same-origin`, or an `Origin` not on this site's own host, is refused 403 before the hub is called.
 - **Headers are an allow-list.** The visitor's `x-forwarded-for` (else `x-real-ip`) and `user-agent` pass through so per-visitor rate limits still count each visitor; no `authorization`, client-sent `x-ailk-*` or `host` is forwarded, and a `cookie` goes only on `POST /v1/commerce/invoices`, the one session route.
 - **The relay has its own per-visitor budget (#7707).** Each visitor gets 8 calls per 10 minutes across the five visitor routes, and the session route (`POST /v1/commerce/invoices`) gets its own, wider budget of 30 per 10 minutes; the call that exceeds either gets `429 rate_limited` before any hub call. The budget is held in this instance's own process (no shared store, no env variable) and holds only where the site's edge overwrites `x-forwarded-for` and `x-real-ip` — Vercel does; a bare self-hosted Next server does not.
+- **A bot check on the public writes (#9889, #9255).** On Vercel, `lib/bot-check.ts`'s `runBotCheck` asks Vercel BotID for a verdict before the hub is called — in the relay for `POST /v1/leads/{submit,subscribe,callback}` and `POST /v1/schedule/book` (`BOT_CHECKED_ROUTES`: `403 bot_detected`, or `503 bot_check_unavailable` when the check throws, answers no boolean or takes over 5 seconds), and in the contact, careers, newsletter, flow-step, flow-checkout, saved-recommendation and `/dev/purchase` Server Actions immediately before their hub call, which answer their own existing failure variant. The locale layout's `BotIdClient` protects every same-origin POST (`BOT_CLIENT_PROTECT`, `/*`), because a Server Action posts to the page it was submitted from; `next.config.mjs` wraps `withBotId` and `middleware.ts` keeps BotID's proxy prefix out of its matcher. It is on by default and inert off Vercel: `AILK_BOT_CHECK=off` turns every check off, `AILK_BOOKING_BOT_CHECK=off` the booking's alone, and MCP tools never pass through a site, so they are never challenged.
 - `/v1` is exempt from next-intl's locale rewrite in `middleware.ts`, as `/api` is.
 
+## Where the docs live (`docsPath`)
+
+A site serves its docs at `/docs` unless `content/_site.mdx` sets a top-level `docsPath` (one to four lowercase kebab segments, leading slash, no trailing slash — e.g. `docsPath: /working-theory/docs`, #10041). The route never moves: it stays at `app/[locale]/docs/`, and every surface reads the one value through `lib/docs-path.ts` (`DOCS_PATH`, `toPublicDocsHref`).
+
+- **Build.** `next.config.mjs` reads `docsPath`, bakes it into `NEXT_PUBLIC_AILK_DOCS_PATH`, and fails the build naming the value when it breaks the pattern, starts with `api`, `og`, `v1` or an enabled locale, sits under `/docs`, shadows a `ROUTES` page (a `:param` segment matches any segment, so `/products/docs` is refused) or sits under a catch-all (`/blog/...`), or when this site's `lib/source.ts` does not set `baseUrl: DOCS_PATH` — a site with no docs-blog module, or one whose docs-blog files predate the setting. Links inside a doc's body are re-pointed only on a site that sets `docsPath`; there they render through `Link`, which forwards a fixed prop set, so a body anchor's `title` / `target` / `rel` are not kept.
+- **Request.** `middleware.ts` hands next-intl the internal `/docs/...` path for a request at or under `docsPath` (bare or locale-prefixed), so the browser keeps the public URL, and maps a redirect's `Location` and each hreflang `Link` entry back onto it. `/docs` and `/docs/...` answer with the site's 404 — rewritten to `/_ailk-docs-unmounted`, whose first segment is no locale, so the locale layout calls `notFound()`.
+- **Surfaces.** The docs sidebar, index and search index (both sources' `baseUrl`), the doc's breadcrumb, links inside a doc's body, every nav and footer entry at `/docs` (mapped at render in the locale layout and `components/signed-in-nav.tsx`; `nav-config.ts` is never edited), and the docs entries in `/sitemap.xml` and `/llms.txt` (`lib/docs-index.ts`, default locale only) all follow it. A site with no `docsPath` serves every URL exactly as before.
+- **Existing docs sites.** `create-ailk update` carries the base readers but never refreshes a module bundle's files, so a docs-blog site installed before this release keeps a `lib/source.ts` without `DOCS_PATH` and its build refuses a `docsPath` until those files are re-installed — a standing gap no command fills yet (#10076).
+- **Rollout.** A `@working-theory/site-config` older than this setting rejects a `_site.mdx` carrying `docsPath` (its schema is strict), and `@working-theory/api` / `@working-theory/mcp-server` then read the site as having no config. Set `docsPath` only once the site's packages carry it.
+
+## Where the services live (`services.path`)
+
+A site serves its services at `/services` unless `content/_site.mdx` sets `services: { path: /capabilities }` (the `services` route family's one extra key, beside its `header` / `footer`; one to four lowercase kebab segments, not under `/services`, #10043). The routes never move: they stay at `app/[locale]/services/`, and every surface reads the one value through `lib/services-path.ts` (`SERVICES_PATH`, `toPublicServicesHref`) or, in `@working-theory/page-renderer`, `NEXT_PUBLIC_AILK_SERVICES_PATH`.
+
+- **Categories.** A category is itself a `Service` page. A service names its category with frontmatter `parent: <category-slug>` and is served at `/<base>/<category>/<slug>` (`services/[slug]/[child]/page.tsx`); its flat URL answers a permanent redirect there, and the nested URL answers 404 unless the `parent` names that category and the category has no `parent` of its own. A category page lists its services after its body (`lib/service-listing.ts`, the `services` messages' `childrenHeading` / `viewService`). One level only.
+- **Build.** `next.config.mjs` reads `services.path`, bakes it into `NEXT_PUBLIC_AILK_SERVICES_PATH`, and fails the build naming the value when it breaks the pattern, starts with an enabled locale, shadows a `ROUTES` page, sits under a catch-all, or overlaps `docsPath` either way. It also fails, naming the file, on a default-locale `Service` whose `parent` names no Service or a Service with its own `parent`, and on any `parent` when the nested route is missing (`create-ailk sync-routes` adds it).
+- **Request.** `middleware.ts` hands next-intl the internal `/services/...` path for a request at or under the base, keeps `x-pathname` public, and maps a redirect's `Location` and each hreflang `Link` entry back. `/services` and `/services/...` answer `308` onto the same rest under the base (query and locale prefix kept), so old links keep working; links inside content are not rewritten.
+- **Surfaces.** The canonical, hreflang and `BreadcrumbList` (the base's title-cased last segment, then the category's title), `/sitemap.xml` and `/llms.txt` (`pagePathFor`), every nav and footer entry at `/services` (mapped in the locale layout and `components/signed-in-nav.tsx`), the hub's own section links, and route-family chrome (`lib/page-chrome.ts`) all follow it. A site that sets neither `services.path` nor any `parent` serves every URL exactly as before.
+- **Moving it.** `/ailk:growth-ops page rename` moves the base (`--from <current base> --to <new base>`): it writes `services.path` and keeps a previous moved base redirecting.
+
 ## AEO & performance
 
 - Static rendering is the default. Don't introduce client rendering without a reason.
@@ -570,7 +610,15 @@ A visitor's browser never calls the hub. Lead capture, newsletter signup, callba
 - Don't reach into `apps/api` or `apps/mcp` from `apps/web`. They're peer apps — talk via HTTP/MCP.
 - Don't commit images to `screenshots/` — only the `.gitkeep` is tracked.
 
-Last updated: 2026-10-24 — § The `(auth)` route group: a magic link can create the account while sign-up is open, carrying the ticked agreements bound to its token (#9667) — verified against `lib/auth-email.ts`, `lib/sign-up-agreements.ts` and `app/[locale]/(auth)/sign-up/{page,sign-up-card}.tsx`.
+Last updated: 2026-10-27 — § Where the services live (`services.path`): the services base, one category level, the 308 from `/services` and the `update-page` base move (#10043) — verified against `lib/services-path.ts`, `lib/service-listing.ts`, `middleware.ts`, `next.config.mjs` and `app/[locale]/services/`.
+
+Prior: 2026-10-26 — § The same-origin relay: the bot check moves to `lib/bot-check.ts` and covers the relay's three lead routes and the seven public lead, flow and checkout Server Actions, with `BotIdClient` protecting every same-origin POST and the `AILK_BOT_CHECK` switch (#9255) — verified against `lib/bot-check.ts`, `lib/relay.ts`, `app/[locale]/layout.tsx` and the seven actions' files.
+
+Prior: 2026-10-25 — the Offerings buy route's spoke sentence: on a hub that sets `OSS_API_INTERNAL_SECRET` a spoke's key authenticates its buy, held to its hub sign-in client's origin (#9910) — verified against `app/api/offerings/checkout/[lookupKey]/route.ts` and `packages/api/src/routes/checkout/sessions.ts`.
+
+Prior: 2026-10-25 — § The same-origin relay: the booking bot check — Vercel BotID on `POST /v1/schedule/book`, `bot_detected` / `bot_check_unavailable`, the `AILK_BOOKING_BOT_CHECK` switch and the middleware's BotID exclusion (#9889) — verified against `lib/relay.ts`, `app/[locale]/layout.tsx`, `next.config.mjs` and `middleware.ts`.
+
+Prior: 2026-10-24 — § The `(auth)` route group: a magic link can create the account while sign-up is open, carrying the ticked agreements bound to its token (#9667) — verified against `lib/auth-email.ts`, `lib/sign-up-agreements.ts` and `app/[locale]/(auth)/sign-up/{page,sign-up-card}.tsx`.
 
 Prior: 2026-10-21 — § Pricing page and § Magnet pages: `/pricing`, the magnet pages and the results permalink read the browser-facing API origin through `browserApiOrigin()` (#7874 D12), so a spoke that enables them passes its own `env:check` (#9480) — verified against `app/[locale]/pricing/page.tsx`, `app/[locale]/flows/[slug]/{magnet-page.tsx,results/[payload]/page.tsx}` and `lib/api-origin.generated.ts`.
 

package/templates/apps/web/__tests__/setup.ts

@@ -58,6 +58,13 @@ if (typeof window !== "undefined") {
   /* eslint-enable no-restricted-syntax */
 }
 
+// A page whose generateMetadata calls @working-theory/page-renderer's
+// renderPageMetadata builds hreflang from readLocales() (#9660), which reads the
+// locale list next.config.mjs bakes into NEXT_PUBLIC_ENABLED_LOCALES and
+// otherwise throws on a missing project.yaml. Jest runs no next build, so supply
+// the baked value; a suite that sets its own keeps it.
+process.env.NEXT_PUBLIC_ENABLED_LOCALES ??= "en";
+
 // next-intl/server and next-intl are supplied by moduleNameMapper entries in
 // jest.config.cjs (__tests__/__mocks__/next-intl-server.ts and next-intl.ts),
 // not by jest.mock() here. A mapper is path-independent; a jest.mock() binds to

package/templates/apps/web/app/.well-known/mcp.json/route.ts

@@ -17,8 +17,8 @@
  * to make impossible. The same single read also yields the licence features
  * the deployment holds (#7136), which gate the five `feature`-tagged tools
  * here exactly as they gate registration on the MCP server. `create_project`
- * is left out while create-ailk's release scope holds the Free level (#9534),
- * as `apps/mcp` leaves it unregistered — `lib/release-scope.ts`.
+ * is always left out: this manifest describes the HTTP surface, and the MCP
+ * server serves that tool over stdio only (#9965 D13, #8584).
  *
  * Mirrors /.well-known/ai-plugin.json conventions: Response.json with a
  * conservative cache-control header.
@@ -28,7 +28,6 @@
  * is appropriate per the MCP discovery spec.
  */
 
-import { isFreeLevelReleased } from "../../../lib/release-scope";
 import { UNSERVED_MCP_TOOLS } from "../../../lib/topology.generated";
 import packageJson from "../../../package.json";
 import {
@@ -64,10 +63,11 @@ export async function GET(): Promise<Response> {
     commerceClaimed: heldFeatures.includes(COMMERCE_FEATURE),
     heldFeatures,
     // The tools this topology's MCP server does not register (#8070 D7) —
-    // and create_project while the Free level is held (#9534).
-    unservedTools: isFreeLevelReleased()
-      ? UNSERVED_MCP_TOOLS
-      : [...UNSERVED_MCP_TOOLS, "create_project"],
+    // and create_project, which the HTTP transport never serves (#9965 D13).
+    unservedTools: [
+      ...UNSERVED_MCP_TOOLS.filter((name) => name !== "create_project"),
+      "create_project",
+    ],
     // Spread conditional to satisfy exactOptionalPropertyTypes: omit the key
     // entirely when the env var is not set rather than passing undefined.
     ...(mcpHttpUrlEnv ? { mcpHttpUrl: mcpHttpUrlEnv } : {}),

package/templates/apps/web/app/[locale]/(auth)/sign-in/__tests__/next-path.test.ts

@@ -2,8 +2,11 @@
  * Tests for `resolveNextPath` — the /sign-in `?next=` sanitizer (#4984).
  * Foreign, protocol-relative, backslash, control-char, and non-string inputs
  * all fall back; plain in-app paths pass through unchanged.
+ *
+ * `hrefWithNext` (#9912 D4) — a toggle carries `?next=` only when the page's
+ * resolved `next` is not its fallback.
  */
-import { resolveNextPath } from "../next-path";
+import { hrefWithNext, resolveNextPath } from "../next-path";
 
 const FALLBACK = "/account";
 
@@ -29,3 +32,23 @@ describe("resolveNextPath()", () => {
     expect(resolveNextPath(raw, FALLBACK)).toBe(FALLBACK);
   });
 });
+
+describe("hrefWithNext()", () => {
+  it("the fallback gives the bare href", () => {
+    expect(hrefWithNext("/sign-up", "/account", "/account")).toBe("/sign-up");
+  });
+
+  it("any other next rides as ?next=, URL-encoded", () => {
+    expect(
+      hrefWithNext("/sign-up", "/api/auth/hub/continue/abc_-1", "/account"),
+    ).toBe("/sign-up?next=%2Fapi%2Fauth%2Fhub%2Fcontinue%2Fabc_-1");
+    expect(
+      hrefWithNext("/fr/sign-in", "/fr/account?tab=x", "/fr/account"),
+    ).toBe("/fr/sign-in?next=%2Ffr%2Faccount%3Ftab%3Dx");
+  });
+
+  it("a refused next resolves to the fallback, so its toggle is bare", () => {
+    const next = resolveNextPath("//evil.example", FALLBACK);
+    expect(hrefWithNext("/sign-up", next, FALLBACK)).toBe("/sign-up");
+  });
+});

package/templates/apps/web/app/[locale]/(auth)/sign-in/__tests__/page.test.tsx

@@ -28,6 +28,9 @@
  *       the deployment's own data — a crafted query parameter cannot change
  *       the name — the "Don't have an account? Sign up" line linking
  *       /sign-up, and the Terms + Privacy acknowledgement.
+ *   (k) the Sign up toggle (#9912 D4): it carries the validated `?next=` to
+ *       /sign-up; a `next` resolveNextPath refuses, or none, gives the bare
+ *       /sign-up.
  *
  * `next-intl/server` is mocked here against the real en.json, with `{name}`
  * placeholders filled from the values passed, so `signIn` copy is asserted
@@ -524,3 +527,51 @@ describe("/sign-in page — the one card (#9662)", () => {
     expect(within(footnote).getAllByRole("link")).toHaveLength(2);
   });
 });
+
+describe("/sign-in page — the Sign up toggle keeps the next (#9912 D4)", () => {
+  beforeEach(() => {
+    mockClientInfo.mockReset().mockResolvedValue({ ok: false, status: 404 });
+  });
+
+  it("(k) a continuation next rides the toggle to /sign-up, URL-encoded", async () => {
+    const ref = mintContinuation("client_id=spoke_1", TEST_SECRET);
+    const next = `/api/auth/hub/continue/${ref}`;
+    await renderPage(next);
+    expect(screen.getByTestId("auth-card-prospect-link")).toHaveAttribute(
+      "href",
+      `/sign-up?next=${encodeURIComponent(next)}`,
+    );
+  });
+
+  it("(k) an in-app next rides the toggle too", async () => {
+    await renderPage("/account/billing");
+    expect(screen.getByTestId("auth-card-prospect-link")).toHaveAttribute(
+      "href",
+      "/sign-up?next=%2Faccount%2Fbilling",
+    );
+  });
+
+  it.each([
+    ["a protocol-relative next", "//evil.example"],
+    ["an absolute next", "https://evil.example/x"],
+    ["a backslash next", "/\\evil.example"],
+    ["a control character", "/x\r\ny"],
+  ])(
+    "(k) %s fails resolveNextPath, so the toggle is the bare /sign-up",
+    async (_label, next) => {
+      await renderPage(next);
+      expect(screen.getByTestId("auth-card-prospect-link")).toHaveAttribute(
+        "href",
+        "/sign-up",
+      );
+    },
+  );
+
+  it("(k) no next: the bare /sign-up", async () => {
+    await renderPage();
+    expect(screen.getByTestId("auth-card-prospect-link")).toHaveAttribute(
+      "href",
+      "/sign-up",
+    );
+  });
+});

package/templates/apps/web/app/[locale]/(auth)/sign-in/next-path.ts

@@ -3,5 +3,18 @@
  * `lib/next-path.ts` (#7894 D7) so the hub-session callback, which a spoke
  * keeps when it drops this route group, shares it. Re-exported here so this
  * group's importers are unchanged.
+ *
+ * `hrefWithNext` (#9912 D4) builds the /sign-in ↔ /sign-up toggle: it carries
+ * the page's validated `next` only when that is not the page's fallback, so a
+ * refused or absent `next` gives today's bare link.
  */
 export { resolveNextPath } from "../../../../lib/next-path";
+
+/** `href` with `?next=<next>` when `next` is not the page's fallback, else `href`. */
+export function hrefWithNext(
+  href: string,
+  next: string,
+  fallback: string,
+): string {
+  return next === fallback ? href : `${href}?next=${encodeURIComponent(next)}`;
+}

package/templates/apps/web/app/[locale]/(auth)/sign-in/page.tsx

@@ -24,7 +24,9 @@
  * The one card (#9662): "Sign in to <site>" (the name is the deployment's,
  * read in `resolveSignInCardText`, never the request's), the "Don't have an
  * account? Sign up" line to `/sign-up`, and the Terms + Privacy
- * acknowledgement.
+ * acknowledgement. The Sign up line carries the validated `next` (#9912 D4),
+ * so a buyer who switches to sign-up keeps the destination; a refused or
+ * absent `next` gives the bare `/sign-up`.
  *
  * Signed-in visitors are not redirected here — the Nav's session-aware action
  * cluster (Account / Sign out) is the affordance for them.
@@ -48,7 +50,7 @@ import {
 } from "../../../api/auth/hub/continuation";
 import { legalFootnote } from "../legal-footnote";
 
-import { resolveNextPath } from "./next-path";
+import { hrefWithNext, resolveNextPath } from "./next-path";
 import { SignInCard, type SignInProvider } from "./sign-in-card";
 import { resolveSignInCardText, type SignInCardText } from "./sign-in-text";
 
@@ -147,7 +149,8 @@ export default async function SignInPage({
   );
   const method = active.includes("email") ? "password" : "sso";
   const emailLink = active.includes("magic-link");
-  const next = resolveNextPath(rawNext, localeHref(locale, "/account"));
+  const fallback = localeHref(locale, "/account");
+  const next = resolveNextPath(rawNext, fallback);
   // A failed link returns here, keeping the visitor's destination.
   const signInHref = `${localeHref(locale, "/sign-in")}?next=${encodeURIComponent(next)}`;
   // Only the email link produces `?error=` here; with it off, today's render.
@@ -167,7 +170,10 @@ export default async function SignInPage({
             },
           }
         : {})}
-      prospect={{ ...text.prospect, href: localeHref(locale, "/sign-up") }}
+      prospect={{
+        ...text.prospect,
+        href: hrefWithNext(localeHref(locale, "/sign-up"), next, fallback),
+      }}
       footnote={legalFootnote(locale, text.acknowledgement)}
       providers={providers}
       method={method}