geneseed 3.12.0 → 3.13.0

package/docs/reference/troubleshoot-hooks.md

@@ -0,0 +1,99 @@
+---
+group: reference
+kind: "concept"
+section: "Troubleshooting"
+order: 7
+title: "Hook, context and memory problems"
+description: "Hooks that stopped firing, no readiness sigil, project docs not loaded, no memory written."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. First stop for almost anything: `geneseed doctor` (see [Troubleshooting](troubleshooting.md)).
+
+## Hooks stopped firing
+
+The agent loads its rules, but nothing is enforced and no memory is written — on Claude Code, Bob or OpenClaude.
+
+Every `geneseed` command now says so first, on stderr:
+
+> `[geneseed] ⚠ hooks are off on this machine: the hook shim points at <path>, which no longer exists. Fix: geneseed rebuild-all`
+
+and the `gates` row of `geneseed status` reads `DEAD — hook shim points at <path>; run: geneseed rebuild-all`. A script that must not see the line can set `GENESEED_NO_SHIM_CHECK=1`.
+
+**Cause.** Almost always a **stale hook shim**. Your tool's settings call `geneseed-hook` through one small script, `~/.geneseed/bin/geneseed-hook` (`geneseed-hook.cmd` on Windows), which holds the absolute path of your Geneseed folder. Move or delete that folder and the shim points at nothing: the hooks still fire, fail, and every gate goes silently dead. `geneseed doctor` reports it as:
+
+> `[shim] <path> pointed at <old path>, which does not exist — every hook in every install was dead (the checkout most likely moved).`
+
+**Fix.** Re-emit from where Geneseed lives now — any build rewrites the shim:
+
+```bash
+geneseed rebuild-all
+```
+
+If you moved the shim itself with `GENESEED_HOME`, set it the same way before rebuilding.
+
+**Confirm.** `geneseed doctor` prints no `[shim]` line, and a new session opens with the readiness sigil and your project docs in context.
+
+## The agent never shows the readiness sigil
+
+The first reply of a session should open with the readiness sigil (`✅` in the neutral theme) — the agent's sign that it loaded the harness.
+
+**Cause.** The tool is not loading the root file. On OpenCode, `opencode.json` `instructions` does not point at `AGENT.md`; on another tool, its rules setting does not.
+
+**Fix.** Rebuild the install so its config is merged again:
+
+```bash
+geneseed rebuild-all
+```
+
+For a tool Geneseed does not wire itself, point its rules setting at the bundle's `AGENT.md`.
+
+**Confirm.** Start a **new** session; the first reply opens with the sigil. See [Verify](../guides/verify.md).
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+## The agent doesn't load my project docs
+
+**Cause.** The `geneseed-context` plugin is not in OpenCode's plugins directory, or injection is switched off (`GENESEED_CONTEXT_INJECT=off`).
+
+**Fix.**
+
+```bash
+geneseed build --emit opencode-global
+```
+
+and unset `GENESEED_CONTEXT_INJECT`.
+
+**Confirm.** `ls ~/.config/opencode/plugins/` shows the `geneseed-*.js` files, and a session started with `GENESEED_DEBUG=1` logs what the plugin discovered. See [OpenCode plugins](opencode-plugins.md).
+
+## `PROJECT CONTEXT` appears twice
+
+**Cause.** Two copies of the context plugin — the global one and a leftover `.opencode/plugins/` in the repo. OpenCode loads both.
+
+**Fix.** Delete the project copy (`.opencode/plugins/geneseed-context.js`), or uninstall the project-scoped install.
+
+**Confirm.** A new session shows the block at most once.
+
+## The full `PROJECT CONTEXT` block shows in the terminal
+
+**Cause.** Either `GENESEED_CONTEXT_VISIBLE=1` (or legacy `GENESEED_CONTEXT_TRANSFORM=0`) is set, or your OpenCode build lacks the experimental hook for invisible delivery and the plugin fell back to the visible block.
+
+**Fix.** Unset the variable. If it still shows, your OpenCode build is the reason — update OpenCode, or live with the visible block; the context is the same.
+
+**Confirm.** Run with `GENESEED_DEBUG=1`; the plugin's log says which delivery it used.
+
+## No memory is written after a session
+
+**Cause.** The learn plugin found no memory directory, or it did not load.
+
+**Fix.** Pin the store, then restart OpenCode:
+
+```bash
+export GENESEED_HARNESS=~/.config/opencode
+```
+
+(or `GENESEED_MEMORY` for an explicit directory), and confirm the `geneseed-*.js` files are in the plugins dir.
+
+**Confirm.** About a minute after the session goes quiet, stderr shows `[geneseed-learn] wrote N memory file(s): …` or a `skipped:` reason. Total silence means the plugin did not load.
+<!--/harness-->
+
+Model, read-only agent, document and MCP problems are on [their own page](troubleshoot-tools.md).

