Glossary
Alert
A threshold on a measure of a work station's runs, such as its sent-back rate
or its cost per run, set in the station's alert blocks. The Station page lists
a station's alerts. When one goes off, the task of the run that crossed it gets
an inbox item. See Alert fields
and Station alerts.
Approval
A person's decision on one tool call, or one harness permission, that a run asked to use. A person may change a tool call's inputs before approving it. A grant is spent by the call it allows; a dismissal stands at the station that asked. See Approvals.
Attachment
A file of up to 25 MiB given with a task, an answer, a message to a run or a
chat message. A run finds it in its workspace at
.spotlight/attachments/<id>/<name>. See
Attachments.
Backlog
The first station of every line, of kind backlog. Nothing runs there, so a
task waits at the backlog until a person or a reaction moves it. See
spotlight_line.
Baseline
The replay of a station's live config on a replay set's runs that the set's other replays are compared with, other than a replay with the answer, which is compared with the live replay that started it. It starts the first time a set is replayed, again once runs are added after it or a replay asks for more copies of each run than it has, and when a search of the set starts. See Regressions.
Before event
A hook event that waits while its hooks run, such as tool.using. A hook on a
before event can stop it. An after event, such as task.moved, has already
happened when its hooks run. See Events.
Board
A line's page in the web app. It shows the line's stations and the tasks standing at them, in the views Backlog, Active and Completed. See Web app.
Briefing
The first prompt a task's run gives its agent: the station's prompt, the task, what earlier stations noted, the task's decisions, the repositories, skills, open remarks on the pull request, and how to hand over. See Briefing.
Candidate
A work station's block as someone wants to try it, proposed to be replayed on the station's past tasks. It is never applied. A person proposes one as a replay candidate; a search's agent proposes them as it searches.
Catalog
Tools and skills Spotlight publishes, named catalog.<name>@<version>, such as
catalog.fetch-page@1.0.0. A station gives them as it gives its own. Each item
needs a plan. See
Catalog.
Change stack
A run's diff arranged for review as cohorts of layers.
Spotlight drafts one after each run at a station with diffs: true. See
Change stacks and decisions.
Chat
A private planning conversation between one person and a team's agent, on the team's Agent page. A chat is worked by runs, and the agent can propose tasks in it. See Chats.
Check
A station's one-line command, such as npm test, run against the whole change
and then each layer of a change stack drafted at that station. See
Checks.
Claim
A statement a good run makes true, such as The change adds a test that fails without it., listed in a station's judge block. The judge marks
each claim met or not, and scores a run as the share met. See
Judge fields.
Cohort
A group of layers in a change stack, of kind change or incidental, with a
title and an intent. See
Structure.
Completed
The last station of every line, of kind completed. Nothing runs there. A task
moved to it is finished. See spotlight_line.
Config fingerprint
A SHA-256 of the config a task's run was given at its station: the prompt, harness, model, effort, harness profile, the line's image, repositories and their setup commands, skills, tools, the decisions and memories switches, and the judge. Runs with the same fingerprint ran the same config. The web app shows its first 8 characters. See Config.
Configuration change
A record of one create, update or delete of a workspace's configuration: who made it, through which client, and what changed. Owners and admins read them. See Configuration changes.
Conversation
The stretch of a task's notes from a station putting the task to a person
(an asked note) to the task next being passed on (a passed note). It is open
until then. Each conversation is one inbox item. See
Notes.
Counterpart
The replay a replay is compared with: its task-by-task rows, its gain and its regressions are measured against it. Usually its set's baseline; for a replay with the answer, the live replay that started it. See Counterparts.
Decision
A trade-off, assumption, limitation, rejected approach or deviation that
Spotlight draws from what an agent said during a run at a station with
decisions: true. People can dispute a decision. See
Decisions.
Egress
A proxy container a host starts beside each sandbox. The sandbox reaches the network only through it. Egress admits or refuses each connection and adds secrets to requests to the hosts they are bound to. See Egress.
Frontier
The candidates of a search for which no other candidate succeeds as often for less. The station's live config is always on it. In a search that aims for the same success for less, only candidates whose gain over the live config reads Better or Within noise can be on it. See Frontier.
Grade
A person's score of a judged run, on the judge's scale, given from the inbox. On claims, a grade marks each claim met or not. The judge's agreement with people is measured against grades. See Grades.
Handover
What a task's run declares when it ends: pass the task to another station, put
it to a person (review), or finish it (done). The agent declares it with
spotlight handover. See Handover
and Agent commands.
Happening
A named event from outside Spotlight, such as github.pull_request.merged,
raised by GitHub or by an integration. A happening finds the task it concerns
and may move it, or opens a new task. See
GitHub events and
spotlight_integration.
Harness
The agent command line a station runs: claude-code (Claude Code), cursor
(Cursor CLI) or codex (Codex). See Harnesses.
Harness key
An API key or token a harness uses to reach its model provider, such as
ANTHROPIC_API_KEY. A host gives them to its sandboxes from sandbox.env.
Egress holds the ones it knows, and the sandbox gets a stand-in.
See Harness keys.
Harness profile
A team's named set of permission rules, MCP servers and native harness
settings. A station names one in its profile. See
spotlight_harness_profile.
Held-out task
One of the tasks of a replay set that a search keeps from its agent, about 30% of them. Only the best candidates are replayed on them, once the search stops searching, to check they did not just fit the tasks the agent saw. See Why a search holds tasks back.
Hook
A team's rule that runs steps when an event happens, such as tool.using or
pull-request.opening. A hook on a before event can stop that
event. See spotlight_hook.
Host
A machine running spotlight host. It claims runs for a workspace and starts a
fresh sandbox for each one. A host is admitted through a pull pool's token or a
runner trust. See Host settings.
Inbox
A person's list of conversations on the tasks assigned to them, across every team in a workspace. See The inbox.
Insights
A team's page that sums up how its runs, tasks and pull requests went over the past 7, 30 or 90 days, against the period before, and sets the station configs it replayed beside the live config. See Insights.
Integration
A team's definition of an outside service: the webhooks it sends and the
happenings they raise, the tools agents may call on it, and how Spotlight
connects to it. See spotlight_integration.
Judge
A model that scores a share of a work station's runs against the station's
rubric or claims, citing the steps and changes behind each reason. Its scores
show only once they agree often enough with people's. A station sets one in
its judge block. See Judging
and Judge fields.
Label
A name a runner pool or runner trust gives the runners it admits. A line's or
station's runners place its work on runners that carry one of the labels. See
Placement.
Layer
A step of a change stack: a title, a summary and the changes it places, built
on the layers before it. A station's check runs on each layer of a change cohort
together with the layers before it. See
Structure.
Line
A team's workflow: an ordered set of stations, the reactions that move tasks
between them, the repositories its runs work in, and an optional role. See
spotlight_line and Built-in lines.
Line role
A word on a line that integrations open tasks onto. delivery and review are
built in. Only a line with role review may carry a review policy
(reviews). See spotlight_line.
Mark
A handle a task is known by outside Spotlight: a kind and a value, such as
git.pull-request and a pull request's URL. A mark belongs to at most one task
in a workspace. A finding mark is used to find the task a happening concerns.
An ambient mark (find: false) is kept on the task but never used to find
it. See Marks and
spotlight_integration.
Memory
Something a team knows that its repository can't tell, such as a rationale, a
rejected approach, a failure, an environment quirk, a correction or a
preference. A station with memories: true drafts proposed memories after each
completed run, from what the agent said and from what people said on the task.
Each is kept with the steps and notes it rests on. The run's memories arrive
as one item in the inbox, where a teammate approves, edits or rejects each one.
A memory from outside the team, such as a review of an outside author's pull
request, cannot be approved together with other memories. Approved memories
stand; rejected ones are kept, and the newest of them are shown to the
drafter. The team's Memory page
lists what stands, filtered by line, station, repository, path or kind. There
you can write a memory yourself, correct one (the correction replaces it) or
retire one with a reason; retired memories stay readable under Retired. Each
standing memory has a handle, such as M-12, and runs are briefed with the ones
that bear most closely on their work, whatever harness they run. Every memory
that applies to a run is also laid out in its workspace under
.spotlight/memory, for the agent to search; it can also search with
spotlight recall, and propose one itself with spotlight remember; that
proposal waits in the inbox beside the run like a drafted one. "Remembered" on
each run's page lists what it was given, briefed or recalled, and what it
proposed, and the Memory page shows how many runs used each memory. See
Station fields and
Agent commands.
Noise
How far a replay set's success moves by chance: the spread between the success
rates of copies of the same runs, replayed under the station's live config
with each run replayed 2 or more times. It is one reading of a set's
health. Separately, a gain whose 95% interval
reaches across no change, that is smaller than the line's min_gain, or that
rests on fewer than 5 tasks scored on both sides, reads "Within noise". See
Noise and
Why changes are replayed on past tasks.
Note
An entry on a task's trail, of kind asked, passed, answered or said,
with a voice (station, person or world) and a form. A note's words never
change. See Notes.
Notice
An inbox entry that tells one person about their team's work, outside any task, such as a search they started that stalled. Nothing waits on it; its person dismisses it. See Notices.
Occurrence
One instance of an event that hooks fire for, with an id of its own. A hook's
request carries it as occurrence. See spotlight_hook.
Placement
The terms a run's runner must meet: the station's runners labels,
or the line's where the station names none; the runner image; and the harness.
See Placement.
Plan
A workspace's commercial plan: free, team or enterprise. Each plan
includes the ones before it. The plan decides which catalog items a station may
give. See Catalog. The
plan permission is unrelated; see
Roles and permissions.
Pool
A runner pool: a workspace resource that admits runners. Hosts serve a pull
pool and claim its runs with the pool's token. For a push pool, Spotlight calls
a provision URL to start a runner for each run. See
spotlight_runner_pool.
Proposal
A task the agent proposes in a chat, naming a line and a station. It is open until the person accepts it, which creates the task, or dismisses it. See Proposals.
Reaction
A line's rule that moves a task to a station when a happening arrives,
optionally only while the task stands at a given station. See
spotlight_line and
Moves.
Reflection
An iteration of a stalled search that proposes nothing: its agent records why each searched task the best config so far still fails, as one of five causes. Only a cause the config can fix lets the search go on. See Reflections.
Regression
A task on which a replay did worse than the replay it is compared with, usually its set's baseline: the baseline succeeded and the replay did not, or the judge scored the replay's change lower. When each run is replayed more than once, the share of the baseline's copies that succeeded is higher than the replay's by more than 50 points. See Regressions.
Replay
A run of some of a work station's past task runs again, under a candidate or the station's live config, from where each run started, each up to 5 times. A replay changes nothing outside Spotlight, and each of its runs is scored. See Replays.
Replay check
A replay of a work station's change as a Terraform plan would
apply it, on the replay set that guards the station's changes, judged against
the line's replay_check. CI runs it with spotlight replay check. See
Replay checks API.
Replay set
A named list of up to 50 of a work station's past task runs, replayed together. While a run is in a set, the workspace it started from is kept. See Replay set page.
Replay set health
Whether a replay set can tell a better config from a worse one, read for the station's live config as it is now: its noise, how much of it the live config succeeds on already, whether the station's judge and check give the same answer twice, and how much better the live config does when handed each run's answer. The set's first baseline of the live config checks the set and measures the first four; the replay with the answer that Spotlight starts after it measures the last. See Health.
Repository
A GitHub repository, owner/name, named on a line. The line's runs check it
out. It may name a runner image and a setup command. See
spotlight_line.
Requester
The person who started a task, its Raised by. An integration whose
connection.holder is requester has its tools act with that person's own
connection to the host, which each person makes on the team's Integrations
settings page. See Holder.
Revision
A counter on a task. It goes up each time the task moves to another station and when it is finished. A person's move must name the current revision. See Tasks.
Rubric
What a good run at a station looks like, in Markdown, written by the team for
the station's judge. Its first line can name its scale,
scores: yes-no or scores: 1-5. A judge can have claims in
place of a rubric, or beside one. See
Judge fields.
Run
One execution of a harness in a fresh sandbox, for a task at a station, for a chat, or for a replay. See Runs.
Runner
The spotlight runner process inside a sandbox. It prepares the workspace,
runs the harness for one run, and reports the run's steps and outcome to
Spotlight. Every run gets a new runner. See
The spotlight command.
Runner image
The container image a sandbox runs from. A host serves the images its
SPOTLIGHT_RUNNER_IMAGE allows. A line names one through its repositories'
image; otherwise the host's default image is used. See
Host settings.
Runner trust
A workspace resource that admits hosts presenting an OIDC token from a named
issuer, for a named subject, in place of a pool token. See
spotlight_runner_trust.
Sandbox
The container one run executes in. A host starts a fresh sandbox for each run. See Inside a sandbox.
Search
A series of rounds in which an agent proposes changed configs for a work station, called candidates, each replayed on a replay set's tasks, within a budget. A search aims for more success, or for the same success for less. A search that finds nothing better twice in a row stalls, and may run a reflection. A person picks a candidate, and Spotlight opens a pull request with it. See Searches.
Secret
A named value a workspace keeps. Spotlight puts it in a request header or
query parameter on requests to the hosts it is bound to; the value never
enters a sandbox. See
spotlight_secret.
Side by side
A judging of two replays' changes to the same task together, without the judge being told which replay made which, against the change people accepted. A replay whose candidate has a judge, other than a baseline, a check of a set or a replay with the answer, is set side by side with the replay it is compared with once it finishes, and reads its wins, losses and ties beside its success. It never changes a run's result. See Side by side.
Skill
Reusable instructions, a SKILL.md with other files, that a station gives its
runs. See spotlight_skill.
Spotlight address
The URL a team's people, hosts and the Terraform provider reach Spotlight at.
Spotlight is offered as a hosted service at https://app.usespotlight.ai, and
these docs use that address throughout. Spotlight can also be self-hosted; on a
self-hosted Spotlight, use the address your deployment is served at, such as
https://spotlight.acme.example, wherever the docs show app.usespotlight.ai.
Hosts and the provider read it from SPOTLIGHT_URL. See
Host settings, and
Self-hosted Spotlight settings for a
deployment's own settings.
Stand-in
The value spotlight-egress:<NAME> a sandbox holds in place of a harness key
or a run secret. Egress replaces it with the real value in the request header
or query parameter.
See What egress adds to requests.
Starting point
Where a task's run started: the workspace archive it restored, if any, and the commit each repository was checked out at. A replay starts from it. See Starting point.
Station
A step on a line, of kind backlog, work or completed. A work station
may name a harness to work its tasks, and names its prompt, tools and skills,
and the stations it passes to. See spotlight_line.
Task
A unit of work. A task stands at one station of one line at a time, and carries a title, a description, attachments, a trail of notes, marks and an assignee. See Tasks.
Team
A group of people inside a workspace, with a key and a name. Lines,
integrations, hooks, skills, harness profiles and chats belong to a team. See
spotlight_team.
Tool
An operation an agent calls through spotlight from inside a run. A tool is
built in (such as pull-request), defined by an integration
(<integration>.<tool>), or from the catalog. A station lists the tools its
runs are given. See
Built-in tools and skills and
spotlight_integration.
Trace
The record of a task's runs and their steps, with their timings and faults.
The web app lists a team's traces on the Traces tab of Insights and shows one
on its task's Trace page. spotlight trace writes it to a file, and a chat
message can share up to 20. See
spotlight trace.
Unscored
The result of a replay run that nothing could score: one that could not be replayed or started, was cut short by its replay's stop or ceiling, failed before its agent began or for another reason outside the candidate, or changed nothing for its checks to run on. Unscored runs are left out of a replay's success. One that the judge still scored can make a task regress through a lower judge score. See Results.
Workspace
The top-level account in Spotlight, with a name and a URL slug. It holds teams,
members and their roles, the GitHub connection, secrets, runner pools and
trusts, and workspace tokens. See
spotlight_workspace.
Workspace runners
A workspace resource that names the workspace's runner pools and runner trusts
by key. A workspace has at most one. See
spotlight_workspace_runners.
Workspace token
A bearer token that acts inside one workspace within its scopes, for the resource API and the Terraform provider. A workspace admin or owner issues one. Spotlight also mints one for each run of a setup chat; see The run's Spotlight token. See Workspace tokens.
Workspace token trust
A workspace resource that lets a CI workload exchange the OIDC token its
platform issues for a short-lived workspace token. See
spotlight_workspace_token_trust.