Config: docs/runbooks/runbooks.config.json

setup writes this file from ${RUNBOOKS_PLUGIN_ROOT}/templates/runbooks.config.json. runbooks.mjs fills missing keys with the defaults below.

Tests

One key per surface the stack allows, tests.ui and tests.api. A key for a surface the stack does not allow is a config error.

"stack": "fullstack",
"tests": {
  "ui":  { "tech": "next", "framework": "playwright", "dir": "e2e",
           "command": "PLAYWRIGHT_JUNIT_OUTPUT_NAME={junit} npx playwright test {files} --reporter=junit" },
  "api": { "tech": "laravel", "framework": "phpunit", "dir": "tests/Feature/Runbooks", "root": "apps/api",
           "command": "php artisan test {files} --log-junit {junit}" }
}

JUnit flags by framework: Jest --reporters=default --reporters=jest-junit with JEST_JUNIT_OUTPUT_FILE={junit} (needs jest-junit), Vitest --reporter=junit --outputFile={junit}, PHPUnit and Pest --log-junit {junit}, Playwright --reporter=junit with PLAYWRIGHT_JUNIT_OUTPUT_NAME={junit}, Cypress --reporter junit --reporter-options mochaFile={junit}.

Endpoint sources: the next-app-router extractor marks route handlers api-endpoint. A regex source for endpoints (routes/api.php, Nest controllers) sets "kind": "api-endpoint", so coverage can tell endpoints from screens.

Roles

roles.enabled is the switch. With it true, the project keeps a registry of its roles at <paths.runbooks>/roles.json, committed by the runbooks commit policy, with the runbook edits, while config changes stay in the setup commit. With it false or missing, roles: [admin] in a runbook keeps its meaning (the account roles the steps log in as), roles: all and review are problems, and no command or script reads the registry. The runbook side of roles: format.md, "Roles".

{
  "version": 1,
  "actions": ["approve", "export"],
  "roles": {
    "anonymous": { "description": "No session", "permissions": {} },
    "editor": {
      "description": "Edits invoices and clients",
      "found": ["src/auth/roles.ts:12", "contract: scope invoices:write"],
      "permissions": { "billing/invoices": ["view", "create", "edit"], "billing/clients": ["view", "create", "edit"] },
      "origins": { "billing/clients": "guess" }
    },
    "manager": {
      "description": "Billing manager",
      "inherits": ["editor"],
      "found": ["user"],
      "permissions": { "billing/invoices": ["view", "create", "edit", "approve"] }
    }
  }
}

Base actions are view, create, edit and delete. They are fixed and need no entry in actions. An action in a role's permissions that is not in the action list is an error.

