docs: align Fish completion with manual load only

Clarify that mage install and go install do not write fish/completions,
document removing stale ask.fish from older installs, and cross-link
README, buildandinstall, and usage.

Made-with: Cursor

4 files changed, 13 insertions, 8 deletions

diff --git a/README.md b/README.md
index ad80817..e71e93b 100644
--- a/README.md
+++ b/README.md
@@ -22,7 +22,7 @@ It has got improved capabilities for Go code understanding (for example, create
   - `ask info` hides raw UUIDs unless `HEXAI_DEBUG` is set
   - Machine-friendly output with suppressed decorative text
   - Subcommands: `ask add`, `ask list`, `ask info`, `ask annotate`, `ask start`, `ask stop`, `ask done`, `ask priority`, `ask tag`, `ask dep`, `ask urgency`, `ask modify`, `ask denotate`, `ask delete`, `ask fish`, `ask help`
-  - Fish completion generator: `ask fish`
+  - Fish shell completions: run `ask fish | source` in a session, or use a `conf.d` snippet (see [Fish shell completion](docs/fish-completion.md)); installs do not write files under `fish/completions/`
 * Parallel completions and CLI responses from multiple providers/models for side-by-side comparison
 * **MCP server for prompt/runbook management** (`hexai-mcp-server`) - **⚠️ DEPRECATED/EXPERIMENTAL**
   - Create, update, delete, and retrieve prompts via MCP protocol
diff --git a/docs/buildandinstall.md b/docs/buildandinstall.md
index 74562f0..8e7a4f8 100644
--- a/docs/buildandinstall.md
+++ b/docs/buildandinstall.md
@@ -10,8 +10,8 @@ Hexai uses Mage for developer tasks. Install Mage, then run targets like build,
 - Full cross-package coverage and HTML report: `mage coverage` (writes `docs/coverage.html`)
 - In restricted sandboxes/CI (no sockets), skip network-based tests:
   - `HEXAI_TEST_SKIP_NET=1 go test ./... -cover`
-- Install binaries to `GOPATH/bin`: `mage install`
-- Load Fish completions in the current shell after install: `~/go/bin/ask fish | source` (or add a `conf.d` snippet; see `docs/fish-completion.md`)
+- Install binaries to `GOPATH/bin`: `mage install` (does not install Fish completion files; configure Fish yourself—see below)
+- Fish (`ask`): after install, run `ask fish | source` or set up `conf.d` as in [Fish shell completion](fish-completion.md)
 
 Note: `mage lint` uses `golangci-lint`. Install via `mage devinstall` if needed.
 
@@ -19,7 +19,7 @@ Note: `mage lint` uses `golangci-lint`. Install via `mage devinstall` if needed.
 
 Either use the Mage method as mentioned above, or install directly with:
 
-- Task CLI (`ask`, agent-scoped Taskwarrior wrapper): `go install codeberg.org/snonux/hexai/cmd/ask@latest`
+- Task CLI (`ask`, agent-scoped Taskwarrior wrapper): `go install codeberg.org/snonux/hexai/cmd/ask@latest` (Fish completions: same as above—[Fish shell completion](fish-completion.md))
 - CLI: `go install codeberg.org/snonux/hexai/cmd/hexai@latest`
 - LSP: `go install codeberg.org/snonux/hexai/cmd/hexai-lsp-server@latest`
 - Action runner: `go install codeberg.org/snonux/hexai/cmd/hexai-tmux-action@latest`
diff --git a/docs/fish-completion.md b/docs/fish-completion.md
index f1e1f21..388ca98 100644
--- a/docs/fish-completion.md
+++ b/docs/fish-completion.md
@@ -2,6 +2,11 @@
 
 The `ask` task-management CLI embeds its Fish completion script in the binary and prints it with `ask fish`.
 
+`mage install` and `go install …/cmd/ask` only place the `ask` binary on your `PATH` (under `GOPATH/bin` or `~/go/bin`). They do **not** install anything under `fish/completions/`. You load completions yourself as below.
+
+If you used an older Hexai release whose `mage install` wrote `ask.fish` into your Fish completions directory, remove that file so Fish does not keep sourcing a stale script:  
+`~/.config/fish/completions/ask.fish` or `$XDG_CONFIG_HOME/fish/completions/ask.fish`.
+
 It completes the top-level `ask` subcommands and the nested `ask dep` operations.
 It also suggests the global task prefixes `na`, `no-agent`, and `proj:`.
 It also completes task selectors for UUID-taking commands by reading pending tasks through `ask complete-aliases`, which uses the local alias cache for stable short IDs.
@@ -16,13 +21,13 @@ Load it into the current Fish session:
 ask fish | source
 ```
 
-If you installed with `mage install` and `~/go/bin` is not on your `PATH` yet, use:
+If `ask` is not on your `PATH` yet, call it by full path (for example `~/go/bin/ask` when `GOPATH` is unset):
 
 ```sh
 ~/go/bin/ask fish | source
 ```
 
-To enable it automatically for new Fish sessions, add this to your Fish config or a file in `~/.config/fish/conf.d/`:
+To enable it automatically for new Fish sessions, add this to your Fish config or a file in `$XDG_CONFIG_HOME/fish/conf.d/` (often `~/.config/fish/conf.d/`):
 
 ```fish
 set -l ask_bin ~/go/bin/ask
@@ -32,4 +37,4 @@ if test -x $ask_bin
 end
 ```
 
-No completion file under `~/.config/fish/completions/` is required; use `ask fish | source` or the `conf.d` snippet above for new sessions.
+Do not rely on a static file under `fish/completions/`; either run `ask fish | source` when you want completions in the current session, or keep the `conf.d` snippet so each new session sources the script from the installed binary (stays in sync when you upgrade `ask`).
diff --git a/docs/usage.md b/docs/usage.md
index ce449f4..0429176 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -125,7 +125,7 @@ cat SOMEFILE.txt | hexai --tps-simulation 20
 
 ## Task management
 
-`ask` is a task management CLI for the current git project. The binary was briefly named `do`; use `ask` everywhere (commands, scripts, shell completion).
+`ask` is a task management CLI for the current git project. The binary was briefly named `do`; use `ask` everywhere (commands, scripts, shell completion). For Fish, load completions with `ask fish | source` or the setup in [Fish shell completion](fish-completion.md).
 
 By default it auto-scopes to `project:<repo> +agent` so operations are confined to agent-managed project tasks.