pi-revit 0.3.1 → 0.5.0

package/scripts/lib/platform.mjs

@@ -0,0 +1,226 @@
+// Shared offline platform helpers for the contract generator and the documentation
+// checker. Nothing here contacts Revit, the network or a live model: bridge metadata
+// comes from the real C# registry compiled with stubbed tool bodies, and the Pi
+// extension is registered against an isolated fake bridge.
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+export const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+export const skillRoot = path.join(root, 'skills', 'pi-revit');
+export const manualRoot = path.join(skillRoot, 'references', 'tools');
+export const snapshotPath = path.join(skillRoot, 'contracts.generated.json');
+export const manifestPath = path.join(skillRoot, 'tool-manifest.json');
+export const toolIndexPath = path.join(skillRoot, 'references', 'tool-index.md');
+
+export function resolvePiDependencies() {
+  const candidates = [process.env.PI_CODING_AGENT_PATH,
+    path.join(path.dirname(process.execPath), 'node_modules', '@earendil-works', 'pi-coding-agent')].filter(Boolean);
+  for (const candidate of candidates) {
+    const require = createRequire(path.join(path.resolve(candidate), 'package.json'));
+    try { require.resolve('jiti'); require.resolve('typebox/value'); return require; } catch {}
+  }
+  throw new Error('Set PI_CODING_AGENT_PATH to an existing @earendil-works/pi-coding-agent directory containing jiti and typebox. These checks never install dependencies.');
+}
+
+export function createLoader(piRequire) {
+  const { createJiti } = piRequire('jiti');
+  return createJiti(import.meta.url, { alias: { typebox: piRequire.resolve('typebox') }, moduleCache: false });
+}
+
+/** Real ToolRegistry.DescribeAll() output, via the Roslyn schema extractor. */
+export async function extractBridgeDescriptors() {
+  const scratch = await mkdtemp(path.join(os.tmpdir(), 'pi-revit-contracts-'));
+  try {
+    const output = path.join(scratch, 'bridge.json');
+    const run = spawnSync('dotnet', ['run', '--project', path.join(root, 'tests', 'tool-documentation', 'schema-extractor.csproj'), '--', root, output],
+      { cwd: root, encoding: 'utf8', maxBuffer: 8 * 1024 * 1024, env: { ...process.env, DOTNET_CLI_TELEMETRY_OPTOUT: '1', DOTNET_SKIP_FIRST_TIME_EXPERIENCE: '1' } });
+    if (run.error || run.status !== 0)
+      throw new Error(`Bridge schema extraction failed (installed .NET SDK 8+ required).\n${run.error?.message ?? ''}\n${run.stdout}\n${run.stderr}`);
+    return JSON.parse(await readFile(output, 'utf8'));
+  } finally { await rm(scratch, { recursive: true, force: true }); }
+}
+
+/**
+ * Register the real extension against an in-memory bridge that serves `descriptors`.
+ * Returns the registrations and event handlers. Every non-metadata route and all
+ * real network access are rejected, and no registered execute() is invoked.
+ */
+export async function registerExtension(loader, descriptors, addinVersion) {
+  const scratch = await mkdtemp(path.join(os.tmpdir(), 'pi-revit-register-'));
+  const original = { fetch: globalThis.fetch, appdata: process.env.APPDATA, setInterval: globalThis.setInterval };
+  process.env.APPDATA = scratch;
+  await mkdir(path.join(scratch, 'RevitBridge'));
+  await writeFile(path.join(scratch, 'RevitBridge', 'bridge.json'), JSON.stringify({ baseUrl: 'http://platform-fixture.invalid', token: 'offline-fixture' }));
+  const routes = [];
+  globalThis.fetch = async (input, init) => {
+    const url = new URL(typeof input === 'string' || input instanceof URL ? input : input.url);
+    if (url.origin !== 'http://platform-fixture.invalid') throw new Error('real network access is forbidden');
+    if ((init?.method ?? 'GET') !== 'GET' || !['/ping', '/tools'].includes(url.pathname)) throw new Error(`tool execution is forbidden: ${url.pathname}`);
+    routes.push(url.pathname);
+    return new Response(JSON.stringify(url.pathname === '/tools' ? { tools: descriptors } : { ok: true, addinVersion }));
+  };
+  globalThis.setInterval = () => { throw new Error('Background polling is forbidden in platform fixtures'); };
+  const registered = new Map(), events = new Map();
+  let active = [];
+  const pi = {
+    registerTool(tool) { if (registered.has(tool.name)) throw new Error(`duplicate registered tool ${tool.name}`); registered.set(tool.name, tool); active = [...active, tool.name]; },
+    on(name, handler) { events.set(name, handler); },
+    getActiveTools() { return [...active]; },
+    setActiveTools(names) { active = [...names]; },
+    sendMessage() { throw new Error('Messages are forbidden in platform fixtures'); },
+  };
+  const restore = async () => {
+    await events.get('session_shutdown')?.({}, {});
+    globalThis.fetch = original.fetch; globalThis.setInterval = original.setInterval;
+    if (original.appdata === undefined) delete process.env.APPDATA; else process.env.APPDATA = original.appdata;
+    await rm(scratch, { recursive: true, force: true });
+  };
+  try {
+    const { default: connector } = await loader.import(path.join(root, 'extensions', 'pi-revit', 'index.ts'));
+    await connector(pi);
+  } catch (error) { await restore(); throw error; }
+  return { pi, registered, events, routes, activeTools: () => [...active], restore };
+}
+
+/** Human-readable type, requiredness, default and allowed values of one JSON schema property. */
+function describeProperty(schema) {
+  const values = [];
+  let type = schema?.type;
+  if (Array.isArray(schema?.enum)) values.push(...schema.enum);
+  for (const variant of schema?.anyOf ?? schema?.oneOf ?? []) {
+    if (variant.const !== undefined) { values.push(variant.const); type ??= typeof variant.const; }
+    else if (variant.type) type = type ? `${type} | ${variant.type}` : variant.type;
+  }
+  if (schema?.const !== undefined) values.push(schema.const);
+  if (type === 'array') {
+    const items = schema.items ?? {};
+    const itemValues = Array.isArray(items.enum) ? items.enum : (items.anyOf ?? []).filter(v => v.const !== undefined).map(v => v.const);
+    values.push(...itemValues);
+    type = `array of ${items.type ?? (itemValues.length ? typeof itemValues[0] : 'value')}`;
+  }
+  if (Array.isArray(type)) type = type.join(' | ');
+  return { type: type ?? 'value', values, default: schema?.default };
+}
+
+const VERIFICATION_TEXT = {
+  reread: 'query the changed state again with a read tool',
+  capture: 'capture the visible result and inspect the image',
+  inspect_output: 'open and inspect the produced file',
+  none: 'no durable outcome to check; report what was done',
+};
+const cell = text => String(text).replace(/\|/g, '\\|').replace(/\r?\n/g, ' ');
+
+export function alternativeText(limit) {
+  const ref = limit.alternative.ref ? cell(limit.alternative.ref) : '';
+  switch (limit.alternative.kind) {
+    case 'tool': return `Tool: ${ref}`;
+    case 'api': return `Revit API: ${ref}. ${limit.lookup ? `Check all its members in one call: \`search_api_docs\` with query \`${cell(limit.lookup.query)}\`` : 'Check with `search_api_docs`'}, then use \`execute_csharp\` within the requested scope.`;
+    case 'user': return `User action: ${ref}`;
+    case 'revit_unsupported': return `Not offered by the Revit API (${ref}). Report this with the evidence checked.`;
+    default: return ref;
+  }
+}
+
+export const CONTRACT_START = '<!-- generated:contract:start (npm run generate:contracts; do not edit this block) -->';
+export const CONTRACT_END = '<!-- generated:contract:end -->';
+
+export function renderManualBlock(tool) {
+  const lines = [CONTRACT_START, '## Contract (generated)', ''];
+  const tier = tool.source === 'native' ? 'Pi extension utility, always active'
+    : tool.tier === 'advanced' ? 'bridge tool, advanced tier: activate it with `find_revit_tools`' : 'bridge tool, core tier: active by default';
+  lines.push(`- **Source:** ${tier}.`);
+  lines.push(`- **Writes model:** ${tool.write ? 'yes' : 'no'}. **Effects:** ${tool.effects.length ? tool.effects.join(', ') : 'none'}. **Requires an open document:** ${tool.requires_document ? 'yes' : 'no'}.`);
+  if (tool.document_kinds?.length && tool.requires_document)
+    lines.push(`- **Works in:** ${tool.document_kinds.length > 1 ? 'project and family documents' : `${tool.document_kinds[0]} documents only; the bridge refuses other documents before running, with the route to use instead`}.`);
+  if (tool.verification) lines.push(`- **Verify the outcome:** \`${tool.verification}\`: ${VERIFICATION_TEXT[tool.verification]}.`);
+  lines.push(`- **Contract hash:** \`${tool.contract_hash}\`. \`find_revit_tools\` compares it with the selected bridge's live contract.`);
+  lines.push('', '| Input | Type | Required | Default | Allowed values |', '| --- | --- | --- | --- | --- |');
+  const schema = tool.parameters ?? {};
+  const required = new Set(schema.required ?? []);
+  const properties = Object.entries(schema.properties ?? {});
+  if (!properties.length) lines.push('| _(none)_ | | | | |');
+  for (const [name, property] of properties) {
+    const d = describeProperty(property);
+    lines.push(`| \`${name}\` | ${cell(d.type)} | ${required.has(name) ? 'yes' : 'no'} | ${d.default === undefined ? '' : `\`${cell(JSON.stringify(d.default))}\``} | ${d.values.map(v => `\`${cell(v)}\``).join(', ')} |`);
+  }
+  if (tool.source === 'bridge') lines.push('', 'Bridge calls also accept `_operation_id`, only to retry an identical earlier request (see [operation recovery](../operation-recovery.md)).');
+  if (tool.limits.length) {
+    lines.push('', '| Not covered by this tool | Use instead |', '| --- | --- |');
+    for (const limit of tool.limits) lines.push(`| ${cell(limit.what)} | ${alternativeText(limit)} |`);
+  }
+  lines.push(CONTRACT_END);
+  return lines.join('\n');
+}
+
+/** Replace the generated block, or insert it before the first "## Inputs" heading (else the second H2). */
+export function applyManualBlock(markdown, block) {
+  const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+  const body = block.replace(/\n/g, eol);
+  const start = markdown.indexOf(CONTRACT_START), end = markdown.indexOf(CONTRACT_END);
+  if (start >= 0 && end > start) return markdown.slice(0, start) + body + markdown.slice(end + CONTRACT_END.length);
+  const headings = [...markdown.matchAll(/^## .*$/gm)];
+  const anchor = headings.find(h => /^## Inputs/.test(h[0])) ?? headings[1];
+  if (!anchor) return markdown.trimEnd() + eol + eol + body + eol;
+  return markdown.slice(0, anchor.index) + body + eol + eol + markdown.slice(anchor.index);
+}
+
+export const INDEX_START = '<!-- generated:tool-index:start (npm run generate:contracts; do not edit this block) -->';
+export const INDEX_END = '<!-- generated:tool-index:end -->';
+
+export function renderToolIndex(manifest, contracts) {
+  const byName = new Map(contracts.map(tool => [tool.name, tool]));
+  const lines = [INDEX_START];
+  for (const group of manifest.groups) {
+    lines.push('', `## ${group.title}`, '', '| Manual | Use | Tier | Verify |', '| --- | --- | --- | --- |');
+    for (const tool of manifest.tools.filter(entry => entry.group === group.id)) {
+      const contract = byName.get(tool.name);
+      const tier = tool.source === 'native' ? 'native' : contract?.tier ?? '';
+      lines.push(`| [${tool.name}](tools/${tool.name}.md) | ${cell(tool.summary)} | ${tier} | ${contract?.verification ?? ''} |`);
+    }
+  }
+  lines.push('', '## Workflows and shared guidance', '', '| Guide | Kind | Use |', '| --- | --- | --- |');
+  for (const guide of manifest.guidance) lines.push(`| [${guide.name}](${guide.path.replace(/^references\//, '')}) | ${guide.kind} | ${cell(guide.summary)} |`);
+  lines.push(INDEX_END);
+  return lines.join('\n');
+}
+
+export function applyIndexBlock(markdown, block) {
+  const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+  const body = block.replace(/\n/g, eol);
+  const start = markdown.indexOf(INDEX_START), end = markdown.indexOf(INDEX_END);
+  if (start < 0 || end < start) throw new Error(`tool-index.md needs ${INDEX_START} ... ${INDEX_END} markers`);
+  return markdown.slice(0, start) + body + markdown.slice(end + INDEX_END.length);
+}
+
+/**
+ * Score the discovery corpus against packaged documentation (no bridge needed).
+ * An entry passes when its expected tool or guidance appears in the top_n results,
+ * or, for expect_fallback, when the response carries the capability route.
+ */
+export async function evaluateCorpus(loader, corpus, addinVersion) {
+  const fixture = await registerExtension(loader, [], addinVersion);
+  try {
+    const find = fixture.registered.get('find_revit_tools');
+    const results = [];
+    for (const entry of corpus.entries) {
+      const response = (await find.execute('corpus', { scope: 'documentation', query: entry.q, limit: corpus.top_n })).details;
+      const tools = response.tools.map(tool => tool.name), guides = response.guidance.map(guide => guide.name);
+      const pass = entry.expect_fallback ? Boolean(response.fallback) && response.match === 'none'
+        : entry.expect_guidance ? guides.slice(0, corpus.top_n).includes(entry.expect_guidance)
+        : tools.slice(0, corpus.top_n).includes(entry.expect);
+      results.push({ ...entry, pass, match: response.match, got: entry.expect_guidance ? guides : tools });
+    }
+    return results;
+  } finally { await fixture.restore(); }
+}
+
+/** Candidate RevitAPI.xml files for optional API-reference verification. */
+export function revitApiXmlPaths() {
+  const roots = [process.env.REVIT_API_PATH, 'C:\\Program Files\\Autodesk\\Revit 2025', 'C:\\Program Files\\Autodesk\\Revit 2026', 'C:\\Program Files\\Autodesk\\Revit 2027'].filter(Boolean);
+  return roots.map(directory => path.join(directory, 'RevitAPI.xml')).filter(file => existsSync(file));
+}

