From a3c305812c50be99e30827df5006a6ca7a4be2df Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:20:26 +0000 Subject: [PATCH 1/9] fix(console): separate offline workers from unserved resources in Needs you --- .../limen-control-plane/src/console/pages.rs | 48 ++++++++++++------- docs/guides/console.md | 2 +- 2 files changed, 31 insertions(+), 19 deletions(-) diff --git a/crates/limen-control-plane/src/console/pages.rs b/crates/limen-control-plane/src/console/pages.rs index ea1790cd..92123f3b 100644 --- a/crates/limen-control-plane/src/console/pages.rs +++ b/crates/limen-control-plane/src/console/pages.rs @@ -282,33 +282,45 @@ async fn admin_attention( .await .map_err(|e| db_error("listing components", &e))?; let loaded = state.policy.current(); - let down = loaded - .policy - .documents() - .iter() - .filter_map(|d| match d { - Document::Resource(r) => Some(r), - _ => None, - }) - .filter(|r| { - views::Health::of(&matching_workers( + let (mut offline, mut unserved) = (0, 0); + for doc in loaded.policy.documents() { + if let Document::Resource(r) = doc { + match views::Health::of(&matching_workers( &components, &tunnels, &r.spec.worker_selector, - )) - .needs_attention() - }) - .count(); - if down > 0 { + )) { + views::Health::Up => {} + views::Health::Offline => offline += 1, + views::Health::NoWorker => unserved += 1, + } + } + } + // Two causes, two lines. Enrolled workers that lost their tunnel is an outage. No enrolled + // worker matching the selector is a deployment fact (a policy can describe resources whose + // workers are not run here, such as the example production ones), so it must not raise the + // same alarm. + let href = "/console/resources?sort=attention&attention=1"; + if offline > 0 { items.push(views::AttentionItem { text: format!( - "{} without a connected worker, so sessions will fail", - plural(down, "resource", "resources") + "{} whose workers are offline, so sessions will fail", + plural(offline, "resource", "resources") ), - href: "/console/resources?sort=attention&attention=1".to_owned(), + href: href.to_owned(), tone: "bad", }); } + if unserved > 0 { + items.push(views::AttentionItem { + text: format!( + "{} that no enrolled worker serves (no worker matches its selector)", + plural(unserved, "resource", "resources") + ), + href: href.to_owned(), + tone: "warn", + }); + } if overview.locked > 0 { items.push(views::AttentionItem { text: format!( diff --git a/docs/guides/console.md b/docs/guides/console.md index 05cffb07..e814347a 100644 --- a/docs/guides/console.md +++ b/docs/guides/console.md @@ -6,7 +6,7 @@ Open `https:///console/` (locally `https://localhost:3443/console/`) | Page | What you can do | Who | |---|---|---| -| **Overview** | Your identity and roles, what you can reach (with a copy-paste `limen ssh` command), recent sessions, and **Continue where you left off**: the resources you used last, each with its command. **Needs you** lists what is waiting: access requests for you to decide (and yours that are still waiting), policy changes and access reviews with something for you, a console session about to end and, for admins, disabled accounts and resources without a connected worker. **Favourites** and **Saved views** (see below) sit under it. A favourite or recent resource is a card: its name and kind, a star to remove it, and one line to get in, the command with a copy button, or *Choose how to connect* when you may act as several logins, roles or users (that leads to the resource page, where each has its own command). Admins also get live counts: active sessions, users, locks, workers, policy version | everyone | +| **Overview** | Your identity and roles, what you can reach (with a copy-paste `limen ssh` command), recent sessions, and **Continue where you left off**: the resources you used last, each with its command. **Needs you** lists what is waiting: access requests for you to decide (and yours that are still waiting), policy changes and access reviews with something for you, a console session about to end and, for admins, disabled accounts, resources whose workers are offline (a red line: sessions fail) and resources no enrolled worker serves (an amber line: no worker's labels match the resource's `worker_selector`, which is normal for example resources whose workers are not run in that deployment). **Favourites** and **Saved views** (see below) sit under it. A favourite or recent resource is a card: its name and kind, a star to remove it, and one line to get in, the command with a copy button, or *Choose how to connect* when you may act as several logins, roles or users (that leads to the resource page, where each has its own command). Admins also get live counts: active sessions, users, locks, workers, policy version | everyone | | **Resources** | Search and filter by kind and label (click a label chip; the URL is shareable, e.g. `?kind=postgres&label=env=staging`), and sort by name or **recently used** (admins also: busiest, or **needs attention** first). Every row you can open shows how to get in and when you last used it: a **Connect** column with the command and a button to copy it, or *Choose how to connect* (to the resource page's builder) when you may act as several logins, roles or users and a bare command would not run. Admins' table is already wide, so there the same is a copy button (or an arrow to the builder) beside the star, and only for resources their own roles open. Admins also see each resource's **errors in the last 24 hours** (refused attempts, statement errors, web 5xx, Kubernetes errors, with a tooltip saying which) and **status**: *reachable*, *offline* (workers are enrolled but none holds a tunnel) or *no worker* (none matches), and a **Needs attention** filter for those two, and for any resource with errors. The star on a row makes it a **favourite**; favourites are listed first, and **Favourites** narrows the list to just them. A resource page **leads with how to connect**: one command per login, role or user where the CLI takes one (`limen ssh deploy@host`, `limen db connect orders --db-role app`, `limen redis connect cache --user reader`), else one command. **Build your command** below it works for databases, MongoDB, Redis, search, RabbitMQ and Kafka: pick who to act as, a database or virtual host, and a local port, and the exact command updates (the choices are in the address, so it can be bookmarked or shared, and picking one updates the command where you are, without reloading or moving the page). It offers only what your own roles allow and shows what each identity may open; where policy allows any database, you type the name. Kubernetes and web apps show what your access covers. Below it, a strip shows its status (admins), when it was last used, and who is **on it now** with links to **Details** and, for SSH, **Watch**; links go to all its sessions and its audit trail. Admins can **End** a live session from the strip. The tabs are **Overview** (labels, and for admins the target, selector and workers), **Access** (admins and auditors: who can reach it; admins also get a box to check why a given person, bot or group can't, in the simulator) and **Activity** (its sessions). **Request access** appears when you can ask | everyone sees their own; admins see all | | **Sessions** | Live and past sessions, filterable by user, resource, kind, people or bots, how they ended and a UTC time range. Open one to **replay the recording** (SSH, after the control plane verifies its hash), read **its statements and commands** (SQL, Redis, MongoDB, search, RabbitMQ, Kafka; no recording) or **its Kubernetes API requests** (one kubectl session per login and cluster). Live SSH sessions have **Watch it** ([watching](watching-sessions.md)). Admins can **end** a session with a reason **Related links** on a session (the resource, the person, similar sessions, the audit trail of that session), **Copy link** and, on a recording, **Copy link to this moment**; the timeline of a recording is **marked where the output paused for 30 seconds or more**. A session still open refreshes itself. Admins can **End several sessions** at once: each is ended, and audited, on its own with the one reason you give. | everyone sees their own; admins and auditors see all | | **Access** | **Ask for access** that expires, see your requests, and (approvers) the queue **waiting for you** with the reason and what the requester did on that resource in the past 30 days. Admins and auditors also see **active grants** (admins can revoke) and everyone's requests. See [access requests](access-requests.md) | everyone | From 211338a98780164f80eaa66df06da7d264388cac Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:25:11 +0000 Subject: [PATCH 2/9] docs: use 'limen admin manage' where the guide and --etag help still said 'limen manage' --- crates/limen-cli/src/commands/manage.rs | 2 +- docs/cli-reference.md | 2 +- docs/guides/management-api.md | 6 +++--- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/crates/limen-cli/src/commands/manage.rs b/crates/limen-cli/src/commands/manage.rs index 9727240b..79326937 100644 --- a/crates/limen-cli/src/commands/manage.rs +++ b/crates/limen-cli/src/commands/manage.rs @@ -59,7 +59,7 @@ pub enum ManageCommand { /// Defaults to a writer's namespace, or `default` for admins. #[arg(long)] namespace: Option, - /// Replace the resource with this etag (from `limen manage get`). + /// Replace the resource with this etag (from `limen admin manage get`). #[arg(long)] etag: Option, /// Check everything and show the impact, but change nothing. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 7b9a96c0..991e1b87 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -1097,7 +1097,7 @@ Options: - `--description ` - `--source `: Who you write as, such as terraform/payments-prod. - `--namespace `: Defaults to a writer's namespace, or `default` for admins. -- `--etag `: Replace the resource with this etag (from `limen manage get`). +- `--etag `: Replace the resource with this etag (from `limen admin manage get`). - `--dry-run`: Check everything and show the impact, but change nothing. - `--request-id `: Makes a retry safe: the same id returns the first result. diff --git a/docs/guides/management-api.md b/docs/guides/management-api.md index 89b0bd59..b05432f0 100644 --- a/docs/guides/management-api.md +++ b/docs/guides/management-api.md @@ -2,7 +2,7 @@ `limen.manage.v1.ManagementService` ([ADR-0042](../adr/0042-management-api.md)) is how the CLI, the console and the Terraform provider ([`limen-dev/terraform-provider-limen`](https://github.com/limen-dev/terraform-provider-limen)) read and write policy. This page is for whoever writes a client. The contract is [`proto/limen/manage/v1/manage.proto`](../../proto/limen/manage/v1/manage.proto), where every message and field is documented; CI refuses breaking changes to it. Each kind's `spec` is described in the [policy reference](../policy.md). -Served now: reads and writes of **every document kind** (create, update, delete, batch, replace a source, transfer), **changes held for approval** (get, list, approve, reject, cancel), and `GetSchema`, which returns the JSON Schema of a kind's `spec` (`limen manage schema `). The schema is generated from the types the control plane parses with, and the same files are committed in [`docs/policy-schema/`](../policy-schema/) for clients that can't reach a server, such as a plan in a pull request. A writer's half of a resource from a profile is only part of a spec and may lack fields the schema requires, so validate `effective_spec_json` instead. Each field is described in the [policy reference](../policy.md). +Served now: reads and writes of **every document kind** (create, update, delete, batch, replace a source, transfer), **changes held for approval** (get, list, approve, reject, cancel), and `GetSchema`, which returns the JSON Schema of a kind's `spec` (`limen admin manage schema `). The schema is generated from the types the control plane parses with, and the same files are committed in [`docs/policy-schema/`](../policy-schema/) for clients that can't reach a server, such as a plan in a pull request. A writer's half of a resource from a profile is only part of a spec and may lack fields the schema requires, so validate `effective_spec_json` instead. Each field is described in the [policy reference](../policy.md). ## Who can call it @@ -42,7 +42,7 @@ Each Terraform resource is one document: `limen_resource`, `limen_role`, `limen_ | import | `GetDocument`, then keep its `ownership` | A document another owner manages can't be written; `TransferDocument` moves one between a writer's own sources. | - **Drift:** compare `spec_json` and `labels` with what you sent; they are exactly what you wrote (`spec_json` keys sorted). The profile's fixed half is in `effective_spec_json` and `effective_labels`, so it never shows as drift. -- **Past versions:** `GetDocument { policy_version }` reads a document as an earlier policy version had it (`limen manage get --policy-version N`). If its current revision was already there, it comes in full. An older revision comes as that version stored it, to admins only: the effective document and the version it first appeared in, with no owner or etag, since those are kept for current revisions only. +- **Past versions:** `GetDocument { policy_version }` reads a document as an earlier policy version had it (`limen admin manage get --policy-version N`). If its current revision was already there, it comes in full. An older revision comes as that version stored it, to admins only: the effective document and the version it first appeared in, with no owner or etag, since those are kept for current revisions only. - **Retries:** send a fresh UUID `request_id` per operation, and the same one when retrying. A repeat returns the first result; the same id with a different body is `REQUEST_ID_REUSED`. - **`ownership.source`** names your writer, such as `terraform/`. Use different sources for two states in one namespace; writing a document another source manages is `OWNED_ELSEWHERE`. - **Pull request plans can't log in:** a pull request run never matches a bot (ADR-0019). Plan online on the protected branch; validate offline in pull requests. @@ -56,7 +56,7 @@ A write that widens **standing** access (someone reaches something they couldn't A held write returns `WRITE_OUTCOME_PENDING_APPROVAL` with the change in `pending_change`, and nothing is applied. A client that can't wait (a Terraform plan) sets `fail_if_approval_needed` (with `validate_only`) and gets `APPROVAL_REQUIRED`. A dry run without it returns `VALIDATED` with a warning that applying will wait for approval. -People decide: `ApproveChange` or `RejectChange` (a note is required), `limen manage changes approve|deny ` (`reject` still works), or the console's **Policy changes** page. Deciders are admins and members of the writer grant's `approvers.groups`. Bots never decide. Neither the author nor whoever started the CI run (`actor` on GitHub, `user_login` on GitLab) can decide a change. The author withdraws it with `CancelChange`. +People decide: `ApproveChange` or `RejectChange` (a note is required), `limen admin manage changes approve|deny ` (`reject` still works), or the console's **Policy changes** page. Deciders are admins and members of the writer grant's `approvers.groups`. Bots never decide. Neither the author nor whoever started the CI run (`actor` on GitHub, `user_login` on GitLab) can decide a change. The author withdraws it with `CancelChange`. Approval writes again on the **current** policy, as the author, re-checking the grant. The change becomes `SUPERSEDED` instead if a document it touches changed, it no longer fits the grant, or it would now give standing access the approver didn't see in the impact. From ade443f94fe766ec0d7cc51d16d28c4e11e3ec1e Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:31:37 +0000 Subject: [PATCH 3/9] fix(cli): top-level approve, deny, cancel and completions answer with the new command in a terminal --- crates/limen-cli/src/main.rs | 12 ++++++++++-- demos/demo-phase1.sh | 2 +- docs/adr/0052-requests-command-group.md | 2 +- 3 files changed, 12 insertions(+), 4 deletions(-) diff --git a/crates/limen-cli/src/main.rs b/crates/limen-cli/src/main.rs index 220f571c..80d331c5 100644 --- a/crates/limen-cli/src/main.rs +++ b/crates/limen-cli/src/main.rs @@ -265,8 +265,7 @@ enum Command { /// Agents run this; to set one up, see `limen config mcp`. #[command(hide = true)] Mcp, - /// Print a shell completion script: `limen completions zsh > ~/.zfunc/_limen`. - /// Also `limen config completions`. + /// Moved: use `limen config completions zsh > ~/.zfunc/_limen`. #[command(hide = true)] Completions { shell: clap_complete::Shell }, /// Print the CLI reference as Markdown, generated from the command tree. @@ -776,6 +775,15 @@ fn print_completions(shell: clap_complete::Shell) { #[allow(clippy::too_many_lines)] // one arm per command async fn run(cli: Cli) -> anyhow::Result<()> { let proxy = cli.server.as_deref(); + // Commands that moved: refused with a tip in a terminal, still run from scripts. Before + // anything else, so no spinner starts for a command that is about to be refused. + match &cli.command { + Command::Approve { .. } => moved("approve", "limen requests approve"), + Command::Deny { .. } => moved("deny", "limen requests deny"), + Command::Cancel { .. } => moved("cancel", "limen requests cancel"), + Command::Completions { .. } => moved("completions", "limen config completions"), + _ => {} + } if cli.detach { anyhow::ensure!( opens_listener(&cli.command), diff --git a/demos/demo-phase1.sh b/demos/demo-phase1.sh index 3f60e68d..093f910d 100755 --- a/demos/demo-phase1.sh +++ b/demos/demo-phase1.sh @@ -74,7 +74,7 @@ first="$(limen ls -q | head -1)" limen show "$first" --json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert d["name"] == sys.argv[1] and d["connect"].startswith("limen "), d' "$first" || fail "limen show $first" [ "$(limen ls "${first:0:3}" -q | grep -c .)" -ge 1 ] || fail "limen ls found nothing" limen status --json | python3 -c 'import json,sys; d=json.load(sys.stdin); assert d["logged_in"] and d["roles"], d' || fail "limen status --json" -limen completions bash | grep -q _limen || fail "limen completions bash" +limen config completions bash | grep -q _limen || fail "limen config completions bash" pass "limen ls , -q, show, status --json and completions work" step "A developer sees only what policy allows" diff --git a/docs/adr/0052-requests-command-group.md b/docs/adr/0052-requests-command-group.md index 68974a5a..ea213b33 100644 --- a/docs/adr/0052-requests-command-group.md +++ b/docs/adr/0052-requests-command-group.md @@ -9,7 +9,7 @@ Access requests had five top-level verbs (`request`, `requests`, `approve`, `den ## Decision - `limen request ` stays: it is the action nearly everyone takes, and it is short. - Everything else about requests lives under `limen requests`: `ls` (the default, so bare `limen requests` and `limen requests --approvals` still work), `approve`, `deny`, `cancel`. A group of its own, not subcommands of `request`, because `request` takes a resource name and a resource called `ls` or `approve` would be ambiguous. -- Top-level `approve`, `deny` and `cancel` remain as hidden aliases for one release, so scripts and habits keep working. `limen admin approve|deny` (hidden duplicates) are removed. +- Top-level `approve`, `deny` and `cancel` are hidden. Typed in a terminal they answer like any unknown command and name the new one (`did you mean limen requests approve`), the same as `limen mcp` and `limen completions`; run by a script (stdin or stdout not a terminal) they still work, so existing jobs keep running. `limen admin approve|deny` (hidden duplicates) are removed. - `limen manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change. - Help text carries no ADR numbers; they stay in code comments and docs for developers. From bd9737d7495a8ee3523d2c4682a92576d1a2731c Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:33:01 +0000 Subject: [PATCH 4/9] docs(cli): guide lists the current commands, animation speeds and moved commands --- docs/guides/cli.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/cli.md b/docs/guides/cli.md index 3dc75202..559b7386 100644 --- a/docs/guides/cli.md +++ b/docs/guides/cli.md @@ -7,6 +7,7 @@ limen login # sign in (opens a browser); on a machine without o limen status # who am I, which roles, when does it expire? limen ls # what can I reach? --json for scripts limen ls --type postgres --label env=staging # filter by type and label (repeat --label to require several) +limen ls --watch # redraw every 2 seconds; -q prints only the names, for scripts limen show orders-staging # type, labels, who you may act as, and how to connect limen connect orders-staging # open any resource by name; picks db/redis/ssh/... from its type limen ssh ubuntu@web-staging-1 -- uptime # explicit login, run a command @@ -37,13 +38,13 @@ web-staging-1 ● ssh ec2-user, ubuntu env=staging | Connect brokers | `mq connect`, `kafka connect` | [Messaging](messaging.md) | | Use Kubernetes | `kube config`, `kube login` | [Kubernetes](kubernetes.md) | | Open a web app or a raw TCP target | `web open`, `tcp` | [Web apps](web-apps.md), [TCP](tcp.md) | -| Let an AI agent see what you can reach (read-only) | `mcp`, `config mcp` | [AI agents](ai-agents.md) | +| Let an AI agent see what you can reach (read-only) | `config mcp` | [AI agents](ai-agents.md) | | Ask for, approve or revoke access | `request`, `requests` (`ls`, `approve`, `deny`, `cancel`), `admin grants` | [Access requests](access-requests.md) | | Test and question policy | `policy test`, `who-can`, `what-can`, `diff`, `explain`, `suggest` | [Policy tooling](policy-tooling.md) | | Search the audit trail | `audit search` | [Audit search](audit-search.md) | | Review access, export evidence | `review …`, `admin evidence` | [Access reviews](access-reviews.md) | | Review discovered resources | `admin discovery` | [Discovery](discovery.md) | -| Administer | `admin apply`, `policy`, `components`, `token create`, `lock`, `kill-session`, `revoke`, `manage` (schema, get, changes) | [Management API](management-api.md), [Runbooks](../runbooks/README.md) | +| Administer | `admin apply`, `admin policy`, `admin components`, `admin token create`, `admin lock`, `admin unlock`, `admin locks`, `admin kill-session`, `admin revoke`, `admin selftest`, `admin manage` (whoami, schema, ls, get, put, delete, changes) | [Management API](management-api.md), [Runbooks](../runbooks/README.md) | | Run connections in the background | `--detach`, `conns ls`, `conns stop` | [ADR-0039](../adr/0039-detached-connections.md) | Admin commands need the `limen:admin` role and are audited like everything else. @@ -132,4 +133,4 @@ Every `✔` result grows into place (`·`, `•`, `✔`) in about a tenth of a s The logo at the top of `limen`, `limen --help` and `limen login` wipes in over about a second. Any call to the proxy that takes more than a third of a second (in `ls`, `show`, `requests`, `audit`, `admin` and most other commands) shows a spinner named for it, such as `List resources`. Slow steps show a spinner on stderr after about a third of a second, with the elapsed time after five seconds, and finish with a result line. Nothing moves when stderr is not a terminal, when `TERM=dumb`, when `CI` is set, or when `LIMEN_NO_ANIMATION` is set; you then get one plain `›` line per step. `NO_COLOR` removes colour but not the spinner. Ctrl-C during a wait ends it cleanly and exits 130. -`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.7, 1 or 0.5 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. `limen completions` still works and is hidden from the menu. `limen mcp` and `limen manage` moved to `limen config mcp` and `limen admin manage`: typed in a terminal they answer as an unknown command and name the new one, and run by an agent or a script (stdin or stdout not a terminal) they still work, so existing agent configs and CI jobs keep running. +`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. `limen mcp`, `limen completions` and `limen manage` moved to `limen config mcp`, `limen config completions` and `limen admin manage`, and the top-level `limen approve`, `deny` and `cancel` to `limen requests approve`, `deny` and `cancel`: typed in a terminal they answer as an unknown command and name the new one, and run by an agent or a script (stdin or stdout not a terminal) they still work, so existing agent configs and CI jobs keep running. From bd7a4680da45f0e5df8bc08639dfd43ded15d14e Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:12:49 +0000 Subject: [PATCH 5/9] fix(cli): the held-for-approval hint names 'limen admin manage changes approve' --- crates/limen-cli/src/commands/admin.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/limen-cli/src/commands/admin.rs b/crates/limen-cli/src/commands/admin.rs index 34b7238b..f6ae50ee 100644 --- a/crates/limen-cli/src/commands/admin.rs +++ b/crates/limen-cli/src/commands/admin.rs @@ -243,7 +243,7 @@ pub async fn run(proxy: Option<&str>, command: AdminCommand) -> anyhow::Result<( )); } else if !resp.pending_change_id.is_empty() { ui::warn(&format!( - "Held for approval: it widens standing access, and another admin approves it with `limen manage changes approve {}`.", + "Held for approval: it widens standing access, and another admin approves it with `limen admin manage changes approve {}`.", resp.pending_change_id )); } else if resp.applied { From b0c6d5ceff36f2d797d0b2b41a1f9d5c574f9296 Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 11:21:22 +0000 Subject: [PATCH 6/9] feat(cli)!: remove top-level approve, deny, cancel, completions and manage; answer them with a tip --- crates/limen-cli/src/commands/manage.rs | 2 +- crates/limen-cli/src/main.rs | 226 +++++++++++++++++------- docs/adr/0012-dependency-selection.md | 2 +- docs/adr/0052-requests-command-group.md | 2 +- docs/adr/README.md | 2 +- docs/guides/cli.md | 2 +- docs/guides/management-api.md | 2 +- 7 files changed, 167 insertions(+), 71 deletions(-) diff --git a/crates/limen-cli/src/commands/manage.rs b/crates/limen-cli/src/commands/manage.rs index 79326937..73656ac7 100644 --- a/crates/limen-cli/src/commands/manage.rs +++ b/crates/limen-cli/src/commands/manage.rs @@ -1,4 +1,4 @@ -//! `limen manage`: the management API (ADR-0042) from the command line, for +//! `limen admin manage`: the management API (ADR-0042) from the command line, for //! admins and for bots with a `policy_writer` grant (log in with //! `limen login --bot ...`). Output is JSON, for scripts and CI. diff --git a/crates/limen-cli/src/main.rs b/crates/limen-cli/src/main.rs index 80d331c5..f6fcb96d 100644 --- a/crates/limen-cli/src/main.rs +++ b/crates/limen-cli/src/main.rs @@ -194,23 +194,6 @@ enum Command { #[command(subcommand)] command: Option, }, - /// Approve an access request (the same as `limen requests approve`). - #[command(hide = true)] - Approve { - id: String, - #[arg(long, short = 'm')] - comment: Option, - }, - /// Deny an access request (the same as `limen requests deny`). - #[command(hide = true)] - Deny { - id: String, - #[arg(long, short = 'm')] - comment: Option, - }, - /// Withdraw an access request (the same as `limen requests cancel`). - #[command(hide = true)] - Cancel { id: String }, /// Say why you can or cannot reach a resource. #[command(display_order = 11)] Explain { @@ -265,9 +248,6 @@ enum Command { /// Agents run this; to set one up, see `limen config mcp`. #[command(hide = true)] Mcp, - /// Moved: use `limen config completions zsh > ~/.zfunc/_limen`. - #[command(hide = true)] - Completions { shell: clap_complete::Shell }, /// Print the CLI reference as Markdown, generated from the command tree. #[command(hide = true)] MarkdownHelp, @@ -358,13 +338,6 @@ enum Command { #[command(subcommand)] command: commands::admin::AdminCommand, }, - /// The management API: read policy documents and write resources, as an - /// admin or as a bot with a policy_writer grant. - #[command(hide = true)] - Manage { - #[command(subcommand)] - command: commands::manage::ManageCommand, - }, } /// Options shared by every `ls` view. @@ -736,17 +709,74 @@ fn opens_listener(command: &Command) -> bool { /// where it is. clap only suggests by spelling, which gets these wrong. fn moved_suggestion(args: &[String]) -> Option<(&str, &'static str)> { let word = args.iter().find(|a| !a.starts_with('-'))?.as_str(); - let now = match word { + moved_to(word).map(|now| (word, now)) +} + +/// Where a word that is not a command now lives: commands that moved, and names people reach +/// for out of habit (other tools, plain English). +fn moved_to(word: &str) -> Option<&'static str> { + Some(match word { + // Moved. + "approve" => "limen requests approve", + "deny" | "reject" => "limen requests deny", + "cancel" => "limen requests cancel", + "manage" => "limen admin manage", + "completions" | "completion" => "limen config completions", "animations" | "animation" | "settings" => "limen config animations", - "completion" => "limen config completions", + // The admin commands, typed without `admin`. + "apply" | "token" | "components" | "lock" | "unlock" | "locks" | "revoke" | "grants" + | "revoke-grant" | "kill-session" | "evidence" | "discovery" | "selftest" => { + return admin_command(word); + } + // Habit. + "list" | "resources" => "limen ls", + "whoami" | "me" => "limen status", + "signin" | "sign-in" | "auth" => "limen login", + "signout" | "sign-out" => "limen logout", + "ssh-config" => "limen config ssh", + "approvals" | "pending" => "limen requests --approvals", + "who-can" | "what-can" | "suggest" => return policy_command(word), + "psql" | "mysql" | "postgres" | "mysqld" => "limen db connect", + "mongosh" | "mongodb" => "limen mongo connect", + "valkey" | "redis-cli" => "limen redis connect", + "kubeconfig" | "kubectl" | "k8s" | "eks" => "limen kube config", + "open" => "limen connect", + "help-me" | "diagnose" | "check" => "limen doctor", + _ => return None, + }) +} + +fn admin_command(word: &str) -> Option<&'static str> { + Some(match word { + "apply" => "limen admin apply", + "token" => "limen admin token create", + "components" => "limen admin components", + "lock" => "limen admin lock", + "unlock" => "limen admin unlock", + "locks" => "limen admin locks", + "revoke" => "limen admin revoke", + "grants" => "limen admin grants", + "revoke-grant" => "limen admin revoke-grant", + "kill-session" => "limen admin kill-session", + "evidence" => "limen admin evidence", + "discovery" => "limen admin discovery", + "selftest" => "limen admin selftest", _ => return None, - }; - Some((word, now)) + }) +} + +fn policy_command(word: &str) -> Option<&'static str> { + Some(match word { + "who-can" => "limen policy who-can", + "what-can" => "limen policy what-can", + "suggest" => "limen policy suggest", + _ => return None, + }) } /// A command that moved. Typed in a terminal it answers like any unknown command and names the /// new one. Run by a script or an agent (stdin or stdout is not a terminal) it still works, so -/// existing agent configs (`limen mcp`) and CI jobs (`limen manage`) don't break. +/// existing agent configs (`limen mcp`) don't break. fn moved(name: &str, now: &str) { use std::io::IsTerminal as _; if std::io::stdin().is_terminal() && std::io::stdout().is_terminal() { @@ -775,15 +805,6 @@ fn print_completions(shell: clap_complete::Shell) { #[allow(clippy::too_many_lines)] // one arm per command async fn run(cli: Cli) -> anyhow::Result<()> { let proxy = cli.server.as_deref(); - // Commands that moved: refused with a tip in a terminal, still run from scripts. Before - // anything else, so no spinner starts for a command that is about to be refused. - match &cli.command { - Command::Approve { .. } => moved("approve", "limen requests approve"), - Command::Deny { .. } => moved("deny", "limen requests deny"), - Command::Cancel { .. } => moved("cancel", "limen requests cancel"), - Command::Completions { .. } => moved("completions", "limen config completions"), - _ => {} - } if cli.detach { anyhow::ensure!( opens_listener(&cli.command), @@ -799,15 +820,11 @@ async fn run(cli: Cli) -> anyhow::Result<()> { | Command::Show { .. } | Command::Request { .. } | Command::Requests { .. } - | Command::Approve { .. } - | Command::Deny { .. } - | Command::Cancel { .. } | Command::Explain { .. } | Command::Policy { .. } | Command::Audit { .. } | Command::Review { .. } | Command::Admin { .. } - | Command::Manage { .. } | Command::Connect { .. } | Command::Conns { .. } | Command::Ssh { .. } @@ -875,8 +892,7 @@ async fn run(cli: Cli) -> anyhow::Result<()> { moved("mcp", "limen config mcp"); commands::mcp::serve(proxy).await } - Command::Completions { shell } - | Command::Config { + Command::Config { command: ConfigCommand::Completions { shell }, } => { print_completions(shell); @@ -935,13 +951,6 @@ async fn run(cli: Cli) -> anyhow::Result<()> { Command::Requests { list, command } => { commands::access::requests_command(proxy, list, command).await } - Command::Approve { id, comment } => { - commands::access::decide(proxy, &id, true, comment.as_deref()).await - } - Command::Deny { id, comment } => { - commands::access::decide(proxy, &id, false, comment.as_deref()).await - } - Command::Cancel { id } => commands::access::cancel(proxy, &id).await, Command::Explain { resource, principal, @@ -963,10 +972,6 @@ async fn run(cli: Cli) -> anyhow::Result<()> { Command::Audit { command } => commands::audit::run(proxy, command).await, Command::Review { command } => commands::review::run(proxy, command).await, Command::Admin { command } => commands::admin::run(proxy, command).await, - Command::Manage { command } => { - moved("manage", "limen admin manage"); - commands::manage::run(proxy, command).await - } Command::Ssh { target, command } => commands::ssh::ssh(proxy, &target, &command).await, Command::SshProxy { login, host } => commands::ssh::ssh_proxy(proxy, &login, &host).await, Command::Config { @@ -1168,7 +1173,7 @@ fn not_yet(command: &str, what: &str, phase: &str) -> anyhow::Result<()> { mod tests { use clap::{CommandFactory, Parser}; - use super::{Cli, Command, DbCommand, is_top_level}; + use super::{Cli, Command, DbCommand, is_top_level, moved_to}; /// Resource commands have a stable, parseable CLI shape. #[test] @@ -1210,12 +1215,6 @@ mod tests { &["requests", "approve", "id1", "-m", "ok"], &["requests", "deny", "id1", "-m", "no"], &["requests", "cancel", "id1"], - // The old top-level forms stay for one release. - &["approve", "id1", "-m", "ok"], - &["deny", "id1"], - &["cancel", "id1"], - &["manage", "changes", "deny", "id1", "--note", "n"], - &["manage", "changes", "reject", "id1", "--note", "n"], ] { let mut full = vec!["limen"]; full.extend_from_slice(args); @@ -1225,6 +1224,103 @@ mod tests { assert!(Cli::try_parse_from(["limen", "requests", "--all", "approve", "id1"]).is_err()); } + #[test] + fn removed_commands_are_unknown_and_get_a_tip() { + for (old, new) in [ + ("approve", "limen requests approve"), + ("deny", "limen requests deny"), + ("cancel", "limen requests cancel"), + ("manage", "limen admin manage"), + ("completions", "limen config completions"), + ("lock", "limen admin lock"), + ("token", "limen admin token create"), + ("who-can", "limen policy who-can"), + ("psql", "limen db connect"), + ("whoami", "limen status"), + ] { + let err = Cli::try_parse_from(["limen", old, "x"]).expect_err(old); + assert_eq!( + err.kind(), + clap::error::ErrorKind::InvalidSubcommand, + "{old}" + ); + assert_eq!(moved_to(old), Some(new), "{old}"); + } + // The tip names a command that exists. + for word in [ + "approve", + "deny", + "reject", + "cancel", + "manage", + "completions", + "completion", + "animations", + "apply", + "token", + "components", + "lock", + "unlock", + "locks", + "revoke", + "grants", + "revoke-grant", + "kill-session", + "evidence", + "discovery", + "selftest", + "list", + "resources", + "whoami", + "me", + "signin", + "sign-in", + "auth", + "signout", + "sign-out", + "ssh-config", + "kubeconfig", + "approvals", + "pending", + "who-can", + "what-can", + "suggest", + "psql", + "mysql", + "postgres", + "mysqld", + "mongosh", + "mongodb", + "valkey", + "redis-cli", + "kubectl", + "k8s", + "eks", + "open", + "help-me", + "diagnose", + "check", + "settings", + "animation", + ] { + let tip = moved_to(word).unwrap_or_else(|| panic!("no tip for {word}")); + let mut argv: Vec<&str> = tip.split_whitespace().collect(); + argv.push("--help"); + let err = Cli::try_parse_from(argv).expect_err(tip); + assert_eq!( + err.kind(), + clap::error::ErrorKind::DisplayHelp, + "{word} -> {tip}" + ); + } + // A real command is never shadowed by a tip. + for real in [ + "login", "ls", "request", "requests", "review", "policy", "config", "admin", + ] { + assert_eq!(moved_to(real), None, "{real}"); + } + } + #[test] fn kube_commands_parse() { for args in [ diff --git a/docs/adr/0012-dependency-selection.md b/docs/adr/0012-dependency-selection.md index 4bfa8b48..b5a50a04 100644 --- a/docs/adr/0012-dependency-selection.md +++ b/docs/adr/0012-dependency-selection.md @@ -32,7 +32,7 @@ A dependency is adopted only if all of these hold: | OIDC | openidconnect | 4.1.0 | 2026-10-31 | Adopt. Stable and widely used. Watch maintenance; a fallback is `openidconnect` minus discovery plus `jsonwebtoken` | | SQL state | sqlx | 0.9.0 | 2026-05 | Adopt | | CLI | clap | 4.6.7 | 2026-09 | Adopt | -| CLI completions | clap_complete 4.6.11 | | 2026-10 | Adopt. Same maintainers and release train as clap; generates `limen completions `. No advisories; MIT/Apache-2.0 | +| CLI completions | clap_complete 4.6.11 | | 2026-10 | Adopt. Same maintainers and release train as clap; generates `limen config completions `. No advisories; MIT/Apache-2.0 | | Docs diagrams | @mermaid-js/mermaid-cli 12.0.0 (MIT) | | 2026-09-24 | Adopt as a **maintainer tool only**: `website/scripts/render-mermaid.mjs` runs it with `npx` to draw the Mermaid blocks in `docs/` as light and dark SVGs (committed under `docs/diagrams/mermaid/`). It is not in `website/package.json`, not in the site's build or CI, and nothing from it runs in the reader's browser. The build only checks that each block has its pictures (#139) | | Telemetry | tracing 0.1.44, tracing-subscriber 0.3.23, opentelemetry(-otlp) 0.33.1, tracing-opentelemetry 0.34 | OTLP over HTTP/protobuf with the blocking reqwest client (shares reqwest and prost; no second tonic). ADR-0040 | 2025-12 → 2026-10 | Adopt | | Metrics | metrics 0.24.6 + metrics-exporter-prometheus 0.18.3, cadence 1.8.0 | | 2026-04/05 | Adopt | diff --git a/docs/adr/0052-requests-command-group.md b/docs/adr/0052-requests-command-group.md index ea213b33..5697237f 100644 --- a/docs/adr/0052-requests-command-group.md +++ b/docs/adr/0052-requests-command-group.md @@ -9,7 +9,7 @@ Access requests had five top-level verbs (`request`, `requests`, `approve`, `den ## Decision - `limen request ` stays: it is the action nearly everyone takes, and it is short. - Everything else about requests lives under `limen requests`: `ls` (the default, so bare `limen requests` and `limen requests --approvals` still work), `approve`, `deny`, `cancel`. A group of its own, not subcommands of `request`, because `request` takes a resource name and a resource called `ls` or `approve` would be ambiguous. -- Top-level `approve`, `deny` and `cancel` are hidden. Typed in a terminal they answer like any unknown command and name the new one (`did you mean limen requests approve`), the same as `limen mcp` and `limen completions`; run by a script (stdin or stdout not a terminal) they still work, so existing jobs keep running. `limen admin approve|deny` (hidden duplicates) are removed. +- Top-level `approve`, `deny` and `cancel` are removed (amended before the first stable release). Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. Only `limen mcp` still runs from a script, because agents start it. `limen admin approve|deny` (hidden duplicates) are removed. - `limen manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change. - Help text carries no ADR numbers; they stay in code comments and docs for developers. diff --git a/docs/adr/README.md b/docs/adr/README.md index 3b8b105f..62d14a57 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -56,7 +56,7 @@ Each ADR's status line gives its approval date. | [0049](0049-ocsf-audit-export.md) | OCSF audit export for SIEMs: a projection sink with one exhaustive event mapping, a bucket and key of its own, the native hash chain staying the source of truth, and a bounded lag so a dead SIEM cannot fill the spool | Proposed (built in PR #294) | | [0050](0050-policy-suggest.md) | Policy suggest: removals-only proposals from real sessions (unused rules and logins), a coverage check, exempt roles, an audited admin call; output is YAML and a diff, never applied | Accepted | | [0051](0051-policy-replay.md) | Replay recorded sessions against a policy change: active versus proposed on the same reconstructed requests, one decision engine, aggregates only, audited and admin-only | Accepted | -| [0052](0052-requests-command-group.md) | One `limen requests` group for listing, approving, denying and cancelling access requests; old top-level verbs kept as hidden aliases | Accepted | +| [0052](0052-requests-command-group.md) | One `limen requests` group for listing, approving, denying and cancelling access requests; the old top-level verbs answer with a tip | Accepted | | [0053](0053-scheduled-self-test.md) | Scheduled self-test and controls report: a test principal no issuer will vouch for, checks named by the path they exercise, a signed self-attestation anchored in the audit trail, skipped never a pass | Proposed | | [0054](0054-motion-in-the-cli-and-console.md) | Motion in the CLI and console: a scroll cue for the sidebar, spinners that end in a result, Ctrl-C-safe waits, optional view transitions; short, reduced-motion safe, never on stdout | Accepted | | [0055](0055-console-resource-ux.md) | Console resources and navigation: connect first, status and last use on every resource, tabs, relative times, an attention card, a command palette; no new state, no inline script | Accepted | diff --git a/docs/guides/cli.md b/docs/guides/cli.md index 559b7386..f5d064aa 100644 --- a/docs/guides/cli.md +++ b/docs/guides/cli.md @@ -133,4 +133,4 @@ Every `✔` result grows into place (`·`, `•`, `✔`) in about a tenth of a s The logo at the top of `limen`, `limen --help` and `limen login` wipes in over about a second. Any call to the proxy that takes more than a third of a second (in `ls`, `show`, `requests`, `audit`, `admin` and most other commands) shows a spinner named for it, such as `List resources`. Slow steps show a spinner on stderr after about a third of a second, with the elapsed time after five seconds, and finish with a result line. Nothing moves when stderr is not a terminal, when `TERM=dumb`, when `CI` is set, or when `LIMEN_NO_ANIMATION` is set; you then get one plain `›` line per step. `NO_COLOR` removes colour but not the spinner. Ctrl-C during a wait ends it cleanly and exits 130. -`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. `limen mcp`, `limen completions` and `limen manage` moved to `limen config mcp`, `limen config completions` and `limen admin manage`, and the top-level `limen approve`, `deny` and `cancel` to `limen requests approve`, `deny` and `cancel`: typed in a terminal they answer as an unknown command and name the new one, and run by an agent or a script (stdin or stdout not a terminal) they still work, so existing agent configs and CI jobs keep running. +`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. Some commands moved, and typing the old name prints the new one (`did you mean ...`): `limen completions` is `limen config completions`, `limen manage` is `limen admin manage`, `limen approve`, `deny` and `cancel` are `limen requests approve`, `deny` and `cancel`, and the admin commands (`lock`, `token`, `apply` ...) live under `limen admin`. `limen mcp` is the one old name that still runs when an agent or script starts it (stdin or stdout not a terminal), so existing agent configs keep working; in a terminal it points to `limen config mcp`. diff --git a/docs/guides/management-api.md b/docs/guides/management-api.md index b05432f0..5d4d5ed7 100644 --- a/docs/guides/management-api.md +++ b/docs/guides/management-api.md @@ -26,7 +26,7 @@ Anyone else gets `PERMISSION_DENIED`. - `limen.v1.Auth/BotLogin { method: "github_actions" | "gitlab" | "oidc", token, csr_der, bot: "" }` returns `cert_pem` and `expires_at_unix` (at most an hour; no refresh: log in again with a new token). 3. **Call the API** on a new connection with `cert_pem` and the key as the TLS client certificate. -`limen login --bot github_actions` does steps 1–2 (`crates/limen-cli/src/commands/bot.rs`) and `limen admin manage ...` (the older `limen manage ...` still runs in scripts and CI, but in a terminal it points you here) does step 3; read them as a reference implementation. +`limen login --bot github_actions` does steps 1–2 (`crates/limen-cli/src/commands/bot.rs`) and `limen admin manage ...` (the old `limen manage ...` was removed; typing it prints the new name) does step 3; read them as a reference implementation. ## Mapping a Terraform resource From 6fb9fc40add95fb4eb818caba6d6da950e79c310 Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:45:04 +0000 Subject: [PATCH 7/9] docs(adr): 0052 states the decision without release-timing wording --- docs/adr/0052-requests-command-group.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/adr/0052-requests-command-group.md b/docs/adr/0052-requests-command-group.md index 5697237f..6db657bb 100644 --- a/docs/adr/0052-requests-command-group.md +++ b/docs/adr/0052-requests-command-group.md @@ -9,7 +9,7 @@ Access requests had five top-level verbs (`request`, `requests`, `approve`, `den ## Decision - `limen request ` stays: it is the action nearly everyone takes, and it is short. - Everything else about requests lives under `limen requests`: `ls` (the default, so bare `limen requests` and `limen requests --approvals` still work), `approve`, `deny`, `cancel`. A group of its own, not subcommands of `request`, because `request` takes a resource name and a resource called `ls` or `approve` would be ambiguous. -- Top-level `approve`, `deny` and `cancel` are removed (amended before the first stable release). Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. Only `limen mcp` still runs from a script, because agents start it. `limen admin approve|deny` (hidden duplicates) are removed. +- Top-level `approve`, `deny` and `cancel` are removed. Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. `limen mcp` stays, because agents start it. `limen admin approve|deny` (hidden duplicates) are removed. - `limen manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change. - Help text carries no ADR numbers; they stay in code comments and docs for developers. From 310bec0da6a32f09307b344cd91f6aad27b1dd51 Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:46:38 +0000 Subject: [PATCH 8/9] feat(cli)!: move the MCP server to 'limen config mcp serve'; 'limen mcp' answers with a tip --- crates/limen-cli/src/commands/mcp.rs | 19 +++++--- crates/limen-cli/src/main.rs | 55 +++++++++++------------- crates/limen-cli/tests/mcp_stdio.rs | 4 +- docs/adr/0032-ai-agents-as-principals.md | 6 +-- docs/adr/0052-requests-command-group.md | 2 +- docs/cli-reference.md | 16 ++++++- docs/guides/ai-agents.md | 6 +-- docs/guides/cli.md | 2 +- docs/threat-model.md | 2 +- 9 files changed, 65 insertions(+), 47 deletions(-) diff --git a/crates/limen-cli/src/commands/mcp.rs b/crates/limen-cli/src/commands/mcp.rs index ab30bc70..9ee66232 100644 --- a/crates/limen-cli/src/commands/mcp.rs +++ b/crates/limen-cli/src/commands/mcp.rs @@ -1,4 +1,4 @@ -//! `limen mcp`: a read-only Model Context Protocol server over stdio. +//! `limen config mcp serve`: a read-only Model Context Protocol server over stdio. //! //! A useful tool surface with **no agent identity**. Every tool runs this same binary with `--json` as the person who //! is logged in, so it grants nothing `limen` doesn't already grant. There is @@ -168,7 +168,7 @@ fn config_text(exe: &str, proxy: Option<&str>) -> String { if let Some(proxy) = proxy { args.extend(["--server", proxy]); } - args.push("mcp"); + args.extend(["config", "mcp", "serve"]); let json = serde_json::to_string_pretty(&json!({ "mcpServers": { "limen": { "command": exe, "args": args } } })) @@ -836,7 +836,7 @@ mod tests { fn config_text_is_valid_json_and_quotes_awkward_paths() { let text = config_text("/opt/my tools/limen", Some("limen.example.com:443")); assert!(text.contains( - "claude mcp add --scope user limen -- '/opt/my tools/limen' --server limen.example.com:443 mcp" + "claude mcp add --scope user limen -- '/opt/my tools/limen' --server limen.example.com:443 config mcp serve" )); let start = text.find('{').unwrap(); let end = text.rfind('}').unwrap(); @@ -847,11 +847,20 @@ mod tests { ); assert_eq!( parsed["mcpServers"]["limen"]["args"], - json!(["--server", "limen.example.com:443", "mcp"]) + json!([ + "--server", + "limen.example.com:443", + "config", + "mcp", + "serve" + ]) ); assert_eq!(shell_quote("it's"), "'it'\\''s'"); let plain = config_text("/usr/bin/limen", None); - assert!(plain.contains("claude mcp add --scope user limen -- /usr/bin/limen mcp\n")); + assert!( + plain + .contains("claude mcp add --scope user limen -- /usr/bin/limen config mcp serve\n") + ); assert!(!plain.contains("--server")); } diff --git a/crates/limen-cli/src/main.rs b/crates/limen-cli/src/main.rs index f6fcb96d..e599d497 100644 --- a/crates/limen-cli/src/main.rs +++ b/crates/limen-cli/src/main.rs @@ -242,12 +242,6 @@ enum Command { #[command(subcommand)] command: ConnsCommand, }, - /// Serve a read-only Model Context Protocol server on stdin and stdout, for AI agents. - /// - /// Tools list and explain what the logged-in person may reach. None connects, requests or changes anything. - /// Agents run this; to set one up, see `limen config mcp`. - #[command(hide = true)] - Mcp, /// Print the CLI reference as Markdown, generated from the command tree. #[command(hide = true)] MarkdownHelp, @@ -340,6 +334,15 @@ enum Command { }, } +/// What `limen config mcp` can also do. +#[derive(Debug, clap::Subcommand)] +enum McpCommand { + /// Serve a read-only Model Context Protocol server on stdin and stdout. Agents run this. + /// + /// Tools list and explain what the logged-in person may reach. None connects, requests or changes anything. + Serve, +} + /// Options shared by every `ls` view. #[derive(Debug, clap::Args)] struct ListArgs { @@ -404,8 +407,13 @@ enum ConfigCommand { #[arg(long, value_name = "FILE")] file: Option, }, - /// Print how to add `limen mcp` to an AI agent (Claude Code and any client that reads `mcpServers`). Changes no files. - Mcp, + /// Print how to add Limen to an AI agent (Claude Code and any client that reads `mcpServers`). Changes no files. + /// + /// The agent runs `limen config mcp serve`. + Mcp { + #[command(subcommand)] + command: Option, + }, /// Print a shell completion script: `limen config completions zsh > ~/.zfunc/_limen`. Completions { shell: clap_complete::Shell }, /// Show or change how the CLI looks and moves: animations, their speed, the logo, the call spinner. @@ -721,6 +729,7 @@ fn moved_to(word: &str) -> Option<&'static str> { "deny" | "reject" => "limen requests deny", "cancel" => "limen requests cancel", "manage" => "limen admin manage", + "mcp" => "limen config mcp", "completions" | "completion" => "limen config completions", "animations" | "animation" | "settings" => "limen config animations", // The admin commands, typed without `admin`. @@ -774,21 +783,6 @@ fn policy_command(word: &str) -> Option<&'static str> { }) } -/// A command that moved. Typed in a terminal it answers like any unknown command and names the -/// new one. Run by a script or an agent (stdin or stdout is not a terminal) it still works, so -/// existing agent configs (`limen mcp`) don't break. -fn moved(name: &str, now: &str) { - use std::io::IsTerminal as _; - if std::io::stdin().is_terminal() && std::io::stdout().is_terminal() { - ::command() - .error( - clap::error::ErrorKind::InvalidSubcommand, - format!("unrecognized subcommand '{name}'\n\n tip: did you mean `{now}`?"), - ) - .exit(); - } -} - /// The completion script for `shell`, on stdout. fn print_completions(shell: clap_complete::Shell) { // Render first: writing straight to a closed pipe (`| head`) would panic. @@ -813,7 +807,7 @@ async fn run(cli: Cli) -> anyhow::Result<()> { return commands::conns::detach(proxy).await; } // A spinner while a call to the proxy is slow, for the commands that print once it returns. - // Not for ones that serve a protocol on stdout (`mcp`, `ssh-proxy`) or are long-lived. + // Not for ones that serve a protocol on stdout (`config mcp serve`, `ssh-proxy`) or are long-lived. if matches!( cli.command, Command::Ls { .. } @@ -888,10 +882,6 @@ async fn run(cli: Cli) -> anyhow::Result<()> { ConnsCommand::Ls { json } => commands::conns::ls(proxy, json), ConnsCommand::Stop { ids, all } => commands::conns::stop_command(proxy, &ids, all), }, - Command::Mcp => { - moved("mcp", "limen config mcp"); - commands::mcp::serve(proxy).await - } Command::Config { command: ConfigCommand::Completions { shell }, } => { @@ -992,8 +982,14 @@ async fn run(cli: Cli) -> anyhow::Result<()> { } } Command::Config { - command: ConfigCommand::Mcp, + command: ConfigCommand::Mcp { command: None }, } => commands::mcp::config(proxy), + Command::Config { + command: + ConfigCommand::Mcp { + command: Some(McpCommand::Serve), + }, + } => commands::mcp::serve(proxy).await, Command::Config { command: ConfigCommand::Animations { @@ -1232,6 +1228,7 @@ mod tests { ("cancel", "limen requests cancel"), ("manage", "limen admin manage"), ("completions", "limen config completions"), + ("mcp", "limen config mcp"), ("lock", "limen admin lock"), ("token", "limen admin token create"), ("who-can", "limen policy who-can"), diff --git a/crates/limen-cli/tests/mcp_stdio.rs b/crates/limen-cli/tests/mcp_stdio.rs index 4766b5c2..aef0f258 100644 --- a/crates/limen-cli/tests/mcp_stdio.rs +++ b/crates/limen-cli/tests/mcp_stdio.rs @@ -1,4 +1,4 @@ -//! `limen mcp` over its real stdin and stdout, with no login. +//! `limen config mcp serve` over its real stdin and stdout, with no login. //! //! Guards the invariant that stdout carries protocol messages only. @@ -10,7 +10,7 @@ use serde_json::Value; fn session(input: &str) -> (Vec, std::process::ExitStatus) { let home = tempfile::tempdir().expect("temp home"); let mut child = Command::new(env!("CARGO_BIN_EXE_limen")) - .arg("mcp") + .args(["config", "mcp", "serve"]) // An empty home: no profile, so nothing can be reached or logged in. .env("HOME", home.path()) .env("XDG_CONFIG_HOME", home.path()) diff --git a/docs/adr/0032-ai-agents-as-principals.md b/docs/adr/0032-ai-agents-as-principals.md index 45e776db..676e15d7 100644 --- a/docs/adr/0032-ai-agents-as-principals.md +++ b/docs/adr/0032-ai-agents-as-principals.md @@ -27,10 +27,10 @@ How an agent proves who it is (a platform-issued token, a signed attestation fro ## Amendment: spike 0 and desk analysis of the open questions (2026-11-06) The status stays Proposed. This records what was built and what reading Limen at `0bc7da6` (ADR-0019, ADR-0025, ADR-0042 as built) suggests for the questions above. **Nothing below was run against a real agent runtime**; each answer is a recommendation for the owner, and spikes 1 to 3 are still to do. -- **Spike 0 is built:** `limen mcp` (#268), a read-only stdio server in the CLI with five tools (`status`, `ls`, `show`, `explain`, `requests`). It runs the CLI with `--json` as the logged-in person, so it grants nothing new and has no agent identity. It has not been tested against a live login. Threat model: TB15. `policy who-can` and `what-can` are left out because they read local policy files or need `limen:admin`. -- **Where the server lives:** in the CLI first (`limen mcp`). A separate component is justified only by a remote, multi-tenant server that many agents connect to, which has a larger attack surface and no demand yet. The separate `mcp-server-limen` repository was archived for this reason. +- **Spike 0 is built:** `limen config mcp serve` (#268; first named `limen mcp`), a read-only stdio server in the CLI with five tools (`status`, `ls`, `show`, `explain`, `requests`). It runs the CLI with `--json` as the logged-in person, so it grants nothing new and has no agent identity. It has not been tested against a live login. Threat model: TB15. `policy who-can` and `what-can` are left out because they read local policy files or need `limen:admin`. +- **Where the server lives:** in the CLI first (`limen config mcp serve`). A separate component is justified only by a remote, multi-tenant server that many agents connect to, which has a larger attack surface and no demand yet. The separate `mcp-server-limen` repository was archived for this reason. - **How an agent proves who it is:** a platform-issued OIDC token through the existing bot join (ADR-0019), with no new login path. A signed attestation needs a trust root nobody has defined. Approval by the accountable person at start-up is an additional control, not the proof. A local desktop agent has no workload identity; today it can only use the person's own login, which is not an agent identity. The accountable person must come from something the issuer vouches for or from the `bot` document, never from a claim the agent makes about itself. - **Transcripts:** SSH is the best understood (the session recording plus the tool call and stated reason, linked by session id, redacted before storage). For databases, statements and row counts, not result rows (ADR-0033 already audits one `db.query` per statement without parameter values). Kubernetes and web apps are undecided. - **Blocker found:** bots cannot request access (ADR-0025, as built), so approval per action for an agent is impossible until Limen lets agents request. Bots also never hold built-in roles, which should stay true for agents. - **First action tool, when allowed:** a wrapper over `limen request --wait`, because approval is the control that matters most; then SSH. -- **Stop condition (unchanged):** if `limen mcp` proves little used, drop the idea. +- **Stop condition (unchanged):** if `limen config mcp serve` proves little used, drop the idea. diff --git a/docs/adr/0052-requests-command-group.md b/docs/adr/0052-requests-command-group.md index 6db657bb..a48412ed 100644 --- a/docs/adr/0052-requests-command-group.md +++ b/docs/adr/0052-requests-command-group.md @@ -9,7 +9,7 @@ Access requests had five top-level verbs (`request`, `requests`, `approve`, `den ## Decision - `limen request ` stays: it is the action nearly everyone takes, and it is short. - Everything else about requests lives under `limen requests`: `ls` (the default, so bare `limen requests` and `limen requests --approvals` still work), `approve`, `deny`, `cancel`. A group of its own, not subcommands of `request`, because `request` takes a resource name and a resource called `ls` or `approve` would be ambiguous. -- Top-level `approve`, `deny` and `cancel` are removed. Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. `limen mcp` stays, because agents start it. `limen admin approve|deny` (hidden duplicates) are removed. +- Top-level `approve`, `deny` and `cancel` are removed. Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. `limen mcp` moved to `limen config mcp serve`, which `limen config mcp` prints for agents. `limen admin approve|deny` (hidden duplicates) are removed. - `limen manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change. - Help text carries no ADR numbers; they stay in code comments and docs for developers. diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 991e1b87..1d9b5037 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -569,10 +569,22 @@ Options: #### `limen config mcp` -Print how to add `limen mcp` to an AI agent (Claude Code and any client that reads `mcpServers`). Changes no files +Print how to add Limen to an AI agent (Claude Code and any client that reads `mcpServers`). Changes no files. + +The agent runs `limen config mcp serve`. + +```text +Usage: limen config mcp [OPTIONS] [COMMAND] +``` + +##### `limen config mcp serve` + +Serve a read-only Model Context Protocol server on stdin and stdout. Agents run this. + +Tools list and explain what the logged-in person may reach. None connects, requests or changes anything. ```text -Usage: limen config mcp [OPTIONS] +Usage: limen config mcp serve [OPTIONS] ``` #### `limen config completions` diff --git a/docs/guides/ai-agents.md b/docs/guides/ai-agents.md index 7bf2307c..6d47281a 100644 --- a/docs/guides/ai-agents.md +++ b/docs/guides/ai-agents.md @@ -1,6 +1,6 @@ # Use Limen from an AI agent -`limen mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server built into the CLI. It lets an AI agent ask what you can reach through Limen, and why you can't reach something. It is **read-only**, runs on your machine, and uses your own login, so it grants nothing you don't already have. +`limen config mcp serve` is a [Model Context Protocol](https://modelcontextprotocol.io) server built into the CLI. It lets an AI agent ask what you can reach through Limen, and why you can't reach something. It is **read-only**, runs on your machine, and uses your own login, so it grants nothing you don't already have. ## Set it up @@ -11,11 +11,11 @@ limen login limen config mcp ``` -`limen config mcp` prints the command for Claude Code, which looks like `claude mcp add --scope user limen -- /path/to/limen mcp`, and a JSON block for other clients. Run the command it prints. The `limen mcp` inside it is what your agent starts; you don't type it yourself. +`limen config mcp` prints the command for Claude Code, which looks like `claude mcp add --scope user limen -- /path/to/limen config mcp serve`, and a JSON block for other clients. Run the command it prints. The `limen config mcp serve` inside it is what your agent starts; you don't type it yourself. `--scope user` makes it available in every project. Without it, Claude Code adds the server only to the directory you ran the command in. -For any other client that reads an `mcpServers` block (a `.mcp.json`, for example), run `limen config mcp`. (Typing `limen mcp` in a terminal answers as an unknown command and points here; an agent starting it still works.) It prints the Claude Code command and a JSON block with the full path of your `limen`, and changes no file. If you use a proxy other than the last one you signed in to, run `limen --server host:port config mcp` so the snippet carries it. +For any other client that reads an `mcpServers` block (a `.mcp.json`, for example), run `limen config mcp`. (`limen mcp`, the old name, is gone; typing it points here.) It prints the Claude Code command and a JSON block with the full path of your `limen`, and changes no file. If you use a proxy other than the last one you signed in to, run `limen --server host:port config mcp` so the snippet carries it. Logins are short-lived. When yours expires, every tool answers `run limen login`. The agent cannot sign in for you, and that is deliberate. diff --git a/docs/guides/cli.md b/docs/guides/cli.md index f5d064aa..13504b77 100644 --- a/docs/guides/cli.md +++ b/docs/guides/cli.md @@ -133,4 +133,4 @@ Every `✔` result grows into place (`·`, `•`, `✔`) in about a tenth of a s The logo at the top of `limen`, `limen --help` and `limen login` wipes in over about a second. Any call to the proxy that takes more than a third of a second (in `ls`, `show`, `requests`, `audit`, `admin` and most other commands) shows a spinner named for it, such as `List resources`. Slow steps show a spinner on stderr after about a third of a second, with the elapsed time after five seconds, and finish with a result line. Nothing moves when stderr is not a terminal, when `TERM=dumb`, when `CI` is set, or when `LIMEN_NO_ANIMATION` is set; you then get one plain `›` line per step. `NO_COLOR` removes colour but not the spinner. Ctrl-C during a wait ends it cleanly and exits 130. -`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. Some commands moved, and typing the old name prints the new one (`did you mean ...`): `limen completions` is `limen config completions`, `limen manage` is `limen admin manage`, `limen approve`, `deny` and `cancel` are `limen requests approve`, `deny` and `cancel`, and the admin commands (`lock`, `token`, `apply` ...) live under `limen admin`. `limen mcp` is the one old name that still runs when an agent or script starts it (stdin or stdout not a terminal), so existing agent configs keep working; in a terminal it points to `limen config mcp`. +`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. Some commands moved, and typing the old name prints the new one (`did you mean ...`): `limen completions` is `limen config completions`, `limen manage` is `limen admin manage`, `limen approve`, `deny` and `cancel` are `limen requests approve`, `deny` and `cancel`, and the admin commands (`lock`, `token`, `apply` ...) live under `limen admin`. `limen mcp` is `limen config mcp serve` (run by agents; `limen config mcp` prints how to add it). diff --git a/docs/threat-model.md b/docs/threat-model.md index a4e5c2f5..0c37b6ba 100644 --- a/docs/threat-model.md +++ b/docs/threat-model.md @@ -312,7 +312,7 @@ A static site, built and checked in CI (`website.yml`) and deployed to GitHub Pa | T: a retried write applies twice or differently | `request_id` remembered per caller for 24 hours; the same id with a different body is refused | | Limit | Limen has no mapping between IdP and CI accounts: a person whose names differ on the two can approve a change their own run produced (residual 9) | -### TB15: AI agent ↔ `limen mcp` (ADR-0032, spike 0) +### TB15: AI agent ↔ `limen config mcp serve` (ADR-0032, spike 0) *Built: a read-only stdio server in the CLI. There is no agent identity yet; the agent borrows the logged-in person's own login. Tested without a live session only.* | Threat | Mitigation | From f5d2005fdb1cd332b47a0acd0c7787fe75595023 Mon Sep 17 00:00:00 2001 From: Jorge Martins <76965647+jfcmartins@users.noreply.github.com> Date: Mon, 16 Nov 2026 14:48:23 +0000 Subject: [PATCH 9/9] docs: describe the commands as they are now, without how they were named before; console hint says 'limen admin manage' --- crates/limen-cli/src/main.rs | 24 ++--- crates/limen-cli/tests/mcp_stdio.rs | 2 +- .../limen-control-plane/templates/policy.html | 2 +- .../console-pages/console/policy/index.html | 92 +++++++++---------- docs/adr/0032-ai-agents-as-principals.md | 2 +- docs/adr/0052-requests-command-group.md | 6 +- docs/guides/ai-agents.md | 2 +- docs/guides/cli.md | 2 +- docs/guides/management-api.md | 2 +- 9 files changed, 67 insertions(+), 67 deletions(-) diff --git a/crates/limen-cli/src/main.rs b/crates/limen-cli/src/main.rs index e599d497..ff4a1687 100644 --- a/crates/limen-cli/src/main.rs +++ b/crates/limen-cli/src/main.rs @@ -651,7 +651,7 @@ async fn main() { ui::banner(); } if e.kind() == ErrorKind::InvalidSubcommand - && let Some((word, now)) = moved_suggestion(&args) + && let Some((word, now)) = suggest_command(&args) { // clap's own guess goes by spelling (`animations` -> `completions`); these are known. ::command() @@ -715,16 +715,16 @@ fn opens_listener(command: &Command) -> bool { /// Words people try that live under another command: the first word that isn't a flag, and /// where it is. clap only suggests by spelling, which gets these wrong. -fn moved_suggestion(args: &[String]) -> Option<(&str, &'static str)> { +fn suggest_command(args: &[String]) -> Option<(&str, &'static str)> { let word = args.iter().find(|a| !a.starts_with('-'))?.as_str(); - moved_to(word).map(|now| (word, now)) + tip_for(word).map(|now| (word, now)) } -/// Where a word that is not a command now lives: commands that moved, and names people reach -/// for out of habit (other tools, plain English). -fn moved_to(word: &str) -> Option<&'static str> { +/// The command to suggest for a word that is not one: where a command lives now, and names +/// people reach for out of habit (other tools, plain English). +fn tip_for(word: &str) -> Option<&'static str> { Some(match word { - // Moved. + // Where it lives. "approve" => "limen requests approve", "deny" | "reject" => "limen requests deny", "cancel" => "limen requests cancel", @@ -1169,7 +1169,7 @@ fn not_yet(command: &str, what: &str, phase: &str) -> anyhow::Result<()> { mod tests { use clap::{CommandFactory, Parser}; - use super::{Cli, Command, DbCommand, is_top_level, moved_to}; + use super::{Cli, Command, DbCommand, is_top_level, tip_for}; /// Resource commands have a stable, parseable CLI shape. #[test] @@ -1221,7 +1221,7 @@ mod tests { } #[test] - fn removed_commands_are_unknown_and_get_a_tip() { + fn unknown_words_get_a_tip() { for (old, new) in [ ("approve", "limen requests approve"), ("deny", "limen requests deny"), @@ -1241,7 +1241,7 @@ mod tests { clap::error::ErrorKind::InvalidSubcommand, "{old}" ); - assert_eq!(moved_to(old), Some(new), "{old}"); + assert_eq!(tip_for(old), Some(new), "{old}"); } // The tip names a command that exists. for word in [ @@ -1300,7 +1300,7 @@ mod tests { "settings", "animation", ] { - let tip = moved_to(word).unwrap_or_else(|| panic!("no tip for {word}")); + let tip = tip_for(word).unwrap_or_else(|| panic!("no tip for {word}")); let mut argv: Vec<&str> = tip.split_whitespace().collect(); argv.push("--help"); let err = Cli::try_parse_from(argv).expect_err(tip); @@ -1314,7 +1314,7 @@ mod tests { for real in [ "login", "ls", "request", "requests", "review", "policy", "config", "admin", ] { - assert_eq!(moved_to(real), None, "{real}"); + assert_eq!(tip_for(real), None, "{real}"); } } diff --git a/crates/limen-cli/tests/mcp_stdio.rs b/crates/limen-cli/tests/mcp_stdio.rs index aef0f258..bada7ace 100644 --- a/crates/limen-cli/tests/mcp_stdio.rs +++ b/crates/limen-cli/tests/mcp_stdio.rs @@ -20,7 +20,7 @@ fn session(input: &str) -> (Vec, std::process::ExitStatus) { .stdout(Stdio::piped()) .stderr(Stdio::null()) .spawn() - .expect("spawn limen mcp"); + .expect("spawn limen config mcp serve"); child .stdin .take() diff --git a/crates/limen-control-plane/templates/policy.html b/crates/limen-control-plane/templates/policy.html index b49d6818..56a56298 100644 --- a/crates/limen-control-plane/templates/policy.html +++ b/crates/limen-control-plane/templates/policy.html @@ -50,7 +50,7 @@

{{ group.title }} {{ group.docs.len() }}

{% else %} -

Managed by {{ d.owner }}: change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by {{ d.owner }}: change it there. A person with the admin role can move it to the console with limen admin manage.

{{ d.yaml }}
{% endif %} diff --git a/crates/limen-control-plane/tests/console-pages/console/policy/index.html b/crates/limen-control-plane/tests/console-pages/console/policy/index.html index daf3b505..07ad24c2 100644 --- a/crates/limen-control-plane/tests/console-pages/console/policy/index.html +++ b/crates/limen-control-plane/tests/console-pages/console/policy/index.html @@ -104,7 +104,7 @@

Roles 11

auditor 1 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -135,7 +135,7 @@ 

Roles 11

contractor 1 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -168,7 +168,7 @@ 

Roles 11

deployer 1 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -198,7 +198,7 @@ 

Roles 11

dev-planned 2 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -235,7 +235,7 @@ 

Roles 11

dev-readonly 7 allow, 1 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -344,7 +344,7 @@ 

Roles 11

phase12-tcp 1 allow, 1 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -374,7 +374,7 @@ 

Roles 11

phase12-web 1 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -403,7 +403,7 @@ 

Roles 11

sre 7 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -520,7 +520,7 @@ 

Roles 11

sre-oncall 2 allow, 1 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -572,7 +572,7 @@ 

Roles 11

sre-planned 3 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -618,7 +618,7 @@ 

Roles 11

viewer 1 allow, 0 deny rules git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role
 version: v1
 metadata:
@@ -651,7 +651,7 @@ 

Role mappings 4

dev-idp 7 group mappings git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role_mapping
 version: v1
 metadata:
@@ -686,7 +686,7 @@ 

Role mappings 4

phase12-tcp 1 group mappings git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role_mapping
 version: v1
 metadata:
@@ -703,7 +703,7 @@ 

Role mappings 4

phase12-web 1 group mappings git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role_mapping
 version: v1
 metadata:
@@ -720,7 +720,7 @@ 

Role mappings 4

planned-idp 2 group mappings git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: role_mapping
 version: v1
 metadata:
@@ -743,7 +743,7 @@ 

Resources 28

bastion-staging ssh git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -763,7 +763,7 @@ 

Resources 28

billing-mysql-staging mysql git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -787,7 +787,7 @@ 

Resources 28

cache-staging redis git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -808,7 +808,7 @@ 

Resources 28

cache-valkey redis git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -829,7 +829,7 @@ 

Resources 28

catalog-atlas mongodb git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -857,7 +857,7 @@ 

Resources 28

catalog-staging mongodb git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -885,7 +885,7 @@ 

Resources 28

catalog-x509 mongodb git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -913,7 +913,7 @@ 

Resources 28

eks-staging kubernetes git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -932,7 +932,7 @@ 

Resources 28

events-kafka-scram kafka git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -955,7 +955,7 @@ 

Resources 28

events-kafka-staging kafka git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -978,7 +978,7 @@ 

Resources 28

events-rabbit-staging rabbitmq git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1000,7 +1000,7 @@ 

Resources 28

grafana web git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1025,7 +1025,7 @@ 

Resources 28

legacy-ftp tcp git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1044,7 +1044,7 @@ 

Resources 28

logs-opensearch opensearch git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1070,7 +1070,7 @@ 

Resources 28

orders-mq rabbitmq git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1092,7 +1092,7 @@ 

Resources 28

orders-mysql-staging mysql git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1131,7 +1131,7 @@ 

Resources 28

orders-prod postgres git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1155,7 +1155,7 @@ 

Resources 28

orders-staging postgres git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1194,7 +1194,7 @@ 

Resources 28

payments-msk kafka git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1216,7 +1216,7 @@ 

Resources 28

reviews-docdb mongodb git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1243,7 +1243,7 @@ 

Resources 28

search-opensearch opensearch git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1263,7 +1263,7 @@ 

Resources 28

search-staging elasticsearch git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1284,7 +1284,7 @@ 

Resources 28

tcp-blocked tcp git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1304,7 +1304,7 @@ 

Resources 28

tcp-echo tcp git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1324,7 +1324,7 @@ 

Resources 28

warehouse-prod redshift git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1348,7 +1348,7 @@ 

Resources 28

web-demo web git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1370,7 +1370,7 @@ 

Resources 28

web-demo-other web git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1392,7 +1392,7 @@ 

Resources 28

web-staging-1 ssh git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: resource
 version: v1
 metadata:
@@ -1415,7 +1415,7 @@ 

Bots 3

argo-sync oidc · roles deployer git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: bot
 version: v1
 metadata:
@@ -1437,7 +1437,7 @@ 

Bots 3

deploy-staging github_actions · roles deployer git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: bot
 version: v1
 metadata:
@@ -1462,7 +1462,7 @@ 

Bots 3

nightly-report gitlab · roles deployer git source "default" in namespace "default" -

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen manage.

+

Managed by git source "default" in namespace "default": change it there. A person with the admin role can move it to the console with limen admin manage.

kind: bot
 version: v1
 metadata:
diff --git a/docs/adr/0032-ai-agents-as-principals.md b/docs/adr/0032-ai-agents-as-principals.md
index 676e15d7..e0c7a5f1 100644
--- a/docs/adr/0032-ai-agents-as-principals.md
+++ b/docs/adr/0032-ai-agents-as-principals.md
@@ -27,7 +27,7 @@ How an agent proves who it is (a platform-issued token, a signed attestation fro
 ## Amendment: spike 0 and desk analysis of the open questions (2026-11-06)
 The status stays Proposed. This records what was built and what reading Limen at `0bc7da6` (ADR-0019, ADR-0025, ADR-0042 as built) suggests for the questions above. **Nothing below was run against a real agent runtime**; each answer is a recommendation for the owner, and spikes 1 to 3 are still to do.
 
-- **Spike 0 is built:** `limen config mcp serve` (#268; first named `limen mcp`), a read-only stdio server in the CLI with five tools (`status`, `ls`, `show`, `explain`, `requests`). It runs the CLI with `--json` as the logged-in person, so it grants nothing new and has no agent identity. It has not been tested against a live login. Threat model: TB15. `policy who-can` and `what-can` are left out because they read local policy files or need `limen:admin`.
+- **Spike 0 is built:** `limen config mcp serve` (#268), a read-only stdio server in the CLI with five tools (`status`, `ls`, `show`, `explain`, `requests`). It runs the CLI with `--json` as the logged-in person, so it grants nothing new and has no agent identity. It has not been tested against a live login. Threat model: TB15. `policy who-can` and `what-can` are left out because they read local policy files or need `limen:admin`.
 - **Where the server lives:** in the CLI first (`limen config mcp serve`). A separate component is justified only by a remote, multi-tenant server that many agents connect to, which has a larger attack surface and no demand yet. The separate `mcp-server-limen` repository was archived for this reason.
 - **How an agent proves who it is:** a platform-issued OIDC token through the existing bot join (ADR-0019), with no new login path. A signed attestation needs a trust root nobody has defined. Approval by the accountable person at start-up is an additional control, not the proof. A local desktop agent has no workload identity; today it can only use the person's own login, which is not an agent identity. The accountable person must come from something the issuer vouches for or from the `bot` document, never from a claim the agent makes about itself.
 - **Transcripts:** SSH is the best understood (the session recording plus the tool call and stated reason, linked by session id, redacted before storage). For databases, statements and row counts, not result rows (ADR-0033 already audits one `db.query` per statement without parameter values). Kubernetes and web apps are undecided.
diff --git a/docs/adr/0052-requests-command-group.md b/docs/adr/0052-requests-command-group.md
index a48412ed..74123a72 100644
--- a/docs/adr/0052-requests-command-group.md
+++ b/docs/adr/0052-requests-command-group.md
@@ -4,13 +4,13 @@
 - Date: 2026-11-11
 
 ## Context
-Access requests had five top-level verbs (`request`, `requests`, `approve`, `deny`, `cancel`), plus hidden duplicates under `limen admin`. The first three screens of `limen --help` were mostly one object. `limen manage changes` used `reject` for what `requests` calls `deny`.
+Access requests had five top-level verbs (`request`, `requests`, `approve`, `deny`, `cancel`), plus hidden duplicates under `limen admin`. The first three screens of `limen --help` were mostly one object. `limen admin manage changes` used `reject` for what `requests` calls `deny`.
 
 ## Decision
 - `limen request ` stays: it is the action nearly everyone takes, and it is short.
 - Everything else about requests lives under `limen requests`: `ls` (the default, so bare `limen requests` and `limen requests --approvals` still work), `approve`, `deny`, `cancel`. A group of its own, not subcommands of `request`, because `request` takes a resource name and a resource called `ls` or `approve` would be ambiguous.
-- Top-level `approve`, `deny` and `cancel` are removed. Typing one answers like any unknown command and names the new one (`did you mean limen requests approve`); so do the old `limen manage` and `limen completions`, and a few names people reach for by habit. `limen mcp` moved to `limen config mcp serve`, which `limen config mcp` prints for agents. `limen admin approve|deny` (hidden duplicates) are removed.
-- `limen manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change.
+- There are no top-level `approve`, `deny` or `cancel`, and no `limen admin approve|deny`. Typing a word that is not a command, such as `approve`, prints `did you mean limen requests approve`; the CLI has such tips for other names people reach for by habit.
+- `limen admin manage changes reject` is renamed `deny`, to match; `reject` stays as an alias. Server-side states and API names (`rejected`, `RejectChange`) do not change.
 - Help text carries no ADR numbers; they stay in code comments and docs for developers.
 
 This supersedes the command names in ADR-0025's "Console and CLI" paragraph. Behavior is unchanged.
diff --git a/docs/guides/ai-agents.md b/docs/guides/ai-agents.md
index 6d47281a..6efcca47 100644
--- a/docs/guides/ai-agents.md
+++ b/docs/guides/ai-agents.md
@@ -15,7 +15,7 @@ limen config mcp
 
 `--scope user` makes it available in every project. Without it, Claude Code adds the server only to the directory you ran the command in.
 
-For any other client that reads an `mcpServers` block (a `.mcp.json`, for example), run `limen config mcp`. (`limen mcp`, the old name, is gone; typing it points here.) It prints the Claude Code command and a JSON block with the full path of your `limen`, and changes no file. If you use a proxy other than the last one you signed in to, run `limen --server host:port config mcp` so the snippet carries it.
+For any other client that reads an `mcpServers` block (a `.mcp.json`, for example), run `limen config mcp`. It prints the Claude Code command and a JSON block with the full path of your `limen`, and changes no file. If you use a proxy other than the last one you signed in to, run `limen --server host:port config mcp` so the snippet carries it.
 
 Logins are short-lived. When yours expires, every tool answers `run limen login`. The agent cannot sign in for you, and that is deliberate.
 
diff --git a/docs/guides/cli.md b/docs/guides/cli.md
index 13504b77..6832fb8f 100644
--- a/docs/guides/cli.md
+++ b/docs/guides/cli.md
@@ -133,4 +133,4 @@ Every `✔` result grows into place (`·`, `•`, `✔`) in about a tenth of a s
 
 The logo at the top of `limen`, `limen --help` and `limen login` wipes in over about a second. Any call to the proxy that takes more than a third of a second (in `ls`, `show`, `requests`, `audit`, `admin` and most other commands) shows a spinner named for it, such as `List resources`. Slow steps show a spinner on stderr after about a third of a second, with the elapsed time after five seconds, and finish with a result line. Nothing moves when stderr is not a terminal, when `TERM=dumb`, when `CI` is set, or when `LIMEN_NO_ANIMATION` is set; you then get one plain `›` line per step. `NO_COLOR` removes colour but not the spinner. Ctrl-C during a wait ends it cleanly and exits 130.
 
-`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`. Some commands moved, and typing the old name prints the new one (`did you mean ...`): `limen completions` is `limen config completions`, `limen manage` is `limen admin manage`, `limen approve`, `deny` and `cancel` are `limen requests approve`, `deny` and `cancel`, and the admin commands (`lock`, `token`, `apply` ...) live under `limen admin`. `limen mcp` is `limen config mcp serve` (run by agents; `limen config mcp` prints how to add it).
+`limen config animations` shows and changes this, saved in `~/.limen/settings.json` (or `$LIMEN_HOME`): `--off` or `--on`, `--speed slow|normal|fast` (the logo takes about 1.8, 1 or 0.4 seconds), `--logo on|off`, `--call-spinner on|off`, and `--reset`. Each change plays the logo once so you can judge it. The environment variables still win for one run. Shell completions and the agent (MCP) setup live under the same command: `limen config completions zsh > ~/.zfunc/_limen` and `limen config mcp`.
diff --git a/docs/guides/management-api.md b/docs/guides/management-api.md
index 5d4d5ed7..d25c34cb 100644
--- a/docs/guides/management-api.md
+++ b/docs/guides/management-api.md
@@ -26,7 +26,7 @@ Anyone else gets `PERMISSION_DENIED`.
    - `limen.v1.Auth/BotLogin { method: "github_actions" | "gitlab" | "oidc", token, csr_der, bot: "" }` returns `cert_pem` and `expires_at_unix` (at most an hour; no refresh: log in again with a new token).
 3. **Call the API** on a new connection with `cert_pem` and the key as the TLS client certificate.
 
-`limen login --bot github_actions` does steps 1–2 (`crates/limen-cli/src/commands/bot.rs`) and `limen admin manage ...` (the old `limen manage ...` was removed; typing it prints the new name) does step 3; read them as a reference implementation.
+`limen login --bot github_actions` does steps 1–2 (`crates/limen-cli/src/commands/bot.rs`) and `limen admin manage ...` does step 3; read them as a reference implementation.
 
 ## Mapping a Terraform resource