Lint two OpenAPI specs for breaking changes and policy violations.

When to use: as the primary CI gate before merging API spec changes — combines diff + policy into a pass/fail verdict. When NOT to use: for raw change data (use delimit_diff) or quality scoring (delimit_spec_health).

Sibling contrast: delimit_diff returns changes only; delimit_diff_report renders HTML; this enforces policy.

Side effects: writes evidence on breaking findings; auto-chains semver classification and governance evaluation. dry_run=True suppresses evidence, notifications, and governance — returns violations + semver only.

Spec args accept local paths or http(s) URLs. URLs are fetched once into a tempfile (size cap, SSRF guard).

Diff two OpenAPI specs and list all changes (pure diff, no policy).

When to use: when you only need the structural change set (added / removed / modified endpoints, schemas, parameters) without any policy verdict. When NOT to use: as a CI gate — for pass/fail use delimit_lint, for a shareable HTML report use delimit_diff_report.

Sibling contrast: delimit_lint adds policy + governance; this is the underlying change list. delimit_diff_report wraps both in a presentable report.

Side effects: read-only. Calls backends.gateway_core.run_diff.

Generate a shareable API diff report with full analysis.

When to use: when a team needs a shareable artifact (API review, PR comment, compliance record) — runs diff + policy + semver + spec health + migration guide. When NOT to use: for a CI gate verdict (use delimit_lint) or raw diff data (delimit_diff).

Sibling contrast: delimit_lint enforces; delimit_diff is raw; this is the presentable composite report.

Side effects: read-only on inputs. When output_file is provided, writes the rendered HTML/JSON to disk. The HTML has inline CSS — no external dependencies, opens in any browser.

Score an OpenAPI spec on quality dimensions (0-100, A-F grade).

When to use: for quick spec quality checks during onboarding or review — completeness, security, consistency, documentation, best practices. When NOT to use: as a breaking-change gate (use delimit_lint) or raw diff (delimit_diff).

Sibling contrast: delimit_lint compares two specs; this scores one spec on its own merits.

Side effects: read-only. Calls backends.gateway_core.run_spec_health. Works on any valid OpenAPI 3.x or Swagger 2.0 spec.

Inspect or simulate governance policy configuration.

When to use: to inspect the active policy or dry-run lint+policy against several presets to preview what would block. When NOT to use: for an actual gate decision (use delimit_lint) or to manage the policy file itself (delimit_gov_policy).

Sibling contrast: delimit_gov_policy reads the live policy; delimit_lint enforces; this lets you simulate / inspect.

Side effects: read-only on policy + spec files. action="simulate" runs lint internally without writing evidence.

Query the append-only contract ledger (hash-chained JSONL).

When to use: to read or audit the cryptographically-chained contract ledger that records signed governance events. When NOT to use: for the project work ledger (use delimit_ledger_list / delimit_ledger_query) — the contract ledger is a different, hash-chained store.

Sibling contrast: delimit_ledger_list reads work items; delimit_audit reads audit logs; this reads the hash-chained contract ledger and can verify integrity.

Side effects: read-only. Calls backends.gateway_core.query_ledger.

Analyze downstream impact of an API change (informational only).

When to use: when assessing blast radius for a planned API change, by inspecting a dependency manifest for callers of the named API. When NOT to use: to make a gate decision (use delimit_lint or delimit_gov_evaluate for pass/fail) — this returns information.

Sibling contrast: delimit_lint returns pass/fail; this returns a blast-radius report.

Side effects: read-only. Calls backends.gateway_core.run_impact.

Classify a spec change's semver bump (MAJOR/MINOR/PATCH/NONE).

When to use: to deterministically pick the version bump for an API spec change, optionally computing the next version string. When NOT to use: for full lint with policy (use delimit_lint) or a plain change list (delimit_diff).

Sibling contrast: delimit_diff lists changes; delimit_lint adds policy; this maps the diff to a semver verdict only.

Side effects: read-only. Calls backends.gateway_core.run_semver (deterministic classification on top of the diff engine output).

Render a human-readable explanation of API changes (7 templates).

When to use: to produce migration notes, PR comments, changelog entries, or Slack-friendly summaries from a spec diff. When NOT to use: for raw change data (use delimit_diff) or a shareable HTML report (delimit_diff_report).

Sibling contrast: delimit_diff returns structured change data; delimit_diff_report renders an HTML report; this renders a template-driven text explanation.

Side effects: read-only. Calls backends.gateway_core.run_explain.

Extract OpenAPI spec from framework source code (no spec file needed).

When to use: when a project has no checked-in OpenAPI spec but uses a framework Delimit can introspect (FastAPI today; Express, NestJS planned). When NOT to use: when a spec file already exists — pass it directly to delimit_lint or delimit_diff.

Sibling contrast: delimit_lint operates on existing spec files; this generates one from source.

Side effects: read-only on the project source. Calls backends.gateway_core.run_zero_spec which may invoke a Python subprocess to introspect FastAPI routes.

Initialize Delimit governance scaffolding for a project.

When to use: once per project, the first time you adopt Delimit — creates .delimit/policies.yml, ledger directory, and (optionally) a project .claude/settings.json with a reasonable allowlist. When NOT to use: to load an existing config (use delimit_project_config action="load") or to discover Delimit's capabilities for a project (delimit_scan).

Sibling contrast: delimit_project_config manages the config after init; delimit_scan inspects what could be governed; this is the one-time initializer.

