@ultimat3/cli 29.3.2 → 30.0.0

package/src/templates/scaffold-mcp-endpoint.ts

@@ -0,0 +1,182 @@
+// The app's own `POST /mcp`, as `x new` writes it: `apps/web/mcp.ts` — the file and export the
+// mount reads (`app-mcp.ts`) — over the `@<app>/mcp` catalog, and the token resolver that makes it a
+// route. Mounted and REFUSING: no bearer, or one nobody issued, is a 401 before a tool is read. The
+// development token works under `x dev` alone, and its test says so in every other environment.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+const endpoint = (
+  app: NameSet,
+): string => `// The app's own MCP endpoint: \`POST /mcp\`, mounted by \`x dev\` and by the web role, which find
+// this file by its path and its \`mcp\` export. The tools are \`@${app.kebab}/mcp\`'s catalog; who may
+// call them is \`resolveAgentToken\`. Delete this file to unmount it — the boot then says
+// X_MCP_APP_UNMOUNTED — or set \`ai: { mcp: { expose: false } }\` in app.config.ts.
+//
+// Built when the boot scan reaches this file, after \`apps/*/api\` registered its actions: a tool
+// declared later in a running \`x dev\` is on \`POST /mcp\` from its next restart.
+import { appMcp } from '@${app.kebab}/mcp';
+import { resolveAgentToken } from './app/auth/agent-token';
+
+export const mcp = appMcp({ resolveToken: resolveAgentToken });
+`;
+
+const endpointTest =
+  (): string => `// The endpoint is mounted and refusing: a route at /mcp, and a 401 for a request that carries no
+// token or one this process does not honour — before any tool, or the body, is read.
+import { expect, unitTest } from '@ultimat3/testing';
+import { DEV_AGENT_TOKEN_PREFIX } from './app/auth/agent-token';
+import { mcp } from './mcp';
+
+const post = (headers: Record<string, string>) =>
+  new Request('http://localhost/mcp', { method: 'POST', headers, body: '{}' });
+
+unitTest('POST /mcp is mounted, and answers 401 without a token', async () => {
+  const route = mcp.route;
+  if (route === undefined) return expect.unreachable('apps/web/mcp.ts built no route');
+  expect(route.path).toBe('/mcp');
+  const response = await route.handle(post({}));
+  expect(response.status).toBe(401);
+  // The development token is refused outside \`x dev\`: \`bun test\` is not development.
+  const dev = await route.handle(post({ authorization: \`Bearer \${DEV_AGENT_TOKEN_PREFIX}admin\` }));
+  expect(dev.status).toBe(401);
+});
+`;
+
+const agentToken =
+  (): string => `// Who an MCP caller is, for \`apps/web/mcp.ts\`: an API key issued through \`@ultimat3/auth\` —
+// \`issueApiKey\`, stored in the framework's \`x_api_keys\` — resolved to an agent actor, in every
+// environment. Under \`x dev\` alone, \`dev-agent.<role>\` is also an agent holding that declared role,
+// so a local client can call the app's tools before the app issues keys. It FAILS CLOSED: a process
+// naming no environment is production, where that token is refused like any unknown one.
+import { type Auth, apiKeyResolver } from '@ultimat3/auth';
+import { type Actor, agentActor, peerAddressClass, tryResolveEnvironment } from '@ultimat3/core';
+import { DEMO_ORG_ID } from '../../shared/demo-org';
+import { roles } from '../../shared/roles';
+import { appAuth } from './auth';
+
+/** \`Authorization: Bearer dev-agent.admin\` under \`x dev\`; refused everywhere else. */
+export const DEV_AGENT_TOKEN_PREFIX = 'dev-agent.';
+
+/** What \`defineAppMcp\`'s \`resolveToken\` answers: an agent, and the scopes its connection holds. */
+export interface AgentCaller {
+  readonly actor: Actor;
+  readonly scopes: ReadonlySet<string>;
+}
+
+/** The development agent a token names, or \`null\` for a role \`shared/roles.ts\` never declared. */
+export const devAgentFor = (token: string): AgentCaller | null => {
+  const role = token.slice(DEV_AGENT_TOKEN_PREFIX.length);
+  // \`Object.hasOwn\`, never \`in\`: a token saying \`constructor\` names no role.
+  if (!Object.hasOwn(roles, role)) return null;
+  return {
+    actor: agentActor({ id: 'dev-agent', orgId: DEMO_ORG_ID, roles: [role] }),
+    scopes: new Set(),
+  };
+};
+
+export interface AgentTokenOptions {
+  readonly env: Readonly<Record<string, string | undefined>>;
+  /** The app's \`Auth\`, asked for when a key is presented, never at import. */
+  readonly auth: () => Auth;
+}
+
+/** How the request arrived: the two facts \`defineAppMcp\` hands every resolver that this one reads. */
+export interface CallerFacts {
+  /** The \`Origin\` header: a browser sends one on every POST, a local MCP client none. */
+  readonly origin: string | null;
+  /** The caller's address as the host resolved it. */
+  readonly address: string | null;
+}
+
+/**
+ * The development token is honoured only from this machine and never from a browser: a page that
+ * rebinds its name to 127.0.0.1 reaches \`x dev\` over loopback, but it sends \`Origin\`.
+ */
+const localClient = (facts: CallerFacts | undefined): boolean =>
+  facts !== undefined &&
+  facts.origin === null &&
+  facts.address !== null &&
+  peerAddressClass(facts.address) === 'loopback';
+
+/** The resolver, over an environment and an \`Auth\` — so its test chooses both. */
+export const agentTokenResolver = (options: AgentTokenOptions) => {
+  const keys = apiKeyResolver(() => options.auth().adapter);
+  return async (token: string, facts?: CallerFacts): Promise<AgentCaller | null> => {
+    if (!token.startsWith(DEV_AGENT_TOKEN_PREFIX)) return await keys(token);
+    const environment = tryResolveEnvironment({ env: options.env, fallback: 'production' });
+    return environment === 'development' && localClient(facts) ? devAgentFor(token) : null;
+  };
+};
+
+export const resolveAgentToken = agentTokenResolver({ env: process.env, auth: appAuth });
+`;
+
+const agentTokenTest =
+  (): string => `// An issued key is an agent of its org everywhere; the development token is an agent under
+// \`x dev\` and nothing anywhere else — including a process that names no environment at all.
+import { defineAuth, issueApiKey, memoryAuthAdapter } from '@ultimat3/auth';
+import { expect, unitTest } from '@ultimat3/testing';
+import { DEMO_ORG_ID } from '../../shared/demo-org';
+import { agentTokenResolver, DEV_AGENT_TOKEN_PREFIX, resolveAgentToken } from './agent-token';
+
+/** In memory: the key store is the package's, and this test is about the wiring around it. */
+const memoryAuth = () => {
+  const auth = defineAuth({ adapter: memoryAuthAdapter() });
+  return () => auth;
+};
+
+unitTest('an issued API key is an agent of its org, in every environment', async () => {
+  const auth = memoryAuth();
+  const issued = issueApiKey({ env: 'dev', scopes: [], orgId: DEMO_ORG_ID });
+  await auth().adapter.putApiKey(issued.record);
+  for (const ULTIMATE_ENV of ['development', 'production']) {
+    const caller = await agentTokenResolver({ env: { ULTIMATE_ENV }, auth })(issued.plaintext);
+    expect(caller?.actor.kind).toBe('agent');
+    expect(caller?.actor.orgId).toBe(DEMO_ORG_ID);
+  }
+  // One character off the secret is nobody.
+  const resolve = agentTokenResolver({ env: {}, auth });
+  expect(await resolve(\`\${issued.plaintext}x\`)).toBeNull();
+});
+
+/** A local, non-browser client: what \`x dev\`'s own MCP clients are. */
+const LOCAL = { origin: null, address: '127.0.0.1' };
+
+unitTest('dev-agent.<role> is that declared role under x dev, and nobody elsewhere', async () => {
+  const auth = memoryAuth();
+  const dev = agentTokenResolver({ env: { ULTIMATE_ENV: 'development' }, auth });
+  const admin = \`\${DEV_AGENT_TOKEN_PREFIX}admin\`;
+  expect((await dev(admin, LOCAL))?.actor.roles).toEqual(['admin']);
+  expect(await dev(\`\${DEV_AGENT_TOKEN_PREFIX}nobody\`, LOCAL)).toBeNull();
+  expect(await dev(\`\${DEV_AGENT_TOKEN_PREFIX}constructor\`, LOCAL)).toBeNull();
+  for (const env of [{ ULTIMATE_ENV: 'production' }, { ULTIMATE_ENV: 'staging' }, {}]) {
+    expect(await agentTokenResolver({ env, auth })(admin, LOCAL)).toBeNull();
+  }
+});
+
+unitTest('the development token is refused from a browser or from off this machine', async () => {
+  // A hostile page that rebinds its name to 127.0.0.1 reaches \`x dev\` from a loopback socket,
+  // but a browser sends Origin on every POST; another machine on the network has no loopback address.
+  const dev = agentTokenResolver({ env: { ULTIMATE_ENV: 'development' }, auth: memoryAuth() });
+  const admin = \`\${DEV_AGENT_TOKEN_PREFIX}admin\`;
+  expect(await dev(admin, { origin: 'http://rebound.test:3000', address: '127.0.0.1' })).toBeNull();
+  expect(await dev(admin, { origin: 'null', address: '::1' })).toBeNull();
+  expect(await dev(admin, { origin: null, address: '192.168.1.20' })).toBeNull();
+  expect(await dev(admin, { origin: null, address: null })).toBeNull();
+  expect(await dev(admin)).toBeNull();
+  expect((await dev(admin, { origin: null, address: '::1' }))?.actor.kind).toBe('agent');
+});
+
+unitTest('the installed resolver refuses the development token under bun test', async () => {
+  // \`bun test\` sets NODE_ENV=test: not development, so no key store is ever asked.
+  expect(await resolveAgentToken(\`\${DEV_AGENT_TOKEN_PREFIX}admin\`)).toBeNull();
+});
+`;
+
+/** `apps/web/mcp.ts`, the resolver it mounts with, and the tests that pin both refusing. */
+export const mcpEndpointFiles = (app: NameSet): readonly GeneratedFile[] => [
+  { path: 'apps/web/mcp.ts', contents: endpoint(app) },
+  { path: 'apps/web/mcp.test.ts', contents: endpointTest() },
+  { path: 'apps/web/app/auth/agent-token.ts', contents: agentToken() },
+  { path: 'apps/web/app/auth/agent-token.test.ts', contents: agentTokenTest() },
+];

