@xcitedbs/client 0.2.10 → 0.2.12

package/llms-full.txt

@@ -8,13 +8,13 @@
 
 Before reading the full reference, note these critical differences from typical databases:
 
-1. **The default branch is the empty string `""`, not `"main"`.** When no `X-Branch` header is sent (or `context.branch` is omitted/empty), the server operates on the root timeline. A branch named `"main"` may exist as a user-created branch, but it is not required or special.
+1. **The default workspace is the empty string `""`, not `"main"`.** When no `X-Workspace` header is sent (or `context.workspace` / `context.branch` is omitted/empty), the server operates on the root timeline. `X-Branch` is a supported alias of `X-Workspace`. A workspace named `"main"` may exist as user-created metadata, but it is not required or special.
 
 2. **Identifiers are hierarchical, path-like strings** — e.g. `/us/bills/hr1`, `/manual/v2/chapter3`. They are NOT auto-generated UUIDs. The leading `/` is part of the identifier. Parent/child relationships are derived from the path structure.
 
 3. **Documents are XML or JSON, not arbitrary blobs.** XML documents are the primary document type. JSON documents are a parallel store. Both are fully versioned.
 
-4. **Context (branch + date) travels as HTTP headers** (`X-Branch`, `X-Date`, and optionally `X-Unversioned` for explicit flat writes), not URL path segments.
+4. **Context (workspace + date) travels as HTTP headers** (`X-Workspace` preferred, `X-Branch` alias, `X-Date`, and optionally `X-Unversioned` for explicit flat writes), not URL path segments.
 
 5. **XML documents carry their identifier inside the XML** via a `db:identifier` attribute on the root element.
 
@@ -26,7 +26,19 @@ Before reading the full reference, note these critical differences from typical
 
 9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
 
-10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. With a default body (omit or `{}`), the test LMDB starts **empty** (no cloned production project config).
+
+11. **Overlay test sessions.** Same **`POST`**, with JSON **`{"overlay":true}`**, while authenticated for the **project to debug** (project-scoped API key, or platform Bearer + **`X-Project-Id`**). The session metadata records overlay mode; subsequent requests need only **`X-Test-Session`**. The server opens **`XCiteDB(_test/<uuid>/data, <production data path>)`**: production is used as a **read-only base**; reads merge overlay + base; **writes never modify production**. If the production data directory is missing, opening the session database fails. JS **`createTestSession({ …, overlay: true })`**, C++ **`test_session_overlay`** + **`create_test_session`**, MCP **`create_test_session`** tool **`overlay: true`**.
+
+## Choosing the Right Versioning Approach
+
+- **Write at a specific date:** Set `X-Date` / `context.date` and write — every dated write is a **temporal revision**; no workspace or checkpoint required.
+- **Read as-of a date:** Set `X-Date` and read; the engine returns the revision at or before that instant.
+- **Isolated editing (draft → publish):** Create a **workspace**, edit, then **publish** to the target timeline; optional **checkpoints** for named snapshots.
+- **Audit trail:** Checkpoints carry messages and affected identifiers; **bookmarks** name a checkpoint.
+- **Undo a batch:** **Revert** to a prior checkpoint on that workspace.
+
+Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain **deprecated** aliases; prefer **`/api/v1/workspaces`**, **`/checkpoints`**, **`/bookmarks`**, **`/compare`**.
 
 ## Common Pitfalls
 
@@ -48,7 +60,7 @@ Before reading the full reference, note these critical differences from typical
 
 6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
 
-7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Ephemeral test sessions" below.
+7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real LMDB under `_test/<uuid>/` (empty by default, or **overlay** on read-only production with **`{"overlay":true}`** / **`overlay: true`** / **`test_session_overlay`**). See "Ephemeral test sessions" below.
 
 ---
 
@@ -65,25 +77,25 @@ Before reading the full reference, note these critical differences from typical
 ### 1.1 What is XciteDB?
 XciteDB is an enterprise-grade **Backend-as-a-Service (BaaS)** built on top of a highly optimized **embedded LMDB** database engine. Powered by a high-performance C++17 HTTP/WebSocket API, XciteDB exposes a multi-tenant, secure platform for managing complex, versioned, structured documents.
 
