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

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.

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

@@ -0,0 +1,175 @@
+> 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>` のままで、ルートが `/_/<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 署名 |
+
+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,175 @@
+> 日本語版: [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>`; the route redirects to `/_/<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 |
+
+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.