package/src/templates/scaffold-mcp-json.ts

@@ -0,0 +1,31 @@
+// `.mcp.json`: the one MCP client config `x new` writes, in the format several clients read. It
+// starts `x mcp serve` over stdio — the dev tools — through the SCOPED package, because a client may
+// spawn the command outside the installed app, and there `bunx x` fetches an unrelated npm package.
+// A client that wants another file is told how in `wiki/MCP-And-AI.md`, never generated for.
+
+import type { GeneratedFile, NameSet } from './naming';
+
+export const MCP_JSON_PATH = '.mcp.json';
+
+const COMMAND = 'bunx';
+const ARGS = ['@ultimat3/cli', 'mcp', 'serve', '--transport', 'stdio'] as const;
+
+/** The line the file encodes, as a shell would run it — what the docs and the smoke both quote. */
+export const MCP_SERVE_COMMAND = [COMMAND, ...ARGS].join(' ');
+
+/** The file itself, Biome-formatted: one server, keyed by the app's name. */
+export function mcpJsonFile(app: NameSet): GeneratedFile {
+  const args = ARGS.map((arg) => `"${arg}"`).join(', ');
+  return {
+    path: MCP_JSON_PATH,
+    contents: `{
+  "mcpServers": {
+    "${app.kebab}": {
+      "command": "${COMMAND}",
+      "args": [${args}]
+    }
+  }
+}
+`,
+  };
+}

