# WarmHub

> A platform for storing and versioning structured data as named, schema-validated records.
>
> Every published page concatenated into one file: /llms-full.txt

## Documentation Sets


- [Complete documentation](/llms-full.txt): every published page concatenated into a single file

- [Evaluating WarmHub](/evaluate.md): evaluation guide for agents deciding whether WarmHub fits a project — includes non-fit cases

## Curated Pages (subset; see /llms-full.txt for the complete documentation)


### Get Started

- [What is WarmHub?](/get-started/what-is-warmhub.md): Knowledge platform for AI agents — versioned, structured, auditable
- [Quickstart](/get-started/quickstart.md): Connect to WarmHub via MCP, SDK, or CLI and run your first query — under 5 minutes.
- [Core Concepts](/get-started/core-concepts.md): The mental model behind WarmHub — orgs, repos, shapes, things, assertions, and writes
- [Principles & Patterns](/get-started/principles-and-patterns.md): Modeling guidance has moved to the Data Modeling section.

### Data Modeling

- [Modeling Overview](/data-modeling/overview.md): How to think about modeling with WarmHub — core principles that guide every design decision.
- [Shapes](/data-modeling/shapes.md): Define schemas for things and assertions with typed fields and versioning.
- [Content Shape (built-in)](/data-modeling/content-shape.md): The built-in Content shape provides three well-known instance names for conventional repo markdown — Readme, Agents, and LlmsTxt.
- [Things](/data-modeling/things.md): Named, versioned entities — the core data objects in WarmHub.
- [Naming as Navigation](/data-modeling/naming-as-navigation.md): How hierarchical thing names create a navigable knowledge structure — and why this matters for agents.
- [Assertions](/data-modeling/assertions.md): Claims about things — with immutable targets and version pinning.
- [Wrefs](/data-modeling/wrefs.md): How to address any entity in WarmHub — wrefs are the references that fields like committer and about use to point at other entities.
- [Collections](/data-modeling/collections.md): Pair, Triple, Set, and List — built-in collection shapes for grouping things.
- [Retract, Rename & Schema Changes](/data-modeling/retract-rename-schema-changes.md): What happens to your data — and everything pointing at it — when you retract, rename, or change a shape.
- [Patterns & Recipes](/data-modeling/patterns.md): Common modeling patterns for agent memory, multi-agent collaboration, and evolving understanding.

### Writes

- [Writes](/writes/overview.md): How WarmHub turns operations into versioned graph state.
- [Operations](/writes/operations.md): Add, revise, and retract operations for shapes, things, and assertions — plus inline collection syntax.
- [Write History](/writes/history.md): Auditing changes — per-thing version trails replace the commit log.

### Queries

- [Queries](/queries/overview.md): Read data from WarmHub — HEAD snapshots, targeted lookups, search, and history.
- [HEAD Queries](/queries/head.md): Get a fast snapshot of the current active state of a repository.
- [Filtering and Lookup](/queries/filtering.md): Targeted queries — by wref, shape, about target, kind, version history, and text search.

### Agent Integration

- [Why Agent-Native?](/agent-integration/why-agent-native.md): Why WarmHub is agent-native and how AI agents connect.
- [MCP Tool Walkthrough](/agent-integration/mcp-tool-walkthrough.md): Bootstrap, read, write, and query a WarmHub repo through the MCP tool sequence.
- [MCP Server](/agent-integration/mcp-server.md): Endpoints, protocol details, and configuration for the WarmHub MCP server.
- [MCP Tools Reference](/agent-integration/mcp-tools-reference.md): Complete catalog of all MCP tools with parameters and descriptions.
- [Agent Context (wh prime)](/agent-integration/wh-prime.md): Context bootstrapping for AI agents — how to run it, its flags, output format, and token budget.

### CLI Reference

- [CLI Overview](/cli-reference/overview.md): Install the wh CLI, configure your environment, and learn the command patterns.
- [Commands](/cli-reference/commands.md): All CLI commands organized by domain — org, repo, shape, thing, assertion, commit, use, init, doctor, sub, auth, token, credential, component, prime, channel, notifications.
- [Write Submit Deep-Dive](/cli-reference/write-submit-deep-dive.md): All the ways to submit operations — --ops JSON, --file, --stream, and shorthand flags.

### SDK

