@aotter/mantle 0.0.11-alpha.73 → 0.1.0-alpha.2

package/docs/performance-harness.md

@@ -13,8 +13,8 @@ make a normal content/API/page change.
 | Manifest View execution | `ExecuteViewUseCase` + `ViewSqlCompiler` | The deliberate compiled-query exception; it still resolves declared Schema indexes. |
 | Editable settings and code-owned locale/media policy | `DatabaseSiteConfigRepository` | Editable values and dynamic media tool policy are read fresh; boot-seeded locale policy may be memoized within the runtime instance. |
 | Pending media uploads | `DatabasePendingUploadRepository` | Canonical, read-after-write D1 state; never publish-cache state. |
-| Rendered HTML, Markdown, and `llms.txt` | `HtmlPublishOrchestrator` plus the Cloudflare public-route cache policy | Reproducible derivatives live in KV. Settings updates invalidate through a runtime use case. |
-| D1/KV transport and optional query metrics | Cloudflare bindings | Bindings stay thin. Query/cache policy does not belong in a generic provider `BaseRepository`. |
+| Rendered HTML, Markdown, and `llms.txt` | Request-time render use cases plus the Cloudflare public-route cache policy | D1 is canonical; version-local Workers Cache stores anonymous HTTP responses. |
+| D1 transport and optional query metrics | Cloudflare bindings | Bindings stay thin. Query/cache policy does not belong in a generic provider `BaseRepository`. |
 
 `CmsRuntime.db` remains deprecated compatibility surface. New site code uses
 Manifests, runtime use cases, `entryReader`, and `siteConfig`. A site may own
@@ -24,16 +24,14 @@ must not query Mantle-owned tables through `runtime.db`.
 ## Cache contract
 
 - D1 is canonical for entries, site settings, media metadata, and pending
-  uploads. KV contains only reproducible public artifacts.
-- A public KV hit checks the cache before loading full editable site settings.
-  Locale policy is the small boot-seeded exception. A warm entry/page artifact
-  therefore performs zero D1 queries.
-- A safe cache miss renders from canonical state and schedules KV write-back
-  with the request execution context. It waits inline only when no execution
-  context exists, such as a direct unit call.
-- Site-setting writes call the runtime settings use case, which completes
-  public-artifact invalidation before reporting success. HTTP routes do not
-  scan/delete KV prefixes themselves.
+  uploads. Core stores no rendered artifact copies.
+- Public routes render canonical state and return
+  `Cache-Control: public, max-age=0, s-maxage=300`.
+- Cloudflare Workers Cache checks eligible anonymous responses before invoking
+  the Worker. Cache keys are version-local, so a deploy starts with no stale
+  response from the previous Worker version.
+- Site-setting and content writes only persist canonical state. They do not
+  wait for render work or scan/delete cache prefixes.
 - Do not cache every repository read. Cross-isolate correctness for editable
   data wins unless a read has a measured hot-path contract and explicit
   invalidation.
@@ -76,11 +74,12 @@ Timing always reports p50/p95/max. A test-only Worker wrapper may also return
 `x-mantle-query-count` and `x-mantle-rows-read`; those become distributions in
 the same report. Do not expose these diagnostic headers in production.
 
-Core CI runs `pnpm bench:wrangler` against real Wrangler-local D1, KV, Worker
-HTTP routing, View execution, and live page rendering. It compares 100 and
-10,000 row fixtures, then samples page MISS and HIT separately. CI gates
-row-read scaling, endpoint query budgets, and zero-D1 warm hits, not absolute
-milliseconds.
+Core CI runs `pnpm bench:wrangler` against real Wrangler-local D1, Worker HTTP
+routing, View execution, and origin page rendering. It compares 100 and 10,000
+row fixtures and gates row-read scaling plus endpoint query budgets, not
+absolute milliseconds. Wrangler-local does not emulate the new entrypoint
+Workers Cache, so cache hits are a deployment-level smoke check rather than a
+fabricated local metric.
 
 ## Seven findings: measured disposition
 