-**Both XML and JSON are first-class citizens.** XciteDB can operate as a pure **XML document store**, a pure **JSON document database**, or any combination of the two — including the common pattern of **XML documents enriched with structured JSON metadata**. In every mode, data is deeply shredded into its structural components (elements, attributes, objects, fields, array items), versioned, branched, indexed by path, and fully queryable through the same Unquery analytics engine.
+**Both XML and JSON are first-class citizens.** XciteDB can operate as a pure **XML document store**, a pure **JSON document database**, or any combination of the two — including the common pattern of **XML documents enriched with structured JSON metadata**. In every mode, data is deeply shredded into its structural components (elements, attributes, objects, fields, array items), versioned, indexed by path, and fully queryable through the same Unquery analytics engine — with **temporal revisions**, **workspaces**, and **checkpoints** when you need collaborative workflow.
 
 ### 1.2 The Problem It Solves
 Standard relational databases and generic NoSQL stores struggle with highly structured, hierarchical, and deeply versioned content. Building collaborative authoring tools, legislative drafting systems, or complex content management platforms usually requires bolting a Git-like versioning layer and document-aware parsers onto an ill-fitting database.
 
-XciteDB bridges this gap. It provides **Git-like versioning for structured XML and JSON data** out of the box, delivered as a modern, API-first cloud platform with multi-tenancy, Attribute-Based Access Control (ABAC), and S3-compatible backups.
+XciteDB bridges this gap. It provides **temporal versioning plus optional workspaces and checkpoints** for structured XML and JSON data out of the box, delivered as a modern, API-first cloud platform with multi-tenancy, Attribute-Based Access Control (ABAC), and S3-compatible backups.
 
 ### 1.3 Target Workloads
 XciteDB shines in domains requiring strict auditability, collaborative authoring, and complex document hierarchies:
 - **Legal and Legislative Drafting:** Tracking amendments, clauses, and exact historical states of laws.
 - **Structured Technical Documentation:** Managing manuals, specifications, and compliance documents where every change must be versioned and attributable.
-- **Collaborative Content Management:** Systems requiring branching, merging, and cooperative locking to prevent editor conflicts.
+- **Collaborative Content Management:** Systems requiring isolated workspaces, publish workflows, and cooperative locking to prevent editor conflicts.
 - **Application State and Configuration:** Storing deeply structured JSON configuration, feature flags, or workflow state that benefits from versioning and path-level querying.
 
 ### 1.4 Unique Differentiators
-- **First-Class XML & JSON:** Both formats are shredded, indexed by path, versioned, branched, and fully queryable through the same engine.
+- **First-Class XML & JSON:** Both formats are shredded, indexed by path, versioned, and fully queryable through the same engine.
 - **Embedded LMDB Engine:** A memory-mapped, ACID-compliant storage core purpose-built for structured document workloads.
 - **Bare-Metal Speed:** Reads hit memory-mapped pages with no network round-trip. Microsecond-class read latency on warm data.
-- **"Git for Data" Versioning:** Branches, commits, tags, diffs, and time-travel are first-class database primitives.
+- **Document-centric versioning:** Temporal revisions (`X-Date`), workspaces, checkpoints, bookmarks, compare, publish, revert, and apply — plus time-travel reads.
 - **Unquery DSL:** A purpose-built declarative query language for navigating, filtering, and aggregating data across both XML trees and JSON structures.
 - **Native Office Ingestion:** Directly convert and ingest DOCX, ODF, RTF, and PDF formats into clean, versioned XML documents.
 - **Transparent Tenant Routing:** Scale out horizontally using a coordinator/worker topology without breaking the client API contract.
@@ -106,10 +118,10 @@ XciteDB shines in domains requiring strict auditability, collaborative authoring
 - **JSON Metadata on XML:** JSON metadata can be attached to any XML document or path.
 - **Hierarchical Identifiers:** Both XML and JSON documents are addressed via logical, path-like strings. The engine natively indexes parent/child relationships.
 
