@aotter/mantle 0.1.4 → 0.1.5-alpha.1

package/skills/install/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mantle
-description: Author a new Mantle application directly from version-matched SDK docs, or continue an existing project. Use when asked to install Mantle, build a Mantle application, or open a Mantle repository.
+description: Set up a new Mantle application or continue an existing one using the installed SDK's matching instructions.
 metadata:
   source: "@aotter/mantle"
   sourcePath: skills/install/SKILL.md
@@ -11,139 +11,102 @@ metadata:
 
 # Mantle
 
-Mantle is an embeddable manifest engine. The application owns its source and
-provider configuration. There is no Starter/type picker or `mantle create`.
-Do not use the SDK checkout as the application, copy an old Starter tree, or
-turn `generate` into implicit scaffolding.
-A same-version `mantle-starters` tag is not required; do not wait for one.
-
-## Locate the version-matched instructions
-
-`npx skills add aotter/mantle` installs this brief, not the SDK,
-a project, or the handbook. Read the path printed by the installer (Codex's
-project-local path is `.agents/skills/mantle/SKILL.md`); `metadata.sourcePath`
-is repository provenance, not a consumer path. A repository install follows
-the selected Git ref and does not pin an npm release.
-
-After selecting the host and exact version, install `@aotter/mantle` locally
-with the selected optional packages. All `docs/...` paths below then mean
-`node_modules/@aotter/mantle/docs/...`; package skills are under
-`node_modules/@aotter/mantle/skills/`. Read that package's
-`skills/install/SKILL.md` before authoring: it supersedes this bootstrap copy.
-Use the new application's installation, never another project's `node_modules`
-or an SDK checkout packing harness, to resolve these paths.
-Before reading a handbook page, verify the version in that application's
-`node_modules/@aotter/mantle/package.json` against its lockfile and confirm
-the page exists under the same package directory. If the package is missing or
-the versions differ, fix the installation first; do not substitute a nearby
-checkout's docs or another project's `node_modules`.
-If the user requested a prerelease, resolve that channel explicitly; `latest`
-need not contain prerelease features. Never mix versioned npm code with branch
-docs. No local CLI exists until the package is installed.
-
-## New application
-
-1. Determine the actual host and required surfaces from the request. Reuse an
-   existing application when available; otherwise work in its own directory.
-   Do not assume Cloudflare, public HTML or Admin is required. Check Node 22+
-   and pnpm 9+ for these SDK examples. A ChatGPT Site is not a conventional
-   Cloudflare Worker deployment; use the installed
-   `docs/handbook/chatgpt-sites/index.md` integration guide and
-   `docs/examples/host-chatgpt-sites/` runnable reference when selected.
-2. Choose the requested exact SDK version, or resolve the intended release
-   channel once. Pin all selected `@aotter/mantle*` dependencies to that same
-   version. Install only the adapter/optional packages the application needs.
-   If a global scope registry overrides public npmjs, use a project-owned
-   `.npmrc` with `@aotter:registry=https://registry.npmjs.org/`.
-3. Use the host and surfaces already established in step 1; ask only for
-   information still missing. Read `docs/handbook/start/overview.md` and
-   `docs/handbook/reference/features.md`, then select the matching path:
-   - Spec + generate / embed Runtime — `docs/handbook/start/project-and-cli.md`.
-   - Adapter without Admin — `docs/examples/host-minimal-worker/`.
-   - Opt-in Admin / Dev UI — only when a human needs a console: interview
-     the bootstrap owner email, then `docs/examples/host-local-admin-otp/`
-     (`pnpm install && pnpm generate && pnpm dev`, `/admin/sign-in`, OTP
-     in wrangler logs). Admin needs `@aotter/mantle-admin`,
-     `@aotter/mantle-admin-ui`, wrangler `ASSETS` on `./public`, and
-     `createAuth` email-otp + `ConsoleEmailSender`. Do not Vite-build Admin.
-   - ChatGPT Sites with Admin/D1/R2 — follow
-     `docs/examples/host-chatgpt-sites/`, not the email-OTP Worker example.
-     Copy it outside the SDK checkout, pin its `@aotter/mantle*` dependencies
-     to the selected exact version, then `npm install`,
-     `npx mantle validate --phase deploy`, `npm run generate`, `npm run check`,
-     `npx wrangler d1 migrations apply DB --local`,
-     `npm run dev -- --port 4174`, and `npm test` in a second terminal.
-     Preserve its Sites-owned identity ingress and hosting manifest; author the
-     user's Schema/View/Procedure/Trigger, then review migrations, media policy
-     and the local/production smoke gates. Sites provisions and deploys; never
-     `wrangler deploy` a Site. Request both D1 and R2 when uploads are in scope.
-     Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not enable remote staff OAuth MCP.
-     At handoff, show the owner where Admin WebMCP and the public/staff MCP
-     endpoints appear, and state which are usable from the browser versus a
-     remote connector.
-   - ChatGPT Sites with custom business rules or an external callback — the
-     runnable reference covers builtin content only. For application-owned
-     operational state, `handler: { kind: ref }` Procedures, staff-only SQL
-     Views, staff MCP Triggers with `requires.auth`, and outbound webhooks
-     called from handler code, follow
-     `docs/handbook/chatgpt-sites/equipment-checkout.md`. It is an implementation
-     guide, not a shipped app: keep Mantle-owned Schema tables and
-     application-owned tables separate, and give every application table a
-     reviewed migration.
-   - Grammar — `docs/examples/README.md`. Copy `builtin-*` Manifests directly.
-     Read `cf-primitives-*` when the request needs Durable Objects, Queues,
-     cron, payment-provider callbacks, or API-key and entitlement guards;
-     those carry `ref` handlers and are not Builder-ingestible.
-   None of these is a template to install wholesale. Other hosts use the
-   embedded adapter guides. Author package scripts, manifests, entry and
-   configuration for the user's requirements. No default notes model, home
-   page, icon, launch metadata or visitor frontend is required.
-4. Compile and verify using the application's commands. The fundamental CLI
-   sequence is:
-
-```sh
-pnpm exec mantle generate
-pnpm exec mantle generate --check
-pnpm exec mantle validate
-pnpm exec mantle skills
-pnpm exec mantle skills --check
-```
-
-Run the project's TypeScript check and start its actual local server. Probe
-a route the application declares. An API-only or adapter-only project may
-correctly return 404 at `/` and have no Admin. When Admin was requested,
-probe `/admin/sign-in` and a `/_mantle/admin/assets/*` URL — both must be
-200. A white screen is an assets 404, not a missing frontend build.
-Conventional Auth routes may return `503 setup_incomplete` until that mode
-is configured; the local OTP path replaces construction instead. Do not
-introduce an auth bypass to make smoke pass.
-
-Commit the resolved lockfile in the application's normal workflow; subsequent
-installs use `pnpm install --frozen-lockfile`. Do not initialize/push a remote,
-provision resources, deploy or commit secrets as part of local verification.
-
-## Existing application
-
-Read package.json, lockfile, actual entry, manifest files, provider config and
-project instructions. `.mantle/launch-state.json`, features or handoff files
-are optional legacy context, never prerequisites. Preserve them and user code.
-Install the frozen dependency graph, project installed Core skills, then read
-those skills and embedded docs. Never apply develop docs to an older package.
-Use the installed `mantle --help` and the project's scripts as authority.
-
-For a legacy pre-stable project, retain its pinned behavior until an explicit
-upgrade is requested. Do not rewrite provider identities, delete metadata or
-fetch a nonexistent new Starter tag. SDK upgrades follow the update skill, not
-a bundle comparison command.
-
-## Ship and report
-
-When deployment is requested, read
-`node_modules/@aotter/mantle/skills/provision/SKILL.md` (not projected by
-`mantle skills`) and follow that version-matched skill and the
-observed host configuration. Legacy Landing remains a pre-stable product; it
-is not a launch dependency for new Core projects.
-
-Report the project path, exact SDK version, local URL/HTTP result and checks,
-plus any genuinely missing auth/provider setup. Do not claim a working homepage
-or authenticated MCP based only on successful generation.
+`npx skills add aotter/mantle` installs this small bootstrap skill. It does not
+install the SDK or create a project. The skill name is `mantle`; the source
+folder remains `skills/install/` so installation does not copy the repository.
+
+## Find the application and its version
+
+First locate the user's target project. If it already has `@aotter/mantle`,
+read that project's `package.json`, lockfile, and
+`node_modules/@aotter/mantle/package.json`. Follow the CLI and docs shipped in
+that exact installed package. Never use another project's dependencies, the
+SDK checkout, a floating GitHub handbook, or an old alpha/Starter fallback.
+An older installed SDK may only support direct authoring; its own
+`mantle generate --help` decides which flags exist. Upgrade only when requested.
+
+For a new project, choose `cf` or `chatgpt-sites` from the request; ask only if
+it remains ambiguous. A host-free Spec-only project needs no host. Resolve the
+latest **published stable** `@aotter/mantle` version from npm once, confirm it
+is not a prerelease, and install it with an exact version in the new project.
+For example, run `npm view @aotter/mantle@latest version`, inspect the returned
+plain `X.Y.Z`, then `npm install --save-exact @aotter/mantle@X.Y.Z` with that
+actual version substituted. Set `type=module` in `package.json` first; npm's
+default project type may be CommonJS.
+When testing a release candidate, use the explicitly supplied exact version
+or local tarball instead of npm latest. Pin every selected `@aotter/mantle*`
+package to the running CLI's exact version; `generate` writes the required
+package declarations. Do not let npm's default `^` range remain. If the
+project registry overrides public npmjs, set `@aotter:registry=https://registry.npmjs.org/`
+in a project-owned `.npmrc`.
+
+## New project sequence
+
+1. Create a separate application directory with Node 22+ and a project
+   `package.json` containing `"type":"module"`. Install the exact chosen
+   `@aotter/mantle` version locally. Read its
+   `node_modules/@aotter/mantle/skills/install/SKILL.md` and version-matched
+   `docs/handbook/start/overview.md` before continuing. These installed
+   instructions take precedence over this GitHub bootstrap copy. Check
+   `npx mantle generate --help`: if it does not list `--host`, follow the
+   installed version's direct-authoring path instead of the steps below.
+2. On a CLI that supports it, run with an explicit host, for example
+   `npx mantle generate --host cf` or `npx mantle generate --host chatgpt-sites`.
+   No `--features` means Spec, Runtime, API, MCP, Admin and a blank editable
+   home. For a smaller app, positively list the modules with `--features`
+   (for example `spec,api`); use `--features spec` for a host-free compiler.
+   Do not remove Admin merely because its package is not installed yet.
+3. The first run may declare selected dependencies and exit asking for an
+   install. Install them using the project's package manager, then rerun
+   `mantle generate` to finish. Read `docs/handbook/start/project-and-cli.md`
+   from the same installed package for saved selections, owned files,
+   `--check`.
+4. Before adding a Schema on ChatGPT Sites, review and apply its initial local
+   D1 migration as the installed Sites guide says. Then add only the user's
+   Schema, View, Procedure and Trigger manifests. Keep the blank home editable;
+   do not invent business data or media bindings. Run `mantle generate` to
+   append any new migration, review and apply it, then run `generate --check`,
+   `validate`, `skills`, build/typecheck and local smoke.
+5. For Cloudflare, follow installed `docs/handbook/start/project-and-cli.md`
+   and `docs/handbook/cloudflare/authentication.md`. Copy `.dev.vars.example`
+   to `.dev.vars`, set `ADMIN_EMAIL` and `BETTER_AUTH_SECRET`, and match
+   `PUBLIC_ORIGIN` to the loopback URL printed by `wrangler dev`. Open
+   `/admin/sign-in` with that email; read the OTP from wrangler logs. Check
+   Admin assets and an owner-only Admin API before claiming Admin works. For
+   ChatGPT Sites, follow installed
+   `docs/handbook/chatgpt-sites/generated-app.md`: review and apply local D1
+   migrations, set `OWNER_EMAIL` and `PUBLIC_ORIGIN`, then test the blank home,
+   unauthorized Admin, owner Admin, public MCP and staff MCP. Local owner
+   identity is simulated by the loopback-only smoke; it does not create a
+   browser ChatGPT session. Sites owns
+   production identity and deployment; do not deploy its Worker directly.
+   Browser Admin WebMCP and Sites-session `/api/mcp/staff` do not provide
+   remote staff OAuth MCP. The owner can maintain content through Admin and
+   the applicable authenticated MCP surface.
+
+Use installed `docs/handbook/reference/features.md` for Manifest choices and
+`docs/examples/` for optional examples. The generated project is the starting
+point; a domain example is not a template to copy wholesale. Do not use a
+`mantle-starters` tag or `mantle create`.
+
+## Existing project and handoff
+
+For an application that already uses Mantle, preserve selected features,
+user-authored files, migrations, package versions, identity settings and
+provider resources. Use its installed CLI's `--help` and package-local docs.
+Run `generate --check` without writing, then the project's normal tests.
+
+When the request is to add Mantle to an independently authored application,
+inspect its host, code and data first. Use the exact installed package's
+`docs/skills/integrate/SKILL.md` if available. If Mantle is not installed,
+choose between selective embedding, incremental replacement and creating a
+separate Mantle app followed by frontend/data migration before installing an
+exact SDK version. The existing application does not need to adopt the
+generated project's entry or directory layout. An older SDK's own docs and
+CLI govern its behavior; upgrade deliberately if the selected strategy needs
+newer capabilities.
+
+When deployment is requested, read the installed version's
+`skills/provision/SKILL.md`. Report the target path, exact SDK version, local
+HTTP results, Admin/MCP identity evidence, and any missing provider setup.
+Local simulated Sites headers do not prove deployed ChatGPT sign-in.

