@interf/compiler 0.22.2 → 0.50.0

package/public-repo/README.md

@@ -1,327 +1,164 @@
 # Interf
 
-**Data preparation for agents.**
+**Interf prepares data for agent tasks.**
 
-Agents miss things in files.
+Interf structures your files into a task-specific graph your agent can navigate.
+Your agent starts from prepared context built for the task, instead of a partial
+read of whatever files it happened to open.
 
-Interf builds verifiable context for agents from your files.
+> This npm package is the `interf` CLI and local runtime. A Mac app (Interf
+> Desktop) is coming soon.
 
-It turns hidden file discovery into traceable artifacts with proof of how they were built.
-
-When agents answer from your files, they first have to discover what is in them. That context-building step is hidden, inconsistent, and hard to verify: you cannot see which files were checked, what was extracted, or what the agent skipped. When the agent misses a file or page, the output can sound confident but be wrong.
-
-Source discovery should be separate from agent work. Interf separates that step, builds verifiable context, and lets your agent work from traceable artifacts instead of rediscovering the files during the job.
-
-```text
-Source files                        Verifiable context agents use
-
-bristol-office-market/              <context-locator>/
-  q4-market-report.pdf                AGENTS.md
-  lease-comps.xlsx                    .interf/runtime/source-snapshot.json
-  planning-notes.md                   home.md
-  exports/availability.csv            summaries/
-                                      knowledge/
-```
-
-## What a Build Run Produces
-
-A Build run produces verifiable context plus proof of work. Verifiable context is what agents use. The proof shows which source files were assigned, which Build Plan stages ran, what each stage wrote, and whether required artifacts exist.
-
-For the built-in `interf-default` Build Plan, a Build run looks like this:
-
-```text
-Source: bristol-office-market
-Build Plan: interf-default
-Requested Artifacts: atlas, summaries, knowledge, claims, indexes
-
-Build run
-  record source references
-  summarize -> summaries/
-  structure -> knowledge/
-  shape -> home.md and agent entrypoints
-  record proof -> processed files, stage outputs, required artifacts
-
-verifiable context
-  locator -> { kind: "local-path", value: "<local-path-returned-by-interf>" }
-```
-
-The output is not an answer. It is a prepared local folder with routes, artifacts, source snapshots, and agent instructions. Your runtime agent reads that folder when it does the actual agent work.
-
-## Design Choices
-
-- `Preparation-scoped`: every Preparation starts from a specific Source, requested Artifacts, and agent job, not a generic index over all your files.
-- `Deterministic`: Interf runs each stage, an ordered phase of a Build Plan, and shows stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs exist. Agents do not have to rebuild the full picture while they work.
-- `Local-first and private`: your files, readiness checks, and agent runs stay on your machine. No cloud, no uploads, no telemetry.
-- `Bring your own AI`: use Claude Code, Codex, or another local agent.
-- `File over app`: verifiable context is exposed as a local folder owned by the instance — no hidden store, no hidden index. Inspect it, diff it, version it.
-- `Readiness checks you control`: every build can be checked against gates you wrote from the files. If the context is `not ready`, `interf test` shows the readiness evidence behind that status.
-
-## Why Not Just Ask Your Agent?
-
-You can. Interf can use Claude Code, Codex, or another local agent while it builds verifiable context.
-
-A one-off preprocessing prompt gives you another agent answer to trust. Interf puts that work inside a Build Plan you can inspect: requested artifacts, declared stages, stage-by-stage proof of work, and readiness checks that decide whether the context is `ready` or `not ready`.
-
-The agent can still execute the stages. Interf shows what ran, which files were processed, what artifacts and evidence were produced, and whether the result is ready for the agent work.
-
-## Install
+## Quick start
 
 ```bash
 npm install -g @interf/compiler
-interf            # opens the wizard; start or connect an engine when needed
+interf                 # the interactive wizard walks you through your first build
 ```
 
-Requires Node.js 20+ and a local coding agent such as Claude Code or Codex. Run `interf doctor --live` if the executor is not detected.
+Requires Node 20+ and a local agent CLI (Claude Code, Codex, or another). Check
+it with `interf doctor --live`.
 
