@thanh01.pmt/domain-kit 0.5.0 → 0.6.0

package/README.md

@@ -11,6 +11,13 @@
 ## Table of Contents
 
 - [Overview](#overview)
+- [End-to-End: From Raw Input to `CurriculumFeed`](#end-to-end-from-raw-input-to-curriculumfeed)
+  - [Layer 1 - Detect](#layer-1---detect)
+  - [Layer 2 - Generate](#layer-2---generate-one-branch-by-learning-mode)
+  - [Layer 3 - Emit](#layer-3---emit-one-shape-for-every-graph)
+  - [Layer 4 - Validate](#layer-4---validate-fail-closed-at-the-source)
+  - [The three graph types](#the-three-graph-types-at-a-glance)
+  - [Depth and minute conventions](#depth-and-minute-conventions)
 - [Installation](#installation)
 - [Quick Start](#quick-start)
   - [5. Emit Curriculum Feed](#5-emit-curriculum-feed-from-any-graph)
@@ -38,13 +45,455 @@
 - **Auto-detect** input type (repo, syllabus, description) and domain category (software, math, science...) with multi-language support (EN, VI, ZH, JA, KO, FR)
 - **Context-dependent domain detection** — `.cpp` files default to `software`; `hardware_iot` only when Arduino/ESP32/sensor context is present
 - **Choose graph type** automatically: `project_graph` (product-driven) or `knowledge_graph` (concept-driven) or `hybrid_graph`
-- **AST-level parsing** of Swift, TypeScript, Python, C++ source code
+- **Source scanning** of Swift, TypeScript/JavaScript, Python and C/C++ files (regex-based — the package has no parser dependency)
 - **LLM-powered decomposition** of projects into features → steps → keywords
 - **ULO/CIO/SIO depth classification** — each keyword/concept mapped to WHAT (ulo), HOW (cio), or IMPLEMENTATION (sio)
 - **Concept resolution** with ULO/CIO-aware matching against Master Tree concept codes
 - **Prerequisite cycle detection** — DFS cycle detection + Kahn's topological sort for knowledge graphs
 - **Keyword-per-milestone tracking** with new vs prerequisite distinction
-- **Time-budget-aware assembly** — configurable session duration, overhead factor, and automatic milestone splitting
+- **Time-budget-aware assembly** — milestones split against a 90-minute session, a 1.15 overhead factor and a 120-minute cap (fixed by the pipeline today; `assembleRoadmap()` takes them as parameters)
+
+---
+
+## End-to-End: From Raw Input to `CurriculumFeed`
+
+`domain-kit` never writes a lesson, never schedules a session, never picks an activity.
+Its entire job is to turn *something that already exists* — a repository, a syllabus, a
+short description — into **one JSON object with a fixed shape** (`CurriculumFeed` v2)
+that `curriculum-kit` can schedule without guessing.
+
+Read this section as four layers that always run in this order:
+
+| Layer | Who | Calls the LLM? | When it fails |
+|---|---|---|---|
+| 1. Detect | `detectDomainProfile()` | no | never throws — reports `confidence` / `ambiguous` |
+| 2. Generate | `runProjectGraphPipeline` / `runKnowledgeGraphPipeline` / `runHybridGraphPipeline` | yes | `throw` (fail-closed) |
+| 3. Emit | `emitCurriculumFeed()` | no | `throw` (fail-closed) |
+| 4. Validate | `validateCurriculumFeed()` | no | `throw` (fail-closed) |
+
+The rule that makes the package trustworthy: **layer 2 and 3 never hand back a
+half-built graph.** A missing LLM key, an empty phase plan, a concept with no keywords,
+a backwards prerequisite edge — all of them stop the run at the layer that produced
+them, instead of surfacing as a broken lesson three packages later.
+
+> **Shape is fail-closed; content is reported.** Structural violations throw at
+> emission. Things that make a graph *pedagogically* suspect — a feature with no
+> steps, a concept no phase introduces — are **diagnostics** (`source.diagnostics`,
+> each with a `code` and a `severity`) rather than throws, so the host decides whether
+> to block. See [ADR-0002](docs/adr/2026-10-05-ADR-0002-graph-integrity-provenance-and-diagnostics.md).
+
+### The whole picture
+
+```
+ +------------------------------------------------------------------------------+
+ | INPUT                                                                        |
+ |   repoDir / repoUrl - syllabusText / parsedSyllabus - description - goal     |
+ |   techStack - chapters - fileExtensions - gradeBand                          |
+ |   forcedLearningMode (router override) - knowledgeTreePath - proposalsPath   |
+ +------------------------------------+-----------------------------------------+
+                                      v
+ +------------------------------------------------------------------------------+
+ | LAYER 1 - detectDomainProfile() - pure, deterministic, no LLM                |
+ |   detectInputType() -> detectDomain() -> detectLearningMode()                |
+ |   => DomainProfile { inputType, domainCategory, learningMode, graphType,     |
+ |                     confidence, evidence, ambiguous? }                       |
+ +------------------------------------+-----------------------------------------+
+                                      | effectiveMode = forcedLearningMode
+                                      |   ?? domainProfile.learningMode
+                                      | (graphType is only its echo)
+        +---------------------+---------------------+
+        v                     v                     v
+    'product'             'concept'             'hybrid'
+        |                     |                     |
+        |                     |        repoDir present? --no--> FALLBACK to the
+        |                     |             |                  concept branch,
+        |                     |             |                  loud if auto (R1)
+        v                     v             v
+ runProjectGraph   runKnowledgeGraph   runProjectGraphPipeline + runKnowledgeGraphPipeline
+ Pipeline          Pipeline            (two full graph runs), then:
+ STEP_1 scan/      (parseSyllabus      generateHybridGraph()
+   select/AST        first if raw        STEP_1 feature-concept links
+ STEP_2 keyword      syllabusText)       STEP_2 decomposePhases
+   extract           generateKnowledge     (auditPhasePlan fail-closed)
+ STEP_3 SDK API      Graph:              STEP_3 totals
+   index              STEP_1 decompose
+ STEP_4 LLM           STEP_2 validate & clean
+   C0/C1/C2           STEP_2_5 standardize vs
+ STEP_5 verify          mlo-knowlege-tree.tsv  <== knowledgeTreePath enters
+   vs source            here, fail-closed (R5, R6)
+ STEP_6 escalate     STEP_3 detect + break cycles (R4)
+   keywords          STEP_4 topological sort
+ STEP_7 resolve to   STEP_5 ULO/CIO/SIO authoring
+   Master Tree       STEP_5b SIO keyword enrichment
+   concepts          STEP_5c minute calibration
+ STEP_8 assemble     STEP_6 verify + coverage audit
+   roadmap (feed is
+   emitted by the
+   ROUTER, not this
+   pipeline - R3)
+        |                     |                     |
+        +---------------------+---------------------+
+                              v
+ +------------------------------------------------------------------------------+
+ | LAYER 3 - emitCurriculumFeed(graph) - pure projection, no LLM                |
+ |   Called from THREE places (R3): router for the project branch               |
+ |   (domainRouter.ts:171), knowledge orchestrator, hybrid orchestrator.        |
+ |   learning_nodes[] - dependency_edges[] - suggested_groupings[] - phases[]   |
+ |   (phases[] is filled ONLY by the hybrid emitter - R1)                       |
+ +------------------------------------+-----------------------------------------+
+                                      v
+ +------------------------------------------------------------------------------+
+ | LAYER 4 - validateCurriculumFeed(feed) - structural + teaching order         |
+ |   Entry dispatches by graph shape; anything that already looks like a        |
+ |   feed is pass-through validated (R7)                                        |
+ +------------------------------------------------------------------------------+
+                                      v
+                            CurriculumFeed  (schema_version: 2)
+                                      ||
+                                      ||  ====== package boundary ======
+                                      ||  nothing below this line is
+                                      ||  domain-kit's business
+                                      v
+              curriculum-kit -> units -> sessions -> lessons -> activities
+```
+
+Risk tags (R1-R9) are defined in the Risk map below.
+
+Two facts about that diagram are easy to miss and worth stating up front:
+
+1. **Only the hybrid path fills `phases[]`.** `emitFromProject` and `emitFromKnowledge`
+   both return `phases: []`. "The order in the file is the order in the classroom"
+   is therefore a guarantee that only hybrid consumers can rely on — a project-only or
+   knowledge-only feed has no phase authority at all.
+2. **`runProjectGraphPipeline` stops at STEP_8.** Feed emission for the product branch is
+   done by `runDomainPipeline()` (static import of the emitter - the old dynamic
+   `import()` was removed as pure inconsistency), not by the project pipeline itself.
+   The knowledge and hybrid branches emit from their own thin orchestrators in
+   `src/pipeline/`.
+
+3. **Hybrid degrades loudly; explicit requests fail closed.** An AUTO-detected
+   `hybrid` without a `repoDir` runs the concept branch instead and returns a
+   structured `modeDowngrade: { from, to, reason }` on the result (R1). A
+   FORCED `forcedLearningMode: 'hybrid'` without `repoDir` throws. Both hybrid
+   knowledge legs pass `knowledgeTreePath`/`proposalsPath` through, so STEP_2_5
+   tree standardization runs in every mode (R2). Both fixed 2026-10-07.
+
+
+### Risk map (2026-10-07 - re-verified against code)
+
+Written while re-drawing the diagram above; every row cites the code it was
+verified against. Full postmortems: deep review 2026-10-05 (app repo,
+`docs/analysis/2026-10-05-graph-curriculum-deep-review.md`) and
+[ADR-0002](docs/adr/2026-10-05-ADR-0002-graph-integrity-provenance-and-diagnostics.md).
+
+| # | Risk | Where | Severity |
+|---|---|---|---|
+| R1 | **FIXED 2026-10-07.** Was: `hybrid` without `repoDir` silently degraded to a knowledge-graph feed (only a `warnings[]` entry). Now a FORCED hybrid throws (fail-closed); an auto-detected downgrade returns a structured `modeDowngrade { from, to, reason }`. | `src/pipeline/domainRouter.ts` | High |
+| R2 | **FIXED 2026-10-07.** Was: the hybrid branch's knowledge legs dropped `knowledgeTreePath`/`proposalsPath`, so STEP_2_5 ran in concept mode but not hybrid mode for the same subject. Now both hybrid legs pass them through. | `src/pipeline/domainRouter.ts` | High |
+| R3 | Feed emission is invoked from three different places, and emission options already diverge (`hallucinationCount` is only passed by the router). Drift risk with every emitter change. | `domainRouter.ts:171`, `pipeline/knowledgeGraphPipeline.ts:37`, `pipeline/hybridGraphPipeline.ts:22` | Medium |
+| R4 | Cycle breaking mutates `prerequisites` in place ("weakest edge" heuristic) and only warns. Which edge is dropped decides teaching order - a pedagogy-relevant decision hidden in a warning string. | `src/graph/knowledgeGraphPipeline.ts:383` | Medium |
+| R5 | STEP_2_5 only runs when `knowledgeTreePath` is provided. Without it, every concept stays `proposed_new` and nothing in the output flags the absence of tree anchoring. | `src/graph/knowledgeGraphPipeline.ts:322` | Medium |
+| R6 | Tree prerequisite edges are seeded only when the referenced tree concept is part of THIS analysis - partial graphs silently lose cross-analysis prerequisite edges. Matters for gold-set coverage measurement across runs. | `src/graph/knowledgeGraphPipeline.ts:363-375` | Medium |
+| R7 | `emitCurriculumFeed` dispatches by shape (key presence) and pass-through-validates anything that "looks like a feed" (CF-8 in the deep review). | `src/feed/curriculumFeedEmitter.ts:833-839` | Low |
+| R8 | Non-fatal pedagogy issues funnel into a single lossy `warnings[]` string channel; some drops only hit `console.warn` (e.g. a concept falling out of `learning_path`, KG-3). Structured diagnostics per ADR-0002 should replace string warnings. | deep review KG-3 | Medium |
+| R9 | **FIXED 2026-10-07.** Was: ASCII-only regex assumptions broke on Vietnamese text (KG-1) - empty derived keywords threw, registries filled with fragments. Now a shared `stripDiacritics()` (NFD + combining-mark strip + `đ`→`d`, incl. the precomposed-base-letter case NFD cannot decompose) backs every tokenizer; regression tests in `src/__tests__/vietnamese-tokenization.test.ts`. | `src/utils/diacritics.ts` | Critical |
+
+### Layer 1 - Detect
+
+`detectDomainProfile()` runs three detectors in sequence and never calls an LLM:
+
+- **Input type** — `repository | syllabus | description | files | mixed`
+- **Domain category** — multi-signal scoring over 340+ keywords in 10 categories,
+  with Vietnamese / English / Chinese / Japanese / French keyword lists and
+  context-dependent extension mapping (`.cpp` is ambiguous: software by default,
+  `hardware_iot` only with Arduino/ESP32/sensor context).
+- **Learning mode** — `product | concept | hybrid`, the signal that actually picks
+  the branch in layer 2.
+
+`graphType` on the profile is a convenience mirror of `learningMode`
+(`product→project_graph`, `concept→knowledge_graph`, `hybrid→hybrid_graph`); when the
+two would disagree, `forcedLearningMode` overrides the mode and `graphType` is
+recomputed at the branch.
+
+### Layer 2 - Generate (one branch by learning mode)
+
+#### Branch A — `project_graph` (product-driven)
+
+```
+ STEP_1     scan the file TREE, names only (no content)
+            └─▶ LLM picks the relevant files  ─▶ read content for those files only
+            └─▶ parse .swift / .ts .tsx / .js .jsx / .py / .ino .cpp .c .h .hpp
+            └─▶ merge results by PRIMARY language
+ STEP_2     extractKeywords()  → weighted keywords (app / esp32 tags)
+ STEP_3     SDK API index, derived from STEP_2 keywords
+ STEP_4_C0  scaffold   → feature F0 "FOUNDATION & SETUP" (LLM failure ⇒ F0 is skipped
+                         silently and the pipeline continues without it)
+ STEP_4_C1  overview   → product{ goals, users, journeys, development_stages } + features
+ STEP_4_C2  steps      → per-feature steps, one batched LLM call, falling back to
+                         per-feature; a feature that still fails is logged and left
+                         step-less (no throw)
+ STEP_5     verifyProjectGraph() → strip files / APIs / keywords not found in code;
+                                F0 keywords are exempt (pedagogical terms)
+ STEP_6     escalateAndMapConcepts() → keyword → technology-neutral concept +
+                                       depth (ulo | cio | sio) + evidence files.
+                                       Depth comes from the LLM; on LLM failure a
+                                       regex fallback reads the usage context
+                                       (import → sio, code body → sio, comment → ulo)
+ STEP_7     resolveConcepts() → concept → Master-Tree code, scored ULO/CIO-aware:
+                                   sio keyword → concept.keywords
+                                   cio keyword → concept.description + concept.cio
+                                   ulo keyword → concept.ulo + concept.description
+ STEP_8     assembleRoadmap() → milestones grouped into phases, each milestone tagged
+                                with all / new / prerequisite keywords + a time budget
+ ───────────────────────── package boundary ───────────────────────────────
+            emitCurriculumFeed(projectGraph) → CurriculumFeed (phases: [])
+```
+
+#### Branch B — `knowledge_graph` (concept-driven)
+
+```
+ STEP_1    parseSyllabus(syllabusText) → structured units/topics
+           LLM decomposes the subject → concepts + prerequisites + problem_types
+           + categories + techniques. The syllabus is truncated at
+           KG_MAX_SYLLABUS_CHARS (default 16000) with a warning.
+
+ STEP_2    validate & clean
+           · description shorter than 50 chars → warning
+           · KEYWORD REGISTRY IS FAIL-CLOSED: a concept with no keywords gets them
+             derived from its name/description; if nothing is derivable → throw
+           · a prerequisite pointing at a non-existent concept → edge removed + warning
+
+ STEP_2_5  only when knowledgeTreePath is supplied: standardize every concept against
+           mlo-knowlege-tree.tsv → `standardized` (adopts the tree code + the keywords
+           the standardizer chose for this tech stack) or `proposed_new`.
+           A concept with no decision → throw. Tree prerequisite codes then seed
+           internal edges where both ends are in this analysis.
+
+ STEP_3    detectPrerequisiteCycles() → breakPrerequisiteCycles() at the weakest edge
+ STEP_4    topologicalSort() (Kahn) → learning_path is REBUILT from the sorted order
+ STEP_5    hierarchical ULO/CIO/SIO authoring, then deterministic ULO/CIO/SIO codes
+           (a tree-standardized code from STEP_2_5 always wins over a generated one)
+ STEP_5b   mine the SIO text for technology identifiers — backticked tokens,
+           @Annotations, a.b() calls, .modifiers, camelCase — and merge them into the
+           keyword registry (capped at 8 per concept)
+ STEP_5c   minute calibration:
+             score = 0.2·sio + 0.15·problem_types + 0.15·prerequisites
+                   + 0.2·(has Analyze/Evaluate/Create)
+             minutes = 15 + 45·score          ⇒ 15 … 60 minutes
+           The calibrated value overrides the LLM estimate only when the LLM returned
+           its default 30, or when the two diverge by more than 50%.
+
+ STEP_6    verifyKnowledgeGraph() → referential integrity + REVERSE COVERAGE audit:
+           every syllabus topic must be covered by at least one concept.
+           Findings are reported as warnings, not thrown.
+ ───────────────────────── package boundary ───────────────────────────────
+           emitCurriculumFeed(knowledgeGraph) → CurriculumFeed (phases: [])
+```
+
+#### Branch C — `hybrid_graph` (both, and how they interlock)
+
+Needs a `project_graph` **and** a `knowledge_graph` — it is the only branch that runs two
+generators before it starts.
+
+```
+ input: project_graph + knowledge_graph
+
+ STEP_1   LLM emits feature ↔ concept links
+          { feature_id, concept_id, relationship: requires|demonstrates|applies|extends,
+            depth: ulo|cio|sio, estimated_prereq_minutes }
+          A link naming an unknown feature or concept is DROPPED with a warning.
+
+ STEP_2   decomposePhases() — the LLM turns the build into PROGRESSIVE COMPLETION
+          PHASES: each phase states what the product can demonstrably do once it is
+          done, owns every feature built in it, and declares which concepts it teaches
+          at its start (aspect = new | advanced | preview).
+          auditPhasePlan() then checks the contract deterministically:
+            · every feature in EXACTLY one phase, none skipped
+            · every phase has a non-empty product_completion
+            · a concept is introduced no later than the phase that consumes it
+            · no concept before its own prerequisites — checked per PHASE, not per array
+              position: teaching a concept and its prerequisite in the SAME phase is valid
+              whichever order the LLM emitted them, and flagging it would burn all three
+              repair attempts and then throw away a good plan
+            · a preview is satisfied by an earlier anchor or an earlier preview, and every
+              preview has an anchor teach somewhere
+            · preview must precede its anchor and precede nothing already introduced
+          Violations are fed back verbatim; at most 3 attempts, then throw. A phase
+          model that cannot be trusted is worse than no output.
+
+ STEP_3   totals
+          total_project_minutes  = Σ step.effort.estimated_minutes (fallback 15)
+          total_concept_minutes  = Σ concept.estimated_minutes   (fallback 30)
+          linked_prereq_minutes  = total_project_minutes + Σ max-per-concept prereq
+                                   minutes, counting only concepts that HAVE a feature
+                                   link. It is NOT the course total.
+ ───────────────────────── package boundary ───────────────────────────────
+          emitCurriculumFeed(hybridGraph) → CurriculumFeed — the only path that
+          fills phases[], and therefore the only path that defines teaching order.
+```
+
+### Layer 3 - Emit (one shape for every graph)
+
+```
+ emitCurriculumFeed(graph, opts?)
+   ├─ graph already has learning_nodes[]   → validate and pass through unchanged
+   ├─ has project_graph | knowledge_graph | links[] | phases[]
+   │                                        → emitFromHybrid()
+   ├─ has concepts[] or type==='knowledge_graph'
+   │                                        → emitFromKnowledge()
+   └─ otherwise                             → emitFromProject()
+```
+
+**`emitFromHybrid` — phase-driven emission.** For each phase, in order, it emits
+`new` concepts first, then `advanced` revisits, then `previews`, and only then the
+phase's features and their steps (project-graph order):
+
+| Aspect | Node id | Minutes | Carries |
+|---|---|---|---|
+| `new` | `<cid>` | the concept's own estimate | `keywords.new` — the legitimate vocabulary introducer |
+| `advanced` | `<cid>__ADV<phase>` | `max(15, 50% of anchor)` | a `sio → cio` downgrade candidate saving 30% **of the revisit's own minutes** |
+| `preview` | `<cid>__PREV<phase>` | `max(5, 25% of anchor)` | `keywords.all` — may introduce the vocabulary early, with **no** prerequisite edges and no scaffolding |
+
+**A preview in an EARLIER phase satisfies a downstream concept's prerequisite** — that is
+what it is for. A preview in the *same* phase does not, because within a phase the order
+is `new → advanced → preview`, so it would arrive after the dependent concept.
+
+### Knowledge edges
+
+Edges are materialized as *concept → first step of the consumer feature* (`kind: 'knowledge'`);
+feature build order and `depends_on` become `kind: 'task'`. When a prerequisite is satisfied
+only by a preview, the edge points at the **preview node** — the vocabulary genuinely comes
+from there.
+
+Keyword identity is case- and Unicode-insensitive: `SwiftUI` / `swiftui` and an NFD/NFC
+Vietnamese pair are the same keyword. The ledger and the edge materializer share one
+comparison key, so they cannot disagree about what counts as a first appearance.
+
+Edges are materialized as *concept → first step of the consumer feature* (`kind: 'knowledge'`);
+feature build order and `depends_on` become `kind: 'task'`.
+
+Where the graph contradicts itself, the emitter **reports instead of inventing**:
+
+- a link whose anchor teach sits in a LATER phase than its consumer → `hybrid_link_drift`, no edge;
+- a product step that would become the introducer of a concept's vocabulary → `concept_overtaken_by_step`, no edge;
+- a keyword introducer that sits in a later phase than its consumer → `keyword_order_drift`, no edge.
+
+That last class of edge is what once produced the 2026-09-17 "Teaching-order violation"
+incident: the contradiction used to escape emission and explode inside the planner.
+
+#### Coverage holes that used to be silent
+
+| Diagnostic | Severity | Meaning |
+|---|---|---|
+| `orphan_concept` | `error` | the knowledge graph holds a concept that no phase introduces and no link consumes — it will not be taught |
+| `feature_without_steps` | `warning` | the project graph declares a feature whose steps never materialised (STEP_4_C2 failed for it) — it will not appear in the feed |
+| `step_without_id` | `warning` | a step with no `id` cannot become a node and was dropped (reported as `feature#index`) |
+| `external_prerequisite` | `info` | a concept depends on knowledge outside this analysis — recorded on the node as `external_prerequisites`, not an error |
+| `upstream_warning` | `warning` | a warning string handed in by the graph pipeline, kept for backward compatibility |
+
+Both of the first two used to vanish with an empty `warnings: []`. The host can gate on
+`code`/`severity` instead of substring-matching free text.
+
+### Entry requirements
+
+A concept can depend on knowledge the analysis does not cover — a course on vector
+calculus legitimately requires linear algebra. Those ids are **not** nodes here, so they
+cannot be edges; dropping them silently would throw away exactly what someone deciding
+whether to enrol needs most.
+
+They land on the node instead:
+
+```json
+{ "id": "C7", "kind": "concept", "external_prerequisites": ["C_LINALG"] }
+```
+
+and surface once as an `external_prerequisite` **info** diagnostic. Info, not warning —
+a course with entry requirements is normal, and a host that gates on severity should not
+block on it. The three emission paths used to disagree here: the knowledge path dropped
+them silently while **both** hybrid paths hard-failed (one built a dangling edge, the other
+threw an ordering error blaming a concept that was not in the analysis), so any graph
+referencing prior knowledge was un-emittable.
+
+### Provenance
+
+`source.provenance` records which providers actually served the run:
+
+```typescript
+provenance: {
+  providers: ['openrouter', 'nvidia'],  // failover is visible, not silent
+  models: ['preset-x', 'nemotron-3-ultra'],
+  calls: 7,
+  failed_calls: 1,                       // openrouter fell through
+  degraded: true,
+}
+```
+
+Without it, a graph produced half by a paid preset and half by a free tier is
+indistinguishable from a clean one — and not reproducible or auditable. The client is
+created **once per pipeline run** and threaded through every step, so all calls land in
+one log; it is per-instance, so concurrent runs never inherit each other's history.
+
+### Layer 4 - Validate (fail-closed, at the source)
+
+`validateCurriculumFeed()` runs on every emission path and rejects:
+
+- duplicate node ids;
+- an edge pointing at an unknown node, or a self-loop;
+- a grouping or phase referencing an unknown node;
+- duplicate phase ids;
+- **duplicate or non-ascending phase `order`** — `order` *is* the teaching sequence once
+  phases exist, so two phases claiming one slot makes it undefined;
+- an empty feed (`learning_nodes` has a minimum of 1);
+- **the teaching-order invariant** — when `phases[]` is non-empty, a prerequisite must
+  live in the same phase or an *earlier* one than its consumer.
+
+`emitFromProject` adds one more: a graph with `features[]` but no `features[].steps` is
+rejected by name as a legacy knowledge-tree graph, with the regeneration command in the
+message.
+
+### The three graph types at a glance
+
+|  | `project_graph` | `knowledge_graph` | `hybrid_graph` |
+|---|---|---|---|
+| Answers | "what is being built?" | "what must be understood?" | "both, and how they interlock" |
+| LLM sees | file tree + selected file contents | syllabus / description | both graphs, rendered as text |
+| Atomic node | `features[].steps[]` | `concepts[]` | both |
+| Ordering authority | array order of features/steps | `learning_path` (topological) | `phases[]` → `feed.phases` |
+| Time source | `step.effort.estimated_minutes` | `concept.estimated_minutes` (calibrated 15–60) | sum of both |
+| Prerequisite evidence | none — build order only | `concept.prerequisites[]`, proven acyclic | both, cross-checked against concept prerequisites |
+| `feed.phases` | always `[]` | always `[]` | filled ⇒ teaching order |
+| Entry point | `runProjectGraphPipeline()` | `runKnowledgeGraphPipeline()` | `runHybridGraphPipeline()` |
+
+### Depth and minute conventions
+
+Exported from code as `DEPTH_MINUTE_FRACTIONS` and `calibrateConceptMinutes()` — read
+those rather than copying numbers out of this table.
+
+| Convention | Value | Source |
+|---|---|---|
+| preview node minutes | `max(5, 25%)` of the anchor | `DEPTH_MINUTE_FRACTIONS` |
+| ULO / CIO / SIO minutes for a concept node | `max(5, 35%)` / `max(ulo+5, 65%)` / `max(cio+5, 100%)` | `DEPTH_MINUTE_FRACTIONS` |
+| advanced revisit minutes | `max(15, 50%)` of the anchor | `DEPTH_MINUTE_FRACTIONS` |
+| advanced revisit downgrade candidate | `sio → cio`, saves 30% **of the revisit's own minutes** | `DEPTH_MINUTE_FRACTIONS` |
+| step with no `estimated_minutes` | 15 minutes (same constant the hybrid totals use) | `DEFAULT_STEP_MINUTES` |
+| concept minutes after calibration | 15–60 minutes | `calibrateConceptMinutes()` |
+| roadmap session / overhead / milestone split cap | 90 min / ×1.15 / 120 min — hardcoded by the pipeline, not configurable through it | `STEP_8` in `pipeline/projectGraphPipeline.ts` |
+| phase minute balance demanded of the LLM | 120–240 min per phase; rebalance below 60 or above 400 | `STEP_2` in `graph/hybridGraphPipeline.ts` |
+| file budget per run | 70 files / 500 000 chars | `utils/fileUtils.ts` |
+
+> The three depth levels are a **single ladder applied everywhere**:
+> `ulo` = WHAT + WHY (technology-agnostic), `cio` = HOW the mechanism works
+> (still no concrete API), `sio` = IMPLEMENTATION (must name a real API, function,
+> module or file). A keyword can only ever move *down* this ladder, never across it.
+>
+> The percentages above live in one exported table, `DEPTH_MINUTE_FRACTIONS`. They were
+> previously hardcoded in three places (25% / 35% / 30%), which meant "what does a ULO
+> pass cost?" had three answers. Read that table rather than hardcoding a fourth.
+
+> **Unicode:** Vietnamese input reaches the detector in NFC or NFD form. Text is
+> normalized at the boundary and also matched with diacritics stripped, so the same
+> sentence classifies identically whichever form it arrives in — before this, one
+> sentence measured as `math` (confidence 1.0) in NFC and `other` (confidence 0.2) in NFD.
 
 ---
 
@@ -74,9 +523,34 @@ npm link @thanh01.pmt/domain-kit
 LLM_API_KEY=sk-...           # OpenAI-compatible API key
 LLM_BASE_URL=https://api.openai.com/v1  # API base URL
 LLM_MODEL=gpt-4o-mini        # Model to use
-LLM_MAX_TOKENS=16384          # Max output tokens
+LLM_MAX_TOKENS=65536          # Max output tokens (default)
+LLM_MIN_REQUEST_INTERVAL_MS=2500  # process-wide pacing; 0 disables
+
+# Extra knobs the pipelines read directly:
+KG_MAX_SYLLABUS_CHARS=16000   # syllabus truncation before decomposition
+KG_MAX_TOKENS=65536           # knowledge-graph generation budget
+LLM_REQUEST_TIMEOUT_MS=300000 # per-request cap
 ```
 
+**Provider chain.** `createLlmClient()` builds an ordered chain and fails over through
+it on transient errors (408/429/500/502/503/504):
+
+1. explicit `llmConfig.apiKey`
+2. `LLM_*` (or `OPENAI_*`) — generic OpenAI-compatible
+3. `DASHSCOPE_*` / `ALIBABA_*`
+4. `NVIDIA_API_KEY` → NVIDIA NIM
+5. `OPENROUTER_API_KEY` → OpenRouter
+
+If `OPENROUTER_MODEL` is set, OpenRouter is moved to the front. Requests are paced
+process-wide so free tiers are not rate-limited by a burst; the interval is configurable
+via `LLM_MIN_REQUEST_INTERVAL_MS` or `llmConfig.minRequestIntervalMs` (set `0` when the
+caller owns the rate limit — several concurrent pipelines in one process, or serverless).
+
+Each client keeps a `callLog` of every provider attempt it made. One client is created
+per pipeline run and threaded through every step, so `PipelineResult.provenance` and
+`CurriculumFeed.source.provenance` reflect that whole run — and because the log is
+per-instance, concurrent runs never inherit each other's history.
+
 ---
 
 ## Quick Start
@@ -138,7 +612,7 @@ const result = await generateHybridGraph({
   knowledgeGraph: existingKnowledgeGraph,
 });
 
-console.log(result.hybridGraph);      // HybridGraph with links[]
+console.log(result.hybridGraph);      // HybridGraph with links[] + phases[]
 ```
 
 ### 5. Emit Curriculum Feed (from any graph)
@@ -146,7 +620,11 @@ console.log(result.hybridGraph);      // HybridGraph with links[]
 ```typescript
 import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
 
-const feed = emitCurriculumFeed(result.projectGraph);  // or knowledgeGraph or hybridGraph
+// `graph` is whichever graph object you just produced — note that step 4 above
+// rebinds `result` to the HYBRID result, so name the graph explicitly:
+const feed = emitCurriculumFeed(projectGraph);        // project_graph
+// const feed = emitCurriculumFeed(knowledgeGraph);   // knowledge_graph
+// const feed = emitCurriculumFeed(hybridGraph);       // hybrid_graph (phases filled)
 
 console.log(feed.learning_nodes.length);    // unified nodes ready for planner
 console.log(feed.dependency_edges.length);  // knowledge + task edges
@@ -159,48 +637,22 @@ console.log(feed.phases.length);            // non-empty ⇒ learning_nodes are
 
 ## Architecture
 
-```
-┌─────────────────────────────────────────────────────────────┐
-│                        domain-kit                           │
-├─────────────────────────────────────────────────────────────┤
-│                                                             │
-│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
-│  │   schemas/    │   │  detector/   │   │   parsers/   │    │
-│  │              │   │              │   │              │    │
-│  │ ProjectGraph │   │ inputType    │   │ Swift        │    │
-│  │ KnowledgeGr. │   │ domain       │   │ TypeScript   │    │
-│  │ HybridGraph  │   │ learningMode │   │ Python       │    │
-│  │ DomainProfile│   │ orchestrator │   │ C++/Arduino  │    │
-│  │ Extensions   │   │              │   │              │    │
-│  └──────────────┘   └──────────────┘   └──────────────┘    │
-│                                                             │
-│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
-│  │ extractors/  │   │    graph/    │   │  concepts/   │    │
-│  │              │   │              │   │              │    │
-│  │ keywords     │   │ scaffold     │   │ concept      │    │
-│  │              │   │ overview     │   │ resolver     │    │
-│  │              │   │ steps        │   │              │    │
-│  │              │   │ verify       │   │              │    │
-│  │              │   │ escalate     │   │              │    │
-│  │              │   │ knowledgeKG  │   │              │    │
-│  │              │   │ hybridKG     │   │              │    │
-│  └──────────────┘   └──────────────┘   └──────────────┘    │
-│                                                             │
-│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐    │
-│  │  assembly/   │   │  pipeline/   │   │    feed/     │    │
-│  │              │   │              │   │              │    │
-│  │ roadmap      │   │ projectGraph │   │ emitCurricu..│    │
-│  │ assembler    │   │ pipeline     │   │ lumFeed      │    │
-│  └──────────────┘   └──────────────┘   └──────────────┘    │
-│                                                             │
-│  ┌──────────────┐                                           │
-│  │    utils/    │                                           │
-│  │ llmClient    │                                           │
-│  │ fileUtils    │                                           │
-│  └──────────────┘                                           │
-│                                                             │
-└─────────────────────────────────────────────────────────────┘
-```
+| Directory | Files | Owns |
+|---|---|---|
+| `schemas/` | `projectGraphSchema`, `knowledgeGraphSchema`, `hybridGraphSchema`, `domainProfileSchema`, `curriculumFeedSchema`, `domainExtensions` | every Zod schema; `validateCurriculumFeed()` lives in `curriculumFeedSchema` |
+| `detector/` | `inputTypeDetector`, `domainDetector`, `learningModeDetector`, `domainProfileDetector` | layer 1 — pure, no LLM |
+| `parsers/` | `swift`, `typescript`, `python`, `cpp`, `syllabusParser` | source + syllabus readers |
+| `extractors/` | `keywordExtractor`, `fileSelector`, `fileRelevanceScorer` | keyword weights, LLM file relevance |
+| `graph/` | `scaffoldExtractor`, `overviewExtractor`, `stepExtractor`, `graphVerifier`, `conceptEscalator`, `hierarchicalLoAuthoring`, `loCodeStandard`, `loExemplars`, `depthAudit`, `knowledgeTreeCatalog`, `conceptStandardizer`, `knowledgeGraphPipeline`, `knowledgeGraphVerifier`, `hybridGraphPipeline` | layer 2 — the three graph generators |
+| `concepts/` | `conceptResolver` | keyword → Master-Tree code, ULO/CIO-aware |
+| `assembly/` | `roadmapAssembler` | milestones, phases, keyword ledger, time budget |
+| `pipeline/` | `domainRouter`, `projectGraphPipeline`, `knowledgeGraphPipeline`, `hybridGraphPipeline` | the three **orchestrators** (thin) + the router; only `projectGraphPipeline` holds the 8 real steps |
+| `feed/` | `curriculumFeedEmitter` | layer 3 — projects any graph onto `CurriculumFeed` v2 |
+| `utils/` | `llmClient`, `fileUtils` | provider chain + pacing, file budget |
+
+> `graph/` and `pipeline/` both contain files named `knowledgeGraphPipeline.ts` and
+> `hybridGraphPipeline.ts`. They are not duplicates: the `graph/` ones do the LLM work,
+> the `pipeline/` ones parse the syllabus, call the `graph/` one, and emit the feed.
 
 ---
 
@@ -242,7 +694,12 @@ Step 2: ROUTE (by graphType)
   └── hybrid_graph    → project_graph + knowledge_graph + LLM link features↔concepts
   │
 Step 3: OUTPUT
-  └── domain_graph.json
+  ├── the graph object   (project_graph | knowledge_graph | hybrid_graph)
+  └── CurriculumFeed v2  (learning_nodes / dependency_edges / groupings / phases)
+      ↑ always produced by emitCurriculumFeed(); hybrid is the only branch that fills phases[]
+
+Note: domain-kit returns objects in memory — it never writes *.json itself.
+Serialising them is the host's job.
 ```
 
 ### Output
@@ -264,7 +721,7 @@ Always **one of three schemas**:
 `detectDomainProfile()` runs three detectors in sequence:
 
 1. **Input Type Detector** — Checks for repo URLs, syllabus text, file extensions, descriptions
-2. **Domain Detector** — Multi-signal scoring with 200+ keywords across 10 domains, **multi-language support** (EN, VI, ZH, JA, KO, FR), and **context-dependent extension mapping** (e.g., `.cpp` → software by default, hardware only when Arduino/ESP32/sensor context present)
+2. **Domain Detector** — Multi-signal scoring with 340+ keywords across 10 domains, **multi-language support** (EN, VI, ZH, JA, KO, FR), and **context-dependent extension mapping** (e.g., `.cpp` → software by default, hardware only when Arduino/ESP32/sensor context present)
 3. **Learning Mode Detector** — Combines input signals + domain heuristics + verb patterns
 
 ### Ambiguous Domain Handling
@@ -274,7 +731,7 @@ Some file extensions map to multiple domains (e.g., `.cpp` → software or hardw
 1. Default-maps ambiguous extensions to `software` (most common use)
 2. Checks context keywords (e.g., `arduino`, `ESP32`, `GPIO`, `sensor`) to upgrade to `hardware_iot`
 3. Sets `ambiguous` field in output when detection is borderline
-4. Agent should **ask user to confirm** when `ambiguous` is set or confidence < 0.6
+4. Agent should **ask user to confirm** when `ambiguous` is set or `confidence.domainCategory < 0.6`
 
 ### Domain Categories
 
@@ -287,8 +744,8 @@ Some file extensions map to multiple domains (e.g., `.cpp` → software or hardw
 | `science` | Lý, hóa, sinh | thí nghiệm, năng lượng, cell |
 | `language` | Tiếng Anh, writing | grammar, vocabulary, essay |
 | `arts` | Âm nhạc, thiết kế | piano, color theory, typography |
-| `research` | Nghiên cứu, thống kê | methodology, hypothesis, SPSS |
-| `business` | Kinh doanh, tài chính | revenue, agile, business plan |
+| `research` | Nghiên cứu, thống kê | methodology, hypothesis, regression |
+| `business` | Kinh doanh, tài chính | revenue, agile, kế hoạch kinh doanh |
 | `other` | Fallback | — |
 
 ### Confidence & Fallback
@@ -380,9 +837,27 @@ For projects that require **both building and understanding**.
       "concept_id": "G3",
       "relationship": "requires",
       "depth": "cio",
-      "estimated_prereq_minutes": 30
+      "estimated_prereq_minutes": 30,
+      "phase_id": "PH2"
     }
-  ]
+  ],
+  // phases[] is the teaching order — and the only source of CurriculumFeed.phases
+  "phases": [
+    {
+      "id": "PH1",
+      "order": 1,
+      "name": "Runnable slice",
+      "product_completion": "App launches and shows an empty conversation list",
+      "feature_ids": ["F0", "F1"],
+      "introduces": [
+        { "concept_id": "G1", "aspect": "new", "note": "..." },
+        { "concept_id": "G3", "aspect": "preview", "note": "vocabulary only" }
+      ]
+    }
+  ],
+  "total_project_minutes": 480,
+  "total_concept_minutes": 210,
+  "linked_prereq_minutes": 540
 }
 ```
 
@@ -398,23 +873,34 @@ All schemas are Zod-validated TypeScript types.
 | `KnowledgeGraphSchema` | `knowledgeGraphSchema.ts` | Concept-driven subject structure |
 | `HybridGraphSchema` | `hybridGraphSchema.ts` | Combined project + knowledge |
 | `DomainProfileSchema` | `domainProfileSchema.ts` | Domain detection output |
-| `HardwareFeatureExtension` | `domainExtensions.ts` | Hardware overlay (wiring, materials) |
-| `ThreeDesignFeatureExtension` | `domainExtensions.ts` | 3D Design overlay (shapes, dimensions) |
+| `HardwareFeatureExtensionSchema` | `domainExtensions.ts` | Hardware overlay (wiring, materials) |
+| `ThreeDesignFeatureExtensionSchema` | `domainExtensions.ts` | 3D Design overlay (shapes, dimensions) |
+| `MathConceptExtensionSchema` | `domainExtensions.ts` | Math overlay (theorems) |
+| `ScienceConceptExtensionSchema` | `domainExtensions.ts` | Science overlay (experiment procedures) |
+| `LanguageConceptExtensionSchema` | `domainExtensions.ts` | Language overlay (grammar rules) |
+| `ConceptSchema` | `knowledgeGraphSchema.ts` | One knowledge concept |
+| `LearningPathStepSchema` | `knowledgeGraphSchema.ts` | One topological-order step |
 | `CurriculumFeedSchema` | `curriculumFeedSchema.ts` | Planner-ready normalized feed (nodes, edges, groupings, phases) |
 | `FeedNodeSchema` | `curriculumFeedSchema.ts` | Individual learning node (concept, skill, or product step) |
 | `FeedEdgeSchema` | `curriculumFeedSchema.ts` | Dependency edge (knowledge or task) |
 | `FeedGroupingSchema` | `curriculumFeedSchema.ts` | Suggested grouping of nodes (feature or category) |
 | `FeedPhaseSchema` | `curriculumFeedSchema.ts` | Development phase — when non-empty, defines teaching sequence and unit structure |
+| `FeedDiagnosticSchema` | `curriculumFeedSchema.ts` | Typed finding (code + severity + node ids) |
+| `FeedProvenanceSchema` | `curriculumFeedSchema.ts` | Which LLM providers served the run |
 
 ### Key Types
 
 ```typescript
 // Project Graph
 type ProjectGraph = {
+  schema_version: 3;
   project: ProjectInfo;
   product: Product;
   features: Feature[];
+  capabilities: Capability[];
   implementation: { tasks: Task[] };
+  missing_gaps: MissingGap[];
+  tech_debt: TechDebt[];
 }
 
 type Feature = {
@@ -430,11 +916,16 @@ type Step = {
   keywords: string[];
   api_usage: string[];
   completion_level: 'base' | 'mvp' | 'extend' | 'polish';
-  effort: { estimated_minutes: number; complexity: 'low' | 'medium' | 'high' };
+  outcome?: { user_visible: string; technical: string };   // → FeedNode.user_visible_deliverable
+  // all effort fields are OPTIONAL — downstream totals fall back to 15 minutes
+  effort?: { estimated_minutes?: number; complexity?: 'low' | 'medium' | 'high';
+             concepts_count?: number; files_touched?: number };
 }
 
 // Knowledge Graph
 type KnowledgeGraph = {
+  schema_version: 1;
+  type: 'knowledge_graph';
   subject: SubjectInfo;
   concepts: Concept[];
   categories: ConceptCategory[];
@@ -444,11 +935,26 @@ type KnowledgeGraph = {
 type Concept = {
   id: string;
   name: string;
+  description: string;
+  keywords: string[];   // SIO-level tech terms — drives the keyword ledger, STEP_5b enrichment
+                        // and the SIO-binding audit; NEVER silently empty (fail-closed)
   ulo: string;      // WHAT + WHY
   cio: string;       // HOW
   sio: string[];     // Specific implementations
   prerequisites: string[];
+  estimated_minutes: number;   // calibrated 15–60 (STEP_5c)
   problem_types: ProblemType[];
+  techniques: string[];
+  common_mistakes: string[];
+  materials: string[];         // physical lab equipment
+  visual_aids: string[];       // diagrams / images / animations
+  // codes — a knowledge-tree code from STEP_2_5 always wins over a generated one
+  code?: string;
+  standardization?: 'standardized' | 'proposed_new';
+  tree_code?: string;
+  ulo_code?: string;
+  cio_code?: string;
+  sio_codes?: string[];
 }
 
 // Domain Detection
@@ -467,27 +973,51 @@ type ConceptMapping = {
   concept_code: string;
   concept_name: string;
   depth: 'ulo' | 'cio' | 'sio';     // WHAT (ulo), HOW (cio), IMPLEMENTATION (sio)
-  rationale: string;
+  depth_source: 'llm' | 'heuristic' | 'override';  // who decided it — the regex
+                                  // fallback (comment→ulo, import→sio) has no
+                                  // pedagogical basis and must stay distinguishable
+  depth_rationale: string;
   evidence_files: string[];
 }
 
-// Assembled Roadmap (with time budget)
+// Assembled Roadmap (with time budget) — TypeScript interface, not a Zod schema
 type AssembledRoadmap = {
-  phases: Phase[];
-  all_keywords: string[];
-  new_keywords: string[];
-  prerequisite_keywords: string[];
+  project: ProjectGraph['project'];
+  product: ProjectGraph['product'];
+  phases: AssembledPhase[];        // { phase_id, phase_name, milestones, total_minutes,
+                                   //   concept_progression }
+  feature_concepts: Map<string, ConceptMapping[]>;
   time_budget: {
-    total_estimated_minutes: number;
-    overhead_minutes: number;
-    session_minutes: number;
+    session_minutes: number;          // 90
+    overhead_factor: number;          // 1.15
+    total_estimated_minutes: number;  // Σ milestone.estimated_minutes (raw)
+    total_adjusted_minutes: number;   // Σ milestone.adjusted_minutes (after overhead)
   };
-}
+};
+
+type AssembledMilestone = {
+  id: string; name: string; description: string;
+  feature_id: string; feature_name: string;
+  concept_code: string; depth: 'ulo' | 'cio' | 'sio';
+  all_keywords: string[];             // keyword ledger lives HERE, per milestone
+  new_keywords: string[];
+  prerequisite_keywords: string[];
+  steps: Step[];
+  estimated_minutes: number;
+  adjusted_minutes: number;           // estimated_minutes × overhead_factor
+  completion_level: string;
+};
 
 // Curriculum Feed (planner-ready projection)
 type CurriculumFeed = {
   schema_version: 2;
-  source: { graph_type: 'project_graph' | 'knowledge_graph' | 'hybrid_graph'; warnings: string[]; hallucination_count: number };
+  source: {
+    graph_type: 'project_graph' | 'knowledge_graph' | 'hybrid_graph';
+    warnings: string[];             // DERIVED from diagnostics (severity ≠ 'info')
+    hallucination_count: number;
+    diagnostics: FeedDiagnostic[];   // { code, severity, message, node_ids }
+    provenance?: FeedProvenance;     // providers / models / calls / degraded
+  };
   learning_nodes: FeedNode[];   // in TEACHING ORDER when phases[] is non-empty
   dependency_edges: FeedEdge[];
   suggested_groupings: FeedGrouping[];
@@ -514,6 +1044,7 @@ type FeedNode = {
   depth_variants?: { ulo: number; cio: number; sio: number };  // minutes per depth level — reconciler price list (ULO ≤ CIO ≤ SIO)
   depth_scaffold_candidates?: { from_depth: 'ulo' | 'cio' | 'sio'; to_depth: 'ulo' | 'cio' | 'sio'; minutes_saved: number; reason: string }[];  // DEPTH downgrades (SIO→CIO, CIO→ULO) — parallel to scaffold_candidates
   is_core: boolean;                          // Master-Tree core concept — never depth-downgraded; escalate instead
+  external_prerequisites: string[];          // what the learner must already know that this feed does not teach
 }
 
 type FeedPhase = {
@@ -560,6 +1091,7 @@ const profile = detectDomainProfile({
   fileExtensions?: string[];
   techStack?: string;
   gradeBand?: [number, number];
+  parsedSyllabus?: ParsedSyllabus;   // pre-parsed syllabus; skips parseSyllabus()
 });
 ```
 
@@ -576,12 +1108,13 @@ const result = await runProjectGraphPipeline({
   techStack: string;         // Required: comma-separated technologies
   llmConfig?: LlmClientConfig;
   embeddings?: Record<string, { embedding?: number[] }>;
-  sessionMinutes?: number;   // Lesson/session duration (default: 90)
-  overheadFactor?: number;   // Setup/transition overhead multiplier (default: 1.15)
-  maxMilestoneMinutes?: number; // Max minutes before splitting milestone (default: 120)
   onProgress?: (step: string, message: string) => void;
 });
 
+// NOTE: sessionMinutes / overheadFactor / maxMilestoneMinutes are NOT options here.
+// STEP_8 hardcodes 90 / 1.15 / 120 when it calls assembleRoadmap(). Call
+// assembleRoadmap() yourself if you need different values.
+
 // Returns:
 {
   projectGraph: ProjectGraph;
@@ -590,6 +1123,7 @@ const result = await runProjectGraphPipeline({
   hallucinations: Hallucination[];
   keywords: Keyword[];
   featureConcepts: Map<string, ConceptMapping[]>;
+  provenance: LlmCallRecord[];   // every provider attempt this run made
 }
 ```
 
@@ -606,17 +1140,26 @@ const result = await generateKnowledgeGraph({
   syllabusText?: string;     // Full syllabus text (multi-language supported)
   gradeBand?: [number, number];
   domain?: string;
+  techStack?: string;        // target tech for SIO keyword binding (e.g. "python")
+  knowledgeTreePath?: string; // path to mlo-knowlege-tree.tsv → enables STEP_2_5 standardization
+  proposalsPath?: string;     // where proposed-new concepts are persisted for the later merge
   llmConfig?: LlmClientConfig;
+  onProgress?: (step: string, message: string) => void;
 });
-// Internally runs: LLM decomposition → cycle detection → topological sort → depth estimation
+// Internally runs STEP_1 … STEP_6 — see [Pipeline Details](#pipeline-details).
 
 // Returns:
 {
   knowledgeGraph: KnowledgeGraph;
   warnings: string[];
+  verificationReport?: KnowledgeGraphVerificationReport;  // uncovered topics, missing ULO/CIO/SIO…
 }
 ```
 
+> Prefer `runKnowledgeGraphPipeline()` over `generateKnowledgeGraph()`: it parses the
+> syllabus, applies syllabus-derived defaults (subject, domain, grade band) and emits the
+> `CurriculumFeed` for you.
+
 ### `generateHybridGraph(options) → HybridGraphPipelineResult`
 
 Links project graph with knowledge graph.
@@ -626,13 +1169,15 @@ import { generateHybridGraph } from '@thanh01.pmt/domain-kit';
 
 const result = await generateHybridGraph({
   projectGraph: ProjectGraph;
-  knowledgeGraph: KnowledgeGraph;
+  knowledgeGraph: KnowledgeGraph;   // both are required
   llmConfig?: LlmClientConfig;
+  onProgress?: (step: string, message: string) => void;
 });
 
 // Returns:
 {
-  hybridGraph: HybridGraph;
+  hybridGraph: HybridGraph;   // links[] + phases[] + total_project_minutes /
+                              // total_concept_minutes / linked_prereq_minutes
   warnings: string[];
 }
 ```
@@ -654,8 +1199,13 @@ const feed = emitCurriculumFeed(existingFeed);         // pass-through (already
 const feed = emitCurriculumFeed(graph, {
   hallucinationCount: 3,      // metadata for source info
   warnings: ['Feature F5 had low confidence'],
+  provenance: { providers: ['nvidia'], models: ['nemotron'], calls: 7, failed_calls: 0, degraded: false },
 });
 
+// Gate on diagnostics rather than substring-matching warning text:
+const blockers = feed.source.diagnostics.filter((d) => d.severity === 'error');
+if (blockers.length) throw new Error(blockers.map((d) => d.code).join(', '));
+
 // Returns CurriculumFeed with:
 // - learning_nodes[]     — unified node format (concept | skill | product_step), in teaching order when phases[] is non-empty
 // - dependency_edges[]   — knowledge (prerequisite) or task (build order) edges
@@ -700,93 +1250,52 @@ const keywords = extractKeywords(parsedSourceContext);
 
 ## Pipeline Details
 
-### Project Graph Pipeline (Product-Driven)
+### Project Graph Pipeline (product-driven)
 
-```
-STEP 1: AST Analysis
-  → Parse all source files (Swift, TS, Python, C++)
-  → Merge by language, extract imports/types/functions/wrappers
-
-STEP 2: Keyword Extraction
-  → Filter stdlib, assign weights, tag platform (app/esp32)
-
-STEP 3: SDK API Index
-  → Build symbol index from AST results
-
-STEP 4: LLM Graph Generation
-  C0: Scaffold F0 (foundation features: tools, setup, minimal knowledge)
-  C1: Overview (features meta, journeys, architecture, development stages)
-  C2: Steps per feature (batched or per-feature LLM calls)
-
-STEP 5: Verification
-  → Remove hallucinated files, APIs, keywords not found in code
-  → F0 keywords exempt (pedagogical terms)
-
-STEP 6: Concept Escalation
-  → Map keywords → neutral concepts via LLM
-  → Classify each keyword as ULO (WHAT/WHY), CIO (HOW), or SIO (IMPLEMENTATION)
-  → Infer depth from code context (function bodies→sio, types→cio, imports→sio, docs→ulo)
-  → Join evidence files
-
-STEP 7: Concept Resolution
-  → Map concepts → Master Tree codes with ULO/CIO-aware scoring:
-    - SIO keywords matched against concept.keywords
-    - CIO keywords matched against concept.description + concept.cio
-    - ULO keywords matched against concept.ulo + concept.description
-  → Depth field propagated to resolved concepts
-
-STEP 8: Assembly
-  → Group features into phases (session-time-aware)
-  → Respect sessionMinutes, overheadFactor, maxMilestoneMinutes constraints
-  → Split large features across multiple milestones when exceeding time budget
-  → Compute all_keywords / new_keywords / prerequisite_keywords per milestone
-  → Output time_budget with total_estimated_minutes + overhead_minutes
-
-STEP 9: Feed Emission
-  → emitCurriculumFeed(graph) — pure transformation, no LLM
-  → Convert project_graph → FeedNode[] (kind: product_step) + FeatureGroupings
-  → Convert knowledge_graph → FeedNode[] (kind: concept) + CategoryGroupings
-  → Convert hybrid_graph → combined nodes + knowledge/task edges + hybrid link depth hints
-  → Project steps: project outcome.user_visible onto user_visible_deliverable (checkpoint candidate)
-  → Concept nodes: emit depth_variants (ULO ≤ CIO ≤ SIO minutes) + depth_scaffold_candidates + is_core
-  → Teaching order: when phases[] exist, nodes are emitted in phase sequence; new/prerequisite
-    keywords computed in TEACHING order (first appearance = new), never array position
-  → Preview priming: phase-declared __PREVxx awareness nodes carry keywords.all (legitimate
-    vocabulary introducer) without fabricating prerequisite edges
-  → Validate: fail-closed (duplicate IDs, edge resolution, self-loops, non-empty, duplicate
-    phase ids, and the teaching-order invariant: a prerequisite must live in the same or an
-    EARLIER phase than its consumer — a backwards edge throws at emission, never in the planner)
-```
+`runProjectGraphPipeline()` — the only pipeline whose steps live inside its orchestrator.
+Step ids below are the ones it actually logs.
 
-### Knowledge Graph Pipeline (Concept-Driven)
+| Step | What happens | Fail mode |
+|---|---|---|
+| `STEP_1` | scan the file **tree** (names only) → LLM selects relevant files → read only those → parse → merge by primary language | parse failure is per-file, non-fatal |
+| `STEP_2` | `extractKeywords()` — filter stdlib, assign weights, tag platform (`app` / `esp32`) | — |
+| `STEP_3` | SDK API index, derived from STEP_2 keywords | — |
+| `STEP_4_C0` | scaffold → feature `F0` "FOUNDATION & SETUP" | scaffold extractor returns `null`; the pipeline continues **without** F0 |
+| `STEP_4_C1` | overview → product meta (goals, users, journeys, development stages) + the feature list | — |
+| `STEP_4_C2` | steps per feature — one batched LLM call, falling back to per-feature | a feature that still fails is logged and left step-less; **no throw** |
+| `STEP_5` | `verifyProjectGraph()` — strip files / APIs / keywords not found in code; F0 keywords exempt | findings returned as `hallucinations[]`, graph is repaired |
+| `STEP_6` | `escalateAndMapConcepts()` — keyword → neutral concept + `ulo`/`cio`/`sio` + evidence files. Depth from the LLM; regex fallback on LLM failure (import → sio, code body → sio, comment → ulo) | LLM failure degrades to the regex fallback |
+| `STEP_7` | `resolveConcepts()` — concept → Master-Tree code, scored ULO/CIO-aware | unmatched keywords become `proposed` concepts |
+| `STEP_8` | `assembleRoadmap()` — milestones grouped into phases; each milestone gets `all` / `new` / `prerequisite` keywords and a time budget (90 min sessions, ×1.15 overhead, 120 min split cap — hardcoded) | — |
+
+There is **no STEP 9 here.** Feed emission happens one layer up: `runDomainPipeline()`
+calls `emitCurriculumFeed()` for the product branch, and the knowledge / hybrid
+orchestrators call it for theirs.
+
+### Knowledge Graph Pipeline (concept-driven)
+
+`generateKnowledgeGraph()` — the LLM work. Step ids as logged:
+
+| Step | What happens | Fail mode |
+|---|---|---|
+| `STEP_1` | parse the syllabus into structured units/topics, then LLM-decompose the subject into concepts, prerequisites, `problem_types`, categories | syllabus truncated at `KG_MAX_SYLLABUS_CHARS` (default 16000) + warning |
+| `STEP_2` | validate & clean — description ≥ 50 chars; **keyword registry fail-closed** (empty keywords are derived from name/description; nothing derivable → `throw`); dangling prerequisite edges removed | `throw` when keywords cannot be derived |
+| `STEP_2_5` | *only when `knowledgeTreePath` is supplied* — standardize every concept against `mlo-knowlege-tree.tsv` into `standardized` or `proposed_new`; adopted tech-stack keywords merge into the registry; tree prerequisite codes seed internal edges | missing decision for a concept → `throw` |
+| `STEP_3` | `detectPrerequisiteCycles()` → `breakPrerequisiteCycles()` at the weakest edge | warnings; edges are removed |
+| `STEP_4` | `topologicalSort()` (Kahn) — `learning_path` is **rebuilt** from the sorted order | incomplete sort → warning |
+| `STEP_5` | hierarchical ULO/CIO/SIO authoring + deterministic `ulo_code` / `cio_code` / `sio_codes` (a STEP_2_5 tree code always wins) | — |
+| `STEP_5b` | mine SIO text for tech identifiers (backticked tokens, `@Annotations`, `a.b()`, `.modifiers`, camelCase, cap 8) → merge into keywords | — |
+| `STEP_5c` | minute calibration — each signal normalised against its own cap before weighting (`0.30·sio + 0.25·problem_types + 0.20·prereqs + 0.25·highBloom`, all over `min(count/4, 1)`), `minutes = 15 + 45·score` ⇒ 15–60 min. Overrides the LLM only when the two diverge by more than 50% | — |
+| `STEP_6` | `verifyKnowledgeGraph()` — referential integrity + **reverse coverage** (every syllabus topic covered by ≥ 1 concept) | warnings, never throws |
 
-```
-STEP 1: LLM Decomposition
-  → Decompose subject into concepts with ULO/CIO/SIO
-  → Assign prerequisites
-  → Generate problem_types per concept (bloom levels)
-  → Group into categories
-
-STEP 2: Prerequisite Cycle Detection
-  → DFS to detect cycles in prerequisite graph
-  → Break cycles by removing weakest back-edges
-  → Generate warnings for each broken cycle
-
-STEP 3: Topological Sort (Kahn's Algorithm)
-  → Sort concepts in valid learning order
-  → Assign sequential order numbers
-  → Estimate concept depth per milestone (ULO→CIO→SIO progression)
-
-STEP 4: Validation
-  → Check prerequisite references exist
-  → Check learning_path references exist
-  → Generate warnings for invalid references
-
-STEP 5: Feed Emission
-  → emitCurriculumFeed(knowledgeGraph) → CurriculumFeed
-  → Concept nodes with bloom_hint (from problem_types) + depth_hint (from sio count)
-  → Category groupings for suggested lesson grouping
-```
+Feed emission is **not** a step of `generateKnowledgeGraph()` — it is the next line of
+`runKnowledgeGraphPipeline()` in `src/pipeline/`.
+
+### Hybrid Graph Pipeline (both)
+
+`generateHybridGraph()` — see [Layer 2 · Branch C](#layer-2---generate-one-branch-by-learning-mode)
+for the annotated diagram. `STEP_1` links, `STEP_2` phases (up to 3 repair attempts, then
+`throw`), `STEP_3` totals.
 
 ---
 
@@ -839,7 +1348,7 @@ profile.graphType === 'hybrid_graph'
   → You need BOTH source code AND subject description.
   → Run projectGraphPipeline() + generateKnowledgeGraph() + generateHybridGraph().
 
-profile.confidence < 0.6
+profile.confidence.domainCategory < 0.6   // confidence is an OBJECT — always compare the field
   → Low confidence. Ask the user to confirm domain category.
 
 profile.ambiguous !== undefined
@@ -955,10 +1464,10 @@ try {
 2. **Missing syllabus**: `generateKnowledgeGraph()` needs `syllabusText` to decompose concepts
 3. **Low confidence detection**: If `profile.confidence.domainCategory < 0.6`, the detection may be wrong — ask user to confirm
 4. **Ambiguous domain**: If `profile.ambiguous` is set, present both options to user (e.g., `.cpp` with ESP32 context could be software or hardware)
-5. **LLM not configured**: Graph generation (graph/, concepts/, pipeline/) requires `LLM_API_KEY` env var
+5. **LLM not configured**: graph generation needs at least one provider key — `LLM_API_KEY` / `OPENAI_API_KEY`, `DASHSCOPE_API_KEY`, `NVIDIA_API_KEY` or `OPENROUTER_API_KEY` (see [Environment Variables](#environment-variables-for-llm-features))
 6. **Large repos**: The pipeline reads up to 70 files / 500K chars — very large repos may be truncated
 7. **ULO/CIO/SIO depth**: Concept escalation now classifies keywords by depth level — ULO (intro), CIO (mechanism), SIO (implementation). This affects how `curriculum-kit` structures exposition depth per lesson
-8. **Time budget**: `assembleRoadmap()` respects `sessionMinutes` and `maxMilestoneMinutes` — large features are automatically split across milestones. Set these to match your curriculum constraints
+8. **Time budget**: `assembleRoadmap()` respects `sessionMinutes` and `maxMilestoneMinutes` — large features are automatically split across milestones. `runProjectGraphPipeline()` does **not** forward these; it hardcodes 90 / 1.15 / 120. Call `assembleRoadmap()` yourself to change them
 
 ### Available Exports
 
@@ -977,24 +1486,28 @@ import { extractKeywords } from '@thanh01.pmt/domain-kit';
 
 // Schema validation
 import {
-  ProjectGraphSchema, KnowledgeGraphSchema, HybridGraphSchema,
-  DomainProfileSchema, ConceptMappingSchema, AssembledRoadmapSchema,
-  KnowledgeConceptSchema, KnowledgeLearningPathStepSchema,
+  ProjectGraphSchema, KnowledgeGraphSchema, HybridGraphSchema, DomainProfileSchema,
+  ConceptSchema, LearningPathStepSchema, ProblemTypeSchema,
   CurriculumFeedSchema, FeedNodeSchema, FeedEdgeSchema, FeedGroupingSchema, FeedPhaseSchema,
+  validateCurriculumFeed,
 } from '@thanh01.pmt/domain-kit';
 
+// Graph verification
+import { verifyKnowledgeGraph, detectPrerequisiteCycles, breakPrerequisiteCycles, auditSyllabusCoverage }
+  from '@thanh01.pmt/domain-kit';
+
 // Roadmap assembly
 import { assembleRoadmap } from '@thanh01.pmt/domain-kit';
 
 // Concept resolution (ULO/CIO-aware)
 import { resolveConcepts } from '@thanh01.pmt/domain-kit';
 
-// Graph verification
-import { verifyProjectGraph } from '@thanh01.pmt/domain-kit';
-
 // Concept escalation (with ULO/CIO/SIO depth classification)
 import { escalateAndMapConcepts } from '@thanh01.pmt/domain-kit';
 
+// Router — detect + dispatch + emit in one call
+import { runDomainPipeline } from '@thanh01.pmt/domain-kit';
+
 // Curriculum Feed emission (any graph → planner-ready feed)
 import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
 
@@ -1002,7 +1515,7 @@ import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
 import { validateCurriculumFeed } from '@thanh01.pmt/domain-kit';
 ```
 
-> **Note:** Internal utilities like `detectCycles`, `topologicalSort`, `inferDepthFromContext` are used within the pipelines but not exported directly. They are invoked automatically during `generateKnowledgeGraph()` and concept escalation.
+> **Note:** `topologicalSort()` (Kahn) and the depth fallback (`inferDepthFromSource`) are module-private — they run inside the pipelines. `detectPrerequisiteCycles`, `breakPrerequisiteCycles` and `auditSyllabusCoverage` **are** exported, from `graph/knowledgeGraphVerifier`.
 
 ---
 
@@ -1090,6 +1603,7 @@ const knowledgeResult = await generateKnowledgeGraph({
   subject: 'Lý thuyết điện tử',
   syllabusText: profile.syllabusText,
   domain: 'science',
+  techStack: 'Arduino,ESP32',   // ← binds SIO keywords to the project's real APIs
 });
 
 // Step C