dazuma
Carried over from the open questions in `docs/dev/DESIGN.md`, which has been dissolved. Raised by the 2026-07-27 skill-scope discussion. `agentdocs gems` builds from installed gem specifications only — `GemBuilder.default_spec_dirs` globs the global specifications directory plus the default-gems directory — so a git- or path-sourced dependency has no bundle path to compute and no supported way to get one. What is open is not the tool ergonomics but the **location convention**, which is a consumption contract. `agentdocs gems` forces its output location precisely so an agent looking for a gem's docs has one path to compute rather than a convention to discover, and a git dependency has no `<name>-<version>` that identifies it. Candidate directions if the convention is extended: - a git SHA or ref in the version position - a digest of the source path - a separate root alongside `gems/` The alternative is staying releases-only, and letting non-release dependencies fall back to a project-local `agentdocs build` tree. **Interacts with staleness.** A git checkout or path source is *mutable* input — `git pull`, or a checkout being actively edited — so any bundle for one lands on the staleness side rather than the immutable-release side, and would need whatever freshness signal that settles on. The skill-side half — a fallback rule for an agent that hits this case — is a separate concern from the path convention itself.