docs(examples): worked graph-exploration walkthrough (Cypher -> GDS -> embeddings)

docs/examples/exploration-diagrams/01-method-escalation.dot

@@ -0,0 +1,24 @@
+digraph MethodEscalation {
+  rankdir=LR;
+  bgcolor="white";
+  node [shape=box, style="rounded,filled", fontname="Helvetica", fontsize=11, margin="0.18,0.10"];
+  edge [fontname="Helvetica", fontsize=9, color="#555555"];
+  labelloc="t"; fontsize=16; fontname="Helvetica-Bold";
+  label="How the search escalated: plain question -> Cypher -> GDS -> Embeddings";
+
+  q     [label="Plain-language\nquestion\n(\"who works with whom?\")", fillcolor="#fef3c7", color="#d97706"];
+  cy    [label="Rung 1: CYPHER\ngraph queries\n(co-occurrence,\ndelegation, tool profiles)", fillcolor="#dbeafe", color="#2563eb"];
+  gds   [label="Rung 2: NEO4J GDS\nproject.cypher + knn +\nlouvain + pageRank\n(+ APOC helpers)", fillcolor="#dcfce7", color="#16a34a"];
+  neg   [label="Rung 3: negative result\ntool-behaviour clusters\n!= objectives\n(machinery, not mission)", fillcolor="#ffe4e6", color="#e11d48"];
+  emb   [label="Rung 4: EMBEDDINGS\nOpenAI text-embedding-3-small\n(1536-d) + k-means\non 3,199 first-prompts", fillcolor="#ede9fe", color="#7c3aed"];
+  disc  [label="DISCOVERY\ncoherent objective clusters\n(review / implement / git / build)", shape=box, style="rounded,filled,bold", fillcolor="#fde68a", color="#b45309"];
+
+  q -> cy -> gds -> neg -> emb -> disc;
+
+  steer1 [label="steering:\n\"any root/forked/sub session\"", shape=note, fillcolor="#f1f5f9", color="#94a3b8", fontsize=9];
+  steer2 [label="steering:\n\"neo4j community, GDS free\"\n+ \"use the private destination\"", shape=note, fillcolor="#f1f5f9", color="#94a3b8", fontsize=9];
+  steer3 [label="steering:\n\"read the inline prompts;\nuse OpenAI models\"", shape=note, fillcolor="#f1f5f9", color="#94a3b8", fontsize=9];
+  steer1 -> cy  [style=dashed, arrowhead=none, color="#94a3b8"];
+  steer2 -> gds [style=dashed, arrowhead=none, color="#94a3b8"];
+  steer3 -> emb [style=dashed, arrowhead=none, color="#94a3b8"];
+}

docs/examples/exploration-diagrams/02-agent-cooccurrence.dot

