Skip to content

M9: rewrite the README and the docs for v0.3.0 - #28

Merged
tamnd merged 1 commit into
mainfrom
docs/v0.3.0
Aug 15, 2026
Merged

tamnd merged 1 commit into
mainfrom
docs/v0.3.0

Conversation

@tamnd

@tamnd tamnd commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Closes the first two boxes of #17.

The README and everything under docs/ were thoroughly v0.2.0. They documented --cookies, --workers, a singular quote command, crawl --parse, search --html and a five row exit code table that has not been right since M4, and they said nothing at all about works, editions, the graph, the crawler or the MCP server.

Everything here is one sentence per line with no newline inside a sentence, so a one word change is a one line diff rather than a reflow.

Renames

The guides were named after the commands that happened to exist in v0.1.0. They are now named after the job:

was is
books-and-authors.md books-and-works.md
search-and-discovery.md store-and-graph.md
shelves-and-quotes.md robots-and-limits.md
bulk-crawling.md crawling.md
mcp.md, new

What is new in the content

  • The book/work/edition distinction, stated once at the top of the README and again in the introduction, because it is the thing the release is built on.
  • The extraction ladder, with the honest bit: the book page is Next.js and the six Rails surfaces have nothing but og: tags, so a selector there is not a shortcut.
  • robots.txt as its own guide: what is disallowed, what you lose, the two real routes around, and the four deliberate properties of --no-robots.
  • The MCP guide, including why the server has no --no-robots and why that is enforced by a test rather than by a paragraph.
  • The graph: the gr: URI, the twelve predicates with their properties, and the SQL you can actually run.
  • The eight v0.3.0 exit codes, in the README, the two output pages, the CLI reference and troubleshooting, all matching cli/root.go.
  • release-notes/v0-3-0.md, with a breaking-changes section naming every flag and command that moved.

v0-1-0.md keeps its facts and gains a note at the top saying they are v0.1.0's, so somebody landing on it from a search does not follow it into --cookies.

One code change

cli/root.go's Long was stale in the same way as the docs. It named search, shelves and reviews as the headline and said nothing about the line robots.txt draws, so it says that instead.

Checked

Every command, flag and default in the reference was read off goodread <command> --help from a build of this branch rather than remembered. The book table output in the README and the quick start is a real run. The --template examples are real too, which is how the note about --fields naming JSON keys and --template walking the Go struct got written: {{.title}} does not work and it is not obvious why.

gofmt -l . && go vet ./... && go test ./... is clean.

Both were thoroughly v0.2.0. They documented --cookies, --workers, a
singular quote command, crawl --parse, search --html and a five row exit
code table that has not been right since M4, and they said nothing about
works, editions, the graph, the crawler or the MCP server.

Everything is one sentence per line, with no newline inside a sentence,
so a one word change is a one line diff.

The guides are renamed to the job they cover rather than the commands
that happened to exist in v0.1.0:

  books-and-authors    -> books-and-works
  search-and-discovery -> store-and-graph
  shelves-and-quotes   -> robots-and-limits
  bulk-crawling        -> crawling
  (new)                   mcp

v0-1-0.md keeps its facts and gains a note saying they are v0.1.0's, so
somebody landing on it from a search does not follow it into --cookies.

The root command's Long text was stale in the same way, naming search,
shelves and reviews as the headline and saying nothing about the line
robots.txt draws, so it says that now instead.
@tamnd
tamnd merged commit af76f33 into main Aug 15, 2026
4 of 7 checks passed
@tamnd
tamnd deleted the docs/v0.3.0 branch August 15, 2026 23:14
@tamnd tamnd mentioned this pull request Aug 15, 2026
5 of 7 tasks
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