I

Docs

Docs is a direct workspace-document viewer, review surface, and Markdown/HTML source editor. It is a normal Cloudflare TanStack Start app styled with Tailwind and the shared Iterate UI package.

A URL addresses one existing workspace and, optionally, one of its files. The file tree is the same pierre tree as the apps/os repo IDE, over the WHOLE workspace: every project repo mounted at its own repos/<name> path plus the /workspace directory, with git-status badges for the workspace's uncommitted changes and new/rename/delete/discard. Documents (.md, .markdown, .html, .htm) open in the collaborative editor; any other text file opens read-only, with change bars against HEAD in the gutter and a diff toggle (?diff=1) that shows the file's uncommitted change in CodeMirror's merge view. Each dirty repo gets its own Commit button, which publishes that mount's dirty set to the repo's main — a commit never spans mounts, and the files under /workspace are never committed. Listings load per mount: the config repo and the /workspace directory at once, any other mount when its row is opened, so a big repo costs nothing until then. The tree, file view, diff, and commit controls are the shared @iterate-com/workspace-documents components that apps/os renders too, over the same platform workspace surface. A relative path resolves under /workspace; an absolute path names a workspace file (e.g. /repos/config/docs/plan.md):

https://docs--<project>.iterate.app/?workspace=/agents/<agent>&path=review.md

The default project worker exposes the Docs connector as itx.worker.docs. Agents should ask that RpcTarget for the environment-correct production, preview, or localhost link instead of assembling a hostname:

const url = await itx.worker.docs.link({
  workspace: "/agents/reviewer",
  path: "review.md",
});
await itx.chat.sendMessage(`[Review the plan](${url})`);

Docs reads and edits the workspace overlay directly through the OS workspace capability, forwarded verbatim by its vessel (itx.workspaces.get(path): fs, git, collab). It holds no state of its own.

Review model#

  • The default Preview tab renders Markdown or workspace-authored HTML.
  • Source opens the shared CodeMirror collaborative editor. Both rich and source editing highlight fenced ts, typescript, tsx, js, javascript, and jsx blocks.
  • The comments rail always ends with Comment on the whole document.
  • Selecting rendered Markdown text creates a passage-anchored thread.
  • Threads and replies use Roughdraft Flavored Markdown (RFM): CriticMarkup passage anchors and YAML endmatter. Source is interoperable with Roughdraft.
  • Suggestions render in the preview and can be accepted or rejected.
  • Review writes are applied atomically against the source used to create them; conflicting edits preserve the comment draft for retry.
  • The old Iterate annotation format is no longer interpreted; existing source files remain editable without a compatibility parser or automatic migration.

@iterate-com/ui provides format-independent DocumentPreview, DocumentComments, and ReviewComposer components. iterate/document-review reads and edits RFM; useDocumentReview in @iterate-com/workspace-documents/review connects that source model to the UI. Docs and Tasks share this experience and its collaborative Source editor. HTML document comments use an inert JSON script containing RFM, separate from the HTML body.

Sharing a workspace#

The URL of a workspace is the thing to share: everyone on it edits the same live files, and an agent invited to it (or born with it — every agent has its own at /workspaces/agents/<agent>) reads and writes the same overlay. New workspace in the sidebar names one — pre-filled with three random words — and creates it with every project repo mounted. Each dirty repo's Commit control auto-commits about a minute after the last change unless switched off; a failed commit pauses the timer and reports the error.

Install into a project#

Docs runs behind your project's config worker, which authenticates project members and proxies to the app. The default template already installs it. If a project lacks it, hand this to the project's iterate agent (or commit it yourself to worker.ts in /repos/config); these lines are the whole integration:

import { DocsApp } from "@iterate-com/docs";
 
const docsApp = DocsApp.create(this.env, {
  auth: { policy: "project-member" },
  proxy: {
    origin: "https://docs.iterate.workers.dev",
    originOverrideKvKey: "docs-app-origin",
  },
});
 
if (app === "docs") return docsApp.fetch(request);

https://docs--<project>.iterate.app then works. More in Remote apps.

Development#

pnpm install
doppler setup --project docs --config dev_jonas --no-interactive
pnpm --dir apps/docs dev

The app's worker serves /healthz and the Cap'n Web /api; all document pages are rendered through TanStack Start routes.

Was this page helpful?

Powered by Docsbook