@topy-ai/maggie 0.8.0 → 0.8.1

package/README-zh-TW.md

@@ -2,7 +2,7 @@
 
 [English README](README.md) · [完整繁體中文 README](https://github.com/TOPY-AI-LTD/ai-cmo-skills/blob/main/README.zh-TW.md)
 
-`@topy-ai/maggie` 提供 20 個可安裝的 AI website workflow skills，支援
+`@topy-ai/maggie` 提供 24 個可安裝的 AI website workflow skills，支援
 Codex、Claude Code 與相容的 coding agents。
 
 ## 安裝
@@ -143,7 +143,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 npm 版本為 `0.8.0`,安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 npm 版本為 `0.8.1`,新增 maggie-spirit（為 AI 品牌生成平面像素 spirit/sprite 系統：logo mark 與各 agent avatar 皆以共用的 32 狀態基礎集播放動畫）與 goal-led AI agent 設計參考，並補上 ONEMAN.APP in-place 開發的部署與設計筆記（靜態站先 build 再部署、Astro 執行期注入節點樣式、in-place DESIGN.md 擷取）。先前 0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -87,9 +87,9 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 23 installable skills and a local-first MaggieDash foundation.
+package ships 24 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.0` — the security optimization roadmap: one-shot `scan`, `image-patch` (copa) container remediation, A+…F header grade, SSVC rationale in reports, a GDPR log-privacy rule in code-scan, five more MCP tools (35), and pinned scanners, on top of safe patching (fix-risk tiers + host-impact).
+This package is `0.8.1` — adds `maggie-spirit` (generate an AI brand's flat-pixel spirit/sprite system: a logo mark plus per-agent avatars animated through a shared 32-state base set) and a goal-led AI agent design reference, plus deployment and design notes from the ONEMAN.APP in-place build (static-site build-before-deploy, Astro runtime-injected DOM styling, in-place DESIGN.md extraction).
 
 The 0.7.59 release made `maggie security host-audit` (the deep
 lynis audit over SSH) robust on hosts where a storage test can stall: lynis runs

package/bundled-references/agent-goal-design.md

@@ -0,0 +1,92 @@
+# Goal-led AI agent design
+
+A reusable method for defining the agents in a multi-agent product so a single
+human can run a company by stating intent, not by operating tools. Distilled
+from the ONEMAN.APP cofounder build; pairs with the `maggie-spirit` skill (give
+each designed agent a spirit/avatar) and `maggie-assistant-tools` (expose an
+agent's capabilities safely).
+
+## Principle
+
+The human sets a **goal**; the agents turn it into work and keep the human in
+the loop only for judgement and approval. Each agent owns one lane, declares the
+**capability classes** it may use, and runs under a **risk ceiling** with
+explicit approval gates. Nothing that is risky, public, or spends money happens
+without a human yes.
+
+## Define each agent with a role contract
+
+One `role.yaml` per agent. Recommended fields:
+
+```yaml
+role: CTO                     # the lane
+name: AI CTO                  # display name
+persona: Turing               # inspiration, not impersonation
+spirit: Engineering           # one-word identity (drives the spirit accent/motif)
+summary: >                    # what it owns, in one or two sentences
+  Technical design, build, integrate, test and deploy. Production deployment is
+  gated behind human approval.
+responsibilities: [design, build, integrate, test, deploy, observe]
+constraints: [no prod deploy without approval, no secrets in source]
+allowed_capability_classes: [app.scaffold, app.build, app.test, code.review,
+  deploy.release, integration.connect, ops.observe, job.execute]
+default_risk_ceiling: L1      # L0 read -> L3 irreversible/public/paid
+business_system: Execution    # which paired system (e.g. with COO)
+raci: { new_service_app: "A", security_verdict: I }
+interfaces: { mcp: planned, cli: planned, api: planned }
+```
+
+- **Capability classes**, not freeform skills, are the unit of authority. They
+  are stable `area.verb` identifiers (`content.publish`, `revenue.close`,
+  `security.scan`) that a UI can list and a gate can check. These are the
+  "skills" a product surfaces per agent.
+- **One CEO orchestrates.** The CEO owns `goal.decompose`, `mission.manage`,
+  `plan.compose`, `priority.rank`, `outcome.accept`: it turns intent into
+  missions with acceptance criteria, delegates each to the right agent, and
+  signs off - it never bypasses security or budget approval.
+- **Security holds a non-overridable veto.** A high-risk security verdict cannot
+  be overruled by another agent.
+- **Finance is explain-only.** Financial facts come from deterministic data
+  (billing/usage ledger, Stripe); the CFO reconciles and advises, it is not the
+  source of truth.
+
+## Risk ceilings and approval gates
+
+| Level | Meaning | Gate |
+|---|---|---|
+| L0 | read-only | none |
+| L1 | internal writes (drafts, plans, workflows) | logged |
+| L2 | customer-facing or public (publish, close a deal) | human approval |
+| L3 | irreversible / paid / production (deploy, transfer) | human approval + audit |
+
+Every agent declares a `default_risk_ceiling`; an action above it stops for an
+explicit human yes. Log every action; make L2/L3 produce an approval card.
+
+## The goal loop
+
+1. The human states what the business should do.
+2. The CEO writes missions with acceptance criteria.
+3. Each mission is delegated to the agent whose lane and capability classes fit.
+4. Agents work their lane; risky/public/paid steps wait for approval.
+5. The CEO reviews outcomes against the acceptance criteria and signs off, or
+   sends the mission back.
+6. The human stays the only human in the loop - approve, steer, ship.
+
+## Surfacing agents to users
+
+Each agent reads cleanly as a profile: persona name, spirit, its capability
+classes (its "skills"), and the service apps it manages. Give it a spirit/avatar
+with `maggie-spirit` (shared 32-state motion vocabulary, per-agent accent) so
+status (idle, working, deploying, success, blocked, secure) reads the same
+across the whole team. Mark an agent "shipped" only when its product is actually
+live.
+
+## Checklist
+
+- [ ] One lane per agent; no two agents own the same decision.
+- [ ] Capability classes are `area.verb`, stable, and enumerable.
+- [ ] A single orchestrator (CEO) owns decomposition and sign-off.
+- [ ] Security veto and finance-is-explain-only are encoded, not assumed.
+- [ ] Every agent has a risk ceiling; L2/L3 actions gate on human approval.
+- [ ] Persona is inspiration, not impersonation of a real person.
+- [ ] Each agent has a spirit/avatar from the shared 32-state base set.

package/bundled-skills/catalog.json

@@ -90,6 +90,10 @@
       "name": "maggie-social-share",
       "description": "Turn approved AI CMO articles and content assets into platform-native social drafts, scheduled posts, and measured distribution. Use for Social Share planning, LinkedIn/Facebook copy, CTA mapping, calendars, approvals, publish retries, or social performance readback."
     },
+    {
+      "name": "maggie-spirit",
+      "description": "Generate an AI brand's flat-pixel spirit (sprite) system - a logo mark that animates through a fixed 32-state base set, and per-agent avatar faces animated through the same states. Use for agent/brand avatars, logo marks, sprite-sheet and sprite-animation assets, and a shared motion vocabulary across Core and Service agents."
+    },
     {
       "name": "maggie-template",
       "description": "Discover, recommend, inspect, and apply verified Astro homepage templates from the Maggie marketplace. Use when a user wants to start a site from a selected template, compare available designs, or choose a visual direction before maggie-clone or maggie-design."

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

@@ -2,7 +2,7 @@
 name: maggie-deployment
 description: Deploy and operate Maggie blog projects with Cloudflare Workers as the default target, while preserving an adapter boundary for VPS, GCP, and AWS.
 metadata:
-  version: 1.6.0
+  version: 1.6.1
 ---
 
 # Maggie Deployment
@@ -749,3 +749,23 @@ discovery, install-manifest writes, or file synchronization. For fixture-backed
 browser QA, the host owns the isolated dev server and data source; document a
 second port/process and fixture mode in the host runbook instead of making the
 shared updater or deployment CLI start an unmanaged daemon.
+
+## Static sites: build first, ship the build output only
+
+A static-site deploy must run the framework build and ship **only** the build
+output, never the source tree. A pipeline that copies the project directory and
+serves it (for example `rsync webapp/ ...` then `python -m http.server`) exposes
+the source and, with no `index.html` at the root, serves a directory listing
+instead of the site.
+
+The deploy step must therefore:
+
+1. install and build in the project (`npm ci && npm run build`), then
+2. ship only the build artifact (`dist/`, `build/`, `.output/public`, ...) to the
+   web root, and
+3. verify the live root returns the rendered page (a `200` whose body contains
+   the expected `<title>`/`<h1>`), not an autoindex.
+
+Treat "the root is a directory listing" or "source files (`package.json`,
+`src/`) are reachable over HTTP" as a failed deploy. Prefer a build artifact
+check in CI over trusting that a copy step shipped the right directory.

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

@@ -2,7 +2,7 @@
 name: maggie-design
 description: Design authorized interior pages, review rendered responsive layouts, or explicitly rebrand a packaged homepage/template. Use rebrand only with a named source brand and target brand.
 metadata:
-  version: 1.6.0
+  version: 1.6.1
 ---
 
 # Maggie Design
@@ -853,3 +853,31 @@ without an explicit host contract. Decode HTML entities exactly once; unknown
 or double-escaped entities stop the check. Optional empty attributes such as
 `style=""` must be omitted. Codemods using compiler positions must anchor at
 the opening `<tag` before slicing source text.
+
+## Front-end pitfalls from in-place builds
+
+### Runtime-injected DOM does not get scoped styles
+
+Astro (and other scoped-style systems) add a per-component attribute
+(`data-astro-cid-*`) only to nodes present in the template at build time. Nodes
+you create at runtime with `innerHTML`/`createElement` never receive it, so
+scoped `<style>` rules silently do not match them - a tab, card, or image built
+in script renders unstyled while the identical server-rendered markup looks
+correct. Style runtime-injected content with `<style is:global>` (scoped by an
+id/class you control, e.g. `#my-modal .card { ... }`) or with inline styles.
+Verify with rendered-browser evidence, not a static class scan: the static
+selector exists, but the element it should match does not carry the scope.
+
+### Extract DESIGN.md in-place from the project's own homepage
+
+`maggie_design_system.py generate` builds a DESIGN.md from clone evidence, which
+an in-place redesign does not have. When the design source of truth is the
+project's existing homepage, author `DESIGN.md` directly from it: read the
+`:root` tokens, fonts, composition, responsive and interaction rules from the
+live page, write the eight required headings (`## Source and evidence`,
+`## Design tokens`, `## Composition rules`, `## Responsive rules`,
+`## Interaction rules`, `## Shared shell contract`, `## New page contract`,
+`## Unknowns and approvals`), and include the `Generated by Maggie` marker line
+so `maggie tool maggie_design_system.py validate DESIGN.md` passes. State in
+`## Source and evidence` that it was extracted in-place with no external clone.
+This unlocks `maggie design in-place` for a route without a clone run.

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

@@ -0,0 +1,128 @@
+---
+name: maggie-spirit
+description: Generate an AI brand's flat-pixel spirit (sprite) system - a logo mark that animates through a fixed 32-state base set, and per-agent avatar faces animated through the same states. Use for agent/brand avatars, logo marks, sprite-sheet and sprite-animation assets, and a shared motion vocabulary across Core and Service agents.
+metadata:
+  version: 0.1.0
+---
+
+# Maggie Spirit
+
+Give an agent brand one flat-pixel visual language: a **logo mark** and a set of
+**agent avatars** that all animate through the **same fixed catalog of 32
+states** (power, work, comms, outcome, gov). Agents differ only by their
+**motif/face** and their **accent** hue; the motion vocabulary, semantic palette
+and status badges stay identical so a state reads the same everywhere.
+
+Everything is deterministic (seeded by accent + persona) and self-contained
+(Pillow only - no model calls, no per-image cost). It pairs with
+[agent goal-led design](../../references/agent-goal-design.md): design the agent,
+then give it a spirit.
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation
+and completion.
+
+## When to use
+
+- You are standing up a multi-agent product (a C-suite of AI cofounders, a set
+  of Service Apps) and want a consistent avatar + logo + status-animation set.
+- You need a logo mark that can show live state (idle, working, deploying,
+  success, warning, secure, ...) rather than a single static glyph.
+- You need sprite sheets / animation strips + a `states.json` manifest to drive
+  a web UI (the CSS `steps()` technique), not a one-off illustration.
+
+For page/layout design use `maggie-design`; for marketplace templates use
+`maggie-marketplace`; this skill produces the brand's character assets only.
+
+## The 32-state base set
+
+Five groups, fixed across every agent so severity and status read the same:
+
+- **power:** off, booting, idle, active, paused, offline
+- **work:** thinking, loading, syncing, writing, streaming, queued, scanning, deploying
+- **comms:** speaking, listening, notification, mention, recording
+- **outcome:** success, warning, critical, blocked, error, retrying
+- **gov:** awaiting, approved, rejected, secure, vulnerable, maintenance, celebrating
+
+Each state carries its own frame count, fps, motion and optional badge; every
+state animates (none is static). The per-state `[frames, fps]` are written to
+`states.json` beside the images so a UI can play each strip exactly.
+
+## CLI
+
+Run through the bundled tool so it uses the current project as the working
+directory:
+
+```bash
+# logo mark + 32-state animated base set (anim-*.png, mark-*.svg, sprite-sheet.png, states.json)
+maggie tool maggie_spirit.py mark --out public/assets/brand --name oneman \
+  --accent "#ff1212" --title ONEMAN
+
+# one agent avatar animated through all 32 states (+ stills + sheet + states.json)
+maggie tool maggie_spirit.py agent --out public/assets/brand --name cto \
+  --accent "#3b82f6" --spec cto.persona.json
+
+# a single still avatar face
+maggie tool maggie_spirit.py avatar --out public/assets/brand/cto/face.png \
+  --accent "#3b82f6" --spec cto.persona.json
+
+# the reference base set to copy and recolour: default mark + example cast + founder
+maggie tool maggie_spirit.py demo --out public/assets/brand
+```
+
+`persona.json` (all keys optional except implied by your design):
+
+```json
+{
+  "gender": "m",
+  "hair": "#2a2018",
+  "skin": "light | mid | tan | deep",
+  "hairstyle": "short|slick|spiky|buzz|longwavy|longstraight|longbob|ponytail",
+  "eyes": "round|wide|lash|happy",
+  "mouth": "flat|smile|smirk|lips|open",
+  "prop": "glasses|shades|cigar|headset|earbuds|monocle|pen|bandana",
+  "propcol": "#f2c75a",
+  "hoodie": true, "band": "#e23b3b", "mask": "#12201a", "specs": true
+}
+```
+
+## Output contract
+
+For each target (`<out>/<name>/`):
+
+- `anim-<state>.png` - one horizontal strip per state (frames laid left to right).
+- `still-<state>.png` - a representative still per state (agents only).
+- `mark-<state>.svg` - a crisp SVG still per state (mark only).
+- `sprite-sheet.png` - an overview contact sheet.
+- `states.json` - `{ title, accent, N, scale, groups, states: { <state>: {group, frames, fps, motion, badge} } }`.
+
+## Driving the animation in a UI
+
+Flat-pixel, pixel-exact. Use CSS `steps()` with the per-state frame count, never
+percentage-position stepping:
+
+```css
+.sprite{
+  --fw: 48px;                 /* one frame = one cell */
+  width: var(--fw); height: var(--fw);
+  background: url(/assets/brand/cto/anim-active.png) no-repeat;
+  background-size: calc(var(--n) * var(--fw)) var(--fw);
+  image-rendering: pixelated;
+  animation: play calc(var(--n) / var(--fps) * 1s) steps(var(--n)) infinite;
+}
+@keyframes play { to { background-position-x: calc(-1 * var(--n) * var(--fw)); } }
+```
+
+Set `--n` and `--fps` per state from `states.json`. If you build the sprite
+element with `innerHTML` in an Astro page, style it with `<style is:global>` -
+Astro's scoped styles do not reach runtime-injected nodes (see `maggie-design`).
+
+## Boundaries
+
+- Deterministic and local: no LLM/image-model calls and no per-image billing.
+  Pillow is the only dependency.
+- The mark is the brand's own; recolour via `--accent`, keep the semantic
+  palette (severity colours) fixed so status stays legible across agents.
+- Do not hand-edit generated files; change the persona/accent and regenerate so
+  the whole set stays consistent.
+- Store generated art under the host project's assets; keep source personas
+  (the `*.persona.json`) in the repo so the set is reproducible.

package/bundled-tools/clis/maggie_dash.py

@@ -38,6 +38,11 @@ def project_root(args: argparse.Namespace) -> Path:
 
 
 def store_for(root: Path) -> MaggieDashStore:
+    # ONEMAN forbids SQLite: when MAGGIEDASH_DATABASE_URL is set, back the store
+    # with Postgres. Otherwise fall back to the local SQLite dev store.
+    dsn = os.environ.get("MAGGIEDASH_DATABASE_URL")
+    if dsn:
+        return MaggieDashStore(dsn=dsn)
     return MaggieDashStore(root / ".maggie" / "maggiedash.sqlite")
 
 
@@ -642,6 +647,9 @@ def command_recommend(args: argparse.Namespace) -> int:
 def command_init(args: argparse.Namespace) -> int:
     require_confirm(args)
     root = project_root(args)
+    if str(getattr(args, "adapter", "")).endswith("postgres") and not os.environ.get("MAGGIEDASH_DATABASE_URL"):
+        print("POSTGRES_DSN_REQUIRED: adapter is postgres but MAGGIEDASH_DATABASE_URL is not set.", file=sys.stderr)
+        return 2
     store = store_for(root)
     try:
         project = store.init_project(args.project_id, args.name, args.adapter, args.locale)
@@ -652,9 +660,9 @@ def command_init(args: argparse.Namespace) -> int:
             "name": args.name,
             "adapter": args.adapter,
             "locale": args.locale,
-            "storage": str(store.path),
+            "storage": store.storage_label,
         }, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-        emit({"status": "initialized", "project": project, "contract": str(contract), "storage": str(store.path)})
