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

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

@@ -0,0 +1,176 @@
+> English: [README.md](./README.md)
+> 
+# {{siteName}}
+
+このサイトは [ampless](https://github.com/heavymoons/ampless) で構築されています — AWS Amplify Gen 2（Cognito + DynamoDB + S3 + AppSync + Lambda）上で動くサーバーレス CMS、フロントエンドは Next.js 15。
+
+この README は、サイト運営者として日常的に知っておくべき内容をまとめたものです。たまにやる運用手順（API キーのローテーション、バックアップ復元など）は [RUNBOOK.ja.md](./RUNBOOK.ja.md) に置いています。テーマごとのカスタマイズ詳細は `themes/<name>/README.ja.md` を参照してください。
+
+このプロジェクトで AI コーディングエージェント（Claude Code, Cursor, Codex など）を使うなら [AGENTS.ja.md](./AGENTS.ja.md) を読ませてください。エージェントが触っていい場所・ダメな場所がそこに書いてあります。
+
+## 必要なもの
+
+- **Node.js 20+** と **npm**
+- **AWS アカウント**と CLI 認証情報（`aws configure`）— sandbox / 本番ともに実 AWS リソースをデプロイします
+- 本番ホスティング（AWS Amplify Hosting）用の **GitHub アカウント**
+
+## コマンド
+
+| コマンド | 内容 |
+| --- | --- |
+| `npm install` | 依存関係をインストール |
+| `npm run sandbox` | 個人用 AWS サンドボックス（Cognito / DynamoDB / S3 など）をプロビジョニング、`amplify_outputs.json` を再生成し、`next dev` を `http://localhost:3000` で起動 |
+| `npm run dev` | Next.js だけを起動（サンドボックスのプロビジョニングはスキップ — 一度 `sandbox` を実行済みなら使える） |
+| `npm run build` | Next.js アプリの本番ビルド（Amplify Hosting のデプロイでも自動実行される） |
+| `npm run start` | ビルド済みアプリをローカルで配信 |
+| `npm run lint` | `next lint` で lint |
+| `npm run update-ampless` | ampless テンプレートの最新ファイルを取り込む（設定やテーマは保持。下記「ampless の更新」参照） |
+| `npm run copy-theme` | 公式テーマを後から追加する |
+
+## 初回セットアップ
+
+```bash
+npm install
+npm run sandbox
+```
+
+初回 sandbox は 5〜10 分かかります（AWS リソースのプロビジョニング）。`next dev` 起動前に毎回 `amplify_outputs.json` が再生成されます。
+
+[http://localhost:3000/login](http://localhost:3000/login) を開き、**Create admin account** をクリック。最初に登録したユーザーが自動的に `ampless-admin` Cognito グループに追加されます。
+
+## 管理画面
+
+サインイン後、管理画面は `/admin`:
+
+| パス | 役割 |
+| --- | --- |
+| `/admin` | ダッシュボード |
+| `/admin/posts` | 投稿の一覧 / 作成 / 編集（Tiptap、Markdown、生 HTML、または zip アップロードの静的バンドル） |
+| `/admin/media` | 画像 / 動画 / ファイルを S3 にアップロード |
+| `/admin/sites/<siteId>` | サイトレベル設定（名前、URL） |
+| `/admin/sites/<siteId>/theme` | テーマの切り替え + フィールド調整（カラー、フォント、ナビ、ロゴなど） |
+| `/admin/users` | ユーザー一覧と Cognito グループ所属の確認 |
+| `/admin/mcp-tokens` | HTTP MCP エンドポイント用の Bearer トークンを発行 |
+
+ユーザーロール（Cognito グループ）:
+
+- `ampless-admin` — フルアクセス（コンテンツ + 運用 + 破壊的操作）
+- `ampless-editor` — コンテンツの CRUD（破壊的操作はなし）
+- `ampless-reader` — 将来の REST/MCP API クライアント用に予約
+
+ロールの付与 / 取り消しは AWS Cognito コンソールで行います — [RUNBOOK.ja.md → ユーザーの昇格 / 降格](./RUNBOOK.ja.md#promote--demote-a-user) を参照。
+
+## コンテンツの執筆
+
+投稿（Post）が唯一のコンテンツタイプです。各投稿には以下があります:
+
+- **Format** — `tiptap`（リッチテキスト）/ `markdown` / `html`（生 HTML、サニタイズなし）/ `static`（HTML/CSS/JS の zip アップロード）
+- **No layout** フラグ（`format: 'html'` のときのみ）— 本文をそのまま出力し、Next.js のレイアウトもテーマのクロームも適用しない。URL は `/<slug>` のままで、middleware がリクエストを内部のベア HTML ハンドラーに書き換える
+- **キャッシュ戦略**（`metadata.cache`）— 投稿ごとに `Cache-Control` を上書き: `'auto'`（デフォルト、編集時刻ベースのクールダウン）、`'deep'`（常に長期キャッシュ）、`'hot'`（常に no-store）。詳細は `docs/CONTENT.ja.md`
+- **Slug** — 公開 URL
+- **Status** — `draft`（管理者のみ）または `published`
+
+詳細リファレンス: [docs/CONTENT.ja.md（GitHub）](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.ja.md) ([English](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.md))
+
+## テーマ
+
+インストール済みのテーマはすべて `themes/<name>/` にバンドルされています。**アクティブな**テーマはサイトごとのランタイム設定 — テーマの切り替えに**再デプロイは不要**です。
+
+アクティブテーマの切り替え: `/admin/sites/<siteId>/theme` → インストール済みリストから選択 → 保存。
+
+アクティブテーマのカスタマイズ（カラー、フォント、ヘッダー / フッターナビなど）: 同じ画面 — 各テーマが固有のカスタマイズフィールドを公開しています。各テーマで何が変えられるかは `themes/<name>/README.ja.md` を参照。
+
+このプロジェクトに別の公式テーマを追加する:
+
+```bash
+npm run copy-theme
+```
+
+独自テーマを作る場合: 既存テーマをコピーから始める（`cp -R themes/blog themes/your-theme`）→ `manifest.ts`、`tokens.css`、`pages/*.tsx` を編集 → `themes-registry.ts` に追加。フルガイド: [docs/THEMES.ja.md](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.ja.md) ([English](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.md))
+
+## プラグイン
+
+プラグインは CMS にイベント駆動の副作用（SEO メタデータ、RSS フィード、外部 URL への webhook、OG 画像生成など）を追加する仕組みです。[`cms.config.ts`](./cms.config.ts) で宣言し、投稿の publish / update / delete 時に Lambda 上で実行されます。
+
+`cms.config.ts` に書けば有効になる、同梱の公式プラグイン:
+
+| パッケージ | 役割 |
+| --- | --- |
+| `@ampless/plugin-seo` | 投稿ごとの OGP / Twitter / canonical メタデータ + `sitemap.xml` |
+| `@ampless/plugin-rss` | `/feed.xml` の RSS 2.0 フィード |
+| `@ampless/plugin-webhook` | 外部 URL へのイベント POST（HMAC 署名付き） |
+| `@ampless/plugin-og-image` | `/og/<slug>` での動的 OG 画像生成 |
+
+プラグインを追加するには: install（`npm i @ampless/plugin-...`）→ `cms.config.ts` で import → `plugins` 配列に追加:
+
+```ts
+import seoPlugin from '@ampless/plugin-seo'
+import rssPlugin from '@ampless/plugin-rss'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    seoPlugin({ twitterSite: '@example' }),
+    rssPlugin({ language: 'ja', limit: 20 }),
+  ],
+})
+```
+
+プラグイン変更には再デプロイが必要です（プラグインコードは Lambda バンドルに含まれます）。
+
+## 本番デプロイ
+
+同梱の [`amplify.yml`](./amplify.yml) が、connect したブランチへの push のたびに `npx ampx pipeline-deploy`（Amplify バックエンド） + `npm run build`（Next.js）を実行します。
+
+1. **GitHub（または Amplify Hosting が対応する git ホスト）にこのプロジェクトを push**:
+   ```bash
+   git init && git add . && git commit -m "init"
+   git remote add origin <your-repo>
+   git push -u origin main
+   ```
+2. **AWS Amplify Hosting コンソール** → **Create new app** → **Host web app** → リポジトリを連携 → ブランチを選択 → 自動検出されたビルド設定（`amplify.yml` の内容になっているはず）を確認 → デプロイ
+3. 初回デプロイは 10〜20 分。以降は連携ブランチへの push で自動再デプロイ
+
+### 環境変数
+
+環境ごとの値は **Amplify Hosting コンソール → Hosting → Environment variables** で設定。よく使うもの:
+
+| 変数 | 利用箇所 |
+| --- | --- |
+| `WEBHOOK_SECRET` | `@ampless/plugin-webhook` の HMAC 署名 |
+
+env 変数追加 / 変更後は再デプロイをトリガーしてください。
+
+### カスタムドメイン
+
+Amplify Hosting アプリの **Domain management** からドメインをバインドします — ACM 証明書と DNS レコードは Amplify が自動でプロビジョニングします。詳細手順: [RUNBOOK.ja.md → カスタムドメインを Amplify Hosting に追加](./RUNBOOK.ja.md#adding-a-custom-domain-to-amplify-hosting)
+
+## AI 連携（MCP）
+
+ampless は MCP（Model Context Protocol）サーバーを同梱しているので、Claude Desktop / Cursor / Claude Code など MCP に対応した AI クライアントから投稿の読み書きができます。
+
+- **ローカル / sandbox** — グローバルに 1 度入れる: `npx -y @ampless/mcp-server@alpha` に `amplify_outputs.json` のパスを渡す
+
+## ampless の更新
+
+ampless は `alpha` dist-tag でリリースしています。新機能を取り込むには:
+
+```bash
+npm run update-ampless
+```
+
+これは `npx create-ampless@latest upgrade` を実行し、以下を行います:
+
+- `package.json` の `@ampless/*` / `ampless` 依存をバージョンアップ
+- 共有テンプレートファイル（admin アプリの土台、amplify バックエンド、lib/、middleware、テーマ）を再同期 — `cms.config.ts`、`theme.*` 管理画面設定、投稿、テーマ manifest 値などのユーザーカスタマイズは保持されます
+- `update-ampless` / `copy-theme` スクリプトのコマンドが変わっていれば更新
+
+commit 前に diff を確認できます。
+
+## 運用
+
+日常以外の運用レシピ — ユーザー昇格、パスワードリセット、バックアップ復元、カスタムドメイン配線、AppSync API キーローテーション — は [RUNBOOK.ja.md](./RUNBOOK.ja.md) にあります。
+
+## ライセンス
+
+このプロジェクト自身のコードはあなたのものです。ampless 本体は MIT ライセンスです。詳細は [ampless リポジトリ](https://github.com/heavymoons/ampless) を参照。

package/dist/templates/_shared/README.md

@@ -0,0 +1,176 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# {{siteName}}
+
+Your site is built with [ampless](https://github.com/heavymoons/ampless) — a serverless CMS that runs on AWS Amplify Gen 2 (Cognito + DynamoDB + S3 + AppSync + Lambda) with a Next.js 15 frontend.
+
+This README covers what you, the site owner, need to know day-to-day. Operational recipes (rotating keys, restoring backups, etc.) live in [RUNBOOK.md](./RUNBOOK.md). Per-theme customization details live in `themes/<name>/README.md`.
+
+If you use an AI coding agent (Claude Code, Cursor, Codex, etc.) on this project, point it at [AGENTS.md](./AGENTS.md) — that file tells the agent what it can and can't touch.
+
+## Requirements
+
+- **Node.js 20+** and **npm**
+- **AWS account** with CLI credentials (`aws configure`) — the sandbox + production both deploy real AWS resources
+- **GitHub account** for production hosting via AWS Amplify Hosting
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npm install` | Install dependencies |
+| `npm run sandbox` | Provision a personal AWS sandbox (Cognito / DynamoDB / S3 / etc.), regenerate `amplify_outputs.json`, then start `next dev` on `http://localhost:3000` |
+| `npm run dev` | Start Next.js only (skip sandbox provisioning — use after `sandbox` has already run once) |
+| `npm run build` | Production build of the Next.js app (also runs as part of Amplify Hosting deploy) |
+| `npm run start` | Serve the production build locally |
+| `npm run lint` | Lint with `next lint` |
+| `npm run update-ampless` | Pull the latest ampless template files into this project, preserving your config and themes (see "Updating ampless" below) |
+| `npm run copy-theme` | Add another official theme to this project after-the-fact |
+
+## First time setup
+
+```bash
+npm install
+npm run sandbox
+```
+
+First sandbox run takes 5–10 minutes (AWS resource provisioning). `amplify_outputs.json` is regenerated each time before `next dev` starts.
+
+Open [http://localhost:3000/login](http://localhost:3000/login) and click **Create admin account**. The first registered user is automatically added to the `ampless-admin` Cognito group.
+
+## Admin UI
+
+After signing in, the admin lives at `/admin`:
+
+| Path | Purpose |
+| --- | --- |
+| `/admin` | Dashboard |
+| `/admin/posts` | List / create / edit posts (Tiptap editor, Markdown, raw HTML, or zip-uploaded static bundles) |
+| `/admin/media` | Upload images / videos / files to S3 |
+| `/admin/sites/<siteId>` | Site-level settings (name, URL) |
+| `/admin/sites/<siteId>/theme` | Activate a theme + customize its fields (colors, fonts, nav, logo, etc.) |
+| `/admin/users` | View users + Cognito group memberships |
+| `/admin/mcp-tokens` | Issue Bearer tokens for the HTTP MCP endpoint |
+
+User roles (Cognito groups):
+
+- `ampless-admin` — full access (content + ops + destructive)
+- `ampless-editor` — content CRUD (no destructive ops)
+- `ampless-reader` — reserved for future REST/MCP API consumers
+
+Promotion/demotion is done in the AWS Cognito console — see [RUNBOOK.md → Promote / demote a user](./RUNBOOK.md#promote--demote-a-user).
+
+## Authoring content
+
+Posts are the single content type. Each post has:
+
+- **Format** — `tiptap` (rich text) / `markdown` / `html` (raw, no sanitization) / `static` (zip-upload of HTML/CSS/JS)
+- **No layout** flag (`format: 'html'` only) — render the body verbatim with no Next.js layout and no theme chrome. URL stays `/<slug>`; middleware rewrites the request to the internal bare-HTML handler.
+- **Cache strategy** (`metadata.cache`) — override the per-post Cache-Control: `'auto'` (default; cooldown by edit time), `'deep'` (always long-cache), or `'hot'` (always no-store). See `docs/CONTENT.md` for details.
+- **Slug** — the public URL
+- **Status** — `draft` (admin only) or `published`
+
+Full reference: [docs/CONTENT.md on GitHub](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.md) ([日本語](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.ja.md)).
+
+## Themes
+
+Every installed theme is bundled in this project under `themes/<name>/`. The **active** theme per site is a runtime setting — switching themes does **not** require a redeploy.
+
+To switch the active theme: `/admin/sites/<siteId>/theme` → pick from the installed list → save.
+
+To customize the active theme (colors, fonts, header / footer nav, etc.): same page — each theme exposes its own customization fields. See `themes/<name>/README.md` for what's customizable per theme.
+
+To install another official theme into this project:
+
+```bash
+npm run copy-theme
+```
+
+To author your own theme: copy an existing one as a starting point (`cp -R themes/blog themes/your-theme`), edit `manifest.ts`, `tokens.css`, and `pages/*.tsx`, then add it to `themes-registry.ts`. Full guide: [docs/THEMES.md](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.md) ([日本語](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.ja.md)).
+
+## Plugins
+
+Plugins extend the CMS with event-driven side effects (SEO metadata, RSS feed, webhooks to external URLs, OG image generation, etc.). They're declared in [`cms.config.ts`](./cms.config.ts) and run on Lambda when posts are published / updated / deleted.
+
+Bundled and ready to enable in `cms.config.ts`:
+
+| Package | Purpose |
+| --- | --- |
+| `@ampless/plugin-seo` | Per-post OGP / Twitter / canonical metadata + `sitemap.xml` |
+| `@ampless/plugin-rss` | RSS 2.0 feed at `/feed.xml` |
+| `@ampless/plugin-webhook` | POST events to external URLs (HMAC-signed) |
+| `@ampless/plugin-og-image` | Dynamic Open Graph image generation at `/og/<slug>` |
+
+To add a plugin: install (`npm i @ampless/plugin-...`), import in `cms.config.ts`, and add to the `plugins` array:
+
+```ts
+import seoPlugin from '@ampless/plugin-seo'
+import rssPlugin from '@ampless/plugin-rss'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    seoPlugin({ twitterSite: '@example' }),
+    rssPlugin({ language: 'en', limit: 20 }),
+  ],
+})
+```
+
+A redeploy is required for plugin changes (the plugin code ships in the Lambda bundle).
+
+## Deploying to production
+
+The shipped [`amplify.yml`](./amplify.yml) runs `npx ampx pipeline-deploy` (Amplify backend) + `npm run build` (Next.js) on every push to the branch you connect.
+
+1. **Push this project to GitHub** (or another git host Amplify Hosting supports):
+   ```bash
+   git init && git add . && git commit -m "init"
+   git remote add origin <your-repo>
+   git push -u origin main
+   ```
+2. **AWS Amplify Hosting console** → **Create new app** → **Host web app** → connect the repo → pick the branch → review the auto-detected build settings (they should match `amplify.yml`) → deploy.
+3. First deploy takes 10–20 minutes. Subsequent pushes to the connected branch redeploy automatically.
+
+### Environment variables
+
+Set per-environment values in **Amplify Hosting console → Hosting → Environment variables**. Common ones:
+
+| Variable | Used by |
+| --- | --- |
+| `WEBHOOK_SECRET` | `@ampless/plugin-webhook` HMAC signing |
+
+Trigger a redeploy after adding/changing env vars.
+
+### Custom domains
+
+Bind a domain to your Amplify Hosting app in **Domain management** — Amplify provisions an ACM certificate and DNS records automatically. Full step-by-step: [RUNBOOK.md → Adding a custom domain](./RUNBOOK.md#adding-a-custom-domain-to-amplify-hosting).
+
+## AI integration (MCP)
+
+ampless ships an MCP (Model Context Protocol) server so Claude Desktop / Cursor / Claude Code / anything that speaks MCP can read and write your posts.
+
+- **Local / sandbox** — install once globally: `npx -y @ampless/mcp-server@alpha` with the path to your `amplify_outputs.json`.
+
+## Updating ampless
+
+ampless releases on the `alpha` dist-tag. To pick up new features:
+
+```bash
+npm run update-ampless
+```
+
+This runs `npx create-ampless@latest upgrade`, which:
+
+- Bumps the `@ampless/*` and `ampless` dependencies in `package.json`
+- Re-syncs the shared template files (admin app shell, amplify backend, lib/, middleware, themes) — your customizations to `cms.config.ts`, `theme.*` admin settings, posts, and theme manifest values are preserved.
+- Updates `update-ampless` and `copy-theme` script entries if their commands change
+
+You can review the diff before committing.
+
+## Operations
+
+Day-to-day operational recipes — user promotion, password reset, backup restore, custom domain wiring, AppSync API key rotation — live in [RUNBOOK.md](./RUNBOOK.md).
+
+## License
+
+This project's own code is yours. ampless itself is MIT-licensed; see the [ampless repository](https://github.com/heavymoons/ampless) for details.

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

@@ -0,0 +1,120 @@
+> English: [RUNBOOK.md](./RUNBOOK.md)
+> 
+
+# ランブック
+
+ampless で構築したサイトで、ときどき必要になる運用作業の手順集です。毎日やるわけではないけれど、いざ必要になったときに迷わずに進めるためのものです。
+
+日常的な使い方（コマンド、管理画面、テーマ、プラグイン、デプロイなど）は [README.ja.md](./README.ja.md) を参照してください。
+
+## 目次
+
+- [AppSync API キー（自動更新）](#appsync-api-キー自動更新)
+- [よくある運用](#よくある運用)
+  - [ユーザーの昇格 / 降格](#promote--demote-a-user)
+  - [パスワードリセット（管理者上書き）](#reset-a-users-password-admin-override)
+  - [Post テーブルのバックアップから復元](#restore-from-a-post-table-backup)
+  - [失敗したプラグインイベントを確認する](#inspect-failed-plugin-events)
+- [カスタムドメイン](#custom-domains)
+  - [カスタムドメインを Amplify Hosting に追加する](#adding-a-custom-domain-to-amplify-hosting)
+
+## AppSync API キー（自動更新）
+
+パブリックブログの読み取り（`listPublishedPosts`、`getPublishedPost`、`listPostsByTag`）は AppSync API キーで保護されています。このキーは `amplify_outputs.json` に含まれているため、**公開サイトを訪問した誰もが確認できる**状態にあります。低信頼度のクレデンシャルとして扱ってください。このキーが持つ権限は上記 3 つのカスタムクエリを呼び出すことのみであり、それらのクエリは `status === 'published'` の行しか返しません。
+
+### なぜ API キーなのか（Identity Pool ゲストロールではなく）？
+
+Amplify Gen 2 の `a.handler.custom` リゾルバーは `allow.guest()` や `allow.authenticated('identityPool')` をサポートしておらず、apiKey / userPool / lambda / group / owner のみが使用可能です。v0.1 では簡潔さを優先して API キーを選択しました。パブリック読み取りを Lambda 関数データソース（`a.handler.function`）に移行することは v0.2 の候補です。
+
+### 自動更新 — ローテーション手順は不要
+
+`api-key-renewer` Lambda（`amplify/functions/api-key-renewer/` を参照）は、毎月 1 日の UTC 03:00 に EventBridge スケジュールで起動します。`AppSync.UpdateApiKey` を呼び出して既存キーの `expires` を「現時点 + 364 日」に延長するため、以下が保証されます：
+
+- キー ID は変化しない
+- `amplify_outputs.json` は引き続き有効
+- Next.js アプリの再ビルドは不要
+- 常に約 334 日以上の残有効期限が維持される
+
+手動で確認または実行したい場合：
+
+```bash
+# 現在の有効期限を確認
+aws appsync list-api-keys \
+  --region <amplify_outputs.json の data.aws_region> \
+  --api-id <amplify_outputs.json の data.url から導出した api-id>
+
+# 手動実行（サンドボックスを長期間停止した後など）
+aws lambda invoke \
+  --function-name $(aws lambda list-functions \
+    --query "Functions[?contains(FunctionName,'api-key-renewer')].FunctionName | [0]" \
+    --output text) \
+  /tmp/out.json && cat /tmp/out.json
+```
+
+### キーの漏洩が疑われる場合
+
+有効期限の延長ではなく、キーの値そのものをローテーションする即時対応を行います：
+
+1. `amplify/data/resource.ts` のコメントを編集して CFN 更新を強制する
+2. `npx ampx sandbox`（サンドボックス）または `npx ampx pipeline-deploy ...`（本番）を実行 — Amplify がキーの値を再生成する
+3. Next.js アプリを再デプロイして SSR が新しい `data.api_key` を参照するようにする
+
+## 一般的な操作
+
+### ユーザーのグループ昇格 / 降格
+
+AWS Cognito コンソールから操作します：
+
+1. User Pool → Users → 対象ユーザーを選択
+2. Group memberships → グループに追加 / グループから削除
+3. ユーザーに一度サインアウトしてサインインし直してもらい、新しいクレームを適用させる
+
+グループの種類： `ampless-admin`（フル CRUD + 運用操作）、`ampless-editor`（コンテンツ CRUD）、`ampless-reader`（将来の REST/MCP API 利用者向けに予約済み）。
+
+### ユーザーパスワードのリセット（管理者による上書き）
+
+ロックアウトされており、メールによる復旧が利用できない場合：
+
+```bash
+aws cognito-idp admin-set-user-password \
+  --user-pool-id <amplify_outputs.json の auth.user_pool_id> \
+  --region <リージョン> \
+  --username <メールアドレス> \
+  --password '<新しいパスワード>' --permanent
+```
+
+`/login` ページにはセルフサービスの「パスワードを忘れた場合」フローもあります。
+
+### Post テーブルのバックアップからの復元
+
+DynamoDB のポイントインタイムリカバリ（PITR）は v0.1 の `defineData` では有効になっていません。AWS コンソール → DynamoDB → Tables → `<投稿テーブル名>` → Backups → Edit PITR から手動で有効化してください。有効化後は `aws dynamodb restore-table-to-point-in-time` で新しいテーブルに復元し、その後アイテムをライブテーブルに移行する作業が必要です。
+
+### 失敗したプラグインイベントの確認
+
+処理に失敗したプロセッサー呼び出しは、`amplify/backend.ts` で作成された共有イベント DLQ（`EventsDlq`）に送られます。SQS コンソールまたは `aws sqs receive-message --queue-url <dlq-url> --max-number-of-messages 10` でメッセージを確認してください。v0.1 には自動アラームがないため、定期的な手動確認を推奨します。あるいは `ApproximateNumberOfMessagesVisible` に CloudWatch アラームを設定してください。
+
+## カスタムドメイン
+
+ampless は 1 Amplify デプロイ = 1 サイト。複数サイトを別ドメインで配信したい場合は、サイトごとに Amplify 環境を分けてデプロイしてください。
+
+### Amplify Hosting へのカスタムドメイン追加
+
+バインドしたいドメインごとに以下を実施します：
+
+1. **Amplify Hosting コンソール** → アプリ → **Domain management** → **Add domain** を選択。
+2. 頂点ドメイン（`example.com`）と接続したいサブドメインを入力します。Amplify が ACM 証明書と CloudFront SAN エントリを自動でプロビジョニングします。
+3. DNS を更新：
+   - **Route 53 / Amplify 管理の DNS プロバイダー**：Amplify が CNAME を作成してくれるので、確認するだけです。
+   - **外部 DNS**（Cloudflare、Squarespace など）：Amplify が表示する CNAME / DNS 検証レコードをコピーします。ACM のメール検証もフォールバックとして使用できます。
+4. **Domain activation** が完了するまで待ちます（通常 15〜60 分。証明書の検証が最も時間がかかります）。
+5. `cms.config.ts` の `site.url` を新しい canonical URL に更新し、commit して push します：
+   ```bash
+   git add cms.config.ts && git commit -m "feat: bind docs.example.com"
+   git push   # Amplify Hosting が自動検出します
+   ```
+
+エンドツーエンドで確認：
+
+```bash
+curl -I https://docs.example.com/   # 200 とサイトの HTML
+```

package/dist/templates/_shared/RUNBOOK.md

@@ -1,6 +1,22 @@
+> 日本語版: [RUNBOOK.ja.md](./RUNBOOK.ja.md)
+> 
+
 # Runbook
 
-Operational tasks for an ampless-powered site.
+Step-by-step recipes for occasional operations on an ampless-powered site — the things you don't do every day but want a reliable procedure for when you do.
+
+For day-to-day usage (commands, admin UI tour, themes, plugins, deploying), start with [README.md](./README.md).
+
+## Contents
+
+- [AppSync API key (auto-renewed)](#appsync-api-key-auto-renewed)
+- [Common operations](#common-operations)
+  - [Promote / demote a user](#promote--demote-a-user)
+  - [Reset a user's password (admin override)](#reset-a-users-password-admin-override)
+  - [Restore from a Post-table backup](#restore-from-a-post-table-backup)
+  - [Inspect failed plugin events](#inspect-failed-plugin-events)
+- [Custom domains](#custom-domains)
+  - [Adding a custom domain to Amplify Hosting](#adding-a-custom-domain-to-amplify-hosting)
 
 ## AppSync API key (auto-renewed)
 
@@ -99,49 +115,10 @@ or `aws sqs receive-message --queue-url <dlq-url> --max-number-of-messages 10`.
 There's no automated alarm in v0.1 — periodic manual checks recommended,
 or wire up a CloudWatch alarm on `ApproximateNumberOfMessagesVisible`.
 
-## Multi-site / custom domains
-
-ampless can serve multiple sites from one Amplify Hosting deployment.
-Each site is identified by a `siteId` and bound to one or more
-hostnames via `cms.config.ts`:
-
-```ts
-sites: {
-  blog: {
-    domains: ['blog.example.com', 'www.example.com'],
-    name: 'My Blog',
-    url: 'https://blog.example.com',
-  },
-  docs: {
-    domains: ['docs.example.com'],
-    name: 'Docs',
-    url: 'https://docs.example.com',
-  },
-},
-```
-
-The middleware (`middleware.ts`) maps incoming `Host` to a `siteId` and
-internally rewrites the path to `/_sites/{siteId}/...`. Subdomains and
-fully separate domains are equivalent at the application layer — only
-the AWS-side wiring differs.
-
-### Single domain operation
-
-If `sites` is undefined or has only one entry, ampless runs in
-single-site mode (`siteId='default'`). SSR responses follow each page's
-own caching directives (so you can opt into CloudFront caching with
-`Cache-Control: public, s-maxage=...` per route).
+## Custom domains
 
-### Multi-site mode caveat: SSR caching is force-disabled
-
-When two or more sites are declared, the middleware adds
-`Cache-Control: private, no-store` to every public response. This is
-because Amplify Hosting's CloudFront does not include `Host` in its
-cache key — leaving caching on would let `https://site1/foo` and
-`https://site2/foo` cross-contaminate at the edge. The trade-off is
-that every public read hits Lambda. Lifting it requires moving off
-Amplify Hosting onto a self-managed CloudFront + Open Next stack
-(roadmap: post-v1.0).
+ampless runs one site per Amplify deployment. To serve multiple sites
+on different domains, deploy a separate Amplify environment per site.
 
 ### Adding a custom domain to Amplify Hosting
 
@@ -160,19 +137,15 @@ For each domain you want to bind:
      also works as a fallback.
 4. Wait for the **Domain activation** to finish (typically 15–60
    minutes; certificate validation is the slow step).
-5. Add the new domain to the matching `sites.{id}.domains[]` in
-   `cms.config.ts` and redeploy:
+5. Update `cms.config.ts` so `site.url` reflects the new canonical URL,
+   commit, and push to redeploy:
    ```bash
-   git add cms.config.ts && git commit -m "feat: add docs.example.com"
+   git add cms.config.ts && git commit -m "feat: bind docs.example.com"
    git push   # Amplify Hosting picks it up
    ```
 
 Verify end-to-end:
 
 ```bash
-curl -I https://docs.example.com/                  # 200 with the docs site's HTML
-curl -sI https://docs.example.com/ | grep -i cache # Cache-Control: private, no-store
+curl -I https://docs.example.com/   # 200 with your site's HTML
 ```
-
-If the request returns `404 Site not found` instead, the host is not
-listed in any `sites.*.domains[]` — fix the config and redeploy.

package/dist/templates/_shared/amplify/auth/post-confirmation/resource.ts

@@ -3,4 +3,10 @@ import { defineFunction } from '@aws-amplify/backend'
 export const postConfirmation = defineFunction({
   name: 'post-confirmation',
   entry: './handler.ts',
+  // Auth trigger — assign to the auth nested stack so CFN doesn't
+  // place it in a separate `function` stack that ends up in a
+  // circular dependency loop with auth (which references this
+  // function) and storage/data (which auth happens to reach via
+  // cross-stack refs the function adds).
+  resourceGroupName: 'auth',
 })

package/dist/templates/_shared/amplify/backend.ts

@@ -8,6 +8,7 @@ import { eventDispatcher } from './events/dispatcher/resource.js'
 import { processorTrusted } from './events/processor-trusted/resource.js'
 import { processorUntrusted } from './events/processor-untrusted/resource.js'
 import { apiKeyRenewer } from './functions/api-key-renewer/resource.js'
+import { mcpHandler } from './functions/mcp-handler/resource.js'
 import { userAdmin } from './functions/user-admin/resource.js'
 import { customizeBackend } from './backend.custom.js'
 
@@ -27,6 +28,7 @@ const backend = defineAmplessBackend({
   processorTrusted,
   processorUntrusted,
   apiKeyRenewer,
+  mcpHandler,
   userAdmin,
 })
 

package/dist/templates/_shared/amplify/data/get-published-post.js

@@ -2,24 +2,21 @@ import { util } from '@aws-appsync/utils'
 
 // AppSync JS resolver: returns a single published post by slug.
 //
-// Reads the `bySiteIdSlug` GSI: PK = `${siteId}#${slug}`. A given
-// (site, slug) tuple identifies at most one row, so this is an O(1)
-// PK Query — no scan, no filter, no per-partition limit issues.
+// Reads the `bySlug` GSI: PK = slug. A slug identifies at most one row
+// (uniqueness enforced at the admin form level), so this is an O(1) PK
+// Query — no scan, no filter, no per-partition limit issues.
 //
-// Drafts are dropped in the response handler. The admin form
-// enforces a unique slug per site at the application layer, but if
-// somehow draft + published share a slug we prefer the published row.
+// Drafts are dropped in the response handler. If draft + published
+// somehow share a slug we prefer the published row.
 export function request(ctx) {
-  const siteId = ctx.args.siteId ?? 'default'
   const slug = ctx.args.slug
-  const partition = `${siteId}#${slug}`
   return {
     operation: 'Query',
-    index: 'bySiteIdSlug',
+    index: 'bySlug',
     query: {
-      expression: '#siteIdSlug = :siteIdSlug',
-      expressionNames: { '#siteIdSlug': 'siteIdSlug' },
-      expressionValues: util.dynamodb.toMapValues({ ':siteIdSlug': partition }),
+      expression: '#slug = :slug',
+      expressionNames: { '#slug': 'slug' },
+      expressionValues: util.dynamodb.toMapValues({ ':slug': slug }),
     },
     limit: 5,
   }