querri 2.0.0__tar.gz → 2.2.0__tar.gz

querri-2.2.0/CHANGELOG.md

@@ -0,0 +1,238 @@
+# Changelog
+
+## 2.2.0 (2026-10-31)
+
+### Added
+
+- **Custom roles as code.** `client.roles` (sync and async): `list()`,
+  `get(ref)`, `catalog()`, `apply(definition, dry_run=)` (idempotent upsert,
+  `PUT /roles/{key}`), `import_roles(definitions, dry_run=)` (one call, each
+  role independent), `delete(ref, reassign_to=)` and `export()` (definitions
+  with the output-only fields stripped, ready to save and re-apply). New
+  types in `querri.types`: `RoleDefinition`, `RoleApplyResult`,
+  `RoleChange`, `RoleApplyError`, `RoleImportResult`, `RoleDeleteResponse`,
+  `PermissionCatalog`, `CatalogPermission`. Needs the `admin:roles:read` /
+  `admin:roles:write` scopes. See docs/roles.md.
+- **`querri role`** (alias `querri roles`): `list`, `get`, `export`,
+  `apply -f FILE [--dry-run] [--watch]`, `delete [--reassign-to] [--yes]` and
+  `catalog [--area]`. `apply` prints a per-field change summary
+  (`denies: +chat.code.view -tools.dashboards.use`) and exits non-zero when
+  any role failed; `--watch` re-applies whenever the file is saved. JSON
+  files only.
+- The **Roles** scope group in the `querri key new` scope picker.
+- **Custom Roles on embed sessions.** `client.embed.create_session()` and
+  `client.embed.get_session()` (sync and async) take `role=` — the id or key
+  of the Custom Role the session runs as. It is sent only when set, and it
+  is not `user["role"]` (the org role used when creating a user). Decide it
+  on your server, never from the browser's request. Granting a role the user
+  does not hold is **permanent**: it is added to the user's role assignment
+  (later sessions and the app see it), revoking the session does not remove
+  it, and an admin removes it in Settings → People. `EmbedSession.role_id`
+  and `EmbedSessionListItem.role_id` carry the applied role (`None` without
+  one — or when an older server ignored `role`, in which case the session
+  runs as the user's own role; servers released after 2026-10-21 also
+  return it from refresh and list, earlier ones only from create);
+  `refresh_session()` returns it too, and the `get_session()` dict carries
+  `role_id` when a role was applied. CLI: `querri session new --role` /
+  `querri session get --role`; `session new` and `session refresh` print
+  `Role ID`, and the `session list` table has a `Role ID` column.
+- **`APIError.permission` and `APIError.reason`.** A `403
+  permission_denied` names the permission the call needed (from the body,
+  else the `X-Permission-Denied` header) and why it was refused
+  (`role_denied`, `not_in_plan`, `flag_off`, `embed_disabled`,
+  `dependency_unmet`, `forbidden`, `scope_exceeds_role`; the server may add
+  more). The header is used only when the error's code is
+  `permission_denied` or there is no code, and only when it holds a
+  permission key (contains a `.`), not an error code — so an
+  `escalation_denied` refusal never borrows it. The in-app flat body
+  `{"detail": {"error": "<code>", ...}}` is parsed too. `RateLimitError`
+  keeps them too.
+- **`APIError.body`**: the parsed JSON response body (any JSON value; `None`
+  when the response was not JSON), on every `APIError`, streamed requests
+  included. It carries the fields the exception does not lift out, e.g.
+  `err.body["detail"]["error"]["scopes"]` on `scope_exceeds_role` and
+  `err.body["detail"]["error"]["missing"]` on `escalation_denied`.
+- **Error-code constants**: `querri.ROLE_DISABLED`, `querri.PERMISSION_DENIED`,
+  `querri.ESCALATION_DENIED` (403), `querri.LAST_ADMIN` (409),
+  `querri.INVALID_PARAMETERS` (400), … (26 in all) and the
+  `querri.ErrorCode` / `querri.PermissionDeniedReason` `Literal`s — the
+  codes for authentication, access, Custom Roles, embed sessions and user
+  role changes; the API sends other codes too, so treat `code` as a string.
+  docs/server-sdk.md has an Error codes table.
+- `embed:role:assign` in the `querri key new` scope picker.
+- **`X-Querri-Client` header.** Every client sends `X-Querri-Client:
+  sdk/<version>`; clients built by the `querri` command, and its
+  login/refresh token requests, send `cli/<version>`, so the server can tell
+  CLI use from library use.
+
+### Changed
+
+- **`422` request-validation errors raise `ValidationError`** (was the base
+  `APIError`) with a readable message — `"Validation failed: body.ttl: Input
+  should be greater than or equal to 900"` — instead of the raw `detail`
+  list. A bare `{"detail": {"code", "message"}}` body is parsed like the
+  `error` envelope.
+- **Behaviour change — CLI: a 403 exits `6`** instead of `1`. Scripts that
+  test for exit code `1` on a refused call must accept `6`. In text mode the
+  message gains the permission and reason (`(permission:
+  dashboards.list.view, reason: role_denied)`); the API code is printed once,
+  on its `Code:` line, as before.
+- **CLI `--json` errors: unchanged from 2.1.0, plus `exit_code`.** Every
+  JSON error prints the same keys and values 2.1.0 printed for the same
+  situation — a 403 is still `"error": "api_error"`, `code` is still the API
+  error code when the server sent one and otherwise the exit code, and
+  `permission` / `reason` are not added as keys — plus `"exit_code"`, the
+  process exit code. The one value that moves is a consequence of the exit
+  code above: a 403 with no API code has `"code": 6` (it was `1`). The `querri
+  view run` timeout (`{"error": "<message>"}`) and `querri auth switch-org`
+  single-org outputs keep their 2.1.0 shapes, plus `exit_code`.
+- Docs: API-key scopes follow a person's role — a key keeps only the scopes
+  both its creator and its bound user currently hold, and the permission
+  checks made on its behalf (embed role grants, the users endpoints' role
+  guards) use the permissions both hold (servers released after 2026-10-21;
+  earlier servers cap only keys created in Settings and check role grants
+  against the bound user, else the creator). The keys section covers
+  binding (Admins only), pseudo ids, and what a key minted by another key
+  inherits. On those servers `client.users` `create` / `update` / `delete` /
+  `get_or_create` (and `get_session()` for a new user) can be refused with
+  `escalation_denied` or `last_admin`. The real scope list replaces the
+  invented names in the CLI skill. `as_user` calls can raise
+  `permission_denied` under the session's role.
+
+### Fixed
+
+- **Streaming calls keep their error details.** A streamed request
+  (`projects.chats.stream()`, view streams) that failed raised an
+  `APIError` with no `code`, `message`, `permission` or `reason`, because
+  the unread body could not be parsed. The body is now read (and the
+  response closed) before raising; a body that fails mid-read still raises
+  the status's exception class.
+- **Retried streamed responses are closed.** A streamed request that got a
+  429 or a retryable 5xx left each discarded response open, holding its
+  connection; each is now closed before the retry.
+- **A JSON array or scalar error body no longer crashes error handling.**
+  `raise_for_status` assumed a JSON object and raised `AttributeError` on a
+  body like `["bad"]` or `"oops"`; it now raises the status's exception.
+- `create_session(role="")` / `get_session(role="")` no longer send an
+  empty `role`.
+- **`querri view list` no longer truncates IDs.** The Rich table clipped
+  36-character view UUIDs with `…`, and pasting the clipped ID into `querri
+  view chat` failed with a misleading 403. ID/UUID columns now never wrap
+  (QUE-135).
+- `skills/querri-cli/references/json-shapes.md` documented a non-existent
+  `querri embed create-session` and a stale `querri key create`; it now
+  documents `querri session new` / `refresh` / `list` / `get`, `querri key
+  new` and the `--json` error shape.
+- **`examples/web-embed/server.py` no longer exposes the Werkzeug
+  debugger.** It bound `0.0.0.0` with `debug=True`, letting anyone on the
+  network run code on the machine. It now binds `127.0.0.1` with debug off;
+  `HOST` and `FLASK_DEBUG=1` opt in, and debug is refused on a non-local
+  host.
+
+## 2.1.0 (2026-09-24)
+
+### Added
+
+- **`client.library`** (sync and async) and the `querri library` CLI: the Data
+  Library surface — libraries, collections, anchor and refining questions,
+  graph search and zoom, `record_fact`, the Librarian `chat` / `chat_stream`,
+  `ask`, `intake`, `consolidate`, `eval`, backfill and health. Reference:
+  [docs/data-library.md](docs/data-library.md). This is the `dev` line that
+  had been building since 1.1.0; it ships here unchanged.
+
+### Fixed
+
+- **Error bodies without a Stripe-style envelope keep their message and
+  code.** FastAPI raises `{"detail": {"error": {...}}}` (or a plain string
+  `detail`); `APIError.message`, `.code` and `.type` were left as
+  `"HTTP <status>"` / `None` for those, so a `NotFoundError` for a step with
+  no data read the same as one for a missing project. Both shapes are parsed
+  now.
+
+## 2.0.0 (2026-08-31)
+
+Migration guide with before/after snippets: [docs/MIGRATION.md](docs/MIGRATION.md).
+
+### Breaking
+
+- **`source_scope` removed from `client.embed.create_session()`** (sync and
+  async). It was never enforced by the server — a silently-ignored parameter
+  that *looked* like access control. Passing it now raises `TypeError`. Scope
+  sessions with access policies instead: `client.embed.get_session(access=...)`.
+- **`as_user()` / `UserQuerri` rebased from `/api` to `/api/v1`.** Embed
+  sessions (`X-Embed-Session`) are the public API's highest-priority
+  credential, so user-scoped clients now call the same public API paths as
+  the admin client.
+- **`user_client.dashboards` is read-only.** Embed sessions exclude the
+  `admin:dashboards:write` scope server-side; the user-scoped surface now
+  exposes only `list()`, `get()`, and `refresh_status()` — `create`,
+  `update`, `delete`, and `refresh` no longer exist there (they always
+  belonged to the admin client).
+- There is no `user_client.embed`: embed sessions exclude
+  `embed:session:create` server-side (a session cannot mint sessions).
+  The accessor never existed in the SDK; the contract is now documented
+  and tested.
+- **`ttl` is validated client-side**: `create_session()` and
+  `get_session()` raise `ValueError` for TTLs outside [900, 86400] seconds
+  instead of sending a value the server would silently clamp.
+
+### Added
+
+- `client.embed.get_ui_config(org)` — fetches the public, unauthenticated
+  `GET {host}/api/embed/ui-config?org=...` (main app path, not `/api/v1`)
+  and returns the raw `{chrome, theme, privacy}` dict.
+- `querri session ui-config --org <id>` CLI command for the same.
+- `OriginRequiredError` (subclass of `ValidationError`), raised for
+  `400 origin_required` with a message explaining the org's embed-domain
+  allowlist and how to pass `origin`.
+- `querri share source org` gained `--disable` to turn org-wide sharing
+  off (the server contract always supported `enabled: false`).
+- `querri keys create` interactive scope picker now includes the
+  `admin:skills:*`, `admin:library:*` scopes and `*` (superadmin).
+
+### Fixed
+
+- `client.embed.revoke_user_sessions()` no longer stops at the first
+  listing page: the server caps listings at 200 with no cursor, so it now
+  loops revoke-and-relist until a listing shows no sessions for the user
+  (bounded at 50 passes), and tolerates a session expiring between list
+  and delete. Still best-effort — with more than 200 concurrent sessions
+  org-wide the listing is a sample and stragglers can survive; do not
+  treat a return as proof every session is gone.
+
+## 1.1.1 (2026-08-31)
+
+### Fixed
+
+- **Web-embed example** (`examples/web-embed/server.py`): three dispatched
+  actions called keyword-only SDK methods positionally, raising `TypeError`
+  (returned as HTTP 500): `embed.refreshSession`, `users.getOrCreate`, and
+  `policies.resolve`. All now pass keyword arguments.
+- **Web-embed example** (`examples/web-embed/index.html`): the SDK Explorer's
+  "Data" group sent `data.*` action names the server never dispatched — every
+  action in the group returned "Unknown action". Renamed to the real
+  `sources.*` actions.
+- **Docs**: `docs/server-sdk.md` and `README.md` showed `create_session`,
+  `refresh_session`, and `get_session` with positional parameters; all three
+  are keyword-only (`create_session(*, user_id=..., origin=..., ttl=...)`,
+  `refresh_session(session_token=...)`). Snippets updated to keyword form.
+- **Browser embed loading**: examples and docs now load the embed script from
+  the product — `<script src="{serverUrl}/sdk/querri-embed.js">` — instead of
+  an unverifiable CDN/npm IIFE path. The web-embed example injects the script
+  after fetching `serverUrl` from its `/api/config` endpoint.
+- **Embed chrome options**: examples use the v2 vocabulary
+  (`chrome: { rail: { show: true }, header: { show: true } }` — `rail`
+  replaces `sidebar`).
+- **Origin allowlist guidance**: create-session docs and examples now pass
+  `origin` and document the enforcement behavior — when the organization
+  configures allowed embed domains, session creation without an origin fails
+  with `400 origin_required`, and an origin not on the allowlist fails with
+  `403 origin_not_allowed`.
+
+### Deprecated
+
+- `source_scope` on `client.embed.create_session()` (sync and async): the
+  server does not enforce it, and it will be removed in v2.0.0. Passing it now
+  emits a `DeprecationWarning`; the field is still sent, so behavior is
+  unchanged. Scope sessions with access policies instead — see
+  `client.embed.get_session(access=...)`.

