Halve the README - #27
Merged
Merged
Conversation
578 lines and 4,141 words, of which I added 121 this session — for a tool whose pitch is that you can read the whole thing in one sitting. Now 300 lines and 2,105 words. Most of the weight was duplication rather than detail. The CLI command list appeared twice, once under "Use it" and again under "For coding agents". The token economics of `--json` were argued in both places. `knoten update`'s `--field` / `--result` semantics were explained at length in the README and again in SKILL.md, which is the file an agent actually reads. Five sections — attachments, frontier, query-vs-index, gates, retraction — each opened with its own preamble to make one point, and now share one "What it answers" section that makes all four. Nothing was deleted that is not either in SPEC.md, in SKILL.md, or a repetition of a sentence already on the page. The node example, the rules examples and the vocabulary block stay, because `test_docs` executes them. One improvement while condensing: the `require_edge_target` example was written as a bare indented fragment, so `test_docs`'s extractor never matched it and it was the one yaml block in the README nothing validated. It is a full `rules:` block now, and runs.
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.
578 lines / 4,141 words → 300 lines / 2,105 words, for a tool whose pitch is that you
can read the whole thing in one sitting. I added 121 of those lines this session.
Most of the weight was duplication, not detail
agents".
--jsonwere argued in both places.knoten update's--field/--resultsemantics were explained at length here andagain in
SKILL.md, which is the file an agent actually reads.opened with its own preamble to make one point. They are now one "What it answers"
section that makes all four.
Nothing was cut that is not either in
SPEC.md, inSKILL.md, or a repetition of asentence already on the page. The node example, the rules examples and the vocabulary block
stay, because
tests/test_docs.pyexecutes them against the real example graph.One improvement while condensing
The
require_edge_targetexample was written as a bare indented fragment, so the docextractor never matched it — it was the one yaml block in the README that nothing
validated. It is a full
rules:block now, and runs. Doc-block coverage went from 7executed examples to 8.
Verified
266 passed, 6 skipped, withtest_docsstill extracting one node block and three rulesblocks from README.