@aotter/mantle 0.1.0-alpha.1 → 0.1.0-alpha.2

package/docs/design-atoms.md

@@ -3,14 +3,7 @@
 > If you're an AI working in a project that consumes `@aotter/mantle-*`,
 > read this first. It explains the entire surface area in one page.
 >
-> **Status**: v0.1 grammar lock. Atoms are shipped; rich sub-spec
-> grammar (policies, recursive views, temporal predicates, quotas,
-> projection triggers, cron/queue sources, and extended lifecycle hooks) is
-> reserved as **DRAFT** — see "Future grammar" appendix. Editorial
-> lifecycle is the one shipped grammar key whose runtime is **deferred
-> to v0.1.x**: parser and boot accept the shape, while
-> `request_publish` rejects it with `LIFECYCLE_NOT_IN_V010` until the approval
-> queue lands. Do not use editorial for a v0.1 publishing workflow.
+> **Status**: v0.1 shipped grammar. Unknown keys and enum values are rejected.
 >
 > **This is the reference manual** — what the system is. For *why* it
 > ended up this shape (alternatives considered, trade-offs accepted),
@@ -33,7 +26,7 @@ primitives Postgres has shipped for 30 years.
 | **`Schema`** | `CREATE TABLE` | no (manipulated via View / Procedure) | no |
 | **`View`** | `CREATE VIEW` | **yes** (auto-mounted on its declared public/staff REST and MCP surface; see ADR-0012) | no |
 | **`Procedure`** | `CREATE FUNCTION ... LANGUAGE plpgsql` | **no** (transport-agnostic; needs a `Trigger` to bind it) | **yes — handler ref to consumer's TS file** |
-| **`Trigger`** | `CREATE TRIGGER` + `pg_cron` + PostgREST route + `LISTEN/NOTIFY` | yes (the binding atom — turns Procedures into HTTP endpoints, cron jobs, MCP tools, lifecycle hooks) | no |
+| **`Trigger`** | `CREATE TRIGGER` + route/tool binding | yes (the binding atom — turns Procedures into HTTP endpoints, MCP tools, and lifecycle hooks) | no |
 
 The **read/write asymmetry is by design** and matches HTTP safe-vs-unsafe
 semantics. Reads (`View`) are idempotent and cacheable; the SDK
@@ -53,7 +46,6 @@ apiVersion: cms.mantle.aotter.net/v1
 kind: Schema | View | Procedure | Trigger
 metadata:
   name: posts                # required, kebab-case, unique within deployment
-  labels: { ... }            # optional, free-form
 spec:
   ...                        # kind-specific
 ```
@@ -73,7 +65,7 @@ A logical feature commonly bundles a Procedure + a Trigger (and often a
 Schema and a View). Put related atoms in one file separated by `---`:
 
 ```yaml
-# manifests/contact.yaml
+# manifests/site.yaml
 apiVersion: cms.mantle.aotter.net/v1
 kind: Procedure
 metadata: { name: send-contact-message }
@@ -93,8 +85,8 @@ spec:
   target: { procedure: send-contact-message }
 ```
 
-One file, two atoms. File count stays low; conceptual atom separation
-stays honest.
+One fixed file, two documents. Add every atom to `manifests/site.yaml` with
+`---`; the loader rejects other manifest filenames.
 
 ## What each atom is for (v0.1 minimum essential grammar)
 
@@ -112,7 +104,7 @@ metadata: { name: posts }
 spec:
   title: Posts                    # required: human-readable label for the admin UI
   localized: true                 # opt-in: row carries data.locale (ADR-0010)
-  lifecycle: simple               # default; 'none' is operational, 'editorial' is reserved
+  lifecycle: publishing               # default; use 'operational' for live records
   schema:
     $schema: https://json-schema.org/draft/2020-12/schema
     type: object
@@ -126,7 +118,8 @@ spec:
                                    # against localized Schemas.
       content:  { type: string }
       authorId: { type: string, format: uuid, x-mantle-bind: ctx.user }
-      createdAt: { type: string, format: date-time, x-mantle-bind: now }
+      createdAt: { type: integer, x-mcp-hint: timestamp-ms, x-mantle-bind: now }
+  searchableFields: [title, slug]   # id is always searched
   uniqueIndexes: [[slug, locale]]
   indexes: [[locale, title]]        # ordered, non-unique hot path
 ```
