avodado

77 typed blocks

Every block type in @avodado/core, with its starter template rendered right here by the real pipeline — the same parse → validate → render path avo build uses.

Showing 77 of 77

Narrative & prose

9 blocks

Document cover

Document cover — title, subtitle, tag, and an optional logo.

title: New document
subtitle: One-line description.
tag: DRAFT
Narrative & proseDocs →

Callout

A single aside — note, tip, warning, or danger.

SECTION 01 · Note

Heads up

Note
A short note that the reader should not miss.
Narrative & proseDocs →

Structured prose

Structured prose (headings, paragraphs, lists, quotes) as data.

SECTION 01 · Overview

Overview

Background

A paragraph explaining the context.

  • Idea one
  • Idea two
  • Idea three
Narrative & proseDocs →

Glossary

Term → definition rows.

SECTION 01 · Glossary
Idempotency
Doing a thing twice has the same effect as doing it once.
SLO
Service-level objective the team commits to.
Narrative & proseDocs →

Figure

An image with a caption in a bordered card (optional pixel width cap).

src: https://example.com/architecture.png
alt: The deployment topology
caption: "The production topology: CDN, gateway, and two service tiers."
width: 560
Narrative & proseDocs →

FAQ

Q&A accordions — native details/summary, no JavaScript.

SECTION 01 · FAQ

Common questions

Where does the content live?

In the .md files on disk — they are the single source of truth.

Do diagrams need a drawing tool?

No. Diagrams are typed YAML blocks; the renderer draws the SVG.

How do I validate a doc?

Run avo check and fix every diagnostic it reports.

Narrative & proseDocs →

Section divider

A full-width section break — kicker, display title, optional subtitle on an accent-washed band; a clean interstitial slide in decks.

SECTION 01 · Divider
PART 2
What we change

The three fixes, in the order we ship them.

Narrative & proseDocs →

Big number

One hero metric at presentation scale — a display-size value with an optional delta + trend arrow, a one-line claim, and a context line.

SECTION 01 · Big number
-75%-1.8s
Checkout p95 after moving capture off the request path

2.4s → 600ms, measured over four weeks of production traffic

Narrative & proseDocs →

Takeaways

The 2-6 things to remember — numbered rows at presentation scale, each a bold one-liner with an optional detail; a deck’s closing slide.

SECTION 01 · Takeaways
Takeaways
  1. The synchronous capture call was the bottleneck

    It accounted for 71% of the 2.4s checkout p95.

  2. Moving it to a queue cut p95 by 75%
  3. Conversion recovered within two weeks

    +0.4pp against the pre-regression baseline.

Narrative & proseDocs →

Tables & code

4 blocks

Table

Genuinely tabular data; cells can carry a tone.

SECTION 01 · Comparison
FieldDescription
nameDisplay name
idStable identifier
Tables & codeDocs →

KPI cards

KPI cards with a delta and an up / down / flat trend.

SECTION 01 · Metrics

This quarter

12.4k
Active users
▲ +18%
99.95%
Uptime
— 0
142ms
p95 latency
▲ -22ms
Tables & codeDocs →

Code snippets

One or more syntax-highlighted code snippets; `kind: diff` renders a unified diff, `kind: terminal` a shell session.

also: diff, terminal

SECTION 01 · Code

Reference

index.tsTypeScript
export function add(a: number, b: number): number {
  return a + b;
}
Tables & codeDocs →

SLOs & error budgets

Service-level objectives — SLI, target vs current, and an error-budget burn bar.

SECTION 01 · Service objectives

Orders API — objectives

Availability30d

Successful requests / total requests

Target99.9%
Current99.97%
25% of error budget used
Latency30d

Requests served under 400 ms (p99)

Target99%
Current98.9%
70% of error budget used
Tables & codeDocs →

API

3 blocks

API endpoint

A Swagger-style API endpoint card.

SECTION 01 · API endpoint

Create an order

POST/ordersBearer token

Submit a cart and create a new order.

Parameters
NameInTypeDescription
idempotency-keyheaderstringSafe-retry key
Request body
FieldTypeDescription
items requiredItem[]Line items
couponstringOptional discount code
Responses
StatusDescription
201Order created
400Invalid cart
401Missing or invalid token
Example request
{ "items": [{ "sku": "A1", "qty": 2 }] }
Example response
{ "id": "ord_123", "status": "pending" }
APIDocs →

Pull quote

A standout pull-quote with optional attribution.

SECTION 01 · Quote

The whole design in one sentence.