package/skills/integrate/SKILL.md

@@ -0,0 +1,60 @@
+---
+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.
+metadata:
+  source: "@aotter/mantle"
+  sourcePath: docs/skills/integrate/SKILL.md
+  applies_to: mantle grammar v0.1
+  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.

package/templates/chatgpt-sites/auth.ts

@@ -0,0 +1,66 @@
+import type { AdminAuth, AdminStaffUser, StaffRole } from '@aotter/mantle/admin';
+
+export interface Env { DB: D1Database; ASSETS?: Fetcher; PUBLIC_ORIGIN: string; OWNER_EMAIL?: string }
+type UserRow = { id: string; email: string; name: string; role: StaffRole | null; created_at: string; signed_in: number };
+const project = (row: UserRow): AdminStaffUser => ({ id:row.id,email:row.email,name:row.name,role:row.role,githubLogin:null,emailVerified:!!row.signed_in,createdAt:new Date(row.created_at) });
+
+// This adapter must only receive requests through Sites' identity-stripping dispatcher.
+// Never expose the Worker independently with caller-controlled oai-* headers.
+export function readIdentity(request: Request) {
+  const sub=request.headers.get('oai-authenticated-user-id');
+  const email=request.headers.get('oai-authenticated-user-email')?.trim().toLowerCase();
+  if(!sub || !email || sub.length>512 || email.length>320) return null;
+  let name=email;
+  if(request.headers.get('oai-authenticated-user-full-name-encoding')==='percent-encoded-utf-8') {
+    try { name=decodeURIComponent(request.headers.get('oai-authenticated-user-full-name')||'')||email; } catch {}
+  }
+  return {id:`chatgpt:${sub}`,email,name};
+}
+
+export function createChatGPTAuth(env: Env): AdminAuth {
+  const db=env.DB;
+  const roleFor=async(id:string)=>(await db.prepare('SELECT role FROM sites_users WHERE id = ?').bind(id).first<{role:StaffRole|null}>())?.role??null;
+  const auth: AdminAuth = {
+    basePath:'/api/auth', methods:[],
+    async getSession(request) {
+      const who=readIdentity(request); if(!who)return null;
+      let row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      if(!row){
+        // Claim an invitation before inserting; a stable identity keeps its existing role if its email later changes.
+        await db.prepare('UPDATE sites_users SET id=?,name=?,signed_in=1 WHERE email=? AND signed_in=0').bind(who.id,who.name,who.email).run();
+        await db.prepare('INSERT OR IGNORE INTO sites_users (id,email,name,role,signed_in) VALUES (?,?,?,?,1)')
+          .bind(who.id,who.email,who.name,who.email===env.OWNER_EMAIL?.trim().toLowerCase()?'owner':null).run();
+        row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      }
+      if(!row)return null;
+      return {session:{id:`sites:${who.id}`},user:{id:row.id,email:row.email,name:row.name,role:row.role,roleCurrent:true}};
+    },
+    getUserRole:roleFor,
+    async handler(request) {
+      const path=new URL(request.url).pathname;
+      if(path==='/api/auth/get-session' && request.method==='GET') return Response.json(await auth.getSession(request));
+      if(path==='/api/auth/sign-out' && request.method==='POST') {
+        if(request.headers.get('origin')!==env.PUBLIC_ORIGIN)return new Response('Forbidden',{status:403});
+        // The shipped Admin UI navigates here after its POST; the next top-level request signs out at Sites.
+        return Response.json({success:true},{headers:{'set-cookie':'mantle-sites-signout=1; Path=/admin/sign-in; HttpOnly; SameSite=Strict; Max-Age=60'+(env.PUBLIC_ORIGIN.startsWith('https:')?'; Secure':'')}});
+      }
+      return Response.json({error:'unsupported_auth_route'},{status:404});
+    },
+    async listUsers(){const r=await db.prepare('SELECT * FROM sites_users WHERE role IS NOT NULL ORDER BY created_at,id').all<UserRow>();return r.results.map(project);},
+    async listMembers(args){
+      // ponytail: one bounded page for this integration lab; add cursor pagination before a large member rollout.
+      const r=await db.prepare('SELECT * FROM sites_users WHERE role IS NULL AND (email LIKE ? OR name LIKE ?) ORDER BY created_at,id LIMIT ?').bind(`%${args.search||''}%`,`%${args.search||''}%`,Math.min(args.limit,100)).all<UserRow>();
+      return {items:r.results.map(project),previousCursor:null,nextCursor:null};
+    },
+    async setUserRole(id,role){if(role!==null&&!['owner','editor','contributor'].includes(role))throw new Error('Invalid role');return !!(await db.prepare('UPDATE sites_users SET role=? WHERE id=?').bind(role,id).run()).meta.changes;},
+    async inviteUser(email,role){
+      const normalized=email.trim().toLowerCase();const id=`invite:${crypto.randomUUID()}`;
+      const r=await db.prepare('INSERT OR IGNORE INTO sites_users (id,email,name,role,signed_in) VALUES (?,?,?,?,0)').bind(id,normalized,normalized,role).run();
+      if(r.meta.changes)return {kind:'created',id};
+      const existing=await db.prepare('SELECT id FROM sites_users WHERE email=?').bind(normalized).first<{id:string}>();
+      if(!existing)throw new Error('Invitation could not be saved');return {kind:'exists',id:existing.id};
+    },
+    async revokeInvite(id){return !!(await db.prepare('DELETE FROM sites_users WHERE id=? AND signed_in=0').bind(id).run()).meta.changes;},
+  };
+  return auth;
+}

