Strengthen snapshot navigation metadata

PRD.md

@@ -703,6 +703,14 @@ Recommended MVP schema:
 interface DevMapSnapshot {
   version: string;
   generatedAt: string;
+  agentInstructions: {
+    navigationPolicy: "snapshot-first";
+    defaultMode: "minimal-exploration";
+    maxInitialFiles: number;
+    missingSnapshotAction: "run-devmap-analyze";
+    staleSnapshotAction: "run-devmap-analyze-fresh";
+    fallbackRule: string;
+  };
   project: {
     name?: string;
     root: string;
@@ -719,10 +727,24 @@ interface DevMapSnapshot {
   database?: DatabaseInfo;
   features: FeatureInfo[];
   flows: FlowInfo[];
+  onboarding: {
+    recommendedPath: string[];
+  };
+  changeImpact: Record<string, {
+    impacts: string[];
+    dependents: string[];
+  }>;
   fileIndex: Record<string, {
     hash: string;
     imports: string[];
     exportedSymbols: string[];
+    topFunctions: Array<{
+      name: string;
+      kind: "function" | "const" | "class" | "method";
+      line: number;
+      exported: boolean;
+      async: boolean;
+    }>;
     lines: number;
     purpose?: string;
     scope: "api" | "ui" | "database" | "config" | "service" | "cli" | "test" | "docs" | "unknown";
@@ -741,9 +763,18 @@ interface DevMapSnapshot {
 - Snapshot must include a schema version
 - Future schema changes must be versioned
 - File index entries should include compact navigation metadata such as
-  purpose, responsibility scope, feature references, search terms, and
-  importance. These fields help `devmap ask`, future onboarding output, and
-  future flow generation without storing full raw source.
+  purpose, responsibility scope, exported symbols, top functions/code symbols,
+  feature references, search terms, and importance. These fields help
+  `devmap ask`, future onboarding output, and future flow generation without
+  storing full raw source.
+- Flow metadata should include compact high-confidence feature flows and
+  request/API flows derived from routes and local dependency edges.
+- Feature metadata should expose a primary entry point and a short business
+  flow when DevMap can infer one from routes or dependency edges.
+- Snapshot should include a lightweight onboarding path and file-level change
+  impact map for future generated docs and safer AI-assisted edits.
+- Snapshot should include compact machine-readable agent instructions. The
+  complete agent navigation contract belongs in generated `DEVMAP.md`.
 - AI-generated file purpose and search terms must be batched and optional.
   Analyze must continue if enrichment fails.
 

README.md

@@ -37,12 +37,15 @@ The snapshot contains:
 * Architecture overview
 * Entry points
 * Critical files
-* File purpose, scope, search terms, and importance
+* File purpose, scope, top functions, search terms, and importance
 * Routes and APIs
 * External services
 * Database information
 * Detected features
-* Minimal high-confidence feature flows
+* Minimal high-confidence feature and request flows
+* Feature entry points and lightweight business flows
+* Onboarding path and file-level change impact
+* Snapshot-first agent navigation policy
 * Project relationships
 
 One analysis. Reusable context. Any codebase.

docs/architecture.md

@@ -377,6 +377,7 @@ Each `fileIndex` entry stores compact navigation metadata:
 | ----- | ------- |
 | `purpose` | One-sentence description of what the file does when available |
 | `scope` | Responsibility classification: API, UI, database, config, service, CLI, test, docs, or unknown |
+| `topFunctions` | Compact list of important functions or exported code symbols with line numbers |
 | `featureRefs` | Feature names that reference this file |
 | `searchTerms` | Retrieval-focused terms used by `devmap ask` |
 | `importance` | Static importance score from references, entry point status, critical-file score, and feature ownership |
@@ -391,9 +392,39 @@ and snapshot generation must still complete.
 ### Minimal Flows
 
 Snapshot schema includes `flows` as a foundation for future `FLOW.md`
-generation. Phase 1 only creates small feature flows for high-confidence
-features, using the feature file order as steps. It does not build a full call
-graph or separate flow analyzer.
+generation. Phase 1 creates small feature flows for high-confidence features
+and request/API flows from detected routes plus local dependency edges. Flow
+steps may include important exported symbols, but DevMap still does not build a
+full call graph or separate flow analyzer.
+
+Feature metadata also stores a primary `entryPoint` and a short
+`businessFlow` when DevMap can infer them from routes or dependencies. This
+gives future generated docs a human-oriented path through the feature, not only
+a list of files.
+
+### Onboarding and Change Impact
+
+Snapshot schema includes two lightweight navigation aids:
+
+| Field | Purpose |
+| ----- | ------- |
+| `onboarding.recommendedPath` | Ordered files a new developer or AI agent should read first |
+| `changeImpact` | File-level impacted features, flows, and direct dependents |
+
+These fields are static-first and intentionally shallow. They are meant to guide
+future `ONBOARDING.md`, `FLOW.md`, and safer edit planning without building a
+full symbol graph.
+
+### Agent Contract
+
+Generated `DEVMAP.md` contains the complete agent navigation contract. It tells
+agents to use `.devmap/snapshot.json` before broad repository exploration, to
+prefer feature entry points and flows, and to run `devmap analyze` when the
+snapshot is missing.
+
+The snapshot also stores a compact `agentInstructions` object for machine
+readers. This is intentionally small: policy fields live in JSON, while the
+human-readable workflow lives in `DEVMAP.md`.
 
 ---
 

docs/commands.md

@@ -144,9 +144,11 @@ devmap analyze --deep
 * Detect database usage
 * Detect entry points
 * Detect critical files
-* Build a compact file index with purpose, scope, search terms, feature
-  references, and importance
-* Generate minimal high-confidence feature flows
+* Build a compact file index with purpose, scope, top functions/code symbols,
+  search terms, feature references, and importance
+* Generate minimal high-confidence feature and request/API flows
+* Infer feature entry points and short business flows where possible
+* Build a lightweight onboarding path and file-level change impact map
 * Generate architecture overview
 * Save snapshot to `.devmap/snapshot.json`
 

docs/for-me-personal/PROGRESS.md

@@ -917,3 +917,34 @@ Verifikasi:
 ```powershell
 pnpm --filter devmap exec tsx --test test/analyzers.test.ts
 ```
+
+## Snapshot Function Metadata
+
+**Tanggal:** 2026-06-18
+
+Snapshot `fileIndex` sekarang menyimpan `topFunctions`, yaitu daftar ringkas
+fungsi atau symbol kode penting beserta line number, tipe symbol, status export,
+dan status async. Metadata ini menjadi fondasi untuk jawaban `ask`, onboarding,
+dan flow document tanpa harus membaca raw source terlalu banyak.
+
+Flow minimal juga mulai memakai symbol penting pada label step, sehingga flow
+lebih informatif daripada sekadar daftar file.
+
+Tahap lanjutannya menambahkan request/API flows dari route yang terdeteksi ke
+dependency lokalnya. Contoh: route API dapat menghasilkan flow
+`route.ts -> auth.ts -> db.ts`, yang nanti bisa menjadi bahan awal `FLOW.md`.
+
+Tahap berikutnya menambahkan primary feature entry point, business flow ringkas,
+`onboarding.recommendedPath`, dan `changeImpact` file-level. Ini sengaja masih
+shallow agar snapshot lebih memahami project tanpa masuk ke symbol graph penuh.
+
+Generated `DEVMAP.md` sekarang memiliki Agent Navigation Contract yang meminta
+agent memakai snapshot-first, menjalankan `devmap analyze` saat snapshot hilang,
+dan meminta user menjalankan `devmap init` jika DevMap belum terkonfigurasi.
+Snapshot juga menyimpan `agentInstructions` kecil untuk machine reader.
+
+Verifikasi:
+
+```powershell
+pnpm --filter devmap exec tsx --test test/analyzers.test.ts test/context-builder.test.ts
+```

docs/for-me-personal/TEST.md

@@ -391,7 +391,17 @@ Expected tambahan:
 
 - `.agent/` dan `.agents/` tidak masuk hasil scan;
 - `.agents/skills/*/SKILL.md` tidak terdeteksi sebagai fitur AI project;
-- snapshot tetap hanya merepresentasikan source project yang dianalisis.
+- snapshot tetap hanya merepresentasikan source project yang dianalisis;
+- `fileIndex[*].topFunctions` berisi fungsi atau symbol kode penting dengan
+  line number, status export, dan status async;
+- `flows` mencakup feature flow dan request/API flow dari route ke dependency
+  lokalnya;
+- `features[*].entryPoint` dan `features[*].businessFlow` terisi ketika bisa
+  diinfer dari route/dependency;
+- `onboarding.recommendedPath` dan `changeImpact` tersedia sebagai metadata
+  navigasi lanjutan;
+- `agentInstructions` tersedia di snapshot sebagai policy machine-readable
+  ringkas.
 
 AI client:
 

packages/cli/src/ai/contextBuilder.ts

@@ -804,7 +804,7 @@ async function readContextFile(
   return {
     ...rankedFile,
     exports: snapshot.fileIndex[rankedFile.path]?.exportedSymbols ?? [],
-    topFunctions: [],
+    topFunctions: snapshot.fileIndex[rankedFile.path]?.topFunctions ?? [],
     purpose: snapshot.fileIndex[rankedFile.path]?.purpose,
     startLine: window.start + 1,
     endLine: window.end,

packages/cli/src/analyzers/featureDetector.ts

@@ -7,7 +7,9 @@ export type FeatureInfo = {
   name: string;
   purpose: string;
   files: string[];
+  entryPoint?: string;
   entryPoints: string[];
+  businessFlow: string[];
   searchTerms: string[];
   confidence: "high" | "medium" | "low";
   evidence: string[];
@@ -80,6 +82,7 @@ function createFeatureInfo(
     name,
     purpose: `Identifies ${name.toLowerCase()} capability in the project.`,
     files,
+    businessFlow: [],
     entryPoints: [],
     searchTerms: [...new Set(terms.map((term) => term.toLowerCase()))].slice(0, 8),
     confidence: evidence.length >= 2 ? "high" : "medium",