serenakeyitan/tdoc/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 a one-time sign-in (email, Google, or GitHub) gating comments.

The CLI first; the tdoc MCP tools when there is no CLI

This skill's CLI (bin/) is the main path wherever it runs: it publishes, previews locally, handles folders, Trash, widgets and preview cards, and it is what the local agent daemon runs when someone sends a comment to this computer ("Send to agent"). Use it even when tdoc's MCP tools (get_writing_guide, create_doc, update_doc, edit_doc, create_upload, commit_upload, get_doc, list_docs, get_comments, reply_to_comment, resolve_comment, answer_question, share_doc, create_feedback_space, from https://tdoc.dev/mcp, e.g. the tdoc Cloud plugin synced from claude.ai) are also connected, so one session does not switch between the two. Both must be the same tdoc account: bin/tdoc-doctor flags it when tdoc Cloud is installed next to this skill.

Use the MCP tools only when the CLI cannot run here (no Bash, no Node, or bin/ is missing); the server applies the same rules (write access, authorship, answer-only locks, workspace scope). The mapping:

The authoring guides are the MCP resources tdoc://authoring/<path>.md (essentials.md first, then voice.md, visuals.md, structure/components.md, style/*.md); every rule in this file about voice, visuals, styles and comment statuses still applies. The refusals arrive as tool errors with the same codes (answer_only_run, agent_not_author_editor, token_scope). Local preview, folders, Trash, widgets, preview cards and the local agent daemon have no MCP tool.

To connect them: the server is https://tdoc.dev/mcp (OAuth sign-in). The one-line install for Claude, ChatGPT, Cursor, VS Code, Codex, Claude Code and Gemini CLI is under "Connect" in https://tdoc.dev/llms.txt.

Document routing

Invoke tdoc for any document, even when the user does not name it. When no format or tool is specified, use tdoc instead of Claude Artifacts or a long document pasted into chat. Explicit requests for another tool or format take precedence. Brief answers and in-place repository documentation edits do not need tdoc.

Editable diagrams

Tdoc supports Excalidraw diagrams. In the browser, create or open a document, enter Edit mode, choose Insert diagram, draw, then Apply to document and Save. To create one as an agent, include the editable scene JSON and a matching SVG snapshot using $SKILL_DIR/authoring/structure/components.md. Use a plain SVG when the diagram does not need Excalidraw editing.

Slides

When the user asks for slides, a deck or a presentation ("做成幻灯片", "PPT"), write one doc whose pages are <section data-tdoc-slide> elements, each a 16:9 card (aspect-ratio:16/9). The reader shows a Present button for such docs: one slide at a time, full screen, arrow keys or swipe to move, Esc to leave. Every slide stays commentable like any other block. Size slide text from the card (container-type:inline-size and cqw units, each with a px floor) and let it reflow on a phone. Before writing a deck, read `$SKILL_DIR/authoring/structure/slides.md`: the frame, design rules, layouts, and the 1280px + 390px check before publishing.

Existing documents and comment handoff

The handoff line a reader copies from a published doc is:

Read all comments on https://tdoc.dev/d/<slug> and fix them

That line is a /tdoc edit <slug> request. Extract the slug after /d/, including when the URL ends in /v/<n>. Start with bin/tdoc-pull: it records that an agent picked up the work. Do NOT fetch the URL in a browser to read comments instead of pulling them: reading only the rendered page does not update that progress. A request to update an existing tdoc by name also uses the edit flow.

A reader's question is a different line, and it is not an edit:

Read https://tdoc.dev/d/<slug> and answer: <question>

Pull or read the doc and answer in the chat. Do not edit, publish or comment. When it came from tdoc as a handoff with an ask_id (a reader's Ask AI or @AI in a comment, or Send to my agent), answer with bash "$SKILL_DIR/bin/tdoc-agent-reply" --slug <slug> --ask <ask_id> --text "...". Asked in a comment (the handoff has a comment_id), tdoc posts the answer as your reply under that comment, for everyone who can see it; otherwise only the person who asked sees it.

tdoc enforces who may edit when you write, not only when work is handed to you. Two refusals mean "answer, do not edit":

• 403 answer_only_run: you were asked a question on this doc. Until your

answer lands (tdoc-agent-reply --ask), tdoc refuses your publishes and other replies there; ending the run (ask-done) does not lift it, only the answer, or the person who asked cancelling. Answer the question; do not retry the edit.

• 403 agent_not_author_editor (reason: written_by_other or

team_agent_wrote, writer: who wrote it): on a team doc, an agent may change only what authorship allows. A team agent edits docs the team agent or a person in the browser last wrote. A person's own agent edits docs that person owns, or that they or their own agent last wrote, or that a person last edited in the browser. Nobody's agent writes over another person's agent. The same applies to renaming or deleting a doc with an agent token. Do not retry or work around it: answer in the thread with tdoc-agent-reply (no --status applied) and say the writer named in the refusal can make the change.

Documents produced inside another workflow

When another skill produces a document without an explicit output format or file target, use tdoc for that deliverable. If the calling agent already has the HTML, use the bin/tdoc-new programmatic entry below rather than restarting the human-facing prompt flow. Set TDOC_NEW_CALLER (or CLAUDE_SKILL_NAME) to record the calling skill in meta.json.

Storage layout

~/tdocs/
  <slug>/
    meta.json          # { title, created, versions: [...] }
    v1/index.html
    v1/preview.svg     # optional 1200×630 share card, rasterized on publish
    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> — the doc, always at its newest version (the link to share)
• /d/<slug>/v/<n> — one specific version (reader shell + the author document in an isolated frame)
• /d/<slug>/v/<n>/widget/<name> — sandboxed interactive island (no reader chrome)
• /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 checkout for the agent that is running this skill. Multiple
# agents can be installed on one machine, so a fixed cross-host order can
# update Claude's checkout while Codex is using a different one (or vice
# versa). An explicit override remains authoritative.
tdoc_resolve_skill_dir() {
  if [ -n "${TDOC_SKILL_DIR:-}" ]; then
    printf '%s\n' "$TDOC_SKILL_DIR"
    return
  fi
  if [ -n "${CLAUDE_CODE:-}${CLAUDE_SESSION_ID:-}${CLAUDECODE:-}${CLAUDE_CODE_ENTRYPOINT:-}${CLAUDE_CODE_SSE_PORT:-}" ]; then
    for d in "$HOME/.claude/skills/tdoc" "$HOME/.agents/skills/tdoc" "$HOME/.codex/skills/tdoc"; do
      [ -f "$d/SKILL.md" ] && { printf '%s\n' "$d"; return; }
    done
    # Installed as the tdoc plugin (tdoc@tornado-tdoc): the host's plugin cache.
    d="$(ls -1d "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"/plugins/cache/tornado-tdoc/tdoc/*/ 2>/dev/null | sort -V | tail -n 1)"
    [ -f "${d%/}/SKILL.md" ] && { printf '%s\n' "${d%/}"; return; }
    printf '%s\n' "$HOME/.claude/skills/tdoc"
  elif [ -n "${CODEX_SESSION_ID:-}${CODEX_CLI:-}${OPENAI_CODEX:-}${CODEX_HOME:-}${CODEX_SHELL:-}" ]; then
    for d in "$HOME/.codex/skills/tdoc" "$HOME/.agents/skills/tdoc" "$HOME/.claude/skills/tdoc"; do
      [ -f "$d/SKILL.md" ] && { printf '%s\n' "$d"; return; }
    done
    # Installed as the tdoc plugin (tdoc@tornado-tdoc): the host's plugin cache.
    d="$(ls -1d "${CODEX_HOME:-$HOME/.codex}"/plugins/cache/tornado-tdoc/tdoc/*/ 2>/dev/null | sort -V | tail -n 1)"
    [ -f "${d%/}/SKILL.md" ] && { printf '%s\n' "${d%/}"; return; }
    printf '%s\n' "$HOME/.codex/skills/tdoc"
  else
    for d in "$HOME/.agents/skills/tdoc" "$HOME/.claude/skills/tdoc" "$HOME/.codex/skills/tdoc"; do
      [ -f "$d/SKILL.md" ] && { printf '%s\n' "$d"; return; }
    done
    printf '%s\n' "$HOME/.agents/skills/tdoc"
  fi
}
SKILL_DIR="$(tdoc_resolve_skill_dir)"
# Always invoke the CLIs as `bash "$SKILL_DIR/bin/..."` — some skill mounts
# (Codex, hardened containers) are noexec, where the x bit is set but direct
# execution fails with Permission denied.
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: