querri 2.1.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.1.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.1.0 → querri-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: querri
-Version: 2.1.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
@@ -318,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
@@ -330,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.1.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
@@ -272,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
@@ -284,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.1.0 → querri-2.2.0}/docs/data-library.md

@@ -177,4 +177,9 @@ Library routes require API-key scopes:
 | `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. JWT auth gives both scopes to `member` role.
+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).

querri-2.2.0/docs/roles.md

@@ -0,0 +1,151 @@
+# Custom roles as code — CLI + SDK reference
+
+A Querri custom role is a JSON **definition document** identified by a stable `key`, much like an AWS IAM policy. You export it, edit it in your editor, and apply it back in one call. Apply is an idempotent upsert: it creates the role when the key is new, replaces it when the key exists, and reports `unchanged` when nothing differs.
+
+The `querri role` command (`querri roles` works too) and the `client.roles` SDK resource expose the full surface.
+
+## Auth + setup
+
+Roles-as-code calls need an API key with the roles scopes:
+
+| Scope | Allows |
+|---|---|
+| `admin:roles:read` | `list`, `get`, `catalog`, `export` |
+| `admin:roles:write` | `apply`, `import`, `delete` |
+
+An admin creates a key with those scopes in **Settings → API Keys** (or `querri key new` and pick the **Roles** group). The person behind the key must also hold `admin.roles.manage`.
+
+A key never does more than its person. A role may not grant a permission the caller does not hold; the server refuses that with 403 `escalation_denied`.
+
+```bash
+export QUERRI_API_KEY=qk_...
+export QUERRI_ORG_ID=org_...
+```
+
+## The workflow
+
+```bash
+# 1. Export the custom roles (system roles are left out) to a file.
+querri role export -o roles.json
+
+# Or export one role.
+querri role get ev-datapro > ev.json
+
+# 2. Preview what an edit would change. Nothing is written.
+querri role apply -f ev.json --dry-run
+
+# 3. Apply it, and keep applying on every save.
+querri role apply -f ev.json --watch
+```
+
+With `--watch` running, open the app in another browser as someone who holds the role, edit `ev.json`, and save: the role updates within about a second. Each apply prints what changed:
+
+```
+ev-datapro: updated  denies: +chat.code.view -tools.dashboards.use
+ev-datapro: updated  config.home_chat: "chat" -> "project"
+ev-datapro: unchanged
+```
+
+Press Ctrl-C to stop watching. A file that is mid-save or holds invalid JSON prints an error and the watch keeps going.
+
+## The definition document
+
+```json
+{
+  "schema": "querri.role/v1",
+  "key": "ev-datapro",
+  "name": "EV DataPro",
+  "description": "Estrenar Vivienda end users: projects only, charts on request",
+  "base": "creator",
+  "enabled": true,
+  "grants": [],
+  "denies": ["tools.charts.use", "chat.code.view", "chat.tables.view"],
+  "settings": {"chat.think_longer.use": {"default": "fast", "user_can_change": false}},
+  "config": {"home_chat": "project"}
+}
+```
+
+| Field | Notes |
+|---|---|
+| `schema` | Optional on input; always `querri.role/v1` on output. Any other value is refused (422 `unsupported_schema`). |
+| `key` | `^[a-z0-9][a-z0-9-]{0,47}$`. The built-in keys `guest`, `creator`, `admin` cannot be applied or deleted (405 `system_role_immutable`). |
+| `name` | Required, 1-80 characters, unique per org ignoring case (409 `name_taken`). |
+| `base` | `guest`, `creator` or `admin` (default `creator`). The role starts from this and adds `grants` / removes `denies`. |
+| `enabled` | Default `true`. |
+| `grants` / `denies` | Permission keys from `querri role catalog`. Normalised by the server: a grant the base already has, or a deny the base lacks, is dropped. |
+| `settings` | `{permission_key: {"default": ..., "user_can_change": bool}}` for setting-kind permissions. |
+| `config` | `home_chat`, `landing`, `credits_monthly`, `context_overrides`, `theme`, `support_contact`, `access_policy_ids`, with the same validation as Settings → Roles. |
+
+The API also returns `id`, `system`, `seat_class`, `user_count` and `updated_at`. They are output only: the server ignores them on input, and `get` and `export` leave them out of what they write.
+
+### File formats
+
+`querri role apply -f` reads JSON that holds any of:
+
+- one definition: applied with `PUT /roles/{key}`
+- a list of definitions, or `{"roles": [...]}` (what `export` writes): applied with one `POST /roles/import` call, in order. Each role succeeds or fails on its own.
+
+YAML is not supported. The SDK does not depend on PyYAML.
+
+`apply` exits non-zero when any role failed, so it is safe to use in CI.
+
+## CLI reference
+
+| Command | What it does |
+|---|---|
+| `querri role list` | Table of every role: key, name, base, enabled, users, system. |
+| `querri role get REF` | The role's definition as JSON (`REF` is a key or ID). |
+| `querri role export [-o PATH] [--include-system]` | `{"roles": [...]}` for the custom roles. |
+| `querri role apply -f PATH [--dry-run] [--watch]` | Create or update roles from a file. |
+| `querri role delete REF [--reassign-to KEY] [--yes]` | Delete a role. Asks first unless `--yes`. |
+| `querri role catalog [--area AREA]` | Permission keys: key, area, kind, default per base role, requires. |
+
+Deleting a role that some people hold as their only role needs `--reassign-to` (409 `role_in_use` otherwise).
+
+All commands take the global `--json` flag.
+
+## SDK reference
+
+```python
+from querri import Querri
+
+client = Querri()
+
+# Read
+roles = client.roles.list()             # every role, system ones included
+role = client.roles.get("ev-datapro")   # RoleDefinition
+catalog = client.roles.catalog()        # PermissionCatalog
+
+# Export what you would save to a file and re-apply
+definitions = client.roles.export()     # list[dict], output-only fields stripped
+
+# Apply one (dict or RoleDefinition); the key comes from the definition
+result = client.roles.apply(
+    {"key": "ev-datapro", "name": "EV DataPro", "denies": ["chat.code.view"]},
+    dry_run=True,
+)
+print(result.action)                    # would_create / would_update / unchanged
+for change in result.changes:
+    print(change.field, change.before, "->", change.after)
+
+# Apply several in one call
+out = client.roles.import_roles(definitions)
+if out.failed:
+    for r in out.results:
+        if r.failed:
+            print(r.key, r.error.code, r.error.message)
+
+# Delete
+client.roles.delete("ev-datapro", reassign_to="creator")
+```
+
+`AsyncQuerri` has the same methods on `client.roles`, awaited.
+
+`apply` raises `ValueError` when the definition has no `key`. Errors from the server raise the usual `APIError` subclasses. For example, `escalation_denied` raises `PermissionError`, and `name_taken` and `role_in_use` raise `ConflictError`.
+
+| `result.action` | Meaning |
+|---|---|
+| `created` / `updated` | Written. |
+| `unchanged` | The stored role already matches. |
+| `would_create` / `would_update` | Dry run: what an apply would do. |
+| `failed` | Import only: `result.error` has `code` and `message`. |