create-ailk 0.6.0 → 0.7.0

package/dist/surfaces.js

@@ -20,8 +20,8 @@
  *
  * The default (`--modules marketing`) enables NO gateable surface: every one of
  * them is a claim about the business that the scaffolder cannot make. The path
- * from there is the `suggest-site-pages` → `scaffold-page` skill pair that
- * already ships in `templates/.claude/skills/`.
+ * from there is the `add-page` skill that already ships in
+ * `templates/.claude/skills/`.
  *
  * Zero runtime dependencies — create-ailk is a published, standalone CLI.
  *
@@ -75,10 +75,19 @@ export const CORE_ROUTE_DIRS = [
     // registering the group keeps `sign-in`'s existing `core` identity exactly.
     `${ROUTE_ROOT}/(auth)`,
     // #5469 D2 — always copied: it is what serves the Free template's
-    // /how-it-works, /features and /blog pages, and it is inert for every slug
-    // that has no LandingPage MDX (notFound), so a scaffold carrying it and no
-    // content is byte-for-byte a scaffold with three more 404s, nothing else.
+    // /blog teaser page (its former /how-it-works and /features siblings
+    // moved to the /use-cases list and the product's own page), and it is
+    // inert for every slug that has no LandingPage MDX (notFound), so a
+    // scaffold carrying it and no content is byte-for-byte a scaffold with one
+    // more 404, nothing else.
     `${ROUTE_ROOT}/[slug]`,
+    // #6658 D3 — the product's own detail page (`/software/product`, a
+    // SoftwareProduct → SoftwareApplication), which replaced the /features
+    // stand-in. Core for the same reason [slug] is: its content
+    // (`content/en/SoftwareProduct/product.mdx`) is in the always-copied overlay
+    // and the generated nav always links it, so every scaffold — template or
+    // not — must carry the route.
+    `${ROUTE_ROOT}/software`,
     // #6084 D12 (the operator's shape-2 disposition) — the checkout return
     // pair. The launchers pointing at them (`apps/mcp/src/tools/purchase.ts`,
     // `apps/web/.../dev/purchase/purchase.actions.ts`) are ALREADY
@@ -118,6 +127,13 @@ export const GATEABLE_SURFACES = [
         content: ["apps/web/content/<locale>/blog"],
         navLabelKey: "blog",
     },
+    {
+        // Module-less (#6658 D5), like `pricing`: every starter's roster names
+        // it. No `navLabelKey` — the footer links it, gated on this surface.
+        id: "book-a-call",
+        routes: [`${ROUTE_ROOT}/book-a-call`],
+        content: ["content/<locale>/BookCall"],
+    },
     {
         id: "careers",
         routes: [`${ROUTE_ROOT}/careers`],
@@ -170,6 +186,12 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/flows`],
         content: [],
     },
+    {
+        // Module-less (#6658 D5) — see `book-a-call`.
+        id: "glossary",
+        routes: [`${ROUTE_ROOT}/glossary`],
+        content: ["content/<locale>/GlossaryList"],
+    },
     {
         id: "how-to",
         routes: [`${ROUTE_ROOT}/how-to`],
@@ -206,6 +228,13 @@ export const GATEABLE_SURFACES = [
         // functional gain, since no route derives from a message key.
         navLabelKey: "schedule",
     },
+    {
+        // Module-less (#6658 D5) — see `book-a-call`. The page's form posts to
+        // lead capture and sends no verification email.
+        id: "newsletter",
+        routes: [`${ROUTE_ROOT}/newsletter`],
+        content: ["content/<locale>/NewsletterSignup"],
+    },
     {
         id: "partners",
         routes: [`${ROUTE_ROOT}/partners`],
@@ -247,11 +276,6 @@ export const GATEABLE_SURFACES = [
         routes: [`${ROUTE_ROOT}/services`],
         content: ["content/<locale>/ServicesList", "content/<locale>/Service"],
     },
-    {
-        id: "software",
-        routes: [`${ROUTE_ROOT}/software`],
-        content: ["content/<locale>/SoftwareProduct"],
-    },
     {
         id: "tech-articles",
         routes: [`${ROUTE_ROOT}/tech-articles`],
@@ -270,7 +294,7 @@ export const GATEABLE_SURFACES = [
     {
         id: "use-cases",
         routes: [`${ROUTE_ROOT}/use-cases`],
-        content: ["content/<locale>/UseCasesList"],
+        content: ["content/<locale>/UseCasesList", "content/<locale>/UseCase"],
     },
     {
         id: "whitepapers",
@@ -288,6 +312,14 @@ export const RECOGNIZED_SURFACES = GATEABLE_SURFACES.map((s) => s.id);
 export const SURFACE_ALIASES = {
     schedule: "meet",
 };
+/**
+ * Surface ids that became core routes (#6658 D3: `software` — the product's
+ * own page is in every scaffold). Accepted and dropped wherever a surface list
+ * is read — a `--surfaces` value or an existing site's `# Surfaces:` header —
+ * so a site scaffolded with `--surfaces software` keeps working: its route
+ * is copied regardless.
+ */
+export const CORE_PROMOTED_SURFACES = new Set(["software"]);
 /** Canonical id for a `--surfaces` value, resolving a retired alias. */
 function canonicalizeSurface(s) {
     return SURFACE_ALIASES[s] ?? s;
@@ -346,7 +378,7 @@ export function parseSurfaces(raw) {
     const requested = raw
         .split(",")
         .map((s) => canonicalizeSurface(s.trim().toLowerCase()))
-        .filter(Boolean);
+        .filter((s) => s !== "" && !CORE_PROMOTED_SURFACES.has(s));
     for (const s of requested) {
         if (!RECOGNIZED_SURFACES.includes(s)) {
             throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
@@ -376,6 +408,8 @@ export function resolveSurfaces(modules = ["marketing"], explicit = []) {
     const selected = new Set(modules.map((m) => m.trim().toLowerCase()));
     for (const raw of explicit) {
         const s = canonicalizeSurface(raw);
+        if (CORE_PROMOTED_SURFACES.has(s))
+            continue;
         if (!RECOGNIZED_SURFACES.includes(s)) {
             throw new SurfaceError(`unknown surface "${s}". Recognized: ${RECOGNIZED_SURFACES.join(", ")}`);
         }
@@ -458,6 +492,10 @@ export function excludedContentPaths(enabled) {
 export const ROUTE_SINCE = {
     about: "0.0.0",
     "blog/[[...slug]]": "0.0.0",
+    // #6658 — four genuinely new route directories (D4, D5), attaching at
+    // today's fixed-group version, the same "attach at today's version" rule
+    // #6084, #5977, #5678, #5479, #5371 and #5048 applied.
+    "book-a-call": "0.26.0",
     careers: "0.0.0",
     "careers/[slug]": "0.0.0",
     "case-studies": "0.0.0",
@@ -475,6 +513,7 @@ export const ROUTE_SINCE = {
     "flows/[slug]": "0.0.0",
     "flows/[slug]/results/[payload]": "0.14.0",
     "flows/[slug]/start": "0.18.0",
+    glossary: "0.26.0",
     "how-to": "0.0.0",
     "how-to/[slug]": "0.0.0",
     integrations: "0.0.0",
@@ -486,6 +525,7 @@ export const ROUTE_SINCE = {
     // in rather than the "predates the manifest" 0.0.0 above.
     "meet/[slug]": "0.5.0",
     "meet/confirmed": "0.0.0",
+    newsletter: "0.26.0",
     partners: "0.0.0",
     "partners/[slug]": "0.0.0",
     // #5479 — three genuinely new route directories, so they attach at today's
@@ -519,6 +559,7 @@ export const ROUTE_SINCE = {
     testimonials: "0.0.0",
     "thanks/[slug]": "0.14.0",
     "use-cases": "0.0.0",
+    "use-cases/[slug]": "0.26.0",
     whitepapers: "0.0.0",
     "whitepapers/[slug]": "0.0.0",
     // #5014 — the (authed) route GROUP: layout.tsx + sign-in-gate.tsx sit
@@ -708,44 +749,113 @@ export const NAV_CONFIG_PATH = "apps/web/lib/nav-config.ts";
  * surface set for the same reason the route tree does.
  *
  * The base items are the Free marketing-site chrome (#5469 D5, the approved
- * chrome diff recorded on that card):
- * a Product flyout (How it works · Features · FAQ), then How it works, Pricing
- * and About. Every one of those pages is in EVERY scaffold — the four core
- * routes plus the `[slug]` route over the overlay's LandingPage MDX — except
- * Pricing, which is a gateable surface: its item is emitted only when the
- * `pricing` surface is enabled (a template roster enables it, #5469 D10), so
- * the nav still never links a page the scaffold does not carry.
+ * chrome diff recorded on that card, re-pointed by #6658 D8):
+ * a Product flyout (Use cases · Features · FAQ), then Use cases, Blog, Pricing
+ * and About. Features links the product's own page (`/software/product`), a
+ * core route like `/faq` and `/about`; `/blog` is always linked (the teaser or
+ * the docs-blog module serves it). Use cases and Pricing are gateable
+ * surfaces: each item is emitted only when its surface is enabled (a template
+ * roster enables it, #5469 D10), so the nav still never links a page the
+ * scaffold does not carry.
  *
  * Only gateable surfaces carrying a `navLabelKey` are linked after the base
  * items, because a nav entry needs a translated label. Emitting an entry whose
  * `labelKey` has no translation would trade a dead link for a missing-message
  * error.
  *
+ * The same file carries `footerColumns`, the footer's column groups (#6468):
+ * label keys and paths only, under the same gates, so the footer links every
+ * seed page the header does not.
+ *
  * Deterministic: gateable entries follow GATEABLE_SURFACES order (alphabetical
  * by id), after the fixed base items.
  */
 export function renderNavConfig(enabled) {
     const on = new Set(enabled);
-    const linked = GATEABLE_SURFACES.filter((s) => s.navLabelKey !== undefined && on.has(s.id));
+    // `blog` is linked unconditionally below (operator ruling 2026-09-23), so
+    // it is excluded here; `use-cases` is the Free roster's own page (a
+    // module-less surface the roster enables, like `pricing`), linked in its
+    // fixed positions below rather than appended.
+    const linked = GATEABLE_SURFACES.filter((s) => s.navLabelKey !== undefined &&
+        on.has(s.id) &&
+        s.id !== "blog" &&
+        s.id !== "use-cases");
+    const useCases = on.has("use-cases");
     const entries = [
         "  {",
         '    labelKey: "product",',
         "    flyout: {",
-        '      presentation: "list",',
-        '      width: "trigger",',
+        // SOFT_LOCK_OK: #6508 — width "panel" (D4/D5): a fixed 640px, two-column
+        // grid, replacing the "list"/"trigger" one-column menu. `presentation` is
+        // omitted — it defaults to "grid" (D5). The `docs` action is dropped (it
+        // duplicated the first feature's /how-it-works destination, § 1.4).
+        '      width: "panel",',
         "      features: [",
-        '        { labelKey: "howItWorks", descKey: "howItWorksDesc", icon: Layers, path: "/how-it-works" },',
-        '        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/features" },',
+        ...(useCases
+            ? ['        { labelKey: "useCases", descKey: "useCasesDesc", icon: Layers, path: "/use-cases" },']
+            : []),
+        '        { labelKey: "features", descKey: "featuresDesc", icon: Sparkles, path: "/software/product" },',
         '        { labelKey: "faq", descKey: "faqDesc", icon: HelpCircle, path: "/faq" },',
         "      ],",
-        '      actions: [{ labelKey: "docs", icon: BookOpen, path: "/how-it-works" }],',
+        "      actions: [],",
         "    },",
         "  },",
-        '  { labelKey: "howItWorks", path: "/how-it-works" },',
+        // Operator ruling 2026-09-23: Product · Use cases · Blog · Pricing · About.
+        // `/blog` is always linked — the `blog` surface serves the real route, and
+        // with it off the `[slug]` route serves the overlay's module page.
+        ...(useCases ? ['  { labelKey: "useCases", path: "/use-cases" },'] : []),
+        '  { labelKey: "blog", path: "/blog" },',
         ...(on.has("pricing") ? ['  { labelKey: "pricing", path: "/pricing" },'] : []),
         '  { labelKey: "about", path: "/about" },',
         ...linked.map((s) => `  { labelKey: "${s.navLabelKey}", path: "/${s.id}" },`),
     ];
+    // The footer's column groups (operator ruling 2026-09-23, replacing #6468's
+    // Product/Company pair): Site pages, Features, Resources. Pricing rides the
+    // same `pricing` gate as the header item; `/blog` is always linked (above).
+    // The product links point at the product's own page, `/software/product`
+    // (#6658 D3): `software` is core, so they stay unconditional. Book a call,
+    // Glossary and Newsletter (#6658 D8) each ride their own surface's gate.
+    const footerEntries = [
+        "  {",
+        '    headingKey: "footerSitePagesHeading",',
+        "    items: [",
+        '      { labelKey: "features", path: "/software/product" },',
+        ...(on.has("pricing")
+            ? ['      { labelKey: "pricing", path: "/pricing" },']
+            : []),
+        ...(useCases ? ['      { labelKey: "useCases", path: "/use-cases" },'] : []),
+        '      { labelKey: "about", path: "/about" },',
+        '      { labelKey: "contact", path: "/contact" },',
+        ...(on.has("book-a-call")
+            ? ['      { labelKey: "bookACall", path: "/book-a-call" },']
+            : []),
+        "    ],",
+        "  },",
+        "  {",
+        '    headingKey: "footerFeaturesHeading",',
+        "    items: [",
+        '      { labelKey: "feature1", path: "/software/product" },',
+        '      { labelKey: "feature2", path: "/software/product" },',
+        '      { labelKey: "feature3", path: "/software/product" },',
+        '      { labelKey: "feature4", path: "/software/product" },',
+        '      { labelKey: "feature5", path: "/software/product" },',
+        '      { labelKey: "allFeatures", path: "/software/product" },',
+        "    ],",
+        "  },",
+        "  {",
+        '    headingKey: "footerResourcesHeading",',
+        "    items: [",
+        '      { labelKey: "blog", path: "/blog" },',
+        ...(on.has("glossary")
+            ? ['      { labelKey: "glossary", path: "/glossary" },']
+            : []),
+        ...(on.has("newsletter")
+            ? ['      { labelKey: "newsletter", path: "/newsletter" },']
+            : []),
+        '      { labelKey: "faq", path: "/faq" },',
+        "    ],",
+        "  },",
+    ];
     // The emitted file imports the consumer's `NavItem` type from the UI package.
     // Assembled from fragments so THIS source file never contains the literal
     // import string: `tools/lint-architecture.ts` matches on source text, so a
@@ -763,15 +873,26 @@ export function renderNavConfig(enabled) {
 // points at a route this site actually carries — the nav is regenerated with
 // the surface set so it can never link a page that was not scaffolded.
 //
-// Adding a link: scaffold the page (the \`scaffold-page\` skill), then add an
+// Adding a link: scaffold the page (the \`add-page\` skill), then add an
 // entry below with a \`labelKey\` that exists in the \`nav\` namespace of
 // \`apps/web/messages/<locale>.json\`. Paths are locale-agnostic — Nav prefixes
 // them with the active locale at render.
 ${navItemImport}
-import { BookOpen, HelpCircle, Layers, Sparkles } from "lucide-react";
+import { HelpCircle, Layers, Sparkles } from "lucide-react";
 
 export const navItems: NavItem[] = [
 ${entries.join("\n")}
 ];
+
+// Footer column groups. Keys only — the layout resolves each \`headingKey\`
+// and \`labelKey\` through the same \`nav\` labels as the header.
+export interface FooterColumnConfig {
+  headingKey: string;
+  items: { labelKey: string; path: string }[];
+}
+
+export const footerColumns: FooterColumnConfig[] = [
+${footerEntries.join("\n")}
+];
 `;
 }

package/dist/sync-routes.d.ts

@@ -15,6 +15,15 @@ export interface SyncRoutesOptions {
     versions: WorkspaceVersionMap;
     /** Copy the missing routes into the target. Default false = check only. */
     apply?: boolean;
+    /**
+     * Surface ids to treat as carried whether or not any of their route dirs
+     * exists yet (#6653 D8) — `add-module` passes the added module's
+     * `MODULE_SURFACES`, since a surface whose routes ship from `templates/`
+     * would otherwise read as not-carried on first add and never be copied.
+     * Undefined for every other caller: the carried set is then exactly the
+     * presence-derived one.
+     */
+    forceSurfaces?: readonly string[];
 }
 /** One route directory the report names. */
 export interface RouteReport {

package/dist/sync-routes.js

@@ -141,10 +141,10 @@ export function syncRoutes(opts) {
     // unrelated "projects" CONTENT surface is separately requested. Without
     // this exclusion, a signal-collectors-only scaffold would falsely read as
     // "carries projects" the moment its bundle lands that one file.
-    const carried = new Set();
+    const carried = new Set(opts.forceSurfaces ?? []);
     const skippedSurfaces = [];
     for (const surface of GATEABLE_SURFACES) {
-        const present = surface.routes.some((r) => {
+        const present = carried.has(surface.id) || surface.routes.some((r) => {
             const p = join(targetAbs, r);
             if (!existsSync(p) || !statSync(p).isDirectory())
                 return false;

package/dist/template-manifest.d.ts

@@ -18,6 +18,33 @@ import type { CategorySlug } from "@working-theory/schema/categories";
 import { type PageRosterRow } from "./module-architecture.js";
 import type { ModuleName } from "./parse-args.js";
 import type { TemplateLayout } from "./site-chrome.js";
+/**
+ * The closed **shape** enum (starter-template contract § The three axes,
+ * operator-disposed 2026-09-24) — `<primary node>-<offering node>` in
+ * schema.org terms, kebab-cased. Declared beside `TemplateManifest`, the same
+ * pattern `ModuleName` uses in `parse-args.ts`: a `readonly [...] as const`
+ * array plus its derived literal-union type, so an unrecognized value fails
+ * type-check rather than a runtime validation.
+ */
+export declare const STARTER_SHAPES: readonly ["organization-product", "organization-service", "local-business-service", "local-business-product", "person-service"];
+export type StarterShape = (typeof STARTER_SHAPES)[number];
+/**
+ * The closed **design** enum (same contract section) — the look applied to
+ * any shape; orthogonal to it by construction.
+ */
+export declare const STARTER_DESIGNS: readonly ["standard", "minimalism"];
+export type StarterDesign = (typeof STARTER_DESIGNS)[number];
+/**
+ * Each design's layout knobs (#6638) — the part of a design that is chrome,
+ * so a template names `design:` instead of re-typing a `layout` block, and any
+ * shape can wear any design. `resolveSiteChrome(layout, design)` reads it:
+ * an explicit `TemplateManifest.layout` wins field by field, then this, then
+ * `DEFAULT_SITE_CHROME`. `standard` declares nothing — it IS the defaults, so
+ * spelling them out here would be a second copy of them to drift. A plain
+ * object, not a file: this module touches no disk. The design's documented
+ * look lives in `site-templates/designs/<design>/DESIGN.md`.
+ */
+export declare const DESIGN_LAYOUTS: Readonly<Record<StarterDesign, TemplateLayout>>;
 /**
  * One site template: its fixed module list and the page rows it brings itself.
  *
@@ -57,6 +84,20 @@ export interface TemplateManifest {
      * registry — never a group here.
      */
     categories: readonly CategorySlug[];
+    /**
+     * The shape this template's roster renders (starter-template contract § The
+     * three axes) — `<primary node>-<offering node>`, from the closed
+     * {@link STARTER_SHAPES} enum. Owns the entity preset, the roster and each
+     * page's section stack; the machine truth the showcase, the build-starter
+     * skill and the render gate read — never the directory name.
+     */
+    shape: StarterShape;
+    /**
+     * The design this template renders (same contract section) — the look,
+     * orthogonal to `shape` by construction: any design applies to any shape.
+     * From the closed {@link STARTER_DESIGNS} enum.
+     */
+    design: StarterDesign;
     /**
      * The template this one EXTENDS — its lineage, never its level (#5618 D2).
      * A single parent, not a list: "later layers win file by file" needs a
@@ -70,7 +111,7 @@ export interface TemplateManifest {
      */
     extends: string;
     /** Base rows, before any module's contribution is merged. */
-    roster: readonly PageRosterRow[];
+    roster: readonly TemplateRosterRow[];
     /** Bundle-relative source → scaffold-relative destination. */
     installMap?: Record<string, string>;
     /**
@@ -94,6 +135,21 @@ export interface TemplateManifest {
  * the directory-scanning tests key their skip on.
  */
 export declare const BASE_LAYER_DIR = "_base";
+/**
+ * One row of a template's own roster — the same shape as a module's
+ * `PageRosterRow`, `contentDir` included (#6646 disposition (a)): a module's
+ * contributed detail row (`/reports/[slug]`) serves a seed directory exactly
+ * as a template's own does. Where `routes-map.ts` records the route's
+ * `contentPath`, the generator refuses a `contentDir` that disagrees.
+ */
+export type TemplateRosterRow = PageRosterRow;
+/**
+ * Whether a merged roster declares one scaffold-relative content file
+ * (#6646 D1): named by a row's `content`, or under a row's `contentDir`.
+ * The one predicate the scaffold's per-row install and the manifest
+ * generator's install-diff both read, so the two cannot disagree.
+ */
+export declare function rosterDeclares(roster: readonly TemplateRosterRow[], path: string): boolean;
 /** Thrown on an undeclared template name or a route claimed twice. Mirrors `SurfaceError`'s shape. */
 export declare class TemplateError extends Error {
     constructor(message: string);
@@ -161,7 +217,7 @@ export declare function resolveTemplateLineage(name: string, registry?: Readonly
  *   runtime by a base-wins or module-wins precedence rule, either of which
  *   silently produces a site missing a page someone declared.
  */
-export declare function mergeRoster(manifest: TemplateManifest, modules: readonly string[]): PageRosterRow[];
+export declare function mergeRoster(manifest: TemplateManifest, modules: readonly string[]): TemplateRosterRow[];
 /**
  * Whether a template installs on the keyless path or needs a verified
  * `AILK_LICENSE_KEY` — derived from `requires`, never declared (parent § D3).