The takeaway
APIDocs →

Layered explanation

N numbered layers, each answering one question (L1 / L2 / L3).

SECTION 01 · Layers

The model in three layers

1
L1
Identity
JWT
Are you signed in?
Validate the token and resolve the user.
2
L2
Scope
Lookup
Which sites?
Confirm the request is in range.
3
L3
Permission
App DB
May you do this?
Check the action against the matrix.
APIDocs →

Architecture

7 blocks

C4 architecture

C4 model — context / container / component.

SECTION 01 · C4 model

System context

C4 · CONTEXT
C4 diagramPersonShopperA customer placing an order.Software SystemShopCoThe retail platform.External SystemPayment GWStripe authorisation.12
1places order2authorises
PersonSoftware SystemExternal System
ArchitectureDocs →

UML class diagram

A class diagram — attributes, methods, UML relationships.

SECTION 01 · Class model

Class model

UML
UML class diagramOrderid: UUIDstatus: Statustotal: Moneyplace()cancel()OrderItemid: UUIDsku: Stringqty: int«enumeration»StatusPENDINGCONFIRMEDCANCELLEDhas
ArchitectureDocs →

Component tree

A top-down component tree (root / layout / page / hook / store).

SECTION 01 · Component tree

React component tree

FE
Component treeAppLayoutHomeOrdersOrderCarduseOrdercartZustand
ArchitectureDocs →

Cluster topology

Kubernetes-style namespaces holding services, with replicas.

SECTION 01 · Cluster

Production cluster

CLUSTER
Cluster diagramapi namespacenamespacedata namespacenamespacewebNext.js×3ordersGo×4postgresPostgres 16×1redisRedis 7×2
ArchitectureDocs →

Block diagram

Generic boxes-and-arrows architecture (grid or layered bands); `preset: infra | event | ddd | network` picks the domain styling.

also: infra, event, ddd, network

SECTION 01 · Architecture

System architecture

ARCH
Block diagramServicesEdgeCDNCloudflareGatewayEnvoyAPIGoWorkerGoPostgres16EventsNATS
ArchitectureDocs →

Frontend logic graph

Frontend module graph — components, hooks, interfaces, strategies; `variant: be` renders the backend flavour (controller / service / repository).

also: belogic

SECTION 01 · Frontend logic

Frontend modules

LOGIC
Module graphuseOrders«service»ordersService«interface»OrdersClient«strategy»HttpOrdersClientOrders APIHTTPS
ArchitectureDocs →

Capability map

A target-architecture capability map — tinted domain areas packed with small status-coded capability tiles (current / target / new / gap / deprecated).

SECTION 01 · Architecture map

Target platform architecture

Customer channels
Web storefront
Mobile app
Commerce
Catalog
Checkout
Promotions
Platform services
Shared capabilities every domain builds on.
Identity
Event bus
Legacy ESB
CurrentTargetNewGapDeprecated
ArchitectureDocs →

Flows & state

7 blocks

Sequence diagram

Messages between actors over time (lifelines + returns).

SECTION 01 · Sequence
FLOW
Sequence diagramClientServer1request2response
Flows & stateDocs →

Flowchart

A decision flowchart with branches and error exits; `variant: dag` renders a pipeline DAG.

also: dag

SECTION 01 · Flowchart

Decision flow

FLOW
FlowchartStartIs valid?ProcessRejectDoneyesno
Flows & stateDocs →

State machine

A state machine — states + event transitions.

SECTION 01 · State machine

Order lifecycle

STATE
State machinePENDINGCONFIRMEDcreatepayship
FromEventGuardTo
s0create—PENDING
PENDINGpay—CONFIRMED
CONFIRMEDship—end
Flows & stateDocs →

Data-flow diagram

Data-flow — processes, external entities, and datastores.

SECTION 01 · Data flow

Data flow

DFD
Data-flow diagramClient1ProcessOrdersrequestwrite
Flows & stateDocs →

Swimlane diagram

A cross-functional process, one horizontal lane per role.

SECTION 01 · Process

Cross-functional flow

LANES
SwimlaneCustomerSalesOpsSubmit requestQualifyFulfillReceive
Flows & stateDocs →

How-to steps

A numbered how-to / runbook stepper — title, body, command, note per step.

SECTION 01 · Steps

Deploy a hotfix

  1. Branch from main

    Hotfixes always branch from the latest main.

    bash
    git checkout -b hotfix/fix-retry main
  2. Ship the fix

    Commit and push; CI runs the full suite.

    bash
    git push -u origin hotfix/fix-retry

    CI must be green before the next step.

  3. Tag and deploy
    bash
    git tag v1.4.1 && git push --tags
