pi-skill-search 0.1.0

package/skills/vetc-verify/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: vetc-verify
+description: PROACTIVELY verify feature hoàn thành — build, test, coverage, security, API contract. Dùng sau vetc-ralph hoặc sau khi implement xong, trước khi ship.
+---
+
+# VETC Verify — End-to-End Verification
+
+Verify toàn diện sau khi implement. Không edit code — chỉ report pass/fail.
+
+
+
+## When to Activate
+
+- Sau khi implement xong (manual hoặc vetc-ralph)
+- Trước khi mở PR hoặc merge
+- Sau deslop pass, cần final check
+- User nói: "verify", "kiểm tra", "chạy full check"
+
+## Do NOT Activate When
+
+- Đang implement code (chưa đến phase verify) → dùng implementation skills
+- Build đang fail → fix build trước với `vetc-build-resolver`
+- Chỉ cần code review, không cần full verification pipeline → dùng `vetc-review`
+- Đang debug lỗi cụ thể → dùng `vetc-systematic-debugging`
+
+## Rationalization Prevention
+
+| Thought | Reality |
+|---------|---------|
+| "The build was fine yesterday" | Yesterday is not now. Run it again. |
+| "I only changed a comment, no need to verify" | Verify is cheap. Regressions are expensive. |
+| "Coverage is probably still above 80%" | "Probably" is not evidence. Run the coverage report. |
+| "The CI will catch it" | CI catches it AFTER merge. You catch it BEFORE. |
+| "I ran the tests locally already" | Were they ALL the tests? Was it a clean build? |
+| "Security scan takes too long" | A vulnerability in production takes longer. |
+| "The API contract hasn't changed" | Prove it. Compare the actual response with the spec. |
+
+## Common Verification Failures
+
+| Failure Pattern | Root Cause | Prevention |
+|----------------|------------|------------|
+| Tests pass locally, fail in CI | Dirty build, missing `mvn clean` | Always verify with clean build |
+| Coverage drops silently | New code without tests | Check coverage after every change |
+| Security scan finds what you missed | You didn't scan yourself | Run security quick scan before PR |
+| API contract drift | Spec not updated with code changes | Compare actual response with spec |
+| Debug statements left in code | Forgot to clean up | Gate 6 catches these |
+
+## Verification Pipeline
+
+### Gate 0 — Cross-Artifact Consistency (Optional)
+
+Chỉ chạy khi có spec files trong `specs/{NNN}-{slug}/`. READ-ONLY analysis — không edit.
+
+**6 Detection Passes:**
+
+| Pass | What It Detects | Severity Range |
+|------|-----------------|----------------|
+| Duplication | Same requirement stated in multiple places | MEDIUM |
+| Ambiguity | Vague or unclear requirements | HIGH |
+| Underspecification | Missing details, incomplete requirements | HIGH |
+| Principle Alignment | Violations of core principles (security-first, spec-first) | CRITICAL |
+| Coverage Gaps | Requirements without tasks, tasks without requirements | CRITICAL |
+| Inconsistency | Contradictions between spec, plan, tasks | CRITICAL |
+
+
+## Artifact Consistency
+| Pass | Findings | Max Severity |
+|------|----------|--------------|
+| Duplication | 0 | — |
+| Ambiguity | 1 | HIGH |
+| Underspecification | 2 | HIGH |
+| Principle Alignment | 0 | — |
+| Coverage Gaps | 1 | CRITICAL |
+| Inconsistency | 0 | — |
+| **Total** | **4** | **CRITICAL** |
+```
+
+### Gate 1 — Build
+
+```bash
+# Backend
+mvn clean compile -q
+
+# Frontend
+npm run build
+```
+
+**Result**: PASS (0 errors) / FAIL (list errors)
+
+### Gate 2 — Tests
+
+```bash
+# Backend — targeted
+mvn test -Dtest=XxxServiceImplTest -q
+
+# Backend — full module
+mvn test -pl <module> -q
+
+# Frontend
+
+

