create-ailk 0.28.1 → 0.29.0

package/dist/migrate-content.js

@@ -0,0 +1,215 @@
+/**
+ * `create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>]
+ * [--workspace <id>]` — import an existing site's MDX pages into its
+ * workspace (#10207).
+ *
+ * The same import as `seed-workspace` — `importMdx` over `<dir>/content` with
+ * the site's own installed adapter — for the site `seed-workspace` refuses: one
+ * with no `.ailk-site-manifest.json`, or a spoke, whose workspace lives on its
+ * hub (D1). No manifest and no topology is read; the operator names the API
+ * origin and the workspace, which is all the topology would decide.
+ *
+ * A dry run is the default (D3): the importer runs over `readOnlyFetch`, which
+ * passes each `GET` through and answers a `POST` or `PATCH` locally without
+ * sending it, so the plan — create · update · unchanged · skipped · failed — is
+ * decided by the importer itself against the live workspace, and no write can
+ * leave the process. `--apply` writes; a second `--apply` reports every page
+ * `unchanged`.
+ *
+ * Credentials follow `seed-workspace` (#10204 D2): the origin from
+ * `--api-url`, else `AILK_API_URL`; the workspace id from `--workspace`, else
+ * `AILK_WORKSPACE_ID`; the agent key from `AILK_AGENT_KEY` and nowhere else.
+ * A missing or malformed credential is refused before the adapter is loaded;
+ * every refusal, the importer's included, is thrown before any request.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly. Spec:
+ * docs/specs/10207-create-ailk-migrate-content-import-spec.md.
+ */
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { ParseError } from "./parse-args.js";
+import { AGENT_KEY_ENV_VAR, WORKSPACE_ID_ENV_VAR } from "./seed-workspace.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, } from "./topology.js";
+/** The locale imported: the importer's default. */
+const LOCALE = "en";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export class MigrateContentRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "MigrateContentRefusedError";
+    }
+}
+function refuse(message) {
+    throw new MigrateContentRefusedError(`migrate-content: ${message} Nothing was sent.`);
+}
+/** A value given, or `undefined` for an absent or empty one. */
+function given(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+// ── The dry run's transport (D3) ────────────────────────────────────────────
+/**
+ * A fetch that sends `GET`s through `inner` and never sends a write: a `POST`
+ * is answered `201` and a `PATCH` `200` locally, with the one member of a
+ * write's answer `importMdx` reads (`data.locale`). Any other method throws.
+ */
+export function readOnlyFetch(inner, locale) {
+    return (async (input, init) => {
+        const method = (init?.method ?? (input instanceof Request ? input.method : "GET")).toUpperCase();
+        if (method === "GET")
+            return inner(input, init);
+        if (method !== "POST" && method !== "PATCH") {
+            throw new Error(`a dry run sends no ${method} request`);
+        }
+        return new Response(JSON.stringify({ ok: true, data: { locale } }), {
+            status: method === "POST" ? 201 : 200,
+            headers: { "content-type": "application/json" },
+        });
+    });
+}
+// ── The plan (D4) ───────────────────────────────────────────────────────────
+/** A dry run's verb for what `--apply` would do. */
+const PLAN_VERB = {
+    created: "create",
+    updated: "update",
+    unchanged: "unchanged",
+    skipped: "skipped",
+    failed: "failed",
+};
+function planLine(outcome) {
+    const verb = PLAN_VERB[outcome.result];
+    return "reason" in outcome
+        ? `${outcome.path}: ${verb} — ${outcome.reason}`
+        : `${outcome.path}: ${verb}`;
+}
+// ── The command (D1–D4) ─────────────────────────────────────────────────────
+export async function migrateContent(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    const apply = opts.apply === true;
+    const apiKey = given(env[AGENT_KEY_ENV_VAR]);
+    if (apiKey === undefined) {
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+    }
+    const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
+    if (workspaceId === undefined) {
+        refuse(`no workspace id was given. Pass --workspace <wksp_id>, or set ${WORKSPACE_ID_ENV_VAR}.`);
+    }
+    const flagOrigin = given(opts.apiUrl);
+    const source = flagOrigin !== undefined ? "--api-url" : HUB_ORIGIN_ENV_VAR;
+    const rawOrigin = flagOrigin ?? given(env[HUB_ORIGIN_ENV_VAR]);
+    if (rawOrigin === undefined) {
+        refuse(`no API origin was given. Pass --api-url <origin>, or set ${HUB_ORIGIN_ENV_VAR}.`);
+    }
+    let origin;
+    try {
+        origin = normalizeHubUrl(rawOrigin);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`the API origin must be an https: origin (http: only on a loopback host) with no path, query, fragment or credentials (from ${source}).`);
+    }
+    const at = `workspace ${workspaceId} at ${origin} (from ${source}).`;
+    onLine(apply
+        ? `Migrating ${opts.targetDir} into ${at}`
+        : `Planning ${opts.targetDir} against ${at} Nothing is written without --apply.`);
+    const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
+    const fetch = opts.fetch ?? globalThis.fetch;
+    const result = await importMdx({
+        contentRoot: join(targetDir, "content"),
+        adapters,
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        defaultLocale: LOCALE,
+        fetch: apply ? fetch : readOnlyFetch(fetch, LOCALE),
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        // A dry run's importer lines say `created`/`updated`, which nothing was.
+        ...(apply && { onLine }),
+    });
+    const { failed } = result.counts;
+    if (apply) {
+        onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
+        if (failed > 0) {
+            onLine(`${failed} page(s) were not migrated. Fix them and re-run: create-ailk migrate-content ${opts.targetDir} --apply`);
+        }
+    }
+    else {
+        const { created, updated, unchanged, skipped } = result.counts;
+        for (const outcome of result.pages)
+            onLine(planLine(outcome));
+        onLine(`create ${created} · update ${updated} · unchanged ${unchanged} · skipped ${skipped} · failed ${failed}`);
+        onLine("Dry run: nothing was written. Re-run with --apply to write these pages.");
+        if (failed > 0) {
+            onLine(`${failed} page(s) would fail. Fix them before --apply.`);
+        }
+    }
+    return { result, exitCode: failed > 0 ? 1 : 0 };
+}
+export const MIGRATE_CONTENT_HELP = `create-ailk migrate-content — import an existing site's pages into its workspace.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk migrate-content [<dir>] [--apply] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                    The site. Defaults to the current dir.
+
+Options:
+  --apply                  Write the pages. Without it the command reads the
+                           workspace, prints what it would do, and writes
+                           nothing.
+  --api-url <origin>       The API origin that holds the workspace — on a
+                           spoke, its hub's. Else AILK_API_URL. https: only
+                           (http: on localhost or 127.0.0.1).
+  --workspace <wksp_id>    The workspace the pages are written to. Else
+                           AILK_WORKSPACE_ID.
+  -h, --help               Show this help.
+
+Each content/en/<Type>/<slug>.mdx page (and each legacy
+content/<Type>/<slug>.mdx) is written to the workspace as a draft through
+the API's content routes, with the agent key, which is read from
+AILK_AGENT_KEY only and needs the content-edit grant. Nothing is published,
+so the live site does not change. The site needs no .ailk-site-manifest.json
+and may be a spoke; its dependencies must be installed.
+
+A dry run prints create, update, unchanged, skipped or failed per page. It
+cannot see a write the API would refuse at --apply (a conflict or a server
+error), and a page whose content fails its page type is planned and saved
+with errors the editor shows, not failed. --apply prints created, updated,
+unchanged, skipped or failed per page, so a re-run is safe. Exit 0 when no
+page failed, 1 when any did, 2 on a refusal (nothing is sent).
+`;
+export function parseMigrateContentArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                apply: { type: "boolean", default: false },
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`migrate-content: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`migrate-content takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        apply: parsed.values.apply === true,
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}

