xmemcli 1.0.0__tar.gz → 1.2.0__tar.gz

{xmemcli-1.0.0 → xmemcli-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: xmemcli
-Version: 1.0.0
+Version: 1.2.0
 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
@@ -22,6 +22,8 @@ xmemcli read <query>
 xmemcli write <text>
 xmemcli write-status <write_id> [<id> …]
 xmemcli quota
+xmemcli instance templates
+xmemcli instance create --name NAME (--template ID | --schema-file PATH | --schema-stdin)
 xmemcli binding list [--autoload]
 xmemcli binding add <instance_id> [--tier autoload|available|off] [--scope project|user]
 xmemcli binding remove <instance_id> [--scope project|user]
@@ -30,7 +32,7 @@ xmemcli context [--text] [--max-tokens N] [--no-live-state]
 
 Global flags / env: `--api-key` / `$XMEM_API_KEY`, `--instance-id` / `$XMEM_INSTANCE_ID`, `--api-url` / `$XMEM_API_URL`, `--rc-dir` / `$XMEM_RC_DIR`, `--binding-dir` / `$XMEM_BINDING_DIR`, `--json`, `--verbose`. See `xmemcli help options`.
 
-Credential resolution: `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` (walk up from `--rc-dir` toward `$HOME`). Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default.
+Credential resolution: `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` (walk up from `--rc-dir` toward `$HOME`). Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default. The `mcp` transport resolves its own origin the same way: `--mcp-url` → `$XMEM_MCP_URL` → rc `mcp_url` → default, where `mcp_url` is what the API told `auth login` about itself.
 
 `context` is the exception: it runs unattended from a session-start hook, with no person and no chosen directory behind it, so it resolves the credential from `$HOME` **only** — a project `.xmemrc.json` is used only when `--api-key` / `$XMEM_API_KEY` or `--rc-dir` / `$XMEM_RC_DIR` names it explicitly. That stops a cloned repository shipping the key and origin its own context is fetched with.
 
@@ -97,7 +99,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.0.0**.
+Version: **1.2.0**.
 
 
 ---
@@ -151,7 +153,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 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 only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL` when inference does not apply). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), 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.
+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 only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url`; `$XMEM_CONSOLE_URL` only when `--api-url` was not given). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), 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.
 
@@ -163,12 +165,16 @@ Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking
 
 Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
 
-Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → sibling inference from the call's `--api-url` when it applies → `$XMEM_CONSOLE_URL` → sibling inference from `$XMEM_API_URL` → default — when `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
+Since 1.1.0 the file may also carry **`mcp_url`** — the MCP resource the API reported for itself when the key was issued, written only when the server names one. It is what lets `xmemcli mcp` reach an on-premise MCP host: that host is in no table the client was built with, and the rc is the one anchor a cloned `.mcp.json` does not control. A blank or non-string value is read as absent. It outranks the single-origin sibling inference below — a deployment naming itself beats a shape we derived — and both beat the built-in default. The mount path is part of the destination: `https://host/mcp` authorises that mount, not the sibling services beside it — and the instance id is canonicalised as a UUID before it is appended, so nothing following the mount can walk back out of it. Every lookup that reads `mcp_url` refuses redirects rather than merely dropping the credential across them, because what it learns is a host the key is later sent to. Every mutation of the file — write, in-place update, and logout's delete — is serialised under an exclusive lock on its containing directory, and an update is additionally bound to the identity *and* origin it was decided from. What protects an in-place update is that comparison, which is portable; the lock narrows what remains — the moment between comparing and replacing — where the platform offers one. A failed record is a warning, a failed de-authorisation fails the command. The enrichment write after login is conditional on the same comparison, so logging out or signing in again while it is in flight is not undone by it.
+
+Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → Console pinned by a positional (or mistaken `--api-url`) single-origin URL → `$XMEM_CONSOLE_URL` when `--api-url` was *not* given → sibling inference from the call's `--api-url` when it applies → sibling inference from `$XMEM_API_URL` → default. An explicit `--api-url` suppresses `$XMEM_CONSOLE_URL` for that invocation (a five-host `--api-url` without `--console-url` is a usage error, not a fall-through to the env Console). A named API origin from `$XMEM_API_URL` is held to the same infer-or-refuse rule, so an env-only non-default API without a Console cannot mint at the hosted Console and record that key against the foreign API; an inferred sibling that is remote HTTP is refused under the same HTTPS-or-loopback rule as a positional login URL. The same resolved Console is passed to the post-login `/whoami` that records `mcp_url`, so a leftover `$XMEM_CONSOLE_URL` cannot steer that lookup either. When `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
 `xmemcli auth status` calls **`GET /whoami`** with the active bearer key and reports `{authenticated, email, key_prefix}`. Exit `0` when the key resolves; auth error when it does not.
 
