The Glossaries

104 terms·7 glossaries·13 groups

104 terms

ALLAt a glance

AGENTAgentsVocabulary to use when developing agents (coding agents, design agents, embedded agents, etc.).

PARTPartsWhat an agent is made of.

PART-01

agent

harness + model + tools + policy. Never the model alone.

agents.md
Agent: harness, model, tools and policy in one box, the workspace beside itAgent: harness, model, tools and policy in one box, the workspace beside it
PART-02

model

The LLM, identified by a string (claude-opus-5). Stateless: one context in, one message out.

agents.md
Model: a context in, one message out, nothing remembered between callsModel: a context in, one message out, nothing remembered between calls
PART-03

harness

The code that runs the loop: builds context, calls the model, executes tools, appends results, stops.

agents.md
Harness: the loop of building the context, calling the model, running the tools, appending, stoppingHarness: the loop of building the context, calling the model, running the tools, appending, stopping
PART-04

tool

A named operation the model may request. The model sees its definition; the harness owns its implementation.

agents.md
Tool: the definition the model sees, the implementation the harness ownsTool: the definition the model sees, the implementation the harness owns
PART-05

policy

Text in the system message that constrains behavior. Read, not enforced. Enforcement is permission, gate and sandbox.

agents.md
Policy: text the model reads; what must not happen is stopped by permission, gate and sandboxPolicy: text the model reads; what must not happen is stopped by permission, gate and sandbox
PART-06

skill

Instructions loaded into context on demand, not resident in every call.

agents.md
Skill: instructions on a shelf, loaded into the context only when asked forSkill: instructions on a shelf, loaded into the context only when asked for
PART-07

workspace

What tools act on: a repo, a canvas, an app database.

agents.md
Workspace: a repository, a canvas or an app database, what the tools act onWorkspace: a repository, a canvas or an app database, what the tools act on

ROLERolesWho stands outside the loop.

TIMETimeFrom one call to a whole session.

TIME-02

round

One call plus execution of the tool_calls it returned. Zero tool_calls for a final.

agents.md
Round: one call plus the tool_calls it returnedRound: one call plus the tool_calls it returned
TIME-03

turn

One user message, or one scheduled task, through to its last final: one round or many. The checks after a final belong to the same turn: when the tests fail, the harness sends the failure back and the fixing goes on in the same turn, so max_rounds and the budget cover it too (MP-60).

agents.md
Turn: one user message through to the final, one or many roundsTurn: one user message through to the final, one or many rounds
TIME-05

run

One launch of the harness process (CLI invocation, cron job).

agents.md
Run: one launch of the harness, holding the sessionRun: one launch of the harness, holding the session

MSGMessagesWhat the transcript holds and a call sends.

MSG-01

message

One unit of the transcript. Has a role: system, user, assistant, tool.

agents.md
Message: one unit of the transcript with its roleMessage: one unit of the transcript with its role
MSG-02

transcript

Every message of the session so far, append-only. Includes tool_calls and tool_results.

agents.md
Transcript: every message so far, append-onlyTranscript: every message so far, append-only
MSG-03

context

What surrounds a thing and gives it its meaning: the sentence around a word, the conversation around a message, the project around a file. The same words mean different things in different contexts, so the context is read first and the thing after.

For an AI model, the context is the context window: everything it reads before it answers, counted in tokens. One call sends it whole: the system message, the tool definitions, the transcript or its compacted form, the grounding. The model has nothing else: what is not in the context does not exist for it, and what falls out of it (compacted away, or left behind when a session ends) is gone unless it was written down somewhere it will be read again, a note, a file, a database.

agents.md
Context: system message, tool definitions, the transcript or its summary, grounding, sent whole to the modelContext: system message, tool definitions, the transcript or its summary, grounding, sent whole to the model
MSG-04

sidecar

A second payload carried beside a message, never merged into it: the untruncated tool output, file handles, timings. The request goes over the wire; the sidecar stays with the harness.

agents.md
Sidecar: the small message over the wire, the large payload kept by the harnessSidecar: the small message over the wire, the large payload kept by the harness
MSG-05

memory

What outlives one context: the transcript, plus external stores (notes, a database).

agents.md
Memory: the transcript, notes, files and databases that outlive one contextMemory: the transcript, notes, files and databases that outlive one context
MSG-06