-## Quick Start
+Or run it command by command:
 
 ```bash
-interf web                                      # terminal 1: start the local engine
-interf prep create bristol \                    # terminal 2: save the source + requested Artifacts
+interf runtime                                 # start the local runtime
+interf project create bristol \                # bind a folder + the agent's task
   --source ./bristol-office-market \
-  --about "Bristol annual take-up and availability chart lookup" \
-  --requested-artifacts-json '[{"title":"Guide to the report","checks":["Every page or file is listed.","Pages about Bristol and annual take-up are marked."]},{"title":"Annual take-up figures","checks":["Every figure has a source reference."]}]'
-interf build-plan draft bristol \                 # draft the Build Plan for review
-  --task "Bristol annual take-up and availability chart lookup"
-interf build bristol                            # build verifiable context, returns the locator
-interf test bristol                             # check readiness
+  --intent "Bristol annual take-up and availability"
+interf plan draft bristol                      # draft a Build Plan, then review it
+interf plan select bristol <build-plan-id>     # pick the reviewed plan
+interf build bristol                           # build the graph
 ```
 
-`interf web` starts the engine in the foreground and writes the active
-connection record so subsequent CLI commands can connect. Agents can use
-`interf web start` for an explicit managed background engine, then
-`interf web stop` when their work is done. Mutating commands never implicitly
-auto-start an engine — if no instance is connected, they exit with a hint
-pointing at `interf web` / `interf web start` (local) or `interf login`
-(future cloud).
-
-`interf build` returns the artifact locator on success — for a local
-engine that's a `local-path` you can open with any tool. Point your agent at
-that path. There's no `--out` flag, no implicit copy, no hidden store: the
-instance owns the bytes and the API tells you where they are.
-
-If you want a baseline before building verifiable context, run `interf test bristol --target source-files`. It is optional proof, not the main path.
+`interf build` returns the graph path: a folder your agent opens and continues
+from. No `--out` flag, no copy of your Source. Mutating commands never auto-start
+the runtime; they exit with a hint if nothing is connected.
 
-## Verifiable Context
+## What you get
 
-Verifiable context is the output Interf builds from your files for agents. The current local engine exposes it as a local folder. Do not hardcode its location. The API returns a typed locator (`{ kind: "local-path" | "remote-url", value }`); your agent reads from there.
-
-It gives agents evidence, structure, and cross-file connections for navigating the files. It is not a replacement for your files. For the built-in `interf-default`, it includes:
+A folder your agent navigates instead of grepping raw files. Interf calls it a
+**Context Graph**:
 
 ```text
-<context-locator>/
-  AGENTS.md       # agent-facing entry point and source-checking rules
-  CLAUDE.md       # same guidance for Claude Code
-  .interf/
-    runtime/
-      source-snapshot.json  # source references captured for the latest run
-      stages/               # per-stage source input lists
-  home.md         # overview and routes for agents
-  summaries/      # one note per source file
-  knowledge/      # linked notes built from the files
+<graph>/
+  home.md          # start here. routes into the three layers below
+  summaries/       # one folder per source file. every file read and summarized
+  knowledge/       # the connected web: linked notes, claims, entities, source refs
+  artifacts/       # task handoffs that reference summaries and knowledge
+  traces/          # provenance: every claim links back to source
+  AGENTS.md        # how agents use the graph (plus CLAUDE.md for Claude Code)
 ```
 
-The source files stay the source of truth. Interf writes verifiable context inside the instance's data dir; it does not modify the source.
-
-`AGENTS.md` tells agents how to use the verifiable context: start from the prepared outputs, follow the prepared routes, and use the recorded source references when exact source evidence matters.
-
-Interf also records stage-by-stage proof of work: which files were processed, what each stage produced, and whether required outputs were created.
-
-The returned local folder carries source references, not a mandatory copy of every source file. The source files remain where you keep them; Interf records which sources were assigned and what artifacts were produced from them.
+`summaries/`, `knowledge/`, and `artifacts/` are the three fixed layers, plus
+`home.md`. What goes inside `knowledge/` (claims, entities, timelines, tables) is
+up to the Build Plan, so any task shapes its own web. Your Source stays read-only
+and the ground truth. Agents follow source links when exact wording, table
+values, or chart reads matter.
 
-## Build Plans
+## Why Interf is different
 
