create-ampless 0.2.0-alpha.17 → 0.2.0-alpha.19

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 15（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.

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

@@ -0,0 +1,182 @@
+> 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` を参照してください。
+
+## 必要なもの
+
+- **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>` のままで、ルートが `/raw/<slug>` にリダイレクトする
+- **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 署名 |
+| `AMPLESS_MCP_SERVICE_EMAIL` | HTTP MCP サービスユーザーのメール — `/api/mcp` を有効化するのに必須 |
+| `AMPLESS_MCP_SERVICE_PASSWORD` | HTTP MCP サービスユーザーのパスワード |
+
+env 変数追加 / 変更後は再デプロイをトリガーしてください。
+
+### カスタムドメイン
+
+Amplify Hosting アプリの **Domain management** からドメインをバインドします — ACM 証明書と DNS レコードは Amplify が自動でプロビジョニングします。詳細手順: [RUNBOOK.ja.md → カスタムドメインを Amplify Hosting に追加](./RUNBOOK.ja.md#adding-a-custom-domain-to-amplify-hosting)
+
+### マルチサイト（複数ドメインを 1 デプロイで）
+
+ampless は 1 つの Amplify Hosting デプロイで複数のサイトを配信できます。各サイトは独自の `siteId`、ホスト名、サイト名、アクティブテーマを持ちます。有効化するには、`cms.config.ts` の `sites:` ブロック（コメントアウト例あり）を埋めてデプロイ。
+
+マルチサイトモードにはキャッシュ周りのトレードオフがあります。詳細: [RUNBOOK.ja.md → マルチサイト / カスタムドメイン](./RUNBOOK.ja.md#multi-site--custom-domains)
+
+## 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` のパスを渡す
+- **本番（HTTP）** — `/admin/mcp-tokens` で Bearer トークンを発行し、MCP クライアントを `https://<your-domain>/api/mcp` に向ける。フルセットアップ: [docs/mcp-http-setup.ja.md](https://github.com/heavymoons/ampless/blob/main/docs/mcp-http-setup.ja.md) ([English](https://github.com/heavymoons/ampless/blob/main/docs/mcp-http-setup.md))
+
+## 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,182 @@
+> 日本語版: [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`.
+
+## 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>`; the route redirects to `/raw/<slug>`.
+- **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 |
+| `AMPLESS_MCP_SERVICE_EMAIL` | HTTP MCP service-user email — required to enable `/api/mcp` |
+| `AMPLESS_MCP_SERVICE_PASSWORD` | HTTP MCP service-user password |
+
+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).
+
+### Multi-site (multiple domains, one deploy)
+
+ampless can serve multiple sites from a single Amplify Hosting deployment. Each site has its own `siteId`, hostname(s), name, and active theme. To enable, fill in the `sites:` block in `cms.config.ts` (it's there as a commented example) and deploy.
+
+There's a caching trade-off in multi-site mode; details in [RUNBOOK.md → Multi-site / custom domains](./RUNBOOK.md#multi-site--custom-domains).
+
+## 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`.
+- **Production (HTTP)** — issue a Bearer token at `/admin/mcp-tokens` and point your MCP client at `https://<your-domain>/api/mcp`. Full setup: [docs/mcp-http-setup.md](https://github.com/heavymoons/ampless/blob/main/docs/mcp-http-setup.md) ([日本語](https://github.com/heavymoons/ampless/blob/main/docs/mcp-http-setup.ja.md)).
+
+## 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, multi-site setup — 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,150 @@
+> 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)
+- [マルチサイト / カスタムドメイン](#multi-site--custom-domains)
+  - [シングルドメイン運用](#single-domain-operation)
+  - [マルチサイト時の注意：SSR キャッシュは強制無効化](#multi-site-mode-caveat-ssr-caching-is-force-disabled)
+  - [カスタムドメインを 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 Hosting デプロイメントから複数のサイトを配信できます。各サイトは `siteId` で識別され、`cms.config.ts` 内で 1 つ以上のホスト名に紐づけられます：
+
+```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',
+  },
+},
+```
+
+ミドルウェア（`middleware.ts`）が受信リクエストの `Host` を `siteId` にマッピングし、パスを `/_sites/{siteId}/...` に内部リライトします。サブドメインと完全に分離されたドメインはアプリケーション層では等価です — AWS 側の設定のみが異なります。
+
+### シングルドメイン運用
+
+`sites` が未定義または 1 エントリのみの場合、ampless はシングルサイトモード（`siteId='default'`）で動作します。SSR レスポンスはルートごとのキャッシュディレクティブに従います（ルートごとに `Cache-Control: public, s-maxage=...` を指定することで CloudFront キャッシュを利用できます）。
+
+### マルチサイトモードの注意事項：SSR キャッシュの強制無効化
+
+2 つ以上のサイトが設定されている場合、ミドルウェアはすべてのパブリックレスポンスに `Cache-Control: private, no-store` を付加します。これは Amplify Hosting の CloudFront がキャッシュキーに `Host` を含まないため、キャッシュを有効にすると `https://site1/foo` と `https://site2/foo` がエッジでコンテンツを混在させてしまうためです。このトレードオフとして、すべてのパブリック読み取りが Lambda にヒットします。この制約を解消するには、Amplify Hosting から独自管理の CloudFront + Open Next スタックへの移行が必要です（ロードマップ：v1.0 以降）。
+
+### 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` の対応する `sites.{id}.domains[]` に追加して再デプロイします：
+   ```bash
+   git add cms.config.ts && git commit -m "feat: add docs.example.com"
+   git push   # Amplify Hosting が自動検出します
+   ```
+
+エンドツーエンドで確認：
+
+```bash
+curl -I https://docs.example.com/                  # 200 とドキュメントサイトの HTML
+curl -sI https://docs.example.com/ | grep -i cache # Cache-Control: private, no-store
+```
+
+リクエストが `404 Site not found` を返す場合、そのホストはいずれの `sites.*.domains[]` にも登録されていません — 設定を修正して再デプロイしてください。

package/dist/templates/_shared/RUNBOOK.md

@@ -1,6 +1,24 @@
+> 日本語版: [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)
+- [Multi-site / custom domains](#multi-site--custom-domains)
+  - [Single domain operation](#single-domain-operation)
+  - [Multi-site mode caveat: SSR caching is force-disabled](#multi-site-mode-caveat-ssr-caching-is-force-disabled)
+  - [Adding a custom domain to Amplify Hosting](#adding-a-custom-domain-to-amplify-hosting)
 
 ## AppSync API key (auto-renewed)
 

package/dist/templates/_shared/package.json

@@ -22,15 +22,15 @@
     "@tiptap/pm": "^3.23.4",
     "@tiptap/react": "^3.23.4",
     "@tiptap/starter-kit": "^3.23.4",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.5",
-    "@ampless/plugin-rss": "^0.2.0-alpha.5",
-    "@ampless/plugin-seo": "^0.2.0-alpha.5",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.5",
-    "@ampless/admin": "^0.2.0-alpha.15",
-    "@ampless/backend": "^0.2.0-alpha.7",
-    "@ampless/runtime": "^0.2.0-alpha.8",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.6",
+    "@ampless/plugin-rss": "^0.2.0-alpha.6",
+    "@ampless/plugin-seo": "^0.2.0-alpha.6",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.6",
+    "@ampless/admin": "^0.2.0-alpha.18",
+    "@ampless/backend": "^0.2.0-alpha.8",
+    "@ampless/runtime": "^0.2.0-alpha.9",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^0.2.0-alpha.5",
+    "ampless": "^0.2.0-alpha.6",
     "aws-amplify": "^6.10.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

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

@@ -0,0 +1,22 @@
+> English: [README.md](./README.md)
+> 
+# Blog テーマ
+
+shadcn/ui のデフォルトに準じたニュートラル系モノクロ。時系列の投稿フィード、個別投稿ページ、タグ別一覧を提供します。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **プライマリカラー** — ボタン、リンク、強調表示の背景色
+- **アクセントカラー**
+- **フォーカスリング**
+- **破壊的操作** — 削除等の操作色
+- **角丸**
+- **本文フォント** — システムサンセリフ / セリフ (Georgia) / セリフ (Iowan) / 等幅
+- **トップに固定する記事のスラッグ** — 公開済み投稿を 1 件ホームの先頭に固定
+- **ロゴ画像 URL**
+- **ヘッダーナビ** — ラベル + URL のペア
+- **フッターリンク** — ラベル + URL のペア
+
+サイトごとのライト/ダークカラースキームは ampless の標準テーマトークン経由で反映されます。

package/dist/templates/blog/README.md

@@ -1,49 +1,22 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Blog theme
 
-A blog site powered by [ampless](https://github.com/heavymoons/ampless).
+Neutral monochrome with shadcn/ui defaults. Chronological post feed, single-post page, and tag listing.
 
-## Getting Started
+## Customizing
 
-This project uses Amplify Gen 2 for the backend (Cognito, DynamoDB, S3) and Next.js for the frontend.
+In `/admin/sites/<siteId>/theme`:
 
-```bash
-# 1. Install dependencies
-npm install
+- **Primary color** — buttons, links, accent fills
+- **Accent color**
+- **Focus ring**
+- **Destructive** — color used for destructive actions
+- **Corner radius**
+- **Body font** — System sans / Serif (Georgia) / Serif (Iowan) / Monospace
+- **Featured post slug** — pin one published post to the top of the home page
+- **Logo image URL**
+- **Header navigation** — label + URL pairs
+- **Footer links** — label + URL pairs
 
-# 2. Deploy a personal AWS sandbox + start the Next.js dev server.
-#    Requires AWS credentials configured (`aws configure`).
-#    First run takes ~5–10 min to provision resources;
-#    amplify_outputs.json is regenerated each time before dev starts.
-npm run sandbox
-```
-
-Then open [http://localhost:3000](http://localhost:3000).
-
-## First admin user
-
-Open [http://localhost:3000/login](http://localhost:3000/login) and click **Create admin account**. The first user to register is automatically added to the `ampless-admin` Cognito group.
-
-After that, manage content from `/admin`:
-
-- `/admin` — dashboard
-- `/admin/posts` — list / create / edit posts (tiptap editor)
-- `/admin/media` — upload images to S3
-
-## Production deploy
-
-```bash
-git init && git add . && git commit -m "init"
-git remote add origin <your-repo>
-git push
-# Then connect the repo to AWS Amplify Hosting in the AWS console.
-```
-
-## Customize
-
-- `cms.config.ts` — site name, media delivery mode, plugins
-- `app/` — Next.js App Router pages (`(public)/` for the blog, `(admin)/` for the CMS)
-- `amplify/` — Amplify Gen 2 backend definitions (auth / data / storage)
-
-## Plugins
-
-Enabled: {{plugins}}
+Per-site light/dark color scheme is honored through the standard ampless theme tokens.

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

@@ -0,0 +1,18 @@
+> English: [README.md](./README.md)
+> 
+# Corporate テーマ
+
+企業サイト向けの落ち着いたレイアウト。明るい背景にネイビーの配色、ヒーロー + お知らせ一覧構成、ヘッダー / フッターナビ付き。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **タグライン** — ヒーロー内、サイト名の上に表示される短いフレーズ
+- **プライマリカラー**
+- **角丸**
+- **トップストーリーのスラッグ** — ヒーローとお知らせ一覧の間に公開済み投稿を 1 件フィーチャー
+- **ロゴ画像 URL**
+- **ヘッダーナビ** — ラベル + URL のペア
+- **フッターリンク** — ラベル + URL のペア
+- **フッター注記** — 住所 / 会社情報 / 追加の注意書き

package/dist/templates/corporate/README.md

@@ -1,19 +1,18 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Corporate theme
 
-Corporate / company-site theme: navy on near-white, hero + news layout, header + footer navigation.
+Conservative business / company-site layout with hero and news section. Navy on near-white, header + footer navigation.
 
 ## Customizing
 
 In `/admin/sites/<siteId>/theme`:
 
-- Tagline (small line above the site name in the hero)
-- Header navigation (label + URL pairs)
-- Footer links + legend (address / company info / extra small print)
-- Primary color, corner radius
-
-## Getting started
-
-```bash
-npm install
-npm run sandbox
-```
+- **Tagline** — short phrase shown above the site name in the hero
+- **Primary color**
+- **Corner radius**
+- **Top story slug** — feature one published post between the hero and the news section
+- **Logo image URL**
+- **Header navigation** — label + URL pairs
+- **Footer links** — label + URL pairs
+- **Footer legend** — address / company info / extra small print

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

@@ -0,0 +1,31 @@
+> English: [README.md](./README.md)
+> 
+# DADS テーマ
+
+デジタル庁デザインシステム準拠のレイアウト。政府・自治体・公共系サイト向け。高コントラスト、アクセシビリティ重視、装飾控えめ。公式の **[デジタル庁デザインシステム Tailwind プラグイン](https://github.com/digital-go-jp/tailwind-theme-plugin)**（`@digital-go-jp/tailwind-theme-plugin`、MIT）をベースに構築されています。
+
+## プラグインが提供する機能
+
+- **カラーパレット** — プライマリカラーに `solidBlue`（`#0017c1`）を使用し、DADS の全スケール（ライトブルー、シアン、グリーン、ライム、イエロー、オレンジ、レッド、マゼンタ）を Tailwind クラス（`bg-blue-900`、`text-blue-50` など）で利用可能
+- **タイポグラフィ** — プラグイン経由で `fontFamily.sans` に Noto Sans JP を設定。`--ampless-body-font` として参照可能
+- **ボーダー半径** — `rounded-4` / `rounded-6` が利用可能
+
+`tokens.css` がプラグインの CSS 変数（`--color-blue-900` など）を ampless 標準のテーマ変数（`--primary`、`--background` など）にバインドするため、共有 chrome（SiteHeader、SiteFooter、shadcn ボタンなど）が自動的に DADS カラーで描画されます。
+
+DADS が新しいパレットバージョンを公開した場合、`@digital-go-jp/tailwind-theme-plugin` をバージョンアップするだけでテーマに反映されます。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **ロゴ画像 URL** — 組織マーク
+- **プライマリカラー** — デフォルトは DADS の `solidBlue`。DADS 以外の色に変更するとサイトは DADS 準拠ではなくなります。
+- **トップストーリーのスラッグ** — ヒーローとお知らせ一覧の間に公開済み投稿を 1 件フィーチャー
+- **ヘッダーナビ** — ラベル + URL のペア
+- **フッターリンク** — ラベル + URL のペア
+- **フッター注記** — 住所 / 機関情報 / 追加の注意書き
+
+## 注意事項
+
+- ダークモードは反転色による近似実装です。プラグイン 0.3.4 時点では DADS の公式ダークパレットは存在しません。公式ダークパレットが公開された際は、`tokens.css` のダーク変数バインディングを更新してください。
+- このプラグインはデザイントークンのみを提供します。フル DADS コンポーネント（ボタン、アラート、タブなど）については [design-system-example-components](https://github.com/digital-go-jp/design-system-example-components) を参照し、必要に応じて取り込んでください。

package/dist/templates/dads/README.md

@@ -1,6 +1,8 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# DADS theme
 
-DADS theme — built on the official **[Digital Agency Design System Tailwind plugin](https://github.com/digital-go-jp/tailwind-theme-plugin)** (`@digital-go-jp/tailwind-theme-plugin`, MIT). Color palette and typography conform to DADS specifications, suitable for Japanese government / public-sector / institutional sites.
+Government / public-sector layout following the Digital Agency Design System aesthetic. High contrast, accessibility-first, minimal decoration. Built on the official **[Digital Agency Design System Tailwind plugin](https://github.com/digital-go-jp/tailwind-theme-plugin)** (`@digital-go-jp/tailwind-theme-plugin`, MIT).
 
 ## What's plugin-backed
 
@@ -8,27 +10,22 @@ DADS theme — built on the official **[Digital Agency Design System Tailwind pl
 - **Typography** — `fontFamily.sans` set to Noto Sans JP via the plugin; surfaced through `--ampless-body-font`
 - **Border radii** — `rounded-4` / `rounded-6` available
 
-`templates/dads/tokens.css` binds the plugin's CSS variables (`--color-blue-900` etc.) to ampless's standard theme variables (`--primary`, `--background`, ...) so all shared chrome (SiteHeader, SiteFooter, shadcn buttons, etc.) automatically renders in DADS colors.
+`tokens.css` binds the plugin's CSS variables (`--color-blue-900` etc.) to the standard ampless theme variables (`--primary`, `--background`, ...) so all shared chrome (SiteHeader, SiteFooter, shadcn buttons, etc.) automatically renders in DADS colors.
 
-When DADS publishes a new palette version, bumping `@digital-go-jp/tailwind-theme-plugin` in `package.json` is enough — the theme picks it up.
+When DADS publishes a new palette version, bumping `@digital-go-jp/tailwind-theme-plugin` is enough — the theme picks it up.
 
 ## Customizing
 
 In `/admin/sites/<siteId>/theme`:
 
-- **Logo image URL** — branding (organization mark)
-- **Primary color** — defaults to DADS solidBlue. Changing to a non-DADS color makes the site no longer DADS-conformant.
-- **Top story slug** — feature one published post between hero and news
-- **Header navigation / Footer links / Footer legend**
+- **Logo image URL** — organization mark
+- **Primary color** — defaults to DADS `solidBlue`. Changing to a non-DADS color makes the site no longer DADS-conformant.
+- **Top story slug** — feature one published post between the hero and the news section
+- **Header navigation** — label + URL pairs
+- **Footer links** — label + URL pairs
+- **Footer legend** — address / agency info / extra small print
 
 ## Notes
 
-- Dark mode uses an inverted approximation. DADS doesn't ship an official dark palette as of plugin 0.3.4; when one lands, update `templates/dads/tokens.css` to bind the dark variables.
+- Dark mode uses an inverted approximation. DADS doesn't ship an official dark palette as of plugin 0.3.4; when one lands, update `tokens.css` to bind the dark variables.
 - The plugin only provides design tokens. For full DADS components (buttons, alerts, tabs, etc.), see [design-system-example-components](https://github.com/digital-go-jp/design-system-example-components) and adapt as needed.
-
-## Getting started
-
-```bash
-npm install
-npm run sandbox
-```

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

@@ -0,0 +1,24 @@
+> English: [README.md](./README.md)
+> 
+# Docs テーマ
+
+サイドバー主導のドキュメントレイアウト。サイドバー項目は通常のリンクに加え、**タグ駆動セクション**を組み合わせられます — `tag:<name>` 形式の項目を入れると、そのタグが付いた公開済み投稿の一覧に自動展開されます。タグでコンテンツを整理するだけでナビゲーションに自動反映されます。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **プライマリカラー**
+- **角丸**
+- **コードフォント** — システム等幅 / JetBrains Mono
+- **サイドバーナビ** — 各行は `ラベル` + `URL`。URL には以下を指定可能:
+  - パス（`/getting-started`）
+  - 外部 URL（`https://...`）
+  - タグ参照（`tag:tutorials`）→ 見出し + タグ付き投稿一覧として描画
+- **ロゴ画像 URL**
+- **ヘッダーナビ** — トップレベルのリンク
+- **フッターリンク** — ラベル + URL のペア
+
+## 執筆のヒント
+
+投稿に `guide` タグを付けて、サイドバーに URL `tag:guide` の行を追加するだけ。新しい記事を公開しても手動でリンクを編集する必要はなく、サイドバーに自動で並びます。

package/dist/templates/docs/README.md

@@ -1,26 +1,24 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Docs theme
 
-Docs theme: sidebar-led documentation layout. The sidebar combines plain links with **tag-driven sections** — entering a URL like `tag:guide` in the sidebar nav field auto-expands to a list of every published post tagged "guide". Lets writers organize content by tag and have it appear in nav automatically.
+Sidebar-led documentation layout. The sidebar combines plain links with **tag-driven sections** — a sidebar entry of the form `tag:<name>` auto-expands into a list of every published post with that tag. Lets writers organize content by tag and have it appear in nav automatically.
 
 ## Customizing
 
 In `/admin/sites/<siteId>/theme`:
 
+- **Primary color**
+- **Corner radius**
+- **Code font** — System monospace / JetBrains Mono
 - **Sidebar navigation** — each row is `Label` + `URL`. The URL can be:
   - a path (`/getting-started`)
   - an external URL (`https://...`)
   - a tag reference (`tag:tutorials`) → renders as a heading + list of tagged posts
-- Header navigation (top-level links)
-- Code font (system mono / JetBrains Mono / etc.)
-- Primary color, corner radius
+- **Logo image URL**
+- **Header navigation** — top-level links
+- **Footer links** — label + URL pairs
 
 ## Authoring tip
 
 Tag a post `guide` (in the post editor) and add a sidebar row with URL `tag:guide`. The sidebar will list that post automatically — no manual link editing every time you publish.
-
-## Getting started
-
-```bash
-npm install
-npm run sandbox
-```

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

@@ -0,0 +1,20 @@
+> English: [README.md](./README.md)
+> 
+# Landing テーマ
+
+1 ページ完結型のヒーロー中心レイアウト。任意で「最新記事」グリッドも併設可能。ヘッダー / フッターナビ設定とウォームコーラル系アクセントパレットを備えます。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **ヒーロー見出し** — 空欄ならサイト名を使用
+- **ヒーローサブ見出し** — 空欄ならサイト説明を使用
+- **CTA ボタンのテキスト**
+- **CTA リンク先**
+- **プライマリカラー**
+- **角丸**
+- **フィーチャー記事のスラッグ** — 公開済み投稿を 1 件ホームに固定
+- **ロゴ画像 URL**
+- **ヘッダーナビ** — ラベル + URL のペア
+- **フッターリンク** — ラベル + URL のペア

package/dist/templates/landing/README.md

@@ -1,24 +1,20 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Landing theme
 
-A site powered by [ampless](https://github.com/heavymoons/ampless), using the **Landing** theme — hero-led single-page layout with optional "Latest" post grid, configurable header / footer nav, and a warm-coral accent palette.
+Single-page hero focus with optional "Latest" post grid. Hero-led layout with configurable header / footer nav and a warm-coral accent palette.
 
 ## Customizing
 
 In `/admin/sites/<siteId>/theme`:
 
-- Hero headline / subheadline / CTA button text + URL
-- Header navigation (label + URL pairs)
-- Footer links
-- Primary color
-- Corner radius
-
-Empty hero fields fall back to the site name / description from `/admin/sites/<siteId>`.
-
-## Getting started
-
-```bash
-npm install
-npm run sandbox        # provision the AWS backend + start Next.js
-```
-
-See the project README for full setup.
+- **Hero headline** — empty falls back to the site name
+- **Hero subheadline** — empty falls back to the site description
+- **CTA button text**
+- **CTA URL**
+- **Primary color**
+- **Corner radius**
+- **Featured post slug** — pin one published post to the home page
+- **Logo image URL**
+- **Header navigation** — label + URL pairs
+- **Footer links** — label + URL pairs

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

@@ -0,0 +1,14 @@
+> English: [README.md](./README.md)
+> 
+# Minimal テーマ
+
+shadcn/ui のカラートークンをベースにした、暖色系ニュートラル地にソフトブルーをアクセントとした構成。カスタマイズ項目を絞ったシンプルなブログレイアウトで、デザインを主張させたくない場合に向きます。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **プライマリカラー**
+- **角丸**
+
+以上です。フォントや複数のアクセントカラー、フッター / ナビゲーションの制御など、より細かい調整が必要な場合は `blog` テーマを利用してください。

package/dist/templates/minimal/README.md

@@ -1,49 +1,14 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Minimal theme
 
-A blog site powered by [ampless](https://github.com/heavymoons/ampless), using the **Minimal** theme — a soft blue accent on a warm-neutral background, derived from shadcn/ui's color tokens.
+Soft blue accent on a warm-neutral background, derived from shadcn/ui's color tokens. Stripped-down blog layout with very few customization knobs — pick this when you want the design to disappear.
 
-## Getting Started
+## Customizing
 
-This project uses Amplify Gen 2 for the backend (Cognito, DynamoDB, S3) and Next.js for the frontend.
+In `/admin/sites/<siteId>/theme`:
 
-```bash
-# 1. Install dependencies
-npm install
+- **Primary color**
+- **Corner radius**
 
-# 2. Deploy a personal AWS sandbox + start the Next.js dev server.
-#    Requires AWS credentials configured (`aws configure`).
-#    First run takes ~5–10 min to provision resources;
-#    amplify_outputs.json is regenerated each time before dev starts.
-npm run sandbox
-```
-
-Then open [http://localhost:3000](http://localhost:3000).
-
-## First admin user
-
-Open [http://localhost:3000/login](http://localhost:3000/login) and click **Create admin account**. The first user to register is automatically added to the `ampless-admin` Cognito group.
-
-After that, manage content from `/admin`:
-
-- `/admin` — dashboard
-- `/admin/posts` — list / create / edit posts (tiptap editor)
-- `/admin/media` — upload images to S3
-
-## Production deploy
-
-```bash
-git init && git add . && git commit -m "init"
-git remote add origin <your-repo>
-git push
-# Then connect the repo to AWS Amplify Hosting in the AWS console.
-```
-
-## Customize
-
-- `cms.config.ts` — site name, media delivery mode, plugins
-- `app/` — Next.js App Router pages (`(public)/` for the blog, `(admin)/` for the CMS)
-- `amplify/` — Amplify Gen 2 backend definitions (auth / data / storage)
-
-## Plugins
-
-Enabled: {{plugins}}
+That's it. For richer customization (fonts, multiple accent colors, footer / nav controls), use the `blog` theme.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "0.2.0-alpha.17",
+  "version": "0.2.0-alpha.19",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",