{querri-2.0.0 → querri-2.2.0}/CLAUDE.md

@@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Querri Python SDK — a typed Python client for the Querri API, providing both sync (`Querri`) and async (`AsyncQuerri`) clients. Built on httpx + Pydantic v2. Requires Python >=3.9.
+Querri Python SDK — a typed Python client for the Querri API, providing both sync (`Querri`) and async (`AsyncQuerri`) clients. Built on httpx + Pydantic v2. Requires Python >=3.10.
 
 ## Commands
 
@@ -37,7 +37,7 @@ ruff check querri/ tests/
 `Querri` / `AsyncQuerri` (`_client.py`) are the public entry points. They hold lazily-initialized resource namespaces (e.g., `client.users`, `client.projects`) and support context-manager usage. They delegate HTTP to `SyncHTTPClient` / `AsyncHTTPClient` (`_base_client.py`), which handle auth headers (Bearer token + X-Tenant-ID), retries with exponential backoff, and error-to-exception mapping.
 
 ### User-Scoped Client
-`UserQuerri` / `AsyncUserQuerri` (`_user_client.py`) are created via `client.as_user(session)`. They use `X-Embed-Session` auth against the internal API (`/api` instead of `/api/v1`). Only expose FGA-filtered resources: `projects`, `dashboards`, `sources`, `data`, `chats`.
+`UserQuerri` / `AsyncUserQuerri` (`_user_client.py`) are created via `client.as_user(session)`. They use `X-Embed-Session` auth against the same public API (`/api/v1`) as the admin client. Only expose FGA-filtered resources: `projects`, `dashboards` (read-only), `sources`, `chats`. Calls are subject to the session's role and can raise `PermissionError` (`permission_denied`).
 
 ### Resource Pattern
 Each API resource lives in `querri/resources/` with paired sync/async classes (e.g., `Users` / `AsyncUsers`). Resources receive the HTTP client at init and expose CRUD methods that return Pydantic models from `querri/types/`. Projects has a nested `Chats` sub-resource for chat streaming.
