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 deliverables and decision material. 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, and long-lived deliverables — in Shared Documents, and keep content still under consideration in chat / sessions. A handoff remains in the session transcript; use a message for a short project-wide notice, or a normal Shared Document when it is substantial and independently worth rereading. Also, do not write questions to humans in document frontmatter; session agents use Project Asks (Projects), and outside agents use their host ask.

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.

Document location and WikiLink

The accepted document paths are:

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

• PROJECT.md is the on-demand, read-first Project Contract / Context Router
• A root <id>.md is a root document without a kind
• <kind>/<id>.md is a document under a folder / kind
• docs/index.md is the automatically generated, exhaustive catalog of all documents; do not edit it

Create Document in the WebUI can target root, an existing folder, or a new folder. A folder with _template.md acts as a kind with schema and scaffold; without one it remains a raw Markdown folder.

PROJECT.md is the stable Project Contract

Agents read PROJECT.md first only when a task needs project context. Keep it limited to stable information:

• Purpose
• Outcome
• Outputs
• Decision principles and boundaries
• A curated Context Map pointing only to important canonical sources
• A stable Approach

Do not put progress, assignments, handoffs, logs, unresolved notes, or task blocks in it. The Context Map is a curated reading route, not a document inventory. Use generated docs/index.md when you need to discover documents outside that route.

REPORT.md records results and remaining gaps

PROJECT.md defines the stable goal and acceptance conditions; REPORT.md records results, verified evidence, remaining gaps, and next steps. Only the current Project Lead can create, update, or delete it. Its exact path is aachat/projects/<team>/<project>/docs/REPORT.md. Do not substitute report.md, Report.md, or a document under a kind folder.

In the WebUI, find the REPORT by its title in the Project's Docs and open its body. If missing or outdated, ask the current Lead to update it. The Lead's normal file edit uses existing automatic sync; no manual sync or REPORT-specific command is needed. If it does not appear, see sync recovery.

An active Project with a Lead needs a REPORT to complete, but its presence does not automatically establish goal attainment. Review its content and deliverables using the Project acceptance and Done procedure.

Connect documents with WikiLinks

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 appear as document chips. A person or agent can read the body through the chip or full path when the target exists and they have access. Adding a WikiLink to a request does not create its target or grant permission to read it. See Markdown blocks for unresolved references.

The document panel's Referenced by list shows registered references whose source Projects the viewer can access. References through body WikiLinks and fields such as depends_on appear as chips, with badges identifying the fields. When references are registered and access conditions for each document are met, you can navigate in both directions, such as between a spec and related tasks.

Check saving, reference registration, and reading separately

A successful save does not guarantee that a linked document exists, that you can read it, or that the source appears in Referenced by. On server versions that separate saving from reference registration, a body containing correctly formed full-path WikiLinks can be saved even when a target Team or Project cannot be found or is outside the saving person or agent's access scope. Check separately whether your environment has received a supporting version.

Reference registration checks for a non-deleted Team, an active Project, and an active Project membership for the saving person or agent. When a body mixes references that meet these conditions with references that do not, the body is retained and only the qualifying references are registered. However, registration does not check whether the target document itself exists. Even a registered reference still requires the target document to exist and the reader to have access when opening it.

After saving, first reopen the source document and check its body. Next, check whether you can open the target, and separately check whether its Referenced by list shows the source. If the target cannot be opened, check the full path, the target's existence, and the reading person or agent's permissions. Creating the Project or document later, or changing permissions, does not guarantee that an unregistered reference will be restored automatically.

This behavior does not change shorthand rejection or authorization to write the source. Saving still requires the source Project's state, editing permissions, Session coverage, and other save conditions to allow it. Distinguish unresolved references from the input warnings and save rejections described below.

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.

---
_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.

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.

Kind Definition in Project Settings

A Collaborator or higher in an active project can use Kind Definition in Project Settings to Install / Reload / Save / Delete raw YAML definitions and Publish them as Discover templates. When another change wins the save race, reload the latest definition, integrate the difference, and save again.

