Clarify when relationships.py adds value over the fetch preview

SKILL.md and workflows.md now spell out that fetch.py already previews 3
outgoing/incoming calls, so relationships.py is mainly worth running for
full incoming lists, inheritance trees, references, or artifacts too large
to fetch. Adds a playbook table for common tool sequences and flags
compiler-generated noise (MoveNext/GetEnumerator) in outgoing calls so
agents don't build conclusions on analyzer artifacts.

Bumps plugin version to 2.0.6 (docs-only patch).

Author: rodion-m

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "codealive",
   "description": "CodeAlive context engine for semantic code search and AI-powered codebase Q&A. Enables AI coding agents to understand entire codebases beyond just open files — search across all indexed repositories, trace cross-service dependencies, discover usage patterns, and get synthesized answers to architectural questions. Includes a lightweight code exploration subagent, authentication hooks, and multiple search modes (fast lexical, semantic, and deep cross-cutting). Works standalone or alongside the CodeAlive MCP server for direct tool access via the Model Context Protocol.",
-  "version": "2.0.5",
+  "version": "2.0.6",
   "author": {
     "name": "CodeAlive AI",
     "email": "hello@codealive.ai"

skills/codealive-context-engine/SKILL.md

@@ -40,8 +40,8 @@ Do NOT retry the failed script until setup completes successfully.
 | **List Data Sources** | `datasources.py` | Instant | Free | Discovering indexed repos and workspaces |
 | **Semantic Search** | `search.py` | Fast | Low | Default discovery — finds code by meaning (concepts, behavior, architecture) |
 | **Grep Search** | `grep.py` | Fast | Low | Finds code containing a specific string or regex (identifiers, literals, patterns) |
-| **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content for search results |
-| **Artifact Relationships** | `relationships.py` | Fast | Low | Drilling into call graph, inheritance, references for one artifact |
+| **Fetch Artifacts** | `fetch.py` | Fast | Low | Retrieving full content; function-like artifacts also include up to 3 outgoing/incoming calls as a preview |
+| **Artifact Relationships** | `relationships.py` | Fast | Low | Full call graph (past the fetch preview's 3-cap), inheritance, or symbol references for one artifact |
 | **Chat with Codebase** | `chat.py` | Slow | High | **Not recommended.** Call ONLY when the user explicitly asks (e.g. "use chat"). |
 
 **Cost guidance:** `semantic_search` and `grep_search` are the default starting point — fast and cheap. Use `fetch_artifacts` to load full source and `get_artifact_relationships` to trace call graphs. All four tools are low-cost.
@@ -60,9 +60,26 @@ Do NOT retry the failed script until setup completes successfully.
       file-read tool
     Treat only that real `content` as ground truth.
 
-**Optional drill-down:** once you know an artifact matters, run
-`python relationships.py <identifier>` to expand its call graph, inheritance,
-or references.
+**Drill into `relationships.py` when the fetch preview isn't enough.** The
+`fetch.py` response already previews up to 3 outgoing + 3 incoming calls for
+function-like artifacts, so the call graph alone is rarely a reason to run
+`relationships.py` after a full fetch of a small artifact. Reach for it when:
+
+- **You need all incoming callers** — the fetch preview is capped at 3.
+  The full incoming list also surfaces test coverage (incoming from test
+  files).
+- **You need the inheritance tree** — `--profile inheritanceOnly` returns
+  ancestors + descendants (interface implementations, subclasses, base-class
+  chains). The preview doesn't include inheritance.
+- **You need symbol references** — `--profile referencesOnly` for places
+  that reference a type or identifier.
+- **The artifact is too large to fetch into context** — the call graph is a
+  cheaper summary than pulling the full source.
+
+**Analyzer noise:** outgoing calls occasionally include compiler-generated
+helpers (`MoveNext`, `GetEnumerator`, closure invocations) from methods using
+`foreach`/LINQ. Ignore outgoing hits that don't match the artifact's real
+logic.
 
 ## When to Use
 
@@ -222,6 +239,25 @@ python scripts/relationships.py <identifier> [--profile PROFILE] [--max-count N]
 | `--max-count N` | Max related artifacts per relationship type (1–1000, default 50) |
 | `--json` | Emit the raw JSON response instead of the formatted view |
 
+**When this adds value vs the fetch preview:**
+- You need **all incoming callers** (including tests) — the fetch preview
+  caps at 3 per direction
+- You need the **inheritance tree** (`--profile inheritanceOnly`) — preview
+  doesn't include ancestors/descendants
+- You need **symbol references** (`--profile referencesOnly`) — preview
+  doesn't include references
+- The artifact is too large to fetch into context
+
+**When it's usually redundant:** you already ran `fetch.py` on a small
+artifact that fits in context. The outgoing calls you need are either in the
+source you just read or in the preview's 3-cap — reach for `relationships.py`
+only when you specifically need incoming calls, inheritance, or references.
+
+**Noise caveat:** outgoing calls occasionally include compiler-generated
+helpers (`MoveNext`, `GetEnumerator`, closure invocations) for methods using
+`foreach`/LINQ. These are analyzer artifacts — ignore outgoing hits that
+don't match the artifact's real logic.
+
 ### `chat.py` — Chat with Codebase (not recommended)
 
 **Do NOT call unless the user explicitly asks** (e.g. "use chat", "use codebase_consultant", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" refer to search tools, not chat.

skills/codealive-context-engine/references/workflows.md

@@ -387,21 +387,58 @@ understanding of the code. For each relevant result, immediately load the real
 source via `fetch.py <identifier>` (external repos) or your editor's file-read
 tool (current working repo). Treat only that real `content` as ground truth.
 
-### Drill into relationships when you need the call graph
-Once you've located an artifact via `search.py` or fetched it via `fetch.py`,
-use `relationships.py` to expand it:
-```bash
-# Default: full outgoing + incoming call graph
+### Drill into relationships when you need more than the fetch preview
+
+`fetch.py` already includes up to 3 outgoing + 3 incoming calls as a preview
+for function-like artifacts, so the call graph alone is rarely a reason to
+run `relationships.py` after a full fetch of a small artifact. Reach for it
+when:
+
+- **All incoming callers (including tests):** the preview caps at 3, so
+  production callers and test coverage both get truncated. `callsOnly`
+  returns the full list — incoming hits from test files are a proxy for test
+  coverage.
+- **Inheritance tree:** the preview doesn't include ancestors or descendants.
+  `--profile inheritanceOnly` is the only way to see all interface
+  implementations, subclasses, or the full base-class chain.
+- **Symbol references:** `--profile referencesOnly` for places that
+  reference a type or identifier without calling it.
+- **Large artifacts you don't want to fetch:** the graph is a cheaper summary
+  than pulling the full source into context.
+
+```bash
+# Full incoming + outgoing (default)
 python relationships.py "my-org/backend::src/auth.py::AuthService.login()"
 
-# Class hierarchy
+# Class hierarchy — ancestors + descendants
 python relationships.py "my-org/backend::src/models.py::User" --profile inheritanceOnly
 
-# Everything (calls + inheritance), bigger cap
+# Calls + inheritance with a bigger cap
 python relationships.py "my-org/backend::src/svc.py::Service" --profile allRelevant --max-count 200
 ```
-The `fetch.py` response shows up to 3 calls per direction as a preview;
-`relationships.py` is how you escape that preview cap and switch profiles.
+
+**When `relationships.py` usually adds nothing:** you already fetched the
+full source for a small artifact and it fits in context. Outgoing calls are
+already visible in the source or the fetch preview — start with incoming,
+inheritance, or references instead.
+
+**Noise caveat:** outgoing calls can include compiler-generated helpers
+(`MoveNext`, `GetEnumerator`, closure invocations) from methods using
+`foreach`/LINQ. Ignore hits that don't match the artifact's real logic.
+
+### Typical playbooks
+
+Concrete tool sequences for common questions — pick whichever matches your
+task and skip the rest:
+
+| You want to know... | Sequence |
+|---------------------|----------|
+| "How is X implemented?" | `search.py` → `fetch.py` on the top result (preview covers common outgoing calls) |
+| "Who calls X?" | `search.py`/`grep.py` to find X → `relationships.py --profile callsOnly` → read incoming |
+| "Is X tested, and how?" | locate X → `relationships.py --profile callsOnly` → filter incoming for test-file paths |
+| "All implementations of interface X?" | locate X → `relationships.py --profile inheritanceOnly` → read descendants |
+| "What does this giant service do?" | `search.py` → `relationships.py --profile callsOnly` instead of fetching the full source |
+| "Where is this type referenced?" | locate X → `relationships.py --profile referencesOnly` |
 
 ### Iterative Refinement
 Start broad → Review results → Refine query → Repeat