@@ -88,8 +88,8 @@ Every resource, pagination class, and stream has mirrored sync/async implementat
 
 ## Code Quality
 
-- **mypy**: Strict mode, target Python 3.9
-- **ruff**: Rules E, F, I, N, UP, B, SIM (target Python 3.9)
+- **mypy**: Strict mode, target Python 3.10
+- **ruff**: Rules E, F, I, N, UP, B, SIM (target Python 3.10)
 - **Tests**: pytest + pytest-asyncio (mode: auto) + respx for HTTP mocking
 
 ## Releasing

{querri-2.0.0 → querri-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: querri
-Version: 2.0.0
+Version: 2.2.0
 Summary: Python SDK and CLI for the Querri data analysis platform
 Project-URL: Homepage, https://querri.com
 Project-URL: Documentation, https://docs.querri.com/sdk/python
@@ -257,6 +257,32 @@ session["expires_in"]     # int — seconds until expiry
 session["user_id"]        # str — Querri user ID
 ```
 
+To run the session as one of your org's **Custom Roles**, pass `role` (a role
+id or key); the result carries `role_id` when it was applied:
+
+```python
+session = client.embed.get_session(user="customer-42", role="analyst")
+session.get("role_id")    # str — present only when a role was applied
+```
+
+`role_id` is a custom role's id (`role_…`) or a built-in role's
+(`system:creator`). No `role_id` means the role was not applied — an older
+server ignores `role`, and the session runs as the user's own role.
+
+`role` is not `user["role"]` (the org role, `admin`/`member`, used when the
+user is created). **Decide `role` on your server from your own auth — never
+read it from the browser's request.** Granting a role the user does not yet
+hold needs an API key with the `embed:role:assign` scope, and **the grant is
+permanent**: the role is added to the user's assignment, so their later
+sessions and the Querri app see it, and revoking the session does not remove
+it (an admin removes it in Settings → People). Failures raise
+`NotFoundError` (`role_not_found`) or `PermissionError` (`role_not_allowed`,
+`role_disabled`, `insufficient_scope`, `seat_change_required`). The user is
+created/updated and access policies applied before the session is requested,
+so if the role is refused those steps have still happened. On servers
+released after 2026-10-21, creating that user can itself be refused
+(`escalation_denied`, `last_admin` — see below).
+
 You can also pass pre-created policy IDs directly:
 
 ```python
@@ -290,6 +316,7 @@ See **[docs/server-sdk.md](docs/server-sdk.md#user-scoped-client-as_user)** for
 | `client.projects.chats` | Chats within projects | `create`, `list`, `get`, `stream`, `cancel`, `delete` |
 | `client.sources` | Sources, connectors & data | `list`, `create`, `create_data_source`, `query`, `source_data`, `append_rows`, `replace_data`, `ask`, `sync`, `list_connectors` |
 | `client.views` | SQL-defined views | `list`, `create`, `get`, `update`, `delete`, `run`, `get_run`, `wait_for_run`, `preview`, `chat` |
+| `client.library` | Data Library — graph + librarian agent | `create_library`, `create_collection`, `create_anchor_question`, `create_refining_question`, `link`, `status`, `list_nodes`, `get_node`, `search`, `zoom`, `record_fact`, `chat`, `chat_stream`, `backfill`, `seed_fixture`, `health` |
 | `client.files` | File management | `upload`, `list`, `get`, `delete` |
 | `client.keys` | API key management | `create`, `list`, `get`, `delete` |
 | `client.sharing` | Sharing & permissions | `share_project`, `share_dashboard`, `share_source`, `list_project_shares`, `list_dashboard_shares`, `revoke_project_share`, `revoke_dashboard_share`, `org_share_source` |
@@ -317,7 +344,7 @@ All errors extend `QuerriError`:
 ```
 QuerriError
 ├── APIError                — HTTP error responses
-│   ├── ValidationError     — 400
+│   ├── ValidationError     — 400 / 422
 │   │   └── OriginRequiredError — 400 origin_required (org has an embed-domain allowlist)
 │   ├── AuthenticationError — 401
 │   ├── PermissionError     — 403
@@ -329,10 +356,40 @@ QuerriError
 └── ConfigError             — missing/invalid configuration
 ```
 
+Every `APIError` carries `status`, `message`, `type`, `code`, `doc_url`,
+`request_id` and `body` (the parsed JSON response, `None` when it was not
+JSON — it holds the fields the exception does not lift out, e.g.
+`e.body["detail"]["error"]["scopes"]` on `scope_exceeds_role`). A `403
+permission_denied` (the caller's role does not allow the action) also carries
+`permission` and `reason` (`role_denied`, `not_in_plan`, `flag_off`,
+`embed_disabled`, `dependency_unmet`, `forbidden`, `scope_exceeds_role` — the
+server may add more). On servers
+released after 2026-10-21, `client.users` `create` / `update` / `delete` /
+`get_or_create` — and `get_session()` for a new user — can raise
+`PermissionError` (`escalation_denied`, the permissions you lack in
+`e.body["detail"]["error"]["missing"]`) or `ConflictError` (`last_admin`).
+Compare `code` against the
+exported constants (they cover authentication, access, Custom Roles and embed
+sessions; the API sends other codes too, so treat `code` as a string):
+
+```python
+from querri import PermissionError, PERMISSION_DENIED  # shadows the builtin
+
+try:
+    client.dashboards.list()
+except PermissionError as e:
+    if e.code == PERMISSION_DENIED:
+        print(f"needs {e.permission} ({e.reason})")
+```
+
+See [docs/server-sdk.md](docs/server-sdk.md#error-codes) for the code table.
+
 The SDK automatically retries **429** (always) and **5xx** (idempotent methods only) with exponential backoff + jitter.
 
 ### Full Reference
 
+Custom roles can be managed as code (export, edit, `querri role apply -f role.json --watch`): see **[docs/roles.md](docs/roles.md)**.
+
 See **[docs/server-sdk.md](docs/server-sdk.md)** for complete method signatures, all framework examples, and the `get_session()` deep dive.
 
 ---

{querri-2.0.0 → querri-2.2.0}/README.md

@@ -211,6 +211,32 @@ session["expires_in"]     # int — seconds until expiry
 session["user_id"]        # str — Querri user ID
 ```
 
+To run the session as one of your org's **Custom Roles**, pass `role` (a role
+id or key); the result carries `role_id` when it was applied:
+
+```python
+session = client.embed.get_session(user="customer-42", role="analyst")
+session.get("role_id")    # str — present only when a role was applied
+```
+
+`role_id` is a custom role's id (`role_…`) or a built-in role's
+(`system:creator`). No `role_id` means the role was not applied — an older
+server ignores `role`, and the session runs as the user's own role.
+
+`role` is not `user["role"]` (the org role, `admin`/`member`, used when the
+user is created). **Decide `role` on your server from your own auth — never
+read it from the browser's request.** Granting a role the user does not yet
+hold needs an API key with the `embed:role:assign` scope, and **the grant is
+permanent**: the role is added to the user's assignment, so their later
+sessions and the Querri app see it, and revoking the session does not remove
+it (an admin removes it in Settings → People). Failures raise
+`NotFoundError` (`role_not_found`) or `PermissionError` (`role_not_allowed`,
+`role_disabled`, `insufficient_scope`, `seat_change_required`). The user is
+created/updated and access policies applied before the session is requested,
+so if the role is refused those steps have still happened. On servers
+released after 2026-10-21, creating that user can itself be refused
+(`escalation_denied`, `last_admin` — see below).
+
 You can also pass pre-created policy IDs directly:
 
 ```python
@@ -244,6 +270,7 @@ See **[docs/server-sdk.md](docs/server-sdk.md#user-scoped-client-as_user)** for
 | `client.projects.chats` | Chats within projects | `create`, `list`, `get`, `stream`, `cancel`, `delete` |
 | `client.sources` | Sources, connectors & data | `list`, `create`, `create_data_source`, `query`, `source_data`, `append_rows`, `replace_data`, `ask`, `sync`, `list_connectors` |
 | `client.views` | SQL-defined views | `list`, `create`, `get`, `update`, `delete`, `run`, `get_run`, `wait_for_run`, `preview`, `chat` |
+| `client.library` | Data Library — graph + librarian agent | `create_library`, `create_collection`, `create_anchor_question`, `create_refining_question`, `link`, `status`, `list_nodes`, `get_node`, `search`, `zoom`, `record_fact`, `chat`, `chat_stream`, `backfill`, `seed_fixture`, `health` |
 | `client.files` | File management | `upload`, `list`, `get`, `delete` |
 | `client.keys` | API key management | `create`, `list`, `get`, `delete` |
 | `client.sharing` | Sharing & permissions | `share_project`, `share_dashboard`, `share_source`, `list_project_shares`, `list_dashboard_shares`, `revoke_project_share`, `revoke_dashboard_share`, `org_share_source` |
@@ -271,7 +298,7 @@ All errors extend `QuerriError`:
 ```
 QuerriError
 ├── APIError                — HTTP error responses
-│   ├── ValidationError     — 400
+│   ├── ValidationError     — 400 / 422
 │   │   └── OriginRequiredError — 400 origin_required (org has an embed-domain allowlist)
 │   ├── AuthenticationError — 401
 │   ├── PermissionError     — 403
@@ -283,10 +310,40 @@ QuerriError
 └── ConfigError             — missing/invalid configuration
 ```
 
+Every `APIError` carries `status`, `message`, `type`, `code`, `doc_url`,
+`request_id` and `body` (the parsed JSON response, `None` when it was not
+JSON — it holds the fields the exception does not lift out, e.g.
+`e.body["detail"]["error"]["scopes"]` on `scope_exceeds_role`). A `403
+permission_denied` (the caller's role does not allow the action) also carries
+`permission` and `reason` (`role_denied`, `not_in_plan`, `flag_off`,
+`embed_disabled`, `dependency_unmet`, `forbidden`, `scope_exceeds_role` — the
+server may add more). On servers
+released after 2026-10-21, `client.users` `create` / `update` / `delete` /
+`get_or_create` — and `get_session()` for a new user — can raise
+`PermissionError` (`escalation_denied`, the permissions you lack in
+`e.body["detail"]["error"]["missing"]`) or `ConflictError` (`last_admin`).
+Compare `code` against the
+exported constants (they cover authentication, access, Custom Roles and embed
+sessions; the API sends other codes too, so treat `code` as a string):
+
+```python
+from querri import PermissionError, PERMISSION_DENIED  # shadows the builtin
+
+try:
+    client.dashboards.list()
+except PermissionError as e:
+    if e.code == PERMISSION_DENIED:
+        print(f"needs {e.permission} ({e.reason})")
+```
+
+See [docs/server-sdk.md](docs/server-sdk.md#error-codes) for the code table.
+
 The SDK automatically retries **429** (always) and **5xx** (idempotent methods only) with exponential backoff + jitter.
 
 ### Full Reference
 
+Custom roles can be managed as code (export, edit, `querri role apply -f role.json --watch`): see **[docs/roles.md](docs/roles.md)**.
+
 See **[docs/server-sdk.md](docs/server-sdk.md)** for complete method signatures, all framework examples, and the `get_session()` deep dive.
 
 ---

querri-2.2.0/docs/data-library.md

@@ -0,0 +1,185 @@
+# Data Library — CLI + SDK reference
+
+The Data Library is Querri's knowledge-graph + semantic-search layer over Collections, Questions, Sources, Views, KPIs, and Facts. The `querri library` CLI subcommand + `client.library` SDK resource expose the full surface.
+
+This doc is the user-facing reference. For module-level architecture see [`~/Q/Querri/server-api/querri_core/library/MODULE.md`](https://github.com/Querri-inc/server-api/blob/feat/data-overview/server-api/querri_core/library/MODULE.md) and the program-level [`documentation/data-library/`](https://github.com/Querri-inc/server-api/tree/feat/data-overview/documentation/data-library).
+
+## Auth + setup
+
+```bash
+export QUERRI_API_KEY=qk_...
+export QUERRI_ORG_ID=<tenant-id>      # required for API-key auth
+export QUERRI_HOST=http://localhost   # dev; production defaults to https://app.querri.com
+```
+
+Most commands take `--library-id` explicitly. To save typing, set an active library once and subsequent commands pick it up:
+
+```bash
+querri library use lib_<tenant-id>_<uuid>
+```
+
+The active library is stored in `~/.querri/library_context.json`. Override per-call with `--library-id` or `QUERRI_LIBRARY_ID`.
+
+## Quick start — the demo path
+
+```bash
+# 1. Create a library and select it.
+querri library create-library "Primary Library"
+querri library use <library-id-printed-above>
+
+# 2. Seed it with realistic demo data (5 collections, 16 sources, ~150 series).
+querri library seed-demo --fixture demo-acme
+
+# 3. Inspect.
+querri library status
+querri library list Collection
+querri library list ViewStub
+
+# 4. Search semantically.
+querri library search "customer churn signals"
+querri library zoom "marketing attribution by channel" --zoom 50 --explain
+
+# 5. Chat with the Librarian agent.
+querri library chat "What collections relate to revenue?" --new --show-tools
+
+# 6. Record a Fact (CLI-direct OR via the agent).
+querri library record-fact \
+  "orders.status enum gained 'awaiting_carrier' in Mar 2026" \
+  --attach <source-node-id> --kind data_quality
+
+# 7. Have the agent commission a new view.
+querri library chat \
+  "Commission a view called orders_by_country that sums total_amount grouped by shipping_country, using the orders source. Build it." \
+  --show-tools
+```
+
+## CLI reference
+
+All commands accept `--json` (a top-level flag, e.g. `querri --json library status`) for scripting.
+
+### Workspace state
+
+| Command | What it does |
+|---|---|
+| `querri library use <library-id>` | Set active library (persists across invocations). |
+| `querri library status [--library-id <id>]` | Counts per node_kind + tenant + total. |
+| `querri library health` | Tenant-scoped health probe (Mongo doc count, embedding model). |
+
+### Create
+
+| Command | What it does |
+|---|---|
+| `querri library create-library <name> [--summary <s>]` | New `Library` node. |
+| `querri library create-collection <name> [--anchor "<text>"] [--summary <s>]` | New `Collection`. With `--anchor` also mints an `AnchorQuestion` + the `anchor_of` edge in one call. |
+| `querri library create-question <text> [--refining] [--name <n>]` | Anchor question by default; pass `--refining` for a `RefiningQuestion`. |
+| `querri library add-refining <anchor-id> "<text>"` | New `RefiningQuestion` linked to the anchor via `refines`. |
+| `querri library link <a> <b> <relation> [--weight X] [--confidence X]` | Bidirectional edge between two existing nodes. `<relation>` is one of `contains`, `anchor_of`, `refines`, `parent_of`, `in_category`, `uses_source`, `uses_view`, `connector_provides`, `view_built_from`, `series_in`, `about`, `semantic_neighbor`, `mentions`. |
+
+### Read
+
+| Command | What it does |
+|---|---|
+| `querri library get <node-id>` | Fetch a single node by id. |
+| `querri library list <node-kind> [--limit N]` | All nodes of a given kind in the active library. |
+| `querri library search <query> [--kind K] [--limit N] [--surface S]` | Vector ANN search — flat top-K, no graph traversal. Fast surface. |
+| `querri library zoom <query> [--zoom N] [--budget N] [--top-k N] [--threshold X] [--kind K] [--explain]` | Vector-seeded multi-focal graph zoom: ANN-resolves focals, BFS up to 2 hops, scores by `edge.confidence × edge.weight × (zoom/100)^hops`. `--explain` prints per-stage latency + algorithm decisions. |
+| `querri library zoom --focal <id> [--focal <id>] [--zoom N]` | Skip ANN; zoom directly from given focal IDs (for iterative drill-in). |
+
+### Write — facts + view commissioning
+
+| Command | What it does |
+|---|---|
+| `querri library record-fact "<statement>" --attach <node-id> [--attach <id>] [--kind <K>] [--evidence <url>] [--confidence X]` | Create a `Fact` node + `about` edges to each `--attach` target. `--kind` is one of `contextual_note` (default), `data_quality`, `timing`, `scope_constraint`. |
+| `querri library chat "<message>" [--new] [--chat-id <id>] [--show-tools]` | Streaming chat with the LibrarianAgent. Three tools available to the agent: `search_graph`, `record_fact`, `commission_view`. `--show-tools` prints tool calls + Views-agent progress dots in real time. Active chat id persists per-library so subsequent calls continue the same conversation; `--new` starts fresh. |
+
+### Bulk / admin
+
+| Command | What it does |
+|---|---|
+| `querri library seed-demo [--fixture <name>]` | Apply a named demo fixture (currently: `demo-acme`). Writes both library_graph stubs AND real legacy `sources` + `connectors` docs so the Views agent can resolve fixture sources. Idempotent. |
+| `querri library backfill [--library-id <id>] [--no-series]` | Walk the tenant's existing `connectors` + `sources` collections and create matching stubs in `library_graph`. Idempotent. |
+
+## SDK reference
+
+Sync (`client.library`) and async (`client.library` on `AsyncQuerri`) have identical surfaces.
+
+```python
+from querri import Querri
+
+client = Querri(api_key="qk_...", org_id="<tenant>", host="http://localhost")
+
+# Workspace
+status = client.library.status(library_id="lib_...")
+print(status.counts_by_kind)            # {"Collection": 8, "Fact": 4, ...}
+
+# Search
+hits = client.library.search(query="churn risk", library_id="lib_...", limit=5)
+for h in hits.results:
+    print(h.score, h.node_kind, h.name)
+
+# Vector-seeded graph zoom
+zoom = client.library.zoom(
+    library_id="lib_...",
+    query="channel attribution and ROI",
+    zoom=50, budget_tokens=2000, top_k_focal=4,
+)
+for f in zoom.focal_nodes:
+    print(f.score, f.confidence_tier, f.node_kind, f.name)
+for n in zoom.subgraph_nodes:
+    print(n.edge_strength, n.hops, "/".join(n.edge_path), n.name)
+
+# Record a fact via the API directly
+fact = client.library.record_fact(
+    library_id="lib_...",
+    statement="orders.status enum gained 'awaiting_carrier' in Mar 2026",
+    fact_kind="data_quality",
+    source_node_ids=["src_..."],
+    evidence_refs=["https://runbooks/orders-status-evolution"],
+    confidence=0.95,
+)
+
+# Chat — drained ChatResponse
+result = client.library.chat(
+    library_id="lib_...",
+    message="What collections relate to revenue?",
+    chat_id=None,                       # omit to start fresh
+)
+print(result.assistant_message)
+print(result.tool_calls)                # list of {name, input, result, duration_ms}
+
+# Chat — streaming events (sync iterator)
+for event in client.library.chat_stream(
+    library_id="lib_...",
+    message="Commission a payment_failures view from the payments source",
+):
+    print(event["type"], event.get("name") or event.get("text", "")[:80])
+```
+
+### Streaming event types
+
+The chat stream yields these `type`s (in order, typically):
+
+| Type | Payload |
+|---|---|
+| `tool_use` | `{tool_use_id, name, input}` — emitted right before each tool call |
+| `tool_progress` | `{tool_use_id, raw}` — pass-through inner-agent SSE chunks during `commission_view` |
+| `tool_result` | `{tool_use_id, name, input, result, duration_ms}` |
+| `assistant_text` | `{text}` — terminal LLM text in the final turn |
+| `done` | `{chat_id, library_id, assistant_message, turns_used, stop_reason, input_tokens, output_tokens, total_ms}` |
+| `error` | `{message}` — stream-level failure |
+
+## Scopes
+
+Library routes require API-key scopes:
+
+| Scope | Routes |
+|---|---|
+| `admin:library:read` | GET `/library/nodes`, `/library/nodes/{id}`, `/library/status`, `/library/health`, POST `/library/search`, `/library/zoom` |
+| `admin:library:write` | POST `/library/libraries`, `/library/collections`, `/library/questions/*`, `/library/edges`, `/library/facts`, `/library/backfill`, `/library/seed-fixture`, `/library/chat` |
+
+The wildcard `*` superadmin scope satisfies both. With JWT auth (the CLI after
+`querri auth login`) the scopes follow your active role (Custom Roles), so
+whether you hold the write scope depends on that role; a Guest role is
+read-only. An API key keeps only the scopes both its creator and its bound
+user currently hold (servers released after 2026-10-21; earlier servers cap
+only keys created in Settings).