Flows & stateDocs →

Cycle

A closed loop of stages arranged in a circle — build–measure–learn, PDCA, an incident loop; step descriptions become a numbered legend.

SECTION 01 · Cycle

Build–measure–learn

CYCLE
Cycleevery releaseBuild1Measure2Learn3
1Build — Ship the smallest testable change2Measure — Watch the one metric the change should move3Learn — Keep the change or roll it back
Flows & stateDocs →

Data model

1 block

Entity-relationship diagram

Entities, columns, keys, and crow’s-foot relationships.

SECTION 01 · Entity model
ER
Entity-relationship diagramusersPKiduuidordersPKiduuidFKuser_iduuidplaces
Data modelDocs →

Charts & overviews

8 blocks

File tree

An indented file / folder hierarchy; `variant: issue` renders a MECE issue tree.

also: mece

SECTION 01 · Hierarchy
▸src
—components
—hooks
—index.tsentry point
Charts & overviewsDocs →

Pyramid

A layered pyramid, widening top → bottom.

SECTION 01 · Pyramid
PyramidVisionLong-term directionStrategyHow we get thereTacticsThis quarterTasksThis week
Charts & overviewsDocs →

User journey

A user journey across stages, with an emotion curve.

SECTION 01 · Journey

Onboarding journey

DiscoverSign upActivatePay
TouchpointLandingFormEmailCheckout
FrictionLowMedLowMed
Emotion
Emotion curve
Charts & overviewsDocs →

Gantt chart

A schedule — task bars across date columns.

SECTION 01 · Schedule

Roadmap

ScheduleQ1Q2Q3Q4DiscoveryBuildShipGA
Charts & overviewsDocs →

Node-link graph

A generic node-link graph with colour-cycled groups.

SECTION 01 · Graph

Dependency graph

GRAPH
GraphModule AModule BModule CShared
Charts & overviewsDocs →

Quadrant chart

A 2×2 matrix (e.g. effort vs impact) with plotted items.

SECTION 01 · Matrix

Effort vs impact

2×2
QuadrantEffort →↑ ImpactLowHighHighLowQuick winBig betFill-inThankless
Charts & overviewsDocs →

Data chart

A data chart — bar / line / area / donut / radar / waterfall / funnel, pure SVG, series coloured by accent.

also: waterfall, funnel

SECTION 01 · Chart

p95 latency by week

CHART
Chart0ms77.5ms155ms232.5ms310msW1W2W3W4
/orders/search
Charts & overviewsDocs →

Heatmap

A numeric grid with an intensity ramp — rows × columns of tiles tinted by value.

SECTION 01 · Heatmap

p95 latency by region

00
06
12
18
us-east-1
120
135
210
265
eu-west-1
110
150
240
190
ap-south-1
180
220
310
280
110 ms310 ms
Charts & overviewsDocs →

Planning & backlogs

13 blocks

User story

One agile story — role / want / soThat + acceptance criteria + links.

SECTION 01 · User story
As a user, I want to do the thing, so that I get the outcome.
Acceptance criteria
Givena preconditionWhenI actThenthe outcome
Planning & backlogsDocs →

Timeline

Phases in order with status dots (done / current / next / future).

SECTION 01 · Roadmap
now
Phase 1
What is happening now
next
Phase 2
What is next
Planning & backlogsDocs →

Kanban board

Flexible named columns of cards (Now / Next / Later).

SECTION 01 · Board
Now
Current task
Next
Upcoming task
Later
Eventually
Planning & backlogsDocs →

Pros & cons

Two columns weighed against each other — pros vs cons.

SECTION 01 · Trade-offs

Synchronous vs async

Synchronous
Easy to reason about
One transaction
Asynchronous
Latency-bound
Single point of failure
Planning & backlogsDocs →

Current vs target

Current → target, before / after panels.

SECTION 01 · Before / after

Migration plan

Today
Single monolith
Shared database
Manual deploys
→
Target
Modular services
Per-service stores
Automated deploys
Migrate one service per quarter.
Planning & backlogsDocs →

Meeting agenda

A meeting agenda — time, duration, owner, topic per row.

SECTION 01 · Agenda
09:00
30m
IntrosHost
09:30
45m
Status updates
Each team for 5 min
10:15
15m
Wrap-up
Planning & backlogsDocs →

Fancy list

A fancy bullet list — accent / check / icon / number marker styles.

