flipstream 0.4.0 → 0.6.0

package/README.md

@@ -6,25 +6,20 @@ authenticates once and prints clean **structured JSON** for AI coding agents.
 > **Architecture:** this supersedes `flipstream-cli-kickoff.md`. See [`CLAUDE.md`](./CLAUDE.md)
 > for the corrected model (thin client, two hosts, **no natural-language "ask"**).
 
-## Prerequisites
-
-- [Bun](https://bun.sh) (development toolchain)
-- Node.js **20+** (the published CLI runs under Node)
-
-## Install (development)
+## Install
 
 ```sh
-bun install
-bun run build
+npm i -g flipstream   # requires Node.js 20+
 ```
 
 ## Usage
 
 ```sh
-./bin/run.js --help          # or during dev: bun bin/dev.js --help
-./bin/run.js --version
-./bin/run.js version --json  # {version,node,platform,contractVersion}
-./bin/run.js auth login      # opens the browser to sign in (OAuth2 + PKCE)
+flipstream --help
+flipstream --version
+flipstream version --json  # {version,node,platform,contractVersion}
+flipstream auth login      # opens the browser to sign in (OAuth2 + PKCE)
+flipstream ws list         # list your organization's workspaces
 ```
 
 ## For agents (Claude Code / Codex / MCP)
@@ -46,19 +41,30 @@ taxonomy, per-command shapes, `CONTRACT_VERSION`) lives in
 [`docs/AGENT-CONTRACT.md`](./docs/AGENT-CONTRACT.md) and is enforced by a
 conformance suite.
 
