@aotter/mantle 0.1.4 → 0.2.0-alpha.1

package/docs/adapter-guide.md

@@ -1,222 +0,0 @@
-# Adapter implementation guide
-
-This guide is the fresh-developer entry point for implementing a new mantle platform adapter.
-
-Read this with [ADR-0019](adr/0019-sealed-manifest-runtime-pipeline.md). The source of truth for TypeScript shapes is `packages/mantle-runtime/src/domain/port/`.
-
-Adapter packages live under `packages/adapters/<platform>/` using a plural `adapters` bucket. The npm package names stay unchanged, for example `@aotter/mantle-cloudflare`. Keep adapters in this monorepo until the runtime/spec API is stable enough that coordinated releases across separate repositories would not create version skew for consumers.
-
-## Required storage boundary
-
-A storage adapter prepares one `RuntimePlan` into semantic ports:
-
-| Contract | Source | Cloudflare example |
-|---|---|---|
-| `MantleStorageAdapter` / `PreparedMantleStorage` | `packages/mantle-runtime/src/domain/port/MantleStorageAdapter.ts` | `SqliteMantleStorageAdapter` over `D1DatabaseDriver` |
-| `EntryRepository & EntryReader` | Existing semantic content ports | `DatabaseEntryRepository` supplied by the SQLite adapter |
-| `ViewQueryExecutor` | `packages/mantle-runtime/src/domain/port/ViewQueryExecutor.ts` | `SqliteViewQueryExecutor` |
-
-`DatabaseDriver` is only the reusable SQLite/D1 implementation seam. A
-PostgreSQL, MongoDB, or application-owned-table adapter implements the semantic
-ports directly; it does not emulate D1 and needs no mapping DSL. Platform types
-such as `D1Database`, Postgres pools, and Mongo clients remain in adapter code.
-
-## Optional capabilities
-
-Optional ports are enabled only when a feature needs them:
-
-| Contract | Source | Required when |
-|---|---|---|
-| `MediaStorage` | `packages/mantle-runtime/src/domain/port/MediaStorage.ts` | The adapter exposes admin/MCP media upload flows. |
-| `DeferredHookDispatcher` | `packages/mantle-runtime/src/domain/port/DeferredHookDispatcher.ts` | The adapter wants at-least-once queue delivery for `after_*` lifecycle hooks. |
-
-Test seams such as `Clock` and `IdGenerator` are injectable through `createMantleRuntime`, but normal adapters do not need custom implementations.
-
-Deferred delivery is an optional, versioned wire contract. Queue acceptance is
-not atomic with the entry write; adapters must preserve the supplied event id,
-validate untrusted messages before dereferencing them, surface handler failures
-to their retry mechanism, and document poison-message/DLQ behavior. See
-[Deferred lifecycle hooks on Cloudflare Queues](deferred-lifecycle-queues.md)
-for the reference implementation and exact guarantees.
-
-## Storage preparation
-
-Compile before deployment preparation, then pass only the sealed plan:
-
-```ts
-import {
-  bootMantleRuntime,
-  SqliteMantleStorageAdapter,
-} from "@aotter/mantle-runtime";
-
-const storage = new SqliteMantleStorageAdapter(db, siteDefaults);
-const runtime = await bootMantleRuntime({
-  plan,
-  storage,
-  handlers,
-  ports,
-  deployment: {
-    reservedHttpPathPrefixes: selectedCapabilities.flatMap(
-      (capability) => capability.reservedHttpPathPrefixes,
-    ),
-  },
-});
-```
-
-`bootMantleRuntime` performs one attempt and derives Procedure readiness from
-the supplied handlers. The platform adapter remains responsible for lazy boot,
-promise caching, retry policy, and teardown.
-
-Hosts that need work between preparation and binding may keep the same stages
-public and explicit:
-
-```ts
-const prepared = await prepareDeployment(plan, storage, {
-  handlerNames: Object.keys(handlers ?? {}),
-});
-const runtime = createMantleRuntime({ prepared, handlers, ports });
-```
-
-The prepared revision carries its exact plan, but exposes both `plan` and
-`storage`; it seals the pairing invariant rather than hiding low-level host
-capabilities. Omit `handlerNames` only for a read-only embedding that never
-dispatches Procedures.
-
-The official SQLite adapter runs canonical migrations, materializes one native
-table per Schema, prepares indexes and Views, and skips mutation for an
-unchanged storage revision. A
-custom adapter owns its own preparation and returns application-owned semantic
-ports. Unsupported native View dialects fail before the adapter mutates state.
-
-### Bun embedding
-
-> **Experimental.** The Bun and Vercel adapters may change in a minor
-> release. They cover public Views and HTTP Triggers; the host owns
-> authentication and CSRF, and Auth, Admin and MCP are Cloudflare-only today.
-> Cloudflare is the supported host.
-
-`@aotter/mantle-bun` is the minimal SQLite reference: pass an application-owned
-`bun:sqlite` `Database` and a compiled `RuntimePlan` to `createBunMantle()`.
-Its `handle()` returns `null` for sibling routes and a Web-standard `Response`
-for manifest-declared public Views and HTTP Triggers. The host owns
-`Bun.serve`, database shutdown, authentication, and CSRF policy; the adapter
-prepares the semantic revision once and retries only after failed preparation.
-
-### Vercel Functions embedding
-
-`@aotter/mantle-vercel` accepts a compiled plan plus any application-owned
-`MantleStorageAdapter` and reuses the same public View/HTTP Trigger transport as
-Bun. It maps deferred work to Vercel Functions `waitUntil` and otherwise leaves
-the Web Handler, auth/CSRF, and route composition to the application. The
-optional `/libsql` subpath adapts a caller-owned remote Turso/libSQL client to
-the canonical SQLite chain; the default entry has no database-vendor policy.
-Vercel's read-only filesystem and writable `/tmp` are never durable state.
-
-### Browser IndexedDB embedding
-
-`@aotter/mantle-indexeddb` implements the same required semantic storage ports
-over one application-owned IndexedDB database. It keeps browser globals out of
-Runtime Core, supports declarative Views with a documented O(n) collection
-scan, and exposes `deleteDatabase()` only on the concrete adapter. The host owns
-database naming, `navigator.storage` persistence requests, active-runtime
-selection, UI invalidation, and any remote synchronization.
-
-## HTTP and MCP surfaces
-
-The runtime is a library, not an HTTP server. A new adapter must mount equivalent framework routes:
-
-| Surface | Adapter responsibility | Cloudflare reference |
-|---|---|---|
-| Runtime HTTP endpoints | Route HTTP Triggers and public View REST endpoints into runtime use cases. | `packages/adapters/cloudflare/src/mount/mountRuntimeEndpoints.ts` |
-| Optional Admin | Supply session/request context and assets to `mantle-admin`; mount only when selected. | `packages/adapters/cloudflare/src/mount/mountAdmin.ts` |
-| Auth endpoints | Own sign-in/session/OAuth metadata through the adapter's Better Auth implementation selected by Admin/OAuth surfaces. | `packages/adapters/cloudflare/src/auth/createAuth.ts` |
-| MCP endpoints | Mount `/mcp/staff` and `/mcp` behind one canonical protected resource. The adapter verifies Better Auth JWTs, normalizes the caller, re-reads the staff D1 role, then dispatches JSON-RPC. | `packages/adapters/cloudflare/src/mount/mountMcp.ts`, `auth/createAuth.ts` |
-
-Auth is not a runtime port. Per [ADR-0014](adr/0014-auth-better-auth-and-multi-tenant-mcp.md), the adapter owns Better Auth wiring and passes authenticated user/staff context into runtime dispatchers. Procedure handlers receive that data through `HandlerContext` in `packages/mantle-runtime/src/domain/model/HandlerContext.ts`.
-
-The adapter must also normalize verified credential metadata into
-`HandlerContext.auth` (`credential`, opaque `credentialId`, optional
-`clientId`, scopes). Platform-native session/OAuth verification stays in the
-adapter. A narrow adapter extension seam may let consumer code verify its own
-API-key or personal-token formats, but credential storage/issuance must not
-become a runtime port. The Cloudflare reference is
-`mount/resolveCaller.ts`; consumer usage is documented in
-[API and MCP authorization](examples/cf-primitives-guarded-api.md).
-
-Minimum HTTP behavior for a full adapter:
-
-- Route manifest HTTP Triggers to `runtime.invokeProcedure`.
-- Route `GET /api/views/<name>` to `runtime.executeView`.
-- Mount admin content APIs with session/role checks before calling runtime content use cases.
-- Serve selected Admin SPA assets through `AdminAssetServer`, with an SPA catchall for client-side routes.
-- Mount public render routes and markdown mirrors when the application exposes public pages.
-- Translate runtime diagnostics and validation failures into stable HTTP JSON responses instead of throwing raw errors.
-- Evaluate target auth and dynamic guards through the runtime use cases; do
-  not duplicate guard logic in HTTP handlers.
-
-For the Cloudflare adapter, public rendering requires three matching consumer
-inputs: `mountPublicRoutes(...)` route declarations, a `TemplateRegistry`
-passed through `MantleCloudflareConfig.templates`, and a `publicPathResolver`
-passed through `MantleCloudflareConfig.publicPathResolver`. Omitting public routes is valid for a headless
-consumer; mounting every Schema automatically is not, because some collections
-are private even when they contain a slug.
-
-`TemplateRegistry` and `createPublicPathResolver` come from
-`@aotter/mantle-web`. Other adapters can call `createMantleWeb(runtime)` and map
-its document operations into their own routing and cache conventions.
-
-### HTTP cache contract
-
-Keep responses private by default. For Cloudflare, apply the final policy after
-all routes and preserve only explicit anonymous public opt-in. Follow the
-[public cache contract](handbook/cloudflare/public-web.md#cache-contract) and the
-[performance harness](performance-harness.md#cache-contract) for verification.
-
-Minimum auth/MCP behavior:
-
-- Provide Better Auth-compatible sign-in/session routes for the platform.
-- Validate `/mcp/staff` requests with the staff D1 admin role (`owner`/`editor`/`contributor`).
-- Validate `/mcp` requests with any authenticated session (D1 role check is surface-driven, not OAuth-scope-driven — claude.ai rejects colon-shaped scopes).
-- Advertise a single non-colon scope (default `["mcp"]`) in `scopes_supported`. Per-surface enforcement happens server-side in the apiHandler.
-- Build `McpAuthContext` from the validated session and pass it to `McpJsonRpcDispatcher`.
-- Build Procedure/View `HandlerContext` with `user`, live `staff`, normalized
-  `auth`, adapter `env`, and optional `waitUntil`.
-- Re-read mutable staff role for each protected REST/MCP invocation. Token or
-  consent-time role snapshots are not an authorization boundary.
-- Keep `tools/list` filtering as UX only; route every `tools/call` through the
-  same auth evaluator and guard runner used by REST.
-
-## Static assets
-
-`AdminAssetServer` belongs to optional `@aotter/mantle-admin`. Headless Core
-storage preparation and binding do not accept or require a static asset port.
-
-## Implementation checklist
-
-- [ ] Run `runStorageConformance` from `@aotter/mantle-runtime/testing/storage`
-      against a disposable prepared-storage factory. See the
-      [Runtime conformance guide](../packages/mantle-runtime/README.md#storage-adapter-conformance)
-      for coverage, cleanup, locale setup, and remaining adapter-specific tests.
-- [ ] Implement `MantleStorageAdapter` returning existing semantic ports, or reuse `SqliteMantleStorageAdapter` with an already-owned handle.
-- [ ] Call `bootMantleRuntime()` once per semantic revision, or explicitly prepare before binding.
-- [ ] Mount HTTP Trigger and View REST surfaces.
-- [ ] Mount admin/public render routes and admin SPA assets.
-- [ ] Provide adapter-owned Better Auth wiring and session helpers.
-- [ ] Normalize session/OAuth and any consumer credential seam into
-      `HandlerContext.auth`; never put raw credentials in runtime context.
-- [ ] Mount `/mcp/staff` and `/mcp` behind one resource-bound token verifier. Enforce the live staff role inside the apiHandler.
-- [ ] Preserve the HTTP cache contract: private by default; explicit anonymous 200 `GET`/`HEAD` public opt-in only.
-- [ ] Prove one guarded target has identical REST/MCP outcomes, including
-      mutable revocation on the next call.
-- [ ] Add optional `MediaStorage` or `DeferredHookDispatcher` only when the adapter supports those features.
-- [ ] For deferred hooks, document at-least-once delivery, idempotency,
-      message limits, retries/DLQ, and the non-transactional write-to-enqueue gap.
-- [ ] Verify the runtime package still has no platform-specific imports.
-
-## Current non-goals
-
-- Do not add `SessionRepository`, `OAuthVerifier`, `UserRepository`, or `StaffRepository` runtime ports. Those were pre-ADR-0014 concepts and are not part of the current adapter contract.
-- Do not add API-key, personal-token, transaction, billing, or entitlement
-  repositories to Core. They are consumer state behind the adapter resolver
-  and guard Procedure.
-- Do not generalize `DatabaseDriver` for PostgreSQL/MongoDB or add a mapping DSL. Implement semantic ports; SQLite/D1 alone reuse the canonical SQL chain.

package/docs/agent-prompts.md

@@ -1,102 +0,0 @@
-# Task-specific agent prompts
-
-Cold start from GitHub or a marketplace host is the install skill:
-
-```sh
-npx skills add aotter/mantle
-```
-
-Copy one block into a coding agent after that skill is present. Paths below
-are relative to the Mantle docs root: `node_modules/@aotter/mantle/docs/`
-after `@aotter/mantle` is installed. A standalone `skills add` installation
-contains only the selected skill, not these docs.
-`npx --no-install mantle --help` is the layered CLI overview; it mirrors the
-authoring docs. A live `/mcp` catalog mirrors the Manifest → RuntimePlan, not
-the CLI. Resolve only missing requirements first; do not assume a host. There is no `mantle create`. Empty `generate` fails until
-manifests exist. Admin is opt-in.
-
-### Interview then build
-
-```text
-Interview me about the service: host, who uses it, whether humans need a
-Dev UI, and whether we only embed Spec/Runtime. If the install skill is
-missing, run npx skills add aotter/mantle. Read the
-installer-reported skill, choose and install an exact SDK version, then read
-its embedded skills/install/SKILL.md,
-run npx --no-install mantle --help, and
-read handbook/start/overview.md.
-Use examples/README.md as the examples index; copy builtin-* Manifests only
-(not cf-primitives-*). Implement locally first. Take only the surfaces we
-chose. For Spec-only use, skip Runtime and code generation. For a Worker
-without Admin, follow examples/host-minimal-worker/. For a Worker with
-Dev UI, follow examples/host-local-admin-otp/README.md. ChatGPT Sites only
-if I name that host. No mantle create. Pin all @aotter/mantle* packages
-to one exact version.
-```
-
-### Embed Runtime with typed APIs
-
-```text
-Read handbook/start/project-and-cli.md and npx --no-install mantle --help.
-Pin @aotter/mantle at the exact version we agree, author manifests for
-this existing host, then run mantle generate. Embed
-the typed binding from .mantle/generated/mantle.ts into the current
-system. Do not add Admin, mantle-admin-ui, a visitor frontend, or a
-Cloudflare adapter unless I ask. Do not invent a default Schema.
-```
-
-### Minimal API service locally
-
-```text
-Read handbook/start/quickstart-worker.md and examples/host-minimal-worker/.
-Author a Cloudflare Worker from that official example or from scratch:
-one Schema, one public View (copy the contract, not the tree wholesale).
-Pin every @aotter/mantle* package to the same exact version. Run
-pnpm install && pnpm generate && pnpm dev (or wrangler dev --local).
-Probe GET /api/views/<name> with curl. GET / may 404. Do not install
-Admin or wrangler ASSETS unless I ask.
-```
-
-### Full local Dev UI (opt-in)
-
-```text
-I want the optional Admin / Dev UI. Read examples/host-local-admin-otp/README.md
-(the procedural SSOT) and the thin pointer at handbook/start/quickstart-admin.md.
-Interview me for a bootstrap owner email, then follow that example locally.
-Prefer 127.0.0.1 over localhost. After pnpm check / smoke, restore .dev.vars
-from .dev.vars.example before pnpm dev.
-```
-
-### Later layer: MCP or public web (opt-in)
-
-```text
-Do not add Admin unless it is already in this project. Read
-handbook/concepts/mcp-and-agents.md and/or
-handbook/cloudflare/public-web.md. Add only the surface I name: MCP
-Triggers at /mcp or /mcp/staff, or optional @aotter/mantle-web
-composition. Keep Core adapter-neutral. Probe the new route; do not
-claim Auth or Admin works from a public 200.
-```
-
-### Mantle on ChatGPT Sites, including media
-
-Use only when the user names ChatGPT Sites as the host.
-
-```text
-Build with ChatGPT Sites; use Mantle for content management and publishing.
-Read handbook/chatgpt-sites/index.md and examples/host-chatgpt-sites/README.md.
-Use that runnable host as a reference and install its pinned
-dependencies from the registry. Derive Schema, View,
-Procedure and Trigger from my requirements and check the Admin editor/picker and public
-projections against them. Request both Sites D1 and R2 when my workflow
-includes uploads. Bind the R2 media port, declare media.purposes, and keep
-the same-origin PUT and committed-only public GET checks. Pin every
-@aotter/mantle* dependency to one exact version. Run the local smoke,
-show a draft-to-publish walkthrough, then save and deploy through Sites when
-requested. Verify the deployed owner/member role, R2 upload, published page, and anonymous draft 404. Treat public read-only
-MCP, Admin WebMCP, and staff OAuth MCP as separate acceptance gates; never
-claim staff MCP from a working browser session or connector URL alone.
-```
-
-
-[Back to the Core README](../README.md#for-engineers-and-agents).

package/docs/api-mcp-authorization.md

@@ -1,5 +0,0 @@
-# API and MCP authorization
-
-See [Authorization](handbook/reference/authorization.md),
-[Guarded API access](examples/cf-primitives-guarded-api.md), and
-[OAuth resource primitives](handbook/cloudflare/authentication.md#oauth-resource-primitives).

package/docs/auth-hosting-model.md

@@ -1,166 +0,0 @@
-# Auth Hosting Model
-
-Mantle treats authentication as a runtime capability, not a paywall on
-basic login. The split is:
-
-- **Mantle SDK** gives every generated site the primitives needed to
-  run its own auth.
-- **Mantle's conventional Cloudflare adapter** runs the generated site's
-  selected self-hosted or Mantle Platform hosted client configuration.
-- **The application owner/host** declares the explicit auth mode and provider
-  configuration.
-- **Mantle Platform** can sell hosted identity, provider setup, email,
-  and billing convenience for site owners who do not want to operate
-  those pieces.
-
-This document is the source of truth for the product and SDK boundary.
-Do not duplicate this model in starter handoff copy or landing prose;
-link here and keep downstream docs short.
-
-## Free Self-Hosted Auth
-
-A free Mantle site can run every login method the SDK exposes through
-`createAuth()`:
-
-- social OAuth providers supported by Better Auth;
-- provider-specific options through Better Auth's native `socialProviders` types;
-- email OTP;
-- magic link;
-- passkey or another Better Auth method through the raw `plugins` path when the
-  application owns its callback and UI;
-- first-party same-domain or same-parent-domain SSO when the site owner
-  controls every participating subdomain.
-
-The site owner supplies their own provider client ids/secrets,
-transactional email sender, DNS, cookie policy, and operational
-maintenance. Mantle must not block self-hosted login behind a paid
-feature flag.
-
-## Hosted Platform Auth
-
-Paid hosted auth is a convenience and operations product. The value is
-that Mantle Platform can:
-
-- hold OAuth provider configuration;
-- hold email provider credentials;
-- send OTP and magic-link email;
-- manage deliverability and provider rotation;
-- register generated sites as clients;
-- check billing/license entitlements before hosted capabilities are
-  enabled;
-- expose a stable hosted identity broker for generated sites.
-
-The generated site still owns local grants, member records, content,
-orders, forms, and legal copy. Platform returns identity. The site maps
-that identity into `ctx.user`, `ctx.staff`, and its own grant model.
-
-## Same Parent Domain SSO
-
-When the apps share a parent domain that the same party controls, SSO
-can use browser cookies:
-
-```ts
-createAuth({
-  // ...
-  trustedOrigins: ["https://mantle.tools", "https://www.mantle.tools"],
-  cookiePrefix: "mantle-platform",
-  crossSubDomainCookies: {
-    enabled: true,
-    domain: "mantle.tools",
-  },
-});
-```
-
-Use this only for a trusted first-party app family, for example
-`platform.mantle.tools` and `mantle.tools`.
-
-`cookiePrefix` is required whenever more than one Better Auth app can
-write cookies under the same parent domain. Without it, Platform and
-Landing can overwrite each other's default Better Auth cookie names.
-
-`trustedOrigins` is a Better Auth auth-flow trust list. It is not a
-general API CORS policy and must not be documented as one.
-
-## Customer Domain SSO
-
-Shared cookies do not work across different registrable domains:
-
-```text
-platform.mantle.tools  ->  customer.com
-```
-
-Browsers will not send a `mantle.tools` cookie to `customer.com`. For a
-customer-owned domain, hosted auth must use OAuth/OIDC:
-
-```text
-customer.com/login
-  -> platform.mantle.tools/api/auth/oauth2/authorize
-  -> user signs in with Platform-supported methods
-  -> customer.com/api/auth/callback/mantle
-  -> customer.com verifies the authorization response
-  -> customer.com creates its own local session
-```
-
-That local session is the customer's site session. Platform remains the
-identity broker and entitlement authority; it does not become the
-customer site's member database or authorization system.
-
-## Landing Provisioning Split
-
-Landing should branch before GitHub or Cloudflare side effects:
-
-- **Continue free**: commit a self-hosted auth-ready site with docs,
-  env placeholders, and the user's own provider setup path.
-- **Use hosted auth**: check Platform entitlement, register the site as
-  a Platform auth client, and commit the generated site's Platform auth
-  client config.
-
-Landing can probe Platform staff/session state, but provisioning's
-GitHub OAuth token is still Landing-owned unless a separate token
-handoff design is introduced.
-
-The conventional hosted-auth client wiring belongs in Core's Cloudflare
-adapter. Applications declare its environment bindings; a provisioning host supplies an
-allocated client. A site can still replace Auth construction through
-`createMantleWorker({ auth })` when it needs a different curated identity
-design. Core continues to own the normalized manifest/runtime credential
-vocabulary (`ctx.user`, `ctx.staff`, `ctx.auth`) and guard orchestration.
-
-## API and MCP Authorization
-
-Login hosting and business API authorization are related but separate. Core
-provides a normalized verified-credential context (`ctx.auth`), closed scope
-predicates, one Cloudflare consumer credential resolver seam, and a
-Procedure-backed guard that REST and MCP both execute. A generated site owns
-API keys, personal tokens, grants, transactions, subscriptions, and the guard
-handler that checks current business state.
-
-Mantle Platform may be the identity or OAuth token authority for a hosted
-flow. That does not make token claims the generated site's live membership or
-entitlement authority. The target site's guard reads its authoritative state
-on every call. See [API and MCP authorization](examples/cf-primitives-guarded-api.md) for
-the exact public API and four consumer examples.
-
-## SDK Surface Rule
-
-Mantle owns only integration fields with a real Mantle use case. Method
-configuration uses Better Auth's official provider/plugin option types; do not
-copy those unions or add a generic `Partial<BetterAuthOptions>` deep merge.
-
-The current first-party SSO use case justifies these optional fields on
-`CreateAuthConfig`:
-
-- `trustedOrigins`
-- `crossSubDomainCookies`
-- `cookiePrefix`
-
-The cross-site API use case additionally justifies these fields and facades:
-
-- native generic OAuth `authorizationUrlParams`, `tokenUrlParams`, and
-  `refreshTokenParams` for RFC 8707 `resource`
-- OAuth provider `resources` and the curated `mcpResource`
-- `Auth.getProviderAccessToken(request, providerId)`
-- `Auth.verifyOAuthAccessToken(tokenOrRequest, { audience, scopes })`
-
-Generic OAuth providers use Better Auth 1.7's official `GenericOAuthConfig`,
-standard social sign-in and `/api/auth/callback/:id` path.

package/docs/cloudflare-low-level-composition.md

@@ -1,5 +0,0 @@
-# Cloudflare low-level composition
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/low-level-composition.md`](handbook/cloudflare/low-level-composition.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/consumer-onboarding-audit.md

@@ -1,65 +0,0 @@
-# Consumer onboarding audit for 0.1.3
-
-Scope: source skill install → pinned npm package → CLI → generated skills and
-handbook → application manifest and Admin customization. This is maintainer
-evidence, not a release announcement. Baseline: develop `b90cebbd`, package
-version `0.1.3-alpha.5`; the package version alone does not identify unreleased
-commits on develop. Tracking: [#1042](https://github.com/aotter/mantle/issues/1042).
-
-## Clean source install
-
-Executed in an empty temporary directory:
-
-```sh
-npx --yes skills add aotter/mantle --skill install --agent codex --yes
-```
-
-Observed output: repository cloned, **7 skills found**, **1 selected**, copied
-to `./.agents/skills/install`. `skills-lock.json` records source `aotter/mantle`,
-source type `github`, and source path `skills/install/SKILL.md`. The installed
-file's hash in that lock was
-`8a6fd26aea97ae8bdf3e05fef22196c247b3f95aa049204a6ac51259d87e4e29`.
-No SDK, handbook or application is installed by that command. The explicit
-Codex and noninteractive flags make the audited destination reproducible;
-other selected agents/global scope can use another destination.
-
-This source install follows the repository's default ref. It does not test the
-unreleased edits in this PR or establish an npm version. The packed-consumer
-check below tests this branch's shipped instructions separately.
-
-## White-box path and fixes
-
-| Stage / owner | Finding before this change | Correction |
-|---|---|---|
-| README → external skills installer | Prompt told the agent to read `skills/install/SKILL.md` and `docs/agent-prompts.md`, neither installed there. | Read the installer-reported destination, then the installed SDK's embedded docs. |
-| `skills/install/SKILL.md` | Bootstrap Git instructions did not explicitly hand off to the installed package's own install skill; `docs/...` root was implicit. Host interview was repeated. | Explicit package-root resolution and version authority; ask only for missing requirements. |
-| Install → CLI | It was possible to try the local CLI before installing Core; `generate` in an empty directory fails rather than creating a project. | Spell out package installation before CLI and manifest authoring before generation. |
-| Quickstart versions | Floating `latest` dependency examples contradicted exact-pin advice. | Resolve the requested channel once and save exact Mantle versions before the first build. |
-| `mantle skills` | Correctly projected four project skills, but success output did not tell the agent what to read next. | Print the projected develop skill and installed handbook entry. Document overwrite, drift and opt-in behavior. |
-| `sync-package-docs.mjs` → npm `files` | Docs and all seven skills already shipped; presence checks did not protect the new entry paths or exercise projection from the tarball. | Assert handbook/skill files and byte-identical `.agents`/`.claude` projection in the existing packed-consumer check. |
-| View concepts → grammar/runtime | Concepts denied internal Views and recommended SQL for every new View; reference `surface` table omitted `internal`. SQL admission text was stale. | Match implemented surfaces, typed declarative reads, SQLite admission sandbox and native-dialect limits. |
-| Manifest reference | View's allowed spec keys omitted `cache`; Schema list-column prose omitted native columns. | Reconcile with parser and Admin UI checker. |
-| Plugin/update skills | Assumed conventional source paths, missed regeneration after plugin manifest edits, and treated every View as publicly callable. | Use actual project paths, regenerate the plan, verify the declared surface and distinguish stable index from target prerelease docs. |
-| Feature discovery | No task-to-manifest capability map or usable human entry; reference was buried after host-specific sections. | Add overview, capability table and task guides; move reference before host guides without breaking existing URLs. |
-| Typed query discovery | APIs existed but lacked a complete internal-View calling example or clear reader authorization distinction. | Explain generated params/results, runtime `result` versus REST `data`, SQL `unknown`, indexed reader limits and plan-based emission. |
-| Admin requests → theme/develop skills | Theme skill targeted visitor source; no routing from an Admin request to manifest-controlled presentation. | Route to Admin guide, with Schema/View/Procedure rendering table and supported customization ceiling. |
-| Auth operations | Store-bound session cache behavior existed in code/ADR but was missing from the handbook. | Explain store identity, preparation order and KV propagation limits. |
-
-## Verification and regression coverage
-
-- `packages/mantle-spec/test/handbook-contract.test.ts`: complete handbook YAML
-  examples parse and validate; navigation covers pages; relative links resolve.
-- `packages/mantle/test/cli/generate.test.ts`: extracts the new internal-View
-  YAML and TypeScript directly from the handbook, generates bindings and runs
-  strict TypeScript checking on the real example.
-- CLI surface/projection tests assert the concrete next-read destinations;
-  existing drift checks verify `--check` is read-only.
-- `scripts/check-optional-packages.mjs`: packs and installs the actual Core
-  tarball, checks embedded entry pages/skills, runs `skills` and `skills --check`,
-  and compares each project projection byte-for-byte with the installed package.
-- Repository gate: `pnpm check`. Exact execution results and any environment
-  limitations are recorded in the PR, rather than frozen as a future guarantee.
-
-No npm publish, tag, deployment or grammar change is part of this audit. Source
-skill consumers receive the corrections only once they reach the installed Git
-ref; npm consumers receive them only in a package built from the corrected tree.

package/docs/deferred-lifecycle-queues.md

@@ -1,5 +0,0 @@
-# Deferred lifecycle hooks on Cloudflare Queues
-
-This guide moved into the handbook: [`docs/handbook/cloudflare/deferred-hooks-queues.md`](handbook/cloudflare/deferred-hooks-queues.md).
-
-The handbook ships inside the `@aotter/mantle` package under `node_modules/@aotter/mantle/docs/handbook/` and describes the installed release.

package/docs/design-atoms.md

@@ -1,16 +0,0 @@
-# Manifest reference has moved
-
-The version-matched [handbook](handbook/reference/manifest.md) is the single
-grammar reference. This compatibility URL contains no duplicate grammar.
-
-- [Four atoms](handbook/concepts/four-atoms.md)
-- [Schema](handbook/reference/schema.md)
-- [View](handbook/reference/view.md)
-- [Procedure and builtin handlers](handbook/reference/procedure.md)
-- [Trigger](handbook/reference/trigger.md)
-- [Authorization](handbook/reference/authorization.md)
-- [Diagnostics](handbook/reference/diagnostics.md)
-
-Builder consumers must load these pages from the same installed SDK as their
-runtime. The old Markdown section headings are retired; see
-[#837](https://github.com/aotter/mantle/issues/837).