---

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.