@@ -135,6 +128,17 @@ spec:
 in the user's primary language (the install-time chosen locale); the
 SPA shows this everywhere instead of `metadata.name`.
 
+**`spec.searchableFields`** — optional allowlist of top-level string
+properties used by Admin and Staff MCP substring search. Entry id is always
+searchable. This is separate from `indexes`; ordinary B-tree indexes do not
+accelerate leading-wildcard substring search.
+
+**`spec.uiSchema.list.filterField`** — optional Admin-only primary filter for
+an operational collection. The field must declare a non-empty string `enum`
+and be the first field of an `indexes` or `uniqueIndexes` tuple. Admin reuses
+the enum for sidebar links and list tabs; Staff MCP uses declared Views for
+richer query capabilities instead of reading UI configuration.
+
 **`spec.localized: bool`** (default `false`, ADR-0010) — opt-in per
 Schema. Localized Schemas store locale in `data.locale`; non-localized
 Schemas reject `data.locale` writes. Site config must declare the set
@@ -144,25 +148,22 @@ validates manifest shape.
 
 **`spec.translates: { parent, on }`** (ADR-0010) — declares this
 Schema as the translation companion to a non-localized parent, joined
-on the named field (typically `slug`). Implies `localized: true`. The
+on the named field (typically `slug`). Requires an explicit
+`localized: true`. The
 admin UI surfaces the child only as locale tabs in the parent's editor.
 
+Use a standalone localized Schema only when each locale row is an
+independent record. When several locale rows are versions of one entity,
+declare a non-localized parent plus a localized `translates` child; that
+relationship is what powers translation grouping and completeness in Admin.
+
 #### Lifecycle
 
-**`spec.lifecycle: 'simple' | 'editorial' | 'none'`** — controls the
+**`spec.lifecycle: 'publishing' | 'operational'`** — controls the
 entry's state machine.
 
-- `simple` (default) — `draft → published → archived`. No approval
-  queue. **This is the only content-workflow mode whose runtime ships
-  in v0.1.0.**
-- `editorial` — the six-state machine with an approval queue
-  (`draft → review → approved → scheduled → published → archived`,
-  with `published` returnable to `draft` for republish). The grammar and
-  state-machine vocabulary are reserved for forward compatibility, but the
-  approval/request-publish runtime is on the v0.1.x roadmap. In v0.1,
-  `request_publish` rejects with `LIFECYCLE_NOT_IN_V010`; do not declare
-  editorial for a current publishing workflow.
-- `none` — **operational records**, not authored content: orders,
+- `publishing` (default) — `draft → published → archived`. No approval queue.
+- `operational` — records that are not authored content: orders,
   inventory snapshots, grant/audit rows — anything written by
   Procedures as a side effect rather than drafted by a person. No
   content workflow applies: entries are live (`published`) the moment
@@ -175,8 +176,8 @@ entry's state machine.
   `update_record_<schema>` for these Schemas instead of draft tools.
 
 The modes are **per-Schema and mix freely** within a site. There is no
-site-wide lifecycle setting; one Schema can be `simple` while another
-is `editorial` and a third is `none`.
+site-wide lifecycle setting; one Schema can be `publishing` while another
+is `operational`.
 
 **Property-level extensions** (JSON Schema vendor keywords, all optional):
 
@@ -204,17 +205,11 @@ wire.
 | `now` | Server timestamp at write (ISO-8601 string with timezone) | `createdAt`, `submittedAt`, `grantedAt` |
 
 **v0.1 stamping behavior**:
-- Stamped on `INSERT` only. Update-stamping (e.g. `updatedAt: now` that
-  re-stamps on every UPDATE) is DRAFT — it lands when first use case
-  surfaces.
+- Stamped on `INSERT` only.
 - Caller-supplied value: rejected at input validation. The Procedure's
   effective input schema strips bound fields before checking caller
   input, so callers can't accidentally send them.
 - Visible in View output: yes, as ordinary columns. No special masking.
-- Used by `requires.auth.owns:` predicate (DRAFT): the predicate
-  compares a row's `x-mantle-bind: ctx.user` field to the current
-  `:ctx.user` to verify ownership without configuring per-Schema
-  owner-column names.
 
 **Why a closed enum** (highest-leverage discipline in the spec): bind
 values are server-controlled identity + time facts. If we accepted
