@aotter/mantle 0.0.11-alpha.28 → 0.0.11-alpha.30

package/docs/adr/0016-site-semantic-layer.md

@@ -1,24 +1,29 @@
-# ADR-0016: Site semantic layer — `AGENTS.md` + `mantle/site.md`
+# ADR-0016: Site semantic layer — `AGENTS.md` + launch state
 
 ## Status
 
-Accepted (slimmed 2026-05-12 per Epic #116; letter surface suspended 2026-06-19).
+Accepted (slimmed 2026-05-12 per Epic #116; `mantle/site.md` letter
+surface suspended 2026-06-19 and removed from first-run scaffolds).
 
 ## Decision
 
-Every agent-authored mantle project carries two files at fixed paths. They serve different audiences, change at different rates, and are filled by `create-mantle` from `_common/*.template` files.
+Every agent-authored mantle project carries a small cross-tool entry file
+and deterministic launch state at fixed paths:
 
 | File | Audience | Size budget | Format |
 |---|---|---|---|
 | `AGENTS.md` | Any cross-tool agent harness (Codex / Cursor / Aider / Amp / Factory / Claude Code) | ~30 lines | Plain markdown |
-| `mantle/site.md` | Mantle install / customize / deploy context | ~300 lines | Frontmatter + section bodies |
+| `.mantle/launch-state.json` | Install/provision context captured by landing or direct CLI flags | Small JSON record | JSON |
 
-`AGENTS.md` answers "what is this and how do I run it." `mantle/site.md` carries the site's semantic layer:
+`AGENTS.md` answers "what is this and how do I run it." Launch state
+carries install-critical facts such as archetype, brand, description,
+locales, selected features, GitHub owner/admin login, starter ref, and
+repo target.
 
-- Frontmatter: machine-readable (`archetype`, `brand`, `locales`, `site_url`, `revisions[]`, `futures[]`, `dont_touch[]`).
-- Body sections (`## site`, `## voice`, `## editor`, `## history`) each open with a `> purpose:` header so agents can route reads without parsing prose. Mantle reads the whole file on return, edits sections, writes the whole file back. **Atomic replace, not append.**
-
-The earlier `## welcome` 5-card letter surface is suspended. Provisioning must not block on prose completion in `mantle/site.md`; a first deploy should be possible from deterministic scaffold state.
+The earlier `mantle/site.md` semantic/letter surface and `## welcome`
+5-card letter surface are suspended for the first-run path. Provisioning
+must not block on prose completion; a first deploy should be possible
+from deterministic scaffold state.
 
 ## Placeholder macros
 
@@ -40,18 +45,21 @@ New macros must be added here, to `_common/*.template`, and to the substitution
 
 ## Update rules
 
-- **Mantle on return**: read whole `mantle/site.md`, edit relevant sections, write whole atomically, append one paragraph to `## history`.
-- **provision on deploy**: rewrite frontmatter `site_url:` placeholder → real Workers URL; append a `revisions:` entry. Same `Public site:` rewrite in `AGENTS.md`. Single commit at end of provision.
-- **No mid-section staged-and-running mutation.** A section is prose-replaced atomically, or a frontmatter scalar/list is replaced — never partial writes.
+- **Mantle on return**: read `AGENTS.md`, `.mantle/launch-state.json`,
+  and repo-local skills before changing code.
+- **provision on deploy**: rewrite `AGENTS.md` `Public site:`
+  placeholder → real Workers URL. Single commit at end of provision.
+- **No hidden letter gate.** Prose may be added later, but first deploy
+  only depends on deterministic scaffold state and provider configuration.
 
 ## Cross-tool compatibility
 
-`AGENTS.md` lives at repo root because that is where the AGENTS.md ecosystem (`agents.md`) looks. `mantle/` is a mantle-owned subdirectory; the naming is deliberately specific so a generic AGENTS.md reader does not interpret it as its own state.
+`AGENTS.md` lives at repo root because that is where the AGENTS.md ecosystem (`agents.md`) looks. `.mantle/` is for Mantle-owned non-secret state.
 
 ## Implementation
 
-- Templates: `mantle-starters/_common/AGENTS.md.template` and `mantle-starters/_common/mantle/site.md.template`.
+- Templates: `mantle-starters/_common/AGENTS.md.template`.
 - Substitution: `packages/create-mantle/src/placeholder.ts`.
 - Install handoff: `skills/install/SKILL.md` describes deterministic scaffold validation and the short post-substitution notes fill.
-- Provision update: `skills/provision/SKILL.md` describes the `site_url:` + `revisions:` write after deploy.
+- Provision update: `skills/provision/SKILL.md` describes the `AGENTS.md` public-site rewrite after deploy.
 - Theme overlay merge (Epic #116): `themes/<theme-key>/` overlay applies after the archetype starter and may touch `src/theme/` — never these two files.

package/docs/adr/README.md

@@ -16,7 +16,7 @@ Records of *why* mantle ended up shaped this way. The numbering preserves POC AD
 | [0012](0012-views-as-public-rest.md) | Views auto-expose `GET /api/views/<name>` as the public REST read surface. Schemas never get a public REST endpoint. Filter comparison values accept `{ $param: <name> }`; `?page=&show=` reserved for pagination. | Accepted (new) |
 | [0013](0013-agent-provisioned-consumer-projects.md) | Agent-provisioned consumer projects: website prompt → Skill → npm packages → starter setup → first-run provision/seed → owner/MCP handoff. | Accepted (new) |
 | [0014](0014-auth-better-auth-and-multi-tenant-mcp.md) | Better Auth for staff sign-in (D1 session); the MCP OAuth surface carves out to `@cloudflare/workers-oauth-provider` (KV grant store) at top level. The two meet at `/oauth/authorize` where the consent handler reads the Better Auth session. MCP splits into `/mcp/staff` (write, admin-role) and `/mcp` (read, any signed-in). Scope advertised as `["mcp"]` (single non-colon) because claude.ai rejects colon-shaped scopes. Auth port disappears; runtime takes Better Auth instance directly. See § "Amendment 2026-05-15". | Accepted + amended |
-| [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry, ~30 lines) + `mantle/site.md` (Mantle's frontmatter + section bodies, ~300 lines). Both ship as `{{PLACEHOLDER}}` templates filled by `create-mantle`; Mantle reads whole, edits sections, writes whole atomically. Slimmed 2026-05-12 per Epic #116. | Accepted (slimmed) |
+| [0016](0016-site-semantic-layer.md) | Site semantic layer: `AGENTS.md` (cross-tool entry) + `.mantle/launch-state.json` (deterministic install context). The older `mantle/site.md` letter surface is suspended from first-run scaffolds. | Accepted (slimmed) |
 
 ## Reading order
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.28",
+  "version": "0.0.11-alpha.30",
   "description": "Umbrella entry for @aotter/mantle. Adopters install this one package and import from subpaths: /spec, /runtime, /cloudflare, /admin-ui. Sub-packages remain individually installable on npm for tooling / alt-adapter authors. The Netlify adapter ships as a private workspace stub in v0.1 — its subpath will be added when the impl lands in v0.2.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
@@ -47,10 +47,10 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.28",
-    "@aotter/mantle-runtime": "0.0.11-alpha.28",
-    "@aotter/mantle-spec": "0.0.11-alpha.28",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.28"
+    "@aotter/mantle-admin-ui": "0.0.11-alpha.30",
+    "@aotter/mantle-cloudflare": "0.0.11-alpha.30",
+    "@aotter/mantle-runtime": "0.0.11-alpha.30",
+    "@aotter/mantle-spec": "0.0.11-alpha.30"
   },
   "peerDependencies": {
     "@cloudflare/workers-oauth-provider": "^0.7.0",

package/skills/install/SKILL.md

@@ -49,7 +49,6 @@ After `create-mantle` runs, the scaffold's ground truth lives in:
 | `src/.mantle/generated.*.ts` | Scaffolder-owned feature glue |
 | `.mantle/features.json` | Selected feature overlays |
 | `.mantle/launch-state.json` | Non-secret launch choices from landing |
-| `mantle/site.md` | Site semantic layer |
 | `AGENTS.md` | Cross-tool agent entry |
 
 ## Accepted Inputs
@@ -214,7 +213,7 @@ from the landing answers or the user's explicit request:
 - delete an unused manifest;
 - add one clearly requested field to an existing Schema;
 - correct site defaults in `src/mantleConfig.ts`;
-- fix a typo in `mantle/site.md` or `AGENTS.md`.
+- fix a typo in `AGENTS.md`.
 
 Run `pnpm validate` after every edit. Route larger feature work to
 `mantle:development` after production provision.
@@ -222,7 +221,7 @@ Run `pnpm validate` after every edit. Route larger feature work to
 ## Don't
 
 - Don't resurrect the manual interview / prompt-composition harness.
-- Don't block first deploy on polishing `mantle/site.md` prose.
+- Don't block first deploy on polishing prose or writing a site letter.
 - Don't ask for a Cloudflare API token in the base first-run path.
 - Don't commit provider secrets.
 - Don't use `127.0.0.1` in OAuth callback examples; use `localhost`

package/skills/provision/SKILL.md

@@ -38,8 +38,7 @@ expected result, and what value the user should report back.
   `ADMIN_GITHUB_LOGIN`, and the correct Worker name.
 - Worker secrets are set: `GITHUB_CLIENT_SECRET`,
   `BETTER_AUTH_SECRET`, and optional feature/provider secrets.
-- `mantle/site.md` frontmatter `site_url:` and `AGENTS.md` `Public
-  site:` point at the deployed Worker URL.
+- `AGENTS.md` `Public site:` points at the deployed Worker URL.
 - Staff MCP and browser admin sign-in are ready to test.
 - Operator setup URL is ready to hand to the owner:
   `https://mantle.tools/connect?site=<url-encoded-worker-url>`.
@@ -136,8 +135,8 @@ unset GITHUB_CLIENT_SECRET
 8. Commit and push generated non-secret outputs:
 
 ```bash
-git status --short -- wrangler.toml src/mantleConfig.ts mantle/site.md AGENTS.md
-git add wrangler.toml src/mantleConfig.ts mantle/site.md AGENTS.md
+git status --short -- wrangler.toml src/mantleConfig.ts AGENTS.md
+git add wrangler.toml src/mantleConfig.ts AGENTS.md
 git commit -m "mantle: wire production provision"
 git push
 ```
@@ -183,8 +182,8 @@ language:
 - What changed locally and what was committed.
 - Any intentionally deferred feature setup.
 
-Point future agents at `mantle/site.md`, `AGENTS.md`, and the repo-local
-`.agent/skills/` directory.
+Point future agents at `AGENTS.md`, `.mantle/launch-state.json`, and the
+repo-local `.agent/skills/` directory.
 
 ## Diagnostics