flipstream 0.5.0 → 0.6.1

package/dist/commands/connections/list.js

@@ -27,9 +27,10 @@ export default class ConnectionsList extends BaseCommand {
             assertUuid(workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
+        const startedMs = Date.now();
         const projected = await fetchConnections(client, {
             all: this.flags.all,
             limit: this.flags.limit,
@@ -39,6 +40,31 @@ export default class ConnectionsList extends BaseCommand {
             workspace,
         });
         await hydrate(client, projected.records, [WORKSPACE_NAME]);
-        return this.respondList(projected, (records) => renderConnectionsTable(records));
+        // Which origin answered (E11-2): planner vs admin is the first debugging question.
+        this.verboseLog(`GET ${host}/connections (${Date.now() - startedMs} ms)`);
+        return this.respondList(projected, (records) => {
+            renderConnectionsTable(records);
+            this.printUsageFooter(records);
+        });
+    }
+    // The exact next command with a REAL id from the results (E11-3, #102) — the
+    // whole reason an agent lists connections is to feed one into `query`.
+    // stderr — guidance, not data; only in the human path (respondList gates it).
+    printUsageFooter(records) {
+        const first = records.find((record) => {
+            const candidate = record;
+            return typeof candidate?.id === 'string' && candidate.active !== false;
+        });
+        if (first === undefined) {
+            // All-inactive is exactly when the reader is about to be confused:
+            // `query` will refuse every one of these ids.
+            if (records.length > 0) {
+                this.footer('\nNo ACTIVE connection in these results — query refuses an inactive connection.');
+            }
+            return;
+        }
+        // The id is a server-supplied string — footer() redacts + sanitizes it.
+        this.footer(`\nTry: ${this.config.bin} query --source <source> --connection-id ${first.id} -d <dim> -m <metric> --json\n` +
+            `     (${this.config.bin} catalog lists the sources and their names)`);
     }
 }

package/dist/commands/contract.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../lib/command/base.js';
+export default class Contract extends BaseCommand<typeof Contract> {
+    static description: string;
+    static examples: string[];
+    static flags: {};
+    static summary: string;
+    run(): Promise<{
+        contractVersion: string;
+        markdown: string;
+    }>;
+}

package/dist/commands/contract.js

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { BaseCommand } from '../lib/command/base.js';
+import { CONTRACT_VERSION } from '../lib/config/constants.js';
+import { CliError } from '../lib/errors.js';
+import { ExitCode } from '../lib/exit-codes.js';
+// <package root>/docs/AGENT-CONTRACT.md, resolved relative to this module so it
+// works from dist in the published tarball and from src in dev.
+function contractPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    return join(here, '..', '..', 'docs', 'AGENT-CONTRACT.md');
+}
+export default class Contract extends BaseCommand {
+    static description = '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.';
+    static examples = ['<%= config.bin %> contract', '<%= config.bin %> contract --json'];
+    static flags = {};
+    static summary = 'Print the agent contract (machine-facing promises) to stdout.';
+    async run() {
+        let markdown;
+        try {
+            markdown = readFileSync(contractPath(), 'utf8');
+        }
+        catch {
+            // Never a raw ENOENT: the class name is not a contract code, and the
+            // absolute path (with the OS username) does not belong on stdout.
+            throw new CliError('The packaged agent contract is missing from this installation.', 'contract_unavailable', ExitCode.GENERIC).withDetails({ hint: 'Reinstall the CLI: npm i -g flipstream', retryable: false });
+        }
+        // The document IS the data here, so human mode prints it verbatim on
+        // stdout; --json wraps it with the version for programmatic consumers.
+        return this.respond({ contractVersion: CONTRACT_VERSION, markdown }, () => this.log(markdown));
+    }
+}

package/dist/commands/health.d.ts

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

package/dist/commands/health.js