package/skills/visual-verdict/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: visual-verdict
+description: Structured visual QA verdict for screenshot-to-reference comparisons
+---
+
+- `reference_images[]` (one or more image paths)
+- `generated_screenshot` (current output image)
+- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)
+
+Return **JSON only** with this exact shape:
+
+```json
+{
+  "score": 0,
+  "verdict": "revise",
+  "category_match": false,
+  "differences": ["..."],
+  "suggestions": ["..."],
+  "reasoning": "short explanation"
+}
+```
+
+Rules:
+- `score`: integer 0-100
+- `verdict`: short status (`pass`, `revise`, or `fail`)
+- `category_match`: `true` when the generated screenshot matches the intended UI category/style
+- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
+- `suggestions[]`: actionable next edits tied to the differences
+- `reasoning`: 1-2 sentence summary
+
+- Target pass threshold is **90+**.
+- If `score < 90`, continue editing and rerun `visual-verdict` before any further visual review pass.
+- Do **not** treat the visual task as complete until the next screenshot clears the threshold.
+
+When mismatch diagnosis is hard:
+1. Keep `$visual-verdict` as the authoritative decision.
+2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
+3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.
+
+```json
+{
+  "score": 87,
+  "verdict": "revise",
+  "category_match": true,
+  "differences": [
+    "Top nav spacing is tighter than reference",
+    "Primary button uses smaller font weight"
+  ],
+  "suggestions": [
+    "Increase nav item horizontal padding by 4px",
+    "Set primary button font-weight to 600"
+  ],
+  "reasoning": "Core layout matches, but style details still diverge."
+}
+```
+
+Task: {{ARGUMENTS}}
+
+

