@aotter/mantle 0.1.3 → 0.1.5-alpha.1

package/docs/examples/host-chatgpt-sites/drizzle/meta/mantle-state.json

@@ -0,0 +1,60 @@
+{
+  "fingerprint": "9ef85f9933e22328140e924045820af6be2a6985ed8ecc19b63a4f2a37826618",
+  "schemas": [
+    {
+      "apiVersion": "cms.mantle.aotter.net/v1",
+      "kind": "Schema",
+      "metadata": {
+        "name": "articles"
+      },
+      "spec": {
+        "title": "文章",
+        "schema": {
+          "type": "object",
+          "required": [
+            "title"
+          ],
+          "properties": {
+            "title": {
+              "type": "string",
+              "title": "標題",
+              "maxLength": 160
+            },
+            "summary": {
+              "type": "string",
+              "title": "摘要",
+              "maxLength": 1000
+            },
+            "body": {
+              "type": "string",
+              "title": "內容",
+              "x-mcp-hint": "markdown"
+            },
+            "coverAssetId": {
+              "type": "string",
+              "title": "封面圖片",
+              "x-mantle-ref": "media_assets",
+              "x-mcp-hint": "media-image"
+            }
+          }
+        },
+        "lifecycle": "publishing",
+        "uniqueIndexes": [],
+        "indexes": [],
+        "searchableFields": [],
+        "localized": false
+      }
+    }
+  ],
+  "appliedMigrationIds": [
+    "0001-init",
+    "0002-media-assets",
+    "0003-pending-media-uploads",
+    "0004-native-schema-storage",
+    "0005-store-instance-id",
+    "0006-managed-runtime-version",
+    "0007-schedule-run-observations"
+  ],
+  "lastIndex": 5,
+  "canonicalVersion": "0007-schedule-run-observations"
+}

package/docs/examples/host-chatgpt-sites/package.json

