Glossary

Every term this documentation uses, defined once. That is the rule the page enforces: a definition lives here, so any other page can use the word and link back rather than explaining it again — and when two pages disagree about what a word means, this is the one checked against the source.

Entries are grouped by area and run alphabetically within a group, case-insensitively, and a term with an obvious synonym lists the synonym too. Identifiers are set in code exactly as the source spells them, because a term you cannot grep for is a term you cannot check. The last section collects the words the project deliberately does not use, where a vocabulary becomes a set of decisions rather than a list.

Runs and stages

run

One submitted brief executed end to end, and the durable record of it. It owns its stages, turns, tool calls, artifacts and budget, whose limit is fixed at submission. How a run flows.

stage

One step of a pipeline, instantiated for one run as a StageRun: a kind, a mode, participating roles, a status, and a summary the next stage receives.

stage kind

One of twelve: intake, plan, research, debate, workshop, design, architect, build, review, test, integrate, report. The kind sets the turn's task class, so it also decides how its turns are priced.

stage mode

How a stage's employees are run: single, parallel, debate or review-loop. It decides how many turns the stage produces and whether it consults abortReason.

single

One turn, by roles[0], and nothing else. The source comment mentions "a short internal loop"; there is no such loop.

parallel

One turn per listed employee, each against its own clone of the knowledge snapshot, bounded by DEV3D_MAX_CONCURRENCY and merged back in role order.

debate

Attributed speeches, one per participant per round, then roles[0] as facilitator delivering the verdict that becomes the stage summary. Rounds default to 2. Nobody walks to the meeting room.

review-loop

Reviewers critique in parallel, the chair synthesises, and the run's real file producers revise until the chair approves or stops objecting. roles[0] is the chair, not the producer, and objections are matched by regex over the reviewers' text.

optional stage

A stage carrying optional: true, whose failure is recorded while the run continues. The one shipped example is research in product-build; exceeding the budget halts a run regardless.

turn (TurnRecord)

One employee, one model call, zero or more tool calls — carrying its routing decision, the model that answered, usage, text, reasoning, skills, files written and its own error.

tool call (ToolCallRecord)

One tool invocation by one turn: the raw JSON arguments, a result preview, a duration, the paths touched and a status. The finest level at which a refusal is recorded as a fact.

artifact

A document a stage produced, of a kind such as objective, plan, decision, spec, code, review or report — how one stage's thinking reaches the next.

pipeline

A named, ordered list of stage specifications. product-build has 10 stages, code-change 7 and quick-answer 3, and a plugin can contribute more.

brief

The user's original words, unedited and never rewritten: the structured reading of them becomes the objective, so input and interpretation stay separately inspectable.

objective

The structured statement of what a brief asks for, produced by intake and stored on the run. It is what the pipeline works from, with the brief kept beside it.

run status

One of queued, running, awaiting-approval, paused, done, failed, cancelled. Only the last three are terminal, and paused is declared and never set.

stage status

One of pending, running, awaiting-approval, done, failed or skipped. There is no stage-level "degraded" status.

partial failure

A turn that produced something but not everything, recorded in the turn's error while its status stays done and no error event is emitted. The shipped cases are an output limit hit mid-turn and 8 tool round trips without an answer.

repairNote

A prompt field rendered as a correction block telling an employee that its previous attempt failed and why. Dead code: declared, rendered, never passed by any caller. Known gaps.

abortReason

The callback a stage uses to ask between turns whether the run has already been aborted. Only debate and review-loop consult it, which is how the other two overshoot the budget ceiling.

Models and routing

provider

A place a turn can be sent; deepseek, openai, openrouter, anthropic and local ship built in. One with no key and no keyless base URL is catalogued but never a candidate.

model id

The identifier a provider serves a model under. Tier, price and quality are the office's opinion about the model; the id is the provider's, and the only part discovery changes.

tier

One of five bands, in order: nano, small, standard, strong, max. Not a price bracket and not a filter: a position on the walk and a term in the score.

task class

What kind of work a turn is, mapped from its stage kind — coding and summarize are two. It selects the policy tier, scopes plugin rules, and is what fitness is scored against.

policy (ModelPolicy)

