Tdoc

tdoc — Prompt-native HTML documents

Open-source, collaborative. Docs are HTML build artifacts, not files the user maintains.

Source of truth (see AGENTS.md): Remote storage is source of truth. Local HTML is disposable. Local skill is authoring/scaffold. Authoring interface is a prompt. Every edit creates a new version. Comments anchor to highlighted text or to artifacts (images, SVG, canvas, video) and are used to regenerate the next version. Each user publishes to their own Cloudflare Worker for free always-on sharing, with GitHub auth gating comments.

Storage layout

~/tdocs/
  <slug>/
    meta.json          # { title, created, versions: [...] }
    v1/index.html
    v1/widgets/<name>.html  # optional; sandboxed JS island, served at /widget/<name>
    v2/index.html
    comments.json      # [{ id, version, anchor, text, status }]

Server runs at http://localhost:7878 (override with TDOC_PORT) and serves:

• / — index of all docs
• /d/<slug>/v/<n> — a specific version (injects comment overlay)
• /d/<slug>/v/<n>/widget/<name> — sandboxed interactive island (no overlay)
• /api/comments GET/POST — comment persistence
• /api/ping — health check; responds {"ok":true,"service":"tdoc"}. The service field is the identity marker — a foreign service answering 200 on the port must NOT pass as tdoc.

Setup check

TDOC_DIR="${TDOC_DIR:-$HOME/tdocs}"
# Resolve the skill dir for whichever host installed it: Claude Code
# (~/.claude/skills/tdoc) or Codex (~/.codex/skills/tdoc). Honor an explicit
# TDOC_SKILL_DIR override if set. Claude's location is checked first, so its
# behavior is unchanged.
SKILL_DIR="${TDOC_SKILL_DIR:-}"
[ -z "$SKILL_DIR" ] && for d in "$HOME/.claude/skills/tdoc" "$HOME/.codex/skills/tdoc"; do
  [ -f "$d/SKILL.md" ] && SKILL_DIR="$d" && break
done
SKILL_DIR="${SKILL_DIR:-$HOME/.claude/skills/tdoc}"
mkdir -p "$TDOC_DIR"

# Check server is running. Identity-check the body — 200 alone is not proof
# the answerer is tdoc; another local service can squat the port.
TDOC_PORT="${TDOC_PORT:-7878}"
PING_BODY=$(curl -sf --max-time 2 "http://localhost:${TDOC_PORT}/api/ping" 2>/dev/null || true)
if printf '%s' "$PING_BODY" | grep -q '"service" *: *"tdoc"'; then
  echo "SERVER_OK"
elif [ -n "$PING_BODY" ]; then
  echo "PORT_FOREIGN"   # something else answers on the port — do NOT use it
else
  echo "SERVER_DOWN"
fi

If PORT_FOREIGN: another service holds port ${TDOC_PORT}. If pgrep -f "$SKILL_DIR/server/server.js" finds a process, it's an outdated tdoc server — restart it. Otherwise tell the user which process holds the port (lsof -i :${TDOC_PORT}) and either free it or set TDOC_PORT to a free port.

If server is down, start it:

nohup node "$SKILL_DIR/server/server.js" > "$TDOC_DIR/.server.log" 2>&1 &
sleep 1

Authoring contract — read before writing any doc

Three files are required reading before you write doc HTML, on every /tdoc new and every regeneration in /tdoc edit:

File	Governs	Selectable?
$SKILL_DIR/authoring/voice.md	how the prose reads	No. A floor — no switch, no doc exempt.
$SKILL_DIR/authoring/visuals.md	how much of the doc is a picture	No. A floor — be visual-first, many visuals, varied types.
$SKILL_DIR/authoring/style/default.md	what the page looks like	Only by naming another entry in style/.

$SKILL_DIR is the installed skill directory resolved in "Setup check" above (~/.claude/skills/tdoc, or ~/.codex/skills/tdoc under Codex) — not the current working directory, which is the user's project.

voice.md carries tdoc's adaptation of the vendored no-ai-slop rule set ($SKILL_DIR/authoring/vendor/no-ai-slop.md) — which prose the rules govern, which spans they must never rewrite (code, identifiers, quotes, data), and whose voice is being preserved when the agent is the one writing.

style/default.md is the stark sans style: pure white, pure black, one clean sans everywhere (open Inter, standing in for the proprietary OpenAI Sans), an oversized tight-tracked headline, near-zero color, and a full technical-diagram vocabulary (thin frames, mono pill labels, numbered containers, solid/dashed arrows, one accent per figure, dot/hatch textured fills). The OpenAI-index aesthetic, done with open fonts — no brand assets, a look not an identity. Apply it unless the user names a different entry in $SKILL_DIR/authoring/style/.

The other entries a user can name:

• $SKILL_DIR/authoring/style/technical.md — a cold engineering-blog register: mono for identifiers and metrics, neutral greys for structure, a single sparing red-orange accent. For dense technical writeups.
• $SKILL_DIR/authoring/style/editorial.md — a long-read essay register: warm paper ground, a serif reading voice, electric-blue accent, and colored underlines that mark terms inline. The one style that overrides typography, and only the ground and body font.
• $SKILL_DIR/authoring/style/paper.md — a warm serif long-read: off-white paper ground, an open serif display (Fraunces) over a humanist sans body, one clay accent. The Anthropic-blog aesthetic, done with open fonts (not the proprietary brand fonts, no logo/byline — a look, not an identity).

$SKILL_DIR/authoring/structure/ is still an empty mount point. Empty means no choice to make: derive the document's shape from the prompt.

visuals.md is the visual-first floor: lead with charts, diagrams, tables, and stat tiles rather than paragraphs; pick the visual type that fits the data (bar, line/scatter, quadrant, matrix, timeline, stacked bar, flow — not a flowchart by default); most docs carry several different types. The style colors them; this file decides there should be many.

Commands

/tdoc new <prompt> — create a new doc

Where it goes. A doc is published to hosted tdoc.dev and the user is handed a shareable link. That is the default and it is not something to ask about. Two things change it, and only if the user says so in their own words:

The user said	Destination	What they get back
nothing about hosting	hosted tdoc.dev	https://tdoc.dev/d/<slug>/v/1 — link-readable, not listed anywhere
"publish to my own Cloudflare / Vercel", "self-host it"	their own worker	<worker>.workers.dev / tdoc-<scope>.vercel.app — still a public link, not localhost
"keep it local", "don't upload it anywhere", "just show me locally"	local only	http://localhost:7878/...

The localhost rule: never hand over a localhost URL unless the user asked to keep the doc local. Not as a fallback, not when a sign-in did not finish, not as "here it is locally in the meantime". Asking to self-host on Cloudflare or Vercel is NOT asking for localhost — that path still ends at a public URL. If publishing cannot complete, say so and leave the doc in $TDOC_DIR/<slug>/; do not substitute a local URL for the link the user was promised.

This rule is about what you hand over, not about the local server, which is untouched. /tdoc serve still works for everyone, and previewing locally while iterating is fine whenever the user asks for it — it is simply not what a finished doc is delivered as.

Step 0 — start the sign-in before you start writing. Hosted publishing needs a one-time GitHub sign-in. Generating a doc takes 30–60 s and the device flow is a poll loop, so run them at the same time rather than interrupting the user at the end:

# no-op and instant when already signed in
"$SKILL_DIR/bin/tdoc-publish" --signin-only

Launch this in the background (Bash run_in_background: true) and go straight on to writing the doc. It opens GitHub in the user's browser and prints a short code that they type there — GitHub does not accept the code through the URL, so it has to be entered by hand. Tell the user in one line that a GitHub page has opened and that the code is in the terminal; then keep working. Skip Step 0 entirely for the local-only and self-host destinations.

