@aotter/mantle 0.1.2-alpha.6 → 0.1.2

package/docs/handbook/sites/equipment-checkout.md

@@ -0,0 +1,231 @@
+---
+description: "Design a non-payment equipment checkout workflow with Mantle custom handlers, Sites identity and storage, and external Slack notifications."
+---
+# Equipment checkout and external notifications
+
+**Turn a ChatGPT Site into an operational tool, with a Mantle-managed back
+office and application-owned business rules.**
+
+A production crew, school media room, or shared studio needs to know who has
+each camera kit, who approved the loan, and when it should come back. A form
+alone cannot prevent two people reserving the last kit. A notification alone
+cannot enforce who may approve or return it.
+
+This guide describes a non-payment application of the Sites integration:
+members request equipment, staff approve and record handover, and a custom
+handler notifies an equipment desk in Slack. There are no prices, deposits,
+checkout charges, invoices, or payment-provider credentials.
+
+**Status: implementation guide, not a shipped equipment app.** Start from the
+[runnable article host reference](../../examples/host-chatgpt-sites/README.md).
+That reference does not include these manifests, loan handlers, or a Slack
+integration. The [verification boundary](#verification-boundary) distinguishes
+the earlier deployment experiment from this proposed application.
+
+## A useful first workflow
+
+1. A member signs in with ChatGPT and requests a camera kit for tomorrow
+   afternoon. The server derives the borrower from the verified identity, not
+   a submitted user ID.
+2. An owner or editor reviews the request in Mantle Admin. Approval claims the
+   kit for that time slot only if it is still available. A pending request does
+   not promise availability.
+3. The approval commits, then the application attempts a Slack notification to
+   the equipment desk. The message identifies the request and links to the
+   authenticated Admin page; it contains no borrower email or private notes.
+4. Staff record pickup and return. A return records condition and releases the
+   current checkout once. A damaged unit becomes unavailable for new claims.
+5. Staff can inspect pending requests, reservations, checked-out equipment,
+   overdue returns, and notification failures in Admin Views.
+
+Keep the first implementation bounded: identify individual kits, allow one kit
+and one fixed half-day slot per request, and define slots in the team's chosen
+time zone before storing UTC bounds. Multi-kit carts, arbitrary overlapping
+intervals, recurring bookings and automated reminders are separate extensions.
+An overdue checkout blocks physical handover to the next borrower even when a
+future reservation exists; time passing is not evidence of a physical return.
+
+## What Mantle owns, and what your application owns
+
+| Surface | Contract |
+|---|---|
+| Equipment catalog | An `equipment` Schema with title, description and an R2 media asset reference. Use the runtime's content use cases for authoring. |
+| Operational state | Application-owned D1 loan, unit-availability, reservation-claim and notification tables with reviewed migrations. Do not write Mantle-owned Schema tables directly. |
+| Staff reports | Staff-only SQL Views over the application tables. SQL Views are specific to SQLite/D1, not a portable storage guarantee. |
+| Business operations | Typed Procedures with `handler: { kind: ref, ref: ... }` for request, approval, rejection, pickup, return, cancellation and notification retry. |
+| Staff controls | Explicit staff MCP Triggers expose appropriate Procedures to Admin operations/WebMCP; `requires.auth` checks owner/editor roles on every invocation. This does not mount remote staff OAuth MCP. |
+| Member pages | Application routes show only the current member's requests and call the same runtime Procedure pipeline for mutations. |
+| External integration | Application handler code calls a configured Slack incoming webhook with server-side credentials. Core needs no Slack-specific port or manifest kind. |
+
+Keep approval, custody and delivery status separate. For example, a loan may
+be `requested`, `approved`, `checked_out`, `returned`, `rejected` or `cancelled`,
+while its notification is `pending`, `sent`, `failed`, `unknown` or
+`not_configured`. A Slack failure must not turn an approved loan into a rejected
+one. Do not expose generic CRUD for operational state transitions.
+
+If you choose Mantle operational Schemas for query mirrors instead, declare
+root `schema.readOnly: true`, maintain them through runtime use cases, and
+define reconciliation with the authoritative reservation state. Do not add a
+second writable authority just to obtain a sidebar entry; staff Views are
+enough for the first implementation.
+
+## Connect the custom handlers
+
+Follow the existing [Procedure contract](../reference/procedure.md) and
+[low-level host composition](../cloudflare/low-level-composition.md):
+
+1. Author each Procedure's strict input/output schema and authorization
+   requirements. For example, `approve-loan` accepts a request ID and operation
+   ID, requires an owner/editor, and names `approveLoan` as its handler ref.
+   Resolve the kit, borrower, slot and current state from stored data.
+2. Run `mantle generate`. Implement the resulting `MantleHandlers<Env>` map and
+   pass it as `handlers` to `bootMantleRuntime` alongside the sealed plan,
+   existing storage adapter and media port. A ref is a registration key, not a
+   file path or automatic route.
+3. Mount member routes in the application. Bound and validate request bodies,
+   require the existing Sites session, check exact same-origin on browser
+   writes, and construct the runtime context from verified identity. Never
+   accept caller-supplied `staff`, role or borrower identity.
+4. Invoke `bindMantle(runtime).procedures.<generatedName>(input, ctx)` and handle
+   its success/diagnostic result. Do not call the handler function directly.
+   A host-mounted route is an explicit entry point; the Procedure alone does
+   not install it. A manifest HTTP Trigger likewise needs the host's matching
+   transport mounting.
+5. Expose only staff-appropriate operations through staff Triggers. Keep member
+   ownership checks inside handlers too: a role check alone does not prove
+   that the current member owns the request being cancelled or read.
+
+See [Procedures and Triggers](../concepts/procedures-and-triggers.md) for
+declarative transport binding. The Sites host still owns its router, auth and
+external service configuration; Mantle owns validation, authorization and
+dispatch through the sealed plan.
+
+## Make reservations safe under retries and concurrency
+
+Application storage must make approval and the claim for `(unitId, slotId)`
+atomic. Use a database uniqueness constraint for the claim, not a browser
+availability check followed by an unconditional write. When approval involves
+several application-table statements, use a supported atomic D1 batch and
+verify rollback on a conflicting claim. A conflict must not leave an approved
+loan without its claim or a claim without its loan.
+
+Bind every operation ID to its actor and complete business input. Replaying the
+same input returns the prior result; reusing the ID for different input fails.
+Guard transitions against the current state: repeated approval does not claim
+twice, cancellation cannot silently undo checked-out equipment, and repeated
+return cannot increase availability twice. Releasing a claim and changing loan
+state must also commit atomically. Persist the audit record rather than deleting
+the loan to make inventory appear available.
+
+Re-check unit serviceability at approval and pickup. A catalog entry is
+descriptive content, not the authoritative physical stock counter. Staff may
+edit descriptions through Mantle without bypassing the reservation rules.
+
+Do not infer this correctness from the catalog's CRUD tests. Include concurrent
+approval, rollback and late-return scenarios in the application's own tests.
+The earlier single-SKU stock experiment does not validate future time-slot
+reservations.
+
+## Call an external API without coupling it to approval
+
+Start with a single administrator-configured Slack incoming webhook. An owner
+chooses the destination channel and stores `SLACK_WEBHOOK_URL` as a Sites runtime
+secret. It is not a manifest field, browser variable, member-supplied URL or
+committed setting. Keep the URL and provider response details out of logs and
+public diagnostics. Validate the configured HTTPS destination and do not follow
+redirects to arbitrary hosts.
+
+Slack accepts a server-side JSON POST. See its
+[incoming webhook guide](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/)
+for setup, response semantics and errors. The first integration sends a short
+notification, not interactive Slack approval buttons. Those buttons would need
+a separate authenticated callback design and a mapping to Mantle staff identity.
+
+Commit a durable notification record in the **same application-owned D1
+transaction** as approval, then attempt delivery with a bounded timeout. Claim
+the record before sending so concurrent retries do not both send it. Record a
+successful acknowledgement separately from the business result; an accepted
+message does not prove a human read it.
+
+Missing configuration is `not_configured`, not success. Definite provider
+rejection is `failed`; a timeout or crash after sending may mean delivery is
+`unknown`. Show these states and a staff-only retry action in Admin, including
+recovery for an abandoned delivery claim. Retrying an unknown attempt may post
+a duplicate: include the same notification ID and do not promise exactly-once
+delivery. Never roll back the reservation because Slack is unavailable.
+
+The first version attempts delivery after commit in the current request and
+uses **manual staff retry**, not an assumed background scheduler. Sites Queue,
+Durable Object and Cron support remains unverified here; `waitUntil` is not
+durable delivery. Automated reminders require a separately verified host
+capability, not a timer left running in a Worker.
+
+## Verification boundary
+
+The earlier deployed integration experiment established these narrower facts:
+
+- Mantle custom handlers performed server-priced, idempotent single-SKU stock
+  operations on application-owned D1 tables, alongside the existing Admin/R2
+  content flow. Local regression tests covered concurrent oversell and replay.
+- A browser form reached an external provider's **sandbox**, and its signed
+  server callback reached the published Site and updated a test record through
+  the runtime Procedure pipeline. This was not a Worker-originated Slack call.
+- A migration containing SQLite triggers passed local D1 but failed Sites
+  deployment with `incomplete input: SQLITE_ERROR`. A trigger-free conditional
+  SQL/ledger version deployed successfully. This is a deployment observation,
+  not proof that all Sites deployments prohibit SQLite triggers.
+
+The experiment is engineering evidence, **not a payment feature to adopt**.
+[Sites' documented unsupported uses](https://learn.chatgpt.com/docs/sites#understand-limits-and-unsupported-uses)
+include enabling financial transactions. Do not copy payment routes, merchant
+credentials or payment terminology into this example, or infer permission for
+live payments from successful sandbox transport.
+
+Equipment reservations, Worker-to-Slack HTTPS delivery and its failure recovery
+remain implementation and deployed acceptance work. They are not tested merely
+because the underlying host composition or a different provider succeeded.
+
+## Acceptance checklist for your application
+
+- Preserve existing Site identity, audience, content and R2 objects. Follow the
+  [host reference](./host-reference.md) and its supported SDK installation path.
+- Review additive migrations and the Mantle storage fingerprint; leave applied
+  migrations immutable. Test the actual Sites deploy, not only local D1.
+- Verify member ownership, staff role revocation and cross-origin rejection.
+  Keep borrower records out of public Views, public MCP and static artifacts.
+- Race two approvals for one unit/slot: exactly one succeeds. Verify a failed
+  batch leaves no partial approval, claim or notification record.
+- Replay approve/cancel/return operations, including changed-input retries.
+  Check damaged units, overdue handover, and slot/time-zone boundaries.
+- With the secret absent, show `not_configured`. With the configured test
+  channel, verify one actual deployed Worker-to-Slack notification and the
+  matching delivery record. Test rejection, timeout, abandoned claim and manual
+  retry without changing the loan's approved state.
+- Walk through Admin's typed forms, staff Views and row operations with a real
+  second account. Browser WebMCP success is not remote OAuth MCP success.
+
+## Ask your agent to build it
+
+```text
+Extend my existing ChatGPT Site with Mantle equipment checkout. Read the matching
+SDK's docs/handbook/sites/index.md, equipment-checkout.md and host-reference.md.
+Preserve current content, audience and R2 media. This guide is a design, not an
+installed app: implement and test the missing manifests, handlers and routes.
+Start with one identified kit and one fixed half-day slot per request. Include
+member-owned requests, staff approval/pickup/return, atomic reservation claims,
+typed Admin operations, staff reports and an audit trail. Use a server-side
+Slack webhook secret for minimal notifications, with durable delivery records
+and manual retry. If no secret is configured, report that honestly. Do not
+implement payments, remote staff OAuth, or assume DO/Queue/Cron availability.
+Run the acceptance checklist and distinguish local, deployed and untested cases.
+```
+
+## Source
+
+- [Sites integration](./index.md) and [host reference](./host-reference.md)
+- [Runnable article host](../../examples/host-chatgpt-sites/README.md)
+- [Procedure reference](../reference/procedure.md) and [authorization](../concepts/authorization.md)
+- [Sealed runtime ownership](../../adr/0019-sealed-manifest-runtime-pipeline.md)
+- [Schema storage and migrations](../../adr/0024-manifest-native-schema-tables.md)
+- [Slack incoming webhooks](https://docs.slack.dev/messaging/sending-messages-using-incoming-webhooks/)
+- [OpenAI Sites](https://learn.chatgpt.com/docs/sites)

package/docs/handbook/sites/host-reference.md

@@ -0,0 +1,113 @@
+---
+description: "Mantle on ChatGPT Sites: identity, D1, R2 media, public web, MCP boundaries, and deployment checks."
+---
+# ChatGPT Sites host reference
+
+Start with [Mantle on ChatGPT Sites](./index.md) for the supported installation
+path and your first publishing workflow. This reference explains how the
+integration connects Sites hosting and sign-in to Mantle content, staff roles,
+Admin, media, and public web. Keep the application outside the Mantle SDK
+checkout and use matching SDK packages.
+
+Start from the [runnable Sites host reference](../../examples/host-chatgpt-sites/README.md), then replace its **example** manifest with the user's business contract. It contains the matching D1 migrations/fingerprint, R2 upload adapter, local smoke test and build layout. Its browser-backed staff identity is not an OAuth resource-server credential.
+
+## First deployment
+
+1. Inspect the Site's actual hosting manifest and available bindings. Bind D1 before booting Mantle; create and apply the generated immutable D1 migration before publishing. Do not run DDL per request.
+2. Compile the sealed plan (`mantle generate --check`, `mantle validate --phase deploy`) and bind `SqliteMantleStorageAdapter(new D1DatabaseDriver(env.DB), siteDefaults)`. Keep the generated storage fingerprint in sync with the migration.
+3. If Admin is requested, mount `@aotter/mantle-admin` and its prebuilt assets. Use the trusted identity supplied by Sites **only after its ingress has stripped caller-supplied identity headers**. Map the stable per-Site user ID to a Mantle principal; use email only for owner bootstrap/invitation matching, not as a durable ID. Persist staff roles in D1 and re-read them for each privileged request. A Site Viewer is not automatically a Mantle editor.
+4. If public pages are requested, compose `@aotter/mantle-web` over published-only queries. Verify anonymous article HTML, canonical/JSON-LD, Markdown, sitemap and `llms.txt`; a draft must remain 404. Do not assume a successful Admin boot implies a working homepage.
+5. Publish through Sites, then verify the deployed version rather than only a local preview. Test owner, second account, role revocation, public/anonymous reads and every configured binding.
+
+## Media with only an R2 binding
+
+The `MediaStorage` port returns an HTTP `PUT` capability; it does **not** require a presigned S3 URL. An application with `env.MEDIA_BUCKET` can implement the port with `R2Bucket.put/head/get/delete` and return a same-origin upload URL. Bind that implementation as `ports.mediaStorage` **and** declare at least one `siteDefaults.media.purposes` policy; otherwise the Admin library and `create_media_upload` remain disabled.
+
+The application must mount two routes alongside the port:
+
+- `PUT /admin/media-upload/:group/:file`: check an authenticated editor-or-higher session, exact `Origin`, unexpired D1 pending-upload record, server-generated storage key, declared MIME and exact byte size before `R2Bucket.put`. Bound the request body by the policy limit. In Workers, a fixed-length `Uint8Array` is the conservative input to `put` when a streamed request body has unknown length. The port's `createUpload` must return this route as `uploadUrl` and the exact required `Content-Type` header.
+- `GET /media/:purpose/:group/:file`: look up the committed `media_assets` row before `R2Bucket.get`, and serve only a listed variant with a safe MIME, `nosniff` and an intentional public cache policy. This is a **public** URL; it does not make private media safe.
+
+The existing create → `PUT` each `uploadUrl` → commit flow works unchanged in Admin UI. Verify that an anonymous/cross-origin/expired/oversize `PUT` fails, that pre-commit public reads are 404, and that committed media resolves anonymously. A successful R2 binding read/write probe alone does not enable the library.
+
+The browser route above uses the Sites session and therefore does **not** automatically work for a remote MCP client. For remote agent upload, either give the client a separately authenticated Worker `PUT` capability (with its own expiry and pending-record check) or choose the native `R2MediaStorage` direct-to-R2 path. Do not put image bytes in MCP JSON tool arguments. R2 bindings expose object operations, not S3 SigV4 presigning: direct-to-R2 presigned URLs require an R2 S3 endpoint and API key pair. Do not configure those credentials merely to make Admin UI upload work.
+
+## Remote MCP is a separate gate
+
+The reference exposes these separate surfaces:
+
+| Surface | Authentication | Reference support |
+|---|---|---|
+| Admin WebMCP | Current browser Admin session and fresh Mantle staff role | Available within Admin. |
+| Public MCP (reference path: `/api/mcp`) | Anonymous, read-only public Views | Manual HTTPS `initialize`, `tools/list`, and a published View call verified on the deployed integration. |
+| Sites-session staff MCP (reference path: `/api/mcp/staff`) | Sites-injected identity plus a fresh Mantle staff role | Mounted and reported to Admin; not usable as a remote OAuth connector. |
+| Remote staff OAuth MCP | OAuth bearer authorization and fresh Mantle staff role | Requires a separate integration. |
+| Sites-managed connector registration | Sites MCP declaration and connection configuration | Unverified; do not guess a hosting manifest key. |
+
+Try the conventional `/mcp` path first. If ChatGPT Sites does not route that
+path to the application, mount the MCP handler at another application-owned
+path and report the actual path through `mcpEndpoints`. For example:
+
+```ts
+app.all("/agent/read", publicMcpHandler);
+
+mountMantleAdmin(app, {
+  plan,
+  auth,
+  assets,
+  get,
+  mcpEndpoints: { public: "/agent/read", staff: "/agent/staff" },
+});
+```
+
+The reference encountered that condition and chose `/api/mcp` plus
+`/api/mcp/staff`. It mounts both handlers and passes both paths through
+`mcpEndpoints`, so Admin displays the routes that actually exist. These are
+example fallback paths, not Mantle Core routes. Verify each chosen route with
+`initialize`, `tools/list`, and a tool call after every Sites deployment.
+
+The reference smoke test also checks that `/mcp` and `/mcp/staff` return 404.
+The earlier deployment's root `/mcp` response is not evidence of a globally
+reserved Sites path; another Sites deployment may route it differently.
+
+Identity follows the same host-owned design. `@aotter/mantle-admin` exports
+`AdminAuth`; the reference implements it using trusted Sites identity headers
+and a D1 staff table. A host may implement the interface with another identity
+system or wrap Mantle's Better Auth adapter. Core does not contain a ChatGPT
+login implementation or require Better Auth for Sites.
+
+A successful public MCP call verifies that endpoint, not ChatGPT connector
+registration. A manually configured connector targets the HTTPS endpoint;
+Sites-provisioned connection details (`get_site` with `include_mcp_connection`)
+additionally require a deployed MCP declaration.
+
+The reference's staff endpoint trusts only identity injected by the Sites
+ingress, rejects ordinary members, and re-reads the Mantle role on every
+request. Before exposing staff MCP to remote clients, implement a standard
+OAuth authorization server or established provider, bearer verification, and
+a fresh Mantle staff role check on each tool request. Verify OAuth protected-resource and
+authorization metadata as JSON, a standards-compliant unauthenticated `401`
+challenge, and authenticated `tools/list` plus a read-only call. A Sites browser
+session or forwarded identity header is not an OAuth bearer token; a sign-in
+HTML page returned to an OAuth JSON request is a failed integration.
+
+## Capability boundaries
+
+Native Cloudflare deployments can configure R2 public domains, S3 credentials, Queues, Durable Objects, KV and Cron independently. A Sites deployment should claim only the bindings its hosting manifest and deployed tests actually expose. `waitUntil` is not a durable queue. Keep missing primitives as explicit host limitations rather than adding fake Mantle ports.
+
+See [native R2 direct upload](../cloudflare/media-r2.md), [authentication](../cloudflare/authentication.md), and [public web](../cloudflare/public-web.md).
+
+For custom business rules and external API calls, see the
+[equipment checkout guide](./equipment-checkout.md). It keeps transactional
+application state separate from notification delivery and documents the
+deployment experiment's limits. Sites' [unsupported uses](https://learn.chatgpt.com/docs/sites#understand-limits-and-unsupported-uses)
+include financial transactions; a successful sandbox experiment is not support
+for live payments.
+
+## Source
+
+- `MediaStorage` port and the media upload use case in `@aotter/mantle-runtime`
+- [Cloudflare R2 Workers binding API](https://developers.cloudflare.com/r2/api/workers/workers-api-reference/)
+- [Cloudflare R2 presigned URLs](https://developers.cloudflare.com/r2/api/s3/presigned-urls/)
+- [OpenAI Sites](https://learn.chatgpt.com/docs/sites)
+- [OpenAI MCP server authentication](https://developers.openai.com/plugins/build/auth)

package/docs/handbook/sites/index.md

@@ -0,0 +1,111 @@
+---
+description: "Build with ChatGPT Sites. Manage content and publishing with Mantle."
+---
+# Mantle on ChatGPT Sites
+
+**Build with ChatGPT Sites. Manage content and publishing with Mantle.**
+
+Give your Site an editorial workflow: sign in, invite editors, upload a cover
+image, save a draft, and publish an article. Mantle connects the Admin console,
+public pages, and agent tools to the same content model, so your team can keep
+the site current after the first build.
+
+ChatGPT Sites is a first-class integration in Mantle's official documentation,
+with a runnable reference and a repeatable verification flow maintained in this
+repository. Sites owns hosting, visitor access, and ChatGPT sign-in; Mantle owns
+the content model, staff roles, and publishing workflow. For platform access and
+sharing options, see [OpenAI's Sites documentation](https://learn.chatgpt.com/docs/sites).
+
+## What you get
+
+| Capability | In the Mantle Sites reference |
+|---|---|
+| Content management | Admin for drafting, editing, publishing, and unpublishing articles stored in D1. |
+| Staff access | ChatGPT sign-in with Mantle owner, editor, and contributor roles. Site visitor access grants no Mantle staff role. |
+| Images | Admin uploads through the Site's R2 binding, with public URLs for committed images. No R2 S3 credentials required. |
+| Public pages | Published article HTML and Markdown, cover images, canonical metadata, JSON-LD, sitemap, and `llms.txt`. |
+| Agent access | Admin WebMCP, anonymous read-only public Views at `/api/mcp`, and Sites-session staff tools at `/api/mcp/staff`. |
+
+Remote staff OAuth MCP and automatic ChatGPT connector registration are outside
+the reference's current scope. Public media URLs are readable by anyone
+who can reach the Site; this integration does not implement private media.
+See the [host reference](./host-reference.md) for the exact trust and transport
+boundaries.
+
+## Start with the supported SDK
+
+You need Node.js 22+, pnpm 9+, and Sites access with D1 and R2 available for your
+project. Follow the reference's local build and smoke test before deployment.
+Keep your application outside the SDK checkout. The included article schema is
+a working example; adapt its fields and lifecycle to your team's content.
+
+## Publish your first article
+
+1. **Prepare the application.** Follow the
+   [runnable reference](../../examples/host-chatgpt-sites/README.md#install-and-run).
+   Its local test verifies content, roles, images, public pages, and MCP together.
+2. **Connect Sites.** Follow [Publish with Sites](../../examples/host-chatgpt-sites/README.md#publish-with-sites)
+   to provision D1 and R2, set the production origin and first owner's email,
+   and review the database migrations. Save a version, then deploy it through
+   Sites for the intended audience.
+3. **Sign in as the owner.** Open `/admin/sign-in` and use the configured owner's
+   ChatGPT account. Give a second account an editor role in Mantle when you want
+   someone else to manage content. Sites sharing and Mantle staff roles are
+   separate controls.
+4. **Create a draft.** In Admin, create an article with a title, summary, and
+   Markdown body. Upload an image in the media library and select it as the
+   article's cover. The draft's public article URL should return 404.
+5. **Publish and read.** Publish the article and open `/articles`. Follow its
+   link to check the body and cover, then open its `.md` version. For a public
+   Site, repeat this while signed out. A restricted Site still enforces its
+   audience settings before visitors reach these pages.
+6. **Verify control.** Unpublish the article and confirm its detail page returns
+   404. Revoke the second account's staff role and verify it can no longer edit.
+   Published content and staff access should follow your changes immediately.
+
+For later content edits, return to Mantle Admin. Changes to the application's
+schema, code, or deployment settings follow the reference's migration and Sites
+deployment workflow.
+
+## Ask your agent to set it up
+
+Install the Mantle agent plugin, or `@aotter/mantle` itself, then describe your
+audience and content requirements:
+
+```text
+Build a content site with ChatGPT Sites and Mantle. Read
+handbook/sites/index.md and examples/host-chatgpt-sites/README.md from the
+installed Mantle docs, and follow that reference's install and run steps.
+Adapt the article example to my content requirements. Include ChatGPT
+sign-in, Mantle staff roles, cover uploads, and published article pages.
+Run the local checks and show me a draft-to-publish walkthrough before
+deploying through Sites. Keep remote staff OAuth MCP outside this scope.
+```
+
+For business rules beyond content, add: "use custom `ref` handlers and
+application-owned tables as described in handbook/sites/equipment-checkout.md."
+
+## Beyond content: operational workflows
+
+Custom handlers can connect typed Mantle operations to application-owned
+business rules and external services. See [Equipment checkout and external
+notifications](./equipment-checkout.md) for a non-payment scenario: staff
+approve equipment loans, atomically reserve a kit, and notify an equipment desk
+in Slack without making approval depend on notification delivery.
+
+This is an implementation guide and acceptance checklist, not an additional
+feature installed by the article reference. It separates deployed integration
+evidence from the equipment and Slack work still required in your application.
+
+## Integration details
+
+- [Host reference](./host-reference.md): identity, migrations, R2 routes, MCP, and deployment checks.
+- [Equipment checkout](./equipment-checkout.md): custom business rules and external API delivery without payments.
+- [Runnable application](../../examples/host-chatgpt-sites/README.md): installation, build artifacts, and smoke tests.
+- [Conventional Cloudflare Worker](../cloudflare/conventional-worker.md): the separate path for a Worker you deploy directly.
+
+## Source
+
+- [Runnable Sites application](../../examples/host-chatgpt-sites/README.md)
+- [Sites host reference](./host-reference.md)
+- [OpenAI Sites documentation](https://learn.chatgpt.com/docs/sites)

package/docs/handbook/start/project-and-cli.md

@@ -1,13 +1,13 @@
 ---
-description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and upgrade rules.
+description: The files you own in a Mantle project, every mantle and mantle-harness command with its flags, the generated module, the daily check loop, and version pins.
 ---
 # Project layout and the CLI loop
 
-This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. It is for engineers and coding agents working in an existing project.
+This page describes a directly authored Mantle project: which files are yours, what the installed CLI does to them, and the loop you run before every commit. Surfaces are optional — take only what you need. [The minimal Worker](./quickstart-worker.md) is Spec + adapter without Admin. [Local Admin](./quickstart-admin.md) is the opt-in Dev UI path when humans need a console.
 
 ## You own the project
 
-Core supplies a manifest compiler and a runtime, not a project generator. Since [ADR-0021](../../../docs/adr/0021-retire-starter-scaffolding.md) there is no scaffolder: you write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
+Core is a manifest compiler and a runtime, not a project generator. You write `package.json`, the manifests, the Worker entry, handlers, TypeScript and provider configuration. `mantle generate` compiles what exists; it never initializes a missing project or invents a default Schema, frontend or home route.
 
 ```txt
 my-service/
@@ -20,7 +20,7 @@ my-service/
 ├── src/
 │   ├── index.ts              createMantleWorker({ plan, extend })
 │   └── mantle/handlers/      handler refs (a convention; any path under src/)
-├── public/                   ASSETS: your frontend; public/_mantle/admin/ when Admin UI is installed
+├── public/                   required ASSETS root when Admin is installed; generate writes public/_mantle/admin/
 ├── .mantle/generated/
 │   └── mantle.ts             written by mantle generate
 ├── .agents/skills/mantle-*/  written by mantle skills
@@ -33,7 +33,7 @@ The minimal Worker reference keeps `.mantle/`, `.agents/`, `.claude/`, `.wrangle
 
 ## The CLI
 
-The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones.
+The umbrella package installs two binaries, `mantle` and `mantle-harness`. Run them through the package manager, for example `pnpm exec mantle generate`. Defaults shown are the pinned ones. Bare `mantle` / `mantle --help` prints a layered overview of optional surfaces (Minimal Spec + generate, Runtime / adapter, opt-in Admin). `generate --help` and `validate --help` stay on the compile path. After a successful `generate`, the CLI says Admin is opt-in: next steps when `@aotter/mantle-admin-ui` is installed, otherwise an API-only tip.
 
 | Command | Flags | Does |
 |---|---|---|
@@ -48,7 +48,15 @@ Advanced manifest primitives live in the `@aotter/mantle-spec` package's own `ma
 
 ### What `generate` does and does not do
 
-`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
+`generate` reads the manifest directory, runs the same validation as `validate` (without the handler-source grep), links the set, and emits one `.mantle/generated/mantle.ts`. When `@aotter/mantle-admin-ui` is installed it also syncs the **prebuilt** Admin SPA into `public/_mantle/admin/`, excluding the package's `server.*` exports; Core-only installs skip that copy. Any error diagnostic stops the run with exit 1.
+
+Do not Vite-build Admin unless you are developing `@aotter/mantle-admin-ui` itself. A Cloudflare project that serves Admin must declare Static Assets:
+
+```jsonc
+"assets": { "directory": "./public", "binding": "ASSETS" }
+```
+
+That binding is a hard requirement. If `/admin` returns SPA `index.html` (`200`) while `/_mantle/admin/assets/*` is `404`, the page white-screens. Leave `/_mantle` out of `run_worker_first` so those files stay on the assets layer. `generate` warns when it syncs Admin and the local wrangler config has no `ASSETS` binding.
 
 It does not project skills, update packages, change styling, provision providers, or deploy. It does not create manifests: a missing or empty `manifests/` directory is an error, not a prompt.
 
@@ -78,7 +86,7 @@ pnpm exec mantle-harness indexes --require-public --format text
 pnpm exec wrangler dev --local
 ```
 
-Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works.
+Run the harness after any change to a Schema index, View filter or ordering, or public route; declare the smallest ordered index the measured path needs and respect SQLite's leftmost-prefix rule. Before a deploy, run `mantle validate --phase deploy`. Probe at least one declared route on the local origin; a `200` from a public View does not prove Admin or MCP login works. When Admin is installed, also probe `/admin/sign-in` and one `/_mantle/admin/assets/*` URL — both must be `200`. HTML 200 with asset 404 is the white-screen class of bug.
 
 ## Connecting an agent
 
@@ -98,18 +106,18 @@ codex plugin add mantle@mantle
 
 The projected `develop` skill tells the agent to read `package.json` for the installed version, the manifests and adapter config, and the docs under `node_modules/@aotter/mantle/docs/` before editing. To connect an MCP client to the running Worker, see [MCP and agents](../concepts/mcp-and-agents.md).
 
-## Upgrade rules
+## Version pins
 
 - Pin every `@aotter/mantle*` package to one exact version and move them together. Check that release's peer ranges when you move.
-- Read the migration notes of the release you are moving to. Docs for a floating branch do not describe your installed version; use a tag that matches `package.json`.
-- The 0.1.2 line removes `mantle create`, the bundle `mantle update` command and `@aotter/mantle/provision`, with no aliases. `generate`, `validate`, `emit-openapi` and `skills` remain. `0.1.0-alpha.17` stays immutable; staying on it requires no migration.
-- When upgrading an existing application: pin the new exact version and refresh the lockfile; remove scripts that invoked the retired scaffolder; keep the Worker, D1, KV identity, origins, auth mode, secrets and legacy `.mantle` metadata; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
+- This handbook describes the snapshot in this source tree. Use the docs that ship with the version in `package.json`, not a floating branch.
+- The authoring CLI is `generate`, `validate`, `emit-openapi` and `skills`. `mantle-harness` is the measurement binary. There is no `create` / `update` happy path.
+- When you change versions: pin the new exact version and refresh the lockfile; keep the Worker, D1, KV identity, origins, auth mode and secrets; then run `generate`, `generate --check`, `skills`, `skills --check`, `validate`, typecheck and tests before deploying.
 
 ## Source
 - [`docs/direct-authoring.md`](../../../docs/direct-authoring.md)
-- [`docs/adr/0021-retire-starter-scaffolding.md`](../../../docs/adr/0021-retire-starter-scaffolding.md)
-- [`docs/migration-0.1.2.md`](../../../docs/migration-0.1.2.md)
-- [`docs/examples/minimal-worker/.gitignore`](../../../docs/examples/minimal-worker/.gitignore)
+- [`docs/examples/host-local-admin-otp/README.md`](../../../docs/examples/host-local-admin-otp/README.md)
+- [`docs/examples/host-local-admin-otp/wrangler.jsonc`](../../../docs/examples/host-local-admin-otp/wrangler.jsonc)
+- [`docs/examples/host-minimal-worker/.gitignore`](../../../docs/examples/host-minimal-worker/.gitignore)
 - [`packages/mantle/README.md`](../../../packages/mantle/README.md)
 - [`packages/mantle/src/cli/main.ts`](../../../packages/mantle/src/cli/main.ts)
 - [`packages/mantle/src/cli/generate.ts`](../../../packages/mantle/src/cli/generate.ts)