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

package/dist/templates/_shared/amplify/data/list-published-posts.js

@@ -1,23 +1,22 @@
 import { util } from '@aws-appsync/utils'
 
-// AppSync JS resolver: list a site's published posts, newest first.
+// AppSync JS resolver: list published posts, newest first.
 //
-// Reads the `bySiteIdStatus` GSI:
-//   PK = `${siteId}#${status}`   (denormalized field set by writers)
+// Reads the `byStatus` GSI:
+//   PK = status   (denormalized field set by writers)
 //   SK = publishedAt
-// so a single Query reads only one site's published partition. Drafts
-// never appear because the PK condition pins status='published'.
+// so a single Query reads only the `published` partition. Drafts never
+// appear because the PK condition pins status='published'.
 //
 // Date-range filtering (`from`, `to`) is pushed into the SK condition,
 // so DynamoDB only reads the matching range. `nextToken` paginates
 // without re-issuing a fresh query.
 export function request(ctx) {
-  const { siteId = 'default', from, to, limit, nextToken } = ctx.args
+  const { from, to, limit, nextToken } = ctx.args
 
-  const partition = `${siteId}#published`
-  let keyExpression = '#siteIdStatus = :siteIdStatus'
-  const expressionNames = { '#siteIdStatus': 'siteIdStatus' }
-  const expressionValueMap = { ':siteIdStatus': partition }
+  let keyExpression = '#status = :status'
+  const expressionNames = { '#status': 'status' }
+  const expressionValueMap = { ':status': 'published' }
 
   if (from && to) {
     keyExpression += ' AND #publishedAt BETWEEN :from AND :to'
@@ -36,7 +35,7 @@ export function request(ctx) {
 
   return {
     operation: 'Query',
-    index: 'bySiteIdStatus',
+    index: 'byStatus',
     query: {
       expression: keyExpression,
       expressionNames,

package/dist/templates/_shared/amplify/data/resource.custom.ts

@@ -14,12 +14,11 @@
 //     return {
 //       Bookmark: a
 //         .model({
-//           siteId: a.string().required(),
 //           bookmarkId: a.id().required(),
 //           url: a.string().required(),
 //           title: a.string(),
 //         })
-//         .identifier(['siteId', 'bookmarkId'])
+//         .identifier(['bookmarkId'])
 //         .authorization((allow: any) => [allow.groups(['ampless-admin', 'ampless-editor'])]),
 //     }
 //   }

package/dist/templates/_shared/amplify/data/resource.ts

@@ -1,8 +1,14 @@
 import { fileURLToPath } from 'node:url'
 import { dirname, resolve } from 'node:path'
 import { a, defineData, type ClientSchema } from '@aws-amplify/backend'
-import { amplessSchemaModels, defaultAuthorizationModes } from '@ampless/backend'
+import {
+  amplessSchemaModels,
+  amplessSchemaAuthorization,
+  defaultAuthorizationModes,
+} from '@ampless/backend'
 import { userAdmin } from '../functions/user-admin/resource.js'
+import { mcpHandler } from '../functions/mcp-handler/resource.js'
+import { pluginSecretHandler } from '../functions/plugin-secret-handler/resource.js'
 import { customSchemaModels } from './resource.custom.js'
 
 // AppSync's `a.handler.custom({ entry })` paths are resolved by CDK
@@ -15,8 +21,9 @@ import { customSchemaModels } from './resource.custom.js'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 
 // Ampless's built-in models (Post / Page / Media / Taxonomy / PostTag /
-// KvStore) plus the three public-read custom queries
-// (listPublishedPosts / getPublishedPost / listPostsByTag).
+// KvStore) plus the public-read custom queries
+// (listPublishedPosts / getPublishedPost / listPostsByTag /
+// getMediaBySrc).
 //
 // Add project-specific models in `amplify/data/resource.custom.ts` —
 // that file is never overwritten by `create-ampless upgrade`.
@@ -24,12 +31,26 @@ const resolverPaths = {
   listPublishedPosts: resolve(__dirname, 'list-published-posts.js'),
   getPublishedPost: resolve(__dirname, 'get-published-post.js'),
   listPostsByTag: resolve(__dirname, 'list-posts-by-tag.js'),
+  getMediaBySrc: resolve(__dirname, 'get-media-by-src.js'),
 }
 
-const schema = a.schema({
-  ...amplessSchemaModels(a, { resolverPaths, userAdminFunction: userAdmin }),
-  ...customSchemaModels(a),
-})
+const schema = a
+  .schema({
+    ...amplessSchemaModels(a, {
+      resolverPaths,
+      userAdminFunction: userAdmin,
+      pluginSecretHandlerFunction: pluginSecretHandler,
+    }),
+    ...customSchemaModels(a),
+  })
+  // Schema-level `.authorization()` is the only place resource auth is
+  // honoured in `@aws-amplify/data-schema` — model-level callbacks have
+  // `resource` destructured out of `allow`. The helper returns an empty
+  // array when no Lambda refs are supplied, so the schema stays
+  // unaffected if MCP is later removed.
+  .authorization((allow) => amplessSchemaAuthorization(allow, {
+    mcpHandlerFunction: mcpHandler,
+  }))
 
 export type Schema = ClientSchema<typeof schema>
 export const data = defineData({

package/dist/templates/_shared/amplify/events/dispatcher/resource.ts

@@ -3,6 +3,7 @@ import { defineFunction } from '@aws-amplify/backend'
 export const eventDispatcher = defineFunction({
   name: 'event-dispatcher',
   entry: './handler.ts',
+  runtime: 22,
   // Co-locate with the data stack — the function reads the Post table's
   // DynamoDB Stream, so being in the same stack avoids a CloudFormation
   // circular dependency between data, function, and auth.

package/dist/templates/_shared/amplify/events/processor-trusted/resource.ts

@@ -3,6 +3,7 @@ import { defineFunction } from '@aws-amplify/backend'
 export const processorTrusted = defineFunction({
   name: 'processor-trusted',
   entry: './handler.ts',
+  runtime: 22,
   // Co-locate with data — this Lambda reads the Post table to assemble
   // sitemap/RSS, so we keep the dependency intra-stack and avoid a
   // function → data → auth → function cycle.

package/dist/templates/_shared/amplify/events/processor-untrusted/resource.ts

@@ -3,7 +3,12 @@ import { defineFunction } from '@aws-amplify/backend'
 export const processorUntrusted = defineFunction({
   name: 'processor-untrusted',
   entry: './handler.ts',
+  runtime: 22,
   // Untrusted plugins do pure JS work; modest memory.
   memoryMB: 256,
   timeoutSeconds: 30,
+  // Pin to the data stack so all event-system Lambdas live together
+  // (dispatcher / processor-trusted are also `data`) and the function
+  // stack doesn't bridge data ↔ storage ↔ auth in a CFN cycle.
+  resourceGroupName: 'data',
 })

package/dist/templates/_shared/amplify/functions/api-key-renewer/resource.ts

@@ -3,6 +3,7 @@ import { defineFunction } from '@aws-amplify/backend'
 export const apiKeyRenewer = defineFunction({
   name: 'api-key-renewer',
   entry: './handler.ts',
+  runtime: 22,
   // Co-locate with the data stack — the function reads/updates the
   // AppSync API's API key, so being in the same stack avoids a CFN
   // dependency cycle between data, function, and auth.

package/dist/templates/_shared/amplify/functions/mcp-handler/handler.ts

@@ -0,0 +1 @@
+export { handler } from '@ampless/backend/functions/mcp-handler'

package/dist/templates/_shared/amplify/functions/mcp-handler/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+export const mcpHandler = defineFunction({
+  name: 'mcp-handler',
+  entry: './handler.ts',
+  runtime: 22,
+  // Co-locate with the data stack so the function has the KvStore
+  // table ARN available without cross-stack references at synth time.
+  resourceGroupName: 'data',
+  memoryMB: 512,
+  timeoutSeconds: 30,
+})

package/dist/templates/_shared/amplify/functions/plugin-secret-handler/handler.ts

@@ -0,0 +1,11 @@
+// Re-exported from @ampless/backend so the package can ship Lambda
+// handler updates via `npm update`. Amplify's esbuild follows this
+// import and bundles the real handler into the Lambda artifact.
+//
+// The handler validates Cognito group membership (admin/editor),
+// enforces a hard 10,000-char server cap on the value (field-level
+// `pattern` / `maxLength` come from the admin client and are NOT
+// re-enforced here), encrypts with the AES-256-GCM key from
+// `process.env.PLUGIN_SECRET_ENCRYPTION_KEY`, and dual-writes to
+// PluginSecret + PluginSecretIndicator.
+export { handler } from '@ampless/backend/functions/plugin-secret-handler'

package/dist/templates/_shared/amplify/functions/plugin-secret-handler/resource.ts

@@ -0,0 +1,12 @@
+import { defineFunction } from '@aws-amplify/backend'
+
+// `resourceGroupName: 'data'` co-locates this Lambda with the AppSync
+// stack. Required because `setPluginSecret` / `clearPluginSecret` are
+// wired as custom GraphQL resolvers (data → function), matching the
+// same circular-dependency avoidance used for user-admin.
+export const pluginSecretHandler = defineFunction({
+  name: 'plugin-secret-handler',
+  entry: './handler.ts',
+  runtime: 22,
+  resourceGroupName: 'data',
+})

package/dist/templates/_shared/amplify/functions/user-admin/resource.ts

@@ -1,6 +1,13 @@
 import { defineFunction } from '@aws-amplify/backend'
 
+// `resourceGroupName: 'data'` co-locates this Lambda with the AppSync
+// stack. Required because ampless wires userAdmin as a custom GraphQL
+// resolver (data → function) while api-key-renewer reads graphqlApi
+// (function → data); leaving userAdmin in the default `function` stack
+// turns those two arrows into a CloudFormation circular dependency.
 export const userAdmin = defineFunction({
   name: 'user-admin',
   entry: './handler.ts',
+  runtime: 22,
+  resourceGroupName: 'data',
 })

package/dist/templates/_shared/amplify/secrets/encryption-key.ts

@@ -0,0 +1,9 @@
+// Generated by `npx create-ampless setup-encryption-key`.
+// AES-256-GCM key (32 bytes, base64) for plugin secret storage.
+// Rotate via the same CLI command. Existing ciphertext becomes unreadable on rotation.
+//
+// IMPORTANT: This is a placeholder. Replace the value below with a real key
+// by running: npx create-ampless setup-encryption-key
+// (from your project root, after scaffolding).
+
+export const PLUGIN_SECRET_ENCRYPTION_KEY = ''

package/dist/templates/_shared/app/(admin)/admin/mcp-tokens/page.tsx

@@ -0,0 +1,5 @@
+import { admin } from '@/lib/admin'
+import { createMcpTokensPage } from '@ampless/admin/pages'
+
+export const dynamic = 'force-dynamic'
+export default createMcpTokensPage(admin)

package/dist/templates/_shared/app/(admin)/admin/plugins/page.tsx

@@ -0,0 +1,5 @@
+import { admin } from '@/lib/admin'
+import { createPluginsPage } from '@ampless/admin/pages'
+
+export const dynamic = 'force-dynamic'
+export default createPluginsPage(admin)

package/dist/templates/_shared/app/globals.css

@@ -1,4 +1,17 @@
 @import 'tailwindcss';
+
+/*
+ * Tailwind v4 doesn't scan `node_modules/` by default. The admin UI
+ * (`@ampless/admin`) and runtime UI bits (`@ampless/runtime`) ship
+ * compiled JS that uses Tailwind utility classes; without these
+ * explicit sources, every utility used only inside those packages
+ * (e.g. the admin sidebar's `flex`, `fixed`, `md:sticky`, ...) gets
+ * tree-shaken out of the final CSS, and the admin layout falls back
+ * to browser defaults — sidebar overlaps main content, etc.
+ */
+@source '../node_modules/@ampless/admin/dist';
+@source '../node_modules/@ampless/runtime/dist';
+
 @plugin '@tailwindcss/typography';
 /* DADS theme plugin from Digital Agency. Loaded globally so the
  * `templates/dads/` theme can use DADS-conformant color variables
@@ -36,6 +49,31 @@
   --radius-sm: calc(var(--radius) - 4px);
 }
 
+/*
+ * Color scheme:
+ *
+ * - `:root { color-scheme: light dark }` opts the page into both modes
+ *   and asks the browser to pick based on the visitor's
+ *   `prefers-color-scheme` setting.
+ * - `html[data-color-scheme='light' | 'dark']` lets the site admin pin
+ *   one mode regardless of system preference. The attribute is written
+ *   by `app/layout.tsx` from the per-site setting
+ *   (`theme.colorScheme`, default `'auto'` = no attribute).
+ * - Token values below (and in each theme's `tokens.css`) use the CSS
+ *   `light-dark(L, D)` function so a single declaration covers both
+ *   modes — the active `color-scheme` selects between L and D at
+ *   paint time.
+ */
+:root {
+  color-scheme: light dark;
+}
+html[data-color-scheme='light'] {
+  color-scheme: light;
+}
+html[data-color-scheme='dark'] {
+  color-scheme: dark;
+}
+
 /*
  * Default tokens — used as fallback when no theme's `[data-theme=...]`
  * selector matches (e.g. body has no data-theme attribute, or admin
@@ -45,49 +83,27 @@
  * `<body data-theme="...">` attribute makes the scoped selector match.
  */
 :root {
-  --background: oklch(1 0 0);
-  --foreground: oklch(0.145 0 0);
-  --card: oklch(1 0 0);
-  --card-foreground: oklch(0.145 0 0);
-  --primary: oklch(0.205 0 0);
-  --primary-foreground: oklch(0.985 0 0);
-  --secondary: oklch(0.97 0 0);
-  --secondary-foreground: oklch(0.205 0 0);
-  --muted: oklch(0.97 0 0);
-  --muted-foreground: oklch(0.556 0 0);
-  --accent: oklch(0.97 0 0);
-  --accent-foreground: oklch(0.205 0 0);
-  --destructive: oklch(0.577 0.245 27.325);
-  --destructive-foreground: oklch(0.985 0 0);
-  --border: oklch(0.922 0 0);
-  --input: oklch(0.922 0 0);
-  --ring: oklch(0.708 0 0);
+  --background: light-dark(oklch(1 0 0), oklch(0.145 0 0));
+  --foreground: light-dark(oklch(0.145 0 0), oklch(0.985 0 0));
+  --card: light-dark(oklch(1 0 0), oklch(0.145 0 0));
+  --card-foreground: light-dark(oklch(0.145 0 0), oklch(0.985 0 0));
+  --primary: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --primary-foreground: light-dark(oklch(0.985 0 0), oklch(0.205 0 0));
+  --secondary: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --secondary-foreground: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --muted: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --muted-foreground: light-dark(oklch(0.556 0 0), oklch(0.708 0 0));
+  --accent: light-dark(oklch(0.97 0 0), oklch(0.269 0 0));
+  --accent-foreground: light-dark(oklch(0.205 0 0), oklch(0.985 0 0));
+  --destructive: light-dark(oklch(0.577 0.245 27.325), oklch(0.396 0.141 25.723));
+  --destructive-foreground: light-dark(oklch(0.985 0 0), oklch(0.985 0 0));
+  --border: light-dark(oklch(0.922 0 0), oklch(0.269 0 0));
+  --input: light-dark(oklch(0.922 0 0), oklch(0.269 0 0));
+  --ring: light-dark(oklch(0.708 0 0), oklch(0.439 0 0));
   --radius: 0.5rem;
   --ampless-body-font: system-ui, -apple-system, sans-serif;
 }
 
-@media (prefers-color-scheme: dark) {
-  :root {
-    --background: oklch(0.145 0 0);
-    --foreground: oklch(0.985 0 0);
-    --card: oklch(0.145 0 0);
-    --card-foreground: oklch(0.985 0 0);
-    --primary: oklch(0.985 0 0);
-    --primary-foreground: oklch(0.205 0 0);
-    --secondary: oklch(0.269 0 0);
-    --secondary-foreground: oklch(0.985 0 0);
-    --muted: oklch(0.269 0 0);
-    --muted-foreground: oklch(0.708 0 0);
-    --accent: oklch(0.269 0 0);
-    --accent-foreground: oklch(0.985 0 0);
-    --destructive: oklch(0.396 0.141 25.723);
-    --destructive-foreground: oklch(0.985 0 0);
-    --border: oklch(0.269 0 0);
-    --input: oklch(0.269 0 0);
-    --ring: oklch(0.439 0 0);
-  }
-}
-
 body {
   font-family: var(--ampless-body-font, system-ui, -apple-system, sans-serif);
   background: var(--background);

package/dist/templates/_shared/app/layout.tsx

@@ -1,37 +1,67 @@
 import type { Metadata } from 'next'
 import { headers } from 'next/headers'
-import { DEFAULT_SITE_ID } from 'ampless'
+import { renderThemeCss, validateColorScheme } from '@ampless/runtime'
+import { getDictionary } from '@ampless/admin'
+import { I18nProvider } from '@ampless/admin/components'
+import { ampless } from '@/lib/ampless'
+import { admin } from '@/lib/admin'
 import { Providers } from './providers'
-import { siteMetadata } from '@/lib/seo'
-import { loadThemeConfig, renderThemeCss } from '@/lib/theme-config'
-import { getLocale, getDictionary } from '@/lib/i18n'
-import { I18nProvider } from '@/components/i18n-provider'
 import './globals.css'
 
-// Resolve metadata per site at request time. The middleware sets
-// `x-site-id` so we can pick the right merged settings; falls back to
-// DEFAULT_SITE_ID for admin / API routes that don't go through the
-// public middleware path.
 export async function generateMetadata(): Promise<Metadata> {
-  const h = await headers()
-  const siteId = h.get('x-site-id') ?? DEFAULT_SITE_ID
-  return siteMetadata(siteId)
+  return ampless.siteMetadata()
 }
 
 export default async function RootLayout({ children }: { children: React.ReactNode }) {
   const h = await headers()
-  const siteId = h.get('x-site-id') ?? DEFAULT_SITE_ID
-  const theme = await loadThemeConfig(siteId)
+  // Resolve theme, plugin head + body in parallel. `publicHead` and
+  // `publicBodyEnd` both fetch the S3 site-settings cache to bind
+  // `ctx.setting()`; Next.js fetch dedupe collapses that into a
+  // single round trip when the two run on the same request.
+  const [theme, pluginHead, pluginBodyEnd] = await Promise.all([
+    ampless.loadThemeConfig(),
+    ampless.publicHead(),
+    ampless.publicBodyEnd(),
+  ])
   const themeCss = renderThemeCss(theme.cssVars)
-  const locale = getLocale()
+  const locale = admin.locale
   const dict = getDictionary(locale)
+  // `data-color-scheme` pins the visitor to light or dark regardless
+  // of their system `prefers-color-scheme`. `'auto'` (the default)
+  // means we don't emit the attribute at all, so `globals.css`'s
+  // `:root { color-scheme: light dark }` lets the browser follow the
+  // system setting. Themes use `light-dark()` in their tokens.css so a
+  // single declaration covers both modes; the active `color-scheme`
+  // selects which value is rendered.
+  //
+  // The admin's theme-settings iframe preview passes the unsaved
+  // selection via `?previewColorScheme=<mode>`, which middleware
+  // forwards as `x-preview-color-scheme`. When that header is present
+  // it overrides the stored site setting so the preview updates live.
+  const previewHeader = h.get('x-preview-color-scheme')
+  const effectiveColorScheme = previewHeader
+    ? validateColorScheme(previewHeader)
+    : theme.colorScheme
+  const htmlProps: { lang: string; 'data-color-scheme'?: 'light' | 'dark' } = { lang: locale }
+  if (effectiveColorScheme !== 'auto') {
+    htmlProps['data-color-scheme'] = effectiveColorScheme
+  }
   return (
-    <html lang={locale}>
+    <html {...htmlProps}>
       <head>
         {/* Inline `:root` overrides come AFTER globals.css so they win
             against the static defaults. Validated values only — see
             ampless `validateThemeValue`. */}
         {themeCss && <style dangerouslySetInnerHTML={{ __html: themeCss }} />}
+        {/* Descriptor-based plugin head injection (Phase 1+2). Each
+            active plugin's `publicHead()` runs validation here; the
+            output is a `<Fragment>` of `<script>` / `<meta>` / `<link>`
+            / `<noscript>` elements. Placed after the theme style so
+            plugin-emitted overrides win on the rare collision.
+            Awaited via Promise.all above so admin-managed
+            `settings.public` values flow into ctx.setting() before
+            render. */}
+        {pluginHead}
       </head>
       {/* `data-theme` selects which theme's `tokens.css` block matches.
           The active theme is resolved from `theme.active` site setting,
@@ -42,6 +72,11 @@ export default async function RootLayout({ children }: { children: React.ReactNo
             {children}
           </I18nProvider>
         </Providers>
+        {/* Descriptor-based body-end injection (Phase 1+2). GTM
+            no-script iframe / chat widgets / analytics tail snippets
+            land here. Awaited above so the same ctx.setting()
+            snapshot powers both head + body. */}
+        {pluginBodyEnd}
       </body>
     </html>
   )

package/dist/templates/_shared/app/providers.tsx

@@ -2,8 +2,6 @@
 
 import { useEffect } from 'react'
 import '@/lib/amplify'
-import '@/lib/posts-provider'
-import '@/lib/kv-provider'
 
 export function Providers({ children }: { children: React.ReactNode }) {
   useEffect(() => {

package/dist/templates/_shared/app/raw/[slug]/route.ts

@@ -0,0 +1,10 @@
+import { ampless } from '@/lib/ampless'
+import { createRawRouteHandler } from '@ampless/runtime/routes'
+
+// Internal handler for `format: 'html'` posts with
+// `metadata.no_layout === true`. Reached via middleware rewrite from
+// `/<slug>` — never directly. The browser URL stays `/<slug>`; the
+// `/raw/` prefix is an implementation detail (folder names starting
+// with `_` are excluded by the App Router, hence the explicit `raw/`).
+export const dynamic = 'force-dynamic'
+export const GET = createRawRouteHandler(ampless)

package/dist/templates/_shared/app/static/[slug]/[[...path]]/route.ts

@@ -0,0 +1,14 @@
+import { ampless } from '@/lib/ampless'
+import { createStaticRouteHandler } from '@ampless/runtime/routes'
+
+// Internal handler for `format: 'static'` posts — the body is a
+// manifest pointing at a bundle of files in S3 at
+// `public/static/<slug>/`. Reached via middleware rewrite from
+// `/<slug>(/<path>)` — never directly. Each request becomes a short-
+// lived S3 presigned redirect (302) for the entrypoint or the
+// requested bundle file. The browser URL stays `/<slug>(/<path>)`;
+// the `/static/` prefix is an implementation detail (folder names
+// starting with `_` are excluded by the App Router, hence the
+// explicit `static/`).
+export const dynamic = 'force-dynamic'
+export const GET = createStaticRouteHandler(ampless)

package/dist/templates/_shared/cms.config.ts

@@ -1,6 +1,12 @@
 import { defineConfig } from 'ampless'
 import seoPlugin from '@ampless/plugin-seo'
 import rssPlugin from '@ampless/plugin-rss'
+// import schemaJsonLdPlugin from '@ampless/plugin-schema-jsonld'
+// import readingTimePlugin from '@ampless/plugin-reading-time'
+// import cookieConsentPlugin from '@ampless/plugin-cookie-consent'
+// import analyticsGa4Plugin from '@ampless/plugin-analytics-ga4'
+// import gtmPlugin from '@ampless/plugin-gtm'
+// import plausiblePlugin from '@ampless/plugin-plausible'
 // import webhookPlugin from '@ampless/plugin-webhook'
 // import ogImagePlugin, { loadFontFromUrl } from '@ampless/plugin-og-image'
 
@@ -27,29 +33,7 @@ export default defineConfig({
       losslessForPng: true,
     },
   },
-  // Multi-site config. Leave undefined for single-site operation; the
-  // runtime then serves every request as siteId='default'. To run
-  // multiple sites in one Amplify environment, declare two or more
-  // entries here:
-  //
-  //   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',
-  //     },
-  //   },
-  //
-  // In multi-site mode the middleware forces `Cache-Control: private,
-  // no-store` on public responses (Amplify Hosting's CloudFront cache
-  // key cannot disambiguate by Host). Single-site mode leaves caching
-  // to the default page directives.
-
+  // Date display format.
   // 'iso'    — YYYY-MM-DD (default; SSR-safe, locale-neutral)
   // 'long'   — "April 27, 2026" (en-US)
   // 'locale' — browser/server locale
@@ -90,6 +74,63 @@ export default defineConfig({
     //   ],
     // }),
     //
+    // Cookie consent banner. Installs `window.amplessConsent` so other
+    // plugins can gate themselves on user consent (see the Consent
+    // Convention in `docs/architecture/08-plugin-architecture.md`).
+    //
+    // IMPORTANT: cookieConsentPlugin() must come BEFORE any analytics
+    // plugin in this array — both run `afterInteractive` and the consent
+    // API must be installed before analytics scripts read it. (Analytics
+    // plugins also wait for `ampless:consent-ready`, so out-of-order
+    // registration still works, but in-order is faster.)
+    //
+    // Categories (analytics / marketing / etc.) are managed live from
+    // `/admin/plugins`. Banner text and button labels are also admin-editable.
+    //
+    // cookieConsentPlugin(),
+    //
+    // Reading-time badge. Estimates read time from the post body and injects
+    // a configurable label (default: "3 min read") before or after the post
+    // content. Supports English word count + CJK character count (÷ 2).
+    // Label template and position are editable from `/admin/plugins`.
+    //
+    // readingTimePlugin(),
+    //
+    // Google Analytics 4. Once registered here, the measurement ID can be
+    // edited from `/admin/plugins` without a redeploy — the constructor
+    // value below is just the initial default. Pass an empty string to
+    // disable the GA tag entirely. See packages/ampless/docs/plugin-author-guide.md.
+    //
+    // analyticsGa4Plugin({
+    //   measurementId: '', // 'G-XXXXXXXX' to enable
+    // }),
+    //
+    // Google Tag Manager. Like GA4, the container ID is editable from
+    // `/admin/plugins` after deploy. Tags fire via GTM's own trigger model.
+    //
+    // gtmPlugin({
+    //   containerId: '', // 'GTM-XXXXXXX' to enable
+    // }),
+    //
+    // Plausible Analytics (privacy-focused, typically no cookie consent
+    // required). `domain` matches the registered Plausible site.
+    // `scriptUrl` defaults to plausible.io; override for self-hosted.
+    //
+    // plausiblePlugin({
+    //   domain: '', // 'example.com' to enable
+    // }),
+    //
+    // JSON-LD structured data (Schema.org). Injects <script type="application/ld+json">
+    // into post pages for Article / BlogPosting markup. articleType, authorName and
+    // publisherName fall back to the site name when left empty.
+    //
+    // schemaJsonLdPlugin({
+    //   articleType: 'Article', // 'Article' | 'BlogPosting' | 'NewsArticle'
+    //   authorName: '', // empty falls back to site.name
+    //   publisherName: '', // empty falls back to site.name
+    //   publisherLogo: '', // optional absolute URL to publisher logo
+    // }),
+    //
     // Per-post OG images: SNS crawlers hit `/og/<slug>` and we render
     // a JSX card → PNG via Next.js `ImageResponse`. Requires at least one
     // font — ship a .ttf from your CDN or `/public` directory.

package/dist/templates/_shared/components/site-chrome/site-sidebar.tsx

@@ -1,10 +1,9 @@
 import Link from 'next/link'
 import { parseLinkList, isTagListUrl } from 'ampless'
-import { listPostsByTag } from '@/lib/posts-public'
+import { ampless } from '@/lib/ampless'
 
 interface Props {
   links: string | undefined
-  siteId: string
   className?: string
 }
 
@@ -19,7 +18,7 @@ interface Props {
  * paired with `force-dynamic` on the page so fresh content shows up
  * after publish events.
  */
-export async function SiteSidebar({ links, siteId, className }: Props) {
+export async function SiteSidebar({ links, className }: Props) {
   const items = parseLinkList(links)
   if (items.length === 0) return null
 
@@ -28,7 +27,7 @@ export async function SiteSidebar({ links, siteId, className }: Props) {
     items.map(async (item) => {
       const tagRef = isTagListUrl(item.url)
       if (!tagRef) return { type: 'link' as const, label: item.label, url: item.url }
-      const { items: posts } = await listPostsByTag(tagRef.tag, { siteId, limit: 50 })
+      const { items: posts } = await ampless.listPostsByTag(tagRef.tag, { limit: 50 })
       return {
         type: 'tagSection' as const,
         label: item.label,