@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/admin/skills/task/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: task
+description: |
+  Generate a task entry that fully defines a unit of work — motivation,
+  boundaries, verification, and observability — so any session can
+  implement it without further conversation. Use when asked to "task it",
+  "create a task", "write a task file", or when the user describes work
+  that should be captured before a sprint.
+allowed-tools:
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - Bash
+  - AskUserQuestion
+---
+
+# Task Generation
+
+## What this skill produces
+
+A single task entry that fully defines a unit of work — its motivation,
+boundaries, verification strategy, and deployment observability — so that
+any session can implement it without further conversation.
+
+The entry is written through the **task surface of the environment this
+install exposes**. The surface resolution below decides where; the
+structure, principles, and precision pass below are identical regardless
+of surface.
+
+---
+
+## Task surface (where tasks live in this environment)
+
+Before searching prior work or writing the deliverable, resolve where
+tasks live in the current install. Check in this order; use the first
+one that exists:
+
+1. **Graph tasks (deployed maxy).** If the `work-*` MCP tools are
+   available — `work-list` and `work-get` for prior-work search,
+   `work-create` to write the deliverable (it persists `:Task` nodes in
+   Neo4j and **owns the identifier — no number scan**) — tasks live in
+   the graph. Use those tools. The plugin is `work`, not `tasks` —
+   renamed to avoid colliding with Claude Code's built-in `Task*` family.
+2. **Local `.tasks/` directory.** If the repo has a `.tasks/` directory
+   (optionally with `archive/`, `in-progress/`, `parked/`, `backlog/`
+   subdirs and a `LANES.md`), tasks live on disk as
+   `.tasks/<N>-<slug>.md`.
+3. **Neither.** State this explicitly: "No task surface detected — this
+   install has no `work-*` graph tools and no `.tasks/` directory. The
+   deliverable will be a written report only."
+
+Throughout this skill, "search prior tasks" and "write the task" mean:
+use the resolved surface. Operate inside whatever tree/surface the
+install exposes; never hard-code paths.
+
+## Before generating
+
+1. **Determine the next identifier.**
+   - **Graph surface:** `work-create` assigns the identifier on write —
+     no number scan, no manual numbering. For prior-work search use
+     `work-list` / `work-get`.
+   - **Local `.tasks/` surface:** scan `.tasks/`, `.tasks/in-progress/`,
+     `.tasks/archive/`, and `.tasks/parked/` for the highest existing
+     `<N>-<slug>.md` and increment by one. Never invent a numbering
+     convention not already in use in this tree.
+   - **No surface:** skip — the deliverable is a report.
+
+2. **Read the task tracker, if one exists.**
+   - **Local `.tasks/` surface:** read `.tasks/LANES.md` (if present) to
+     understand active lanes and file contention; the new task's lane
+     assignment and touches must be checked against in-progress work.
+   - **Graph surface:** skip — there is no `LANES.md` on a graph surface.
+
+3. **Gather context from the user.** If the user's description is
+   ambiguous or missing critical information (what's broken, what success
+   looks like, what's excluded), ask via AskUserQuestion — one focused
+   question at a time.
+
+## Task structure
+
+Every task contains these sections. Each section has a purpose — if the
+purpose can't be fulfilled, the section should say why (e.g., "No
+existing logs cover this path — observability must be added as part of
+the implementation").
+
+### Title and metadata
+
+```markdown
+# Task <N> — <Descriptive title>
+
+**Lane:** <lane from the tracker, or proposed new lane>
+**Status:** Open
+**Touches:** <precise file paths or graph node types this task will modify>
+```
+
+Optional metadata when relevant: `**Depends on:**`, `**Blocks:**`,
+`**Sequencing:**`, `**Priority:**`
+
+### Problem
+
+What is wrong, missing, or suboptimal — grounded in evidence. Include log
+extracts, reproduction steps, or code references when available. The
+problem section answers "why does this task exist?" not "what will we
+build?"
+
+### What success looks like
+
+Observable outcomes that define completion. Each criterion is
+verifiable — someone reading this section can confirm whether the task is
+done without knowing the implementation details.
+
+### Scope boundaries
+
+Two subsections, always paired:
+
+- **In scope** — the specific changes, files, and behaviours this task
+  covers. Precise file paths and line ranges when known. **100% coverage
+  rule:** if the task delivers a capability that should apply uniformly
+  across a known set of surfaces (every brand JSON, every plugin
+  manifest, every specialist template, every IDENTITY.md, every CRM
+  connector, etc.), the in-scope list must enumerate **every member of
+  that set** — not a representative subset. A task that ships the
+  capability to 1-of-N surfaces and defers the rest is incomplete by
+  construction; the deferred N-1 surfaces become silent regressions
+  because the capability is "shipped" in the changelog while most users
+  never see it. If the set is genuinely large enough that staged rollout
+  is required, the task is split into N sibling tasks, each covering
+  one surface end-to-end — never one task covering one surface with the
+  others listed as "out of scope" or "future work".
+- **Out of scope** — adjacent work that is explicitly excluded. This
+  prevents scope creep and makes the boundary between this task and
+  future tasks unambiguous. **Out of scope cannot be used to defer
+  members of a coverage set** (see 100% coverage rule above) — only
+  genuinely adjacent work (different capability, different layer,
+  different concern).
+
+### Verification
+
+How the implementation will be proven correct. This section is mandatory
+— a task without a verification strategy is incomplete.
+
+The verification section addresses:
+
+- **What is tested** — which behaviours, edge cases, and failure modes
+  have automated or manual verification. Not "write tests" but
+  specifically what the tests prove.
+- **How to reproduce** — for bug fixes, the exact reproduction steps
+  that should fail before the fix and pass after. For features, the
+  user-visible scenario that demonstrates the new capability.
+- **Regression boundary** — what existing behaviour must remain
+  unchanged and how that's confirmed (e.g., "existing tests pass",
+  "manual smoke test of X").
+
+If the project has no test infrastructure for the affected area, the
+verification section must acknowledge this and define what manual
+verification is required.
+
+### Observability
+
+How the change will be monitored once deployed. This section is
+mandatory — code that cannot be observed in production is incomplete
+code.
+
+**Derive it first, adversarially — do not write this section last.**
+Observability designed after the fix inherits the fix's blind spots;
+designed first, it forces the fix to expose what would otherwise stay
+hidden. Before writing prose, name **every way the change can fail**,
+and treat the failures that emit *no event and do not reproduce on
+demand* as first-class — they are the ones routinely missed. For
+**each** failure mode, answer one forcing question and write the answer
+in:
+
+> **What signal reveals this failure — and does it fire (a) without
+> reproducing the failure and (b) without waiting for unrelated future
+> activity?**
+
+The two clauses are the part repeatedly gotten wrong:
+
+- **Presence ≠ adequacy.** A section that merely has "what to log /
+  signals / diagnostic path" passes a presence check while still being
+  blind. The test is not "is there a section" but "is every failure
+  mode answered by the forcing question."
+- **Event-driven logging is structurally blind to no-event failures.**
+  A failure that triggers no action produces no log line, and re-running
+  the code will not surface it. Any such failure REQUIRES a **standing
+  check — an independent periodic audit that reconciles expected state
+  against actual** — not a log hung on some action. A task that names a
+  no-event failure mode but specifies no standing check to detect it is
+  inadequate by construction.
+- **Verify outcomes, don't log intentions.** "Called the cleanup" is
+  not "the resource was freed." Log the *verified* post-condition (a
+  measured delta, the resource absent from the live set), and never
+  swallow the failure branch.
+
+The observability section addresses:
+
+- **What to log** — the specific events, state transitions, or error
+  conditions that must produce log output. Each log point should carry
+  enough structured context to diagnose failures without reproducing
+  them locally.
+- **What signals confirm correct behaviour** — the log patterns,
+  metrics, or observable states that indicate the feature is working
+  as intended in deployment. An operator reading the logs should be
+  able to answer "is this working?" without reading the source code.
+- **What signals indicate failure** — the absence patterns, error
+  signatures, or anomalous states that indicate something is wrong.
+  The absence of an expected log entry is as important a signal as the
+  presence of an error.
+- **Diagnostic path** — given a failure signal, what targeted grep or
+  log query surfaces the cause. On a deployed install, this means
+  log-accessible forensics with specific tag/field patterns to search
+  for.
+
+If existing observability already covers the change adequately, the
+section should state what to look for in existing logs rather than
+adding new instrumentation.
+
+### Touches
+
+Precise file paths (local-`.tasks/` surface) or graph node/edge types
+(graph surface) the task will modify. Used for lane contention checks
+on the local-`.tasks/` surface.
+
+**Documentation triple-target (local-`.tasks/` surface with a
+`task-commit-gate` only).** When the task modifies source files under
+`platform/` and the repo enforces a `task-commit-gate` hook that
+mechanically requires all three documentation targets to be updated
+before any commit is allowed, include the applicable targets in the
+Touches list so the author scopes documentation work upfront:
+
+- `.docs/` — developer and architecture reference
+- `platform/plugins/docs/references/` — user guide shipped to device,
+  loaded by admin agent
+- `.tasks/LANES.md` — task tracker reflecting what changed
+
+A graph task surface has no `LANES.md`, and the commit-gate hook
+governs only on-disk `platform/` commits — on a graph-only install
+this paragraph does not apply.
+
+### Dependencies (when relevant)
+
+What must exist or be true before this task can start. If nothing, omit
+the section entirely rather than writing "None."
+
+## Principles
+
+- **Evidence before prescription.** The problem section contains
+  observed facts. The success criteria describe verifiable outcomes.
+  Neither section prescribes implementation steps.
+
+- **Scope is defined by exclusion.** What's out of scope is as important
+  as what's in scope. Adjacent improvements, refactors, and "while
+  we're here" changes are explicitly out of scope unless the user says
+  otherwise.
+
+- **Coverage is defined by enumeration.** When a task delivers a
+  capability to a known set of surfaces, the in-scope list enumerates
+  every member of that set. Shipping to 1-of-N and deferring the rest
+  is incomplete by construction — the deferred members become silent
+  regressions. See § Scope boundaries / 100% coverage rule.
+
+- **Testing is not optional.** Every task defines how its implementation
+  will be verified. "It works when I try it" is not verification —
+  it's anecdote.
+
+- **Observability is not optional.** Every task defines how its
+  implementation will be monitored in deployment. If you can't tell
+  whether it's working from the logs, the task isn't done. If current
+  observability is insufficient to monitor the change, adding
+  observability is in-scope for the task.
+
+- **Precision over brevity.** File paths are exact. Line ranges are
+  included when known. Error messages are quoted, not paraphrased.
+  Vague tasks produce vague implementations.
+
+## Precision pass (mandatory final step before commit)
+
+After drafting the task and before staging it, compress it to ~25% of
+its initial length (75% reduction) without losing informative value.
+This step is non-optional — tasks are read by every sprint, indexed by
+every learning extraction, and paid for in every context window that
+loads them. Bloat compounds.
+
+- **Strip:** planning narrative, restated repository context already in
+  linked docs, ceremonial framing, prose that paraphrases section
+  headings, redundant motivation, and verbose phrasing. Replace
+  multi-sentence explanations with single declarative lines.
+- **Preserve:** every file path, line range, log extract quotation,
+  scope boundary item (in and out), verification criterion,
+  observability hook, error signature, dependency, and link. Precision
+  data is incompressible.
+- **Verify:** re-read the compressed task once. Every detail an
+  implementer would need to execute the task without further
+  conversation must still be present. If a fact was lost, restore it;
+  if it wasn't needed, the original was bloated.
+
+The same "additions require deletions" doctrine that governs
+`CLAUDE.md` applies here.
+
+## After generating
+
+1. Confirm the task was written through the resolved surface and that
+   the precision pass has been applied.
+2. **Local `.tasks/` surface only:** stage and commit the task file with
+   message `task: add Task <N> — <title>` and the co-author trailer. If
+   `LANES.md` was updated (new lane or touches entry), include it in
+   the same commit. Report any lane contention found in `LANES.md`
+   (files touched by both this task and an in-progress task).
+3. **Graph surface:** the `work-create` write is the commit-equivalent;
+   no git step. If a project surface is implied by the work, set it on
+   the node at write time.
+4. Do not implement. The task entry is the deliverable. Implementation
+   is a separate step that goes through the sprint workflow.

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