Side effects: creates .delimit/policies.yml + ledger dir; chmod 755 on .delimit/, chmod 600 on .delimit/secrets/*; writes a project .claude/settings.json with an Edit/Write/Bash allowlist if missing. Pass no_permissions=True to skip the permission step.

Mint an OS-level execution plan against a target component (Pro).

When to use: to draft a structured plan (deploy, migrate, rotation, rollback) that the governance kernel can later inspect via delimit_os_gates and human reviewers can approve before any side-effecting execution. The pattern is plan -> approval check via gates -> separate execution call. When NOT to use: for aggregate OS counts (delimit_os_status), to check gate state on an existing plan (delimit_os_gates), or to actually execute a deploy (delimit_deploy_* / delimit_deploy_build). Also do not use this as an audit-trail surrogate for free-form work; that is delimit_ledger_add territory.

Sibling contrast: delimit_os_gates checks gates on an existing plan; delimit_os_status reports portfolio-wide counts; this is the only OS surface that mints a new plan. Compared to delimit_gov_new_task (governance-classed task), this records an OS-level operation (deploy/migrate/rotation) rather than a policy-scoped task.

Side effects: gated by require_premium — unlicensed callers receive a license payload and no plan is created. On a licensed call, parameters is first coerced (string -> dict via _coerce_dict_arg); a malformed payload short-circuits with an error response. On success, invokes backends.os_bridge.create_plan which writes a new plan record to the OS plan store keyed by a generated plan_id. Result is wrapped via _with_next_steps. No deploy is executed by this call.

Report Delimit OS overall status (plans, tasks, tokens) (Pro).

When to use: at session start or in a status dashboard, to read aggregate OS-level counts and active plan IDs. When NOT to use: for governance health (use delimit_gov_health) or per-plan gates (use delimit_os_gates).

Sibling contrast: delimit_gov_health reports governance engine; delimit_os_gates reports a specific plan's gate state; this reports overall OS counts.

Side effects: read-only on the OS backend; gated by require_premium. Calls backends.os_bridge.get_status.

Args: None.

Returns: Dict with plan/task/token counts and next_steps.

Check governance gates for an OS plan (Pro).

When to use: to check whether a specific plan is currently blocked by a governance gate before proceeding. When NOT to use: for general OS counts (use delimit_os_status) or governance engine health (delimit_gov_health).

Sibling contrast: delimit_os_status returns aggregate counts; delimit_gov_health reports the engine; this returns gate state for one plan.

Side effects: read-only on the OS backend; gated by require_premium. Calls backends.os_bridge.check_gates.

Unified governance entry point — dispatches to one of seven actions.

When to use: as the single MCP-registered governance surface (delimit_gov) when the caller wants to pick the action by name in one call rather than choosing a specific delimit_gov_* alias. When NOT to use: from internal code paths — prefer the specific alias (delimit_gov_health, delimit_gov_evaluate, etc.) for clarity and so docstrings and license gates show up at the right call site.

Sibling contrast: each delimit_gov_ wrapper above is a thin alias over this implementation; they exist so the action's docstring lives at the right name. This is the dispatch core.

Side effects: action="health" / "status" are read-only and not gated. action="policy" / "evaluate" / "new_task" / "run" / "verify" are gated by require_premium — unlicensed callers receive a license payload and no backend call is made. Each gated action routes to a distinct backends.governance_bridge function (health, status, policy, evaluate_trigger, new_task, run_task, verify) and the result is wrapped via _with_next_steps for orchestrator hints. Errors are deterministic ({"error": ...}); inputs that cannot be coerced (e.g. malformed context for evaluate) short-circuit before the backend call.

Report whether the governance kernel and policy are reachable.

When to use: at session start as part of the standard orchestrator ritual (delimit_revive + delimit_ledger_context + this + inbox daemon), or as a CI smoke check before a gated deploy. Confirms the governance backend is reachable and the policy kernel is loaded so downstream gates will fail-closed correctly rather than silently no-op. When NOT to use: to evaluate whether a specific candidate action requires gating (use delimit_gov_evaluate), to read the rules themselves (delimit_gov_policy), or to check per-repo task state (delimit_gov_status).

Sibling contrast: delimit_gov_status reports per-repo workload (open tasks, recent decisions); this reports the engine layer itself (kernel boot status, policy load, backend integration). If a deploy gate is failing, run this first to rule out "engine down" before debugging policy logic.

Side effects: read-only and not license-gated. Invokes backends.governance_bridge.health and wraps the response through _with_next_steps. No ledger write, no notification, no evidence file. Safe to call on every session start without rate concern.

Report governance state (open tasks, decisions) for a repo.

When to use: when you need a snapshot of governance activity for a given repo — what tasks are open, what was recently decided. When NOT to use: for engine-level health (use delimit_gov_health) or to evaluate a new action (use delimit_gov_evaluate).

Sibling contrast: delimit_gov_health reports the engine; this reports the workload (per-repo task and decision state).

Side effects: read-only. Calls backends.governance_bridge.status.

Read the active governance policy for a repository (Pro).

When to use: when an agent or operator needs to inspect the live policy rules being enforced for a repo (risk thresholds, gates). When NOT to use: to mutate policy — this tool is read-only.

Sibling contrast: delimit_gov_evaluate runs an action against the policy; this returns the policy itself.

Side effects: read-only on policy storage; gated by require_premium (returns a license payload if the caller is unlicensed).

Evaluate whether a proposed action triggers governance gating (Pro).

When to use: BEFORE performing any action whose policy class is uncertain — deploy, external PR submission, schema change, npm publish, force-push, force-update of a floating tag, account switch, ruleset edit. This is the canonical pre-action check the orchestrator and CI hooks call; the response is the gate verdict. When NOT to use: to read the policy rules themselves (use delimit_gov_policy), to materialize a tracked task from a "gating required" verdict (delimit_gov_new_task), or to check engine health (delimit_gov_health). Also: do not call after starting the action — the verdict is decision-time and a retroactive call has no gating effect.

Sibling contrast: delimit_gov_policy returns the rules; this evaluates a candidate action against them. delimit_external_pr_check handles the specialised external-PR duplicate path; this is the general action evaluator. delimit_gov_new_task is what you call AFTER this returns "gating required" to mint a tracked task.

Side effects: read-only on policy storage and gated by require_premium — unlicensed callers receive a license payload and no evaluation runs. On a licensed call, invokes backends.governance_bridge.evaluate_trigger which loads the active policy and returns a verdict; no task is created, no ledger write, no evidence file. Inputs are coerced before the backend call: a string context is wrapped as {"text": ...} via _coerce_dict_arg; a malformed context short-circuits with an error response.

Create a governance-classed task with risk tier and scope (Pro).

When to use: immediately after delimit_gov_evaluate returns a "gating required" verdict and you need a tracked, audit-bearing record before performing the gated work. The three-step pipeline is delimit_gov_new_task -> delimit_gov_run -> delimit_gov_verify; this is step one. When NOT to use: for free-form work tracking (use delimit_ledger_add), to perform the work itself (delimit_gov_run), or to verify a completed task (delimit_gov_verify).

Sibling contrast: delimit_ledger_add tracks general work items with no policy gating; this creates a governance-classed task with a risk tier and scope record that the run/verify steps operate on. delimit_gov_evaluate returns a verdict only; this materializes that verdict into a tracked task.

Side effects: gated by require_premium — unlicensed callers receive a license payload, no task created. On a licensed call, invokes backends.governance_bridge.new_task which writes a new task record keyed by a generated task_id into the governance task store; the record carries title, scope, risk_level, repo path, and creation timestamp. The response is routed through _with_next_steps so the returned dict carries orchestrator hints.

Execute a previously created governance task under policy (Pro).

When to use: as step two of the three-step governance pipeline, after delimit_gov_new_task has minted a task_id and before delimit_gov_verify closes it out. Call when you are ready to perform the gated work and want the policy engine to record the execution. When NOT to use: to evaluate a candidate action (use delimit_gov_evaluate), to mint a task (delimit_gov_new_task), or to attest a completed task (delimit_gov_verify).

Sibling contrast: delimit_gov_new_task creates the task record but does no work; this records the execution against an existing task_id; delimit_gov_verify attests the run output afterwards. The full pipeline is new_task -> run -> verify.

Side effects: gated by require_premium — unlicensed callers receive a license payload, no execution recorded. On a licensed call, invokes backends.governance_bridge.run_task which appends a run record to the task identified by task_id (status transition, timestamp, repo). The response is routed through _with_next_steps so the returned dict carries orchestrator hints. Note this tool records the run event; it does NOT itself perform the underlying work — the caller is expected to do that.

Attest that a governance task completed under policy (Pro).

When to use: as step three (closing step) of the governance pipeline, immediately after delimit_gov_run has recorded the execution. This is the call that flips a task from "ran" to "verified" and produces the attestation entry used by downstream audit consumers. When NOT to use: to mint a task (delimit_gov_new_task) or to record the execution itself (delimit_gov_run). Verify is closing only — it does not run work and does not create tasks.

Sibling contrast: delimit_gov_new_task creates; delimit_gov_run records execution; this attests the outputs satisfy policy. Compared to delimit_evidence_verify (which checks an evidence file), this attests against the policy engine, not a static file.

Side effects: gated by require_premium — unlicensed callers receive a license payload, no verification recorded. On a licensed call, invokes backends.governance_bridge.verify which writes a verification record against the task_id (verdict, timestamp, repo, policy snapshot). The response is routed through _with_next_steps. Does not perform additional work — only validates and records the verdict.

Pre-PR duplicate guard for external repos — call BEFORE drafting.

When to use: as the first step before drafting any PR against a repo you don't own. Fail-closed by design. When NOT to use: for internal repos or to evaluate a non-PR action (use delimit_gov_evaluate).

Sibling contrast: delimit_gov_evaluate(action="external_pr") wraps this with policy evaluation; this is the underlying duplicate check.

Side effects: read-only network call. Calls backends.governance_bridge.external_pr_check which shells out to gh CLI. Any open PR or PR merged in the last 30 days yields verdict="duplicate" — caller stops drafting.

Pre-submit gate for autonomous github outreach (LED-2214b).

When to use: as the LAST step before any agent submits a comment, issue body, or PR description to a third-party github repo via the outreach_substantive task path. Mandatory under CLAUDE.md SHIFT-1; bypass requires explicit founder approval. When NOT to use: for internal repo content, for posts on platforms other than github, or for non-outreach submissions (use the surface's own validators instead).

Sibling contrast: delimit_external_pr_check guards PR duplication; this guards the substantive-content boundary itself. For a PR submission the agent calls BOTH — this one first to refuse covert-commercial drafts, then external_pr_check to refuse duplicates.

Side effects: read-only. Pure validator over the body string and target metadata; no network, no ledger writes, no notifications.

The gate runs in two stages:

1. Target-side veto — if repo / repo_description / repo_topics contain a banking / fintech / regulator-adjacent keyword, the gate blocks regardless of content quality (SHIFT-1 hard veto; KYC would deanonymize the operating account).

2. Content shape — bans forbidden phrases (incl. our own product names), requires at least one technical anchor (commit hash, issue number, CVE, spec path, source file path), enforces minimum body length.

Run one tick of the autonomous github-outreach loop (LED-2214b).

When to use: from an external scheduler (cron, loop_daemon) or for an ad-hoc manual cycle. The tick monitors existing outreach LEDs for new activity AND scans for new substantive candidates. When NOT to use: as a backfill for thousands of stale items — the per-tick caps are intentional. Multiple ticks at the scheduler interval is the right pattern.

Sibling contrast: delimit_social_target scans a broader platform set; this is github-only and dispatches via the substantive- outreach path (with the SHIFT-1 gates). delimit_sensor_github_ issue watches a single issue; this orchestrates the sensor over every open outreach LED.

Side effects: reads ledger, network reads (gh CLI) for the monitor phase, writes new intel-class LEDs + dispatches new substantive tasks for the scan phase. Honours the DELIMIT_GITHUB_OUTREACH_DISABLED env var and the ~/.delimit/outreach_pause sentinel file as kill switches.

Score MCP tool docstrings against the 6 TDQS dimensions (LED-2108).

When to use: as a CI gate before publishing the MCP server, to catch low-quality tool descriptions. Operates on any Python file with @mcp.tool()-decorated functions.

When NOT to use: for runtime tool selection or policy decisions — TDQS grades documentation, not behaviour. Use delimit_lint for OpenAPI specs and delimit_gov_evaluate for policy-class decisions.

Sibling contrast: unlike delimit_lint (OpenAPI specs) and delimit_spec_health (spec quality scoring), this scores Python source against Glama's Tool Definition Quality Score rubric.

Side effects: none. Pure read-only static analysis via ast (no import, no execution). Does not write ledger, evidence, or notify.

Search conversation memory semantically (Pro).

When to use: to recall prior context by meaning rather than recency — e.g. "what did we decide about deploys?" finds relevant entries across sessions. When NOT to use: for the chronological tail (use delimit_memory_recent) or to write a memory (delimit_memory_store).

Sibling contrast: delimit_memory_recent is the free chronological tail; this is the Pro semantic search.

Side effects: read-only on the memory backend; gated by require_premium. Calls backends.memory_bridge.search.

Store a memory entry for future cross-session retrieval (Free tier).

When to use: per the orchestrator's memory rules — to capture failed approaches, architecture decisions, key context, or setup gotchas that git would not surface. When NOT to use: for routine code changes (git is the source of truth) or for venture-scoped artifacts (use delimit_context_write).

Sibling contrast: delimit_memory_search retrieves; delimit_memory_recent reads the tail; this writes.

Side effects: writes a memory entry via backends.memory_bridge.store. Free tier — no license gate. hot_load=True marks the entry for projection into the Claude Code auto-memory MEMORY.md hot-load index (PR-B writer projects on next sync).

Return the most recent memory entries (Free tier).

When to use: at session start to recall what the previous session was working on, or to scan for the last N memory captures. When NOT to use: for semantic / structured search (use delimit_memory_search) or to write a memory (delimit_memory_store).

Sibling contrast: delimit_memory_search does Pro semantic search; this is the free chronological tail.

Side effects: read-only. Calls backends.memory_bridge.get_recent. Free tier — no license gate.

Project delimit_memory hot entries into Claude Code's MEMORY.md.

When to use: to surface hot delimit_memory entries (flagged hot_load=True) into Claude Code's MEMORY.md so they load on session start without making delimit_memory dependent on Anthropic's auto-memory format. When NOT to use: to add a new memory (use delimit_memory_store) or search existing memories (delimit_memory_search, delimit_memory_recent).

Sibling contrast: delimit_memory_store writes a new entry; delimit_memory_search queries; delimit_memory_recent returns the tail; this is the one-way projection into MEMORY.md.

Side effects: writes to target_path (default ~/.claude/projects/-root/memory/MEMORY.md). If the file already has <!-- delimit:start --> / <!-- delimit:end --> markers, ONLY the content between them is replaced; anything outside is preserved. If markers are missing, the managed section is APPENDED to the end of the file (existing content is never touched). If the file does not exist, it is created with just the section. One-way projection only — MEMORY.md is never read back into delimit_memory (Anthropic owns the auto-memory format; format-drift risk).

LED-1165 Phase 2 #5 PR-B.

Search vault entries by query string (Pro).

When to use: to retrieve stored vault content matching a search string. The vault holds long-lived knowledge artifacts. When NOT to use: for conversation memory (use delimit_memory_search) or to capture state (delimit_vault_snapshot).

Sibling contrast: delimit_memory_search hits the conversation memory store; this hits the vault — different storage, different semantics.

Side effects: read-only on the vault backend; gated by require_premium. Calls backends.vault_bridge.search.

Report vault subsystem health (Pro).

When to use: at session start or as a CI smoke test to confirm the vault backend is reachable and indexes are intact. When NOT to use: to query content (use delimit_vault_search) or to capture state (delimit_vault_snapshot).

Sibling contrast: delimit_vault_search reads content; delimit_vault_snapshot captures state; this reports the engine's own health.

Side effects: read-only on the vault backend; gated by require_premium. Calls backends.vault_bridge.health.

Args: None.

Returns: Dict with health status and next_steps.

Capture a snapshot of vault state (Pro).

When to use: before a risky vault edit, to have a rollback point for content recovery. When NOT to use: for searching content (use delimit_vault_search) or checking health only (delimit_vault_health).

Sibling contrast: delimit_vault_health reports up/down only; this returns a structured snapshot of state.

Side effects: gated by require_premium. Calls backends.vault_bridge.snapshot, which writes a snapshot record on the vault backend.

Args: None.

Returns: Dict with snapshot data and next_steps.

Manage deployments (Pro).

Actions: plan, build, npm, publish, site, status, verify, rollback.

Generate a deploy plan with security preflight (Pro).

When to use: as the first step in the deploy chain. The plan enumerates build steps and bakes in a security audit + governance evaluation before any artifact is produced. When NOT to use: to actually build images (use delimit_deploy_build) or to ship code (use delimit_deploy_publish).

Sibling contrast: this is the planning gate; delimit_deploy_build and delimit_deploy_publish are the execution steps that follow.

Side effects: auto-chains delimit_security_audit (fail-closed on critical findings), then delimit_gov_evaluate, then the underlying deploy_plan handler. Halts and returns status="blocked" on any critical security finding without producing a plan.

Build container images for an app at a specific git ref (Pro).

When to use: as the second step of the deploy chain after delimit_deploy_plan has succeeded and you need SHA-tagged container images locally before delimit_deploy_publish pushes them to the registry. The full chain is plan -> build -> publish -> verify -> (rollback on failure). When NOT to use: to push existing images to a registry (use delimit_deploy_publish), to deploy a site (delimit_deploy_site), to publish an npm package (delimit_deploy_npm), or to start the full chain (delimit_deploy_plan).

Sibling contrast: deploy_plan plans, this builds local images, deploy_publish pushes to the registry, deploy_verify checks rollout health, deploy_rollback reverts. Compared to delimit_deploy_site (static-site deploy) and delimit_deploy_npm (npm publish), this is the container path.

Side effects: gated by require_premium — unlicensed callers receive a license payload and no build runs. On a licensed call, invokes backends.deploy_bridge.build which shells out to the local container builder (e.g. docker buildx) — this consumes local disk for image layers and CPU for the build. No network push at this step (that is delivery_publish). The response is routed through _with_next_steps.

Publish previously built images to the registry (Pro).

When to use: after delimit_deploy_build has produced images locally. When NOT to use: to build images (delimit_deploy_build) or to start the deploy chain (delimit_deploy_plan).

Sibling contrast: deploy_build produces local images; this pushes them to the registry; deploy_verify confirms rollout health.

Side effects: gated by require_premium. Calls backends.deploy_bridge.publish, which performs network writes to the configured container registry.

Probe a freshly-deployed revision's health — experimental (Pro).

When to use: immediately after delimit_deploy_publish has rolled out a new revision, to confirm the new SHA is actually healthy before declaring the deploy done and closing out the chain (delimit_deploy_verify -> delimit_evidence_collect -> delimit_ledger_done -> delimit_notify). If this returns unhealthy, the next step is delimit_deploy_rollback. When NOT to use: for steady-state runtime health checks (use delimit_obs_status / delimit_obs_metrics), to read deploy-system metadata only (delimit_deploy_status), or for a smoke test before deploy (delimit_test_smoke).

Sibling contrast: delimit_deploy_status reads deploy-system metadata only; this actively probes the running deployment. delimit_obs_status is the steady-state observability surface; this is post-deploy-only.

Side effects: gated by require_premium — unlicensed callers receive a license payload and no probe runs. On a licensed call, invokes backends.deploy_bridge.verify which performs network health checks against the deployed app (HTTP probes, container inspection, dependency reachability). No write. Marked EXPERIMENTAL — health logic may return partial results on backends without health endpoints; do not treat as authoritative for runtime SLOs.

Roll back an environment to a previous SHA (Pro).

When to use: when delimit_deploy_verify shows a regression and you need to revert the running deployment to a known-good revision. When NOT to use: to deploy a new version forward (delimit_deploy_plan -> _build -> _publish) — rollback is reversal-only.

Sibling contrast: delimit_deploy_publish moves an env forward; this moves it back to a prior to_sha.

Side effects: gated by require_premium. Calls backends.deploy_bridge.rollback which mutates the running environment to point at to_sha.

Read the current rollout metadata for an app/env (Pro).

When to use: to inspect the currently deployed SHA, rollout state, and any in-progress deploy without actually probing the running app. Useful for "what is live right now?" questions and for the deploy dashboard. When NOT to use: for active runtime health probes (use delimit_deploy_verify), for steady-state observability metrics (delimit_obs_metrics / delimit_obs_status), or to deploy a change (delimit_deploy_plan / delimit_deploy_build).

Sibling contrast: delimit_deploy_verify exercises the running app via probes; this reads deploy-system metadata only. delimit_release_status is the sibling on the release-tracking side (versions, history). Compared to a registry inspection, this reports rollout state, not just image presence.

Side effects: read-only against the deploy backend and gated by require_premium — unlicensed callers receive a license payload and no query runs. On a licensed call, invokes backends.deploy_bridge.status which queries the deploy state store. No write, no probe, no notification. Response routed through _with_next_steps.

Register a new dataset in the file-based intel registry.

When to use: at the start of an intel collection effort, to declare a named dataset that future ingest calls will write to. When NOT to use: to write data into an existing dataset (use delimit_intel_snapshot_ingest) or to inventory datasets (delimit_intel_dataset_list).

Sibling contrast: delimit_intel_dataset_list inventories; delimit_intel_dataset_freeze locks; this creates.

Side effects: writes a registry entry via backends.tools_data.intel_dataset_register. Coerces schema from a JSON string to a dict via _coerce_dict_arg.

List all datasets in the intel registry.

When to use: to inventory datasets currently registered for intel queries. When NOT to use: to register a new dataset (use delimit_intel_dataset_register) or to freeze one (delimit_intel_dataset_freeze).

Sibling contrast: delimit_intel_dataset_register writes; delimit_intel_dataset_freeze locks; this reads metadata.

Side effects: read-only. Calls backends.tools_data.intel_dataset_list.

Args: None.

Returns: Dict with the dataset registry and next_steps.

Freeze a dataset to make it immutable for replay integrity.

When to use: when a dataset is about to be referenced as evidence or signed attestation, and you want to lock its content forever. When NOT to use: to delete a dataset (the registry is append-only) or to inspect what's frozen (use delimit_intel_dataset_list).

Sibling contrast: delimit_intel_dataset_list inventories; delimit_intel_dataset_register writes; this locks against further writes.

Side effects: writes a frozen marker to the registry via backends.tools_data.intel_dataset_freeze. Subsequent writes to this dataset id will be rejected.

Store a research snapshot with provenance in the intel store.

When to use: to ingest research / signal data with provenance (source, author) for later replay or attestation. When NOT to use: to register a dataset (use delimit_intel_dataset_register) or query existing snapshots (delimit_intel_query).

Sibling contrast: delimit_intel_dataset_register declares; delimit_intel_query reads; this writes new snapshots.

Side effects: writes a snapshot record via backends.tools_data.intel_snapshot_ingest. Coerces data and provenance from JSON strings to dicts via _coerce_dict_arg.

Search saved intel snapshots by keyword, date, or dataset.

When to use: to surface ingested intel matching a query, optionally scoped to one dataset. When NOT to use: to ingest new data (use delimit_intel_snapshot_ingest) or list datasets (delimit_intel_dataset_list).

Sibling contrast: delimit_intel_snapshot_ingest writes; this reads back filtered snapshots.

Side effects: read-only. Calls backends.tools_data.intel_query. Coerces parameters from JSON string to dict via _coerce_dict_arg.

Generate a structured daily digest of loop activity (LED-966).

When to use: for the founder daily summary — signals, deliberations, ledger movement, swarm dispatch, health. When NOT to use: for raw notifications (use delimit_notify) or inbox routing (delimit_notify_inbox).

Sibling contrast: delimit_notify is per-event; this is a windowed rollup digest.

Side effects: action="run" always writes markdown + json to ~/.delimit/digest/ (the founder can read directly, no email dependency). When send_email=True, emails via the notify pipeline, BUT delivery requires DELIMIT_DIGEST_EMAIL=true in the env (pipeline gate). action="latest" is read-only.

Manage work orders — structured task artifacts for the founder (STR-177).

When to use: to list, read, or close work orders that bridge strategy deliberations and interactive execution. When NOT to use: for ledger items (use delimit_ledger_*) or governance tasks (delimit_gov_new_task / run / verify).

Sibling contrast: delimit_ledger_add tracks general work; delimit_gov_new_task is governance-classed; this is the founder work-order surface — copy-pasteable markdown artifacts.

Side effects: action="list" / "show" are read-only. action="complete" writes to the work-order store via ai.work_order.complete_work_order.

Run approved work orders from the dashboard inbox (Pro) (Worker Pool v2).

When to use: as the autonomous executor for human-approved work orders, or to inspect/pause the executor. When NOT to use: to dispatch new agent work (use delimit_agent_dispatch) or close out a work order (delimit_work_orders complete).

Sibling contrast: delimit_work_orders reads/closes the work order artifact; this is the run surface that turns approved orders into real GitHub side effects.

Side effects: action="run" / "poll" with live=True fire whitelisted state-changing actions: gh_issue_create, gh_pr_comment, gh_issue_comment. Every invocation is logged to ~/.delimit/workers/audit/executor.jsonl. Touch ~/.delimit/pause_executor to halt the autonomous path at the next tick.

Review and manage the signal corpus (LED-877).

When to use: to inspect, cluster, or explicitly promote sensed signals into ledger items. Signals live separately from the ledger so noise doesn't pollute it. When NOT to use: to fetch new signals (use the platform-specific sensors like delimit_reddit_scan / delimit_github_scan) or write ledger items directly (delimit_ledger_add).

Sibling contrast: platform sensors capture; this manages the captured corpus and bridges it into the ledger.

Side effects: "promote" writes a new ledger item (via the ledger manager). "freeze" cold-archives a month of signals. "query", "digest", "show", "status" are read-only against ~/.delimit/intel/signals/.

Write a single file from a code template into an existing project.

When to use: when an existing project needs one more piece — a component, a page, an API handler — and you want the framework-conformant skeleton (imports, exports, default structure) rather than hand-writing the boilerplate. Pair with delimit_test_generate to scaffold the matching test file. When NOT to use: to lay out a fresh project (use delimit_generate_scaffold), to design a UI component with tokens (delimit_design_generate_component), or to bulk-generate many files (call this once per file, or write a custom script).

Sibling contrast: delimit_generate_scaffold lays out a complete project tree; this writes a single file. Compared to delimit_design_generate_component, this is framework-only and does not consume design tokens. Compared to delimit_test_generate, this writes source, not tests.

Side effects: writes ONE file to disk under target/ via backends.generate_bridge.template. target is sanitised via _sanitize_path — paths escaping the workspace short-circuit with an error. features is coerced from a comma string to a list via _coerce_list_arg. No license gate, no ledger write, no notification. If a file with the same name already exists, the backend determines overwrite vs. error — call with care on populated directories.

Lay out a fresh project tree with framework-conformant skeleton.

When to use: at project zero, when starting a new Next.js app, API service, or library and you want the standard directory tree, package.json/pyproject.toml, lint config, and entry-point files all written in one call. Typical follow-up is delimit_init to set up governance scaffolding in the new project root. When NOT to use: to add files to an existing project (use delimit_generate_template for single-file scaffolds), to duplicate an existing project (use the shell), or to add a package to an existing project (use the project's own package manager directly).

Sibling contrast: delimit_generate_template writes a single file into an existing project; this writes a NEW project tree. Compared to create-next-app / cookiecutter, this routes the scaffold through the Delimit bridge so the resulting project can later be wired into delimit_init governance with no manual cleanup.

Side effects: writes MANY new files and directories under a new name/ root via backends.generate_bridge.scaffold. packages is coerced from a comma string to a list via _coerce_list_arg (malformed values short-circuit). No license gate. No ledger write, no notification. The backend determines collision behaviour if name/ already exists — call against a fresh target.

Diagnose repository health issues (experimental) (Pro).

When to use: before a commit or push to surface common repo problems — broken hooks, missing config, dirty working tree. When NOT to use: for full quality analysis (use delimit_repo_analyze) or per-file config validation (delimit_repo_config_validate).

Sibling contrast: delimit_repo_analyze is a deeper structural audit; this is a quick health-check pass.

Side effects: read-only on the repo; gated by require_premium. Calls backends.repo_bridge.diagnose. Marked experimental — output schema may evolve.

Analyze repository structure and quality (experimental) (Pro).

When to use: for a deep audit of a repo (local or remote) — code structure, language mix, quality signals. When NOT to use: for a fast health pass (use delimit_repo_diagnose) or config-only audit (delimit_repo_config_audit).

Sibling contrast: delimit_repo_diagnose is a quick smoke test; this is the deeper structural audit.

Side effects: read-only on the resolved local path. Accepts local path, "owner/repo" shorthand, or GitHub URL — remote inputs are shallow-cloned into a tempdir for the call. Calls backends.repo_bridge.analyze through _run_repo_tool_with_remote.

Validate repository configuration files (experimental) (Pro).

When to use: as a pre-merge check that .github/, package.json, pyproject.toml, etc. are well-formed and self-consistent. When NOT to use: for compliance vs an external standard (use delimit_repo_config_audit) or full repo analysis (delimit_repo_analyze).

Sibling contrast: delimit_repo_config_audit reports policy compliance; this checks structural validity.

Side effects: read-only on the resolved local path. Accepts local path, "owner/repo" shorthand, or GitHub URL — remote inputs are shallow-cloned into a tempdir. Calls backends.repo_bridge.config_validate via _run_repo_tool_with_remote.

Audit repository configuration for compliance (experimental) (Pro).

When to use: when checking a repo's config against a compliance standard — required files, branch protection, license header. When NOT to use: for structural validity (use delimit_repo_config_validate) or full quality analysis (delimit_repo_analyze).

Sibling contrast: delimit_repo_config_validate checks well-formedness; this checks compliance.

Side effects: read-only on the resolved local path. Accepts local path, "owner/repo" shorthand, or GitHub URL — remote inputs are shallow-cloned. Calls backends.repo_bridge.config_audit via _run_repo_tool_with_remote.

Scan a repository for security vulnerabilities.

When to use: as a baseline security pass over a repo, before a deploy or a release. When NOT to use: to ingest external scan results (use delimit_security_ingest) or to triage findings (delimit_security_deliberate).

Sibling contrast: delimit_security_ingest accepts external scanner output; delimit_security_deliberate triages findings; this is the built-in scan.

Side effects: read-only on the target. Calls backends.repo_bridge.security_scan.

Ingest external security scan output and normalize into ledger findings (Pro).

When to use: after running a scanner externally — Trivy, Semgrep, npm-audit, pip-audit, Snyk, CodeQL — to feed its JSON output into Delimit's canonical schema and gate deploys on unresolved criticals. When NOT to use: to run a scan from scratch (use delimit_security_scan) or to triage findings (delimit_security_deliberate).

Sibling contrast: delimit_security_scan runs the built-in scan; delimit_security_deliberate triages findings; this is the bridge that pulls external scanner output into the same ledger.

Side effects: gated by require_premium. Writes findings to the ledger (creates new items, optionally closes resolved ones). Computes a stable fingerprint per finding to enable diffing.

Multi-model triage of security findings (Pro).

When to use: after delimit_security_ingest has loaded findings, to classify each as real risk / false positive / accepted risk / needs immediate action. When NOT to use: to ingest the findings (use delimit_security_ingest) or to scan from scratch (delimit_security_scan).

Sibling contrast: delimit_deliberate is general-purpose multi-model consensus; this is the security-class variant scoped to findings.

Side effects: gated by require_premium. Calls multiple models via the deliberation panel. Updates ledger items with triage verdicts.

Manage SIEM streaming for audit-event forwarding (Splunk/Datadog/etc.).

When to use: to inspect or configure where Delimit's audit events stream — Splunk, Datadog, EventBridge, generic webhooks. When NOT to use: for one-shot notifications (use delimit_notify) or inbox handling (delimit_notify_inbox).

Sibling contrast: delimit_notify sends to humans; this configures structured-log streaming to SIEM endpoints.

Side effects: action="configure" / "forward" / "test" write to the configured SIEM endpoints (network calls). action="status" is read-only.

Audit security and auto-chain evidence + governance on critical findings.

When to use: as the deploy gate / pre-release security check — combines dependency vulnerability scanning, hardcoded-secret detection, dangerous-pattern checks, and .env-tracked-in-git checks, AND automatically opens a governance task + sends a notification when critical findings are present. When NOT to use: for a baseline scanner pass without auto-chained side effects (use delimit_security_scan), to ingest an external scanner's output (delimit_security_ingest), or to triage existing findings (delimit_security_deliberate).

Sibling contrast: delimit_security_scan is the read-only baseline scanner; delimit_security_ingest accepts external tool output; delimit_security_deliberate triages findings via multi-model panel; this one runs the audit AND auto-chains evidence collection, governance task creation, and notification on criticals.

LED-1278: by default the scanner skips test directories (tests/, tests/, spec/, fixtures/, *_test.py, *.test.tsx, etc.) and suppresses well-known dummy values (AWS canonical example, alphabet-pattern GitHub tokens, leading-1234567890 Slack tokens, trivial JWTs, generic placeholder dict values). Pass include_tests=True to scan test trees too — useful for repos that ship real secrets in fixture files (rare, but legitimate).

Side effects: writes an evidence bundle (always, best-effort). On critical findings, creates a governance task via the governance engine and sends a webhook notification. Optional: SNYK_TOKEN or Trivy in the environment enable enhanced scanning.

Collect evidence artifacts for governance (Pro).

When to use: after a deploy, security audit, test run, or other gate event — to capture an evidence bundle that delimit_evidence_verify can later attest. When NOT to use: to verify an existing bundle (use delimit_evidence_verify) or query the contract ledger (delimit_ledger).

Sibling contrast: delimit_evidence_verify verifies; delimit_ledger queries the chain; this collects new evidence.

Side effects: gated by require_premium. Writes a new evidence bundle via backends.repo_bridge.evidence_collect.

Verify the integrity of an evidence bundle (Pro).

When to use: to attest that a previously-collected evidence bundle has not been tampered with — typical use is during replay or audit. When NOT to use: to capture new evidence (use delimit_evidence_collect) or to query the contract ledger (delimit_ledger).

Sibling contrast: delimit_evidence_collect captures; this verifies a captured bundle's hash chain integrity.

Side effects: read-only on the evidence store; gated by require_premium. Calls backends.repo_bridge.evidence_verify.

Verify a Delimit Seal receipt against the bundled Layer-0 constitution (Free).

When to use: to check that a signed governed-output receipt has not been tampered with — content-pin to the published constitution, a valid Ed25519 signature, and a well-formed structure. Free tier. When NOT to use: to verify an evidence bundle (use delimit_evidence_verify) or to query the ledger (delimit_ledger).

Sibling contrast: delimit_evidence_verify checks an evidence bundle's hash chain; this checks an open-core Seal receipt's signature + content-pin with no access to the engine or the signing key.

Side effects: read-only. Calls backends.repo_bridge.seal_verify. The 'cryptography' dependency is optional + lazy-imported: if absent, it returns verification_unavailable rather than failing. No license gate.

Manage releases: plan, validate, status, rollback, history, sync (Pro for plan/status/sync).

Actions: plan, validate, status, rollback, history, sync.

Generate a release plan from git history (Pro).

When to use: ahead of cutting a release, to enumerate the services and changes that will ship and surface the version to bump. When NOT to use: to validate readiness (use delimit_release_validate) or to ship code (use delimit_deploy_publish).

Sibling contrast: delimit_deploy_plan plans a deploy of one app; this plans a multi-service release across an environment.

Side effects: read-only on git/repo state; gated by require_premium. Calls backends.tools_infra.release_plan.

Validate that a release is safe to ship (Pro).

When to use: as the gate between delimit_release_plan and the actual rollout — confirms the release passes preflight checks. When NOT to use: for OpenAPI spec linting (delimit_lint) or for runtime health (delimit_obs_status).

Sibling contrast: delimit_release_plan describes what would ship; this attests it is safe to ship.

Side effects: on success, returns a passed verdict (no side effects). On failure, auto-chains:

1. backends.repo_bridge.evidence_collect (records failure evidence)

2. ai.notify.send_notification (webhook event release_validation_failed)

3. ai.ledger_manager.add_item (creates ops-ledger fix item, P1)

Report the active release version for a whole environment (Pro).

When to use: to inspect which release version is currently live across all services in an environment — the "what is shipped right now?" check at the release-tier (versions across services) rather than the deploy-tier (per-app SHA). Useful for incident pages and pre-deploy "what are we coming from?" snapshots. When NOT to use: for per-app rollout state (use delimit_deploy_status), for past releases on the same env (use delimit_release_history), or to plan a new release (delimit_release_plan).

Sibling contrast: delimit_deploy_status reports a single app's SHA rollout; this reports the environment's release version overall (the rollup across apps). delimit_release_history is the time-axis sibling; this is the point-in-time snapshot.

Side effects: read-only against the ops backend and gated by require_premium — unlicensed callers receive a license payload and no query runs. On a licensed call, invokes backends.tools_infra.release_status which reads the release manifest for the environment. No write, no probe, no notification. Response routed through _with_next_steps.

Revert a whole environment to a prior release version (experimental).

When to use: when delimit_release_validate or delimit_obs_alerts indicate a regression that spans services and you need to revert the WHOLE environment to a known-good release, not just one app. Typical sequence: alert fires -> delimit_release_history to pick a target -> this -> delimit_release_status to confirm. When NOT to use: to roll back a single app at the SHA level (use delimit_deploy_rollback), to roll back an npm publish (npm publish history is largely append-only — there is no clean rollback), or to roll forward (delimit_release_plan).

Sibling contrast: delimit_deploy_rollback reverts one app at the SHA level; this reverts a release version across services in lockstep. delimit_release_history is how you pick the to_version.

Side effects: invokes backends.ops_bridge.release_rollback which MUTATES the live environment — services are flipped to the to_version artifacts. No license gate at this level (handled by the backend's own admin checks). Marked EXPERIMENTAL — handler may return partial results on backends without rollback automation; verify with delimit_release_status afterwards. No automatic ledger write, no automatic notification — pair with delimit_evidence_collect + delimit_notify per the deploy-gate chain.

Return the recent release timeline for an environment (experimental).

When to use: during incident investigation when you need to see what shipped and when ("what changed in the last 10 releases?"), or when picking a known-good to_version for delimit_release_rollback. The output is the release-tier equivalent of git log for a deploy environment. When NOT to use: to inspect only the current release (use delimit_release_status) or for per-app deploy timeline (delimit_deploy_status / SHA-level history). Also: for audit-trail evidence collection use delimit_evidence_collect.

Sibling contrast: delimit_release_status is the point-in-time snapshot; this is the time-axis sibling. delimit_release_rollback consumes the output of this tool when picking a target version.

Side effects: read-only against the ops backend. No license gate at this level. Calls backends.ops_bridge.release_history which reads the release timeline store. No write, no probe, no notification. Marked EXPERIMENTAL — output schema may evolve.

Analyze a project for cost drivers (Dockerfile, deps, cloud) (Pro).

When to use: when investigating spend on a project — scans Dockerfile, dependency manifests, and cloud configs for cost signals. When NOT to use: to enact cost reductions (use delimit_cost_optimize) or to manage alert rules (delimit_cost_alert).

Sibling contrast: delimit_cost_optimize finds reduction opportunities; this surfaces drivers (where the cost is).

Side effects: read-only on the target. Gated by require_premium. Calls backends.tools_data.cost_analyze.

Find cost optimization opportunities in a project (Pro).

When to use: after delimit_cost_analyze surfaces drivers, to get concrete suggestions: unused deps, oversized images, uncompressed assets. When NOT to use: to inventory current spend (delimit_cost_analyze) or manage threshold alerts (delimit_cost_alert).

Sibling contrast: delimit_cost_analyze identifies sources of cost; this proposes reductions.

Side effects: read-only on the target. Gated by require_premium. Calls backends.tools_data.cost_optimize.

Manage cost alert rules (CRUD on spending thresholds) (Pro).

When to use: to configure ongoing spend thresholds and notifications that fire when costs exceed a configured ceiling. When NOT to use: for one-shot cost analysis (use delimit_cost_analyze) or finding optimisations (delimit_cost_optimize).

Sibling contrast: delimit_cost_analyze finds drivers; delimit_cost_optimize finds reductions; this manages the alerting layer.

Side effects: action="create"/"delete"/"toggle" write to the file-based alert store. action="list" is read-only.

Manage MCP rate limits and session cost controls.

When to use: to inspect or adjust per-tool hourly rate limits and the session cost cap that throttle Delimit's call surface. When NOT to use: for project-cost analysis (use delimit_cost_analyze) or alert configuration (delimit_cost_alert).

Sibling contrast: delimit_cost_analyze inspects spend in your project; this manages our own per-session call quotas.

Side effects: action="set" / "reset" mutate the rate-limiter state. action="status" / "quota" are read-only.

Validate data files: JSON parse, CSV shape, SQLite integrity.

When to use: as a smoke check before relying on data files (CI pipelines, before migrations) to catch corruption early. When NOT to use: for migration status (use delimit_data_migrate) or backups (delimit_data_backup).

Sibling contrast: delimit_data_migrate inspects migration files; this exercises the data files themselves.

Side effects: read-only on the target. Calls backends.tools_data.data_validate.

Inspect migration files (alembic / Django / Prisma / Knex) for status.

When to use: to audit pending and applied migrations before a deploy, or as a CI gate. When NOT to use: to actually apply migrations (this tool only inspects status) or back up data first (delimit_data_backup).

Sibling contrast: delimit_data_validate exercises data files; delimit_data_backup captures restore points; this reads migration status only.

Side effects: read-only inspection. Calls backends.tools_data.data_migrate.

Back up SQLite and JSON data files to ~/.delimit/backups/.

When to use: before a risky migration or refactor that touches SQLite or JSON data, to capture a timestamped restore point. When NOT to use: to validate data integrity (use delimit_data_validate) or apply migrations (delimit_data_migrate).

Sibling contrast: delimit_data_validate inspects integrity; delimit_data_migrate runs migrations; this captures a backup.

Side effects: writes timestamped copies of SQLite + JSON files under ~/.delimit/backups/ via backends.tools_data.data_backup.

Manage observability: metrics, logs, alerts, status (Pro for metrics/logs/status).

Actions: metrics, logs, alerts, status.

Pull numeric metric series from the observability backend (Pro).

When to use: during runtime health investigation when you need numeric series (CPU, memory, request rate, error rate, latency percentiles) over a named time window. Pair with delimit_obs_logs to correlate a numeric anomaly with the underlying log lines. When NOT to use: for free-text search of log lines (use delimit_obs_logs), to read or configure alert rules (delimit_obs_alerts), or for a quick at-a-glance health rollup (delimit_obs_status).

Sibling contrast: delimit_obs_logs returns text matches; this returns numeric time series. delimit_obs_status is the rollup-summary surface; this is the raw-series surface. delimit_obs_alerts configures thresholds against these same series.

Side effects: read-only on the metrics backend and gated by require_premium — unlicensed callers receive a license payload and no query runs. On a licensed call, invokes backends.tools_infra.obs_metrics which queries the backing metrics store; no data is written, no ledger entry, no notification. The response is routed through _with_next_steps.

Search application and system logs across configured sources (Pro).

When to use: during incident investigation when you have a symptom (error string, trace id, user id, request id) and need to find every log line mentioning it across the configured sources over a time window. The typical pattern is: delimit_obs_metrics flags a numeric anomaly, then this tool finds the offending log lines. When NOT to use: for numeric series (use delimit_obs_metrics), for the at-a-glance health rollup (delimit_obs_status), or to configure ongoing alerts (delimit_obs_alerts). Also: do not use this as a tail-follow surface — it is a windowed search, not a streaming subscription.

Sibling contrast: delimit_obs_metrics returns numeric series for the same backend; this returns text matches. Compared to grepping the local filesystem, this queries the centralised log store across services / hosts.

Side effects: read-only on the log backend and gated by require_premium — unlicensed callers receive a license payload and no query runs. On a licensed call, invokes backends.tools_infra.obs_logs which queries the backing log store; no data is written, no ledger entry, no notification. The response is routed through _with_next_steps.

Manage alerting rules — list, create, update, delete (experimental).

When to use: to configure ongoing alerts for production thresholds (latency, error rate, saturation, queue depth) against the same metric series visible via delimit_obs_metrics. Sub-actions: "list" inventories existing rules, "create" mints one, "update" edits, "delete" removes. When NOT to use: for one-shot metric queries (delimit_obs_metrics), log search (delimit_obs_logs), or the health rollup (delimit_obs_status). Also: do not call "create" repeatedly to retry a failed alert delivery — alerting is configuration, not delivery.

Sibling contrast: delimit_obs_metrics queries data; this configures automated thresholds against that data. Compared to cloud-provider alerting consoles, this routes through the ops bridge so the rule set is recorded in the same observability layer as the metric source.

Side effects: WRITES to the alert configuration on the ops backend for action in ("create", "update", "delete"); reads only for "list". Routes through backends.ops_bridge.obs_alerts. Marked EXPERIMENTAL — the schema for alert_rule is backend-specific and may evolve; pin tested rule shapes if depending on this in production. No license gate at this level (gating handled by the backend's own admin checks).

Return a high-level health rollup from the observability layer (Pro).

When to use: for the "are we green?" check at session start, in a status dashboard, or as a single-call smoke test before a deploy. The orchestrator's session-start ritual calls this only if delimit_agent_dashboard or delimit_gov_health flag anomalies — it is the second-tier health surface, not the first. When NOT to use: for detailed numeric series (delimit_obs_metrics), for log investigation (delimit_obs_logs), or for alerting rule management (delimit_obs_alerts). Also do not use as the only deploy gate — pair with delimit_security_audit + delimit_test_smoke per the deploy chain.

Sibling contrast: delimit_obs_metrics returns raw numeric series; this returns a synthesised rollup (typically per-service status + a few key indicators). Compared to delimit_gov_health, this reports the runtime observability layer rather than the governance kernel.

Side effects: read-only on the observability backend and gated by require_premium — unlicensed callers receive a license payload and no query runs. On a licensed call, invokes backends.tools_infra.obs_status which composes a health summary from the backing data sources. No write, no ledger entry, no notification. Response is wrapped through _with_next_steps.

Args: None.

Returns: Dict with keys: overall (green/yellow/red), services (list of {name, status, indicators}), checked_at timestamp, plus a next_steps field from _with_next_steps. Returns a license-gate payload if the caller lacks Premium, or {"error": "..."} on backend failure (does not raise).

Validate cross-agent handoff invariants before switching coding agents (LED-1710).

When to use: before a session hands off to a different coding agent (claude -> antigravity -> codex -> gemini) or an Auto-Phoenix revive, to confirm the next agent will NOT inherit corrupted state — a core.bare=true repo, a junk test@*/empty git identity, leaked GIT_* env vars that misdirect git subprocesses, a stale <gitdir>/index.lock, or a missing/stale ~/.delimit/.last_capture stamp (next agent starts blind). When NOT to use: to capture or restore session context (use delimit_soul_capture / delimit_revive — this only INSPECTS), or for general repo health (delimit_repo_diagnose).

