create-ailk 0.1.0 → 0.2.0

package/README.md

@@ -13,13 +13,134 @@ pnpm install
 pnpm dev
 ```
 
+Compose the site from modules with `--modules` (recognized: `marketing`, `docs`,
+`multi-tenant`; default `marketing`):
+
+```bash
+pnpm create ailk@latest my-site --modules marketing,docs
+```
+
+### Sync `architecture.yaml` after adding a module
+
+When a module is added to an already-scaffolded repo, regenerate its
+`architecture.yaml` in place with `--sync-architecture <csv>` (recognized
+modules are the same set as `--modules`):
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+create-ailk --sync-architecture marketing,docs
+# or point at the repo explicitly
+create-ailk --sync-architecture marketing,docs ./my-site
+```
+
+Sync mode is **data-only and non-destructive**: it rewrites only
+`architecture.yaml` from the module set, re-copies no template tree, and runs
+no install. Because `deriveArchitecture` is byte-deterministic, the synced file
+is identical to a fresh scaffold's for the same module set — the idempotency
+the deferred-sync signal contract depends on.
+
+### Sync template routes into an existing site
+
+The template is copied once, at scaffold time. When a later release adds a
+route directory (0.14.0 added `/thanks/{slug}` and the flow results page, for
+example), a site scaffolded earlier does not pick it up on its own.
+`sync-routes` reports the route directories a site is missing and, with
+`--apply`, copies exactly those in:
+
+```bash
+# check — exit 1 if any template route is missing, 0 otherwise (default target: cwd)
+create-ailk sync-routes ./my-site
+# copy the missing route directories in
+create-ailk sync-routes ./my-site --apply
+```
+
+Check mode lists each missing route with the surface that owns it and the
+release it was added in (`thanks/[slug]  (surface: core, added in 0.14.0)`).
+It also lists routes **modified locally** — a route directory the site has,
+whose files differ from what the template would write (an edited, added, or
+deleted file). Modified routes are your edits: they are reported and left
+as-is, they never fail the check, and `--apply` never overwrites them.
+
+`--apply` only creates route directories that are absent, through the same
+copier a fresh scaffold uses (so the copied files are byte-identical to a fresh
+scaffold's). It never rewrites or deletes an existing file, never writes
+outside `apps/web/app/[locale]/`, runs no install, and a second run is a
+no-op. `--apply` exits 0 on success.
+
+**Scope.** Every core route (`about`, `contact`, `faq`, `thanks/[slug]`,
+`sign-in`) is always checked, and so is the `(authed)` route GROUP —
+`layout.tsx` + `sign-in-gate.tsx`, `account/`, and `waitlist/` — even though
+it is not itself a `--modules`-gated surface (#5014): a fresh scaffold ships
+it unconditionally, the same as core, so `sync-routes` checks it
+unconditionally too. It is reported under its own `authed` identity rather
+than lumped in with `core`, so `sync-routes`'s output distinguishes "always
+present, and this is the sign-in/account shell" from "always present, and
+this is the marketing core." A gateable surface's routes (`blog`, `docs`,
+`flows`, …) are checked only when the site carries that surface; a surface
+gated off at scaffold time is listed as skipped, not missing — its absence is
+deliberate, not drift. Add a surface with `--sync-architecture` and the
+`scaffold-page` skill, not with `sync-routes`.
+
+**The lib-and-messages dependency contract (#5014).** Some routes import
+files OUTSIDE their own route directory — `sign-in/page.tsx` imports
+`apps/web/lib/auth-env.ts` and `lib/site-brand.tsx`; the `(authed)` group's
+`layout.tsx` imports `apps/web/auth.ts`; `(authed)/account/page.tsx` imports
+`lib/account-config.ts`, `lib/server-api.ts`, and two files from its
+`(authed)/waitlist` sibling (`components/ForbiddenState.tsx`, `format.ts`).
+Copying a route's directory alone would leave those imports dangling in an
+older consumer that never had them. `ROUTE_DEPENDENCIES` in `src/surfaces.ts`
+declares them per route; `sync-routes` copies each one `--apply` finds
+missing (never overwriting — the same rule routes themselves follow) and
+reports it in check mode under an `Also required` heading. `ROUTE_MESSAGE_NAMESPACES`
+does the same for the i18n namespaces a route's copy needs
+(`signIn`, `account`, `waitlistDashboard.gate`) — but CHECK-ONLY: a
+consumer's `apps/web/messages/<locale>.json` already exists and may carry
+hand-authored translations, so `sync-routes` reports a missing namespace
+rather than attempting to merge JSON keys into it. Adding it is a manual
+step, same as reading any other reported gap.
+
+**The manifest.** `ROUTE_SINCE` in `src/surfaces.ts` maps every template route
+directory (relative to `apps/web/app/[locale]`) to the `@working-theory/*`
+fixed-group release line that first shipped it — the version a site pins, so
+the report can say "added in 0.14.0". `create-ailk`'s own version is not the
+axis. `0.0.0` means the route predates the manifest and its first release is
+not recoverable. Surface membership is not in the manifest: it is derived from
+the route-surface registry in the same file.
+
+**Maintainer rule:** adding a route directory to the template MUST add a
+`ROUTE_SINCE` entry — `__tests__/sync-routes.test.ts` fails otherwise (and it
+fails on a stale entry for a route the template no longer ships).
+
 ## What it does
 
 1. Validates the target directory does not exist OR is empty.
 2. Copies the curated template tree (`apps/{web,api,mcp}` + `database/` + `content/` + root config files) from the package's `templates/` directory.
 3. Substitutes `workspace:*` references in every `package.json` with the matching `@working-theory/*` semver from npm — versions are pinned at npm-publish time.
 4. Substitutes `{{PROJECT_NAME}}`, `{{COMPANY_NAME}}`, `{{COMPANY_DOMAIN}}` markers in `templates/README.md` from the target directory name (and CLI flags / interactive prompts in future versions).
-5. Prints next steps: `cd <dir> && pnpm install && pnpm dev`.
+5. Derives and writes `architecture.yaml` (the site's code-boundary config) from the selected module set — see below.
+6. Prints next steps: `cd <dir> && pnpm install && pnpm dev`.
+
+## `architecture.yaml` is derived from the module set
+
+The scaffolded site's `architecture.yaml` (the apps/packages/namespaces the
+architecture linter walks + the import rules it enforces) is **derived from the
+selected `--modules`**, not copied from a fixed template. The module set is the
+single source of truth for the site's code-architecture boundaries:
+
+- A **module → architecture-slice registry** (`src/module-architecture.ts`) maps
+  each recognized module to the boundary fragment it contributes.
+- **`deriveArchitecture(modules)`** (`src/derive-architecture.ts`, also exported
+  from the package index) composes a module-independent base with the selected
+  slices into one deterministic document. Same module set → byte-identical
+  output.
+- The scaffolder writes the derived file at the target root, satisfying the
+  scaffolded `project.yaml`'s `architecture_rules: architecture.yaml` reference.
+
+**Sync on module-add** is the same derivation re-run over the current module set
+— idempotent (re-deriving an unchanged set is a no-op), so adding a module later
+and re-deriving updates `architecture.yaml` to match. `deriveArchitecture` is
+exported for that re-derivation. `marketing` is validated end-to-end; the `docs`
+and `multi-tenant` slices are registry-defined ahead of their template trees.
 
 ## Templates are snapshotted at build time
 
@@ -30,9 +151,9 @@ populates `templates/`. The npm tarball ships the populated templates via the
 
 ## Repository
 
-Source: https://github.com/tailwind-ai/ai-launch-kit
+Source: https://github.com/working-theory-labs/ai-launch-kit
 
-Issues: https://github.com/tailwind-ai/ai-launch-kit/issues
+Issues: https://github.com/working-theory-labs/ai-launch-kit/issues
 
 ## License