# Document Format

## Structure

Session documents are markdown files with YAML frontmatter:

```markdown
---
session: 05304d74-90f1-46a1-8a79-55736341b193
agent: claude
model: null
branch: null
---

# Session: Topic Name

## User

Your question or instruction here.

## Assistant

(agent writes here)

## User

Follow-up. You can also annotate inline:

> What about edge cases?
```

## Frontmatter fields

| Field | Required | Default | Description |
|-------|----------|---------|-------------|
| `session` | no | (generated on first run) | Session ID for continuity |
| `agent` | no | `claude` | Agent backend to use |
| `model` | no | (agent default) | Model override |
| `branch` | no | (none) | Git branch for session commits |

All fields are optional and default to null.

## Frontmatter parsing

Delimited by `---\n` at the start of the file and a closing `\n---\n`. If frontmatter is absent, all fields default to null and the entire content is treated as the body.

## Interaction modes

### Append mode

Structured `## User` / `## Assistant` blocks. Each run appends a new assistant response.

### Inline mode

Annotations anywhere — blockquotes, edits to previous responses, comments in the body. The diff captures what changed; the agent addresses inline edits alongside new `## User` content.

Both modes work simultaneously because the run sends a diff, not a parsed structure.

## Components

Documents can contain **components** — named, re-renderable regions marked with HTML comment pairs:

```markdown
<!-- agent:status -->
| Field | Value |
|-------|-------|
| build | passing |
<!-- /agent:status -->
```

Components are updated via `agent-doc patch` or by agents/scripts. Their content can be replaced, appended to, or prepended to based on configuration in `.agent-doc/components.toml`.

Regular HTML comments (`<!-- like this -->`) remain a private scratchpad — they're stripped during diff and never trigger responses. Component markers look like comments but are structural and preserved.

See the [Components](components.md) guide for full details.

## History rewriting

Delete anything from the document. On next run, the diff shows deletions and the agent sees the cleaned-up document as ground truth. This lets you:

- Remove irrelevant exchanges
- Consolidate scattered notes
- Restructure the conversation
- Correct earlier context