@@ -241,8 +236,7 @@ detection). The admin uses declared refs to show related rows and to nest
 required child collections; it does not infer relationships from field names.
 Declare a single-field `indexes` entry for the ref field (for example,
 `indexes: [[authorId]]`) when reverse lookups must stay bounded. Mantle adds
-the native entry-order columns to that access path. Future grammar may upgrade
-it to enforced.
+the native entry-order columns to that access path.
 
 **Example**:
 ```yaml
@@ -286,12 +280,6 @@ MCP tool schemas preserve the hint for agents. Admin surfaces expose
 media-shaped fields but first-party upload hosting is optional and not
 part of first-run provisioning.
 
----
-
-Anything beyond these three (policies, computed columns, RBAC grants,
-owner declarations, `x-mantle-bind` enum extension) is **DRAFT** — see
-appendix.
-
 **Postgres analogue**: `CREATE TABLE posts (id UUID PRIMARY KEY, ...,
 UNIQUE (slug, locale));`
 
@@ -363,11 +351,8 @@ query, no `LIMIT n+1` probe.
 
 **v0.1 filter AST**: comparison operators (`eq`, `gt`, `gte`, `lt`,
 `lte`) plus `and` / `or`. Comparison `value` may be a literal or a
-`{ $param: <name> }` sentinel. v0.1.0 enforces required-only param refs;
-optional-with-skip semantics are reserved for v0.1.x. Field-to-field
-comparisons are not supported yet; compare a field to a literal or
-param. Anything else (`contains`, `recursive`, `gatedBy`,
-`join.aggregate`, `policies.skip`) is DRAFT.
+`{ $param: <name> }` sentinel. Param refs must be required. Field-to-field
+comparisons are not supported; compare a field to a literal or param.
 
 **Postgres analogue**: `CREATE VIEW recent_published AS SELECT ...
 FROM posts WHERE status = 'published' ORDER BY updated_at DESC LIMIT
@@ -383,8 +368,8 @@ provides the handler function with auto-generated TS types.
 `Procedure` is **transport-agnostic and not directly exposed**. It does
 not contain HTTP paths, methods, or MCP tool names. To call a Procedure
 from outside the SDK runtime, declare a `Trigger` whose `target` points
-at it. The same Procedure can be bound by multiple Triggers (HTTP +
-cron + MCP + lifecycle, all sharing one handler).
+at it. The same Procedure can be bound by multiple Triggers (HTTP + MCP +
+lifecycle, all sharing one handler).
 
 ```yaml
 apiVersion: cms.mantle.aotter.net/v1
@@ -426,9 +411,6 @@ export const handlers = {
 - `ctx.auth.scope: <scope>` — verified credential carries the exact opaque,
   consumer-owned scope; repeat to require multiple scopes
 
-Anything beyond this (`any:`, `owns:`, `withinMinutes:`, `contains:`,
-`requires.window`, `requires.quota`, `errors`, `retry`) is DRAFT.
-
 Both Procedures and Views may add one dynamic guard beside `auth`:
 
 ```yaml
@@ -485,7 +467,7 @@ spec:
 ```
 
 The same Procedure can have multiple Triggers — that's how it becomes
-"an HTTP endpoint AND a cron job AND an MCP tool" without duplicating
+an HTTP endpoint and an MCP tool without duplicating
 handler logic. Each transport is one Trigger; the Procedure body is
 shared.
 
@@ -496,17 +478,14 @@ tool on `surface: public | staff`), or `lifecycle` (entry-writer hook). For `lif
 Lifecycle hooks are wired through `LifecycleHookingEntryRepository`, so
 MCP, admin, and builtin write paths share the same hook behavior.
 
-- `cron` / `queue` are **DRAFT (v0.2+)** — speculative, gated by
-  concrete consumer demand. Same appendix § "DRAFT (v0.2+)."
-
 The state-machine "lifecycle" from the Schema atom
