@rubytech/create-siteoffice-code 0.1.256

package/payload/platform/plugins/admin/skills/qr-code/references/data-formats.md

@@ -0,0 +1,113 @@
+# QR Code Data Formats & CLI Reference
+
+## CLI Invocation
+
+Always pipe data via stdin to avoid shell injection. Never interpolate user data into the command string.
+
+```bash
+printf '%s' 'ENCODED_DATA' | npx -y qrcode -o output/qr/qr-$(date +%s).png
+```
+
+### Options
+
+| Option | Flag | Values |
+|--------|------|--------|
+| Size | `--width` | Small: 200, Medium: 400 (default), Large: 800 |
+| Error correction | `--error-correction-level` | L (7%), M (15%, default), Q (25%), H (30%) |
+| SVG output | `--type svg -o output/qr/qr-$(date +%s).svg` | Use instead of PNG when user requests SVG |
+
+Higher error correction allows the QR code to remain scannable even if partially damaged, but reduces data capacity.
+
+## Data Capacity
+
+QR codes have a maximum capacity that depends on the error correction level:
+
+| EC Level | Alphanumeric max | Binary max |
+|----------|-----------------|------------|
+| L | 4,296 | 2,953 |
+| M | 3,391 | 2,331 |
+| Q | 2,420 | 1,663 |
+| H | 1,852 | 1,273 |
+
+If the encoded data exceeds capacity, the CLI will error. Tell the user the data is too long and suggest reducing it or lowering the error correction level.
+
+## Encoding Formats
+
+### URL
+
+Encode the URL as-is. No special formatting needed.
+
+```
+https://example.com/path?query=value
+```
+
+### Plain Text
+
+Encode the text as-is.
+
+### Wi-Fi
+
+Collect from the user: network name (SSID), password, and encryption type.
+
+| Field | Required | Values |
+|-------|----------|--------|
+| SSID | Yes | The network name |
+| Password | Yes (unless open) | The network password |
+| Encryption | Yes | WPA (covers WPA2/WPA3), WEP, or nopass |
+| Hidden | No | true if the network is hidden (default: false) |
+
+Default encryption to WPA if the user doesn't specify.
+
+```
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;;
+WIFI:T:WPA;S:MyNetwork;P:MyPassword;H:true;;
+WIFI:T:nopass;S:OpenNetwork;;;
+```
+
+Special characters in SSID or password (`;`, `,`, `"`, `:`, `\`) must be escaped with a backslash.
+
+### vCard (Contact)
+
+Collect from the user: at minimum a name. Phone and email are optional but encouraged.
+
+```
+BEGIN:VCARD
+VERSION:3.0
+N:LastName;FirstName;;;
+FN:FirstName LastName
+TEL;TYPE=CELL:+441234567890
+EMAIL:person@example.com
+ORG:Company Name
+TITLE:Job Title
+URL:https://example.com
+END:VCARD
+```
+
+Omit any field the user doesn't provide. Do not add placeholder values.
+
+### Email (mailto)
+
+```
+mailto:recipient@example.com
+mailto:recipient@example.com?subject=Hello&body=Message%20here
+```
+
+URL-encode the subject and body values.
+
+### SMS
+
+```
+sms:+441234567890
+sms:+441234567890?body=Message%20here
+```
+
+URL-encode the body value.
+
+## Error Handling
+
+| Error | Cause | User-facing message |
+|-------|-------|-------------------|
+| CLI exits non-zero | Various | Report the stderr output and suggest the user check their input |
+| "Input too long" | Data exceeds QR capacity | "The data is too long for a QR code. Try shorter text or a lower error correction level (L instead of M)." |
+| npm/npx failure | Package not available | "QR code package couldn't be downloaded. Check your internet connection and try again." |
+| File write error | Permission or disk issue | "Couldn't save the QR code image. Check disk space and try again." |

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

@@ -0,0 +1,62 @@
+---
+name: session-management
+description: "Reset the current session, list past sessions, continue a previous session, or read the session memory. Triggers when the owner says 'start a new session', 'continue the last session', 'pick up where we left off', 'what were we doing last time', or asks about session state."
+---
+
+# Session management
+
+This skill wraps the session tools and carries the discipline that keeps long-running work coherent across sessions. The platform handles a lot of session machinery automatically: this skill is for the moments where the owner names a session intent directly.
+
+## The tools
+
+| Tool | Purpose |
+|---|---|
+| `session-reset` | Clear the current session and return to idle. |
+| `session-list` | List recent sessions with metadata. |
+| `session-resume` | Resume a specific session by `sessionId`. |
+| `session-compact-status` | Read the compaction state of the current session: how much context has been compacted, what remains. |
+
+## Resetting the session
+
+When the owner asks to start a new session, clear the conversation, or reset, call `session-reset`. Do not ask for confirmation. After the tool call, say nothing further; the UI clears and returns to idle.
+
+**Before suggesting a reset (e.g. after a plugin activation, when context has drifted), persist every actionable finding from the current conversation to its durable store first.** Compaction saves a session summary, but summaries are lossy: decisions, working state, and unfinished threads must be captured explicitly before the context window is cleared. Write open tasks via `work-create`, profile updates via `profile-update`, and any other graph state. Then tell the owner what will carry into the new session (the summary and the open tasks via `<previous-context>`) and suggest the reset.
+
+## Continuing a previous session
+
+When the owner asks to continue, pick up, resume, or carry on:
+
+- **Most recent session.** Call `session-list` with `limit: 1`, then `session-resume` with the returned `sessionId`.
+- **Specific session by name or topic.** Call `session-list` with a higher limit, identify the matching session, then `session-resume`.
+- **No sessions found.** Tell the owner. Do not improvise by reading `<previous-context>`, searching memory, or re-researching prior work.
+
+## Trusting the session summary
+
+When `<previous-context>` is present in the system prompt, the platform has injected a recent session summary and the open tasks at session end. The platform rejects stale summaries older than 48 hours; when the summary is present, it is recent and trustworthy.
+
+- Trust the summary for state orientation. Do not re-verify claims it already describes.
+- Pick up from the state the summary describes. Redundant `memory-search` or other tool calls for information already in the summary waste the owner's time.
+- Use the summary to greet the owner with awareness of prior work and outstanding tasks.
+
+When `<previous-context>` is absent, Neo4j was unreachable or no prior context exists: proceed normally, using tool calls to establish state.
+
+## The recovery context block
+
+A `<recovery-context>` block on the user-message side appears whenever the previous turn was aborted by a stall recovery. It is the authoritative description of what failed, what was incomplete, and what to do now.
+
+- The **resume variant** announces that a synthetic tool result for the in-flight `tool_use_id` was just pushed above this message. Read it for the completed-work summary, then resume by re-issuing the next pending step concretely.
+- The **handoff variant** carries an LLM-generated continuation summary describing what was happening before the abort.
+
+In both shapes, the next operator message means resume the work. Never treat it as empty, never ask "what would you like to do?", never wait for direction. Do not re-research the blocker. Do not call `session-list` to figure out what was happening.
+
+## The api-wait-ping liveness gate
+
+The platform suppresses a heartbeat-driven stall fire while the SDK API request is still alive, bounded by a 600-second cap. When the cap forces an abort, the synthetic tool result names "API request stayed alive past the 600 s cap without producing tokens". This is upstream API latency, not specialist failure. Do not infer that the specialist's approach was wrong from a long stall; many stalls are not the subagent's fault.
+
+## In managed context mode
+
+Conversation history is provided inside `<conversation-history>` tags. Use `session-compact-status` to retrieve older archived context if needed.
+
+## What this skill does not do
+
+It does not edit summaries, delete past sessions, or modify the recovery-context block. These are platform-owned mechanics.

package/payload/platform/plugins/admin/skills/skill-builder/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: skill-builder
+description: "Guide the user through creating a new lean skill — collect name, description, behaviour rules, and references, then save the skill to memory."
+---
+
+# Skill Builder
+
+A deterministic walkthrough for creating new lean skills. Follow each step in order. Be conversational — one question at a time.
+
+## When to Activate
+
+The admin requests a new skill, asks to "create a skill", "add a skill", or "teach you something new".
+
+## Before Starting
+
+Load `references/lean-pattern.md` for the template and examples. Use it throughout as your reference for correct structure.
+
+## Step 1: Understand the Purpose
+
+Ask: **"What should this skill do?"**
+
+Listen for:
+- What capability it adds (scheduling, quoting, inventory, etc.)
+- When it should activate (what triggers it)
+- What tools or data it needs (memory, web search, file access, etc.)
+
+Clarify until you can describe the skill in one sentence. This becomes the `description` in frontmatter.
+
+## Step 2: Choose a Name
+
+Propose a name based on the purpose. Names must be:
+- Lowercase
+- Hyphen-separated (e.g. `inventory-management`)
+- Short and descriptive
+
+Confirm with the user.
+
+## Step 3: Define Behaviour
+
+Ask what rules the agent should follow when using this skill:
+- **Tone and style** — formal, casual, WhatsApp-short?
+- **Activation conditions** — when exactly should the agent use this skill?
+- **Hard boundaries** — what should the agent never do?
+- **Data sources** — where does the skill's knowledge live? (memory, external API, files)
+- **Escalation** — when should it hand off to admin?
+
+Not every skill needs all of these. Only include what's relevant.
+
+If the skill involves generating PDFs or print-ready documents, load `references/pdf-generation.md` for the constraints on HTML layout and the `browser-pdf-save` rendering path.
+
+## Step 4: Decide on References
+
+If the skill has detailed procedures, templates, or data formats, those belong in `references/` files — not inline in SKILL.md.
+
+Ask: **"Are there any detailed procedures, templates, or formats this skill needs?"**
+
+For each reference file:
+- Give it a descriptive filename (e.g. `event-format.md`, `quoting-rules.md`)
+- Collect the content from the user — they can dictate, paste, or describe it and you draft it
+
+If the skill is simple enough to fit in SKILL.md alone (under ~30 lines of instructions), skip references.
+
+## Step 5: Choose an Icon
+
+Ask: **"Would you like to pick an icon for this skill?"**
+
+Icons give skills a visual identity. They use [Lucide](https://lucide.dev) icon names. Offer a few suggestions that match the skill's purpose — the reference file `references/lean-pattern.md` has a curated list.
+
+If the user picks one, note it as part of the skill record. If they skip this, omit it — it's optional.
+
+## Step 6: Compose the Skill
+
+Using the lean pattern from `references/lean-pattern.md`, compose:
+
+1. **SKILL.md** — frontmatter (`name`, `description`) + activation conditions + behaviour rules + references index
+2. **Reference files** — one per detailed topic
+
+Show the user the complete SKILL.md content and each reference file. Ask them to review.
+
+## Step 7: Save the Skill as a Plugin File
+
+Use `store-skill` to write the composed skill to disk as part of an admin-managed plugin. The tool computes the path internally — supply the names and content only.
+
+Pick a `pluginName` that groups related operator-authored skills (e.g. `beacons-skills`, `my-utils`). Reuse the same `pluginName` across calls so the skill joins existing operator skills under one plugin. If this is the first skill in a new plugin, the tool creates the `PLUGIN.md` automatically.
+
+```
+store-skill({
+  pluginName: "{kebab-case plugin name}",
+  skillName: "{kebab-case skill name}",
+  description: "{the one-sentence description from Step 1}",
+  publicEmbed: false,
+  body: "{SKILL.md body content WITHOUT frontmatter — activation conditions, behaviour rules, references index}",
+  references: [
+    { filename: "{kebab-case-name}.md", content: "{full reference body}" }
+  ]
+})
+```
+
+Set `publicEmbed: true` only when the user wants this skill surfaced to the public agent. Default to `false` for admin-only skills.
+
+`references` is optional — pass `[]` (or omit) when the skill has no detailed procedures or templates.
+
+## Step 8: Confirm
+
+Tell the user:
+
+> "Your skill is saved on disk as part of the `{pluginName}` plugin and is active right now for the admin agent. I can use it when the situation matches. To edit it later, ask me to update the skill — I'll re-run `store-skill` with the new content."
+
+If `publicEmbed: true`, add: "It will surface in the public agent on the next session start."
+
+---
+
+**Remember:** Be conversational. Don't dump all questions at once. Guide through each step one at a time.

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 agent renders it to PDF with the on-device `browser-pdf-save` 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 on device — 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. **Render with `browser-pdf-save`** — serve the HTML over `http://127.0.0.1:<port>`, `browser-navigate` to it, then `browser-pdf-save` to the output path. The tool drives the device's Chromium over CDP (honours `@page`/print CSS, prints backgrounds); no Playwright is involved.
+
+## 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 goes through `browser-pdf-save` — it should not contain Playwright code, npm commands, or file path assumptions about any Playwright installation.

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

@@ -0,0 +1,45 @@
+---
+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. Extract the `name` and `description` fields from the copied file's YAML frontmatter.
+4. Read `agents/admin/AGENTS.md`. If it already contains a line matching `- **specialists:{name}**:` (any text after the colon — an operator may have tuned it), leave it untouched. Otherwise append `- **specialists:{name}**: {description}` using Edit, with `{description}` copied verbatim from the frontmatter.
+5. 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-{sessionId}.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 `sessionId` 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 <sessionId> 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 `sessionId` is visible in the admin UI and appears on every `[spawn]` / `[process-exit]` line in the log itself. A single `logs-read.sh <sessionId> 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-{sessionId}.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.