From 5f9d461f63fe81f89d00a09323f1aaa682aa778f Mon Sep 17 00:00:00 2001
From: sanguine59 <the6seas0n@gmail.com>
Date: Sun, 16 Aug 2026 14:05:20 +0700
Subject: [PATCH] docs(claude-skills): update gitnexus-exploring

---
 .claude/skills/gitnexus-exploring/SKILL.md | 32 +++++++++++++++++-----
 1 file changed, 25 insertions(+), 7 deletions(-)

diff --git a/.claude/skills/gitnexus-exploring/SKILL.md b/.claude/skills/gitnexus-exploring/SKILL.md
index f483c2fd6..ec5900192 100644
--- a/.claude/skills/gitnexus-exploring/SKILL.md
+++ b/.claude/skills/gitnexus-exploring/SKILL.md
@@ -13,27 +13,37 @@ description: "Use when the user asks how code works, wants to understand archite
 - "Where is the database logic?"
 - Understanding code you haven't seen before
 
+## Bind the repository first
+
+Step 1 discovers what is indexed; the calls after it must say which of those
+they mean. With one indexed repository, use the examples below as written. With
+more than one, pass `repo` explicitly on every call — an omitted `repo` errors,
+or silently resolves to a configured default — and stop and ask if the intended
+repository is ambiguous. See `references/repository-identity.md`.
+
 ## Workflow
 
 ```
-1. READ gitnexus://repos                          → Discover indexed repos
+1. list_repos {} or READ gitnexus://repos         → Discover indexed repos; bind one
 2. READ gitnexus://repo/{name}/context             → Codebase overview, check staleness
-3. query({search_query: "<what you want to understand>"})  → Find related execution flows
-4. context({name: "<symbol>"})            → Deep dive on specific symbol
+3. query({search_query: "<what you want to understand>"[, repo: "<repo>"]})  → Find related execution flows
+4. context({name: "<symbol>"[, repo: "<repo>"]})   → Deep dive on specific symbol
 5. READ gitnexus://repo/{name}/process/{name}      → Trace full execution flow
 ```
 
-> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in terminal.
+> If step 2 says "Index is stale" → run `node .gitnexus/run.cjs analyze` in the bound checkout.
 
 ## Checklist
 
 ```
+- [ ] list_repos {} — bind repo; explicit repo when total > 1, ask if ambiguous
 - [ ] READ gitnexus://repo/{name}/context
 - [ ] query for the concept you want to understand
 - [ ] Review returned processes (execution flows)
 - [ ] context on key symbols for callers/callees
 - [ ] READ process resource for full execution traces
 - [ ] Read source files for implementation details
+- [ ] State the repository and index freshness alongside the explanation
 ```
 
 ## Resources
@@ -50,7 +60,7 @@ description: "Use when the user asks how code works, wants to understand archite
 **query** — find execution flows related to a concept:
 
 ```
-query({search_query: "payment processing"})
+query({search_query: "payment processing", repo: "my-app"})
 → Processes: CheckoutFlow, RefundFlow, WebhookHandler
 → Symbols grouped by flow with file locations
 ```
@@ -58,16 +68,20 @@ query({search_query: "payment processing"})
 **context** — 360-degree view of a symbol:
 
 ```
-context({name: "validateUser"})
+context({name: "validateUser", repo: "my-app"})
 → Incoming calls: loginHandler, apiMiddleware
 → Outgoing calls: checkToken, getUserById
 → Processes: LoginFlow (step 2/5), TokenRefresh (step 1/3)
 ```
 
+`repo` is required once more than one repository is indexed, and may be omitted
+with a single one.
+
 ## Example: "How does payment processing work?"
 
 ```
-1. READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes
+1. list_repos {}                             → total: 1 (my-app) — bind it
+   READ gitnexus://repo/my-app/context       → 918 symbols, 45 processes, index current
 2. query({search_query: "payment processing"})
    → CheckoutFlow: processPayment → validateCard → chargeStripe
    → RefundFlow: initiateRefund → calculateRefund → processRefund
@@ -75,4 +89,8 @@ context({name: "validateUser"})
    → Incoming: checkoutHandler, webhookHandler
    → Outgoing: validateCard, chargeStripe, saveTransaction
 4. Read src/payments/processor.ts for implementation details
+5. Answer, noting: Repository my-app, index current
 ```
+
+Had step 1 returned two repositories, every call above would carry
+`repo: "my-app"`.