-(`Schema.spec.lifecycle: simple | editorial`) is a separate domain
+(`Schema.spec.lifecycle: publishing | operational`) is a separate domain
 that shares the word. The Schema setting governs which states an
 entry can be in; shipped lifecycle Triggers govern what fires around
 mutations.
 
 **Postgres analogue**: `CREATE TRIGGER ... AFTER INSERT ON posts
-EXECUTE FUNCTION ...` (lifecycle); `pg_cron` extension (cron); plus
+EXECUTE FUNCTION ...` (lifecycle), plus
 `CREATE FUNCTION` exposed via PostgREST routes (http) — Postgres has
 had all of these via extensions for years, just split across multiple
 mechanisms. We unify them under one atom.
@@ -584,7 +563,7 @@ different constraints.
 | `UNAUTHENTICATED` | `401` | no active session (admin API: missing/expired session cookie) |
 | `AUTH_DENIED` | `403` | `requires.auth` predicate evaluated false (or admin: caller lacks required staff role) |
 | `ENTITLEMENT_REQUIRED` | `402` | consumer guard denies current payment/membership/transaction entitlement |
-| `NOT_FOUND` | `404` | resource not found — admin: approval id; runtime: View name at `/api/views/<name>` |
+| `NOT_FOUND` | `404` | resource not found — entry id or View name at `/api/views/<name>` |
 | `HANDLER_NOT_REGISTERED` | `500` | `handler.ref` key not registered at boot |
 | `DISPATCHER_NOT_BUILT` | `501` | runtime feature not implemented in this SDK build |
 | `INTERNAL_ERROR` | `500` | uncaught handler exception |
@@ -595,10 +574,7 @@ may also fire in earlier loops (e.g. `HANDLER_NOT_REGISTERED`
 fires at boot — `phase: "boot"` — and that's where it should be
 caught; the runtime occurrence is defense-in-depth).
 
-Additional runtime codes activate as future grammar surfaces (e.g.
-`QUOTA_EXCEEDED → 429` arrives with `requires.quota`).
-
-## RBAC — what v0.1 ships, what's DRAFT
+## RBAC
 
 v0.1 auth gates use `requires.auth.all` with `ctx.user`,
 `ctx.staff: [<roles>]`, `ctx.auth`, and `ctx.auth.scope` predicates on
@@ -606,16 +582,6 @@ Procedures and Views. This covers staff-only, logged-in-only,
 credential-protected, and delegated-scope targets. One Procedure-backed guard
 handles mutable consumer business state without widening the static grammar.
 
-**Not yet shipped** (DRAFT):
-- Row-level read visibility (private posts, friend-only audiences)
-- Field-level write policies (this user can update body but not
-  parent_id)
-- Cross-Schema policy inheritance (gatedBy)
-- Quotas, edit-windows, rate limits
-
-These all live as `Schema.spec.policies.*` and `Procedure.spec.requires.*`
-sub-specs in the DRAFT spec. See "Future grammar" appendix.
-
 ## How to think when extending this CMS
 
 1. **What entities does the feature need?** → `Schema` for each.
@@ -624,13 +590,11 @@ sub-specs in the DRAFT spec. See "Future grammar" appendix.
    external read endpoints).
 3. **What operations?** → `Procedure` for each. One Procedure = one
    typed function call. Compose in handler code, not in YAML.
-4. **What invokes them?** → `Trigger` per source. Multiple Triggers
-   can target the same Procedure (HTTP + MCP + cron, all on one
-   handler).
+4. **What invokes them?** → `Trigger` per declared HTTP, MCP, or lifecycle
+   source. Site-owned events can call the same Procedure binding directly.
 5. **Who's allowed?** → `Procedure/View.spec.requires.auth` for static
    identity/scope; optional `requires.guard.procedure` for one live,
-   consumer-owned business check. Row-level and field-level rules remain
-   future grammar.
+   consumer-owned business check.
 
 If you find yourself wanting a 5th kind, **stop**. Sketch the same
 thing as a composition of the four; almost always it works.
@@ -722,8 +686,7 @@ grammar, leftmost-prefix rules, SQL helper, and query-plan examples.
   comfortable. Anonymous public responses can hit version-local Workers
   Cache before the Worker; origin misses use indexed D1 reads.
 - **Mid-scale (10k – 100k entries)**: declare measured list/filter
-  access paths with ordered `indexes`. Cross-collection JSON-path joins
-  may eventually gain `x-mantle-ref` auto-lift; that remains DRAFT.
+  access paths with ordered `indexes`.
 - **Hard D1 limits**: 1 MB max row size; 5,000 rows per query result;
   single-writer per database (concurrent writes serialize).
 - **Cross-region read**: D1 is region-pinned; first origin hit from a
@@ -753,7 +716,6 @@ When this path is taken (post-v0.1; not implemented yet), the
 | `json_each` → array operators (`@>`, `&&`) | none — predicates stay declarative |
 | SDK-stamped `now` → `DEFAULT now()` (optional) | none |
 | SDK-side policy rewriting → native RLS (optional) | none |
-| `Trigger.target.project` single-writer DO → real same-transaction trigger | atomicity guarantee strengthens; YAML grammar unchanged (the `atomicity:` declaration just stops needing the eventual-consistency caveat) |
 
 Migration shape: `entries` table dumped from D1, restored to PG. Stay
 single-table-with-discriminator (drop-in) or split into
@@ -761,68 +723,12 @@ table-per-collection (more PG-idiomatic, longer migration). Both shapes
 remain valid `cms.mantle.aotter.net/v1` deployments.
 
 **v0.1 commitment**: D1 only via the Cloudflare adapter. Hyperdrive +
-PG path is documented as the upgrade route but not implemented. SDKs
-and starters target D1 exclusively. The Netlify adapter package
-(`@aotter/mantle-netlify`) is a README stub for v0.2; its
-existence is an engineering forcing function ensuring the runtime
-package stays portable across adapters.
-
-## Roadmap — what's not in v0.1.0
-
-> See [ADR-0001 §"Future grammar discipline"](adr/0001-four-atom-manifest-model.md#future-grammar-discipline-was-poc-adr-0005)
-> for the v0.1 minimum-vs-roadmap discipline, the promotion process,
-> and the YAGNI argument that gates speculative shipping.
+PG is an upgrade route, not an implemented adapter. SDKs and starters target
+D1 exclusively.
 
-The atoms are locked at 4. Their **inner grammar** is intentionally
-narrow at v0.1.0 and grows in two tiers:
+## Detailed shipped grammar
 
-1. **v0.1.0 shipped** — grammar parses and runtime behavior is wired
-   in the current rebuild.
-2. **v0.1.x committed** — on the patch-release roadmap. Spec is
-   documented; implementation lands within the v0.1 series. The unsupported
-   runtime path fails closed with a code naming the feature.
-3. **DRAFT (v0.2+)** — speculative, gated by concrete consumer
-   demand. Parser/static validation rejects with `DRAFT_KEY_USED`. May or may
-   not ship — depends on whether real use cases apply pressure.
-
-### v0.1.0 shipped
-
-#### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
-
-Grammar lives in v0.1.0. Runtime is the
-`LifecycleHookingEntryRepository` decorator wrapping the entry-writer
-chokepoint so MCP / admin / builtin paths all fire the same hooks.
-Full shape lives further down.
-
-#### `Procedure.handler.kind: builtin` — SDK-supplied CRUD Procedure
-
-Grammar lives in v0.1.0. Runtime is the
-`InvokeBuiltinUseCase` that dispatches `op: create | update | upsert
-| delete | archive` against the entry-writer chokepoint with `x-mantle-bind`
-stamping and `input ∩ Schema.properties` projection. Full shape lives
-further down.
-
-#### `Trigger.source.kind: mcp` and shared authorization
-
-An MCP Trigger binds a declared Procedure to either the public or staff MCP
-surface. Procedures/Views share `ctx.auth`/scope predicates and optional guard
-orchestration across REST and MCP. Staff role is loaded live for each protected
-call; staff Views remain absent and un-callable on public MCP.
-
-### Detailed shipped grammar and v0.1.x reservation
-
-> The `handler.kind: builtin` and `Trigger.source.kind: lifecycle`
-> sections below describe shipped v0.1.0 behavior. Only the
-> `Schema.spec.lifecycle: editorial` subsection remains v0.1.x-committed.
-
-#### `Schema.spec.lifecycle: editorial` runtime
-
-Grammar and boot already accept the key, but `request_publish` emits
-`LIFECYCLE_NOT_IN_V010` because the approval-queue runtime ships in v0.1.x.
-When that runtime lands, the same manifest can use the publish workflow without
-a grammar change.
-
-#### `handler.kind: builtin` — thin shortcut over the storage adapter for trivial CRUD-shaped Procedures
+### `handler.kind: builtin` — thin shortcut over the storage adapter for trivial CRUD-shaped Procedures
 
 Use when the body is "insert a row" / "update a row" / "delete a
 row"; reach for `ref` when there is real business logic. Shape:
@@ -839,11 +745,11 @@ spec:
 
 | op | Behavior |
 |---|---|
-| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: none`. |
+| `create` | INSERT a new row. Project `input ∩ Schema.spec.schema.properties`; stamp `x-mantle-bind` fields; generated id; status is `draft`, or immediately `published` for `lifecycle: operational`. |
 | `update` | UPDATE in place. `input.id` + `input.expectedVersion` (OCC) required. Bumps version. |
 | `upsert` | If `input.id` resolves, behaves as `update`; else as `create`. |
 | `delete` | Hard DELETE by id. |