1. Pick a slug from the prompt (kebab-case, ≤4 words).

2. Read $SKILL_DIR/authoring/voice.md, $SKILL_DIR/authoring/visuals.md, and $SKILL_DIR/authoring/style/default.md. Voice constrains the prose as you generate it, not as a later cleanup pass. The style tells you which components to reach for and its palette — apply it unless the user named another entry in $SKILL_DIR/authoring/style/. The named style file is the complete visual contract: use its CSS, but do not invent a second page-wide aesthetic on top of it.

3. Create ~/tdocs/<slug>/v1/index.html — the host document:

   • All host CSS inline in <style>. Never put JavaScript in the host. Host <script>, on*= handlers, and javascript: URLs are inert under CSP and therefore create controls or empty panels that cannot work. If the idea needs computation, write v1/widgets/<name>.html and iframe it.
   • No external CDNs in the host unless requested. No build step.
   • The default style is mandatory when the user names no style. A full-page custom design is allowed only when the user explicitly requests one; programmatic callers must make that exception visible with --custom-template.
   • Interactive: if the prompt implies a model or diagram, build it with the CSS-only techniques in "Interactivity: CSS only" — :checked toggles, CSS keyframes, <style> inside the <svg>. If the idea genuinely needs computation, emit a sandboxed widget island (see that section); do NOT put <script> in the host document.

4. Validate the host before recording or opening the doc. This is mandatory for every generated version, including chat-driven /tdoc new:

   "$SKILL_DIR/bin/tdoc-validate-template" \
     "$TDOC_DIR/<slug>/v1/index.html" --style <selected-style>
   

   Use --custom-template only when the user explicitly requested a custom whole-page design. It never permits host JavaScript. If validation fails, fix the host or move computation into v1/widgets/<name>.html; do not open, publish, or report the document as complete.

5. Write meta.json:

   { "title": "...", "slug": "...", "created": "<iso>", "versions": [{ "n": 1, "created": "<iso>", "prompt": "..." }] }
   

6. Init comments.json as [].

7. Publish and hand over the link.

   Hosted (the default). Confirm the background sign-in from Step 0 finished, then publish:

   "$SKILL_DIR/bin/tdoc-publish" <slug>
   # keep earlier drafts to yourself:
   #   "$SKILL_DIR/bin/tdoc-publish" --history owner <slug>
   

   Report the https://tdoc.dev/d/<slug>/v/1 URL on its own line, and say what it is — the user may never have seen a tdoc page before. Describe the access it actually has, which for a plain publish is the legacy policy:

   Your doc is live. Anyone with this link can read it — and can page back through earlier versions — but it is not listed anywhere, so only people you send it to will find it.

   Do not call it "unlisted". A publish with no explicit flags stores no access block and takes the legacy policy (visibility: public, history_visibility: public); saying unlisted would understate what a recipient can see. If the user wants earlier versions kept private, that is --history owner.

   If the sign-in has not completed yet, do not fall back to localhost and do not go quiet. Say the doc is written and waiting, and that approving the GitHub page finishes it — or that they can say "publish it" later and you'll get them a fresh code. The doc stays in $TDOC_DIR/<slug>/.

   Self-host. "$SKILL_DIR/bin/tdoc-publish" --platform cloudflare <slug> (or vercel). Report the worker URL, with the same note about access.

   Local preview stays available to self-hosting users — /tdoc serve and http://localhost:7878 are unchanged, and iterating locally before pushing to your own worker is a perfectly good loop. That is an authoring step the user can ask for at any time; it does not change what gets handed over at the end, which is still the worker URL. Nothing about the local server was removed.

   Local only — because the user asked. Start the server if needed and open the local URL:

   open "http://localhost:7878/d/<slug>/v/1"
   

   This is the only branch that reports a localhost URL.

bin/tdoc-new — programmatic entry for agents in other skills

This is the contract OTHER skills (/document-release, /retro, /investigate, /cso, /qa-only, /office-hours, /plan-*, etc.) use when an agent inside them is about to emit a doc-shaped artifact. The human-facing /tdoc new flow is a chat-driven prompt → HTML generation. bin/tdoc-new is the other direction: the calling agent already has the finished HTML and just wants tdoc to scaffold storage, serve it locally, and (optionally) publish.

When to use it: any time inside another skill you would otherwise have written cat > some-report.md <<EOF ... with more than a couple paragraphs of structured content. Generate the doc as HTML (use the template + styling rules from the /tdoc new section above), then hand it off:

HTML_FILE=$(mktemp -t tdoc-handoff.XXXXXX.html)
cat > "$HTML_FILE" <<'HTML'
<!doctype html>
<html lang="en">
<head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
<title>...</title></head>
<body><div class="wrap">
  <h1>...</h1>
  <!-- sections; tag author-composed wrappers data-tdoc-artifact
       wherever you want a comment surface -->
</div></body>
</html>
HTML

TDOC_NEW_CALLER=document-release \
  ~/.claude/skills/tdoc/bin/tdoc-new \
    --slug "release-notes-$(date +%Y%m%d)" \
    --title "Release notes — $(date +%Y-%m-%d)" \
    --html-file "$HTML_FILE" \
    --publish

Args:

• --slug <kebab-case> (required) — slug for ~/tdocs/<slug>/.
• --title "<title>" (required) — recorded in meta.json.
• --html-file <path> OR --html-stdin (required) — full HTML for v1.
• --widgets-dir <path> — optional directory of sandboxed widget HTML files. Each <name>.html is stored as v1/widgets/<name>.html; JavaScript belongs there, never in the host HTML.
• --prompt "<one-line>" — prompt-of-record in meta.json (defaults to Imported via tdoc-new by <caller>).
• --publish — also run tdoc-publish so a shareable URL is returned.
• --open — open the resulting URL in the default browser.
• --quiet — suppress informational output (the URL is still printed on the last line so callers can capture it).
• --style default|technical|editorial|paper — selected house-style contract. Omit it to use default.
• --custom-template — explicit opt-out from the default template for a user-requested presentation, landing page, or full-bleed simulation. Normal docs must not pass it.
• --force — overwrite an existing slug. Without this, an existing slug is a hard error (no silent clobber).

Output contract: the local URL is always the last line on stdout. If --publish succeeded, the published URL appears on a second line. This is what callers should tail -n 1 (or tail -n 2) to capture.

Guards built in: refuses to clobber existing slugs without --force; validates the host before replacing an existing doc; copies explicitly supplied widget files; restarts the local server if needed. Host validation rejects <script>, on*= handlers, javascript: URLs, and <canvas> even in custom-template mode, because all of them are inert under the host CSP and can silently create empty UI. It also enforces the selected house-style boundary. Whole-page custom styling requires the deliberate --custom-template flag; that flag never permits host JavaScript.

Set TDOC_NEW_CALLER (or rely on CLAUDE_SKILL_NAME) so meta.json records which skill scaffolded the doc — useful for later auditing or for /tdoc list to show provenance.

/tdoc edit <slug> [<extra prompt>] — new version from comments

You MUST report back on every open comment — applied, partial, or unclear. This is a hard requirement, not a suggestion. The user can't tell which comments you handled unless you reply on each one. Skipping comments silently is the #1 source of regression complaints.

1. Read ~/tdocs/<slug>/comments.json — filter to status: "open".

2. Read latest version's index.html, and re-read $SKILL_DIR/authoring/voice.md and $SKILL_DIR/authoring/visuals.md. A regeneration writes new prose, so the contract applies here exactly as it does on /tdoc new. Prose you carry over unchanged from the previous version stays as it is — do not re-edit untouched sections for voice, and keep whichever style the existing version already uses rather than restyling a doc the reader has been reading.

