kyb v0.3.0

kyb v0.3.0 for aarch64-apple-darwin (Apple Silicon), Docker (linux/amd64, linux/arm64) and crates.io. Intel macOS is not supported.

109 commits since v0.2.3, every one reviewed before merge.

Attribution: every write records who made it

Each commit in the canon now carries four trailers: Kyb-Agent, Kyb-Session, Kyb-Workspace, Kyb-Via. The same record is returned as by in history, in the activity ledger and on the Versions tab of the web console, and kyb whoami shows what the current shell would write.

The agent and its session are chosen together from one source and never borrowed from a source that names another agent. via names that source:

• cli: the kyb command read its environment.
• hook: Claude Code called the kyb MCP tools and a decision-free PreToolUse hook supplied the record.
• meta: the MCP client's own call metadata named the conversation (Codex, Antigravity).
• headers: the client sent X-Kyb-Agent / X-Kyb-Session / X-Kyb-Workspace itself.

Workspace names stay inside the repository (a repository-relative path, never an absolute one). The git author stays kyb.

Boundaries, stated precisely. The cli and hook paths have live evidence from the fleet; the meta formats for Codex and Antigravity are fixture-tested and have not yet been exercised by a live client. There is one via per write, not per field; per-field provenance and "unknown" reasons are deferred. The record is supplied by the caller: it is attribution, not authenticated identity. Commit author metadata is not cryptographic commit signing.

Access: tokens and three roles

A caller presents a bearer token; the server looks it up in a book of principals kept outside the knowledge repository (KYB_AUTH_FILE, on the volume under Compose; a book inside the canon is refused). Roles: read < write < admin. Modes (KYB_AUTH): off as before; compat honours a token when sent and keeps full access for callers without one (rollout on a trusted bind, protects nothing); required admits no one without a token, or the role in KYB_ANON for a public demo. The book is re-read when it changes, so issuing and revoking need no restart. kyb-server auth add|token|revoke|list edits it on the machine that holds it; kyb login|whoami|logout on the client, the token sent through a curl config stream and never on the command line.

A write made with a token is committed under the token's principal; a write without one keeps the service signature and is shown with no author, so nothing is attributed to the owner by default any more. The audit log gains an actor field, including for refused requests. The web console asks for a token on 401 and hides every control the role would be refused. The maintainer's own preview runs auth=off: shipping roles does not mean a deployment enforces them.

Point-in-time search answers from the snapshot, never from a superseded version

--as-of T now selects the version current at T for every key first, then applies the text and metadata predicates. A version already replaced at T never answers, even if nothing newer matched. Knowledge deleted at T' is absent from every snapshot after T' (archived incidents and tasks are not deletions: they stay findable at their last version). A later rewrite with the same text is a new version. Documents and their tombstones are published as one generation, so a reader never sees documents from one commit paired with tombstones from another. The matching set is counted before it is fetched, so no fixed candidate budget truncates it. --history still returns every version; --changed-between keeps its contract.

History index

One index over the whole canon, extended by the commits since, replaces a walk over every commit per question. A card's history was a second per request; it is now served from the index. The start-up walk reports what it skips instead of refusing to start.

Relations

The force-directed topology graph drawn from tags and hosts is gone: no edge in it was something an author wrote. Relations are now derived from what entries actually say and stored nowhere: an incident's or task's knowledge list, a task's parent_task, and internal links in the body ([[key]], [text](key), [text](#/knowledge/key); fenced blocks and inline code are skipped, a key merely mentioned is not a link). Three read endpoints: /knowledge/{key}/related, /places (services and hosts named by incidents, the worst first) and /impact?service=|host=. The console gets a Services tab and a Related section on every card, each row with the reason it is there. Nothing is inferred from tags. An archive note is settled by its own number, and a build consumes only the notes it acted on.

Web console

A redesign to one quiet system: one type scale, one accent, colour only where state demands it; every control checked against the design. Incidents and tasks are attention queues with the reason in the row; Activity is a change ledger showing the whole change; History and Diff are one Versions panel listing every version with everything it changed, who wrote it and from where. Deep links and permalinks, #tag filters, paging at 40, a card that draws before its history arrives, and a browser test that drives every screen and every write a person can make, with block coverage of the UI script gated at 100% in CI. The page is assembled from src/web/css and src/web/js at compile time and served from the binary unless KYB_UI_PATH says otherwise.

Deploy

scripts/deploy.sh installs the exact digest the CI run smoke-tested (published as an artifact only after the smoke passed), keeps a named rollback, waits for a cold start, compares the running image id with the pinned digest's local id, and refuses a stale UI override. The served-page marker identifies a console generation; the pinned image identity identifies the deployed artifact.

Registry and citation

server.json and glama.json describe the MCP server for the registries. CITATION.cff is at 0.3.0 and cites the concept DOI 10.5281/zenodo.22850723; the versioned DOI of this release is added once Zenodo archives it. The 0.2.3 record (10.5281/zenodo.23027682) remains the DOI of 0.2.3 only.

Known, not blocking

Card "ago" labels from a date-only updated_at; kyb query brief output, scores and --help; canon git gc automation; kyb lookup / context / verified_at. The audit deliberately omits the console's polling routes, so it is not a complete traffic record.

Install

brew install alex09x/apps/kyb          # Apple Silicon
cargo install knowyourbusiness --locked  # kyb-server only
docker pull ghcr.io/alex09x/kyb:v0.3.0