pi-revit 0.4.0 → 0.5.1

package/AGENTS.md

@@ -0,0 +1,167 @@
+# Contributing to PI-Revit
+
+This file guides agents changing **this source repository**. Start with
+[the architecture](docs/architecture.md) for resource ownership and discovery,
+and [evaluation](docs/evaluation.md) for evidence and validation limits.
+Follow the user's requested scope; an investigation does not authorize implementation,
+and a source change does not by itself authorize installation, deployment, publication,
+or changes to a live Revit model.
+
+## Two different AGENTS files
+
+- **This file:** contributor instructions, repository structure, and checks.
+- **[workspace/AGENTS.md](workspace/AGENTS.md):** template copied into the user's
+  Revit working folder by setup. It owns model output locations and local session
+  conventions. It is not the contributor guide or the complete tool manual.
+
+Pi's global/project instruction scope is separate from resource type. A skill is
+a task-specific entry with optional references; a tool is executable behavior;
+a package distributes them. Do not turn every manual into a separate skill or
+copy all operational guidance into workspace instructions.
+
+## Where a change belongs
+
+Fix a class of problem where every present and future resource inherits the fix: in a
+shared mechanism, in declared metadata, or in the platform section. A sentence in one
+manual is never the only fix. Each rule has one owner.
+
+| Change | Primary owner | Update alongside it |
+| --- | --- | --- |
+| Revit operation, inputs, outputs, effects | `src/Revit/Tools/<Tool>.cs` | `ToolRegistry.cs`, manual, focused C# tests |
+| A tool's contract: keywords, limits with alternatives, verification | the tool's `Keywords`/`Limits`/`Verification` (bridge) or `extensions/pi-revit/contracts.ts` (native) | `npm run generate:contracts`; discovery corpus entries |
+| Parameter lookup by name, BuiltInParameter or GUID | `src/Revit/Tools/ParameterResolver.cs`, the only resolver | element-query tests; never `LookupParameter` in a tool |
+| Special or system-owned objects (revision schedules, templates, groups, design options) | `src/Revit/Tools/ElementTraits.cs` | element-traits tests; flag or count, never mix silently |
+| State an object inherits when created from an existing one (duplicate, copy, mirror, retype) | `src/Revit/Tools/InheritedState.cs` (reading) and `InheritedState.Summary.cs` (pure summary) | derived-state tests; the gate requires it wherever a tool duplicates, copies or retypes |
+| Assigning a name or sheet number; name collisions | `src/Revit/Tools/ElementNames.cs`, the only place a tool assigns them | the gate rejects any other `Name`/`SheetNumber` assignment |
+| What a call changed in the model (`model_changes`) | `src/Revit/Tools/ModelChanges.cs` and `ChangeSet.cs`, attached once by the dispatcher in `BridgeServer.cs` | derived-state tests; never report changes per tool |
+| Shared document identity/transaction rules | `src/Revit/Tools/DocumentGuard.cs`, `ModelEditBatch.cs`, related helpers | guard/transaction tests; execution and recovery references |
+| HTTP, queueing, receipt retention | `src/Revit/BridgeServer.cs`, `CommandQueue.cs`, `OperationStore.cs` | receipt/result tests and recovery reference |
+| Cross-cutting protocol (capability, scope/completion, evidence, identity, language) | `extensions/pi-revit/platform-prompt.ts`, stated once for all tools | platform tests; never repeat it per tool or per manual |
+| Completion/loop steering | `extensions/pi-revit/completion-monitor.ts` (metadata-driven) | platform tests; the `modify-*` evaluation scenarios |
+| Objects that predate the request; per-request created-object ledger | `extensions/pi-revit/scope-monitor.ts` (reads `model_changes` and `name_collision`) | scope-monitor tests; the `modify-name-collision` scenario |
+| Pi registration, result presentation, retries | `extensions/pi-revit/index.ts`, `tool-schema.ts` | extension tests and affected manuals |
+| Instance routing | `extensions/pi-revit/instance-router.ts` | instance-router tests and instance manual |
+| Discovery matching and ranking | `extensions/pi-revit/discovery.ts`, `tool-catalog.ts` | `tests/discovery/corpus.json` (recall gate) and catalogue tests |
+| Documentation index, groups, guidance resources | `skills/pi-revit/tool-manifest.json` | regenerate; corpus entry for each new workflow |
+| A "never" or "must" rule | `docs/invariants.json` plus an `<!-- inv:<id> -->` tag on the sentence | a code test, or, only for agent intent, an `agent-eval` scenario |
+| Agent behavior worth measuring | `tests/agent-eval/scenarios.json` | invariants it protects; live runs on a disposable fixture |
+| Reusable script library | `extensions/pi-revit/script-library.ts` | script-library tests and manual |
+| Cross-tool operating rule | `skills/pi-revit/references/` | short entry link only if needed on every task |
+| One public tool's usage | hand-written part of `skills/pi-revit/references/tools/<public_name>.md` | executable examples; the Contract block is generated |
+| A multi-tool task recipe | workflow reference under `skills/pi-revit/references/` | manifest guidance entry, corpus entry and task-based evaluation |
+| Revit subject knowledge | a scoped future `skills/revit-<subject>/SKILL.md` and references | official Autodesk sources and version; discovered automatically; add corpus and routing evaluation |
+| API signatures | existing `search_api_docs` implementation and live version's documentation | search tests; do not maintain a parallel copied API catalogue |
+| Installation or output-folder convention | `scripts/`, `bin/pi-revit.js`, `workspace/AGENTS.md` | README and installer tests |
+
+Generated artifacts are never edited by hand: `skills/pi-revit/contracts.generated.json`,
+each manual's `Contract (generated)` block and the tool-index tables. Change the code or
+manifest and run `npm run generate:contracts`; `npm run test:docs` fails when they are stale.
+
+Tool vocabulary is English. There are no per-language rules: the model translates a
+request into English search words, replies in the user's language, and reads localized
+Revit names from results. Prefer exact identities (BuiltInParameter, GUID) over display names.
+
+The future subject library is an extension point, not an already implemented
+library. Keep one package until independent ownership or releases justify another.
+Names in the table are repository-relative paths, not files to create indiscriminately.
+
+## Adding or changing a public tool
+
+1. Decide whether it belongs in the Revit bridge or the Pi extension. A bridge
+   `ITool` implements metadata/schema and execution, and is registered in
+   `src/Revit/ToolRegistry.cs`. Set `Write`, `Effects`, `RequiresDocument` and tier to
+   match real behavior. `write: false` does not mean no UI/file effects. Tools with
+   `RequiresDocument: false` run off the API thread with no Revit context; do not
+   access the Revit API there.
+2. Declare the contract. `Keywords` holds at least 3 English task words, outcome words
+   and synonyms. Every `Limits` entry names what the tool does not cover and an
+   alternative: another `tool`, `api` members (checked against the installed
+   RevitAPI.xml), a `user` action, or `revit_unsupported` with its evidence. A tool
+   that writes or has effects declares `Verification`. Prompt guidelines hold only
+   tool-specific facts; identity, manual location, capability and completion rules
+   live once in the platform section.
+3. Use the shared primitives: `ParameterResolver` for any parameter reference,
+   `ElementTraits` for special objects, `ModelEditBatch` for edits, `InheritedState` for
+   anything created from an existing object, and `ElementNames` for names and sheet numbers.
+   The dispatcher reports `model_changes` for every write tool; do not add a private variant. Preserve enforced
+   safeguards. The public bridge contract is the class schema plus registry-added
+   `expected_document_id` and extension-added `_operation_id`. Never weaken identity
+   guards or receipt routing to make an example pass.
+4. Add the manifest entry (name, source, group, summary) and a manual under
+   `references/tools/`. Run `npm run generate:contracts`, which writes the manual's
+   Contract block and the tool index. Write the hand part against the final schema
+   and actual execution: purpose/preconditions, action differences, effects/identity,
+   units/coordinates, result interpretation, recovery and verification. Include at
+   least one valid JSON input example and a source pointer. Label example IDs as
+   placeholders to discover. A native tool also needs its `NATIVE_CONTRACTS` entry; the
+   manifest's native entries reserve its name against bridge descriptors.
+5. Add at least 5 English task phrasings to `tests/discovery/corpus.json`. Register
+   any new "never" or "must" rule in `docs/invariants.json` with its test. Add or extend
+   an `agent-eval` scenario when the tool changes what the agent can do.
+6. Update `documentation_revision` whenever guidance changes. Compatibility with a
+   bridge is the per-tool contract hash (input schema and effects, without wording).
+   Do not bump the package release or redeploy unless part of the task.
+7. Run the checks below. Include defaults, rejected inputs, state transitions,
+   partial/rollback results and caller-visible outcomes where meaningful. Update the
+   README/change log for user-visible behavior. Report live checks separately from
+   offline checks.
+
+## Maintaining skills and workflows
+
+- Keep `skills/pi-revit/SKILL.md` a concise task router with essential cross-tool
+  rules. Put detail in linked references. Large collections of tool names do not
+  belong in its description. Tools/manuals can also be discovered without loading
+  this skill; do not assume the model will always select it.
+- Every workflow distinguishes explanation/planning, inspection, and modification
+  or deliverable creation. Do not make an ordinary question open/edit/export a model.
+- Add subject skills only for independently meaningful Revit tasks. Their references
+  own modeling concepts, constraints and cited Autodesk Help knowledge, while tool
+  manuals own our integration contract. Link between them; do not duplicate both.
+- Put project-specific standards in the user's project context. Source-wide rules
+  belong here, and runtime output conventions belong in the workspace template.
+- Keep uncertainty explicit: a supported preview can validate then roll back;
+  preview IDs are temporary; a timeout is not cancellation; a commit is not a save.
+  Link to recovery/verification instructions instead of inventing another policy.
+
+## Validation and completion
+
+Run these from the repository root, using Node and .NET 8 SDK or newer. Point
+`PI_CODING_AGENT_PATH` to an installed Pi package containing its `jiti` and
+`typebox` dependencies when they are not locally resolvable. Current extension
+fixtures require this variable; the path below is an example, not a fixed location.
+
+```powershell
+$env:PI_CODING_AGENT_PATH = 'C:\path\to\node_modules\@earendil-works\pi-coding-agent'
+npm.cmd run generate:contracts
+npm.cmd run test:docs
+npm.cmd run test:extension
+dotnet run --project tests/document-identity/document-identity-tests.csproj
+dotnet run --project tests/element-query-regressions/element-query-regressions.csproj
+dotnet run --project tests/element-traits/element-traits-tests.csproj
+dotnet run --project tests/derived-state/derived-state-tests.csproj
+git diff --check
+```
+
+`test:docs` checks actual registered input schemas and source-derived bridge
+metadata without running Revit operations. It also checks that generated artifacts are
+current, that contracts are valid with resolvable alternatives, and that the invariant
+register and its tests agree. It enforces discovery-corpus recall, the startup prompt
+budget and the architecture rules (no model saves, one parameter resolver, special
+objects classified, inherited state reported for created-from-existing objects, names assigned
+through `ElementNames`, model changes attached by the dispatcher). `test:extension` uses isolated mock
+discovery and intercepted HTTP. Neither establishes live API behavior, successful
+drawings, agent instruction adherence, or performance improvement.
+
+Use the relevant existing suites for changed components: `tests/model-edit-batch`,
+`transaction-export`, `operation-store`, `element-query-regressions`, `element-traits`, `derived-state`,
+`linked-geometry`, `schedule-fields`, `search-engine`, and `installer` each document
+their scope. Agent behavior is measured with `tests/agent-eval` on a disposable fixture
+(see its README); it never runs as an incidental check. A full bridge build requires matching Revit SDK assemblies; build
+using `scripts/build.ps1`, not deployment, when compilation alone is requested.
+Do not install dependencies, publish a release, modify a live model or deploy an
+add-in as an incidental documentation check.
+
+Before completion review the diff, run appropriate checks, and explain what
+changed, why, and what was actually tested. For model-affecting changes, include
+live verification only when performed within the requested scope. See the
+evaluation guide before claiming faster, cheaper, or more reliable agent behavior.

