Design Documents¶
Detailed implementation design docs — file layouts, data models, algorithm choices, and trade-offs as they were understood when each piece of work was planned.
These are more granular than the decision records, which capture why a direction was chosen. Design docs capture how something is built.
| Doc | Date | Scope |
|---|---|---|
| Docs AST Pipeline | 2026-06-17 | Phase 2 HTML→AST→Docs API pipeline — AST node design, file layout, emitter algorithm, test plan |
| Heading-Anchor Resolution | 2026-07-28 | Resolving GitHub/GitLab #slug heading-anchor links to working Docs jump links — multi-scheme slugifier, strip-if-unmatched policy, opinionated-layer-over-primitive rationale |
| Native Markdown/HTML Image Support | 2026-08-02 | Image as a zero-width AST node vs. a marker-based alternative, the combined table+image descending-position insertion pass, three-source-kind resolution + share/revoke lifecycle, the retry-on-image-failure fix, and the deliberate table-cell-image gap |
| Borderless-Table Columns | 2026-08-02 | Form-style column alignment via a zero-padding table, once tabStops was found read-only (#404) — border-suppression step flagged unverified pending live check |
| Blockquote Representation | 2026-08-06 | Flat blockquote_depth field (mirroring BulletItem.depth) vs. a wrapper node; left border + scaled indent via paragraphStyle.borderLeft, live-verified writable before implementing |
| Module Implementation History | 2026-09-29 | Per-PR history behind root CLAUDE.md's module and workflow rules, moved there verbatim by #849 so CLAUDE.md keeps only lasting rules and invariants |
| SSE OAuth Consent Off the Event Loop | 2026-10-01 | #833: the SSE consent wait on a daemon thread with a stoppable callback server, shared across connections, ended by sse_starlette's shutdown flag on SIGTERM |
| Re-authorizing OAuth from the Failing Tool Call | 2026-10-06 | #873/#906: a revoked or missing token offers the consent link from the failing call (URL elicitation, or the link in the ToolError), detected at thread_http's transport so tools that catch errors are covered, adopted in place on every connection |
| Local-File Access Policy | 2026-10-10 | #796: LOCAL_FILE_ACCESS=full\|roots\|off resolved at import from argv (plus an HTTP-request tripwire for launches argv can't see), one check_read/check_write at each choke point and per entry in folder walks, an identity-based (samefile) deny-list of the server's own credential/config/cache/log files, @tool(local_only=True) unregistering nine tools in off mode, mode and roots reported in server://auth-status and the refusal |
| Google Doc Revisions as Markdown | 2026-10-11 | #959: export_revision on a Doc via DOCX export → temporary Doc → get_doc_as_markdown's own converter (Drive's Markdown and HTML exports measured lossy), heading links and image URLs rewritten so two exports diff cleanly, shielded temp-Doc cleanup |
| Backup Copy Before Replacing a Doc's Content | 2026-10-12 | #878: write_doc_content/update_doc_from_file copy a non-empty doc with files.copy before the clear, delete it on success and name it as backupId on failure; the planned pre-clear revision ID was measured to 404 right after the clear |
| One Temporary-Image-Share Lifecycle | 2026-10-13 | #909: images.ImageShareLifecycle shared by _apply_doc_content and insert_local_images (shielded gather, pre-edit and post-revoke checkpoints, shielded revoke and log), after_abandoned_calls re-invalidating the doc cache once an abandoned edit lands, created_in tagging so each upload's folder is marked dirty |