-A Build Plan tells Interf how to build requested Artifacts from your source files for the job agents need to do. It can start as a draft inside one Preparation, based on the user's instructions, the agent goal, and the described Source. If it works, save it and reuse it on another Source.
+Most tools prepare your files one way for every question: chunks in a vector
+store, or a single knowledge graph that maps everything the same way (RAG
+indexes, Obsidian-style graphs, code-graph tools). Interf is `task-specific`. You
+tell it what the agent needs to do, and it builds a graph tailored to that task:
+the right summaries, connections, and entrypoints for *this* work, not a one-size
+index of all your files.
 
-The built-in `interf-default` Build Plan ships with `interf`. Save your own local Build Plan with `interf build-plan save <path>`; draft new ones with `interf build-plan draft <prep-id>`.
+And the graph is `provable`:
 
-```text
-<build-plan-folder>/
-  build-plan.json         # Build Plan definition: artifacts, stages, build rules
-  build-plan.schema.json  # output contract: required verifiable-context files and folders
-  README.md             # what this Build Plan is for
-  build/
-    stages/
-      summarize/        # stage instructions Interf runs during the Build run
-      structure/
-      shape/
-  use/
-    query/              # how agents read the verifiable context
-  improve/              # how Interf revises this plan if readiness checks still fail
-```
+- `Coverage`: every Source file was read and summarized.
+- `Traceability`: every claim links back to a Source, and every note connects to
+  the web. No orphans, no islands.
 
-- `build-plan.json` is the current technical filename for the Build Plan definition: source data, requested artifacts, stages, and how the files should be built.
-- `build-plan.schema.json` describes the output contract: what the verifiable context must contain. Interf enforces it when you run `interf build`.
-- `build/stages/<stage>/` is where you author one folder per stage — a small, specific phase like `summarize` or `structure`. You write the instructions; Interf runs them during the Build run.
-- `use/query/` holds the instructions agents follow when they read the verifiable context for live agent work.
-- `improve/` holds the instructions Interf follows when the first build misses and the Build Plan itself needs editing.
+It is `provider-agnostic` by design: the same prepared context works across
+Claude, Codex, GPT, and whatever you switch to next, because the graph is a
+portable folder you own, never trapped in one vendor's session. Your own agents
+do the work, your files never leave your machine, and the output is files you can
+read, diff, commit, and reuse.
 
-A Build Plan defines the stages, output contract, proof requirements, and improvement instructions Interf runs on your files. The result is verifiable context your agents can read.
+## Design principles
 
-## Build Plan Improvement
+- `Not a replacement for your agent harness`: just a task-specific graph to navigate.
+- `Your files stay yours`: local, read-only, never sent to Interf's servers.
+- `Runs with your agents`: your CLIs, your subscriptions, in a replayable shell.
+- `File over app`: the graph is inspectable files, not a hidden index.
+- `Connected, not orphaned`: every note links to others and back to sources.
+- `Coverage-first`: exact file, summary, knowledge, and output counts.
+- `Project-scoped`: one Source, one agent task, one Build Plan.
 
-When the first Build run still misses readiness checks, Interf edits the Build Plan and builds again. Same files, same checks, improved plan and verifiable context. Run `interf build-plan improve <prep-id>` to invoke that loop manually.
+## Readiness is provable
 
-Interf saves every readiness-check run inside the returned local folder under `.interf/tests/`. You can inspect what changed and why a later Build run did better.
+Every Build reports exact coverage metrics (files processed, source units
+summarized, knowledge reviewed and used, graph outputs, entrypoints) behind a
+single `ready` / `not ready` verdict backed by two deterministic guarantees:
 
-## How Interf Builds
+- **Coverage**: every Source file was read and summarized. This is file-level. It
+  does not claim every fact was caught, only that no file went unread.
+- **Traceability**: every claim links back to a Source, every summary is linked,
+  and every knowledge note connects to the web. No orphans, no islands.
 
-You don't need to think about roles. By default Interf uses your active agent for every stage of every Build run. Roles are available for advanced users who want different agents per stage; defaults are good and stable.
+If a file is unread, a claim is unlinked, or a note is an island, the graph is
+`not ready` and the gap is named.
 
-Interf treats connected agents as a first-class primitive and uses a small role taxonomy internally to route stages between them. The default behavior is single-active-agent — one installed agent runs everything — but you can opt into per-role specialization without changing any Build Plan.
+`interf benchmark` is a separate, optional check that scores answer accuracy
+against the Source baseline, the graph, or both. It is a fallible double-check,
+never a readiness gate.
 