Sibling contrast: delimit_revive restores prior context (read+write); delimit_gov_health reports the policy-kernel layer; this is a narrow read-only pre-handoff gate over git + env + capture stamp returning a fail-closed verdict. Phase-1 VALIDATOR only: NOT wired into any live handoff path; auto-remediation is held for a later phase.

Side effects: READ-ONLY — inspects git config + the process env + the .last_capture file via a hermetic git env. NO writes, env mutation, git config changes, network, ledger, or notification; it cannot itself corrupt the state it checks.

Verdict: ok=False if ANY critical check fails (fail-closed). Critical: git_identity, not_bare. Warn: no_git_env_leak, no_stale_index_lock, handoff_freshness. Each check is {name, ok, severity, detail, remediation}.

Walk the heartbeat directory and report which scheduled services are stale (LED-1412).

When to use: as part of the session-start ritual to surface silent daemon staleness before it becomes a customer-visible incident. The 2026-05-15 incident — delimit-reddit-proxy.service inactive for 13 days, all reddit scans 429-failing silently, founder noticing only via "3 day old posts" — is the failure mode this prevents. Each scheduled task writes ~/.delimit/heartbeats/<service>.json after every run; this tool walks the dir and classifies each service. When NOT to use: for one-off liveness checks (just read the file yourself) or for full-host metrics (delimit_obs_status). Phase 2 will add an external deadman ping for full-host outages — heartbeats here are local-only.