system

The message that holds the policy. Tool_definitions travel beside it, not in it.

agents.md
System: the message holding the policy, the tool definitions beside itSystem: the message holding the policy, the tool definitions beside it
MSG-08

tool_result

Harness → model: output or error of one tool_call, paired by id. Data, never instructions.

agents.md
Tool result: output or error back to the model, paired by id, data not instructionsTool result: output or error back to the model, paired by id, data not instructions
MSG-09

final

An assistant message with no tool_call. It ends the turn once the checks after it pass; when a check fails, the failure goes back and another final comes later in the same turn. A final says nothing about whether the task succeeded. final is our name, not an API's (MP-60).

agents.md
Final: an assistant message with no tool_call ends the turn; its claim still needs a checkFinal: an assistant message with no tool_call ends the turn; its claim still needs a check
MSG-10

stop_reason

Why a call ended: final, tool_call, max_tokens, refusal. These are our own names; each API spells them its way. Anthropic's stop_reason says end_turn for a final, tool_use for a tool_call, max_tokens and refusal; OpenAI's finish_reason says stop, tool_calls, length and content_filter (MP-60).

agents.md
Stop reason: final, tool_call, max_tokens or refusalStop reason: final, tool_call, max_tokens or refusal

TOOLToolsWhat the model may request, and what contains it.

TOOL-01

tool_definition

name + description + input_schema. What the model sees. The description is what makes the model pick it.

agents.md
Tool definition: name, description and input schemaTool definition: name, description and input schema
TOOL-03

readonly

Observes only: view, grep, query. Declared at registration; a tool is classed by the worst its arguments allow.

agents.md
Readonly: the three classes of tools, readonly highlightedReadonly: the three classes of tools, readonly highlighted
TOOL-06

permission

What the harness lets a tool touch: paths, hosts, commands. Enforced before the tool runs.

agents.md
Permission: a tool_call outside the allowed paths is refused before it runsPermission: a tool_call outside the allowed paths is refused before it runs
TOOL-07

gate

User approval required before a tool runs. Default for destructive.

agents.md
Gate: the harness asks the user before a destructive tool runsGate: the harness asks the user before a destructive tool runs
TOOL-08

sandbox

The boundary that contains a tool's effects: files, network, processes.

agents.md
Sandbox: files, network and processes inside the boundary, the machine outside itSandbox: files, network and processes inside the boundary, the machine outside it
TOOL-09

grounding

Workspace state the harness injects into context each turn.

agents.md
Grounding: the state of the workspace, injected into the context each turnGrounding: the state of the workspace, injected into the context each turn

LIMLimitsCaps, and what is cut to fit them.

LIM-02

budget

Token, time or cost cap, scoped to a turn, run or session.

agents.md
Budget: token, time and cost bars, scoped to a turn, run or sessionBudget: token, time and cost bars, scoped to a turn, run or session
LIM-03

truncate

Cut one tool_result to fit. The full output stays in the sidecar.

agents.md
Truncate: one result cut to fit, the whole of it in the sidecarTruncate: one result cut to fit, the whole of it in the sidecar
LIM-04

compact

Replace the older part of the transcript in context with a summary. The replaced messages stay in the transcript and in the sidecar.

agents.md
Compact: older messages replaced by a summary in the context, kept in the transcriptCompact: older messages replaced by a summary in the context, kept in the transcript

FAILFailureHow a turn goes wrong.

FAIL-01

stall

Rounds continue without progress. Reading counts as progress; repeating the same call does not.

agents.md
Stall: the same call five times, nothing movesStall: the same call five times, nothing moves

RECOVRecoveryWhat follows a final.

RECOV-01

check

The harness runs the tests or the linter after a final and, on a failure, sends it back to the model. It extends the turn: the turn ends at the last final, once the checks pass (MP-60).

agents.md
Check: tests run after the final; a failure goes back as another roundCheck: tests run after the final; a failure goes back as another round
RECOV-02

review

One extra call asking a model to inspect the result against the task. Same model, another agent, or a human.

agents.md
Review: one extra call reads the task and the result and gives a verdictReview: one extra call reads the task and the result and gives a verdict
RECOV-03

handoff

Agent stops and passes the task and its context to the user or to another agent.

agents.md
Handoff: the task and its context passed whole to the user or another agentHandoff: the task and its context passed whole to the user or another agent