package/templates/chatgpt-sites/build.mjs

@@ -0,0 +1,14 @@
+import { build } from 'esbuild';
+import { cp, mkdir, rm } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+
+execFileSync('node', ['node_modules/@aotter/mantle/dist/cli/main.js', 'generate', '--check'], { stdio: 'inherit' });
+execFileSync('node', ['node_modules/typescript/bin/tsc', '--noEmit'], { stdio: 'inherit' });
+await rm('dist', { recursive: true, force: true });
+await mkdir('dist/server', { recursive: true });
+await build({ entryPoints: ['src/index.ts'], outfile: 'dist/server/index.js', bundle: true, format: 'esm', platform: 'browser', conditions: ['workerd'], target: 'es2022', external: ['cloudflare:*', 'node:*'] });
+await mkdir('dist/client', { recursive: true });
+await cp('public', 'dist/client', { recursive: true, force: true }).catch(error => { if (error.code !== 'ENOENT') throw error; });
+await mkdir('dist/.openai', { recursive: true });
+await cp('.openai/hosting.json', 'dist/.openai/hosting.json');
+await cp('drizzle', 'dist/.openai/drizzle', { recursive: true });

package/templates/chatgpt-sites/env.ts

@@ -0,0 +1 @@
+export interface Env { DB: D1Database; PUBLIC_ORIGIN: string; ASSETS?: Fetcher }