Sibling contrast: delimit_obs_status reports composed runtime observability metrics; this reports per-service liveness based on last_run timestamps written by each daemon. delimit_gov_health reports the kernel layer.

Side effects: read-only on the heartbeat directory. No network, no write, no ledger, no notification.

Classification (most-severe-first):

• parse_error: heartbeat file unreadable

• failed: status='failed' in the record

• stale: last_run older than service-specific threshold

• degraded: status='degraded' in the record

• never_seen: configured service has no heartbeat file yet

• unknown_age: heartbeat exists but timestamp won't parse

• ok: status='ok' AND last_run within threshold

Per-service thresholds default to sensible values (reddit/social-loop 2h, inbox 30min, daily timers 36h). Override via <dir>/_thresholds.json — JSON map of {service_name: seconds}.

Extract design tokens from a project's CSS/SCSS/Tailwind config.

When to use: to inventory or generate design tokens before creating a Tailwind config or component scaffold. When NOT to use: to scaffold a component (use delimit_design_generate_component) or generate tailwind config (delimit_design_generate_tailwind).

Sibling contrast: delimit_design_generate_tailwind builds a config from these tokens; this extracts them.

Side effects: read-only scan of local CSS/Tailwind. Figma API integration auto-activates when a Figma token is found in FIGMA_TOKEN env var, ~/.delimit/secrets/figma.json, or via delimit_secret_store. Calls backends.ui_bridge.design_extract_tokens. Coerces token_types via _coerce_list_arg.