+The `AuthApiKey` body also carries **`mcp_url`**, this deployment's own MCP origin (`null` where it serves none). The field is always present, `null` included: an absent key means the server predates it, which is a different answer and is treated as one. `auth login` reads it from there — on both paths, since the email flow never calls `POST /cli/token` — and records it in the rc. The lookup is best-effort: any failure simply leaves the key out of the file, and the transport falls back to its table of shipped API↔MCP pairs.
+
 ## Security model
 
 | Threat | Mitigation |
@@ -193,7 +199,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.0.0` (see `xmemcli version`)
+**Version:** `1.2.0` (see `xmemcli version`)
 
 `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.
 
@@ -236,7 +242,8 @@ Permission-filtered view of what this API key can see.
 | Command | Description |
 |---------|-------------|
 | **`instance get`** `<instance_id>` | Fetch one instance |
-| **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
+| **`instance templates`** | List the ready-made templates a create can name — id, label, one-line description, who each is for, example writes and reads, and the object-type names. No schema crosses the wire; the server holds the shape. |
+| **`instance create`** | Create from a template or an XMD/JSON schema. Required `--name`; then exactly one of `--template <id>`, `--schema-file` or `--schema-stdin`. `--template` sends only the id: no schema is composed, generated or repaired, so the shape you get is exactly the one you picked. |
 | **`instance instructions`** `[instance_id]` `[text]` `[--clear]` | Read, set or clear the instance's standing instructions to an agent — the owner's own words, carried to every agent that connects it. No text and no `--clear` reads and changes nothing. Setting reads the current value first and writes with the epoch it read, so an edit composed against instructions someone has since replaced is refused rather than applied (the console form and the instance chat write the same field). Clearing is `--clear`; an empty string is refused, because that is what a shell substitutes for an unset variable. The id may be pinned with `--instance-id` or `$XMEM_INSTANCE_ID` and the text given alone — a lone positional that is not an id is read as the text. |
 | **`instance setup`** `[instance_id]` `[--format agent\|project]` | How to connect this instance to an agent, ordered for where it is likely to be used. Prints the same steps the `get_setup_instructions` MCP tool gives an agent, so a person and the agent beside them read the same thing. `--format project` additionally prints the shared setup files to commit; each teammate still approves the install and signs in once. Carries no credential. |
 
@@ -270,6 +277,10 @@ XMD (xmemory Data) is the typed schema format for instances. These commands mirr
 #### Typical workflow
 
 ```text
+# 0. Or skip 1-2 entirely: pick a ready-made shape
+xmemcli instance templates
+xmemcli instance create --name demo --template personal_crm
+
 # 1. Synthesize or enhance
 xmemcli xmd generate "people and their pets" -o schema.yml
 xmemcli xmd enhance schema.yml "add a Pet.breed field" -o next.yml --plan-output plan.json
@@ -417,7 +428,7 @@ so a typo fails loudly rather than being ignored.
 | **`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. |
 | **`version`** | CLI release version (no network) |
-| **`status`** | Local health: version + whether `.xmemrc.json` exists (no network) |
+| **`status`** | Local health: version + whether `.xmemrc.json` exists, and the `mcp_url` it declares when it declares one (no network) |
 
 **`mcp` is a transport, not a command you run.** An MCP client starts it and speaks
 JSON-RPC to it over stdio; it forwards each frame to `<mcp-url>/instance/<id>` with this
@@ -430,6 +441,31 @@ It exists because an MCP client can reference an environment variable in an
 connection means nothing is captured when the server is registered, so a configuration
 written today still works in a session opened next week with an empty environment.
 