KINDKindsAn agent is named by its workspace.

KIND-01

coding agent

workspace = repo; tools = view, grep, edit, shell.

agents.md
Coding agent: workspace a repository, tools view, grep, edit, shellCoding agent: workspace a repository, tools view, grep, edit, shell
KIND-02

design agent

workspace = canvas or artifact; tools = inspect, render, place, style.

agents.md
Design agent: workspace a canvas, tools inspect, render, place, styleDesign agent: workspace a canvas, tools inspect, render, place, style
KIND-03

embedded agent

workspace = app data via the app's API; scope enforced by the app's access controls.

agents.md
Embedded agent: workspace app data through its APIEmbedded agent: workspace app data through its API

TESTTestingWords for failures, and for the tests that find them.

TEST-02

Smoke Tests

A small set of basic tests that verify whether the most critical parts of a system work at all. They answer one question: Does the application run without immediately breaking? If smoke tests fail, deeper testing is usually pointless. (Why "smoke"? From hardware: Power it on – if smoke comes out, something is seriously broken.)

testing.mdwikipedia
Smoke tests: power on, does it run at all; the deep tests wait behindSmoke tests: power on, does it run at all; the deep tests wait behind
TEST-03

Edge Case

A situation at an extreme of the input – an empty list, the first or the last item, the maximum size – where code written for the usual case breaks.

testing.mdwikipedia
Edge case: the usual range in green, the empty, first, last and maximum in redEdge case: the usual range in green, the empty, first, last and maximum in red
TEST-05

Intermittent Failure

A failure of the application that happens sometimes, unpredictably, and usually cannot be reproduced consistently. Request #1 works, request #2 fails, request #3 works again — even though nothing was changed. A test that fails this way is a flaky test.

Common causes: timing issues and race conditions, network instability, concurrency issues (threads or processes interfering), uninitialized values, hardware flakiness (bad RAM, overheating), resource limits hit sometimes (a connection pool exhausted).

Painful because it does not fail every time, logs often do not show a clear cause, and "works on my machine" happens a lot.

testing.md
Intermittent failure: six requests to the same code, two of them failing, nothing changedIntermittent failure: six requests to the same code, two of them failing, nothing changed
TEST-06

Error Flood

Provisional: not defined yet. The author's note reads "a scenario with 75% errors", a working name kept until the author settles what it means (MP-62).

testing.md
Error flood: forty requests, thirty of them failedError flood: forty requests, thirty of them failed
TEST-07

Flaky Test

A test that passes and fails by turns with no change to the code or to the test. The fault is in the test (a fixed timeout, an order it relies on) or an intermittent failure under it.

testing.md
// Sometimes fetch() returns slow, causing timeout.
// Sometimes it's fast. So the test occasionally fails.
test("API returns data", async function () {
    const response = await fetch("/api/data");
    expect(response.ok).toBe(true);
});
Flaky test: one unchanged test, red and green by turns through the weekFlaky test: one unchanged test, red and green by turns through the week
TEST-08

Showstopper Bug

A defect so severe that it prevents the system from functioning or blocks further progress (development, testing, or release). Work cannot reasonably continue until it is fixed.

testing.md
Showstopper bug: the road from development to customers blocked by a barrierShowstopper bug: the road from development to customers blocked by a barrier
TEST-09

Self-check

The application checks, by itself, that it is fit to work, as a car checks itself on the dashboard: one lamp per thing it needs, dark when that thing is there and works, lit when it is not. The lamps are the programs it calls, the environment variables, the folders it writes, the port, the versions, and what its own build was to produce. A lit lamp is the whole answer: the application is not fit, and the lamp names what to fix. It changes nothing: a self-check reads and reports. When every lamp is dark it says one line or nothing; when one is lit it names it and stops, before any work is half done.

It runs where there is something new to check: the last step of the build (PROJ-30), so an image that fails it is never shipped; and again as the first step of the run when the host may differ from the build, so a host that fails it does no work. One probe per lamp, each in its own strict shell, its output prefixed with the lamp's name, so the log says which one lit. Present is not enough: a probe exercises the tool the way the application will use it (a font subset must come out smaller with zopfli; a time zone the data uses must be known to the runtime), for the usual failure is a tool that is there and misconfigured.

