@tpsdev-ai/flair 0.53.0 → 0.54.1

package/docs/api-reference.md

@@ -154,7 +154,8 @@ Skill-tagged Memory rows embed from `trigger` (the recall signal), not
 | GET / POST / PUT | `/WorkspaceState` | Ed25519 | Owner-only. POST stamps `agentId`; PUT rejects a mismatch. |
 | GET | `/WorkspaceLatest` | Ed25519 | Latest workspace row for the caller. |
 | GET / POST / PUT | `/OrgEvent` | Ed25519 | Any verified agent reads every event. Writes stamp `authorId`. |
-| GET | `/OrgEventCatchup` | Ed25519 | Catch-up feed for the caller. |
+| GET / POST | `/OrgEventCatchup` | Ed25519 | Catch-up feed for the caller. `since` is optional (defaults to the per-agent watermark). GET pages; POST acks `{ position }` (advance-on-ack). |
+| GET / POST | `/AgentReadPosition` | Ed25519 | Owner-only watermark (`stream`, default `org-event`). Foundation for light-comms catch-up. |
 | POST | `/OrgEventMaintenance` | Ed25519 / admin | Expire / sweep org events. |
 | POST | `/AttentionQuery` | Ed25519 | Cross-table “what touches entity E”. Entity strings: [docs/entity-vocabulary.md](entity-vocabulary.md). |
 
@@ -163,7 +164,7 @@ Skill-tagged Memory rows embed from `trigger` (the recall signal), not
 | Method | Path | Auth | Notes |
 |--------|------|------|-------|
 | GET | `/FederationInstance` | Admin Basic | Local instance identity (CLI / admin). Peers do not call this during pair. |
-| POST | `/FederationPair` | Pairing token + body-sig | Public at the Harper role gate. Handler validates token, signature, anti-replay. Fabric uses the bootstrap-user triple from `flair federation token`. |
+| POST | `/FederationPair` | Pairing token + body-sig | Public at the Harper role gate. Handler validates token, signature, anti-replay. Response includes `instance {id, publicKey}` when this hub has an Instance row; `instance` is null if it does not (flair#839). The spoke CLI must not store an empty hub key (flair#822). Fabric uses the bootstrap-user triple from `flair federation token`. |
 | POST | `/FederationSync` | Peer body-sig | Public at the role gate. Merge Memory / Soul / Agent / Relationship (and classifier-ready Message). Originator + per-record signature checks. |
 | GET | `/FederationPeers` | Admin Basic | Known peers. |
 | GET / write | `/Instance` | Read: Ed25519. Write: admin | Instance row (`flair_…` id, role hub/spoke). |
@@ -355,6 +356,7 @@ ed25519 / idp) and **Integration** (legacy platform connection).
 | **Asset** | memory.graphql | yes | Blob (`contentType`, `data`) owned by `agentId`, linked by `memoryId` |
 | **WorkspaceState** | workspace.graphql | yes | Current work (`ref`, `provider`, `phase`, `entities`) |
 | **OrgEvent** | event.graphql | yes | Org-visible event (`authorId`, `kind`, `summary`, `entities`) |
+| **AgentReadPosition** | agent.graphql | no | Per-agent watermark (`agentId`, `stream`, `position`). HTTP via `/AgentReadPosition`, not raw-table REST. |
 | **Message** | message.graphql | yes | Signed envelope (`from`, `to`, `threadId`, `seq`, `state`, `signature`) |
 | **OAuthClient** | oauth.graphql | yes | Registered OAuth clients |
 | **OAuthAuthCode** | oauth.graphql | no | Single-use codes + PKCE |

package/docs/deploying-on-fabric.md

@@ -241,7 +241,9 @@ Provision once, from one place, before serving multi-region traffic: step 2's
 | `flair fleet verify --target <url>` | health, auth, version across origin + Flair peers |
 | `flair federation status\|verify\|reachability --target <url>` | peer table, sync recency, probes |
 
