[codex] Update skills for Tool API v3 (#5)

* Update skills for Tool API v3

* Remove legacy chat alias guidance

* Address skills review findings

* Clarify Tool API v3 error contract

* Align artifact batch documentation

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.1.0",
+  "version": "3.0.0",
   "author": {
     "name": "CodeAlive AI",
     "email": "hello@codealive.ai"

agents/codealive-context-explorer.md

@@ -89,7 +89,7 @@ When unsure, start with `search.py` — it covers more ground; pivot to `grep.py
 - Use only local `Grep`/`Glob` when the question is about an external repo or a cross-repo concept.
 - Trust the `description` field of search results as ground truth — always fetch or read the real source.
 - Run a single empty search and conclude "nothing found" — try at least 2 different query phrasings before giving up.
-- Run `chat.py`. Only do so when the user explicitly asks (e.g. "use chat", "use codebase_consultant").
+- Run `chat.py`. Only do so when the user explicitly asks (e.g. "use chat", "call the chat tool").
 
 ## Output Format
 

skills/codealive-context-engine/SKILL.md

@@ -40,15 +40,25 @@ Do NOT retry the failed script until setup completes successfully.
 | **List Data Sources** | `datasources.py` | Instant | Free | Discovering indexed repos and workspaces. With `--query "task"`, runs an AI relevance filter (low cost, not instant) returning only the relevant sources |
 | **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; 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"). |
+| **Repository Ontology** | `ontology.py` | Fast | Low | High-level orientation for exactly one repository |
+| **File Tree** | `tree.py` | Fast | Free | Bounded repository tree inspection |
+| **Read File** | `read_file.py` | Fast | Free | Read one repository-relative file path, optionally with a line range |
+| **Fetch Artifacts** | `fetch.py` | Fast | Free | Retrieve full content for search result identifiers |
+| **Artifact Relationships** | `relationships.py` | Fast | Free | Full call graph, inheritance, or symbol references for one artifact |
+| **ArtifactQuery Schema** | `schema.py` | Fast | Free | Inspect supported metadata query entities, fields, and examples |
+| **Artifact Metadata Query** | `metadata.py` | Fast | Low | Read-only aggregate/query analytics across indexed repositories |
+| **Chat with Codebase** | `chat.py` | Slow | High | Stateless synthesized Q&A. Call ONLY when the user explicitly asks. |
 
 **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.
 
-**Chat is not recommended:** `chat.py` invokes an LLM on the server side, can take up to 30 seconds, and is significantly more expensive per call. Do NOT call it unless the user has explicitly requested it (e.g. "use chat", "use codebase_consultant", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" do NOT qualify — they refer to search tools.
+**Chat is not recommended:** `chat.py` invokes an LLM on the server side, can take substantially longer than retrieval, and is significantly more expensive per call. It is stateless in v3: include prior findings, artifact identifiers, assumptions, scope, and constraints in each question. Do NOT call it unless the user has explicitly requested it (e.g. "use chat", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" do NOT qualify — they refer to search tools.
 
-**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `search.py`, `grep.py`, `fetch.py`, `relationships.py`, and local file reads.
+**Repairable tool errors:** Treat a returned `<tool_error>` as a failed call,
+not as an empty successful result. Follow its `<try>` guidance, repair the
+arguments, and retry only when the `<retry>` field permits it. Tool API v3
+always preserves the same error in `obj.error` for JSON-mode automation.
+
+**Highest-confidence guidance:** If your agent supports subagents and the task needs maximum reliability or depth, prefer a subagent-driven workflow that combines `ontology.py`, `search.py`, `grep.py`, `fetch.py`, `tree.py`/`read_file.py`, `relationships.py`, `metadata.py`, and local file reads.
 
 **Three-step workflow (search → triage → load real content):**
 1. **Search** — find relevant code locations with descriptions and identifiers
@@ -144,11 +154,11 @@ python scripts/relationships.py "my-org/backend::src/svc.py::Service" --profile
 ### 5. Chat with codebase (not recommended — only if user explicitly asks)
 
 ```bash
-python scripts/chat.py "Explain the authentication flow" my-backend
-python scripts/chat.py "What about security considerations?" --continue CONV_ID
+python scripts/chat.py "Explain the authentication flow. Prior context: none." my-backend
+python scripts/chat.py "Given these prior findings and identifiers: ..., what about security considerations?" my-backend
 ```
 
-**Do not call chat unless the user explicitly asks for it.** Use search, grep, fetch, and relationships for all other tasks.
+**Do not call chat unless the user explicitly asks for it.** v3 chat is stateless and has no `conversation_id`; include all needed context in each question. Use ontology, search, grep, fetch/read, relationships, and metadata queries for all other tasks.
 
 ## Tool Reference
 
@@ -223,7 +233,7 @@ python scripts/fetch.py <identifier1> [identifier2...] [--data-source NAME_OR_ID
 
 | Constraint | Value |
 |-----------|-------|
-| Max identifiers per request | 20 |
+| Max identifiers per request | 50 |
 | Identifiers source | `identifier` field from search results |
 | Identifier format | `{owner/repo}::{path}::{symbol}` (symbols), `{owner/repo}::{path}` (files) |
 | `--data-source NAME_OR_ID` | Optional. Data source Name or Id (from a result's `Source:` line) to disambiguate an identifier indexed in more than one data source |
@@ -295,23 +305,17 @@ 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.
+**Do NOT call unless the user explicitly asks** (e.g. "use chat", "call the chat tool"). Phrases like "ask CodeAlive" or "search CodeAlive" refer to search tools, not chat.
 
-Sends your question to an AI consultant that has full context of the indexed codebase. Returns synthesized, ready-to-use answers. Supports conversation continuity for follow-ups.
+Sends your self-contained question to an AI consultant that has full context of the selected indexed codebase. Returns synthesized, ready-to-use answers.
 
-**This is slow and expensive** — runs an LLM on the server side, up to 30 seconds per call. For all standard tasks (finding code, understanding architecture, debugging), use `search.py`, `grep.py`, `fetch.py`, and `relationships.py` instead.
+**This is slow and expensive** — runs an LLM on the server side and can take substantially longer than retrieval. It is stateless in v3, so include prior findings, identifiers, assumptions, scope, and constraints in each question. For all standard tasks (finding code, understanding architecture, debugging), use ontology, search, grep, fetch/read, relationships, and metadata queries instead.
 
 ```bash
 python scripts/chat.py <question> <data_sources...> [options]
 ```
 
-| Option | Description |
-|--------|-------------|
-| `--continue <id>` | Continue a previous conversation (saves context and cost) |
-
-**Conversation continuity:** Every successful response includes a `conversation_id` (a 24-character hex Mongo ObjectId, e.g. `69fceb3e7b2a6a7efdd18180`) and a `message_id` of the same format. Pass `--continue <conversation_id>` for follow-up questions — this preserves context and is cheaper than starting fresh.
-
-Format guarantee: any value not matching `^[0-9a-fA-F]{24}$` is rejected client-side before the request is sent.
+There is no public `conversation_id` in v3. For follow-ups, restate the relevant context in the next `question`.
 
 ## Data Sources
 

skills/codealive-context-engine/scripts/chat.py

@@ -8,7 +8,7 @@
 Usage:
     python chat.py "How does authentication work?" my-repo
     python chat.py "Explain the database schema" workspace:backend-team
-    python chat.py "What's the best way to add caching?" --continue CONV_ID
+    python chat.py "What's the best way to add caching? Prior context: ..." my-repo
 
 Examples:
     # Ask about current project
@@ -20,15 +20,14 @@
     # Ask about dependencies/libraries
     python chat.py "How does lodash debounce work internally?" lodash
 
-    # Continue previous conversation
-    python chat.py "What about error handling?" --continue 69fceb3e7b2a6a7efdd18180
+    # v3 chat is stateless: include prior findings and constraints in every question.
+    python chat.py "Given prior finding X, what about error handling?" my-backend
 
     # Cross-project learning
     python chat.py "Show me authentication patterns across our org" workspace:all-backend
 """
 
 import sys
-import json
 from pathlib import Path
 
 # Add lib directory to path
@@ -41,63 +40,51 @@ def main():
     """CLI interface for codebase consultant."""
     if len(sys.argv) < 2:
         print("Error: Missing required arguments.", file=sys.stderr)
-        print("Usage: python chat.py <question> <data_source> [data_source2...] [--continue <conversation_id>]", file=sys.stderr)
+        print("Usage: python chat.py <question> <data_source> [data_source2...]", file=sys.stderr)
         sys.exit(1)
 
     if sys.argv[1] == "--help":
         print(__doc__)
         sys.exit(0)
 
     question = sys.argv[1]
-    conversation_id = None
     data_sources = []
 
     # Parse arguments
     i = 2
     while i < len(sys.argv):
         arg = sys.argv[i]
-        if arg == "--continue" and i + 1 < len(sys.argv):
-            conversation_id = sys.argv[i + 1]
-            i += 2
-        elif arg == "--conversation-id" and i + 1 < len(sys.argv):
-            conversation_id = sys.argv[i + 1]
-            i += 2
+        if arg in {"--continue", "--conversation-id"}:
+            print("Error: chat is stateless in v3; include prior context in the question instead.", file=sys.stderr)
+            sys.exit(1)
         else:
             data_sources.append(arg)
             i += 1
 
-    if not conversation_id and not data_sources:
-        print("Error: Either data sources or --continue <conversation_id> is required.", file=sys.stderr)
+    if not data_sources:
+        print("Error: At least one data source is required.", file=sys.stderr)
         print("Run datasources.py to see available sources.", file=sys.stderr)
         sys.exit(1)
 
     try:
         client = CodeAliveClient()
 
         print(f"💬 Question: {question}", file=sys.stderr)
-        if conversation_id:
-            print(f"🔄 Continuing conversation: {conversation_id}", file=sys.stderr)
-        else:
-            print(f"📚 Analyzing: {', '.join(data_sources)}", file=sys.stderr)
+        print(f"📚 Analyzing: {', '.join(data_sources)}", file=sys.stderr)
+        print("ℹ️  v3 chat is stateless; each question must include needed prior context.", file=sys.stderr)
         print(file=sys.stderr)
         print("🤔 Thinking...", file=sys.stderr)
         print(file=sys.stderr)
 
         result = client.chat(
             question=question,
-            data_sources=data_sources if data_sources else None,
-            conversation_id=conversation_id
+            data_sources=data_sources,
         )
 
         print("="*80)
-        print(result["answer"])
+        print(result)
         print("="*80)
 
-        if result.get("conversation_id"):
-            print()
-            print(f"💾 Conversation ID: {result['conversation_id']}")
-            print(f"   Use --continue {result['conversation_id']} to ask follow-up questions")
-
     except Exception as e:
         print(f"❌ Error: {e}", file=sys.stderr)
         sys.exit(1)

skills/codealive-context-engine/scripts/datasources.py

@@ -112,7 +112,7 @@ def format_datasources(datasources: list, as_json: bool = False, message: str =
 
 def main():
     """CLI interface for listing data sources."""
-    alive_only = True
+    ready_only = True
     as_json = False
     query = None
 
@@ -121,7 +121,7 @@ def main():
     while i < len(args):
         arg = args[i]
         if arg == "--all":
-            alive_only = False
+            ready_only = False
         elif arg == "--json":
             as_json = True
         elif arg == "--query":
@@ -137,14 +137,15 @@ def main():
 
     try:
         client = CodeAliveClient()
-        result = client.get_datasources(alive_only=alive_only, query=query)
-        if isinstance(result, dict):
-            datasources = result.get("dataSources", [])
-            message = result.get("message", "")
+        result = client.get_datasources(
+            ready_only=ready_only,
+            query=query,
+            output_format="json" if as_json else "agentic",
+        )
+        if as_json:
+            print(json.dumps(result, indent=2))
         else:
-            datasources = result
-            message = ""
-        print(format_datasources(datasources, as_json, message))
+            print(result)
 
     except Exception as e:
         print(f"❌ Error: {e}", file=sys.stderr)