@topy-ai/maggie 0.7.4 → 0.7.6

package/README.md

@@ -92,6 +92,9 @@ maggie bootstrap interview | phase ...
 maggie dash install | init | status | migrate | cms ...
 maggie dash transition ...      # explicit content approval transition
 maggie dash variant ...         # service variant create/review/preview/publish
+maggie dash sections ...        # validate/catalogue/identity keys
+maggie agent-content write ...  # host-authorized, origin-bound content bridge
+maggie verification coverage ... # changed surface/locale evidence gate
 maggie clone ...                 # authorized homepage capture
 maggie design ...                # authorized interior-page design
 maggie clone-to-template ...     # URL → validated marketplace template
@@ -109,6 +112,18 @@ maggie design icon-inventory --source-dir src --runtime assets/icons.css
 maggie api lifecycle | site-audit | ops audit
 ```
 
+Agent content writes must declare the exact host origin that minted the
+short-lived token; the CLI rejects nested credential keys and cross-origin
+redirects:
+
+```bash
+maggie agent-content write \
+  --url https://example.test/api/maggie/agent-content.json \
+  --allowed-origin https://example.test \
+  --token-env MAGGIE_CONTENT_TOKEN \
+  --payload .maggie/content-operation.json
+```
+
 Run `maggie --help` for the complete syntax. `maggie-emdash` is migration
 history only and is not an installable package skill.
 
@@ -191,8 +206,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.4 update --project . --force
-npx @topy-ai/maggie@0.7.4 cleanup --project .
+npx @topy-ai/maggie@0.7.6 update --project . --force
+npx @topy-ai/maggie@0.7.6 cleanup --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never
@@ -202,15 +217,25 @@ as a command-line argument:
 node scripts/publish-npm.mjs --maggie-env-file ../.env
 ```
 
-The 0.7.4 workflow adds the installable MaggieDash admin distribution and
+The 0.7.6 workflow adds the installable MaggieDash admin distribution and
 audited CMS operations (`cms revisions`,
 `trash`, `restore`, `schedule`, `publish-due`, `duplicate`, `redirect`, and
 signed `preview`). It also adds a read-only MaggieDash `--diff`/`--dry-run`
 migration inventory, body-only dashboard prop validation, dialog accessibility
 contract checks, 404-only redirect policy, trash/scheduler/preview invariants,
-and a shared first-party traffic filter for every measurement channel. The
-release retains the existing service matching, localization, seed-manifest,
-lockfile/analytics, sitemap, deployment and rollback workflows.
+and a shared first-party traffic filter for every measurement channel. It also
+adds stable section identities and reusable section presets, a machine-readable
+MaggieDash section registry, a short-lived agent content bridge, restart gates
+for out-of-band translation writes, deployment release-runner generation,
+disk-versus-manifest skill inventory checks, and changed-surface/locale
+verification. Surface evidence is route-level and rejects duplicate
+observations; every route must include status, canonical, indexability, and
+required metadata checks. Agent content writes require an explicit approved
+origin, same-origin redirects, and recursive credential validation. Feedback
+submissions persist and print only an allowlisted acknowledgement. The release
+retains the existing service matching,
+localization, seed-manifest, lockfile/analytics, sitemap, deployment and
+rollback workflows.
 
 ## MaggieDash lifecycle
 
@@ -300,6 +325,9 @@ maggie feedback submit .maggie/feedback/<feedback-id>.json \
 Submission is never implicit. Project paths, source files, logs, and secrets
 are excluded by default. The hosted endpoint stores the normalized feedback in
 NoBlox for maintainer review; it does not automatically create a GitHub Issue.
