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 that the next agent or human will reread outside the request — decisions, completed specs and research, refined proposals, and handoffs — in Shared Documents, and keep content still under consideration in chat / sessions. Results the requester receives in a reply and is done with (review verdicts and findings, answers to questions) go back in the Session reply. Decide whether to write a document by whether it must be reread outside the request and how settled it is, not by its length. For example, a single review verdict is fine as a reply, while a full-site audit that several follow-up fixes each refer to is kept as its own document. Session-specific history remains in the session transcript. You do not need to post a Project Chat message just to announce that a document was created or updated (see Find and open documents in the WebUI for discovery surfaces). 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/teams/<team>/projects/<project>/docs/ directory is a projection: an editable copy. A change is shared when the server accepts it.

• On your machine, it syncs bidirectionally with the server while aachat up is running. In a Session workspace, that Session's own mirror syncs it
• Editing local files syncs automatically. There is no manual sync command
• Local edits made while aachat up is not running are not synced; they sync once it runs
• Deleting a projected file in the normal way also deletes the document on the server. Deleting requires the same permissions as editing
• If asked which side is authoritative: the server is the source of truth, local is the projection

Regular files named exactly .DS_Store, .localized, Thumbs.db, ehthumbs.db, ehthumbs_vista.db, or desktop.ini, which operating systems create automatically, are excluded from sync at any depth in the projection. They are neither synced nor deleted, and they do not block startup. Directories or symbolic links with those names, and other unknown files, are not excluded.

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 locations

The accepted document paths are:

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

• PROJECT.md is the stable Project Contract / Context Router
• REPORT.md is the lifecycle document that records the Project's results and remaining gaps
• 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
• _errors.md is a generated sync diagnostics file, and <kind>/_template.md is a kind definition; neither is an ordinary deliverable

PROJECT.md is the stable Project Contract

At Session startup, the full PROJECT.md body for the Project named in the request is included as a snapshot if the file exists; otherwise, its absence is stated. Agents read the source when they need another Project's context or the latest version. Use these headings in this order and keep only stable information:

• Purpose: why the work matters and the value it creates
• Outcome: the change in state to achieve
• Success Measures: definitions, measurement methods, and target direction or level for 1–3 indicators that observe the Outcome. No current values
• Milestones (optional): only for Projects where staging changes decisions. Stages of state and their exit conditions, without dates or progress
• Required Outputs: deliverables needed for the Outcome, who uses them, their dependency order, volume, and completion conditions. Recurring work lists its Workflows and Triggers as deliverables too. Not a task list
• Decision Principles and Boundaries: priorities, discretion, responsibilities, and decisions returned to humans
• Context Map: a curated set of references to canonical sources that affect decisions, with the reason to read each

Do not put progress, current indicator values, assignments, handoffs, logs, or unresolved notes 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 is the Project's current position

PROJECT.md defines the stable goal and how success is judged; REPORT.md records the observed current position and the material the next Lead needs to choose their own moves. Rewrite the whole file in the present tense as of a date, using five sections — Outcome Status, Results and Approaches, Human Intent, Gap Hypotheses, and In Flight — for current indicator values, results and the approaches tried, human decisions, hypotheses about why the Outcome is not yet reached, and work in flight. Do not write next steps, recommendations, or task lists. The frontmatter summary is what reaches the parent Project and lists.

This heading structure is a document contract that agents follow, not a schema enforced at save time. A REPORT missing sections is still saved; doc check only returns a warning. Its exact path is aachat/teams/<team>/projects/<project>/docs/REPORT.md. Do not substitute report.md, Report.md, or a document under a kind folder.

In the WebUI, open the REPORT from the Project's Docs. If it is missing or outdated, create or update it with the usual Project document permissions. Normal file edits use 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. Write a WikiLink as the in-repository path wrapped as-is in [[ ]].

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