+        emit({"status": "initialized", "project": project, "contract": str(contract), "storage": store.storage_label})
         return 0
     finally:
         store.close()
@@ -667,7 +675,7 @@ def command_status(args: argparse.Namespace) -> int:
     try:
         project = store.connection.execute("SELECT * FROM maggiedash_projects WHERE id=?", (project_id,)).fetchone()
         documents = store.connection.execute("SELECT id, kind, title, slug, status, updated_at FROM maggiedash_documents WHERE project_id=? ORDER BY updated_at DESC", (project_id,)).fetchall()
-        emit({"status": "ready" if project else "not_initialized", "project": dict(project) if project else None, "documents": [dict(row) for row in documents], "storage": str(store.path)})
+        emit({"status": "ready" if project else "not_initialized", "project": dict(project) if project else None, "documents": [dict(row) for row in documents], "storage": store.storage_label})
         return 0 if project else 1
     finally:
         store.close()
@@ -680,7 +688,7 @@ def command_migrate(args: argparse.Namespace) -> int:
     try:
         store.connection.execute("PRAGMA user_version = 1")
         store.connection.commit()
-        emit({"status": "migrated", "schemaVersion": "maggiedash-storage.v1", "storage": str(store.path)})
+        emit({"status": "migrated", "schemaVersion": "maggiedash-storage.v1", "storage": store.storage_label})
         return 0
     finally:
         store.close()

