Proposal: note tail blocks for backmatter and banknotes

[junior-ricon]

Proposal

Add first-class support in notes for hidden/optional tail blocks at the end of Markdown notes:

1. Backmatter — structured machine-readable metadata after the visible body.
2. Banknotes — freeform Markdown tail notes, optionally named and attributed with key/value attributes.

Motivation

Some notes need operational instructions or parser-only metadata, but putting that material in the visible body can clutter the note and reduce readability. Frontmatter is useful for concise metadata, but not ideal for maintenance instructions, hidden agent notes, or long freeform guidance.

A tail-block convention would let normal readers consume the visible note while notes-aware readers can query the hidden/optional layer.

Proposed syntax

Backmatter

Structured tail metadata:

<!-- NOTE-BACKMATTER-BEGIN
role: control-surface
owner: c0da
stale_after: P7D
reader_policy: hide_by_default
maintenance: update after each referral run
NOTE-BACKMATTER-END -->

Banknotes

Freeform tail notes, with optional attributes:

<!-- NOTE-BANKNOTE-BEGIN name=maintenance audience=agents
## How to maintain this note

This note is a control surface. Update the visible `Now` section after each run.
Archive completed detail into `status-archive.md`.
Do not append chronological logs here.
NOTE-BANKNOTE-END -->

Attributes could initially be parsed as simple shell-like key=value tokens. name= should be optional but recommended if more than one banknote exists.

Proposed semantics

• Tail blocks are hidden by default from notes read once that command exists, unless explicitly requested.
• Raw file reads still show the blocks; this is a convention, not access control.
• Backmatter is for structured metadata.
• Banknotes are for freeform Markdown.
• Tail blocks should live after the visible body, ideally at EOF.
• Multiple banknotes are allowed.
• Multiple backmatter blocks should probably be rejected or reported as malformed.

Initial CLI possibilities

This issue is about defining/parsing the block model, not necessarily shipping all CLI commands at once. Possible commands:

notes banknotes list <file>
notes banknotes get <file> [name]
notes backmatter get <file> --json
notes read <file> --with-banknotes

Guardrails

• This is not encryption or privacy. It is a reader/filtering convention.
• Critical human instructions should not disappear solely into banknotes unless the workflow guarantees notes-aware reading.
• Prefer small, purposeful banknotes over dumping hidden scratch text.
• Avoid making note maintenance depend on invisible material that ordinary Markdown readers cannot discover.

Open questions

1. Exact delimiter names: NOTE-BACKMATTER-* and NOTE-BANKNOTE-* seem readable; confirm before implementation.
2. Should banknote attributes support quoted values, or only simple tokens at first?
3. Should banknotes be allowed anywhere, or only after the visible body?
4. Should notes verify eventually detect malformed/unclosed tail blocks?

Acceptance criteria for a first slice

• Parser helper can identify visible body vs backmatter vs banknotes.
• Tests cover no tail blocks, one backmatter block, one banknote, multiple banknotes, malformed/unclosed blocks, and delimiter text in ordinary code blocks if relevant.
• Documentation states this is a convention/filtering layer, not a privacy boundary.