-| `archive` | Soft-archive (status='archived'). The manifest validator permits this builtin only for `editorial` Schemas; the archive transition itself is runtime-wired, while editorial approval/request-publish remains deferred. |
+| `archive` | Soft-archive a publishing entry (`status='archived'`). |
 
 The Procedure's `input` is the contract with the *caller*. It MAY
 declare fields the Schema does not (e.g. a Turnstile token). The
@@ -853,11 +759,10 @@ the side-channel fields pass validation. To act on those fields
 (read the token, call the vendor), declare a `before_create`
 lifecycle Trigger — see below.
 
-`request_publish` and `publish` are intentionally not in the
-builtin vocabulary. They are editorial-workflow operations, not CRUD
-primitives.
+`request_publish` and `publish` are intentionally not in the builtin
+vocabulary. They are lifecycle operations, not CRUD primitives.
 
-#### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
+### `Trigger.source.kind: lifecycle` — bind a Procedure to a Schema event
 
 Shape:
 
@@ -879,12 +784,15 @@ spec:
 |---|---|
 | `before_create` | Before INSERT. Throw cancels. |
 | `after_create` | After INSERT. Default best-effort. |
-| `before_update` | Before UPDATE. Throw cancels. |
-| `after_update` | After UPDATE. Default best-effort. |
+| `before_update` | Before UPDATE or a status transition whose target is not `published` (including unpublish and archive). Throw cancels. |
+| `after_update` | After UPDATE or a status transition whose target is not `published` (including unpublish and archive). Default best-effort. |
 | `before_delete` | Before DELETE. Throw cancels. |
 | `after_delete` | After DELETE. Default best-effort. |
