Kherad boundary

Type: agentic-system-analyses/types/agentic-system-boundary.md

Boundary and evidence

Kherad is in scope as a self-hosted knowledge system with model-driven drafting, editing, knowledge compilation and question answering. Its intended users are organizational authors, reviewers and readers, rather than developers embedding a standalone retrieval library. The target is the shipped application, including its human interfaces and persistence services; the Next.js client and Fastify server are not excluded enclosing hosts. The boundary is whole-system because it includes the paths that produce source material, compile it, admit changes, preserve state and consume that state later. This is a scope declaration supported by entry-point tracing, not a claim that every implementation file has already been exhaustively reviewed. [SRC-1] README.md, apps/api/src/index.ts, apps/api/src/routes/indexer.ts, apps/api/src/agents/indexer/run.ts, apps/web/src/components/chat/bundle-chat.tsx.

The author's stated purpose is:

A Notion-like wiki for non-technical teams, backed by real git commits and a merge-request review workflow — plus AI agents that write the first draft for you. --- README.md

The API entry point creates the database and Git engine and registers page, ingest, review, search, compilation, chat, specialist-session, skill and MCP routes. The compilation route invokes the indexer, whose model receives source/delta context and tools, then stages compiled documents and mirrored sources on an agent branch and opens or updates a merge request. The review route checks review permission and invokes a subtree-scoped squash merge, followed by search synchronization. These shipped responsibilities are included; neither the review gate nor state persistence is attributed to an unspecified external host. [SRC-1] apps/api/src/index.ts, apps/api/src/routes/indexer.ts, apps/api/src/agents/indexer/run.ts, apps/api/src/routes/merge-requests.ts.

Model dependence is executable, not merely a documentation promise:

const agent = new Agent({ id: "okf-indexer", name: "OKF Indexer", instructions: indexerInstructions(bundle), model: buildModel(settings, "indexer"), tools: createIndexerTools({ db, git, bundle, pending }), }); --- apps/api/src/agents/indexer/run.ts

The compilation prompt supplies maintenance instructions for incremental updates, source references, concept files, a root directory and an update log. Specialist sessions additionally load stored skills, page mentions, quotations and optional MCP tools into model instructions/tools. Chat constructs a model agent with tools that read compiled content from the bundle's default branch and search its indexed state. The web chat reloads stored thread messages and resubmits subsequent turns. Wiki rendering separately reloads Git content. These are retained-content consumers inside the target. [SRC-1] apps/api/src/agents/indexer/prompt.ts, apps/api/src/agents/skills.ts, apps/api/src/routes/agent-sessions.ts, apps/api/src/routes/chat.ts, apps/api/src/agents/chat/tools.ts, apps/api/src/agents/search-tools.ts, apps/web/src/components/chat/bundle-chat.tsx, apps/web/src/lib/wiki-render.ts.

For example, the chat read tool selects persisted content rather than receiving an externally prepared document body:

const bytes = await git.getFileAtRef(bundle.defaultBranch, ${okfPrefix}/${validPath}); --- apps/api/src/agents/chat/tools.ts

Human review is one admission path, not an assumption that every default-branch change is reviewed. The shipped remote synchronization routes also belong to the boundary; the raw-bundle remote route explicitly describes direct default-branch replacement and invokes reconciliation. Its presence prevents treating the README's review language as a universal enforcement claim. [SRC-1] apps/api/src/routes/bundle-remote.ts, apps/api/src/routes/merge-requests.ts, packages/db/src/schema.ts.

Tracked-root coverage

The table accounts for every top-level tracked file or directory at the frozen commit. “Included” means available to the analysis within SRC-1. Initial inspection is bounded: paths named as not yet inspected are not access gaps or silent exclusions. They remain in scope for later implementation tracing.

Frozen evidence and external limits

The sole frozen source is the acquired Git repository at full commit 2a8d6992b87a33760688e1f956653c21a6292294; checkout HEAD was checked against that pin. The analysis cutoff is 2026-11-08, the supplied run date. Applicability is limited to this revision, not later upstream changes. No extra repository, web page, deployed database, user knowledge corpus or execution trace is registered.

The overall tier is code-grounded. Source inspection supplies implementation evidence; README and prompt text supply doctrine/design. Tests supply inspectable assertions, not observed run results. No target code, tests or examples were executed, so this boundary supports neither measured answer quality nor demonstrated recovery, throughput, security or operational reliability.

External dependencies include Postgres/pgvector, the Git storage implementation, Fastify/Next.js, Mastra and AI SDK adapters, Docling, configured model/embedding/OCR/transcription services, remote Git servers and session-selected MCP services. Dependency declarations and call sites are included; dependency implementation repositories, actual credentials/configurations, remote tool behavior and provider outputs are not frozen. This prevents attributing their internal guarantees or real-world availability to Kherad. [SRC-1] docker-compose.yml, apps/api/package.json, packages/core/package.json, apps/ingest/main.py, apps/api/src/routes/agent-sessions.ts. Available but not yet inspected source files are distinguished above from these external evidence limits.

Source register