Generate a React/Next.js component skeleton with Tailwind support.

When to use: to scaffold a new component (.tsx) with props interface and Tailwind class structure. When NOT to use: to generate stories for an existing component (use delimit_story_generate) or extract design tokens (delimit_design_extract_tokens).

Sibling contrast: delimit_story_generate adds stories to a component; this creates the component itself.

Side effects: writes a new component file (.tsx) under output_path or components//.tsx via backends.ui_bridge.design_generate_component. Detects Tailwind config inside project_path.

Read an existing tailwind.config or generate one from detected CSS tokens.

When to use: to bootstrap a Tailwind config from existing CSS tokens, or to inspect an existing config in a project. When NOT to use: to extract general design tokens (use delimit_design_extract_tokens) or generate a component (delimit_design_generate_component).

Sibling contrast: delimit_design_extract_tokens scans CSS; this writes a tailwind config from those tokens.

Side effects: writes tailwind.config.js if missing, otherwise reads the existing one. Calls backends.ui_bridge.design_generate_tailwind.

Validate responsive design patterns via static CSS analysis.

When to use: as a CI check after editing UI/CSS, to flag missing media queries, fixed widths, or non-mobile-first patterns. When NOT to use: for accessibility audits (use delimit_story_accessibility) or component scaffolding (delimit_design_generate_component).