Beside its neighbours: bin/configure makes the environment, the self-check tells whether it is as made (PROJ-02). A smoke test asks the same question from outside, by a test run now and then; the self-check is asked by the application itself, on every build or start. A health check is the probe of a running service, asked again and again; the self-check runs once.

Self-check, not self-test: a test is run against the code, by bin/test; a check is what the application does to itself and its surroundings, as a driver reads the dashboard before setting out. The command is bin/self-check, named for who checks: the application, not a tester from outside. A script named for one lamp, check-env for the environment, is one lamp of it; the self-check is the whole dashboard, and the build's last step adds the lamps of its own output, the folders it was to produce.

testing.md
# bin/build, the last step (PROJ-30)
bin/self-check

# bin/self-check: one lamp per thing, one shell each
bash -ue -o pipefail << 'EOF' 2>&1 | ts -s '[ffmpeg]'
    ffmpeg -version
EOF

bash -ue -o pipefail << 'EOF' 2>&1 | ts -s '[pyftsubset]'
    pyftsubset font.woff --text=12345 \
        --flavor=woff --with-zopfli --output-file=a
    pyftsubset font.woff --text=12345 \
        --flavor=woff --output-file=b
    test $(stat -c %s a) -ne $(stat -c %s b)
EOF

test -e build/front.d    # what the build was to produce
Self-check: a dashboard of lamps, one lit, naming the port to fixSelf-check: a dashboard of lamps, one lit, naming the port to fix
TEST-10

Safety net

The net under the trapeze: the act is done without it, and nobody falls on purpose, but when someone does, the net is what holds. In software, a second mechanism, independent of the first, that catches what the first lets through and limits the damage: a timeout behind a request that should return, a cap on a loop that should end, a job that puts back what a step should have put back. It is not the way things are meant to work; it is what holds when they do not.

An example: an agent is switched to the strongest model for one message, and the reply is meant to switch it back. The safety net: if the agent is still on the strongest model ten minutes after that message's reply, the app switches it back itself and says so in the log. The switch-back after the reply is the plan; the ten-minute check is the net.

Beside its neighbours: a self-check asks before the work whether the application is fit; an integrity check asks after it whether the data is still whole; a safety net sits under the work itself and acts when the first mechanism did not. A fallback is a second way to the same result; a safety net does not finish the job, it stops a miss from spreading. A good net is simple and independent, so it cannot fail for the same reason as what it guards, and it says when it caught something: every catch is a sign that the first way failed, and worth a look.

testing.md
// the plan: the reply switches the model back
// the net: ten minutes on, the app does it itself
const late = now - reply.at > 10 * MINUTE;
if (late && (agent.model === strongest)) {
    agent.model = agent.default_model;
    log.warn('safety net: switched the model back');
}
Safety net: the plan as a rope across, the miss falling into the net belowSafety net: the plan as a rope across, the miss falling into the net below
TEST-11

Robustness

How well a program keeps behaving right off the happy path. The happy path is the road where everything goes as meant; robustness is what the program does on every way off it: a field left empty, the network down, the server saying no, empty data, two clicks where one was expected. A robust program answers each one with something the person can act on (it names the field, keeps the text and retries, says why) instead of a crash, a blank screen or a spinner that never stops.

testing.mdwikipedia
Robustness: the happy path's road, each way off it ending in an answerRobustness: the happy path's road, each way off it ending in an answer
TEST-12

Hardening

The work on robustness, and its place in the order of work. Build the happy path first, because the result is what matters: a form that saves, a page that shows. Once it runs, harden it: take the ways off it one by one and give each its answer. The urge is to handle every case at once, before anything works; it leaves nothing working for a long time, and the cases are guessed before the running result shows which ones really happen.

Then verification (TEST-14): before the word done, the result is run and looked at, its states tried, beside what was asked.

testing.md
Hardening: the happy path works, then hardening, then robust; every case at once leaves nothing workingHardening: the happy path works, then hardening, then robust; every case at once leaves nothing working
TEST-13

Fault Tolerance

A part of the system breaks and the whole keeps running: one server of three is down and the requests go to the other two; a disk fails and its mirror carries on. Fault tolerance is one kind of robustness, the one about the program's own parts failing; robustness also covers what comes from outside, the input and the people.

