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

package/dist/templates/_shared/lib/admin.ts

@@ -1,19 +1,18 @@
 // Wired-up admin UI factory. Single source of truth for the admin
 // library — every admin route shell, API route shell, and form
-// re-export shim imports the `admin` value from here.
-//
-// L2 architectural change (admin extraction): admin UI now lives in
-// `@ampless/admin`. This module wires the project's
+// imports the `admin` value from here. Admin UI lives in
+// `@ampless/admin`; this module wires the project's
 // `amplify_outputs.json` and `cms.config` into a single `Admin`
 // instance.
 //
-// NOTE: We intentionally do NOT pass an `ampless` instance to
-// createAdmin. That would import `lib/ampless.ts`, which imports
-// `themes-registry`, which (via theme pages → `lib/i18n.ts`) imports
-// back to this file — a circular chain that crashes with a TDZ
-// ReferenceError on `ampless` at module init. `createAdmin` builds
-// its own internal Ampless when omitted, which is functionally
-// equivalent for admin's needs.
+// NOTE: we pass `ampless` as a thunk (not the resolved instance) so we
+// don't have a static `import './ampless'` at the top of this file.
+// A static import would form the cycle
+//   `lib/admin.ts → lib/ampless.ts → themes-registry → themes → lib/admin.ts`
+// and crash with a TDZ ReferenceError on `ampless` at module init.
+// The thunk uses dynamic `import()` so `lib/ampless.ts` only loads on
+// the first `loadSiteSettings` / `loadThemeConfig` call (request
+// time), by which point every module has finished initialising.
 
 import outputs from '../amplify_outputs.json'
 import cmsConfig from '@/cms.config'
@@ -22,9 +21,10 @@ import { createAdmin } from '@ampless/admin'
 export const admin = createAdmin({
   outputs,
   cmsConfig,
+  ampless: async () => (await import('./ampless')).ampless,
   locale: (cmsConfig as { locale?: string }).locale ?? 'en',
 })
 
 // Convenience: the server-side translation helper. Client components
-// should use `useT()` from `@/components/i18n-provider` instead.
+// should use `useT()` from `@ampless/admin/components` instead.
 export const t = admin.t

package/dist/templates/_shared/lib/ampless.ts

@@ -1,15 +1,9 @@
 // Wired-up ampless runtime instance. Single source of truth for the
 // public-side library — every route handler, dispatcher, and theme
-// component imports the `ampless` value from here.
-//
-// L1 architectural change (runtime extraction): public-side
-// behaviour now lives in `@ampless/runtime`. This module wires the
+// component imports the `ampless` value from here. Public-side
+// behaviour lives in `@ampless/runtime`; this module wires the
 // project's `amplify_outputs.json`, `cms.config`, and themes registry
 // into a single `Ampless` instance.
-//
-// Admin-side modules (post providers, kv-provider, auth, etc.) stay
-// in `templates/_shared/lib/` for now — they move into `@ampless/admin`
-// in L2.
 
 import outputs from '../amplify_outputs.json'
 import cmsConfig from '@/cms.config'

package/dist/templates/_shared/lib/amplify.ts

@@ -13,8 +13,3 @@ import { Amplify } from 'aws-amplify'
 import outputs from '../amplify_outputs.json'
 
 Amplify.configure(outputs, { ssr: true })
-
-export function configureAmplify() {
-  // module-level side effect above already ran; keep this as a no-op
-  // for callers that still import it as a function for back-compat.
-}

package/dist/templates/_shared/package.json

