# Dovod

> Structured AI-driven research sessions. Design research structures, conduct interactive Q&A sessions, manage tasks, build visual roadmaps, create cross-referenced knowledge entries, and track progress.

## Data Model

```
Team — owns researches; a member's role (viewer / editor / owner) is the whole access model
  |-- Template (no short code) — a kickoff methodology, read once before a research exists; global or a team's. Addressed by slug
  |
Research (R1, R2...) — statuses: active, completed, archived; records template_slug + template_version when started from one
  |-- Section (S1, S2...) — logical topics within a research; may declare `field_spec`, the typed fields its documents record
  |     |-- Entry (E1, E2...) — markdown or block documents with findings; `metadata` holds the values for the fields its section declares
  |
  |-- Session (SS1, SS2...) — interactive Q&A interview (multiple per research)
  |     |-- Question (Q1, Q2...) — structured prompts with answers
  |
  |-- Task (T1, T2...) — todo items for tracking work
  |
  |-- Roadmap (RM1, RM2...) — visual graphs for learning paths, strategy maps, step-by-step guides
  |     |-- Node (N1, N2...) — graph nodes with type, status, and content
  |     |-- Edge — directed connections between nodes with labels
  |
  |-- Share (no short code) — a revocable, read-only link over this research; token, never a person
  |
  |-- Skill (no short code) — a methodology document the research follows: built-in, team library, or private to one research. Addressed by slug
  |
  Entry --> Revision (1, 2, 3... — numbers, not short codes) — a snapshot per write: who wrote it, in which session, what changed
  Entry --> View checkpoint (personal, no short code) — the last numbered revision one reader actually saw; server-side web UI state, never MCP, export or share data
  Entry --> Annotation (A1, A2...) — a person's mark on one sentence: verify / dig / disagree, open → answered → closed | dismissed. Anchored by block id + quote; created only from the web, answered by you, closed only by them
  Entry -?-> Session — optional link (session_id tracks which session produced the entry)
  Entry --[[E3]]--> Entry — cross-references form a knowledge graph
  Entry --[[RM1]]--> Roadmap — cross-references to roadmaps and nodes
```

Cross-references work in entry content, question text, question answers, task results, and session notes. They are rendered as clickable links in the web UI and stored in the `crossrefs` table for graph queries.

Entries come in two kinds, chosen with `entry_type`: `markdown` (default) and `blocks` — an article of typed blocks (paragraph, heading, list, table, quote, code, mermaid, checklist, task_ref, transcript, callout, divider, image, html) that mixes prose with alerts and custom visuals. The `html` block holds a self-contained HTML document rendered in a sandboxed iframe at full height, for charts and interactive layouts; `entry_type: artifact` is sugar for a document holding one of them. See [Block Documents](/llms/blocks.md).

Content supports Mermaid diagrams via fenced code blocks with `mermaid` language. All Mermaid diagram types are supported (flowchart, sequence, class, state, ER, Gantt, pie, mindmap, timeline, etc.). Diagrams are rendered as interactive SVG in the web UI — pan, zoom, fullscreen, and a link that reopens the diagram in mermaid.live. In a `blocks` document use the `mermaid` block (`{ code, caption? }`); a `code` block with `language: "mermaid"` is accepted as the same thing. See [MCP Client Guide](/llms/mcp-client-guide.md) for examples.

| Syntax | Target | Example |
|--------|--------|---------|
| `[[E3]]` | Entry in same research | Links to entry E3 |
| `[[R2:E5]]` | Entry in another research | Links to entry E5 in research R2 |
| `[[R2]]` | Research | Links to research R2 |
| `[[RM1]]` | Roadmap | Links to roadmap RM1 |
| `[[RM1:N3]]` | Roadmap node | Links to roadmap RM1 (node N3 context) |

A research can have **multiple sessions** (e.g. initial exploration, deep-dive, follow-up). Each session has its own set of questions. Sessions are displayed grouped in the mindmap and listed on the research detail page.