- [SDK Overview](/sdk/overview.md): Install the TypeScript SDK, create a client, and browse the available SDK surfaces.
- [Client Surfaces](/sdk/client.md): Narrative map of the WarmHubClient surfaces, with links to the generated TypeDoc reference for method signatures and per-method details.
- [Write Methods](/sdk/write-methods.md): Choose between client.commit.apply and OperationBuilder for SDK writes, and understand operation inputs and results.
- [Transient Retry](/sdk/transient-retry.md): Retry and partial-submission behavior for SDK commit writes and OperationBuilder submissions.
- [Component Identity](/sdk/component-identity.md): How componentId attribution works across SDK commit writes and subscription creation.
- [Read Semantics](/sdk/read-semantics.md): SDK read filters, glob match behavior, reference queries, search modes, batch reads, and anonymous pagination limits.
- [Repo Statistics](/sdk/repo-stats.md): Choose between repo list metadata, repository stats, batch stats, configure stats, and shape instance counts.

### SDK Reference

- [Class: WarmHubClient](/sdk-reference/classes/warmhubclient.md): Create a WarmHub client.
- [Class: AllStreamOperationsFailedError](/sdk-reference/classes/allstreamoperationsfailederror.md): Error raised when the stream append path completed deterministically but every submitted operation failed.
- [Class: CliCallVerificationError](/sdk-reference/classes/clicallverificationerror.md): [`CliCallVerificationFailureReason`](/sdk-reference/type-aliases/clicallverificationfailurereason/)
- [Class: OperationBuilder](/sdk-reference/classes/operationbuilder.md): Fluent builder for composing, validating, and submitting WarmHub commit operations.
- [Class: PartialStreamSubmissionError](/sdk-reference/classes/partialstreamsubmissionerror.md): Error raised when a streamed commit submission fails after an ambiguous or partial append.
- [Class: WarmHubError](/sdk-reference/classes/warmhuberror.md): Normalized error shape thrown by the WarmHub SDK.
- [Interface: AddOp](/sdk-reference/interfaces/addop.md): Builder add operation for shapes, things, assertions, and collections.
- [Interface: ReviseOp](/sdk-reference/interfaces/reviseop.md): Builder revise operation.
- [Interface: RetractOp](/sdk-reference/interfaces/retractop.md): Builder retract operation.
- [Interface: WarmHubClientOptions](/sdk-reference/interfaces/warmhubclientoptions.md): Options for constructing a `WarmHubClient`.
- [Interface: AddOperation](/sdk-reference/interfaces/addoperation.md): Add operation accepted by `client.commit.apply`. Use this shape to create new shapes, things, assertions, or collections in a single commit.
- [Interface: OperationBuilderOptions](/sdk-reference/interfaces/operationbuilderoptions.md): Options for constructing an `OperationBuilder`.
- [Interface: RetractOperation](/sdk-reference/interfaces/retractoperation.md): Retract operation accepted by `client.commit.apply`. Marks the target as retracted in a new version; prior versions remain queryable by history.
- [Interface: ReviseOperation](/sdk-reference/interfaces/reviseoperation.md): Revise operation accepted by `client.commit.apply`. Replaces the shape-validated data on an existing shape, thing, or assertion and creates a new version.
- [Interface: ValidationDiagnostic](/sdk-reference/interfaces/validationdiagnostic.md): Client-side validation diagnostic returned by `OperationBuilder.validate`.
- [Interface: ValidationResult](/sdk-reference/interfaces/validationresult.md): Result returned by `OperationBuilder.validate`.
- [Interface: VerifiedCliCall](/sdk-reference/interfaces/verifiedclicall.md): HTTP method the request arrived on.
- [Type: CliCallSecrets](/sdk-reference/type-aliases/clicallsecrets.md): Secret bundle accepted by `verifyCliCall`. Pass your worker's full env (e.g. `c.env`) or just the CLI_* subset — the verifier looks only at the keys it knows.
- [Type: CliCallVerificationFailureReason](/sdk-reference/type-aliases/clicallverificationfailurereason.md)
- [Type: CountOptions](/sdk-reference/type-aliases/countoptions.md): Options for `client.thing.count`. Same filter set as [FilterOptions](/sdk-reference/type-aliases/filteroptions/); pagination fields (`limit`, `cursor`) are ignored.
- [Type: ErrorKind](/sdk-reference/type-aliases/errorkind.md): Stable SDK error kinds plus backend domain codes that pass through as strings.
- [Type: FilterOptions](/sdk-reference/type-aliases/filteroptions.md): Filter to records of this shape name (for example `Player`).
- [Type: GlobalSearchOptions](/sdk-reference/type-aliases/globalsearchoptions.md): ***
- [Type: GlobalSearchResultItem](/sdk-reference/type-aliases/globalsearchresultitem.md): A cross-org search hit (repo or component). GH-4383.
- [Type: IndexedFieldEntry](/sdk-reference/type-aliases/indexedfieldentry.md): A single entry in the indexed-fields report.
- [Type: IndexedFieldsReport](/sdk-reference/type-aliases/indexedfieldsreport.md): Report of all indexed fields for a repo, grouped by state.
- [Type: LiveHandle](/sdk-reference/type-aliases/livehandle.md): Handle returned by live subscription helpers.
- [Type: LiveRepoEvent](/sdk-reference/type-aliases/liverepoevent.md): Raw SSE invalidation event from a watched repo.
- [Type: Operation](/sdk-reference/type-aliases/operation.md): Commit operation accepted by `client.commit.apply`. Discriminated union over [AddOperation](/sdk-reference/interfaces/addoperation/), [ReviseOperation](/sdk-reference/interfaces/reviseoperation/), and [RetractOperation](/sdk-reference/interfaces/retractoperation/), keyed on `operation`.
- [Type: OperationBuilderOp](/sdk-reference/type-aliases/operationbuilderop.md): Operation queued by `OperationBuilder`.
- [Type: OperationSubmitResult](/sdk-reference/type-aliases/operationsubmitresult.md): Result returned by successful commit submissions.
- [Type: OrgRole](/sdk-reference/type-aliases/orgrole.md): Caller's role within an organization. Returned by `client.org.getCallerRole`, carried as `callerRole` on `client.org.listMembers` results, and accepted by `client.org.changeMemberRole` to set a member's role (only owners may promote to or demote from `'owner'`; the last owner cannot be demoted). Mirrors `orgRoleSchema` in `@warmhub/backend`; the static check below blocks any drift between this literal and the generated copy.
- [Type: Page](/sdk-reference/type-aliases/page.md): Cursor page envelope used by paginated SDK methods.
- [Type: RefsOptions](/sdk-reference/type-aliases/refsoptions.md): Options for `client.thing.refs` — wref-field reverse and forward lookups.
- [Type: RenameResult](/sdk-reference/type-aliases/renameresult.md): Result returned by in-place rename mutations: `client.shape.rename` and `client.thing.rename`. A rename patches the identity field directly and preserves the existing version history; no new version is created. The `renamed: true` discriminator distinguishes the success shape from a rejected request (which throws `WarmHubError`).
- [Type: RepoInfo](/sdk-reference/type-aliases/repoinfo.md): Repository metadata returned by `client.repo.get`, `create`, `setDescription`, `setDisplayName`, `setVisibility`, `rename`, `update`, `archive`, and `unarchive`.
- [Type: RetryPolicyOptions](/sdk-reference/type-aliases/retrypolicyoptions.md): Caller-facing knobs for the SDK's auto-idempotency retry on transient first-chunk failures.
- [Type: SearchOptions](/sdk-reference/type-aliases/searchoptions.md): Options for `client.thing.search`. Search does not support field-value `where` predicates in v1; use `thing.query` for typed structured filtering.
- [Type: ShapeFields](/sdk-reference/type-aliases/shapefields.md): Shape field definitions — the value side of a shape's data.fields
- [Type: ShapeValidatorResult](/sdk-reference/type-aliases/shapevalidatorresult.md)
- [Type: StreamAppendInput](/sdk-reference/type-aliases/streamappendinput.md): Low-level stream append input accepted by `client.stream.append`.
- [Type: StreamAppendResult](/sdk-reference/type-aliases/streamappendresult.md): Low-level stream append result returned by `client.stream.append`.
- [Type: StreamContinuationState](/sdk-reference/type-aliases/streamcontinuationstate.md): Continuation state for caller-managed streamed commit submissions.
- [Type: SubscriptionCompatCreateInput](/sdk-reference/type-aliases/subscriptioncompatcreateinput.md): Input shape for `client.subscription.create`. Webhook subscriptions require `filterJson` and `webhookUrl`, and must identify a shape via `shapeName` or `filterJson.shape` (or a shape-lifecycle `{ kind: 'shape' }` filter). The cron kind was retired from public surfaces; legacy cron rows remain readable via SubscriptionInfo.
- [Type: SubscriptionCompatUpdateInput](/sdk-reference/type-aliases/subscriptioncompatupdateinput.md): Input shape for `client.subscription.update`. `orgName`, `repoName`, and `name` identify the subscription; all other fields are optional and only the ones you provide get patched.
- [Type: ThingDetail](/sdk-reference/type-aliases/thingdetail.md): Full record shape for a single Thing returned by single-record SDK reads. Returned by `client.thing.get` and `client.thing.resolve`, the `items[]` element type for `client.thing.getMany`, the base of `client.thing.graph`, and the return of `client.repo.getReadme` and `getAgents` (nullable). Identity fields (`wref`, `name`, `kind`, `shape`/`shapeName`) are always populated. `data` carries the shape-validated payload when present; `active` is `false` for retracted reads. The `[key: string]: unknown` index signature is a forward-compat affordance — current callers should rely on the named fields. Note: list reads — `client.thing.head`, `query`, and `search` — return a thinner row shape (no `shape`, `validatedShape`, or `committerWref`); use `client.thing.get` to hydrate a full `ThingDetail` from a list result.
- [Type: ThingGetWithLease](/sdk-reference/type-aliases/thinggetwithlease.md): Returned by `client.thing.getWithLease`. Everything `client.thing.get` returns, plus a `lease` block (ThingGetWithLease.lease) the holder echoes back on the subsequent `revise`/`retract` (`leaseId`) and on `client.thing.releaseLease`. The `version` and the `lease` come from a single backend snapshot, so the holder knows exactly which version it leased.
- [Type: ThingMetadata](/sdk-reference/type-aliases/thingmetadata.md): Stable identity and creation timestamps embedded on every thing-like read result. `durableId` is a self-routing, self-verifying token (Crockford base32 over `repo_id + things.id + CRC-32C`) that remains identical before and after rename and across revise/retract. `thingCreatedAt` records the thing's birth date (stable across all mutations); `versionCreatedAt` is the timestamp of the current version (advances on each revise). History rows carry only `durableId` and `thingCreatedAt` — omit `versionCreatedAt`.
- [Type: UndeclaredFieldsWarning](/sdk-reference/type-aliases/undeclaredfieldswarning.md): ***
- [Type: WarmHubErrorDetails](/sdk-reference/type-aliases/warmhuberrordetails.md): Structured backend error details surfaced on `data.warmhub.details`. Derived from the generated wire type so it stays in lockstep with the backend's `WarmHubError.details` union. Branch on `details.reason` to recover the structured payload type-safely — e.g. read `currentVersion` after an `expected_version_mismatch` to retry against HEAD (#3624), or `leaseExpiresAt` after a `lease_held` to back off until the lease expires (#3625).
- [Type: WherePredicate](/sdk-reference/type-aliases/wherepredicate.md): A typed field-value WHERE predicate for `thing.query`, `thing.head`, and `thing.count`.
- [Function: isWarmHubError](/sdk-reference/functions/iswarmhuberror.md): Return whether a thrown value is already a `WarmHubError`.
- [Function: isRetryable](/sdk-reference/functions/isretryable.md): Return whether an error kind is generally safe to retry.
- [Function: normalizeWref](/sdk-reference/functions/normalizewref.md): Remove an `@vN`, `@HEAD`, or `@ALL` version suffix from a wref.
- [Function: connectionErrorMessage](/sdk-reference/functions/connectionerrormessage.md): Canonical user-facing message for a connection-level failure. Embeds the target URL so the user can see which endpoint was unreachable.
- [Function: contentFieldLimitError](/sdk-reference/functions/contentfieldlimiterror.md): Returns a validation error message if the given string exceeds [MAX\_CONTENT\_FIELD\_BYTES](/sdk-reference/variables/max_content_field_bytes/) when UTF-8 encoded, or `null` if it is within the limit.
- [Function: isConnectionError](/sdk-reference/functions/isconnectionerror.md): True if `error` is a connection-level fetch failure — raised before the server produced a response. Detects both `TypeError('fetch failed')` (Node undici, browsers) and Bun's native `Error` with a `code` like `ConnectionRefused` / `ECONNREFUSED`.
- [Function: toWarmHubError](/sdk-reference/functions/towarmhuberror.md): Normalize an unknown thrown value into `WarmHubError`.
- [Function: validateAgainstShape](/sdk-reference/functions/validateagainstshape.md): Validate a data payload against shape field definitions.
- [Function: verifyCliCall](/sdk-reference/functions/verifyclicall.md): Verify and parse an inbound component CLI call.
- [Variable: CLI_INSTALL_REPO_HEADER](/sdk-reference/variables/cli_install_repo_header.md): Wire header names for component CLI dispatch — the single source of truth shared by the backend dispatcher (which sets them) and `verifyCliCall` (which reads them). The install repo always rides in [CLI\_INSTALL\_REPO\_HEADER](/sdk-reference/variables/cli_install_repo_header/); the signing scheme adds [CLI\_SIGNATURE\_HEADER](/sdk-reference/variables/cli_signature_header/) + [CLI\_TIMESTAMP\_HEADER](/sdk-reference/variables/cli_timestamp_header/).
- [Variable: CLI_SIGNATURE_HEADER](/sdk-reference/variables/cli_signature_header.md)
- [Variable: CLI_TIMESTAMP_HEADER](/sdk-reference/variables/cli_timestamp_header.md)
- [Variable: CONTENT_FIELD_LIMIT_ERROR](/sdk-reference/variables/content_field_limit_error.md): Human-readable explanation of the [MAX\_CONTENT\_FIELD\_BYTES](/sdk-reference/variables/max_content_field_bytes/) limit, suitable for appending to a field-specific validation error. States the byte cap and points callers to an external document store for large payloads.
- [Variable: DEFAULT_API_URL](/sdk-reference/variables/default_api_url.md): Default WarmHub API URL used when a client is constructed without `apiUrl`.
- [Variable: MAX_CONTENT_FIELD_BYTES](/sdk-reference/variables/max_content_field_bytes.md): Maximum size, in bytes (UTF-8 encoded), allowed for a single content field value. WarmHub is not a document store: values larger than this are rejected at validation. Store large documents in S3, Box, Drive, or another document system and reference them from WarmHub instead.
- [Variable: SDK_VERSION](/sdk-reference/variables/sdk_version.md): Version string for the installed SDK package.

