create-ailk 0.1.0 → 0.1.1

package/dist/module-architecture.js

@@ -0,0 +1,663 @@
+/**
+ * Module → architecture-slice registry.
+ *
+ * The single source that turns the `--modules` selection into a scaffolded
+ * site's `architecture.yaml` (its code-boundary config — the apps/packages/
+ * namespaces the linter walks + the import rules it enforces). Each recognized
+ * module maps to the architecture FRAGMENT it contributes; `deriveArchitecture`
+ * (derive-architecture.ts) composes a module-independent BASE + the selected
+ * slices into one deterministic document.
+ *
+ * Grounded in the root AILK `architecture.yaml` `composition_model`: a customer
+ * site is the three-tier AILK app (data · api · presentation) COMPOSED of the
+ * selected modules. `marketing` is the thin presentation default and is
+ * validated end-to-end; `docs` (a mountable presentation surface) and
+ * `multi-tenant` (a full-stack module) are registry-defined ahead of their
+ * template trees (per spec #3787 D3). `scheduling` (#4633) contributes all
+ * three tiers — the provider client, the /v1/schedule/* routes, and the
+ * booker + confirmation pages — into the marketing surface.
+ *
+ * Design (spec #3787 D1): a code registry, NOT N hand-maintained per-module
+ * `architecture.yaml` template files — a fixed template IS the drift this
+ * removes.
+ */
+import { RECOGNIZED_MODULES } from "./parse-args.js";
+/**
+ * The standalone-site "no upstream-monorepo import" forbidden pattern, assembled
+ * from fragments so this source file does not itself contain the literal
+ * substring the repo's own `tools/lint-architecture.ts` forbids (a scaffolded
+ * SITE's boundary data, defined here, must not trip the harness's boundary lint
+ * — the same technique __tests__/security.test.ts uses for the Stripe-key rule).
+ */
+const NO_UPSTREAM_IMPORT_PATTERN = ["from '", "platform/"].join("");
+/**
+ * The scheduling module's three credential-boundary patterns, assembled from
+ * fragments for the same reason as NO_UPSTREAM_IMPORT_PATTERN above: these are
+ * a scaffolded SITE's boundary DATA, and this repo's own
+ * `tools/lint-architecture.ts` matches raw source text — a literal here would
+ * read as create-ailk violating the very rules it is declaring.
+ */
+/**
+ * The provider's domain, in any form. Deliberately the whole domain rather
+ * than just its REST host: the failure this module exists to prevent reached
+ * the provider through its embed script, served from a DIFFERENT subdomain,
+ * not through the API host at all.
+ */
+const CAL_DOMAIN_PATTERN = ["cal", "\\.com"].join("");
+/** The provider's browser embed package — the iframe path, by import specifier. */
+const CAL_EMBED_PACKAGE_PATTERN = ["@cal", "com/"].join("");
+/**
+ * The credential's NAME, not a particular way of reading it. An earlier version
+ * matched `process.env[...]` and was trivially sidestepped by destructuring,
+ * optional chaining, or an aliased `env`; naming the variable catches all of
+ * them, and a file outside apps/api has no business mentioning it at all.
+ */
+const CAL_KEY_PATTERN = ["CAL", "_API_KEY"].join("");
+/**
+ * Any browser-published scheduling variable, not just one spelling. Matching a
+ * single prefix missed the obvious variants (the provider's company name run
+ * together, "calendar", "booking"); the alternation below covers them while
+ * still not matching the locales variable, whose value contains those three
+ * letters but never followed by an underscore.
+ */
+const PUBLIC_SCHEDULING_VAR_PATTERN = [
+    "NEXT_PUBLIC_[A-Z0-9_]*(",
+    "CAL",
+    "_|CALCOM|CALENDAR|SCHEDUL|BOOKING)",
+].join("");
+/**
+ * The module-independent base: `apps/web` (the Next.js presentation shell every
+ * AILK site has) plus the standalone forbidden-pattern floor. `may_import_from`
+ * starts EMPTY — the selected modules fill it via `webImports`.
+ */
+export const ARCHITECTURE_BASE = {
+    version: 1,
+    composition_model: {
+        reference: "claude-setup rules/need-to-know.md § Vocabulary (Module / Surface)",
+        tiers: {
+            data: "database/ — Prisma schema + migrations",
+            api: "apps/api (public HTTP API) + apps/mcp (agent tools)",
+            presentation: "apps/web — frontend surfaces",
+        },
+    },
+    /** The base apps/web shell. may_import_from is filled from the selected modules' webImports. */
+    web: {
+        path: "apps/web",
+        description: "Next.js — presentation tier. Frontend surfaces composed from the selected modules.",
+        may_not_import_from: ["apps/api", "apps/mcp"],
+        forbidden_patterns: [
+            {
+                pattern: NO_UPSTREAM_IMPORT_PATTERN,
+                reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports",
+            },
+            {
+                pattern: "@alkit/",
+                reason: "Renamed to @working-theory/* on extraction",
+            },
+        ],
+    },
+    /** Standalone-site forbidden-pattern floor (top-level, always present). */
+    forbiddenPatterns: [
+        {
+            pattern: NO_UPSTREAM_IMPORT_PATTERN,
+            reason: "A scaffolded AILK site is standalone — no upstream-monorepo imports anywhere",
+        },
+        {
+            pattern: "import.*from ['\"]@alkit/",
+            reason: "Renamed to @working-theory/* on extraction; @alkit/ is a foreign namespace",
+        },
+    ],
+};
+/**
+ * The per-module slices. Authored for every `RECOGNIZED_MODULES` value; only
+ * `marketing` (the default) is validated end-to-end against a golden.
+ */
+export const MODULE_SLICES = {
+    // ── marketing — thin presentation module (the default) ───────────────────
+    marketing: {
+        webImports: [
+            "packages/content-adapters",
+            "packages/jsonld",
+            "packages/metadata",
+            "packages/page-renderer",
+            "packages/schema",
+            "packages/sections-registry",
+            "packages/site-config",
+            "packages/theme",
+            "packages/ui",
+            "packages/validation",
+            "packages/web-i18n",
+        ],
+        packages: {
+            "content-adapters": {
+                description: "MDX (default) + pluggable CMS content adapters",
+                may_import_from: ["packages/schema", "packages/validation"],
+            },
+            jsonld: {
+                description: "React component rendering schema.org JSON-LD on pages",
+                may_import_from: ["packages/schema"],
+            },
+            metadata: {
+                description: "Site metadata builders",
+                may_import_from: ["packages/validation"],
+            },
+            "page-renderer": {
+                description: "Composable page-render pipeline (frontmatter → JSON-LD → sections)",
+                may_import_from: [
+                    "packages/content-adapters",
+                    "packages/jsonld",
+                    "packages/schema",
+                    "packages/sections-registry",
+                    "packages/ui",
+                    "packages/validation",
+                ],
+            },
+            schema: {
+                description: "schema.org JSON-LD builders",
+                may_import_from: ["packages/validation"],
+            },
+            "sections-registry": {
+                description: "Typed section catalog for the composable page types",
+                may_import_from: [
+                    "packages/content-adapters",
+                    "packages/schema",
+                    "packages/theme",
+                    "packages/ui",
+                    "packages/validation",
+                ],
+            },
+            "site-config": {
+                description: "Site-level configuration (siteName, baseUrl, site identity)",
+                may_import_from: ["packages/validation"],
+            },
+            theme: {
+                description: "Design tokens",
+                may_import_from: [],
+            },
+            ui: {
+                description: "React component hierarchy — primitives → blocks → sections",
+                may_import_from: [
+                    "packages/schema",
+                    "packages/sections-registry",
+                    "packages/theme",
+                    "packages/validation",
+                ],
+            },
+            validation: {
+                description: "Zod schemas + shared types",
+                may_import_from: [],
+            },
+            "web-i18n": {
+                description: "Shared i18n helpers for web surfaces",
+                may_import_from: [],
+            },
+        },
+    },
+    // ── docs — mountable presentation surface (fumadocs) ─────────────────────
+    docs: {
+        webImports: ["packages/fumadocs-schema"],
+        packages: {
+            "fumadocs-schema": {
+                description: "Fumadocs ↔ schema.org bridge — BlogList / DocsPage JSON-LD from Fumadocs MDX",
+                may_import_from: ["packages/schema", "packages/validation"],
+            },
+        },
+        // ownedFiles (S1, #5088). packages/fumadocs-schema/** is deliberately NOT
+        // listed: it is a JSON-LD bridge over the oss `packages/schema`, consumed
+        // by the Free `/blog` route, and was tiered `oss` in architecture.yaml
+        // (Sam, 2026-09-10, REL-015 #5182 Q3). The docs module owns its ROUTES,
+        // not that helper — the strip keeps the package in the public tree.
+        // (`webImports` above still names it, so a docs scaffold still installs it.)
+        //
+        // apps/web's own `/docs` catch-all route IS module-owned and IS listed
+        // (verified against the filesystem — it exists today, contrary to this
+        // slice's header comment suggesting docs may have "zero apps/web files
+        // today"). Its two closest neighbors are deliberately NOT listed, because
+        // both are genuinely mixed with the base `/blog` route rather than
+        // docs-exclusive (checked by reading each file in full):
+        //   - apps/web/lib/source.ts        — exports BOTH `blogSource` and
+        //     `docsSource` from one file; `/blog` (base) needs the former.
+        //   - apps/web/source.config.ts     — defines BOTH the `blog` and `docs`
+        //     Fumadocs collections in one `defineDocs` pair.
+        // A strip tool cannot delete either without breaking `/blog`, which ships
+        // in every OSS build regardless of the docs module. apps/web/content/en/docs/
+        // (the MDX content itself, not source) is also excluded — content, not code.
+        ownedFiles: ["apps/web/app/[locale]/docs/[[...slug]]/page.tsx"],
+    },
+    // ── multi-tenant — full-stack module (data + api + presentation) ─────────
+    //
+    // The FEAT-042 Organization → Workspace → Membership tenancy layer:
+    // schema (auth/content namespaces) + workspace-scoped API (apps/api) +
+    // the authed workspace app surface (apps/workspace). Single-tenant sites
+    // (module absent) ship none of this — same base apps/web, fixed scope.
+    "multi-tenant": {
+        apps: {
+            workspace: {
+                path: "apps/workspace",
+                description: "Next.js — authed workspace app (Organization → Workspace → Membership). Hosts the organization-plugin Better Auth handlers; imports the database only via lib/prisma-for-auth.ts (auth-adapter exception); all domain data via apps/api's workspace-scoped routes over HTTP.",
+                may_import_from: [
+                    "database",
+                    "packages/templates",
+                    "packages/theme",
+                    "packages/ui",
+                    "packages/validation",
+                ],
+                may_not_import_from: [
+                    "apps/api",
+                    "apps/mcp",
+                    "apps/web",
+                    "packages/email",
+                    "packages/stripe-client",
+                ],
+            },
+            api: {
+                path: "apps/api",
+                description: "Public HTTP API — routes + services (Fastify). Owns webhooks, checkout, email, server-side analytics.",
+                may_import_from: [
+                    "database",
+                    "packages/analytics",
+                    "packages/email",
+                    "packages/license",
+                    "packages/schema",
+                    "packages/site-config",
+                    "packages/stripe-client",
+                    "packages/validation",
+                ],
+                may_not_import_from: [
+                    "apps/mcp",
+                    "apps/web",
+                    "packages/theme",
+                    "packages/ui",
+                ],
+            },
+            mcp: {
+                path: "apps/mcp",
+                description: "MCP server — agent-facing tools. Calls apps/api for writes; never holds Stripe/email secrets.",
+                may_import_from: [
+                    "database",
+                    "packages/api-client",
+                    "packages/license",
+                    "packages/schema",
+                    "packages/site-config",
+                    "packages/validation",
+                ],
+                may_not_import_from: [
+                    "apps/api",
+                    "apps/web",
+                    "packages/email",
+                    "packages/stripe-client",
+                    "packages/theme",
+                    "packages/ui",
+                ],
+            },
+        },
+        packages: {
+            analytics: {
+                description: "Event wrapper — client + server analytics",
+                may_import_from: ["packages/validation"],
+            },
+            "api-client": {
+                description: "HTTP client (web + mcp → apps/api)",
+                may_import_from: ["packages/validation"],
+            },
+            email: {
+                description: "Email send + templates (provider-swappable adapter)",
+                may_import_from: ["packages/validation"],
+            },
+            license: {
+                description: "License-validation client",
+                may_import_from: ["packages/api-client", "packages/validation"],
+            },
+            "stripe-client": {
+                description: "Stripe SDK wrapper + webhook signature verification",
+                may_import_from: ["packages/validation"],
+            },
+            // apps/workspace presentation deps. templates is net-new here; theme/ui/
+            // validation duplicate the marketing slice's definitions VERBATIM so the
+            // Object.assign merge in deriveArchitecture is order-independent (a
+            // multi-tenant-only selection stays self-consistent).
+            templates: {
+                description: "Shell/Chrome composition — WorkspaceShell + ArtifactEditorShell (tier-5 shells)",
+                may_import_from: ["packages/theme", "packages/ui", "packages/validation"],
+            },
+            theme: {
+                description: "Design tokens",
+                may_import_from: [],
+            },
+            ui: {
+                description: "React component hierarchy — primitives → blocks → sections",
+                may_import_from: [
+                    "packages/schema",
+                    "packages/sections-registry",
+                    "packages/theme",
+                    "packages/validation",
+                ],
+            },
+            validation: {
+                description: "Zod schemas + shared types",
+                may_import_from: [],
+            },
+        },
+        namespaces: {
+            description: "Per-namespace boundaries inside database/. Logical-only isolation; no Postgres-schema-level changes.",
+            members: {
+                auth: {
+                    path: "database/auth",
+                    description: "Identity, sessions, OAuth, agent context, tenancy membership (Organization / Workspace / Membership / Invitation)",
+                },
+                config: {
+                    path: "database/config",
+                    description: "Site-wide settings",
+                },
+                content: {
+                    path: "database/content",
+                    description: "Content-adapter persistence + chat/artifact substrate (AgentSession, ConversationEvent, Artifact — workspaceId-scoped, no cross-namespace FK)",
+                },
+                ops: {
+                    path: "database/ops",
+                    description: "AEO scores, audit log, analytics events",
+                },
+            },
+            rules: [
+                "No cross-namespace Prisma @relation.",
+                "No cross-namespace TS imports between database/<a>/ and database/<b>/.",
+                "Cross-namespace data assembly routes through apps/api/src/services/.",
+            ],
+        },
+        forbiddenPatterns: [
+            {
+                pattern: "import.*['\"]stripe['\"]",
+                paths_excluded: ["packages/stripe-client/**"],
+                reason: "Stripe SDK imports go through packages/stripe-client only — single point of config",
+            },
+            {
+                pattern: "import.*['\"]resend['\"]|['\"]nodemailer['\"]",
+                paths_excluded: ["packages/email/**"],
+                reason: "Email provider SDKs go through packages/email — provider swap is a one-package change",
+            },
+        ],
+        // ownedFiles (S1, #5088). Verified against the current filesystem and
+        // server.ts's module-conditional registration (isModuleEnabled('multi-tenant')).
+        //
+        // apps-paid/workspace/** is a single glob — the whole app (43 files as of
+        // this pass, excluding __tests__/node_modules), just moved here from
+        // apps/workspace by a parallel workstream on this same branch. Unlike
+        // every other entry below, this one is intentionally a glob, not an
+        // enumeration.
+        //
+        // apps/api/src/routes/project-listings/ is MIXED (free anonymous surface
+        // + tenant dashboard sharing one directory) — only the tenant-guarded
+        // trio is listed:
+        //   - get.ts, list.ts, patch.ts        — tenant-guarded (projectListingTenantRoutes)
+        // Deliberately EXCLUDED, all confirmed by reading server.ts + grepping
+        // every importer:
+        //   - start.ts, patch-draft.ts, submit.ts, public.ts, resume-token.ts —
+        //     the free anonymous surface (leadsScope in server.ts).
+        //     resume-token.ts is imported ONLY by patch-draft.ts + submit.ts
+        //     (both free) — free-surface-exclusive, not multi-tenant.
+        //   - index.ts — the barrel BOTH leadsScope and tenantScope import from
+        //     (projectListingStartRoute etc. AND projectListingTenantRoutes);
+        //     never edited/deleted on its own per this card's constraint.
+        //   - respond.ts — a `sendValidated` helper imported by get.ts/list.ts/
+        //     patch.ts (tenant) AND ALSO by patch-draft.ts/public.ts (free) —
+        //     shared within the directory across the free/paid split, so it stays.
+        //
+        // apps/api/src/routes/waitlist-experiments/respond.ts, by contrast, IS
+        // listed: grepped every `from "./respond.js"` importer in the repo and
+        // it is used ONLY by this directory's own comparison.ts/list.ts/signup.ts/
+        // signups.ts — all four tenant-scoped — so unlike its project-listings
+        // namesake it is NOT shared with a free route.
+        //
+        // apps/api/src/middleware/tenant.ts, services/tenant-context.ts,
+        // services/waitlist-dashboard.ts: each grepped for every importer
+        // repo-wide. tenant.ts is registered only in server.ts's tenantScope;
+        // tenant-context.ts backs only workspaces/tenant-guarded routes;
+        // waitlist-dashboard.ts backs only the four waitlist-experiments handlers
+        // above. None is reachable from a free route.
+        //
+        // apps/api/src/lib/tenant-db.ts and lib/ws-token.ts are an ADDITION beyond
+        // this card's literal checklist, found by tracing workspaces/*.ts's own
+        // imports: tenant-db.ts (the per-tenant Prisma-scoped client) is used only
+        // by services/tenant-context.ts and the three workspaces/*.ts route files
+        // below; ws-token.ts (realtime push-channel token minting) is used only
+        // by workspaces/sessions.ts. Both are genuinely tenant-exclusive by the
+        // same grep-every-importer standard applied to everything else here.
+        //
+        // NOT listed, deliberately, despite living in apps/api/src/services/ and
+        // being imported ONLY by billing/*.ts today: usage-aggregation.ts,
+        // usage-credits.ts, entitlements.ts, usage-metering.ts. Their names don't
+        // match this card's "tenant/workspace/org-specific" naming test, and
+        // apps/api/CLAUDE.md documents them as a standing "Services
+        // (billing-ledger)" concern rather than a module-conditional one (unlike
+        // every route registration this slice's other entries trace back to,
+        // which server.ts explicitly marks "Module-conditional (S1, #5088)").
+        // Their current single-caller status may just be incidental integration,
+        // not a documented module boundary — flagged for reviewer judgment
+        // rather than asserted here.
+        //
+        // database/auth/ and database/content/ — investigated, NOT listed.
+        // Both namespaces DO have their own schema.prisma file (a real
+        // filesystem split via Prisma's multi-file schema feature), but each
+        // file's CONTENTS are mixed at the model level, not module-exclusive:
+        //   - database/auth/schema.prisma mixes base identity/session models
+        //     (needed by every deployment) with the Organization/Workspace/
+        //     Membership/Invitation tenancy models (multi-tenant only).
+        //   - database/content/schema.prisma's models (AgentSession,
+        //     ConversationEvent, Artifact, UsageEvent, ...) look workspace-scoped
+        //     but billing-ledger models among them are not confirmed
+        //     module-exclusive per the same caution as the services above.
+        // Consistent with this slice's own namespaces.members[].path (directory
+        // grain only): the boundary here is enforced at the Prisma-model level,
+        // not file grain, so it stays out of this literal list rather than
+        // asserting a split the evidence doesn't cleanly support.
+        ownedFiles: [
+            "apps/api/src/routes/workspaces/index.ts",
+            "apps/api/src/routes/workspaces/sessions.ts",
+            "apps/api/src/routes/workspaces/config.ts",
+            "apps/api/src/routes/billing/index.ts",
+            "apps/api/src/routes/billing/portal.ts",
+            "apps/api/src/routes/billing/read.ts",
+            "apps/api/src/routes/billing/usage.ts",
+            "apps/api/src/routes/waitlist-experiments/index.ts",
+            "apps/api/src/routes/waitlist-experiments/list.ts",
+            "apps/api/src/routes/waitlist-experiments/comparison.ts",
+            "apps/api/src/routes/waitlist-experiments/signup.ts",
+            "apps/api/src/routes/waitlist-experiments/signups.ts",
+            "apps/api/src/routes/waitlist-experiments/respond.ts",
+            "apps/api/src/routes/project-listings/get.ts",
+            "apps/api/src/routes/project-listings/list.ts",
+            "apps/api/src/routes/project-listings/patch.ts",
+            "apps/api/src/middleware/tenant.ts",
+            "apps/api/src/services/tenant-context.ts",
+            "apps/api/src/services/waitlist-dashboard.ts",
+            "apps/api/src/lib/tenant-db.ts",
+            "apps/api/src/lib/ws-token.ts",
+            "apps-paid/workspace/**",
+        ],
+    },
+    // ── scheduling — full-stack module (provider + routes + booker pages) ────
+    //
+    // The #4416 scheduling seam, made installable. Three tiers into the
+    // marketing surface, no access model and no surface class of its own:
+    //
+    //   data          apps/api/src/services/scheduling/ — the provider client,
+    //                 the ONLY holder of the scheduling credential.
+    //   api           apps/api's own /v1/schedule/availability + /v1/schedule/book.
+    //   presentation  the `booker` section (packages/ui, no iframe) rendered by
+    //                 the `schedule` route surface, plus the module-owned
+    //                 confirmation page at /schedule/confirmed.
+    //
+    // The four forbidden patterns below are the module's whole security
+    // argument, restated as boundary rules rather than left in a comment: the
+    // credential belongs to apps/api and nowhere else, only the server tier
+    // addresses the provider, the provider's embed package is never imported at
+    // all, and no scheduling value is ever published to the browser as a
+    // `NEXT_PUBLIC_` variable.
+    //
+    // NOTE — a scaffolded site cannot run these yet. It receives
+    // `architecture.yaml` and a `package.json` whose `architecture` script names
+    // `tools/lint-architecture.ts`, but `build-templates.mjs` snapshots only
+    // `apps/` and `database/`, so `tools/` is absent. The rules are declarative
+    // there until the scaffold ships its linter; they ARE enforced in the AILK
+    // repo, whose own architecture.yaml carries the same four.
+    //
+    // The `api` block is a VERBATIM copy of multi-tenant's, deliberately. Two
+    // reasons: `deriveArchitecture` merges app blocks with `Object.assign`, so
+    // two slices declaring `api` differently would make the derivation depend on
+    // module order; and it is accurate — `apps/` is snapshotted whole, so a
+    // scheduling-bearing scaffold's `apps/api` really does contain the billing,
+    // checkout and email routes those imports are for.
+    scheduling: {
+        apps: {
+            api: {
+                path: "apps/api",
+                description: "Public HTTP API — routes + services (Fastify). Owns webhooks, checkout, email, server-side analytics.",
+                may_import_from: [
+                    "database",
+                    "packages/analytics",
+                    "packages/email",
+                    "packages/license",
+                    "packages/schema",
+                    "packages/site-config",
+                    "packages/stripe-client",
+                    "packages/validation",
+                ],
+                may_not_import_from: [
+                    "apps/mcp",
+                    "apps/web",
+                    "packages/theme",
+                    "packages/ui",
+                ],
+            },
+        },
+        packages: {
+            // Duplicated VERBATIM from the marketing slice for the same
+            // order-independence reason the multi-tenant slice states.
+            validation: {
+                description: "Zod schemas + shared types",
+                may_import_from: [],
+            },
+        },
+        forbiddenPatterns: [
+            {
+                pattern: CAL_KEY_PATTERN,
+                paths_excluded: ["apps/api/**"],
+                reason: "The scheduling credential belongs to apps/api. A file outside it has no reason to name the variable, let alone read it",
+            },
+            {
+                pattern: CAL_DOMAIN_PATTERN,
+                // The two server-side apps: apps/api holds the provider client, and
+                // apps/mcp's tools name booking links in their fixtures. Everything
+                // else — apps/web above all — is browser-reachable.
+                paths_excluded: ["apps/api/**", "apps/mcp/**"],
+                reason: "Only this site's server tier addresses the provider; every browser call goes to this site's own /v1/schedule/* routes instead",
+            },
+            {
+                pattern: CAL_EMBED_PACKAGE_PATTERN,
+                reason: "The provider's embed package is the iframe booker this module replaces — it hands the visitor to the provider's domain at the moment they convert",
+            },
+            {
+                pattern: PUBLIC_SCHEDULING_VAR_PATTERN,
+                reason: "A NEXT_PUBLIC_ variable is serialized into the page — no scheduling credential or provider config may ever be one",
+            },
+        ],
+        // ownedFiles (S1, #5088). Verified against the current filesystem,
+        // server.ts's module-conditional registration (isModuleEnabled('scheduling')),
+        // and a repo-wide grep of every importer of each candidate file.
+        //
+        // apps/api/src/services/scheduling/index.ts, cal-provider.ts, types.ts —
+        // the whole directory; grepped `services/scheduling` repo-wide and the
+        // ONLY importer outside its own __tests__/ is routes/schedule/index.ts,
+        // so no sibling error-type file exists elsewhere to add.
+        //
+        // packages/ui's Booker* components ARE listed individually (not a glob):
+        // every non-test, non-stories file whose name starts `Booker` under
+        // packages/ui/src/sections/ and packages/ui/src/blocks/. These live
+        // inside a package that marketing ALSO imports wholesale, but each of
+        // these particular files is scheduling-exclusive UI with no other
+        // consumer — unlike packages/validation below, a strip tool CAN delete
+        // exactly these files without touching anything another module needs.
+        //
+        // BOTH apps/web/app/[locale]/schedule pages are listed (#5182 Q9, disposed
+        // 2026-09-11). confirmed/page.tsx says outright in its own doc comment that
+        // "The module OWNS this page... a scaffold without the module has no such
+        // route", and its sibling page.tsx is the SOLE production constructor of a
+        // `booker` section: it builds the section literally in TypeScript
+        // (page.tsx:60, `type: "booker"`) rather than reading it from content, and
+        // its own header calls the route API-backed with "no content file that
+        // could disagree with the calendar". The create-ailk scaffolder already
+        // gates the whole `schedule` route surface (src/surfaces.ts), so the two
+        // pages arrive and depart together.
+        //
+        // packages/sections-registry/src/registry.ts (the `booker:` entry) and
+        // packages/validation/src/schemas/page-sections.ts (BookerSectionDataSchema,
+        // line ~2870) are investigated and EXCLUDED for the same reason as
+        // packages/validation below: each is one shared, multi-hundred-schema
+        // file serving every section type across every module, not a
+        // scheduling-owned file.
+        //
+        // packages/validation/src/schemas/scheduling.ts is the canonical home of
+        // listAvailabilityShape / createBookingShape / getEventMetaShape (its own
+        // doc comment names it as the shared vocabulary across apps/api, apps/mcp,
+        // packages/api-client, and packages/ui) — found via
+        // `grep -rl BookerSectionDataSchema\|listAvailabilityShape... packages/validation/src`.
+        // Per this card's explicit instruction it is NOT added to ownedFiles even
+        // though it is single-purpose: packages/validation is declared a shared
+        // kernel package (see this slice's own `packages.validation` entry above,
+        // "duplicated VERBATIM across slices for order-independence") and a strip
+        // tool must not delete a file another module also needs at runtime.
+        //
+        // packages/api-client/src/schedule.ts — found while reading
+        // list_availability.ts's imports; the MCP twins call apps/api through it.
+        // Treated the SAME as packages/validation/src/schemas/scheduling.ts and
+        // excluded for the same reason (packages/api-client is declared as
+        // shared HTTP-client infrastructure — see multi-tenant.packages["api-client"]
+        // above — not scheduling-owned), even though this file's content is
+        // scheduling-specific. This is a judgment call, not covered by this
+        // card's explicit checklist: flagged for reviewer confirmation.
+        //
+        // `packages/ui/src/sections/slices/scheduling.ts` (#5214) is the slice's own
+        // registration entry point: it statically imports Booker and registers it as
+        // the `booker` renderer, so it is the one file inside packages/ui that may
+        // reach a scheduling component — because it strips alongside them. The three
+        // files that path added on the OSS side — `SectionRenderer.tsx`,
+        // `slice-renderers.ts` and `ModuleAbsent.tsx` — are deliberately NOT listed
+        // here: they ship, and listing one would take the whole dispatch table with it.
+        ownedFiles: [
+            "apps/api/src/routes/schedule/index.ts",
+            "apps/api/src/services/scheduling/index.ts",
+            "apps/api/src/services/scheduling/cal-provider.ts",
+            "apps/api/src/services/scheduling/types.ts",
+            "apps/mcp/src/tools/list_availability.ts",
+            "apps/mcp/src/tools/get_event_meta.ts",
+            "apps/mcp/src/tools/create_booking.ts",
+            "packages/ui/src/sections/Booker.tsx",
+            "packages/ui/src/sections/BookerIsland.tsx",
+            "packages/ui/src/blocks/BookerPanel.tsx",
+            "packages/ui/src/blocks/BookerSlotGrid.tsx",
+            "packages/ui/src/blocks/BookerAttendeeFields.tsx",
+            "packages/ui/src/blocks/BookerEventHeader.tsx",
+            "packages/ui/src/blocks/BookerDateStrip.tsx",
+            "packages/ui/src/sections/slices/scheduling.ts",
+            "apps/web/app/[locale]/schedule/page.tsx",
+            "apps/web/app/[locale]/schedule/confirmed/page.tsx",
+        ],
+    },
+};
+/**
+ * Normalize a requested module list to the unique set, ordered by the canonical
+ * `RECOGNIZED_MODULES` sequence — so the derivation is a pure function of the
+ * SET, independent of input order (`['docs','marketing']` ≡ `['marketing','docs']`).
+ *
+ * @throws Error on an unrecognized module (a defensive backstop; `parse-args`
+ *   rejects unrecognized values upstream before they reach derivation).
+ */
+export function normalizeModules(modules) {
+    const requested = new Set(modules.map((m) => m.trim().toLowerCase()));
+    for (const m of requested) {
+        if (!RECOGNIZED_MODULES.includes(m)) {
+            throw new Error(`unknown module "${m}". Recognized: ${RECOGNIZED_MODULES.join(", ")}`);
+        }
+    }
+    return RECOGNIZED_MODULES.filter((m) => requested.has(m));
+}