block / block/trailblaze

Homebrew CLI ships no docs or CLI skill — agents/end-users driving the brew binary can't self-serve trailmap authoring

Open
#191 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
Kotlin
Stars
310
Forks
28
Avg merge
7h 45m
Merged PRs (30d)
8

Description

## 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//
├── 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 ` 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.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing docs/your-first-trailmap.md, docs/trailmaps.md, the CLI --help surface, and the daemon's MCP interface. Determine which authoring guidance and CLI skill should be locally discoverable, then verify that a Homebrew-installed binary exposes the selected docs or skill and that the relevant online or local paths are clear.

Written by the indexing model from the issue text.

Assessment

Tech stack
kotlin
Domain
cli, documentation
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.