package/scripts/test-extension.mjs

@@ -0,0 +1,15 @@
+import { readdirSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+// Run sequentially: fixtures replace fetch, timers and discovery paths in-process.
+// Each module has a separate process and uses Node's test API directly.
+const directory = new URL('../tests/result-contract/', import.meta.url);
+for (const file of readdirSync(directory).filter(name => name.endsWith('.test.mjs')).sort()) {
+  process.stdout.write(`\n${file}\n`);
+  const result = spawnSync(process.execPath, [fileURLToPath(new URL(file, directory))], {
+    stdio: 'inherit', env: process.env,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) process.exit(result.status ?? 1);
+}

package/skills/pi-revit/SKILL.md

@@ -1,63 +1,39 @@
----
-name: pi-revit
-description: Work with the open Autodesk Revit model through the Revit bridge tools (ping, get_model_overview, get_elements, get_element_details, get_element_types, manage_selection, open_view, set_parameters, search_api_docs, execute_csharp, capture_view, export_documents, get_model_health) and retrieve saved results with read_revit_result. Use when the user asks about the Revit project, its elements, parameters, selection, or wants to change, script, capture, or export the model.
----
-
-# Revit
-
-Work with the live Revit model. The bridge targets Revit 2025, 2026, and 2027; the 0.3.0 changes were tested live on Revit 2025. Bridge document tools require Revit running with a project open; `ping` and `search_api_docs` work without a document. `read_revit_result` reads an already saved result locally without contacting Revit.
-
-## Tool selection
-
-| Task | Tool |
-|------|------|
-| Bridge alive? Which Revit version? | `ping` |
-| Orientation: project info, units, levels, grids, category counts | `get_model_overview` |
-| List or count elements of ANY category (walls, doors, rooms, sheets, views, ...) | `get_elements` |
-| Read parameter VALUES, location, bounding box, materials of specific elements | `get_element_details` |
-| List element types / family symbols; "used vs merely loaded" | `get_element_types` |
-| Read or change the user's selection; zoom; temporary isolate | `manage_selection` |
-| Put a view or sheet on the user's screen (activate it) | `open_view` |
-| Write parameter values; rename anything (levels, views, sheets, types) | `set_parameters` |
-| Look up Revit API classes/members/signatures | `search_api_docs` |
-| Everything else (create, delete, move, views, sheets, tagging, ...) | `execute_csharp` |
-| PNG snapshot of a view (visual QA) | `capture_view` (advanced) |
-| PDF/DWG/PNG/IFC file export | `export_documents` (advanced) |
-| Warnings / model quality audit | `get_model_health` (advanced) |
-| Continue a saved large tool result | `read_revit_result` (local, no Revit call) |
-
-Workflow guidance:
-
-- Call `get_model_overview` for the intended open model before changing it. Copy `project.documentId` unchanged into `expected_document_id` for `set_parameters`, `execute_csharp`, `export_documents`, `open_view`, and selection/zoom changes. `manage_selection` also requires it whenever `isolate_in_view: true`, even with action `get`. Pure reads may omit it; a supplied ID is always checked. A matching legacy `expected_document` title alone is insufficient.
-- The ID belongs to one open document in one bridge session. Refresh it after closing/reopening the model or restarting Revit. If the guard rejects a call, activate the intended model and obtain its overview again; do not blindly substitute the currently active model's ID.
-- `get_elements` is the listing/counting primitive (`count_only: true` for bare counts). It returns identity fields only (id, name, category, typeName, levelId); read parameter values with `get_element_details`. Prefer a `category` or `of_class` scope when filtering by a parameter's display name.
-- The selection pipeline is `get_elements` -> ids -> `manage_selection` (action `set`); there is no inline filter on selection.
-- `set_parameters` handles bulk parameter writes and renames (the `Name` parameter covers levels, views, sheets, types). It can commit a partially successful batch: inspect every failed update, `commitWarnings`, and the reported transaction outcome before describing what changed.
-- Parameter display names are LOCALIZED: in a non-English Revit UI, `Mark`, `Comments`, and every other display name appear under their translated names. When a display-name lookup or `parameter_names` filter finds nothing, or the document may be non-English, use the language-independent `BuiltInParameter` enum name instead (e.g. `ALL_MODEL_MARK` for Mark, `ALL_MODEL_INSTANCE_COMMENTS` for Comments) — `set_parameters`, `get_element_details.parameter_names`, and `get_elements` filter rules all accept them, and `get_element_details` reports each parameter's `builtInParameter` name for discovery.
-- Before writing `execute_csharp` code, verify unfamiliar classes/members with `search_api_docs` (works with no document open; first query builds the index and takes a few seconds). The top match carries its remarks, parameter docs, and returns inline, and every public API enum value is searchable — trust the result over guessing or web search; narrow the query to promote a different match into the top slot.
-- `export_documents` defaults to `Documents\pi-revit\Models\<model title>--<identity hash>\exports`. Use its returned `outputDir` and file paths as authoritative; do not construct a destination from the title or opaque `project.documentId`. Saved paths and cloud/server identities determine the folder; unsaved/unavailable identities use a session fallback. Save As can select a new folder. Pass `output_dir` when the user requests a different destination. Existing title-only folders remain untouched.
-- Large tool payloads return a `result_id`, `file_path`, and continuation instructions. Call `read_revit_result` with that ID and `offset: 0`, then follow `next_offset` until `has_more` is false. Concatenate `text` fragments in order; each fragment is not a standalone JSON result. Offsets count UTF-16 code units. IDs last for the current extension instance; after reload, use the returned absolute file path with `read` while the file exists. Retrieval does not replace the original query's pagination or remove its limits.
-
-## execute_csharp playbook
-
-- Globals: `doc` (Document), `uidoc` (UIDocument), `uiapp` (UIApplication), and `Dump(value)` to record intermediates into the result's `dumps[]`.
-- The script runs inside one backend-owned transaction. Do not start another transaction on `doc` (sub-transactions are allowed). The tool checks commit status and attempts rollback on script failure; read its actual outcome instead of assuming rollback succeeded. Result projection can fail after a successful commit and report `returnValueError`. Filesystem and UI effects are separate from model rollback.
-- Scripts must be fully synchronous: `await`/`async` is rejected at compile time; never block on `Task.Result`/`.Wait()`.
-- Return primitives, strings, or anonymous objects/lists; raw Revit API objects are projected to compact shapes (Element -> `{id,name,category,typeName,levelId}`, ElementId -> number, XYZ -> `{x,y,z}`).
-- Lengths are internal units (decimal feet) — convert with `UnitUtils.ConvertToInternalUnits`/`ConvertFromInternalUnits`.
-- Common pitfalls: call `FamilySymbol.Activate()` before `NewFamilyInstance`; use collector-level filtering (`OfCategory`/`OfClass`/`WhereElementIsNotElementType`) and bounded loops. The budget is 120s and Revit cannot be interrupted mid-script. The dialog guard attempts dismissive responses and reports `suppressedDialogs`; it cannot guarantee handling every modal dialog.
-- `capture_view` returns a `filePath` to a temp PNG, never image data — open it with the read tool to actually see it.
-
-## Failure modes
-
-- **Identity rejected**: no tool action was performed. Verify the intended active model, refresh `project.documentId`, and pass `expected_document_id` unchanged.
-- **Partial UI/export effects**: selection or zoom can already have changed when isolation fails. Export errors can leave incomplete files, and IFC commit warnings are returned. Inspect the reported effects and output paths; model rollback does not remove files or reverse earlier UI actions.
-- **Large-result save failed**: Revit may already have completed the operation. Verify its effects before retrying a write.
-- **Bridge not reachable** ("Revit bridge is not available" / "Could not reach the Revit bridge"): Revit is not running or the add-in did not load. Ask the user to start Revit, then retry `ping`.
-- **HTTP 409 / "No active Revit document is open."** (`hasActiveDocument: false`): Revit is running but no project is open. Ask the user to open a project, then retry. This fails immediately; do not wait or retry blindly.
-- **Timeout** ("Revit did not answer within Ns", 30s default / 120s for execute_csharp, capture_view, export_documents): Revit is busy or showing a modal dialog. An already-started tool still runs to completion in Revit — verify model state (e.g. `get_elements`) before re-issuing a write.
-- **Cancelled**: same caveat — the bridge cannot abort queued or running work, so verify model state before retrying a write tool.
-
-## Upgrading from 0.2.x
-
-Version 0.3.0 requires exact document IDs for the operations above. Update the Pi package and deploy the matching add-in with Revit closed, then restart Revit and start a fresh Pi session so the new schemas and instructions are loaded. Obtain a fresh overview before writes. `ping` reports an installed/loaded version mismatch. Setup preserves existing workspace `AGENTS.md`; merge these targeting, result-reading, and folder rules into an older workspace's instructions when needed.
+---
+name: pi-revit
+description: Inspect, edit, document, script, and export Autodesk Revit models using PI-Revit. Use for questions about the connected project, selecting Revit capabilities, or carrying out model and drawing workflows. Routes to focused tool manuals and execution guidance.
+---
+
+# PI-Revit
+
+Choose the path that matches the user's request. This skill routes tasks; the always-present PI-Revit protocol states the capability, completion, evidence, identity and language rules for every tool. Executable schemas and bridge checks remain authoritative. Guidance does not grant permission for additional edits, exports, model saving, or deployment.
+
+## Choose the task path
+
+- **Explain or plan:** answer from relevant Revit knowledge and tool manuals. A general Revit explanation does not require an open model. `find_revit_tools` with `scope: "documentation"` can find packaged manuals without connecting to Revit. Connect only when the answer depends on the actual project. Do not turn a question into a modification.
+- **Inspect:** select the intended session and read the requested model scope. Use `get_elements` for listings or `count_only: true` for a simple count. An audit does not authorize repairs, selection changes, or exports.
+- **Modify or produce a deliverable:** establish model identity and scope, inspect the existing state, read the relevant manuals, then execute and verify requested work. Use preview and atomic behavior where they help validate a proposed change. A successful transaction does not save the Revit file.
+
+## Essential rules
+
+1. Before working against a model, read [execution rules](references/execution-rules.md). For several Revit sessions or a stale selection, use [manage_revit_instances](references/tools/manage_revit_instances.md). Select the intended model; do not substitute whichever document happens to be active.
+2. Obtain `project.documentId` from `get_model_overview` before edits and pass it unchanged as `expected_document_id`, including previews. The same guard applies to export, view activation, selection changes, and every `manage_sheet_placements` action. Refresh after reopening the document, restarting Revit, or changing instances. A title is insufficient.
+3. Discover dedicated capabilities with [find_revit_tools](references/tools/find_revit_tools.md) before custom code; search with English task words. Specialist tools begin inactive. Registration, activation, and reading a manual are separate actions: read the relevant returned manual, and inspect the activated public schema before calling the tool. Use the [tool index](references/tool-index.md) for all public tools and direct manual links; do not load every manual.
+4. Each tool declares what it does not cover and what to use instead. When a tool or manual does not cover the request, follow that alternative. When nothing dedicated fits, verify the API members with [search_api_docs](references/tools/search_api_docs.md) and use [execute_csharp](references/tools/execute_csharp.md) within the requested scope. Report an operation as not possible only after that check, naming what you checked and whether the gap is a missing tool, the Revit API, or a user decision. <!-- inv:capability-claims-checked -->
+5. Discover IDs and parameter identities from the model. Display names are localized; prefer discovered `BuiltInParameter` names or shared GUIDs where supported. Respect each tool's units and coordinate frame; raw measurements commonly use internal feet.
+6. Check `committed`, `succeeded`, `proposed`, `failed`, warnings, and commit-validation status. Rolled-back proposals are not retained changes. Discard preview-created or replacement IDs after rollback; reuse only committed IDs.
+7. For large responses, use [read_revit_result](references/tools/read_revit_result.md) and follow every continuation needed for the requested result. Saved-result fragments and the original tool's query pages are separate layers.
+8. For a timeout, cancellation, uncertain outcome, or incomplete result, read [operation recovery](references/operation-recovery.md) before repeating an action. Check the original receipt. Only an identical request with its original `_operation_id` is a deduplicated retry.
+9. For visible changes or graphical deliverables, read [visual verification](references/visual-verification.md), capture the actual result, and inspect the image. Correct only what breaks the request; once its requirements are verified, stop and report, offering further improvements as suggestions. Report blocked verification honestly. Evidence capture does not authorize saving the model.
+
+## Read the detail needed for this task
+
+| Need | Read |
+| --- | --- |
+| Choose among tools; inspect input/output and effects | [Tool index and individual manuals](references/tool-index.md) |
+| Room plans/sections, tags, schedules, sheets | [Room documentation workflow](references/room-documentation.md) |
+| Multi-step model audit, data review, and requested exports | [Model audit and export workflow](references/model-audit-export.md) |
+| No dedicated tool covers the operation, or an unfamiliar Revit API member | The tool's declared alternative; else [search_api_docs](references/tools/search_api_docs.md), then [execute_csharp](references/tools/execute_csharp.md) |
+| Save, inspect, or run a reusable script | [manage_revit_scripts](references/tools/manage_revit_scripts.md) |
+| Bridge unavailable or version mismatch | [ping](references/tools/ping.md) and [operation recovery](references/operation-recovery.md) |
+
+The bridge targets Revit 2025–2027. Manuals describe this package's contract; check the selected bridge's schema and version. `ping` and API search need no open document. Saved results and local script-library inspection work without Revit. General modeling standards and the future Revit subject library are separate from these tool contracts.