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

package/dist/templates/_shared/README.md

@@ -0,0 +1,239 @@
+> 日本語版: [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 16 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 22+** and **npm**.
+- **AWS account.** Install the [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html), then `aws configure` to set credentials + default region. The sandbox + production both deploy real AWS resources.
+- **GitHub account** for production hosting via AWS Amplify Hosting. The CLI deploy flow ([below](#option-1-cli-one-shot-recommended)) also needs the [`gh` CLI](https://cli.github.com/) authenticated via `gh auth login` (or a `GITHUB_TOKEN` env var with `repo` scope). The manual console flow doesn't need `gh`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `npm install` | Install dependencies |
+| `npm run sandbox` | Provision a personal AWS sandbox (Cognito / DynamoDB / S3 / etc.), regenerate `amplify_outputs.json`, then start `next dev` on `http://localhost:3000` |
+| `npm run dev` | Start Next.js only (skip sandbox provisioning — use after `sandbox` has already run once) |
+| `npm run build` | Production build of the Next.js app (also runs as part of Amplify Hosting deploy) |
+| `npm run start` | Serve the production build locally |
+| `npm run lint` | Lint with `next lint` |
+| `npm run update-ampless` | Pull the latest ampless template files into this project, preserving your config and themes (see "Updating ampless" below) |
+| `npm run copy-theme` | Add another official theme to this project after-the-fact |
+
+## First time setup
+
+```bash
+npm install
+npm run sandbox
+```
+
+First sandbox run takes 5–10 minutes (AWS resource provisioning). `amplify_outputs.json` is regenerated each time before `next dev` starts.
+
+Open [http://localhost:3000/login](http://localhost:3000/login) and click **Create admin account**. The first registered user is automatically added to the `ampless-admin` Cognito group.
+
+## Admin UI
+
+After signing in, the admin lives at `/admin`:
+
+| Path | Purpose |
+| --- | --- |
+| `/admin` | Dashboard |
+| `/admin/posts` | List / create / edit posts (Tiptap editor, Markdown, raw HTML, or zip-uploaded static bundles) |
+| `/admin/media` | Upload images / videos / files to S3 |
+| `/admin/sites/<siteId>` | Site-level settings (name, URL) |
+| `/admin/sites/<siteId>/theme` | Activate a theme + customize its fields (colors, fonts, nav, logo, etc.) |
+| `/admin/users` | View users + Cognito group memberships |
+| `/admin/mcp-tokens` | Issue Bearer tokens for the HTTP MCP endpoint |
+
+User roles (Cognito groups):
+
+- `ampless-admin` — full access (content + ops + destructive)
+- `ampless-editor` — content CRUD (no destructive ops)
+- `ampless-reader` — reserved for future REST/MCP API consumers
+
+Promotion/demotion is done in the AWS Cognito console — see [RUNBOOK.md → Promote / demote a user](./RUNBOOK.md#promote--demote-a-user).
+
+## Authoring content
+
+Posts are the single content type. Each post has:
+
+- **Format** — `tiptap` (rich text) / `markdown` / `html` (raw, no sanitization) / `static` (zip-upload of HTML/CSS/JS)
+- **No layout** flag (`format: 'html'` only) — render the body verbatim with no Next.js layout and no theme chrome. URL stays `/<slug>`; middleware rewrites the request to the internal bare-HTML handler.
+- **Cache strategy** (`metadata.cache`) — override the per-post Cache-Control: `'auto'` (default; cooldown by edit time), `'deep'` (always long-cache), or `'hot'` (always no-store). See `docs/CONTENT.md` for details.
+- **Slug** — the public URL
+- **Status** — `draft` (admin only) or `published`
+
+Full reference: [docs/CONTENT.md on GitHub](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.md) ([日本語](https://github.com/heavymoons/ampless/blob/main/docs/CONTENT.ja.md)).
+
+## Themes
+
+Every installed theme is bundled in this project under `themes/<name>/`. The **active** theme per site is a runtime setting — switching themes does **not** require a redeploy.
+
+To switch the active theme: `/admin/sites/<siteId>/theme` → pick from the installed list → save.
+
+To customize the active theme (colors, fonts, header / footer nav, etc.): same page — each theme exposes its own customization fields. See `themes/<name>/README.md` for what's customizable per theme.
+
+To install another official theme into this project:
+
+```bash
+npm run copy-theme
+```
+
+To customize an installed theme without losing the customization on `npm run update-ampless`, copy it under the `my-` prefix:
+
+```bash
+npm run copy-theme blog my-blog
+```
+
+The full working guide for theme customization — base-theme selection, the standard copy / edit / activate flow, Claude Design handoff, AI-assisted implementation, responsive QA, Markdown styling, and the common pitfalls — lives in [THEMES.md](./THEMES.md) (and [THEMES.ja.md](./THEMES.ja.md)) right in this project.
+
+## 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.
+
+### Option 1: CLI one-shot (recommended)
+
+From inside this project directory:
+
+```bash
+npx create-ampless@latest --mount \
+  --github-owner <your-user-or-org> \
+  --aws-region <region> \
+  --create-iam-role           # first time only; reuse `--iam-service-role <arn>` on later mounts
+```
+
+The CLI:
+
+1. Creates a GitHub repo (uses your authenticated `gh` CLI, the `GITHUB_TOKEN` env var, or the `--github-token` flag).
+2. Pushes this project to that repo.
+3. Provisions an Amplify Hosting app + branch, registers the GitHub connection, writes the `amplify.yml` build spec.
+4. Kicks off the first deploy.
+
+Useful extra flags:
+
+- `--github-private` — private repo (default: public)
+- `--domain <name>` `--subdomain <prefix>` — bind a custom domain in the same pass
+- `--skip-confirm` — non-interactive (good for CI / re-runs)
+- `--aws-profile <name>` — explicit AWS profile when you have multiple
+
+See `npx create-ampless@latest --help` for the full list.
+
+**Prerequisites for this flow (in addition to the [top-level Requirements](#requirements)):**
+
+| | Why | How |
+|---|---|---|
+| `aws` CLI authenticated | Provisions the Amplify Hosting app + service role | [Install](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) and run `aws configure` (or `aws sso login`). Verify with `aws sts get-caller-identity`. |
+| `gh` CLI authenticated **or** `GITHUB_TOKEN` env | Creates the GitHub repo and pushes the initial commit | [Install `gh`](https://cli.github.com/) and `gh auth login`, **or** export a [personal access token](https://github.com/settings/tokens) with `repo` scope as `GITHUB_TOKEN`. Skip if you pass `--github-token <token>` directly. |
+| IAM service role for Amplify Hosting | Lets Amplify deploy backend resources on your behalf | Either pass `--create-iam-role` to have the CLI provision one named `AmplifyDeployBackend` (idempotent), or pass `--iam-service-role <arn>` to reuse an existing role. The role must trust `amplify.amazonaws.com` and have `AdministratorAccess-Amplify` attached. |
+
+### Option 2: Console (manual)
+
+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 via HTTP transport with Bearer token authentication.
+
+**Setup:**
+
+1. Go to `/admin/mcp-tokens` in your admin UI and issue a Bearer token (`amk_...`).
+2. Find the `mcp-handler` Lambda Function URL in your Amplify console or `amplify_outputs.json`.
+3. Add an entry to your MCP client's config (`.mcp.json` at the project root, `claude_desktop_config.json`, etc.):
+
+```json
+{
+  "mcpServers": {
+    "ampless": {
+      "url": "https://<function-url-id>.lambda-url.<region>.on.aws/",
+      "transport": "http",
+      "headers": {
+        "Authorization": "Bearer amk_..."
+      }
+    }
+  }
+}
+```
+
+See [docs/architecture/04-access-layer-mcp.md](./docs/architecture/04-access-layer-mcp.md) for the full MCP setup and token management guide.
+
+## Updating ampless
+
+ampless releases on the `alpha` dist-tag. To pick up new features:
+
+```bash
+npm run update-ampless
+```
+
+This runs `npx create-ampless@latest upgrade`, which:
+
+- Bumps the `@ampless/*` and `ampless` dependencies in `package.json`
+- Re-syncs the shared template files (admin app shell, amplify backend, lib/, middleware, themes) — your customizations to `cms.config.ts`, `theme.*` admin settings, posts, and theme manifest values are preserved.
+- Updates `update-ampless` and `copy-theme` script entries if their commands change
+
+You can review the diff before committing.
+
+## Operations
+
+Day-to-day operational recipes — user promotion, password reset, backup restore, custom domain wiring, AppSync API key rotation — live in [RUNBOOK.md](./RUNBOOK.md).
+
+## License
+
+This project's own code is yours. ampless itself is MIT-licensed; see the [ampless repository](https://github.com/heavymoons/ampless) for details.

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

@@ -0,0 +1,120 @@
+> English: [RUNBOOK.md](./RUNBOOK.md)
+> 
+
+# ランブック
+
+ampless で構築したサイトで、ときどき必要になる運用作業の手順集です。毎日やるわけではないけれど、いざ必要になったときに迷わずに進めるためのものです。
+
+日常的な使い方（コマンド、管理画面、テーマ、プラグイン、デプロイなど）は [README.ja.md](./README.ja.md) を参照してください。
+
+## 目次
+
+- [AppSync API キー（自動更新）](#appsync-api-キー自動更新)
+- [よくある運用](#よくある運用)
+  - [ユーザーの昇格 / 降格](#promote--demote-a-user)
+  - [パスワードリセット（管理者上書き）](#reset-a-users-password-admin-override)
+  - [Post テーブルのバックアップから復元](#restore-from-a-post-table-backup)
+  - [失敗したプラグインイベントを確認する](#inspect-failed-plugin-events)
+- [カスタムドメイン](#custom-domains)
+  - [カスタムドメインを Amplify Hosting に追加する](#adding-a-custom-domain-to-amplify-hosting)
+
+## AppSync API キー（自動更新）
+
+パブリックブログの読み取り（`listPublishedPosts`、`getPublishedPost`、`listPostsByTag`）は AppSync API キーで保護されています。このキーは `amplify_outputs.json` に含まれているため、**公開サイトを訪問した誰もが確認できる**状態にあります。低信頼度のクレデンシャルとして扱ってください。このキーが持つ権限は上記 3 つのカスタムクエリを呼び出すことのみであり、それらのクエリは `status === 'published'` の行しか返しません。
+
+### なぜ API キーなのか（Identity Pool ゲストロールではなく）？
+
+Amplify Gen 2 の `a.handler.custom` リゾルバーは `allow.guest()` や `allow.authenticated('identityPool')` をサポートしておらず、apiKey / userPool / lambda / group / owner のみが使用可能です。ampless では簡潔さを優先して API キーを選択しています。パブリック読み取りを Lambda 関数データソース（`a.handler.function`）に移行することは将来の選択肢です。
+
+### 自動更新 — ローテーション手順は不要
+
+`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）は `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` でメッセージを確認してください。ampless にはデフォルトの自動アラームがないため、定期的な手動確認を推奨します。あるいは `ApproximateNumberOfMessagesVisible` に CloudWatch アラームを設定してください。
+
+## カスタムドメイン
+
+ampless は 1 Amplify デプロイ = 1 サイト。複数サイトを別ドメインで配信したい場合は、サイトごとに Amplify 環境を分けてデプロイしてください。
+
+### Amplify Hosting へのカスタムドメイン追加
+
+バインドしたいドメインごとに以下を実施します：
+
+1. **Amplify Hosting コンソール** → アプリ → **Domain management** → **Add domain** を選択。
+2. 頂点ドメイン（`example.com`）と接続したいサブドメインを入力します。Amplify が ACM 証明書と CloudFront SAN エントリを自動でプロビジョニングします。
+3. DNS を更新：
+   - **Route 53 / Amplify 管理の DNS プロバイダー**：Amplify が CNAME を作成してくれるので、確認するだけです。
+   - **外部 DNS**（Cloudflare、Squarespace など）：Amplify が表示する CNAME / DNS 検証レコードをコピーします。ACM のメール検証もフォールバックとして使用できます。
+4. **Domain activation** が完了するまで待ちます（通常 15〜60 分。証明書の検証が最も時間がかかります）。
+5. `cms.config.ts` の `site.url` を新しい canonical URL に更新し、commit して push します：
+   ```bash
+   git add cms.config.ts && git commit -m "feat: bind docs.example.com"
+   git push   # Amplify Hosting が自動検出します
+   ```
+
+エンドツーエンドで確認：
+
+```bash
+curl -I https://docs.example.com/   # 200 とサイトの HTML
+```

package/dist/templates/_shared/RUNBOOK.md

@@ -1,6 +1,22 @@
+> 日本語版: [RUNBOOK.ja.md](./RUNBOOK.ja.md)
+> 
+
 # Runbook
 
-Operational tasks for an ampless-powered site.
+Step-by-step recipes for occasional operations on an ampless-powered site — the things you don't do every day but want a reliable procedure for when you do.
+
+For day-to-day usage (commands, admin UI tour, themes, plugins, deploying), start with [README.md](./README.md).
+
+## Contents
+
+- [AppSync API key (auto-renewed)](#appsync-api-key-auto-renewed)
+- [Common operations](#common-operations)
+  - [Promote / demote a user](#promote--demote-a-user)
+  - [Reset a user's password (admin override)](#reset-a-users-password-admin-override)
+  - [Restore from a Post-table backup](#restore-from-a-post-table-backup)
+  - [Inspect failed plugin events](#inspect-failed-plugin-events)
+- [Custom domains](#custom-domains)
+  - [Adding a custom domain to Amplify Hosting](#adding-a-custom-domain-to-amplify-hosting)
 
 ## AppSync API key (auto-renewed)
 
@@ -15,9 +31,9 @@ return rows where `status === 'published'`.
 
 Amplify Gen 2 `a.handler.custom` resolvers don't support `allow.guest()`
 or `allow.authenticated('identityPool')` — only apiKey / userPool /
-lambda / group / owner. v0.1 chose API key for simplicity; switching
-the public reads to a Lambda function data source (`a.handler.function`)
-is a v0.2 candidate.
+lambda / group / owner. ampless uses the API key for simplicity;
+moving the public reads to a Lambda function data source
+(`a.handler.function`) is a future option.
 
 ### Auto-renewal — no rotation runbook required
 
@@ -85,8 +101,8 @@ The `/login` page also has a self-service "Forgot password?" flow.
 
 ### Restore from a Post-table backup
 
-DynamoDB Point-in-Time Recovery is **not** enabled by `defineData` in
-v0.1; turn it on manually via AWS Console → DynamoDB → Tables →
+DynamoDB Point-in-Time Recovery is **not** enabled by `defineData`;
+turn it on manually via AWS Console → DynamoDB → Tables →
 `<your post table>` → Backups → Edit PITR. Once enabled, restoration
 takes the form `aws dynamodb restore-table-to-point-in-time` to a new
 table; you'll need to migrate items back to the live table afterwards.
@@ -96,52 +112,14 @@ table; you'll need to migrate items back to the live table afterwards.
 Failed processor invocations land in the shared events DLQ created in
 `amplify/backend.ts` (`EventsDlq`). View messages via the SQS console
 or `aws sqs receive-message --queue-url <dlq-url> --max-number-of-messages 10`.
-There's no automated alarm in v0.1 — periodic manual checks recommended,
-or wire up a CloudWatch alarm on `ApproximateNumberOfMessagesVisible`.
-
-## Multi-site / custom domains
-
-ampless can serve multiple sites from one Amplify Hosting deployment.
-Each site is identified by a `siteId` and bound to one or more
-hostnames via `cms.config.ts`:
-
-```ts
-sites: {
-  blog: {
-    domains: ['blog.example.com', 'www.example.com'],
-    name: 'My Blog',
-    url: 'https://blog.example.com',
-  },
-  docs: {
-    domains: ['docs.example.com'],
-    name: 'Docs',
-    url: 'https://docs.example.com',
-  },
-},
-```
+ampless doesn't ship an automated alarm out of the box — periodic
+manual checks are recommended, or wire up a CloudWatch alarm on
+`ApproximateNumberOfMessagesVisible`.
 
-The middleware (`middleware.ts`) maps incoming `Host` to a `siteId` and
-internally rewrites the path to `/_sites/{siteId}/...`. Subdomains and
-fully separate domains are equivalent at the application layer — only
-the AWS-side wiring differs.
+## Custom domains
 
-### Single domain operation
-
-If `sites` is undefined or has only one entry, ampless runs in
-single-site mode (`siteId='default'`). SSR responses follow each page's
-own caching directives (so you can opt into CloudFront caching with
-`Cache-Control: public, s-maxage=...` per route).
-
-### Multi-site mode caveat: SSR caching is force-disabled
-
-When two or more sites are declared, the middleware adds
-`Cache-Control: private, no-store` to every public response. This is
-because Amplify Hosting's CloudFront does not include `Host` in its
-cache key — leaving caching on would let `https://site1/foo` and
-`https://site2/foo` cross-contaminate at the edge. The trade-off is
-that every public read hits Lambda. Lifting it requires moving off
-Amplify Hosting onto a self-managed CloudFront + Open Next stack
-(roadmap: post-v1.0).
+ampless runs one site per Amplify deployment. To serve multiple sites
+on different domains, deploy a separate Amplify environment per site.
 
 ### Adding a custom domain to Amplify Hosting
 
@@ -160,19 +138,15 @@ For each domain you want to bind:
      also works as a fallback.
 4. Wait for the **Domain activation** to finish (typically 15–60
    minutes; certificate validation is the slow step).
-5. Add the new domain to the matching `sites.{id}.domains[]` in
-   `cms.config.ts` and redeploy:
+5. Update `cms.config.ts` so `site.url` reflects the new canonical URL,
+   commit, and push to redeploy:
    ```bash
-   git add cms.config.ts && git commit -m "feat: add docs.example.com"
+   git add cms.config.ts && git commit -m "feat: bind docs.example.com"
    git push   # Amplify Hosting picks it up
    ```
 
 Verify end-to-end:
 
 ```bash
-curl -I https://docs.example.com/                  # 200 with the docs site's HTML
-curl -sI https://docs.example.com/ | grep -i cache # Cache-Control: private, no-store
+curl -I https://docs.example.com/   # 200 with your site's HTML
 ```
-
-If the request returns `404 Site not found` instead, the host is not
-listed in any `sites.*.domains[]` — fix the config and redeploy.