One role's routing rules: a default tier, per-task-class overrides, a floor and ceiling, optional escalation, an output cap, an optional pin and an optional preferred model. Model routing.

minTier and maxTier

The hard bounds on the target tier, clamped after posture and escalation move it — which is why one reason can say both "escalated to max" and "clamped". A plugin's hinted tier is applied later and is not clamped.

byTaskClass

The policy's per-task-class tier overrides, e.g. { coding: 'strong' }. An absent class falls back to the policy's defaultTier, so an override is an exception.

escalation

Raising the target tier when a turn's complexity crosses escalateAtComplexity, up to escalateTo, still clamped into the policy band. Thresholds run from 0.60 for engineers to 0.75 for the CEO.

maxOutputTokens

The policy's per-turn output cap: 4096 shipped, 3072 on ui-designer and platform-engineer. Reaching it produces a partial failure, not an error event.

pin

A policy boolean that pins a role to one model and skips posture, escalation and the whole walk. Every other candidate loses with a pin is in force for this role.

preferredModelId

A tie-break preference for one model, explicitly not a pin. It prefers candidates that already passed capability filtering, so it cannot resurrect an excluded model.

posture

The routing stance: cheap, balanced or quality, default balanced. It moves the target tier — cheap to minTier, quality one tier up — and is forced to cheap under $0.05 remaining.

fitness

How well a model suits the request's task class, 0–1, weighted 0.45, the heaviest term. A model with no per-class entry falls back to its overall quality, weighted 0.20.

tier affinity

How well a model's tier matches the walk position reached, as 1 − 0.15 × position, weighted 0.35 — what keeps the policy meaningful further down the walk.

cost pressure

The posture's price sensitivity — 0.30 under cheap, 0.12 under balanced, 0.03 under quality — times a model's blended cost normalised across the pool. Zero when nothing is rated.

reliability penalty

Up to 0.30 of score removed for poor observed uptime. A demotion, never an exclusion, and an unknown uptime contributes nothing, so unmeasured providers are not penalised.

hint bonus

The adjustment a plugin routing rule makes: +0.08 for a preferred model, +0.04 for a preferred provider, −0.12 for an avoided model — a penalty, not an exclusion.

walk order

Hinted tiers first, then the target, then the tiers above it weakest-first, then the tiers below strongest-first. Walk position is what tier affinity scores.

capability relaxation

What the router does rather than return nothing: drop tool and vision requirements, then the context requirement, then use the whole catalogue, recording which step applied.

rejection reason

The clause recorded for every candidate that lost: excluded, lacks tool calling, lacks vision, context window too small, a pin is in force for this role, tier is not on this policy's walk, scored 0.512 against the chosen 0.804, tied on score; more expensive, or later by id.

routing decision (RouteDecision)

The chosen model with its tier, score, considered candidates, ordered fallbacks and a reason of clauses joined with — . It reaches the turn, the event stream and lastRoute.

fallback

A candidate the router will try after its first choice. Failover is recorded separately: servedBy names the model that answered, attemptedRoutes lists failures as provider/model: error.

routing rule

A plugin's declared routing preference: an optional task class, an optional tier, preferred provider and model ids, avoided model ids. Rules add score bonuses and cannot add a candidate that failed filtering.

Organisation and the office

office

The whole running installation: one database, one organisation per floor, one process, three views — console, socket, HTTP. Nothing in it authenticates, which is why it belongs on localhost.

floor

One organisation's storey, and the unit the console switches between. Switching is the wire command selectWorkspace; there is no selectFloor, and storeys are 4.2 metres apart.

department

One of eight groups a role belongs to: executive, design, research, technology, frontend, backend, platform, quality. A label for the chart, not a permission boundary.

employee

A role instantiated on a floor: a seat, an appearance, a status, a lifetime spend, a last route. "Agent" is the general word for the model working; a role is the job and an employee holds it.

role

A job: an id, a display name, a title, a department, a model policy, allowed tools and skills, an appearance and a seat. Thirteen ship, and a role is what hiring adds and firing removes.

seat

A named asset anchor an employee is placed at, such as Seat_CEO or Seat_Dev_01. The asset contract is 21 seats, 13 desks and 7 rooms, and employees are repositioned rather than walked.

floor plan

