create-ailk 0.7.0 → 0.9.0

package/README.md

@@ -7,7 +7,7 @@ canonical install path per [ADR 0007](../../docs/adr/0007-install-path-canonical
 ## Usage
 
 ```bash
-pnpm create ailk@latest my-site
+pnpm create ailk@latest my-site --shape organization-product
 cd my-site
 pnpm install
 pnpm dev
@@ -16,17 +16,46 @@ pnpm dev
 Compose the site from modules with `--modules`. The recognized vocabulary is
 `RECOGNIZED_MODULES` in `src/parse-args.ts` — `marketing`, `docs-blog`,
 `multi-tenant`, `workspace`, `scheduling`, `signal-collectors`, `commerce` —
-and the default when the flag is absent is `marketing` (`DEFAULT_MODULES`, same
-file):
+and `--modules` TRIMS or ADDS relative to the level your licence key unlocks
+(#6759), never replaces it: with no key the level is Free (`marketing`
+alone); a Pro key switches on `docs-blog`, `scheduling` and
+`signal-collectors` too; Pro Plus adds `multi-tenant`. Naming modules here
+keeps exactly those, trimming the level's default; naming only `commerce`
+(a per-site add-on) or `workspace` (included at Pro, opt-in) adds it on top
+of the level's default without trimming. The level is always DERIVED from
+what the module registry answers for your key — never read from a flag, a
+manifest or a key claim (`src/lib/module-tier.ts` `LEVEL_MODULES`,
+`src/lib/module-license-gate.ts` `deriveLevel`):
 
 ```bash
-pnpm create ailk@latest my-site --modules marketing,docs-blog
+pnpm create ailk@latest my-site --shape organization-product --modules marketing,docs-blog
 ```
 
 Every recognized module except `marketing` is a paid module, delivered under a
 license key rather than shipped inside this package — see
 [Paid modules require `AILK_LICENSE_KEY`](#paid-modules-require-ailk_license_key).
 
+### Shape, level and design
+
+Every scaffold also picks a shape and, optionally, a design. `--shape`'s
+vocabulary is `RECOGNIZED_SHAPES` in `src/parse-args.ts` — `organization-product`,
+`organization-service`, `local-business-service`, `person-service` (the README
+already lists `RECOGNIZED_MODULES` the same way); `local-business-product` is
+refused as not available yet. A terminal run with no `--shape` asks; a
+non-interactive one stops. The level comes only from your license key: no key
+is Free, and a key switches on its level's modules (`LEVEL_MODULES`) —
+`--modules` trims or adds relative to that set, as above. A keyed example:
+
+```bash
+pnpm create ailk@latest my-site --shape organization-service --license <key>
+```
+
+`--design minimalism` picks the other look and needs a Pro or Pro Plus key;
+`standard` (the default) needs none. `--template <alias>` scaffolds one of the
+four named aliases (`marketing-site-free`, `marketing-site`, `saas-product`,
+`minimalism-site`) — each fixes a shape, a design and its own module list — and
+cannot be combined with `--shape` or `--design`.
+
 ### Add a purchased module to an existing site
 
 A site scaffolded without a paid module (a Free site whose owner then buys
@@ -65,6 +94,45 @@ result of the roster check (`Page roster check: clean`). Running it again
 changes nothing and reports nothing to add.
 Run `pnpm install` afterwards.
 
+### Apply a design to an existing site
+
+A site that already exists can wear a different design with one command. Name
+a shipped design, or point at a directory holding a `DESIGN.md`:
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+create-ailk apply-design minimalism
+# a design package on disk, applied to a repo named explicitly
+create-ailk apply-design ./designs/acme --target ./my-site
+```
+
+It changes how the site **looks**, never what it **is**. It writes only:
+
+- the `theme:` block of `content/_site.mdx` — every other key, the `brand:`
+  block included, and the body stay byte-for-byte;
+- the generated `apps/web/lib/site-chrome.ts` — the design's layout, under any
+  knob the site's own template sets (so a template's announcement banner
+  stays on);
+- the look fields of sections the site's pages already place, from the
+  design's `sections:` presets;
+- the `design`, `layout` and `theme` record in `.ailk-site-manifest.json`.
+
+It never adds, removes or renames a route or page, never touches a content
+field, and leaves every page's structured data unchanged. It prints the files
+it changed; running it again changes nothing. A site whose roster is the older
+root `TEMPLATE-MANIFEST.json` gets the look but no record, and the report says
+so.
+
+A design other than `standard` needs a Pro or Pro Plus key. The key is read
+from the site's own `ailk.key` (put one there with
+`create-ailk license set <key>`), else from `AILK_LICENSE_KEY`. A malformed
+package, a preset the validator refuses or a missing key is refused before
+anything is written, naming the field or the licence level.
+
+A preset **sets** the look fields it names and never unsets one: a field it
+does not name keeps whatever value the page has, including one a previous
+design set.
+
 ### Sync `architecture.yaml` after adding a module
 
 `add-module` above regenerates `architecture.yaml` itself. To regenerate it by
@@ -85,6 +153,35 @@ 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.
 
+### Keep `CLAUDE.md` aligned with the template
+
+A scaffold's root `CLAUDE.md` is a run of AI Launch Kit sections, each between
+`<!-- ailk:template id="…" sha256="…" -->` and `<!-- /ailk:template id="…" -->`,
+followed by a **Site notes** section that starts at `<!-- ailk:site -->` and is
+the site owner's alone. Each begin marker records the SHA-256 of its section,
+so the scaffold's own check needs no network:
+
+```bash
+# in the scaffold — fails naming any template section edited by hand
+pnpm claude-md:check          # also runs inside `pnpm preflight` and CI
+```
+
+To pull a newer template's sections into an existing site:
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+pnpm create ailk@latest --sync-claude-md
+# or point at the repo explicitly
+pnpm create ailk@latest --sync-claude-md ./my-site
+```
+
+It rewrites only the template sections of `CLAUDE.md` and writes no other
+file; Site notes, and anything between sections (such as a pasted CloudParity
+block, which goes just above `<!-- ailk:site -->`), are kept byte for byte. A
+`CLAUDE.md` from before these markers is replaced only when it is an unedited
+published template; an edited one is refused with the steps to move your
+notes across.
+
 ### Sync template routes into an existing site
 
 The template is copied once, at scaffold time. When a later release adds a
@@ -183,16 +280,21 @@ a refused run leaves no partial scaffold behind.
 
 ```bash
 # free-only — no key read, no network call
-pnpm create ailk@latest my-site --modules marketing
+pnpm create ailk@latest my-site --shape organization-product --modules marketing
 
 # paid — the key is read from the environment
-AILK_LICENSE_KEY=... pnpm create ailk@latest my-site --modules marketing,docs-blog
+AILK_LICENSE_KEY=... pnpm create ailk@latest my-site --shape organization-product --modules marketing,docs-blog
 ```
 
-A request that names no paid module never reaches the key check at all:
-`resolvePaidModules` returns an empty map on its first branch, before touching
-`process.env` or the network, so a free-only `--modules` request reads no env
-var and makes no network call (`src/lib/module-license-gate.ts`).
+The network invariant (#6759 D6), in full:
+
+- **No key** → no request at all. A request that names no paid module never
+  reaches the key check either: `resolvePaidModules` returns an empty map on
+  its first branch, before touching `process.env` or the network.
+- **A key with no `--modules`** → the level probe (`deriveLevel`): 3-4
+  requests, to find out what the key unlocks.
+- **An explicit `--modules` list** → requests only for the paid modules it
+  names, exactly as before this level mechanism existed.
 
 ## What it does