Reopening a research in a new chat is two calls, not a walk of the tree. `research_get` carries the constraints — `memory`, the sections and their declared fields, the skills index — and `research_resume` carries the work still open: tasks, the selected session's unanswered questions, the marks a person left split into what you may do and what only a person can accept, the documents changed most recently with who wrote the newest revision, and at most three candidate next actions each carrying the fact it was derived from. It is read-only and writes nothing, every group says how much it left behind, and with several sessions active it returns them and asks rather than guessing. There is no share equivalent: what is unfinished is working process, like private skills. The Conducting Research guide holds the sequence.

Ownership is a team's, not a creator's: a research you can read may still refuse your writes, because your role in the owning team is `viewer`. `research_list` marks those with `access: "read-only"` (and a shared research with `team`); `research_get` returns your `role`. A non-member gets `not found`, a member without the right gets `your role in this team does not allow this`. With `auth_enabled: false` there is no caller and no check, and nothing is ever read-only. Details in the MCP Client Guide and the Domain Guide.

A research can also be handed out as a **read-only share link** — a revocable token over one research, read via REST under `/api/shared/{token}/…` by someone who never signs in. There is no MCP tool for it: creating a link, changing what it shows and revoking it are human acts done in the web UI or over REST, and nothing about the tool list changes because of it. The Domain Guide holds the routes, the include flags and what a visitor is never shown.

## Docs