The generated layout of a floor: desks, rooms and the block modules they are assembled from, growing when a roster outgrows its desks. A real jigsaw with mating edges and collision rejection, not art direction. The office.

quick jump

The console's one-box search over employees, runs, artifacts and events. It searches state the client already holds, so a result is always something the console could already render.

activity feed

The console's chronological stream of run, turn, tool, approval and routing events plus the lines surfaced as log events. The readable half of the stream; the transcript is the structured half.

project

A workspace as the console presents it: a card carrying a name, a directory, a floor, a roster, skills, budget and spend. "Project" and "workspace" name the same record.

workspace

An organisation plus the directory it works in, addressed by workspaceId. A run copies the id and the resolved workspacePath and never rewrites them. Projects, organisations and floors.

workspaces root

The directory new project folders are created under: DEV3D_WORKSPACES_ROOT, default ./workspaces. A project created by name resolves under this root.

external workspace

A project pointing outside the workspaces root, gated by DEV3D_ALLOW_EXTERNAL_WORKSPACES — on by default, disabled only by the literal false. Turning the boundary off is a real grant.

budget

The money on a run and a floor: limitUsd and spentUsd. A run's limit is the submitted amount, or the floor's budget.defaultRunUsd, which defaults to 5. Environment.

hard ceiling

The budget check that fails the whole run. It runs before each stage, so a single or parallel stage can overshoot before the next check catches up.

soft gate

DEV3D_SOFT_SPEND_APPROVAL_USD, default 1.50, fired at most once per run between stages. Approving continues, refusing cancels the run rather than pausing it, 0 disables it.

approval

A request for a human decision, of kind shell, write, network, spend or risk. The only thing that makes a run awaiting-approval; a timeout resolves it as refused.

spend approval

The approval of kind spend, raised by the soft gate. It carries turnId: null and is attributed to the first stage's owner, and its refusal cancels the run.

Tools and the workspace

tool

A capability an employee can be granted and a turn can call, with a name, a description and a JSON parameter schema. Nine ship built in and a plugin can register more.

built-in tool

One of nine: think, list_dir, read_file, search_files, write_file, edit_file, run_shell, web_search, web_fetch. "Built-in" says where it came from, not what it may reach.

tool grant

The list of tool names a role may hold, replaced rather than merged and filtered against what exists. It is the only way to grant a tool a plugin registered.

tool status

ok, error, denied or running, on one call. denied covers a tool the role does not hold and a shell command a human declined — a normal outcome, not a run failure.

workspace root

The absolute directory a run's file tools resolve against, taken from the run's workspace at submit time. Every scoped lookup during a run is keyed by that organisation.

resolveInWorkspace

The single path choke point: it rejects .., absolute paths outside the root, Windows drive-relative forms such as C:foo, NTFS alternate data streams and reserved device names, then resolves the real path of both the root and the target and refuses any symlink, junction or mount point on the way out. Eight of the fifteen built-in tools call it. Projects, organisations and floors.

approval round trip

The wait for a human to answer an approval, bounded by DEV3D_APPROVAL_TIMEOUT_MS, default 600000 and floored at 1000. A timeout counts as refused, so nothing wedges a run forever.

auto-approve shell

DEV3D_AUTO_APPROVE_SHELL, default false and enabled only by the literal true, which skips run_shell's approval — the tool's only gate.

plugin tool confinement

The fact that a plugin's tools are not confined by the host: the workspace root is forwarded as information and nothing resolves what the tool touches. A plugin tool is trusted code in the orchestrator's process. Known gaps.

Skills, plugins and the marketplace

skill

A markdown document with front matter, loaded at boot before the server listens. Fifteen ship, and a malformed file is skipped with its reason logged rather than being fatal. Writing a skill.

skill selection

The per-turn choice of skills: the first two a role and workspace agree on are always included, the rest score a task-class match at 100 plus keyword overlap, and the engine takes three. Each carries a via.

plugin

A directory with a plugin.json and, optionally, a code entry module; three ship. Contributions are recomputed from the loaded manifests rather than patched. Building a plugin.

manifest (plugin.json)

The plugin's identity, API version, permissions, settings schema and contributions. Problems reject the whole plugin; warnings drop one contribution and keep the rest. Plugin manifest.

apiVersion

