product-console-companion 0.1.0 → 0.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Fynch Consulting
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Fynch Consulting
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,96 +1,141 @@
-# product-console-companion
-
-A local-first BYOS companion for the [Fynch Product Console](../README.md). Reads code from
-your own machine, so:
-
-- code never leaves your machine — only a small structured verdict (matches/differs + a short
-  explanation) is ever sent back;
-- there's no server-side truncation on what gets read (`server/drift.ts`'s
-  `MAX_FILE_CHARS`/`MAX_TREE_PATHS` don't apply here at all);
-- AI spend bills against your own key/subscription, not the workspace's shared/BYOK credential.
-
-Covers every AI call the hosted Console makes that reads your code — six task kinds as of this
-release (`verify_module` — "Check against code" on a module card; `generate_spec_batch` —
-writing full specs during setup; `propose_skeleton` and `propose_new_capabilities` — the two
-shallow whole-repo scans; `design_prompt` — the free-text export; `analyse_shipment` — the
-passive per-commit drift check behind the GitHub webhook and the "Check GitHub" button), two
-backends, chosen per connection at `connect` time:
-
-- **`api-key`** (default) — no CLI dependency. Calls Anthropic directly with your own API key
-  (`api-key-caller.ts`), running its own two-pass file-select-then-judge, mirroring
-  `server/drift.ts`'s `verifyModuleAgainstCode` but reading local files unbounded.
-- **`cli`** — shells out to an already-authenticated `claude` CLI (`claude-cli-caller.ts`) for
-  full agentic Read/Grep/Glob depth in one call — the model does its own exploring instead of a
-  separate file-select pass. Bills against whatever the CLI is authenticated with (a Claude
-  subscription via `claude setup-token`, or `ANTHROPIC_API_KEY` if the CLI has that set). Runs
-  against a disposable, read-only git worktree (`sandbox.ts`) as defense-in-depth on top of
-  `--restricted --tools "Read,Grep,Glob"`, which should already make a write/exec structurally
-  impossible on its own.
-
-## Setup
-
-```bash
-npx product-console-companion connect \
-  --url https://console.fynchconsulting.com \
-  --token <publicId>.<secret> \
-  --connection <connectionId> \
-  --path /path/to/your/local/checkout \
-  --backend api-key   # or: --backend cli
-```
-
-Get `--token`/`--connection` from the Console's **Companion** button (generates a token and a
-ready-to-paste version of this command) — see `src/CompanionModal.tsx` in the parent repo.
-Running `connect` again for a different `--connection`/`--path` (same `--url`/`--token`) adds a
-second connection to the same local config; one companion process can serve several repos, each
-with its own backend choice.
-
-For `--backend api-key`: `export ANTHROPIC_API_KEY=sk-ant-...` (get one at console.anthropic.com).
-For `--backend cli`: install and authenticate the CLI first — `npm install -g
-@anthropic-ai/claude-code`, then `claude` (interactive login) or set `ANTHROPIC_API_KEY` for it.
-`connect` checks `claude --version` up front and fails fast if it's missing.
-
-Then, in the Console's **Manage connected repos**, switch that repo's execution to "On your
-machine, via companion". Finally, to actually serve tasks:
-
-```bash
-npx product-console-companion run
-```
-
-Polls each configured connection every few seconds until Ctrl+C. Nothing runs while this isn't
-running — see the parent plan's Section 7 for why that's deliberate (goal 4: no AI spend while
-you're not around to notice).
-
-## What's NOT yet implemented (be aware before relying on this)
-
-- **Per-task budget is not enforced client-side for the `api-key` backend.** Every dispatched
-  task carries a `maxBudgetUsd` (visible in the `run` log line); `api-key-caller.ts` does not
-  track spend against it or abort a call that exceeds it. The `cli` backend passes it straight
-  through as `claude`'s own `--max-budget-usd`, which the CLI does enforce (confirmed
-  empirically: it stops and reports `terminal_reason: 'budget_exhausted'`).
-- **No wall-clock timeout for the `api-key` backend** — a hung request blocks that connection's
-  polling loop. The `cli` backend has one (10 minutes, independent of the budget cap — a dollar
-  ceiling doesn't stop a network-stall hang).
-- **Git-fetch-if-missing is `analyse_shipment`-only.** Every other task kind reads whatever HEAD
-  currently is in `--path` (or, for `cli`, a worktree pinned to that HEAD) — correct for those,
-  since they check the *current* state of your code, not a specific historical commit.
-  `analyse_shipment` is different: it's about one specific commit a webhook or the hosted poller
-  told the server about, which the server never fetches for you. It verifies that commit is
-  actually present locally first, attempts one `git fetch` (your own git credentials — never
-  anything from the hosted server) if it isn't, and reports back distinctly (`sha_not_local`)
-  rather than silently analysing the wrong tree state if it still can't find it.
-- **`cli` backend's sandbox worktree isolates writes, not reads** — `--add-dir` points at the
-  disposable worktree, so a read sees exactly what's committed at HEAD, including anything
-  `.gitignore`d being invisible (same as `git ls-files`'s own behavior). Uncommitted local
-  changes in your real checkout are never visible to the CLI backend — worth knowing if you're
-  expecting a check to see work-in-progress edits. (`analyse_shipment`'s own diff read is the one
-  exception: it happens against your real checkout, via `git show`, before the sandbox is even
-  created — the model itself still only ever sees the sandboxed copy.)
-
-## Local development (inside the parent repo)
-
-```bash
-cd companion
-npm install
-npm run dev -- connect --url http://localhost:3101 --token <publicId>.<secret> --connection <connectionId> --path <repo path> --backend api-key
-npm run dev -- run
-```
+# product-console-companion
+
+A local-first BYOS companion for the [Fynch Product Console](../README.md). Reads code from
+your own machine, so:
+
+- code never leaves your machine — only a small structured verdict (matches/differs + a short
+  explanation) is ever sent back;
+- there's no server-side truncation on what gets read (`server/drift.ts`'s
+  `MAX_FILE_CHARS`/`MAX_TREE_PATHS` don't apply here at all);
+- AI spend bills against your own key/subscription, not the workspace's shared/BYOK credential.
+
+Covers every AI call the hosted Console makes that reads your code — six task kinds as of this
+release (`verify_module` — "Check against code" on a module card; `generate_spec_batch` —
+writing full specs during setup; `propose_skeleton` and `propose_new_capabilities` — the two
+shallow whole-repo scans; `design_prompt` — the free-text export; `analyse_shipment` — the
+passive per-commit drift check behind the GitHub webhook and the "Check GitHub" button), two
+backends, chosen per connection at `connect` time:
+
+- **`api-key`** (default) — no CLI dependency. Calls Anthropic directly with your own API key
+  (`api-key-caller.ts`), running its own two-pass file-select-then-judge, mirroring
+  `server/drift.ts`'s `verifyModuleAgainstCode` but reading local files unbounded.
+- **`cli`** — shells out to an already-authenticated `claude` CLI (`claude-cli-caller.ts`) for
+  full agentic Read/Grep/Glob depth in one call — the model does its own exploring instead of a
+  separate file-select pass. Bills against whatever the CLI is authenticated with (a Claude
+  subscription via `claude setup-token`, or `ANTHROPIC_API_KEY` if the CLI has that set). Runs
+  against a disposable, read-only git worktree (`sandbox.ts`) as defense-in-depth on top of
+  `--restricted --tools "Read,Grep,Glob"`, which should already make a write/exec structurally
+  impossible on its own.
+
+## Setup
+
+The Console's **Companion** button generates a ready-to-paste command per connected project —
+that's the intended way to get `--token`/`--connection`/`--path` right (see
+`src/CompanionModal.tsx` in the parent repo, which also has an inline toggle to switch that
+connection's execution to "on your machine" right next to the command it activates). Written out,
+the shape is:
+
+```bash
+npx product-console-companion connect \
+  --url https://console.fynchconsulting.com \
+  --token <publicId>.<secret> \
+  --connection <connectionId> \
+  --path /path/to/your/local/checkout \
+  --backend api-key \
+  --api-key sk-ant-...     # optional — see below
+```
+
+`--path` defaults to the current directory if omitted — running `connect` from inside your
+project's own folder works with no `--path` at all. `connect` **pairs and immediately starts
+serving tasks in the same command** (equivalent to also running `run`, below) — pass `--no-run`
+if you're pairing a second/third project first and want to start one shared `run` for all of them
+afterward instead.
+
+Running `connect` again for a different `--connection`/`--path` (same `--url`/`--token`) adds a
+second connection to the same local config; one companion process can serve several repos, each
+with its own backend choice.
+
+To pair this machine before any repo is connected, omit `--connection` and `--path`:
+
+```bash
+npx product-console-companion connect --url https://console.fynchconsulting.com --token <publicId>.<secret> [--api-key sk-ant-...]
+```
+
+This runs your workspace's PRD-only setup AI calls when there is no repo yet. `run` then polls
+for workspace-level tasks in addition to any per-repo connections configured on this machine.
+
+**`--backend api-key`** (default) needs an Anthropic API key (get one free at
+console.anthropic.com) — either pass it inline with `--api-key sk-ant-...` (saved to this
+package's own local config file, `~/.product-console-companion/config.json`, permissions locked
+to your user only) or set `ANTHROPIC_API_KEY` in your environment yourself; the inline flag takes
+priority if both are present.
+
+**`--backend cli`** needs [Claude Code](https://claude.com/claude-code) installed and you logged
+into it first — `npm install -g @anthropic-ai/claude-code`, then run `claude` and follow the login
+prompt. `connect` checks `claude --version` up front and fails fast if it's missing. Bills against
+your Claude subscription, not a separate API key.
+
+Once it's running:
+
+```bash
+npx product-console-companion run
+```
+
+(this is what `connect` already ran for you, unless you passed `--no-run`) polls each configured
+connection every few seconds until Ctrl+C. Nothing runs while this isn't running — see the parent
+plan's Section 7 for why that's deliberate (goal 4: no AI spend while you're not around to
+notice).
+
+## What's NOT yet implemented (be aware before relying on this)
+
+- **Per-task budget is not enforced client-side for the `api-key` backend.** Every dispatched
+  task carries a `maxBudgetUsd` (visible in the `run` log line); `api-key-caller.ts` does not
+  track spend against it or abort a call that exceeds it. The `cli` backend passes it straight
+  through as `claude`'s own `--max-budget-usd`, which the CLI does enforce (confirmed
+  empirically: it stops and reports `terminal_reason: 'budget_exhausted'`).
+- **No wall-clock timeout for the `api-key` backend** — a hung request blocks that connection's
+  polling loop. The `cli` backend has one (10 minutes, independent of the budget cap — a dollar
+  ceiling doesn't stop a network-stall hang).
+- **Git-fetch-if-missing is `analyse_shipment`-only.** Every other task kind reads whatever HEAD
+  currently is in `--path` (or, for `cli`, a worktree pinned to that HEAD) — correct for those,
+  since they check the *current* state of your code, not a specific historical commit.
+  `analyse_shipment` is different: it's about one specific commit a webhook or the hosted poller
+  told the server about, which the server never fetches for you. It verifies that commit is
+  actually present locally first, attempts one `git fetch` (your own git credentials — never
+  anything from the hosted server) if it isn't, and reports back distinctly (`sha_not_local`)
+  rather than silently analysing the wrong tree state if it still can't find it.
+- **`cli` backend's sandbox worktree isolates writes, not reads** — `--add-dir` points at the
+  disposable worktree, so a read sees exactly what's committed at HEAD, including anything
+  `.gitignore`d being invisible (same as `git ls-files`'s own behavior). Uncommitted local
+  changes in your real checkout are never visible to the CLI backend — worth knowing if you're
+  expecting a check to see work-in-progress edits. (`analyse_shipment`'s own diff read is the one
+  exception: it happens against your real checkout, via `git show`, before the sandbox is even
+  created — the model itself still only ever sees the sandboxed copy.)
+
+## Local development (inside the parent repo)
+
+```bash
+cd companion
+npm install
+npm run dev -- connect --url http://localhost:3101 --token <publicId>.<secret> --connection <connectionId> --path <repo path> --backend api-key
+npm run dev -- run
+```
+
+## Publishing a new version
+
+Via GitHub Actions Trusted Publishing (`.github/workflows/publish-companion.yml`) — no npm token
+generated, pasted, or stored for this, ever. One-time setup on npmjs.com (already done as of this
+writing): on the `product-console-companion` package's own page, **Settings → Trusted
+publishing → GitHub Actions**, pointing at this repo (`fynchconsulting/product-console`) and this
+exact workflow filename (`publish-companion.yml`), no environment.
+
+To actually publish once that's configured: bump the version in `package.json` in a normal PR,
+merge it, then either
+
+```bash
+git tag companion-v<the new version> && git push --tags
+```
+
+or trigger the workflow manually (Actions tab, or `gh workflow run publish-companion.yml`). Either
+way it publishes whatever's currently in `package.json` at that point — there's no separate
+"which version" input to get wrong.

package/dist/api-key-caller.js

@@ -47,16 +47,16 @@ export async function runVerifyModuleTask(client, task, repoPath) {
     // Pass 1: which files implement this module? Reuses the module-spec text the server already
     // wrote into spec.volatileText (buildVerifyModuleTaskSpec) as context — it already contains
     // the full spec, so this doesn't need to re-derive it.
-    const selectPrompt = `${spec.volatileText}
-
-# The repository file tree (${allFiles.length} files)
-
-${allFiles.join('\n')}
-
-# Before judging
-
-First, list the file paths (verbatim from the tree above, up to ${MAX_CANDIDATE_FILES}) most
-likely to implement this module's behaviour. Prefer application source over tests, config, and
+    const selectPrompt = `${spec.volatileText}
+
+# The repository file tree (${allFiles.length} files)
+
+${allFiles.join('\n')}
+
+# Before judging
+
+First, list the file paths (verbatim from the tree above, up to ${MAX_CANDIDATE_FILES}) most
+likely to implement this module's behaviour. Prefer application source over tests, config, and
 generated files. Empty list if nothing plausibly implements it.`;
     const selectStream = client.messages.stream({
         model: spec.model,
@@ -160,19 +160,41 @@ export async function runGenerateSpecBatchTask(client, task, repoPath) {
     const payload = task.payload;
     const spec = payload.spec;
     const moduleIds = payload.moduleIds;
+    if (payload.connectionless) {
+        // The PRD is already in spec.stableText (stableTextForLocalDispatch); there is nothing local to read.
+        const content = [];
+        if (spec.stableText)
+            content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
+        content.push({ type: 'text', text: spec.volatileText });
+        const writeStream = client.messages.stream({
+            model: spec.model,
+            max_tokens: spec.maxTokens,
+            thinking: { type: 'adaptive' },
+            output_config: spec.schema ? { effort: spec.effort, format: { type: 'json_schema', schema: spec.schema } } : { effort: spec.effort },
+            system: spec.system,
+            messages: [{ role: 'user', content }],
+        });
+        const writeMsg = await writeStream.finalMessage();
+        if (writeMsg.stop_reason === 'refusal')
+            throw new Error('The model declined to write specs for this batch.');
+        const writeText = writeMsg.content.find((b) => b.type === 'text');
+        if (!writeText || writeText.type !== 'text')
+            throw new Error('No specs returned.');
+        return { result: JSON.parse(writeText.text), filesRead: [] };
+    }
     const allFiles = await listRepoFiles(repoPath);
     console.log(`  scanning ${allFiles.length} files in ${repoPath} for ${moduleIds.length} module(s)…`);
     // Pass 1: which files relate to each module in this batch?
-    const selectPrompt = `${spec.volatileText}
-
-# The repository file tree (${allFiles.length} files)
-
-${allFiles.join('\n')}
-
-# Before writing specs
-
-For EACH module above (by id: ${moduleIds.join(', ')}), list up to ${MAX_FILES_PER_MODULE_IN_BATCH}
-file paths (verbatim from the tree above) most likely to implement it. One entry per module id,
+    const selectPrompt = `${spec.volatileText}
+
+# The repository file tree (${allFiles.length} files)
+
+${allFiles.join('\n')}
+
+# Before writing specs
+
+For EACH module above (by id: ${moduleIds.join(', ')}), list up to ${MAX_FILES_PER_MODULE_IN_BATCH}
+file paths (verbatim from the tree above) most likely to implement it. One entry per module id,
 in the same order as given.`;
     const selectStream = client.messages.stream({
         model: spec.model,
@@ -236,31 +258,34 @@ in the same order as given.`;
  * server/index.ts's completeAiJob payloads for /api/setup/skeleton and
  * /api/module-suggestions/scan — neither includes it), so there's nothing meaningful to report.
  */
-async function runShallowRepoTask(client, spec, repoPath) {
-    const repoCtx = await buildLocalRepoContext(repoPath);
-    console.log(`  scanning ${repoCtx.fileList.length} files, README ${repoCtx.readme ? 'found' : 'not found'}, CHANGELOG ${repoCtx.changelog ? 'found' : 'not found'}, package.json ${repoCtx.packageJson ? 'found' : 'not found'}`);
-    const repoSection = `
-# Repository context (your local checkout)
-
-## File tree (${repoCtx.fileList.length} files)
-${repoCtx.fileList.join('\n')}
-
-## README
-${repoCtx.readme ?? '(none found)'}
-
-## CHANGELOG
-${repoCtx.changelog ?? '(none found)'}
-
-## package.json
-${repoCtx.packageJson ?? '(none found)'}
+async function runShallowRepoTask(client, spec, repoPath, connectionless = false) {
+    let repoSection = '';
+    if (!connectionless) {
+        const repoCtx = await buildLocalRepoContext(repoPath);
+        console.log(`  scanning ${repoCtx.fileList.length} files, README ${repoCtx.readme ? 'found' : 'not found'}, CHANGELOG ${repoCtx.changelog ? 'found' : 'not found'}, package.json ${repoCtx.packageJson ? 'found' : 'not found'}`);
+        repoSection = `
+# Repository context (your local checkout)
+
+## File tree (${repoCtx.fileList.length} files)
+${repoCtx.fileList.join('\n')}
+
+## README
+${repoCtx.readme ?? '(none found)'}
+
+## CHANGELOG
+${repoCtx.changelog ?? '(none found)'}
+
+## package.json
+${repoCtx.packageJson ?? '(none found)'}
 `.trim();
+    }
     const content = [];
     if (spec.stableDocumentBase64) {
         content.push({ type: 'document', source: { type: 'base64', media_type: 'application/pdf', data: spec.stableDocumentBase64 } });
     }
     if (spec.stableText)
         content.push({ type: 'text', text: spec.stableText, cache_control: { type: 'ephemeral' } });
-    content.push({ type: 'text', text: `${spec.volatileText}\n\n${repoSection}` });
+    content.push({ type: 'text', text: connectionless ? spec.volatileText : `${spec.volatileText}\n\n${repoSection}` });
     const stream = client.messages.stream({
         model: spec.model,
         max_tokens: spec.maxTokens,
@@ -279,7 +304,7 @@ ${repoCtx.packageJson ?? '(none found)'}
 }
 export async function runProposeSkeletonTask(client, task, repoPath) {
     const payload = task.payload;
-    return runShallowRepoTask(client, payload.spec, repoPath);
+    return runShallowRepoTask(client, payload.spec, repoPath, payload.connectionless);
 }
 export async function runProposeNewCapabilitiesTask(client, task, repoPath) {
     const payload = task.payload;

package/dist/cli.js

@@ -2,18 +2,27 @@
 import Anthropic from '@anthropic-ai/sdk';
 import spawn from 'cross-spawn';
 import { resolve } from 'node:path';
-import { addConnection, configPath, loadConfig } from './config.js';
+import { addConnection, configPath, enableWorkspacePolling, loadConfig } from './config.js';
 import { CompanionClient, CompanionHttpError } from './http-client.js';
 import { assertIsRepo, currentCommit } from './local-scan.js';
 import { runAnalyseShipmentTask, runDesignPromptTask, runGenerateSpecBatchTask, runProposeNewCapabilitiesTask, runProposeSkeletonTask, runVerifyModuleTask } from './api-key-caller.js';
 import { runAnalyseShipmentTaskViaCli, runDesignPromptTaskViaCli, runGenerateSpecBatchTaskViaCli, runProposeNewCapabilitiesTaskViaCli, runProposeSkeletonTaskViaCli, runVerifyModuleTaskViaCli } from './claude-cli-caller.js';
+/** A flag with nothing after it (end of argv, or the next token is itself another "--flag") is
+ *  treated as a bare boolean ("true") rather than swallowing the following flag as its value —
+ *  needed for --no-run below. Every existing "--flag value" pair still parses exactly as before. */
 function parseFlags(argv) {
     const flags = {};
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a?.startsWith('--')) {
-            flags[a.slice(2)] = argv[i + 1] ?? '';
-            i++;
+            const next = argv[i + 1];
+            if (next === undefined || next.startsWith('--')) {
+                flags[a.slice(2)] = 'true';
+            }
+            else {
+                flags[a.slice(2)] = next;
+                i++;
+            }
         }
     }
     return flags;
@@ -32,40 +41,84 @@ async function cmdConnect(argv) {
     const url = f.url?.replace(/\/+$/, '');
     const token = f.token;
     const connectionId = f.connection;
-    const repoPath = f.path ? resolve(f.path) : undefined;
-    const backend = (f.backend || 'api-key');
-    if (!url || !token || !connectionId || !repoPath) {
-        console.error('Usage: product-console-companion connect --url <origin> --token <publicId.secret> --connection <connectionId> --path <local repo path> [--backend api-key|cli]');
+    const apiKey = f['api-key'];
+    // Pairing on its own does nothing useful — see cmdRun below — so this defaults to starting
+    // right away, which is what someone following the app's own copy-pasted command wants: one
+    // paste, and it's working. --no-run is the escape hatch for pairing a second/third project
+    // before starting one shared `run` for all of them (see the README's own multi-connection note).
+    const shouldRunAfter = f['no-run'] !== 'true';
+    if (!url || !token) {
+        console.error('Usage: product-console-companion connect --url <your Console link> --token <publicId.secret> --connection <connectionId> ' +
+            '[--path <folder — defaults to the folder you\'re in right now>] [--backend api-key|cli] [--api-key <your Anthropic key>] [--no-run]\n' +
+            '   or: product-console-companion connect --url <your Console link> --token <publicId.secret> [--api-key <your Anthropic key>] [--no-run]');
         process.exitCode = 1;
         return;
     }
+    if (!connectionId) {
+        const client = new CompanionClient(url, token);
+        try {
+            await client.whoami();
+        }
+        catch (err) {
+            console.error(`Hmm, that didn't work — could not verify your token against ${url}. Double check you copied the ` +
+                `WHOLE thing, including the part after the dot.`, err instanceof Error ? err.message : err);
+            process.exitCode = 1;
+            return;
+        }
+        enableWorkspacePolling({ url, token, apiKey });
+        console.log(`Connected! This computer will now run AI calls for this workspace's setup (PRD-only) tasks. (Saved to ${configPath}.)`);
+        if (!shouldRunAfter) {
+            console.log('Run "product-console-companion run" whenever you\'re ready to start.');
+            return;
+        }
+        console.log('Starting now — Ctrl+C any time to stop.\n');
+        await cmdRun();
+        return;
+    }
+    // --path is optional — defaults to wherever this command is actually run from, so "open a
+    // terminal in your project's folder, paste this" just works without typing a path at all.
+    const repoPath = resolve(f.path || '.');
+    const backend = (f.backend || 'api-key');
     if (backend !== 'api-key' && backend !== 'cli') {
         console.error(`--backend must be "api-key" or "cli", got "${backend}"`);
         process.exitCode = 1;
         return;
     }
-    await assertIsRepo(repoPath);
+    try {
+        await assertIsRepo(repoPath);
+    }
+    catch (err) {
+        console.error((err instanceof Error ? err.message : String(err)) + ' Run this from inside your project\'s folder, or pass --path <folder>.');
+        process.exitCode = 1;
+        return;
+    }
     if (backend === 'cli') {
         const version = await checkClaudeCliAvailable();
         if (!version) {
-            console.error('--backend cli needs the `claude` CLI on PATH and authenticated — install it first: npm install -g @anthropic-ai/claude-code');
+            console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
             process.exitCode = 1;
             return;
         }
-        console.log(`Found claude CLI: ${version}`);
+        console.log(`Found Claude Code: ${version}`);
     }
     const client = new CompanionClient(url, token);
     try {
         await client.whoami();
     }
     catch (err) {
-        console.error(`Could not validate that token against ${url}:`, err instanceof Error ? err.message : err);
+        console.error(`Hmm, that didn't work — could not verify your token against ${url}. Double check you copied the ` +
+            `WHOLE thing, including the part after the dot.`, err instanceof Error ? err.message : err);
         process.exitCode = 1;
         return;
     }
-    addConnection({ url, token, connection: { connectionId, repoPath, backend } });
-    console.log(`Paired (backend: ${backend}). Saved to ${configPath}.`);
-    console.log(`Run "product-console-companion run" to start serving tasks for this (and any other configured) connection.`);
+    addConnection({ url, token, connection: { connectionId, repoPath, backend }, apiKey });
+    console.log(`Connected! This computer will now read this project's code and run AI calls for it. (Saved to ${configPath}.)`);
+    if (!shouldRunAfter) {
+        console.log('Run "product-console-companion run" whenever you\'re ready to start.');
+        return;
+    }
+    console.log('Starting now — Ctrl+C any time to stop.\n');
+    await cmdRun();
 }
 /** How often an idle connection is re-polled when nothing was claimed — a short client-side
  *  poll, not a server-held long-poll (see the plan's own reasoning: this app has already been
@@ -78,23 +131,29 @@ const HEARTBEAT_MS = 30_000;
  *  each backed by both backends. Grows by one entry per phase, same as the server's own registry
  *  (server/companion.ts's TASK_RESULT_SCHEMAS) — the two lists should always name the same kinds. */
 async function runTask(task, backend, anthropic, repoPath) {
+    const connectionless = task.payload.connectionless === true;
+    const effectiveBackend = connectionless ? 'api-key' : backend;
+    if (connectionless && !anthropic) {
+        throw new Error('This is a connection-less (PRD-only) task, which needs an Anthropic API key. Re-run ' +
+            '`connect` with --api-key <key>, or set ANTHROPIC_API_KEY.');
+    }
     if (task.kind === 'verify_module') {
-        return backend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
+        return effectiveBackend === 'cli' ? runVerifyModuleTaskViaCli(task, repoPath) : runVerifyModuleTask(anthropic, task, repoPath); // anthropic is always set for backend 'api-key' — see cmdRun
     }
     if (task.kind === 'generate_spec_batch') {
-        return backend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runGenerateSpecBatchTaskViaCli(task, repoPath) : runGenerateSpecBatchTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_skeleton') {
-        return backend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runProposeSkeletonTaskViaCli(task, repoPath) : runProposeSkeletonTask(anthropic, task, repoPath);
     }
     if (task.kind === 'propose_new_capabilities') {
-        return backend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runProposeNewCapabilitiesTaskViaCli(task, repoPath) : runProposeNewCapabilitiesTask(anthropic, task, repoPath);
     }
     if (task.kind === 'design_prompt') {
-        return backend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runDesignPromptTaskViaCli(task, repoPath) : runDesignPromptTask(anthropic, task, repoPath);
     }
     if (task.kind === 'analyse_shipment') {
-        return backend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
+        return effectiveBackend === 'cli' ? runAnalyseShipmentTaskViaCli(task, repoPath) : runAnalyseShipmentTask(anthropic, task, repoPath);
     }
     throw new Error(`This companion doesn't know how to run task kind "${task.kind}" yet.`);
 }
@@ -124,43 +183,56 @@ async function runOneTask(anthropic, backend, client, repoPath, task) {
 }
 async function cmdRun() {
     const config = loadConfig();
-    if (!config || config.connections.length === 0) {
-        console.error(`No connections configured — ${configPath} is missing or empty. Run "connect" first.`);
+    if (!config || (config.connections.length === 0 && !config.pollWorkspaceTasks)) {
+        console.error(`Nothing set up yet — ${configPath} is missing or empty. Run "connect" first.`);
         process.exitCode = 1;
         return;
     }
-    // Backends are per-connection (chosen at `connect` time) — only require what's actually
-    // configured to run, not every prerequisite either backend could ever need.
-    const needsApiKey = config.connections.some((c) => c.backend !== 'cli');
+    // Repo backends are chosen per connection; workspace-level tasks always use api-key. Only
+    // require what's actually configured to run, not every prerequisite either backend could need.
+    const needsApiKey = config.pollWorkspaceTasks || config.connections.some((c) => c.backend !== 'cli');
     const needsCli = config.connections.some((c) => c.backend === 'cli');
-    const apiKey = process.env.ANTHROPIC_API_KEY;
+    // config.apiKey (set via `connect --api-key ...`) takes priority over the environment variable
+    // — the easier path for someone who'd rather paste their key once into a command than learn
+    // what an environment variable is and how to set one on their OS. Both are supported; neither
+    // is required unless a configured connection actually needs it.
+    const apiKey = config.apiKey || process.env.ANTHROPIC_API_KEY;
     if (needsApiKey && !apiKey) {
-        console.error('ANTHROPIC_API_KEY is not set — the api-key backend calls the model directly with your own key. Get one at console.anthropic.com and set it in your environment.');
+        console.error('No Anthropic API key found. Get one free at console.anthropic.com, then either run ' +
+            '"connect" again adding --api-key <your key>, or set it yourself: ' +
+            '"set ANTHROPIC_API_KEY=<your key>" (Windows) / "export ANTHROPIC_API_KEY=<your key>" (Mac/Linux), then run "run" again.');
         process.exitCode = 1;
         return;
     }
     if (needsCli) {
         const version = await checkClaudeCliAvailable();
         if (!version) {
-            console.error('The cli backend needs the `claude` CLI on PATH and authenticated — install it first: npm install -g @anthropic-ai/claude-code');
+            console.error('This needs Claude Code installed and you logged into it first: npm install -g @anthropic-ai/claude-code, then run `claude` and follow the login prompt.');
             process.exitCode = 1;
             return;
         }
     }
     for (const c of config.connections) {
         await assertIsRepo(c.repoPath).catch((err) => {
-            console.error(`Warning: ${c.connectionId} → ${c.repoPath}:`, err instanceof Error ? err.message : err);
+            console.error(`Warning: can't find ${c.connectionId}'s project folder (${c.repoPath}):`, err instanceof Error ? err.message : err);
         });
     }
     const anthropic = needsApiKey ? new Anthropic({ apiKey }) : null;
     const client = new CompanionClient(config.url, config.token);
     await client.whoami();
-    console.log(`Connected to ${config.url}. Serving ${config.connections.length} connection${config.connections.length === 1 ? '' : 's'}:`);
+    const projectCount = config.connections.length;
+    const watching = config.pollWorkspaceTasks
+        ? `${projectCount > 0 ? `${projectCount} project${projectCount === 1 ? '' : 's'} and ` : ''}workspace-level tasks`
+        : `${projectCount} project${projectCount === 1 ? '' : 's'}`;
+    console.log(`Connected to ${config.url}. Watching ${watching}:`);
     for (const c of config.connections) {
         const sha = await currentCommit(c.repoPath).catch(() => '(unknown)');
         console.log(`  - ${c.connectionId} → ${c.repoPath} @ ${sha.slice(0, 7)} (${c.backend})`);
     }
-    console.log('Polling for tasks — Ctrl+C to stop.');
+    if (config.pollWorkspaceTasks) {
+        console.log('  - workspace-level (connection-less / PRD-only) tasks');
+    }
+    console.log('Waiting for work — leave this running. Ctrl+C any time to stop.');
     let stopping = false;
     process.on('SIGINT', () => {
         if (stopping)
@@ -190,6 +262,25 @@ async function cmdRun() {
             claimedAny = true;
             await runOneTask(anthropic, c.backend, client, c.repoPath, claim.task);
         }
+        if (!stopping && config.pollWorkspaceTasks) {
+            let claim;
+            try {
+                claim = await client.claimNext();
+            }
+            catch (err) {
+                if (err instanceof CompanionHttpError && err.status === 401) {
+                    console.error('Token rejected (revoked?) — stopping. Pair a new token and reconnect.');
+                    return;
+                }
+                console.error('Workspace-level poll failed:', err instanceof Error ? err.message : err);
+                claim = { task: null };
+            }
+            if (claim.task) {
+                claimedAny = true;
+                // Connection-less task kinds do not read a repo; cwd is a harmless placeholder.
+                await runOneTask(anthropic, 'api-key', client, process.cwd(), claim.task);
+            }
+        }
         if (!claimedAny && !stopping)
             await new Promise((r) => setTimeout(r, IDLE_POLL_MS));
     }

package/dist/config.js

@@ -20,12 +20,35 @@ function save(config) {
 }
 /** Adds (or replaces, if this exact connectionId is already configured) one connection —
  *  url/token are shared across every connection this companion serves; only mismatched values
- *  overwrite them, so re-running `connect` for a second repo with the SAME url/token is additive. */
+ *  overwrite them, so re-running `connect` for a second repo with the SAME url/token is additive.
+ *  apiKey works the same way: passing one saves/updates it; omitting it on a later `connect`
+ *  call leaves whatever was already saved untouched, rather than blowing it away. */
 export function addConnection(args) {
     const existing = loadConfig();
     const connections = (existing?.connections ?? []).filter((c) => c.connectionId !== args.connection.connectionId);
     connections.push(args.connection);
-    const config = { url: args.url, token: args.token, connections };
+    const config = {
+        url: args.url,
+        token: args.token,
+        connections,
+        apiKey: args.apiKey || existing?.apiKey,
+        pollWorkspaceTasks: existing?.pollWorkspaceTasks,
+    };
+    save(config);
+    return config;
+}
+/** Records that this companion should also poll for workspace-level (connection-less) tasks.
+ *  Additive: keeps any existing connections and apiKey; only sets url/token if not already set
+ *  (or if they differ — same rule as addConnection). */
+export function enableWorkspacePolling(args) {
+    const existing = loadConfig();
+    const config = {
+        url: args.url,
+        token: args.token,
+        connections: existing?.connections ?? [],
+        apiKey: args.apiKey || existing?.apiKey,
+        pollWorkspaceTasks: true,
+    };
     save(config);
     return config;
 }

package/dist/http-client.js

@@ -26,7 +26,7 @@ export class CompanionClient {
         return this.call('/api/companion/whoami');
     }
     claimNext(connectionId) {
-        return this.call(`/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}`);
+        return this.call(connectionId ? `/api/companion/tasks/next?connectionId=${encodeURIComponent(connectionId)}` : '/api/companion/tasks/next');
     }
     heartbeat(taskId) {
         return this.call(`/api/companion/tasks/${encodeURIComponent(taskId)}/heartbeat`, { method: 'POST' });

package/package.json

@@ -1,46 +1,46 @@
-{
-  "name": "product-console-companion",
-  "version": "0.1.0",
-  "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
-  "type": "module",
-  "license": "MIT",
-  "bin": {
-    "product-console-companion": "dist/cli.js"
-  },
-  "files": [
-    "dist"
-  ],
-  "scripts": {
-    "build": "tsc -b",
-    "dev": "tsx src/cli.ts"
-  },
-  "keywords": [
-    "cli",
-    "ai",
-    "anthropic",
-    "claude",
-    "companion",
-    "byok",
-    "byos",
-    "product-console"
-  ],
-  "homepage": "https://console.fynchconsulting.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/fynchconsulting/product-console.git",
-    "directory": "companion"
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.111.0",
-    "cross-spawn": "^7.0.6"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^24.10.1",
-    "tsx": "^4.20.6",
-    "typescript": "^5.9.3"
-  },
-  "engines": {
-    "node": ">=20"
-  }
-}
+{
+  "name": "product-console-companion",
+  "version": "0.3.0",
+  "description": "Local-first BYOS companion for the Fynch Product Console — reads code and runs AI calls from your own machine instead of the hosted server.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "product-console-companion": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "tsx src/cli.ts"
+  },
+  "keywords": [
+    "cli",
+    "ai",
+    "anthropic",
+    "claude",
+    "companion",
+    "byok",
+    "byos",
+    "product-console"
+  ],
+  "homepage": "https://console.fynchconsulting.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fynchconsulting/product-console.git",
+    "directory": "companion"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.111.0",
+    "cross-spawn": "^7.0.6"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^24.10.1",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}