• A display label in [[<target>|label]] is accepted but does not change the target. Agents writing new links should omit the label by default
• A body containing any of these WikiLink forms is rejected on save: the old shorthand [[<kind>/<id>]], the removed document layout without Team/Project scope, or a target that starts with aachat/teams/<team>/projects/<project>/ but is not a valid supported docs, html, or workflows path
• [[...]] inside inline code, fenced code blocks, or HTML is not treated as a WikiLink

Project HTML and Workflow paths also work as body WikiLinks, for example [[aachat/teams/acme/projects/demo/html/reports/review.html]] and [[aachat/teams/acme/projects/demo/workflows/posting/README.md]]. A .html page opens its member preview in a new tab. A Workflow slug or any path below it opens that Workflow's screen. Other HTML assets, including .htm, CSS, and JS, appear as non-interactive paths. Existence and access are checked at the destination. HTML and Workflow links are not added to document reference lists.

In the WebUI, WikiLinks in document bodies and messages appear as document chips. Chip states:

When a Markdown link's destination contains a full aachat/teams/<team>/projects/<project>/docs/... path, the WebUI also shows it as a document chip. Local file paths such as absolute /Users/... paths or file:// cannot be opened in a browser, so they are shown as text, not links. A relative link such as ../spec/x.md does not become a document chip; use a WikiLink to point at a document.

Adding a WikiLink to a request does not create its target or grant permission to read it. See Markdown blocks for differences between display surfaces.

Referenced by

The document view'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. A body containing correctly formed full-path WikiLinks is saved even when a target Team or Project cannot be found or is outside the saving person or agent's access scope.

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

kind and _template.md

kind is the document's type (spec / 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 a definition error.

When preview_fields is omitted, whichever of aachat's default fields (assignee, owner, author, reviewers, due_date, priority, tags, depends_on, related, commands, and others) exist in the frontmatter are used.

An undefined kind is treated as plain Markdown. Documents work normally without defining a kind; schema validation and scaffolds apply only to defined kinds. Deleting _template.md returns that kind to raw Markdown and keeps existing documents. If the definition has a problem, diagnostics appear in that folder's _errors.md.

Ready-made sets of kind definitions can be installed into a project from Discover templates in Docs, or from Discover. If a name collides with an existing kind, you can choose, after confirmation, to overwrite only the colliding kinds. 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

Kind Definition in Project Settings handles the Project's whole kind definition as raw YAML. A Collaborator or Admin in an active project can use Install, Publish, Define (when nothing is defined), Save, and Delete. It is read-only for Viewers and for Projects that are not active; Reload, which loads the latest definition, is available to anyone who can open the screen.

• If another tab or person saves first, "Definition updated elsewhere" appears. Use Reload latest to load the latest, integrate your differences, and save again
• Publish is available for a saved definition with no unsaved edits
• Delete removes the whole definition. Existing documents are not deleted, but the schema and scaffold are removed and documents are handled as raw Markdown. Before deleting, confirm the validation and new-document scaffold that will be lost

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 in the document's frontmatter _warnings and shown in the "Validation warnings" banner in the document view. Syntax problems in mindmap and brainstorm blocks do not stop the save either; when you save in the WebUI, they are shown as warnings. 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 rule violations (starts with a lowercase letter or digit; lowercase letters, digits, _, and -; up to 64 characters)
• Syntax errors in the frontmatter itself
• A non-string status in a document without a kind schema
• The invalid WikiLink forms listed above
• Exceeding 1 MiB per document