package/docs/reference/troubleshoot-install.md

@@ -0,0 +1,108 @@
+---
+group: reference
+kind: "concept"
+section: "Troubleshooting"
+order: 6
+title: "Install problems"
+description: "Node missing or too old, setup without a terminal, tools not detected, command not found."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. First stop for almost anything: `geneseed doctor` (see [Troubleshooting](troubleshooting.md)).
+
+## `Node.js not found` or `Node vX is too old`
+
+The one-step installer (`./install`, `install.cmd`, `install.command`) checks Node first and stops:
+
+> `xx  Node v20.11.0 is too old — Geneseed needs 22.3 or newer.`
+
+**Cause.** No Node on PATH, or an older one — Linux distribution packages are often behind.
+
+**Fix.** Install the current Node.js LTS from <https://nodejs.org/> (macOS: `brew install node`; Linux: nvm or NodeSource). Open a **new** terminal, then run the installer again.
+
+**Confirm.**
+
+```bash
+node --version
+```
+
+prints 22.3 or newer, and the installer's first line reads `ok  Node v…`.
+
+## `geneseed needs Node 22.3 or newer`
+
+Run without the installer — `npx geneseed`, a global npm install, or a hook — on an older Node, every Geneseed command stops with one sentence:
+
+> `geneseed needs Node 22.3 or newer; this is Node 20.18.1. Install a current Node from https://nodejs.org (or your package manager), then run the command again.`
+
+**Cause.** The `node` on PATH is older than 22.3. npm only *warns* about the engine requirement, so a global install succeeds anyway. A hook prints the same sentence and lets the tool call through rather than block it, so on Claude Code, Bob or OpenClaude the hooks are off until Node is upgraded.
+
+**Fix.** Install the current Node.js LTS (see above), open a **new** terminal, and run the command again.
+
+**Confirm.** `geneseed version` prints the version instead of the sentence.
+
+## `setup` says it needs an interactive terminal
+
+> `[setup] needs an interactive terminal. Non-interactive? e.g.:`
+> `  geneseed build --emit opencode-global --theme neutral`
+
+**Cause.** `geneseed setup` is a wizard and refuses to run when its input is not a terminal — in CI, through a pipe, or from a tool that runs commands without a TTY.
+
+**Fix.** Run it from a real terminal, or skip the wizard and build directly with the flags it would have asked for:
+
+```bash
+geneseed build --emit opencode-global --theme neutral
+```
+
+See [Install](../guides/install.md) for the emit target that matches your tool.
+
+**Confirm.** `geneseed status` lists the install.
+
+## `setup` lists a tool as missing — or present — when it isn't
+
+Setup opens with `AI coding tools on this machine:` and an `ok` or `--` per tool.
+
+**Cause.** The check only asks whether the command (`opencode`, `claude`, `bob`, `openclaude`) is on your PATH. A desktop-only install with no command shows as missing; an unrelated program with the same name shows as present.
+
+**Fix.** Nothing to fix — the line is advisory. Pick the install mode for the tool you actually use; a missing tool among several present is just a line, and you can continue without one.
+
+**Confirm.** Open the tool and check for the readiness sigil (see [The agent never shows the readiness sigil](troubleshoot-hooks.md)).
+
+## `Java 21+ (jdtls) missing`
+
+Shown in setup's summary for OpenCode installs:
+
+> `Java 21+ (jdtls) missing — install a JDK 21+ — e.g. brew install openjdk@21, SDKMAN sdk install java 21-tem, or your distro's package`
+
+**Cause.** OpenCode's Java language server needs a JDK 21 or newer, and it is the one language server OpenCode cannot download for you. See [LSP](../concepts/lsp.md).
+
+**Fix.** Install a JDK 21+ if you work in Java; ignore the line otherwise. Everything else works without it.
+
+**Confirm.**
+
+```bash
+java -version
+```
+
+reports `version "21` or higher.
+
+## `geneseed: command not found`
+
+**Cause.** The `geneseed` launcher is not on your PATH. A git clone is not put there automatically (an `npm install -g geneseed` install is).
+
+**Fix.** From the cloned folder:
+
+```bash
+./geneseed link
+```
+
+```bat
+.\geneseed.cmd link
+```
+
+On Windows, `link` writes to `%LOCALAPPDATA%\Geneseed\bin` and adds it to your user PATH — only **new** terminals see it, so close and reopen yours.
+
+**Confirm.**
+
+```bash
+geneseed version
+```
+
+works from any directory. See [Run anywhere](../guides/run-anywhere.md).