testing.mdwikipedia
Fault tolerance: one server of three down, the request still answeredFault tolerance: one server of three down, the request still answered
TEST-14

Verification

The last step of the order of work: the happy path runs, hardening gives the ways off it their answers, and before the word done the result is checked against what was asked. Checked by running, not by reading: the command run to its end and its output read, the page opened and looked at, every state tried, the request read again beside the result. What was not run was not verified, and a command started is not a check passed. It ends in evidence someone else can see: the screenshot, the test that passed, the output.

Beside its neighbours: a smoke test asks whether it runs at all; verification asks whether this change does what was asked. Validation, its usual pair, asks whether what was asked is the right thing: verification, built right; validation, the right thing built. A self-check is the application checking itself; verification is whoever did the work checking it.

testing.md
Verification: the happy path, hardening, then verification before done; done said on a command only started leaves the author to find what brokeVerification: the happy path, hardening, then verification before done; done said on a command only started leaves the author to find what broke

WORDDocumentsWords about words.

WORD-02

glossary

The words of a vocabulary, with their description and meaning.

README.md
Glossary: a table of terms, each with its meaningGlossary: a table of terms, each with its meaning
WORD-03

dictionary

Every word of a language, or of a whole field, in alphabetical order, each with all its meanings, its part of speech and how it is used. Where a glossary keeps only our words and the one meaning we give each, a dictionary keeps every word and every meaning; a glossary is chosen, a dictionary is complete. In code a dictionary is something else: a map from keys to values (user_by_id).

README.md
Dictionary: process, provider and proxy under P, process with two numbered meaningsDictionary: process, provider and proxy under P, process with two numbered meanings

MAPMaps and waysWords for the shapes knowledge takes, and for the way a piece of work goes: where we are, where we came from, where we are going.

MAP-01

tree

One root, and every other node has exactly one parent, so there are no circles and exactly one path from the root to any node. Folders, an outline, an org chart, a family line.

In the agent notes: the folders of a note (agentdir, commondir, messages, roadmaps). A thread is a tree as long as each message answers one message.

A tree is a graph with rules; a taxonomy is a tree of kinds.

maps.md
Tree: the folders of a noteTree: the folders of a note
MAP-02

graph

Things (nodes) and the links between them (edges), directed or not, with no rule on how they link: a node may have several parents, and links may run in circles.

The pages of this site are a graph: the README links to Rules and to Glossaries, Rules links to Glossaries, Glossaries to Agents, and Agents back to Rules. Glossaries has two parents, and three pages link in a circle; a tree allows neither.

Trees, taxonomies and ontologies are all graphs with rules added.

maps.md
Graph: the pages of this site and the links between them, one page with two parents and three pages in a circleGraph: the pages of this site and the links between them, one page with two parents and three pages in a circle
MAP-03

map

A smaller picture that keeps what matters of something bigger: where things are and how they connect. "The map is not the territory": a map leaves things out on purpose. In code, a map (a dictionary) goes from keys to values, one value per key. Also a mind map, a concept map, a site map.

In the agent notes: a roadmap is a map of the way; "the terms and how they relate" below is a concept map; a glossary maps each term to its meaning.

maps.md
MapMap
MAP-04

taxonomy

Sorting into kinds and kinds of kinds, each one "is a" the one above it: animal › bird › owl. Linnaeus for living things, the shelves of a library.

In the agent notes: a message is the author's or the agent's; a page is a subject file, a cover or a plan; a marker is .working or .cancelled.

A taxonomy is a tree, and the backbone of an ontology, which adds the other links.

maps.md
Taxonomy: the kinds of things in a noteTaxonomy: the kinds of things in a note
MAP-05

ontology

In philosophy, the study of what exists. In computing, a written map of what a field talks about, in four parts: the kinds of things (a message, a conversation, a subject file), the things themselves (your message of this morning asking for a glossary is a message), the relations between them (a conversation is made of messages; a reply answers a message) and the rules (every conversation has exactly one subject file). It is written down so that people and programs use the words the same way: RDF and OWL are the standards, Schema.org the best known on the web.

A glossary defines words one by one; an ontology also says how they connect. Written down once, a rename (workdir became subjectdir) happens in one place, and an agent can check a word against it.

maps.md
Ontology: the words of a note and how they connectOntology: the words of a note and how they connectThe terms of this glossary and how they relateThe terms of this glossary and how they relate
MAP-06

