Files

T

araharah-executor 91ad0c9d93 docs: generate + verify project documentation — canonical docs, per-package READMEs, verified fix pass

- New: docs/ARCHITECTURE.md, docs/GETTING-STARTED.md, docs/DEVELOPMENT.md,
  docs/TESTING.md, docs/CONFIGURATION.md (colored mermaid diagrams, quoted labels)
- Regenerated README.md (arah² / arah2bot naming, canonical clone URL)
- New per-package READMEs: theme/, bot/, web/
- Verified 13 docs against the live codebase (2 fix iterations + 2 residual
  corrections); corrected 56 stale claims across AGENTS/DESIGN/IDEAS/GSD_FIX

2026-10-23 20:56:40 +08:00

3.6 KiB

Raw Blame History

GSD_FIX.md — Notes on repairing the GSD-OpenCode install

Date: 2026-10-21 Package: gsd-opencode v1.38.5 (installed via npx gsd-opencode → global scope, ~/.config/opencode/)

Symptoms

Inside OpenCode, none of the /gsd-* commands were available, and gsd-sdk appeared broken/missing.

Root causes (two separate issues)

1. Slash commands were registered under the wrong names — `/gsd/gsd-`, not `/gsd-`

The v1.38.5 distribution manager installs the 88 GSD command files into a nested subdirectory:

~/.config/opencode/commands/gsd/gsd-plan-phase.md
~/.config/opencode/commands/gsd/gsd-execute-phase.md
...

This layout predates OpenCode V2's command discovery rules. In V2, nested paths become namespaced slash commands (documented at https://opencode.ai/v2/docs/commands/):

commands/gsd/gsd-execute-phase.md → /gsd/gsd-execute-phase (what OpenCode registered)
instead of /gsd-execute-phase (what the GSD README documents and users expect)

Verified against the running service via opencode api get /api/command: every command was registered as gsd/gsd-*, so typing /gsd-* found nothing — they "seemed" missing even though the files were all present (the installer's gsd-opencode check reported 755/843 files verified — 755 passing out of the 843-file manifest — which is exactly why the health check did not catch this).

Fix: flattened the command files:

mv ~/.config/opencode/commands/gsd/*.md ~/.config/opencode/commands/
rmdir ~/.config/opencode/commands/gsd

OpenCode hot-reloads command files, so the /gsd-* names registered immediately (confirmed via the /api/command endpoint — 88 flat gsd-* commands, zero gsd/gsd-* entries).

2. `gsd-sdk` was a dangling symlink into the ephemeral npx cache

Running the installer via npx gsd-opencode leaves the "global" binaries pointing into ~/.npm/_npx/*.*/node_modules/.bin/, which npx may garbage-collect at any time:

~/.local/bin/gsd-sdk -> ~/.npm/_npx/2ada84fac427087c/node_modules/.bin/gsd-sdk   # fragile

Every GSD command/agent shells out to gsd-sdk query …; when the npx cache is pruned, all of those calls die silently.

Fix: installed a pinned global copy and re-pointed the shim:

npm install -g gsd-opencode
ln -sf ~/.nvm/versions/node/v24.18.0/bin/gsd-sdk ~/.local/bin/gsd-sdk

Verified with gsd-sdk query state.load (succeeds) and gsd-sdk --version.

Side notes

At the time of this repair, which gsd-opencode also resolved to a Windows npm shim (under /mnt/c/Users/.../npm/) on the WSL PATH, from a previous install on the Windows side. Harmless but confusing; the Linux binaries under ~/.nvm/.../bin now take precedence for gsd-sdk. That shim has since been removed and is no longer on the current PATH.
The installer's own health checker (gsd-opencode check) still expects the old nested commands/gsd/ layout and will report the 88 flattened files as "missing" — this is a false positive caused by the checker not knowing about OpenCode V2's namespacing rules. The files are fine where OpenCode can find them.
After changing GSD model profiles, note the package requires a full OpenCode restart (agent→model mappings come from opencode.jsonc and are read at startup).

Current state

Item	Status
`/gsd-*` slash commands	✅ 88 registered flat at `~/.config/opencode/commands/`
`gsd-sdk` CLI	✅ stable symlink to global npm install (`~/.nvm/.../bin/gsd-sdk`)
Agents / skills / rules / sdk files	✅ untouched, integrity verified
`gsd-opencode check`	⚠️ reports false "missing files" (stale checker, see above)

3.6 KiB Raw Blame History