@topy-ai/maggie 0.1.0 → 0.1.1

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,11 @@ 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-deployment",
   "maggie-project-context",
   "maggie-seo-geo",
@@ -24,6 +27,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 +81,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 +136,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 +204,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,7 @@ 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` | Build authorized interior pages using the homepage header/footer as the shared shell | browser MCP, clone planner CLI, completed Maggie homepage |
 | `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,14 @@ 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:** enable the complete private Maggie Ops dashboard, including
+   content inventory/editor/preview, topics and FAQs, sitemap matching and
+   history, rewrite/API Pull controls, reports, settings/integrations,
+   migrations, calendar, media, redirects, tasks, agency scope, audit events,
+   authentication, role checks, and noindex/robots protection. This is enabled
+   by default and is required for a completed bootstrap unless the user
+   explicitly chooses a different operating model.
+
 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 +188,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 +204,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 +224,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.
+- a complete private Ops dashboard following
+  [`ops-dashboard-contract.md`](../../references/ops-dashboard-contract.md),
+  backed by the same repository as public reads; do not ship a mock-only Ops UI.
 
 ### 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,12 @@ 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,
+- The clone is an additive homepage operation. Do not overwrite an existing route,
   component namespace, asset namespace, or research artifact without explicit
   approval.
+- 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 +67,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 +82,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 +191,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 +213,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,146 @@
+---
+name: maggie-design
+description: Design or recreate authorized interior pages inside a Maggie blog while reusing the cloned homepage header and footer exactly. Use with /maggie-design plus one or more target URLs for pricing, about, feature, landing, or other non-homepage pages.
+metadata:
+  version: 1.0.0
+---
+
+# Maggie Design
+
+Create authorized interior pages inside an existing Maggie project. This is
+the page-design companion to `maggie-clone`: the homepage establishes the
+global shell, and this skill designs only the content area between that shell.
+
+Invoke it as:
+
+```text
+/maggie-design <target-url1> [<target-url2> ...]
+```
+
+## 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.
+- Treat the homepage header and footer as immutable shared layout boundaries.
+  Reuse their component, tokens, navigation, logo, fonts, breakpoints,
+  responsive behavior, accessibility behavior, analytics hooks, and footer
+  links. Do not restyle, duplicate, or fork them for an interior page.
+- Clone only the target's content region: 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 unless
+  the user explicitly approves a shared-shell change.
+
+## 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>
+```
+
+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
+files preserved -> all existing 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.
+
+## Phase 1: Content-area reconnaissance
+
+Use the available browser/Chrome/Playwright capability. Capture desktop
+1440px, tablet 768px, and mobile 390px. Inspect the target with the global
+header and footer excluded from the page scope after verifying their local
+equivalent. Record:
+
+- 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 explicitly say: `header: reuse homepage`,
+`footer: reuse homepage`, and list the content-only target file and states.
+
+## Phase 2: Build the content area
+
+Build the page using the host framework and the homepage's shared layout
+component. 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>/
+```
+
+The 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 3: 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 local and target screenshots at 1440px, 768px, and 390px. Compare
+   the header/footer separately to prove they are the same local components,
+   then compare only the content region 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 target-to-route mappings, the reused homepage shell files, new
+content-only components, research/screenshots, assets, preserved routes,
+commands and test results, visual QA status, and any requested global changes
+that remain pending approval. Deployment, publishing, API Pull, and rewrite
+operations are separate actions.

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 bootstrap implement the complete private Maggie Ops dashboard?", ["enabled", "disabled"]),
+]
+
+
+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 "enabled"
+    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=True)
     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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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.