-`fleet verify` exit codes: 1 origin failed, 2 peer version skew, 3 peer unverifiable.
+`fleet verify` exit codes: 1 origin failed, 2 reachable peer diverged (wrong version), 3 reachable peer unreachable/auth-failed. Unverifiable peers (no endpoint on file) warn and exit 0.
+
+`federation verify` is a different question (did this canary land). Exit 0 includes unverifiable peers (401/403, unreachable); exit 1 is a reachable peer missing the canary. It pushes before probing so a spoke with no sync daemon can still check.
 
 > **A credential mismatch renders as an empty section, not an error.** `flair status`
 > reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent
@@ -299,17 +301,16 @@ without this re-flip will appear healthy (`/Health` green) while its MCP tools a
 dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
 runbook.
 
-### Known hazard: unbounded npm cache
+### npm cache on the node
 
-**Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** Every deploy runs a
-server-side `npm install` using the node's default cache. npm never evicts it, so it
-grows until it fills the quota.
+`flair deploy` and `flair upgrade --target` pass Harper an `install_command` that runs
+`npm install --cache <tmp>` and deletes that directory when the install finishes. The
+node's `~/.npm/_cacache` is no longer the install cache, so repeated deploys do not
+accumulate tarballs ([flair#886](https://github.com/tpsdev-ai/flair/issues/886)).
 
-No in-product mitigation: no cache flag, no alternate location, no cleanup. One install
-per deploy bounds the *rate*, not the total. Harper consults `install_command` only when
-`node_modules` is absent and `deploy_component` has no force-reinstall option, so the
-obvious fix isn't available — and clearing the cache needs node access this shape
-doesn't give you.
+Harper still consults `install_command` only when `node_modules` is absent — that is
+exactly when a fresh extract runs the install, which is every deploy (Harper replaces
+the component directory). There is nothing for an operator to clean.
 
 ### Backup and rollback
 

package/docs/deployment.md

@@ -194,6 +194,7 @@ These are read by the Harper process at boot (same places as the table above: la
 | Variable | Default | What it does |
 |----------|---------|--------------|
 | `FLAIR_EMBED_THREADS` | `max(1, availableParallelism() − 1)` | CPU threads for in-process embedding (harper-fabric-embeddings / llama.cpp). Host-aware so a 4-core box does not inherit HFE's fixed 6, and an 8-vCPU ingest host is not stuck at 6 idle cores. One core is left for Harper's event loop and the OS. `availableParallelism()` respects a container CPU quota. Set a positive integer to pin. Invalid values fall back to the default. |
+| `FLAIR_EMBED_GPU_LAYERS` | unset (HFE default `0`, CPU only) | Layers to offload to the GPU. **Unset omits the field** so harper-fabric-embeddings keeps its own default of 0. This is a pin for measurement (the ingest-throughput bench, flair#1436), not a new product default — #1437 is the detect-and-default decision. `0` = CPU; `99` = full offload (Metal on mac-arm64). Invalid values fall through to omit. |
 | `FLAIR_HYBRID_RETRIEVAL` | `true` | Hybrid BM25 + vector retrieval. Set `false` / `0` / `off` to revert to the legacy HNSW + keyword-bump path. |
 | `FLAIR_MODELS_DIR` | `<data-dir>/models` | Directory the embedding GGUF is loaded from (and downloaded into on first boot). Point this at a pre-seeded directory to skip the HuggingFace download; see [troubleshooting.md](troubleshooting.md). |
 
@@ -216,6 +217,7 @@ Always backup before upgrades.
 ## Uninstall
 
 ```bash
-flair uninstall   # stops server, removes ~/.flair/, removes launchd/systemd service
+flair uninstall           # stop the server and remove the launchd/systemd service; keep data and keys
+flair uninstall --purge   # also remove ~/.flair (data, keys, secrets), schedulers, and client wiring
 npm uninstall -g @tpsdev-ai/flair
 ```

package/docs/federation.md

@@ -120,6 +120,24 @@ knob. The first sync runs immediately on enable.
 `flair federation watch` is unchanged and still the right tool for an
 interactive "watch it sync while I debug" session.
 
+### Did the canary actually land?
+
+`flair federation verify` writes a tagged memory, **pushes it** (so a
+freshly paired spoke with no sync daemon can still pass), then probes each
+peer. It uses the same couldn't-check-≠-failed split as `flair fleet verify`
+(flair#988 / #823):
+
+| What the probe saw | Verdict | Exit |
+|---|---|---|
+| Canary found | OK | 0 |
+| HTTP 401/403, unreachable, or no endpoint | UNVERIFIABLE (warning) | 0 |
+| Reachable peer answered 200 without the canary after a successful push | FAIL | 1 |
+| Revoked peer | UNVERIFIABLE (warning; not probed) | 0 |
+
+A 401 is "could not authenticate to that peer," not "sync failed." Do not
+treat unverifiable as a pass that hides a reachable peer on the wrong side
+of the canary.
+
 **Credentials.** The scheduler never writes a password into a unit file. It
 stores the *path* given to `--admin-pass-file` (defaulting to
 `~/.flair/admin-pass` when that exists) and the CLI reads the file at run time,
@@ -197,6 +215,7 @@ Records with `updatedAt` more than 5 minutes in the future are rejected. This pr
 | `flair federation sync disable [--remove-shim]` | Remove the scheduled sync driver |
 | `flair federation sync status` | Show whether the driver is installed and genuinely active |
 | `flair federation watch [--interval <s>]` | Run sync in a foreground loop for an interactive session (default 30s) |
+| `flair federation verify [--wait <s>] [--admin-pass <pass>]` | Write a canary, push it, and check each peer. Flag/file admin credentials authenticate the admin-gated peer listing. 401/403, unreachable, and revoked are UNVERIFIABLE (warning, exit 0); a reachable peer missing the canary still FAILs (exit 1). |
 | `flair federation reachability` | Probe local instance + each paired peer (read-only) |
 | `flair federation token [--ttl <min>]` | Generate a one-time pairing token triple (hub only) |
 

package/docs/hosted-on-fabric.md

@@ -155,7 +155,7 @@ flair status --target https://<cluster>.<org>.harperfabric.com
 flair fleet verify --target https://<cluster>.<org>.harperfabric.com
 ```
 
-`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all verified, 1 = origin failed, 2 = peer version skew, 3 = peer unverifiable.
+`fleet verify` checks health, auth, and version across the origin node plus every Flair federation peer on file. Exit codes: 0 = all probed nodes verified (unverifiable peers warn, do not fail), 1 = origin failed, 2 = reachable peer diverged, 3 = reachable peer unreachable/auth-failed.
 
 > **A credential mismatch renders as an empty section.** `flair status` reads `/HealthDetail` with `FLAIR_ADMIN_PASS` / `HDB_ADMIN_PASSWORD` / a pinned agent key — **not** the `FABRIC_*` credentials. On failure it renders blank.
 
@@ -241,9 +241,9 @@ Fabric gives you N regional nodes running one component — **not** N Flair inst
 
 `flair status` reports usage for two directories: no free space, no total, no quota. An instance can hit its quota with nothing saying so. The one indirect signal is a migration halting for space.
 
-### Unbounded npm cache
+### npm cache is ephemeral per deploy
 
-Every deploy runs a server-side `npm install` using the node's default cache. npm never evicts it, so it grows until it fills the quota. There is no cache flag, alternate location, or cleanup option. [flair#886](https://github.com/tpsdev-ai/flair/issues/886).
+`flair deploy` / `flair upgrade --target` run the node's `npm install` against a temporary cache and delete it afterwards, so hub quota no longer grows with every install ([flair#886](https://github.com/tpsdev-ai/flair/issues/886)).
 
 ---
 

package/docs/quickstart.md

@@ -202,7 +202,8 @@ Soul entries and relevant memories, in one block sized to a token budget. Paste
 flair stop              # stop the service, keep data
 flair restart           # restart
 flair uninstall         # remove the service, keep data and keys
-flair uninstall --purge # remove everything, including data and keys
+flair uninstall --purge # remove data, keys, secrets, schedulers, and client wiring
+                        # (the npm package is left; `npm uninstall -g @tpsdev-ai/flair`)
 ```
 
 All reversible. Your memories aren't locked in.

package/docs/releasing.md

@@ -1,13 +1,15 @@
 # Releasing Flair
 
-Flair publishes eight workspace packages to npm under `@tpsdev-ai/*`. Releases are
+Flair publishes nine workspace packages to npm under `@tpsdev-ai/*`. Releases are
 **tokenless** and **staged**: CI authenticates to npm with a short-lived OIDC token
 (no `NPM_TOKEN` lives anywhere) and submits each package to npm's **staging** area.
 A maintainer then approves the staged tarballs on npmjs.com with 2FA to make them live.
 
 > `flair-bench` is version-bumped and tagged in lockstep with the other 7, and stages in
 > its own step in CI for [historical reasons](#flair-bench-bootstrap-one-time-done). That
-> step is no longer allowed to fail: all eight packages must stage for a release to pass.
+> step is no longer allowed to fail: every already-published package must stage
+> for a release to pass. `@tpsdev-ai/flair-tool-descriptors` is the one
+> first-publish exception until an npm org owner bootstraps it.
 
 ```
  merge release PR ──▶ push tag v0.11.0 ──▶ CI stages all packages ──▶ npm staging
@@ -145,11 +147,17 @@ Leave `npm publish` **unchecked** under allowed actions. This structurally preve
 CI/OIDC identity from publishing anything live directly — the only path to live is the
 human 2FA approval of a staged package.
 
-Packages: `flair-client`, `flair-mcp`, `flair`, `openclaw-flair`, `pi-flair`,
-`n8n-nodes-flair`, `langgraph-flair`, `flair-bench`.
-
-> A package must already exist on npm before a trusted publisher can be added — all
-> eight already do. This account-level config can only be done by an npm org owner.
+Packages: `flair-client`, `flair-tool-descriptors`, `flair-mcp`, `flair`,
+`openclaw-flair`, `pi-flair`, `n8n-nodes-flair`, `langgraph-flair`, `flair-bench`.
+
+> A package must already exist on npm before a trusted publisher can be added.
+> `@tpsdev-ai/flair-tool-descriptors` (flair#1580) is the next first-publish:
+> stage it with the dedicated continue-on-error step, then an npm org owner
+> publishes once and registers its Trusted Publisher (same playbook as
+> `flair-bench` below). Until that exists on the registry, `@tpsdev-ai/flair`
+> and `@tpsdev-ai/flair-mcp` tarballs bundle it (`bundleDependencies` +
+> `scripts/materialize-bundled-descriptors.mjs`) so `npm install` of those
+> tarballs does not 404.
 
 ### `flair-bench` bootstrap (one-time, done)
 

package/docs/spoke-bringup.md

@@ -138,8 +138,8 @@ The `--admin-pass` is required so the CLI can write the hub as a local `Peer` re
 
 1. The spoke POSTs a signed pairing request to the hub's `/FederationPair` endpoint.
 2. The bootstrap user authenticates at the Harper platform layer (works on standalone and Fabric deployments alike).
-3. The hub validates the one-time token, verifies the Ed25519 signature, and creates a `Peer` record.
-4. The spoke writes a `Peer` record pointing to the hub so sync knows where to push.
+3. The hub validates the one-time token, verifies the Ed25519 signature, and creates a `Peer` record. The response includes the hub's `instance {id, publicKey}` when the hub has a FederationInstance row.
+4. The spoke writes a `Peer` record pointing to the hub so sync knows where to push. A missing hub `publicKey` is an error, never an empty string. That does not create the hub's Instance row.
 
 ---
 
@@ -156,13 +156,18 @@ Syncing to hub: <hub-instance-id>...
 ✅ Synced 0 records (0 skipped) in 45ms
 ```
 
-Then verify reachability across the federation:
+Then verify the pairing. `federation verify` pushes the canary itself — you
+do not need the systemd timer from §7 first:
 
 ```bash
+flair federation verify --admin-pass "$FLAIR_ADMIN_PASS"
 flair federation reachability
 ```
 
-Both local and hub peer should report `OK`.
+`verify` writes a tagged memory, syncs it, and checks each peer. HTTP 401/403,
+an unreachable peer, or a revoked leftover row is UNVERIFIABLE (a warning),
+not FAIL. A reachable peer that is missing the canary still fails.
+`reachability` should report `OK` for local and the hub.
 
 ---
 
@@ -290,7 +295,7 @@ flair federation pair https://fabric-node.example.com:19926/<instance> \
 | Hub: mint token | `flair federation token --admin-pass <pass> > triple.json` |
 | Spoke: pair | `flair federation pair <hub-url> --token-from ./triple.json --admin-pass <pass>` |
 | Spoke: sync | `flair federation sync --admin-pass <pass>` |
-| Spoke: verify | `flair federation reachability` |
+| Spoke: verify | `flair federation verify --admin-pass <pass>` then `flair federation reachability` |
 | Watch loop | `flair federation watch --interval 30` |
 
 ---

package/docs/standalone-local.md

@@ -57,7 +57,8 @@ flair status        # check everything is working
 flair stop          # stop the service (keeps data)
 flair restart       # restart the service
 flair uninstall     # remove the service (keeps data + keys)
-flair uninstall --purge   # remove everything including data and keys
+flair uninstall --purge   # remove data, keys, secrets, schedulers, and client wiring
+                          # (the npm package is left; `npm uninstall -g @tpsdev-ai/flair`)
 ```
 
 On macOS the service is a launchd plist at `~/Library/LaunchAgents/ai.tpsdev.flair.plist`. On Linux it is a systemd unit at `~/.config/systemd/user/flair.service`. Both auto-start on login/boot and restart on crash.
@@ -108,6 +109,7 @@ logging:
 | `FLAIR_KEY_PASSPHRASE` | Passphrase for AES-256-GCM encryption of federation private-key seeds. | Set explicitly for production federation deployments. |
 | `FLAIR_URL` | Override the Flair base URL for CLI commands (points to a remote instance). | When connecting from a different machine. |
 | `FLAIR_EMBED_THREADS` | CPU threads for in-process embedding. Default is `max(1, availableParallelism() − 1)` — host-aware, one core left for Harper. | Pin a positive integer on a dedicated ingest host, or when the default leaves cores idle / oversubscribed. See [deployment.md](deployment.md#performance-related-environment-variables). |
+| `FLAIR_EMBED_GPU_LAYERS` | GPU layers to offload. Unset leaves HFE's default of 0 (CPU only) — this is a pin, not a new default. | Only to measure Metal offload (`99`) or pin CPU (`0`). See [deployment.md](deployment.md#performance-related-environment-variables) and #1437. |
 | `FLAIR_HYBRID_RETRIEVAL` | Hybrid BM25 + vector retrieval (default on). | Set `false` to revert to HNSW-only. |
 | `FLAIR_MODELS_DIR` | Directory the embedding GGUF is loaded from. | When the model lives outside `<data-dir>/models`. |
 

package/docs/upgrade.md

@@ -39,7 +39,11 @@ flair doctor
 `flair upgrade` checks and upgrades the npm-global packages (`@tpsdev-ai/flair`,
 `@tpsdev-ai/flair-mcp`) and, if present, the `openclaw-flair` plugin (via
 `openclaw plugins install --force --pin`, not `npm install -g` — it needs OpenClaw's
-own plugin loader). Pass `--all` to also see `flair-client` (normally hidden as a
+own plugin loader). It also refreshes every `@tpsdev-ai/flair-mcp@<version>` pin
+it previously wrote — MCP server entries **and** SessionStart hook commands —
+for each already-wired client (`~/.claude.json`, `~/.claude/settings.json`,
+`~/.codex/config.toml`, `~/.codex/hooks.json`, and the other auto-wired clients).
+Pass `--all` to also see `flair-client` (normally hidden as a
 transitive dependency). **Other integrations upgrade in their own ecosystem, not via
 `flair upgrade`:** `pi-flair` (pi's plugin manager), `langgraph-flair` / `hermes-flair`
 (pip / your Python package manager), `n8n-nodes-flair` (n8n's Community Nodes UI).
@@ -264,6 +268,20 @@ flair upgrade --target https://<fabric-node>/<instance-name> \
   --fabric-user <admin> --fabric-password <pass>
 ```
 
+### Post-deploy embedding-stamp verify
+
+As of flair#1073, both `flair deploy` and `flair upgrade --target` poll
+authenticated `/HealthDetail` after the served-API check until the
+`embedding-stamp` migration has converged — every real embedding is in the
+current `+searchprefix` space, and the migration is not halted or still
+running. Route verify only proves the component is serving; it does not
+prove the boot-keyed re-embed actually finished. A Fabric instance that
+stayed split for days after 0.30.0 was the incident this closes.
+
+`--no-verify` skips this check together with the served-API check.
+`--verify-timeout` covers both. Token-only auth skips the stamp check
+(it needs Basic admin to read `/HealthDetail`) and says so.
+
 ### Post-deploy fleet verify
 
 As of flair#636, both `flair deploy` and `flair upgrade --target` automatically run a
@@ -287,10 +305,10 @@ Exit codes:
 
 | Code | Meaning |
 |------|---------|
-| 0 | All nodes verified: healthy, authenticated, and version-matched |
+| 0 | All probed nodes verified. Unverifiable peers (no endpoint on file) are listed as a warning and do not fail |
 | 1 | Origin failed (unreachable, unauthenticated, or wrong version) |
-| 2 | Origin OK, but a reachable peer is running a different version (skew) |
-| 3 | Origin OK, no skew among reachable peers, but a peer couldn't be verified at all (unreachable, auth rejected, or no endpoint on file) |
+| 2 | A reachable node diverged (wrong version) — NOT converged |
+| 3 | A reachable peer was unreachable or rejected auth (not unverifiable) |
 
 **What "peer" means here — read before trusting a green sweep:** this checks
 *Flair's own* federation peer table, not Harper Fabric's own cluster-replication
@@ -300,8 +318,9 @@ in this cluster and are they in sync") is harper-pro-only and unavailable in the
 Fabric's own replication topology, on the origin or anywhere else. A Fabric replica
 that was never separately paired as a Flair federation peer (`flair federation pair`)
 is invisible to this sweep: `0 peers known` means "0 peers on file," never "0 peers
-exist." A peer with no usable endpoint is reported `unverifiable` — never silently
-dropped, never shown green. The sweep also needs Basic-auth credentials
+exist." A peer with no usable endpoint is reported `unverifiable` — listed and
+warned, never shown green, and does not fail the run (a reachable peer on the
+wrong version still does). The sweep also needs Basic-auth credentials
 (`FABRIC_USER`/`FABRIC_PASSWORD` env, or the discouraged inline
 `--fabric-user`/`--fabric-password`) to authenticate each peer probe; a token-only
 (`--fabric-token`) deploy skips it with a note instead of a silent no-op.

package/node_modules/@tpsdev-ai/flair-tool-descriptors/LICENSE

@@ -0,0 +1,19 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   Copyright 2026 TPS Dev AI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/node_modules/@tpsdev-ai/flair-tool-descriptors/README.md

@@ -0,0 +1,22 @@
+# @tpsdev-ai/flair-tool-descriptors
+
+Transport-agnostic MCP tool descriptors for [Flair](https://tps.dev/#flair).
+
+This package is **pure data and types**: tool name, description, JSON Schema
+`inputSchema`, output shape, and reviewed surface flags. It imports neither
+Harper nor FlairClient. The Flair server binds each native descriptor to its
+Harper implementation; `@tpsdev-ai/flair-mcp` binds each stdio descriptor to a
+FlairClient HTTP call. Both tool sets are derived from this list, so a new
+descriptor appears on every listed surface with zero hand-wiring (flair#1580).
+
+## Install
+
+```bash
+npm install @tpsdev-ai/flair-tool-descriptors
+```
+
+## Surfaces
+
+`native` and `stdio` default to true. Set either to `false` for a reviewed
+one-sided tool (`attention` is native-only; `relationship_store` is
+stdio-only). The #1578 exemption list is derived from those flags.

package/node_modules/@tpsdev-ai/flair-tool-descriptors/dist/index.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Transport-agnostic MCP tool descriptors (flair#1580).
+ *
+ * Pure data + types: name, description, inputSchema, output shape, and
+ * reviewed surface flags. No Harper, no FlairClient, no Zod, no HTTP.
+ *
+ * The server TOOLS registry binds each native descriptor to its Harper impl.
+ * The flair-mcp stdio adapter binds each stdio descriptor to a FlairClient
+ * call. Both tool sets are DERIVED from this list — a new descriptor appears
+ * on every surface that lists it, with zero hand-wiring.
+ */
+/** JSON Schema object used as MCP tools/list inputSchema. */
+export interface JsonSchemaObject {
+    type: "object";
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+}
+export interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    enum?: string[];
+    items?: {
+        type?: string;
+    };
+    default?: unknown;
+}
+/** MCP tool descriptor as returned by tools/list. */
+export interface McpToolDef {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    annotations?: Record<string, unknown>;
+}
+/**
+ * One MCP-facing tool. `native` / `stdio` default true — omit both and the
+ * tool appears on every surface. Set false for a reviewed one-sided tool
+ * (the #1578 exemption list is derived from these flags).
+ */
+export interface ToolDescriptor {
+    name: string;
+    description: string;
+    inputSchema: JsonSchemaObject;
+    /** One-line output shape (MCP metadata). Native conformance contracts pin this as `summary`. */
+    outputShape: string;
+    annotations?: Record<string, unknown>;
+    /** When false, native /mcp does not bind this tool. Default true. */
+    native?: boolean;
+    /** When false, the stdio adapter does not bind this tool. Default true. */
+    stdio?: boolean;
+    /** Stdio-only description when the HTTP path differs from native /mcp policy. */
+    stdioDescription?: string;
+    /** Properties advertised on native /mcp only (reviewed, e.g. flair#1579). */
+    stdioOmitProperties?: readonly string[];
+    /** Properties advertised on the stdio adapter only (reviewed). */
+    stdioExtraProperties?: Record<string, JsonSchemaProperty>;
+}
+export declare function isNativeTool(d: ToolDescriptor): boolean;
+export declare function isStdioTool(d: ToolDescriptor): boolean;
+export declare function toMcpToolDef(d: ToolDescriptor): McpToolDef;
+/** Native tools/list def, minus reviewed stdio-only omissions. */
+export declare function toStdioMcpToolDef(d: ToolDescriptor): McpToolDef;
+export declare function descriptorNames(descriptors: readonly ToolDescriptor[]): string[];
+export declare const TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+export declare const NATIVE_TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+export declare const STDIO_TOOL_DESCRIPTORS: readonly ToolDescriptor[];
+/** Derived #1578 exemption list — one-sided by construction, not hand-synced. */
+export declare const SURFACE_EXEMPTIONS: {
+    readonly registryOnly: string[];
+    readonly adapterOnly: string[];
+};