@@ -0,0 +1,84 @@
+---
+name: unzip-attachment
+description: "Safely extract a zip archive the admin has uploaded, inventory its contents, and route each entry to the right downstream specialist, refusing path traversal, symlink escape, and decompression bombs. Use when an admin uploads a zip to unzip or extract."
+---
+
+# 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 by the admin agent directly.** Admin owns all unzipping: the operator drops a zip, admin runs this skill against the attachment, then forwards the extracted tree to the appropriate downstream specialist — `specialists:content-producer` for static-site zips carrying a host-website / publish-site / put-online intent (it chains into `publish-site` on the extracted tree), and `specialists:librarian` for graph-bound archives (LinkedIn exports, conversation transcripts, loose PDFs, etc.). The skill itself does not dispatch; it extracts safely, inventories the result, and surfaces the post-unzip contents so admin can route.
+
+## 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. 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` → "state their location under `extracted/<attachmentId>/` — the operator retrieves them from the Artefacts panel or file share."
+   - 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.

package/payload/platform/plugins/admin/skills/unzip-attachment/__tests__/preflight.sh

@@ -0,0 +1,148 @@
+#!/usr/bin/env bash
+# Regression suite for the single-pass pre-flight prescribed by SKILL.md step 2.
+# Each test builds a fixture zip, runs the exact awk one-liners from SKILL.md
+# against `unzip -Z` output, and asserts the expected gate fires.
+#
+# Run from anywhere: `bash platform/plugins/admin/skills/unzip-attachment/__tests__/preflight.sh`
+# Exits 0 if all assertions pass, non-zero on the first failure.
+
+set -uo pipefail
+
+WORK=$(mktemp -d)
+trap 'rm -rf "$WORK"' EXIT
+
+PASS=0
+FAIL=0
+fail() { echo "FAIL: $1"; FAIL=$((FAIL+1)); }
+pass() { echo "PASS: $1"; PASS=$((PASS+1)); }
+
+# --- The four awk gates from SKILL.md step 2 -----------------------------------
+# Each takes `unzip -Z $zip` on stdin and exits 0 if the gate FIRES (attack
+# detected), non-zero if the zip is clean for that gate.
+
+detect_symlink()   { awk 'NR>2 && $1 ~ /^l/ { found=1; print $0 } END { exit !found }'; }
+detect_encrypted() { awk 'NR>2 && $5 ~ /^[TB]/ { found=1; print $0 } END { exit !found }'; }
+detect_slip()      { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { found=1; print $i } } END { exit !found }'; }
+sum_uncompressed() { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { print s+0 }'; }
+extract_names()    { awk 'NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) printf "%s%s", $i, (i<NF?" ":"\n") }'; }
+
+LIMIT=$((100 * 1024 * 1024))
+
+# --- (a) Password-protected archive refused ----------------------------------
+cd "$WORK"
+echo "secret" > a-secret.txt
+zip -e -P testpass a-pw.zip a-secret.txt >/dev/null 2>&1
+if unzip -Z a-pw.zip 2>/dev/null | detect_encrypted >/dev/null; then
+  pass "(a) password — col-5 uppercase first letter detected"
+else
+  fail "(a) password — col-5 uppercase first letter NOT detected"
+fi
+
+# --- (b) Symlink entry refused -----------------------------------------------
+cd "$WORK"
+ln -s /etc/passwd b-link
+echo "ok" > b-ok.txt
+zip -y b-sym.zip b-link b-ok.txt >/dev/null 2>&1
+if unzip -Z b-sym.zip 2>/dev/null | detect_symlink >/dev/null; then
+  pass "(b) symlink — col-1 leading 'l' detected"
+else
+  fail "(b) symlink — col-1 leading 'l' NOT detected"
+fi
+
+# --- (c) Zip-slip entry refused by pre-scan ---------------------------------
+# The PRE-scan must detect `../`-prefixed entry names in `unzip -Z` column 9+
+# BEFORE extraction runs. macOS unzip silently sanitises these paths during
+# extraction (the file lands inside dest with `../` stripped), so the
+# post-extraction realpath check is a defense-in-depth backstop for unzip
+# versions that don't sanitise — not the primary gate.
+# zip(1) refuses `..` paths, so python forges the central-directory entry.
+cd "$WORK"
+python3 - <<'PY' >/dev/null 2>&1
+import zipfile
+with zipfile.ZipFile("c-slip.zip", "w") as z:
+    z.writestr("../../escapee.txt", "evil payload")
+    z.writestr("good.txt", "ok")
+PY
+if unzip -Z c-slip.zip 2>/dev/null | detect_slip >/dev/null; then
+  pass "(c) zip-slip — pre-scan caught '../' in entry name"
+else
+  fail "(c) zip-slip — pre-scan missed '../' in entry name"
+fi
+
+# --- (d) Oversize archive refused (declared > 100 MiB) -----------------------
+# Building a 100 MiB+ fixture is expensive on disk and CI. Instead, simulate
+# the awk gate against a synthetic `unzip -Z`-shaped fixture whose column-4
+# sum exceeds the limit. This tests the *gate logic*, not unzip itself.
+cd "$WORK"
+cat > d-zfake.txt <<'FAKE'
+Archive:  d-big.zip
+Zip file size: 999 bytes, number of entries: 2
+-rw-r--r--  3.0 unx 60000000 tx stor 26-May-10 21:08 big1.bin
+-rw-r--r--  3.0 unx 60000000 tx stor 26-May-10 21:08 big2.bin
+2 files, 120000000 bytes uncompressed, 999 bytes compressed:  0.0%
+FAKE
+SUM=$(sum_uncompressed < d-zfake.txt)
+if [ "$SUM" -gt "$LIMIT" ]; then
+  pass "(d) oversize — sum=$SUM > limit=$LIMIT detected"
+else
+  fail "(d) oversize — sum=$SUM did not exceed limit=$LIMIT (gate broken)"
+fi
+
+# --- (e) Clean zip = exactly 1 pre-flight + 1 extraction ---------------------
+cd "$WORK"
+mkdir e-stage && cd e-stage
+echo "alpha" > a.txt
+mkdir sub && echo "beta" > sub/b.txt
+zip -r ../e-clean.zip a.txt sub >/dev/null 2>&1
+cd "$WORK"
+
+# Wrap unzip in a tracer that increments a counter file per invocation, scoped
+# by the flag combination so we can count pre-flight vs extraction calls.
+TRACE_DIR=$(mktemp -d)
+mkdir -p "$TRACE_DIR/bin"
+cat > "$TRACE_DIR/bin/unzip" <<TRACE
+#!/usr/bin/env bash
+# Classify the call: -Z* = pre-flight (zipinfo mode), -o* = extraction.
+case "\$1" in
+  -Z*) echo "Z" >> "$TRACE_DIR/calls" ;;
+  -o*) echo "O" >> "$TRACE_DIR/calls" ;;
+  -t*) echo "T" >> "$TRACE_DIR/calls" ;;
+  *)   echo "?" >> "$TRACE_DIR/calls" ;;
+esac
+exec /usr/bin/unzip "\$@"
+TRACE
+chmod +x "$TRACE_DIR/bin/unzip"
+: > "$TRACE_DIR/calls"
+
+# Run the prescribed clean-path: 1 `unzip -Z` + 1 `unzip -oq`.
+mkdir e-dest
+PATH="$TRACE_DIR/bin:/usr/bin:/bin" unzip -Z e-clean.zip >/dev/null 2>&1
+PATH="$TRACE_DIR/bin:/usr/bin:/bin" unzip -oq e-clean.zip -d e-dest >/dev/null 2>&1
+
+Z_COUNT=$(grep -c '^Z$' "$TRACE_DIR/calls" || true)
+O_COUNT=$(grep -c '^O$' "$TRACE_DIR/calls" || true)
+T_COUNT=$(grep -c '^T$' "$TRACE_DIR/calls" || true)
+
+if [ "$Z_COUNT" = "1" ] && [ "$O_COUNT" = "1" ] && [ "$T_COUNT" = "0" ]; then
+  pass "(e) clean — exactly 1 pre-flight + 1 extraction (Z=$Z_COUNT O=$O_COUNT T=$T_COUNT)"
+else
+  fail "(e) clean — wrong invocation count Z=$Z_COUNT O=$O_COUNT T=$T_COUNT"
+fi
+
+# --- (f) Filenames with spaces survive name extraction -----------------------
+cd "$WORK"
+mkdir f-stage && cd f-stage
+echo "hello" > "hello world.txt"
+zip ../f-space.zip "hello world.txt" >/dev/null 2>&1
+cd "$WORK"
+NAMES=$(unzip -Z f-space.zip 2>/dev/null | extract_names)
+if [ "$NAMES" = "hello world.txt" ]; then
+  pass "(f) whitespace name — extracted intact: '$NAMES'"
+else
+  fail "(f) whitespace name — corrupted: got '$NAMES' want 'hello world.txt'"
+fi
+
+# --- Summary -----------------------------------------------------------------
+echo
+echo "RESULT: $PASS passed, $FAIL failed"
+exit "$FAIL"

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