The plugin API a manifest was written against. The host implements 1 and compares only the leading integer, so 1.4 works and 2 is refused rather than guessed at.

declarative plugin

A plugin contributing only validated data: catalog entries, skills, templates, settings forms and panels. It cannot ship markup or script into the browser at all.

code plugin

A plugin whose manifest names an entry module exporting activate(api), imported into the orchestrator's process and run unsandboxed. Disabling it cannot unload the module, so it stays resident until a restart.

contributes

The eight seams a plugin reaches, and only eight: providers, models, skills, roleTemplates, pipelines, routingRules, uiPanels, toolNames. settings is a top-level field, and toolNames only names tools.

plugin permission

One of ten declarations: models, providers, tools, routing, skills, agents, pipelines, settings, ui, events. Enforced for two of them — a tool registration needs tools and an event subscription needs events — and a disclosure for the other eight, which is what an operator reads before enabling a plugin.

tool namespace

The prefix a plugin's tool names get: the id lowercased, non-alphanumerics turned into underscores, capped at 40 characters. So dev3d.office-echo registering echo becomes dev3d_office_echo_echo.

UI panel

A console panel in one of four placements — inspector, runs, office-overlay, settings — built from six widget kinds: metric, keyValue, table, list, bars, note. A live panel's URL is fetched by the server, never the browser.

bundle

A .tar.gz of a plugin directory, verified by hash before a byte is unpacked. The reader refuses absolute paths, .., links, device nodes, over 2048 files and over 32 MB unpacked.

sha256

The digest of a bundle's exact bytes, published in the catalogue entry and checked before unpacking. A value that is not 64 lowercase hex characters is dropped, switching verification off for that entry.

checksum

The general word for that digest, and the name of the failure when it does not match: the error shows the first 16 characters of each hash. Publishing to the marketplace.

catalog

The JSON a marketplace serves: a format version, a name and entries each carrying a manifest, a download URL and an optional sha256. One invalid manifest rejects the whole document.

marketplace

Any static host that can serve a catalogue document, and this site is one. Registering a marketplace to browse it is not gated; installing from one is.

install gate

DEV3D_ALLOW_PLUGIN_INSTALL, default false and opened only by the literal true. Environment-only on purpose: the decision to run downloaded code belongs to the launching environment.

listing

The marketplace's editorial record of a plugin: an id, a name, a description, a category, links and versions. The listing governs presentation; the manifest governs what the plugin is. Listing a plugin.

review queue

The human step before a version becomes installable. A queued version is hidden from the catalogue and from its own bundle URL, and a rejection carries a required note.

verified publisher

An account an administrator has confirmed is who it claims to be. A badge about identity, not quality: it says nothing about whether the plugin is any good.

trusted publisher

An account whose submissions skip the review queue. A separate switch from verification, because a reduction in oversight is a decision rather than something verification quietly grants.

yank

Withdrawing an approved version: it leaves the catalogue and stops being served while the row survives for the download history. The last approved version cannot be yanked.

hosting

Running the orchestrator yourself. There is no hosted dev3d, because nothing in it authenticates and it is built to bind to localhost on a machine you control. Contact.

API token

A credential a pipeline presents instead of a browser session. Only its sha256 is stored, so it is shown once, and revoking it takes effect on the next request. Publishing from CI.

API token scope

What a token may do: marketplace:read, marketplace:publish or marketplace:manage, with publish the default. Checked per request, and marketplace:manage implies publish.

claim token

A one-shot secret proving control of an email address, used for an invite and a password reset. Only its sha256 is stored, and the link is handed over out of band because there is no email delivery.

Durability and verification

durability

What survives a restart, and in what order: an event is persisted before it is broadcast, so a client that reconnects and replays sees a superset rather than a gap. Verification.

store

SQLite through Node's own node:sqlite, with no driver package and exactly one writer. If the path is unusable the office runs non-persistently and says history will be lost.

verification

The evidence behind this documentation's claims, suite by suite, with each suite's stated limits. Counts are measured by running the suites rather than counting declarations. Verification.

dead code

Declared, seeded and rendered, but reached by no code path: repairNote, and config.runBudgetUsd behind DEV3D_RUN_BUDGET_USD. The category used to include the per-role maxTurnsPerStage, which is now enforced — a role that reaches its per-stage cap is skipped for the rest of the stage and the skip is logged by name. Known gaps.