-## Scripts
+## Development
+
+Built with [Bun](https://bun.sh); the published CLI runs under **Node.js 20+**.
+
+```sh
+bun install
+bun run build
+./bin/run.js --help        # run from source (or during dev: bun bin/dev.js --help)
+```
+
+Scripts:
 
 - `bun run build` — compile TypeScript to `dist/`
 - `bun run lint` — eslint (flat config)
 - `bun run check:secrets` — static deny-list gate over `src/lib/auth` (CI-enforced)
 - `bun run format` — prettier
 - `bun test` — run the test suite
+- `bun run smoke` — pack the tarball + run the packaged binary (E5-4)
 - `bun run dev` — run the CLI from source (`./bin/dev.js`)
 
 ## Security
 
-The CLI is a **public OAuth2 client** (Authorization Code + PKCE + Dynamic Client
-Registration) — it holds **no client secret**.
+The CLI is a **public OAuth2 client** (Authorization Code + PKCE, a fixed
+first-party `client_id`) — it holds **no client secret**.
 
 - **Tokens live only in the OS keychain** (`@napi-rs/keyring`, service id
   `io.flipstream.cli`); nothing is written to disk in plaintext, and the
@@ -101,10 +107,18 @@ If you already removed the binary, clean up manually:
 * [`flipstream auth login`](#flipstream-auth-login)
 * [`flipstream auth logout`](#flipstream-auth-logout)
 * [`flipstream auth status`](#flipstream-auth-status)
+* [`flipstream catalog [SOURCE]`](#flipstream-catalog-source)
 * [`flipstream commands`](#flipstream-commands)
 * [`flipstream conn list`](#flipstream-conn-list)
 * [`flipstream connections list`](#flipstream-connections-list)
+* [`flipstream contract`](#flipstream-contract)
+* [`flipstream health`](#flipstream-health)
+* [`flipstream log add MESSAGE`](#flipstream-log-add-message)
+* [`flipstream log list`](#flipstream-log-list)
+* [`flipstream logs add MESSAGE`](#flipstream-logs-add-message)
+* [`flipstream logs list`](#flipstream-logs-list)
 * [`flipstream query`](#flipstream-query)
+* [`flipstream skills install`](#flipstream-skills-install)
 * [`flipstream version`](#flipstream-version)
 * [`flipstream workspaces connections ID`](#flipstream-workspaces-connections-id)
 * [`flipstream workspaces get ID`](#flipstream-workspaces-get-id)
@@ -230,6 +244,45 @@ EXAMPLES
   $ flipstream auth status --json
 ```
 
+## `flipstream catalog [SOURCE]`
+
+Show the dimensions and metrics a source accepts.
+
+```
+USAGE
+  $ flipstream catalog [SOURCE] [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--auth-host
+    <value>] [--url <value>]
+
+ARGUMENTS
+  [SOURCE]  A source name (omit to list every source).
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --auth-host=<value>  OAuth issuer host for credentials/refresh (defaults to the prod issuer).
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>    Network timeout in milliseconds.
+      --url=<value>        Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose            Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Show the dimensions and metrics a source accepts.
+
+  Print the request vocabulary the query planner accepts. The names shown ARE what `query` takes: `-d` and `-m` and
+  filter keys use an item's `name` (the wire name, e.g. search_date), never its `label` (what a human reads, e.g. Date).
+  Read from the SERVICE, never from a local data-model checkout — the two differ exactly when it matters most, right
+  after a version bump.
+
+EXAMPLES
+  $ flipstream catalog
+
+  $ flipstream catalog gsc
+
+  $ flipstream catalog gsc --json
+```
+
 ## `flipstream commands`
 
 List all flipstream commands.
@@ -341,20 +394,297 @@ EXAMPLES
   $ flipstream conn list --all
 ```
 
+## `flipstream contract`
+
+Print the agent contract (machine-facing promises) to stdout.
+
+```
+USAGE
+  $ flipstream contract [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+
+FLAGS
+  -H, --host=<value>     OAuth provider host (defaults to the prod issuer).
+      --ndjson           Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>  Network timeout in milliseconds.
+      --verbose          Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Print the agent contract (machine-facing promises) to stdout.
+
+  Print docs/AGENT-CONTRACT.md — the frozen machine contract (output modes, exit codes, error envelope, per-command JSON
+  shapes) — to stdout, from the installed package, no network needed. Context self-service for agents: read this before
+  driving the CLI programmatically.
+
+EXAMPLES
+  $ flipstream contract
+
+  $ flipstream contract --json
+```
+
+## `flipstream health`
+
+Check that the query planner is reachable.
+
+```
+USAGE
+  $ flipstream health [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--url <value>]
+
+FLAGS
+  -H, --host=<value>     OAuth provider host (defaults to the prod issuer).
+      --ndjson           Stream output as NDJSON (one compact JSON object per line).
+      --timeout=<value>  Network timeout in milliseconds.
+      --url=<value>      Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose          Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Check that the query planner is reachable.
+
+  Check that the query planner is answering. This is the ONE endpoint that takes no token, so it separates "the service
+  is down" from "my credentials are wrong" before any auth debugging starts.
+
+EXAMPLES
+  $ flipstream health
+
+  $ flipstream health --json
+
+  $ flipstream health --url http://localhost:8080
+```
+
+## `flipstream log add MESSAGE`
+
+Add an entry to a workspace's log.
+
+```
+USAGE
+  $ flipstream log add MESSAGE --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>]
+    [--verbose] [--end <value>] [--start <value>]
+
+ARGUMENTS
+  MESSAGE  The log entry text.
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --end=<value>        End date (ISO 8601). Defaults to now.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --start=<value>      Start date (ISO 8601). Defaults to now.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) Workspace id (UUID) the entry belongs to.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Add an entry to a workspace's log.
+
+  Add an entry to a workspace's log (the logbook). You give the workspace (--workspace/--ws) and the message; the
+  organization is derived from the workspace, and the dates default to now (override with --start/--end). Returns the
+  created entry. Targets the OAuth/admin host.
+
+ALIASES
+  $ flipstream logs add
+
+EXAMPLES
+  $ flipstream log add "shipped the new pipeline" --workspace <id>
+
+  $ flipstream log add "kickoff call done" --ws <id> --json
+```
+
+## `flipstream log list`
+
+Read a workspace's log entries.
+
+```
+USAGE
+  $ flipstream log list --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+    [--all] [--limit <value>] [--offset <value>] [--q <value>] [--sort <value>]
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --all                Fetch every page (drains pagination).
+      --limit=<value>      [default: 50] Page size.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>     Starting offset.
+      --q=<value>          Free-text filter.
+      --sort=<value>       Sort field.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) The workspace whose log to read (UUID).
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Read a workspace's log entries.
+
+  Read a workspace's log entries (the logbook). --workspace is required — a log entry only makes sense in a workspace's
+  context, so there is no account-wide read. Shows each entry's description, dates, and author; the full record
+  (including any new fields like tags) is under --json. Targets the OAuth/admin host.
+
+ALIASES
+  $ flipstream logs list
+
+EXAMPLES
+  $ flipstream log list --workspace <id>
+
+  $ flipstream logs list --ws <id> --json
+
+  $ flipstream log list --ws <id> --all
+```
+
+## `flipstream logs add MESSAGE`
+
+Add an entry to a workspace's log.
+
+```
+USAGE
+  $ flipstream logs add MESSAGE --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>]
+    [--verbose] [--end <value>] [--start <value>]
+
+ARGUMENTS
+  MESSAGE  The log entry text.
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --end=<value>        End date (ISO 8601). Defaults to now.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --start=<value>      Start date (ISO 8601). Defaults to now.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) Workspace id (UUID) the entry belongs to.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Add an entry to a workspace's log.
+
+  Add an entry to a workspace's log (the logbook). You give the workspace (--workspace/--ws) and the message; the
+  organization is derived from the workspace, and the dates default to now (override with --start/--end). Returns the
+  created entry. Targets the OAuth/admin host.
+
+ALIASES
+  $ flipstream logs add
+
+EXAMPLES
+  $ flipstream log add "shipped the new pipeline" --workspace <id>
+
+  $ flipstream log add "kickoff call done" --ws <id> --json
+```
+
+## `flipstream logs list`
+
+Read a workspace's log entries.
+
+```
+USAGE
+  $ flipstream logs list --workspace <value> [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose]
+    [--all] [--limit <value>] [--offset <value>] [--q <value>] [--sort <value>]
+
+FLAGS
+  -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
+      --all                Fetch every page (drains pagination).
+      --limit=<value>      [default: 50] Page size.
+      --ndjson             Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>     Starting offset.
+      --q=<value>          Free-text filter.
+      --sort=<value>       Sort field.
+      --timeout=<value>    Network timeout in milliseconds.
+      --verbose            Print redacted diagnostics to stderr.
+      --workspace=<value>  (required) The workspace whose log to read (UUID).
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Read a workspace's log entries.
+
+  Read a workspace's log entries (the logbook). --workspace is required — a log entry only makes sense in a workspace's
+  context, so there is no account-wide read. Shows each entry's description, dates, and author; the full record
+  (including any new fields like tags) is under --json. Targets the OAuth/admin host.
+
+ALIASES
+  $ flipstream logs list
+
+EXAMPLES
+  $ flipstream log list --workspace <id>
+
+  $ flipstream logs list --ws <id> --json
+
+  $ flipstream log list --ws <id> --all
+```
+
 ## `flipstream query`
 
-Run an opaque query against the Flipstream data API.
+Run a logical query against the Flipstream query planner.
 
 ```
 USAGE
   $ flipstream query [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--auth-host <value>]
-    [--body <value> | --body-file <value>]
+    [--url <value>] [--body <value> | --body-file <value>] [--connection-id <value>] [-d <value>...] [--dry-run] [-f
+    <value>...] [-m <value>...] [--offset <value>] [--rows <value>] [-s <value>...] [--source <value>] [--table <value>]
+
+FLAGS
+  -H, --host=<value>           OAuth provider host (defaults to the prod issuer).
+  -d, --dimension=<value>...   Dimension name (repeatable).
+  -f, --filter=<value>...      Filter as col=a,b | col=from..to | col=<json> (repeatable). 'col=' is refused.
+  -m, --metric=<value>...      Metric name (repeatable).
+  -s, --sort=<value>...        FIELD[:asc|desc] (repeatable).
+      --auth-host=<value>      OAuth issuer host for credentials/refresh (defaults to the prod issuer).
+      --body=<value>           Send this JSON body verbatim.
+      --body-file=<value>      Path to a file holding the JSON body verbatim ("-" reads stdin).
+      --connection-id=<value>  Connection UUID, or a name to look up.
+      --dry-run                Print the request body and send nothing.
+      --ndjson                 Stream output as NDJSON (one compact JSON object per line).
+      --offset=<value>         Row offset.
+      --rows=<value>           Row limit (default 100).
+      --source=<value>         The dataset discriminator, e.g. gsc.
+      --table=<value>          Physical table — honoured only for an unmodelled source.
+      --timeout=<value>        Network timeout in milliseconds.
+      --url=<value>            Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).
+      --verbose                Print redacted diagnostics to stderr.
+
+GLOBAL FLAGS
+  --json  Format output as json.
+
+DESCRIPTION
+  Run a logical query against the Flipstream query planner.
+
+  Send a LOGICAL query (source + dimensions + metrics + filters) to the Flipstream query planner, which resolves which
+  physical table answers it and returns the rows. Run `flipstream catalog <source>` first — the names it prints ARE what
+  -d, -m and filter keys take. --body/--body-file/stdin still forwards a JSON body verbatim for shapes the flags cannot
+  express.
+
+EXAMPLES
+  $ flipstream catalog gsc
+
+  $ flipstream query --source gsc --connection-id <id|name> -d search_date -d query -m clicks -f 'search_date=2026-01-01..2026-02-01' --rows 20
+
+  $ flipstream query --source gsc --connection-id <id> -d query -m clicks --dry-run
+
+  $ flipstream query --body-file request.json --json
+```
+
+## `flipstream skills install`
+
+Install the flipstream skill for detected AI coding agents.
+
+```
+USAGE
+  $ flipstream skills install [--json] [-H <value>] [--ndjson] [--timeout <value>] [--verbose] [--agent
+    claude-code|codex|cursor|opencode...] [-y]
 
 FLAGS
   -H, --host=<value>       OAuth provider host (defaults to the prod issuer).
-      --auth-host=<value>  OAuth issuer host for credentials/refresh (defaults to the prod issuer).
-      --body=<value>       Opaque JSON request body as a string.
-      --body-file=<value>  Path to a file holding the opaque JSON request body.
+  -y, --yes                Install without asking.
+      --agent=<option>...  Install for this agent id only (repeatable). Known: claude-code, codex, cursor, opencode.
+                           <options: claude-code|codex|cursor|opencode>
       --ndjson             Stream output as NDJSON (one compact JSON object per line).
       --timeout=<value>    Network timeout in milliseconds.
       --verbose            Print redacted diagnostics to stderr.
@@ -363,18 +693,18 @@ GLOBAL FLAGS
   --json  Format output as json.
 
 DESCRIPTION
-  Run an opaque query against the Flipstream data API.
+  Install the flipstream skill for detected AI coding agents.
 
-  Send an OPAQUE JSON body (--body, --body-file, or piped stdin) to the Flipstream data API and print the structured
-  JSON response. The CLI never constructs, validates, or transforms the query payload — the body is forwarded verbatim
-  (your agent/Skill builds it).
+  Install the flipstream skill (SKILL.md) into the global skills directory of every detected AI coding agent (Claude
+  Code, Codex, Cursor, OpenCode). Detection is local env/dir inspection only — nothing is reported anywhere. The skill
+  teaches an agent to retrieve the command surface and data vocabulary from the CLI instead of guessing.
 
 EXAMPLES
-  $ flipstream query --body '{"opaque":true}'
+  $ flipstream skills install
 
-  echo '{"opaque":true}' | flipstream query
+  $ flipstream skills install --yes
 
-  $ flipstream query --body-file query.json --json
+  $ flipstream skills install --agent claude-code --agent codex
 ```
 
 ## `flipstream version`

package/dist/commands/auth/login.js

@@ -44,6 +44,12 @@ export default class AuthLogin extends BaseCommand {
         }
         // Emit only the (redacted) decoded claims — never the raw token.
         const claims = redact(result.claims);
-        return this.respond(claims, (data) => this.log(JSON.stringify(data)));
+        return this.respond(claims, (data) => {
+            this.log(JSON.stringify(data));
+            // Close the loop (E11-3, #102): a fresh login has exactly two sensible
+            // next moves — prove the pipe works, then learn the vocabulary.
+            this.footer(`\nNext: ${this.config.bin} health   (checks the query planner is reachable)\n` +
+                `      ${this.config.bin} catalog  (lists the sources you can query)`);
+        });
     }
 }

package/dist/commands/auth/status.js

@@ -1,8 +1,15 @@
 import { tokenClaims } from '../../lib/auth/claims.js';
 import { BaseCommand } from '../../lib/command/base.js';
 import { ExitCode } from '../../lib/exit-codes.js';
-import { redact } from '../../lib/output/redact.js';
+import { isCI } from '../../lib/output/interactivity.js';
+import { maskAccount, redact } from '../../lib/output/redact.js';
 import { createStore } from '../../lib/store/index.js';
+// 'expires in 25m' below an hour, 'expires in 2h' above — never a rounded-to-0h.
+function formatRemaining(seconds) {
+    if (seconds < 3600)
+        return `${Math.max(1, Math.round(seconds / 60))}m`;
+    return `${Math.round(seconds / 3600)}h`;
+}
 export default class AuthStatus extends BaseCommand {
     static description = 'Show the current Flipstream authentication status for a host.';
     static examples = ['<%= config.bin %> auth status', '<%= config.bin %> auth status --json'];
@@ -37,11 +44,30 @@ export default class AuthStatus extends BaseCommand {
             scopes: creds.scopes,
         });
         return this.respond(status, () => {
-            const relative = expired ? 'expired' : `expires in ${Math.round((creds.expiresAt - nowSeconds) / 3600)}h`;
+            // ONE formatter for both the stdout line and the stderr note — a status
+            // command must not contradict itself about its own subject (E11-2 review).
+            const remaining = formatRemaining(creds.expiresAt - nowSeconds);
+            const relative = expired ? 'expired' : `expires in ${remaining}`;
+            // Disclosure tier (E11-4): mask the account in CI human output. This is
+            // HYGIENE for the human line, not a privacy control — the --json path
+            // (the one agents/CI actually consume) keeps the stable value by
+            // contract, so a public build log is not made safe by this alone.
+            const shown = typeof displayAccount === 'string' ? displayAccount : 'unknown';
             this.log(`Logged in to ${host}`);
-            this.log(`  account: ${typeof displayAccount === 'string' ? displayAccount : 'unknown'}`);
+            this.log(`  account: ${isCI() ? maskAccount(shown) : shown}`);
             this.log(`  expires: ${expiresAtIso} (${relative})`);
             this.log(`  scopes:  ${creds.scopes.join(' ')}`);
+            // Expiry narration (E11-2, #101): state the consequence, not just the fact.
+            // An expired ACCESS token is normal — commands refresh it on use — so the
+            // warning names the failure mode that actually needs the human (refresh
+            // rejected → session_expired) rather than crying wolf.
+            if (expired) {
+                this.note('the access token has expired; commands refresh it automatically — if one fails with ' +
+                    'session_expired, run `flipstream auth login`');
+            }
+            else if (creds.expiresAt - nowSeconds < 24 * 3600) {
+                this.note(`the access token expires in ${remaining} and will refresh automatically on use`);
+            }
         });
     }
 }

package/dist/commands/catalog.d.ts

@@ -0,0 +1,15 @@
+import { BaseCommand } from '../lib/command/base.js';
+export default class Catalog extends BaseCommand<typeof Catalog> {
+    static args: {
+        source: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static summary: string;
+    run(): Promise<unknown>;
+    private renderSource;
+}

package/dist/commands/catalog.js

@@ -0,0 +1,110 @@
+import { Args } from '@oclif/core';
+import { BaseCommand } from '../lib/command/base.js';
+import { plannerFlags } from '../lib/command/flags.js';
+import { authedPlannerClient } from '../lib/command/planner.js';
+import { resolveHost, resolvePlannerUrl } from '../lib/config/xdg.js';
+import { AuthRequiredError } from '../lib/errors.js';
+import { redact } from '../lib/output/redact.js';
+import { sanitizeTerminal } from '../lib/output/sanitize.js';
+import { renderTable } from '../lib/output/table.js';
+import { parseCatalogIndex, parseCatalogSource } from '../lib/planner/catalog.js';
+import { mapCatalogError } from '../lib/planner/errors.js';
+import { createStore } from '../lib/store/index.js';
+export default class Catalog extends BaseCommand {
+    static args = {
+        source: Args.string({
+            description: 'A source name (omit to list every source).',
+            // oclif fills a MISSING positional from stdin when stdin is not a TTY, so
+            // `echo x | flipstream catalog` would silently become `catalog x` — and a
+            // spawned process (the normal case for an agent) has a non-TTY stdin it may
+            // never close, which makes that read hang forever. Nothing here wants stdin.
+            ignoreStdin: true,
+            required: false,
+        }),
+    };
+    static description = 'Print the request vocabulary the query planner accepts. The names shown ARE what `query` takes: `-d` and ' +
+        "`-m` and filter keys use an item's `name` (the wire name, e.g. search_date), never its `label` (what a human " +
+        'reads, e.g. Date). Read from the SERVICE, never from a local data-model checkout — the two differ exactly ' +
+        'when it matters most, right after a version bump.';
+    static examples = [
+        '<%= config.bin %> catalog',
+        '<%= config.bin %> catalog gsc',
+        '<%= config.bin %> catalog gsc --json',
+    ];
+    static flags = { ...plannerFlags };
+    static summary = 'Show the dimensions and metrics a source accepts.';
+    async run() {
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] ?? this.flags.host });
+        const store = createStore();
+        if (!store.load(authHost))
+            throw AuthRequiredError.notLoggedIn();
+        const client = authedPlannerClient({ authHost, store, timeoutMs: this.flags.timeout, url });
+        const { source } = this.args;
+        let raw;
+        const started = Date.now();
+        try {
+            raw = await client.getCatalog(source, { timeoutMs: this.flags.timeout });
+        }
+        catch (error) {
+            throw mapCatalogError(error, { bin: this.config.bin, source, url });
+        }
+        // Which host answered (E11-2): the planner and the admin API are different
+        // origins, and "which one did I just talk to" is the first debugging question.
+        this.verboseLog(`GET ${url}/catalog${source === undefined ? '' : `/${source}`} (${Date.now() - started} ms)`);
+        // Redact BEFORE the document becomes output, exactly as `query` does. The
+        // served catalog is an allowlist projection built by data-model, so nothing
+        // secret should be in it — but "should" is the service's promise, and this is
+        // our own output boundary. A projection here would instead drop fields the
+        // service legitimately adds, so redaction (which masks secret-NAMED keys and
+        // leaves the rest untouched) is the right tool: it keeps `--json` faithful to
+        // the document as served while still refusing to print a credential.
+        const payload = redact(raw);
+        if (source === undefined) {
+            const index = parseCatalogIndex(payload);
+            return this.respond(payload, () => {
+                renderTable(index.sources.map((entry) => ({ ...entry })), [
+                    { key: 'name', name: 'Source' },
+                    { key: 'label', name: 'Label' },
+                    { key: 'dimensions', name: 'Dimensions' },
+                    { key: 'metrics', name: 'Metrics' },
+                ], 'No sources.');
+                // Footer to STDERR: it is guidance, not data, and stdout must stay clean.
+                const hint = index.defaultSource === undefined ? '' : `, default ${index.defaultSource}`;
+                this.footer(`\n${index.sources.length} source(s)${hint}; \`${this.config.bin} catalog ${index.defaultSource ?? '<source>'}\` for its names`);
+            });
+        }
+        const entry = parseCatalogSource(payload);
+        return this.respond(payload, () => this.renderSource(entry));
+    }
+    renderSource(entry) {
+        this.log(sanitizeTerminal(`${entry.name} — ${entry.label}`));
+        if (entry.description)
+            this.log(sanitizeTerminal(entry.description));
+        for (const [heading, items] of [
+            ['DIMENSIONS', entry.dimensions],
+            ['METRICS', entry.metrics],
+        ]) {
+            this.log(`\n${heading}`);
+            renderTable(items.map((item) => ({ ...item })), [
+                { key: 'name', name: 'Name' },
+                { key: 'label', name: 'Label' },
+                { key: 'type', name: 'Type' },
+                { key: 'description', name: 'Description' },
+            ], '(none)');
+        }
+        if (entry.customDimensionsMax !== undefined) {
+            this.log(`\nCUSTOM DIMENSIONS  up to ${entry.customDimensionsMax} per connection`);
+        }
+        // A runnable next command built from THIS source's real names (E11-3, #102):
+        // the reader of a catalog is one edit away from a working query, so hand
+        // them that edit. stderr — guidance, not data.
+        const dimension = entry.dimensions[0]?.name;
+        const metric = entry.metrics[0]?.name;
+        if (dimension !== undefined && metric !== undefined) {
+            this.footer(`\nTry: ${this.config.bin} query --source ${entry.name} --connection-id <id|name> ` +
+                `-d ${dimension} -m ${metric} --json\n` +
+                `     (${this.config.bin} connections list prints the ids)`);
+        }
+    }
+}

package/dist/commands/connections/list.d.ts

@@ -16,4 +16,5 @@ export default class ConnectionsList extends BaseCommand<typeof ConnectionsList>
         count: number;
         records: unknown[];
     }>;
+    private printUsageFooter;
 }