Phase 1 — the skeleton
Feature. Records in D1, documents in R2, and the publish / get / update / delete / list surface on top. Links carried an unlisted token from the first commit — the private default was never retrofitted.
POST /sites → { id, url, unlisted_token }Phase 2 — access control
Feature. Passwords, work-email gates, expiry with a purge that really deletes,
burn-after-read, and a sensitive-data scan that blocks a publish rather than warning after it.
Strict CSP and noai headers on every viewer response landed here too.
Phase 3 — end-to-end encryption
Feature. Encrypted publishing where the key lives in the URL fragment. Browsers never send a fragment, so only ciphertext reaches storage.
Phase 4 — the MCP server
Feature. Twelve tools over Streamable HTTP, API keys, and a full OAuth 2.1 authorization-code flow with PKCE and dynamic client registration.
claude mcp add --transport http opentree https://read.botook.ai/mcp \
--header "Authorization: Bearer otr_live_YOUR_KEY"Phase 5 — interaction
Feature. The on-page toolbar: comments anchored to elements, reactions, private notes.
Plus the author-side reads — list_feedback, resolve_feedback — and an
account-wide activity feed.
Phase 6 — engagement and the dashboard
Feature. Dwell time, scroll depth, read-to-end and a ten-segment attention map; the daily digest email; custom domains with real DNS verification; and the web dashboard.
Live on real infrastructure
Improvement. Moved off the local simulator onto D1, R2 and a custom domain, with a production smoke test that runs against the deployed origin rather than a local one.
Behavioural parity, round one
Improvement. Viewer path at /p/<token>/, titles extracted from the
document itself, share cards with preview images, and every timestamp switched to unix seconds to
match the documented contract.
Non-MCP entry points
Feature. PATCH /sites/:id for settings-only changes,
GET /raw/:token for plain text an agent can re-read, zip uploads as multi-file sites,
and the agent discovery documents.
curl https://read.botook.ai/raw/UNLISTED_TOKEN
curl -s https://read.botook.ai/.well-known/ai-catalog.json | jq .Coverage as a gate
Improvement. A script that enumerates the surface and a ledger where every entry must be either implemented-with-a-test or deliberately-skipped-with-a-reason. Unclassified entries fail the build, which is what stops a gap quietly becoming a habit.
Semantic assertions
Improvement. Tests moved from does the endpoint answer to did it do what it promised. That caught a real bug: revoking an OAuth grant blocked the access token but not the refresh token, so a revoked client could trade its way back in. Fixed, with a test.
Formats
Feature. Markdown rendered at publish time rather than at read time, SVG hosted
byte-for-byte, bare-body and multipart uploads wired into the same path as JSON. The bug that
prompted it: markdown was accepted with a 201 and then served as raw text with visible
hashes and asterisks.
curl -X POST https://read.botook.ai/sites -H "content-type: text/markdown" \
-H "Authorization: Bearer otr_live_KEY" --data-binary @NOTES.mdPreview images
Feature. Real rendered screenshots for share cards, plus HSTS on every response.
The whole front of the site
Feature. Every content page a visitor could want, server-rendered from one layout: integration guides per client, a page for each capability, the use cases, the comparisons, and this changelog. One navigation, one footer, one stylesheet.
How the phases were gated
Each phase had a script that had to pass before the phase counted. The rule that mattered
most: a 2xx is not evidence. Every assertion that something was accepted is followed by
one that checks the artifact — open the page, read the rendered output, confirm the conversion
happened.
bash qa/upto.sh 6 # every phase, in order
bash qa/sitewalk.sh # every page of the site itselfThe gates are layered rather than lumped together, which matters when one of them goes red: the phase scripts prove the engine works at all, the parity scripts check behaviour against a frozen baseline of how the original behaved, and separate passes cover the upload formats, the preview images, and a real browser walking the publish flow end to end.
| Gate | What it proves |
|---|---|
qa/upto.sh 6 | Every phase, from the storage layer to the dashboard |
qa/parity*.sh | Behaviour matches the recorded baseline, field by field |
qa/formats.sh | markdown, svg and zip render, not merely upload |
qa/ogshot.sh | A share card is a real screenshot of the current revision |
qa/journey.sh | A browser, not a client library, completes the whole flow |
Depth, after breadth
Improvement. Having a page at every address is not the same as the page being worth reading. The pass after the site went up went through it section by section and filled in what was structurally thin — the per-client integration guides gained the parts nobody documents (what to do when the sandbox has no network, how to clean up after a loop, what the reader on the other end actually sees), and the comparison pages gained the question a comparison exists to answer: how hard is it to leave again.
# every published page can be pulled back out, in the bytes that are served
curl -s https://read.botook.ai/sites -H "Authorization: Bearer otr_live_KEY" | jq '.sites[].id'
curl -s https://read.botook.ai/sites/SITE_ID/content -H "Authorization: Bearer otr_live_KEY" -o page.htmlTwo claims were corrected rather than expanded while checking them against the code, which is
the useful part of writing documentation late: one-time links are not merely "not consumed by an
unfurl" — they are never screenshotted at all, because the same rule that forbids previews for gated
pages covers them. And an expired link answers 410 until the purge runs and
404 afterwards, which the security page had collapsed into one code.
curl -so /dev/null -w '%{http_code}\n' https://read.botook.ai/p/EXPIRED_TOKEN/Measuring pages without spending the request budget
Improvement. Every content page is scored against a frozen baseline — keyword coverage, section count, code-block count — and that scoring used to run against the deployed site. Running it on every iteration is how an unattended loop walks into the daily request ceiling of the free tier, so the same scorer now reads from a local dev server and only the release is measured in production.
npx wrangler dev --local --port 8799
node tools/surface-score.mjs # same baseline, local pages
SHOW_MISS=1 node tools/surface-score.mjsThe lesson generalises past this repository: a verification step that is expensive to run gets run less often, and a verification step that is never run is decoration.
Reactions as their own record
Improvement. Reactions were split from feedback in storage: feedback is a to-do with a resolve state, a reaction is an opinion. The author-side read merges them, so the distinction never reaches the API.
What is next
The ledger in the repository lists what is deliberately not built — per-call payments, a distributed Slack app, a plan system — each with a reason. That list is the roadmap's negative space, and it is more honest than a list of promises.