docs: correct what the README says the commands print - #11
Open
otsobide wants to merge 1 commit into
Open
Conversation
Audited by running every example against the binaries rather than reading them, which turned up four things that were wrong and two that had gone stale: - `mind validate` was shown printing `skill/commit-style`. It prints `skill:commit-style`; the qualifier has been a colon since the kinds landed, for the reason the same document explains four paragraphs earlier. - The install screen was hand-drawn ASCII that did not line up with what ratatui renders. Replaced with the real frame. - `flayer gather list` was shown with three spaces between columns; `table` pads to the widest cell and adds two. - The three listing examples described three different setups while claiming to be one workspace seen from two levels. - Gathering still said installing from the shelf was "the next piece of work", in a document that documents it two sections down. - A workspace "will know" where to put a skill. It knows. `make dev/link` no longer claims to put anything on your PATH: its default is `~/.cargo/bin`, which is on it if rustup put it there and is not if Rust came from a system package. The `cargo-watch` note gains the failure that actually happens — installed, on no PATH, and reported as missing. `docs/architecture.md` records the asymmetry the audit surfaced: the shelf keeps the folder name a source used, and installing files the copy under the name the skill declares. Upstream a mismatch is something `validate` should report; inside a project it is a skill that lists fine and never loads. The test that claimed to cover that asymmetry did not — its fixture spelled both names the same way, so it asserted nothing the ordinary case did not already. It now gathers from a folder that disagrees with the front matter. Claude-Session: https://claude.ai/code/session_01V2osQx2Q4LKUBXTLJCiMDR
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.
Audited the docs by running every example against the binaries rather than reading them. Six things were wrong or stale.
Wrong
mind validateskill/commit-style: okskill:commit-style: okflayer installflayer gather listtablepads to the widest cellThe
validateone is the interesting one: the qualifier has been a colon since the kinds landed, and the same README explains why a slash would be wrong four paragraphs above the example that used a slash.Stale
flayer installreads.Honest about the PATH
make dev/linkno longer claims to put anything on your PATH. Its default is~/.cargo/bin, which is on it if rustup put it there and is not if Rust came from a system package. Thecargo-watchnote gains the failure that actually happens rather than the one that is easy to write: installed, on no PATH, and reported bymake dev/watchas missing.One finding that was not a docs bug
docs/architecture.mdnow records an asymmetry the audit surfaced: gathering keeps the folder name the source used, installing files the copy under the name the skill declares. That is deliberate — upstream a mismatch is somethingvalidateshould report, inside a project it is a skill that lists fine and never loads — but it was nowhere written down.Worse, the test that claimed to cover it did not.
the_folder_is_named_after_the_skill_rather_than_after_its_shelf_folderbuilt its fixture with both names spelled the same way, so it asserted nothing the ordinary case did not already. It now gathers fromskills/a-different-folder/declaringdeploy, and asserts both halves: the shelf keepsa-different-folder, the project getsdeploy.Verified
make fmt/check,make lint(clean),make test— 198 passing, 0 failing. Every command example in the README was reproduced against the real binaries; the install frame is a paste of whatTestBackendrenders. The three internal anchors resolve.https://claude.ai/code/session_01V2osQx2Q4LKUBXTLJCiMDR