@topy-ai/maggie 0.1.0 → 0.1.2

package/bin/maggie.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
 import { cp } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -9,9 +10,12 @@ const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const SKILLS_ROOT = join(PACKAGE_ROOT, "bundled-skills");
 const REFERENCES_ROOT = join(PACKAGE_ROOT, "bundled-references");
 const TOOLS_ROOT = join(PACKAGE_ROOT, "bundled-tools");
+const STATE_DIR = ".maggie";
 const SKILL_NAMES = [
   "maggie-blog-bootstrap",
   "maggie-clone",
+  "maggie-design",
+  "maggie-ops",
   "maggie-deployment",
   "maggie-project-context",
   "maggie-seo-geo",
@@ -24,6 +28,7 @@ function usage() {
 Usage:
   maggie init [--project PATH] [--agent auto|codex|claude|all] [--skills LIST]
   maggie install [SKILL ...] [--project PATH] [--agent auto|codex|claude|all]
+  maggie update [SKILL ...] [--project PATH] [--agent auto|codex|claude|all] [--force]
   maggie list
   maggie doctor [--project PATH]
   maggie remove [SKILL ...] [--project PATH] [--agent codex|claude|all]
@@ -77,6 +82,35 @@ function copyIfMissing(source, target, force = false) {
   return "installed";
 }
 
+function digest(path) {
+  return createHash("sha256").update(readFileSync(path)).digest("hex");
+}
+
+function syncTree(source, target, force) {
+  let changed = 0;
+  for (const entry of readdirSync(source, { withFileTypes: true })) {
+    const sourcePath = join(source, entry.name);
+    const targetPath = join(target, entry.name);
+    if (entry.isDirectory()) {
+      changed += syncTree(sourcePath, targetPath, force);
+      continue;
+    }
+    if (!existsSync(targetPath)) {
+      mkdirSync(dirname(targetPath), { recursive: true });
+      writeFileSync(targetPath, readFileSync(sourcePath));
+      console.log(`installed ${targetPath}`);
+      changed++;
+    } else if (force || digest(sourcePath) === digest(targetPath)) {
+      writeFileSync(targetPath, readFileSync(sourcePath));
+      console.log(`updated ${targetPath}`);
+      changed++;
+    } else {
+      console.log(`preserved ${targetPath} (local changes; use --force to replace)`);
+    }
+  }
+  return changed;
+}
+
 function install(args) {
   const root = projectRoot(args);
   const skills = selectedSkills(args);
@@ -103,6 +137,34 @@ function install(args) {
   console.log("Run `maggie doctor --project .` before using mutating workflows.");
 }
 
+function update(args) {
+  const root = projectRoot(args);
+  const skills = selectedSkills(args);
+  const force = args.includes("--force");
+  const roots = agentRoots(args, root);
+  if (!existsSync(SKILLS_ROOT)) throw new Error("bundled skills are missing; run npm pack from the package source");
+  let updated = 0;
+  for (const agentRoot of roots) {
+    for (const skill of skills) {
+      const source = join(SKILLS_ROOT, skill);
+      const target = join(agentRoot, "skills", skill);
+      if (!existsSync(target)) {
+        console.log(`absent ${target} (run install to add it)`);
+        continue;
+      }
+      updated += syncTree(source, target, force);
+    }
+    if (existsSync(REFERENCES_ROOT) && existsSync(join(agentRoot, "references"))) updated += syncTree(REFERENCES_ROOT, join(agentRoot, "references"), force);
+  }
+  const tools = join(root, "tools");
+  if (existsSync(TOOLS_ROOT)) for (const group of ["clis", "integrations"]) if (existsSync(join(tools, group))) updated += syncTree(join(TOOLS_ROOT, group), join(tools, group), force);
+  const stateDir = join(root, STATE_DIR);
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, "install.json"), JSON.stringify({ version: "0.1.0", agents: roots.map((item) => item.slice(root.length + 1)), skills, updated_at: new Date().toISOString() }, null, 2) + "\n");
+  console.log(`Maggie update complete: ${updated} files changed`);
+  if (!force) console.log("Local files with changes were preserved. Review the output and rerun with --force only when replacement is intended.");
+}
+
 function list() {
   for (const skill of SKILL_NAMES) console.log(skill);
 }
@@ -143,6 +205,7 @@ try {
   if (["help", "--help", "-h"].includes(command)) usage();
   else if (command === "list") list();
   else if (command === "init" || command === "install") install(args);
+  else if (command === "update") update(args);
   else if (command === "doctor") doctor(args);
   else if (command === "remove") remove(args);
   else throw new Error(`unknown command: ${command}`);

package/bundled-references/blog-data-contract.md

@@ -56,6 +56,14 @@ with the canonical post source enum while remaining unique and rerunnable.
 This is the default for a new, small single-instance project. Use the same
 logical fields with Postgres or another engine when the deployment requires it.
 
+## Default listing configuration
+
+The default blog index is a 3-column grid with 9 posts per page (3×3). Store
+this as typed configuration (`postsPerPage: 9`, `gridColumns: 3`) rather than
+scattering literals through templates. Users may change it later through site
+settings; pagination, canonical URLs, sitemap eligibility, and audits must use
+the same configured value.
+
 ```sql
 CREATE TABLE posts (
   id TEXT PRIMARY KEY,

package/bundled-references/decision-loop.md

@@ -0,0 +1,25 @@
+# Maggie Decision Loop
+
+Every state-changing Maggie skill follows this protocol:
+
+1. Inspect first and label evidence `Detected`, `Likely`, `Missing`, or
+   `Unknown`.
+2. Propose one recommended choice and up to two alternatives.
+3. Ask one focused question at a time, showing the selection, evidence,
+   affected files, and risks.
+4. Record each answer in `.maggie/decisions.json` or a skill checkpoint.
+5. Summarize all selections and require explicit final confirmation before
+   mutation or external writes.
+6. If an earlier answer changes, recalculate dependent choices and confirm
+   again; never silently overwrite a confirmed decision.
+
+Headless runs use an answers JSON file plus a separate `--confirm` flag. They
+must follow the same sequence and may not bypass final confirmation.
+
+```bash
+python3 tools/clis/maggie.py bootstrap interview .
+python3 tools/clis/maggie.py bootstrap interview . --answers-file .maggie/answers.json --non-interactive --confirm
+```
+
+Use this loop for framework changes, clone routes, rewrite policy, publishing,
+integrations, migrations, and deployment.

package/bundled-references/ops-dashboard-contract.md

@@ -0,0 +1,41 @@
+# Maggie Ops Dashboard Contract
+
+Bootstrap must implement a private, authenticated Ops application before the
+blog is complete. Visual design is flexible; the operational surface and
+server-side boundaries are fixed.
+
+## Required screens
+
+```text
+/ops                         health summary and pending actions
+/ops/posts                   inventory, filters, bulk preview/apply
+/ops/posts/new               create draft
+/ops/posts/[id]/edit         validated editor and metadata preview
+/ops/posts/[id]/preview      noindex preview
+/ops/topics                  topics and FAQs
+/ops/sitemap                 sources, matching runs, unmatched and eligible counts
+/ops/reports                 SEO, content quality, visibility, analytics
+/ops/settings/site           origin, locale, timezone and defaults
+/ops/settings/integrations   Maggie API, GSC, GA4 and provider health
+/ops/operations              calendar, tasks, media, redirects and agency work
+/ops/wordpress               migration preview, apply, validate and resume
+```
+
+Required server routes include `/api/ops/summary`, `/api/ops/posts`,
+`/api/ops/topics`, `/api/ops/sitemap/{runs,match,auto-detect}`,
+`/api/ops/reports`, `/api/ops/pull/{project-context,sync,sync-updates}`,
+`/api/ops/rewrite/{queue,history,policy}`, and content-tracking report-state.
+
+Every request enforces session authentication, role authorization, input
+validation, and state-transition validation. Keys never reach browser code.
+Mutations show an impact preview where applicable and create an audit event
+with actor, timestamp, previous state, next state, reason, and an
+idempotency/correlation key. Ops pages are `noindex`, excluded from public
+sitemaps, and blocked in robots rules.
+
+## Bootstrap acceptance
+
+The bootstrap manifest contains the complete Ops route set, an enabled
+dashboard decision, and a verification command. `maggie doctor --strict
+--require-bootstrap` fails when the host project has no Ops UI, Ops API, or
+authentication boundary.

package/bundled-skills/README.md

@@ -7,6 +7,8 @@ Skills are the agent-facing workflows. They compose with the tools in
 |---|---|---|
 | `maggie-blog-bootstrap` | Build a complete blog in an existing project | site audit, analytics, API Pull |
 | `maggie-clone` | Reverse-engineer authorized URLs into namespaced blog-project pages | browser MCP, clone planner CLI, bootstrap state |
+| `maggie-design` | Fully clone authorized interior pages, then reconcile them to the homepage header/footer shell | browser MCP, clone planner CLI, completed Maggie homepage |
+| `maggie-ops` | Build, connect, operate, upgrade, and verify the private blog operations dashboard | Ops dashboard contract, authenticated API bridge, host tests |
 | `maggie-deployment` | Deploy and verify a dynamic Maggie blog, Cloudflare-first | Cloudflare Workers, D1, R2, KV, Wrangler |
 | `maggie-project-context` | Sync Project, voice, site and CTA context | project-context CLI/API |
 | `maggie-seo-geo` | Plan, audit, create/rewrite and measure SEO/GEO | visibility, SEO audit, GSC/GA4, content quality |

package/bundled-skills/maggie-blog-bootstrap/SKILL.md

@@ -2,7 +2,7 @@
 name: maggie-blog-bootstrap
 description: Build or complete a small SEO/GEO-ready blog in an existing vibe-coded project, including posts, metadata, sitemap, analytics hooks, and optional AI CMO API Pull integration. Use when adding a blog to a custom site, WordPress, Wix, Shopify, or headless stack.
 metadata:
-  version: 1.3.0
+  version: 1.4.0
 ---
 
 # Maggie Blog Bootstrap
@@ -31,6 +31,9 @@ GA4/GSC, AI CMO API Pull, rewrite delivery, or a basic content system.
    blog” is not approval to select an unconfirmed database, visual identity,
    language, or publishing policy.
 6. Prefer deterministic adapters and idempotent upserts over one-off scripts.
+7. Use the shared [Maggie decision loop](../../references/decision-loop.md):
+   inspect, propose, ask one question, record the answer, summarize, and then
+   require final confirmation. The CLI equivalent is `bootstrap interview`.
 
 ## Required phases
 
@@ -140,7 +143,15 @@ database, language, or visual system is unknown, say so instead of guessing.
 
 ### Phase 3: Decision gates
 
-Ask the user to confirm the recommendation in small groups before writing code:
+Ask the user to confirm the recommendation in small groups before writing code.
+Run the interactive loop when possible:
+
+```bash
+python3 tools/clis/maggie.py bootstrap interview .
+```
+
+It checkpoints every answer, shows the complete proposal, and requires a
+separate final confirmation. Use the following groups for the conversation:
 
 1. **Foundation:** framework, programming language, content language, runtime,
    and deployment target.
@@ -150,6 +161,11 @@ Ask the user to confirm the recommendation in small groups before writing code:
 4. **Content and publishing:** initial routes, API Pull, sitemap matching,
    rewrite approval, analytics, GSC, and whether the first run is dry-run.
 
+5. **Operations handoff:** decide whether the project needs the private Maggie
+   Ops dashboard now. If yes, hand off to `maggie-ops`; do not silently build a
+   partial admin surface inside bootstrap. If no, record Ops as pending while
+   completing the public blog foundation.
+
 Show the proposed choices, detected evidence, files likely to change, and
 unknowns for each gate. If the user confirms only part of a gate, implement
 only that part and leave the rest pending. Do not ask a single broad “is this
@@ -169,6 +185,11 @@ English             only when existing project language is absent
 These are proposals, not automatic permission. SQLite, English, a new font,
 or a new design system must never silently replace detected project choices.
 
+The default public blog index is 9 posts per page in a 3-column (3×3) grid.
+Store `postsPerPage: 9` and `gridColumns: 3` in typed configuration so the
+operator can change them later from site settings without changing the post
+model or pagination logic.
+
 ### Phase 4: Contract
 
 Implement or map these post fields:
@@ -180,7 +201,8 @@ canonicalUrl, coverImage, author, tags, status
 
 The public contract must support:
 
-- `/posts` with stable pagination or a bounded list;
+- `/posts` with stable pagination, defaulting to 9 posts per page and a 3-column
+  grid;
 - `/posts/:slug` with a real 404 for missing/unpublished posts;
 - canonical, Open Graph, Twitter, and Article metadata;
 - post links that are crawlable plain anchors;
@@ -199,6 +221,9 @@ Implement the host project's equivalent of:
 - JSON-LD `Article` or `BlogPosting` with valid dates and image URLs;
 - GA4 page view/event hooks that do nothing when analytics is disabled;
 - GSC verification via a public token or DNS instruction, never a private key.
+- an explicit Ops decision and handoff to `maggie-ops` when private content
+  operations are requested; the Ops dashboard is not satisfied by a mock or
+  partial bootstrap screen.
 
 ### Phase 6: Optional AI CMO integration
 

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

@@ -1,27 +1,30 @@
 ---
 name: maggie-clone
-description: Reverse-engineer one or more authorized websites and create matching pages inside an existing Maggie blog project. Use with /maggie-clone <target-url1> [<target-url2> ...] when a user wants to replicate a page's structure, content, assets, responsive behavior, and interactions.
-argument-hint: "<target-url1> [<target-url2> ...]"
+description: Reverse-engineer an authorized website homepage and create the Maggie homepage foundation inside an existing blog project. Use with /maggie-clone plus a homepage URL when the user wants to replicate the homepage structure, header, footer, assets, responsive behavior, and interactions.
 metadata:
   version: 1.0.0
 ---
 
 # Maggie Clone
 
-Create one or more website-inspired pages inside an existing Maggie blog
-project. This workflow is for authorized sites and pages. It preserves the
-host project's bootstrap foundation, public blog routes, content contracts,
-SEO safeguards, and existing user work while adding namespaced page output.
+Before any route or asset mutation, follow the shared [Maggie decision loop](../../references/decision-loop.md): inspect, propose, ask focused questions, checkpoint answers, summarize, and confirm.
+
+Create the authorized website homepage inside an existing Maggie blog project.
+This is the foundation workflow: it establishes the shared header, footer,
+navigation, brand assets, design tokens, and responsive shell that
+`maggie-design` will reuse for interior pages. It preserves the host project's
+bootstrap foundation, public blog routes, content contracts, SEO safeguards,
+and existing user work while adding namespaced page output.
 
 Invoke it as:
 
 ```text
-/maggie-clone <target-url1> [<target-url2> ...]
+/maggie-clone <homepage-url>
 ```
 
-The URL path becomes the default destination path. Multiple URLs from one
-origin remain separate routes; query strings and fragments are inspected for
-state but do not silently create duplicate routes.
+The target must be the origin homepage or an explicitly approved homepage
+variant. If the user supplies an interior page, stop and route the request to
+`maggie-design`; do not use homepage clone to create an interior page.
 
 ## Boundaries
 
@@ -36,9 +39,15 @@ state but do not silently create duplicate routes.
 - Use real public assets only when the user is authorized to reproduce them.
   Preserve attribution or licensing requirements and report assets that could
   not be safely reused.
-- The clone is an additive page operation. Do not overwrite an existing route,
-  component namespace, asset namespace, or research artifact without explicit
-  approval.
+- A supplied homepage URL is always a create or update request. If the
+  homepage route, component namespace, asset namespace, or research artifact
+  already exists, inspect it and reconcile/regenerate the requested target;
+  never silently skip it because output exists. Preserve unrelated local
+  changes and report changed, preserved, and conflicted files. Explicit
+  approval is still required for unrelated shared-foundation changes.
+- The homepage header and footer become the shared shell source of truth. Record
+  their component paths, tokens, breakpoints, states, and asset dependencies so
+  later design pages never fork them.
 - Keep AI CMO writes, publishing, and external deployment separate from local
   page construction. A clone does not automatically create, publish, or queue
   content in Maggie.
@@ -61,7 +70,7 @@ editing and report the missing capability.
    ```bash
    python3 tools/clis/maggie.py status <project-root>
    python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
-   python3 tools/clis/maggie_clone.py plan <url1> [<url2> ...] --project <project-root>
+   python3 tools/clis/maggie_clone.py plan <homepage-url> --project <project-root>
    ```
 
    The clone planner emits collision-resistant site/page keys and destination
@@ -76,7 +85,7 @@ editing and report the missing capability.
    approval for a combined route-scoped app. Do not mix global fonts or CSS
    foundations silently.
 
-Write an output plan before implementation containing, for every URL:
+Write an output plan before implementation containing:
 
 ```text
 source URL -> destination route
@@ -185,7 +194,7 @@ The cloned page remains a Maggie blog project page:
 
 ## Phase 4: Verification
 
-For every target:
+For the homepage target:
 
 1. Run the host typecheck/lint/build commands and `doctor --strict`.
 2. Verify the exact destination URL, neighboring blog routes, 404 behavior,
@@ -207,7 +216,8 @@ differences and whether they are known, measured, or unverified.
 
 ## Completion report
 
-Report source-to-route mappings, preserved routes, sections/components/specs,
+Report source-to-route mapping, the shared header/footer source of truth,
+preserved routes, sections/components/specs,
 assets downloaded and failed, files changed, commands run, build/audit status,
 visual QA result, and known limitations. Deployment, API Pull, rewrite, and
 publication require a separate explicit request.

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

@@ -7,6 +7,8 @@ metadata:
 
 # Maggie Deployment
 
+Before changing deployment or production state, follow the shared [Maggie decision loop](../../references/decision-loop.md) and obtain explicit confirmation of target, environment, migrations, and rollback plan.
+
 Deploy a confirmed Maggie blog to a real hosting target. Cloudflare Workers is
 the default target for dynamic Astro sites; use the Cloudflare reference for
 Worker, D1, R2, KV, secrets, environments, and verification details.

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

@@ -0,0 +1,214 @@
+---
+name: maggie-design
+description: Fully clone authorized interior pages, then reconcile their header and footer to the Maggie homepage shell. Use with /maggie-design plus one or more target URLs for pricing, about, feature, landing, or other non-homepage pages.
+metadata:
+  version: 1.1.0
+---
+
+# Maggie Design
+
+Create authorized interior pages inside an existing Maggie project. This is
+the interior-page companion to `maggie-clone`, but it is not a shortened
+content-only clone. For every supplied URL, first execute the complete clone
+workflow and create a full first-pass page, including the target's header and
+footer. Then reconcile the page to the already-cloned homepage shell so that
+only the page-specific content remains different.
+
+Invoke it as:
+
+```text
+/maggie-design <target-url1> [<target-url2> ...]
+```
+
+Create the execution contract before browser research:
+
+```bash
+python3 tools/clis/maggie_design.py <target-url1> [<target-url2> ...] \\
+  --project <project-root> --save
+```
+
+The contract is non-skippable. For every supplied URL, execute every phase in
+`required_phases` in order. `operation` is `create` or `update-regenerate`;
+existing routes, artifacts, or screenshots never change a URL into a skip.
+
+Every URL is a required work item. A URL that already has a route, component,
+or research directory means update/regenerate that target; it must never be
+silently skipped because output already exists.
+
+## Hard boundaries
+
+- Require a completed `.maggie/bootstrap-state.json` and a completed homepage
+  foundation from `maggie-clone`. If either is missing, stop and request it.
+- Reject the origin homepage as a target. Use `maggie-clone` for that job.
+- The target is initially cloned as a complete page. After that first pass,
+  replace its header and footer with the homepage's canonical shared shell.
+  Reuse the homepage component, tokens, navigation, logo, fonts, breakpoints,
+  responsive behavior, accessibility behavior, analytics hooks, and footer
+  links. Do not leave a target-specific shell in the final route.
+- The final page-specific scope is the content between the shared shell:
+  hero, sections, cards, forms, pricing/features, testimonials, FAQs,
+  conversion blocks, and page-specific interactions. Do not copy credentials,
+  private data, tracking IDs, authentication, checkout logic, or proprietary
+  backend behavior.
+- Keep each page in its own route and component namespace. Existing blog,
+  homepage, metadata, sitemap, robots, and Ops routes remain unchanged except
+  for the explicitly requested target route update. Preserve unrelated local
+  changes, but do not convert an existing target route into a no-op.
+
+## Phase 0: Preflight and decision loop
+
+Follow the shared [Maggie decision loop](../../references/decision-loop.md).
+Inspect before editing:
+
+```bash
+python3 tools/clis/maggie.py status <project-root>
+python3 tools/clis/maggie.py doctor <project-root> --require-bootstrap --strict
+python3 tools/clis/maggie_clone.py plan <target-url1> [<target-url2> ...] --project <project-root>
+```
+
+Read and follow the complete `maggie-clone` workflow before proceeding. Verify
+the homepage foundation exists and locate its actual shared shell. The plan
+must state, for every target:
+
+```text
+source URL -> destination route
+homepage shell component/layout -> reused unchanged
+content component namespace -> new isolated namespace
+research and screenshots -> page-scoped directories
+assets -> page-scoped directory; shared assets remain shared
+operation -> create or update/regenerate (never skip)
+files preserved -> all unrelated public/blog/Ops routes
+```
+
+Ask for confirmation of destination routes, page scope, asset reuse, and any
+requested CTA/form behavior before mutation. Interior pages do not silently
+become published posts or sitemap entries. Confirmation authorizes processing
+each listed URL, including an existing route; it does not authorize unrelated
+route changes.
+
+## Phase 1: Complete clone reconnaissance
+
+This phase is the full `maggie-clone` reconnaissance contract applied to the
+interior URL. Do not replace it with a content-only scrape. The target header
+and footer are deliberately captured and implemented in the first pass even
+though they will be replaced later.
+
+Use the available browser/Chrome/Playwright capability. Capture desktop
+1440px, tablet 768px, and mobile 390px. Run the same full reconnaissance
+contract as `maggie-clone`, including the target header and footer. They must
+be captured because the first-pass clone needs complete evidence before the
+shell is reconciled. Record:
+
+- full page topology, including header, footer, sticky layers, and shell
+  transitions;
+- content topology and section order;
+- exact visible copy, links, labels, images, forms, and public states;
+- content-area typography, spacing, colors, borders, radii, shadows, and
+  responsive changes, comparing every value with the homepage tokens;
+- hover, focus, open, loading, empty, error, scroll, tab, and reduced-motion
+  behavior;
+- required assets and their reuse/licensing notes;
+- page metadata and whether the page is a marketing route, conversion route,
+  or actual blog content.
+
+Persist page-scoped evidence before building:
+
+```text
+docs/research/<site-key>/<page-key>/
+  OUTPUT_PLAN.md
+  PAGE_TOPOLOGY.md
+  BEHAVIORS.md
+  DESIGN_TOKENS.md
+  COMPONENT_INVENTORY.md
+  ASSET_MANIFEST.md
+docs/design-references/<site-key>/<page-key>/
+  desktop.png  tablet.png  mobile.png
+```
+
+Every new component spec must initially document the full target component,
+then include a reconciliation note naming the homepage shell source file and
+the final content-only target file and states.
+
+## Phase 2: Build the complete first-pass page
+
+The first pass is a real full clone, not a mock, analysis-only artifact, or
+shell-free approximation. It must contain the target header, target footer,
+page content, responsive behavior, assets, and observed interactions.
+
+Build the target page from the full clone evidence, including its observed
+header, footer, responsive shell, assets, and interactions. This first pass is
+required even when the final result will replace the shell. For an existing
+target route, inspect the current implementation, calculate the update plan,
+and regenerate/reconcile that route; report changed and preserved files.
+
+Do not report `already exists` as a completion state and do not skip browser
+research, asset checks, or verification for an existing URL.
+
+## Phase 3: Reconcile to the homepage shell
+
+After the complete first pass, make the homepage shell the sole source of
+truth. Put page-specific output under an isolated namespace, for example:
+
+```text
+src/components/sites/<site-key>/<page-key>/
+src/pages/<approved-route>.*
+public/sites/<site-key>/<page-key>/
+```
+
+Perform this reconciliation explicitly:
+
+1. Identify the generated target header/footer and the homepage header/footer
+   components, layout wrappers, tokens, assets, and behavior contracts.
+2. Replace the generated target shell with imports/composition from the
+   homepage source of truth. Do not copy its markup into the page namespace.
+3. Remove target-only shell styles, duplicate logo/font/icon assets, and
+   duplicate navigation/footer links from the final page bundle.
+4. Keep the target's route-specific content and interactions inside the
+   content region. A global token or shared-shell change requires explicit
+   approval.
+5. Verify the resulting DOM has one header and one footer, with the target
+   content between them and no hidden duplicate shell.
+
+This is a replacement step after the first pass, never a substitute for it.
+The final implementation must not retain the target header/footer as an
+alternative path or silently fall back to them when the homepage shell exists.
+
+The final page must:
+
+- render inside the exact homepage shell and use its skip link, landmarks,
+  navigation, footer, fonts, and responsive breakpoints;
+- use the existing metadata helper and canonical route;
+- use normal anchors and real form validation;
+- keep marketing pages out of the post sitemap and Article JSON-LD unless they
+  are explicitly mapped to the canonical post contract;
+- preserve analytics consent and server-only API keys;
+- implement observed interactions rather than guessed click-only substitutes.
+
+If a page needs a new global navigation item, footer link, font, token, or
+shared component change, stop, show the impact, and obtain explicit approval.
+
+## Phase 4: Verify
+
+For every target:
+
+1. Run the host build, typecheck/lint, and `maggie doctor --strict` gates.
+2. Verify the exact destination route, homepage route, blog routes, 404,
+   robots, sitemap exclusion/inclusion, canonical metadata, and JSON-LD.
+3. Compare the complete first-pass clone to the target at 1440px, 768px, and
+   390px. Then compare the final page shell to the homepage and compare only
+   the final content region to the target for page fidelity.
+4. Sweep keyboard focus, links, forms, hover, tabs/dialogs, scroll behavior,
+   mobile menu, and reduced-motion behavior.
+5. Run `python3 tools/clis/site_audit.py <local-or-production-url> --json`.
+
+Do not claim exact fidelity when a dynamic state, asset, or authenticated
+target could not be inspected. Report measured differences and limitations.
+
+## Completion report
+
+Report every input URL and its create/update result, target-to-route mappings,
+the full first-pass artifacts, reused homepage shell files, removed duplicate
+shell artifacts, final content-only components, research/screenshots, assets,
+preserved unrelated routes, commands and test results, visual QA status, and
+any requested global changes pending approval. Deployment, publishing, API
+Pull, and rewrite operations are separate actions.

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

@@ -0,0 +1,163 @@
+---
+name: maggie-ops
+description: Build, connect, operate, upgrade, and verify a private Maggie Ops dashboard for blog content, API Pull, sitemap matching, rewrite approvals, reports, and integrations. Use when the user asks for Ops/admin functionality or lifecycle operations rather than public blog pages.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Ops
+
+Manage the private operational surface for a Maggie blog. This skill is
+separate from `maggie-blog-bootstrap`: bootstrap establishes the public blog
+contract, while Maggie Ops establishes the authenticated editor and operations
+contract around it.
+
+Invoke it as:
+
+```text
+/maggie-ops <audit|install|connect|operate|upgrade|verify>
+```
+
+If the user does not name a mode, inspect the project and propose the smallest
+mode that satisfies the request. Do not rebuild the public blog or change its
+framework just to add Ops.
+
+## Required preflight
+
+1. Inspect `.maggie/analysis.json` and `.maggie/bootstrap-state.json`.
+2. Read [`ops-dashboard-contract.md`](../../references/ops-dashboard-contract.md).
+3. Inventory existing private routes, session/auth middleware, role checks,
+   API proxy routes, content tables, audit events, robots, and deployment
+   configuration.
+4. Run the host's existing typecheck, test, and build commands before editing.
+5. State which mode is being run, which routes/API resources it will touch,
+   and whether any operation can consume quota or change production state.
+
+Do not proceed with a production mutation when authentication, ownership,
+role authorization, secret configuration, or rollback information is unknown.
+
+## Modes
+
+### Audit
+
+Produce a gap report against the Ops contract. Check the actual rendered
+screens and server routes, not just documentation. Classify every item as
+implemented, partial, missing, or unverifiable. Include:
+
+- dashboard/list/editor/detail screens and responsive states;
+- session authentication, role authorization, CSRF/input validation, and
+  server-only secret handling;
+- content inventory and identity editing;
+- API Pull status, project context, delivery state, and idempotency;
+- sitemap sources, matching runs, unmatched URLs, matched assets, and history;
+- rewrite queue, preview quota reservation, approval/rejection transitions;
+- reports, GSC/GA4/provider health, audit events, noindex, and robots rules.
+
+### Install
+
+Add or complete the private Ops surface in the existing project. Follow the
+host's UI system and routing conventions, but use the EmDash-style information
+architecture as the baseline:
+
+```text
+/ops                         dashboard and pending actions
+/ops/posts                   paginated content list
+/ops/posts/[id]/edit         validated editor
+/ops/posts/[id]/preview      noindex preview
+/ops/sitemap                 sources, match runs, history, eligibility
+/ops/reports                 SEO, GEO, visibility, analytics
+/ops/settings/integrations   Maggie API and provider health
+/ops/operations              calendar, tasks, media, redirects, agency work
+```
+
+Use a clean list → detail/editor journey, outlined cards, clear status
+chips, predictable spacing, explicit loading/empty/error states, and a
+desktop/mobile layout consistent with the reference admin product. Do not
+ship a mock table whose buttons do not reach a server route.
+
+### Connect
+
+Wire the dashboard to real backend contracts. Prefer the first-party Maggie
+API or a narrowly scoped server-side Ops bridge. The browser may call only
+the project's authenticated proxy; Maggie/API secrets must remain server-side.
+
+At minimum, verify real readbacks for:
+
+- content assets and versions/identity;
+- pull runs and delivery status;
+- sitemap sources and matching runs;
+- rewrite jobs and action state;
+- project context and CTA/settings data.
+
+Every mutation must validate the session, role, resource ownership/project
+scope, input schema, legal state transition, and idempotency/correlation key.
+Record actor, timestamp, previous state, next state, reason, and result.
+
+### Operate
+
+Use the dashboard or API to perform an explicitly requested operation. Show an
+impact preview before bulk or quota-consuming work. Keep these actions
+separate:
+
+```text
+read status → inspect impact → run/mutate → read back result → record audit
+```
+
+Sitemap matching must report total sitemap documents, total URLs, matched
+posts, already matched/queued posts, not-tracked URLs, newly eligible posts,
+and matching time. Rewrite preview reserves quota; approval is a separate
+human action. Never silently publish, overwrite content, or enqueue a whole
+site because a list endpoint returned data.
+
+### Upgrade
+
+Upgrade an existing Ops installation without losing local work:
+
+1. read the installed version and local modifications;
+2. compare the target contract, frontend routes, backend routes, and schema;
+3. apply additive changes first and write migrations only when required;
+4. preserve local UI customizations unless the user explicitly requests a
+   replacement;
+5. run read-only verification before enabling new mutations;
+6. report changed, preserved, conflicting, and deprecated files.
+
+For an installed Maggie package, use:
+
+```bash
+npx @topy-ai/maggie update --project .
+```
+
+Use `--force` only after the user explicitly approves replacing locally
+modified managed files. An npm skill update does not automatically deploy the
+dashboard or migrate a production database.
+
+### Verify
+
+Run the host build/test/typecheck gates and verify the actual private routes
+with an authenticated session. Test at least:
+
+- unauthenticated and non-admin denial;
+- list, detail, editor save, and validation errors;
+- API Pull readback and stale/error states;
+- sitemap matching with zero, partial, and complete matches;
+- rewrite preview, approval, rejection, retry, and quota failure;
+- refresh/idempotency behavior and audit records;
+- `noindex`, robots blocking, and exclusion from public sitemap;
+- desktop and mobile layout against the EmDash-style design baseline.
+
+Do not claim an API is connected because a frontend button rendered. Show the
+endpoint, response status, persisted state, and verification command.
+
+## Stop conditions
+
+Stop before a write when the user has not authorized it, the project scope is
+ambiguous, the endpoint is only proposed/documented rather than reachable,
+the admin identity cannot be verified, the operation would expose a secret,
+or a migration/rollback plan is missing.
+
+## Completion report
+
+Report the mode, screens and endpoints implemented, authentication/ownership
+boundary, quota impact, database/migration status, audit behavior, preserved
+local changes, commands and live/readback checks, remaining gaps, and whether
+deployment was actually performed.

package/bundled-skills/maggie-ops/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Maggie Ops"
+  short_description: "Build and operate Maggie blog admin workflows"
+  default_prompt: "Use $maggie-ops to audit and connect this project's private blog operations dashboard."

package/bundled-skills/maggie-project-context/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Maggie Project Context
 
+For changes, follow the shared [Maggie decision loop](../../references/decision-loop.md): inspect the project, propose mappings, checkpoint answers, and confirm before writing context or calling external APIs.
+
 Use the authenticated AI CMO Project as the source of truth for brand
 positioning, audience, voice, site URL, and conversion CTAs.
 

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

@@ -7,6 +7,8 @@ metadata:
 
 # Maggie SEO and GEO
 
+For state-changing audits, rewrites, or publishing, follow the shared [Maggie decision loop](../../references/decision-loop.md) and confirm policy and scope before external writes.
+
 Treat SEO and GEO as one measurable content system: people-first content,
 technical accessibility, extractable structure, evidence, authority, brand
 voice, CTA alignment, and observed search/AI outcomes.

package/bundled-skills/maggie-social-share/SKILL.md

@@ -7,6 +7,8 @@ metadata:
 
 # Maggie Social Share
 
+For scheduling or publishing actions, follow the shared [Maggie decision loop](../../references/decision-loop.md): inspect, propose channels and copy, checkpoint answers, then confirm.
+
 Social Share is a distribution layer downstream of the same AI CMO Project,
 brand voice, CTA, canonical URL, content asset, and approval state used by SEO
 and GEO. It is not a second content source of truth.

package/bundled-tools/clis/maggie.py

@@ -397,6 +397,83 @@ def command_status(args: argparse.Namespace) -> int:
     return 0 if state.get("status") == "completed" else 1
 
 
+BOOTSTRAP_QUESTIONS = [
+    ("framework", "Which framework should Maggie preserve?", ["detected", "astro", "nextjs", "eleventy", "custom"]),
+    ("language", "Which implementation language should the blog use?", ["detected", "typescript", "javascript"]),
+    ("content_language", "What is the default content language?", ["detected", "en", "zh-TW", "zh-CN", "multilingual"]),
+    ("ui_system", "Which UI system should the blog use?", ["preserve", "tailwind", "css-modules", "plain-css"]),
+    ("icon_set", "Which icon set should the blog use?", ["preserve", "heroicons", "lucide", "none"]),
+    ("font", "Which typography choice should the blog use?", ["preserve", "system", "custom"]),
+    ("database", "Which database boundary should the blog use?", ["preserve", "sqlite", "postgres", "mysql"]),
+    ("content_source", "Where should posts be stored?", ["preserve", "local-content", "database", "api-pull"]),
+    ("posts_per_page", "How many posts should appear on each blog page?", ["9", "12", "6", "custom"]),
+    ("grid_columns", "How many columns should the default post grid use?", ["3", "2", "4", "custom"]),
+    ("ops_dashboard", "Should the project add the private Maggie Ops dashboard after bootstrap?", ["disabled", "enabled"]),
+]
+
+
+def question_default(key: str, analysis: dict) -> str:
+    detected = analysis.get(key, {}).get("value") if isinstance(analysis.get(key), dict) else None
+    if key == "posts_per_page": return "9"
+    if key == "grid_columns": return "3"
+    if key == "ops_dashboard": return "disabled"
+    return detected or {"ui_system": "preserve-or-tailwind", "icon_set": "preserve-or-heroicons", "font": "preserve-or-system", "database": "preserve-or-sqlite"}.get(key, "detected")
+
+
+def interview_choices(key: str, choices: list[str], current: str) -> str:
+    print(f"\n{key}: {current}")
+    for index, choice in enumerate(choices, 1):
+        marker = " (recommended)" if choice == current else ""
+        print(f"  {index}. {choice}{marker}")
+    while True:
+        answer = input("Select a number, or type a value: ").strip()
+        if answer.isdigit() and 1 <= int(answer) <= len(choices):
+            return choices[int(answer) - 1]
+        if answer in choices or (key in {"posts_per_page", "grid_columns"} and answer.isdigit()):
+            return answer
+        print("Please choose one of the listed options.")
+
+
+def command_bootstrap_interview(args: argparse.Namespace) -> int:
+    root = Path(args.project).resolve()
+    analysis = detect(root)
+    answers: dict[str, str] = {}
+    if args.answers_file:
+        try:
+            loaded = json.loads(Path(args.answers_file).read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError) as error:
+            raise RuntimeError(f"invalid answers file: {args.answers_file}") from error
+        if not isinstance(loaded, dict): raise RuntimeError("answers file must contain a JSON object")
+        answers.update({str(key): str(value) for key, value in loaded.items()})
+    for key, question, choices in BOOTSTRAP_QUESTIONS:
+        value = answers.get(key, question_default(key, analysis))
+        if not args.non_interactive and key not in answers:
+            print(f"\n{question}")
+            value = interview_choices(key, choices, value)
+        elif value not in choices and key not in {"posts_per_page", "grid_columns"}:
+            raise RuntimeError(f"invalid value for {key}: {value}")
+        answers[key] = value
+        checkpoint = root / STATE_DIR / "bootstrap-interview.json"
+        checkpoint.parent.mkdir(parents=True, exist_ok=True)
+        checkpoint.write_text(json.dumps({"status": "in_progress", "answers": answers, "updated_at": utc_now()}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print("\nBootstrap proposal")
+    print(json.dumps(answers, indent=2, ensure_ascii=False))
+    if not args.confirm:
+        if args.non_interactive:
+            print("CONFIRMATION_REQUIRED: rerun with --confirm after reviewing the proposal.", file=sys.stderr)
+            return 2
+        if input("Apply these selections and generate the bootstrap contract? [y/N] ").strip().lower() not in {"y", "yes"}:
+            print("Bootstrap remains pending; the checkpoint was saved.")
+            return 0
+    complete_args = argparse.Namespace(
+        project=str(root), confirm=["foundation", "experience", "data", "publishing"],
+        framework=answers["framework"], language=answers["language"], content_language=answers["content_language"],
+        ui_system=answers["ui_system"], icon_set=answers["icon_set"], font=answers["font"], database=answers["database"], content_source=answers["content_source"],
+        posts_per_page=int(answers["posts_per_page"]), grid_columns=int(answers["grid_columns"]), ops_dashboard=answers["ops_dashboard"] == "enabled",
+    )
+    return command_complete(complete_args)
+
+
 def command_complete(args: argparse.Namespace) -> int:
     root = Path(args.project).resolve()
     required = {"foundation", "experience", "data", "publishing"}
@@ -406,7 +483,7 @@ def command_complete(args: argparse.Namespace) -> int:
         print("Confirmation required for: " + ", ".join(sorted(missing)), file=sys.stderr)
         return 2
     state = {
-        "schema_version": "1.0",
+        "schema_version": "1.1",
         "status": "completed",
         "completed_at": utc_now(),
         "confirmed": {name: True for name in sorted(required)},
@@ -419,6 +496,9 @@ def command_complete(args: argparse.Namespace) -> int:
             "font": args.font,
             "database": args.database,
             "content_source": args.content_source,
+            "posts_per_page": args.posts_per_page,
+            "grid_columns": args.grid_columns,
+            "ops_dashboard": args.ops_dashboard,
         },
     }
     path = state_path(root)
@@ -427,8 +507,8 @@ def command_complete(args: argparse.Namespace) -> int:
     contracts = {
         "project.json": {"schema_version": "1.0", "framework": args.framework, "language": args.language, "database": args.database, "content_source": args.content_source},
         "decisions.json": state["decisions"],
-        "schema.json": {"post_required": ["id", "slug", "title", "content", "status", "canonicalUrl", "publishedAt", "updatedAt", "author"], "public_status": "published"},
-        "routes.json": {"public": ["/about", "/blog", "/blog/[slug]", "/topics", "/authors/[slug]", "/sitemap.xml", "/robots.txt"], "ops": ["/ops", "/ops/posts", "/ops/operations", "/ops/wordpress", "/api/ops/bulk", "/api/ops/agency", "/api/ops/entities", "/api/ops/migrations/[id]/resume", "/api/ops/wordpress/migration-plan", "/api/ops/pull/project-context", "/api/ops/pull/sync-updates", "/api/ops/sitemap/matching-history", "/api/ops/content-tracking/report-state", "/api/ops/content-tracking/report-state/batch", "/api/ops/playbooks/[id]/run"]},
+        "schema.json": {"post_required": ["id", "slug", "title", "content", "status", "canonicalUrl", "publishedAt", "updatedAt", "author"], "public_status": "published", "posts_per_page": args.posts_per_page, "grid_columns": args.grid_columns, "grid_default": f"{args.grid_columns}x{args.posts_per_page // args.grid_columns}"},
+        "routes.json": {"public": ["/about", "/blog", "/blog/page/[page]", "/blog/[slug]", "/topics", "/topics/[slug]", "/authors/[slug]", "/sitemap.xml", "/robots.txt"], "ops": ["/ops", "/ops/posts", "/ops/posts/new", "/ops/posts/[id]/edit", "/ops/posts/[id]/preview", "/ops/topics", "/ops/sitemap", "/ops/reports", "/ops/settings/site", "/ops/settings/integrations", "/ops/operations", "/ops/wordpress", "/api/ops/summary", "/api/ops/posts", "/api/ops/topics", "/api/ops/bulk", "/api/ops/agency", "/api/ops/entities", "/api/ops/migrations/import", "/api/ops/migrations/[id]/resume", "/api/ops/wordpress/migration-plan", "/api/ops/pull/project-context", "/api/ops/pull/sync", "/api/ops/pull/sync-updates", "/api/ops/sitemap/matching-history", "/api/ops/sitemap/match", "/api/ops/sitemap/auto-detect", "/api/ops/rewrite/queue", "/api/ops/rewrite/history", "/api/ops/rewrite/policy", "/api/ops/content-tracking/report-state", "/api/ops/content-tracking/report-state/batch", "/api/ops/reports", "/api/ops/playbooks/[id]/run"]},
         "integrations.json": {"ai_cmo": "server-only", "gsc": "server-only", "ga4": "consent-aware"},
         "migration.json": {"supported": ["wordpress-rest", "wxr", "csv", "json", "sitemap", "media-archive"], "idempotency": "source-id-and-checksum", "default_conflict": "manual", "sync_modes": ["all", "new", "modified"], "deleted_policy": "archive"},
     }
@@ -511,10 +591,12 @@ def command_doctor(args: argparse.Namespace) -> int:
             "faq_surface": "faq" in text.lower(),
             "cta_surface": "cta" in text.lower(),
             "pagination_surface": "pagination" in text.lower() or "page_size" in text.lower(),
+            "nine_posts_three_columns": bool(re.search(r"(?:postsPerPage|posts_per_page|PUBLIC_POSTS_PER_PAGE)[^\n]{0,80}(?:9|default.?9)", text, re.IGNORECASE)) and ("grid" in text.lower() or "grid_columns" in text.lower()),
             "eeat_authorship": "author" in text.lower() and ("credential" in text.lower() or "organisation" in text.lower() or "organization" in text.lower()),
             "modified_date": "dateModified" in text or "updatedAt" in text,
             "ops_surface": any("ops" in path for path in paths),
             "ops_authentication": "auth" in text.lower() or "middleware" in text.lower(),
+            "ops_api_surface": all(token in text for token in ("/api/ops/summary", "/api/ops/posts", "/api/ops/sitemap", "/api/ops/reports")),
             "integration_config": "AI_CMO_API_KEY" in text or "measurement_id" in text.lower() or "verification" in text.lower(),
             "bootstrap_contract": all((root / STATE_DIR / filename).exists() for filename in ("project.json", "decisions.json", "schema.json", "routes.json", "integrations.json", "migration.json")),
             "scheduled_publication_state": "scheduled" in text.lower() and "published" in text.lower(),
@@ -610,9 +692,18 @@ def parser() -> argparse.ArgumentParser:
     bootstrap_sub = bootstrap.add_subparsers(dest="bootstrap_command", required=True)
     complete = bootstrap_sub.add_parser("complete", help="write state after explicit user confirmations")
     complete.add_argument("project", nargs="?", default=".")
+    interview = bootstrap_sub.add_parser("interview", help="walk through one decision at a time and confirm the proposal")
+    interview.add_argument("project", nargs="?", default=".")
+    interview.add_argument("--answers-file", help="JSON answers for headless/CI use")
+    interview.add_argument("--non-interactive", action="store_true", help="do not prompt; requires --answers-file and --confirm")
+    interview.add_argument("--confirm", action="store_true", help="apply the reviewed proposal")
+    interview.set_defaults(func=command_bootstrap_interview)
     complete.add_argument("--confirm", action="append", choices=["foundation", "experience", "data", "publishing"], required=True)
     for name, default in (("framework", "detected"), ("language", "detected"), ("content-language", "confirmed"), ("ui-system", "preserve-or-tailwind"), ("icon-set", "preserve-or-heroicons"), ("font", "preserve-or-system"), ("database", "preserve-or-sqlite"), ("content-source", "confirmed")):
         complete.add_argument("--" + name, dest=name.replace("-", "_"), default=default)
+    complete.add_argument("--posts-per-page", type=int, default=9)
+    complete.add_argument("--grid-columns", type=int, default=3)
+    complete.add_argument("--ops-dashboard", action=argparse.BooleanOptionalAction, default=False)
     complete.set_defaults(func=command_complete)
     generate = sub.add_parser("generate", help="generate stable contract or fixture files")
     generate.add_argument("target", choices=["contract", "fixture", "post", "topic", "author", "migration", "seo", "ops-page"])

package/bundled-tools/clis/maggie_design.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Create a non-skippable execution contract for Maggie interior-page design.
+
+This command does not fetch a site or edit the host project.  It gives an
+agent a machine-readable checklist so an interior URL cannot accidentally be
+treated as a content-only clone or skipped because output already exists.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+from urllib.parse import urlsplit
+
+from maggie_clone import normalized, plan
+
+
+PHASES = [
+    {
+        "id": "preflight",
+        "required": [
+            "bootstrap-state",
+            "homepage-shell",
+            "host-inventory",
+            "baseline-validation",
+        ],
+    },
+    {
+        "id": "full-research",
+        "required": [
+            "desktop-1440",
+            "tablet-768",
+            "mobile-390",
+            "target-header",
+            "target-footer",
+            "assets",
+            "interactions",
+            "component-specs",
+        ],
+    },
+    {
+        "id": "full-first-pass",
+        "required": [
+            "target-header",
+            "target-footer",
+            "page-content",
+            "responsive-behavior",
+            "target-interactions",
+        ],
+    },
+    {
+        "id": "shell-reconciliation",
+        "required": [
+            "replace-target-header-with-homepage-shell",
+            "replace-target-footer-with-homepage-shell",
+            "remove-duplicate-shell-assets-and-styles",
+            "one-header-and-one-footer",
+        ],
+    },
+    {
+        "id": "verification",
+        "required": [
+            "build-typecheck-lint",
+            "route-and-404",
+            "metadata-robots-sitemap-jsonld",
+            "shell-regression",
+            "desktop-tablet-mobile-comparison",
+            "site-audit",
+        ],
+    },
+]
+
+
+def existing_evidence(project: Path, target: dict[str, str]) -> list[str]:
+    """Return evidence paths without deciding that any work can be skipped."""
+
+    candidates = [
+        Path(target["artifact_root"]),
+        Path(target["screenshot_root"]),
+        Path(target["component_root"]),
+        Path(target["asset_root"]),
+    ]
+    route = target["destination_route"].strip("/") or "root"
+    for base in (project / "src" / "app", project / "src" / "pages"):
+        if base.exists():
+            candidates.extend(
+                path
+                for path in base.rglob("*")
+                if path.is_file() and route.lower() in str(path).lower()
+            )
+    return sorted({str(path) for path in candidates if path.exists()})
+
+
+def design_plan(urls: list[str], project: Path) -> dict[str, object]:
+    targets = []
+    for target in plan(urls, project):
+        parsed = urlsplit(target["source_url"])
+        if parsed.path in {"", "/"}:
+            raise ValueError(
+                f"homepage URL is not valid for maggie-design: {target['source_url']} "
+                "(use maggie-clone)"
+            )
+        evidence = existing_evidence(project, target)
+        targets.append(
+            {
+                **target,
+                "operation": "update-regenerate" if evidence else "create",
+                "input_url_is_required_work_item": True,
+                "skip_allowed": False,
+                "existing_evidence": evidence,
+                "required_phases": PHASES,
+                "shell_source_of_truth": {
+                    "must_resolve_before_build": True,
+                    "must_be_reused_in_final_page": True,
+                    "target_shell_allowed_in_final_page": False,
+                },
+            }
+        )
+    return {
+        "workflow": "maggie-design",
+        "contract_version": "1.0",
+        "project_root": str(project),
+        "non_skippable": True,
+        "rule": "Every supplied URL is processed through all required phases; existing output changes the operation to update-regenerate, never skip.",
+        "targets": targets,
+    }
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("urls", nargs="+", help="authorized interior-page URLs")
+    parser.add_argument("--project", type=Path, default=Path.cwd())
+    parser.add_argument("--save", action="store_true", help="save .maggie/design-plan.json")
+    args = parser.parse_args()
+    try:
+        project = args.project.resolve()
+        result = design_plan(args.urls, project)
+    except ValueError as error:
+        parser.error(str(error))
+    encoded = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    if args.save:
+        destination = project / ".maggie" / "design-plan.json"
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        destination.write_text(encoded, encoding="utf-8")
+        result["saved_to"] = str(destination)
+        encoded = json.dumps(result, indent=2, ensure_ascii=False) + "\n"
+    print(encoded, end="")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/blog-data-contract.md

@@ -56,6 +56,14 @@ with the canonical post source enum while remaining unique and rerunnable.
 This is the default for a new, small single-instance project. Use the same
 logical fields with Postgres or another engine when the deployment requires it.
 
+## Default listing configuration
+
+The default blog index is a 3-column grid with 9 posts per page (3×3). Store
+this as typed configuration (`postsPerPage: 9`, `gridColumns: 3`) rather than
+scattering literals through templates. Users may change it later through site
+settings; pagination, canonical URLs, sitemap eligibility, and audits must use
+the same configured value.
+
 ```sql
 CREATE TABLE posts (
   id TEXT PRIMARY KEY,

package/references/decision-loop.md

@@ -0,0 +1,25 @@
+# Maggie Decision Loop
+
+Every state-changing Maggie skill follows this protocol:
+
+1. Inspect first and label evidence `Detected`, `Likely`, `Missing`, or
+   `Unknown`.
+2. Propose one recommended choice and up to two alternatives.
+3. Ask one focused question at a time, showing the selection, evidence,
+   affected files, and risks.
+4. Record each answer in `.maggie/decisions.json` or a skill checkpoint.
+5. Summarize all selections and require explicit final confirmation before
+   mutation or external writes.
+6. If an earlier answer changes, recalculate dependent choices and confirm
+   again; never silently overwrite a confirmed decision.
+
+Headless runs use an answers JSON file plus a separate `--confirm` flag. They
+must follow the same sequence and may not bypass final confirmation.
+
+```bash
+python3 tools/clis/maggie.py bootstrap interview .
+python3 tools/clis/maggie.py bootstrap interview . --answers-file .maggie/answers.json --non-interactive --confirm
+```
+
+Use this loop for framework changes, clone routes, rewrite policy, publishing,
+integrations, migrations, and deployment.

package/references/ops-dashboard-contract.md

@@ -0,0 +1,41 @@
+# Maggie Ops Dashboard Contract
+
+Bootstrap must implement a private, authenticated Ops application before the
+blog is complete. Visual design is flexible; the operational surface and
+server-side boundaries are fixed.
+
+## Required screens
+
+```text
+/ops                         health summary and pending actions
+/ops/posts                   inventory, filters, bulk preview/apply
+/ops/posts/new               create draft
+/ops/posts/[id]/edit         validated editor and metadata preview
+/ops/posts/[id]/preview      noindex preview
+/ops/topics                  topics and FAQs
+/ops/sitemap                 sources, matching runs, unmatched and eligible counts
+/ops/reports                 SEO, content quality, visibility, analytics
+/ops/settings/site           origin, locale, timezone and defaults
+/ops/settings/integrations   Maggie API, GSC, GA4 and provider health
+/ops/operations              calendar, tasks, media, redirects and agency work
+/ops/wordpress               migration preview, apply, validate and resume
+```
+
+Required server routes include `/api/ops/summary`, `/api/ops/posts`,
+`/api/ops/topics`, `/api/ops/sitemap/{runs,match,auto-detect}`,
+`/api/ops/reports`, `/api/ops/pull/{project-context,sync,sync-updates}`,
+`/api/ops/rewrite/{queue,history,policy}`, and content-tracking report-state.
+
+Every request enforces session authentication, role authorization, input
+validation, and state-transition validation. Keys never reach browser code.
+Mutations show an impact preview where applicable and create an audit event
+with actor, timestamp, previous state, next state, reason, and an
+idempotency/correlation key. Ops pages are `noindex`, excluded from public
+sitemaps, and blocked in robots rules.
+
+## Bootstrap acceptance
+
+The bootstrap manifest contains the complete Ops route set, an enabled
+dashboard decision, and a verification command. `maggie doctor --strict
+--require-bootstrap` fails when the host project has no Ops UI, Ops API, or
+authentication boundary.