create-ampless 1.0.0-alpha.99 → 1.0.0-beta.149

package/dist/templates/_shared/docs/plugin-author-guide.md

@@ -19,6 +19,8 @@ per-post body injection, the async event hooks, and admin-managed
 The design rationale is in [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md);
 this page is the hands-on companion.
 
+> **Positioning**: ampless is a customization-based CMS for engineers — plugins are **npm dependencies that the site engineer imports + configures in `cms.config.ts`**. The engineer audits each dep before installing, the way they would for any other npm library (Astro integration / Next.js plugin pattern). The trust framework described in this guide (`trust_level`, capabilities, IAM-scoped Lambdas) is implemented in v1 as **first-party plugin organization** — it decides which trust tier's Lambda runs each event hook, which IAM permissions each tier holds, and applies hard runtime gates only at narrowly-scoped points (most notably: `settings.secret` requires `trust_level: 'trusted'` because secret read needs the trusted Lambda's IAM permission). Most capability declarations are soft warnings + admin labels + future allow-list surfaces, not hard runtime gates. It is **not** designed as a marketplace-grade automatic sandbox that safely runs arbitrary untrusted third-party plugins. Marketplace + runtime sandbox is a v2.0+ exploration, not a v1 guarantee. See [`docs/architecture/08-plugin-architecture.md#trust-model-v1-scope`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope) for the full trust model.
+
 ---
 
 ## 0. Theme vs Plugin Boundary
@@ -75,7 +77,7 @@ same surfaces. The differences are packaging, distribution, and the
 opt-in install-time validation that the static `package.json#amplessPlugin`
 manifest enables (see §3 below).
 
-§14 below has a one-command scaffold (`npx create-ampless plugin <name>`)
+§14 below has a one-command scaffold (`npx create-ampless@beta plugin <name>`)
 that produces ready-to-use boilerplate for either of the latter two.
 
 An ampless plugin is a TypeScript module that returns an
@@ -121,10 +123,10 @@ The fastest way to create a plugin is to scaffold one:
 
 ```bash
 # Site-local (writes plugins/<name>/index.ts in the current ampless site)
-npx create-ampless@latest plugin my-thing
+npx create-ampless@beta plugin my-thing
 
 # Standalone npm package (writes ./<name>/ ready for `npm publish`)
-npx create-ampless@latest plugin @myscope/ampless-plugin-my-thing --standalone
+npx create-ampless@beta plugin @myscope/ampless-plugin-my-thing --standalone
 ```
 
 §14 covers the full flow. The rest of this section explains what the