@@ -0,0 +1,52 @@
+digraph AgentCooccurrence {
+  rankdir=TB; bgcolor="white"; nodesep=0.35; ranksep=0.7; splines=true;
+  node [shape=box, style="filled,rounded", fontname="Helvetica", fontsize=11, penwidth=1.2];
+  edge [fontname="Helvetica", fontsize=8, dir=none];
+  labelloc="t"; fontsize=15; fontname="Helvetica-Bold";
+  label="Agent co-occurrence -> GDS Louvain communities + PageRank hubs (private, 43 agents)";
+
+  // hubs (top rank) -- connective glue, top PageRank
+  { rank=same;
+    gitops   [label="git-ops\nPageRank 5.55", fillcolor="#f59e0b", fontsize=13];
+    explorer [label="explorer\nPageRank 5.50", fillcolor="#f59e0b", fontsize=13];
+    builder  [label="modular-builder\nPageRank 3.11", fillcolor="#fbbf24", fontsize=12];
+  }
+
+  subgraph cluster_c3 {
+    label="Community 3 — foundation build/investigate core (19)"; fontsize=10;
+    style="rounded,filled"; fillcolor="#f0fdf4"; color="#86efac";
+    zen [label="zen-architect", fillcolor="#bbf7d0"];
+    bughunt [label="bug-hunter", fillcolor="#bbf7d0"];
+    ganalyst [label="graph-analyst", fillcolor="#bbf7d0"];
+    dtu [label="dtu-profile-builder", fillcolor="#bbf7d0"];
+    sessan [label="session-analyst", fillcolor="#bbf7d0"];
+  }
+  subgraph cluster_c11 {
+    label="Community 11 — superpowers TDD pipeline (14)"; fontsize=10;
+    style="rounded,filled"; fillcolor="#eff6ff"; color="#93c5fd";
+    impl [label="implementer", fillcolor="#bfdbfe"];
+    plan [label="plan-writer", fillcolor="#bfdbfe"];
+    crev [label="code-reviewer", fillcolor="#bfdbfe"];
+    fileops [label="file-ops", fillcolor="#bfdbfe"];
+  }
+  subgraph cluster_c23 {
+    label="Community 23 — research / expert consult (6)"; fontsize=10;
+    style="rounded,filled"; fillcolor="#faf5ff"; color="#d8b4fe";
+    webres [label="web-research", fillcolor="#e9d5ff"];
+    setupdtu [label="setup-digital-twin", fillcolor="#e9d5ff"];
+    secg [label="security-guardian", fillcolor="#e9d5ff"];
+  }
+
+  // top co-occurring edges (weights = sessions together)
+  explorer -> gitops  [label="69", penwidth=4.0, color="#334155"];
+  gitops -> builder   [label="34", penwidth=2.6, color="#334155"];
+  explorer -> builder [label="32", penwidth=2.5, color="#334155"];
+  bughunt -> gitops   [label="21", penwidth=1.8, color="#64748b"];
+  setupdtu -> gitops  [label="17", penwidth=1.6, color="#64748b"];
+  ganalyst -> explorer[label="14", penwidth=1.4, color="#64748b"];
+
+  gitops -> zen [color="#a7f3d0"]; gitops -> sessan [color="#a7f3d0"]; explorer -> dtu [color="#a7f3d0"];
+  impl -> plan [color="#bfdbfe"]; impl -> crev [color="#bfdbfe"]; impl -> fileops [color="#bfdbfe"];
+  webres -> secg [color="#e9d5ff"];
+  builder -> impl [style=dashed, color="#cbd5e1"];
+}

docs/examples/exploration-diagrams/03-delegation-star.dot

@@ -0,0 +1,34 @@
+digraph DelegationStar {
+  rankdir=LR; bgcolor="white"; nodesep=0.25; ranksep=1.3; splines=true;
+  node [shape=box, style="filled,rounded", fontname="Helvetica", fontsize=11];
+  edge [color="#94a3b8", fontname="Helvetica", fontsize=9];
+  labelloc="t"; fontsize=15; fontname="Helvetica-Bold";
+  label="Delegation topology: a STAR from root sessions (94%) -> most-delegated-to agents (PageRank)";
+
+  root [label="ROOT / MAIN sessions\n(agent = NULL)\n94.2% of all\n2,598 delegations", shape=box, style="filled,bold,rounded", fillcolor="#fca5a5", color="#b91c1c", fontsize=13, width=2.0];
+
+  { rank=same;
+    gitops   [label="git-ops\nin-deg 479 | PR 6.91", fillcolor="#f59e0b", fontsize=12];
+    explorer [label="explorer\nin-deg 228 | PR 4.35", fillcolor="#fbbf24", fontsize=12];
+    builder  [label="modular-builder\nin-deg 174 | PR 1.29", fillcolor="#fde68a"];
+    ganalyst [label="graph-analyst\nin-deg 71 | PR 1.26", fillcolor="#fde68a"];
+    impl     [label="implementer\nin-deg 59", fillcolor="#fef3c7"];
+    deploy   [label="deployment-guide\nin-deg 47", fillcolor="#fef3c7"];
+    bughunt  [label="bug-hunter\nin-deg 36", fillcolor="#fef3c7"];
+  }
+
+  root -> gitops   [penwidth=5.0, color="#475569"];
+  root -> explorer [penwidth=3.2, color="#475569"];
+  root -> builder  [penwidth=2.6];
+  root -> ganalyst [penwidth=1.6];
+  root -> impl     [penwidth=1.4];
+  root -> deploy   [penwidth=1.2];
+  root -> bughunt  [penwidth=1.2];
+
+  // the rare agent->agent sub-delegation + PageRank-inheritance finding
+  navi [label="session-navigator\nin-deg only 6\nyet PageRank RANK #5", fillcolor="#ddd6fe", color="#7c3aed", fontsize=10];
+  ganalyst -> navi [label="rare agent->agent;\nPageRank inherited\nfrom a central node", style=dashed, color="#7c3aed", fontsize=8];
+
+  note [label="Named agents almost never delegate onward\n(11 total): a shallow star, not a deep chain.", shape=note, fillcolor="#f1f5f9", color="#94a3b8", fontsize=9];
+  { rank=same; root; note; }
+}

