Docs and the knowledge graph

How it works

A doc is Markdown with a share link. Anyone can write one in the app, and any workspace's box can publish one with devbench doc create. A doc can be public (a link that works with no login) or kept inside the organization, and it can be attached to a workspace or stand on its own.

Two things turn a pile of documents into something that can be searched by a program:

Subjects file a doc under a topic. Slugs are normalized, so Security Audit, security_audit and SECURITY-AUDIT are one node rather than three synonyms nothing can be found under.

Edges say how two docs relate, relates to, follows, supersedes, derived from, answers, contradicts. This is the half a tag index cannot express: "this week's findings supersede last week's" and "this week's findings contradict last week's" are both "two docs tagged security-audit" to a tag index, and they mean opposite things to whoever has to act. supersedes in particular is what lets a reader, and the Graph view, tell a current answer from one kept for the record.

Each doc also carries a summary: one paragraph read instead of the whole body. That is not decoration. A briefing that pastes five documents into a prompt is one nobody reads, so the summary is what a scheduled run is given.

The two views answer different questions. List answers "where is that document". Graph answers "what do we know about X, and what replaced what".

Reading a doc where the work is. A doc opened while a workspace is in front (from the workspace's Docs page, a link in its chat, a task's note) opens as a tab of that workspace's own, after its Docs, so you never leave the workspace to read it. Opened from the Docs place or a link on its own, it opens there; a doc that belongs to a workspace then shows Open in workspace, which opens it as that workspace's doc tab.