EvanProgramming · Oct 10, 2026 · Oct 9, 2026 · Oct 10, 2026
diff --git a/docs/extensions.md b/docs/extensions.md
@@ -29,3 +29,37 @@ Self-learning produces bounded candidate artifacts and records their evidence, v
 ## Troubleshooting
 
 If `/skills` does not show an installed package, check the selected skill root, manifest, activation state, and compatibility diagnostics. If plugin loading fails, inspect the sanitized startup diagnostic and import path; do not solve an import problem by adding a credentials file or private environment to a public report. Restore a prior skill through its documented rollback path; disable or remove untrusted extensions only after recording any state they own.
+
+## Tool catalog contracts
+
+`ToolRegistry` owns canonical tool identity, schema, capability, risk, side-effect
+class, parallel safety, visibility, aliases and version/source provenance.
+`ToolSpec` binds that metadata to a workspace/runtime executor; `ToolManifest`
+remains a compatibility projection. MCP `inputSchema` and provider-neutral
+`parameters` are generated from the same defensive schema copy. Tool descriptions
+in prompts, discovery and generated inventory come from registered specs.
+
+`AVAILABLE_TOOLS` is a registry-backed compatibility mapping. Adding a callable
+registers a complete spec, replacing an executor retains its metadata, and
+removal removes its aliases and descriptors. Unknown legacy callables default to
+the restrictive `dynamic` capability, unknown side effects and no parallel
+safety. Explicit `register_spec` rejects duplicate names and alias collisions;
+replacement requires `replace=True`. Schemas and alias metadata are immutable,
+and snapshots preserve complete specs rather than only callables.
+
+Dynamic source registration retains its existing opt-in, capability, AST checks,
+confirmation and audit gates. Registry metadata does not grant capabilities or
+bypass approvals. Side effects are separate from capabilities: graph refresh can
+update derived state under its existing read capability and remains nonparallel.
+Browser and orchestration tools remain nonparallel. Only the pure calculator is
+currently declared parallel-safe; this catalog does not schedule parallel calls.
+
+Existing string executors and MCP compatibility argument conversion remain in
+use. The native typed invocation migration belongs to V3 issue #233. Tool
+inventory is generated with `scripts/generate_tool_inventory.py --write` and
+checked by `make docs-check`.
+
+Registration validates the supported object-schema vocabulary, including nested
+properties/items/combinators and scalar constraints. Unsupported keywords are
+rejected rather than forwarded unchecked; this registry is not a general JSON
+Schema evaluation engine. Existing legacy argument conversion remains unchanged.
diff --git a/docs/index.md b/docs/index.md
@@ -29,6 +29,7 @@ This index covers the current product guides, developer references, and dated en
 - [V3 architecture ownership plan](superpowers/plans/2026-10-07-v3-issue-227.md) records the scoped implementation and verification for issue #227.
 - [V3 provider contract plan](superpowers/plans/2026-10-08-v3-issue-228.md) records the structured response and compatibility migration for issue #228.
 - [V3 provider error plan](superpowers/plans/2026-10-09-v3-issue-231.md) records typed failures, cancellation and bounded retry for issue #231.
+- [V3 authoritative tool catalog plan](superpowers/plans/2026-10-09-v3-issue-232.md) records registry ownership and schema/policy migration for issue #232.
 - Machine-readable audit receipts and benchmark inputs remain beside their corresponding reports under `docs/` and `docs/benchmarks/`.
 
 The repository's [English overview](../README.md) links here. Technical guides are maintained in English; README translations provide localized entry points.
diff --git a/docs/superpowers/plans/2026-10-09-v3-issue-232.md b/docs/superpowers/plans/2026-10-09-v3-issue-232.md
@@ -0,0 +1,41 @@
+# V3 authoritative tool catalog implementation plan
+
+> **For agentic workers:** Use superpowers:executing-plans and test-driven-development. Deliver only issue #232; no merge.
+
+**Goal:** Complete R011, R012, R013, R022 and R023 with the existing ToolRegistry as the authoritative catalog for all 48 runtime tools.
+**Architecture:** ToolSpec stores immutable schema/policy/identity metadata and workspace-bound executors. Registry-backed compatibility mappings preserve string invocation and aliases; MCP/provider descriptors, prompts, discovery and docs derive from specs. Security remains the permission authority.
+**Tech stack:** Python 3.12/3.13, standard library, existing SDK/test environments; no new dependency or paid calls.
+**Spec:** User-approved plan and https://github.com/EvanProgramming/OpenKyrozen/issues/232.
+
+## Task 1: Catalog contracts
+- [x] Write failing specs/registration/runtime-manifest regressions.
+- [x] Extend tools/manifest.py with ToolSpec, ToolManifest projection, validated atomic registration, defensive schema copies and registry-backed mutable compatibility mappings.
+- [x] Declare all built-in metadata once in a tool-owned catalog, including canonical identities, aliases, capabilities, side effects, conservative parallel safety and current MCP/string conversions.
+- [x] Verify invalid metadata/schema/aliases, duplicate rejection, replacement/removal and snapshot preservation.
+
+## Task 2: Runtime and security consumers
+- [x] Bind adapter, memory, discovery and orchestration executors per workspace/runtime; preserve child orchestration exclusions and workspace/session isolation.
+- [x] Make compatibility AVAILABLE_TOOLS writes register metadata; route dynamic definitions and learning restore through registry.
+- [x] Derive capability helpers and aliases from catalog; retain config/token/mode/approval bounds and argument-sensitive checks.
+- [x] Build prompts/discovery from spec descriptions and visibility, without adding deferred-discovery behavior assigned to #234.
+
+## Task 3: Schemas and documentation
+- [x] Move current MCP schema/legacy argument conversion metadata into catalog; preserve existing canonical objects, strings and argument aliases. Typed invocation belongs to #233.
+- [x] Generate MCP and provider-neutral descriptors from the same schema; do not serialize provider SDK requests (#229).
+- [x] Generate tool inventory from registered specs, retain HTTP route inventory and documentation drift checks.
+
+## Task 4: Verify and deliver
+- [x] Run focused 3.12/3.13 tests, full suite, make check/lint/docs-check and offline agent/subagent acceptance.
+- [x] Obtain independent review; reproduce/fix material findings.
+- [ ] GPG-sign task-scoped commits, verify locally/GitHub, create/attach one PR, wait for final-head CI, leave unmerged.
+
+## Review focus
+- No schema/policy bypass via compatibility dictionary mutation or dynamic registration.
+- No shared bound executor across workspaces/users; child callers cannot gain orchestration tools.
+- Schema copies/snapshots cannot mutate authoritative metadata.
+- Dynamic tools retain restrictive capability and existing source-validation/approval/audit gates.
+- Capabilities do not imply side-effect freedom or parallel safety; browser, graph refresh and orchestration remain nonparallel.
+
+Final local verification: 615 full Python3.12 tests,76 focused Python3.13 integration tests; make check/lint/docs-check/agent/subagent acceptance PASS. Independent review findings reproduced and fixed; final review clear. Unsupported schema vocabulary is rejected explicitly; no paid calls.
+
+PR #273 follow-up: reproduced and resolved four automated-review findings. Runtime-tool deletion survives lookup/replacement; mixed-case canonical names and aliases work through plain/XML/DSML calls; valid combinator schemas register while invalid explicit types reject; legacy pipe conversion requires string fields. Final independent re-review reports no material defects. Final local suite and offline acceptance PASS.