spool

Spool is the publishing platform for agent Sessions. **Share** explicitly sends the selected records to the Hub and returns a durable URL. Claude Code and Codex CLI Shares are Public by default and can appear in Explore and search; Gemini CLI, OpenCode, and Pi remain Link-only until Discovery supports them. Claude Code and Codex CLI shares can also be resumed from another machine. A Share can carry a Markdown Summary: the interactive CLI can generate one with a detected Claude Code or Codex CLI, while an agent shell should provide its own Summary with `--summary`. Local preparation and sharing cover all five providers, so **any agent with a shell can recall another agent's Sessions**.

## Routing

Decide from `$ARGS` and the conversation:

- **share/publish** this (or a specific) session → Share flow
- **withdraw/unpublish** a shared session → `spool withdraw <sid-or-url>`
- a resumable **Claude/Codex spool session URL or sid** the user wants to continue → `spool resume <sid-or-url>` (materializes it locally and forks the provider's native session)
- anything else (a topic, a question, "that session where…") → Recall flow

## Preflight

Use the installed `spool …` command for every Spool action. First run `command -v spool`. If it is
missing, install the CLI once, then verify it with `spool --version`:

```bash
curl -fsSL https://spool.new/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"
spool --version
```

Do not fall back to npx: a temporary package invocation does not make the `spool` command available
for the later login, Share, or Resume step. For a person sharing the current project, bare `spool` is
the everyday flow: it refreshes the index, signs in if needed, and starts a Share for the latest
Session. This skill uses explicit commands because its non-interactive Share passes a prepared Summary.

## Share flow

**claude**, **codex**, **gemini**, **opencode**, and **pi** sessions can be shared. Sharing sends native Claude/Codex records or the other sources' provider-neutral indexed conversation to the Hub. The CLI states the resulting visibility before upload and then prints the durable URL.

1. Run bare `spool` (or rely on a running `spool daemon`) so the session and its newest turns are indexed.
2. Pick the target:
   - Inside Claude Code, use `$CLAUDE_CODE_SESSION_ID`.
   - In another agent (or if that variable is unset), omit the session argument to select the latest indexed session whose cwd exactly matches the current directory.
   - For any other session, pass a UUID or unique UUID prefix from `spool sessions list`. `<uuid>@<n>` shares only the first _n_ records.
3. Write a share-ready Markdown Summary from the shared portion of the conversation. It should read like a concise, polished GitHub README for this one session—not a turn-by-turn chat recap.

   Determine the language from the session's natural-language conversation, giving substantive user messages more weight than assistant replies. Ignore code, logs, commands, paths, identifiers, metadata, and pasted material when deciding. For a mixed-language session, use the dominant language of the user's discussion; if none is clear, use the first substantive user request. Use that language for all prose and headings while preserving technical names in their original form.

   Use this README-style structure, localizing every heading:
   - `# <specific title>` derived from the actual goal, followed by a 1–2 sentence overview.
   - `## Goal` — the original request, constraints, and meaningful scope changes.
   - `## What happened` — the important stages in chronological order, grouped into concise paragraphs or bullets; include relevant pivots, failures, implementation details, and validation.
   - `## Key decisions and findings` only when material decisions or discoveries shaped the work.
   - `## Validation` only when the session contains concrete checks, tests, builds, or measurements.
   - `## Outcome` — state whether the goal was achieved, partially achieved, changed, or remains unresolved, and explain why.
   - `## Next steps` only when the session supports specific remaining work.

   Omit optional sections without meaningful content. Use direct, neutral language, preserve useful technical details, distinguish completed work from proposals and unresolved items, do not expose secrets, and never invent outcomes.

4. Pass that Summary directly. Agent tool shells are non-interactive, so do not rely on the CLI's post-upload Agent prompt:

```bash
summary="$(cat <<'SPOOL_SUMMARY'
<share-ready Markdown Summary>
SPOOL_SUMMARY
)"

# Inside Claude Code:
spool share "$CLAUDE_CODE_SESSION_ID" --summary "$summary" --visibility-confirmed < /dev/null
```

Outside Claude Code, omit the target: `spool share --summary "$summary" --visibility-confirmed < /dev/null`. For a selected session, put its UUID before `--summary`. Add `--spool-file <path>` only when the user wants to attach a `.spool` document. `--visibility-confirmed` acknowledges the stated Public/Link-only result but does not bypass sensitive-data findings.

The `< /dev/null` is deliberate: if the secret gate needs confirmation, a non-interactive invocation must abort instead of hanging. Do not add `--yes` until the user explicitly accepts the reported risk.

5. Handle outcomes:
   - **`Session published`** — a Claude/Codex Session and its provided Summary are Public and can appear in Explore and search; give the user the URL. Teammates can run `spool resume <sid-or-url>` to fork it locally.
   - **`Session shared as Link-only`** — a Gemini/OpenCode/Pi Session and its provided Summary are live for anyone with the URL, but do not appear in Explore or search.
   - **`Not logged in`** — ask the user to run `spool login` (browser approval), then retry.
   - **Secret findings / `Cannot confirm ... without a TTY`** — show the findings summary and ask. Only after an explicit yes, re-run the same command with `--yes`.
   - **`<source> sessions can be shared and read, but native