-### 2.3 Git-Like Document Versioning
-- **Branches & Commits:** Isolate collaborative edits into branches. Create atomic commits with descriptive messages.
-- **Merge & Cherry-Pick:** Merge branches or cherry-pick specific commits.
-- **Time Travel:** Read historical state at any point in time using the `X-Date` header. For **writes**, `X-Unversioned: true` explicitly requests flat (unversioned) storage; it conflicts with `X-Date` (**400**).
+### 2.3 Document versioning model
+- **Temporal revisions & workspaces:** Every write with `X-Date` records under that revision instant. **Workspaces** isolate draft edits from the root timeline.
+- **Checkpoints, publish, apply, revert:** Optional named snapshots (**checkpoints**); **publish** merges a workspace into a target; **apply** brings another checkpoint’s changes; **revert** rolls the workspace back to a checkpoint.
+- **Time travel:** Read historical state at any point in time using the `X-Date` header. For **writes**, `X-Unversioned: true` explicitly requests flat (unversioned) storage; it conflicts with `X-Date` (**400**).
 - **Cooperative Locking:** TTL locks prevent conflicting writes (HTTP 409 on conflict).
 
 ### 2.4 Unquery: Declarative Query DSL
@@ -142,7 +154,8 @@ Welcome to the **XciteDB HTTP API**. This reference describes REST endpoints und
 |--------|------|-------------|
 | `Authorization` | Usually required | `Bearer <JWT>` or `Bearer <api_key>` |
 | `X-Project-Id` | Platform console / multi-project JWT | Selects the **tenant project** when the token is not already bound to one tenant |
-| `X-Branch` | Optional | Active branch name for document and versioning operations |
+| `X-Workspace` | Optional | Active workspace name for document and versioning operations (preferred) |
+| `X-Branch` | Optional | Deprecated alias of `X-Workspace` |
 | `X-Date` | Optional | Point-in-time / revision context (ISO-like string as used by your deployment) |
 | `X-Unversioned` | Optional | When `true` or `1`, **writes** use flat LMDB keys (no date revision). Must not be combined with `X-Date` (**400**). Omitting `X-Date` remains valid (implicit unversioned). |
 
@@ -194,7 +207,7 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 | Step | What to do |
 |------|------------|
-| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). |
+| **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
 | **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
 | **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, but data still comes from the test session DB. |
 | **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. |
@@ -202,9 +215,9 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`. `destroyTestSession()` calls `DELETE …/test/sessions/current`.
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor. For overlay until the helper accepts a flag, call **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`** then construct the client with the returned token.
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay = true`**, and optional `test_require_auth`; `destroy_test_session()`.
 
 **JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
 
@@ -241,8 +254,8 @@ describe('XciteDB integration', () => {
     expect(xml).toContain('<title>Hello</title>');
   });
 
-  it('creates a branch, commits, and merges', async () => {
-    await client.withBranch('feature-test', async (c) => {
+  it('creates a workspace, checkpoints, and publishes', async () => {
+    await client.withWorkspace('feature-test', async (c) => {
       await c.writeJsonDocument('test.feature', { active: true });
     }, { message: 'Add feature flag', autoMerge: true });
     const doc = await client.readJsonDocument<{ active: boolean }>('test.feature');
@@ -283,8 +296,8 @@ async def test_xml_document(db):
     assert "<title>Hello</title>" in result
 
 @pytest.mark.asyncio
-async def test_branch_and_merge(db):
-    async with db.with_branch("feature-test", message="Add flag", auto_merge=True):
+async def test_workspace_and_publish(db):
+    async with db.with_workspace("feature-test", message="Add flag", auto_merge=True):
         await db.put("test.feature", {"active": True})
     doc = await db.get("test.feature")
     assert doc["active"] is True
@@ -518,7 +531,7 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 # Search
 
-Full-text search uses embedded XciteFTS (enable per project in server settings).
+Full-text search uses **embedded XciteFTS** (LMDB index per project). **Semantic** and **hybrid** (FTS + vector) search are available when vector search is enabled in project settings. The JSON field **`mode`** selects behavior (`auto` picks the best option for the project, or set `fts`, `semantic`, or `hybrid` explicitly).
 
 **Base path:** `/api/v1/search`
 
@@ -532,15 +545,26 @@ Full-text search uses embedded XciteFTS (enable per project in server settings).
   "doc_types": ["xml", "json"],
   "branch": "",
   "limit": 20,
-  "offset": 0
+  "offset": 0,
+  "mode": "fts"
 }
 ```
 
