docs(clients): distinguish discovery and schema recovery boundaries

2026-10-25 22:08:11 -04:00 · 2026-10-24 03:11:24 +08:00
parent 8bb466d0dc
commit b791f029aa
3 changed files with 66 additions and 8 deletions
@@ -7,7 +7,11 @@ operation and the next useful step; after repair, continue the investigation.
 Commands below use an installed `rea`. If none is available, use the package
 invocation in `SKILL.md` when acquiring REA is authorized. Follow the connected
 server's schemas and the installed CLI's help rather than assuming repository
-main and an older release expose the same arguments.
+main and an older release expose the same arguments. Tool-name prefixes belong
+to the client: find the canonical REA operation in its actual tool listing and
+server association before concluding that it is absent. A shared prefix alone
+does not establish which server an approval wildcard covers. See
+[client tool names and discovery](https://github.com/morluto/rea/blob/main/docs/client-configuration.md#client-tool-names-and-discovery).

 ## Choose the remedy from the observed failure

@@ -6,6 +6,23 @@ for the reviewed setup transaction and [client IDs](installation.md#supported-ag
 The versioned verification notes below describe their stated runs; live service
 acceptance is verified only where explicitly recorded.

+## Client tool names and discovery
+
+REA advertises canonical names such as `binary_session`. The MCP host decides
+how to expose them to its model: a name such as `mcp__rea__binary_session` is a
+client convention, not a prefix REA can enforce. Use the active client's tool
+listing and server association to find the operation. A valid registration or
+installed skill does not prove that those tools reached the model. Doctor reports
+live-server identity as unknown; query `binary_session` through the active client
+to observe the running server's identity.
+
+If a client or fork exposes several servers under the same prefix, a wildcard
+for that prefix does not isolate REA permissions. Inspect that client's actual
+tool names and approval rules before selecting a permission scope. REA setup
+does not repair a client's naming behavior or infer permission drift from an
+unfamiliar prefix. The unavailable fork reported in
+[#5512](https://github.com/morluto/rea/issues/5512) has not been reverified.
+
 ## Fiddler Everywhere alongside REA

 Connect Fiddler Everywhere's MCP server separately for HTTP traffic debugging,
@@ -252,6 +269,15 @@ Review those files manually: setup never edits administrator/workspace settings
 or grants workspace trust. Trust supplied only by a running IDE is outside this
 standalone CLI check.

+A model API's `400 INVALID_ARGUMENT` alone does not identify a rejected schema,
+tool-count limit or skill defect. Preserve the response's parameter path and
+diagnostic, the actual running REA version, Gemini CLI version and selected
+model. For schema rejection, review the [input presentation profiles](mcp-contracts.md#compact-input-schema-profile)
+and reconnect after changing REA's registration environment. Compact is the
+current default; an explicitly stored `full` choice is preserved. The generic
+error in [#4620](https://github.com/morluto/rea/issues/4620) does not establish
+which constraint failed, and local schema checks do not prove live API acceptance.
+
 ## Codex and Devin

 REA manages its launcher and selected provider settings in the client
@@ -316,6 +342,35 @@ These values are client-side deadlines, so increase them in `~/.codex/config.tom
 workload needs more time. Devin honors `XDG_CONFIG_HOME` for its
 `devin/mcp_config.json` on non-Windows systems.

+### Codex with Moonshot or Kimi models
+
+An older REA input containing acyclic local references was rejected by a
+Responses-compatible Kimi gateway as “infinite recursion”; expanding those
+references succeeded. A separate full-profile input failed the provider's
+schema-size limit. These are distinct reported failures, not proof that the
+canonical schema is recursive. Current REA inputs are already self-contained;
+see [schema advertisement](mcp-contracts.md#schema-advertisement).
+
+For this failure, inspect the active MCP launch command and refresh the REA
+installation that command actually runs. A configured package selector or the
+installed skill version alone does not identify a cached or still-running
+server. Follow [installation and update guidance](installation.md#diagnose-update-and-remove).
+Then merge this setting into the REA entry in `$CODEX_HOME/config.toml`
+(`~/.codex/config.toml` by default), preserving its launcher and other settings:
+
+```toml
+[mcp_servers.rea.env]
+REA_MCP_INPUT_SCHEMA_PROFILE = "compact"
+```
+
+If that table already exists, add or update the key there. Restart/reconnect
+Codex so REA reads the new environment. Compact is now REA's default, but an
+explicit `full` override remains effective until changed. It preserves the
+tool inventory and canonical server validation while reducing advertised input
+detail. The probes in [#5160](https://github.com/morluto/rea/issues/5160) covered
+individual tools through one gateway, not the entire current catalog or a
+model-driven analysis workflow.
+
 ## OMP

 For OMP, setup writes a `type: "stdio"` entry to the user-level
@@ -1112,13 +1112,12 @@ failures for such entries name this cause and the operation to rerun with
 ## Schema advertisement

 Advertised input and output schemas contain no reachable recursive references.
-Schemas share repeated definitions through schema-local references while
-preserving complete nested fields and validation rules. Input schemas whose
-shared definitions would exhaust a client's declaration-rendering reference
-budget (Pi 1.1.0 code-mode shares 32 reference expansions across an input and
-renders every later reference as `unknown`) are re-projected without shared
-definitions, so every advertised field renders with complete structure.
-Input properties retain their descriptions and literal examples.
+Input schemas inline repeated definitions before applying the selected
+presentation profile. Both `full` and `compact` start from this self-contained
+projection; output schemas can share schema-local definitions. Full inputs
+retain nested fields, descriptions and valid literal examples. The compatibility
+projections below can relax advertised constraints; canonical runtime validation
+still enforces the complete input contract.

 When a host forwards input schemas to the model, their examples consume context.
 REA's advertised examples therefore never copy complete producer Evidence.