cg-code-graph 0.23.0__tar.gz → 0.23.2__tar.gz

{cg_code_graph-0.23.0/cg_code_graph.egg-info → cg_code_graph-0.23.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cg-code-graph
-Version: 0.23.0
+Version: 0.23.2
 Summary: cg: a code graph of routes, calls, data access and platform boundaries for agents and humans (CLI + MCP server)
 Author: cyberchronos00
 License-Expression: MIT
@@ -48,7 +48,7 @@ For you and your AI agent (CLI + MCP). No LLM in the graph.
 ```bash
 pipx install cg-code-graph          # or: uv tool install cg-code-graph
 cg index . --db out/graph.db        # prints starter queries for your repo
-cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server
+cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server and a "use cg first" agent rule
 cg reaches table:orders --db out/graph.db   # any table, connection or config key
 ```
 

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/README.md

@@ -21,7 +21,7 @@ For you and your AI agent (CLI + MCP). No LLM in the graph.
 ```bash
 pipx install cg-code-graph          # or: uv tool install cg-code-graph
 cg index . --db out/graph.db        # prints starter queries for your repo
-cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server
+cg install --host cursor    # or claude, codex, vscode, …: registers the MCP server and a "use cg first" agent rule
 cg reaches table:orders --db out/graph.db   # any table, connection or config key
 ```
 

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/__init__.py

@@ -1,2 +1,2 @@
 """code-graph: deterministic code knowledge graph (beta)."""
-__version__ = "0.23.0"
+__version__ = "0.23.2"

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/cli.py

@@ -73,6 +73,10 @@ def _add_install_parser(sub, uninstall: bool):
     p.add_argument("--uninstall", action="store_true", help="remove the entry instead of writing it")
     p.add_argument("--dry-run", action="store_true", help="print the exact changes and write nothing")
     p.add_argument("--yes", action="store_true", help="skip the confirmation prompt")
+    p.add_argument("--no-rules", dest="rules", action="store_false",
+                   help=("leave AGENTS.md and .cursor/rules/cg.mdc alone" if uninstall else
+                         "do not write the 'use cg first' agent rules (AGENTS.md section, .cursor/rules/cg.mdc); "
+                         "project scope only"))
     if not uninstall:
         p.add_argument("--registry", action="store_true",
                        help="global single entry: cg-mcp with no --db; graphs come from the registry")
@@ -96,9 +100,24 @@ def _impact_labels(rows: list[dict], name_of, group_of) -> list[str]:
     return labels
 
 
+def _version_text(version: str) -> str:
+    """`cg X.Y.Z`, plus a second line when the cached newer-release check (written by `cg doctor`) knows of a newer
+    release. Reads the cache only: never connects (#98)."""
+    try:
+        from .update_check import check, notice
+        n = notice(check(version, network=False))
+    except Exception:
+        n = None
+    return f"cg {version}" + (f"\n{n}" if n else "")
+
+
 def main(argv=None):
     from . import __version__
     ap = argparse.ArgumentParser(prog="cg")
+    args_in = sys.argv[1:] if argv is None else list(argv)
+    if args_in[:1] == ["--version"]:
+        print(_version_text(__version__))   # printed here: argparse's version action re-wraps a second line
+        return 0
     ap.add_argument("--version", action="version", version=f"cg {__version__}")
     sub = ap.add_subparsers(dest="cmd", required=True)
     p = sub.add_parser("index", help="detect languages / frameworks under ROOT and build the graph DB (stats JSON on stdout, coverage on stderr)"); p.add_argument("root"); p.add_argument("--db", required=True); p.add_argument("--name"); p.add_argument("--scip", action="append"); p.add_argument("--gates", help="gate scenarios JSON (e.g. examples/bookstore.gates.json)")
@@ -520,7 +539,8 @@ def main(argv=None):
         return run_install(a.host, scope="global" if a.glob else "project", root=a.dir, db=a.db,
                            tools=a.tools, portable=a.portable, remove=a.cmd == "uninstall" or a.uninstall,
                            dry_run=a.dry_run, assume_yes=a.yes, registry=registry, migrate=migrate,
-                           apply=bool(getattr(a, "apply", False)), graphs=getattr(a, "graphs", None))
+                           apply=bool(getattr(a, "apply", False)), graphs=getattr(a, "graphs", None),
+                           rules=a.rules)
     if a.cmd == "hooks":
         from . import hooks as HK
         return HK.run(a.action, root=a.dir, db=a.db, dry_run=a.dry_run, assume_yes=a.yes)