knowledge graph

An ontology filled with real things: not "a reply answers a message" in general, but "my reply of 09:30 answers your message of 09:17", one link for each pair that has it. What search engines and AI retrieval use.

In the agent notes: every message, subject file and plan of a note with their links; the app could build it, and it would feed an agent's context.

maps.md
Knowledge graph: the ontology on the left, this note's real messages and links on the rightKnowledge graph: the ontology on the left, this note's real messages and links on the right
MAP-07

roadmap

The whole way ahead: where we are going and in what order, not exactly when. A product roadmap is often three columns, Now / Next / Later. It changes as we learn, and it is meant to be shown, so it stays coarse: themes and stages, not tasks.

In the agent notes: an agent's plan for one conversation, roadmaps/<time>-agent-plan.md, its parts - [ ] **P1** … ticked as each is done, new ones added at the end; and the author's roadmaps in the app, lists of work across projects.

A roadmap is laid on a timeline, marked by milestones and fed by a backlog.

maps.md
RoadmapRoadmap
MAP-08

milestone

The Roman stone by the road that said how far it was to Rome. In a project, a point that is reached or not ("Released", "Signed"); it takes no time, unlike a task. A diamond on a Gantt chart; on GitHub, a group of issues with a due date.

In the agent notes: the goal's steps in a subject file, drawn under the cover: done, now or next. The step that is now waits on the agent while it works and on the author after its reply; a step is named as it stands ("Testing" while now, "Tested" once done); the last is always "Done: nothing left, to the archive".

maps.md
MilestoneMilestone
MAP-09

breadcrumbs

The trail that shows where you are and how you got there, as in Hansel and Gretel; on a web page, Home › Docs › Page, each crumb a link back up.

Against roadmap and milestone: breadcrumbs look back (the way behind, from the root to here), a roadmap looks ahead (the whole way, in order), and a milestone is one stone on that way. A milestone passed is, in effect, a breadcrumb.

In the agent notes: the path agentdir › commondir › Terms, and the chain of Re: lines back to a conversation's first message.

maps.md
Breadcrumbs, roadmap and milestone side by sideBreadcrumbs, roadmap and milestone side by side
MAP-10

timeline

Events placed along time. In the agent notes: the change log at the end of each subject file, and the times in message names. A roadmap is laid on one.

maps.md
Timeline: the events of this morning along one lineTimeline: the events of this morning along one line
MAP-11

chronology

Events in the order they happened, each with its date or time, at even steps: the order and the times count, not the distance between them. It fits what a user did over time: first one thing, then another, then a third. A long gap is cut short, its length written on the cut.

In the agent notes: a conversation's messages, first to last, each with its time in its name.

A timeline puts each event at its moment, so the gaps show; in a chronology a night between two visits takes no more room than a minute.

maps.md
Chronology: one user's seven actions evenly along a line, from opening the pricing page to upgrading the next day, the 23-hour night cut shortChronology: one user's seven actions evenly along a line, from opening the pricing page to upgrading the next day, the 23-hour night cut short
MAP-12

backlog

The work known but not yet planned, in no fixed order. In the agent notes: the "what is next" list of a subject file, the parts not yet on a roadmap. It feeds a roadmap.

maps.md
Backlog: a pile of cards in no order, and the three columns of the roadmap they feedBacklog: a pile of cards in no order, and the three columns of the roadmap they feed
MAP-13

anatomy

The parts of one thing, seen whole: each part named where it sits, in the thing it belongs to. Borrowed from biology (the anatomy of a hand), it is common in computing: the anatomy of a button (a container, an icon on the left, a label beside it), of a URL (scheme, host, path, query, in that order), of a log line or of a file. Design systems give each component page an Anatomy section: the component drawn once, each part numbered in place, the names beside.

In the agent notes: a message as the app shows it, its header on top, its text, a voice comment's player with the transcript under it, a screenshot last.

A taxonomy sorts many things into kinds ("is a"); an anatomy opens one thing ("part of"). The parts taken out and set in a tree are a meronomy, which keeps what holds what but loses where each part sits: the anatomy is the picture of the whole, usually a labelled diagram.

maps.md
Anatomy: one message seen whole, its five parts numbered where they sitAnatomy: one message seen whole, its five parts numbered where they sit
MAP-14

