Agents

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 with basedOnVersion (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.
  • contentHash is 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