@topy-ai/maggie 0.7.61 → 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.7.61`，包含 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.7.61` — safe patching. `maggie security fix-plan` tags every action with a **fix-risk tier** T1–T4 — whether a patch is safe to apply, not just what to patch: T1 batch-safe distro/permission fixes, T2 restart+smoke-test, T3 config hardening that validates and auto-rolls-back, T4 major/EOL moves emitted as accepted-risk drafts to stage first. New `maggie security host-impact` (read-only) measures each patch's **blast radius** — which pending updates are security-only, which running services must restart to make a fix live (`needrestart`), and whether a reboot is pending — and feeds it back into the plan.
+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
@@ -111,7 +111,7 @@ interactive-only and never probes, submits or scans; the active scanners
 (`web-scan`, `zap-baseline`) and host checks stay verified-only.
 
 The 0.7.56 release added Maggie Security, a new
-`maggie-security` skill and `maggie security` command family (49 commands, 30
+`maggie-security` skill and `maggie security` command family (51 commands, 35
 MCP tools, 7 contracts under `contracts/maggie-security/`).
 
 - **Advisories for the whole stack.** Packages (npm, pnpm, Yarn, Bun,
@@ -858,8 +858,8 @@ artifact schemas.
 Recommended upgrade sequence for the current release:
 
 ```bash
-npx @topy-ai/maggie@0.7.61 update --scope project --project . --force
-npx @topy-ai/maggie@0.7.61 cleanup --scope project --project .
+npx @topy-ai/maggie@0.8.0 update --scope project --project . --force
+npx @topy-ai/maggie@0.8.0 cleanup --scope project --project .
 ```
 
 Maintainers should pass npm credentials through the repository helper, never

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-security/SKILL.md

@@ -31,16 +31,22 @@ Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and c
 3. `maggie security doctor --fix` — creates `.maggie/security/config.json` and
    keeps `.maggie/security/` out of git.
 
+Then `maggie security scan` runs the right detectors for the detected profile and
+builds a report in one step (add `--domain` for the web checks and
+`--ssh ALIAS=user@host` for the host checks once consent is granted). Use the
+individual commands below when you want one area, or `scan` for the whole sweep.
+
 ## What to run
 
 | The user wants… | Run | MCP tool |
 |---|---|---|
+| "do a full security check" / "scan my site" | `maggie security scan` — detects the profile, runs the right detectors (inventory → vulns, deps, secrets, code, EOL; add `--domain` for headers/tls, `--ssh ALIAS=user@host` for host checks), then builds a report. Add `--fix-plan` for a remediation runbook. Each detector is best-effort. | `security_scan` |
 | "anything new I should worry about?" | `maggie security vuln-watch` then `maggie security eol-watch` | `security_vuln_watch`, `security_eol_check` |
 | "are we affected by CVE-X?" | `maggie security osv-query --id CVE-X`; for a runtime/OS: `maggie security advisory --cve CVE-X --component php` → [CVE response](references/cve-response.md) | `security_osv_query`, `security_findings_list` |
 | "is package X safe?" | `maggie security osv-query --purl pkg:npm/x@1.2.3` | `security_osv_query` |
 | "is our WordPress / plugin safe?" | `maggie security wp-check` | `security_wp_check` |
 | "is our PHP / MySQL / Ubuntu / Node still supported?" | `maggie security eol-watch` (`--product php=8.1` without an inventory) | `security_eol_check` |
-| "Node.js security releases" | `maggie security node-check` | `security_eol_check` |
+| "Node.js security releases" | `maggie security node-check` | `security_node_check` |
 | "check before deploy" / CI gate | `maggie security deps --ci`, `maggie security secrets --ci`, then `maggie security report --kind gate --output .maggie/security/gate.json` and `maggie deployment readiness --security-report .maggie/security/gate.json` | `security_deps_scan`, `security_secrets_scan`, `security_report_build` |
 | "did a key or password leak?" | `maggie security secrets` (git history, project files, build output) | `security_secrets_scan` |
 | "are my dependencies safe?" | `maggie security deps` (every lockfile ecosystem + JavaScript copied into the site) | `security_deps_scan` |
@@ -50,12 +56,14 @@ Follow [Maggie Memory Hook](../../references/memory-hook.md) at invocation and c
 | "are we being attacked / were we hacked?" | `maggie security logs-traffic --file access.log`, `maggie security logs-sigma --file access.log`, `maggie security logs-ioc --file access.log`; servers: `maggie security logs-remote --ssh web1=user@host` | `security_logs_check` |
 | "is my server hardened?" | `maggie security host-quick --ssh web1=user@host` (or `--print-collector` for the person to run), `maggie security host-nginx-config --ssh web1=user@host`, deep: `maggie security host-audit --ssh web1=user@host` | `security_host_check` |
 | "protect my server" (CrowdSec / fail2ban / Cloudflare) | `maggie security protect-plan --host web1 [--engine crowdsec\|fail2ban]` → the person reviews and runs it under the host lock; afterwards `maggie security protect-plan verify --plan FILE --ssh web1=user@host` | `security_protect_plan` |
-| "give me the fixes to run" | after the checks: `maggie security fix-plan --script fix.sh --output RUNBOOK.md` — a reviewed runbook (file permissions, firewall, apt updates, intrusion prevention, nginx, EOL) built from the findings, each action tagged with a fix-risk tier T1–T4 (T1 batch-safe → T3 validate+auto-rollback → T4 stage-first/accepted-risk) so the operator knows what is safe to batch vs what must be tested first; the person reviews it and runs it themselves under the host lock. Maggie never applies it. Run `maggie security host-impact` first so the plan is blast-radius-aware (which services a patch affects, what must restart, whether a reboot is pending). | — |
+| "give me the fixes to run" | after the checks: `maggie security fix-plan --script fix.sh --output RUNBOOK.md` — a reviewed runbook (file permissions, firewall, apt updates, intrusion prevention, nginx, EOL) built from the findings, each action tagged with a fix-risk tier T1–T4 (T1 batch-safe → T3 validate+auto-rollback → T4 stage-first/accepted-risk) so the operator knows what is safe to batch vs what must be tested first; the person reviews it and runs it themselves under the host lock. Maggie never applies it. Run `maggie security host-impact` first so the plan is blast-radius-aware (which services a patch affects, what must restart, whether a reboot is pending). | `security_fix_plan` |
+| "track a CVE response / log an incident" | `maggie security incident start --title … --cve …`, then `incident log --id … --event … --note …`, and `incident close --id …`; read the timeline in `report --kind incident`. Local records only — no server or site is changed. | `security_incident` |
 | "monitor uptime / tell me when the site is down" | `maggie security uptime-init` (verified domains) → `maggie security uptime-deploy --hostname status.example.com` (plan) → `maggie security uptime-status --gatus URL`; jobs report with `maggie security uptime-push` | `security_uptime_status` |
 | "how do we compare to OWASP?" / "threat model" | `maggie security checklist --level 1`, `maggie security threat-model --include-findings` | `security_checklist_get`, `security_threat_model` |
 | "is this npm package safe to add?" | `maggie security preinstall PKG[@VERSION]` before installing (W5); never install on `block` | `security_package_vet` |
 | "is this skill / MCP server safe to install?" | `maggie security skills-scan PATH` (or `--kind mcp-registry`); `maggie security mcp-self-check` for our own MCP | `security_skills_scan`, `security_mcp_self_check` |
 | "any malicious package in the project?" / container image / SBOM | `maggie security exposure-check`, `maggie security image REF`, `maggie security sbom` | `security_exposure_check`, `security_image_scan`, `security_sbom_build` |
+| "patch the container image" | `maggie security image-patch REF [--report trivy.json]` — a reviewed copa plan to rebuild the image with its OS-package fixes into a new tag; the operator runs it (needs Docker/buildkit). Maggie never runs copa. | `security_image_patch` |
 | "what does GitHub say?" | export alerts with github-mcp-server (read-only toolsets) and run `maggie security github-alerts --from-file alerts.json --repo OWNER/NAME` | — |
 | "security report" | `maggie security report --kind weekly` (`--audience technical` for developers) | `security_report_build` + `report_save` |
 | "we accept this risk" / "that's a false positive" | `maggie security ledger accept --id … --reason … [--until YYYY-MM-DD]` — only when the person says so | `security_ledger_mark` |

package/bundled-skills/maggie-security/references/commands.md

@@ -8,6 +8,12 @@ Exit codes: 0 ok · 1 findings at/above `--fail-on` · 2 usage · 3 degraded
 (a source or tool did not answer) · 4 refused by policy · 5 scanner missing
 or checksum mismatch.
 
+## Scan (one-shot orchestrator)
+
+| Command | What it does |
+|---|---|
+| `maggie security scan [--profile TYPE] [--domain D] [--ssh ALIAS=user@host] [--kind weekly\|daily_ops] [--fix-plan] [--offline]` | Detects the site profile (or `--profile`), runs the detectors that profile expects (inventory → vuln-watch, deps, secrets, code-scan, eol-watch, and wp-check/node-check by profile; adds headers/tls when `--domain` is given and host-quick/host-impact when `--ssh` is given), then builds a report. Each detector runs in its own process, best-effort — one that degrades or refuses does not abort the scan. Interactive/heavy commands (web-scan, zap-baseline, host-audit, public-check, logs-remote) are never auto-run. Exposed over MCP as `security_scan`. |
+
 ## Housekeeping
 
 | Command | What it does |
@@ -48,7 +54,7 @@ findings never leave the machine.
 | Command | What it does | Contacted |
 |---|---|---|
 | `maggie security domain-verify start\|check\|status\|revoke --domain D [--method dns\|file]` | proves control of the registrable domain (TXT seen by the system resolver **and** DNS-over-HTTPS) or one host (file); valid 90 days, re-checked weekly | system resolver, cloudflare-dns.com, the site |
-| `maggie security headers --url U [--paths / /login] [--serving auto\|nginx\|apache\|cloudflare\|headers-file\|astro\|next\|php]` | grades security headers and cookies per path (ASVS 5.0 ids), plain-HTTP redirect, fix snippets for the serving layer; a new CSP is always suggested as Report-Only first | the site |
+| `maggie security headers --url U [--paths / /login] [--serving auto\|nginx\|apache\|cloudflare\|headers-file\|astro\|next\|php]` | grades security headers and cookies per path (ASVS 5.0 ids), plain-HTTP redirect, fix snippets for the serving layer; a new CSP is always suggested as Report-Only first. Emits a **letter grade A+…F** (an info finding, score 0–100) using the mdn-http-observatory additive model, so owners see "you are a C → here is how to reach a B" | the site |
 | `maggie security tls --host H [--engine auto\|testssl\|native] [--ip ORIGIN]` | certificate trust and expiry, TLS 1.0/1.1 still accepted, TLS 1.3 missing; testssl.sh (GPL, installed by the person) when present | the site |
 | `maggie security web-scan --url U [--profile safe\|full-safe]` | httpx fingerprint, then nuclei with the safe profile (no intrusive, fuzz, DoS, brute-force, OAST templates; ≤ 10 req/s; one scan per domain at a time) | the site |
 | `maggie security zap-baseline --url U` | weekly passive ZAP baseline in Docker; header rules skipped (headers covers them) | the site |
@@ -71,7 +77,7 @@ checks stay verified-only — do not run them against a site you do not control.
 
 | Command | What it does |
 |---|---|
-| `maggie security code-scan [--changed-since REF] [--rules maggie\|DIR] [--baseline FILE\|--write-baseline FILE]` | semgrep (LGPL, installed by the person, `--metrics=off`) with Maggie's 22-rule pack for Astro, React/Next, Node, PHP/WordPress, Dockerfile, nginx, plus native checks for root containers and served dotfiles; registry rules are refused |
+| `maggie security code-scan [--changed-since REF] [--rules maggie\|DIR] [--baseline FILE\|--write-baseline FILE]` | semgrep (LGPL, installed by the person, `--metrics=off`) with Maggie's 22-rule pack for Astro, React/Next, Node, PHP/WordPress, Dockerfile, nginx, plus native checks for root containers, served dotfiles, and **personal data written to logs** (GDPR / CWE-532, a privacy rule reimplemented from Bearer's patterns since Bearer itself is Elastic-licensed and cannot be run); registry rules are refused |
 
 ## Logs (read where they are; never uploaded)
 
@@ -92,7 +98,6 @@ Formats: nginx/Apache combined and vcombined, Caddy JSON, Cloudflare Logpush JSO
 | `maggie security host-nginx-config --ssh web1=user@host \| --evidence FILE` | nginx -T and php -i rules: hidden files, PHP in uploads, PATH_INFO, old TLS/weak ciphers, HSTS, add_header inheritance, WordPress login limits, xmlrpc, key permissions | ssh-read |
 | `maggie security host-audit --ssh web1=user@host \| --evidence report.dat` | lynis (GPL, external) uploaded to a private /tmp folder under the host lock, removed afterwards (verified); hardening index and warnings | ssh-temp-write |
 | `maggie security host-impact --ssh web1=user@host \| --evidence FILE \| --print-collector` | patch **blast radius** (read-only): which pending updates are security-only (`apt-get -s upgrade` origin parsing) vs not, which running services still use pre-update libraries and must restart (`needrestart -b` — a patched library in memory is still the old one until restart), whether a reboot is pending (`/var/run/reboot-required` + kernel comparison), and the port→process map. Writes `inventory/impact.json`, which `fix-plan` reads to sharpen its risk tiers and restart steps. Techniques ported from PatchMon (MIT). | ssh-read |
-| `maggie security incident start\|log\|close\|show\|list` | timeline for a CVE response; `report --kind incident` prints it | none |
 
 ## Protect and assure
 
@@ -105,6 +110,7 @@ Formats: nginx/Apache combined and vcombined, Caddy JSON, Cloudflare Logpush JSO
 | `maggie security waf-replay --log access.log [--paranoia 2] [--threshold 5] [--exclude-bots]` | replays the log through Coraza + OWASP CRS v4 offline (helper `maggie-waf-replay`); share of real visitors each paranoia level would block, rules needing exclusions; feeds `protect-plan --replay-report` |
 | `maggie security sbom [--engine native\|syft] [--image REF]` | CycloneDX 1.5 SBOM |
 | `maggie security image REF` | trivy (vulns, secrets without values, misconfig, EOL base) + dockle |
+| `maggie security image-patch REF [--report trivy.json] [--tag OUT] [--pkg-types os\|os,library] [--script FILE]` | a reviewed **copa** plan to rebuild the image with its OS-package security fixes applied, into a **new tag** (the original image is untouched). Completes the safe-patching story for containers. Plan only — Maggie never runs copa; the operator runs it where Docker/buildkit is available. Exposed over MCP as `security_image_patch`. |
 | `maggie security preinstall PKG[@V] [--threshold strict]` | npm package vetting: age, version age, install scripts, typosquats, OSV MAL-/vulns, Scorecard; never installs |
 | `maggie security exposure-check [--root DIR] [--deep] [--catalog-dir DIR]` | malicious packages already installed (OSV MAL- and incident catalogs) |
 | `maggie security skills-scan PATH [--kind mcp-registry] [--max-risk 50]` | SkillSpector (installed by you, `--no-llm` forced) |
@@ -124,4 +130,5 @@ Formats: nginx/Apache combined and vcombined, Caddy JSON, Cloudflare Logpush JSO
 |---|---|
 | `maggie security report --kind weekly\|daily_ops\|incident\|gate [--audience owner\|technical] [--save]` | Markdown + JSON report from the latest runs; `--save` writes the `report_save` payload |
 | `maggie security fix-plan [--priority p0..p4] [--script fix.sh] [--output RUNBOOK.md]` | a reviewed remediation runbook from the open findings: grouped by category (file permissions, firewall, package/apt updates, intrusion prevention, web-server config, EOL), each step the commands the findings themselves carry (never invented). Every action is tagged with a **fix-risk tier** (T1 batch-safe distro/permission fixes → T2 restart+smoke-test → T3 config hardening that validates and auto-rolls-back → T4 major/EOL moves that are NOT auto-applied and are emitted as accepted-risk drafts to stage first); the apt batch backs up package state and verifies afterwards. If `host-impact` has run, the plan also shows the **blast radius** (which services each patch affects, what must restart, whether a reboot is pending) and its apt verify step restarts the services still running pre-update libraries. Writes a shell script you run yourself, under `maggie deployment host-lock`, after a backup and with a second SSH session open. Maggie never applies it. |
+| `maggie security incident start\|log\|close\|show\|list` | timeline for a CVE response or other incident (local records only); `report --kind incident` prints the timeline. Exposed over MCP as `security_incident` (write actions need the preview→confirm handshake). |
 | `maggie security mcp [--tools p0\|all] [--print-config claude\|codex]` | local stdio MCP server |

package/bundled-skills/maggie-security/references/explaining-findings.md

@@ -6,6 +6,13 @@ Four parts, plain words, one action per finding:
 
 Urgency words: p0 today · p1 this week · p2 this month · p3 when convenient · p4 for information.
 No CVSS vectors, purls or rule ids for site owners; keep them for developers.
+
+The technical report also shows an **SSVC decision** per action — a defensible
+"do it now vs watch it" call from the signals we already have (CISA SSVC, a
+simplification of the deployer tree): **Act** (actively exploited — KEV — with high
+impact), **Attend** (automatable — high EPSS — and high impact), **Track\*** (high
+impact but no exploitation yet) or **Track** (routine). It is a rationale, not a new
+severity; owners still see the plain urgency words above.
 Name components the way the owner sees them (the plugin's name in WordPress,
 "your database (MySQL 5.7)", "the server's operating system (Ubuntu 20.04)").
 

package/bundled-skills/maggie-security/references/tools-and-licences.md

@@ -13,4 +13,12 @@ required ones (for example nuclei `-ni -duc`).
 | external-only | GPL, LGPL | installed by the person from upstream; called as a separate process |
 | reference-only | AGPL, BSL, ELv2 | design reference; not run by Maggie |
 
+Ported methods (data/algorithm, not bundled code):
+- The HTTP security-header **letter grade** in `maggie security headers` uses the
+  additive score model and grade chart from
+  [mdn-http-observatory](https://github.com/mdn/mdn-http-observatory) (MPL-2.0),
+  reimplemented as a Python data table.
+- Patch **blast-radius** and **fix-risk** handling in `host-impact`/`fix-plan`
+  follow [PatchMon](https://github.com/PatchMon/PatchMon) (MIT) techniques.
+
 Packaged data and its attribution: [data/LICENSE-NOTICE.md](../data/LICENSE-NOTICE.md).