+The local submission record and command output keep only `status`, `feedbackId`,
+and `requestId` from the provider acknowledgement; arbitrary response bodies
+are not persisted or printed.
 For public reports, use the repository's
 [GitHub Issue Forms](https://github.com/TOPY-AI-LTD/ai-cmo-skills/issues/new/choose).
 

package/README.zh-TW.md

@@ -8,7 +8,7 @@ Codex、Claude Code 與相容的 coding agents。
 ## 安裝
 
 ```bash
-npx @topy-ai/maggie@0.6.9 init --agent all
+npx @topy-ai/maggie@0.7.6 init --agent all
 npx @topy-ai/maggie doctor --project .
 ```
 
@@ -25,6 +25,10 @@ maggie doctor --project . --require-bootstrap --strict
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
+MaggieDash 也提供穩定 section identity、可重用 section arrangement、機器可讀
+section registry、短期 agent content bridge，以及 translation out-of-band write
+後的 restart gate。`maggie doctor` 會比較 install manifest 與磁碟上的實際 skills。
+
 新版 release gates：
 
 ```bash

package/bin/maggie.js

@@ -66,9 +66,11 @@ Usage:
   maggie doctor [--project PATH]
   maggie bootstrap interview [project]
   maggie dash init|install|status|migrate|transition|variant|cms --project PATH [options]
+  maggie dash sections <validate|prompt|keys> [options]
   maggie dash status --project PATH
   maggie dash migrate --project PATH --confirm
   maggie content FILE --source PROVIDER --project PATH --confirm
+  maggie agent-content write --url URL --token-env ENV --payload FILE
   maggie bootstrap phase <start|pass|fail|status> <phase> [project]
   maggie remove [SKILL ...] [--project PATH] [--agent codex|claude|all]
   maggie cleanup --project PATH [--confirm]
@@ -117,6 +119,7 @@ Usage:
   maggie site-audit URL --crawl --save-baseline FILE --reviewer NAME
   maggie site-audit URL --crawl --baseline FILE
   maggie browser-audit URL --browse PATH --output DIR --required SELECTOR [--sticky SELECTOR]
+  maggie verification coverage --contract FILE --evidence FILE
   maggie ops audit|preflight|verify|lockfiles|seed-manifest --project PATH
   maggie ops preflight --project PATH --write
 
@@ -320,11 +323,22 @@ function doctor(args) {
     ["claude-skills", existsSync(join(root, ".claude", "skills"))],
   ];
   for (const [name, passed] of checks) console.log(`${passed ? "PASS" : "INFO"} ${name}`);
+  const manifestPath = join(root, STATE_DIR, "install.json");
+  let manifest = null;
+  try { if (existsSync(manifestPath)) manifest = JSON.parse(readFileSync(manifestPath, "utf8")); } catch { manifest = null; }
+  const expected = Array.isArray(manifest?.skills) ? [...new Set(manifest.skills)] : null;
   const installed = [];
+  const installedNames = new Set();
   for (const agentRoot of [join(root, ".agents"), join(root, ".claude")]) {
-    for (const skill of SKILL_NAMES) if (existsSync(join(agentRoot, "skills", skill, "SKILL.md"))) installed.push(`${agentRoot}/${skill}`);
+    for (const skill of SKILL_NAMES) if (existsSync(join(agentRoot, "skills", skill, "SKILL.md"))) {
+      installed.push(`${agentRoot}/${skill}`);
+      installedNames.add(skill);
+    }
   }
-  console.log(`INFO installed-skills=${installed.length}`);
+  const missing = expected ? expected.filter((skill) => !installedNames.has(skill)) : [];
+  const inventoryState = expected && missing.length ? "INCOMPLETE" : "PASS";
+  console.log(`${inventoryState} skill-inventory manifest=${expected?.length ?? "unknown"} on-disk=${installedNames.size}${missing.length ? ` missing=${missing.join(",")}` : ""}`);
+  console.log(`INFO installed-skills=${installedNames.size}`);
   console.log("INFO doctor is diagnostic; bootstrap completion remains a project decision gate.");
 }
 
@@ -394,7 +408,9 @@ try {
   else if (command === "feedback") workflowCli("maggie_feedback.py", args);
   else if (command === "site-audit") workflowCli("site_audit.py", args);
   else if (command === "browser-audit") workflowCli("maggie_browser_audit.py", args);
+  else if (command === "verification") workflowCli("maggie_verification.py", args);
   else if (command === "dash") workflowCli("maggie_dash.py", args);
+  else if (command === "agent-content") workflowCli("maggie_agent_content.py", args);
   else if (command === "content") workflowCli("maggie_content.py", args);
   else if (command === "init" || command === "install") install(args);
   else if (command === "update") update(args);

package/bundled-contracts/maggie-deployment/release-runner-v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/release-runner-v1.schema.json",
+  "title": "Maggie deployment release runner v1",
+  "type": "object",
+  "required": ["schemaVersion", "orderedSteps", "retention"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-release-runner.v1"},
+    "orderedSteps": {"const": ["install", "typecheck", "migrate", "build", "carry-agent-state", "switch", "restart", "verify", "prune"]},
+    "retention": {"const": "exactly-current-plus-one-rollback"},
+    "mutation": {"enum": ["reviewable-script", "executed-after-confirmation"]}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/README.md

@@ -18,6 +18,12 @@ frontend framework.
   self/chain safety for canonical route redirects;
 - [`telemetry-policy-v1.json`](telemetry-policy-v1.json): first-party/toolchain
   traffic exclusion for every measurement channel.
+- [`agent-content-v1.json`](agent-content-v1.json): short-lived host bridge for
+  validated agent content writes without database credentials;
+- [`section-identity-v1.json`](section-identity-v1.json): stable section IDs
+  for translation keys and ordered migration;
+- [`translation-cache-policy-v1.json`](translation-cache-policy-v1.json):
+  restart-after-out-of-band-write evidence.
 
 MaggieDash owns these contracts. Provider adapters may add namespaced metadata,
 but they may not change the required identity, status, provenance, or approval

package/bundled-contracts/maggiedash/agent-content-v1.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/agent-content-v1.schema.json",
+  "title": "MaggieDash agent content bridge v1",
+  "type": "object",
+  "required": ["method", "authorization", "tokenLifetime", "databaseCredentials", "originPolicy", "payloadSecurity"],
+  "properties": {
+    "method": {"const": "POST"},
+    "authorization": {"const": "Bearer short-lived session token"},
+    "tokenLifetime": {"const": "terminal session"},
+    "databaseCredentials": {"const": "never exposed to agent"},
+    "originPolicy": {"const": "explicit approved origin allowlist; redirects remain same-origin"},
+    "payloadSecurity": {"const": "recursive sensitive-key rejection and response redaction"},
+    "writes": {"type": "array", "items": {"enum": ["validated content operation", "revision", "audit event"]}}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/section-identity-v1.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/section-identity-v1.schema.json",
+  "title": "MaggieDash stable section identity v1",
+  "type": "object",
+  "required": ["schemaVersion", "keyPattern", "fallback", "migrationOrder"],
+  "properties": {
+    "schemaVersion": {"const": "maggiedash-section-identity.v1"},
+    "keyPattern": {"const": "page.<id>.sections.<section-id>.<field>"},
+    "fallback": {"const": "array-index-until-migrated"},
+    "migrationOrder": {"const": "longest-old-prefix-first"}
+  },
+  "additionalProperties": false
+}

package/bundled-contracts/maggiedash/translation-cache-policy-v1.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://maggiedash.noblox.app/contracts/translation-cache-policy-v1.schema.json",
+  "title": "MaggieDash translation cache policy v1",
+  "type": "object",
+  "required": ["schemaVersion", "outOfBandWrite", "restartRequired", "restartCommand", "verificationAfterRestart"],
+  "properties": {
+    "schemaVersion": {"const": "maggie-restart-gate.v1"},
+    "outOfBandWrite": {"const": true},
+    "restartRequired": {"const": true},
+    "restartCommand": {"type": "string", "minLength": 1},
+    "verificationAfterRestart": {"const": true}
+  },
+  "additionalProperties": false
+}

package/bundled-references/localization-extraction-render-prd.md

@@ -0,0 +1,55 @@
+# Localization source extraction and rendered validation
+
+## Problem
+
+`maggie-content-localization` currently accepts a prepared `content.json` and
+validates the resulting job. It does not extract translatable strings from a
+real project, so malformed JSX fragments, multiline text nodes, untranslated
+Latin terms, and script mismatches can pass the record validator while still
+breaking the rendered page.
+
+## Proposed stable workflow
+
+Add a read-only extractor and a separate rendered validation gate:
+
+```bash
+maggie localization extract --project . --source-dir src \
+  --routes-file docs/routes.tsv --output .maggie/localization/source.json
+maggie localization plan --content .maggie/localization/source.json ...
+maggie localization validate .maggie/localization/<job>.json \
+  --source .maggie/localization/source.json \
+  --render-report .maggie/localization/rendered.json
+```
+
+The extractor must use an AST-aware adapter for JSX/TSX/Astro/Vue/Svelte
+where available, with a conservative HTML fallback. It must never rewrite
+source files. Each extracted string records file, line, route, source hash,
+attribute/text-node kind, and an explicit translatable/non-translatable
+decision. Fragments containing braces or JavaScript operators are rejected or
+reported for review, not interpreted as text.
+
+The validation report must cover multiline nodes, required metadata, protected
+facts, script expectations, glossary/allowlist exceptions, and browser output.
+The rendered report must identify route, screenshot, console errors, failed
+asset requests, placeholder count, and untranslated required strings. Any
+failure keeps the locale non-indexable and blocks publish.
+
+## Acceptance criteria
+
+- JSX conditionals and expressions are never emitted as translation strings.
+- Text nodes spanning multiple lines are extracted and tested.
+- Script/Latin-word checks support all registered languages and configurable
+  proper-noun/glossary allowlists.
+- Source and translated strings are linked by stable IDs and source revision.
+- A clean extraction plus clean rendered report is required before approval;
+  record-only validation is not sufficient.
+- Unit fixtures cover Astro/JSX/Vue/Svelte/HTML, false positives, protected
+  facts, multiline nodes, script checks, and route-level browser errors.
+- The feature remains local-first, dependency-adaptable, redacted, and
+  backward-compatible with existing `content.json` input.
+
+## Out of scope
+
+Automatic translation quality scoring, silent source rewriting, and automatic
+publish. Translation generation and owner/Admin approval remain separate
+operations.

package/bundled-skills/maggie-content-localization/SKILL.md

@@ -114,7 +114,7 @@ line numbers, routes, and attribute/text-node kinds while skipping scripts,
 styles, SVG, and dynamic expressions. Supplying source and render reports to
 `validate` makes the checks fail closed; the prepared `content.json` flow
 remains backward-compatible without those artifacts. See
-[`docs/localization-extraction-render-prd.md`](../../docs/localization-extraction-render-prd.md)
+[`docs/localization-extraction-render-prd.md`](../../references/localization-extraction-render-prd.md)
 for the artifact contract and limitations.
 
 Use the shared translation index and route predicates from

package/bundled-skills/maggie-dash/SKILL.md

@@ -46,6 +46,25 @@ owns the framework route, email/password session middleware, database, media
 storage, provider credentials, and `/api/maggie/*` adapter endpoints. Read the
 MaggieDash host adapter contract before adding a new framework adapter.
 
+For a built/deployed host, an agent must use the host's validated content
+bridge rather than editing release files or receiving database credentials:
+
+```bash
+maggie agent-content write \
+  --url https://example.test/api/maggie/agent-content.json \
+  --allowed-origin https://example.test \
+  --token-env MAGGIE_CONTENT_TOKEN --payload .maggie/content-operation.json
+```
+
+The host mints a short-lived session token. The bridge uses `POST` with
+`Authorization: Bearer`, requires the exact approved host origin, rejects
+cross-origin redirects, delegates to the ordinary save/revision/audit path,
+and returns 401/422 for invalid authority or content. Nested credential-like
+payload keys are rejected and response values are recursively redacted. Never
+put database credentials or the short-lived token in the payload or generated
+reports. See
+the [agent content contract](../../bundled-contracts/maggiedash/agent-content-v1.json).
+
 ## Workflow
 
 1. Inspect the project with `maggie dash status --project PATH`.
@@ -125,6 +144,11 @@ maggie dash cms publish-due --project . --project-id local-project \
   --reason "scheduled publish tick" --confirm
 maggie dash cms duplicate --project . --project-id local-project --document-id <id> \
   --new-id <new-id> --new-slug <new-slug> --reason "create draft" --confirm
+maggie dash cms preset-save --project . --project-id local-project \
+  --preset-id treatment-page --name "Treatment page" \
+  --sections-file .maggie/sections.json --confirm
+maggie dash cms preset-insert --project . --project-id local-project \
+  --preset-id treatment-page --existing-id hero-1 --reason "add arrangement" --confirm
 maggie dash cms redirect --project . --project-id local-project --from-path /old --to-path /new \
   --reason "canonical slug change" --confirm
 maggie dash cms preview --project . --project-id local-project --document-id <id> \
@@ -141,4 +165,32 @@ the route returns 404 and self/chain redirects are rejected. Preview tokens
 are short-lived HMAC-signed tokens; preview responses must use a real preview
 URL with `noindex`, `X-Robots-Tag: noindex`, and `Cache-Control: no-store`.
 Never place the secret in source control or generated reports. See the
-provider-neutral [MaggieDash contract set](../../contracts/maggiedash/README.md).
+provider-neutral [MaggieDash contract set](../../bundled-contracts/maggiedash/README.md).
+
+Reusable arrangements are stored without page-specific section IDs and expand
+into ordinary editable sections with fresh IDs on every insert. Use the
+machine-readable section catalogue before asking a model to plan copy:
+
+```bash
+maggie dash sections validate --registry templates/maggiedash/section-registry.json \
+  --sections-file .maggie/sections.json
+maggie dash sections prompt --registry templates/maggiedash/section-registry.json
+maggie dash sections keys --registry templates/maggiedash/section-registry.json \
+  --page-id <page-id> --sections-file .maggie/sections.json
+```
+
+The catalogue declares purpose, usage, placement, repeatability and layout
+limits. Over-limit copy is an editor note; unknown types fail validation.
+Translation keys use stable section IDs, with an array-index fallback only
+until the ordered migration is complete.
+
+After any script or direct adapter write to translation data, invalidate the
+running process before verification. Record the restart and run the rendering
+check afterward:
+
+```bash
+maggie ops restart-gate --manifest .maggie/translation-restart.json
+```
+
+This prevents an in-process cache window from turning correct database state
+into temporarily stale pages and false verification failures.

package/bundled-skills/maggie-deployment/SKILL.md

@@ -63,11 +63,15 @@ Generate a reviewable VPS plan and configuration artifacts locally:
 python3 tools/clis/maggie_deployment.py /path/to/project \
   --vps-plan --domain example.co.uk --service example \
   --release-root /var/www/example \
-  --plan-dir .maggie/deployment/vps-staging
+  --plan-dir .maggie/deployment/vps-staging \
+  --runner-output .maggie/deployment/vps-staging/release-runner.sh
 ```
 
 The output contains only the immutable release/current layout, systemd unit,
-Nginx reverse-proxy config, health commands and rollback command. It never
+Nginx reverse-proxy config, health commands, rollback command, and an ordered
+reviewable release runner. The runner keeps migrations before the symlink flip,
+carries `.agents`/`.claude` state, restarts before verification, and prunes to
+the current release plus one rollback candidate. It never
 contains credentials and never SSHs, changes DNS, restarts systemd or deploys.
 
 VPS plans include a bounded retention policy: keep two immutable releases,
@@ -136,6 +140,20 @@ MaggieDash schema compatibility, and live runtime security-header checks. It wri
 `.maggie/release-preflight.json`; a failed gate blocks release. It never
 deploys, migrates, publishes, or sends provider requests.
 
+Generate a repeatable VPS runner as part of the plan. A deploy step that exists
+only in an operator's shell history is not a release contract:
+
+```bash
+python3 tools/clis/maggie_deployment.py /path/to/project \
+  --vps-plan --domain example.co.uk --service example \
+  --release-root /var/www/example \
+  --runner-output .maggie/deployment/release-runner.sh
+```
+
+Review the generated runner before execution. Its order is install → typecheck
+→ migrate → build → carry agent state → switch → restart → verify → prune;
+retention keeps the current release and one rollback candidate.
+
 Production additionally requires `docs/deployment-rollback-smoke.json` with
 `passed: true`, `environment: production`, a non-empty `previousRelease`, and
 `testedAt`. A rollback command in a plan is not proof that the rollback was

package/bundled-skills/maggie-feedback/SKILL.md

@@ -44,7 +44,10 @@ maggie feedback submit .maggie/feedback/<feedback-id>.json \
 
 Only HTTPS endpoints are accepted. Project paths, file contents, secrets, and
 logs are excluded by default. `--allow-project-context` is an explicit opt-in;
-even then, send only a short public-safe context note.
+even then, send only a short public-safe context note. After submission, the
+local record and stdout retain only the provider acknowledgement fields
+`status`, `feedbackId`, and `requestId`; arbitrary response bodies are never
+stored or printed.
 
 ## Lifecycle
 

package/bundled-skills/maggie-ops/SKILL.md

@@ -226,3 +226,20 @@ shared contract is in
 [references/maggiedash-telemetry-contract.md](../../references/maggiedash-telemetry-contract.md);
 it excludes only explicit tool/test markers and never infers identity from IP
 or private fields.
+
+## Agent runtime preflight
+
+Before starting an agent from a dashboard, run the runtime preflight and show
+its warnings to the operator. Terminal output must be stripped of ANSI escape
+sequences before URL/code parsing. Headless hosts should use device auth and
+state the account prerequisite before starting. Release installs and agent
+conversation state must be carried outside the immutable release directory.
+When continuing a conversation, pass the agent's resume subcommand before
+other arguments; otherwise the CLI may interpret it as a new prompt.
+
+```bash
+maggie ops agent-preflight --output .maggie/agent-runtime-preflight.json
+```
+
+The preflight is advisory about the host environment but its warnings are
+load-bearing operational evidence, not a claim that an agent login succeeded.

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -19,6 +19,26 @@ Static audit success
 does not establish Google indexing, scroll behavior, responsive visibility,
 or translation quality. Record those as unverified without separate evidence.
 
+Choose verification from the changed surface. An admin-only change still needs
+the admin routes; an API change needs the API responses; a localized change
+needs every affected locale. Declare the matrix and validate explicit evidence
+before release:
+
+```bash
+maggie verification coverage \
+  --contract contracts/maggie-verification/surface-coverage-v1.json \
+  --evidence .maggie/surface-coverage.json
+```
+
+The evidence must contain one observation for every declared
+surface/locale/route key with a unique `route`, HTTP `status`, `passed: true`,
+`canonical: true`, a boolean `indexable`, and a `metadata` object containing
+every field named by that surface's `requiredMetadata`. Duplicate keys fail;
+the verifier preserves the observation count and reports the duplicate and
+the original failure instead of allowing a later passing observation to hide
+it. Public-page checks alone cannot close an admin or API change, and one
+source-language rendering cannot close a localized change.
+
 Crawl reports include `summary.byLocaleTemplate` with total, passed, failed
 and failed URLs per declared locale and template. Regions/scripts remain
 distinct (for example en-GB versus en-US). A template is identified only when

package/bundled-templates/maggiedash/section-registry.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": "maggiedash-section-registry.v1",
+  "description": "The machine-readable section vocabulary used by page planners and editors.",
+  "sections": [
+    {"type": "hero", "purpose": "Says what the page is about and offers the one important action.", "usage": "First on the page; once.", "position": "opening", "repeatable": false, "fields": [{"name": "title", "usage": "Plain words a visitor would search for.", "limit": 70, "required": true}, {"name": "intro", "usage": "Who it is for and what it does.", "limit": 220}, {"name": "ctaLabel", "usage": "The action as a verb.", "limit": 30}]},
+    {"type": "prose", "purpose": "Explains a topic at length, optionally beside an image.", "usage": "Use in the body for explanation.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "The argument in a sentence.", "limit": 90}, {"name": "paragraphs", "usage": "Two or three standalone paragraphs.", "limit": 400, "repeats": {"min": 1, "max": 4}}]},
+    {"type": "cards", "purpose": "Presents parallel points side by side.", "usage": "Use for steps or genuinely parallel points.", "position": "body", "repeatable": true, "fields": [{"name": "heading", "usage": "What the cards share.", "limit": 90}, {"name": "items", "usage": "The parallel points.", "limit": 220, "repeats": {"min": 3, "max": 3}}]},
+    {"type": "links", "purpose": "Sends the reader to related pages.", "usage": "Near the end after the page has done its job.", "position": "closing", "repeatable": true, "fields": [{"name": "heading", "usage": "What the links have in common.", "limit": 90}, {"name": "items", "usage": "Real related pages on this site.", "limit": 160, "repeats": {"min": 2, "max": 6}}]},
+    {"type": "faq", "purpose": "Answers questions a visitor would otherwise ask.", "usage": "Once near the end; use real visitor questions.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The question topic.", "limit": 90}, {"name": "items", "usage": "Direct questions and answers.", "limit": 600, "repeats": {"min": 2, "max": 8}}]},
+    {"type": "cta", "purpose": "Makes the closing ask.", "usage": "Last on the page; once.", "position": "closing", "repeatable": false, "fields": [{"name": "heading", "usage": "The invitation in a sentence.", "limit": 90, "required": true}, {"name": "body", "usage": "What happens next.", "limit": 220}, {"name": "label", "usage": "The action as a verb.", "limit": 30, "required": true}]}
+  ]
+}

package/bundled-tools/clis/maggie_agent_content.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python3
+"""Use a short-lived MaggieDash host token for validated content writes."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlparse
+from urllib.request import HTTPRedirectHandler, Request, build_opener
+
+
+SENSITIVE_KEYS = {"databaseurl", "password", "secret", "token", "apikey", "authorization", "privatekey", "connectionstring", "clientsecret"}
+SENSITIVE_KEY_PARTS = ("databaseurl", "password", "secret", "token", "apikey", "authorization", "privatekey", "connectionstring")
+
+
+def normalized_key(value: object) -> str:
+    return "".join(character for character in str(value).lower() if character.isalnum())
+
+
+def is_sensitive_key(value: object) -> bool:
+    key = normalized_key(value)
+    return key in SENSITIVE_KEYS or any(part in key for part in SENSITIVE_KEY_PARTS)
+
+
+def validate_no_credentials(value: object) -> None:
+    if isinstance(value, dict):
+        for key, child in value.items():
+            if is_sensitive_key(key):
+                raise ValueError("payload must not contain credentials; use the short-lived token environment variable")
+            validate_no_credentials(child)
+    elif isinstance(value, list):
+        for child in value:
+            validate_no_credentials(child)
+
+
+def validate_payload(value: object) -> dict:
+    if not isinstance(value, dict):
+        raise ValueError("payload must be a JSON object")
+    validate_no_credentials(value)
+    if not value.get("op"):
+        raise ValueError("payload.op is required")
+    return value
+
+
+def origin(url: str) -> str:
+    parsed = urlparse(url)
+    if parsed.scheme not in {"http", "https"} or not parsed.hostname or parsed.username or parsed.password or parsed.query or parsed.fragment:
+        raise ValueError("content host must be an absolute HTTP(S) URL without credentials or query parameters")
+    try:
+        port = parsed.port
+    except ValueError as error:
+        raise ValueError("content host origin has an invalid port") from error
+    default = (parsed.scheme == "http" and port == 80) or (parsed.scheme == "https" and port == 443)
+    return f"{parsed.scheme.lower()}://{parsed.hostname.lower()}" + (f":{port}" if port and not default else "")
+
+
+def approved_origin(value: str) -> str:
+    parsed = urlparse(value)
+    if parsed.path not in {"", "/"}:
+        raise ValueError("approved origin must not contain a path")
+    return origin(value)
+
+
+class SameOriginRedirectHandler(HTTPRedirectHandler):
+    def __init__(self, approved_origin: str):
+        super().__init__()
+        self.approved_origin = approved_origin
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: N802
+        if origin(newurl) != self.approved_origin:
+            raise ValueError("content host redirected to a different origin")
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def redact_response(value: object) -> object:
+    if isinstance(value, dict):
+        return {key: "[REDACTED]" if is_sensitive_key(key) else redact_response(child) for key, child in value.items()}
+    if isinstance(value, list):
+        return [redact_response(child) for child in value]
+    return value
+
+
+def write(url: str, token_env: str, payload: dict, allowed_origin: str, timeout: int = 30) -> dict:
+    token = os.environ.get(token_env, "")
+    if not token:
+        raise ValueError(f"{token_env} is not set")
+    approved = approved_origin(allowed_origin)
+    if origin(url) != approved:
+        raise ValueError("content host URL must match the approved origin")
+    request = Request(url, data=json.dumps(payload, ensure_ascii=False).encode("utf-8"), method="POST", headers={
+        "Accept": "application/json", "Content-Type": "application/json", "Authorization": f"Bearer {token}",
+    })
+    try:
+        opener = build_opener(SameOriginRedirectHandler(approved))
+        with opener.open(request, timeout=timeout) as response:
+            raw = response.read().decode("utf-8", errors="replace")
+            status = response.status
+    except HTTPError as error:
+        raw = error.read().decode("utf-8", errors="replace")
+        status = error.code
+    except URLError as error:
+        raise RuntimeError("content host could not be reached") from error
+    try:
+        body = json.loads(raw) if raw else {}
+    except json.JSONDecodeError:
+        body = {"error": "host returned non-JSON"}
+    return {"status": status, "passed": 200 <= status < 300, "response": redact_response(body)}
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+    command = sub.add_parser("write", help="POST a validated content operation")
+    command.add_argument("--url", required=True)
+    command.add_argument("--allowed-origin", required=True, help="exact HTTP(S) origin approved by the host")
+    command.add_argument("--token-env", default="MAGGIE_CONTENT_TOKEN")
+    command.add_argument("--payload", type=Path, required=True)
+    command.add_argument("--timeout", type=int, default=30)
+    args = parser.parse_args()
+    try:
+        payload = validate_payload(json.loads(args.payload.read_text(encoding="utf-8")))
+        result = write(args.url, args.token_env, payload, args.allowed_origin, args.timeout)
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0 if result["passed"] else 1
+    except (OSError, ValueError, RuntimeError) as error:
+        print(f"agent-content: {error}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())