heyspex 0.1.0 → 0.2.1

package/.claude-plugin/marketplace.json

@@ -0,0 +1,14 @@
+{
+  "name": "heyspex-marketplace",
+  "owner": {
+    "name": "pwher",
+    "email": "paul@monstergrowth.com"
+  },
+  "plugins": [
+    {
+      "name": "heyspex",
+      "source": "./plugins/heyspex",
+      "description": "SpexCode plugin (for Claude Code and GitHub Copilot CLI): HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+    }
+  ]
+}

package/README.md

@@ -112,6 +112,26 @@ Every machine points somewhere: a console (local or cloud), a read tier, and a w
 
 If `/hs-next` or the `heyspex_*` tools are missing, run `npm run doctor` and restart the agent session.
 
+### Inside a SpexCode session
+
+The `spexcode` launcher opens a SpexCode session - HeySpex's own chat front, a thin wrapper over `hs chat` that runs any model. What you see and what to type:
+
+- **The header.** The terminal is cleared, then a compact header in Claude Code's shape: the HeySpex glyph and `SpexCode v<version>`, the model line, the folder · seat line, the mode · vault line, and a hint block (`/hs-next` pull your next task, `/recent` what shipped recently, `/handoff` hand this session off, `/help` every command by category). Launch jobs (PROFILE, BOOTSTRAP) run above the input box and never block the prompt; when BOOTSTRAP finishes it prints a context block - where you left off, other open work, the dispatcher hand-off, and recalled memories.
+- **`/help`** is a category index; `/help chat|skills|cli|fleet|vault|setup|quality|learn|companion` expands one category. The CLI rows are parsed live from `hs --help`, so they cannot drift from the CLI.
+- **`/recent [n]`** lists recent work from the WIP ledger and `git log` (`/recent 20` for more).
+- **`!<cmd>`** runs one shell command without the model. **`/shell`** (alias `/cli`; also `/shell on|off`) switches to CLI mode - the caret becomes `$`, the status line shows `$ shell`, and every line runs in the shell; **`/ai`** switches back. `cd` is applied locally, and command output rides into the next model turn as context. The shell is `pwsh -NoLogo -NoProfile -Command` on Windows and `sh -c` elsewhere; set `SPEXCODE_SHELL` to override it (for example `pwsh -NoLogo -Command` to load your PowerShell profile). Stdin is not connected, so interactive commands - editors, REPLs, anything that prompts - need a separate terminal.
+- **Pasting.** A multi-line paste collapses to one `[Pasted text #1 +5 lines]` row in the input box (type after it if you like, then Enter), the transcript echoes it once as `❯ [Pasted text #1 +5 lines] <first line>`, and the model still receives the whole text. A single-line paste is typed as usual. Set `agent_behaviors.spexcode.paste_label: summary` in `.heyspex/config.yaml` to have the seat's model write a five-to-ten-word label instead (`❯ [Pasted text #1 +5 lines: failing login redirect stack trace]`) - one short no-tools call per paste, capped at 4 s, falling back to the lines marker on any error or timeout. `lines` (the default) makes no call.
+- **Sessions survive their window.** Every turn is appended, as it completes, to `.heyspex/sessions/<id>.jsonl` in the working folder (the newest 20 are kept; the folder is gitignored), together with the shell cwd and shell mode it ran under. **`spexcode --resume`** restores the latest session for that folder - its messages, shell cwd and shell mode - and prints `Resumed session from <age> · <n> turns`; **`spexcode --resume <id>`** names one (the id is the file name without `.jsonl`). Inside a session, **`/resume`** lists the newest 10 in an arrow-key picker and restores the one you choose (`/resume <id>` names one; without a terminal - piped, `--script`, `--plain` - it restores the latest with no picker). A resumed session is written to a fresh file seeded with the restored turns, so the newest file is always the whole story.
+- **`/compact`** summarizes the older conversation into one block through the session's own model, keeping the last 4 turns verbatim, replaces the live history in place, and prints `Compacted <n> turns into a summary. Context 78% → 31% (41,200 → 16,400 tokens).` Two `.heyspex/config.yaml` keys govern it: `agent_behaviors.spexcode.compact.auto_threshold_pct` compacts automatically after any turn whose context use reaches that percentage (absent, `0`, `off` or `false` = never - the default), and `agent_behaviors.spexcode.context_window_tokens` overrides the model's window when the built-in table is wrong. That table (a substring match on the model name, first hit wins) is what the status line's context percentage is computed against:
+
+  | model name contains | window (tokens) |
+  |---|---|
+  | `claude` | 200,000 |
+  | `deepseek` | 128,000 |
+  | `gpt-oss` | 128,000 |
+  | `qwen` | 32,768 |
+  | anything else | 128,000 |
+
 ## Reference shelf
 
 Look-up material, not required reading. Start with the [glossary](specs/glossary.md) when a term is unfamiliar.
@@ -137,6 +157,7 @@ The full folder (`specs/protocols/`, about 70 protocols) is reference material -
 | Your role | Read these |
 |---|---|
 | Everyone | [docs/claude-code-setup.md](docs/claude-code-setup.md) or [docs/cursor-setup.md](docs/cursor-setup.md) (whichever editor you drive), [docs/sharing-secrets-with-your-team.md](docs/sharing-secrets-with-your-team.md) |
+| Working on HeySpex itself | [docs/admin/](docs/admin/README.md) - admin pages that assume localhost, dev mode, and this clone |
 | Console work | [dev-server-lifecycle-and-db-safety](specs/protocols/dev-server-lifecycle-and-db-safety.md), the design-system registry under `spex-console/public/design-system/` |
 | Companion work | .NET 8 SDK plus `pwsh` prerequisites above, [docs/fleet/companion-app-distribution.md](docs/fleet/companion-app-distribution.md), [docs/fleet/cloud-relay-add-machine.md](docs/fleet/cloud-relay-add-machine.md), [docs/fleet/chrome-extension-distribution.md](docs/fleet/chrome-extension-distribution.md) |
 | Fleet machines | [docs/fleet/README.md](docs/fleet/README.md), [docs/fleet/release-runbook.md](docs/fleet/release-runbook.md), [scripts/public-install/README.md](scripts/public-install/README.md) |