3. For EACH open comment, decide one of three outcomes BEFORE writing:

   • applied — the comment is clear and you can act on it.
   • partial — you applied part of it but couldn't fully address it (e.g. the user asked to "add a chart and explain compound interest"; you added the chart but the explanation is shallow).
   • question — you can't act without clarification (the comment is ambiguous, contradicts another comment, or refers to content that doesn't exist in the current doc).

4. Regenerate as v<n+1>/index.html incorporating every applied and partial comment. A comment's anchor has:

   • anchor.text — the exact text the user highlighted (may span across paragraphs and inline elements)
   • anchor.context_before / anchor.context_after — surrounding text (~60 chars each side) for disambiguation when the same text appears multiple times

5. Validate v<n+1>/index.html before updating metadata or replying to comments. Run bin/tdoc-validate-template with the style already used by the document. If validation fails, repair the host or move the computation into v<n+1>/widgets/<name>.html; never publish or report a broken version.

6. Append to meta.json versions array.

7. For each comment, post an agent reply so the user sees the outcome in the doc UI. This is mandatory.

   Use bin/tdoc-agent-reply. It auto-detects the host runtime (Claude Code, Codex, Grok, Cursor, Gemini) from the process environment and stamps agent_login so the comment shows that product's logo. Do not invent a login or pass tdoc-agent. Only pass --login if you must override detection. The published Worker cannot see your env, so do not raw-curl /api/agent/reply yourself — the helper stamps identity before the request leaves the machine.

   "$SKILL_DIR/bin/tdoc-agent-reply" \
     --slug "<slug>" \
     --parent "<comment_id>" \
     --text "<one or two sentences>" \
     --status applied \
     --applied-in <n+1>
   

   It posts to the published Worker when ~/.tdoc/published.json exists, otherwise to http://localhost:${TDOC_PORT:-7878}. Users can also reply to any reply (HN/Reddit-style nesting); parent is the comment or reply you are answering.

   The reply text should be specific:

   • applied: "Rewrote the second paragraph in English. The section heading is now 'What an Agent Needs'."
   • partial: "Added the chart but the compound-interest explainer is still basic — want me to flesh it out?"
   • question: "Two of your comments asked for different tones — formal in the intro and casual in section II. Which should I prioritize?"

8. Update comments.json: set status: "applied" (or leave "open" for partial/question) and applied_in: n+1. The agent-reply endpoint already flips the status server-side AND drops a status emoji on the parent comment (✅ applied, 🟡 partial, ❓ question), clearing any previous agent emoji first. You don't need to send a separate reaction request — the reply endpoint does it. Users see the verdict at a glance from the comment cards without expanding replies.

   If a comment is later re-anchored by the user (anchor moved to new text), the server automatically clears the agent's emoji and resets status: "open". Re-running /tdoc edit will pick it up again.

9. Publish the new version and hand back its link, the same way /tdoc new does. A doc that was published stays published; report https://tdoc.dev/d/<slug>/v/<n+1> so the reviewer can see the version their comment produced. The link a user already shared keeps working — a new version never breaks it.

   "$SKILL_DIR/bin/tdoc-publish" <slug>
   

   Only report a localhost URL if this doc is local-only because the user asked for that (see the localhost rule in /tdoc new).

If there are zero open comments AND no extra prompt, ask the user what to change before doing anything.

/tdoc fork <slug> [<new-slug>] — copy a doc

cp -R "$TDOC_DIR/<slug>" "$TDOC_DIR/<new-slug>"

Reset comments.json to []. Update meta.json title to include (fork).

/tdoc list — show all docs

Read each meta.json and print: slug, title, latest version, # open comments.

/tdoc serve — (re)start the server

pkill -f "$SKILL_DIR/server/server.js" 2>/dev/null
nohup node "$SKILL_DIR/server/server.js" > "$TDOC_DIR/.server.log" 2>&1 &
echo "tdoc server: http://localhost:7878"

/tdoc stop — stop the server

pkill -f "$SKILL_DIR/server/server.js"

/tdoc publish <slug> — publish to hosted tdoc (default), or self-host

Publishes the latest version of <slug> to a public URL.

Architecture — publish auth, multi-tenant scoping, GitHub-account/BYOK switching, and the client-version gap — is written up as a tdoc: docs/publish-auth-architecture.html (live: tdoc.dev/d/tdoc-auth-arch). Read it before changing bin/tdoc-publish, bin/tdoc-update-nag, or the worker auth/hosted-token routes.