-Response: `{ hits: [{ identifier, path, doc_type, branch, snippet, score, xcitepath? }], total, query }`.
+Optional fields (also on SDK `TextSearchQuery` and the MCP `search` tool): **`min_score`**, **`semantic_weight`** for semantic/hybrid.
+
+**Temporal FTS** (posting intervals; applies to the FTS keyword index—use **`mode`: `"fts"`** for pure temporal keyword search, or hybrid where the FTS leg participates):
+
+| Field | Meaning |
+|-------|---------|
+| **`at_date`** | Date string (e.g. ISO `YYYY-MM-DD` or `mm/dd/yyyy` as accepted by the server). A posting matches if it is valid at that instant: `start <= at_date < end` (internal 7-char keys after `date2key`). |
+| **`date_from`**, **`date_to`** | Date strings defining a half-open range `[date_from, date_to)`. A posting matches if its `[start, end)` **overlaps** that range. Either bound may be omitted (open-ended). |
+| *(none of the three)* | **Current-time** view: only postings whose interval is still “open” (end at the internal max sentinel) are included. |
+
+**Response:** `{ hits: [...], total, query }`. Each hit has **`identifier`**, **`path`**, **`doc_type`**, **`branch`**, **`snippet`**, **`score`**, and optionally **`xcitepath`** (XML). Semantic/hybrid hits may include **`source`**: `fts` \| `semantic` \| `both`. When the server infers a temporal window for the matched term(s), hits may include **`valid_from`** and **`valid_to`** as **7-character internal date keys** (same alphabet as revision keys—not ISO). Omitted for full-range/unversioned postings or when not computed.
 
 ## Reindex
 
-**`POST /api/v1/search/reindex`** — Rebuilds the search index.
+**`POST /api/v1/search/reindex`** — Rebuilds the full-text search index.
 
 ---
 