SECTION 01 · List

What you get

  • Typed blocks76 strict schemas, validated by avo check.
  • One source of truthDiagrams live in the .md file.
  • Many outputsHTML, slides, and PDF from one file.
Planning & backlogsDocs →

Story backlog

A collapsible backlog of user stories (accordions) in one section.

SECTION 01 · User stories

Backlog

US-1One-step checkout5 ptsHigh

As shopper, I want pay for my cart in one step, so that I finish faster.

Acceptance criteria
  • Given I have items, when I submit valid payment, then an order is created.
US-2Save payment method3 ptsMed

As returning shopper, I want store a card, so that I skip re-entry.

Planning & backlogsDocs →

Design pattern

A design-pattern card — intent · forces · participants · consequences.

SECTION 01 · Pattern
PATTERNRepositoryBackend
Intent
Hide persistence behind a collection-like interface so the domain never sees the database.
Forces
Swap the data storeUnit-test without a DBNo query leaks into the domain
Participants
  • OrderRepositoryinterface the service depends on
  • PgOrderRepositoryPostgres implementation
  • OrderServicecaller (domain logic)
Consequences
  • +Swappable storage
  • +Testable with a fake
  • +Clear seam
  • −Another layer
  • −Risk of anemic pass-through methods
Planning & backlogsDocs →

Card gallery

A responsive grid of cards — code snippets or notes (e.g. a bug gallery or comparison).

SECTION 01 · Gallery

Bug gallery

A grid of code snippets — great for a comparison or a "spot the bug" set.

N+1 queryJavaScript
users.forEach(async u => {
  await db.query("SELECT * FROM orders WHERE user_id=?", u.id);
});
1000 users = 1001 queries. Fix: JOIN or batch.
Off-by-oneJavaScript
for (let i = 0; i <= arr.length; i++)
  process(arr[i]);
arr[arr.length] is undefined. Fix: < not <=.
Secrets in codeJavaScript
const API_KEY = "sk-live-abc123";
Committed to the repo. Fix: env vars + a scanner.
Planning & backlogsDocs →

Changelog

Release history on a vertical rail — version pills, dates, and typed change chips.

SECTION 01 · Changelog

Release history

2.0.02026-06-24breaking
changedConfig moved from .rc to avodado.config.json
removedDropped Node 18 support
1.4.02026-05-12minor
addedDark theme
fixedSlide overflow on long tables
Planning & backlogsDocs →

Risk register

A risk register — severity derived from likelihood × impact, with mitigation, owner, and status.

SECTION 01 · Risk register

Launch risks

highTraffic spike overwhelms the APIPlatformmitigating
L: med · I: high

Mitigation: Autoscaling + load-shedding at the gateway.

highData migration misses edge casesDataopen
L: low · I: high

Mitigation: Dry-run against a prod snapshot.

mediumDocs lag the releaseaccepted
L: med · I: low
Planning & backlogsDocs →

Status table

Task table with an update column, user-defined colored status pills, and optional subtasks per row; `variant: tracker` renders the classic task-tracker list.

also: tracker

SECTION 01 · Status

Workstream status

TaskUpdateStatus
Payment retriesBackoff logic merged; canary running since Mondayshipped
Vendor SSOContract countersigned; sandbox creds due this weekwaiting on vendor
SAML metadata exchangeOur metadata sent Tuesdayshipped
Provisioning syncBlocked on sandbox credentialswaiting on vendor
Rate-limit reworkPR up for second reviewin review
Planning & backlogsDocs →

Business & decisions

12 blocks

Capability matrix

A role × resource capability grid; cells tint by permission level.

SECTION 01 · Capability matrix

Who can do what

Role / AppBillingReportsAdmin
OwnerFullFullFull
ManagerFullRead—
ViewerReadRead—
Business & decisionsDocs →

Anatomy breakdown

The labelled parts of a delimited string (app:feature:action).

SECTION 01 · Anatomy

Anatomy of a permission

meridian:billing:invoices.read
App
meridian
Which product.
:
Feature
billing
The area within the app.
:
Action
invoices.read
The specific capability.
Business & decisionsDocs →

Access composition

Effective access as intersected gates (A ∩ B ∩ C = result).

SECTION 01 · Composition

How access is decided

Identity
A valid signed-in user.
∩
Scope
The request is in range.
∩
Permission
The action is granted.
=
Effective
May read invoices
Business & decisionsDocs →

Design drivers

A grid of factor cards — the forces that shaped a design.

SECTION 01 · Drivers

What shaped the design

