@thanh01.pmt/domain-kit 0.1.0

package/README.md

@@ -0,0 +1,1101 @@
+# `@thanh01.pmt/domain-kit`
+
+> **Project graph generation engine** — decomposes any domain (software, hardware, math, science, language...) into structured domain graphs for curriculum planning.
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://typescriptlang.org)
+[![Zod](https://img.shields.io/badge/Zod-3.23-3248ff.svg)](https://zod.dev)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+---
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+  - [5. Emit Curriculum Feed](#5-emit-curriculum-feed-from-any-graph)
+- [Architecture](#architecture)
+- [Input → Processing → Output](#input--processing--output)
+- [Domain Detection](#domain-detection)
+  - [Ambiguous Domain Handling](#ambiguous-domain-handling)
+  - [Confidence & Fallback](#confidence--fallback)
+- [Graph Types](#graph-types)
+- [Schemas](#schemas)
+- [API Reference](#api-reference)
+- [Pipeline Details](#pipeline-details)
+- [AI Agent Guide](#ai-agent-guide)
+- [Examples](#examples)
+- [Contributing](#contributing)
+
+---
+
+## Overview
+
+`domain-kit` is a TypeScript package that analyzes a learning domain and produces a structured **domain_graph** — the single source of truth consumed by `curriculum-kit` to generate lessons, activities, assessments, and all pedagogical artifacts.
+
+**Key capabilities:**
+
+- **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
+- **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
+
+---
+
+## Installation
+
+```bash
+npm install @thanh01.pmt/domain-kit
+```
+
+Or with workspace link:
+
+```bash
+npm link @thanh01.pmt/domain-kit
+```
+
+### Peer Dependencies
+
+```json
+{
+  "zod": "^3.23.8"
+}
+```
+
+### Environment Variables (for LLM features)
+
+```bash
+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
+```
+
+---
+
+## Quick Start
+
+### 1. Detect Domain Profile
+
+```typescript
+import { detectDomainProfile } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  repoUrl: 'https://github.com/user/talky',
+  goal: 'Build iOS chat app with SwiftUI and Firebase',
+  techStack: 'Swift,SwiftUI,Firebase',
+});
+
+console.log(profile.graphType);       // 'project_graph'
+console.log(profile.domainCategory);  // 'software'
+console.log(profile.learningMode);    // 'product'
+```
+
+### 2. Generate Project Graph (Software)
+
+```typescript
+import { runProjectGraphPipeline } from '@thanh01.pmt/domain-kit';
+
+const result = await runProjectGraphPipeline({
+  repoDir: '/path/to/repo',
+  goal: 'Build iOS chat app with SwiftUI',
+  techStack: 'Swift,SwiftUI,Firebase',
+});
+
+console.log(result.projectGraph);     // ProjectGraph schema
+console.log(result.roadmap);          // AssembledRoadmap with phases
+console.log(result.keywords);         // Extracted keywords
+```
+
+### 3. Generate Knowledge Graph (Math/Science)
+
+```typescript
+import { generateKnowledgeGraph } from '@thanh01.pmt/domain-kit';
+
+const result = await generateKnowledgeGraph({
+  subject: 'Hình học K12',
+  syllabusText: 'Chương 1: Phân loại góc...\nChương 2: Tam giác...',
+  gradeBand: [6, 9],
+  domain: 'math',
+});
+
+console.log(result.knowledgeGraph);   // KnowledgeGraph schema
+```
+
+### 4. Generate Hybrid Graph
+
+```typescript
+import { generateHybridGraph } from '@thanh01.pmt/domain-kit';
+
+const result = await generateHybridGraph({
+  projectGraph: existingProjectGraph,
+  knowledgeGraph: existingKnowledgeGraph,
+});
+
+console.log(result.hybridGraph);      // HybridGraph with links[]
+```
+
+### 5. Emit Curriculum Feed (from any graph)
+
+```typescript
+import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
+
+const feed = emitCurriculumFeed(result.projectGraph);  // or knowledgeGraph or hybridGraph
+
+console.log(feed.learning_nodes.length);    // unified nodes ready for planner
+console.log(feed.dependency_edges.length);  // knowledge + task edges
+console.log(feed.suggested_groupings);      // feature/category groupings
+// Each node has: bloom_hint, depth_hint, keywords.new/.prerequisite
+```
+
+---
+
+## 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    │                                           │
+│  └──────────────┘                                           │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Input → Processing → Output
+
+### Input
+
+User provides **one or more** of:
+
+| Field | Type | Description |
+|---|---|---|
+| `repoUrl` | `string` | Git repository URL |
+| `repoDir` | `string` | Local repository path |
+| `goal` | `string` | Learning goal or project description |
+| `description` | `string` | Subject/project description |
+| `syllabusText` | `string` | Syllabus or curriculum text |
+| `chapters` | `string[]` | Chapter/section names |
+| `techStack` | `string` | Comma-separated technologies |
+| `fileExtensions` | `string[]` | File extensions in repo |
+| `gradeBand` | `[number, number]` | Target grade range |
+
+### Processing
+
+```
+Input
+  │
+  ▼
+Step 1: DETECT
+  ├── detectInputType()       → repository | syllabus | description | files | mixed
+  ├── detectDomain()          → software | hardware_iot | math | science | ...
+  │     └── context-dependent: .cpp→software (default), hardware only with ESP32/Arduino context
+  ├── detectLearningMode()    → product | concept | hybrid
+  └── → DomainProfile (with ambiguity flag if domains overlap)
+  │
+Step 2: ROUTE (by graphType)
+  │
+  ├── project_graph   → parsers → extractors → graph/LLM → verify → concepts → assembly
+  ├── knowledge_graph → LLM decompose → ULO/CIO/SIO → cycle detect → topo sort → problem_types
+  └── hybrid_graph    → project_graph + knowledge_graph + LLM link features↔concepts
+  │
+Step 3: OUTPUT
+  └── domain_graph.json
+```
+
+### Output
+
+Always **one of three schemas**:
+
+| Graph Type | Schema | When |
+|---|---|---|
+| `project_graph` | `ProjectGraph` | Product-driven (software, hardware, 3D design) |
+| `knowledge_graph` | `KnowledgeGraph` | Concept-driven (math, science, language) |
+| `hybrid_graph` | `HybridGraph` | Both product + concept linked |
+
+---
+
+## Domain Detection
+
+### How it works
+
+`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)
+3. **Learning Mode Detector** — Combines input signals + domain heuristics + verb patterns
+
+### Ambiguous Domain Handling
+
+Some file extensions map to multiple domains (e.g., `.cpp` → software or hardware). The detector:
+
+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
+
+### Domain Categories
+
+| Category | Examples | Keywords (sample) |
+|---|---|---|
+| `software` | App, web, API | swift, react, typescript, docker |
+| `hardware_iot` | Arduino, robotics | arduino, sensor, ESP32, GPIO |
+| `3d_design` | Tinkercad, Fusion360 | shape, dimension, STL, CAD |
+| `math` | Hình học, đại số | tam giác, phương trình, calculus |
+| `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 |
+| `other` | Fallback | — |
+
+### Confidence & Fallback
+
+```typescript
+const profile = detectDomainProfile({ ... });
+
+// Check for ambiguous detection
+if (profile.ambiguous) {
+  // E.g., { domain1: 'software', domain2: 'hardware_iot', reason: 'C++ files + ESP32 context' }
+  // → Ask user to confirm which domain
+}
+
+if (profile.confidence.domainCategory < 0.6) {
+  // Low confidence — ask user to confirm
+}
+
+if (profile.domainCategory === 'other') {
+  // Unknown domain — ask user to specify
+}
+```
+
+---
+
+## Graph Types
+
+### Project Graph (Product-Driven)
+
+For projects where the learner **builds something**: apps, robots, 3D models.
+
+```json
+{
+  "project": { "id": "...", "tech_stack": {...} },
+  "product": { "goals": [...], "development_stages": [...] },
+  "features": [
+    {
+      "id": "F1",
+      "name": "Authentication",
+      "steps": [
+        {
+          "id": "F1-S1",
+          "name": "Implement AuthViewModel",
+          "keywords": ["@Published", "@EnvironmentObject"],
+          "api_usage": ["FirebaseAuth"],
+          "effort": { "estimated_minutes": 30 }
+        }
+      ]
+    }
+  ]
+}
+```
+
+### Knowledge Graph (Concept-Driven)
+
+For subjects where the learner **understands concepts**: math, science, language.
+
+```json
+{
+  "subject": { "id": "geometry-k12", "domain": "math" },
+  "concepts": [
+    {
+      "id": "G1",
+      "name": "Angle Classification",
+      "ulo": "WHAT: Angles are... WHY: We classify to compare...",
+      "cio": "HOW: Measured in degrees, compared using protractor...",
+      "sio": ["protractor usage", "angle notation"],
+      "prerequisites": [],
+      "problem_types": [{ "bloom_level": "Remember", "difficulty": "easy" }]
+    }
+  ],
+  "learning_path": [
+    { "concept_id": "G1", "order": 1 },
+    { "concept_id": "G2", "order": 2, "depends_on": ["G1"] }
+  ]
+}
+```
+
+### Hybrid Graph
+
+For projects that require **both building and understanding**.
+
+```json
+{
+  "project_graph": { ... },
+  "knowledge_graph": { ... },
+  "links": [
+    {
+      "feature_id": "F2",
+      "concept_id": "G3",
+      "relationship": "requires",
+      "depth": "cio",
+      "estimated_prereq_minutes": 30
+    }
+  ]
+}
+```
+
+---
+
+## Schemas
+
+All schemas are Zod-validated TypeScript types.
+
+| Schema | File | Purpose |
+|---|---|---|
+| `ProjectGraphSchema` | `projectGraphSchema.ts` | Software/hardware/3D project structure |
+| `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) |
+| `CurriculumFeedSchema` | `curriculumFeedSchema.ts` | Planner-ready normalized feed (nodes, edges, groupings) |
+| `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) |
+
+### Key Types
+
+```typescript
+// Project Graph
+type ProjectGraph = {
+  project: ProjectInfo;
+  product: Product;
+  features: Feature[];
+  implementation: { tasks: Task[] };
+}
+
+type Feature = {
+  id: string;
+  name: string;
+  steps: Step[];
+  depends_on: string[];
+}
+
+type Step = {
+  id: string;
+  name: string;
+  keywords: string[];
+  api_usage: string[];
+  completion_level: 'base' | 'mvp' | 'extend' | 'polish';
+  effort: { estimated_minutes: number; complexity: 'low' | 'medium' | 'high' };
+}
+
+// Knowledge Graph
+type KnowledgeGraph = {
+  subject: SubjectInfo;
+  concepts: Concept[];
+  categories: ConceptCategory[];
+  learning_path: LearningPathStep[];
+}
+
+type Concept = {
+  id: string;
+  name: string;
+  ulo: string;      // WHAT + WHY
+  cio: string;       // HOW
+  sio: string[];     // Specific implementations
+  prerequisites: string[];
+  problem_types: ProblemType[];
+}
+
+// Domain Detection
+type DomainProfile = {
+  inputType: 'repository' | 'syllabus' | 'description' | 'files' | 'mixed';
+  domainCategory: 'software' | 'math' | 'science' | ...;
+  learningMode: 'product' | 'concept' | 'hybrid';
+  graphType: 'project_graph' | 'knowledge_graph' | 'hybrid_graph';
+  confidence: { inputType: number; domainCategory: number; learningMode: number };
+  ambiguous?: { domain1: DomainCategory; domain2: DomainCategory; reason: string };
+}
+
+// Concept Escalation (ULO/CIO/SIO depth)
+type ConceptMapping = {
+  keyword: string;
+  concept_code: string;
+  concept_name: string;
+  depth: 'ulo' | 'cio' | 'sio';     // WHAT (ulo), HOW (cio), IMPLEMENTATION (sio)
+  rationale: string;
+  evidence_files: string[];
+}
+
+// Assembled Roadmap (with time budget)
+type AssembledRoadmap = {
+  phases: Phase[];
+  all_keywords: string[];
+  new_keywords: string[];
+  prerequisite_keywords: string[];
+  time_budget: {
+    total_estimated_minutes: number;
+    overhead_minutes: number;
+    session_minutes: number;
+  };
+}
+
+// Curriculum Feed (planner-ready projection)
+type CurriculumFeed = {
+  schema_version: 2;
+  source: { graph_type: 'project_graph' | 'knowledge_graph' | 'hybrid_graph'; warnings: string[]; hallucination_count: number };
+  learning_nodes: FeedNode[];
+  dependency_edges: FeedEdge[];
+  suggested_groupings: FeedGrouping[];
+}
+
+type FeedNode = {
+  id: string;
+  kind: 'skill' | 'concept' | 'product_step';
+  name: string;
+  concept_codes: string[];
+  keywords: { all: string[]; new: string[]; prerequisite: string[] };
+  estimated_minutes: number;
+  bloom_hint: 'Remember' | 'Understand' | 'Apply' | 'Analyze' | 'Evaluate' | 'Create' | null;
+  depth_hint: 'ulo' | 'cio' | 'sio' | null;
+  completion_level: 'mvp' | 'standard' | 'stretch';
+  scaffolding: { scaffold_candidates: ScaffoldCandidate[]; core_value_minutes: number };
+  references: { file: string; evidence: string }[];
+  feature_id: string | null;
+  concept_ref: string | null;
+}
+
+type FeedEdge = {
+  from: string;   // node id
+  to: string;     // node id
+  kind: 'knowledge' | 'task';
+  reason: string;
+}
+
+type FeedGrouping = {
+  id: string;
+  name: string;
+  node_ids: string[];
+  rationale: string;
+}
+```
+
+---
+
+## API Reference
+
+### `detectDomainProfile(options) → DomainProfile`
+
+Detects input type, domain category, learning mode, and graph type.
+
+```typescript
+import { detectDomainProfile } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  repoUrl?: string;
+  repoDir?: string;
+  goal?: string;
+  description?: string;
+  syllabusText?: string;
+  chapters?: string[];
+  fileExtensions?: string[];
+  techStack?: string;
+  gradeBand?: [number, number];
+});
+```
+
+### `runProjectGraphPipeline(options) → PipelineResult`
+
+Full pipeline for product-driven projects. Requires source code repository.
+
+```typescript
+import { runProjectGraphPipeline } from '@thanh01.pmt/domain-kit';
+
+const result = await runProjectGraphPipeline({
+  repoDir: string;           // Required: local repo path
+  goal: string;              // Required: project goal
+  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;
+});
+
+// Returns:
+{
+  projectGraph: ProjectGraph;
+  resolvedConcepts: ResolveConceptsResult;
+  roadmap: AssembledRoadmap;
+  hallucinations: Hallucination[];
+  keywords: Keyword[];
+  featureConcepts: Map<string, ConceptMapping[]>;
+}
+```
+
+### `generateKnowledgeGraph(options) → KnowledgeGraphPipelineResult`
+
+Generates knowledge graph for concept-driven subjects.
+
+```typescript
+import { generateKnowledgeGraph } from '@thanh01.pmt/domain-kit';
+
+const result = await generateKnowledgeGraph({
+  subject: string;           // Required: subject name
+  description?: string;
+  syllabusText?: string;     // Full syllabus text (multi-language supported)
+  gradeBand?: [number, number];
+  domain?: string;
+  llmConfig?: LlmClientConfig;
+});
+// Internally runs: LLM decomposition → cycle detection → topological sort → depth estimation
+
+// Returns:
+{
+  knowledgeGraph: KnowledgeGraph;
+  warnings: string[];
+}
+```
+
+### `generateHybridGraph(options) → HybridGraphPipelineResult`
+
+Links project graph with knowledge graph.
+
+```typescript
+import { generateHybridGraph } from '@thanh01.pmt/domain-kit';
+
+const result = await generateHybridGraph({
+  projectGraph: ProjectGraph;
+  knowledgeGraph: KnowledgeGraph;
+  llmConfig?: LlmClientConfig;
+});
+
+// Returns:
+{
+  hybridGraph: HybridGraph;
+  warnings: string[];
+}
+```
+
+### `emitCurriculumFeed(graph, opts?) → CurriculumFeed`
+
+Converts any domain graph (project, knowledge, or hybrid) into a unified, planner-ready `CurriculumFeed`. Pure transformation — no LLM calls. Validates output (fail-closed).
+
+```typescript
+import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
+
+// From any graph type:
+const feed = emitCurriculumFeed(projectGraph);        // project_graph
+const feed = emitCurriculumFeed(knowledgeGraph);      // knowledge_graph
+const feed = emitCurriculumFeed(hybridGraph);          // hybrid_graph
+const feed = emitCurriculumFeed(existingFeed);         // pass-through (already a feed)
+
+// With options:
+const feed = emitCurriculumFeed(graph, {
+  hallucinationCount: 3,      // metadata for source info
+  warnings: ['Feature F5 had low confidence'],
+});
+
+// Returns CurriculumFeed with:
+// - learning_nodes[]     — unified node format (concept | skill | product_step)
+// - dependency_edges[]   — knowledge (prerequisite) or task (build order) edges
+// - suggested_groupings[] — feature or category groupings
+// - Each node has: bloom_hint, depth_hint (ulo/cio/sio), keywords.new vs .prerequisite
+```
+
+**Key behaviors:**
+- **Hybrid graphs**: concepts emitted first (prerequisite-first), then project steps; hybrid links carry depth hint onto step nodes; `estimated_prereq_minutes` accumulated per concept node
+- **Knowledge graphs**: concepts + prerequisite edges + category groupings
+- **Project graphs**: features → steps + depends_on edges + feature groupings
+- **Pass-through**: if input already has `learning_nodes[]`, validates and returns as-is
+- **Legacy rejection**: throws descriptive error if graph has `implementation.tasks` but no `features[].steps` (old knowledge-tree format)
+- **New/prerequisite keywords**: computed in emission order — first appearance = new, seen before = prerequisite
+
+### Parsers
+
+```typescript
+import { parseSwiftFile, parseTsFile, parsePythonFile, parseCppFile } from '@thanh01.pmt/domain-kit';
+
+const swiftResult = parseSwiftFile('AuthViewModel.swift', fileContent);
+// → { imports: ['SwiftUI', 'FirebaseAuth'], types: [...], functions: [...] }
+```
+
+### Keyword Extraction
+
+```typescript
+import { extractKeywords } from '@thanh01.pmt/domain-kit';
+
+const keywords = extractKeywords(parsedSourceContext);
+// → [{ keyword: 'SwiftUI', source: 'import', weight: 1.0, platform: 'app' }]
+```
+
+---
+
+## Pipeline Details
+
+### 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
+  → Compute new/prerequisite keywords in emission order
+  → Validate: fail-closed (duplicate IDs, edge resolution, self-loops, non-empty)
+```
+
+### Knowledge Graph Pipeline (Concept-Driven)
+
+```
+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
+```
+
+---
+
+## AI Agent Guide
+
+> **This section is specifically for AI agents that need to use domain-kit programmatically.**
+
+### When to Use domain-kit
+
+Use `domain-kit` when you need to:
+
+1. **Analyze a project** and understand what it builds, what technologies it uses, what concepts it teaches
+2. **Decompose a subject** into structured learning concepts with prerequisites
+3. **Generate a domain graph** that `curriculum-kit` can consume to create lessons, activities, assessments
+
+### Step-by-Step Usage
+
+#### Step 1: Detect the Domain
+
+**Always start here.** This tells you what kind of input you have and what graph type to generate.
+
+```typescript
+import { detectDomainProfile } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  // Provide whatever the user gave you:
+  repoUrl: userRepoUrl,
+  goal: userGoal,
+  techStack: userTechStack,
+  description: userDescription,
+  syllabusText: userSyllabus,
+});
+
+// Check the result:
+console.log(profile.graphType);      // ← THIS determines your next step
+console.log(profile.domainCategory); // ← THIS tells you the domain
+console.log(profile.confidence);     // ← Check if confidence is high enough
+```
+
+**Decision tree after detection:**
+
+```
+profile.graphType === 'project_graph'
+  → You need source code. Proceed with runProjectGraphPipeline().
+
+profile.graphType === 'knowledge_graph'
+  → You need subject description or syllabus. Proceed with generateKnowledgeGraph().
+
+profile.graphType === 'hybrid_graph'
+  → You need BOTH source code AND subject description.
+  → Run projectGraphPipeline() + generateKnowledgeGraph() + generateHybridGraph().
+
+profile.confidence < 0.6
+  → Low confidence. Ask the user to confirm domain category.
+
+profile.ambiguous !== undefined
+  → Domain is ambiguous (e.g., .cpp could be software or hardware).
+  → Present both options to user with the reason.
+
+profile.domainCategory === 'other'
+  → Unknown domain. Ask the user what domain this is.
+```
+
+#### Step 2: Generate the Graph
+
+**For project_graph (product-driven):**
+
+```typescript
+import { runProjectGraphPipeline } from '@thanh01.pmt/domain-kit';
+
+// REQUIRES: source code directory
+const result = await runProjectGraphPipeline({
+  repoDir: '/path/to/cloned/repo',  // Must be a real directory with source files
+  goal: profile.goal,
+  techStack: profile.detectedTechStack.join(',') || 'auto',
+});
+
+// result.projectGraph ← feed this to curriculum-kit
+// result.roadmap      ← has phases, milestones, keyword tracking
+// result.keywords     ← all extracted keywords
+// result.hallucinations ← items that were removed during verification
+```
+
+**For knowledge_graph (concept-driven):**
+
+```typescript
+import { generateKnowledgeGraph } from '@thanh01.pmt/domain-kit';
+
+// REQUIRES: subject name + syllabus text
+const result = await generateKnowledgeGraph({
+  subject: profile.detectedSubject || 'Unknown Subject',
+  syllabusText: profile.syllabusText,  // ← MUST have syllabus text
+  gradeBand: profile.detectedGradeBand,
+  domain: profile.domainCategory,
+});
+
+// result.knowledgeGraph ← feed this to curriculum-kit
+// result.warnings       ← check for invalid references
+```
+
+**For hybrid_graph:**
+
+```typescript
+import { runProjectGraphPipeline, generateKnowledgeGraph, generateHybridGraph } from '@thanh01.pmt/domain-kit';
+
+// Step A: Generate project graph
+const projectResult = await runProjectGraphPipeline({
+  repoDir: profile.repoDir,
+  goal: profile.goal,
+  techStack: profile.detectedTechStack.join(','),
+});
+
+// Step B: Generate knowledge graph
+const knowledgeResult = await generateKnowledgeGraph({
+  subject: profile.detectedSubject,
+  syllabusText: profile.syllabusText,
+});
+
+// Step C: Link them
+const hybridResult = await generateHybridGraph({
+  projectGraph: projectResult.projectGraph,
+  knowledgeGraph: knowledgeResult.knowledgeGraph,
+});
+
+// hybridResult.hybridGraph ← feed this to curriculum-kit
+```
+
+#### Step 3: Hand Off to curriculum-kit
+
+The output of domain-kit (`project_graph.json`, `knowledge_graph.json`, or `hybrid_graph.json`) is consumed by curriculum-kit:
+
+```typescript
+// In curriculum-kit:
+import { convertRoadmapToFoundationSot } from '@thanh01.pmt/curriculum-kit';
+
+// For project_graph:
+const sot = convertRoadmapToFoundationSot(roadmapJson, projectGraphJson);
+
+// curriculum-kit then generates:
+// - LESSON.md (5E lesson plan)
+// - ACT.md (activity lab)
+// - SLIDE.md (slide deck)
+// - QUIZ.md (diagnostic quiz)
+// - etc.
+```
+
+### Error Handling
+
+```typescript
+try {
+  const result = await runProjectGraphPipeline({ repoDir, goal, techStack });
+} catch (err) {
+  if (err instanceof LlmClientError) {
+    // LLM API error — check API key, model, rate limits
+    console.error('LLM error:', err.message, err.status);
+  } else {
+    // Other errors — file not found, parse error, etc.
+    console.error('Pipeline error:', err);
+  }
+}
+```
+
+### Common Pitfalls
+
+1. **Missing repo directory**: `runProjectGraphPipeline()` requires `repoDir` to exist and contain source files
+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
+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
+
+### Available Exports
+
+```typescript
+// Detection
+import { detectDomainProfile, detectInputType, detectDomain, detectLearningMode } from '@thanh01.pmt/domain-kit';
+
+// Graph generation
+import { runProjectGraphPipeline, generateKnowledgeGraph, generateHybridGraph } from '@thanh01.pmt/domain-kit';
+
+// Parsers
+import { parseSwiftFile, parseTsFile, parsePythonFile, parseCppFile } from '@thanh01.pmt/domain-kit';
+
+// Keyword extraction
+import { extractKeywords } from '@thanh01.pmt/domain-kit';
+
+// Schema validation
+import {
+  ProjectGraphSchema, KnowledgeGraphSchema, HybridGraphSchema,
+  DomainProfileSchema, ConceptMappingSchema, AssembledRoadmapSchema,
+  KnowledgeConceptSchema, KnowledgeLearningPathStepSchema,
+  CurriculumFeedSchema, FeedNodeSchema, FeedEdgeSchema, FeedGroupingSchema,
+} 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';
+
+// Curriculum Feed emission (any graph → planner-ready feed)
+import { emitCurriculumFeed } from '@thanh01.pmt/domain-kit';
+
+// Feed schema validation
+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.
+
+---
+
+## Examples
+
+### Example 1: iOS App Project
+
+```typescript
+import { detectDomainProfile, runProjectGraphPipeline } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  repoUrl: 'https://github.com/thanh01/Talky',
+  goal: 'Build iOS chat app with SwiftUI and Firebase',
+  techStack: 'Swift,SwiftUI,Firebase',
+});
+// → { graphType: 'project_graph', domainCategory: 'software' }
+
+const result = await runProjectGraphPipeline({
+  repoDir: '/tmp/talky',
+  goal: profile.goal,
+  techStack: profile.detectedTechStack.join(','),
+});
+
+// result.projectGraph.features = [
+//   { id: 'F0', name: 'FOUNDATION & SETUP', steps: [...] },
+//   { id: 'F1', name: 'Welcome & Onboarding', steps: [...] },
+//   { id: 'F2', name: 'Authentication', steps: [...] },
+//   ...
+// ]
+```
+
+### Example 2: Math Syllabus
+
+```typescript
+import { detectDomainProfile, generateKnowledgeGraph } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  syllabusText: `
+    Chương 1: Phân loại góc (nhọn, vuông, tù, bẹt)
+    Chương 2: Tổng ba góc trong tam giác = 180°
+    Chương 3: Tam giác cân, tam giác đều
+    Chương 4: Định lý Pytago
+  `,
+  goal: 'Hiểu và vận dụng kiến thức hình học',
+  gradeBand: [6, 9],
+});
+// → { graphType: 'knowledge_graph', domainCategory: 'math' }
+
+const result = await generateKnowledgeGraph({
+  subject: 'Hình học K12',
+  syllabusText: profile.syllabusText,
+  gradeBand: profile.detectedGradeBand,
+  domain: 'math',
+});
+
+// result.knowledgeGraph.concepts = [
+//   { id: 'G1', name: 'Phân loại góc', ulo: '...', cio: '...', sio: [...] },
+//   { id: 'G2', name: 'Tổng 3 góc tam giác', prerequisites: ['G1'], ... },
+//   ...
+// ]
+```
+
+### Example 3: Arduino Robot (Hybrid)
+
+```typescript
+import { detectDomainProfile, runProjectGraphPipeline, generateKnowledgeGraph, generateHybridGraph } from '@thanh01.pmt/domain-kit';
+
+const profile = detectDomainProfile({
+  repoUrl: 'https://github.com/user/arduino-robot',
+  goal: 'Build Arduino robot và hiểu lý thuyết điện tử',
+  techStack: 'Arduino,ESP32',
+  syllabusText: 'Lý thuyết: Ohm\'s law, PWM, I2C communication',
+});
+// → { graphType: 'hybrid_graph', domainCategory: 'hardware_iot' }
+
+// Step A
+const projectResult = await runProjectGraphPipeline({
+  repoDir: '/tmp/arduino-robot',
+  goal: profile.goal,
+  techStack: profile.detectedTechStack.join(','),
+});
+
+// Step B
+const knowledgeResult = await generateKnowledgeGraph({
+  subject: 'Lý thuyết điện tử',
+  syllabusText: profile.syllabusText,
+  domain: 'science',
+});
+
+// Step C
+const hybridResult = await generateHybridGraph({
+  projectGraph: projectResult.projectGraph,
+  knowledgeGraph: knowledgeResult.knowledgeGraph,
+});
+
+// hybridResult.hybridGraph.links = [
+//   { feature_id: 'F2', concept_id: 'E1', relationship: 'requires', depth: 'cio' },
+//   { feature_id: 'F3', concept_id: 'E2', relationship: 'applies', depth: 'sio' },
+//   ...
+// ]
+```
+
+---
+
+## Contributing
+
+1. Fork the repository
+2. Create feature branch: `git checkout -b feature/my-feature`
+3. Commit changes: `git commit -m 'Add my feature'`
+4. Push to branch: `git push origin feature/my-feature`
+5. Open Pull Request
+
+### Development
+
+```bash
+cd packages/domain-kit
+npm install
+npm run typecheck    # Check types
+npm test             # Run tests
+npm run build        # Build dist/
+```
+
+---
+
+## License
+
+MIT © LearnWell Platform Team