package/templates/chatgpt-sites/mcp.ts

@@ -0,0 +1,48 @@
+import type { Hono } from 'hono';
+import type { AdminAuth, MantleAdminRuntime, StaffRole } from '@aotter/mantle/admin';
+import { McpJsonRpcDispatcher, projectCallableCapabilities, type RuntimePlan } from '@aotter/mantle/runtime';
+import type { Env } from './sites-auth';
+
+const staffRoles=new Set<string>(['owner','editor','contributor']);
+
+/** Sites-session MCP surfaces. Remote clients still need a separate OAuth bearer flow. */
+export function mountMcp(app:Hono<{Bindings:Env}>, get:()=>Promise<MantleAdminRuntime>, auth:AdminAuth, plan:RuntimePlan) {
+  const cache=new WeakMap<object,Map<'public'|'staff',McpJsonRpcDispatcher>>();
+  const dispatcher=async(surface:'public'|'staff',origin:string)=>{
+    const runtime=await get();
+    let dispatchers=cache.get(runtime);
+    if(!dispatchers)cache.set(runtime,dispatchers=new Map());
+    let value=dispatchers.get(surface);
+    if(!value) {
+      value=new McpJsonRpcDispatcher({
+        getEntry:runtime.getEntry,
+        createDraft:runtime.createDraft,
+        updateDraft:runtime.updateDraft,
+        requestPublish:runtime.requestPublish,
+        unpublish:runtime.unpublish,
+        archive:runtime.archive,
+        deleteEntry:runtime.deleteEntry,
+        executeView:{execute:request=>runtime.executeView({...request,view:request.view.metadata.name})},
+        invokeTrigger:{execute:request=>runtime.invokeTrigger(request)},
+      },[...runtime.schemas.values()],{
+        surface,
+        capabilities:projectCallableCapabilities(plan,{surface}),
+        serverInfo:{name:`aotter.mantle.${surface}`,title:`Mantle ${surface}`,websiteUrl:origin},
+      });
+      dispatchers.set(surface,value);
+    }
+    return value;
+  };
+  app.all('/api/mcp',async c=>(await dispatcher('public',c.env.PUBLIC_ORIGIN)).dispatch(c.req.raw,{user:null,staff:null,env:c.env,waitUntil:p=>c.executionCtx.waitUntil(p)}));
+  app.all('/api/mcp/staff',async c=>{
+    const session=await auth.getSession(c.req.raw);
+    if(!session)return Response.json({error:'unauthorized'},{status:401});
+    const role=session.user.roleCurrent?session.user.role:await auth.getUserRole(session.user.id);
+    if(!role||!staffRoles.has(role))return Response.json({error:'forbidden'},{status:403});
+    return (await dispatcher('staff',c.env.PUBLIC_ORIGIN)).dispatch(c.req.raw,{
+      user:{id:session.user.id},staff:{id:session.user.id,role:role as StaffRole},
+      auth:{credential:'session',credentialId:session.session.id,clientId:null,scopes:[]},
+      env:c.env,waitUntil:p=>c.executionCtx.waitUntil(p),
+    });
+  });
+}

