@fradser/pi-context 0.5.0

package/README.md

@@ -0,0 +1,187 @@
+# Code Context Pi Package
+
+**Version:** 0.4.1
+
+Retrieve code context for any repo, library, or natural-language query via 5 methods: DeepWiki, Context7, Exa, git clone, and web search+fetch.
+
+## Installation
+
+```bash
+pi install /path/to/pi-packages/packages/code-context
+```
+
+Run `/skill:get-context <query…>` for the executable Pi workflow.
+
+## Runtime requirements
+
+| Method | Availability | Notes |
+|--------|--------------|-------|
+| DeepWiki | Always (native tool `context_deepwiki`) | No API key required |
+| Context7 | Always (native tool `context_context7`) | Optional `CONTEXT7_API_KEY` (Bearer) for per-key quota |
+| Exa | Native tool `context_exa` | Requires `EXA_API_KEY` env var |
+| Git clone | Always | Pi `bash` + `read` |
+| Web fetch | Always | `curl`/HTTP via `bash` |
+
+All three retrieval tools are registered by this package's extension (`extensions/context-tools.ts`) and call the public REST APIs directly — no MCP servers needed.
+
+## Overview
+
+Code Context accepts **arbitrary input** — a natural-language question, a repo slug, a library name, or several of these at once — and routes each target to the right method(s). It prefers intermediate summaries so the main conversation stays clean, returning only synthesized summaries.
+
+## Methods
+
+### 1. DeepWiki (AI-powered repo documentation)
+
+Best for: Public GitHub repositories requiring architecture overview, component explanations, or high-level understanding.
+
+**Tool:** `context_deepwiki` — `owner`/`repo` + `mode: structure | contents | ask`
+
+**Process:**
+1. `context_deepwiki` with `mode: "structure"` (e.g. owner=`facebook`, repo=`react`)
+2. `context_deepwiki` with `mode: "contents"` for full wiki text, or `mode: "ask"` + `question` for targeted Q&A
+
+**Strengths:** Zero setup, instant AI-summarized documentation.
+
+**Limitations:** Only works for public GitHub repos; coverage varies by popularity.
+
+---
+
+### 2. Context7 (library documentation)
+
+Best for: Getting up-to-date API docs, usage examples, and version-specific documentation for npm/pip packages.
+
+**Tool:** `context_context7` — `query` + optional `topic`
+
+**Process:**
+1. `context_context7` with the library name (e.g. `"react"`, `"fastapi"`)
+2. Pass a `topic` (e.g. `"auth"`, `"ssr"`) for focused snippets; include the version in the query when given (`react@18`)
+
+**Strengths:** Always current docs, supports version pinning, covers thousands of libraries.
+
+**Limitations:** Requires the library to be indexed; less useful for internal packages.
+
+---
+
+### 3. Exa Code Search (web-wide code examples)
+
+Best for: Finding real-world usage patterns, StackOverflow answers, GitHub Gist examples.
+
+**Tool:** `context_exa` — `query` + optional `numResults` (requires `EXA_API_KEY`)
+
+**Query tips:**
+- Include language: `"TypeScript React"`
+- Include version: `"Next.js 14 app router"`
+- Use exact identifiers: `"useServerAction"`
+- Add pattern type: `"example"`, `"error handling"`
+
+**Strengths:** Finds diverse real-world examples beyond official docs.
+
+**Limitations:** Results may be outdated; verify publication dates.
+
+---
+
+### 4. Git Clone (direct code inspection)
+
+Best for: Private repositories, detailed implementation review, or when other methods lack depth.
+
+**Process:**
+1. `git clone <repo-url> /tmp/<repo-name> --depth=1`
+2. Read key files: entry points, configuration, core modules
+3. Use bash find/grep and Pi `read` to analyze structure and patterns
+4. Clean up: `rm -rf /tmp/<repo-name>`
+
+**Strengths:** Full code access, works with private repos.
+
+**Limitations:** Requires network/disk space; slow for large repos.
+
+---
+
+### 5. Web Search + Fetch (post-clone enrichment)
+
+Best for: Enriching clone findings with changelogs, issue discussions, migration guides.
+
+**Tools:** web search via `curl`/HTTP, HTTP fetch via `curl`
+
+**When to use:** After completing Method 4. Gives you the *why* and *what changed*.
+
+**Query patterns:**
+- Changelogs: `"<repo> CHANGELOG v<version>"`
+- Design rationale: `"<repo> <concept> why OR rationale site:github.com"`
+- Migration: `"<repo> migrate from <old> to <new>"`
+
+**Strengths:** Surfaces context never in source code.
+
+**Limitations:** Results may be stale; always validate against actual code.
+
+---
+
+## Usage
+
+### Pi skill: get-context
+
+Run `/skill:get-context` followed by a natural-language question, repository slug, library name, or several targets. For example:
+
+```text
+/skill:get-context React 19 server actions error handling
+/skill:get-context facebook/react
+/skill:get-context facebook/react zustand --method=deepwiki,context7
+```
+
+`--method=` accepts `deepwiki,context7,exa,clone,web,all` (comma-separated). With no target, the skill reads dependency manifests in the current directory. It classifies each target and routes it through the allowed methods, noting gaps when a permitted method cannot cover it.
+
+### Optional manual brief
+
+`agents/context-researcher.md` is an optional manual prompt brief for an isolated research pass. Pi does not load it as an invocable agent; use the `get-context` skill for the executable workflow.
+
+The package's internal method-selection guidance is loaded by the `get-context` workflow.
+
+## Method Selection Guide
+
+| Scenario | Primary | Fallback |
+|----------|---------|----------|
+| "How does X library work?" | Context7 | DeepWiki |
+| "Understand Y repo architecture" | DeepWiki | Git Clone |
+| "Find examples of Z pattern" | Exa | Context7 |
+| "Inspect private/internal repo" | Git Clone | - |
+| "What changed in v3?" | Context7 | Exa |
+| "How are modules connected?" | DeepWiki | Git Clone |
+| "Why was this design decision?" | Git Clone → Web Search | DeepWiki |
+| "Compare X vs Y" (natural-language) | Exa + Context7 | Web Search |
+| "Best practice for Z" (natural-language) | Web Search | Exa |
+
+## Structure
+
+```
+code-context/
+├── extensions/
+│   └── context-tools.ts         # Native pi tools: context_deepwiki / context_context7 / context_exa
+├── agents/
+│   └── context-researcher.md    # Isolated research agent brief
+├── skills/
+│   ├── code-context/            # Knowledge skill (internal)
+│   │   └── SKILL.md            # Method selection guide
+│   └── get-context/             # User-invocable command
+│       └── SKILL.md            # Command workflow
+└── README.md
+```
+
+## Prerequisites
+
+- Pi 0.84+ (extensions + custom tools)
+- Network access for external lookups
+- `EXA_API_KEY` for the Exa method (optional for the other four)
+
+## Best Practices
+
+- **Local first**: Always check local context (package.json, imports) before external lookups
+- **Isolated execution**: External lookups run in agent context to keep main conversation clean
+- **Combine methods**: For comprehensive context, use DeepWiki → Context7 → Exa → Clone
+- **Verify sources**: Cross-reference fetched content against actual code
+
+## License
+
+MIT
+
+## Author
+
+Frad LEE (fradser@gmail.com)

