create-ailk 0.30.0 → 0.32.0

package/README.md

@@ -393,6 +393,15 @@ merge-file` against the recorded version's own copy as the base. A clean
   **Added**, unless it sits under a route or directory the site deliberately
   does not carry (a gated-off surface, a spoke exclusion, or a directory you
   deleted entirely) — those are left alone.
+- A surface no module owns (such as `projects`) that a page row of the
+  site's `.ailk-site-manifest.json` names, but `architecture.yaml` does not
+  declare, is in scope for adding: its route files are **Added** and
+  recorded, and `architecture.yaml` is regenerated to declare it. Reported
+  as **Surfaces declared from the roster**.
+- A code-route row (`kind: "route"`) of `.ailk-site-manifest.json` that no
+  page file under `apps/web/app/[locale]/` serves (a spoke's `/sign-in`) is
+  dropped from the roster after the writes, every other byte of the file
+  kept. Reported as **Roster rows dropped, no route serves them**.
 
 A file outside the gated-off surfaces and spoke exclusions the site's scope
 no longer covers is **Skipped**, as is one that exists on disk but was never
@@ -425,7 +434,8 @@ never a shell. Fetching an old template version (when it is not the running
 package's own) reads the public npm registry at
 `https://registry.npmjs.org`, overridable with `AILK_NPM_REGISTRY_URL` for a
 mirror. `update` never touches content, except to give an mdx-body page
-with no `# ` heading its title and description (below), nor env files,
+with no `# ` heading its title and description and to escape a bare `{` on
+an mdx-body page (both below), nor env files,
 `.claude/`, lockfiles or any `package.json` — those stay `add-module`'s and
 the consumer version bump's job. Commit before running `update`, and review the diff after: a
 clean merge is still worth reading.
@@ -444,6 +454,27 @@ folded `>` block, say), is listed under **Needs review** for you to fix.
 Which pages are mdx-body is read from your own `apps/web/app` routes, and the
 step runs again harmlessly on every update.
 
+**Placeholder braces (#10773).** MDX reads a `{` in a page body as
+JavaScript, so on an mdx-body page a bare placeholder such as
+`{First engagement}` fails the page with a 500, and one that parses
+(`{Tagline}`) renders as nothing. After the heading step, `update` writes a
+`\` before every bare `{` on each mdx-body page — never in frontmatter, fenced
+or inline code, a JSX tag or a `{/* … */}` comment — and keeps the page's
+change only when your site's own MDX parser (the `@mdx-js/mdx` its
+`next-mdx-remote` uses) then reads the page with no expression left but
+comments. Each such page is listed under **Placeholder brace escaped**; one
+byte per brace changes and nothing else. A page it cannot escape safely (a
+mangled `{/ … /}` comment, or another MDX error the escape does not reach)
+is left alone and listed under **Needs review** with the line, and so is
+every page with a bare brace while the site's dependencies are not installed
+(run `pnpm install`, then `update` again). A fresh scaffold also runs
+`pnpm mdx-body:check` in `preflight` and CI, which names each bare brace by
+file, line and column before a deploy. A site scaffolded before it gains the
+check by copying `tools/check-mdx-body.ts`, `tools/mdx-braces.ts` and
+`tools/body-heading.ts` from a fresh scaffold and adding
+`"mdx-body:check": "tsx tools/check-mdx-body.ts"` to its `package.json`
+scripts and `preflight`.
+
 ### Adopting an existing site
 
 A site that create-ailk did not scaffold, or that was scaffolded before
@@ -558,7 +589,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 +603,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 +615,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 +654,22 @@ 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>`, or one series down,
+`blog/<series>/<post>.mdx` (or `<post>/index.mdx`), as a `BlogPosting/<post>`
+whose `parent` is the series (#10775) — served at `/blog/<series>/<post>`, the
+URL its file serves at; 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. A blog post's
+`parent` comes from its path, never its frontmatter, and a file the walk skips
+is listed with the rule it failed. 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 +729,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 +859,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