@@ -680,100 +704,107 @@ Dry-run: **`POST /api/v1/security/check`** with `subject`, `identifier`, `action
 
 ---
 
-# Branches
+# Workspaces (branches)
 
-**Base path:** `/api/v1/branches`
+**Preferred base path:** `/api/v1/workspaces`  
+**Deprecated alias:** `/api/v1/branches` (same handlers)
 
-**IMPORTANT: The default branch is the empty string `""`.** When no branch is specified, the server uses the root timeline.
+**IMPORTANT: The default workspace is the empty string `""`.** When no workspace is specified, the server uses the root timeline.
 
-## List branches
+## List workspaces
 
-**`GET /api/v1/branches`** — Returns `{ branches: [{ name, from_branch, from_date, from_date_key, tip_commit }] }`.
+**`GET /api/v1/workspaces`** — Returns `{ workspaces: [...], branches: [...] }` where each item includes `name`, `from_branch`, `from_date`, `tip_checkpoint` (and `tip_commit` mirror).
 
-## Create branch
+## Create workspace
 
-**`POST /api/v1/branches`** — `{ "name": "feature-x", "from_branch": "", "from_date": "" }`
+**`POST /api/v1/workspaces`** — `{ "name": "feature-x", "from_branch": "", "from_date": "" }`
 
-## Get branch
+## Get workspace
 
-**`GET /api/v1/branches/{name}`** — Returns `{ branch: {...} }`.
+**`GET /api/v1/workspaces/{name}`** — Returns `{ workspace: {...}, branch: {...} }`.
 
-## Delete branch
+## Delete workspace
 
-**`DELETE /api/v1/branches/{name}`**
+**`DELETE /api/v1/workspaces/{name}`**
 
-## Merge branch
+## Publish workspace
 
-**`POST /api/v1/branches/{target}/merge`**
+**`POST /api/v1/workspaces/{target}/publish`**
 
 ```json
 {
+  "source_workspace": "feature-x",
   "source_branch": "feature-x",
-  "message": "Merge feature",
+  "message": "Publish feature",
   "auto_resolve": "none"
 }
 ```
 
 `auto_resolve`: `"none"` | `"source"` | `"target"`.
 
-Returns `{ status: "completed"|"conflicts", commit?, merged_identifiers?, conflicts? }`.
+Returns `{ status: "completed"|"conflicts", checkpoint?, commit?, merged_identifiers?, conflicts? }` (`commit` mirrors `checkpoint`).
 
-## Delete revision on branch
+## Delete revision on workspace
 
-**`DELETE /api/v1/branches/{name}/revisions/{date}`**
+**`DELETE /api/v1/workspaces/{name}/revisions/{date}`** (human-readable date in path; legacy `/branches/...` path still works)
 
 ---
 
-# Commits, tags & diff
+# Checkpoints, bookmarks & compare
 
-## Create commit
+## Create checkpoint
 
-**`POST /api/v1/commits`** — `{ "message": "...", "author": "..." }`
+**`POST /api/v1/checkpoints`** — `{ "message": "...", "author": "..." }`  
+(Deprecated: **`POST /api/v1/commits`**)
 
-Returns `{ commit: { id, branch, date_key, message, author, ... } }`.
+Returns `{ checkpoint: { id, checkpoint_id, branch, date, message, author, ... }, commit: <same> }`. Public JSON uses human-readable **`date`** (no `date_key`).
 
-## List commits
+## List checkpoints
 
-**`GET /api/v1/commits?branch=...&limit=...&offset=...`**
+**`GET /api/v1/checkpoints?branch=...&limit=...&offset=...`** (query param name unchanged; means workspace)  
+Returns `{ checkpoints: [...], commits: [...], total, branch }` (mirrors).
 
-Returns `{ commits: [...], total, branch }`.
+## Get checkpoint
 
-## Get commit
+**`GET /api/v1/checkpoints/{id}`** — Returns `{ checkpoint, commit }`.
 
-**`GET /api/v1/commits/{id}`** — Returns `{ commit: {...} }`.
+## Revert to checkpoint
 
-## Rollback to commit
+**`POST /api/v1/checkpoints/{id}/revert`** — `{ "confirm": true }`  
+(Deprecated: **`.../rollback`**)
 
-**`POST /api/v1/commits/{id}/rollback`** — `{ "confirm": true }`
+## Apply checkpoint
 
-## Cherry-pick commit
+**`POST /api/v1/checkpoints/{id}/apply`** — `{ "message": "...", "author": "..." }`  
+(Deprecated: **`.../cherry-pick`**)
 
-**`POST /api/v1/commits/{id}/cherry-pick`** — `{ "message": "...", "author": "..." }`
+## Create bookmark
 
-## Create tag
+**`POST /api/v1/bookmarks`** — `{ "name": "v1.0", "checkpoint_id": "...", "commit_id": "...", "message": "..." }`  
+(Deprecated: **`POST /api/v1/tags`**)
 
-**`POST /api/v1/tags`** — `{ "name": "v1.0", "commit_id": "...", "message": "..." }`
+## List bookmarks
 
-## List tags
+**`GET /api/v1/bookmarks?limit=...&offset=...`** — Returns `{ bookmarks: [...], tags: [...], total }` (mirrors where applicable).
 
-**`GET /api/v1/tags?limit=...&offset=...`** — Returns `{ tags: [...], total }`.
+## Get / Delete bookmark
 
-## Get / Delete tag
+**`GET /api/v1/bookmarks/{name}`** / **`DELETE /api/v1/bookmarks/{name}`** (deprecated `/tags/...`)
 
-**`GET /api/v1/tags/{name}`** / **`DELETE /api/v1/tags/{name}`**
+## Compare
 
-## Diff
-
-**`POST /api/v1/diff`**
+**`POST /api/v1/compare`**
 
 ```json
 {
-  "from": { "branch": "", "date_key": "..." },
+  "from": { "branch": "", "date": "2024-01-15T00:00:00" },
   "to": { "branch": "feature-x" },
   "include_content": true
 }
 ```
 
+(Deprecated: **`POST /api/v1/diff`**; `date_key` still accepted internally but prefer **`date`**.)
+
 Returns `{ changes: [{ identifier, action: "added"|"modified"|"deleted", from_content?, to_content? }], total_changes }`.
 
 ---
@@ -1243,7 +1274,7 @@ import { XCiteDBClient } from '@xcitedbs/client';
 const client = new XCiteDBClient({
   baseUrl: 'http://localhost:8080',
   apiKey: 'your-api-key',
-  context: { branch: '', date: '' },
+  context: { workspace: '', date: '' },
 });
 
 // Health check
@@ -1263,12 +1294,12 @@ await client.writeJsonDocument('app.settings', { theme: 'dark' });
 // Read JSON document
 const settings = await client.readJsonDocument('app.settings');
 
-// Branch, edit, commit, merge
-await client.createBranch('feature-x');
-client.setContext({ branch: 'feature-x' });
+// Workspace, edit, checkpoint, publish
+await client.createWorkspace('feature-x');
+client.setContext({ workspace: 'feature-x' });
 await client.writeJsonDocument('app.settings', { theme: 'light' });
-await client.createCommit('Switch to light theme');
-await client.mergeBranch('', 'feature-x');
+await client.createCheckpoint('Switch to light theme');
+await client.publishWorkspace('', 'feature-x');
 ```
 
 ## Constructor Options
