create-ampless 0.2.0-alpha.9 → 1.0.0-alpha.39

package/README.ja.md

@@ -0,0 +1,77 @@
+> English: [README.md](./README.md)
+> 
+
+# create-ampless
+
+[ampless](https://github.com/heavymoons/ampless) プロジェクト向け CLI スキャフォールディングツール。
+
+> **プレリリース / アルファ版。** v1.0 まではマイナーバージョンでも破壊的変更が入る可能性があります。`@alpha` タグを使用してください（`@latest` タグは v1.0 まで存在しません）。
+
+```bash
+npx create-ampless@alpha
+```
+
+ウィザードが以下を順に案内します：
+
+1. プロジェクト名
+2. サイト名（デフォルトの `<title>` および OGP `siteName` として使用）
+3. テーマ — v0.1 では `blog`
+4. プラグイン — `seo`、`rss`、`webhook`
+
+出力は AWS Amplify Gen 2 バックエンド定義を含む Next.js 16（App Router）プロジェクトです。`/admin` に管理パネル、`/` にパブリックブログが設置され、選択したプラグインが `cms.config.ts` にあらかじめ設定されます。また運用メモ用の `RUNBOOK.md` も生成されます。
+
+## 生成されたプロジェクトでの次のステップ
+
+```bash
+cd my-project
+npm install
+npx ampx sandbox        # AWS 開発リソースをプロビジョニングし amplify_outputs.json を生成
+npm run dev             # http://localhost:3000
+```
+
+`/login` でサインアップすると、最初に登録したユーザーが自動的に `ampless-admin` Cognito グループに昇格します。
+
+## ワンショットデプロイ：`--deploy`
+
+ウィザードは `npx` から Amplify Hosting の URL まで一気に進めることもできます：
+
+```bash
+npx create-ampless@alpha my-site --deploy
+```
+
+このフラグを追加すると、スキャフォールディング後に以下が実行されます：
+
+1. `git init` + 初回コミット
+2. GitHub リポジトリを作成（`gh repo create`）してプッシュ
+3. 新しいリポジトリに紐付けた `aws amplify create-app`
+4. `aws amplify create-branch main`
+5. `aws amplify start-job --job-type RELEASE`
+6. `--domain` を指定した場合はオプションで `aws amplify create-domain-association`
+
+コマンドラインに指定が不足している場合はインタラクティブに確認します。CI 向けのフル指定の例：
+
+```bash
+npx create-ampless@alpha my-site --deploy \
+  --github-owner my-org \
+  --github-private \
+  --aws-region us-east-1 \
+  --domain example.com --subdomain blog \
+  --skip-confirm
+```
+
+apex ドメインが同じ AWS アカウントの Route 53 でホストされている場合、ACM の検証が完了すると Amplify が DNS レコードを自動作成します。それ以外の場合、CLI がレジストラで追加すべき正確な CNAME を表示します。
+
+### デプロイの要件
+
+- [`gh`](https://cli.github.com/) のインストールと認証（`gh auth login`）
+- [`aws`](https://aws.amazon.com/cli/) のインストールと設定（`aws configure`）
+- `repo` スコープを持つ GitHub トークン（`--github-token` → `GITHUB_TOKEN` 環境変数 → `gh auth token` → インタラクティブプロンプトの順で解決）
+
+## 動作要件
+
+- Node.js >= 20
+- AWS アカウントと `aws configure` の設定済み（サンドボックス / パイプラインデプロイは AWS に直接アクセスします）
+
+## ライセンス
+
+[MIT](../../LICENSE)

package/README.md

@@ -1,3 +1,6 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+
 # create-ampless
 
 CLI scaffolding tool for [ampless](https://github.com/heavymoons/ampless) projects.
@@ -15,7 +18,7 @@ The wizard walks you through:
 3. Theme — `blog` for v0.1
 4. Plugins — `seo`, `rss`, `webhook`
 
-Output is a Next.js 15 (App Router) project with the AWS Amplify Gen 2 backend definitions, an admin panel at `/admin`, public blog at `/`, the chosen plugins pre-wired in `cms.config.ts`, and a `RUNBOOK.md` for operations notes.
+Output is a Next.js 16 (App Router) project with the AWS Amplify Gen 2 backend definitions, an admin panel at `/admin`, public blog at `/`, the chosen plugins pre-wired in `cms.config.ts`, and a `RUNBOOK.md` for operations notes.
 
 ## Next steps inside the generated project
 

package/dist/index.js

@@ -435,9 +435,9 @@ function parseDeployArgs(argv) {
 var HELP_TEXT = `create-ampless \u2014 scaffold an ampless project
 
 Usage:
-  npx create-ampless@alpha <project-name> [options]
-  npx create-ampless@alpha --mount [options]    # in an existing project dir
-  npx create-ampless@alpha upgrade [options]    # in an existing project dir
+  npx create-ampless@latest <project-name> [options]
+  npx create-ampless@latest --mount [options]    # in an existing project dir
+  npx create-ampless@latest upgrade [options]    # in an existing project dir
 
 Options:
   --site-name <name>          Site display name (default: "My Blog")
@@ -487,7 +487,7 @@ copy-theme <source> <target>
          (the convention that flags it as user-owned, so upgrade leaves
          it alone). Run inside an existing ampless project.
 
-         Example: npx create-ampless@alpha copy-theme blog my-blog
+         Example: npx create-ampless@latest copy-theme blog my-blog
 `;
 
 // src/deploy-prompts.ts
@@ -1091,38 +1091,19 @@ function splitDomain(domain, subdomain) {
 async function rewriteCmsConfigForDomain(projectDir, fullDomain) {
   const path = resolve4(projectDir, "cms.config.ts");
   if (!existsSync4(path)) {
-    return { urlRewritten: false, sitesInjected: false };
+    return { urlRewritten: false };
   }
   let content = await readFile2(path, "utf-8");
   let urlRewritten = false;
-  let sitesInjected = false;
   const urlRe = /url:\s*['"]http:\/\/localhost:3000['"]/;
   if (urlRe.test(content)) {
     content = content.replace(urlRe, `url: 'https://${fullDomain}'`);
     urlRewritten = true;
   }
-  const sitesActiveRe = /^\s*sites:\s*\{/m;
-  if (!sitesActiveRe.test(content)) {
-    const siteCloseRe = /(\n(\s*)site:\s*\{[\s\S]*?\n\2\},)/;
-    const m = siteCloseRe.exec(content);
-    if (m) {
-      const indent = m[2] ?? "  ";
-      const inner = indent + "  ";
-      const innermost = inner + "  ";
-      const inject = `
-${indent}sites: {
-${inner}default: {
-${innermost}domains: ['${fullDomain}'],
-${inner}},
-${indent}},`;
-      content = content.replace(siteCloseRe, `$1${inject}`);
-      sitesInjected = true;
-    }
-  }
-  if (urlRewritten || sitesInjected) {
+  if (urlRewritten) {
     await writeFile2(path, content, "utf-8");
   }
-  return { urlRewritten, sitesInjected };
+  return { urlRewritten };
 }
 async function run(cmd, args, opts = {}) {
   const { step, ...execaOpts } = opts;
@@ -1503,11 +1484,8 @@ async function runDeploy(opts) {
     const { registrable, subdomain } = splitDomain(opts.domain, opts.subdomain);
     const fullDomain = subdomain ? `${subdomain}.${registrable}` : registrable;
     const mutations = await rewriteCmsConfigForDomain(opts.projectDir, fullDomain);
-    if (mutations.urlRewritten || mutations.sitesInjected) {
-      const parts = [];
-      if (mutations.urlRewritten) parts.push(`site.url \u2192 https://${fullDomain}`);
-      if (mutations.sitesInjected) parts.push(`sites.default.domains += ${fullDomain}`);
-      log.info(`cms.config.ts updated: ${parts.join(", ")}`);
+    if (mutations.urlRewritten) {
+      log.info(`cms.config.ts updated: site.url \u2192 https://${fullDomain}`);
     }
   }
   const created = {};
@@ -1761,6 +1739,14 @@ import { join as join3, relative, extname as extname2, dirname } from "path";
 import { log as log3, outro } from "@clack/prompts";
 import pc3 from "picocolors";
 import { execa as execa4 } from "execa";
+var AMPLESS_MANAGED_APP_PATHS = [
+  "app/(admin)/admin",
+  "app/api/admin",
+  "app/api/media",
+  "app/api/mcp",
+  "app/login",
+  "app/site"
+];
 var AMPLESS_PACKAGES = /* @__PURE__ */ new Set([
   "ampless",
   "@ampless/admin",
@@ -1882,6 +1868,63 @@ async function walkDir(dir, base, out) {
     }
   }
 }
+async function listFilesRecursive(root) {
+  const out = [];
+  async function walk(current, relPrefix) {
+    const entries = await readdir3(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+      if (entry.isDirectory()) {
+        await walk(join3(current, entry.name), rel);
+      } else if (entry.isFile()) {
+        out.push(rel);
+      }
+    }
+  }
+  if (!existsSync5(root)) return out;
+  await walk(root, "");
+  return out;
+}
+async function pruneEmptyDirs(root) {
+  if (!existsSync5(root)) return;
+  const entries = await readdir3(root, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      await pruneEmptyDirs(join3(root, entry.name));
+    }
+  }
+  const remaining = await readdir3(root);
+  if (remaining.length === 0) {
+    await rm2(root, { recursive: true, force: true });
+  }
+}
+async function findObsoleteAppFiles(destDir, sharedDir) {
+  const obsolete = [];
+  for (const managedPath of AMPLESS_MANAGED_APP_PATHS) {
+    const userPath = join3(destDir, managedPath);
+    if (!existsSync5(userPath)) continue;
+    const templatePath2 = join3(sharedDir, managedPath);
+    const templateFiles = new Set(await listFilesRecursive(templatePath2));
+    const userFiles = await listFilesRecursive(userPath);
+    for (const f of userFiles) {
+      if (!templateFiles.has(f)) {
+        obsolete.push(`${managedPath}/${f}`);
+      }
+    }
+  }
+  return obsolete;
+}
+async function removeObsoleteAppFiles(destDir, paths) {
+  for (const rel of paths) {
+    const abs = join3(destDir, rel);
+    if (existsSync5(abs)) {
+      await rm2(abs, { force: true });
+    }
+  }
+  for (const managedPath of AMPLESS_MANAGED_APP_PATHS) {
+    await pruneEmptyDirs(join3(destDir, managedPath));
+  }
+}
 function substituteVars(content, vars) {
   return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? `{{${key}}}`);
 }
@@ -1935,21 +1978,25 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
   const shippedThemes = themeSyncEnabled ? await listShippedThemes(templatesRoot) : [];
   const existingThemes = themeSyncEnabled ? await discoverInstalledThemes(destDir) : [];
   const preservedThemes = existingThemes.filter((t) => !shippedThemes.includes(t));
+  const obsoleteFiles = await findObsoleteAppFiles(destDir, sharedDir);
   log3.info(
-    `replace: ${pc3.green(`\u8FFD\u52A0 ${replaceNew.length}`)} / ${pc3.yellow(`\u66F4\u65B0 ${replaceUpdate.length}`)}`
+    `replace: ${pc3.green(`${replaceNew.length} added`)} / ${pc3.yellow(`${replaceUpdate.length} updated`)}`
   );
-  log3.info(`merge:   ${pc3.cyan("package.json: ampless deps / managed scripts \u3092\u30C6\u30F3\u30D7\u30EC\u5074\u306B\u5408\u308F\u305B\u308B")}`);
+  log3.info(`merge:   ${pc3.cyan("package.json: sync ampless deps and managed scripts with the template")}`);
   if (classification.seed.length > 0) {
     log3.info(
-      `seed:    ${pc3.green(`\u8FFD\u52A0 ${seedNew.length}`)} / ${pc3.dim(`\u65E2\u5B58\u30D5\u30A1\u30A4\u30EB\u306F\u4E0A\u66F8\u304D\u3057\u306A\u3044: ${seedSkipped.length}`)} (*.custom.ts)`
+      `seed:    ${pc3.green(`${seedNew.length} added`)} / ${pc3.dim(`${seedSkipped.length} kept (existing *.custom.ts left untouched)`)}`
     );
   }
   if (themeSyncEnabled) {
     log3.info(
-      `themes:  ${pc3.cyan(`\u30C7\u30D5\u30A9\u30EB\u30C8\u30C6\u30FC\u30DE\u3092\u540C\u671F: ${shippedThemes.length}`)} / ${pc3.dim(`\u30AB\u30B9\u30BF\u30E0\u30C6\u30FC\u30DE (my-*) \u3092\u4FDD\u6301: ${preservedThemes.length}`)}`
+      `themes:  ${pc3.cyan(`${shippedThemes.length} default themes synced`)} / ${pc3.dim(`${preservedThemes.length} custom (my-*) themes preserved`)}`
     );
   }
-  log3.info(`protected: ${pc3.dim(`\u30C6\u30F3\u30D7\u30EC\u306B\u5B58\u5728\u3059\u308B\u304C\u89E6\u3089\u306A\u3044: ${classification.protected.length} \u500B`)}`);
+  if (obsoleteFiles.length > 0) {
+    log3.info(`cleanup: ${pc3.yellow(`${obsoleteFiles.length} removed`)} (files under ampless-managed app/ paths that no longer exist in the template)`);
+  }
+  log3.info(`protected: ${pc3.dim(`${classification.protected.length} template files left untouched`)}`);
   if (opts.dryRun) {
     return {
       added: replaceNew,
@@ -1958,7 +2005,8 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
       protected: classification.protected,
       themesSynced: shippedThemes,
       themesPreserved: preservedThemes,
-      packageJsonMerged: false
+      packageJsonMerged: false,
+      obsoleteRemoved: obsoleteFiles
     };
   }
   for (const rel of classification.replace) {
@@ -1972,6 +2020,7 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
     await copyWithSubstitution(src, dst, vars);
   }
   const themeResult = themeSyncEnabled ? await syncThemes(destDir, templatesRoot) : { synced: [], preserved: [] };
+  await removeObsoleteAppFiles(destDir, obsoleteFiles);
   const templatePkgRaw = await readFile3(join3(sharedDir, "package.json"), "utf-8");
   const templatePkg = JSON.parse(templatePkgRaw);
   const indent = detectIndent(projectPkgRaw);
@@ -1988,9 +2037,12 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
   }
   const templateScripts = templatePkg["scripts"] ?? {};
   const projectScripts = projectPkg["scripts"] ?? {};
-  for (const [name, body] of Object.entries(templateScripts)) {
-    if (!AMPLESS_MANAGED_SCRIPTS.has(name)) continue;
-    projectScripts[name] = body;
+  for (const name of AMPLESS_MANAGED_SCRIPTS) {
+    if (name in templateScripts) {
+      projectScripts[name] = templateScripts[name];
+    } else {
+      delete projectScripts[name];
+    }
   }
   if (Object.keys(projectScripts).length > 0) {
     projectPkg["scripts"] = projectScripts;
@@ -2008,7 +2060,8 @@ async function runUpgradeIn(destDir, sharedDir, opts = {}) {
     protected: classification.protected,
     themesSynced: themeResult.synced,
     themesPreserved: themeResult.preserved,
-    packageJsonMerged: true
+    packageJsonMerged: true,
+    obsoleteRemoved: obsoleteFiles
   };
 }
 async function runUpgrade(args) {
@@ -2104,8 +2157,8 @@ async function runCopyTheme(args) {
   const source = args.copyThemeSource;
   const target = args.copyThemeTarget;
   if (!source || !target) {
-    log4.error("Usage: npx create-ampless@alpha copy-theme <source> <target>");
-    log4.info("Example: npx create-ampless@alpha copy-theme blog my-blog");
+    log4.error("Usage: npx create-ampless@latest copy-theme <source> <target>");
+    log4.info("Example: npx create-ampless@latest copy-theme blog my-blog");
     process.exit(1);
   }
   try {
@@ -2118,7 +2171,7 @@ async function runCopyTheme(args) {
 
   themes-registry.ts updated. Next:
     ${pc4.cyan(`Open themes/${result.target}/ and start customising`)}
-    ${pc4.cyan(`Activate via /admin/sites/<siteId>/theme`)}`
+    ${pc4.cyan(`Activate via /admin/sites/default/theme`)}`
     );
   } catch (err) {
     log4.error(err instanceof Error ? err.message : String(err));
@@ -2163,7 +2216,7 @@ async function runMount(args) {
   if (problem) {
     log5.error(problem);
     log5.info(
-      "Run `npx create-ampless@alpha <name>` first to scaffold, or `cd` into a scaffolded project before passing --mount."
+      "Run `npx create-ampless@latest <name>` first to scaffold, or `cd` into a scaffolded project before passing --mount."
     );
     process.exit(1);
   }
@@ -2269,8 +2322,7 @@ async function main() {
   Next steps:
     ${pc5.cyan("cd")} ${opts.projectName}
     ${pc5.cyan("npm install")}
-    ${pc5.cyan("npx ampx sandbox")}   ${pc5.dim("# start Amplify backend")}
-    ${pc5.cyan("npm run dev")}         ${pc5.dim("# start Next.js")}`
+    ${pc5.cyan("npm run sandbox")}   ${pc5.dim("# deploy sandbox + start Next.js")}`
   );
 }
 main().catch((err) => {

package/dist/templates/_shared/AGENTS.ja.md

@@ -0,0 +1,104 @@
+> English: [AGENTS.md](./AGENTS.md)
+> 
+# AGENTS.md
+
+このファイルは AI コーディングエージェント（Claude Code, Cursor, Codex など）が読む前提で書かれています。人間向けの日常利用ガイドは `README.ja.md` と `RUNBOOK.ja.md` を参照してください。
+
+## プロジェクトのレイアウト
+
+- `themes/<name>/` — インストール済みのテーマ（tokens、pages、manifest）。アクティブテーマの切り替えは `/admin/sites/<id>/theme` で行う。
+- `themes/my-<name>/` — ユーザーが所有するカスタマイズ済みのテーマコピー（`npm run copy-theme` で作成）。`my-` プレフィックスがついているコピーは `update-ampless` で上書きされない。
+- `themes-registry.ts` — 自動生成ファイル。手動で編集しない。
+- `amplify/` — TypeScript で定義された Amplify Gen 2 バックエンド（Cognito / DynamoDB / S3 / AppSync / Lambda）。
+- `amplify_outputs.json` — `npm run sandbox` / Amplify Hosting が生成するファイル。編集しない。
+- `app/` — Next.js 15 App Router（公開サイト + `/admin` UI）。
+- `components/` — 共有 UI コンポーネント。
+- `lib/` — 共有ユーティリティ（データアクセス、認証など）。
+- `cms.config.ts` — サイト、プラグイン、デフォルト設定。
+- `proxy.ts` — リクエストプロキシの設定。
+
+## 触っていい場所・ダメな場所
+
+**自由に編集可能:**
+- `themes/my-*/` — ユーザー自身のテーマコピー。
+- `cms.config.ts` — サイト / プラグインの設定。
+- 投稿コンテンツは管理 UI（推奨）または MCP サーバー経由で操作する。
+
+**注意して触る（編集前に理由を説明すること）:**
+- `app/`、`components/`、`lib/` — 共有シェルの一部。`update-ampless` 後も編集は残るが、上流が同じファイルを変更した場合のマージはユーザー側の責任になる。テーマ関連の変更であれば、カスタムテーマ経由での拡張を優先する。
+- `themes/<official-name>/`（`my-` プレフィックスなし）— 公式テーマは `update-ampless` で上書きされる。カスタマイズしたい場合は先に `npm run copy-theme <official-name> my-<your-name>` を実行し、コピーを編集する。
+- `package.json` — `ampless` / `@ampless/*` のバージョンは一貫して管理する。バージョンアップには `update-ampless` を使う。
+
+**編集禁止:**
+- `themes-registry.ts` — scaffold / copy-theme / update コマンドが再生成する。
+- `amplify/` — バックエンドのスキーマ変更はテーブルの再構築とサンドボックスデータの消失を招く可能性がある。触る前にユーザーの明示的な確認を得ること。
+- `amplify_outputs.json` — `npm run sandbox` のたびに再生成される。
+- `.amplify/` — Amplify CLI の作業ディレクトリ。
+- `pnpm-lock.yaml` / `package-lock.json` — パッケージマネージャーに任せる。
+
+## テーマのカスタマイズ（標準的な手順）
+
+1. 公式テーマをコピーする:
+   ```bash
+   npm run copy-theme blog my-blog
+   ```
+   `my-` プレフィックスがついているコピーは `npm run update-ampless` で上書きされない。ターゲット名が `my-` で始まらない場合、コマンドは実行を拒否する。
+
+2. 以下の優先順位で編集する:
+   - `themes/my-blog/tokens.css` — 色、タイポグラフィ、スペーシング（`[data-theme='my-blog']` スコープの CSS カスタムプロパティ）。
+   - `themes/my-blog/manifest.ts` — 管理 UI（`/admin/sites/<id>/theme`）に公開するフィールドの宣言。
+   - `themes/my-blog/pages/` — レイアウト / 構造（Next.js ページモジュール: フィード、サイトマップ、投稿テンプレート）。
+
+3. テーマを有効化する: `/admin/sites/<siteId>/theme` を開き、`my-blog` を選択する。テーマ切り替えはランタイム設定 — 再デプロイは不要。
+
+4. 動作確認:
+   ```bash
+   npm run dev   # http://localhost:3000
+   ```
+
+## MCP サーバー（`@ampless/mcp-server`）
+
+エージェントが投稿コンテンツを直接クエリ・編集できる。公開ツール: `list_posts`、`get_post`、`create_post`、`update_post`、`delete_post`、`upload_media`、`get_schema`。
+
+登録方法:
+
+プロジェクトルートの `.mcp.json` に追加する:
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "command": "npx",
+      "args": ["-y", "@ampless/mcp-server", "--outputs", "./amplify_outputs.json"],
+      "env": {
+        "AMPLESS_MCP_EMAIL": "<your-admin-email>",
+        "AMPLESS_MCP_PASSWORD": "<your-admin-password>"
+      }
+    }
+  }
+}
+```
+
+投稿本文は `markdown`、`html`、`tiptap`（JSON ドキュメント）の 3 フォーマットに対応している。
+
+## 動作確認の基準
+
+変更後は最低限以下を実行すること:
+
+- `npm run dev` でブラウザから該当ページを開く。UI / テーマの変更は特に目視確認が必要（Playwright MCP が使える場合はスクリーンショットを活用する）。
+- `npm run build` — 本番ビルドが成功することを確認する。
+- `npm run lint`。
+
+UI / テーマを変更した場合、型チェックだけを根拠にタスク完了を報告しない — ブラウザで実際に確認すること。
+
+## 既知の制約
+
+- **サンドボックスのデータは揮発性。** スキーマに影響する変更は API とテーブルの再構築を引き起こす可能性がある。サンドボックスのコンテンツは使い捨てとして扱うこと。本番データは永続する。
+- **1 Amplify デプロイ = 1 サイト。** 複数サイトを別ドメインで配信したい場合は、サイトごとに Amplify 環境を分けてデプロイする。スキーマの `siteId` カラムは常に `"default"` 固定（前方互換のため残してある）。
+- **AppSync 公開 API キーは `amplify_outputs.json` に含まれ、サイト訪問者から見える。** 低信頼の認証情報として扱うこと — このキーの権限は公開済み投稿の読み取りのみ。`api-key-renewer` Lambda が毎月自動ローテーションするため、手動ローテーションは不要。
+- **最初に登録したユーザーが管理者になる。** 以降のロール変更は Cognito コンソールで行う（RUNBOOK 参照）。
+
+## 参照先
+
+- `README.ja.md` — サイト運営者向けの日常利用ガイド。
+- `RUNBOOK.ja.md` — 定期的な運用手順（キーローテーション、バックアップ復元など）。
+- `themes/<name>/README.ja.md` — テーマごとのカスタマイズ詳細。

package/dist/templates/_shared/AGENTS.md

@@ -0,0 +1,104 @@
+> 日本語版: [AGENTS.ja.md](./AGENTS.ja.md)
+> 
+# AGENTS.md
+
+This file is written for AI coding agents (Claude Code, Cursor, Codex, etc.). For human-readable day-to-day guidance, see `README.md` and `RUNBOOK.md`.
+
+## Project layout
+
+- `themes/<name>/` — installed themes (tokens, pages, manifest). Switch active theme at `/admin/sites/<id>/theme`.
+- `themes/my-<name>/` — user-owned customised theme copies (created via `npm run copy-theme`). The `my-` prefix is what marks the copy as user-owned; `update-ampless` leaves anything under `themes/my-*/` alone.
+- `themes-registry.ts` — auto-generated, do not hand-edit.
+- `amplify/` — Amplify Gen 2 backend (Cognito / DynamoDB / S3 / AppSync / Lambda) defined in TypeScript.
+- `amplify_outputs.json` — generated by `npm run sandbox` / Amplify Hosting. Do not edit.
+- `app/` — Next.js 15 App Router (public site + `/admin` UI).
+- `components/` — shared UI components.
+- `lib/` — shared utilities (data access, auth, etc.).
+- `cms.config.ts` — site, plugins, defaults.
+- `proxy.ts` — request proxy config.
+
+## What you can and can't touch
+
+**Free to edit:**
+- `themes/my-*/` — your own theme copies.
+- `cms.config.ts` — site/plugin config.
+- Post content via the admin UI (recommended) or via the MCP server.
+
+**Touch with caution (explain why before editing):**
+- `app/`, `components/`, `lib/` — these are part of the shared shell. Edits survive `update-ampless` but you own the merge if upstream changes the same file. Prefer extending via a custom theme if the change is theme-related.
+- `themes/<official-name>/` (no `my-` prefix) — official themes get overwritten by `update-ampless`. If you want to customise, run `npm run copy-theme <official-name> my-<your-name>` first and edit the copy.
+- `package.json` — keep `ampless` / `@ampless/*` versions consistent. Use `update-ampless` to bump them.
+
+**Do not edit:**
+- `themes-registry.ts` — regenerated by the scaffold/copy-theme/update commands.
+- `amplify/` — backend schema changes can rebuild tables and wipe sandbox data. Get explicit confirmation from the user before touching.
+- `amplify_outputs.json` — regenerated each `npm run sandbox`.
+- `.amplify/` — Amplify CLI working directory.
+- `pnpm-lock.yaml` / `package-lock.json` — let the package manager update these.
+
+## Customising a theme (the standard flow)
+
+1. Copy an official theme:
+   ```bash
+   npm run copy-theme blog my-blog
+   ```
+   The `my-` prefix marks the copy as user-owned so `npm run update-ampless` leaves it alone. The target name must start with `my-` or the command refuses to run.
+
+2. Edit in this priority order:
+   - `themes/my-blog/tokens.css` — colours, typography, spacing (CSS custom properties scoped under `[data-theme='my-blog']`).
+   - `themes/my-blog/manifest.ts` — declare which fields are exposed in the admin UI (`/admin/sites/<id>/theme`).
+   - `themes/my-blog/pages/` — layout / structure (Next.js page modules: feed, sitemap, post templates).
+
+3. Activate the theme: open `/admin/sites/<siteId>/theme` and select `my-blog`. Theme switching is a runtime setting — no redeploy needed.
+
+4. Verify:
+   ```bash
+   npm run dev   # http://localhost:3000
+   ```
+
+## MCP server (`@ampless/mcp-server`)
+
+Lets agents query and modify post content directly. Tools exposed: `list_posts`, `get_post`, `create_post`, `update_post`, `delete_post`, `upload_media`, `get_schema`.
+
+Registration:
+
+Add to `.mcp.json` at the project root:
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "command": "npx",
+      "args": ["-y", "@ampless/mcp-server", "--outputs", "./amplify_outputs.json"],
+      "env": {
+        "AMPLESS_MCP_EMAIL": "<your-admin-email>",
+        "AMPLESS_MCP_PASSWORD": "<your-admin-password>"
+      }
+    }
+  }
+}
+```
+
+Post bodies accept three formats: `markdown`, `html`, or `tiptap` (JSON document).
+
+## Verification expectations
+
+After any change, run at minimum:
+
+- `npm run dev` and load the affected page in a browser. UI changes especially require visual confirmation (use Playwright MCP for screenshots when available).
+- `npm run build` — confirms the production build succeeds.
+- `npm run lint`.
+
+Do not report a task complete based solely on type checks if a UI/theme was modified — load it in a browser.
+
+## Known constraints
+
+- **Sandbox data is ephemeral.** Schema-affecting changes can rebuild the API and tables; treat sandbox content as throw-away. Production data is durable.
+- **One Amplify deployment = one site.** To serve multiple sites on different domains, deploy separate Amplify environments. The schema's `siteId` column is always the literal `"default"` (retained for forward-compat).
+- **The AppSync public API key is shipped in `amplify_outputs.json` and visible to any site visitor.** Treat it as a low-trust credential — its only privilege is reading published posts. Auto-rotated monthly by the `api-key-renewer` Lambda; no manual rotation needed.
+- **The first registered user becomes admin.** Subsequent role changes go through the Cognito console (see RUNBOOK).
+
+## See also
+
+- `README.md` — day-to-day usage for site owners.
+- `RUNBOOK.md` — occasional ops procedures (key rotation, backup restore, etc.).
+- `themes/<name>/README.md` — per-theme customization details.