@@ -89,12 +88,12 @@ diagnostic, while query/row counts are the stable assertions.
 
 | Finding | Disposition |
 |---|---|
-| Public KV hits read D1 first | Fixed. A 10,000-row warm page measured 0 queries / 0 rows read. |
+| Public cache hits read D1 first | Removed from Worker code. Cloudflare's entrypoint Workers Cache runs before the Worker; Core has no inner render cache. |
 | Slug/locale reads bypass generated indexes | Fixed by the shared schema-aware entry-read boundary. A 10,000-row page MISS measured 2 queries / 5 rows read. |
 | OFFSET pagination | Accepted for the v0.1 bounded-result surfaces: every response is capped at 500 rows and public hot paths must stay shallow. Deep/export workloads require a purpose-shaped cursor API before they are declared hot. |
 | Admin substring search scans | Accepted only for the authenticated Admin collection browser, with a 500-row response cap. Large/search-heavy sites should add a purpose-shaped indexed View or dedicated search service; do not expose this scan publicly. |
 | Published list/sitemap/llms paths lack system indexes | Fixed with measured partial indexes for published global, locale, collection, and collection+locale ordering. The 100-row and 10,000-row API runs both measured 1 query / 20 rows read. |
-| Page MISS waits for KV write-back | Fixed. Reproducible artifacts write through `waitUntil`; regression coverage proves response completion does not await KV. |
+| Page MISS waits for cache write-back | Removed. Origin rendering returns directly; Workers Cache owns response storage outside the Worker. |
 | Benchmark stops at fake in-process dispatch | Fixed by the Node planner and Wrangler-local Worker/API/page layers. The old dispatch microbenchmark remains a narrow CPU signal only. |
 
 The retained OFFSET and substring-search trade-offs are visible exceptions,

package/docs/release-process.md

@@ -48,20 +48,23 @@ decision instead of starting another local redesign loop.
 ## Branches and channels
 
 - Feature and release PRs target `develop`.
-- Pre-v0.1 alphas release directly from the merged `develop` release commit.
+- Alpha prereleases before stable v0.1.0 release directly from the merged
+  `develop` release commit.
 - Beta, RC, and stable promotion to `main` remains a deliberate human decision;
   it is not part of the alpha controller.
 - Alpha, beta, and RC GitHub releases are prereleases.
 - npm dist-tags follow the suffix: `alpha`, `beta`, `rc`, or `latest` for
   stable versions.
-- During the current `0.0.x-alpha` cadence, `latest` follows the current alpha
-  while the `alpha` tag remains available.
+- During the legacy `0.0.x-alpha` cadence, `latest` follows the current alpha.
+  The final `0.1.0-alpha.N` candidates advance only `alpha`; `latest` moves to
+  `0.1.0` after the stable gate passes.
 
 ## Release PR
 
 1. Fetch Core and Starter remotes and choose the next unused version.
-2. Read `CHANGELOG.md` completely. Add a dated Keep-a-Changelog entry from the
-   merged commits since the previous tag; do not add an `[Unreleased]` bucket.
+2. Preview GitHub's generated notes for the merged commits since the previous
+   tag. Correct PR titles and labels before release; do not duplicate the notes
+   in `CHANGELOG.md`. Label the release-only PR `skip-release-notes`.
 3. Set that exact version in every workspace package and in all four agent
    plugin manifests. Set `.agents/plugins/marketplace.json` to the immutable
    `v<version>` ref.
@@ -75,6 +78,16 @@ decision instead of starting another local redesign loop.
    packed-consumer gate. Review and merge a same-repository PR into `develop`;
    the controller rejects a direct-push release commit.
 
