Quote terms
The brand's standard terms for quotes, per-client variants, immutable published versions, diffs, and how Polyther and Nitti resolve the terms for a quote.
Most clients get the same terms on a quote. Some negotiate their own: longer payment terms, a capped liability, a different notice period. Quote terms keep both in Braaand: the brand's standard terms, and a variant for each client who agreed something else. Polyther and Nitti resolve the terms for a quote's client and put them in the quote as appendix pages.
Clients
A variant belongs to a client: a customer of the brand, kept as a shared record beside the company and its offices. A client is not the brand's own company. It has a name, a legal name, an organisation number, a country, a contact name, a contact email and notes.
- The contact email and the notes start private: they never leave Braaand
(not in an export, not in what a connected site or an app reads). Change that
per client with
privateFields, as for any record. - Clients are in the records feed when a reader
asks for them (
?kinds=client), so Polyther can link its contact books to them. A connected site reads clients; it does not push them.
braaand clients add <brandId> --set name="WWF Norway" --set orgNumber="958 382 557" --set country=Norway
braaand clients list <brandId>MCP: list_clients, create_client, update_client, delete_client. REST:
GET|POST /api/brands/{brandId}/clients, GET|PATCH|DELETE …/clients/{clientId}.
Draft, publish, versions
Every terms block (blk_…) has a draft, the working copy, and
published versions.
- Editing the draft never changes what a quote resolves to.
- Publish turns the draft into the next version. A published version never changes: the database refuses any update of it. A quote that was sent with version 3 can always show exactly version 3.
- Delete removes terms that were never published. Published terms are archived instead: their versions stay, because sent quotes cite them, and they no longer resolve. Archiving standard terms archives their variants too.
The content is BlockNote blocks, the format Polyther and Nitti documents use: paragraphs, headings (levels 1 to 3), quotes, bulleted, numbered and checklist items, and dividers, with bold, italic, underline, strikethrough, code and links. That is the prose part of BlockNote's default schema, which every editor built on it reads. Anything else is refused.
Markdown is the fallback for writing terms from the command line or an
agent: send markdown instead of content and it is turned into the same
blocks (# headings, paragraphs, - bullets, 1. numbers, - [ ] checks,
> quotes, ---, **bold**, *italic*, [text](https://…)). Every read
also answers the content as markdown.
Client variants
braaand terms create <brandId> --name "Standard terms 2026" --file terms.md
braaand terms publish <brandId> <termsId>
braaand terms variant <brandId> <termsId> --client <clientId> --note "Net 60, liability capped at the fee"
braaand terms set-draft <brandId> <variantId> --file wwf-terms.md
braaand terms diff <brandId> <variantId> --from base --to draft
braaand terms publish <brandId> <variantId>- A variant opens as a draft copy of the standard's latest published
version, and records that version as
basedOnVersion. - There is one variant per client per standard.
- The negotiation note says what was agreed, for the next person who reads it.
- Behind: when the standard terms publish a newer version, every variant
based on an older one reads
behind: true(braaand terms behind,list_terms({ behindOnly: true }),GET …/terms/behind). Someone decides whether the change applies to that client: edit the variant if it does, then mark it reviewed withbasedOnVersion(braaand terms set-draft … --based-on <n>), which clears the flag.
Drafting a variant from a negotiation
draft_terms_variant_from_text (CLI braaand terms draft-variant, REST POST …/terms/{termsId}/variants/draft-from-text) takes the negotiation text, an
email thread or meeting notes, and drafts the client's variant in one model
pass. It changes only what the text clearly agrees, keeps every other sentence,
and lists its changes and any openQuestions. The result is saved as the
variant's draft, with the diff against the standard. It never publishes:
a person reviews it first. It is metered like other single model passes.
Diffs
diff_terms_versions (braaand terms diff, GET …/terms/{termsId}/diff)
compares two sides of a terms block line by line, one markdown line per block:
each line is equal, insert or delete, with line numbers and totals.
A side is a version number, latest (the current published version), draft,
or, on a variant, base (the standard at the version the variant was copied
from) or standard (the standard's latest). from: base shows exactly what was
negotiated. from: base, to: standard shows what changed in the standard
since the variant was made, which is what a variant that is behind is missing.
Resolving the terms for a quote
GET /api/brands/{brandId}/terms/resolve?termsId=<blk_…>&clientRecordId=<rec_…>
→ { termsId, variantId?, version, contentHash, name, content }- The client's published variant answers when there is one. Otherwise the standard terms do, at their latest published version.
- A variant that is only a draft, or archived, is ignored.
contentHashis the SHA-256 of the content's canonical JSON.- Pin on sending. The first time a quote is exported or shared, store
{ termsId, variantId?, version, contentHash }and the content with it. That copy never changes afterwards, even when the terms are revised: legal text must not move under a sent quote.
A document kit lists the terms it offers in
terms. The document theme (profile=document) carries them as [{ id, name }],
published standard terms only. The text is never in the theme: a document
resolves it.
Access
- Reads (list, get, versions, diff, variants, behind, resolve) need read access to the brand, or the brand-supply OAuth grant with an active subscription, which is how Polyther and Nitti resolve terms.
- Unlike the design-system export, a system brand's terms are not readable by everyone: terms and client variants are the brand's business.
- Writes (create, edit, publish, delete, variants, drafting from text) need the editor role.
- Ids from another brand read as not found.
MCP tools
| Tool | What it does |
|---|---|
list_terms |
Standards with their variants grouped; behindOnly |
get_terms |
The draft, the latest published version, versions, variants; or one version |
create_terms |
New standard terms as a draft |
update_terms_draft |
Edit the draft, the name, a variant's note or basedOnVersion |
publish_terms |
The draft becomes the next immutable version |
delete_terms |
Delete never-published terms; archive published ones |
create_terms_variant |
A client's variant, copied from the standard's latest published version |
draft_terms_variant_from_text |
Draft a variant from negotiation text; never publishes |
diff_terms_versions |
The line diff between two sides |
resolve_terms |
What a quote for a client uses now |