[Codegraph] Add Obsidian entrypoints dashboard

Add ranked human and agent starting points to the Obsidian export
Surface top features, layers, files, modules, and research links
Cover entrypoint navigation with generic fixtures and field validation

Author: alucardeht

CHANGELOG.md

@@ -11,6 +11,7 @@
 - Incremental refresh cache for safe changed-file rebuilds.
 - Extractor capability declarations in the manifest.
 - Markdown concept and claim extraction with inferred confidence.
+- Obsidian entrypoints dashboard for human and agent starts.
 - Obsidian research dashboard and indexes for concepts and claims.
 - Obsidian dashboards for architecture, features, and layers.
 - Operator commands for export rebuilds, Obsidian export path discovery, and

README.md

@@ -281,6 +281,7 @@ Important sections:
 
 - `index.md`: freshness, quality, totals, and navigation.
 - `Dashboards/Architecture.md`: ranked architecture summary.
+- `Dashboards/Entrypoints.md`: recommended starts for humans and agents.
 - `Dashboards/Features.md`: ranked feature summary.
 - `Dashboards/Layers.md`: ranked layer summary.
 - `Dashboards/Research.md`: concepts and claims from documentation/research.

src/codegraph/scanner.py

@@ -798,6 +798,7 @@ def write_obsidian_export(path: Path, graph_payload: dict[str, Any], manifest: d
                 "## Navigation",
                 "",
                 "- [[Dashboards/Architecture|Architecture Dashboard]]",
+                "- [[Dashboards/Entrypoints|Entrypoints Dashboard]]",
                 "- [[Dashboards/Features|Feature Dashboard]]",
                 "- [[Dashboards/Layers|Layer Dashboard]]",
                 "- [[Dashboards/Research|Research Dashboard]]",
@@ -1025,12 +1026,22 @@ def write_obsidian_dashboards(
     dashboards_dir = path / "Dashboards"
     dashboards_dir.mkdir(exist_ok=True)
     incoming_by_target: dict[str, list[dict[str, Any]]] = defaultdict(list)
+    outgoing_by_source: dict[str, list[dict[str, Any]]] = defaultdict(list)
     for edge in graph_payload["edges"]:
         incoming_by_target[edge["to"]].append(edge)
+        outgoing_by_source[edge["from"]].append(edge)
     nodes_by_kind: dict[str, list[dict[str, Any]]] = defaultdict(list)
     for node in graph_payload["nodes"]:
         nodes_by_kind[node["kind"]].append(node)
 
+    write_entrypoints_dashboard(
+        dashboards_dir / "Entrypoints.md",
+        graph_payload,
+        node_note_paths,
+        nodes_by_kind,
+        incoming_by_target,
+        outgoing_by_source,
+    )
     write_architecture_dashboard(
         dashboards_dir / "Architecture.md",
         graph_payload,
@@ -1112,6 +1123,73 @@ def write_ranked_architecture_dashboard(
     path.write_text("\n".join(lines), encoding="utf-8")
 
 
+def write_entrypoints_dashboard(
+    path: Path,
+    graph_payload: dict[str, Any],
+    node_note_paths: dict[str, str],
+    nodes_by_kind: dict[str, list[dict[str, Any]]],
+    incoming_by_target: dict[str, list[dict[str, Any]]],
+    outgoing_by_source: dict[str, list[dict[str, Any]]],
+) -> None:
+    lines = [
+        "# Entrypoints Dashboard",
+        "",
+        "## Agent Sequence",
+        "",
+        "- Run `status` before trusting the graph.",
+        "- Run `doctor` before using the graph for planning.",
+        "- Start with architecture, feature, layer, and important file entrypoints.",
+        "- Use focused source inspection after the graph narrows the area.",
+        "",
+        "## Top Features",
+        "",
+    ]
+    lines.extend(
+        render_ranked_architecture_links(
+            nodes_by_kind["feature"],
+            node_note_paths,
+            incoming_by_target,
+            limit=12,
+        )
+    )
+    lines.extend(["", "## Top Layers", ""])
+    lines.extend(
+        render_ranked_architecture_links(
+            nodes_by_kind["layer"],
+            node_note_paths,
+            incoming_by_target,
+            limit=12,
+        )
+    )
+    lines.extend(["", "## Important Files", ""])
+    lines.extend(
+        render_ranked_file_links(
+            nodes_by_kind["file"],
+            node_note_paths,
+            incoming_by_target,
+            outgoing_by_source,
+            limit=20,
+        )
+    )
+    lines.extend(["", "## External Modules", ""])
+    lines.extend(
+        render_ranked_links(
+            nodes_by_kind["module"],
+            node_note_paths,
+            incoming_by_target,
+            edge_kinds={"imports"},
+            empty_label="None",
+            limit=20,
+            suffix="importing edges",
+        )
+    )
+    if nodes_by_kind["concept"] or nodes_by_kind["claim"]:
+        lines.extend(["", "## Research", ""])
+        lines.append("- [[Dashboards/Research|Research Dashboard]]")
+    lines.append("")
+    path.write_text("\n".join(lines), encoding="utf-8")
+
+
 def write_research_dashboard(
     path: Path,
     nodes_by_kind: dict[str, list[dict[str, Any]]],
@@ -1154,6 +1232,39 @@ def write_research_dashboard(
     path.write_text("\n".join(lines), encoding="utf-8")
 
 
+def render_ranked_file_links(
+    files: list[dict[str, Any]],
+    node_note_paths: dict[str, str],
+    incoming_by_target: dict[str, list[dict[str, Any]]],
+    outgoing_by_source: dict[str, list[dict[str, Any]]],
+    *,
+    limit: int,
+) -> list[str]:
+    ranked = sorted(
+        files,
+        key=lambda node: (
+            -semantic_edge_count(node["id"], incoming_by_target, outgoing_by_source),
+            node["id"],
+        ),
+    )[:limit]
+    if not ranked:
+        return ["- None"]
+    return [
+        f"- [[{node_note_paths[node['id']]}|{node['source_path']}]] "
+        f"({semantic_edge_count(node['id'], incoming_by_target, outgoing_by_source)} semantic edges)"
+        for node in ranked
+    ]
+
+
+def semantic_edge_count(
+    node_id: str,
+    incoming_by_target: dict[str, list[dict[str, Any]]],
+    outgoing_by_source: dict[str, list[dict[str, Any]]],
+) -> int:
+    edges = incoming_by_target[node_id] + outgoing_by_source[node_id]
+    return sum(1 for edge in edges if edge["kind"] != "contains")
+
+
 def render_ranked_links(
     nodes: list[dict[str, Any]],
     node_note_paths: dict[str, str],

tests/test_codegraph.py

@@ -53,6 +53,7 @@ def test_scan_writes_graph_manifest_report_and_obsidian_export(self) -> None:
             self.assertTrue((output / "obsidian" / "Indexes" / "Features.md").is_file())
             self.assertTrue((output / "obsidian" / "Indexes" / "Layers.md").is_file())
             self.assertTrue((output / "obsidian" / "Dashboards" / "Architecture.md").is_file())
+            self.assertTrue((output / "obsidian" / "Dashboards" / "Entrypoints.md").is_file())
             self.assertTrue((output / "obsidian" / "Dashboards" / "Features.md").is_file())
             self.assertTrue((output / "obsidian" / "Dashboards" / "Layers.md").is_file())
             self.assertTrue(
@@ -109,6 +110,35 @@ def test_scan_writes_graph_manifest_report_and_obsidian_export(self) -> None:
             self.assertEqual(open_code, 0)
             self.assertEqual(open_stdout.getvalue().strip(), str((output / "obsidian").resolve()))
 
+    def test_obsidian_entrypoints_dashboard_ranks_navigation_starts(self) -> None:
+        with tempfile.TemporaryDirectory() as temp:
+            root = Path(temp)
+            target = root / "target"
+            output = root / "graph"
+            (target / "src" / "screens" / "Home").mkdir(parents=True)
+            (target / "src" / "components").mkdir(parents=True)
+            (target / "src" / "screens" / "Home" / "HomeScreen.tsx").write_text(
+                "import { Button } from '../../components/Button'\n"
+                "export function HomeScreen() { return <Button /> }\n",
+                encoding="utf-8",
+            )
+            (target / "src" / "components" / "Button.tsx").write_text(
+                "import { Clickable } from 'external-ui'\n"
+                "export function Button() { return <Clickable /> }\n",
+                encoding="utf-8",
+            )
+
+            scan(ScanOptions(target=target, output=output, export_obsidian=True))
+            entrypoints = (output / "obsidian" / "Dashboards" / "Entrypoints.md").read_text(
+                encoding="utf-8"
+            )
+            index = (output / "obsidian" / "index.md").read_text(encoding="utf-8")
+
+            self.assertIn("[[Dashboards/Entrypoints|Entrypoints Dashboard]]", index)
+            self.assertIn("## Agent Sequence", entrypoints)
+            self.assertIn("## Important Files", entrypoints)
+            self.assertIn("HomeScreen.tsx", entrypoints)
+
     def test_architecture_enrichment_links_roles_layers_and_import_relationships(self) -> None:
         with tempfile.TemporaryDirectory() as temp:
             root = Path(temp)
@@ -605,28 +635,28 @@ def test_tsx_external_named_imports_are_queryable_and_rendered(self) -> None:
             output = root / "graph"
             (target / "src").mkdir(parents=True)
             (target / "src" / "Screen.tsx").write_text(
-                "import { Pressable, TouchableOpacity } from 'react-native'\\n"
-                "export function Screen() { return <TouchableOpacity><Pressable /></TouchableOpacity> }\\n",
+                "import { Clickable, Surface } from 'external-ui'\\n"
+                "export function Screen() { return <Surface><Clickable /></Surface> }\\n",
                 encoding="utf-8",
             )
             scan(ScanOptions(target=target, output=output))
             graph = json.loads((output / "graph.json").read_text(encoding="utf-8"))
             node_ids = {node["id"] for node in graph["nodes"]}
-            self.assertIn("imported-symbol:react-native#TouchableOpacity", node_ids)
-            self.assertIn("imported-symbol:react-native#Pressable", node_ids)
+            self.assertIn("imported-symbol:external-ui#Surface", node_ids)
+            self.assertIn("imported-symbol:external-ui#Clickable", node_ids)
             self.assertTrue(
                 any(
                     edge["kind"] == "renders"
                     and edge["from"] == "file:src/Screen.tsx"
-                    and edge["to"] == "imported-symbol:react-native#TouchableOpacity"
+                    and edge["to"] == "imported-symbol:external-ui#Surface"
                     for edge in graph["edges"]
                 )
             )
             self.assertTrue(
                 any(
                     edge["kind"] == "renders"
                     and edge["from"] == "file:src/Screen.tsx"
-                    and edge["to"] == "imported-symbol:react-native#Pressable"
+                    and edge["to"] == "imported-symbol:external-ui#Clickable"
                     for edge in graph["edges"]
                 )
             )
@@ -662,8 +692,8 @@ def test_js_ts_module_forms_create_navigation_edges(self) -> None:
                 "} from 'react'\n"
                 "import type { ButtonProps } from './components/types'\n"
                 "import { Button } from './components'\n"
-                "const { TouchableOpacity, Pressable: RNPressable } = require('react-native')\n"
-                "export default function Screen() { return <><Button /><TouchableOpacity /></> }\n",
+                "const { Surface, Clickable: PrimaryClickable } = require('external-ui')\n"
+                "export default function Screen() { return <><Button /><Surface /></> }\n",
                 encoding="utf-8",
             )
 
@@ -697,16 +727,16 @@ def test_js_ts_module_forms_create_navigation_edges(self) -> None:
                 ),
                 edges,
             )
-            self.assertIn("imported-symbol:react-native#TouchableOpacity", node_ids)
-            self.assertIn("imported-symbol:react-native#RNPressable", node_ids)
+            self.assertIn("imported-symbol:external-ui#Surface", node_ids)
+            self.assertIn("imported-symbol:external-ui#PrimaryClickable", node_ids)
             self.assertIn("lexical-re-export", methods)
             self.assertIn("lexical-type-import", methods)
             self.assertIn("lexical-require", methods)
             self.assertTrue(
                 any(
                     edge["kind"] == "renders"
                     and edge["from"] == "file:src/Screen.tsx"
-                    and edge["to"] == "imported-symbol:react-native#TouchableOpacity"
+                    and edge["to"] == "imported-symbol:external-ui#Surface"
                     for edge in graph["edges"]
                 )
             )