package/dist/seed-workspace.d.ts

@@ -0,0 +1,71 @@
+import { type ImportMdxResult, type MdxAdapterModule } from "./lib/import-mdx.js";
+import { type Topology } from "./topology.js";
+/** The environment variable the agent key is read from — and nowhere else. */
+export declare const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
+/** The environment variable the workspace id is read from when no flag names one. */
+export declare const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export declare class SeedWorkspaceRefusedError extends Error {
+    readonly exitCode = 2;
+    constructor(message: string);
+}
+export interface SeedWorkspaceOptions {
+    /** The site. */
+    targetDir: string;
+    /** `--api-url`. */
+    apiUrl?: string | undefined;
+    /** `--workspace`. */
+    workspaceId?: string | undefined;
+    /** Injectable for tests; defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Injectable for tests; defaults to the site's installed adapter. */
+    adapters?: MdxAdapterModule;
+    /** Injectable for tests; defaults to `globalThis.fetch`. */
+    fetch?: typeof globalThis.fetch;
+    /** Injectable for tests; the wait before a rate-limited retry. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Each report line as it happens; defaults to nothing. */
+    onLine?: (line: string) => void;
+}
+export declare function seedWorkspace(opts: SeedWorkspaceOptions): Promise<{
+    result: ImportMdxResult;
+    exitCode: 0 | 1;
+}>;
+export type ScaffoldSeedPlan = {
+    kind: "not-applicable";
+} | {
+    kind: "skip";
+    reason: string;
+} | {
+    kind: "seed";
+};
+export interface ScaffoldSeedPlanInput {
+    topology: Topology | undefined;
+    /** The scaffold's effective module set. */
+    modules: readonly string[];
+    /** Whether `--install` ran. */
+    installed: boolean;
+    env: NodeJS.ProcessEnv;
+}
+/** What the scaffold does about seeding, decided in D3's order. */
+export declare function scaffoldSeedPlan(input: ScaffoldSeedPlanInput): ScaffoldSeedPlan;
+export interface RunScaffoldSeedOptions extends ScaffoldSeedPlanInput {
+    targetDir: string;
+    onLine: (line: string) => void;
+    adapters?: MdxAdapterModule;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * The whole scaffold-time step: plan, then print the skip or run the seed. A
+ * refusal is printed, never thrown, and sets no exit code (D6).
+ */
+export declare function runScaffoldSeed(opts: RunScaffoldSeedOptions): Promise<void>;
+export interface SeedWorkspaceArgs {
+    target: string | undefined;
+    apiUrl: string | undefined;
+    workspaceId: string | undefined;
+    help: boolean;
+}
+export declare const SEED_WORKSPACE_HELP = "create-ailk seed-workspace \u2014 import a starter's pages into its workspace.\n\nUsage:\n  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]\n\nArguments:\n  <dir>                    The site. Defaults to the current dir.\n\nOptions:\n  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:\n                           only (http: on localhost or 127.0.0.1).\n  --workspace <wksp_id>    The workspace the pages are written to. Else\n                           AILK_WORKSPACE_ID.\n  -h, --help               Show this help.\n\nEach content/en/<Type>/<slug>.mdx page is written to the workspace as a\ndraft through the API's content routes, with the agent key, which is read\nfrom AILK_AGENT_KEY only and needs the content-edit grant. Each page prints\ncreated, updated, unchanged, skipped or failed, so a re-run is safe. The\nsite's dependencies must be installed. Exit 0 when every page was seeded, 1\nwhen any failed, 2 on a refusal (nothing is sent).\n";
+export declare function parseSeedWorkspaceArgs(argv: string[]): SeedWorkspaceArgs;

package/dist/seed-workspace.js

@@ -0,0 +1,242 @@
+/**
+ * `create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <id>]`
+ * — import a starter scaffold's pages into its workspace (#10204), and the
+ * scaffold-time step that runs it at the end of `pnpm create ailk`.
+ *
+ * A fresh scaffold's `content/` tree is exactly its roster (spec §1), so the
+ * seed is `importMdx` over `<dir>/content` with the site's own installed
+ * adapter (D1): one `text/page` Artifact per page, and a re-run writes
+ * nothing and reports every page `unchanged`.
+ *
+ * The API origin comes from `--api-url`, else `AILK_API_URL`; the workspace
+ * id from `--workspace`, else `AILK_WORKSPACE_ID`; the agent key from
+ * `AILK_AGENT_KEY` and nowhere else — no flag and no file decides where the
+ * key goes (D2, the `seed-flows` rule, #9969 D8). Every refusal is thrown
+ * before the adapter reads a file and before any request; the origin and its
+ * source are printed before the first one. The importer owns the transport
+ * (#10203 D5): bearer header only, no redirect, the key never printed.
+ *
+ * The scaffold-time step (D3, D6) runs only on a hub with an Admin
+ * (`workspace` or `multi-tenant`), after `--install`, with all three
+ * variables set; otherwise it prints why and the command that seeds later,
+ * or nothing on a site with no Admin. It never fails the scaffold.
+ *
+ * Pure module: no `import.meta.url`, so jest can import it directly. `fetch`,
+ * `sleep`, `env` and the adapter are injectable. Spec:
+ * docs/specs/10204-seed-the-starter-s-roster-spec.md.
+ */
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AddModuleRefusedError } from "./add-module-core.js";
+import { ImportMdxRefusedError, formatImportMdxReport, importMdx, loadSiteMdxAdapter, } from "./lib/import-mdx.js";
+import { ParseError } from "./parse-args.js";
+import { readSiteRoster } from "./site-roster.js";
+import { HUB_ORIGIN_ENV_VAR, TopologyError, normalizeHubUrl, readSiteTopology, } from "./topology.js";
+/** The environment variable the agent key is read from — and nowhere else. */
+export const AGENT_KEY_ENV_VAR = "AILK_AGENT_KEY";
+/** The environment variable the workspace id is read from when no flag names one. */
+export const WORKSPACE_ID_ENV_VAR = "AILK_WORKSPACE_ID";
+/** A refusal the CLI exits 2 on, thrown before any request is sent. */
+export class SeedWorkspaceRefusedError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "SeedWorkspaceRefusedError";
+    }
+}
+function refuse(message) {
+    throw new SeedWorkspaceRefusedError(`seed-workspace: ${message} Nothing was sent.`);
+}
+/** A value given, or `undefined` for an absent or empty one (D2). */
+function given(value) {
+    const trimmed = value?.trim();
+    return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+}
+// ── The command (D4) ────────────────────────────────────────────────────────
+export async function seedWorkspace(opts) {
+    const targetDir = resolve(opts.targetDir);
+    const env = opts.env ?? process.env;
+    const onLine = opts.onLine ?? (() => undefined);
+    let roster;
+    try {
+        roster = readSiteRoster(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof AddModuleRefusedError))
+            throw err;
+        refuse(`${err.message}.`);
+    }
+    if (roster === undefined) {
+        refuse(`${opts.targetDir} has no .ailk-site-manifest.json, so it is not a starter scaffold.`);
+    }
+    let topology;
+    try {
+        topology = readSiteTopology(targetDir);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`${err.message}.`);
+    }
+    if (topology === "spoke") {
+        refuse(`${opts.targetDir} is a spoke: its pages are its own MDX files, and its hub owns the workspace.`);
+    }
+    const apiKey = given(env[AGENT_KEY_ENV_VAR]);
+    if (apiKey === undefined) {
+        refuse(`set ${AGENT_KEY_ENV_VAR} to an agent key with the content-edit grant. It is read from the environment only — never a flag or a file.`);
+    }
+    const workspaceId = given(opts.workspaceId) ?? given(env[WORKSPACE_ID_ENV_VAR]);
+    if (workspaceId === undefined) {
+        refuse(`no workspace id was given. Pass --workspace <wksp_id>, or set ${WORKSPACE_ID_ENV_VAR}.`);
+    }
+    const flagOrigin = given(opts.apiUrl);
+    const source = flagOrigin !== undefined ? "--api-url" : HUB_ORIGIN_ENV_VAR;
+    const rawOrigin = flagOrigin ?? given(env[HUB_ORIGIN_ENV_VAR]);
+    if (rawOrigin === undefined) {
+        refuse(`no API origin was given. Pass --api-url <origin>, or set ${HUB_ORIGIN_ENV_VAR}.`);
+    }
+    let origin;
+    try {
+        origin = normalizeHubUrl(rawOrigin);
+    }
+    catch (err) {
+        if (!(err instanceof TopologyError))
+            throw err;
+        refuse(`the API origin must be an https: origin (http: only on a loopback host) with no path, query, fragment or credentials (from ${source}).`);
+    }
+    onLine(`Seeding ${opts.targetDir} into workspace ${workspaceId} at ${origin} (from ${source}).`);
+    const adapters = opts.adapters ?? (await loadSiteMdxAdapter(targetDir));
+    const result = await importMdx({
+        contentRoot: join(targetDir, "content"),
+        adapters,
+        apiOrigin: origin,
+        workspaceId,
+        apiKey,
+        ...(opts.fetch !== undefined && { fetch: opts.fetch }),
+        ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        onLine,
+    });
+    // The report's count line alone: no page rows.
+    onLine(formatImportMdxReport({ pages: [], counts: result.counts }).trimEnd());
+    const { failed } = result.counts;
+    if (failed > 0) {
+        onLine(`${failed} page(s) were not seeded. Fix them and re-run: create-ailk seed-workspace ${opts.targetDir}`);
+    }
+    return { result, exitCode: failed > 0 ? 1 : 0 };
+}
+const SEED_CREDENTIALS = [
+    HUB_ORIGIN_ENV_VAR,
+    WORKSPACE_ID_ENV_VAR,
+    AGENT_KEY_ENV_VAR,
+];
+/** `A`, `A and B`, `A, B and C`. */
+function joinNames(names) {
+    return names.length <= 1
+        ? names.join("")
+        : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
+}
+/** What the scaffold does about seeding, decided in D3's order. */
+export function scaffoldSeedPlan(input) {
+    if (input.topology === "spoke")
+        return { kind: "not-applicable" };
+    if (!input.modules.includes("workspace") &&
+        !input.modules.includes("multi-tenant")) {
+        return { kind: "not-applicable" };
+    }
+    const unset = SEED_CREDENTIALS.filter((name) => given(input.env[name]) === undefined);
+    if (unset.length > 0) {
+        return {
+            kind: "skip",
+            reason: `Workspace seeding skipped: ${joinNames(unset)} ${unset.length === 1 ? "is" : "are"} not set.`,
+        };
+    }
+    if (!input.installed) {
+        return {
+            kind: "skip",
+            reason: "Workspace seeding skipped: the site's dependencies are not installed (pass --install, or run pnpm install first).",
+        };
+    }
+    return { kind: "seed" };
+}
+/**
+ * The whole scaffold-time step: plan, then print the skip or run the seed. A
+ * refusal is printed, never thrown, and sets no exit code (D6).
+ */
+export async function runScaffoldSeed(opts) {
+    const plan = scaffoldSeedPlan(opts);
+    if (plan.kind === "not-applicable")
+        return;
+    if (plan.kind === "skip") {
+        opts.onLine(plan.reason);
+        opts.onLine(`  To seed it later: ${AGENT_KEY_ENV_VAR}=<key> create-ailk seed-workspace ${opts.targetDir} --api-url <origin> --workspace <wksp_id>`);
+        return;
+    }
+    opts.onLine("Seeding the workspace:");
+    try {
+        await seedWorkspace({
+            targetDir: opts.targetDir,
+            env: opts.env,
+            onLine: opts.onLine,
+            ...(opts.adapters !== undefined && { adapters: opts.adapters }),
+            ...(opts.fetch !== undefined && { fetch: opts.fetch }),
+            ...(opts.sleep !== undefined && { sleep: opts.sleep }),
+        });
+    }
+    catch (err) {
+        if (!(err instanceof SeedWorkspaceRefusedError) &&
+            !(err instanceof ImportMdxRefusedError)) {
+            throw err;
+        }
+        opts.onLine(err.message);
+    }
+}
+export const SEED_WORKSPACE_HELP = `create-ailk seed-workspace — import a starter's pages into its workspace.
+
+Usage:
+  AILK_AGENT_KEY=<key> create-ailk seed-workspace [<dir>] [--api-url <origin>] [--workspace <wksp_id>]
+
+Arguments:
+  <dir>                    The site. Defaults to the current dir.
+
+Options:
+  --api-url <origin>       The site's API origin. Else AILK_API_URL. https:
+                           only (http: on localhost or 127.0.0.1).
+  --workspace <wksp_id>    The workspace the pages are written to. Else
+                           AILK_WORKSPACE_ID.
+  -h, --help               Show this help.
+
+Each content/en/<Type>/<slug>.mdx page is written to the workspace as a
+draft through the API's content routes, with the agent key, which is read
+from AILK_AGENT_KEY only and needs the content-edit grant. Each page prints
+created, updated, unchanged, skipped or failed, so a re-run is safe. The
+site's dependencies must be installed. Exit 0 when every page was seeded, 1
+when any failed, 2 on a refusal (nothing is sent).
+`;
+export function parseSeedWorkspaceArgs(argv) {
+    let parsed;
+    try {
+        parsed = parseArgs({
+            args: argv,
+            strict: true,
+            allowPositionals: true,
+            options: {
+                "api-url": { type: "string" },
+                workspace: { type: "string" },
+                help: { type: "boolean", default: false, short: "h" },
+            },
+        });
+    }
+    catch (err) {
+        throw new ParseError(`seed-workspace: ${err.message}`);
+    }
+    const [target, ...rest] = parsed.positionals;
+    if (rest.length > 0) {
+        throw new ParseError(`seed-workspace takes at most one target directory, got ${parsed.positionals.length} arguments`);
+    }
+    return {
+        target,
+        apiUrl: parsed.values["api-url"],
+        workspaceId: parsed.values.workspace,
+        help: parsed.values.help === true,
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ailk",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "Scaffolder for AI Launch Kit — `pnpm create ailk@latest <dir>` produces a starter repo consuming @working-theory/* from npm (per ADR 0007).",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,8 +28,8 @@
     "tar": "^7.5.21"
   },
   "devDependencies": {
-    "@working-theory/schema": "0.50.0",
-    "@working-theory/templates": "0.50.0"
+    "@working-theory/schema": "0.51.0",
+    "@working-theory/templates": "0.51.0"
   },
   "repository": {
     "type": "git",

package/templates/apps/api/CLAUDE.md

@@ -119,7 +119,7 @@ Routes are versioned under `/v1/*`:
 
 **`AILK_OPERATOR_EMAIL` is REQUIRED for a `workspace`-module deployment** (#5515 item 1), exactly as it already is for the review dashboard. On a build with the `workspace` module and WITHOUT `multi-tenant`, `server.ts`'s `tenantPreHandlerForBuild()` selects the base guard (`src/middleware/default-tenant.ts` → `resolveDefaultTenantForOperator`), which fails CLOSED when the pin is unset: every `/v1/workspaces/*` route answers 403 to everyone — so the module's Admin pages (`apps/web/app/[locale]/(authed)/admin*`, renamed from `workspace` by #5637) render their shared `ForbiddenState` — and — the reason this matters — the TOFU operator bind (`services/default-tenant.ts#bindOperatorMembership`, #3631) is never reached, so the first account to load the settings page cannot seat ITSELF as the sole owner off a plain GET. With `multi-tenant` present, a session that has activated a workspace resolves from it and its Membership, unchanged; a session with NO active workspace (every `apps/web` request) goes through the same `resolveDefaultTenantForOperator`, so on a one-workspace deployment the pin is REQUIRED there too — unset, nobody is seated and those requests answer 403 (#7523). The `kind: "all"` waitlist read likewise needs the caller to BE the pin, not merely a sentinel-org owner. `.env.example` § Single-tenant operator pin carries the operator-facing copy; `src/middleware/__tests__/default-tenant.test.ts` § "#5515 item 1" is the objective record.
 
-The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the write scope is the caller's active workspace, never a body-supplied id). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
+The workspace site-config routes are **identity-bound tenant routes** (guarded by the tenant preHandler; the scope is the workspace the request names — the path's `:workspaceId`, or on a route with none the required `x-ailk-workspace-scope` header — checked against the caller's Membership on every request, never a body-supplied id and never the session's old active-workspace pointer, #10165). Like the sibling `/v1/workspaces/*` routes they have **no anonymous MCP twin** — the OSS MCP surface is identity-blind (`apps/mcp/CLAUDE.md`), so the "1:1 MCP tool" rule above does not apply to them; the tenant-scoped authed MCP surface is tracked in #3591. The `/v1/billing/*` and `/v1/waitlist-experiments/*` routes are the same shape — identity-bound tenant routes, admin/settings-facing rather than agent-facing, no MCP twin.
 
 AEO Layer 1 scoring runs both ways: locally as a CLI command (`ailk audit`, filesystem content-root input) AND behind the anonymous `/v1/aeo/score` HTTP endpoint above (external-URL input, #4666) — the CLI's content-root audit and the route's crawler-fed score are two different input paths over the same underlying scorer, not a contradiction.
 

package/templates/apps/mcp/CLAUDE.md

@@ -124,16 +124,18 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
 **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
+**Redirect (1):** `get_redirect` (#10202 D8) — module-gated (`module: "content-write"`) and licence-feature-tagged (`feature: "workspace"`, the content-write claim), gated on the deployment's `workspace` licence feature under `MCP_FEATURE_GATE_MODE`. It twins `GET /v1/redirects`: given an old site path (and an optional locale) it returns where the site permanently redirects it — `{ from, to, permanent: true }` — or the route's not-found body. Its handler rides `@working-theory/mcp-workspace`'s anonymous `tools` (`redirect.ts`), the pack the `workspace` and `multi-tenant` modules carry, and calls the module-level `apiClient` with no agent key
 
-### Why the parity test counts 21 and a keyless server registers 19 (20 over stdio once Free is released)
+### Why the parity test counts 22 and a keyless server registers 20 (21 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
-  parity test counts that full array. It also holds the thirty-one signed-in
-  workspace tools (#3591), which no anonymous view returns — see § The
+- **22 in the `TOOLS` array / parity test**: the `TOOLS` array in
+  `packages/metadata/src/mcp-tool-catalog.ts` defines 22 anonymous tools; the
+  parity test counts that full array. It also holds the thirty-three signed-in
+  workspace tools (#3591; the content-suggestion pair `draft_page_suggestions`
+  and `decide_page_suggestion` since #10218), 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 or over HTTP — 20 and 21 over stdio once it is
+- **20 registered on a KEYLESS deployment, 21 on a commerce-claimed one,
+  while the Free level is held or over HTTP — 21 and 22 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
@@ -143,16 +145,16 @@ Every tool maps 1:1 to an `apps/api` endpoint. When you change a tool, change th
   `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 or over HTTP (20 over stdio once released)**: since #5853 retired the three content-write
+- **20 anonymous tools while Free is held or over HTTP (21 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"`
+  licence claim, never an identity. The seven carrying `tier: "pro"`
   (`get_flow`, `submit_flow_step`, `list_availability`, `get_event_meta`,
-  `list_meetings`, `create_booking`) are gated at REGISTRATION **and at call time** (#7315):
+  `list_meetings`, `create_booking`, `get_redirect`) are gated at REGISTRATION **and at call time** (#7315):
   each needs its module, and each catalog row names the licence `feature:`
   that entitles it. `start_purchase` is gated at call time by both this
   server-wide gate and its own Gate 2 in `tools/purchase.ts`.
   `MCP_FEATURE_GATE_MODE` (`packages/metadata`) decides what an unheld
-  feature does. In `"warn"` mode (this release) the six register on module
+  feature does. In `"warn"` mode (this release) the seven register on module
   presence alone, and the boot (`bootMcp()`) logs one warning (stderr) per tool
   served without its feature. In `"refuse"` mode (the next release) they
   also need the deployment's licence to hold the feature, and
@@ -283,7 +285,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-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`.
+Last updated: 2026-10-29 — #10202 (D8): `get_redirect` (`mcp-workspace`'s `redirect.ts`, the pack's first anonymous handler) twins `GET /v1/redirects` under `module: "content-write"` and `feature: "workspace"` — 22 in `TOOLS`, 20 registered keyless and 21 commerce-claimed while Free is held, seven `tier: "pro"` — verified against `packages/metadata/src/mcp-tool-catalog.ts`, `packages-paid/mcp-workspace/src/index.ts` and `tests/parity/api-parity/kinds/site.ts`.
+
+Prior: 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`.
 

package/templates/apps/web/CLAUDE.md

@@ -594,6 +594,14 @@ A site serves its services at `/services` unless `content/_site.mdx` sets `servi
 - **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.
 
+## Nav-only lists (`navOnly`)
+
+A list page whose frontmatter sets `navOnly: true` (valid on a registry list type only, #10200) has no page of its own: `honourNavOnly` (`lib/hub-children.tsx`) answers `permanentRedirect` (308) to the first child in the route's own child order (a hub's is slug order after `includeChild`, not the order of links its authored sections carry), at the card's public path with the locale prefix kept, and `notFound()` when it lists none. Only an exact `true` acts; anything else renders as before.
+
+- **Where.** The thirteen hubs inside `hubPageInput` (slug order after `includeChild`; `/services` at `servicePublicPath`), `/alternatives` (`/vs/<slug>`, slug-read order), `/templates`, `/careers` (newest first) and `/reports` (newest first) with one call each, and the childless `/faq`, `/glossary`, `/clients`, `/testimonials` and the `[slug]` `BlogList` teaser, which 404.
+- **Not honoured.** The docs-blog module's Fumadocs `/blog` and `/docs`; `DownloadsList` (`/downloads` already redirects to `/reports`); `LocationsList` (no route). `/sitemap.xml` and `/llms.txt` still list a Nav-only list's URL.
+- **The nav is untouched.** `lib/nav-config.ts` is generated from route surfaces, not from list pages, so the heading and its children stay in the menu.
+
 ## AEO & performance
 
 - Static rendering is the default. Don't introduce client rendering without a reason.
@@ -610,7 +618,9 @@ A site serves its services at `/services` unless `content/_site.mdx` sets `servi
 - 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-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/`.
+Last updated: 2026-10-28 — § Nav-only lists (`navOnly`): a Nav-only list's route answers 308 to its first child and 404 with none (#10200) — verified against `lib/hub-children.tsx` and the nine list routes it is called from beside the hubs.
+
+Prior: 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.