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

package/README.ja.md

@@ -18,7 +18,7 @@ npx create-ampless@alpha
 3. テーマ — v0.1 では `blog`
 4. プラグイン — `seo`、`rss`、`webhook`
 
-出力は AWS Amplify Gen 2 バックエンド定義を含む Next.js 15（App Router）プロジェクトです。`/admin` に管理パネル、`/` にパブリックブログが設置され、選択したプラグインが `cms.config.ts` にあらかじめ設定されます。また運用メモ用の `RUNBOOK.md` も生成されます。
+出力は AWS Amplify Gen 2 バックエンド定義を含む Next.js 16（App Router）プロジェクトです。`/admin` に管理パネル、`/` にパブリックブログが設置され、選択したプラグインが `cms.config.ts` にあらかじめ設定されます。また運用メモ用の `RUNBOOK.md` も生成されます。
 
 ## 生成されたプロジェクトでの次のステップ
 

package/README.md

@@ -18,7 +18,7 @@ The wizard walks you through:
 3. Theme — `blog` for v0.1
 4. Plugins — `seo`, `rss`, `webhook`
 
-Output is a Next.js 15 (App Router) project with the AWS Amplify Gen 2 backend definitions, an admin panel at `/admin`, public blog at `/`, the chosen plugins pre-wired in `cms.config.ts`, and a `RUNBOOK.md` for operations notes.
+Output is a Next.js 16 (App Router) project with the AWS Amplify Gen 2 backend definitions, an admin panel at `/admin`, public blog at `/`, the chosen plugins pre-wired in `cms.config.ts`, and a `RUNBOOK.md` for operations notes.
 
 ## Next steps inside the generated project
 

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

@@ -0,0 +1,108 @@
+> 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`。
+
+登録方法は 2 つ:
+
+**ローカル stdio（Claude Code / Cursor 向け、推奨）:**
+
+プロジェクトルートの `.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>"
+      }
+    }
+  }
+}
+```
+
+**管理者発行トークンによる HTTP**（ホスト型エージェント向け）: `/admin/mcp-tokens` で Bearer トークンを発行し、エージェントクライアントを公開 MCP HTTP エンドポイントに向ける。エンドポイント URL は管理 UI で確認できる。
+
+投稿本文は `markdown`、`html`、`tiptap`（JSON ドキュメント）の 3 フォーマットに対応している。
+
+## 動作確認の基準
+
+変更後は最低限以下を実行すること:
+
+- `npm run dev` でブラウザから該当ページを開く。UI / テーマの変更は特に目視確認が必要（Playwright MCP が使える場合はスクリーンショットを活用する）。
+- `npm run build` — 本番ビルドが成功することを確認する。
+- `npm run lint`。
+
+UI / テーマを変更した場合、型チェックだけを根拠にタスク完了を報告しない — ブラウザで実際に確認すること。
+
+## 既知の制約
+
+- **サンドボックスのデータは揮発性。** スキーマに影響する変更は API とテーブルの再構築を引き起こす可能性がある。サンドボックスのコンテンツは使い捨てとして扱うこと。本番データは永続する。
+- **マルチサイトモードでは SSR キャッシュが無効になる。** `cms.config.sites` に 1 ドメインだけ設定すれば Amplify Hosting CDN キャッシュが有効になる。複数ドメインを設定するとキャッシュが強制的に無効化される。パフォーマンス施策はこの制約を考慮して計画すること。
+- **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,108 @@
+> 日本語版: [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` — sites, 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`.
+
+Two registration options:
+
+**Local stdio (recommended for Claude Code / Cursor):**
+
+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>"
+      }
+    }
+  }
+}
+```
+
+**HTTP via admin-issued token** (for hosted agents): issue a Bearer token at `/admin/mcp-tokens` and point the agent client at the public MCP HTTP endpoint. See the admin UI for the exact endpoint URL.
+
+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.
+- **Multi-site mode disables SSR caching.** A single configured domain (`cms.config.sites`) enables Amplify Hosting CDN caching; multiple domains force it off. Plan performance work accordingly.
+- **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

@@ -6,6 +6,8 @@
 
 この 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**

package/dist/templates/_shared/README.md

@@ -6,6 +6,8 @@ Your site is built with [ampless](https://github.com/heavymoons/ampless) — a s
 
 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**

package/package.json

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