@topy-ai/maggie 0.2.9 → 0.5.0

package/README.md

@@ -264,12 +264,49 @@ python3 tools/clis/maggie_design.py rebrand \
 | `maggie-memory` | Persist confirmed preferences, conventions, lessons, and errors |
 | `maggie-content-localization` | Manage locale-aware translation, review, provenance, stale state, and publication gates |
 | `maggie-feedback` | Collect redacted feedback drafts and explicitly submit them to the NoBlox feedback endpoint |
+| `maggie-auth-reference` | Generate and validate traditional email/password auth with secure server-side sessions |
+| `maggie-blog` | Run a provider-neutral blog lifecycle with stable identity, topics, feeds, settings, and rollback |
+
+`maggie-design` can initialize native blog and service UI plans from a local,
+read-only structural reference:
+
+```bash
+maggie design reference-ui --project . --reference /path/to/reference \
+  --surface blog,service --confirm
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> --confirm
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> --confirm
+maggie design validate-ui --project . \
+  --plan .maggie/design/content-ui/blog/init-<id>/plan.json \
+  --rendered-dir .maggie/design/content-ui/blog/init-<id>/screenshots --confirm
+```
+
+This reuses the host project's homepage shell and `DESIGN.md`; it does not
+copy reference branding, source code, private data, or provider facts.
 
 The remaining installable skills are `maggie-blog-bootstrap`, `maggie-dash`,
 `maggie-clone`, `maggie-clone-to-template`, `maggie-marketplace`,
 `maggie-template`, `maggie-design`, `maggie-ops`, `maggie-deployment`,
 `maggie-project-context`, `maggie-social-share`, and `maggie-memory`.
 