Sibling contrast: delimit_story_accessibility checks WCAG; this checks responsive patterns.

Side effects: read-only static analysis of CSS files. Calls backends.ui_bridge.design_validate_responsive. Coerces check_types from comma string to list via _coerce_list_arg.

Scan a project for React/Vue/Svelte components and emit a catalog.

When to use: to inventory a project's UI components for review, docs, or design-system curation. When NOT to use: to generate a single component (delimit_design_generate_component) or stories (delimit_story_generate).

Sibling contrast: delimit_design_generate_component creates one; this lists what already exists.

Side effects: read-only scan via backends.ui_bridge.design_component_library. Writes nothing.

Generate a .stories.tsx file for a UI component (no Storybook required).

When to use: to scaffold per-variant stories for a React/TSX component without installing the full Storybook toolchain. When NOT to use: for accessibility checks (use delimit_story_accessibility) or component scaffolding from scratch (delimit_design_generate_component).

Sibling contrast: delimit_design_generate_component creates the component; this generates its stories file. Together they form a component-first authoring path.

Side effects: writes a new .stories.tsx file next to the component. Coerces variants from a comma string to a list via _coerce_list_arg.

Run visual regression test — screenshot vs stored baseline.

When to use: as a CI gate after UI changes, to catch unintended visual regressions vs a stored baseline. Auto-creates the baseline on first run. When NOT to use: for a11y checks (use delimit_story_accessibility) or one-off screenshots (delimit_screenshot).

