Goldfish note format (goldfish-note/1)

A Goldfish note is a Markdown document. It is written to be read by a person on a phone, and to be pasted as-is into a notes app or a language model.

The note reaches the phone inside the NFC link (https://<reader>/#g1.<base64url(deflate-raw(note))>, see firmware/goldfish/handoff.py). The reader page renders it and saves it as a .md file.

Shape

---
format: goldfish-note/1
recorded: 2026-10-13T14:00
read: 2026-10-14 (day 1)
voices: 5
protocol: Resolution Protocol 0.2
profile: goldfish
device: Goldfish v01
---

# Session note: 13 Oct 2026, 14:00

## Outcomes
*R1 outcomes · kept until 2027-10-13*
- Outcome: we sign with Calder by the 20th.

## Gist
*R2 gist · kept until 2026-11-12*
- the deck goes out on Friday

## Attributed
*R3 attributed · kept until 2026-10-16*
- Mara said that the deck is late.

> Left out to fit the tag: Attributed. Hold the eye again later to read them.

Rules

Part Rule Why
Front matter YAML, flat key: value; format first. Values are quoted only where YAML would misread them Tools and models get the session's facts without parsing prose
Title One # line: the recording's date and start time A file list stays readable
Sections One ## per level, in priority order: Outcomes, Gist, Attributed The lowest resolution is always kept; the tag drops from the bottom
Level line The first line of each section, in italics: the level and its expiry date RP §5.4: an exported artefact states its level and expiry
Statements One - bullet per statement; - (none) when a level holds nothing Models and diff tools work line by line
Dropped sections A closing > line names any section left out to fit the 8 KB tag Nobody mistakes a cut note for a complete one
Voices Named only as the room named them at R3; otherwise unnamed Below R3 the protocol keeps no attribution (RP §3)

What a note never contains: audio, timestamps per statement, voice features, or anything above the level each voice chose.

Compatibility

# Goldfish note format (`goldfish-note/1`)

A Goldfish note is a **Markdown** document. It is written to be read by a person on a phone, and to be pasted as-is into a notes app or a language model.

The note reaches the phone inside the NFC link (`https://<reader>/#g1.<base64url(deflate-raw(note))>`, see `firmware/goldfish/handoff.py`). The reader page renders it and saves it as a `.md` file.

## Shape

```markdown
---
format: goldfish-note/1
recorded: 2026-10-13T14:00
read: 2026-10-14 (day 1)
voices: 5
protocol: Resolution Protocol 0.2
profile: goldfish
device: Goldfish v01
---

# Session note: 13 Oct 2026, 14:00

## Outcomes
*R1 outcomes · kept until 2027-10-13*
- Outcome: we sign with Calder by the 20th.

## Gist
*R2 gist · kept until 2026-11-12*
- the deck goes out on Friday

## Attributed
*R3 attributed · kept until 2026-10-16*
- Mara said that the deck is late.

> Left out to fit the tag: Attributed. Hold the eye again later to read them.
```

## Rules

| Part | Rule | Why |
|---|---|---|
| Front matter | YAML, flat `key: value`; `format` first. Values are quoted only where YAML would misread them | Tools and models get the session's facts without parsing prose |
| Title | One `#` line: the recording's date and start time | A file list stays readable |
| Sections | One `##` per level, in priority order: Outcomes, Gist, Attributed | The lowest resolution is always kept; the tag drops from the bottom |
| Level line | The first line of each section, in italics: the level and its expiry date | RP §5.4: an exported artefact states its level and expiry |
| Statements | One `-` bullet per statement; `- (none)` when a level holds nothing | Models and diff tools work line by line |
| Dropped sections | A closing `>` line names any section left out to fit the 8 KB tag | Nobody mistakes a cut note for a complete one |
| Voices | Named only as the room named them at R3; otherwise unnamed | Below R3 the protocol keeps no attribution (RP §3) |

What a note never contains: audio, timestamps per statement, voice features, or anything above the level each voice chose.

## Compatibility

- Readers accept older notes with no front matter (plain `## Heading` sections).
- A later format bumps `format:` (for example `goldfish-note/2`); readers show unknown keys as they are.
- The Python (`handoff.front_matter`, `handoff.section`, `handoff.fit`) and JavaScript (`frontMatter`, `section`, `fit` in `firmware/js/goldfish.js`) writers produce the same bytes.