+Preview the native notes before merging the release PR:
+
+```bash
+gh api --method POST repos/aotter/mantle/releases/generate-notes \
+  -f tag_name=vX.Y.Z \
+  -f target_commitish="$(git rev-parse origin/develop)" \
+  -f previous_tag_name=vPREVIOUS \
+  --jq .body
+```
+
 The five public packages publish in dependency order:
 
 1. `@aotter/mantle-spec`
@@ -177,7 +190,7 @@ deployment was started.
 ## Fix-forward policy
 
 - Broken public package or Starter bundle: publish the next alpha and explain
-  the re-spin in `CHANGELOG.md`.
+  the re-spin in the fix PR and generated GitHub Release notes.
 - Use `npm deprecate` to steer consumers away from a broken version.
 - Unpublish only for secrets, private files, or similarly severe exposure;
   npm versions cannot be reused and registry metadata may remain unavailable

package/docs/schema-indexes.md

@@ -11,7 +11,7 @@ kind: Schema
 metadata: { name: account-members }
 spec:
   title: Account members
-  lifecycle: none
+  lifecycle: operational
   schema:
     type: object
     properties:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aotter/mantle",
-  "version": "0.0.11-alpha.73",
-  "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.",
+  "version": "0.1.0-alpha.2",
+  "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 and adapter authors.",
   "license": "Apache-2.0",
   "homepage": "https://mantle.tools/",
   "repository": {
@@ -55,24 +55,24 @@
     "README.md"
   ],
   "dependencies": {
-    "@aotter/mantle-admin-ui": "0.0.11-alpha.73",
-    "@aotter/mantle-cloudflare": "0.0.11-alpha.73",
-    "@aotter/mantle-runtime": "0.0.11-alpha.73",
-    "@aotter/mantle-spec": "0.0.11-alpha.73"
+    "@aotter/mantle-cloudflare": "0.1.0-alpha.2",
+    "@aotter/mantle-admin-ui": "0.1.0-alpha.2",
+    "@aotter/mantle-runtime": "0.1.0-alpha.2",
+    "@aotter/mantle-spec": "0.1.0-alpha.2"
   },
   "peerDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.0",
+    "@cloudflare/workers-oauth-provider": "^0.8.2",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.23",
+    "better-auth": "^1.6.27",
     "hono": "^4.12.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {
-    "@cloudflare/workers-oauth-provider": "^0.8.0",
+    "@cloudflare/workers-oauth-provider": "^0.8.2",
     "@types/node": "^26",
     "aws4fetch": "^1.0.20",
-    "better-auth": "^1.6.23",
-    "hono": "^4.12.30",
+    "better-auth": "^1.6.27",
+    "hono": "^4.12.34",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.2"

package/skills/develop/SKILL.md

@@ -16,7 +16,7 @@ docs govern runtime/API behavior.
 ## First Read
 
 1. `package.json` for the installed `@aotter/mantle*` versions.
-2. `manifests/`, the active adapter config, and `src/auth.ts` when present. If the project is older, check `src/mantleConfig.ts`.
+2. `manifests/site.yaml`, the active adapter config, and `src/auth.ts` when present. If the project is older, check `src/mantleConfig.ts`.
 3. The active `.mantle/overlays/<type>/seed.json`, when present; generated
    homepages commonly import visible copy and form structure from it.
 4. Optional local context: `.mantle/launch-state.json`, `.mantle/handoff.md`,
@@ -82,9 +82,12 @@ the atoms cannot express the behavior.
   `Procedure.spec.input` before the seed/form. Keep public mutation inputs
   `additionalProperties: false`; otherwise JSON Schema's default may strip an
   undeclared field while returning success.
-- Use `lifecycle: none` for submissions, inquiries, orders, and other
+- Use `lifecycle: operational` for submissions, inquiries, orders, and other
   Procedure-created operational records that staff inspect or correct. Reserve
