◈OpenTree DashboardSign in

$ git log --reverse

What shipped, in the order it shipped

This deployment was built in phases, each one gated by a test script that had to pass before the phase counted as done. The list below is that history, taken from the commits.

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.md

Preview 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 itself

The 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.

GateWhat it proves
qa/upto.sh 6Every phase, from the storage layer to the dashboard
qa/parity*.shBehaviour matches the recorded baseline, field by field
qa/formats.shmarkdown, svg and zip render, not merely upload
qa/ogshot.shA share card is a real screenshot of the current revision
qa/journey.shA 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.html

Two 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.mjs

The 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.

Keep reading