habithive-code 0.2.4 → 0.3.0

package/docs/guide/05-spec-workflow.md

@@ -0,0 +1,159 @@
+# 05. Spec workflow
+
+## What it is
+
+Hive ships a spec workflow built on OpenSpec and a custom schema called `intent-driven`. A change moves through a fixed chain of written artifacts (proposal, specs, design, ADR, tasks) before any code is written, and the agent then implements the task list. `habithive setup` installs everything you need. `habithive spec init` prepares a project to use it.
+
+## Why a spec workflow
+
+- The intent (why) is written down before the implementation (how).
+- Behaviour is described as testable GIVEN/WHEN/THEN scenarios, not prose.
+- Long-lived architectural decisions are kept in the repo as ADRs, so the next change can read them.
+- The agent works from a checklist and marks progress, so a session can be resumed.
+
+## OpenSpec is pinned at 1.5.0
+
+Setup and update install exactly `@fission-ai/openspec@1.5.0`. A newer install is moved down to it. Newer releases (1.14.x was tested) reject the `intent-driven` schema, because its ADR step writes outside the change folder, and silently fall back to the default `spec-driven` schema. OpenSpec 1.5.0 needs Node.js 20.19 or later, which is why Hive requires it too.
+
+The pin moves only with a Hive release. See [../COMPATIBILITY.md](../COMPATIBILITY.md).
+
+## The intent-driven chain
+
+```
+proposal -> specs -> design -> adr -> tasks -> apply
+```
+
+| Step | Produces | Requires | Contents |
+|------|----------|----------|----------|
+| proposal | `proposal.md` | nothing | Why (1-2 sentences), What Changes (mark breaking items **BREAKING**), Capabilities (new and modified, kebab-case names), Impact |
+| specs | `specs/<capability>/spec.md` | proposal | One delta spec per capability. Requirements and scenarios in Gherkin style |
+| design | `design.md` | proposal | Context, Goals / Non-Goals, Decisions (with alternatives), Risks / Trade-offs, Migration Plan, Open Questions |
+| adr | `<repo>/adr/NNNN-title.md` | design | New Architecture Decision Records for long-term decisions |
+| tasks | `tasks.md` | specs, adr | Numbered groups of `- [ ] X.Y` checkbox tasks |
+| apply | code | tasks | Work through pending tasks and tick them off |
+
+### Specs
+
+Each spec file is an OpenSpec delta. Use these headings exactly so archive can merge them:
+
+- `## ADDED Requirements`, `## MODIFIED Requirements` (paste the full updated requirement, not a partial diff), `## REMOVED Requirements` (needs **Reason** and **Migration**), `## RENAMED Requirements` (`FROM:` / `TO:`).
+- Each requirement is `### Requirement: <name>` and needs at least one scenario.
+- Each scenario is `#### Scenario: <name>` (four hashes) with GIVEN, WHEN and THEN steps, plus AND or BUT for follow-ons.
+
+```markdown
+## ADDED Requirements
+
+### Requirement: Export as CSV
+Users can export the report table.
+
+#### Scenario: Export with rows
+- **GIVEN** a report with three rows
+- **WHEN** the user chooses Export
+- **THEN** a CSV file with a header and three rows is downloaded
+```
+
+Write observable outcomes in THEN steps. Do not create `.feature` files.
+
+### Design
+
+Include `design.md` only when it helps: cross-cutting changes, new dependencies or data models, security, performance or migration concerns, or real ambiguity. Before writing, the agent reads the existing ADRs and keeps the design consistent with those in force. If a design needs to revisit an ADR, it lists that under Open Questions rather than editing the ADR.
+
+## ADR rules
+
+- ADRs live in the repository's top-level `adr/` folder, beside `openspec/`. Never under `openspec/` and never inside a change folder.
+- File name: `NNNN-kebab-title.md`, a four-digit sequence one higher than the highest in use. Numbers are never reused.
+- ADRs are immutable once accepted. Do not edit a prior ADR: not its status, body or date.
+- To change a decision, write a new ADR with status `accepted, supersedes ADR-NNNN` and a `Supersedes:` field naming the old one. The old ADR stays as history.
+- An ADR is in force unless a later ADR supersedes it. The agent walks the `Supersedes:` links to find the set in force.
+- Only record decisions that are long-term, affect future changes, and are not already covered. If nothing qualifies, no ADR is created.
+
+An ADR has: Status, Date, Supersedes, Context and Problem Statement, Considered Options, Decision Outcome, Consequences.
+
+## Set up a project: `habithive spec init`
+
+Run it from the project root (or pass a folder):
+
+```bash
+cd my-project
+habithive spec init
+```
+
+It requires the `openspec` command on PATH (`habithive setup` installs it). It then:
+
+1. Runs `openspec init --tools opencode`, creating `openspec/`, the opencode slash commands and skills.
+2. Copies the `intent-driven` schema into `openspec/schemas/intent-driven/` so it is committed with your code.
+3. Sets `schema: intent-driven` in `openspec/config.yaml`.
+4. Runs `openspec schema validate intent-driven` and prints `ok` or `failed`.
+
+Then commit `openspec/` and `.opencode/`.
+
+If `openspec/config.yaml` already exists, Hive changes nothing. It prints the current schema, and if that is not `intent-driven` it prints how to switch:
+
+```bash
+openspec schema fork intent-driven intent-driven
+# then set `schema: intent-driven` in openspec/config.yaml
+```
+
+## Slash commands
+
+`openspec init --tools opencode` creates these commands in the project's `.opencode/commands/`, in both modes:
+
+| Command | Does |
+|---------|------|
+| `/opsx-propose` | Creates a change and generates the artifacts in one step |
+| `/opsx-explore` | Think through an idea or problem before or during a change |
+| `/opsx-apply` | Implements `tasks.md`, ticking checkboxes |
+| `/opsx-sync` | Syncs delta specs into `openspec/specs/` without archiving |
+| `/opsx-archive` | Archives a finished change |
+
+There are no global `/opsx` commands. They exist only in projects that have been initialised. Matching skills are created under `.opencode/skills/`.
+
+## Worked example
+
+```text
+/opsx-propose export-report-csv     # change folder + proposal, specs, design, tasks
+```
+
+1. Review `openspec/changes/export-report-csv/proposal.md` and the spec scenarios. Edit them until they say what you want.
+2. Check `design.md`, and the new file in `adr/` if a long-term decision was made.
+3. Run `/opsx-apply`. The agent implements tasks and marks `- [ ]` as `- [x]`.
+4. Validate, then archive:
+
+```bash
+openspec validate export-report-csv --type change --strict
+```
+
+```text
+/opsx-sync       # optional: merge specs now
+/opsx-archive    # finish and archive the change
+```
+
+If a change name is ambiguous, `openspec list --json` lists the changes.
+
+## Refresh a project's schema copy
+
+Setup and update refresh the user-level schema only. A project keeps its own copy in `openspec/schemas/intent-driven/` and `habithive spec init` will not overwrite it. To take a newer shipped version, replace the project copy with the user-level one and review the diff before committing:
+
+```bash
+cp -R ~/.local/share/openspec/schemas/intent-driven/. openspec/schemas/intent-driven/
+```
+
+## Where the user-level schema lives
+
+Setup and update install the schema to OpenSpec's data directory so every project can resolve it:
+
+| Platform | Path |
+|----------|------|
+| macOS, Linux | `~/.local/share/openspec/schemas/intent-driven/` |
+| With `XDG_DATA_HOME` set | `$XDG_DATA_HOME/openspec/schemas/intent-driven/` |
+| Windows | `%LOCALAPPDATA%\openspec\schemas\intent-driven\` |
+
+Hive owns this folder. If you edited it, setup moves your copy to `~/.habithive/schema-backups/intent-driven-<timestamp>` before installing the shipped one. Make lasting changes in a project copy instead.
+
+## Related
+
+- [06-agents-skills-tools.md](06-agents-skills-tools.md)
+- [07-updates-and-versions.md](07-updates-and-versions.md)
+- [09-troubleshooting.md](09-troubleshooting.md)
+- [../COMPATIBILITY.md](../COMPATIBILITY.md)
+- [README.md](README.md)

package/docs/guide/06-agents-skills-tools.md

@@ -0,0 +1,97 @@
+# 06. Agents, skills and tools
+
+## What it is
+
+In complex mode Hive runs opencode with oh-my-openagent, which adds named agents and task categories. Hive also installs two skills and three tools (graphify, Playwright MCP, OpenSpec). All of this is installed by `habithive setup`. Hive does not bundle opencode or oh-my-openagent; it installs them from their official sources.
+
+## Agents
+
+oh-my-openagent has four main agents and seven subagents. Hive's model tree (`/hive-models`) lists exactly these.
+
+Main agents are primary modes. You switch between them in the TUI and they use the model selected on screen.
+
+| Agent | Role |
+|-------|------|
+| `sisyphus` | Ultraworker, the default orchestrating agent |
+| `prometheus` | Plan builder |
+| `atlas` | Plan executor |
+| `hephaestus` | Deep worker, GPT models only |
+
+Subagents are started by other agents through tasks. Each has its own model in `~/.config/opencode/oh-my-openagent.json`.
+
+| Agent | Role |
+|-------|------|
+| `oracle` | Deep reasoning and debugging |
+| `explore` | Codebase search |
+| `librarian` | External documentation |
+| `multimodal-looker` | Images and visual input |
+| `metis` | Plan consultant |
+| `momus` | Plan critic |
+| `sisyphus-junior` | Worker |
+
+## Categories
+
+Categories are task tiers. An agent delegating work picks a category, and the category decides the model. oh-my-openagent defines eight:
+
+`ultrabrain`, `deep`, `quick`, `visual-engineering`, `artistry`, `writing`, `unspecified-low`, `unspecified-high`.
+
+Model precedence in the tree: agent override, then category override, then the "everything" override, then your baseline. See [03-model-tree.md](03-model-tree.md).
+
+## GPT rules
+
+oh-my-openagent enforces two rules through its own hooks. Hive does not change them. It warns you before a relaunch if your chosen model will be rerouted.
+
+| Agent | Rule |
+|-------|------|
+| Sisyphus | Cannot use older GPT models. Models from `gpt-5.4` upward and the `gpt-5.x-codex` models are accepted. Otherwise the session is switched to Hephaestus. |
+| Hephaestus | Requires a GPT model. With a non-GPT model it shows an error and the session returns to Sisyphus (oh-my-openagent 4.19.1). It is also absent from the agent list. |
+
+To allow a non-GPT model on Hephaestus, set `agents.hephaestus.allow_non_gpt_model: true` in `oh-my-openagent.json`. Hive reads this setting and then does not warn. See [../COMPATIBILITY.md](../COMPATIBILITY.md) (finding 12).
+
+## Bundled skills
+
+Setup copies the skills in the package's `skills/` folder to `~/.config/opencode/skills/`, replacing earlier copies. oh-my-openagent loads them in complex mode.
+
+| Skill | For | Triggers |
+|-------|-----|----------|
+| `karpathy-guidelines` | Reducing common LLM coding mistakes: avoid overcomplication, make surgical changes, state assumptions, define verifiable success criteria | When the agent writes, reviews or refactors code (matched by its description) |
+| `graphify` | Turning code, docs, papers, images or video into a knowledge graph, and answering codebase questions from it | `/graphify`, or any codebase question, especially when `graphify-out/` exists |
+
+`karpathy-guidelines` is bundled unmodified under the MIT licence from the andrej-karpathy-skills project.
+
+## graphify CLI
+
+The `graphify` skill drives the `graphify` command-line tool, published on PyPI as `graphifyy`. Setup installs it with `uv tool install --upgrade graphifyy`, or with `pip install -U graphifyy` when `uv` is missing. If `uv` already manages it, setup runs `uv tool upgrade graphifyy`. It builds an interactive HTML graph, a JSON graph and a `GRAPH_REPORT.md`.
+
+```text
+/graphify                 # graph of the current folder
+/graphify <path> --update # re-extract only changed files
+```
+
+The skill was written for Claude Code's subagent runtime and may need tuning under opencode.
+
+## Playwright MCP
+
+Gives agents a real browser to open pages, click, fill forms and take screenshots. Setup adds this entry to `mcp` in `opencode.jsonc` (in each mode's config) if it is not there:
+
+```json
+"playwright": { "type": "local", "enabled": true, "command": "npx", "args": ["@playwright/mcp@latest"] }
+```
+
+An existing entry is kept as you wrote it. The package is fetched by `npx` on first use.
+
+## OpenSpec CLI
+
+Installed at the pinned version 1.5.0, with the `intent-driven` schema. See [05-spec-workflow.md](05-spec-workflow.md).
+
+## Licences and credits
+
+Hive installs opencode, oh-my-openagent, OpenSpec, graphify and Playwright MCP from their official sources under their own licences. Bundled skills and their licence texts are listed in [../../THIRD-PARTY-NOTICES.md](../../THIRD-PARTY-NOTICES.md). Project overview: [../../README.md](../../README.md).
+
+## Related
+
+- [02-modes.md](02-modes.md)
+- [03-model-tree.md](03-model-tree.md)
+- [05-spec-workflow.md](05-spec-workflow.md)
+- [08-files-and-safety.md](08-files-and-safety.md)
+- [README.md](README.md)

package/docs/guide/07-updates-and-versions.md

@@ -0,0 +1,115 @@
+# Updates and versions
+
+## What it is
+
+Hive is tested against specific versions of opencode, oh-my-openagent and OpenSpec. A Hive release pins those versions, and `habithive update` brings your machine to the release you install. Hive also checks once a day for a newer release and tells you inside opencode. Nothing updates on its own.
+
+## The daily update check
+
+When the Hive plugin loads, it reads a cache (`~/.habithive/update-check.json`). If a newer release is known, opencode shows a toast: `habithive v<version> available — quit and run habithive update`. At most one such toast appears per process.
+
+The cache refreshes in the background from the public npm registry when the last success is over 24 hours old and the last attempt over 1 hour old. The check has a 3-second timeout, never blocks startup and is silent on failure.
+
+## `habithive update`
+
+Quit opencode first, then run:
+
+```bash
+habithive update
+```
+
+Steps:
+
+1. Checks npm for the latest `habithive-code`.
+2. If it is newer than the installed version, runs `npm i -g habithive-code@latest`. If npm is unreachable it says so and reconciles the installed version. If the install fails, check npm's global prefix permissions and retry.
+3. Runs the **new version's** `reconcile --yes` so its pins apply, not the old ones.
+4. Prints `restart opencode to load habithive v<version>`.
+
+Update keeps your mode, model overrides and config. It does not record a mode or rename files.
+
+If you run Hive from a source checkout, `habithive update` does not overwrite it from npm. It prints `update it with: git -C <path> pull && habithive update` and reconciles the checkout.
+
+## `habithive reconcile`
+
+Reconcile is `setup` without the mode change. It is hidden from `--help` and is what `update` runs. Use it after pulling a source checkout or when you want to re-apply pins:
+
+```bash
+habithive reconcile          # prompts before installing opencode if it is missing
+habithive reconcile --yes    # no prompts
+```
+
+It runs these steps, applied to **every mode set that exists** (see [02-modes.md](02-modes.md)):
+
+| Step | Action |
+|------|--------|
+| 1 | Install opencode at the pin, or move an existing 1.x install to it with `opencode upgrade <pin>` |
+| 2 | Wire the Hive plugin (both sets) and oh-my-openagent (complex set only); replace stale entries |
+| 3 | Set `autoupdate: false` in each `opencode.jsonc` |
+| 4 | Reset Hive-owned OmniRoute values in each set ([04-omniroute.md](04-omniroute.md)) |
+| 5 | Add the Playwright MCP server if absent |
+| 6 | Install OpenSpec at its pin and the intent-driven schema |
+| 7 | Install or upgrade graphify |
+| 8 | Copy the bundled skills into `~/.config/opencode/skills/` |
+
+## Pinned versions
+
+These are set in `src/versions.js` and move only with a Hive release.
+
+| Tool | Constant | Value |
+|------|----------|-------|
+| opencode | `OPENCODE_PIN` | 1.19.4 |
+| oh-my-openagent | `OMO_SPEC` | `oh-my-openagent@4.19.1` |
+| OpenSpec | `OPENSPEC_PIN` | 1.5.0 |
+| Node.js | `NODE_MIN` | 20.19.0 (minimum, not an exact pin) |
+
+Why they are pinned: oh-my-openagent 5.x moves the config file Hive manages, and newer OpenSpec releases reject the intent-driven schema. The test evidence for each pin is in [../COMPATIBILITY.md](../COMPATIBILITY.md).
+
+### What floats
+
+| Tool | Behavior |
+|------|----------|
+| graphify | Upgraded to the latest release by `update` and `reconcile` (via `uv`, else `pip`) |
+| Playwright MCP | Wired as `@playwright/mcp@latest`; npx fetches the current version |
+
+## Why `autoupdate` is false
+
+Hive writes `"autoupdate": false` in `opencode.jsonc` in both mode sets. opencode therefore never upgrades itself to a version Hive has not tested. opencode moves only when you run `habithive update` or `habithive setup`.
+
+## Drift warnings
+
+If the opencode on your machine differs from `OPENCODE_PIN`, Hive warns:
+
+- At launch (shell): `opencode <version> is not the tested 1.19.4 — run: habithive update`
+- Inside opencode, if started without the launcher: a toast saying the same.
+
+The launch still continues. Run `habithive update` to move to the pin.
+
+## OpenCode 2 guard
+
+Hive needs OpenCode 1. On OpenCode 2, complex mode and the model tree do not work. If Hive detects a different major version it prints a red notice at launch, in `habithive status`, and during `setup`/`update`, then continues. It does not try to downgrade (OpenCode 2 cannot be downgraded with `opencode upgrade`).
+
+Recovery depends on how you installed OpenCode 2. Hive detects the method and prints one of these:
+
+```bash
+# npm
+npm rm -g @opencode/cli
+habithive setup
+
+# Homebrew
+brew uninstall opencode-v2
+habithive setup
+
+# curl installer
+curl -fsSL https://opencode.ai/install | bash -s -- --version 1.19.4
+```
+
+If the method is not detected, Hive lists all three. Sessions created under OpenCode 2 may not open in OpenCode 1.
+
+## Related
+
+- [01-getting-started.md](01-getting-started.md)
+- [02-modes.md](02-modes.md): both mode sets receive updates
+- [../COMPATIBILITY.md](../COMPATIBILITY.md): test evidence for each pin
+- [../../CHANGELOG.md](../../CHANGELOG.md)
+- [09-troubleshooting.md](09-troubleshooting.md)
+- [Guide index](README.md)

package/docs/guide/08-files-and-safety.md

@@ -0,0 +1,83 @@
+# 8. Files and safety
+
+## What it is
+
+This chapter lists every file and folder Hive reads or writes, the guarantees around those writes, and how to remove Hive completely. Paths use `~` for your home directory.
+
+## Files Hive writes
+
+### opencode config (`~/.config/opencode/`)
+
+| File | Written by | What changes |
+|------|------------|--------------|
+| `opencode.jsonc` | setup, update, `--gateway` | `plugin` (oh-my-openagent in complex mode), `autoupdate: false`, `mcp.playwright` (only if absent), `provider.omniroute` |
+| `tui.json` | setup, update | The Hive plugin `file://` entry in `plugin` |
+| `opencode.json` | setup, update | Only if it already lists oh-my-openagent: it is then part of the mode set and handled like the files above |
+| `oh-my-openagent.json` | model tree | Agent and category models. Not live: applies on relaunch |
+| `skills/<name>/` | setup, update | Copies of the bundled skills |
+| `<file>.habithive-bak-<timestamp>` | any edit above | Backup made before a change |
+
+During a mode switch these config files are also renamed, not edited (see below).
+
+### Hive store (`~/.habithive/`)
+
+| Path | Purpose |
+|------|---------|
+| `mode` | The active mode (`simple` or `complex`) |
+| `modes/<mode>/` | The inactive mode's stored config set |
+| `modes/files.json` | Which file names make up a mode set |
+| `switch.journal` | Present only during a mode switch, so an interrupted switch can finish or roll back |
+| `overrides.json` | Your model choices from the model tree |
+| `baseline.json` | Snapshot of your original `oh-my-openagent.json`, restored by Reset |
+| `oh-my-openagent.first-backup.json` | Byte copy of that original file |
+| `last-applied.sha256` | Hash of the `oh-my-openagent.json` text Hive last wrote, to tell its writes from yours |
+| `pending-apply.json` | A main-agent model change waiting to be applied after relaunch |
+| `next-mode`, `next-session` | Queued in-app mode switch and the session to reopen; cleared on launch |
+| `update-check.json` | Cache of the daily "new release?" check against the npm registry |
+| `schema-installed.sha256` | Hash of the `intent-driven` schema Hive last installed |
+| `schema-backups/` | Your edited schema copy, kept here when setup replaces it |
+
+### Elsewhere
+
+| Path | What Hive does |
+|------|----------------|
+| `~/.local/share/openspec/schemas/intent-driven` | Installs the schema (the base follows `XDG_DATA_HOME` or `LOCALAPPDATA` when set) |
+| `~/.local/state/opencode/model.json` | On a main-agent model change, moves the old and new model to the front of `recent` |
+| `<project>/openspec/`, `<project>/.opencode/` | Created by `hive spec init` |
+
+Hive also reads opencode's session list and the `opencode --version` output; it writes nothing there.
+
+## Safety guarantees
+
+- A normal launch never writes config. `habithive status` reads only `~/.habithive/mode`.
+- A mode switch only renames files. The first switch to a mode creates its set once from the active files; after that, contents are never edited.
+- Switches are journaled. A launch finishes or rolls back an interrupted switch before doing anything else.
+- Only `habithive setup`, `habithive update` and `habithive --gateway` edit your config.
+- Every edit goes through one safe-edit routine: it parses the file first, makes no write when nothing changes, saves `<file>.habithive-bak-<timestamp>` next to the file, writes through a temp file and rename, keeps the file's permissions, and keeps only the newest 5 backups per file.
+- An edited file is saved as plain JSON. Every setting is kept, but comments and layout are not; the backup keeps the original.
+- If a file cannot be parsed, Hive writes nothing and prints `cannot read <file>:<line>:<col>`. Fix the file and re-run.
+- Hive refuses to apply model overrides over an empty baseline, so it cannot wipe oh-my-openagent's config.
+- Hive never writes API keys.
+
+Never touched: your keys, other providers, sessions, projects, models you added to OmniRoute, and any config value Hive does not manage.
+
+## Uninstall
+
+Switch to the mode whose config you want to keep, because deleting `~/.habithive` removes the other mode's stored set.
+
+```sh
+habithive complex                                      # or: habithive simple
+npm rm -g habithive-code
+npm rm -g @fission-ai/openspec                         # optional: the pinned OpenSpec CLI
+rm -rf ~/.local/share/openspec/schemas/intent-driven   # optional: the schema
+rm -rf ~/.habithive
+rm -f ~/.config/opencode/*.habithive-bak-*             # optional: backups
+```
+
+Then remove the Hive plugin and `oh-my-openagent` entries from `~/.config/opencode/tui.json` and `opencode.jsonc`, and the `omniroute` provider if you do not want it. Also optional: `~/.config/opencode/skills/` copies, the `playwright` MCP entry, and `"autoupdate": false` (opencode then updates itself again). Project folders created by `hive spec init` stay.
+
+## Related
+
+- [Modes](02-modes.md)
+- [Updates and versions](07-updates-and-versions.md)
+- [Troubleshooting](09-troubleshooting.md)

