> 日本語版: [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.