package/src/templates/scaffold-mcp-package.ts

@@ -1,85 +1,88 @@
 // The generated app's `packages/mcp`: the app's own MCP surface, projected straight from the
 // action registry rather than re-listed, plus the test that pins every projected tool describing
-// itself.
+// itself — and the `apps/web/mcp.ts` endpoint that mounts it (`scaffold-mcp-endpoint.ts`).
 
-import { sortedImports } from './imports';
 import type { GeneratedFile, NameSet } from './naming';
-import { packageShapeFiles } from './scaffold-package-shape';
+import { mcpEndpointFiles } from './scaffold-mcp-endpoint';
+import { packageShapeFiles, workspacePackageJson } from './scaffold-package-shape';
 
 const DESCRIPTION = "The app's own MCP tools";
 
-/**
- * Writes its own manifest, for the reason `scaffold-i18n.ts` does: `workspacePackageJson` is the
- * dependency-free shape, and this package has a real dependency — `src/index.ts` below imports the
- * app's actions out of `apps/web/api`, because `registerActions` has to see them.
- *
- * The edge points AT the app, which is unusual and correct. `apps/web` is a workspace like any
- * other; reversing it would put the tool catalog upstream of the actions it projects. Declared
- * rather than left to the root tsconfig's `paths`: an undeclared edge resolves for `tsc` and for
- * nothing else — not for `bun --filter` ordering, not for any tool asking what a change affects
- * (`X_WORKSPACE_DEP_UNDECLARED`).
- *
- * `"0.0.0"` and not `workspace:*`: it is the version `apps/web` really carries, which is what
- * `checkLockstep` compares a sibling pin against, and it is the one spelling every other manifest
- * `x new` writes already uses.
- */
-const mcpPackage = (app: NameSet): string => `{
-  "name": "@${app.kebab}/mcp",
-  "version": "0.0.0",
-  "private": true,
-  "type": "module",
-  "description": "${DESCRIPTION}",
-  "exports": {
-    ".": "./src/index.ts"
-  },
-  "scripts": {
-    "typecheck": "tsc --noEmit -p ../../tsconfig.json"
-  },
-  "dependencies": {
-    "@${app.kebab}/web": "0.0.0"
-  }
-}
-`;
-
 const mcpIndex = (
   app: NameSet,
 ): string => `// The app's own MCP tools. Every action with mcp.expose is already a tool; add app-specific
 // read-only helpers here. Authorization is the action's policy, unchanged.
-${sortedImports([
-  `import * as api from '@${app.kebab}/web/api/health';`,
-  `import { registerActions } from '@ultimat3/action';`,
-  `import { defineAppMcp } from '@ultimat3/mcp';`,
-])}
+//
+// A FUNCTION, and it imports no app (X_BOUNDARY_PACKAGE_TO_APP): \`defineAppMcp\` reads the registry
+// where it is called, and \`runRole()\` and \`loadApp()\` both fill that registry before anything
+// asks for the catalog. A module-scope call froze whatever had registered by import time.
+import { defineAppMcp, type McpRequestFacts, type ResolvedToken } from '@ultimat3/mcp';
 
-// Names come from export names, so the registry agrees with the module the app already wrote.
-registerActions(api);
+/** Who a bearer token is, or \`null\` for nobody — answered 401. */
+export type TokenResolver = (
+  token: string,
+  facts: McpRequestFacts,
+) => Promise<ResolvedToken | null> | ResolvedToken | null;
+
+export interface AppMcpOptions {
+  /** \`apps/web/mcp.ts\` passes the app's resolver; without one there is no route. */
+  readonly resolveToken?: TokenResolver | undefined;
+}
 
 // \`include: 'exposed'\` projects straight from the registry. Re-listing the actions here would
 // copy \`mcp: { expose: true }\` into a second place, and the copy goes stale in silence.
-export const mcp = defineAppMcp({
-  name: '${app.kebab}',
-  include: 'exposed',
+export const appMcp = (options: AppMcpOptions = {}) =>
+  defineAppMcp({
+    name: '${app.kebab}',
+    include: 'exposed',
+    ...(options.resolveToken === undefined ? {} : { resolveToken: options.resolveToken }),
+  });
+`;
+
+const mcpUnitTest =
+  (): string => `// The catalog is built where it is called, from whatever has registered by then: this file loads no
+// app, so what it pins is the shape. The tools themselves are the contract test's, next door.
+import { expect, unitTest } from '@ultimat3/testing';
+import { appMcp } from './index';
+
+unitTest('the catalog is in process until a token resolver is given', () => {
+  // No \`resolveToken\` means no route: a mount with no bearer check is the failure this rules out.
+  expect(appMcp().route).toBeUndefined();
+});
+
+unitTest('given one, it is a route at /mcp', () => {
+  expect(appMcp({ resolveToken: () => null }).route?.path).toBe('/mcp');
 });
 `;
 
 const mcpTest =