Infrastructure

wire protocol

An HTTP API for asking and one-shot actions, plus a single WebSocket for watching and anything run-scoped. The counts are 31 server events and 33 client commands declared, of which the socket serves 26 and one event is never emitted. The wire protocol.

server event

One of the 27 types the server pushes. Both applications import the union from one dependency-free package, so a shape change only one side made is a compile error.

client command

One of the 31 types a client may send. The socket implements 24; the seven plugin commands answer Unknown command and each has an HTTP route instead.

whole-state event

An event carrying a complete object rather than a patch: hello, office.updated, org.updated, settings.updated, plugins.updated. A client that missed one is corrected by the next.

HTTP route

One of the JSON endpoints, pretty-printed and sent with cache-control: no-store so the read API is usable from a terminal. Reads are unauthenticated; cancellation and approvals are socket-only.

catch-all

The handler answering an unknown /api/ path with 404 and No such endpoint: <path> — why POST /api/runs/:id/cancel gives a legible refusal.

installation settings

The database values that beat the environment after a first boot: eight engine-affecting values copied from .env once, after which the console is how they change. Environment.

.env bootstrap

The file read exactly once, at startup. Editing it while the process runs changes nothing, and a real environment variable always beats the file.

environment-only variable

One that cannot be changed from the console: provider keys, the database path, the install gate, the bind address, every cache path. A secret, or needed before the database opens, or a launch-time decision.

mock mode and live mode

Scripted employees with no billing, versus real providers. auto resolves to live the moment a provider counts as configured, so a key in .env moves the office from scripted to billed at the next restart.

Terms deliberately avoided

A vocabulary is defined as much by what it refuses to say. These words have been used about this project and should not be, either because the mechanism does not exist or because using them would hide a limit stated plainly elsewhere.

Word or phrase	Why it is not used
"degraded" as a status	No stage-level degraded status exists: StageStatus has six values and degraded is not one. The word appears in the source meaning something else — a provider's modelSource is discovered, degraded or seed.
"complexity" and "prompt" as nesting levels	They are not levels of anything. The hierarchy is Run → StageRun → TurnRecord → ToolCallRecord; both are computations inside one turn.
"sandbox"	There isn't one. A code plugin runs with the orchestrator's authority, and run_shell is confined only by its working directory. The permission list is a partial gate rather than a sandbox: it is enforced for registering a tool and for subscribing to the event stream, and is a declaration for the other eight.
"walked to the meeting room"	A debate does not move anybody. employee.moved comes only from hiring and from moving a seat, and a re-seat is a teleport. Idle employees do walk — there is a real locomotion layer with a walk cycle and routes computed on a grid sampled from the floor geometry — but it is client-side rendering, unrelated to a debate, and it stops the instant work arrives.
"semver"	The one version comparison in the host is documented as not a semantic-version implementation: a missing part counts as zero, so 1.2 and 1.2.0 compare equal.
"filter by tier band, then pick the cheapest"	Capability filtering is not tier-based, the posture moves the target tier rather than a band, and a weighted score decides — so a better-fitting model at the original tier can win.
"confined", applied to every tool	Eight of the fifteen built-in tools call the workspace resolver. think and todo_write touch no path, the web tools are address-guarded rather than path-confined, run_shell and git are approval-gated instead, and a plugin's or an MCP server's tools are not confined at all.
"paused" as something you can observe	The run status paused is declared and never set. The soft-spend gate cancels a run, and a tool approval makes a stage awaiting-approval — not the run.
"the marketplace" as a server	A marketplace is a contract: a JSON document and a bundle behind a URL, which any static host can serve. There is no API beyond fetching the document and downloading what it names.
"the AI decided"	It hides which mechanism produced an outcome. The model comes from a policy, a posture, an escalation threshold, a weighted score over candidates and possibly a plugin hint — all written into the routing reason.

Two habits follow. When a term has been used loosely elsewhere on this site, linking back here is the fix, because a definition maintained in one place is one that can be corrected. And when a word from the list is the only accurate one, the sentence around it should say what is missing rather than implying the project provides it.