@@ -857,6 +877,11 @@ def render_node(d: dict) -> str:
         unk = at.get("platform_unknown") or []
         ps = ", ".join(p + ("?" if p in unk else "") for p in at["platforms"]) or "none of the targets"
         out.append(f"  platforms: {ps}" + (f"  ({at['platform_expr']})" if at.get("platform_expr") else ""))
+    if n.get("kind") == "i18n" and at.get("definitions"):
+        out.append("  definitions: " + ", ".join(f"{x.get('locale') or '-'} {x['file']}:{x['line']}" for x in at["definitions"]))
+        if at.get("missing_locales"):
+            out.append("  missing locales: " + ", ".join(at["missing_locales"]))
+        at = {k: v for k, v in at.items() if k not in ("definitions", "defined_in", "missing_locales")}
     rest = {k: v for k, v in at.items() if k not in ("platforms", "platform_unknown", "platform_expr", "platform_at", "platforms_other")}
     if rest:
         out.append("  attrs: " + ", ".join(f"{k}={v if isinstance(v, str) else json.dumps(v, default=str, ensure_ascii=False)}"

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/core/model.py

@@ -56,7 +56,7 @@ EDGE_KINDS: dict[str, tuple[bool, str]] = {
     "HTTP_CALLS": (True, "client code calls an HTTP endpoint (method + path template)"),
     "MATCHES_ROUTE": (True, "client endpoint matched to a backend route (cross-repo link)"),
     "USES_LAYOUT": (False, "page uses layout"),
-    "USES_I18N": (False, "code/template uses i18n key"),
+    "USES_I18N": (True, "code/template uses i18n key (propagating: a key's users are its dependents in reaches / impact, #182)"),
     "REFERENCES_TYPE": (False, "code references a type/interface"),
     # value facts
     "READS_SETTING": (True, "code reads a JSON settings key (getSetting('a.b', default))"),

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/coverage.py

@@ -344,6 +344,9 @@ def compute(root: str | Path, plugins: dict, scip_imported: bool = False, report
             elif not e["files_complete"] and lang == "typescript" and e.get("unmapped"):
                 e["hint"] = ("files outside the source dirs and test trees were not read: list the directories that hold "
                              "source in .cg.yaml `include` (or a tsconfig.json `include`) and re-index")
+                if (nx := _nuxt_dirs(root)):
+                    # Nuxt: name the dirs that were read, so a layer or module dir outside them is explained (#214)
+                    e["hint"] = f"Nuxt project: the source dirs read are the srcDir plus server/ and shared/ ({nx}); " + e["hint"]
         se = (rep or {}).get("syntax_errors")
         if isinstance(se, list) and se and status not in ("skipped", "not_indexed"):
             # files parsed with syntax errors (#73): error spans and the declarations lost there
@@ -434,6 +437,16 @@ def _ts_not_run(root, with_php: bool) -> tuple[str, str]:
     return reason, hint
 
 
+def _nuxt_dirs(root) -> str | None:
+    """'app/, server/, shared/' for a Nuxt project (the dirs the Nuxt plugin reads), else None."""
+    from .plugins.nuxt.plugin import _CFG_NAMES, find_src_dir, side_dirs
+    r = Path(root)
+    if not any((r / n).exists() for n in _CFG_NAMES):
+        return None
+    src = find_src_dir(r)
+    return ", ".join(["the project root" if src == "." else f"{src}/", *(f"{d}/" for d in side_dirs(r, src))])
+
+
 def _python_unmapped_hint(st: dict) -> str:
     if st.get("roots_mode") in ("configured", "flag"):
         where = "python.source_roots in .cg.yaml" if st["roots_mode"] == "configured" else "--python-root"

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/doctor.py

@@ -407,12 +407,25 @@ def report(root: str | Path | None = None, scip: list | None = None) -> dict:
         "legacy_cache": cache.legacy_report(),
         **({"hooks_outdated": _outdated_hooks(rootp)} if rootp is not None else {}),
         "update": "uv tool upgrade cg-code-graph  |  pipx upgrade cg-code-graph  |  install.sh --update",
+        "latest": _latest(),
         **({"scip": [scip_health(x) for x in scip]} if scip else {}),
     }
 
 
+def _latest() -> dict:
+    """Newer-release check (#98): PyPI at most once a day, cached; never fails or blocks for long."""
+    from .update_check import check
+    try:
+        return check()
+    except Exception:
+        return {"current": __version__, "latest": None, "newer": False, "source": "none", "disabled": None}
+
+
 def render(r: dict) -> str:
     out = [f"cg {r['cg']}  (Python {r['python']}, {r['os']}; {r['package']}{', checkout' if r['checkout'] else ''})"]
+    from .update_check import notice
+    if (n := notice(r.get("latest") or {})):
+        out.append(f"newer release: {n}")
     out.append("tools:")
     for k, v in r["tools"].items():
         out.append(f"  {k:<14} {v['version'] or 'not found'}" + (f"  ({v['path']})" if v["path"] else "")

cg_code_graph-0.23.2/cg_code_graph/install_rules.py

@@ -0,0 +1,88 @@
+"""Agent rules written by `cg install` (project scope, on by default, `--no-rules` skips): a short "use cg first"
+section in AGENTS.md (Claude Code, Codex and other agents read it) and an alwaysApply Cursor rule at
+.cursor/rules/cg.mdc. Only the `<!-- cg:start --> ... <!-- cg:end -->` section is ever written: a re-run replaces
+it in place, content around it is kept, and `cg uninstall` removes it."""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+
+START = "<!-- cg:start -->"
+END = "<!-- cg:end -->"
+AGENTS_FILE = "AGENTS.md"
+CURSOR_FILE = ".cursor/rules/cg.mdc"
+MDC_HEADER = "---\ndescription: Use the cg code graph before grep or opening whole files\nalwaysApply: true\n---\n"
+_SECTION = re.compile(re.escape(START) + r".*?" + re.escape(END), re.S)
+
+
+def body(db: str = "out/graph.db") -> str:
+    return (
+        "## Code graph (cg)\n\n"
+        "This repo has a cg code graph (MCP server `cg`). Use it before grep or opening whole files:\n"
+        "- `search` to find a symbol (file:line);\n"
+        "- `impact` before editing a function (or `reaches` for a table, column or env key) to see what the change affects;\n"
+        "- `snippet` to read one symbol instead of a whole file;\n"
+        "- `graphs` if unsure which graph to query.\n\n"
+        "Use normal search only for what cg reports as not covered (`coverage`). Without MCP: "
+        f"`cg search|impact|snippet <symbol> --db {db}`.\n")
+
+
+def section(db: str = "out/graph.db") -> str:
+    return f"{START}\n{body(db)}{END}"
+
+
+def _plan(path: Path, new: str | None, old: str, delete: bool = False) -> dict:
+    if delete:
+        return {"path": str(path), "kind": "text", "action": "remove", "old": old, "new": "", "delete_file": True}
+    if new == old:
+        return {"path": str(path), "kind": "text", "action": "noop", "old": old, "new": old, "current": True}
+    action = "insert" if not _SECTION.search(old) else ("remove" if not _SECTION.search(new) else "update")
+    return {"path": str(path), "kind": "text", "action": action, "old": old, "new": new}
+
+
+def _with_section(old: str, sec: str) -> str:
+    if _SECTION.search(old):
+        return _SECTION.sub(lambda _m: sec, old, count=1)
+    if not old:
+        return sec + "\n"
+    return old + ("" if old.endswith("\n\n") else "\n" if old.endswith("\n") else "\n\n") + sec + "\n"
+
+
+def _without_section(old: str) -> str:
+    m = _SECTION.search(old)
+    if not m:
+        return old
+    s, e = m.start(), m.end()
+    while e < len(old) and old[e] == "\n":
+        e += 1
+    while s > 0 and old[s - 1] == "\n":
+        s -= 1
+    head = old[:s]
+    return (head + "\n" + old[e:]) if head and old[e:] else (head + "\n" if head else old[e:])
+
+
+def plans(root: Path, remove: bool = False, db: str = "out/graph.db") -> list[dict]:
+    """One text plan per rules file (the shape `cg agents` previews and `cg install` applies)."""
+    out = []
+    sec = section(db)
+    agents = root / AGENTS_FILE
+    old = agents.read_text(encoding="utf-8") if agents.exists() else ""
+    if remove:
+        rest = _without_section(old)
+        out.append(_plan(agents, None, old, delete=True) if _SECTION.search(old) and not rest.strip() else _plan(agents, rest, old))
+    else:
+        out.append(_plan(agents, _with_section(old, sec), old))
+    mdc = root / CURSOR_FILE
+    old = mdc.read_text(encoding="utf-8") if mdc.exists() else ""
+    if remove:
+        rest = _without_section(old)
+        if mdc.exists() and _SECTION.search(old) and rest.strip() in ("", MDC_HEADER.strip()):
+            out.append(_plan(mdc, None, old, delete=True))
+        else:
+            out.append(_plan(mdc, rest, old))
+    else:
+        new = _with_section(old, sec)
+        if not new.startswith("---\n"):
+            new = MDC_HEADER + new        # an alwaysApply header, added once in front of whatever is there
+        out.append(_plan(mdc, new, old))
+    return [p for p in out if not (remove and p["action"] == "noop" and not p["old"])]

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/link.py

@@ -137,7 +137,10 @@ def known_origin_text(attrs: dict) -> str | None:
     return None
 
 
-_GENERIC_ORIGIN = {"env", "base", "url", "api", "app", "http", "https", "host", "origin", "endpoint", "service", "internal"}
+_GENERIC_ORIGIN = {"env", "base", "url", "uri", "api", "app", "http", "https", "host", "origin", "endpoint", "service",
+                   "internal", "server", "backend", "public", "private", "remote", "domain", "root", "prefix", "path",
+                   "address", "addr", "runtime", "config", "runtimeconfig", "process", "import", "meta", "window",
+                   "location", "nuxt", "next", "vite", "react", "expo", "vue", "localhost", "www", "com"}
 
 
 def repos_for_origin(text: str, servers: list[str]) -> list[str] | None:
@@ -146,17 +149,20 @@ def repos_for_origin(text: str, servers: list[str]) -> list[str] | None:
     ``None`` when the origin is a generic API base (``API_BASE_URL``) and does not name a repo:
     matching stays as it was. ``[]`` when it names a service that is not one of ``servers``.
     """
-    low = text.lower()
+    # camelCase splits (runtimeConfig.public.apiBase -> runtime config public api base); `-`, `_` and `.` all separate,
+    # so ORDERS_API_URL names an orders-api repo
+    split = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", text).lower()
+    norm = "-" + "-".join(re.findall(r"[a-z0-9]+", split)) + "-"
     hits = []
     for name in servers:
-        token = name.lower()
+        token = "-".join(re.findall(r"[a-z0-9]+", re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name).lower()))
         if len(token) < 3:
             continue
-        if re.search(rf"(^|[^a-z0-9]){re.escape(token)}([^a-z0-9]|$)", low):
+        if f"-{token}-" in norm:
             hits.append(name)
     if hits:
         return hits
-    tokens = [t for t in re.findall(r"[a-z][a-z0-9]+", low) if t not in _GENERIC_ORIGIN]
+    tokens = [t for t in re.findall(r"[a-z][a-z0-9]+", split) if t not in _GENERIC_ORIGIN]
     if not tokens:
         return None
     return []
@@ -431,6 +437,7 @@ def link_many(repos: list[tuple[str, str, str]], out_db: str, *, allow: dict | N
         by_server[rt["server"]].append(rt)
     results = []
     new_edges = []
+    matched_origins: set[tuple[str, str]] = set()
     for client, ep_id, a, _test in http_rows:
         targets = [s for s in server_names if (s != client or folded_self) and (client not in allow or s in allow[client])]
         pool = [rt for s in targets for rt in by_server[s]]
@@ -443,7 +450,11 @@ def link_many(repos: list[tuple[str, str, str]], out_db: str, *, allow: dict | N
         if origin_text and owners == [] and not res.get("matched") and a.get("origin_kind") != "other":
             reason = res.get("reason") or ""
             if reason.startswith(("no backend route", "not a backend URL")) or "suffix" in reason:
+                res["_reason_before_external"] = reason
+                res["_origin_text"] = origin_text
                 res["reason"] = "external (other origin)"
+        elif origin_text and res.get("matched"):
+            matched_origins.add((client, origin_text))
         res.update({"endpoint": ep_id, "method": a["method"], "calls": calls_by_ep.get(ep_id, []),
                     "_client": client, "_servers": targets})
         results.append(res)
@@ -452,6 +463,12 @@ def link_many(repos: list[tuple[str, str, str]], out_db: str, *, allow: dict | N
             rr = rmap[m["route"]]
             new_edges.append((ep_id, m["route"], "MATCHES_ROUTE", rr["file"], rr["line"], m["confidence"], CONFIDENCE_RANK[m["confidence"]],
                               json.dumps({"client_path": a["path"], "uri_variant": m["uri_variant"], "segments": m["segments"]}), None))
+    for res in results:
+        # an origin whose other calls from this client matched a linked server is that backend, not an external one
+        before = res.pop("_reason_before_external", None)
+        if before is not None and (res["_client"], res.pop("_origin_text")) in matched_origins:
+            res["reason"] = before
+        res.pop("_origin_text", None)
     db.executemany("INSERT INTO edges(src,dst,kind,file,line,confidence,conf_rank,attrs,gate) VALUES (?,?,?,?,?,?,?,?,?)", new_edges)
     db.commit()
     subscriptions = pair_subscriber_urls(db, routes, server_names, allow, folded_self)

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/mcp_install.py

@@ -781,6 +781,9 @@ def _apply_file(plan: dict) -> None:
         if path.exists():
             path.unlink()
         parent = path.parent
+        if parent.name == "rules" and parent.parent.name == ".cursor" and parent.exists() and not any(parent.iterdir()):
+            parent.rmdir()            # .cursor/rules/cg.mdc was the only rule
+            parent = parent.parent
         if parent.name in _EMPTY_PARENTS and parent.exists() and not any(parent.iterdir()):
             parent.rmdir()
         return
@@ -1023,7 +1026,7 @@ def run(hosts: list[str] | None, *, scope: str, root: str = ".", db: str | None
         tools: str | None = None, portable: bool = False, remove: bool = False,
         dry_run: bool = False, assume_yes: bool = False, input_fn=input, out=print,
         registry: bool = False, migrate: bool = False, apply: bool = False,
-        graphs: str | None = None) -> int:
+        graphs: str | None = None, rules: bool = True) -> int:
     if migrate:
         return run_migrate(hosts, scope=scope, root=root, tools=tools, graphs=graphs, apply=apply and not dry_run, out=out)
     rootp = Path(root).resolve()
@@ -1050,6 +1053,16 @@ def run(hosts: list[str] | None, *, scope: str, root: str = ".", db: str | None
         dbp = None
     plans = iter_plans(expanded, scope=scope, root=rootp, db=dbp, tools=tools, portable=portable, remove=remove,
                        registry=registry)
+    if rules and scope == "project" and not registry:
+        # "use cg first" rules for agents: AGENTS.md section + alwaysApply Cursor rule (cg_code_graph/install_rules.py)
+        from . import install_rules as IR
+        shown = "out/graph.db"
+        if dbp is not None and not portable:
+            try:
+                shown = dbp.relative_to(rootp).as_posix()
+            except ValueError:
+                shown = str(dbp)
+        plans = [*plans, *IR.plans(rootp, remove=remove, db=shown)]
     if not portable and not remove and uses_module_fallback():
         out(_FALLBACK_NOTE)
     for plan in plans:
@@ -1088,6 +1101,10 @@ def run(hosts: list[str] | None, *, scope: str, root: str = ".", db: str | None
         _apply_file(plan)
         if plan.get("delete_file"):
             out(f"removed {plan['path']}")
+        elif plan.get("kind") == "text" and plan["action"] == "remove":
+            out(f"removed the cg section from {plan['path']}")
+        elif plan.get("kind") == "text":
+            out(f"wrote {plan['path']} (cg agent rules, {plan['action']})")
         else:
             out(f"wrote {plan['path']} ({plan['action']})")
     return 0

{cg_code_graph-0.23.0 → cg_code_graph-0.23.2}/cg_code_graph/mcp_server.py

@@ -62,9 +62,9 @@ STATE = _State({"db": str(ROOT / "out" / "graph.db"), "root": None, "gates": Non
                 "graph_entry": None, "graph_name": None, "graph_arg": False})
 _MCP_ROOTS: contextvars.ContextVar[list[str] | None] = contextvars.ContextVar("cg_mcp_roots", default=None)
 
-server = MCPServer(
-    name="code-graph",
-    instructions=(
+# Reference text (stacks, spec forms, per-feature notes): the MCP resource cg://guide. The initialize
+# `instructions` stay short and directive so agents use cg before grep / file reads.
+GUIDE = (
         "Code graph of a project: classes, functions, routes, commands, jobs, pages, DB tables/columns, connections, "
         "config/env keys, each edge with file:line evidence and a confidence (exact / resolved / heuristic). Stacks: "
         "For a broad question ('how does X work') start with `explore`: source, entry points, call paths and blast radius in one call. "
@@ -119,8 +119,23 @@ server = MCPServer(
         "issue links) and overlays the graph without changing it. Workflow: write the plan -> `plan_check` (compact "
         "summary with counts and the top items; details=true for every item with file:line, forbidden paths and open "
         "findings) -> refine the plan -> `plan_baseline` -> implement -> `index` -> `plan_check(verify=true)` (planned "
-        "nodes/edges exist, forbidden paths gone or guarded, modified targets changed)."),
-)
+        "nodes/edges exist, forbidden paths gone or guarded, modified targets changed).")
+
+INSTRUCTIONS = (
+    "Use cg before grep or opening files for questions about where code is, what calls what, or what a change "
+    "affects. `search` finds a symbol; before editing, `impact` (callers up to entry points) or `reaches` (every "
+    "dependent) shows what the change affects; `snippet` reads one symbol instead of a whole file; `explore` answers "
+    "a broad 'how does X work' in one call. Unsure which graph? Call `graphs`. Fall back to normal search only for "
+    "what cg reports as not covered (`coverage`, a `coverage note:` line). Spec forms and stack notes: resource "
+    "cg://guide.")
+
+server = MCPServer(name="code-graph", instructions=INSTRUCTIONS)
+
+
+@server.resource("cg://guide", name="guide", description="cg reference: stacks, spec forms, per-feature notes",
+                 mime_type="text/plain")
+def guide() -> str:
+    return GUIDE
 
 
 def _rel_text(txt: str) -> str:
@@ -451,7 +466,8 @@ def _ename(e: dict) -> str:
 def reaches(targets: list[str], min_confidence: str = "heuristic", group_by: str = "module",
             include_gated: bool = True, max_per_group: int = 25, paths: bool = True, platform: str | None = None,
             connection: str | None = None) -> str:
-    """Reverse transitive dependents of one or more targets (union), e.g.
+    """Use before changing a column, table, connection, env key or symbol: everything that depends on it.
+    Reverse transitive dependents of one or more targets (union), e.g.
     ["orders.customer_id", "connection:warehouse", "connection:tenant_*"].
 
     Groups: RUNTIME (live; reached from http routes/schedules/jobs/listeners, or main()/exported FFI symbols in
@@ -489,7 +505,7 @@ def reaches(targets: list[str], min_confidence: str = "heuristic", group_by: str
         route_lines = [Q.route_failure(st, s)["text"] for s in missing if Q.route_failure(st, s)]
         if route_lines and len(route_lines) == len(missing):
             return "\n".join(route_lines)
-        return "\n".join(pline + [f"targets: {tl}"]) + f"\nno node matches {', '.join(map(repr, missing))}; try search() with part of the name (spec forms are listed in the server instructions)"
+        return "\n".join(pline + [f"targets: {tl}"]) + f"\nno node matches {', '.join(map(repr, missing))}; try search() with part of the name (spec forms: resource cg://guide)"
     if not items and connection:
         return "\n".join(pline + [f"targets: {tl}", f"no dependents recorded for {', '.join(res['targets'])} on connection {connection!r} "
                                   f"(connections seen: {Q.seen_text(res.get('connections_seen') or [])})."])
@@ -550,7 +566,7 @@ def reaches(targets: list[str], min_confidence: str = "heuristic", group_by: str
 @tool
 def impact(method: str, min_confidence: str = "heuristic", max_items: int = 60, platform: str | None = None,
            paths: bool = True) -> str:
-    """Reverse callers of a method (Class::method, short or FQN) up to entry points, with the shortest call path
+    """Use before editing a function: what a change to it affects. Reverse callers of a method (Class::method, short or FQN) up to entry points, with the shortest call path
     from each entry point.
     platform: only code built for that target (windows, linux, macos, ios, android, web): code under a platform
     condition that is false there (#[cfg], #if, Platform.OS / Platform.isX, kIsWeb, .ios.ts / .android.ts files,
@@ -666,7 +682,7 @@ CALLER_KINDS = ("CALLS", "INSTANTIATES", "IMPLEMENTED_BY", "OVERRIDDEN_BY", "BOU
 
 @tool
 def callers(symbol: str, min_confidence: str = "heuristic", limit: int = 60) -> str:
-    """Direct callers of a function / method / class (one level: CALLS, INSTANTIATES, dispatch and framework edges
+    """Use to see who calls X right now. Direct callers of a function / method / class (one level: CALLS, INSTANTIATES, dispatch and framework edges
     into it), each with the call site file:line and confidence. For the full chain up to entry points use impact()."""
     st = _st()
     ids = Q.resolve_targets(st, symbol)
@@ -1042,8 +1058,9 @@ def affected(files: list[str] | None = None, base: str | None = None, max_depth:
 
 @tool
 def node(id_or_symbol: str) -> str:
-    """Details of one node: kind, FQN, file:line span, module, entry kinds, docblock (PHPDoc), and edge counts
-    by kind (in/out) with a few neighbours."""
+    """Use to inspect a symbol without reading its file. Details of one node: kind, FQN, file:line span, module, entry kinds, docblock (PHPDoc), and edge counts
+    by kind (in/out) with a few neighbours. Specs: Class::method | file#name | table.column | table:<t> |
+    route:<METHOD> <uri> | env:<KEY> | page:/path (more: resource cg://guide)."""
     st = _st()
     n = st.node(id_or_symbol)
     if not n:
@@ -1076,7 +1093,7 @@ def node(id_or_symbol: str) -> str:
 
 @tool
 def snippet(id_or_symbol: str, context: int = 0, max_lines: int = 200) -> str:
-    """Source of one symbol: a `path:start-end` header then the body with line numbers. Resolves a
+    """Use instead of opening a whole file. Source of one symbol: a `path:start-end` header then the body with line numbers. Resolves a
     node id or a symbol / FQN (as node() and search() do); an ambiguous name lists the candidates
     instead of guessing. context adds lines around the span; max_lines caps the body (truncation noted)."""
     return Q.render_snippet(Q.snippet(_st(), id_or_symbol, context=context, max_lines=max_lines))
@@ -1084,7 +1101,7 @@ def snippet(id_or_symbol: str, context: int = 0, max_lines: int = 200) -> str:
 
 @tool
 def search(name: str, kind: str | None = None, limit: int = 20, platform: str | None = None) -> str:
-    """Find nodes by name / FQN substring (case-insensitive), optionally filtered by kind
+    """Use first to find a symbol instead of grep. Finds nodes by name / FQN substring (case-insensitive), optionally filtered by kind
     (class, method, route, command, table, column, connection, config, env, job, admin...). Also matches route
     middleware, guards, auth and access checks (e.g. "auth" finds `auth:api`, `ApiKeyGuard`, `IsAuthenticated`) and
     lists the routes that carry them. Platform-specific symbols carry their targets, e.g. `[ios, android]`.
@@ -1115,7 +1132,7 @@ def explore(query: str, budget_tokens: int = 3000, max_symbols: int = 4) -> str:
 def routes(writes: str | None = None, reaches: list[str] | None = None, missing: str | None = None,
            unguarded: bool = False, strict: bool = False, auth_pattern: str | None = None, max_items: int = 40, paths: bool = True,
            min_confidence: str = "heuristic", platform: str | None = None) -> str:
-    """Routes with their middleware / guards / auth, in one call. Optional scope: writes="*" (routes that reach any
+    """Use for route, auth and middleware questions. Routes with their middleware / guards / auth, in one call. Optional scope: writes="*" (routes that reach any
     DB write) or writes="<table>", reaches=[specs] (routes that reach any of these nodes: table, column, connection,
     method, env key...). Optional filters: missing="<name>" keeps routes with no guard whose name contains it (e.g.
     "auth:api", "ApiKeyGuard"), unguarded=true keeps routes with no auth guard (the framework presets' auth guards and
@@ -1154,7 +1171,7 @@ def doctor(root: str | None = None, scip: list[str] | None = None, json_output:
 
 @tool
 def coverage(path: str | None = None, all_files: bool = False, json_output: bool = False) -> str:
-    """Which languages and files this index covers. Per language: parser mode (exact, heuristic only when an
+    """Use when cg finds nothing or you need to know if a file is indexed. Which languages and files this index covers. Per language: parser mode (exact, heuristic only when an
     exact-mode indexer such as rust-analyzer or scip-clang is missing, skipped when the toolchain is missing, with the
     install hint) and file completeness (discovered vs indexed, with parse failures, files over the size limit,
     unmapped files outside the source roots, excluded files); unsupported source types by extension or shebang
@@ -1242,7 +1259,7 @@ def stats() -> str:
 @tool
 def downstream(target: str, max_per_kind: int = 25, paths: bool = True, min_confidence: str = "heuristic",
                platform: str | None = None) -> str:
-    """Forward dependencies of a node: what it ends up calling/reading. On a combined graph a frontend page goes
+    """Use to see what X ends up calling or reading (page -> routes -> tables). Forward dependencies of a node. On a combined graph a frontend page goes
     page -> composables/components -> HTTP endpoints -> backend routes -> controllers/services -> tables.
     Lists backend routes, tables touched (directly or via columns), columns, connections, config/env keys, each
     with one shortest evidence path. target: page:/reports/:id | app/pages/x.vue | Class::method | ...
@@ -1288,7 +1305,7 @@ def downstream(target: str, max_per_kind: int = 25, paths: bool = True, min_conf
 
 @tool
 def path(source: str, target: str, min_confidence: str = "heuristic", platform: str | None = None) -> str:
-    """Shortest forward evidence chain from source to target (e.g. page:/reports/:id ->
+    """Use to answer "how does A reach B". Shortest forward evidence chain from source to target (e.g. page:/reports/:id ->
     SalesReportService::report), one hop per line with file:line and confidence.
     platform: only code built for that target (windows, linux, macos, ios, android, web): code under a platform
     condition that is false there (#[cfg], #if, Platform.OS / Platform.isX, kIsWeb, .ios.ts / .android.ts files,
@@ -1601,7 +1618,7 @@ def _index(root: str | None = None, gates: str | None = None, repo: str | None =
 
 @tool
 def index(root: str | None = None, gates: str | None = None, repo: str | None = None) -> str:
-    """Re-index after editing (static analysis only: never boots the app or touches a database).
+    """Use after editing so later answers see the change. Re-index (static analysis only: never boots the app or touches a database).
     On a combined graph (any number of repos): with no arguments every repo is re-indexed from its recorded root and the
     cross-repo link is rebuilt; repo (a name used at link time) re-indexes just that repo; root is matched to the
     recorded repo roots (a repo directory, a path inside one, or a parent of several). A root that matches no repo, or
@@ -1623,7 +1640,7 @@ def index(root: str | None = None, gates: str | None = None, repo: str | None =
 
 @tool
 def graphs() -> str:
-    """List the graphs this server can query: name, repo roots, languages, indexed commit and freshness.
+    """Use when unsure which graph a question belongs to. Lists the graphs this server can query: name, repo roots, languages, indexed commit and freshness.
     One `cg-mcp` process serves every registered graph. Pass `graph` to other tools to choose one, or omit it
     and the server resolves from a path in the call, then MCP roots or the working directory, then the configured
     default. An ambiguous choice returns the list instead of guessing."""