package/bundled-tools/clis/maggie_spirit.py

@@ -0,0 +1,143 @@
+#!/usr/bin/env python3
+"""maggie_spirit — generate an AI brand's pixel spirit (sprite) system.
+
+One flat-pixel visual language for an agent brand:
+  * a logo "mark" that animates through a fixed 32-state base set, and
+  * per-agent avatar faces that animate through the same 32 states.
+
+Everything is deterministic (seeded by accent + persona) and self-contained
+(Pillow only). See skills/maggie-spirit/SKILL.md for the workflow.
+
+Subcommands:
+  mark   --out DIR [--name mark] [--accent #ff1212] [--title ONEMAN] [--scale 9]
+         Logo mark + 32-state animated base set + sprite sheet + states.json.
+  agent  --out DIR --name cto --accent #3b82f6 --spec persona.json
+         One agent avatar animated through all 32 states (+ sheet + states.json).
+  avatar --out FILE.png --accent #3b82f6 --spec persona.json [--scale 10]
+         A single still avatar face (no animation).
+  demo   --out DIR
+         The reference spirit base set: the default mark + 8 example agents +
+         founder — a starter kit to copy and recolour.
+
+persona.json (agent/avatar), all keys optional except noted:
+  {"gender":"m|f","hair":"#2a2018","skin":"light|mid|tan|deep",
+   "hairstyle":"short|slick|spiky|buzz|longwavy|longstraight|longbob|ponytail",
+   "eyes":"round|wide|lash|happy","mouth":"flat|smile|smirk|lips|open",
+   "prop":"glasses|shades|cigar|headset|earbuds|monocle|pen|bandana",
+   "propcol":"#f2c75a","hoodie":true,"band":"#e23b3b","mask":"#12201a","specs":true}
+"""
+import argparse, json, os, sys
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+RUNTIME = os.path.normpath(os.path.join(HERE, "..", "runtime"))
+if RUNTIME not in sys.path:
+    sys.path.insert(0, RUNTIME)
+
+try:
+    import spirit_base as B
+    import spirit_face as F
+    import spirit_agent as A
+except ImportError as e:  # pragma: no cover
+    sys.stderr.write(
+        "maggie_spirit needs Pillow and the spirit_* runtime modules.\n"
+        f"  {e}\n  pip install pillow\n")
+    raise SystemExit(2)
+
+
+def _load_spec(path):
+    if not path:
+        return {}
+    with open(path, "r", encoding="utf-8") as fh:
+        spec = json.load(fh)
+    if not isinstance(spec, dict):
+        raise SystemExit("persona spec must be a JSON object")
+    return spec
+
+
+def cmd_mark(a):
+    B.OUT_BASE = os.path.abspath(a.out)
+    os.makedirs(B.OUT_BASE, exist_ok=True)
+    meta = B.generate(B.Motif.oneman(), accent=a.accent, out=a.name,
+                      title=a.title, scale=a.scale)
+    print(f"{a.title}: {len(meta['states'])} states -> {os.path.join(a.out, a.name)}/")
+    print("groups:", ", ".join(meta.get("groups", [])))
+
+
+def _persona(spec):
+    gender = spec.get("gender", "m")
+    params = {k: v for k, v in spec.items() if k != "gender"}
+    params.setdefault("hair", "#1c1c22")
+    params.setdefault("skin", "mid")
+    return gender, params
+
+
+def cmd_agent(a):
+    A.OUT_BASE = os.path.abspath(a.out)
+    os.makedirs(A.OUT_BASE, exist_ok=True)
+    gender, params = _persona(_load_spec(a.spec))
+    meta = A.gen_agent(a.name.lower(), a.accent, gender, params, scale=a.scale)
+    print(f"{a.name} {a.accent} {gender}: {len(meta['states'])} states -> "
+          f"{os.path.join(a.out, a.name.lower())}/")
+
+
+def cmd_avatar(a):
+    gender, params = _persona(_load_spec(a.spec))
+    img = F.render(F.face(a.accent, gender=gender, **params), a.scale)
+    out = os.path.abspath(a.out)
+    os.makedirs(os.path.dirname(out) or ".", exist_ok=True)
+    img.save(out)
+    print(f"avatar -> {a.out} ({img.size[0]}x{img.size[1]})")
+
+
+def cmd_demo(a):
+    base = os.path.abspath(a.out)
+    os.makedirs(base, exist_ok=True)
+    B.OUT_BASE = base
+    A.OUT_BASE = base
+    B.generate(B.Motif.oneman(), accent="#ff1212", out="oneman", title="ONEMAN")
+    made = ["oneman (mark)"]
+    for role, acc, g, p in list(F.CAST) + [F.FOUNDER]:
+        A.gen_agent(role.lower(), acc, g, p)
+        made.append(role.lower())
+    print(f"spirit base set -> {a.out}/")
+    print("generated:", ", ".join(made))
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_spirit", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    m = sub.add_parser("mark", help="logo mark + 32-state animated base set")
+    m.add_argument("--out", required=True)
+    m.add_argument("--name", default="mark")
+    m.add_argument("--accent", default="#ff1212")
+    m.add_argument("--title", default="ONEMAN")
+    m.add_argument("--scale", type=int, default=9)
+    m.set_defaults(fn=cmd_mark)
+
+    ag = sub.add_parser("agent", help="one agent avatar through all 32 states")
+    ag.add_argument("--out", required=True)
+    ag.add_argument("--name", required=True)
+    ag.add_argument("--accent", required=True)
+    ag.add_argument("--spec", help="persona.json")
+    ag.add_argument("--scale", type=int, default=8)
+    ag.set_defaults(fn=cmd_agent)
+
+    av = sub.add_parser("avatar", help="a single still avatar face")
+    av.add_argument("--out", required=True)
+    av.add_argument("--accent", required=True)
+    av.add_argument("--spec", help="persona.json")
+    av.add_argument("--scale", type=int, default=10)
+    av.set_defaults(fn=cmd_avatar)
+
+    d = sub.add_parser("demo", help="reference spirit base set (mark + examples)")
+    d.add_argument("--out", required=True)
+    d.set_defaults(fn=cmd_demo)
+
+    a = ap.parse_args(argv)
+    a.fn(a)
+
+
+if __name__ == "__main__":
+    main()