Return service health: kb_commit, index_built_at, staleness, degraded flag, and write-side state (pending_count, push_queue_size, last_index_*).

verbose: False (default) returns a token-compact shape that keeps the core snapshot and OMITS diagnostic fields that are null/empty (e.g. last_index_error, remote_head_sha when unset). verbose=True returns every field including the nulls.

pending_actions, when present, lists open maintenance items (missing status fields, recently-expired/expiring-soon docs) computed at the last index build; it is omitted when the corpus is clean. Surface it to the operator and act on it only with operator confirmation.

Return the tree of tiers and categories with doc counts.

verbose: kb_outline is already lean, so compact and full modes return the same shape; the parameter exists for interface consistency.

Full-text search across the KB.

Optional tier/category/status/type filters (status e.g. 'active', doc_type e.g. 'decision'). Returns ranked hits with snippets.

in_force: when true, HARD-filter to the in-force status class (active/accepted/approved) AND the validity window (not expired, not upcoming) before ranking, EXCLUDING superseded/deprecated/expired/ upcoming docs rather than only soft-downranking them. Composes with an explicit status (both must hold). Use this when you want only guidance that currently applies.

A doc past its valid_until date is EXCLUDED from every default search result (not just in_force=True): an expired doc has no named successor to outrank it, so left visible it could be the top hit and would govern. Set include_expired=true to see it anyway; it then carries freshness: "expired". A doc with a future valid_from ("upcoming") stays visible in default search, flagged freshness: "upcoming"; only in_force=true excludes it. validity_state is an audit-query facet: one of "expired", "stale", or "expiring_within:N" (N days) to list docs by validity condition; filtering for "expired" implies including them regardless of include_expired.

abstain: when true, apply the signal gate. If the query matches no discriminating column (title/tags/applies_when) it is treated as out-of-scope and the search returns NO hits with abstained: true and an abstain_reason, instead of surfacing a weak keyword match. A query with a real signal retrieves normally. Distinguish abstained: true (no governing rule) from an ordinary empty result (abstained: false).

verbose: False (default) returns a token-compact shape. Each hit is {id, title, snippet} plus status only when a hit is NOT in-force (superseded/deprecated), type when set, and freshness only when a hit deviates (stale/expired/upcoming); the query echo, per-hit path, and score are dropped (fetch a hit's full metadata with kb_get(id); array order conveys rank). A compact hit additionally carries in_force: false when the computed in-force predicate (the single-sourced status + validity-window + not-inbox rule; never stored in frontmatter) says the doc does NOT currently govern -- emitted deviation-only, so an in-force hit's compact shape is unchanged. verbose=True restores the full legacy shape with query, path, score, status, type, freshness, and the computed in_force: bool on every hit, so a hit retrieved WITHOUT in_force=true can still be checked for whether it may govern now.

Retrieve a document by id (STD-U-001, ADR-002, T-NNN, etc.). Returns the full content markdown plus metadata.

Always resolves regardless of expiry (ids never dangle): an expired document is still returned, with its full validity object and a computed freshness indicator (stale/expired/upcoming).

verbose: False (default) returns the full content_markdown body (kb_get exists to read the doc) with a trimmed envelope: path, git_remote_url, and last_modified_source are dropped and empty status/type/applies_when/description/validity/freshness are omitted; source_commit and last_modified provenance are kept, and in_force: false is emitted when the computed in-force predicate says the doc does NOT currently govern (deviation-only; an in-force doc omits the key). verbose=True returns the full legacy envelope with every field plus the computed in_force: bool (the single-sourced status + validity-window + not-inbox predicate; never stored in frontmatter).

List doc ids in the given tier (and optional category), ordered by id.

verbose: False (default) drops per-entry path (fetch via kb_get(id)) and omits a null category. verbose=True restores the full shape with paths.

Compute onboarding status for a workspace + optional component. State is one of: absent, partial, onboarded, rename_candidate.

Read-only. Classify local project-repo docs against KB content for this workspace/component and return thin-pointer replacements for duplicates. The agent applies confirmed edits locally; the server writes nothing.

Propose a new memory file. High confidence auto-commits and enqueues for push; low confidence enters the pending queue for operator review.

evidence: optional supporting-context strings (max 10 items, 500 chars each), rendered into the memory's frontmatter and surfaced by kb_pending.

Propose an edit to an existing (or new) markdown file under an indexed tier. High confidence auto-commits + queues for push; low confidence enters the pending queue for operator review.

evidence: optional supporting-context strings (max 10 items, 500 chars each), persisted in pending meta / audit events and surfaced by kb_pending (not rendered into the postimage: unlike kb_propose_memory, the postimage here is caller-supplied verbatim).

Resolve a pending proposal: approve (optionally with edited text) or reject. Approval commits + enqueues for push.

override_secret_scan: operator-only override of the secret- scanning gate (issue #71). When True and the resolved postimage matches a credential pattern, the commit proceeds anyway instead of being rejected rejected_secret_detected, and the audit event records that the override was used. Use only after confirming the flagged content is NOT a real credential.

List currently pending proposals awaiting operator decision.

Return recent audit events, most-recent first. Optional filters: since (unix ts), agent (agent_identity), status (event status).

Read-only per-session write summary (issue #112 feedback loop): N committed, M demoted-to-pending, K rejected for source_session. Call this (or kb pending) whenever a write response indicated a demotion, to confirm the current tally before informing the operator.

Bootstrap a new workspace/component. Only valid when status=absent or partial. High confidence commits atomically; low confidence enqueues pending.

Record a consultation for (source_session, workspace) and return the governing rules for the intent. Call before code/architectural work. trigger is 'explicit' (default: a deliberate consult, clears the gate) or 'prompt_hook' (an installer auto-consult: audited, never clears).

Retrieval is hard-filtered to the in-force class (active/accepted/ approved, within its validity window, and never a memory-inbox doc): an unreviewed proposed memory, a retired/superseded decision, an expired doc, or a legacy/forged inbox file is never returned as a governing rule.

pending_actions, when present, lists open maintenance items (missing status fields, recently-expired/expiring-soon docs); omitted when the corpus is clean. Surface it to the operator and act on it only with operator confirmation.

Return a verdict (allow | consult_required) for a pending code action. Governed actions require a fresh consultation on record.

Aggregate enforcement events (consult / gate_*) overall and per agent.

Record a gate_bypass or gate_degraded enforcement event in the audit.