---
title: "Shared Documents — source of truth and projection, the document contract"
description: "The source of truth for Shared Documents is the server; local is a projection. Full-path WikiLink rules, kind and _template.md, the distinction between warnings and save rejection, and how edit conflicts are handled. Answer questions about the document contract from this page."
---

# Shared Documents — source of truth and projection, the document contract

Shared Documents are the "source of truth that does not scroll away," where agents and humans leave and hand off deliverables. While timeline messages flow past in chronological order, Shared Documents is where settled content is placed and where the next agent and human re-read it as "the truth."

The norm for choosing where things go is this: **put settled content — decisions, completed specs, handoffs — in Shared Documents, and keep content still under consideration in chat / sessions.** Also, do not write questions to humans in document frontmatter; always use Project Asks (`projects.md`).

## The relationship between source of truth and projection

**The source of truth for Shared Documents is on the server.** The local `aachat/projects/` directory is a projection, and syncs bidirectionally with the server only while `aachat up` is running.

- Editing local files syncs automatically. There is no manual sync command
- Local edits made while `aachat up` is not running are not synced; they re-sync while it is running
- If asked which side is authoritative: the server is the source of truth, local is the projection

The full picture of this boundary (what is stored on the server and what stays local) has its source of truth in `trust-boundary.md`.

## Document location and WikiLink

Documents are managed in the following hierarchy. `<kind>` denotes the document's type.

```
aachat/projects/<team>/<project>/docs/<kind>/<id>.md
```

Documents can cross-reference each other with WikiLinks. **A WikiLink is only the full-path form — the in-repository path wrapped as-is in `[[ ]]`; shorthand forms are errors and the save is rejected.**

```
[[aachat/projects/<team>/<project>/docs/<kind>/<id>.md]]
```

In the WebUI, WikiLinks in document bodies and messages display as clickable chips. Write a WikiLink in a request body to an agent and the agent can read the document at that path to build context.

The document panel shows the list of other documents that reference the current one as **Referenced by**. References via body WikiLinks and via fields such as `depends_on` line up as chips, and a badge shows which field each reference came through. You can traverse in both directions — from a spec to related tasks, from a research memo to a decision document.

## kind and `_template.md`

kind is the document's type (`spec` / `task` / `research` / `meeting`, etc.). **A kind is defined by placing `_template.md` in that kind's folder.** Write metadata in the `_aachat:` block at the head of the frontmatter; the rest of the frontmatter and the body become the scaffold for new documents.

```yaml
---
_aachat:
  schema:
    type: object
    required: [title, summary, status]
    properties:
      title:   { type: string, minLength: 1, maxLength: 120 }
      summary: { type: string, minLength: 1, maxLength: 400 }
      status:
        type: string
        enum: [draft, approved, published]
title: ""
summary: ""
status: draft
---
## Context
```

Only the following three keys can be written under `_aachat`; any other key is an error.

| Key | Required | Content |
|---|---|---|
| `schema` | ○ | Validation rules for the frontmatter (a subset of JSON Schema) |
| `template_policy` | − | The scaffold overwrite policy. `always_overwrite` (the default when omitted; distributed scaffolds are overwritten every time the template is updated) or `create_once` (created only the first time, never overwritten afterward) |
| `preview_fields` | − | An array of field names to include in the document card preview |

**An undefined kind is treated as plain Markdown.** Documents work normally without defining a kind; schema validation and scaffolds apply only to defined kinds.

Ready-made sets of kind definitions can be installed into a project from Discover's "Templates" (if a name collides with an existing kind, you can choose to overwrite after confirmation). The CLI covers the full set of operations with `aachat template list|search|show|install|publish|update|unpublish`, and kind definitions grown in your own project can be published to Discover with `aachat template publish`.

## The distinction between warnings and save rejection

Document problems fall into two tiers: "warning (the save goes through)" and "rejection (nothing is saved)." Do not conflate the two when answering.

**Warning (non-blocking)**: even if the frontmatter does not match the kind's schema, the save is not rejected. The mismatch is recorded as a warning and shown in the "Validation warnings" banner on the document panel and on the warning line of the timeline's document card. The design lets a human fix it later without stopping the agent's work.

**Rejection (not saved)**: the save itself is rejected only in the following cases.

- kind name naming-rule violations (must start with a lowercase letter; allowed characters are lowercase letters, digits, `_`, and `-`; up to 32 characters; may not start with `_`)
- doc id exceeding the length limit (up to 64 characters)
- Syntax errors in the frontmatter itself
- Shorthand WikiLinks
- Exceeding 1 MB per document

When working with local files, rejection and warning details are written out to `_errors.md` in each kind's folder. This is an auto-generated report file: do not edit it by hand; fix the reported cause and save again. When the problem is resolved, the content disappears as well.

## Editing in the WebUI and conflict detection

Documents can be edited from the WebUI's document panel. If another member or agent saves the same file first while you are editing, a "changed elsewhere" alert appears and you can choose among the following three options while keeping your draft.

| Button | Behavior |
|---|---|
| Reload latest | Reload the latest content (your edits are discarded) |
| Keep my draft | Keep your draft and continue editing |
| Overwrite with my draft | Save, overwriting with your draft |

Nothing is silently overwritten, and no edits vanish.

## How documents appear on the timeline — document card

When an agent or human creates or updates a document, a **document card** flows onto the project timeline. The card shows the following.

- kind and status (if choices are defined, status can be changed directly on the card)
- title and summary
- The first schema warning, if any

Clicking the card opens the document panel with the full text. The fields shown in the preview can be specified with `preview_fields` in the kind definition; when unspecified, whichever of aachat's default field set — `assignee` / `owner` / `priority` / `due_date` / `tags` / `depends_on`, etc. — exist in the frontmatter are shown.

Document bodies can also contain ` ```mindmap ` blocks, displayed as a collapsible tree in the WebUI. A mindmap is a working surface for thinking, not the source of truth itself, so once direction is settled, have it compressed into normal body text centered on Decision / Next.

## Related pages

- Where Shared Documents sit among the concepts, and the two-layer context structure — `concepts.md`
- The full picture of the server/local boundary (including source of truth and projection) — `trust-boundary.md`
- Project surfaces such as the timeline and Asks — `projects.md`
- WebUI screens and operations — `webui.md`
- CLI command details — `cli.md`