Default target is hosted (https://tdoc.dev). First run signs in with GitHub (Device Flow), then asks the host for an account-scoped upload token bound to that login and stores it in ~/.tdoc/published.json. That token can only mutate docs it owns. /me on tdoc.dev lists that GitHub user's docs. If hosted signup is not open on the target, the CLI fails with a clear prompt to self-host instead — do not tell the user to flip a Worker env flag.

Self-host — Cloudflare: tdoc-publish --platform cloudflare <slug>. First run (or an explicit switch onto cloudflare) prompts wrangler login, creates an R2 bucket (tdoc-docs) and KV namespace (META) in your Cloudflare account, generates an upload token, and deploys your own Worker. The choice is persisted in ~/.tdoc/published.json as the default.

Self-host — Vercel: tdoc-publish --platform vercel <slug>. First run (or an explicit switch onto vercel) needs the vercel CLI (npm i -g vercel), links a Vercel project named tdoc, then asks you (via an agent prompt) to connect a Blob store and an Upstash Redis store in the Vercel dashboard's Storage tab — both free tier, ~2 clicks each — and deploys. Caveats: no per-doc write serialization (Cloudflare uses a Durable Object for that) and a ~4.5 MB upload cap per doc (Vercel request limit).

Subsequent runs upload the latest version of <slug> using the saved default. Pass a different --platform any time to switch: full re-setup rewrites published.json (previous file kept as published.json.bak.switch). A custom domain and *.workers.dev on the same Worker are two hostnames, not two platforms. Self-host targets compare a content hash of the Worker/overlay bundle against the last deployed hash in ~/.tdoc/published.json and redeploy automatically when runtime code changed. Set TDOC_SKIP_WORKER_DEPLOY=1 to skip the redeploy (useful for batch uploads). Published pages expose runtime provenance at /api/runtime and in window.__TDOC__.runtime.

Local preview (tdoc serve) does not need GitHub login. Published docs — hosted (tdoc.dev) and BYOK remote (your Cloudflare/Vercel worker) — use GitHub Device Flow for commenter sign-in via the org-owned OAuth App in shared/github-oauth.js (scope read:user). Viewers authorize that shared app; they do not register their own. Set the OAuth App callback URL to https://<host>/auth/done so GitHub's post-approve redirect is not a 404.

Hosted needs no extra CLI beyond Node 18+ and curl. Self-hosting needs jq. Cloudflare needs wrangler (npm i -g wrangler); Vercel needs vercel (npm i -g vercel).

"$SKILL_DIR/bin/tdoc-publish" <slug>

Prints the published URL: https://tdoc.dev/d/<slug>/v/<N> (hosted), https://<worker>.<subdomain>.workers.dev/d/<slug>/v/<N> (Cloudflare), or https://tdoc-<scope>.vercel.app/d/<slug>/v/<N> (Vercel).

/tdoc pull <slug> — pull comments from the published doc

Overwrites local ~/tdocs/<slug>/comments.json with comments collected on the published Worker. Run before /tdoc edit to regenerate using community feedback.

"$SKILL_DIR/bin/tdoc-pull" <slug>

/tdoc unpublish <slug> — remove from your Worker

Deletes all versions, meta, and comments for <slug> from R2/KV. Local files are untouched.

"$SKILL_DIR/bin/tdoc-unpublish" <slug>

/tdoc onboard — guided first-time setup

You are walking a user through tdoc onboarding. The user might have nothing installed, or might be partway through. You must drive the flow from bin/tdoc-doctor JSON output, not assume state.

Algorithm:

1. Run "$SKILL_DIR/bin/tdoc-doctor" and parse the JSON. This is non-destructive. The doctor is target-aware and reports what it assessed under .target. The default is hosted (tdoc.dev), which needs only Node 18+ and curl — no Cloudflare account, no wrangler, nothing to click in a dashboard. Only pass --platform cloudflare / --platform vercel when the user has asked to self-host.
2. If .ready_to_publish == true AND .published.ok == true → tell the user they are fully set up, and offer to run /tdoc new <prompt> or to test publishing with a sample doc.
3. If .ready_to_publish == true AND .published.ok == false → they have all deps but haven't published yet. Offer to create a quick sample doc with /tdoc new and then /tdoc publish it.
4. Otherwise, walk through .missing_steps in order. On the hosted default this list is usually empty. For each step:
   • kind == "install": run the cmd for them via Bash (e.g. brew install jq). After install, re-run tdoc-doctor to confirm.
   • kind == "login": explain that this opens a browser, then run the cmd. wrangler login is interactive — print clear instructions and wait.
   • kind == "click": you cannot click for the user. Print the URL clearly and tell them what to do ("Open this and click 'Enable R2'"). Then wait for the user to say "done", then re-run tdoc-doctor to verify. login and click steps are self-host only. If one appears for a user who never asked to self-host, re-read .target before sending them to a dashboard.
5. After every step, re-run tdoc-doctor and continue from the new state.
6. When .ready_to_publish == true, congratulate and offer to create + publish a sample doc.

Important behavioral rules:

• NEVER skip the doctor check before suggesting a step. State changes between steps (e.g. R2 takes a few seconds after enabling).
• NEVER walk a hosted user through Cloudflare setup. Publishing to tdoc.dev does not use wrangler, a workers.dev subdomain, or R2.
• ALWAYS show the user what you're running. Print the JSON status if helpful.
• If a "click" step doesn't take effect after the user says "done", offer to re-check after waiting 10s (Cloudflare API can be slow to reflect changes).
• Published/BYOK remotes bake in the shared org OAuth client ID from shared/github-oauth.js — users do NOT register their own. Local preview never needs that login path.

/tdoc update — check for updates and pull the latest

Wraps bin/tdoc-update. Runs git fetch + git merge --ff-only against origin/main of tornado-doc/tdoc.

• tdoc-update --check → report-only, prints incoming commits without changing anything
• tdoc-update → apply, with auto-stash of local edits, auto-restarts the running local server so new routes / overlay code take effect
• tdoc-update --yes → also redeploy the Worker so users get the new overlay

BYOK CLIs (tdoc-publish / pull / unpublish / new) and every skill run also check origin/main and nag immediately when this checkout is behind. tdoc-doctor reports the same as .update (not a missing_step).

"$SKILL_DIR/bin/tdoc-update" --check    # see what's new
"$SKILL_DIR/bin/tdoc-update"            # apply
"$SKILL_DIR/bin/tdoc-update" --yes      # apply + redeploy worker

If the user has not yet git clone'd (the skill dir is not a git checkout), the script prints a clean instruction to re-clone.

/tdoc doctor — health check, no changes

Prints the doctor JSON. Use this when the user reports a problem to localize which dep / Cloudflare resource is missing.

# jq is a self-host-only dependency, so read the report with node.
"$SKILL_DIR/bin/tdoc-doctor" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>console.log(JSON.stringify(JSON.parse(s),null,2)))'

Troubleshooting

When the user reports a problem, check these first:

