docs: rewrite the README for people using Pilot - #62
Merged
ragilhadi merged 1 commit intoAug 14, 2026
Merged
Conversation
The README's skills section ended by linking `./docs/user-guide.md`, which 404s for every reader: `/docs/` is gitignored as internal planning material, so the guide exists on the author's machine and nowhere else. `packages/lsp/README.md` had the same problem pointing at `docs/decisions/0009-...`, which ships to npm. Both links are gone and the content that mattered is inlined: the skill manifest fields and what each permission field can and cannot do, the `.pilot/skills` and `.pilot/prompts` layout, and the `/skill` and `/prompt` flows. The README is now written for someone who wants to use Pilot rather than build it. Install, quick start, a command table, what a chat session gives you, then configuration one feature at a time. Building from source, the test commands, and the release process moved to CONTRIBUTING.md rather than being deleted. A few corrections while rewriting: `pilot doctor` does not check ripgrep or model reachability, and `pilot instructions` takes an optional path. `scripts/check-links.mjs` runs in `pnpm check` and fails on a relative Markdown link that does not resolve to a published file. It asks git what it tracks rather than the filesystem what exists, because a file being present locally is exactly what hid this bug — verified against the original broken link. Closes #56 Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #56. Stacked on #61 — review that one first; this diff is against its branch.
The broken link
/docs/is gitignored ("Internal planning/spec docs — not part of the published project"), sodocs/user-guide.mdexists on the author's machine and nowhere a reader can reach. That is why the link resolved for whoever wrote it and 404s for everyone else.The same bug turned up a second time:
packages/lsp/README.mdlinked../../docs/decisions/0009-language-server-diagnostics.md, which ships to npm with that package. Both links are gone, and the details worth keeping are inlined — the skill manifest fields and what each permission field can and cannot do, the.pilot/skills/.pilot/promptslayout, and the/skill NAMEand/prompt NAME argumentsflows. The lsp README already explains its own reasoning under "Design notes".The README
Rewritten for someone who wants to use Pilot: install → quick start → a command table → what a chat session gives you (
@mentions, slash commands, approvals, scrolling, display modes) → configuration, one feature at a time.Building from source, the test commands, and the release process moved to a new
CONTRIBUTING.mdrather than being deleted — the release process in particular (lockstep versions, thepilot-vX.Y.Ztag contract, whatrelease.ymlverifies) exists nowhere else. Say the word if you'd rather it were dropped entirely.Three factual corrections found while rewriting:
pilot doctordoes not check ripgrep or model reachability — it checks configuration, Node, Git, shell, provider credentials, the database, the workspace, and language servers.pilot instructionstakes an optional path and defaults to the workspace root.pilot chat --session <id>, which the README never mentioned.Keeping it from happening again
scripts/check-links.mjsruns as part ofpnpm check(so, in CI) and fails on any relative Markdown link that doesn't resolve to a file a reader will receive. It asks git what it tracks rather than the filesystem what exists — a file being present locally is exactly what hid this bug — and accepts a target that is present and not ignored, so a link and its target can land in the same commit.I verified it against the real thing: re-adding the original
./docs/user-guide.mdlink makes it fail, and the tree passes without it.pnpm checkclean, 953 tests passing.🤖 Generated with Claude Code