package/docs/guide/09-troubleshooting.md

@@ -0,0 +1,117 @@
+# 9. Troubleshooting
+
+## What it is
+
+Each entry is a symptom, the cause Hive's code handles, and the fix. `hive` is the same command as `habithive`. Hive prints `!` lines for warnings and keeps going; it only stops on a config parse error or a failed install.
+
+## Models and relaunch
+
+### The model did not change on screen
+
+Cause: only main-agent and Everything changes move the on-screen model, and only through a relaunch. Subagent, sub-agent group and tier changes are saved to `oh-my-openagent.json` and apply on relaunch; the agent on screen keeps its model. If the automatic step cannot run, opencode's model picker opens and a toast names the model to select.
+
+Fix: select the model in the picker, or relaunch with `habithive -c`. See [Model tree](03-model-tree.md).
+
+### "waiting for the open prompt"
+
+Cause: a permission or question prompt is open. Hive does not quit opencode while one is open, because quitting would reject it.
+
+Fix: answer the prompt. The change then applies. If opencode does not quit within 3 seconds, type `/exit` so the launcher can reopen the session.
+
+### "saved - restart with `habithive -c` to apply"
+
+Cause: opencode was started as plain `opencode`, not through `habithive`, so there is no launcher to relaunch it. The change is saved.
+
+Fix: quit and run `habithive -c`.
+
+### Another mode's provider or MCP server is missing
+
+Cause: each mode keeps its own complete config set; changes made in one mode are not in the other.
+
+Fix: copy the entry from `~/.habithive/modes/<mode>/` (the inactive set) into the active file. See [Modes](02-modes.md).
+
+## Versions
+
+### "opencode X is not the tested Y"
+
+Cause: the installed opencode differs from the version pinned in this Hive release.
+
+Fix: run `habithive update`. It re-applies the pin (`opencode upgrade <pin>`). `habithive setup` does the same.
+
+### OpenCode 2 detected
+
+Cause: OpenCode 2 is installed (for example through `opencode upgrade --major`). Complex mode and the model tree do not work on it.
+
+Fix: go back to OpenCode 1 with the command for your install method, then run `habithive setup` where shown. The launcher, `habithive status` and `habithive setup` print the right commands; see the Compatibility section of the [README](../../README.md#compatibility). Never run `opencode upgrade --major`.
+
+### "habithive needs Node.js 20.19 or newer"
+
+Cause: Node is older than 20.19 (OpenSpec requires it).
+
+Fix: `nvm install 22`, then retry.
+
+### `npm i -g` fails with `EACCES`
+
+Cause: npm's global prefix is not writable. Fix: use a user-owned prefix or nvm, never `sudo`. See [Getting started](01-getting-started.md#install).
+
+## Config files
+
+### "cannot read <file>:<line>:<col>"
+
+Cause: a config file Hive must edit has a syntax error. Hive writes nothing in that case.
+
+Fix: open the file at that line and column, fix it, re-run the command.
+
+## OmniRoute
+
+### "connection refused" from OmniRoute
+
+Cause: OmniRoute is not enabled. The provider points at the placeholder `http://localhost:20128/v1` until you set a gateway.
+
+Fix: run `habithive --gateway <ip>`, then `/connect` in opencode to add your key. `habithive update` never changes the address. See [OmniRoute](04-omniroute.md).
+
+### OmniRoute sends no key
+
+Cause: an older hand-copied OmniRoute block has `"apiKey": "{env:OMNIROUTE_API_KEY}"` and that variable is unset. opencode then sends no key and ignores the one saved by `/connect`. Hive never adds or removes that line.
+
+Fix: export `OMNIROUTE_API_KEY`, or delete that line from the `omniroute` provider block.
+
+## Plugin and launcher
+
+### Two wordmarks on the home screen
+
+Cause: the previous package is still wired into a global or per-project opencode config.
+
+Fix: follow [Migrating from the previous package name](01-getting-started.md#migrating-from-the-previous-package-name).
+
+### "habithive plugin path is stale"
+
+Cause: `tui.json` names a Hive plugin path that no longer exists, for example after the global npm install moved.
+
+Fix: run `habithive setup`. It replaces the stale entry.
+
+### `hive` runs a different program
+
+Cause: another program named `hive` (such as Apache Hive) is earlier on your PATH. Setup warns about this.
+
+Fix: use `habithive`, which is the same command.
+
+## Specs
+
+### The schema is missing in a project
+
+Cause: the project has OpenSpec set up with another schema, or its `openspec/schemas/intent-driven` copy is gone. `hive spec init` leaves an initialized project alone and prints how to switch.
+
+Fix: run `habithive setup` to reinstall the user-level schema, then in the project:
+
+```sh
+openspec schema fork intent-driven intent-driven
+```
+
+and set `schema: intent-driven` in `openspec/config.yaml`. To refresh an existing copy: `rm -rf openspec/schemas/intent-driven && openspec schema fork intent-driven intent-driven`. If `hive spec init` says "openspec not found", run `habithive setup`. See [Spec workflow](05-spec-workflow.md).
+
+## Related
+
+- [Files and safety](08-files-and-safety.md)
+- [Updates and versions](07-updates-and-versions.md)
+- [docs/COMPATIBILITY.md](../COMPATIBILITY.md)

package/docs/guide/README.md

@@ -0,0 +1,32 @@
+# Hive developer guide
+
+Hive (`habithive-code`) is a control layer for opencode. This guide is for developers adopting it. Commands are written as `habithive`; `hive` is the same command.
+
+## Reading order
+
+| Chapter | What it covers |
+|---------|----------------|
+| [1. Getting started](01-getting-started.md) | Prerequisites, install, `habithive setup`, first launch, verifying |
+| [2. Modes](02-modes.md) | Simple and complex mode, how switching works |
+| [3. Model tree](03-model-tree.md) | Setting models per agent, group and tier |
+| [4. OmniRoute](04-omniroute.md) | The OmniRoute provider, gateway, key |
+| [5. Spec workflow](05-spec-workflow.md) | OpenSpec and the `intent-driven` schema in a project |
+| [6. Agents, skills and tools](06-agents-skills-tools.md) | What is bundled and installed |
+| [7. Updates and versions](07-updates-and-versions.md) | `habithive update`, pins, autoupdate |
+| [8. Files and safety](08-files-and-safety.md) | Every file Hive touches, safety guarantees, uninstall |
+| [9. Troubleshooting](09-troubleshooting.md) | Symptom, cause, fix |
+
+Technical record of tested versions: [../COMPATIBILITY.md](../COMPATIBILITY.md). Patch notes: [../../CHANGELOG.md](../../CHANGELOG.md).
+
+## I want to...
+
+| Goal | Go to |
+|------|-------|
+| Switch between simple and complex mode | [Modes](02-modes.md) |
+| Change a model | [Model tree](03-model-tree.md) |
+| Enable OmniRoute | [OmniRoute](04-omniroute.md), or [Getting started](01-getting-started.md#enable-omniroute) |
+| Start a spec in a project | [Spec workflow](05-spec-workflow.md) |
+| Update Hive | [Updates and versions](07-updates-and-versions.md) |
+| Fix a problem | [Troubleshooting](09-troubleshooting.md) |
+| Know what Hive writes to my machine | [Files and safety](08-files-and-safety.md) |
+| Remove Hive | [Files and safety](08-files-and-safety.md#uninstall) |