• /api/publish 404, or "string did not match the expected pattern" in the Publish modal → the running server is stale (old process, doesn't have current routes). Restart it: pkill -f "$SKILL_DIR/server/server.js" && nohup node "$SKILL_DIR/server/server.js" > "$TDOC_DIR/.server.log" 2>&1 &. /tdoc update now auto-restarts, but a server that was started before the update is still running stale code until restarted.
• Comment popup doesn't appear when selecting text → ensure overlay.js has the fix where a drag-without-artifact-intersection falls through to the text-selection branch (regression test: ui.test.js "Drag-to-select TEXT in a <p> opens the comment popup"). If the test fails, check overlay.js mouseup handler: the if (dragged) { ... return; } block must only return when an artifact was actually hit.
• Publish modal hangs forever → check ~/tdocs/.server.log; usually wrangler login is waiting for browser auth or R2 isn't enabled.
• Local doc URLs show the wrong content / weird JSON, or the server "is up" but docs 404 → another local service may be squatting the tdoc port (seen in the wild: a daemon from another product bound 7878). Run curl -s http://localhost:7878/api/ping — if the body lacks "service":"tdoc", the answerer is not tdoc. Identify the squatter with lsof -i :7878, then free the port or run tdoc on another port via TDOC_PORT=<port> (the bin scripts and server all honor it).

HTML generation rules

• The prose in the doc is governed by $SKILL_DIR/authoring/voice.md. These rules cover markup; that file covers the words inside it. Both apply to every doc. It also fences off the spans the prose rules must never touch — code, identifiers, quoted material, and data.
• Host HTML does not run author JavaScript. Every host document is served under a nonce-based CSP (script-src 'nonce-<n>' 'strict-dynamic'; object-src 'none'; base-uri 'none';) and the nonce is stamped onto the two injected overlay scripts only. Host <script> tags (inline or src), onclick=/onchange= attributes, and javascript: URLs have no nonce, so the browser refuses them: no error in the page, no visible failure — just a control that never does anything. This is true on both the local server (server/server.js → cspHeader, injectOverlay) and published docs (worker/worker.js → cspHeader, injectOverlayCfg). Exception — sandboxed island: if the doc needs computation, write v<n>/widgets/<name>.html and embed <iframe sandbox="allow-scripts" src="/d/<slug>/v/<n>/widget/<name>">. Inline <script> in that widget file does run. Never put author JS in the host document. See "When the prompt wants something CSS can't express" below.
• Host document is one HTML file (no imports). Optional islands are extra files under v<n>/widgets/. External <script src> in the host is blocked by the same CSP, so a CDN library (D3, Chart.js, …) will not load in the host — put it in a widget island or say so rather than shipping a dead reference.
• Sandboxed-safe: the server serves docs inside an iframe overlay-host, so don't rely on top-level navigation or parent-frame access.
• The comment overlay is injected by the server — don't add commenting UI yourself.
• Don't add a "made with tdoc" footer, version selector, or share button. The shell handles those.
• Use SVG for diagrams (commentable text, and CSS can animate it). Don't use <canvas> in the host — nothing can draw to it without JS. Draw inside a widget island if needed.
• Default font stack: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif. Mono: ui-monospace, "SF Mono", Menlo, monospace.

Interactivity: CSS only

Author <script> in the host document never executes (see above), so every moving or switchable part of the host has to be declarative. The patterns below are verified on this runtime; a working reference doc using all three is at ~/tdocs/agent-gui-integration/v1/index.html. Computed state belongs in a sandboxed island, not in the host.

1. Toggles and mode switches — :checked + sibling selectors

A hidden <input type="radio"> (or checkbox), then <label for="…"> controls and the panes it switches. Everything toggled must be a sibling that comes after the input: ~ only reaches forward, and only within one parent.

<div class="fig" data-tdoc-artifact>
  <input type="radio" name="mode" id="m-a" class="vis-radio" checked>
  <input type="radio" name="mode" id="m-b" class="vis-radio">
  <div class="fig-controls"><label for="m-a">Before</label><label for="m-b">After</label></div>
  <div class="pane pane-a"> … </div>
  <div class="pane pane-b"> … </div>
</div>

/* off-screen, NOT display:none — that drops it out of the tab order */
.vis-radio { position: absolute; width: 1px; height: 1px; opacity: 0; pointer-events: none; }
.pane-b { display: none; }
#m-b:checked ~ .pane-a { display: none; }
#m-b:checked ~ .pane-b { display: block; }
#m-b:checked ~ .fig-controls label[for="m-b"] { background: #111; border-color: #111; color: #fff; }

2. Motion — CSS @keyframes

For flow along a route, animate stroke-dashoffset on a dashed copy of the path drawn over a static base path:

.flow { stroke-dasharray: 9 22; animation: flowdash 2.2s linear infinite; }
@keyframes flowdash { to { stroke-dashoffset: -31; } }
@media (prefers-reduced-motion: reduce) { .flow { animation: none; } }

Always ship the prefers-reduced-motion guard.

3. SVG styling — put <style> INSIDE the <svg> element

A <style> in <head> was observed not to reach elements inside inline SVG on this runtime. SVG-internal <style> is the reliable placement, so make each <svg> fully self-contained:

<svg viewBox="0 0 720 400" role="img" aria-label="…">
  <style>
    .flow-a { stroke-dasharray: 9 22; animation: flowdash-a 2.2s linear infinite; }
    @keyframes flowdash-a { to { stroke-dashoffset: -31; } }
    @media (prefers-reduced-motion: reduce) { .flow-a { animation: none; } }
  </style>
  …
</svg>

Give each SVG its own class names and @keyframes names (flow-a / flowdash-a, flow-b / flowdash-b) so two figures on one page don't collide.

What does NOT work in the host document

• <script> of any kind, on*= handler attributes, javascript: URLs — all inert in the host. The same tags do run inside v<n>/widgets/<name>.html.
• SMIL (<animate>, <animateMotion>, <animateTransform>): verified not to run here — the SVG timeline stays frozen at getCurrentTime() === 0. Use CSS animation instead.
• <canvas> in the host: a blank box without JS. Draw inside a widget island if needed.
• Computed state in the host — simulations, a slider that recalculates a model, live data, sorting or filtering a table, form validation. Use a sandboxed island.

When the prompt wants something CSS can't express

Game of Life, a live calculator, a parameter sweep. Do not put <script> in the host document — it is inert under CSP. Two options:

1. Sandboxed island (preferred when it must compute). Write a second HTML file and embed it as an iframe. Overlay comments on the iframe as one artifact (iframe[src] is already commentable). Do not walk into the frame.

   ~/tdocs/<slug>/v1/index.html
   ~/tdocs/<slug>/v1/widgets/compound-interest.html
   

   Host document:

   <iframe
     sandbox="allow-scripts"
     src="/d/<slug>/v/1/widget/compound-interest"
     title="Compound interest"
     style="width:100%;height:320px;border:0">
   </iframe>
   

   The sandbox attribute must be allow-scripts only — never add allow-same-origin. The server rewrites matching widget iframes to that value even if the author HTML forgets or adds extra flags. Widget HTML is a full document; inline <script> there does run. Do not use srcdoc, data:, or blob: — those inherit the host CSP and the script stays dead.

2. Precompute if an island is overkill: :checked panels, a static SVG, or a CSS loop, and note in the doc what was simplified.

Download / Duplicate of a doc with islands is not supported in v1 (the downloaded file cannot fetch /widget/ URLs; account copy is host HTML only).

Default styling — trust the reading template, add components on top

The house style ($SKILL_DIR/authoring/style/default.md) deliberately does not touch reading typography. It trusts the overlay's injected template for body size, headings, and measure, and adds only semantic components (risk / positive / leveled block / pill / diagram box). So "do not re-style" and the house style agree: write component CSS and doc-specific CSS, but do not set your own font-size on p, h1, h2 — the overlay already did.

The values below are what the overlay injects, at :where() zero specificity, and what /export and Download PDF inline. The house style sits on top of them rather than replacing them.

The overlay's template is modeled after the conway-life doc ("What if a doc could think?"): tight, readable, system fonts only. Download is a menu: Download HTML (/export, reader CSS inlined as <style id="tdoc-reader">) and Download PDF (print that same reading column; use the browser's Save as PDF). Neither includes overlay chrome (bar, comments).

• System font stack (system-ui, -apple-system, "Segoe UI", Roboto, sans-serif)
• Body: 17px / line-height 1.65 / #111 on white
• h1: 34px / line-height 1.15 / -0.01em letter-spacing
• h2: 24px / 1.25 / 40px top margin
• h3: 19px / 1.35 / 28px top margin
• Paragraph: 18px bottom margin
• Blockquote: 3px solid #111 left rule, #f5f6f8 background-ish quoted block (mono pre)
• pre: mono 15px, light gray background, left-rule, scrolling overflow
• Code (inline): 0.92em mono, light-gray rounded chip

The default style is mandatory when the user names no other style. Use the CSS from $SKILL_DIR/authoring/style/default.md as written. Add only the house style's components and tightly scoped CSS for content-specific charts, diagrams, and controls. Do not invent additional bare-element rules or change the content root's width, margins, or padding.

A different file in $SKILL_DIR/authoring/style/ applies only when the user names it. A presentation or landing page may replace the reading aesthetic only when the user explicitly asks; programmatic creation must mark that exception with --custom-template.

What to write:

<!doctype html>
<html lang="en"><head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>{title}</title>
</head><body>
  <div class="wrap">
    <h1>{title}</h1>
    <p class="meta">{subtitle or attribution}</p>
    <!-- content here using plain <h2>, <h3>, <p>, <ul>, <pre>, <table>, etc. -->
    <!-- host interactivity goes in <style>, not <script>. Computation
         belongs in v1/widgets/<name>.html. See HTML generation rules. -->
  </div>
</body></html>

The overlay's :where() defaults handle:

• Centered article column (max-width: 720px, padded)
• All heading sizes, weights, spacing
• Paragraph + list spacing
• Code/pre, blockquote, table styling
• Link color
• Image margins

Only add CSS for doc-specific content (a custom widget, a simulation, a chart). When you do, scope it tightly (e.g. .my-slider { ... }), not body p { ... }.

Required container structure

Wrap the doc content in a single container element with one of these selectors: .wrap (preferred), main, article, .content, or .container. The overlay relies on this to:

• Detect article width for the responsive breakpoint
• Anchor the article to the LEFT when there are comments (so growing/shrinking the window preserves the right-side comment column)
• Calculate where comment cards land

Note: the container should not have margin: 0 auto. The overlay sets its margins itself based on comment state (overrides with !important if you write it).

Required: explicit body background

