# API Reference Blindspots

This audit captures what the public references cover today, and where they can
still mislead an operator or agent if read too literally.

## Current source of truth

- MCP runtime catalog: [mcp-tools.md](mcp-tools.md), generated from the compiled
  registry by `node scripts/export-operator-catalog.mjs`.
- Operational impact matrix: [operator-catalog.md](operator-catalog.md),
  generated by the same script.
- CLI command map: [gcp-commands.md](gcp-commands.md), maintained by hand from
  `bin/gcp.mjs`, `bin/commands/*`, and the lower-level `ghostcrab` launcher.
- Telemetry HTTP API: [openapi.yaml](openapi.yaml). This is not the MCP tool
  API.

## Blindspots found

1. `tools/list` returns the full registered tool catalog so every tool is
   directly callable on strict MCP clients. A curated subset is flagged as
   recommended defaults via the tool `title`. Use `gcp tools list`,
   `gcp tools verify`, or `ghostcrab_tool_search` for discovery metadata,
   access classes, and domain filtering.

2. Older ignored notes and archived planning material can mention historical
   tool names such as `ghostcrab_facet_tree`, `ghostcrab_query_geo`,
   `ghostcrab_marketplace`, or `ghostcrab_patch`. Those names must not be
   treated as current contract unless they also appear in the generated catalog.

3. `docs/dev/`, `docs/audit/`, and `docs/plan/` are ignored in this repository.
   They can be useful working notes, but they are not durable public reference
   surfaces. Current references must live under tracked docs such as
   `docs/reference/`, `docs/setup/`, `docs/methodology/`, or `docs/explanation/`.

4. `gcp brain artifact refresh` and MCP `ghostcrab_live_refresh` refresh one
   exact `live_answer_view__...` artifact id per call. Wildcards such as
   `live_answer_view__serenity_*` are not supported. A `405 MethodNotAllowed`
   on refresh usually means a stale backend after upgrade or a manual `GET`
   request; the CLI/MCP refresh path uses HTTP `POST`.

5. The generated MCP reference documents input argument names, required flags,
   and coarse JSON-schema types. It does not yet formalize per-tool success
   payload schemas, error code enums, pagination guarantees, or row-level table
   contracts.

6. The `access` facet is a policy hint, not a security boundary. It now marks
   `_refresh`, `_reindex`, `_delete`, and `_reset` tools as write operations, but
   callers still need host-level permission policies for Cursor, Claude, Codex,
   and other MCP clients.

7. `ghostcrab_tool_search` is discovery-oriented and limited by its `limit`
   argument. Use `gcp tools list` for a complete flat export of every registered
   tool.

8. `gcp maintenance` is an operator maintenance surface. Some launchers expose
   help and behavior at `maintenance ddl-approve` / `maintenance ddl-execute`
   rather than a broad interactive group help. Reference docs should name the
   concrete subcommands.

9. Destructive workspace maintenance exists on the lower-level `ghostcrab`
   launcher as `workspace reset` and `workspace delete`. These are not normal
   product modeling commands and should stay separated from MCP onboarding flows.

10. Backend-authoritative contracts, especially answer-artifact storage, event
   persistence, and gap/rule/diagnostic table semantics, remain owned by
   MindBrain. This repo may document consumption boundaries, but backend changes
   must be planned in the MindBrain repo first.

11. Ontology import now exists on both surfaces: MCP `ghostcrab_ontology_import`
    for agent workflows, and CLI `gcp brain ontology ...` for operator scripts.
    Do not describe `ghostcrab_remember`, `ghostcrab_upsert`,
    `ghostcrab_learn`, `ghostcrab_schema_register`, or
    `ghostcrab_graph_gap_rules_import` as ontology import paths; they write
    memory, graph instances, agent schemas, or diagnostic rules.

## Maintenance checks

Run these before publishing API-reference changes:

```bash
pnpm run build
node scripts/export-operator-catalog.mjs
pnpm run verify:mcp-tools
gcp tools list
git diff --check
```

Then search the tracked docs for stale current-contract claims:

```bash
rg -n "53 registered|12 recommended|41 extended|all 50|50 remain|12 default tools|ghostcrab_facet_tree|ghostcrab_query_geo|ghostcrab_marketplace|ghostcrab_patch|docs/dev/mcp_tools_contract" README.md INSTALL.md installations docs/reference docs/setup docs/methodology docs/explanation
```