package/docs/reference/troubleshoot-tools.md

@@ -0,0 +1,56 @@
+---
+group: reference
+order: 8
+title: "Model, agent and MCP problems"
+kind: "concept"
+section: "Troubleshooting"
+description: "No model for learn, a read-only agent, ignored PDFs, an MCP server that will not connect."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. Hooks, project context and memory are on [Hook, context and memory problems](troubleshoot-hooks.md).
+
+## `could not determine a model`
+
+**Cause.** The learn step could not read which model the session used.
+
+**Fix.** Give it a fallback:
+
+```bash
+export GENESEED_MODEL=provider/model
+```
+
+**Confirm.** The next session end writes memory instead of logging the message.
+
+## A read-only agent won't run a command
+
+**Cause.** By design: read-only agents are denied the shell. The few that must run read-only commands (the reviewer, security) are allowed it in their own spec.
+
+**Fix.** Hand the task to an agent that can run commands, or run it yourself. See [Agents](../concepts/agents.md).
+
+## PDFs and Office documents are ignored
+
+**Cause.** Agents read text. Binary documents need converting first.
+
+**Fix.** Use the `ingest` skill with a converter installed (MarkItDown, Pandoc or Docling), or wire MarkItDown as an MCP server. See [Reading non-markdown docs](../guides/read-non-markdown.md).
+
+## An MCP server is listed but won't connect
+
+Work through these in order:
+
+1. **Does the command resolve?** Run the exact command in a fresh terminal: `uvx markitdown-mcp --help`, or `npx -y @modelcontextprotocol/server-filesystem --help`. "command not found" means the binary is not on the `PATH` your agent starts from. Use the `uvx` or `npx` form, which needs only uv or Node, or point at the absolute path of the binary. This is the most common cause for MarkItDown.
+2. **Filesystem sees nothing?** The allowed folder is still the placeholder, or it points at a path that does not exist.
+3. **GitLab will not connect?** Almost always a missing or under-scoped token, or a wrong `GITLAB_API_URL`. Keep the `/api/v4` suffix.
+4. **Right file?** Editing a file the host does not read fails silently.
+
+<!--harness:opencode-->
+*(OpenCode only)*
+
+OpenCode reads `opencode.jsonc` if it exists, otherwise `opencode.json`, both in the project root and in `~/.config/opencode/`. The console toggle always writes the file OpenCode actually reads.
+<!--/harness-->
+
+<!--harness:claude-->
+*(Claude Code only)*
+
+Claude Code reads `.mcp.json` in the project and the `mcpServers` block in `~/.claude.json`. `claude mcp list` shows which servers actually loaded.
+<!--/harness-->
+
+Where each host keeps the file: [MCP servers](../guides/mcp.md).