@@ -200,7 +202,7 @@ That's it. Restart `npm run dev`, view source on any page, and the
 interface AmplessPlugin {
   name: string                      // package-like identifier, e.g. 'analytics-ga4'
   packageName?: string              // npm package name for install-time cross-check
-  apiVersion: 1                     // bump only when the contract changes
+  apiVersion: 1                     // the only valid value today
   trust_level: 'untrusted' | 'trusted' | 'privileged'
   instanceId?: string               // namespace for multi-instance installs
   displayName?: LocalizedString     // admin UI label
@@ -213,7 +215,11 @@ interface AmplessPlugin {
   publicBodyForPost?(post: Post, ctx): readonly PublicPostBodyDescriptor[]
   publicHtmlForPost?(post: Post, ctx): readonly PublicPostHtmlDescriptor[]
   ogImage?: OgImageConfig
-  settings?: { public?: readonly PluginSettingField[] }
+  settings?: {
+    public?: readonly PluginSettingField[]
+    secret?: readonly PluginSecretField[]
+    version?: number  // Phase 1 reservation; runtime ignores
+  }
 }
 ```
 
@@ -230,6 +236,23 @@ There's only one version today. Future breaking-change versions will
 bump this number; the runtime rejects unknown values rather than
 silently mis-binding.
 
+**Today only `apiVersion: 1` is valid.** The literal type accepts
+no other value, and the runtime hard-throws if `package.json#amplessPlugin.apiVersion`
+disagrees with what `definePlugin()` returns or exceeds the runtime's
+`SUPPORTED_API_VERSION`.
+
+All Phase 1 compat-break reservations (PRs #220, #222, #230, #232,
+#234) live within `apiVersion: 1` — declaring or not declaring them
+in your plugin does not affect the contract version.
+
+If a future `apiVersion: 2` is ever introduced, it will be announced
+through a changeset and a section update in this guide and the
+architecture doc. Until then, **publish your plugin with
+`apiVersion: 1` and treat it as the only valid value**. See the
+[apiVersion bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+section in the architecture doc for the full criteria around what
+would (and would not) trigger a v2 bump.
+
 ### `instanceId`
 
 Optional, defaults to `name`. When you ship a plugin that can run
@@ -337,15 +360,29 @@ not a runtime block.
 
 ## 4. Picking a `trust_level`
 
+The trust tiers are implemented in v1 as **first-party plugin organization** — they decide which IAM-scoped Lambda runs your event hooks and which permissions that Lambda holds. This is a code organization surface for engineer-audited npm deps, not a marketplace-grade automatic sandbox for arbitrary third-party untrusted plugins (see the [Positioning note](#writing-an-ampless-plugin) above and the [full trust model](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#trust-model-v1-scope)).
+
 Three tiers, picked by what the plugin needs to do **inside
 event hooks** (the sync surfaces — metadata, head, body — don't
 touch IAM):
 
-| Tier | IAM | Used by |
-|---|---|---|
-| `untrusted` | none (SQS consume only) | head/body descriptors, webhook delivery, content transforms |
-| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | RSS feed, sitemap, computed JSON indexes |
-| `privileged` | reserved | future: SES, secrets, private S3 |
+| Tier | IAM | What runs today | Used by |
+|---|---|---|---|
+| `untrusted` | none (SQS consume only) | sync surfaces + event hooks | head/body descriptors, webhook delivery, content transforms |
+| `trusted` | read posts, write `public/plugins/<instanceId ?? name>/...` | sync surfaces + event hooks | RSS feed, sitemap, computed JSON indexes |
+| `privileged` | reserved (v2.0+ exploration only) | sync surfaces only — event hooks are silently filtered out (warning logged) | future marketplace exploration: SES, secrets, private S3 |
+
+> **Warning for `privileged` plugin authors:** If you declare
+> `trust_level: 'privileged'` with event `hooks` today, **your hooks
+> WILL NOT EXECUTE**. Both event processors filter out privileged
+> plugins and emit a `console.warn` on every matching SQS event so
+> the drop is visible. Sync render surfaces (`publicHead`,
+> `publicBodyEnd`, `metadata`, `publicBodyForPost`, `publicHtmlForPost`)
+> work normally regardless of `trust_level` and emit no warning.
+> `privileged` Lambda provisioning is a v2.0+ exploration item — if
+> AmpLess later builds a plugin marketplace, that PR will automatically
+> pick up plugins that already declared `'privileged'`.
+> v1 first-party plugins should use `trust_level: 'trusted'` for capabilities that fit within the trusted Lambda's existing IAM scope: Post / KvStore / PluginSecret / PostTag read, `public/plugins/*` S3 write, and outbound HTTP (no AWS-IAM-authenticated calls). Requirements that fall outside that scope — SES, private S3 prefixes, calling AWS APIs that need an IAM principal of their own — are v2.0+ privileged-Lambda exploration material and don't fit into v1 `trusted`.
 
 Rule of thumb:
 
@@ -540,8 +577,12 @@ a console warning** and never rendered.
   index numbers no one can map back to a plugin.
 - **Duplicate `id`**: the last occurrence wins. A dev warning prints
   which key was duplicated.
-- **CSP nonce**: not propagated in Phase 1. The `nonce` attr is
-  declared in the type for forward-compat but discarded today.
+- **CSP nonce**: `inlineScript.nonce` and `script.nonce` are accepted
+  by the type (`'auto'` is the sentinel for future runtime stamping;
+  any string is an explicit literal). Phase 1 reservation: the runtime
+  accepts the field but does not propagate it to the rendered element.
+  See [CSP nonce (Phase 1 reservation)](#csp-nonce-phase-1-reservation)
+  below.
 - **Strategy**: `afterInteractive` adds `async` to external scripts.
   `lazyOnload` adds `defer`. Explicit `async` / `defer` always
   wins. `beforeInteractive` is not supported.
@@ -637,7 +678,7 @@ the slots:
 ```tsx
 {postBody}            {/* publicBodyForPost — JSON-LD */}
 {html.beforeContent}  {/* publicHtmlForPost — beforeContent slot */}
-<div className="prose" dangerouslySetInnerHTML={{ __html: renderBody(post) }} />
+<div className="prose">{await ampless.renderBody(post)}</div>
 {html.afterContent}   {/* publicHtmlForPost — afterContent slot */}
 ```
 
@@ -717,10 +758,731 @@ nothing races against hydration.
 
 ---
 
+## 6a. Scheduled posts and content events
+
+ampless supports **scheduled publishing**: a post with `status:
+'published'` and a future `publishedAt` is hidden from all public
+reads until that time. Once `publishedAt` arrives, the post becomes
+visible within the site's natural cache window (≤ ~5 minutes by
+default) — there is no exact-time trigger.
+
+### Events fire at save time, not at `publishedAt`
+
+`content.published` (and `content.updated`) are emitted via DynamoDB
+Streams **when the post is saved**, not when `publishedAt` arrives.
+This means a plugin that reacts to `content.published` will run
+**before the post is publicly visible** when the post is future-dated.
+
+For trusted plugins that rebuild public assets from the current post
+list (RSS, sitemap, JSON indexes), this is harmless — `listPublishedPosts()`
+already filters out future-dated posts, so the regenerated asset
+simply omits the scheduled post until it goes live.
+
+For **outbound-notification plugins** (webhook, push notification,
+social post) the early fire matters: the notification will be
+delivered to subscribers while the post URL still returns 404 or
+redirects to the home page.
+
+### Recommended pattern: gate on `publishedAt`
+
+Check `event.payload.publishedAt` before dispatching. Skip or defer
+when the post is future-dated:
+
+```ts
+hooks: {
+  async 'content.published'(event, ctx) {
+    const { publishedAt } = event.payload
+
+    // Skip notification for future-scheduled posts. The event fires
+    // at save time, but the post won't be public until publishedAt.
+    if (publishedAt && new Date(publishedAt) > new Date()) {
+      return
+    }
+
+    // Post is live now — safe to notify.
+    await sendWebhook(event.payload, ctx)
+  },
+}
+```
+
+The `publishedAt` value in the event payload is a UTC ISO 8601 string
+(`...Z`). Parse it with `new Date()` or your preferred date library
+before comparing against `Date.now()`.
+
+### Future work
+
+Aligning event emission with the scheduled time — so `content.published`
+fires at `publishedAt` rather than at save time — is a planned
+enhancement. It requires a scheduler component (EventBridge Scheduler
+or a DynamoDB TTL-triggered Lambda) and is not yet in scope for the
+current release. Until then, the pattern above is the recommended
+guard for notification plugins.
+
+For a full description of `publishedAt` semantics from the operator's
+perspective, see [`docs/scheduled-publishing.md`](https://github.com/heavymoons/ampless/blob/main/docs/scheduled-publishing.md).
+
+---
+
+### CSP nonce (Phase 1 reservation)
+
+Content Security Policy (CSP) is a near-mandatory requirement for production
+sites. To avoid breaking every plugin at once when nonce propagation lands,
+ampless reserves the API surface today (Phase 1 no-op) so plugins can opt in
+ahead of time.
+
+The 3-layer design:
+
+1. **`ctx.cspNonce?: string`** on `PluginPublicRenderContext` — type-reserved
+   on the interface; always `undefined` today. The runtime does not populate
+   this field yet; reads resolve to `undefined`. Middleware/SSR nonce threading
+   lands with the future CSP RFP.
+
+2. **`descriptor.nonce: 'auto' | string`** — accepted by the type on both
+   `inlineScript` and `script` descriptor variants. `'auto'` is the sentinel
+   for future runtime stamping; any other string is an explicit literal;
+   `undefined` emits no `nonce` attribute (default, backward-compatible).
+   Phase 1: the runtime accepts but does not propagate it. Declaring
+   `nonce: 'auto'` today is a forward-compatibility hint and does not change
+   the rendered HTML.
+
+3. **`'cspReady'` capability** — a name-only declarative badge. Declaring it
+   signals intent; future admin UI / sanity checks may surface it. No runtime
+   cross-check or enforcement exists in Phase 1.
+
+**How to be ready:**
+
+```ts
+// src/index.ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['publicHead', 'cspReady'],
+  publicHead: () => [{
+    type: 'inlineScript',
+    id: 'my-snippet',
+    body: '...',
+    nonce: 'auto',    // forward-compat hint; no effect in Phase 1
+  }],
+})
+```
+
+For standalone npm-published plugins, also update `package.json#amplessPlugin.capabilities`
+to match — the runtime cross-check warns on disagreement between the static
+manifest and the factory return value:
+
+```json
+{
+  "amplessPlugin": {
+    "apiVersion": 1,
+    "name": "my-plugin",
+    "trustLevel": "untrusted",
+    "capabilities": ["publicHead", "cspReady"]
+  }
+}
+```
+
+**What "cspReady" means:**
+
+- Site-level CSP compliance depends on middleware / response headers / other
+  inline content the runtime does not control.
+- Once the middleware-driven nonce threading PR lands, plugin-supplied scripts
+  that carry `nonce: 'auto'` will become candidates for runtime nonce stamping.
+- `'cspReady'` does **not** appear in `create-ampless plugin --capabilities`
+  output — it is a reserved capability and the scaffold excludes it to avoid
+  implying active enforcement.
+
+---
+
+## 6b. In-body content renderers: `contentFields` (Phase 7)
+
+The `contentFields` capability lets a plugin replace specific fragments
+of a post body — tiptap nodes or single-line markdown URLs — with a
+React subtree it controls. Used by the first-party `@ampless/plugin-youtube`
+and `@ampless/plugin-x-embed` packages to expand `https://youtu.be/...`
+URLs into iframe players and `https://x.com/<handle>/status/...` URLs
+into tweet blockquotes.
+
+### Shape
+
+```ts
+import { definePlugin, type ContentFieldRenderer } from 'ampless'
+
+definePlugin({
+  // ...
+  capabilities: ['contentFields'],
+  contentFields: [
+    {
+      kind: 'tiptap',
+      nodeType: 'amplessYoutube',
+      render: (node, ctx) => <YouTubeEmbed videoId={String(node.attrs?.videoId)} />,
+    },
+    {
+      kind: 'markdown-url',
+      pattern: /^https:\/\/youtu\.be\/([\w-]{11})$/,
+      render: ({ match }, ctx) => <YouTubeEmbed videoId={match[1]!} />,
+    },
+  ],
+})
+```
+
+Each renderer is called server-side by the runtime when it walks a post
+body during `ampless.renderBody(post)`. The return value must be a
+`ReactNode`. The plugin's `PluginPublicRenderContext` (`ctx`) is the
+same context handed to `publicHead` / `publicBodyEnd`, so `ctx.setting<T>(key)`
+works exactly the same way.
+
+### The two kinds
+
+- **`tiptap`** — keyed by `nodeType` (a string, e.g. `'amplessYoutube'`).
+  The runtime's tiptap walker calls the renderer whenever it encounters
+  a node whose `type` matches `nodeType`. Default switch-case rendering
+  is bypassed; the plugin owns the subtree.
+- **`markdown-url`** — keyed by an anchored `RegExp` (`^...$`). The
+  runtime tokenizes markdown with `marked.lexer` and, for any
+  `paragraph` token whose entire content is a single URL (autolink,
+  bare URL, or `[text](url)` markdown link), tests the URL against
+  each registered pattern. The first match wins; capture groups are
+  exposed via `match[1]`, `match[2]`, etc.
+
+### Naming and uniqueness
+
+- First-party plugins use the `ampless...` camelCase prefix
+  (`amplessYoutube`, `amplessTweet`) so the namespace stays clear of
+  community-contributed `nodeType`s.
+- The runtime rejects duplicate `nodeType` / `pattern.source` at
+  startup with a thrown error. The first plugin to register a given key
+  wins; the second one fails fast. Multi-instance v1 is not supported.
+
+### Markdown URL pattern rules
+
+- **Always anchor with `^...$`** so the pattern only matches paragraphs
+  whose entire content is a single URL. A pattern without anchors would
+  match URLs embedded mid-paragraph and break the surrounding text.
+- The runtime trims leading/trailing whitespace before matching, so
+  patterns don't need to account for `\s*` around the URL.
+- Inline `[caption](url)` markdown links are accepted when the link is
+  the paragraph's only token. `[caption with link](url)` mixed with
+  surrounding text is NOT matched (correct behaviour: the prose
+  belongs in the post, not a video embed).
+
+---
+
+## 6c. Page-level scripts: `publicPostScript` (Phase 7)
+
+The `publicPostScript` capability lets a plugin emit a `<script>` tag
+that any post on the page needs. The runtime dedupes by stable `id`
+so multiple embeds in one or several posts collapse to one script tag.
+Used by `@ampless/plugin-x-embed` to inject
+`https://platform.twitter.com/widgets.js` once per page that has any
+tweet embed.
+
+### Shape
+
+```ts
+definePlugin({
+  capabilities: ['contentFields', 'publicPostScript'],
+  publicPostScript(post, ctx) {
+    if (!hasTweetIn(post)) return []
+    return [
+      {
+        id: 'amplessTweet:widgets',
+        src: 'https://platform.twitter.com/widgets.js',
+        async: true,
+      },
+    ]
+  },
+})
+```
+
+### Theme integration
+
+Themes call `{await ampless.publicPostScriptsForPage(posts)}` after
+rendering each post body. First-party themes do this automatically in
+their post detail page and home page (when a featured post is shown):
+
+```tsx
+<div>{await ampless.renderBody(post)}</div>
+{await ampless.publicPostScriptsForPage([post])}
+```
+
+The runtime:
+
+1. Calls `publicPostScript(post, ctx)` for each plugin × post pair.
+2. Drops descriptors with empty/non-string `id`, with `src` that fails
+   the http(s) allowlist, or that aren't objects.
+3. Dedupes by `id` (first arrival wins).
+4. Emits a `<Fragment>` of `<script src={src} async defer />` elements.
+
+### CSP considerations
+
+The runtime does **not** enforce a host allowlist on `src`. CSP is the
+site engineer's responsibility — add the script host (e.g.
+`platform.twitter.com`) to `script-src` in `next.config.ts` /
+middleware. This is documented in each plugin's README.
+
+---
+
+## 6d. Admin editor extension wiring (Phase 7)
+
+Plugins that contribute tiptap Node extensions to the admin editor
+ship a separate client-side entry under the `./editor` subpath.
+`app/(admin)/admin/_editor-bootstrap.tsx` is **auto-generated** by
+`npm run update-ampless` — you should not edit it by hand.
+
+### For plugin authors
+
+Declare `editorExports` in `package.json#amplessPlugin`:
+
+```jsonc
+// packages/plugin-youtube/package.json
+"amplessPlugin": {
+  "apiVersion": 1,
+  "name": "youtube",
+  "trustLevel": "trusted",
+  "capabilities": ["contentFields"],
+  "editorExports": "./editor"   // ← subpath where the editor module lives
+}
+```
+
+Export `editorExtension` as a named symbol from that subpath:
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+export const editorExtension = AmplessYoutubeNode   // tiptap Node or Extension
+```
+
+The subpath must be declared in `package.json#exports` as well (the
+codegen validates this — a missing `exports` entry triggers a warning
+and the plugin is skipped):
+
+```jsonc
+"exports": {
+  ".":       { "import": "./dist/index.js", "types": "./dist/index.d.ts" },
+  "./editor": { "import": "./dist/editor.js", "types": "./dist/editor.d.ts" }
+}
+```
+
+### For plugin users (site engineers)
+
+1. `npm i @ampless/plugin-youtube@beta` — add the plugin as a dependency.
+2. Register it in `cms.config.ts` for the server-side renderer.
+3. `npm run update-ampless` — regenerates `_editor-bootstrap.tsx`
+   automatically from the installed plugin manifests.
+
+The generated file is committed to your repo and looks like:
+
+```tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — do not edit)
+'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit — your changes
+// will be overwritten on the next run.
+import { installAdminEditorExtensions } from '@ampless/admin/editor'
+import { editorExtension as __ampless_plugin_x_embed_editor } from '@ampless/plugin-x-embed/editor'
+import { editorExtension as __ampless_plugin_youtube_editor } from '@ampless/plugin-youtube/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    __ampless_plugin_x_embed_editor,
+    __ampless_plugin_youtube_editor,
+  ])
+  return <>{children}</>
+}
+```
+
+The file is then wired into the admin layout (already in the template — no
+extra work required):
+
+```tsx
+// templates/_shared/app/(admin)/admin/layout.tsx
+import { createAdminLayout } from '@ampless/admin/pages'
+import { EditorBootstrap } from './_editor-bootstrap'
+export default createAdminLayout(admin, { editorBootstrap: EditorBootstrap })
+```
+
+`installAdminEditorExtensions` is idempotent and runs at render time
+inside a client component. The admin's `<TiptapEditor>` spreads the
+registered list onto its built-in extensions on every render.
+
+The `_editor-bootstrap.tsx` generated by `update-ampless` wires three
+install calls — extensions, markdown adapters, and html adapters:
+
+```tsx
+// app/(admin)/admin/_editor-bootstrap.tsx  (AUTO-GENERATED — do not edit)
+'use client'
+// AUTO-GENERATED by `npm run update-ampless`. Do not edit ...
+import { installAdminEditorExtensions, installAdminTiptapNodeMarkdown, installAdminTiptapNodeHtml } from '@ampless/admin/editor'
+import * as __ampless_plugin_x_embed_editor from '@ampless/plugin-x-embed/editor'
+import * as __ampless_plugin_youtube_editor from '@ampless/plugin-youtube/editor'
+
+export function EditorBootstrap({ children }: { children: React.ReactNode }) {
+  installAdminEditorExtensions([
+    __ampless_plugin_x_embed_editor.editorExtension,
+    __ampless_plugin_youtube_editor.editorExtension,
+  ])
+  installAdminTiptapNodeMarkdown([
+    __ampless_plugin_x_embed_editor.tiptapNodeToMarkdown ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToMarkdown ?? {},
+  ])
+  installAdminTiptapNodeHtml([
+    __ampless_plugin_x_embed_editor.tiptapNodeToHtml ?? {},
+    __ampless_plugin_youtube_editor.tiptapNodeToHtml ?? {},
+  ])
+  return <>{children}</>
+}
+```
+
+### Lossless format-switch adapters (`tiptapNodeToMarkdown` + `tiptapNodeToHtml`)
+
+When the operator switches the post format in the admin UI (e.g. `tiptap →
+markdown` or `tiptap → html`), the admin must convert the body content. For
+standard prose nodes tiptap's built-in renderers handle this, but **atom
+nodes** (embed blocks like `amplessYoutube`) have no children — they fall
+through with empty output, silently dropping the embed.
+
+Two adapters fix both directions:
+
+| Adapter               | Direction                         | Output |
+| --------------------- | --------------------------------- | ------ |
+| `tiptapNodeToMarkdown`| `tiptap → markdown`               | bare URL line (e.g. `https://youtu.be/<id>`) |
+| `tiptapNodeToHtml`    | `tiptap → html`, `markdown → html`| canonical placeholder div |
+
+The three canonical body representations across format-switch are:
+
+| Format   | Canonical form |
+| -------- | -------------- |
+| tiptap   | `{ type: 'amplessYoutube', attrs: { videoId, start } }` Node |
+| markdown | bare `https://youtu.be/<id>` URL line |
+| html     | `<div data-ampless-youtube data-video-id="<id>" …>…</div>` |
+
+The placeholder div is the canonical HTML form for **admin format-switch
+interop only**: it is what `Node.renderHTML` emits, and what
+`Node.parseHTML`'s `tag: 'div[data-ampless-*]'` rule restores from, so
+that switching `tiptap ↔ markdown ↔ html` in the admin preserves embeds
+losslessly.
+
+**Public render of `format: 'html'` posts expands the placeholder when
+the plugin declares `htmlPlaceholder`.** All three public render paths
+reach the same `contentFields.tiptap` renderer: tiptap posts go through
+the React walker that consults the `contentFields.tiptap` registry
+(= real iframe for `amplessYoutube` Nodes); markdown posts go through the
+markdown walker that consults `contentFields.markdownUrl` (= real iframe
+for bare URL paragraphs); html posts go through the **public html walker**
+that consults `contentFields.htmlPlaceholder` (= real iframe for
+top-level `<div data-ampless-youtube …>` placeholders). The
+`tiptapNodeToHtml` adapter above only governs the **admin format-switch**
+interchange form — declaring `htmlPlaceholder` is what makes the public
+html walker expand that form on render. (See the dedicated
+`htmlPlaceholder` section below for the contract.) `publicHtmlForPost`
+still only emits `beforeContent` / `afterContent` slots and does not
+transform the body.
+
+A plugin that ships an embed node but does **not** declare
+`htmlPlaceholder` keeps the old behaviour: the placeholder div is shipped
+literally on public render of `format: 'html'` posts (the inner canonical
+URL link is still clickable, so it degrades gracefully). Save as `tiptap`
+or `markdown` to get the iframe in that case.
+
+#### Adapter contract
+
+Both adapters have the same signature:
+
+```ts
+(node: TiptapRenderNode) => string | null
+```
+
+Return a **string** (including empty string `''`) to use your output.
+Return **`null`** to fall through to the default switch (useful for nodes
+you don't handle or for degenerate inputs like a missing video id).
+
+```ts
+// packages/plugin-youtube/src/editor.tsx
+import type { TiptapNodeMarkdownAdapters, TiptapNodeHtmlAdapters } from 'ampless'
+
+export const tiptapNodeToMarkdown: TiptapNodeMarkdownAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fall through
+    return `https://youtu.be/${videoId}`
+  },
+}
+
+export const tiptapNodeToHtml: TiptapNodeHtmlAdapters = {
+  amplessYoutube: (node) => {
+    const videoId = String(node.attrs?.videoId ?? '').trim()
+    if (!videoId) return null   // fall through
+    const attrs = placeholderAttrs(node.attrs ?? {})
+    // Inner content is the canonical URL as a clickable link, not the
+    // editor's visual label `<span>YouTube: id</span>`. Public render of
+    // `format: 'html'` posts shows this content literally; an editor
+    // label would leak. The URL link gracefully degrades — viewers
+    // without iframe expansion still get a clickable link, and it
+    // mirrors the markdown canonical form. parseHTML reads the
+    // `data-video-id` attribute, so the inner content is irrelevant
+    // for round-trip.
+    const url = `https://youtu.be/${videoId}`
+    return `<div ${attrsToHtmlString(attrs)}><a href="${escapeAttr(url)}">${escapeAttr(url)}</a></div>`
+  },
+}
+```
+
+#### Wiring
+
+`update-ampless` reads the `tiptapNodeToMarkdown` and `tiptapNodeToHtml`
+named exports from each plugin's `./editor` module (via namespace import `*
+as`) and wires them into both installs automatically — **no hand-wiring
+required**. If your plugin does not export one of the maps, the `?? {}`
+fallback in the generated file is a no-op.
+
+#### `markdown → html` 2-hop
+
+The `markdown → html` direction reuses the `tiptapNodeToHtml` adapter via
+a 2-hop:
+
+1. `markdownToHtml(body)` — marked converts the markdown body to HTML. Bare
+   URL lines become `<p><a href="URL">URL</a></p>`.
+2. `generateJSON(html, extensions)` — tiptap parses the HTML. Your plugin's
+   `Node.parseHTML` `tag: 'p'` rule promotes the bare-URL paragraph to the
+   embed Node.
+3. `tiptapToHtml(doc, { nodeAdapters })` — the html adapter serialises the
+   embed Node to the placeholder div.
+
+This means your plugin only needs to export the `tiptap → html` adapter once;
+the `markdown → html` direction reuses it automatically through tiptap's parse
+rules. **No duplicate logic is needed.**
+
+#### Public html walker: `htmlPlaceholder`
+
+To make `format: 'html'` posts render placeholder divs as real embeds on
+the public page, add an **`htmlPlaceholder`** declaration to your existing
+`contentFields` `tiptap` entry. You write **no new renderer** — the walker
+calls the same `render(node, ctx)` your tiptap entry already uses, so all
+three formats (tiptap / markdown / html) reach one renderer with no
+divergence.
+
+```ts
+// packages/plugin-youtube/src/index.tsx
+contentFields: [
+  {
+    kind: 'tiptap',
+    nodeType: 'amplessYoutube',
+    render: (node) => {
+      const videoId = String(node.attrs?.videoId ?? '')
+      const startRaw = node.attrs?.start
+      const start =
+        typeof startRaw === 'number' && Number.isFinite(startRaw) ? startRaw : undefined
+      return <YouTubeEmbed videoId={videoId} start={start} />
+    },
+    htmlPlaceholder: {
+      // The marker attribute that flags a top-level placeholder div.
+      flagAttr: 'data-ampless-youtube',
+      // Convert the div's HTML attributes into the tiptap node `attrs`
+      // your `render` expects — WITH the right types. The walker is
+      // type-agnostic, so coerce here (e.g. data-start string → number).
+      attrsFromElement: (attribs) => {
+        const start = Number(attribs['data-start'])
+        return {
+          videoId: attribs['data-video-id'] ?? '',
+          start: Number.isFinite(start) ? start : undefined,
+        }
+      },
+    },
+  },
+  // …markdown-url entry unchanged…
+]
+```
+
+On public render of a `format: 'html'` post, the runtime parses the body
+server-side (`htmlparser2`), finds each **top-level** element carrying
+`flagAttr`, builds a `{ type: nodeType, attrs: attrsFromElement(attribs) }`
+node, and calls `render(node, ctx)`. Everything else passes through as the
+**original-string slices** (byte-for-byte; no DOM re-serialisation).
+
+Constraints worth knowing:
+
+- **Top-level only.** Placeholder divs nested inside `<blockquote>`,
+  `<li>`, etc. stay literal — consistent with the editor's body-level-only
+  `parseHTML` fallback. Only depth-0 elements expand.
+- **`flagAttr` is matched case-insensitively.** htmlparser2 lowercases
+  HTML attribute names while parsing, and the runtime lowercases your
+  `flagAttr` at registration, so `<div DATA-AMPLESS-YOUTUBE …>` and
+  `<div data-ampless-youtube …>` both expand. `flagAttr` can be any
+  attribute name — a site-local plugin may use `data-my-embed`; there is
+  no fixed `data-ampless` prefix requirement.
+- **Graceful degradation.** If `attrsFromElement` or `render` throws, the
+  runtime logs a `console.warn` and falls back to the **raw placeholder
+  slice** (the inner canonical URL link stays clickable) rather than
+  dropping the engineer-authored content.
+- **Page-level scripts.** If your embed needs a third-party script (e.g.
+  x.com's `widgets.js`), your `publicPostScript` / detection helper must
+  also recognise the placeholder form. `plugin-x-embed`'s `hasTweetIn`
+  matches both `twitter-tweet` and `data-ampless-tweet` in `format: 'html'`
+  bodies so widgets.js is injected for the expanded blockquote to hydrate.
+
+**Wrapper-boundary change.** A placeholder-free `format: 'html'` post is
+emitted as a single wrapper `<div>` (the fast path — markup-identical to
+the previous raw passthrough). A post **with** placeholders becomes
+**multiple wrapper divs interleaved with the React embed siblings**: the
+bytes inside each raw chunk are preserved exactly, but the wrapper
+boundaries shift. Direct-child / adjacent-sibling CSS selectors that
+assumed one wrapper around the whole body will not match the same way.
+This is the accepted trade-off for expanding embeds in-place.
+
+### Markdown to tiptap restoration
+
+If an editor Node serializes to markdown as a bare URL line, the reverse
+direction must be handled by `Node.parseHTML()`, not by paste rules. The
+admin's `markdown → tiptap` format switch first converts markdown to HTML;
+GFM autolinks emit a bare URL line as
+`<p><a href="https://...">https://...</a></p>`, then tiptap parses that
+HTML into a document. Paste rules only run for user paste / typing events,
+so they do not fire on this HTML parse path.
+
+Embed-style Nodes should add a high-priority parse rule for the paragraph
+shape above, and may also add an `a[href]` rule for other HTML-to-tiptap
+paths. The paragraph rule should only match when the paragraph contains a
+single link whose text equals its `href`; that lets the parser replace the
+whole paragraph with the block embed Node instead of leaving an empty
+paragraph before the embed. `getAttrs` should validate the URL and return
+`false` for non-matching links so the normal Link mark remains in place.
+
+### Active source and full disable
+
+**The active source for editor wiring is `package.json#dependencies`**
+(= `node_modules`), not `cms.config.ts`. This means:
+
+- Removing a plugin from `cms.config.ts` but keeping it in
+  `package.json` leaves the editor paste rule active. The editor can
+  still insert the node type into the tiptap document, but the public
+  renderer won't render it (inconsistent state — avoid).
+- To fully disable a plugin's editor extension: remove it from
+  `cms.config.ts` **and** run `npm uninstall @ampless/plugin-...`,
+  then `npm run update-ampless` to regenerate the bootstrap file.
+
+### Editor preview pipeline
+
+The admin's edit / new post forms render the preview pane in an
+`<iframe sandbox="allow-scripts allow-same-origin">` whose `srcDoc` is the HTML returned
+by the template's preview Route Handler. The template scaffold ships
+the handler at `app/(admin)/admin/preview/route.tsx`:
+
+```tsx
+// templates/_shared/app/(admin)/admin/preview/route.tsx
+import type { Post } from 'ampless'
+import { admin } from '@/lib/admin'
+
+export async function POST(req: Request): Promise<Response> {
+  const session = await admin.getServerSession()
+  if (!admin.isEditor(session)) {
+    return new Response('Forbidden', { status: 403 })
+  }
+  let draft: Post
+  try {
+    draft = (await req.json()) as Post
+  } catch {
+    return new Response('Bad Request', { status: 400 })
+  }
+  const ampless = await admin.getAmpless()
+  const node = (
+    <>
+      {await ampless.renderBody(draft)}
+      {await ampless.publicPostScriptsForPage([draft])}
+    </>
+  )
+  // Dynamic import: see "Why a Route Handler" below.
+  const { renderToStaticMarkup } = await import('react-dom/server')
+  return new Response(renderToStaticMarkup(node), {
+    headers: {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'no-store',
+    },
+  })
+}
+```
+
+`<PostForm>` / `<PostHistoryPanel>` POST the draft to `/admin/preview`
+out of the box — no extra wiring at the call site:
+
+```tsx
+// templates/_shared/app/(admin)/admin/posts/[postId]/page.tsx
+import { admin } from '@/lib/admin'
+import { createEditPostPage } from '@ampless/admin/pages'
+
+export default createEditPostPage(admin)
+```
+
+If the admin is mounted at a non-default path (Next.js `basePath` or
+a custom prefix), override the endpoint via the page factory's
+`previewEndpoint` option:
+
+```tsx
+export default createEditPostPage(admin, { previewEndpoint: '/cms/admin/preview' })
+```
+
+Why a Route Handler rather than a Server Action: putting
+`react-dom/server`-driven rendering inside a `'use server'` module
+makes Next.js 15+ refuse to compile the edit-post page, because the
+build traces the import graph from Client Components through Server
+Action modules and any reach to `react-dom/server` along that path
+trips the "You're importing a component that imports
+react-dom/server" check. A Route Handler decouples the rendering
+from that graph entirely — `<PostForm>` fetches a plain HTTP
+endpoint and the bundler never walks from the form into here. The
+handler's explicit `admin.isEditor()` check also defends against
+accidental exposure if the `(admin)` route-group gate is ever
+misconfigured. The `react-dom/server` import itself is dynamic
+because Next.js 16's Turbopack flags any top-level static import of
+`react-dom/server` reached from the app router build, Route Handlers
+included; deferring it to request time keeps the module outside the
+build-time import-graph walker while still loading it from the same
+Node.js subpath at runtime.
+
+**Preview iframe sandbox — v1 trust boundary expansion:** The iframe uses
+`sandbox="allow-scripts allow-same-origin"`. With `srcDoc`, this gives
+the iframe the admin's origin, which 3rd-party embed widgets (YouTube SDK,
+x.com `widgets.js`) require — they refuse to initialise in an opaque-origin
+(`allow-scripts`-only) iframe because they need access to non-HttpOnly
+storage / cache and real-origin requests. Same-origin also gives the
+preview script access to the admin's auth state / non-HttpOnly storage /
+DOM and lets it issue authenticated same-origin XHR / fetch.
+
+This is an explicit v1 design decision, not a no-op sandbox relax:
+**ampless v1 treats admin preview content / plugin script as trusted**.
+The engineer audits plugins before npm-installing them (customization-based
+CMS model), and body content is produced by trusted editors of this site.
+`<PostHistoryPanel>` can also surface a past revision authored by a
+different editor (revision author ≠ preview viewer) — v1 explicitly puts
+both inside the trust ring. The safer alternative — separate-origin preview
+route + CSP / COEP / COOP — is parked for v2.0+ if/when a real plugin
+marketplace lands.
+
+---
+
 ## 7. Async event hooks
 
 `hooks` runs inside the trust_level-matched processor Lambda when an
-event arrives via SQS. The runtime context (`ctx`) carries:
+event arrives via SQS.
+
+### Return value reservation
+
+`PluginEventHandler` returns `Promise<void | PluginHookResult>`. The
+runtime currently ignores the return value entirely — existing
+plugins returning `Promise<void>` keep working without migration.
+`PluginHookResult` is reserved for a future directive (likely first:
+`metrics?: Record<string, number>` for observability emission);
+declaring it today is a forward-compatibility hint. Note: rewrite
+or cancel directives are NOT enabled by this widening alone — they
+require additional `before:*` event support and payload extensions
+in separate PRs.
+
+`PluginHookResult` carries a private `__amplessPluginHookResult`
+marker so that the union does not silently accept unrelated promise
+types (`Promise<string>` / `Promise<number>` etc.) — plugin authors
+do not need to set this field.
+
+### Runtime context
+
+The runtime context (`ctx`) carries:
 
 ```ts
 interface PluginRuntimeContext {
@@ -924,71 +1686,82 @@ etc. — but completely wrong for a webhook signing secret.
 
 - Stored in the `PluginSecret` DynamoDB table (separate from KvStore).
   Admin/editor Cognito users have **no direct AppSync access** to this
-  table — all writes go through the `setPluginSecret` mutation backed
-  by the `plugin-secret-handler` Lambda.
+  table — all writes go through the `setPluginSecret` mutation, which
+  is backed by the `plugin-secret-handler` Lambda.
 - Values are **AES-256-GCM encrypted** before reaching DynamoDB.
   The admin browser sends the plaintext to the Lambda via AppSync
-  (TLS); the Lambda validates, reads the 32-byte encryption key from
-  `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` (injected by CDK from
-  `amplify/secrets/encryption-key.ts`), and writes only the ciphertext.
-  The plaintext never rests in DynamoDB and never flows back to the browser.
+  (TLS in transit); the Lambda validates it, reads the 32-byte
+  encryption key from `process.env.PLUGIN_SECRET_ENCRYPTION_KEY`
+  (injected by CDK from `amplify/secrets/encryption-key.ts`), encrypts
+  the value, and writes only the ciphertext to DDB. The plaintext
+  never rests in DynamoDB and never flows back to the browser.
 - **Threat model (Phase 6a v2.2)**:
 
   | Threat | Status |
   |---|---|
   | AWS Console operator browsing PluginSecret table | ✓ defeated — ciphertext only, no key in DDB |
-  | Source repo / deploy artifact access | ⚠ NOT defeated — key is in `amplify/secrets/encryption-key.ts`. Private repo + restricted artifact access expected. |
+  | Source repo / deploy artifact access | ⚠ NOT defeated — key is in `amplify/secrets/encryption-key.ts`. For public repos, keep the key out of source control (for example with `npx create-ampless@beta setup-encryption-key --gitignore`) and restrict deploy artifact access. |
   | Malicious trusted plugin in same Lambda | ✗ NOT defeated — `process.env.PLUGIN_SECRET_ENCRYPTION_KEY` reachable from plugin code. True isolation = per-plugin Lambda (privileged tier, roadmap). |
   | S3 mirror leak | ✓ defeated — PluginSecret table never mirrored. |
 
 - The trusted-processor Lambda decrypts with `node:crypto` on read.
-  `ctx.secret<T>(key)` returns the plaintext string, never ciphertext.
+  `ctx.secret<T>(key)` returns the plaintext string, never the
+  ciphertext.
 - Never queried by the site-settings mirror path.
 - Never passed to any public-render surface
-  (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
-  `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
 - **Field-manifest validation scope**: the admin client validates
   `pattern` / `maxLength` / `required` for UX feedback, but the
-  Lambda only enforces a generic 10,000-character hard cap +
-  safe-character sanitizer. An admin/editor calling the AppSync
-  mutation directly can bypass field-level constraints — by design,
-  since admin/editor are trusted operators authorised to set
-  secrets. The manifest checks are UX guidance, not a security
-  boundary.
-
-### Requirements
-
-`settings.secret` requires:
-
-1. `trust_level: 'trusted'` — untrusted Lambdas have no DDB read
-   access to the PluginSecret table. `definePlugin()` throws if you
-   declare `settings.secret` with any other trust level.
-2. `'secretSettings'` in `capabilities` — required so admin UI and
-   future allow-lists can gate the capability. Omitting it produces
-   a console warning (same pattern as `'schema'` vs `publicBodyForPost`).
+  Lambda only enforces a generic 10,000-character hard cap + safe-
+  character sanitizer. An admin/editor calling the AppSync mutation
+  directly can bypass field-level constraints — by design, since
+  admin/editor are trusted operators authorised to set secrets.
+  The manifest checks are UX guidance, not a security boundary.
+  (`publicHead`, `publicBodyEnd`, `publicBodyForPost`,
+  `publicHtmlForPost`) — those surfaces only see `ctx.setting()`.
+
+### Requirements and `definePlugin()` behaviour
+
+`settings.secret` has four observable behaviours at `definePlugin()` time (this is the v1 first-party organization hard gate for secret access; see [plugin.ts:1004-1019](https://github.com/heavymoons/ampless/blob/main/packages/ampless/src/plugin.ts#L1004-L1019)):
+
+1. **`settings.secret` non-empty + `trust_level !== 'trusted'`** → `definePlugin()` **throws**. Untrusted and privileged Lambdas have no IAM read access to the `PluginSecret` table; the trusted Lambda's IAM permission is required.
+2. **`settings.secret` non-empty + `capabilities` declared + `'secretSettings'` missing from `capabilities`** → **soft mismatch warning**. Matches the existing capability-mismatch pattern for `'schema'` / `'publicHtmlForPost'`.
+3. **`settings.secret` non-empty + `capabilities` undefined** (legacy plugin without a `capabilities` array) → **no warning**. The mismatch check is skipped when `capabilities` is `undefined`, for backward compatibility.
+4. **`capabilities: ['secretSettings']` declared with no `settings.secret` field** → **no-op**. Neither warning nor throw.
+
+To use `settings.secret`, you also need:
+1. `trust_level: 'trusted'` (requirement #1 above; `definePlugin()` throws otherwise).
+2. `'secretSettings'` in `capabilities` (omitting it when `capabilities` is defined produces a console warning).
 3. **One-time key setup** — run from your project root:
    ```sh
-   npx create-ampless setup-encryption-key
+   npx create-ampless@beta setup-encryption-key
    ```
-   Generates a cryptographically random 32-byte key and writes it to
-   `amplify/secrets/encryption-key.ts`. No AWS credentials required.
-   Then import it in `amplify/backend.ts` and pass it to
+   This generates a cryptographically random 32-byte key and writes
+   it to `amplify/secrets/encryption-key.ts`. No AWS credentials
+   required — this is a local file operation only.
+
+   Then import the constant in `amplify/backend.ts` and pass it to
    `defineAmplessBackend({ pluginSecretEncryptionKey })`. Redeploy (or
-   restart the sandbox) to inject the key into Lambda env vars.
-   For public repos, add `--gitignore` to exclude from version control.
+   restart the sandbox) to inject the key into the Lambda env vars.
+
+   For public repos, pass `--gitignore` to exclude the key file from
+   version control and distribute the key separately.
 
 ### Dual-write integrity
 
-The `setPluginSecret` and `clearPluginSecret` operations each write to
-**two DynamoDB tables** in sequence. If the second write fails, the
-tables are left in a predictable state:
+The `setPluginSecret` and `clearPluginSecret` operations each write
+to **two DynamoDB tables** in sequence: `PluginSecret` (ciphertext)
+and `PluginSecretIndicator` (existence timestamp). If the second
+write fails, the tables are left in a predictable, documented state:
 
-| Failure | `PluginSecret` | `PluginSecretIndicator` | `ctx.secret()` | `hasPluginSecret()` |
+| Failure point | `PluginSecret` | `PluginSecretIndicator` | `ctx.secret()` | `hasPluginSecret()` |
 |---|---|---|---|---|
 | **set**: indicator PutItem fails | ciphertext present | absent | returns plaintext ✓ | `false` (UI: "not saved") |
-| **clear**: indicator DeleteItem fails | absent | stale | `undefined` ✓ | `true` (UI: "saved") |
+| **clear**: indicator DeleteItem fails | absent | stale (old timestamp) | `undefined` ✓ | `true` (UI: "saved") |
 
-The clear-path failure is the "safe side": the secret stops firing.
+The clear-path failure is the "safe side": the secret stops firing even
+though the UI briefly shows it as saved. The set-path failure is a minor
+UI inaccuracy: the secret is functional but the existence indicator is
+absent until a retry succeeds.
 
 ### Declaring secret fields
 
@@ -1020,9 +1793,16 @@ export default function webhookPlugin(opts?: { signingSecret?: string }) {
     },
     hooks: {
       async 'content.published'(event, ctx) {
+        // ctx.secret() reads from PluginSecret DDB table.
+        // Returns undefined when no value has been saved by admin yet.
         const storedSecret = await ctx.secret<string>('signingSecret')
+
+        // Closure-private fallback: use the constructor argument when
+        // the admin has not saved a value yet. This preserves backward
+        // compatibility with sites that pass the secret at install time.
         const secret = storedSecret ?? constructorSecret
-        if (!secret) return
+        if (!secret) return // no secret → skip signing
+
         // ... use secret to sign and POST
       },
     },
@@ -1034,25 +1814,306 @@ export default function webhookPlugin(opts?: { signingSecret?: string }) {
 
 The type `PluginSecretField` is defined as `Omit<PluginTextField,
 'default'> | Omit<PluginTextareaField, 'default'>` — the `default`
-property is **removed at the type level**. Use a closure-private
-fallback variable instead; never put credentials in the manifest.
+property is **removed at the type level** and TypeScript will error
+if you try to add one.
+
+This is intentional: `default` values propagate into admin UI form
+props (visible in the browser), static manifests cross-checked by
+the runtime, and JS bundles. For a credential, these are all leak
+paths.
+
+If you have a fallback value (e.g. the constructor argument), keep
+it as a **closure-private variable** inside the plugin factory
+function — never in the manifest:
+
+```ts
+// ✓ correct — closure-private, never in the manifest
+const constructorSecret = opts?.signingSecret
+
+// ✗ wrong — TypeScript error, would also leak to browser
+settings: {
+  secret: [{
+    type: 'text',
+    key: 'signingSecret',
+    label: 'Secret',
+    default: opts?.signingSecret, // ← TS compile error
+  }],
+}
+```
 
 ### Reading secrets: `ctx.secret<T>(key)`
 
-`ctx.secret<T>(key)` is only available in trusted hook handlers.
-Returns `undefined` when no value has been saved by admin. Returns
-the **decrypted plaintext** — never the ciphertext blob.
-Results are per-invocation cached (plaintext, not ciphertext).
-The encryption key is decoded from the Lambda env var at cold-start
-(no extra DDB fetch).
-Cache keys are namespaced by `${instanceId ?? name}:${fieldKey}`.
+`ctx.secret<T>(key)` is only available in trusted hook handlers
+(injected by `processor-trusted.ts`). The signature is:
+
+```ts
+ctx.secret<T = string>(key: string): Promise<T | undefined>
+```
+
+- Returns `undefined` when no value has been saved by admin yet.
+- The generic `T` is a convenience cast (same as `ctx.setting<T>()`).
+  Values are always stored as strings; `T` defaults to `string`.
+- Results are per-invocation cached. Calling `ctx.secret('key')`
+  twice in the same hook batch costs one DDB round-trip (and one
+  decrypt). The encryption key is decoded from the Lambda env var
+  at cold-start (no extra DDB fetch).
+- Cache keys are namespaced: `${instanceId ?? name}:${fieldKey}`.
+  Two plugin instances both declaring `'signingSecret'` never get
+  each other's values.
+- The cached value is the **decrypted plaintext** — not the
+  ciphertext. There is no redundant decrypt on repeated calls.
 
 ### Admin UI
 
 When `settings.secret` is declared, the admin plugin settings page
 renders a **Secret settings** section below the public fields.
-Admins see `••••••••` for stored values and can Replace or Clear
-without deploying. Rotation takes effect within ~5–10 seconds.
+Each secret field shows:
+
+- **Unset**: a plain text input + Save button.
+- **Stored**: a masked placeholder `••••••••` + Replace + Clear
+  buttons. The actual value is never fetched or displayed.
+- **Editing**: after clicking Replace — new text input + Save + Cancel.
+
+Admins can rotate a secret at any time without redeploying. The
+change takes effect on the next trusted-Lambda invocation (within
+~5–10 seconds of saving).
+
+### Testing hooks that use `ctx.secret`
+
+Mock `ctx.secret` alongside the other context methods:
+
+```ts
+import { describe, it, expect, vi } from 'vitest'
+import webhookPlugin from './index.js'
+import type { TrustedPluginRuntimeContext } from 'ampless'
+
+function makeCtx(secrets: Record<string, string> = {}): TrustedPluginRuntimeContext {
+  return {
+    site: { name: 'Test', url: 'https://example.com' },
+    listPublishedPosts: vi.fn().mockResolvedValue([]),
+    writePublicAsset: vi.fn().mockResolvedValue(''),
+    secret: vi.fn().mockImplementation(async (key: string) => secrets[key]),
+  }
+}
+
+describe('webhookPlugin signing', () => {
+  it('uses admin-stored secret when available', async () => {
+    const plugin = webhookPlugin()
+    const ctx = makeCtx({ signingSecret: 'stored-secret' })
+    await plugin.hooks?.['content.published']?.({ type: 'content.published', payload: {} as never }, ctx)
+    // assert that the request was signed with 'stored-secret'
+  })
+
+  it('falls back to constructor secret when admin has not saved one', async () => {
+    const plugin = webhookPlugin({ signingSecret: 'fallback-secret' })
+    const ctx = makeCtx({}) // no stored secret
+    await plugin.hooks?.['content.published']?.({ type: 'content.published', payload: {} as never }, ctx)
+    // assert that the request was signed with 'fallback-secret'
+  })
+})
+```
+
+---
+
+## 9b. Where your plugin's data lives
+
+Plugin-owned data may live in the five storage areas listed below; the
+**current write paths differ by area** and fall into three families:
+
+- **KvStore** — admin/editor write through AppSync. Plugin hooks have no
+  KvStore write helper today.
+- **PluginSecret + PluginSecretIndicator** — written by the
+  `plugin-secret-handler` Lambda, which is invoked by admin/editor through
+  the `setPluginSecret` / `clearPluginSecret` AppSync mutations. The
+  trusted processor reads `PluginSecret` via `ctx.secret<T>()` but does
+  NOT write to either secret table.
+- **S3 `public/plugins/{instanceId ?? name}/*`** — written by the trusted
+  Lambda's hook context (`ctx.writePublicAsset(...)`). This is the only
+  area a plugin hook writes to directly today.
+
+All other areas — the `Post`, `Page`, `Media`, and `PostTag` DynamoDB
+tables, the `public/site-settings.json` S3 mirror, and any other plugin's
+namespace — are off-limits. The runtime does not enforce this today; it is
+a contract enforced by trust (and future IAM hardening).
+
+| Area | Path / identifier | Access level | Phase |
+|---|---|---|---|
+| KvStore (admin settings) | DynamoDB `pk='siteconfig'`, `sk='plugins.<instanceId>.<fieldKey>'` | admin/editor via AppSync; plugin hook write helper is not provided today | Phase 2 |
+| KvStore (runtime state/cache) | DynamoDB `pk='pluginstate:<plugin>:...'` with optional TTL | admin/editor via AppSync; plugin hook write helper is not provided today | Current |
+| PluginSecret | DynamoDB `PluginSecret` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` only (IAM-only AppSync auth) | Phase 6a |
+| PluginSecretIndicator | DynamoDB `PluginSecretIndicator` table, `sk='plugins.<instanceId>.<fieldKey>'` | `trusted` + admin/editor (read indicator) | Phase 6a |
+| S3 plugin assets | `public/plugins/{instanceId ?? name}/*` | `trusted` only (`writePublicAsset`) | Phase 3 |
+
+**Cleanup is not automatic.** Removing a plugin from `cms.config.ts` leaves
+orphan data in all five areas. Manual operator cleanup is required until the
+future lifecycle-dispatch PR ships the invocation mechanism for the `uninstall`
+hook (see §9c below).
+
+**Custom DynamoDB tables.** If your plugin provisions its own DynamoDB table
+outside the ampless schema, lifecycle management (including cleanup on uninstall)
+is your responsibility. ampless has no visibility into external tables and the
+future `uninstall` cleanup grants cover only the five areas above.
+
+See [`docs/architecture/08-plugin-architecture.md`](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#plugin-owned-data-areas)
+for the full rationale and the IAM grant design.
+
+---
+
+## 9c. `uninstall` hook (Phase 1 reservation)
+
+`AmplessPlugin.uninstall` is a **Phase 1 type reservation** — the runtime does
+not call it today. Its purpose is to lock in the hook name and signature before
+any plugin code ships, so the future lifecycle-dispatch PR can wire the
+invocation without renaming or reshaping anything.
+
+**Phase 1 scope**: only the hook name and signature are reserved. The `ctx`
+does **not** yet carry cleanup helpers (`deletePublicAsset` /
+`deletePluginSetting` / `deletePluginSecret`) — writing
+`await ctx.deletePublicAsset(...)` today is a TypeScript error. When those
+helpers land (in the lifecycle-dispatch PR), they are added to
+`PluginUninstallContext` additively, with no breaking change to plugins that
+declared an empty body in advance.
+
+**Recommended declaration today** — an empty body:
+
+```ts
+// Example: a trusted plugin that writes assets and stores secrets
+definePlugin({
+  name: 'my-trusted-plugin',
+  apiVersion: 1,
+  trust_level: 'trusted',
+  capabilities: ['eventHooks', 'writePublicAsset', 'secretSettings'],
+  hooks: { 'content.published': async (_evt, ctx) => { /* ... */ } },
+  uninstall: async (_ctx) => {
+    // Phase 1 reservation: the runtime does not invoke this hook
+    // today, AND `ctx` does not yet carry cleanup helpers
+    // (`deletePublicAsset` / `deletePluginSetting` /
+    // `deletePluginSecret`). Declaring an empty body is the
+    // recommended forward-compat shape — when the future
+    // lifecycle-dispatch PR ships, the helpers land on
+    // `PluginUninstallContext` additively, and you fill in the
+    // body THEN. Plugins that shipped the empty declaration
+    // today do not need to re-publish for the signature change,
+    // but a re-publish is required to add the actual cleanup
+    // body.
+  },
+})
+```
+
+**Idempotency.** When the lifecycle-dispatch PR ships, the `uninstall` hook
+runs in a trusted-Lambda IAM context. The SQS delivery is at-least-once, so
+your cleanup body may run more than once — design it to be safe to retry
+(e.g. `deleteObject` is idempotent on S3; a conditional `delete` on DDB is
+safe if the key is already gone).
+
+---
+
+## 9d. When you change settings shape (Phase 1 reservation)
+
+### What happens today: `public` and `secret` travel through different paths
+
+Shape changes are absorbed silently by today's runtime, but the actual
+behaviour differs between `settings.public` and `settings.secret` because
+they use entirely different write/read paths.
+
+#### `settings.public` (lenient resolver via `resolvePluginSettings`)
+
+`resolvePluginSettings` ([packages/ampless/src/plugin-settings.ts](packages/ampless/src/plugin-settings.ts))
+iterates `manifest.public` and falls back to `field.default` per field. The
+resolver never looks at `manifest.secret`.
+
+| Change | Behaviour today (public fields) |
+|---|---|
+| **Field added** | New field resolves via `manifest.default` — stored value is absent, default takes over. |
+| **Field deleted** | Orphan row remains in KvStore. `resolvePluginSettings` silently skips keys that are not in the current manifest. |
+| **Field renamed** (`endpoint` → `url`) | Treated as deletion + addition: old value is unreachable (orphan), new field resolves via `default`. |
+| **Type changed incompatibly** | New validator runs on the stored value. If it passes, the value is used. If it fails, falls through to `default` (or `undefined`). |
+
+#### `settings.secret` (admin UI + `PluginSecret` + `ctx.secret()`, no lenient resolver)
+
+Secret fields are never read by `resolvePluginSettings`. They travel a
+separate path:
+
+- The admin UI writes individual values through the `setPluginSecret`
+  AppSync mutation, which the `plugin-secret-handler` Lambda encrypts and
+  stores in the `PluginSecret` DynamoDB table.
+- Trusted hooks read them individually by key via `ctx.secret<T>(key)`,
+  which goes directly to `PluginSecret` and decrypts.
+- The `PluginSecretField` type forbids `default` — there is no
+  manifest-level fallback for secret values.
+
+| Change | Behaviour today (secret fields) |
+|---|---|
+| **Field added** | New field appears in the admin UI. Until an admin sets a value, `ctx.secret<T>(key)` returns `undefined`. |
+| **Field deleted** | The field disappears from the admin UI, but the encrypted row in `PluginSecret` is orphaned. No resolver runs over it; an operator must delete it manually. |
+| **Field renamed** | Old key's encrypted row is orphaned (no resolver / cleanup). The new key shows up unset. Admin must re-enter the value under the new key. |
+| **Type changed incompatibly** | `validatePluginSettingValue` only runs at write time, so an existing stored ciphertext is unaffected on read; `ctx.secret<T>(key)` returns whatever was last written. A re-validate on admin save would reject incompatible new input. |
+
+No error or warning is produced in any of these cases. Plugin authors must
+inspect their stored values manually if they need to verify behaviour
+after a shape change.
+
+### The `version` reservation
+
+`PluginSettingsManifest.version?: number` is a **Phase 1 type
+reservation** — the runtime does NOT read it today. Declaring it has no
+effect on the lenient resolver above.
+
+The reservation exists so that a future migration PR may persist the
+active manifest version somewhere alongside stored values and compare it to
+`manifest.version` at resolve time to detect mismatch. The exact mismatch
+response (warn / skip / migrate in-place / trigger an admin-driven flow) is
+design territory for that future PR.
+
+**What declaring `version` today does NOT promise:**
+
+- It does NOT trigger any migration body.
+- It does NOT cause the runtime to re-validate or re-default stored values.
+- It does NOT reserve a `migrate` hook signature — that is a separate future
+  design.
+
+**What declaring `version` today does do:**
+
+- It positions the plugin to be picked up by the future migration detection
+  path, without requiring a re-publish just to add the `version` field once
+  that PR ships.
+- It communicates intent to future maintainers that this manifest has a
+  versioned shape.
+
+### Recommended pattern
+
+| Scenario | Recommendation |
+|---|---|
+| Additive change only (new optional field, default provided) | No `version` bump needed. Lenient resolver handles it. |
+| Non-additive change (rename, incompatible type change, semantic shift) | Bump `version` by 1. |
+| First time adding `version` to an existing manifest | Start at `version: 1`. |
+
+**Use positive integers, starting at 1.** Do NOT use `0`, negative numbers,
+or floats — the `number` type accepts them but the future migration PR may
+reserve special semantics for `0` / undefined (legacy / pre-v1 conflation).
+
+### Code example
+
+```ts
+definePlugin({
+  name: 'my-plugin',
+  apiVersion: 1,
+  trust_level: 'untrusted',
+  capabilities: ['adminSettings'],
+  settings: {
+    version: 2,           // ← Phase 1 reservation. Today runtime ignores.
+    public: [
+      { type: 'url', key: 'webhookUrl', label: 'Webhook URL', required: true },
+    ],
+  },
+})
+```
+
+When a future migration PR ships, plugins that have already declared
+`version` will be on the detection path automatically. Plugins that want to
+provide an actual migration body will need to re-publish after that PR ships
+to add the body. Plugins that omit `version` entirely continue with the
+current lenient-resolver behaviour — no change.
 
 ---
 
@@ -1168,10 +2229,15 @@ a normal npm package:
   monorepo.
 - **Entry**: ESM only, exports default (the factory) and the
   config interface (for typed args in user `cms.config.ts`).
-- **`apiVersion`**: bump only when the contract changes. Bump
-  major when an existing field's type changes; bump minor when you
-  add a new field (existing installs keep working).
-- **Dist-tag**: `@alpha` while ampless itself is in alpha. The
+- **`apiVersion`**: declare `1` today — it is the only valid
+  value, and the literal type rejects others at compile time.
+  `apiVersion` is the breaking-change marker on the plugin
+  contract, not a semver-style channel: additive changes (new
+  optional fields, new reserved capabilities) stay within
+  `apiVersion: 1` and do NOT require a bump. See the [apiVersion
+  bump policy](https://github.com/heavymoons/ampless/blob/main/docs/architecture/08-plugin-architecture.md#apiversion-bump-policy)
+  in the architecture doc for the full criteria.
+- **Dist-tag**: `@beta` while ampless itself is in beta. The
   `@latest` tag stays reserved until ampless v1.0.
 
 Worked examples to crib from:
@@ -1181,7 +2247,7 @@ Worked examples to crib from:
 - [`packages/plugin-plausible`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-plausible) — single `<script>` descriptor with `data-*` attrs and a required URL field (self-hosted Plausible override).
 - [`packages/plugin-rss`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-rss) — trusted, async event hooks + `writePublicAsset`.
 - [`packages/plugin-seo`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-seo) — `metadata()` + `siteMetadata()`.
-- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — untrusted hook with outbound HTTP.
+- [`packages/plugin-webhook`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-webhook) — trusted hook with outbound HTTP + `secretSettings` (admin-managed signing secret, Phase 6a).
 - [`packages/plugin-og-image`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-og-image) — `ogImage` route renderer.
 - [`packages/plugin-schema-jsonld`](https://github.com/heavymoons/ampless/tree/main/packages/plugin-schema-jsonld) — `publicBodyForPost` + `schema` capability; per-post Article JSON-LD. (Phase 4)
 
@@ -1238,7 +2304,7 @@ CLI ships a `plugin <name>` subcommand:
 ```bash
 # Site-local: scaffolds plugins/<name>/index.ts inside the current
 # ampless site. Run from the site repo root.
-npx create-ampless@latest plugin my-thing \
+npx create-ampless@beta plugin my-thing \
   --trust-level untrusted \
   --capabilities publicHead,adminSettings
 
@@ -1246,7 +2312,7 @@ npx create-ampless@latest plugin my-thing \
 # tsconfig.json, tsup.config.ts, README + .ja, CHANGELOG, .gitignore,
 # and src/index.ts + src/index.test.ts. Run from wherever you want
 # the new package directory to land.
-npx create-ampless@latest plugin @myscope/ampless-plugin-thing \
+npx create-ampless@beta plugin @myscope/ampless-plugin-thing \
   --standalone \
   --trust-level untrusted \
   --capabilities publicHead,adminSettings \
@@ -1260,7 +2326,7 @@ keyword, and a minimal vitest sample so `pnpm install && pnpm test &&
 pnpm build` runs clean on the freshly generated directory.
 
 Both modes also accept a positional flag-less invocation (`npx
-create-ampless@latest plugin`) that walks you through the same
+create-ampless@beta plugin`) that walks you through the same
 questions interactively via the @clack prompt UI.
 
 ### Publishing a standalone plugin
@@ -1270,17 +2336,17 @@ cd ampless-plugin-thing
 pnpm install
 pnpm test
 pnpm build
-pnpm publish --access public --tag alpha
+pnpm publish --access public --tag beta
 ```
 
 `--access public` is mandatory for scoped names (`@scope/...`).
-`--tag alpha` matches the current ampless pre-release cadence — drop
+`--tag beta` matches the current ampless pre-release cadence — drop
 it once the package reaches a stable major.
 
 There's a publish-to-install lag of "seconds to minutes" before
-`npm install <pkg>@alpha` picks up a fresh publish (CDN + registry
+`npm install <pkg>@beta` picks up a fresh publish (CDN + registry
 replica propagation). If `npm install` 404s right after `npm publish`
-returns, wait 1-2 minutes and retry — `npm view <pkg>@alpha version`
+returns, wait 1-2 minutes and retry — `npm view <pkg>@beta version`
 visible in the registry is necessary but sometimes not sufficient.
 
 ### Naming the package
@@ -1331,6 +2397,7 @@ PROTECTED), so the scaffolded code is safe across ampless upgrades.
 - Bugs in the plugin runtime / admin form → same repo, label
   `area:plugins`.
 
-The ampless repo stays private until v1.0 RC. Once it's public, the
-links above resolve to the actual GitHub URLs; today they live in
-the package tarball directly under `node_modules/ampless/docs/`.
+The GitHub URLs above resolve in the public beta repo. The same docs
+also live in the package tarball directly under
+`node_modules/ampless/docs/`, so plugin authors can read them locally
+without checking out this repo.