rakomi 0.3.0 → 0.3.1

package/README.md

@@ -2,6 +2,16 @@
 
 The [Rakomi](https://rakomi.com) CLI. EU-native authentication as a service.
 
+## Ask your agent
+
+Add the Rakomi MCP server to your coding agent, then ask it directly:
+
+```sh
+claude mcp add --transport http rakomi https://mcp.rakomi.com/mcp
+```
+
+"List the AI agents connected to my Rakomi tenant."
+
 ## Getting started
 
 ```sh
@@ -15,7 +25,8 @@ session to get a short code to enter on another device instead. If you don't alr
 Rakomi administrator for the right value.
 
 `rakomi whoami` shows the tenant you signed in against ("Home tenant") and the tenant your other
-commands should treat as active ("Active tenant"). `rakomi tenants memberships` lists every tenant
+commands should treat as active ("Active tenant") — including whether that active selection was
+confirmed by the server or only remembered locally. `rakomi tenants memberships` lists every tenant
 your account is a verified member of, with your role in each. `rakomi use <slug>` looks one up from
 that list and remembers it — a slug you don't belong to fails with a plain "not found" rather than
 confirming the tenant exists; `rakomi use <tenant-id>` (a full id) remembers it directly without a
@@ -27,10 +38,12 @@ lookup, and `--tenant <tenant-id>` overrides it for one command.
 npx rakomi connect
 ```
 
-Detects Claude Code and writes the `.mcp.json` entry for you, or prints Claude Desktop's
-Custom-Connectors instructions when run with `--client claude-desktop`. Read access works
-immediately once the client finishes its own sign-in; write access is a separate step your
-tenant owner approves — see the [Connect an AI Agent guide](https://docs.rakomi.dev/guides/connect-an-ai-agent).
+Detects Claude Code and writes its config entry for you. Pass `--client <name>` for any other known
+client — a config file is written in that client's own shape for one that supports it, or its own
+connection steps are printed for a UI-only client (Claude Desktop, ChatGPT, JetBrains). Run
+`rakomi --help` for the current client list. Read access works immediately once the client finishes
+its own sign-in; write access is a separate step your tenant owner approves — see the
+[Connect an AI Agent guide](https://docs.rakomi.dev/guides/connect-an-ai-agent).
 
 Pass `--cimd-url <url>` (find it in your MCP client's own connection diagnostics) and `rakomi`
 confirms the connection for you instead of leaving you to check the dashboard; add `--write` to
@@ -57,7 +70,7 @@ token), sends a real invitation e-mail, and is refused under `--ci` — see
 | `logout` | clear the local session |
 | `whoami` | show the signed-in account, home tenant, and active tenant |
 | `use <tenant-id-or-slug>` | remember a tenant locally for `whoami`/future commands; a slug is server-verified |
-| `connect` | connect Claude Code / Claude Desktop to your tenant (read access) |
+| `connect` | connect an MCP client (Claude Code, Claude Desktop, and others — see `--help`) to your tenant (read access) |
 | `tenants create <name>` | create a tenant (`--owner me\|<email>`, `--slug <slug>`) |
 | `tenants list` | list tenants you provisioned |
 | `tenants memberships` | list tenants you're a verified member of |
@@ -73,10 +86,11 @@ token), sends a real invitation e-mail, and is refused under `--ci` — see
 | `--no-keychain` | store the session in a `0600` file instead of the OS keychain |
 | `--tenant-id <uuid>` | (`login`) the tenant to sign in against, if `RAKOMI_PLATFORM_TENANT_ID` isn't set for you |
 | `--tenant <tenant-id>` | override the active tenant for a single command (`whoami` today) |
-| `--client <name>` | `claude-code` or `claude-desktop` — required when more than one applies |
-| `--undo` | restore the `.mcp.json` `connect` last backed up |
+| `--client <name>` | one of the known MCP clients (`connect --help` prints the current list) — required when more than one applies |
+| `--name <server-name>` | (`connect`) the config key to write the entry under (default `rakomi`) — one name per workspace on a machine; a client keeps one login per server name |
+| `--undo` | restore the config file `connect` last backed up (for the same `--name`) |
 | `--cimd-url <url>` | (`connect`) the connecting client's own CIMD document URL — confirms/re-checks the connection |
-| `--status` | (`connect`) re-check status only — needs `--cimd-url`, never rewrites `.mcp.json` |
+| `--status` | (`connect`) re-check status only — needs `--cimd-url`, never rewrites the config file |
 | `-h`, `--help` | show help |
 | `-V`, `--version` | print the version |
 

package/SECURITY.md

@@ -9,8 +9,8 @@ While these packages remain pre-1.0 (`0.x`), they carry **no stability or suppor
 (SemVer 2.0.0 §4); the latest `0.x` line receives security updates on a best-effort basis.
 
 From version **1.0** onward, Rakomi maintains the current (N) and previous (N-1) MAJOR in parallel, with N-1 receiving
-security-only fixes. The CRA support period for each MAJOR is determined in accordance with
-**CRA Art. 13(8)** — at least five years, or the product's expected use time where shorter. The authoritative, machine-readable support windows are published at
+security-only fixes. For each MAJOR version of the Rakomi SDKs, CRE8EVE commits to a CRA support period of
+**at least five years (60 months)**, meeting the support-period requirement of **CRA Art. 13(8)**. The authoritative, machine-readable support windows are published at
 [`https://api.rakomi.com/.well-known/sdk-support.json`](https://api.rakomi.com/.well-known/sdk-support.json)
 and rendered for humans on the [SDK Support & Lifecycle page](https://rakomi.com/sdk-support). This
 document points at that single source rather than re-typing dated rows.

package/dist/billing-client.js

@@ -0,0 +1,19 @@
+import { CliError, EXIT } from './errors.js';
+import { describeError, request } from './http.js';
+export async function getBillingPlan(deps, opts) {
+    const url = new URL('/v1/billing/plan', opts.apiBaseUrl);
+    url.searchParams.set('tenant_id', opts.tenantId);
+    const result = await request(deps, {
+        method: 'GET',
+        url: url.toString(),
+        headers: opts.dpop ? undefined : { authorization: `Bearer ${opts.accessToken}` },
+        dpop: opts.dpop ? { key: opts.dpop, accessToken: opts.accessToken } : undefined,
+    });
+    if (result.status === 401) {
+        throw new CliError('Your session has expired. Run `rakomi login` again.', EXIT.NOT_LOGGED_IN);
+    }
+    if (result.status !== 200) {
+        throw new CliError(`Could not fetch your billing plan: ${describeError(result.body, result.status)}`, EXIT.FAIL);
+    }
+    return result.body;
+}

package/dist/client-registry.generated.js

@@ -0,0 +1,156 @@
+export const RAKOMI_SERVER_NAME = "rakomi";
+export const CLIENT_REGISTRY = [
+    {
+        id: "claude-code",
+        displayName: "Claude Code",
+        tier: "written",
+        status: "verified",
+        finishInstruction: "1. Run `claude` in this directory and approve the \"{{SERVER_NAME}}\" project server when prompted.\n2. Then run `claude mcp login {{SERVER_NAME}}` to finish sign-in in your browser (or use `/mcp` inside that session).",
+        config: {
+            scope: "project",
+            pathTemplate: ".mcp.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "url",
+            extraFields: { "type": "http" },
+        },
+        evidenceUrl: "https://code.claude.com/docs/en/mcp",
+    },
+    {
+        id: "vscode",
+        displayName: "VS Code",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open the Command Palette and run \"MCP: List Servers\", or the Extensions view — VS Code starts the OAuth flow automatically the first time it connects.",
+        config: {
+            scope: "project",
+            pathTemplate: ".vscode/mcp.json",
+            serialization: "json",
+            topLevelKey: "servers",
+            remoteUrlField: "url",
+            extraFields: { "type": "http" },
+        },
+        evidenceUrl: "https://code.visualstudio.com/docs/agents/reference/mcp-configuration",
+    },
+    {
+        id: "cursor",
+        displayName: "Cursor",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Cursor's MCP settings and connect — for a server that supports OAuth, Cursor completes the flow for you (or accepts static client credentials in mcp.json instead of dynamic client registration).",
+        config: {
+            scope: "project",
+            pathTemplate: ".cursor/mcp.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://cursor.com/docs/mcp",
+    },
+    {
+        id: "antigravity",
+        displayName: "Google Antigravity",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open the MCP Store or your MCP settings in Antigravity — it handles OAuth automatically for servers that support dynamic client registration (DCR).",
+        config: {
+            scope: "project",
+            pathTemplate: ".agents/mcp_config.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "serverUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://antigravity.google/docs/ide/mcp/",
+    },
+    {
+        id: "gemini-cli",
+        displayName: "Gemini CLI",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Run `gemini mcp list`, or just start a session — the Gemini CLI supports OAuth 2.0 for remote MCP servers and negotiates it automatically.",
+        config: {
+            scope: "project",
+            pathTemplate: ".gemini/settings.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "httpUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://google-gemini.github.io/gemini-cli/docs/tools/mcp-server.html",
+    },
+    {
+        id: "zed",
+        displayName: "Zed",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Settings -> AI -> MCP Servers in Zed — when a remote server has no Authorization header configured, Zed prompts you to authenticate with the standard MCP OAuth flow.",
+        config: {
+            scope: "project",
+            pathTemplate: ".zed/settings.json",
+            serialization: "json",
+            topLevelKey: "context_servers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://zed.dev/docs/ai/mcp",
+    },
+    {
+        id: "codex-cli",
+        displayName: "OpenAI Codex CLI",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Run `codex mcp login {{SERVER_NAME}}` to finish sign-in in your browser.",
+        config: {
+            scope: "user",
+            pathTemplate: ".codex/config.toml",
+            serialization: "toml",
+            topLevelKey: "mcp_servers",
+            remoteUrlField: "url",
+            extraFields: {},
+        },
+        evidenceUrl: "https://learn.chatgpt.com/docs/extend/mcp?surface=cli",
+    },
+    {
+        id: "devin-desktop",
+        displayName: "Devin Desktop",
+        tier: "written",
+        status: "documented-shape-only",
+        finishInstruction: "Open Devin Desktop — it supports OAuth for each transport type and prompts you to connect the first time.",
+        config: {
+            scope: "user",
+            pathTemplate: ".codeium/windsurf/mcp_config.json",
+            serialization: "json",
+            topLevelKey: "mcpServers",
+            remoteUrlField: "serverUrl",
+            extraFields: {},
+        },
+        evidenceUrl: "https://docs.devin.ai/desktop/cascade/mcp",
+    },
+    {
+        id: "claude-desktop",
+        displayName: "Claude Desktop",
+        tier: "instructed",
+        status: "verified",
+        finishInstruction: "Claude Desktop connects to remote MCP servers through Connectors, configured from your Claude account rather than a local file — there is nothing for `rakomi connect` to write.\n\n1. Open Settings -> Connectors in Claude Desktop and add a custom connector.\n2. Enter Rakomi's MCP server URL: {{MCP_URL}}\n3. Click Connect. Claude Desktop opens your browser at accounts.rakomi.com — sign in and\n   approve the read-only consent screen.",
+        evidenceUrl: "https://support.claude.com/en/articles/11175166-about-custom-connectors-remote-mcp",
+    },
+    {
+        id: "chatgpt",
+        displayName: "ChatGPT",
+        tier: "instructed",
+        status: "documented-shape-only",
+        finishInstruction: "In ChatGPT, go to Workspace Settings -> Permissions & Roles -> Developer mode, then add {{MCP_URL}} as a remote server. ChatGPT starts an OAuth flow to your workspace's identity provider once it's added.",
+        evidenceUrl: "https://developers.openai.com/api/docs/mcp",
+    },
+    {
+        id: "jetbrains",
+        displayName: "JetBrains AI Assistant",
+        tier: "instructed",
+        status: "documented-shape-only",
+        finishInstruction: "In your JetBrains IDE, go to Settings -> Tools -> AI Assistant -> Model Context Protocol (MCP), click Add, and paste: {\"mcpServers\":{\"{{SERVER_NAME}}\":{\"url\":\"{{MCP_URL}}\"}}}\nJetBrains' own documentation does not state whether it drives OAuth for you — be ready to complete sign-in in whatever browser tab it opens.",
+        evidenceUrl: "https://www.jetbrains.com/help/ai-assistant/mcp.html",
+    },
+];
+export const KNOWN_CLIENTS = CLIENT_REGISTRY.map((c) => c.id);

package/dist/clients.js

@@ -1,9 +1,17 @@
-export const KNOWN_CLIENTS = ['claude-code', 'claude-desktop'];
+import { CLIENT_REGISTRY, KNOWN_CLIENTS } from './client-registry.generated.js';
+import { CliError, EXIT } from './errors.js';
+export { CLIENT_REGISTRY, KNOWN_CLIENTS };
 export function isKnownClient(value) {
     return KNOWN_CLIENTS.includes(value);
 }
+export function clientRegistryEntry(id) {
+    const entry = CLIENT_REGISTRY.find((c) => c.id === id);
+    if (!entry)
+        throw new CliError(`clientRegistryEntry: unknown client '${id}' — this should be unreachable, isKnownClient() gates every caller`, EXIT.FAIL);
+    return entry;
+}
 export function clientDisplayName(client) {
-    return client === 'claude-code' ? 'Claude Code' : 'Claude Desktop';
+    return clientRegistryEntry(client).displayName;
 }
 export function resolveTargetClients(opts) {
     if (opts.explicitClient) {

package/dist/commands/connect.js

@@ -1,24 +1,29 @@
-import { AmbiguousClientError, clientDisplayName, resolveTargetClients } from '../clients.js';
+import { AmbiguousClientError, clientRegistryEntry, resolveTargetClients } from '../clients.js';
 import { pollCimdMaterialization, requestWriteElevation } from '../connect-client.js';
-import { DEFAULT_MCP_URL } from '../env.js';
 import { InteractiveRequiredError, NotLoggedInError, UsageError } from '../errors.js';
 import { resolveDpopKey } from '../install-key.js';
-import { mcpConfigPath, undoMcpConfigWrite, writeRakomiMcpServerEntry } from '../mcp-config.js';
-const CLAUDE_DESKTOP_INSTRUCTIONS = [
-    'Claude Desktop connects to remote MCP servers through Connectors, configured from your Claude',
-    'account rather than a local file — there is nothing for `rakomi connect` to write.',
-    '',
-    '1. Open Settings -> Connectors in Claude Desktop and add a custom connector.',
-    `2. Enter Rakomi's MCP server URL: ${DEFAULT_MCP_URL}`,
-    '3. Click Connect. Claude Desktop opens your browser at accounts.rakomi.com — sign in and',
-    '   approve the read-only consent screen.',
-].join('\n');
+import { backupSuffixFor, clientConfigPath, RAKOMI_SERVER_NAME, undoClientConfigWrite, writeClientMcpConfigEntry, } from '../mcp-config.js';
+import { resolveServerName } from '../server-name.js';
+import { undoClientTomlConfigWrite, writeClientTomlConfigEntry } from '../toml-config.js';
+function renderInstruction(instruction, mcpUrl, serverName) {
+    return instruction.replaceAll('{{MCP_URL}}', mcpUrl).replaceAll('{{SERVER_NAME}}', serverName);
+}
+function resolveSingleTargetClient(deps) {
+    let targets;
+    try {
+        targets = resolveTargetClients({ explicitClient: deps.explicitClient, claudeCodeDetected: deps.detectClaudeCode() });
+    }
+    catch (e) {
+        if (e instanceof AmbiguousClientError)
+            throw new UsageError(e.message);
+        throw e;
+    }
+    return clientRegistryEntry(targets[0]);
+}
 export async function runConnect(deps) {
+    const serverName = resolveServerName(deps.serverName);
     if (deps.undo) {
-        const restored = undoMcpConfigWrite(deps.cwd);
-        deps.stdout.write(restored
-            ? `Restored ${mcpConfigPath(deps.cwd)} from the backup \`rakomi connect\` made.\n`
-            : `No \`rakomi connect\` backup found at ${mcpConfigPath(deps.cwd)}.rakomi-backup — nothing to undo.\n`);
+        runUndo(deps, serverName);
         return;
     }
     const session = deps.session.read();
@@ -37,13 +42,33 @@ export async function runConnect(deps) {
             throw new UsageError(e.message);
         throw e;
     }
-    for (const client of targets) {
-        if (client === 'claude-desktop') {
-            deps.stdout.write(`${clientDisplayName(client)}:\n${CLAUDE_DESKTOP_INSTRUCTIONS}\n`);
+    for (const clientId of targets) {
+        const client = clientRegistryEntry(clientId);
+        if (client.tier === 'instructed') {
+            deps.stdout.write(`${client.displayName}:\n${renderInstruction(client.finishInstruction, deps.mcpUrl, serverName)}\n`);
             continue;
         }
-        await connectClaudeCode(deps, session);
+        if (clientId === 'claude-code') {
+            await connectClaudeCode(deps, session, client, serverName);
+        }
+        else {
+            connectGenericWrittenClient(deps, client, serverName);
+        }
+    }
+}
+function runUndo(deps, serverName) {
+    const client = resolveSingleTargetClient(deps);
+    if (!client.config) {
+        deps.stdout.write(`${client.displayName} writes no config file — nothing to undo.\n`);
+        return;
     }
+    const path = clientConfigPath(client, deps.cwd, deps.homeDir);
+    const restored = client.config.serialization === 'toml'
+        ? undoClientTomlConfigWrite(client, deps.cwd, deps.homeDir, serverName)
+        : undoClientConfigWrite(client, deps.cwd, deps.homeDir, serverName);
+    deps.stdout.write(restored
+        ? `Restored ${path} from the backup \`rakomi connect\` made.\n`
+        : `No \`rakomi connect\` backup found at ${path}${backupSuffixFor(serverName)} — nothing to undo.\n`);
 }
 async function reportStatus(deps, session) {
     if (!deps.cimdUrl) {
@@ -65,20 +90,35 @@ async function reportStatus(deps, session) {
         await requestWrite(deps, session, row.id);
     }
 }
-async function connectClaudeCode(deps, session) {
-    if (deps.dryRun) {
-        deps.stdout.write(`Would write ${mcpConfigPath(deps.cwd)} with mcpServers.rakomi -> ${deps.mcpUrl}. No file written (--dry-run).\n`);
-        return;
-    }
-    const result = writeRakomiMcpServerEntry(deps.cwd, deps.mcpUrl);
+function writeSummary(deps, result) {
     if (result.wrote) {
-        deps.stdout.write(`Wrote ${mcpConfigPath(deps.cwd)}${result.backedUp ? ' (previous file backed up)' : ''}.\n${result.diff}\n`);
+        deps.stdout.write(`Wrote ${result.path}${result.backedUp ? ' (previous file backed up)' : ''}.\n${result.diff}\n`);
     }
     else {
         deps.stdout.write(`${result.diff}\n`);
     }
-    deps.stdout.write('Now open Claude Code and run `claude mcp login rakomi` to finish sign-in in your browser.\n' +
+}
+function secondWorkspaceHint(client, explicitClient) {
+    const example = `${RAKOMI_SERVER_NAME}-<workspace>`;
+    const clientFlag = explicitClient ? ` --client ${explicitClient}` : '';
+    const where = client.config?.scope === 'user' ? '' : ' in that project';
+    const login = client.id === 'claude-code' ? `, then \`claude mcp login ${example}\`` : ', then sign in under that name';
+    return (`\nTip: another project on this machine bound to a different workspace? Sign-ins are kept per server ` +
+        `name, so give it its own: run \`rakomi connect${clientFlag} --name ${example}\`${where}${login}.\n`);
+}
+async function connectClaudeCode(deps, session, client, serverName) {
+    const path = clientConfigPath(client, deps.cwd, deps.homeDir);
+    if (deps.dryRun) {
+        deps.stdout.write(`Would write ${path} with ${client.config.topLevelKey}.${serverName} -> ${deps.mcpUrl}. No file written (--dry-run).\n`);
+        return;
+    }
+    const result = writeClientMcpConfigEntry(client, deps.cwd, deps.homeDir, deps.mcpUrl, serverName);
+    writeSummary(deps, result);
+    deps.stdout.write(`${renderInstruction(client.finishInstruction, deps.mcpUrl, serverName)}\n` +
         'Once approved, Claude Code has READ access to your tenant immediately.\n');
+    if (result.wrote && serverName === RAKOMI_SERVER_NAME) {
+        deps.stdout.write(secondWorkspaceHint(client, deps.explicitClient));
+    }
     if (!deps.cimdUrl) {
         deps.stdout.write('\nOnce connected, Rakomi can confirm it and (with --write) request write access for you — pass ' +
             '`--cimd-url <url>` (find it in your MCP client\'s own connection diagnostics) to use it, or ' +
@@ -93,8 +133,9 @@ async function connectClaudeCode(deps, session) {
         dpop,
     });
     if (!row) {
+        const nameFlag = serverName === RAKOMI_SERVER_NAME ? '' : ` --name ${serverName}`;
         deps.stdout.write(`\nNot connected yet. Ctrl+C is safe — resume any time with:\n` +
-            `  rakomi connect --status --cimd-url ${deps.cimdUrl}\n`);
+            `  rakomi connect --status${nameFlag} --cimd-url ${deps.cimdUrl}\n`);
         return;
     }
     deps.stdout.write(`\nConnected — access: ${row.agent_access.level}.\n`);
@@ -105,6 +146,21 @@ async function connectClaudeCode(deps, session) {
         await requestWrite(deps, session, row.id);
     }
 }
+function connectGenericWrittenClient(deps, client, serverName) {
+    const path = clientConfigPath(client, deps.cwd, deps.homeDir);
+    if (deps.dryRun) {
+        deps.stdout.write(`Would write ${path} with ${client.config.topLevelKey}.${serverName} -> ${deps.mcpUrl}. No file written (--dry-run).\n`);
+        return;
+    }
+    const result = client.config.serialization === 'toml'
+        ? writeClientTomlConfigEntry(client, deps.cwd, deps.homeDir, deps.mcpUrl, serverName)
+        : writeClientMcpConfigEntry(client, deps.cwd, deps.homeDir, deps.mcpUrl, serverName);
+    writeSummary(deps, result);
+    deps.stdout.write(`${renderInstruction(client.finishInstruction, deps.mcpUrl, serverName)}\n`);
+    if (result.wrote && serverName === RAKOMI_SERVER_NAME) {
+        deps.stdout.write(secondWorkspaceHint(client, deps.explicitClient));
+    }
+}
 async function requestWrite(deps, session, oauthClientId) {
     const dpop = resolveDpopKey(deps.keys, session);
     await requestWriteElevation(deps, { apiBaseUrl: deps.apiBaseUrl, accessToken: session.access_token, oauthClientId, dpop });

package/dist/commands/login.js

@@ -89,6 +89,7 @@ async function runLoopbackLogin(deps, apiUrl, cid, installKey, tenantId) {
             scope: LOGIN_SCOPE,
             tenantId,
         });
+        deps.stdout.write('Signing you in to your Rakomi developer account (separate from your tenants\' end-user accounts)…\n');
         deps.stdout.write(`Opening your browser to sign in:\n  ${authorizeUrl}\n`);
         await deps.openBrowser(authorizeUrl);
         const callback = await listener.waitForCallback(LOOPBACK_TIMEOUT_MS);

package/dist/commands/upgrade.js

@@ -0,0 +1,21 @@
+import { getBillingPlan } from '../billing-client.js';
+import { NotLoggedInError, UsageError } from '../errors.js';
+import { resolveDpopKey } from '../install-key.js';
+export async function runUpgrade(deps) {
+    const session = deps.session.read();
+    if (!session)
+        throw new NotLoggedInError();
+    const tenantId = deps.explicitTenant ?? deps.tenantConfig.read() ?? undefined;
+    if (!tenantId) {
+        throw new UsageError('No active tenant set. Run `rakomi use <tenant-slug>` first, or pass --tenant <id>.');
+    }
+    const dpop = resolveDpopKey(deps.keys, session);
+    const plan = await getBillingPlan(deps, {
+        apiBaseUrl: session.api_base_url,
+        accessToken: session.access_token,
+        tenantId,
+        dpop,
+    });
+    deps.stdout.write(`Current plan: ${plan.effective_plan}\nOpening ${plan.upgrade_url} in your browser...\n`);
+    await deps.openBrowser(plan.upgrade_url);
+}

package/dist/commands/use.js

@@ -21,6 +21,6 @@ export async function runUse(deps, args) {
         throw new UsageError(`No tenant membership found for "${args.tenantId}" — check the spelling, or ask a tenant ` +
             'admin to invite you. (Run `rakomi tenants memberships` to see the tenants you already belong to.)');
     }
-    deps.tenantConfig.write(membership.id);
+    deps.tenantConfig.write(membership.id, membership.slug);
     deps.stdout.write(`Active tenant set to ${membership.slug} (${membership.id}) — role: ${membership.role}.\n`);
 }

package/dist/commands/whoami.js

@@ -1,12 +1,29 @@
 import { NotLoggedInError } from '../errors.js';
 import { resolveDpopKey } from '../install-key.js';
 import { fetchUserInfo } from '../userinfo-client.js';
+function describeTokenStatus(expiresAt, now) {
+    return now >= expiresAt ? 'expired (will auto-refresh on next use)' : 'valid';
+}
+function describeActiveTenant(deps, activeTenantId) {
+    if (!activeTenantId)
+        return 'none set (run `rakomi use <tenant-slug>`)';
+    if (deps.explicitTenant)
+        return `${activeTenantId} (--tenant override for this command only — not verified)`;
+    const active = deps.tenantConfig.readActive?.() ?? null;
+    if (active && active.tenantId === activeTenantId && active.verifiedViaSlug) {
+        return `${activeTenantId} (verified member of "${active.verifiedViaSlug}")`;
+    }
+    return `${activeTenantId} (remembered locally — membership not verified; re-run \`rakomi use <tenant-slug>\` to verify)`;
+}
 export async function runWhoami(deps) {
-    const session = deps.session.read();
-    if (!session)
+    const initialSession = deps.session.read();
+    if (!initialSession)
         throw new NotLoggedInError();
-    const dpop = resolveDpopKey(deps.keys, session);
-    const info = await fetchUserInfo(deps, { apiBaseUrl: session.api_base_url, accessToken: session.access_token, dpop });
+    const dpop = resolveDpopKey(deps.keys, initialSession);
+    const info = await fetchUserInfo(deps, { apiBaseUrl: initialSession.api_base_url, accessToken: initialSession.access_token, dpop });
+    const session = deps.session.read() ?? initialSession;
+    const now = (deps.now ?? Date.now)();
+    const tokenStatus = describeTokenStatus(session.expires_at, now);
     const activeTenantId = deps.explicitTenant ?? deps.tenantConfig.read() ?? undefined;
     if (deps.json) {
         deps.stdout.write(JSON.stringify({
@@ -16,6 +33,8 @@ export async function runWhoami(deps) {
             org_role: info.org_role,
             session_store: deps.session.describePath(),
             token_type: session.token_type,
+            expires_at: new Date(session.expires_at).toISOString(),
+            token_status: tokenStatus,
             home_tenant_id: session.home_tenant_id,
             active_tenant_id: activeTenantId,
         }) + '\n');
@@ -26,8 +45,9 @@ export async function runWhoami(deps) {
         lines.push(`Organization: ${info.org_id}${info.org_role ? ` (${info.org_role})` : ''}`);
     lines.push(`API: ${session.api_base_url}`);
     lines.push(`Home tenant: ${session.home_tenant_id ?? 'unknown (this session did not authenticate via the CIMD-default flow)'}`);
-    lines.push(`Active tenant: ${activeTenantId ?? 'none set (run `rakomi use <tenant-id>`)'}`);
+    lines.push(`Active tenant: ${describeActiveTenant(deps, activeTenantId)}`);
     lines.push(`Session stored in: ${deps.session.describePath()}`);
     lines.push(`Token type: ${session.token_type}`);
+    lines.push(`Token expires: ${new Date(session.expires_at).toISOString()} (${tokenStatus})`);
     deps.stdout.write(lines.join('\n') + '\n');
 }

package/dist/http.js

@@ -7,7 +7,40 @@ function isErrorEnvelope(v) {
 function isProblemDetails(v) {
     return typeof v === 'object' && v !== null && !('error' in v) && ('code' in v || 'detail' in v || 'title' in v);
 }
+function errorDetails(body) {
+    if (isErrorEnvelope(body) && typeof body.error === 'object') {
+        const d = body.error.details;
+        return d && typeof d === 'object' ? d : undefined;
+    }
+    if (isProblemDetails(body)) {
+        return body.details && typeof body.details === 'object' ? body.details : undefined;
+    }
+    return undefined;
+}
+export function upsellFromProblem(body, status) {
+    if (status !== 403)
+        return undefined;
+    const url = errorDetails(body)?.upgrade_url;
+    return typeof url === 'string' && url.length > 0 ? { upgradeUrl: url } : undefined;
+}
+export function requestIdFromError(body) {
+    if (isErrorEnvelope(body) && typeof body.error === 'object') {
+        const id = body.error.request_id;
+        return typeof id === 'string' && id.length > 0 ? id : undefined;
+    }
+    if (isProblemDetails(body)) {
+        return typeof body.request_id === 'string' && body.request_id.length > 0 ? body.request_id : undefined;
+    }
+    return undefined;
+}
 export function describeError(body, status) {
+    const base = describeErrorBase(body, status);
+    const upsell = upsellFromProblem(body, status);
+    const withUpsell = upsell ? `${base}\nUpgrade: ${upsell.upgradeUrl}\nRun \`rakomi upgrade\` to open this in your browser.` : base;
+    const id = requestIdFromError(body);
+    return id ? `${withUpsell}\nRequest ID: ${id}` : withUpsell;
+}
+function describeErrorBase(body, status) {
     if (isErrorEnvelope(body)) {
         if (typeof body.error === 'string')
             return body.error_description || body.error;
@@ -72,6 +105,8 @@ async function performOnce(deps, req, dpopNonce) {
                 parsed = JSON.parse(text);
             }
             catch {
+                if (res.status < 200 || res.status >= 300)
+                    return { status: res.status, body: {}, headers: res.headers };
                 throw new CliError('The Rakomi API returned a response the CLI could not understand.', EXIT.FAIL);
             }
         }
@@ -89,7 +124,7 @@ function isDpopNonceChallenge(result) {
     const nonce = result.headers.get('dpop-nonce');
     return nonce && nonce.length > 0 ? nonce : undefined;
 }
-export async function request(deps, req) {
+async function performWithNonceRetry(deps, req) {
     const first = await performOnce(deps, req);
     if (!req.dpop)
         return first;
@@ -102,3 +137,25 @@ export async function request(deps, req) {
     }
     return retry;
 }
+function isAuthenticatedRequest(req) {
+    if (req.dpop?.accessToken !== undefined)
+        return true;
+    return typeof req.headers?.authorization === 'string' && req.headers.authorization.length > 0;
+}
+function withRefreshedCredentials(req, credentials) {
+    if (req.dpop?.accessToken !== undefined) {
+        return { ...req, dpop: { ...req.dpop, accessToken: credentials.accessToken } };
+    }
+    return { ...req, headers: { ...req.headers, authorization: `Bearer ${credentials.accessToken}` } };
+}
+export async function request(deps, req) {
+    const first = await performWithNonceRetry(deps, req);
+    if (first.status !== 401)
+        return first;
+    if (!deps.onUnauthorized || !isAuthenticatedRequest(req))
+        return first;
+    const refreshed = await deps.onUnauthorized();
+    if (!refreshed)
+        return first;
+    return performWithNonceRetry(deps, withRefreshedCredentials(req, refreshed));
+}

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { delimiter, join } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
@@ -10,6 +11,7 @@ import { runLogin, runLoginCi } from './commands/login.js';
 import { runLogout } from './commands/logout.js';
 import { runMcpToolsCi } from './commands/mcp.js';
 import { runTenantsClaim, runTenantsCreate, runTenantsList, runTenantsMemberships, runTenantsRelease } from './commands/tenants.js';
+import { runUpgrade } from './commands/upgrade.js';
 import { runUse } from './commands/use.js';
 import { runWhoami } from './commands/whoami.js';
 import { apiBaseUrl, DEFAULT_MCP_URL } from './env.js';
@@ -17,6 +19,7 @@ import { CliError, EXIT, UsageError } from './errors.js';
 import { startLoopbackListener } from './loopback-server.js';
 import { resolveStores } from './session.js';
 import { FileTenantConfigStore } from './tenant-config.js';
+import { refreshSession } from './token-refresh.js';
 import { helpText, usageLine } from './usage.js';
 const GLOBAL_OPTIONS = {
     json: { type: 'boolean' },
@@ -37,6 +40,7 @@ const GLOBAL_OPTIONS = {
     label: { type: 'string' },
     'cimd-url': { type: 'string' },
     status: { type: 'boolean' },
+    name: { type: 'string' },
     help: { type: 'boolean', short: 'h' },
     version: { type: 'boolean', short: 'V' },
 };
@@ -89,6 +93,13 @@ async function dispatch(args, deps) {
     const dryRun = values['dry-run'] === true;
     const json = values.json === true;
     const httpDeps = { fetchImpl: deps.fetchImpl };
+    const onUnauthorized = async () => {
+        const current = deps.session.read();
+        if (!current)
+            return undefined;
+        return refreshSession({ fetchImpl: deps.fetchImpl }, current, deps.keys, deps.session, () => Date.now());
+    };
+    const authHttpDeps = { ...httpDeps, onUnauthorized };
     const [command, ...rest] = positionals;
     switch (command) {
         case 'login': {
@@ -126,7 +137,7 @@ async function dispatch(args, deps) {
             return EXIT.OK;
         case 'whoami':
             await runWhoami({
-                ...httpDeps,
+                ...authHttpDeps,
                 session: deps.session,
                 keys: deps.keys,
                 json,
@@ -139,15 +150,27 @@ async function dispatch(args, deps) {
             const tenantId = rest[0];
             if (!tenantId)
                 throw new UsageError('Usage: rakomi use <tenant-id-or-slug>');
-            await runUse({ ...httpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, stdout: deps.stdout }, { tenantId });
+            await runUse({ ...authHttpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, stdout: deps.stdout }, { tenantId });
             return EXIT.OK;
         }
+        case 'upgrade':
+            await runUpgrade({
+                ...authHttpDeps,
+                session: deps.session,
+                keys: deps.keys,
+                tenantConfig: deps.tenantConfig,
+                explicitTenant: typeof values.tenant === 'string' ? values.tenant : undefined,
+                openBrowser: systemBrowserOpener(),
+                stdout: deps.stdout,
+            });
+            return EXIT.OK;
         case 'connect':
             await runConnect({
-                ...httpDeps,
+                ...authHttpDeps,
                 session: deps.session,
                 keys: deps.keys,
                 cwd: deps.cwd,
+                homeDir: homedir(),
                 apiBaseUrl: apiBaseUrl(deps.env),
                 mcpUrl: deps.env.RAKOMI_API_URL ? `${apiBaseUrl(deps.env)}/mcp` : DEFAULT_MCP_URL,
                 detectClaudeCode: deps.detectClaudeCode,
@@ -159,6 +182,7 @@ async function dispatch(args, deps) {
                 explicitClient: typeof values.client === 'string' ? values.client : undefined,
                 cimdUrl: typeof values['cimd-url'] === 'string' ? values['cimd-url'] : undefined,
                 status: values.status === true,
+                serverName: typeof values.name === 'string' ? values.name : undefined,
             });
             return EXIT.OK;
         case 'mcp': {
@@ -187,22 +211,22 @@ async function dispatch(args, deps) {
                 const name = tenantArgs[0];
                 if (!name)
                     throw new UsageError('Usage: rakomi tenants create <name> [--owner me|<email>] [--slug <slug>]');
-                await runTenantsCreate({ ...httpDeps, session: deps.session, keys: deps.keys, json, dryRun, ci, stdout: deps.stdout }, { name, slug: typeof values.slug === 'string' ? values.slug : undefined, owner: typeof values.owner === 'string' ? values.owner : 'me' });
+                await runTenantsCreate({ ...authHttpDeps, session: deps.session, keys: deps.keys, json, dryRun, ci, stdout: deps.stdout }, { name, slug: typeof values.slug === 'string' ? values.slug : undefined, owner: typeof values.owner === 'string' ? values.owner : 'me' });
                 return EXIT.OK;
             }
             if (sub === 'list') {
-                await runTenantsList({ ...httpDeps, session: deps.session, keys: deps.keys, json, stdout: deps.stdout });
+                await runTenantsList({ ...authHttpDeps, session: deps.session, keys: deps.keys, json, stdout: deps.stdout });
                 return EXIT.OK;
             }
             if (sub === 'memberships') {
-                await runTenantsMemberships({ ...httpDeps, session: deps.session, keys: deps.keys, json, stdout: deps.stdout });
+                await runTenantsMemberships({ ...authHttpDeps, session: deps.session, keys: deps.keys, json, stdout: deps.stdout });
                 return EXIT.OK;
             }
             if (sub === 'claim') {
                 if (values.ci !== true) {
                     throw new UsageError('rakomi tenants claim requires --ci (no interactive form exists yet).');
                 }
-                await runTenantsClaim({ ...httpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, json, stdout: deps.stdout }, {
+                await runTenantsClaim({ ...authHttpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, json, stdout: deps.stdout }, {
                     parentTenantId: typeof values.tenant === 'string' ? values.tenant : undefined,
                     ttlSeconds: parseTtlSeconds(values['ttl-seconds']),
                     label: typeof values.label === 'string' ? values.label : undefined,
@@ -216,7 +240,7 @@ async function dispatch(args, deps) {
                 const tenantId = tenantArgs[0];
                 if (!tenantId)
                     throw new UsageError('Usage: rakomi tenants release --ci <tenant-id> [--tenant <parent-tenant-id>]');
-                await runTenantsRelease({ ...httpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, json, stdout: deps.stdout }, { tenantId, parentTenantId: typeof values.tenant === 'string' ? values.tenant : undefined });
+                await runTenantsRelease({ ...authHttpDeps, session: deps.session, keys: deps.keys, tenantConfig: deps.tenantConfig, json, stdout: deps.stdout }, { tenantId, parentTenantId: typeof values.tenant === 'string' ? values.tenant : undefined });
                 return EXIT.OK;
             }
             throw new UsageError('Usage: rakomi tenants <create|list|claim|release> ...');

package/dist/loopback-server.js

@@ -1,11 +1,90 @@
 import { createServer } from 'node:http';
 import { CliError, EXIT } from './errors.js';
-const SUCCESS_PAGE = `<!doctype html><html><head><title>rakomi login</title></head>
-<body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;text-align:center">
-<h1>Signed in</h1><p>You can close this tab and return to your terminal.</p></body></html>`;
-const ERROR_PAGE = (message) => `<!doctype html><html><head><title>rakomi login</title></head>
-<body style="font-family:system-ui,sans-serif;max-width:32rem;margin:4rem auto;text-align:center">
-<h1>Sign-in failed</h1><p>${escapeHtml(message)}</p><p>Return to your terminal and try again.</p></body></html>`;
+const PAGE_STYLE = `
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-family: "Inter", ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
+    background: linear-gradient(to bottom, #F3F4F7, #ECEEF2, #E4E6EB);
+    color: #2A2A2A;
+  }
+  .card {
+    max-width: 26rem;
+    width: calc(100% - 3rem);
+    margin: 1.5rem;
+    padding: 2.5rem 2rem;
+    border-radius: 1rem;
+    text-align: center;
+    background: rgba(255, 255, 255, 0.75);
+    border: 1px solid rgba(29, 85, 102, 0.14);
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 8px 24px rgba(29, 85, 102, 0.08);
+  }
+  .wordmark {
+    font-size: 0.8125rem;
+    font-weight: 600;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: #1d5566;
+    margin: 0 0 1.5rem;
+  }
+  .icon {
+    width: 3rem;
+    height: 3rem;
+    margin: 0 auto 1.25rem;
+    border-radius: 999px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 1.5rem;
+    line-height: 1;
+  }
+  .icon.success { background: rgba(40, 114, 77, 0.14); color: #28724D; }
+  .icon.error { background: rgba(189, 46, 46, 0.14); color: #BD2E2E; }
+  h1 {
+    font-size: 1.25rem;
+    font-weight: 700;
+    line-height: 1.25;
+    margin: 0 0 0.5rem;
+    color: #2A2A2A;
+  }
+  p {
+    font-size: 0.9375rem;
+    line-height: 1.5;
+    color: #4A4A4A;
+    margin: 0 0 0.375rem;
+  }
+  p.hint { color: #616161; font-size: 0.875rem; }
+  @media (prefers-color-scheme: dark) {
+    body { background: linear-gradient(to bottom right, #23242c, #1e1f26, #191a20); color: #e6e7ec; }
+    .card { background: rgba(255, 255, 255, 0.07); border-color: rgba(255, 255, 255, 0.10); box-shadow: 0 1px 3px rgba(0, 0, 0, 0.3); }
+    .wordmark { color: #51b0cd; }
+    .icon.success { background: rgba(98, 200, 146, 0.16); color: #62C892; }
+    .icon.error { background: rgba(242, 159, 159, 0.16); color: #F29F9F; }
+    h1 { color: #e6e7ec; }
+    p { color: #a1a3ad; }
+    p.hint { color: #a1a3ad; }
+  }
+`;
+const SUCCESS_PAGE = `<!doctype html><html><head><meta charset="utf-8"><title>rakomi login</title><style>${PAGE_STYLE}</style></head>
+<body><main class="card">
+<p class="wordmark">rakomi</p>
+<div class="icon success" aria-hidden="true">&#10003;</div>
+<h1>Signed in</h1>
+<p>You can close this tab and return to your terminal.</p>
+</main></body></html>`;
+const ERROR_PAGE = (message) => `<!doctype html><html><head><meta charset="utf-8"><title>rakomi login</title><style>${PAGE_STYLE}</style></head>
+<body><main class="card">
+<p class="wordmark">rakomi</p>
+<div class="icon error" aria-hidden="true">&#10005;</div>
+<h1>Sign-in failed</h1>
+<p>${escapeHtml(message)}</p>
+<p class="hint">Return to your terminal and try again.</p>
+</main></body></html>`;
 function escapeHtml(s) {
     return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }

package/dist/mcp-config.js

@@ -1,7 +1,12 @@
-import { readFileSync, writeFileSync } from 'node:fs';
-import { join } from 'node:path';
-export const RAKOMI_SERVER_NAME = 'rakomi';
-const BACKUP_SUFFIX = '.rakomi-backup';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { RAKOMI_SERVER_NAME } from './client-registry.generated.js';
+import { CliError, EXIT } from './errors.js';
+export { RAKOMI_SERVER_NAME };
+export function backupSuffixFor(serverName) {
+    return `.${serverName}-backup`;
+}
+export const BACKUP_SUFFIX = backupSuffixFor(RAKOMI_SERVER_NAME);
 function readIfPresent(file) {
     try {
         return readFileSync(file, 'utf8');
@@ -12,13 +17,17 @@ function readIfPresent(file) {
         throw err;
     }
 }
-export function mcpConfigPath(projectDir) {
-    return join(projectDir, '.mcp.json');
+export function clientConfigPath(client, cwd, homeDir) {
+    if (!client.config) {
+        throw new CliError(`clientConfigPath: '${client.id}' is instructed-tier — it has no config file to write`, EXIT.FAIL);
+    }
+    const base = client.config.scope === 'user' ? homeDir : cwd;
+    return join(base, client.config.pathTemplate);
 }
-function backupPath(configPath) {
-    return `${configPath}${BACKUP_SUFFIX}`;
+function backupPath(configPath, serverName) {
+    return `${configPath}${backupSuffixFor(serverName)}`;
 }
-function readConfig(path) {
+function readJsonConfig(path) {
     const text = readIfPresent(path);
     if (text === null)
         return {};
@@ -32,43 +41,57 @@ function readConfig(path) {
         return {};
     }
 }
-export function mergeRakomiServerEntry(config, mcpUrl) {
-    const previousEntry = config.mcpServers?.[RAKOMI_SERVER_NAME];
-    const nextEntry = { type: 'http', url: mcpUrl };
-    const alreadyIdentical = previousEntry !== undefined &&
-        typeof previousEntry === 'object' &&
-        previousEntry.type === 'http' &&
-        previousEntry.url === mcpUrl;
+function shallowEqualStringRecord(a, b) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every((k) => a[k] === b[k]);
+}
+export function mergeClientServerEntry(config, client, mcpUrl, serverName = RAKOMI_SERVER_NAME) {
+    if (!client.config || client.config.serialization !== 'json') {
+        throw new CliError(`mergeClientServerEntry: '${client.id}' is not a JSON-shaped written client`, EXIT.FAIL);
+    }
+    const { topLevelKey, remoteUrlField, extraFields } = client.config;
+    const bucket = config[topLevelKey] ?? {};
+    const previousEntry = bucket[serverName];
+    const nextEntry = { ...extraFields, [remoteUrlField]: mcpUrl };
+    const alreadyIdentical = previousEntry !== undefined && shallowEqualStringRecord(previousEntry, nextEntry);
     if (alreadyIdentical)
         return { config, changed: false, previousEntry };
     const merged = {
         ...config,
-        mcpServers: { ...(config.mcpServers ?? {}), [RAKOMI_SERVER_NAME]: nextEntry },
+        [topLevelKey]: { ...bucket, [serverName]: nextEntry },
     };
     return { config: merged, changed: true, previousEntry };
 }
-export function writeRakomiMcpServerEntry(projectDir, mcpUrl) {
-    const path = mcpConfigPath(projectDir);
-    const before = readConfig(path);
-    const { config: after, changed, previousEntry } = mergeRakomiServerEntry(before, mcpUrl);
+export function writeClientMcpConfigEntry(client, cwd, homeDir, mcpUrl, serverName = RAKOMI_SERVER_NAME) {
+    const path = clientConfigPath(client, cwd, homeDir);
+    const before = readJsonConfig(path);
+    const { config: after, changed, previousEntry } = mergeClientServerEntry(before, client, mcpUrl, serverName);
     if (!changed) {
-        return { wrote: false, backedUp: false, diff: `${RAKOMI_SERVER_NAME} already configured with ${mcpUrl} — no change.` };
+        return { wrote: false, backedUp: false, diff: `${serverName} already configured with ${mcpUrl} — no change.`, path };
     }
     let backedUp = false;
     const existing = readIfPresent(path);
     if (existing !== null) {
-        writeFileSync(backupPath(path), existing);
+        writeFileSync(backupPath(path, serverName), existing);
         backedUp = true;
     }
+    else {
+        mkdirSync(dirname(path), { recursive: true });
+    }
     writeFileSync(path, JSON.stringify(after, null, 2) + '\n');
+    const topLevelKey = client.config.topLevelKey;
+    const nowEntry = after[topLevelKey][serverName];
     const diff = previousEntry
-        ? `mcpServers.${RAKOMI_SERVER_NAME}: ${JSON.stringify(previousEntry)} -> ${JSON.stringify(after.mcpServers?.[RAKOMI_SERVER_NAME])}`
-        : `mcpServers.${RAKOMI_SERVER_NAME}: (added) ${JSON.stringify(after.mcpServers?.[RAKOMI_SERVER_NAME])}`;
-    return { wrote: true, backedUp, diff };
+        ? `${topLevelKey}.${serverName}: ${JSON.stringify(previousEntry)} -> ${JSON.stringify(nowEntry)}`
+        : `${topLevelKey}.${serverName}: (added) ${JSON.stringify(nowEntry)}`;
+    return { wrote: true, backedUp, diff, path };
 }
-export function undoMcpConfigWrite(projectDir) {
-    const path = mcpConfigPath(projectDir);
-    const backup = readIfPresent(backupPath(path));
+export function undoClientConfigWrite(client, cwd, homeDir, serverName = RAKOMI_SERVER_NAME) {
+    const path = clientConfigPath(client, cwd, homeDir);
+    const backup = readIfPresent(backupPath(path, serverName));
     if (backup === null)
         return false;
     writeFileSync(path, backup);

package/dist/server-name.js

@@ -0,0 +1,15 @@
+import { RAKOMI_SERVER_NAME } from './client-registry.generated.js';
+import { UsageError } from './errors.js';
+export const SERVER_NAME_PATTERN = /^[a-z][a-z0-9-]{0,39}$/;
+export const SERVER_NAME_MAX_LENGTH = 40;
+export function isValidServerName(value) {
+    return SERVER_NAME_PATTERN.test(value);
+}
+export function resolveServerName(raw) {
+    if (raw === undefined)
+        return RAKOMI_SERVER_NAME;
+    if (isValidServerName(raw))
+        return raw;
+    throw new UsageError(`Invalid --name "${raw}": use lowercase letters, digits and hyphens only, starting with a letter, ` +
+        `at most ${SERVER_NAME_MAX_LENGTH} characters (for example \`${RAKOMI_SERVER_NAME}-acme\`).`);
+}

package/dist/tenant-config.js

@@ -5,7 +5,9 @@ function isStoredTenantConfig(value) {
     if (typeof value !== 'object' || value === null)
         return false;
     const v = value;
-    return typeof v.active_tenant_id === 'string' && v.active_tenant_id.length > 0;
+    if (typeof v.active_tenant_id !== 'string' || v.active_tenant_id.length === 0)
+        return false;
+    return v.verified_via_slug === undefined || typeof v.verified_via_slug === 'string';
 }
 function tenantConfigFilePath(env) {
     return join(configDir(env), 'tenant.json');
@@ -18,18 +20,27 @@ export class FileTenantConfigStore {
         this.path = tenantConfigFilePath(env);
     }
     read() {
+        return this.readActive()?.tenantId ?? null;
+    }
+    readActive() {
         try {
             const raw = readFileSync(this.path, 'utf8');
             const parsed = JSON.parse(raw);
-            return isStoredTenantConfig(parsed) ? parsed.active_tenant_id : null;
+            if (!isStoredTenantConfig(parsed))
+                return null;
+            return parsed.verified_via_slug !== undefined && parsed.verified_via_slug.length > 0
+                ? { tenantId: parsed.active_tenant_id, verifiedViaSlug: parsed.verified_via_slug }
+                : { tenantId: parsed.active_tenant_id };
         }
         catch {
             return null;
         }
     }
-    write(tenantId) {
+    write(tenantId, verifiedViaSlug) {
         mkdirSync(this.dir, { recursive: true, mode: 0o700 });
-        const config = { active_tenant_id: tenantId };
+        const config = verifiedViaSlug !== undefined && verifiedViaSlug.length > 0
+            ? { active_tenant_id: tenantId, verified_via_slug: verifiedViaSlug }
+            : { active_tenant_id: tenantId };
         writeFileSync(this.path, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
         try {
             chmodSync(this.path, 0o600);

package/dist/token-refresh.js

@@ -0,0 +1,56 @@
+import { CliError, EXIT } from './errors.js';
+import { request, requestIdFromError } from './http.js';
+import { resolveDpopKey } from './install-key.js';
+export async function refreshSession(deps, session, keys, sessionStore, now) {
+    if (!session.refresh_token)
+        return undefined;
+    const dpopKey = resolveDpopKey(keys, session);
+    let result;
+    try {
+        result = await request({ fetchImpl: deps.fetchImpl, timeoutMs: deps.timeoutMs }, {
+            method: 'POST',
+            url: `${session.api_base_url}/oauth/token`,
+            form: {
+                grant_type: 'refresh_token',
+                refresh_token: session.refresh_token,
+                client_id: session.client_id,
+            },
+            dpop: dpopKey ? { key: dpopKey } : undefined,
+        });
+    }
+    catch (err) {
+        const cause = err instanceof CliError ? err.message : 'The Rakomi API could not be reached.';
+        throw new CliError(`Could not refresh your session: ${cause} You are still logged in — try again in a moment.`, EXIT.FAIL);
+    }
+    if (isTransientStatus(result.status)) {
+        const retryAfter = retryAfterSeconds(result.headers.get('retry-after'));
+        const wait = retryAfter !== undefined ? `in ${retryAfter}s` : 'in a moment';
+        const id = requestIdFromError(result.body);
+        throw new CliError(`Could not refresh your session: the Rakomi API is temporarily unavailable (HTTP ${result.status}). ` +
+            `You are still logged in — try again ${wait}.${id ? `\nRequest ID: ${id}` : ''}`, EXIT.FAIL);
+    }
+    if (result.status !== 200)
+        return undefined;
+    const token = result.body;
+    if (typeof token.access_token !== 'string' || token.access_token.length === 0)
+        return undefined;
+    if (typeof token.expires_in !== 'number' || !Number.isFinite(token.expires_in))
+        return undefined;
+    const updated = {
+        ...session,
+        access_token: token.access_token,
+        refresh_token: token.refresh_token ?? session.refresh_token,
+        token_type: token.token_type === 'DPoP' ? 'DPoP' : 'Bearer',
+        expires_at: now() + token.expires_in * 1000,
+    };
+    sessionStore.write(updated);
+    return { accessToken: updated.access_token };
+}
+function isTransientStatus(status) {
+    return status >= 500 || status === 429 || status === 408;
+}
+function retryAfterSeconds(header) {
+    if (header === null || !/^\d+$/.test(header.trim()))
+        return undefined;
+    return Number(header.trim());
+}

package/dist/toml-config.js

@@ -0,0 +1,96 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { CliError, EXIT } from './errors.js';
+import { backupSuffixFor, clientConfigPath, RAKOMI_SERVER_NAME } from './mcp-config.js';
+function readIfPresent(file) {
+    try {
+        return readFileSync(file, 'utf8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+function backupPath(configPath, serverName) {
+    return `${configPath}${backupSuffixFor(serverName)}`;
+}
+function tomlBasicString(value) {
+    return JSON.stringify(value);
+}
+function renderTomlBlockLines(header, fields) {
+    const lines = [`[${header}]`];
+    for (const [key, value] of Object.entries(fields)) {
+        lines.push(`${key} = ${tomlBasicString(value)}`);
+    }
+    return lines;
+}
+export function mergeTomlServerTable(text, client, mcpUrl, serverName = RAKOMI_SERVER_NAME) {
+    if (!client.config || client.config.serialization !== 'toml') {
+        throw new CliError(`mergeTomlServerTable: '${client.id}' is not a TOML-shaped written client`, EXIT.FAIL);
+    }
+    const header = `${client.config.topLevelKey}.${serverName}`;
+    const fields = { ...client.config.extraFields, [client.config.remoteUrlField]: mcpUrl };
+    const newBlockLines = renderTomlBlockLines(header, fields);
+    const newBlockText = newBlockLines.join('\n');
+    const lines = text.length > 0 ? text.split('\n') : [];
+    const headerLine = `[${header}]`;
+    let start = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i]?.trim() === headerLine) {
+            start = i;
+            break;
+        }
+    }
+    if (start === -1) {
+        const needsSeparator = lines.length > 0 && lines[lines.length - 1] !== '';
+        const prefix = needsSeparator ? [...lines, ''] : lines;
+        const nextLines = [...prefix, ...newBlockLines, ''];
+        return { text: nextLines.join('\n'), changed: true, previousBlock: undefined };
+    }
+    let end = lines.length;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (/^\[/.test(lines[i] ?? '')) {
+            end = i;
+            break;
+        }
+    }
+    let blockEnd = end;
+    while (blockEnd > start + 1 && lines[blockEnd - 1] === '')
+        blockEnd--;
+    const previousBlock = lines.slice(start, blockEnd).join('\n');
+    if (previousBlock === newBlockText) {
+        return { text, changed: false, previousBlock };
+    }
+    const nextLines = [...lines.slice(0, start), ...newBlockLines, ...lines.slice(end)];
+    return { text: nextLines.join('\n'), changed: true, previousBlock };
+}
+export function writeClientTomlConfigEntry(client, cwd, homeDir, mcpUrl, serverName = RAKOMI_SERVER_NAME) {
+    const path = clientConfigPath(client, cwd, homeDir);
+    const existing = readIfPresent(path);
+    const before = existing ?? '';
+    const { text: after, changed, previousBlock } = mergeTomlServerTable(before, client, mcpUrl, serverName);
+    if (!changed) {
+        return { wrote: false, backedUp: false, diff: `${serverName} already configured with ${mcpUrl} — no change.`, path };
+    }
+    let backedUp = false;
+    if (existing !== null) {
+        writeFileSync(backupPath(path, serverName), existing);
+        backedUp = true;
+    }
+    else {
+        mkdirSync(dirname(path), { recursive: true });
+    }
+    writeFileSync(path, after.endsWith('\n') ? after : `${after}\n`);
+    const header = `${client.config.topLevelKey}.${serverName}`;
+    const diff = previousBlock !== undefined ? `[${header}]: updated` : `[${header}]: (added)`;
+    return { wrote: true, backedUp, diff, path };
+}
+export function undoClientTomlConfigWrite(client, cwd, homeDir, serverName = RAKOMI_SERVER_NAME) {
+    const path = clientConfigPath(client, cwd, homeDir);
+    const backup = readIfPresent(backupPath(path, serverName));
+    if (backup === null)
+        return false;
+    writeFileSync(path, backup);
+    return true;
+}

package/dist/usage.js

@@ -1,4 +1,6 @@
+import { KNOWN_CLIENTS } from './clients.js';
 export function helpText() {
+    const clientList = KNOWN_CLIENTS.join(' | ');
     return [
         'rakomi — the Rakomi CLI: sign in, connect an AI agent, and provision tenants',
         '',
@@ -13,12 +15,14 @@ export function helpText() {
         '  logout                   clear the local session',
         '  whoami                   show the signed-in account, home tenant, and active tenant',
         '  use <tenant-id-or-slug>  remember a tenant locally (whoami/future commands); a UUID is stored as-is, a slug is server-verified',
-        '  connect                  connect Claude Code / Claude Desktop to your tenant (read access)',
+        '  upgrade                  open your current tenant\'s upgrade page in the browser',
+        '  connect                  connect an MCP client to your tenant (read access)',
         '    --write                also request write access for the connected client',
-        '    --client <name>        claude-code | claude-desktop (required if more than one applies)',
-        '    --undo                 restore the .mcp.json this command last backed up',
+        `    --client <name>        ${clientList} (required if more than one applies)`,
+        '    --name <server-name>   the config key to write the entry under (default: rakomi) — one name per workspace on a machine',
+        '    --undo                 restore the config file this command last backed up (for the same --name)',
         '    --cimd-url <url>       the connecting client\'s own CIMD document URL — confirms the connection',
-        '    --status               re-check status only (needs --cimd-url; never rewrites .mcp.json)',
+        '    --status               re-check status only (needs --cimd-url; never rewrites the config file)',
         '  tenants create <name>    create a tenant (parent-tenant only; depth-1 enforced server-side)',
         '    --owner <me|email>     who becomes the new tenant\'s owner (default: me)',
         '    --slug <slug>          optional; auto-derived + suffixed if omitted',
@@ -38,7 +42,7 @@ export function helpText() {
         '  --dry-run                print what would happen, make no writes or mutating calls',
         '  --no-browser             use the RFC 8628 device-code flow instead of opening a browser',
         '  --no-keychain            store the session in a 0600 file instead of the OS keychain',
-        '  --tenant <id>            the tenant for this invocation (whoami, tenants claim/release)',
+        '  --tenant <id>            the tenant for this invocation (whoami, upgrade, tenants claim/release)',
         '  -h, --help               show this help and exit',
         '  -V, --version            print the version and exit',
         '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rakomi",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "The Rakomi CLI — sign in, connect an AI agent (Claude Code, Claude Desktop) to your tenant, and provision tenants. EU-native auth-as-a-service.",
   "keywords": [
     "rakomi",
@@ -42,6 +42,6 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/ test/ --max-warnings=0",
-    "test": "vitest run"
+    "test": "node ../../scripts/assert-not-story-agent-worktree.mjs test && node ../../scripts/ci/vitest-fork-crash-retry.mjs --results ./test-results.json -- vitest run"
   }
 }

package/sbom.cdx.json

@@ -26,10 +26,10 @@
     },
     "component": {
       "type": "library",
-      "bom-ref": "pkg:npm/rakomi@0.3.0",
+      "bom-ref": "pkg:npm/rakomi@0.3.1",
       "name": "rakomi",
-      "version": "0.3.0",
-      "purl": "pkg:npm/rakomi@0.3.0",
+      "version": "0.3.1",
+      "purl": "pkg:npm/rakomi@0.3.1",
       "licenses": [
         {
           "license": {