-```text
-Connected agents             Role map (per-instance)
-  claude-code (active)         extractor   → claude-code
-  codex                        summarizer  → claude-code
-  pdf-extract (custom)         structurer  → claude-code
-                               verifier    → claude-code
-                               general     → claude-code
-
-A Build run
-  for each stage in the Build Plan
-    look up the stage's role in the role map
-    invoke the mapped agent on the prepared shell
-    record which agent ran which stage
-```
+## Build Plans
 
-Build Plans declare an optional `role` per stage — one of `extractor`, `summarizer`, `structurer`, `verifier`, or `general`. Custom role names are allowed; unknown roles fall through to `general`.
+A Build Plan is the reviewed recipe for how Interf builds the graph from your
+Source for the task: requested outputs, stage instructions, expected inputs, and
+the entrypoints you review before building. `interf-default` ships built in.
+Draft your own with `interf plan draft <project-id>`, or save one with
+`interf plan save <path>`.
 
-The role map lives in the instance's agent settings. On a fresh install with one agent installed, every role maps to that agent and you get the same single-active-agent behavior 0.14 had. To change which agent runs which role:
+When a Build comes back `not ready`, Interf can revise the plan and build again
+(same Source, same intent, better plan), recorded as a Run:
 
 ```bash
-interf agents ls
-interf agents register opencode --command "opencode --prompt"
-interf agents map structurer codex
-interf agents use claude-code   # set the active agent
-interf agents unmap structurer  # fall back to active
-```
-
-Or use the **Agents** tab in Interf UI. Either surface mutates the same instance agent settings through the local service.
-
-Readiness-check runs always resolve to the `verifier` role. Build Plan authoring runs ask the authoring agent to propose a `role` per stage based on the prompt content; missing roles default to `general`.
-
-## How the Pieces Fit
-
-The instance owns preparation state. A preparation declares a source binding (`{ kind: "local-folder", locator: <path> }`), requested artifacts, and a selected Build Plan. It stores preparation state and generated bytes in the instance data directory. A Build run processes the selected source files and produces the artifact locator the API returns. `interf test` checks source files and verifiable context against the same readiness checks.
-
-Readiness is one `ready` / `not ready` status, not a separate score. Interf builds it from evidence primitives: Build Plan Artifact checks, proof records, file coverage, artifact validation, and readiness checks.
-
-`interf web` runs the local Interf instance and serves Interf UI. The UI reads local-service resources: Source, Preparations, Build Plans, Build runs, stages, proof, artifacts, readiness checks, and whether verifiable context is `ready` or `not ready`. It renders local instance state; it does not own Build Plan, proof, or readiness semantics.
-
-Everywhere Interf shows a resource — Source, context output, Build Plan files, run artifacts — the API returns a single locator shape: `{ kind, value }`. `local-path` means the engine has filesystem access to the same host as the user; `remote-url` is a signed URL the UI opens in a browser tab; `api-served` is a relative API route the UI fetches and renders inline. Local engines today return `local-path`; the same shape carries forward unchanged when a remote instance fronts the API.
-
-## CLI Connection
-
-The CLI is a thin authorized client of one connected instance. It carries one active connection record:
-
-```text
-{
-  "url": "http://127.0.0.1:4873",
-  "auth_token": null
-}
+interf plan improve <project-id>
 ```
 
-`interf web` and `interf web start` write that record on startup. `interf login --url <remote>` writes a remote one (the cloud backend ships in a future release; the wire shape and config layer ship now). `interf logout` clears it.
-
-If the connection is unreachable, every mutating command exits non-zero with:
+A Build Plan is a folder you can read and version:
 
 ```text
-Not connected to any Interf instance.
-Start one with `interf web` or `interf web start`, or set --url / `interf login` for a remote one.
+<build-plan>/
+  build-plan.json         # outputs, stages, and build rules
+  build-plan.schema.json  # the output contract: what the graph must contain
+  build/stages/<stage>/   # the instructions Interf runs for each stage
+  use/query/              # how agents read the graph for the task
+  improve/                # how Interf revises the plan when checks still fail
 ```
 
