diff --git a/.gitignore b/.gitignore
index b10c388..8487ac1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -55,3 +55,7 @@ internal/web/dist/*
 /.mcp.json
 /.githooks/
 /specs/
+
+# csdd operational state (.csdd/): local, regenerable — but commit manifests.
+/.csdd/state.json
+/.csdd/cache/
diff --git a/go.mod b/go.mod
index b36e6a1..8fbbde0 100644
--- a/go.mod
+++ b/go.mod
@@ -6,6 +6,7 @@ require (
 	github.com/charmbracelet/bubbles v0.18.0
 	github.com/charmbracelet/bubbletea v0.25.0
 	github.com/charmbracelet/lipgloss v0.10.0
+	golang.org/x/text v0.3.8
 )
 
 require (
@@ -24,5 +25,4 @@ require (
 	golang.org/x/sync v0.1.0 // indirect
 	golang.org/x/sys v0.12.0 // indirect
 	golang.org/x/term v0.6.0 // indirect
-	golang.org/x/text v0.3.8 // indirect
 )
diff --git a/internal/cli/claudemd.go b/internal/cli/claudemd.go
index 910f506..e2ad28d 100644
--- a/internal/cli/claudemd.go
+++ b/internal/cli/claudemd.go
@@ -1,10 +1,12 @@
 package cli
 
 import (
+	"embed"
 	"os"
 	"strings"
 
 	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/templater"
 	"github.com/protonspy/csdd/internal/textutil"
 	"github.com/protonspy/csdd/internal/workspace"
 )
@@ -15,6 +17,60 @@ const (
 	steeringMarkerEnd   = "<!-- csdd:steering:end -->"
 )
 
+// Markers delimiting the csdd-managed knowledge-base section inside CLAUDE.md
+// (the graph/wiki workflow moments + the tech-contract protocol).
+const (
+	knowledgeMarkerStart = "<!-- csdd:knowledge:start -->"
+	knowledgeMarkerEnd   = "<!-- csdd:knowledge:end -->"
+)
+
+// ensureKnowledgeSection writes the knowledge-base workflow moments (R16.3) and
+// the tech-contract protocol (R17.4, R17.7) into the managed block of CLAUDE.md.
+// It fills the empty markers a fresh template ships with, and — for a legacy
+// CLAUDE.md that predates them — appends the whole section (markers + content).
+// A no-op when CLAUDE.md is absent. Returns whether the file was changed.
+func ensureKnowledgeSection(root string, templates embed.FS) (bool, error) {
+	entry := paths.Entry(root)
+	data, err := os.ReadFile(entry)
+	if err != nil {
+		return false, nil // no CLAUDE.md — nothing to wire
+	}
+	body, err := templater.Static(templates, "templates/root/knowledge-section.md.tmpl")
+	if err != nil {
+		return false, err
+	}
+	body = strings.TrimRight(body, "\n")
+	text := textutil.NormalizeNewlines(string(data))
+
+	start := strings.Index(text, knowledgeMarkerStart)
+	end := strings.Index(text, knowledgeMarkerEnd)
+	var rebuilt string
+	switch {
+	case start != -1 && end != -1 && end > start:
+		// Fill (or refresh) the content between existing markers.
+		before := text[:start+len(knowledgeMarkerStart)]
+		after := text[end:]
+		newBlock := before + "\n" + body + "\n" + after
+		if newBlock == text {
+			return false, nil
+		}
+		rebuilt = newBlock
+	default:
+		// Legacy CLAUDE.md without the markers: append the managed section.
+		section := "\n## Knowledge base — graph, wiki, tech contract\n\n" +
+			knowledgeMarkerStart + "\n" + body + "\n" + knowledgeMarkerEnd + "\n"
+		if strings.HasSuffix(text, "\n") {
+			rebuilt = text + section
+		} else {
+			rebuilt = text + "\n" + section
+		}
+	}
+	if err := workspace.AtomicWrite(entry, []byte(rebuilt), 0o644); err != nil {
+		return false, err
+	}
+	return true, nil
+}
+
 // ensureSteeringImports inserts `@.claude/steering/<name>` import lines into the
 // managed block of CLAUDE.md, one per steering file name (e.g. "product.md").
 // It is idempotent and a safe no-op when CLAUDE.md is missing or has no managed
diff --git a/internal/cli/cli.go b/internal/cli/cli.go
index a54c4a2..b96625e 100644
--- a/internal/cli/cli.go
+++ b/internal/cli/cli.go
@@ -62,6 +62,10 @@ func Run(args []string, templates embed.FS) int {
 		return runAgent(rest, templates)
 	case "mcp":
 		return runMCP(rest)
+	case "graph":
+		return runGraph(rest)
+	case "wiki":
+		return runWiki(rest, templates)
 	case "export":
 		return runExport(rest)
 	case "web", "--web":
@@ -139,6 +143,8 @@ RESOURCES
   skill    {create,list,show,add-reference,add-script,add-asset,validate,delete}
   agent    {create,list,show,delete}
   mcp      {add,install,presets,list,show,remove,enable,disable,validate}
+  graph    {build,query,path,explain,analyze,export}   The knowledge-base index (a structured brain over the workspace).
+  wiki     {init,lint}                 The LLM-authored knowledge base under docs/ (scaffold + health lint).
   export   {kiro,codex}                Convert the workspace to Kiro / Codex format.
   web                         Launch a read-only web dashboard (live spec progress + file viewer).
 
diff --git a/internal/cli/e2e_graph_test.go b/internal/cli/e2e_graph_test.go
new file mode 100644
index 0000000..fa515cf
--- /dev/null
+++ b/internal/cli/e2e_graph_test.go
@@ -0,0 +1,69 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// TestE2EGoldenPath drives the full knowledge-base flow through the CLI on a
+// fixture workspace: init → build → analyze → query, and wiki lint — asserting
+// the golden path holds end-to-end and the graph.json is byte-stable across
+// rebuilds (task 15.1).
+func TestE2EGoldenPath(t *testing.T) {
+	dir := freshWorkspace(t)
+	seedSpec(t, dir)
+
+	// build → graph.json exists.
+	if code, _, e := run(t, "graph", "build", "--root", dir); code != 0 {
+		t.Fatalf("graph build failed: %s", e)
+	}
+	graphPath := filepath.Join(dir, "docs", "graph", "graph.json")
+	first, err := os.ReadFile(graphPath)
+	if err != nil {
+		t.Fatalf("graph.json missing: %v", err)
+	}
+
+	// A second build with an unchanged corpus is byte-identical (§5.9, R7.2).
+	if code, _, e := run(t, "graph", "build", "--root", dir, "--full"); code != 0 {
+		t.Fatalf("second build failed: %s", e)
+	}
+	second, _ := os.ReadFile(graphPath)
+	if string(first) != string(second) {
+		t.Fatalf("graph.json not byte-stable across rebuilds")
+	}
+
+	// Incremental (default) also matches the full rebuild byte-for-byte.
+	if code, _, e := run(t, "graph", "build", "--root", dir); code != 0 {
+		t.Fatalf("incremental build failed: %s", e)
+	}
+	third, _ := os.ReadFile(graphPath)
+	if string(first) != string(third) {
+		t.Fatalf("incremental graph.json differs from full rebuild")
+	}
+
+	// analyze surfaces the seeded gap (criterion 1.2 untested); --strict gates.
+	if code, out, _ := run(t, "graph", "analyze", "--root", dir); code != 0 || !strings.Contains(out, "criterion") {
+		t.Fatalf("analyze: code=%d out=%s", code, out)
+	}
+	if code, _, _ := run(t, "graph", "analyze", "--strict", "--root", dir); code == 0 {
+		t.Fatalf("analyze --strict should gate non-zero on findings")
+	}
+
+	// query resolves the design component.
+	if code, out, _ := run(t, "graph", "query", "Svc", "--root", dir); code != 0 || !strings.Contains(out, "Svc") {
+		t.Fatalf("query: code=%d out=%s", code, out)
+	}
+
+	// wiki lint on the clean init scaffold passes; a dropped raw source fails it.
+	if code, _, _ := run(t, "wiki", "lint", "--root", dir); code != 0 {
+		t.Fatalf("clean wiki lint should pass")
+	}
+	if err := os.WriteFile(filepath.Join(dir, "docs", "raw", "src.md"), []byte("x"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	if code, _, _ := run(t, "wiki", "lint", "--root", dir); code == 0 {
+		t.Fatalf("unprocessed raw source should fail wiki lint")
+	}
+}
diff --git a/internal/cli/graph.go b/internal/cli/graph.go
new file mode 100644
index 0000000..a2e238c
--- /dev/null
+++ b/internal/cli/graph.go
@@ -0,0 +1,359 @@
+package cli
+
+import (
+	"flag"
+	"fmt"
+	"os"
+	"time"
+
+	"github.com/protonspy/csdd/internal/graph"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/render"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// runGraph dispatches `csdd graph <action>`. The graph is a structured brain for
+// fast, token-cheap, precise consultation of the workspace: build persists the
+// index, query/path/explain traverse it, analyze lints the SDD contract.
+func runGraph(args []string) int {
+	action, rest, err := parseAction("graph", args)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if isHelpFlag(action) {
+		graphHelp()
+		return 0
+	}
+	switch action {
+	case "build":
+		return graphBuild(rest)
+	case "query":
+		return graphQuery(rest)
+	case "path":
+		return graphPath(rest)
+	case "explain":
+		return graphExplain(rest)
+	case "analyze":
+		return graphAnalyze(rest)
+	case "export":
+		return graphExport(rest)
+	default:
+		render.Err("unknown action for `graph`: " + action)
+		graphHelp()
+		return 1
+	}
+}
+
+func graphHelp() {
+	fmt.Println(`csdd graph — the knowledge-base index (a structured brain over the workspace).
+
+  build            Rebuild docs/graph/graph.json from the corpus (+ appends log.md).
+  query "<terms>"  Find nodes by label tier and show their neighborhood.
+  path <A> <B>     Shortest path between two nodes.
+  explain <label>  A node plus its connections, ordered by neighbor degree.
+  analyze          Surface traceability gaps + wiki/tech lints (--strict exits non-zero).
+  export           Write docs/graph/graph.html (self-contained visualization).
+
+Common flags: --root DIR, --json.`)
+}
+
+// requireWorkspace enforces the .csdd/ marker (R15.2), with an explicit
+// legacy-upgrade message when only .claude/ exists (R15.3).
+func requireWorkspace(root string) error {
+	if dirExists(paths.State(root)) {
+		return nil
+	}
+	if dirExists(paths.Claude(root)) {
+		return fmt.Errorf("legacy csdd workspace: found .claude/ but no .csdd/ at %s — re-run `%s init` to upgrade it in place (nothing is overwritten; only the missing .csdd/ and other new pieces are added)", root, prog())
+	}
+	return fmt.Errorf("not a csdd workspace (no .csdd/ at %s) — run `%s init` first", root, prog())
+}
+
+// resolveGraphRoot resolves --root and enforces the workspace marker.
+func resolveGraphRoot(root string) (string, error) {
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		return "", err
+	}
+	if err := requireWorkspace(r); err != nil {
+		return "", err
+	}
+	return r, nil
+}
+
+func graphBuild(args []string) int {
+	fs := flag.NewFlagSet("graph build", flag.ContinueOnError)
+	var root string
+	var jsonOut, full bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	fs.BoolVar(&full, "full", false, "Force a complete rebuild instead of the incremental default.")
+	if err := fs.Parse(args); err != nil {
+		return failOnFlagParse(err)
+	}
+	r, err := resolveGraphRoot(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	// Incremental is the default; --full forces a complete rebuild (R13.3). Both
+	// produce byte-identical output.
+	build := graph.BuildIncremental
+	if full {
+		build = graph.Build
+	}
+	g, err := build(r)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if _, err := graph.WriteBuild(r, g, time.Now()); err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if jsonOut {
+		return emitJSON(map[string]any{
+			"ok": true, "nodes": len(g.Nodes), "edges": len(g.Links),
+			"pending": len(g.Pending), "output": graph.GraphJSONRel,
+		})
+	}
+	render.OK(fmt.Sprintf("Built graph: %d nodes, %d edges (%d pending references).", len(g.Nodes), len(g.Links), len(g.Pending)))
+	render.Info("Wrote " + graph.GraphJSONRel)
+	return 0
+}
+
+func graphQuery(args []string) int {
+	fs := flag.NewFlagSet("graph query", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	var hops, budget int
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	fs.IntVar(&hops, "hops", 1, "Neighborhood radius.")
+	fs.IntVar(&budget, "budget", 2000, "Token budget for rendering (M4 engine).")
+	pos, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(pos) == 0 {
+		render.Err("usage: " + prog() + " graph query \"<terms>\"")
+		return 1
+	}
+	terms := pos[0]
+	g, r, code := loadGraph(root)
+	if code != 0 {
+		return code
+	}
+	_ = r
+	matches := graph.Query(g, terms, graph.QueryOptions{Hops: hops, Budget: budget})
+	if jsonOut {
+		return emitJSON(map[string]any{"query": terms, "matches": matches})
+	}
+	if len(matches) == 0 {
+		render.Info("No nodes match " + terms)
+		return 0
+	}
+	for _, m := range matches {
+		fmt.Printf("%s  %s  [%s, %s]\n", render.Bold(m.Node.Label), render.Cyan(m.Node.ID), m.Node.FileType, m.Tier)
+		for _, nb := range m.Neighbors {
+			arrow := "→"
+			if nb.Direction == "in" {
+				arrow = "←"
+			}
+			fmt.Printf("    %s %s  %s (%s)\n", arrow, nb.Relation, nb.Node.Label, nb.Node.FileType)
+		}
+	}
+	return 0
+}
+
+func graphPath(args []string) int {
+	fs := flag.NewFlagSet("graph path", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	var maxHops int
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	fs.IntVar(&maxHops, "max-hops", 0, "Maximum path length (0 = unbounded).")
+	pos, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(pos) < 2 {
+		render.Err("usage: " + prog() + " graph path <A> <B>")
+		return 1
+	}
+	g, _, code := loadGraph(root)
+	if code != 0 {
+		return code
+	}
+	pr, err := graph.Path(g, pos[0], pos[1], maxHops)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if jsonOut {
+		return emitJSON(pr)
+	}
+	fmt.Printf("%s\n", render.Bold(pr.From.Label))
+	for _, s := range pr.Steps {
+		arrow := "──" + s.Relation + "──▶"
+		if s.Direction == "backward" {
+			arrow = "◀──" + s.Relation + "──"
+		}
+		fmt.Printf("  %s %s\n", arrow, s.Node.Label)
+	}
+	return 0
+}
+
+func graphExplain(args []string) int {
+	fs := flag.NewFlagSet("graph explain", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	pos, err := parseFlags(fs, args)
+	if err != nil {
+		return failOnFlagParse(err)
+	}
+	if len(pos) == 0 {
+		render.Err("usage: " + prog() + " graph explain <label>")
+		return 1
+	}
+	g, _, code := loadGraph(root)
+	if code != 0 {
+		return code
+	}
+	er, err := graph.Explain(g, pos[0])
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if jsonOut {
+		return emitJSON(er)
+	}
+	fmt.Printf("%s  %s  [%s]\n", render.Bold(er.Node.Label), render.Cyan(er.Node.ID), er.Node.FileType)
+	for _, c := range er.Connections {
+		arrow := "→"
+		if c.Direction == "in" {
+			arrow = "←"
+		}
+		fmt.Printf("  %s %s  %s (deg %d)\n", arrow, c.Relation, c.Node.Label, c.Degree)
+	}
+	return 0
+}
+
+func graphAnalyze(args []string) int {
+	fs := flag.NewFlagSet("graph analyze", flag.ContinueOnError)
+	var root string
+	var jsonOut, strict bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	fs.BoolVar(&strict, "strict", false, "Exit non-zero when any finding is reported (CI gate).")
+	if err := fs.Parse(args); err != nil {
+		return failOnFlagParse(err)
+	}
+	g, r, code := loadGraph(root)
+	if code != 0 {
+		return code
+	}
+	report := graph.Analyze(g, r)
+	if jsonOut {
+		exit := 0
+		if strict && len(report.Findings) > 0 {
+			exit = 2
+		}
+		_ = emitJSON(report)
+		return exit
+	}
+	if len(report.Findings) == 0 {
+		render.OK("No findings. Traceability contract is clean.")
+		return 0
+	}
+	renderFindings(report.Findings)
+	if len(report.GodNodes) > 0 {
+		render.Info(fmt.Sprintf("Hubs: %s", godNodeSummary(report.GodNodes)))
+	}
+	render.Warn(fmt.Sprintf("%d finding(s).", len(report.Findings)))
+	if strict {
+		return 2
+	}
+	return 0
+}
+
+func graphExport(args []string) int {
+	fs := flag.NewFlagSet("graph export", flag.ContinueOnError)
+	var root, out string
+	addRoot(fs, &root)
+	fs.StringVar(&out, "out", "", "Output path (default: docs/graph/graph.html).")
+	if err := fs.Parse(args); err != nil {
+		return failOnFlagParse(err)
+	}
+	r, err := resolveGraphRoot(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	g, err := graph.Build(r)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	path, err := graph.ExportHTML(r, g, out)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	render.OK("Wrote " + workspace.Relative(r, path))
+	return 0
+}
+
+// loadGraph resolves the workspace and builds the graph in memory (a full rebuild
+// is milliseconds at this scale). Returns the graph, the resolved root, and a
+// nonzero exit code on failure.
+func loadGraph(root string) (*graph.Graph, string, int) {
+	r, err := resolveGraphRoot(root)
+	if err != nil {
+		render.Err(err.Error())
+		return nil, "", 1
+	}
+	g, err := graph.Build(r)
+	if err != nil {
+		render.Err(err.Error())
+		return nil, "", 1
+	}
+	return g, r, 0
+}
+
+func renderFindings(findings []graph.Finding) {
+	for _, f := range findings {
+		label := f.Label
+		if label != "" {
+			label = " — " + label
+		}
+		loc := ""
+		if f.File != "" {
+			loc = "  (" + f.File + ")"
+		}
+		render.Info(fmt.Sprintf("[%s] %s%s%s", f.Corpus, f.Message, label, loc))
+	}
+}
+
+func godNodeSummary(hubs []graph.GodNode) string {
+	s := ""
+	for i, h := range hubs {
+		if i > 0 {
+			s += ", "
+		}
+		s += fmt.Sprintf("%s(%d)", h.Label, h.Degree)
+		if i >= 4 {
+			break
+		}
+	}
+	return s
+}
+
+func dirExists(path string) bool {
+	info, err := os.Stat(path)
+	return err == nil && info.IsDir()
+}
diff --git a/internal/cli/graph_cli_test.go b/internal/cli/graph_cli_test.go
new file mode 100644
index 0000000..204ef31
--- /dev/null
+++ b/internal/cli/graph_cli_test.go
@@ -0,0 +1,224 @@
+package cli
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	"github.com/protonspy/csdd/internal/manifest"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/templater"
+)
+
+// seedSpec drops a minimal spec into an initialized workspace so graph/analyze
+// have traceable content.
+func seedSpec(t *testing.T, dir string) {
+	t.Helper()
+	files := map[string]string{
+		"specs/demo/spec.json":       `{"feature_name":"demo","phase":"tasks","development_flow":"tdd"}`,
+		"specs/demo/requirements.md": "# Requirements\n## Requirements\n### Requirement 1: A\n**Acceptance Criteria**\n1. WHEN x THEN the system SHALL y.\n2. WHEN q THEN the system SHALL r.\n",
+		"specs/demo/tasks.md":        "# Tasks\n## Phase 1\n- [ ] 1. Do it _Boundary: Svc_\n  - _Requirements: 1.1_\n",
+		"specs/demo/design.md":       "# Design\n## Requirements Traceability\n| Requirement | Components | Interfaces | Flows |\n|---|---|---|---|\n| 1.1 | Svc | do() | f1 |\n## Components and Interfaces\n### Svc\n- **Requirements**: 1.1\n",
+	}
+	for rel, c := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(c), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func TestGraphBuildAndAnalyzeCLI(t *testing.T) {
+	dir := freshWorkspace(t)
+	seedSpec(t, dir)
+
+	// build writes docs/graph/graph.json and exits 0.
+	if code, out, errOut := run(t, "graph", "build", "--root", dir); code != 0 {
+		t.Fatalf("graph build failed: code=%d out=%s err=%s", code, out, errOut)
+	}
+	if _, err := os.Stat(filepath.Join(dir, "docs", "graph", "graph.json")); err != nil {
+		t.Fatalf("graph.json not written: %v", err)
+	}
+
+	// analyze reports the untested criterion 1.2.
+	code, out, _ := run(t, "graph", "analyze", "--root", dir)
+	if code != 0 {
+		t.Fatalf("analyze exit should be 0 without --strict; got %d", code)
+	}
+	if !strings.Contains(out, "criterion") {
+		t.Errorf("expected an untested-criterion finding; got: %s", out)
+	}
+
+	// --strict exits non-zero when findings exist (CI gate).
+	code, _, _ = run(t, "graph", "analyze", "--strict", "--root", dir)
+	if code == 0 {
+		t.Errorf("analyze --strict should exit non-zero with findings")
+	}
+
+	// query/path/explain work and emit JSON.
+	if code, out, _ := run(t, "graph", "query", "Svc", "--root", dir, "--json"); code != 0 || !strings.Contains(out, "design_demo_svc") {
+		t.Errorf("query --json failed: code=%d out=%s", code, out)
+	}
+	if code, out, _ := run(t, "graph", "explain", "Svc", "--root", dir, "--json"); code != 0 || !strings.Contains(out, "connections") {
+		t.Errorf("explain --json failed: code=%d out=%s", code, out)
+	}
+}
+
+func TestWikiLintCLI(t *testing.T) {
+	dir := freshWorkspace(t)
+	// The init scaffold is clean, so lint exits 0.
+	if code, out, _ := run(t, "wiki", "lint", "--root", dir); code != 0 {
+		t.Fatalf("clean wiki should lint 0; got %d out=%s", code, out)
+	}
+	// Drop an unprocessed raw source → lint exits 2.
+	if err := os.WriteFile(filepath.Join(dir, "docs", "raw", "note.md"), []byte("hi"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	code, out, _ := run(t, "wiki", "lint", "--root", dir)
+	if code != 2 {
+		t.Errorf("unprocessed source should make lint exit 2; got %d", code)
+	}
+	if !strings.Contains(out, "unprocessed") {
+		t.Errorf("expected unprocessed-source finding; got %s", out)
+	}
+}
+
+func TestSkillsForbidDirectGeneratedWrites(t *testing.T) {
+	// R16.4: skills must route every mutation through the CLI and never write
+	// docs/graph/ or .csdd/ directly. Assert the shipped graph/wiki skills carry
+	// that boundary explicitly.
+	skills, err := templater.SkillFiles(templater.FS)
+	if err != nil {
+		t.Fatal(err)
+	}
+	graphSkill := skills["graph/SKILL.md"]
+	if !strings.Contains(graphSkill, "single mutation path") && !strings.Contains(graphSkill, "Never hand-edit `docs/graph/`") {
+		t.Errorf("graph skill must state the CLI is the single mutation path / never hand-edit docs/graph")
+	}
+	wikiSkill := skills["wiki/SKILL.md"]
+	if !strings.Contains(wikiSkill, "docs/raw/") || !strings.Contains(strings.ToLower(wikiSkill), "never edit") {
+		t.Errorf("wiki skill must state docs/raw/ is never edited")
+	}
+}
+
+func TestWikiInitInstallsSchema(t *testing.T) {
+	// A bare directory (no full init): `wiki init` scaffolds the docs structure
+	// AND installs the wiki skill + knowledge-base steering rule (R9.2).
+	dir := t.TempDir()
+	if code, _, e := run(t, "wiki", "init", "--root", dir); code != 0 {
+		t.Fatalf("wiki init failed: %s", e)
+	}
+	for _, rel := range []string{
+		"docs/raw/README.md",
+		"docs/wiki/index.md",
+		"docs/wiki/log.md",
+		"docs/wiki/pages",
+		".claude/skills/wiki/SKILL.md",
+		".claude/rules/knowledge-base.md",
+	} {
+		if _, err := os.Stat(filepath.Join(dir, filepath.FromSlash(rel))); err != nil {
+			t.Errorf("wiki init did not create %s: %v", rel, err)
+		}
+	}
+	// Idempotent: a second run creates nothing new and never touches docs/raw/.
+	if code, _, _ := run(t, "wiki", "init", "--root", dir); code != 0 {
+		t.Errorf("second wiki init should succeed idempotently")
+	}
+}
+
+func TestRequireWorkspaceMarker(t *testing.T) {
+	// A dir with .claude/ but no .csdd/ → legacy message, exit 1 (R15.3).
+	legacy := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(legacy, ".claude"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	code, _, errOut := run(t, "graph", "build", "--root", legacy)
+	if code == 0 {
+		t.Errorf("graph on a legacy workspace should fail")
+	}
+	if !strings.Contains(errOut, "legacy") || !strings.Contains(errOut, "init") {
+		t.Errorf("expected legacy-upgrade guidance; got %s", errOut)
+	}
+
+	// A dir with neither → generic not-a-workspace error (R15.2).
+	bare := t.TempDir()
+	code, _, errOut = run(t, "wiki", "lint", "--root", bare)
+	if code == 0 || !strings.Contains(errOut, "not a csdd workspace") {
+		t.Errorf("bare dir should fail with not-a-workspace; got code=%d err=%s", code, errOut)
+	}
+}
+
+func TestInitScaffoldsFullLayout(t *testing.T) {
+	dir := freshWorkspace(t)
+	// The .csdd/ marker and the docs/ knowledge base exist (R15.1, R7).
+	for _, rel := range []string{
+		".csdd",
+		"docs/plans",
+		"docs/raw/README.md",
+		"docs/wiki/index.md",
+		"docs/wiki/log.md",
+		"docs/wiki/pages",
+		"docs/graph/README.md",
+		"docs/stack.md",
+		".claude/skills/graph/SKILL.md",
+		".claude/skills/wiki/SKILL.md",
+		".claude/skills/stack/SKILL.md",
+		".claude/commands/csdd-graph-query.md",
+		".claude/commands/csdd-wiki-ingest.md",
+		".claude/commands/csdd-stack-propose.md",
+		".claude/rules/knowledge-base.md",
+	} {
+		if _, err := os.Stat(filepath.Join(dir, filepath.FromSlash(rel))); err != nil {
+			t.Errorf("init did not scaffold %s: %v", rel, err)
+		}
+	}
+	// docs/stack.md must NOT prefill any technology choice (R17.1).
+	stack, _ := os.ReadFile(filepath.Join(dir, "docs", "stack.md"))
+	if strings.Contains(string(stack), "| Language | Go |") {
+		t.Errorf("stack.md must not prefill a technology choice")
+	}
+	// CLAUDE.md carries the filled knowledge-base managed section (R16.3).
+	claudemd, _ := os.ReadFile(filepath.Join(dir, "CLAUDE.md"))
+	cm := string(claudemd)
+	if !strings.Contains(cm, knowledgeMarkerStart) || !strings.Contains(cm, "Consult the graph before searching") {
+		// The body uses "Consult the graph before searching." heading text.
+		if !strings.Contains(cm, "Consult the graph before searching") && !strings.Contains(cm, "consult the graph") {
+			t.Errorf("CLAUDE.md missing wired knowledge-base section")
+		}
+	}
+}
+
+func TestManifestMigrationFromLegacy(t *testing.T) {
+	dir := freshWorkspace(t)
+	// Remove the new-path manifest init wrote, leaving only a legacy one.
+	newPath := paths.StateManifest(dir)
+	_ = os.Remove(newPath)
+	m := manifest.New()
+	m.Files[".claude/rules/ears-format.md"] = manifest.Hash("OLD SHIPPED\n")
+	if err := m.Save(paths.Manifest(dir), "test", time.Now()); err != nil {
+		t.Fatal(err)
+	}
+	// Simulate the pristine-outdated on-disk file matching the legacy baseline.
+	rule := filepath.Join(dir, ".claude", "rules", "ears-format.md")
+	if err := os.WriteFile(rule, []byte("OLD SHIPPED\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	// update must read the legacy baseline (so this is an in-place update, not a
+	// conflict) and write the manifest forward to the new path (R14.1, R14.2).
+	code, out, _ := run(t, "update", "--root", dir)
+	if code != 0 {
+		t.Fatalf("update failed: %s", out)
+	}
+	if !strings.Contains(out, "1 updated") {
+		t.Errorf("legacy baseline should yield an in-place update, not a conflict:\n%s", out)
+	}
+	if _, err := os.Stat(newPath); err != nil {
+		t.Errorf("save should have migrated the manifest to %s", newPath)
+	}
+}
diff --git a/internal/cli/init.go b/internal/cli/init.go
index 0d6773a..ae281aa 100644
--- a/internal/cli/init.go
+++ b/internal/cli/init.go
@@ -157,6 +157,7 @@ var excludable = []struct{ key, desc string }{
 	{"commands", ".claude/commands/"},
 	{"hooks", ".claude/hooks/"},
 	{"specs", "specs/"},
+	{"knowledge", "docs/ knowledge base (plans/raw/wiki/graph) + docs/stack.md tech contract"},
 }
 
 // excludableKeys returns the valid --exclude component keys in canonical order.
@@ -238,6 +239,10 @@ func initWorkspace(root string, opts initOptions, templates embed.FS) (initCount
 		{"agents", paths.Agents(root)},
 		{"commands", paths.Commands(root)},
 		{"hooks", paths.Hooks(root)},
+		{"knowledge", paths.DocsPlans(root)},
+		{"knowledge", paths.DocsRaw(root)},
+		{"knowledge", filepath.Join(paths.DocsWiki(root), "pages")},
+		{"knowledge", paths.DocsGraph(root)},
 	}
 	for _, d := range dirs {
 		if opts.skip(d.comp) || pathExists(d.path) {
@@ -373,6 +378,47 @@ func initWorkspace(root string, opts initOptions, templates embed.FS) (initCount
 		}
 	}
 
+	// The .csdd/ operational-state directory is the workspace marker (R15.2), so
+	// it is always created — even when the knowledge scaffold is excluded.
+	if !pathExists(paths.State(root)) {
+		if err := mkdirAll(paths.State(root)); err != nil {
+			return c, err
+		}
+		c.dirs++
+	}
+
+	// Knowledge-base scaffold: the docs/ raw+wiki structure, the generated-index
+	// and state READMEs, and the (choice-free) tech contract. Idempotent — never
+	// overwrites, never touches docs/raw/ contents (R9.3, R9.4, R15.1).
+	if !opts.skip("knowledge") {
+		scaffolds := []func(fs.FS) (map[string]string, error){
+			templater.WikiScaffoldFiles,
+			templater.KnowledgeStructureFiles,
+		}
+		for _, fn := range scaffolds {
+			files, err := fn(templates)
+			if err != nil {
+				return c, err
+			}
+			for rel, content := range files {
+				created, err := workspace.SafeWrite(filepath.Join(root, filepath.FromSlash(rel)), content)
+				if err != nil {
+					return c, err
+				}
+				if created {
+					c.files++
+				}
+			}
+		}
+	}
+
+	// Wire the managed knowledge-base section into CLAUDE.md (R16.3, R17.4, R17.7).
+	if !opts.skip("claude-md") {
+		if _, err := ensureKnowledgeSection(root, templates); err != nil {
+			return c, err
+		}
+	}
+
 	// Record the manifest of csdd-managed artifacts so a later `csdd update` can
 	// tell pristine shipped files from ones the user has since edited.
 	if err := recordManifest(root, templates, time.Now(), nil); err != nil {
diff --git a/internal/cli/update.go b/internal/cli/update.go
index 60a01ca..4ffd9cb 100644
--- a/internal/cli/update.go
+++ b/internal/cli/update.go
@@ -90,6 +90,27 @@ func collectManagedFiles(root string, templates embed.FS) ([]managedFile, error)
 	return out, nil
 }
 
+// loadWorkspaceManifest reads the csdd-managed manifest, preferring the new
+// .csdd/manifest.json home and falling back to the legacy
+// .claude/.csdd-manifest.json when the new path is absent (R14.1). Workspaces
+// that only have the legacy file keep working unchanged (R14.2).
+func loadWorkspaceManifest(root string) (*manifest.Manifest, bool, error) {
+	m, exists, err := manifest.Load(paths.StateManifest(root))
+	if err != nil {
+		return nil, false, err
+	}
+	if exists {
+		return m, true, nil
+	}
+	return manifest.Load(paths.Manifest(root))
+}
+
+// saveWorkspaceManifest always writes to the new .csdd/manifest.json path, so the
+// next save transparently migrates a legacy workspace forward (R14.1).
+func saveWorkspaceManifest(root string, m *manifest.Manifest, now time.Time) error {
+	return m.Save(paths.StateManifest(root), version, now)
+}
+
 // recordManifest rewrites the workspace manifest to record the shipped-content
 // hash of every managed file for this csdd version. Both `init` and `update`
 // call it so the baseline always reflects what csdd last wrote — which is what
@@ -101,7 +122,7 @@ func recordManifest(root string, templates embed.FS, now time.Time, skipped map[
 	if err != nil {
 		return err
 	}
-	prior, _, _ := manifest.Load(paths.Manifest(root))
+	prior, _, _ := loadWorkspaceManifest(root)
 	m := manifest.New()
 	for _, f := range files {
 		if skipped[f.Rel] {
@@ -112,7 +133,7 @@ func recordManifest(root string, templates embed.FS, now time.Time, skipped map[
 		}
 		m.Files[f.Rel] = managedBaselineHash(f, f.Content)
 	}
-	return m.Save(paths.Manifest(root), version, now)
+	return saveWorkspaceManifest(root, m, now)
 }
 
 type updateOptions struct {
@@ -247,7 +268,7 @@ func updateWorkspace(opts updateOptions, templates embed.FS, now time.Time) (upd
 	if err != nil {
 		return res, err
 	}
-	base, existed, err := manifest.Load(paths.Manifest(opts.root))
+	base, existed, err := loadWorkspaceManifest(opts.root)
 	if err != nil {
 		return res, err
 	}
diff --git a/internal/cli/update_test.go b/internal/cli/update_test.go
index b9ce796..5eb8f70 100644
--- a/internal/cli/update_test.go
+++ b/internal/cli/update_test.go
@@ -89,12 +89,12 @@ func TestUpdatePristineOutdatedUpdatesInPlace(t *testing.T) {
 	if err := os.WriteFile(rule, []byte("OLD SHIPPED\n"), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	m, _, err := manifest.Load(paths.Manifest(dir))
+	m, _, err := manifest.Load(paths.StateManifest(dir))
 	if err != nil {
 		t.Fatal(err)
 	}
 	m.Files[relKey] = manifest.Hash("OLD SHIPPED\n")
-	if err := m.Save(paths.Manifest(dir), "test", time.Now()); err != nil {
+	if err := m.Save(paths.StateManifest(dir), "test", time.Now()); err != nil {
 		t.Fatal(err)
 	}
 
@@ -182,12 +182,12 @@ func TestUpdateCarriesManagedAgentModelEffortAcrossTemplateRefresh(t *testing.T)
 	if err := os.WriteFile(agent, []byte(oldWithOverrides), 0o644); err != nil {
 		t.Fatal(err)
 	}
-	m, _, err := manifest.Load(paths.Manifest(dir))
+	m, _, err := manifest.Load(paths.StateManifest(dir))
 	if err != nil {
 		t.Fatal(err)
 	}
 	m.Files[relKey] = manifest.Hash(oldShipped)
-	if err := m.Save(paths.Manifest(dir), "test", time.Now()); err != nil {
+	if err := m.Save(paths.StateManifest(dir), "test", time.Now()); err != nil {
 		t.Fatal(err)
 	}
 
@@ -399,7 +399,7 @@ func TestUpdateYesSkipsPrompt(t *testing.T) {
 
 func TestInitWritesManifest(t *testing.T) {
 	dir := freshWorkspace(t)
-	m, exists, err := manifest.Load(paths.Manifest(dir))
+	m, exists, err := manifest.Load(paths.StateManifest(dir))
 	if err != nil || !exists {
 		t.Fatalf("init should write a manifest: exists=%v err=%v", exists, err)
 	}
diff --git a/internal/cli/wiki.go b/internal/cli/wiki.go
new file mode 100644
index 0000000..aa4f935
--- /dev/null
+++ b/internal/cli/wiki.go
@@ -0,0 +1,173 @@
+package cli
+
+import (
+	"embed"
+	"flag"
+	"fmt"
+	"path/filepath"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/graph"
+	"github.com/protonspy/csdd/internal/paths"
+	"github.com/protonspy/csdd/internal/render"
+	"github.com/protonspy/csdd/internal/templater"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// runWiki dispatches `csdd wiki <action>`. The wiki is the LLM-authored knowledge
+// base under docs/: the CLI scaffolds (init) and lints (lint) deterministically;
+// content is authored by LLM sessions via the installed `wiki` skill.
+func runWiki(args []string, templates embed.FS) int {
+	action, rest, err := parseAction("wiki", args)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	if isHelpFlag(action) {
+		wikiHelp()
+		return 0
+	}
+	switch action {
+	case "init":
+		return wikiInit(rest, templates)
+	case "lint":
+		return wikiLint(rest)
+	default:
+		render.Err("unknown action for `wiki`: " + action)
+		wikiHelp()
+		return 1
+	}
+}
+
+func wikiHelp() {
+	fmt.Println(`csdd wiki — the LLM-authored knowledge base under docs/.
+
+  init   Scaffold docs/raw/ (dropzone) + docs/wiki/ (index, log, pages/).
+  lint   Report broken wikilinks, orphan pages, index/log desync, unprocessed sources.
+
+Flags: --root DIR, --force (init), --json (lint).`)
+}
+
+func wikiInit(args []string, templates embed.FS) int {
+	fs := flag.NewFlagSet("wiki init", flag.ContinueOnError)
+	var root string
+	var force bool
+	addRoot(fs, &root)
+	addForce(fs, &force)
+	if err := fs.Parse(args); err != nil {
+		return failOnFlagParse(err)
+	}
+	r, err := workspace.Resolve(root)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	created, err := scaffoldWiki(r, force, templates)
+	if err != nil {
+		render.Err(err.Error())
+		return 1
+	}
+	render.OK(fmt.Sprintf("Wiki scaffolded at %s (%d file(s) created).", workspace.Relative(r, paths.DocsWiki(r)), created))
+	render.Info("Drop sources into docs/raw/, then use the `wiki` skill's Ingest workflow.")
+	return 0
+}
+
+// scaffoldWiki lays down the docs/raw/ + docs/wiki/ structure idempotently. It
+// never overwrites an existing file without --force and never touches docs/raw/
+// contents (R9.3, R9.4). Returns the number of files created.
+func scaffoldWiki(root string, force bool, templates embed.FS) (int, error) {
+	// The pages/ content home is a directory the LLM fills.
+	if err := mkdirAll(filepath.Join(paths.DocsWiki(root), "pages")); err != nil {
+		return 0, err
+	}
+	if err := mkdirAll(paths.DocsRaw(root)); err != nil {
+		return 0, err
+	}
+	files, err := templater.WikiScaffoldFiles(templates)
+	if err != nil {
+		return 0, err
+	}
+	// Install the wiki schema doc — the `wiki` skill plus the knowledge-base
+	// steering rule — through the existing skill/rule mechanisms (R9.2).
+	if schema, err := wikiSchemaFiles(templates); err != nil {
+		return 0, err
+	} else {
+		for rel, content := range schema {
+			files[rel] = content
+		}
+	}
+	created := 0
+	for rel, content := range files {
+		dst := filepath.Join(root, filepath.FromSlash(rel))
+		if force {
+			if err := workspace.WriteFile(dst, content, true); err != nil {
+				return created, err
+			}
+			created++
+			continue
+		}
+		wrote, err := workspace.SafeWrite(dst, content)
+		if err != nil {
+			return created, err
+		}
+		if wrote {
+			created++
+		}
+	}
+	return created, nil
+}
+
+// wikiSchemaFiles returns the wiki skill (.claude/skills/wiki/*) and the
+// knowledge-base steering rule (.claude/rules/knowledge-base.md), keyed by
+// workspace-relative destination — the "schema doc" R9.2 installs.
+func wikiSchemaFiles(templates embed.FS) (map[string]string, error) {
+	out := map[string]string{}
+	skills, err := templater.SkillFiles(templates)
+	if err != nil {
+		return nil, err
+	}
+	for rel, content := range skills {
+		if strings.HasPrefix(rel, "wiki/") {
+			out[".claude/skills/"+rel] = content
+		}
+	}
+	rules, err := templater.RuleFiles(templates)
+	if err != nil {
+		return nil, err
+	}
+	if content, ok := rules["knowledge-base.md"]; ok {
+		out[".claude/rules/knowledge-base.md"] = content
+	}
+	return out, nil
+}
+
+func wikiLint(args []string) int {
+	fs := flag.NewFlagSet("wiki lint", flag.ContinueOnError)
+	var root string
+	var jsonOut bool
+	addRoot(fs, &root)
+	addJSON(fs, &jsonOut)
+	if err := fs.Parse(args); err != nil {
+		return failOnFlagParse(err)
+	}
+	g, r, code := loadGraph(root)
+	if code != 0 {
+		return code
+	}
+	report := graph.Analyze(g, r)
+	findings := graph.WikiFindings(report)
+	if jsonOut {
+		_ = emitJSON(map[string]any{"findings": findings})
+		if len(findings) > 0 {
+			return 2
+		}
+		return 0
+	}
+	if len(findings) == 0 {
+		render.OK("Wiki is healthy: no findings.")
+		return 0
+	}
+	renderFindings(findings)
+	render.Warn(fmt.Sprintf("%d wiki finding(s).", len(findings)))
+	return 2 // R10.6: exit non-zero on findings (CI-gateable)
+}
diff --git a/internal/graph/analyze.go b/internal/graph/analyze.go
new file mode 100644
index 0000000..219c951
--- /dev/null
+++ b/internal/graph/analyze.go
@@ -0,0 +1,546 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Finding is one mechanical contract violation surfaced by analyze. Corpus tags
+// which knowledge domain it belongs to (spec | wiki | tech), so `csdd wiki lint`
+// can render exactly the wiki subset (§5.10 — lint is analyze filtered).
+type Finding struct {
+	Kind    string `json:"kind"`
+	Corpus  string `json:"corpus"`
+	NodeID  string `json:"node_id,omitempty"`
+	Label   string `json:"label,omitempty"`
+	Message string `json:"message"`
+	File    string `json:"file,omitempty"`
+}
+
+// GodNode is a hub — a node whose degree stands out — surfaced so reviewers see
+// where the graph concentrates (§5.10).
+type GodNode struct {
+	ID     string `json:"id"`
+	Label  string `json:"label"`
+	Degree int    `json:"degree"`
+}
+
+// GapReport is the full analysis: every finding plus the god-node hubs.
+type GapReport struct {
+	Findings []Finding `json:"findings"`
+	GodNodes []GodNode `json:"god_nodes,omitempty"`
+}
+
+// Corpus tags.
+const (
+	corpusSpec = "spec"
+	corpusWiki = "wiki"
+	corpusTech = "tech"
+)
+
+// Finding kinds.
+const (
+	kindUntestedRequirement = "untested_requirement"
+	kindOrphanTask          = "orphan_task"
+	kindUnimplementedCompo  = "unimplemented_component"
+	kindPendingReference    = "pending_reference"
+	kindRangeShorthand      = "range_shorthand"
+	kindDependencyCycle     = "dependency_cycle"
+	kindBrokenWikilink      = "broken_wikilink"
+	kindOrphanPage          = "orphan_page"
+	kindIndexMissingPage    = "index_missing_page"
+	kindIndexDanglingEntry  = "index_dangling_entry"
+	kindLogFormat           = "log_format"
+	kindUnprocessedSource   = "unprocessed_source"
+	kindUndeclaredTech      = "undeclared_tech"
+	kindPhantomTech         = "phantom_tech"
+	kindUnrefinedTech       = "unrefined_tech"
+	kindNoTechContract      = "no_tech_contract"
+)
+
+// Analyze runs every mechanical check over an assembled graph. root is used only
+// for the wiki index/log file checks (which read content the graph does not
+// carry); everything else is derived from the graph itself.
+func Analyze(g *Graph, root string) GapReport {
+	var r GapReport
+	r.Findings = append(r.Findings, specFindings(g)...)
+	r.Findings = append(r.Findings, wikiFindings(g, root)...)
+	r.Findings = append(r.Findings, techFindings(g, root)...)
+	r.GodNodes = godNodes(g)
+	sortFindings(r.Findings)
+	return r
+}
+
+// WikiFindings returns the wiki-corpus subset of a report — exactly what
+// `csdd wiki lint` renders (§5.10: lint is analyze filtered to the wiki corpus).
+func WikiFindings(r GapReport) []Finding {
+	var out []Finding
+	for _, f := range r.Findings {
+		if f.Corpus == corpusWiki {
+			out = append(out, f)
+		}
+	}
+	return out
+}
+
+// edgeSets precomputes inbound/outbound edge presence keyed by relation.
+type edgeSets struct {
+	outByRel map[string]map[string]bool // relation → source → true
+	inByRel  map[string]map[string]bool // relation → target → true
+}
+
+func buildEdgeSets(g *Graph) edgeSets {
+	es := edgeSets{outByRel: map[string]map[string]bool{}, inByRel: map[string]map[string]bool{}}
+	for _, e := range g.Links {
+		if es.outByRel[e.Relation] == nil {
+			es.outByRel[e.Relation] = map[string]bool{}
+		}
+		if es.inByRel[e.Relation] == nil {
+			es.inByRel[e.Relation] = map[string]bool{}
+		}
+		es.outByRel[e.Relation][e.Source] = true
+		es.inByRel[e.Relation][e.Target] = true
+	}
+	return es
+}
+
+func (es edgeSets) hasOut(rel, id string) bool {
+	m := es.outByRel[rel]
+	return m != nil && m[id]
+}
+func (es edgeSets) hasIn(rel, id string) bool {
+	m := es.inByRel[rel]
+	return m != nil && m[id]
+}
+
+var reRange = regexp.MustCompile(`\d+\.\d+\s*[-–—]\s*\d+`)
+
+func specFindings(g *Graph) []Finding {
+	es := buildEdgeSets(g)
+	var out []Finding
+	for _, n := range g.Nodes {
+		switch n.FileType {
+		case TypeCriterion:
+			// R3.1 untested requirement: a criterion no task realizes.
+			if !es.hasIn(RelRealizes, n.ID) {
+				out = append(out, Finding{
+					Kind: kindUntestedRequirement, Corpus: corpusSpec, NodeID: n.ID, Label: n.Label,
+					Message: "acceptance criterion has no task realizing it", File: n.SourceFile,
+				})
+			}
+		case TypeTask:
+			// R3.2 orphan task: a task with no _Requirements annotation.
+			if !es.hasOut(RelRealizes, n.ID) {
+				out = append(out, Finding{
+					Kind: kindOrphanTask, Corpus: corpusSpec, NodeID: n.ID, Label: n.Label,
+					Message: "task has no _Requirements annotation (realizes no criterion)", File: n.SourceFile,
+				})
+			}
+		case TypeDesign:
+			// R3.3 unimplemented component: a design component no task targets.
+			if !es.hasIn(RelInBoundary, n.ID) {
+				out = append(out, Finding{
+					Kind: kindUnimplementedCompo, Corpus: corpusSpec, NodeID: n.ID, Label: n.Label,
+					Message: "design component has no task in its boundary (_Boundary)", File: n.SourceFile,
+				})
+			}
+		}
+	}
+	// R3.4 pending references (incl. range shorthand as a distinct kind).
+	for _, p := range g.Pending {
+		if p.Relation == RelLinksTo {
+			continue // handled in wikiFindings
+		}
+		if !reportedRefRelations[p.Relation] {
+			continue
+		}
+		kind := kindPendingReference
+		msg := "annotation references a nonexistent ID: " + refDisplay(p)
+		if reRange.MatchString(p.Ref) {
+			kind = kindRangeShorthand
+			msg = "range shorthand is not supported (list IDs explicitly): " + p.Ref
+		}
+		out = append(out, Finding{
+			Kind: kind, Corpus: corpusSpec, NodeID: p.FromID, Label: p.FromLabel,
+			Message: msg, File: p.SourceFile,
+		})
+	}
+	// R3.5 depends_on cycles.
+	for _, cyc := range dependencyCycles(g) {
+		out = append(out, Finding{
+			Kind: kindDependencyCycle, Corpus: corpusSpec,
+			Message: "task dependency cycle: " + strings.Join(cyc, " → "),
+		})
+	}
+	return out
+}
+
+func refDisplay(p PendingRef) string {
+	if p.Ref != "" {
+		return p.Ref + " (→ " + p.TargetID + ")"
+	}
+	return p.TargetID
+}
+
+func wikiFindings(g *Graph, root string) []Finding {
+	es := buildEdgeSets(g)
+	var out []Finding
+
+	// R10.1 broken wikilinks (from assembly's dangling links_to).
+	for _, p := range g.Pending {
+		if p.Relation != RelLinksTo {
+			continue
+		}
+		out = append(out, Finding{
+			Kind: kindBrokenWikilink, Corpus: corpusWiki, NodeID: p.FromID, Label: p.FromLabel,
+			Message: "broken [[wikilink]] to \"" + p.Ref + "\" (no such page)", File: p.SourceFile,
+		})
+	}
+
+	indexed := readIndexEntries(root)
+	// R10.2 orphan pages; R10.3a pages missing from index.md.
+	for _, n := range g.Nodes {
+		if !isWikiContentPage(n) {
+			continue
+		}
+		inIndex := indexed.hasPage(n.ID)
+		hasInbound := es.hasIn(RelLinksTo, n.ID)
+		if !inIndex && !hasInbound {
+			out = append(out, Finding{
+				Kind: kindOrphanPage, Corpus: corpusWiki, NodeID: n.ID, Label: n.Label,
+				Message: "orphan page: no inbound [[wikilink]] and not listed in index.md", File: n.SourceFile,
+			})
+		}
+		if indexed.present && !inIndex {
+			out = append(out, Finding{
+				Kind: kindIndexMissingPage, Corpus: corpusWiki, NodeID: n.ID, Label: n.Label,
+				Message: "page not listed in index.md", File: n.SourceFile,
+			})
+		}
+	}
+	// R10.3b index entries pointing at missing files.
+	pageFiles := map[string]bool{}
+	for _, n := range g.Nodes {
+		if isWikiContentPage(n) {
+			pageFiles[n.SourceFile] = true
+		}
+	}
+	for _, entry := range indexed.entryPaths {
+		if !pageFiles[entry] && !pathExists(root, entry) {
+			out = append(out, Finding{
+				Kind: kindIndexDanglingEntry, Corpus: corpusWiki,
+				Message: "index.md entry points at a missing file: " + entry,
+				File:    "docs/wiki/index.md",
+			})
+		}
+	}
+	// R10.4 log.md format.
+	out = append(out, logFormatFindings(root)...)
+	// R10.5 unprocessed raw sources.
+	for _, n := range g.Nodes {
+		if n.FileType != TypeRawSource {
+			continue
+		}
+		if !es.hasIn(RelDerivedFrom, n.ID) {
+			out = append(out, Finding{
+				Kind: kindUnprocessedSource, Corpus: corpusWiki, NodeID: n.ID, Label: n.Label,
+				Message: "unprocessed raw source: dropped in docs/raw/ but no wiki page derives from it", File: n.SourceFile,
+			})
+		}
+	}
+	return out
+}
+
+func isWikiContentPage(n Node) bool {
+	return n.FileType == TypeWikiPage && strings.HasPrefix(n.SourceFile, "docs/wiki/pages/")
+}
+
+func techFindings(g *Graph, root string) []Finding {
+	es := buildEdgeSets(g)
+	var out []Finding
+	// R17.5 no contract → a lint finding, not an error.
+	if !pathExists(root, "docs/stack.md") {
+		out = append(out, Finding{
+			Kind: kindNoTechContract, Corpus: corpusTech,
+			Message: "no tech contract (docs/stack.md); stack decisions are undocumented",
+		})
+	}
+	// A dependency is "undeclared" only when a manifest declares it (R17.3) — a
+	// design-level External dependency is an intent, not a manifest fact.
+	usedByManifest := map[string]bool{}
+	nodeType := map[string]string{}
+	for _, n := range g.Nodes {
+		nodeType[n.ID] = n.FileType
+	}
+	for _, e := range g.Links {
+		if e.Relation == RelUsesTech && nodeType[e.Source] == TypeCodeRef {
+			usedByManifest[e.Target] = true
+		}
+	}
+	for _, n := range g.Nodes {
+		if n.FileType != TypeTech {
+			continue
+		}
+		declared := asBool(n.Attrs["from_contract"])
+		used := es.hasIn(RelUsesTech, n.ID)
+		switch {
+		case usedByManifest[n.ID] && !declared:
+			out = append(out, Finding{
+				Kind: kindUndeclaredTech, Corpus: corpusTech, NodeID: n.ID, Label: n.Label,
+				Message: "undeclared tech decision: \"" + n.Label + "\" is used but absent from the contract", File: n.SourceFile,
+			})
+		case declared && !used:
+			out = append(out, Finding{
+				Kind: kindPhantomTech, Corpus: corpusTech, NodeID: n.ID, Label: n.Label,
+				Message: "phantom tech: \"" + n.Label + "\" is in the contract but no usage was detected", File: n.SourceFile,
+			})
+		}
+		if declared {
+			if asString(n.Attrs["version"]) == "" || asString(n.Attrs["refs"]) == "" {
+				out = append(out, Finding{
+					Kind: kindUnrefinedTech, Corpus: corpusTech, NodeID: n.ID, Label: n.Label,
+					Message: "unrefined tech: \"" + n.Label + "\" is missing Version or Refs", File: n.SourceFile,
+				})
+			}
+		}
+	}
+	return out
+}
+
+func asBool(v any) bool {
+	b, _ := v.(bool)
+	return b
+}
+func asString(v any) string {
+	s, _ := v.(string)
+	return s
+}
+
+// godNodes returns the highest-degree hubs (top few, degree ≥ 4), so the report
+// highlights concentration without listing every leaf.
+func godNodes(g *Graph) []GodNode {
+	deg := map[string]int{}
+	label := map[string]string{}
+	for _, n := range g.Nodes {
+		label[n.ID] = n.Label
+	}
+	for _, e := range g.Links {
+		deg[e.Source]++
+		deg[e.Target]++
+	}
+	var hubs []GodNode
+	for id, d := range deg {
+		if d >= 4 {
+			hubs = append(hubs, GodNode{ID: id, Label: label[id], Degree: d})
+		}
+	}
+	sort.Slice(hubs, func(i, j int) bool {
+		if hubs[i].Degree != hubs[j].Degree {
+			return hubs[i].Degree > hubs[j].Degree
+		}
+		return hubs[i].ID < hubs[j].ID
+	})
+	if len(hubs) > 10 {
+		hubs = hubs[:10]
+	}
+	return hubs
+}
+
+func sortFindings(f []Finding) {
+	sort.SliceStable(f, func(i, j int) bool {
+		if f[i].Corpus != f[j].Corpus {
+			return f[i].Corpus < f[j].Corpus
+		}
+		if f[i].Kind != f[j].Kind {
+			return f[i].Kind < f[j].Kind
+		}
+		if f[i].NodeID != f[j].NodeID {
+			return f[i].NodeID < f[j].NodeID
+		}
+		return f[i].Message < f[j].Message
+	})
+}
+
+// --- wiki index.md / log.md helpers -----------------------------------------
+
+type indexEntries struct {
+	present    bool
+	pageIDs    map[string]bool
+	entryPaths []string
+}
+
+func (ie indexEntries) hasPage(id string) bool { return ie.pageIDs[id] }
+
+var reIndexLink = regexp.MustCompile(`\]\(([^)]+\.md)\)`)
+
+// readIndexEntries parses docs/wiki/index.md for the pages it catalogs, via both
+// markdown links to pages/*.md and [[wikilinks]].
+func readIndexEntries(root string) indexEntries {
+	ie := indexEntries{pageIDs: map[string]bool{}}
+	data, err := os.ReadFile(filepath.Join(root, "docs", "wiki", "index.md"))
+	if err != nil {
+		return ie
+	}
+	ie.present = true
+	text := stripHTMLComments(string(data))
+	for _, m := range reIndexLink.FindAllStringSubmatch(text, -1) {
+		target := strings.TrimSpace(m[1])
+		if strings.ContainsAny(target, "<>") {
+			continue // a placeholder in the entry-format doc, not a real entry
+		}
+		ie.pageIDs[wikiTargetID(target)] = true
+		ie.entryPaths = append(ie.entryPaths, normalizeIndexPath(target))
+	}
+	for _, m := range reWikiLink.FindAllStringSubmatch(text, -1) {
+		if strings.ContainsAny(m[1], "<>") {
+			continue
+		}
+		ie.pageIDs[wikiTargetID(m[1])] = true
+	}
+	return ie
+}
+
+// normalizeIndexPath resolves an index entry link to a workspace-relative path
+// so its existence can be checked. Relative links are taken from docs/wiki/.
+func normalizeIndexPath(target string) string {
+	if strings.HasPrefix(target, "docs/") {
+		return target
+	}
+	return "docs/wiki/" + strings.TrimPrefix(target, "./")
+}
+
+var reLogEntry = regexp.MustCompile(`^## \[(\d{4}-\d{2}-\d{2})\]\s+(\w+)\s+\|\s+(.+)$`)
+var logOps = map[string]bool{"ingest": true, "query": true, "lint": true, "refactor": true}
+
+// logFormatFindings flags docs/wiki/log.md headings that start with "## [" but do
+// not match the documented `## [YYYY-MM-DD] <op> | <title>` format (R10.4).
+func logFormatFindings(root string) []Finding {
+	data, err := os.ReadFile(filepath.Join(root, "docs", "wiki", "log.md"))
+	if err != nil {
+		return nil
+	}
+	var out []Finding
+	stripped := stripHTMLComments(strings.ReplaceAll(string(data), "\r\n", "\n"))
+	for i, raw := range strings.Split(stripped, "\n") {
+		line := strings.TrimRight(raw, " \t")
+		if !strings.HasPrefix(line, "## [") {
+			continue
+		}
+		m := reLogEntry.FindStringSubmatch(line)
+		if m == nil || !logOps[strings.ToLower(m[2])] {
+			out = append(out, Finding{
+				Kind: kindLogFormat, Corpus: corpusWiki,
+				Message: "log.md entry does not match `## [YYYY-MM-DD] <op> | <title>` (op ∈ ingest|query|lint|refactor): " + strings.TrimSpace(line),
+				File:    "docs/wiki/log.md", NodeID: "", Label: "L" + itoa(i+1),
+			})
+		}
+	}
+	return out
+}
+
+// --- depends_on cycle detection (Tarjan SCC) --------------------------------
+
+// dependencyCycles returns the node-label cycles among depends_on edges, one per
+// strongly-connected component of size > 1 (or a self-loop), deterministically
+// ordered.
+func dependencyCycles(g *Graph) [][]string {
+	adj := map[string][]string{}
+	label := map[string]string{}
+	selfLoop := map[string]bool{}
+	nodes := map[string]bool{}
+	for _, n := range g.Nodes {
+		label[n.ID] = n.Label
+	}
+	for _, e := range g.Links {
+		if e.Relation != RelDependsOn {
+			continue
+		}
+		if e.Source == e.Target {
+			selfLoop[e.Source] = true
+		}
+		adj[e.Source] = append(adj[e.Source], e.Target)
+		nodes[e.Source] = true
+		nodes[e.Target] = true
+	}
+	for k := range adj {
+		sort.Strings(adj[k])
+	}
+	sccs := tarjanSCC(nodes, adj)
+	var cycles [][]string
+	for _, comp := range sccs {
+		if len(comp) > 1 || (len(comp) == 1 && selfLoop[comp[0]]) {
+			labels := make([]string, len(comp))
+			for i, id := range comp {
+				if l := label[id]; l != "" {
+					labels[i] = l
+				} else {
+					labels[i] = id
+				}
+			}
+			cycles = append(cycles, labels)
+		}
+	}
+	sort.Slice(cycles, func(i, j int) bool {
+		return strings.Join(cycles[i], "\x00") < strings.Join(cycles[j], "\x00")
+	})
+	return cycles
+}
+
+func tarjanSCC(nodes map[string]bool, adj map[string][]string) [][]string {
+	ids := make([]string, 0, len(nodes))
+	for n := range nodes {
+		ids = append(ids, n)
+	}
+	sort.Strings(ids)
+
+	index := 0
+	indices := map[string]int{}
+	low := map[string]int{}
+	onStack := map[string]bool{}
+	var stack []string
+	var out [][]string
+
+	var strongconnect func(v string)
+	strongconnect = func(v string) {
+		indices[v] = index
+		low[v] = index
+		index++
+		stack = append(stack, v)
+		onStack[v] = true
+		for _, w := range adj[v] {
+			if _, seen := indices[w]; !seen {
+				strongconnect(w)
+				if low[w] < low[v] {
+					low[v] = low[w]
+				}
+			} else if onStack[w] {
+				if indices[w] < low[v] {
+					low[v] = indices[w]
+				}
+			}
+		}
+		if low[v] == indices[v] {
+			var comp []string
+			for {
+				w := stack[len(stack)-1]
+				stack = stack[:len(stack)-1]
+				onStack[w] = false
+				comp = append(comp, w)
+				if w == v {
+					break
+				}
+			}
+			sort.Strings(comp)
+			out = append(out, comp)
+		}
+	}
+	for _, v := range ids {
+		if _, seen := indices[v]; !seen {
+			strongconnect(v)
+		}
+	}
+	return out
+}
diff --git a/internal/graph/build.go b/internal/graph/build.go
new file mode 100644
index 0000000..35a9362
--- /dev/null
+++ b/internal/graph/build.go
@@ -0,0 +1,366 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Build walks the workspace at root through the default extractors and assembles
+// the result into a deterministic knowledge graph. It is a full rebuild — at
+// M1–M3 corpus size this is milliseconds and trivially deterministic (§5.9).
+func Build(root string) (*Graph, error) {
+	return BuildWith(root, defaultExtractors())
+}
+
+// BuildWith is Build with an explicit extractor set, so tests can drive a subset.
+func BuildWith(root string, extractors []Extractor) (*Graph, error) {
+	sources, err := collectSources(root, extractors)
+	if err != nil {
+		return nil, err
+	}
+	var nodes []Node
+	var edges []Edge
+	for _, src := range sources {
+		frags, err := dispatch(extractors, src)
+		if err != nil {
+			return nil, err
+		}
+		for _, f := range frags {
+			nodes = append(nodes, f.Nodes...)
+			edges = append(edges, f.Edges...)
+		}
+	}
+	return assemble(root, nodes, edges), nil
+}
+
+// dedupNodes merges nodes by ID. Identity fields take the last writer; Attrs are
+// unioned (existing keys preserved, incoming keys overlaid), so a technology that
+// is both declared in the contract and used by a manifest keeps both markers
+// regardless of which file was walked first (§5.6 tech matching).
+func dedupNodes(in []Node) []Node {
+	idx := map[string]int{}
+	var out []Node
+	for _, n := range in {
+		if i, ok := idx[n.ID]; ok {
+			out[i] = mergeNode(out[i], n)
+			continue
+		}
+		idx[n.ID] = len(out)
+		out = append(out, n)
+	}
+	return out
+}
+
+func mergeNode(existing, incoming Node) Node {
+	merged := incoming
+	if merged.Attrs == nil && existing.Attrs == nil {
+		return merged
+	}
+	attrs := map[string]any{}
+	for k, v := range existing.Attrs {
+		attrs[k] = v
+	}
+	for k, v := range incoming.Attrs {
+		attrs[k] = v
+	}
+	merged.Attrs = attrs
+	return merged
+}
+
+// dedupEdges removes duplicate (source, target, relation) triples, keeping the
+// first (which preserves the strongest/first-declared confidence and the ref).
+func dedupEdges(in []Edge) []Edge {
+	seen := map[[3]string]bool{}
+	var out []Edge
+	for _, e := range in {
+		key := [3]string{e.Source, e.Target, e.Relation}
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		out = append(out, e)
+	}
+	return out
+}
+
+var reSpecMember = regexp.MustCompile(`^specs/([^/]+)/`)
+
+// assembleSpecOwnership synthesizes a spec node for every spec folder that has
+// any node and adds `owns` edges from it to the requirement/design/task nodes it
+// contains. Centralizing spec membership here keeps extractors ignorant of
+// cross-file structure (the (spec,N,M) reconciliation of §5.9).
+func assembleSpecOwnership(g *Graph) {
+	// Discover spec folders from node source files and ensure a spec node exists.
+	present := map[string]bool{}
+	for _, n := range g.Nodes {
+		present[n.ID] = true
+	}
+	folderSeen := map[string]bool{}
+	for _, n := range g.Nodes {
+		m := reSpecMember.FindStringSubmatch(n.SourceFile)
+		if m == nil {
+			continue
+		}
+		spec := m[1]
+		if folderSeen[spec] {
+			continue
+		}
+		folderSeen[spec] = true
+		sid := specNodeID(spec)
+		if !present[sid] {
+			g.Nodes = append(g.Nodes, Node{
+				ID: sid, Label: spec, FileType: TypeSpec,
+				SourceFile: "specs/" + spec + "/", SourceLocation: "L1",
+			})
+			present[sid] = true
+		}
+	}
+	// owns edges spec → {requirement, design, task}.
+	for _, n := range g.Nodes {
+		switch n.FileType {
+		case TypeRequire, TypeDesign, TypeTask:
+			m := reSpecMember.FindStringSubmatch(n.SourceFile)
+			if m == nil {
+				continue
+			}
+			g.Links = append(g.Links, Edge{
+				Source: specNodeID(m[1]), Target: n.ID, Relation: RelOwns,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: "specs/" + m[1] + "/spec.json",
+			})
+		}
+	}
+	g.Links = dedupEdges(g.Links)
+}
+
+// resolveCitedPaths reclassifies references/reuses edges by whether the cited
+// path exists on disk, and — when M3 code nodes are present — retargets them from
+// the placeholder code_ref to the real code file node (§5.7 resolution pass).
+func resolveCitedPaths(g *Graph, root string) {
+	idx := g.nodeIndex()
+	codeFileByPath := map[string]string{}
+	for i := range g.Nodes {
+		n := &g.Nodes[i]
+		if n.FileType == TypeCode && n.Attrs["kind"] == "file" {
+			codeFileByPath[n.SourceFile] = n.ID
+		}
+	}
+	replaced := map[string]bool{}
+	for i := range g.Links {
+		e := &g.Links[i]
+		if e.Relation != RelReferences && e.Relation != RelReuses {
+			continue
+		}
+		tgt := idx[e.Target]
+		if tgt == nil || tgt.FileType != TypeCodeRef {
+			continue
+		}
+		cited := tgt.SourceFile
+		if codeID, ok := codeFileByPath[cited]; ok {
+			// Upgrade artifact→code traceability from placeholder to the real node.
+			e.Target = codeID
+			e.Relation = RelReuses
+			e.Confidence = Extracted
+			e.ConfidenceScore = 1.0
+			replaced[tgt.ID] = true
+			continue
+		}
+		// A citation to a generated/state path (docs/graph/*, .csdd/*) must classify
+		// the same whether or not a prior build has produced that file — otherwise
+		// the build's own output would make the next build's graph.json differ
+		// (non-deterministic). Treat those as planned references, never reuses.
+		if !isGeneratedPath(cited) && pathExists(root, cited) {
+			e.Relation = RelReuses
+			e.Confidence = Extracted
+			e.ConfidenceScore = 1.0
+		} else {
+			e.Relation = RelReferences
+			e.Confidence = Inferred
+			e.ConfidenceScore = 0.85
+		}
+	}
+	if len(replaced) > 0 {
+		g.Nodes = removeNodes(g.Nodes, replaced)
+	}
+}
+
+var reGoModule = regexp.MustCompile(`(?m)^module\s+(\S+)`)
+
+// resolveGoImports rewrites in-module import edges from the import-path
+// placeholder node to the real package node, using the module path from go.mod.
+// Cross-module and std imports are left as-is (out of scope for M3, §5.7).
+func resolveGoImports(g *Graph, root string) {
+	data, err := os.ReadFile(filepath.Join(root, "go.mod"))
+	if err != nil {
+		return
+	}
+	m := reGoModule.FindSubmatch(data)
+	if m == nil {
+		return
+	}
+	modulePath := string(m[1])
+	pkgExists := map[string]bool{}
+	for _, n := range g.Nodes {
+		if n.FileType == TypeCode && n.Attrs["kind"] == "package" {
+			pkgExists[n.ID] = true
+		}
+	}
+	idx := g.nodeIndex()
+	replaced := map[string]bool{}
+	for i := range g.Links {
+		e := &g.Links[i]
+		if e.Relation != RelImports {
+			continue
+		}
+		tgt := idx[e.Target]
+		if tgt == nil || tgt.Attrs["kind"] != "import" {
+			continue
+		}
+		ip, _ := tgt.Attrs["import_path"].(string)
+		if ip == "" || !strings.HasPrefix(ip, modulePath) {
+			continue
+		}
+		dir := strings.TrimPrefix(strings.TrimPrefix(ip, modulePath), "/")
+		pkgID := goPkgID(dir)
+		if pkgExists[pkgID] {
+			e.Target = pkgID
+			replaced[tgt.ID] = true
+		}
+	}
+	if len(replaced) > 0 {
+		g.Nodes = removeNodes(g.Nodes, replaced)
+		g.Links = dedupEdges(g.Links)
+	}
+}
+
+// reportedRefRelations are the spec-traceability relations whose dangling target
+// is a reported gap (a pending reference), not a silent drop.
+var reportedRefRelations = map[string]bool{
+	RelRealizes:   true,
+	RelDependsOn:  true,
+	RelInBoundary: true,
+	RelTracedTo:   true,
+	RelRefinedBy:  true,
+}
+
+// resolveReferences scans every edge for an endpoint that resolved to no node.
+// Spec-traceability danglers and broken [[wikilinks]] become PendingRef findings
+// (the gap is the product); other inferred danglers are dropped silently. The
+// returned edges are the resolvable graph; Pending carries the diagnostics.
+func resolveReferences(g *Graph) []PendingRef {
+	present := map[string]bool{}
+	labels := map[string]string{}
+	for _, n := range g.Nodes {
+		present[n.ID] = true
+		labels[n.ID] = n.Label
+	}
+	var kept []Edge
+	var pending []PendingRef
+	for _, e := range g.Links {
+		srcOK, tgtOK := present[e.Source], present[e.Target]
+		if srcOK && tgtOK {
+			kept = append(kept, e)
+			continue
+		}
+		switch {
+		case reportedRefRelations[e.Relation]:
+			// The reference is whichever endpoint failed to resolve; the endpoint
+			// that did resolve is the anchor that carried the annotation. For
+			// realizes/depends_on/in_boundary the target is the ref; for
+			// traced_to/refined_by the source (a criterion) is the ref.
+			anchor, missing := e.Source, e.Target
+			if !srcOK && tgtOK {
+				anchor, missing = e.Target, e.Source
+			}
+			if srcOK || tgtOK {
+				pending = append(pending, PendingRef{
+					FromID: anchor, FromLabel: labels[anchor], Relation: e.Relation,
+					TargetID: missing, Ref: e.Ref, SourceFile: e.SourceFile,
+				})
+			}
+		case e.Relation == RelLinksTo && srcOK:
+			pending = append(pending, PendingRef{
+				FromID: e.Source, FromLabel: labels[e.Source], Relation: e.Relation,
+				TargetID: e.Target, Ref: e.Ref, SourceFile: e.SourceFile,
+			})
+		}
+		// Non-reported danglers (component_dep, related_to, derived_from, …) are
+		// dropped: their absence is not a contract violation.
+	}
+	g.Links = kept
+	return pending
+}
+
+// removeNodes returns nodes with any ID in drop removed.
+func removeNodes(nodes []Node, drop map[string]bool) []Node {
+	out := nodes[:0]
+	for _, n := range nodes {
+		if drop[n.ID] {
+			continue
+		}
+		out = append(out, n)
+	}
+	return out
+}
+
+// sortGraph imposes a total, deterministic order on nodes and edges so an
+// unchanged corpus yields byte-identical JSON (§5.9, R7.2).
+func sortGraph(g *Graph) {
+	sort.SliceStable(g.Nodes, func(i, j int) bool {
+		return g.Nodes[i].ID < g.Nodes[j].ID
+	})
+	sort.SliceStable(g.Links, func(i, j int) bool {
+		a, b := g.Links[i], g.Links[j]
+		if a.Source != b.Source {
+			return a.Source < b.Source
+		}
+		if a.Relation != b.Relation {
+			return a.Relation < b.Relation
+		}
+		if a.Target != b.Target {
+			return a.Target < b.Target
+		}
+		return a.SourceFile < b.SourceFile
+	})
+	sort.SliceStable(g.Pending, func(i, j int) bool {
+		a, b := g.Pending[i], g.Pending[j]
+		if a.FromID != b.FromID {
+			return a.FromID < b.FromID
+		}
+		if a.Relation != b.Relation {
+			return a.Relation < b.Relation
+		}
+		return a.TargetID < b.TargetID
+	})
+}
+
+// setMeta stamps the node-link graph block with the canonical vocabulary. It
+// carries NO wall-clock time so the output stays byte-stable across rebuilds
+// (the build timestamp lives in log.md instead).
+func setMeta(g *Graph) {
+	g.Meta = map[string]any{
+		"schema_version":    1,
+		"generated_by":      "csdd graph build",
+		"node_types":        NodeTypes,
+		"edge_relations":    EdgeRelations,
+		"confidence_levels": []string{Extracted, Inferred, Ambiguous},
+		"hyperedges":        []any{},
+	}
+}
+
+// isGeneratedPath reports whether a cited path lives in a csdd-generated or
+// operational-state subtree, whose existence must not influence build output.
+func isGeneratedPath(rel string) bool {
+	return strings.HasPrefix(rel, "docs/graph/") || strings.HasPrefix(rel, ".csdd/")
+}
+
+// pathExists reports whether a workspace-relative path exists on disk.
+func pathExists(root, rel string) bool {
+	if rel == "" {
+		return false
+	}
+	_, err := os.Stat(filepath.Join(root, filepath.FromSlash(rel)))
+	return err == nil
+}
diff --git a/internal/graph/export.go b/internal/graph/export.go
new file mode 100644
index 0000000..8ed5a77
--- /dev/null
+++ b/internal/graph/export.go
@@ -0,0 +1,125 @@
+package graph
+
+import (
+	"bytes"
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"time"
+
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// Canonical on-disk locations for the generated knowledge index. docs/graph/ is
+// the only generated subtree inside docs/ (PLAN §2).
+const (
+	GraphDirRel  = "docs/graph"
+	GraphJSONRel = "docs/graph/graph.json"
+	GraphHTMLRel = "docs/graph/graph.html"
+	GraphLogRel  = "docs/graph/log.md"
+)
+
+// GraphJSONPath is the absolute path of graph.json under root.
+func GraphJSONPath(root string) string {
+	return filepath.Join(root, filepath.FromSlash(GraphJSONRel))
+}
+
+// Marshal renders the graph as deterministic, human-readable NetworkX node-link
+// JSON: one node and one edge object per line (clean git diffs, §5.9), attrs in
+// sorted order, and NO wall-clock timestamp (byte-stable across rebuilds, R7.2).
+func Marshal(g *Graph) ([]byte, error) {
+	var b bytes.Buffer
+	b.WriteString("{\n")
+	fmt.Fprintf(&b, "  \"directed\": %t,\n", g.Directed)
+	fmt.Fprintf(&b, "  \"multigraph\": %t,\n", g.Multigraph)
+
+	meta := g.Meta
+	if meta == nil {
+		meta = map[string]any{}
+	}
+	metaJSON, err := json.MarshalIndent(meta, "  ", "  ")
+	if err != nil {
+		return nil, err
+	}
+	fmt.Fprintf(&b, "  \"graph\": %s,\n", metaJSON)
+
+	if err := writeArray(&b, "nodes", len(g.Nodes), func(i int) ([]byte, error) {
+		return marshalNode(g.Nodes[i])
+	}); err != nil {
+		return nil, err
+	}
+	b.WriteString(",\n")
+	if err := writeArray(&b, "links", len(g.Links), func(i int) ([]byte, error) {
+		return marshalEdge(g.Links[i])
+	}); err != nil {
+		return nil, err
+	}
+	b.WriteString("\n}\n")
+	return b.Bytes(), nil
+}
+
+func writeArray(b *bytes.Buffer, key string, n int, item func(int) ([]byte, error)) error {
+	if n == 0 {
+		fmt.Fprintf(b, "  %q: []", key)
+		return nil
+	}
+	fmt.Fprintf(b, "  %q: [\n", key)
+	for i := 0; i < n; i++ {
+		raw, err := item(i)
+		if err != nil {
+			return err
+		}
+		b.WriteString("    ")
+		b.Write(raw)
+		if i < n-1 {
+			b.WriteByte(',')
+		}
+		b.WriteByte('\n')
+	}
+	b.WriteString("  ]")
+	return nil
+}
+
+// WriteBuild persists the graph to docs/graph/graph.json and appends one line to
+// docs/graph/log.md (R4.2). now is injected so the log entry is testable and the
+// JSON itself carries no time. Returns the JSON bytes written.
+func WriteBuild(root string, g *Graph, now time.Time) ([]byte, error) {
+	data, err := Marshal(g)
+	if err != nil {
+		return nil, err
+	}
+	if err := workspace.AtomicWrite(GraphJSONPath(root), data, 0o644); err != nil {
+		return nil, err
+	}
+	if err := appendBuildLog(root, g, now); err != nil {
+		return nil, err
+	}
+	return data, nil
+}
+
+// appendBuildLog appends a Karpathy-format heading to docs/graph/log.md, creating
+// the file with a header when it does not yet exist.
+func appendBuildLog(root string, g *Graph, now time.Time) error {
+	logPath := filepath.Join(root, filepath.FromSlash(GraphLogRel))
+	pending := len(g.Pending)
+	entry := fmt.Sprintf("## [%s] build | %d nodes / %d edges (%d pending)\n",
+		now.UTC().Format("2006-01-02"), len(g.Nodes), len(g.Links), pending)
+
+	existing, err := os.ReadFile(logPath)
+	if os.IsNotExist(err) {
+		header := "# csdd graph — build log\n\n" +
+			"Append-only, chronological. One line per build. Parseable with\n" +
+			"`grep \"^## \\[\" log.md | tail -5`.\n\n"
+		if err := os.MkdirAll(filepath.Dir(logPath), 0o755); err != nil {
+			return err
+		}
+		return os.WriteFile(logPath, []byte(header+entry), 0o644)
+	}
+	if err != nil {
+		return err
+	}
+	out := append(existing, '\n')
+	out = append(out, []byte(entry)...)
+	return os.WriteFile(logPath, out, 0o644)
+}
diff --git a/internal/graph/export_html.go b/internal/graph/export_html.go
new file mode 100644
index 0000000..8671313
--- /dev/null
+++ b/internal/graph/export_html.go
@@ -0,0 +1,155 @@
+package graph
+
+import (
+	"path/filepath"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// ExportHTML writes a self-contained interactive visualization of the graph to
+// out (default docs/graph/graph.html). The page embeds the graph data and a
+// dependency-free force-directed canvas renderer — no external asset is fetched,
+// so it opens offline from a file:// URL (R6.2). Returns the path written.
+func ExportHTML(root string, g *Graph, out string) (string, error) {
+	data, err := Marshal(g)
+	if err != nil {
+		return "", err
+	}
+	// Escape "</" so the JSON payload can never terminate the <script> element
+	// early (the classic inline-data XSS/breakage vector).
+	safe := strings.ReplaceAll(string(data), "</", "<\\/")
+	html := strings.Replace(htmlTemplate, "/*__GRAPH_DATA__*/", safe, 1)
+
+	dst := out
+	if dst == "" {
+		dst = filepath.Join(root, filepath.FromSlash(GraphHTMLRel))
+	} else if !filepath.IsAbs(dst) {
+		dst = filepath.Join(root, filepath.FromSlash(dst))
+	}
+	if err := workspace.AtomicWrite(dst, []byte(html), 0o644); err != nil {
+		return "", err
+	}
+	return dst, nil
+}
+
+// htmlTemplate is the single-file visualization shell. The "/*__GRAPH_DATA__*/"
+// marker is replaced with the node-link JSON at export time.
+const htmlTemplate = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>csdd knowledge graph</title>
+<style>
+  :root { color-scheme: light dark; }
+  html,body { margin:0; height:100%; font-family: ui-sans-serif, system-ui, sans-serif; }
+  #wrap { display:flex; height:100%; }
+  #c { flex:1; display:block; background:#fbfbfd; }
+  @media (prefers-color-scheme: dark) { #c { background:#0b0b0f; } }
+  #side { width:280px; overflow:auto; padding:12px 14px; border-left:1px solid #8883; font-size:13px; }
+  #side h1 { font-size:14px; margin:0 0 8px; }
+  .legend span { display:inline-block; width:10px; height:10px; border-radius:50%; margin-right:6px; vertical-align:middle; }
+  .row { margin:2px 0; }
+  #meta { opacity:.7; margin-top:12px; font-size:12px; }
+  #q { width:100%; box-sizing:border-box; margin-bottom:8px; padding:4px 6px; }
+</style>
+</head>
+<body>
+<div id="wrap">
+  <canvas id="c"></canvas>
+  <div id="side">
+    <h1>csdd knowledge graph</h1>
+    <input id="q" placeholder="filter nodes by label…">
+    <div id="legend" class="legend"></div>
+    <div id="sel"></div>
+    <div id="meta"></div>
+  </div>
+</div>
+<script>
+"use strict";
+const GRAPH = /*__GRAPH_DATA__*/;
+const palette = {
+  spec:"#6C8EBF", requirement:"#B85450", criterion:"#D79B00", design:"#9673A6",
+  interface:"#82B366", flow:"#3A9CA6", task:"#D6B656", steering:"#647687",
+  skill:"#4C8C5A", agent:"#B46EAB", mcp:"#8C6D46", code_ref:"#999999",
+  wiki_page:"#5A7DBE", raw_source:"#B0B0B0", tech:"#C97B2C", code:"#4E79A7"
+};
+function colorFor(t){ return palette[t] || "#888"; }
+const canvas = document.getElementById("c"), ctx = canvas.getContext("2d");
+let W=0,H=0;
+function resize(){ W=canvas.width=canvas.clientWidth*devicePixelRatio; H=canvas.height=canvas.clientHeight*devicePixelRatio; }
+window.addEventListener("resize", resize); resize();
+
+const nodes = GRAPH.nodes.map((n,i)=>({...n, x:Math.cos(i)*200+W/2/devicePixelRatio, y:Math.sin(i*1.7)*200+H/2/devicePixelRatio, vx:0, vy:0, deg:0}));
+const byId = {}; nodes.forEach(n=>byId[n.id]=n);
+const links = GRAPH.links.filter(l=>byId[l.source]&&byId[l.target]);
+links.forEach(l=>{ byId[l.source].deg++; byId[l.target].deg++; });
+
+// Simple force-directed layout.
+function step(){
+  for(let i=0;i<nodes.length;i++){
+    const a=nodes[i];
+    for(let j=i+1;j<nodes.length;j++){
+      const b=nodes[j];
+      let dx=a.x-b.x, dy=a.y-b.y, d2=dx*dx+dy*dy+0.01, d=Math.sqrt(d2);
+      const rep=1200/d2; const fx=dx/d*rep, fy=dy/d*rep;
+      a.vx+=fx; a.vy+=fy; b.vx-=fx; b.vy-=fy;
+    }
+  }
+  for(const l of links){
+    const a=byId[l.source], b=byId[l.target];
+    let dx=b.x-a.x, dy=b.y-a.y, d=Math.sqrt(dx*dx+dy*dy)+0.01;
+    const k=(d-90)*0.01; const fx=dx/d*k, fy=dy/d*k;
+    a.vx+=fx; a.vy+=fy; b.vx-=fx; b.vy-=fy;
+  }
+  const cx=W/2/devicePixelRatio, cy=H/2/devicePixelRatio;
+  for(const n of nodes){
+    n.vx+=(cx-n.x)*0.002; n.vy+=(cy-n.y)*0.002;
+    n.vx*=0.85; n.vy*=0.85; n.x+=n.vx; n.y+=n.vy;
+  }
+}
+let filter="";
+document.getElementById("q").addEventListener("input", e=>{ filter=e.target.value.toLowerCase(); });
+let selected=null;
+canvas.addEventListener("click", e=>{
+  const mx=e.offsetX, my=e.offsetY; let best=null,bd=1e9;
+  for(const n of nodes){ const d=(n.x-mx)**2+(n.y-my)**2; if(d<bd){bd=d;best=n;} }
+  selected = bd<400 ? best : null; renderSel();
+});
+function renderSel(){
+  const el=document.getElementById("sel");
+  if(!selected){ el.innerHTML=""; return; }
+  const outs=links.filter(l=>l.source===selected.id).map(l=>"→ "+l.relation+" "+(byId[l.target].label||l.target));
+  const ins=links.filter(l=>l.target===selected.id).map(l=>"← "+l.relation+" "+(byId[l.source].label||l.source));
+  el.innerHTML="<h1>"+esc(selected.label)+"</h1><div class=row><b>"+esc(selected.file_type)+"</b> · "+esc(selected.source_file||"")+"</div>"+
+    [...outs,...ins].map(s=>"<div class=row>"+esc(s)+"</div>").join("");
+}
+function esc(s){ return String(s).replace(/[&<>]/g,c=>({"&":"&amp;","<":"&lt;",">":"&gt;"}[c])); }
+function draw(){
+  ctx.setTransform(devicePixelRatio,0,0,devicePixelRatio,0,0);
+  ctx.clearRect(0,0,W,H);
+  ctx.globalAlpha=0.35; ctx.strokeStyle="#8888";
+  for(const l of links){ const a=byId[l.source],b=byId[l.target]; ctx.beginPath(); ctx.moveTo(a.x,a.y); ctx.lineTo(b.x,b.y); ctx.stroke(); }
+  ctx.globalAlpha=1;
+  for(const n of nodes){
+    const dim = filter && !(n.label||"").toLowerCase().includes(filter);
+    ctx.globalAlpha = dim?0.15:1;
+    const r=4+Math.min(8,n.deg);
+    ctx.beginPath(); ctx.arc(n.x,n.y,r,0,7); ctx.fillStyle=colorFor(n.file_type); ctx.fill();
+    if(n===selected){ ctx.lineWidth=2; ctx.strokeStyle="#111"; ctx.stroke(); }
+    if(n.deg>=4 || n===selected){ ctx.globalAlpha=dim?0.2:0.9; ctx.fillStyle="#444"; ctx.font="10px sans-serif"; ctx.fillText((n.label||"").slice(0,24), n.x+r+2, n.y+3); }
+  }
+  ctx.globalAlpha=1;
+}
+function loop(){ step(); draw(); requestAnimationFrame(loop); }
+loop();
+
+// Legend + meta.
+const types=[...new Set(nodes.map(n=>n.file_type))].sort();
+document.getElementById("legend").innerHTML = types.map(t=>"<div class=row><span style='background:"+colorFor(t)+"'></span>"+esc(t)+"</div>").join("");
+document.getElementById("meta").textContent = nodes.length+" nodes · "+links.length+" edges";
+</script>
+</body>
+</html>
+`
diff --git a/internal/graph/export_html_test.go b/internal/graph/export_html_test.go
new file mode 100644
index 0000000..b06cf66
--- /dev/null
+++ b/internal/graph/export_html_test.go
@@ -0,0 +1,42 @@
+package graph
+
+import (
+	"os"
+	"strings"
+	"testing"
+)
+
+func TestExportHTMLSelfContained(t *testing.T) {
+	g, dir := buildFixture(t)
+	path, err := ExportHTML(dir, g, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	html := string(data)
+
+	// Self-contained: no external asset is fetched (R6.2). No src=/href= to a
+	// remote host, no CDN link.
+	for _, bad := range []string{"src=\"http", "href=\"http", "src='http", "//cdn", "unpkg.com", "jsdelivr"} {
+		if strings.Contains(html, bad) {
+			t.Errorf("graph.html must be self-contained; found %q", bad)
+		}
+	}
+	// The graph payload is embedded and "</" is escaped so the JSON can never
+	// terminate the <script> element early (R6.2 / task 13.1).
+	if strings.Contains(html, "</script>") && !strings.Contains(html, "const GRAPH =") {
+		t.Errorf("expected embedded graph data")
+	}
+	if !strings.Contains(html, "const GRAPH =") {
+		t.Errorf("graph data not embedded")
+	}
+	// No raw "</" from the data survived escaping inside the data payload region.
+	dataStart := strings.Index(html, "const GRAPH =")
+	dataEnd := strings.Index(html[dataStart:], "\n") + dataStart
+	if strings.Contains(html[dataStart:dataEnd], "</") {
+		t.Errorf("unescaped </ in embedded data line")
+	}
+}
diff --git a/internal/graph/extract.go b/internal/graph/extract.go
new file mode 100644
index 0000000..529e0e0
--- /dev/null
+++ b/internal/graph/extract.go
@@ -0,0 +1,256 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/textutil"
+)
+
+// Source is one file of a corpus, already read and root-relative. Content is the
+// raw bytes; for opaque corpora (docs/raw/) Content is left empty because the
+// file is indexed by path only.
+type Source struct {
+	Path    string // workspace-root-relative, forward slashes
+	Content []byte
+}
+
+// Fragment is one extractor's partial contribution: nodes plus edges whose
+// endpoints may still be symbolic (e.g. an annotation "1.1") until Assemble
+// reconciles them against the assembled node set.
+type Fragment struct {
+	Nodes []Node
+	Edges []Edge
+}
+
+// Extractor is the single seam through which every corpus enters the graph.
+// Nothing downstream of extraction branches on which corpus a fragment came
+// from (design principle 6) — adding a new corpus is adding a new Extractor.
+type Extractor interface {
+	// Matches reports whether this extractor handles the given root-relative path.
+	Matches(path string) bool
+	// Extract parses one source into fragments. Deterministic; performs no I/O.
+	Extract(src Source) ([]Fragment, error)
+}
+
+// defaultExtractors returns the corpus extractors in dispatch order. Order
+// matters where paths overlap: docs/stack.md and the dependency manifests are
+// claimed by the stack extractor before the wiki extractor would treat stack.md
+// as a page.
+func defaultExtractors() []Extractor {
+	return []Extractor{
+		&specExtractor{},
+		&claudeExtractor{},
+		&stackExtractor{},
+		&wikiExtractor{},
+		&goExtractor{},
+	}
+}
+
+// walkSkipDirs are directory names never descended into during corpus discovery:
+// VCS internals, dependency dumps, csdd's own state dir, build staging, and the
+// vendored graphify study material.
+var walkSkipDirs = map[string]bool{
+	".git":         true,
+	"node_modules": true,
+	".csdd":        true,
+	"dist":         true,
+}
+
+// collectSources walks the workspace once and returns every file some extractor
+// claims, read and root-relative, in deterministic (lexical) order. Files under
+// docs/raw/ are returned with empty Content — they are indexed opaquely, so
+// their (possibly large, possibly binary) bytes are never read.
+func collectSources(root string, extractors []Extractor) ([]Source, error) {
+	var out []Source
+	err := filepath.WalkDir(root, func(p string, d os.DirEntry, err error) error {
+		if err != nil {
+			// A transient stat error on one entry must not abort the whole build.
+			return nil
+		}
+		if d.IsDir() {
+			name := d.Name()
+			if p != root && walkSkipDirs[name] {
+				return filepath.SkipDir
+			}
+			return nil
+		}
+		rel := filepath.ToSlash(mustRel(root, p))
+		if !anyMatch(extractors, rel) {
+			return nil
+		}
+		if isRawSourcePath(rel) {
+			// Opaque: path only, content never parsed.
+			out = append(out, Source{Path: rel})
+			return nil
+		}
+		content, rerr := os.ReadFile(p)
+		if rerr != nil {
+			return nil
+		}
+		out = append(out, Source{Path: rel, Content: content})
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
+	return out, nil
+}
+
+func mustRel(root, p string) string {
+	rel, err := filepath.Rel(root, p)
+	if err != nil {
+		return p
+	}
+	return rel
+}
+
+func anyMatch(extractors []Extractor, path string) bool {
+	for _, e := range extractors {
+		if e.Matches(path) {
+			return true
+		}
+	}
+	return false
+}
+
+// dispatch runs the first matching extractor for a source. Exactly one extractor
+// handles each file (Matches order is the tie-break), so a fragment's origin is
+// unambiguous.
+func dispatch(extractors []Extractor, src Source) ([]Fragment, error) {
+	for _, e := range extractors {
+		if e.Matches(src.Path) {
+			return e.Extract(src)
+		}
+	}
+	return nil, nil
+}
+
+// isRawSourcePath reports whether a path is an immutable raw source under
+// docs/raw/ (indexed opaquely as a raw_source node).
+func isRawSourcePath(path string) bool {
+	return strings.HasPrefix(path, "docs/raw/")
+}
+
+// --- shared parsing helpers -------------------------------------------------
+
+// normLines splits content into line-ending-normalized lines.
+func normLines(content []byte) []string {
+	return strings.Split(textutil.NormalizeNewlines(string(content)), "\n")
+}
+
+// rtrim strips trailing spaces and tabs (keeping leading indentation, which some
+// parsers use to detect block boundaries).
+func rtrim(s string) string { return strings.TrimRight(s, " \t") }
+
+// reHTMLComment matches an HTML/markdown comment, including multi-line ones.
+var reHTMLComment = regexp.MustCompile(`(?s)<!--.*?-->`)
+
+// stripHTMLComments blanks out `<!-- … -->` regions so example links and
+// placeholders in commented-out scaffold content are never parsed as real edges.
+// Newlines inside a comment are preserved so line-oriented parsing stays aligned.
+func stripHTMLComments(s string) string {
+	return reHTMLComment.ReplaceAllStringFunc(s, func(m string) string {
+		return strings.Repeat("\n", strings.Count(m, "\n"))
+	})
+}
+
+// loc formats a 0-based line index as the "L<n>" source_location convention.
+func loc(lineIndex int) string {
+	return "L" + itoa(lineIndex+1)
+}
+
+func itoa(n int) string {
+	if n == 0 {
+		return "0"
+	}
+	neg := n < 0
+	if neg {
+		n = -n
+	}
+	var b [20]byte
+	i := len(b)
+	for n > 0 {
+		i--
+		b[i] = byte('0' + n%10)
+		n /= 10
+	}
+	if neg {
+		i--
+		b[i] = '-'
+	}
+	return string(b[i:])
+}
+
+// specNameFromPath extracts <name> from "specs/<name>/...", or "" if the path is
+// not inside a spec folder.
+func specNameFromPath(path string) string {
+	const prefix = "specs/"
+	if !strings.HasPrefix(path, prefix) {
+		return ""
+	}
+	rest := path[len(prefix):]
+	if i := strings.IndexByte(rest, '/'); i >= 0 {
+		return rest[:i]
+	}
+	return ""
+}
+
+// reIDList matches a comma-separated annotation ID list, individual tokens split
+// by the caller. Kept liberal on the token content so malformed tokens (ranges)
+// survive to become pending references rather than being silently discarded.
+var reWhitespace = regexp.MustCompile(`\s+`)
+
+// splitList splits a comma-separated annotation value into trimmed, non-empty
+// tokens. Range shorthand ("3.1-3.5") is preserved verbatim as a single token so
+// Assemble surfaces it as an unresolved reference (§5.6) rather than expanding
+// it.
+func splitList(raw string) []string {
+	var out []string
+	for _, part := range strings.Split(raw, ",") {
+		t := strings.TrimSpace(part)
+		if t != "" {
+			out = append(out, t)
+		}
+	}
+	return out
+}
+
+// splitCells splits a markdown table row into trimmed cell values (leading and
+// trailing pipe removed).
+func splitCells(row string) []string {
+	row = strings.TrimSpace(row)
+	row = strings.TrimPrefix(row, "|")
+	row = strings.TrimSuffix(row, "|")
+	parts := strings.Split(row, "|")
+	for i := range parts {
+		parts[i] = strings.TrimSpace(parts[i])
+	}
+	return parts
+}
+
+// isTableSeparator reports whether a table row is the `|---|---|` divider.
+func isTableSeparator(cells []string) bool {
+	if len(cells) == 0 {
+		return false
+	}
+	for _, c := range cells {
+		c = strings.TrimSpace(c)
+		if c == "" {
+			continue
+		}
+		if strings.Trim(c, "-: ") != "" {
+			return false
+		}
+	}
+	return true
+}
+
+// collapseSpaces normalizes internal whitespace runs to single spaces.
+func collapseSpaces(s string) string {
+	return strings.TrimSpace(reWhitespace.ReplaceAllString(s, " "))
+}
diff --git a/internal/graph/extract_claude.go b/internal/graph/extract_claude.go
new file mode 100644
index 0000000..17ed3bb
--- /dev/null
+++ b/internal/graph/extract_claude.go
@@ -0,0 +1,167 @@
+package graph
+
+import (
+	"encoding/json"
+	"path"
+	"sort"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+)
+
+// claudeExtractor indexes the Claude Code workspace configuration: steering and
+// generation rules, skills, custom agents, MCP servers, and the CLAUDE.md entry
+// point. Frontmatter is parsed with internal/frontmatter so node attributes stay
+// consistent with the rest of csdd.
+type claudeExtractor struct{}
+
+func (claudeExtractor) Matches(p string) bool {
+	if p == "CLAUDE.md" || p == ".mcp.json" {
+		return true
+	}
+	if !strings.HasPrefix(p, ".claude/") {
+		return false
+	}
+	base := path.Base(p)
+	switch {
+	case strings.HasPrefix(p, ".claude/rules/") && strings.HasSuffix(p, ".md"):
+		return true
+	case strings.HasPrefix(p, ".claude/steering/") && strings.HasSuffix(p, ".md"):
+		return true
+	case strings.HasPrefix(p, ".claude/skills/") && base == "SKILL.md":
+		return true
+	case strings.HasPrefix(p, ".claude/agents/") && strings.HasSuffix(p, ".md"):
+		return true
+	}
+	return false
+}
+
+func (claudeExtractor) Extract(src Source) ([]Fragment, error) {
+	switch {
+	case src.Path == "CLAUDE.md":
+		return claudeEntry(src), nil
+	case src.Path == ".mcp.json":
+		return claudeMCP(src), nil
+	case strings.HasPrefix(src.Path, ".claude/skills/"):
+		return claudeSkill(src), nil
+	case strings.HasPrefix(src.Path, ".claude/agents/"):
+		return claudeAgent(src), nil
+	case strings.HasPrefix(src.Path, ".claude/rules/"), strings.HasPrefix(src.Path, ".claude/steering/"):
+		return claudeSteering(src), nil
+	}
+	return nil, nil
+}
+
+func claudeEntry(src Source) []Fragment {
+	return []Fragment{{Nodes: []Node{{
+		ID: "entry_claude_md", Label: "CLAUDE.md", FileType: TypeSteering,
+		SourceFile: src.Path, SourceLocation: "L1",
+		Attrs: map[string]any{"kind": "entry"},
+	}}}}
+}
+
+func claudeSteering(src Source) []Fragment {
+	fm := frontmatter.Parse(string(src.Content))
+	name := path.Base(src.Path)
+	kind := "steering"
+	if strings.HasPrefix(src.Path, ".claude/rules/") {
+		kind = "rule"
+	}
+	attrs := map[string]any{"kind": kind}
+	if incl := fm.AsString("inclusion", ""); incl != "" {
+		attrs["inclusion"] = incl
+	}
+	if desc := fm.AsString("description", ""); desc != "" {
+		attrs["description"] = desc
+	}
+	id := MakeID("steering", kind, strings.TrimSuffix(name, ".md"))
+	frag := Fragment{Nodes: []Node{{
+		ID: id, Label: name, FileType: TypeSteering,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}
+	// Cited repo paths in the body become code_ref references.
+	appendCited(&frag, src, id)
+	return []Fragment{frag}
+}
+
+func claudeSkill(src Source) []Fragment {
+	// .claude/skills/<name>/SKILL.md — the skill name is the directory.
+	rel := strings.TrimPrefix(src.Path, ".claude/skills/")
+	name := rel
+	if i := strings.IndexByte(rel, '/'); i >= 0 {
+		name = rel[:i]
+	}
+	fm := frontmatter.Parse(string(src.Content))
+	attrs := map[string]any{}
+	if desc := fm.AsString("description", ""); desc != "" {
+		attrs["description"] = desc
+	}
+	label := fm.AsString("name", name)
+	id := MakeID("skill", name)
+	frag := Fragment{Nodes: []Node{{
+		ID: id, Label: label, FileType: TypeSkill,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}
+	appendCited(&frag, src, id)
+	return []Fragment{frag}
+}
+
+func claudeAgent(src Source) []Fragment {
+	name := strings.TrimSuffix(path.Base(src.Path), ".md")
+	fm := frontmatter.Parse(string(src.Content))
+	attrs := map[string]any{}
+	if desc := fm.AsString("description", ""); desc != "" {
+		attrs["description"] = desc
+	}
+	if model := fm.AsString("model", ""); model != "" {
+		attrs["model"] = model
+	}
+	label := fm.AsString("name", name)
+	id := MakeID("agent", name)
+	frag := Fragment{Nodes: []Node{{
+		ID: id, Label: label, FileType: TypeAgent,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}
+	appendCited(&frag, src, id)
+	return []Fragment{frag}
+}
+
+func claudeMCP(src Source) []Fragment {
+	var frag Fragment
+	servers := parseMCPServers(src.Content)
+	for _, name := range servers {
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: MakeID("mcp", name), Label: name, FileType: TypeMCP,
+			SourceFile: src.Path, SourceLocation: "L1",
+		})
+	}
+	return []Fragment{frag}
+}
+
+// parseMCPServers returns the server names declared under "mcpServers" in a
+// .mcp.json file, sorted for deterministic output. A malformed file yields no
+// servers (the graph stays honest rather than guessing).
+func parseMCPServers(content []byte) []string {
+	var doc struct {
+		MCPServers map[string]json.RawMessage `json:"mcpServers"`
+	}
+	if err := json.Unmarshal(content, &doc); err != nil {
+		return nil
+	}
+	names := make([]string, 0, len(doc.MCPServers))
+	for name := range doc.MCPServers {
+		names = append(names, name)
+	}
+	sort.Strings(names)
+	return names
+}
+
+// appendCited scans the source body for cited repo paths and appends code_ref
+// references from fromID. Kept a helper because every .claude artifact does it.
+func appendCited(frag *Fragment, src Source, fromID string) {
+	for i, raw := range normLines(src.Content) {
+		for _, cited := range citedPathsInline(raw) {
+			emitCitedPath(src, i, cited, fromID, frag)
+		}
+	}
+}
diff --git a/internal/graph/extract_go.go b/internal/graph/extract_go.go
new file mode 100644
index 0000000..3e1ea65
--- /dev/null
+++ b/internal/graph/extract_go.go
@@ -0,0 +1,27 @@
+package graph
+
+import (
+	"path"
+	"strings"
+)
+
+// goExtractor (M3) indexes Go source into code nodes via stdlib go/parser
+// (syntax-only, cgo-free): one node per package, file, and top-level
+// declaration, with containment and import edges. It excludes vendor/, hidden
+// directories, and testdata/ fixtures by default, and tags _test.go files.
+type goExtractor struct{}
+
+func (goExtractor) Matches(p string) bool {
+	if !strings.HasSuffix(p, ".go") {
+		return false
+	}
+	for _, seg := range strings.Split(path.Dir(p), "/") {
+		if seg == "vendor" || seg == "testdata" {
+			return false
+		}
+		if len(seg) > 1 && strings.HasPrefix(seg, ".") {
+			return false // hidden directory
+		}
+	}
+	return true
+}
diff --git a/internal/graph/extract_go_impl.go b/internal/graph/extract_go_impl.go
new file mode 100644
index 0000000..f51ea0d
--- /dev/null
+++ b/internal/graph/extract_go_impl.go
@@ -0,0 +1,171 @@
+package graph
+
+import (
+	"go/ast"
+	"go/parser"
+	"go/token"
+	"path"
+	"strings"
+)
+
+// includeStdImports controls whether standard-library imports become nodes/edges.
+// Off by default (§5.7): std imports are noise for a project graph.
+const includeStdImports = false
+
+// Extract parses one Go file syntax-only (no go/types, no module resolution, so
+// no network and no toolchain dependency) into code nodes and containment/import
+// edges. The package node is re-emitted per file and deduped by ID in Assemble.
+func (goExtractor) Extract(src Source) ([]Fragment, error) {
+	fset := token.NewFileSet()
+	file, err := parser.ParseFile(fset, src.Path, src.Content, parser.SkipObjectResolution)
+	if err != nil {
+		// A file that does not parse is skipped rather than failing the whole build
+		// (honesty over recall — a syntactically broken file has no reliable structure).
+		return nil, nil
+	}
+	isTest := strings.HasSuffix(src.Path, "_test.go")
+	dir := path.Dir(src.Path)
+	if dir == "." {
+		dir = ""
+	}
+	pkgName := file.Name.Name
+	pkgNodeID := goPkgID(dir)
+	fileNodeID := MakeID("go", "file", src.Path)
+
+	var frag Fragment
+	frag.Nodes = append(frag.Nodes, Node{
+		ID: pkgNodeID, Label: pkgName, FileType: TypeCode,
+		SourceFile: dir, SourceLocation: "L1",
+		Attrs: map[string]any{"kind": "package", "package": pkgName},
+	})
+	fileAttrs := map[string]any{"kind": "file"}
+	if isTest {
+		fileAttrs["test"] = true
+	}
+	frag.Nodes = append(frag.Nodes, Node{
+		ID: fileNodeID, Label: path.Base(src.Path), FileType: TypeCode,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: fileAttrs,
+	})
+	frag.Edges = append(frag.Edges, Edge{
+		Source: pkgNodeID, Target: fileNodeID, Relation: RelContains,
+		Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+	})
+
+	for _, decl := range file.Decls {
+		for _, d := range goDecls(src.Path, decl, fset, isTest) {
+			frag.Nodes = append(frag.Nodes, d)
+			frag.Edges = append(frag.Edges, Edge{
+				Source: fileNodeID, Target: d.ID, Relation: RelContains,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+			})
+		}
+	}
+
+	for _, imp := range file.Imports {
+		importPath := strings.Trim(imp.Path.Value, `"`)
+		if importPath == "" {
+			continue
+		}
+		if isStdImport(importPath) && !includeStdImports {
+			continue
+		}
+		impID := MakeID("go", "import", importPath)
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: impID, Label: importPath, FileType: TypeCode,
+			SourceFile: importPath, SourceLocation: "L1",
+			Attrs: map[string]any{"kind": "import", "import_path": importPath},
+		})
+		frag.Edges = append(frag.Edges, Edge{
+			Source: pkgNodeID, Target: impID, Relation: RelImports,
+			Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+		})
+	}
+	return []Fragment{frag}, nil
+}
+
+// goPkgID keys a package node by its directory (relative to the workspace root).
+func goPkgID(dir string) string {
+	if dir == "" {
+		return MakeID("go", "pkg", "root")
+	}
+	return MakeID("go", "pkg", dir)
+}
+
+// goDecls turns one top-level declaration into code nodes (a func/method, a type,
+// or exported vars/consts).
+func goDecls(filePath string, decl ast.Decl, fset *token.FileSet, isTest bool) []Node {
+	loc := "L" + itoa(fset.Position(decl.Pos()).Line)
+	mkNode := func(key, label, kind string) Node {
+		attrs := map[string]any{"kind": kind}
+		if isTest {
+			attrs["test"] = true
+		}
+		return Node{
+			ID: MakeID("go", "decl", filePath, key), Label: label, FileType: TypeCode,
+			SourceFile: filePath, SourceLocation: loc, Attrs: attrs,
+		}
+	}
+	switch d := decl.(type) {
+	case *ast.FuncDecl:
+		name := d.Name.Name
+		if d.Recv != nil && len(d.Recv.List) > 0 {
+			recv := receiverName(d.Recv.List[0].Type)
+			key := recv + "." + name
+			return []Node{mkNode(key, "func "+key, "method")}
+		}
+		return []Node{mkNode(name, "func "+name, "func")}
+	case *ast.GenDecl:
+		var out []Node
+		switch d.Tok {
+		case token.TYPE:
+			for _, spec := range d.Specs {
+				if ts, ok := spec.(*ast.TypeSpec); ok {
+					out = append(out, mkNode(ts.Name.Name, "type "+ts.Name.Name, "type"))
+				}
+			}
+		case token.VAR, token.CONST:
+			kind := "var"
+			if d.Tok == token.CONST {
+				kind = "const"
+			}
+			for _, spec := range d.Specs {
+				vs, ok := spec.(*ast.ValueSpec)
+				if !ok {
+					continue
+				}
+				for _, n := range vs.Names {
+					if ast.IsExported(n.Name) {
+						out = append(out, mkNode(n.Name, kind+" "+n.Name, kind))
+					}
+				}
+			}
+		}
+		return out
+	}
+	return nil
+}
+
+// receiverName returns the (possibly pointer) receiver type name for a method.
+func receiverName(expr ast.Expr) string {
+	switch t := expr.(type) {
+	case *ast.StarExpr:
+		return receiverName(t.X)
+	case *ast.Ident:
+		return t.Name
+	case *ast.IndexExpr: // generic receiver T[P]
+		return receiverName(t.X)
+	case *ast.IndexListExpr:
+		return receiverName(t.X)
+	}
+	return "recv"
+}
+
+// isStdImport reports whether an import path is from the standard library (its
+// first path segment carries no dot, e.g. "fmt" or "encoding/json").
+func isStdImport(importPath string) bool {
+	first := importPath
+	if i := strings.IndexByte(importPath, '/'); i >= 0 {
+		first = importPath[:i]
+	}
+	return !strings.Contains(first, ".")
+}
diff --git a/internal/graph/extract_go_test.go b/internal/graph/extract_go_test.go
new file mode 100644
index 0000000..c904e0b
--- /dev/null
+++ b/internal/graph/extract_go_test.go
@@ -0,0 +1,110 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestGoExtractor(t *testing.T) {
+	dir := t.TempDir()
+	files := map[string]string{
+		"go.mod": "module example.com/proj\n\ngo 1.22\n",
+		"internal/store/store.go": `package store
+
+import "example.com/proj/internal/db"
+
+type Store struct{ db *db.DB }
+
+func New() *Store { return &Store{} }
+
+func (s *Store) Save(x int) error { return nil }
+
+const Version = "1"
+`,
+		"internal/db/db.go": `package db
+
+type DB struct{}
+
+func Open() *DB { return &DB{} }
+`,
+		"internal/store/store_test.go": `package store
+
+import "testing"
+
+func TestSave(t *testing.T) {}
+`,
+		"vendor/lib/lib.go":            "package lib\nfunc F() {}\n",
+		"internal/store/testdata/x.go": "package x\nfunc G() {}\n",
+		// A spec that cites a real Go file — should resolve code_ref → code.
+		"specs/f/tasks.md":  "# Tasks\n- [ ] 1. Build store `internal/store/store.go`\n  - _Requirements: 1.1_\n",
+		"specs/f/spec.json": `{"feature_name":"f"}`,
+	}
+	for rel, c := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(c), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	g, err := Build(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Package/file/decl nodes exist (R12.1).
+	pkgID := goPkgID("internal/store")
+	if nodeByID(g, pkgID) == nil {
+		t.Fatalf("missing store package node %s", pkgID)
+	}
+	fileID := MakeID("go", "file", "internal/store/store.go")
+	if nodeByID(g, fileID) == nil {
+		t.Fatalf("missing store.go file node")
+	}
+	saveID := MakeID("go", "decl", "internal/store/store.go", "Store.Save")
+	if n := nodeByID(g, saveID); n == nil {
+		t.Fatalf("missing method decl node %s", saveID)
+	} else if n.Attrs["kind"] != "method" {
+		t.Errorf("Save should be a method; got %v", n.Attrs["kind"])
+	}
+
+	// Containment edges (R12.2).
+	if !hasEdge(g, pkgID, RelContains, fileID) {
+		t.Errorf("missing contains pkg → file")
+	}
+	if !hasEdge(g, fileID, RelContains, saveID) {
+		t.Errorf("missing contains file → Save")
+	}
+
+	// Import edge resolved to the in-module package (R12.2).
+	if !hasEdge(g, pkgID, RelImports, goPkgID("internal/db")) {
+		t.Errorf("missing imports store → db (resolved)")
+	}
+
+	// Exclusions: vendor/ and testdata/ produce no nodes (R12.4).
+	if nodeByID(g, goPkgID("vendor/lib")) != nil {
+		t.Errorf("vendor/ must be excluded")
+	}
+	if nodeByID(g, goPkgID("internal/store/testdata")) != nil {
+		t.Errorf("testdata/ must be excluded")
+	}
+
+	// _test.go included but tagged (R12.4).
+	testFileID := MakeID("go", "file", "internal/store/store_test.go")
+	if n := nodeByID(g, testFileID); n == nil {
+		t.Errorf("_test.go file should be indexed")
+	} else if n.Attrs["test"] != true {
+		t.Errorf("_test.go file should be tagged test=true; got %v", n.Attrs)
+	}
+
+	// Cited path resolved code_ref → real code file node (R12.3): the edge now
+	// targets the code file, and the placeholder code_ref is gone.
+	if !hasEdge(g, taskID("f", "1"), RelReuses, fileID) {
+		t.Errorf("cited path should resolve to the code file node via reuses")
+	}
+	if nodeByID(g, codeRefID("internal/store/store.go")) != nil {
+		t.Errorf("placeholder code_ref should be replaced by the code node")
+	}
+}
diff --git a/internal/graph/extract_paths.go b/internal/graph/extract_paths.go
new file mode 100644
index 0000000..6bce7c5
--- /dev/null
+++ b/internal/graph/extract_paths.go
@@ -0,0 +1,138 @@
+package graph
+
+import (
+	"regexp"
+	"strings"
+)
+
+// codeRefID is the canonical node ID for a cited path. The path itself is stored
+// in the node's SourceFile so Assemble can stat it (reuses vs references) and M3
+// can resolve it to a real code node.
+func codeRefID(citedPath string) string { return MakeID("code_ref", citedPath) }
+
+// emitCitedPath appends a code_ref node for citedPath plus a references edge from
+// fromID. Assemble reclassifies the edge to `reuses` (EXTRACTED, 1.0) when the
+// path exists on disk, or leaves it `references` (INFERRED, planned) when it does
+// not — the deterministic on-disk check the extractor cannot perform (no I/O).
+func emitCitedPath(src Source, line int, citedPath, fromID string, frag *Fragment) {
+	cid := codeRefID(citedPath)
+	frag.Nodes = append(frag.Nodes, Node{
+		ID: cid, Label: citedPath, FileType: TypeCodeRef,
+		SourceFile: citedPath, SourceLocation: "L1",
+	})
+	frag.Edges = append(frag.Edges, Edge{
+		Source: fromID, Target: cid, Relation: RelReferences,
+		Confidence: Inferred, ConfidenceScore: 0.85, SourceFile: src.Path, Ref: citedPath,
+	})
+}
+
+// knownCodeExts are file extensions treated as citable code/artifact paths even
+// when the token has no directory separator.
+var knownCodeExts = map[string]bool{
+	".go": true, ".ts": true, ".tsx": true, ".js": true, ".jsx": true,
+	".py": true, ".rs": true, ".java": true, ".rb": true, ".c": true,
+	".h": true, ".cpp": true, ".md": true, ".json": true, ".yaml": true,
+	".yml": true, ".toml": true, ".sh": true, ".sql": true,
+}
+
+// reInlineCode matches markdown inline code spans: `like this`.
+var reInlineCode = regexp.MustCompile("`([^`]+)`")
+
+// reMdLink matches markdown link targets: [text](target).
+var reMdLink = regexp.MustCompile(`\]\(([^)]+)\)`)
+
+// citedPathsInline extracts repo-relative paths cited in a markdown line, from
+// inline code spans and link targets. Deduped, in first-seen order. URLs,
+// anchors, and non-path tokens are rejected so the graph stays honest.
+func citedPathsInline(line string) []string {
+	seen := map[string]bool{}
+	var out []string
+	add := func(tok string) {
+		p := cleanCitedToken(tok)
+		if p == "" || seen[p] {
+			return
+		}
+		seen[p] = true
+		out = append(out, p)
+	}
+	for _, m := range reInlineCode.FindAllStringSubmatch(line, -1) {
+		add(m[1])
+	}
+	for _, m := range reMdLink.FindAllStringSubmatch(line, -1) {
+		add(m[1])
+	}
+	return out
+}
+
+// reTreeArt strips box-drawing characters and leading list markers from a File
+// Structure Plan tree line.
+var reTreeArt = regexp.MustCompile(`[│├└─\t]+`)
+
+// citedPathsInTreeLine extracts a repo path from one line of a ```text tree
+// block. It drops box-drawing art and a trailing "# comment", then validates the
+// remainder as a real path. Placeholder tokens (containing < or >) are rejected.
+func citedPathsInTreeLine(line string) []string {
+	s := reTreeArt.ReplaceAllString(line, " ")
+	if i := strings.IndexByte(s, '#'); i >= 0 {
+		s = s[:i]
+	}
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil
+	}
+	// Take the first whitespace-delimited token.
+	if i := strings.IndexAny(s, " \t"); i >= 0 {
+		s = s[:i]
+	}
+	p := cleanCitedToken(s)
+	if p == "" {
+		return nil
+	}
+	return []string{p}
+}
+
+// cleanCitedToken normalizes and validates a candidate path token, returning ""
+// when it is not a plausible repo-relative file path.
+func cleanCitedToken(tok string) string {
+	tok = strings.TrimSpace(tok)
+	tok = strings.Trim(tok, "`'\"")
+	// Strip a trailing slash (directory) — we index files, not dirs, but keep the
+	// path for resolution; a bare directory has no extension and is rejected below.
+	tok = strings.TrimRight(tok, "/")
+	if tok == "" {
+		return ""
+	}
+	if strings.ContainsAny(tok, "<>*?\" ") {
+		return ""
+	}
+	if strings.Contains(tok, "://") || strings.HasPrefix(tok, "http") || strings.HasPrefix(tok, "#") || strings.HasPrefix(tok, "mailto:") {
+		return ""
+	}
+	// Drop a leading slash so an absolute-looking cite resolves workspace-relative.
+	tok = strings.TrimPrefix(tok, "/")
+	if tok == "" {
+		return ""
+	}
+	if !looksLikePath(tok) {
+		return ""
+	}
+	return tok
+}
+
+// looksLikePath reports whether a token is a plausible repo-relative file path:
+// it either has a directory separator or ends in a known code/artifact extension.
+func looksLikePath(tok string) bool {
+	if idx := strings.LastIndexByte(tok, '.'); idx >= 0 {
+		if knownCodeExts[strings.ToLower(tok[idx:])] {
+			return true
+		}
+	}
+	// A path with a separator and at least one segment that looks file-ish.
+	if strings.Contains(tok, "/") {
+		last := tok[strings.LastIndexByte(tok, '/')+1:]
+		if strings.Contains(last, ".") {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/graph/extract_spec.go b/internal/graph/extract_spec.go
new file mode 100644
index 0000000..02d2f0a
--- /dev/null
+++ b/internal/graph/extract_spec.go
@@ -0,0 +1,454 @@
+package graph
+
+import (
+	"encoding/json"
+	"path"
+	"regexp"
+	"strings"
+)
+
+// specExtractor parses the four spec artifacts. It relies on the explicit
+// traceability annotations the csdd templates already demand
+// (internal/templater/templates/spec/*.tmpl), so ~95% of the edges it emits are
+// EXTRACTED with confidence 1.0.
+type specExtractor struct{}
+
+func (specExtractor) Matches(p string) bool {
+	if specNameFromPath(p) == "" {
+		return false
+	}
+	base := path.Base(p)
+	switch base {
+	case "spec.json", "requirements.md", "design.md", "tasks.md":
+		return true
+	}
+	return false
+}
+
+func (specExtractor) Extract(src Source) ([]Fragment, error) {
+	spec := specNameFromPath(src.Path)
+	if spec == "" {
+		return nil, nil
+	}
+	switch path.Base(src.Path) {
+	case "spec.json":
+		return extractSpecJSON(spec, src)
+	case "requirements.md":
+		return extractRequirements(spec, src), nil
+	case "design.md":
+		return extractDesign(spec, src), nil
+	case "tasks.md":
+		return extractTasks(spec, src), nil
+	}
+	return nil, nil
+}
+
+// specNodeID / criterionID / taskID / designID / interfaceID / flowID are the
+// canonical ID constructors. Because "." normalizes to "_", a whole annotation
+// token ("1.2") and its split parts ("1","2") both produce the same ID, so
+// references resolve regardless of how they were written.
+func specNodeID(spec string) string        { return MakeID("spec", spec) }
+func requirementID(spec, n string) string  { return MakeID("req", spec, n) }
+func criterionID(spec, ref string) string  { return MakeID("crit", spec, ref) }
+func taskID(spec, ref string) string       { return MakeID("task", spec, ref) }
+func designID(spec, comp string) string    { return MakeID("design", spec, comp) }
+func interfaceID(spec, name string) string { return MakeID("iface", spec, name) }
+func flowID(spec, name string) string      { return MakeID("flow", spec, name) }
+
+func extractSpecJSON(spec string, src Source) ([]Fragment, error) {
+	var doc struct {
+		FeatureName     string          `json:"feature_name"`
+		Language        string          `json:"language"`
+		Phase           string          `json:"phase"`
+		DevelopmentFlow string          `json:"development_flow"`
+		Ready           bool            `json:"ready_for_implementation"`
+		Approvals       json.RawMessage `json:"approvals"`
+	}
+	// A malformed spec.json still yields a bare spec node so the folder is indexed.
+	_ = json.Unmarshal(src.Content, &doc)
+	label := doc.FeatureName
+	if label == "" {
+		label = spec
+	}
+	attrs := map[string]any{}
+	if doc.Phase != "" {
+		attrs["phase"] = doc.Phase
+	}
+	if doc.DevelopmentFlow != "" {
+		attrs["development_flow"] = doc.DevelopmentFlow
+	}
+	if doc.Language != "" {
+		attrs["language"] = doc.Language
+	}
+	attrs["ready_for_implementation"] = doc.Ready
+	return []Fragment{{Nodes: []Node{{
+		ID: specNodeID(spec), Label: label, FileType: TypeSpec,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}}, nil
+}
+
+var reRequirementHeading = regexp.MustCompile(`^###\s+Requirement\s+(\d+)\s*:?\s*(.*)$`)
+var reNumberedItem = regexp.MustCompile(`^(\d+)\.\s+(.*)$`)
+
+func extractRequirements(spec string, src Source) []Fragment {
+	lines := normLines(src.Content)
+	var frag Fragment
+	curReq := ""   // current requirement number
+	curReqID := "" // current requirement node ID
+	inCriteria := false
+	for i, raw := range lines {
+		line := strings.TrimRight(raw, " ")
+		if m := reRequirementHeading.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
+			curReq = m[1]
+			title := strings.TrimSpace(m[2])
+			curReqID = requirementID(spec, curReq)
+			label := "Requirement " + curReq
+			if title != "" {
+				label += ": " + title
+			}
+			frag.Nodes = append(frag.Nodes, Node{
+				ID: curReqID, Label: label, FileType: TypeRequire,
+				SourceFile: src.Path, SourceLocation: loc(i),
+			})
+			inCriteria = false
+			continue
+		}
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "**Acceptance Criteria**") {
+			inCriteria = true
+			continue
+		}
+		// A new heading ends the criteria region.
+		if strings.HasPrefix(trimmed, "#") || strings.HasPrefix(trimmed, "**Objective") {
+			if !strings.HasPrefix(trimmed, "###") {
+				inCriteria = false
+			}
+		}
+		if !inCriteria || curReq == "" {
+			continue
+		}
+		if m := reNumberedItem.FindStringSubmatch(trimmed); m != nil {
+			critNum := m[1]
+			text := collapseSpaces(m[2])
+			cid := criterionID(spec, curReq+"_"+critNum)
+			frag.Nodes = append(frag.Nodes, Node{
+				ID: cid, Label: text, FileType: TypeCriterion,
+				SourceFile: src.Path, SourceLocation: loc(i),
+			})
+			frag.Edges = append(frag.Edges, Edge{
+				Source: curReqID, Target: cid, Relation: RelHasCriterion,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+			})
+		}
+	}
+	return []Fragment{frag}
+}
+
+func extractDesign(spec string, src Source) []Fragment {
+	lines := normLines(src.Content)
+	var frag Fragment
+	section := ""
+	inTraceTable := false
+	// Component parsing state.
+	curComp := ""
+	curCompID := ""
+	depSubsection := "" // Inbound | Outbound | External | ""
+	inFileStructure := false
+	seenNode := map[string]bool{}
+	addNode := func(n Node) {
+		if seenNode[n.ID] {
+			return
+		}
+		seenNode[n.ID] = true
+		frag.Nodes = append(frag.Nodes, n)
+	}
+
+	for i, raw := range lines {
+		line := rtrim(raw)
+		trimmed := strings.TrimSpace(line)
+
+		if strings.HasPrefix(trimmed, "## ") {
+			section = strings.TrimSpace(strings.TrimPrefix(trimmed, "## "))
+			inTraceTable = strings.EqualFold(section, "Requirements Traceability")
+			inFileStructure = strings.EqualFold(section, "File Structure Plan")
+			curComp, curCompID, depSubsection = "", "", ""
+			continue
+		}
+
+		// --- Requirements Traceability table ---
+		if inTraceTable && strings.HasPrefix(trimmed, "|") {
+			cells := splitCells(trimmed)
+			if isTableSeparator(cells) {
+				continue
+			}
+			if len(cells) >= 1 && strings.EqualFold(cells[0], "Requirement") {
+				continue // header
+			}
+			if len(cells) < 2 {
+				continue
+			}
+			addTraceRow(spec, src, i, cells, &frag, addNode)
+			continue
+		}
+
+		// --- Components and Interfaces ---
+		if strings.EqualFold(section, "Components and Interfaces") {
+			if strings.HasPrefix(trimmed, "### ") {
+				curComp = strings.TrimSpace(strings.TrimPrefix(trimmed, "### "))
+				curCompID = designID(spec, curComp)
+				depSubsection = ""
+				addNode(Node{
+					ID: curCompID, Label: curComp, FileType: TypeDesign,
+					SourceFile: src.Path, SourceLocation: loc(i),
+				})
+				continue
+			}
+			if curComp == "" {
+				continue
+			}
+			// **Requirements**: 1.1, 1.2  → refined_by (criterion → design)
+			if v, ok := boldField(trimmed, "Requirements"); ok {
+				for _, ref := range splitList(v) {
+					frag.Edges = append(frag.Edges, Edge{
+						Source: criterionID(spec, ref), Target: curCompID, Relation: RelRefinedBy,
+						Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+					})
+				}
+				continue
+			}
+			// **Dependencies**: begins a sub-block of Inbound/Outbound/External.
+			if _, ok := boldField(trimmed, "Dependencies"); ok {
+				depSubsection = "deps"
+				continue
+			}
+			if depSubsection != "" {
+				if names, kind, ok := depLine(trimmed); ok {
+					for _, name := range names {
+						switch kind {
+						case "External":
+							// External dependency → tech (INFERRED); resolved by name.
+							tid := MakeID("tech", name)
+							addNode(Node{
+								ID: tid, Label: name, FileType: TypeTech,
+								SourceFile: src.Path, SourceLocation: loc(i),
+								Attrs: map[string]any{"status": "referenced"},
+							})
+							frag.Edges = append(frag.Edges, Edge{
+								Source: curCompID, Target: tid, Relation: RelUsesTech,
+								Confidence: Inferred, ConfidenceScore: 0.7, SourceFile: src.Path,
+							})
+						default: // Inbound / Outbound → component_dep (design → design)
+							frag.Edges = append(frag.Edges, Edge{
+								Source: curCompID, Target: designID(spec, name), Relation: RelComponentDep,
+								Confidence: Inferred, ConfidenceScore: 0.8, SourceFile: src.Path, Ref: name,
+							})
+						}
+					}
+					continue
+				}
+			}
+		}
+
+		// --- File Structure Plan: cited paths become code_ref nodes ---
+		// The reference source is the spec node (not a design component), so the
+		// planning list never masquerades as an unimplemented component.
+		if inFileStructure {
+			for _, cited := range citedPathsInTreeLine(line) {
+				emitCitedPath(src, i, cited, specNodeID(spec), &frag)
+			}
+		}
+		// Any component contract or prose line may cite a real repo path.
+		for _, cited := range citedPathsInline(line) {
+			from := specNodeID(spec)
+			if curCompID != "" && strings.EqualFold(section, "Components and Interfaces") {
+				from = curCompID
+			}
+			emitCitedPath(src, i, cited, from, &frag)
+		}
+	}
+	return []Fragment{frag}
+}
+
+// addTraceRow emits traced_to / implements / exercises for one traceability row.
+func addTraceRow(spec string, src Source, line int, cells []string, frag *Fragment, addNode func(Node)) {
+	reqCell := cells[0]
+	var comps, ifaces, flows []string
+	if len(cells) > 1 {
+		comps = splitList(cells[1])
+	}
+	if len(cells) > 2 {
+		ifaces = splitList(cells[2])
+	}
+	if len(cells) > 3 {
+		flows = splitList(cells[3])
+	}
+	for _, comp := range comps {
+		if comp == "—" || comp == "-" {
+			continue
+		}
+		did := designID(spec, comp)
+		addNode(Node{ID: did, Label: comp, FileType: TypeDesign, SourceFile: src.Path, SourceLocation: loc(line)})
+		for _, ref := range splitList(reqCell) {
+			// A malformed requirement cell (e.g. a range "3.1-3.5") is kept as the
+			// edge ref so Assemble reports it, never expanded.
+			crit := criterionID(spec, ref)
+			frag.Edges = append(frag.Edges, Edge{
+				Source: crit, Target: did, Relation: RelTracedTo,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+			})
+		}
+		for _, iface := range ifaces {
+			if iface == "—" || iface == "-" || iface == "" {
+				continue
+			}
+			iid := interfaceID(spec, iface)
+			addNode(Node{ID: iid, Label: iface, FileType: TypeInterface, SourceFile: src.Path, SourceLocation: loc(line)})
+			frag.Edges = append(frag.Edges, Edge{
+				Source: did, Target: iid, Relation: RelImplements,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+			})
+		}
+	}
+	for _, ref := range splitList(reqCell) {
+		crit := criterionID(spec, ref)
+		for _, flow := range flows {
+			if flow == "—" || flow == "-" || flow == "" {
+				continue
+			}
+			fid := flowID(spec, flow)
+			addNode(Node{ID: fid, Label: flow, FileType: TypeFlow, SourceFile: src.Path, SourceLocation: loc(line)})
+			frag.Edges = append(frag.Edges, Edge{
+				Source: crit, Target: fid, Relation: RelExercises,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+			})
+		}
+	}
+}
+
+var reTaskLine = regexp.MustCompile(`^-\s*\[([ xX])\]\s+([0-9]+(?:\.[0-9]+)*)\.?\s+(.*)$`)
+var reAnnotation = regexp.MustCompile(`^_([A-Za-z]+):\s*(.*?)_$`)
+
+func extractTasks(spec string, src Source) []Fragment {
+	lines := normLines(src.Content)
+	var frag Fragment
+	curTaskID := ""
+	for i, raw := range lines {
+		line := rtrim(raw)
+		trimmed := strings.TrimSpace(line)
+		if m := reTaskLine.FindStringSubmatch(trimmed); m != nil {
+			done := m[1] == "x" || m[1] == "X"
+			num := m[2]
+			title := strings.TrimSpace(m[3])
+			parallel := strings.Contains(title, "(P)")
+			curTaskID = taskID(spec, num)
+			status := "pending"
+			if done {
+				status = "done"
+			}
+			frag.Nodes = append(frag.Nodes, Node{
+				ID: curTaskID, Label: cleanTaskLabel(title), FileType: TypeTask,
+				SourceFile: src.Path, SourceLocation: loc(i),
+				Attrs: map[string]any{"status": status, "parallel": parallel, "number": num},
+			})
+			// Inline _Boundary:_ on the task line itself.
+			for _, b := range inlineBoundaries(title) {
+				frag.Edges = append(frag.Edges, Edge{
+					Source: curTaskID, Target: designID(spec, b), Relation: RelInBoundary,
+					Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: b,
+				})
+			}
+			// A cited path in the task title (e.g. `internal/foo/bar.go`).
+			for _, cited := range citedPathsInline(line) {
+				emitCitedPath(src, i, cited, curTaskID, &frag)
+			}
+			continue
+		}
+		if curTaskID == "" {
+			continue
+		}
+		// A task line or its notes may cite a real repo path (reuses/references).
+		for _, cited := range citedPathsInline(line) {
+			emitCitedPath(src, i, cited, curTaskID, &frag)
+		}
+		// Annotation lines: "- _Requirements: 1.1, 1.2_"
+		body := strings.TrimSpace(strings.TrimPrefix(trimmed, "-"))
+		if m := reAnnotation.FindStringSubmatch(body); m != nil {
+			key := m[1]
+			val := strings.TrimSpace(m[2])
+			switch key {
+			case "Requirements":
+				for _, ref := range splitList(val) {
+					frag.Edges = append(frag.Edges, Edge{
+						Source: curTaskID, Target: criterionID(spec, ref), Relation: RelRealizes,
+						Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+					})
+				}
+			case "Depends":
+				for _, ref := range splitList(val) {
+					frag.Edges = append(frag.Edges, Edge{
+						Source: curTaskID, Target: taskID(spec, ref), Relation: RelDependsOn,
+						Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+					})
+				}
+			case "Boundary":
+				for _, ref := range splitList(val) {
+					frag.Edges = append(frag.Edges, Edge{
+						Source: curTaskID, Target: designID(spec, ref), Relation: RelInBoundary,
+						Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: ref,
+					})
+				}
+			}
+		}
+	}
+	return []Fragment{frag}
+}
+
+var reInlineBoundary = regexp.MustCompile(`_Boundary:\s*([^_]+)_`)
+var reInlineDepends = regexp.MustCompile(`_Depends:\s*([^_]+)_`)
+
+// cleanTaskLabel strips the inline annotations (_Boundary:_, _Depends:_) and the
+// (P) marker from a task title so the node label reads as the plain capability.
+func cleanTaskLabel(title string) string {
+	title = reInlineBoundary.ReplaceAllString(title, "")
+	title = reInlineDepends.ReplaceAllString(title, "")
+	title = strings.ReplaceAll(title, "(P)", "")
+	return collapseSpaces(title)
+}
+
+func inlineBoundaries(title string) []string {
+	var out []string
+	for _, m := range reInlineBoundary.FindAllStringSubmatch(title, -1) {
+		out = append(out, splitList(m[1])...)
+	}
+	return out
+}
+
+// boldField parses a "**Key**: value" line, returning the value if the key matches.
+func boldField(line, key string) (string, bool) {
+	prefix := "**" + key + "**"
+	if !strings.HasPrefix(line, prefix) {
+		return "", false
+	}
+	rest := strings.TrimSpace(strings.TrimPrefix(line, prefix))
+	rest = strings.TrimPrefix(rest, ":")
+	return strings.TrimSpace(rest), true
+}
+
+// depLine parses an Inbound/Outbound/External dependency sub-line under
+// **Dependencies**, e.g. "- Inbound: API, Gateway". Returns the names, the kind,
+// and whether the line was a dependency line.
+func depLine(line string) (names []string, kind string, ok bool) {
+	l := strings.TrimSpace(strings.TrimPrefix(strings.TrimSpace(line), "-"))
+	for _, k := range []string{"Inbound", "Outbound", "External"} {
+		if strings.HasPrefix(l, k) {
+			rest := strings.TrimSpace(strings.TrimPrefix(l, k))
+			rest = strings.TrimPrefix(rest, ":")
+			rest = strings.TrimSpace(rest)
+			if rest == "" || rest == "..." || rest == "—" {
+				return nil, k, true
+			}
+			return splitList(rest), k, true
+		}
+	}
+	return nil, "", false
+}
diff --git a/internal/graph/extract_stack.go b/internal/graph/extract_stack.go
new file mode 100644
index 0000000..14dd0f3
--- /dev/null
+++ b/internal/graph/extract_stack.go
@@ -0,0 +1,6 @@
+package graph
+
+// stackExtractor indexes the tech contract (docs/stack.md) and dependency
+// manifests into tech nodes with uses_tech edges. Fully implemented in
+// extract_stack_impl.go; this declares the type for defaultExtractors.
+type stackExtractor struct{}
diff --git a/internal/graph/extract_stack_impl.go b/internal/graph/extract_stack_impl.go
new file mode 100644
index 0000000..301be31
--- /dev/null
+++ b/internal/graph/extract_stack_impl.go
@@ -0,0 +1,281 @@
+package graph
+
+import (
+	"encoding/json"
+	"path"
+	"regexp"
+	"sort"
+	"strings"
+)
+
+// Matches claims docs/stack.md (the tech contract) and the dependency manifests.
+func (stackExtractor) Matches(p string) bool {
+	if p == "docs/stack.md" {
+		return true
+	}
+	switch path.Base(p) {
+	case "go.mod", "package.json", "pyproject.toml", "requirements.txt":
+		return true
+	}
+	return false
+}
+
+func (stackExtractor) Extract(src Source) ([]Fragment, error) {
+	if src.Path == "docs/stack.md" {
+		return stackContract(src), nil
+	}
+	return stackManifest(src), nil
+}
+
+// techID keys a tech node by its short, normalized name so a contract entry and
+// the dependency that realizes it collapse onto the same node (matched by
+// normalized name, §5.6).
+func techID(name string) string { return MakeID("tech", techKey(name)) }
+
+// techKey reduces a raw dependency or contract choice to a comparable short name:
+// the last path segment (for module paths like github.com/go-chi/chi) with any
+// version specifier stripped, normalized.
+var reMajorVersionSeg = regexp.MustCompile(`^v[0-9]+$`)
+
+// techKey reduces a raw dependency or contract choice to a comparable short name.
+// A scoped npm package (@scope/name) keeps its scope so it never collides with a
+// same-named bare package (@monaco-editor/react must not fold onto react). A
+// module path (github.com/go-chi/chi/v5) reduces to its last non-version segment
+// so the contract entry "chi" still matches. Everything else normalizes as-is.
+func techKey(name string) string {
+	name = strings.TrimSpace(name)
+	if strings.HasPrefix(name, "@") {
+		// npm scoped package: normalize the whole "@scope/name" (drop any version).
+		if i := strings.IndexAny(name, "@<>=~! "); i > 0 {
+			// keep the leading @, cut a trailing "@version" if present
+			if v := strings.LastIndexByte(name, '@'); v > 0 {
+				name = name[:v]
+			}
+		}
+		return NormalizeID(name)
+	}
+	// Take the last path segment, skipping a Go-module major-version suffix.
+	segs := strings.Split(strings.TrimRight(name, "/"), "/")
+	if len(segs) > 0 {
+		last := segs[len(segs)-1]
+		if reMajorVersionSeg.MatchString(last) && len(segs) > 1 {
+			last = segs[len(segs)-2]
+		}
+		name = last
+	}
+	fields := strings.FieldsFunc(name, func(r rune) bool {
+		return r == '=' || r == '>' || r == '<' || r == '~' || r == '!' || r == '^' || r == '@' || r == ' ' || r == '\t'
+	})
+	if len(fields) > 0 {
+		name = fields[0]
+	}
+	return NormalizeID(name)
+}
+
+// stackContract parses the Decided table of docs/stack.md into tech nodes. The
+// Rules and Open-questions sections are prose and are not parsed.
+func stackContract(src Source) []Fragment {
+	lines := normLines(src.Content)
+	var frag Fragment
+	inDecided := false
+	headerSeen := false
+	for i, raw := range lines {
+		trimmed := strings.TrimSpace(rtrim(raw))
+		if strings.HasPrefix(trimmed, "## ") {
+			title := strings.ToLower(strings.TrimSpace(strings.TrimPrefix(trimmed, "## ")))
+			inDecided = strings.HasPrefix(title, "decided")
+			headerSeen = false
+			continue
+		}
+		if !inDecided || !strings.HasPrefix(trimmed, "|") {
+			continue
+		}
+		cells := splitCells(trimmed)
+		if isTableSeparator(cells) {
+			continue
+		}
+		if !headerSeen {
+			headerSeen = true // first row is the column header
+			continue
+		}
+		if len(cells) < 2 {
+			continue
+		}
+		choice := cells[1]
+		if choice == "" || choice == "—" || choice == "-" {
+			continue
+		}
+		attrs := map[string]any{"status": "decided", "from_contract": true}
+		if cells[0] != "" {
+			attrs["domain"] = cells[0]
+		}
+		version := ""
+		if len(cells) > 2 {
+			version = strings.TrimSpace(cells[2])
+		}
+		refs := ""
+		if len(cells) > 4 {
+			refs = strings.TrimSpace(cells[4])
+		}
+		attrs["version"] = version
+		attrs["refs"] = refs
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: techID(choice), Label: choice, FileType: TypeTech,
+			SourceFile: src.Path, SourceLocation: loc(i), Attrs: attrs,
+		})
+	}
+	return []Fragment{frag}
+}
+
+// stackManifest parses a dependency manifest into a code_ref node (the manifest)
+// and a tech node + uses_tech edge per declared dependency.
+func stackManifest(src Source) []Fragment {
+	var deps []string
+	eco := ""
+	switch path.Base(src.Path) {
+	case "go.mod":
+		deps, eco = parseGoMod(src.Content), "go"
+	case "package.json":
+		deps, eco = parsePackageJSON(src.Content), "npm"
+	case "pyproject.toml":
+		deps, eco = parsePyproject(src.Content), "python"
+	case "requirements.txt":
+		deps, eco = parseRequirementsTxt(src.Content), "python"
+	}
+	manifestID := codeRefID(src.Path)
+	frag := Fragment{Nodes: []Node{{
+		ID: manifestID, Label: path.Base(src.Path), FileType: TypeCodeRef,
+		SourceFile: src.Path, SourceLocation: "L1",
+		Attrs: map[string]any{"kind": "manifest", "ecosystem": eco},
+	}}}
+	seen := map[string]bool{}
+	for _, dep := range deps {
+		id := techID(dep)
+		if seen[id] {
+			continue
+		}
+		seen[id] = true
+		frag.Nodes = append(frag.Nodes, Node{
+			ID: id, Label: dep, FileType: TypeTech,
+			SourceFile: src.Path, SourceLocation: "L1",
+			Attrs: map[string]any{"status": "used", "from_manifest": true, "ecosystem": eco},
+		})
+		frag.Edges = append(frag.Edges, Edge{
+			Source: manifestID, Target: id, Relation: RelUsesTech,
+			Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+		})
+	}
+	return []Fragment{frag}
+}
+
+var reGoRequireLine = regexp.MustCompile(`^\s*([a-zA-Z0-9.\-/]+)\s+v[0-9]`)
+
+// parseGoMod returns the direct module dependencies (skipping `// indirect`).
+func parseGoMod(content []byte) []string {
+	var out []string
+	inBlock := false
+	for _, raw := range normLines(content) {
+		line := strings.TrimSpace(raw)
+		if strings.HasPrefix(line, "//") {
+			continue
+		}
+		if strings.HasPrefix(line, "require (") {
+			inBlock = true
+			continue
+		}
+		if inBlock && line == ")" {
+			inBlock = false
+			continue
+		}
+		target := line
+		if strings.HasPrefix(line, "require ") {
+			target = strings.TrimSpace(strings.TrimPrefix(line, "require "))
+		} else if !inBlock {
+			continue
+		}
+		if strings.Contains(target, "// indirect") {
+			continue
+		}
+		if m := reGoRequireLine.FindStringSubmatch(target); m != nil {
+			out = append(out, m[1])
+		}
+	}
+	return out
+}
+
+func parsePackageJSON(content []byte) []string {
+	var doc struct {
+		Dependencies    map[string]json.RawMessage `json:"dependencies"`
+		DevDependencies map[string]json.RawMessage `json:"devDependencies"`
+	}
+	if err := json.Unmarshal(content, &doc); err != nil {
+		return nil
+	}
+	var out []string
+	for name := range doc.Dependencies {
+		out = append(out, name)
+	}
+	for name := range doc.DevDependencies {
+		out = append(out, name)
+	}
+	// Sort so the extracted order is deterministic (map iteration is randomized);
+	// last-writer-wins node dedup must not depend on walk order.
+	sort.Strings(out)
+	return out
+}
+
+var rePyDepArrayItem = regexp.MustCompile(`["']([A-Za-z0-9._\-]+)\s*(?:[=<>~!].*)?["']`)
+var rePyPoetryDep = regexp.MustCompile(`^([A-Za-z0-9._\-]+)\s*=`)
+
+// parsePyproject does a pragmatic scan: PEP 621 `dependencies = [ "a", "b>=1" ]`
+// arrays and `[tool.poetry.dependencies]` tables. Full TOML parsing is avoided to
+// stay dependency-free.
+func parsePyproject(content []byte) []string {
+	var out []string
+	lines := normLines(content)
+	inArray := false
+	inPoetry := false
+	for _, raw := range lines {
+		line := strings.TrimSpace(raw)
+		if strings.HasPrefix(line, "[") {
+			inPoetry = strings.HasPrefix(line, "[tool.poetry.dependencies]")
+			inArray = false
+			continue
+		}
+		if strings.HasPrefix(line, "dependencies") && strings.Contains(line, "[") {
+			inArray = true
+		}
+		if inArray {
+			for _, m := range rePyDepArrayItem.FindAllStringSubmatch(line, -1) {
+				out = append(out, m[1])
+			}
+			if strings.Contains(line, "]") {
+				inArray = false
+			}
+			continue
+		}
+		if inPoetry {
+			if m := rePyPoetryDep.FindStringSubmatch(line); m != nil && m[1] != "python" {
+				out = append(out, m[1])
+			}
+		}
+	}
+	return out
+}
+
+func parseRequirementsTxt(content []byte) []string {
+	var out []string
+	for _, raw := range normLines(content) {
+		line := strings.TrimSpace(raw)
+		if line == "" || strings.HasPrefix(line, "#") || strings.HasPrefix(line, "-") {
+			continue
+		}
+		name := strings.FieldsFunc(line, func(r rune) bool {
+			return r == '=' || r == '>' || r == '<' || r == '~' || r == '!' || r == ' ' || r == ';' || r == '['
+		})
+		if len(name) > 0 && name[0] != "" {
+			out = append(out, name[0])
+		}
+	}
+	return out
+}
diff --git a/internal/graph/extract_stack_test.go b/internal/graph/extract_stack_test.go
new file mode 100644
index 0000000..2e96f6b
--- /dev/null
+++ b/internal/graph/extract_stack_test.go
@@ -0,0 +1,139 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+func TestStackContractAndLints(t *testing.T) {
+	dir := t.TempDir()
+	files := map[string]string{
+		"docs/stack.md": `# Stack
+## Decided
+| Domain | Choice | Version | Why | Refs |
+|---|---|---|---|---|
+| Router | chi | v5 | lightweight | [notes](docs/wiki/pages/chi.md) |
+| Cache | redis |  | speed |  |
+
+## Rules
+The contract is law.
+
+## Open questions
+- none
+`,
+		"go.mod": `module example.com/p
+
+go 1.22
+
+require (
+	github.com/go-chi/chi/v5 v5.0.0
+	github.com/lib/pq v1.10.0 // indirect
+)
+
+require github.com/spf13/cobra v1.8.0
+`,
+	}
+	for rel, c := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(c), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+	ex := []Extractor{&stackExtractor{}, &wikiExtractor{}}
+	g, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// Contract rows → tech nodes (R17.2).
+	chi := nodeByID(g, techID("chi"))
+	if chi == nil || chi.Attrs["from_contract"] != true {
+		t.Fatalf("chi contract node missing/incorrect: %+v", chi)
+	}
+	// Manifest dep chi → uses_tech from the go.mod code_ref (R17.2).
+	if !hasEdge(g, codeRefID("go.mod"), RelUsesTech, techID("chi")) {
+		t.Errorf("missing uses_tech go.mod → chi")
+	}
+
+	report := Analyze(g, dir)
+	kinds := map[string][]string{}
+	for _, f := range report.Findings {
+		kinds[f.Kind] = append(kinds[f.Kind], f.Label)
+	}
+
+	// cobra is a direct dep not in the contract → undeclared (R17.3).
+	if !containsLabel(kinds[kindUndeclaredTech], "github.com/spf13/cobra") {
+		t.Errorf("expected undeclared cobra; got %v", kinds[kindUndeclaredTech])
+	}
+	// pq is `// indirect` and skipped, so it must NOT be flagged undeclared.
+	if containsLabel(kinds[kindUndeclaredTech], "github.com/lib/pq") {
+		t.Errorf("indirect dep pq should be skipped")
+	}
+	// redis is declared but unused → phantom; and missing Version+Refs → unrefined.
+	if len(kinds[kindPhantomTech]) == 0 {
+		t.Errorf("expected phantom tech (redis)")
+	}
+	if len(kinds[kindUnrefinedTech]) == 0 {
+		t.Errorf("expected unrefined tech (redis)")
+	}
+	// chi is declared AND used with version+refs → clean (no findings about it).
+	for _, k := range []string{kindUndeclaredTech, kindPhantomTech, kindUnrefinedTech} {
+		if containsLabel(kinds[k], "chi") {
+			t.Errorf("chi should be clean; flagged as %s", k)
+		}
+	}
+	// Contract present → no no_tech_contract finding.
+	if len(kinds[kindNoTechContract]) != 0 {
+		t.Errorf("stack.md present; no_tech_contract must not fire")
+	}
+}
+
+// TestScopedNpmPackagesDistinct guards against the react vs @monaco-editor/react
+// collision that made package.json indexing non-deterministic: scoped packages
+// must key distinctly from a same-named bare package, and repeated builds must be
+// byte-identical.
+func TestScopedNpmPackagesDistinct(t *testing.T) {
+	if techID("react") == techID("@monaco-editor/react") {
+		t.Fatalf("scoped and bare package must not share a tech ID")
+	}
+	dir := t.TempDir()
+	pkg := `{"dependencies":{"react":"^18","@monaco-editor/react":"^4","react-dom":"^18"}}`
+	if err := os.WriteFile(filepath.Join(dir, "package.json"), []byte(pkg), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	ex := []Extractor{&stackExtractor{}}
+	var first string
+	for i := 0; i < 8; i++ {
+		g, err := BuildWith(dir, ex)
+		if err != nil {
+			t.Fatal(err)
+		}
+		data, _ := Marshal(g)
+		if i == 0 {
+			first = string(data)
+			// All three packages become distinct tech nodes.
+			for _, id := range []string{techID("react"), techID("@monaco-editor/react"), techID("react-dom")} {
+				if nodeByID(g, id) == nil {
+					t.Errorf("missing tech node %s", id)
+				}
+			}
+			continue
+		}
+		if string(data) != first {
+			t.Fatalf("package.json indexing not deterministic across builds")
+		}
+	}
+}
+
+func containsLabel(list []string, want string) bool {
+	for _, l := range list {
+		if l == want {
+			return true
+		}
+	}
+	return false
+}
diff --git a/internal/graph/extract_wiki.go b/internal/graph/extract_wiki.go
new file mode 100644
index 0000000..12ead43
--- /dev/null
+++ b/internal/graph/extract_wiki.go
@@ -0,0 +1,158 @@
+package graph
+
+import (
+	"path"
+	"regexp"
+	"strings"
+
+	"github.com/protonspy/csdd/internal/frontmatter"
+	"github.com/protonspy/csdd/internal/textutil"
+)
+
+// wikiExtractor indexes the documentation knowledge base under docs/: every
+// markdown page outside docs/raw/ becomes a wiki_page carrying its frontmatter,
+// and every file under docs/raw/ becomes an opaque raw_source (path only). It is
+// wiki-aware — [[wikilinks]] and `sources:` provenance become links_to and
+// derived_from edges — while treating docs/plans/ and other docs the same way.
+type wikiExtractor struct{}
+
+func (wikiExtractor) Matches(p string) bool {
+	if !strings.HasPrefix(p, "docs/") {
+		return false
+	}
+	if strings.HasPrefix(p, "docs/graph/") {
+		return false // the only generated subtree in docs/ — never re-indexed
+	}
+	if p == "docs/raw/README.md" {
+		return false // the scaffold's dropzone explainer, not a raw source to ingest
+	}
+	if isRawSourcePath(p) {
+		return true // any file, any extension, indexed opaquely
+	}
+	return strings.HasSuffix(p, ".md")
+}
+
+func (wikiExtractor) Extract(src Source) ([]Fragment, error) {
+	if isRawSourcePath(src.Path) {
+		return rawSourceFragment(src), nil
+	}
+	return wikiPageFragment(src), nil
+}
+
+// rawSourceID is the canonical ID for an immutable source under docs/raw/, keyed
+// by its path relative to docs/raw/ so a `sources:` reference (with or without
+// the docs/raw/ prefix) resolves to it.
+func rawSourceID(rawRelPath string) string {
+	rel := strings.TrimPrefix(rawRelPath, "docs/raw/")
+	return MakeID("raw", rel)
+}
+
+// wikiPageID is the canonical ID for a page, keyed by its base filename so a
+// [[wikilink]] written with the page's title or slug resolves to it (both
+// normalize identically).
+func wikiPageID(pagePath string) string {
+	base := strings.TrimSuffix(path.Base(pagePath), ".md")
+	return MakeID("wiki", base)
+}
+
+func rawSourceFragment(src Source) []Fragment {
+	rel := strings.TrimPrefix(src.Path, "docs/raw/")
+	return []Fragment{{Nodes: []Node{{
+		ID: rawSourceID(src.Path), Label: rel, FileType: TypeRawSource,
+		SourceFile: src.Path, SourceLocation: "L1",
+	}}}}
+}
+
+var reWikiLink = regexp.MustCompile(`\[\[([^\]|#]+)(?:[|#][^\]]*)?\]\]`)
+
+func wikiPageFragment(src Source) []Fragment {
+	fm := frontmatter.Parse(string(src.Content))
+	pid := wikiPageID(src.Path)
+	attrs := map[string]any{}
+	if tags := fm.AsStringSlice("tags"); len(tags) > 0 {
+		attrs["tags"] = tags
+	}
+	for _, k := range []string{"date", "updated", "created", "status", "category"} {
+		if v := fm.AsString(k, ""); v != "" {
+			attrs[k] = v
+		}
+	}
+	label := fm.AsString("title", "")
+	if label == "" {
+		label = firstHeading(fm.Body)
+	}
+	if label == "" {
+		label = strings.TrimSuffix(path.Base(src.Path), ".md")
+	}
+	frag := Fragment{Nodes: []Node{{
+		ID: pid, Label: label, FileType: TypeWikiPage,
+		SourceFile: src.Path, SourceLocation: "L1", Attrs: attrs,
+	}}}
+
+	// derived_from from the frontmatter sources: list (provenance).
+	for _, s := range fm.AsStringSlice("sources") {
+		addDerivedFrom(&frag, src, pid, s)
+	}
+
+	// Body: [[wikilinks]], raw/ provenance links, and other cited repo paths.
+	// Commented-out scaffold examples are stripped so they are never parsed.
+	body := stripHTMLComments(textutil.NormalizeNewlines(string(src.Content)))
+	for i, raw := range strings.Split(body, "\n") {
+		for _, m := range reWikiLink.FindAllStringSubmatch(raw, -1) {
+			text := strings.TrimSpace(m[1])
+			if strings.ContainsAny(text, "<>") {
+				continue // a placeholder like [[<slug>]], not a real link
+			}
+			frag.Edges = append(frag.Edges, Edge{
+				Source: pid, Target: wikiTargetID(text), Relation: RelLinksTo,
+				Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path,
+				Ref: text,
+			})
+		}
+		for _, cited := range citedPathsInline(raw) {
+			if isRawSourcePath(cited) {
+				addDerivedFrom(&frag, src, pid, cited)
+				continue
+			}
+			emitCitedPath(src, i, cited, pid, &frag)
+		}
+	}
+	return []Fragment{frag}
+}
+
+// wikiTargetID resolves a [[wikilink]] target text to a wiki_page ID. A link may
+// carry a path (docs/wiki/pages/foo.md) or a bare title (Foo); both reduce to the
+// base name, normalized.
+func wikiTargetID(text string) string {
+	text = strings.TrimSpace(text)
+	if strings.Contains(text, "/") {
+		text = path.Base(text)
+	}
+	text = strings.TrimSuffix(text, ".md")
+	return MakeID("wiki", text)
+}
+
+// addDerivedFrom appends a derived_from edge from a page to the raw source it was
+// derived from, resolving the reference to a raw_source node ID.
+func addDerivedFrom(frag *Fragment, src Source, pageID, rawRef string) {
+	rawRef = strings.TrimSpace(rawRef)
+	if rawRef == "" {
+		return
+	}
+	frag.Edges = append(frag.Edges, Edge{
+		Source: pageID, Target: rawSourceID(rawRef), Relation: RelDerivedFrom,
+		Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: src.Path, Ref: rawRef,
+	})
+}
+
+var reHeading = regexp.MustCompile(`^#{1,6}\s+(.*)$`)
+
+// firstHeading returns the text of the first markdown heading in a body, or "".
+func firstHeading(body string) string {
+	for _, line := range strings.Split(body, "\n") {
+		if m := reHeading.FindStringSubmatch(strings.TrimSpace(line)); m != nil {
+			return collapseSpaces(m[1])
+		}
+	}
+	return ""
+}
diff --git a/internal/graph/ids.go b/internal/graph/ids.go
new file mode 100644
index 0000000..25ecaf7
--- /dev/null
+++ b/internal/graph/ids.go
@@ -0,0 +1,43 @@
+package graph
+
+import (
+	"regexp"
+	"strings"
+
+	"golang.org/x/text/unicode/norm"
+)
+
+// reNonWord collapses every run of non-word characters (anything that is not a
+// Unicode letter or number) into a single underscore. Using the Unicode classes
+// \p{L}\p{N} keeps CJK ideographs and accented letters intact rather than
+// stripping them, which matters for non-English artifact titles.
+var reNonWord = regexp.MustCompile(`[^\p{L}\p{N}]+`)
+
+// reUnderscores squashes any accidental underscore runs left over after
+// normalization into one.
+var reUnderscores = regexp.MustCompile(`_+`)
+
+// NormalizeID is the single canonical ID function — graphify's lesson #1: one
+// place, imported by extraction and assembly, so the same artifact always yields
+// the same node ID across rebuilds (no ghost duplicates). It applies NFKC so
+// visually-identical Unicode spellings collapse, replaces non-word runs with
+// underscores, and casefolds. It is idempotent: NormalizeID(NormalizeID(s)) == NormalizeID(s).
+func NormalizeID(s string) string {
+	s = norm.NFKC.String(s)
+	s = reNonWord.ReplaceAllString(s, "_")
+	s = reUnderscores.ReplaceAllString(s, "_")
+	return strings.ToLower(strings.Trim(s, "_"))
+}
+
+// MakeID joins the given parts with underscores after normalizing each, dropping
+// empties so a blank part never produces a doubled separator. The result is
+// itself a normalized, idempotent ID.
+func MakeID(parts ...string) string {
+	out := make([]string, 0, len(parts))
+	for _, p := range parts {
+		if n := NormalizeID(p); n != "" {
+			out = append(out, n)
+		}
+	}
+	return strings.Join(out, "_")
+}
diff --git a/internal/graph/ids_test.go b/internal/graph/ids_test.go
new file mode 100644
index 0000000..7b025c8
--- /dev/null
+++ b/internal/graph/ids_test.go
@@ -0,0 +1,58 @@
+package graph
+
+import "testing"
+
+func TestNormalizeID(t *testing.T) {
+	cases := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"lowercase spaces", "Album Service", "album_service"},
+		{"trims edge underscores", "  --Foo--  ", "foo"},
+		{"collapses runs", "a...b   c", "a_b_c"},
+		{"casefold", "REQ.1.2", "req_1_2"},
+		{"keeps digits", "Requirement 1", "requirement_1"},
+		{"keeps accents", "Café Ação", "café_ação"},
+		{"keeps cjk", "設計 node", "設計_node"},
+		{"empty", "", ""},
+		{"only punctuation", "---", ""},
+		{"nfkc fold ligature", "file", "file"},
+		{"nfkc fullwidth", "ＡＢ", "ab"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			got := NormalizeID(c.in)
+			if got != c.want {
+				t.Fatalf("NormalizeID(%q) = %q, want %q", c.in, got, c.want)
+			}
+			// Idempotence: normalizing an already-normalized ID is a no-op.
+			if again := NormalizeID(got); again != got {
+				t.Fatalf("NormalizeID not idempotent: %q -> %q", got, again)
+			}
+		})
+	}
+}
+
+func TestMakeID(t *testing.T) {
+	cases := []struct {
+		parts []string
+		want  string
+	}{
+		{[]string{"crit", "graph-index", "1", "2"}, "crit_graph_index_1_2"},
+		{[]string{"task", "foo", "1.1"}, "task_foo_1_1"},
+		{[]string{"design", "foo", "AlbumService"}, "design_foo_albumservice"},
+		{[]string{"", "spec", ""}, "spec"},      // empty parts dropped
+		{[]string{"a", "", "b"}, "a_b"},         // no doubled separators
+		{[]string{"Café", "Ação"}, "café_ação"}, // unicode preserved
+	}
+	for _, c := range cases {
+		got := MakeID(c.parts...)
+		if got != c.want {
+			t.Fatalf("MakeID(%v) = %q, want %q", c.parts, got, c.want)
+		}
+		if again := NormalizeID(got); again != got {
+			t.Fatalf("MakeID output not normalized-stable: %q -> %q", got, again)
+		}
+	}
+}
diff --git a/internal/graph/incremental.go b/internal/graph/incremental.go
new file mode 100644
index 0000000..7bbb361
--- /dev/null
+++ b/internal/graph/incremental.go
@@ -0,0 +1,124 @@
+package graph
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+
+	"github.com/protonspy/csdd/internal/manifest"
+	"github.com/protonspy/csdd/internal/workspace"
+)
+
+// StateRel is the incremental build state — per-source content hashes and their
+// cached extraction fragments. It lives in .csdd/ (operational state), is local
+// and regenerable, and is not committed (§5.9).
+const StateRel = ".csdd/state.json"
+
+// sourceCache is one source's cached contribution: the content hash it was
+// extracted at and the fragments that extraction produced. Reusing it skips
+// re-parsing an unchanged file (R13.2 "skip its re-extraction").
+type sourceCache struct {
+	Hash      string     `json:"hash"`
+	Fragments []Fragment `json:"fragments"`
+}
+
+// buildState is the on-disk incremental cache.
+type buildState struct {
+	Version int                    `json:"version"`
+	Sources map[string]sourceCache `json:"sources"`
+}
+
+// BuildIncremental builds the graph reusing cached fragments for unchanged
+// sources: a source whose content hash is unchanged is not re-extracted; a
+// changed source has its entire prior contribution replaced (replace-per-source);
+// a deleted source is pruned from the cache (R13.2). The assembled result is
+// byte-identical to a full Build, because the same fragments feed the same
+// deterministic Assemble regardless of which were cached (R13.3).
+func BuildIncremental(root string) (*Graph, error) {
+	return buildIncrementalWith(root, defaultExtractors())
+}
+
+func buildIncrementalWith(root string, extractors []Extractor) (*Graph, error) {
+	sources, err := collectSources(root, extractors)
+	if err != nil {
+		return nil, err
+	}
+	state := loadState(root)
+	next := &buildState{Version: 1, Sources: map[string]sourceCache{}}
+
+	var nodes []Node
+	var edges []Edge
+	for _, src := range sources {
+		h := manifest.Hash(string(src.Content))
+		if cached, ok := state.Sources[src.Path]; ok && cached.Hash == h {
+			// Unchanged: reuse without re-parsing.
+			next.Sources[src.Path] = cached
+			for _, f := range cached.Fragments {
+				nodes = append(nodes, f.Nodes...)
+				edges = append(edges, f.Edges...)
+			}
+			continue
+		}
+		frags, err := dispatch(extractors, src)
+		if err != nil {
+			return nil, err
+		}
+		if frags == nil {
+			frags = []Fragment{}
+		}
+		next.Sources[src.Path] = sourceCache{Hash: h, Fragments: frags}
+		for _, f := range frags {
+			nodes = append(nodes, f.Nodes...)
+			edges = append(edges, f.Edges...)
+		}
+	}
+	// Deleted sources simply vanish: next only contains current paths.
+
+	g := assemble(root, nodes, edges)
+	if err := saveState(root, next); err != nil {
+		return nil, err
+	}
+	return g, nil
+}
+
+// assemble is the shared post-extraction pipeline (merge → ownership → resolve →
+// references → sort → meta), factored out so full and incremental builds run the
+// identical assembly and therefore produce identical output.
+func assemble(root string, nodes []Node, edges []Edge) *Graph {
+	g := New()
+	g.Nodes = dedupNodes(nodes)
+	g.Links = dedupEdges(edges)
+	assembleSpecOwnership(g)
+	resolveCitedPaths(g, root)
+	resolveGoImports(g, root)
+	g.Pending = resolveReferences(g)
+	sortGraph(g)
+	setMeta(g)
+	return g
+}
+
+func statePath(root string) string {
+	return filepath.Join(root, filepath.FromSlash(StateRel))
+}
+
+// loadState reads the incremental cache, returning an empty state when it is
+// absent or unreadable (a corrupt cache just forces a full re-extraction).
+func loadState(root string) *buildState {
+	data, err := os.ReadFile(statePath(root))
+	if err != nil {
+		return &buildState{Version: 1, Sources: map[string]sourceCache{}}
+	}
+	var st buildState
+	if err := json.Unmarshal(data, &st); err != nil || st.Sources == nil {
+		return &buildState{Version: 1, Sources: map[string]sourceCache{}}
+	}
+	return &st
+}
+
+func saveState(root string, st *buildState) error {
+	data, err := json.MarshalIndent(st, "", "  ")
+	if err != nil {
+		return err
+	}
+	return workspace.AtomicWrite(statePath(root), data, 0o644)
+}
diff --git a/internal/graph/model.go b/internal/graph/model.go
new file mode 100644
index 0000000..755f526
--- /dev/null
+++ b/internal/graph/model.go
@@ -0,0 +1,387 @@
+// Package graph is csdd's knowledge base: a deterministic, persistent graph over
+// the artifacts csdd governs (specs/, .claude/, CLAUDE.md, .mcp.json), the
+// documentation under docs/ (wiki + raw sources), the tech contract
+// (docs/stack.md + dependency manifests), and — from M3 — the project's Go
+// source. It answers csdd's core question ("what connects this requirement to
+// the code, and what breaks if I change this task?") by traversal instead of by
+// re-reading files, and it is the substrate the spec-lint (`csdd graph analyze`)
+// and wiki-lint operations run on.
+//
+// The model is a straight port of graphify's {nodes, edges} contract with a
+// single canonical node ID and confidence tiers, serialised as NetworkX
+// node-link JSON so the graph is directly loadable by NetworkX/graphify tooling.
+package graph
+
+import (
+	"encoding/json"
+	"fmt"
+	"sort"
+)
+
+// Confidence tiers label how an edge was derived. EXTRACTED is an explicit
+// annotation or an exact cited path (score 1.0); INFERRED is resolved by
+// name/path matching (discrete 0.55–0.95); AMBIGUOUS is genuine uncertainty
+// surfaced for the human gate (0.1–0.3). Structural ambiguity that is not one of
+// these is omitted, never emitted as a noisy edge.
+const (
+	Extracted = "EXTRACTED"
+	Inferred  = "INFERRED"
+	Ambiguous = "AMBIGUOUS"
+)
+
+// Node file_type values — the canonical node vocabulary (PLAN §5.5). Kept as
+// constants so extractors never spell a type wrong and drift the schema.
+const (
+	TypeSpec      = "spec"
+	TypeRequire   = "requirement"
+	TypeCriterion = "criterion"
+	TypeDesign    = "design"
+	TypeInterface = "interface"
+	TypeFlow      = "flow"
+	TypeTask      = "task"
+	TypeSteering  = "steering"
+	TypeSkill     = "skill"
+	TypeAgent     = "agent"
+	TypeMCP       = "mcp"
+	TypeCodeRef   = "code_ref"
+	TypeWikiPage  = "wiki_page"
+	TypeRawSource = "raw_source"
+	TypeTech      = "tech"
+	TypeCode      = "code"
+)
+
+// Edge relation values — the canonical edge vocabulary (PLAN §5.5).
+const (
+	RelOwns         = "owns"
+	RelHasCriterion = "has_criterion"
+	RelRealizes     = "realizes"
+	RelTracedTo     = "traced_to"
+	RelImplements   = "implements"
+	RelExercises    = "exercises"
+	RelRefinedBy    = "refined_by"
+	RelInBoundary   = "in_boundary"
+	RelDependsOn    = "depends_on"
+	RelComponentDep = "component_dep"
+	RelReferences   = "references"
+	RelReuses       = "reuses"
+	RelGoverns      = "governs"
+	RelRelatedTo    = "related_to"
+	RelLinksTo      = "links_to"
+	RelDerivedFrom  = "derived_from"
+	RelUsesTech     = "uses_tech"
+	RelContains     = "contains"
+	RelImports      = "imports"
+)
+
+// NodeTypes and EdgeRelations mirror the seed graph.json meta block so the
+// generated file always advertises the full vocabulary regardless of which
+// corpora happen to be present in a given workspace.
+var NodeTypes = []string{
+	TypeSpec, TypeRequire, TypeCriterion, TypeDesign, TypeInterface, TypeFlow,
+	TypeTask, TypeSteering, TypeSkill, TypeAgent, TypeMCP, TypeCodeRef,
+	TypeWikiPage, TypeRawSource, TypeTech, TypeCode,
+}
+
+var EdgeRelations = []string{
+	RelOwns, RelHasCriterion, RelRealizes, RelTracedTo, RelImplements,
+	RelExercises, RelRefinedBy, RelInBoundary, RelDependsOn, RelComponentDep,
+	RelReferences, RelReuses, RelGoverns, RelRelatedTo, RelLinksTo,
+	RelDerivedFrom, RelUsesTech, RelContains, RelImports,
+}
+
+// Node is one artifact or entity. The five fixed fields are always present;
+// Attrs carries type-specific metadata (task status, parallel flag, frontmatter
+// tags, tech version, …) that is flattened into the node object on the wire.
+type Node struct {
+	ID             string
+	Label          string
+	FileType       string
+	SourceFile     string
+	SourceLocation string
+	Attrs          map[string]any
+}
+
+// Edge is one relationship. Endpoints are node IDs. Confidence is the tier
+// label; ConfidenceScore is its numeric weight. SourceFile records which file
+// the edge was extracted from (its provenance).
+//
+// Ref carries the raw reference text as written in the source (e.g. "1.1" or a
+// component name) for edges derived from an annotation whose target is resolved
+// at assembly time. It is never part of the node-link wire format (marshalEdge
+// omits it), but it IS carried in the incremental fragment cache, so it is an
+// exported field with an explicit tag. It lets assembly report an unresolved
+// reference (PendingRef) with the exact string the author wrote.
+type Edge struct {
+	Source          string
+	Target          string
+	Relation        string
+	Confidence      string
+	ConfidenceScore float64
+	SourceFile      string
+	Ref             string `json:"ref,omitempty"`
+}
+
+// PendingRef is a reference (a numeric annotation ID or a boundary component
+// name) that did not resolve to any node in the assembled graph. In csdd the gap
+// is the product: these are reported by `analyze`, never silently dropped.
+type PendingRef struct {
+	FromID     string // the node that carried the annotation
+	FromLabel  string // its human label (for the finding message)
+	Relation   string // realizes | depends_on | in_boundary | ...
+	TargetID   string // the unresolved node ID
+	Ref        string // the raw reference as written (e.g. "9.9" or "GhostComponent")
+	SourceFile string
+}
+
+// Graph is a directed knowledge graph. Meta is the node-link "graph" block.
+// Pending holds unresolved references discovered during assembly; it is not part
+// of the node-link wire format (it is a build-time diagnostic consumed by
+// analyze), so a Graph reloaded from disk has an empty Pending slice.
+type Graph struct {
+	Directed   bool
+	Multigraph bool
+	Meta       map[string]any
+	Nodes      []Node
+	Links      []Edge
+	Pending    []PendingRef
+}
+
+// New returns an empty directed graph with the canonical meta block seeded.
+func New() *Graph {
+	return &Graph{
+		Directed:   true,
+		Multigraph: false,
+		Meta:       map[string]any{},
+		Nodes:      []Node{},
+		Links:      []Edge{},
+	}
+}
+
+// nodeLink is the on-disk (NetworkX node-link) envelope. Nodes and links are
+// json.RawMessage because each element is a flat object merging the fixed fields
+// with the Attrs map — encoded/decoded by (Node|Edge).marshal below.
+type nodeLink struct {
+	Directed   bool              `json:"directed"`
+	Multigraph bool              `json:"multigraph"`
+	Meta       map[string]any    `json:"graph"`
+	Nodes      []json.RawMessage `json:"nodes"`
+	Links      []json.RawMessage `json:"links"`
+}
+
+// reservedNodeKeys and reservedEdgeKeys are the fixed field names that must not
+// be clobbered by (or duplicated into) the flattened Attrs map on decode.
+var reservedNodeKeys = map[string]bool{
+	"id": true, "label": true, "file_type": true,
+	"source_file": true, "source_location": true,
+}
+
+// MarshalJSON emits the graph as NetworkX node-link JSON. Node Attrs are
+// flattened alongside the fixed keys; attr keys are written in sorted order so
+// the output is byte-identical across runs (Go map iteration is randomized).
+func (g *Graph) MarshalJSON() ([]byte, error) {
+	nl := nodeLink{
+		Directed:   g.Directed,
+		Multigraph: g.Multigraph,
+		Meta:       g.Meta,
+		Nodes:      make([]json.RawMessage, 0, len(g.Nodes)),
+		Links:      make([]json.RawMessage, 0, len(g.Links)),
+	}
+	if nl.Meta == nil {
+		nl.Meta = map[string]any{}
+	}
+	for _, n := range g.Nodes {
+		raw, err := marshalNode(n)
+		if err != nil {
+			return nil, err
+		}
+		nl.Nodes = append(nl.Nodes, raw)
+	}
+	for _, e := range g.Links {
+		raw, err := marshalEdge(e)
+		if err != nil {
+			return nil, err
+		}
+		nl.Links = append(nl.Links, raw)
+	}
+	return json.Marshal(nl)
+}
+
+// orderedObject encodes a map as a JSON object with keys emitted in a caller-
+// supplied order, so node/edge objects are deterministic and human-readable
+// (fixed fields first, then sorted attrs).
+func orderedObject(pairs [][2]any) ([]byte, error) {
+	var buf []byte
+	buf = append(buf, '{')
+	for i, kv := range pairs {
+		if i > 0 {
+			buf = append(buf, ',')
+		}
+		k, err := json.Marshal(kv[0])
+		if err != nil {
+			return nil, err
+		}
+		v, err := json.Marshal(kv[1])
+		if err != nil {
+			return nil, err
+		}
+		buf = append(buf, k...)
+		buf = append(buf, ':')
+		buf = append(buf, v...)
+	}
+	buf = append(buf, '}')
+	return buf, nil
+}
+
+func marshalNode(n Node) ([]byte, error) {
+	pairs := [][2]any{
+		{"id", n.ID},
+		{"label", n.Label},
+		{"file_type", n.FileType},
+		{"source_file", n.SourceFile},
+		{"source_location", n.SourceLocation},
+	}
+	for _, k := range sortedAttrKeys(n.Attrs, reservedNodeKeys) {
+		pairs = append(pairs, [2]any{k, n.Attrs[k]})
+	}
+	return orderedObject(pairs)
+}
+
+func marshalEdge(e Edge) ([]byte, error) {
+	pairs := [][2]any{
+		{"source", e.Source},
+		{"target", e.Target},
+		{"relation", e.Relation},
+		{"confidence", e.Confidence},
+		{"confidence_score", e.ConfidenceScore},
+		{"source_file", e.SourceFile},
+	}
+	return orderedObject(pairs)
+}
+
+// sortedAttrKeys returns the attr keys not shadowed by a reserved field, sorted.
+func sortedAttrKeys(attrs map[string]any, reserved map[string]bool) []string {
+	if len(attrs) == 0 {
+		return nil
+	}
+	keys := make([]string, 0, len(attrs))
+	for k := range attrs {
+		if reserved[k] {
+			continue
+		}
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+	return keys
+}
+
+// UnmarshalJSON parses NetworkX node-link JSON, splitting each flat node object
+// back into the fixed fields plus the residual Attrs map. It is the inverse of
+// MarshalJSON, so a round-trip preserves every field (R8.1 interoperability).
+func (g *Graph) UnmarshalJSON(data []byte) error {
+	var nl nodeLink
+	if err := json.Unmarshal(data, &nl); err != nil {
+		return err
+	}
+	g.Directed = nl.Directed
+	g.Multigraph = nl.Multigraph
+	g.Meta = nl.Meta
+	if g.Meta == nil {
+		g.Meta = map[string]any{}
+	}
+	g.Nodes = make([]Node, 0, len(nl.Nodes))
+	for _, raw := range nl.Nodes {
+		n, err := unmarshalNode(raw)
+		if err != nil {
+			return err
+		}
+		g.Nodes = append(g.Nodes, n)
+	}
+	g.Links = make([]Edge, 0, len(nl.Links))
+	for _, raw := range nl.Links {
+		e, err := unmarshalEdge(raw)
+		if err != nil {
+			return err
+		}
+		g.Links = append(g.Links, e)
+	}
+	return nil
+}
+
+func unmarshalNode(raw json.RawMessage) (Node, error) {
+	var m map[string]json.RawMessage
+	if err := json.Unmarshal(raw, &m); err != nil {
+		return Node{}, err
+	}
+	n := Node{}
+	getString(m, "id", &n.ID)
+	getString(m, "label", &n.Label)
+	getString(m, "file_type", &n.FileType)
+	getString(m, "source_file", &n.SourceFile)
+	getString(m, "source_location", &n.SourceLocation)
+	for k, v := range m {
+		if reservedNodeKeys[k] {
+			continue
+		}
+		if n.Attrs == nil {
+			n.Attrs = map[string]any{}
+		}
+		var val any
+		if err := json.Unmarshal(v, &val); err != nil {
+			return Node{}, err
+		}
+		n.Attrs[k] = val
+	}
+	return n, nil
+}
+
+func unmarshalEdge(raw json.RawMessage) (Edge, error) {
+	var obj struct {
+		Source          string  `json:"source"`
+		Target          string  `json:"target"`
+		Relation        string  `json:"relation"`
+		Confidence      string  `json:"confidence"`
+		ConfidenceScore float64 `json:"confidence_score"`
+		SourceFile      string  `json:"source_file"`
+	}
+	if err := json.Unmarshal(raw, &obj); err != nil {
+		return Edge{}, err
+	}
+	return Edge{
+		Source:          obj.Source,
+		Target:          obj.Target,
+		Relation:        obj.Relation,
+		Confidence:      obj.Confidence,
+		ConfidenceScore: obj.ConfidenceScore,
+		SourceFile:      obj.SourceFile,
+	}, nil
+}
+
+func getString(m map[string]json.RawMessage, key string, dst *string) {
+	if raw, ok := m[key]; ok {
+		_ = json.Unmarshal(raw, dst)
+	}
+}
+
+// nodeIndex builds an id → *Node lookup over the current node slice.
+func (g *Graph) nodeIndex() map[string]*Node {
+	idx := make(map[string]*Node, len(g.Nodes))
+	for i := range g.Nodes {
+		idx[g.Nodes[i].ID] = &g.Nodes[i]
+	}
+	return idx
+}
+
+// HasNode reports whether a node with the given ID exists.
+func (g *Graph) HasNode(id string) bool {
+	for i := range g.Nodes {
+		if g.Nodes[i].ID == id {
+			return true
+		}
+	}
+	return false
+}
+
+// String renders a short human summary (node/edge counts), handy in errors.
+func (g *Graph) String() string {
+	return fmt.Sprintf("graph(%d nodes, %d edges)", len(g.Nodes), len(g.Links))
+}
diff --git a/internal/graph/model_test.go b/internal/graph/model_test.go
new file mode 100644
index 0000000..16ff133
--- /dev/null
+++ b/internal/graph/model_test.go
@@ -0,0 +1,100 @@
+package graph
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestNodeLinkRoundTrip(t *testing.T) {
+	g := New()
+	g.Meta["schema_version"] = float64(1)
+	g.Nodes = []Node{
+		{
+			ID: "spec_foo", Label: "foo", FileType: TypeSpec,
+			SourceFile: "specs/foo/spec.json", SourceLocation: "L1",
+			Attrs: map[string]any{"phase": "tasks", "development_flow": "tdd"},
+		},
+		{
+			ID: "task_foo_1_1", Label: "Do a thing", FileType: TypeTask,
+			SourceFile: "specs/foo/tasks.md", SourceLocation: "L10",
+			Attrs: map[string]any{"status": "pending", "parallel": true},
+		},
+	}
+	g.Links = []Edge{
+		{Source: "spec_foo", Target: "task_foo_1_1", Relation: RelOwns, Confidence: Extracted, ConfidenceScore: 1.0, SourceFile: "specs/foo/spec.json"},
+	}
+
+	data, err := json.Marshal(g)
+	if err != nil {
+		t.Fatalf("marshal: %v", err)
+	}
+
+	// The wire format must be NetworkX node-link (R8.1): the five envelope keys.
+	var envelope map[string]json.RawMessage
+	if err := json.Unmarshal(data, &envelope); err != nil {
+		t.Fatalf("unmarshal envelope: %v", err)
+	}
+	for _, k := range []string{"directed", "multigraph", "graph", "nodes", "links"} {
+		if _, ok := envelope[k]; !ok {
+			t.Fatalf("node-link JSON missing key %q; got %s", k, data)
+		}
+	}
+
+	// Attrs must be flattened into the node object, not nested.
+	if !strings.Contains(string(data), `"development_flow":"tdd"`) {
+		t.Fatalf("expected flattened attr development_flow in %s", data)
+	}
+	if !strings.Contains(string(data), `"parallel":true`) {
+		t.Fatalf("expected flattened attr parallel in %s", data)
+	}
+
+	var back Graph
+	if err := json.Unmarshal(data, &back); err != nil {
+		t.Fatalf("unmarshal: %v", err)
+	}
+	if len(back.Nodes) != 2 || len(back.Links) != 1 {
+		t.Fatalf("round-trip lost data: %s", back.String())
+	}
+	if back.Nodes[0].FileType != TypeSpec || back.Nodes[0].Attrs["phase"] != "tasks" {
+		t.Fatalf("node 0 corrupted: %+v", back.Nodes[0])
+	}
+	if back.Nodes[1].Attrs["parallel"] != true {
+		t.Fatalf("bool attr lost: %+v", back.Nodes[1].Attrs)
+	}
+	e := back.Links[0]
+	if e.Source != "spec_foo" || e.Relation != RelOwns || e.ConfidenceScore != 1.0 {
+		t.Fatalf("edge corrupted: %+v", e)
+	}
+}
+
+func TestMarshalDeterministic(t *testing.T) {
+	// Same graph, marshaled twice, must be byte-identical despite the randomized
+	// Go map iteration over Attrs (§5.9 git-diff stability).
+	mk := func() *Graph {
+		g := New()
+		g.Nodes = []Node{{
+			ID: "n", Label: "n", FileType: TypeTask,
+			Attrs: map[string]any{"z": 1, "a": 2, "m": 3, "status": "done"},
+		}}
+		return g
+	}
+	var first string
+	for i := 0; i < 20; i++ {
+		data, err := json.Marshal(mk())
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i == 0 {
+			first = string(data)
+			continue
+		}
+		if string(data) != first {
+			t.Fatalf("non-deterministic marshal:\n%s\nvs\n%s", first, data)
+		}
+	}
+	// Attr keys must appear sorted.
+	if !strings.Contains(first, `"a":2,"m":3,"status":"done","z":1`) {
+		t.Fatalf("attrs not sorted: %s", first)
+	}
+}
diff --git a/internal/graph/pipeline_test.go b/internal/graph/pipeline_test.go
new file mode 100644
index 0000000..ae2cfa3
--- /dev/null
+++ b/internal/graph/pipeline_test.go
@@ -0,0 +1,353 @@
+package graph
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+)
+
+// writeFixture materializes a small but complete csdd workspace under dir,
+// crafted to trigger every analyze/wiki-lint finding at least once.
+func writeFixture(t *testing.T, dir string) {
+	t.Helper()
+	files := map[string]string{
+		"specs/photos/spec.json": `{"feature_name":"photos","language":"go","phase":"tasks","development_flow":"tdd","ready_for_implementation":false}`,
+		"specs/photos/requirements.md": `# Requirements
+## Requirements
+### Requirement 1: Upload
+**Objective**
+As a user, I want uploads.
+**Acceptance Criteria**
+1. WHEN a photo is uploaded THEN the system SHALL store it.
+2. IF the file is too large THEN the system SHALL reject it.
+
+### Requirement 2: View
+**Acceptance Criteria**
+1. WHEN a user views THE SYSTEM SHALL list photos.
+2. WHERE albums exist THE SYSTEM SHALL group them.
+`,
+		"specs/photos/design.md": `# Design
+## Requirements Traceability
+| Requirement | Components | Interfaces | Flows |
+|---|---|---|---|
+| 1.1 | AlbumService | upload() | upload-flow |
+| 3.1-3.5 | RangeComp | x() | y-flow |
+
+## Components and Interfaces
+
+### AlbumService
+- **Requirements**: 1.1
+- **Dependencies**:
+  - Inbound: API
+  - External: aws-s3
+
+### GhostService
+- **Requirements**: 2.1
+`,
+		"specs/photos/tasks.md": `# Tasks
+## Phase 1: Foundation
+- [ ] 1. Implement upload _Boundary: AlbumService_
+  - _Requirements: 1.1_
+- [ ] 2. Do some plumbing _Boundary: AlbumService_
+- [ ] 3. Bad reference
+  - _Requirements: 9.9_
+- [ ] 4. First cycle node
+  - _Requirements: 1.2_
+  - _Depends: 5_
+- [ ] 5. Second cycle node
+  - _Requirements: 2.1_
+  - _Depends: 4_
+`,
+		".claude/skills/wiki/SKILL.md": "---\nname: wiki\ndescription: wiki skill\n---\n# Wiki\n",
+		".claude/agents/reviewer.md":   "---\nname: reviewer\ndescription: reviews\nmodel: sonnet\n---\n# Reviewer\n",
+		".claude/rules/ears.md":        "# EARS\nUse SHALL.\n",
+		".mcp.json":                    `{"mcpServers":{"csdd":{"command":"npx","args":["-y","@protonspy/csdd-mcp"]}}}`,
+		"CLAUDE.md":                    "# Project\nEntry point.\n",
+		"docs/wiki/index.md": `# Wiki Index
+## Pages
+- [Overview](pages/overview.md)
+- [Ghost](pages/ghost.md)
+`,
+		"docs/wiki/log.md": `# Log
+## [2026-07-06] ingest | good entry
+## [bad] wrong format
+`,
+		"docs/wiki/pages/overview.md": `---
+title: Overview
+sources: [docs/raw/article.md]
+tags: [core]
+---
+# Overview
+See [[Details]] and [[Nonexistent]].
+Also see ` + "`internal/graph/model.go`" + ` and ` + "`internal/nope/ghost.go`" + `.
+`,
+		"docs/wiki/pages/details.md": "# Details\nSome detail here.\n",
+		"docs/wiki/pages/orphan.md":  "# Orphan\nNobody links here.\n",
+		"docs/raw/article.md":        "Raw article content.\n",
+		"docs/raw/unused.md":         "Unprocessed raw content.\n",
+		// A real repo file so a reuses edge resolves.
+		"internal/graph/model.go": "package graph\n",
+	}
+	for rel, content := range files {
+		p := filepath.Join(dir, filepath.FromSlash(rel))
+		if err := os.MkdirAll(filepath.Dir(p), 0o755); err != nil {
+			t.Fatal(err)
+		}
+		if err := os.WriteFile(p, []byte(content), 0o644); err != nil {
+			t.Fatal(err)
+		}
+	}
+}
+
+func buildFixture(t *testing.T) (*Graph, string) {
+	t.Helper()
+	dir := t.TempDir()
+	writeFixture(t, dir)
+	// Exclude the go extractor so a lone `package graph` file does not add code
+	// nodes to this spec/wiki-focused fixture (its resolution is tested separately).
+	ex := []Extractor{&specExtractor{}, &claudeExtractor{}, &stackExtractor{}, &wikiExtractor{}}
+	g, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatalf("build: %v", err)
+	}
+	return g, dir
+}
+
+func nodeByID(g *Graph, id string) *Node {
+	for i := range g.Nodes {
+		if g.Nodes[i].ID == id {
+			return &g.Nodes[i]
+		}
+	}
+	return nil
+}
+
+func hasEdge(g *Graph, src, rel, tgt string) bool {
+	for _, e := range g.Links {
+		if e.Source == src && e.Relation == rel && e.Target == tgt {
+			return true
+		}
+	}
+	return false
+}
+
+func TestBuildNodesAndEdges(t *testing.T) {
+	g, _ := buildFixture(t)
+
+	// Spec node exists (from spec.json) and owns its children (R1.1).
+	if n := nodeByID(g, "spec_photos"); n == nil || n.FileType != TypeSpec {
+		t.Fatalf("missing spec node; got %v", n)
+	}
+	if !hasEdge(g, "spec_photos", RelOwns, requirementID("photos", "1")) {
+		t.Errorf("spec should own requirement 1")
+	}
+	if !hasEdge(g, "spec_photos", RelOwns, taskID("photos", "1")) {
+		t.Errorf("spec should own task 1")
+	}
+
+	// Criteria + has_criterion (R1.2, R1.3).
+	c11 := criterionID("photos", "1_1")
+	if nodeByID(g, c11) == nil {
+		t.Fatalf("missing criterion 1.1 (%s)", c11)
+	}
+	if !hasEdge(g, requirementID("photos", "1"), RelHasCriterion, c11) {
+		t.Errorf("requirement 1 should have criterion 1.1")
+	}
+
+	// realizes is EXTRACTED with score 1.0 (R1.3).
+	var found bool
+	for _, e := range g.Links {
+		if e.Source == taskID("photos", "1") && e.Relation == RelRealizes && e.Target == c11 {
+			found = true
+			if e.Confidence != Extracted || e.ConfidenceScore != 1.0 {
+				t.Errorf("realizes edge should be EXTRACTED 1.0; got %s %v", e.Confidence, e.ConfidenceScore)
+			}
+		}
+	}
+	if !found {
+		t.Errorf("missing realizes edge task 1 → criterion 1.1")
+	}
+
+	// Traceability: traced_to / implements / exercises.
+	if !hasEdge(g, c11, RelTracedTo, designID("photos", "AlbumService")) {
+		t.Errorf("missing traced_to crit 1.1 → AlbumService")
+	}
+	if !hasEdge(g, designID("photos", "AlbumService"), RelImplements, interfaceID("photos", "upload()")) {
+		t.Errorf("missing implements AlbumService → upload()")
+	}
+	if !hasEdge(g, c11, RelExercises, flowID("photos", "upload-flow")) {
+		t.Errorf("missing exercises crit 1.1 → upload-flow")
+	}
+
+	// in_boundary from task 1.
+	if !hasEdge(g, taskID("photos", "1"), RelInBoundary, designID("photos", "AlbumService")) {
+		t.Errorf("missing in_boundary task 1 → AlbumService")
+	}
+
+	// depends_on both directions (the cycle).
+	if !hasEdge(g, taskID("photos", "4"), RelDependsOn, taskID("photos", "5")) {
+		t.Errorf("missing depends_on 4 → 5")
+	}
+
+	// Task parallel/status attrs.
+	if n := nodeByID(g, taskID("photos", "1")); n == nil || n.Attrs["status"] != "pending" {
+		t.Errorf("task 1 status wrong: %v", n)
+	}
+
+	// .claude nodes.
+	for _, id := range []string{"skill_wiki", "agent_reviewer", "mcp_csdd", "entry_claude_md"} {
+		if nodeByID(g, id) == nil {
+			t.Errorf("missing .claude node %s", id)
+		}
+	}
+
+	// wiki + raw nodes.
+	if nodeByID(g, "wiki_overview") == nil || nodeByID(g, "raw_article_md") == nil {
+		t.Errorf("missing wiki/raw nodes")
+	}
+	// derived_from provenance from frontmatter sources:.
+	if !hasEdge(g, "wiki_overview", RelDerivedFrom, "raw_article_md") {
+		t.Errorf("missing derived_from overview → article")
+	}
+	// links_to wikilink resolves to the details page.
+	if !hasEdge(g, "wiki_overview", RelLinksTo, "wiki_details") {
+		t.Errorf("missing links_to overview → details")
+	}
+
+	// A cited path that exists → reuses (EXTRACTED); one that doesn't → references.
+	reuseOK, refOK := false, false
+	for _, e := range g.Links {
+		if e.Target == codeRefID("internal/graph/model.go") && e.Relation == RelReuses && e.Confidence == Extracted {
+			reuseOK = true
+		}
+		if e.Target == codeRefID("internal/nope/ghost.go") && e.Relation == RelReferences {
+			refOK = true
+		}
+	}
+	if !reuseOK {
+		t.Errorf("cited existing path should be a reuses/EXTRACTED edge")
+	}
+	if !refOK {
+		t.Errorf("cited missing path should be a references edge")
+	}
+}
+
+func TestByteStableDoubleBuild(t *testing.T) {
+	dir := t.TempDir()
+	writeFixture(t, dir)
+	ex := []Extractor{&specExtractor{}, &claudeExtractor{}, &stackExtractor{}, &wikiExtractor{}, &goExtractor{}}
+
+	g1, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatal(err)
+	}
+	d1, err := Marshal(g1)
+	if err != nil {
+		t.Fatal(err)
+	}
+	g2, err := BuildWith(dir, ex)
+	if err != nil {
+		t.Fatal(err)
+	}
+	d2, err := Marshal(g2)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(d1) != string(d2) {
+		t.Fatalf("double build not byte-identical:\n--- first ---\n%s\n--- second ---\n%s", d1, d2)
+	}
+}
+
+func TestAnalyzeFindings(t *testing.T) {
+	g, dir := buildFixture(t)
+	report := Analyze(g, dir)
+	got := map[string]int{}
+	for _, f := range report.Findings {
+		got[f.Kind]++
+	}
+	want := []string{
+		kindUntestedRequirement, // criterion 2.2
+		kindOrphanTask,          // task 2
+		kindUnimplementedCompo,  // GhostService / RangeComp
+		kindPendingReference,    // task 3 → 9.9
+		kindRangeShorthand,      // traceability 3.1-3.5
+		kindDependencyCycle,     // tasks 4 ↔ 5
+		kindBrokenWikilink,      // [[Nonexistent]]
+		kindOrphanPage,          // orphan.md
+		kindIndexMissingPage,    // details.md / orphan.md
+		kindIndexDanglingEntry,  // pages/ghost.md
+		kindLogFormat,           // "## [bad] wrong format"
+		kindUnprocessedSource,   // docs/raw/unused.md
+		kindNoTechContract,      // no docs/stack.md
+	}
+	for _, k := range want {
+		if got[k] == 0 {
+			t.Errorf("expected at least one %q finding; findings: %+v", k, report.Findings)
+		}
+	}
+
+	// Untested must specifically flag criterion 2.2 and NOT 1.1 (which is realized).
+	untested := map[string]bool{}
+	for _, f := range report.Findings {
+		if f.Kind == kindUntestedRequirement {
+			untested[f.NodeID] = true
+		}
+	}
+	if !untested[criterionID("photos", "2_2")] {
+		t.Errorf("criterion 2.2 should be untested")
+	}
+	if untested[criterionID("photos", "1_1")] {
+		t.Errorf("criterion 1.1 is realized and must not be untested")
+	}
+}
+
+func TestWriteBuildDeterministicAndLog(t *testing.T) {
+	g, dir := buildFixture(t)
+	now := time.Date(2026, 7, 6, 12, 0, 0, 0, time.UTC)
+	d1, err := WriteBuild(dir, g, now)
+	if err != nil {
+		t.Fatal(err)
+	}
+	onDisk, err := os.ReadFile(GraphJSONPath(dir))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(onDisk) != string(d1) {
+		t.Errorf("written file differs from returned bytes")
+	}
+	// log.md gained a build heading in the documented format.
+	logData, err := os.ReadFile(filepath.Join(dir, filepath.FromSlash(GraphLogRel)))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !reLogEntry.MatchString(firstBuildHeading(string(logData))) {
+		t.Errorf("log heading not in documented format: %q", firstBuildHeading(string(logData)))
+	}
+}
+
+func firstBuildHeading(s string) string {
+	for _, line := range splitLines(s) {
+		if len(line) > 4 && line[:4] == "## [" {
+			return line
+		}
+	}
+	return ""
+}
+
+func splitLines(s string) []string {
+	var out []string
+	cur := ""
+	for _, r := range s {
+		if r == '\n' {
+			out = append(out, cur)
+			cur = ""
+			continue
+		}
+		cur += string(r)
+	}
+	if cur != "" {
+		out = append(out, cur)
+	}
+	return out
+}
diff --git a/internal/graph/query.go b/internal/graph/query.go
new file mode 100644
index 0000000..2233727
--- /dev/null
+++ b/internal/graph/query.go
@@ -0,0 +1,493 @@
+package graph
+
+import (
+	"fmt"
+	"math"
+	"sort"
+	"strings"
+)
+
+// QueryOptions tunes retrieval. Hops is the neighborhood radius (default 1).
+// Budget is the token budget honored by the M4 engine; the v1 label matcher
+// ignores it (the surface is stable across the M1→M4 swap, §5.11).
+type QueryOptions struct {
+	Hops   int
+	Budget int
+}
+
+// Neighbor is one edge incident to a matched node, with the node on the far end
+// and the edge's real direction relative to the match.
+type Neighbor struct {
+	Direction string `json:"direction"` // "out" (match→node) or "in" (node→match)
+	Relation  string `json:"relation"`
+	Node      Node   `json:"node"`
+}
+
+// Match is a query hit: the node, the tier it matched on, and its neighborhood.
+type Match struct {
+	Node      Node       `json:"node"`
+	Tier      string     `json:"tier"` // exact | prefix | substring
+	Neighbors []Neighbor `json:"neighbors"`
+}
+
+// Tier ranks; lower is stronger.
+const (
+	tierExact     = "exact"
+	tierPrefix    = "prefix"
+	tierSubstring = "substring"
+)
+
+func tierRank(t string) int {
+	switch t {
+	case tierExact:
+		return 0
+	case tierPrefix:
+		return 1
+	default:
+		return 2
+	}
+}
+
+// defaultTokenBudget is the rendering budget (R13.1) when the caller passes 0.
+const defaultTokenBudget = 2000
+
+// hubGateFloor is the minimum degree at which hub-gating can kick in — a node is
+// never treated as a super-hub below this, regardless of the p99 (R13.1).
+const hubGateFloor = 50
+
+// Query returns nodes matching terms, scored by label tier weighted by inverse
+// document frequency, each with its (hub-gated) neighborhood, rendered within a
+// token budget (R13.1). At small corpus size this reduces to the v1 label
+// matcher — tier ordering, full neighborhoods, nothing truncated — so the M1
+// query behavior is preserved (§5.11: same surface, the internals grow).
+func Query(g *Graph, terms string, opts QueryOptions) []Match {
+	hops := opts.Hops
+	if hops <= 0 {
+		hops = 1
+	}
+	budget := opts.Budget
+	if budget <= 0 {
+		budget = defaultTokenBudget
+	}
+	toks := tokenize(terms)
+	if len(toks) == 0 {
+		return nil
+	}
+	idf := buildIDF(g, toks)
+	hubThreshold := hubThreshold(g)
+
+	// Score every node: sum over terms of tier_weight(term) × idf(term). A node
+	// matching any term becomes a hit, so every term that matches anything is
+	// seeded by at least its best node (R13.1: ≥1 seed per term).
+	type scored struct {
+		node  Node
+		score float64
+		tier  string
+	}
+	var hits []scored
+	for _, n := range g.Nodes {
+		total := 0.0
+		bestRank := 99
+		bestTier := ""
+		for _, tk := range toks {
+			w, tier := termTierWeight(n, tk)
+			if w == 0 {
+				continue
+			}
+			total += w * idf[tk]
+			if r := tierRank(tier); r < bestRank {
+				bestRank = r
+				bestTier = tier
+			}
+		}
+		if total > 0 {
+			hits = append(hits, scored{node: n, score: total, tier: bestTier})
+		}
+	}
+	sort.SliceStable(hits, func(i, j int) bool {
+		if hits[i].score != hits[j].score {
+			return hits[i].score > hits[j].score
+		}
+		if ri, rj := tierRank(hits[i].tier), tierRank(hits[j].tier); ri != rj {
+			return ri < rj
+		}
+		return hits[i].node.ID < hits[j].node.ID
+	})
+
+	// Render within the token budget, attaching each hit's hub-gated neighborhood.
+	var matches []Match
+	spent := 0
+	for _, h := range hits {
+		cost := estimateTokens(h.node.Label) + 6
+		if spent+cost > budget && len(matches) > 0 {
+			break
+		}
+		spent += cost
+		nbrs := neighborhoodGated(g, h.node.ID, hops, hubThreshold)
+		kept := nbrs[:0:0]
+		for _, nb := range nbrs {
+			c := estimateTokens(nb.Node.Label) + 4
+			if spent+c > budget {
+				break
+			}
+			spent += c
+			kept = append(kept, nb)
+		}
+		matches = append(matches, Match{Node: h.node, Tier: h.tier, Neighbors: kept})
+	}
+	return matches
+}
+
+// tokenize splits a query into normalized, stopword-filtered terms.
+func tokenize(q string) []string {
+	fields := splitWords(NormalizeID(q))
+	var out []string
+	for _, f := range fields {
+		if f == "" || stopwords[f] {
+			continue
+		}
+		out = append(out, f)
+	}
+	if len(out) == 0 {
+		// All stopwords (or a single normalized token): fall back to the whole
+		// normalized query so a lookup like "the-x" still resolves.
+		if whole := NormalizeID(q); whole != "" {
+			return []string{whole}
+		}
+	}
+	return out
+}
+
+func splitWords(normalized string) []string {
+	return strings.Split(normalized, "_")
+}
+
+var stopwords = map[string]bool{
+	"the": true, "a": true, "an": true, "of": true, "to": true, "and": true,
+	"or": true, "in": true, "on": true, "for": true, "is": true, "are": true,
+}
+
+// buildIDF computes inverse document frequency per term over node labels+IDs.
+func buildIDF(g *Graph, terms []string) map[string]float64 {
+	n := float64(len(g.Nodes))
+	if n == 0 {
+		n = 1
+	}
+	idf := map[string]float64{}
+	for _, tk := range terms {
+		df := 0
+		for _, node := range g.Nodes {
+			if termTierWeightRank(node, tk) > 0 {
+				df++
+			}
+		}
+		idf[tk] = math.Log(1 + n/float64(1+df))
+	}
+	return idf
+}
+
+// termTierWeight scores how a single term matches a node and returns (weight, tier).
+func termTierWeight(n Node, term string) (float64, string) {
+	nl := NormalizeID(n.Label)
+	id := n.ID
+	switch {
+	case nl == term || id == term:
+		return 3, tierExact
+	case strings.HasPrefix(nl, term) || strings.HasPrefix(id, term):
+		return 2, tierPrefix
+	case strings.Contains(nl, term) || strings.Contains(id, term):
+		return 1, tierSubstring
+	}
+	return 0, ""
+}
+
+func termTierWeightRank(n Node, term string) float64 {
+	w, _ := termTierWeight(n, term)
+	return w
+}
+
+// hubThreshold returns the degree above which a node is a super-hub not traversed
+// *through* — max(p99 of degrees, floor). At small scale the floor dominates, so
+// nothing is gated (v1 behavior preserved).
+func hubThreshold(g *Graph) int {
+	deg := degreeMap(g)
+	if len(deg) == 0 {
+		return hubGateFloor
+	}
+	degrees := make([]int, 0, len(deg))
+	for _, d := range deg {
+		degrees = append(degrees, d)
+	}
+	sort.Ints(degrees)
+	idx := int(0.99 * float64(len(degrees)-1))
+	p99 := degrees[idx]
+	if p99 < hubGateFloor {
+		return hubGateFloor
+	}
+	return p99
+}
+
+// neighborhoodGated is neighborhood() with hub-gating: a super-hub can be a
+// neighbor, but BFS never expands *through* it into its own neighbors (R13.1).
+func neighborhoodGated(g *Graph, id string, hops, hubThreshold int) []Neighbor {
+	idx := g.nodeIndex()
+	adj := buildAdjacency(g)
+	deg := degreeMap(g)
+	visited := map[string]bool{id: true}
+	var out []Neighbor
+	frontier := []string{id}
+	for depth := 0; depth < hops; depth++ {
+		var next []string
+		for _, cur := range frontier {
+			// Do not expand through a super-hub (but the hub itself was already
+			// added as a neighbor when it was first reached).
+			if cur != id && deg[cur] > hubThreshold {
+				continue
+			}
+			for _, a := range adj[cur] {
+				if visited[a.to] {
+					continue
+				}
+				visited[a.to] = true
+				if nn := idx[a.to]; nn != nil {
+					out = append(out, Neighbor{Direction: a.dir, Relation: a.relation, Node: *nn})
+				}
+				next = append(next, a.to)
+			}
+		}
+		frontier = next
+	}
+	sort.SliceStable(out, func(i, j int) bool {
+		if out[i].Relation != out[j].Relation {
+			return out[i].Relation < out[j].Relation
+		}
+		return out[i].Node.ID < out[j].Node.ID
+	})
+	return out
+}
+
+// estimateTokens is a coarse token estimate for budget accounting (~4 chars/token).
+func estimateTokens(s string) int {
+	t := len(s) / 4
+	if t < 1 {
+		t = 1
+	}
+	return t
+}
+
+// labelTier reports the strongest tier at which node matches the normalized query,
+// or "" for no match. ID and label are both consulted (IDs are already normalized).
+func labelTier(n Node, q string) string {
+	nl := NormalizeID(n.Label)
+	id := n.ID
+	switch {
+	case nl == q || id == q:
+		return tierExact
+	case strings.HasPrefix(nl, q) || strings.HasPrefix(id, q):
+		return tierPrefix
+	case strings.Contains(nl, q) || strings.Contains(id, q):
+		return tierSubstring
+	}
+	return ""
+}
+
+// arc is one directed adjacency entry with the direction relative to the node it
+// is stored under.
+type arc struct {
+	to       string
+	relation string
+	dir      string // "out" if the stored node is the edge source, else "in"
+}
+
+// buildAdjacency builds an undirected adjacency (both directions) preserving each
+// edge's real orientation via arc.dir.
+func buildAdjacency(g *Graph) map[string][]arc {
+	adj := map[string][]arc{}
+	for _, e := range g.Links {
+		adj[e.Source] = append(adj[e.Source], arc{to: e.Target, relation: e.Relation, dir: "out"})
+		adj[e.Target] = append(adj[e.Target], arc{to: e.Source, relation: e.Relation, dir: "in"})
+	}
+	for k := range adj {
+		sort.SliceStable(adj[k], func(i, j int) bool {
+			if adj[k][i].relation != adj[k][j].relation {
+				return adj[k][i].relation < adj[k][j].relation
+			}
+			return adj[k][i].to < adj[k][j].to
+		})
+	}
+	return adj
+}
+
+// PathStep is one hop along a path: the edge (with its real direction) and the
+// node it leads to.
+type PathStep struct {
+	Relation  string `json:"relation"`
+	Direction string `json:"direction"` // "forward" (with the edge) or "backward"
+	Node      Node   `json:"node"`
+}
+
+// PathResult is a resolved shortest path from From to To.
+type PathResult struct {
+	From  Node       `json:"from"`
+	To    Node       `json:"to"`
+	Steps []PathStep `json:"steps"`
+}
+
+// Path returns the shortest path between the nodes A and B resolve to, rendering
+// each edge with its real direction (R2.2). It errors when A and B resolve to the
+// same node, or when either does not resolve, or when no path exists.
+func Path(g *Graph, a, b string, maxHops int) (*PathResult, error) {
+	from, ok := resolveNode(g, a)
+	if !ok {
+		return nil, fmt.Errorf("no node matches %q", a)
+	}
+	to, ok := resolveNode(g, b)
+	if !ok {
+		return nil, fmt.Errorf("no node matches %q", b)
+	}
+	if from.ID == to.ID {
+		return nil, fmt.Errorf("both endpoints resolve to the same node (%s)", from.ID)
+	}
+	if maxHops <= 0 {
+		maxHops = len(g.Nodes) + 1
+	}
+	adj := buildAdjacency(g)
+	// BFS over the undirected graph, remembering the arc used to reach each node.
+	type crumb struct {
+		prev string
+		via  arc
+	}
+	prev := map[string]crumb{from.ID: {}}
+	queue := []string{from.ID}
+	depth := map[string]int{from.ID: 0}
+	found := false
+	for len(queue) > 0 && !found {
+		cur := queue[0]
+		queue = queue[1:]
+		if depth[cur] >= maxHops {
+			continue
+		}
+		for _, a := range adj[cur] {
+			if _, seen := prev[a.to]; seen {
+				continue
+			}
+			prev[a.to] = crumb{prev: cur, via: a}
+			depth[a.to] = depth[cur] + 1
+			if a.to == to.ID {
+				found = true
+				break
+			}
+			queue = append(queue, a.to)
+		}
+	}
+	if _, ok := prev[to.ID]; !ok {
+		return nil, fmt.Errorf("no path from %s to %s within %d hops", from.ID, to.ID, maxHops)
+	}
+	idx := g.nodeIndex()
+	var steps []PathStep
+	for cur := to.ID; cur != from.ID; {
+		c := prev[cur]
+		// c.via is the arc stored under c.prev. dir=="out" means the real edge runs
+		// prev→cur (we traverse it forward); dir=="in" means it runs cur→prev (we
+		// traverse it backward).
+		dir := "forward"
+		if c.via.dir == "in" {
+			dir = "backward"
+		}
+		steps = append(steps, PathStep{Relation: c.via.relation, Direction: dir, Node: *idx[cur]})
+		cur = c.prev
+	}
+	// steps were collected target→source; reverse to source→target order.
+	for i, j := 0, len(steps)-1; i < j; i, j = i+1, j-1 {
+		steps[i], steps[j] = steps[j], steps[i]
+	}
+	return &PathResult{From: *from, To: *to, Steps: steps}, nil
+}
+
+// ExplainConnection is one neighbor in an explain result, with the neighbor's own
+// degree (so connections can be ordered by hub-ness).
+type ExplainConnection struct {
+	Direction string `json:"direction"`
+	Relation  string `json:"relation"`
+	Node      Node   `json:"node"`
+	Degree    int    `json:"degree"`
+}
+
+// ExplainResult is a node plus its connections ordered by neighbor degree.
+type ExplainResult struct {
+	Node        Node                `json:"node"`
+	Connections []ExplainConnection `json:"connections"`
+}
+
+// Explain returns the node label resolves to plus its connections ordered by
+// neighbor degree, descending (R2.3).
+func Explain(g *Graph, label string) (*ExplainResult, error) {
+	n, ok := resolveNode(g, label)
+	if !ok {
+		return nil, fmt.Errorf("no node matches %q", label)
+	}
+	deg := degreeMap(g)
+	idx := g.nodeIndex()
+	adj := buildAdjacency(g)
+	var conns []ExplainConnection
+	seen := map[string]bool{}
+	for _, a := range adj[n.ID] {
+		key := a.dir + "|" + a.relation + "|" + a.to
+		if seen[key] {
+			continue
+		}
+		seen[key] = true
+		nb := idx[a.to]
+		if nb == nil {
+			continue
+		}
+		conns = append(conns, ExplainConnection{
+			Direction: a.dir, Relation: a.relation, Node: *nb, Degree: deg[a.to],
+		})
+	}
+	sort.SliceStable(conns, func(i, j int) bool {
+		if conns[i].Degree != conns[j].Degree {
+			return conns[i].Degree > conns[j].Degree
+		}
+		if conns[i].Relation != conns[j].Relation {
+			return conns[i].Relation < conns[j].Relation
+		}
+		return conns[i].Node.ID < conns[j].Node.ID
+	})
+	return &ExplainResult{Node: *n, Connections: conns}, nil
+}
+
+func degreeMap(g *Graph) map[string]int {
+	deg := map[string]int{}
+	for _, e := range g.Links {
+		deg[e.Source]++
+		deg[e.Target]++
+	}
+	return deg
+}
+
+// resolveNode maps a user query (an ID or a label) to a single node, using the
+// same tiers as Query and breaking ties by ID for determinism.
+func resolveNode(g *Graph, query string) (*Node, bool) {
+	q := NormalizeID(query)
+	if q == "" {
+		return nil, false
+	}
+	best := -1
+	bestRank := 99
+	for i := range g.Nodes {
+		tier := labelTier(g.Nodes[i], q)
+		if tier == "" {
+			continue
+		}
+		r := tierRank(tier)
+		if r < bestRank || (r == bestRank && (best < 0 || g.Nodes[i].ID < g.Nodes[best].ID)) {
+			bestRank = r
+			best = i
+		}
+	}
+	if best < 0 {
+		return nil, false
+	}
+	return &g.Nodes[best], true
+}
diff --git a/internal/graph/query_test.go b/internal/graph/query_test.go
new file mode 100644
index 0000000..5b51a7e
--- /dev/null
+++ b/internal/graph/query_test.go
@@ -0,0 +1,79 @@
+package graph
+
+import "testing"
+
+func TestQueryTiers(t *testing.T) {
+	g, _ := buildFixture(t)
+
+	// Exact label match beats substring; results are deterministic.
+	matches := Query(g, "AlbumService", QueryOptions{})
+	if len(matches) == 0 {
+		t.Fatal("expected AlbumService match")
+	}
+	if matches[0].Node.ID != designID("photos", "AlbumService") {
+		t.Fatalf("expected AlbumService first; got %s", matches[0].Node.ID)
+	}
+	if matches[0].Tier != tierExact {
+		t.Errorf("expected exact tier; got %s", matches[0].Tier)
+	}
+	// The neighborhood is populated (1-hop).
+	if len(matches[0].Neighbors) == 0 {
+		t.Errorf("expected neighbors for AlbumService")
+	}
+
+	// Prefix vs substring ordering: "Upload" matches task 1's label as a prefix.
+	up := Query(g, "Implement", QueryOptions{})
+	if len(up) == 0 || up[0].Tier != tierPrefix {
+		t.Errorf("expected a prefix match for 'Implement'; got %+v", up)
+	}
+
+	// Determinism: same query twice yields identical ordering.
+	a := Query(g, "e", QueryOptions{})
+	b := Query(g, "e", QueryOptions{})
+	if len(a) != len(b) {
+		t.Fatalf("nondeterministic length")
+	}
+	for i := range a {
+		if a[i].Node.ID != b[i].Node.ID {
+			t.Fatalf("nondeterministic order at %d", i)
+		}
+	}
+}
+
+func TestPath(t *testing.T) {
+	g, _ := buildFixture(t)
+
+	// task 1 → AlbumService is a single in_boundary hop.
+	pr, err := Path(g, "Implement upload", "AlbumService", 0)
+	if err != nil {
+		t.Fatalf("path: %v", err)
+	}
+	if len(pr.Steps) != 1 {
+		t.Fatalf("expected 1 step; got %d (%+v)", len(pr.Steps), pr.Steps)
+	}
+	if pr.Steps[0].Relation != RelInBoundary || pr.Steps[0].Direction != "forward" {
+		t.Errorf("expected forward in_boundary; got %+v", pr.Steps[0])
+	}
+
+	// A→B resolving to the same node is an error (R2.2).
+	if _, err := Path(g, "AlbumService", "AlbumService", 0); err == nil {
+		t.Error("expected error for identical endpoints")
+	}
+}
+
+func TestExplain(t *testing.T) {
+	g, _ := buildFixture(t)
+	er, err := Explain(g, "AlbumService")
+	if err != nil {
+		t.Fatalf("explain: %v", err)
+	}
+	if er.Node.ID != designID("photos", "AlbumService") {
+		t.Fatalf("wrong node: %s", er.Node.ID)
+	}
+	// Connections are ordered by neighbor degree, descending.
+	for i := 1; i < len(er.Connections); i++ {
+		if er.Connections[i-1].Degree < er.Connections[i].Degree {
+			t.Errorf("connections not ordered by degree: %+v", er.Connections)
+		}
+	}
+}
diff --git a/internal/graph/scale_test.go b/internal/graph/scale_test.go
new file mode 100644
index 0000000..028f321
--- /dev/null
+++ b/internal/graph/scale_test.go
@@ -0,0 +1,141 @@
+package graph
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestQueryIDFRanking checks that a rare term outweighs a common one: a node
+// matching only the rare term ranks above a node matching only the common term
+// (R13.1 tier×IDF scoring).
+func TestQueryIDFRanking(t *testing.T) {
+	g := New()
+	// "apple" appears in many labels (low IDF); "zebra" in exactly one (high IDF).
+	for i := 0; i < 12; i++ {
+		g.Nodes = append(g.Nodes, Node{ID: MakeID("apple", itoa(i)), Label: fmt.Sprintf("apple item %d", i), FileType: TypeTask})
+	}
+	g.Nodes = append(g.Nodes, Node{ID: "zebra_solo", Label: "zebra solo", FileType: TypeTask})
+
+	matches := Query(g, "zebra apple", QueryOptions{Budget: 100000})
+	if len(matches) == 0 {
+		t.Fatal("expected matches")
+	}
+	if matches[0].Node.ID != "zebra_solo" {
+		t.Fatalf("rare-term node should rank first (IDF); got %s", matches[0].Node.ID)
+	}
+}
+
+// TestQueryBudget checks that a tight token budget truncates results (R13.1).
+func TestQueryBudget(t *testing.T) {
+	g := New()
+	for i := 0; i < 40; i++ {
+		g.Nodes = append(g.Nodes, Node{ID: MakeID("node", itoa(i)), Label: fmt.Sprintf("node number %d here", i), FileType: TypeTask})
+	}
+	big := Query(g, "node", QueryOptions{Budget: 100000})
+	small := Query(g, "node", QueryOptions{Budget: 30})
+	if len(small) == 0 {
+		t.Fatal("budget should still return at least one match")
+	}
+	if len(small) >= len(big) {
+		t.Fatalf("small budget (%d) should return fewer matches than large (%d)", len(small), len(big))
+	}
+}
+
+// TestQueryHubGating checks that BFS does not expand *through* a super-hub: the
+// hub is a neighbor of a leaf, but the hub's other leaves are not pulled in at
+// 2 hops (R13.1 hub-gating, floor 50).
+func TestQueryHubGating(t *testing.T) {
+	g := New()
+	g.Nodes = append(g.Nodes, Node{ID: "hub", Label: "central hub", FileType: TypeDesign})
+	for i := 0; i < 60; i++ {
+		leaf := MakeID("leaf", itoa(i))
+		g.Nodes = append(g.Nodes, Node{ID: leaf, Label: fmt.Sprintf("leaf %d", i), FileType: TypeTask})
+		g.Links = append(g.Links, Edge{Source: "hub", Target: leaf, Relation: RelContains, Confidence: Extracted, ConfidenceScore: 1})
+	}
+	// Query leaf 0 with 2 hops. Without gating, leaf0→hub→(59 other leaves).
+	matches := Query(g, "leaf 0", QueryOptions{Hops: 2, Budget: 1000000})
+	var leaf0 *Match
+	for i := range matches {
+		if matches[i].Node.ID == MakeID("leaf", "0") {
+			leaf0 = &matches[i]
+			break
+		}
+	}
+	if leaf0 == nil {
+		t.Fatal("leaf 0 not matched")
+	}
+	sawHub, sawOtherLeaf := false, false
+	for _, nb := range leaf0.Neighbors {
+		if nb.Node.ID == "hub" {
+			sawHub = true
+		}
+		if nb.Node.ID == MakeID("leaf", "5") {
+			sawOtherLeaf = true
+		}
+	}
+	if !sawHub {
+		t.Errorf("hub should be a direct neighbor of leaf 0")
+	}
+	if sawOtherLeaf {
+		t.Errorf("hub-gating should stop BFS expanding through the super-hub to other leaves")
+	}
+}
+
+// TestIncrementalByteIdentical checks that an incremental build's output is
+// byte-identical to a full build, on first run and after an edit (R13.3).
+func TestIncrementalByteIdentical(t *testing.T) {
+	dir := t.TempDir()
+	writeFixture(t, dir)
+
+	full1, err := Build(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fullBytes1, _ := Marshal(full1)
+
+	inc1, err := BuildIncremental(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	incBytes1, _ := Marshal(inc1)
+	if string(fullBytes1) != string(incBytes1) {
+		t.Fatalf("first incremental build differs from full:\n%s\n---\n%s", fullBytes1, incBytes1)
+	}
+
+	// Edit one spec file, then rebuild both ways — still byte-identical.
+	tasks := filepath.Join(dir, "specs", "photos", "tasks.md")
+	edited := "# Tasks\n## Phase 1\n- [ ] 1. Implement upload _Boundary: AlbumService_\n  - _Requirements: 1.1_\n- [ ] 9. New task\n  - _Requirements: 2.1_\n"
+	if err := os.WriteFile(tasks, []byte(edited), 0o644); err != nil {
+		t.Fatal(err)
+	}
+	full2, err := Build(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	fullBytes2, _ := Marshal(full2)
+	inc2, err := BuildIncremental(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	incBytes2, _ := Marshal(inc2)
+	if string(fullBytes2) != string(incBytes2) {
+		t.Fatalf("post-edit incremental build differs from full:\n%s\n---\n%s", fullBytes2, incBytes2)
+	}
+	if string(fullBytes1) == string(fullBytes2) {
+		t.Fatal("edit should have changed the graph")
+	}
+
+	// Delete a source; incremental must prune it and still match full.
+	if err := os.Remove(tasks); err != nil {
+		t.Fatal(err)
+	}
+	full3, _ := Build(dir)
+	fb3, _ := Marshal(full3)
+	inc3, _ := BuildIncremental(dir)
+	ib3, _ := Marshal(inc3)
+	if string(fb3) != string(ib3) {
+		t.Fatalf("post-delete incremental build differs from full")
+	}
+}
diff --git a/internal/paths/paths.go b/internal/paths/paths.go
index e7e5196..a15198f 100644
--- a/internal/paths/paths.go
+++ b/internal/paths/paths.go
@@ -7,9 +7,31 @@ package paths
 
 import "path/filepath"
 
-// ClaudeDir is the marker directory that identifies a workspace root.
+// ClaudeDir is the Claude Code configuration directory. Historically it also
+// marked a csdd workspace root; the marker is moving to StateDir (.csdd/), which
+// csdd owns exclusively (see StateDir).
 const ClaudeDir = ".claude"
 
+// StateDir is csdd's operational-state directory — the csdd analog of .git/. Its
+// presence at the project root is the workspace marker (R15): hash manifests,
+// incremental build state, and caches live here, never knowledge artifacts.
+const StateDir = ".csdd"
+
+// StateManifestSeg is the csdd-managed artifact manifest under .csdd/, migrated
+// from the legacy .claude/.csdd-manifest.json (R14). It drives `csdd update`.
+const StateManifestSeg = "manifest.json"
+
+// Documentation knowledge-base segments under docs/ (R7). docs/graph/ is the only
+// generated subtree; the rest is human/LLM-authored.
+const (
+	DocsSeg      = "docs"
+	DocsPlansSeg = "plans"
+	DocsRawSeg   = "raw"
+	DocsWikiSeg  = "wiki"
+	DocsGraphSeg = "graph"
+	StackSeg     = "stack.md"
+)
+
 // Entry-point files at the workspace root.
 const (
 	EntryFile = "CLAUDE.md" // agent entry point, imports steering via @-references
@@ -64,6 +86,31 @@ func Settings(root string) string { return filepath.Join(root, ClaudeDir, Settin
 // artifacts and their content hashes that `csdd update` reconciles against.
 func Manifest(root string) string { return filepath.Join(root, ClaudeDir, ManifestSeg) }
 
+// State returns the .csdd/ operational-state directory (the workspace marker).
+func State(root string) string { return filepath.Join(root, StateDir) }
+
+// StateManifest returns .csdd/manifest.json, the current home of the csdd-managed
+// artifact manifest.
+func StateManifest(root string) string { return filepath.Join(root, StateDir, StateManifestSeg) }
+
+// Docs returns the repo-root docs/ knowledge-base directory.
+func Docs(root string) string { return filepath.Join(root, DocsSeg) }
+
+// DocsPlans returns docs/plans/.
+func DocsPlans(root string) string { return filepath.Join(root, DocsSeg, DocsPlansSeg) }
+
+// DocsRaw returns docs/raw/, the immutable raw-source dropzone.
+func DocsRaw(root string) string { return filepath.Join(root, DocsSeg, DocsRawSeg) }
+
+// DocsWiki returns docs/wiki/, the LLM-authored structured knowledge base.
+func DocsWiki(root string) string { return filepath.Join(root, DocsSeg, DocsWikiSeg) }
+
+// DocsGraph returns docs/graph/, the only generated subtree in docs/.
+func DocsGraph(root string) string { return filepath.Join(root, DocsSeg, DocsGraphSeg) }
+
+// Stack returns docs/stack.md, the human-authored tech contract.
+func Stack(root string) string { return filepath.Join(root, DocsSeg, StackSeg) }
+
 // MCP returns the repo-root .mcp.json.
 func MCP(root string) string { return filepath.Join(root, MCPFile) }
 
diff --git a/internal/templater/templater.go b/internal/templater/templater.go
index 2e35bb7..66b4b48 100644
--- a/internal/templater/templater.go
+++ b/internal/templater/templater.go
@@ -126,6 +126,43 @@ func CommandFiles(efs fs.FS) (map[string]string, error) {
 	return staticTree(efs, "templates/commands")
 }
 
+// WikiScaffoldFiles returns the LLM-wiki scaffold `csdd wiki init` lays down,
+// keyed by workspace-relative destination path. It is the raw-source dropzone
+// plus the wiki catalog/log skeletons; page content is authored by the LLM, so
+// only docs/wiki/pages/ (a directory) is left for the wiki skill to fill.
+func WikiScaffoldFiles(efs fs.FS) (map[string]string, error) {
+	return renderMapping(efs, map[string]string{
+		"templates/wiki/raw-README.md.tmpl": "docs/raw/README.md",
+		"templates/wiki/index.md.tmpl":      "docs/wiki/index.md",
+		"templates/wiki/log.md.tmpl":        "docs/wiki/log.md",
+	})
+}
+
+// KnowledgeStructureFiles returns the remaining knowledge-base structure files
+// `csdd init` scaffolds: the generated-index README, the state-dir README, and
+// the (empty-of-choices) tech contract. Keyed by workspace-relative path.
+func KnowledgeStructureFiles(efs fs.FS) (map[string]string, error) {
+	return renderMapping(efs, map[string]string{
+		"templates/wiki/graph-README.md.tmpl": "docs/graph/README.md",
+		"templates/wiki/state-README.md.tmpl": ".csdd/README.md",
+		"templates/wiki/stack.md.tmpl":        "docs/stack.md",
+	})
+}
+
+// renderMapping reads each template path and returns a dest→content map with
+// line endings normalized to LF (byte-deterministic scaffolding).
+func renderMapping(efs fs.FS, mapping map[string]string) (map[string]string, error) {
+	out := make(map[string]string, len(mapping))
+	for tpl, dest := range mapping {
+		raw, err := fs.ReadFile(efs, tpl)
+		if err != nil {
+			return nil, err
+		}
+		out[dest] = textutil.NormalizeNewlines(string(raw))
+	}
+	return out, nil
+}
+
 // WorkflowTemplateFiles returns the versioned templates that belong under
 // .claude/templates/. The embedded tree uses implementation-oriented
 // names; this function emits the canonical on-disk layout from the guide.
diff --git a/internal/templater/templates/commands/csdd-graph-analyze.md.tmpl b/internal/templater/templates/commands/csdd-graph-analyze.md.tmpl
new file mode 100644
index 0000000..16e477d
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-graph-analyze.md.tmpl
@@ -0,0 +1,21 @@
+---
+description: Run the mechanical SDD lint over the whole spec — untested criteria, orphan tasks, unimplemented components, pending references, cycles, plus wiki/tech findings.
+argument-hint: [--strict]
+allowed-tools: Bash(csdd graph analyze:*), Bash(npx @protonspy/csdd graph analyze:*), Bash(csdd graph build:*)
+---
+
+## Task
+
+Use the **graph** skill to gate the current work before review/commit:
+
+1. Rebuild first so the analysis reflects the working tree: `csdd graph build`.
+2. Run `csdd graph analyze --strict --json` (append `$ARGUMENTS`). `--strict`
+   exits non-zero when anything is found — treat that as a failing gate.
+3. Walk the `findings` array:
+   - `corpus: spec` — fix untested criteria / orphan tasks / unimplemented
+     components / pending references / dependency cycles at the source artifact.
+   - `corpus: wiki` — hand to the **wiki** skill (Maintain).
+   - `corpus: tech` — hand to the **stack** skill (Reconcile). Do not edit
+     manifests silently.
+4. Report each finding and its resolution, or explicitly flag anything deferred to
+   the human. Do not silently ignore a finding.
diff --git a/internal/templater/templates/commands/csdd-graph-explain.md.tmpl b/internal/templater/templates/commands/csdd-graph-explain.md.tmpl
new file mode 100644
index 0000000..e7ad8a0
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-graph-explain.md.tmpl
@@ -0,0 +1,14 @@
+---
+description: Explain one node in the csdd knowledge graph — its connections ordered by neighbor degree (the local map).
+argument-hint: <node label>
+allowed-tools: Bash(csdd graph explain:*), Bash(npx @protonspy/csdd graph explain:*)
+---
+
+## Task
+
+Use the **graph** skill. For the node named in `$ARGUMENTS`:
+
+1. Run `csdd graph explain "$ARGUMENTS" --json` (or the `npx @protonspy/csdd` form).
+2. Read the node and its connections, ordered by neighbor degree (hubs first).
+3. Report what the node is, what it connects to, and where it sits in the graph —
+   without reading the underlying files unless the graph is insufficient.
diff --git a/internal/templater/templates/commands/csdd-graph-path.md.tmpl b/internal/templater/templates/commands/csdd-graph-path.md.tmpl
new file mode 100644
index 0000000..6c1e6ca
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-graph-path.md.tmpl
@@ -0,0 +1,16 @@
+---
+description: Show the shortest path between two nodes in the csdd knowledge graph — "what connects these, and what breaks if I change one".
+argument-hint: <A> <B>
+allowed-tools: Bash(csdd graph path:*), Bash(npx @protonspy/csdd graph path:*)
+---
+
+## Task
+
+Use the **graph** skill. For the two nodes named in `$ARGUMENTS` (A then B):
+
+1. Run `csdd graph path "<A>" "<B>" --json` (or the `npx @protonspy/csdd` form).
+2. Read the returned steps — each edge with its real direction.
+3. Report the chain and what it implies: what connects A to B, and what would be
+   affected if either changes.
+
+If A and B resolve to the same node the CLI errors — pick more specific labels.
diff --git a/internal/templater/templates/commands/csdd-graph-query.md.tmpl b/internal/templater/templates/commands/csdd-graph-query.md.tmpl
new file mode 100644
index 0000000..9c28c82
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-graph-query.md.tmpl
@@ -0,0 +1,20 @@
+---
+description: Query the csdd knowledge graph for nodes matching terms and their neighborhood (brain-first, before grepping).
+argument-hint: <terms to search for>
+allowed-tools: Bash(csdd graph query:*), Bash(npx @protonspy/csdd graph query:*)
+---
+
+## Task
+
+Use the **graph** skill. Answer `$ARGUMENTS` by consulting the knowledge graph
+instead of grepping or reading source:
+
+1. Run `csdd graph query "$ARGUMENTS" --json` (or `npx @protonspy/csdd graph query …`
+   when csdd is not installed globally).
+2. Read the matched nodes and their 1-hop neighborhood from the JSON.
+3. If you need the chain between two nodes, follow up with `csdd graph path`; for a
+   single node's full local map, `csdd graph explain`.
+4. Report the answer from the graph. Only fall back to reading files when the
+   graph cannot answer.
+
+Never open `docs/graph/graph.json` by hand — query it.
diff --git a/internal/templater/templates/commands/csdd-stack-propose.md.tmpl b/internal/templater/templates/commands/csdd-stack-propose.md.tmpl
new file mode 100644
index 0000000..25cd4db
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-stack-propose.md.tmpl
@@ -0,0 +1,18 @@
+---
+description: Propose a technology decision — present 2-3 options with trade-offs and ask the human before amending the docs/stack.md contract.
+argument-hint: <the need, e.g. "message broker" or "http router">
+allowed-tools: Read, Edit, Bash(csdd graph analyze:*)
+---
+
+## Task
+
+Use the **stack** skill's **Propose** workflow for the need in `$ARGUMENTS`:
+
+1. Confirm the technology is not already a row in `docs/stack.md` **Decided**.
+2. Present **2–3 options with trade-offs** (fit, maturity, ops cost, lock-in).
+3. **Ask the human to choose.** Do not pick for them, and do not adopt anything.
+4. Only after an explicit decision, add the chosen row to the **Decided** table
+   (`| Domain | Choice | Version | Why | Refs |`). Do not edit dependency
+   manifests here — that is a separate, human-authorized code change.
+
+The contract is law: any technology not listed is an open decision.
diff --git a/internal/templater/templates/commands/csdd-stack-refine.md.tmpl b/internal/templater/templates/commands/csdd-stack-refine.md.tmpl
new file mode 100644
index 0000000..238454e
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-stack-refine.md.tmpl
@@ -0,0 +1,20 @@
+---
+description: Refine a contracted library against current docs (Context7 MCP or web), file the findings as a wiki page, and link it in the contract's Refs.
+argument-hint: <library from docs/stack.md>
+allowed-tools: Read, Edit, Write, Bash(npx ctx7:*)
+---
+
+## Task
+
+Use the **stack** skill's **Refine** workflow for the library in `$ARGUMENTS`
+(before its first use in a feature):
+
+1. Run the currency check against **current documentation** — Context7 MCP when
+   configured (`ctx7`/find-docs), else web search. Do not rely on training data
+   for API/config/version details.
+2. Capture the findings as a wiki page `docs/wiki/pages/<library>.md` (via the
+   **wiki** skill, with `sources:` and `tags`).
+3. Link that page in the library's **Refs** column in `docs/stack.md`, and set
+   its **Version** if it was blank.
+4. Report what changed since your prior knowledge, so the implementation uses the
+   library correctly and current.
diff --git a/internal/templater/templates/commands/csdd-wiki-ingest.md.tmpl b/internal/templater/templates/commands/csdd-wiki-ingest.md.tmpl
new file mode 100644
index 0000000..f53fa5a
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-wiki-ingest.md.tmpl
@@ -0,0 +1,19 @@
+---
+description: Ingest a raw source from docs/raw/ into the wiki — read it, write/extend pages with provenance, cross-link, update index + log.
+argument-hint: [docs/raw/<file> or a description of what to ingest]
+allowed-tools: Read, Write, Edit, Bash(csdd wiki lint:*), Bash(csdd graph build:*)
+---
+
+## Task
+
+Use the **wiki** skill's **Ingest** workflow for `$ARGUMENTS` (or the most recent
+file the user dropped into `docs/raw/`):
+
+1. Read the raw source. **Do not modify anything under `docs/raw/`.**
+2. Write or extend pages under `docs/wiki/pages/` capturing its knowledge, each
+   with `title`, `tags`, and `sources: [docs/raw/<file>]` frontmatter.
+3. Add `[[wikilinks]]` to related pages; list the new page in `docs/wiki/index.md`.
+4. Append `## [YYYY-MM-DD] ingest | <title>` to `docs/wiki/log.md`.
+5. Rebuild and check: `csdd graph build` then `csdd wiki lint` (must be clean).
+
+Never restate spec/code internals — link to them.
diff --git a/internal/templater/templates/commands/csdd-wiki-lint.md.tmpl b/internal/templater/templates/commands/csdd-wiki-lint.md.tmpl
new file mode 100644
index 0000000..ab15c2f
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-wiki-lint.md.tmpl
@@ -0,0 +1,18 @@
+---
+description: Run the deterministic wiki health check — broken wikilinks, orphan pages, index/log desync, unprocessed raw sources — and fix what it finds.
+argument-hint: [--json]
+allowed-tools: Bash(csdd wiki lint:*), Bash(npx @protonspy/csdd wiki lint:*), Read, Write, Edit
+---
+
+## Task
+
+Use the **wiki** skill's **Maintain** workflow:
+
+1. Run `csdd wiki lint --json` (append `$ARGUMENTS`). It exits non-zero when
+   anything is found.
+2. Fix each finding at the source:
+   - broken `[[wikilink]]` → correct the target or create the page.
+   - orphan page / index desync → list it in `index.md` (or link it from a page).
+   - malformed `log.md` entry → rewrite it as `## [YYYY-MM-DD] <op> | <title>`.
+   - **unprocessed raw source** → run the **Ingest** workflow for it.
+3. Re-run `csdd wiki lint` until it is clean (exit 0). Report what you fixed.
diff --git a/internal/templater/templates/commands/csdd-wiki-query.md.tmpl b/internal/templater/templates/commands/csdd-wiki-query.md.tmpl
new file mode 100644
index 0000000..105f5c6
--- /dev/null
+++ b/internal/templater/templates/commands/csdd-wiki-query.md.tmpl
@@ -0,0 +1,17 @@
+---
+description: Answer a question from the accumulated wiki knowledge — read index + pages, use the graph for structure, synthesize with citations.
+argument-hint: <question>
+allowed-tools: Read, Bash(csdd graph query:*), Bash(csdd graph explain:*), Write
+---
+
+## Task
+
+Use the **wiki** skill's **Query** workflow to answer `$ARGUMENTS`:
+
+1. Read `docs/wiki/index.md`, then drill into the relevant pages.
+2. For structural questions, run `csdd graph query`/`explain` (the wiki is part of
+   the same graph).
+3. Synthesize an answer **with citations** to the pages/sources you used.
+4. If the synthesis is worth keeping, file it back as a new page under
+   `docs/wiki/pages/` (with `sources:`), list it in `index.md`, and append
+   `## [YYYY-MM-DD] query | <title>` to `log.md` — explorations compound.
diff --git a/internal/templater/templates/root/CLAUDE.md.tmpl b/internal/templater/templates/root/CLAUDE.md.tmpl
index c3607ac..b322dec 100644
--- a/internal/templater/templates/root/CLAUDE.md.tmpl
+++ b/internal/templater/templates/root/CLAUDE.md.tmpl
@@ -226,6 +226,16 @@ commits or PRs.
 Escalate to a human when a feature touches auth, payments, PII, or regulated
 data; when a change needs `--force` past a gate; or before anything destructive.
 
+## Knowledge base — graph, wiki, tech contract
+
+The workflow moments for the knowledge base (consult the graph before searching;
+rebuild after changes; ingest raw sources; gate with `analyze`/`wiki lint`) and
+the tech-contract protocol live in the managed block below. `csdd init` keeps it
+in sync — do not hand-edit between the markers.
+
+<!-- csdd:knowledge:start -->
+<!-- csdd:knowledge:end -->
+
 ## Project memory (steering)
 
 Steering files are always-on project memory, loaded via the `@`-imports below.
diff --git a/internal/templater/templates/root/knowledge-section.md.tmpl b/internal/templater/templates/root/knowledge-section.md.tmpl
new file mode 100644
index 0000000..4312a8c
--- /dev/null
+++ b/internal/templater/templates/root/knowledge-section.md.tmpl
@@ -0,0 +1,32 @@
+The workspace carries a **knowledge base** — a graph brain and an LLM-wiki — plus
+a **tech contract**. Drive them through the CLI (or `npx @protonspy/csdd …`); the CLI
+is the only author of `docs/graph/` and `.csdd/`, and nothing ever edits
+`docs/raw/`.
+
+**Workflow moments — do these without being asked:**
+
+- **Consult the graph before searching.** Before you grep or read source to
+  understand structure, query the brain: `csdd graph query "<terms>"`,
+  `csdd graph explain "<label>"`, `csdd graph path "<A>" "<B>"`. Understanding
+  should come from traversing relationships, not re-reading files.
+- **Rebuild after changing** specs, tasks, `.claude/`, `docs/`, or `.go` files:
+  `csdd graph build` (byte-stable output — commit it with the change).
+- **Ingest raw sources.** When a file lands in `docs/raw/`, run the `wiki` skill's
+  **Ingest** workflow: read it, write/extend pages under `docs/wiki/pages/` with
+  `sources:` provenance, cross-link, update `index.md` + `log.md`.
+- **Gate before commit/PR:** `csdd graph analyze --strict` (SDD + tech lints) and
+  `csdd wiki lint` (wiki health) must be clean.
+
+**The tech contract (`docs/stack.md`) is law.** Any technology **not** listed
+there is an **open decision**: propose 2–3 options with trade-offs and **ask the
+human** before adopting — never introduce a dependency silently (this is what
+stops assuming Redis when the decision was RabbitMQ). Before the first use of a
+listed library in a feature, **refine** it against current documentation
+(Context7 MCP when configured, else web search) and file the findings as a wiki
+page linked from that row's **Refs** column. Use the **stack** skill for all of
+this.
+
+**Invoke the `stack` skill whenever:** a new dependency or technology is about to
+enter the project; `csdd graph analyze` reports a tech finding
+(`undeclared`/`phantom`/`unrefined`); or the user mentions adopting or changing
+technology.
diff --git a/internal/templater/templates/rules/knowledge-base.md.tmpl b/internal/templater/templates/rules/knowledge-base.md.tmpl
new file mode 100644
index 0000000..2f01c70
--- /dev/null
+++ b/internal/templater/templates/rules/knowledge-base.md.tmpl
@@ -0,0 +1,26 @@
+# Knowledge base — consult it before searching
+
+csdd maintains a **knowledge base** in two cooperating halves. Use it; do not
+re-derive what it already holds.
+
+- **The graph** (`docs/graph/graph.json`, built by `csdd graph build`) is a
+  structured brain over specs, `.claude/`, `docs/`, the tech contract, and the Go
+  source. **Before you grep or read code** to understand structure, query it:
+  `csdd graph query "<terms>"`, `csdd graph explain "<label>"`,
+  `csdd graph path "<A>" "<B>"`. Understanding should come from traversing
+  relationships, not from re-reading files.
+- **The wiki** (`docs/wiki/`, authored via the `wiki` skill from immutable sources
+  in `docs/raw/`) is the prose knowledge base. **Read `docs/wiki/index.md`** before
+  searching the docs.
+
+Discipline:
+
+- **Rebuild after you change** specs, tasks, `.claude/`, `docs/`, or `.go` files:
+  `csdd graph build` (byte-stable; commit the regenerated `graph.json` with the
+  change).
+- **Gate before review/commit**: `csdd graph analyze --strict` (SDD + tech lints)
+  and `csdd wiki lint` (wiki health) must be clean.
+- **The CLI is the only author of `docs/graph/` and `.csdd/`.** Never hand-edit
+  them; never modify `docs/raw/`.
+- A new dependency or technology is an **open decision** — use the `stack` skill:
+  propose options, ask, and only then amend `docs/stack.md`.
diff --git a/internal/templater/templates/skills/graph/SKILL.md.tmpl b/internal/templater/templates/skills/graph/SKILL.md.tmpl
new file mode 100644
index 0000000..6b49cd9
--- /dev/null
+++ b/internal/templater/templates/skills/graph/SKILL.md.tmpl
@@ -0,0 +1,85 @@
+---
+name: graph
+description: Use to consult or refresh the csdd knowledge graph — before grepping/reading code to understand structure, after editing specs/tasks/code, and before review/commit. Drives everything through the `csdd graph` CLI; never writes docs/graph/ or .csdd/ directly.
+---
+
+# Graph — the structured brain
+
+## Goal
+
+Understand and govern the workspace by **querying its structure**, not by reading
+all of it. The graph is a deterministic, persistent index of every csdd artifact,
+the docs/ knowledge base, the tech contract, and (once present) the Go source —
+queried in milliseconds, answered within a token budget. Reach for it *before*
+grep/read and *before* review, so comprehension comes from traversing
+relationships (a few hundred tokens) instead of re-reading files (hundreds of
+thousands).
+
+The CLI is the **single mutation path** for the graph. This skill only ever
+*runs* `csdd graph …` (or `npx @protonspy/csdd graph …` when csdd is not installed
+globally). It never edits `docs/graph/` or `.csdd/` by hand — those are generated.
+
+## Execution Workflow
+
+Pick the moment, run the command, read the output — do not open `graph.json`.
+
+1. **Consult before searching (the brain-first habit).** Before you grep or read
+   source to answer "what depends on X?", "what implements Y?", "where are the
+   hubs?", ask the graph:
+   - `csdd graph query "<terms>" --json` — nodes matching a label, with their
+     1-hop neighborhood. Start here for "what is X and what touches it".
+   - `csdd graph explain "<label>" --json` — one node plus its connections
+     ordered by neighbor degree (the local map).
+   - `csdd graph path "<A>" "<B>" --json` — the shortest chain between two nodes
+     (e.g. a requirement and a code file): "what connects these, and what breaks
+     if I change it".
+2. **Rebuild after editing specs, tasks, or code.** Any change to `specs/`,
+   `.claude/`, `docs/`, or `.go` files makes the index stale:
+   - `csdd graph build` — full deterministic rebuild of `docs/graph/graph.json`
+     (+ one line appended to `docs/graph/log.md`). Byte-stable for an unchanged
+     corpus, so commit the result with the change that caused it.
+3. **Analyze before review or commit.** Run the mechanical SDD lint and treat it
+   as a gate:
+   - `csdd graph analyze --strict --json` — untested criteria, orphan tasks,
+     unimplemented components, pending references, dependency cycles, plus wiki
+     and tech findings. `--strict` exits non-zero, so it fails a pre-commit check.
+
+### Consuming `--json`
+
+Every subcommand takes `--json` and prints a machine-readable object on stdout
+(diagnostics go to stderr). Parse that instead of scraping the human table.
+`analyze --json` returns `{ "findings": [ {kind, corpus, node_id, label,
+message, file} ], "god_nodes": [...] }`; filter `corpus` to focus on `spec`,
+`wiki`, or `tech`.
+
+## Gotchas
+
+- **Never hand-edit `docs/graph/` or `.csdd/`.** They are generated; edits are
+  overwritten on the next `build` and corrupt the byte-stable diff. Change the
+  *source* artifact and rebuild.
+- **`analyze` reflects the live corpus, not the last committed `graph.json`.** It
+  rebuilds in memory, so it is always current — but that means a green `analyze`
+  needs the same working tree the reviewer will see.
+- **Range shorthand is a parse error.** `_Requirements: 3.1-3.5_` is reported,
+  not expanded. List IDs explicitly: `3.1, 3.2, 3.3, 3.4, 3.5`.
+- **A pending reference is a real gap, not noise.** It means an annotation points
+  at an ID that does not exist — fix the annotation or add the missing artifact.
+- **Tech findings route to the stack skill.** `undeclared_tech`,`phantom_tech`,
+  and `unrefined_tech` are contract issues — hand them to the `stack` skill's
+  Reconcile workflow, do not silently edit manifests.
+
+## Verification Before Reporting
+
+- You ran the actual `csdd graph …` command this session and read its output —
+  never report graph facts from memory or a stale `graph.json`.
+- Before claiming the contract is clean, `csdd graph analyze --strict` exited 0.
+- After any spec/task/code edit you intend to commit, `csdd graph build` ran and
+  the regenerated `docs/graph/graph.json` is staged alongside the change.
+
+## Completion Criteria
+
+- The question was answered by a graph query/path/explain, not by re-reading
+  source, whenever the graph could answer it.
+- `docs/graph/graph.json` is current with the working tree (rebuilt after edits).
+- `analyze` findings are either resolved or explicitly acknowledged to the human;
+  none were silently ignored.
diff --git a/internal/templater/templates/skills/stack/SKILL.md.tmpl b/internal/templater/templates/skills/stack/SKILL.md.tmpl
new file mode 100644
index 0000000..4dc95ef
--- /dev/null
+++ b/internal/templater/templates/skills/stack/SKILL.md.tmpl
@@ -0,0 +1,83 @@
+---
+name: stack
+description: Use whenever a new dependency/technology is about to enter the project, when `csdd graph analyze` reports tech findings, or when the user mentions adopting or changing technology. Owns the docs/stack.md contract — Propose, Refine, Reconcile — behind a human-decision gate. Never edits manifests or adopts tech without approval.
+---
+
+# Stack — the tech contract
+
+## Goal
+
+Keep **stack/library/framework decisions the human's**, written down in
+`docs/stack.md` as a contract the agent must follow — so architectural choices
+stay deliberate, libraries are used current and correctly, and silent tech
+decisions (assuming Redis when the decision was RabbitMQ) stop happening.
+
+**The contract is law.** Any technology not listed in `docs/stack.md` is an
+**open decision** — you propose options and ask; you do not adopt. This skill
+never edits dependency manifests and never adopts a technology without an
+explicit human decision.
+
+## The contract file
+
+`docs/stack.md` has three sections:
+- **Decided** — a parseable table `| Domain | Choice | Version | Why | Refs |`.
+  Each row is indexed as a `tech` node and matched against declared dependencies.
+- **Rules** — the decision protocol (pre-filled; see below).
+- **Open questions** — pending decisions.
+
+## Execution Workflow
+
+Three workflows, each gated on a human decision.
+
+1. **Propose** (a new tech need appears):
+   - Identify the need (broker, cache, router, ORM, …).
+   - Present **2–3 options with trade-offs** (fit, maturity, ops cost, lock-in).
+   - **Ask the human to choose.** Do not pick for them.
+   - Only *after* approval, amend the **Decided** table with the chosen row
+     (Domain, Choice, Version, Why, Refs). Add nothing to manifests yourself
+     beyond what the human authorized.
+2. **Refine** (before first use of a contracted library in a feature):
+   - Run the currency check against **current documentation** — Context7 MCP when
+     configured (`ctx7`/find-docs), else web search. Never rely on training data
+     for API details, config, or version specifics.
+   - File the findings as a wiki page (`docs/wiki/pages/<lib>.md`, via the wiki
+     skill) and link it in that row's **Refs** column.
+3. **Reconcile** (react to `csdd graph analyze` tech findings):
+   - `undeclared_tech` → a dependency is used but absent from the contract:
+     **Propose** it (options + ask) or remove the dependency. This is the
+     Celery+Redis catcher — do not just add the row silently.
+   - `phantom_tech` → a contract entry with no detected usage: confirm intent
+     (planned?) or drop the entry.
+   - `unrefined_tech` → a contract entry missing Version or Refs: run **Refine**.
+
+## Gotchas
+
+- **Never adopt or swap technology without an explicit human decision.** Options
+  and a question first; amendment only after approval.
+- **Never edit dependency manifests** (`go.mod`, `package.json`,
+  `pyproject.toml`, `requirements.txt`) as part of this skill — that is a code
+  change the human authorizes separately.
+- **Match names so lints resolve.** The contract `Choice` is matched to a
+  dependency by normalized short name (`chi` ↔ `github.com/go-chi/chi/v5`). Name
+  the choice to match the library, or the lints misfire.
+- **Refine uses live docs, not memory.** Context7 MCP when available, else web
+  search — then record what you found as a wiki page in Refs.
+- **No `docs/stack.md` is a lint finding, not an error.** Adoption is
+  incremental; scaffold it with `csdd init` (or create it) when the project is
+  ready to commit its stack.
+
+## Verification Before Reporting
+
+- Any technology you are about to introduce is either already in the **Decided**
+  table, or you presented options and the human explicitly chose.
+- After amending the contract, `csdd graph analyze` no longer reports the tech
+  finding you were resolving.
+- Refined entries carry a **Refs** link to a wiki page built from current docs.
+
+## Completion Criteria
+
+- Every technology in play is a human-approved row in `docs/stack.md`; no silent
+  additions.
+- `analyze` tech findings are resolved (Propose/confirm/drop/Refine) or explicitly
+  deferred to the human in Open questions.
+- No manifest was edited and no library was adopted without an explicit decision.
diff --git a/internal/templater/templates/skills/wiki/SKILL.md.tmpl b/internal/templater/templates/skills/wiki/SKILL.md.tmpl
new file mode 100644
index 0000000..b2cc7cd
--- /dev/null
+++ b/internal/templater/templates/skills/wiki/SKILL.md.tmpl
@@ -0,0 +1,84 @@
+---
+name: wiki
+description: Use to build and maintain the docs/ knowledge base from raw sources — when the user drops a file into docs/raw/ (Ingest), when answering from accumulated knowledge (Query), or when keeping the wiki healthy (Maintain). You author the prose; the CLI scaffolds and lints deterministically.
+---
+
+# Wiki — the LLM-authored knowledge base
+
+## Goal
+
+Turn whatever the user drops into `docs/raw/` (articles, notes, transcripts,
+clippings — immutable, never edited) into a **solid, structured, interlinked
+markdown knowledge base** under `docs/wiki/` that is cheap for an LLM to consume.
+This is Karpathy's LLM-wiki pattern instantiated on csdd: **you author content**;
+the **CLI scaffolds and lints** (`csdd wiki init|lint`) but never writes prose and
+never touches `docs/raw/`.
+
+**Boundary (do not cross):** the wiki is a knowledge base built from
+`docs/raw/` — it is **not** documentation *of the specs*. `specs/` holds
+per-feature contracts; the wiki holds knowledge. When a page must mention project
+internals, **link** to them (a path or `[[wikilink]]`) — never restate them.
+Duplicated text is drift waiting to happen and a Maintain finding.
+
+## Page conventions
+
+- **One concept per page**, under `docs/wiki/pages/<slug>.md`.
+- **Frontmatter**: `title`, `tags: [..]`, and — crucially — `sources: [docs/raw/<file>]`
+  for provenance (every page records the raw source it was derived from).
+- **`[[wikilinks]]`** connect related pages. `[[Page Title]]`, `[[slug|alias]]`,
+  and `[[slug#anchor]]` all resolve to the page whose filename matches the slug.
+- **`index.md`** is the catalog (every page is listed under a category);
+  **`log.md`** is the append-only chronology.
+
+## Execution Workflow
+
+Three workflows. Deterministic structure comes from the CLI; judgment is yours.
+
+1. **Ingest** (a source landed in `docs/raw/`):
+   - Read the raw file. Do **not** modify it.
+   - Write or extend pages under `docs/wiki/pages/` capturing its knowledge, with
+     `sources:` pointing back at the raw file (this creates the `derived_from`
+     provenance edge that clears the "unprocessed source" lint).
+   - Add `[[wikilinks]]` to related pages; add the new page to `index.md` under
+     the right category.
+   - Append a `log.md` entry: `## [YYYY-MM-DD] ingest | <title>`.
+2. **Query** (answer from accumulated knowledge):
+   - Read `index.md`, drill into the relevant pages, and — for structural
+     questions — run `csdd graph query`/`explain` (the wiki is part of the same
+     graph). Synthesize with citations.
+   - When the synthesis is worth keeping, file it back as a new page (explorations
+     compound). Append `## [YYYY-MM-DD] query | <title>`.
+3. **Maintain** (keep it healthy):
+   - Run `csdd wiki lint` and fix every finding — broken `[[wikilinks]]`, orphan
+     pages, index desync, malformed `log.md` entries, and **unprocessed raw
+     sources** (Ingest them).
+   - Look for contradictions or stale claims between pages; reconcile them.
+   - Append `## [YYYY-MM-DD] refactor | <what changed>`.
+
+## Gotchas
+
+- **Never edit `docs/raw/`.** It is immutable input for everyone — CLI, LLM, and
+  (by convention) the user only adds, never rewrites.
+- **Never restate spec/code content.** Link to it. A page that duplicates
+  internals is a Maintain finding the moment the source changes.
+- **`sources:` is not optional.** A page without it reads as knowledge from
+  nowhere and leaves its raw source flagged "unprocessed".
+- **`log.md` format is linted.** Entries must be exactly
+  `## [YYYY-MM-DD] <op> | <title>` with `op ∈ ingest|query|lint|refactor`.
+- **The CLI is the only author of `docs/graph/`.** Rebuild with `csdd graph build`
+  after ingesting so the wiki corpus is reflected in the graph.
+
+## Verification Before Reporting
+
+- `csdd wiki lint` ran this session and reports **no findings** (exit 0), or every
+  finding is explicitly acknowledged to the human.
+- Every new/edited page carries `title` and `sources:` frontmatter and is listed
+  in `index.md`.
+- A `log.md` entry was appended for the operation, in the documented format.
+
+## Completion Criteria
+
+- New knowledge from `docs/raw/` is captured in `docs/wiki/pages/` with provenance
+  and cross-links; nothing under `docs/raw/` was modified.
+- `index.md` and `log.md` are in sync with the pages on disk (lint clean).
+- No page restates spec/code content — internals are linked, not duplicated.
diff --git a/internal/templater/templates/wiki/graph-README.md.tmpl b/internal/templater/templates/wiki/graph-README.md.tmpl
new file mode 100644
index 0000000..1a57041
--- /dev/null
+++ b/internal/templater/templates/wiki/graph-README.md.tmpl
@@ -0,0 +1,38 @@
+# `docs/graph/` — the knowledge-base index (generated)
+
+> **Generated by the csdd CLI — do not edit by hand.** This is the **only
+> generated subtree inside `docs/`**. Everything else under `docs/` is
+> human/LLM-authored; everything here is rebuilt deterministically by
+> `csdd graph build`.
+
+This directory holds the **structured brain** of the project: a persistent
+knowledge graph an LLM queries to understand the codebase without reading all of
+it — fast, token-cheap, precise. It lives inside `docs/` because it *is* knowledge
+(committed, shared, reviewed in PRs); csdd's machine state lives in `.csdd/`.
+
+## What lives here
+
+| File | Purpose | Writer |
+|------|---------|--------|
+| `graph.json` | The knowledge graph (NetworkX node-link, graphify-interoperable). | `csdd graph build` |
+| `graph.html` | Self-contained interactive visualization. | `csdd graph export` |
+| `log.md` | Append-only chronological record of builds. | every build |
+
+## The graph model
+
+One node per artifact/entity; one edge per relationship. Node IDs are canonical
+and deterministic (NFKC → non-word→`_` → casefold), so the same artifact always
+yields the same node ID across rebuilds. Every node carries
+`{id, label, file_type, source_file, source_location}`; every edge carries
+`{source, target, relation, confidence, confidence_score, source_file}`.
+
+**Confidence:** `EXTRACTED` (explicit annotation / exact cited path, 1.0) ·
+`INFERRED` (resolved by name/path match, 0.55–0.95) · `AMBIGUOUS` (surfaced for
+the human gate, 0.1–0.3).
+
+## Consume it, don't read it
+
+Query the graph with `csdd graph query|path|explain`, lint it with
+`csdd graph analyze`. The JSON is byte-stable for an unchanged corpus (total
+deterministic ordering), so it diffs cleanly in PRs. Everything in `docs/` —
+including this generated directory — is committed.
diff --git a/internal/templater/templates/wiki/index.md.tmpl b/internal/templater/templates/wiki/index.md.tmpl
new file mode 100644
index 0000000..3677935
--- /dev/null
+++ b/internal/templater/templates/wiki/index.md.tmpl
@@ -0,0 +1,20 @@
+# Wiki index
+
+The catalog of the knowledge base. Every page under `pages/` is listed here,
+grouped by category. `csdd wiki lint` flags pages missing from this index and
+index entries pointing at missing files.
+
+> **Entry format:** `- [Page Title](pages/<slug>.md) — one-line summary`.
+> Keep entries under the right category heading; add categories as the base grows.
+
+## Concepts
+
+<!-- - [Example Concept](pages/example-concept.md) — what it is, in one line. -->
+
+## Guides
+
+<!-- - [Example Guide](pages/example-guide.md) — how to do X. -->
+
+## References
+
+<!-- - [Example Reference](pages/example-reference.md) — pinned facts / API notes. -->
diff --git a/internal/templater/templates/wiki/log.md.tmpl b/internal/templater/templates/wiki/log.md.tmpl
new file mode 100644
index 0000000..7d2fc9d
--- /dev/null
+++ b/internal/templater/templates/wiki/log.md.tmpl
@@ -0,0 +1,16 @@
+# Wiki log
+
+Append-only chronology of knowledge-base operations. One heading per operation.
+`csdd wiki lint` flags any `## [` heading that does not match the format below.
+
+> **Entry format:** `## [YYYY-MM-DD] <op> | <title>` where
+> `op ∈ ingest | query | lint | refactor`. `grep "^## \[" log.md | tail -5` must
+> always list the five most recent operations.
+
+<!-- Newest entries at the bottom. Example:
+
+## [2026-01-01] ingest | Payment webhooks overview
+
+Ingested docs/raw/stripe-webhooks.md into pages/payment-webhooks.md; linked from
+[[payments]]; added to index under Concepts.
+-->
diff --git a/internal/templater/templates/wiki/raw-README.md.tmpl b/internal/templater/templates/wiki/raw-README.md.tmpl
new file mode 100644
index 0000000..a081a2e
--- /dev/null
+++ b/internal/templater/templates/wiki/raw-README.md.tmpl
@@ -0,0 +1,17 @@
+# `docs/raw/` — the raw-source dropzone (immutable)
+
+Drop sources here **verbatim**: articles, notes, transcripts, clippings, exported
+threads — anything you want turned into knowledge. One rule:
+
+> **Nothing here is ever edited — not by the CLI, not by the LLM.** Raw sources
+> are immutable input. You only ever *add* files.
+
+The `wiki` skill's **Ingest** workflow reads what you drop here and writes
+structured, interlinked pages under `docs/wiki/pages/`, recording provenance with
+a `sources:` frontmatter entry pointing back at the raw file. Until a page derives
+from a raw file, `csdd wiki lint` flags it as an **unprocessed source** — so
+nothing you drop is silently forgotten.
+
+The graph indexes each file here as an opaque `raw_source` node (path only; the
+content is never parsed). Its purpose in the graph is provenance (`derived_from`
+targets) and the unprocessed-source lint.
diff --git a/internal/templater/templates/wiki/stack.md.tmpl b/internal/templater/templates/wiki/stack.md.tmpl
new file mode 100644
index 0000000..7f4ffae
--- /dev/null
+++ b/internal/templater/templates/wiki/stack.md.tmpl
@@ -0,0 +1,37 @@
+# Tech contract
+
+The stack/library/framework decisions for this project, authored by **humans**.
+This file is **law**: any technology not listed below is an **open decision** —
+the agent proposes options and asks before adopting. `csdd graph analyze` indexes
+the Decided table and diffs it against declared dependencies, reporting undeclared
+usage, phantom entries, and unrefined rows.
+
+Manage it with the `stack` skill (Propose / Refine / Reconcile). Do not prefill
+technology choices you have not decided — the structure is provided; the decisions
+are yours.
+
+## Decided
+
+| Domain | Choice | Version | Why | Refs |
+|---|---|---|---|---|
+<!-- | Language | ... | ... | ... | ... | -->
+<!-- | HTTP router | ... | ... | ... | [notes](wiki/pages/<lib>.md) | -->
+
+## Rules
+
+1. **The contract is law.** Use only technologies listed in **Decided**. Anything
+   else is an open decision — propose 2–3 options with trade-offs and **ask the
+   human** before adopting. Never introduce a dependency silently.
+2. **Refine before first use.** Before first using a listed library in a feature,
+   check it against **current documentation** (Context7 MCP when configured, else
+   web search), file the findings as a wiki page, and link it in that row's
+   **Refs**. Do not rely on training data for API/config/version details.
+3. **Reconcile on findings.** When `csdd graph analyze` reports a tech finding,
+   resolve it: `undeclared` → propose it or remove the dependency; `phantom` →
+   confirm intent or drop the entry; `unrefined` → refine it.
+4. **Decisions are the human's.** The agent never edits dependency manifests or
+   adopts technology without an explicit human decision.
+
+## Open questions
+
+<!-- - Which broker: RabbitMQ vs Redis Streams vs Kafka? (owner: ..., due: ...) -->
diff --git a/internal/templater/templates/wiki/state-README.md.tmpl b/internal/templater/templates/wiki/state-README.md.tmpl
new file mode 100644
index 0000000..ef73fae
--- /dev/null
+++ b/internal/templater/templates/wiki/state-README.md.tmpl
@@ -0,0 +1,23 @@
+# `.csdd/` — csdd operational state
+
+Machine state only — the csdd analog of `.git/`. **No knowledge artifacts live
+here**: the knowledge graph is at `docs/graph/` and the wiki at `docs/wiki/`. The
+presence of this directory at the project root is the **workspace marker**:
+`csdd init` creates it, and `csdd graph`/`csdd wiki` require it.
+
+| File | Purpose | Committed? |
+|------|---------|------------|
+| `manifest.json` | Content hashes of the csdd-installed core files, used by `csdd update` to tell your edits from core drift. Migrated from the legacy `.claude/.csdd-manifest.json` (read-fallback kept). | yes |
+| `state.json` | Incremental graph-build state (per-source hashes). Regenerable. | no (local) |
+| `cache/` | Per-file extraction fragments keyed by content hash. Regenerable. | no (local) |
+
+Recommended `.gitignore`:
+
+```gitignore
+.csdd/state.json
+.csdd/cache/
+```
+
+Everything here except committed manifests is safe to delete — csdd rebuilds it.
+If you are looking for the graph, it is at `docs/graph/graph.json` (query it with
+`csdd graph query`, don't read it raw).
diff --git a/internal/web/frontend/src/App.tsx b/internal/web/frontend/src/App.tsx
index 9e6489a..c5fbd92 100644
--- a/internal/web/frontend/src/App.tsx
+++ b/internal/web/frontend/src/App.tsx
@@ -8,18 +8,20 @@ import { SpecView } from './components/SpecView'
 import { FileViewer } from './components/FileViewer'
 import { TestsView } from './components/TestsView'
 import { ResourceView } from './components/ResourceView'
+import { GraphView } from './components/GraphView'
 import { AuthScreen } from './components/AuthScreen'
 import { resourceKindsHint } from './resources'
 import type { ResourceKind } from './resources'
 
 // View is the top-level workspace area chosen from the header tabs. Specs and
 // Tests are full-width pages; Resources and Files use the contextual sidebar.
-export type View = 'specs' | 'resources' | 'files' | 'tests'
+export type View = 'specs' | 'resources' | 'files' | 'tests' | 'graph'
 const VIEWS: { id: View; label: string }[] = [
   { id: 'specs', label: 'Specs' },
   { id: 'resources', label: 'Resources' },
   { id: 'files', label: 'Files' },
   { id: 'tests', label: 'Tests' },
+  { id: 'graph', label: 'Graph' },
 ]
 
 export type Selection =
@@ -158,6 +160,8 @@ export function App() {
             ))}
 
           {view === 'tests' && <TestsView version={version} />}
+
+          {view === 'graph' && <GraphView version={version} />}
         </main>
       </div>
     </div>
diff --git a/internal/web/frontend/src/components/GraphView.tsx b/internal/web/frontend/src/components/GraphView.tsx
new file mode 100644
index 0000000..8a0c04c
--- /dev/null
+++ b/internal/web/frontend/src/components/GraphView.tsx
@@ -0,0 +1,252 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+import { api } from '../api'
+
+// GraphView renders docs/graph/graph.json — the csdd knowledge graph — through
+// the same read-only /api/file route as every other file (host guard + auth +
+// secret redaction, PR #43). It never writes; the CLI is the only author of the
+// graph (R6.3). Layout is a dependency-free canvas force simulation so the tab
+// stays self-contained.
+
+interface GNode {
+  id: string
+  label: string
+  file_type: string
+  source_file?: string
+}
+interface GLink {
+  source: string
+  target: string
+  relation: string
+}
+interface NodeLink {
+  nodes: GNode[]
+  links: GLink[]
+}
+
+interface Sim extends GNode {
+  x: number
+  y: number
+  vx: number
+  vy: number
+  deg: number
+}
+
+const PALETTE: Record<string, string> = {
+  spec: '#6C8EBF', requirement: '#B85450', criterion: '#D79B00', design: '#9673A6',
+  interface: '#82B366', flow: '#3A9CA6', task: '#D6B656', steering: '#647687',
+  skill: '#4C8C5A', agent: '#B46EAB', mcp: '#8C6D46', code_ref: '#999999',
+  wiki_page: '#5A7DBE', raw_source: '#B0B0B0', tech: '#C97B2C', code: '#4E79A7',
+}
+const colorFor = (t: string) => PALETTE[t] ?? '#888'
+
+export function GraphView({ version }: { version: number }) {
+  const canvasRef = useRef<HTMLCanvasElement | null>(null)
+  const [graph, setGraph] = useState<NodeLink | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [filter, setFilter] = useState('')
+  const [selected, setSelected] = useState<GNode | null>(null)
+
+  useEffect(() => {
+    let cancelled = false
+    api
+      .file('docs/graph/graph.json')
+      .then((fc) => {
+        if (cancelled) return
+        try {
+          setGraph(JSON.parse(fc.text) as NodeLink)
+          setError(null)
+        } catch (e) {
+          setError('graph.json is not valid JSON: ' + String(e))
+        }
+      })
+      .catch(() => {
+        if (!cancelled) setError('No graph yet. Run `csdd graph build` to generate docs/graph/graph.json.')
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [version])
+
+  const model = useMemo(() => {
+    if (!graph) return null
+    const byId: Record<string, Sim> = {}
+    const nodes: Sim[] = graph.nodes.map((n, i) => {
+      const s: Sim = { ...n, x: Math.cos(i) * 220 + 400, y: Math.sin(i * 1.7) * 220 + 300, vx: 0, vy: 0, deg: 0 }
+      byId[n.id] = s
+      return s
+    })
+    const links = graph.links.filter((l) => byId[l.source] && byId[l.target])
+    links.forEach((l) => {
+      byId[l.source].deg++
+      byId[l.target].deg++
+    })
+    return { nodes, links, byId }
+  }, [graph])
+
+  useEffect(() => {
+    if (!model) return
+    const canvas = canvasRef.current
+    if (!canvas) return
+    const ctx = canvas.getContext('2d')
+    if (!ctx) return
+    let raf = 0
+    const { nodes, links, byId } = model
+
+    const step = () => {
+      for (let i = 0; i < nodes.length; i++) {
+        const a = nodes[i]
+        for (let j = i + 1; j < nodes.length; j++) {
+          const b = nodes[j]
+          const dx = a.x - b.x
+          const dy = a.y - b.y
+          const d2 = dx * dx + dy * dy + 0.01
+          const rep = 1400 / d2
+          const d = Math.sqrt(d2)
+          a.vx += (dx / d) * rep
+          a.vy += (dy / d) * rep
+          b.vx -= (dx / d) * rep
+          b.vy -= (dy / d) * rep
+        }
+      }
+      for (const l of links) {
+        const a = byId[l.source]
+        const b = byId[l.target]
+        const dx = b.x - a.x
+        const dy = b.y - a.y
+        const d = Math.sqrt(dx * dx + dy * dy) + 0.01
+        const k = (d - 90) * 0.01
+        a.vx += (dx / d) * k
+        a.vy += (dy / d) * k
+        b.vx -= (dx / d) * k
+        b.vy -= (dy / d) * k
+      }
+      const cx = canvas.clientWidth / 2
+      const cy = canvas.clientHeight / 2
+      for (const n of nodes) {
+        n.vx += (cx - n.x) * 0.002
+        n.vy += (cy - n.y) * 0.002
+        n.vx *= 0.85
+        n.vy *= 0.85
+        n.x += n.vx
+        n.y += n.vy
+      }
+    }
+
+    const draw = () => {
+      const dpr = window.devicePixelRatio || 1
+      canvas.width = canvas.clientWidth * dpr
+      canvas.height = canvas.clientHeight * dpr
+      ctx.setTransform(dpr, 0, 0, dpr, 0, 0)
+      ctx.clearRect(0, 0, canvas.clientWidth, canvas.clientHeight)
+      ctx.globalAlpha = 0.3
+      ctx.strokeStyle = '#8888'
+      for (const l of links) {
+        const a = byId[l.source]
+        const b = byId[l.target]
+        ctx.beginPath()
+        ctx.moveTo(a.x, a.y)
+        ctx.lineTo(b.x, b.y)
+        ctx.stroke()
+      }
+      ctx.globalAlpha = 1
+      const f = filter.toLowerCase()
+      for (const n of nodes) {
+        const dim = f !== '' && !n.label.toLowerCase().includes(f)
+        ctx.globalAlpha = dim ? 0.15 : 1
+        const r = 4 + Math.min(8, n.deg)
+        ctx.beginPath()
+        ctx.arc(n.x, n.y, r, 0, 7)
+        ctx.fillStyle = colorFor(n.file_type)
+        ctx.fill()
+        if (selected && n.id === selected.id) {
+          ctx.lineWidth = 2
+          ctx.strokeStyle = '#111'
+          ctx.stroke()
+        }
+      }
+      ctx.globalAlpha = 1
+    }
+
+    const loop = () => {
+      step()
+      draw()
+      raf = requestAnimationFrame(loop)
+    }
+    loop()
+    return () => cancelAnimationFrame(raf)
+  }, [model, filter, selected])
+
+  const onClick = (e: React.MouseEvent<HTMLCanvasElement>) => {
+    if (!model) return
+    const rect = e.currentTarget.getBoundingClientRect()
+    const mx = e.clientX - rect.left
+    const my = e.clientY - rect.top
+    let best: Sim | null = null
+    let bd = 1e9
+    for (const n of model.nodes) {
+      const d = (n.x - mx) ** 2 + (n.y - my) ** 2
+      if (d < bd) {
+        bd = d
+        best = n
+      }
+    }
+    setSelected(bd < 400 && best ? best : null)
+  }
+
+  const connections = useMemo(() => {
+    if (!graph || !selected) return []
+    const out: string[] = []
+    for (const l of graph.links) {
+      if (l.source === selected.id) out.push(`→ ${l.relation} ${l.target}`)
+      else if (l.target === selected.id) out.push(`← ${l.relation} ${l.source}`)
+    }
+    return out
+  }, [graph, selected])
+
+  if (error) {
+    return (
+      <div className="empty">
+        <h2>Graph</h2>
+        <p className="muted">{error}</p>
+      </div>
+    )
+  }
+
+  return (
+    <div className="graph-view" style={{ display: 'flex', height: '100%', minHeight: 0 }}>
+      <div style={{ flex: 1, position: 'relative', minWidth: 0 }}>
+        <input
+          placeholder="filter nodes by label…"
+          value={filter}
+          onChange={(e) => setFilter(e.target.value)}
+          style={{ position: 'absolute', top: 8, left: 8, zIndex: 2, padding: '4px 8px' }}
+        />
+        <canvas
+          ref={canvasRef}
+          onClick={onClick}
+          style={{ width: '100%', height: '100%', display: 'block' }}
+        />
+      </div>
+      <aside style={{ width: 300, overflow: 'auto', padding: '12px 14px', borderLeft: '1px solid #8883', fontSize: 13 }}>
+        <h3 style={{ marginTop: 0 }}>Graph</h3>
+        <p className="muted">{graph ? `${graph.nodes.length} nodes · ${graph.links.length} edges` : 'loading…'}</p>
+        {selected ? (
+          <div>
+            <strong>{selected.label}</strong>
+            <div className="muted" style={{ margin: '4px 0' }}>
+              {selected.file_type}
+              {selected.source_file ? ` · ${selected.source_file}` : ''}
+            </div>
+            {connections.map((c, i) => (
+              <div key={i} style={{ margin: '2px 0' }}>
+                {c}
+              </div>
+            ))}
+          </div>
+        ) : (
+          <p className="muted">Click a node to inspect its connections.</p>
+        )}
+      </aside>
+    </div>
+  )
+}
diff --git a/internal/web/graph_tab_test.go b/internal/web/graph_tab_test.go
new file mode 100644
index 0000000..85b8014
--- /dev/null
+++ b/internal/web/graph_tab_test.go
@@ -0,0 +1,53 @@
+package web
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+)
+
+// TestGraphJSONServedThroughHardenedRoute verifies the web dashboard serves
+// docs/graph/graph.json through the same read-only /api/file route as every
+// other file — with the Host-header guard applied (R6.3). The Graph tab reads
+// exactly this; no new write endpoint is introduced.
+func TestGraphJSONServedThroughHardenedRoute(t *testing.T) {
+	graphJSON := `{"directed":true,"multigraph":false,"graph":{},"nodes":[{"id":"spec_x","label":"x","file_type":"spec","source_file":"specs/x/spec.json","source_location":"L1"}],"links":[]}`
+	root := tempWorkspace(t, map[string]string{
+		"docs/graph/graph.json": graphJSON,
+		"CLAUDE.md":             "# c\n",
+	})
+	srv := testServer(t, root)
+
+	// Served through /api/file with a valid (loopback) Host.
+	var fc struct {
+		Path string `json:"path"`
+		Text string `json:"text"`
+	}
+	if code := getJSON(t, srv.URL+"/api/file?path=docs/graph/graph.json", &fc); code != http.StatusOK {
+		t.Fatalf("graph.json should be served; got %d", code)
+	}
+	if !strings.Contains(fc.Text, "spec_x") {
+		t.Errorf("served graph.json missing content: %q", fc.Text)
+	}
+	// It parses as node-link JSON (what the Graph tab consumes).
+	var nl struct {
+		Nodes []map[string]any `json:"nodes"`
+	}
+	if err := json.Unmarshal([]byte(fc.Text), &nl); err != nil || len(nl.Nodes) != 1 {
+		t.Fatalf("served payload is not node-link JSON: %v", err)
+	}
+
+	// The Host-header guard (DNS-rebinding defense) rejects a foreign Host, so the
+	// graph is only reachable through the hardened path.
+	req, _ := http.NewRequest("GET", srv.URL+"/api/file?path=docs/graph/graph.json", nil)
+	req.Host = "evil.example.com"
+	resp, err := http.DefaultClient.Do(req)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode != http.StatusForbidden {
+		t.Errorf("foreign Host should be forbidden; got %d", resp.StatusCode)
+	}
+}