Sibling contrast: delimit_screenshot is one image without baseline; delimit_story_accessibility audits HTML; this compares against a stored baseline.

Side effects: writes baseline images on first run; subsequent runs are read-only against the baseline. Falls back to Puppeteer (screenshot only) when Playwright is not installed.

Build a Storybook static site (or return setup guidance).

When to use: to build the Storybook static site for an existing project, e.g. for hosting on a docs site. When NOT to use: to write stories (use delimit_story_generate) or run a11y checks (delimit_story_accessibility).

Sibling contrast: delimit_story_generate writes stories; delimit_story_accessibility audits; this builds the static site.

Side effects: when Storybook is configured, invokes the build via backends.ui_bridge.story_build (subprocess writes the static site under output_dir). When not configured, returns setup guidance instead.

Scan HTML/JSX/TSX for WCAG accessibility issues.

When to use: as a CI gate or pre-merge check on UI changes for common a11y problems — missing alt, missing labels, empty buttons, heading order, aria-hidden on focusable elements. When NOT to use: for responsive layout (use delimit_design_validate_responsive) or visual regression (delimit_story_visual_test).

Sibling contrast: delimit_design_validate_responsive checks layout; this checks WCAG.

Side effects: read-only static analysis. Calls backends.ui_bridge.story_accessibility_test.