-  (): string => `// The app exposes its actions as MCP tools, and each tool carries the action's own policy. An
-// agent reaching a tool that authorises differently is the failure this rules out.
-import { expect, unitTest } from '@ultimat3/testing';
-import { mcp } from './index';
+  (): string => `// The app exposes its actions as MCP tools, and each tool carries the action's own policy. The
+// catalog reads a registry, so the honest proof fills it the way the process does: \`loadApp\` scans
+// \`apps/*\` exactly as \`runRole()\` does. Booting the app is the fixture, so the timeout moves.
+import { resolve } from 'node:path';
+import { loadApp } from '@ultimat3/cli';
+import { beforeAll, contractTest, expect } from '@ultimat3/testing';
+import { appMcp } from './index';
+
+beforeAll(async () => {
+  await loadApp(resolve(import.meta.dir, '../../..'));
+}, 30_000);
 
-unitTest('the app exposes its actions as MCP tools', () => {
-  expect(mcp.tools.length).toBeGreaterThan(0);
+contractTest('the app exposes its actions as MCP tools', () => {
+  const tools = appMcp().tools;
+  expect(tools.length).toBeGreaterThan(0);
   // Every projected tool must describe itself: an agent picks a tool by its description. Assert
   // on the value, not its length — a failure then prints the empty description, not "0 > 0".
-  for (const tool of mcp.tools) expect(tool.description).not.toBe('');
+  for (const tool of tools) expect(tool.description).not.toBe('');
 });
 `;
 
-/** Every file the `packages/mcp` workspace ships, in the order `x new` writes them. */
+/** Every file the `packages/mcp` workspace ships, then the endpoint that mounts it. */
 export const mcpPackageFiles = (app: NameSet): readonly GeneratedFile[] => [
-  { path: 'packages/mcp/package.json', contents: mcpPackage(app) },
+  { path: 'packages/mcp/package.json', contents: workspacePackageJson(app, 'mcp', DESCRIPTION) },
   ...packageShapeFiles(app, 'mcp', DESCRIPTION),
   { path: 'packages/mcp/src/index.ts', contents: mcpIndex(app) },
-  { path: 'packages/mcp/src/index.test.ts', contents: mcpTest() },
+  { path: 'packages/mcp/src/index.test.ts', contents: mcpUnitTest() },
+  { path: 'packages/mcp/src/index.contract.test.ts', contents: mcpTest() },
+  ...mcpEndpointFiles(app),
 ];

package/src/templates/scaffold-repo.ts

@@ -74,7 +74,6 @@ const rootPackage = (app: NameSet, version: string): string => `{
   "scripts": {
     "setup": "${binScript(BIN_SCRIPTS.setup)}",
     "dev": "x dev",
-    "check": "${binScript(BIN_SCRIPTS.check)}",
     "verify": "x verify",
     "typecheck": "tsc -p . --pretty",
     "lint": "biome check .",
@@ -208,7 +207,8 @@ export const config = defineConfig({
   // Locales are declared by the catalogs (\`defineCatalogs\` in \`packages/i18n/src/index.ts\`); no
   // zone or currency default exists — every format call names its zone, every \`Money\` its currency.
   // Env KEYS, never the value: the same image deploys to every environment. The database is
-  // configured entirely from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`.
+  // configured from the environment — \`DATABASE_URL\` and \`DATABASE_POOL_MAX\`. Off by default,
+  // \`database: { rowSecurity: true }\` adds the database's own tenant guard under the repository's.
   // The tiers ARE the cache selection: add 'redis' to build the shared rung, which reads
   // \`REDIS_URL\` and refuses the boot when it is unset.
   cache: { tiers: ['request-memo', 'lru'] },
@@ -340,6 +340,8 @@ const SCAFFOLD_FLOOR: readonly VerifyStepName[] = [
   'errors',
   'unit',
   'contract',
+  // Every app has an `app.config.ts` and primitives to run: `x new` writes `apps/web/exercise.ts`.
+  'exercise',
   'eval',
   'drift',
   'budgets',
@@ -387,6 +389,8 @@ const verifyFloor = (example: boolean): string =>
         funcs: COVERAGE_BAR,
         exclude: SCAFFOLD_COVERAGE_EXCLUDE,
       },
+      // The rolling rail judges from the first migration: a new app has nothing to grandfather.
+      rollingSince: '0',
     },
     null,
     2,
@@ -433,6 +437,7 @@ packages/*/dist/
 *.tsbuildinfo
 .env
 .env.*.local
+.env.production
 /coverage/
 playwright-report/
 test-results/

package/src/templates/scaffold-shell.ts

@@ -14,7 +14,9 @@ const SHELL_DIR = 'apps/web/shared';
 const navType = (example: boolean): string => (example ? "'dashboard' | 'posts'" : "'dashboard'");
 
 const postsItem = (example: boolean): string =>
-  example ? `\n            {item('posts', '/posts', t('shell.nav.posts'), iconList)}` : '';
+  example
+    ? `\n    { label: t('shell.nav.posts'), href: '/posts', icon: <Icon glyph={iconList} size="sm" /> },`
+    : '';
 
 // Plain strings for the framework lines, never template literals: the workspace-dependency scanner
 // blanks a string's contents but not a nested template's, so a template here would bill the CLI
@@ -25,14 +27,16 @@ const shell = (
 ): string => `// The app's frame: brand mark, the sidebar with one link per destination, an environment pill,
 // the page's own actions at the end of the bar, and a footer — composed over the catalog's
 // \`AppShell\`, so the skip link, the landmarks and the phone layout are the framework's and not
-// this file's. \`site/page.tsx\` does NOT use it: the landing page is a 0kb document and this is the
-// signed-in product's chrome. Every page under \`app/\` does.
+// this file's. The destinations are ONE list, drawn twice: \`NavList\` in the sidebar, \`BottomNav\`
+// along a phone's bottom edge; each marks the current page by its href, with no script.
+// \`site/page.tsx\` does NOT use it: the landing page is a 0kb document and this is the signed-in
+// product's chrome. Every page under \`app/\` does.
 //
 // \`useT()\`, not \`t\` from @ultimat3/i18n — see apps/web/site/page.tsx for why.
 ${sortedImports([
   `import { useT } from '@${app.kebab}/i18n';`,
   "import { tryResolveEnvironment } from '@ultimat3/core';",
-  "import { AppShell, Icon, type IconGlyph, Link } from '@ultimat3/ui';",
+  "import { AppShell, BottomNav, Icon, Link, NavList } from '@ultimat3/ui';",
   "import { iconHexagon } from '@ultimat3/ui/icons/hexagon';",
   "import { iconLayoutDashboard } from '@ultimat3/ui/icons/layout-dashboard';",
   ...(example ? ["import { iconList } from '@ultimat3/ui/icons/list';"] : []),
@@ -43,6 +47,11 @@ import styles from './shell.module.scss';
 /** The routes the sidebar knows about. A page names itself so its link can carry aria-current. */
 export type ShellNav = ${navType(example)};
 
+/** Where each destination lives — what \`NavList\` and \`BottomNav\` match the current page against. */
+const HREFS: Readonly<Record<ShellNav, string>> = {
+  dashboard: '/dashboard',${example ? "\n  posts: '/posts'," : ''}
+};
+
 export interface ShellProps {
   readonly nav?: ShellNav | undefined;
   /** Controls that belong to the page, rendered at the end of the header bar — a theme toggle. */
@@ -56,20 +65,15 @@ export function Shell(props: ShellProps): JSX.Element {
   // neither ULTIMATE_ENV nor NODE_ENV names one, and the pill is absent with it.
   const environment = tryResolveEnvironment();
 
-  const item = (id: ShellNav, href: string, label: string, glyph: IconGlyph): JSX.Element => (
-    <li>
-      <Link
-        class={styles.navLink}
-        href={href}
-        tone="inherit"
-        underline="none"
-        aria-current={props.nav === id ? 'page' : false}
-      >
-        <Icon glyph={glyph} size="sm" class={styles.navIcon} />
-        <span>{label}</span>
-      </Link>
-    </li>
-  );
+  const destinations = [
+    {
+      label: t('shell.nav.dashboard'),
+      href: '/dashboard',
+      icon: <Icon glyph={iconLayoutDashboard} size="sm" />,
+    },${postsItem(example)}
+  ];
+  // No page named means nothing is current: an href no destination covers.
+  const currentHref = props.nav === undefined ? '' : HREFS[props.nav];
 
   return (
     <div class={styles.doc}>
@@ -97,11 +101,8 @@ export function Shell(props: ShellProps): JSX.Element {
             </div>
           </div>
         }
-        sidebar={
-          <ul class={styles.nav}>
-            {item('dashboard', '/dashboard', t('shell.nav.dashboard'), iconLayoutDashboard)}${postsItem(example)}
-          </ul>
-        }
+        sidebar={<NavList items={destinations} currentHref={currentHref} />}
+        bottomNav={<BottomNav items={destinations} currentHref={currentHref} />}
         footer={<span>{t('shell.footer')}</span>}
       >
         {props.children}
@@ -207,55 +208,6 @@ const shellStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
     opacity: 0.35;
   }
 }
-
-.nav {
-  display: flex;
-  // A row on a phone — stacked links cost a fifth of the first screen — a rail from md up.
-  flex-direction: row;
-  gap: tokens.space(1);
-  margin: 0;
-  padding: 0;
-  overflow-x: auto;
-  list-style: none;
-
-  @include tokens.respond-to(md) {
-    flex-direction: column;
-  }
-}
-
-.navLink {
-  display: flex;
-  align-items: center;
-  gap: tokens.space(3);
-  padding: tokens.space(2) tokens.space(3);
-  border-radius: tokens.radius('md');
-  color: tokens.role('fg-muted');
-  font-size: tokens.text('sm');
-  transition:
-    color tokens.duration('fast') tokens.easing('out'),
-    background-color tokens.duration('fast') tokens.easing('out');
-
-  &:hover {
-    color: tokens.role('fg-strong');
-    background: tokens.role('surface');
-  }
-
-  &[aria-current='page'] {
-    color: tokens.role('fg-strong');
-    background: tokens.role('surface-raised');
-    box-shadow: inset 0 0 0 1px tokens.role('line', 0.7);
-
-    .navIcon {
-      color: tokens.role('accent');
-    }
-  }
-}
-
-.navIcon {
-  flex: none;
-  color: tokens.role('fg-muted');
-  transition: color tokens.duration('fast') tokens.easing('out');
-}
 `;
 
 const shellTest =
@@ -267,10 +219,13 @@ import { Shell } from './shell';
 
 unitTest('the shell marks the current destination and keeps the page in <main>', async () => {
   const view = await renderView(Shell, { nav: 'dashboard', children: 'the page body' });
-  expect(view.html).toMatch(/<a href="\\/dashboard" aria-current="page"/);
-  // Landmarks come from AppShell: one banner, one navigation, one main, one contentinfo.
+  // One current link per list — the sidebar's and the bottom bar's — and both are the dashboard.
+  const current = [...view.html.matchAll(/<a[^>]*aria-current="page"[^>]*>/g)].map((m) => m[0]);
+  expect(current).toHaveLength(2);
+  for (const link of current) expect(link).toContain('href="/dashboard"');
+  // Landmarks come from AppShell: one banner, two navigations (sidebar, bottom bar), one main.
   expect(view.html.match(/<main\\b/g)).toHaveLength(1);
-  expect(view.html.match(/<nav\\b/g)).toHaveLength(1);
+  expect(view.html.match(/<nav\\b/g)).toHaveLength(2);
   expect(view.html).toMatch(/<main[^>]*>the page body<\\/main>/);
 });
 
@@ -295,6 +250,7 @@ import {
   createContext,
   createEffect,
   createMemo,
+  createRoot,
   createSignal,
   onCleanup,
   useContext,
@@ -309,14 +265,24 @@ export interface ThemeToggleIslandProps {
 /**
  * The one export the hydration runtime calls. \`setSolidRuntime\` comes FIRST and is not optional:
  * \`@ultimat3/ui\` imports types from solid-js and never a runtime, so the reactive graph a
- * component reaches is the one an entry registers. Six NAMED imports, never a namespace: a
+ * component reaches is the one an entry registers. Seven NAMED imports, never a namespace: a
  * namespace object keeps every export of solid-js alive in the chunk. The shell is cleared before
  * \`render\`, which APPENDS — the server's copy would otherwise stay on screen beside the live one.
  */
-export function mount(el: HTMLElement, props: ThemeToggleIslandProps): void {
-  setSolidRuntime({ createContext, useContext, createSignal, createMemo, createEffect, onCleanup });
+export function mount(el: HTMLElement, props: ThemeToggleIslandProps): () => void {
+  setSolidRuntime({
+    createContext,
+    useContext,
+    createSignal,
+    createMemo,
+    createEffect,
+    onCleanup,
+    createRoot,
+  });
   el.textContent = '';
-  render(
+  // Solid's disposer, returned: the client router calls it when it navigates away, and a mount
+  // that returns nothing is X_ISLAND_DISPOSER_MISSING.
+  return render(
     () => (
       <UiProvider locale={props.locale}>
         <ThemeToggle mode="toggle" />

package/src/templates/scaffold-test-services.ts

@@ -1,9 +1,10 @@
 // The backing services a new app's suites run against: `docker/docker-compose.test.yml` and the
 // one env file that points the suites at it. In RAM, durability off, silent — the framework's own
 // `docker/docker-compose.test.yml`, cut to what an app has. Ports sit apart from the dev stack's
-// so both can run at once; `ci.yml` starts this file before `bun run check`.
+// so both can run at once; `ci.yml` starts this file before `bun run verify`.
 
 import type { GeneratedFile, NameSet } from './naming';
+import { S3_GATEWAY_IMAGE } from './pinned-images';
 
 export const TEST_COMPOSE_PATH = 'docker/docker-compose.test.yml';
 export const TEST_ENV_PATH = 'docker/test-services.env';
@@ -17,7 +18,7 @@ const composeTest = (
 #
 #   docker compose -f ${TEST_COMPOSE_PATH} up -d --wait
 #   set -a; . ${TEST_ENV_PATH}; set +a
-#   bun run check
+#   bun run verify
 #
 # \`--wait\` returns once every healthcheck passes. CI runs the same lines (.github/workflows/ci.yml).
 # None of it is required: with no TEST_* variable set the unit suite runs on the in-memory driver,
@@ -41,7 +42,9 @@ x-silent: &silent
 services:
   # Postgres 18, the production major. \`initdb -c\` writes each setting into the new cluster;
   # \`--no-sync\` is initdb's own fsync of a cluster on a tmpfs. Postgres 18 images keep the cluster
-  # under /var/lib/postgresql/18, so the tmpfs is the parent.
+  # under /var/lib/postgresql/18, so the tmpfs is the parent. After the logging: no JIT and no
+  # autovacuum for millisecond queries, room for every parallel test process, and a small WAL —
+  # it is RAM here.
   postgres:
     <<: *silent
     image: postgres:18-alpine
@@ -62,6 +65,11 @@ services:
         -c log_checkpoints=off
         -c log_connections=off
         -c log_disconnections=off
+        -c jit=off
+        -c autovacuum=off
+        -c max_connections=400
+        -c min_wal_size=32MB
+        -c max_wal_size=256MB
     tmpfs: [/var/lib/postgresql]
     ports: ['127.0.0.1:${TEST_PORTS.postgres}:5432']
     healthcheck:
@@ -74,7 +82,7 @@ services:
   redis:
     <<: *silent
     image: redis:8-alpine
-    command: ['redis-server', '--save', '', '--appendonly', 'no', '--loglevel', 'warning']
+    command: ['redis-server', '--save', '', '--appendonly', 'no', '--loglevel', 'nothing']
     tmpfs: [/data]
     ports: ['127.0.0.1:${TEST_PORTS.redis}:6379']
     healthcheck:
@@ -99,7 +107,7 @@ services:
   # A directory under /data is a bucket, so the tmpfs mounted AT the bucket's path is the bootstrap.
   s3:
     <<: *silent
-    image: versity/versitygw:v1.8.0@sha256:30292fc2eeacc67a36993b01f7a7a5e3361a19cced0e80c1d71cfa2a4b0a2499
+    image: ${S3_GATEWAY_IMAGE}
     environment:
       VGW_BACKEND: posix
       VGW_BACKEND_ARG: /data