@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/docs/skills/develop/SKILL.md

@@ -1,258 +1,88 @@
 ---
 name: develop
-description: Work on any Mantle project using the Core SDK contract. Use for manifest, runtime, content model, handler, adapter, validation, and MCP work after a project already exists.
+description: Work on an existing Mantle 0.2 project — manifests, SQL Views and Procedures, ref handlers, the service entry, surfaces, identity, MCP tool design and independent acceptance — using the installed package's contract.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/develop/SKILL.md
-  applies_to: mantle grammar v0.1
-  projection: project
+  applies_to: mantle 0.2
+  projection: package
 ---
 
 # Mantle Develop
 
-This is the Core workflow skill for an existing Mantle project. Repo-local
-copies are byte-for-byte projections from the installed package; its embedded
-docs govern runtime/API behavior.
-
-## First Read
-
-1. `package.json` for the installed `@aotter/mantle*` versions.
-2. The manifest directory selected by the project scripts, the actual host
-   entry and adapter config (for example `wrangler.jsonc` on Cloudflare).
-   Read custom Auth construction there when present.
-3. Optional local context: `.mantle/plugins.json`, `.mantle/plugins.lock.json`,
-   and `.mantle/recipes/`. Legacy launch/handoff files are context only.
-4. Installed Core docs in `node_modules/@aotter/mantle/docs/`.
-
-If `node_modules/` is missing, run `pnpm install --frozen-lockfile` before
-falling back to remote docs. Remote docs must use a tag matching the installed
-version; never use `develop` branch docs for a versioned consumer project.
-
-## Existing Examples
-
-Read installed `docs/handbook/start/project-and-cli.md` and
-`docs/examples/README.md`. Use `docs/examples/host-minimal-worker/` for Spec +
-adapter without Admin. Read `docs/examples/host-local-admin-otp/` only when the
-project already has Admin or the human asked for Dev UI — that path is opt-in.
-Ingest only `docs/examples/builtin-*.md` Manifests as grammar for new domains.
-Read `docs/examples/cf-primitives-*.md` before inventing Durable Object, Queue,
-cron, or `ref` handler patterns.
-References are test/documentation, not a Starter or a fixed application shape.
-
-Public rendering is opt-in consumer wiring: `mountPublicRoutes`, a
-`TemplateRegistry`, and a matching `publicPathResolver` must agree on the
-exposed collections. Do not auto-publish every Schema. Applications document their mounted URL surface in their own README.
-Import the registry and resolver from `@aotter/mantle/web`; Core runtime does
-not install public rendering by itself.
-
-## Authoring CLI
-
-Use the project's scripts first; applications use the shipping
-`mantle` authoring CLI from `@aotter/mantle`. Ask the installed CLI for its
-command list instead of trusting one copied into prose — the surface is
-version-matched and changes between releases:
-
-```bash
-pnpm exec mantle --help
-pnpm validate
-```
-
-On 0.1.5 and newer, `generate --host cf|chatgpt-sites` assembles a new blank
-app; no `--features` selects Spec, Runtime, API, MCP, Admin and Web. Explicit
-`--features` selects a smaller composition. It never invents a business
-Schema. Existing authored apps keep compile mode, and older installed CLIs
-may not support project generation. Check this project's CLI help first.
-
-## Core Model
-
-Mantle exposes exactly four declarative atoms:
-
-| Atom | Purpose |
-|---|---|
-| `Schema` | Stored entity/table shape. |
-| `View` | Read/query surface. |
-| `Procedure` | Typed mutation or operation. |
-| `Trigger` | HTTP/lifecycle/MCP invocation binding. |
-
-Do not invent manifest kinds such as `Form`, `Feature`, `Workflow`, or
-`Membership`. Compose those from the four atoms plus TypeScript only where
-the atoms cannot express the behavior.
-
-## Choose the manifest feature first
-
-Read installed `docs/handbook/reference/features.md` to map the requested
-behavior to fields before adding handlers or a custom UI. For host-only reads,
-`surface: internal` keeps a View out of REST/MCP/Admin while preserving its
-`requires` checks. Read `docs/handbook/guides/typed-queries.md` for generated
-View params/results, indexed entry reads, and their authorization boundary.
-Use `from` for portable typed projections; SQL is for queries needing native
-SQLite and produces `unknown` row types.
-
-For Admin labels, inputs, collection columns/tabs, reports or action buttons,
-read `docs/handbook/guides/admin-ui.md`. Prefer supported Schema/Procedure/View
-metadata and `uiSchema` before custom frontend code. These control the Admin
-console, not the visitor frontend. Regenerate and verify the actual console;
-never edit generated `public/_mantle/admin/` assets.
-
-## Content Edits
-
-- Follow the actual frontend content source. Use Admin or Staff MCP for
-  runtime-backed content. Do not invent an overlay/seed homepage.
-- For a new submitted field, update the stored `Schema` and the public
-  `Procedure.spec.input` before any form UI. Keep public mutation inputs
-  `additionalProperties: false`; otherwise JSON Schema's default may strip an
-  undeclared field while returning success.
-- Use `lifecycle: operational` for submissions, inquiries, orders, and other
-  Procedure-created operational records that staff inspect or correct. Reserve
-  `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 frontend content source;
-  Admin and Staff MCP derive their typed controls from the manifest values.
-- If the application has a `page` Schema with sections, update its declared
-  section properties when adding display fields; an undeclared property has no
-  runtime-backed Admin or Staff MCP path.
-- Update notification handlers when they need the new field. Test the stored
-  entry, not only the HTTP `{ "ok": true }` response.
-
-## Locales
-
-- `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.origin`, `siteDefaults.locales`, and `siteDefaults.icons` are
-  code-owned and boot-synced. The icon list is shared by browser favicons,
-  Admin chrome, and MCP `serverInfo.icons`; keep its static files under
-  `public/`. 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. A `MantleStorageAdapter` prepares the compiled
-plan into semantic storage ports; `createMantleRuntime` binds that prepared
-storage and selected capabilities. Database drivers and asset serving belong
-to the host/optional composition. Follow the installed adapter guide.
-
-Do not assume Cloudflare unless the project imports `@aotter/mantle/cloudflare`
-or its adapter config is visible. A future Netlify adapter should satisfy the
-same Core workflow through its own ports and provider setup.
-
-Site code is a consumer of this abstraction. Use Manifests, runtime use cases,
-`runtime.entries`, and optional `runtime.siteConfig`; do not query Mantle-owned `entries` or
-`site_config`, reach through deprecated `runtime.db`, copy generated-column
-names, or construct SDK KV keys. Cloudflare bindings belong only at the
-composition root. If a normal feature cannot be expressed through a
-purpose-shaped surface, treat that as a Core abstraction gap instead of
-teaching the project Mantle internals.
-
-## Auth Composition
-
-Generated full apps select Admin by default; smaller selections can omit it.
-A project without `@aotter/mantle-admin-ui` is complete when Admin was not
-selected. If Admin was selected but its package is missing, install the
-CLI-declared exact version and rerun generation.
-When Admin is installed, `createMantleWorker({ auth })` with `email-otp`
-and `ConsoleEmailSender` is the local human path (OTP in wrangler logs).
-That override owns Auth construction; Core still owns `/admin` and
-`/api/auth/*`. Admin also requires wrangler `assets.directory=./public`
-and an `ASSETS` binding. A white screen at `/admin` with HTML 200 and
-`/_mantle/admin/assets/*` 404 is a missing assets binding, not a missing
-frontend build.
-
-Generated Cloudflare apps use `MANTLE_AUTH_MODE=local-otp` on loopback after
-copying `.dev.vars.example` to `.dev.vars` and setting a real owner email and
-random secret. Production uses `hosted` or `self-managed` with provider
-credentials and `ADMIN_GITHUB_LOGIN`. Conventional Cloudflare projects that
-do not replace Auth use those two production modes; Core owns that standard
-composition and rejects partial or mixed bindings. Preserve the explicit
-mode recorded in Worker config, keep provider secrets out of source, and
-do not infer a mode from whichever credentials happen to be present.
-
-## Performance Loop
-
-After changing a Schema index, View filter/order, public API, or rendered page,
-run the project's index check when present. Otherwise run the installed
-harness directly:
-
-```bash
-pnpm exec mantle-harness indexes --require-public --format text
-```
-
-The check uses crowded real SQLite and the shipped compiler. It complements
-`pnpm validate`; it does not replace correctness validation. Declare the
-smallest ordered index justified by the measured path and respect SQLite's
-leftmost-prefix rule; which columns an index may name and how a public View's
-status predicate shapes it is in the handbook (`reference/schema.md#indexes`).
-Do not change user-visible filter or ordering semantics
-just to make the gate pass. Do not add every permutation or cache every read.
-
-For relevant Cloudflare serving changes, start the project and sample the
-actual routes:
-
-```bash
-pnpm exec mantle-harness http \
-  --base-url http://127.0.0.1:8787 \
-  --route page=/en/example \
-  --rounds 20 --warmup 2 --format text
-```
-
-Prefer query plan, query count, `rows_read` scaling, and cache MISS/HIT
-evidence. Do not create CI gates from absolute local milliseconds.
-
-## Loop
-
-```bash
-pnpm install --frozen-lockfile
-pnpm validate
-pnpm check:indexes # when the project provides it
-pnpm typecheck
-pnpm check
-```
-
-Use `pnpm dev` for local preview when the project provides it.
-
-## Connect a Local MCP Client
-
-Start the project with `pnpm dev`, then use the exact local origin it prints.
-The conventional Cloudflare adapter exposes:
-
-- `http://localhost:8787/mcp` for public tools;
-- `http://localhost:8787/mcp/staff` for authenticated authoring tools.
-
-Prefer the client's native remote HTTP + OAuth support. Use a standard
-HTTP-to-stdio bridge such as `npx -y mcp-remote <url>` only when the client
-accepts stdio MCP servers but cannot connect to remote HTTP directly. Mantle
-does not own a separate local proxy or an auth-bypass mode.
-
-Before changing client config, confirm the Worker is reachable:
-
-```bash
-curl -i http://localhost:8787/mcp
-```
-
-An OAuth-protected endpoint should respond with `401` and a
-`WWW-Authenticate` resource-metadata challenge before sign-in. After
-connecting, inspect `tools/list`; make one read-only `query_view_*` call when
-available before invoking any mutation. Use project-scoped client config when
-the client offers it, and never commit OAuth tokens or the bridge's token
-cache.
-
-## Rules
-
-- Keep content models in the configured manifest directory; its immediate
-  `.yaml` and `.yml` files are loaded together.
-- Add TypeScript only for handlers, rendering, adapter wiring, or real behavior.
-- Do not write directly to D1, KV, Postgres, or object storage for content
-  authoring. Use runtime use cases, admin APIs, or Staff MCP.
-- Do not commit provider secrets.
-- If the work is an installable capability, switch to `mantle:plugin`.
+## Workflow
+
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+Use the native Store/query/surface entries and app-owned fetch from the [service
+composition guide](../../handbook/cloudflare/service-entry.md).
+Pair every HTTP Trigger with an MCP Trigger by default; see [Trigger](../../handbook/reference/trigger.md)
+for the generate warning and deliberate asymmetry exception.
+Keep optional modules out of unused entry imports and auth dynamically loaded.
+Run actual public/member/admin HTTP, MCP and UI scenarios; verify stored state,
+visibility, OCC and restart persistence, not just a 200 response.
+Before reporting any new app or feature as done, follow the [independent
+acceptance guide](../../handbook/guides/agent-workflow-acceptance.md): write a
+private rubric, then give one fresh agent per role (`admin`, `user`) only its
+role and entry points, across every surface it uses. This is not limited to
+MCP; if it was not run, say so explicitly and report the work as UNVERIFIED
+rather than done. For MCP workflows, also run the guide's design audit before implementing
+tools.
+
+For native Admin, read the [current guide](../../handbook/guides/native-admin.md):
+the app builds Admin with `mantle bundle`. To customise pages, slots, hooks or
+MCP-host-safe components, follow [Customising Admin](../../handbook/guides/native-admin.md#customising-admin).
+Keep matching SDK, Admin and UI versions. Ref handlers retain caller-bound
+`ctx.store`; generic Admin reads use shared generated View templates and writes
+use native Procedure fragments.
+Check actual member/Admin OTP, private scope/TTL/translation visibility, paging,
+statistics, safe/exact OCC and no automatic retry after unknown 503 outcomes.
+
+For application-owned MCP App entries and host checks, follow the [MCP Apps
+guide](../../handbook/guides/mcp-apps.md).
+
+Build a custom frontend with `App` from `@modelcontextprotocol/ext-apps`: register
+`ontoolinput`/`ontoolresult` before `connect()`, and use `callServerTool` for
+host-proxied calls. Keep protocol negotiation and message routing in the official
+client; importing its types while writing a second `postMessage` bridge is
+insufficient.
+
+For Admin UI upgrades, follow the installed handbook's
+[retained-page recipe](../../handbook/guides/mcp-apps.md#keep-old-conversations-working-after-an-upgrade).
+Keep deployed snapshots in source/artifact storage and pass `previous` to
+`adminMcpApps`; verify old conversations after a changed UI build without host
+tool refresh, reconnection or cache clearing. Keep tool contracts compatible
+through the declared retention window.
+
+
+Place admin MCP Procedures in Admin deliberately: `spec.uiSchema.collectionAction:
+<schema-name>` adds a collection-header action; `spec.target: { schema, id,
+version? }` selects row actions and binds the row id / reviewed OCC version to
+the named inputs. Other admin operations appear under Operations in the sidebar.
+Keep state conditions in the SQL WHERE: simple AND equality/IN literals become
+row-menu hints, while the Procedure remains the authority. Required-ref child
+collections fold under their parent's sidebar group; with two or more required
+`id` refs, set Schema `uiSchema.nav.parentField` to the parent's ref (generate
+refuses otherwise); use `uiSchema.nav.standalone: true` for a top-level entry.
+
+## Database changes
+
+The runtime never creates, alters or checks tables. Boot and requests run no DDL, introspection or schema checks.
+
+For the first install, apply generated `schema.sql`, including selected auth/site DDL, to an empty database. Apply selected seed SQL explicitly.
+
+For every later schema change, the application's coding agent diffs the regenerated `schema.sql`, writes a migration with the host's native tool (`wrangler d1 migrations` or the app's PostgreSQL migration tool), rehearses it on a copy, and applies it before deploying the new code.
+
+Destructive changes and type changes need explicit data migration. Mantle drops nothing. Initial `schema.sql` is not an upgrade script.
+
+## Data paths
+
+Writes use Store `insert` / `update` / `delete`, `batch`, `transaction`, or declared Procedures. Never use raw SQL writes: they bypass scope, TTL, publishing and system-column rules. For reads beyond an id lookup or simple AND filter (joins, aggregates, OR, reuse), declare an internal View so the SQL is reviewable and typed. Store `findById`, `find` and `first` remain suitable for handler lookups and embedding in an existing app. Ref handlers receive `ctx.store` bound to the same Caller and transaction.
+
+For simple creates/partial updates, prefer Store-backed ref Procedures; keep
+Procedure `requires`/generated input checks, use only allowed patch fields and
+return safe business fields with the actual returned ID/version. Preserve
+omitted fields and document null semantics. Retain SQL for atomic conditional
+or related writes; D1 batches cannot consume an earlier result. Follow the
+[Store write guidance](../../handbook/guides/typed-queries.md#prefer-store-backed-ref-procedures-for-simple-writes).

package/docs/skills/integrate/SKILL.md

@@ -1,60 +1,49 @@
 ---
 name: integrate
-description: Integrate Mantle into an existing application. Use when the application has its own code, routes, storage or deployment and the owner wants to add Mantle, replace part of it, or rebuild with Mantle while migrating frontend and data.
+description: Add Mantle 0.2 to an existing application, or rebuild one on Mantle and migrate its data. Use when the application already has its own code, routes, users, storage or deployment.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/integrate/SKILL.md
-  applies_to: mantle grammar v0.1
+  applies_to: mantle 0.2
   projection: package
-  projectionReason: Existing-project migration is opt-in; a fresh generated app does not need this brief.
 ---
 
 # Integrate Mantle into an existing application
 
-Work in the target application. Read its installed `@aotter/mantle` version,
-CLI help and package-local docs before editing. If Mantle is absent, inspect
-the application first, then install an exact SDK version only after choosing an
-integration strategy. Use the installed version's contract; do not copy
-`develop` branch examples into an older consumer.
-
-## Inspect and decide
-
-Map the actual entry points, router, frontend, auth, storage, data volume and
-relationships, deployment pipeline, URLs, background jobs and existing tests.
-Identify which behavior the owner wants Mantle to own and what must remain
-stable. Compare three approaches using the application's evidence:
-
-1. **Embed selectively:** keep the host and call Mantle's parser, Runtime or
-   selected surfaces through its documented package APIs. The host owns wiring.
-2. **Replace incrementally:** move one bounded capability at a time. Define
-   where reads and writes go during coexistence and how each step is checked.
-3. **Rebuild and migrate:** create a separate new Mantle application, port the
-   frontend and business behavior, and transform/import existing data. Prefer
-   this when adapting the old structure costs more than rebuilding. Preserve
-   relevant IDs, relations, URLs and identity semantics; rehearse the data
-   transfer before a production cutover.
-
-Explain the chosen path and its concrete tradeoffs to the owner. A small
-prototype or read-only inventory may resolve uncertainty. Do not run a generic
-project converter or assume the current application's shape matches a
-generated Cloudflare or ChatGPT Sites skeleton.
-
-## Implement and verify
-
-- For embedding, retain user-owned entry/config/build files. Use the installed
-  direct-authoring docs and CLI to validate manifests and emit bindings; wire
-  the selected Mantle capabilities into the existing host explicitly.
-- For incremental replacement, establish a clear owner for each data write
-  and request route at every stage. Verify old and new behavior together.
-- For rebuilding, generate in a **separate directory** with the installed
-  CLI, move frontend and handlers deliberately, and plan data mapping and
-  import separately. Review database migrations before application or cutover.
-- Run the application's build and representative behavior checks for the
-  changed routes, auth and data. `mantle generate --check` checks generated
-  output against its declared selection; it cannot certify host integration.
-  For live data, record migration counts and a rollback or recovery path
-  appropriate to the project.
-
-Leave existing data and deployment untouched until the requested migration
-and release steps are ready. Report which capabilities Mantle now owns,
-what was verified, and what remains for application deployment or cutover.
+## Workflow
+
+Read the installed SDK README, then follow the version-matched [project and CLI
+workflow](../../handbook/start/project-and-cli.md) before editing.
+
+Keep the application router, database/pool, identity and frontend. Replace
+Core consumers explicitly and compose only selected generated entries. Resolve
+one Caller per request with the shared cookie-session origin check. Rehearse
+data-preserving schema/auth/role migrations on a copy and retain rollback artifacts.
+Initial schema.sql is for an empty database, not an in-place upgrade. Requests run
+no DDL or storage checks; the only request-time write outside app operations is
+the configured OAuth resource row (see [OAuth](../../handbook/guides/oauth.md)).
+Verify cutover with actual app tests.
+
+Preserve the app router, verified identity and native resources. For selected
+Admin, follow the [native guide](../../handbook/guides/native-admin.md) for its
+application-built bundle and service composition.
+Do not import old `/spec`, `/core` or runtime surface APIs. Review data/role
+migrations explicitly; full cross-target int64 parity and automated transfer
+are not this release's upgrade contract.
+
+## Partial adoption in TypeScript/Node
+
+Keep the app's router, pool/handle, identity and frontend. Declare only the Schemas and operations being adopted; import selected `views/<encoded-name>.ts` or `procedures/<encoded-name>.ts`, then call `(appHandle, verifiedCaller, validatedInput)`. Bun.SQL and postgres.js fit directly; [node-postgres can adapt](../../handbook/guides/postgres-adapters.md). No Admin/auth/surface module is required for direct queries.
+
+Existing tables need explicit migration into the declared storage shape, including system columns and constraints. Initial schema.sql must not be applied over an occupied database. Rehearse on a copy and test scope, TTL, publication, OCC and persisted state with the app's own identity.
+
+Writes use Store or declared Procedures; never raw SQL writes to adopted collections. Use internal Views for joins, aggregates, OR and reusable reads. Store findById/find/first remain useful for simple AND lookups in existing handlers.
+
+Direct declared Schema-column outputs in Views and SQL Procedure `RETURNING`
+keep their authored field names; explicit aliases keep SQL casing rules. Store
+rows and nested SQL relations use storage names. Boundary validators support a
+permissive `format: email` check (one `@`, non-empty parts, no whitespace). For
+LEFT JOIN paging, join on the joined Schema's id or single-field unique key and
+keep the base indexed, non-null order/id tuple. Generation always emits `Handlers`
+(empty without ref Procedures); pass `handlers` at `adminBindings()`, generated REST/MCP options and
+`webmcpRoutes(catalogue, tools, handlers)`, as the app shell does.

package/docs/skills/media-gc/SKILL.md

@@ -1,41 +1,65 @@
 ---
 name: media-gc
-description: Audit and safely remove stale, uncommitted public media uploads from a Mantle Cloudflare R2 bucket. Use when a Mantle operator asks to inspect or clean orphan media objects left after create_media_upload without commit_media_upload.
+description: Audit and safely remove stale, uncommitted media uploads from a Mantle 0.2 Cloudflare R2 bucket. Use when an operator asks to inspect or clean objects left under uploads/ by an upload that was created but never committed.
 metadata:
   source: "@aotter/mantle"
   sourcePath: docs/skills/media-gc/SKILL.md
-  applies_to: mantle grammar v0.1
+  applies_to: mantle 0.2
   projection: package
   projectionReason: Destructive remote object deletion and Cloudflare-specific; opt-in only.
 ---
 
 # Mantle Media GC
 
+## Generated native applications (alpha.7 and later)
+
+If the installed README describes generated native queries, read
+`docs/handbook/cloudflare/media-r2.md` and app-owned site/media wiring instead of Core storage
+options. Resolve the exact configured bucket and declared purposes. The
+`uploads/` candidate audit below still applies. Committed copies live under
+`committed/` and must never be candidates. Attempt-isolated committed copies
+retained after an uncertain DB outcome require reconciliation with live DB
+references before any separately authorized cleanup.
+
 Use the connected Cloudflare API. Audit by default; delete only the exact
 objects approved by the user.
 
 ## Preflight
 
-1. Read the project's Wrangler config and Mantle config. Resolve the R2 bucket
-   binding, bucket name, and declared public media purpose names.
+1. Read `wrangler.jsonc`, the app-owned entry (`src/worker.ts` by default,
+   or the generation command's `--entry`) and its media wiring. Resolve the R2
+   bucket that `r2MediaStorage` uses and the media purpose names in
+   `siteDefaults.media.purposes` selected by `--site`.
 2. Confirm the exact Cloudflare account and bucket. If either is ambiguous,
    ask; never choose by name similarity.
 3. Use the Cloudflare OpenAPI search before execution to resolve the current
    R2 List Objects and Delete Objects endpoints. If the connected account lacks
    access, stop. Do not create, request, or store credentials.
-4. Stop when the project has no public R2 media binding or no declared purpose.
+4. Stop when the service passes no `r2MediaStorage` or declares no purpose.
+
+## How 0.2 lays out media
+
+`POST /admin/api/media/uploads` issues presigned PUT URLs that expire after 15
+minutes, for keys under `uploads/<purpose>/<group>/<role>.<ext>`. Commit
+copies each checked object to `committed/<group>/<attempt>/<role>.<ext>` (with
+`committedAt` metadata); the attempt UUID isolates concurrent commits. Upload
+keys are removed after the database commit succeeds, or when a group is
+rejected. An old upload key may also be leftover cleanup from a successful or
+uncertain commit: it is not evidence that the media row is absent. Once expired,
+it cannot create a new asset. Objects outside `uploads/` are never candidates;
+reconcile attempt copies separately with live database references.
 
 ## Audit
 
 For each declared purpose, list up to 1,000 objects per page under the exact
-`<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
+`uploads/<purpose>/` prefix. Use the API cursor until `is_truncated` is false.
 
 An object is a deletion candidate only when all conditions hold:
 
 - `last_modified` is more than 24 hours old;
 - `custom_metadata.committedAt` is absent or empty;
-- the key matches the exact Mantle layout
-  `<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|svg)`,
+- the key matches the exact upload layout
+  `uploads/<purpose>/<group>/(primary|alternate|fallback).(png|jpg|webp|avif|gif|bin)`,
   where `<purpose>` is declared by this project and `<group>` contains only
   letters, digits, `_`, or `-`.
 
@@ -65,8 +89,8 @@ filenames, public URLs, signed URLs, or secrets.
 
 - Don't create a Worker, Cron Trigger, lifecycle rule, D1 table, or local script.
 - Don't use prefix deletion or empty-bucket operations.
-- Don't delete private-media buckets or objects outside declared purpose
-  prefixes.
+- Don't delete objects outside `uploads/<declared purpose>/`, and never
+  committed media.
 - Don't treat missing pagination pages, metadata, or permissions as an empty
   result.