docs/examples/exploration-diagrams/04-gds-session-clustering.dot

@@ -0,0 +1,42 @@
+digraph GdsSessionClustering {
+  rankdir=LR; bgcolor="white"; nodesep=0.35; ranksep=0.9;
+  node [fontname="Helvetica", fontsize=10];
+  edge [color="#64748b", fontname="Helvetica", fontsize=9];
+  labelloc="t"; fontsize=15; fontname="Helvetica-Bold";
+  label="GDS transformation: sessions -> TF-IDF tool-vectors -> kNN -> Louvain (19 communities, Q=0.862)";
+
+  // stage 1: raw graph (bipartite session-tool)
+  subgraph cluster_raw {
+    label="1. graph (read-only)"; style="rounded,filled"; fillcolor="#f8fafc"; color="#cbd5e1"; fontsize=10;
+    s1 [label="Session", shape=ellipse, style=filled, fillcolor="#e0e7ff"];
+    s2 [label="Session", shape=ellipse, style=filled, fillcolor="#e0e7ff"];
+    s3 [label="Session", shape=ellipse, style=filled, fillcolor="#e0e7ff"];
+    tb [label="bash",       shape=box, style="filled,rounded", fillcolor="#fee2e2"];
+    tr [label="read_file",  shape=box, style="filled,rounded", fillcolor="#fef9c3"];
+    tg [label="graph_query",shape=box, style="filled,rounded", fillcolor="#dcfce7"];
+    s1 -> tb [label="USES", fontsize=7]; s1 -> tr [fontsize=7];
+    s2 -> tb [fontsize=7]; s2 -> tg [fontsize=7];
+    s3 -> tr [fontsize=7]; s3 -> tb [fontsize=7];
+  }
+
+  // stage 2: TF-IDF vectors
+  vec [label="2. per-session\nTF-IDF tool vector\n(32 dims)\ndown-weights ubiquitous\nbash / read_file / todo", shape=box, style="filled,rounded", fillcolor="#ede9fe", color="#7c3aed"];
+
+  // stage 3: knn similarity graph
+  knn [label="3. gds.knn (cosine)\n2,030 nodes\n20,300 SIMILAR edges", shape=box, style="filled,rounded", fillcolor="#dbeafe", color="#2563eb"];
+
+  // stage 4: louvain communities
+  subgraph cluster_comm {
+    label="4. gds.louvain -> 19 workload communities"; style="rounded,filled"; fillcolor="#f0fdf4"; color="#86efac"; fontsize=10;
+    c1 [label="pure shell/ops\n344", shape=box, style="filled,rounded", fillcolor="#fecaca"];
+    c2 [label="edit+python\nimpl 158", shape=box, style="filled,rounded", fillcolor="#bfdbfe"];
+    c3 [label="grep/read\nrecon 165", shape=box, style="filled,rounded", fillcolor="#fde68a"];
+    c4 [label="delegate/todo\norchestration 156", shape=box, style="filled,rounded", fillcolor="#ddd6fe"];
+    c5 [label="graph_query\nanalysis 49", shape=box, style="filled,rounded", fillcolor="#bbf7d0"];
+    c6 [label="web research\n89", shape=box, style="filled,rounded", fillcolor="#fbcfe8"];
+  }
+
+  s1 -> vec [ltail=cluster_raw, style=bold]; 
+  vec -> knn [style=bold]; 
+  knn -> c1 [lhead=cluster_comm, style=bold];
+}