package/templates/chatgpt-sites/public-mcp.ts

@@ -0,0 +1,29 @@
+import type { Hono } from 'hono';
+import { McpJsonRpcDispatcher, projectCallableCapabilities, type MantleRuntime, type RuntimePlan } from '@aotter/mantle/runtime';
+import type { Env } from './sites-env';
+
+export function mountPublicMcp(app:Hono<{Bindings:Env}>,get:()=>Promise<MantleRuntime>,plan:RuntimePlan) {
+  let current:MantleRuntime|undefined;
+  let dispatcher:McpJsonRpcDispatcher|undefined;
+  app.all('/api/mcp',async c=>{
+    const runtime=await get();
+    if(current!==runtime){
+      current=runtime;
+      dispatcher=new McpJsonRpcDispatcher({
+        getEntry:runtime.getEntry,
+        createDraft:runtime.createDraft,
+        updateDraft:runtime.updateDraft,
+        requestPublish:runtime.requestPublish,
+        unpublish:runtime.unpublish,
+        archive:runtime.archive,
+        deleteEntry:runtime.deleteEntry,
+        executeView:{execute:request=>runtime.executeView({...request,view:request.view.metadata.name})},
+        invokeTrigger:{execute:request=>runtime.invokeTrigger(request)},
+      },[...runtime.schemas.values()],{
+        surface:'public',capabilities:projectCallableCapabilities(plan,{surface:'public'}),
+        serverInfo:{name:'aotter.mantle.public',title:'Mantle public',websiteUrl:c.env.PUBLIC_ORIGIN},
+      });
+    }
+    return dispatcher!.dispatch(c.req.raw,{user:null,staff:null,env:c.env,waitUntil:p=>c.executionCtx.waitUntil(p)});
+  });
+}