@@ -1 +1 @@
-{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}
+{"name":"mantle-sites-reference","version":"0.0.1","private":true,"type":"module","scripts":{"build":"node scripts/build.mjs","dev":"wrangler dev","generate":"mantle generate","check":"tsc --noEmit","test":"node --experimental-strip-types scripts/check.mjs","migrate:generate":"node scripts/migration.mjs","migrate:check":"node scripts/migration.mjs --check"},"dependencies":{"@aotter/mantle":"latest","@aotter/mantle-admin":"latest","@aotter/mantle-admin-ui":"latest","@aotter/mantle-cloudflare":"latest","@aotter/mantle-web":"latest","hono":"^4.9.0","micromark":"4.0.2","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"*","esbuild":"^0.28.0","typescript":"^5.9.0","wrangler":"^4.0.0"}}

package/docs/examples/host-chatgpt-sites/public/site.css

@@ -1 +1 @@
-:root{font-family:Inter,"Noto Sans TC",ui-sans-serif,system-ui,sans-serif;color:#172320;background:#f7f8f4;font-synthesis:none}*{box-sizing:border-box}body{margin:0}a{color:inherit;text-decoration:none}a:hover{text-decoration:underline}.topbar{height:78px;max-width:1440px;margin:auto;padding:0 clamp(24px,5vw,80px);display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid #d9dfd8}.brand{display:flex;align-items:center;gap:12px;font-size:18px;font-weight:760;letter-spacing:-.04em}.brand em{color:#95aa8c;font-style:normal}.mark{width:37px;height:37px;border-radius:11px;background:#183c30;color:#d9eadb;display:grid;place-items:center;font-size:19px;font-family:Georgia,serif}.topbar nav{display:flex;gap:28px;font-size:14px;color:#43564e}.hero{max-width:1440px;margin:auto;padding:100px clamp(24px,8vw,128px) 116px}.hero.small{padding-bottom:75px}.eyebrow,.feature-index{font-size:11px;letter-spacing:.19em;font-weight:750;color:#68806f}.hero h1,.article-page h1{font-family:Georgia,"Noto Serif TC",serif;font-weight:500;letter-spacing:-.055em;line-height:1.09;margin:26px 0 28px;font-size:clamp(48px,6.1vw,94px)}.dot{color:#a2b888}.hero-copy{max-width:620px;color:#52665a;font-size:18px;line-height:1.8}.actions{display:flex;align-items:center;gap:30px;margin-top:38px}.button{display:inline-flex;justify-content:space-between;gap:44px;min-width:184px;padding:17px 19px;border-radius:7px;color:#fff;background:#214f3c;font-size:14px;font-weight:650}.button:hover{background:#173c2d;text-decoration:none}.text-link{font-size:14px;color:#315640}.feature-grid{max-width:1440px;margin:auto;padding:0 clamp(24px,8vw,128px) 110px;display:grid;grid-template-columns:repeat(3,1fr);gap:18px}.feature-grid>div{border-top:1px solid #bfcac0;padding-top:24px}.feature-grid h2{font-family:Georgia,"Noto Serif TC",serif;font-size:29px;font-weight:500;margin:29px 0 10px}.feature-grid p{font-size:14px;line-height:1.75;color:#597064;max-width:270px}.content-wrap{max-width:1184px;margin:0 auto;padding:0 24px 100px}.article-row{padding:25px 0;border-top:1px solid #cbd5ca;display:grid;grid-template-columns:160px 1fr 36px;gap:24px;align-items:start}.article-row:last-child{border-bottom:1px solid #cbd5ca}.article-number{font-size:12px;color:#708477;margin-top:11px}.article-row h2{font-family:Georgia,"Noto Serif TC",serif;font-size:clamp(24px,3vw,35px);font-weight:500;letter-spacing:-.035em;margin:0 0 8px}.article-row p{font-size:14px;color:#617468;line-height:1.65;margin:0}.article-row>span{color:#739279;font-size:25px}.empty{min-height:220px;padding:52px 0}.empty h2{font-size:27px;font-family:Georgia,"Noto Serif TC",serif;font-weight:500}.empty p{color:#66796c}.pagination{margin:26px 0}.article-page{max-width:900px;padding:75px 30px 140px;margin:auto}.back{font-size:13px;color:#5c7768}.article-page article{margin-top:75px}.article-page h1{font-size:clamp(44px,5vw,75px)}.lede{font-size:21px;line-height:1.75;color:#52685a}.prose{border-top:1px solid #cbd5ca;margin-top:45px;padding-top:28px;line-height:1.95;font-size:17px;color:#33473c}.prose p{margin:0 0 1.2em}.markdown-link{display:inline-block;margin-top:40px;font-size:13px;color:#4f765b}footer{border-top:1px solid #d5ddd3;max-width:1440px;margin:auto;padding:28px clamp(24px,5vw,80px);display:flex;justify-content:space-between;font-size:12px;color:#788b7d}@media(max-width:700px){.topbar{height:68px}.topbar nav{gap:16px;font-size:12px}.hero{padding-top:74px;padding-bottom:70px}.hero-copy{font-size:16px}.feature-grid{grid-template-columns:1fr;gap:26px}.article-row{grid-template-columns:1fr 26px;gap:10px}.article-number{grid-column:1/-1;margin:0}.article-page{padding-top:55px}.article-page article{margin-top:50px}footer{gap:20px}}
+:root{font-family:Inter,"Noto Sans TC",ui-sans-serif,system-ui,sans-serif;color:#172320;background:#f7f8f4;font-synthesis:none}*{box-sizing:border-box}body{margin:0}a{color:inherit;text-decoration:none}a:hover{text-decoration:underline}.topbar{height:78px;max-width:1440px;margin:auto;padding:0 clamp(24px,5vw,80px);display:flex;align-items:center;justify-content:space-between;border-bottom:1px solid #d9dfd8}.brand{display:flex;align-items:center;gap:12px;font-size:18px;font-weight:760;letter-spacing:-.04em}.brand em{color:#95aa8c;font-style:normal}.mark{width:37px;height:37px;border-radius:11px;background:#183c30;color:#d9eadb;display:grid;place-items:center;font-size:19px;font-family:Georgia,serif}.topbar nav{display:flex;gap:28px;font-size:14px;color:#43564e}.hero{max-width:1440px;margin:auto;padding:100px clamp(24px,8vw,128px) 116px}.hero.small{padding-bottom:75px}.eyebrow,.feature-index{font-size:11px;letter-spacing:.19em;font-weight:750;color:#68806f}.hero h1,.article-page h1{font-family:Georgia,"Noto Serif TC",serif;font-weight:500;letter-spacing:-.055em;line-height:1.09;margin:26px 0 28px;font-size:clamp(48px,6.1vw,94px)}.dot{color:#a2b888}.hero-copy{max-width:620px;color:#52665a;font-size:18px;line-height:1.8}.actions{display:flex;align-items:center;gap:30px;margin-top:38px}.button{display:inline-flex;justify-content:space-between;gap:44px;min-width:184px;padding:17px 19px;border-radius:7px;color:#fff;background:#214f3c;font-size:14px;font-weight:650}.button:hover{background:#173c2d;text-decoration:none}.text-link{font-size:14px;color:#315640}.feature-grid{max-width:1440px;margin:auto;padding:0 clamp(24px,8vw,128px) 110px;display:grid;grid-template-columns:repeat(3,1fr);gap:18px}.feature-grid>div{border-top:1px solid #bfcac0;padding-top:24px}.feature-grid h2{font-family:Georgia,"Noto Serif TC",serif;font-size:29px;font-weight:500;margin:29px 0 10px}.feature-grid p{font-size:14px;line-height:1.75;color:#597064;max-width:270px}.content-wrap{max-width:1184px;margin:0 auto;padding:0 24px 100px}.article-row{padding:25px 0;border-top:1px solid #cbd5ca;display:grid;grid-template-columns:160px 1fr 36px;gap:24px;align-items:start}.article-row:last-child{border-bottom:1px solid #cbd5ca}.article-number{font-size:12px;color:#708477;margin-top:11px}.article-row h2{font-family:Georgia,"Noto Serif TC",serif;font-size:clamp(24px,3vw,35px);font-weight:500;letter-spacing:-.035em;margin:0 0 8px}.article-row p{font-size:14px;color:#617468;line-height:1.65;margin:0}.article-row>span{color:#739279;font-size:25px}.empty{min-height:220px;padding:52px 0}.empty h2{font-size:27px;font-family:Georgia,"Noto Serif TC",serif;font-weight:500}.empty p{color:#66796c}.pagination{margin:26px 0}.article-page{max-width:900px;padding:75px 30px 140px;margin:auto}.back{font-size:13px;color:#5c7768}.article-page article{margin-top:75px}.article-page h1{font-size:clamp(44px,5vw,75px)}.lede{font-size:21px;line-height:1.75;color:#52685a}.prose{border-top:1px solid #cbd5ca;margin-top:45px;padding-top:28px;line-height:1.95;font-size:17px;color:#33473c}.prose p{margin:0 0 1.2em}footer{border-top:1px solid #d5ddd3;max-width:1440px;margin:auto;padding:28px clamp(24px,5vw,80px);display:flex;justify-content:space-between;font-size:12px;color:#788b7d}@media(max-width:700px){.topbar{height:68px}.topbar nav{gap:16px;font-size:12px}.hero{padding-top:74px;padding-bottom:70px}.hero-copy{font-size:16px}.feature-grid{grid-template-columns:1fr;gap:26px}.article-row{grid-template-columns:1fr 26px;gap:10px}.article-number{grid-column:1/-1;margin:0}.article-page{padding-top:55px}.article-page article{margin-top:50px}footer{gap:20px}}

package/docs/examples/host-chatgpt-sites/scripts/build.mjs

@@ -1,6 +1,7 @@
 import { build } from 'esbuild';
-import { cp, mkdir } from 'node:fs/promises';
+import { cp, mkdir, rm } from 'node:fs/promises';
 import { execFileSync } from 'node:child_process';
+await rm('dist',{recursive:true,force:true});
 execFileSync('node',['node_modules/@aotter/mantle/dist/cli/main.js','generate'],{stdio:'inherit'});
 // Reject older published SDKs that cannot advertise the mounted MCP endpoints.
 execFileSync('node',['node_modules/typescript/bin/tsc','--noEmit'],{stdio:'inherit'});

package/docs/examples/host-chatgpt-sites/scripts/check.mjs

@@ -76,6 +76,8 @@ assert.match(publicPage,new RegExp(mediaUrl));
 assert.doesNotMatch(publicPage,/href="javascript:/);
 assert.match(publicPage,/<meta property="og:image"/);
 assert.match(publicPage,/<link rel="canonical"/);
+assert.match(publicPage,/<link rel="alternate" type="text\/markdown"/);
+assert.doesNotMatch(publicPage,/<a\b[^>]*href="[^"]+\.md(?:[?#][^"]*)?"/);
 assert.match(publicPage,/application\/ld\+json/);
 assert.match(await (await call(`/articles/${entry.id}.md`)).text(),/Published body from Mantle/);
 assert.match(await (await call('/articles')).text(),new RegExp(entry.id));

package/docs/examples/host-chatgpt-sites/scripts/migration.mjs

@@ -1,9 +1,43 @@
-// One-time, reviewable initial migration from Mantle's public migration planner.
-import { buildSqliteMigrationArtifact, splitSqlStatements } from '@aotter/mantle/runtime';
-import { plan } from '../.mantle/generated/mantle.ts';
-import { writeFile } from 'node:fs/promises';
-const artifact=await buildSqliteMigrationArtifact([],Object.values(plan.schemas).map(s=>s.manifest));
-const quote=value=>`'${value.replaceAll("'","''")}'`;
-const sql=[...artifact.migrations.flatMap(m=>splitSqlStatements(m.sql).map(s=>s+';')),...artifact.projections.map(p=>`INSERT INTO _mantle_schema_tables(name,projection) VALUES (${quote(p.name)},${quote(p.projection)});`),`INSERT INTO _mantle_storage_state(id,fingerprint) VALUES (1,${quote(artifact.targetFingerprint)});`].join('\n--> statement-breakpoint\n');
-await writeFile('drizzle/0001_mantle.sql',sql);
+// Append a reviewed D1 migration only after the previous one is applied locally.
+import { buildSqliteMigrationArtifact, renderSqliteManagedMigration } from '@aotter/mantle/runtime';
+import { parseManifestSources, ValidateManifestsUseCase } from '@aotter/mantle/spec';
+import { execFileSync } from 'node:child_process';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+const statePath='drizzle/meta/mantle-state.json';
+const state=JSON.parse(await readFile(statePath,'utf8'));
+const files=(await readdir('manifests')).filter(name=>/\.ya?ml$/i.test(name)).sort();
+const parsed=parseManifestSources({sources:await Promise.all(files.map(async name=>({sourceId:name,text:await readFile(`manifests/${name}`,'utf8')})))});
+if(!parsed.ok)throw Error(`Invalid manifest: ${parsed.diagnostics.map(d=>d.message).join('; ')}`);
+const validated=ValidateManifestsUseCase.run({parsed:parsed.value});
+if(validated.errorCount)throw Error(`Invalid manifest: ${validated.diagnostics.filter(d=>d.severity==='error').map(d=>d.message).join('; ')}`);
+const target=parsed.value.entries.map(entry=>entry.manifest).filter(manifest=>manifest.kind==='Schema');
+const artifact=await buildSqliteMigrationArtifact(state.schemas,target,{appliedMigrationIds:state.appliedMigrationIds});
+if(artifact.sourceFingerprint!==state.fingerprint)throw Error('The saved migration source fingerprint is invalid. Restore the applied state before generating.');
+if(artifact.destructive)throw Error('Destructive Schema change needs a reviewed migration; no D1 file was written.');
+const unchanged=artifact.sourceFingerprint===artifact.targetFingerprint&&artifact.migrations.length===0;
+const fingerprint=JSON.parse(await readFile('src/storage-fingerprint.json','utf8'));
+if(fingerprint!==state.fingerprint)throw Error('Generated fingerprint and migration source disagree. Restore the reviewed migration state.');
+if(process.argv.includes('--check')){
+  if(!unchanged)throw Error('Pending Schema or runtime migration. Run node scripts/migration.mjs and review the new D1 file.');
+  process.exit(0);
+}
+const output=execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command','SELECT fingerprint FROM _mantle_storage_state WHERE id = 1','--json'],{encoding:'utf8'});
+const active=JSON.parse(output)[0]?.results?.[0]?.fingerprint;
+if(active!==state.fingerprint)throw Error(`Local D1 fingerprint ${active??'(missing)'} does not match the last migration ${state.fingerprint}. Apply pending D1 migrations first.`);
+const versionOutput=execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command',"SELECT name FROM sqlite_schema WHERE type='table' AND name='_mantle_managed_runtime_state'",'--json'],{encoding:'utf8'});
+const versionTable=JSON.parse(versionOutput)[0]?.results?.[0]?.name;
+const version=versionTable?(JSON.parse(execFileSync('node',['node_modules/wrangler/bin/wrangler.js','d1','execute','mantle-sites-reference-local','--local','--command','SELECT canonical_version FROM _mantle_managed_runtime_state WHERE id = 1','--json'],{encoding:'utf8'}))[0]?.results?.[0]?.canonical_version??null):null;
+if(version!==null&&version!==state.canonicalVersion)throw Error(`Local D1 runtime version ${version} does not match migration source ${state.canonicalVersion}.`);
+if(version===null&&state.canonicalVersion!=='0005-store-instance-id')throw Error('Local D1 is missing the managed runtime version marker. Apply pending migrations first.');
+if(unchanged){console.log('D1 migrations are current.');process.exit(0);}
+const sql=renderSqliteManagedMigration(artifact,{canonicalVersion:state.canonicalVersion});
+const index=state.lastIndex+1;
+const path=`drizzle/${String(index).padStart(4,'0')}_mantle.sql`;
+const journalPath='drizzle/meta/_journal.json';
+const journal=JSON.parse(await readFile(journalPath,'utf8'));
+if(journal.entries.at(-1)?.idx!==state.lastIndex)throw Error('Drizzle journal does not match the saved migration state.');
+await writeFile(path,sql,{flag:'wx'});
+await writeFile(journalPath,JSON.stringify({...journal,entries:[...journal.entries,{idx:index,version:'6',when:Date.now(),tag:`${String(index).padStart(4,'0')}_mantle`,breakpoints:true}]})+'\n');
+await writeFile(statePath,JSON.stringify({fingerprint:artifact.targetFingerprint,canonicalVersion:artifact.targetCanonicalVersion,schemas:target,appliedMigrationIds:[...new Set([...state.appliedMigrationIds,...artifact.migrations.map(m=>m.id)])],lastIndex:index},null,2)+'\n');
 await writeFile('src/storage-fingerprint.json',JSON.stringify(artifact.targetFingerprint)+'\n');
+console.log(`Review ${path}, then apply it with wrangler d1 migrations apply mantle-sites-reference-local --local.`);

package/docs/examples/host-chatgpt-sites/src/chatgpt-auth.ts

@@ -24,13 +24,16 @@ export function createChatGPTAuth(env: Env): AdminAuth {
     basePath:'/api/auth', methods:[],
     async getSession(request) {
       const who=readIdentity(request); if(!who)return null;
-      // Only the configured owner can bootstrap privilege; a later role revocation persists.
-      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();
-      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();
-      const row=await db.prepare('SELECT * FROM sites_users WHERE id=?').bind(who.id).first<UserRow>();
+      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:{...who,role:row.role,roleCurrent:true}};
+      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) {

package/docs/examples/host-chatgpt-sites/src/index.ts

@@ -23,7 +23,7 @@ function assemble(env:Env) {
   mountWeb(app,get);
   mountMcp(app,get,auth);
   mountMedia(app,auth,env);
-  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites',mantle:'0.1.2'});});
+  app.get('/health',async()=>{await get();return Response.json({ok:true,storage:'D1',auth:'ChatGPT Sites'});});
   app.get('/admin/sign-in',async c=>{
     if(c.req.header('cookie')?.split(';').some(v=>v.trim()==='mantle-sites-signout=1')) {
       c.header('Set-Cookie','mantle-sites-signout=; Path=/admin/sign-in; HttpOnly; SameSite=Strict; Max-Age=0'+(env.PUBLIC_ORIGIN.startsWith('https:')?'; Secure':''));

package/docs/examples/host-chatgpt-sites/src/web.ts

@@ -26,7 +26,7 @@ export function mountWeb(app:Hono<{Bindings:Env}>,get:()=>Promise<MantleAdminRun
     const title=String(entry.data.title??site.title);
     const image=coverUrl?`<figure class="article-cover"><img src="${escape(coverUrl)}" alt="${escape(cover?.alt||title)}" loading="eager"></figure>`:'';
     const body=micromark(String(entry.data.body??''),{allowDangerousHtml:false,allowDangerousProtocol:false});
-    return c.html(shell(`${title}｜${site.title}`,renderSeoTagsHtml(seo),`<main class="article-page"><a class="back" href="/articles">← 返回文章</a><article><p class="eyebrow">ARTICLE · ${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</p><h1>${escape(title)}</h1>${entry.data.summary?`<p class="lede">${escape(entry.data.summary)}</p>`:''}${image}<div class="prose">${body}</div>${seo.alternateMarkdown?`<a class="markdown-link" href="${articlePath(entry.id)}.md">閱讀 Markdown 版本 ↗</a>`:''}</article></main>`));});
+    return c.html(shell(`${title}｜${site.title}`,renderSeoTagsHtml(seo),`<main class="article-page"><a class="back" href="/articles">← 返回文章</a><article><p class="eyebrow">ARTICLE · ${new Date(entry.updatedAt).toLocaleDateString('zh-TW',{timeZone:'UTC'})}</p><h1>${escape(title)}</h1>${entry.data.summary?`<p class="lede">${escape(entry.data.summary)}</p>`:''}${image}<div class="prose">${body}</div></article></main>`));});
   // ponytail: one discovery page is enough for this lab; expose cursor pages when published articles exceed the SDK page limit.
   app.get('/llms.txt',async c=>{const {site,web}=await load();const page=await web.composeLlmsTxt.execute({collections:['articles'],locale:null,site,pathFor:e=>articlePath(e.id)});const body=page?.body??`# ${site.title}\n\n文章索引：${site.origin}/articles\n`;return c.text(body,200,{'Content-Type':'text/plain; charset=utf-8'});});
   // ponytail: first 1000 published URLs; add sitemap index parts only when the catalogue reaches that ceiling.

package/docs/examples/host-local-admin-otp/package.json

@@ -21,9 +21,9 @@
     "aws4fetch": "^1.0.20"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
+    "@cloudflare/workers-types": "5.20260904.1",
     "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
+    "wrangler": "4.129.0"
   },
   "packageManager": "pnpm@9.15.0"
 }

package/docs/examples/host-minimal-worker/README.md

@@ -9,15 +9,15 @@ Schema/View is example business data; `mantle generate` never invents it.
 
 For your own project, author package.json, manifests, Worker/provider config
 and TypeScript settings for your requirements. Pin all selected `@aotter/mantle*`
-dependencies to the same intended release. This reference depends on them via
-the `latest` dist-tag instead, so a fresh install always resolves the current
-stable release; Core's test runner substitutes its exact candidate in a
-disposable copy.
+dependencies to the same intended release. The checked-in `latest` values are
+placeholders for Core's disposable release test; resolve and pin one exact
+version before installing a copied application.
 
 Outside the SDK workspace, with Node 22+ and pnpm 9+:
 
 ```sh
-pnpm install
+MANTLE_VERSION=$(pnpm view @aotter/mantle@latest version)
+pnpm add --save-exact "@aotter/mantle@$MANTLE_VERSION" "@aotter/mantle-cloudflare@$MANTLE_VERSION"
 pnpm check
 pnpm dev
 ```

package/docs/examples/host-minimal-worker/package.json

@@ -18,9 +18,9 @@
     "aws4fetch": "^1.0.20"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^5.20260907.1",
+    "@cloudflare/workers-types": "5.20260904.1",
     "typescript": "^6.0.3",
-    "wrangler": "^4.125.0"
+    "wrangler": "4.129.0"
   },
   "packageManager": "pnpm@9.15.0"
 }

package/docs/handbook/{sites → chatgpt-sites}/equipment-checkout.md

@@ -208,7 +208,7 @@ because the underlying host composition or a different provider succeeded.
 
 ```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.
+SDK's docs/handbook/chatgpt-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

package/docs/handbook/chatgpt-sites/generated-app.md

@@ -0,0 +1,84 @@
+---
+description: Generate a blank Mantle app for ChatGPT Sites, apply D1 migrations, and verify local Admin and MCP.
+---
+# Generate a ChatGPT Sites app
+
+`mantle generate --host chatgpt-sites` creates a blank home, a D1-backed Runtime,
+public API and MCP, and Mantle Admin. It adds no article Schema, media bucket, or
+demo content. Edit `src/home.ts` and add your own manifests and handlers as needed.
+
+```sh
+mkdir my-site && cd my-site
+npm init -y
+npm pkg set type=module
+npm install --save-exact @aotter/mantle
+npx mantle generate --host chatgpt-sites
+npm install
+npx mantle generate
+npm run build
+npx wrangler d1 migrations apply my-site --local
+```
+
+The first generate declares the exact Mantle package versions it needs; the
+second runs after those packages are installed. Review `drizzle/0000_mantle.sql`
+before applying it. The D1 name comes from `wrangler.jsonc`. Generation does not
+apply a migration, provision a Site, or publish one. `npm run build` removes the
+old `dist` before copying the current migrations and Admin assets.
+
+For local Admin, copy `.dev.vars.example` to `.dev.vars`, set `OWNER_EMAIL` to
+the email of the ChatGPT account that will own this Site, and keep
+`PUBLIC_ORIGIN` equal to the local URL. Run `npm run dev`.
+The plain local browser has no ChatGPT Sites identity, so it will redirect to
+Sites sign-in and cannot prove owner access. To exercise the identity contract
+locally, set `MANTLE_TEST_OWNER_EMAIL` to the same email and run
+`npm run smoke:local`. That script refuses non-loopback
+targets. Its identity headers are a local simulation; the production Worker
+contains no identity-injection path and must run behind Sites' trusted
+identity-stripping dispatcher. The generated Wrangler config disables the
+independent `workers.dev` URL; do not add a direct Worker route. A passing
+local smoke does not verify a deployed ChatGPT sign-in.
+
+Without `OWNER_EMAIL`, sign-in grants no Mantle staff role. If the intended
+owner signed in before configuration, their existing `sites_users` row remains
+unprivileged. Configure the owner email and deliberately assign `role='owner'`
+to that account's exact email and `chatgpt:` ID in D1, or reset a disposable
+local database and sign in again. Mantle never gives ownership to the first
+visitor.
+
+The anonymous public MCP endpoint is `/api/mcp`; it discovers only public
+manifest capabilities. `/api/mcp/staff` uses the current Sites browser session
+and a Mantle staff role. Admin advertises these endpoints, and Admin WebMCP
+works in supporting browsers. The staff endpoint is not a remote OAuth MCP
+connector. A remote agent needs a separately implemented verified OAuth flow.
+
+When a Schema changes, run `npx mantle generate --check` to detect drift, then
+`npx mantle generate`. Review the newly appended SQL and apply pending D1
+migrations before deploying code that expects the new Schema. Previous
+migration files remain untouched; an unapplied migration keeps the old database
+fingerprint, and managed boot refuses to use an older database. Sites owns
+`.openai/hosting.json` project metadata and production D1 migration delivery.
+
+Replacing a Schema's `uniqueIndexes` tuple requires an explicit reviewed
+migration. With the old local D1 migration applied, edit the Manifest and run
+`npx mantle generate --review-unique-indexes --check` to inspect the proposed
+source/target fingerprints, affected tuples and checksum without writing. Then
+run `npx mantle generate --review-unique-indexes`, review the new
+`drizzle/meta/000N_mantle.review.json` and matching SQL, and apply that SQL
+through the normal Sites D1 migration path. The CLI checks **local D1 only**
+for duplicate target tuples and reports a count and sample before writing;
+inspect production data separately before applying there. SQLite also refuses
+to create the new unique index if production has conflicts; do
+not deploy the target Worker until the migration has succeeded. Old Workers
+cannot safely reactivate after the old uniqueness guarantee is removed.
+This option is limited to managed Sites SQLite and unique tuple changes;
+field conversions and runtime-managed CF boot still reject destructive
+changes.
+
+For a complete article, media, and publishing example, use the
+[Sites reference](../../examples/host-chatgpt-sites/README.md).
+
+## Source
+
+- [Sites generator](../../../packages/mantle/src/cli/generate-sites.ts)
+- [Generated Sites templates](../../../packages/mantle/templates/chatgpt-sites)
+- [Runnable Sites reference](../../examples/host-chatgpt-sites/README.md)

package/docs/handbook/{sites → chatgpt-sites}/index.md

@@ -16,6 +16,10 @@ 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).
 
+For a new project, start with the [blank generated app](./generated-app.md).
+The article reference below demonstrates a complete editorial Site with R2
+media after you choose that content model.
+
 ## What you get
 
 | Capability | In the Mantle Sites reference |
@@ -34,12 +38,17 @@ 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.
+You need Node.js 22+ and Sites access with D1. Start with the
+[blank generated app](./generated-app.md) to choose your own content model;
+it requires no R2 bucket. The article reference also needs R2 for cover
+images. Build and smoke-test locally before deployment, and keep your
+application outside the SDK checkout.
+
+## Follow the article reference when it fits
 
-## Publish your first article
+The steps below apply to the optional prebuilt article example. A new blank
+generated Site has no article Schema, media bucket or content; add those only
+when your requirements call for them.
 
 1. **Prepare the application.** Follow the
    [runnable reference](../../examples/host-chatgpt-sites/README.md#install-and-run).
@@ -56,7 +65,8 @@ a working example; adapt its fields and lifecycle to your team's content.
    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
+   link to check the body and cover, then confirm the page head advertises
+   its `.md` version with `rel="alternate"` and `type="text/markdown"`. 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
@@ -67,23 +77,34 @@ 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.
 
+## Maintain content with an agent
+
+The owner can use Admin WebMCP in a browser that supports it to let an agent
+discover staff tools for drafts, publishing, and other permitted operations.
+Open `/admin/dev/docs/webmcp` to see that browser surface and
+`/admin/dev/docs/mcp` to see the Site's `/api/mcp` public read-only endpoint and `/api/mcp/staff`
+staff endpoint. The latter uses the current Sites browser session and checks
+the Mantle staff role on each request. It is useful to same-origin browser
+code, but is not a remote OAuth MCP connector for a desktop agent. A remote
+staff connector needs its own verified OAuth flow; see the [host reference](./host-reference.md#remote-mcp-is-a-separate-gate).
+
 ## Ask your agent to set it up
 
-Install the Mantle agent plugin, or `@aotter/mantle` itself, then describe your
-audience and content requirements:
+Install the Mantle skill and exact SDK version, 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.
+handbook/chatgpt-sites/generated-app.md from the installed Mantle docs, and
+start from the blank generated Site when that CLI supports it. Use the article
+reference only if its content model matches my requirements. Include ChatGPT
+sign-in and Mantle staff roles; add cover uploads only if I request media.
 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."
+application-owned tables as described in handbook/chatgpt-sites/equipment-checkout.md."
 
 ## Beyond content: operational workflows
 
@@ -100,6 +121,7 @@ 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.
+- [Generated blank app](./generated-app.md): local composition, D1 migration, Admin, and MCP.
 - [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.

package/docs/handbook/cloudflare/authentication.md

@@ -7,11 +7,28 @@ Conventional Auth is chosen by one variable, `MANTLE_AUTH_MODE`, and fails close
 
 ## Local Admin: email OTP
 
-The local human path does not use `MANTLE_AUTH_MODE` or GitHub. Pass `auth` to `createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and `bootstrapOwner.match: "email"`. The one-time code is printed on the wrangler log. See [Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender` is for `wrangler dev` only; production needs a real sender. The official example binds `127.0.0.1:8787` and sets `PUBLIC_ORIGIN` to that origin; Better Auth rejects OTP with `INVALID_ORIGIN` when they diverge from the origin wrangler prints.
+The generated CF app writes `.dev.vars.example`. Copy it to `.dev.vars` for
+local use, then set `MANTLE_AUTH_MODE=local-otp`, the real `ADMIN_EMAIL`, a
+random `BETTER_AUTH_SECRET`, and the exact loopback `PUBLIC_ORIGIN`. It configures
+its email-OTP auth factory only for a
+loopback origin. If you author the Worker yourself, pass `auth` to
+`createMantleWorker` with `email-otp`, `ConsoleEmailSender`, and
+`bootstrapOwner.match: "email"`; that factory does not read the conventional
+mode matrix. The one-time code is printed in wrangler logs. See
+[Quickstart: local Admin](../start/quickstart-admin.md). `ConsoleEmailSender`
+is for `wrangler dev` only; production needs a real sender. Match
+`PUBLIC_ORIGIN` to wrangler's actual `127.0.0.1:8787` origin or Better Auth
+will reject OTP with `INVALID_ORIGIN`.
+
+For production, the generated Worker's local OTP branch is disabled outside
+loopback. Configure the conventional `self-managed` or `hosted` Auth mode,
+including its required provider credentials and `ADMIN_GITHUB_LOGIN`, instead
+of editing the CLI-owned Worker. An application that needs production email
+delivery should author its own Worker Auth factory and real `EmailSender`.
 
 With `auth` set, the mode matrix below is not read. Core still owns `/admin` and `/api/auth/*`.
 
-For production email OTP, keep the custom `createAuth()` factory, replace
+For production email OTP in a manually authored Worker, keep the custom `createAuth()` factory, replace
 `ConsoleEmailSender` with the application's production `EmailSender`, and keep
 `bootstrapOwner: { match: "email", value: <owner email> }`. Store the sender
 credentials and `BETTER_AUTH_SECRET` as Worker secrets. If the application has

package/docs/handbook/cloudflare/bindings.md

@@ -186,26 +186,19 @@ the interface is one `record(event)` method.
 "triggers": { "crons": ["*/5 * * * *"] }
 ```
 
-A `scheduled()` handler reuses the fetch path's runtime and invokes a Procedure that has no Trigger of its own:
+A `schedule` Trigger declares the Procedure, and the Worker export reuses the same runtime as `fetch`:
 
 ```ts
-import { bindMantle } from "../.mantle/generated/mantle.js";
-
 const worker = createMantleWorker<Env>({ plan, handlers });
 
 export default {
   fetch: worker.fetch,
-  async scheduled(_controller, env, ctx) {
-    const mantle = bindMantle(await worker.getRuntime(env));
-    const result = await mantle.procedures.sweepExpiredOrders(
-      { now: Date.now() },
-      { user: null, staff: null, env, waitUntil: (p) => ctx.waitUntil(p) },
-    );
-    if (!result.ok) throw new Error(`sweep failed: ${result.diagnostic.code}`);
-  },
+  scheduled: worker.scheduled,
 } satisfies ExportedHandler<Env>;
 ```
 
+Register the exact enabled `cron` expression in `wrangler.jsonc`; Mantle does not create provider triggers. The Procedure takes `{}` input and sees `ctx.schedule.id` for retry-safe idempotency. See [Trigger](../reference/trigger.md#schedule-source).
+
 ## Durable Objects (application-owned)
 
 Durable Objects are not a Core primitive. Use one as an application-owned coordinator when a decision must be serialized, for example reserving inventory exactly once. Export the class from the Worker entry, then bind and migrate it:

package/docs/handbook/cloudflare/chatgpt-sites.md

@@ -4,26 +4,26 @@ description: "Mantle on ChatGPT Sites now has its own integration guide."
 # Mantle on ChatGPT Sites
 
 ChatGPT Sites has a dedicated section in the Mantle handbook. Start with
-[Mantle on ChatGPT Sites](../sites/index.md) for installation, supported
+[Mantle on ChatGPT Sites](../chatgpt-sites/index.md) for installation, supported
 capabilities, and your first published article. This page preserves earlier
 links to the host checklist.
 
 ## First deployment
 
-See [the host deployment checklist](../sites/host-reference.md#first-deployment).
+See [the host deployment checklist](../chatgpt-sites/host-reference.md#first-deployment).
 
 ## Media with only an R2 binding
 
-See [R2 media integration](../sites/host-reference.md#media-with-only-an-r2-binding).
+See [R2 media integration](../chatgpt-sites/host-reference.md#media-with-only-an-r2-binding).
 
 ## Remote MCP is a separate gate
 
-See [MCP support and authentication](../sites/host-reference.md#remote-mcp-is-a-separate-gate).
+See [MCP support and authentication](../chatgpt-sites/host-reference.md#remote-mcp-is-a-separate-gate).
 
 ## Capability boundaries
 
-See [host capability boundaries](../sites/host-reference.md#capability-boundaries).
+See [host capability boundaries](../chatgpt-sites/host-reference.md#capability-boundaries).
 
 ## Source
 
-See [integration sources](../sites/host-reference.md#source).
+See [integration sources](../chatgpt-sites/host-reference.md#source).

package/docs/handbook/cloudflare/conventional-worker.md

@@ -3,7 +3,10 @@ description: Assemble a Mantle Worker with createMantleWorker, add handlers and
 ---
 # The conventional Worker
 
-`createMantleWorker` is the normal Cloudflare entry for a Mantle application. This page covers its options, what the facade owns, how to add application handlers and routes, and the readiness and reserved-path rules that keep those extensions safe.
+New applications can start with `mantle generate --host cf`, which writes a
+blank home, Worker entry and selected Admin/API/MCP wiring. This page covers
+the lower-level `createMantleWorker` facade for applications that author their
+own Worker entry: its options, extension seam, readiness and reserved paths.
 
 ## Minimal entry
 
@@ -14,7 +17,7 @@ import { plan } from "../.mantle/generated/mantle.js";
 export default createMantleWorker({ plan, cacheScope: "my-site-production" });
 ```
 
-`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, the Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md). Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
+`plan` is the sealed plan that `mantle generate` writes to `.mantle/generated/mantle.ts`. With only `plan`, this manually assembled Worker serves public View REST, HTTP Triggers, Admin, Auth, OAuth and MCP. It renders no public pages and `/` is a 404; see [Public web](./public-web.md). A newly generated full CF project wires a separate editable blank home. Local Admin with email OTP replaces Auth construction; see [Quickstart: local Admin](../start/quickstart-admin.md). Admin still requires the `ASSETS` binding.
 
 ## Options
 
@@ -64,9 +67,10 @@ If `auth.ready` rejects, the memoized assembly is evicted so the next request re
 const worker = createMantleWorker<Env>({ plan });
 worker.fetch(request, env, ctx);   // HTTP entry
 worker.getRuntime(env);            // the runtime fetch uses, resolved after auth.ready
+worker.scheduled(controller, env, ctx); // declared scheduled Procedure Triggers
 ```
 
-Queue and scheduled handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime and never write Mantle tables directly. See [Bindings](./bindings.md#cron-triggers) and [Deferred hooks](./deferred-hooks-queues.md).
+Queue handlers call `worker.getRuntime(env)` and then generated `bindMantle(runtime)` so they reuse the assembled runtime. Scheduled Procedure Triggers use `worker.scheduled` with expressions registered in Wrangler. See [Bindings](./bindings.md#cron-triggers), [Trigger](../reference/trigger.md#schedule-source), and [Deferred hooks](./deferred-hooks-queues.md).
 
 ## Readiness rule
 

package/docs/handbook/cloudflare/deploy-and-operate.md

@@ -10,7 +10,7 @@ This page is the production checklist for a Mantle Worker on Cloudflare: what to
 - Pin every `@aotter/mantle*` package to one exact version and commit the lockfile. Install with `pnpm install --frozen-lockfile` (or `npm ci`) from then on. See [Project and CLI](../start/project-and-cli.md).
 - Set `PUBLIC_ORIGIN` to the real HTTPS origin, without a trailing slash. It drives canonical URLs, `.md` mirrors, `llms.txt`, the MCP resource and the OAuth callback. If a static documentation build also emits absolute URLs, give it the same value.
 - Set the production D1 `database_id` (and `account_id` if your deployment needs it) in `wrangler.jsonc`. A local `database_name` is not a production identifier, and local D1 is not production data.
-- Choose production Auth: replace local console email delivery with a real `EmailSender`, or configure `MANTLE_AUTH_MODE` for GitHub OAuth or hosted Auth. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
+- Choose production Auth: a generated CF app uses `MANTLE_AUTH_MODE=self-managed` or `hosted` with `ADMIN_GITHUB_LOGIN` and the matching provider credentials. Local `local-otp` works only on loopback. If you author your own Worker Auth factory, replace console email delivery with a real `EmailSender`. Store secrets with `wrangler secret put`. See [Authentication](./authentication.md).
 - Keep `compatibility_flags: ["nodejs_compat", "global_fetch_strictly_public"]`.
 - Enable observability:
 
@@ -47,7 +47,8 @@ wrangler deploy
 
 ## Post-deploy verification
 
-Probe the deployed origin, not `wrangler dev`:
+Probe the deployed origin, not `wrangler dev`. Run only the probes for surfaces
+the application mounts and configures:
 
 | Probe | Expect |
 |---|---|
@@ -55,7 +56,7 @@ Probe the deployed origin, not `wrangler dev`:
 | `GET /<locale>/<segment>/<slug>` and `GET /<locale>/<segment>/<slug>.md` | `200` HTML and Markdown for a published entry |
 | `GET /llms.txt`, `GET /sitemap.xml`, `GET /robots.txt` | `200` |
 | `GET /<locale>/<segment>/does-not-exist` | `404` from your `notFoundRenderer` |
-| `GET /mcp` without credentials | `401` with `WWW-Authenticate` |
+| `POST /mcp/staff` without credentials | `401` with `WWW-Authenticate`; `GET /mcp` is `405` |
 | `GET /admin` | Sign-in page; sign in with the `ADMIN_GITHUB_LOGIN` account |
 
 Then check the cache: a second anonymous `GET` of a public page should show `cf-cache-status: HIT`; publish a change in Admin and the next request should be a `MISS`. Sample latency with: