Definitions

Plain-language explanations for the jargon that shows up around this site.

Technical write-ups on the Projects and Blog pages link the first mention of a term straight here. You can also just browse the full list below, grouped by topic.

Specific Services & Tools

ability meter

DiceLock's charge gauge for a player's special ability: it fills as the board plays, and tapping it fires the ability once full. Shown as a vertical bar beside the board on desktop and a sideways phone, colored to match whichever ability is charged; on an upright phone it is drawn instead as two small rings in the board's bottom corners.A gauge in the dice game DiceLock that fills up as you play and lets you fire a special power once it's full. On a desktop screen or a sideways phone it's a colored bar next to the board; on an upright phone it's two small rings in the board's bottom corners instead.

AdMob

Google's ad network for mobile apps. An app asks it for an ad to show, AdMob picks one from its advertisers and reports back whether the ad was watched, and the app's owner gets paid a share of what the advertiser spent.Google's system for showing ads inside mobile apps. The app asks it for an ad, Google supplies one, and the app's owner earns a small amount when it's watched.

agent session

Linear's own framing for handing a ticket to a bot: mentioning or delegating to it opens a session, the bot has to acknowledge within ten seconds, and its progress and result post back onto the issue as it works.The task tracker's way of formally handing a job to a bot. Tag it and it has to answer within a few seconds, then report back on the ticket as it works.

Alexa Skill

A custom voice app that plugs into Amazon's Alexa, letting it understand and respond to a specific set of spoken requests. Big Brain is one.A custom voice app for Amazon Alexa devices that teaches Alexa to understand and respond to a specific set of spoken requests. This project is one.

App Store Connect

Apple's dashboard for managing an app's listing and submitting it for review: the subtitle, promotional text, description, screenshots, categories, age rating and the build attached to a version all get set here before anything goes out.The web page where an app's maker fills in everything Apple needs to list the app and review it: its description, its screenshots, and which build of the app to submit.

blocks edge

A declared link between two tickets saying one has to finish before the other can start. It is what turns a pile of tickets into a tree with an order, and it is the thing auto-chaining walks: with the edges drawn, starting the first ticket is the approval for everything downstream of it.A recorded link between two tickets saying which one has to be finished first. Draw enough of them and a list of jobs becomes an ordered chain that can run itself once you start the first one.

Capacitor

A framework that wraps an existing web page in a native app shell, so the same served tree an app already runs in a browser can also be packaged and installed as an iOS or Android app, with a bridge to native device features like haptics.A tool that wraps a website's existing pages in a shell so they can be installed and run like a normal phone app, on the same code the browser version already uses.

Clerk

A hosted authentication service: it provides the sign-in and sign-up pages, manages user accounts and sessions, and hands the application a verified user id, so the application never stores passwords or builds its own login. The trade is that user ids belong to the Clerk instance: a database column bound to them is bound to that instance.A service that handles signing in for a website (the login pages, the accounts, the sessions), so the site itself never has to store passwords. The site just gets told, reliably, who you are.

demo card

DiceLock's way of teaching a move the first time it happens: a short looping card opens over the live board showing that exact move, with a header, a line of body copy, and a separate spoken caption for screen readers. It shows once per move and can be reopened on demand through a debug door for testing.A short looping video clip that pops up over the board the first time a particular move happens in the dice game DiceLock, explaining what just happened. It only shows once per move, and testers can reopen any of them on demand.

friend code

DiceLock's one permanent code per account for adding friends: share it, and whoever redeems it becomes your friend immediately, with no request or acceptance step either side has to approve. Redeeming one also tells the sharer it happened, unlike an ordinary friend request.A single, permanent code every DiceLock account has, for adding friends instantly. Share it with someone and the moment they enter it, you're friends, with nobody needing to approve anything on either side.

GitHub

A website for storing and backing up a project's code online, with a full history of every change. This project's code lives there in a private repository.A website for storing and backing up code online, with a complete history of every change ever made.

Gmail API

Google's official way for software to read, label, and organize a Gmail inbox on your behalf, with your permission.Google's official way for an app to read, sort, and label your Gmail, once you've given it permission.

Google One Tap

Google's sign-in method that hands a web or Android app a signed token identifying the user, without a redirect to a separate sign-in page. The token carries an azp claim naming the app that requested it, and whatever checks that token, Clerk in Dice Lock's case, has to recognise that app or it refuses the token outright.A way for Google to tell an app who just signed in without sending them to a separate Google page first. It works by handing the app a signed note from Google, and whatever reads that note has to already know and trust the exact app it came from, or it refuses the note.

headless Chrome

The Chrome browser run from a command line with no window, so a page can be loaded, scripted and screenshotted by a program rather than a person. It is how a build step gets a real browser engine (full layout, fonts and JavaScript) without installing a separate rendering library, and its output is only reproducible if every source of variation is pinned first, since two runs of the same page are not identical by default.An ordinary web browser running invisibly, driven by a script instead of a person, so a program can open a page and take a picture of it. It is useful when you want a real browser to do the drawing without anyone having to sit and click.

Home Assistant

Open-source home automation software that acts as a hub between different smart-home devices, like Hue lights, and anything that wants to control them.Free software that acts as a central hub for smart-home devices, letting different brands, like Hue lights, all be controlled from one place.

Hue bridge

The small physical device that connects Philips Hue smart lights to your home network, acting as the go-between for any app or service that wants to control them.The small box that connects Philips Hue smart lights to your home network, so apps and other services can control them.

input_select

A Home Assistant entity type that holds one value from a fixed list of options, like a dropdown. Used here as the single place a lighting mode gets written. An automation watching the select is what actually applies the scene, rather than the thing writing it touching any light directly.A dropdown setting inside Home Assistant that can only ever hold one of a few named choices. It's used here to store which lighting mode is active, so a separate automatic rule can watch it and turn the right lights on, rather than whatever set the mode having to control each light itself.

Linear

A project- and task-tracking tool, used here to log to-do items and let this assistant pick up and act on tasks directly through comments.An app for tracking to-do items and projects, used here to give this assistant a to-do list it can read and act on.

lobby

DiceLock's room-code system for getting people into the same multiplayer match: host a room, share its code, and whoever enters it takes one of the room's open seats. The same lobby machinery underlies every room-based mode, so a new mode just needs its own seat count and rules once it exists.The dice game DiceLock's system for getting people into the same online match: one person hosts and gets a code, and anyone who enters that code takes an open seat in the room. Every mode built around room codes runs on this same system underneath.

Mermaid

A small text language for describing a diagram (boxes, arrows, the labels on both), which a renderer turns into a picture. The point of writing a diagram as text is that it lives in the repository next to the code it describes, so a change to it shows up in a diff like any other change, instead of being a drawing somebody exported once and never opened again.A way of describing a diagram by typing it out (these boxes, these arrows) and letting a program draw it for you. Because it is text, it sits with the code and any change to it is visible, unlike a picture somebody drew once and forgot.

milestone

A group of tickets in Linear meant to ship together, distinct from the project they all belong to. A milestone says which tickets go together; it never used to say which one goes first.A batch of related to-do tickets meant to be finished together, inside a bigger project. Being in the same batch never used to say which one comes first.

ntfy

A free, simple push-notification service. Send it a message and it shows up on your phone, no account required beyond installing its own notification app once.A simple, free way for a script or program to send a notification straight to your phone.

OKLab

A way of describing colors as three numbers, built so that two colors a set distance apart in it look about equally different to a human eye no matter where in the color range they sit. That makes it possible to compute whether two colors are "far enough apart" to tell apart at a glance, including under a simulation of color blindness, rather than guessing from the hex codes.A way of describing colors with numbers that line up with how different two colors actually look to a human eye, so a program can check whether two colors are far enough apart to tell apart at a glance, including for someone who is color blind, instead of just guessing from the color codes.

Plaid

A service that sits between an application and a bank, so the application can read balances, transactions and holdings through one API rather than a different integration per institution. It can also initiate payments, which is exactly why an application that only ever needs to read is worth constraining explicitly: the ability to move money is available on the same credential, one field away.A service that connects an app to your bank so it can read your balances and transactions without needing a separate arrangement with every bank. It can also send money, which is why an app that only needs to look at your accounts is worth locking down.

Playwright

A tool that drives a real web browser by script, clicking, typing and reading the page back, so a program can test a site the way a person would rather than by calling its code directly. It can also freeze the browser's own clock, so timers, animations and the page's sense of "now" only move forward when the script tells them to.A tool that controls a real web browser by script, clicking buttons and reading the screen the way a person would, so a program can test a website without a human sitting at it. It can also freeze the browser's clock, so animations and timers only move when the script says to.

raid room

DiceLock's shared room for its raid boss fight, built on the same lobby machinery as every other room-based mode but seating up to four players against one boss instead of pairing opponents. A room shows the boss's life total, fills seats as players arrive, and lets the host start the fight at any headcount once someone else has joined; closing the room mid-fight or the host handing it off are both said out loud to everyone in it.A shared online room in the dice game DiceLock where up to four players team up against one boss, instead of the usual one-on-one match. It shows the boss's health, fills up with seats as people join, and lets whoever is hosting start the fight once at least one other player is in.

Sentry

A service that collects crash and error reports from an app's various parts (a server, a web page, a phone app) and groups them so a maintainer can see what broke, how often, and where, instead of each failure happening silently.A service that collects error reports from an app, so whoever maintains it can see what broke and how often, instead of a crash just happening unnoticed.

Smart Home Skill

A category of Alexa Skill built around Amazon's own device model (discovery, on/off, brightness, scenes), but one that Amazon requires to be hosted as a Lambda function, unlike the simpler Custom Skill kind Big Brain actually is. Its endpoints only appear to "Alexa, discover devices"; a Custom Skill has to be reached by naming it, "ask Big Brain for...".One particular kind of Alexa voice app, the kind meant for smart devices like lights and plugs, that Alexa can find automatically with "discover devices." It has to be built a specific technical way that this project's assistant, a simpler kind of voice app, isn't. So it can't be found that way, and has to be reached by name instead, like "ask Big Brain for dinner mode."

Stockfish

A very strong, free chess engine used to evaluate how good or bad a chess move was. It is the raw analysis a chess coaching tool would build on top of.A free, very strong chess-playing computer program used to judge how good or bad a chess move actually was.

Strava API

Strava's official way for software to pull GPS activity data (runs, rides, hikes) for accounts that have specifically approved access.Strava's official way for an app to pull someone's GPS activity data (runs, rides, hikes) once that person has approved it.

tapback

iMessage's quick reaction on a message: a heart, thumbs-up, exclamation or one of the other built-in icons, or, more recently, a custom emoji, attached to a message without sending a reply of its own. It is stored as its own kind of message naming which message it targets, rather than as text.iMessage's built-in reaction you can tap onto a text instead of typing a reply: a heart, a thumbs-up, an exclamation mark, or, more recently, any emoji you pick. It's recorded as its own small message pointing at the one it's attached to, rather than as actual text.

TestFlight

Apple's system for putting an iPhone or iPad app in front of testers before it goes on the App Store. A build is signed, uploaded, and then invited testers can install it like a regular app, without Apple's public review.Apple's way of sending an app out to a small group of testers to try before everyone else can download it from the App Store.

the Ladder

DiceLock's ranked puzzle mode: climbing levels on rated puzzles with three regenerating lives, a season-long rank, and boards above level 30 dealt from a server-side bank built so a player never gets the same one twice in a season. Replaced the Daily, DiceLock's earlier ranked puzzle mode.A ranked puzzle mode in the dice game DiceLock. You climb levels by solving puzzles, with three lives that slowly refill, and your rank for the current multi-month "season" moves with how well you play. It replaced the game's older ranked puzzle mode, called the Daily.

versionCode

The integer Google Play uses to tell one uploaded build from the next. It has to go up every time, across every testing track at once, so a build that reuses or skips a number gets rejected rather than silently replacing the one before it.The number Google Play uses to tell one upload of an app from the next. It always has to go up, never repeat or skip around, across every group of testers at once.

WordNet

A large, freely available database of English words grouped by meaning, where each word is linked to its close synonyms and to the words a step away from it in sense. It is a common base to build a dictionary check or a word-relationship feature on top of, rather than starting a word list from scratch.A large, free database of English words, grouped by what they mean and linked to their close synonyms. It's a common building block for anything that needs to check whether something is a real word or find words related to it.

Infrastructure & Hosting

CDN

A content delivery network: a fleet of servers spread across the world that hold copies of files and serve each visitor from one near them. Files on one are usually addressed by signed links that expire, so a URL copied out of a CDN is only good for a few hours.A network of computers around the world that keep copies of a website's pictures and files, so each visitor gets them from one nearby instead of from the other side of the planet. The links to those copies usually stop working after a few hours.

Cloudflare Tunnel

A secure, outbound-only connection from a home computer to Cloudflare's network, used to make a service reachable on the internet without opening any inbound ports on the home network. The computer connects out to Cloudflare; nothing connects in directly.A way to make a website or service on a home computer reachable from the internet, without opening up the home network to outside connections. The computer calls out to make the connection instead of letting strangers call in.

Cloudflare Worker

A small program Cloudflare runs on its own network rather than on a server you keep. Most have a web handler and answer HTTP; one can instead have only an email handler, invoked directly by Email Routing when a message arrives, in which case it has no URL at all and asking for one is a category error.A small program that runs on somebody else's network instead of on a computer you own. It gets woken up when there is something to do (a page to serve, or in this case an email to process) and costs nothing while it sits idle.

Colyseus

An off-the-shelf framework for real-time multiplayer game rooms: it handles seating players into a shared session and relaying messages between them over a live connection, so a game only has to write the rules of the match rather than the networking underneath it.Ready-made software for building live multiplayer games. It handles seating players together and passing messages between them, so a game doesn't have to build that networking plumbing itself.

control plane

A single directory on this machine holding the things every project here needs but none of them owns: shared credentials, and the map of where each sibling repo is checked out. It exists so the monorepo can be split into separate repos without every package losing track of the others.One shared folder on the machine holding the passwords and addresses that every part of the system needs, so the parts can live in separate places and still find each other.

disk ballast

A deliberately wasted reservation of disk space, held as an ordinary unused file so it can be deleted in an instant to free that space back up the moment the machine actually starts running low, rather than scrambling to find something real to delete under pressure.A chunk of disk space deliberately set aside and left empty on purpose, purely so it can be deleted in a hurry to free up room the moment the machine actually starts running low, instead of scrambling to find something real to delete under pressure.

Docker

A tool for running software in an isolated, self-contained package (a "container") so it doesn't depend on whatever else is installed on the host computer. Used here to run Home Assistant.A way to package up a piece of software with everything it needs to run, so it works the same way on any computer without extra setup.

environment variable

A named value handed to a program by whatever started it, the usual way to pass a file path or a credential in without writing it into the code. The catch is that it is inherited: anything that program then starts gets the same values, so a setting meant for one process can silently reach every process downstream of it.A setting passed to a program by whatever started it. Anything that program starts in turn inherits the same settings, which is how a value meant for one thing quietly ends up affecting another.

event log

An append-only file in the control plane where anything notable (a commit, a degraded capability) writes one line saying what happened, where, and when. Its value is entirely in being joinable to everything else, so a line tagged with a location no other tool recognises is technically accurate and practically invisible.A running list of everything that happens on the machine, one line each: what it was, where, and when. It is only useful if the 'where' matches what everything else calls that place.

Homebrew

The most common package manager for installing developer command-line tools on a Mac, essentially an app store for things like git or the GitHub CLI.A tool for installing extra software on a Mac from the command line. It is like an app store, but for developer tools.

Keychain

macOS's encrypted credential store, where interactive apps keep passwords and tokens. Background processes started by launchd don't get access to it, which is why a service can be locked out of a credential that works perfectly from a terminal.The locked drawer on every Mac where apps keep passwords. Programs running in the background can't open it, so they need their credentials handed to them another way.

LaunchAgent

Like a LaunchDaemon, but tied to a specific logged-in user rather than the whole system. It is used here when a background job needs to inherit that user's own permissions, like access to Messages data.Like a LaunchDaemon, but it only runs when a specific person is logged in, since it needs to use that person's own permissions to do its job.

launchd

macOS's built-in system for managing background services. LaunchDaemons and LaunchAgents are both configured through it.The system built into every Mac that's in charge of starting and stopping background programs automatically.

LaunchDaemon

A macOS system service that starts automatically at boot and keeps running in the background, independent of any user being logged in. It is the standard way this project keeps its always-on services (like the website and the Alexa backend) alive across restarts.A little program on a Mac that keeps something running in the background all the time, even before anyone logs in, so a service doesn't stop just because no one's using the computer.

MX record

The DNS entry that says which server receives mail for a domain. There is one set per domain rather than one per subdomain, so pointing it somewhere new moves all of that domain's mail at once, which makes switching it a whole-identity decision rather than a reversible experiment.The signpost that says where a domain's email should be delivered. There is only one per domain, so changing it moves all of that domain's mail at once.

PATH

The ordered list of folders a shell searches when you type a bare command name. If the program you want lives somewhere not on that list, the shell reports it as not existing at all, which is indistinguishable, from the typist's side, from never having been installed. Adding a folder to it is one line in a shell startup file, with the catch that those files are read by interactive shells only: scheduled jobs and scripts get their own, usually much shorter, list.The list of folders your terminal looks in when you type a command. A program sitting anywhere else may as well not be installed, because the terminal will simply say there is no such command. Adding a folder to the list is a one-line change, but it only applies to terminals a person is typing in, not to things running on a schedule.

plist

The small configuration file macOS reads to learn how to run a background job: what command to run, when, and from which directory. Every path in it is absolute, which is why moving code between checkouts means rewriting one per job, and why a plist can go stale on disk without anything failing until the next time the job is loaded.The little settings file macOS reads to know how to run a background job. It spells out the full location of everything, so moving the code means editing the file, and if you forget, nothing complains until the job is next started.

Railway

A hosting platform that runs an application's server continuously, redeploying it automatically on every push. It ends the old container with SIGTERM before starting the new one, and its dashboard reports a deployment as crashed based on the exit code that container returns, not on whether the site actually stayed up.A service that keeps a website's server running around the clock, and automatically swaps in a new version whenever the code changes. It flags a deployment as "crashed" based on a technical exit signal from the old copy shutting down, not on whether the site was actually working.

Render

A hosting platform that runs an application's server and, separately, a managed Postgres database, deploying a new version whenever it's told to. A service on it can be set to deploy automatically on every push to main, or to wait for an explicit deploy call naming the exact commit to run.A service that keeps a website's server running and can also run its database for it, automatically putting out a new version whenever it's told to. It can be set to do that the moment code changes, or to wait until it's specifically told which version to run.

runbook

The written procedure for operating one piece of infrastructure: how to restart it, what to check first, what the failure looks like. Its whole value is that it is read at the worst possible moment, by somebody who does not have time to verify it, which is also why it is the document most dangerous to leave stale: a step that has quietly become a no-op still reads as mandatory, and a warning that has stopped being true still reads as a reason not to act.The written instructions for keeping one part of a system running: how to restart it, what to look at first, what going wrong looks like. The whole point is that somebody reads it in an emergency, without time to double-check any of it, which is exactly why letting it go out of date is worse than not having written it.

SIGKILL

The forceful signal one program sends another to end it immediately, with no chance to clean up or finish what it was doing. Unlike SIGTERM, a process cannot catch it, ignore it, or delay it.The 'stop right now, no excuses' message one program can send another. Unlike the polite version of that message, the program receiving it has no way to ignore it or ask for more time.

SIGTERM

The polite signal one program sends another to tell it to shut down, the same thing a timeout or a restart sends. The receiving program is meant to stop, but gets no guarantee of time to finish or save what it was in the middle of.The 'please stop now' message one program sends another, used by things like timeouts. Whatever the program was halfway through doing is usually lost.

Tailscale

A tool that creates a private, secure network between your own devices, letting them reach each other (like over SSH) without exposing anything to the public internet.A tool that lets your own devices talk to each other privately and securely over the internet, as if they were all sitting on the same home network.

ttyd

A small program that makes a terminal (command-line window) accessible through a web browser, so a computer can be operated remotely without a separate remote-desktop app.A tool that lets you open a command-line window right inside a web browser, so you can control a computer remotely without installing separate remote-access software.

Engineering Practice

architecture decision record

A short numbered document recording one design decision, what was rejected and why, written at the time rather than reconstructed later. The value is in the rejected options: without them, a future reader only sees the choice and assumes nobody thought about the alternative.A short note written at the time a design choice is made, saying what was chosen and what was turned down. The rejected options are the useful part. Otherwise nobody later knows whether the alternative was considered at all.

background task

A command an AI session starts and then walks away from, collecting the output later instead of sitting through it, the natural way to handle a slow download or a throttled fetch. The trap is that it belongs to the session's process rather than to the machine: an unattended session that ends its turn has exited, and the exit reaps every background task it left running, so waiting for one by ending a turn is the single reliable way to destroy it.A job an AI session kicks off and checks back on later, rather than watching it the whole time. The catch is that it only lives as long as the session does. When the session finishes, anything it left running is shut down with it.

bb suite

A first-arrived, first-served queue in the control plane that a repo's full test suite waits its turn in, so only one full run happens on the machine at a time instead of sessions polling and starting on their own. It logs how long each run waited and how long it took, separate from the job queue, which orders dispatched work rather than test runs.A waiting line, built into the shared control system, for running a project's full set of automated checks. Before it existed, every session just checked every so often whether the computer looked free and jumped in, which could let two full test runs start at once. It keeps a record of how long each run waited and how long it took.

coded error

A server response that names what went wrong with a stable code, domain, and HTTP status, not just a sentence for a person to read. It lets a client branch on why a request failed, such as retrying an outage instead of signing someone out, without pattern-matching English that was never a contract.A way for a server to say what went wrong using a short fixed label instead of an ordinary sentence. A program can safely check the label to decide what to do next (try again, ask you to log in again) in a way it can't safely do with a sentence, which might be reworded later.

contrast ratio

A number describing how much two colors stand out from each other, measured from 1 (identical) to 21 (pure black against pure white). Accessibility guidelines set a minimum ratio, usually 3 or 4.5 to 1, for text or shapes that need to read clearly against their background, including for someone with color-blindness.A number that says how much two colors stand out from each other, from 1 (no difference) up to 21 (black against white). Accessibility rules set a minimum number for things like text, so they stay readable against their background, including for someone who is color-blind.

debounce

Waiting a short time after an event before acting, so a burst of events close together produces one response instead of one each. Used here so a change landing in several repos within a minute regenerates the blog once rather than once per commit.Waiting a moment before reacting, so a flurry of related changes causes one response instead of a dozen.

dry run

Running a command with every write disabled, so it resolves and prints exactly what it would do and changes nothing. Worth making the default rather than a flag for anything that writes into a system a human reads. The cost of an unwanted dry run is a wasted minute, and the cost of an unwanted real run is twenty-one tickets somebody now has to delete by hand.Running something with all its changes switched off, so it tells you exactly what it would have done without doing any of it. Best made the default for anything that creates real things, since a pointless practice run costs a minute and a real one costs an afternoon of undoing.

fast-forward

Moving a checkout straight up to a newer saved state, with no merging required, because that newer state was built directly on top of the one already there. The blog publisher writes and commits in a separate working copy and then fast-forwards the main checkout onto it. That is the step that actually publishes, since the live site is served off that checkout's files rather than out of the repository history. Git refuses to do it whenever the two have genuinely diverged, which is the point: a refusal is a signal to stop, not a problem to force past.Catching one copy of a project up to another by simply sliding it forward, when nothing has changed underneath it to argue with. If the two copies have genuinely drifted apart, it refuses rather than guessing, which is exactly what you want it to do.

git remote

The other copy of a repository that a local checkout pushes to and pulls from, usually one hosted on GitHub. A repo with no remote still records history perfectly well, but that history exists on exactly one disk: nothing is backed up, nothing is visible to anyone else, and there is no second copy to restore from.The online copy of a project that your computer sends its work to. Without one, everything you have done still saves fine, but it only exists on that one machine, with no backup and nothing anyone else can see.

in-memory mock

A stand-in that answers like the real thing without doing anything: fake bulbs instead of the actual lights, holding its answers in memory and forgetting them when the process ends. Fine as a deliberate test fixture; dangerous as a fallback, because a system running on one reports success for every command it is given.A pretend version of something that answers as if it were real but does nothing. It is useful for testing, disastrous when the real thing goes missing and nobody notices the answers stopped meaning anything.

K-factor

In an Elo-style rating system, the number that sets how hard a single result can move a rating: a win raises it and a loss lowers it by K times how surprising the result was. A high K-factor makes a rating swing fast and settle quickly; a low one makes it move slowly and stay stable once there.In a system that scores how good someone is at something, the number that controls how big a jump one win or loss can cause. A high version of this number makes a score swing around a lot; a low one keeps it moving slowly and steadily.

load-time ceiling

A hard limit on how long a page is allowed to take to load or paint, checked automatically on every build. Unlike a byte-count limit, which comes back to the same number every time an unchanged page is measured, a timing number moves with whatever else the machine happens to be doing at that moment, so a single miss against it is not on its own proof that the page got slower.An automatic limit on how long a page is allowed to take to show up on screen, checked every time the code changes. Unlike a limit on how much data a page sends, which gives the same answer every time you measure an unchanged page, a timing measurement can come out different from one run to the next depending on what else the computer is doing, so one slow result by itself doesn't prove the page actually got slower.

post-commit hook

A script that runs automatically every time a change is saved ("committed") to the project. This is what triggers the daily blog post to write itself.A little script that runs automatically every time a change is saved to the project, like a trigger that fires right after you hit save.

Promote tap

A single button on a standing per-repo message that is the only way a commit on main reaches production once a repo's automatic deploy is switched off. Tapping it checks out the exact approved commit in a clean folder, runs the install, typecheck and full test suite, then deploys that commit and polls until the host reports it live, editing the same message to say how it ended.A single approval button that is now the only way a finished code change actually goes live for an app whose automatic deploys have been switched off. Tapping it runs the full set of checks on the exact version approved, then sends it out and reports back, on the same message, whether it worked.

re-parent

Moving a working copy's next commit so it sits directly on top of the current main line, rather than beside it, so the live checkout can fast-forward onto it instead of refusing. The blog publisher does this because it starts work in a worktree that may be half an hour out of date by the time it commits. The subtlety that cost a morning: the git reset that re-parents deliberately leaves the files on disk untouched, so re-parenting alone makes a commit a descendant of main without making its CONTENTS agree with main, so staging a file main moved during the run silently commits the version from before the move.Lining up work done in a side copy so it sits neatly on the end of the main one, instead of off to the side where it would have to be merged. The catch is that this only rearranges the bookkeeping: the actual files in the side copy are left exactly as they were, so anything changed underneath in the meantime gets quietly written back to its old state.

rebase

Replaying a branch's commits on top of a newer copy of the branch it started from, so it ends up built on everything that has landed there since, instead of the stale snapshot it was cut from. A clean rebase means every commit replayed without a conflict; a failed one hands the conflicting files back to whoever is still working the branch.Taking a finished piece of work and re-applying it on top of the very latest version of the shared project, rather than the older version it was started from. If it fits cleanly, nothing else needs to happen; if it doesn't, someone has to go sort out what collided.

shadowcasting

An algorithm that works out what is visible from a point on a grid by casting lines outward and stopping each one at the first thing that blocks it, such as a wall or a tree. Run often enough, it gives each side of a match its own up-to-date view of what it can and cannot see.A way of figuring out what someone standing in one spot could actually see, by checking outward in every direction and stopping at the first thing in the way, like a wall or a tree.

smoke test

A quick end-to-end run of a newly built path with real inputs, just to establish that it works at all before trusting it. It is not thorough coverage, but the difference between "the pieces look right" and "a real request went in one end and came out the other".Running a new thing once, for real, to see whether it works at all. It is not an exhaustive check, just proof it isn't dead on arrival.

soak

A deliberate waiting period between shipping a fix and declaring it worked, so the same measurement can be taken again across a stretch of real traffic rather than a moment of it. It exists because an intermittent fault (three errors a day, say) cannot be disproved by one check straight after the change, and because the wait is only worth anything if the thing that used to fail was genuinely running throughout it.Deliberately waiting a while after a fix before declaring it worked, so you can re-count a problem that only turns up now and then. Checking once, right after the change, proves very little; checking again three days later proves rather more, provided the thing that used to break was actually running the whole time.

test fixture

A piece of fake data stood up so a test has something to run against: a synthetic message blob, a throwaway database, a canned API response. The failure mode worth knowing: if the fixture is built from the code's own assumptions about the real format rather than transcribed from the real thing, the test can only prove the code agrees with itself, and it will stay green through a bug that ruins every real input.Fake data made up so a test has something to work on. The trap is building that fake data from the same misunderstanding the code has. Then the test happily passes while the real thing is broken.

test-count conservation

Recording how many tests ran before a structural change and checking the same number still runs after it. The failure it catches is invisible in a diff: a test file that lands in the wrong repo, or is left behind in an old copy, simply stops being executed, and a suite that quietly runs fewer tests still reports every one of them passing.Counting the checks before and after moving code around, to make sure none of them quietly stopped running. A check that never runs still looks like a check that passed.

worktree

A second, separate working copy of the same git repository, checked out at its own path so it can be built, run, or measured without disturbing the primary checkout. Useful for ruling out the machine itself as a cause: if a byte-for-byte identical worktree fails the same check the primary one does, the check's own measurement is the suspect, not whatever the primary checkout happened to change.A second copy of the same project's code, sitting in its own folder, so you can run or test it without touching the copy you're actually working in. It's handy for ruling out your own machine as the cause of a problem: if an exact copy of the unchanged project fails the same check, the check itself is the suspect, not anything you did.

Web, Security & APIs

access token

A temporary, revocable credential that grants access to a service's data or actions, without ever exposing the underlying account password, usually the end result of an OAuth login.A temporary keycard an app gets after you log in somewhere, letting it act on your behalf without ever knowing your actual password, and it can be taken away at any time.

allowlist

A closed list of what is permitted, where anything not named on it is refused. The opposite arrangement, a list of what is forbidden, fails quietly the day somebody invents a new thing to do, because a capability nobody thought to ban is allowed by default. The cost is that the list has to be widened deliberately whenever the system legitimately needs something new, which is the point: widening it is a visible edit rather than an accident.A short list of exactly what something is allowed to do, where anything not on the list is refused automatically. It is safer than a list of banned things, because that only covers what somebody thought to ban. Anything new slips through.

app password

A separate, long-lived password Google generates for one specific app or script, instead of your real account password. It only works for that one purpose, can be revoked on its own without touching your main login, and unlike the limited, revocable access behind OAuth logins, it doesn't expire on a fixed clock.A separate password Google lets you generate just for one program to use, so that program never sees or needs your real account password. You can cancel it any time without changing your main password, and unlike the usual "log in with Google" kind of access, it doesn't expire on its own after a set number of days.

BigInt

A JavaScript number type for integers too large to store exactly in JavaScript's ordinary number type, kept as its own separate kind of value rather than converted silently. The built-in function that turns a value into text for sending over the network, JSON.stringify, does not know how to handle one and throws instead, so any code expecting an ordinary number has to be written to expect a BigInt might show up instead.A special kind of very large whole number in JavaScript that doesn't fit in the ordinary number type the language normally uses. The built-in tool for turning a value into text to send over the network doesn't know what to do with one and fails outright, so code has to be written to expect one might turn up.

browser extension

A small program a browser runs on every page a visitor opens, able to add its own menu items, read or edit the page's content, or talk to its own server, under permissions it has to declare up front. It runs separately from the site that happens to be open, which is what lets it work the same way on any page rather than only on the one it was built for.A small add-on a web browser can run on every page you visit, letting it add menu items, read or change what's on the page, or fetch its own information, within limits it has to state up front. Because it isn't part of any one website, it can work the same way no matter which site you're looking at.

CA bundle

A collection of trusted "root" certificate authorities that a computer uses as its ultimate reference point when checking whether a certificate chain is trustworthy.A built-in list of trusted "notaries" a computer keeps, so it has something to check a certificate chain against.

certificate chain

The trail of digital signatures that lets a computer confirm a security certificate was genuinely issued by a trusted authority, rather than made up. It is verified here when confirming a request really came from Amazon's Alexa service.The trail of proof a computer follows to confirm a security certificate is legitimate, tracing back step by step to a source it already trusts.

chip row

The small labelled links printed under a feature on a project page, one per part of the system that feature touches. Each one is a real link to the diagram further down, which is what makes it work with no JavaScript and with a keyboard; the highlight that dims every other box is layered on top. Being a link is also where its bugs come from, because following one scrolls the page, and a page that scrolls underneath a pointer that never moved looks exactly like a reader moving away.The little labels shown under each thing a project does, naming the parts of the system it uses. Each is an ordinary link down to the diagram, so it works without any clever code, and pointing at or tapping one lights up the matching boxes.

Credential Manager

Android's built-in system for signing in: it shows the native account picker and hands back a token, so an app's sign-in button never has to open a browser tab or see a password.The sign-in screen built into Android phones. An app can use it to let you pick your Google account without ever opening a separate browser page.

CSS

The language a web page uses to say how things should look: colours, sizes, spacing, what a button does when pressed. It lives apart from the page's content, so one rule can restyle every button at once, and when two rules disagree the one written later or more specifically wins, which is a whole class of bug on its own.The language a web page uses to say how things should look: colours, sizes, spacing, what a button does when pressed. It lives apart from the page's content, so one rule can restyle every button at once, and when two rules disagree the one written later or more specifically wins, which is a whole class of bug on its own.

Custom Tab

A browser window Android opens inside another app's own task, running as Chrome with the visited site's real address bar, used so a sign-in page can show its own site's identity rather than being dressed up to look like part of the app.A browser window that opens on top of an app, showing the real website and its real address, so a sign-in page can't be faked to look like it's part of the app.

design token

A named value (a spacing step, a colour, a font size) defined once and referred to everywhere it's used, rather than the literal number being retyped at each site. Changing the rhythm of a whole site then means editing one declaration instead of hunting down every hardcoded margin, and it makes the intent visible: two different gaps with two different names are obviously meant to be different, where two identical numbers just look like a coincidence.Giving a design decision (how big a gap is, what shade a colour is) a name, and using the name everywhere instead of the number. Change it in one place and the whole site follows.

DKIM

A signature the sending mail server puts on a message, checkable against a key published in the sending domain's DNS. A pass says the message really did leave that domain and was not altered on the way, which is how an arriving message can be told apart from one injected locally into the same database.A stamp the sending mail service puts on an email that proves it genuinely came from the domain it claims, and that nobody rewrote it in transit.

DMARC

The policy a domain publishes saying what a receiver should do with mail claiming to be from it that fails the underlying signature and sender checks: accept, quarantine, or reject. It is the layer that makes DKIM worth checking, since a signature nobody has said anything about is only evidence, not a rule.A domain owner's published instruction for what to do with email that claims to be from them but fails the authenticity checks: let it through, put it in spam, or throw it away.

DSN

The address and key a piece of software is given so it knows where to send its crash reports and which project in Sentry they belong to. Every report names the DSN it was sent for, which is also how a receiving server can check it is being asked to forward to the right place and nowhere else.The address and key an app is given so it knows where to send its crash reports and which project they belong to.

Email Address Obfuscation

A Cloudflare setting that rewrites any mailto: link on a page into a script-decoded placeholder, so a scraper reading the raw HTML sees no real address. It runs on the served page rather than the file in a repo, so a page can look correct in the source and still be wrong on the wire. It was caught here only because the address was checked against the live page, not just the file that was written.A Cloudflare setting that hides email addresses on a page behind a bit of code, so a program scanning the page's text can't just read them out. It only shows the real address once a visitor's browser reassembles it with JavaScript, so a page can look right in the file that was written and still show the wrong thing once it's actually served.

exclusive cursor

A "give me everything older than this" marker that an API treats strictly: an item sitting on exactly the timestamp you name is left out. Harmless when the timestamp identifies one item, dangerous when several share it, because the ones you never asked about again vanish with nothing to show they existed. The safe answer is to name a moment one tick later and drop the duplicate yourself. That costs one row per page, and a count that forgets that is wrong by exactly that much.A bookmark that says "carry on from just before this point", where anything landing exactly on the point named is skipped. If several things happened at the same second, asking for the point itself loses the rest of them silently, so it is safer to ask for a hair later and throw away the repeat you get back.

focus ring

The outline a browser paints around whatever the keyboard is currently pointed at, so somebody tabbing through a page can see where they are. It is drawn just outside the element's own box, which is what makes it easy to lose: any effect that clips an element to its box (a fade applied to the edges of a scrolling frame, for instance) clips the ring away too. The browser still computes it, the page still reports it as focused, and nothing is painted, so this is a class of bug only a real browser will show you.The outline a browser draws around whatever you have tabbed to, so you can see where you are without a mouse. It sits just outside the edge of the thing it marks, which means an effect that trims an element to its edges can quietly erase it. Everything still behaves as though it is there, and nothing appears on screen.

fragment jump

What a browser does when you follow a link ending in `#something`: it stays on the page and scrolls the matching element into view. No request is made and no handler has to run, which is what makes an in-page link work with JavaScript switched off. But the scroll it causes moves everything under a pointer that never moved, so boundary events like `mouseleave` can fire as a direct result of the click that was supposed to be a highlight.What happens when a link points at a spot further down the same page: the browser stays put and scrolls you to it. Nothing is loaded, but the page slides underneath your finger or cursor, which can look to the page like you moved away when you did not.

gain node

A volume knob inside a browser's audio engine: every sound routed through it gets multiplied by one number before it reaches the speakers. Chaining several of them lets separate sounds share one on-off switch while still being levelled against each other independently, rather than forcing every sound through a single shared number.A digital volume knob a web page's sound system can put in front of any sound it plays, so turning that one knob changes the loudness of everything passing through it. Several of them can be chained, so a game can have one overall mute switch and still let different kinds of sound, like music and effects, be turned up or down separately underneath it.

HMAC

A way of scrambling a piece of data, such as an address, using a secret key the scrambler holds, so the result can't be reversed back into the original and nobody without the key can produce the same scrambled value for a different input. The same input and the same key always scramble to the same output, which is what lets a server tell two visits from the same device apart from two different devices without ever storing the raw value.A way of turning something, like an address, into a scrambled code using a secret key, so the scrambled code can't be turned back into the original but the same input always produces the same code.

IMAP

The protocol a mail client uses to read a mailbox that lives on someone else's server, such as Gmail. A read-only connection opens a mailbox without marking anything read or moving it, so a tool can scan mail without changing what the owner sees when they open it themselves.The standard way a program reads an email inbox that's actually stored on a mail provider's server, like Gmail's. Opening it read-only means the program can look at the mail without marking anything as read or moving it, so it doesn't change what you see when you check your own inbox.

keepalive

An option on a browser's fetch request that lets the request keep going even if the page that started it is being closed or navigated away from, instead of being cut off mid-send. It exists so a page can reliably get a last piece of data out the door on its way out, without needing a separate, more limited method just for that moment.A setting on a web request that lets it keep sending even while the page that started it is in the middle of closing, instead of being cut off half-finished.

localStorage

