kushi-agents 4.4.3 → 4.4.4

package/README.md

@@ -79,6 +79,7 @@ The Evidence/ folder produced by every profile is a **stable public contract**
 
 | Verb | Profile | Window | What it does |
 |------|---------|--------|--------------|
+| `setup` | core+ | n/a | Functionally verify WorkIQ is reachable + auto-fill contributor identity. Idempotent. Run once per machine before first `bootstrap`/`refresh`. |
 | `aggregate` | core+ | last watermark → now | Pull every enabled source + consolidate. **No State/ rebuild.** |
 | `bootstrap` | standard+ | 30 days (default) | First-time setup — scaffold folders, lay configs side-by-side, initial pull. Profile-aware (builds State only on `full`). |
 | `refresh` | standard+ | last watermark → now | Pull only what changed. Profile-aware (rebuilds State only on `full`). |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kushi-agents",
-  "version": "4.4.3",
+  "version": "4.4.4",
   "description": "Install Kushi — multi-source project evidence agent with snapshot+stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic.",
   "type": "module",
   "bin": {

package/plugin/agents/kushi.agent.md

@@ -16,7 +16,7 @@ Kushi ships in three profiles. The installed profile is recorded in `kushi-insta
 
 | Profile | What's installed | Verbs available |
 |---|---|---|
-| `core` | Aggregator only: `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `self-check`, `intro` | `aggregate`, `consolidate`, `status`, `pull`, `ask` |
+| `core` | Aggregator only: `setup`, `pull-*`, `consolidate-evidence`, `aggregate-project`, `ask-project`, `project-status`, `self-check`, `intro` | `setup`, `aggregate`, `consolidate`, `status`, `pull`, `ask` |
 | `standard` *(default)* | core + `bootstrap-project`, `refresh-project`, `fde-intake`, `fde-report`, `fde-triage` + FDE reference pack | core + `bootstrap`, `refresh`, `fde-intake`, `fde-report`, `fde-triage` |
 | `full` | standard + `build-state` | standard + `state` |
 | **`preview`** *(opt-in)* | standard + `propose-ado-update`, `apply-ado-update` | standard + `propose-ado`, `apply-ado` |
@@ -29,6 +29,7 @@ The Evidence/ folder produced by `aggregate` is the **public contract** between
 
 | Verb | Profile | Default window | Calls (in order) |
 |---|---|---|---|
+| `@Kushi setup` | core+ | n/a (read-only) | `setup` — functional WorkIQ ping + identity auto-fill. Idempotent; safe to re-run. Required before first bootstrap/refresh. |
 | `@Kushi aggregate <project>` | core+ | since last watermark | `aggregate-project` → `pull-*` (all enabled) → `consolidate-evidence`. **No build-state.** |
 | `@Kushi aggregate <project> last N days` / `since <date>` / `<from>..<to>` | core+ | as supplied | same |
 | `@Kushi bootstrap <project>` | standard+ | last 30 days | `bootstrap-project` → `pull-*` → `consolidate-evidence` → (full only) `build-state` |
@@ -85,8 +86,9 @@ See `instructions/snapshot-vs-stream.instructions.md` for the full rule.
 
 When a user message arrives:
 
-1. Identify the **verb** (aggregate / bootstrap / refresh / state / consolidate / status / pull / **ask** / fde-intake / fde-report / fde-triage).
+1. Identify the **verb** (setup / aggregate / bootstrap / refresh / state / consolidate / status / pull / **ask** / fde-intake / fde-report / fde-triage).
    - If the message starts with an explicit producer verb → use it.
+   - **setup** dispatches immediately on `setup`, `verify workiq`, `who am I to kushi`, `fix my install`, `setup kushi`.
    - Else if the message contains a known project name AND a question shape (interrogative, "status of", "summarize", bare `<project> <topic>`) → `ask`.
    - Else → ask the user to clarify.
 2. **Profile check**: confirm the chosen verb is listed in `kushi-install.json#verbs`. If not, surface: *"Verb `<verb>` requires the `<profile>` profile. Re-install with `npx kushi-agents --clawpilot --profile <profile> --force`."* and stop.

package/plugin/instructions/workiq-only.instructions.md

@@ -48,7 +48,7 @@ For every M365 source in scope:
 
 ## Canonical WorkIQ commands (CODIFIED — do not re-discover)
 
-The CLI is at `<USER_HOME>\.kushi\bin\workiq.cmd` (resolved from `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path`; fall back to PATH; fall back to `~/.kushi/bin/workiq.cmd`).
+The CLI is resolved in this order: `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path` → `Get-Command workiq` (PATH) → `~/.copilot/bin/workiq[.cmd]` (Clawpilot-managed convenience fallback, probed only if it already exists). The legacy `~/.kushi/bin/workiq.cmd` path was removed in v4.4.4 — see the `setup` skill for the functional verification flow.
 
 Invocation shape:
 
@@ -153,7 +153,7 @@ List my Teams meetings between <YYYY-MM-DD> and <YYYY-MM-DD> where the subject c
 
 Before the first WorkIQ query in a run:
 
-1. Resolve CLI path: `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path` → `Get-Command workiq` → `~/.kushi/bin/workiq.cmd`. If none resolves → log `workiq-not-on-path`, write evidence file pointing at install docs, STOP this source.
+1. Resolve CLI path: `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path` → `Get-Command workiq` → `~/.copilot/bin/workiq[.cmd]` (Clawpilot-managed, only if present). If none resolves → log `workiq-not-on-path`, write evidence file pointing at install docs, STOP this source. The legacy `~/.kushi/bin/workiq.cmd` probe was removed in v4.4.4; the `setup` skill handles the recovery flow.
 2. Probe with `workiq ask -q "ping"`. If EULA prompt → `workiq accept-eula` once, retry.
 3. Capture `--version` once into run-log for audit.
 

package/plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kushi",
   "description": "Multi-source project evidence + Q&A agent. Snapshot + stream capture across Email, Teams, OneNote, SharePoint, Meetings, CRM, ADO; plus read-only natural-language Q&A over the captured evidence. WorkIQ-only for M365 sources (Graph / m365_* FORBIDDEN as fallbacks; user-paste is first-class). Host-agnostic. Three install profiles: core (aggregator only), standard (default — adds bootstrap/refresh + FDE authoring), full (adds State/ rollup).",
-  "version": "3.12.1",
+  "version": "3.12.2",
   "author": "ushakrishnan",
   "repository": "https://github.com/gim-home/kushi",
   "default_profile": "standard",
@@ -11,6 +11,7 @@
       "skills": [
         "intro",
         "self-check",
+        "setup",
         "pull-email",
         "pull-teams",
         "pull-meetings",
@@ -24,6 +25,7 @@
         "ask-project"
       ],
       "prompts": [
+        "setup",
         "aggregate",
         "consolidate",
         "status",
@@ -36,6 +38,7 @@
       ],
       "reference_packs": [],
       "verbs": [
+        "setup",
         "aggregate",
         "consolidate",
         "status",

package/plugin/prompts/setup.prompt.md

@@ -0,0 +1,29 @@
+---
+name: setup
+description: "Functionally verify WorkIQ is reachable + auto-fill contributor identity into project-evidence.yml. Run once per machine; idempotent."
+argument-hint: "(no args) — pings WorkIQ, captures identity, persists to ~/.kushi config"
+agent: kushi
+tools: [search, read/readFile, edit, agent]
+---
+
+## User Input
+
+```text
+(none)
+```
+
+# /setup
+
+Route to `@Kushi setup`.
+
+Runs the **setup** skill:
+
+1. Resolves the workiq CLI path (pinned `cli_path` → PATH → Clawpilot-managed `~/.copilot/bin/workiq` fallback). **No `~/.kushi/bin/` filesystem probe** (removed in v4.4.4).
+2. Functionally verifies WorkIQ by sending: *"Who am I? Return UPN, displayName, mailNickname as JSON."*
+3. Parses the response and writes `identity` (alias / display_name / email) into `<workspace>/.kushi/config/user/project-evidence.yml`, preserving comments.
+4. On failure, walks the user through install / sign-in / retry using `ask_user` (no outbound sends).
+5. Prints a green status table summarizing host, cli_path, identity, and persistence target.
+
+**Idempotent.** Re-running on a healthy machine re-verifies the connection and exits cleanly — bootstrap / refresh are blocked until this skill records `identity_status: verified`.
+
+Delegates to `setup` skill.

package/plugin/skills/bootstrap-project/SKILL.md

@@ -61,11 +61,7 @@ Hard stop if WorkIQ returns auth error or empty — print the WorkIQ sign-in hin
 Verify in order. Stop on hard failures.
 
 1. **OS + host runtime** — display OS + Node/PowerShell version. Informational.
-2. **WorkIQ install (REQUIRED, hard stop)** — read `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path`. If missing, probe known paths:
-   - `$HOME\.kushi\bin\workiq.cmd`
-   - `$env:LOCALAPPDATA\Programs\WorkIQ\workiq.cmd`
-   - `$env:ProgramFiles\WorkIQ\workiq.cmd`
-   If found, persist path. If not found, ask user for path (or to install). Test with `<workiq.cli_path> --help`. Without WorkIQ, M365 sources will all fail — STOP.
+2. **WorkIQ install (REQUIRED, hard stop)** — read `<workspace>/.kushi/config/user/project-evidence.yml workiq.cli_path`. If missing, dispatch the `setup` skill (which does a functional `workiq ask -q "Who am I?"` check, captures identity, and walks the user through install/sign-in on failure). **Do NOT probe `$HOME\.kushi\bin\` — removed in v4.4.4** because it triggered VS Code's "Allow reading external directory?" prompt even on machines where workiq was already on PATH. If `setup` returns `identity_status: skipped-*`, STOP — bootstrap is blocked until WorkIQ is reachable.
 3. **Conditional az login** — only if `<workspace>/.kushi/config/shared/integrations.yml` OR `<workspace>/.kushi/config/shared/integrations.yml` exists. Per `az-auth-conditional.instructions.md`. Soft warning on failure, never blocking.
 4. **Engagement-root resolution** — per `engagement-root-resolution.instructions.md`. Persist to `<workspace>/.kushi/config/user/project-evidence.yml engagement_root` if newly resolved.
 

package/plugin/skills/setup/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: "setup"
+version: "1.0.0"
+description: "First-run machine setup for Kushi. Functionally verifies WorkIQ is reachable by sending a real query, captures contributor identity (alias / display_name / email) from the response, persists it to `<workspace>/.kushi/config/user/project-evidence.yml`, and walks the user through workiq install/start if it is not running. Idempotent — re-running on a healthy machine prints a green status table and exits. Modeled on the wss-cto-write-connect `setup.agent.md` Step 6 pattern: ping the service, ask the user nothing the service can already answer."
+---
+
+# Skill: setup
+
+> **Doctrine**: WorkIQ is a **service**, not a binary on disk. This skill probes it functionally (sends a real query) instead of probing the filesystem. Avoids the v3.x `~/.kushi/bin/` external-directory prompt and the dead-config UX where `<auto>` placeholders surface to the user.
+>
+> **No outbound messages.** This skill never sends Teams / email / RSVP. Identity capture only writes the local YAML.
+>
+> **Idempotent.** Re-running on a machine where everything is healthy prints the green status table and exits cleanly. Safe to wire into `bootstrap-project` Step 1.
+
+Run this skill when:
+
+- The user says `setup`, `kushi setup`, `verify workiq`, `who am I to kushi`, `fix my install`, `setup kushi`.
+- The installer finished and printed `Run \`setup\` once to verify WorkIQ + auto-fill identity`.
+- A `pull-*` or `bootstrap-project` skill is about to fire its first WorkIQ query in a workspace whose `project-evidence.yml#identity` is still `<auto>` / missing.
+
+## What it does
+
+1. Detects the host runtime + workiq.cli_path (no filesystem probes beyond an explicit `cli_path`).
+2. **Functionally verifies WorkIQ** by sending one query: *"Who am I? Return UPN, displayName, mailNickname as JSON."*
+3. On success, persists the captured identity to `<workspace>/.kushi/config/user/project-evidence.yml#identity` (preserving comments + other keys).
+4. On failure, walks the user through starting WorkIQ via the host's documented entry point, then retries.
+5. Prints a final status table the user can screenshot to file with IT support.
+
+## Inputs
+
+None. The skill discovers everything it needs.
+
+Optional flags surfaced by the user:
+- `non-interactive` / `--yes` — skip `ask_user` retries on failure; emit a single actionable error and exit.
+- `verbose` — print every probe step + raw workiq response.
+
+## Steps
+
+### Step 1 — Detect host runtime (informational)
+
+Run `node --version`, `pwsh --version` (or `powershell -Command "$PSVersionTable.PSVersion"`), and capture the platform (`win32` / `darwin` / `linux`). Display:
+
+```
+🔍 Host: <platform> · Node <ver> · PowerShell <ver>
+```
+
+Never blocking. Used only for the final status table.
+
+### Step 2 — Resolve workiq CLI path (NO filesystem probe beyond explicit cli_path)
+
+Resolution order (FIRST match wins):
+
+1. **Explicit pin** — read `<workspace>/.kushi/config/user/project-evidence.yml#workiq.cli_path`. If present and the file exists on disk, use it.
+2. **PATH lookup** — run `Get-Command workiq -ErrorAction SilentlyContinue` (Windows) / `command -v workiq` (Unix). If a result is returned, use the first executable hit.
+3. **Host integration** — if the host is Clawpilot and `~/.copilot/bin/workiq[.cmd]` exists (this is the Clawpilot-managed location, not a kushi-managed location), use it as a final convenience fallback. **Do NOT probe `~/.kushi/bin/` — that path is removed from kushi doctrine as of v4.4.4.**
+
+If none of the three resolves, jump to **Step 4 — Recovery prompt** with reason `cli-not-resolved`.
+
+### Step 3 — Functional verification (the actual check)
+
+Send this exact query (PowerShell shape — adapt single-quoting for bash):
+
+```powershell
+& "<resolved-cli-path>" ask -q 'Who am I? Return UPN, displayName, mailNickname strictly as a single JSON object with keys upn, displayName, mailNickname. No prose, no markdown fences.' 2>&1
+```
+
+Timeout: 30 seconds. Capture both stdout and stderr.
+
+**Parse the response.** Look for a JSON object containing all three keys. Strip any leading `request-id:` line that WorkIQ prepends. If WorkIQ wrapped the JSON in markdown fences (```json ... ```), strip them.
+
+| Outcome | Next |
+|---|---|
+| Valid JSON with non-empty `upn`, `displayName`, `mailNickname` | Go to Step 5 (persist identity) |
+| WorkIQ returned a summary / refusal / empty | Retry ONCE with stricter prompt: *"Output ONLY the JSON object, nothing else. Do not narrate, do not explain. {upn, displayName, mailNickname}."* If still no JSON, jump to Step 4 with reason `workiq-no-identity`. |
+| Process timed out | Step 4 with reason `workiq-timeout` |
+| Non-zero exit (auth error, ENOENT, etc.) | Step 4 with reason `workiq-exit-<code>` |
+
+### Step 4 — Recovery prompt (only on Step-2 or Step-3 failure)
+
+Display the platform-appropriate install/start block. Use `ask_user` to drive the recovery loop.
+
+**Recovery messages by reason:**
+
+```
+cli-not-resolved (Windows)
+⚙️  WorkIQ CLI not found.
+
+Kushi could not locate the workiq executable in:
+  - <workspace>/.kushi/config/user/project-evidence.yml#workiq.cli_path  (unset or path missing)
+  - the system PATH                                                       (no `workiq` on PATH)
+  - ~/.copilot/bin/workiq.cmd                                             (Clawpilot-managed fallback; not present)
+
+To install / start WorkIQ:
+  1. Open a NEW terminal window (keep this one open).
+  2. Run:  winget install Microsoft.WorkIQ
+     (macOS:  brew install --cask microsoft-workiq)
+  3. After install completes, run:  workiq accept-eula
+  4. Then run:  workiq ask -q "ping"   — should print a non-empty response.
+  5. Come back to this window when done.
+```
+
+```
+workiq-no-identity / workiq-timeout / workiq-exit-*
+⚙️  WorkIQ is installed but did not respond to the identity query.
+
+Likely causes (in priority order):
+  1. Not signed in. Run:           workiq ask -q "ping"
+                                   (You'll be prompted to sign in on first call.)
+  2. Off-corpnet / VPN required.   Reconnect and retry.
+  3. WorkIQ daemon not running.    (Host-specific. Clawpilot users: restart Clawpilot.
+                                   VS Code Chat users: restart the workiq host process.)
+  4. Tenant misconfiguration.      Check the configured tenant in your WorkIQ profile.
+
+When ready, type 'retry' below.
+```
+
+`ask_user` choices:
+
+- `retry` — re-run Step 3.
+- `change-path` — prompt for an absolute path. Validate the file exists, persist to `project-evidence.yml#workiq.cli_path`, then re-run Step 2 → Step 3.
+- `skip` — write a stub identity (`alias: 'unknown'`, `display_name: '(WorkIQ unreachable)'`, `email: 'unknown@unknown'`) AND mark `<workspace>/.kushi/config/user/project-evidence.yml#identity_status: "skipped-workiq-down"`. **bootstrap / refresh MUST refuse to run while `identity_status: skipped-*` is set**, surfacing "Run `setup` first" as the gate.
+
+Recovery loop budget: **3 retries**. After the third failure, force `skip` mode and exit cleanly. Never crash — the user still has read-only verbs available.
+
+### Step 5 — Persist identity (success path)
+
+Open `<workspace>/.kushi/config/user/project-evidence.yml`. If the file does not exist, create it from `templates/init/project-evidence.template.yml`. Update the `identity:` block in place (preserve every other key + every comment) using a YAML-comment-safe rewrite. Map:
+
+| WorkIQ field | YAML field | Notes |
+|---|---|---|
+| `upn` | `identity.email` | Verbatim. |
+| `displayName` | `identity.display_name` | Verbatim. |
+| `mailNickname` | `identity.alias` | Lowercase. Fallback to `email.split('@')[0]` if missing. |
+
+Also write:
+
+- `identity_status: "verified"` (so bootstrap/refresh stop pestering)
+- `identity_verified_at: "<ISO-8601 UTC>"`
+- `workiq.cli_path: "<resolved-path>"` (only if it was discovered via PATH or host-integration and not yet pinned)
+
+### Step 6 — Print status table
+
+```
+WorkIQ Setup Complete
+─────────────────────
+  ✅ Host:           win32 · Node v22.x · PowerShell 7.x
+  ✅ workiq.cli_path C:\Users\<you>\.copilot\bin\workiq.cmd
+  ✅ Identity        Usha Krishnan <ushak@microsoft.com> (alias=ushak)
+  ✅ Persisted to    <workspace>/.kushi/config/user/project-evidence.yml
+
+Next:   kushi bootstrap <project>      to bootstrap a project
+        kushi refresh   <project>      to refresh evidence
+```
+
+If recovery ended in `skip`, change the trailing lines to:
+
+```
+  ⚠️  WorkIQ unreachable. Identity not verified.
+       Re-run `setup` once WorkIQ is running. bootstrap / refresh are blocked
+       until then; `ask`, `status`, and Q&A verbs remain available.
+```
+
+## Notes
+
+- This skill writes ONLY to `<workspace>/.kushi/config/user/project-evidence.yml`. It does NOT touch `shared/integrations.yml` (team-owned) or any project-level file.
+- The functional check replaces the pre-v4.4.4 filesystem-probe pattern in `check-workiq.mjs` + `bootstrap-project SKILL.md` Step 1.2. Those still ship for backwards-compat at install time but are no longer the source of truth for "is WorkIQ healthy."
+- See `instructions/identity-resolution.instructions.md` for the contract this skill implements.
+
+## References
+
+- `instructions/workiq-only.instructions.md` — WorkIQ-only doctrine for M365 sources.
+- `instructions/identity-resolution.instructions.md` — contributor identity contract.
+- `instructions/communication-guidelines.instructions.md` — chat-reply tone for the recovery prompts.
+- `instructions/status-taxonomy.instructions.md` — `identity_status` value vocabulary.

package/plugin/templates/init/project-evidence.template.yml

@@ -42,7 +42,11 @@ active_projects:
 # (Optional) Path to the WorkIQ CLI. If omitted, Kushi resolves in this order:
 #   1. this `cli_path` value
 #   2. `workiq` on PATH
-#   3. ~/.kushi/bin/workiq.cmd  (Windows) / ~/.kushi/bin/workiq  (Linux/macOS)
+#   3. ~/.copilot/bin/workiq[.cmd]  (Clawpilot-managed convenience fallback —
+#      probed ONLY if it already exists; never created by kushi)
+# The legacy ~/.kushi/bin/ path is no longer probed (removed in v4.4.4 to avoid
+# the VS Code "Allow reading external directory?" prompt). Run the `setup` skill
+# to functionally verify WorkIQ is reachable and auto-fill your identity.
 # workiq:
-#   cli_path: 'C:\Users\<you>\.kushi\bin\workiq.cmd'
+#   cli_path: 'C:\Program Files\WorkIQ\workiq.cmd'
 

package/src/check-workiq.mjs

@@ -6,10 +6,17 @@ import os from 'node:os';
 /**
  * Probe for a working WorkIQ install.
  *
- * Resolution order:
+ * Resolution order (NO kushi-owned filesystem probe — see v4.4.4 doctrine):
  *   1. explicit absolute path supplied via --workiq-path / opts.workiqPath
  *   2. `workiq` on PATH (via `where` on Windows, `command -v` elsewhere)
- *   3. Kushi-managed bin: ~/.kushi/bin/workiq.cmd (Win) or ~/.kushi/bin/workiq
+ *   3. Clawpilot-managed convenience fallback: ~/.copilot/bin/workiq[.cmd]
+ *      (only probed when it ALREADY exists — never created, never assumed)
+ *
+ * The old `~/.kushi/bin/workiq.cmd` probe was removed in v4.4.4: it caused
+ * VS Code to surface an "Allow reading external directory?" prompt for `bin`
+ * even on machines where workiq was already discoverable via PATH. The
+ * functional verification now happens in the `setup` skill via a real
+ * `workiq ask -q "Who am I?"` call, not a filesystem probe.
  *
  * Returns:
  *   { ok: true,  path, version }                       — usable WorkIQ found
@@ -19,16 +26,9 @@ import os from 'node:os';
  *   'not-found'        — no workiq binary anywhere we looked
  *   'path-invalid'     — explicit --workiq-path was given but the file doesn't exist
  *   'not-executable'   — found but `--version` failed (corrupt install, missing deps, etc.)
+ *   'not-responsive'   — runs `--version` ok but functional ping returned no JSON-shaped output
  */
 export function checkWorkIQ(opts = {}) {
-  const isWin = process.platform === 'win32';
-  const homeBin = path.join(
-    os.homedir(),
-    '.kushi',
-    'bin',
-    isWin ? 'workiq.cmd' : 'workiq',
-  );
-
   if (opts.workiqPath) {
     const abs = path.resolve(opts.workiqPath);
     if (!existsSync(abs) || !statSync(abs).isFile()) {
@@ -44,9 +44,8 @@ export function checkWorkIQ(opts = {}) {
   const onPath = findOnPath('workiq');
   if (onPath) return runVersion(onPath);
 
-  if (existsSync(homeBin) && statSync(homeBin).isFile()) {
-    return runVersion(homeBin);
-  }
+  const clawpilotBin = clawpilotManagedBin();
+  if (clawpilotBin) return runVersion(clawpilotBin);
 
   return {
     ok: false,
@@ -55,6 +54,27 @@ export function checkWorkIQ(opts = {}) {
   };
 }
 
+/**
+ * Clawpilot installs workiq at ~/.copilot/bin/workiq[.cmd] as part of its own
+ * setup. We probe it ONLY if it already exists — we never create the dir, and
+ * we never probe `~/.kushi/bin/` (the v3.x location, removed in v4.4.4).
+ */
+function clawpilotManagedBin() {
+  const isWin = process.platform === 'win32';
+  const candidate = path.join(
+    os.homedir(),
+    '.copilot',
+    'bin',
+    isWin ? 'workiq.cmd' : 'workiq',
+  );
+  try {
+    if (existsSync(candidate) && statSync(candidate).isFile()) return candidate;
+  } catch {
+    // permission denied / external-dir prompt declined — treat as not present
+  }
+  return null;
+}
+
 function findOnPath(name) {
   const isWin = process.platform === 'win32';
   const cmd = isWin ? 'where' : 'command';
@@ -106,13 +126,54 @@ function runVersion(binPath) {
   return { ok: true, path: binPath, version };
 }
 
+/**
+ * Functional check — sends a real `workiq ask -q "ping"` and confirms a
+ * non-empty response. Used by the installer's preflight AFTER runVersion()
+ * passes, so we don't ship users to bootstrap with a workiq binary that
+ * exists but can't actually answer queries (sign-in missing, daemon down,
+ * tenant misconfigured, etc.).
+ *
+ * Returns the same shape as runVersion(). On a soft failure we still return
+ * { ok: true } and just attach `.warning` so the installer can print a hint
+ * without hard-failing — the `setup` skill is responsible for the deep
+ * recovery flow.
+ */
+export function pingWorkIQ(binPath, { timeoutMs = 30_000 } = {}) {
+  const isWin = process.platform === 'win32';
+  const res = isWin
+    ? spawnSync(`"${binPath}" ask -q "ping"`, {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+        shell: true,
+      })
+    : spawnSync(binPath, ['ask', '-q', 'ping'], {
+        encoding: 'utf-8',
+        timeout: timeoutMs,
+      });
+  const stdout = (res.stdout || '').trim();
+  const stderr = (res.stderr || '').trim();
+  if (res.status !== 0) {
+    return {
+      ok: true,
+      warning: `workiq ping returned exit ${res.status}. Run \`workiq ask -q "ping"\` manually to confirm sign-in. (${stderr.split(/\r?\n/)[0] || 'no stderr'})`,
+    };
+  }
+  if (!stdout) {
+    return {
+      ok: true,
+      warning: 'workiq ping returned empty stdout. The CLI is reachable but may not be signed in. Run `workiq ask -q "ping"` manually.',
+    };
+  }
+  return { ok: true };
+}
+
 function installHint() {
   const plat = process.platform;
   if (plat === 'win32') {
-    return 'Install with: winget install Microsoft.WorkIQ';
+    return 'Install with: winget install Microsoft.WorkIQ — then run `workiq ask -q "ping"` to sign in.';
   }
   if (plat === 'darwin') {
-    return 'Install with: brew install --cask microsoft-workiq';
+    return 'Install with: brew install --cask microsoft-workiq — then run `workiq ask -q "ping"` to sign in.';
   }
   return 'See https://gim-home.github.io/kushi/getting-started/install-workiq/ for Linux instructions.';
 }

package/src/main.mjs

@@ -16,7 +16,7 @@ import { copyAssets } from './copy-assets.mjs';
 import { mergeSettings } from './settings.mjs';
 import { mergeCopilotInstructions } from './copilot-instructions.mjs';
 import { seedConfig } from './seed-config.mjs';
-import { checkWorkIQ, tryInstallWorkIQ } from './check-workiq.mjs';
+import { checkWorkIQ, pingWorkIQ, tryInstallWorkIQ } from './check-workiq.mjs';
 import {
   resolveProfile,
   makeIncludeFilter,
@@ -317,7 +317,16 @@ async function preflightWorkIQ(options) {
     process.exit(1);
   }
 
-  console.log(`  ✓ WorkIQ detected at ${result.path} (${result.version})\n`);
+  console.log(`  ✓ WorkIQ detected at ${result.path} (${result.version})`);
+
+  // Functional ping — confirm the binary actually answers queries, not just
+  // that it exists. Soft warning only; the `setup` skill does the deep
+  // recovery + identity capture on first verb run.
+  const ping = pingWorkIQ(result.path);
+  if (ping.warning) {
+    console.warn(`    ⚠  ${ping.warning}`);
+  }
+  console.log('    Next: run `setup` once to verify sign-in + auto-fill your identity.\n');
 }
 
 /**