@@ -3,64 +3,72 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
   "scripts": {
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "sandbox": "ampx sandbox",
-    "sandbox:dev": "ampx sandbox --once && next dev",
-    "update-ampless": "npx create-ampless@alpha upgrade",
-    "copy-theme": "npx create-ampless@alpha copy-theme"
+    "sandbox": "ampx sandbox --once && next dev",
+    "update-ampless": "npx create-ampless@latest upgrade",
+    "copy-theme": "npx create-ampless@latest copy-theme"
   },
   "dependencies": {
-    "@aws-amplify/adapter-nextjs": "^1.6.0",
-    "@radix-ui/react-dialog": "^1.1.4",
-    "@radix-ui/react-label": "^2.1.1",
-    "@radix-ui/react-slot": "^1.1.1",
-    "@tiptap/extension-image": "^3.23.4",
-    "@tiptap/extension-link": "^3.23.4",
-    "@tiptap/pm": "^3.23.4",
-    "@tiptap/react": "^3.23.4",
-    "@tiptap/starter-kit": "^3.23.4",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.2",
-    "@ampless/plugin-rss": "^0.2.0-alpha.2",
-    "@ampless/plugin-seo": "^0.2.0-alpha.2",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.2",
-    "@ampless/admin": "^0.2.0-alpha.7",
-    "@ampless/backend": "^0.2.0-alpha.3",
-    "@ampless/runtime": "^0.2.0-alpha.4",
+    "@aws-amplify/adapter-nextjs": "^1.7.3",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "@radix-ui/react-label": "^2.1.8",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@tiptap/extension-image": "^3.23.6",
+    "@tiptap/extension-link": "^3.23.6",
+    "@tiptap/pm": "^3.23.6",
+    "@tiptap/react": "^3.23.6",
+    "@tiptap/starter-kit": "^3.23.6",
+    "@ampless/plugin-analytics-ga4": "^0.2.0-alpha.14",
+    "@ampless/plugin-cookie-consent": "^0.1.0-alpha.5",
+    "@ampless/plugin-gtm": "^0.2.0-alpha.13",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.30",
+    "@ampless/plugin-plausible": "^0.2.0-alpha.13",
+    "@ampless/plugin-reading-time": "^0.1.0-alpha.3",
+    "@ampless/plugin-rss": "^0.2.0-alpha.30",
+    "@ampless/plugin-schema-jsonld": "^0.1.1-alpha.9",
+    "@ampless/plugin-seo": "^0.2.0-alpha.30",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.31",
+    "@ampless/admin": "^1.0.0-alpha.59",
+    "@ampless/backend": "^1.0.0-alpha.49",
+    "@ampless/runtime": "^1.0.0-alpha.38",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^0.2.0-alpha.2",
-    "aws-amplify": "^6.10.0",
+    "ampless": "^1.0.0-alpha.30",
+    "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^1.16.0",
     "next": "^16.2.6",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "react-image-crop": "^11.0.7",
+    "react": "^19.2.6",
+    "react-dom": "^19.2.6",
+    "react-image-crop": "^11.0.10",
     "tailwind-merge": "^3.6.0"
   },
   "devDependencies": {
-    "@aws-amplify/backend": "^1.13.0",
-    "@aws-amplify/backend-cli": "^1.4.0",
-    "@aws-sdk/client-appsync": "^3.717.0",
-    "@aws-sdk/client-cognito-identity-provider": "^3.717.0",
-    "@aws-sdk/client-dynamodb": "^3.717.0",
-    "@aws-sdk/client-s3": "^3.1048.0",
-    "@aws-sdk/client-sqs": "^3.717.0",
-    "@aws-sdk/lib-dynamodb": "^3.717.0",
-    "@aws-sdk/util-dynamodb": "^3.717.0",
-    "@tailwindcss/postcss": "^4.0.0",
-    "@tailwindcss/typography": "^0.5.16",
-    "@types/aws-lambda": "^8.10.147",
-    "@types/node": "^22.10.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "aws-cdk-lib": "^2.174.0",
-    "postcss": "^8.4.0",
-    "tailwindcss": "^4.0.0",
+    "@aws-amplify/backend": "^1.22.0",
+    "@aws-amplify/backend-cli": "^1.8.2",
+    "@aws-sdk/client-appsync": "^3.1053.0",
+    "@aws-sdk/client-cognito-identity-provider": "^3.1053.0",
+    "@aws-sdk/client-dynamodb": "^3.1053.0",
+    "@aws-sdk/client-s3": "^3.1053.0",
+    "@aws-sdk/client-sqs": "^3.1053.0",
+    "@aws-sdk/lib-dynamodb": "^3.1053.0",
+    "@aws-sdk/util-dynamodb": "^3.996.2",
+    "@tailwindcss/postcss": "^4.3.0",
+    "@tailwindcss/typography": "^0.5.19",
+    "@types/aws-lambda": "^8.10.161",
+    "@types/node": "^22.19.19",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "aws-cdk-lib": "^2.257.0",
+    "postcss": "^8.5.15",
+    "tailwindcss": "^4.3.0",
     "typescript": "^6.0.3"
   }
 }

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