-| `before_publish` | Before any supported status transition to `published` (the shipped workflow is `simple`). |
-| `after_publish` | After any supported status transition to `published` (the shipped workflow is `simple`). |
+| `before_publish` | Before any supported status transition to `published` (the shipped workflow is `publishing`). |
+| `after_publish` | After any supported status transition to `published` (the shipped workflow is `publishing`). |
+
+v0.1 has no separate unpublish or archive hooks. Do not treat
+`before_update` / `after_update` as edit-only hooks.
 
 **Atomicity defaults by phase**:
 - `before_*`: `errorPolicy: abort`. Handler throw cancels the
@@ -915,9 +823,8 @@ post-mutation row for every `after_*`.
 
 **Hook ordering**: when multiple lifecycle Triggers bind the same
 `(schema, hook)`, the runtime fires them **alphabetically by
-`Trigger.metadata.name`**. A `priority: number` key is reserved for
-v0.2; today, choose names that sort correctly (`010-bot-check`,
-`020-rate-limit`).
+`Trigger.metadata.name`**. Choose names that sort correctly
+(`010-bot-check`, `020-rate-limit`).
 
 For deferred delivery, that ordered Trigger-name list is captured in
 one strict versioned event. Every captured Trigger runs before a
@@ -928,103 +835,7 @@ Cloudflare wiring, the 128 KB platform limit, retry/DLQ configuration,
 idempotency, and legacy-envelope draining are specified in
 [Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md).
 
