create-ailk 0.6.1 → 0.8.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,22 +16,90 @@ 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
+Pro, say) gets it with `add-module` — alias `upgrade` — run against the site
+itself, with `AILK_LICENSE_KEY` covering the module:
+
+```bash
+# in an already-scaffolded repo (default target: cwd)
+AILK_LICENSE_KEY=<key> create-ailk add-module docs-blog
+# or point at the repo explicitly
+AILK_LICENSE_KEY=<key> create-ailk upgrade docs-blog ./my-site
+```
+
+It fetches the module's bundle through the same licence gate a scaffold uses
+(no key, or a key that does not cover the module, is refused with the same
+message, before anything is written) and merges it **without overwriting
+anything the site has**:
+
+- a file the site lacks is written;
+- a file the site already has is left as-is — if its content differs from the
+  module's, the report lists it under _Needs manual review_ with the exact
+  change the module wanted, for you to apply by hand;
+- the only edits to existing files are the module's config patches, and only
+  to `package.json` dependency and script keys, `next.config.*` and
+  `jest.config.*` — each reported with its diff.
+
+It then copies in the module's route directories, together with any other
+template route the site is missing (the same set `sync-routes --apply` copies,
+so a core route you deleted comes back and is listed in the report), regenerates `architecture.yaml`
+for the site's modules plus this one, and regenerates the site nav unless you
+have edited it. On a site scaffolded from a template, it also appends the
+module's pages to the site's roster (`TEMPLATE-MANIFEST.json`) — replacing a
+template placeholder page the module takes over, such as the Free `/blog`
+teaser, whose seed is removed only if you have not edited it — and prints the
+result of the roster check (`Page roster check: clean`). Running it again
+changes nothing and reports nothing to add.
+Run `pnpm install` afterwards.
+
 ### 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`):
+`add-module` above regenerates `architecture.yaml` itself. To regenerate it by
+hand for a module set — after changing modules some other way — use
+`--sync-architecture <csv>` (recognized modules are the same set as
+`--modules`):
 
 ```bash
 # in an already-scaffolded repo (default target: cwd)
@@ -86,7 +154,7 @@ 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`.
+`add-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
@@ -144,16 +212,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