create-ailk 0.13.0 → 0.15.0

package/dist/cli.js

@@ -201,7 +201,9 @@ async function main() {
             targetDir: args.target ?? process.cwd(),
             designsDir: resolve(PKG_ROOT, "site-templates", "designs"),
             siteTemplatesDir: resolve(PKG_ROOT, "site-templates"),
+            templatesDir: resolve(PKG_ROOT, "templates"),
             catalogPath: resolve(PKG_ROOT, "component-catalog.json"),
+            allowUnreadChrome: args.allowUnreadChrome,
         });
         process.stdout.write(formatApplyDesignReport(result));
         process.exit(0);
@@ -317,7 +319,8 @@ async function main() {
     // marketing-site-free` still rides the no-key case (record D11): its
     // `requires` is all-free, so it installs from the shipped
     // `site-templates/` tree with no key and no request.
-    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, } = await scaffold(toScaffoldOptions(opts));
+    const { targetDir: targetAbs, surfaces, starter, modules: effectiveModules, droppedModules, hubOrigin, } = await scaffold(toScaffoldOptions(opts));
+    const isSpoke = opts.topology === "spoke";
     // The starter scaffold() resolved — from --template, or from --shape (#6754 D4).
     const templateName = starter?.template ?? opts.template;
     if (opts.install) {
@@ -345,6 +348,22 @@ async function main() {
         ...(starter !== undefined
             ? [`Starter: shape ${starter.shape}, design ${starter.design}.`]
             : []),
+        // #7426 — a spoke says so, and names what its hosts must carry (D3).
+        ...(isSpoke
+            ? [
+                `Topology: spoke — no apps/api, no database, no sign-in${opts.mcp === false ? ", no apps/mcp" : "; apps/mcp is a stateless front"}.`,
+                ...(droppedModules !== undefined && droppedModules.length > 0
+                    ? [
+                        `Not carried on a spoke: ${droppedModules.join(", ")} (your licence includes ${droppedModules.length === 1 ? "it" : "them"}; a spoke does not admit ${droppedModules.length === 1 ? "it" : "them"} yet).`,
+                    ]
+                    : []),
+                "",
+                `Every host serving this spoke's ${opts.mcp === false ? "apps/web" : "apps/web and apps/mcp"} must carry:`,
+                `  AILK_API_URL=${hubOrigin ?? "<your hub origin>"}   # written to apps/web/.env.local`,
+                "  AILK_SPOKE_KEY             # issued by the hub; never written here",
+                "  AILK_VISITOR_FORWARD_KEY   # issued by the hub; never written here",
+            ]
+            : []),
         "",
     ];
     // Prerequisites (#6440 AC4) — every one the scaffold enforces, and nothing
@@ -373,13 +392,15 @@ async function main() {
     lines.push("Next steps:");
     lines.push(`  cd ${targetAbs}`);
     if (!opts.install) {
-        lines.push("  pnpm install     # also generates the Prisma client");
+        lines.push(isSpoke ? "  pnpm install" : "  pnpm install     # also generates the Prisma client");
     }
     lines.push("  pnpm dev         # http://localhost:3000");
     lines.push("  pnpm build       # production build, when you are ready to deploy");
     lines.push("");
     lines.push("Open http://localhost:3000 to see the home page.");
-    lines.push("Adding auth, saved flows, checkout or database-backed content later? README.md \u00a7 \"When you need a database\" has the one-command setup.");
+    if (!isSpoke) {
+        lines.push("Adding auth, saved flows, checkout or database-backed content later? README.md \u00a7 \"When you need a database\" has the one-command setup.");
+    }
     lines.push("");
     lines.push("Claude Code: the AI Launch Kit skills come from the ailk plugin. Trust this folder and Claude Code loads it, or run in a session:");
     for (const line of PLUGIN_INSTALL_LINES)

package/dist/derive-architecture.d.ts

@@ -1,3 +1,11 @@
+import type { Topology } from "./topology.js";
+/** The topology a document is derived for (#7426 D8). */
+export interface DeriveArchitectureOptions {
+    /** `"hub"` (the default) or `"spoke"`. */
+    topology?: Topology;
+    /** Spoke only: whether the spoke keeps `apps/mcp` (default true). */
+    mcp?: boolean;
+}
 /**
  * Derive the `architecture.yaml` document for a module set.
  *
@@ -6,8 +14,13 @@
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export declare function deriveArchitecture(modules?: string[], surfaces?: string[]): string;
+export declare function deriveArchitecture(modules?: string[], surfaces?: string[], options?: DeriveArchitectureOptions): string;

package/dist/derive-architecture.js

@@ -15,6 +15,12 @@
  */
 import { ARCHITECTURE_BASE, MODULE_SLICES, normalizeModules, } from "./module-architecture.js";
 import { CORE_SURFACE_PATHS, RECOGNIZED_SURFACES, resolveSurfaces, } from "./surfaces.js";
+/** A spoke's composition tiers (#7426 D8): its data and API are the hub's. */
+const SPOKE_TIERS = {
+    data: "none — the hub's database",
+    api: "the hub at AILK_API_URL (apps/mcp is a stateless front)",
+    presentation: "apps/web",
+};
 function isScalar(v) {
     return typeof v === "string" || typeof v === "number";
 }
@@ -150,11 +156,18 @@ function namespacesToYaml(ns) {
  * @param surfaces the enabled gateable route surfaces. Omitted ⟹ derived from
  *   the module set alone (`resolveSurfaces`), so a caller that passes only
  *   modules gets exactly what the modules imply.
+ * @param options the topology (#7426 D8). Absent or `"hub"` ⟹ the output is
+ *   byte-identical to the two-argument form. `"spoke"` ⟹ only the spoke's own
+ *   apps (`web`, and `mcp` unless `mcp: false`), no `namespaces`, no
+ *   `database` root, a top-level `topology: spoke` and the hub-facing
+ *   composition tiers.
  * @returns the complete `architecture.yaml` file content (a deterministic
- *   function of the module SET and the surface SET).
+ *   function of the module SET, the surface SET and the topology).
  * @throws Error on an unrecognized module (defensive; parse-args rejects first).
  */
-export function deriveArchitecture(modules = ["marketing"], surfaces) {
+export function deriveArchitecture(modules = ["marketing"], surfaces, options = {}) {
+    const spoke = options.topology === "spoke";
+    const keepMcp = options.mcp !== false;
     const selected = normalizeModules(modules);
     const slices = selected.map((m) => MODULE_SLICES[m]);
     // The declared route surface (#4154). A scaffold's live-route set is a
@@ -180,12 +193,20 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     };
     for (const s of slices)
         Object.assign(declared, s.apps ?? {});
+    // A spoke carries only its own apps (#7426 D8): web, and mcp unless
+    // `--without-mcp` — never api, never a module's admin.
+    if (spoke) {
+        for (const key of Object.keys(declared)) {
+            if (key !== "web" && !(key === "mcp" && keepMcp))
+                delete declared[key];
+        }
+    }
     // A scaffold carries no `packages/` tree — `@working-theory/*` install from
     // npm — so an entry naming a monorepo folder is dropped rather than shipped
     // as a rule the linter can never apply (#6940). What survives names a path
     // the scaffold has: a declared app, or `database/`.
     const roots = [
-        "database",
+        ...(spoke ? [] : ["database"]),
         ...Object.values(declared).map((a) => a.path),
     ];
     const inScaffold = (p) => {
@@ -209,8 +230,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
             forbidden_patterns: mergeForbidden([...ARCHITECTURE_BASE.appForbiddenPatterns], a.forbidden_patterns ?? []).map(scoped),
         });
     }
-    // namespaces — present only if a data-tier module contributes one.
-    const nsSlice = slices.find((s) => s.namespaces)?.namespaces;
+    // namespaces — present only if a data-tier module contributes one, and
+    // never on a spoke, which has no database/ of its own.
+    const nsSlice = spoke
+        ? undefined
+        : slices.find((s) => s.namespaces)?.namespaces;
     // forbidden_patterns — base floor first, then the selected modules' patterns.
     const extraForbidden = [];
     for (const s of slices)
@@ -218,8 +242,11 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
     const forbidden = mergeForbidden([...ARCHITECTURE_BASE.forbiddenPatterns], extraForbidden).map(scoped);
     const doc = {
         version: ARCHITECTURE_BASE.version,
+        ...(spoke ? { topology: "spoke" } : {}),
         composition_model: {
-            tiers: { ...ARCHITECTURE_BASE.composition_model.tiers },
+            tiers: spoke
+                ? { ...SPOKE_TIERS }
+                : { ...ARCHITECTURE_BASE.composition_model.tiers },
         },
         surfaces: {
             core: [...CORE_SURFACE_PATHS],
@@ -240,6 +267,7 @@ export function deriveArchitecture(modules = ["marketing"], surfaces) {
         "#",
         `# Modules: ${selected.join(", ")}`,
         `# Surfaces: ${enabledSurfaces.length > 0 ? enabledSurfaces.join(", ") : "core only"}`,
+        ...(spoke ? ["# Topology: spoke"] : []),
         "",
     ].join("\n");
     return header + emitDocument(doc);

package/dist/design-compile.d.ts

@@ -15,7 +15,7 @@
  * this compiles to what `SiteThemeSchema` accepts is test-only, by relative
  * path, in `design-compile.test.ts`.
  */
-import type { DesignPackage } from "./design-package.js";
+import { type DesignPackage } from "./design-package.js";
 /** The nine runtime colour slots this compile emits, per mode (D4). */
 export type RuntimeColorSlot = "bg" | "bgMuted" | "surface" | "border" | "text" | "textMuted" | "primary" | "primaryFg" | "accent";
 /** One mode's compiled palette — the shape `SiteThemeSchema`'s partial palette accepts. */
@@ -28,11 +28,72 @@ export interface CompiledDesignTheme {
     eyebrowCase?: "upper" | "sentence";
     placeholders?: "outline" | "fill";
     checkmarks?: "circle" | "plain";
+    /** #7741 D7 — the button shape, copied from `treatments.buttonShape`. */
+    buttonShape?: "control" | "pill";
+    /** #7739 D2 — the ink of headings and labels on a dark ground, verbatim from the package. */
+    darkInk?: "fg" | "accent";
+    /** #7739 D2 — the stat-numeral treatment, verbatim from the package. */
+    figures?: "platform" | "display";
+    /**
+     * #7720 D2 — the display leading pair, present only when the display role
+     * declares `lineHeightMobile`; or, under `typeScale: design` (#7739 D2.2),
+     * every declared field of the five compiled roles.
+     */
+    typography?: CompiledTypography;
+    /**
+     * #7719 D6 — `"site"` paints dark-scoped bands with the site's own dark
+     * colours. Derived (never authored): emitted when the package names the
+     * `solid-dark` surface or declares `darkInk: accent` (#7739 D2.3); absent otherwise.
+     */
+    darkBands?: "platform" | "site";
     colors: {
         light: CompiledColorPalette;
         dark: CompiledColorPalette;
     };
 }
+/**
+ * The compiled type roles (#7720, #7739 D2.2) — the shape `SiteThemeSchema`'s
+ * `typography` accepts. Each role is present only when it carries a field.
+ */
+export interface CompiledTypography {
+    display?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+        lineHeight?: number;
+        lineHeightMobile?: number;
+    };
+    "heading-section"?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+    };
+    "heading-item"?: {
+        fontSize?: string;
+        fontSizeMobile?: string;
+        fontWeight?: number;
+    };
+    body?: {
+        fontSize?: string;
+        lineHeight?: number;
+    };
+    eyebrow?: {
+        fontSize?: string;
+        fontWeight?: number;
+    };
+}
+/** One sourced face (#7720 D3.1): the first family, unquoted, and the rest of the authored stack. */
+export interface CompiledFace {
+    source: "google";
+    family: string;
+    /** The authored stack after the first comma, trimmed and verbatim; "" when there is none. */
+    fallback: string;
+}
+/** `compileDesignFonts`'s return shape — the faces `apps/web/lib/site-fonts.ts` loads. */
+export interface CompiledDesignFonts {
+    display?: CompiledFace;
+    body?: CompiledFace;
+}
 /** Every authored colour key the map may read from (design-package.ts D3). */
 type DesignAuthoredColorKey = "bg" | "fg" | "surface" | "surface-secondary" | "border" | "text-muted" | "brand" | "fg-on-brand" | "accent" | "bg-dark" | "fg-dark" | "border-dark" | "brand-dark" | "surface-dark" | "surface-secondary-dark" | "text-muted-dark" | "fg-on-brand-dark" | "accent-dark";
 /** The five named lossy cases with a row (D4) — an authored key absent falls back. */
@@ -59,7 +120,7 @@ export declare const DESIGN_COLOR_MAP: readonly DesignColorMapRow[];
  */
 export declare const DESIGN_COMPILE_LOSSY: {
     readonly L6: "accentFg, destructive and destructiveFg have no authored source and are never emitted by this compile — the partial palette inherits the platform default.";
-    readonly L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name.";
+    readonly L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name. Three exceptions: the display role's leading pair (lineHeight, lineHeightMobile) compiles into theme.typography.display when lineHeightMobile is declared (#7720); the display/body faces a fontSource names compile to apps/web/lib/site-fonts.ts (#7720); and under treatments.typeScale: design the display, heading-section, heading-item, body and eyebrow roles' sizes, phone sizes, weights and leadings compile into theme.typography (#7739) — never their families or letterSpacing.";
     readonly L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.";
 };
 /**
@@ -68,4 +129,11 @@ export declare const DESIGN_COMPILE_LOSSY: {
  * performs no I/O.
  */
 export declare function compileDesignTheme(pkg: DesignPackage): CompiledDesignTheme;
+/**
+ * The faces a package's display and body roles source (#7720 D3.1), or
+ * `undefined` when neither declares `fontSource`. Pure, like
+ * `compileDesignTheme`; `readDesignPackage` has already constrained every
+ * stack it reads here.
+ */
+export declare function compileDesignFonts(pkg: DesignPackage): CompiledDesignFonts | undefined;
 export {};

package/dist/design-compile.js

@@ -1,3 +1,32 @@
+/**
+ * Compile a `DesignPackage` (design-package.ts) into the `theme:` block a
+ * site's `_site.mdx` carries (#6812 D4, spec docs/specs/6812-the-design-package-design-md-spec.md).
+ *
+ * `compileDesignTheme` is pure and idempotent: it reads `pkg` only, never
+ * mutates it, and has no I/O. The authored→runtime key map is the single
+ * exported table `DESIGN_COLOR_MAP` below — every lossy translation (a
+ * runtime slot the authored quartet has no direct source for) is named as a
+ * `fallback` + `lossy` case, and the cases with no row at all are named in
+ * `DESIGN_COMPILE_LOSSY`.
+ *
+ * This module imports nothing from `@working-theory/site-config` — the
+ * `theme:` block's shape is reproduced structurally here so `create-ailk`
+ * gains no runtime dependency (§ 1.5); the cross-package read that proves
+ * this compiles to what `SiteThemeSchema` accepts is test-only, by relative
+ * path, in `design-compile.test.ts`.
+ */
+import { unquoteFamily } from "./design-package.js";
+/**
+ * #7739 D2.2 — the fields `typeScale: design` compiles, per role, in emission
+ * order. Roles are emitted in this table's order.
+ */
+const COMPILED_TYPE_FIELDS = {
+    display: ["fontSize", "fontSizeMobile", "fontWeight", "lineHeight", "lineHeightMobile"],
+    "heading-section": ["fontSize", "fontSizeMobile", "fontWeight"],
+    "heading-item": ["fontSize", "fontSizeMobile", "fontWeight"],
+    body: ["fontSize", "lineHeight"],
+    eyebrow: ["fontSize", "fontWeight"],
+};
 /**
  * The authored→runtime key map (D4) — 18 rows, one per emitted runtime slot
  * per mode, in the overlay block's key order (bg bgMuted surface border text
@@ -62,9 +91,46 @@ export const DESIGN_COLOR_MAP = [
  */
 export const DESIGN_COMPILE_LOSSY = {
     L6: "accentFg, destructive and destructiveFg have no authored source and are never emitted by this compile — the partial palette inherits the platform default.",
-    L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name.",
+    L7: "typography, rounded and spacing are carried in the package and not compiled — SiteThemeSchema rejects fonts/radius/spacing by name. Three exceptions: the display role's leading pair (lineHeight, lineHeightMobile) compiles into theme.typography.display when lineHeightMobile is declared (#7720); the display/body faces a fontSource names compile to apps/web/lib/site-fonts.ts (#7720); and under treatments.typeScale: design the display, heading-section, heading-item, body and eyebrow roles' sizes, phone sizes, weights and leadings compile into theme.typography (#7739) — never their families or letterSpacing.",
     L8: "an absent treatments key is omitted from the compiled theme block, not defaulted.",
 };
+/** Whether a package names the `solid-dark` surface — in its deck grounds or any section preset (#7719 D6). */
+function usesSolidDark(pkg) {
+    if (pkg.layout.deckGrounds?.includes("solid-dark"))
+        return true;
+    return Object.values(pkg.sections).some((sections) => Object.values(sections).some((preset) => typeof preset === "object" &&
+        preset !== null &&
+        preset.surface === "solid-dark"));
+}
+/** The `typography` group a package compiles (#7720 D2, #7739 D2.2), or `undefined`. */
+function compileTypography(pkg) {
+    if (pkg.treatments?.typeScale === "design") {
+        const result = {};
+        for (const [role, fields] of Object.entries(COMPILED_TYPE_FIELDS)) {
+            const def = pkg.typography[role];
+            if (def === undefined)
+                continue;
+            const compiled = {};
+            for (const field of fields) {
+                const value = def[field];
+                if (value !== undefined)
+                    compiled[field] = value;
+            }
+            if (Object.keys(compiled).length > 0)
+                result[role] = compiled;
+        }
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    const display = pkg.typography["display"];
+    if (display?.lineHeightMobile === undefined)
+        return undefined;
+    return {
+        display: {
+            ...(display.lineHeight !== undefined && { lineHeight: display.lineHeight }),
+            lineHeightMobile: display.lineHeightMobile,
+        },
+    };
+}
 /**
  * Translate a `DesignPackage` into the `theme:` block `SiteThemeSchema.parse`
  * accepts (D4). Pure and idempotent — reads `pkg` only, mutates nothing, and
@@ -88,11 +154,41 @@ export function compileDesignTheme(pkg) {
         target[row.runtime] = value;
     }
     const treatments = pkg.treatments ?? {};
+    const typography = compileTypography(pkg);
+    // #7739 D2.3 — accent ink needs the site's own palette on the band, or the
+    // accent there would be the platform's.
+    const darkBands = usesSolidDark(pkg) || treatments.darkInk === "accent";
     return {
         ...(treatments.corners !== undefined && { corners: treatments.corners }),
         ...(treatments.eyebrowCase !== undefined && { eyebrowCase: treatments.eyebrowCase }),
         ...(treatments.placeholders !== undefined && { placeholders: treatments.placeholders }),
         ...(treatments.checkmarks !== undefined && { checkmarks: treatments.checkmarks }),
+        ...(treatments.buttonShape !== undefined && { buttonShape: treatments.buttonShape }),
+        ...(treatments.darkInk !== undefined && { darkInk: treatments.darkInk }),
+        ...(treatments.figures !== undefined && { figures: treatments.figures }),
+        ...(typography !== undefined && { typography }),
+        ...(darkBands && { darkBands: "site" }),
         colors: { light, dark },
     };
 }
+/**
+ * The faces a package's display and body roles source (#7720 D3.1), or
+ * `undefined` when neither declares `fontSource`. Pure, like
+ * `compileDesignTheme`; `readDesignPackage` has already constrained every
+ * stack it reads here.
+ */
+export function compileDesignFonts(pkg) {
+    const fonts = {};
+    for (const role of ["display", "body"]) {
+        const def = pkg.typography[role];
+        if (def?.fontSource === undefined || def.fontFamily === undefined)
+            continue;
+        const comma = def.fontFamily.indexOf(",");
+        fonts[role] = {
+            source: def.fontSource,
+            family: unquoteFamily(comma === -1 ? def.fontFamily : def.fontFamily.slice(0, comma)),
+            fallback: comma === -1 ? "" : def.fontFamily.slice(comma + 1).trim(),
+        };
+    }
+    return fonts.display !== undefined || fonts.body !== undefined ? fonts : undefined;
+}

package/dist/design-home.d.ts

@@ -0,0 +1,74 @@
+import { type SectionLookCatalog } from "./design-presets.js";
+import type { ResolvedDesign } from "./design-scaffold.js";
+/** Where a site's home page lives, site-relative. */
+export declare const HOME_PAGE_PATH = "content/en/HomePage/home.mdx";
+/** One `home/<shape>.mdx` file of a design package (D1). */
+export interface HomeSeed {
+    readonly shape: string;
+    /** Absolute path, for refusals. */
+    readonly file: string;
+    readonly text: string;
+}
+export type HomeSeedOutcome = "seeded" | "restored" | "unchanged" | "authored" | "no-shape" | "no-home";
+/**
+ * Read and validate `<dir>/home/*` (D1). Refuses with a `DesignPackageError`
+ * naming the file, before any write: a basename that is not a recognized
+ * shape, a page whose `type` is not `HomePage`, `sections` that cannot be
+ * located (or are not in the flow form a carry can splice), a section type
+ * the catalog does not carry, or a `logoCloud` whose `logos` is not `[]`.
+ */
+export declare function readDesignHomeSeeds(dir: string, opts: {
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/**
+ * The seeds a resolved design uses (D1): its own `home/`, else — a
+ * byte-identical copy of a shipped design IS that design — the shipped
+ * design's, else none.
+ */
+export declare function designHomeSeeds(resolved: ResolvedDesign, opts: {
+    designsDir: string;
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/** Every shipped design's seeds (D3's placeholder set reads them all). */
+export declare function shippedHomeSeeds(opts: {
+    designsDir: string;
+    catalog: () => SectionLookCatalog;
+}): HomeSeed[];
+/** The shape's own home: its shape tree's, else the overlay's (spec § 1.4). */
+export declare function shapeHomePath(shape: string, opts: {
+    siteTemplatesDir: string;
+    templatesDir: string;
+}): string;
+/**
+ * A home's content fingerprint (D3): per section in order, its type and its
+ * non-look `data` entries as `[key, normalized raw value]`, sorted by key.
+ * A reflow, a look-field change or a preset leaves it unchanged; ids, the
+ * title, the description and the body are not in it.
+ */
+export declare function fingerprint(text: string, catalog: SectionLookCatalog, file?: string): string;
+/**
+ * The seed's `sections:` value with D4's carry applied from `home`: a seed
+ * `logoCloud` (its `logos: []`) takes the raw `logos` of the home's first
+ * `logoCloud`, or is dropped when the home has none.
+ */
+export declare function applySeed(home: string, seed: HomeSeed, file?: string): string;
+/**
+ * Plan a site home under a design (D3). Writes nothing: `text` is the new
+ * home when the outcome is `seeded` or `restored`, and absent otherwise.
+ */
+export declare function planDesignHome(opts: {
+    /** The site's content/en/HomePage/home.mdx, if any. */
+    current: string | undefined;
+    /** The roster's template shape. */
+    shape: string | undefined;
+    /** The applied design's seed for that shape (D1). */
+    target: HomeSeed | undefined;
+    /** The text of the shape's own home file (spec § 1.4). */
+    shapeHome: string;
+    /** Every shipped design's seeds (filtered to `shape` here). */
+    shippedSeeds: readonly HomeSeed[];
+    catalog: SectionLookCatalog;
+}): {
+    outcome: HomeSeedOutcome;
+    text?: string;
+};