pi-revit 0.4.0 → 0.5.1

package/extensions/pi-revit/script-library.ts

@@ -1,146 +1,146 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { mkdir, readdir, readFile, writeFile, rename } from "node:fs/promises";
-import { createHash, randomUUID } from "node:crypto";
-import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { mkdir, readdir, readFile, writeFile, rename } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import path from "node:path";
 import os from "node:os";
-
-type InputKind = "string" | "number" | "integer" | "boolean" | "object" | "array";
-interface Definition { name: string; description: string; code: string; input_types: Record<string, InputKind>; }
-interface Version extends Definition { version: string; created_at: string; }
-interface Receipt { operation_id: string; bridge_id: string; }
-type Result = { content: { type: "text"; text: string }[]; details?: unknown };
-type Runner = (args: Record<string, unknown>, signal: AbortSignal | undefined, prepared: (receipt: Receipt) => Promise<void>) => Promise<Result>;
-const kinds = ["string", "number", "integer", "boolean", "object", "array"] as const;
-const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
-const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
-const scriptName = (name: unknown) => {
-    if (typeof name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(name)) throw new Error("name must be 1–64 lowercase letters, digits, underscores or hyphens, starting with a letter.");
-    return name;
-};
-const versionId = (version: unknown) => {
-    if (typeof version !== "string" || !/^[a-f0-9]{64}$/.test(version)) throw new Error("version must be the exact saved 64-character hash.");
-    return version;
-};
-
-export function createScriptLibrary(root: string) {
-    const versions = path.join(root, "versions"), history = path.join(root, "history");
-    const definition = (value: Record<string, unknown>): Definition => {
-        const name = scriptName(value.name);
-        if (typeof value.code !== "string" || !value.code.trim() || value.code.length > 100000) throw new Error("code must contain 1–100,000 characters.");
-        if (typeof value.description !== "string" || value.description.length > 2000) throw new Error("description must be a string of at most 2,000 characters.");
-        if (!object(value.input_types) || Object.keys(value.input_types).length > 40) throw new Error("input_types must declare at most 40 named inputs.");
-        const input_types: Record<string, InputKind> = Object.create(null);
-        for (const key of Object.keys(value.input_types).sort()) {
-            if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || !kinds.includes(value.input_types[key] as InputKind)) throw new Error(`Invalid input declaration: ${key}.`);
-            input_types[key] = value.input_types[key] as InputKind;
-        }
-        return { name, description: value.description, code: value.code, input_types };
-    };
-    async function files(directory: string) {
-        try { return (await readdir(directory)).filter(file => file.endsWith(".json")); }
-        catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
-    }
-    async function read(name: unknown, version: unknown): Promise<Version> {
-        const value = JSON.parse(await readFile(path.join(versions, `${scriptName(name)}--${versionId(version)}.json`), "utf8"));
-        const content = definition(value);
-        if (content.name !== name || hash(content) !== version || value.version !== version) throw new Error("Saved script integrity check failed; no code was executed.");
-        return { ...content, version: value.version, created_at: value.created_at };
-    }
-    async function save(args: Record<string, unknown>) {
-        const content = definition(args), version = hash(content);
-        await mkdir(versions, { recursive: true });
-        const file = path.join(versions, `${content.name}--${version}.json`);
-        const value = { ...content, version, created_at: new Date().toISOString() };
-        try { await writeFile(file, JSON.stringify(value, null, 2), { encoding: "utf8", flag: "wx" }); }
-        catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
-        const saved = await read(content.name, version);
-        return { name: saved.name, version, created_at: saved.created_at, file_path: file, executed: false };
-    }
-    function validateInputs(saved: Version, input: unknown) {
-        if (!object(input)) throw new Error("inputs must be a JSON object.");
-        if (JSON.stringify(input).length > 100000) throw new Error("inputs exceed 100,000 JSON characters.");
-        for (const name of Object.keys(input)) if (!Object.hasOwn(saved.input_types, name)) throw new Error(`Undeclared input: ${name}.`);
-        for (const [name, kind] of Object.entries(saved.input_types)) {
-            const value = input[name];
-            const valid = Object.hasOwn(input, name) && (kind === "array" ? Array.isArray(value) : kind === "object" ? object(value)
-                : kind === "integer" ? Number.isSafeInteger(value) : kind === "number" ? typeof value === "number" && Number.isFinite(value) : typeof value === kind);
-            if (!valid) throw new Error(`Input '${name}' is required and must be ${kind}.`);
-        }
-        return input;
-    }
-    async function list(name: unknown, offset: number, limit: number) {
-        const filter = name === undefined ? undefined : scriptName(name);
-        const names = (await files(versions)).filter(file => /^[a-z][a-z0-9_-]{0,63}--[a-f0-9]{64}\.json$/.test(file) && (!filter || file.slice(0, file.lastIndexOf("--")) === filter)).sort();
-        const entries = [];
-        for (const file of names.slice(offset, offset + limit)) {
-            const split = file.lastIndexOf("--");
-            const value = await read(file.slice(0, split), file.slice(split + 2, -5));
-            entries.push({ name: value.name, version: value.version, description: value.description, input_types: value.input_types, created_at: value.created_at });
-        }
-        return { total_count: names.length, offset, entries, next_offset: offset + entries.length < names.length ? offset + entries.length : null };
-    }
-    async function writeHistory(record: Record<string, unknown>) {
-        await mkdir(history, { recursive: true });
-        const file = path.join(history, `${record.run_id}.json`), temp = `${file}.${randomUUID()}.tmp`;
-        await writeFile(temp, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx" });
-        await rename(temp, file);
-    }
-    async function readHistory(name: unknown, offset: number, limit: number) {
-        const filter = name === undefined ? undefined : scriptName(name);
-        const entries = [];
-        for (const file of await files(history)) {
-            if (!/^[a-f0-9-]{36}\.json$/.test(file)) continue;
-            const value = JSON.parse(await readFile(path.join(history, file), "utf8"));
-            if (!filter || value.name === filter) entries.push(value);
-        }
-        entries.sort((a, b) => b.started_at.localeCompare(a.started_at) || a.run_id.localeCompare(b.run_id));
-        return { total_count: entries.length, offset, entries: entries.slice(offset, offset + limit), next_offset: offset + limit < entries.length ? offset + limit : null };
-    }
-    return { root, read, save, list, validateInputs, writeHistory, readHistory };
-}
-
-export function registerScriptLibrary(pi: ExtensionAPI, run: Runner, render: (value: unknown) => Promise<Result>) {
-    const library = createScriptLibrary(path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "pi-revit", "scripts"));
-    pi.registerTool({
+
+type InputKind = "string" | "number" | "integer" | "boolean" | "object" | "array";
+interface Definition { name: string; description: string; code: string; input_types: Record<string, InputKind>; }
+interface Version extends Definition { version: string; created_at: string; }
+interface Receipt { operation_id: string; bridge_id: string; }
+type Result = { content: { type: "text"; text: string }[]; details?: unknown };
+type Runner = (args: Record<string, unknown>, signal: AbortSignal | undefined, prepared: (receipt: Receipt) => Promise<void>) => Promise<Result>;
+const kinds = ["string", "number", "integer", "boolean", "object", "array"] as const;
+const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+const hash = (value: unknown) => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const scriptName = (name: unknown) => {
+    if (typeof name !== "string" || !/^[a-z][a-z0-9_-]{0,63}$/.test(name)) throw new Error("name must be 1–64 lowercase letters, digits, underscores or hyphens, starting with a letter.");
+    return name;
+};
+const versionId = (version: unknown) => {
+    if (typeof version !== "string" || !/^[a-f0-9]{64}$/.test(version)) throw new Error("version must be the exact saved 64-character hash.");
+    return version;
+};
+
+export function createScriptLibrary(root: string) {
+    const versions = path.join(root, "versions"), history = path.join(root, "history");
+    const definition = (value: Record<string, unknown>): Definition => {
+        const name = scriptName(value.name);
+        if (typeof value.code !== "string" || !value.code.trim() || value.code.length > 100000) throw new Error("code must contain 1–100,000 characters.");
+        if (typeof value.description !== "string" || value.description.length > 2000) throw new Error("description must be a string of at most 2,000 characters.");
+        if (!object(value.input_types) || Object.keys(value.input_types).length > 40) throw new Error("input_types must declare at most 40 named inputs.");
+        const input_types: Record<string, InputKind> = Object.create(null);
+        for (const key of Object.keys(value.input_types).sort()) {
+            if (!/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(key) || !kinds.includes(value.input_types[key] as InputKind)) throw new Error(`Invalid input declaration: ${key}.`);
+            input_types[key] = value.input_types[key] as InputKind;
+        }
+        return { name, description: value.description, code: value.code, input_types };
+    };
+    async function files(directory: string) {
+        try { return (await readdir(directory)).filter(file => file.endsWith(".json")); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") return []; throw error; }
+    }
+    async function read(name: unknown, version: unknown): Promise<Version> {
+        const value = JSON.parse(await readFile(path.join(versions, `${scriptName(name)}--${versionId(version)}.json`), "utf8"));
+        const content = definition(value);
+        if (content.name !== name || hash(content) !== version || value.version !== version) throw new Error("Saved script integrity check failed; no code was executed.");
+        return { ...content, version: value.version, created_at: value.created_at };
+    }
+    async function save(args: Record<string, unknown>) {
+        const content = definition(args), version = hash(content);
+        await mkdir(versions, { recursive: true });
+        const file = path.join(versions, `${content.name}--${version}.json`);
+        const value = { ...content, version, created_at: new Date().toISOString() };
+        try { await writeFile(file, JSON.stringify(value, null, 2), { encoding: "utf8", flag: "wx" }); }
+        catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+        const saved = await read(content.name, version);
+        return { name: saved.name, version, created_at: saved.created_at, file_path: file, executed: false };
+    }
+    function validateInputs(saved: Version, input: unknown) {
+        if (!object(input)) throw new Error("inputs must be a JSON object.");
+        if (JSON.stringify(input).length > 100000) throw new Error("inputs exceed 100,000 JSON characters.");
+        for (const name of Object.keys(input)) if (!Object.hasOwn(saved.input_types, name)) throw new Error(`Undeclared input: ${name}.`);
+        for (const [name, kind] of Object.entries(saved.input_types)) {
+            const value = input[name];
+            const valid = Object.hasOwn(input, name) && (kind === "array" ? Array.isArray(value) : kind === "object" ? object(value)
+                : kind === "integer" ? Number.isSafeInteger(value) : kind === "number" ? typeof value === "number" && Number.isFinite(value) : typeof value === kind);
+            if (!valid) throw new Error(`Input '${name}' is required and must be ${kind}.`);
+        }
+        return input;
+    }
+    async function list(name: unknown, offset: number, limit: number) {
+        const filter = name === undefined ? undefined : scriptName(name);
+        const names = (await files(versions)).filter(file => /^[a-z][a-z0-9_-]{0,63}--[a-f0-9]{64}\.json$/.test(file) && (!filter || file.slice(0, file.lastIndexOf("--")) === filter)).sort();
+        const entries = [];
+        for (const file of names.slice(offset, offset + limit)) {
+            const split = file.lastIndexOf("--");
+            const value = await read(file.slice(0, split), file.slice(split + 2, -5));
+            entries.push({ name: value.name, version: value.version, description: value.description, input_types: value.input_types, created_at: value.created_at });
+        }
+        return { total_count: names.length, offset, entries, next_offset: offset + entries.length < names.length ? offset + entries.length : null };
+    }
+    async function writeHistory(record: Record<string, unknown>) {
+        await mkdir(history, { recursive: true });
+        const file = path.join(history, `${record.run_id}.json`), temp = `${file}.${randomUUID()}.tmp`;
+        await writeFile(temp, JSON.stringify(record, null, 2), { encoding: "utf8", flag: "wx" });
+        await rename(temp, file);
+    }
+    async function readHistory(name: unknown, offset: number, limit: number) {
+        const filter = name === undefined ? undefined : scriptName(name);
+        const entries = [];
+        for (const file of await files(history)) {
+            if (!/^[a-f0-9-]{36}\.json$/.test(file)) continue;
+            const value = JSON.parse(await readFile(path.join(history, file), "utf8"));
+            if (!filter || value.name === filter) entries.push(value);
+        }
+        entries.sort((a, b) => b.started_at.localeCompare(a.started_at) || a.run_id.localeCompare(b.run_id));
+        return { total_count: entries.length, offset, entries: entries.slice(offset, offset + limit), next_offset: offset + limit < entries.length ? offset + limit : null };
+    }
+    return { root, read, save, list, validateInputs, writeHistory, readHistory };
+}
+
+export function registerScriptLibrary(pi: ExtensionAPI, run: Runner, render: (value: unknown) => Promise<Result>) {
+    const library = createScriptLibrary(path.join(process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"), "pi-revit", "scripts"));
+    pi.registerTool({
         name: "manage_revit_scripts", label: "Manage Revit Scripts",
-        description: "Save, list, read, run and inspect local reusable C# scripts. Saving never executes code. Versions are immutable content hashes; read a version before explicitly running that exact hash. Every declared input is required; extra inputs are rejected. input_types validates top-level JSON kinds only; scripts validate nested contents and domain rules. Runs use execute_csharp with separate inputs JsonElement, exact expected_document_id and operation receipts. Scripts have the same unrestricted model/UI/file/external effects and transaction behavior as execute_csharp. Local history records version, document, input hash and receipt, not input values or results. After interruption, inspect get_revit_operation before retrying with the same _operation_id and identical inputs. No automatic runs or model saving.",
-        parameters: Type.Object({
-            action: Type.Union(["list", "save", "read", "run", "history"].map(value => Type.Literal(value))),
-            name: Type.Optional(Type.String()), version: Type.Optional(Type.String()), description: Type.Optional(Type.String({ maxLength: 2000 })),
-            code: Type.Optional(Type.String({ minLength: 1, maxLength: 100000 })),
-            input_types: Type.Optional(Type.Record(Type.String(), Type.Union(kinds.map(value => Type.Literal(value))))),
-            inputs: Type.Optional(Type.Record(Type.String(), Type.Unknown())), expected_document_id: Type.Optional(Type.String()), _operation_id: Type.Optional(Type.String()),
-            offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
-        }),
-        executionMode: "sequential",
-        async execute(_id, args, signal) {
-            const offset = Math.max(0, args.offset ?? 0), limit = Math.max(1, Math.min(100, args.limit ?? 20));
-            if (args.action === "save") return render(await library.save(args));
-            if (args.action === "list") return render(await library.list(args.name, offset, limit));
-            if (args.action === "history") return render(await library.readHistory(args.name, offset, limit));
-            if (args.action !== "read" && args.action !== "run") throw new Error("Unknown script library action.");
-            const saved = await library.read(args.name, args.version);
-            if (args.action === "read") return render(saved);
-            if (typeof args.expected_document_id !== "string" || !args.expected_document_id) throw new Error("Run requires expected_document_id from get_model_overview.");
-            const inputs = library.validateInputs(saved, args.inputs ?? {});
-            const record: Record<string, unknown> = { run_id: randomUUID(), name: saved.name, version: saved.version, started_at: new Date().toISOString(), expected_document_id: args.expected_document_id, inputs_hash: hash(inputs), state: "prepared" };
-            let dispatched = false;
-            try {
-                const result = await run({ code: saved.code, inputs, expected_document_id: args.expected_document_id, ...(args._operation_id !== undefined ? { _operation_id: args._operation_id } : {}) }, signal, async receipt => {
-                    Object.assign(record, receipt); await library.writeHistory(record); dispatched = true;
-                });
-                Object.assign(record, { state: "response_received", completed_at: new Date().toISOString() });
-                try { await library.writeHistory(record); }
-                catch { result.content.push({ type: "text", text: "The script response was received, but the final local history update failed. Use the operation receipt for its outcome." }); }
-                return result;
-            } catch (error) {
-                if (dispatched) {
-                    Object.assign(record, { state: "outcome_unconfirmed", completed_at: new Date().toISOString() });
-                    try { await library.writeHistory(record); } catch { /* Preserve the original error and operation ID. */ }
-                }
-                throw error;
-            }
-        },
-    });
-}
+        description: "Save, list, read, run and inspect local reusable C# scripts. Saving never executes code. Versions are immutable content hashes; read a version before explicitly running that exact hash. Every declared input is required; extra inputs are rejected. input_types validates top-level JSON kinds only; scripts validate nested contents and domain rules. Runs use execute_csharp with separate inputs JsonElement, exact expected_document_id and operation receipts. Scripts have the same unrestricted model/UI/file/external effects and transaction behavior as execute_csharp. Local history records version, document, input hash and receipt, not input values or results. After interruption, inspect get_revit_operation before retrying with the same _operation_id and identical inputs. No automatic runs or model saving.",
+        parameters: Type.Object({
+            action: Type.Union(["list", "save", "read", "run", "history"].map(value => Type.Literal(value))),
+            name: Type.Optional(Type.String()), version: Type.Optional(Type.String()), description: Type.Optional(Type.String({ maxLength: 2000 })),
+            code: Type.Optional(Type.String({ minLength: 1, maxLength: 100000 })),
+            input_types: Type.Optional(Type.Record(Type.String(), Type.Union(kinds.map(value => Type.Literal(value))))),
+            inputs: Type.Optional(Type.Record(Type.String(), Type.Unknown())), expected_document_id: Type.Optional(Type.String()), _operation_id: Type.Optional(Type.String()),
+            offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+        }),
+        executionMode: "sequential",
+        async execute(_id, args, signal) {
+            const offset = Math.max(0, args.offset ?? 0), limit = Math.max(1, Math.min(100, args.limit ?? 20));
+            if (args.action === "save") return render(await library.save(args));
+            if (args.action === "list") return render(await library.list(args.name, offset, limit));
+            if (args.action === "history") return render(await library.readHistory(args.name, offset, limit));
+            if (args.action !== "read" && args.action !== "run") throw new Error("Unknown script library action.");
+            const saved = await library.read(args.name, args.version);
+            if (args.action === "read") return render(saved);
+            if (typeof args.expected_document_id !== "string" || !args.expected_document_id) throw new Error("Run requires expected_document_id from get_model_overview.");
+            const inputs = library.validateInputs(saved, args.inputs ?? {});
+            const record: Record<string, unknown> = { run_id: randomUUID(), name: saved.name, version: saved.version, started_at: new Date().toISOString(), expected_document_id: args.expected_document_id, inputs_hash: hash(inputs), state: "prepared" };
+            let dispatched = false;
+            try {
+                const result = await run({ code: saved.code, inputs, expected_document_id: args.expected_document_id, ...(args._operation_id !== undefined ? { _operation_id: args._operation_id } : {}) }, signal, async receipt => {
+                    Object.assign(record, receipt); await library.writeHistory(record); dispatched = true;
+                });
+                Object.assign(record, { state: "response_received", completed_at: new Date().toISOString() });
+                try { await library.writeHistory(record); }
+                catch { result.content.push({ type: "text", text: "The script response was received, but the final local history update failed. Use the operation receipt for its outcome." }); }
+                return result;
+            } catch (error) {
+                if (dispatched) {
+                    Object.assign(record, { state: "outcome_unconfirmed", completed_at: new Date().toISOString() });
+                    try { await library.writeHistory(record); } catch { /* Preserve the original error and operation ID. */ }
+                }
+                throw error;
+            }
+        },
+    });
+}

package/extensions/pi-revit/tool-catalog.ts

@@ -1,5 +1,10 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { contractHash, descriptorLimits, packagedContracts, withApiLookups, type ToolLimit } from "./contracts.js";
+import { createDiscoveryIndex } from "./discovery.js";
+import { documentedTools, packagedGuidance, readablePathWithin, resolveToolDocumentation, skillRoot } from "./tool-documentation.js";
 
 export interface BridgeToolDescriptor {
 	name: string;
@@ -12,26 +17,89 @@ export interface BridgeToolDescriptor {
 	write?: boolean;
 	effects?: string[];
 	requiresDocument?: boolean;
+	documentKinds?: string[] | null;
 	promptSnippet?: string | null;
 	promptGuidelines?: string[] | null;
+	keywords?: string[] | null;
+	limits?: unknown;
+	verification?: string | null;
 }
 
+interface Candidate {
+	name: string; source: "native" | "bridge"; description: string | null; summary: string | null; keywords: string[];
+	tier: string | null; effects: string[] | null; verification: string | null; limits: ToolLimit[] | null; inputs: string[]; documentKinds: string[] | null;
+}
+interface Guide { name: string; kind: string; path: string | null; summary: string; keywords: string[] }
+
+/** Packaged guidance plus every skill found beside this package's skill (future subject skills included). */
+function loadGuidance(): Guide[] {
+	const guides: Guide[] = packagedGuidance.map(g => ({ name: g.name, kind: g.kind, path: readablePathWithin(skillRoot, g.path), summary: g.summary, keywords: g.keywords ?? [] }));
+	const skillsRoot = path.resolve(skillRoot, "..");
+	let directories: string[] = [];
+	try { directories = readdirSync(skillsRoot, { withFileTypes: true }).filter(d => d.isDirectory()).map(d => d.name).sort(); } catch { /* no sibling skills */ }
+	for (const directory of directories) {
+		const file = readablePathWithin(skillsRoot, path.join(directory, "SKILL.md"));
+		if (!file) continue;
+		try {
+			const front = readFileSync(file, "utf8").match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1] ?? "";
+			const field = (key: string) => front.match(new RegExp(`^${key}:\\s*(.+)$`, "m"))?.[1]?.trim().replace(/^["']|["']$/g, "") ?? null;
+			const keywords = (field("keywords") ?? "").split(",").map(k => k.trim()).filter(Boolean);
+			guides.push({ name: field("name") ?? directory, kind: "skill", path: file, summary: field("description") ?? "", keywords });
+		} catch { /* unreadable skill metadata is skipped, never fatal */ }
+	}
+	return guides;
+}
+
+const FALLBACK_ROUTE = [
+	"A missing dedicated tool does not mean the operation is impossible.",
+	"If a tool is still expected, retry with fewer task words, a different wording, exact names, or scope=documentation.",
+	"Otherwise verify the needed Revit API members with search_api_docs, then use execute_csharp within the requested scope.",
+	"Report that something is not possible only after that check, naming what was checked.",
+];
+
 /** The bridge registry is the source of truth; discovery never duplicates its schemas. */
 export function createToolCatalog(pi: ExtensionAPI, discover: () => Promise<boolean>) {
 	const entries = new Map<string, BridgeToolDescriptor>();
+	const liveHashes = new Map<string, string>();
+	// Pi retains registrations when a bridge switch merely deactivates them.
+	// Keep this separate from the selected bridge's current discovery snapshot.
+	const registeredBridgeNames = new Set<string>();
+	const manifestByName = new Map(documentedTools.map(entry => [entry.name, entry]));
+	const natives = documentedTools.filter(entry => entry.source === "native");
+	const guides = loadGuidance();
+	const index = createDiscoveryIndex();
+	let bridgeVersion: string | null = null;
+	let observedAt: string | null = null;
 	function hideAdvanced(names: string[] = [...entries.keys()]) {
 		const advanced = new Set(names.filter(name => entries.get(name)?.tier === "advanced"));
 		pi.setActiveTools(pi.getActiveTools().filter(name => !advanced.has(name)));
 	}
+	function candidate(name: string, source: "native" | "bridge", live?: BridgeToolDescriptor): Candidate {
+		const packaged = packagedContracts.get(name);
+		return {
+			name, source,
+			description: live?.description ?? null,
+			summary: manifestByName.get(name)?.summary ?? null,
+			// Live v2 metadata wins; packaged metadata fills gaps from older bridges; unknown stays unknown.
+			keywords: live?.keywords ?? packaged?.keywords ?? [],
+			tier: live?.tier ?? packaged?.tier ?? (source === "native" ? "core" : null),
+			effects: live?.effects ?? (live?.write !== undefined ? (live.write ? ["model"] : []) : packaged?.effects ?? null),
+			verification: live?.verification ?? packaged?.verification ?? null,
+			limits: descriptorLimits(live?.limits) ?? packaged?.limits ?? null,
+			inputs: Object.keys(((live?.parameters ?? packaged?.parameters) as { properties?: object } | undefined)?.properties ?? {}),
+			documentKinds: live?.documentKinds ?? packaged?.document_kinds ?? null,
+		};
+	}
 
 	pi.registerTool({
 		name: "find_revit_tools",
 		label: "Find Revit Tools",
-		description: "Search the installed Revit tool catalogue and activate matching tools for this Pi session. Search words match tool names and descriptions. Supply exact names to activate known tools. With no query or names, list tools without activating them. Activation is additive and does not run any Revit operation. Read the returned schemas on the next model turn before calling a newly activated tool.",
-		promptSnippet: "Find and activate specialist Revit tools for links, schedules, relationships, inspection and editing.",
-		promptGuidelines: ["Use find_revit_tools to discover and activate specialist Revit tools before using execute_csharp for a task that may already have a dedicated tool."],
+		description: "Search PI-Revit tools, workflows and guidance by English task words, and activate matching tools. Tool vocabulary is English: translate a request written in another language into English search words first. The default available scope covers native utilities and the selected bridge's last-discovered tools; a query or names activates matches, while browsing only lists. scope=documentation searches packaged manuals without contacting Revit or activating tools, including when Revit is closed. Each tool result gives its declared limits with alternatives, its verification method, its manual path and whether that manual matches the selected bridge's contract. When nothing matches every word, the result states the remaining route: API search, then custom execution. Activation is additive and runs no Revit operation.",
+		promptSnippet: "Find PI-Revit capabilities, their limits and alternatives, and activate specialist tools.",
+		promptGuidelines: ["find_revit_tools: search with short English task words (translate the user's language first); use names for a known tool and scope=documentation while Revit is closed. Read only the returned manuals you need."],
 		parameters: Type.Object({
-			query: Type.Optional(Type.String({ description: "Search words, such as linked elements or schedules." })),
+			scope: Type.Optional(Type.Union([Type.Literal("available"), Type.Literal("documentation")], { description: "available (default): search registered native and last-discovered bridge tools. documentation: read-only packaged manual lookup; no bridge request or activation." })),
+			query: Type.Optional(Type.String({ description: "Short English task words, such as 'tag rooms' or 'count walls per level'; translate from the user's language first. Tools matching every word rank first, followed by strong partial matches; when nothing matches every word the remaining route is explained. Use separate queries for different capabilities." })),
 			names: Type.Optional(Type.Array(Type.String(), { maxItems: 20, description: "Exact tool names; takes precedence over query." })),
 			activate: Type.Optional(Type.Boolean({ description: "Activate returned matches. Default true for a query or exact names; false for browsing." })),
 			offset: Type.Optional(Type.Integer({ minimum: 0 })),
@@ -39,22 +107,45 @@ export function createToolCatalog(pi: ExtensionAPI, discover: () => Promise<bool
 		}),
 		executionMode: "sequential",
 		async execute(_id, args) {
-			if (!entries.size && !(await discover())) throw new Error("The Revit tool catalogue is unavailable. Start Revit with the bridge loaded and retry.");
+			const scope = args.scope ?? "available";
+			if (scope !== "available" && scope !== "documentation") throw new Error("scope must be available or documentation.");
+			if (scope === "documentation" && args.activate === true) throw new Error("documentation scope does not activate tools. Use available scope to activate registered tools.");
+			if (scope === "available" && observedAt === null) await discover();
+			const candidates = new Map<string, Candidate>();
+			if (scope === "documentation") for (const tool of documentedTools) candidates.set(tool.name, candidate(tool.name, tool.source));
+			for (const tool of natives) candidates.set(tool.name, candidate(tool.name, "native"));
+			for (const tool of entries.values()) candidates.set(tool.name, candidate(tool.name, "bridge", tool));
 			const names = args.names?.length ? [...new Set(args.names)] : undefined;
-			if (names?.some(name => !entries.has(name))) throw new Error(`Unknown Revit tool names: ${names.filter(name => !entries.has(name)).join(", ")}`);
-			const words = (args.query ?? "").trim().toLowerCase().split(/[\s_]+/).filter(Boolean);
-			const matches = [...entries.values()].filter(entry => names ? names.includes(entry.name)
-				: words.every(word => `${entry.name.replaceAll("_", " ")} ${entry.description ?? ""}`.toLowerCase().includes(word)))
-				.sort((a, b) => a.name.localeCompare(b.name));
+			if (names?.some(name => !candidates.has(name))) throw new Error(`Unknown Revit tool names or tools unavailable in this scope: ${names.filter(name => !candidates.has(name)).join(", ")}. Use scope=documentation to look up packaged manuals independently of bridge availability.`);
+			const query = (args.query ?? "").trim();
+			const toDocument = (c: Candidate) => ({ name: c.name, keywords: c.keywords, summary: c.summary, description: c.description, limits: c.limits?.map(limit => limit.what), inputs: c.inputs });
+			let mode: "names" | "browse" | "all" | "partial" | "none";
+			let matches: Candidate[];
+			if (names) { mode = "names"; matches = [...candidates.values()].filter(c => names.includes(c.name)).sort((a, b) => a.name.localeCompare(b.name)); }
+			else if (!query) { mode = "browse"; matches = [...candidates.values()].sort((a, b) => a.name.localeCompare(b.name)); }
+			else { const result = index.search([...candidates.values()], query, toDocument); mode = result.mode; matches = result.matches.map(m => m.item); }
 			const offset = Math.max(0, args.offset ?? 0);
-			const page = matches.slice(offset, offset + Math.max(1, Math.min(20, args.limit ?? 10)));
-			const activate = args.activate ?? Boolean(names || words.length);
+			const pageSize = Math.max(1, Math.min(20, args.limit ?? (mode === "partial" ? 5 : 10)));
+			const page = matches.slice(offset, offset + pageSize);
+			const activate = scope === "available" && (args.activate ?? (mode === "names" || mode === "all" || mode === "partial"));
 			if (activate && page.length) pi.setActiveTools([...new Set([...pi.getActiveTools(), ...page.map(entry => entry.name)])]);
 			const active = new Set(pi.getActiveTools());
+			const guidance = query && !names ? index.search(guides, query, g => ({ name: g.name, keywords: g.keywords, summary: g.summary })).matches.slice(0, 5)
+				.map(({ item }) => ({ name: item.name, kind: item.kind, path: item.path, summary: item.summary })) : [];
 			const result = {
+				scope, bridge_catalog_known: observedAt !== null, bridge_catalog_observed_at: observedAt, match: mode,
+				instructions: "Bridge availability is a discovery snapshot, not a fresh health check; registration, advertisement and activation are separate. Follow a tool's limits alternatives when it does not cover the request; an API alternative's lookup verifies all its members in one search_api_docs call. contract_match means the manual was generated from the selected bridge's exact input contract; otherwise trust the active schema. Read only relevant manual paths.",
 				total_count: matches.length, offset, returned_count: page.length,
 				next_offset: offset + page.length < matches.length ? offset + page.length : null,
-				tools: page.map(entry => ({ name: entry.name, description: entry.description, tier: entry.tier ?? "core", effects: entry.effects ?? (entry.write ? ["model"] : []), active: active.has(entry.name) })),
+				tools: page.map(entry => ({ name: entry.name, description: entry.description ?? entry.summary, source: entry.source,
+					tier: entry.tier, effects: entry.effects, verification: entry.verification, document_kinds: entry.documentKinds,
+					limits: entry.limits ? withApiLookups(entry.limits) : "unknown: no declared limits; if the tool does not cover the request, use the capability route",
+					registered: entry.source === "native" || registeredBridgeNames.has(entry.name),
+					advertised_by_selected_bridge: entry.source === "native" ? null : observedAt !== null ? entries.has(entry.name) : null,
+					active: active.has(entry.name),
+					documentation: resolveToolDocumentation(entry.name, { contractHash: entries.has(entry.name) ? liveHashes.get(entry.name) ?? null : null, bridgeVersion }) })),
+				guidance,
+				...(query && (mode === "none" || mode === "partial") ? { fallback: { reason: mode === "none" ? "No tool matched this query." : "No tool matched every word; these are partial matches.", route: FALLBACK_ROUTE } } : {}),
 			};
 			return { content: [{ type: "text" as const, text: JSON.stringify(result) }], details: result };
 		},
@@ -62,6 +153,14 @@ export function createToolCatalog(pi: ExtensionAPI, discover: () => Promise<bool
 	function reset() {
 		pi.setActiveTools(pi.getActiveTools().filter(name => !entries.has(name)));
 		entries.clear();
+		liveHashes.clear();
+		bridgeVersion = null;
+		observedAt = null;
 	}
-	return { add: (entry: BridgeToolDescriptor) => entries.set(entry.name, entry), hideAdvanced, reset };
+	return { add: (entry: BridgeToolDescriptor) => {
+		entries.set(entry.name, entry); liveHashes.set(entry.name, contractHash(entry)); registeredBridgeNames.add(entry.name); observedAt = new Date().toISOString();
+	},
+		// Called after successful /tools discovery, including a valid empty array.
+		setBridgeVersion: (value: string | null) => { bridgeVersion = value; observedAt = new Date().toISOString(); },
+		liveContracts: () => new Map(liveHashes), hideAdvanced, reset };
 }

package/extensions/pi-revit/tool-documentation.ts

@@ -0,0 +1,72 @@
+import { accessSync, constants, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import manifest from "../../skills/pi-revit/tool-manifest.json";
+import { version as packageVersion } from "../../package.json";
+import { packagedContracts } from "./contracts.js";
+
+export interface DocumentedTool { name: string; source: "native" | "bridge"; group: string; summary: string; }
+export interface GuidanceEntry { name: string; kind: string; path: string; summary: string; keywords?: string[] }
+// This index is documentation metadata only. Live registration remains authoritative
+// for input schemas, effects, tool availability and execution.
+export const documentedTools = manifest.tools as DocumentedTool[];
+export const packagedGuidance = manifest.guidance as GuidanceEntry[];
+export const documentationRevision = manifest.documentation_revision as string;
+const byName = new Map(documentedTools.map(tool => [tool.name, tool]));
+const defaultRoot = fileURLToPath(new URL("../../skills/pi-revit/references/tools/", import.meta.url));
+export const skillRoot = fileURLToPath(new URL("../../skills/pi-revit/", import.meta.url));
+export const manualDirectory = defaultRoot;
+
+/**
+ * Compatibility compares the executable-contract hash of the selected bridge's live
+ * descriptor with the hash the packaged manual was generated from:
+ *   package_local     native tool documented and shipped with this extension
+ *   contract_match    identical input schema and effects; the manual describes this contract
+ *   contract_changed  the live contract differs; trust the active schema over the manual
+ *   undocumented      the live tool has no packaged contract (newer bridge)
+ *   unknown           no live contract observed (bridge not discovered)
+ */
+export interface LiveEvidence { contractHash?: string | null; bridgeVersion?: string | null }
+
+/** Real-path containment keeps documentation lookup inside `root`; failures are nonfatal. */
+export function readablePathWithin(root: string, relative: string): string | null {
+	try {
+		const base = realpathSync(root), real = realpathSync(path.resolve(root, relative));
+		const inside = path.relative(base, real);
+		if (inside && inside !== ".." && !inside.startsWith(`..${path.sep}`) && !path.isAbsolute(inside) && statSync(real).isFile()) {
+			accessSync(real, constants.R_OK);
+			return real;
+		}
+	} catch {
+		// Missing, unreadable or concurrently replaced documentation must not
+		// prevent tool registration or discovery. Do not read manual bodies here.
+	}
+	return null;
+}
+
+export function createDocumentationResolver(root = defaultRoot) {
+	return (name: string, live: LiveEvidence = {}) => {
+		const entry = byName.get(name);
+		const contract = packagedContracts.get(name);
+		const liveHash = live.contractHash ?? null;
+		if (!entry) return {
+			key: name, status: "missing", path: null, packaged_contract_hash: null, live_contract_hash: liveHash,
+			compatibility: liveHash ? "undocumented" : "unknown",
+		};
+		const readablePath = readablePathWithin(root, `${entry.name}.md`);
+		const packagedHash = contract?.contract_hash ?? null;
+		return {
+			key: entry.name, status: readablePath ? "available" : "missing", path: readablePath,
+			revision: documentationRevision, package_version: packageVersion,
+			packaged_contract_hash: packagedHash,
+			live_contract_hash: entry.source === "bridge" ? liveHash : null,
+			observed_bridge_version: entry.source === "bridge" ? live.bridgeVersion ?? null : null,
+			compatibility: entry.source === "native" ? "package_local"
+				: !liveHash ? "unknown"
+				: !packagedHash ? "undocumented"
+				: liveHash === packagedHash ? "contract_match" : "contract_changed",
+		};
+	};
+}
+
+export const resolveToolDocumentation = createDocumentationResolver();

package/extensions/pi-revit/tool-schema.ts

@@ -0,0 +1,8 @@
+/** Compose the extension-only retry input after the bridge has added document targeting. */
+export function publicBridgeSchema(parameters: unknown) {
+	const schema = structuredClone(parameters ?? { type: "object", properties: {} }) as { properties?: Record<string, unknown> };
+	schema.properties = { ...schema.properties, _operation_id: {
+		type: "string", description: "Optional exact operation ID for retrying an identical earlier request. Reuses its result without repeating the action. Omit for a new operation.",
+	} };
+	return schema;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-revit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Native Pi connector for Autodesk Revit. Run npx.cmd -y pi-revit for the full Windows install.",
   "author": "Ahmad Altahlawi",
   "license": "MIT",
@@ -28,8 +28,12 @@
     "setup": "powershell -ExecutionPolicy Bypass -File scripts/setup-workspace.ps1",
     "uninstall:revit": "powershell -ExecutionPolicy Bypass -File scripts/uninstall.ps1",
     "test:search": "dotnet run --project tests/search-engine",
+    "test:extension": "node scripts/test-extension.mjs",
+    "test:docs": "node scripts/check-tool-documentation.mjs",
     "test:installer": "node --test tests/installer/*.test.cjs",
-    "test:sdk": "powershell -NoProfile -ExecutionPolicy Bypass -File tests/installer/sdk.test.ps1"
+    "test:sdk": "powershell -NoProfile -ExecutionPolicy Bypass -File tests/installer/sdk.test.ps1",
+    "generate:contracts": "node scripts/generate-contracts.mjs",
+    "test:corpus": "node tests/discovery/run-corpus.mjs"
   },
   "files": [
     "bin/",
@@ -38,6 +42,8 @@
     "scripts/",
     "src/",
     "workspace/",
+    "docs/",
+    "AGENTS.md",
     "README.md",
     "CHANGELOG.md"
   ],

package/scripts/build.ps1

@@ -17,15 +17,15 @@ param(
 )
 
 $ErrorActionPreference = 'Stop'
-$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
-
-. (Join-Path $PSScriptRoot 'check-sdk.ps1')
-$frameworks = if ($TargetFramework) { $TargetFramework -split ';' } else {
-    ([xml](Get-Content $project -Raw)).Project.PropertyGroup.TargetFrameworks | Where-Object { $_ } | ForEach-Object { $_ -split ';' }
-}
-if (-not (Test-PiRevitSdk -TargetFrameworks $frameworks)) { exit 1 }
-
-$buildArgs = @('build', $project, '-c', $Configuration)
+$project = Join-Path $PSScriptRoot '..\src\Revit\RevitBridge.csproj'
+
+. (Join-Path $PSScriptRoot 'check-sdk.ps1')
+$frameworks = if ($TargetFramework) { $TargetFramework -split ';' } else {
+    ([xml](Get-Content $project -Raw)).Project.PropertyGroup.TargetFrameworks | Where-Object { $_ } | ForEach-Object { $_ -split ';' }
+}
+if (-not (Test-PiRevitSdk -TargetFrameworks $frameworks)) { exit 1 }
+
+$buildArgs = @('build', $project, '-c', $Configuration)
 
 # Stamp the package version into the assembly so the bridge can report which release
 # the deployed add-in came from; the pi extension compares it against its own package