### SDK Methods (by surface)

Method names per WarmHubClient surface. Use this list to pick the call before fetching the full reference page.

- [WarmHubClient.auth](/sdk-reference/classes/warmhubclient.md#auth): getClientId, sync, currentUser, whoami
- [WarmHubClient.diagnostics](/sdk-reference/classes/warmhubclient.md#diagnostics): ping, capabilities, assertCompatible
- [WarmHubClient.component](/sdk-reference/classes/warmhubclient.md#component): list, search, get, install, registry.register, registry.unregister, registry.list, registry.view, registry.update, registry.resolve, registry.setupCall, cli.call
- [WarmHubClient.commit](/sdk-reference/classes/warmhubclient.md#commit): apply, See
- [WarmHubClient.org](/sdk-reference/classes/warmhubclient.md#org): get, getCallerRole, list, create, setDescription, setDisplayName, rename, update, addMember, removeMember, changeMemberRole, setMemberScopes, clearMemberScopes, listMembers, archive, unarchive
- [WarmHubClient.repo](/sdk-reference/classes/warmhubclient.md#repo): get, getStats, getStatsBatch, getConfigureStats, getShapeInstanceCounts, list, search, create, setDescription, setDisplayName, setVisibility, rename, update, archive, unarchive, delete, hardDelete, listPage, listForCaller, getReadme, getAgents, setReadme, setAgents, getLlmsTxt, index.describe, See
- [WarmHubClient.shape](/sdk-reference/classes/warmhubclient.md#shape): list, get, create, revise, remove, rename, history
- [WarmHubClient.subscription](/sdk-reference/classes/warmhubclient.md#subscription): create, get, reveal, list, update, pause, resume, remove, bindCredentials, unbindCredentials, See
- [WarmHubClient.action](/sdk-reference/classes/warmhubclient.md#action): acquireLease, heartbeatLease, releaseLease, claimDelivery, completeDelivery, liveFeed, listRuns, runStats, getRunAttempts, listNotifications
- [WarmHubClient.thing](/sdk-reference/classes/warmhubclient.md#thing): head, headIter, headAll, get, getWithLease, releaseLease, graph, getMany, headVersions, history, rename, resolve, about, aboutIter, aboutAll, query, queryIter, queryAll, search, count, refs, refsIter, refsAll
- [WarmHubClient.live](/sdk-reference/classes/warmhubclient.md#live): thingHead, thingHistory, subscriptionLog, subscribe
- [WarmHubClient.token](/sdk-reference/classes/warmhubclient.md#token): create, list, get, revoke
- [WarmHubClient.stream](/sdk-reference/classes/warmhubclient.md#stream): append
- [WarmHubClient.credential](/sdk-reference/classes/warmhubclient.md#credential): createSet, listSets, getSet, setKey, setKeys, unsetKey, deleteSet, listAuditLog, revokeSet