Generate test skeletons for source code (Jest / pytest / vitest).

When to use: to scaffold new test stubs for public functions when starting tests on a previously-untested module. When NOT to use: to measure coverage of existing tests (use delimit_test_coverage) or run a smoke test (delimit_test_smoke).

Sibling contrast: delimit_test_coverage measures; delimit_test_smoke runs; this writes new test scaffolds.

Side effects: writes new test files alongside the source. Uses AST parsing for Python and regex for JS/TS via backends.ui_bridge.test_generate.

Analyze test coverage for a project (experimental) (Pro).

When to use: to surface coverage by file/folder against a threshold when you need a pass/fail signal for CI. When NOT to use: to scaffold new test stubs (use delimit_test_generate) or run a smoke run (delimit_test_smoke).

Sibling contrast: delimit_test_smoke validates that tests run at all; delimit_test_generate writes test scaffolds; this measures coverage of existing tests.

Side effects: read-only inspection. Gated by require_premium. Calls backends.ui_bridge.test_coverage. Marked experimental — coverage runner detection is heuristic.

Run smoke tests for a project.

When to use: as a pre-commit / pre-deploy gate to confirm tests pass. Auto-detects framework (pytest / jest / vitest / mocha) from project config. When NOT to use: to scaffold new tests (use delimit_test_generate) or measure coverage (delimit_test_coverage).

Sibling contrast: delimit_test_generate writes; delimit_test_coverage measures; this runs and parses.

Side effects: invokes the project's test runner via backends.ui_bridge.test_smoke (subprocess). Read-only on filesystem apart from the test runner's own outputs.

Generate a markdown API reference from source docstrings/JSDoc.

When to use: to produce a starter API reference doc from existing in-source documentation, organized per source file. When NOT to use: for doc-quality validation (use delimit_docs_validate) — generation does not validate.

Sibling contrast: delimit_docs_validate inspects existing docs; this writes a fresh API reference.

Side effects: writes a markdown reference file via backends.ui_bridge.docs_generate.

Validate documentation quality and completeness.

When to use: as a CI gate to surface missing READMEs, undocumented public functions, and broken internal markdown links. When NOT to use: to generate fresh API reference (use delimit_docs_generate).

Sibling contrast: delimit_docs_generate writes; this validates existing docs.

Side effects: read-only inspection. Calls backends.ui_bridge.docs_validate.

Check a GitHub issue for new comments since the last sensor tick.

When to use: to monitor a specific outreach / tracking issue for new activity, returning a structured signal for routing. When NOT to use: for repo-wide scans (use delimit_github_scan) or one-shot fetch (delimit_resource_get).

Sibling contrast: delimit_github_scan scans many repos for migrations; this watches one issue for new comments.

Side effects: read-only network call via gh CLI. Validates repo format with regex (defense-in-depth). Subject to the confused-deputy guard (_check_repo_allowlist) before fetching.

Scan GitHub issues/PRs for migration patterns across target repos.

When to use: for competitive intelligence — surface where target repos are migrating between tools (e.g. "switched from X to Y", "replaced X with Y") so the sensing function can act on the signal. When NOT to use: for general sensing/outreach research (use delimit_sense), to pull single-issue intel (delimit_sensor_github_issue), or for broad public-repo polling (delimit_github_scan).

Sibling contrast: delimit_sensor_github_issue tracks a specific issue's state; delimit_github_scan does broad public-repo polling; delimit_sense is the high-level sensing entrypoint; this one detects migration-pattern language specifically.

Side effects: read-only on the target repos via GitHub API. Enforces the per-repo allowlist (LED-881 confused-deputy guard) — refuses non-allowlisted repos. Calls ai.social_target.scan_github_migrations.

Return Delimit server version, tool count, and environment status.

When to use: at session start, in a dashboard, or as a diagnostic when investigating capability availability. When NOT to use: for governance health (use delimit_gov_health) or OS status (delimit_os_status).

Sibling contrast: delimit_help describes individual tools; this reports server-wide version and detected environment.

Side effects: read-only. Counts registered tools and detects API keys / CLIs / security tools in the environment so callers know what's available without manual config.

Args: None.

Returns: Dict with version, total_tools, adapter_contract, authority, environment-detection results, plus next_steps.