+**Where a file-held key may be sent.** The MCP origin is configured separately from the API
+origin, and a project `.mcp.json` arrives by `git clone` — it controls that server's `args` and
+`env`, so it is not allowed to vouch for itself. A key read from `.xmemrc.json` therefore reaches
+only the MCP origin that same file records in `mcp_url`, the origin paired with its `api_url` in
+this client's built-in table of shipped deployments, or a loopback host when both ends are on this
+machine. Anywhere else needs a key named on the call with `--api-key`.
+
+A recorded origin says *where*, never *how*: a remote one must be `https`, so a hand-written
+`http://` entry is refused rather than sending the key in clear text. Loopback stays exempt — those
+bytes never leave the machine.
+
+The **mount path is part of the destination**, not decoration. A deployment serving every route
+group on one hostname puts MCP at `https://host/mcp`, the REST API at `https://host/xmem` and the
+OAuth server at `https://host/oauth2`; an rc recording the first authorises the first only.
+
+`auth login` fills in `mcp_url` from what the API reports about itself, which is what makes an
+on-premise deployment work: its MCP host is in no table this client was built with, and every
+attempt to *derive* one host from the other has been wrong in a new way. If the transport refuses
+an origin you expect it to accept, run `auth login` against that deployment again — the rc predates
+the field, or that server does not report one. That works even when the stored key is still good:
+the `--email` path records the origin it learns while checking, and reports it as `mcp_url` on the
+`already_authorized` payload. A deployment that has stopped serving MCP answers `null`, and the
+recorded origin is dropped rather than left authorised — and if that removal cannot be written,
+the command fails rather than reporting success over a host that is still authorised.
+
 Two consequences worth knowing:
 
 - **stdout is the protocol.** Alone among these commands it emits no JSON document and
@@ -515,15 +551,21 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
+**New in 1.2.0:** `instance templates` lists the ready-made instance shapes the service ships, with the prose to choose between them, and `instance create --template <id>` builds one from a pinned schema the server already holds. No schema is generated on that path: no description to compose, no `xmd generate` hop, and the instance comes out identical to the one the console would have made from the same template. (Creating an instance still generates its agent brief afterwards, on this path as on any other.)
+
+**New in 1.1.0:** `auth login` records the deployment's own MCP origin in `.xmemrc.json` as `mcp_url` (omitted where the server reports none), and `mcp` both connects there by default and accepts it as the pair its key may reach. Requires 0.0.12 or newer to read such a file — see the note below.
+
 **Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
 
 **Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit `--console-url` / `--mcp-url` and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win when inference does not apply; on a call that names `--api-url …/xmem`, sibling inference beats `$XMEM_CONSOLE_URL`; the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
 
-Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere. On a single-origin deployment they also rely on path inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — and an older CLI given that command signs in at the hosted Console instead. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere, and **1.1.1** on a single-origin deployment — earlier releases let `$XMEM_CONSOLE_URL` steer sign-in and token redemption to a foreign Console. On a single-origin deployment they render `auth login --api-url https://host/xmem` with **no** `--console-url`. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
 
-**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form, and the CLI writes the inferred ``api_url`` into ``.xmemrc.json`` as soon as login starts.
+**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form. When no ``.xmemrc.json`` exists yet, the CLI stages the inferred ``api_url`` into a placeholder rc as soon as login starts; an existing credential file is never rewritten mid-login. Remote plain HTTP is refused (HTTPS or loopback only) — the same rule as the plain URLs below.
 
-**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions.
+**Plain single-origin login URLs (1.1.1+):** `xmemcli auth login https://host/console` or `…/xmem` (trailing slash optional) infer the same sibling pair with no instance id — useful when signing in before you have an instance page open. Remote plain HTTP is refused (HTTPS or loopback only). An existing `.xmemrc.json` credential is never rebound mid-login; only a missing rc gets a placeholder `api_url`.
+
+**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions. **Revised in 1.1.1:** staging writes only a placeholder when no rc exists (an existing credential file is left alone until login succeeds); single-origin connect instructions name **1.1.1** as their minimum — earlier releases let `$XMEM_CONSOLE_URL` steer the sign-in Console; and HTTPS-or-loopback now applies to every single-origin login URL, including instance pages, not only the new `/console` and `/xmem` forms. A mistaken `--api-url http://host/xmem` is refused the same way.
 
 See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
@@ -614,7 +656,7 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
-**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings, plus an optional `mcp_url` recorded by `auth login`. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
 
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
@@ -628,6 +670,8 @@ and each delivery mechanism turned out to be a fresh bypass.
 
 **Origin resolution:** `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **with one escape hatch**: when the key comes from `--api-key` / `$XMEM_API_KEY` (not from the rc), the rc's `api_url` is **not** consulted and the origin falls back to the built-in default (`https://api.xmemory.ai`) unless you also set `--api-url` / `$XMEM_API_URL`. That keeps an explicitly supplied key from being silently paired with an unrelated origin in a project `.xmemrc.json`. If `$XMEM_API_KEY` is set without `$XMEM_API_URL`, the CLI warns once per invocation.
 
+**MCP origin resolution (`mcp` only):** `--mcp-url` → `$XMEM_MCP_URL` → the rc's `mcp_url` → default (`https://mcp.xmemory.ai`). The rc rung follows the same escape hatch as the API origin: a key named with `--api-key` / `$XMEM_API_KEY` never inherits an origin from a project file.
+
 **Instance resolution (read/write):** `--instance-id` → `$XMEM_INSTANCE_ID` → if exactly **one** instance is visible, auto-select with a **stderr warning** → else error.
 
 **Output:** Pipes and non-TTY stdout → JSON. Interactive TTY → one-line summaries unless `--json`.