- [MCP Client Guide](/llms/mcp-client-guide.md): Practical guide for AI assistants interacting via MCP tools. Covers all 52 tools, the input-schema contract (nearly every property is required, which ones accept `null`, the thirteen tools that let you omit one, the two that take no input at all, and the two whose schema requires nothing because the skill they act on can be addressed two ways), what your team role lets you write and how a refusal reads, content formatting (newlines, markdown, cross-references), entry types, roadmap node types, entity references, common pitfalls, and where short codes are accepted. Start here if you are an MCP client.
- [Domain Guide](/llms/domain-guide.md): Complete reference for every entity (Team, Research, Share, Section, Entry, personal Entry View state, Session, Question, Task, Roadmap, Revision, Annotation, CrossRef, Skill, Template). Describes fields, statuses, relationships, lifecycle, and when to use each entity. Holds the role matrix, the link-based invitation flow, research transfer and the team REST routes, the read-only share link — its owner and visitor routes, the four include flags, the in-place edit that changes what a live link shows without changing its address, the knowledge graph a visitor reaches with the node types the flags withhold left out, and everything a visitor is never shown — the personal new/changed document queue, its exact-revision acknowledgement routes and its separation from MCP and shares — the read-only continuation summary on the research: its groups and their totals, why it refuses to pick between two open sessions where `research_get` picks arbitrarily, and the size cap — tagging strategy and cross-reference syntax, and the real-time event stream at `/ws` — how to connect and authenticate, the event envelope including the `parent_id` / `parent_code` pair an annotation event carries so a document page can tell whether the mark is one of its own, every event type including the reader-directed `entry_view.updated`, who each one reaches, and how a client recognises its own writes.
- [Conducting Research](/llms/conducting-research.md): Step-by-step guide on how to initialize, conduct, and complete a research project. Checking a methodology before you design a structure, checking you may write before you interview, the interview workflow, entry creation with cross-references and with the fields the target section declares, working the annotations a reader left on the text as a scoped pass, task tracking, roadmap creation, and best practices. Holds the continuation path — `research_resume` after `research_get` when a new chat opens on a research that is already running, what its `actor`, `has_more` and `author_kind` fields oblige you to do, and the two things it is deliberately not.
- [Tasks](/llms/tasks.md): Guide to using tasks for tracking work items, action items, and outcomes within a research. When to create tasks, statuses, priorities, tasks vs questions, projecting a task into a `blocks` document as a `task_ref` block (which references it rather than copying it, so a tick there is a status change), and best practices.
- [Roadmaps](/llms/roadmaps.md): Guide to building visual directed graphs — learning paths, strategy maps, decision trees. When to create roadmaps, node/edge types, custom statuses by domain, the three layouts (graph / stages / timeline) and the roadmap `view`/`stages` and node `stage`/`node_date`/`node_end_date` fields that drive them (timeline range bars with a Month/Quarter/Year zoom), how to build a graph step by step, and best practices.
- [Block Documents](/llms/blocks.md): The `blocks` entry type — the JSON document shape, the catalog of all 14 block types with every field and cap, how text fields carry inline markdown and cross-references, the sandboxed `html` block, title/description derivation, the `artifact` alias, and what export and import do with a block document. Read this before writing an entry with `entry_type: blocks`. Blocks can be edited one at a time with `entry_patch` (addressed by block id, strict and atomic), and a stable block id is what two things a person made hang off: the ticks in a `checklist` block, and the annotations anchored to a sentence — which is why a write reports the ticks it lost and the marks it drifted or orphaned. Two blocks point outside the prose: `task_ref` projects existing tasks as a checklist whose ticks are status changes on the tasks, and `transcript` stores a conversation held outside the tool as turns indexed with their speakers.
- [Writing an Artifact](/llms/artifacts.md): How to author the HTML document that goes inside an `html` block — when a finding deserves one, what the sandbox grants and withholds, why the document must size itself instead of the viewport, how the read-only `researchData` bridge arrives and why it may be absent, and the style the host expects. **Write one theme and hard-code it**: an artifact carrying both a light and a dark palette flips to the light one when printed and prints dark text on the dark surface behind the frame. Read this before writing an `html` block or an `artifact` entry.
- [Document Metadata](/llms/metadata.md): A section can declare the typed fields its documents record (`field_spec` on `section_update`), and an entry carries the values (`metadata` on `entry_create` / `entry_update`). The vocabulary is closed — an undeclared key is dropped and reported — and a section that declares nothing accepts none, which is the normal case. Covers the six field types and the caps, the eleven reserved keys, why `null` is an explicit unknown that answers a required field and guessing is the failure this guards against, the `metadata_report` no write is refused for except the markdown import, which is strict because a person is standing over the file, the single `completed` gate and its `allow_incomplete` override, how a declaration change ages documents without rewriting them, and what the exports, revisions and share links do with it. Read this before writing an entry into a section whose `field_spec` came back non-empty — and before deciding a fact belongs in `tags`.
- [Templates](/llms/templates.md): A template is a kickoff methodology the model reads, not a skeleton the code clones — it carries no sections and no questions, only the criteria an agent matches on and a markdown body saying what to ask before proposing anything, what structure to suggest, and when the research is finished. `template_list` then `template_get`, and pass `template_slug` to `research_create` to record which methodology was followed and attach the skills it names. Covers the twenty-five that ship and the skills each attaches, the two tiers (global and team, with no third) and the two kinds of global — what ships in the binary and what the operator of the instance added through `POST /api/templates`, which the boot-time refresh must never overwrite — how a fork shadows its parent, why asking before offering one matters, the nine REST routes with their conflict codes including `operator_required`, and why "save as template" returns a skeleton rather than a capture.
- [Skills](/llms/skills.md): A skill is a methodology document the agent opens when it decides it needs it — how to run an interview, how to grade a source. `research_get` lists each skill's name and a line saying when to use it — including the four product skills, which are on without being attached, so the index is never empty; `skill_load` returns one body, one slug per call, and is the only tool that returns a body — ten skill tools in all, the other nine attaching, writing, editing, forking, copying, promoting and deleting them over the same service the web UI uses. Covers the three tiers (research-private, team, built-in) and the fact that **the tier order is the precedence**, the trigger-shaped description that decides whether a skill is ever opened, why product skills are never counted against the six-skill budget and cannot be detached, the thirteen REST routes and ten MCP tools that attach, write, fork, copy and promote them, the conflict codes both answer with, and why a share link never exposes one.
- [Annotations](/llms/annotations.md): A person reads a document, reaches a sentence they do not believe, and marks it — `verify`, `dig` or `disagree`. You read that queue with `annotation_list` and record what you did with `annotation_answer`; there is deliberately no tool that creates a mark and none that closes one, because a mark is a person pointing and only a person accepts the work. Covers the border with provenance (a mark is a request for work, not a record of what we know), the input contract of both tools, the four anchor states the server computes on every read — including `orphaned`, which means the paragraph somebody doubted was rewritten and is a finding rather than a broken row — the `annotation_report` an entry write produces when it drifts or buries a marked sentence and where that report can and cannot be read, how a pass is scoped and accepted, and why a mark you cannot settle becomes a question instead of a third attempt.
- [Revisions](/llms/revisions.md): Every write to an entry leaves a numbered snapshot — who wrote it (agent, human, import, restore), during which session, and what changed. Covers `entry_history` and `entry_diff`, what does and does not create a revision (a checkbox tick does not), how restoring works, the roll-up of what a whole session changed, and how an orphaned annotation is investigated by diffing from the revision it was anchored to. Read the history before rewriting an entry another session wrote.
- [Export](/llms/export.md): How to export a whole research or a single session as markdown or PDF, one document as a `.md` file with YAML front matter (`GET /api/entries/{id}/markdown` — no MCP tool, no share equivalent, and `[[E3]]` left exactly as stored because a loose file has no siblings to resolve it against), a whole research as an Obsidian vault (`?format=obsidian` — a zip of folders and linked notes, with `research_export` returning the download link and its options), or as portable JSON for moving a research to another server — and the other direction: one markdown file dropped into a section (`POST /api/sections/{id}/import/preview` then `POST /api/sections/{id}/import`, no MCP tool because an agent writes with `entry_create`), with the three closed front matter key sets, the caps, the five refusals, and the round-trip contract that keeps title, description, status, tags and metadata while codes and cross-references deliberately do not survive. Endpoint reference, web UI export pages, which team a portable import lands in, how block documents — including an `html` block — are carried through each export, how a section's declared fields render (a labelled block in markdown, front matter after the eleven system keys in the vault, with unanswered fields written as `null` so a vault query can find them), and what the export looks like through a share link.
- [REST API — OpenAPI Specification](/api/openapi.yaml): OpenAPI 3.1 description of every REST route this server registers — the reads and writes, teams and invitations, research transfer, skills, templates, annotations, revisions and restore, exports and both imports, search, graph, links, block patching, the per-document markdown download, the personal document-update queue, the share-link owner routes and the OAuth2 endpoints. It is generated from the route registrations rather than maintained beside them, so it can no longer fall behind the router; the same document is served as YAML at `/api/openapi.yaml` and as JSON at `/api/openapi.json`, and a client picks whichever it can parse. A person reading in a browser can open the same document rendered at `/api-docs` on this instance, which needs no sign-in; that page is an application that fetches the JSON itself, so an assistant fetches one of those two URLs and not the page. It also describes authentication, which the guides above only mention in passing: `bearerAuth` — a JWT from `POST /api/auth/login`, an API key from `POST /api/auth/api-keys`, or an OAuth2 access token from `POST /auth/token`, the three interchangeable on every route — and `operatorToken`, the instance `api_token`, which the server-wide template routes accept in place of a person. **Fetch it from the instance you are talking to**: it is built from that server's configuration, so where accounts are disabled the writes are documented as open and the OAuth endpoints are absent entirely; its `servers` entry is the relative `/` unless the operator configured `base_url`, so its paths resolve against wherever you fetched it from. The one surface it gives in prose rather than as paths is the share visitor's, under `/api/shared/{token}/…`, which mirrors the authenticated paths with the token in front — the Domain Guide holds that list. Read it if you are a non-MCP client, or when you need an exact request or response shape the guides above do not spell out.