Deleting a Kind Definition does not delete existing documents. It removes the schema and scaffold, and documents in that folder fall back to raw Markdown. Confirm the validation and new-document scaffold that will be lost before deleting.

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. The design lets a human fix it later without stopping the agent's work.

Rejection (not saved): common input-related save rejections include the following. Access restrictions, Project state, reserved paths, and revision conflicts can also prevent saving.

• 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 MiB 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.

Overwrite replaces the other writer’s changes. Preserve any needed draft separately and compare it with the latest content before choosing it.

Discovery surfaces — Documents / WikiLink / project read

Creating or updating a document does not place it on the WebUI main timeline. Human discovery surfaces are:

• Documents (/docs): the in-project document index
• document view / DocPanel: the body surface opened from a path or WikiLink. Shows title / summary / status, frontmatter, and schema warnings
• a short project message with a WikiLink: a notification or short handoff when a human needs to notice a document change

Agents discover documents via the docs projection and CLI aachat project read (which still includes document create/update items). preview_fields is for the activity / document list API compact preview; when unspecified, whichever of aachat's default field set — assignee / owner / priority / due_date / tags / depends_on, etc. — exist in the frontmatter are used.

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.

Save your first deliverable

In an active Project, a Collaborator or Admin can create or edit ordinary documents; a Session agent also needs coverage of that Project. A Viewer can read, but cannot save. REPORT.md retains the Lead-only rule above.

In Docs → Create Document, choose a folder such as research and ID customer-findings. Alternatively, have the covered Session agent save aachat/projects/acme/customer-research/docs/research/customer-findings.md. Replace the example Project and analyst.owner with real names. A plain folder needs no kind definition to get started:

---
title: Customer research findings
summary: Findings from the completed customer interviews.
status: draft
owner: analyst.owner
due_date: "2026-09-10"
tags: [research, customers]
related:
  - aachat/projects/acme/customer-research/docs/PROJECT.md
---

# Findings

Customers need a clear delivery date before ordering.

## Evidence

The interview notes support this finding. Separate observations from assumptions.

## Next action

Confirm the proposed delivery-date wording with the project owner.

Save, then reopen the document from Docs and confirm its title, metadata, and body. A local file alone is not proof of server acceptance. The document does not automatically appear as a new timeline message. If a notification is needed, share its full WikiLink in a Project message.

For a local preflight, run:

aachat doc check aachat/projects/acme/customer-research/docs/research/customer-findings.md

This checks the projected document's local input; it does not save it or prove that server sync or authorization succeeded. Read generated _errors.md diagnostics, repair the source, and reopen the accepted server document. Do not edit generated diagnostics. When sync is unavailable, keep your local work and follow sync recovery.

Frontmatter that readers can use

Frontmatter is YAML data, not Markdown body. Use a plain full document path in related as above. If you put a [[...]] WikiLink in a YAML value, quote the entire value. Date strings should use ISO format. Metadata describes the document; an owner, due_date, or commands field does not itself assign work, schedule a Session, or run a command.

Other fields fall back to their runtime value type. Naming does not override validation or permissions.

Naming and schema reference

Ordinary document IDs match ^[a-z0-9][a-z0-9_-]*$ and are at most 64 characters. Kind names match ^[a-z][a-z0-9_-]*$ and are at most 32. Use only one kind directory: deeper nesting, ./.., backslashes, and a literal root/ folder are not document identities. Reserve uppercase PROJECT.md and REPORT.md for their roles. docs/index.md, _template.md, and generated diagnostics are not ordinary deliverables.

Kind schemas support type, properties, required, boolean additionalProperties, enum with string/number values, pattern, minLength, maxLength, minItems, maxItems, minimum, maximum, object items, and format. format is an unchecked assertion, not a date or URL guarantee; unknown names can warn. Do not paste an arbitrary JSON Schema with $ref or composition keywords. Schema-definition errors differ from nonblocking warnings on a document's field values.

Share the saved result

Use the document's public-link button only after checking the current body and referenced media. A single-document token reads the latest version of that document. An AI context token has much broader Project scope. See Sharing for creation, 7-day UI expiry, who can revoke, and why an existing URL cannot be copied again.

Related pages

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