Summary
The Homebrew install ships only the binary — no documentation and no CLI "skill"/usage guide. An end user who runs brew install has no local access to docs/your-first-trailmap.md, docs/trailmaps.md, or the repo's CLI skill. The Cellar directory contains only bin + libexec:
/opt/homebrew/Cellar/trailblaze/<version>/
├── INSTALL_RECEIPT.json
├── bin
└── libexec
So the guidance that would let someone author a trailmap or learn the CLI's conventions lives only in the GitHub repo, out of reach of the CLI it documents. There's no trailblaze docs, no trailblaze skill, and nothing in --help that surfaces this material locally.
Why this matters (agent-as-consumer angle)
Trailblaze is explicitly designed for an AI agent to drive the CLI as a first-class consumer. But an agent operating the brew-installed CLI has no way to discover how to author a target/trailmap or use the CLI's conventions — the docs and the skill aren't on the machine and aren't reachable through the CLI or the daemon. The agent has to already "know" to go read files on GitHub. First-run is a dead-end for self-service, for humans and agents alike.
This is separate from #190 (which is about the Trail Runner UI's empty-state). This one is about the CLI/agent surface having no access to the docs or skill at all.
Concrete suggestions
- Bundle a condensed authoring quickstart + the CLI skill into the CLI, surfaced via commands:
trailblaze docs (or trailblaze help authoring) — print/open the trailmap-authoring quickstart from a copy shipped with the binary.trailblaze skill — emit the agent-facing CLI skill/usage guide so an agent can self-load it into its context.
- Expose docs + skill as MCP resources on the daemon, so an agent connected over MCP can fetch "how do I author a target?" / the CLI skill on demand (fits the agent-first design).
- Ship the key docs with the Homebrew formula (e.g. into
share/doc/trailblaze/ or under libexec), and have trailblaze --help and the daemon first-run output point at both the local path and the online docs URL.
- Add a
trailblaze init / trailblaze new target <appId> scaffold that writes the minimal workspace + trailmap, so neither an agent nor a human needs external docs just to get a first target running.
- At an absolute minimum: make
trailblaze --help (and the Trail Runner empty state) link to the online docs and mention the skill.
Environment
- Trailblaze 2026.07.02 (Homebrew). Cellar contains only
bin + libexec (no docs). Verified an agent driving the brew CLI has no local docs/skill to consult.
Summary
The Homebrew install ships only the binary — no documentation and no CLI "skill"/usage guide. An end user who runs
brew installhas no local access todocs/your-first-trailmap.md,docs/trailmaps.md, or the repo's CLI skill. The Cellar directory contains onlybin+libexec:So the guidance that would let someone author a trailmap or learn the CLI's conventions lives only in the GitHub repo, out of reach of the CLI it documents. There's no
trailblaze docs, notrailblaze skill, and nothing in--helpthat surfaces this material locally.Why this matters (agent-as-consumer angle)
Trailblaze is explicitly designed for an AI agent to drive the CLI as a first-class consumer. But an agent operating the brew-installed CLI has no way to discover how to author a target/trailmap or use the CLI's conventions — the docs and the skill aren't on the machine and aren't reachable through the CLI or the daemon. The agent has to already "know" to go read files on GitHub. First-run is a dead-end for self-service, for humans and agents alike.
This is separate from #190 (which is about the Trail Runner UI's empty-state). This one is about the CLI/agent surface having no access to the docs or skill at all.
Concrete suggestions
trailblaze docs(ortrailblaze help authoring) — print/open the trailmap-authoring quickstart from a copy shipped with the binary.trailblaze skill— emit the agent-facing CLI skill/usage guide so an agent can self-load it into its context.share/doc/trailblaze/or underlibexec), and havetrailblaze --helpand the daemon first-run output point at both the local path and the online docs URL.trailblaze init/trailblaze new target <appId>scaffold that writes the minimal workspace + trailmap, so neither an agent nor a human needs external docs just to get a first target running.trailblaze --help(and the Trail Runner empty state) link to the online docs and mention the skill.Environment
bin+libexec(no docs). Verified an agent driving the brew CLI has no local docs/skill to consult.