labelled diagram

A thing drawn whole, as it is seen, with a thin line (a callout, or leader line) from each part to its name. Nothing is moved and nothing is opened, so only the outside can be named. The common picture of an anatomy: a diagram of a flower in a school book, a device's parts in its manual, a component in a design system.

What is inside stays hidden; a cutaway opens it, an exploded view takes it apart.

maps.md
Labelled diagram: a hand coffee grinder whole, a line from each part to its nameLabelled diagram: a hand coffee grinder whole, a line from each part to its name
MAP-15

exploded view

The parts of a thing pulled apart along the lines they fit on, each in the place it goes, so that every part is seen and the order of putting them together can be read off the picture. Each part has a number; the numbers lead to a parts list (in industry, a bill of materials). An assembly sheet of flat-pack furniture is one.

It shows what a labelled diagram cannot: the parts behind other parts, and how they go together.

maps.md
Exploded view: the same grinder, its seven parts pulled apart along their axis and numbered, with the parts listExploded view: the same grinder, its seven parts pulled apart along their axis and numbered, with the parts list
MAP-16

cutaway

A thing drawn whole with part of its casing taken away, so the inside shows in its place: the gears of a clock behind its face, the rooms of a ship behind its hull. The edge of the cut is drawn, so it reads as opened, not as missing.

Unlike an exploded view nothing moves: the inside is seen where it works. Only what the cut opens is named; the outside is the labelled diagram's.

maps.md
Cutaway: the same grinder with its front cut open, the shaft, the burrs and the ground coffee namedCutaway: the same grinder with its front cut open, the shaft, the burrs and the ground coffee named
MAP-17

legend

The key of a picture: a small box, set apart from the drawing, with a sample of each colour, line and sign and what it means. A map's legend says that a blue line is a river and a dashed red one a border; a chart's says which colour is which series. In British English also a key.

A label names one thing on the drawing itself; a caption says under the picture what the whole shows; a legend explains the marks, once, for all of them.

In the agent notes: the overview's colours (green done, orange waits on the author, the accent at work), and the two samples at the top of this page's terms map.

maps.md
Legend: a small map of roads, a river, a border and a park, its legend beside itLegend: a small map of roads, a river, a border and a park, its legend beside it

NAMESStandard namesPlain public names, used in place of private ones: the same word for the same thing in every project, so a reader outside knows at once what it is. Several of one kind are numbered from 1: laptop1, laptop2, vps1, vps2.

MACHMachines

MACH-05

server

A machine that serves others, at home or in an office.

names.md
MACH-06

vps1, vps2

A rented virtual server, numbered in the order they appear.

names.md
MACH-09

box

A container or virtual machine an agent or a service runs in.

names.md

PLACEPlaceholders

PLACE-04

192.0.2.x

An IPv4 address (RFC 5737, reserved for documentation)

names.md

MOTIONMotionWords for how things move on a screen. The rules that use them are on the Animations page (ANIM).

MOTION-01

morphing

One element turns into another: its shape, size and place change through every frame between, so the eye follows it as the same thing, never one thing swapped for another. A menu grows out of its button and shrinks back into it; a chip opens into its field; a card's avatar shrinks into its folded line while the time moves beside it.

It is the ideal animation: almost every animation rule is built on it. What comes from something on the screen, or goes into it, morphs (ANIM-16); only what has nothing to come from fades.

motion.md
Morphing: the menu grows out of its button and back, the toast only fadesMorphing: the menu grows out of its button and back, the toast only fades
MOTION-02

fade

An element comes or goes by its opacity alone, where it stands, its shape and place unchanged: the simplest smooth change. It is for what has nothing to morph from or into, a toast or a tooltip, and for the parts of a morph that have no place in the other shape (ANIM-10). Never whole on one frame and gone on the next.

motion.md
Fade: the toast comes and goes by its opacity, where it standsFade: the toast comes and goes by its opacity, where it stands

ARCHArchitectureWords for what software is made of and for the work it does, each with the words that can stand in for it.

WHOLEPartsFrom the whole down to a part of the code.

WHOLE-01

system

The whole: every part working together for one purpose, the browser, the services, the databases and the providers outside. A word for when the parts matter less than what they do together.

