Skip to content

docs: the README describes the tool it has become - #76

Merged
khaneight merged 1 commit into
mainfrom
feat/clone-docs
Aug 27, 2026
Merged

docs: the README describes the tool it has become#76
khaneight merged 1 commit into
mainfrom
feat/clone-docs

Conversation

@khaneight

Copy link
Copy Markdown
Owner

Stacked on #75. Last PR in the stack.

The README still opened "CLI tooling for a personal knowledge base that an LLM
builds and maintains"
— true nine PRs ago.

What changed

  • The tagline is what the thing does: clone yourself from your corpus of work.
  • A "What keeps it honest" section, which is the part I'd most want a reader
    to hit first. The six safeguards, stated as what they are — lint errors and
    refusals, not instructions an agent can talk itself out of.
  • The persona contract, with the review commands beside it, and the fact
    that an agent writes proposed and can never write affirmed.
  • The seven-rung ladder, with why learn sits below compile and extend
    near the bottom, and why approval is deliberately not a rung.
  • extrapolated in the article format, and why raw/ can never hold it.
  • One publishing section covering both artifacts — the wiki for reading, the
    showcase for watching.

Trimmed elsewhere, so a considerably larger product costs 3 KB more rather than
5.

The design doc records where it was wrong

More useful than the ticks. Two calls in #67 did not survive contact:

learn moved below compile. "A corpus read after the fact shaped
nothing"
was overstated — compiling a document is the close reading that
makes mining it cheap, and what a thin profile degrades is generated work, four
rungs further down.

review was never renamed to revise. The rename was proposed to free the
word for the human gate. The gate turned out to need a command, not a rung,
and sentinel review reads fine beside a review rung meaning stalled drafts —
the two never appear in the same sentence. Renaming would have broken every
--action review in the wild to solve a collision that did not exist.

That is also why SCHEMA_VERSION stays at 1: everything this stack added to
a payload is an optional field.

531 tests, clippy and fmt clean.

🤖 Generated with Claude Code

It still opened "CLI tooling for a personal knowledge base that an LLM
builds and maintains", which was true nine PRs ago. The tagline is now
what the thing does: clone yourself from your corpus of work.

Adds the section that matters most for anyone reading this repository
cold — the six safeguards, stated as what they are: lint errors and
refusals rather than instructions an agent can talk itself out of.
Alongside, the persona contract with the review commands beside it, the
seven-rung ladder with the reasoning for where `learn` and `extend` sit,
`extrapolated` in the article format, and one publishing section covering
both artifacts.

Trimmed back where the old text had gone slack, so a considerably larger
product costs 3 KB more rather than 5.

docs/clone.md marks what shipped and, more usefully, records the two
places the design was wrong.

`learn` moved below `compile`: "a corpus read after the fact shaped
nothing" was overstated, since compiling a document *is* the close
reading that makes mining it cheap.

And `review` was never renamed to `revise`. The rename was proposed to
free the word for the human gate, and the gate turned out to need a
*command* rather than a rung — `sentinel review` reads correctly beside a
`review` rung meaning stalled drafts, because the two never appear in the
same sentence. Renaming would have broken every `--action review` in the
wild to solve a collision that did not exist, which is also why
`SCHEMA_VERSION` stays at 1: everything this stack added to a payload is
an optional field.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@khaneight
khaneight changed the base branch from feat/ui to main August 27, 2026 02:26
@khaneight
khaneight merged commit ea3407f into main Aug 27, 2026
6 checks passed
@khaneight
khaneight deleted the feat/clone-docs branch August 27, 2026 02:33
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant