create-ampless 0.2.0-alpha.8 → 1.0.0-alpha.100

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

@@ -0,0 +1,94 @@
+> 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 16 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` — パッケージマネージャーに任せる。
+
+## テーマのカスタマイズ
+
+テーマのカスタマイズ手順 — ベーステーマの選び方、`themes/my-*/`
+へのコピーフロー、Claude Design からの反映、AI 支援の実装、
+レスポンシブの目視確認、Markdown 要素のデザイン方針、よくある失敗
+— は [THEMES.ja.md](./THEMES.ja.md) を参照する。
+
+## MCP サーバー（HTTP トランスポート）
+
+エージェントが `mcp-handler` Lambda 経由で投稿コンテンツを直接クエリ・編集できる。公開ツール: `list_posts`、`get_post`、`create_post`、`update_post`、`delete_post`、`upload_media`、`get_schema`、`upload_static_bundle`、`list_static_files`、`delete_static_file`、`get_site_context`。
+
+登録方法:
+
+1. 管理画面の `/admin/mcp-tokens` で Bearer トークンを発行する。
+2. Amplify コンソールまたは `amplify_outputs.json` で `mcp-handler` の Function URL を確認する。
+3. プロジェクトルートの `.mcp.json` に追加する：
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
+      }
+    }
+  }
+}
+```
+
+投稿本文は `markdown`、`html`、`tiptap`（JSON ドキュメント）の 3 フォーマットに対応している。
+
+## 動作確認の基準
+
+変更後は最低限以下を実行すること:
+
+- `npm run dev` でブラウザから該当ページを開く。UI / テーマの変更は特に目視確認が必要（Playwright MCP が使える場合はスクリーンショットを活用する）。
+- `npm run build` — 本番ビルドが成功することを確認する。
+- `npm run lint`。
+
+UI / テーマを変更した場合、型チェックだけを根拠にタスク完了を報告しない — ブラウザで実際に確認すること。
+
+## 既知の制約
+
+- **サンドボックスのデータは揮発性。** スキーマに影響する変更は API とテーブルの再構築を引き起こす可能性がある。サンドボックスのコンテンツは使い捨てとして扱うこと。本番データは永続する。
+- **1 Amplify デプロイ = 1 サイト。** 複数サイトを別ドメインで配信したい場合は、サイトごとに Amplify 環境を分けてデプロイする。
+- **AppSync 公開 API キーは `amplify_outputs.json` に含まれ、サイト訪問者から見える。** 低信頼の認証情報として扱うこと — このキーの権限は公開済み投稿の読み取りのみ。`api-key-renewer` Lambda が毎月自動ローテーションするため、手動ローテーションは不要。
+- **最初に登録したユーザーが管理者になる。** 以降のロール変更は Cognito コンソールで行う（RUNBOOK 参照）。
+
+## 参照先
+
+- `THEMES.ja.md` — テーマカスタマイズの実務ガイド（ベーステーマの選び方、Claude Design からの反映、AI への依頼、ブラウザ確認、Markdown 要素のスタイリング、よくある失敗）。
+- `README.ja.md` — サイト運営者向けの日常利用ガイド。
+- `RUNBOOK.ja.md` — 定期的な運用手順（キーローテーション、バックアップ復元など）。
+- `themes/<name>/README.ja.md` — テーマごとのカスタマイズ詳細。

package/dist/templates/_shared/AGENTS.md

@@ -0,0 +1,94 @@
+> 日本語版: [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 16 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.
+
+## Theme customization
+
+For theme customization workflows — choosing a base theme, the
+standard copy-and-edit flow, Claude Design handoff, AI-assisted
+implementation, responsive visual QA, Markdown styling expectations,
+and the common failure modes — see [THEMES.md](./THEMES.md).
+
+## MCP server (HTTP transport)
+
+Lets agents query and modify post content directly via the `mcp-handler` Lambda. Tools exposed: `list_posts`, `get_post`, `create_post`, `update_post`, `delete_post`, `upload_media`, `get_schema`, `upload_static_bundle`, `list_static_files`, `delete_static_file`, `get_site_context`.
+
+Registration:
+
+1. Issue a Bearer token from `/admin/mcp-tokens` in the admin UI.
+2. Find the `mcp-handler` Function URL in the Amplify console or `amplify_outputs.json`.
+3. Add to `.mcp.json` at the project root:
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
+      }
+    }
+  }
+}
+```
+
+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 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
+
+- `THEMES.md` — theme customization workflows (base-theme selection, Claude Design handoff, AI prompts, browser QA, Markdown styling, common pitfalls).
+- `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.

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