package/agents/context-researcher.md

@@ -0,0 +1,36 @@
+---
+name: context-researcher
+description: Research a library, repository, or code pattern without polluting the main conversation. Uses the native context_deepwiki/context_context7/context_exa tools when applicable, otherwise git clone + HTTP fetch via Pi bash/read. Accepts natural-language queries, repo slugs, library names, or any combination.
+---
+
+# Context researcher (optional agent brief)
+
+Pi does not load Claude Code agent files automatically. Treat this file as a **prompt brief** when you want an isolated research pass. Prefer `/skill:get-context` or `/skill:code-context` for the executable workflow.
+
+## Runtime requirements
+
+| Method | Requirement |
+|--------|-------------|
+| DeepWiki | Native `context_deepwiki` tool |
+| Context7 | Native `context_context7` tool |
+| Exa | Native `context_exa` tool (+ optional `EXA_API_KEY`) |
+| Git clone | `git` + Pi `bash` / `read` (always) |
+| Web | `curl` or host HTTP via Pi `bash` (always) |
+
+If a native context tool is unavailable or fails, skip that method, use clone + web, and report which methods ran and why the fallback was needed.
+
+## Process
+
+1. **Parse the request** — targets and optional `--method=` list (see `/skill:get-context`).
+2. **Classify** each target (repo / library / natural-language).
+3. **Select methods** per `/skill:code-context` selection guide.
+4. **Execute with Pi tools** — use the applicable native context tools (`context_deepwiki`, `context_context7`, `context_exa`) plus `bash` and `read`. Summarize intermediates; do not dump raw payloads.
+5. **Return** a concise architecture/API/examples summary only.
+
+## Output format
+
+- Target classification
+- Methods used (and skipped, with reason)
+- Key findings (bullets)
+- Copyable snippets only when necessary
+- Open questions / confidence notes

