habithive-code 0.2.4 → 0.3.0

package/docs/COMPATIBILITY.md

@@ -0,0 +1,158 @@
+ # habithive-code compatibility record: dependency refresh
+
+Date: 2026-10-23
+Change: `hive-dependency-refresh` (design D7, tasks group 1)
+
+## Decision
+
+| Pin | Value | Reason |
+|-----|-------|--------|
+| `OPENCODE_PIN` | **1.19.4** (moved from 1.19.0 on 2026-10-28) | Every opencode internal Hive relies on is unchanged from 1.18.34 → 1.19.0 (findings 1 to 6) and from 1.19.0 → 1.19.4 (see "Recheck: opencode 1.19.4"). No blocking difference. |
+| `OMO_SPEC` | **`oh-my-openagent@4.19.1`** (fallback; 5.1.33 is blocked) | oh-my-openagent 5.1.33 moves Hive's model-tree file out of the way on first plugin load and discards its `agents` and `categories` (finding 9). Hive reads and writes that file today (`OMO_CONFIG` in `src/core.js`), so 5.x needs a code change (target `~/.omo/omo.jsonc`), which is a separate change. The combination opencode 1.19.0 + oh-my-openagent 4.19.1 was verified headless (finding 9). |
+
+Consequence for this change: set `OMO_SPEC = "oh-my-openagent@4.19.1"` in `src/versions.js` (it currently reads 5.1.33). Design D8 (baseline refresh after an oh-my-openagent migration) and task 3.4 do not apply while the pin stays on 4.19.1.
+
+## Tested versions
+
+| Component | Previous | Tested | Status |
+|-----------|----------|--------|--------|
+| opencode | 1.18.34 | 1.19.0 | Compatible (binary inspection and headless run). Live TUI checks pending. |
+| opencode | 1.19.0 | 1.19.4 | Compatible (binary inspection, headless OMO 4.19.1 and OmniRoute runs). Pinned. Live TUI checks pending. |
+| @opencode-ai/plugin (SDK) | 1.18.34 | 1.19.0 | `dist/tui.d.ts` identical to 1.18.34. |
+| oh-my-openagent | 4.19.1 | 5.1.33 | **Blocked** for Hive as built (finding 9). Not pinned. |
+| oh-my-openagent | 4.19.1 | 4.19.1 on opencode 1.19.0 | Compatible (headless): overrides in `oh-my-openagent.json` applied, file byte-identical after load. |
+| openspec | 1.5.0 | 1.14.1 | Compatible. Every command the repo workflow uses exists. |
+| graphify (graphifyy) | 0.9.88 | 0.9.90 | Compatible. Every subcommand and flag used by the bundled skill exists. |
+| @playwright/mcp | unpinned (`@latest`) | 0.0.83 | Informational: 0.0.83 is the current `latest` dist-tag (node >= 18). Hive keeps `@latest`. |
+
+## Method
+
+- Everything ran under a fresh temp directory with `HOME` pointed into it; `opencode-ai@1.19.0` and `opencode-ai@1.18.34` were installed with `npm i --prefix <temp>`, never globally. Nothing under the real `~/.config/opencode`, `~/.habithive`, `~/.local/state/opencode` or `~/.local/bin` was touched.
+- opencode: `strings -n 12` on both binaries; for each internal, a window around a string literal was extracted from both builds and compared after replacing minified identifiers with a placeholder. "Identical" below means the normalized windows are equal (windows of 400 to 9,200 characters).
+- oh-my-openagent: `npm pack` of 4.19.1 and 5.1.33 (`dist/index.js`, `dist/oh-my-opencode.schema.json`), plus live runs of `opencode debug config` (loads the plugin and runs its startup migration) in isolated homes with sample data only.
+- openspec and graphify: run via `npx -y` and `uvx` with temp `HOME` and caches.
+
+## Findings
+
+### Recheck: opencode 1.19.4 (2026-10-28)
+
+Same method as below (isolated HOME, binary literal/normalised-window comparison, headless runs). Full notes: `orchestrate-agents/review/opencode-1.19.4/recheck.md`.
+
+- **Same as 1.19.0:** on-screen model order; session restore of agent + model; the four `app.exit` registrations; `model.list` / `model.cycle_recent` / `model.cycle_favorite`; config merge order, `autoupdate`, CLI flags and `--version` format; plugin SDK `dist/` byte-identical; TUI plugin loader literals.
+- **Headless:** oh-my-openagent 4.19.1 loads, an `oracle` override applies, `oh-my-openagent.json` is byte-identical afterwards; a custom `omniroute` provider with no `apiKey` sends the `/connect` key.
+- **Changed, no Hive impact:** the update check is semver-aware and still returns early with `autoupdate: false`; `opencode upgrade` without a target prints "Couldn't check for updates" when the lookup fails (an explicit target is unaffected); `import` help text.
+- **Changelog 1.19.1–1.19.4:** 1.19.1 removes session sharing; 1.19.2 stops offering OpenCode 2.x to 1.x installs; 1.19.3 reasoning variants; 1.19.4 Bun 1.4.4. 1.19.5 (released 2026-10-28) was not tested.
+
+### opencode 1.18.34 → 1.19.0
+
+| # | Component | Old → new | Difference | Hive impact | Action |
+|---|-----------|-----------|------------|-------------|--------|
+| 1 | TUI on-screen model order (a) | 1.18.34 → 1.19.0 | **Same.** One read of `model.json`. Current model = per-agent in-memory pick (`<store>.model[agent.name]`), else the agent's configured `.model`, else fallback (`--model` arg, config `model`, first valid `recent` entry, provider default). | None. | None. |
+| 2 | Session open restores agent and model (b) | 1.18.34 → 1.19.0 | **Same.** An effect keyed on `sessionID` calls `agent.set(<msg>.agent)` (only when no `--agent` arg) then `model.set(<msg>.model)` and `model.variant.set(...)`. The `--model` arg is applied earlier in `onMount` with `{recent:true}`. | None. | None. |
+| 3 | `app.exit` registrations (c) | 1.18.34 → 1.19.0 | **Same.** Four registrations: "Exit the app" (slash `exit`, `quit`, `q`), "Cancel permission rejection", "Reject permission", "Reject question". | None. | None. |
+| 4 | Built-in model commands (d) | 1.18.34 → 1.19.0 | **Same.** `model.list` (slash `models`, alias `mo`), `model.cycle_recent` (`cycle(1)`: finds the current model in in-memory `recent`, no-op if absent, else sets the agent's pick to the next entry, does not save), `model.cycle_favorite`, plus the two reverse variants. | None. | None. |
+| 5 | Config and update handling (e) | 1.18.34 → 1.19.0 | Global merge order is **the same** (`config.json`, then `opencode.json`, then `opencode.jsonc`; observed in the 1.19.0 run log). `autoupdate` still accepts `true`, `false` or `"notify"`, and `false` (or `OPENCODE_DISABLE_AUTOUPDATE`) still stops the update check entirely. `opencode upgrade [target]` is unchanged. **New in 1.19.0:** `upgrade --major` (moves to OpenCode 2), a skip message pointing at it, and a TUI update dialog with a `/update` command (Update, Skip, Upgrade, Restart). | Pin and `autoupdate:false` (D3) still work. The `/update` dialog is only fed by the update check, which `autoupdate:false` short-circuits, but this needs a live look. | Keep D2 and D3 as designed. Use `opencode upgrade <pin>` (explicit target, never `--major`). |
+| 6 | Plugin SDK (f) | 1.18.34 → 1.19.0 | `dist/tui.d.ts` is **byte-identical**. Present: `api.keymap` (typed `Keymap` from `@opentui/keymap`; the 1.19.0 binary calls `keymap.dispatchCommand`), `api.command.trigger` (deprecated, still works: logs a one-time deprecation then calls `keymap.dispatchCommand`), `api.state.session.messages/permission/question`, `api.app.version`, `api.lifecycle.signal`. Peer dependencies `@opentui/core|keymap|solid >= 0.4.5`, all optional. | None. | None. |
+
+### oh-my-openagent 4.19.1 → 5.1.33
+
+| # | Component | Old → new | Difference | Hive impact | Action |
+|---|-----------|-----------|------------|-------------|--------|
+| 7 | Schema: agents, categories, top-level keys | 4.19.1 → 5.1.33 | The same 14 agent keys (`OpenCode-Builder`, `atlas`, `build`, `explore`, `hephaestus`, `librarian`, `metis`, `momus`, `multimodal-looker`, `oracle`, `plan`, `prometheus`, `sisyphus`, `sisyphus-junior`); `categories` is still open (any string key). Top-level keys 46 → 46: **`codegraph` removed**, **`ulw_execute` added**. `start_work` was **already in 4.19.1** (not new); in 5.x it is deprecated in favour of `ulw_execute`. Agent entries gain `models` and `reasoning`; category entries gain `models`, `reasoning`, `max_tokens`, `provider_options`, `warn_unavailable`. `reasoningEffort`, `variant` and `fallback_models` remain accepted. Builtin category enum unchanged (8 names), but see finding 11. | Hive's 4 main and 7 sub agents are all present. | None for the schema itself. |
+| 8 | Unknown keys | 4.19.1 → 5.1.33 | The published JSON schema has `additionalProperties:false` at the top level (editor validation only). At runtime unknown keys are reported and ignored: with `bogus_key`, `codegraph`, `start_work` and an unknown agent in `~/.omo/omo.jsonc` the plugin still loaded and applied the `oracle` override. `codegraph` is actively stripped. **The startup migration validates strictly**: the same file produced `[config-migration] legacy configuration changes were not applied ... Unrecognized keys: "bogus_key", "start_work"`, and the migration was skipped (file untouched). | An existing `codegraph` key is harmless. A stray key can silently disable the migration. | Relevant only if 5.x is adopted later. |
+| 9 | **First-run config migration (blocking)** | 4.19.1 → 5.1.33 | 4.19.1 reads `~/.config/opencode/oh-my-openagent.json` in place; in the test it was byte-identical after load (its `migrateConfigFile` rewrites only when one of its migrations applies; applied ids are tracked in `_migrations` or a `.migrations.json` sidecar). **5.1.33 runs `runOpenCodeStartupMigration` on every plugin load.** It discovers `oh-my-openagent.{jsonc,json}` and `oh-my-opencode.{jsonc,json}` in the opencode config dir (and in `.opencode/` from the working directory up to `$HOME`), **moves** them to `~/.omo/migration-backup-<timestamp>-opencode-config/`, and writes `~/.omo/omo.jsonc`. Only `disabled_providers`, `model_fallback`, `models` and `sisyphus_agent` are carried over; **`agents` and `categories` are deleted**. Observed: after one `opencode debug config`, the source file was gone, `omo.jsonc` held only `_migrations`, and Sisyphus fell back to the default model instead of the sample override. User settings are read from `~/.omo/omo.jsonc` (top-level `agents` and `categories`, or an `[opencode]` block); verified that sample overrides there are applied. | **Breaks the model tree.** Hive writes `oh-my-openagent.json` and snapshots it as the baseline; on 5.x the next launch moves the file away and drops every override, and Reset would restore a file OMO no longer reads. | Do not pin 5.x in this change. Follow-up change: point `OMO_CONFIG` at `~/.omo/omo.jsonc`, re-capture the baseline from it, keep the legacy path as a migration source (D8). |
+| 10 | In-place rewrite of `omo.jsonc` | 4.19.1 → 5.1.33 | On first load 5.x rewrites an existing `omo.jsonc` (keeping `omo.jsonc.bak.<timestamp>`): `variant` and `reasoningEffort` become `reasoning`; an agent with `fallback_models` becomes a `models` array (primary first) and **loses its `model` key**; `codegraph` is dropped; `_migrations` is stamped. | Hive reads `agents.<name>.model` back from the file; after the rewrite that field can be absent. | Follow-up change must read `models[0]` as well as `model`. |
+| 11 | Category rename | 4.19.1 → 5.1.33 | `categories.deep` is renamed to `deep-low` (migration `2026-09-category-deep-split`; `deep-high` is a new category). Verified: a `deep` override in `omo.jsonc` came back as `deep-low`. | `KNOWN_CATEGORIES` in `src/core.js` lists `deep`, not `deep-low`/`deep-high`. | Follow-up change: update the category list. |
+| 12 | GPT guard hooks | 4.19.1 → 5.1.33 | Both hooks **still exist** under the same names, enabled by default, disabled via `disabled_hooks`. Both act on `chat.message`; the model id is the part after the last `/`, lowercased. `no-sisyphus-gpt`: agent `sisyphus` and id contains `gpt` and does not match `/gpt-5[.-](?:(?:3[.-])?codex\|[4-9]\|\d{2,})/i` (5.x also exempts ids containing `gpt-6`) switches the session to `hephaestus`. 5.x does this only if Hephaestus is registered; otherwise it shows a toast and keeps Sisyphus. `no-hephaestus-non-gpt`: agent `hephaestus` and id does not contain `gpt` shows an error toast, then **4.19.1 switches the session to `sisyphus`; 5.1.33 throws `HephaestusRequiresGptError` and aborts the message**. Opt-out for both: `agents.hephaestus.allow_non_gpt_model: true` (warning toast only). In both versions Hephaestus is absent from the agent list when its configured model is not a GPT model (observed). | A non-GPT model on Hephaestus (or a non-native GPT on Sisyphus) is rerouted or rejected by OMO, not by Hive. 5.x turns the reroute into a hard error. | Keep Hive's "Hephaestus is GPT-only" label. Consider surfacing the rule in the model tree. |
+| 13 | Package metadata | 4.19.1 → 5.1.33 | Neither version declares `peerDependencies` or `engines`. 4.19.1 depends on `@opencode-ai/plugin` and `@opencode-ai/sdk` 1.15.13; 5.1.33 no longer depends on them (dependencies are `@opentui/solid ^0.5.11`, `detect-libc`, `zod`). `dist/tui.js` has no static `@opentui` imports in either version. | No version constraint ties OMO to a specific opencode release. | Live check that the OMO TUI plugin loads on 1.19.0 (only matters for 5.x). |
+| 14 | `tui.json` and telemetry (informational) | 4.19.1 → 5.1.33 | Both versions contain `ensureTuiPluginEntry`, which writes the plugin entry into `tui.json` when absent (observed on both). Anonymous telemetry is enabled by default in both; opt out with `telemetry: false` or `OMO_DISABLE_POSTHOG`. | Hive already manages `tui.json` per mode. Telemetry default may matter in a healthcare setting. | Informational. |
+
+### openspec 1.5.0 → 1.14.1
+
+| # | Component | Old → new | Difference | Hive impact | Action |
+|---|-----------|-----------|------------|-------------|--------|
+| 15 | `init --tools opencode .` and CLI | 1.5.0 → 1.14.1 | Generated: 5 skills and 5 commands → **6 and 6** (adds `.opencode/commands/opsx-update.md` and `.opencode/skills/openspec-update-change/SKILL.md`); also creates `openspec/specs/.gitkeep` and `openspec/changes/archive/.gitkeep`. Common files: `opsx-apply`, `opsx-archive`, `opsx-explore`, `opsx-propose`, `opsx-sync` and the five matching skills. The propose command gains a "Planning boundary" paragraph. Six more workflows (`new`, `continue`, `ff`, `bulk-archive`, `verify`, `onboard`) are available through `openspec config profile`. CLI: new `version` command; `validate` adds `--archived --report`; `status` adds `--all`; `list` adds `--archived --all`. Everything the repo's commands call (`list --json`, `status --change/--json`, `instructions [apply] --change`, `new change`, `store list --json`, `validate --type change --strict`) exists, and `openspec validate hive-dependency-refresh --type change --strict` passes on 1.14.1. | None for Hive (it does not bundle openspec). | None. |
+
+### graphify (graphifyy) 0.9.88 → 0.9.90
+
+| # | Component | Old → new | Difference | Hive impact | Action |
+|---|-----------|-----------|------------|-------------|--------|
+| 16 | CLI and skill | 0.9.88 → 0.9.90 | `graphify --help` differs in three places: `hook install` now also installs a `post-merge` hook; new `pi guard install`, `pi guard uninstall` and `pi guard path`. No top-level command removed. The 24 real CLI invocations in `skills/graphify/SKILL.md` (`add`, `query`, `path`, `explain`, `update`, `cluster-only`, `merge-graphs`, `clone`, `export <fmt>`, `extract`, `hook`, `save-result`, `benchmark`, `claude`) all resolve, and every flag on them is in the 0.9.90 help. The `/graphify <path> --html`-style flags are slash-command syntax handled by the skill, not CLI flags. The skill file packaged inside the wheel is byte-identical between 0.9.88 and 0.9.90. | None. The bundled `SKILL.md` already differs from the packaged one (frontmatter, `--falkordb` flags, `references/`); that predates this change. | None. Optionally refresh the bundled skill separately (it is byte-identical across both repos). |
+
+### Reference machine (informational, read-only)
+
+| # | Item | Observation |
+|---|------|-------------|
+| 17 | Stale oh-my-openagent copies | `~/.cache/opencode/packages/node_modules/oh-my-openagent` is 4.13.0 and `~/.cache/opencode/packages/oh-my-openagent@latest` is 4.15.0 (`oh-my-openagent@4.19.1` is also cached). `~/.config/opencode/package.json` still depends on `oh-my-openagent ^4.15.0` and `@opencode-ai/plugin 1.3.17`. None is loaded while the config names an exact version. Not modified. |
+
+## Needs live verification
+
+These cannot be checked headlessly. Run them in a real TUI, in an isolated `HOME`, after `habithive setup --yes` with the final pins.
+
+- [ ] Hive TUI plugin loads on opencode 1.19.0 (no "import-but-skip", factory runs on first chat).
+- [ ] `/habithive` opens and lists the dialogs.
+- [ ] Mode switch complex to simple and simple to complex relaunches and keeps the session (`--session <id>`).
+- [ ] Model tree writes (all, category, agent) reach the file oh-my-openagent 4.19.1 reads, and apply after relaunch.
+- [ ] Reset restores the captured baseline.
+- [ ] Home-screen wordmark renders.
+- [ ] `model.cycle_recent` after a session restore: the restored model is found in `recent` (otherwise the command is a no-op, as in 1.18.34).
+- [ ] The `/update` dialog does not appear with `autoupdate: false`.
+- [ ] Hephaestus set to a non-GPT model in the model tree: confirm the 4.19.1 behaviour (error toast, then the session switches to Sisyphus).
+- [ ] (Only for the follow-up that adopts oh-my-openagent 5.x) OMO TUI plugin loads on 1.19.0, and the `~/.omo/omo.jsonc` path round-trips through Hive's model tree.
+
+## OmniRoute key source (opencode 1.19.0)
+
+Headless experiment: opencode-ai 1.19.0 in an isolated `HOME`, a local OpenAI-compatible stub logging the `Authorization` header, custom provider `omniroute` (`@ai-sdk/openai-compatible`, `options.baseURL` only unless stated), run with `opencode run -m omniroute/auto/fast "say ok"`. Only fake keys were used.
+
+| Case | Config (`options`) | Env `OMNIROUTE_API_KEY` | auth.json (`/connect`) | Authorization sent | Conclusion |
+|------|--------------------|-------------------------|------------------------|--------------------|------------|
+| A | no `apiKey` | unset | `connect-key-123` | `Bearer connect-key-123` | The `/connect` key is used. |
+| B | `apiKey: "{env:OMNIROUTE_API_KEY}"` | unset | `connect-key-123` | none (no header) | The empty `{env:}` result shadows the `/connect` key. |
+| C | `apiKey: "{env:OMNIROUTE_API_KEY}"` | `env-key-456` | `connect-key-123` | `Bearer env-key-456` | The config `apiKey` wins over auth.json. |
+| D | no `apiKey` | unset | none | none (no header) | The provider is still allowed (defined in config) and the request is sent unauthenticated. |
+
+Conclusion: a provider block with no `apiKey` line plus a key saved through `/connect` is sufficient. A leftover `apiKey: "{env:OMNIROUTE_API_KEY}"` line breaks `/connect` unless that variable is exported.
+
+Guidance: if your `opencode.jsonc` still has `"apiKey": "{env:OMNIROUTE_API_KEY}"` under `provider.omniroute.options`, delete that line (or export the variable) so the `/connect` key is sent.
+
+## OpenCode 2
+
+Date: 2026-10-23
+Change: `hive-opencode-v2-guard` (ADR-0010; research: `review/opencode-2/SUMMARY.md`)
+
+### Status
+
+- OpenCode 2 is stable: 2.0.0 shipped 2026-09-11, current 2.1.3 (npm `@opencode/cli`, Homebrew `anomalyco/tap/opencode-v2`).
+- OpenCode 1 is still patched (`opencode-ai` 1.19.4, 2026-10-22), no end-of-life date announced.
+- `opencode upgrade --major` (from 1.19) moves an install to OpenCode 2: npm-family installs swap `opencode-ai` for `@opencode/cli`, brew swaps the formula, curl replaces the binary; data is migrated in place.
+
+### What breaks
+
+| Area | On OpenCode 2 |
+|------|---------------|
+| oh-my-openagent | 4.19.1 fails to load; 5.x loads only a stub that toasts a redirect to a separate product (OmO Native). Agents, tools and hooks do not run. **Complex mode and the model tree have no engine.** |
+| Plugin module | The v1 `{ id, tui }` shape is gone (new `{ id, setup(context) }`); the Hive plugin does not load (non-fatal). TUI plugin wiring moves to `cli.json`; no `home_logo` slot. |
+| CLI | `--version` prints `opencode v2.x`; `--model`, `--agent`, `--fork`, `--pure` are rejected; `opencode upgrade 1.19.0` fails (404), so Hive cannot downgrade through OpenCode 2. |
+| Credentials, process model | `/connect` keys move to SQLite; the TUI is a client of a shared background service. |
+| Unchanged | Config files and merge order, `autoupdate`, `provider` blocks, `model.json`. |
+
+### Decision
+
+ADR-0010: Hive stays on OpenCode 1 (pinned, ADR-0003). OpenCode 2 is unsupported until a complex-mode engine exists on it (OmO Native is evaluated separately).
+
+Behaviour:
+
+- The launcher replaces the "not the tested version" line with a notice (OpenCode 2 detected, Hive needs OpenCode 1, recovery steps for the detected install method) and still starts opencode.
+- `habithive status` adds a line saying OpenCode 2 is not supported.
+- `habithive setup` and `habithive reconcile` (so `habithive update`) never run `opencode upgrade` against OpenCode 2; they print the recovery steps and continue.
+- Install method comes from the resolved path of `opencode` on PATH (npm, brew, curl, else unknown, which lists all three). Hive never uninstalls or reinstalls opencode for you.
+
+- npm: `npm rm -g @opencode/cli`, then `habithive setup`
+- Homebrew: `brew uninstall opencode-v2`, then `habithive setup`
+- curl installer: `curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.0`
+
+Sessions created under OpenCode 2 may not open in OpenCode 1 (OpenCode 2 migrates data in place; the reverse is not verified).
+
+## OpenSpec 1.5.0 pin
+
+Hive pins `@fission-ai/openspec` at 1.5.0. OpenSpec 1.14.x rejects `generates` paths containing `..`, and the intent-driven schema's ADR step writes outside the change folder (`../../adr/`), so the schema fails validation there. 1.5.0 accepts it. `habithive setup` installs the pin and copies the bundled intent-driven schema to the user-level OpenSpec schemas folder; OpenSpec 1.5.0 needs Node 20.19 or newer. See ADR-0011.

package/docs/guide/01-getting-started.md

@@ -0,0 +1,135 @@
+# 1. Getting started
+
+## What it is
+
+Hive installs and wires opencode, oh-my-openagent, the Hive plugin, extra tools and skills with one command, then launches opencode in complex mode. This chapter takes you from nothing to a verified install. The command is `habithive`; `hive` is the same command.
+
+## Prerequisites
+
+| Need | Why |
+|------|-----|
+| Node.js 20.19 or newer | OpenSpec 1.5.0 requires it. Hive checks at start and exits with a message if Node is older. |
+| Internet access | First setup fetches opencode, oh-my-openagent, OpenSpec and graphify. |
+| `uv` or `pip` (Python) | Installs the graphify CLI. If neither exists, setup warns and continues. |
+
+Upgrade Node with a version manager, for example:
+
+```sh
+nvm install 22
+```
+
+## Install
+
+```sh
+npm i -g habithive-code
+```
+
+If npm fails with `EACCES`, its global prefix is not writable. Do not use `sudo`. Use a user-owned prefix or a Node version manager:
+
+```sh
+mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
+export PATH="$HOME/.npm-global/bin:$PATH"     # add to your shell profile
+npm i -g habithive-code
+```
+
+On version 0.2.4 or earlier `habithive update` does not exist. Upgrade once with `npm i -g habithive-code@latest && habithive setup`. Setup leaves you in complex mode; if you used simple mode, run `habithive simple` once afterwards. Setup also removes comments from the config files it changes; the original is kept as a `.habithive-bak-<timestamp>` file next to each one (see [Files and safety](08-files-and-safety.md)).
+
+## Run setup
+
+```sh
+habithive setup
+```
+
+Setup asks before installing opencode if it is missing (`--yes` or `-y` skips the question). It is always a full install; `--minimal` is ignored with a message. Steps, in order:
+
+| Step | What it does |
+|------|--------------|
+| opencode | Installs `opencode-ai` at the pinned version, or runs `opencode upgrade <pin>` if another 1.x is present. OpenCode 2 is never touched; setup prints how to go back. |
+| oh-my-openagent | Adds `oh-my-openagent@4.19.1` to the complex mode config. |
+| Hive plugin | Adds the Hive plugin `file://` entry to `tui.json` in both modes. |
+| autoupdate | Sets `"autoupdate": false` in `opencode.jsonc`. |
+| OmniRoute | Adds or refreshes the OmniRoute provider (38 models) with a placeholder address. |
+| Playwright MCP | Adds the `playwright` MCP server if absent. |
+| OpenSpec | Installs `@fission-ai/openspec@1.5.0` if the installed version differs. |
+| intent-driven schema | Copies the schema to `~/.local/share/openspec/schemas/intent-driven`. |
+| graphify | Installs or upgrades `graphifyy` via `uv` or `pip`. |
+| Skills | Copies bundled skills to `~/.config/opencode/skills/`. |
+
+On the first setup Hive records complex mode in `~/.habithive/mode`. Running setup again is safe: it changes only what differs and writes nothing when everything is current. If a config file cannot be parsed, setup stops and prints `file:line:column`. If `hive` on your PATH is another program, setup warns; use `habithive`.
+
+## First launch
+
+```sh
+habithive
+```
+
+This starts a new session in complex mode. Other forms:
+
+```sh
+habithive simple        # vanilla opencode
+habithive -c            # continue the last session
+habithive -s <id>       # continue a specific session
+```
+
+## Enable OmniRoute
+
+Every install includes the OmniRoute provider pointing at `http://localhost:20128/v1`. If you are eligible, point it at your team's gateway, then add your key in opencode:
+
+```sh
+habithive --gateway <ip>
+```
+
+Pass the IP only; Hive adds `http://` and port 20128. Then run `/connect` in opencode, pick OmniRoute and paste your key. Hive never writes a key. See [OmniRoute](04-omniroute.md).
+
+## Verify
+
+```sh
+habithive status        # prints "habithive: complex mode"
+```
+
+In opencode: `/habithive` opens the Hive menu and `/hive-models` opens the model tree. The home screen shows the HABITHIVE wordmark.
+
+## Install from a source checkout
+
+```sh
+git clone https://repository.hclhealthcare.in/hive/habit-hive-code.git
+cd habit-hive-code
+npm test                        # every suite should report 0 failed
+node bin/habithive.mjs status   # smoke test, nothing installed globally
+npm i -g .
+habithive setup
+```
+
+You need a GitLab account with access to the `hive` group. From a checkout, `habithive update` never reinstalls from npm; it prints `git -C <checkout> pull && habithive update`.
+
+## Migrating from the previous package name
+
+`habithive-code` replaces an earlier package with a different name and plugin entry. If the old one is still wired into any opencode config, both load and two wordmarks stack on the home screen. opencode reads plugins from the global config and from per-project configs (`opencode.json`, `opencode.jsonc`, `.opencode/opencode.json`), so clean both:
+
+```sh
+npm rm -g maliv-code
+rm -rf ~/.maliv
+find ~ -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/Library/*" \( -name "tui.json" -o -name "opencode.json" -o -name "opencode.jsonc" \) -print0 2>/dev/null \
+  | xargs -0 grep -l "maliv" 2>/dev/null \
+  | while read -r f; do
+      echo "cleaning: $f"
+      node -e '
+        const fs = require("fs");
+        const p = process.argv[1];
+        const raw = fs.readFileSync(p, "utf8");
+        const c = JSON.parse(raw.replace(/\/\*[\s\S]*?\*\//g, "").replace(/^\s*\/\/.*$/gm, ""));
+        if (Array.isArray(c.plugin)) c.plugin = c.plugin.filter(e => !String(e).includes("maliv"));
+        fs.writeFileSync(p, JSON.stringify(c, null, 2) + "\n");
+      ' "$f"
+    done
+habithive setup
+```
+
+The script rewrites each file as plain JSON, so comments in those files are lost. If a cleaned file is tracked by git in a shared project, commit that fix, or teammates will bring the old entry back. Skip this section if you never had the old package.
+
+## Related
+
+- [Modes](02-modes.md)
+- [OmniRoute](04-omniroute.md)
+- [Files and safety](08-files-and-safety.md)
+- [Troubleshooting](09-troubleshooting.md)

package/docs/guide/02-modes.md

@@ -0,0 +1,105 @@
+# Modes: simple and complex
+
+## What it is
+
+Hive runs opencode in one of two modes. **Complex** mode loads oh-my-openagent (the multi-agent layer) plus Hive's plugin. **Simple** mode is vanilla opencode plus Hive's plugin, with oh-my-openagent off. You can start in either mode and switch at any time, from the shell or from inside opencode, without losing your session.
+
+| | Simple | Complex |
+|---|--------|---------|
+| oh-my-openagent | off | on (pinned `oh-my-openagent@4.19.1`) |
+| Hive plugin (`tui.json`) | on | on |
+| Agents, categories, model tree | not used | available |
+| Startup | fastest | loads the agent layer |
+
+Complex is the default.
+
+## Launching
+
+`hive` is the same command as `habithive`.
+
+| Command | Result |
+|---------|--------|
+| `habithive` | Complex mode, new session |
+| `habithive simple` | Simple mode, new session |
+| `habithive complex` | Complex mode, new session |
+| `habithive -c` | Continue the last session (also `--continue`) |
+| `habithive -s <id>` | Continue a specific session (also `--session <id>`) |
+| `habithive new` | New session (the default; also `-n`, `--new`) |
+| `habithive status` | Print the current mode and any queued switch |
+
+Flags combine with a mode and any other arguments opencode accepts:
+
+```bash
+habithive simple -c
+habithive complex -s <id>
+habithive status
+```
+
+Output of `status` looks like `habithive: complex mode`, with ` · queued → simple` appended if an in-app switch is waiting.
+
+On exit, Hive prints the resume commands (`habithive -c` and `habithive -s <id>`). Use those rather than opencode's own `opencode -s` hint so the right mode and plugin load.
+
+## Switching inside opencode
+
+| Command | What it does |
+|---------|--------------|
+| `/habithive-mode` | Opens the mode menu: switch to Simple or Complex |
+| `/habithive` | Umbrella menu: model tree, switch mode, reset model overrides |
+
+Choosing a mode queues the switch and quits opencode. The `habithive` launcher, which is still running, reopens opencode in the new mode and returns to **the same session** (`--session <id>`).
+
+Details worth knowing:
+
+- A brand-new session with no messages has no saved ID yet, so the relaunch opens a fresh session. Hive never uses `--continue` here, because that would reopen an older conversation.
+- Switching only works when opencode was started by `habithive`. Otherwise Hive shows a toast with the command to run, for example `restart with habithive simple to switch mode`, and does not quit.
+- If a permission or question prompt is open, Hive waits until you answer it before quitting.
+- If opencode ignores the quit, a warning appears after 3 seconds: type `/exit` so Hive can reopen the session.
+
+## How a switch works
+
+Each mode owns **one complete set of config files**.
+
+| Set | Location while active | Location while inactive |
+|-----|-----------------------|-------------------------|
+| Active mode | `~/.config/opencode/` (`opencode.jsonc`, `tui.json`) | n/a |
+| Inactive mode | n/a | `~/.habithive/modes/<mode>/` |
+
+Hive also manages `opencode.json` if it lists oh-my-openagent. The list of managed files is recorded in `~/.habithive/modes/files.json`.
+
+- **A switch only renames files.** The active set moves to the store and the other set moves into `~/.config/opencode/`. File contents are not edited.
+- **The first switch creates the other set, once,** by copying your active files and adding or removing the oh-my-openagent plugin entry. If either file cannot be parsed, the switch stops and names the file and line. Nothing is changed.
+- **A normal launch writes no config.** Launching in the mode you are already in touches nothing.
+- **Hive's record of the active mode** is `~/.habithive/mode`.
+
+### Additions stay in one mode
+
+Because the sets are independent, a change you make in one mode is not in the other. Add an MCP server, plugin or provider while in complex mode and it is absent in simple mode. Hive prints this reminder after each switch.
+
+To carry a change across, copy it by hand into the other set's file. While in complex mode, the simple set sits in `~/.habithive/modes/simple/`:
+
+```bash
+# edit the stored file directly (this is the inactive mode's copy)
+$EDITOR ~/.habithive/modes/simple/opencode.jsonc
+```
+
+Edit stored files only for the inactive mode. Do not edit them while that mode is active, because the active copy lives in `~/.config/opencode/`. Keep the oh-my-openagent entry out of the simple set.
+
+`habithive setup` and `habithive update` apply Hive's own entries (plugin, pins, OmniRoute block) to both sets, so those stay aligned without manual work. See [07-updates-and-versions.md](07-updates-and-versions.md).
+
+## Recovering from an interrupted switch
+
+A switch writes a journal (`~/.habithive/switch.journal`) before renaming anything. If Hive is killed mid-switch, the next `habithive` launch finishes the switch, or rolls it back if it cannot, and prints one of:
+
+- `completed interrupted switch to <mode> mode`
+- `rolled back interrupted switch to <mode> mode (...); still <mode> mode`
+- `could not recover interrupted switch (...); see ~/.habithive/switch.journal`
+
+In the last case, compare `~/.habithive/modes/` with `~/.config/opencode/`, restore the files by hand, then delete the journal. An unreadable journal produces a similar message. See [09-troubleshooting.md](09-troubleshooting.md).
+
+## Related
+
+- [01-getting-started.md](01-getting-started.md): install and first launch
+- [03-model-tree.md](03-model-tree.md): the model tree (complex mode)
+- [08-files-and-safety.md](08-files-and-safety.md): every file Hive touches
+- [09-troubleshooting.md](09-troubleshooting.md)
+- [Guide index](README.md)

package/docs/guide/03-model-tree.md

@@ -0,0 +1,100 @@
+# Model tree
+
+## What it is
+
+The model tree is a menu inside opencode for choosing which model each oh-my-openagent agent and task tier uses. Open it with `/hive-models` (alias `/hivemodels`) or from the `/habithive` umbrella menu. It is meant for complex mode, where oh-my-openagent is loaded. The on-screen model is changed live through opencode's own picker; everything else is saved to a config file and takes effect after a relaunch, which Hive performs for you.
+
+## The rows
+
+Rows appear in this order. Each row shows the configured model, such as `→ provider/model`, or `→ (default)` when nothing is set.
+
+| Group | Row | Sets |
+|-------|-----|------|
+| Live | **This screen (live)** | Opens opencode's own model picker. Instant, no relaunch. |
+| Everything | **★ Everything (agents + tiers)** | One model for every agent and every tier |
+| Main agents (primary) | **★ All main agents** | The four main agents below |
+| | Sisyphus — ultraworker | `sisyphus` |
+| | Prometheus — plan builder | `prometheus` |
+| | Atlas — plan executor | `atlas` |
+| | Hephaestus — deep (GPT-only) | `hephaestus` |
+| Subagents | **★ All sub agents** | The seven subagents below |
+| | Oracle — deep reasoning / debugging | `oracle` |
+| | Explore — codebase search | `explore` |
+| | Librarian — external docs | `librarian` |
+| | Multimodal-looker — images / visual | `multimodal-looker` |
+| | Metis — plan consultant | `metis` |
+| | Momus — plan critic | `momus` |
+| | Sisyphus-Junior — worker | `sisyphus-junior` |
+| Categories (tiers) | `ultrabrain`, `deep`, `quick`, `visual-engineering`, `artistry`, `writing`, `unspecified-low`, `unspecified-high` | One tier each |
+
+Picking a row opens a filterable list of every model from your connected providers. Choose one, or choose **Clear override (use default)** to remove the override for that row. Group rows show `→ all: <model>` when every member agrees and `→ (mixed)` when they differ.
+
+## Precedence
+
+The most specific setting wins:
+
+```
+agent  >  category  >  all  >  default
+```
+
+- **agent**: an override on one agent.
+- **category**: an override on a tier.
+- **all**: the "Everything" row.
+- **default**: your original `oh-my-openagent.json`, saved as the baseline (see below).
+
+Two behaviors follow from how Hive compiles the settings:
+
+- Choosing a model on **Everything** replaces any agent and category overrides, so one model really applies everywhere.
+- If any category override exists, agents without their own override drop their model and inherit from their category, which is how oh-my-openagent cascades.
+
+## What is live and what needs a relaunch
+
+| Change | Applies |
+|--------|---------|
+| This screen (live) | Immediately. It is opencode's own picker. |
+| Any other row | After a relaunch, which Hive performs (same session) |
+
+oh-my-openagent reads its config once at startup. Writing the file does not change a running process, so Hive saves your choice, quits opencode, and the `habithive` launcher reopens the same session. A row saved but not yet in effect shows ` · pending relaunch` after its model.
+
+### Main agent models after relaunch
+
+opencode restores a session's last-used model when you reopen it, overriding config. To make a main-agent change (Sisyphus, Prometheus, Atlas, Hephaestus, the main group, or Everything) show up on screen, Hive:
+
+1. Reorders opencode's recent-models list so the old model and the new one are adjacent.
+2. Leaves a short-lived marker (valid 10 minutes).
+3. After the relaunch, triggers opencode's recent-model cycle exactly once to move the active agent to the new model, and shows a toast such as `sisyphus → provider/model`.
+
+If the cycle cannot run, Hive opens the native model picker and shows `select <model> to apply it to <agent>`. Pick the model there.
+
+Subagents and tiers never change the on-screen model, so they skip this step.
+
+## Safety
+
+- **Not started by `habithive`:** Hive does not quit. It saves the change and shows `saved — restart with habithive -c to apply`.
+- **Prompt open:** if a permission or question prompt is open, Hive waits until it is answered, then quits.
+- **Quit ignored:** after 3 seconds a warning asks you to type `/exit` so the session can reopen.
+- **Model rules:** oh-my-openagent enforces them, not Hive. Sisyphus does not accept most GPT models: among GPT models only `gpt-5.4` and newer, `gpt-5-codex` and `gpt-5.3-codex` are accepted (non-GPT models are fine). Hephaestus is GPT-only unless your config sets `allow_non_gpt_model`. If you pick a model that breaks a rule, Hive warns beforehand: oh-my-openagent will reroute and the agent keeps its previous model.
+
+## Reset
+
+`/habithive` then **Reset all model overrides** clears every override and rewrites `oh-my-openagent.json` from the baseline. Relaunch to apply. It does not quit for you.
+
+## Where settings live
+
+| File | Role |
+|------|------|
+| `~/.habithive/overrides.json` | Your overrides: `all`, `categories`, `agents` |
+| `~/.habithive/baseline.json` | Snapshot of your original `oh-my-openagent.json`, the "default" and the Reset target |
+| `~/.config/opencode/oh-my-openagent.json` | What oh-my-openagent reads. Hive compiles it from overrides plus baseline. |
+| `~/.habithive/oh-my-openagent.first-backup.json` | Copy of the file as found when the baseline was first captured |
+| `~/.local/state/opencode/model.json` | opencode's own picker state; Hive only reorders its `recent` list |
+
+On a fresh install, where `oh-my-openagent.json` does not exist yet, the baseline is empty and Hive writes only your overrides. If you later edit the file yourself, Hive recaptures the baseline once rather than overwriting your changes. Edit overrides through the menu, not by hand in `oh-my-openagent.json`, because Hive rewrites that file when you apply a change.
+
+## Related
+
+- [02-modes.md](02-modes.md): the model tree needs complex mode
+- [06-agents-skills-tools.md](06-agents-skills-tools.md): what each agent does
+- [04-omniroute.md](04-omniroute.md): OmniRoute models appear in the picker once connected
+- [08-files-and-safety.md](08-files-and-safety.md)
+- [Guide index](README.md)

package/docs/guide/04-omniroute.md

@@ -0,0 +1,98 @@
+# OmniRoute gateway
+
+## What it is
+
+OmniRoute is your team's model gateway. It exposes an OpenAI-compatible API, so opencode talks to it through the `@ai-sdk/openai-compatible` adapter. Hive ships an `omniroute` provider with a fixed set of 38 models, installed for everyone with a placeholder address (`http://localhost:20128/v1`). The package contains no real gateway address. A developer becomes eligible by pointing Hive at the gateway and adding a key.
+
+## Enable OmniRoute on your machine
+
+Get the gateway IP from your team, then run:
+
+```bash
+habithive --gateway <ip>
+```
+
+Behavior:
+
+- Takes the IP only. Hive builds `http://<ip>:20128/v1` itself.
+- Writes the address into the OmniRoute block of **both** mode sets (see [02-modes.md](02-modes.md)), adding the block if it is missing.
+- Prints `OmniRoute enabled (...)` and the files updated, or `already set`.
+- **Exits without launching opencode.**
+- Rejects input that is not a bare dotted IPv4 address: a scheme or port (`pass only the IP address: habithive --gateway <ip>`), out-of-range or malformed numbers (`not a valid IPv4 address: ...`), or no value (`usage: habithive --gateway <ip>`).
+- Stops and names the file, line and column if a config file cannot be parsed.
+
+## Add your key
+
+Start opencode and run `/connect`, choose OmniRoute, and enter your API key. opencode stores it; Hive never writes or reads secrets. No model is made a default: choose OmniRoute models in the model picker or the [model tree](03-model-tree.md).
+
+Who may use the gateway is controlled in the OmniRoute dashboard. Hive has no command to disable access; to remove a developer, change their eligibility there.
+
+## What updates do and do not touch
+
+`habithive update`, `habithive reconcile` and `habithive setup` keep the block current.
+
+| Hive keeps aligned | Hive never touches |
+|--------------------|--------------------|
+| Provider `name` (`OmniRoute`) | The address (`options.baseURL`) once set |
+| Adapter (`@ai-sdk/openai-compatible`) | Any `apiKey` in the block |
+| The 38 shipped model entries (names and limits) | Models you added yourself |
+| | Everything outside `provider.omniroute` |
+
+An update never changes the address. If the address is empty or missing, it is reset to the placeholder.
+
+### Old `apiKey` line
+
+If your block has `"apiKey": "{env:OMNIROUTE_API_KEY}"` from an older hand-copied config, either export `OMNIROUTE_API_KEY` or delete that line. With the variable unset, opencode sends no key and ignores the one saved by `/connect`. Hive does not add or remove that line. Evidence is in [../COMPATIBILITY.md](../COMPATIBILITY.md).
+
+## The 38 shipped models
+
+Reference for the `omniroute` provider. Context and input limits are equal. Every model is marked as supporting reasoning, temperature and tool calls. Generated from `OMNIROUTE_MODELS` in `src/omniroute.js`.
+
+| Model id | Context | Input | Output |
+|----------|---------|-------|--------|
+| `auto/best-coding` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-reasoning` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-fast` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-vision` | 200,000 | 200,000 | 131,072 |
+| `auto/best-chat` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-coding-fast` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/pro-coding` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/pro-reasoning` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/pro-vision` | 128,000 | 128,000 | 8,192 |
+| `auto/pro-chat` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/pro-fast` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/coding` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/fast` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/chat` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/cheap` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/offline` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/smart` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/claude-opus` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/claude-sonnet` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-free` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/best-chaos` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/chaos` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/coding:fast` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/coding:cheap` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/coding:free` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/coding:pro` | 128,000 | 128,000 | 8,192 |
+| `auto/coding:reliable` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/reasoning` | 1,000,000 | 1,000,000 | 384,000 |
+| `auto/reasoning:pro` | 128,000 | 128,000 | 8,192 |
+| `auto/vision` | 200,000 | 200,000 | 131,072 |
+| `auto/multimodal` | 200,000 | 200,000 | 131,072 |
+| `auto/glm` | 1,000,000 | 1,000,000 | 131,072 |
+| `auto/minimax` | 128,000 | 128,000 | 8,192 |
+| `auto/mimo` | 200,000 | 200,000 | 131,072 |
+| `auto/zai` | 128,000 | 128,000 | 8,192 |
+| `auto/gemma` | 128,000 | 128,000 | 8,192 |
+| `auto/llama` | 128,000 | 128,000 | 8,192 |
+| `auto/gemini` | 1,048,576 | 1,048,576 | 65,535 |
+
+## Related
+
+- [01-getting-started.md](01-getting-started.md)
+- [03-model-tree.md](03-model-tree.md): assign OmniRoute models to agents
+- [07-updates-and-versions.md](07-updates-and-versions.md)
+- [09-troubleshooting.md](09-troubleshooting.md)
+- [Guide index](README.md)