@ai-matrx/agents 0.59.271 → 0.59.273

package/CHANGELOG.md

@@ -1,10 +1,25 @@
 # Changelog
 
-## 0.59.271
+## 0.59.273
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.272
+
+- New export `./context/rules-corpus.json` (shipped in `files`): the context-rules parity corpus, so a consumer test (chat) reads it through the dependency instead of a path into this package. Additive; no consumer action required.
+
+- `./settings`: `reasoning_effort` leaves `AUTO_MEANS_UNSET_KEYS` — a person's "auto" is saved and
+  sent (owner ruling 2026-10-24: unset effort runs at the platform default "low"; "auto" only when a
+  person picks it). New `NEVER_IMPLICIT_AUTO_KEYS` + `isNeverImplicitChoice`; `startingValueFor`
+  never starts a row at "auto". Consumer action: none beyond adopting latest — every writer reads
+  `isUnsetChoice` already.
+
+## 0.59.271
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 8a4ed656ea 2c48e64133 -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.270
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff 4c08cba6c4 8a4ed656ea -- apps/shared/matrx-agents/src`

package/context/rules-corpus.json

@@ -0,0 +1,238 @@
+{
+  "version": 1,
+  "about": "THE parity corpus for context value rules (common-docs/systems/data/scopes-context/context-delivery/RULES.md). Run by the package vitest (context/rules.test.ts) AND aidream pytest (tests/test_context_rules_corpus.py). Expectations are hand-derived from RULES.md section 2 — never regenerate them from either implementation.",
+  "defaults": { "cap": 50000 },
+  "rules_cases": [
+    { "name": "bare value under default", "input": { "chars": 150 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "bare value at the default is inline (<=)", "input": { "chars": 200 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "bare value one over the default", "input": { "chars": 201 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "unresolved lazy source is on request", "input": { "chars": null }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "server per-key default (small lazy document)", "input": { "default_max": 6000, "chars": 5000 }, "expect": { "include": true, "max_inline_chars": 6000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "server per-key default zero (IDE diagnostics)", "input": { "default_max": 0, "chars": 10 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "page limit raises the default", "input": { "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 7000 }, "expect": { "include": true, "max_inline_chars": 8000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent ceiling below page limit wins", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 5000 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "page limit below agent ceiling wins", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 500 }, "chars": 400 }, "expect": { "include": true, "max_inline_chars": 500, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent and page tie — agent named", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 1000 }, "chars": 1000 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "agent declares key without a limit — page limit applies", "input": { "agent": { "declared": true, "max_inline_chars": null }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 3000 }, "expect": { "include": true, "max_inline_chars": 8000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent limit ignored when the key is not declared", "input": { "agent": { "declared": false, "max_inline_chars": 1000 }, "chars": 300 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "page zero beats agent ceiling", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "agent zero with no page", "input": { "agent": { "declared": true, "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "page auto_context off drops an undeclared value", "input": { "surface": { "declared": true, "auto_context": false, "max_inline_chars": null }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "agent declaration re-admits a page auto_context off value", "input": { "agent": { "declared": true }, "surface": { "declared": true, "auto_context": false }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "auto_context off on an undeclared surface value is not a page rule", "input": { "surface": { "declared": false, "auto_context": false }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch drops an undeclared key", "input": { "agent": { "declared": false, "kill_switch": true }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch keeps a declared key", "input": { "agent": { "declared": true, "kill_switch": true }, "chars": 50 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "kill switch beats a page auto_context on", "input": { "agent": { "declared": false, "kill_switch": true }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 50 }, "expect": { "include": false, "max_inline_chars": 8000, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "YOU re-admit past the kill switch", "input": { "agent": { "declared": false, "kill_switch": true }, "user": { "include": true }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU re-admit past page auto_context off", "input": { "surface": { "declared": true, "auto_context": false }, "user": { "include": true }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU turn a value off", "input": { "user": { "include": false }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "YOU turn off an agent-declared value", "input": { "agent": { "declared": true, "max_inline_chars": 5000 }, "user": { "include": false }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 5000, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "agent" }, "clamped": false } },
+    { "name": "YOUR limit beats a lower agent ceiling", "input": { "agent": { "declared": true, "max_inline_chars": 1000 }, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 500 }, "user": { "max_inline_chars": 20000 }, "chars": 15000 }, "expect": { "include": true, "max_inline_chars": 20000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit zero means never inline", "input": { "user": { "max_inline_chars": 0 }, "chars": 5 }, "expect": { "include": true, "max_inline_chars": 0, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit at exact size is inline", "input": { "user": { "max_inline_chars": 300 }, "chars": 300 }, "expect": { "include": true, "max_inline_chars": 300, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "YOUR limit above the cap is clamped and says so", "input": { "user": { "max_inline_chars": 60000 }, "chars": 55000 }, "expect": { "include": true, "max_inline_chars": 50000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": true } },
+    { "name": "agent limit above the cap is clamped", "input": { "agent": { "declared": true, "max_inline_chars": 70000 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 50000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "agent" }, "clamped": true } },
+    { "name": "lowered cap knob clamps a page limit", "input": { "cap": 1000, "surface": { "declared": true, "auto_context": true, "max_inline_chars": 8000 }, "chars": 900 }, "expect": { "include": true, "max_inline_chars": 1000, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": true } },
+    { "name": "negative user limit is ignored", "input": { "user": { "max_inline_chars": -5 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "fractional user limit is ignored", "input": { "user": { "max_inline_chars": 12.5 }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "non-boolean user include is ignored", "input": { "user": { "include": "no" }, "chars": 100 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "user limit only — include still decided by the page", "input": { "surface": { "declared": true, "auto_context": false }, "user": { "max_inline_chars": 900 }, "chars": 100 }, "expect": { "include": false, "max_inline_chars": 900, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "user limit on an unresolved lazy source stays on request", "input": { "user": { "max_inline_chars": 20000 }, "chars": null }, "expect": { "include": true, "max_inline_chars": 20000, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "you" }, "clamped": false } },
+    { "name": "identity survives the agent kill switch", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity survives a page that switched auto context off", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity under the kill switch: the person's off rule still wins", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "user": { "include": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "a page's own conversation never gets the page: the lock turns it off", "input": { "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the person's saved on rule cannot reopen a page's own conversation", "input": { "surface": { "declared": true, "auto_context": false, "own": true }, "user": { "include": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the agent's own declaration cannot reopen a page's own conversation", "input": { "agent": { "declared": true, "kill_switch": false }, "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity is never locked by a page's own conversation", "input": { "identity": true, "surface": { "declared": true, "auto_context": false, "own": true }, "chars": 10 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "default", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity under a switched-off page: the person's off rule still wins", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "user": { "include": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity on the page's own conversation with the person's on rule is sent", "input": { "identity": true, "surface": { "declared": true, "auto_context": false }, "user": { "include": true }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 200, "delivery": "inline", "decided_by": { "include": "you", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "the same page-off layer closes a value that is not identity", "input": { "surface": { "declared": true, "auto_context": false }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "page", "max_inline_chars": "default" }, "clamped": false } },
+    { "name": "identity's limit still resolves like any value", "input": { "identity": true, "agent": { "declared": false, "kill_switch": true }, "surface": { "declared": true, "auto_context": false, "max_inline_chars": 100 }, "chars": 120 }, "expect": { "include": true, "max_inline_chars": 100, "delivery": "on_request", "decided_by": { "include": "default", "max_inline_chars": "page" }, "clamped": false } },
+    { "name": "a value that is not identity is still closed by the kill switch", "input": { "identity": false, "agent": { "declared": false, "kill_switch": true }, "chars": 120 }, "expect": { "include": false, "max_inline_chars": 200, "delivery": "off", "decided_by": { "include": "agent", "max_inline_chars": "default" }, "clamped": false } }
+  ],
+  "lookup_cases": [
+    { "name": "no rows", "rows": {}, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": null },
+    { "name": "default row only", "rows": { "_default": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": false } },
+    { "name": "surface row merges over default per field", "rows": { "_default": { "note_bundle": { "max_inline_chars": 1000 } }, "matrx-user/notes": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": false, "max_inline_chars": 1000 } },
+    { "name": "surface row field wins over default field", "rows": { "_default": { "note_bundle": { "include": false } }, "matrx-user/notes": { "note_bundle": { "include": true } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": { "include": true } },
+    { "name": "other surface rows never apply", "rows": { "matrx-user/tasks": { "note_bundle": { "include": false } } }, "surface_key": "matrx-user/notes", "key": "note_bundle", "expect": null },
+    { "name": "no-surface value reads the default row", "rows": { "_default": { "attached_document_1": { "max_inline_chars": 9000 } } }, "surface_key": "_default", "key": "attached_document_1", "expect": { "max_inline_chars": 9000 } },
+    { "name": "other key absent", "rows": { "_default": { "a": { "include": false } } }, "surface_key": "_default", "key": "b", "expect": null }
+  ],
+  "chars_cases": [
+    { "name": "plain string", "value": "hello", "chars": 5 },
+    { "name": "empty string", "value": "", "chars": 0 },
+    { "name": "accented string counts code points", "value": "héllo", "chars": 5 },
+    { "name": "astral emoji is ONE code point (JS .length would say 2)", "value": "😀ab", "chars": 3 },
+    { "name": "string with a raw newline is itself", "value": "a\nb", "chars": 3 },
+    { "name": "object pretty-printed at indent 2", "value": { "a": 1 }, "chars": 12 },
+    { "name": "empty object", "value": {}, "chars": 2 },
+    { "name": "empty array", "value": [], "chars": 2 },
+    { "name": "array pretty-printed", "value": [1, 2], "chars": 12 },
+    { "name": "nested with empty array", "value": { "a": { "b": [] } }, "chars": 28 },
+    { "name": "object with non-ASCII value (ensure_ascii off)", "value": { "k": "é😀" }, "chars": 15 },
+    { "name": "object with newline in a string escapes it", "value": { "t": "a\nb" }, "chars": 17 },
+    { "name": "boolean", "value": true, "chars": 4 },
+    { "name": "null", "value": null, "chars": 4 },
+    { "name": "integer", "value": 42, "chars": 2 }
+  ],
+  "server_default_cases": [
+    { "name": "plain string has no server default", "value": "hello", "expect": null },
+    { "name": "plain object has no server default", "value": {"a": 1}, "expect": null },
+    { "name": "envelope with content only", "value": {"content": "x", "label": "Note"}, "expect": null },
+    { "name": "envelope default_max_inline_chars is the server default", "value": {"content": "x", "default_max_inline_chars": 9000}, "expect": 9000 },
+    { "name": "envelope default zero (IDE diagnostics)", "value": {"content": "x", "default_max_inline_chars": 0}, "expect": 0 },
+    { "name": "negative envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": -1}, "expect": null },
+    { "name": "boolean envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": true}, "expect": null },
+    { "name": "fractional envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": 12.5}, "expect": null },
+    { "name": "string envelope default is ignored", "value": {"content": "x", "default_max_inline_chars": "9000"}, "expect": null },
+    { "name": "a page limit is not a server default", "value": {"content": "x", "max_inline_chars": 8000}, "expect": null },
+    { "name": "lazy source pointer (no content) is 6000", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111", "field": "content"}, "type": "json", "label": "Doc"}, "expect": 6000 },
+    { "name": "lazy source with null content is 6000", "value": {"content": null, "source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}}, "expect": 6000 },
+    { "name": "a source with content is not lazy", "value": {"content": "body", "source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "normalized resource source is descriptor-first", "value": {"source": {"kind": "file", "id": "11111111-1111-4111-8111-111111111111", "extra": {"resource_type": "file"}}, "type": "json"}, "expect": 0 },
+    { "name": "explicit default beats the lazy default", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "default_max_inline_chars": 100}, "expect": 100 },
+    { "name": "a source without kind is raw content", "value": {"source": {"id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "an unknown key makes the dict raw JSON", "value": {"content": "x", "default_max_inline_chars": 9000, "other": 1}, "expect": null },
+    { "name": "bare resource reference is descriptor-first", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "11111111-1111-4111-8111-111111111111"}, "expect": 0 },
+    { "name": "resource reference nested as envelope content is not promoted", "value": {"content": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "11111111-1111-4111-8111-111111111111"}}, "expect": null },
+    { "name": "resource reference without a UUID id is raw content", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "not-a-uuid"}, "expect": null }
+  ],
+  "envelope_cases": [
+    { "name": "a record that merely has content is raw content", "value": {"id": "11111111-1111-4111-8111-111111111111", "title": "Q3 vendor review", "content": "Follow up with Acme"}, "expect": {"content": {"id": "11111111-1111-4111-8111-111111111111", "title": "Q3 vendor review", "content": "Follow up with Acme"}, "overrides": {}} },
+    { "name": "a true envelope splits content from its fields", "value": {"content": "Follow up with Acme", "label": "Current note", "max_inline_chars": 8000}, "expect": {"content": "Follow up with Acme", "overrides": {"label": "Current note", "max_inline_chars": 8000}} },
+    { "name": "an envelope with an unknown key is raw content", "value": {"content": "x", "label": "L", "pinned": true}, "expect": {"content": {"content": "x", "label": "L", "pinned": true}, "overrides": {}} },
+    { "name": "an envelope keeps default_max_inline_chars as a field", "value": {"content": "2 errors", "default_max_inline_chars": 0}, "expect": {"content": "2 errors", "overrides": {"default_max_inline_chars": 0}} },
+    { "name": "a lazy source pointer has null content", "value": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "type": "json", "label": "Doc"}, "expect": {"content": null, "overrides": {"source": {"kind": "note", "id": "11111111-1111-4111-8111-111111111111"}, "type": "json", "label": "Doc"}} },
+    { "name": "a source without kind and no content is raw content", "value": {"source": {"id": "11111111-1111-4111-8111-111111111111"}, "label": "Doc"}, "expect": {"content": {"source": {"id": "11111111-1111-4111-8111-111111111111"}, "label": "Doc"}, "overrides": {}} },
+    { "name": "a plain string is content", "value": "hello", "expect": {"content": "hello", "overrides": {}} },
+    { "name": "an array is content", "value": [1, 2], "expect": {"content": [1, 2], "overrides": {}} }
+  ],
+  "wire_passthrough_cases": [
+    { "name": "an attached file reference ships as-is", "key": "attached_file_22222222-2222-4222-8222-222222222222", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "22222222-2222-4222-8222-222222222222"}, "passthrough": true },
+    { "name": "a reference with its own policy ships as-is", "key": "attached_file_22222222-2222-4222-8222-222222222222", "value": {"__kind": "resource_ref", "resource_type": "file", "resource_id": "22222222-2222-4222-8222-222222222222", "promote": [{"representation": "clean_text", "max_chars": 5000}], "exclude": ["image"]}, "passthrough": true },
+    { "name": "a processed document reference ships as-is", "key": "source_doc", "value": {"__kind": "resource_ref", "resource_type": "processed_document", "resource_id": "22222222-2222-4222-8222-222222222222"}, "passthrough": true },
+    { "name": "a bare file id under file_id ships as-is", "key": "file_id", "value": "22222222-2222-4222-8222-222222222222", "passthrough": true },
+    { "name": "a bare file id under a *_file_id key ships as-is", "key": "attached_file_id", "value": "22222222-2222-4222-8222-222222222222", "passthrough": true },
+    { "name": "a record with content is wrapped", "key": "current_note", "value": {"id": "22222222-2222-4222-8222-222222222222", "title": "Q3 vendor review", "content": "Follow up"}, "passthrough": false },
+    { "name": "a plain string is wrapped", "key": "current_note", "value": "Follow up with Acme", "passthrough": false }
+  ],
+  "server_resolved_cases": [
+    { "name": "bare note id is server-resolved", "key": "note_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "prefixed note id is server-resolved", "key": "current_note_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "an id key is case-insensitive", "key": "Note_ID", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "a braced UUID is a UUID", "key": "file_id", "value": "{33333333-3333-4333-8333-333333333333}", "expect": true, "server_promotes": true },
+    { "name": "a hyphenless UUID is a UUID", "key": "file_id", "value": "33333333333343338333333333333333", "expect": true, "server_promotes": true },
+    { "name": "a urn UUID is a UUID", "key": "note_id", "value": "urn:uuid:33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": true },
+    { "name": "a top-level resource reference is server-resolved", "key": "current_note", "value": {"__kind": "resource_ref", "resource_type": "note", "resource_id": "33333333-3333-4333-8333-333333333333"}, "expect": true, "server_promotes": true },
+    { "name": "an unregistered id noun: the client stops predicting, the server keeps it raw", "key": "model_id", "value": "33333333-3333-4333-8333-333333333333", "expect": true, "server_promotes": false },
+    { "name": "a resource reference as envelope content: the client stops predicting", "key": "current_note", "value": {"content": {"__kind": "resource_ref", "resource_type": "note", "resource_id": "33333333-3333-4333-8333-333333333333"}, "label": "Note"}, "expect": true, "server_promotes": false },
+    { "name": "a UUID under a non-id key is plain text", "key": "note", "value": "33333333-3333-4333-8333-333333333333", "expect": false, "server_promotes": false },
+    { "name": "a non-UUID under an id key is plain text", "key": "note_id", "value": "not-a-uuid", "expect": false, "server_promotes": false },
+    { "name": "a plain record is not server-resolved", "key": "current_note", "value": {"id": "33333333-3333-4333-8333-333333333333", "title": "Q3 vendor review", "content": "Follow up"}, "expect": false, "server_promotes": false }
+  ],
+  "effective_lookup_cases": [
+    { "name": "declared on both sides: page key", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false} },
+    { "name": "declared client-only: the server files it under _default and still reads the page rule", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false} },
+    { "name": "rule in _default only, page key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"max_inline_chars": 1000} },
+    { "name": "rule in _default only, _default key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"max_inline_chars": 1000} },
+    { "name": "rule in P only, _default key", "rows": {"matrx-user/notes": {"attached_document_1": {"max_inline_chars": 9000}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "attached_document_1", "expect": {"max_inline_chars": 9000} },
+    { "name": "both rows merge per field, page key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "both rows merge per field, _default key", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "P wins a field both rows set", "rows": {"_default": {"current_note_published_to_web": {"include": true, "max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "a surroundings key keeps its own surface", "rows": {"matrx-user/sidebar": {"sidebar_filter": {"include": false}}, "matrx-user/notes": {"sidebar_filter": {"include": true}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/sidebar", "key": "sidebar_filter", "expect": {"include": false} },
+    { "name": "a surroundings key never reads P", "rows": {"matrx-user/notes": {"sidebar_filter": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "matrx-user/sidebar", "key": "sidebar_filter", "expect": null },
+    { "name": "no primary surface: _default key reads _default only", "rows": {"matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": null, "surface_key": "_default", "key": "current_note_published_to_web", "expect": null },
+    { "name": "no primary surface: surface key merges as before", "rows": {"_default": {"current_note_published_to_web": {"max_inline_chars": 1000}}, "matrx-user/notes": {"current_note_published_to_web": {"include": false}}}, "primary_surface": null, "surface_key": "matrx-user/notes", "key": "current_note_published_to_web", "expect": {"include": false, "max_inline_chars": 1000} },
+    { "name": "other surfaces' rows never apply", "rows": {"matrx-user/tasks": {"current_note_published_to_web": {"include": false}}}, "primary_surface": "matrx-user/notes", "surface_key": "_default", "key": "current_note_published_to_web", "expect": null },
+    { "name": "a value a screen mounted inside the page published keeps that screen's surface", "rows": {"matrx-user/transcripts": {"transcript_title": {"include": false}}, "matrx-user/knowledge": {"transcript_title": {"include": true, "max_inline_chars": 9}}, "_default": {"transcript_title": {"max_inline_chars": 700}}}, "primary_surface": "matrx-user/knowledge", "surface_key": "matrx-user/transcripts", "origin": "client", "key": "transcript_title", "expect": {"include": false, "max_inline_chars": 700} },
+    { "name": "a mounted screen's value never reads the primary's row", "rows": {"matrx-user/knowledge": {"transcript_title": {"include": false}}}, "primary_surface": "matrx-user/knowledge", "surface_key": "matrx-user/transcripts", "origin": "client", "key": "transcript_title", "expect": null }
+  ],
+  "humanize_cases": [
+    { "name": "snake case to title words", "key": "current_note", "expect": "Current Note" },
+    { "name": "id is an acronym", "key": "note_id", "expect": "Note ID" },
+    { "name": "a long page key", "key": "current_note_published_to_web", "expect": "Current Note Published To Web" },
+    { "name": "several acronyms", "key": "source_url_pdf", "expect": "Source URL PDF" },
+    { "name": "acronyms are whole parts only", "key": "url2pdf_source", "expect": "Url2pdf Source" },
+    { "name": "hyphens split like underscores", "key": "ai-model-settings", "expect": "AI Model Settings" },
+    { "name": "runs of separators collapse", "key": "attached__file--id", "expect": "Attached File ID" },
+    { "name": "leading and trailing separators drop", "key": "_internal_key_", "expect": "Internal Key" },
+    { "name": "upper-case input is normalized", "key": "API_KEY_STATUS", "expect": "API Key Status" },
+    { "name": "camelCase splits into words", "key": "myValue_ID", "expect": "My Value ID" },
+    { "name": "uuid and json", "key": "resource_uuid_json", "expect": "Resource UUID JSON" },
+    { "name": "every listed acronym", "key": "id_url_pdf_html_json_api_ai_ui_csv_sms_seo_llm_mcp_uuid_iso", "expect": "ID URL PDF HTML JSON API AI UI CSV SMS SEO LLM MCP UUID ISO" },
+    { "name": "a word that only contains an acronym stays a word", "key": "idea_guide", "expect": "Idea Guide" },
+    { "name": "digits stay", "key": "attached_document_2", "expect": "Attached Document 2" },
+    { "name": "a single word", "key": "notes", "expect": "Notes" },
+    { "name": "empty key", "key": "", "expect": "" },
+    { "name": "already words stay as written", "key": "Normal Text", "expect": "Normal Text" },
+    { "name": "a person's phrase keeps its casing and apostrophe", "key": "Customer's iPhone model", "expect": "Customer's iPhone model" },
+    { "name": "a phrase with a version number is not split on the dot", "key": "Version 2.0", "expect": "Version 2.0" },
+    { "name": "a lowercase phrase gains only a capital first letter", "key": "lowercase words here", "expect": "Lowercase words here" },
+    { "name": "a plural acronym tail stays whole", "key": "userIDs", "expect": "User IDs" },
+    { "name": "a plural acronym part", "key": "user_ids", "expect": "User IDs" },
+    { "name": "api key", "key": "api_key", "expect": "API Key" },
+    { "name": "user id", "key": "user_id", "expect": "User ID" },
+    { "name": "an upper-case run before a word splits", "key": "HTMLParser", "expect": "HTML Parser" },
+    { "name": "digits stay inside a part", "key": "step2_output", "expect": "Step2 Output" },
+    { "name": "a short versioned key", "key": "v2", "expect": "V2" },
+    { "name": "no key at all", "key": null, "expect": "" }
+  ],
+  "attachment_key_cases_about": "attached_resource_ + encode(provider + ':' + resource_ref): ASCII letters, digits and '-' kept; every other UTF-8 byte is '_' + two lowercase hex digits ('_' itself is _5f), so the key is unique across providers, case-preserving and stable, and every client derives it from GET /conversations/{id}/attachments (provider, resource_ref).",
+  "attachment_key_cases": [
+    { "name": "a GitHub repository", "provider": "github", "resource_ref": "harbor-point/work-orders", "expect": "attached_resource_github_3aharbor-point_2fwork-orders" },
+    { "name": "a Drive file id keeps its case", "provider": "google", "resource_ref": "1AbCvendorSchedule", "expect": "attached_resource_google_3a1AbCvendorSchedule" },
+    { "name": "ids that differ only by case stay distinct", "provider": "google", "resource_ref": "1abcvendorschedule", "expect": "attached_resource_google_3a1abcvendorschedule" },
+    { "name": "an underscore is escaped, so it never collides with a slash", "provider": "github", "resource_ref": "harbor_point/ops", "expect": "attached_resource_github_3aharbor_5fpoint_2fops" },
+    { "name": "slash form", "provider": "github", "resource_ref": "a/b", "expect": "attached_resource_github_3aa_2fb" },
+    { "name": "underscore form", "provider": "github", "resource_ref": "a_b", "expect": "attached_resource_github_3aa_5fb" },
+    { "name": "the same ref under another provider is another key", "provider": "microsoft", "resource_ref": "1AbC", "expect": "attached_resource_microsoft_3a1AbC" },
+    { "name": "the same ref under Google", "provider": "google", "resource_ref": "1AbC", "expect": "attached_resource_google_3a1AbC" },
+    { "name": "a synced record ref with dots, colons and @", "provider": "google", "resource_ref": "calendar.events:abc123@google.com", "expect": "attached_resource_google_3acalendar_2eevents_3aabc123_40google_2ecom" },
+    { "name": "non-ASCII is escaped byte by byte (UTF-8)", "provider": "github", "resource_ref": "café", "expect": "attached_resource_github_3acaf_c3_a9" },
+    { "name": "spaces and dots", "provider": "microsoft", "resource_ref": "Q4 Budget.xlsx", "expect": "attached_resource_microsoft_3aQ4_20Budget_2exlsx" },
+    { "name": "an empty ref still names the provider", "provider": "github", "resource_ref": "", "expect": "attached_resource_github_3a" }
+  ],
+  "server_authoritative_keys_about": "The keys whose value the SERVER states itself, never the client's copy (RULES.md section 5a, owner ruling 2026-10-01: identity is the server's truth, never the page's claim), and where it states each: active_context = the turn's <active_context> block; manifest = a server-built context value. aidream SERVER_AUTHORITATIVE_KEYS and the package SERVER_AUTHORITATIVE_KEYS must equal this table exactly.",
+  "server_authoritative_keys": { "user": "manifest", "client": "manifest", "organization": "active_context", "active_scopes": "active_context" },
+  "pointer_inline_ceilings_about": "The page-layer limits the client DERIVES instead of reading from the page (owner ruling 2026-09-30, the person's pointer): a selection and the text around it inline up to these sizes on every page, never below the page's own number; pageless_content is a launch with no page behind it. A sent value carries the number on its envelope; a WITHHELD value does not, so the server holds the same table for its receipt row. matrx-frontend POINTER_INLINE_CEILINGS / PAGELESS_CONTENT_INLINE_CEILING and aidream POINTER_INLINE_CEILINGS / PAGELESS_CONTENT_INLINE_CEILING must equal this table exactly.",
+  "pointer_inline_ceilings": { "selection": 10000, "text_before": 2500, "text_after": 2500 },
+  "pageless_content_inline_ceiling": 6000,
+  "consumed_key_cases_about": "The reserved keys the server never keeps under their own name (RULES.md section 5 consumed_as): each still gets a receipt row naming what became of it. aidream RESERVED_CONSUMED_KEYS and the package RESERVED_CONSUMED_KEYS must equal this table exactly.",
+  "consumed_key_cases": [
+    { "name": "the registered screens around the page expand into <surface>::<value> rows", "key": "surface_chain", "consumed_as": "expanded" },
+    { "name": "open unregistered windows expand into window::<title> rows", "key": "window_forms", "consumed_as": "expanded" },
+    { "name": "a table-access grant is a directive the server acts on", "key": "__table_access", "consumed_as": "directive" },
+    { "name": "attached Google files are a directive the server acts on", "key": "__google_files", "consumed_as": "directive" },
+    { "name": "an Orchestra member step's connection is a directive the server acts on", "key": "__orchestra_member", "consumed_as": "directive" }
+  ],
+  "surroundings_key_cases_about": "The key the server delivers each value of a surface_chain level under (aidream chain_context_key), which the composer lists before the send (expandSurroundingsForDisplay): one key, so the composer, the person's rule and the receipt name the same value.",
+  "surroundings_key_cases": [
+    { "name": "the canvas beside the chat delivers its active organization id under its own surface", "surface": "matrx-user/canvas", "value": "active_organization_id", "key": "matrx-user/canvas::active_organization_id" },
+    { "name": "a window's value keeps its window surface", "surface": "matrx-user/data-tables-row-editor", "value": "row_draft", "key": "matrx-user/data-tables-row-editor::row_draft" }
+  ],
+  "page_context_cases_about": "RULES.md section 0: a page's OWN conversation (mode own) and a conversation whose page switch is off (mode off) never receive the page. The listed keys are withheld at the PAGE layer (declared, auto_context off), as is any value from the screens around the page (origin surroundings) and any value the page itself declared; the person values are never withheld. withheld null = the default list for the mode. aidream page_context.py and the package's pageContextWithholds must agree with every case.",
+  "page_context_defaults": {
+    "off": ["route_brief", "surface_chain", "window_forms", "surface_closed"],
+    "own": ["route_brief", "surface_chain", "window_forms", "surface_closed", "conversation"],
+    "person_values": ["user", "client", "organization", "project", "task", "active_scopes"]
+  },
+  "page_context_cases": [
+    { "name": "an own conversation never gets its route", "mode": "own", "withheld": null, "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "an own conversation never gets its own id", "mode": "own", "withheld": null, "key": "conversation", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "a switched-off page still lets the conversation know its id", "mode": "off", "withheld": null, "key": "conversation", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a switched-off page withholds its route", "mode": "off", "withheld": null, "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": true },
+    { "name": "the person is never withheld", "mode": "own", "withheld": null, "key": "user", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "the organization is never withheld, even when the page declares it", "mode": "own", "withheld": null, "key": "organization", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "the conversation's working document is never withheld, even when the page declares the name", "mode": "own", "withheld": null, "key": "working_document", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "the conversation's scratchpad is never withheld from its own conversation", "mode": "own", "withheld": null, "key": "user_scratchpad", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "an attached scratchpad is never withheld by a switched-off page", "mode": "off", "withheld": null, "key": "user_scratchpad_ab12cd34", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/chat", "expect": false },
+    { "name": "a page's own declared value is withheld from its own conversation", "mode": "own", "withheld": null, "key": "battle_columns", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/agent-battle", "expect": true },
+    { "name": "a screen around the page is withheld", "mode": "own", "withheld": null, "key": "matrx-user/notes::content", "origin": "surroundings", "surface_declared": true, "surface_key": "matrx-user/notes", "expect": true },
+    { "name": "an attachment is not the page", "mode": "own", "withheld": null, "key": "attached_document_x", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a page that declares its own list overrides the default", "mode": "own", "withheld": ["conversation"], "key": "route_brief", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a declared list can never withhold the person", "mode": "own", "withheld": ["user", "conversation"], "key": "user", "origin": "client", "surface_declared": false, "surface_key": "_default", "expect": false },
+    { "name": "a switched-off page withholds what a screen mounted inside it published", "mode": "off", "withheld": null, "key": "transcript_title", "origin": "client", "surface_declared": true, "surface_key": "matrx-user/transcripts", "expect": true }
+  ]
+}

package/dist/models/index.cjs

@@ -38,6 +38,7 @@ __export(models_exports, {
   GgufError: () => GgufError,
   INPUT_MODALITIES: () => INPUT_MODALITIES,
   INTERACTION_MODES: () => INTERACTION_MODES,
+  LLM_INTERACTIONS: () => LLM_INTERACTIONS,
   MAX_SUCCESSION_HOPS: () => MAX_SUCCESSION_HOPS,
   MODEL_CATALOG_KINDS: () => MODEL_CATALOG_KINDS,
   MODEL_FAVORITE_ENTITY_TYPE: () => MODEL_FAVORITE_ENTITY_TYPE,
@@ -47,6 +48,7 @@ __export(models_exports, {
   SERVICE_LABEL_PLURAL: () => SERVICE_LABEL_PLURAL,
   TOP_TIER_COST_RATING: () => TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE: () => TOP_TIER_LOCKED_TITLE,
+  UNKNOWN_MODEL_KIND: () => UNKNOWN_MODEL_KIND,
   acceptsTextInstructions: () => acceptsTextInstructions,
   announceModelCatalogChanged: () => announceModelCatalogChanged,
   availableOnDevices: () => availableOnDevices,
@@ -57,6 +59,7 @@ __export(models_exports, {
   catalogForApp: () => catalogForApp,
   catalogKeyColumn: () => catalogKeyColumn,
   catalogKindOf: () => catalogKindOf,
+  catalogKindVerdict: () => catalogKindVerdict,
   cheapestAdequateModel: () => cheapestAdequateModel,
   classConfigKey: () => classConfigKey,
   collapseTiersByClass: () => collapseTiersByClass,
@@ -2828,7 +2831,8 @@ function toDeviceModelFile(r) {
     sha256: sn2(r.sha256),
     artifact_id: sn2(r.artifact_id),
     state: s2(r.state),
-    organization_id: sn2(r.organization_id)
+    organization_id: sn2(r.organization_id),
+    model_key: sn2(r.metadata?.model_key)
   };
 }
 async function readDeviceModelFiles(client, opts = {}) {
@@ -2881,6 +2885,7 @@ var DeviceModelUnavailableError = class extends Error {
 };
 
 // models/catalog-reader.ts
+var UNKNOWN_MODEL_KIND = "unknown";
 var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "llm_model",
   "whisper_model",
@@ -2889,23 +2894,35 @@ var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "video_gen_model",
   "ner_model",
   "wake_word_model",
-  "lora"
+  "lora",
+  "embedding_model",
+  UNKNOWN_MODEL_KIND
 ]);
-function catalogKindOf(m, kindOfEntry) {
+var LLM_INTERACTIONS = /* @__PURE__ */ new Set(["turn", "single", "agent"]);
+function catalogKindVerdict(m, kindOfEntry) {
   for (const v of m.variants)
     for (const id of v.catalog_entry_ids ?? []) {
       const k = kindOfEntry.get(id);
-      if (k && MODEL_CATALOG_KINDS.has(k)) return k;
+      if (k && k !== UNKNOWN_MODEL_KIND && MODEL_CATALOG_KINDS.has(k)) return { kind: k, reason: null };
     }
   const out = m.capabilities.output ?? [];
   const inp = m.capabilities.input ?? [];
-  if (m.presentation?.shelf === "loras") return "lora";
-  if (out.includes("video")) return "video_gen_model";
-  if (out.includes("image")) return "image_gen_model";
-  if (out.includes("audio")) return "tts_model_file";
-  if (inp.includes("audio")) return "whisper_model";
-  if (m.capabilities.interaction === "extraction") return "ner_model";
-  return "llm_model";
+  const interaction = m.capabilities.interaction ?? "";
+  const placed = (kind) => ({ kind, reason: null });
+  if (m.presentation?.shelf === "loras" || interaction === "adapter") return placed("lora");
+  if (out.includes("video")) return placed("video_gen_model");
+  if (out.includes("image")) return placed("image_gen_model");
+  if (out.includes("embedding")) return placed("embedding_model");
+  if (out.includes("audio")) return placed("tts_model_file");
+  if (inp.includes("audio") && (out.includes("decision") || interaction === "detection")) return placed("wake_word_model");
+  if (inp.includes("audio") && out.includes("text")) return placed("whisper_model");
+  if (interaction === "extraction") return placed("ner_model");
+  if (inp.includes("text") && out.includes("text") && LLM_INTERACTIONS.has(interaction)) return placed("llm_model");
+  const shape = `input [${inp.join(", ")}], output [${out.join(", ")}], interaction ${interaction || "(none)"}`;
+  return { kind: UNKNOWN_MODEL_KIND, reason: `no kind rule places ${shape}` };
+}
+function catalogKindOf(m, kindOfEntry) {
+  return catalogKindVerdict(m, kindOfEntry).kind;
 }
 function canonicalJson(value) {
   if (value === void 0) return "null";
@@ -2984,6 +3001,8 @@ async function readCatalogWith(client, opts, preread) {
     const p = presentationOf.get(c.id);
     stamp(p);
     const maker = providerById.get(s3(m.provider_id));
+    const verdict = catalogKindVerdict(c, kindOfEntry);
+    if (verdict.reason) warnings.push(`${s3(m.name)}: kind unknown: ${verdict.reason}`);
     return [
       {
         id: s3(m.id),
@@ -2994,7 +3013,7 @@ async function readCatalogWith(client, opts, preread) {
         maker_logo_file_id: sn3(maker?.logo_file_id),
         description: sn3(m.description),
         capabilities: m.capabilities ?? {},
-        kind: catalogKindOf(c, kindOfEntry),
+        kind: verdict.kind,
         offered: c.offered,
         updated_at: c.updated_at,
         presentation: p ? {

package/dist/models/index.d.cts

@@ -1109,7 +1109,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
@@ -1764,6 +1764,11 @@ interface DeviceModelFile {
     artifact_id: string | null;
     state: string;
     organization_id: string | null;
+    /**
+     * The key the computer runs this file under (`metadata.model_key`, published by Matrx 2): for a person's own
+     * file it is the run key the device's model service names it by. Null when not reported yet.
+     */
+    model_key: string | null;
 }
 declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
 /**
@@ -1845,8 +1850,12 @@ interface ReadModelCatalogOptions {
         appInstanceIds?: readonly string[];
     };
 }
+/** The kind of a model the catalog cannot place by its capabilities: shown loudly, never offered to a chat. */
+declare const UNKNOWN_MODEL_KIND: "unknown";
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
+/** The interactions a text-in, text-out model answers a person in: only these make an llm_model. */
+declare const LLM_INTERACTIONS: ReadonlySet<string>;
 /** What `catalogKindOf` reads from a model (a CuratedModel or a LocalModel from `readModelCatalog` both fit). */
 interface CatalogKindInput {
     readonly variants: ReadonlyArray<{
@@ -1861,11 +1870,20 @@ interface CatalogKindInput {
         readonly shelf?: string | null;
     } | null;
 }
+/** A model's admin kind and, when it is `unknown`, why (one line, said on the admin page and in reader warnings). */
+interface CatalogKindVerdict {
+    kind: string;
+    reason: string | null;
+}
 /**
- * THE admin Catalogs kind of a unified model: the kind of the old public.catalog_entries rows its variants
- * carry (the list migration stamps them), when that is a model kind; else placed by what it does.
- * `kindOfEntry` maps catalog_entries.id → kind.
+ * THE admin Catalogs kind of a unified model, with the reason when it cannot be placed: the kind of the
+ * old public.catalog_entries rows its variants carry (the list migration stamps them), when that is a
+ * model kind; else placed by what it does (capabilities, never a name list). There is NO default: a model
+ * is an llm_model only when it takes text, gives text and answers in a chat-like interaction
+ * (LLM_INTERACTIONS); anything the rules cannot place is `unknown`, with the reason.
  */
+declare function catalogKindVerdict(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): CatalogKindVerdict;
+/** THE admin Catalogs kind of a unified model (`catalogKindVerdict(...).kind`); `unknown` when it cannot be placed. */
 declare function catalogKindOf(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): string;
 /** sha256 (hex) of the catalog's canonical JSON, its own `catalog_fingerprint` left out. Isomorphic (pure JS). */
 declare function catalogFingerprint(catalog: LocalModelCatalog): string;
@@ -2087,5 +2105,5 @@ interface ModelCatalogVisibilityOptions {
  */
 declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, LLM_INTERACTIONS, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, UNKNOWN_MODEL_KIND, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, catalogKindVerdict, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogKindVerdict, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.d.ts

@@ -1109,7 +1109,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;
@@ -1764,6 +1764,11 @@ interface DeviceModelFile {
     artifact_id: string | null;
     state: string;
     organization_id: string | null;
+    /**
+     * The key the computer runs this file under (`metadata.model_key`, published by Matrx 2): for a person's own
+     * file it is the run key the device's model service names it by. Null when not reported yet.
+     */
+    model_key: string | null;
 }
 declare function toDeviceModelFile(r: Row$1): DeviceModelFile;
 /**
@@ -1845,8 +1850,12 @@ interface ReadModelCatalogOptions {
         appInstanceIds?: readonly string[];
     };
 }
+/** The kind of a model the catalog cannot place by its capabilities: shown loudly, never offered to a chat. */
+declare const UNKNOWN_MODEL_KIND: "unknown";
 /** The catalog kinds whose rows live in the unified catalog (ai.*): the admin Catalogs page's model kinds. */
 declare const MODEL_CATALOG_KINDS: ReadonlySet<string>;
+/** The interactions a text-in, text-out model answers a person in: only these make an llm_model. */
+declare const LLM_INTERACTIONS: ReadonlySet<string>;
 /** What `catalogKindOf` reads from a model (a CuratedModel or a LocalModel from `readModelCatalog` both fit). */
 interface CatalogKindInput {
     readonly variants: ReadonlyArray<{
@@ -1861,11 +1870,20 @@ interface CatalogKindInput {
         readonly shelf?: string | null;
     } | null;
 }
+/** A model's admin kind and, when it is `unknown`, why (one line, said on the admin page and in reader warnings). */
+interface CatalogKindVerdict {
+    kind: string;
+    reason: string | null;
+}
 /**
- * THE admin Catalogs kind of a unified model: the kind of the old public.catalog_entries rows its variants
- * carry (the list migration stamps them), when that is a model kind; else placed by what it does.
- * `kindOfEntry` maps catalog_entries.id → kind.
+ * THE admin Catalogs kind of a unified model, with the reason when it cannot be placed: the kind of the
+ * old public.catalog_entries rows its variants carry (the list migration stamps them), when that is a
+ * model kind; else placed by what it does (capabilities, never a name list). There is NO default: a model
+ * is an llm_model only when it takes text, gives text and answers in a chat-like interaction
+ * (LLM_INTERACTIONS); anything the rules cannot place is `unknown`, with the reason.
  */
+declare function catalogKindVerdict(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): CatalogKindVerdict;
+/** THE admin Catalogs kind of a unified model (`catalogKindVerdict(...).kind`); `unknown` when it cannot be placed. */
 declare function catalogKindOf(m: CatalogKindInput, kindOfEntry: ReadonlyMap<string, string>): string;
 /** sha256 (hex) of the catalog's canonical JSON, its own `catalog_fingerprint` left out. Isomorphic (pure JS). */
 declare function catalogFingerprint(catalog: LocalModelCatalog): string;
@@ -2087,5 +2105,5 @@ interface ModelCatalogVisibilityOptions {
  */
 declare function followModelCatalogVisibility(options: ModelCatalogVisibilityOptions): () => void;
 
-export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
-export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };
+export { CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, DEFAULT_CAPABILITIES, DEVICE_FILE_USABLE_STATES, DEVICE_OWN_FILE_USABLE_STATES, DEVICE_RULE_TWIN_FIXTURE, DEVICE_SERVED_SETTINGS_KEY, DEVICE_SERVED_VIA, DeviceModelUnavailableError, EMPTY_MODEL_RECORDS, EXCLUDED_REVIEW_STATES, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, GgufError, INPUT_MODALITIES, INTERACTION_MODES, LLM_INTERACTIONS, MAX_SUCCESSION_HOPS, MODEL_CATALOG_KINDS, MODEL_FAVORITE_ENTITY_TYPE, NEW_AGENT_DEFAULT_MODEL_KNOB, OUTPUT_MODALITIES, SERVICE_LABEL, SERVICE_LABEL_PLURAL, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, UNKNOWN_MODEL_KIND, acceptsTextInstructions, announceModelCatalogChanged, availableOnDevices, blendedPrice, buildModelClassIndex, buildSuccessionIndex, catalogFingerprint, catalogForApp, catalogKeyColumn, catalogKindOf, catalogKindVerdict, cheapestAdequateModel, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsNeed, fitsThisComputer, followModelCatalogChanges, followModelCatalogVisibility, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isChatModelCapability, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isListedVariant, isLocalModelCatalog, isManagedAgentModelCapability, isModelCatalogChange, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelCatalogRevision, modelClassKnobFor, modelClassName, modelClassPinOf, modelDisplayLabel, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, onModelCatalogChanged, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readCuratedRows, readDeviceModelFiles, readGgufHeader, readModelCatalog, readModelCatalogStamp, readModelIdentities, readPublicModel, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifactIds, requiredArtifacts, resetSuccessionLogForTests, resolveDeviceModel, resolveLiveModelId, resolveModelMapKnob, resolveNewAgentModelId, resolvePreferredModelChoice, resolveSuccessor, runtimesOnEngine, seesImages, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, takesInput, toAuditRecord, toDeviceModelFile, validateModelSet, variantVerdict, withModelClass };
+export type { AdminOffering, AdminPricingBand, ArtifactUse, AuditCapabilitiesRecord, AvailabilityVariant, CapabilitiesParseContext, CatalogKeyColumn, CatalogKindInput, CatalogKindVerdict, CatalogModel, CatalogTier, CheapestAdequateOptions, CompatStatus, ContentType, CuratedCatalogClient, CuratedModel, CuratedPresentation, CuratedRows, CuratedVariant, DecidedBy, DeviceAvailability, DeviceGraphics, DeviceHardware, DeviceModelFile, DeviceModelResolution, DeviceServedSettings, DiscoveryAmbiguity, DiscoveryArtifact, DiscoveryMedia, DiscoveryResult, DiscoveryRuntime, DiscoverySource, DiscoveryVariant, FeatureBucket, FeatureBucketMeta, FeatureKey, FitCapabilities, GgufHeader, GgufRead, GgufTensor, GroupedFeatures, HardwareClass, HardwareClasses, HeaderFlag, HeaderJudgement, HeaderRefusal, Interaction, InteractionMode, LocalArtifact, LocalCatalogClient, LocalCatalogQuery, LocalCompatRow, LocalModel, LocalModelCatalog, LocalPresentation, LocalRuntime, LocalRuntimeBuild, LocalVariant, Modality, ModelCapabilities, ModelCatalog, ModelCatalogChangePayload, ModelCatalogClient, ModelCatalogConfig, ModelCatalogDirectiveSubscribe, ModelCatalogErrorSink, ModelCatalogPgError, ModelCatalogPgResult, ModelCatalogQuery, ModelCatalogState, ModelCatalogVariant, ModelCatalogVariantState, ModelCatalogVisibilityOptions, ModelClassConfig, ModelClassEntry, ModelClassIndex, ModelDiagnosticEntry, ModelDiagnosticsSink, ModelFavorites, ModelFavoritesCache, ModelFavoritesClient, ModelFavoritesConfig, ModelFavoritesErrorSink, ModelFavoritesState, ModelFetchScope, ModelFileHandle, ModelFit, ModelIdentityRow, ModelJson, ModelLabelSource, ModelNeed, ModelOfferingRow, ModelOption, ModelOptionWithLifecycle, ModelRecord, ModelRecordFetchType, ModelRecords, ModelRecordsClient, ModelRecordsConfig, ModelRecordsState, ModelSelectionPurpose, ModelSetEnv, ModelSetFacts, ModelSetValidation, NewAgentModel, NoSelection, OrderedLike, PreferredModelChoice, PreferredModelChoicePorts, PriceTier, PricedCatalogModel, PublicModelClient, RankOptions, RankedVariant, ReadModelCatalogOptions, SelectDevice, Selection, ShardName, SuccessionClient, SuccessionIndex, SuccessionNode, VariantDiscovery, VariantVerdict, Want };

package/dist/models/index.js

@@ -2648,7 +2648,8 @@ function toDeviceModelFile(r) {
     sha256: sn2(r.sha256),
     artifact_id: sn2(r.artifact_id),
     state: s2(r.state),
-    organization_id: sn2(r.organization_id)
+    organization_id: sn2(r.organization_id),
+    model_key: sn2(r.metadata?.model_key)
   };
 }
 async function readDeviceModelFiles(client, opts = {}) {
@@ -2701,6 +2702,7 @@ var DeviceModelUnavailableError = class extends Error {
 };
 
 // models/catalog-reader.ts
+var UNKNOWN_MODEL_KIND = "unknown";
 var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "llm_model",
   "whisper_model",
@@ -2709,23 +2711,35 @@ var MODEL_CATALOG_KINDS = /* @__PURE__ */ new Set([
   "video_gen_model",
   "ner_model",
   "wake_word_model",
-  "lora"
+  "lora",
+  "embedding_model",
+  UNKNOWN_MODEL_KIND
 ]);
-function catalogKindOf(m, kindOfEntry) {
+var LLM_INTERACTIONS = /* @__PURE__ */ new Set(["turn", "single", "agent"]);
+function catalogKindVerdict(m, kindOfEntry) {
   for (const v of m.variants)
     for (const id of v.catalog_entry_ids ?? []) {
       const k = kindOfEntry.get(id);
-      if (k && MODEL_CATALOG_KINDS.has(k)) return k;
+      if (k && k !== UNKNOWN_MODEL_KIND && MODEL_CATALOG_KINDS.has(k)) return { kind: k, reason: null };
     }
   const out = m.capabilities.output ?? [];
   const inp = m.capabilities.input ?? [];
-  if (m.presentation?.shelf === "loras") return "lora";
-  if (out.includes("video")) return "video_gen_model";
-  if (out.includes("image")) return "image_gen_model";
-  if (out.includes("audio")) return "tts_model_file";
-  if (inp.includes("audio")) return "whisper_model";
-  if (m.capabilities.interaction === "extraction") return "ner_model";
-  return "llm_model";
+  const interaction = m.capabilities.interaction ?? "";
+  const placed = (kind) => ({ kind, reason: null });
+  if (m.presentation?.shelf === "loras" || interaction === "adapter") return placed("lora");
+  if (out.includes("video")) return placed("video_gen_model");
+  if (out.includes("image")) return placed("image_gen_model");
+  if (out.includes("embedding")) return placed("embedding_model");
+  if (out.includes("audio")) return placed("tts_model_file");
+  if (inp.includes("audio") && (out.includes("decision") || interaction === "detection")) return placed("wake_word_model");
+  if (inp.includes("audio") && out.includes("text")) return placed("whisper_model");
+  if (interaction === "extraction") return placed("ner_model");
+  if (inp.includes("text") && out.includes("text") && LLM_INTERACTIONS.has(interaction)) return placed("llm_model");
+  const shape = `input [${inp.join(", ")}], output [${out.join(", ")}], interaction ${interaction || "(none)"}`;
+  return { kind: UNKNOWN_MODEL_KIND, reason: `no kind rule places ${shape}` };
+}
+function catalogKindOf(m, kindOfEntry) {
+  return catalogKindVerdict(m, kindOfEntry).kind;
 }
 function canonicalJson(value) {
   if (value === void 0) return "null";
@@ -2804,6 +2818,8 @@ async function readCatalogWith(client, opts, preread) {
     const p = presentationOf.get(c.id);
     stamp(p);
     const maker = providerById.get(s3(m.provider_id));
+    const verdict = catalogKindVerdict(c, kindOfEntry);
+    if (verdict.reason) warnings.push(`${s3(m.name)}: kind unknown: ${verdict.reason}`);
     return [
       {
         id: s3(m.id),
@@ -2814,7 +2830,7 @@ async function readCatalogWith(client, opts, preread) {
         maker_logo_file_id: sn3(maker?.logo_file_id),
         description: sn3(m.description),
         capabilities: m.capabilities ?? {},
-        kind: catalogKindOf(c, kindOfEntry),
+        kind: verdict.kind,
         offered: c.offered,
         updated_at: c.updated_at,
         presentation: p ? {
@@ -3055,6 +3071,7 @@ export {
   GgufError,
   INPUT_MODALITIES,
   INTERACTION_MODES,
+  LLM_INTERACTIONS,
   MAX_SUCCESSION_HOPS,
   MODEL_CATALOG_KINDS,
   MODEL_FAVORITE_ENTITY_TYPE,
@@ -3064,6 +3081,7 @@ export {
   SERVICE_LABEL_PLURAL,
   TOP_TIER_COST_RATING,
   TOP_TIER_LOCKED_TITLE,
+  UNKNOWN_MODEL_KIND,
   acceptsTextInstructions,
   announceModelCatalogChanged,
   availableOnDevices,
@@ -3074,6 +3092,7 @@ export {
   catalogForApp,
   catalogKeyColumn,
   catalogKindOf,
+  catalogKindVerdict,
   cheapestAdequateModel,
   classConfigKey,
   collapseTiersByClass,

package/dist/models/react/index.d.cts

@@ -804,7 +804,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;

package/dist/models/react/index.d.ts

@@ -804,7 +804,7 @@ interface LocalModel {
     /** Matrx 2's 1.48 id for a model seeded from its old list (metadata.desktop_id). */
     desktop_id?: string | null;
     maker_logo_file_id?: string | null;
-    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora. */
+    /** The admin Catalogs kind (`catalogKindOf`): llm_model, whisper_model, tts_model_file, image_gen_model, video_gen_model, ner_model, wake_word_model, lora, embedding_model, or unknown (no rule places it; `catalogKindVerdict` says why). */
     kind?: string;
     /** At least one variant is offered (Matrx 2 lists it). */
     offered?: boolean;

package/dist/settings/index.cjs

@@ -25,6 +25,7 @@ __export(settings_exports, {
   CATALOGUE_KEYS: () => CATALOGUE_KEYS,
   EMPTY_UI_GATES: () => EMPTY_UI_GATES,
   ENUM_OFF_VALUE: () => ENUM_OFF_VALUE,
+  NEVER_IMPLICIT_AUTO_KEYS: () => NEVER_IMPLICIT_AUTO_KEYS,
   PARAM_ALIASES: () => PARAM_ALIASES,
   SETTINGS_CATALOGUE: () => SETTINGS_CATALOGUE,
   UI_GATE_EDITABLE_KEYS: () => UI_GATE_EDITABLE_KEYS,
@@ -39,6 +40,7 @@ __export(settings_exports, {
   extractModelDefaults: () => extractModelDefaults,
   gateEnabled: () => gateEnabled,
   getActionForMode: () => getActionForMode,
+  isNeverImplicitChoice: () => isNeverImplicitChoice,
   isOffValue: () => isOffValue,
   isUiGateKey: () => isUiGateKey,
   isUnsetChoice: () => isUnsetChoice,
@@ -1032,13 +1034,19 @@ function withSettingState(settings, key, state, control, value) {
 // settings/auto-means-unset.ts
 var AUTO_VALUE = "auto";
 var AUTO_MEANS_UNSET_KEYS = /* @__PURE__ */ new Set([
-  "reasoning_effort",
   "visualization"
 ]);
+var NEVER_IMPLICIT_AUTO_KEYS = /* @__PURE__ */ new Set([
+  "reasoning_effort"
+]);
 function isUnsetChoice(key, value) {
   if (value === void 0 || value === null) return true;
   return value === AUTO_VALUE && AUTO_MEANS_UNSET_KEYS.has(key);
 }
+function isNeverImplicitChoice(key, value) {
+  if (isUnsetChoice(key, value)) return true;
+  return value === AUTO_VALUE && NEVER_IMPLICIT_AUTO_KEYS.has(key);
+}
 
 // settings/starting-value.ts
 function startingValueFor(key, control) {
@@ -1056,8 +1064,8 @@ function startingValueFor(key, control) {
       value = [];
     }
   }
-  if (isUnsetChoice(key, value) && control.type === "enum" && control.enum?.length) {
-    value = control.enum.find((choice) => !isUnsetChoice(key, choice));
+  if (isNeverImplicitChoice(key, value) && control.type === "enum" && control.enum?.length) {
+    value = control.enum.find((choice) => !isNeverImplicitChoice(key, choice));
   }
   if (key === "response_format" && typeof value === "string") {
     value = value === "" ? void 0 : { type: value };

package/dist/settings/index.d.cts

@@ -516,14 +516,16 @@ declare function withSettingState<T extends Record<string, unknown>>(settings: T
  * included at all").
  *
  * For these keys the house "auto" posture IS the unset state on the server:
- *   - reasoning_effort — aidream `matrx_ai/catalog/canonicalize.py` normalizes
- *     "auto" to None before any rule or processor sees it (ai_041).
  *   - visualization — the Google research agent reads an unset value as "auto"
  *     (`providers/google/google_research_agent.py`).
  * So a control that offers "auto" for one of them must CLEAR the key, never
- * save the word: a saved "auto" and an absent key would be two stored states
- * with one meaning. Keys whose "auto" is a real provider value that goes on the
- * wire (render_quality, background, moderation, reasoning_summary) are NOT here.
+ * save the word.
+ *
+ * `reasoning_effort` is NOT here (owner ruling 2026-10-24): unset runs at the
+ * platform default ("low"), and "auto" is a PERSON's explicit choice that the
+ * server sends as the provider's own auto where it has one
+ * (`matrx_ai/catalog/controls.py::apply_reasoning_default`). So a person picking
+ * "auto" SAVES "auto"; it is never a starting value (`NEVER_IMPLICIT_AUTO_KEYS`).
  *
  * Every settings writer reads this one rule: the agent builder
  * (AgentSettingsCore), the conversation settings target (useConversationSettingsTarget), the
@@ -531,8 +533,12 @@ declare function withSettingState<T extends Record<string, unknown>>(settings: T
  */
 declare const AUTO_VALUE = "auto";
 declare const AUTO_MEANS_UNSET_KEYS: ReadonlySet<string>;
+/** Keys whose "auto" is a real choice that only a person makes — never a default. */
+declare const NEVER_IMPLICIT_AUTO_KEYS: ReadonlySet<string>;
 /** True when writing `value` to `key` means "not set" — the key is removed. */
 declare function isUnsetChoice(key: string, value: unknown): boolean;
+/** True when `value` may not be chosen FOR a person (a starting value / default). */
+declare function isNeverImplicitChoice(key: string, value: unknown): boolean;
 
 /**
  * THE starting value of a setting a person turns on (ticks its box). One rule
@@ -746,5 +752,5 @@ interface CapabilitiesWriteTarget {
     error?: string | null;
 }
 
-export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, CATALOGUE_KEYS, EMPTY_UI_GATES, ENUM_OFF_VALUE, PARAM_ALIASES, SETTINGS_CATALOGUE, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extraSettingKeys, extractModelDefaults, gateEnabled, getActionForMode, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingControl, settingLabel, settingStateOf, startingValueFor, withSettingState };
+export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, CATALOGUE_KEYS, EMPTY_UI_GATES, ENUM_OFF_VALUE, NEVER_IMPLICIT_AUTO_KEYS, PARAM_ALIASES, SETTINGS_CATALOGUE, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extraSettingKeys, extractModelDefaults, gateEnabled, getActionForMode, isNeverImplicitChoice, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingControl, settingLabel, settingStateOf, startingValueFor, withSettingState };
 export type { AgentContext, AgentSettings, AgentSettingsEntry, AgentSettingsState, AgentSource, AgentVariable, CapabilitiesWriteTarget, CatalogueEntry, CatalogueGroup, ConflictAction, ConflictItem, ConflictReason, ConflictSummary, ControlDefinition, ControlType, ExtraSettingKeys, InitializeSettingsInput, LLMParams, ModelRowTarget, ModelSettingRow, NormalizedControls, PendingModelSwitch, RenderGroup, ResolutionMode, SettingRowFacts, SettingRowRead, SettingRowView, SettingState, SettingsGroupId, SettingsModelInfo, SettingsStore, SettingsStoreConfig, SettingsWriteTarget, UiGateEditableKey, UiGateKey, UiGates, VariableCustomComponentRef };

package/dist/settings/index.d.ts

@@ -516,14 +516,16 @@ declare function withSettingState<T extends Record<string, unknown>>(settings: T
  * included at all").
  *
  * For these keys the house "auto" posture IS the unset state on the server:
- *   - reasoning_effort — aidream `matrx_ai/catalog/canonicalize.py` normalizes
- *     "auto" to None before any rule or processor sees it (ai_041).
  *   - visualization — the Google research agent reads an unset value as "auto"
  *     (`providers/google/google_research_agent.py`).
  * So a control that offers "auto" for one of them must CLEAR the key, never
- * save the word: a saved "auto" and an absent key would be two stored states
- * with one meaning. Keys whose "auto" is a real provider value that goes on the
- * wire (render_quality, background, moderation, reasoning_summary) are NOT here.
+ * save the word.
+ *
+ * `reasoning_effort` is NOT here (owner ruling 2026-10-24): unset runs at the
+ * platform default ("low"), and "auto" is a PERSON's explicit choice that the
+ * server sends as the provider's own auto where it has one
+ * (`matrx_ai/catalog/controls.py::apply_reasoning_default`). So a person picking
+ * "auto" SAVES "auto"; it is never a starting value (`NEVER_IMPLICIT_AUTO_KEYS`).
  *
  * Every settings writer reads this one rule: the agent builder
  * (AgentSettingsCore), the conversation settings target (useConversationSettingsTarget), the
@@ -531,8 +533,12 @@ declare function withSettingState<T extends Record<string, unknown>>(settings: T
  */
 declare const AUTO_VALUE = "auto";
 declare const AUTO_MEANS_UNSET_KEYS: ReadonlySet<string>;
+/** Keys whose "auto" is a real choice that only a person makes — never a default. */
+declare const NEVER_IMPLICIT_AUTO_KEYS: ReadonlySet<string>;
 /** True when writing `value` to `key` means "not set" — the key is removed. */
 declare function isUnsetChoice(key: string, value: unknown): boolean;
+/** True when `value` may not be chosen FOR a person (a starting value / default). */
+declare function isNeverImplicitChoice(key: string, value: unknown): boolean;
 
 /**
  * THE starting value of a setting a person turns on (ticks its box). One rule
@@ -746,5 +752,5 @@ interface CapabilitiesWriteTarget {
     error?: string | null;
 }
 
-export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, CATALOGUE_KEYS, EMPTY_UI_GATES, ENUM_OFF_VALUE, PARAM_ALIASES, SETTINGS_CATALOGUE, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extraSettingKeys, extractModelDefaults, gateEnabled, getActionForMode, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingControl, settingLabel, settingStateOf, startingValueFor, withSettingState };
+export { AUTO_MEANS_UNSET_KEYS, AUTO_VALUE, CATALOGUE_KEYS, EMPTY_UI_GATES, ENUM_OFF_VALUE, NEVER_IMPLICIT_AUTO_KEYS, PARAM_ALIASES, SETTINGS_CATALOGUE, UI_GATE_EDITABLE_KEYS, UI_GATE_KEYS, buildApiPayload, buildSettingsRows, computeOverrideDiff, createSettingsStore, detectConflicts, effectiveOfferingPinOf, extraSettingKeys, extractModelDefaults, gateEnabled, getActionForMode, isNeverImplicitChoice, isOffValue, isUiGateKey, isUnsetChoice, mergeEffectiveSettings, mergeVariableValues, offValueFor, parseModelControls, parseUiGates, readApiPayload, readConflictActions, readConflictSummary, readEffectiveModelId, readEffectiveSettings, readEffectiveVariableValues, readPreviewedResolution, readSettingsEntry, resolveConflicts, sanitizeSettings, settingControl, settingLabel, settingStateOf, startingValueFor, withSettingState };
 export type { AgentContext, AgentSettings, AgentSettingsEntry, AgentSettingsState, AgentSource, AgentVariable, CapabilitiesWriteTarget, CatalogueEntry, CatalogueGroup, ConflictAction, ConflictItem, ConflictReason, ConflictSummary, ControlDefinition, ControlType, ExtraSettingKeys, InitializeSettingsInput, LLMParams, ModelRowTarget, ModelSettingRow, NormalizedControls, PendingModelSwitch, RenderGroup, ResolutionMode, SettingRowFacts, SettingRowRead, SettingRowView, SettingState, SettingsGroupId, SettingsModelInfo, SettingsStore, SettingsStoreConfig, SettingsWriteTarget, UiGateEditableKey, UiGateKey, UiGates, VariableCustomComponentRef };

package/dist/settings/index.js

@@ -965,13 +965,19 @@ function withSettingState(settings, key, state, control, value) {
 // settings/auto-means-unset.ts
 var AUTO_VALUE = "auto";
 var AUTO_MEANS_UNSET_KEYS = /* @__PURE__ */ new Set([
-  "reasoning_effort",
   "visualization"
 ]);
+var NEVER_IMPLICIT_AUTO_KEYS = /* @__PURE__ */ new Set([
+  "reasoning_effort"
+]);
 function isUnsetChoice(key, value) {
   if (value === void 0 || value === null) return true;
   return value === AUTO_VALUE && AUTO_MEANS_UNSET_KEYS.has(key);
 }
+function isNeverImplicitChoice(key, value) {
+  if (isUnsetChoice(key, value)) return true;
+  return value === AUTO_VALUE && NEVER_IMPLICIT_AUTO_KEYS.has(key);
+}
 
 // settings/starting-value.ts
 function startingValueFor(key, control) {
@@ -989,8 +995,8 @@ function startingValueFor(key, control) {
       value = [];
     }
   }
-  if (isUnsetChoice(key, value) && control.type === "enum" && control.enum?.length) {
-    value = control.enum.find((choice) => !isUnsetChoice(key, choice));
+  if (isNeverImplicitChoice(key, value) && control.type === "enum" && control.enum?.length) {
+    value = control.enum.find((choice) => !isNeverImplicitChoice(key, choice));
   }
   if (key === "response_format" && typeof value === "string") {
     value = value === "" ? void 0 : { type: value };
@@ -1003,6 +1009,7 @@ export {
   CATALOGUE_KEYS,
   EMPTY_UI_GATES,
   ENUM_OFF_VALUE,
+  NEVER_IMPLICIT_AUTO_KEYS,
   PARAM_ALIASES,
   SETTINGS_CATALOGUE,
   UI_GATE_EDITABLE_KEYS,
@@ -1017,6 +1024,7 @@ export {
   extractModelDefaults,
   gateEnabled,
   getActionForMode,
+  isNeverImplicitChoice,
   isOffValue,
   isUiGateKey,
   isUnsetChoice,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/agents",
-  "version": "0.59.271",
+  "version": "0.59.273",
   "description": "Portable AI Matrx agent stream protocol, event projection, and safe result-presentation primitives.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -25,6 +25,7 @@
   "files": [
     "dist",
     "scripts/check-model-catalog-reads.mjs",
+    "context/rules-corpus.json",
     "README.md",
     "LICENSE",
     "CHANGELOG.md"
@@ -171,6 +172,7 @@
         "default": "./dist/context/react/index.cjs"
       }
     },
+    "./context/rules-corpus.json": "./context/rules-corpus.json",
     "./react": {
       "import": {
         "types": "./dist/react/index.d.ts",
@@ -518,5 +520,5 @@
       "optional": true
     }
   },
-  "gitHead": "2c48e6413332bdf7ea9f92366e3ad0e4129ddd52"
+  "gitHead": "757401d3d21eefd180f94f290b796b53904b8c15"
 }