---
id: document-interactions
kind: experience
title: Document Interactions
status: active
depends_on:
  - product-vision
  - frontend
  - data-model
  - work-queue
---

# Document Interactions

The spec document is the primary Charter interface. Everything else exists to make changes to documents become visible, accountable work.

## Markdown files first

The first editing surface should be ordinary Markdown files under `spec/`, edited in Zed, Obsidian, or another filesystem editor.

Required behavior:

- edit prose with Markdown semantics.
- preserve frontmatter and stable document ids.
- show a heading outline.
- support links between spec documents.
- ingest filesystem Markdown edits through watch mode.
- round-trip with the Charter database without losing frontmatter or document identity.
- make ingested, queued, failed, and externally changed state visible through logs and API inspection.

A bespoke editor is no longer the first slice. The user should live in the spec through ordinary files; Charter should watch and understand those files rather than demanding a new editing surface before it has earned one.

## Spans

A user should be able to highlight a span of text and create an object attached to that span.

Span anchors should include:

- document id.
- document version id or hash at creation time.
- start and end offsets, or a richer Markdown-aware anchor.
- quoted text snapshot.
- optional resolved/current anchor state after edits.

Span objects let Charter say: this exact part of the spec needs attention.

## Comments

Comments are database objects attached to documents or spans.

A comment can be ordinary discussion, but it can also be an action request:

- "Can an agent resolve this?"
- "Check implementation against this paragraph."
- "This doc line implies a front-end behavior. Build it."
- "This prompt is stale. Review dependent consumers."

An action comment should create a project event and a durable work item. The work item should point back to the comment, span, document version, and author.

## Documentation as contract

A documentation folder should be treated as first-class spec material.

If the user changes a documentation line that describes product behavior, Charter should be able to create an event and dispatch a consumer to reconcile the implementation, tests, or other specs. Documentation drift is product drift with better punctuation.

## Follow-the-run

When a document change, span, or comment creates work, Charter should let the user or agent follow the chain through logs, API state, CLI inspection, and future UI:

1. source document/span/comment.
2. project event.
3. work item.
4. consumer subscription match.
5. packet.
6. run.
7. report.
8. resulting proposal or document/code change.

This chain is Charter's trust surface. If the user cannot follow the chain, Charter is just another background AI thing doing vibes behind frosted glass.