@agentprojectcontext/apx 1.34.0 → 1.35.0

package/src/core/runtime-skills/apx-runtime/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: apx-runtime
-description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) via `apx run`. APX builds the system prompt, spawns the CLI, and captures the result. Load when delegating work to another AI tool.
+description: Delegate a task to an external coding CLI (claude-code, codex, opencode, aider, cursor-agent, gemini-cli, qwen-code) via `apx run`. APX builds the system prompt, spawns the CLI, captures the result. Load when delegating to another AI tool.
 ---
 
 # apx-runtime
 
-A "runtime" in APX is an external AI coding CLI that APX can invoke headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures the stdout (and the external tool's session id when available), and stores the run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (runtime state — never committed). Some flows also link to the external engine's own transcript path.
+A "runtime" is an external AI coding CLI that APX invokes headlessly. APX builds the agent's system prompt, spawns the CLI with the right flags, captures stdout (and the external session id when available), and stores run metadata as a session file under `~/.apx/projects/<apxId>/agents/<slug>/sessions/` (never committed). Some flows link to the engine's own transcript path.
 
 ## Supported runtimes
 
@@ -17,35 +17,33 @@ A "runtime" in APX is an external AI coding CLI that APX can invoke headlessly.
 | `aider`         | `aider`         | `--message "<prompt>" --no-stream` |
 | `cursor-agent`  | `cursor-agent`  | headless print mode |
 | `gemini-cli`    | `gemini`        | headless prompt mode |
-| `qwen-code`     | `qwen-code`     | passes system prompt separately |
+| `qwen-code`     | `qwen-code`     | system prompt passed separately |
 
 `apx env detect` reports which are installed and reachable.
 
 ## Concrete CLI calls
 
 ```bash
-# What's available on this machine
-apx env detect          # which runtimes are installed and reachable
-apx env list            # alias of `apx env detect`
+apx env detect          # which runtimes are installed
+apx env list            # alias
 
-# Run an agent through an external CLI
 apx run reviewer --runtime claude-code "Review the diff in src/host/daemon/api/ for memory leaks"
 apx run scratch  --runtime codex       "Refactor parseAgentsMd to use a state machine"
 apx run scratch  --runtime opencode    "<prompt>"
-apx run scratch  --runtime codex --timeout 300 "<prompt>"   # cap the run (seconds)
-apx run scratch  --runtime codex -      # read the prompt from stdin (large prompts)
+apx run scratch  --runtime codex --timeout 300 "<prompt>"   # cap (seconds)
+apx run scratch  --runtime codex -      # prompt from stdin (large prompts)
 ```
 
 Behavior:
-1. APX picks the project from `--project` or cwd.
-2. Reads the agent's `AGENT.md` + memory + skills, builds the system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
-3. Spawns the CLI with the right flags. cwd = project path.
-4. Captures stdout. If the runtime printed `APC_RESULT: <value>`, that's the structured result; else the first 200 chars of stdout.
-5. Writes `~/.apx/projects/<apxId>/agents/<slug>/sessions/<YYYY-MM-DD>-<id>.md` with frontmatter linking back to the external tool's own session file (when available).
+1. APX picks project from `--project` or cwd.
+2. Reads agent's `AGENT.md` + memory + skills; builds system prompt with `buildAgentSystem({ invocation: "runtime", runtime: "<id>" })`.
+3. Spawns CLI with the right flags; cwd = project path.
+4. Captures stdout. If runtime printed `APC_RESULT: <value>`, that's the structured result; else first 200 chars of stdout.
+5. Writes `~/.apx/projects/<apxId>/agents/<slug>/sessions/<YYYY-MM-DD>-<id>.md` with frontmatter linking back to the external transcript when available.
 
 ## Resuming an external session
 
-After a `apx run`, the resulting APC session file references the external transcript:
+The session file references the external transcript:
 
 ```yaml
 # ~/.apx/projects/<apxId>/agents/reviewer/sessions/2026-05-27-claude-code-abc123.md
@@ -56,62 +54,46 @@ session_id: abc123
 ---
 ```
 
-All session resume / get / continue / summarise operations live in the
-**`apx-sessions`** skill. From here, the most common quick paths:
+Full resume/get/continue/summarise lives in the **`apx-sessions`** skill. Quick paths:
 
 ```bash
-# Discover the id (or use the one printed by `apx run`)
 apx sessions list --engine claude --project iacrmar
-
-# Resume — apx auto-detects which engine owns the id
-apx session resume <id>
-apx session resume <id> --continue              # spawn the native CLI to keep going
-apx session resume <id> --summary               # super-agent summary of the transcript
-apx session resume <id> --into apx:<slug>       # seed a new APX session with the summary
-
-# Just read the transcript
-apx session get <id> --any --full               # or --engine claude --tail 16k
+apx session resume <id>                          # auto-detects engine
+apx session resume <id> --continue               # spawn native CLI to keep going
+apx session resume <id> --summary                # super-agent summary
+apx session resume <id> --into apx:<slug>        # seed new APX session
+apx session get <id> --any --full                # or --engine claude --tail 16k
 ```
 
-See the `apx-sessions` skill for the full flag reference, collision handling,
-and daemon-vs-no-daemon matrix.
+See `apx-sessions` for full flag reference, collision handling, and daemon-vs-no-daemon matrix.
 
 ## APC_RESULT contract
 
-When you want APX to capture a structured value from the external runtime, instruct the runtime via the prompt to print on its last line:
+To capture a structured value from the external runtime, instruct it via the prompt to print on its last line:
 
 ```
 APC_RESULT: <one-line value>
 ```
 
-APX `extractApfResult()` parses that and stores it as the session's `result` field. Useful for return values from automation.
+`extractApfResult()` parses that into the session's `result` field. Useful for automation return values.
 
 ## Anti-examples
 
-```bash
-# DON'T expect `apx run` to be interactive. It's headless.
-# For interactive, just invoke the CLI directly (e.g. `claude` for Claude Code).
-
-# DON'T pass huge prompts via the command line (shell args have limits).
-# For prompts > ~10KB, use a stdin-friendly route or write a temp file and reference it.
-
-# DON'T forget that each runtime has its own model selection.
-# APX passes the system prompt and the user prompt; it does NOT impose a model on
-# the external CLI. The user's external CLI config (e.g. Claude Code's CLAUDE.md
-# defaults) wins.
-```
+- DON'T expect `apx run` to be interactive — it's headless. For interactive, invoke the CLI directly (e.g. `claude`).
+- DON'T pass huge prompts via command line (shell arg limits). For >~10KB, use stdin (`-`) or a temp file.
+- DON'T expect APX to impose a model on the external CLI. APX passes system + user prompt only; the external CLI's own config wins.
 
 ## When to use which
 
 | You want | Pick |
 |---|---|
-| Pair-program with file edits and shell | `claude-code` if the user has Claude Code, else `codex` |
-| Lightweight LLM run with no tools | `apx exec <agent> "<prompt>"` (no runtime needed) |
-| The super-agent to call other agents | `call_agent` tool (in-process, no spawn) |
-| Run something that needs persisted state across days | `apx run` with `claude-code` or `codex` (their sessions persist) |
+| Pair-program with file edits + shell | `claude-code` if installed, else `codex` |
+| Lightweight LLM run, no tools | `apx exec <agent> "<prompt>"` (no runtime needed) |
+| Super-agent to call other agents | `call_agent` tool (in-process, no spawn) |
+| Persisted state across days | `apx run` with `claude-code` or `codex` (their sessions persist) |
 
 ## Don't
 
-- Don't run untrusted prompts in `--runtime` of a CLI with broad tool permissions on the user's machine. The CLI may take file write or shell actions.
-- Don't expect APX to track tool calls inside the external CLI's transcript. APX captures stdout and the external session path — that's it. Inspect the external transcript directly for tool-level audit.
-- Don't pick a runtime the user doesn't have installed; `apx env detect` first if unsure.
+- Run untrusted prompts in a `--runtime` CLI with broad tool permissions — the CLI may take file/shell actions.
+- Expect APX to track tool calls inside the external transcript. APX captures stdout + external session path only; inspect the external transcript for tool-level audit.
+- Pick a runtime the user doesn't have installed; `apx env detect` first.

package/src/core/runtime-skills/apx-sessions/SKILL.md

@@ -1,281 +1,232 @@
 ---
 name: apx-sessions
-description: "Manage APX sessions across engines (apx, claude, codex). Find a session by title, list, resume, summarize, ask about, or pull a transcript — without knowing which engine owns it. Triggers: 'apx session find/ask/summary/resume/get', 'find a session', 'resume claude/codex session', 'summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (that's the apx skill)."
+description: "Cross-engine session ops (apx, claude, codex, antigravity): find by title, list, get transcript, summarize, ask, resume, continue. Triggers: 'apx session find/ask/summary/resume/get', 'find/resume/summarize session', 'get session transcript', 'continue session in apx'. Not for `apx run` orchestration (use apx skill)."
 ---
 
-# APX Sessions — cross-engine resume, summary, and continuation
+# APX Sessions — cross-engine resume, summary, continuation
 
-APX treats every supported engine (apx, claude, codex, antigravity) as a session store. The commands in this skill let you list, read, summarize, and continue sessions **without caring which engine owns them**.
+APX treats every supported engine as a session store. These commands list, read, summarize, and continue sessions **without caring which engine owns them**.
 
-Engine storage locations APX scans:
+Storage locations APX scans:
 
-| Engine    | Where APX looks                                           |
+| Engine    | Where                                                     |
 |-----------|-----------------------------------------------------------|
 | apx       | `~/.apx/projects/<apx_id>/agents/<slug>/sessions/*.md`    |
 | claude    | `~/.claude/projects/<encoded-cwd>/<id>.jsonl`             |
 | codex     | `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`            |
 | antigravity | detected only — listing not implemented yet              |
 
-Engines not installed on the machine are silently skipped. Detected-but-empty engines show `(sin nada)`.
+Uninstalled engines are skipped silently. Detected-but-empty engines print `(sin nada)`.
 
 ---
 
-## The discovery flow (read this first)
+## Discovery flow (read first)
 
-You almost never start with a session id — you start with a vague memory of a *title* ("the one about improving the web UI"). Do **not** hand-roll `apx sessions list ... | grep`. The flow is three commands:
+You start with a vague title, not an id. Do **not** `apx sessions list | grep`. The flow:
 
 ```bash
-# 1. Turn a remembered title into an id (cross-engine, newest first)
+# 1. Title → id (cross-engine, newest first)
 apx session find "improve web UI"
 
-# 2. Get the gist of that session
+# 2. Gist
 apx session summary <id>
 
-# 3. Ask something specific about it
+# 3. Specifics
 apx session ask <id> "what sidebar changes were left pending?"
 ```
 
-`find` prints a "Next:" block with the exact `summary`/`ask`/`resume` commands pre-filled with the top hit's id, so you can copy-paste straight through. **If you're tempted to grep session lists, use `find` instead.**
+`find` prints a "Next:" block with `summary`/`ask`/`resume` pre-filled with the top hit's id. **If tempted to grep session lists, use `find` instead.**
 
 ---
 
-## Finding a session by title or content (`apx session find`)
+## Finding sessions (`apx session find`)
 
 ```bash
-apx session find "<text>"                      # match titles across every engine
-apx session find "<text>" --deep               # also search inside transcript content
+apx session find "<text>"                      # titles across every engine
+apx session find "<text>" --deep               # also greps transcript content
 apx session find "<text>" --engine codex       # restrict to one engine
-apx session find "<text>" --dir /path/to/repo  # scope to one project (reaches unregistered Claude projects)
-apx session find "<text>" --limit 10 --json    # cap results / machine-readable
+apx session find "<text>" --dir /path/to/repo  # scope (reaches unregistered Claude projects)
+apx session find "<text>" --limit 10 --json
 ```
 
-- Default search is **title-only** (fast — titles are already indexed per engine).
-- `--deep` reads each candidate transcript off disk and greps its content too. Slower; prefer combining it with `--engine`/`--dir` scope.
-- Output is one row per match — `DATE | ENGINE | SESSION ID | TITLE` — newest first, followed by ready-to-run `summary`/`ask`/`resume` commands.
+Default is title-only (fast, indexed). `--deep` reads each candidate transcript off disk; combine with `--engine`/`--dir` to scope. Output rows: `DATE | ENGINE | SESSION ID | TITLE`, newest first, plus ready-to-run `summary`/`ask`/`resume` commands.
 
-**Coverage caveat:** an engine can only be enumerated when APX can resolve a project's working directory. Codex always records it; APX uses registered projects; **Claude only lists folders that map back to a registered APX project** (its folder names are a lossy encoding of the cwd). If a Claude session is missing, scope with `--dir <path>` to reach it.
+**Coverage caveat:** an engine is enumerated only when APX can resolve a project cwd. Codex always records it; APX uses registered projects; **Claude only lists folders mapping to a registered APX project** (encoded folder names are lossy). If a Claude session is missing, scope with `--dir <path>`.
 
 ---
 
-## Summarizing a session (`apx session summary`)
+## Summarize / Ask
 
 ```bash
-apx session summary <id>                  # auto-detect engine, print an LLM summary
-apx session summary <id> --engine claude  # skip auto-detect
+apx session summary <id>                  # auto-detect, LLM summary
+apx session summary <id> --engine claude
 apx session summary <id> --max-chunks 8   # bound cost on a huge transcript
-```
-
-This is the discoverable alias for `apx session resume <id> --summary`. It resolves the owning engine, then prints a 4-bullet summary plus next steps. **Requires the daemon + `super_agent.enabled`.**
-
----
 
-## Asking questions about a session (`apx session ask`)
-
-```bash
 apx session ask <id> "what did we decide about the sidebar?"
 apx session ask <id> "what files were changed?" --max-chunks 30
 ```
 
-RAG-lite Q&A over the transcript. Small transcripts are answered in one shot; large ones are **map-reduced**: each ~48 KB part is mined for question-relevant notes, then a final pass synthesizes the answer. **Requires the daemon + `super_agent.enabled`.**
-
-How it works and its limits:
+`summary` is the alias for `apx session resume <id> --summary`: resolves engine, prints a 4-bullet summary plus next steps. `ask` is RAG-lite Q&A: small transcripts answer in one shot; large ones are **map-reduced** (each ~48 KB part mined for relevant notes, final pass synthesizes). Both **require the daemon + `super_agent.enabled`**.
 
-- Binary noise (base64 image payloads, which can be the majority of a JSONL transcript) is stripped before chunking.
-- Coverage is capped at `--max-chunks` (default 20 ≈ ~960 KB). Bigger transcripts print a truncation warning — raise `--max-chunks` for full coverage at the cost of more (sequential) model calls.
-- Speed scales with transcript size: a typical session answers in seconds; a multi-MB Codex rollout can take a couple of minutes.
-- Output quality depends on the configured `super_agent.model`. Small/cheap models that "think" (e.g. gemini-2.5-flash) can return thin answers; the command already requests a raised output budget to compensate.
+Limits of `ask`: binary noise (base64 images) is stripped before chunking. Coverage capped at `--max-chunks` (default 20 ≈ 960 KB) — bigger transcripts print a truncation warning; raise `--max-chunks` for full coverage at the cost of more sequential model calls. Speed scales with size (seconds to a couple of minutes). Quality depends on `super_agent.model` — cheap thinking models (e.g. gemini-2.5-flash) can return thin answers.
 
 ---
 
 ## Listing sessions
 
 ```bash
-# Every detected engine, every known project — broadest view
-apx sessions list
-
-# Every engine, scoped to one directory (no need for it to be a registered APX project)
-apx sessions list --dir /path/to/repo
-apx sessions list --project iacrmar          # uses a registered APX project's path
-
-# One engine, all projects
-apx sessions list --engine claude
-apx sessions list --engine codex
-
-# One engine, one project
-apx sessions list --engine claude --project iacrmar
-apx sessions list --engine codex  --dir /path/to/repo --limit 10
+apx sessions list                                       # all engines, all projects
+apx sessions list --dir /path/to/repo                   # all engines, one dir (no registration needed)
+apx sessions list --project iacrmar                     # all engines, registered project
+apx sessions list --engine claude                       # one engine, all projects
+apx sessions list --engine codex --dir /path --limit 10 # one engine, one dir
 ```
 
-Output format per engine: `DATE | SESSION ID | TITLE`, newest first, plus the exact native-CLI resume command at the bottom.
-
-When no `--engine` is passed, output is grouped by engine with `══ <Engine> ══` headers. Empty engines print `(sin nada)`; un-installed engines are not listed at all.
+Per engine: `DATE | SESSION ID | TITLE` newest first, plus the native-CLI resume command at the bottom. Without `--engine`, output is grouped with `══ <Engine> ══` headers. Empty engines print `(sin nada)`; uninstalled engines are omitted.
 
 ---
 
-## Resuming a session by id (the headline command)
+## Resuming by id (`apx session resume <id>`)
 
-```bash
-apx session resume <id>
-```
-
-What it does, in order:
+1. Searches every engine (apx → claude → codex).
+2. **One match** → prints metadata (engine, path, cwd, title).
+3. **Zero matches** → non-zero exit with `session "<id>" not found in any detected engine`.
+4. **Multiple matches** → prints all, exit 2, asks for `--engine <id>`.
 
-1. Searches every detected engine for `<id>` (apx → claude → codex).
-2. **One match** → prints metadata: engine, file path, cwd, title.
-3. **Zero matches** → exits non-zero with `session "<id>" not found in any detected engine`.
-4. **Multiple matches (collision)** → prints all of them and exits with code 2, telling you to re-run with `--engine <id>`.
-
-Then it applies any of the following flags:
+Flags:
 
 | Flag | Effect |
 |------|--------|
-| `--engine <apx\|claude\|codex>` | Restrict the search to one engine (skip auto-detection). |
-| `--tail N[k\|m]` | Print last N bytes of the transcript (e.g. `--tail 32k`). No daemon required. |
-| `--full` / `--body` | Dump the entire transcript. No daemon required. |
-| `--summary` | Send the tail to the APX super-agent and print a 4-bullet summary. **Requires daemon + `super_agent.enabled`.** |
-| `--continue` | Spawn the engine's native CLI in resume mode (`claude --resume <id>`, `codex resume <id>`) in the recorded cwd. |
-| `--into apx[:slug]` | Create a brand-new APX session whose body is the summary of `<id>`. Frontmatter records `parent_session: <engine>:<id>` for lineage. Default slug = the session's original APX agent if any, else the first agent in `AGENTS.md`. |
-| `--project <name\|id\|path>` | Used only for `--summary` on apx-native sessions (picks the daemon project). |
+| `--engine <apx\|claude\|codex>` | Skip auto-detection. |
+| `--tail N[k\|m]` | Print last N bytes (e.g. `--tail 32k`). No daemon. |
+| `--full` / `--body` | Dump entire transcript. No daemon. |
+| `--summary` | Tail → super-agent → 4-bullet summary. **Daemon + `super_agent.enabled`.** |
+| `--continue` | Spawn engine's native CLI in resume mode (`claude --resume <id>`, `codex resume <id>`) in recorded cwd. |
+| `--into apx[:slug]` | Create a new APX session whose body is the summary of `<id>`. Frontmatter records `parent_session: <engine>:<id>`. Default slug = original APX agent if any, else first agent in `AGENTS.md`. |
+| `--project <name\|id\|path>` | Only for `--summary` on apx-native sessions. |
 
-### Common recipes
+### Recipes
 
 ```bash
-# "I have a Codex session id, give me a summary in apx"
+# Codex id → summary in apx
 apx session resume 019abc... --summary
 
-# "I want to keep working on that Codex thread, but in APX with the reviewer agent"
+# Continue a Codex thread inside APX with the reviewer agent
 apx session resume 019abc... --summary --into apx:reviewer
 
-# "Just dump the full transcript so I can grep it"
+# Dump full transcript and grep
 apx session resume 019abc... --full | rg "TODO"
 
-# "Re-open in the native CLI, interactively"
+# Re-open in native CLI
 apx session resume 019abc... --continue
 
-# "I know it's a Claude session, skip auto-detect"
+# Known Claude session, skip auto-detect
 apx session resume 2e3c840b-... --engine claude --tail 16k
 ```
 
 ---
 
-## Reading a session's content (`apx session get`)
-
-`apx session get` is the "fetch and read" command. It has two modes:
-
-### Default mode — local APC project sessions
+## Reading content (`apx session get`)
 
 ```bash
-apx session get <id>             # metadata of the local APC session
+# Default: local APC project sessions
+apx session get <id>             # metadata
 apx session get <id> --body      # full markdown body
 apx session get <id> --json      # machine-readable metadata
-```
-
-### Engine mode — read any engine's session by id
 
-```bash
-apx session get <id> --engine claude --full       # full Claude JSONL
-apx session get <id> --engine codex  --tail 16k   # last 16 KB of a Codex rollout
-apx session get <id> --any --full                  # search every engine, error on collision
-apx session get <id> --engine claude --json        # JSON metadata only
+# Engine mode: any engine by id
+apx session get <id> --engine claude --full
+apx session get <id> --engine codex  --tail 16k
+apx session get <id> --any --full                 # search all engines, error on collision
+apx session get <id> --engine claude --json
 ```
 
-**This is the command you want when you're inside Claude and need to ingest a Codex/Claude session as context.** Pipe `--full` into a file or directly into your prompt.
+**Use this to pull a Codex/Claude session into your current context.** Pipe `--full` into a file or prompt:
 
 ```bash
-# Pull a Codex session into context for the current Claude session
 apx session get 019abc... --engine codex --full > /tmp/prev.jsonl
 ```
 
 ---
 
-## Daemon vs. no daemon
+## Daemon requirements
 
-| Capability | Daemon required? |
-|------------|------------------|
-| `apx session find ...` | ❌ no |
-| `apx sessions list ...` | ❌ no |
-| `apx session get ...` (any mode) | ❌ no |
-| `apx session resume <id>` (metadata only) | ❌ no |
-| `apx session resume <id> --tail / --full` | ❌ no |
-| `apx session resume <id> --continue` | ❌ no |
-| `apx session resume <id> --summary` / `apx session summary <id>` | ✅ yes (daemon + `super_agent.enabled` in `~/.apx/config.json`) |
-| `apx session ask <id> "<q>"` | ✅ yes (daemon + `super_agent.enabled`) |
-| `apx session resume <id> --into apx[:slug]` | ⚠️ daemon needed only to compute the summary it embeds; without it, the new session is created with an empty summary block |
+| Capability | Daemon? |
+|------------|---------|
+| `find`, `list`, `get`, `resume <id>` (metadata/tail/full/continue) | no |
+| `resume --summary`, `summary`, `ask` | yes (daemon + `super_agent.enabled` in `~/.apx/config.json`) |
+| `resume --into apx[:slug]` | daemon needed only to compute embedded summary; without it the new session has an empty summary block |
 
 If the daemon is down, `apx` auto-starts it when needed.
 
 ---
 
-## Native APX session commands (legacy / still useful)
+## Native APX session commands (legacy, still useful)
 
-These manage APX-native sessions (the `.md` files in `~/.apx/projects/.../sessions/`). They do **not** see Claude/Codex sessions.
+Manage APX-native sessions (`.md` files in `~/.apx/projects/.../sessions/`). They do **not** see Claude/Codex sessions.
 
 ```bash
 apx session new <slug> --title "Investigate bug X"
-apx session list                       # all agents in the current APC project
-apx session list <slug>                # one agent
+apx session list                       # all agents in current APC project
+apx session list <slug>
 apx session update <id> --status "in progress"
 apx session close <id> --result "Fixed in PR #42"
-apx session check                      # exit 1 if any APX session is still open
-apx session close-stale                # auto-close sessions older than 1h
-apx session compact <slug>             # summarize a conversation durable to disk
+apx session check                      # exit 1 if any APX session is open
+apx session close-stale                # auto-close >1h old
+apx session compact <slug>             # summarize a conversation to disk
 ```
 
-These live next to the new cross-engine commands above; they don't replace each other.
-
 ---
 
 ## Disambiguating collisions
 
-If two engines happen to use the same id string for different sessions:
-
 ```
 $ apx session resume abc123
 ⚠️  session id "abc123" exists in multiple engines:
   - claude  /Users/.../-Volumes-work-repo/abc123.jsonl  (cwd: /Volumes/work/repo)
-  - codex   /Users/.../sessions/2026/05/27/rollout-2026-05-27T10-00-00-abc123.jsonl  (cwd: /Volumes/work/repo)
+  - codex   /Users/.../sessions/2026/05/27/rollout-...-abc123.jsonl  (cwd: /Volumes/work/repo)
 → re-run with --engine <id> to pick one (apx | claude | codex)
 ```
 
-Pick one with `--engine claude` or `--engine codex` and run again.
+Pick one with `--engine claude` or `--engine codex`.
 
 ---
 
 ## Tips for callers (LLMs)
 
-1. **Start with `find`, not grep.** If the user describes a session by topic instead of id, run `apx session find "<text>"`. Never reconstruct this with `apx sessions list | grep` — that's the exact footgun this command replaces.
-2. **Don't ask the user which engine.** Auto-detect handles it. If the CLI prints a collision message, *then* re-run with `--engine`.
-3. **`summary` for the gist, `ask` for specifics.** Use `apx session summary <id>` to orient; use `apx session ask <id> "<q>"` when the user has a concrete question. Both need the daemon + `super_agent.enabled`.
-4. **`ask` on a huge transcript is slow and capped.** If the output warns about truncation and the user needs full coverage, re-run with a higher `--max-chunks`.
-5. **Prefer `--tail N` over `--full`** when feeding a raw transcript into another model — JSONL is verbose, the tail is dense.
-6. **`--into apx:slug` is the bridge** between an external runtime's session and an APX agent. Use it when the user says "let's continue this in apx with the reviewer agent".
-7. **Don't invent ids.** Discover them via `apx session find` or `apx sessions list`.
-8. **`apx session get --any --full`** is the simplest way to import an arbitrary engine session into your context, with no daemon dependency.
+1. **Start with `find`, not grep.** Never reconstruct via `apx sessions list | grep`.
+2. **Don't ask the user which engine.** Auto-detect handles it; re-run with `--engine` only on collision.
+3. **`summary` for the gist, `ask` for specifics.** Both need daemon + `super_agent.enabled`.
+4. **`ask` on huge transcripts is slow and capped.** Raise `--max-chunks` if truncation warns and full coverage matters.
+5. **Prefer `--tail N` over `--full`** when feeding raw transcripts to another model — JSONL is verbose, the tail is dense.
+6. **`--into apx:slug`** is the bridge for "let's continue this in apx with the reviewer agent".
+7. **Don't invent ids.** Discover them via `find` or `sessions list`.
+8. **`apx session get --any --full`** is the simplest no-daemon import of any engine session.
 
 ---
 
-## Quick reference card
+## Quick reference
 
 ```bash
 # Discovery
-apx session find "<text>"                          # find by title across engines (start here)
-apx session find "<text>" --deep                   # also search transcript content
-apx sessions list                                  # all engines, all projects
-apx sessions list --project <name>                 # all engines, one project
-apx sessions list --engine <id> --dir <path>       # one engine, one dir
+apx session find "<text>"                          # start here
+apx session find "<text>" --deep
+apx sessions list
+apx sessions list --project <name>
+apx sessions list --engine <id> --dir <path>
 
 # Understand
-apx session summary <id>                           # LLM summary of any session
-apx session ask <id> "<question>"                  # Q&A over the transcript (map-reduced)
+apx session summary <id>
+apx session ask <id> "<question>"
 
 # Read
-apx session get <id>                               # local APC session metadata
-apx session get <id> --engine <id> --full          # any engine, full transcript
-apx session get <id> --any --tail 32k              # any engine, last 32 KB
+apx session get <id>                               # local APC metadata
+apx session get <id> --engine <id> --full
+apx session get <id> --any --tail 32k
 
 # Resume / continue
-apx session resume <id>                            # auto-detect engine, show metadata
-apx session resume <id> --summary                  # add super-agent summary
-apx session resume <id> --continue                 # spawn native CLI to keep working
-apx session resume <id> --into apx:<slug>          # seed a new APX session with the summary
+apx session resume <id>
+apx session resume <id> --summary
+apx session resume <id> --continue
+apx session resume <id> --into apx:<slug>
 ```