create-ailk 0.30.0 → 0.31.0

package/README.md

@@ -558,7 +558,9 @@ On a site with an Admin (the `workspace` or `multi-tenant` module), the
 starter's pages are also rows in the site's workspace, so the Admin's Docs
 lists Home, About, Contact and every other roster page on first open.
 `seed-workspace` writes them there: each `content/en/<Type>/<slug>.mdx` page
-becomes one draft `text/page` Artifact.
+becomes one `text/page` Artifact, set Live when it has no Live version. A page
+already Live is never published over: a newer draft stays a draft for the
+owner to set Live in the Admin.
 
 ```bash
 AILK_AGENT_KEY=<agent key> create-ailk seed-workspace ./my-site --api-url <api origin> --workspace <wksp_id>
@@ -570,7 +572,9 @@ AILK_AGENT_KEY=<agent key> create-ailk seed-workspace ./my-site --api-url <api o
   and the origin's source, before any request.
 - The agent key is read from `AILK_AGENT_KEY` only — never a flag or a file —
   and never printed. An owner issues it in the Admin with the `content-edit`
-  grant.
+  and `content-publish` grants. After the first refused publish, the rest of
+  the pages are saved as drafts and fail `not published`; a re-run with a
+  granted key publishes them.
 - Each page prints `created`, `updated`, `unchanged`, `skipped` or `failed`,
   then a count line. A re-run creates nothing and reports every page
   `unchanged`. An agent writes ten times a minute, so a first seed of about
@@ -580,6 +584,15 @@ AILK_AGENT_KEY=<agent key> create-ailk seed-workspace ./my-site --api-url <api o
 - The API must run with `content-write` and a tenancy module (`workspace` or
   `multi-tenant`) in `AILK_ENABLED_MODULES`. Without them the content routes
   are not served and every page fails `404`.
+- When every page is in the workspace and Live, the site switches to the
+  database: `CONTENT_ADAPTER=database` is written to `apps/web/.env.local`
+  (which the web app reads) and to `apps/api/.env` (which the API that serves
+  the pages reads). Each app keeps a `CONTENT_ADAPTER` it already sets. A
+  skipped, refused or partial seed writes neither, and the site stays on
+  `content/` until a re-run succeeds.
+- The API then serves the pages only when it runs on the database it was
+  seeded through (its `DATABASE_URL`) and its site resolves to the seeded
+  workspace.
 - Exit 0 when every page was seeded, 1 when any failed, 2 on a refusal (no
   `.ailk-site-manifest.json`, a spoke, a missing key, workspace id or origin,
   the adapter not installed), which sends nothing.
@@ -610,6 +623,17 @@ scaffold time — a site with no `.ailk-site-manifest.json`, or a spoke — into
 a workspace: each `content/en/<Type>/<slug>.mdx` page, and each legacy
 `content/<Type>/<slug>.mdx` page, becomes one draft `text/page` Artifact.
 
+When the site has the docs-blog tree `apps/web/content`, its posts and docs
+are imported too (#10701): `apps/web/content/en/blog/<slug>.mdx` and
+`blog/<slug>/index.mdx` become `BlogPosting/<slug>`, the same under `docs`
+become `DocsDetail/<slug>`, and each directory's own `index.mdx` becomes its
+`BlogList/index` or `DocsList/index` — replacing a `content/` teaser of that
+type. Their fumadocs frontmatter is mapped to the stored fields (`date` →
+`publishedAt`, `updated` → `updatedAt`); keys the store does not keep from a
+caller (`featured`, `sidebar`, `tags`) are not sent, and `--apply` names them
+in one line per file. Each outcome carries `root: "content"` or
+`root: "editorial"`, and an editorial line is printed prefixed `editorial: `.
+
 ```bash
 AILK_AGENT_KEY=<agent key> create-ailk migrate-content ./my-site --api-url <api origin> --workspace <wksp_id>
 AILK_AGENT_KEY=<agent key> create-ailk migrate-content ./my-site --apply --api-url <api origin> --workspace <wksp_id>
@@ -669,6 +693,50 @@ diff -r before after && echo "live site unchanged"
 A non-empty diff is a finding: stop and report it before migrating another
 site.
 
+### Cutting a site over to the database
+
+Once a site's pages are in its workspace, three commands move it from its
+page files to the database and back (#10648). Each reads the workspace with
+`AILK_AGENT_KEY` (the `content-edit` grant), `--api-url`/`AILK_API_URL` and
+`--workspace`/`AILK_WORKSPACE_ID`, as `migrate-content` does; a spoke also
+needs `AILK_SPOKE_KEY`.
+
+```bash
+# 1. Freeze what the site serves today, and audit it. Commit both files.
+create-ailk inventory . --origin https://example.com
+#    → .ailk-cutover/inventory.json (written once; --refreeze crawls again)
+#    → .ailk-cutover/audit.json     (every run: per page, words in Markdown? published?)
+
+# 2. Plan the cutover, then run it against a preview reading the database.
+create-ailk cutover . --before https://example.com --after https://preview.example.com
+create-ailk cutover . --before https://example.com --after https://preview.example.com --apply
+
+# Rollback: every published page back to its file, published edits kept.
+create-ailk export-content .
+```
+
+`inventory` freezes every URL the sitemap, a crawl and the route roster name,
+with each page's prose status and images, and joins each page to its
+workspace page — by the inventory's operator-written `joins`, the roster,
+then `/blog` and the docs path. It exits 1 when any prose page is not
+published or its words are not in its Markdown.
+
+`cutover` runs import → publish → inventory → comparison → set env → deploy →
+verify → remove files, in that order, and stops at the first step that fails.
+The comparison renders every frozen page on both origins at 1440 and 390 wide
+and records a text, JSON-LD and screenshot verdict for each, then sweeps every
+frozen URL for a direct 200; it needs Playwright's Chromium in the site
+(`pnpm add -D @playwright/test && pnpm exec playwright install chromium`).
+Without `--apply` it sends only reads and writes and spawns nothing. The kit
+never publishes: the publish step names the pages to publish in Admin. Step 8
+stages the imported files' removal with `git rm`; you commit it. Each run's
+record and screenshots go to `.ailk-cutover/runs/` (gitignored).
+
+`export-content` writes each published page to the file `migrate-content`
+reads it from, with its words moved back into its sections, so a re-run of
+`migrate-content` reports every page `unchanged`. The full sequence, the
+evidence each step leaves and each step's rollback are in the cutover runbook.
+
 ### A spoke's declared environment
 
 A spoke scaffold's `pnpm preflight` and CI run `pnpm env:declared`: every
@@ -755,7 +823,7 @@ The network invariant (#6759 D6), in full:
 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. Derives and writes `architecture.yaml` (the site's code-boundary config) from the selected module set — see below.
-6. On a site with an Admin, seeds the starter's pages into its workspace when `--install` ran and `AILK_API_URL`, `AILK_WORKSPACE_ID` and `AILK_AGENT_KEY` are set, else prints why not and the `seed-workspace` command — see [Seeding the workspace](#seeding-the-workspace).
+6. On a site with an Admin, seeds the starter's pages into its workspace when `--install` ran and `AILK_API_URL`, `AILK_WORKSPACE_ID` and `AILK_AGENT_KEY` are set, sets each page Live and, when every page is Live, switches `apps/web` and `apps/api` to `CONTENT_ADAPTER=database`; else prints why not and the `seed-workspace` command that seeds and switches later — see [Seeding the workspace](#seeding-the-workspace).
 7. Prints next steps: `cd <dir> && pnpm install && pnpm dev`.
 
 ## `architecture.yaml` is derived from the module set