@@ -0,0 +1,139 @@
+> English: [README.md](./README.md)
+
+# サイトローカルプラグイン
+
+このディレクトリは **このサイト専用のプラグイン置き場**。別 npm
+パッケージとして publish したくない小さなカスタマイズを書く場所。
+
+`update-ampless` はこのディレクトリのファイルに一切触らない。ここに置いた
+ものは消えない、上書きされない。
+
+## いつ使うか
+
+詳しい判断軸は [プラグイン作者ガイド](../docs/plugin-author-guide.ja.md)
+§0「テーマとプラグインの境界線」に書いてある。プラグインが初めて、または
+「これはテーマ側に書くべきか、プラグインか」で迷ったら先にそちらを読む。
+ざっくり言うと:
+
+- **テーマ** = ページの見た目 (レイアウト / コンポーネント / CSS)
+- **プラグイン** = admin で編集する設定、バックグラウンド処理、
+  テーマを横断する注入、機械可読メタデータ、複数サイトで共有したい機能
+
+その中でも *ローカル* プラグイン (このディレクトリ) を使うのは、サイト
+固有の機能で:
+
+- プラグイン surface (`publicHead` / `publicBodyEnd` / `metadata` /
+  `eventHooks` 等) が必要
+- このサイト限定の用途 (一度きりのフッタークレジット、サイト特有の
+  JSON-LD 拡張、まだ汎用化したくない analytics スニペット等)
+- 別パッケージとして version 上げて publish するのは大袈裟
+
+複数サイトで使いたくなったら、独立 npm パッケージに切り出す:
+`npx create-ampless@latest plugin <name> --standalone` で publish 用の
+ディレクトリ一式が scaffold される。
+
+## クライアントサイドスクリプトに関する注意
+
+`publicHead` / `publicBodyEnd` で `inlineScript` を返す場合、その body の
+中で **可視 DOM 要素を挿入してはいけない**。React の hydration は DOM が
+virtual DOM と一致していることを前提にしていて、外部からの DOM 操作は
+reconciliation で消されてコンソールに hydration error が出る。
+安全なパターンは `window.dataLayer` 等のグローバル状態操作、自分で隔離
+コンテナを持つ外部ウィジェットローダ、そして SSR 専用 descriptor (`meta` /
+`link` / `noscript` / `iframe`)。詳細は [作者ガイド §6](../docs/plugin-author-guide.ja.md)
+「クライアント側 DOM 変更は禁止」セクションを参照。
+
+## 最小例
+
+`plugins/footer-credit/index.ts`:
+
+```typescript
+import { definePlugin, type AmplessPlugin } from 'ampless'
+
+export interface FooterCreditOptions {
+  instanceId?: string
+}
+
+export default function footerCreditPlugin(
+  options: FooterCreditOptions = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? 'footer-credit'
+  return definePlugin({
+    name: 'footer-credit',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
+    capabilities: ['publicBody', 'adminSettings'],
+    settings: {
+      public: [
+        {
+          type: 'text',
+          key: 'html',
+          label: { en: 'Snippet', ja: 'スニペット' },
+          default: '',
+        },
+      ],
+    },
+    publicBodyEnd(ctx) {
+      const html = (ctx.setting<string>('html') ?? '').trim()
+      if (!html) return []
+      return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
+    },
+  })
+}
+```
+
+`cms.config.ts` で register:
+
+```typescript
+import footerCreditPlugin from './plugins/footer-credit'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...既存 plugin...
+    footerCreditPlugin(),
+  ],
+})
+```
+
+これだけ。`next dev` 再起動 → `/admin/plugins` でスニペットを設定すれば、
+すべての公開ページの `</body>` 直前にレンダされる。
+
+## 宣言できる surface
+
+プラグインは `definePlugin({...})` で組み立てるただのオブジェクト。型は
+`node_modules/ampless/dist/plugin.d.ts` を見るか、[プラグイン作者ガイド][guide]
+の散文で。
+
+現状 active な capability:
+
+| capability | 用途 |
+|---|---|
+| `publicHead` | `<head>` に site-wide で挿入される descriptor |
+| `publicBody` | `</body>` 直前に site-wide で挿入される descriptor |
+| `metadata` | post ごとの Next.js Metadata 拡張 |
+| `eventHooks` | trusted/untrusted の背景ハンドラ (content lifecycle / media event 等) |
+| `adminSettings` | `settings.public[]` で宣言する admin 編集可能な設定 |
+| `writePublicAsset` | trusted plugin が `public/plugins/<instanceId>/...` に書き込み |
+| `schema` | post ごとの JSON-LD を `publicBodyForPost` 経由で (テーマ側で `ampless.publicBodyForPost(post)` を呼ぶ前提) |
+| `publicHtmlForPost` | post ごとの可視 HTML（読了時間バッジ等）を `publicHtmlForPost` 経由で（テーマ側で `ampless.publicHtmlForPost(post)` を呼ぶ前提） |
+
+**`publicHtmlForPost` を使うファーストパーティプラグイン:**
+- `@ampless/plugin-reading-time` — 投稿本文から読了時間を推定し、本文の前後に設定可能なバッジを注入します。
+
+[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+
+## TypeScript 設定
+
+`tsconfig.json` の `**/*.ts` include glob でこのディレクトリも自動的に
+カバーされている。`import x from './plugins/foo'` も
+`import x from '@/plugins/foo'` も追加設定なしで動く。
+
+## `update-ampless` はどうなるか
+
+何もしない。`plugins/` は upgrade ツールの protected list に入っているので、
+ここに置いたファイルは上書きも削除もされない。代償として **この README
+も更新されない** — プラグイン API に大きな変更があるときは、本家リポジトリの
+[プラグイン作者ガイド][guide] で最新版を確認すること。

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

@@ -0,0 +1,143 @@
+> 日本語版: [README.ja.md](./README.ja.md)
+
+# Site-local plugins
+
+This directory is for **plugins that belong only to this site** — small
+customizations you don't want to publish as a separate npm package.
+
+`update-ampless` never touches files in this directory, so anything you
+add here is yours to keep.
+
+## When to use a local plugin
+
+The longer answer lives in §0 ("Theme vs Plugin Boundary") of the
+[plugin author guide](../docs/plugin-author-guide.md) — read that
+first if you're new to plugins, or if you're unsure whether a feature
+belongs in a plugin or a theme. Short version:
+
+- **Theme** = what the page looks like (layout, components, CSS).
+- **Plugin** = admin-editable config, background processing,
+  theme-agnostic injection, machine-readable metadata, or anything
+  you want to share between sites.
+
+Reach for a *local* plugin (this directory) when you want a feature
+that:
+
+- needs a plugin surface (`publicHead` / `publicBodyEnd` /
+  `metadata` / `eventHooks` / etc.)
+- is specific to this site (a one-off footer credit, a custom JSON-LD
+  enrichment, an analytics snippet you're not yet ready to ship as a
+  reusable package)
+- you'd rather not version-bump or republish to iterate on
+
+When the plugin grows useful for more than one site, lift it into its
+own npm package — `npx create-ampless@latest plugin <name> --standalone`
+scaffolds the directory ready for `npm publish`.
+
+## A note on client-side scripts
+
+If your `publicHead` / `publicBodyEnd` returns an `inlineScript`, the
+script body **must not insert visible DOM elements** into the page.
+React's hydration assumes the DOM matches its virtual DOM, and any
+foreign nodes get wiped during reconciliation (plus a console error).
+Safe patterns are `window.dataLayer`-style global state, external
+widget loaders that manage their own isolated container, and
+SSR-only descriptors (`meta` / `link` / `noscript` / `iframe`).
+See the [author guide §6](../docs/plugin-author-guide.md) "Client-side
+DOM mutation: don't" section for the full story.
+
+## Minimal example
+
+`plugins/footer-credit/index.ts`:
+
+```typescript
+import { definePlugin, type AmplessPlugin } from 'ampless'
+
+export interface FooterCreditOptions {
+  instanceId?: string
+}
+
+export default function footerCreditPlugin(
+  options: FooterCreditOptions = {}
+): AmplessPlugin {
+  const instanceId = options.instanceId ?? 'footer-credit'
+  return definePlugin({
+    name: 'footer-credit',
+    instanceId,
+    apiVersion: 1,
+    trust_level: 'untrusted',
+    displayName: { en: 'Footer credit', ja: 'フッタークレジット' },
+    capabilities: ['publicBody', 'adminSettings'],
+    settings: {
+      public: [
+        {
+          type: 'text',
+          key: 'html',
+          label: { en: 'Snippet', ja: 'スニペット' },
+          default: '',
+        },
+      ],
+    },
+    publicBodyEnd(ctx) {
+      const html = (ctx.setting<string>('html') ?? '').trim()
+      if (!html) return []
+      return [{ type: 'noscript', id: `footer-credit-${instanceId}`, html }]
+    },
+  })
+}
+```
+
+Register it in `cms.config.ts`:
+
+```typescript
+import footerCreditPlugin from './plugins/footer-credit'
+
+export default defineConfig({
+  // ...
+  plugins: [
+    // ...existing plugins...
+    footerCreditPlugin(),
+  ],
+})
+```
+
+That's it. Restart `next dev` and visit `/admin/plugins` to configure
+the snippet, then any public page renders it before `</body>`.
+
+## What you can declare
+
+A plugin is just an object built with `definePlugin({...})`. The full
+shape lives in `node_modules/ampless/dist/plugin.d.ts` (or [the plugin
+author guide][guide] if you prefer prose).
+
+Capabilities currently active:
+
+| capability | purpose |
+|---|---|
+| `publicHead` | descriptors rendered in `<head>` site-wide |
+| `publicBody` | descriptors rendered before `</body>` site-wide |
+| `metadata` | per-post Next.js Metadata contributions |
+| `eventHooks` | trusted/untrusted background handlers (content lifecycle, media events, ...) |
+| `adminSettings` | admin-editable settings declared via `settings.public[]` |
+| `writePublicAsset` | trusted plugins can write namespaced files under `public/plugins/<instanceId>/...` |
+| `schema` | per-post JSON-LD via `publicBodyForPost` (theme template must call `ampless.publicBodyForPost(post)`) |
+| `publicHtmlForPost` | per-post visible HTML (e.g. reading-time badge, breadcrumbs) via `publicHtmlForPost` (theme template must call `ampless.publicHtmlForPost(post)`) |
+
+**First-party plugins that use `publicHtmlForPost`:**
+- `@ampless/plugin-reading-time` — estimates read time from the post body and injects a configurable badge before or after the content.
+
+[guide]: https://github.com/heavymoons/ampless/blob/main/packages/ampless/docs/plugin-author-guide.md
+
+## What about TypeScript?
+
+`tsconfig.json` already covers this directory through its `**/*.ts`
+include glob. Both `import x from './plugins/foo'` and
+`import x from '@/plugins/foo'` work; no extra setup needed.
+
+## What `update-ampless` does
+
+Nothing. `plugins/` is in the upgrade tool's protected list, so files
+here are never overwritten or deleted on upgrade. The flip side is that
+this README does not get refreshed either — when ampless ships
+significant changes to the plugin API, check the [plugin author guide][guide]
+in the canonical repo for the up-to-date version.

package/dist/templates/_shared/proxy.ts

@@ -1,18 +1,33 @@
 // Public-site proxy (Next.js 16 rename of "middleware"). Implementation
 // moved to `@ampless/runtime` (L1 extraction); this file wires the
-// project's `cms.config` into the factory and re-exports the default
-// matcher. The runtime export name is still `createAmplessMiddleware`
-// for API stability; only the user-side file convention (proxy.ts +
-// `export const proxy`) follows Next 16's rename.
+// project's `cms.config` + AppSync endpoint into the factory and
+// re-exports the default matcher. The runtime export name is still
+// `createAmplessMiddleware` for API stability; only the user-side
+// file convention (proxy.ts + `export const proxy`) follows Next 16's
+// rename.
 //
-// See `@ampless/runtime/middleware` for behaviour details: multi-site
-// host rewrite, `<slug>.html` → raw route, `?previewTheme=` header
-// forwarding, multi-site Cache-Control override.
+// See `@ampless/runtime/middleware` for behaviour details: AppSync
+// flag fetch + Lambda-memory LRU + `/raw/<slug>` rewrite for no_layout
+// HTML, `/static/<slug>(/<path>)` rewrite for static bundles, plus
+// per-post Cache-Control.
 
 import cmsConfig from './cms.config'
+import outputs from './amplify_outputs.json'
 import { createAmplessMiddleware } from '@ampless/runtime/middleware'
 
-export const proxy = createAmplessMiddleware({ cmsConfig })
+// `amplify_outputs.json` is generated by `npx ampx sandbox` /
+// `npx ampx pipeline-deploy` — the public API key has a 365-day TTL
+// and is rotated monthly by the api-key-renewer Lambda. See
+// RUNBOOK.md §"API key rotation".
+export const proxy = createAmplessMiddleware({
+  cmsConfig,
+  appsyncUrl: outputs.data.url,
+  // The public API key is always present in production deploys (the
+  // backend declares `apiKeyAuthorizationMode`). The non-null assertion
+  // is honest about the assumption; `ampx sandbox` will surface a clear
+  // error long before middleware ever runs if it ever isn't.
+  apiKey: outputs.data.api_key!,
+})
 
 // Next.js 16's Turbopack requires `config` to be a statically
 // analysable object literal — referencing an imported variable

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

@@ -0,0 +1,22 @@
+> English: [README.md](./README.md)
+> 
+# Blog テーマ
+
+shadcn/ui のデフォルトに準じたニュートラル系モノクロ。時系列の投稿フィード、個別投稿ページ、タグ別一覧を提供します。
+
+## カスタマイズ
+
+`/admin/sites/<siteId>/theme` で設定:
+
+- **プライマリカラー** — ボタン、リンク、強調表示の背景色
+- **アクセントカラー**
+- **フォーカスリング**
+- **破壊的操作** — 削除等の操作色
+- **角丸**
+- **本文フォント** — システムサンセリフ / セリフ (Georgia) / セリフ (Iowan) / 等幅
+- **トップに固定する記事のスラッグ** — 公開済み投稿を 1 件ホームの先頭に固定
+- **ロゴ画像 URL**
+- **ヘッダーナビ** — ラベル + URL のペア
+- **フッターリンク** — ラベル + URL のペア
+
+サイトごとのライト/ダークカラースキームは ampless の標準テーマトークン経由で反映されます。

package/dist/templates/blog/README.md

@@ -1,52 +1,22 @@
-# {{siteName}}
+> 日本語版: [README.ja.md](./README.ja.md)
+> 
+# Blog theme
 
-A blog site powered by [ampless](https://github.com/heavymoons/ampless).
+Neutral monochrome with shadcn/ui defaults. Chronological post feed, single-post page, and tag listing.
 
-## Getting Started
+## Customizing
 
-This project uses Amplify Gen 2 for the backend (Cognito, DynamoDB, S3) and Next.js for the frontend.
+In `/admin/sites/<siteId>/theme`:
 
-```bash
-# 1. Install dependencies
-npm install
+- **Primary color** — buttons, links, accent fills
+- **Accent color**
+- **Focus ring**
+- **Destructive** — color used for destructive actions
+- **Corner radius**
+- **Body font** — System sans / Serif (Georgia) / Serif (Iowan) / Monospace
+- **Featured post slug** — pin one published post to the top of the home page
+- **Logo image URL**
+- **Header navigation** — label + URL pairs
+- **Footer links** — label + URL pairs
 
-# 2. Start a personal AWS sandbox (terminal 1)
-#    Requires AWS credentials configured (`aws configure`).
-#    First run takes ~5–10 min to provision resources.
-#    Generates amplify_outputs.json when ready.
-npx ampx sandbox
-
-# 3. Start the Next.js dev server (terminal 2)
-npm run dev
-```
-
-Then open [http://localhost:3000](http://localhost:3000).
-
-## First admin user
-
-Open [http://localhost:3000/login](http://localhost:3000/login) and click **Create admin account**. The first user to register is automatically added to the `ampless-admin` Cognito group.
-
-After that, manage content from `/admin`:
-
-- `/admin` — dashboard
-- `/admin/posts` — list / create / edit posts (tiptap editor)
-- `/admin/media` — upload images to S3
-
-## Production deploy
-
-```bash
-git init && git add . && git commit -m "init"
-git remote add origin <your-repo>
-git push
-# Then connect the repo to AWS Amplify Hosting in the AWS console.
-```
-
-## Customize
-
-- `cms.config.ts` — site name, media delivery mode, plugins
-- `app/` — Next.js App Router pages (`(public)/` for the blog, `(admin)/` for the CMS)
-- `amplify/` — Amplify Gen 2 backend definitions (auth / data / storage)
-
-## Plugins
-
-Enabled: {{plugins}}
+Per-site light/dark color scheme is honored through the standard ampless theme tokens.

package/dist/templates/blog/manifest.ts

@@ -1,7 +1,7 @@
 import { defineTheme } from 'ampless'
 
 // Customizable fields for the Blog theme. Edit values in
-// `/admin/sites/<siteId>/theme` — they're stored in KvStore and applied
+// `/admin/sites/default/theme` — they're stored in KvStore and applied
 // at render time as CSS variables on every public page.
 //
 // Labels / descriptions / groups accept either a plain string (works in

package/dist/templates/blog/pages/feed.ts

@@ -1,14 +1,13 @@
-import { publicAssetUrl } from '@/lib/storage'
+import { ampless } from '@/lib/ampless'
 
 interface Ctx {
-  siteId: string
   request: Request
 }
 
 // /feed.xml proxy — plugin-rss regenerates the feed on content events
-// and writes it to `public/plugins/rss/{siteId}/feed.xml`.
-export async function blogFeedHandler({ siteId }: Ctx): Promise<Response> {
-  const url = publicAssetUrl(`public/plugins/rss/${siteId}/feed.xml`)
+// and writes it to `public/plugins/rss/feed.xml`.
+export async function blogFeedHandler(_ctx: Ctx): Promise<Response> {
+  const url = ampless.publicAssetUrl('public/plugins/rss/feed.xml')
   const upstream = await fetch(url, { cache: 'no-store' })
   if (!upstream.ok) {
     return new Response(