@@ -0,0 +1,31 @@
+import { Flags } from '@oclif/core';
+import { mapDataError } from '../lib/api/errors.js';
+import { BaseCommand } from '../lib/command/base.js';
+import { resolvePlannerUrl } from '../lib/config/xdg.js';
+import { getPlannerHealth } from '../lib/planner/client.js';
+export default class Health extends BaseCommand {
+    static description = '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.';
+    static examples = [
+        '<%= config.bin %> health',
+        '<%= config.bin %> health --json',
+        '<%= config.bin %> health --url http://localhost:8080',
+    ];
+    static flags = {
+        url: Flags.string({
+            description: 'Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).',
+        }),
+    };
+    static summary = 'Check that the query planner is reachable.';
+    async run() {
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        let payload;
+        try {
+            payload = await getPlannerHealth(url, { timeoutMs: this.flags.timeout });
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+        return this.respond(payload, (data) => this.log(JSON.stringify(data, null, 2)));
+    }
+}

package/dist/commands/log/add.js

@@ -8,7 +8,7 @@ import { createStore } from '../../lib/store/index.js';
 export default class LogAdd extends BaseCommand {
     static aliases = ['logs:add'];
     static args = {
-        message: Args.string({ description: 'The log entry text.', required: true }),
+        message: Args.string({ description: 'The log entry text.', ignoreStdin: true, required: true }),
     };
     static description = "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). ' +
@@ -20,14 +20,18 @@ export default class LogAdd extends BaseCommand {
     static flags = {
         end: Flags.string({ description: 'End date (ISO 8601). Defaults to now.' }),
         start: Flags.string({ description: 'Start date (ISO 8601). Defaults to now.' }),
-        workspace: Flags.string({ aliases: ['ws'], description: 'Workspace id (UUID) the entry belongs to.', required: true }),
+        workspace: Flags.string({
+            aliases: ['ws'],
+            description: 'Workspace id (UUID) the entry belongs to.',
+            required: true,
+        }),
     };
     static summary = "Add an entry to a workspace's log.";
     async run() {
         assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const organizationId = await resolveWorkspaceOrg(client, this.flags.workspace);

package/dist/commands/log/list.js

@@ -26,7 +26,7 @@ export default class LogList extends BaseCommand {
         assertUuid(this.flags.workspace, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
         const projected = await fetchLog(client, {

package/dist/commands/query.d.ts

@@ -3,11 +3,24 @@ export default class Query extends BaseCommand<typeof Query> {
     static description: string;
     static examples: string[];
     static flags: {
-        'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         body: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'body-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'connection-id': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        dimension: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        filter: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        metric: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        offset: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        rows: import("@oclif/core/interfaces").OptionFlag<number | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        sort: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        source: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        table: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        '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 parseBody;
+    private engineFailureDetails;
+    private enrichPlannerError;
+    private readVerbatimBody;
 }

package/dist/commands/query.js

@@ -1,76 +1,289 @@
 import { Flags } from '@oclif/core';
 import { readFileSync } from 'node:fs';
-import { mapDataError } from '../lib/api/errors.js';
-import { createAuthedDataClient } from '../lib/api/retry.js';
-import { refresh } from '../lib/auth/refresh.js';
+import { tokenClaims } from '../lib/auth/claims.js';
+import { authedAdminClient } from '../lib/command/admin.js';
 import { BaseCommand } from '../lib/command/base.js';
-import { DATA_HOST } from '../lib/config/constants.js';
-import { resolveHost } from '../lib/config/xdg.js';
-import { AuthRequiredError, UsageError } from '../lib/errors.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, DataHttpError, UsageError } from '../lib/errors.js';
 import { redact } from '../lib/output/redact.js';
+import { assertConnectionActive, connectionIsVisible, resolveConnection } from '../lib/planner/connection.js';
+import { attachVocabularyDiagnosis } from '../lib/planner/diagnose.js';
+import { mapPlannerError, plannerCode } from '../lib/planner/errors.js';
+import { describeSelections } from '../lib/planner/filters.js';
+import { buildLogicalRequest } from '../lib/planner/request.js';
 import { createStore } from '../lib/store/index.js';
+// The connection_id carried by a body, whoever built it.
+function readConnectionId(body) {
+    const value = body?.connection_id;
+    return typeof value === 'string' ? value : undefined;
+}
+// Sub-second runs read as milliseconds — "0.0s" looks like a broken timer.
+function formatElapsed(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+// Row count of a planner/engine response, when it has the conventional shape.
+// undefined (not 0) when the shape is anything else — the narration then simply
+// omits the count rather than asserting a wrong one.
+function countRows(response) {
+    const rows = response?.rows;
+    return Array.isArray(rows) ? rows.length : undefined;
+}
 export default class Query extends BaseCommand {
-    static description = '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).';
+    static description = '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.';
     static examples = [
-        '<%= config.bin %> query --body \'{"opaque":true}\'',
-        'echo \'{"opaque":true}\' | <%= config.bin %> query',
-        '<%= config.bin %> query --body-file query.json --json',
+        '<%= config.bin %> catalog gsc',
+        "<%= config.bin %> 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",
+        '<%= config.bin %> query --source gsc --connection-id <id> -d query -m clicks --dry-run',
+        '<%= config.bin %> query --body-file request.json --json',
     ];
     static flags = {
-        'auth-host': Flags.string({
-            description: 'OAuth issuer host for credentials/refresh (defaults to the prod issuer).',
+        ...plannerFlags,
+        body: Flags.string({ description: 'Send this JSON body verbatim.', exclusive: ['body-file'] }),
+        'body-file': Flags.string({ description: 'Path to a file holding the JSON body verbatim ("-" reads stdin).' }),
+        'connection-id': Flags.string({ description: 'Connection UUID, or a name to look up.' }),
+        dimension: Flags.string({ char: 'd', description: 'Dimension name (repeatable).', multiple: true }),
+        'dry-run': Flags.boolean({ description: 'Print the request body and send nothing.' }),
+        filter: Flags.string({
+            char: 'f',
+            description: "Filter as col=a,b | col=from..to | col=<json> (repeatable). 'col=' is refused.",
+            multiple: true,
         }),
-        body: Flags.string({ description: 'Opaque JSON request body as a string.', exclusive: ['body-file'] }),
-        'body-file': Flags.string({ description: 'Path to a file holding the opaque JSON request body.' }),
+        metric: Flags.string({ char: 'm', description: 'Metric name (repeatable).', multiple: true }),
+        offset: Flags.integer({ description: 'Row offset.' }),
+        rows: Flags.integer({ description: 'Row limit (default 100).' }),
+        sort: Flags.string({ char: 's', description: 'FIELD[:asc|desc] (repeatable).', multiple: true }),
+        source: Flags.string({ description: 'The dataset discriminator, e.g. gsc.' }),
+        table: Flags.string({ description: 'Physical table — honoured only for an unmodelled source.' }),
     };
-    static summary = 'Run an opaque query against the Flipstream data API.';
+    static summary = 'Run a logical query against the Flipstream query planner.';
     async run() {
-        // --host overrides the DATA query target; --auth-host the issuer holding creds.
-        const dataHost = this.flags.host ?? DATA_HOST;
-        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] });
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] ?? this.flags.host });
+        const verbatim = this.readVerbatimBody();
+        const built = verbatim === undefined
+            ? buildLogicalRequest({
+                connectionId: this.flags['connection-id'],
+                dimensions: this.flags.dimension,
+                filters: this.flags.filter,
+                metrics: this.flags.metric,
+                offset: this.flags.offset,
+                rows: this.flags.rows,
+                sort: this.flags.sort,
+                source: this.flags.source,
+                table: this.flags.table,
+            }, this.config.bin)
+            : undefined;
+        const body = verbatim ?? built;
+        // Narrate the filter interpretation (E11-2): the selection-length predicate
+        // routes silently, so say which reading each filter got — in the encoder
+        // module's own words (filters.ts owns the predicate). Flags path only; a
+        // verbatim body is the caller's own construction.
+        if (built !== undefined)
+            for (const line of describeSelections(built.filters))
+                this.note(line);
+        // Deliberately OFFLINE, and deliberately BEFORE the credential check: it
+        // prints what you typed, so a connection NAME is left as you wrote it.
+        // Resolving it would make a dry run need a token, which defeats the point —
+        // `flipstream connections list` is the command for that.
+        if (this.flags['dry-run']) {
+            return this.respond(body, (data) => this.log(JSON.stringify(data, null, 2)));
+        }
         const store = createStore();
-        // Distinguish never-logged-in (no creds) from a later expired/refresh-rejected
-        // session (the wrapper raises session_expired on a null refresh).
-        if (!store.load(authHost))
+        if (!(await store.load(authHost)))
             throw AuthRequiredError.notLoggedIn();
-        const body = this.parseBody();
-        const client = createAuthedDataClient({
-            accessTokenIfFresh: (host) => store.accessTokenIfFresh(host),
-            authHost,
-            host: dataHost,
-            refresh: (host) => refresh(host, { store, timeoutMs: this.flags.timeout }),
-            timeoutMs: this.flags.timeout,
-        });
+        const admin = authedAdminClient(authHost, store, this.flags.timeout);
+        // Resolve + check the connection for BOTH paths. Name resolution is only for
+        // the flags path (a verbatim body stays verbatim), but the inactive check
+        // applies to whatever connection_id is about to be sent — otherwise --body
+        // would be a one-flag bypass of it.
+        const target = verbatim === undefined ? this.flags['connection-id'] : readConnectionId(body);
+        let connectionLabel = target === undefined || target.length === 0 ? 'unspecified' : target;
+        if (target !== undefined && target.length > 0) {
+            // The resolution note ("connection acme → uuid") is an environmental
+            // inference like any other narration: routed through note() so it is
+            // redacted, sanitized, and silent under --json/--ndjson (E11-2).
+            const resolved = await resolveConnection(admin, target, {
+                note: (message) => this.note(message),
+            });
+            assertConnectionActive(resolved);
+            if (verbatim === undefined)
+                body.connection_id = resolved.id;
+            connectionLabel = resolved.name.length > 0 ? `${resolved.name} (${resolved.id})` : resolved.id;
+        }
+        const client = authedPlannerClient({ authHost, store, timeoutMs: this.flags.timeout, url });
+        const started = Date.now();
         let response;
         try {
             response = await client.postQuery(body, { timeoutMs: this.flags.timeout });
         }
         catch (error) {
-            throw mapDataError(error);
+            const engine = await this.engineFailureDetails(error, admin, body);
+            throw await this.enrichPlannerError(mapPlannerError(error), body, { authHost, client, engine, store });
         }
-        // Redact known secret KEY NAMES (E3-4) so a token-like key echoed by the DATA
-        // host never reaches --json/NDJSON/human output.
+        const elapsedMs = Date.now() - started;
+        // Timing to STDERR — diagnostics, never part of the data (protects --json).
+        this.verboseLog(`POST ${url}/query (${elapsedMs} ms)`);
+        // Resolved-context line (E11-2): which host answered, as which connection,
+        // for which source, and how much came back — the facts an agent (or a human
+        // sanity-checking numbers) otherwise has to reconstruct from four places.
+        const source = body?.source;
+        const rows = countRows(response);
+        this.note(`planner ${url} · connection ${connectionLabel} · source ${typeof source === 'string' ? source : 'unspecified'}` +
+            `${rows === undefined ? '' : ` · ${rows} row${rows === 1 ? '' : 's'}`} in ${formatElapsed(elapsedMs)}`);
+        // Redact known secret KEY NAMES so a token-like key echoed by the planner or
+        // the engine behind it never reaches --json/NDJSON/human output.
         const safe = redact(response);
         return this.respond(safe, (data) => this.log(JSON.stringify(data, null, 2)));
     }
-    // Forward the body VERBATIM: parse-only, no schema and no field handling.
-    parseBody() {
+    // ENGINE_FAILED covers everything from a bad connection to broken SQL, and the
+    // distinguishing detail stays in the planner's log on purpose (it names tables).
+    // The most common cause by far is a connection this token cannot resolve — a
+    // question we CAN ask pulse-admin ourselves. Returns envelope DETAILS (not a
+    // stderr side effect) so the --json consumer — the one the contract is written
+    // for — sees the diagnosis too. Only speaks on a definite no; a confident
+    // wrong hint in front of a real failure is worse than none.
+    async engineFailureDetails(error, admin, body) {
+        if (!(error instanceof DataHttpError) || plannerCode(error.bodyText) !== 'ENGINE_FAILED')
+            return undefined;
+        const connectionId = readConnectionId(body);
+        if (connectionId === undefined || connectionId.length === 0)
+            return undefined;
+        if ((await connectionIsVisible(admin, connectionId)) !== false)
+            return undefined;
+        return {
+            hint: 'Your token cannot see this connection — pulse-data resolves it through pulse-admin as you, ' +
+                'and gets nothing. Pick one your token can reach.',
+            next: [`${this.config.bin} connections list --json`],
+            retryable: false,
+        };
+    }
+    // Post-map enrichment (E11-1): attach the remediation only a command with the
+    // full request in hand can know. The mapper stays generic; this layer knows the
+    // source that was queried and the token that was used.
+    async enrichPlannerError(error, body, context) {
+        if (context.engine !== undefined)
+            error.withDetails(context.engine);
+        // An UNKNOWN_* vocabulary rejection: diagnose against the catalog FIRST
+        // (specific hint + runnable next — lib/planner/diagnose.ts), then fill any
+        // remaining gap with generic remediation, never displacing the diagnosis.
+        if (error.details.upstreamCode?.startsWith('UNKNOWN_')) {
+            // Diagnosis never triggers a token refresh: an error-path bonus fetch
+            // must not be able to mutate persistent auth state (review, #110).
+            if ((await context.store.accessTokenIfFresh(context.authHost)) === null) {
+                this.verboseLog('vocabulary diagnosis skipped: no fresh access token (diagnosis never refreshes)');
+            }
+            else {
+                await attachVocabularyDiagnosis(error, {
+                    bin: this.config.bin,
+                    body,
+                    // A bonus fetch gets a bonus-sized budget — a hanging catalog must
+                    // not double the time-to-error of a fast deterministic 400.
+                    fetchCatalog: (catalogSource) => context.client.getCatalog(catalogSource, { timeoutMs: Math.min(this.flags.timeout ?? 30_000, 5000) }),
+                    onSkip: (reason) => this.verboseLog(`vocabulary diagnosis skipped: ${reason}`),
+                });
+            }
+            // Gap-filling generic remediation. The interpolated source comes from
+            // the request body (caller-supplied JSON under --body/stdin) and `next`
+            // strings are commands the contract tells an agent to RUN: only a
+            // catalog-key-shaped name is embedded, and never for UNKNOWN_SOURCE —
+            // that would suggest the very name the planner just rejected.
+            const source = body?.source;
+            const sourceName = typeof source === 'string' && /^[\w.-]{1,64}$/.test(source) ? source : undefined;
+            if (error.details.next === undefined) {
+                const useSource = error.details.upstreamCode !== 'UNKNOWN_SOURCE' && sourceName !== undefined;
+                error.withDetails({ next: [`${this.config.bin} catalog${useSource ? ` ${sourceName}` : ''}`] });
+            }
+            if (error.details.hint === undefined) {
+                error.withDetails({
+                    hint: 'Names for -d, -m and filter keys must come from the catalog — no aliases, no guessing.',
+                });
+            }
+            error.withDetails({ retryable: false });
+        }
+        // A 403 two services away is near-undebuggable without knowing what the token
+        // actually carried. Scopes/roles are display-only claims (never used to gate
+        // anything client-side) and are not secrets; both lists are bounded so a
+        // token from a hostile --auth-host issuer cannot balloon the envelope.
+        if (error.code === 'role_forbidden') {
+            const claims = (await tokenClaims(context.authHost, context.store)) ?? {};
+            const roles = (Array.isArray(claims.roles) ? claims.roles.filter((r) => typeof r === 'string') : [])
+                .slice(0, 20)
+                .map((role) => role.slice(0, 64));
+            const scopes = ((await context.store.load(context.authHost))?.scopes ?? [])
+                .slice(0, 20)
+                .map((scope) => scope.slice(0, 64));
+            error.withDetails({
+                hint: `Your token carries scopes [${scopes.join(' ')}] and roles [${roles.join(' ')}]. ` +
+                    'The planner admits a caller with ANY allowed role OR all required scopes ' +
+                    '(grid_data:read + connections:read) — re-login if these look stale.',
+                next: [`${this.config.bin} auth status`, `${this.config.bin} auth login`],
+                retryable: false,
+            });
+        }
+        return error;
+    }
+    // A verbatim body short-circuits the whole builder. Returns undefined when the
+    // flags path should be used instead.
+    readVerbatimBody() {
+        const file = this.flags['body-file'];
         let raw;
-        if (this.flags.body !== undefined)
+        let label;
+        if (this.flags.body !== undefined) {
             raw = this.flags.body;
-        else if (this.flags['body-file'] !== undefined)
-            raw = readFileSync(this.flags['body-file'], 'utf8');
-        else if (process.stdin.isTTY)
-            throw new UsageError('Provide a body via --body, --body-file <path>, or piped stdin.');
-        else
+            label = '--body';
+        }
+        else if (file !== undefined) {
+            raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8');
+            label = file === '-' ? 'stdin (--body-file -)' : `--body-file ${file}`;
+        }
+        else if (this.flags.source === undefined && this.flags['connection-id'] === undefined && !process.stdin.isTTY) {
+            // Piped stdin with no flags: the pre-E8 invocation, still supported. This
+            // is an INFERENCE — a spawned process has non-TTY stdin by default — so
+            // it is announced, never silent (E11-2), and an empty read means "no
+            // request was given at all", not "bad JSON" (E11-1).
+            this.note('reading the request body from stdin (no query flags given and stdin is piped)');
             raw = readFileSync(0, 'utf8');
+            label = 'stdin';
+            if (raw.trim() === '') {
+                // Empty stdin + builder flags (-d/-m/-f/...) means the caller wanted
+                // the FLAGS path: fall through to the builder, whose missing_source_*
+                // errors name exactly what is absent — never claim "no flags" when
+                // flags were passed (#100's own rule).
+                const builderFlagGiven = this.flags.dimension !== undefined ||
+                    this.flags.metric !== undefined ||
+                    this.flags.filter !== undefined ||
+                    this.flags.sort !== undefined ||
+                    this.flags.rows !== undefined ||
+                    this.flags.offset !== undefined ||
+                    this.flags.table !== undefined;
+                if (builderFlagGiven)
+                    return undefined;
+                throw new UsageError('No request given: no --source/--connection-id flags, and stdin was empty.', 'missing_request').withDetails({
+                    docs: 'docs/AGENT-CONTRACT.md#the-query-request-shape-logicalrequest',
+                    hint: 'Build the query from flags (--source, --connection-id, -d, -m), or pipe a JSON body on stdin.',
+                    next: [`${this.config.bin} catalog`, `${this.config.bin} connections list --json`],
+                    retryable: false,
+                });
+            }
+        }
+        else
+            return undefined;
         try {
             return JSON.parse(raw);
         }
         catch {
-            throw new UsageError('Request body is not valid JSON.');
+            // Name where the body came from — under the stdin inference the caller may
+            // not even realise a body was being read.
+            throw new UsageError(`Request body from ${label} is not valid JSON.`, 'invalid_body_json').withDetails({
+                hint: 'The body must be one JSON object in LogicalRequest shape; flags build it for you.',
+                next: [`${this.config.bin} query --source <source> --connection-id <id> -d <dim> -m <metric> --dry-run`],
+                retryable: false,
+            });
         }
     }
 }

package/dist/commands/skills/install.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class SkillsInstall extends BaseCommand<typeof SkillsInstall> {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<{
+        installed: Array<{
+            agent: string;
+            path: string;
+        }>;
+    }>;
+}

package/dist/commands/skills/install.js

@@ -0,0 +1,55 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/command/base.js';
+import { confirm } from '../../lib/output/dialogs.js';
+import { isCI } from '../../lib/output/interactivity.js';
+import { installSkill, resolveTargets, SUPPORTED_AGENTS } from '../../lib/skills/install.js';
+export default class SkillsInstall extends BaseCommand {
+    static description = '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.';
+    static examples = [
+        '<%= config.bin %> skills install',
+        '<%= config.bin %> skills install --yes',
+        '<%= config.bin %> skills install --agent claude-code --agent codex',
+    ];
+    static flags = {
+        agent: Flags.string({
+            description: `Install for this agent id only (repeatable). Known: ${SUPPORTED_AGENTS.map((a) => a.id).join(', ')}.`,
+            multiple: true,
+            options: SUPPORTED_AGENTS.map((a) => a.id),
+        }),
+        yes: Flags.boolean({ char: 'y', default: false, description: 'Install without asking.' }),
+    };
+    static summary = 'Install the flipstream skill for detected AI coding agents.';
+    async run() {
+        // CI never installs skills: the runner's home is ephemeral and nobody asked.
+        if (isCI()) {
+            // Diagnostics, not data — stderr, per the catalog-footer precedent.
+            return this.respond({ installed: [] }, () => process.stderr.write('CI environment detected — skipping skill install.\n'));
+        }
+        const targets = resolveTargets({ explicit: this.flags.agent });
+        if (targets.length === 0) {
+            return this.respond({ installed: [] }, () => process.stderr.write('No supported agents detected (looked for a driving agent and for ' +
+                `${SUPPORTED_AGENTS.map((a) => a.id).join(', ')} home directories).\n`));
+        }
+        // Running `skills install` already states intent, so the non-interactive
+        // fallback is yes (announced) — --yes exists to skip the question entirely.
+        const proceed = this.flags.yes ||
+            (await confirm(`Install the flipstream skill for: ${targets.map((t) => t.name).join(', ')}?`, {
+                defaultValue: true,
+                fallbackValue: true,
+                unblockFlag: '--yes',
+            }));
+        if (!proceed) {
+            return this.respond({ installed: [] }, () => process.stderr.write('Skipped.\n'));
+        }
+        const result = installSkill(targets);
+        return this.respond(result, () => {
+            for (const entry of result.installed) {
+                const backup = entry.backup === undefined ? '' : ` (previous copy preserved at ${entry.backup})`;
+                this.log(`${entry.status} ${entry.agent}: ${entry.path}${backup}`);
+            }
+        });
+    }
+}