Quotes and provenance

Two body tags keep a card honest about where its words came from. {% quote %} marks a person's exact words; {% source %} marks content that came from another card, file, or page. The rule behind {% quote %} is THE_LAW_OF_QUOTING in the agent guide; this doc is the mechanics.

DIRECT_QUOTES

THE_LAW_OF_QUOTING says never paraphrase the user; {% quote %} is how you carry exact words from any person. Mark a verbatim span with it so the words stay visibly distinct from your paraphrase — inline within a sentence, or as a block:

Mid-rant about his projects: I keep starting things because the start
feels so alive, and then a week in I realize I was just chasing that feeling, not
the actual thing.

There's something about a hand-thrown mug — it has the maker's hand in it. A
perfect machine mug feels dead to me.

We make every installation for the particular room it will inhabit.

You choose which spans to quote, and may trim to the core, split across tags, or move a quote between cards — but the text inside the tag is the user's exact words. (The full rule, and the temptations to resist, are in THE_LAW_OF_QUOTING.)

For the user's own words, omit from: their voice is the default protected by THE_LAW_OF_QUOTING. When quoting a third party — a studio owner, an interview subject, or attributed website copy — set from="…" to the speaker or author. The renderer shows that attribution, keeping the third party visibly distinct from the user's voice. Write a human-readable attribution in from.

A document span you're anchoring a comment to — an excerpt you're pointing at, not a person's words you're recording — is not a quote: it goes in a {% source %} body (see PROVENANCE).

When the user directs an edit to their own quoted words, the result is still authentic — the quote stays a quote. It's your unbidden rewriting the law forbids, not the user's own revision of what they said.

Faithful transcription is not paraphrase. Voice input is transcribed, and these fixes keep a quote faithful:

See node_modules/beebox/box-docs/narration-mode.md.

PROVENANCE — the {% source %} tag

When you write content that's derived from another card or file — a summary of a voice note, an inference from an email, a name pulled from a transcript — wrap it in a {% source %} tag so the origin stays visible. The complement to {% quote %}: where {% quote %} answers whose exact words, {% source %} answers where the content came from, optionally how it was derived.

She's been going back and forth on the kitchen — open shelves vs.
closed, mostly because she doesn't trust herself to keep them tidy.

Dana lives in Portland.

ref — pointing at another card

ref is the box's pointer to another card, used throughout the guide: frontmatter ({ref: "..."}, key-people[].ref), body links, and tags like this one. How to write the path is the refs bullet in the guide's ABOUT_CARDS section. Refs are tracked automatically — bbx validate warns when a ref no longer resolves, and bbx mv rewrites them when the target moves. Inside {% source %}, exactly one of ref / href is required — it names where the wrapped content came from.

A ref reaches only the box's own areas (_content, _config, …): package docs under node_modules/ can be read but not linked, so name them in plain text.

Link-shaped fields use one vocabulary. Internal targets use ref; external targets use href. Put either in an object whose sibling fields explain the relationship — for example sources: [{href, retrieved, usage}] — never an ad-hoc bare URL string array. These names rhyme with {% source %}; use date-only ISO (YYYY-MM-DD) for retrieved.

usage — how the source was used

Optional, free-form natural language describing the way the source material was used to produce the wrapped content. Not an enum — write the truth.

Examples spanning the range:

Honest description beats enum-fitting. If the derivation has a specific shape, name it. If it's just "summarized," say so. Don't collapse everything into verbatim or paraphrase when the truth is sharper.

Composition with {% quote %}

The two tags compose to express "verbatim from there":

I keep going back and forth on the kitchen.

Outer tag pins the origin; inner tag marks that the words are exact. Use the inner {% quote %} only for the user's own words, never for a document excerpt you're pointing at — that goes in the source body (see anchoring, next). A bare {% source %} (no inner {% quote %}) holds content from the source in its body; usage says how faithful — paraphrase, summary, or a verbatim excerpt.

Anchoring an existing span (pos, version, href)

When you're citing a specific span of a specific version of a file — as in a commentary card built from selections — the span itself is the {% source %} body, verbatim (escaped to valid Markdoc), not an inner {% quote %}. The anchor also carries:

When to skip the tag

Your own framing prose — connective tissue, transitions, your read of what something means — doesn't need a {% source %} tag. The tag marks the spans that came from somewhere else. The rest is yours.

Never write the [→ …] bracket form

In compiled context (your briefing include), a {% source %} tag may appear downgraded to [→ name: usage] — that bracket form is generated output for plain-markdown surfaces, never a syntax you write. If you imitate it in chat or a card it renders as literal brackets. Cite with the real tags — chat and card views render {% source %} as a proper citation.