A small key-value store a browser keeps for each site, on the visitor's own device, that survives a reload and stays put until the site or the visitor clears it. It has no server-side counterpart, so it is the natural place to remember something that is purely about how one visitor's browser last looked at a page (a scroll position, a zoom level) without that preference leaking into a link shared with anyone else.A small stash of settings a website keeps inside your own browser, on your own device, that survives a reload but never gets sent to anyone else. It's the natural place to remember something purely personal to how you're looking at a page right now (like how far you'd zoomed in) without that becoming part of a link you might share.

OAuth

A standard way to let one app act on your behalf on another service, like Strava or Gmail, without ever handing over your actual password. You approve access once, and the app gets a limited, revocable token instead.The system behind "log in with Google"-style buttons. It lets an app do things on your behalf on another service without ever actually seeing your password.

pseudo-element

A piece of styling that paints an extra box in front of or behind an element without adding a real element to the page's markup for it. It is addressed off the element it belongs to, so when that element moves, resizes, or is pinned in place by the page's layout, the pseudo-element moves, resizes, and is pinned with it, and there is nothing in the document to keep track of separately.A bit of styling that draws an extra shape on top of or behind something on a page, without that shape being a separate item the page has to track on its own. It just rides along with the thing it's attached to, so if that thing moves or changes size, the extra shape follows automatically.

push notification

A message a server sends to wake a phone app that is not open, like the note saying a friend beat your score. Only Apple and Google can actually deliver one to a device, so every push goes through their services, both free; paid push providers are a convenience layer on top, not the only way in.A short alert an app can send to your phone even while the app is closed. Apple and Google carry these messages for every app, free of charge, which is why most apps do not need an extra company in the middle to send them.

rate limit

A cap a service puts on how many requests it'll accept from you in a given amount of time, to prevent overload or abuse.A speed limit a service puts on how often you're allowed to ask it for something, so it isn't overwhelmed.

refresh token

The longer-lived half of an OAuth login, handed over alongside the short-lived access token purely so software can quietly trade it for a fresh one when the old one expires, with no browser and no human. Nothing renews itself unless something is actually scheduled to do the trading, which is a surprisingly easy step to skip.A spare key handed over at login, whose only job is to let an app quietly renew its own temporary pass before it runs out, instead of asking you to log in again every day.

restricted scope

Google's tightest tier of OAuth permission: the ones that hand an app the actual contents of a mailbox or a drive, rather than just a name and an email address. An app asking for one has to pass a formal verification review before it can be published; until then its consent screen stays in Testing, and that is what puts a seven-day fuse on every refresh token it issues.The most sensitive kind of permission an app can ask Google for: the ones that open up your actual mail or files, not just your name. Asking for one means the app has to pass a formal review before it is allowed out in the open, and until it does, the access it is granted quietly expires after a week.

root-relative link

A link written from the site's root rather than from the page it sits on (`/chess-report` rather than `../report.html`), so it means the same thing on every page that carries it. That is also what makes them checkable in bulk: each one names a path the server must be able to resolve to a real file, so a script can walk every page and assert that all of them do.A link written as a full path from the front door of the site rather than as directions from wherever you happen to be standing. Because each one names one fixed destination, a program can walk every page and check that all of them lead somewhere that actually exists.

SCRAM

A password authentication method where the server stores a one-way derived verifier instead of the password itself, so proving a login never requires sending the plaintext password or storing it in a form a leak could use directly. Postgres uses it for logins by default.A way of checking a password where the system doing the checking never actually has the real password written down anywhere, only a scrambled version it can use to confirm a correct guess without ever storing or revealing the original.

server-rendered

Building a page's markup before it's sent, so the browser receives it already complete, rather than shipping an empty shell and letting JavaScript fill it in after the page loads. It means the content is there for readers with JavaScript off and doesn't visibly pop in a moment after the rest of the page paints.Building a page fully before sending it, so it arrives complete rather than filling itself in a moment after it loads.

server-sent events

A one-way stream a server holds open to a browser and writes lines into as things happen, so the page updates without asking. Each line carries an id, and the browser sends the last id it saw when it reconnects. That is the whole point on a machine where the server restarts on every deploy, because a reconnect that silently skipped the events it missed leaves a page that is wrong and looks fine.A way for a page to be fed updates as they happen instead of asking over and over. Each update is numbered, so when the connection drops the page can say where it got to and be sent only what it missed.

setup token

A long-lived credential minted once by the Claude CLI's setup-token command and valid until revoked, unlike the normal login whose short-lived token has to keep refreshing itself. Background sessions on this machine now carry one, so an interactive login rotating the refresh token can no longer strand them without a working credential.A special long-term pass for automated work, created once and good until cancelled on purpose, so my background helpers stay logged in even when my own login gets renewed and would otherwise knock theirs out.

SSH

A protocol for securely logging into and running commands on a remote computer over an encrypted connection. It is what a remote terminal session is built on, and the connection this project locked one low-privilege account down to a single, unchangeable command.A secure way to connect to and control another computer over the internet from somewhere else, like opening a command line on a machine that isn't the one in front of you.

SVG

A picture stored as a list of shapes and their coordinates rather than as a grid of pixels, which means it stays sharp at any size and, more usefully here, that a browser can address the individual parts of it. That is what makes a diagram on a project page interactive: each box is a real element the page can name, style and light up, so one drawing can illustrate every feature instead of one drawing per feature.A picture stored as instructions for drawing it (this box here, this arrow there) instead of as a photograph of the result. It never goes blurry when it is enlarged, and the page can point at any single box in it, which is how one diagram can highlight a different part of itself for each thing being described.

User-Agent

A line of text a program sends with every web request naming what it is. Nobody verifies it, so it is a courtesy rather than a credential. But on a crawler it is the only way the owner of a small site can tell an automated reader from a person, and writing it in plain words with a contact address is the difference between being asked about and being blocked.A short note a program attaches to every web request saying what it is. Nothing checks that it is true, so it is a courtesy rather than proof. But for something that reads lots of websites automatically, it is the only way the site's owner can tell it apart from a person and get in touch instead of just blocking it.

vendoring

Committing a third-party library into your own repository and serving it from your own domain instead of pointing the page at somebody else's CDN. It costs you the upgrade (a new version is a new directory), and it buys a page that cannot change because a host you do not own changed something, and that does not report your readers to that host. Putting the version in the path also sidesteps caches you have no way to purge.Keeping your own copy of somebody else's code and serving it yourself, rather than loading it from their servers every time a visitor arrives. You have to do your own updates, but nothing on your page can change without you, and your visitors are not quietly announced to a third party.

webhook

A way for one service to instantly notify another when something happens, by sending a message to a specific web address the moment the event occurs, rather than the second service having to constantly check back and ask "anything new?"A way for one app to instantly tell another app "hey, something just happened", instead of that second app having to keep checking back over and over to see if anything's new.

WebKit

The browser engine that renders every web page on iOS, regardless of which browser app is showing it, because Apple requires it; it is also what a Capacitor app's embedded web view runs on. A CSS feature that is not yet supported in the WebKit shipped with a given iOS version simply does not work there, even if every other browser on every other platform already has it.The underlying piece of software that draws every web page on an iPhone or iPad, no matter which browser app you tapped to get there, because Apple requires all of them to use it. If a newer web feature isn't supported by the version built into a given iOS release, it just doesn't work on that device, even though it might already work everywhere else.

WebView

The built-in browser component Android provides for an app to show its own web pages inside a native shell, rather than opening a separate browser window. Unlike iOS, where every app renders through the same engine version, an Android phone keeps whatever WebView version it shipped with, sometimes for years, so a web build has to work on versions far behind the current release rather than the newest one available.The built-in piece of software an Android phone uses to show web pages inside an app, instead of opening a separate browser. Unlike an iPhone, where every app uses the same up-to-date version, an Android phone can be stuck for years on whatever version it shipped with, so an app's web pages have to work on old versions too, not just the newest one.

AI & Automation

Architect

The role that takes a capability and files it as a dependency graph of ordinary tickets, each small enough for one session, with blocks edges drawn so auto-chaining can walk the tree. It is the only role whose deliverable is other tickets rather than code, which is why it is also the one role permitted to write to Linear directly.The planner: the part of the system whose job is to turn one request that is far too big into a numbered list of smaller jobs, in an order, so each one can start itself once the job before it is finished.

Auditor

The role that audits a finished milestone once against live behavior, rather than building anything itself, and reports a pass, a fail, or insufficient-data verdict.The checker: the part of the system that builds nothing itself and tries a whole finished batch of related tasks once, for real, without trusting the builder's word. It passes the batch, sends just the broken pieces back to the builder, or says it couldn't tell. It is a different job from the UX auditor, which checks what players will see.

auto-chaining

Finishing one ticket and immediately picking up whatever that ticket was blocking, with nobody handing the next one over in between. Here it only advances through work that actually succeeded, and it travels as far from the person who started it as the dependency graph reaches.Finishing one job and automatically starting whatever was waiting on it, so a run of dependent tasks moves along without someone passing each one over by hand.

blind playtest persona

One of several separate AI sessions set up to play through a build of a game as a specific kind of player (novice, quick, strategic, legend, explorer, everyday), knowing nothing about the game beyond a short written description of how that player behaves. Each drives its own browser and sees only what a real player's screen shows, so its report reflects what an actual session would run into rather than anything read from the game's own code.One of several separate AI test-players set up to play through a new version of a game, each acting like a different kind of real player (a beginner, a fast player, a careful strategist, and so on). Each one only knows what that kind of player would know and only sees what a real screen would show, so what it reports reflects an actual playthrough rather than anything it read in the game's code.

budget gate

The check that pauses every background job on this machine once Claude usage climbs too close to a spending cap. It tracks more than one overlapping window at a time (a single session, a rolling seven days) and used to judge all of them against the same halt threshold; the halt line and the resume line are now set per window, since a week running close to its cap is not the same emergency as one session almost out of budget.The safety switch that pauses all of my automated background work once Claude usage is about to hit a spending limit. It watches more than one time window at once, like a single work session and a whole week, and now treats those differently instead of pausing everything at the same warning line.

capability

A request that is really a body of work rather than one task: "give me a live board of what every agent is working on" rather than "fix the wording on the board". It is a shape the intake step now decides on the way in, and a capability is routed to the Architect to be broken up. The alternative is what happened before: every sentence became exactly one ticket, however large the sentence was.A request that is really a body of work rather than one task: "give me a live board of what every agent is working on" rather than "fix the wording on the board". It is a shape the intake step now decides on the way in, and a capability is routed to the Architect to be broken up. The alternative is what happened before: every sentence became exactly one ticket, however large the sentence was.

circuit breaker

A counter that refuses to start any more work once a job has run too many times in too short a window, on the assumption that a normal workload does not look like that. It exists for the failure where each individual run succeeds and the loop between them is the bug, a condition every per-run check reports as healthy. Scoped narrowly, so one wedged input cannot stop everything else.A limit that stops something running again once it has already run several times in the last hour, on the grounds that normal work does not look like that. It catches the case where every individual run looks fine and the problem is that they keep happening.

classifier

The step that turns a free-form request into filed, structured fields: which team, which project, what title, who it goes to. Here it's a Claude call with a fixed response schema, so a spoken or typed sentence comes out the other side as a real ticket rather than a note someone has to sort by hand.The bit that reads a request written in ordinary words and decides where it belongs (which project, what to call it, who should do it), so it arrives as a properly filed ticket.

claude -p

The command that runs Claude Code non-interactively, as a single one-shot task rather than a back-and-forth chat session. It is what this project uses to spin up a real AI coding session in the background.The way this project runs Claude Code as a one-time background task, rather than as a live back-and-forth conversation.

Codex

OpenAI's command-line coding agent. First wired in as a second engine and soon removed, it came back as a terminal app the owner can pick when starting a live session, on a subscription login. Unattended ticket work still runs only on Claude Code, and neither vendor is a fallback for the other.A second AI coding assistant, made by OpenAI. This project tried it for a few days, took it back out, then brought it back as an option for the owner's live sessions. Work that runs with nobody watching still uses Claude.

completion comment

The write-up a background task posts back onto its own ticket when it stops: what it did, whether it worked, and now what killed it if it did not. It is the only artefact most runs leave in a place a human will actually look, which is why a sentence in it that merely sounds plausible is worse than no sentence at all.The note a background job leaves on its own ticket when it finishes or dies, saying what it did and how it went. For most jobs it is the only thing anyone ever reads, so a confident-sounding guess in it does more damage than saying nothing.

concurrency guard

A safety check that stops the same task from being started twice at once, built to stop a burst of rapid updates from accidentally dispatching duplicate work.A safeguard that stops the same task from accidentally being started twice at the same time.

content budget

A hard word or character limit on generated content, checked by the code that renders it rather than requested in the prompt that writes it. The prompt still carries the figures so a session writes to them, but what makes them true is a renderer that throws and fails the job, naming the field and the overage. The failure it exists for is drift: an adjective like "short" loses ground a little at a time, and no single day looks wrong next to the day before.A fixed limit on how long generated writing is allowed to be, enforced by the program that publishes it instead of merely asked for in the instructions. Without one, "keep it short" quietly stretches, because no single day looks much longer than the last.

depth cap

A limit on how many hops away from something a human started an automated chain may travel, distinct from fan-out, which is how wide each hop is. Auto-chaining's was five and is now unset by default: leaving it unset means no limit, a number caps the chain at that many hops, and 0 disables chaining altogether. A handoff carries its own cap of three, because it re-dispatches the same ticket and so is the one chain here that could loop.A limit on how many steps away from the thing a person actually asked for an automatic chain of work is allowed to wander before it stops and reports back.

drain mode

A pause state for the job queue: nothing new gets claimed, but nothing already queued is marked failed either. It just waits. Originally built so the queue's worker process could be restarted without losing a job mid-run; the usage gate reuses the same state instead of inventing a second kind of pause, so a job stuck behind it looks the same either way.A pause switch for the queue of background jobs: nothing new starts, but nothing waiting gets thrown away either. It just holds until the pause lifts.

evidence pack

The summarised, pre-aggregated bundle of facts handed to a model in place of the raw data, built by ordinary code before any call is made. Building it first is what makes the whole step testable without a network, lets a dry run print exactly what would be sent, and gives you something concrete to check the model's citations back against afterwards.The tidy summary of the underlying data that gets handed to the AI, worked out by ordinary code beforehand rather than by the AI itself. It means you can see exactly what it was told, and check afterwards that the examples it gave you really are in there.

failure class

One of a small fixed set of names for how a background run went wrong (ran out of time, wrong premise, too big, tests failed, machinery, the session ending itself, or unknown), stored on the run's own row so failures can be counted rather than only read. A pile of write-ups explains each failure beautifully and answers no question about the shape of them all; a class is what makes "which of these is worth fixing first" a query instead of an afternoon.A short label saying what kind of thing went wrong with a background job, chosen from a fixed handful. Individual write-ups explain one failure each; labels are what let you count them up and see which kind keeps happening.

fallback provider

An ordered chain of backup AI providers that the budget gate walks once a halt fires, instead of draining the job queue. Today it has one member: the same Anthropic subscription pinned to a model whose usage window is not the spent one, with a clean drain only when that is exhausted too. Every member is free; there is deliberately no metered vendor in the chain. The model id is swapped in right before the process spawns (same binary, same arguments). A member that is skipped is always named and never silent.A list of backup AI options that automated work falls through in order when the usual one runs low on budget, instead of pausing everything. Today there is one: a different model on the same account, at no extra cost. If it is unavailable, running low still pauses everything as usual, and it says which backup failed and why.

fan-out

How many separate pieces of work one event sets going at once. Here every ticket unblocked by a completion is picked up, however many that is. The queue underneath still runs them one at a time, so fan-out only decides what gets claimed, not what runs.How many things one finished job sets off at the same time.

handoff

An unattended session ending by naming the role the rest of the work belongs to, rather than by finishing it or returning it to a person. The ticket stays open and is re-dispatched under the new role's charter, and under that role's own Linear agent. Unlike auto-chaining it re-dispatches the same ticket, which is why it is the one thing here that can form a loop. Hence a depth cap, and a rule that the same pair of roles may only bounce a ticket once.A bot finishing its turn by passing the job on to a different bot with a different speciality, instead of either completing it or handing it back to a person. Because the job can keep moving, there are limits on how many times it may be passed on and how often two bots may pass it back and forth.

job queue

A single ordered list every dispatched job has to pass through, so only one runs at a time no matter how many things asked for one at once. Here it exists because two jobs launched seconds apart could each start editing, committing and pushing the same working copy of the code underneath each other.A waiting line for work, so only one job runs at a time. Without it, two jobs starting at once can end up editing the same files and tripping over each other.

lane

A named class of queued work, recorded on the job alongside the working tree it needs, so a limit can be set for that class rather than for the queue as a whole: three background sessions at once, say, but only ever one that publishes. The label is worth writing down before any limit uses it, because a job that ran under no lane cannot be told apart afterwards from one that ran under the wrong one.A label saying what kind of work a queued job is, so I can say "at most one of these at a time" about a particular kind rather than about everything at once.

Operations sweep

A scheduled job that looks over this machine and files a ticket when it finds a genuine fault, making it the only source of work here that does not begin with a person. It runs no checks of its own (the evidence is the existing health command's output), because a second implementation of "is this machine healthy" drifts from the first, and the copy that drifts is the unattended one nobody reads. A failure files a ticket; a warning does not, since a handful of long-lived warnings would fill the backlog on day one and teach the reader that a sweep ticket means nothing.A check that runs on a timer, looks the machine over, and writes down a job when something is actually broken. It is the only thing here that starts work without a human asking, and it deliberately stays quiet about the small long-standing complaints, because an alarm that goes off every week is one you learn to ignore.

Orchestrator

The agent an interactive session starts as here, on Claude Code or on Codex, which loads the same charter through an adapter. It keeps the conversation with the owner free by answering small questions itself and running anything bigger in a background agent briefed from scratch, then merges what those agents commit one branch at a time. It routes work by type: concepts to the Designer, words to the Copywriter, visible changes to the UX auditor.The helper the owner talks to in a live session, on either AI tool. It answers small things itself and hands bigger jobs to helpers working in the background, so the conversation is never stuck waiting, and it passes design, writing and screen checks to the helpers built for each.

publisher

A script that regenerates one part of this site from its source of truth and then commits the result itself. The blog publisher owns the post pages, the projects publisher owns the project pages. Each one is given a fixed list of paths it may stage, so two of them running near each other cannot claim the same file. The list is what keeps them apart, and it is also the thing that goes wrong: a publisher rewrites every path it owns whether or not that path changed, so a fix made to one of those files while a run is in flight is simply overwritten.A small program that rebuilds one section of this site and saves the result on its own, without anyone pressing publish. Each one is told exactly which pages it is allowed to touch, so two of them working at the same time do not fight over the same page, though a page edited by hand while one is mid-run can still get written over.

reaper

A job that runs on a timer purely to clean up after work that died without saying so. It looks for tasks still marked as running long after whatever was doing them stopped existing, and marks them failed so nothing waits on them forever.A small routine that runs every few minutes looking for jobs that quietly died halfway through, and writes them off so nothing sits waiting on them forever.

reconcile sweep

A periodic job that re-reads the authoritative source and corrects a local copy of it, rather than waiting to be told what changed. It exists because a mirror fed only by notifications fails silently: a delivery that never arrives leaves stale data looking exactly like current data. Every correction it makes is evidence that a notification went missing, so the count of corrections is worth showing rather than swallowing.A job that every few minutes goes and re-checks the real thing, instead of trusting the updates it was sent. It is there because a copy that has missed an update looks confidently correct rather than obviously broken, and every fix it makes is proof that an update went astray.

registered degradation

A problem that failed quietly on its own is deliberately made loud: it prints to the log, is written to a permanent event record, and flips a health check from healthy to unhealthy until the cause is fixed and the process restarts. It exists for failures a routine check would otherwise never surface on its own.A way of forcing a problem that would otherwise fail silently to announce itself: it gets logged, written to a permanent record, and makes a status check report unhealthy until it's fixed and the thing restarts. It exists for problems that wouldn't otherwise get noticed.

Release

The role that used to merge an approved ticket's branch in as a separate hop after the Auditor passed it. Merging already happens automatically on any "done" outcome regardless of role, so the role is now reachable by name but no longer a default pipeline target.The part of the system that used to fold an approved piece of work into the main project as its own separate step, after a reviewer had already approved it.

restart lock

The arrangement where a job that needs the always-on server restarted records a request rather than killing anything, and the server exits itself once no other job is in flight. It replaces killing whatever process holds the port, which stops being unambiguous the moment two jobs can run at once, because that process is also the supervisor of everything else running. The request surviving as a row is the other half of the point: a restart that silently did not happen is otherwise indistinguishable from one nobody asked for.Instead of a job hunting down the always-on server and killing it, the job leaves a note asking for a restart, and the server stands down by itself once nothing else is running. The note stays on file, so a restart that never happened can be told apart from one nobody wanted.

result marker

The single machine-readable line an unattended session prints last, carrying its structured outcome: whether it finished, whether it needs a person, and what should be filed next. Everything else in the log is prose written for a human. Because it is the last line rather than the first, anything that trims the output from the wrong end silently voids the contract without either half looking wrong on its own.The one line a background job prints at the very end to say, in a form other software can read, whether it finished and whether it needs a person. It comes last, so anything that trims the job's output from the top can throw it away.

scorer

A rule that reads a finished AI session's own record, plus its tickets and the project's git history, and marks the run pass, fail or not-applicable against one specific thing it checks for, such as whether a sim ran with real evidence behind it. Results are stored per run and per rule, tagged by what kind of agent did the work, so a pattern across many runs can be counted rather than noticed one at a time.A rule that reads through a finished AI work session's own written record, plus its tickets and the project's history, and marks it pass, fail, or "doesn't apply" against one specific thing it's checking, like whether a simulation ran with real data behind it. The results are saved so a pattern across many sessions can be counted, rather than only noticed by chance.

scoring signal

One narrow, weighted reading of an account (does it ever ask a question, does it post at every hour of the day, did it go silent for months and come back), combined with the others into a score on a single axis. Each one is allowed to answer 'insufficient data' instead of a number, which matters more than it sounds: a signal that reports a confident zero from a window too small to hold the thing it is looking for quietly drags every other signal on its axis down with it.One small question asked about an account (does it ever ask anything, does it post at all hours, did it go quiet for months), with the answers added up into an overall verdict. Each question is allowed to say 'I can't tell from this' rather than guess, because a confident wrong answer counts just as heavily as a right one.

self-mutation guard

A safeguard that stops this assistant from reacting to its own automated replies as if they were new incoming requests. Without it, the assistant could get stuck responding to itself in an endless loop.A safeguard that stops this assistant from mistaking its own replies for new requests and getting stuck responding to itself forever.

SessionEnd hook

A trigger that fires whenever an AI coding session in this project finishes, used to capture work (like manual steps or system changes) that wouldn't otherwise show up as a saved code change.A trigger that fires whenever an AI coding session in this project wraps up, used to catch and save work that wouldn't otherwise get written down.

Steward

One of this project's agent roles, standing in for the owner on the tasks that used to have to wait for them: signing up for a service, reading a one-time code off a text or email, clicking through a consent screen, solving a CAPTCHA, making a call between options. It works under its own identity (its own name, a fresh throwaway email each run, its own locked-away credentials) and can pay for something itself only through a capped, merchant-locked card in the vault; anything above that cap, or an account under the owner's real identity, still goes to them.One of the automated roles in this project. It handles the small human-shaped steps that used to sit waiting for the owner (signing up for something, reading a verification code, proving it's not a robot), using its own name and its own throwaway email. It can now pay for something itself, but only up to a small monthly limit on one locked-down card; anything bigger, or anything tied to the owner's real identity, still goes to them.

Todo sweep

A check that runs over every ticket moved into Todo and decides whether it can start on its own or has to wait for a human, based on who most recently assigned it and whether its title carries a deliberate human-step marker. A ticket it holds is left alone rather than started automatically.A check that looks over every to-do ticket moved into the "ready to start" column and decides whether it can begin automatically or needs a person to look at it first, based on who assigned it most recently and whether its title is deliberately flagged as a human step.

transcript

The full turn-by-turn record an AI coding session writes to disk as it runs: every question, every file it read, every command, every dead end. It is written whether or not anything else notices, which makes it the last resort when a run left no commit and no note: the material is all there, but nothing points at it, so finding it means knowing the session existed in the first place.The full turn-by-turn record an AI coding session writes to disk as it runs: every question, every file it read, every command, every dead end. It is written whether or not anything else notices, which makes it the last resort when a run left no commit and no note: the material is all there, but nothing points at it, so finding it means knowing the session existed in the first place.

tree lock

A claim on a git working tree, taken by whatever is about to write to it and keyed on the tree resolved at that moment rather than on the partition key the job was queued under. The distinction is the whole point: a job routed to one checkout may find its files in another and commit there, so a lock on the predicted tree guards the wrong directory. A holder is judged stale by a dead pid or an expired clock, and a broken lock says whose it was and why, so waiting for a live session never reads like stealing from one.A claim an agent puts on the folder it is about to save work in, taken at the moment it writes rather than decided in advance, because an agent sent to one folder can quite reasonably end up working in another. Anyone else wanting that folder waits their turn, and if a claim has to be taken off an agent that died, that gets said out loud.

Triage

The role that decides who holds a newly filed ticket (a human, one of the agent roles, or nobody yet) and does nothing else. It exists because the alternative is every filing route answering that question for itself, which is three routes and three answers to one question. Delegating a ticket to it starts a session rather than merely labelling the ticket, so a blocked ticket is never routed to it: that would begin work its blocker was supposed to precede.The part of the system whose only job is deciding who should do a newly written-down job. Everything that files new work hands it over here first, so that decision is made in one place instead of guessed at in three.

trust level

A verdict computed before a dispatched job starts, deciding how much it is allowed to do: whether the owner personally acted on the ticket, whether it arrived through a channel like Telegram, or whether nobody has vouched for it at all. An untrusted verdict limits a job to reading and assessing; only a trusted one, or an explicit promotion, unlocks the full toolset.A judgment made before an automated job starts, deciding how much freedom to give it: did a person actually ask for this, did it come in through a messaging app, or did nobody check it at all. A job nobody vouched for is only allowed to look things over, not act on them, until someone approves it for real.

turn limit

A hard cap (--max-turns) on how many tool calls a Claude Code session may make before it is killed, regardless of whether the ticket it was working is finished. A session stopped this way used to be treated the same as any other unfinished failure; a resumed wrap-up pass now lets it commit whatever work is done before it's cut off for good.A safety limit on how many steps an AI coding session is allowed to take before it gets automatically stopped, whether or not the work is actually done.

UX auditor

The session agent that checks what players will see before it reaches them: each visible UI change measured against its design at phone and desktop widths, accessibility checked on every change, and a before and after of every changed screen, with the owner's OK needed only on new features, new screens, style changes and anything nobody asked for. For big changes it runs blind playtests, each a separate process started in an empty directory with only the URL. It is not the Auditor, which checks a finished milestone against live data.The helper that checks what players will actually see: it compares each changed screen with its design, checks it works for everyone, and makes a before and after of every changed screen, waiting for the owner's yes only on new features, new screens, style changes and anything nobody asked for. For big changes it has fresh AI testers, who know nothing but the web address, try the game. It is a different job from the Auditor, which checks that finished work functions.

vault

This project's store for credentials an agent needs but a human shouldn't have to see printed out: a login, an API key, or a payment card. A lookup command shows what is there without echoing the sensitive value itself; only one narrow, purpose-built function is allowed to read a card back in full, and only to charge it.The place this project keeps passwords, keys and payment cards that an AI agent needs to use but that shouldn't get printed out in full where anyone reading a log could see them. Checking what's stored shows you it exists without showing the actual number or password.

wave

A group of tickets an orchestrator records as built together, so release can check that each one has its own review before any of them goes out. A member's review only counts if it happened after that member's latest build, so a ticket rebuilt after the wave was recorded cannot ride out on an older review.A batch of to-do tickets an automated coordinator notes down as having been built together, so a later step can check that each one was actually reviewed before any of them ships. If a ticket gets rebuilt after that check, the batch does not let it coast on the old review.

Data & Storage

adapter

A small module that translates one particular outside source (an API, a spreadsheet, a scraped page) into the single shape the rest of the system understands, so that everything downstream can be written once instead of once per source. Its value depends entirely on the shape being enforced rather than merely documented: if each adapter is trusted to return the right thing, the differences between sources leak out of the adapters and into every consumer of the data.A small piece of code whose only job is to turn one outside source of information into the one format the rest of the app expects, so the app never has to know where a number came from. Add a new source later and you write another one of these rather than changing everything.

chat.db

The file on a Mac where the Messages app stores every iMessage and SMS conversation. CRM reads this file directly, and never modifies it, to figure out who you still owe a reply to.The file on a Mac that quietly stores every text message conversation. This project's CRM tool reads it to figure out who you still owe a reply to, and never changes anything in it.

cold cache

A lookup table that has been populated at some point in a process's life but is empty right now, most commonly straight after a restart, before anything has filled it. Code that reads a cache without being able to fill it works perfectly in testing and on any long-running process, and is wrong for exactly the first request after every deploy, which is why a cold cache is worth naming as its own state rather than treating an empty answer as a real one.A list a program keeps handy so it doesn't have to look things up twice, and which is empty every time the program has just restarted. Code that only reads that list, and can't go and look anything up itself, gives the wrong answer for the first few requests after every restart and the right one forever after, which makes the bug very easy to miss.

effective-dated

A record that is changed by closing the old row and writing a new one with a start date, rather than by editing the value in place. It costs an extra row and buys the ability to ask what the value was on a given day. That matters wherever a past judgement was made against the old number, since editing in place lets raising a spending cap retroactively turn a month that was blown into one that was met.Instead of editing a number when it changes, you mark the old one as finished on a date and write a new one starting there. That way you can still ask what it was last month, so raising a limit today cannot quietly rewrite whether you stayed under the old one.

Postgres

A full database server, run as its own process rather than living in a single file the way SQLite does, built to hold data that keeps growing and to be read and written by more than one program or container at once.A more heavyweight way of storing organized data than a single file. It runs as its own program, built for data that keeps growing and needs to be read and written by several things at once.

provenance

The record, carried on the row itself, of which source a piece of data came from, so a total can say what it is made of, and a wrong figure can be traced to the thing that produced it. It is worth stamping centrally rather than letting each source label its own rows: a self-labelled row is correct right up until that source is copied to serve a second institution and the label is copied with it.A note attached to every piece of data saying where it came from, so a total can explain what it is made of and a wrong number can be traced back to whatever produced it.

read-only role

A login a database itself restricts to looking things up, rather than trusting whoever connects to behave. Unlike a setting a script turns on for itself, the restriction lives on the account, so a script that tries to write anyway is refused by the database, not merely discouraged.A login that a database itself only allows to look things up, no matter what the program using it tries to do. Because the restriction sits on the login rather than being a setting a program could forget to switch on, trying to write anything with it simply fails.

ROWID

SQLite's built-in row number, handed out in the order rows were inserted into a table. It is tempting to treat it as a stand-in for "newest first" because usually it is, and it sorts far faster than a decoded timestamp. But insertion order only matches chronological order if the rows arrived chronologically. A bulk re-import files old records last, giving them the highest ROWIDs, and every query that ordered by ROWID to mean "recent" then quietly reads the oldest data first.The order in which records were added to a database, which the computer numbers automatically. It is tempting to use it as a shortcut for "most recent first", and usually that works, until a big batch of old records gets imported all at once, which files them at the end and makes the oldest data look like the newest.

SQLite

A lightweight database that lives in a single file on disk, with no separate server process to run or manage. It is a common choice for a small project that needs to remember things between restarts without the overhead of a full database system.A simple way to store organized data in a single file on a computer, without needing to set up and run a separate database program.

write-once

A field that may be filled in once and never changed after. It exists for the case where several parts of a system will each try to fill the same blank at different moments, and only some of them are in a position to have a good answer. It is enforced in the database rather than by checking first and then writing, so a later caller with nothing to say cannot erase what an earlier one recorded, and the first writer wins even against a second process.A slot that can be filled in once and never changed. Useful when several parts of a system will each have a go at filling it at different times and some of them will come up empty: whoever answers first is kept, and a later blank answer cannot wipe it out.