@vibecodr/cli 0.1.8

package/dist/storage/install-manifest.js

@@ -0,0 +1,80 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { CliError, EXIT_CODES } from "../cli/errors.js";
+import { writeFileWithBackup } from "./file-lock.js";
+function windowsAppDataPath() {
+    return process.env["APPDATA"] || join(homedir(), "AppData", "Roaming");
+}
+export function defaultInstallManifestPath() {
+    if (process.env["VIBECDR_MCP_INSTALL_MANIFEST_PATH"])
+        return process.env["VIBECDR_MCP_INSTALL_MANIFEST_PATH"];
+    switch (process.platform) {
+        case "win32":
+            return join(windowsAppDataPath(), "Vibecodr", "MCP", "installs.json");
+        case "darwin":
+            return join(homedir(), "Library", "Application Support", "Vibecodr MCP", "installs.json");
+        default:
+            return join(process.env["XDG_CONFIG_HOME"] || join(homedir(), ".config"), "vibecodr-mcp", "installs.json");
+    }
+}
+export class InstallManifestStore {
+    filePath;
+    constructor(filePath = defaultInstallManifestPath()) {
+        this.filePath = filePath;
+    }
+    async load() {
+        try {
+            const raw = await readFile(this.filePath, "utf8");
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch (error) {
+                throw new CliError("install.manifest_parse", `Install manifest at ${this.filePath} is not valid JSON.`, EXIT_CODES.installConflict, {
+                    cause: error,
+                    nextStep: "Repair or remove the invalid manifest file, then retry."
+                });
+            }
+            return {
+                version: 1,
+                installs: Array.isArray(parsed.installs) ? parsed.installs : []
+            };
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return {
+                    version: 1,
+                    installs: []
+                };
+            }
+            throw error;
+        }
+    }
+    async save(manifest) {
+        await writeFileWithBackup(this.filePath, JSON.stringify(manifest, null, 2) + "\n");
+    }
+    async upsert(entry) {
+        const manifest = await this.load();
+        const installs = manifest.installs.filter((install) => !(install.client === entry.client && install.scope === entry.scope && install.name === entry.name && install.location === entry.location));
+        installs.push(entry);
+        await this.save({
+            version: 1,
+            installs
+        });
+    }
+    async remove(matcher) {
+        const manifest = await this.load();
+        const removed = manifest.installs.filter(matcher);
+        const remaining = manifest.installs.filter((entry) => !matcher(entry));
+        await this.save({
+            version: 1,
+            installs: remaining
+        });
+        return removed;
+    }
+    async find(matcher) {
+        const manifest = await this.load();
+        return manifest.installs.filter(matcher);
+    }
+}

package/dist/storage/secret-store.js