Single sign-on
One login carries the user everywhere.
HOW: token
Read per site
Access is scoped to the sites a user belongs to.
WHERE: site group
Governed roles
An external IGA requests, approves, and certifies access.
WHO: role groups
Per-app permissions
The same role does different things in each app.
WHAT: matrix
Business & decisionsDocs →

Options considered

Approaches explored — pros / cons / verdict; the chosen one highlighted.

SECTION 01 · Options

Approaches explored

Option 1App-managed roles
Roles live in our own DB; SSO only handles sign-in.
  • Full control
  • Second source of truth
  • Custom tooling to govern
REJECTED — fails the constraint
Option 2Global role groups
Site groups for read; one global group per role.
  • Fewest groups
  • Scales linearly
  • A role applies at every site
VIABLE — kept as fallback
Option 3Per-site role groups
One group per persona per site.
  • Least privilege by construction
  • Clean per-site audit
  • Most groups to manage
CHOSEN — matches the constraints
Business & decisionsDocs →

Spec sheet

A labelled spec sheet — label → value rows (a value can be a step-flow).

SECTION 01 · Spec

Per-site role groups

Groups
SiteN-Users (read) + SiteN-<Persona> per staffed plant.
Roles
Each group reads as (site, role); the token carries the full scope.
Resolution
Decode token→Read (site, role)→Check matrix
Cost
Up to Sites x Roles groups; adding a role multiplies them.
Business & decisionsDocs →

Back-of-envelope math

Back-of-envelope capacity math — assumptions, derivation rows, a highlighted bottom line.

SECTION 01 · Capacity math

Write-path capacity

Daily active users
5M
Writes / user / day
4
Writes per day5M × 420M/day
Write QPS20M / 86,400 s≈ 230 rps
Peak QPS230 × 3 (peak factor)≈ 700 rps
Provision for
~1,400 rps (2× peak headroom)
Business & decisionsDocs →

SWOT analysis

A classic SWOT 2×2 — strengths, weaknesses, opportunities, threats as tinted quadrant cards.

SECTION 01 · SWOT

Entering the enterprise segment

Strengths
  • Fastest onboarding in the category
  • Strong developer community
Weaknesses
  • No SSO / SCIM yet
  • Small support team
Opportunities
  • Competitor sunsetting its legacy plan
  • Compliance push creates demand
Threats
  • Incumbent bundling a free tier
  • Procurement cycles slow adoption
Business & decisionsDocs →

OKRs

Objectives and key results — one card per objective, a status-coloured progress bar per KR.

SECTION 01 · Objectives

Q3 objectives

Make onboarding effortlessGrowth
Time-to-first-doc under 5 minutes
70%
Activation rate from 45% to 60%
40%
Earn enterprise trustPlatform
Ship SSO + audit log
100%
SOC 2 Type II report issued
20%
Business & decisionsDocs →

User personas

User persona cards — avatar, role, quote, goals, frustrations, and tools.

SECTION 01 · Personas

Who we build for

MC
Maya Chen
Staff engineer
I want the diagram in the PR diff, not in a wiki.
Goals
  • Docs that live with the code
  • Reviewable architecture changes
Frustrations
  • Stale wiki pages
  • Screenshots of whiteboards
Tools
VS CodeGitHub
PP
Priya Patel
Engineering manager
Every reorg breaks our onboarding docs.
Goals
  • One source of truth per system
Frustrations
  • Docs no one owns
Tools
LinearNotion
Business & decisionsDocs →

Team cards

Compact people cards — initials avatar, name, role, and focus area.

SECTION 01 · Team

Who owns what

AR
Ana Ruiz
Tech lead
Rendering pipeline
SO
Sam Okafor
Backend
Sync + integrations
LF
Lena Fischer
Design
Themes and house style
Business & decisionsDocs →

Decision scorecard

A weighted decision matrix — criteria rows × option columns, totals footer, winner highlighted.

SECTION 01 · Decision matrix

Queue technology choice

CriteriaKafkaWINNERself-hostedSQSWINNERmanaged
Throughput×253
Operational cost25
Team familiarity34
TOTAL1515
Business & decisionsDocs →

Design system

5 blocks

Wireframe

Low-fi UI mockups inside device frames (desktop / browser / phone).

SECTION 01 · Mockup

What the user sees

UI
UI mockupapp.example.comHomeInboxSettingsNotificationsMark all as readDesktop9:41100%AlertsHomeSearchBellYouiPhone
Design systemDocs →

Color palette