{xmemcli-1.0.0 → xmemcli-1.2.0}/README.md

@@ -14,6 +14,8 @@ xmemcli read <query>
 xmemcli write <text>
 xmemcli write-status <write_id> [<id> …]
 xmemcli quota
+xmemcli instance templates
+xmemcli instance create --name NAME (--template ID | --schema-file PATH | --schema-stdin)
 xmemcli binding list [--autoload]
 xmemcli binding add <instance_id> [--tier autoload|available|off] [--scope project|user]
 xmemcli binding remove <instance_id> [--scope project|user]
@@ -22,7 +24,7 @@ xmemcli context [--text] [--max-tokens N] [--no-live-state]
 
 Global flags / env: `--api-key` / `$XMEM_API_KEY`, `--instance-id` / `$XMEM_INSTANCE_ID`, `--api-url` / `$XMEM_API_URL`, `--rc-dir` / `$XMEM_RC_DIR`, `--binding-dir` / `$XMEM_BINDING_DIR`, `--json`, `--verbose`. See `xmemcli help options`.
 
-Credential resolution: `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` (walk up from `--rc-dir` toward `$HOME`). Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default.
+Credential resolution: `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` (walk up from `--rc-dir` toward `$HOME`). Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default. The `mcp` transport resolves its own origin the same way: `--mcp-url` → `$XMEM_MCP_URL` → rc `mcp_url` → default, where `mcp_url` is what the API told `auth login` about itself.
 
 `context` is the exception: it runs unattended from a session-start hook, with no person and no chosen directory behind it, so it resolves the credential from `$HOME` **only** — a project `.xmemrc.json` is used only when `--api-key` / `$XMEM_API_KEY` or `--rc-dir` / `$XMEM_RC_DIR` names it explicitly. That stops a cloned repository shipping the key and origin its own context is fetched with.
 
@@ -89,7 +91,7 @@ xmemcli version
 xmemcli auth login
 ```
 
-Version: **1.0.0**.
+Version: **1.2.0**.
 
 
 ---
@@ -143,7 +145,7 @@ AI-assisted IDE ── xmemcli read/write ──► CLI resolves key; never hand
 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 only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url` or set `$XMEM_CONSOLE_URL` when inference does not apply). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), 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.
+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 only infers a Console where the layout determines one — a single-origin `/xmem` base names its `/console` sibling on the same host, and that sibling beats `$XMEM_CONSOLE_URL` on the same call — and the local-dev convention pairs `:8000` with `:8002` — otherwise it refuses to guess (pass `--console-url`; `$XMEM_CONSOLE_URL` only when `--api-url` was not given). Because that inference exists, a single-origin deployment's rendered sign-in command names the API alone; every other layout still renders the `--api-url`/`--console-url` pair, since naming one without the other is worse than naming neither (`api/agent_setup_renderer.py`), 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.
 
@@ -155,12 +157,16 @@ Project-local **`.xmemrc.json`**: `{email, api_url, api_key}`. Found by walking
 
 Those three keys are required and must be strings. Anything else in the file is **ignored, not rejected** (since 0.0.12): the rc is the only durable credential store, so a file this CLI cannot load is a CLI that cannot run any command at all — which would make adding a field to the file a breaking change far wider than the feature that added it.
 
-Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → sibling inference from the call's `--api-url` when it applies → `$XMEM_CONSOLE_URL` → sibling inference from `$XMEM_API_URL` → default — when `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
+Since 1.1.0 the file may also carry **`mcp_url`** — the MCP resource the API reported for itself when the key was issued, written only when the server names one. It is what lets `xmemcli mcp` reach an on-premise MCP host: that host is in no table the client was built with, and the rc is the one anchor a cloned `.mcp.json` does not control. A blank or non-string value is read as absent. It outranks the single-origin sibling inference below — a deployment naming itself beats a shape we derived — and both beat the built-in default. The mount path is part of the destination: `https://host/mcp` authorises that mount, not the sibling services beside it — and the instance id is canonicalised as a UUID before it is appended, so nothing following the mount can walk back out of it. Every lookup that reads `mcp_url` refuses redirects rather than merely dropping the credential across them, because what it learns is a host the key is later sent to. Every mutation of the file — write, in-place update, and logout's delete — is serialised under an exclusive lock on its containing directory, and an update is additionally bound to the identity *and* origin it was decided from. What protects an in-place update is that comparison, which is portable; the lock narrows what remains — the moment between comparing and replacing — where the platform offers one. A failed record is a warning, a failed de-authorisation fails the command. The enrichment write after login is conditional on the same comparison, so logging out or signing in again while it is in flight is not undone by it.
+
+Resolution order: `--api-key` → `$XMEM_API_KEY` → `.xmemrc.json`. Origin: `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **except** when the key is explicit (`--api-key` / `$XMEM_API_KEY`): the rc's `api_url` is skipped and the origin falls back to the built-in default unless you also set `--api-url` / `$XMEM_API_URL`. The localhost-key-at-prod guard applies when the key comes from the rc and an explicit `--api-url` / `$XMEM_API_URL` mismatches that rc origin. A base URL's path is preserved, never stripped — on a single-origin deployment the API lives at `https://host/xmem`, and that mount is part of every request the CLI builds; query, fragment, and userinfo on a base URL refuse normalisation rather than being stripped, so sibling inference cannot run on a shape the caller did not supply. Console resolution for login: `--console-url` → Console pinned by a positional (or mistaken `--api-url`) single-origin URL → `$XMEM_CONSOLE_URL` when `--api-url` was *not* given → sibling inference from the call's `--api-url` when it applies → sibling inference from `$XMEM_API_URL` → default. An explicit `--api-url` suppresses `$XMEM_CONSOLE_URL` for that invocation (a five-host `--api-url` without `--console-url` is a usage error, not a fall-through to the env Console). A named API origin from `$XMEM_API_URL` is held to the same infer-or-refuse rule, so an env-only non-default API without a Console cannot mint at the hosted Console and record that key against the foreign API; an inferred sibling that is remote HTTP is refused under the same HTTPS-or-loopback rule as a positional login URL. The same resolved Console is passed to the post-login `/whoami` that records `mcp_url`, so a leftover `$XMEM_CONSOLE_URL` cannot steer that lookup either. When `--api-url` is present, `$XMEM_API_URL` is not consulted for Console inference. Because a mounted base cannot also serve the `/api`-prefixed spelling of a route, the compatibility candidate in `whoami_urls` / `token_redeem_urls` (`{base}/api/whoami`, `{base}/api/cli/token` — a root-served deployment's second form) is offered only for a path-less base. The MCP bridge resolves its endpoint as `--mcp-url` → `$XMEM_MCP_URL` → the `/mcp` sibling of the effective API base (`--api-url` → `$XMEM_API_URL` → rc → default) → default, and its foreign-origin guard accepts the `/xmem` ↔ `/mcp` sibling pair as one deployment.
 
 ## Identity — `/whoami`
 
 `xmemcli auth status` calls **`GET /whoami`** with the active bearer key and reports `{authenticated, email, key_prefix}`. Exit `0` when the key resolves; auth error when it does not.
 
+The `AuthApiKey` body also carries **`mcp_url`**, this deployment's own MCP origin (`null` where it serves none). The field is always present, `null` included: an absent key means the server predates it, which is a different answer and is treated as one. `auth login` reads it from there — on both paths, since the email flow never calls `POST /cli/token` — and records it in the rc. The lookup is best-effort: any failure simply leaves the key out of the file, and the transport falls back to its table of shipped API↔MCP pairs.
+
 ## Security model
 
 | Threat | Mitigation |
@@ -185,7 +191,7 @@ Each login binds its own port and names it in the login URL, so concurrent login
 
 # `xmemcli` — capabilities reference
 
-**Version:** `1.0.0` (see `xmemcli version`)
+**Version:** `1.2.0` (see `xmemcli version`)
 
 `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.
 
@@ -228,7 +234,8 @@ Permission-filtered view of what this API key can see.
 | Command | Description |
 |---------|-------------|
 | **`instance get`** `<instance_id>` | Fetch one instance |
-| **`instance create`** | Create from XMD/JSON schema. Required `--name`; schema via `--schema-file` or `--schema-stdin`. |
+| **`instance templates`** | List the ready-made templates a create can name — id, label, one-line description, who each is for, example writes and reads, and the object-type names. No schema crosses the wire; the server holds the shape. |
+| **`instance create`** | Create from a template or an XMD/JSON schema. Required `--name`; then exactly one of `--template <id>`, `--schema-file` or `--schema-stdin`. `--template` sends only the id: no schema is composed, generated or repaired, so the shape you get is exactly the one you picked. |
 | **`instance instructions`** `[instance_id]` `[text]` `[--clear]` | Read, set or clear the instance's standing instructions to an agent — the owner's own words, carried to every agent that connects it. No text and no `--clear` reads and changes nothing. Setting reads the current value first and writes with the epoch it read, so an edit composed against instructions someone has since replaced is refused rather than applied (the console form and the instance chat write the same field). Clearing is `--clear`; an empty string is refused, because that is what a shell substitutes for an unset variable. The id may be pinned with `--instance-id` or `$XMEM_INSTANCE_ID` and the text given alone — a lone positional that is not an id is read as the text. |
 | **`instance setup`** `[instance_id]` `[--format agent\|project]` | How to connect this instance to an agent, ordered for where it is likely to be used. Prints the same steps the `get_setup_instructions` MCP tool gives an agent, so a person and the agent beside them read the same thing. `--format project` additionally prints the shared setup files to commit; each teammate still approves the install and signs in once. Carries no credential. |
 
@@ -262,6 +269,10 @@ XMD (xmemory Data) is the typed schema format for instances. These commands mirr
 #### Typical workflow
 
 ```text