package/skills/what-if-oracle/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: what-if-oracle
+description: Run structured What-If scenario analysis with multi-branch possibility exploration. Use this skill when the user asks speculative questions like "what if...", "what would happen if...", "what are the possibilities", "explore scenarios", "scenario analysis", "possibility space", "what could go wrong", "best case / worst case", "risk analysis", "contingency planning", "strategic options", or any question about uncertain futures. Also trigger when the user faces a fork-in-the-road decision, wants to stress-test an idea, or needs to think through consequences before committing.
+---
+
+# What-If Oracle — Possibility Space Explorer
+
+A structured system for exploring uncertain futures through rigorous multi-branch scenario analysis. Instead of one prediction, the Oracle maps the full **possibility space** — branching timelines where each path has its own logic, probability, and consequences.
+
+Based on the What-If Statement paradigm: the idea that speculative questions ("What if X?") are not idle daydreaming but a **fundamental computing operation** — the mind's way of simulating futures before committing resources to one.
+
+Published research: [The What-If Statement (DOI: 10.5281/zenodo.18736841)](https://doi.org/10.5281/zenodo.18736841) | [IDNA Consolidation v2 (DOI: 10.5281/zenodo.18807387)](https://doi.org/10.5281/zenodo.18807387)
+
+## Core Principle: 0·IF·1
+
+Every scenario analysis has three elements:
+
+- **0** — The unexpressed state (what hasn't happened yet, the potential)
+- **1** — The expressed state (what IS, the current reality)
+- **IF** — The conditional bond (the decision, event, or change that transforms 0 into 1)
+
+The quality of the analysis depends on the precision of the IF. A vague "what if things go wrong?" produces vague results. A precise "what if our primary supplier raises prices 30% in Q3?" produces actionable intelligence.
+
+## How to Run the Oracle
+
+### Phase 1 — Frame the Question
+
+Take the user's What-If question and sharpen it:
+
+**Decompose into components:**
+
+- **The Variable:** What specific thing changes? (one variable per analysis)
+- **The Magnitude:** By how much? (quantify if possible)
+- **The Timeframe:** Over what period?
+- **The Context:** What's the current state before the change?
+
+**If the question is vague, sharpen it:**
+
+- "What if AI takes over?" → "What if 40% of current knowledge-work tasks are automated by AI within 3 years in [specific industry]?"
+- "What if we fail?" → "What if monthly revenue stays below $5K for 6 consecutive months starting now?"
+
+Present the sharpened question to the user for confirmation before proceeding.
+
+### Phase 2 — Map the Possibility Space
+
+Generate **4-6 scenario branches** using this framework:
+
+| Branch             | Definition                                                                   | Purpose                                            |
+| ------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------- |
+| **Ω Best Case**    | Everything goes right. Key assumptions all validate. Lucky breaks occur.     | Define the ceiling — what's the maximum upside?    |
+| **α Likely Case**  | Most probable path given current evidence. No major surprises.               | Anchor expectations in reality                     |
+| **Δ Worst Case**   | Key assumptions fail. Two things go wrong simultaneously.                    | Define the floor — what's the maximum downside?    |
+| **Ψ Wild Card**    | An unexpected variable enters that nobody is tracking. Black swan territory. | Stress-test for the unimaginable                   |
+| **Φ Contrarian**   | The opposite of the consensus view turns out to be true.                     | Challenge groupthink and reveal hidden assumptions |
+| **∞ Second Order** | The first-order effects trigger cascading consequences nobody predicted.     | Map the ripple effects                             |
+
+### Phase 3 — Analyze Each Branch
+
+For each scenario branch, provide:
+
+```
+╔══════════════════════════════════════════════╗
+║  BRANCH: [Ω/α/Δ/Ψ/Φ/∞] — [Branch Name]    ║
+╠══════════════════════════════════════════════╣
+║  Probability: [X%]                           ║
+║  Timeframe: [When this could materialize]    ║
+║  Confidence: [HIGH/MEDIUM/LOW]               ║
+╠══════════════════════════════════════════════╣
+║  NARRATIVE:                                  ║
+║  [2-3 sentences describing how this          ║
+║   scenario unfolds step by step]             ║
+
+### Phase 4 — Synthesis
+
+After analyzing all branches, provide:
+
+**Probability Distribution:**
+
+```
+Ω Best Case ····· [██████░░░░] 15%
+α Likely Case ··· [████████░░] 45%
+Δ Worst Case ···· [██████░░░░] 20%
+Ψ Wild Card ····· [███░░░░░░░]  8%
+Φ Contrarian ···· [████░░░░░░]  7%
+∞ Second Order ·· [███░░░░░░░]  5%
+
+

package/skills/widget-rendering/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: widget-rendering
+description: Pi TUI crew widget data sources, display priority, and rendering performance. Use when debugging empty agents, ghost runs, or widget timing issues.
+---
+
+
+# widget-rendering
+
+The crew widget (`src/ui/crew-widget.ts`) displays active runs and their agents in the Pi TUI. It must render synchronously at TTY refresh rate without blocking. Understanding the data sources and timing rules is essential for debugging display issues.
+
+## Three Data Sources
+
+The widget has three sources, used in priority order:
+
+### 1. `liveAgents` Map (real-time, highest priority)
+
+In-memory map from `live-agent-manager.ts`. Provides:
+- Real-time tool names: `activeTools` Map (toolName → description)
+- Turn count, response text, compaction count
+- Session stats: context %, token usage
+- Status from the handle
+
+**When used:** Agents with `liveHandle && liveHandle.status === "running"` get the live activity description (tool labels, response text, turn counter).
+
+**When NOT used:** After `evictStaleLiveAgentHandles()` removes a handle, widget falls back to agent records on disk.
+
+### 2. Snapshot cache (500ms TTL)
+
+`RunSnapshotCache` from `run-snapshot-cache.ts` caches parsed manifests and agents for 500ms. Reduces disk reads during rapid refresh.
+
+**When used:** As the fallback when no live handle exists. Prevents excessive disk reads on every render tick.
+
+**Invalidation:** Cache is invalidated when:
+- `invalidate()` is called on a specific run
+- An empty result is returned (forces refresh on next tick)
+- TTL expires (500ms)
+
+### 3. `agents.json` on disk (durables, lowest priority)
+
+`readCrewAgents(run)` reads `artifactsRoot/agents.json`. Provides:
+- Final agent status (completed/failed/cancelled)
+- Tool count, token usage from final record
+- Error messages
+- Timestamps (startedAt, completedAt)
+
+**When used:** For completed agents, or when snapshot cache misses.
+
+---
+
+## Display Priority
+
+```
+for each active run:
+  for each agent in run:
+    if liveAgents has this agent (by agentId or taskId):
+      → use live activity description (tool labels, response text)
+      → use live status (running/queued/waiting)
+      → use live session stats (context %, turns, tokens)
+    else if snapshot cache has fresh data:
+      → use cached agent status
+      → use cached tool count, tokens, progress
+    else:
+      → read agents.json from disk
+      → use disk agent status
+
+    if status is completed/failed/cancelled:
+      → apply linger rules (finishedAgents: 1min, errors: 2min)
+```
+
+---
+
+## Active Runs Filtering
+
+`activeWidgetRuns()` determines which runs to show. Key filter: `isDisplayActiveRun(manifest, tasks)` from `process-status.ts`.
+
+**Rule: `hasStaleAsyncProcess()`**
+
+A run with an async PID is considered stale (hidden) if:
+1. PID is recorded but process is dead, AND
+2. The run is more than 30 minutes old (`STALE_ACTIVE_RUN_MS = 30 * 60 * 1000`)
+
+**Rule: `isDisplayActiveRun()`**
+
+```typescript
+export function isDisplayActiveRun(manifest: TeamRunManifest, tasks: TeamTaskState[]): boolean {

package/skills/wiki/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: wiki
+description: LLM Wiki — persistent markdown knowledge base that compounds across sessions (Karpathy model)
+---
+
+# Wiki
+
+Persistent, self-maintained markdown knowledge base for project and session knowledge. Inspired by Karpathy's LLM Wiki concept.
+
+## Operations
+
+### Ingest
+Process knowledge into wiki pages. A single ingest can touch multiple pages.
+
+```
+wiki_ingest({ title: "Auth Architecture", content: "...", tags: ["auth", "architecture"], category: "architecture" })
+```
+
+### Query
+Search across all wiki pages by keywords and tags. Returns matching pages with snippets — YOU (the LLM) synthesize answers with citations from the results.
+
+```
+wiki_query({ query: "authentication", tags: ["auth"], category: "architecture" })
+```
+
+### Lint
+Run health checks on the wiki. Detects orphan pages, stale content, broken cross-references, oversized pages, and structural contradictions.
+
+```
+wiki_lint()
+```
+
+### Quick Add
+Add a single page quickly (simpler than ingest).
+
+```
+wiki_add({ title: "Page Title", content: "...", tags: ["tag1"], category: "decision" })
+```
+
+### List / Read / Delete
+```
+wiki_list()           # Show all pages (reads index.md)
+wiki_read({ page: "auth-architecture" })  # Read specific page
+wiki_delete({ page: "outdated-page" })    # Delete a page
+```
+
+### Log
+View wiki operation history by reading `.omc/wiki/log.md`.
+
+## Categories
+Pages are organized by category: `architecture`, `decision`, `pattern`, `debugging`, `environment`, `session-log`
+
+## Storage
+- Pages: `.omc/wiki/*.md` (markdown with YAML frontmatter)
+- Index: `.omc/wiki/index.md` (auto-maintained catalog)
+- Log: `.omc/wiki/log.md` (append-only operation chronicle)
+
+## Cross-References
+Use `[[page-name]]` wiki-link syntax to create cross-references between pages.
+
+## Auto-Capture
+At session end, significant discoveries are automatically captured as session-log pages. Configure via `wiki.autoCapture` in `.omc-config.json` (default: enabled).
+
+## Hard Constraints
+- NO vector embeddings — query uses keyword + tag matching only
+- Wiki pages are git-ignored by default (`.omc/wiki/` is project-local)
+
+
+

package/skills/workspace-isolation/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: workspace-isolation
+description: Workspace isolation boundaries in pi-crew. Use when ensuring agents from workspace A cannot access workspace B, or when implementing worktree-based parallel execution.
+---
+
+
+# workspace-isolation
+
+pi-crew enforces workspace isolation so that agents, runs, and live sessions from one project folder cannot be accessed from another. The workspace boundary is `manifest.cwd` — the directory where a run was initiated.
+
+## Workspace Boundary Definition
+
+**`manifest.cwd`** is the canonical workspace root. Every run record carries the directory where it was created.
+
+**Why it matters:** Pi can have multiple workspace folders open simultaneously. Without isolation, an agent from workspace A could be steered/controlled from workspace B.
+
+**Rules:**
+- Every run's `manifest.cwd` is set at creation time
+- Every live agent handle carries `workspaceId = manifest.cwd`
+- Widget queries filter by `manifest.cwd`
+- API operations reject cross-workspace access
+
+## Live Agent Workspace Check
+
+`LiveAgentHandle.workspaceId` field (added to prevent cross-workspace access):
+
+```typescript
+interface LiveAgentHandle {
+  // ... other fields
+  /** Workspace where this agent was spawned — used for session-scoped visibility. */
+  workspaceId: string;
+}
+```
+
+**Enforcement in `api.ts`** (team-tool operations):
+
+```typescript
+// list-active-live-agents: filter by workspace
+listActiveLiveAgentsByWorkspace(manifest.cwd);
+
+// steer-agent, follow-up-agent, stop-agent, resume-agent:
+const live = getLiveAgent(agentId);
+if (live && live.workspaceId !== manifest.cwd)
+  return result(`Live agent '${agentId}' does not belong to workspace ${manifest.cwd}.`, { status: "error" }, true);
+```
+
+**Enforcement in `live-agent-manager.ts`**:
+
+```typescript
+// listLiveAgentsByWorkspace(workspaceId): filter by workspaceId
+export function listLiveAgentsByWorkspace(workspaceId: string): LiveAgentHandle[] {
+  return listLiveAgents().filter((a) => a.workspaceId === workspaceId);
+}
+```
+
+## Team Workspace Modes
+
+### `single` (default)
+
+- All agents run in the project root (`manifest.cwd`)
+- No worktree creation
+- Simpler, but all workers share the same git state
+
+### `worktree` (parallel isolation)
+
+- Each task (or phase) gets its own git worktree
+- Worktree path: `<repo-root>/.worktrees/<runId>/<taskId>/`
+- Branch name: `crew/<runId>-<taskId>` (sanitized)
+- Allows parallel code-changing tasks without git conflicts
+
+**Entry point in `team-runner.ts`:**
+```typescript
+const worktree = workspaceMode === "worktree" && task.worktree !== undefined
+  ? { path: task.worktree.path, branch: task.worktree.branch, reused: task.worktree.reused }
+  : undefined;
+```
+
+**Worktree lifecycle:**
+
+1. **Creation** (`prepareTaskWorkspace` in `worktree-manager.ts`):
+   - Check leader repo is clean (`assertCleanLeader`)
+   - `git worktree add <path> <branch>`
+   - Link `node_modules` if present
+   - Mark reused if already exists
+

package/skills/worktree-isolation/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: worktree-isolation
+description: Conflict-safe git worktree workflow. Use when running parallel implementation workers, isolating risky edits, or cleaning up task worktrees.
+---
+
+
+# worktree-isolation
+
+Use this skill for worktree-based execution or cleanup. Git worktrees create isolated working directories that allow parallel code-changing tasks without git conflicts.
+
+## How Worktrees Work
+
+A git worktree is a separate working directory linked to the same repository. It has its own:
+- Working directory (different path)
+- HEAD (can be on a different branch)
+- Staged/unstaged changes
+
+But it shares:
+- Object database (`.git/objects`)
+- Refs (branches, tags)
+
+This means creating a worktree is cheap (no clone needed) and fast.
+
+## When to Use Worktrees
+
+**Use worktree mode when:**
+- Running parallel implementation workers that modify the same repo
+- Isolating risky changes that might need to be discarded
+- Running multiple agents on the same codebase simultaneously
+- Running a long task that would block other work
+
+**Don't use worktree mode when:**
+- The task is read-only (use scaffold mode instead)
+- Only one agent needs to work at a time
+- The repository has uncommitted changes (must be clean)
+
+## Worktree Lifecycle
+
+### 1. Creation
+
+**Prerequisites:**
+- Leader repository must be clean (`git status` empty)
+- Sufficient disk space for worktree directory
+
+**Creation flow:**
+```
+team-runner.ts (workspaceMode: "worktree")
+  → prepareTaskWorkspace(manifest, task)
+    → assertCleanLeader(repoRoot)
+    → git worktree add <path> <branch>
+    → linkNodeModulesIfPresent(repoRoot, worktreePath)
+    → return { cwd: worktreePath, worktreePath, branch }
+```
+
+**Naming convention:**
+- Branch: `crew/<sanitized-runId>-<sanitized-taskId>`
+- Path: `.worktrees/<runId>/<taskId>/`
+- Deterministic from run/task IDs — no user-controlled fragments
+
+**Example:**
+```
+Run: team_20260514092752_218fe358085d7115
+Task: 01_explore
+
+Branch: crew/team-20260514092752-218fe358085d7115/01-explore
+Path: .worktrees/team-20260514092752-218fe358085d7115/01-explore/
+```
+
+### 2. Reuse
+
+If a worktree with the same branch already exists, it is reused instead of recreated:
+
+```typescript
+// Check if worktree already exists
+const existing = git(cwd, ["worktree", "list", "--porcelain"]);
+if (existing.includes(branch)) {
+  return { reused: true, worktreePath: parsePath(existing) };
+}
+```
+
+Reuse is safe when the worktree's base branch hasn't diverged (checked via `branch-freshness.ts`).
+
+### 3. Work in worktree
+
+Each task works in its own worktree directory:

package/skills/wowerpoint/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: wowerpoint
+description: Turn one document into a kawaii NotebookLM slide-deck PDF. Use for "wowerpoint this", "make a deck about <file>", "turn this report into slides", or any request to render a single document as shareable narrative slides.
+---
+
+# Wowerpoint
+
+One doc in, one PDF out. Slide-deck only — videos and podcasts from the same engine are noticeably worse and out of scope; refer the user to the `notebooklm` CLI directly if they want those.
+
+## Triggers
+
+- "Wowerpoint <file>"
+- "Make a slide deck about <file>"
+- "Turn this report into slides"
+- "Kawaii-deck this"
+
+## Setup (one-time per machine)
+
+If `notebooklm auth check` returns 0 and `command -v jq` resolves, skip.
+
+```bash
+uv tool install --with playwright --force notebooklm-py
+$(uv tool dir)/notebooklm-py/bin/playwright install chromium
+```
+
+`jq` is required by the workflow's JSON parsing; install if missing (`brew install jq` on macOS, or your distro's package manager).
+
+Then the user authenticates interactively — do not script. Tell them to type `! notebooklm login` so the OAuth ENTER lands in their terminal.
+
+## Workflow
+
+### 1. The source doc
+
+You need exactly one source doc. If it doesn't exist or is too thin to carry a deck, **write it first** — use mem-search and sequential thinking to make it comprehensive (long-form, narrative, several thousand words is normal). Do not paper over a weak source by adding more sources.
+
+### 2. Auth pre-flight
+
+```bash
+notebooklm auth check 2>&1 | tail -5
+```
+
+Exit 1 with `Run 'notebooklm login' to authenticate.` = halt and tell the user.
+
+### 3. Create notebook, add the source
+
+```bash
+NOTEBOOK_ID=$(notebooklm create "<title>" --json | jq -r .notebook.id)
+SOURCE_ID=$(notebooklm source add "<doc-path>" --notebook "$NOTEBOOK_ID" --json | jq -r .source.id)
+```
+
+Title: H1 of the source doc, or its filename stem; append a date for dated work.
+
+JSON envelope keys differ — `create` → `.notebook.id`, `source add` → `.source.id`, `generate` → `.task_id`. Wrong key = empty string = silent downstream failure.
+
+### 4. Spawn the subagent
+
+Generation takes ~10 minutes; never block on it. Use the template below with `run_in_background: true`.
+
+### 5. End your turn
+
+Print the notebook URL so the user can watch live:
+
+```text
+https://notebooklm.google.com/notebook/
+```
+
+The subagent's completion notification fires when the file is on disk.
+
+## Output path
+
+Adjacent to the source, parallel filename:
+
+```text
+<source-dir>/<source-stem>-slides.pdf
+```
+
+If the source isn't somewhere that makes sense as an output location, default to `reports/<stem>-slides.pdf`.
+
+## Share link (WOWerpoint Server)
+
+After the PDF lands on disk, the subagent also POSTs it to the WOWerpoint Server, which converts the 16:9 deck into a 9:16 mobile twin and returns a share URL. The share URL is the primary deliverable to the user; the PDF on disk is the backup.
+
+Required env (exported in the user's shell — the subagent inherits the parent's environment, so plain `export` is enough; no dotenv loader runs):
+
+```bash
+WOWERPOINT_API_BASE=https://wowerpoint-api.<subdomain>.workers.dev
+WOWERPOINT_VIEWER_BASE=https://wowerpoint-viewer.<subdomain>.workers.dev
+WOWERPOINT_UPLOAD_TOKEN=<token>
+```
+
+If any var is missing, skip the share-link step and just hand the PDF over.
+
+Upload pattern (run AFTER the subagent confirms the PDF exists on disk). Capture the full response so empty `id` and `error` payloads are handled — `jq -r '.id'` returns the literal string `null` on a missing key, so always pipe through `.id // empty`:
+
+## The prompt
+
+One sentence. Default:
+
+```text
+Use kawaii characters to tell the story of <subject>. Keep it warm and clear.
+```