Always set body { background: #fff; } (or your chosen color) so the page doesn't render as transparent over the browser default. Light mode only; the overlay does not currently support dark mode.

Responsive defaults (REQUIRED)

Every doc must work on mobile out of the box. The overlay injects defensive CSS for artifacts, but the doc itself should also be authored responsively:

• Always include <meta name="viewport" content="width=device-width, initial-scale=1"> in <head>. (The overlay injects this if you forget, but include it.)
• Use fluid widths, not hardcoded pixels. Container: max-width: 720px; (no margin: 0 auto; no top-level padding: 0 ... — overlay handles margins and top/bottom reading space). If you need custom inner spacing, put it on a child element inside the container.
• SVG / images: do NOT hardcode width=N height=M. Either:
  • Use width="100%" + CSS aspect-ratio (aspect-ratio: 16/9), or
  • Use a wrapper with max-width: 100% and let the artifact scale.
  • For SVG, give the <svg> a viewBox and size it in CSS (width: 100%; height: auto). If the drawing needs more room than a phone gives it, put the <svg> in a wrapper with overflow-x: auto and a min-width on the SVG so it scrolls rather than squashing.
  • (Canvas isn't an option — see "Interactivity: CSS only". Without JS there is nothing to draw into the buffer.)
• Tables: wrap in <div style="overflow-x:auto"> so they scroll instead of overflowing.
• Code blocks (<pre>): max-width: 100%; overflow-x: auto;.
• Test at 375px wide in your head before claiming done. If anything overflows the viewport on a phone, fix it before writing meta.json.

The overlay applies these as :where() defensive defaults so old docs degrade gracefully, but new docs should bake responsiveness in.

Don't conflict with the overlay's UI

• Don't define button:hover { background: ... } globally — it will override the overlay's Comment pill on artifacts. Scope hover rules to your own buttons (e.g. .my-btn:hover, or .wrap button:hover).
• Don't use these ids/classes in your doc — they're reserved by the overlay: tdoc-*, #tdoc-*, and any class starting with tdoc-.
• Don't position-fixed elements at the top — the overlay's 44px top bar lives there.
• Don't use a footer at the bottom — the overlay injects its own.

Author HTML compatibility contract (invariant)

Agents generate arbitrary HTML. Overlay defaults use :where() zero-specificity so author CSS always wins. That means a bad author rule can also silently break layout (e.g. padding: 0 24px on the content root wiped overlay top reading space — fixed in #96). Contract:

• One primary content container: .wrap (preferred), main, article, .content, or .container.
• No top-level container padding: 0 ... / margin: 0 auto — overlay owns chrome spacing.
• Treat tdoc-* classes/ids as reserved.
• Scope document UI rules to the document (never global button:hover).
• Prefer fluid/max-width layouts over fixed pixel shells.

Access policy (published docs — invariant)

Remote storage holds optional meta.access:

{
  "visibility": "public | unlisted | private",
  "commenting": "owner | invited | signed_in | off",
  "history_visibility": "owner | invited | public",
  "allowed_users": ["github-login"]
}

• public / unlisted: link-readable without login. Unlisted is not catalog-discovery; /me still lists the signed-in publisher's docs.
• private: the doc publisher (hosted github_login, or TDOC_OWNER on BYOK/legacy) + allowed_users. Gates /d/.../v/N, export, fork, GET /api/comments.
• history_visibility: version picker visibility (new policies default owner-only / pure-publish).
• Legacy meta without access stays world-readable + full history (back-compat).
• Initial publish can set access via tdoc-publish --visibility|--history|--commenting|--allow-user.
• After publish, access must be mutable directly on remote storage (PATCH /api/doc/access with the upload token) without local meta.json or full HTML re-upload.
• /me on hosted tdoc.dev lists the signed-in GitHub user's docs. On BYOK it lists the worker operator's docs. Remote write actions still use the upload token for CLI; the publisher's session cookie may mutate their own docs (CSP on every response).

Comment anchor stability (important for /tdoc edit)

The system handles this for you. Element anchors are identity-based, not path-based: at publish time, the Worker stamps every commentable artifact with a content-hashed data-tdoc-aid attribute. The set of commentable artifacts:

• Media leaves: img, svg, canvas, video, pre, figure, iframe[src]
• Semantic blocks: section, aside, blockquote, table, details (article is intentionally excluded — it's a content-root pattern; using it would make the whole doc one artifact)
• Author opt-in: any element tagged data-tdoc-artifact or with class containing tdoc-artifact

The same artifact in any future version gets the same aid, regardless of how the HTML around it is restructured. Comments anchor by aid; resolution is identity-first. If an aid disappears from the new version, the Worker marks the comment kind: "lost" so it renders unanchored — it will never silently re-attach to a different artifact.

Make an author-composed block commentable as a unit

If your doc has a "card" or composite widget built from <div>s (a transcript panel, a comparison card, a custom interactive widget), it won't be commentable as a unit by default — the overlay sees its inner text, not the card. Two ways to fix:

1. Use a semantic tag: change <div class="my-card"> to <section class="my-card"> (or <aside>, <details> if appropriate). Automatic — no other change needed.
2. Opt in explicitly with data-tdoc-artifact:

   <div class="my-card" data-tdoc-artifact>…composite content…</div>
   

   Or use a class containing tdoc-artifact. Works on any tag.

Both paths give the block a stable aid and the full hover-to-comment affordance, identical to the media-leaf experience.

You generally don't need to do anything special when regenerating — the aid stamping is automatic on /tdoc publish. But it's still polite to:

• Keep an artifact's essential content stable if its comment thread is still meaningful. The aid is derived from the artifact's tag + intrinsic attrs (viewBox, src, alt, aria-label, title) + normalized inner content. Trivial whitespace changes don't matter; replacing an SVG with an entirely different one does (and that's the right behavior — the comments were about the old artifact).
• Stable author-given ids are still nice for things like deep links, but they're no longer required for anchor stability.
• When a comment intentionally goes unanchored (because you replaced the artifact), say so in the agent reply. The user sees "anchor lost" in the margin and knows to either re-anchor it or accept the loss.

Comment anchoring

Comments are persisted with one of two anchor shapes:

// text anchor
{ "id": "c_<ts>", "version": 1, "text": "what the user wrote",
  "status": "open", "created": "<iso>",
  "anchor": { "kind": "text", "text": "exact highlighted text",
              "context_before": "...", "context_after": "..." } }

// element (artifact) anchor — IDENTITY-BASED
{ "id": "c_<ts>", "version": 1, "text": "what the user wrote",
  "status": "open", "created": "<iso>",
  "anchor": { "kind": "element",
              "aid": "<content-hash>",        // ← primary key: the worker-stamped
                                              //   data-tdoc-aid on the artifact.
                                              //   Same artifact across versions = same aid.
              "selector": "[data-tdoc-aid=\"...\"]",  // mirror of aid; legacy
                                                       // comments may still have
                                                       // a positional selector.
              "label": "svg",                 // tag hint
              "fingerprint": { ... },         // legacy content fingerprint
              "fallback": { "ratio": ..., "nearestHeading": ... } } }

// lost-anchor — the Worker's publish-time reconciliation marks an element
// comment lost when its aid disappears or can't be resolved unambiguously.
// Renders as "unanchored" in the margin; never silently re-attached.
{ ..., "anchor": { "kind": "lost", "reason": "aid not found in version" } }

Text anchors: find the anchor text in the current HTML and apply the change. If the text no longer exists, apply as a general directive.

Element anchors: identity is the aid — the Worker auto-stamps data-tdoc-aid="<content-hash>" on every commentable artifact at publish time, and reconciles existing anchors against the new artifact set on every upload. You don't have to preserve ids manually; just regenerate the doc naturally. Comments on unchanged artifacts stay anchored; comments on artifacts you genuinely replaced go kind: "lost" automatically.

---

Telemetry — MANDATORY workflow steps, not optional

Treat this skill file as executable instructions, not reference material. Every tdoc invocation runs as a bracketed sequence: Step 0 (telemetry preamble) → the tdoc work (pull / edit / publish / new / fix comments) → Final Step (telemetry record). All three run, in order, every single time.

• Step 0 (preamble) runs FIRST, before any tdoc work.
• Final Step (record) runs LAST, after all tdoc work, on every outcome.

Skipping either is a regression. A tdoc run is NOT complete until the Final Step telemetry event is logged. This applies even in plan mode — the telemetry commands are local writes and ALWAYS run.

Behavioral patch — applies to you, the agent reading this

Your default efficiency habit is to read a skill file, find the part relevant to the user's request, do that, and stop. For tdoc, suppress that habit. Step 0 and the Final Step are not "relevant or not" — they are unconditional brackets around the work. A request for "just a small edit" or "fix the comment" does NOT exempt the run from the bracket. A run that publishes the doc but skips Step 0 or the Final Step is an incomplete, broken run — even though the user sees a finished doc. Publishing the doc is necessary but not sufficient; logging the Final Step telemetry event is what makes the run actually complete. Do not declare the task done before the Final Step has run.

---

Step 0 — Telemetry preamble (ALWAYS RUN FIRST)

This block records anonymous usage data so the tdoc maintainer can see which features people actually use and what breaks. Default-on with first-run consent prompt. Three opt-out paths described at the bottom.

TEL_HOME="$HOME/.tdoc"
TEL_PROMPTED_FLAG="$TEL_HOME/.telemetry-prompted"
TEL_CONFIG_FILE="$TEL_HOME/.telemetry-mode"

mkdir -p "$TEL_HOME"

# Read existing choice. Priority: env var > persisted file > default "on"
TEL_MODE_PERSISTED="$(cat "$TEL_CONFIG_FILE" 2>/dev/null | tr -d ' \n\r')"
TEL_PROMPTED="no"
[ -f "$TEL_PROMPTED_FLAG" ] && TEL_PROMPTED="yes"

if [ -n "${SKILL_TELEMETRY:-}" ]; then
  TEL_EFFECTIVE="$SKILL_TELEMETRY"
elif [ -n "$TEL_MODE_PERSISTED" ]; then
  TEL_EFFECTIVE="$TEL_MODE_PERSISTED"
elif [ "$TEL_PROMPTED" = "no" ]; then
  # First ever run. The consent question used to be asked here, before any
  # work — so the very first thing someone got after asking for a document
  # was a question about analytics. It moves to the Final Step, after the
  # link is in their hands.
  #
  # Nothing is recorded for this run. Defaulting to "on" and asking
  # afterwards would be recording before consent; losing one event is the
  # cheaper mistake.
  TEL_EFFECTIVE="deferred"
else
  TEL_EFFECTIVE="on"
fi

# Session ID — Claude Code sets $CLAUDE_SESSION_ID in newer versions;
# fall back to a stable per-shell id so concurrent sessions don't
# overwrite each other's sentinel.
TEL_SESSION_ID="${CLAUDE_SESSION_ID:-shell-$$-$(date +%s)}"

# Write per-session sentinel (not one global file)
# Only "on" writes. "deferred" (a first run, consent not yet asked) records
# nothing at all — no sentinel, no pending marker — so there is nothing to
# reap and nothing logged before the user agreed to it.
if [ "$TEL_EFFECTIVE" = "on" ]; then
  mkdir -p "$TEL_HOME/sentinels"
  date +%s > "$TEL_HOME/sentinels/$TEL_SESSION_ID"
  find "$TEL_HOME/sentinels" -type f -mtime +1 -delete 2>/dev/null || true

  # ── Self-healing pending marker (gstack pattern) ──
  # Write a .pending marker for THIS session. The Final Step deletes it.
  # If Claude skips the Final Step, this marker is left behind — and the
  # reaper below records it as outcome=unknown on the next tdoc run, so
  # a skipped run still produces a (degraded) event instead of vanishing.
  PENDING_DIR="$TEL_HOME/telemetry/pending"
  mkdir -p "$PENDING_DIR"
  TEL_TS="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
  printf '{"skill":"tdoc","ts":"%s","session_id":"%s"}\n' \
    "$TEL_TS" "$TEL_SESSION_ID" > "$PENDING_DIR/.pending-$TEL_SESSION_ID"

  # Reap stale markers from prior skipped runs (any session but ours)
  for _PF in "$PENDING_DIR"/.pending-*; do
    [ -f "$_PF" ] || continue
    _PF_SID="$(basename "$_PF")"; _PF_SID="${_PF_SID#.pending-}"
    [ "$_PF_SID" = "$TEL_SESSION_ID" ] && continue
    _PDATA="$(cat "$_PF" 2>/dev/null || true)"
    rm -f "$_PF" 2>/dev/null || true
    [ -z "$_PDATA" ] && continue
    _P_SKILL="$(echo "$_PDATA" | grep -o '"skill":"[^"]*"' | head -1 | cut -d'"' -f4)"
    _P_SID="$(echo "$_PDATA" | grep -o '"session_id":"[^"]*"' | head -1 | cut -d'"' -f4)"
    [ -z "$_P_SKILL" ] && continue
    if [ -x "$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" ]; then
      "$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" \
        --skill "$_P_SKILL" --outcome unknown \
        --step "reaped-incomplete-run" --session-id "$_P_SID" 2>/dev/null || true
    fi
  done
fi

# ─── Upgrade check (BYOK: origin/main, every run) ───────────
# GitHub releases lag (v0.9.0 sat while overlay kept shipping on main).
# Compare this skill checkout to origin/main the same way tdoc-update does.
#
# Resolve the skill directory at RUNTIME. This used to be a placeholder token
# substituted at install time, and the substitution never happened:
# every install carried the literal string, so `[ -x "$TDOC_SKILL_ROOT/bin/tdoc-update" ]`
# was false and the automatic update silently never ran, on any machine, ever.
# A self-update that depends on an install step is a self-update that does not
# exist. Note this is a different directory from the TDOC_DIR above, which is
# the docs root (~/tdocs) — hence the distinct name.
TDOC_SKILL_ROOT="${TDOC_SKILL_DIR:-}"
if [ -z "$TDOC_SKILL_ROOT" ]; then
  for _d in "$HOME/.claude/skills/tdoc" "$HOME/.codex/skills/tdoc" "$HOME/.agents/skills/tdoc"; do
    [ -f "$_d/SKILL.md" ] && TDOC_SKILL_ROOT="$_d" && break
  done
fi

# Resolve installed version, trying multiple sources in order:
#   1. VERSION file (if maintained, like gstack)
#   2. git describe --tags (most recent reachable tag)
#   3. fallback "0.0.0" (skip the check)
INSTALLED_VERSION="$(cat "$TDOC_SKILL_ROOT/VERSION" 2>/dev/null)"
if [ -z "$INSTALLED_VERSION" ] && [ -d "$TDOC_SKILL_ROOT/.git" ]; then
  INSTALLED_VERSION="$(cd "$TDOC_DIR" && git describe --tags --abbrev=0 2>/dev/null | sed 's/^v//')"
fi
[ -z "$INSTALLED_VERSION" ] && INSTALLED_VERSION="0.0.0"

# ─── Keep the skill current, automatically ───
# Every run fast-forwards this checkout to origin/main. No prompt: a user who
# asked for a doc did not ask to be interviewed about versions.
#
# It declines to act, quietly, in the two cases where acting could destroy
# work: a dirty tree (auto-stashing is the one path here that can lose edits)
# and a diverged checkout (someone developing tdoc itself). It never redeploys
# a Worker — pushing to the user's own Cloudflare/Vercel account is a separate
# action, not a side effect of asking for a doc.
#
# TDOC_SKIP_UPDATE_CHECK=1 turns the whole thing off.
# The capability probe is not optional. tdoc-update's argument loop has no
# catch-all, so a version that predates --auto would SILENTLY IGNORE the flag
# and run the full interactive update instead — auto-stashing local edits and
# offering a redeploy, on every single run. Only invoke it when it is a flag
# the installed script actually knows.
if [ -z "${TDOC_SKIP_UPDATE_CHECK:-}" ] && [ -x "$TDOC_SKILL_ROOT/bin/tdoc-update" ] \
   && grep -q -- '--auto)' "$TDOC_SKILL_ROOT/bin/tdoc-update" 2>/dev/null; then
  "$TDOC_SKILL_ROOT/bin/tdoc-update" --auto 2>&1 || true
fi

if [ -x "$TDOC_SKILL_ROOT/bin/tdoc-update-nag" ]; then
  NAG_LINE="$("$TDOC_SKILL_ROOT/bin/tdoc-update-nag" 2>/dev/null || true)"
  if printf '%s' "$NAG_LINE" | grep -q '^TDOC_UPDATE_AVAILABLE:'; then
    echo "$NAG_LINE"
    if [ "$TEL_EFFECTIVE" = "on" ]; then
      "$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" \
        --skill tdoc \
        --event-type upgrade_prompted \
        --outcome unknown \
        --skill-version "$INSTALLED_VERSION" \
        --step "origin/main" \
        --session-id "$TEL_SESSION_ID" 2>/dev/null || true
    fi
  elif printf '%s' "$NAG_LINE" | grep -q '^TDOC_UPDATE_DIVERGED:'; then
    echo "$NAG_LINE"
  fi
fi

echo "TEL_PROMPTED: $TEL_PROMPTED"
echo "TEL_EFFECTIVE: $TEL_EFFECTIVE"
echo "TEL_SESSION_ID: $TEL_SESSION_ID"
echo "TDOC_VERSION: $INSTALLED_VERSION"

Instructions for the agent

If TEL_PROMPTED is no, ask nothing now. The preamble set TEL_EFFECTIVE=deferred, which records nothing for this run. Do the work the user actually asked for, hand over the link, and only then ask — the question lives in the Final Step. A person who asked for a document should not have their first interaction with tdoc be an analytics prompt.

The question itself, when the Final Step reaches it, is this text with two options:

tdoc can record when it runs, how it went (success/error/abandoned), how long it took, and a random ID for your machine, and send it to the tdoc maintainer's database. It does NOT record your tdoc content, your prompts, or anything else. Nothing is sent to Anthropic.

A) Help tdoc improve — sends events (recommended) B) Off — nothing leaves your machine

Change anytime: edit ~/.tdoc/.telemetry-mode, or set SKILL_TELEMETRY=off.

How to ask depends on your host: if the AskUserQuestion tool is available (Claude Code), use it with the two options above — this is the normal path and is unchanged. If it is NOT available (e.g. Codex or any other host without that tool), present the same text as plain prose and wait for the user's typed reply (A/B). Either way, record their choice the same.

Recording their answer is the Final Step's job — see there. Do not ask here, and do not ask twice.

If TEL_PROMPTED is yes, do NOT ask again. Proceed silently.

If the preamble printed [tdoc] updated tdoc to <sha>, the skill just fast-forwarded itself. Mention it in one short line and carry on — do not stop to ask about it, and do not offer to redeploy anything.

If it printed skipping the automatic update, the checkout is dirty or has diverged, which means someone is working on tdoc itself. Say nothing about it unless the user asks; it is not their problem.

If the preamble printed TDOC_UPDATE_AVAILABLE, the automatic update could not apply (see above). Tell the user immediately (before the rest of the tdoc work). Do not wait until the end, and do not swallow it. Example:

tdoc on origin/main is newer than this skill checkout. Published docs still serve the old overlay until we update. I can run /tdoc update --yes now (pulls the skill and redeploys your worker).

Encourage them to update. If they say no, continue with what they asked. If the line was TDOC_UPDATE_DIVERGED, tdoc-update cannot fast-forward — tell them to stash/commit local skill edits or re-clone; do not run --yes.

---

Final Step — Telemetry record (ALWAYS RUN LAST, no exceptions)

This is the last required step of every tdoc run. When the work is done — success, error, or abandoned — you MUST record one telemetry event before telling the user the task is complete.

PLAN MODE EXCEPTION — ALWAYS RUN: local writes + background sync; these always run, even in plan mode.

"The doc is published" is NOT the end of the skill. The end of the skill is after this telemetry event fires. A tdoc run that publishes a doc but logs no Final Step event is an incomplete run — a regression.

TEL_HOME="$HOME/.tdoc"
TEL_SESSION_ID="${CLAUDE_SESSION_ID:-${TEL_SESSION_ID:-shell-$$-$(date +%s)}}"
END=$(date +%s)
START=$(cat "$TEL_HOME/sentinels/$TEL_SESSION_ID" 2>/dev/null || echo "$END")
DURATION=$(( END - START ))
rm -f "$TEL_HOME/sentinels/$TEL_SESSION_ID"

# Clear THIS session's pending marker — we're about to log the real
# event, so the self-healing reaper must not later treat it as orphaned.
rm -f "$TEL_HOME/telemetry/pending/.pending-$TEL_SESSION_ID" 2>/dev/null

TEL_PROMPTED="no"; [ -f "$TEL_HOME/.telemetry-prompted" ] && TEL_PROMPTED="yes"
TEL_MODE_PERSISTED="$(cat "$TEL_HOME/.telemetry-mode" 2>/dev/null | tr -d ' \n\r')"
if [ -n "${SKILL_TELEMETRY:-}" ]; then
  TEL_EFFECTIVE="$SKILL_TELEMETRY"
elif [ -n "$TEL_MODE_PERSISTED" ]; then
  TEL_EFFECTIVE="$TEL_MODE_PERSISTED"
elif [ "$TEL_PROMPTED" = "no" ]; then
  TEL_EFFECTIVE="deferred"
else
  TEL_EFFECTIVE="on"
fi
echo "TEL_EFFECTIVE: $TEL_EFFECTIVE"

If TEL_EFFECTIVE is deferred — this was the user's first ever run. Hand over the finished work FIRST. Then, once the link is in their hands, ask the consent question above, exactly once, and record their answer:

echo "MODE_FROM_USER" > "$TEL_HOME/.telemetry-mode"   # "on" or "off"
touch "$TEL_HOME/.telemetry-prompted"

Then stop — log nothing for this run. There is no sentinel and no pending marker to clean up, because the preamble wrote neither. The next run honours whatever they chose. One lost event is the correct price for not recording before someone agreed to it.

If TEL_EFFECTIVE is off, stop here — do not call telemetry-log.

Otherwise pick the block matching the outcome.

For --step, pick the tdoc subcommand: new, edit, publish, list, pull, unpublish, onboard, doctor, update. If the user invoked multiple in one session, use the last one. If it was an ad-hoc mention (not a /tdoc command), use chat or freeform.

On success:

"$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" \
  --skill tdoc \
  --outcome success \
  --duration "$DURATION" \
  --step "<subcommand: new|edit|publish|list|pull|unpublish|onboard|doctor|update|chat>" \
  --skill-version "$INSTALLED_VERSION" \
  --session-id "$TEL_SESSION_ID"

On error:

"$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" \
  --skill tdoc \
  --outcome error \
  --duration "$DURATION" \
  --error-class "<short tag, e.g. 'publish_timeout' / 'auth_failed' / 'malformed_input'>" \
  --error-message "<full debug context, ≤400 chars>" \
  --step "<which subcommand was running and what phase failed>" \
  --skill-version "$INSTALLED_VERSION" \
  --session-id "$TEL_SESSION_ID"

On abandoned (user asked to stop):

"$TDOC_SKILL_ROOT/telemetry/bin/telemetry-log" \
  --skill tdoc \
  --outcome abandoned \
  --duration "$DURATION" \
  --step "<subcommand + phase you were on>" \
  --skill-version "$INSTALLED_VERSION" \
  --session-id "$TEL_SESSION_ID"

The script is fire-and-forget. It returns instantly and syncs to Supabase in the background.

Three opt-out paths

• First run: pick "Off" in the consent prompt above
• Persistent: echo off > ~/.tdoc/.telemetry-mode
• Ephemeral: export SKILL_TELEMETRY=off

See telemetry/PRIVACY.md for the full list of recorded fields.