@@ -0,0 +1,239 @@
+> English: [README.md](./README.md)
+> 
+# {{siteName}}
+
+このサイトは [ampless](https://github.com/heavymoons/ampless) で構築されています — AWS Amplify Gen 2（Cognito + DynamoDB + S3 + AppSync + Lambda）上で動くサーバーレス CMS、フロントエンドは Next.js 16。
+
+この 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 22+** と **npm**。
+- **AWS アカウント.** [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) をインストールしてから `aws configure` で認証情報とデフォルトリージョンを設定します。sandbox / 本番ともに実 AWS リソースをデプロイします。
+- **GitHub アカウント** — AWS Amplify Hosting 経由の本番デプロイで必要。下記の [CLI デプロイフロー](#方法-1-cli-ワンショット推奨) を使う場合は [`gh` CLI](https://cli.github.com/) を `gh auth login` で認証する（または `repo` スコープ付きの `GITHUB_TOKEN` 環境変数を設定する）必要があります。コンソール経由の手動フローには `gh` は不要です。
+
+## コマンド
+
+| コマンド | 内容 |
+| --- | --- |
+| `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
+```
+
+インストール済みテーマを `npm run update-ampless` で上書きされない形でカスタマイズしたい場合は、`my-` プレフィックス付きにコピーする:
+
+```bash
+npm run copy-theme blog my-blog
+```
+
+テーマカスタマイズの実務ガイド — ベーステーマの選び方、コピー / 編集 / 切り替えの標準フロー、Claude Design からの反映、AI を使った実装、レスポンシブ確認、Markdown 要素のスタイリング、よくある失敗 — はこのプロジェクト内の [THEMES.ja.md](./THEMES.ja.md)（[English](./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: CLI ワンショット（推奨）
+
+このプロジェクトディレクトリ内で:
+
+```bash
+npx create-ampless@latest --mount \
+  --github-owner <your-user-or-org> \
+  --aws-region <region> \
+  --create-iam-role           # 初回のみ。次回以降は `--iam-service-role <arn>` で使い回し
+```
+
+CLI が以下を一気に実行します:
+
+1. GitHub repo を作成（認証済みの `gh` CLI、`GITHUB_TOKEN` 環境変数、または `--github-token` フラグを利用）
+2. プロジェクトを repo に push
+3. Amplify Hosting アプリ + ブランチ作成、GitHub 連携登録、`amplify.yml` ビルド spec 配置
+4. 初回デプロイ起動
+
+便利な追加フラグ:
+
+- `--github-private` — private repo を作成（デフォルト: public）
+- `--domain <name>` `--subdomain <prefix>` — 同じ流れの中でカスタムドメインをバインド
+- `--skip-confirm` — 非対話モード（CI / 再実行向け）
+- `--aws-profile <name>` — 複数 AWS profile がある場合に明示
+
+全フラグは `npx create-ampless@latest --help` を参照。
+
+**このフロー固有の事前準備（[トップの必要なもの](#必要なもの) に加えて）:**
+
+| | 用途 | 準備方法 |
+|---|---|---|
+| `aws` CLI 認証済み | Amplify Hosting アプリ + サービスロールの provision | [インストール](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) して `aws configure` を実行（または `aws sso login`）。`aws sts get-caller-identity` で確認。 |
+| `gh` CLI 認証済み **または** `GITHUB_TOKEN` env | GitHub repo を作成して初回コミットを push | [`gh` をインストール](https://cli.github.com/) して `gh auth login` を実行、**または** `repo` スコープ付きの [personal access token](https://github.com/settings/tokens) を `GITHUB_TOKEN` として export。`--github-token <token>` を直接渡す場合は不要。 |
+| Amplify Hosting 用 IAM service role | Amplify が代理で backend リソースをデプロイするのに必要 | `--create-iam-role` を渡せば CLI が `AmplifyDeployBackend`（idempotent）を provision。または `--iam-service-role <arn>` で既存ロールを再利用。ロールは `amplify.amazonaws.com` を trust し、`AdministratorAccess-Amplify` を attach している必要があります。 |
+
+### 方法 2: コンソール（手動）
+
+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 は HTTP トランスポート + Bearer トークン認証による MCP（Model Context Protocol）サーバーを同梱しているので、Claude Desktop / Cursor / Claude Code など MCP に対応した AI クライアントから投稿の読み書きができます。
+
+**セットアップ手順:**
+
+1. 管理画面の `/admin/mcp-tokens` にアクセスし、Bearer トークン（`amk_...`）を発行する。
+2. Amplify コンソールまたは `amplify_outputs.json` で `mcp-handler` Lambda の Function URL を確認する。
+3. MCP クライアントの設定ファイル（プロジェクトルートの `.mcp.json`、`claude_desktop_config.json` など）にエントリを追加する：
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
+      }
+    }
+  }
+}
+```
+
+MCP のセットアップとトークン管理の詳細については [docs/architecture/04-access-layer-mcp.md](./docs/architecture/04-access-layer-mcp.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) を参照。