---
title: "Introducing Docs: collaborative files that save as commits"
summary: "A member-only editor for the mind’s repositories, with live collaboration, text comments and durable git history."
created: "2026-11-15"
updated: "2026-11-18"
revision: "6"
previous: "d1fe80adb9f141ef54e6b51913b6397a539d2249"
reviewedThrough: "499865e6c07a5cc1c6a715609915ce4b57177046"
sourceDigest: "2cad8c3841d40c76c57564398b2a6f8369f8930be2e0c84ffe7ac9912773ea40"
---

With this, your mind can let its members write the same document together and keep the result as a file in git. There is no separate knowledge base to reconcile later: the sidebar is a repository’s file tree, and editing changes that repository. In the config repository that can publish the mind itself, which is why the member boundary matters.

## Wire existing editor parts to the repo

`apps/docs/public/app.js` uses the UI kit’s `DocEditor`, `DocTree`, `DocListPanel` and `DocSession`. It chooses the repo and file from `?repo=<name>&doc=<path>` in the URL, reads the initial text, and opens a live editing session. With no file selected it lists documents and offers a new one. `?mode=comment` offers a comment-oriented view, not an authorization mechanism: every viewer is still a member with the mind’s normal rights.

```ts
case "docs":
  return docs.open?.(request) ||
    this.auth.require(request) || docs.fetch(request, this);
// In the guarded host:
if (url.pathname === "/itx") return host.auth.itx(request);
```

The page reaches the mind through a same-host WebSocket authenticated by the platform. `apps/docs/app.ts` serves the files and a `/processors.json` answer containing the processors module path and a hash of its source. The processors live in `apps/docs/processors/`: root and document folding, collaborative frames, anchoring, merging and comments, exported through `classes.ts`. Hashing the processor source gives an editing session a versioned implementation. An unrelated content commit should not restart all processors.

## Commits are the storage contract

Live collaboration produces durable document events and saves the resulting text as repo commits. That gives ordinary git history instead of an opaque editor database as the only record. Preserve the editor’s merge and anchor logic; replacing it with last-write-wins autosave would lose simultaneous edits or detach comments. The UI should explain when a file cannot be edited, including missing dependencies or non-text content, rather than silently switching storage systems.

## Read a stored HTML note without lending it the member socket

A second path serves a different kind of document. A mind file at `/notes/sample-map.html` can be read inline at that same path on the Docs host. It is not a repository file, an editor session, or a new public page. The existing member guard runs first. `apps/docs/app.ts` intercepts paths starting with `/notes/` and delegates to `apps/docs/notes.ts`, which reads bytes through a short-lived host scope.

The accepted name has one to one hundred lowercase letters, digits or hyphens, starts with a letter or digit, and ends in `.html`. Only GET and HEAD can read it. Names outside that pattern and methods other than GET or HEAD return 404 from the note handler without reading a file. URL normalization happens before routing; paths outside `/notes/` remain ordinary app routes, never arbitrary file reads. A missing file also returns 404; unrelated storage faults propagate rather than pretending the file is missing. HEAD returns the same headers with no body.

Treat stored HTML as untrusted even when an agent wrote it. The response, not just an embedding page, supplies this policy:

```text
Content-Security-Policy: sandbox; default-src 'none'; style-src 'unsafe-inline'; img-src data:
```

This is a CSP sandbox on the document itself, not an iframe supplied by Docs. It grants neither scripts nor same-origin privileges. Inline styles and embedded data images can draw a useful static diagram; external resources are denied by the default policy. The document has an opaque origin rather than the authenticated app's authority. Keep the note static: no live chat, forms or script-driven controls. The response also sets `nosniff`, `private, no-store`, `noindex, nofollow` and `no-referrer`. Those headers supplement membership checks; robots directives alone are not access control. Serving the bytes inline is not a sanitizer or permission to publish their content.

`apps/docs/notes.test.mjs` contains route and response-header assertions. In a rebuild, run those tests and separately check actual browser enforcement, direct navigation, framing, blocked scripts and network requests, and signed-out access. Source and header inspection are not a real-browser security test. The route adds no package or vendor account beyond the existing mind-file storage and authenticated host.

## Rebuilding without opening the repo to visitors

The host, HTML, public assets and processor folder are the implementation unit; the UI kit and the collaborative-editor packages listed in the local package manifest are its dependencies. The processor packages are `yjs`, `diff` and `node-diff3`; their pinned versions join the source hash in the processor cache key. Use the pinned versions together and test two concurrent member tabs, comments, reloads, merges and a save after the repo tip moved. The editor’s shared stylesheet comes from the same tested UI-kit pin, including narrow-screen layout behavior. Verify long comment links, presence labels and mode controls on phones as well as desktop; removed local CSS workarounds are not a reason to stop testing wrapping. No external service account is required merely to edit the mind’s repos. Keep the socket and every processor action behind member authentication; publicly serving a manifest or icon must not accidentally include repository files. The [Dash](/introducing/dash) offers the wider repo view, while [the blog](/introducing/blog) deliberately publishes only reviewed descriptions rather than these private documents.