@@ -0,0 +1,116 @@
+# Zip extraction safety reference
+
+This file is the authoritative source for the exact shell commands, attack examples, and refusal messages referenced by [SKILL.md](../SKILL.md). Changes here propagate to every extraction — the skill file inlines the pre-flight bash block; this reference explains *why* each gate is shaped the way it is.
+
+## The single-pass pre-flight
+
+One `unzip -Z "$zip"` call produces the zipinfo column listing. Every attack-class gate reads the same output:
+
+```
+Archive:  example.zip
+Zip file size: 317 bytes, number of entries: 2
+-rw-r--r--  3.0 unx        6 tx stor 26-May-10 21:08 foo.txt
+lrwxr-xr-x  3.0 unx       11 bx stor 26-May-10 21:08 link
+2 files, 17 bytes uncompressed, 17 bytes compressed:  0.0%
+```
+
+Columns: `$1=permissions $2=zip-version $3=os $4=size-bytes $5=text/binary+crypto-flag $6=method $7=date $8=time $9+=name`. Each gate keys off one column; no second `unzip` invocation is needed.
+
+## Attack classes
+
+### 1. Zip slip (path traversal via entry name)
+
+A malicious archive contains an entry whose name starts with `../` (or uses Windows `..\` on some unzip builds). A naive extractor writing relative paths without validation lands the file *outside* the intended destination.
+
+Example listing (`unzip -Z`):
+```
+?rw-------  2.0 unx        4 b- stor 26-May-11 06:31 ../../escapee.txt
+?rw-------  2.0 unx        2 b- stor 26-May-11 06:31 good.txt
+```
+
+Pre-scan detection (one awk pass over column 9+):
+```awk
+NR>2 && $1 ~ /^[-lrwxd?]/ { for (i=9; i<=NF; i++) if ($i ~ /^\.\.\//) { print "blocked: " $i; exit } }
+```
+
+Ground-truth backstop: after extraction, for every path under `$dest`, compute `realpath --relative-to "$dest" "<entry>"`. If the relative path begins with `../`, the entry escaped. On macOS InfoZIP 6.00 the extractor silently sanitises `../` prefixes (the file lands inside `$dest` with the prefix stripped), so the realpath check is a no-op in that case — but it still catches the attack on `unzip` builds that don't sanitise. Defense in depth: pre-scan refuses the obvious case, realpath catches the version-specific escape.
+
+Refusal line: `[skill:unzip] zip-slip-blocked attachmentId=<uuid> entry=<path>`.
+
+Refusal message to the operator:
+
+> I rejected this archive because one of its entries tried to write outside the extraction directory (zip-slip attack). Entry: `<path>`. No files were kept.
+
+### 2. Symlink escape
+
+A malicious archive contains a symlink entry — for example, a zero-byte file with permission `lrwxrwxrwx` pointing at `/etc/passwd`. If the extractor materialises it, subsequent operations that follow the symlink read or overwrite the target.
+
+Pre-scan detection (same `unzip -Z` output, column 1):
+```awk
+NR>2 && $1 ~ /^l/ { print "blocked: " $9; exit }
+```
+First field beginning with `l` is the POSIX symlink flag in the permission column.
+
+Ground-truth backstop:
+```sh
+find "$dest" -mindepth 1 -type l
+```
+Any hit here → refuse even if the pre-scan missed it (defense in depth against `unzip` versions that normalise symlink entries into regular files with `..` payloads, flipping the attack class).
+
+Refusal line: `[skill:unzip] symlink-blocked attachmentId=<uuid> entry=<path>`.
+
+### 3. Decompression bomb
+
+A 42 KB archive expands to 4.5 GB — the classic `42.zip`. Not filesystem-escape but resource exhaustion: fills the account disk, causes OOM on downstream processing.
+
+Pre-scan gate (sum column 4 over the same `unzip -Z` output):
+```awk
+NR>2 && $1 ~ /^[-lrwxd?]/ { s += $4 } END { if (s > 100*1024*1024) print "oversize: " s }
+```
+Column 4 is the uncompressed size in bytes per entry. If the running sum exceeds `MAX_ZIP_UNCOMPRESSED_BYTES` (100 MiB, defined in `attachments.ts`), refuse *before* calling `unzip -oq`.
+
+Refusal line: `[skill:unzip] oversize attachmentId=<uuid> uncompressed=<bytes> limit=104857600`.
+
+Note: a hostile archive can lie in its declared sizes. The post-extraction realpath loop runs regardless; if the extraction step itself exhausts disk, `unzip -oq` exits non-zero and the skill refuses with the underlying stderr.
+
+### 4. Password-protected archive
+
+Refused without prompting. The signal is **not** the exit code — `unzip -Z` exits 0 on password-protected archives because the central directory itself is unencrypted; only entry payloads are. The signal is column 5: a leading uppercase `T` (encrypted text) or `B` (encrypted binary). Lowercase `t`/`b` = unencrypted.
+
+Pre-scan detection:
+```awk
+NR>2 && $5 ~ /^[TB]/ { print "password"; exit }
+```
+
+Refusal line: `[skill:unzip] unreadable attachmentId=<uuid> reason=password`.
+
+Refusal message:
+
+> This archive is password-protected. Please extract it locally and upload the individual files you want me to look at.
+
+A genuinely corrupt zip (no central directory) makes `unzip -Z` exit non-zero (typically 9). That is the only exit-code-driven branch: non-zero → `[skill:unzip] unreadable attachmentId=<uuid> reason=corrupt`.
+
+## Canonical commands
+
+| Purpose | Command |
+|---------|---------|
+| Single-pass pre-flight (listing + permissions + sizes + crypto flag) | `unzip -Z "$zip"` |
+| Extract | `unzip -oq "$zip" -d "$dest"` |
+| Post-extraction symlink backstop | `find "$dest" -mindepth 1 -type l` |
+| Per-entry zip-slip backstop | `realpath --relative-to "$dest" "<entry>"` → must not start with `../` |
+
+All of these are from `unzip` (InfoZIP) + `coreutils` — installed on every Pi image by the installer. No additional dependency.
+
+## Why one pass
+
+Each `Bash` tool_use is one agent turn. `effortToMaxTurns("low") = 5` ([platform/ui/app/lib/claude-agent/budget.ts:175](../../../../ui/app/lib/claude-agent/budget.ts#L175)). The previous flow used three separate `unzip -Z` invocations (entry list, verbose-for-symlink, totals) plus the extraction — four bash calls inside the skill alone, before counting the surrounding specialist dispatch and `plugin-read` calls. At `effort=low` the floor was six turns; one upload exhausted the budget and tripped `error_max_turns`. The fix is structural: every signal the four gates need is already in `unzip -Z`'s column output, so the three pre-flight calls collapse to one.
+
+The observability anchor is `preflightPasses=1` on the `[skill:unzip] start` log line. Absence after a clean upload means either the skill did not activate or the flow regressed back to multiple passes — both regressions are caught by `grep '[skill:unzip] start' server.log | grep -v preflightPasses=1`.
+
+## Why this is a skill, not a tool
+
+Doctrine: the admin agent has `Bash`; the security-critical code path is a sequence of shell commands whose determinism is enforced by the shell primitives themselves, not by LLM reasoning. Wrapping this in an MCP tool would add a translation layer without adding enforcement — a tool wrapper is still LLM-mediated at the decision boundary. The shell script is the deterministic primitive; the skill tells the agent which primitive to invoke, in which order, against which argument.
+
+## Regression suite
+
+[`__tests__/preflight.sh`](../__tests__/preflight.sh) is the executable specification of the four pre-flight gates. Run it after any change to this file or `SKILL.md`. It builds fixtures for each attack class, pipes `unzip -Z` output through the same awk gates inlined in `SKILL.md` step 2, and asserts each gate fires (or stays silent) on the right input. The clean-zip case also traces `unzip` invocations to assert exactly 1 pre-flight + 1 extraction — the structural invariant `preflightPasses=1` is built on.