@interf/compiler 0.33.0 → 0.50.0

package/dist/packages/runtime/verify/verify-specs.js

@@ -2,7 +2,7 @@ import { existsSync, mkdirSync, readdirSync, writeFileSync, } from "node:fs";
 import { basename, extname, join } from "node:path";
 import { readJsonFileWithSchema } from "../../contracts/utils/parse.js";
 import { TestSpecSchema } from "./lib/schema.js";
-import { TEST_SPEC_EXTENSIONS, assertTestId, assertWritableTestSpecPath, testSpecFilePath, testSpecTypePath, normalizeTestId, } from "./verify-paths.js";
+import { TEST_SPEC_EXTENSIONS, assertTestId, assertSafeRelativeTestFile, assertWritableTestSpecPath, testSpecFilePath, testSpecTypePath, normalizeTestId, } from "./verify-paths.js";
 function readTestSpecFile(filePath) {
     const extension = extname(filePath).toLowerCase();
     if (!TEST_SPEC_EXTENSIONS.has(extension))
@@ -71,44 +71,54 @@ export function writeTestSpec(sourcePath, spec, options = {}) {
         ...(spec.description && spec.description.trim().length > 0
             ? { description: spec.description.trim() }
             : {}),
-        cases: spec.cases.map((testCase) => ({
-            id: normalizeTestId(testCase.id),
-            question: testCase.question.trim(),
-            ...(testCase.file && testCase.file.trim().length > 0
-                ? { file: testCase.file.trim() }
-                : {}),
-            ...(testCase.answer && testCase.answer.trim().length > 0
-                ? { answer: testCase.answer.trim() }
-                : {}),
-            ...(testCase.strictness && testCase.strictness.trim().length > 0
-                ? { strictness: testCase.strictness.trim() }
-                : {}),
-            ...(testCase.expect
-                ? {
-                    expect: {
-                        ...(testCase.expect.must_include && testCase.expect.must_include.length > 0
-                            ? { must_include: testCase.expect.must_include.map((value) => value.trim()).filter(Boolean) }
-                            : {}),
-                        ...(testCase.expect.must_include_one_of && testCase.expect.must_include_one_of.length > 0
-                            ? {
-                                must_include_one_of: testCase.expect.must_include_one_of
-                                    .map((group) => group.map((value) => value.trim()).filter(Boolean))
-                                    .filter((group) => group.length > 0),
-                            }
-                            : {}),
-                        ...(testCase.expect.must_not_include && testCase.expect.must_not_include.length > 0
-                            ? { must_not_include: testCase.expect.must_not_include.map((value) => value.trim()).filter(Boolean) }
-                            : {}),
-                        ...(typeof testCase.expect.min_words === "number"
-                            ? { min_words: testCase.expect.min_words }
-                            : {}),
-                        ...(typeof testCase.expect.max_words === "number"
-                            ? { max_words: testCase.expect.max_words }
-                            : {}),
-                    },
-                }
-                : {}),
-        })),
+        cases: spec.cases.map((testCase) => {
+            // H3: trim then safelist the relative path before persisting. A malicious
+            // `../../../etc/passwd` spec must be rejected here, not stored verbatim and
+            // later fed to path.join. This is the same guard the schema enforces (H2),
+            // applied at the write boundary so the spec is never written with an
+            // escaping file value.
+            const file = testCase.file?.trim();
+            if (file)
+                assertSafeRelativeTestFile(file);
+            return {
+                id: normalizeTestId(testCase.id),
+                question: testCase.question.trim(),
+                ...(file && file.length > 0
+                    ? { file }
+                    : {}),
+                ...(testCase.answer && testCase.answer.trim().length > 0
+                    ? { answer: testCase.answer.trim() }
+                    : {}),
+                ...(testCase.strictness && testCase.strictness.trim().length > 0
+                    ? { strictness: testCase.strictness.trim() }
+                    : {}),
+                ...(testCase.expect
+                    ? {
+                        expect: {
+                            ...(testCase.expect.must_include && testCase.expect.must_include.length > 0
+                                ? { must_include: testCase.expect.must_include.map((value) => value.trim()).filter(Boolean) }
+                                : {}),
+                            ...(testCase.expect.must_include_one_of && testCase.expect.must_include_one_of.length > 0
+                                ? {
+                                    must_include_one_of: testCase.expect.must_include_one_of
+                                        .map((group) => group.map((value) => value.trim()).filter(Boolean))
+                                        .filter((group) => group.length > 0),
+                                }
+                                : {}),
+                            ...(testCase.expect.must_not_include && testCase.expect.must_not_include.length > 0
+                                ? { must_not_include: testCase.expect.must_not_include.map((value) => value.trim()).filter(Boolean) }
+                                : {}),
+                            ...(typeof testCase.expect.min_words === "number"
+                                ? { min_words: testCase.expect.min_words }
+                                : {}),
+                            ...(typeof testCase.expect.max_words === "number"
+                                ? { max_words: testCase.expect.max_words }
+                                : {}),
+                        },
+                    }
+                    : {}),
+            };
+        }),
     };
     const parsed = TestSpecSchema.parse(normalizedSpec);
     writeFileSync(filePath, `${JSON.stringify(serializeTestSpec(parsed), null, 2)}\n`);

package/dist/packages/runtime/wire-schemas.d.ts

@@ -4,7 +4,7 @@
  * can render an actionable error rather than a stack trace.
  *
  * `issues` is typed as `unknown[]` so the class works across both
- * `zod` dependency trees in the monorepo (root + `src/apps/interf-desktop/renderer`).
+ * `zod` dependency trees in the monorepo.
  * Callers cast or render structurally as needed.
  */
 export declare class WireShapeError extends Error {

package/dist/packages/runtime/wire-schemas.js

@@ -4,7 +4,7 @@
  * can render an actionable error rather than a stack trace.
  *
  * `issues` is typed as `unknown[]` so the class works across both
- * `zod` dependency trees in the monorepo (root + `src/apps/interf-desktop/renderer`).
+ * `zod` dependency trees in the monorepo.
  * Callers cast or render structurally as needed.
  */
 export class WireShapeError extends Error {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@interf/compiler",
-  "version": "0.33.0",
+  "version": "0.50.0",
   "description": "Interf prepares data for agents by building Context Graphs from files.",
   "type": "module",
   "bin": {
@@ -45,13 +45,7 @@
   },
   "files": [
     "dist",
-    "public-repo",
-    "!dist/cli/commands/desktop.d.ts",
-    "!dist/cli/commands/desktop.js",
-    "!dist/desktop",
-    "!dist/desktop/**",
-    "!dist/desktop-renderer",
-    "!dist/desktop-renderer/**"
+    "public-repo"
   ],
   "publishConfig": {
     "access": "public"

package/public-repo/CONTRIBUTING.md

@@ -7,6 +7,10 @@ Only files under `public-repo` are intended for this public surface. Do not add
 source paths outside `public-repo`, maintainer docs, or repo-specific operating
 instructions here.
 
+The marketing website is maintained separately in `interf-labs/interf-website`.
+Do not add landing-page code, website assets, or website operating notes to this
+public SDK/package surface.
+
 ## What To Change Here
 
 - Public product docs: the public README, `SECURITY.md`, and `TRADEMARKS.md`.
@@ -17,11 +21,14 @@ instructions here.
 
 Build Plans are inspectable folders. Keep them standalone:
 
-- `build-plan.json` is the current technical filename for the Build Plan stages and Artifact outputs.
-- `build-plan.schema.json` is the current technical filename for the output contract.
+- `build-plan.json` is the current technical filename for Build Plan stages,
+  requested outputs, coverage requirements, and graph entrypoints.
+- `build-plan.schema.json` is the current technical filename for the Build Plan
+  package contract.
 - `build/stages/<stage>/SKILL.md` contains stage instructions.
 - `use/query/SKILL.md` tells agents how to read the Context Graph.
-- `improve/SKILL.md` tells Interf how to revise the Build Plan when checks fail.
+- `improve/SKILL.md` tells Interf how to revise the Build Plan when coverage,
+  Stage Manifest validation, or graph output requirements fail.
 
 For the shipped default Build Plan, edit `build-plans/interf-default/`.
 

package/public-repo/README.md

@@ -1,268 +1,164 @@
 # Interf
 
-**Interf prepares data for agents.**
+**Interf prepares data for agent tasks.**
 
-This npm package ships the `interf` CLI and local Interf runtime for building
-task-specific Context Graphs from 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.
 
-Agents miss things in files. When agents answer from a folder, they first have
-to discover what is in it, decide what matters, extract evidence, and connect
-facts across files. That file-to-context step is hidden, inconsistent, and hard
-to inspect.
+> This npm package is the `interf` CLI and local runtime. A Mac app (Interf
+> Desktop) is coming soon.
 
-Interf separates that step. It makes users' agents build a Context Graph from
-their files. It has source coverage summaries, task-aware knowledge, artifact
-handoffs, and links back to sources. Your agent uses the prepared map instead
-of rediscovering the files during the task.
-
-```text
-Source files                        Context Graph agents use
-
-bristol-office-market/              <context-graph>/
-  q4-market-report.pdf                AGENTS.md
-  lease-comps.xlsx                    home.md
-  planning-notes.md                   summaries/
-  exports/availability.csv            knowledge/
-                                      artifacts/
-                                      traces/
-```
-
-## What a Build Produces
-
-A Build produces a Context Graph. The Context Graph is source-backed context
-built from files so agents can use prepared context instead of partial file
-reads.
-
-For a local Build, the Context Graph is an inspectable folder:
-
-```text
-<context-graph>/
-  AGENTS.md              # agent guidance
-  home.md                # overview and routes
-  artifacts/             # task-specific agent handoffs
-  summaries/             # source coverage proof
-  knowledge/             # navigation and drilldown
-  traces/                # links back to sources
-```
-
-The output is not an answer. It is a prepared map over the Source: artifact
-handoffs, summaries, knowledge notes, and links back to sources. The Source
-remains the ground truth. Agents start from `artifacts/`, use `summaries/` for
-coverage proof and `knowledge/` for drilldown, then follow source links when
-exact wording, table values, chart reads, or provenance-sensitive claims matter.
-
-## Design Choices
-
-- `Project-scoped`: every Project starts from a specific Source and selected
-  Build Plan, not a generic index over every file.
-- `Inspectable`: Interf records what was built, which requested Artifacts exist,
-  and where source-backed traces live.
-- `Local-first`: local Builds keep Source files on your machine and read-only.
-- `Bring your own agent`: use Claude Code, Codex, or another registered
-  command-line agent.
-- `File over hidden index`: local Builds expose the Context Graph as a folder
-  agents can inspect.
-- `Context Checks you control`: every Build can be checked against
-  plain-English conditions such as "Every page is covered" or "Every figure
-  cites a source page."
-
-## Why Not Just Ask Your Agent?
-
-You can. Interf can use Claude Code, Codex, or another registered local agent
-while it builds the Context Graph.
-
-A one-off preprocessing prompt gives you another answer to trust. Interf puts
-the preparation step inside a Build Plan you can inspect: requested Artifacts,
-declared stages, Build evidence, Context Checks, and traces.
-
-The agent can still execute the stages. Interf shows what was covered, what was
-produced, and whether the Context Graph is ready for the task.
-
-## Install
+## Quick start
 
 ```bash
 npm install -g @interf/compiler
-interf            # opens the wizard
+interf                 # the interactive wizard walks you through your first build
 ```
 
-Requires Node.js 20+ and a local agent CLI such as Claude Code, Codex, or
-another registered command-line agent. 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
-# terminal 1: start the local Interf runtime
-interf runtime
-
-# terminal 2: create a Project from a local Source
-interf project create bristol --source ./bristol-office-market
+interf runtime                                 # start the local runtime
+interf project create bristol \                # bind a folder + the agent's task
+  --source ./bristol-office-market \
+  --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
+```
 
-# draft the Build Plan for review
-interf plan draft bristol \
-  --intent "Bristol annual take-up and availability chart lookup" \
-  --artifacts "Guide to the report; annual take-up figures with source references" \
-  --ready-when "Every page is listed and every figure has a source reference."
+`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.
 
-# select the reviewed Build Plan
-interf plan select bristol <build-plan-id>
+## What you get
 
-# build the Context Graph
-interf build bristol
+A folder your agent navigates instead of grepping raw files. Interf calls it a
+**Context Graph**:
 
-# optional: benchmark/evaluate answers from the Source baseline, Context Graph, or both
-interf benchmark bristol
+```text
+<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)
 ```
 
-`interf runtime` starts the local runtime in the foreground and writes the
-active connection record so subsequent CLI commands can connect. Agents can use
-`interf runtime start` for an explicit managed background runtime, then
-`interf runtime stop` when their task is done.
+`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.
 
-Mutating commands never implicitly auto-start a runtime. If no instance is
-connected, they exit with a hint pointing at `interf runtime`,
-`interf runtime start`, or `interf login`.
+## Why Interf is different
 
-`interf build` returns the Context Graph locator on success. For local Builds,
-that locator points to a folder agents can inspect and continue from. There is
-no `--out` flag and no implicit copy of your Source folder.
+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.
 
-## Context Graph
+And the graph is `provable`:
 
-The Context Graph is the output Interf builds from your files for agents. It is
-a knowledge map over the Source, not a replacement for the Source.
+- `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.
 
-It gives agents structure and source-backed routes for navigating files. For
-the built-in `interf-default`, it includes:
+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.
 
-```text
-<context-graph>/
-  AGENTS.md       # agent-facing guidance and source-checking rules
-  CLAUDE.md       # same guidance for Claude Code
-  home.md         # graph index
-  artifacts/      # task-specific handoffs for agents
-  summaries/      # one source-named folder per source file
-  knowledge/      # linked notes built from summaries and source refs
-  traces/         # source provenance for claims and checks
-```
+## Design principles
 
-The source files stay the source of truth. Interf writes generated state inside
-the instance data directory and does not modify the Source.
+- `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.
 
-`AGENTS.md` tells agents how to use the Context Graph: start from the prepared
-outputs, follow the prepared routes, and use the recorded source references
-when exact source evidence matters.
+## Readiness is provable
 
-## Build Plans
+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:
 
-A Build Plan tells Interf how to build requested Artifacts from your Source for
-the agent task. It also states the Context Checks the user can review before the
-Build.
+- **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.
 
-The built-in `interf-default` Build Plan ships with `interf`. Save your own
-local Build Plan with `interf plan save <path>`; draft new ones with
-`interf plan draft <project-id>`.
+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.
 
-```text
-<build-plan-folder>/
-  build-plan.json         # Build Plan definition: artifacts, stages, build rules
-  build-plan.schema.json  # output contract: required Context Graph files/folders
-  README.md               # what this Build Plan is for
-  build/
-    stages/
-      summarize/          # stage instructions Interf runs during the Build
-      structure/
-      shape/
-  use/
-    query/                # how agents read the Context Graph
-  improve/                # how Interf revises the plan if checks still fail
-```
+`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.
 
-- `build-plan.json` is the technical filename for the Build Plan definition:
-  requested Artifacts, stages, and how the files should be built.
-- `build-plan.schema.json` describes the output contract: what the Context Graph
-  must contain.
-- `build/stages/<stage>/` is where you author one folder per stage.
-- `use/query/` holds the instructions agents follow when they read the Context
-  Graph for the task.
-- `improve/` holds the instructions Interf follows when the first Build misses
-  and the Build Plan itself needs editing.
+## Build Plans
 
-## Build Plan Improvement
+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>`.
 
-When the first Build is `not ready`, Interf can edit the Build Plan and build
-again. Same Source, same checks, improved Build Plan and Context Graph.
+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 plan improve <project-id>
 ```
 
-Interf records Build Plan improvement as a Run with the revised Build Plan,
-Build evidence, and resulting Context Graph.
-
-## Context Checks And Benchmarks
-
-Context Checks are plain-English promises the user reviews before a Build.
-Requested Artifacts back those checks.
-
-Examples:
+A Build Plan is a folder you can read and version:
 
-- every file in scope was processed
-- required pages or slides were inventoried
-- required outputs exist
-- every figure cites a source page
-- the Source has not changed since the Build
-
-Benchmarks are different. A benchmark asks saved questions and measures answer
-accuracy against an agent source-access baseline, the Context Graph, or both.
-
-```bash
-interf benchmark bristol
-interf benchmark bristol --target source-files
-interf benchmark bristol --target context-graph
+```text
+<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
 ```
 
-`interf benchmark` is optional evaluation. It is not the main readiness surface.
-
-## What Interf Is Not
-
-- Not a second brain or memory product. One Project starts from one Source and
-  agent task.
-- Not a vector store or hosted RAG server. The Context Graph is structured
-  source-backed context agents can inspect.
-- Not a hosted data platform by default. Local Builds run on your machine.
-- Not a generic agent task orchestrator. Interf prepares files into Context
-  Graphs for agents.
-
-## Useful Commands
-
-- `interf` / `interf init` - open the interactive wizard.
-- `interf runtime` - run the local Interf runtime in the foreground.
-- `interf runtime start` - start a managed background local runtime.
-- `interf runtime stop` - stop the running local runtime.
-- `interf project ls / create / show / rm` - manage Projects.
-- `interf plan list / show / save / draft / select / improve` - manage Build
-  Plans.
-- `interf build <project-id>` - Build the Context Graph for a Project.
-- `interf graphs ls --project <id>` / `show <graph-id> --project <id>` - inspect
-  Context Graphs.
-- `interf traces ls --project <id>` / `show <trace-kind> --project <id>` -
-  inspect Context Graph traces.
-- `interf runs ls --project <id>` / `status <run-id>` - inspect Runs.
-- `interf benchmark <project-id>` - run an optional benchmark/evaluation pass.
-- `interf agents ls / use / register / unregister / map / unmap` - configure
-  local agents and role mapping.
-- `interf login / logout` - connect the CLI to another Interf instance.
-- `interf status` - show the active connection and Project summary.
-- `interf doctor --live` - check the local executor before a Build.
-
-## Public Assets
-
-- [skills/interf](./skills/interf/) - bundled agent Skill for Interf.
-- [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/build-plans/interf-default/README.md

@@ -2,37 +2,40 @@
 
 Built-in Build Plan that builds a three-layer Context Graph from source files:
 summaries for coverage, knowledge for task-aware graph structure, and
-artifacts for downstream agent handoff with links back to sources.
+home.md/artifacts for downstream agent entrypoints with links back to sources.
 
 ## Purpose
 
 - General Build Plan implementation for preparing data for agents from source files.
-- Build mixed source files into source coverage summaries, task-aware knowledge, Artifact handoffs, and links back to sources the downstream agent can use without rediscovering the Source.
+- 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` — 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 agent handoff directory at `artifacts`
+- `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 evidence 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 source-named coverage folders with source metadata. (build-file-evidence; reads: none; writes: summaries)
-- `structure` — Build the task-aware Context Graph structure from summaries, including entities, claims, topics, indexes, and links back to sources. (build-knowledge-structure; reads: summaries; writes: knowledge)
-- `shape` — Shape task-specific Artifact handoffs and the final Context Graph around the saved task focus and Context Checks. (build-query-shape; reads: summaries, knowledge; writes: knowledge, artifacts, home)
+- `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 Context Graph index.
-Downstream agents should start from `artifacts/` for task handoffs and use
-`home.md` only to navigate the graph. That is behavior of the `interf-default`
-Build Plan implementation, not a local-service invariant.
+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`.