+# 0. Or skip 1-2 entirely: pick a ready-made shape
+xmemcli instance templates
+xmemcli instance create --name demo --template personal_crm
+
 # 1. Synthesize or enhance
 xmemcli xmd generate "people and their pets" -o schema.yml
 xmemcli xmd enhance schema.yml "add a Pet.breed field" -o next.yml --plan-output plan.json
@@ -409,7 +420,7 @@ so a typo fails loudly rather than being ignored.
 | **`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. |
 | **`version`** | CLI release version (no network) |
-| **`status`** | Local health: version + whether `.xmemrc.json` exists (no network) |
+| **`status`** | Local health: version + whether `.xmemrc.json` exists, and the `mcp_url` it declares when it declares one (no network) |
 
 **`mcp` is a transport, not a command you run.** An MCP client starts it and speaks
 JSON-RPC to it over stdio; it forwards each frame to `<mcp-url>/instance/<id>` with this
@@ -422,6 +433,31 @@ It exists because an MCP client can reference an environment variable in an
 connection means nothing is captured when the server is registered, so a configuration
 written today still works in a session opened next week with an empty environment.
 
+**Where a file-held key may be sent.** The MCP origin is configured separately from the API
+origin, and a project `.mcp.json` arrives by `git clone` — it controls that server's `args` and
+`env`, so it is not allowed to vouch for itself. A key read from `.xmemrc.json` therefore reaches
+only the MCP origin that same file records in `mcp_url`, the origin paired with its `api_url` in
+this client's built-in table of shipped deployments, or a loopback host when both ends are on this
+machine. Anywhere else needs a key named on the call with `--api-key`.
+
+A recorded origin says *where*, never *how*: a remote one must be `https`, so a hand-written
+`http://` entry is refused rather than sending the key in clear text. Loopback stays exempt — those
+bytes never leave the machine.
+
+The **mount path is part of the destination**, not decoration. A deployment serving every route
+group on one hostname puts MCP at `https://host/mcp`, the REST API at `https://host/xmem` and the
+OAuth server at `https://host/oauth2`; an rc recording the first authorises the first only.
+
+`auth login` fills in `mcp_url` from what the API reports about itself, which is what makes an
+on-premise deployment work: its MCP host is in no table this client was built with, and every
+attempt to *derive* one host from the other has been wrong in a new way. If the transport refuses
+an origin you expect it to accept, run `auth login` against that deployment again — the rc predates
+the field, or that server does not report one. That works even when the stored key is still good:
+the `--email` path records the origin it learns while checking, and reports it as `mcp_url` on the
+`already_authorized` payload. A deployment that has stopped serving MCP answers `null`, and the
+recorded origin is dropped rather than left authorised — and if that removal cannot be written,
+the command fails rather than reporting success over a host that is still authorised.
+
 Two consequences worth knowing:
 
 - **stdout is the protocol.** Alone among these commands it emits no JSON document and
@@ -507,15 +543,21 @@ Some commands attach a more specific `stage` (`validate`, `usage`, `limit`, …)
 
 **Breaking change in 0.0.5:** HTTP **403** previously exited **4** (`auth`); it now exits **3** (`permission`). Scripts that treated exit **4** as “any auth-layer failure” must check `stage` or handle exit **3** for permission denials.
 
