create-ailk 0.4.0 → 0.6.0

package/README.md

@@ -13,13 +13,20 @@ pnpm install
 pnpm dev
 ```
 
-Compose the site from modules with `--modules` (recognized: `marketing`, `docs`,
-`multi-tenant`; default `marketing`):
+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):
 
 ```bash
-pnpm create ailk@latest my-site --modules marketing,docs
+pnpm create ailk@latest my-site --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).
+
 ### Sync `architecture.yaml` after adding a module
 
 When a module is added to an already-scaffolded repo, regenerate its
@@ -28,9 +35,9 @@ modules are the same set as `--modules`):
 
 ```bash
 # in an already-scaffolded repo (default target: cwd)
-create-ailk --sync-architecture marketing,docs
+create-ailk --sync-architecture marketing,docs-blog
 # or point at the repo explicitly
-create-ailk --sync-architecture marketing,docs ./my-site
+create-ailk --sync-architecture marketing,docs-blog ./my-site
 ```
 
 Sync mode is **data-only and non-destructive**: it rewrites only
@@ -111,6 +118,43 @@ the route-surface registry in the same file.
 `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).
 
+## Paid modules require `AILK_LICENSE_KEY`
+
+`src/lib/module-tier.ts` splits a requested module set into its free and paid
+subsets. `FREE_MODULES` is the one hand-authored list — today `marketing`
+alone — and `PAID_MODULES` is **derived** from it as every other
+`RECOGNIZED_MODULES` entry, so the paid set is currently `docs-blog`,
+`multi-tenant`, `workspace`, `scheduling`, `signal-collectors` and `commerce`.
+A module added to the vocabulary is paid until someone deliberately adds it to
+`FREE_MODULES`.
+
+Paid modules are not published inside this npm package: their bundles are
+fetched at scaffold time. `resolvePaidModules` in
+`src/lib/module-license-gate.ts` reads `AILK_LICENSE_KEY` from the environment
+(or an injected `licenseKey` option) and refuses the run when it is unset or
+empty, naming the paid modules requested and pointing at
+`https://ailaunchkit.ai/pro`. An invalid or lapsed key is refused the same way,
+from the module distribution's own 401/403 (`src/lib/fetch-module.ts`). The
+gate runs before anything is copied (`scaffold()` in `src/programmatic.ts`), so
+a refused run leaves no partial scaffold behind.
+
+`AILK_MODULE_REGISTRY_URL` is optional: `fetchModule` uses an explicitly passed
+`registryUrl`, then that variable, then the built-in
+`DEFAULT_AILK_MODULE_REGISTRY_URL` (`src/lib/fetch-module.ts`).
+
+```bash
+# free-only — no key read, no network call
+pnpm create ailk@latest my-site --modules marketing
+
+# paid — the key is read from the environment
+AILK_LICENSE_KEY=... pnpm create ailk@latest my-site --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`).
+
 ## What it does
 
 1. Validates the target directory does not exist OR is empty.
@@ -139,15 +183,18 @@ single source of truth for the site's code-architecture boundaries:
 **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.
+exported for that re-derivation. `MODULE_SLICES` in `src/module-architecture.ts`
+declares a slice for every recognized module.
 
 ## Templates are snapshotted at build time
 
 The `prepublishOnly` script (`scripts/build-templates.mjs`) reads the canonical
 sources from this monorepo (`apps/`, `database/`, `content/`, root config) and
 populates `templates/`. The npm tarball ships the populated templates via the
-`files` field. No network access is performed at scaffold time; only `pnpm install` (run by the user after scaffolding) hits the npm registry.
+`files` field. A free-only scaffold performs no network access at scaffold
+time; only `pnpm install` (run by the user after scaffolding) hits the npm
+registry. A run naming a paid module fetches that module's bundle — see
+[Paid modules require `AILK_LICENSE_KEY`](#paid-modules-require-ailk_license_key).
 
 ## Repository