package/extensions/context-tools.ts

@@ -0,0 +1,275 @@
+/**
+ * Native pi tools for DeepWiki / Context7 / Exa retrieval.
+ *
+ * Replaces the package's `.mcp.json` (MCP servers). pi has no built-in MCP
+ * support (docs/usage.md), so these tools call the public REST APIs directly:
+ *   - context_deepwiki  → https://mcp.deepwiki.com/mcp (DeepWiki's public JSON-RPC/SSE API)
+ *   - context_context7  → https://context7.com/api/v1/{search,docs}
+ *   - context_exa       → https://api.exa.ai/search  (needs EXA_API_KEY)
+ *
+ * Pure HTTP tools — available in interactive and non-interactive runs alike.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { truncateHead, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type } from "typebox";
+
+const MAX_CHARS = 60_000;
+const TIMEOUT_MS = 30_000;
+const DEEPWIKI_MCP = "https://mcp.deepwiki.com/mcp";
+
+interface ToolTextResult {
+	content: [{ type: "text"; text: string }];
+	details: Record<string, unknown>;
+}
+
+function textResult(text: string, details: Record<string, unknown> = {}): ToolTextResult {
+	return { content: [{ type: "text", text }], details };
+}
+
+function truncate(text: string): string {
+	if (text.length <= MAX_CHARS) return text;
+	const result = truncateHead(text, { maxLines: DEFAULT_MAX_LINES, maxBytes: MAX_CHARS });
+	return `${result.content}\n\n…[truncated ${text.length - MAX_CHARS} chars]`;
+}
+
+function requestSignal(signal: AbortSignal | undefined): AbortSignal {
+	const timeout = AbortSignal.timeout(TIMEOUT_MS);
+	return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function httpJson(
+	url: string,
+	init: RequestInit = {},
+	signal: AbortSignal | undefined,
+): Promise<{ ok: boolean; status: number; body: string }> {
+	const res = await fetch(url, { ...init, signal: requestSignal(signal) });
+	const body = await res.text();
+	return { ok: res.ok, status: res.status, body };
+}
+
+/**
+ * DeepWiki's public API is a JSON-RPC-over-HTTP/SSE endpoint (mcp.deepwiki.com).
+ * Call a tool directly — no MCP client or sidecar process needed.
+ */
+async function deepwikiCall(
+	tool: string,
+	args: Record<string, unknown>,
+	signal: AbortSignal | undefined,
+): Promise<string> {
+	const res = await fetch(DEEPWIKI_MCP, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json, text/event-stream",
+		},
+		body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "tools/call", params: { name: tool, arguments: args } }),
+		signal: requestSignal(signal),
+	});
+	const body = await res.text();
+	if (!res.ok) throw new Error(`DeepWiki HTTP ${res.status}: ${body.slice(0, 200)}`);
+
+	// SSE frames: `event: message` + one or more `data:` lines, blank-line terminated.
+	// Join multiline payloads, keep the last frame with data.
+	let payload: string | null = null;
+	let currentData: string[] = [];
+	for (const raw of body.split("\n")) {
+		const line = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+		if (line === "") {
+			if (currentData.length > 0) payload = currentData.join("\n");
+			currentData = [];
+			continue;
+		}
+		if (line.startsWith(":")) continue; // SSE comment
+		if (line.startsWith("data:")) {
+			currentData.push(line.slice(5).replace(/^ /, ""));
+		}
+	}
+	if (currentData.length > 0) payload = currentData.join("\n");
+	if (payload === null) throw new Error("DeepWiki: no data frame in response");
+
+	const data = JSON.parse(payload);
+	if (data.error) throw new Error(`DeepWiki: ${data.error.message ?? JSON.stringify(data.error)}`);
+	const content = data.result?.content;
+	if (Array.isArray(content)) {
+		return content.map((c) => (typeof c?.text === "string" ? c.text : JSON.stringify(c))).join("\n");
+	}
+	return JSON.stringify(data.result ?? data);
+}
+
+const DeepWikiParams = Type.Object({
+	owner: Type.String({ description: "GitHub owner, e.g. 'facebook'" }),
+	repo: Type.String({ description: "GitHub repository name, e.g. 'react'" }),
+	mode: StringEnum(["structure", "contents", "ask"], {
+		description: "structure = table of contents; contents = full wiki text; ask = targeted Q&A",
+	}),
+	question: Type.Optional(
+		Type.String({ description: "Required when mode is 'ask'; the question about the repository" }),
+	),
+});
+const Context7Params = Type.Object({
+	query: Type.String({ description: "Library name to find docs for, e.g. 'fastapi' or 'react'" }),
+	topic: Type.Optional(
+		Type.String({ description: "Optional topic focus, e.g. 'auth' or 'ssr' (best results with a topic)" }),
+	),
+});
+
+const ExaParams = Type.Object({
+	query: Type.String({ description: "Precise natural-language or code query" }),
+	numResults: Type.Optional(
+		Type.Number({ description: "Number of results (default 5)", default: 5 }),
+	),
+});
+
+export default function (pi: ExtensionAPI) {
+	pi.registerTool({
+		name: "context_deepwiki",
+		label: "DeepWiki repo docs",
+		description:
+			"Fetch AI-generated documentation for a public GitHub repository from DeepWiki. " +
+			"mode=structure returns the table of contents; mode=contents returns the full wiki text; " +
+			"mode=ask answers a specific question with sources. No API key required.",
+		promptSnippet: "Look up AI-generated documentation for a public GitHub repo from DeepWiki",
+		promptGuidelines: [
+			"Use context_deepwiki to fetch structured repo documentation via DeepWiki instead of cloning when you only need a high-level understanding.",
+		],
+		parameters: DeepWikiParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal) {
+			const repo = `${params.owner}/${params.repo}`;
+			if (params.mode === "ask") {
+				if (!params.question) {
+					return textResult("context_deepwiki: mode 'ask' requires a question");
+				}
+				const answer = await deepwikiCall("ask_question", { repoName: repo, question: params.question }, signal);
+				return textResult(truncate(answer));
+			}
+			const tool = params.mode === "structure" ? "read_wiki_structure" : "read_wiki_contents";
+			const out = await deepwikiCall(tool, { repoName: repo }, signal);
+			return textResult(truncate(out));
+		},
+	});
+
+	pi.registerTool({
+		name: "context_context7",
+		label: "Context7 library docs",
+		description:
+			"Fetch up-to-date, version-aware documentation snippets for a library from Context7. " +
+			"Searches the library, then retrieves markdown docs (optionally focused on a topic). " +
+			"Anonymous usage is rate-limited; set CONTEXT7_API_KEY (Authorization: Bearer) for per-key quota.",
+		promptSnippet: "Look up version-aware library documentation from Context7",
+		promptGuidelines: [
+			"Use context_context7 to look up library docs instead of guessing APIs from memory. Anonymous usage is rate-limited; set CONTEXT7_API_KEY for higher quota.",
+		],
+		parameters: Context7Params,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal) {
+			const headers: Record<string, string> = {};
+			if (process.env.CONTEXT7_API_KEY) {
+				headers.Authorization = `Bearer ${process.env.CONTEXT7_API_KEY}`;
+			}
+
+			const { ok, status, body } = await httpJson(
+				`https://context7.com/api/v1/search?query=${encodeURIComponent(params.query)}`,
+				{ headers },
+				signal,
+			);
+			if (!ok) {
+				if (status === 401 || status === 403) {
+					return textResult(
+						`Context7 search needs an API key (HTTP ${status}). Set CONTEXT7_API_KEY ` +
+							`(Authorization: Bearer) or fall back to web/clone methods.`,
+					);
+				}
+				throw new Error(`Context7 search failed (HTTP ${status}): ${body.slice(0, 400)}`);
+			}
+
+			let data: { results?: Array<{ id?: unknown }> };
+			try {
+				data = JSON.parse(body);
+			} catch {
+				throw new Error(`Context7 search: unexpected response: ${body.slice(0, 400)}`);
+			}
+			const results = Array.isArray(data.results) ? data.results : [];
+			if (results.length === 0) {
+				return textResult(`Context7: no library found for "${params.query}"`);
+			}
+			const libraryId = typeof results[0]?.id === "string" ? results[0].id : "";
+			if (!libraryId) {
+				return textResult(`Context7: search returned no usable library id for "${params.query}"`);
+			}
+
+			// v1 doc ids look like "/owner/repo" — strip the leading slash for the path.
+			const path = libraryId.startsWith("/") ? libraryId.slice(1) : libraryId;
+			const topic = params.topic ? `&topic=${encodeURIComponent(params.topic)}` : "";
+			const docUrl = `https://context7.com/api/v1/${path}?type=txt${topic}`;
+			const doc = await httpJson(docUrl, { headers }, signal);
+			if (!doc.ok) {
+				throw new Error(`Context7 docs failed (HTTP ${doc.status}): ${doc.body.slice(0, 400)}`);
+			}
+			return textResult(
+				`Context7 docs for "${params.query}" (${libraryId})${params.topic ? `, topic ${params.topic}` : ""}:\n\n${truncate(doc.body)}`,
+			);
+		},
+	});
+
+	pi.registerTool({
+		name: "context_exa",
+		label: "Exa web/code search",
+		description:
+			"Search the web for real-world code patterns, comparisons, and up-to-date information via Exa. " +
+			"Requires the EXA_API_KEY environment variable. Returns titles, URLs, and text snippets.",
+		promptSnippet: "Search the web for real-world code patterns, comparisons, and up-to-date information via Exa",
+		promptGuidelines: [
+			"Use context_exa to search the web when you need current information, code patterns, or comparisons. Requires EXA_API_KEY to be set.",
+		],
+		parameters: ExaParams,
+		executionMode: "sequential",
+
+		async execute(_toolCallId, params, signal) {
+			const apiKey = process.env.EXA_API_KEY;
+			if (!apiKey) {
+				return textResult(
+					"context_exa: EXA_API_KEY is not set. Set EXA_API_KEY to enable Exa search, " +
+						"or fall back to web search via curl / GitHub search.",
+				);
+			}
+
+			const numResults = Math.max(1, Math.min(10, Math.floor(params.numResults ?? 5)));
+			const { ok, status, body } = await httpJson(
+				"https://api.exa.ai/search",
+				{
+					method: "POST",
+					headers: {
+						"Content-Type": "application/json",
+						"x-api-key": apiKey,
+					},
+					body: JSON.stringify({ query: params.query, numResults, contents: { text: true } }),
+				},
+				signal,
+			);
+			if (!ok) throw new Error(`Exa search failed (HTTP ${status}): ${body.slice(0, 400)}`);
+
+			let data: { results?: Array<{ title?: string; url?: string; text?: string }> };
+			try {
+				data = JSON.parse(body);
+			} catch {
+				throw new Error(`Exa search: unexpected response: ${body.slice(0, 400)}`);
+			}
+			const results = Array.isArray(data.results) ? data.results : [];
+			if (results.length === 0) {
+				return textResult(`Exa: no results for "${params.query}"`);
+			}
+			const lines = results.map((r, i) => {
+				const title = r.title || r.url || "(untitled)";
+				const url = r.url || "";
+				const text = typeof r.text === "string" ? r.text.slice(0, 1200) : "";
+				return `${i + 1}. ${title}\n   ${url}\n${text ? `   ${text}` : ""}`;
+			});
+			return textResult(truncate(lines.join("\n\n")));
+		},
+	});
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@fradser/pi-context",
+  "version": "0.5.0",
+  "description": "Retrieve code context for any repo, library, or natural-language query via DeepWiki, Context7, Exa, git clone, and web search+fetch. Native pi tools (context_deepwiki/context_context7/context_exa) call the public REST APIs directly — no MCP servers.",
+  "keywords": [
+    "pi-package",
+    "code-context",
+    "deepwiki",
+    "context7",
+    "exa"
+  ],
+  "author": "Frad LEE <fradser@gmail.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/FradSer/pi-packages.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "skills",
+    "extensions",
+    "agents",
+    "README.md"
+  ],
+  "pi": {
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-ai": "*",
+    "typebox": "*"
+  }
+}