Color-token swatches on a card grid — hex value, name, and usage per color.

SECTION 01 · Palette

Brand palette

#0E54A1
Primary
Buttons and links
#1F2937
Ink
Body text
#F6F8FB
Surface
Card backgrounds
#1F9747
Positive
Success states
Design systemDocs →

Type scale

A live type specimen — one row per style, the sample rendered at its real size, weight, and font.

SECTION 01 · Type scale

Type scale

Display
40px / weight 700
The quick brown fox jumps over the lazy dog
Body
15px / weight 400
The quick brown fox jumps over the lazy dog
Caption
12px / weight 500
secondary text
The quick brown fox jumps over the lazy dog
Code
13px / weight 400
The quick brown fox jumps over the lazy dog
Design systemDocs →

Do / don't guide

Do / don’t guideline cards — a green DO and a red DON’T column, with optional mono examples.

SECTION 01 · Guidelines

Button usage

✓Do
Use one primary button per view
Write labels as verbs
Save changes
✕Don't
Stack two primary buttons side by side
Disable a button without explaining why
tooltip: Add a line item first
Design systemDocs →

Component inventory

A component / feature status board — compact rows with a color-coded stable / beta / experimental / deprecated / planned chip.

SECTION 01 · Inventory

Component status

Buttonv2
stable
Data table
API may change before GA
beta
Date picker
experimental
Modal (legacy)
Use Dialog instead
deprecated
Charts
planned
Design systemDocs →

Algorithms

4 blocks

Array walkthrough

Array cells for algorithm walkthroughs — tones, pointer labels below cells, and a dashed index-window highlight.

SECTION 01 · Array

Binary search — step 2

ARRAY
Array0317212319427541lomidhisearch space
AlgorithmsDocs →

Linked list

A pointer-chain diagram (singly or doubly) — boxed nodes, next/prev arrows, node markers, and a ∅ terminator.

SECTION 01 · Linked list

Reversing a list — step 2

LIST
Linked list∅9471prevcurrnext
AlgorithmsDocs →

Binary tree

A binary tree — nodes placed by parent + side, tinted to show search paths, traversals, and heap shapes.

SECTION 01 · Binary tree

BST search for 27

TREE
Binary tree198312740
AlgorithmsDocs →

Hash map

Hash buckets with chained entries — collision chains read left → right as key/value pills; tones highlight probes.

SECTION 01 · Hash map

Chained hash table

HASH
Hash map0apple: 31—2plum: 9grape: 13—4fig: 7
AlgorithmsDocs →

AI & agents

4 blocks

Agent loop

The canonical LLM agent loop — environment → agent (model chip) → tools, with memory and a stop condition.

SECTION 01 · Agent loop

Support triage agent

AGENT
Agent loopCustomerTriage agentclaude-sonnet-4-6Routes each ticket to a fixor a human.search_kbSearch help-centerarticlesget_accountLook up plan andbilling statecreate_ticketEscalate to a humanqueue1prompt4response2tool call3resultread/writememoryconversation historycustomer profile
stops when: reply sent or ticket escalated
AI & agentsDocs →

Agent trace

An agent execution transcript — user / assistant / tool / system turns, with thinking and tool args → result.

SECTION 01 · Trace

Password reset — one episode

USER
I never get the reset email.
ASSISTANT
Could be a bounce — check delivery logs before blaming spam.
Let me check our email logs.
TOOL
email_logs.search
args:{ "to": "sam@example.com", "type": "password_reset" }
→1 result: bounced (mailbox full)
ASSISTANT
Your mailbox rejected the email — free up space and I will resend it.
AI & agentsDocs →

Prompt anatomy

Prompt anatomy — stacked role segments (system / user / assistant / tool) with highlighted {{variable}} chips and a legend.

SECTION 01 · Prompt

Support reply template

SYSTEM— role + guardrails
You are a support agent for {{product}}. Answer from the docs only.
USER
Customer ({{plan}} plan) asks: {{question}}
{{product}}Product name from config
{{plan}}Plan tier of the signed-in customer
{{question}}The inbound message
AI & agentsDocs →

Context-window budget

A context-window token budget — one stacked bar sized against the window, with free space and over-budget overflow.

SECTION 01 · Context window

Where the window goes

CONTEXT
Context windowwindow: 200,000 tokens12retrievalhistoryfree (50,000)
1system prompt6,000 tokens · 3%
2tool schemas14,000 tokens · 7%
3retrieval60,000 tokens · 30%
4history70,000 tokens · 35%
AI & agentsDocs →