+The package also includes `maggie-auth-reference` and `maggie-blog`. Use the
+stable commands below after installation:
+
+```bash
+maggie auth reference --project . --confirm
+maggie auth check --project . --production
+maggie design author --project . --route /about --purpose "Explain our approach" --audience "Visitors" --confirm
+maggie blog init --project . --confirm
+maggie blog ingest --project . --source local --input content/posts.json --confirm
+maggie blog validate --project .
+maggie blog sitemap --project .
+```
+
+Blog imports are idempotent and draft-first. Published slugs remain stable;
+public feeds exclude drafts, and `maggie blog rollback --confirm` restores the
+latest local content backup.
+
 List every installed skill and command:
 
 ```bash

package/bin/maggie.js

@@ -34,6 +34,8 @@ const SKILL_NAMES = [
   "maggie-memory",
   "maggie-content-localization",
   "maggie-feedback",
+  "maggie-auth-reference",
+  "maggie-blog",
 ];
 const RETIRED_PATHS = [
   ".agents/skills/maggie-emdash",
@@ -83,6 +85,13 @@ Usage:
   maggie clone run <homepage-url> --run-id <id>
   maggie clone status --run-id <id>
   maggie design run <target-url> --clone-run <id>
+  maggie design reference-ui --project PATH --reference PATH --surface blog,service --confirm
+  maggie design init --project PATH --surface blog|service --reference-run PATH --confirm
+  maggie design validate-ui --project PATH --plan PATH --rendered-dir PATH --confirm
+  maggie design author --project PATH --route /about --purpose TEXT --audience TEXT --confirm
+  maggie auth reference --project PATH --confirm
+  maggie auth check --project PATH [--production]
+  maggie blog init|inspect|ingest|validate|publish|sitemap|settings|rollback --project PATH
   maggie design status <job-id>
   maggie service import <provider-url> --project PATH
   maggie service sync <provider-url> --project PATH
@@ -206,7 +215,7 @@ function install(args) {
     copyIfMissing(join(DESIGN_ROOT, "SPA-DESIGN.md"), join(root, ".maggie", "design-reference", "SPA-DESIGN.md"));
   }
   if (existsSync(MARKETPLACE_ROOT)) copyIfMissing(MARKETPLACE_ROOT, join(root, "marketplace"));
-  if (existsSync(join(CONTRACTS_ROOT, "maggiedash"))) copyIfMissing(join(CONTRACTS_ROOT, "maggiedash"), join(root, "contracts", "maggiedash"));
+  if (existsSync(CONTRACTS_ROOT)) copyIfMissing(CONTRACTS_ROOT, join(root, "contracts"));
   if (existsSync(join(TEMPLATES_ROOT, "maggiedash"))) copyIfMissing(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"));
   const stateDir = join(root, ".maggie");
   mkdirSync(stateDir, { recursive: true });
@@ -240,7 +249,7 @@ function update(args) {
     updated += syncTree(DESIGN_ROOT, join(root, ".maggie", "design-reference"), force);
   }
   if (existsSync(MARKETPLACE_ROOT) && existsSync(join(root, "marketplace"))) updated += syncTree(MARKETPLACE_ROOT, join(root, "marketplace"), force);
-  if (existsSync(join(CONTRACTS_ROOT, "maggiedash")) && existsSync(join(root, "contracts", "maggiedash"))) updated += syncTree(join(CONTRACTS_ROOT, "maggiedash"), join(root, "contracts", "maggiedash"), force);
+  if (existsSync(CONTRACTS_ROOT) && existsSync(join(root, "contracts"))) updated += syncTree(CONTRACTS_ROOT, join(root, "contracts"), force);
   if (existsSync(join(TEMPLATES_ROOT, "maggiedash")) && existsSync(join(root, "templates", "maggiedash"))) updated += syncTree(join(TEMPLATES_ROOT, "maggiedash"), join(root, "templates", "maggiedash"), force);
   const stateDir = join(root, STATE_DIR);
   mkdirSync(stateDir, { recursive: true });
@@ -346,6 +355,8 @@ try {
   else if (command === "clone") workflowCli("maggie_clone.py", args);
   else if (command === "clone-to-template") workflowCli("maggie_clone_to_template.py", args);
   else if (command === "design") workflowCli("maggie_design.py", args);
+  else if (command === "auth") workflowCli("maggie_auth.py", args);
+  else if (command === "blog") workflowCli("maggie_blog.py", args);
   else if (command === "service") service(args);
   else if (command === "ops") workflowCli("maggie_ops.py", args);
   else if (command === "deployment") workflowCli("maggie_deployment.py", args);

package/bundled-contracts/maggie-auth/README.md

@@ -0,0 +1,8 @@
+# Maggie Auth Reference Contract
+
+Provider-neutral traditional email/password authentication reference. This
+contract intentionally excludes passkeys, WebAuthn, passwordless login, and
+vendor-specific browser auth.
+
+The host application owns persistence and HTTP handlers. The reference CLI
+only writes a reviewable contract and validates production prerequisites.

package/bundled-contracts/maggie-auth/auth-reference-v1.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-auth-reference.v1",
+  "type": "object",
+  "required": ["schemaVersion", "passwordPolicy", "sessionPolicy", "tables"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-auth-reference.v1" },
+    "passwordPolicy": {
+      "type": "object",
+      "required": ["algorithm", "minimumLength"],
+      "properties": { "algorithm": { "const": "argon2id" }, "minimumLength": { "type": "integer", "minimum": 12 } }
+    },
+    "sessionPolicy": {
+      "type": "object",
+      "required": ["serverSide", "httpOnly", "sameSite"],
+      "properties": { "serverSide": { "const": true }, "httpOnly": { "const": true }, "sameSite": { "enum": ["lax", "strict"] } }
+    },
+    "tables": { "type": "array", "items": { "type": "string" }, "minItems": 3 }
+  }
+}

package/bundled-contracts/maggie-blog/blog-post-v1.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-blog-post.v1",
+  "type": "object",
+  "required": ["schemaVersion", "id", "projectId", "contentId", "slug", "title", "body", "status", "source"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-blog-post.v1" },
+    "id": { "type": "string", "minLength": 1 },
+    "projectId": { "type": "string", "minLength": 1 },
+    "contentId": { "type": "string", "minLength": 1 },
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "title": { "type": "string", "minLength": 1 },
+    "excerpt": { "type": "string" },
+    "body": { "type": "object", "required": ["format", "value"], "properties": { "format": { "enum": ["markdown", "html"] }, "value": { "type": "string" } } },
+    "topics": { "type": "array", "items": { "type": "object", "required": ["slug", "label"] } },
+    "status": { "enum": ["draft", "review", "approved", "published", "archived"] },
+    "source": { "type": "object", "required": ["provider", "revision"] }
+  }
+}

package/bundled-contracts/maggie-blog/blog-settings-v1.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-blog-settings.v1",
+  "type": "object",
+  "required": ["schemaVersion", "basePath", "postsPerPage", "defaultPostStatus", "autoPullEnabled"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-blog-settings.v1" },
+    "basePath": { "type": "string", "pattern": "^/" },
+    "postsPerPage": { "type": "integer", "minimum": 1, "maximum": 100 },
+    "topicLimit": { "type": "integer", "minimum": 1 },
+    "defaultPostStatus": { "enum": ["draft", "review"] },
+    "autoPullEnabled": { "type": "boolean" },
+    "pullIntervalMinutes": { "type": "integer", "minimum": 5 },
+    "maxPerRun": { "type": "integer", "minimum": 1 }
+  }
+}

package/bundled-contracts/maggie-content-ui/README.md

@@ -0,0 +1,6 @@
+# Maggie Content UI Contracts
+
+These contracts describe sanitized structural evidence captured from a local
+UI reference and the native implementation plan consumed by `maggie-design`.
+They intentionally exclude source-brand content, private data, credentials,
+raw assets, and copied source code.

package/bundled-contracts/maggie-content-ui/plan-v1.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-content-ui-plan.v1",
+  "type": "object",
+  "required": ["schemaVersion", "id", "workflow", "mode", "surface", "phase", "shell", "components", "routes", "dataAdapter", "publicWrite"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-content-ui-plan.v1" },
+    "id": { "type": "string", "pattern": "^init-[a-f0-9]+$" },
+    "workflow": { "const": "maggie-design" },
+    "mode": { "const": "content-ui-init" },
+    "surface": { "enum": ["blog", "service"] },
+    "phase": { "const": "ready" },
+    "shell": { "type": "object", "required": ["sourceOfTruth", "reuse", "replaceAllowed"] },
+    "components": { "type": "array", "minItems": 1 },
+    "routes": { "type": "array", "minItems": 1 },
+    "dataAdapter": { "enum": ["maggie-blog", "maggie-service-booking"] },
+    "publicWrite": { "const": false }
+  }
+}

package/bundled-contracts/maggie-content-ui/reference-manifest-v1.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "maggie-content-ui-reference.v1",
+  "type": "object",
+  "required": ["schemaVersion", "id", "workflow", "mode", "surfaces", "sourcePolicy", "privateSourceCopied"],
+  "properties": {
+    "schemaVersion": { "const": "maggie-content-ui-reference.v1" },
+    "id": { "type": "string", "pattern": "^reference-[a-f0-9]+$" },
+    "workflow": { "const": "maggie-design" },
+    "mode": { "const": "reference-ui" },
+    "surfaces": { "type": "object", "minProperties": 1 },
+    "sourcePolicy": { "const": "read-only-structural-guideline" },
+    "privateSourceCopied": { "const": false }
+  }
+}

package/bundled-skills/maggie-auth-reference/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: maggie-auth-reference
+description: Generate and validate a provider-neutral traditional email/password auth reference with secure server sessions and production security gates.
+metadata:
+  version: 1.0.0
+---
+
+Before and after a meaningful auth-reference run, follow the shared
+[Maggie Memory Hook](../../references/memory-hook.md). Store only confirmed,
+project-scoped lessons; never store passwords, hashes, tokens, or provider
+credentials.
+
+# Maggie Auth Reference
+
+Use this skill when a project needs a reviewed starting point for
+email/password authentication. It does not replace an existing auth provider
+and it does not support passkeys, WebAuthn, or passwordless login.
+
+```bash
+maggie auth reference --project . --confirm
+maggie auth check --project . --production
+```
+
+The reference uses Argon2id in production, normalized email identity,
+HttpOnly/SameSite server-side sessions, generic failed-login responses,
+throttling, lockout, revocation, and an explicit owner setup gate. Secrets,
+hashes, and session tokens must never be emitted into browser responses,
+logs, or project context.

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

@@ -0,0 +1,46 @@
+---
+name: maggie-blog
+description: Create and operate a provider-neutral blog with stable post identity, topics, draft approval, archive/post routes, RSS, sitemap, settings, and idempotent local ingest.
+metadata:
+  version: 1.0.0
+---
+
+Before and after a meaningful blog run, follow the shared [Maggie Memory
+Hook](../../references/memory-hook.md). Record only confirmed, reusable
+project lessons, never raw provider credentials or temporary content facts.
+
+# Maggie Blog
+
+Use the stable CLI to initialize a local blog contract, ingest versioned local
+content, validate lifecycle invariants, publish with an actor and reason, and
+generate route/feed artifacts. Read the host framework and database contract
+before adding public routes. The host project owns rendering, persistence
+credentials, and deployment; this skill owns normalized blog semantics.
+
+```bash
+maggie blog init --project . --base-path /our-blogs --confirm
+maggie blog ingest --project . --source local --input content/posts.json --confirm
+maggie blog validate --project .
+maggie blog publish --project . --slug example-post --actor owner --reason "approved" --confirm
+maggie blog sitemap --project .
+maggie blog settings --project .
+maggie blog rollback --project . --confirm
+```
+
+Posts are draft-first. Stable `contentId` is the ingest identity and a
+published slug must not change during a rewrite. Search/sort views are not
+indexable; drafts never appear in public routes, RSS, or sitemap output.
+Provider keys remain server-side. Public publication and migrations always
+require explicit confirmation.
+
+To initialize native front-end pages from the approved local UI guideline,
+run `maggie-design`:
+
+```bash
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --base-path /our-blogs --confirm
+```
+
+The blog skill supplies route/data semantics; `maggie-design` supplies the
+host-native components and responsive visual review.

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

@@ -73,6 +73,74 @@ run visual review, and validate the route. It reuses shared tokens and the
 approved palette; it does not rewrite `DESIGN.md`, change the colour palette,
 or require a clone run.
 
+## First-party author mode
+
+Use author mode when the requested page is original and has no external source
+URL. It preserves the homepage shell and current `DESIGN.md` contract, writes
+a local brief and route plan, and stops before implementation approval:
+
+```bash
+maggie design author --project . --route /about \
+  --purpose "Explain our approach and contact path" \
+  --audience "Prospective customers" --confirm
+```
+
+The command rejects `/`, existing route collisions, missing `DESIGN.md`, and
+unconfirmed writes. Generated copy and media must be marked authored rather
+than source-observed. Implementation must still capture responsive screenshots
+and run accessibility/build validation before publication.
+
+## Content UI initialization
+
+Use content UI initialization when `maggie-blog` or
+`maggie-service-booking` needs native front-end layouts based on a local UI
+reference. The reference is structural evidence only. It must not replace the
+project's `DESIGN.md`, homepage shell, brand, copy, assets, or provider facts.
+
+First record a sanitized, read-only reference manifest:
+
+```bash
+maggie design reference-ui \
+  --project . \
+  --reference /home/balalior/Dev/clients/spachevychase.org \
+  --surface blog,service --confirm
+```
+
+Then initialize one surface at a time from that manifest:
+
+```bash
+maggie design init --project . --surface blog \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --base-path /our-blogs --confirm
+
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --route-pattern '/services/[slug]/' --confirm
+```
+
+The initializer creates a reviewable component/route/responsive/provenance
+plan under `.maggie/design/content-ui/`. It does not write public components
+or publish routes. The implementation phase must call the matching data skill,
+reuse the homepage shell, capture desktop/tablet/mobile screenshots, and pass
+accessibility, metadata, build, and visual review gates before approval.
+
+Validate the rendered plan before approval:
+
+```bash
+maggie design validate-ui --project . \
+  --plan .maggie/design/content-ui/blog/init-<id>/plan.json \
+  --rendered-dir .maggie/design/content-ui/blog/init-<id>/screenshots \
+  --confirm
+```
+
+This gate requires valid PNG evidence for desktop, tablet, and mobile and keeps
+`publicWrite: false` until a separate approval step.
+
+For blog UI, preserve archive, topic, post/slug, pagination, RSS, and sitemap
+semantics from `maggie-blog`. For service UI, preserve provider identity,
+variants, booking URLs, duplicate canonical/noindex decisions, and service
+sitemap semantics from `maggie-service-booking`.
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -207,6 +207,19 @@ and `DESIGN.md`. Use the homepage header, footer, fonts, tokens, navigation,
 analytics boundary, accessibility behaviour, and responsive breakpoints.
 Only the service content region varies.
 
+When initializing a new service UI from the approved reference guideline, use
+the shared `maggie-design` initializer:
+
+```bash
+maggie design init --project . --surface service \
+  --reference-run .maggie/design/content-ui/reference-<id> \
+  --route-pattern '/services/[slug]/' --confirm
+```
+
+This creates a reviewable native component/route plan. It does not copy the
+reference project's brand, source code, assets, or provider facts, and it does
+not publish service pages without the existing service fact/copy gates.
+
 Each service page must expose the service title, category breadcrumbs, factual
 description, all active variants, duration, currency-formatted price, booking
 CTA, and payment CTA only if available. Preserve the provider booking URL as

package/bundled-tools/clis/maggie_auth.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python3
+"""Auth reference and production prerequisite checks."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_auth import production_hashing_ready  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie auth")
+    sub = parser.add_subparsers(dest="command", required=True)
+    reference = sub.add_parser("reference"); reference.add_argument("--project", type=Path, default=Path.cwd()); reference.add_argument("--confirm", action="store_true")
+    check = sub.add_parser("check"); check.add_argument("--project", type=Path, default=Path.cwd()); check.add_argument("--production", action="store_true")
+    args = parser.parse_args(); project = args.project.resolve(); state = project / ".maggie" / "auth" / "reference.json"
+    if args.command == "reference":
+        if not args.confirm: print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+        state.parent.mkdir(parents=True, exist_ok=True)
+        value = {"schemaVersion": "maggie-auth-reference.v1", "mode": "traditional-email-password", "passwordAlgorithm": "argon2id", "session": {"serverSide": True, "httpOnly": True, "sameSite": "lax"}, "tables": ["accounts", "sessions", "auth_events"], "status": "review", "project": str(project)}
+        state.write_text(json.dumps(value, indent=2) + "\n", encoding="utf-8"); print(json.dumps(value, indent=2)); return 0
+    result = {"reference": state.exists(), "argon2id": production_hashing_ready(), "production": args.production}
+    if args.production: result["passed"] = result["reference"] and result["argon2id"]
+    else: result["passed"] = result["reference"]
+    print(json.dumps(result, indent=2)); return 0 if result["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_blog.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Stable Maggie Blog CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
+from maggie_blog import BlogStore  # noqa: E402
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="maggie blog")
+    sub = parser.add_subparsers(dest="command", required=True)
+    init = sub.add_parser("init"); init.add_argument("--project", type=Path, default=Path.cwd()); init.add_argument("--base-path", default="/our-blogs"); init.add_argument("--posts-per-page", type=int, default=9); init.add_argument("--confirm", action="store_true")
+    inspect = sub.add_parser("inspect"); inspect.add_argument("--project", type=Path, default=Path.cwd())
+    ingest = sub.add_parser("ingest"); ingest.add_argument("--project", type=Path, default=Path.cwd()); ingest.add_argument("--input", type=Path, required=True); ingest.add_argument("--source", default="local"); ingest.add_argument("--confirm", action="store_true")
+    validate = sub.add_parser("validate"); validate.add_argument("--project", type=Path, default=Path.cwd())
+    publish = sub.add_parser("publish"); publish.add_argument("--project", type=Path, default=Path.cwd()); publish.add_argument("--slug", required=True); publish.add_argument("--actor", required=True); publish.add_argument("--reason", required=True); publish.add_argument("--confirm", action="store_true")
+    sitemap = sub.add_parser("sitemap"); sitemap.add_argument("--project", type=Path, default=Path.cwd())
+    settings = sub.add_parser("settings"); settings.add_argument("--project", type=Path, default=Path.cwd())
+    rollback = sub.add_parser("rollback"); rollback.add_argument("--project", type=Path, default=Path.cwd()); rollback.add_argument("--backup"); rollback.add_argument("--confirm", action="store_true")
+    args = parser.parse_args()
+    store = BlogStore(args.project.resolve())
+    if args.command in {"init", "ingest", "publish", "rollback"} and not args.confirm:
+        print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+    try:
+        if args.command == "init": result = store.init(args.base_path, args.posts_per_page)
+        elif args.command == "inspect": result = {"settings": store.settings(), "posts": store.posts(), "runs": json.loads(store.runs_path.read_text(encoding="utf-8")) if store.runs_path.exists() else []}
+        elif args.command == "ingest":
+            payload = json.loads(args.input.read_text(encoding="utf-8"));
+            if not isinstance(payload, list): raise ValueError("local input must be a JSON array")
+            result = store.ingest(payload, args.source)
+        elif args.command == "validate": result = store.validate()
+        elif args.command == "publish": result = store.publish(args.slug, args.actor, args.reason)
+        elif args.command == "settings": result = store.settings()
+        elif args.command == "rollback": result = store.rollback(args.backup)
+        else: result = store.generate_feeds()
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"maggie-blog: {error}", file=sys.stderr); return 1
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    return 0 if args.command != "validate" or result.get("valid") else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_design.py

@@ -34,6 +34,32 @@ DESIGN_HEADINGS = (
 
 REVIEW_VIEWPORTS = {"desktop": (1440, 900), "tablet": (768, 900), "mobile": (390, 844)}
 
+REFERENCE_SURFACES = {
+    "blog": {
+        "files": [
+            "src/layouts/BlogLayout.astro", "src/components/blog/BlogArchive.astro",
+            "src/components/blog/PostCard.astro", "src/components/blog/Pagination.astro",
+            "src/components/blog/PostSidebar.astro", "src/pages/our-blogs/index.astro",
+            "src/pages/our-blogs/[slug].astro", "src/pages/our-blogs/topic/[slug].astro",
+            "src/pages/rss.xml.ts", "src/pages/sitemap.xml.ts",
+        ],
+        "components": ["BlogLayout", "BlogArchive", "PostCard", "Pagination", "PostSidebar", "ShareMenu"],
+        "routes": ["{base}/", "{base}/page/{n}/", "{base}/{slug}/", "{base}/topic/{slug}/", "{base}/topic/{slug}/page/{n}/", "/rss.xml", "/sitemap.xml"],
+        "patterns": ["compact image-backed archive hero", "URL-backed search/topic/sort controls", "responsive post grid", "sticky article sidebar", "related articles", "crawlable topic links"],
+    },
+    "service": {
+        "files": [
+            "src/pages/services/index.astro", "src/pages/services/[slug].astro",
+            "src/components/ServicePage.astro", "src/components/CategoryServiceHub.astro",
+            "src/components/SupportingServicePage.astro", "src/components/ServiceContextNarrative.astro",
+            "src/pages/sitemap-services.xml.ts", "src/pages/sitemap-service-categories.xml.ts",
+        ],
+        "components": ["ServiceIndex", "CategoryServiceHub", "ServicePage", "ServiceFacts", "RelatedServices", "ServiceFaq"],
+        "routes": ["/services/", "/services/{slug}/", "/service-categories/{slug}/", "/sitemap-services.xml", "/sitemap-service-categories.xml"],
+        "patterns": ["category breadcrumb hero", "variant facts and booking card", "service narrative with image", "related treatment grid", "FAQ accordion", "category navigation"],
+    },
+}
+
 
 def rendered_asset_preflight(template: Path) -> list[str]:
     """Catch package CSS failures before visual comparison is trusted."""
@@ -56,6 +82,81 @@ def rendered_asset_preflight(template: Path) -> list[str]:
     return errors
 
 
+def _surface_list(value: str) -> list[str]:
+    surfaces = [item.strip().lower() for item in value.split(",") if item.strip()]
+    invalid = sorted(set(surfaces) - set(REFERENCE_SURFACES))
+    if invalid or not surfaces:
+        raise ValueError("surface must contain blog and/or service")
+    return list(dict.fromkeys(surfaces))
+
+
+def reference_ui(project: Path, reference: Path, surfaces: list[str], screenshots_dir: Path | None, confirm: bool) -> int:
+    """Record sanitized structural evidence from a read-only reference project."""
+    project = project.resolve(); reference = reference.resolve()
+    if not reference.is_dir(): raise ValueError(f"reference project not found: {reference}")
+    if not confirm: print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+    missing = {surface: [item for item in REFERENCE_SURFACES[surface]["files"] if not (reference / item).exists()] for surface in surfaces}
+    missing = {key: value for key, value in missing.items() if value}
+    if missing: raise ValueError("reference files missing: " + json.dumps(missing, ensure_ascii=False))
+    digest = hashlib.sha256((str(reference) + "\n" + ",".join(surfaces)).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "content-ui" / f"reference-{digest}"; output_dir.mkdir(parents=True, exist_ok=True)
+    evidence = {}
+    for surface in surfaces:
+        config = REFERENCE_SURFACES[surface]
+        evidence[surface] = {"sourceFiles": config["files"], "components": config["components"], "routes": config["routes"], "patterns": config["patterns"], "observations": {pattern: True for pattern in config["patterns"]}}
+    screenshots = {name: "pending" for name in REVIEW_VIEWPORTS}
+    if screenshots_dir:
+        screenshots = {name: str((screenshots_dir / f"{name}.png").resolve()) if (screenshots_dir / f"{name}.png").is_file() else "missing" for name in REVIEW_VIEWPORTS}
+    manifest = {"schemaVersion": "maggie-content-ui-reference.v1", "id": f"reference-{digest}", "workflow": "maggie-design", "mode": "reference-ui", "referenceProject": reference.name, "surfaces": evidence, "screenshots": screenshots, "sourcePolicy": "read-only-structural-guideline", "privateSourceCopied": False, "createdAt": datetime.now(timezone.utc).isoformat()}
+    path = output_dir / "reference-manifest.json"; path.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"manifest": str(path), "id": manifest["id"], "surfaces": surfaces, "screenshotStatus": screenshots}, indent=2, ensure_ascii=False)); return 0
+
+
+def init_content_ui(project: Path, surface: str, reference_run: Path, base_path: str, route_pattern: str, confirm: bool) -> int:
+    """Create the reviewable plan that Maggie Design will implement natively."""
+    project = project.resolve(); surface = surface.strip().lower()
+    if surface not in REFERENCE_SURFACES: raise ValueError("surface must be blog or service")
+    if not confirm: print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr); return 2
+    contract = require_design_contract(project)
+    manifest_path = reference_run.resolve()
+    if manifest_path.is_dir(): manifest_path /= "reference-manifest.json"
+    if not manifest_path.exists(): raise ValueError(f"reference manifest required: {manifest_path}")
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    if surface not in manifest.get("surfaces", {}): raise ValueError(f"reference manifest does not contain surface: {surface}")
+    digest = hashlib.sha256((str(project) + "\n" + surface + "\n" + str(manifest_path)).encode()).hexdigest()[:12]
+    output_dir = project / ".maggie" / "design" / "content-ui" / surface / f"init-{digest}"; output_dir.mkdir(parents=True, exist_ok=True)
+    config = REFERENCE_SURFACES[surface]
+    routes = config["routes"]
+    if surface == "blog": routes = [route.replace("{base}", base_path.rstrip("/") or "/our-blogs") for route in routes]
+    elif route_pattern: routes = [route_pattern, "/sitemap-services.xml", "/sitemap-service-categories.xml"]
+    plan = {"schemaVersion": "maggie-content-ui-plan.v1", "id": f"init-{digest}", "workflow": "maggie-design", "mode": "content-ui-init", "surface": surface, "phase": "ready", "referenceManifest": str(manifest_path), "designContract": contract, "shell": {"sourceOfTruth": "existing homepage shell", "reuse": ["header", "footer", "tokens", "typography", "icons", "breakpoints", "accessibility", "analytics"], "replaceAllowed": False}, "components": config["components"], "routes": routes, "dataAdapter": "maggie-blog" if surface == "blog" else "maggie-service-booking", "provenance": {"referenceObserved": True, "projectPreserved": True, "agentAuthored": True, "providerFact": surface == "service"}, "requiredSteps": ["inspect-host-shell", "create-native-components", "bind-data-adapter", "capture-desktop-tablet-mobile", "accessibility-check", "metadata-and-route-check", "build-check", "explicit-approval"], "publicWrite": False, "createdAt": datetime.now(timezone.utc).isoformat()}
+    files = {"reference-manifest.json": manifest, "shell-reuse.json": plan["shell"], "component-plan.json": {"components": config["components"], "patterns": config["patterns"]}, "route-plan.json": {"routes": routes, "dataAdapter": plan["dataAdapter"]}, "responsive-plan.json": {"viewports": REVIEW_VIEWPORTS, "mobileStickySidebar": False if surface == "blog" else None}, "provenance.json": plan["provenance"], "validation.json": {"status": "pending", "required": plan["requiredSteps"]}}
+    for filename, value in files.items(): (output_dir / filename).write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    (output_dir / "screenshots").mkdir(exist_ok=True)
+    (output_dir / "plan.json").write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"plan": str(output_dir / "plan.json"), "surface": surface, "phase": "ready", "publicWrite": False}, indent=2)); return 0
+
+
+def validate_content_ui(project: Path, plan_path: Path, rendered_dir: Path | None, confirm: bool) -> int:
+    """Validate a generated content UI plan before host publication."""
+    project = project.resolve(); plan_path = plan_path.resolve()
+    if not plan_path.exists(): raise ValueError(f"content UI plan not found: {plan_path}")
+    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []
+    if plan.get("workflow") != "maggie-design" or plan.get("mode") != "content-ui-init": errors.append("invalid design workflow plan")
+    if plan.get("publicWrite") is not False: errors.append("publicWrite must remain false before approval")
+    try: require_design_contract(project)
+    except ValueError as error: errors.append(str(error))
+    screenshot_status = {}
+    for name in REVIEW_VIEWPORTS:
+        path = (rendered_dir / f"{name}.png") if rendered_dir else plan_path.parent / "screenshots" / f"{name}.png"
+        valid = path.is_file() and path.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
+        screenshot_status[name] = {"path": str(path), "validPng": valid}
+        if not valid: errors.append(f"missing valid {name} screenshot")
+    result = {"schemaVersion": "maggie-content-ui-validation.v1", "plan": str(plan_path), "surface": plan.get("surface"), "screenshots": screenshot_status, "checks": {"shellReuse": plan.get("shell", {}).get("replaceAllowed") is False, "publicWriteBlocked": plan.get("publicWrite") is False, "designContract": not any("DESIGN.md" in error for error in errors)}, "status": "passed" if not errors else "failed", "errors": errors, "validatedAt": datetime.now(timezone.utc).isoformat()}
+    if not confirm: print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
+    output = plan_path.parent / "validation.json"; output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"); print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
+
+
 def rebrand_template(args: argparse.Namespace) -> int:
     """Apply an explicit brand identity to a packaged homepage template."""
     template = args.template.resolve()
@@ -453,7 +554,68 @@ def in_place_job(project: Path, routes: list[str], force: bool = False) -> int:
     return 0
 
 
+def author_job(project: Path, route: str, purpose: str, audience: str, brief_file: Path | None, confirm: bool) -> int:
+    """Create an original page brief without requiring an external source URL."""
+    project = project.resolve()
+    if not confirm:
+        print("CONFIRMATION_REQUIRED: rerun with --confirm", file=sys.stderr)
+        return 2
+    if not route.startswith("/") or route == "/": raise ValueError("author route must be a non-homepage path starting with /")
+    contract = require_design_contract(project)
+    relative = route.strip("/")
+    candidates = [project / "src" / "pages" / relative, project / "src" / "pages" / f"{relative}.astro", project / "src" / "app" / relative / "page.tsx", project / relative]
+    collision = next((path for path in candidates if path.exists()), None)
+    if collision: raise ValueError(f"route collision; existing route: {collision}")
+    source_brief = {}
+    if brief_file:
+        source_brief = json.loads(brief_file.resolve().read_text(encoding="utf-8"))
+    if not purpose.strip() and not source_brief.get("purpose"): raise ValueError("purpose is required")
+    if not audience.strip() and not source_brief.get("audience"): raise ValueError("audience is required")
+    brief = {"schemaVersion": "maggie-page-brief.v1", "route": route, "purpose": purpose.strip() or source_brief["purpose"], "audience": audience.strip() or source_brief["audience"], "contentBrief": source_brief.get("contentBrief", ""), "shell": "homepage-canonical", "status": "draft", "sourceEvidence": None, "approval": {"status": "pending", "actor": None}, "createdAt": datetime.now(timezone.utc).isoformat()}
+    digest = hashlib.sha256((str(project) + "\n" + route).encode()).hexdigest()[:12]
+    output = project / ".maggie" / "design" / "briefs" / f"{relative.replace('/', '-')}.json"; output.parent.mkdir(parents=True, exist_ok=True); output.write_text(json.dumps(brief, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    plan_path = project / ".maggie" / "design" / f"author-{digest}.json"
+    plan_path.write_text(json.dumps({"id": f"author-{digest}", "workflow": "maggie-design", "mode": "author", "phase": "ready", "brief": str(output), "designContract": contract, "sourceUrlRequired": False, "shellSourceOfTruth": "homepage-canonical", "approvalRequired": True, "requiredSteps": ["inspect-shell", "implement-page", "capture-responsive-screenshots", "accessibility-check", "build-check", "approval"]}, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"brief": str(output), "plan": str(plan_path), "phase": "ready"}, indent=2)); return 0
+
+
 def main() -> int:
+    if len(sys.argv) > 1 and sys.argv[1] == "reference-ui":
+        command = argparse.ArgumentParser(description="Record sanitized blog/service UI evidence from a read-only reference project.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--reference", type=Path, required=True)
+        command.add_argument("--surface", default="blog,service")
+        command.add_argument("--screenshots-dir", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return reference_ui(args.project, args.reference, _surface_list(args.surface), args.screenshots_dir, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design reference-ui: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "init":
+        command = argparse.ArgumentParser(description="Initialize a native blog or service UI plan from a sanitized reference manifest.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--surface", required=True, choices=["blog", "service"])
+        command.add_argument("--reference-run", type=Path, required=True)
+        command.add_argument("--base-path", default="/our-blogs")
+        command.add_argument("--route-pattern", default="/services/[slug]/")
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return init_content_ui(args.project, args.surface, args.reference_run, args.base_path, args.route_pattern, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design init: {error}", file=sys.stderr); return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "validate-ui":
+        command = argparse.ArgumentParser(description="Validate content UI screenshots and design/public-write gates.")
+        command.add_argument("--project", type=Path, default=Path.cwd())
+        command.add_argument("--plan", type=Path, required=True)
+        command.add_argument("--rendered-dir", type=Path)
+        command.add_argument("--confirm", action="store_true")
+        args = command.parse_args(sys.argv[2:])
+        try:
+            return validate_content_ui(args.project, args.plan, args.rendered_dir, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design validate-ui: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "rebrand":
         rebrand = argparse.ArgumentParser(description="Apply an explicit brand identity to a packaged marketplace template.")
         rebrand.add_argument("--template", type=Path, required=True)
@@ -486,6 +648,19 @@ def main() -> int:
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design in-place: {error}", file=sys.stderr)
             return 1
+    if len(sys.argv) > 1 and sys.argv[1] == "author":
+        author = argparse.ArgumentParser(description="Create an original first-party page brief and route plan.")
+        author.add_argument("--project", type=Path, default=Path.cwd())
+        author.add_argument("--route", required=True)
+        author.add_argument("--purpose", default="")
+        author.add_argument("--audience", default="")
+        author.add_argument("--brief-file", type=Path)
+        author.add_argument("--confirm", action="store_true")
+        args = author.parse_args(sys.argv[2:])
+        try:
+            return author_job(args.project, args.route, args.purpose, args.audience, args.brief_file, args.confirm)
+        except (OSError, ValueError, json.JSONDecodeError) as error:
+            print(f"BLOCKED: maggie-design author: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] in {"run", "status", "resume"}:
         workflow = argparse.ArgumentParser(description=__doc__)
         sub = workflow.add_subparsers(dest="command", required=True)

package/bundled-tools/runtime/maggie_blog.py

@@ -0,0 +1,167 @@
+"""Local, provider-neutral Maggie Blog content lifecycle."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+STATUSES = ("draft", "review", "approved", "published", "archived")
+DEFAULTS = {
+    "schemaVersion": "maggie-blog-settings.v1",
+    "basePath": "/our-blogs",
+    "postsPerPage": 9,
+    "topicLimit": 12,
+    "defaultPostStatus": "draft",
+    "autoPullEnabled": False,
+    "pullIntervalMinutes": 120,
+    "maxPerRun": 1,
+    "fallbackImageMode": "gradient",
+}
+
+
+def now() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+
+def slugify(value: str) -> str:
+    value = re.sub(r"[^a-z0-9]+", "-", value.strip().lower()).strip("-")
+    if not value:
+        raise ValueError("slug cannot be empty")
+    return value
+
+
+def checksum(value: object) -> str:
+    return "sha256:" + hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()
+
+
+class BlogStore:
+    def __init__(self, project: Path) -> None:
+        self.root = project / ".maggie" / "blog"
+        self.posts_path = self.root / "posts.json"
+        self.settings_path = self.root / "settings.json"
+        self.runs_path = self.root / "pull-runs.json"
+
+    def init(self, base_path: str = "/our-blogs", posts_per_page: int = 9) -> dict:
+        self.root.mkdir(parents=True, exist_ok=True)
+        settings = {**DEFAULTS, "basePath": "/" + base_path.strip("/"), "postsPerPage": posts_per_page, "updatedAt": now()}
+        if self.settings_path.exists():
+            existing = json.loads(self.settings_path.read_text(encoding="utf-8"))
+            settings = {**settings, **existing}
+        self._write(self.settings_path, settings)
+        if not self.posts_path.exists(): self._write(self.posts_path, [])
+        if not self.runs_path.exists(): self._write(self.runs_path, [])
+        return settings
+
+    def settings(self) -> dict:
+        if not self.settings_path.exists(): raise ValueError("blog is not initialized; run `maggie blog init` first")
+        return json.loads(self.settings_path.read_text(encoding="utf-8"))
+
+    def posts(self) -> list[dict]:
+        if not self.posts_path.exists(): return []
+        return json.loads(self.posts_path.read_text(encoding="utf-8"))
+
+    def _write(self, path: Path, value: object) -> None:
+        path.write_text(json.dumps(value, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    def _backup(self) -> None:
+        if self.posts_path.exists():
+            backup_dir = self.root / "backups"; backup_dir.mkdir(exist_ok=True)
+            shutil.copy2(self.posts_path, backup_dir / f"posts-{now().replace(':', '').replace('.', '')}.json")
+
+    def ingest(self, payload: list[dict], provider: str = "local") -> dict:
+        settings = self.settings()
+        posts = self.posts()
+        by_content = {post["contentId"]: post for post in posts}
+        changed = 0
+        for item in payload:
+            content_id = str(item.get("contentId") or item.get("id") or "").strip()
+            title = str(item.get("title") or "").strip()
+            if not content_id or not title: raise ValueError("each post requires contentId/id and title")
+            old = by_content.get(content_id)
+            raw_slug = str(item.get("slug") or title)
+            post = {
+                "schemaVersion": "maggie-blog-post.v1",
+                "id": old["id"] if old else f"post:{content_id}",
+                "projectId": str(item.get("projectId") or "local-project"),
+                "contentId": content_id,
+                "slug": old["slug"] if old else slugify(raw_slug),
+                "title": title,
+                "excerpt": str(item.get("excerpt") or ""),
+                "body": item.get("body") if isinstance(item.get("body"), dict) else {"format": str(item.get("format") or "markdown"), "value": str(item.get("body") or item.get("content") or "")},
+                "topics": [{"slug": slugify(str(topic)), "label": str(topic)} for topic in item.get("topics", item.get("keywords", []))],
+                # Provider input can suggest a status, but cannot bypass the
+                # local approval gate. Existing published state is preserved.
+                "status": old.get("status", settings["defaultPostStatus"]) if old else settings["defaultPostStatus"],
+                "canonicalUrl": item.get("canonicalUrl"),
+                "source": {"provider": provider, "revision": str(item.get("revision") or checksum(item))},
+                "publishedAt": old.get("publishedAt") if old else item.get("publishedAt"),
+                "updatedAt": now(),
+            }
+            if post["status"] not in STATUSES: raise ValueError(f"invalid post status: {post['status']}")
+            post["canonicalUrl"] = post["canonicalUrl"] or settings["basePath"].rstrip("/") + "/" + post["slug"] + "/"
+            comparable_old = {k: v for k, v in (old or {}).items() if k != "updatedAt"}
+            comparable_new = {k: v for k, v in post.items() if k != "updatedAt"}
+            if comparable_old != comparable_new: changed += 1
+            by_content[content_id] = post
+        result = list(by_content.values())
+        slugs = [post["slug"] for post in result]
+        if len(slugs) != len(set(slugs)): raise ValueError("slug collision detected; provide unique slugs")
+        self._backup(); self._write(self.posts_path, result)
+        runs = json.loads(self.runs_path.read_text(encoding="utf-8")) if self.runs_path.exists() else []
+        run = {"id": "pull:" + hashlib.sha256((now() + provider).encode()).hexdigest()[:12], "provider": provider, "status": "completed", "delivered": len(payload), "changed": changed, "finishedAt": now()}
+        runs.append(run); self._write(self.runs_path, runs)
+        return run
+
+    def validate(self) -> dict:
+        settings = self.settings(); posts = self.posts(); errors = []
+        ids = [p.get("contentId") for p in posts]; slugs = [p.get("slug") for p in posts]
+        if len(ids) != len(set(ids)): errors.append("duplicate contentId")
+        if len(slugs) != len(set(slugs)): errors.append("duplicate slug")
+        for post in posts:
+            if post.get("schemaVersion") != "maggie-blog-post.v1": errors.append(f"{post.get('id')}: schemaVersion")
+            if post.get("status") not in STATUSES: errors.append(f"{post.get('id')}: status")
+            if post.get("status") == "published" and not post.get("publishedAt"): errors.append(f"{post.get('id')}: publishedAt required")
+        return {"valid": not errors, "posts": len(posts), "published": sum(p.get("status") == "published" for p in posts), "settings": settings, "errors": errors}
+
+    def publish(self, slug: str, actor: str, reason: str) -> dict:
+        if not actor or not reason: raise ValueError("actor and reason are required")
+        posts = self.posts(); found = next((p for p in posts if p.get("slug") == slug), None)
+        if not found: raise ValueError(f"post not found: {slug}")
+        if found["status"] not in {"draft", "review", "approved"}: raise ValueError(f"post cannot publish from {found['status']}")
+        found["status"] = "published"; found["publishedAt"] = found.get("publishedAt") or now(); found["updatedAt"] = now(); found["lastTransition"] = {"actor": actor, "reason": reason, "at": now()}
+        self._backup(); self._write(self.posts_path, posts); return found
+
+    def rollback(self, backup: str | None = None) -> dict:
+        backups = sorted((self.root / "backups").glob("posts-*.json")) if (self.root / "backups").exists() else []
+        source = Path(backup) if backup else (backups[-1] if backups else None)
+        if source is None or not source.exists(): raise ValueError("no blog backup available")
+        current = self.posts_path.read_text(encoding="utf-8") if self.posts_path.exists() else "[]"
+        self._backup(); self.posts_path.write_text(source.read_text(encoding="utf-8"), encoding="utf-8")
+        return {"restored": str(source), "previousPostCount": len(json.loads(current)), "postCount": len(self.posts())}
+
+    def generate_feeds(self) -> dict:
+        settings = self.settings(); posts = [p for p in self.posts() if p.get("status") == "published"]
+        base = settings["basePath"].rstrip("/"); out = self.root / "generated"; out.mkdir(exist_ok=True)
+        topics = sorted({topic["slug"] for post in posts for topic in post.get("topics", [])})
+        page_count = max(1, (len(posts) + settings["postsPerPage"] - 1) // settings["postsPerPage"])
+        routes = {
+            "archive": base + "/", "archivePages": [base + "/page/" + str(n) + "/" for n in range(2, page_count + 1)],
+            "post": [base + "/" + p["slug"] + "/" for p in posts],
+            "topics": [base + "/topic/" + t + "/" for t in topics], "rss": "/rss.xml", "sitemap": "/sitemap.xml",
+            "searchPolicy": {"robots": "noindex,follow", "canonical": "archive"},
+            "sortPolicy": {"robots": "noindex,follow", "canonical": "archive"},
+            "postMetadata": [{"url": base + "/" + p["slug"] + "/", "canonical": p["canonicalUrl"], "type": "BlogPosting", "headline": p["title"], "datePublished": p.get("publishedAt"), "dateModified": p.get("updatedAt")} for p in posts],
+        }
+        rss = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><rss version=\"2.0\"><channel>" + "".join(f"<item><title>{_xml(p['title'])}</title><link>{_xml(p['canonicalUrl'])}</link></item>" for p in posts) + "</channel></rss>"
+        sitemap_urls = [base + "/"] + routes["archivePages"] + routes["post"] + routes["topics"]
+        sitemap = "<?xml version=\"1.0\" encoding=\"UTF-8\"?><urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">" + "".join(f"<url><loc>{_xml(url)}</loc></url>" for url in sitemap_urls) + "</urlset>"
+        self._write(out / "routes.json", routes); (out / "rss.xml").write_text(rss, encoding="utf-8"); (out / "sitemap.xml").write_text(sitemap, encoding="utf-8")
+        return {"routes": routes, "rss": str(out / "rss.xml"), "sitemap": str(out / "sitemap.xml")}
+
+
+def _xml(value: object) -> str:
+    return str(value).replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace('"', "&quot;")

package/package.json

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