@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/admin/skills/skill-builder/references/lean-pattern.md

@@ -0,0 +1,110 @@
+# Lean SKILL.md Pattern
+
+Skills teach agents specialised capabilities. Each skill is a directory containing a `SKILL.md` file and optional `references/` subdirectory.
+
+## Directory Structure
+
+```
+skills/
+  my-skill/
+    SKILL.md              <- Main file (lean index)
+    references/
+      detailed-guide.md   <- Loaded on demand
+      templates.md
+```
+
+## SKILL.md Template
+
+```markdown
+---
+name: my-skill
+description: "One-line summary of what this skill does — used for agent routing."
+---
+
+# My Skill
+
+Applies when [activation conditions].
+
+## When to Activate
+
+- [Trigger condition 1]
+- [Trigger condition 2]
+
+## Behaviour
+
+[Concise rules — keep this section short. Move detailed procedures to references.]
+
+## References
+
+Load `references/detailed-guide.md` for [what it covers].
+Load `references/templates.md` for [what it covers].
+```
+
+## Principles
+
+1. **SKILL.md is an index, not a manual.** Keep it under 30 lines of instructions. The agent reads it on every activation — bloated skills waste context.
+
+2. **References hold the detail.** Procedures, templates, data formats, and examples go in `references/`. The agent loads them on demand.
+
+3. **Frontmatter is required.** Every SKILL.md must start with YAML frontmatter containing `name` and `description`. Missing `description` causes the skill to be silently skipped.
+
+4. **Description drives routing.** The description is injected into the agent's prompt as part of the available skills list. Make it specific enough that the agent activates the skill for the right messages.
+
+5. **Behaviour, not data.** Skills define how the agent should act. Business-specific data (pricing, customer info, hours) belongs in memory, not in the skill file. Skills are generic; memory is specific.
+
+## Available Icon Names
+
+These are [Lucide](https://lucide.dev) icon names. Choose one that reflects the skill's purpose:
+
+`Zap` · `Globe` · `BookOpen` · `Calendar` · `Camera` · `Clock` · `Cloud` · `Code` · `Database` · `FileText` · `Headphones` · `Heart` · `Home` · `Image` · `Mail` · `Map` · `MessageSquare` · `Music` · `Phone` · `Puzzle` · `Search` · `Settings` · `ShoppingCart` · `Star` · `Tag` · `Truck` · `User` · `Wallet` · `Wrench` · `Cpu`
+
+Any valid Lucide icon name works — this list is a starting point, not a constraint.
+
+## Examples
+
+### Simple skill (no references)
+
+```markdown
+---
+name: weather
+description: "Provide weather context for scheduling and outdoor work decisions."
+---
+
+# Weather
+
+When scheduling or planning outdoor work, check weather conditions.
+
+## When to Activate
+
+- Customer asks about weather
+- Scheduling outdoor appointments
+- Weather might affect planned work
+
+## Behaviour
+
+Use the `web_search` tool to check current weather for the business location.
+Keep weather info brief — one or two sentences unless asked for detail.
+```
+
+### Lean skill with references
+
+```markdown
+---
+name: event-management
+description: "Manage anything time-bound: appointments, meetings, reminders, follow-ups."
+---
+
+# Event Management
+
+Applies when handling anything time-bound.
+
+## When to Activate
+
+- Customer requests or confirms an appointment
+- Business owner asks to schedule, reschedule, or cancel something
+- A reminder or follow-up needs to be recorded
+
+## References
+
+Load `references/events.md` for the standard event template, file naming, and calendar query instructions.
+```

package/payload/platform/plugins/admin/skills/skill-builder/references/pdf-generation.md

@@ -0,0 +1,30 @@
+# PDF Generation in Skills
+
+When a skill needs to produce a PDF, the output is always a two-stage process: the skill authors the HTML, and the personal-assistant renders it to PDF via the `browser_pdf_save` MCP tool.
+
+## The rule
+
+Never instruct the agent to write or execute raw Node.js scripts (e.g. `require('playwright')`, `page.pdf()`, `npx playwright`). Playwright is not in the Node.js module path — these scripts fail with MODULE_NOT_FOUND, waste tool calls searching the filesystem, and produce hardcoded paths that break on reinstall.
+
+Instead, skills that produce PDFs should:
+
+1. **Build the HTML** — the skill's behaviour section describes what the document contains and how it's structured. The agent writes the HTML file using standard file tools.
+2. **Delegate rendering to personal-assistant** — the agent asks the personal-assistant to navigate to the HTML file and call `browser_pdf_save` to produce the PDF. The specialist has Playwright access through governed MCP tools; the admin agent does not.
+
+## Print-ready HTML constraints
+
+HTML intended for PDF output must follow print-ready layout patterns. The most common failures when agents design their own pagination are rigid fixed-height page divs (causing whitespace gaps) and `position: fixed` hacks for headers/footers (causing overlap and duplication).
+
+**Continuous flow layout** — content flows naturally. Use `@page` margin rules for page margins, not wrapper divs with fixed heights. Use `page-break-inside: avoid` on logical units (cards, tables, stat groups) and `page-break-before: always` on major section dividers.
+
+**Page numbers and running footers** — use `@page` margin boxes (`@bottom-center { content: counter(page); }`), not JavaScript or position-fixed elements.
+
+**Dark backgrounds in print** — browsers strip background colours by default. Add `print-color-adjust: exact; -webkit-print-color-adjust: exact;` to dark elements in `@media print`.
+
+**Cover and back pages** — full-bleed pages use `height: 100vh; page-break-after: always;` in `@media print` with zero `@page` margins (via `@page :first` for covers, named pages for back pages).
+
+**Glassmorphism and backdrop-filter** — these do not survive browser print rendering. Any section using glassmorphism needs a pre-rendered PNG fallback image that is hidden on screen and shown only in `@media print`.
+
+## What the skill file should contain
+
+The skill's SKILL.md describes the document's purpose and structure. A `references/` file holds the HTML template or content specification. The skill should state that PDF rendering is delegated to personal-assistant — it should not contain Playwright code, npm commands, or file path assumptions about the Playwright installation.

package/payload/platform/plugins/admin/skills/specialist-management/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: specialist-management
+description: "Install, remove, and manage specialist subagents and premium plugin agents."
+---
+
+# Specialist Management
+
+Manage specialist subagents at any time via conversation.
+
+## Install a specialist
+
+1. Use Bash: `cp $PLATFORM_ROOT/templates/specialists/agents/{name}.md specialists/agents/{name}.md`
+2. Ensure `agents/admin/AGENTS.md` exists; create if absent.
+3. Read `agents/admin/AGENTS.md`, then append: `- **specialists:{name}**: {one-line delegation rule}` using Edit.
+4. Confirm to the user — active from next session start.
+
+## Remove a specialist
+
+1. Use Bash: `rm specialists/agents/{name}.md`
+2. Read `agents/admin/AGENTS.md`, then remove the specialist's line using Edit — match the full line: `- **specialists:{name}**: ...`.
+3. Confirm to the user.
+
+## Premium plugin agents
+
+Premium plugins can include an `agents/` directory alongside `skills/` and `references/`. Agent files use the naming convention `{plugin-name}--{agent-name}.md` — the double-dash separator prevents collisions with core specialists, which never contain `--`.
+
+### Activate premium plugin agents
+
+For each `.md` file in `$PLATFORM_ROOT/plugins/{plugin-name}/agents/`:
+
+1. Check whether `specialists/agents/{filename}` already exists — skip if so (idempotent).
+2. Use Bash: `cp $PLATFORM_ROOT/plugins/{plugin-name}/agents/{filename} specialists/agents/{filename}`
+3. Extract the `name` and `description` fields from the copied file's YAML frontmatter.
+4. Read `agents/admin/AGENTS.md`. If it already contains `specialists:{name}`, skip. Otherwise append: `- **specialists:{name}**: {description}` using Edit.
+5. Confirm each installed specialist to the user — active from next session start.
+
+### Deactivate premium plugin agents
+
+1. Use Bash: `ls specialists/agents/{plugin-name}--*.md` to list matching files.
+2. For each match, use Bash: `rm specialists/agents/{filename}`
+3. Read `agents/admin/AGENTS.md`, then remove each matching line using Edit — match by `specialists:{name}` where `{name}` is extracted from the removed file's frontmatter `name` field.
+4. Confirm removal to the user.
+
+Core specialists (files without `--` in the name) are never affected by premium plugin operations.

package/payload/platform/plugins/admin/skills/stream-log-review/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: stream-log-review
+description: >
+  Analyse a Claude agent stream log file for errors, warnings, and anomalies.
+  Produces a structured diagnostic report with session-by-session breakdown,
+  root-cause analysis for known patterns, and cost/usage summary.
+  Trigger phrases: "review logs", "stream log", "log errors", "log review",
+  "what went wrong", "diagnose the log", "log report".
+---
+
+# Stream Log Review
+
+Analyse Claude agent stream logs — the `claude-agent-stream-{conversationId}.log` files generated by the platform. Each file is scoped to exactly one conversation; a resumed conversation accumulates in one file across multiple process lifetimes, delimited by `[spawn]` / `[process-exit]`. Pre-conversation events (CDP auth-poll, module-init warnings) live in `preconversation-claude-agent-stream-{YYYY-MM-DD}.log` — a separate file per UTC day, read only when investigating boot-time failures.
+
+Parse the log, identify problems, attempt diagnosis, and produce a structured report.
+
+## When to Activate
+
+- Admin asks to review, diagnose, or analyse a stream log
+- A log file path is provided for analysis
+- Admin asks what went wrong in a session or across sessions
+
+## What a Good Report Looks Like
+
+- Covers every session in the log, segmented by session boundaries
+- Every error and warning is classified by severity with a root-cause diagnosis where patterns are known
+- Errors that repeat across sessions are grouped and counted, not listed individually
+- Causal chains are identified (e.g. DNS failure leading to retry loop leading to context overflow)
+- Cost and token usage are summarised per session and in aggregate
+- Recommendations are actionable — grouped by bugs to fix, infrastructure issues, and agent behaviour problems
+- A non-technical admin can scan it for severity; a developer can use it to prioritise fixes
+
+## Log Retrieval
+
+On the Pi, use the `logs-read` MCP tool with `conversationId` to retrieve a single conversation's log. From the dev machine (SSH), use the shell counterpart:
+
+```bash
+# Read a single conversation's stream log (primary mode)
+sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh <conversationId> system"
+
+# Tail the most-recently-active stream log (any conversation)
+sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh --tail system 200"
+
+# Legacy: grep sessionKey across all log files (backward compat)
+sshpass -p 'password' ssh admin@<hostname>.local "~/<installDir>/platform/scripts/logs-read.sh --grep <sessionKey>"
+```
+
+The `conversationId` is visible in the admin UI and appears on every `[spawn]` / `[process-exit]` line in the log itself. A single `logs-read.sh <conversationId> system` returns the full conversation-scoped record — no grep filter required, no cross-file correlation.
+
+## What to Look For
+
+- `[tool-wait]` lines every 5 s between `[tool-use]` and `[tool-result]` — distinguishes API silence from tool-internal stall.
+- `[tool-wait-diag]` at 15 / 30 / 45 / 60 s — confirms DNS/TCP/HTTP health across a stall window (not just at the timeout moment).
+- `[tool-wait-proc]` at 30 s — subprocess open FDs, sockets by TCP state, RSS.
+- `[subproc-stderr]` — line from the main Claude Code subprocess's stderr. Today the CLI is a bundled Bun binary that ignores Node's `NODE_DEBUG`, so this channel is normally silent — see `[subproc-debug-unavailable]` below. MCP server stderr lines arrive separately as `[mcp:<server>]`.
+- `[subproc-stderr-tee-attached]` / `[subproc-stderr-tee-detached]` — lifecycle of the main-subprocess stderr tee. `bytes=0 lines=0` on detach means the tee worked but the subprocess emitted nothing. Absence of both markers next to a `[spawn]` means the tee infrastructure is broken — escalate.
+- `[subproc-debug-unavailable]` — one line per spawn, `reason=bundled-bun-binary-ignores-node-debug`. This is the documented reason `[subproc-stderr]` lines are normally absent for the main subprocess. Treat its absence as a regression, not its presence as a problem.
+- `[tool-failure-diag]` — one-shot probe on the failure path; complements the mid-flight `[tool-wait-diag]` with end-of-wait network state.
+- `[mcp-tee-attach]` / `[mcp-tee-skip]` / `[mcp:<server>]` — MCP server stderr routed into the stream log; a missing attach marker explains missing server diagnostics.
+- `[tool-result] error=true output="WEBFETCH_CANNOT_READ_JS_SPA: …"` — a WebFetch dispatch was short-circuited by the SPA preflight hook. The URL is a JS-SPA shell that WebFetch cannot extract content from. The agent should have responded to the user naming the failure and asking for a paste or screenshot; if instead an `[agent-dispatch]` (Playwright, research-assistant) follows immediately, the loud-failure guidance in IDENTITY.md did not land. The hook's per-invocation decision trail lives in `{accountDir}/logs/webfetch-preflight.log` (one `[webfetch-preflight] verdict=…` line per probe).
+
+## Boundaries
+
+- This skill analyses logs. It does not fix the bugs it finds — that's a separate task.
+- Applies to `claude-agent-stream-{conversationId}.log` files only. SSE event logs and stderr logs are handled by `logs-read` directly.
+- Does not modify or rotate log files.
+- Does not correlate across conversations — each report covers a single conversation's log.
+
+## References
+
+Load `references/analysis-patterns.md` for the event taxonomy, error classification patterns, diagnosis heuristics, and report format template.

package/payload/platform/plugins/admin/skills/stream-log-review/references/analysis-patterns.md

@@ -0,0 +1,189 @@
+# Stream Log Analysis Patterns
+
+## Log Format
+
+Stream logs contain two interleaved formats:
+
+### Bracketed app-level lines
+
+```
+[2026-03-24T08:36:45.445Z] [tag] key=value key=value …
+```
+
+Tags identify the event type. Key tags:
+
+| Tag | Meaning |
+|-----|---------|
+| `managed-spawn` | New session started. Contains `pid`, `sessionKey`, `historyMessages`, `pluginDir`. This is the **session boundary marker**. |
+| `stdin` | Prompt sent to Claude. `len` = character count, `preview` = first N chars. |
+| `init` | MCP servers connected and tool count. |
+| `tool-use` | Agent called a tool. `name` = tool name, `input` = JSON args. |
+| `tool-result` | Tool returned. `name`, `error` (true/false), `output` (truncated). |
+| `usage` | Token counts for this turn. `input`, `cache_create`, `cache_read`, `output`, `reported_window`. |
+| `modelUsage` | Per-model cost breakdown JSON. Contains `costUSD`. |
+| `context-overflow` | Session exceeded context window. Shows percentage and token counts. |
+| `managed-append` | Response appended to session history. `sessionKey`, `historyAfter`, `responseTextLen`. |
+| `unknown-type` | Unhandled stream event type. Usually `rate_limit_event`. |
+| `subagent-start` / `subagent-end` | Specialist subagent dispatched/returned. |
+| `agent-dispatch` / `agent-return` | Agent tool dispatch/return. |
+| `heartbeat` | Long-running session keepalive. |
+| `active` / `disabled` / `unchanged` | Plugin/tool status during init. |
+| `expanded` | Skill or slash command expanded. |
+| `render-component` / `browser-viewer` | UI component rendered in response. |
+
+### Raw JSON lines
+
+```json
+{"type":"system","subtype":"init", ...}
+{"type":"rate_limit_event", ...}
+{"type":"user","message":{...}, ...}
+{"type":"result","subtype":"success", ...}
+```
+
+The `result` event is the **session result**. It contains `is_error`, `duration_ms`, `num_turns`, `total_cost_usd`, `stop_reason`, `usage`, and `modelUsage`.
+
+## Session Segmentation
+
+Each session begins with a `[managed-spawn]` line and ends with either:
+- A `result` JSON line (normal completion)
+- The next `[managed-spawn]` line (if the session crashed without a result)
+
+Extract `sessionKey` from `managed-spawn` and `session_id` from the `result` JSON.
+
+## Conversation Identification
+
+Three independent identifiers trace a conversation through the system:
+
+| Identifier | Scope | Where it lives | Survives restart |
+|------------|-------|-----------------|-----------------|
+| `sessionKey` | Single agent process lifetime | Server memory, stream logs (`sessionKey=XXXXXXXX…`) | No |
+| `conversationId` | Entire conversation (may span multiple sessionKeys) | Neo4j `Conversation` node, stream logs on resume/attribution | Yes |
+| `visitorId` (public) / `userId` (admin) | Visitor or admin identity across conversations | `maxy_visitor` cookie (public), users.json (admin) | Yes |
+
+### Finding the right session in logs
+
+**From the admin UI**: The sessions modal and Claude info panel both display the first 8 characters of `conversationId`. Use `logs-read` with the corresponding `sessionKey` to pull the full timeline.
+
+**From a conversationId**: The stream log lines that link `conversationId` to `sessionKey` are:
+- `[session] conversation attributed: conversationId=XXXX… userId=… admin/…` (new sessions)
+- `[session-resume] updated conversationId to XXXX… for session YYYY…` (resumed sessions)
+- `[session] cold-resume visitor=XXXX… conversation=YYYY…` (public cold resume)
+
+**From a visitorId**: Query Neo4j to find all conversations for a visitor, then trace the `sessionKey` into logs:
+```cypher
+MATCH (c:Conversation {visitorId: $visitorId, accountId: $accountId})
+RETURN c.conversationId, c.sessionKey, c.createdAt
+ORDER BY c.createdAt DESC
+```
+
+**Public agent sessions** use `[public-managed-spawn]` and `[public-managed-append]` tags instead of `[managed-spawn]` / `[managed-append]`. The `sessionKey` field is present in both.
+
+## Error Classification
+
+### Severity: ERROR
+
+These indicate something broke and the agent could not complete the intended action.
+
+| Pattern | How to detect | Known root cause |
+|---------|--------------|-----------------|
+| **MCP tool failure** | `[tool-result] name=mcp__* error=true` | Tool-specific — read the `output` for the error message |
+| **Neo4j LIMIT float** | `error=true` + output contains `'50.0' is not a valid value` | LIMIT parameter passed as float instead of integer. Fix: wrap with `neo4j.int()` |
+| **Bash command not found** | `error=true` + `command not found` | Missing system tool (e.g. `dig`, `nslookup` on Pi). The Pi may not have DNS utilities installed |
+| **Playwright DNS failure** | `error=true` + `net::ERR_NAME_NOT_RESOLVED` | Domain not resolving — DNS not propagated, tunnel not running, or domain misconfigured |
+| **Playwright protocol blocked** | `error=true` + `Access to "file:" URL is blocked` | Agent tried to browse a local file path. Playwright only allows http/https |
+| **Playwright stale ref** | `error=true` + `Ref e* not found in the current page snapshot` | Agent clicked an element reference from an old snapshot without re-snapshotting |
+| **Playwright timeout** | `error=true` + `Timeout *ms exceeded` | Page too slow to render (common on Pi) or font loading stall |
+| **Tool hallucination** | `error=true` + `No such tool available` | Agent invented a tool name that doesn't exist (e.g. missing double underscore in MCP tool name) |
+| **MCP validation error** | `error=true` + `Input validation error` | Agent passed wrong types or missing required fields to an MCP tool |
+| **Cloudflare cert error** | `error=true` + `Could not read certificate` | Cloudflare auth certificate missing or corrupt |
+| **MCP null dereference** | `error=true` + `Cannot read properties of null` | Bug in MCP server code — null check missing |
+
+### Severity: WARNING
+
+These indicate degraded behaviour or potential problems that didn't cause outright failure.
+
+| Pattern | How to detect | Diagnosis |
+|---------|--------------|-----------|
+| **Context overflow** | `[context-overflow]` line | Session used more tokens than the model's context window. The percentage tells you how far over. Above 150% risks truncation and incoherent responses |
+| **Repeated tool errors** | Same tool fails 3+ times in a session | Agent is retrying a broken tool instead of adapting. Check if it's the same error each time (systemic bug) vs different errors (exploratory) |
+| **High cost session** | `total_cost_usd` > $0.50 in a single session result | Unusually expensive — check context overflow and turn count |
+| **Long session** | `duration_ms` > 120000 (2 minutes) | May indicate agent looping or stuck on a task |
+| **Web fetch unavailable** | Tool returns "not available in Phase 0" | Agent tried to use a capability that hasn't been implemented yet |
+| **Rate limit events** | `[unknown-type] type=rate_limit_event` | API rate limit check. `status: "allowed"` is normal. Watch for non-allowed status |
+
+### Severity: INFO (notable but not problems)
+
+| Pattern | How to detect |
+|---------|--------------|
+| **Subagent dispatched** | `[subagent-start]` / `[agent-dispatch]` lines |
+| **Skill expanded** | `[expanded]` line |
+| **UI component rendered** | `[render-component]` / `[browser-viewer]` lines |
+| **Session completed successfully** | `result` JSON with `is_error: false` |
+
+## Diagnosis Heuristics
+
+When multiple errors appear in the same session, look for causal chains:
+
+- **DNS failure → retry loop**: If `ERR_NAME_NOT_RESOLVED` is followed by multiple attempts with different DNS resolution strategies (Bash dig, nslookup, DoH), the agent is trying to diagnose DNS itself. Root cause is always the tunnel or DNS config.
+
+- **Contact-list LIMIT error → retry loop**: If `contact-list error=true` repeats 3+ times in one session, the agent is retrying with the same float parameter. This is a known Neo4j integer bug — the fix is in the MCP server, not the agent's behaviour.
+
+- **Context overflow → degraded behaviour**: If a session has `context-overflow` above 150% AND errors after that point, the overflow likely caused the errors (truncated instructions, lost context).
+
+- **Stale ref → re-snapshot → stale ref**: If `Ref not found` repeats, the agent may not be re-snapshotting between clicks, or the page is dynamically changing.
+
+- **Screenshot timeout cluster**: Multiple `page.screenshot: Timeout` errors indicate Pi performance issues, not agent bugs. The Pi's limited CPU struggles with Playwright rendering.
+
+## Report Format
+
+Structure the report as follows:
+
+```markdown
+# Stream Log Report — [date]
+
+## Summary
+- **Time span**: [first timestamp] → [last timestamp]
+- **Sessions**: [count] total, [errors] with errors, [clean] clean
+- **Total cost**: $[sum of all session costs]
+- **Context overflows**: [count] ([list percentages])
+
+## Errors ([count])
+
+### [Error category name]
+- **Severity**: ERROR
+- **Occurrences**: [count] across [N] sessions
+- **Pattern**: [what happened]
+- **Diagnosis**: [root cause if known, "investigation needed" if not]
+- **Sessions affected**: [session keys or IDs]
+
+[Repeat for each error category]
+
+## Warnings ([count])
+
+### [Warning category name]
+- **Occurrences**: [count]
+- **Pattern**: [what happened]
+- **Impact**: [what this means for the user/system]
+
+[Repeat for each warning category]
+
+## Session Detail
+
+### Session [N] — [sessionKey prefix]
+- **Time**: [start] → [end] ([duration])
+- **Turns**: [count]
+- **Cost**: $[cost]
+- **Result**: [success/error] — [brief outcome from result text]
+- **Issues**: [list of errors/warnings in this session, or "Clean"]
+
+[Repeat for each session]
+
+## Recommendations
+
+[Actionable items derived from the errors and warnings. Group by:
+1. Bugs to fix (code changes needed)
+2. Infrastructure issues (Pi setup, DNS, certificates)
+3. Agent behaviour issues (retry loops, tool misuse)]
+```
+
+Adapt the format to the actual findings — omit empty sections. The goal is a report that a non-technical admin can scan for severity and a developer can use to prioritise fixes.

package/payload/platform/plugins/admin/skills/unzip-attachment/SKILL.md

@@ -0,0 +1,79 @@
+# Unzip Attachment
+
+Safely extract a zip archive the admin has uploaded, inventory its contents, and propose one concrete follow-up per entry class — refusing archives that attempt path traversal, symlink escape, or decompression-bomb pathologies.
+
+**Invoked from `specialists:content-producer`** when the archive is a static-site zip and the brief carries a host-website / publish-site / put-online intent (Task 966) — the specialist chains directly into `publish-site` on the extracted tree. For graph-bound archives (LinkedIn export, conversation transcripts, PDFs etc.), invocation routes via `specialists:database-operator` instead.
+
+## When to Use
+
+Activate when the `[ATTACHMENTS:]` block of the current turn contains an entry whose MIME is `application/zip` or `application/x-zip-compressed`. Every such attachment line carries an `ID: <uuid>  Path: <storagePath>` pair — the `storagePath` is the absolute path to the `.zip` on disk and is the input to this flow.
+
+Do **not** activate for agent-generated zips (those are already trusted — they originate from `storeGeneratedFile`). The MIME allow-list restricts this skill to admin-uploaded archives by construction: no other code path produces a `[ATTACHMENTS:]` line with a zip MIME.
+
+The `[ATTACHMENTS:]` block is contractually present on every turn that originally had attachments, including post-`max-turns-interrupted` recovery retries (Task 915). Do **not** add a filesystem fallback search — the resolved `Path:` line is authoritative.
+
+## Invariants
+
+These are not guidelines. Every one of them is mechanically enforced by the shell primitives below; if any check fails, abort the flow, emit the named log line, and tell the operator verbatim what tripped it.
+
+- **No byte of the archive may land outside `{accountDir}/extracted/{attachmentId}/`.** The destination is fresh per upload. Extraction uses `unzip -oq` into that directory and only that directory.
+- **Sum of declared uncompressed sizes must be ≤ `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in [platform/ui/app/lib/attachments.ts](../../../../ui/app/lib/attachments.ts)).** Checked by summing column 4 of `unzip -Z` output *before* any write.
+- **No entry may be a symlink.** Checked by parsing column 1 of `unzip -Z` output (permission column; leading `l` = symlink) before extraction; the post-extraction loop also runs `find <dest> -type l` as a ground-truth backstop.
+- **No entry name may start with `../`.** Checked by parsing the name column of `unzip -Z` output before extraction; the post-extraction `realpath --relative-to <dest>` loop is a defense-in-depth backstop for `unzip` versions that silently sanitise `../` during extraction.
+- **Password-protected archives are refused with a fixed message.** Detected by column 5 of `unzip -Z` output: a leading uppercase `T` or `B` (text/binary, encrypted) marks an encrypted entry. Never prompt for a key.
+
+See [references/safety.md](references/safety.md) for the precise shell commands, attack examples, and refusal templates.
+
+## Flow
+
+1. **Resolve paths.** From the `[ATTACHMENTS:]` line read `attachmentId` and `storagePath`. Set `dest="${ACCOUNT_DIR}/extracted/${attachmentId}"`. Create it with `mkdir -p "$dest"`.
+2. **Single-pass pre-flight.** One `unzip -Z "$storagePath"` invocation produces the zipinfo column listing; pipe through an awk parser that checks all four invariants in one read of the output. Non-zero exit from `unzip -Z` → corrupt archive, refuse with `unreadable reason=corrupt`. Otherwise the awk gates (in order: encrypted, symlink, zip-slip, oversize) fire the matching refusal log line and exit before extraction. Inline this single bash block — do **not** split into two or more `unzip` calls:
+   ```sh
+   ZINFO=$(unzip -Z "$storagePath" 2>&1) || { echo "[skill:unzip] unreadable attachmentId=$attachmentId reason=corrupt"; exit 1; }
+   echo "$ZINFO" | awk -v aid="$attachmentId" -v lim=$((100*1024*1024)) '
+     NR>2 && $1 ~ /^[-lrwxd?]/ {
+       if ($5 ~ /^[TB]/)           { print "[skill:unzip] unreadable attachmentId=" aid " reason=password"; bad=1; exit }
+       if ($1 ~ /^l/)              { print "[skill:unzip] symlink-blocked attachmentId=" aid " entry=" $9; bad=1; exit }
+       for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { print "[skill:unzip] zip-slip-blocked attachmentId=" aid " entry=" $i; bad=1; exit }
+       sum += $4
+     }
+     END { if (!bad && sum > lim) { print "[skill:unzip] oversize attachmentId=" aid " uncompressed=" sum " limit=" lim; bad=1 }; exit bad }
+   ' || exit 1
+   DECLARED_BYTES=$(echo "$ZINFO" | awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { print s+0 }')
+   ```
+3. **Emit the start log line** — `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n> preflightPasses=1` — exactly once, before the extraction command. The `preflightPasses=1` field is mandatory and always `1`; its absence in `server.log` after a clean upload means the skill was not invoked or step 2 was split into multiple passes (a regression).
+4. **Extract.** `unzip -oq "$storagePath" -d "$dest"`. Non-zero exit → refuse with the underlying `unzip` stderr quoted.
+5. **Post-extraction realpath check.** For every path emitted by `find "$dest" -mindepth 1 \( -type f -o -type l \)`:
+   - If `-type l`, refuse with `symlink-blocked` (ground-truth guard — pre-scan caught most, this catches the rest).
+   - Else compute `realpath --relative-to "$dest" "<entry>"`; if it begins with `../`, refuse with `zip-slip-blocked`.
+6. **Emit the done log line** — `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>`.
+7. **Inventory + propose.** Reply to the operator with: top-level entries (first-level subdirectories and top-level files, up to ~20), total file count, total uncompressed bytes. For each entry class, propose **one** concrete follow-up:
+   - `.md`, `.txt` → "ingest into memory via `memory-ingest`?"
+   - `.png`, `.jpg`, `.pdf` → "re-attach via `file-attach` so the user sees the file?"
+   - unknown / binary / source → list only. No proposal.
+
+On any refusal step the operator gets the refusal message verbatim, no re-try, no silent substitution — per the loud-failure protocol in IDENTITY.md.
+
+## Log lines (grep targets)
+
+| When | Line |
+|------|------|
+| Before extraction | `[skill:unzip] start attachmentId=<uuid> dest=<path> declaredBytes=<n> preflightPasses=1` |
+| On success | `[skill:unzip] done attachmentId=<uuid> entries=<n> uncompressed=<bytes>` |
+| Oversize refusal | `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600` |
+| Zip-slip refusal | `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>` |
+| Symlink refusal | `[skill:unzip] symlink-blocked attachmentId=<uuid> entry=<path>` |
+| Password / corrupt | `[skill:unzip] unreadable attachmentId=<uuid> reason=<password\|corrupt>` |
+
+One `start` pairs with exactly one of `{done, oversize, zip-slip-blocked, symlink-blocked, unreadable}`. A `start` with no matching terminal line indicates the agent was interrupted mid-extraction — investigate by re-running the flow.
+
+## Out of scope
+
+- `tar`, `tar.gz`, `7z`, `rar` — zip only. The `SUPPORTED_MIME_TYPES` allow-list is the gate.
+- Nested-archive recursion — if an extracted file is itself a zip, the operator may manually re-invoke the skill on that file; no auto-recursion.
+- Password-protected archives — refused, never prompted.
+- Public-chat zip uploads — this skill is admin-only; the public agent never sees attachments of this class.
+
+## See also
+
+- [publish-site](../publish-site/SKILL.md) — when the extracted tree is a static website (HTML + assets), hand off to `publish-site` to move it under `<accountDir>/sites/<slug>/` and emit the canonical path slug.