`: ``. Keep the source references." | A revision task and a review report for the changed page | | Reorganize | "Research the approved knowledge again and propose a more intuitive directory and title structure. Revise after I confirm." | A structure proposal, then revisions | | Plan a large project | "Plan a knowledge project for ``." | The `context-plan` Skill researches and writes a `PLAN-*.md` for review | ## Updating, evaluating and migrating | You want to | Say | What happens | | --- | --- | --- | | Update | "The sources have moved to ``. Find the affected knowledge and review the updates." | Impact assessment, targeted revisions, a review report | | Evaluate | "Evaluate the current knowledge base with ``, grade each answer on the four-level criteria and give me P50/P90." | An evaluation run with grades and timings | | Migrate | "Research what Context can do, then migrate the current knowledge base …" | See [Migrating an Existing Knowledge Base]() for the full prompt | ## Building and asking | You want to | Say | What happens | | --- | --- | --- | | Build and preview | "Build the knowledge package and documentation site, and give me a local preview." | `context build`, then a local HTTP preview whose URL is checked before it is shared; publishing to hosting needs your separate authorization | | Ask a question | "Using the `` knowledge, how does `` work?" | `context-inspect-search` answers from the knowledge with sources and reports gaps | The commands and Skills behind these requests are listed in [Commands and Skills](). --- ## Sources - note:20261012/usage-practices.md · usage-practices.md L5–L7 - note:20261012/usage-practices.md · usage-practices.md L62–L70 - [context/plugins/context/README.md L33–L40 · 3b0ce0a]() - note:20261012/usage-practices.md · usage-practices.md L62–L72 - note:20261012/usage-practices.md · usage-practices.md L47–L60 - [context/packages/context/docs/guides/package-outputs.md L417–L421 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L1–L30 · 3b0ce0a]() --- ## Migrating an Existing Knowledge Base # Migrating an Existing Knowledge Base If you already have a knowledge base — an LLM Wiki, a set of Skills, a documentation folder — you do not have to start from nothing. Create a Context knowledge workspace, describe the existing base to the Agent, and let it plan the migration up to the work-start report, where you review the approach and decide the batches. ## The migration prompt Once the workspace exists, start with: ```text Research what Context can do, then migrate the current knowledge base: - Location, content and document scope of the current knowledge base: - How it is produced today (scripts, prompts, and so on): - Desired published structure and form: keep it as is, or new requirements - Historical Q&A or an evaluation question set, to show how the knowledge base is used Turn this into a research report, continue up to the work-start report and pause. I will review the approach and plan the batches. ``` The last item matters most: real questions tell the Agent what the knowledge base is *for*, and they become your evaluation set later. ## Bringing the existing material in Existing material can be connected in different ways, depending on whether it should become a source of new articles or stay where it is: - **Document directories** — register a folder of existing documents as a source so its contents are captured and cited. See [Document Directories](). - **Same-repository docs and Skills** — documents and authored Skills already kept in the same repository are registered as an entrance; the originals stay where they are and remain the only place to edit them. See [Same-Repository Docs](). - **External entrances** — content elsewhere that pages should link to, declared in `imports.yaml` without downloading or capturing it. See [External Entrances](). ## Switch over after you have measured Keep the old knowledge base running until the new one is proven. Run the same question set against both and compare quality, time and tool calls, as described in [Evaluating Your Knowledge Base](). --- ## Sources - note:20261012/usage-practices.md · usage-practices.md L47–L60 - [context/packages/context/docs/guides/imports.md L1–L7 · 3b0ce0a]() - [context/packages/context/docs/guides/repo-content.md L1–L5 · 3b0ce0a]() - note:20261012/usage-practices.md · usage-practices.md L73–L75 --- ## Evaluating Your Knowledge Base # Evaluating Your Knowledge Base Answer quality and speed depend on the knowledge — its accuracy, completeness and links to evidence — but also on the model, the runtime, retrieval planning and how tools are executed. A good evaluation compares your knowledge base against an alternative, or against its own earlier version, on real questions, and then uses the run traces to find out *why* answers were slow or wrong. This page is the design guide: follow it, or hand it to an Agent, to plan an evaluation for your own business. The exact grading, statistics and timing rules are in [Evaluation Scoring and Timing Standard](); a complete worked run is [Knowledge Retrieval Benchmark](). ```mermaid flowchart LR set["1 Questions
and guides"] --> freeze["2 Freeze
conditions"] freeze --> run["3 Run and
keep evidence"] run --> grade["4 Blind
grading"] grade --> review["5 Review and
attribute"] review --> report["6 Publish with
limits"] ``` ## Decide what you are measuring - **Grade the final answer the user received.** Ask two things: is the core conclusion correct, and did it deliver what the question asked? Traces explain retrieval, tools and time; the Agent does not have to show its reasoning or retell how it checked. - **Report quality, end-to-end time and visible tool calls separately.** Do not merge them into one score with arbitrary weights. - **You are comparing whole setups.** Even with the same model, knowledge organization, system prompt, tools, permissions and runtime can differ, so not every difference belongs to the knowledge base. - **Say what is out of scope.** Answering with deployed knowledge is one thing; producing and updating the knowledge — its quality, time, review effort and cost — is another, and needs its own evaluation. ## Build and freeze the question set 1. **Sample real user questions.** Keep their wording, necessary context and terms. Follow-ups that belong together can be merged into one frozen input, but never add answer hints, source paths, extra locating words or grading requirements. 2. **Give every question a stable ID and keep its origin.** The input sent to an Agent contains only the user's question — no ID, earlier answer, rubric or reference evidence. 3. **Turn images into faithful text** when they cannot be sent identically to every setup; mark unreadable parts as unknown. Leave out questions that cannot be answered without the missing image, and add them in a later version. 4. **Separate rule explanations, code lookups and live troubleshooting.** Do not quietly add online permissions, deployment versions or real requests the user never gave. 5. **Freeze the list and record its hash.** Questions already used to tune prompts or fill knowledge gaps are a *regression set*; keep unseen *held-out* questions to check that improvements generalize. 6. **Cover the questions people actually ask** — for example locating interfaces and pages, interaction rules, parameters, permissions and roles, versions and call relationships, debugging and environments. ## Write a guide for every question Each question gets its own file with: - the exact test input; - the date it was checked, the source version (a pinned commit) and what is still unchecked; - the confirmed reference facts and the conditions under which the conclusion holds; - what the answer must deliver; - acceptable equivalent wordings, other valid approaches, and what is **not** required; - concrete criteria for each of the four grades, and counterexamples that would overturn a wrong claim; - where the evidence is, which fact it supports, and known gaps. The reference answer is for checking facts. It does not prescribe length, headings, number of citations, tool order or a full chain of proof, and it is not a template to reproduce. A conclusion that stayed inside the Agent's process and never reached the user does not count. When a deciding fact cannot be verified, mark it pending rather than borrowing an earlier assistant's answer or a knowledge page as proof. If a guide later turns out to be incomplete, record the correction with evidence instead of failing every answer that disagrees with the old guide. ## Freeze the comparison conditions Fix, and write down, everything that could change the result: - question text, model and reasoning settings, knowledge and source-code scope, system prompt, tool permissions, region and dates; - whether a setup answers from **knowledge only** or **knowledge plus source checks** — never let only one side read sources without saying so; - cache and long-term memory state, concurrency, run order and number of repeats. Start a new task for every question and send every setup exactly the same text. Grading guides never enter the answering context. The default recommendation is **three runs per question, concurrency one, alternating setup order**, with the order or random seed recorded; state it plainly when you choose otherwise. Each change to the questions, guides or configuration gets a new version and a new results directory; old material is kept, and re-runs never overwrite earlier results. ## Run and keep the evidence For every attempt, keep the start and end timestamps with time zone, task or session IDs and links, the complete final answer, the raw tool events, the status, timing precision and any anomaly. The first progress message is not the answer; even when a platform marks a task done, check that the answer was actually delivered. Keep the original receipts of platform failures, timeouts, cancellations, quota refusals and retries. An extra run is linked to the attempt it repeats; never replace a result with the best of several. If a question needs the user to supply more information, define one multi-turn protocol for every setup and label any ad hoc follow-up or resume. If the Agent under test is configured for a chat channel — for example it assembles reply cards — a direct-call evaluation may still run channel checks and card preparation. To measure answering alone, switch to a reply policy suited to direct calls, or record that overhead separately. ## Grade blind, then review - Give each answer a random alias per question and record the seed. First-pass graders see neither the setup nor the time, tool count or earlier scores. Links or wording inside an answer can still reveal its origin, so call this *limited* anonymity. - Check material errors first, then whether the question was fully answered, and assign one of four grades — or *pending verification* when a deciding fact cannot yet be checked. The rules are in the [standard](). - Review every material error, pending item, partial resolution and borderline call, and spot-check full resolutions. Graders must give reasons someone else can check; length, style, tool order and whether the process is shown are not reasons on their own. - Check grader consistency with separate calibration samples: the same facts in a short and a long version, as a paragraph and as a table, and the same pair shown in swapped order should get the same grade. Without human-labelled samples, call it *internal consistency review*, not human calibration. ## Find the causes Numbers say *that* something is slow or wrong; traces say *why*. Only after grading, reveal which setup produced which answer, then read the raw tool trace and classify each gap: - **Wrong or missing knowledge** — the knowledge base does not cover the fact, or states it wrongly. - **A key condition left out** — for example a component's branch condition, leading to an over-generalized answer. Turn such gaps into revision tasks. - **Search scope misjudged** — for example concluding "nothing calls this" from a partial checkout. - **Inference or generalization error**, or **delivery gap** — the Agent knew it but did not tell the user. - **Evidence unreachable**, **repeated searching**, **channel overhead** or **waiting for startup**. A log supports only the behaviour it actually shows, and correlation is not cause. More tool calls do not mean more care, and faster does not mean more accurate. ## Publish results with their limits Show the four grade counts with their denominator, mean, P50 and P90 time, visible tool calls, and the sample and protocol. Compare on all questions *and* on the subset every setup fully resolved. Link each question to its answer, guide, grading, timings and evidence, and seal the raw package with a manifest and hashes. State everything a reader needs to interpret the numbers: how many times each question ran (a single run says nothing about stability), differences between environments, system prompts, models, versions, dates, concurrency and timeouts, whether the questions had been seen before, how many graders there were and whether they were calibrated, what the timings include, and how any cost figure was estimated. Label every improvement figure as measured, conditional estimate (with its formula and assumptions) or untested direction. ## What the evaluation should produce For the target business: a question document with origins, a separate scoring standard, one guide per question, a collection plan (configurations, repeats, order, timeout, recorded fields), a raw-records directory and a summary report. Freeze the questions and criteria before running any Agent. A new business checks its own sources, question scope, required conditions and counterexamples; it does not reuse another business's factual judgements. ## Have an Agent design it An Agent can draft the whole plan if it reads this page and the standard first. Copy the prompt below, fill in the brackets, and review the result before any run: ```text Read the "Evaluation" group of the Context documentation at https://context4ai.org/context/llms.txt — "Evaluating Your Knowledge Base", "Evaluation Scoring and Timing Standard" and "Knowledge Retrieval Benchmark". Then design an evaluation of [knowledge base or assistant] against [baseline or earlier version] for [business area]. Produce, without running anything yet: 1. A question document: 20–30 real user questions sampled from [where], each with a stable ID, its origin, the frozen input text and its question type. 2. A scoring standard adapted from the documented one: two primary metrics, material errors, four grades and pending verification. 3. One guide per question: checked facts with the pinned source version, required deliverables, acceptable alternatives, what is not required, grade criteria, counterexamples and evidence locations. Mark anything unverified. 4. A collection plan: configurations to freeze, repeats, order or seed, concurrency, timeout, timing events and every field to record. 5. A blind-grading and review plan, and the report outline with its limits. Do not reuse facts from the documentation's examples, do not add hints to the questions, and list every decision you need from me. ``` --- ## Sources - note:20261013/evaluation-method.md · evaluation-method.md L5–L9 - note:20261013/evaluation-method.md · evaluation-method.md L25–L32 - note:20261013/evaluation-method.md · evaluation-method.md L7–L10 - note:20261013/evaluation-method.md · evaluation-method.md L36–L43 - note:20261013/evaluation-method.md · evaluation-method.md L45–L57 - note:20261013/evaluation-method.md · evaluation-method.md L28–L29 - note:20261013/evaluation-method.md · evaluation-method.md L34–L34 - note:20261013/evaluation-method.md · evaluation-method.md L123–L123 - note:20261013/evaluation-method.md · evaluation-method.md L29–L29 - note:20261013/evaluation-method.md · evaluation-method.md L129–L137 - note:20261013/evaluation-method.md · evaluation-method.md L30–L31 - note:20261013/evaluation-method.md · evaluation-method.md L87–L89 - note:20261013/evaluation-method.md · evaluation-method.md L111–L116 - note:20261013/evaluation-method.md · evaluation-method.md L139–L141 - note:20261013/evaluation-method.md · evaluation-method.md L32–L32 - note:20261013/evaluation-method.md · evaluation-method.md L124–L125 - note:20261013/evaluation-method.md · evaluation-method.md L143–L145 - note:20261013/evaluation-method.md · evaluation-method.md L27–L32 --- ## Evaluation Scoring and Timing Standard # Evaluation Scoring and Timing Standard This page is the rulebook referred to by [Evaluating Your Knowledge Base](). Use it as written, or adapt it and say what you changed. It covers how one answer is graded, how grades become rates, and how time and tool calls are measured. [Knowledge Retrieval Benchmark]() applies it. ## Industry methods it draws on The standard borrows ideas from published work. The four grades, sampling and recording conventions are choices made for this project, not an industry-wide standard. | Source | What was borrowed | | --- | --- | | [SimpleQA](https://openai.com/index/introducing-simpleqa/) (OpenAI) | Classify answers as correct, incorrect or not attempted, and count "not attempted" separately so refusals are neither errors nor successes. | | [FACTS Grounding](https://deepmind.google/blog/facts-grounding-a-new-benchmark-for-evaluating-the-factuality-of-large-language-models/) (Google DeepMind) | First judge whether the answer addresses the request, then check its factual grounding — two separate judgements. | | [Demystifying evals for AI agents](https://www.anthropic.com/engineering/demystifying-evals-for-ai-agents) (Anthropic) | Grade an Agent by its outcome rather than a fixed tool order or path; keep the full trace to explain the result. | | [Ragas Factual Correctness](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/factual_correctness/) and [Faithfulness](https://docs.ragas.io/en/stable/concepts/metrics/available_metrics/faithfulness/) | Distinguish "agrees with the reference facts" from "agrees with the retrieved material": material can be stale or miss a condition, so faithfulness is not correctness. | | [Judging LLM-as-a-Judge with MT-Bench and Chatbot Arena](https://arxiv.org/abs/2306.05685) | Model judges show position, verbosity and self-preference bias; swap order, anonymize and check with calibration samples. | | Nearest-rank percentile | P90 is the ⌈0.9 × n⌉-th sorted sample, so the figure is always a real, checkable run. | ## Two primary metrics and material errors | Metric | What is judged | Recorded value | | --- | --- | --- | | Core-conclusion correctness | Do the key conclusions given hold within the question's scope? Is a condition missing that makes them misleading? | correct / material error / no gradable conclusion / pending | | Request fulfilment | Was what the user asked for actually delivered? Judged only against the question and its necessary context. | full / partial / not met / pending | Material errors are recorded separately as yes, no or pending. For a yes, record the exact claim, the evidence against it and its effect on the user's judgement or action. Any one of these, once confirmed, is a material error: 1. the core conclusion is wrong; 2. a key recommendation would lead the user to do the wrong thing; 3. deciding evidence is fabricated; 4. an unverified live situation is asserted as confirmed fact; 5. a necessary condition is left out, turning the answer into a wrong unconditional statement. Typos and minor wording issues that change no judgement or action are only noted. A correct main conclusion with a materially wrong side recommendation is still a material error. Correct but irrelevant extra information earns nothing. ## Four grades and the grading order | Grade | Rule | | --- | --- | | Fully resolved (`resolved`) | Core conclusion correct, request fully met, nothing materially misleading. | | Partially resolved (`partially_resolved`) | Useful, correct content delivered, but part of the request or a needed fact is missing; no confirmed material error. | | Material error (`material_error`) | The core conclusion or a key recommendation is materially wrong, including misleading unconditional generalizations and fabricated deciding evidence. | | Not resolved (`unresolved`) | No substantive answer — only a plan, only a request for more information, or "cannot answer". A wrong refusal that itself contains a confirmed key error is still a material error. | **Order:** first look for confirmed material errors, then judge coverage of the request. Correct content does not offset a key error. **Pending verification** (`pending_verification`) is a review state, not a fifth grade. When a deciding fact cannot be checked yet, keep the check open and do not grade; never record it as pass or fail. If existing evidence already confirms a material error, grade it directly. **Needs more information** is an interaction state that can coexist with a grade: only asking questions is not resolved; answering part and then asking can be partially resolved. ## Fairness rules - Accept semantically equivalent short answers, long answers, lists, tables and different valid evidence paths. Check meaning and facts; do not match the reference text, fixed wording, headings or tool order. Form gains or loses nothing unless it actually hinders understanding, hides a key condition or creates ambiguity. - A condition is necessary only if it changes the conclusion or what the user does. Do not universally require version fields, full call chains, parameter flows, edge-case lists or next steps. - For "how do I debug this", the actionable method, prerequisites and steps are the deliverable; how the Agent searched need not appear. - For "list all", check the complete set within the question's scope — a few correct examples may be only partial. Side topics the user did not ask about are not omissions. - The user's assumptions, counts or terms may be wrong. Correcting the premise accurately and answering the real question can be fully resolved. - Separate static rules from live facts. Honestly admitting an evidence gap is not an error, but the unfinished part of the request is still recorded. - Missing citations, an unshown process or a short reply are not grounds for calling a conclusion wrong. Sources are a deliverable only when the user or the shared test protocol asks for them, told identically to every setup. Volunteered citations are checked for existence and support, not counted for points; a temporarily unreachable link is not fabrication. Local evidence existing, a link path being correct, and the link opening for the user's account are three different checks. ## Using counterexamples The grader asks: within the question's scope, is there an evidenced case that overturns a deciding claim, or shows that an omission would change the user's judgement? The counterexample must belong to the question's scope and affect the conclusion — do not widen the question on the fly. The answer need not contain a "counterexamples" section; a correct condition or scope statement is enough. Not mentioning a branch is not itself an error. An answer that keeps its scope and generalizes nothing wrongly but skips part of the request is partially resolved. ## Three calibration patterns These patterns are rewritten from real grading decisions with every business detail removed. **A definition existing is not a call happening.** *Where does the front end call an old endpoint?* The code keeps a request wrapper and a monitoring list registers the address, but nothing in the checked scope calls it; pages now use a newer endpoint. - Saying "no business call was found in the checked scope" fully resolves it. - Listing the wrapper without judging whether it is called is partial. - Treating the monitoring entry as a request, or claiming the endpoint is absent from the code entirely, is a material error. - Only suggesting searches is not resolved. Lesson: grade the real meaning and the user's intent, allow correcting the premise, and never score by how often an address appears. **Role differences are also gated by state and permission.** *What can an owner do on a list page that a non-owner cannot?* In reality each action has its own conditions — role, workflow state, item type — and a detail entry is further controlled by a switch and an organization grant, so non-owners may also reach it. - Stating the differences with their conditions fully resolves it. - "Non-owners see no actions" or "owners can always act" is a material error. Lesson: counterexamples test unconditional generalizations. Necessary conditions come from the question's scope; the answer need not show the grader's whole control chain. **An outer choice and an inner data switch are different layers.** *When the current workflow is the new version, does viewing an old snapshot bring back the old interface?* The parent page picks a component from the *current* workflow; switching history inside it only changes the data. Only a different component renders history by its own version, and a revision number is not a version generation. - Explaining both layers fully resolves it. - Asserting that history always restores the old interface, or treating the revision number as the generation, is a material error. Lesson: when existing knowledge misses the parent-level condition, go back to the source and correct the criteria — do not treat a knowledge page as the answer key. ## Grader calibration and review - Give each answer a random alias per question and record the seed. First-pass grading hides setup, time, tool count and earlier scores. Links or wording inside an answer can still reveal its origin, so state that anonymity is limited. - Check consistency with separate calibration samples: the same facts short and long, as a paragraph and as a table, should get the same grade, and swapping the display order of two answers should not change the judgement. Store calibration samples apart from the real questions. - Review every material error, pending item, partial resolution and borderline call, and spot-check full resolutions. Graders give reasons someone else can check; length, style, tool order and whether the process is shown are not universal plus or minus points. - With only model graders and no human-labelled samples, call it an *internal consistency review*, never human calibration. ## Denominators and statistics - With Q frozen questions and R repeats, each configuration plans **N = Q × R** runs. Every grade rate divides by N; a partial resolution is never counted as half. - Grade counts + pending + not run = N. Graded coverage = runs placed in one of the four grades ÷ N. - A delivery failure or timeout with no answer is graded not resolved, and the platform, tool or cancellation reason is kept; it is not automatically a knowledge error. - The default is three runs per question. A question counts toward the **stable-resolution count** only if all three runs are fully resolved; with single runs, do not report a stable-resolution rate. - Compare performance on all questions *and* on the **common subset** every setup fully resolved, showing each denominator, so setups are not compared on different, easier questions. - Label every improvement figure as **measured**, **conditional estimate** (with formula and assumptions) or **untested direction**. ## Timing - **Primary end-to-end (E2E) time** = when the tester received the complete final answer − when the question was submitted. It includes network, platform initialization, retrieval, tools, polling and delivery. Unit: seconds. - Keep full timestamps with time zone. Across systems, state clock skew and precision; a missing value is never 0. - Startup, first progress, first token, model text finished, runner finished and user received the final answer are different events. Name each by what was actually captured and never substitute one for another. A first progress message is not the final answer, and a task marked done still needs its answer confirmed as delivered. - If only platform creation and final send receipts exist, report a separate **platform E2E** marked as a proxy; never mix it with receiver-side E2E. - Agree the timeout before running; 600 seconds is a reasonable default. It is an execution limit, not a business target. Record the actual stop time for a timeout and give a re-run its own run ID; a timeout is never a successful 600-second sample. Failures without a final answer are not latency samples of successful delivery, but their rate and waiting time must be shown. - **Mean** = sum of same-definition times ÷ sample count. **P50** = median (average of the middle two for an even count). **P90** = nearest-rank, the ⌈0.9 × n⌉-th sorted value. Always show the sample count; with repeats, also report each question's median. ## Tool calls and channel overhead - Count tool calls by unique call ID and state the coverage — events the platform exposes; internal calls of unexposed sub-Agents are not counted. One shell call may run several commands. Tool calls describe the execution path; they are not model calls or tokens. The span from first to last tool event includes reasoning, waiting and concurrency, so do not call it pure tool time. - Keep original receipts for platform failures, timeouts, cancellations, quota refusals and retries. Link an extra run to the attempt it repeats; never replace a result with the best one. When a question needs the user to supply more information, define one multi-turn protocol for all setups and label ad hoc follow-ups and resumes. - **Channel overhead:** an Agent configured for a chat channel — for example one that assembles reply cards — may still detect the channel, read card instructions and resolve links when called directly. For pure question answering, switch to a reply policy suited to direct calls, or record and exclude that overhead. --- ## Sources - note:20261013/evaluation-method.md · evaluation-method.md L1–L3 - note:20261013/evaluation-method.md · evaluation-method.md L12–L23 - note:20261013/evaluation-method.md · evaluation-method.md L61–L76 - note:20261013/evaluation-method.md · evaluation-method.md L78–L89 - note:20261013/evaluation-method.md · evaluation-method.md L91–L99 - note:20261013/evaluation-method.md · evaluation-method.md L101–L103 - note:20261013/evaluation-method.md · evaluation-method.md L105–L109 - note:20261013/evaluation-method.md · evaluation-method.md L111–L116 - note:20261013/evaluation-method.md · evaluation-method.md L118–L125 - note:20261013/evaluation-method.md · evaluation-method.md L127–L134 - note:20261013/evaluation-method.md · evaluation-method.md L135–L137 --- ## Knowledge Retrieval Benchmark # Knowledge Retrieval Benchmark ## Results at a glance On 24 real developer questions from a large production full-stack monorepo, Agents answering from Context knowledge fully solved more questions, faster and with far fewer tool calls than Agents using an LLM Wiki. Adding Source Graph for remote code reading cut time and tool calls further. | Metric | LLM Wiki | Context | Context + Source Graph | | --- | ---: | ---: | ---: | | Answering model | GPT 5.6 SOL | GPT 5.6 SOL | Claude Opus 5.5 | | Fully solved | 19 (79.2%) | 21 (87.5%) | 23 (95.8%) | | Partly solved / substantively wrong | 2 / 3 | 2 / 1 | 0 / 1 | | Mean end-to-end time | 223.2 s | 157.1 s | 93.2 s | | P50 / P90 | 137.2 / 464.7 s | 136.8 / 256.2 s | 89.0 / 123.0 s | | Mean tool calls | 77.5 | 24.5 | 7.8 | ```mermaid xychart-beta title "Mean tool calls per question" x-axis ["LLM Wiki", "Context", "Context + Source Graph"] y-axis "Tool calls" 0 --> 80 bar [77.5, 24.5, 7.8] ``` LLM Wiki and Context used the same model and are directly comparable. The third configuration also changed the model; the same-model comparison below isolates Source Graph's effect. The method follows [Evaluating Your Knowledge Base](); the grading and timing rules are in [Evaluation Scoring and Timing Standard](). ## What was compared | Configuration | Knowledge and retrieval | | --- | --- | | LLM Wiki | A one-off generated LLM Wiki; the Agent searches and reads files locally | | Context | A Context knowledge package; the Agent retrieves locally | | Context + Source Graph | A Context knowledge package; code is read remotely at a pinned version through Source Graph | The benchmark measures **answering** with deployed knowledge. Knowledge production — quality, time, review effort and cost of producing and updating knowledge — has not been benchmarked yet. ## Questions and scoring The 24 questions came from real developer questions and were frozen before any run. Each configuration answered each question once. | Question type | Count | | --- | ---: | | Locating interfaces and pages | 7 | | Business interaction rules | 5 | | Interfaces and parameters | 4 | | Permissions and roles | 3 | | Versions and call relationships | 3 | | Debugging and environments | 2 | - Each question had criteria written in advance; answers were graded fully solved, partly solved, substantively wrong or unanswered. - Grading was done by a model (GPT-6 Astra Ultra) blind to the configuration, without human calibration. - Time is the end-to-end time until the caller saw the complete answer: mean, P50 and P90 (nearest-rank). - Tool calls count only calls visible to the Agent. ## On the 17 questions all three solved To remove differences in question difficulty, the 17 questions that every configuration fully solved were compared separately: | Metric | LLM Wiki | Context | Context + Source Graph | | --- | ---: | ---: | ---: | | Mean end-to-end time | 232.6 s | 160.7 s | 93.5 s | | P90 | 534.5 s | 258.8 s | 123.2 s | | Mean tool calls | 78.3 | 24.9 | 8.0 | ## Source Graph with the same model With Claude Opus 5.5 in both runs, Context with local retrieval fully solved 23 of 24 questions with a mean of 139.3 s, P90 188.7 s and 11.6 tool calls. Adding Source Graph kept 23 of 24 and reduced mean time by 33.1%: 256 local calls for repository preparation, shell, search and file reads were replaced by 164 remote retrievals. Eight remote calls failed parameter validation and the Agent recovered from all of them. Under the same knowledge and retrieval, another model (Grok 4.7) also fully solved 23 of 24 but took a mean of 304.0 s, about 2.2 times as long. At equal quality, model choice has a large effect on time. ## Three models on the same knowledge setup With the same Context knowledge package on a managed Agent platform, the same 24 questions, one run each and the same blind model grader: | Metric | GPT 5.6 SOL (first run) | Grok 4.7 | Claude Opus 5.5 | | --- | ---: | ---: | ---: | | Fully solved | 21 (87.5%) | 23 (95.8%) | 23 (95.8%) | | Partly solved / substantively wrong | 2 / 1 | 0 / 1 | 0 / 1 | | Mean / P50 / P90 end-to-end | 157.1 / 136.8 / 256.2 s | 304.0 / 314.2 / 465.9 s | 139.3 / 141.4 / 188.7 s | | Mean visible tool calls | 24.5 | 40.3 | 11.6 | | Mean observed startup | 31.8 s | 34.4 s | 40.0 s | - On the **20 questions all three fully solved**, mean end-to-end time was 162.8 s, 312.7 s and 142.3 s, with 25.4, 41.3 and 12.2 tool calls. - Against the first run, Claude Opus 5.5 was faster on 18 of 24 questions, with P90 26.3% lower and 52.6% fewer tool calls. Grok 4.7 was slower on all 24 and made 64.0% more tool calls; the longer investigations did not raise the full-resolution rate. - **Equal counts are not equal answers.** Each newer model fixed some of the first run's gaps and introduced a different error of its own. - **The same conclusion can come by very different paths.** On one question both models were correct: one took 493.7 s and 75 calls, the other 176.4 s and 18. ## What the traces showed - When the host repository did not contain the target address, the knowledge gave the page → remote SDK → interface chain directly, so the Agent did not search blindly across repositories. - Questions about differences between versions first need "compared with which version"; the knowledge recorded the pinned commits and comparison range of its sources. - The few errors came from knowledge that missed a component's branch condition and over-generalized. Such gaps should become revision tasks. - Tool calls fell from 77.5 to 24.5 and then to 7.8: knowledge reduced blind exploration, and remote retrieval replaced local repository preparation and file reads. ## Where the errors and overhead came from - **Search scope misjudged.** In a sparse checkout the caller's directory was not checked out, yet a local search was taken as proof that nothing in the whole repository referred to the target. Having read source code is not the same as having searched all of it; confirm the checkout scope before any repository-wide negative conclusion. - **A condition generalized.** The knowledge stated a region for direct calls and kept field-based calls for dynamic forms; the answer extended the first to every request, and a field for another region in the source was the counterexample. The grade fell because of the wrong claim, not because the process was not shown. - **Targeted source checks worked.** On the question where the first run missed a parent-page branch condition, both later models traced the parent's component choice and the history data switch and corrected the conclusion. - **Channel preparation.** Called directly, the configuration under test still ran the steps meant for a chat channel's reply cards: 54 visible related calls across the first run's 24 questions, and for another model — which resolved links and checked channel context on every question — 149 deduplicated calls, 15.4% of its tool calls. They do not mean a card was sent, and their time was not separated. Trimming delivery preparation at the entry point would remove steps unrelated to answering. - **Waiting for startup.** From submission to first observing "running" took about 32 s on the managed platform, including polling granularity. ## Conditional estimate: faster startup This is a **conditional estimate**, not a measurement. Replace each first-run question's measured startup with an assumed target and keep every other stage unchanged: estimated E2E = measured E2E − measured startup + assumed startup target | Assumed startup | Mean | P50 | P90 | | ---: | ---: | ---: | ---: | | 5 s | 130.4 s | 105.5 s | 229.9 s | | 10 s | 135.4 s | 110.5 s | 234.9 s | Whether such a target is reachable has to be re-measured on the same questions and configuration. ## What to improve next - Verify the checkout scope before concluding that nothing in a repository uses something. - Keep branch conditions when knowledge is merged or summarized. - Skip reply-card preparation in direct sessions that have no delivery target. ## Estimated cost Per question, tokens fell from about 567,000 to about 63,000. At standard API prices (input \$4 and output \$20 per million tokens, no cache discount) that is about \$2.45 → \$0.27, a reduction of 88.9%. The first and model-switched runs were estimated by replaying requests; the LLM Wiki and latest runs were extrapolated from tool-call counts. ## Limits of this comparison - Each question was run once, so stability cannot be inferred. - These are whole configurations: LLM Wiki and Context ran in different Agent environments with different system prompts; Context + Source Graph also changed the model and Context version, the run date, concurrency and timeout limits, and is a regression on already-seen questions with a single grader. - End-to-end time includes environment start-up and polling granularity, not quota queuing. - Cost is an estimate, as described above. - In the three-model comparison, the two later runs allowed up to four concurrent questions per model; the first allowed at most two and was partly serial. Dates, Skills, runtime and some read versions also differed, so not every difference belongs to the model. Size reduction is a different measure: knowledge is about 1/115 of its sources by volume, which says nothing about quality on its own. See [Knowledge for Agents](). --- ## Sources - note:20261012/benchmark-summary.md · benchmark-summary.md L40–L49 - note:20261012/benchmark-summary.md · benchmark-summary.md L16–L16 - note:20261012/benchmark-summary.md · benchmark-summary.md L5–L15 - note:20261012/benchmark-summary.md · benchmark-summary.md L19–L30 - note:20261012/benchmark-summary.md · benchmark-summary.md L32–L38 - note:20261012/benchmark-summary.md · benchmark-summary.md L51–L57 - note:20261012/benchmark-summary.md · benchmark-summary.md L59–L67 - note:20261013/evaluation-method.md · evaluation-method.md L147–L162 - note:20261012/benchmark-summary.md · benchmark-summary.md L69–L74 - note:20261013/evaluation-method.md · evaluation-method.md L164–L170 - note:20261013/evaluation-method.md · evaluation-method.md L170–L170 - note:20261013/evaluation-method.md · evaluation-method.md L125–L125 - note:20261013/evaluation-method.md · evaluation-method.md L172–L172 - note:20261012/benchmark-summary.md · benchmark-summary.md L81–L81 - note:20261012/benchmark-summary.md · benchmark-summary.md L76–L80 - note:20261012/compression.md · compression.md L21–L27 - note:20261013/evaluation-method.md · evaluation-method.md L171–L171 --- ## Architecture Overview # Architecture Overview ## The parts ```mermaid flowchart TB user["You"] --> agent["Your Agent"] subgraph plugin["Agent plugin"] entries["Entry skills"] indexers["Indexer skills"] end agent --> plugin plugin --> cli["context CLI"] subgraph runtime["Local runtime"] cli --> provider["Workflow Provider"] cli --> extract["Extractors"] cli --> sdk["SDK declarations"] end cli --> ws["Context knowledge workspace"] ws --> out["Package, site, LLM Docs"] ``` | Part | Role | | --- | --- | | Agent entries | Thin skills that tell the Agent how to start or continue a Context knowledge workspace and how to follow the current step | | Indexer skills | Provider skills that read one kind of source and write source-grounded articles | | `context` CLI | Observes the knowledge workspace, captures sources, runs extractors, validates evidence, applies reviews and builds outputs | | Workflow Provider | The work contract evaluated by Agent Graph: legal steps, Gates and required reading | | SDK (`@c4a/context`) | The declaration surface for a knowledge workspace's `src/index.ts`: sources, phases and packages | | Extractors | Parser packages that turn code and interface definitions into structural facts | | Evidence plugin | An optional WebAssembly plugin that lets Source Graph attach knowledge sections to code reads | ## Local-first by design There is no server, daemon, database, hosted API or web frontend in Context. The CLI reads declared sources, writes knowledge workspace files, validates invariants and produces portable packages. Everything a team needs to inspect lives in the knowledge workspace and can be committed to Git; a hosted Agent or Bot runs the same CLI. ## Who does what The Agent performs semantic work: reading evidence, proposing structure and content, explaining decisions. The CLI performs deterministic work and never calls an LLM. The user owns the goal, source permissions, structure choices and review decisions. Keeping these apart is what makes a long workflow repeatable — see [Why a Workflow](). ## How a request travels 1. The Agent entry runs `context entry`, which resolves initialization, relocation or the current workflow. 2. The CLI observes knowledge workspace facts and asks the Provider for the current Route: the step, its reading list, any Gate and the exact commands. 3. The Agent reads, decides and runs one selected action. 4. The knowledge workspace changes, and the CLI evaluates again. Details are in [Workflow Execution](); the stages a source passes through are in [Knowledge Lifecycle](); package boundaries are in [Module Layout](). --- ## Sources - [context/ARCHITECTURE.md L7–L47 · 3b0ce0a]() - [context/plugins/context/README.md L5–L17 · 3b0ce0a]() - [context/packages/context-cli/README.md L3–L18 · 3b0ce0a]() - [context/ARCHITECTURE.md L49–L52 · 3b0ce0a]() - [context/ARCHITECTURE.md L420–L423 · 3b0ce0a]() - [context/README.md L101–L104 · 3b0ce0a]() - [context/packages/context-cli/README.md L28–L32 · 3b0ce0a]() - [context/packages/context-cli/README.md L80–L107 · 3b0ce0a]() --- ## Why a Workflow # Why a Workflow ## Teams already have Agents Engineering teams already work in Claude Code, Codex, Cursor or a managed Agent environment, and many run team Bots. A hosted knowledge platform would ask them to move their sources, permissions and review habits somewhere new. Context goes the other way: it adds skills to the Agents a team already uses, and a local CLI does the deterministic work. The same skills run in a local coding Agent or a managed Agent environment. ## Semantic work and deterministic work Knowledge production mixes two kinds of work: | Kind | Examples | Done by | | --- | --- | --- | | Semantic | Reading evidence, proposing structure, writing and explaining | The Agent | | Deterministic | Recording source boundaries, capturing snapshots, indexing code, checking evidence, staging candidates, applying reviews, building | The CLI | | Decisions | Goal, source permission, scope, structure, review, output | People | The CLI never calls an LLM and never silently clones, fetches, installs or builds a source repository; registering a source does not grant permission to read its contents, and review decisions stay with people. That keeps the parts that must be repeatable out of the model's hands, while the Agent stays free to choose the best wording and structure. ## A workflow, not a long prompt The lifecycle is long: sources must be scoped and captured, articles written against evidence, human Gates may pause the run, and approved knowledge must be closed, verified and built. Putting all of that in one prompt would be fragile and expensive. Instead the workflow is a contract: at each step the CLI returns only the action that is legal now, the resources to read for it and the commands to run. Interrupting and resuming converge from the actual state of the Context knowledge workspace rather than from conversation memory. See [Workflow Execution](). ## From one person's Agent to a knowledge service Because the skills are platform-independent, a team can run them as a resident knowledge service: an Agent environment with the Context plugin, a Bot prompt and remote code reading, taking requests from chat, the web, schedules or an API. It produces, updates and answers continuously, and people step in only at the decisions that matter — the work-start report, the review report and scope trade-offs. Shared knowledge that needs a lot of searching and confirmation, and answers that must be available at any time, suit such a resident service. Knowledge for a small module can simply live in the repository's `docs/`. --- ## Sources - note:20261012/knowledge-service-agent.md · knowledge-service-agent.md L9–L11 - [context/packages/context-cli/README.md L22–L32 · 3b0ce0a]() - [context/README.md L101–L104 · 3b0ce0a]() - [context/packages/context-cli/README.md L28–L32 · 3b0ce0a]() - [context/packages/context-cli/README.md L182–L184 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L5–L7 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L38–L42 · 3b0ce0a]() - note:20261012/knowledge-service-agent.md · knowledge-service-agent.md L15–L24 - note:20261012/knowledge-service-agent.md · knowledge-service-agent.md L39–L41 --- ## Knowledge Lifecycle # Knowledge Lifecycle ## From source to package ```mermaid flowchart LR reg["Register"] --> cap["Capture"] cap --> idx["Indexer lifecycle"] idx --> cand["Candidates"] cand -->|approve| appr["Approved"] appr --> closed["Close"] closed --> built["Verify and build"] ``` | Stage | What happens | What it protects | | --- | --- | --- | | Register | A repository module, document folder or online document is recorded as a source boundary | Source identity and permission boundary; registration does not grant permission to read beyond it | | Capture | Document bodies and embedded resources are saved as snapshots; repositories are read at a pinned commit | Complete bodies, resources and fingerprints, so later checks can detect stale inputs | | Indexer lifecycle | Requirements are confirmed, a plan and work-start report are approved, then Indexer skills write articles in stages | Every section is bound to exact source locations | | Review | You see the whole current batch of Candidates and approve, reject or ask for revisions | Approval is applied atomically; rejected material keeps a minimal fingerprint so it is not proposed again | | Close | `knowledge/structure.yaml` is rebuilt from approved pages and their edges | The knowledge map matches the approved pages, without rewriting prose | | Verify and build | Source references, frontmatter, structure and assets are checked, then packages and sites are produced | Distributed files map back to approved knowledge through a build inventory | ## Inside the Indexer lifecycle The top-level workflow has a single production step, `run-indexer-lifecycle`, which hands over to the nested Indexer graph: 1. **Requirements.** The reader purpose, questions and authorized sources are recorded in `src/indexers.yaml`. 2. **Planning.** The Agent investigates and writes a plan of articles in batches. 3. **Work-start report.** The plan is presented for confirmation; managed authority does not waive a required decision. 4. **Stage writing.** Each task produces an article and its references; the CLI checks that every cited source is authorized for that task. 5. **Gaps and repair.** Missing evidence becomes further investigation or a repair, not an invented answer. Code, Markdown, notes and session summaries all converge into one current Candidate batch, and one content Review admits it. See [The Indexer System](). ## Where state lives | Location | Lifetime | | --- | --- | | `sources/` | Project state: registries and captured evidence | | `.tmp/context-runtime/lifecycle/` | Disposable: structure drafts and the active Candidate ledger, removed after a successful close | | `knowledge/` | Project state: approved pages and `structure.yaml` | | `dist/` | Reproducible build output | Candidate IDs are workflow state and never become the identity of approved knowledge; approved Markdown stores its stable identity in frontmatter and section metadata. ## After the build Building completes the currently approved state; it does not freeze the Context knowledge workspace. The workflow records a new knowledge workspace version when content changes, before building. Later, `context revise` corrects a selected page and `context update` handles a selected source change; both run through Review and delivery again and touch only what is affected. See [Keeping Knowledge Current]() and [Version-Aware Knowledge](). --- ## Sources - [context/packages/context-cli/README.md L113–L121 · 3b0ce0a]() - [context/ARCHITECTURE.md L236–L257 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L351–L369 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/indexer.yaml L1–L67 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L57–L66 · 3b0ce0a]() - [context/ARCHITECTURE.md L236–L252 · 3b0ce0a]() - [context/ARCHITECTURE.md L151–L160 · 3b0ce0a]() - [context/ARCHITECTURE.md L275–L277 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L343–L349 · 3b0ce0a]() - [context/packages/context/docs/getting-started.md L150–L157 · 3b0ce0a]() - [context/packages/context-cli/README.md L123–L124 · 3b0ce0a]() --- ## Module Layout # Module Layout ## Package dependencies ```mermaid flowchart BT core["@c4a/core"] extract["@c4a/extract"] ts["@c4a/extract-ts"] go["@c4a/extract-go"] catalogs["Catalog parsers"] sdk["@c4a/context"] ag["@c4a/agent-graph"] cli["@c4a/context-cli"] extract --> core ts --> extract go --> extract catalogs --> core cli --> sdk cli --> ag cli --> extract cli --> ts cli --> go cli --> catalogs ``` Arrows point from a package to what it depends on; catalog parsers are `extract-rush`, `-mdx`, `-proto`, `-thrift`, `-contract`, `-sql` and `-style`. `@c4a/context-cli` is the only package users install; the SDK, extractors and Agent Graph come with it. ## What each package does | Package | Responsibility | | --- | --- | | `@c4a/context` | Declarative SDK for a Context knowledge workspace's `src/index.ts`: sources, phases and package outputs, plus the versioned Indexer contracts | | `@c4a/context-cli` | The `context` command: knowledge workspace lifecycle, source capture, validation, review, close, build, the documentation website builder, the bundled workflow Provider and the Agent plugin | | `@c4a/core` | Shared extraction types, schemas and utilities | | `@c4a/extract` | Language-plugin framework and repository runner for code evidence | | `@c4a/extract-ts`, `@c4a/extract-go` | TypeScript/JavaScript and Go extraction plugins: symbols, spans, imports and exports | | `@c4a/extract-rush`, `-mdx`, `-proto`, `-thrift`, `-contract`, `-sql`, `-style` | Lightweight catalogs for Rush workspaces, MDX components, Protocol Buffers, Thrift, OpenAPI/GraphQL contracts, SQL and CSS/SCSS | | `context-evidence-wasm` | Builds the optional `context-evidence.sourcegraph.wasm` plugin for Source Graph | | `@c4a/agent-graph` | External, model-free workflow-contract runtime used only by the bundled Provider | Parser packages materialize structural facts; they never write approved knowledge. See [Code Extraction](). ## Inside the CLI package | Path | Contents | | --- | --- | | `src/project/` | Knowledge workspace observation, sources, Indexer lifecycle, review, close, verify and package build | | `src/project/workflow/` | Observes facts and binds the selected graph action to a revisioned command | | `context-workflow/` | The Provider source: graphs, actions, resources, schemas and route tests | | `plugins/context/` (repository root) | The only maintained source of the Agent plugin: four public entry Skills (`context`, `context-plan`, `context-inspect-search`, `context-repo-content`), four Indexer Provider Skills and `context-indexer-create`; host-specific entries are generated at build | The build emits one bundle: the CLI binary, the immutable Provider under `dist/providers/context`, the plugin projections, the Indexer skills, the diagram viewer and the evidence plugin. ## Where a change lands - `@c4a/context` changes affect knowledge workspace declarations and phase plans. - `@c4a/context-cli` changes affect commands, Agent workflows, knowledge workspace file formats, review behavior and package output. - `@c4a/extract` and the extractor and catalog packages (`extract-ts`, `extract-go`, `extract-rush`, `-mdx`, `-proto`, `-thrift`, `-contract`, `-sql`, `-style`) affect only the code facts of their languages and formats; see [Code Extraction](). - `context-evidence-wasm` changes affect only how Source Graph enriches remote code reads; local retrieval and knowledge production stay unchanged. - Agent Graph is a pinned external dependency; Context owns its Provider and host bindings. --- ## Sources - [context/packages/context-cli/package.json L55–L67 · 3b0ce0a]() - [context/CLAUDE.md L7–L33 · 3b0ce0a]() - [context/ARCHITECTURE.md L54–L75 · 3b0ce0a]() - [context/ARCHITECTURE.md L338–L356 · 3b0ce0a]() - [context/README.md L130–L145 · 3b0ce0a]() - [context/ARCHITECTURE.md L358–L389 · 3b0ce0a]() - [context/packages/context-cli/package.json L37–L38 · 3b0ce0a]() - [context/ARCHITECTURE.md L77–L89 · 3b0ce0a]() --- ## Workflow Execution # Workflow Execution ## The evaluation loop Context does not run a fixed script. Every time the Agent asks what to do, the CLI observes the Context knowledge workspace, turns what it sees into **Facts**, and asks the workflow Provider for the current **Route**. ```mermaid flowchart LR facts["Knowledge workspace facts"] --> evaluate["Agent Graph evaluates"] evaluate --> route["Current Route"] route --> act["Agent runs one action"] act -->|"knowledge workspace changes"| facts ``` A Route carries the selected step, a reason code, the resources the Agent must read before acting, any unresolved Gate and the exact commands to run. Only `workflow.current` chooses the next lifecycle step; a command that finishes returns control to a fresh evaluation instead of choosing the next step itself. ## Two graphs The Provider in `packages/context-cli/context-workflow/` contains two static graphs: | Graph | Covers | | --- | --- | | `workspace` | The top-level lifecycle: repair, source boundary, capture, Indexer lifecycle, review, close, package output, translation, version recording, build and completion, plus rollback | | `indexer` | Requirements, planning, the work-start report, stage writing, gap handling, source updates and approved-page revisions | The top-level order is fixed by the graph's edges: source boundary → capture → `run-indexer-lifecycle` → review → close → package output → version → build. Nodes describe stable task categories such as "a capture target remains"; source names, dates and modules are runtime facts and never become graph nodes. That is why one graph serves every knowledge workspace. ## Gates Some nodes are **Gates**: they wait for a decision. Examples are choosing the source boundary, authorizing document capture, approving the work-start report, reviewing the current batch and choosing the package output. Each Gate declares whether it is delegatable. In ordinary mode a person decides. When you explicitly authorize fully managed operation for the current conversation, the Agent may resolve delegatable Gates — for example applying a review it has checked — but never those marked non-delegatable, such as the work-start report when a scope decision is required. Managed authority is scoped to the conversation and cannot authorize new source boundaries, failed validation or failed verification. ## Revisions and stale commands Every write command is bound to the revision of the observation that produced it. If the knowledge workspace changed since then — another action ran, a file was edited — the command is rejected instead of being applied to newer state. Required resources are acknowledged by digest; dynamic views are tied to the revision that selected them. A receipt proves the Agent received a resource; it does not claim the task is done. ## Resuming With the same Provider, the same observed Facts and the same recorded outcomes, Agent Graph selects the same Route. Work already satisfied by knowledge workspace facts is skipped or advances. So an interruption, a retry or a new conversation converges from observable state, not from conversation memory. The CLI keeps each filesystem effect atomic, guarded or a proven no-op; Agent Graph keeps evaluation repeatable. ## How the workflow improves Route selection is tested without a model: `context-workflow/tests/` holds fact-to-Route scenarios. With debug mode on, Context records CLI invocations and graph evaluations; a replay shows which Route was chosen at each fact change, where a loop advanced and where a Gate paused. Inefficient loops, repeated reads or misleading priorities found in traces become new route tests and graph changes. Long procedures live in separate resources, so they can be improved without touching the entry skill. --- ## Sources - [context/packages/context-cli/context-workflow/README.md L8–L18 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L34–L34 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/README.md L75–L78 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/README.md L37–L51 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L351–L372 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L68–L68 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L183–L202 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/indexer.yaml L50–L63 · 3b0ce0a]() - [context/packages/context-cli/README.md L151–L157 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/README.md L57–L68 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L38–L42 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L74–L88 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/README.md L47–L47 · 3b0ce0a]() --- ## Packages and Sites # Packages and Sites ## One body of knowledge, several outputs ```mermaid flowchart LR kn["Approved knowledge"] --> build["context build"] kmap["Knowledge map"] --> build tpl["Package templates"] --> build build --> kb["Knowledge package"] build --> site["Documentation site"] build --> llms["LLM Docs"] build --> inv["Build inventory"] ``` Build consumes only approved and closed knowledge. Output channels can be combined; for a new knowledge workspace the Agent proposes a knowledge package plus a website by default, and LLM text is an additional choice. Every build emits an inventory that maps distributed files back to approved knowledge in the knowledge workspace. ## Agent knowledge packages A knowledge package uses flat roots: | Root | Internal collections | | --- | --- | | `wikis/` | `codegraph`, `business`, `product` | | `guides/` | `architecture`, `sop`, `faq`, `decision`, `incident` | | `rules/` | `standards`, `test` | | `feats/` | `feats` | The default `knowledge-query` skill is the Agent-facing entry: it starts from directory indexes, follows edge records in the inventory, reads candidate pages and cites their headings, and reports gaps when the package does not cover a fact. When indexes do not narrow the scope, its bundled `scripts/search.mjs` ranks Markdown chunks locally. Consumer pages omit `sources` and section metadata; exact attribution stays in the workspace and is reached through the inventory. ## Documentation sites Enabling `site` on a package also produces `dist/-site/`: a static site with article pages, local search, scripts and styles, built in a sibling staging directory so a failed site build keeps the previous output. - **Navigation** comes from the accepted `src/knowledge-map.yaml`. Entries bind to article identity, so labels and groups do not change URLs, and one article can appear in several places. - **Homepage** uses the first-level knowledge map as a complete site map. - **Diagrams** written in Mermaid render in the browser with the site theme and offer fit, zoom, full-screen and source controls. - **Source footer** on each article links repositories at their recorded revision and documents at their registered URL. - **Languages** can be added with `site.locales`; untranslated pages show the original with a notice. Context does not deploy. Preview with any static HTTP server and deploy the contents of `dist/-site/` with your own hosting. ## LLM Docs `llmsPackage()` produces a text bundle for model context, offline evaluation or downstream ingestion: ```text llms.txt # knowledge-map index llms-full.txt # consolidated approved text llms/pages/.txt # individual articles ``` ## Customizing without forking the knowledge Package templates shape distribution — extra Agent instructions, static files, query helpers — but never replace approved knowledge as the source of truth. Presentation sources for a site, such as homepage slots, custom pages and theme components, live under `src/site/`, separate from generated knowledge. --- ## Sources - [context/packages/context/docs/guides/package-outputs.md L12–L16 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L33–L37 · 3b0ce0a]() - [context/README.md L106–L114 · 3b0ce0a]() - [context/ARCHITECTURE.md L304–L317 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L243–L255 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L45–L54 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L97–L133 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L174–L187 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L363–L376 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L294–L300 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L39–L43 · 3b0ce0a]() --- ## Knowledge for Agents # Knowledge for Agents ## An index, not a copy An Agent that has to answer a question needs to know **where to look** and **what is true**, quickly. It does not need a second copy of the codebase, and it does not need long, polished prose that restates every function. Context therefore treats knowledge as an index with explanations: - each article answers specific reader questions agreed in the requirements; - each statement points to the exact source region it came from; - the source itself stays where it is, readable at a pinned version when more detail is needed. ```mermaid flowchart LR src["Sources"] --> idx["Indexer"] idx -->|keeps| kept["Entries, contracts, rules"] idx -.->|leaves in source| left["Bodies, boilerplate"] kept --> art["Article with references"] ``` ## Extract on demand Indexers do not start with a full symbol scan or a complete relationship graph. During planning they expose a useful skeleton — directories, manifests, registration points, public entries — and propose reader topics. Detailed reading happens while writing each topic, bounded to what that topic needs. Signals such as public exports, registered interfaces, scheduled jobs, storage interfaces or generated clients suggest reader questions, not mandatory pages; one page per symbol is explicitly avoided. Symbol count is not a quality measure. Internal or out-of-scope items can be left out with a reason; Review checks whether the pages actually answer the reader's questions. ## How much smaller In a large production full-stack monorepo, the two repositories that could be counted locally held about 33,700 code files and 5.84 million lines (about 200 MB); together with about 1,130 document snapshots (about 1.77 MB), they became 220 reviewed articles totalling about 1.75 MB — roughly **1/115** of the source volume. Two limits apply to that figure: - only part of the registered sources was counted, so the real ratio is higher; - the ratio measures size, not coverage or quality. Quality is measured separately in the [Knowledge Retrieval benchmark](). The knowledge is not lossless and does not "cover all code". It keeps the facts needed to answer questions, each with a pointer back to the code line or document section. See [Evidence Chains and Index First](). --- ## Sources - [context/plugins/context/skills/context-code-indexer/references/indexer.md L1–L28 · 3b0ce0a]() - note:20261012/compression.md · compression.md L28–L28 - [context/packages/context/docs/reference/indexer-provider-protocol.md L257–L264 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/SKILL.md L16–L31 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/references/indexer.md L37–L50 · 3b0ce0a]() - [context/packages/context/docs/reference/code-extractors.md L47–L51 · 3b0ce0a]() - note:20261012/compression.md · compression.md L15–L22 - note:20261012/compression.md · compression.md L26–L28 --- ## Evidence Chains and Index First # Evidence Chains and Index First ## The chain ```mermaid flowchart LR q["Question"] --> map["Knowledge map and indexes"] map --> page["Article section"] page -->|source_ref + file and lines| region["Source region at a pinned version"] region -->|content digest| check["Verified at write and verify time"] ``` An answer starts from the knowledge map, lands on an article section, and from there follows a reference to an exact region of a registered source. Each step is checkable: the reference names the source and the lines; the source is pinned; the region's content is fingerprinted. ## Sections carry their own evidence Approved articles are divided into sections. Each written fragment cites at most three source positions, each a `source_ref` plus a file and line `locator`. When an article is submitted, the CLI checks that each cited source is authorized for that task, reads the current captured text and computes the region's content digest. Unknown or unauthorized paths and source-version drift are errors, not warnings. There is no separate fact table or claim ledger to maintain — the references are the evidence. `source_ref` values are opaque, verified identities. Agents copy them exactly; they are not file-system paths. ## Checked again before delivery `context verify` re-checks approved pages before close and build: source references for freshness and verbatim match, frontmatter identity, section blocks, assets and the derived structure. Verification errors block close and build. Approved Markdown keeps a stable identity in frontmatter and section metadata, so a page can be revised without losing its history. ## Index first, then the original Agents answering from a knowledge package start from directory indexes and the edge records in the build inventory, read the candidate pages, and cite their headings and passages. When the package does not cover a requested fact, they report the gap instead of guessing. Consumer packages omit section metadata to stay small; a maintainer can map any page back to the Context knowledge workspace through the inventory to see its full evidence. With Source Graph, the chain reaches the code without a clone: the optional evidence plugin joins section markers, `knowledge/structure.yaml` and source registrations, so an Agent reading code at a pinned revision also receives the knowledge sections that cite it. The plugin is read-only; it does not verify source contents or modify knowledge. ## Visible to readers On a documentation site, each article ends with a source footer built from its recorded references: repository entries link to the recorded revision and module, and document entries link to their registered URL. Links are never inferred from prose. --- ## Sources - [context/packages/context/docs/reference/indexer-provider-protocol.md L257–L262 · 3b0ce0a]() - [context/ARCHITECTURE.md L233–L234 · 3b0ce0a]() - [context/packages/context/docs/reference/indexer-provider-protocol.md L257–L264 · 3b0ce0a]() - [context/packages/context/docs/reference/indexer-provider-protocol.md L418–L423 · 3b0ce0a]() - [context/packages/context-cli/README.md L189–L190 · 3b0ce0a]() - [context/ARCHITECTURE.md L279–L302 · 3b0ce0a]() - [context/ARCHITECTURE.md L275–L277 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L243–L254 · 3b0ce0a]() - [context/packages/context-evidence-wasm/README.md L1–L5 · 3b0ce0a]() - [context/packages/context-cli/README.md L14–L17 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L174–L174 · 3b0ce0a]() --- ## Version-Aware Knowledge # Version-Aware Knowledge ## Every source has a fixed version Knowledge is only checkable if you know which version of the source it describes. Context records that for every input: | Source | Fixed by | | --- | --- | | Repository module | The registered commit; restoring a Context knowledge workspace checks out that commit and never substitutes a newer one | | Online or local document | A captured snapshot with a fingerprint | | Note or session summary | The saved file; a session's related commits and merge requests stay in its frontmatter | References store the real repository path at the cited commit, even if the module is later registered under a different path. ## What has been processed `knowledge/structure.yaml` keeps compact `processed_scopes`: for each requirement, source and module range, the version that knowledge has been brought up to. A source update starts from that version, and the processed version only advances after every requested page in the range has been approved, closed and built — a partial update or failed build leaves it where it was. If temporary progress is lost, the next inspection starts again from the recorded version and keeps already approved pages. ```mermaid flowchart LR v1["Processed at commit A"] --> diff["Compare A with B"] diff --> pages["Affected pages and new topics"] pages --> review["Review"] review --> build["Close and build"] build --> v2["Processed at commit B"] ``` ## The knowledge workspace has its own version Besides source versions, the knowledge workspace itself carries a SemVer in `package.json`. At the end of each completed delivery — after Review, close and package configuration, before the final build — the workflow asks the Agent to inspect formal changes and record the next version with a concise changelog: - **minor** for added modules or expanded material coverage; - **patch** for corrections, updates to existing modules and navigation changes; - **major** only on explicit instruction. The CLI updates `package.json`, `changelog.yaml` and `CHANGELOG.md` together. Knowledge packages and LLM Docs carry the same version and changelog, and a documentation site shows the history on its Changelog page. Temporary progress never increases the version, and intermediate batches do not each get one. ## Going back Because the knowledge workspace is in Git, a historical version can be restored: the Agent resolves the target to a concrete commit and path scope, compares it with current files and restores the selected knowledge workspace files and usable sources. It does not reset the whole repository or rewind source repositories. --- ## Sources - [context/packages/context/docs/guides/workspace-prepare.md L88–L91 · 3b0ce0a]() - [context/packages/context-cli/README.md L117–L118 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L29–L30 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L224–L229 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/resources/procedures/source-update.md L29–L32 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L114–L133 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L169–L169 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L187–L190 · 3b0ce0a]() - [context/packages/context/docs/guides/workspace-restore.md L6–L26 · 3b0ce0a]() --- ## Keeping Knowledge Current # Keeping Knowledge Current ## The update loop ```mermaid flowchart LR change["Source changes"] --> cmp["Compare versions"] cmp --> decide["Keep, revise, add"] decide --> write["Write"] write --> review["Review"] review --> deliver["Close and build"] deliver --> base["New baseline"] ``` Building completes the currently approved state; it does not freeze the Context knowledge workspace. When a source moves on, `context update` opens a new round for the selected change. The workflow hands the Agent the fixed old and new source versions and the confirmed requirement scope, plus a list of pages that cite the changed material. ## Deciding what to change The listed pages are candidates to inspect, not an instruction to rewrite all of them. For each page the Agent reads its current approved Markdown and the change, then submits one decision: no change, or a concrete correction. Unrelated content and readers' earlier improvements are preserved. Existing references cannot discover every new topic, so the Agent also inspects additions and shared dependencies and lists necessary **new pages**, each with a path, title, registered sources and instruction. New pages go through the same writing and review as revisions. A renamed subject is revised in place rather than given a new identity; a retirement explains what disappeared and which readers are affected instead of silently deleting pages. ## Moving the baseline The CLI keeps the previous processed version until every requested page has been approved, closed and built. If temporary progress is lost, the next inspection starts again from that version and keeps pages already approved. A saved report or acquisition receipt does not prove the update was completed. See [Version-Aware Knowledge](). ## Keep the update local For one or two documents or a clearly bounded module, the update stays local: which articles to add or revise, and where readers expect them. It does not turn into a taxonomy for the whole knowledge workspace or a navigation redesign. Only the sources needed for the current change are restored; missing material stays a gap rather than being treated as investigated. ## Ways an update starts | Trigger | How | | --- | --- | | A source changed | Tell `/c4a:context` the new version; it runs `context update` for the selected scope | | A page is wrong or incomplete | `context revise "" --instruction ""` continues through Review and delivery, with no recapture for wording-only changes | | Unattended or scheduled runs | An authorized task can pass `CONTEXT_RUN_POLICY` with `plan_review` and `knowledge_review` set to `ask` or `delegate`; human-only Gates still stop | Gaps found while answering questions are handled the same way: they become revision tasks for the affected pages. --- ## Sources - [context/packages/context-cli/README.md L123–L124 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/resources/procedures/source-update.md L9–L16 · 3b0ce0a]() - [context/packages/context/docs/getting-started.md L155–L157 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/resources/procedures/source-update.md L15–L27 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/resources/procedures/source-update.md L41–L47 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/resources/procedures/source-update.md L29–L32 · 3b0ce0a]() - [context/packages/context/docs/reference/indexer-provider-protocol.md L637–L639 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L64–L69 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L52–L58 · 3b0ce0a]() - [context/packages/context/docs/guides/knowledge-updates.md L13–L17 · 3b0ce0a]() - [context/packages/context/docs/getting-started.md L9–L27 · 3b0ce0a]() --- ## The Indexer System # The Indexer System ## What an Indexer is An Indexer is an Agent skill that helps the Agent expose a source's skeleton and write source-grounded articles from it. It is guidance for reading and writing, not a mandatory full scan and not a classifier inside the CLI. The CLI prepares each stage, supplies its material and acceptance rules, and checks the result; the Indexer contributes how to investigate and explain one kind of source. ## Four built-in Indexers | Indexer | Reads | Starts from | | --- | --- | --- | | `context-code-indexer` | Repository modules | Directory and file navigation, manifests, entries and registrations; detailed code reading during writing | | `context-markdown-indexer` | Captured documents and same-repository docs | Titles, bounded opening excerpts and H2/H3 outlines; full text before writing | | `context-note-indexer` | Saved notes, excerpts and observations | Direct reading, no parser | | `context-sessions-indexer` | Saved conversation summaries | Direct reading, no parser | All four are installed with the plugin and discoverable in every supported host. Installing an Indexer makes it available; it does not select it. [Community Indexers]() describes each one in more detail. ## How the workflow uses them ```mermaid flowchart LR req["Requirements"] --> plan["Planning"] plan -->|"picks Indexers"| usage["indexer_usage"] usage --> write["Stage writing"] write -->|"CLI checks"| cand["Candidates"] ``` - `src/indexers.yaml` holds only confirmed requirements: purpose, reader goals, coverage domains and authorized sources. - During planning the Agent chooses the relevant Indexers and records them as `indexer_usage` in the temporary plan; that choice is not persisted on articles. - Several Indexers may explain different aspects of the same module, and their findings can support one article. There is no primary owner, no Provider resolution step and no version or hash pinning of skills. - Each writing task produces Markdown and references in a temporary directory; the CLI accepts them and owns Candidates, Review and formal output. ## Creating your own When a technology or document family needs specialist guidance, `/c4a:context-indexer-create` writes a new reusable Indexer skill in a directory you choose. A new Indexer starts with a useful skeleton — source structure, recognizable features, names, established counts and entry locations — and may add a bounded helper for its technology. It delivers a `SKILL.md` plus only the references, templates or scripts that help, and is validated against realistic anonymous material. It does not register a Provider manifest or start production; after installation it is available for the Agent to select. See [Creating an Indexer]() for the step-by-step guide and [Providers and Customization]() for combining, replacing and disabling Indexers. Where a needed structural fact is missing, writing guidance cannot create it — that calls for a parser. See [Code Extraction](). --- ## Sources - [context/packages/context/docs/guides/indexer-provider-and-customization.md L7–L13 · 3b0ce0a]() - [context/packages/context/docs/guides/indexer-provider-and-customization.md L75–L81 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/SKILL.md L16–L31 · 3b0ce0a]() - [context/plugins/context/skills/context-markdown-indexer/SKILL.md L24–L38 · 3b0ce0a]() - [context/plugins/context/skills/context-note-indexer/SKILL.md L11–L27 · 3b0ce0a]() - [context/plugins/context/README.md L13–L22 · 3b0ce0a]() - [context/plugins/context/skills/context-sessions-indexer/SKILL.md L24–L27 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L204–L215 · 3b0ce0a]() - [context/packages/context/docs/guides/indexer-provider-and-customization.md L23–L43 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/SKILL.md L22–L25 · 3b0ce0a]() - [context/plugins/context/skills/context-indexer-create/SKILL.md L10–L41 · 3b0ce0a]() - [context/packages/context/docs/reference/code-extractors.md L37–L45 · 3b0ce0a]() --- ## Code Extraction # Code Extraction ## Parsers produce facts, not knowledge Parser packages read code and interface definitions and emit deterministic structural facts: symbols, source spans, imports and exports, routes, contracts. They never create Candidates, write `knowledge/` or control Review. The selected Indexer interprets those facts together with the readable source and writes reader-oriented articles. ```mermaid flowchart LR code["Pinned module"] --> parsers["Parsers"] parsers --> facts["Structural facts"] facts --> indexer["Code Indexer"] code --> indexer indexer --> art["Articles"] ``` ## Available parsers | Package | Structural facts | | --- | --- | | `@c4a/extract-ts` | TypeScript/JavaScript symbols, exports, imports, calls and React Router routes | | `@c4a/extract-go` | Go declarations, imports, calls and common HTTP routes | | `@c4a/extract-rush` | Rush projects, tags, entries, dependencies and owner boundaries | | `@c4a/extract-thrift` | Thrift services, methods and declared data types | | `@c4a/extract-proto` | Protobuf messages, fields and service definitions | | `@c4a/extract-mdx` | Markdown/MDX structure, component references, examples and source spans | | `@c4a/extract-contract` | Supported structured API contract declarations (OpenAPI, GraphQL) | | `@c4a/extract-style` | Stylesheet declarations and selectors | | `@c4a/extract-sql` | Supported SQL schema declarations | | `@c4a/extract` | The shared extraction protocol, plugin runner, scanner and snapshot records | All of them ship inside `@c4a/context-cli`. ## Smallest parser set first Parsing is an Indexer implementation detail, not a separate phase in `src/index.ts`. The order is: 1. identify the target boundary and the reader's questions; 2. let the Indexer inspect language, manifests, entries, routes and contracts; 3. use the smallest parser set that covers those questions; 4. keep parser output as facts and write articles from facts plus readable source. During planning, the Code Indexer does not run a full-repository parse just to learn whether a feature exists; deep extraction belongs to writing a selected topic. ## When a technology is not supported Distinguish a parser limitation from missing writing guidance. Configuration can select supported behavior, but instructions and templates cannot create missing structural facts. The workflow reports the capability gap and the smallest supported step; when a technology is useful across projects, a reusable parser is preferred over a project-local pipeline. --- ## Sources - [context/packages/context/docs/reference/code-extractors.md L31–L35 · 3b0ce0a]() - [context/ARCHITECTURE.md L338–L356 · 3b0ce0a]() - [context/packages/context/docs/reference/code-extractors.md L16–L29 · 3b0ce0a]() - [context/packages/extract-mdx/README.md L5–L5 · 3b0ce0a]() - [context/packages/context-cli/package.json L55–L67 · 3b0ce0a]() - [context/packages/context/docs/reference/code-extractors.md L1–L14 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/references/indexer.md L14–L19 · 3b0ce0a]() - [context/packages/context/docs/reference/code-extractors.md L37–L45 · 3b0ce0a]() --- ## Source Graph Overview # Source Graph Overview **Context Source Graph** is a self-hosted service for searching and reading code at pinned Git revisions. It is built on Go, Git and the Zoekt trigram index, and it exists for the workload AI coding Agents create: many small, precise *search, then read* round trips against code the Agent has not checked out. Every request resolves to one exact commit before anything is read, so a search hit, the file it points to and a later diff all describe the same snapshot. The same operations are available in a browser, over HTTP, as an MCP server and from a command-line client. ```mermaid flowchart LR callers["People, scripts
and AI Agents"] --> surfaces["Website · HTTP · MCP · CLI"] surfaces --> service["repo-service
one shared contract"] service --> git["Git mirrors
per repository"] service --> engine["Zoekt index
child process"] service --> db["Application database
SQLite, PostgreSQL or MongoDB"] git -->|background sync and indexing| engine ``` Source Graph is part of the Context project. The name does not imply any affiliation with the Sourcegraph platform. ## Code and live demo - **Source code:** [github.com/context4ai/sourcegraph](https://github.com/context4ai/sourcegraph). - **Live demo:** [https://context4ai-portal.fly.dev/sourcegraph/](https://context4ai-portal.fly.dev/sourcegraph/), also reachable at [https://context4ai-sourcegraph.fly.dev/sourcegraph/](https://context4ai-sourcegraph.fly.dev/sourcegraph/). It is the public, read-only instance behind this documentation site's knowledge service and serves `context4ai/context` and `context4ai/sourcegraph`. Its MCP endpoint is `/sourcegraph/mcp`. [Deployment Recommendations]() shows how it is deployed. - **Optional for Context:** Context works without Source Graph. When no instance is installed or configured, Context's query skill reads code through a shallow, sparse partial clone and grep instead. ## Why it exists An Agent answering a question about code usually needs a handful of exact lines, not a whole repository. Cloning every repository into every Agent sandbox at the right revision is slow, and running `rg` or `git grep` over a checkout repeats the same scan on each call. Source Graph keeps an index per repository and answers instead: - **Fast.** Indexed search typically completes in a few milliseconds on the server. With the service in the same region as its callers, a full request including the network stays well under 100 ms. [Pinned Search and Reads]() explains where the speed comes from and shows the measured comparison. - **Reproducible.** Branches resolve to a commit first, and full commit SHAs are accepted only inside the repository's retention window, so answers never drift to a different snapshot mid-conversation. - **Agent-ready.** The MCP endpoint is stateless Streamable HTTP and works with any MCP client. Anonymous access is read-only and limited to public repositories. - **Small footprint.** One process manages the Git mirrors, the search engine and background indexing; SQLite is the default database. ## One contract, four surfaces All four entry points expose the same operations: | Operation | What it does | | --- | --- | | `repositories` | List registered repositories and their observed branches | | `availability` | Show a repository's retained versions and indexing status | | `resolve` | Turn a branch, or an eligible full SHA, into the fixed commit to use next | | `search` | Search file contents at one commit, shaped like `rg` | | `read` | Read a line range of one file at one commit | | `read_many` | Read up to ten known ranges at one commit in a single MCP call | | `list` | List one directory at one commit | | `diff` | Compare two eligible commits | | `prepare` | Ask for a commit to be synchronized and indexed (authorized callers only) | The website lives under `/sourcegraph/`, the MCP endpoint at `/sourcegraph/mcp`, and the HTTP API under `/sourcegraph/v1/` and `/sourcegraph/api/`. The command-line client `sourcegraph-cli` calls the same HTTP routes. Exact routes, tool inputs and limits are in the [HTTP and MCP]() and [CLI]() references. ## How an instance is put together A Source Graph instance is a single `repo-service` process. It starts the Zoekt search server as a child process listening only on the loopback interface, keeps a bare Git mirror for each registered repository on its data volume, and runs background workers that synchronize monitored branches and index new branch heads. The application database stores repositories, jobs, identities and settings. SQLite is the default; PostgreSQL and MongoDB are supported for larger or sharded deployments. Git mirrors and indexes always stay on the instance's local disk — search speed comes from that locality — so capacity is planned around disk rather than CPU. To grow, run several instances that each own a disjoint set of repositories; never run two instances over the same repositories or data directory. [Self-Hosting]() covers both topologies. Repositories can also ship WebAssembly plugins named `.sourcegraph.wasm` that add text to `read` and `read_many` results. Context uses this to attach each knowledge section's sources, described in [Evidence for Context](). ## Who can do what Without any sign-in provider configured, an instance is an anonymous, read-only site: visitors can search and read repositories marked public, subject to per-minute rate limits. Adding Google or GitHub sign-in enables administration, and the first verified user becomes the administrator. Signed-in users can create personal API keys for scripts and Agents, and a service token covers automation. Registering repositories, indexing older commits and other changes require an administrator or the service token. [Authentication and Access Control]() lists the full matrix. ## Where to go next A public demo instance at [context4ai.org/sourcegraph](https://context4ai.org/sourcegraph/) indexes the Context and Source Graph repositories and allows anonymous reading. | To… | Read | | --- | --- | | Understand pinned search and the speed comparison | [Pinned Search and Reads]() | | See how Context knowledge and Source Graph combine | [Evidence for Context]() | | Connect a browser, MCP client, script or the CLI | [Connecting]() | | Add repositories and monorepo path groups | [Registering Repositories]() | | Deploy your own instance | [Self-Hosting]() | | Configure sign-in and API keys | [Authentication and Access Control]() | | Run, monitor and troubleshoot it | [Operations]() | | Look up routes, tools, flags and settings | [HTTP and MCP](), [CLI](), [Query Syntax](), [Configuration]() | --- ## Sources - [sourcegraph/README.md L1–L16 · 4e5c555]() - [sourcegraph/README.md L105–L109 · 4e5c555]() - [sourcegraph/cmd/repo-service/main.go L113–L126 · 4e5c555]() - [sourcegraph/README.md L43–L43 · 4e5c555]() - note:20261013/demo-deployment.md · demo-deployment.md L12–L19 - [context/plugins/context/skills/context-inspect-search/SKILL.md L348–L352 · 3b0ce0a]() - [sourcegraph/README.md L18–L25 · 4e5c555]() - [sourcegraph/internal/service/service.go L289–L349 · 4e5c555]() - [sourcegraph/README.md L22–L22 · 4e5c555]() - [sourcegraph/docs/interfaces.md L1–L8 · 4e5c555]() - [sourcegraph/internal/mcpserver/server.go L29–L82 · 4e5c555]() - [sourcegraph/cmd/repo-service/main.go L96–L161 · 4e5c555]() - [sourcegraph/internal/service/worker.go L25–L45 · 4e5c555]() - [sourcegraph/docs/deployment.md L3–L17 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L180–L240 · 4e5c555]() - [sourcegraph/internal/httpserver/website_access.go L15–L36 · 4e5c555]() - [sourcegraph/docs/authentication.md L1–L5 · 4e5c555]() - [sourcegraph/README.md L41–L63 · 4e5c555]() --- ## Pinned Search and Reads # Pinned Search and Reads Source Graph answers each request at exactly one Git commit. It first turns the requested revision into a commit inside the repository's retention window, then searches the index or reads Git at that commit, and returns the commit with the result so the caller can keep using it. This page explains how revisions resolve, how versions are kept and indexed, what bounds a search or read, and why the approach is faster than running `rg` over a checkout. ```mermaid sequenceDiagram participant A as Agent participant S as Source Graph participant Z as Zoekt index participant G as Git mirror A->>S: search(repo, pattern) — no revision S->>S: resolve default branch to commit C S->>Z: generated query at C Z-->>S: bounded hits S-->>A: hits + Commit C + Partial / Truncated / Coverage A->>S: read(repo, revision C, path, lines) S->>G: blob at C S-->>A: numbered lines + Commit C + next range ``` ## How a revision resolves Every operation accepts an optional revision and resolves it with the same rules: | You pass | Source Graph uses | | --- | --- | | Nothing | The repository's discovered default branch when the policy follows it; otherwise the single configured `main` or `master` branch, at its last synchronized head | | A monitored branch name | That branch's last synchronized head | | A full 40-character lowercase commit SHA | That commit, if it is inside the retention window | | A short SHA, a tag, `HEAD` or another ref | Rejected (`SHORT_SHA_UNSUPPORTED`, `INVALID_REVISION`) | | An unmonitored branch | Rejected (`BRANCH_NOT_MONITORED`) | A commit outside the window returns `REVISION_NOT_ELIGIBLE` rather than a nearby substitute. Source Graph never silently replaces a requested baseline with another commit, so a caller that pins the returned commit gets the same snapshot on every later call. ## Which versions exist Each repository has a retention policy: one to eight monitored branches (optionally including the remote's default branch) and a window defined either by **days** (1–365) or by **count** (1–4096 first-parent commits per branch). Background synchronization fetches only the monitored branches — never tags — on the repository's sync interval, records each branch head and builds the set of eligible versions from the window. Many versions of one repository can therefore coexist. Indexing is separate from eligibility. After a successful sync, the service queues an index job for each branch head that is not yet indexed, and stops retrying a head after three failures. Older commits in the window stay readable from Git but are searchable only after someone with permission asks for them with `prepare`; searching an unindexed commit returns `INDEX_NOT_READY`. Each index is stored as a separate generation, and generations no longer referenced by any retained version are removed in the background, at most one per collection pass. ## What bounds a search Callers never send engine syntax. A search is a set of structured, `rg`-like fields — a line-oriented regular expression or literal, case folding, globs and directory paths — that the service compiles into an engine query at the resolved commit. The [Query Syntax]() reference lists every field. Results are a bounded first page. The first attempt returns up to 100 files and 1,000 matches with two lines of context; if the response would exceed its 2 MiB budget, the service retries with smaller pages and finally a file-only listing, all within a five-second deadline. The response metadata tells the caller what it got: - `Commit` and `Repository` identify the snapshot. - `Partial` means the engine stopped early, for example at its 10,000-match cap. - `Truncated` means more files or matches existed than were displayed. - `Coverage` describes what was indexed — text only, no symbol index, the registered paths and groups — so a zero-hit result is not proof that something is absent from the repository. ## What bounds a read A `read` returns an inclusive line range of one file at one commit, at most 500 lines and 256 KiB per call; when no range is given over MCP it starts at line 1 and covers up to 500 lines. The response says which lines were returned and where to continue, and flags truncation, binary content, unsupported encodings and Git LFS pointers instead of guessing. In a full-repository registration, reads go straight to Git and do not wait for indexing. In a monorepo registration, the path group must already be prepared at that commit (`CONTENT_NOT_READY` otherwise). `read_many` reads one to ten known ranges at one commit in a single MCP call, sharing a budget of 1,000 lines, 256 KiB and 30 seconds; each item reports its own content and error. ## Why it is faster than a checkout `rg` and `git grep` scan files on every call; the trigram index does that work once per commit. The project's README reports this comparison against the public demo repository (`context4ai/context`, 2,359 indexed files) and a local checkout of the same commit: | Query | Source Graph (server) | `rg` (local) | `git grep` (local) | `grep -r` (local) | | --- | ---: | ---: | ---: | ---: | | Literal, 13 matching files | 0.7–0.9 ms | 61 ms | — | — | | Literal, ~100+ matching files | 3.6–5.2 ms | 61 ms | 39 ms | 3.6 s | | Regex, no matches | 0.4 ms | 62 ms | — | — | Server time is the search duration the engine reports. The local tools ran on an Apple M4 Pro with a warm page cache. Add the network round trip — a few milliseconds within one region — for end-to-end latency. The gap widens as repositories grow, and the service also removes the need to check out every repository at the right revision. Speed depends on locality: each instance keeps its Git mirrors and indexes on its own disk, so deploy instances in the same region as the Agents that call them. How Context's own measurements compare answering with and without Source Graph is covered in [Knowledge Retrieval](). --- ## Sources - [sourcegraph/internal/service/scoped_search.go L120–L168 · 4e5c555]() - [sourcegraph/internal/service/scoped_read.go L32–L62 · 4e5c555]() - [sourcegraph/internal/service/service.go L289–L349 · 4e5c555]() - [sourcegraph/internal/mcpserver/server.go L30–L30 · 4e5c555]() - [sourcegraph/internal/control/model.go L22–L40 · 4e5c555]() - [sourcegraph/internal/gitstore/fetch.go L128–L146 · 4e5c555]() - [sourcegraph/internal/service/schedule.go L155–L230 · 4e5c555]() - [sourcegraph/internal/zoektclient/client.go L105–L190 · 4e5c555]() - [sourcegraph/internal/service/scoped_search.go L215–L260 · 4e5c555]() - [sourcegraph/internal/gitstore/read_content.go L13–L30 · 4e5c555]() - [sourcegraph/internal/mcpserver/server.go L54–L65 · 4e5c555]() - [sourcegraph/internal/service/read_many.go L13–L20 · 4e5c555]() - [sourcegraph/README.md L26–L39 · 4e5c555]() - [sourcegraph/README.md L80–L91 · 4e5c555]() --- ## Evidence for Context # Evidence for Context Context knowledge records, for every section, which source files and line ranges it was written from, each pinned to a commit. Source Graph can read any registered repository at any eligible commit. Together they let an Agent go from an answer to the exact code behind it without cloning anything: read the knowledge page, receive its recorded sources alongside the text, then read those sources at their recorded commits. ```mermaid flowchart LR ws["Knowledge workspace repo
knowledge/ + structure.yaml
+ context-evidence plugin"] -->|registered in| sg["Source Graph"] code["Source code repos
at recorded commits"] -->|registered in| sg agent["Agent with
context-inspect-search"] -->|read knowledge page| sg sg -->|text + references| agent agent -->|read cited range at its commit| sg ``` Two pieces make this work: a WebAssembly plugin that Context places in the knowledge workspace repository, and the query Skill's access policy for using Source Graph. ## The evidence plugin Source Graph lets a repository ship plugins named `.sourcegraph.wasm`. When it serves a `read` or `read_many`, it discovers plugins in that repository at the same commit being read and runs them after the ordinary read has succeeded; their output is appended to the returned text. Plugins have no network, filesystem or process access — the host binds every file they read to the same repository, commit and readable scope. Context's plugin is `context-evidence.sourcegraph.wasm`. For each returned file under `knowledge/` that ends in `.md`, it: 1. Reads the full article at that commit only to locate its `` markers, then selects the sections that overlap the lines actually returned. 2. Looks up those sections in `knowledge/structure.yaml`, the approved structure that records each section's references. 3. Appends a YAML `references:` list for the item, deduplicated. Repository references with a full commit and a supported remote become commit-pinned web URLs with line anchors; other references keep their structured fields. If anything fails, the ordinary text is still returned and the plugin adds diagnostics instead of references. A reference is recorded metadata, not proof that the source was reread during this query. ## Getting the plugin into the repository `context init` writes the plugin when the workspace is the repository root, or when it has no enclosing Git repository. For an existing workspace run: ```bash context evidence install --format json ``` A workspace nested inside a larger repository needs an explicit choice: `--repository-root ` when Source Graph hosts the whole repository, or `--plugin-root ` when it hosts only a registered path; the workspace directory relative to that root is then passed to the plugin as `workspace_root`. The installer upgrades only files it recognizes as earlier versions of the plugin, preserves unknown or modified files with the same name, and never commits or pushes — commit the file and let Source Graph synchronize before relying on it remotely. ## How the query Skill uses Source Graph The `context-inspect-search` Skill reads Source Graph through a read-only MCP server the host names `context-sourcegraph`. `CONTEXT_QUERY_ACCESS_MODE` decides when: | Mode | Behavior | | --- | --- | | `auto` (default) | Reuse suitable local material first, then prefer the authorized read-only service before local retrieval | | `remote` | Read knowledge and original code only through the service; never clone automatically, and on failure use only material that already carries a version | | `local` | Local retrieval only; no MCP required | For remote knowledge, the Skill resolves a branch once and pins the returned full commit for every knowledge read in that answer. It searches within `knowledge/**`, reads the matching sections, and consumes the references the plugin already attached rather than rereading to request them; when a host does not enable plugins by default it asks for `plugins: [{"name":"context-evidence"}]` once. ## Reading the cited code For code, the Skill passes the exact repository from the source registration, the recorded full commit as the revision, and a repository-root-relative path that already includes any registered subpath. It reads directly when the file is known and searches that repository and commit when it is not, without a discovery pass before every query. It never replaces a missing baseline with the default branch. Each piece of evidence keeps four things together: the repository, the returned full commit, the path and the returned line range. Multi-step reads stay on the same commit, follow the continuation range the service returns, and treat `Partial`, `Truncated` and coverage as limits rather than proof of absence. With `read_many`, every item's content and error are checked separately. ## Related pages - [Reading Code Evidence Remotely]() — turning this on for an Agent. - [Evidence Chains and Index First]() — why every section records its sources. - [Pinned Search and Reads]() — how Source Graph resolves commits and bounds reads. --- ## Sources - [context/packages/context-evidence-wasm/README.md L1–L5 · 3b0ce0a]() - [sourcegraph/docs/ref/repository-plugins.md L1–L15 · 4e5c555]() - [sourcegraph/internal/service/plugins.go L70–L116 · 4e5c555]() - [context/packages/context-evidence-wasm/src/lib.rs L144–L235 · 3b0ce0a]() - [context/packages/context-evidence-wasm/README.md L60–L96 · 3b0ce0a]() - [context/packages/context-cli/README.md L1–L12 · 3b0ce0a]() - [context/packages/context-cli/src/project/evidencePlugin.ts L70–L92 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L47–L56 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L158–L190 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L266–L276 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L302–L321 · 3b0ce0a]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L158–L166 · 3b0ce0a]() --- ## Why Graph Engineering # Why Graph Engineering Agent Graph is a work-contract layer for Agent Skills. You describe a workflow as a small graph of legal steps; at runtime it reads the current **Facts** and tells an Agent what to do next, which files to read for that step and what proves the step is done. It never calls a model, assigns Agent identities, moves shared state or schedules workers — it coordinates the work, not the Agents. Existing Agents and hosts consume its Routes and keep the execution boundary. Agent Graph ships as `@c4a/agent-graph`: versioned file specifications with JSON Schemas, a Node.js SDK and an `agent-graph` CLI for authoring, inspecting, testing, building and resuming workflows. Context runs its whole knowledge workflow on it; see [Agent Graph in Context](). The source code, issues and discussions live in the GitHub repository [context4ai/agent-graph](https://github.com/context4ai/agent-graph). Where to go next: - **How it works:** [Core Model](), [Runs and Recovery](), [Skills and Providers](). - **Guides:** [Getting Started](), [Authoring Graphs](), [Testing and Publishing](). - **Reference:** [Specification](), [CLI and SDK](), [Migration](). ## The problem Agents usually know enough. The harder problem in a long task is knowing which part applies **now**, which action is legal next, what proves that action is complete and where to resume after an interruption. Making the prompt longer does not solve this reliably: a complex Skill in one document has a flat topology, every rule sits next to every other and is often loaded together, and the Agent has to infer the current phase from the conversation. Such a workflow is also hard to test without running the whole model behavior. > Context should be discovered, not accumulated. The plan is explicit; the path is selected from current reality. ## A small example An Agent has one job: write a draft, check it, finish. ```mermaid flowchart LR write["Write draft"] -->|"completed"| check["Check draft"] check -->|"completed"| done(["Done"]) ``` The host can observe two facts: `draft.saved = true` and `review.passed = false`. The draft exists but has not passed the check, so Agent Graph returns **Check draft** as the current Route. Nothing is guessed from the conversation: when `review.passed` becomes `true` the next evaluation reaches **Done**; while it stays `false` the Route stays **Check draft**. Four ideas carry the example: the **Graph** describes the legal sequence, **Facts** describe what is true now, the **Route** is the next legal step selected from those Facts and the **Action** tells the Agent or host how to perform it. Real workflows add required files, human Gates, explicit Outcomes, choices and recovery paths without changing this loop. ## The Graph Engineering principles "Graph Engineering" is an emerging architecture label, not an official protocol or a single implementation; writing under that name covers feedback and audit loops, durable multi-Agent organizations and dynamically generated task graphs. Agent Graph takes the engineering principles without claiming the term, and narrows the question to: *how can an Agent discover the next legal action and only the context it needs, while a long workflow stays observable, testable and recoverable?* - **From prompt to topology.** Prompt engineering improves one interaction and context engineering shapes what one interaction sees. Graph Engineering adds how information, authority, actions, evidence and feedback move across many interactions. A graph does not add context; it creates boundaries so the Agent loads a small, relevant slice after a Route is chosen. - **Reality stays outside the optimizer.** Agent Graph separates **facts** (observable state from a Provider or host), **outcomes** (explicit results of an attempted action) and **instructions** (procedures). Instructions cannot assert facts, and a recorded success without the evidence a node requires becomes `unverified`. Source digests, build receipts, test results and scoped review decisions are typical external anchors; another model agreeing is useful evidence, not an anchor. - **Contracts, not diagrams of prose.** Only steps that are independently actionable, gated, recoverable, repeatable or testable become nodes; explanation stays in files. Every element carries a boundary contract — an Action its runner and effect, a Gate who decides, a node the facts it needs and the facts that prove it done — so the visual graph is a view of executable contracts. - **Graphs of loops.** Review, repair, polling and re-planning loops are explicit `repeat` edges with typed Outcomes and stop conditions. Each iteration is a Route and each result an event, so a host can checkpoint, enforce budgets or hand work to another Agent. - **Stable organization, dynamic work.** Graphs describe stable categories of work; current targets, dates and queue items are Facts resolved by stable host Actions, so the Graph never has to be rewritten per run. - **Progressive disclosure as structure.** A thin Skill holds the bootstrap loop, evaluation returns summaries and each Route returns only its own resources as file locations with digests, never document bodies. - **Observability without a mandatory runtime.** Evaluation can be stateless; an optional Run records events and outcomes at a path the host chooses. - **Testability before autonomy.** Route tests assert which step a known state exposes, without calling a model. ## How the principles become implementation | Principle | Agent Graph implementation | | --- | --- | | External reality | Restricted fact checks and `satisfiedBy` | | Boundary contracts | Strict JSON Schemas with closed object fields | | Typed feedback | Eight distinct Outcomes | | Progressive context | Required and recommended file Resource locations | | Explicit authority | Gates plus session-scoped authority input | | Recovery | Failure and repeat edges, Run events, checkpoint and resume | | Explainability | Deterministic Evaluation and Route, inspection, digests | | Stable reasons | Route reason codes plus an optional Code Catalog | | Testability | Declarative state-to-route cases | | Portability | Relative Provider references and host-selected stores | | Supply-chain clarity | Action effects, reachable-file bundles, content digests | Version 1 deliberately does **not** provide arbitrary expressions, self-modifying graphs, cross-Provider calls, model invocation or multi-Agent orchestration, parallel execution, edge-carried artifacts or shared mutable state, schedulers or durable timers, automatic trust in commands or third-party Skills, or semantic proof that an Agent's output is correct. Those limits keep it a standard and toolchain rather than another all-encompassing Agent framework. ## When to use it Not every Skill needs a Graph. Keep a short, single-session task in `SKILL.md`. Adopt Agent Graph when a host can supply trustworthy external facts and the work truly needs verifiable completion, recovery across sessions, or testable routing and human Gates. It pays off for: - **large knowledge without a giant prompt** — procedures, schemas and manuals stay files, loaded only when a Route needs them; - **long tasks across session boundaries** — Facts and Outcomes reconstruct where the work is; an optional Run adds events and checkpoints; - **plans that react without drifting** — the Graph fixes the legal choices and stop conditions, current evidence picks the path; - **testing before model behavior** — references, cycles, resource boundaries and expected Routes are checked without a model. Agent Graph does not rewrite its own plan. Runtime routing follows the evidence; people improve the Graph from events, diagnostics and route tests. Installing the CLI alone does not make an Agent follow a workflow: a Provider defines the contract, a Skill makes it discoverable and a host supplies facts, enforces Gates and records outcomes. Pick your starting point in [Authoring Graphs](). --- ## Sources - [agent-graph/README.md L1–L12 · 9e8b98a]() - [agent-graph/README.md L80–L91 · 9e8b98a]() - [agent-graph/package.json L1–L12 · 9e8b98a]() - [agent-graph/README.md L12–L16 · 9e8b98a]() - [agent-graph/docs/en/graph-engineering.md L13–L22 · 9e8b98a]() - [agent-graph/README.md L20–L50 · 9e8b98a]() - [agent-graph/docs/en/graph-engineering.md L1–L37 · 9e8b98a]() - [agent-graph/docs/en/graph-engineering.md L39–L98 · 9e8b98a]() - [agent-graph/docs/en/graph-engineering.md L99–L124 · 9e8b98a]() - [agent-graph/docs/en/graph-engineering.md L125–L153 · 9e8b98a]() - [agent-graph/README.md L14–L16 · 9e8b98a]() - [agent-graph/README.md L52–L70 · 9e8b98a]() - [agent-graph/README.md L93–L98 · 9e8b98a]() --- ## Core Model # Core Model Agent Graph turns a static work contract and the current state into one legal next step. Every interaction follows the same loop: ```mermaid flowchart LR facts["Facts, Outcomes, authorities"] --> evaluate["evaluate: status, revision, routes"] evaluate --> resolve["route: one Route at that revision"] resolve --> act["Agent or host performs the Action"] act --> record["Record an Outcome, refresh Facts"] record --> facts ``` Evaluation and route resolution are read-only and deterministic: the same definitions and inputs give the same revision, the same Routes and the same order. Nothing is executed by Agent Graph itself; it returns what to run and what to read. ## Providers and Graphs A **Provider** is one independently versioned trust and publication boundary. Its manifest (`agent-graph.provider.v1`) lists Graph files explicitly — nothing is discovered by scanning — plus an optional Code Catalog and the supported toolchain range. References stay inside the Provider root, and several Providers stay isolated from each other. A **Graph** (`agent-graph.graph.v1`) is a deterministic route definition: named `entrypoints`, nodes and edges. Its topology is static. Target names, dates, phases or queue items belong in Facts, and a stable host Action resolves the concrete target, so a Provider never regenerates nodes because parameters changed. Every Graph declares at least one terminal node. | Node kind | Required field | Meaning | | --- | --- | --- | | `action` | `action` | Work done by a command, script, Agent Skill or host handler | | `gate` | `gate` | A decision that needs user or session authority | | `subgraph` | `graph`, `entry` | Enter another Graph in the same Provider | | `terminal` | `terminalOutcome` | End the frame with an explicit Outcome | Action and Gate nodes must carry a `reasonCode` starting with `route.` — a stable machine explanation of why the Route is offered. `priority` ranks routes that are legal at the same time; it never decides semantic fitness. `join: all` (the default) needs every incoming edge to match, `join: any` needs one. ## Facts Facts are observed state supplied by the Provider integration or host. Nodes test them with a deliberately small data model, not expressions: ```yaml requiresFacts: - path: sources.registered equals: true satisfiedBy: - path: artifact.digest exists: true ``` `path` is a dotted lookup in which numeric segments index arrays (`items.0.digest`); each check has exactly one of `exists` or `equals` with a scalar value. There is no JavaScript, template expansion or shell evaluation. - `requiresFacts` makes a node legal only under current state; if a check fails the node is `blocked` with a `required-fact-missing` diagnostic. - `satisfiedBy` proves a node complete without replaying it. Matching facts make it `completed` even with no Run record; a recorded `completed` without them becomes `unverified`. A claim made in conversation never creates a fact. ## Outcomes and edges Outcomes are the typed results of nodes: ```text completed partial failed unverified skipped pending blocked waiting-user ``` They are not aliases: `partial`, `unverified` and `skipped` never silently become `completed`, because the difference is what lets a graph recover. Every edge names the Outcomes that permit it (default `[completed]`): | Edge kind | Meaning | | --- | --- | | `flow` | General control transition | | `consumes` | The target consumes an artifact the source produced | | `requires` | The source is a prerequisite of the target | | `gatedBy` | A Gate source resolves the target's policy boundary | | `repeat` | A matching result re-arms an Action or Gate for another iteration | All non-repeat kinds use the same reachability rule; the kind records causal intent for inspection, tests and host policy. Edges carry no values or artifacts — hosts persist outputs and publish references or digests as Facts. Non-repeat edges must form an acyclic graph, so every loop is an explicit `repeat`. Fan-out and fan-in describe legal reachability, not parallel execution. ## How an Evaluation is computed Starting at the entry node, the evaluator repeatedly settles each reached node's Outcome — from `satisfiedBy` facts, then the recorded Outcome, then `pending` — and follows every edge whose Outcomes match, honouring `join` and re-arming `repeat` targets. Subgraph nodes evaluate their child Graph in place and take its terminal Outcome. Then: - a pending Action becomes an **immediate** candidate; - a pending Gate becomes a **requires-user** candidate, or an immediate one when the input carries its delegatable authority; - if exactly one terminal Outcome is reached the frame is `complete`; conflicting terminal Outcomes are an `error` (`terminal-outcome-ambiguous`); nothing reachable is `blocked` with `no-route`. Candidates are ordered by availability (immediate, then requires-user), then by higher `priority`, then by route ID. The `agent-graph.evaluation.v1` result has a `statusCode` (`actionable`, `waiting-user`, `blocked`, `complete` or `error`), an optional terminal `outcome`, one `primaryRoute` and up to three `alternativeRoutes` — each with its `reasonCode`, an optional Catalog `hint` and a label — plus compact diagnostics. A `route-alternatives-truncated` info diagnostic reports when more alternatives exist. The `revision` is a digest of the selected Graph's same-Provider dependency closure, the facts, the normalized outcomes and the authorities. Timestamps on outcome records and files used only by unrelated Graphs do not change it. ## Routes `route` resolves one route ID from an Evaluation into an `agent-graph.route.v1` plan: | Field | Content | | --- | --- | | `revision`, `routeId` | The Evaluation it belongs to; the route ID is derived from that revision | | `graph`, `node`, `callPath` | Where the step sits, including the Subgraph path | | `statusCode`, `reasonCode`, `hint`, `availability` | Why and how it is offered | | `action` | Action identity, runner and effect | | `commandPlan` | The exact command, script invocation or host handler, with its working directory | | `resources` | Required and recommended locations, each keeping its complete file, Graph-action or Host-action location envelope and a `readState` of `current` or `read-required` | | `gate` | For Gates: authority, resolution, and the separate inspection and resolution Actions | | `afterAction` | `recordNode` — the state key to record — and `evaluate: true` | If the caller passes the Evaluation's revision and the state has changed, resolution fails with `route-revision-stale`; a route ID no longer available fails with `route-stale`. An Agent Skill used by an `agent` Action is added as the first required resource. Document bodies are never embedded; the Route points to files and digests. ## Gates and authority ```yaml kind: gate reasonCode: route.review.approval-required gate: id: result-review prompt: Review the prepared result. authority: review delegatable: true inspectionAction: actions/inspect-review.yaml resolutionAction: actions/apply-review.yaml delegated: inspection: skip resolutionAction: actions/accept-review.yaml resources: { required: [], recommended: [] } ``` Without matching authority the Route is `waiting-user` and its ordinary `commandPlan` is empty. The optional read-only **inspection Action** prepares evidence for the decision and stays available while the Gate waits. The optional **resolution Action** (effect `write` or `external`) applies the decision, but a host must not run it until the user has confirmed. When `delegatable` is true and the current evaluation or Run carries the named authority, the Gate becomes actionable with `resolution: session-authority`; the `delegated` policy can then skip inspection, swap in a different resolution Action and replace the Gate's resources. Authority belongs to the current input or Run, never to the Provider definition. It resolves only delegatable Gates and never satisfies facts or bypasses validation. Context's fully managed mode is built on exactly this mechanism; see [Agent Graph in Context](). ## Explaining every step Every Route carries a machine-stable `reasonCode`. A Provider may add a Code Catalog (`agent-graph.code-catalog.v1`) whose `route-reason` entries give each code a short summary and an optional explanatory document, and whose `diagnostic` entries name product conditions with a severity. Once a Catalog exists, every Action and Gate reason code must be listed in it, turning reasons into a closed, documented set. Hosts and Agents branch on schema, status, reason and diagnostic codes, never on human descriptions. The exact fields of every object are in the [Specification](); how Runs persist Outcomes is in [Runs and Recovery](). --- ## Sources - [agent-graph/docs/en/README.md L20–L32 · 9e8b98a]() - [agent-graph/src/evaluator.ts L356–L391 · 9e8b98a]() - [agent-graph/src/router.ts L261–L354 · 9e8b98a]() - [agent-graph/docs/en/specification.md L7–L28 · 9e8b98a]() - [agent-graph/docs/en/specification.md L44–L81 · 9e8b98a]() - [agent-graph/docs/en/authoring.md L18–L32 · 9e8b98a]() - [agent-graph/docs/en/specification.md L84–L105 · 9e8b98a]() - [agent-graph/src/evaluator.ts L52–L60 · 9e8b98a]() - [agent-graph/src/evaluator.ts L137–L149 · 9e8b98a]() - [agent-graph/docs/en/specification.md L138–L166 · 9e8b98a]() - [agent-graph/docs/en/specification.md L330–L338 · 9e8b98a]() - [agent-graph/src/types.ts L1–L20 · 9e8b98a]() - [agent-graph/src/evaluator.ts L166–L326 · 9e8b98a]() - [agent-graph/src/evaluator.ts L126–L135 · 9e8b98a]() - [agent-graph/src/evaluator.ts L337–L391 · 9e8b98a]() - [agent-graph/docs/en/specification.md L352–L368 · 9e8b98a]() - [agent-graph/src/router.ts L198–L215 · 9e8b98a]() - [agent-graph/docs/en/specification.md L107–L136 · 9e8b98a]() - [agent-graph/examples/review-gate/graphs/review.yaml L1–L35 · 9e8b98a]() - [agent-graph/src/evaluator.ts L277–L291 · 9e8b98a]() - [agent-graph/docs/en/specification.md L310–L328 · 9e8b98a]() - [agent-graph/docs/en/specification.md L404–L410 · 9e8b98a]() --- ## Runs and Recovery # Runs and Recovery ## Facts first, history second The most robust state is the real system. When a host can observe what has happened — an artifact digest, a source revision, a test receipt, a deployed version — it passes those values as Facts and evaluation needs no stored state at all: ```bash agent-graph evaluate build --manifest provider.yaml --facts @observed-facts.json --format json ``` Such facts survive restarts and can invalidate stale work by themselves. When trust depends on who observed a value, the Fact carries the observer's identity and health too (for example `sourceRevision`, `available`, `fresh`). The host applies its own clock, lease or health policy and publishes stable states; Agent Graph never reads the wall clock. Because the whole Facts object is part of the revision, replacing an observer or a value turning stale invalidates an already resolved Route without touching the Graph. Use a **Run** only when you need execution history, a checkpoint for a long task, Outcomes that cannot be observed from outside, or repeated iterations. ## Runs A Run (`agent-graph.run.v1`) is optional, host-owned execution memory in one JSON file: | Field | Content | | --- | --- | | `provider`, `graph`, `entry`, `workspace` | What the Run executes | | `facts` | Facts supplied to routing | | `outcomes` | The latest Outcome record per fully qualified state key | | `authorities` | Session authorities currently granted | | `events` | Append-only, numbered events such as `run.started`, `node.outcome-recorded`, `facts.updated`, `run.checkpointed`, `run.resumed` | ```bash agent-graph run start monitor --manifest provider.yaml --state .runtime/monitor.json --workspace . agent-graph route monitor --manifest provider.yaml --state .runtime/monitor.json --format json agent-graph run record monitor/poll partial --state .runtime/monitor.json ``` After an Action, record its Outcome under the exact `afterAction.recordNode` key from the Route — a key such as `monitor/poll`, prefixed with the Subgraph call path when nested. Outcomes keep only the latest record per key, while events keep every iteration. `run start`, `checkpoint` and `resume` refuse to overwrite an existing file, and every write is validated against the Run schema and written atomically. There is no default directory: the host chooses where Runs live. ## Loops ```yaml edges: - { from: poll, to: poll, kind: repeat, outcomes: [partial] } - { from: poll, to: done, outcomes: [completed] } ``` Recording `partial` re-arms `poll`; recording `completed` reaches the terminal. Agent Graph does not busy-wait, sleep or run the loop itself: the Agent or host decides when to take each Route and may stop by its own time or budget policy. Transport retries, model retries and workflow Outcomes are different things — an exhausted retry should be recorded as `failed` or `unverified`, never `completed`. ## Partial work and failure paths Recovery is modelled with explicit Outcomes and edges, not hidden in prose: ```yaml edges: - { from: verify, to: done, outcomes: [completed] } - { from: verify, to: repair, outcomes: [failed, unverified] } ``` Use `partial` when some required work succeeded and some did not; counts and receipts go in event details or Facts, while routing still uses the Outcome. Never drop the failed items and report the rest as a complete batch. When a result must be provable, add `satisfiedBy`: a recorded success without its proof evaluates as `unverified`, so a crash or handoff between "done" and "proved" routes deterministically to verification or repair. ## Checkpoint and resume ```mermaid flowchart LR run["Run file: facts, outcomes, events, authorities"] -->|"run checkpoint"| cp["Checkpoint: same state, authorities removed"] cp -->|"run resume"| resumed["New Run file: authorities cleared, event appended"] resumed --> eval["Refresh Facts, then evaluate again"] ``` ```bash agent-graph run checkpoint --state .runtime/monitor.json --to .runtime/checkpoints/before-handoff.json agent-graph run resume .runtime/checkpoints/before-handoff.json --state .runtime/resumed.json ``` A checkpoint is a validated copy of the Run with session authorities stripped. Resume copies it to a new path, clears authorities again, appends `run.resumed` and evaluates against the **current** Provider definitions. Authority must be granted again explicitly, so a checkpoint can never become a permanent unattended mode. Facts may have changed while paused, so the host refreshes them first; `satisfiedBy` checks run again. A checkpoint is execution memory, not a truth anchor. ## Rejecting stale plans Every Evaluation has a revision derived from the Graph closure, Facts, Outcomes and authorities, and every route ID is derived from that revision. An Agent passes the revision when resolving: ```bash agent-graph route main --revision --format json ``` If anything relevant changed in between, resolution fails with `route-revision-stale`; a route that is no longer available fails with `route-stale`. The Agent then evaluates again instead of executing a plan computed for older state. Hosts extend the same idea to their own write commands — Context binds every mutating command to the workflow revision that selected it, see [Agent Graph in Context](). ## Session authority Authority can be given to one evaluation (`--authority release.approve`) or set on a Run for a host-defined session (`run authority --set release.approve`). The host clears it when the user's delegation ends, and `run resume` clears it automatically. It only resolves Gates marked `delegatable` and never bypasses fact checks, schema validation, verification or non-delegatable Gates. ## What the host owns Agent Graph selects a legal Route; it does not own the resources used to execute it. A host running several Actions in one process should give each one an execution scope for child processes, timers, temporary files, locks and watchers, closed in reverse order before it publishes the Action's receipt or evaluates again. That scope is not a transaction: lasting results still need their own revision checks, atomic commits and verification, published as Facts. The same holds for host-materialized resources: the host validates the result envelope against the computed input digest, persists it as a Run Fact or in its own store, and on recovery reuses it only if the digest still matches; a mismatch must lead to an explicit `failed` or `unverified` path rather than silent re-execution. Run files, checkpoints and caches live wherever the host chooses — a product runtime directory, an ignored workspace folder, a task store or a temporary location. Provider bundles stay read-only, and materialized resources are cache entries that must be reproducible after deletion. --- ## Sources - [agent-graph/docs/en/runtime-and-recovery.md L1–L18 · 9e8b98a]() - [agent-graph/docs/en/authoring.md L72–L92 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L23–L26 · 9e8b98a]() - [agent-graph/src/runStore.ts L1–L66 · 9e8b98a]() - [agent-graph/src/runStore.ts L74–L93 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L26–L45 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L47–L71 · 9e8b98a]() - [agent-graph/src/evaluator.ts L235–L245 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L72–L88 · 9e8b98a]() - [agent-graph/src/evaluator.ts L137–L149 · 9e8b98a]() - [agent-graph/src/runStore.ts L113–L136 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L90–L104 · 9e8b98a]() - [agent-graph/src/router.ts L261–L279 · 9e8b98a]() - [agent-graph/src/evaluator.ts L81–L84 · 9e8b98a]() - [agent-graph/src/evaluator.ts L337–L354 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L106–L122 · 9e8b98a]() - [agent-graph/src/runStore.ts L104–L111 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L18–L24 · 9e8b98a]() - [agent-graph/docs/en/runtime-and-recovery.md L124–L143 · 9e8b98a]() --- ## Skills and Providers # Skills and Providers Agent Graph extends Agent Skills instead of replacing them. Each part of an integration has one job: ```mermaid flowchart LR skillNode["Skill: name, description, binding"] --> providerNode["Provider bundle"] providerNode --> graphNode["Graph and Entry"] graphNode --> routeNode["Route for current Facts"] routeNode --> resourceNode["Required and recommended Resources"] hostNode["Host: Facts, execution, Gates, storage"] --> routeNode ``` | Part | Responsibility | | --- | --- | | Skill | Advertise when the capability applies and bind Provider, Graph and Entry | | Provider bundle | Define the static legal work, Resources, Gates, reason codes and route tests | | Host | Resolve bundles, observe Facts, persist state, materialize dynamic Resources, run host Actions, enforce Gates | | Agent | Consume the selected Route, read required Resources, do the work and report an Outcome | | Agent Graph | Validate contracts and deterministically evaluate and resolve Routes | ## Binding a Skill A host still uses the Skill's `name` and `description` to decide whether it matches a request. Once selected, three metadata fields form one machine binding: ```yaml --- name: release-package description: Inspect, review, and release a package through the installed workflow. metadata: agent-graph: path:../../release-graph/provider.yaml agent-graph.graph: release agent-graph.entry: default --- ``` | Field | Purpose | | --- | --- | | `agent-graph` | Locate the Provider | | `agent-graph.graph` | Select one Graph in it | | `agent-graph.entry` | Select a public entrypoint in that Graph | All three are required and validated together; the Agent never infers the Graph or Entry from prose. The Skill body keeps only the bootstrap contract — evaluate the bound Graph, resolve the Route, read every required resource marked `read-required`, stop at unresolved Gates, record an explicit Outcome and evaluate again. Phase procedures, schemas and generated context stay Route resources instead of being copied into the Skill. ## Locating Providers - **`path:`** resolves from the directory of that exact `SKILL.md`, never from the process working directory, and points to a source manifest or a built `manifest.json`. The Provider directory can have any name. - **`provider:`** delegates the location to a host registry or bundle resolver, for example a registry file mapping `company/release` to an installed `manifest.json`. The registry belongs to the host. Skills must not hard-code npm prefixes, plugin cache versions or machine paths, and there is no global `~/.agent-graph` or per-project `.agent-graph` directory. The host separately decides where bundles are resolved from, where Run files live (`--state`) and where dynamic resources are cached (`--cache`). ## One Provider, many Skills Several Skills can share one Provider and select different Graphs or Entries; Graph files, procedures and schemas stay single-source, and sharing an Action or Resource creates no execution dependency. One host can also install several Providers: their identities and state stay separate by Provider ID, manifests are never merged, the current Skill picks its own Provider, and a Subgraph cannot call into another Provider in version 1. Each plugin publishes its own bundle instead of mutating a shared manifest. Graphs stay static while work stays dynamic. Instead of a node per module, document or date, a stable host Action such as `handler: batch.process-next` receives the same Facts used for evaluation and resolves the concrete target itself, then the host refreshes Facts and evaluates again. ## Resources Long material lives in Resources declared on the node that needs it. Three independent protocols can appear in the same Route: | Protocol | What it is | How it is delivered | | --- | --- | --- | | File (`agent-graph.resource-location.file.v1`) | Static procedures, diagnostics, templates, schemas and Skills; Markdown carries `id`, `kind` and `media-type` in frontmatter, other formats use a small descriptor | Absolute installed path, media type and content digest | | Graph action (`agent-graph.resource.graph-action.v1`) | A dynamic context view whose materializer is a read-only command or script Action | An opaque materialization request bound to the Route revision; runs only when the host calls `resource materialize` | | Host action (`agent-graph.resource.host-action.v1`) | A resource the integrating host produces through a stable handler with versioned input and output schemas | Handler, input schema and canonical input value; Agent Graph computes the input digest and validates the returned envelope | Normative instructions belong in procedures; generated or workspace-derived evidence does not. Routes return locations and digests, never document bodies, so routine output never becomes an accidental prompt. ## Materializing context views Evaluation and route resolution never run a materializer. `resource materialize` runs it explicitly with the selecting Route's revision, writes stdout to a content-addressed file in the host-chosen cache (`.json`, `.md`, `.txt` or `.bin` by media type) plus a receipt recording the revision and digest, and returns a location the host can check for staleness. The process gets `AGENT_GRAPH_PROVIDER_ROOT`, `AGENT_GRAPH_WORKSPACE`, `AGENT_GRAPH_REVISION` and `AGENT_GRAPH_INPUT` (JSON), plus only a minimal inherited environment — `PATH`, temporary-directory, locale and time-zone variables and their Windows equivalents. SDK hosts can add variables explicitly. Defaults are a 30-second timeout, 10 MiB of stdout and 1 MiB of stderr; exceeding one terminates the process without writing a receipt. `effect: read` is a declared contract, not a sandbox, so hosts isolate untrusted Provider code themselves. For a host-action resource, materialization returns `materializer-host-required`: the host invokes the handler, echoes the computed input digest, returns exactly one inline value or managed resource reference, validates the content against the Provider's output schema and persists it before exposing it to the Agent. ## Read receipts To avoid re-reading unchanged material, a host may attach an `agent-graph.resource-read-receipts.v1` set for the current conversation when resolving a Route. Each Route resource then gets a `readState`: - `current` — a receipt matches: the same ID and exact digest for a static file, or the same ID and the selecting Route revision for a dynamic view; - `read-required` — anything else, including no receipt or a stale one. A receipt may be issued only after the Agent actually read that content and while it is still in the conversation. Receipts are scoped to one Provider, are never stored in Runs or checkpoints, and are not Facts, Outcomes, authority or proof that an Action finished — they only suppress redundant reads. ## A thin host ```ts import { evaluateGraph, loadProvider, resolveRoute, resolveSkillBinding } from "@c4a/agent-graph"; const binding = await resolveSkillBinding(skillPath, { registry }); const provider = await loadProvider(binding.manifestPath); const { evaluation } = evaluateGraph(provider, binding.graph, binding.entry, currentState); if (evaluation.primaryRoute) { const route = await resolveRoute(provider, binding.graph, binding.entry, evaluation.primaryRoute.routeId, currentState, evaluation.revision); // Present the route's resources and action to the Agent; do not execute implicitly. } ``` Use the SDK for an in-process Node.js host, or the JSON CLI when the host runs in another runtime or needs a process boundary; both read the same files. Only explicitly named authoring, Run, build and materialization functions write anything. The full export list is in [CLI and SDK](). --- ## Sources - [agent-graph/docs/en/adoption-paths.md L52–L66 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L1–L8 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L1–L28 · 9e8b98a]() - [agent-graph/README.md L116–L148 · 9e8b98a]() - [agent-graph/docs/en/specification.md L30–L41 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L29–L72 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L107–L118 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L73–L105 · 9e8b98a]() - [agent-graph/docs/en/specification.md L203–L270 · 9e8b98a]() - [agent-graph/docs/en/authoring.md L124–L154 · 9e8b98a]() - [agent-graph/src/materialize.ts L40–L100 · 9e8b98a]() - [agent-graph/src/materialize.ts L186–L237 · 9e8b98a]() - [agent-graph/docs/en/specification.md L234–L252 · 9e8b98a]() - [agent-graph/docs/en/specification.md L278–L309 · 9e8b98a]() - [agent-graph/src/router.ts L217–L236 · 9e8b98a]() - [agent-graph/docs/en/skills-and-providers.md L119–L159 · 9e8b98a]() - [agent-graph/docs/en/adoption-paths.md L78–L82 · 9e8b98a]() --- ## Agent Graph in Context # Agent Graph in Context Context is the largest public Agent Graph adopter, and it shows when a graph is worth having. Its lifecycle is long and stateful: sources must be scoped and captured, one Indexer lifecycle turns every authorized input into a current Candidate batch, human Gates may pause the run, and approved knowledge must be closed, verified, translated, versioned and built. A plain Skill would need to carry all of that in its prompt and still could not prove what had already happened. Context is not evidence that every Skill needs a graph. It is evidence that a graph helps when a Skill fronts a workflow with external Facts, several Gates, repeated batches and a real recovery requirement. Agent Graph does not extract code, interpret documents or approve knowledge; Context remains the host. ## Who does what ```mermaid flowchart LR skill["/c4a:context Skill"] --> status["context status"] status -->|"Facts"| ag["Agent Graph evaluation"] ag -->|"Route"| current["workflow.current"] current --> agent["Agent reads resources and runs commands"] agent -->|"guarded writes"| host["Context host"] host -->|"new Facts"| status ``` | Layer | Responsibility in Context | | --- | --- | | Skill | Discovery and the small Route-consumption contract | | Context host | Observe files and external systems, execute commands, enforce authority, record evidence | | Provider | Bind the `workspace` Graph, entrypoints, Actions, resources and the reason-code catalog | | Graph | Describe legal lifecycle states, dependencies, Gates, loops and terminal outcomes | | Route | Expose one current action, its required resources and its completion contract | | Facts and Outcomes | Prove what has actually happened; conversation claims are not completion evidence | `context status` is the observation boundary: it inspects the workspace, supplies Facts to Agent Graph and returns `workflow.current` with the selected Route, reason code, command plan, Gate and only the resources needed now. The Context-side view of this loop is in [Workflow Execution](). ## One thin public entry Knowledge production has one public Agent entry, `/c4a:context`. Its first `context entry` call resolves initialization, workspace relocation or ordinary continuation, then hands control to `workflow.current`. The plugin's other public Skills — `context-plan` for planning, `context-inspect-search` for querying and `context-repo-content` for same-repository content — do not drive the lifecycle themselves; they hand plans and accepted knowledge suggestions back to this entry. The entry's body describes only how to start and how to consume a Route; phase procedures, schemas, source views, review contracts and package guidance live in independently addressable workflow resources. That is the [Skills and Providers]() pattern at scale: one small, stable shell in front of a large body of instructions that the Graph selects piece by piece. The detail has not been summarized away — it is separated, selected and made verifiable instead of being loaded on every turn. ## The published workflow The whole integration is public in the Context repository under `packages/context-cli/context-workflow/`: | Path | Contents | | --- | --- | | `provider.yaml` | Provider `c4a/context`, binding the `workspace` and `indexer` Graphs, Actions, Resources and the entrypoint | | `graphs/workspace.yaml` | The static top-level lifecycle, from task start through capture, Indexer lifecycle, review, close, package output, translation, version and build | | `graphs/indexer.yaml` | The single Indexer lifecycle: requirement confirmation, Provider selection, authorized worksets, partitioned authoring, reconciliation, layout and Candidate compilation | | `actions/` | Executable contracts: runner, host command or handler, effect, authority boundary and expected Outcome | | `resources/` | Procedures, dialogue files for human decisions, live workspace views, semantic references, diagnostics and manuals | | `codes.yaml` | Stable meanings for Route and diagnostic codes | | `tests/` | Route-selection tests from Facts, run without an Agent or model | The top-level `run-indexer-lifecycle` Action is an Agent Action that hands indexing to the Indexer Graph and is satisfied only when `indexer.lifecycle_current` is true. Repeated sources and partitions do not need repeated graph definitions: the workspace Graph has stable states such as "a capture target remains", and runtime Facts identify the current workset. ## Managed mode is a delegated Gate Context calls its unattended experience *managed mode*. That is a host concept, not an Agent Graph field: the host maps it to session-scoped authorities and each Gate's `delegated` policy. The final knowledge review shows the shape: ```yaml - id: review-current-batch kind: gate reasonCode: route.review.decision-required inspectionAction: actions/inspect-review.yaml resolutionAction: actions/apply-confirmed-review.yaml delegated: inspection: skip resolutionAction: actions/apply-managed-review.yaml resources: required: - resources/views/review-current.yaml gate: id: knowledge-review authority: context.knowledge-review delegatable: true satisfiedBy: - path: gates.knowledge_review_resolved equals: true ``` Without the authority the Route stops for a person. With `context.knowledge-review` granted for the session, the same Gate resolves through the host handler `context.review.approve-current`. A route test, `tests/managed-review.yaml`, pins exactly that: with the authority present it expects `primaryNode: review-current-batch`, `gateResolution: session-authority` and that resolution handler. Session authority never becomes permanent project configuration, and Routes that need semantic judgment or an unsafe repair still stop. ## Idempotent continuation Invoking the Skill again does not replay every instruction or repeat every write. With the same Provider bundle, Facts and Outcomes, Agent Graph selects the same Route, and unchanged resource receipts keep the same read state. Context binds mutating commands to the selected workflow revision and checks their external evidence: work already satisfied by workspace Facts is skipped, and a stale command is rejected instead of being applied to newer state. The boundary is explicit. Agent Graph makes evaluation repeatable and exposes completion contracts; the Context host makes each filesystem effect atomic, guarded or a proven no-op. Agent Graph does not make an arbitrary script idempotent by itself — see [Runs and Recovery](). ## Recording and replay With Context debug mode on, the host records CLI invocation boundaries and Agent Graph evaluations. A replay then shows which Route was selected at each Fact change, where a multi-source loop advanced and how many iterations completed, when an authority or review Gate paused progress, which reason code justified each transition and how the final package was reached. The [interactive replay](https://context4ai.github.io/context/case-studies/workflow/?lang=en) is normalized from a sanitized Context recording; its **Workspace graph** control draws the static contract, and each step links its Action and Resources back to the workflow files. Route traces like these expose wasteful loops, repeated resource reads, incomplete recovery paths and misleading status priorities, and those observations become new route tests and graph changes — the improvement loop described in [Why Graph Engineering](). ## Built with Context This documentation site is itself a Context knowledge workspace, produced through the same `/c4a:context` entry and workflow. - **Workspace.** The Portal repository root is the workspace: `package.json` declares it, `src/index.ts` registers sources and outputs, `src/indexers.yaml` states each reader group's needs, and `src/knowledge-map.yaml` holds the navigation. - **Sources.** Three community repositories, each pinned to one commit (Context first at `v0.7.60` and updated to `v0.7.61` before the final stage, Agent Graph at `v0.3.0`, and Source Graph at a commit without a release number), plus five sanitized notes on usage experience, measured compression, retrieval evaluation, the knowledge service Agent design and frequently asked questions. A maintainer reviewed each note before registering it. - **Plan.** Because the sources span three repositories, production started with a `context-plan` investigation and a PLAN report that split the site into six stages — getting started and Context internals; source, production, review, update and query guides; outputs, Indexers, the knowledge service, workspace maintenance, practices and the Context reference; Source Graph; Agent Graph; and the More menu with homepage links — plus one revision round that added seven pages and unified naming and links. - **Each stage.** `task prepare` and `task resume` opened a new production stage; the Agent wrote articles in batches by reader question, every section carrying references to source lines or notes, and submissions were checked for format, links and references. - **Review.** Each stage produced an HTML review report that was checked for unplaced navigation and diagrams that fail to render before approval. The maintainer reviewed the first two stages, then delegated review to the Agent, which checked each article against its sources and used `revise` to correct approved pages when it found a factual deviation. - **Translation and versions.** Approved articles and navigation titles were translated into Simplified Chinese by several parallel sub-Agents, with a script confirming that section markers, code blocks, links and inline code were unchanged. Each stage recorded a workspace version and Changelog entry, counting up from 0.1.0, before building the site and package. Three observations from the run: - One public entry carried every stage. After each interruption or new session, the Agent resumed from the Route that `context status` returned, not from conversation memory. - Several drafts disagreed with the source code — for example which error code a timeout returns, or what anonymous rate limiting counts. Section references made those checks possible one section at a time, and each was fixed before submission. - Revising an approved page changed only the affected sections instead of reproducing the whole article. - Updating the Context source from `v0.7.60` to `v0.7.61` did not restart production: `context verify` listed the pages whose cited source regions had changed or moved, `context update` offered them as candidates, and the Agent decided page by page whether a revision was needed. The More menu pages were written as new topics of the same update. --- ## Sources - [context/docs/en/case-studies/agent-graph-workflow.md L1–L9 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L90–L94 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L44–L55 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L34–L35 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L11–L21 · 3b0ce0a]() - [context/ARCHITECTURE.md L358–L380 · 3b0ce0a]() - [context/plugins/context/skills/context/SKILL.md L1–L30 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L23–L33 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/provider.yaml L1–L13 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L165–L180 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/graphs/workspace.yaml L182–L212 · 3b0ce0a]() - [context/packages/context-cli/context-workflow/tests/managed-review.yaml L1–L41 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L70–L74 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L38–L42 · 3b0ce0a]() - [context/docs/en/case-studies/agent-graph-workflow.md L76–L88 · 3b0ce0a]() - note:20261012/portal-production.md · portal-production.md L1–L25 --- ## CLI Commands # CLI Commands The `context` CLI holds the workflow state of a Context knowledge workspace. You rarely type these commands yourself: the Agent runs them, and most of them are returned by the current **Route** — the single next step that `context status` or a previous command hands back, often with an exact `--revision` to pass. Commands that drive the workflow print JSON with `--format json`, which is what the Agent reads. Run `context --help` for the full option list of any command. For the Skills that call these commands, see [Skills](); for a short tour, see [Commands and Skills](). ## Setup | Command | What it does | Key options | | --- | --- | --- | | `context entry [dir]` | Resolves the single Agent entry: plans initialization for a new directory or evaluates the workflow of an existing workspace | `--name`, `--language en\|zh-CN`, `--managed`, `--authority` | | `context init [dir]` | Initializes a Context knowledge workspace in the directory | `--name`, `--language`, `--allow-nonempty` (after explicit confirmation) | | `context plugin path` | Prints the bundled plugin root used by install | | | `context plugin status` | Shows the bundled plugin root and which Agents have the plugin globally | | | `context plugin install` | Installs the Agent plugin globally, or copies standalone Skills into a repository | `--agent claude\|codex\|cursor\|all`, `--local ` (also `auto-detect`, `standalone`), `--dry-run` | | `context evidence install [dir]` | Installs or safely upgrades the bundled remote code evidence plugin, without starting production | | | `context clean-cache` | Removes orphaned Claude Code plugin caches | `--dry-run` | ## Workflow | Command | What it does | Key options | | --- | --- | --- | | `context status` | Prints the workspace overview and the next Route | `--format table\|json`, `--view summary\|full`, `--managed`, `--authority` | | `context run [phase]` | Inspects or runs a declared phase; with no phase, advances deterministic Routes | `--list`, `--dry-run`, `--until blocked-or-complete`, `--max-steps`, `--deliver`, `--resume-writing` | | `context resource acknowledge-current` | Records that every resource required by the current Route was read | | | `context resource materialize ` | Writes one revision-bound Context view to a local file | | | `context action prepare-current` | Prepares or retries the current production batch directories without resubmitting accepted articles | `--revision`, `--input` | | `context action complete-current` | Submits the semantic output — a report decision, drafts, a Gate answer — for the exact current revision | `--revision`, `--input`, `--managed`, `--multi-agent`, `--preview` | ## Tasks and maintenance | Command | What it does | | --- | --- | | `context task prepare` | Previews or discards current task state; keeps knowledge, sources and other temporary files | | `context task resume` | Explicitly reopens cleared production from registered requirements and retained knowledge | | `context task adjust` | Adjusts current source and module inputs, or the knowledge map, without disturbing unrelated work (`--input`, `--schema`, `--inspect`) | | `context task maintain` | Registers a scoped page revision, regeneration or approved-output rebuild | | `context task advance-maintenance` | Executes the current maintenance transition | | `context task maintenance-status` | Shows maintenance requests and the current cancellation revision | | `context task cancel-maintenance ` | Cancels a pending maintenance request without discarding an active draft | | `context task retire` | Previews or applies retirement of an approved article and cleanup of references to it | | `context task recover` | Inspects or previews scoped recovery outside the normal Route | | `context task rollback` | Previews exact user-selected reversions and discarded drafts; never resets the repository | | `context task finish-rollback` | Finishes a rollback after close and all builds succeed | | `context update` | Checks acquired source changes against approved knowledge in confirmed scopes (`--input`) | | `context revise ` | Repairs one draft or approved page through the Indexer lifecycle (`--instruction`, `--regenerate`, `--timing after-batch\|priority`, `--move-to`) | ## Review | Command | What it does | Key options | | --- | --- | --- | | `context review html [collection]` | Renders a self-contained local review report | `--all`, `--out`, `--open` | | `context review list [collection]` | Lists draft candidates in the terminal | | | `context review apply ` | Applies scoped JSON or JSONL decisions and revision instructions | | | `context review approve-all [collection]` | Approves the whole current review scope | `--all`, `--confirmed` (your confirmation), `--managed` | | `context review approve ` / `reject ` | Approves or rejects one draft candidate | | | `context review deprecate ` | Marks an approved page deprecated without deleting it | | ## Delivery | Command | What it does | Key options | | --- | --- | --- | | `context close` | Closes approved knowledge: derives `structure.yaml` and runs final verification | `--format` | | `context verify` | Validates the workspace | `--compact`, `--view diagnostics`, `--page-size`, `--page-token` | | `context build` | Builds the declared packages and sites | `--verbose` | | `context translate status` | Reports translation freshness per locale | | | `context translate prepare` | Writes the pending translation task | | | `context translate submit` | Validates and saves translated articles and navigation titles | `--input` | | `context translate skip` | Publishes pending translations in the primary language for now | | ## Versions and packages | Command | What it does | Key options | | --- | --- | --- | | `context version inspect` | Shows formal changes since the current version tag or a given ref | `--base` | | `context version record` | Records the workspace SemVer and changelog entry | `--input` | | `context package site-url ` | Records a deployed site root in the site maps, without network checks | | | `context package template accept [package]` | Explicitly accepts an unchanged generated starter template | | ## Sources and Indexers | Command | What it does | | --- | --- | | `context source add repo\|file\|lark [date]` | Registers a repository, local file or Lark document module under a `YYYYMMDD` batch | | `context source add batch [date]` | Registers several modules under one batch | | `context source import` | Imports managed Markdown (notes, session summaries) or prefetched Lark content, singly or in a batch | | `context source discover` / `fetch` | Discovers a source inventory, or fetches a portable snapshot, without registering anything | | `context source batch-status ` | Reads a saved registration checkpoint | | `context source list` / `get ` | Lists registry entries, or shows one | | `context source rename ` | Renames a note or session summary and updates its references | | `context source remove ` | Previews or removes an unreferenced source and its snapshot | | `context source inspect [name]` | Shows repository module boundaries without extraction | | `context source ensure [name]` | Checks repository checkouts without cloning, checking out or resetting | | `context source recovery-plan [name]` | Plans recovery of missing repository checkouts without changing files | | `context source restore` | Restores repository checkouts from explicit local or clone decisions | | `context indexer catalog` | Lists bundled Skill names, descriptions and entries | | `context indexer report-benchmark` | Builds a forward-test report from an independently loaded oracle | ## Diagnostics | Command | What it does | | --- | --- | | `context debug enable` / `disable` | Turns workspace-local tracing on or off; disabling keeps existing traces | | `context debug status` | Shows debug configuration, counts and trace paths | | `context debug export` | Builds a replay projection from the event stream | Tracing can also be enabled at creation with `context init --debug`. --- ## Sources - [context/packages/context-cli/src/registerProjectLifecycleCommands.ts L29–L62 · 3b0ce0a]() - [context/packages/context-cli/src/registerProjectLifecycleCommands.ts L101–L150 · 3b0ce0a]() - [context/packages/context-cli/src/registerProjectLifecycleCommands.ts L63–L100 · 3b0ce0a]() - [context/packages/context-cli/src/registerPluginCommands.ts L18–L50 · 3b0ce0a]() - [context/packages/context-cli/src/commands/evidenceCommands.ts L6–L12 · 3b0ce0a]() - [context/packages/context-cli/src/commands/runProject.ts L202–L230 · 3b0ce0a]() - [context/packages/context-cli/src/commands/resourceCommands.ts L44–L95 · 3b0ce0a]() - [context/packages/context-cli/src/commands/actionCommands.ts L27–L80 · 3b0ce0a]() - [context/packages/context-cli/src/commands/documentRevisionCommands.ts L20–L188 · 3b0ce0a]() - [context/packages/context-cli/src/commands/documentRevisionCommands.ts L189–L230 · 3b0ce0a]() - [context/packages/context-cli/src/cli.ts L217–L398 · 3b0ce0a]() - [context/packages/context-cli/src/registerProjectLifecycleCommands.ts L151–L220 · 3b0ce0a]() - [context/packages/context-cli/src/commands/translateCommands.ts L28–L84 · 3b0ce0a]() - [context/packages/context-cli/src/commands/versionCommands.ts L11–L25 · 3b0ce0a]() - [context/packages/context-cli/src/registerPackageCommands.ts L11–L40 · 3b0ce0a]() - [context/packages/context-cli/src/project/sourceCommands.ts L260–L610 · 3b0ce0a]() - [context/packages/context-cli/src/project/indexerCommands.ts L29–L45 · 3b0ce0a]() - [context/packages/context-cli/src/project/sourceDiscoveryCommands.ts L1–L30 · 3b0ce0a]() - [context/packages/context-cli/src/commands/debugCommands.ts L44–L80 · 3b0ce0a]() --- ## Project API # Project API A Context knowledge workspace has two durable declarations with separate jobs: | File | Declares | | --- | --- | | `src/index.ts` | Source references, document capture, custom non-knowledge orchestration, and package outputs — through the `@c4a/context` SDK | | `src/indexers.yaml` | Long-term reader requirements, authorized target and supporting sources, and confirmed exclusions | Never describe the same knowledge transformation in both. The Agent edits these declarations when the current Route asks for a configuration change; you do not need to write code yourself. ## `defineProject` ```ts import { defineProject } from "@c4a/context"; export default defineProject({ sources: [], phases: [], packages: [], }); ``` The definition is declarative: loading it must not change knowledge or runtime state. ## Sources ```ts const repo = source("20260901", "component-lib"); const docs = source("20260901/product-docs", { type: "file" }); const handbook = source("20260901/handbook", { type: "lark" }); const note = source("20260908/decision-context.md", { type: "note" }); const session = source("20260908/design-discussion.md", { type: "sessions" }); const everyRepo = allSources("repo"); // spread inside sources: [...everyRepo] ``` | Type | Resolves against | Registered with | | --- | --- | --- | | `repo` (default), `file`, `lark` | `sources//index.yaml`; the name includes the registration date and module | `context source add …` | | `note`, `sessions` | Saved Markdown under `sources/note/YYYYMMDD/` or `sources/sessions/YYYYMMDD/`; no separate registry or capture phase | `context source import` | Saving a source does not select it — include its reference in `sources`. The source list enables acquisition and initial selection; the requirements and each Indexer's target and read scopes decide what it owns and may read. ## Capture phases ```ts captureFile({ source: docs }); captureFile({ source: docs, processor: mdxJsonDocs() }); captureLark({ source: handbook }); ``` Capture only creates a deterministic, readable snapshot; classification and writing follow the selected Indexer. Adding `--configure` to `context source add repo|file|lark|batch` generates the source references and default capture phases in `src/index.ts` for you. It keeps existing settings, is idempotent, and leaves custom or dynamic entries untouched with a `configuration.status: manual` hint. For many documents with the same settings, map the registry instead of repeating declarations: ```ts const registry = await loadSourcesRegistry({ rootDir: workspaceRoot }); const documents = registry.larks.map(entry => source(entry.name, { type: "lark" })); export default defineProject({ sources: documents, phases: documents.map(document => captureLark({ source: document })), packages: [], }); ``` File documents use `registry.files` with `captureFile`. Filter entries for a subset. `allSources("lark")` selects a whole collection and cannot be mapped into per-document phases. Capture boundaries do not dictate article boundaries. ## `customPhase` ```ts customPhase("project:refresh-catalog", async (ctx) => { await ctx.ensureSources(); }); ``` For project orchestration that neither publishes knowledge nor bypasses the Indexer lifecycle. Declare stable reads and writes when the phase has them. ## Packages ```ts kbPackage({ name: "component-kb", template: "src/package-templates/kb", select: { collections: ["codeindex", "architecture"] }, site: { title: "Component knowledge", base: "/" }, }); llmsPackage({ name: "component-context", template: "src/package-templates/llms", select: { collections: ["codeindex"] }, }); ``` | Field | Required | Meaning | | --- | --- | --- | | `name` | Yes | Lowercase, path-safe; output goes to `dist//` | | `template` | Yes | Template directory, or `{ path, vars }` | | `select` | No | `collections`, `okfRoots`, `include`, `exclude`; omit for all approved knowledge | | `navigation` | No | Directory-index policy; default `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }` | | `assets` | No | `{ delivery: "bundle" }` (default), `"git-raw"` with `urlPrefix`, or `"omit"`; optional `optimize` | | `site` | No (`kbPackage` only) | Adds a documentation site at `dist/-site/`, where `` is the name without one trailing `-kb` | Packages read approved `knowledge/` only; `dist/` is generated. Details are in [Package Templates](). ## Site options | Option | Meaning | | --- | --- | | `title`, `description` | Site title and description | | `lang` | Primary language, default `en-US` | | `base` | Deployment path such as `/` or `/docs/` | | `titleLink` | Target of the top-bar title; defaults to the site home | | `home` | `title`, `slogan`, `description`, hero `actions` (`text`, `link`, `theme`), and `resources` (each needs `href`, `command` or both) | | `locales` | Additional reader languages keyed by BCP 47 tag, each with optional `label`, `title`, `description`, `home`; must differ from `lang` | | `nav` | Top links after the knowledge sections: `text`, `link`, optional per-locale `locales` text | | `more` | Items placed in the More menu before the built-in LLM Docs and Changelog entries: `text` with exactly one of `link` or `target.artifact_ref` (an approved article shown only there) | | `socialLinks` | `icon` (`github`, `discord`, `x`, `youtube`, `slack`, `linkedin`, `mastodon`, `npm`), an https `link`, optional `ariaLabel` | | `localePreferenceKey` | Shared storage key so sites on one origin keep the same reader language | | `theme` | `light` and `dark` colors: `brand`, `accent`, `background`, `surface`, `text`, `mutedText`, `border` as hex values | | `extensions` | Trusted presentation code: `root` (default `src/site`), `slots` (`brand`, `banner`, `knowledge`, `resources`, `footer`, `floating`; `false` hides one) and custom Markdown `pages` | Links accept https or `mailto:` URLs, root-relative paths or page anchors. Custom pages are placed in the knowledge map with `target.artifact_ref: "site:"`. See [Documentation Sites]() and [Page and Theme Customization](). ## Requirements and Indexer Skills When `src/indexers.yaml` is missing, the configuration Route supplies its schema. Write `requirements` only — no `protocol`, `indexers`, Provider selections or profiles. Which installed Indexer Skills to use, and their optional configuration, belongs to `indexer_usage` in the temporary production plan, not to this durable file. The Agent writes drafts and references under the returned temporary directory; the CLI accepts them and owns candidates, review and formal output. ## Durable and runtime state Source registries and snapshots, saved notes and summaries, project declarations, package templates and approved knowledge are durable inputs, versioned in Git when Git operations are authorized. `.tmp/context-runtime/` holds unfinished execution state and stays out of Git. `knowledge/structure.yaml` keeps shared page and source metadata and compact `processed_scopes`; a partial update or failed build does not advance a whole range's processed version. Use the CLI to adjust or roll back work rather than editing these baselines. The workspace `package.json` also accepts `context.convertVisuals` (default `true`): a capable Agent may convert source diagrams and tables into faithful text structures, keeping the original image when it cannot preserve the meaning. --- ## Sources - [context/packages/context/docs/reference/project-api.md L1–L10 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L400–L402 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L12–L23 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L25–L56 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L58–L83 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L85–L135 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L137–L146 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L148–L196 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L48–L57 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L109–L116 · 3b0ce0a]() - [context/packages/context/src/packageSite.ts L1–L106 · 3b0ce0a]() - [context/packages/context-cli/src/project/packageSiteTheme.ts L310–L318 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L183–L202 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L204–L215 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L217–L229 · 3b0ce0a]() - [context/packages/context/docs/reference/project-api.md L231–L235 · 3b0ce0a]() --- ## Skills # Skills The Context Agent plugin contains nine Skills. Four are **entries** you invoke, one is an **authoring assistant** you start in plain language, and four are **Indexers** the workflow selects. All of them leave workspace state and lifecycle decisions to the `context` CLI. For a short tour aimed at first-time users, see [Commands and Skills](). ## Entries | Skill | Activates when | Does | Hands off to | | --- | --- | --- | --- | | `context` | You invoke Context explicitly, ask to reorganize an existing knowledge map or site navigation, or continue an active Context workflow to build, inspect, update, recover or package knowledge | Creates or continues a Context knowledge workspace and follows the CLI's current Route through production, review, update and build | The CLI; Indexers selected for each stage | | `context-plan` | You ask for project planning or continue a `PLAN-*.md`, or an authorized Context task involves more than 30 source documents or substantive investigation of at least two repositories | Researches in temporary storage and writes a root `PLAN-YYYYMMDD-topic.md` for review, then runs the project one stage at a time | `context`, which performs each stage | | `context-inspect-search` | You ask a knowledge question, or a host or Bot configuration routes questions here | Answers from knowledge packages or approved knowledge and traces answers to their sources; read-only, no workspace required | `context` for accepted improvement suggestions | | `context-repo-content` | You ask to create, edit or register documentation and authored Skills in the same repository | Maintains `repo-content.yaml` and its symlink view, keeping one original in its project directory; never starts production, builds, publishes or commits | — | None of them starts on its own for ordinary planning, design or coding. ## Authoring assistant | Skill | Activates when | Does | | --- | --- | --- | | `context-indexer-create` | You explicitly ask to create a new Indexer Skill for code, documents, notes or session summaries | Writes a reusable Skill into the directory you choose; does not initialize a workspace or start production. It has no menu command — ask in plain language. See [Creating an Indexer](). | ## Indexers | Skill | Interprets | Selected | | --- | --- | --- | | `context-code-indexer` | Code skeletons of an authorized module, to write source-grounded articles | For the current planning or writing task — not as a standalone repository audit | | `context-markdown-indexer` | Outlines of captured documents | For the current authorized planning or writing task — not as an import workflow | | `context-note-indexer` | Saved notes, excerpts and observations | When the current authorized task selects it — not for importing sources or scanning conversation history | | `context-sessions-indexer` | Saved conversation summaries | When the current authorized task selects it — same limits as notes | Installing an Indexer makes it discoverable, not enabled for every workspace: the Agent chooses Indexers for the current sources and requirements, and the CLI supplies task directories and checks every source reference. Indexers are installed without a plugin namespace, so their names are the same in every host. See [Community Indexers](). ## Host spelling | Host | Entries | | --- | --- | | Claude Code | `/c4a:context`, `/c4a:context-plan`, `/c4a:context-inspect-search`, `/c4a:context-repo-content` | | Cursor | `/c4a-context`, `/c4a-context-plan`, `/c4a-context-inspect-search`, `/c4a-context-repo-content` | | Codex | Skills by name: `context`, `context-plan`, `context-inspect-search`, `context-repo-content` | A local install into one repository with `context plugin install --local` has no plugin namespace; the host discovers the entries in its own directory. Restart the Agent session after installing or updating the plugin. --- ## Sources - [context/plugins/context/README.md L1–L27 · 3b0ce0a]() - [context/plugins/context/skills/context/SKILL.md L1–L4 · 3b0ce0a]() - [context/plugins/context/skills/context-plan/SKILL.md L1–L21 · 3b0ce0a]() - [context/plugins/context/skills/context-repo-content/SKILL.md L1–L9 · 3b0ce0a]() - [context/plugins/context/skills/context-indexer-create/SKILL.md L1–L15 · 3b0ce0a]() - [context/plugins/context/skills/context-code-indexer/SKILL.md L1–L4 · 3b0ce0a]() - [context/plugins/context/skills/context-markdown-indexer/SKILL.md L1–L4 · 3b0ce0a]() - [context/plugins/context/skills/context-note-indexer/SKILL.md L1–L27 · 3b0ce0a]() - [context/plugins/context/README.md L28–L33 · 3b0ce0a]() - [context/plugins/context/README.md L72–L81 · 3b0ce0a]() - [context/packages/context-cli/README.md L43–L53 · 3b0ce0a]() --- ## Package Templates # Package Templates Packages project approved knowledge into `dist//`. This page is the API and template reference; for choosing outputs, see [Knowledge Packages](), and for editing templates, see [Custom Output Templates](). ```ts import { kbPackage, llmsPackage } from "@c4a/context"; kbPackage({ name: "component-lib-kb", template: { path: "src/package-templates/kb", vars: { displayName: "Component Library KB" } }, select: { collections: ["architecture", "sop"], okfRoots: ["wikis", "guides"], include: ["architecture/component-lib/**", "sop/component-lib/**"], exclude: ["**/internal/**"], }, navigation: { foldDirectoryIndexes: true, maxInlineEntries: 50 }, assets: { delivery: "bundle" }, }); llmsPackage({ name: "component-lib-llms", template: "src/package-templates/llms", select: { include: ["codeindex/component-lib/**"] }, }); ``` ## Fields | Field | Required | Meaning | | --- | --- | --- | | `name` | Yes | Lowercase, path-safe package name; output goes to `dist//` | | `template` | Yes | Template directory, or `{ path, vars }` | | `select` | No | Approved knowledge selector; omit to include everything approved | | `navigation` | No | Directory-index policy; default `{ foldDirectoryIndexes: true, maxInlineEntries: 50 }` | | `assets` | No | Resource delivery: bundled (default), Git raw links, or omitted | | `distribution` | No | Legacy input from older workspaces; no longer changes paths — do not add it | `template` is always required; `kbPackage({ name })` alone is rejected. A `kbPackage` can also take `site` for a documentation site — see [Project API](). ## Assets | `assets` | Behavior | | --- | --- | | `{ delivery: "bundle" }` (default) | Selected resources are written under `others/assets/`. Images are compressed when needed to stay within 1 MiB each and 40 MiB per package; source snapshots and `knowledge/assets/` are never changed | | `{ delivery: "git-raw", urlPrefix }` | Links point at raw files in Git. Without `urlPrefix`, the workspace must be in Git and GitHub remotes are derived and pinned to the current commit; other hosts need an explicit HTTPS prefix, where `{commit}` is replaced only inside Git | | `{ delivery: "omit" }` | Leaves unresolved links and reports them | The resolved commit and raw URL count toward package freshness. Context does not check that resources are pushed or remotely readable. An explicit `assets.optimize` (for example `mode: "webp"` with `quality`, optional `maxDimension`) overrides the automatic image policy; if it cannot meet the image budgets, the build stops before replacing the previous package. ## Layout Package roots are flat; the package name is not repeated inside: ```text skills/knowledge-query/SKILL.md wikis/index.md guides/... rules/... feats/... ``` A knowledge package template must contain at least one `SKILL.md` and `wikis/index.md`. Each Skill lives at `skills//SKILL.md` with a matching frontmatter `name`; Skill names are author-maintained and never derived from the package name. Use `{{wikisRoot}}`, `{{guidesRoot}}`, `{{rulesRoot}}`, `{{featsRoot}}` and `{{skillName}}` in templates. Installed examples are in `node_modules/@c4a/context/templates/package-templates/{kb,llms}/`. The default template ships `skills/knowledge-query/SKILL.md` (a reusable query Skill), its `scripts/search.mjs` (a dependency-free BM25 fallback), and `wikis/index.md`. ## Directory indexes - Every selected root — `wikis/`, `guides/`, `rules/`, `feats/` — gets its own `index.md`; `wikis/index.md` is rendered from the template and is the default entry. - With `foldDirectoryIndexes: true`, indexes are planned bottom-up: a directory gets its own `index.md` only when it would expose more than `maxInlineEntries` entries (default 50) to its parent. Folded pages are listed in the nearest generated ancestor, grouped by relative path. The count is of navigation entries, not lines or headings. - `foldDirectoryIndexes: false` generates an index for every directory. - Generated indexes carry OKF frontmatter (`type: Knowledge Directory`, `title`, `description`, `tags`, `timestamp`, `resource`, `package`, `package_kind`, `knowledge_count`) and list child indexes before pages. - Links in root and generated indexes must resolve inside `dist//`; broken ones are reported as `package/index-link-invalid`. ## Article metadata | Owned by | Holds | | --- | --- | | Approved Markdown | `title`, `type`, `description`, ISO UTC `timestamp`; optional `resource` and `tags` | | `knowledge/structure.yaml` | Stable `article_id`, `path`, `collection`, `visibility`, and each section's references (at most three per section: `source_ref`, `locator { path, start_line, end_line }`, `content_digest`) | Section markers in Markdown contain only their ID: `` … ``. Package pages keep reader metadata and receive a generated Sources section from the references; repository links include file and line ranges. ## Build behavior `context build`: 1. Selects approved Markdown from `knowledge/`. 2. Renders every file under `template.path`. 3. Projects the selected articles into consumer pages. 4. For `llmsPackage`, appends the selected knowledge to `llms.txt` unless the template already uses `{{knowledge}}` or `{{approvedKnowledge}}`. 5. Writes `context-build-inventory.json`, recording each selected file with `selected_by` reasons and its production metadata. 6. Writes everything under `dist//`. Build packages the current closed state; when status reports `route.close.projection-stale`, run the returned close command first. Rendered template paths must be safe and unique and must not collide with copied knowledge — rename the template file or use `select.exclude`. Template prose about coverage, scope or limits must cite approved knowledge, the inventory or rendered structure data, or the build reports a template-boundary diagnostic. Fix problems at the source and rebuild; never patch `dist/`. ## Selection order 1. `collections` — internal collections such as `architecture`, `sop`, `standards`, `feats` (see [Knowledge Collections]()). 2. `okfRoots` — output roots after mapping: `wikis`, `guides`, `rules`, `feats`. 3. `include` — path patterns relative to `knowledge/`. 4. `exclude` — removes matches after the previous filters. Without `include`, all approved knowledge is included unless excluded. When `collections` or `okfRoots` are present, a file must pass them before path patterns apply. --- ## Sources - [context/packages/context/docs/reference/package-templates.md L1–L46 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L48–L57 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L121–L122 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L59–L91 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L109–L119 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L124–L164 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L199–L246 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L247–L292 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L302–L327 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L339–L395 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L397–L422 · 3b0ce0a]() --- ## Template Variables # Template Variables Files under `src/package-templates/**` are rendered with Handlebars during `context build`. Templates can render values, loop over arrays, branch on conditions and carry template-only comments; they cannot run JavaScript. Variables work in file contents and in file paths. Custom values come from `template.vars`. ## Syntax ```handlebars Package: {{packageName}} Approved pages: {{knowledgeCount}} Inventory name: {{buildInventory.package.name}} {{#each knowledgeGroups}} ## {{title}} {{#each items}} {{inc @index}}. [{{title}}]({{href}}) {{/each}} {{/each}} {{#if description}} Description: {{description}} {{/if}} ``` - Values support dotted paths. - Loops can nest; `{{@index}}` is zero-based. - `{{#if}}` renders when the value exists and is not `false`, an empty string or an empty array. Template-only comments are stripped from the output: ```handlebars {{! Removed by Handlebars. }} ``` | Helper | Example | Meaning | | --- | --- | --- | | `inc` | `{{inc @index}}` | Adds 1 — for numbered lists | | `json` | `{{json knowledgeGroups}}` | Formatted JSON, for debugging or machine-readable docs | ## Built-in variables | Variable | Type | Meaning | | --- | --- | --- | | `packageName` | string | Package name from the declaration | | `packageKind` | string | `kb` or `llms` | | `displayName` | string | Title-cased `packageName` unless `template.vars.displayName` overrides it | | `skillsRoot`, `wikisRoot`, `guidesRoot`, `rulesRoot`, `featsRoot` | string | Final package roots: `skills`, `wikis`, `guides`, `rules`, `feats` | | `skillName`, `skillPath` | string | Name and package-relative `SKILL.md` path of the Skill being rendered; empty outside a Skill | | `knowledgeCount` | number | Number of selected approved pages | | `knowledgeTimestamp` | string | Latest selected `timestamp`, or the epoch when empty | | `knowledge`, `approvedKnowledge` | string | All selected pages concatenated for consumers, with path headings and without lifecycle metadata — can be large | | `knowledgeItems` | array | One record per selected page | | `knowledgeGroups` | array | Pages grouped by root and first directory | | `knowledgeTreeNodes` | array | Nested path tree, for custom navigation | | `knowledgeTree` | string | Markdown tree preview | | `knowledgeItemsMarkdown` | string | Markdown list of up to 50 pages | | `knowledgeGroupsMarkdown` | string | Navigation for the current index: direct links for folded directories, index links for expanded ones | | `buildInventory`, `buildInventoryJson`, `buildInventoryPath` | object, string, string | The deterministic build inventory, its JSON, and its path `context-build-inventory.json` | | `knowledgeStructure`, `knowledgeStructureJson`, `knowledgeStructurePath` | object or null, string, string | The selected-package projection of `knowledge/structure.yaml`; not copied into the package unless a template renders it | | `knowledgeNamespace`, `namespacedKnowledge` | string, boolean | Legacy; empty and `false` for new workspaces | `buildInventory.structure.edge_records` holds typed edges whose endpoints are in the package — use them for package-local relationship evidence. ## `knowledgeItems` fields | Field | Meaning | | --- | --- | | `path` (`dist_path`) | Package-relative path, such as `guides/architecture/entity/button.md` | | `sourcePath` (`approved_path`) | Approved path before mapping, such as `architecture/entity/button.md` | | `article_id` | Stable article identity | | `collection` (`internalCollection`, `internal_collection`) | Internal collection | | `okf_root`, `okf_root_path` | Output root and its final path | | `pathWithinCollection` | Path below the root | | `href` (`hrefFromTemplate`) | Link relative to the template file being rendered — use this | | `hrefFromPackageRoot` | Link from a root file such as `AGENTS.md` | | `hrefFromCollectionIndex` | Link from the current root index | | `title`, `type`, `description`, `timestamp`, `tags` | Frontmatter values; `title` falls back to the file name | | `source` | First source reference, or the group name | | `group`, `parentPath`, `depth`, `segments` | Position below the root | ## `knowledgeGroups` fields | Field | Meaning | | --- | --- | | `name` | First directory under the root, or `root` | | `title` | Display title; defaults to `name`, or the root title | | `count` | Number of pages | | `collection` (`internalCollection`, `internal_collection`) | Internal collection | | `okf_root`, `okf_root_path` | Output root and its final path | | `hasIndex` (`has_index`) | Whether the navigation policy generates `indexPath` | | `indexPath` | Index path, such as `wikis/codeindex/index.md` | | `indexHrefFromTemplate`, `indexHrefFromCollectionIndex` | Links to `indexPath`; check `hasIndex` first | | `items` | The group's `knowledgeItems` | ```handlebars {{#each knowledgeGroups}} ## {{title}} ({{count}}) {{#if hasIndex}} [Open directory index]({{indexHrefFromTemplate}}) {{/if}} {{#each items}} - [{{title}}]({{href}}) - {{type}} {{/each}} {{/each}} ``` ## `knowledgeTreeNodes` fields Each node has `name`, `title`, `path`, `depth`, `count` (pages under it), `items` (pages directly under it) and `children`. Handlebars has no recursive partials by default, so keep tree templates shallow or write sections for the levels you care about. ## The starter `wikis/index.md` The default template uses these variables for the bundle count and timestamp in its frontmatter, direct links for folded directories, and links to generated indexes for directories over the threshold. It is only a starter: edit `src/package-templates/kb/` when the package needs different reading paths, or accept the unchanged starter explicitly through the package-template review step. --- ## Sources - [context/packages/context/docs/reference/template-variables.md L1–L8 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L166–L194 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L10–L86 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L88–L126 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L182–L182 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L128–L166 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L168–L202 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L204–L222 · 3b0ce0a]() - [context/packages/context/docs/reference/template-variables.md L224–L242 · 3b0ce0a]() --- ## Knowledge Collections # Knowledge Collections Every approved article in `knowledge/` lives under a **collection** — the first directory of its path, such as `knowledge/sop/…`. The collection says what kind of reading the article serves. At build time it decides which package root the article goes to, and package `select.collections` filters by it. ```mermaid flowchart LR k["knowledge/collection/..."] --> w["wikis/
entities and relationships"] k --> g["guides/
explanations and procedures"] k --> r["rules/
standards and checks"] k --> f["feats/
feature records"] ``` ## The collections | Collection | Holds | Package path | OKF type | | --- | --- | --- | --- | | `codeindex` | Source-backed code indexes, with optional structured relationships | `wikis/codeindex/` | Wiki | | `business` | Structured business entities and relationships | `wikis/business/` | Wiki | | `product` | Structured product entities, behavior and relationships | `wikis/product/` | Wiki | | `architecture` | Architecture explanations and design narratives | `guides/architecture/` | Guide | | `sop` | Procedures and runbooks | `guides/sop/` | Guide | | `faq` | Question-oriented explanations and troubleshooting | `guides/faq/` | Guide | | `decision` | Decision records and trade-off narratives | `guides/decision/` | Guide | | `incident` | Incident timelines, response and follow-up | `guides/incident/` | Guide | | `standards` | Normative standards and constraints | `rules/standards/` | Rule | | `test` | Validation rules, scenarios and acceptance checks | `rules/test/` | Rule | | `feats` | Feature capability records | `feats/` | Feature | `codegraph` is still accepted as the legacy name of the code index collection and maps to `wikis/` like `codeindex`. ## What the package roots mean - **`wikis/`** is the structured entity-and-relationship layer and the required default entry of a knowledge package, starting at `wikis/index.md`. - **`guides/`** and **`rules/`** explain, operationalize or constrain that knowledge. Placing an article there does not create a relationship to anything; only a typed edge recorded by Context does. - **`feats/`** holds feature records. A package can choose roots with `select.okfRoots` as well as collections; see [Package Templates](). ## Choosing a collection The Indexer proposes a collection from the reader's need, not from the source type: a document can become a runbook in `sop`, a decision record in `decision` or a standard in `standards`. Typical pairings: | Reader need | Useful form | | --- | --- | | Understand a term, boundary or business rule | Domain explanation with scope and examples | | Understand architecture or integration | Technical explanation, contracts and limitations | | Complete a repeatable task | Guide with prerequisites, actions and checks | | Diagnose or recover | Runbook with symptoms, safe actions and verification | | Understand a choice | Decision, alternatives, rationale and consequences | | Learn from an incident | Impact, observations, causes and response | | Interpret a test | Method, scope and what the result establishes | You can move an approved article to another collection later with `context revise --move-to `, which keeps its identity. ## Reserved names `index.md` is reserved for package bundle and directory indexes. A source document may be called `index.md`, but an article must use another name such as `index-page.md`; `context build` rejects copied knowledge that would occupy `wikis/**/index.md`. --- ## Sources - [context/packages/context/src/contracts.ts L45–L59 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L397–L408 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L299–L313 · 3b0ce0a]() - [context/packages/context-cli/src/project/okfTypes.ts L7–L35 · 3b0ce0a]() - [context/packages/context-cli/src/project/codeIndexCollection.ts L3–L8 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L315–L317 · 3b0ce0a]() - [context/packages/context/docs/reference/package-templates.md L253–L261 · 3b0ce0a]() - [context/plugins/context/skills/context-markdown-indexer/references/classification.md L1–L23 · 3b0ce0a]() - [context/packages/context-cli/src/commands/documentRevisionCommands.ts L204–L216 · 3b0ce0a]() - [context/packages/context/docs/guides/package-outputs.md L319–L322 · 3b0ce0a]() --- ## HTTP and MCP # HTTP and MCP All routes live under the `/sourcegraph` prefix of the instance's origin. Query routes are under `/sourcegraph/v1/` (search is `/sourcegraph/api/search`), management routes under `/sourcegraph/api/admin/`, and the MCP endpoint is `/sourcegraph/mcp`. Both surfaces call the same service, so revisions, limits and error codes are identical. For how to choose a credential see [Connecting](). > **Optional service.** Context does not require Source Graph or its MCP server. When neither is installed or configured, Context's query skill still reads code evidence locally through a shallow, sparse partial clone and grep; in its default `auto` mode it prefers Source Graph only when an authorized instance is available. ## Request conventions - **Repository** — routes that act on one repository take it as the `repo` query parameter, `owner/repository`. - **Query parameters** — only `repo` and `after` are accepted, plus `revision` on `/v1/repo/plugins` and `branch` on `/api/admin/v1/repo/commit-options`. Unknown or repeated parameters return `400 INVALID_QUERY_PARAMETERS`. - **Bodies** — JSON objects of at most 64 KiB. Unknown fields, `null` values, duplicate keys and trailing data are rejected. Query-route fields use capitalized names (`Revision`, `Pattern`); management routes use lowercase names (`name`, `policy`). - **Credentials** — `Authorization: Bearer ` or `Bearer sgk_…` for a personal key; otherwise a browser session or anonymous access. An invalid credential returns `401` and never falls back to anonymous access. - **Time** — each request has a 30-second processing budget; a request that exceeds it returns `503 QUERY_DEADLINE_EXCEEDED`, and an unexpected dependency failure returns `503 DEPENDENCY_UNAVAILABLE`. ## Query routes These are available anonymously when public reading is enabled, and to every credential. | Method | Path | Body | Returns | | --- | --- | --- | --- | | GET | `/v1/capabilities` | — | Protocol and supported operations | | GET | `/v1/repos` | — (`after` for the next page) | Registered repositories, 100 per page | | GET | `/v1/repo/availability` | — | One repository: retained versions, heads, groups and jobs, with an `ETag` | | GET | `/v1/repo/commits` | — | Same as availability | | GET | `/v1/repo/plugins` | — (optional `revision`) | Repository plugins found at that commit, without running them | | POST | `/v1/repo/resolve` | `{"Revision"}` | The fixed commit and whether it is indexed | | POST | `/api/search` | `{"Revision","Pattern","FixedStrings","IgnoreCase","Glob","Paths","Output"}` | Search hits and `Meta`; see [Query Syntax]() | | POST | `/v1/repo/read` | `{"Revision","Path","StartLine","EndLine"}` | One file range | | POST | `/v1/repo/list` | `{"Revision","Path","First","After"}` | Direct children of one directory | | POST | `/v1/repo/diff` | `{"Base","Head","Paths","First","After"}` | Changed files and patches between two commits | `Revision` is optional everywhere except `diff`, where `Base` and `Head` are required. `read_many` has no HTTP route; it exists only as an MCP tool. ## Management routes These need the service token or an administrator's browser session. Personal API keys are read-only and get `403 ACCESS_DENIED` here. A few read routes — `GET /api/admin/v1/repos`, `GET /api/admin/v1/repo` and `GET /api/admin/v1/statistics` — are also open to anonymous reading. | Method | Path | Body or headers | Purpose | | --- | --- | --- | --- | | GET | `/api/admin/v1/statistics` | — | Request and job statistics | | GET | `/api/admin/v1/instances` | — | Instance heartbeats | | GET | `/api/admin/v1/repos` | — | Repository catalog | | POST | `/api/admin/v1/repos` | Registration fields; optional `Idempotency-Key` | Register a repository (`202`) | | GET | `/api/admin/v1/repo` | — | Repository with `ETag` | | PATCH | `/api/admin/v1/repo` | Update fields; `If-Match` revision | Change branches, window, visibility, interval, path groups; enable, disable or delete | | POST | `/api/admin/v1/repo/preview` | Update fields | Preview an update | | POST | `/api/admin/v1/repo/prepare` | `{"kind","commit","group"}`; optional `Idempotency-Key` | Queue `sync` or `index` work (`202`) | | GET | `/api/admin/v1/repo/commit-options` | — (optional `branch`) | Recent synchronized commits to choose from | | POST | `/api/admin/v1/repo/index/preview`, `/api/admin/v1/repo/index` | `{"branch","commit"}`; the second also `preview` and `If-Match` | Add an index for one commit | | POST | `/api/admin/v1/repo/cleanup/preview`, `/api/admin/v1/repo/cleanup` | `{"preview"}` and `If-Match` for the second | Keep only the latest index per branch | | POST | `/api/admin/v1/repo/delete/preview`, `/api/admin/v1/repo/delete` | `{"preview"}` and `If-Match` for the second | Permanently delete repository data | | POST | `/api/admin/v1/repo/jobs/cancel` | `{"job_id"}` | Cancel a job | | POST | `/api/admin/v1/repo/purge` | `If-Match` revision | Purge a disabled, deleted repository | Registration fields are listed in [Registering Repositories](). ## Health, sign-in and settings routes | Path | Access | Purpose | | --- | --- | --- | | `GET /healthz` | Open | Liveness: `{"status":"alive"}` | | `GET /readyz` | Open | Readiness; `503` when the catalog cannot be read | | `GET /access-policy` | Open | `public_read`, `public_prepare` (always `false`) and `sso_enabled` | | `GET /site-settings` | Open | Public repository defaults | | `/auth/…` | Browser | Providers, sign-in and callback, current user, sign-out, `api-keys`, user administration | | `/auth/code-credentials` | Signed-in session | Your own Git credentials | | `/api/admin/settings/…` | Administrator session only | Site settings sections, `code-credentials`, `query-errors`, `jobs/clear`, `storage` | Site administration under `/api/admin/settings` refuses any request that carries an `Authorization` header — it is reachable only from a signed-in administrator's browser. ## MCP endpoint `/sourcegraph/mcp` speaks stateless Streamable HTTP with JSON responses; the server identifies itself as `context-sourcegraph`. The toolset depends on the credential: | Credential | Tools | | --- | --- | | Anonymous (public reading on), personal key | Read-only: every tool except `prepare` | | Administrator personal key created with prepare permission | Read-only tools plus `prepare`, rate-limited to 10 per key and 60 in total per minute | | Service token | All tools | The optional connection parameter `?plugins=` sets the default plugin selection for `read` and `read_many`: `auto`, `off`, or up to 16 comma-separated names. Invalid values return `400 INVALID_PLUGINS`. ## MCP tools | Tool | Required | Optional (default) | | --- | --- | --- | | `repositories` | — | `after` | | `availability` | `repo` | `job_id`, `include_plugins`, `revision` | | `resolve` | `repo` | `revision` | | `search` | `repo`, `pattern` | `revision`, `fixed_strings`, `ignore_case`, `glob`, `paths`, `output` (`content` or `files`), `max_lines_per_file` (10, range 1–1000) | | `read` | `repo`, `path` | `revision`, `start_line` (1), `end_line` (start + 499), `plugins` | | `read_many` | `repo`, `files` (1–10 items of `path`, `start_line`, `end_line`) | `revision` (resolved once for the batch), `plugins` | | `list` | `repo`, `first` (1–1000) | `revision`, `path`, `after` | | `diff` | `repo`, `base`, `head`, `first` (1–100) | `paths`, `after` | | `prepare` | `repo`, `idempotency_key` (8–128 bytes) | `revision`, `group` | `plugins` is a list such as `[{"name":"context-evidence"}]`; `[]` disables enhancements for that call, and a connection opened with `plugins=off` always disables them. `prepare` accepts an omitted revision (default branch), a monitored branch or a full SHA inside the retention window; it is asynchronous, so poll `availability` afterwards. ## MCP output `search`, `read` and `read_many` return readable text rather than raw JSON: - **search** starts with `Repository`, `Commit`, `Status`, `Partial`, `Truncated`, a `Coverage` line, registered `Paths` and `Groups`, and the returned and total file counts, then lists each `File` with numbered matching lines. - **read** starts with `Repository`, then `Path`, `Commit` and `Lines: start-end`, continuation fields when more remains (`Truncated`, `HasMore`, `NextStartLine`), notes for symlinks, submodules and LFS pointers, then numbered lines `N: text`. - **read_many** returns one text block per item, each with `Item N; RequestedLines`, an `Error` line if that item failed, and the same file header and lines. Plugin output is appended after the item it belongs to; plugin diagnostics come in a separate block and never replace the original text. The other tools return compact JSON. Errors come back as a tool result marked as an error, whose text is `{"code","message"}`, with a recovery hint for not-ready states. ## Limits | Limit | Value | | --- | --- | | Catalog page | 100 repositories | | Search pattern | 8,192 bytes; cannot match a newline or the empty string | | Search globs | 64, each up to 1,024 bytes | | Search or diff paths | 64 directories | | Search page | 100 files and 1,000 matches with 2 context lines, then smaller fallbacks; 2 MiB response; 5-second deadline | | Engine match cap | 10,000 matches | | Read | 500 lines and 256 KiB per call | | `read_many` | 1–10 items, 1,000 lines, 256 KiB and 30 seconds shared | | List page | 1–1,000 entries | | Diff page | 1–100 files; patches 64 KiB per file and 256 KiB total | | Request body | 64 KiB | ## Error format HTTP errors return a JSON body with an `Error` message and `Meta` containing `Protocol`, `RequestID`, `Status`, `Code` and `Retryable`. Transport-level codes include `NOT_FOUND`, `METHOD_NOT_ALLOWED`, `INVALID_QUERY_PARAMETERS`, `INVALID_REQUEST`, `AUTHENTICATION_REQUIRED`, `ACCESS_DENIED`, `RATE_LIMITED`, `PRECONDITION_REQUIRED`, `QUERY_DEADLINE_EXCEEDED` and `DEPENDENCY_UNAVAILABLE`. Operation codes such as `INDEX_NOT_READY`, `REVISION_NOT_ELIGIBLE`, `INVALID_PATTERN` or `READ_BUDGET_EXCEEDED` carry their own status. [Operations]() explains the common ones and what to do about them. --- ## Sources - [sourcegraph/internal/httpserver/server.go L16–L16 · 4e5c555]() - [sourcegraph/docs/interfaces.md L1–L8 · 4e5c555]() - [context/plugins/context/skills/context-inspect-search/SKILL.md L49–L55 · 3b0ce0a]() - [sourcegraph/internal/httpserver/runtime.go L241–L250 · 4e5c555]() - [sourcegraph/internal/contract/json.go L12–L55 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L426–L442 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L291–L326 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L389–L422 · 4e5c555]() - [sourcegraph/internal/httpserver/website_access.go L15–L31 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L278–L387 · 4e5c555]() - [sourcegraph/internal/httpserver/repository_maintenance.go L12–L60 · 4e5c555]() - [sourcegraph/internal/httpserver/registration.go L9–L22 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L86–L128 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L129–L159 · 4e5c555]() - [sourcegraph/internal/httpserver/code_credentials.go L74–L78 · 4e5c555]() - [sourcegraph/internal/mcpserver/server.go L14–L30 · 4e5c555]() - [sourcegraph/internal/httpserver/runtime.go L40–L56 · 4e5c555]() - [sourcegraph/internal/mcpserver/plugin_connection.go L19–L62 · 4e5c555]() - [sourcegraph/internal/mcpserver/inputs.go L1–L115 · 4e5c555]() - [sourcegraph/internal/mcpserver/server.go L31–L82 · 4e5c555]() - [sourcegraph/internal/mcpserver/read_defaults.go L1–L16 · 4e5c555]() - [sourcegraph/internal/mcpserver/read_text.go L38–L110 · 4e5c555]() - [sourcegraph/internal/mcpserver/search_text.go L60–L125 · 4e5c555]() - [sourcegraph/internal/mcpserver/plugin_text.go L1–L36 · 4e5c555]() - [sourcegraph/internal/zoektclient/client.go L20–L30 · 4e5c555]() - [sourcegraph/internal/zoektclient/client.go L105–L190 · 4e5c555]() - [sourcegraph/internal/service/read_many.go L13–L20 · 4e5c555]() - [sourcegraph/internal/contract/types.go L36–L46 · 4e5c555]() - [sourcegraph/internal/contract/errors.go L1–L18 · 4e5c555]() - [sourcegraph/internal/httpserver/server.go L49–L86 · 4e5c555]() --- ## CLI # CLI `sourcegraph-cli` is a small, bounded HTTP client for a Source Graph instance. It sends one request per invocation to the routes described in [HTTP and MCP](), prints the JSON response and exits; it never clones repositories or installs anything. It is built with the service into `output/bin/` and is included in the container image. ```text sourcegraph-cli [flags] [arguments] ``` ## Environment | Variable | Default | Rules | | --- | --- | --- | | `SOURCEGRAPH_URL` | `https://context4ai.org/sourcegraph` | The instance's `/sourcegraph` base address. Must be an HTTPS URL without user information, query or fragment | | `SOURCEGRAPH_API_TOKEN` | — | Optional bearer credential — a personal API key or the service token. At least 32 characters when set | Because the address must be HTTPS, a local instance on `http://localhost` needs a TLS-terminating proxy in front of it for CLI use. ## Commands | Command | Route | Flags used | | --- | --- | --- | | `repositories` | `GET /v1/repos` | `-after` | | `availability` | `GET /v1/repo/availability` | `-repo` | | `resolve` | `POST /v1/repo/resolve` | `-repo`, `-revision` | | `search` | `POST /api/search` | `-repo`, `-revision`, `-e`, `-F`, `-i`, `-l`, `-g`; then `PATTERN [PATH...]` | | `read` | `POST /v1/repo/read` | `-repo`, `-revision`, `-path`, `-start-line`, `-end-line` | | `list` | `POST /v1/repo/list` | `-repo`, `-revision`, `-path`, `-first`, `-after` | | `diff` | `POST /v1/repo/diff` | `-repo`, `-base`, `-head`, `-first`, `-after` | | `prepare` | `POST /api/admin/v1/repo/prepare` | `-repo`, `-revision`, `-kind`, `-key` | There is no `read_many` command; use several `read` calls or the MCP tool. `diff` compares all registered paths, and `prepare` targets all path groups. `prepare` is a management route, so it needs the service token. ## Flags Flags use Go syntax: one or two leading dashes both work (`-repo` or `--repo`), and every flag must come before positional arguments. | Flag | Default | Meaning | | --- | --- | --- | | `-repo` | — | Repository key, `owner/repository` | | `-revision` | — | A monitored branch or a full SHA; omitted means the default branch. For `prepare`, the commit to prepare | | `-e` | — | Search pattern, like `rg -e`; otherwise the first positional argument | | `-F` | `false` | Match the pattern as literal text, like `rg -F` | | `-i` | `false` | Ignore case, like `rg -i` | | `-l` | `false` | Print only matching paths, like `rg -l` | | `-g` | — | Include, or `!`-exclude, files by glob, like `rg -g`; repeatable | | `-path` | — | Repository-relative file or directory | | `-start-line` | `1` | First line to read | | `-end-line` | `100` | Last line to read | | `-first` | `100` | Page size for `list` (1–1000) and `diff` (1–100) | | `-after` | — | Cursor from the previous page | | `-base`, `-head` | — | The two revisions for `diff` | | `-key` | — | Idempotency key sent as `Idempotency-Key` for `prepare` | | `-kind` | `index` | `index` or `sync`, for `prepare` | Search arguments after the pattern are directories to search within, like `rg`'s `PATH` arguments. ## Output and exit codes The CLI writes the response body — always JSON — to standard output unchanged, up to 3 MiB, and diagnostics to standard error. Each request has a 35-second timeout, and redirects are refused. | Exit code | Meaning | | --- | --- | | `0` | Success | | `1` | Request failed, timed out, returned an invalid or oversized body, or a non-2xx status | | `2` | Usage error: unknown command, bad flags, missing pattern, invalid `SOURCEGRAPH_URL` or token | | `3` | Accepted but not ready yet — `202 Accepted`, or `409 INDEX_NOT_READY` | After a timeout, delivery is unknown; inspect `availability` before retrying a `prepare`. ## Examples ```bash export SOURCEGRAPH_URL="https://context4ai.org/sourcegraph" # Literal search in TypeScript files under packages/ sourcegraph-cli search -repo context4ai/context -F -g '*.ts' 'defineProject' packages # Read lines 1–40 at the commit returned in Meta.Commit sourcegraph-cli read -repo context4ai/context -revision -path README.md -end-line 40 # List the repository root sourcegraph-cli list -repo context4ai/context -first 50 # Ask an instance you administer to index a commit (service token required) SOURCEGRAPH_API_TOKEN=... sourcegraph-cli prepare -repo acme/app -revision -key index-