docs/examples/exploration-diagrams/05-machinery-vs-mission.dot

@@ -0,0 +1,44 @@
+digraph MachineryVsMission {
+  rankdir=LR; bgcolor="white"; nodesep=0.25; ranksep=1.4;
+  node [fontname="Helvetica", fontsize=10, shape=box, style="filled,rounded"];
+  edge [fontname="Helvetica", fontsize=8];
+  labelloc="t"; fontsize=15; fontname="Helvetica-Bold";
+  label="The key discovery: tool-behaviour clusters the MACHINERY, prompt-embeddings cluster the MISSION (near-orthogonal)";
+
+  // center: the same sessions
+  sessions [label="the SAME\nsessions\n(3,199)", shape=cylinder, fillcolor="#e0e7ff", color="#4338ca", fontsize=12, width=1.4];
+
+  // LEFT lens: tool-behaviour (GDS)  -> role/step
+  subgraph cluster_tools {
+    label="LENS A — tool-vectors -> GDS Louvain (19 comm, Q=0.862)\n= workflow ROLE / STEP"; fontsize=10;
+    style="rounded,filled"; fillcolor="#f0fdf4"; color="#86efac";
+    b1 [label="shell/ops step", fillcolor="#fecaca"];
+    b2 [label="implement step", fillcolor="#bfdbfe"];
+    b3 [label="review step",    fillcolor="#fde68a"];
+    b4 [label="commit step",    fillcolor="#e9d5ff"];
+  }
+
+  // RIGHT lens: embeddings -> objective
+  subgraph cluster_obj {
+    label="LENS B — prompt-embeddings -> k-means\n= human MISSION / OBJECTIVE"; fontsize=10;
+    style="rounded,filled"; fillcolor="#faf5ff"; color="#d8b4fe";
+    o1 [label="spec / code review", fillcolor="#fbcfe8"];
+    o2 [label="council persona review\n(~900 sessions)", fillcolor="#fbcfe8"];
+    o3 [label="implement one task", fillcolor="#bfdbfe"];
+    o4 [label="git / submodule / PR ops", fillcolor="#fed7aa"];
+    o5 [label="CI-server / dashboard build", fillcolor="#bbf7d0"];
+  }
+
+  sessions -> b1 [color="#16a34a"]; sessions -> b2 [color="#16a34a"];
+  sessions -> b3 [color="#16a34a"]; sessions -> b4 [color="#16a34a"];
+  sessions -> o1 [color="#9333ea"]; sessions -> o2 [color="#9333ea"];
+  sessions -> o3 [color="#9333ea"]; sessions -> o4 [color="#9333ea"]; sessions -> o5 [color="#9333ea"];
+
+  // the orthogonality: ONE objective (git ops) is spread across ~all behaviour steps
+  o4 -> b1 [label="git-ops objective\nlands in 18 of 19\nbehaviour clusters", style=dashed, color="#dc2626", constraint=false, fontsize=8];
+  o4 -> b2 [style=dashed, color="#dc2626", constraint=false];
+  o4 -> b3 [style=dashed, color="#dc2626", constraint=false];
+  o4 -> b4 [style=dashed, color="#dc2626", constraint=false];
+
+  note [label="same goal -> many tool-fingerprints;\nsame tool-fingerprint -> many goals.\nYou need BOTH lenses.", shape=note, fillcolor="#fff7ed", color="#ea580c", fontsize=9];
+}