package/CHANGELOG.md

@@ -7,6 +7,50 @@ Format follows [Keep a Changelog](https://keepachangelog.com/); version headers
 Every published version gets an entry with **Added** / **Changed** / **Fixed** sections
 describing what the user will notice — not internal refactors.
 
+## [0.5.1] - 2026-09-29
+
+### Changed
+
+- README describes the 0.5.0 tools: a "Works in" column (project, family or both) in the tool table, family documents, `model_changes`, `inherited_state`, `name_collision`, scope notes, multi-member `search_api_docs` lookups, and what 0.5.0 was actually tested on. No tool behavior changed; redeploy the add-in so its version matches the package.
+
+## [0.5.0] - 2026-09-29
+
+### Added
+
+- Family documents: every tool declares which document kinds it works in. Ten tools are project-only (sheets, sheet placements, schedules, tags, spatial query, links, coordinates) and refuse a family document before running, with the route to use instead. `get_model_overview` reports `documentKind` and, for a family, its category, current type, type names and parameters. In a family, `model_changes` also lists types and parameters added, removed or changed.
+- Scope notes match the names a request mentions in any writing system; there are no per-language rules.
+
+- Every tool now declares what it does not cover and what to use instead (another tool, specific Revit API members, a user action, or "the Revit API does not offer it" with evidence). `find_revit_tools` shows these limits. When nothing matches, it states the remaining route (API search, then custom code) instead of returning an empty list, so PI-Revit no longer treats "no dedicated tool" as "impossible".
+- One always-present PI-Revit protocol for every tool. It covers checking capability before saying no, doing only what was asked, verifying with the tool's declared method and then stopping and reporting, naming evidence, document identity, and replying in the user's language while searching in English.
+- A completion check. When the same verification is repeated after further edits, PI-Revit asks the agent to compare against the request, stop and report, and offer extras as suggestions.
+- `ping` reports what is actually loaded: extension package, guidance revision, source revision, and whether each tool's manual matches the connected bridge's exact contract.
+- `find_revit_tools` also returns matching workflows, shared guides and skills, including subject skills added to the package later.
+- `manage_sheet_placements` list reports per-kind counts. The titleblock's own revision schedule has its own kind and cannot be moved, so "which sheets have nothing placed?" is answered correctly. Special objects (revision schedules, templates, placeholder sheets, dependent views, group and design-option members, pinned elements) carry `traits` in element listings.
+- Every model-changing call reports `model_changes`: the objects it added, modified and deleted, and for new views their hidden categories and elements. This includes custom C# scripts, so a view duplicated in a script shows what it inherited.
+- Duplicating a view, copying elements, changing types and tagging report `inherited_state`: hidden categories and elements, filters, overrides, template and carried values such as Mark or Comments. The agent checks it against the request instead of trusting an image.
+- Objects that existed before a request are protected from silent reuse. A name that another view, schedule, level, grid, type, material, filter or family type already uses (or a sheet number already taken) is rejected with the existing object's ID. When a call changes a pre-existing object the request names, PI-Revit adds a note, and the protocol requires asking the user or reporting it.
+- `search_api_docs` verifies several API members in one call (names separated by `;`). Each API limit shown by `find_revit_tools` and in the manuals carries a ready one-call lookup.
+- Contributor platform: contracts generated from code into manuals and the tool index, a register of every "never/must" rule with its enforcing test, a discovery quality corpus, a prompt-size budget, architecture gates, and a repeatable agent-evaluation suite (`tests/agent-eval`).
+- One focused manual for each public PI-Revit tool, shared execution/recovery/visual guidance, and explicit explanation, inspection and modification paths in the skill and workflows.
+- Offline manual lookup through `find_revit_tools` with `scope: "documentation"`, plus local manual paths, registration/activation state and version evidence in discovery results.
+- Contributor `AGENTS.md`, architecture/ownership documentation, and offline checks that compare manual examples with the actual public input schemas.
+
+### Changed
+
+- A display-name parameter that matches several parameters on one element is no longer resolved to an arbitrary one. Writes and filters fail with the exact candidate identities, and projections flag the ambiguity.
+- An `is_empty` filter on a parameter that was not found keeps its warning even when elements match, because missing parameters also count as empty.
+- Manual compatibility is an exact per-tool contract comparison (`contract_match`, `contract_changed`, `undocumented`, `unknown`) instead of a version-number match; rewording documentation never flags a bridge.
+- The completion check counts only calls that actually changed the model (from `model_changes`), so a read-only script no longer counts as an edit.
+- Tool search uses English task vocabulary with word-form matching, input names and declared limits. Requests in other languages are translated by the model rather than by language tables.
+- Prompt guidance per tool is shorter: identity, manual location and protocol rules appear once instead of once per tool. `expected_document_id` descriptions now agree with whether the schema requires it.
+- The entry skill routes to relevant references instead of carrying every tool's detailed contract. Installation history remains in the README/change log.
+- `find_revit_tools` includes the six Pi-side utilities alongside the selected bridge catalogue. Native utilities remain discoverable when the bridge is unavailable; bridge availability is identified as a discovery snapshot.
+
+### Fixed
+
+- Advanced tool registration preserves its prompt snippet and guidelines so Pi can use them after activation. Tool guidance also links the matching local manual.
+- Tool search retains packaged summary terms after connecting to Revit, so searches such as `warnings` continue to find the relevant manual and available tool.
+
 ## [0.4.0] - 2026-09-22
 
 ### Added