@@ -1289,7 +1320,8 @@ interface XCiteDBClientOptions {
 }
 
 interface DatabaseContext {
-  branch?: string;   // '' = default (root timeline)
+  workspace?: string; // '' = default (root timeline); preferred
+  branch?: string;    // @deprecated alias of workspace
   date?: string;     // Point-in-time
   prefix?: string;   // Identifier prefix filter
   unversioned?: boolean; // Sends X-Unversioned: true (flat writes; do not combine with date)
@@ -1357,30 +1389,34 @@ interface DatabaseContext {
 - `queryMetaByQuery<T>(query, path?)` → `T`
 - `clearMeta(query)` → `boolean`
 
-### Branches
-- `withBranch(name, fn, options?)` → `{ result, commit?, merge? }` — branch, callback, commit, merge back
-- `createBranch(name, fromBranch?, fromDate?)` → `void`
-- `listBranches()` → `BranchInfo[]`
-- `getBranch(name)` → `BranchInfo`
-- `deleteBranch(name)` → `void`
-- `deleteRevision(branch, date)` → `void`
-- `mergeBranch(targetBranch, sourceBranch, options?)` → `MergeResult`
-
-### Commits
-- `createCommit(message, author?)` → `CommitRecord`
-- `listCommits(options?)` → `{ commits, total, branch }`
-- `getCommit(commitId)` → `CommitRecord`
-- `rollbackToCommit(commitId)` → `{ rolled_back_commits, current_tip }`
-- `cherryPick(commitId, message?, author?)` → `CommitRecord`
-
-### Tags
-- `createTag(name, commitId, message?, author?)` → `TagRecord`
-- `listTags(options?)` → `{ tags, total }`
-- `getTag(name)` → `TagRecord`
-- `deleteTag(name)` → `void`
-
-### Diff
-- `diff(from: DiffRef, to: DiffRef, includeContent?)` → `DiffResult`
+### Workspaces & checkpoints
+- `withWorkspace(name, fn, options?)` → `{ result, checkpoint?, publish? }` — workspace, callback, checkpoint, publish back
+- `createWorkspace(name, fromBranch?, fromDate?)` → `void`
+- `listWorkspaces()` → `WorkspaceInfo[]`
+- `getWorkspace(name)` → `WorkspaceInfo`
+- `deleteWorkspace(name)` → `void`
+- `deleteRevision(branch, date)` → `void` (workspace name + human date)
+- `publishWorkspace(targetWorkspace, sourceWorkspace, options?)` → `PublishResult`
+- **Deprecated:** `withBranch`, `createBranch`, `listBranches`, `getBranch`, `deleteBranch`, `mergeBranch` (same HTTP behavior)
+
+### Checkpoints
+- `createCheckpoint(message, author?)` → `CheckpointRecord`
+- `listCheckpoints(options?)` → `{ checkpoints, total, branch }` (wire JSON may also include `commits` mirror)
+- `getCheckpoint(checkpointId)` → `CheckpointRecord`
+- `revertToCheckpoint(checkpointId)` → `{ rolled_back_checkpoints, rolled_back_commits?, current_tip }`
+- `applyCheckpoint(checkpointId, message?, author?)` → `CheckpointRecord`
+- **Deprecated:** `createCommit`, `listCommits`, `getCommit`, `rollbackToCommit`, `cherryPick`
+
+### Bookmarks
+- `createBookmark(name, checkpointId, message?, author?)` → `BookmarkRecord`
+- `listBookmarks(options?)` → `{ bookmarks, tags, total, limit?, offset? }`
+- `getBookmark(name)` → `BookmarkRecord`
+- `deleteBookmark(name)` → `void`
+- **Deprecated:** `createTag`, `listTags`, `getTag`, `deleteTag`
+
+### Compare
+- `compare(from: CompareRef, to: CompareRef, includeContent?)` → `CompareResult`
+- **Deprecated:** `diff(from: DiffRef, …)` — alias of `compare`
 
 ### Locks
 - `acquireLock(identifier, expires?)` → `LockInfo`
@@ -1388,7 +1424,7 @@ interface DatabaseContext {
 - `findLocks(identifier)` → `LockInfo[]`
 
 ### Search
-- `search(query: TextSearchQuery)` → `TextSearchResult`
+- `search(query: TextSearchQuery)` → `TextSearchResult`. Query may include **`at_date`**, **`date_from`**, **`date_to`** (ISO-style or `mm/dd/yyyy` strings) for temporal FTS; set **`mode`: `"fts"`** for keyword-only temporal search. Hits may include **`valid_from`** / **`valid_to`** (7-char internal keys) when the server returns an inferred validity window.
 - `reindex()` → `{ status, message }`
 
 ### Unquery
@@ -1513,7 +1549,7 @@ async def main():
     async with XCiteDBClient(
         "http://localhost:8080",
         api_key="your-key",
-        context=DatabaseContext(branch="", date=""),
+        context=DatabaseContext(workspace="", date=""),
     ) as client:
         print(await client.health())
         print(await client.query_documents(XCiteQuery(match_start="/manual/")))
@@ -1521,15 +1557,16 @@ async def main():
         print(await client.read_json_document("app.settings"))
         print(await client.list_identifiers(XCiteQuery(match_start="/manual/")))
         print(await client.search(TextSearchQuery(query="guide", limit=10)))
+        # Temporal FTS: await client.search(TextSearchQuery(query="guide", mode="fts", at_date="2024-06-01"))
         await client.platform_login("admin@localhost", "password")
         # await client.login_app_user("user@example.com", "pw")  # set context.project_id / tenant_id if needed
-        async with client.with_branch("feature-x", message="WIP", auto_merge=True):
+        async with client.with_workspace("feature-x", message="WIP", auto_merge=True):
             await client.put("app.settings", {"theme": "light"})
 
 asyncio.run(main())
 ```
 
-Async client: `write_xml_document` / `write_document_json` (deprecated), `write_json_document`, `read_json_document`, `list_json_documents`, `list_identifiers`, `search`, `reindex`, `platform_login` / `login` (deprecated), `login_app_user`, `refresh_app_user`, `logout_app_user`, `register_app_user`, `put` / `get` / `remove` / `list_documents` (JSON aliases), `with_branch` (async context manager).
+Async client: `write_xml_document` / `write_document_json` (deprecated), `write_json_document`, `read_json_document`, `list_json_documents`, `list_identifiers`, `search`, `reindex`, `platform_login` / `login` (deprecated), `login_app_user`, `refresh_app_user`, `logout_app_user`, `register_app_user`, `put` / `get` / `remove` / `list_documents` (JSON aliases), `with_workspace` (async context manager; `with_branch` deprecated alias).
 
 ---
 
@@ -1541,7 +1578,7 @@ Async client: `write_xml_document` / `write_document_json` (deprecated), `write_
 xcitedb::XCiteDBClientOptions opt;
 opt.base_url = "http://127.0.0.1:8080";
 opt.api_key = "your-key";
-opt.context.branch = "";  // root timeline
+opt.context.workspace = "";  // root timeline (`branch` is deprecated alias)
 
 xcitedb::XCiteDBClient client(opt);
 auto health = client.health();
@@ -1553,4 +1590,4 @@ auto ids = client.query_documents(q);
 
 Synchronous (blocking) HTTP client. Methods mirror the JavaScript SDK with C++ naming (`write_xml_document`, deprecated `write_document_json`). Errors throw `xcitedb::XCiteDBError` with `.status()` and `.body()`.
 
-Includes optional `xcitevcs` CLI for command-line operations (branches, commits, documents, search, import/export).
+Includes optional `xcitevcs` CLI for command-line operations (legacy branch/commit vocabulary on the wire, documents, search, import/export).