-  `simple` for content a person stages and publishes.
+  `publishing` for content a person stages and publishes.
+- Lifecycle `before_update` / `after_update` hooks also fire for unpublish,
+  archive, and every other status transition whose target is not `published`;
+  do not use them for edit-only work.
 - When a form's fixed option values change, update the stored Schema and public
   Procedure input `enum` together. Keep translated labels in the page seed;
   Admin and Staff MCP derive their typed controls from the manifest values.
@@ -98,18 +101,23 @@ the atoms cannot express the behavior.
 
 - `data.locale` is reserved for `localized: true` Schemas. A non-localized
   Schema must use a domain field such as `replyLocale`.
+- Use a standalone localized Schema only for independent locale rows. For
+  versions of one entity, use a non-localized parent plus a localized child
+  with `translates: { parent, on }`. The child must own at least one field
+  besides `locale` and the join field.
 - Parallel locale blocks must keep field names, option values, step IDs, and
   result keys identical; translate display strings only.
-- `siteDefaults.locales` is code-owned and boot-synced. Brand, title,
-  description, and origin are seeded once, then changed through site settings.
+- `siteDefaults.origin` and `siteDefaults.locales` are code-owned and
+  boot-synced. Brand, title, and description seed once, then change through
+  site settings.
 - When changing an existing collection from `[slug]` to `[slug, locale]`,
   boot with a Mantle version that reconciles obsolete unique indexes and test
   the same slug in two locales. Do not patch D1 manually.
 
 ## Adapter Boundary
 
-The runtime is adapter-neutral. Required runtime ports are `DatabaseDriver`,
-`KvCache`, and `AssetServer`. Optional feature ports, such as `MediaStorage`
+The runtime is adapter-neutral. Required runtime ports are `DatabaseDriver`
+and `AssetServer`. Optional feature ports, such as `MediaStorage`
 or `DeferredHookDispatcher`, are enabled only when the current adapter wires
 them.
 
@@ -203,7 +211,8 @@ cache.
 
 ## Rules
 
-- Prefer manifest YAML for content model changes.
+- Put all content model changes in `manifests/site.yaml`; other manifest
+  filenames are rejected.
 - Use a generated overlay `seed.json` for the auth-free local first page when
   it is already imported by `src/web/content/*`.
 - Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.

package/skills/plugin/SKILL.md

@@ -49,7 +49,7 @@ stop and ask for the recipe instead of guessing.
 ## First Read
 
 1. `package.json` for Mantle version and adapter package.
-2. `manifests/` for current atom names and route/tool collisions.
+2. `manifests/site.yaml` for current atom names and route/tool collisions.
 3. `src/mantle/config.ts` and `src/mantle/handlers/` for registered handlers, templates, and optional ports. Older projects may use `src/mantleConfig.ts`.
 4. `.mantle/plugins.json` and `.mantle/plugins.lock.json` if present.
 5. `.mantle/launch-state.json` only as context, not as plugin authority.

package/skills/provision/SKILL.md

@@ -50,6 +50,10 @@ Capture the live URL in `PUBLIC_ORIGIN` and `Public site:` in `AGENTS.md`, then
 commit and push non-secret changes. Reuse any repo or Worker already created
 by landing. Workers Builds is optional after a direct deploy.
 
+When the owner later adopts a custom domain, update `PUBLIC_ORIGIN` and the
+provider's OAuth callback together, then redeploy. Do not patch `site_config`
+directly; boot syncs its canonical origin from `PUBLIC_ORIGIN`.
+
 ## Choose Auth
 
 - **Self-hosted — free:** configure the owner's per-site GitHub OAuth App and

package/skills/theme/SKILL.md

@@ -18,7 +18,7 @@ tokens, or recipes, but the skill contract is Core-owned.
 2. `styles/`, `components/`, `src/web/`, `src/theme*`, and UI-library config
    if present.
 3. A vendored UI palette's manifest and license, if present.
-4. `manifests/` to understand which content shape drives the public UI.
+4. `manifests/site.yaml` to understand which content shape drives the public UI.
 
 ## Ownership