+**New in 1.2.0:** `instance templates` lists the ready-made instance shapes the service ships, with the prose to choose between them, and `instance create --template <id>` builds one from a pinned schema the server already holds. No schema is generated on that path: no description to compose, no `xmd generate` hop, and the instance comes out identical to the one the console would have made from the same template. (Creating an instance still generates its agent brief afterwards, on this path as on any other.)
+
+**New in 1.1.0:** `auth login` records the deployment's own MCP origin in `.xmemrc.json` as `mcp_url` (omitted where the server reports none), and `mcp` both connects there by default and accepts it as the pair its key may reach. Requires 0.0.12 or newer to read such a file — see the note below.
+
 **Compatibility change in 0.0.12:** an `.xmemrc.json` carrying a key this release does not recognise is now **accepted**, and the unknown key ignored; `email`, `api_url`, and `api_key` are still required and still have to be strings. Until 0.0.12 the key set was closed, which made adding a field to the file a breaking change for **every** command rather than for the one that would read it — a CLI that cannot load the rc cannot resolve a credential for anything. Nothing writes an extra key yet; this release exists so that a later one can.
 
 **Compatibility change in 0.0.13 (single-origin deployments):** an API base URL's path is now **preserved**, never stripped — `--api-url https://host/xmem` builds requests under `/xmem` instead of reducing to the bare origin. Where the base's path is exactly `/xmem`, the CLI infers its single-origin siblings on the same host: `auth login` finds the Console at `/console` without `--console-url`, and `xmemcli mcp` reaches `/mcp` without `--mcp-url` (explicit `--console-url` / `--mcp-url` and `$XMEM_CONSOLE_URL` / `$XMEM_MCP_URL` still win when inference does not apply; on a call that names `--api-url …/xmem`, sibling inference beats `$XMEM_CONSOLE_URL`; the MCP origin guard accepts the `/xmem` ↔ `/mcp` pair as one deployment). Bare origins and every other path shape behave exactly as before. See `cli/`.
 
-Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere. On a single-origin deployment they also rely on path inference — they render `auth login --api-url https://host/xmem` with **no** `--console-url` — and an older CLI given that command signs in at the hosted Console instead. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
+Two consequences worth knowing. Connect instructions from the API assume **1.0.0** or newer everywhere, and **1.1.1** on a single-origin deployment — earlier releases let `$XMEM_CONSOLE_URL` steer sign-in and token redemption to a foreign Console. On a single-origin deployment they render `auth login --api-url https://host/xmem` with **no** `--console-url`. The inference is keyed on the conventional mounts (`/xmem`, `/console`, `/mcp`). A deployment that mounts its services under other prefixes is not inferable: name `--console-url` and `--mcp-url` explicitly there, which is what its own rendered commands do.
 
-**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form, and the CLI writes the inferred ``api_url`` into ``.xmemrc.json`` as soon as login starts.
+**Console instance URLs (1.0.0+):** `xmemcli auth login https://host/console/instance/<uuid>` infers the API base (`/xmem`) and Console (`/console`) from that page URL on a single-origin host — no extra flags or env vars. The Connect tab paste prompt uses this form. When no ``.xmemrc.json`` exists yet, the CLI stages the inferred ``api_url`` into a placeholder rc as soon as login starts; an existing credential file is never rewritten mid-login. Remote plain HTTP is refused (HTTPS or loopback only) — the same rule as the plain URLs below.
 
-**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions.
+**Plain single-origin login URLs (1.1.1+):** `xmemcli auth login https://host/console` or `…/xmem` (trailing slash optional) infer the same sibling pair with no instance id — useful when signing in before you have an instance page open. Remote plain HTTP is refused (HTTPS or loopback only). An existing `.xmemrc.json` credential is never rebound mid-login; only a missing rc gets a placeholder `api_url`.
+
+**Compatibility change in 1.0.0:** console instance page URLs for login (above), immediate ``api_url`` staging in ``.xmemrc.json``, and **1.0.0** as the minimum version named by connect setup instructions. **Revised in 1.1.1:** staging writes only a placeholder when no rc exists (an existing credential file is left alone until login succeeds); single-origin connect instructions name **1.1.1** as their minimum — earlier releases let `$XMEM_CONSOLE_URL` steer the sign-in Console; and HTTPS-or-loopback now applies to every single-origin login URL, including instance pages, not only the new `/console` and `/xmem` forms. A mistaken `--api-url http://host/xmem` is refused the same way.
 
 See also [`ACCOUNTS_AUTH.md`](../docs/auth/ACCOUNTS_AUTH.md) for the server-side 401/403/404 rules.
 
@@ -606,7 +648,7 @@ These apply **before** any subcommand (`xmemcli help options`).
 
 **Credential resolution:** `--api-key` → `$XMEM_API_KEY` → nearest `.xmemrc.json` → *Not logged in — run `xmemcli auth login` first.*
 