package/templates/chatgpt-sites/smoke-local.mjs

@@ -0,0 +1,20 @@
+import assert from 'node:assert/strict';
+
+const origin=process.env.MANTLE_TEST_ORIGIN??'http://127.0.0.1:4174';
+const url=new URL(origin);
+assert.equal(url.protocol,'http:','Identity simulation requires loopback HTTP');
+assert.ok(['localhost','127.0.0.1','[::1]'].includes(url.hostname),'Identity simulation is loopback-only');
+const email=process.env.MANTLE_TEST_OWNER_EMAIL;
+assert.ok(email,'Set MANTLE_TEST_OWNER_EMAIL to the locally configured owner');
+const owner={'oai-authenticated-user-id':'mantle-local-owner','oai-authenticated-user-email':email};
+const stranger={'oai-authenticated-user-id':'mantle-local-stranger','oai-authenticated-user-email':'stranger@example.test'};
+const call=(path,headers={})=>fetch(new URL(path,url),{headers,redirect:'manual'});
+assert.equal((await call('/')).status,200);
+assert.equal((await call('/admin/api/me')).status,401);
+assert.equal((await call('/admin/api/me',stranger)).status,403);
+assert.equal((await call('/admin/api/me',owner)).status,200);
+const mcp=(path,headers={})=>fetch(new URL(path,url),{method:'POST',headers:{...headers,'content-type':'application/json','mcp-protocol-version':'2025-11-25'},body:JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize'})});
+assert.equal((await mcp('/api/mcp')).status,200);
+assert.equal((await mcp('/api/mcp/staff')).status,401);
+assert.equal((await mcp('/api/mcp/staff',owner)).status,200);
+console.log('Local Sites identity simulation passed; this does not verify deployed ChatGPT sign-in.');