Keys. A matrix key is <capability>/<feature> or <capability>/*, with the same names as runbook frontmatter. A key that matches no runbook's capability/feature and no slice gives a warning, to catch typos.

Lookup. For a runbook, the role's entry for <capability>/<feature> wins over <capability>/*. A runbook with no feature uses <capability>/*. No entry means no access. On a key of a context, the lookup also takes the case ("Contexts" below).

Inheritance and override. Roles can be independent or cumulative. The effective matrix of a role is the union of its parents' effective entries, plus its own. An own entry for a key replaces the inherited entry for that same key, so a manager can lose delete that its parent has. When two parents give the same key, their actions are joined. A cycle in inherits is an error.

Contexts. A context is a question about the record that changes what a role may do on some keys: how the user relates to the client a record belongs to, for example. A case is one answer to it. The same manager login can edit one client and only view another. One list of actions per key cannot express that, and a context can. /runbooks:contexts:create, /runbooks:contexts:update and /runbooks:contexts:delete create, edit and delete contexts.

{
  "version": 2,
  "actions": [],
  "contexts": {
    "client-access": {
      "description": "How the user relates to the client the record belongs to",
      "keys": ["clients/*", "billing/invoices"],
      "cases": {
        "vip-team": "VIP client, the user is on its team",
        "vip-outside": "VIP client, the user is not on its team",
        "regular": "client that is not VIP"
      }
    }
  },
  "roles": {
    "viewer": { "permissions": { "clients/*": ["view"] } },
    "manager": {
      "permissions": {
        "clients/*": {
          "vip-team": ["view", "create", "edit", "delete"],
          "vip-outside": ["view"],
          "regular": ["view", "create", "edit"]
        }
      }
    }
  }
}

• A file with contexts has "version": 2. The loader reads versions 1 and 2, and a file at version: 1 with contexts is an error. A file with no contexts can stay at version 1.
• A matrix key belongs to a context when the context lists it, or when the key is <capability>/<feature> and the context lists <capability>/*. A key that belongs to two contexts is an error.
• On a key of a context, a role's entry is either a list, which gives the same actions in every case, or a map from case to list. A case the map leaves out is no access in that case. A map on a key of no context, or with a case its context does not have, is an error.
• Inheritance works per case. A parent's list counts as the same list in every case, and two parents join their actions case by case. An own entry still replaces the inherited entry for the whole key and all its cases, so an own map that leaves out a case takes that case away. runbooks.mjs roles <name> prints the effective matrix with one row per key and case.
• origins stays per key, also on a key of a context.
• A runbook whose capability/feature matches a key of a context runs once per case, and its text states what each role gets in each case (format.md, "Contexts and cases").

found and origins. found is per role and origins is per key. A key the user typed has no origins entry. /runbooks:permissions:manage removes a key's entry when the user edits that key, and /runbooks:roles:generate gives each key it adds or changes the proposal's origin: guess for a key it deduced, none for a key the source states. roles listings and /runbooks:ui flag the keys still marked guess. An origins key that is not in permissions is an error.

anonymous. It is always present, even when the file omits it. It cannot be deleted, renamed or given an account, and it inherits nothing.

Relation to accounts. accounts.<role> holds the login of a role, as env var names. Every key of accounts must be a registered role, and accounts.anonymous is an error. A registered role without an accounts entry is valid: a ui run gives it no-account. The registry never holds a credential value.

Generating from a document. /runbooks:roles:generate reads a document in any format, writes a proposal as JSON and merges it with runbooks.mjs merge-roles. The merge adds roles, contexts, cases, project actions and keys, and replaces the own entry of each key the proposal gives. A role, context or key the proposal leaves out stays as it is, and a key goes away only through the proposal's remove list. It never changes the parents of a registered role and never deletes a role, a context or a case: those stay with their own commands.

Permission history comes from git log of roles.json. The plugin writes no history of its own.

Errors the loader raises, each prefixed with the file path:

• unsupported version <n>, expected 1 or 2
• contexts need version 2
• role "<name>" must be kebab-case
• <role> inherits "<parent>", which is not a registered role
• anonymous inherits nothing
• inheritance cycle: a -> b -> a
• <role>: key "<key>" must be <capability>/<feature> or <capability>/*
• <role> "<key>": action "<action>" is not in actions, and <role> "<key>" in <case>: action "<action>" is not in actions inside a map
• context "<name>" must be kebab-case
• context "<name>": keys must be a list of matrix keys
• context "<name>": key "<key>" must be <capability>/<feature> or <capability>/*
• context "<name>": cases must map each case to a description
• case "<name>" must be kebab-case
• case "<name>" appears in contexts <a> and <b>
• key "<key>" belongs to contexts <a> and <b>
• <role> "<key>": a map of cases needs a key that belongs to a context
• <role> "<key>": case "<case>" is not a case of <context>
• accounts.<role> is not a registered role
• accounts.anonymous is not allowed, because anonymous has no session

Warnings, which leave the registry usable:

• roles.json: <role> "<key>" matches no runbook or slice
• roles.json: context <name> key "<key>" matches no runbook or slice
• roles.json: context <name> has fewer than two cases

Viewports

Each name is a screen size that ui runbooks run at. create adds one when the user picks a size the config lacks; setup keeps the existing ones. Names are kebab-case; width and height are positive integers.

"viewports": {
  "desktop": { "width": 1440, "height": 900 },
  "tablet":  { "width": 768,  "height": 1024 },
  "mobile":  { "width": 390,  "height": 844 }
}

Put each width inside one range of the project's breakpoints, so the page gets the layout of that range. The project declares its breakpoints in one of these places:

• Tailwind v4: --breakpoint-* in @theme. Defaults: sm 640, md 768, lg 1024, xl 1280, 2xl 1536.
• Tailwind v3: theme.screens in tailwind.config.*, with the same defaults.
• Bootstrap: $grid-breakpoints. Defaults: 576, 768, 992, 1200, 1400.
• MUI: theme.breakpoints.values. Defaults: 600, 900, 1200, 1536.
• Plain CSS and JS: @media rules with min-width or max-width, and matchMedia or useMediaQuery calls.

The sizes in the example fit the Tailwind defaults: 390 is below sm, 768 is where md starts, and 1440 falls between xl and 2xl.

Design

setup writes it when the user names a design reference. create and update link a runbook's screens to it (format.md, the design key), and run compares each linked step with its design.

"design": { "system": "figma", "mcp": "figma", "url": "https://www.figma.com/design/AbC123/Billing" }

How each system is read, and what a runbook cites:

The Figma servers setup offers live in ${RUNBOOKS_PLUGIN_ROOT}/templates/design-servers.json, and each one is merged under the name figma into the active host's MCP configuration (see runtime.md for JSON-to-TOML translation):

Upstream

setup writes it when the stack has ui and the upstream API is not served by the app's own process. A config without it behaves as live. The block is a config error in a backend stack. The modes, the server and the fixtures: ${RUNBOOKS_PLUGIN_ROOT}/skills/runbooks/references/upstream.md.

"upstream": {
  "mode": "mocked",
  "baseUrl": "https://api.example.com/v1",
  "urlEnv": "NEXT_PUBLIC_API_URL",
  "schema": "docs/openapi.json"
}

Errors the loader raises:

• upstream must be an object with a "mode"
• upstream applies only to ui runbooks, and a <stack> stack has none
• upstream.mode must be one of live, mocked
• upstream.urlEnv is required when upstream.mode is mocked
• upstream.port must be an integer from 1 to 65535
• upstream.schema must be a JSON file (a local OpenAPI 3 .json path)
• upstream.redactHeaders must be a list of header names
• upstream.redactBodyKeys must be a list of key names

Models

On Claude Code, the optional models block sets which model runs each command. It maps a row key to one of inline, haiku, sonnet, opus or fable. inline runs the command in the main session, with no sub-agent. Any other value launches the command's sub-agents on that model. The five values run from least to most capable in that order. A config without models uses the default table below, and a project's rows replace the default rows with the same key.

A key is a command name followed by options and <placeholder> positionals, as in run --mode test or help <question>. A row matches an invocation when the command is the same, every option in the key is given (an option with a value must have that value), and a placeholder has a positional argument to match. When several rows match, the row with the most options and placeholders wins. On a tie, the more capable model wins. An invocation that no row matches runs inline. --model <value> on the command line overrides every row.

A value outside the five is a config error: models["<key>"] must be one of inline, haiku, sonnet, opus, fable. models itself must be an object or null, or the loader raises models must be an object of "<command> [parameters]": model.

A key that is not a command with options and placeholders, an empty key, or a key whose command does not exist is not an error. The loader warns models["<key>"]: <reason>; the row is ignored and leaves the row out.

setup writes the table into a project that has no models key. /runbooks:settings models changes it.

Codex models

Codex uses a separate optional codex.models object with the same row keys. Its compatibility defaults keep every inline row above and replace every delegated Claude alias with inherit, which delegates using the current session model. Legacy projects need no migration to be read on Codex; absent Codex rows receive those defaults. The helper does not write the configuration while reading it. Setup discovers locally available models and persists explicit task-appropriate IDs instead of blindly copying these fallback defaults; see runtime.md, "Codex setup model selection". Re-running setup also reviews legacy inheritance rows.

{
  "models": { "create": "opus" },
  "codex": { "models": { "create": "inherit", "coverage": "inline" } }
}

inline executes in the main session. inherit delegates with no model override. An explicit model ID must be supported by the active Codex session. The helper validates a nonempty ID of up to 200 characters: letters/digits first, then letters/digits, ., _, :, / or -, with no .. sequence. Claude aliases are rejected. Runtime availability is checked at dispatch, not guessed by the helper. A forced unavailable model stops; see agents.md for fallback behavior.

The most specific matching row wins as on Claude. Equally specific Codex rows keep the first matching row in the effective table (defaults followed by new project rows; replacing an existing row does not move it). No capability ranking is inferred from OpenAI model names. --model overrides row selection and passes through internal calls. setup and settings models edit only the active host's block, preserving the other one.

Use runbooks.mjs model <command> <args> --runtime codex --json and runbooks.mjs models --runtime codex [--defaults|--diff] --json. Omit the runtime only for legacy Claude behavior. An unknown runtime is an error. Invalid Codex row keys are ignored with warnings under codex.models, as for Claude rows.

Sources

Each entries or requirements item is one source. Every source accepts root, a folder of the project relative to its root (for a monorepo: "apps/api"). Ids from a rooted source keep the root in their file (apps/api/src/app/...), and slices globs match that same path. An API in another repository is never a source: CI checks out this repository alone, so the source would never run there (${RUNBOOKS_PLUGIN_ROOT}/docs/adr/0005-upstream-api-in-another-repo-is-a-contract.md).

Globs support * (inside one folder) and ** (any depth). [, ], (, ) are literal characters.

A source whose root does not exist is skipped with a warning; the others still count.

Warnings the loader prints for paths outside the project (from runbooks 2.0 the first three are config errors):

• entries[<n>]: root "<root>" is outside the project, so its CI never reads it (docs/adr/0005). /runbooks:settings sources moves its ids to calls. ...
• slices.<name>: glob "<glob>" is outside the project and never matches a change (docs/adr/0005). ...
• tests.api.root "<root>" is outside the project (docs/adr/0005). .... A tests.ui.root outside the project does not warn (docs/adr/0007).
• upstream.root is no longer read (docs/adr/0005); /runbooks:settings upstream removes it