When working with local files, rejections, warnings, and unresolved conflicts are written to _errors.md in the folder containing the file (the kind folder, or the Project's docs/ for a root document). Its headings are "Unresolved conflict," "Sync errors," and "Warnings." 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.

Find and open documents in the WebUI

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

• Docs (the Project's /docs): the in-project document list
• document view: the body surface opened from a path or WikiLink
• the Session's final answer and results badge: open the document from the final answer of the Session that created or updated it, or from the Docs badge in the Session header (Sessions)

You do not need to post to Project Chat just to announce a document change. Use Chat when you discuss the Project's issues, decisions, or actions based on a document, and point to that document with a WikiLink.

The Docs list

Docs shows documents as a table with the columns Kind, Status, Updated, Title, File, and Related. Status appears only when documents have a status, and Related only when some document has relation fields. The Updated column shows the update time and who updated it.

• The search box filters on title, summary, and path
• The Kind and Status column menus filter by selected values. Clear filters removes them
• Each column menu sorts by kind, title, file, status, updater (Updated by), or update time, ascending or descending. The default is update time, newest first
• Search, filter, and sort state is kept in the URL, so the same view can be shared by URL
• On narrow screens, a row list and a sort selector replace the table
• Collaborators and Admins in an active project see New document and Discover templates

In New document, choose a Folder (root, an existing folder, or + New folder…) and a Name (.md is added automatically). Nothing is created if a file already exists at that path. A folder with _template.md acts as a kind with schema and scaffold; without one it remains a raw Markdown folder.

The document view

The document view shows title / summary / status, frontmatter, body, schema warnings, Referenced by, and the creator, updater, and updating Session. Actions at the top:

The full summary appears at the top, and document references such as related appear after the body in their original order. Long summaries and reference lists wrap to fit the view.

For documents whose kind schema has an enum for status, people who can edit can change the value from the Status dropdown.

In Done (completed) and Archived Projects, human members can open documents read-only. Creating, editing, deleting, creating public links, and changing the Kind Definition are unavailable. Agents can read and write documents only in active Projects. Documents in a planning Project cannot be opened.

For agents, there are the docs projection, CLI aachat project read (which includes document create/update items), and aachat project document <project> (the document catalog, and one document via --path docs/<file>).

Editing in the WebUI and conflicts

After Save succeeds or Cancel discards the edit, the document returns to your reading position from before editing. A section URL takes priority; if the document becomes shorter, the position stays within its new length.

Use Edit in the document view to edit the body. If another member or agent saves the same document while you are editing, a "document changed elsewhere" alert appears. Your draft is kept.

Saving after Keep my draft, and Overwrite, both replace the other writer's changes. Preserve any needed draft separately and compare it with the latest content before choosing.

Edit conflicts in the local projection

While you edit a local projected file, the same document may also be updated on the server. The mirror then runs a three-way merge between the last synced version (the ancestor), your local version, and the server version.

• Changes in different places: merged automatically, and the result is sent to the server again. No action needed
• Changes in the same place: your local change is not sent, and the server version stays canonical. diff3 conflict markers are written into the local file, and the file is listed under "Unresolved conflict" in _errors.md

The markers look like this. ours is your local change, original is the ancestor, and theirs is the server's latest version.

<<<<<<< ours
What you wrote locally
||||||| original
The shared original content
=======
The server's latest content
>>>>>>> theirs

To resolve:

1. Open the same file, remove every conflict marker outside fenced code blocks, and combine the content into one version
2. Save it at the same path. Do not save under a different name, and do not edit the baseline or _errors.md
3. Wait for the server to accept it. Once accepted, the entry disappears from _errors.md

Files that still contain markers, and conflicted files that disappeared, become blocked writes that are not sent until fixed. aachat status then shows projection.state as error, with a cause such as “Mirror has one blocked write: …” in projection.reason. Once you remove the markers and save, and the server accepts it, the error clears and the file leaves _errors.md.

• Deleting or moving a conflicted file does not delete the document. To delete it, resolve the conflict first, wait for acceptance, and then delete it normally
• Markers inside fenced code blocks are ignored. However, outside fenced code blocks, a line starting with seven or more consecutive <, |, or > characters is treated as a conflict marker, and the file is not sent. To show markers as an example, put them in a fenced code block

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.

In Docs, use New document to choose a folder such as research and the Name customer-findings. Alternatively, have the covered Session agent save aachat/teams/acme/projects/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/teams/acme/projects/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. A message only to announce the update is not needed; when you discuss the document in Chat, include its full WikiLink in the Project message.

Check locally before syncing

Before saving, you can check locally whether sync would reject the input. None of these commands contacts the network, and none confirms saving, server sync, or authorization.

Outside a Session (humans and outside agents):

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

• Checks one file per run. It works without a Session on a file in an aachat init connected repository or under ~/aachat/teams/<team>/projects/<project>/
• repo_not_connected means that repository is not connected on this machine. Run aachat init in that repository, or place the file under aachat/teams/<team>/projects/<project>/docs/ in a connected repository

Session agents:

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

• Accepts multiple paths. Documents written with Claude's Write / Edit / MultiEdit or Codex's apply_patch are checked automatically by a PostToolUse hook. Check documents written by other means, such as the shell, with chat doc check
• The hook runs after the write, so the file is already written. Only when sync would reject it does the hook return an error with the reason; fix the file and save again. Warnings are not errors; they are returned as additional context. If the hook could not inspect a write, it says the file was written unchecked and suggests updating aachat

Reading the result (both commands):

• validation.files[] returns one entry per path, in the order given
• In diagnostics[], severity: error means sync will reject the save. severity: warning means it will be saved but does not match the kind schema (including _warnings already recorded in the document) or that REPORT.md is missing sections. message explains the fix
• validation.valid is false when any file would be rejected by sync
• disposition is checked (inspected), not_applicable (not a projected document path), or unreadable (could not be read, not inspected)
• chat doc check fails with invalid_argument and exit code 2 if any path is unreadable. The results for the other paths are in the error's data.validation.files[]

Fix until diagnostics is empty, then save and wait for sync. When sync is unavailable, keep your local work and follow sync recovery.

When a saved document cannot be read

• "Document not found" in the WebUI: check that the path is correct and whether the document has reached the server yet. A document written locally does not exist on the server until sync accepts it
• aachat project document <project> --path docs/<file> returns not_found (field path): the Project exists, but no document exists at that path on the server. Follow the returned next_actions: check the published document list and paths with aachat project document <project> --team <team>, and if you wrote the file locally, check the projection state with aachat status. A projection state of error means sync failed (see projection.reason), stopped means aachat up is not running, and running means it may still be uploading, so read again shortly
• project_not_found: the Project does not exist, or you have no permission to read it. The two are not distinguished. Check the Project name and --team
• Entries in _errors.md: fix the rejection, warning, or conflict described above and save the same file again

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.

The WebUI chooses a display by field name (case-insensitive) and value type.

When the value type does not match, and for other fields, the display follows the value's runtime 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_-]*$, are at most 32 characters, and names starting with _ are reserved. Use only one kind directory level: deeper nesting, ./.., backslashes, and a literal root/ folder are not document identities. Reserve uppercase PROJECT.md and REPORT.md for their roles, and do not use project.md, Project.md, report.md, or Report.md. docs/index.md, _template.md, and generated diagnostics are not ordinary deliverables.

Kind schemas support these keywords:

$ref, $defs, oneOf, anyOf, allOf, not, if/then/else, dependencies, patternProperties, propertyNames, and tuple-form items are not supported. Do not paste an arbitrary JSON Schema as-is. format is recorded but not checked, so it does not guarantee a correct date or URL. Names other than date, date-time, uri, and aachat.* can produce a warning. Schema-definition errors differ from nonblocking warnings on a document's field values.

Share the saved result

Use the document's Create public document link only after checking the current body and referenced media. A single-document link reads only the latest version of that document. An AI context link reads a much broader Project scope. See Sharing for creation, 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
• Timeline, Asks, and Project states — Projects
• Markdown, diagrams, and structured blocks you can write in a body — Markdown blocks
• WebUI screens and operations — WebUI
• CLI command details — CLI
• Recovering when sync stops — troubleshooting