@topy-ai/maggie 0.1.1 → 0.1.2

package/bin/maggie.js

@@ -15,6 +15,7 @@ const SKILL_NAMES = [
   "maggie-blog-bootstrap",
   "maggie-clone",
   "maggie-design",
+  "maggie-ops",
   "maggie-deployment",
   "maggie-project-context",
   "maggie-seo-geo",

package/bundled-skills/README.md

@@ -7,7 +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` | Build authorized interior pages using the homepage header/footer as the shared shell | browser MCP, clone planner CLI, completed Maggie homepage |
+| `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

@@ -161,13 +161,10 @@ separate final confirmation. Use the following groups for the conversation:
 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.
+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
@@ -224,9 +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.
-- 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.
+- 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

@@ -39,9 +39,12 @@ variant. If the user supplies an interior page, stop and route the request to
 - 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 homepage 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.

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

@@ -1,15 +1,18 @@
 ---
 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.
+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.0.0
+  version: 1.1.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.
+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:
 
@@ -17,22 +20,40 @@ Invoke it as:
 /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.
-- Treat the homepage header and footer as immutable shared layout boundaries.
-  Reuse their component, tokens, navigation, logo, fonts, breakpoints,
+- 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 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.
+  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 unless
-  the user explicitly approves a shared-shell change.
+  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
 
@@ -45,8 +66,9 @@ 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:
+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
@@ -54,20 +76,31 @@ 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
+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.
+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
 
-## Phase 1: Content-area 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. Inspect the target with the global
-header and footer excluded from the page scope after verifying their local
-equivalent. Record:
+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
@@ -92,13 +125,29 @@ 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.
+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 content area
+## Phase 2: Build the complete first-pass page
 
-Build the page using the host framework and the homepage's shared layout
-component. Put page-specific output under an isolated namespace, for example:
+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>/
@@ -106,7 +155,25 @@ src/pages/<approved-route>.*
 public/sites/<site-key>/<page-key>/
 ```
 
-The page must:
+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;
@@ -120,16 +187,16 @@ The page must:
 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
+## 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 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.
+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`.
@@ -139,8 +206,9 @@ 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.
+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-tools/clis/maggie.py

@@ -408,7 +408,7 @@ BOOTSTRAP_QUESTIONS = [
     ("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"]),
+    ("ops_dashboard", "Should the project add the private Maggie Ops dashboard after bootstrap?", ["disabled", "enabled"]),
 ]
 
 
@@ -416,7 +416,7 @@ 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"
+    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")
 
 
@@ -703,7 +703,7 @@ def parser() -> argparse.ArgumentParser:
         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.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.1",
+  "version": "0.1.2",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",