Also: platform (others build on it), stack (layers on top of each other), infrastructure (what runs the rest), application (what the user touches), setup (one arrangement of it), ecosystem (many owners). On the Agents glossary system is the system message, not this.

architecture.md
System: a browser, two services, a database and an outside provider in one frame, working for one purposeSystem: a browser, two services, a database and an outside provider in one frame, working for one purpose
WHOLE-02

service

A program that keeps running and answers requests from others, often over the network: started once, then waiting, serving many callers in turn.

Also: server (the program or the machine it runs on), daemon (runs in the background, no screen), backend (behind a front end), endpoint or API (its doorway, not the whole), microservice (one small service among many). "A service" may also mean what is offered, not the program: then facility or utility.

architecture.md
Service: three callers send requests to one running service and each gets its answerService: three callers send requests to one running service and each gets its answer
WHOLE-03

provider

What supplies something the rest needs (files, sign-in, e-mail, payments), one of several that could: the code asks for the thing, and whichever provider is plugged in gives it.

Also: source (where data comes from), supplier, vendor (a company), backend (the one behind a common front), adapter or driver (one swappable piece of code per provider).

architecture.md
Provider: the app asks for storage; the disk provider is plugged in, the cloud and memory providers could take its placeProvider: the app asks for storage; the disk provider is plugged in, the cloud and memory providers could take its place
WHOLE-04

module

One part of the code with a job of its own, used by the rest only through what it exports. Inside it may change freely; its exports are its promise.

Also: component (a part, often of a screen), unit (the smallest part tested alone), package or library (shipped and versioned apart), plugin or extension (added from outside), building block.

architecture.md
Module: three modules in one codebase; each is used only through its exports, its inside hiddenModule: three modules in one codebase; each is used only through its exports, its inside hidden

WORKWorkWhat gets done and what does it: the first four each hold the next, the last two put work in a row.

WORK-01

process

A running program: its own memory, its own id (pid), from start to exit. The operating system runs it; it runs jobs, tasks and functions. A worker is a process that takes jobs from a queue; an instance is one of several copies of the same program.

"Process" may also mean a way of doing things, not a program: then procedure or workflow.

architecture.md
Process: one running program with its pid and memory, started, running its jobs, then exitingProcess: one running program with its pid and memory, started, running its jobs, then exiting
WORK-02

job

Work handed over to run later or apart: it gets an id and a status the caller can look up, queued, running, done or failed, and may be retried or run on a schedule.

Also: batch (many items in one job), run (one execution of it). Tools draw the lines their own way: in CI a job holds steps, in Kubernetes a Job starts pods.

architecture.md
Job: queued, running, then done or failed; a failed job is retriedJob: queued, running, then done or failed; a failed job is retried
WORK-03

task

One unit of work to do: one step of a job, small enough to finish or fail as a whole. Often a function call put in a queue.

Also: step (one in an order), operation, work item.

architecture.md
Task: a job of three tasks, resize, save and upload, done one after anotherTask: a job of three tasks, resize, save and upload, done one after another
WORK-04

function

Code with a name: called with arguments, it returns a value. No life of its own; it runs for the length of one call.

Also: routine or subroutine, procedure (often one that returns nothing), method (a function of an object).

architecture.md
Function: resize is called with an image and a width and returns the smaller imageFunction: resize is called with an image and a width and returns the smaller image
WORK-05

pipeline

Stages in a row, the output of each the input of the next: data goes in at one end and comes out changed at the other. Each stage does one thing and knows only its neighbours, so all of them can be busy at once, each with its own item. A shell's a | b | c, a build, a CI pipeline.

Also: workflow (the steps, often with people in them), flow, stream (items one by one, without end), assembly line.

architecture.md
Pipeline: photos go through resize, compress and upload and come out as thumbnails, each stage busy with its own photoPipeline: photos go through resize, compress and upload and come out as thumbnails, each stage busy with its own photo
WORK-06

chain

Links one after another, each handing on to the next or stopping there. What goes along is control, a request or a call, not data being changed: middleware (next()), a promise chain (.then()), method chaining, a chain of responsibility. Where a pipeline changes data stage by stage, a chain passes a turn, and any link may end it.

Also: sequence, series, cascade (each step sets off the next).

architecture.md
Chain: a request passes log and auth to the handler; auth may stop it with a 401Chain: a request passes log and auth to the handler; auth may stop it with a 401