package/skills/code-context/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: code-context
+description: This skill should be used when the user asks to "understand a codebase", "get code context", "research a library", "explore a repository", "find code examples", "look up documentation", asks a natural-language code/technology question (e.g. "how does X work", "X vs Y", "best practice for Z"), or wants to understand how a specific project, library, or concept works before making changes.
+disable-model-invocation: true
+---
+
+# Code Context Retrieval
+
+This skill provides 5 methods for retrieving code context. Select methods based on the target: public GitHub repos, library docs, code search, direct inspection, or post-clone web enrichment.
+
+## Pi tools and runtime
+
+Use Pi built-ins: `bash`, `read`, `edit` (rarely), `write` (rarely), plus this package's native tools from `extensions/context-tools.ts`.
+
+| Method | Runtime |
+|--------|---------|
+| DeepWiki | `context_deepwiki` tool (always available; no key) |
+| Context7 | `context_context7` tool (always available; optional `CONTEXT7_API_KEY` for higher quota) |
+| Exa | `context_exa` tool (requires `EXA_API_KEY` env) |
+| Git clone | `bash` + `read` (always available) |
+| Web search+fetch | `bash` + `curl` (or host HTTP) |
+
+If a tool reports an error (e.g. `EXA_API_KEY` unset), skip it and use clone/web fallbacks. Report which methods ran.
+
+## Token Isolation (Critical)
+
+Prefer small intermediate summaries over dumping entire API payloads into the long-lived conversation:
+
+- **DeepWiki**: structure → relevant pages → short architecture summary
+- **Context7**: resolve id → query → minimum viable API surface + examples
+- **Exa**: query → dedupe near-identical snippets → short explanation
+- **Git clone**: clone to `/tmp/`, read entry points, cleanup, return structure + patterns
+- **Web**: targeted queries, fetch high-signal URLs only, validate against code when possible
+
+## Method 1: DeepWiki (AI-powered repo documentation)
+
+Best for: public GitHub repos needing architecture overview quickly.
+
+**Tool**: `context_deepwiki` (native, always available)
+
+**Process**:
+1. `context_deepwiki` with `owner`/`repo` and `mode: "structure"` (e.g. `facebook` / `react`)
+2. `context_deepwiki` `mode: "contents"` for the full wiki text, or `mode: "ask"` with a `question` for targeted Q&A
+3. Extract architecture summary and key relationships
+
+**Fallback on error**: Method 4 (clone) + Method 5 (web) on GitHub docs/README.
+
+## Method 2: Context7 (library documentation)
+
+Best for: up-to-date API docs and version-specific examples for packages/frameworks.
+
+**Tool**: `context_context7` (native, always available)
+
+**Process**:
+1. `context_context7` with the library name as `query` (e.g. `fastapi`, `react`)
+2. Pass a `topic` (e.g. `auth`, `ssr`) for focused snippets; include the version in the query when given (`react@18`)
+3. Extract the minimum viable API surface + examples
+
+**Fallback on error**: official docs URLs via `curl`, or clone of the library repo docs.
+
+## Method 3: Exa Code Search
+
+Best for: real-world usage patterns and cross-web code examples.
+
+**Tool**: `context_exa` (native; requires `EXA_API_KEY`)
+
+**Process**:
+1. Call with a precise query (language/framework/version/identifiers)
+2. Prefer recent sources; dedupe mirrors
+
+**Fallback when key missing / error**: GitHub code search URLs / known docs via `curl`, or clone representative examples.
+
+## Method 4: Git Clone (direct code inspection)
+
+Best for: private repos, deep implementation review, when other methods lack depth.
+
+**Process**:
+1. `git clone <repo-url> /tmp/<repo-name> --depth=1`
+2. `read` key files: entry points, config, core modules
+3. Map structure with `bash` find/ls; search with `bash` grep or Pi search tools if available
+4. Cleanup: `rm -rf /tmp/<repo-name>`
+
+## Method 5: Web Search + Fetch
+
+Best for: rationale, changelogs, issues, migration guides.
+
+**Tools**: `bash` + `curl` (or host HTTP client). There are no Pi built-ins named web search via `curl`/HTTP / HTTP fetch via `curl`.
+
+**Process**:
+1. Derive version-anchored queries from the question or clone findings
+2. Fetch high-signal URLs (official docs, GitHub issues/PRs, changelogs)
+3. Extract only relevant sections; cross-check against cloned code when available
+4. Discard results older than ~2 years unless foundational
+
+**Query patterns**:
+- Changelogs: `"<repo> CHANGELOG v<version>"`
+- Rationale: `"<repo> <concept> why OR rationale site:github.com"`
+- Known issues: `"<repo> <symbol> issue OR bug site:github.com"`
+- Migration: `"<repo> migrate from <old> to <new>"`
+
+## Target Classification
+
+- **Repo target** — `owner/repo` or git URL → DeepWiki (`context_deepwiki`) or Git Clone
+- **Library target** — package name / `name@version` → Context7 (`context_context7`) else web/docs clone
+- **Natural-language target** — question/comparison → Exa (`context_exa`) and/or Web; Context7 if a library is named
+
+When caller passes `--method=`, use the intersection of allowed and applicable methods. Empty intersection → skip and report.
+
+## Method Selection Guide
+
+| Scenario | Primary | Fallback |
+|----------|---------|----------|
+| "How does X library work?" | Context7 | Web / clone |
+| "Architecture of Y repo" | DeepWiki | Git Clone |
+| "Examples of Z pattern" | Exa | Context7 / web |
+| "Private/internal repo" | Git Clone | — |
+| "What changed in v3?" | Context7 | Web |
+| "Why this design?" | Git Clone → Web | DeepWiki |
+| "Compare X vs Y" | Exa + Context7 | Web |
+| "Best practice for Z" | Web | Exa |
+
+## Combining Methods
+
+1. DeepWiki / clone for architecture
+2. Context7 for API surface
+3. Exa / web for community patterns
+4. Always prefer read-only operations; clean up `/tmp` clones