-`before_publish` and `after_publish` already wrap the shipped simple publish
-transition. When editorial approval lands, the same hooks wrap its final
-transition to `published`; no second hook grammar is planned.
-
-### DRAFT (v0.2+, speculative)
-
-Each item below lands when the first concrete real-world use case
-forces it, not on speculation. Today, do not implement; parser/static
-validation rejects it with `DRAFT_KEY_USED`.
-
-#### Schema future
-- **`x-mantle-ref` auto-lift to virtual column** — when a property
-  carrying `x-mantle-ref: <other-schema>` is referenced in any registered
-  View's `filter:` or future `join:`, the SDK auto-creates the virtual
-  column + non-unique index without requiring an explicit `indexes`
-  declaration. Solves cross-collection JSON-path join
-  performance without making authors think about it. Pure SDK
-  behavior; no new YAML grammar.
-- **`spec.policies.visible`** — row-level read predicate auto-AND'd
-  into Views from this Schema. Lands with first private/audience
-  feature.
-- **`spec.policies.readable.fields`** — field-level wire-mask. Lands
-  when staff-only fields surface (e.g. `threadLength` visible to
-  editors only).
-- **`spec.policies.writable.{fields, create}`** — field-level write
-  gate auto-applied to all writers.
-- **`spec.policies.owner`** — names the ownership column for `owns:`
-  predicate. Currently implicit (`authorId`).
-- **Computed columns via projection Trigger** — see `Trigger.target`.
-
-#### View future
-- **`recursive: { parent, rootWhen, pathBy, depthAs?, pathAs?, maxDepth }`**
-  — declarative recursive CTE. Lands with first threaded-reads feature
-  (comments, taxonomies).
-- **`params: { <name>: <jsonschema> }`** — caller-bound view parameters.
-- **`gatedBy: [{ schema, policy, on }]`** — cross-Schema visibility
-  inheritance.
-- **`join: [{ as, from, on, project?, aggregate?: count|exists, bind? }]`**
-  — joined relations with optional reducer (per-row count or boolean).
-- **`policies: { skip: [<policy-name> | field, ...] }`** — explicit
-  bypass for admin/audit Views.
-- Filter AST extension: `contains` (array containment), `not`, `in`, `like`.
-
-#### Procedure future
-- **`requires.auth.any`** with disjunction; the shipped `all` predicate
-  vocabulary extends to `owns: { schema, idFrom }`, `contains: {
-  schema, idFrom, field, valueFrom }`.
-- **`requires.window.{withinMinutes, column?}`** — temporal
-  precondition, sibling-modifier of `owns:`. DRY rule: window MUST
-  sit beside exactly one `(schema, id)`-binding predicate in the same
-  any/all group.
-- **`requires.quota.{key, limit, per, overrideFrom?}`** — declarative
-  rate cap. Override Schema lookup keyed by `ctx.user`. Counter
-  substrate: Durable Object.
-- **`errors.{onHandlerThrow, onRecursionDepth, maxDepth}`** + **`retry.{
-  limit, backoff, retryOn, idempotencyKey?}`** — failure-policy
-  declared. Retry + `op: create` requires `idempotencyKey:` (parse
-  error otherwise).
-
-#### Trigger future
-- **`source.kind: cron`** with `expr:` — scheduled invocation.
-- **`source.kind: queue`** — async fan-out / message-driven invocation.
-- **`source.kind: lifecycle.foo`** — DRAFT extensions to the shipped
-  lifecycle hooks (e.g. `before_archive`, `after_request_publish`).
-  The 8 hooks listed in the detailed shipped section are the floor,
-  not the ceiling.
-
-(Full lifecycle Trigger spec for the 8 shipped hooks lives
-in the detailed section above. The remaining DRAFT items
-below are the speculative v0.2+ shapes that haven't yet been promoted
-to a committed roadmap.)
-
-- **`target.project: { schema, where, set: { <col>: { aggregate, from,
-  where } } }`** — declarative aggregate-projection across Schemas.
-  Replaces hand-written counter handlers. Same-transaction on PG;
-  bounded-eventual on D1 via single-writer DO.
-- **`atomicity: same-transaction | best-effort`** — explicit guarantee
-  declaration when projection Triggers ship.
-
-#### Cross-cutting future
-- **Closed `ctx.*` predicate identity**: v0.1 `{ user, staff, auth,
-  auth.scope }`
-  extends to `{ ..., system }` when SDK-internal Trigger executor
-  paths land. Multi-tenant deployments would add `{ tenant }` via
-  grammar-revise round if/when that product shape is pursued. New
-  entries require explicit grammar-revise (closed enum is
-  load-bearing infrastructure).
-- **Placeholder namespace `$.*`**: `$.input.<f>`, `$.row.<f>`, `$.op`,
-  `$.params.<f>`, `$.source` — write-time data-flow bindings inside
-  policy ASTs and handler signatures. Distinct from `:ctx.*` identity
-  bindings; one-site evaluation rule.
-- **`Schema.spec.staffBypass: [<role>]`** — DRY shortcut once
-  `ctx.staff: [editor, owner]` repetition crosses 4+ schemas.
-
-Each extension goes through a 3-agent review (yml-editor proposes /
-code-impler tests buildability / fresh-dev verifies clarity) before
-locking. v0.1 is the floor, not the ceiling.
+`before_publish` and `after_publish` wrap the shipped publishing transition.
 
 ## Lineage — the academic foundations
 