package/docs/reference/troubleshoot-update.md

@@ -0,0 +1,23 @@
+---
+group: reference
+kind: "concept"
+section: "Troubleshooting"
+order: 9
+title: "Update problems"
+description: "Every refusal geneseed upgrade can print, and its fix."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. First stop for almost anything: `geneseed doctor` (see [Troubleshooting](troubleshooting.md)).
+
+## `geneseed upgrade` refuses to run
+
+The upgrade is a `git pull`, so it first checks the folder. Each refusal says what to do:
+
+| Message | Fix |
+| --- | --- |
+| `git is not installed or not on PATH — install git to enable updates.` | Install git, open a new terminal, retry. |
+| ``This Geneseed install isn't a git checkout — update it with `npm install -g geneseed@latest`, or re-clone it with git.`` | Use the npm command for an npm install; otherwise re-clone (`git clone https://github.com/Arylmera/Geneseed.git`). |
+| `You have local changes in the Geneseed folder. Commit or stash them, then update.` | `git stash` in the Geneseed folder, upgrade, then `git stash pop`. |
+| ``HEAD is detached (a tag/commit is checked out). Run `git checkout <branch>` to re-enable updates.`` | `git checkout main`. |
+| ``Your branch has no upstream — set one with `git branch --set-upstream-to`.`` | `git branch --set-upstream-to=origin/main`. |
+
+**Confirm.** `geneseed upgrade` completes and `geneseed version` shows the new version. See [Upgrade](../guides/upgrade.md).

package/docs/reference/troubleshoot-web.md

@@ -0,0 +1,66 @@
+---
+group: reference
+kind: "concept"
+section: "Troubleshooting"
+order: 11
+title: "Web console problems"
+description: "A missing web/dist, a console that looks broken after an upgrade, no deployed harness."
+---
+Each entry gives the likely cause, the fix, and how to confirm it worked. First stop for almost anything: `geneseed doctor` (see [Troubleshooting](troubleshooting.md)).
+
+## `web/dist is missing`
+
+> `[web] web/dist is missing. Build the UI first:`
+> `        cd web && npm install && npm run build`
+
+**Cause.** The built console ships in the repo, so this only happens on a partial checkout. On an interactive terminal `geneseed web` offers to build it for you.
+
+**Fix.** Build it from the Geneseed folder:
+
+```bash
+cd web && npm install && npm run build
+```
+
+If it instead says `web/ sources are missing`, run `geneseed upgrade` (twice on an old install).
+
+**Confirm.** `geneseed web` opens the console.
+
+## The console looks broken after an upgrade
+
+Pages fail to load, or the console shows a banner: *This console is running code from before your last upgrade.* `geneseed web status` adds:
+
+> `[web] running OLD code (started before the last upgrade) — geneseed web restart`
+
+**Cause.** The console server serves the page it started with. An `npm install -g geneseed@latest` or a `git pull` replaces `web/dist/`, and the old page asks for files that no longer exist. `geneseed upgrade` and `geneseed rebuild-all` restart a stale console themselves; other upgrade paths do not.
+
+**Fix.** Click **Restart** on the banner, or:
+
+```bash
+geneseed web restart
+```
+
+A browser refresh is not enough — the server, not the page, is out of date.
+
+**Confirm.** `geneseed web status` prints no `OLD code` line and the banner is gone.
+
+## The console says `no deployed harness`
+
+> `[web] no deployed harness at <dir>.`
+
+**Cause.** Nothing is installed where the console looks. It still serves, read-only, with most actions disabled.
+
+**Fix.**
+
+```bash
+geneseed setup
+```
+
+**Confirm.** Restart the console — `geneseed web restart` — and the warning is gone.
+
+## Skills or agents not tracked in git
+
+**Cause.** A parent `.gitignore` blanket-ignores the bundle directory.
+
+**Fix.** Remove the bare `Harness/` line from the parent `.gitignore`; the bundle's own `.gitignore` already scopes what to skip.
+
+**Confirm.** `git status` lists the bundle's files.