package/skills/get-context/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: get-context
+description: Execute this when the user requests code context for a repository, library, or any natural-language code/technology question using DeepWiki, Context7, Exa, git clone, and/or web search+fetch.
+---
+
+# get-context
+
+Run the full code-context workflow using Pi tools. Prefer keeping heavy lookups out of a single giant turn when possible — summarize intermediate results.
+
+## Pi tools and runtime
+
+| Capability | How |
+|------------|-----|
+| Clone / local files | `bash` (`git clone`), `read`, `bash` (find/grep) |
+| Web fetch | `bash` with `curl -fsSL` (or available HTTP client) |
+| DeepWiki / Context7 / Exa | Native tools from this package's `extensions/context-tools.ts`: `context_deepwiki`, `context_context7`, `context_exa` (Exa needs `EXA_API_KEY`) |
+
+If a native tool is unavailable (e.g. `EXA_API_KEY` unset), fall back to clone + web fetch methods from `/skill:code-context`.
+
+## Invocation args
+
+When invoked as `/skill:get-context <args>`, the text after the skill block is the user-provided arguments. Pi does not expand `$ARGUMENTS` placeholders inside skill bodies; use the trailing invocation text.
+
+1. Split into positional targets and optional `--method=` flag.
+   - `--method=` accepts a comma-separated list from `deepwiki,context7,exa,clone,web,all`. Default: `all`.
+   - Quoted strings are one target.
+   - Multiple positional tokens are multiple targets.
+2. Classify each target:
+   - GitHub slug (`owner/repo`) or git URL → repo (DeepWiki via `context_deepwiki`, else clone).
+   - Bare package name or `name@version` → library (Context7 via `context_context7`, else web + clone of docs repo when known).
+   - Anything else → natural-language (Exa via `context_exa` when `EXA_API_KEY` is set, else web search via `curl` to searchable sources / known docs URLs).
+3. Empty input: read dependency manifests in cwd (`package.json`, `go.mod`, `pyproject.toml`, `Cargo.toml`) and use detected dependencies as targets.
+
+## Execute
+
+1. Load and follow `/skill:code-context` (or `read` that skill file) for method selection and process detail.
+2. Run methods with Pi tools as above; do not invent Claude-only tools (`Task`, `WebSearch`, `WebFetch`).
+3. Return a synthesized summary only — drop raw bulk payloads.