-There is no implicit auto-start. There is no per-folder pointer file. One mental model: client connects to instance, explicitly starts one, or doesn't.
-
-## Readiness Checks
-
-There are two checks in the system, and they answer different questions.
-
-Build Plan Artifact checks check the build: did the plan produce the files, folders, Artifacts, and stage outputs it promised? Interf checks those while it builds.
-
-Readiness checks check the verifiable context: is this Preparation good enough for the specific agent work? They are the confidence layer on top of the context, not the product output.
-
-In the setup flow, readiness checks often look like plain question-and-answer pairs. On the API, they live under each preparation's `checks[]`. They help define whether the context is `ready` or `not ready`. A check should be a small, verifiable fact or condition you already know from the files:
-
-- one exact number from a chart, table, or filing
-- one short statement that should be true or false
-- one comparison across years, files, or sections
-
-Interf proposes an initial set from the files and the description of the job agents need to do. You confirm, edit, or replace them. `interf test` runs those checks through the configured local agent against source files, verifiable context, or both. The context itself does not answer; the agent answers while using it.
-
-A maintained readiness example in this repo uses one market report, two readiness checks, and two agents:
-
-<!-- PUBLIC_BENCHMARK_TABLE:START -->
-| Agent | Source files | Verifiable context |
-| --- | --- | --- |
-| Codex (GPT-5.4, xhigh) | `2/2` | `2/2` |
-| Claude Code (Claude Opus 4.6, max) | `0/2` | `2/2` |
-<!-- PUBLIC_BENCHMARK_TABLE:END -->
-
-Codex passed from the source files; Claude Code only passed when working from Interf's verifiable context. Both numbers come from the same readiness-check pass. That is evidence about whether this context is `ready` for this agent work.
-
-A maintained public test example uses this preparation:
-
-<!-- PUBLIC_TEST_CHECKS:START -->
-```text
-{
-  "id": "cbre-chart-sanity",
-  "source": { "kind": "local-folder", "locator": "./task-files" },
-  "build_plan_id": "interf-default",
-  "about": "Bristol historical take-up and availability chart lookup.",
-  "requested_artifacts": [
-    {
-      "title": "Guide to the report",
-      "checks": ["Every page is listed.", "Pages about Bristol charts are marked."]
-    },
-    {
-      "title": "Annual take-up and availability figures",
-      "checks": ["Every figure has a page reference.", "Approximate chart-derived reads are labelled."]
-    }
-  ],
-  "checks": [
-    {
-      "question": "What were Bristol's annual take-up values in 2018 and 2016?",
-      "answer": "Around half a million sq ft in 2018, roughly 0.45 to 0.6 million sq ft, and about 0.7 to 0.8 million sq ft in 2016. These are approximate chart-derived reads."
-    },
-    {
-      "question": "What were Bristol's availability values in 2018 and 2016?",
-      "answer": "About 0.55 to 0.6 million sq ft in 2018 and about 1.2 to 1.3 million sq ft in 2016. These are approximate chart-derived reads."
-    }
-  ]
-}
-```
-<!-- PUBLIC_TEST_CHECKS:END -->
-
-## What Interf Is Not
-
-- Not a second brain or memory product. One preparation per agent job; nothing global.
-- Not a vector store or RAG server. The context output is plain files.
-- Not a hosted data platform. The local instance runs on your machine; your bytes never leave it.
-- Not an agent harness. Interf builds verifiable context; your existing agent reads it.
-
-## Useful Commands
-
-- `interf web` — run the local engine in the foreground (Interf UI + API)
-- `interf web start` — start a managed background local engine for agent sessions
-- `interf web stop` — kill the running local engine
-- `interf prep ls / create / show / rm` — manage preparations
-- `interf build <prep-id>` — build verifiable context, returns the artifact locator
-- `interf test <prep-id>` — run readiness checks against source files and/or verifiable context
-- `interf build-plan list / show / save / draft / select / improve` — manage Build Plans
-- `interf agents ls / use / register / unregister / map / unmap` — manage connected agents and the role map
-- `interf runs ls / status / cancel / fetch` — inspect runs
-- `interf login / logout` — manage the active connection record (remote backend ships in a future release)
-- `interf status` — show the active connection and a preparation summary
-- `interf doctor --live` — check the local executor
-
-## Public Assets
-
-- [skills/interf](./skills/interf/) — bundled agent Skill for Interf.
-- [plugins/interf](./plugins/interf/) — local MCP host bundle for agents that support local MCP servers.
-- [build-plans/interf-default](./build-plans/interf-default/) — default Build Plan that ships with `interf`.
-
-Contributors: see [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-License: see [LICENSE.md](./LICENSE.md). © 2026 Interf Inc. All rights reserved.
-Name and branding: see [TRADEMARKS.md](./TRADEMARKS.md).
+## Commands
+
+| Command | What it does |
+|---|---|
+| `interf` / `interf init` | Open the interactive wizard |
+| `interf runtime` / `start` / `stop` | Run, background, or stop the local runtime |
+| `interf project create / ls / show / rm` | Manage Projects |
+| `interf plan draft / select / improve / save / list / show` | Manage Build Plans |
+| `interf build <id>` | Build the graph for a Project |
+| `interf graphs ls / show --project <id>` | Inspect built graphs |
+| `interf traces ls / show --project <id>` | Inspect source provenance |
+| `interf runs ls / status --project <id>` | Inspect Runs |
+| `interf benchmark <id>` | Optional accuracy check |
+| `interf agents ls / use / register / map` | Configure local execution agents |
+| `interf status` | Connection and Project summary |
+| `interf doctor --live` | Check your agent before a Build |
+
+## What Interf is not
+
+- Not a second brain or memory product: one Project, one Source, one task.
+- Not a vector store or hosted RAG server: the graph is inspectable, source-backed files.
+- Not a hosted data platform: local Builds run on your machine.
+- Not a general knowledge graph or notes app: each graph is built for one agent task, not a single index of everything.
+
+## More
+
+- [skills/interf](./skills/interf/): the bundled agent Skill.
+- [build-plans/interf-default](./build-plans/interf-default/): the default Build Plan.
+- [CONTRIBUTING.md](./CONTRIBUTING.md) · [LICENSE.md](./LICENSE.md) · [TRADEMARKS.md](./TRADEMARKS.md)
+
+© 2026 Interf Inc. All rights reserved.

package/public-repo/SECURITY.md

@@ -4,7 +4,7 @@ We take security issues seriously. Thank you for helping keep Interf safe for th
 
 ## Supported Versions
 
-Only the latest published release of `@interf/compiler` on npm and the current `main` branch of [`interf-labs/interf`](https://github.com/interf-labs/interf) receive security fixes.
+Only the latest published release of `@interf/compiler` on npm and the current `main` branch of [`interf-labs/compiler`](https://github.com/interf-labs/compiler) receive security fixes.
 
 ## Reporting a Vulnerability
 
@@ -13,7 +13,7 @@ Only the latest published release of `@interf/compiler` on npm and the current `
 Preferred disclosure paths, in order:
 
 1. **Email**: [security@interf.com](mailto:security@interf.com) — primary contact for any security report
-2. **GitHub Security Advisories**: use [private vulnerability reporting](https://github.com/interf-labs/interf/security/advisories/new) on the `interf-labs/interf` repository
+2. **GitHub Security Advisories**: use [private vulnerability reporting](https://github.com/interf-labs/compiler/security/advisories/new) on the `interf-labs/compiler` repository
 3. **PGP**: encrypted reports accepted on request via the email above
 
 Please include:
@@ -46,7 +46,7 @@ Security reports are especially relevant for:
 - unsafe filesystem writes or path traversal
 - command execution boundaries (subprocess, agent shell-out)
 - accidental leakage of private local files or runtime artifacts
-- authentication or authorization bypasses on `interf web` / `/v1/*` endpoints
+- authentication or authorization bypasses on `interf runtime` / `/v1/*` endpoints
 - test or Build Plan files causing unintended code execution
 - supply-chain risks in dependencies
 
@@ -64,4 +64,3 @@ For our compliance posture, control attestations, and policy documentation see [
 - General inquiries: [info@interf.com](mailto:info@interf.com)
 - Trust Center: [trust.interf.com](https://trust.interf.com)
 - Trademark questions: see [TRADEMARKS.md](./TRADEMARKS.md)
-</content>

package/public-repo/build-plans/interf-default/README.md

@@ -1,33 +1,41 @@
 # Built-in Interf Build Plan
 
-Built-in file-processing Build Plan: build traceable artifacts with proof by summarizing source-grounded evidence, structuring cross-file connections, and shaping verifiable context around the saved readiness checks.
+Built-in Build Plan that builds a three-layer Context Graph from source files:
+summaries for coverage, knowledge for task-aware graph structure, and
+home.md/artifacts for downstream agent entrypoints with links back to sources.
 
 ## Purpose
 
-- General Build Plan implementation for building verifiable context agents can use.
-- Build mixed source files into evidence-backed summaries, cross-file structure, and a usable entrypoint for agents running the readiness checks this agent work depends on.
+- General Build Plan implementation for preparing data for agents from source files.
+- Build mixed source files into source coverage summaries, task-aware knowledge, entrypoints, and links back to sources the downstream agent can use without rediscovering the Source.
 
-## Artifacts
+## Requested Outputs
 
-- `summaries` — output directory at `summaries`
-- `knowledge-entities` — output directory at `knowledge/entities`
-- `knowledge-claims` — output directory at `knowledge/claims`
-- `knowledge-indexes` — output directory at `knowledge/indexes`
-- `atlas` — output file at `home.md` used as the primary entrypoint for this Build Plan
+- `summaries` — source coverage directory at `summaries`
+- `knowledge` — task-aware graph directory at `knowledge`; current default is
+  flat `knowledge/*.md`, not required `knowledge/entities/`,
+  `knowledge/claims/`, or `knowledge/indexes/` folders
+- `artifacts` — task-specific entrypoint note directory at `artifacts`
+- `home` — Context Graph index file at `home.md`
 
 ## Stages
 
 Each stage is a folder with a `SKILL.md` file. Interf creates the stage shell,
-attaches source references and runtime context, runs the agent against that
-plain-text Skill, and records proof of what the stage wrote.
+attaches source references and runtime context, runs the stage through the
+runtime contract, and records evidence of what the stage wrote. Flexible stages
+use the connected agent; `build-entrypoint` is assembled by the local service
+from reviewed knowledge and summary resources so `home.md` is deterministic.
 
-- `summarize` — Turn source files into per-file summaries. (build-file-evidence; reads: none; writes: summaries)
-- `structure` — Build the cross-file knowledge structure from the summaries. (build-knowledge-structure; reads: summaries; writes: knowledge-entities, knowledge-claims, knowledge-indexes)
-- `shape` — Shape the final verifiable context around the saved task focus and readiness checks. (build-query-shape; reads: summaries, knowledge-entities, knowledge-claims, knowledge-indexes; writes: knowledge-indexes, atlas)
+- `summarize` — Turn source files into source-named coverage folders with source metadata. (build-file-evidence; reads: none; writes: summaries)
+- `knowledge` — Build the task-aware Context Graph knowledge layer from summaries, including entities, claims, topics, indexes, and links back to sources. (build-knowledge; reads: summaries; writes: knowledge)
+- `entrypoint` — Assemble home.md as the primary agent entrypoint plus task-specific entrypoint notes around the saved Project intent and coverage. (build-entrypoint; reads: summaries, knowledge; writes: knowledge, artifacts, home)
 
 ## Why `home.md` exists here
 
-This built-in Build Plan creates `home.md` as the main agent entrypoint for the verifiable context.
-That is behavior of the `interf-default` Build Plan implementation, not a local-engine rule.
+This built-in Build Plan creates `home.md` as the primary Context Graph
+entrypoint. Downstream agents should start from `home.md`, then follow links
+into `knowledge/`, `summaries/`, `artifacts/`, and source refs. That is
+behavior of the `interf-default` Build Plan implementation, not a local-service
+invariant.
 
 This package is the built-in seed for `interf-default`.

package/public-repo/build-plans/interf-default/build/stages/entrypoint/SKILL.md

@@ -0,0 +1,74 @@
+# Entrypoint
+
+Assemble the primary Context Graph entrypoint and task-specific entrypoint
+notes around the saved Project intent and coverage.
+
+Contract type: `build-entrypoint`
+
+This stage is service-owned in the default local runtime. The local service
+uses the same stage shell, expected inputs, reviewed inputs, output validation,
+and StageManifest path, but writes deterministic routing notes from already
+prepared summaries and knowledge instead of asking an agent to reinterpret the
+Source.
+
+## Requirements
+
+- Read `runtime/project.json`, `runtime/stage-contract.json.project.intent`,
+  `runtime/expected-inputs.json`, summaries, and knowledge notes before writing
+  outputs.
+- Write `runtime/reviewed-inputs.json` with one decision for every required
+  expected knowledge note before DONE.
+- `runtime/reviewed-inputs.json` must use this shape:
+- `{`
+- `  "kind": "interf-stage-reviewed-inputs",`
+- `  "version": 1,`
+- `  "generated_at": "2026-01-01T00:00:00.000Z",`
+- `  "stage_id": "entrypoint",`
+- `  "reviewed": [`
+- `    { "resource_id": "knowledge-example", "decision": "used", "source_refs": ["knowledge/example.md"] }`
+- `  ]`
+- `}`
+- Use Project intent plus coverage from summaries and knowledge to shape
+  `home.md`, `artifacts/`, and supporting graph routes.
+- Write `home.md` as the downstream agent's primary entrypoint. It must tell
+  the next agent where to start, what source refs matter, and what caveats or
+  source re-checks remain.
+- Route into all three fixed layers: `summaries/` (coverage — every Source file
+  read), `knowledge/` (the connected knowledge web — traverse/query),
+  `artifacts/` (task handoffs). Do not introduce a new top-level folder; richer
+  structure nests under `knowledge/`.
+- Close the whole-graph connectivity floor (`graph_notes_connected`): EVERY note
+  in the graph — including every summary, not only the ones a knowledge note
+  happened to cite — must be reachable through the link web. A summary that no
+  note links is a free-floating island and fails readiness. Make `home.md` (or a
+  coverage-index note it links, e.g. `summaries/index.md`) route into the
+  coverage layer so every summary has at least one inbound link. For a large
+  coverage layer, prefer a `summaries/` index note that links each summary and
+  link that index from `home.md`, rather than listing hundreds of summaries
+  directly in `home.md`. The floor is connectedness, not a quota — one genuine
+  inbound or outbound link per note is enough; never fabricate links to pass.
+- Write at least one task-specific entrypoint note under `artifacts/` when it
+  helps the agent continue from prepared context.
+- Each task entrypoint note must start with JSON frontmatter containing non-empty `task`, `source_refs`, `handoff_type`, and `caveats`. Optional routing fields (for example a source-evidence posture or a coverage state) may be added when they help the next agent, but the gating keys are those four.
+- `source_refs` must point to original Source locations, not just generated summaries or knowledge notes.
+- Task entrypoint notes should tell the downstream agent which original Source files, pages, figures, tables, sections, units, periods, series, and caveats matter for the task.
+- Task entrypoint notes should route the downstream agent to original Source refs for exact claims. Do not present generated summaries or knowledge notes as the dataset or source of truth.
+- Do not leave the scaffold `Not yet built.` placeholder in place.
+- When you add wikilinks, target real Context Graph notes by exact basename or explicit relative path.
+- If you introduce a new note name in `home.md` or another shaped output, the same stage must also create that note file.
+- Prefer direct file-reading and search tools over shell commands for routine file inspection.
+- When a source value is approximate, preserve it as a bounded range and say why it is approximate.
+- Do not invent finer precision than the source supports.
+- For unlabeled charts, screenshots, diagrams, or visual marks, either create a measurement note with source-grounded visual reference, calibration, method, and uncertainty, or tell the downstream agent to inspect the original Source before answering.
+- Keep approximate values consistent across `home.md`, focused indexes, and claim/entity notes.
+- Do not copy expected answers into the Context Graph.
+
+## Notes
+
+- Use the saved Project intent and coverage metrics to bias the final Context Graph toward the job it should be especially good at.
+- Do not copy benchmark expected answers into the final Context Graph.
+- Prefer the saved summary evidence and structured notes when they already preserve routing, source refs, and caveats.
+- Reopen source references during shaping when exact wording, table values, chart reads, or provenance-sensitive claims matter.
+- If a prepared value depends on source-derived values, route the entrypoint or handoff to source refs and preserve source granularity instead of fabricating precision.
+- Prefer better routing, prioritization, and focused navigation over speculative synthesis.
+- Any wikilinks you add to `home.md` or indexes must resolve to real Context Graph note basenames or explicit relative paths.