# Discoverable entity

> Marks an entity (chat, conversation, document, artifact, memo, playbook, tool) as searchable via the cross-history retrieval API.

`@kindgi/specs/discoverable.schema.json`, schema version 1.1.0.

Marks an entity (chat, conversation, document, artifact, memo, playbook, tool) as searchable via the cross-history retrieval API. The framework handles embedding via a configured provider; retrieval is always policy-scoped (owner / team / project / org / tenant). Deletion cascades to embeddings + retrieval caches.

- `entityId` (string, required): ID of the entity being made discoverable.

- `entityKind` (`"chat"` | `"conversation"` | `"document"` | `"artifact"` | `"memo"` | `"playbook"` | `"tool"` | `"agent"` | `"flow"` | `"note"`, required)

- `scope` ([DiscoverabilityScope](https://docs.kindgi.com/v0.1.9/reference/schemas/discoverable.md#discoverabilityscope), required)

- `tags` (array of string): Tags to filter retrieval by (e.g. 'customer:acme', 'topic:billing').

- `title` (string): Human-readable title used in search UIs.

- `summary` (string): Optional pre-computed summary used as a second-tier retrieval index (embed summaries + link to full content).

- `content` (object): Content to index. May be inline string or a blob reference. If absent, the retrieval layer derives content from the entity by kind.

- `contentRef` (string): Optional blob reference for large content. Format: 'blob://\<provider>/\<bucket>/\<key>'.

- `embeddingConfig` (object)

  - `model` (string): Embedding model id, as a registered embedding provider reports it (`describe().model`). Router picks based on tenant policy if absent.
  - `chunker` (`"turn-aware"` | `"sliding-window"` | `"recursive"` | `"semantic"`): Chunking strategy. 'turn-aware' is the correct default for chats and conversations (context-preserving); documents use 'recursive' or 'sliding-window'.
  - `chunkSize` (integer)
  - `chunkOverlap` (integer)

- `retention` (object)

  - `keepUntil` (string (date-time))
  - `keepDays` (integer)
  - `legalHold` (boolean)

- `declaredAt` (string (date-time))

## Definitions

### DiscoverabilityScope

- `tenantId` (string, required)
- `visibility` (`"owner-only"` | `"team"` | `"project"` | `"org"` | `"public"`, required): Who can retrieve this entity via search. 'owner-only' = declaring user only. 'team' = members of a specified team (added in schema-version 1.1.0). 'project' = anyone with policy access to the project. 'org' = anyone in the org with the appropriate role. 'public' = anyone in the tenant. Policy engine enforces at retrieval time regardless of this hint.
- `userId` (string): Required if visibility = 'owner-only'.
- `teamId` (string): Required if visibility = 'team'. Added in schema-version 1.1.0.
- `projectId` (string): Required if visibility = 'project'.
- `orgId` (string): Required if visibility = 'org'.
- `allowedRoles` (array of string): Additional role gate applied on top of visibility (e.g. 'admin-only', 'compliance-only').