xmemcli 0.0.8__tar.gz → 0.0.10__tar.gz

{xmemcli-0.0.8 → xmemcli-0.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: xmemcli
-Version: 0.0.8
+Version: 0.0.10
 Summary: Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools.
 Keywords: api,cli,llm,memory,xmemory
 Requires-Python: <4,>=3.12
@@ -15,7 +15,7 @@ Full command reference is included below.
 ## Usage
 
 ```text
-xmemcli auth login [--no-browser] [--timeout S] [--console-url URL]
+xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--email ADDR [--org-name NAME]]
 xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
@@ -97,25 +97,29 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.8**.
+Version: **0.0.10**.
 
 
 ---
 
-# `xmemcli` auth flow — PKCE handoff and credentials
+# `xmemcli` auth flow — PKCE handoff, email sign-in, and credentials
 
-The CLI is **human-governed for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, but **acquiring an API key** stays under human control in the browser. A key must **never enter the AI transcript** — it is handed to the CLI out-of-band via `xmemcli auth login` or environment / `.xmemrc.json`.
+The CLI is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may even *initiate* key acquisition, but a key is only ever issued after **one explicit human approval** — a click in the browser (PKCE handoff) or an approval of a sign-in email (`--email`). A key must **never enter the AI transcript** — it is handed to the CLI out-of-band via `xmemcli auth login` or environment / `.xmemrc.json`, and the CLI prints only its prefix.
 
-**Model:** the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+Two acquisition paths share `xmemcli auth login`:
 
-> **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`.
+- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+- **Headless email sign-in** (`--email <addr>`): the CLI plays the waiting-browser role of the Console's cross-device email sign-in and then mints its own key — no browser on this machine. See [Email sign-in](#email-sign-in----email) below.
+
+> **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, email `auth login --email`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`, and — for the email path — the Console sign-in and accounts routes listed below (all pre-existing Console surfaces; the email path added no server endpoint).
 
 ## Acquiring a key
 
 The human either:
 
 - **Provides a key they already hold** (`$XMEM_API_KEY`, `.xmemrc.json`, or paste at login), or
-- **Creates a key** in the Console and clicks **"Use this key in the CLI"** (when the page was opened via `/xmemcli/<challenge>`).
+- **Creates a key** in the Console and clicks **"Use this key in the CLI"** (when the page was opened via `/xmemcli/<challenge>`), or
+- **Approves a sign-in email** for an `auth login --email` run, after which the CLI mints its own key.
 
 During **onboarding**, the Console may auto-handoff an onboarding key while a short-lived cookie bridge is active.
 
@@ -137,6 +141,22 @@ CLI ◄── localhost redirect ── redeems code + verifier → writes .xmem
 AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never handles plaintext key
 ```
 
+## Email sign-in — `--email`
+
+`xmemcli auth login --email <addr> [--org-name <name>]` acquires the key with **one human action and no browser on this machine** — the flow an agent-driven IDE uses. The CLI takes the waiting-device role of the Console's cross-device email sign-in; every endpoint below already served the Console before this flag existed. **The fully headless path requires the server to have cross-device hand-off enabled**; a server without it only offers the typed six-digit code, so a run with no interactive terminal is refused there (after cancelling the attempt it had to start to find out).
+
+1. `POST /api/kingdom-signin-request` — the server emails a six-digit code + one-click link; the CLI holds the signed pending cookie **in memory**. The reply's **matching code** is consumed only as the hand-off signal and is not printed (the compare UI is retired across all sign-in surfaces for now).
+2. The human opens the email on any device and Approves. *This is the single human action.*
+3. The CLI claim-polls `POST /api/kingdom-signin-claim` on the Console's own waiting-tab cadence (a short grace, ten fast polls, then a slow poll; transient network failures count as missed polls, not aborts) and exchanges the proof via `POST /api/kingdom-signin-mint` for the browser-session cookie — held **in memory only, never written to disk**.
+4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
+5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
+
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+
+When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
+
+A credential that already resolves (via `/whoami`) to the requested address at the requested origin — checked across `--api-key`, `$XMEM_API_KEY`, and the rc, in that order — short-circuits without sending any email, so re-running the command is free (a matching `$XMEM_API_KEY` is copied into `.xmemrc.json` so the project gains a durable credential; an explicit `--api-key` is never persisted); when the check itself cannot be made (the API is unreachable) the CLI refuses to mint rather than stranding a duplicate key. Every abort of a started attempt — Ctrl+C, timeout, or an error mid-wait — best-effort-cancels it (`POST /api/kingdom-signin-cancel`, retried briefly) and reports what the cancel actually achieved: a **confirmed** cancel of a cross-device attempt makes the emailed link unapprovable; an unconfirmed one is reported as such; and on a hand-off-disabled server the link has nothing durable to revoke — it stays redeemable (in the browser that opens it) until it expires on its own, and the terminal says so.
+
 ## Credential store (`.xmemrc.json`)
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
@@ -151,11 +171,15 @@ Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `-
 
 | Threat | Mitigation |
 | --- | --- |
-| Key in AI transcript | localhost callback → `0600` store; login stdout shows `key_prefix` only |
+| Key in AI transcript | localhost callback / in-process mint → `0600` store; login stdout shows `key_prefix` only |
 | Key in URL | URL carries code only; key over TLS on handoff/token |
 | Captured code replay | PKCE verifier never leaves CLI; code is TTL-bounded |
 | CSRF on callback | state = PKCE challenge; redeem requires verifier |
 | Wrong Console page | CLI button only on `/xmemcli/<challenge>` |
+| Session token outliving the login | the email-path session cookie is held in process memory only — never printed, never on disk — and is discarded when the process exits; the token itself stays server-valid until its ~2-day expiry, so the containment is the CLI never letting it out of memory, not revocation |
+| Session cookie over cleartext | the email path refuses non-`https` Console origins (loopback excepted), refuses every redirect on its cookie-carrying requests, and fails fast when a tunnelled Console marks its cookie `Secure` for an `http://` origin |
+| Unsolicited sign-in email initiation | server-side send limits per mailbox (enforced per server node, so the fleet-wide budget scales with node count); the email itself grants nothing without the inbox owner's Approve, and the CLI best-effort-cancels attempts it cannot complete |
+| Approving someone else's email sign-in | **user-mediated** — the confirmation page leads with "only if this is your address" and states that approving lets the requesting device act on the account, including creating API keys; the stake is higher here than in the browser flow, because approving a CLI-started attempt ends in a durable API key, not a two-day browser session. The matching-code comparison that once narrowed this further is retired for now (the code still travels on the wire but no surface displays it). Approve only sign-ins you started. |
 
 Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding; security rests on PKCE, not port secrecy.
 
@@ -167,9 +191,9 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.8` (see `xmemcli version`)
+**Version:** `0.0.10` (see `xmemcli version`)
 
-`xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
+`xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
 ```bash
 xmemcli …   # installed CLI
@@ -185,7 +209,7 @@ Every command below has dedicated help — see [Help](#help).
 
 | Command | Description |
 |---------|-------------|
-| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. |
+| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted, new objects and links to them are allowed, anything else fails; fast extraction only. |
 | **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. |
 | **`read`** `<query>` | Read from active instance. `--read-mode single\|raw\|xresponse`, `--scope TYPE:ID` (repeatable), `--scope-relations`. |
 
@@ -386,7 +410,7 @@ so a typo fails loudly rather than being ignored.
 
 | Command | Description |
 |---------|-------------|
-| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. |
+| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
 | **`auth logout`** | Remove active `.xmemrc.json` |
 | **`auth status`** | Call `/whoami`. No key → exit 0; bad key → auth error; good key → email + prefix. |
 | **`mcp <instance-id>`** | Serve one instance to an MCP client over stdio, using this CLI's credential. Not for humans — see below. |

{xmemcli-0.0.8 → xmemcli-0.0.10}/README.md

@@ -7,7 +7,7 @@ Full command reference is included below.
 ## Usage
 
 ```text
-xmemcli auth login [--no-browser] [--timeout S] [--console-url URL]
+xmemcli auth login [--no-browser] [--timeout S] [--console-url URL] [--email ADDR [--org-name NAME]]
 xmemcli auth logout
 xmemcli auth status
 xmemcli read <query>
@@ -89,25 +89,29 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **0.0.8**.
+Version: **0.0.10**.
 
 
 ---
 
-# `xmemcli` auth flow — PKCE handoff and credentials
+# `xmemcli` auth flow — PKCE handoff, email sign-in, and credentials
 
-The CLI is **human-governed for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, but **acquiring an API key** stays under human control in the browser. A key must **never enter the AI transcript** — it is handed to the CLI out-of-band via `xmemcli auth login` or environment / `.xmemrc.json`.
+The CLI is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may even *initiate* key acquisition, but a key is only ever issued after **one explicit human approval** — a click in the browser (PKCE handoff) or an approval of a sign-in email (`--email`). A key must **never enter the AI transcript** — it is handed to the CLI out-of-band via `xmemcli auth login` or environment / `.xmemrc.json`, and the CLI prints only its prefix.
 
-**Model:** the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+Two acquisition paths share `xmemcli auth login`:
 
-> **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`.
+- **Browser PKCE handoff** (default): the CLI sends the human to **`/xmemcli/<challenge>`** on the Console, listens on **`127.0.0.1:9636/callback`**, and the Console redirects a signed short-lived **code** (not the key) to that callback.
+- **Headless email sign-in** (`--email <addr>`): the CLI plays the waiting-browser role of the Console's cross-device email sign-in and then mints its own key — no browser on this machine. See [Email sign-in](#email-sign-in----email) below.
+
+> **Scope.** Shipped in this package: `.xmemrc.json` discovery, PKCE `auth login` / `logout` / `status`, email `auth login --email`, `/whoami` consumption, and `quota`. Server endpoints: `POST /cli/handoff`, `POST /cli/token`, and — for the email path — the Console sign-in and accounts routes listed below (all pre-existing Console surfaces; the email path added no server endpoint).
 
 ## Acquiring a key
 
 The human either:
 
 - **Provides a key they already hold** (`$XMEM_API_KEY`, `.xmemrc.json`, or paste at login), or
-- **Creates a key** in the Console and clicks **"Use this key in the CLI"** (when the page was opened via `/xmemcli/<challenge>`).
+- **Creates a key** in the Console and clicks **"Use this key in the CLI"** (when the page was opened via `/xmemcli/<challenge>`), or
+- **Approves a sign-in email** for an `auth login --email` run, after which the CLI mints its own key.
 
 During **onboarding**, the Console may auto-handoff an onboarding key while a short-lived cookie bridge is active.
 
@@ -129,6 +133,22 @@ CLI ◄── localhost redirect ── redeems code + verifier → writes .xmem
 AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never handles plaintext key
 ```
 
+## Email sign-in — `--email`
+
+`xmemcli auth login --email <addr> [--org-name <name>]` acquires the key with **one human action and no browser on this machine** — the flow an agent-driven IDE uses. The CLI takes the waiting-device role of the Console's cross-device email sign-in; every endpoint below already served the Console before this flag existed. **The fully headless path requires the server to have cross-device hand-off enabled**; a server without it only offers the typed six-digit code, so a run with no interactive terminal is refused there (after cancelling the attempt it had to start to find out).
+
+1. `POST /api/kingdom-signin-request` — the server emails a six-digit code + one-click link; the CLI holds the signed pending cookie **in memory**. The reply's **matching code** is consumed only as the hand-off signal and is not printed (the compare UI is retired across all sign-in surfaces for now).
+2. The human opens the email on any device and Approves. *This is the single human action.*
+3. The CLI claim-polls `POST /api/kingdom-signin-claim` on the Console's own waiting-tab cadence (a short grace, ten fast polls, then a slow poll; transient network failures count as missed polls, not aborts) and exchanges the proof via `POST /api/kingdom-signin-mint` for the browser-session cookie — held **in memory only, never written to disk**.
+4. With the session, the CLI runs the Console onboarding's core sequence: `GET /api/check-user`; when the address has no account, `GET /api/suggest-slug` (server-derived org name, `--org-name` overrides; ignored for an existing account) and `POST /api/public-signup` — **note that creating a new organisation requires the deployment to allow public registration, which the hosted service currently does not**: an existing account gets a key, a new address gets the server's "organisation creation is not available" refusal (the Console's admin-fallback signup arm is not implemented here); then `GET /api/accounts/users/by-email`, `GET /api/accounts/api-roles` (the seeded default role, or the org's only role — an ambiguous set is refused, never guessed), and `POST /api/accounts/api-keys` with **no cluster list** — the key attaches to every cluster the org has at mint time. Clusters created later are attached by a server-side backfill that repairs only keys already linked to every other cluster in the org; an org with no clusters at mint time gets a key attached to nothing. The key is named **`CLI email login (<hostname>, <timestamp>)`** so every mint stays individually identifiable and revocable on the Console's API Keys page.
+5. The key is written to `.xmemrc.json` (0600), stdout carries the prefix only, and the session cookie dies with the process.
+
+The wait is bounded by `--timeout` — 600 seconds for this path by default, which is also a **ceiling**: nothing stays claimable past the server's pending window, so larger values are clamped. The emailed one-click link and six-digit code themselves expire at about five minutes; the wait continues past that because an approval given in time stays claimable, and the terminal says when the emailed artifacts have lapsed. The Console origin must be `https` (or a loopback host, for local development). The Console must also match the API origin the key will be used against: with a non-default `--api-url` the CLI refuses to guess the Console (pass `--console-url` or set `$XMEM_CONSOLE_URL`), and an explicitly named Console that provably mismatches the API origin (mixed loopback-ness, or a default-production half paired with a non-default one) is refused rather than trusted.
+
+When the server offers no matching code on the request reply (cross-device hand-off disabled, no public Console origin configured, or a transient degradation), there is nothing for a headless starter to claim — the emailed link then signs in the *approving* browser — so the CLI falls back to the emailed **six-digit code typed into the terminal** (`POST /api/kingdom-signin-verify`), still a single human action. That fallback needs an interactive stdin; a non-interactive run cancels the attempt it just started (the mode is only known from the server's reply, after the email is on its way) and refuses with instructions — the typed code dies with that cancel, but on such a server the one-click link has nothing durable to revoke and stays redeemable in a browser until it expires (about five minutes), which the terminal states plainly.
+
+A credential that already resolves (via `/whoami`) to the requested address at the requested origin — checked across `--api-key`, `$XMEM_API_KEY`, and the rc, in that order — short-circuits without sending any email, so re-running the command is free (a matching `$XMEM_API_KEY` is copied into `.xmemrc.json` so the project gains a durable credential; an explicit `--api-key` is never persisted); when the check itself cannot be made (the API is unreachable) the CLI refuses to mint rather than stranding a duplicate key. Every abort of a started attempt — Ctrl+C, timeout, or an error mid-wait — best-effort-cancels it (`POST /api/kingdom-signin-cancel`, retried briefly) and reports what the cancel actually achieved: a **confirmed** cancel of a cross-device attempt makes the emailed link unapprovable; an unconfirmed one is reported as such; and on a hand-off-disabled server the link has nothing durable to revoke — it stays redeemable (in the browser that opens it) until it expires on its own, and the terminal says so.
+
 ## Credential store (`.xmemrc.json`)
 
 Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking up from `--rc-dir` / CWD, ceiling `$HOME`.
@@ -143,11 +163,15 @@ Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `-
 
 | Threat | Mitigation |
 | --- | --- |
-| Key in AI transcript | localhost callback → `0600` store; login stdout shows `key_prefix` only |
+| Key in AI transcript | localhost callback / in-process mint → `0600` store; login stdout shows `key_prefix` only |
 | Key in URL | URL carries code only; key over TLS on handoff/token |
 | Captured code replay | PKCE verifier never leaves CLI; code is TTL-bounded |
 | CSRF on callback | state = PKCE challenge; redeem requires verifier |
 | Wrong Console page | CLI button only on `/xmemcli/<challenge>` |
+| Session token outliving the login | the email-path session cookie is held in process memory only — never printed, never on disk — and is discarded when the process exits; the token itself stays server-valid until its ~2-day expiry, so the containment is the CLI never letting it out of memory, not revocation |
+| Session cookie over cleartext | the email path refuses non-`https` Console origins (loopback excepted), refuses every redirect on its cookie-carrying requests, and fails fast when a tunnelled Console marks its cookie `Secure` for an `http://` origin |
+| Unsolicited sign-in email initiation | server-side send limits per mailbox (enforced per server node, so the fleet-wide budget scales with node count); the email itself grants nothing without the inbox owner's Approve, and the CLI best-effort-cancels attempts it cannot complete |
+| Approving someone else's email sign-in | **user-mediated** — the confirmation page leads with "only if this is your address" and states that approving lets the requesting device act on the account, including creating API keys; the stake is higher here than in the browser flow, because approving a CLI-started attempt ends in a durable API key, not a two-day browser session. The matching-code comparison that once narrowed this further is retired for now (the code still travels on the wire but no surface displays it). Approve only sign-ins you started. |
 
 Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding; security rests on PKCE, not port secrecy.
 
@@ -159,9 +183,9 @@ Fixed port **9636** ("xmem" on phone keypad) allows SSH/devcontainer forwarding;
 
 # `xmemcli` — capabilities reference
 
-**Version:** `0.0.8` (see `xmemcli version`)
+**Version:** `0.0.10` (see `xmemcli version`)
 
-`xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-governed for key acquisition**; an AI-assisted IDE may run reads, writes, and inventory once credentials exist. Humans acquire API keys and change quota limits in the **Console UI**.
+`xmemcli` is the command-line client for the **xmemory HTTP API**. It is **human-approved for key acquisition**: an AI-assisted IDE may run reads, writes, and inventory, and may initiate `auth login`, but a key is only issued after one explicit human approval — a click in the Console UI (PKCE handoff) or an approval of a sign-in email (`--email`). Quota limits change only in the **Console UI**. The full acquisition contract is in the auth-flow reference bundled with this package.
 
 ```bash
 xmemcli …   # installed CLI
@@ -177,7 +201,7 @@ Every command below has dedicated help — see [Help](#help).
 
 | Command | Description |
 |---------|-------------|
-| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. |
+| **`write`** `<text>` | Sync write (`POST …/write`). `--extraction fast\|deep` (default `fast`). `--no-wait` queues async write, returns `write_id`. `--scope TYPE:ID` (repeatable) anchors the write to existing objects: only they may be modified/deleted, new objects and links to them are allowed, anything else fails; fast extraction only. |
 | **`write-status`** `<write_id>` … | Poll async writes until terminal or `--timeout` (default 60s). Accepts multiple ids. |
 | **`read`** `<query>` | Read from active instance. `--read-mode single\|raw\|xresponse`, `--scope TYPE:ID` (repeatable), `--scope-relations`. |
 
@@ -378,7 +402,7 @@ so a typo fails loudly rather than being ignored.
 
 | Command | Description |
 |---------|-------------|
-| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. |
+| **`auth login`** | PKCE via Console `/xmemcli/<challenge>` → `.xmemrc.json`. `--no-browser`, `--timeout`, `--console-url`. With `--email ADDR` (+ optional `--org-name`, used only when a new account is created; requires `--email`): headless email sign-in — one emailed approval, then the CLI mints its own org-wide key named `CLI email login (<hostname>, <timestamp>)`; details in the auth-flow reference. New-organisation creation additionally requires the deployment to allow public registration. Payload shapes: a fresh email mint carries `method: email`, `key_name`, `api_role`, and `org_created`; the browser path carries `method: pkce` (no role/org fields); a matching `--api-key` or rc credential short-circuits to `status: already_authorized` with `source`: flag / rc (`persisted: false` on the flag arm, which saves nothing); a matching `$XMEM_API_KEY` is copied into the rc and reports `status: authorized`, `source: environment`. Exit codes follow the standard HTTP contract (401 → 4 with stage `auth`, 403 → 3 with stage `permission`, other HTTP/network/server-state failures → 3). |
 | **`auth logout`** | Remove active `.xmemrc.json` |
 | **`auth status`** | Call `/whoami`. No key → exit 0; bad key → auth error; good key → email + prefix. |
 | **`mcp <instance-id>`** | Serve one instance to an MCP client over stdio, using this CLI's credential. Not for humans — see below. |

{xmemcli-0.0.8 → xmemcli-0.0.10}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "0.0.8"
+version = "0.0.10"
 description = "Command-line client for the xmemory HTTP API: PKCE auth, instances, read/write, schema and XMD tools."
 readme = "README.md"
 requires-python = ">=3.12,<4"

{xmemcli-0.0.8 → xmemcli-0.0.10}/uv.lock

@@ -4,5 +4,5 @@ requires-python = ">=3.12, <4"
 
 [[package]]
 name = "xmemcli"
-version = "0.0.8"
+version = "0.0.10"
 source = { editable = "." }

{xmemcli-0.0.8 → xmemcli-0.0.10}/xmemcli/__init__.py

@@ -1,3 +1,3 @@
 """Standalone xmemcli package (``xmemcli`` console script)."""
 
-__version__ = "0.0.8"
+__version__ = "0.0.10"

{xmemcli-0.0.8 → xmemcli-0.0.10}/xmemcli/_context_cmd.py

@@ -94,6 +94,12 @@ _CONSUMER_HOOK_OUTPUT_LIMIT = 10_000
 #: just fits over the edge.
 MAX_PACK_CHARS = _CONSUMER_HOOK_OUTPUT_LIMIT - 500
 
+#: Sections the server renders per pack (identity, owner, rules, schema, live state).
+#: The footprint is a diagnostic, so a server sending more is not describing a pack this
+#: client received; publishing them unbounded would let a small response build a large
+#: document. Mirrors the renderer's section list rather than any transport limit.
+_MAX_SECTIONS_PER_PACK = 5
+
 
 def _requestable_ids(autoload: tuple[Any, ...], listed: AbstractSet[str]) -> tuple[list[str], list[str]]:
     """Ids the server will accept, and the ones dropped with a reason.
@@ -456,9 +462,94 @@ def _curated_unavailable(entry: Any) -> dict[str, Any]:
     return curated
 
 
+def _curated_pack(entry: Any) -> dict[str, Any]:
+    """One pack's footprint: what it cost, whether it was cut, and where the cost sits.
+
+    Sizes and identity only. The pack's own text is already in ``text``, and republishing
+    section bodies here would hand a caller a second copy of content that the clamp and
+    scrub below bound exactly once.
+
+    Section titles are the server's own headings rather than anything an owner wrote, but
+    they arrive over the wire like everything else here, so they are scrubbed and length-
+    bounded. Not the UTF-16 clamp the pack text also gets — a title is capped at 200 code
+    points, so it cannot reach the limit that clamp exists for. A count that is not a
+    number is published as ``None``: a caller doing arithmetic on it should see a gap, not
+    a zero it cannot distinguish from a section that genuinely cost nothing.
+    """
+    curated: dict[str, Any] = {
+        "instance_id": scrub(entry["instance_id"], limit=200) if isinstance(entry.get("instance_id"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+        "truncated": entry["truncated"] if isinstance(entry.get("truncated"), bool) else None,
+    }
+    raw_sections = entry.get("sections")
+    # Filtered before the cap, not after: slicing first let junk consume the slots, so a
+    # response whose first five entries were nulls published none of the real ones.
+    sections = [s for s in raw_sections if isinstance(s, dict)] if isinstance(raw_sections, list) else []
+    # Bounded as well as filtered. The server renders at most five sections per pack, so
+    # anything beyond that is not a breakdown of anything, and an unbounded array on a
+    # payload whose text is hard-capped is a way for a small response to build a large
+    # document. Not the only one — ``unavailable`` above is still uncapped — but the cap
+    # is cheap where the shape is known.
+    curated["sections"] = [
+        {
+            "title": scrub(section["title"], limit=200) if isinstance(section.get("title"), str) else None,
+            "estimated_tokens": _count(section.get("estimated_tokens")),
+        }
+        for section in sections[:_MAX_SECTIONS_PER_PACK]
+    ]
+    return curated
+
+
+def _curated_universal_rules(entry: Any) -> dict[str, Any] | None:
+    """The response-level rules block's footprint, or ``None`` when the server sent none.
+
+    Published for the same reason the per-pack sections are: this is the one part of the response
+    that belongs to no pack, so a caller summing ``packs`` to account for ``estimated_tokens``
+    comes up short by exactly it. It used to be inside every pack and is now charged once, which
+    is a change someone reading the breakdown to explain a budget needs to see.
+
+    Title and size only, like ``_curated_pack`` — the body is already in ``text``.
+    """
+    if not isinstance(entry, dict):
+        return None
+    return {
+        "title": scrub(entry["title"], limit=200) if isinstance(entry.get("title"), str) else None,
+        "estimated_tokens": _count(entry.get("estimated_tokens")),
+    }
+
+
+def _count(value: Any) -> int | None:
+    """A published token count, or ``None`` when the server sent something that is not one.
+
+    ``bool`` is excluded explicitly because it is a subclass of ``int``: without that,
+    ``"estimated_tokens": true`` published ``true`` and a caller summing the sections
+    added one, which is the arithmetic the ``None`` exists to keep honest. Spelled the
+    same way in ``_pretty.py`` and ``xmem.py``; ``_binding.py`` reaches the same result
+    through the negated form. The idiom appears at several sites in ``cli/`` and each
+    checks something different afterwards (``> 0``, ``>= 0``, ``< 1``), which is why this
+    stays local rather than becoming a shared helper.
+    """
+    return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
 def _nothing_to_inject() -> dict[str, Any]:
-    """The payload for "there is no context to add", used by every such path."""
-    return {"text": "", "instance_ids": [], "unavailable": [], "estimated_tokens": 0}
+    """The payload for "there is no context to add", used by every such path.
+
+    ``max_tokens`` is ``None`` rather than absent: the success path always carries it,
+    and a caller told the shape is stable should not have to test for the key before
+    reading it on the one branch that omitted it.
+    """
+    return {
+        "text": "",
+        "instance_ids": [],
+        "unavailable": [],
+        "estimated_tokens": 0,
+        "max_tokens": None,
+        "packs": [],
+        # Present and null for the same reason ``max_tokens`` is: the success path always carries
+        # the key, and a caller told the shape is stable should not have to test for it.
+        "universal_rules": None,
+    }
 
 
 def _command_budget(args: argparse.Namespace) -> float:
@@ -743,6 +834,23 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # `diff_plan`, anything an internal renderer attaches) cannot arrive here and be
     # published; it is dropped until someone decides it belongs.
     unavailable = [_curated_unavailable(entry) for entry in unavailable]
+    # Shape-checked before iteration for the same reason `items` and `unavailable` above
+    # are: `result.get("packs") or []` keeps whatever truthy value arrived, so
+    # `{"packs": 7}` raised `TypeError` out of the comprehension and the blanket guard
+    # turned a perfectly good, already-clamped pack into an empty payload — the whole
+    # session's context discarded because an optional diagnostic field had the wrong
+    # type. A dict or a string would not even raise: they iterate, and publish phantom
+    # entries. The footprint is a diagnostic, so a bad one costs itself and nothing else.
+    raw_packs = result.get("packs")
+    if raw_packs is not None and not isinstance(raw_packs, list):
+        m._note_cli_warning(args, "xmemory returned an unreadable context footprint; sizes omitted")
+        raw_packs = []
+    # Non-dict elements are skipped rather than curated into all-null entries: a
+    # phantom pack is the outcome the guard above warns about, one level down, and a
+    # caller cannot tell it from an instance that genuinely reported nothing. Capped at
+    # the number of instances the server will accept in one request, for the same reason
+    # the sections are capped.
+    packs = [_curated_pack(p) for p in [p for p in (raw_packs or []) if isinstance(p, dict)][:MAX_REQUESTED_INSTANCES]]
     delivered = [i for i in requested if i not in missing]
     if unavailable:
         m._note_cli_warning(
@@ -769,7 +877,30 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
     # passes the first at 9,500 and measures 19,000 to the second, and Claude Code
     # writes it to a file and injects a preview instead of the context. Bounding the
     # unit the consumer actually counts is what the cap was for.
-    text = clamp_utf16(scrub(text, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # Sanitised first, with a limit that cannot bite, so the two jobs `scrub` performs are
+    # separated: it strips Cc/Cf/Cs characters *and* clamps. Measuring the final text
+    # against the raw server text conflated them — a fully delivered pack carrying one
+    # zero-width joiner, soft hyphen, BOM or bidi mark came out shorter and was reported as
+    # cut, which is a false alarm aimed at exactly the reader who asked why their context
+    # shrank. Only a length cut is a length cut.
+    sanitised = scrub(text, limit=len(text))
+    injected = clamp_utf16(scrub(sanitised, limit=MAX_PACK_CHARS), limit=MAX_PACK_CHARS)
+    # The footprint below describes what the *server* rendered. When this clamp bites, part
+    # of that never reaches the model, and a breakdown still reporting the full sizes with
+    # `truncated: false` misleads precisely the reader it exists for — someone asking why
+    # their live state disappeared, being shown a section that advertises 4,900 tokens and
+    # arrived as nothing. So a client-side cut marks every pack too. The flag means "what
+    # you are reading is not the whole of it", whichever side did the cutting; the warning
+    # names which side, because the fixes are different — retier a binding, or lower
+    # `pack_max_tokens`.
+    if len(injected) < len(sanitised):
+        m._note_cli_warning(
+            args,
+            "the rendered context was longer than this client can inject and was cut; "
+            "the sizes reported describe what xmemory rendered, not what was injected",
+        )
+        packs = [{**pack, "truncated": True} for pack in packs]
+    text = injected
     return (
         CliOutput(
             OutputKind.AGENT_CONTEXT,
@@ -777,8 +908,22 @@ def _context(args: argparse.Namespace, deadline: float) -> tuple[CliOutput, int]
                 "text": text,
                 "instance_ids": delivered,
                 "unavailable": unavailable,
-                "estimated_tokens": result.get("estimated_tokens") or 0,
-                "max_tokens": result.get("max_tokens"),
+                # Through the same guard as the parts: publishing `true` as a total while
+                # the sections it explains correctly read null is the inconsistency the
+                # breakdown exists to avoid.
+                "estimated_tokens": _count(result.get("estimated_tokens")) or 0,
+                "max_tokens": _count(result.get("max_tokens")),
+                # Where the total sits, per instance and per section. The total alone says a
+                # pack was expensive or was cut; only the breakdown says which instance spent
+                # the budget and what a shrink took, which is what someone asking "why is my
+                # context so big" or "why did my live state disappear" is actually asking.
+                # Curated the way `unavailable` is, so a section body cannot arrive by this
+                # route and bypass the clamp the pack text goes through.
+                "packs": packs,
+                # The part of the total that belongs to no pack: the operating rules, carried once
+                # for the response rather than repeated in each pack. Without it the breakdown
+                # cannot account for its own total.
+                "universal_rules": _curated_universal_rules(result.get("universal_rules")),
             },
         ),
         m.EXIT_OK,