@@ -1037,6 +848,6 @@ locking. v0.1 is the floor, not the ceiling.
 
 The composite design — declarative resources + ECA-fired procedures +
 policy-gated execution — is sometimes labeled **Active Database +
-Policy-Based Management**. Postgres + PostgREST + pg_cron is the
+Policy-Based Management**. Postgres + PostgREST is the
 canonical full-stack reference; we abstract that pattern up to the
 application layer with K8s-style YAML manifests.

package/docs/labels.md

@@ -33,7 +33,7 @@ For package README or package-local docs changes, prefer the package area label
 | `area:skills` | `skills/*` agent briefs and install/extend/provision workflows. |
 | `area:admin-ui` | `packages/mantle-admin-ui` React admin SPA. |
 | `area:docs` | Repo-wide human docs, governance docs, ADR text, release docs, root README content, and cross-cutting documentation work. |
-| `area:adapter` | Adapter boundary work spanning Cloudflare, Netlify stub, or future adapters. |
+| `area:adapter` | Adapter boundary work spanning Cloudflare or future adapters. |
 
 ## Release and review gates
 
@@ -41,7 +41,8 @@ For package README or package-local docs changes, prefer the package area label
 |---|---|---|---|
 | `release-gate` | Blocks a public release or release-quality claim. | Must be resolved or explicitly deferred before release. | The gate is closed or deferred by maintainer decision. |
 | `v0.1.0` | Required for the v0.1.0 release gate. | Track in the v0.1.0 release pass. | The item lands or is moved out of v0.1.0. |
-| `breaking-change` | Semver-relevant breaking change. | Changelog and release notes must call it out. | The change is redesigned to be non-breaking. |
+| `breaking-change` | Semver-relevant breaking change. | Generated release notes must call it out. | The change is redesigned to be non-breaking. |
+| `skip-release-notes` | Release bookkeeping with no user-facing change. | Excluded from generated GitHub Release notes. | The PR contains a user-facing change. |
 | `needs-adr` | Architecture, trust boundary, package boundary, or long-lived decision needs an ADR or ADR-lite proposal. | Do not merge implementation until the decision is captured. | ADR/proposal lands or maintainer confirms an existing ADR covers it. |
 | `needs-grammar-revise` | Manifest grammar or closed-enum change. | Requires grammar-revise round before code/types/starters change. | Grammar decision lands or the change no longer affects grammar. |
 | `needs-discussion` | Not converged enough for implementation. | Do not start coding from this issue. | Closing criteria are met and scope is concrete. |
@@ -60,6 +61,7 @@ gh label create "area:admin-ui" --description "React admin UI" --color "1d76db"
 gh label create "area:docs" --description "Documentation and governance" --color "1d76db"
 gh label create "area:adapter" --description "Adapter boundary and future adapter work" --color "1d76db"
 gh label create "breaking-change" --description "Semver-relevant breaking change" --color "b60205"
+gh label create "skip-release-notes" --description "Release bookkeeping only; omit from generated GitHub notes" --color "ededed"
 gh label create "needs-adr" --description "Requires an ADR or ADR-lite decision before merge" --color "d93f0b"
 gh label create "needs-grammar-revise" --description "Requires manifest grammar review before implementation" --color "d93f0b"
 gh label create "needs-discussion" --description "Not converged enough for implementation" --color "fbca04"

package/docs/release-process.md

@@ -62,8 +62,9 @@ decision instead of starting another local redesign loop.
 ## 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.
@@ -77,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`
@@ -179,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: