@topy-ai/maggie 0.2.9 → 0.3.0

package/README.md

@@ -264,12 +264,31 @@ 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 |
 
 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,10 @@ 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 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 +212,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 +246,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 +352,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-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,34 @@
+---
+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.

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

@@ -73,6 +73,23 @@ 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.
+
 ## Explicit homepage rebrand mode
 
 The homepage `review` mode only compares screenshots. It does not rebrand a

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

@@ -453,6 +453,31 @@ 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] == "rebrand":
         rebrand = argparse.ArgumentParser(description="Apply an explicit brand identity to a packaged marketplace template.")
@@ -486,6 +511,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.3.0",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",