-**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
+**`.xmemrc.json` shape:** `{email, api_url, api_key}`, all three required and all three strings, plus an optional `mcp_url` recorded by `auth login`. Keys beyond those are ignored rather than rejected (see the 0.0.12 note above), so a file written by a newer CLI still loads here.
 
 **`context` is the one exception, and it is a security boundary.** Every other command walks up
 from the current directory for the nearest `.xmemrc.json`, which is deliberate: a person chose
@@ -620,6 +662,8 @@ and each delivery mechanism turned out to be a fresh bypass.
 
 **Origin resolution:** `--api-url` → `$XMEM_API_URL` → rc `api_url` → default — **with one escape hatch**: when the key comes from `--api-key` / `$XMEM_API_KEY` (not from the rc), the rc's `api_url` is **not** consulted and the origin falls back to the built-in default (`https://api.xmemory.ai`) unless you also set `--api-url` / `$XMEM_API_URL`. That keeps an explicitly supplied key from being silently paired with an unrelated origin in a project `.xmemrc.json`. If `$XMEM_API_KEY` is set without `$XMEM_API_URL`, the CLI warns once per invocation.
 
+**MCP origin resolution (`mcp` only):** `--mcp-url` → `$XMEM_MCP_URL` → the rc's `mcp_url` → default (`https://mcp.xmemory.ai`). The rc rung follows the same escape hatch as the API origin: a key named with `--api-key` / `$XMEM_API_KEY` never inherits an origin from a project file.
+
 **Instance resolution (read/write):** `--instance-id` → `$XMEM_INSTANCE_ID` → if exactly **one** instance is visible, auto-select with a **stderr warning** → else error.
 
 **Output:** Pipes and non-TTY stdout → JSON. Interactive TTY → one-line summaries unless `--json`.

{xmemcli-1.0.0 → xmemcli-1.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "xmemcli"
-version = "1.0.0"
+version = "1.2.0"
 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-1.0.0 → xmemcli-1.2.0}/uv.lock

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

{xmemcli-1.0.0 → xmemcli-1.2.0}/xmemcli/__init__.py

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

{xmemcli-1.0.0 → xmemcli-1.2.0}/xmemcli/_help.py

@@ -121,7 +121,8 @@ _OVERVIEW_SECTIONS: tuple[tuple[str, tuple[tuple[str, str], ...]], ...] = (
         "Instances",
         (
             ("instance get", "Get a single instance by id"),
-            ("instance create", "Create a new instance from an XMD/JSON schema"),
+            ("instance templates", "List the ready-made templates a create can name"),
+            ("instance create", "Create a new instance from a template or an XMD/JSON schema"),
             ("instance setup", "How to connect an instance to an agent"),
             ("instance instructions", "Read, set or clear an instance's standing instructions to an agent"),
         ),
@@ -280,8 +281,9 @@ _GLOBAL_OPTION_LINES: dict[str, tuple[str, str]] = {
     ),
     "mcp_url": (
         "MCP origin that `mcp` connects to.",
-        "Default $XMEM_MCP_URL or https://mcp.xmemory.ai; a key from .xmemrc.json only travels to "
-        "its own deployment, so a foreign origin needs --api-key.",
+        "Default $XMEM_MCP_URL, then the mcp_url recorded in .xmemrc.json, then "
+        "https://mcp.xmemory.ai; a key from .xmemrc.json only travels to its own deployment, so a "
+        "foreign origin needs another `auth login` there or --api-key.",
     ),
     "json": (
         "Force JSON output — one JSON document on stdout.",
@@ -411,11 +413,18 @@ def _command_usage(parser: argparse.ArgumentParser, path: tuple[str, ...]) -> st
         if action.dest in _INTERNAL_DESTS or action.option_strings:
             continue
         if action.metavar:
-            usage_parts.append(f"<{action.metavar}>")
+            token = f"<{action.metavar}>"
         elif action.nargs in (argparse.ONE_OR_MORE, "+"):
-            usage_parts.append("<…>")
+            token = "<…>"
         else:
-            usage_parts.append(f"<{action.dest}>")
+            token = f"<{action.dest}>"
+        # ``nargs='?'`` is argparse-optional, not always product-optional: `mcp` uses it
+        # so `cmd_mcp` can print its own usage, but the instance id is required. Bracket
+        # only dests that are genuinely optional (`connect_url`, `instance_id_arg`).
+        if action.nargs in (argparse.OPTIONAL, "?") and action.dest != "instance_id":
+            usage_parts.append(f"[{token}]")
+        else:
+            usage_parts.append(token)
     if sub is not None and not any(a.dest not in _INTERNAL_DESTS and not a.option_strings for a in parser._actions):
         usage_suffix = " <command> [options]"
     else: