npm - @mrciphersmith/keryx - Versions diffs - 0.2.10 → 0.2.12 - Mend

@mrciphersmith/keryx 0.2.10 → 0.2.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.md CHANGED Viewed

@@ -6,52 +6,94 @@
 <p align="center"><strong>One project-local brain for your AI agents and your team.</strong></p>
+<p align="center">
+  Version-controlled repository context for Codex, Claude, Cursor,<br>
+  and any other AI coding agent.
+</p>
 <p align="center">
   <a href="https://github.com/MrCipherSmith/keryx/actions/workflows/ci.yml"><img src="https://github.com/MrCipherSmith/keryx/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.npmjs.com/package/@mrciphersmith/keryx"><img src="https://img.shields.io/npm/v/@mrciphersmith/keryx.svg" alt="npm"></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
-  <a href="package.json"><img src="https://img.shields.io/badge/version-0.2.0-blue.svg" alt="Version"></a>
 </p>
-`keryx` is a CLI that installs a small `.metaproject/` workspace into any codebase, giving AI agents and developers one shared, versioned source of context: a code graph, an architecture wiki, normalized health and test reports, long-term memory, and agent skills. Instead of context scattered across scratchpads, CI logs, and IDE rule files that never agree, everything lives in one git-diffable place that both humans and agents read from.
-The core is deterministic, local, and offline — with zero runtime dependencies. Every model-backed or precision feature is strictly opt-in, so a fresh install behaves identically whether or not you enable them.
-> **Model assets are optional.** Tree-sitter parsing uses downloadable grammars
-> that are **not bundled and not required**; when a grammar is absent, the graph
-> falls back to its deterministic resolver.
->
-> **Two model-backed features are off in a way a download will not fix.**
-> Semantic memory search and the ML security detectors have no runtime shipped —
-> the ONNX stack was removed for weight, so their runtime identifiers are empty
-> strings (`src/security/detect/index.ts`, `src/memory/config.ts`). Re-enabling
-> them means editing those constants and installing a transformers.js-API
-> package, not supplying an asset. Both run on their deterministic floor
-> instead: lexical recall, and regex plus entropy.
-Most things degrade rather than break, but not everything. `keryx ctx rg` exits
-non-zero without `ripgrep` on `PATH` rather than falling back, and the
-model-backed commands — `test suggest`, `flow plan`, `memory reflect --narrate`,
-`health explain --narrate` — have no deterministic mode and exit non-zero
-without a credential. `wiki enrich` is the exception that degrades: it exits 0
-and marks pages skipped.
-## What this removes
-An agent starts every task by re-deriving what your repository already knows.
-Which files relate to which. What the architecture decision was and why. Which
-tests cover the thing being changed. What broke last time someone tried this.
+`keryx` turns what agents keep rediscovering about your repository into durable
+Markdown and JSON under `.metaproject/`: code relationships, architecture,
+project memory, relevant tests, quality signals, agent skills, and task state.
+Every agent and every teammate reads the same context, and it is reviewed in a
+diff like the rest of the code.
+The core is deterministic, local, offline, and has no required runtime
+dependencies. keryx does not take your coding agent away and does not make
+engineering decisions for you — it gives every agent the same project context
+instead of letting each one reconstruct the repository from scratch.
+It also ships **an agent runtime of its own**, built directly on that context:
+durable sessions, an allow/ask/deny policy engine, kernel-enforced sandboxing,
+child agents and evidence-gated completion. Keep using Codex, Claude or Cursor,
+run `keryx shell`, or do both — they all read the same project brain.
+```bash
+npm install -g @mrciphersmith/keryx
+cd path/to/your-project
+keryx init --yes
+keryx gdgraph build
+```
+Local-first · deterministic core · offline by default · MIT
+## Why keryx
+An agent starts every task by re-deriving what your repository already knows:
+- which files and symbols are connected;
+- what a change is going to affect;
+- which architectural decision constrains it, and why;
+- which tests verify the behaviour;
+- what broke the last time someone tried this;
+- which project rules apply.
 That work is repeated per task, per agent, per person — and the answers land in
 scratchpads, CI logs and IDE rule files that never agree with each other.
-keryx materializes those answers **into the repository**, as Markdown and JSON
-under `.metaproject/`, and points every agent at one index. The context is
-versioned with the code, readable in a diff, and shared by the humans and the
-agents alike.
+keryx materializes those answers **into the repository**. The context is
+versioned with the code, readable in a diff, and shared by humans and agents
+alike, whichever agent runtime happens to be open.
+## What you get
+| Need | keryx provides |
+|------|----------------|
+| Understand a change | Dependency and call graph, symbol/concept lookup, affected-set blast radius |
+| Recover project intent | Architecture wiki with grounded retrieval and code↔wiki backlinks |
+| Avoid repeating an investigation | Long-term project memory: lessons, decisions, constraints, known mistakes |
+| Choose what to verify | Related tests for a file, changed-scope runs, coverage-map test impact analysis |
+| Judge readiness | Normalized health reports and a quality gate over lint, types, tests, coverage, complexity |
+| Coordinate work | Versioned task flows, managed review packages, generated agent skills |
+| Keep agents inside boundaries | Deterministic secret / PII / prompt-injection scanning, redaction, policy gate, OS sandbox |
+| Run an agent at all | A first-party harness on top of all of the above: durable sessions, allow/ask/deny policy, child agents, evidence-gated completion |
+## A typical agent workflow
-### What it looks like when it works
+One task, one repository, no re-exploration:
-Real output, from a real run on [express](https://github.com/expressjs/express)
-— cloned fresh, four commands, nothing edited:
+```bash
+keryx gdgraph affected src/payments/retry.ts   # what a change here touches
+keryx wiki ask "How are payment retries designed?"
+keryx memory search "payment retry"            # decisions and past failures
+keryx test related src/payments/retry.ts       # the verification scope
+keryx health run --changed                     # normalized quality result
+```
+The agent gets structural context, architectural intent, previous decisions, the
+tests that matter, and a normalized health result — without reconstructing any of
+it by reading files at random.
+### What it looks like on a real repository
+Real output from a fresh clone of
+[express](https://github.com/expressjs/express) — four commands, nothing edited:
 ```console
 $ keryx init --yes
@@ -78,208 +120,244 @@ $ keryx gdgraph affected lib/express.js
 - index.js
 ```
-That last answer — *what breaks if I change this* — is the one an agent
-otherwise spends a dozen file reads guessing at, and gets wrong on the files
-that matter most.
-### Is this for you?
-**Probably not, if:**
-- **you want a hosted service.** There is no server, no account, no dashboard in
-  the cloud. If nothing runs on your machine, nothing runs.
-- **you are on Linux and need the network allowlist.** The domain allowlist,
-  credential masking and TLS termination are macOS-only and **refuse** to run on
-  Linux rather than quietly doing less. Filesystem containment and network
-  on/off work on both.
-- **you need remote approvals today.** `keryx serve` exists, but a turn whose
-  policy decision is `ask` terminates in a recorded denial. Approvals are not
-  implemented yet.
-- **you want it to think for you.** keryx does deterministic mechanics — scan,
-  graph, score, checksum. The judgement stays with the agent and with you.
-**Probably yes, if** you run agents against a repository you care about, more
-than once, and you have noticed them rediscovering the same things.
-## Quick Start
-**Requirements:** `git` and `bun` (>= 1.1.0). Code search (`keryx ctx rg` and the
-agent's `search_code` tool) additionally requires [ripgrep](https://github.com/BurntSushi/ripgrep)
-(`rg`) on `PATH` — install it with `brew install ripgrep` (macOS) or `apt install ripgrep`
-(Debian/Ubuntu). Without it, code search is unavailable and the harness falls back to
-reading files directly.
-### Install / update (global)
-```bash
-npm install -g @mrciphersmith/keryx
-```
-> **The package is scoped, and the scope matters.** The unscoped name `keryx` on
-> npm belongs to [an unrelated project](https://github.com/actionhero/keryx) —
-> `npm install -g keryx` installs a different program. The executable this
-> package installs is still called `keryx`.
+That last answer — *what breaks if I change this* — is exactly the context the
+affected graph supplies deterministically, in one command.
-Or use the managed installer, which lays out `~/.keryx/keryx` with a wrapper at
-`~/.local/bin/keryx`. Re-run either command to upgrade.
-```bash
-# curl (short)
-curl -fsSL https://raw.githubusercontent.com/MrCipherSmith/keryx/main/install | bash
+### What lands in your repository
-# bun (short) — pipe into bun (Bun cannot run remote https://…/file.ts as entrypoint)
-curl -fsSL https://raw.githubusercontent.com/MrCipherSmith/keryx/main/install.ts | bun -
+```text
+.metaproject/
+├── index.md              # the routing index every agent reads first
+├── wiki/                 # architecture, domain models, decisions, flows
+├── memory/               # lessons, decisions, constraints, known mistakes
+├── skills/               # bundled agent skills and routing
+├── project-skills/       # skills generated from your own modules
+├── rules/                # your AGENTS.md / CLAUDE.md as project rules
+├── data/gdgraph/         # graph artifacts, module map, query results
+├── data/testing/         # test context, related tests, normalized reports
+├── data/health/          # normalized health artifacts and trends
+└── flows/                # task flows with frozen acceptance criteria
 ```
-Pure Bun without the `curl` binary:
+All Markdown and JSON. All diffable. All yours. And readable as a dashboard when
+a human wants to look at it (`keryx dash`):
-```bash
-bun -e 'await Bun.spawn(["bash","-s"],{stdin:await fetch("https://raw.githubusercontent.com/MrCipherSmith/keryx/main/install"),stdout:"inherit",stderr:"inherit"}).exited'
-```
+<p align="center">
+  <img src="docs/assets/dashboard.png" alt="The keryx dashboard: health score, attention signals, and the enabled modules" width="880">
+</p>
-Both paths run `scripts/install.sh --global` under the hood. Ensure `~/.local/bin` is on `PATH`:
+## The agent harness
-```bash
-export PATH="$HOME/.local/bin:$PATH"
-```
+This is the half that makes the other half worth having.
-### Interactive shell (TUI agent harness)
+> **The agent is ephemeral; the project brain is durable.**
-Bare `keryx` is the **CLI** (lists commands / usage). The interactive TUI agent
-harness starts only with **`keryx shell`**:
+keryx ships its own agent runtime — not a wrapper around someone else's. It owns
+the execution loop, the tool registry, permissions, sessions, subagents and
+completion gates, and it assembles its context from the same `.metaproject/`
+graph, wiki, memory, rules, skills, testing, health and security that every other
+agent reads. That combination is the point: an agent that starts a turn already
+knowing the repository, and that cannot end one by asserting it is done.
 ```bash
-keryx              # CLI help — metaproject commands
-keryx shell        # OpenTUI + agent harness (default UI)
+keryx shell                                   # TUI + agent (default UI)
+keryx shell --no-tui                          # classic readline shell
+keryx shell --chat                            # chat without tools
+keryx shell --provider ollama --model llama3.1:latest
 ```
-Useful `shell` flags:
-| Flag | Effect |
-|------|--------|
-| *(default)* | TUI + agent |
-| `--no-tui` | classic readline shell |
-| `--chat` | chat without tools (readline) |
-| `--agent` | agent mode explicitly |
-| `--provider <p> --model <m>` | skip the provider/model picker |
-| `--base-url <url>` | custom provider endpoint |
+<p align="center">
+  <img src="docs/assets/shell.png" alt="keryx shell: the TUI agent harness with session commands and a project sidebar" width="880">
+</p>
-Examples:
+What is in it today:
+- **Provider-neutral loop.** Anthropic, Ollama, OpenRouter and Grok, plus an
+  offline fake provider for deterministic runs. Swapping the model does not
+  change the loop, the tools or the policy.
+- **Durable sessions, per project.** Append-only event log on disk, resume across
+  a process restart, branching, and context compaction that keeps the archive.
+  `/resume`, `/compact`, `/new` — and `keryx sessions list|export`.
+- **A policy engine with three answers, not two.** `allow`, `ask`, `deny` over
+  paths, commands, tools, network and resources. Filesystem mutation is
+  path-checked, security-scanned, approval-bound and recorded as evidence.
+- **Kernel-enforced containment underneath.** The OS sandbox sits *below* the
+  policy engine — Seatbelt on macOS, bubblewrap on Linux — with network off/on,
+  and on macOS a loopback domain allowlist, credential masking behind a per-run
+  sentinel, and opt-in TLS termination. It fails closed when a launcher or a
+  posture is missing rather than quietly doing less.
+- **Child agents with budgets.** Dispatch over the canonical
+  `subagent-dispatch`/`subagent-result` contracts, token budgets per child,
+  bounded parallel scheduling, and a fleet monitor (`keryx agents monitor`).
+- **Completion you can audit.** An evidence ledger backs the completion gate: a
+  run that cannot produce the evidence its flow requires does not get to claim
+  it finished.
+- **Deterministic replay.** Recorded provider and tool fixtures replay a run with
+  no network and no mutation, and report where the state transitions diverge.
+- **Four doors, one loop.** The CLI (`keryx harness run|exec|extension|wave`),
+  JSONL/RPC, the TUI, and the loopback HTTP entry (`keryx serve`) all drive the
+  same execution loop and the same session state.
+You do not have to use it. Every module above works with Codex, Claude Code or
+Cursor driving them instead. But if you want an agent that is native to the
+project rather than a guest in it, it is here and it is the same install.
+## Core capabilities
+Grouped by what you are trying to do, not by internal module layout.
+**Understand the codebase**
+- **gdgraph** — language-aware dependency graph for TypeScript/JavaScript, Java
+  (Maven/Gradle) and Python: cycle and orphan queries, concept and symbol lookup,
+  shortest paths, affected-set blast radius, PageRank repo map, and an optional
+  tree-sitter symbol/call graph.
+- **gdwiki** — a Markdown architecture wiki with hierarchical indexes, link
+  checks, code↔wiki backlinks, and grounded `wiki ask` retrieval.
+- **gdctx** — compact command, search and file-read output, so agents keep raw
+  logs out of their context window while the full output stays on disk.
+**Preserve knowledge**
+- **memory** — long-term project memory with indexing, lexical search, dedup and
+  bitemporal validity, so a lesson learned once stays learned.
+- **gdskills** — bundled and project-generated agent skills with routing,
+  verification, learning from reviews, and export to different agent runtimes.
+**Change with confidence**
+- **testing** — testing context, related-test selection, changed-scope runs, and
+  an opt-in coverage-map Test Impact Analysis.
+- **health** — normalized reports from TypeScript, tests, audit, complexity,
+  coverage and lint (optional SonarQube), plus a quality gate and trends.
+- **review** — managed review packages under `.metaproject/reviews/`, standalone
+  or attached to a flow, so review findings become durable project artifacts.
+**Operate agents**
+- **tasks** — an agent-first Task Manager driven by `keryx flow`, with frozen
+  acceptance criteria and status gates.
+- **security** — deterministic secrets / PII / prompt-injection / egress
+  scanning, redaction, and a policy gate at agent write seams, with a committed
+  evaluation corpus.
+- **mcp** — an opt-in [Model Context Protocol](https://modelcontextprotocol.io)
+  server exposing read-only module services to agents.
+**Run agents inside boundaries**
+- **harness** — the first-party agent runtime described above: provider-neutral
+  loop, durable sessions, policy engine, child agents, evidence-gated completion,
+  deterministic replay.
+- **sandbox** — kernel-enforced containment under the policy engine
+  (`keryx harness exec`), with filesystem boundaries, network posture and, on
+  macOS, a domain allowlist with credential masking.
+- **remote entry** — `keryx serve`, a loopback-bound authenticated HTTP door into
+  the same harness, so a bot or a browser workspace can drive a run.
+`keryx modules` toggles modules by manifest key; `keryx status` shows what is
+enabled. Nine modules are on after `init`; `mcp` is opt-in.
+## Quick start
+**Requirements:** `git` and `bun` (>= 1.1.0).
 ```bash
-keryx shell --provider ollama --model llama3.1:latest
-keryx shell --no-tui
-keryx shell --chat
-```
-### First project setup
+npm install -g @mrciphersmith/keryx
-```bash
 cd path/to/your-project
 keryx init
 keryx gdgraph build          # code dependency graph
 keryx test analyze           # testing context report
 keryx health run --changed   # normalized health report
 keryx dash                   # human admin dashboard
 ```
-`keryx init` creates a `.metaproject/` workspace and connects your existing
+`keryx init` creates the `.metaproject/` workspace and connects your existing
 `AGENTS.md` / `CLAUDE.md` entrypoints to it, so agents are routed to the right
-module automatically. See the
-[onboarding guide](docs/docs/onboarding.md) for the full first-run walkthrough
-and alternative install paths (managed curl installer, or project-local).
-## Core Ideas
-A few pieces of jargon, defined once:
-- **gdgraph** — a *code graph*: language-aware dependency and import graph of your
-  repo (TypeScript/JavaScript, Java via Maven/Gradle, and Python), with
-  cycle/orphan queries, concept and symbol lookup, call-aware impact analysis,
-  shortest paths, and a PageRank-ranked repo map.
-- **gdctx** — *compact context output*: runs commands, searches, and file reads
-  and stores condensed results so agents don't flood their context with raw logs.
-- **gdwiki** — an *architecture wiki*: a Markdown knowledge base of domain
-  models, decisions, and flows, with grounded `wiki ask` retrieval, hierarchical
-  indexes, and backlinks between wiki pages and code.
-- **gdskills** — *agent skills*: bundled and project-generated skills that route
-  agents to the right workflow, plus verification and export to different runtimes.
-## Modules
-`keryx` itself is the toolkit core (`init`, `status`, `update`, `dashboard`,
-`rules`, `standard`, `agents`) and manages the `.metaproject/` structure. It
-ships these modules:
-- **gdgraph** — code dependency graph with language-aware import resolution (TypeScript/JavaScript, Java Maven/Gradle, Python); concept search, file/symbol paths, affected-set blast radius, PageRank repo map, and an optional tree-sitter symbol/call graph.
-- **gdctx** — compact command / search / read output plus opt-in routing guards for supported agent runtimes.
-- **gdwiki** — Markdown project wiki with hierarchical indexes, backlinks, link checks, collection, and grounded retrieval.
-- **gdskills** — bundled and generated agent skills with routing, verification, learning, and export.
-- **health** — normalized code-health reports from TypeScript, tests, audit, complexity, coverage, and lint (optional SonarQube).
-- **testing** — testing context, related-test selection, changed-scope runs, and an opt-in coverage-map Test Impact Analysis.
-- **memory** — long-term Markdown project memory with indexing, lexical search, dedup and bitemporal validity. The embedding seam exists but ships with no runtime — see the note above.
-- **tasks** — an agent-first Task Manager driven by `keryx flow` for issue/task lifecycle tracking.
-- **security** — deterministic secrets / PII / prompt-injection / egress scanning, redaction, and a policy gate at agent write seams.
-- **mcp** — opt-in [Model Context Protocol](https://modelcontextprotocol.io) server exposing read-only module services to agents. A real module, but **off by default** — the nine above are on after `init`, this one is not.
-`keryx modules` toggles modules by manifest key. Two caveats worth knowing:
-`security` is enabled by default but is **not** in that command's module list, so
-it cannot be toggled there; and toggling any module currently drops an enabled
-`mcp` from the manifest.
-**`review` and `serve` are commands, not modules.** They have no manifest entry
-and are not toggleable — `keryx review` writes managed review packages under
-`.metaproject/reviews/`, and `keryx serve` is the loopback HTTP entry described
-below. Earlier versions of this README listed them alongside the modules; that
-conflated three different things.
-Two cross-cutting commands improve agent startup and routing:
-- `keryx orient` emits or installs a compact graph + wiki orientation block at
-  turn start for Claude, Codex, and Cursor.
-- `keryx agents bootstrap` installs the Metaproject discovery rule in supported
-  global agent entrypoints.
-## How Agents Use It
+module automatically.
-After `init`, agents follow the root `AGENTS.md`/`CLAUDE.md` pointer to
-`.metaproject/index.md`, which routes them to the right module. For example:
+> **The package is scoped, and the scope matters.** The unscoped name `keryx` on
+> npm belongs to [an unrelated project](https://github.com/actionhero/keryx).
+> Install `@mrciphersmith/keryx`; the executable it installs is called `keryx`.
-```text
-Find the files related to payment retry handling, explain the relationships,
-and use the keryx tools for context discovery before broad raw search.
-```
+Alternative install paths — the managed installer (`~/.keryx` with a wrapper in
+`~/.local/bin`), project-local installs, and running from source — are in the
+[onboarding guide](docs/docs/onboarding.md).
-The agent is directed to use `gdgraph` for navigation, `gdctx` for large output,
-`gdwiki` and `memory` for decisions and history, and `flow` for managed work —
-only for the modules you've enabled.
+Bare `keryx` prints the CLI surface; `keryx shell` starts the agent harness
+described [above](#the-agent-harness).
-For an always-current starting map, install the optional orientation hook:
+## Agent integrations
-```bash
-keryx orient install-hook --runtime codex
-```
+| Runtime | Integration |
+|---------|-------------|
+| Claude Code | `CLAUDE.md` routing, orientation hook, security hooks, MCP server |
+| Codex | `AGENTS.md` routing and orientation hook |
+| Cursor | Rules/orientation, security hooks, MCP server |
+| Any other agent | Repository-local Markdown/JSON artifacts under `.metaproject/` |
-For traceable review work, create a standalone review package or attach one to
-an existing flow:
+After `init`, agents follow the root `AGENTS.md`/`CLAUDE.md` pointer to
+`.metaproject/index.md`, which routes them to the right capability. Two commands
+sharpen that routing:
 ```bash
-keryx review start --target branch --ref feature/example
-keryx review attach --flow 001 --target pull-request --ref 42
+keryx orient install-hook --runtime codex   # graph + wiki map at turn start
+keryx agents bootstrap install --runtime claude
+keryx mcp install --runtime cursor          # opt-in read-only MCP server
 ```
-For agents that speak the Model Context Protocol, `keryx mcp install` wires a
-read-only MCP server into Cursor or Claude in one command (opt-in, off by
-default). See the [architecture doc](docs/docs/architecture.md) for the module
-data flows.
+## Requirements and compatibility
+| Requirement | Status |
+|-------------|--------|
+| Bun | >= 1.1.0 |
+| Git | Required |
+| ripgrep | Required only for `keryx ctx rg` and the agent's `search_code` tool |
+| Model provider credential | Required only for the optional AI commands below |
+| macOS | Full support, including the complete policy sandbox |
+| Linux | Full core support; filesystem containment and network on/off (needs `bubblewrap`) |
+| Windows | Core CLI is not verified in CI; the OS sandbox is macOS/Linux only |
+| CI | Ubuntu and macOS runners on every push |
+## Optional AI features
+The graph, wiki, memory, testing, health, task, review and security workflows are
+deterministic and run with no model provider at all. A small set of commands adds
+model-generated suggestions or narration on top, and those require a configured
+credential:
+- `keryx test suggest <file>` — a test plan matching your project's frameworks
+- `keryx flow plan <id>` — task breakdown for a flow
+- `keryx memory reflect --narrate` — a narrative summary of project memory
+- `keryx health explain <target> --narrate` — a readable explanation of a health result
+- `keryx wiki enrich` — model-written wiki pages (skips pages without a credential)
+Semantic embeddings and ML security classifiers are not bundled in the current
+release. Memory search uses lexical retrieval, and security scanning uses
+deterministic rules plus entropy analysis — both fully functional on that floor.
+The seams exist for the model-backed variants when they ship.
-## Remote Entry (opt-in, off by default)
+Tree-sitter grammars for the symbol/call graph are downloadable and optional; the
+graph falls back to its deterministic resolver when a grammar is absent.
-`keryx serve` is a second door into the same agent harness `keryx shell` uses —
-a loopback-bound HTTP listener, so a Telegram bot or a browser workspace can
-drive a run without a second agent runtime or a second owner of session state.
+## Current limitations
+| Limitation | Impact | Alternative |
+|------------|--------|-------------|
+| No remote approval transport | A remote turn whose policy decision is `ask` ends in a recorded denial | Run approval-requiring turns locally |
+| Domain allowlist is macOS-only | Domain-level egress policy, credential masking and TLS termination refuse to run on Linux rather than silently doing less | Filesystem containment and network on/off work on both |
+| No bundled embedding runtime | No semantic ranking in memory search | Lexical memory search remains fully available |
+| ripgrep is external | `keryx ctx rg` needs `rg` on `PATH` | Install ripgrep, or let the agent read files directly |
+| Model commands need a credential | The five commands above exit non-zero without one | Everything else runs deterministically offline |
+Full detail, including known defects and platform caveats:
+[limitations](docs/docs/limitations.md).
+## Remote entry (opt-in, off by default)
+`keryx serve` is a second door into the same agent harness `keryx shell` uses — a
+loopback-bound HTTP listener, so a Telegram bot or a browser workspace can drive
+a run without a second agent runtime or a second owner of session state.
 ```bash
 keryx serve config init          # write the listener config
@@ -288,27 +366,18 @@ keryx serve                      # bind 127.0.0.1 and listen
 keryx serve status --json        # configuration state
 ```
-It is **off unless you configure it**, binds loopback unless you pass
-`--acknowledge-non-loopback`, and authenticates *before* routing — so an
-unauthenticated caller cannot tell a known path from an unknown one. Routes
-today: `GET /v1/status`, `GET /v1/projects`, `POST /v1/turns` with
-per-project idempotency keys, and `GET /v1/turns/<id>` for the durable record
-and its server-sent-event stream.
-Two boundaries worth knowing before you point anything at it:
+It is off unless you configure it, binds loopback unless you pass
+`--acknowledge-non-loopback`, and authenticates *before* routing, so an
+unauthenticated caller cannot tell a known path from an unknown one. The remote
+policy profile may never be weaker than the local one — it is compared on every
+turn and a weaker profile is refused. See
+[drive keryx remotely](docs/docs/guides/drive-keryx-remotely.md) for routes and
+setup.
-- **The remote policy profile may never be weaker than the local one**; it is
-  compared on every turn, and a weaker profile is refused rather than accepted.
-- **Approvals are not implemented yet.** A turn whose policy decision is `ask`
-  terminates in a *recorded denial* — it is never auto-approved.
+## CI integration
-`keryx projects` manages the user-global registry these routes address projects
-by; `keryx init` registers a project into it.
-## CI Integration
-`keryx` is designed so CI can publish normalized, committable artifacts that
-humans and agents read later:
+CI can publish normalized, committable artifacts that humans and agents read
+later:
 ```bash
 keryx gdgraph build
@@ -317,28 +386,27 @@ keryx health run --changed
 keryx dashboard build
 ```
-Use `keryx health gate --strict-warn` to fail a job on the normalized health
-gate instead of parsing raw linter/test logs, and `keryx security eval --corpus
-all` to fail on any detector breaching its committed false-negative threshold.
+`keryx health gate --strict-warn` fails a job on the normalized health gate
+instead of parsing raw linter/test logs, and `keryx security eval --corpus all`
+fails on any detector breaching its committed false-negative threshold. See
+[run keryx in CI](docs/docs/guides/run-in-ci.md).
 ## Documentation
-Full developer documentation — reverse-engineered from the source — lives under
-[docs/docs/](docs/docs/):
+Full documentation site: **<https://mrciphersmith.github.io/keryx/>**
 - **[Onboarding](docs/docs/onboarding.md)** — install paths, first-run walkthrough, the build loop.
 - **[Architecture](docs/docs/architecture.md)** — the four-layer pattern, invariants, cross-module data flows.
 - **[Module reference](docs/docs/modules.md)** — one section per module: purpose, CLI surface, mechanics, data paths.
-- **[CLI reference](docs/docs/cli-reference.md)** — every command, subcommand, and flag.
+- **[CLI reference](docs/docs/cli-reference.md)** — every command, subcommand, flag and exit code.
 - **[Workspace & lifecycle](docs/docs/workspace-and-lifecycle.md)** — the `.metaproject/` contract and `init`/`update` lifecycle.
-- **[Changelog](CHANGELOG.md)** — what has landed since `v0.1.0`, including a
-  standing list of known gaps.
+- **[Limitations](docs/docs/limitations.md)** — known gaps, platform caveats, and what to do instead.
+- **[Changelog](CHANGELOG.md)** — what has landed since `v0.1.0`.
 Run `keryx <command> --help` (or `keryx` with no arguments) for the live command
 surface.
-## Local Development
+## Local development
 ```bash
 bun ./src/cli.ts init
@@ -346,6 +414,8 @@ bun ./src/cli.ts status
 bun run check      # typecheck + tests
 ```
+Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 MIT. See [LICENSE](LICENSE).

package/dist/cli.js CHANGED Viewed

@@ -48183,8 +48183,8 @@ Usage:
 // package.json
 var package_default = {
   name: "@mrciphersmith/keryx",
-  version: "0.2.10",
-  description: "CLI-first metaproject workspace for AI agents, code graph, project memory, health reports, testing context, wiki, skills, and task flows.",
+  version: "0.2.12",
+  description: "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   private: false,
   publishConfig: {
     access: "public"
@@ -48197,15 +48197,21 @@ var package_default = {
   },
   keywords: [
     "ai-agents",
-    "agent-tooling",
+    "coding-agents",
+    "agent-harness",
+    "agent-context",
+    "repository-context",
     "code-graph",
     "project-memory",
+    "test-impact-analysis",
     "developer-tools",
-    "bun",
-    "typescript",
+    "model-context-protocol",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "codex",
     "cli",
-    "knowledge-base",
-    "multi-agent"
+    "bun"
   ],
   bin: {
     keryx: "./dist/cli.js"

package/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "@mrciphersmith/keryx",
-  "version": "0.2.10",
-  "description": "CLI-first metaproject workspace for AI agents, code graph, project memory, health reports, testing context, wiki, skills, and task flows.",
+  "version": "0.2.12",
+  "description": "Version-controlled project context for AI coding agents: code graph, architecture wiki, project memory, relevant tests, quality signals, and task flows.",
   "private": false,
   "publishConfig": {
     "access": "public"
@@ -14,15 +14,21 @@
   },
   "keywords": [
     "ai-agents",
-    "agent-tooling",
+    "coding-agents",
+    "agent-harness",
+    "agent-context",
+    "repository-context",
     "code-graph",
     "project-memory",
+    "test-impact-analysis",
     "developer-tools",
-    "bun",
-    "typescript",
+    "model-context-protocol",
+    "mcp",
+    "claude-code",
+    "cursor",
+    "codex",
     "cli",
-    "knowledge-base",
-    "multi-agent"
+    "bun"
   ],
   "bin": {
     "keryx": "./dist/cli.js"