@@ -0,0 +1,301 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { CliError, EXIT_CODES } from "../cli/errors.js";
+import { secretStoreDirectory } from "../platform/paths.js";
+import { writeFileWithBackup } from "./file-lock.js";
+const SERVICE_NAME = "@vibecodr/mcp";
+const KEY_BYTES = 32;
+const CURRENT_SECRET_FILE_VERSION = 1;
+const INSECURE_SECRET_STORE_PATH_ENV = "VIBECDR_MCP_INSECURE_SECRET_STORE_PATH";
+const ENABLE_INSECURE_SECRET_STORE_ENV = "VIBECDR_MCP_ENABLE_INSECURE_SECRET_STORE";
+let asyncEntryCtorPromise;
+export function secureStoreHelpForPlatform(platform = process.platform) {
+    switch (platform) {
+        case "darwin":
+            return "macOS uses Keychain. Unlock the login keychain, allow Terminal or Node access if macOS prompts, then retry.";
+        case "win32":
+            return "Windows uses Credential Manager. Run from a normal signed-in desktop session and confirm Windows Credential Manager is available, then retry.";
+        case "linux":
+            return "Linux uses the Secret Service API. Install libsecret support and make sure a desktop keyring such as GNOME Keyring or KWallet is running and unlocked on the current D-Bus session; on headless Linux, run login from a session with a secret service or let the target MCP client own OAuth instead.";
+        default:
+            return "Enable a native credential store supported by @napi-rs/keyring for this OS, then retry.";
+    }
+}
+function secureStoreNextStep() {
+    return `${secureStoreHelpForPlatform()} The plaintext file secret store is only for local automated tests and requires ${ENABLE_INSECURE_SECRET_STORE_ENV}=true.`;
+}
+async function loadAsyncEntryCtor() {
+    if (!asyncEntryCtorPromise) {
+        asyncEntryCtorPromise = import("@napi-rs/keyring")
+            .then((mod) => mod.AsyncEntry)
+            .catch((error) => {
+            throw new CliError("storage.secret_store_unavailable", "The native secure credential store binding is unavailable.", EXIT_CODES.secretStoreUnavailable, {
+                cause: error,
+                nextStep: secureStoreNextStep()
+            });
+        });
+    }
+    return await asyncEntryCtorPromise;
+}
+function profileAccount(profile) {
+    return `profile:${profile}`;
+}
+function profileKeyAccount(profile) {
+    return `profile-key:${profile}`;
+}
+function base64UrlEncode(buf) {
+    return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/g, "");
+}
+function base64UrlDecode(value) {
+    const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+    const padded = normalized + "=".repeat((4 - (normalized.length % 4)) % 4);
+    return Buffer.from(padded, "base64");
+}
+function sanitizeProfile(profile) {
+    return encodeURIComponent(profile);
+}
+function isSessionRecord(value) {
+    return Boolean(value)
+        && typeof value === "object"
+        && value["schemaVersion"] === 1
+        && typeof value["serverUrl"] === "string"
+        && typeof value["accessToken"] === "string";
+}
+function encryptSession(session, key) {
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", key, iv);
+    const plaintext = Buffer.from(JSON.stringify(session), "utf8");
+    const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    return {
+        version: CURRENT_SECRET_FILE_VERSION,
+        iv: base64UrlEncode(iv),
+        tag: base64UrlEncode(tag),
+        ciphertext: base64UrlEncode(ciphertext)
+    };
+}
+function decryptSession(envelope, key) {
+    if (envelope.version !== CURRENT_SECRET_FILE_VERSION) {
+        throw new Error(`Unsupported secret file version: ${envelope.version}`);
+    }
+    const decipher = createDecipheriv("aes-256-gcm", key, base64UrlDecode(envelope.iv));
+    decipher.setAuthTag(base64UrlDecode(envelope.tag));
+    const plaintext = Buffer.concat([
+        decipher.update(base64UrlDecode(envelope.ciphertext)),
+        decipher.final()
+    ]).toString("utf8");
+    return JSON.parse(plaintext);
+}
+async function readFileStore(path) {
+    try {
+        return JSON.parse(await readFile(path, "utf8"));
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return {};
+        throw error;
+    }
+}
+async function writeFileStore(path, data) {
+    await mkdir(dirname(path), { recursive: true });
+    const tempPath = `${path}.tmp`;
+    await writeFile(tempPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+    await rename(tempPath, path);
+}
+function resolveEnvFileStorePath() {
+    const path = process.env[INSECURE_SECRET_STORE_PATH_ENV]?.trim();
+    if (path === "undefined" || path === "null")
+        return undefined;
+    if (!path)
+        return undefined;
+    if (process.env[ENABLE_INSECURE_SECRET_STORE_ENV] !== "true") {
+        throw new CliError("storage.insecure_secret_store_blocked", "Refusing to use the plaintext secret store without explicit opt-in.", EXIT_CODES.secretStoreUnavailable, {
+            nextStep: `Unset ${INSECURE_SECRET_STORE_PATH_ENV}, or set ${ENABLE_INSECURE_SECRET_STORE_ENV}=true only for local tests.`
+        });
+    }
+    return path;
+}
+export class SecretStore {
+    fileStorePath;
+    encryptedStoreDir;
+    entryFactory;
+    constructor(options) {
+        this.fileStorePath = options?.fileStorePath ?? resolveEnvFileStorePath();
+        this.encryptedStoreDir = options?.encryptedStoreDir ?? secretStoreDirectory();
+        this.entryFactory = options?.entryFactory ?? (async (service, username) => {
+            const AsyncEntry = await loadAsyncEntryCtor();
+            return new AsyncEntry(service, username);
+        });
+    }
+    async entry(profile) {
+        return await this.entryFactory(SERVICE_NAME, profileAccount(profile));
+    }
+    async keyEntry(profile) {
+        return await this.entryFactory(SERVICE_NAME, profileKeyAccount(profile));
+    }
+    encryptedSessionPath(profile) {
+        return join(this.encryptedStoreDir, `${sanitizeProfile(profile)}.json`);
+    }
+    async loadLegacyInlineSession(profile) {
+        const entry = await this.entry(profile);
+        const raw = await entry.getPassword();
+        if (!raw)
+            return undefined;
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+        return isSessionRecord(parsed) ? parsed : undefined;
+    }
+    async getOrCreateProfileKey(profile) {
+        const entry = await this.keyEntry(profile);
+        const raw = await entry.getPassword();
+        if (raw)
+            return base64UrlDecode(raw);
+        const generated = randomBytes(KEY_BYTES);
+        await entry.setPassword(base64UrlEncode(generated));
+        return generated;
+    }
+    async readEncryptedSession(profile) {
+        const path = this.encryptedSessionPath(profile);
+        try {
+            const raw = await readFile(path, "utf8");
+            const parsed = JSON.parse(raw);
+            const keyEntry = await this.keyEntry(profile);
+            const encodedKey = await keyEntry.getPassword();
+            if (!encodedKey)
+                return undefined;
+            const session = decryptSession(parsed, base64UrlDecode(encodedKey));
+            return isSessionRecord(session) ? session : undefined;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return undefined;
+            throw error;
+        }
+    }
+    async persistEncryptedSession(profile, session) {
+        const path = this.encryptedSessionPath(profile);
+        await mkdir(dirname(path), { recursive: true });
+        const key = await this.getOrCreateProfileKey(profile);
+        const envelope = encryptSession(session, key);
+        await writeFileWithBackup(path, JSON.stringify(envelope, null, 2) + "\n");
+    }
+    async removeEncryptedSession(profile) {
+        const path = this.encryptedSessionPath(profile);
+        try {
+            await readFile(path, "utf8");
+            await rm(path, { force: true });
+            return true;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return false;
+            throw error;
+        }
+    }
+    async deleteCredentialBestEffort(loadEntry) {
+        try {
+            const entry = await loadEntry;
+            return await entry.deleteCredential();
+        }
+        catch {
+            return false;
+        }
+    }
+    async get(profile) {
+        if (this.fileStorePath) {
+            const data = await readFileStore(this.fileStorePath);
+            return data[profile];
+        }
+        try {
+            const encrypted = await this.readEncryptedSession(profile);
+            if (encrypted)
+                return encrypted;
+            const legacy = await this.loadLegacyInlineSession(profile);
+            if (legacy) {
+                await this.persistEncryptedSession(profile, legacy);
+                await (await this.entry(profile)).deleteCredential().catch(() => undefined);
+                return legacy;
+            }
+            return undefined;
+        }
+        catch (error) {
+            throw new CliError("storage.secret_store_read_failed", "Unable to read the secure credential store.", EXIT_CODES.secretStoreUnavailable, {
+                cause: error,
+                nextStep: secureStoreNextStep()
+            });
+        }
+    }
+    async set(profile, session) {
+        if (this.fileStorePath) {
+            const data = await readFileStore(this.fileStorePath);
+            data[profile] = session;
+            await writeFileStore(this.fileStorePath, data);
+            return;
+        }
+        try {
+            await this.persistEncryptedSession(profile, session);
+        }
+        catch (error) {
+            throw new CliError("storage.secret_store_write_failed", "Unable to write to the secure credential store.", EXIT_CODES.secretStoreUnavailable, {
+                cause: error,
+                nextStep: secureStoreNextStep()
+            });
+        }
+    }
+    async delete(profile) {
+        if (this.fileStorePath) {
+            const data = await readFileStore(this.fileStorePath);
+            const existed = Boolean(data[profile]);
+            delete data[profile];
+            await writeFileStore(this.fileStorePath, data);
+            return existed;
+        }
+        try {
+            const [encryptedRemoved, legacyRemoved, keyRemoved] = await Promise.all([
+                this.removeEncryptedSession(profile),
+                this.deleteCredentialBestEffort(this.entry(profile)),
+                this.deleteCredentialBestEffort(this.keyEntry(profile))
+            ]);
+            return encryptedRemoved || legacyRemoved || keyRemoved;
+        }
+        catch (error) {
+            throw new CliError("storage.secret_store_delete_failed", "Unable to update the secure credential store.", EXIT_CODES.secretStoreUnavailable, {
+                cause: error,
+                nextStep: secureStoreNextStep()
+            });
+        }
+    }
+    async checkAvailability() {
+        if (this.fileStorePath) {
+            const data = await readFileStore(this.fileStorePath);
+            await writeFileStore(this.fileStorePath, data);
+            return { ok: true, summary: "Contributor-only file secret store is enabled." };
+        }
+        const profile = `doctor:${randomUUID()}`;
+        try {
+            await this.set(profile, {
+                schemaVersion: 1,
+                serverUrl: "https://example.com/mcp",
+                accessToken: "test",
+                registrationMode: "manual",
+                authorizationServerUrl: "https://example.com",
+                clientInformation: { client_id: "test" },
+                updatedAt: new Date().toISOString()
+            });
+            await this.delete(profile);
+            return { ok: true, summary: "Secure credential store is available." };
+        }
+        catch (error) {
+            if (error instanceof CliError) {
+                return { ok: false, summary: error.nextStep ? `${error.message} ${error.nextStep}` : error.message };
+            }
+            return { ok: false, summary: String(error) };
+        }
+    }
+}

package/dist/types/auth.js

@@ -0,0 +1 @@
+export {};

package/dist/types/config.js

@@ -0,0 +1,21 @@
+export const CONFIG_VERSION = 1;
+export const DEFAULT_PROFILE = "default";
+export const DEFAULT_SERVER_URL = "https://openai.vibecodr.space/mcp";
+export function defaultProfileConfig() {
+    return {
+        serverUrl: DEFAULT_SERVER_URL,
+        browserMode: "print",
+        registrationMode: "auto",
+        defaultInstallScope: "user",
+        logLevel: "normal"
+    };
+}
+export function defaultConfigFile() {
+    return {
+        version: CONFIG_VERSION,
+        currentProfile: DEFAULT_PROFILE,
+        profiles: {
+            [DEFAULT_PROFILE]: defaultProfileConfig()
+        }
+    };
+}

package/dist/types/install.js

@@ -0,0 +1 @@
+export {};

package/docs/architecture.md

@@ -0,0 +1,35 @@
+# Architecture
+
+The Vibecodr CLI is a client of the hosted Vibecodr MCP gateway.
+
+## Boundary
+
+- hosted MCP gateway/server repo: `Vibecodr-MCP`
+- CLI client repo: `Vibecodr-MCP-CLI`
+- CLI package: `@vibecodr/cli`
+- primary executable: `vibecodr`
+- compatibility executable: `vibecodr-mcp`
+- legacy package compatibility: `@vibecodr/mcp`
+- default MCP URL: `https://openai.vibecodr.space/mcp`
+
+This repo does not run the hosted server. It installs client config, performs CLI-owned OAuth, discovers the live tool catalog, and calls tools over Streamable HTTP MCP.
+
+## Auth Ownership
+
+`vibecodr login` stores OAuth tokens for the CLI profile only.
+
+Codex, Cursor, VS Code, Windsurf, ChatGPT, and other MCP clients own separate OAuth sessions. Installing MCP config into those clients points them at the same server, but it does not copy CLI tokens into them.
+
+## Why The Repos Are Separate
+
+The CLI is permissively licensed and safe to distribute as a public client package. The hosted gateway implementation is source-available under a different license because it contains server-side orchestration, OAuth gateway behavior, Cloudflare deployment wiring, and Vibecodr API integration code.
+
+The package name is `@vibecodr/cli` because this repo distributes the user-facing command-line client. The older `@vibecodr/mcp` package name is kept only as a compatibility/deprecation surface; the bare `vibecodr` executable remains the canonical user command.
+
+Local config directories and secure-token service names intentionally keep their historical `vibecodr-mcp` / `@vibecodr/mcp` identifiers during this migration. Those names are storage compatibility keys, not the public npm package identity.
+
+Keeping the repos separate makes the contract clear:
+
+- users can use the hosted service normally
+- users can install and inspect the CLI freely under this repo license
+- commercial reuse of the gateway implementation remains governed by the server repo license

package/docs/auth.md

@@ -0,0 +1,66 @@
+# Auth
+
+`vibecodr login` authenticates the CLI itself to the hosted Vibecodr MCP server. It does not log Codex, Cursor, VS Code, Windsurf, ChatGPT, or any other MCP client into MCP.
+
+Vibecodr has one hosted MCP gateway. The CLI is one client of that gateway, with its own local OAuth token store.
+
+Compatibility alias:
+
+- `vibecodr-mcp login`
+
+## Implemented now
+
+- protected-resource and authorization-server discovery against the MCP server
+- PKCE S256 enforcement
+- loopback callback on `127.0.0.1`
+- secure token storage in the OS credential store via `@napi-rs/keyring`
+- proactive refresh before protected runtime commands when a refresh token is available
+- `logout` local token deletion plus best-effort revocation
+
+The plaintext file secret store is for local automated tests only. It is ignored unless both `VIBECDR_MCP_INSECURE_SECRET_STORE_PATH` and `VIBECDR_MCP_ENABLE_INSECURE_SECRET_STORE=true` are set.
+
+The local config and secure-token storage keys intentionally keep their historical `vibecodr-mcp` / `@vibecodr/mcp` names during the `@vibecodr/cli` package rename. That preserves existing CLI sessions instead of forcing users to re-authenticate for a package-name migration.
+
+Supported OS credential stores:
+
+- macOS: Keychain
+- Windows: Credential Manager
+- Linux: Secret Service through a desktop keyring such as GNOME Keyring or KWallet
+
+Linux systems need a running, unlocked keyring on the current D-Bus session. Headless Linux should use a real Secret Service setup for persistent CLI login, or let the target MCP client own its own OAuth flow instead of storing CLI tokens.
+
+## Registration modes
+
+The CLI understands these internal modes:
+
+- `auto`
+- `preregistered`
+- `cimd`
+- `dcr`
+- `manual`
+
+Current repo reality:
+
+- `auto` now uses the committed official client metadata document URL for `https://openai.vibecodr.space/mcp`
+- `cimd` for non-official servers still requires a real `VIBECDR_MCP_CIMD_CLIENT_ID` URL
+- `dcr` works when the authorization server advertises `registration_endpoint`
+- `manual` works with `VIBECDR_MCP_MANUAL_CLIENT_ID` or an interactive prompt
+
+## Runtime behavior
+
+- `login` prints the authorization URL by default so the browser step is explicit and reliable across shells
+- `login --browser open` opts into automatic browser launch
+- `status` reads local session state without requiring the network unless `--probe` is used
+- `tools` and `call` will attempt to reuse the stored session
+- if the access token is close to expiry and a refresh token is present, the CLI refreshes before making the MCP request
+
+## Verified now
+
+- automated mock coverage exercises DCR login, loopback callback handling, refresh, and logout revocation behavior
+- unauthenticated `tools` works against public server surfaces without forcing login first
+- unauthenticated public `call` works for noauth tools, while protected flows retry with refresh or interactive login
+
+## Remaining constraints
+
+- CIMD for non-official servers still needs a real externally hosted client-id metadata document to be genuinely usable
+- dedicated scope step-up UX is still folded into the normal re-auth path rather than a specialized prompt flow

package/docs/clients.md

@@ -0,0 +1,42 @@
+# Clients
+
+This matrix reflects current repo reality, not the full target spec.
+
+| Client | Install status now | Uninstall status now | Scope support now | Auth owner |
+| --- | --- | --- | --- | --- |
+| Codex | Implemented | Implemented via CLI or TOML fallback | User | Codex |
+| Cursor | Implemented | Implemented | User + project | Cursor |
+| VS Code | Implemented | Project uninstall implemented, user uninstall not automated | User + project | VS Code |
+| Windsurf | Implemented | Implemented | User | Windsurf |
+| Direct CLI | Implemented | N/A | N/A | Vibecodr MCP CLI |
+
+## Exact surfaces used now
+
+### Codex
+
+- primary install: `codex mcp add`
+- primary uninstall: `codex mcp remove`
+- fallback file: `~/.codex/config.toml`
+
+### Cursor
+
+- user file: `~/.cursor/mcp.json`
+- project file: `.cursor/mcp.json`
+- optional open-client deeplink
+
+### VS Code
+
+- user install: `code --add-mcp`
+- user fallback when `--open-client` is present: `vscode:mcp/install?...`
+- project file: `.vscode/mcp.json`
+
+### Windsurf
+
+- native file: `~/.codeium/windsurf/mcp_config.json`
+- docs note for legacy plugin path: `~/.codeium/mcp_config.json`
+
+## Current caveats
+
+- installer adapters exist, but the direct CLI runtime remains the primary proofed surface
+- VS Code user-scope uninstall still lacks a documented automated removal path in this repo
+- enterprise allowlists, team policy blocks, and client-side OAuth behavior still need live validation in real environments

package/docs/commands.md

@@ -0,0 +1,134 @@
+# Commands
+
+This page documents the command surface implemented in the current repo.
+
+## Global flags
+
+All commands accept:
+
+- `--profile <name>`
+- `--server-url <url>`
+- `--json`
+- `--verbose`
+- `--non-interactive`
+
+## Commands
+
+### `login`
+
+Syntax:
+
+`vibecodr login [--scope <oauth-scope>] [--registration auto|preregistered|cimd|dcr|manual] [--browser open|print] [--timeout-sec <n>]`
+
+Use this to authenticate the CLI itself.
+
+Current default:
+
+- `login` prints the authorization URL and waits for the loopback callback
+- `--browser open` opts into automatic browser launch
+
+### `logout`
+
+Syntax:
+
+`vibecodr logout [--all] [--no-revoke]`
+
+Use this to clear CLI auth state. It does not touch editor-owned auth.
+
+### `status`
+
+Syntax:
+
+`vibecodr status [--probe] [--show-installs]`
+
+Without `--probe`, this reads only local state.
+
+### `tools`
+
+Syntax:
+
+`vibecodr tools [<tool-name>] [--search <text>] [--schema] [--no-login]`
+
+This always reads the live tool catalog from the MCP server.
+
+### `call`
+
+Syntax:
+
+`vibecodr call <tool-name> [--input-json <json>] [--input-file <path>] [--stdin] [--interactive] [--no-login]`
+
+`--interactive` currently supports top-level scalar object fields.
+
+For `quick_publish_creation` with `payload.importMode: "direct_files"`, pass file paths as normal slash-separated project paths such as `src/main.tsx` or `src/server/binding-proof.js`. Do not pre-encode slashes as `%2F`; the hosted MCP gateway encodes each URL segment when it writes files to Vibecodr.
+
+### `pulse-setup`
+
+Syntax:
+
+`vibecodr pulse-setup [--json] [--descriptor-setup-json <json> | --descriptor-setup-file <path>]`
+
+Calls the live `get_pulse_setup_guidance` MCP tool. Pass a `PulseDescriptorSetupProjection` through `--descriptor-setup-json` or `--descriptor-setup-file` when you have one; the CLI forwards it as `descriptorSetup` and verifies the MCP response evaluated that descriptor. Without a descriptor projection, the command returns general Pulse setup rules and must not be treated as proof that a specific Pulse needs or does not need backend setup.
+
+The CLI does not maintain separate Pulse setup copy; it reads MCP output derived from the API projection owned by `PulseDescriptor`.
+
+The returned guidance should stay capability-shaped: `env.fetch` is Vibecodr policy-mediated fetch, `env.secrets.bearer/header/query/verifyHmac` are policy-bound secret helpers, `env.webhooks.verify("stripe")` is the first certified provider helper rather than the whole webhook model, non-Stripe signed webhooks use generic HMAC format presets such as `github-sha256`, `shopify-hmac-sha256`, and `slack-v0` until fixture-backed helpers exist, `env.connections.use(provider).fetch` is provider-scoped connected-account access, `env.log` is structured logging, `env.request` is sanitized request access, `env.runtime` is safe correlation metadata, and `env.waitUntil` is best-effort after-response work. The CLI must not introduce separate cleanup, platform-binding, dispatch, raw-token, raw-authorization, or physical-storage guidance.
+
+### `doctor`
+
+Syntax:
+
+`vibecodr doctor [--client <client>]`
+
+Supported client probes now:
+
+- `codex`
+- `cursor`
+- `vscode`
+- `windsurf`
+
+### `config`
+
+Syntax:
+
+- `vibecodr config path`
+- `vibecodr config show`
+- `vibecodr config set <key> <value>`
+- `vibecodr config unset <key>`
+- `vibecodr config profile list`
+- `vibecodr config profile create <name> [--server-url <url>]`
+- `vibecodr config profile use <name>`
+- `vibecodr config profile delete <name> [--force]`
+
+### `install`
+
+Syntax:
+
+`vibecodr install <codex|cursor|vscode|windsurf> [--scope user|project] [--path <dir>] [--name <server-name>] [--open-client] [--overwrite] [--dry-run]`
+
+Install config only. Runtime auth remains CLI-owned or editor-owned depending on where the server is used.
+
+### `uninstall`
+
+Syntax:
+
+`vibecodr uninstall <codex|cursor|vscode|windsurf> [--scope user|project] [--path <dir>] [--name <server-name>] [--dry-run]`
+
+## Exit codes
+
+- `0` success
+- `1` runtime or doctor check failure
+- `2` usage error
+- `3` config or filesystem error
+- `4` auth required but unavailable in current mode
+- `5` auth failed
+- `6` network failure
+- `7` protocol or discovery failure
+- `8` tool failure
+- `9` unsupported client or missing required executable
+- `10` install or uninstall conflict
+- `11` secure credential store unavailable
+- `12` cancellation or auth timeout
+
+## Current note
+
+The commands above are implemented now. The main remaining product constraint is VS Code user-scope uninstall, because there is still no documented removal surface that this repo can safely automate without inventing one.