flipstream 0.5.0 → 0.6.1

package/README.md

@@ -107,14 +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)
@@ -240,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.
@@ -351,6 +394,68 @@ 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.
@@ -517,18 +622,69 @@ EXAMPLES
 
 ## `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.
@@ -537,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/clear-all.d.ts

@@ -7,4 +7,5 @@ export default class AuthClearAll extends BaseCommand<typeof AuthClearAll> {
     };
     static summary: string;
     run(): Promise<Record<string, unknown>>;
+    private revoke;
 }

package/dist/commands/auth/clear-all.js

@@ -3,48 +3,115 @@ import { fetchMetadata } from '../../lib/auth/discovery.js';
 import { revokeToken } from '../../lib/auth/revoke.js';
 import { BaseCommand } from '../../lib/command/base.js';
 import { knownHosts, removeConfigDir } from '../../lib/config/xdg.js';
+import { CliError, TimeoutError } from '../../lib/errors.js';
+import { ExitCode } from '../../lib/exit-codes.js';
 import { createStore } from '../../lib/store/index.js';
 export default class AuthClearAll extends BaseCommand {
     static description = 'Purge ALL Flipstream credentials: every keychain entry and the local config directory.';
     static examples = ['<%= config.bin %> auth clear-all', '<%= config.bin %> auth clear-all --no-revoke'];
     static flags = {
-        'no-revoke': Flags.boolean({ description: 'Clear local credentials only; skip the per-host server revocation calls.' }),
+        'no-revoke': Flags.boolean({
+            description: 'Clear local credentials only; skip the per-host server revocation calls.',
+        }),
     };
     static summary = 'Purge ALL credentials: every keychain entry and the local config dir.';
     async run() {
         const store = createStore();
         const hosts = knownHosts();
         const timeoutMs = this.flags.timeout ?? 10_000;
-        // Best-effort revoke each host's refresh token (in parallel — no cross-host
-        // dependency), then clear its keychain entry regardless of the outcome.
-        await Promise.all(hosts.map(async (host) => {
-            const creds = store.load(host);
-            if (!this.flags['no-revoke'] && creds?.refreshToken) {
-                try {
-                    const meta = await fetchMetadata(host, { timeoutMs });
-                    await revokeToken({
-                        clientId: creds.clientId,
-                        revocationEndpoint: meta.revocationEndpoint,
-                        timeoutMs,
-                        token: creds.refreshToken,
-                        tokenTypeHint: 'refresh_token',
-                    });
-                }
-                catch {
-                    // Best-effort — proceed to clear the keychain entry anyway.
-                }
-            }
-            store.clear(host);
-        }));
+        // THE LOCAL PURGE COMES FIRST, AND ALONE. An earlier attempt at this gave the
+        // command one wall-clock budget covering both keychain and network work, and
+        // that budget then got spent by slow token revocations — so a later host's
+        // `clear` was skipped entirely and `clear-all` returned having left
+        // credentials in the keychain. A purge command must never be talked out of
+        // purging by a server that will not answer.
+        //
+        // So the two phases are separated: every host's entry is read and deleted
+        // here, one at a time (each keychain call raises its own OS dialog, and
+        // stacking them puts several prompts on one person), and the revocations run
+        // afterwards from tokens captured on the way through. Serial keychain work is
+        // bounded because each call carries its own deadline; nothing here inherits a
+        // network stall.
+        const revocations = [];
+        const failed = [];
+        let keychainTimedOut = false;
+        for (const host of hosts) {
+            let refreshToken;
+            let clientId;
+            try {
+                // eslint-disable-next-line no-await-in-loop -- serialized on purpose; see above
+                const creds = await store.load(host);
+                refreshToken = creds?.refreshToken;
+                clientId = creds?.clientId;
+            }
+            catch (error) {
+                // Unreadable is not fatal to the purge: the delete below still runs, and
+                // a credential we could not read is one we certainly cannot revoke.
+                if (error instanceof TimeoutError)
+                    keychainTimedOut = true;
+            }
+            if (!this.flags['no-revoke'] && refreshToken && clientId) {
+                revocations.push({ clientId, host, token: refreshToken });
+            }
+            try {
+                // eslint-disable-next-line no-await-in-loop -- serialized on purpose; see above
+                await store.clear(host);
+            }
+            catch (error) {
+                // Keep purging. One unusable entry must not strand every other host's
+                // credentials, and the caller is told exactly which ones survived.
+                if (error instanceof TimeoutError)
+                    keychainTimedOut = true;
+                failed.push(host);
+            }
+        }
+        // Best effort, and deliberately AFTER the purge: a revocation that hangs or
+        // 500s can no longer cost anybody a deleted credential. These are network
+        // calls with their own timeout and are never reported as keychain failures.
+        await Promise.all(revocations.map(async (revocation) => this.revoke(revocation, timeoutMs)));
+        const cleared = hosts.filter((host) => !failed.includes(host));
+        if (failed.length > 0) {
+            // The config dir STAYS. knownHosts() is read from it, so removing it here
+            // would delete the only record of the hosts whose secrets are still in the
+            // keychain — the retry this error recommends would then find nothing to
+            // retry, and live credentials would be left with no way to locate them.
+            const summary = `Cleared ${cleared.length} host(s); ${failed.length} could not be cleared: ${failed.join(', ')}`;
+            const hint = 'Those keychain entries may still exist, so the local host list has been kept for the ' +
+                'retry. Re-run once the keychain can answer.';
+            const next = ['flipstream auth clear-all'];
+            // keychain_timeout means the KEYCHAIN timed out. It is not a label for a
+            // slow issuer, which is why revocation now runs outside this path entirely.
+            if (keychainTimedOut) {
+                throw new TimeoutError(`${summary} — the OS keychain did not respond in time.`, 'keychain_timeout').withDetails({ hint, next, retryable: true });
+            }
+            throw new CliError(summary, 'clear_incomplete', ExitCode.GENERIC).withDetails({ hint, next, retryable: true });
+        }
         const configRemoved = removeConfigDir();
-        return this.respond({ clearedHosts: hosts, configRemoved }, () => {
+        return this.respond({ clearedHosts: cleared, configRemoved }, () => {
             if (hosts.length === 0 && !configRemoved) {
                 this.log('Nothing to clear.');
             }
             else {
-                this.log(`Cleared ${hosts.length} host(s): ${hosts.join(', ') || '(none)'}`);
+                this.log(`Cleared ${cleared.length} host(s): ${cleared.join(', ') || '(none)'}`);
                 this.log(configRemoved ? 'Removed the local config directory.' : 'No local config directory to remove.');
             }
         });
     }
+    // One host's revocation, swallowing everything: the local credential is
+    // already gone, so nothing here can improve or worsen the purge.
+    async revoke(revocation, timeoutMs) {
+        try {
+            const meta = await fetchMetadata(revocation.host, { timeoutMs });
+            await revokeToken({
+                clientId: revocation.clientId,
+                revocationEndpoint: meta.revocationEndpoint,
+                timeoutMs,
+                token: revocation.token,
+                tokenTypeHint: 'refresh_token',
+            });
+        }
+        catch {
+            // Best-effort by contract.
+        }
+    }
 }

package/dist/commands/auth/login.js

@@ -23,7 +23,7 @@ export default class AuthLogin extends BaseCommand {
         });
         const expiresAt = Math.floor(Date.now() / 1000) + result.expiresIn;
         try {
-            createStore().save(result.host, {
+            await createStore().save(result.host, {
                 accessToken: result.accessToken,
                 clientId: result.clientId,
                 expiresAt,
@@ -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/logout.js

@@ -14,7 +14,7 @@ export default class AuthLogout extends BaseCommand {
     async run() {
         const host = this.resolvedHost();
         const store = createStore();
-        const creds = store.load(host);
+        const creds = await store.load(host);
         if (!creds) {
             return this.respond({ host, loggedOut: true, revoked: false }, () => this.log(`Not logged in to ${host}; nothing to do.`));
         }
@@ -40,7 +40,7 @@ export default class AuthLogout extends BaseCommand {
             }
         }
         // Always clear local credentials, even if revocation could not be confirmed.
-        store.clear(host);
+        await store.clear(host);
         forgetHost(host);
         return this.respond({ host, loggedOut: true, revoked }, () => {
             this.log(`Logged out of ${host}.`);

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'];
@@ -11,16 +18,17 @@ export default class AuthStatus extends BaseCommand {
     async run() {
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.available()) {
-            process.stderr.write('The OS keychain is unavailable (e.g. a headless/SSH session). Browser login needs it; ' +
-                'a headless client_credentials / service-account path is PLANNED.\n');
+        if (!(await store.available())) {
+            process.stderr.write('The OS keychain is unavailable (e.g. a headless/SSH session). Browser login needs it. ' +
+                'Over SSH or any other remote access, use a Flipstream service account from your ' +
+                'Flipstream account instead — it needs no browser and no keychain.\n');
             return this.exit(ExitCode.NETWORK);
         }
-        const creds = store.load(host);
+        const creds = await store.load(host);
         if (!creds) {
             return this.respond({ host, loggedIn: false }, () => this.log(`Not logged in to ${host}. Run \`flipstream auth login\`.`));
         }
-        const claims = tokenClaims(host, store) ?? {};
+        const claims = (await tokenClaims(host, store)) ?? {};
         // JSON keeps the stable subject id (agent-friendly); the human line prefers
         // the friendlier email when present.
         const account = [claims.sub, claims.email].find((value) => typeof value === 'string') ?? null;
@@ -37,11 +45,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 (!(await 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;
 }