@sabaiway/agent-workflow-kit 14.18.0 → 14.19.0

package/CHANGELOG.md

@@ -4,6 +4,33 @@ Semantically versioned ([semver](https://semver.org)), newest first. The `versio
 is the current release. `upgrade` mode reads a project's `docs/ai/.workflow-version` and applies
 every `migrations/<version>-<slug>.md` newer than it, in semver order.
 
+## 14.19.0 — the Jev key the vendor's way: `jev-connect` claims no connection, names one restart step and saves for fish and Windows; the guide and the Recommendations item say where to run it (AD-166)
+
+**`jev-connect` no longer prints `connected`.** A saved key reaches the agent only once the agent's environment is read
+again, which the command cannot see; the guide's key mark is the proof. A run that saves every target now closes with
+`saved — restart the agent so it reads the key: in VS Code or a VS Code fork, quit the editor completely (every window)
+and open it again; in a terminal, open a new terminal and start the agent there; then ask the agent to check Jev`,
+exit 0. The key still reaches the agent only through `TYPESAFE_API_KEY`: the kit takes it from no file, and nothing is
+pasted into the chat.
+
+- **One restart step.** The command's all-saved line and the guide's STEP 1 print the same step from
+  `tools/jev-facts.mjs`. When targets are named and none is saved, the command's last line says to fix the cause on the
+  line above and run the command again (exit 4); `saved in part` gives the same remedy. Only a run with no target — off
+  Windows, a shell the command does not save for or an empty home — keeps the editor sentence.
+- **Where to run it.** The guide prints `Run it in <place>:` directly before the connect line and carries `where` in
+  its JSON: `a PowerShell terminal` on Windows, `the WSL distro <name> terminal`, `a terminal on SSH host <host>`, or
+  `a terminal inside this container`; nothing when none applies. The Recommendations item's recipe line opens with
+  `run the apply in <place>;`. The connect line and the apply stay pure commands; on Windows the line is quoted for
+  PowerShell.
+- **fish and Windows save.** fish: the kit's own file `~/.config/fish/conf.d/typesafe-api-key.fish` (under an absolute
+  `XDG_CONFIG_HOME` when set), written whole, its missing directories created 0700, a new file 0600, never through a
+  link. Windows: the user environment variable `TYPESAFE_API_KEY`, set by one `powershell.exe` run that reads the key
+  from its input, never from an argument; a failure names its cause on a `not saved:` line.
+- **The guide's not-set mark asks no hand edit.** After the restart it says to run the connect line again and follow
+  its last line; the guide's help names the place facts it reads.
+- Closes Issue-032. Unproven on the release host and stated: a live Windows run (a stub proves the route) and the fish
+  readback.
+
 ## 14.18.0 — Jev connects from ONE command you run: the Recommendations item hands it over, the guide prints it, and one leaf names it (AD-165)
 
 **While `TYPESAFE_API_KEY` is not in the environment the agent's commands run in, the Recommendations item `jev-connect`

package/README.md

@@ -235,7 +235,7 @@ file), or run the guarded `/agent-workflow-kit uninstall`.
 | `/agent-workflow-kit status` | any time | **read-only** single view of **versions + deployment + settings + bridges**: which members (kit / memory / engine / the two bridges) are installed and at what version (with an honest "installed on this machine" note when one is behind) and — in a project — what's deployed (`docs/ai`, the version stamps, and the **visibility**: visible / hidden / unclear), and the **feature-spec adoption state** (`not adopted` / `adopting (N draft)` / `adopted (N live, M draft)` / `could not be read`, plus `declined` when recorded), plus your settings (orchestration recipes, attribution, velocity) and the bridges' readiness. The two version axes (package number vs deployment-structure head) stay decoupled. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit now` | any time | **read-only** answer to where work stands in four blocks: **NOW** names every plan in flight, its phase, current and next step, and the tree evidence; **STEPS** gives every ledger row its evidence-derived status; **QUEUE** folds named rows under their full heading paths and calls position priority only in the judged backlog; **CAMPAIGN** shows the source-size practice figures and config state. The plan's own text never sets a status; a contradicted claim prints beside it. A block that cannot be derived is WITHHELD with its cause; NOW has two halves, plans and tree, each independently a value or WITHHELD, and NOW itself is WITHHELD only when both are. Never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit tier` | any time | **read-only** guide to the epic, story and task tier: what each level is, and the next step of the walk, with the command that runs it wherever a tool does. Never writes, never commits, never runs a subscription CLI. |
-| `/agent-workflow-kit jev` | any time | **read-only** guide to Jev (TypeSafe), a decision model: what it is, why it pays here, what it is not, the two steps to a connected key (the connect command, the optional vendor skill) and three prompts where it pays. Opens no connection and never prints the key. |
+| `/agent-workflow-kit jev` | any time | **read-only** guide to Jev (TypeSafe), a decision model: what it is, why it pays here, what it is not, the two steps to a set key (the connect command, the optional vendor skill) and three prompts where it pays. Opens no connection and never prints the key. |
 | `/agent-workflow-kit recipes` | any time | **read-only** orchestration advisor: presents five named recipes for composing the carriers of a step — the bridges and the full-tool executor subagent — into plan → execute → review — **Solo / Reviewed / Council / Delegated / Subagent** — plans + recommends one for your environment (degrading with a stated reason when a backend isn't ready, or when the executor vehicle is missing/unusable), and offers the choice. The activity/slot registry (six activities) is rendered by `procedures` and by `set-recipe --help`. The orchestrator runs it via the bridge skills or the executor vehicle and **always commits**; the kit never executes a recipe, never runs a subscription CLI, never commits. |
 | `/agent-workflow-kit procedures <activity>` | any time | **read-only** activity-procedures advisor: prints a named activity's ordered steps (`plan-authoring` / `plan-execution` / `routine` / `feedback-triage` / `epic` / `task`) read **live** from the engine, plus the **resolved recipe per slot** from your `docs/ai/orchestration.json` (agent-writable via `set-recipe`, or hand-edited) + carrier readiness (`plan-authoring`: author, fold, review; default Reviewed when a backend is ready, Council on request; slot-aware incl. Delegated and Subagent) — and, for every dispatched backend, the **full driving contract at the point of use** (exact copy-pasteable invocation, grounding levers like agy's `--facts`/`--decided`, the round-2 `--continue` delta, guarded passthrough), verbatim from the bridge manifests (drift-guarded; each wrapper's `--help` prints the same) — except `feedback-triage`, whose record-bound block carries the check with `--excerpts`, the resolved member lines (ready bridge commands, the ready lens brief, or explicit skipped members), and either the record round-table command for a bridge obligation or the no-receipt fact otherwise: the record is the artifact. `--override <slot>=<value>` adjusts one slot per run. Composes with `recipes`; never writes, never commits, never runs a subscription CLI. |
 | `/agent-workflow-kit set-recipe` | any time | **config writer** for `docs/ai/orchestration.json`: tell the agent your preference in plain language and it maps it to explicit `--set <activity>.<slot>=<value>` / `--unset` ops; the kit validates, **previews by default**, and writes only on `--write` (deployment-gated, atomic, symlink/TOCTOU-safe), resolving the effective recipe vs live readiness. Writes **only** that file — **never runs a backend or a subagent, never commits**; hand-editing stays fully supported. |

package/SKILL.md

@@ -3,7 +3,7 @@ name: agent-workflow-kit
 description: Deploy or upgrade a portable AI-agent memory-and-workflow system in any project. Use when the user wants to bootstrap `docs/ai/` + an entry-point `AGENTS.md` (+ `CLAUDE.md` alias) + cap/archive/index enforcement in a new or existing repo, set up the Memory Map and session protocols, install the docs-rotation pre-commit hook, or run `/agent-workflow-kit` / `/agent-workflow-kit upgrade`. Triggers on phrases like "set up the memory system", "deploy the AI workflow here", "bootstrap docs/ai", "upgrade the workflow". New to the epic, story and task tier? Run `/agent-workflow-kit tier`. A typed decision with a confidence from Jev? Run `/agent-workflow-kit jev`.
 disable-model-invocation: true
 metadata:
-  version: '14.18.0'
+  version: '14.19.0'
 ---
 
 # agent-workflow-kit

package/capability.json

@@ -3,7 +3,7 @@
   "schema": 1,
   "name": "agent-workflow-kit",
   "kind": "composition-root",
-  "version": "14.18.0",
+  "version": "14.19.0",
   "provides": [],
   "roles": {},
   "detect": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sabaiway/agent-workflow-kit",
-  "version": "14.18.0",
+  "version": "14.19.0",
   "description": "Portable, cross-agent memory & workflow for AI coding agents — Claude Code, Codex, Cursor, Devin Desktop. One command deploys an AGENTS.md entry point + docs/ai context with cap/archive/index enforcement into any repo.",
   "keywords": [
     "ai-agents",

package/references/modes/jev.md

@@ -2,11 +2,11 @@
 
 <!-- opt-in-capability: jev-connect -->
 
-Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the two steps to a connected key and three prompts where it pays. The guide writes no file, opens no connection, never prints the key's value and never commits.
+Read-only. The Jev guide: what Jev (TypeSafe) is, why it pays in this workflow, what it is not, the two steps to a set key and three prompts where it pays. The guide writes no file, opens no connection, never prints the key's value and never commits.
 
 Run `node ${CLAUDE_SKILL_DIR}/tools/jev-guide.mjs --dir <project> --json`.
 
-Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them. Keep the one vendor-quoted text verbatim and in quotes, never translated or reflowed: the not-a-replacement sentence.
+Render the returned envelope compactly in the user's conversational language. Never paste the JSON. Keep every path and every command verbatim, each command on its own line so it runs as printed; translate only the prose around them. Keep the one vendor-quoted text verbatim and in quotes, never translated or reflowed: the not-a-replacement sentence. The `Run it in <place>:` line, when the guide printed one, stays directly before the connect line and is never folded into it; the restart step is relayed whole.
 
 The connect line is the user's: hand it over as printed and never run it — the command refuses without a terminal, and a terminal is not consent. The install lines are the user's too: they change the agent's own configuration outside the project. No command the guide prints is run by the agent.
 

package/references/modes/recommendations.md

@@ -38,7 +38,7 @@ Run `node ${CLAUDE_SKILL_DIR}/tools/recommendations.mjs --cwd <project-root> [--
 - ADDITIONAL `gates-inert` arms (the third outcomes) — two further arms, and they differ in whether anything is BROKEN. **`producer-unrecognized`** — a checker with no producer anywhere in the declaration, on a tracked tree the changed-line coverage domain cannot reach (`.ts`/`.tsx`/`.jsx`/`.mts`/`.cts` strictly outnumber `.mjs`/`.cjs`/`.js`): the dead pair is real, so this arm is **HAND-APPLY** and the two remedies are marking the real producer with `"lcovProducer": true` or dropping the checker. Never a `node --test` prescription over a project that has no such suite, never the fill preview, and never an acknowledgement — a dead pair is broken, not narrow, and removing a producer after an acknowledgement lands right back in this arm. **`coverage-domain-narrow`** — the producer/checker pair IS live and the tree is still dominated by what the domain excludes: nothing is broken, and the honest sentence is that certification covers the assessable minority. Its apply is the consent-gated **ack writer** preview (a NEUTRAL fingerprint into `docs/ai/acks.json` as `coverageDomainAck`, never a security key); after the SAME confirmation you run the `--apply` it prints. The fingerprint binds the FACT — the verdict plus the unsupported extensions present, never the file counts — so an acknowledged project stays quiet as it grows and re-fires when a new unsupported language arrives or the verdict flips. The census reads the TRACKED tree with a read-only `git ls-files`; a tree it cannot read (a non-git deployment) becomes a stated skip, so optimality is withheld rather than assumed. Risk profile: no enforcement change of any kind — one acknowledgement recorded in a family-owned file, and one hand edit that stays the maintainer's.
 - `spec-adoption` — the feature-spec layer's ADOPTION STATE, judged from `docs/ai/specs/` alone through the same census `spec-check --all` runs, so a store the checker would refuse to observe is never counted here either. Both arms are OFFERS (`optional`) — the layer is opt-in, and `attention` stays reserved for a configured declaration that is broken. **`not-adopted`** (no store): every plan then cites zero governing specs by default and nothing says adoption never started; its apply is the spec-layer ensure one-liner (`ensure-configs --reconcile --only specs`, the same seed `upgrade` runs — it writes the reader/checker pairs and the store root, create-only, and skips with a stated reason where no Node evidence exists), and its `recipe:` line carries a NAMED **HAND-APPLY alternative** — the DECLINE preview (`ack-write --lane spec-adoption`, a dry-run that prints the exact `--apply`), which records `specAdoptionAck` in the family-owned `docs/ai/acks.json`. **The two are exclusive, and the order is part of the contract:** ask which the maintainer wants BEFORE the confirmation; on "seed" run the apply; on "decline" run NOTHING — hand over the preview line and let them run it and its printed `--apply`; never run the seed after a decline was chosen, and never run the decline preview for them. **`adopting`** (a store with no live contract): an optional item naming the draft count; its apply is that same decline preview (a dry-run; after the SAME confirmation you run the `--apply` it prints), and the honest remedy is authoring a contract from the skill's `SPEC_TEMPLATE.md`. A recorded decline silences BOTH arms and shows on `status` as ` — declined`; one live contract makes the decline moot. An unreadable store is a stated skip, never `flow optimal`. Risk profile: the seed writes only create-only files under `scripts/` and `docs/ai/specs/`; the decline writes one key into the ack store; nothing here authors a spec or blocks a plan.
 - `profile-gap` — each item's apply is a PREVIEW that writes nothing, and consent takes two steps: the confirmed pick runs the preview and you relay every line it prints (the environment-resolved slot values, each checker `entry:` line with its trust-chain disclosure, a Communication region the insert plans in the same run); the same line with ` --apply` appended runs only on a SECOND yes over those lines, never carried by the first. Items whose apply lines are byte-equal are one writer and take one answer: the tier preview's `--apply` writes the absent slots, the store seed and the queue seed together; the checker verb writes only its own entries; the insert writes every region it plans, all or nothing, so a `communication-absent` skip beside a declined `story-sessions-section` gets its own ask after the insert's full preview. A no records nothing and the item stays on the screen. A DECLINE is asked apart from later, before anything runs, and runs `node ${CLAUDE_SKILL_DIR}/tools/tier-preview.mjs --decline --cwd <project-root>` only when the user refuses EVERY item the tier preview then reports offered: it records each of them at the shipped lineage, and a declined item leaves the screen until a lineage step changes the profile. An undecidable entry is a stated skip naming its reason, the remedy by reason: a prior → the upgrade's `lens` reconcile; an absent region → the insert; a customized region → a hand edit only (the lens preserves it), so that skip stands and withholds `flow optimal`. Risk profile: the tier preview's `--apply` rewrites `docs/ai/orchestration.json` in canonical form with the `_README` note and creates `docs/ai/epics/.gitkeep` and `docs/plans/queue.md` create-only; the insert adds regions to `docs/ai/agent_rules.md`; the checker verb adds entries to the PRIVILEGED `docs/ai/gates.json`; the decline writes `docs/ai/profile-declines.json`; nothing here commits.
-- `jev-connect` — the apply is HAND-APPLY: the user runs the connect command in a terminal of their own, never the agent (the command refuses without a terminal, and a terminal is not consent). The command reads the key with no echo, makes one network call to api.typesafe.ai with the vendor's sample text only on the user's own run, and writes the key in plain text as managed export lines in the shell's startup files (bash: ~/.bashrc and the login file, created as ~/.bash_profile when none exists) (readable by any process running as that user, and by other local accounts when one is world-readable in a traversable home); the vendor keeps data under its processing agreement and offers zero retention only to enterprise accounts. The item reads the environment the agent's commands run in: a host setting that filters it shows the item while the key is set in the user's shell. The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation (the `spec-adoption` order): on "connect" hand over the apply line, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevConnectAck` in `docs/ai/acks.json`. Risk profile: a plain-text key in the user's startup files, written by a command the user runs; one network call from that run.
+- `jev-connect` — the apply is HAND-APPLY: the user runs the connect command in a terminal of their own, never the agent (the command refuses without a terminal, and a terminal is not consent); when the recipe line opens with `run the apply in <place>`, that place is the terminal to name. The command reads the key with no echo, makes one network call to api.typesafe.ai with the vendor's sample text only on the user's own run, and writes the key in plain text — as managed export lines in the shell's startup files (bash: ~/.bashrc and the login file, created as ~/.bash_profile when none exists; zsh: ~/.zshrc), as the kit's own file ~/.config/fish/conf.d/typesafe-api-key.fish for fish, or on Windows as the user environment variable TYPESAFE_API_KEY, stored in the Windows user environment; a process already running at the save can keep its old environment and hand it to what it starts — the guide's key mark confirms the agent sees it (a file is readable by any process running as that user, and by other local accounts when one is world-readable in a traversable home); the vendor keeps data under its processing agreement and offers zero retention only to enterprise accounts. The item reads the environment the agent's commands run in: a host setting that filters it shows the item while the key is set in the user's shell. The decline is the HAND-APPLY alternative on the recipe line, asked apart BEFORE the confirmation (the `spec-adoption` order): on "connect" hand over the apply line, on "decline" run nothing and hand over the recipe line; the decline is recorded per project as `jevConnectAck` in `docs/ai/acks.json`. Risk profile: a plain-text key in the user's startup files or the Windows user environment, written by a command the user runs; one network call from that run.
 - `adr-store-migration` — other items write project files too; what is unique here is that the crossing **overwrites and deletes files the project already has**: it replaces the deployed enforcement scripts in `scripts/` (the directional subset — only basenames the project already has; a locally-edited copy is snapshotted first, never silently clobbered) and, where a retired archive file exists, DELETES it once conservation has been proven. That is why it is **HAND-APPLY** and why the command shown in the apply slot is a **`--dry-run`** — it writes nothing and prints the whole plan. `--apply` is a SEPARATE step, run only after that plan has been shown and **fresh consent** obtained for it; the consent flow executes only the apply slot, so an item that needs consent AFTER its preview cannot use that lane at all. Every write is idempotent and the run is re-runnable to completion after any interruption, so a re-run repairs rather than double-applies. It never commits. Risk profile: overwrite + delete of existing project files, gated on a preview you have actually read.
 
 **Sandbox lanes (what to DO with the `sandbox-lane` recipe, per host class):**

package/tools/jev-connect.mjs

@@ -1,41 +1,49 @@
 #!/usr/bin/env node
 // spec:jev-guide — docs/ai/specs/kit/jev-guide/jev-connect.md
-// The one command that connects Jev (TypeSafe) on a host. The USER runs it in a terminal of their
-// own: it reads the key with no echo, verifies it with one request, saves it as managed export lines
-// in the shell's startup files and says to restart the agent. It never prints the key, never puts it in
-// an argv, and refuses when stdin is not a terminal, so a non-interactive run (the agent's) cannot
-// reach the prompt — the mode doc keeps the rule that the agent never runs it.
-import { lstatSync, readFileSync, writeFileSync } from 'node:fs';
+// The one command that saves the Jev (TypeSafe) key on a host. The USER runs it in a terminal of
+// their own: it reads the key with no echo, verifies it with one request, saves it where the shell
+// reads it (bash, zsh, fish) or in the Windows user environment, and prints the restart step. It never
+// prints the key, never puts it in an argv, and refuses when stdin is not a terminal, so a
+// non-interactive run (the agent's) cannot reach the prompt — the mode doc keeps the rule that the
+// agent never runs it. It claims no connection: the guide's key mark, read after the restart, is the proof.
+import { spawnSync } from 'node:child_process';
+import { lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, sep } from 'node:path';
 import { fail } from '../references/scripts/markdown-blocks.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { JEV_ENDPOINT, JEV_ERROR_MEANINGS, JEV_SAMPLE_BODY, KEY_VARIABLE } from './jev-facts.mjs';
+import { JEV_ENDPOINT, JEV_ERROR_MEANINGS, JEV_SAMPLE_BODY, KEY_VARIABLE, RESTART_STEP } from './jev-facts.mjs';
 
 export const EXIT = Object.freeze({ saved: 0, notVerified: 1, usage: 2, noTerminal: 3, notSaved: 4 });
 export const MARK = '# agent-workflow jev';
 export const TIMEOUT_MS = 15000;
 const LOGIN_FILES = ['.bash_profile', '.bash_login', '.profile'];
+const FISH_FILE = join('fish', 'conf.d', 'typesafe-api-key.fish');
+const WINDOWS_TARGET = `the Windows user environment variable ${KEY_VARIABLE}`;
+const WINDOWS_SCRIPT = `$ErrorActionPreference='Stop'; [Environment]::SetEnvironmentVariable('${KEY_VARIABLE}', [Console]::In.ReadLine(), 'User')`;
 export const TERMINAL_SENTENCE = 'run this in a terminal of your own: it asks for the key there, so the agent never sees it';
-export const CONNECTED = 'connected — quit the agent and start it again from a new terminal';
-export const SAVED_IN_PART = 'saved in part — add the export line by hand where a line above says not saved, then restart the agent';
+export const ALL_SAVED = `saved — ${RESTART_STEP}; then ask the agent to check Jev`;
+export const SAVED_IN_PART = 'saved in part — fix the cause on the not saved: line above and run this command again, then restart the agent';
+const RETRY_SENTENCE = 'not saved — fix the cause on the line above and run this command again';
 export const NOT_SAVED_SENTENCE = `not saved — set ${KEY_VARIABLE} to your key in your shell's startup file, in an editor and in that shell's own syntax, then restart the agent`;
 export const EDITOR_SENTENCE = `verified, ${NOT_SAVED_SENTENCE}`;
-const HELP = `jev-connect — connects Jev (TypeSafe) on this host; run it in a terminal of your own.
+const HELP = `jev-connect — saves the Jev (TypeSafe) key on this host; run it in a terminal of your own.
 
 Usage:
   node jev-connect.mjs [--unverified]
 
-Asks for ${KEY_VARIABLE} with no echo, verifies the key with one request to api.typesafe.ai, saves it
-as managed export lines in your shell's startup files (bash: ~/.bashrc and the login file bash
-reads; zsh: ~/.zshrc, under ZDOTDIR when set) and says to restart the agent. The key is never printed and never put in an argument.
+Asks for ${KEY_VARIABLE} with no echo, verifies the key with one request to api.typesafe.ai and
+saves it: for bash and zsh as managed export lines in your shell's startup files (bash: ~/.bashrc
+and the login file bash reads; zsh: ~/.zshrc, under ZDOTDIR when set), for fish as the file
+~/.config/fish/conf.d/typesafe-api-key.fish (under XDG_CONFIG_HOME when set), on Windows as the user
+environment variable. Then it prints the restart step. The key is never printed and never put in an argument.
 
 --unverified  save without the request (no network from here).
 --help        answered only when it is the whole invocation.
 
-Exit codes: 0 saved; 1 not verified, nothing written; 2 usage; 3 no terminal, aborted or no key,
-nothing written; 4 not saved (another shell, Windows, a linked startup file or directory) — the
-last line says what to set by hand.`;
+Exit codes: 0 saved; 1 not verified, nothing written; 2 usage; 3 no terminal, aborted, no key or a
+failed read, nothing written;
+4 not saved (a refused or failed target, or a shell it does not save for) — the last line says what to do next.`;
 
 const parseArgv = (argv) => {
   if (argv.includes('--help') || argv.includes('-h')) {
@@ -112,22 +120,31 @@ export const verifyKey = async (key, io = {}) => {
   return { ok: true, line: `verified: HTTP 200 — department ${scrub(answer.choice, key)}, confidence ${answer.confidence}` };
 };
 
-// The startup files the key goes to, by a closed rule over the shell: zsh reads ~/.zshrc (under
-// ZDOTDIR when set); an interactive bash reads ~/.bashrc and a login bash the first of
-// .bash_profile, .bash_login, .profile that exists — created as .bash_profile when none does. Both
-// bash files always: no file content decides the set, so a login file's own older export is
-// rewritten too. Any other shell, and Windows, gets no target.
-export const targetsFor = ({ shell, home, zdotdir, platform = 'linux' }, deps = {}) => {
+// The targets the key goes to, as descriptors { form, path }, by a closed rule over the platform and
+// the shell: Windows → the user environment variable (one spawn); zsh reads ~/.zshrc (under ZDOTDIR
+// when set); an interactive bash reads ~/.bashrc and a login bash the first of .bash_profile,
+// .bash_login, .profile that exists — created as .bash_profile when none does. Both bash files
+// always: no file content decides the set. fish reads its conf.d (under XDG_CONFIG_HOME when it is
+// absolute). Any other shell gets no target.
+export const targetsFor = ({ shell, home, zdotdir, xdgConfigHome, platform = 'linux' }, deps = {}) => {
   const exists = deps.exists ?? ((path) => { try { lstatSync(path); return true; } catch { return false; } });
-  if (platform === 'win32' || typeof home !== 'string' || home === '') return [];
+  if (platform === 'win32') return [{ form: 'windows', path: null }];
+  if (typeof home !== 'string' || home === '') return [];
   const name = typeof shell === 'string' ? basename(shell) : '';
-  if (name === 'zsh') return [join(typeof zdotdir === 'string' && zdotdir !== '' ? zdotdir : home, '.zshrc')];
+  const exported = (path) => ({ form: 'export', path });
+  if (name === 'zsh') return [exported(join(typeof zdotdir === 'string' && zdotdir !== '' ? zdotdir : home, '.zshrc'))];
+  if (name === 'fish') {
+    const config = typeof xdgConfigHome === 'string' && isAbsolute(xdgConfigHome) ? xdgConfigHome : join(home, '.config');
+    return [{ form: 'fish', path: join(config, FISH_FILE) }];
+  }
   if (name !== 'bash') return [];
   const login = LOGIN_FILES.map((file) => join(home, file)).find(exists) ?? join(home, LOGIN_FILES[0]);
-  return [join(home, '.bashrc'), login];
+  return [exported(join(home, '.bashrc')), exported(login)];
 };
 
 export const managedLine = (key) => `export ${KEY_VARIABLE}='${key.replace(/'/g, `'\\''`)}'  ${MARK}`;
+// fish's single quotes take two escapes: a backslash doubled, a quote after a backslash.
+export const fishLine = (key) => `set -gx ${KEY_VARIABLE} '${key.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'  ${MARK}`;
 const isExportLine = (line) => new RegExp(`^\\s*export\\s+${KEY_VARIABLE}=`).test(line);
 
 // Replace matching export lines in place, their indent and CR kept, so no if/case branch is
@@ -143,42 +160,73 @@ export const upsertManagedLine = (text, line) => {
 };
 
 // The directories between the home and the target, each lstat'ed: a link among them is never written
-// through (a stow'd ZDOTDIR is a dotfiles repo); a target outside the home is not written at all.
-const parentRefusal = (path, home, lstat) => {
+// through (a stow'd ZDOTDIR is a dotfiles repo); a target outside the home is not written at all. The
+// walk stops at the first missing directory: nothing below it exists, so nothing below is a link.
+const walkParents = (path, home, lstat) => {
   const rel = relative(home, dirname(path));
-  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return `${path} is outside the home`;
+  if (rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return { refusal: `${path} is outside the home` };
+  const missing = [];
   let dir = home;
   for (const part of rel.split(sep).filter(Boolean)) {
     dir = join(dir, part);
-    if (lstat(dir).isSymbolicLink()) return `${path} — ${dir} is a link`;
+    if (missing.length > 0) { missing.push(dir); continue; }
+    let stat;
+    try { stat = lstat(dir); } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+      missing.push(dir);
+      continue;
+    }
+    if (stat.isSymbolicLink()) return { refusal: `${path} — ${dir} is a link` };
   }
-  return null;
+  return { refusal: null, missing };
 };
 
-// One line per target: `saved: <path>` or `not saved: <path> — <why>`. A link — the target or a
-// directory below the home — or a non-regular entry is never written through; a new file is created
-// 0600; an existing file keeps its mode.
-export const saveKey = (key, targets, home, deps = {}) => targets.map((path) => {
+// A file target: the export form upserts its managed line and creates no directory; the fish form is
+// the kit's own file, written whole, its missing directories created 0700. A new file is 0600; an
+// existing one keeps its mode.
+const saveFile = (key, { form, path }, home, deps) => {
   const lstat = deps.lstat ?? lstatSync;
   const read = deps.read ?? ((at) => readFileSync(at, 'utf8'));
   const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  const no = (line) => ({ path, saved: false, line });
   let stat = null;
   try {
-    const refusal = parentRefusal(path, home, lstat);
-    if (refusal) return { path, saved: false, line: `not saved: ${refusal} — add the export line by hand` };
-    stat = lstat(path);
+    const { refusal, missing } = walkParents(path, home, lstat);
+    if (refusal) return no(`not saved: ${refusal} — nothing written`);
+    if (form === 'fish') for (const dir of missing) mkdir(dir, { mode: 0o700 });
+    if (form === 'fish' || missing.length === 0) stat = lstat(path);
   } catch (error) {
-    if (error?.code !== 'ENOENT') return { path, saved: false, line: `not saved: ${path} — ${error?.code ?? error?.message}` };
+    if (error?.code !== 'ENOENT') return no(`not saved: ${path} — ${error?.code ?? error?.message}`);
   }
-  if (stat?.isSymbolicLink()) return { path, saved: false, line: `not saved: ${path} is a link — add the export line by hand` };
-  if (stat && !stat.isFile()) return { path, saved: false, line: `not saved: ${path} is not a regular file` };
+  if (stat?.isSymbolicLink()) return no(`not saved: ${path} is a link — nothing written`);
+  if (stat && !stat.isFile()) return no(`not saved: ${path} is not a regular file`);
   try {
-    write(path, upsertManagedLine(stat ? read(path) : '', managedLine(key)), stat ? {} : { mode: 0o600 });
+    const text = form === 'fish' ? `${fishLine(key)}\n` : upsertManagedLine(stat ? read(path) : '', managedLine(key));
+    write(path, text, stat ? {} : { mode: 0o600 });
     return { path, saved: true, line: `saved: ${path}` };
   } catch (error) {
-    return { path, saved: false, line: `not saved: ${path} — ${error?.code ?? error?.message}` };
+    return no(`not saved: ${path} — ${error?.code ?? error?.message}`);
   }
-});
+};
+
+// The Windows target: one powershell.exe fed the key on stdin, never in an argv. The default spawn
+// starts a process only on Windows; nothing the child printed is relayed.
+const saveWindows = (key, deps) => {
+  const no = (cause) => ({ path: null, saved: false, line: `not saved: ${WINDOWS_TARGET} — ${cause}` });
+  if (!deps.spawn && process.platform !== 'win32') return no('not on Windows');
+  const timeoutMs = deps.timeoutMs ?? TIMEOUT_MS;
+  const result = (deps.spawn ?? spawnSync)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', WINDOWS_SCRIPT],
+    { input: `${key}\n`, timeout: timeoutMs, encoding: 'utf8', windowsHide: true });
+  if (result.error?.code === 'ETIMEDOUT') return no(`no answer within ${timeoutMs / 1000} s`);
+  if (result.error) return no(result.error.code ?? result.error.message);
+  if (result.status !== 0) return no(`powershell.exe exited ${result.status}`);
+  return { path: null, saved: true, line: `saved: ${WINDOWS_TARGET}` };
+};
+
+// One line per target: `saved: <where>` or `not saved: <where> — <why>`.
+export const saveKey = (key, targets, home, deps = {}) => targets.map((target) => (target.form === 'windows'
+  ? saveWindows(key, deps) : saveFile(key, target, home, deps)));
 
 const safeHome = (env) => {
   if (typeof env.HOME === 'string' && env.HOME !== '') return env.HOME;
@@ -206,12 +254,15 @@ export const main = async (argv, io = {}) => {
   }
   const env = io.env ?? process.env;
   const home = io.home ?? safeHome(env);
-  const targets = targetsFor({ shell: env.SHELL, home, zdotdir: env.ZDOTDIR, platform: io.platform ?? process.platform }, io);
+  const targets = targetsFor({ shell: env.SHELL, home, zdotdir: env.ZDOTDIR, xdgConfigHome: env.XDG_CONFIG_HOME,
+    platform: io.platform ?? process.platform }, io);
   const results = saveKey(key, targets, home, io);
   for (const result of results) log(result.line);
   const saved = results.filter((result) => result.saved).length;
-  if (results.length > 0 && saved === results.length) { log(CONNECTED); return EXIT.saved; }
+  const verified = parsed.unverified ? '' : 'verified, ';
+  if (results.length > 0 && saved === results.length) { log(ALL_SAVED); return EXIT.saved; }
   if (saved > 0) log(SAVED_IN_PART);
+  else if (results.length > 0) log(`${verified}${RETRY_SENTENCE}`);
   else log(parsed.unverified ? NOT_SAVED_SENTENCE : EDITOR_SENTENCE);
   return EXIT.notSaved;
 };

package/tools/jev-facts.mjs

@@ -15,8 +15,26 @@ const SAFE = /^[A-Za-z0-9_./:=+@%,-]+$/;
 export const quoteArg = (value) => (SAFE.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`);
 
 // The command the user runs in a terminal of their own; the guide prints it, the advisor's apply
-// carries it. `toolsDir` is the kit's tools directory (the file beside this one).
-export const connectLine = (toolsDir) => `node ${quoteArg(join(toolsDir, 'jev-connect.mjs'))}`;
+// carries it. `toolsDir` is the kit's tools directory (the file beside this one). On win32 the line
+// is for PowerShell: always single-quoted, a quote doubled, one backslash by concatenation.
+export const connectLine = (toolsDir, platform) => (platform === 'win32'
+  ? `node '${`${toolsDir}\\jev-connect.mjs`.replace(/'/g, "''")}'`
+  : `node ${quoteArg(join(toolsDir, 'jev-connect.mjs'))}`);
+
+// The one restart step the connect command's all-saved line and the guide's STEP 1 print.
+export const RESTART_STEP = 'restart the agent so it reads the key: in VS Code or a VS Code fork, quit the editor completely (every window) and open it again; in a terminal, open a new terminal and start the agent there';
+
+// Where the user runs the connect line, by one ordered rule; a name outside the set drops its rung.
+const NAME = /^[A-Za-z0-9._-]+$/;
+const named = (value) => typeof value === 'string' && NAME.test(value);
+const nonEmpty = (value) => typeof value === 'string' && value !== '';
+export const placeOf = ({ env = {}, platform, hostname, container } = {}) => {
+  if (platform === 'win32') return 'a PowerShell terminal';
+  if (named(env.WSL_DISTRO_NAME)) return `the WSL distro ${env.WSL_DISTRO_NAME} terminal`;
+  if (nonEmpty(env.SSH_CONNECTION) && named(hostname)) return `a terminal on SSH host ${hostname}`;
+  if (nonEmpty(env.REMOTE_CONTAINERS) || nonEmpty(env.CODESPACES) || container === true) return 'a terminal inside this container';
+  return '';
+};
 
 // The vendor's smallest documented request (docs.typesafe.ai quickstart, read 2026-09-29) and the
 // meanings of its documented error codes, quoted as the vendor prints them.

package/tools/jev-guide.mjs

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 // spec:jev-guide — docs/ai/specs/kit/jev-guide/index.md
 import { statSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { homedir, hostname } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { fail } from '../references/scripts/markdown-blocks.mjs';
 import { isDirectRun } from './direct-run.mjs';
-import { KEY_VARIABLE, connectLine, keySet } from './jev-facts.mjs';
+import { KEY_VARIABLE, RESTART_STEP, connectLine, keySet, placeOf } from './jev-facts.mjs';
 
 const SCHEMA = 1;
 const TOOLS = dirname(fileURLToPath(import.meta.url));
 const SKILL_FILE = join('typesafe-ai', 'SKILL.md');
-const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the two steps to a connected key.
+const HELP = `jev — read-only: what Jev (TypeSafe) is, why it pays here, and the two steps to a set key.
 
 Usage:
   node jev-guide.mjs [--dir PROJECT] [--json]
@@ -22,7 +22,7 @@ Usage:
 
 Exit codes: 0 rendered; 1 nothing rendered (a --dir that is not a directory); 2 usage.
 
-Reads only: the --dir, the home directory, the key variable's presence and five skill paths; no network.`;
+Reads only: the --dir, the home directory, the key variable's presence, five skill paths, and for the place WSL_DISTRO_NAME, SSH_CONNECTION, REMOTE_CONTAINERS, CODESPACES, the platform, the hostname and /.dockerenv; no network.`;
 
 export const JEV_TEXT = Object.freeze([
   'WHAT: Jev is a decision model: it takes a state and typed questions (choice, score, noul) and returns typed answers with probabilities and a confidence; it does not write text.',
@@ -45,10 +45,10 @@ export const JEV_TEXT = Object.freeze([
 ]);
 
 const KEY_GET = 'Get a key at console.typesafe.ai and set it on every host the agent runs on.';
-const KEY_CONNECT = 'Connect it from a terminal of your own, never through the agent: the command asks for the key with no echo, checks it with one request and, for bash or zsh, saves it to your shell\'s startup files.';
-const KEY_RESTART = 'Then quit the agent, start it again from a new terminal, and run /agent-workflow-kit jev again: the key mark should read set.';
+const KEY_CONNECT = 'Connect it from a terminal of your own, never through the agent: the command asks for the key with no echo, checks it with one request and saves it for bash, zsh or fish in your shell\'s startup files, or on Windows as a user environment variable.';
+const KEY_RESTART = `Then ${RESTART_STEP}. Run /agent-workflow-kit jev again: the key mark should read set.`;
 const KEY_NEVER = 'Never paste the key into the chat or into a project file.';
-const KEY_NOT_SET = `key: ${KEY_VARIABLE} not set. A host setting that filters the environment of the agent's commands also hides it. If it still reads not set after a restart and no such setting applies, the agent may not have been started from a shell that reads its startup file: export the variable in the file the agent's launcher reads, then restart.`;
+const KEY_NOT_SET = `key: ${KEY_VARIABLE} not set. A host setting that filters the environment of the agent's commands also hides it. If it still reads not set after that restart and no such setting applies, run the connect line again and follow its last line.`;
 const INSTALL = [
   'Optional, for your own code and prompts — the vendor skill:',
   'Claude Code:',
@@ -101,12 +101,17 @@ const homeOf = (io) => {
   if (io.home !== undefined) return io.home;
   try { return homedir(); } catch { return ''; }
 };
+// The place's host facts: each injected, else read once from the host, a failing read reading as none.
+const placeFor = (io, env, platform) => placeOf({ env, platform,
+  hostname: io.hostname ?? (() => { try { return hostname(); } catch { return ''; } })(),
+  container: io.container ?? statIs('/.dockerenv', 'file') });
 const skillPaths = (dir, home) => [...new Set([join(dir, '.claude', 'skills'), join(dir, '.agents', 'skills'),
   ...(home === '' ? [] : [join(home, '.claude', 'skills'), join(home, '.codex', 'skills'), join(home, '.cursor', 'skills')])]
   .map((root) => join(root, SKILL_FILE)))];
 
-const renderSteps = (found, set, connect) => [
-  ['STEP 1 — the key', KEY_GET, KEY_CONNECT, connect, KEY_RESTART, KEY_NEVER, set ? `key: ${KEY_VARIABLE} set.` : KEY_NOT_SET],
+const renderSteps = (found, set, connect, where) => [
+  ['STEP 1 — the key', KEY_GET, KEY_CONNECT, ...(where ? [`Run it in ${where}:`] : []), connect, KEY_RESTART, KEY_NEVER,
+    set ? `key: ${KEY_VARIABLE} set.` : KEY_NOT_SET],
   ['STEP 2 — the vendor skill', ...INSTALL,
     ...(found.length ? found.map((path) => `skill: found at ${path}`) : NOT_SEEN), ...AFTER_INSTALL],
 ];
@@ -124,10 +129,12 @@ export const main = (argv, io = {}) => {
   const found = skillPaths(dir, homeOf(io)).filter((path) => statIs(path, 'file'));
   const env = io.env ?? process.env;
   const set = keySet(env);
-  const connect = connectLine(io.toolsDir ?? TOOLS);
-  const steps = renderSteps(found, set, connect);
+  const platform = io.platform ?? process.platform;
+  const connect = connectLine(io.toolsDir ?? TOOLS, platform);
+  const where = placeFor(io, env, platform);
+  const steps = renderSteps(found, set, connect, where);
   log(parsed.json
-    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found }, key: { set }, connect, steps, prompts: PROMPTS }, null, 2)
+    ? JSON.stringify({ schema: SCHEMA, command: 'jev', dir, text: JEV_TEXT, skill: { found }, key: { set }, connect, where, steps, prompts: PROMPTS }, null, 2)
     : [...JEV_TEXT, ...steps.flat(), 'WHERE IT PAYS IN THIS WORKFLOW', ...PROMPTS].join('\n'));
   return 0;
 };

package/tools/recommendations.mjs

@@ -31,8 +31,8 @@
 // read-only git queries. Dependency-free, Node >= 22. No side effects on import (the isDirectRun
 // idiom).
 
-import { readFileSync, readdirSync, lstatSync, existsSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { readFileSync, readdirSync, lstatSync, existsSync, statSync } from 'node:fs';
+import { homedir, hostname } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
@@ -102,7 +102,7 @@ import {
 import { ADOPTION, STORE_DIR_REL as SPEC_STORE_DIR_REL, SPEC_ADOPTION_LANE, declineFingerprint, readDeclineAck, surveySpecAdoption } from './spec-adoption.mjs';
 import { ENSURE_OPS } from './ensure-vocabulary.mjs';
 import { composeProfileGapScreen } from './profile-gap-screen.mjs';
-import { connectLine, keySet } from './jev-facts.mjs';
+import { connectLine, keySet, placeOf } from './jev-facts.mjs';
 
 // The upgrade ensure that seeds the spec store — the not-adopted item's apply; pinned to the vocabulary.
 const SPEC_LAYER_ENSURE = ENSURE_OPS.includes('specs') ? 'specs' : null;
@@ -1612,11 +1612,14 @@ const probeMcpChannel = ({ root, deps, add, skip }) => {
 // the injected environment; the apply is the connect command the USER runs in a terminal of their own (HAND-APPLY), never a guide.
 export const probeJevConnect = ({ root, deps, add, skip }) => {
   try {
-    if (keySet(deps.getenv ?? {})) return;
+    const env = deps.getenv ?? {};
+    if (keySet(env)) return;
     if (readAckValue(root, deps, ACKS_JEV_CONNECT_KEY) === JEV_CONNECT_DECLINE) return;
+    const host = deps.jevHost ?? {};
+    const place = placeOf({ env, platform: host.platform, hostname: host.hostname, container: host.container });
     const decline = `node ${q(toolPath('ack-write.mjs'))} --lane jev-connect --fingerprint ${JEV_CONNECT_DECLINE} --cwd ${q(root)}`;
-    add('jev-connect', WHATS['jev-connect'], `HAND-APPLY: ${connectLine(HERE)}`, 'jev-connect',
-      `HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
+    add('jev-connect', WHATS['jev-connect'], `HAND-APPLY: ${connectLine(HERE, host.platform)}`, 'jev-connect',
+      `${place ? `run the apply in ${place}; ` : ''}HAND-APPLY alternative (instead of the apply, never after it): decline the offer by recording it — ${decline}`);
   } catch (err) {
     skip('jev-connect', err);
   }
@@ -1757,6 +1760,10 @@ the consent-gated ack writer into docs/ai/acks.json (never a security key).
 Read-only: never writes, never commits, never runs a subscription CLI. Exit codes: 0 report
 rendered (items or empty); 1 error; 2 usage.`;
 
+// The host facts of the key offer's place: the platform, the hostname (a throw reads as none), /.dockerenv a regular file.
+const hostFacts = () => ({ platform: process.platform, hostname: (() => { try { return hostname(); } catch { return ''; } })(),
+  container: (() => { try { return statSync('/.dockerenv').isFile(); } catch { return false; } })() });
+
 export const main = (argv, ctx = {}) => {
   try {
     if (argv.includes('--help') || argv.includes('-h')) return { code: 0, stdout: HELP, stderr: '' };
@@ -1781,7 +1788,7 @@ export const main = (argv, ctx = {}) => {
       }
     })();
     if (st == null || !st.isDirectory()) throw Object.assign(new Error(`--cwd is not a directory: ${cwd}`), { exitCode: 1 });
-    const result = buildRecommendations({ cwd, deps: ctx.deps ?? { getenv: process.env } });
+    const result = buildRecommendations({ cwd, deps: ctx.deps ?? { getenv: process.env, jevHost: hostFacts() } });
     if (json) return { code: 0, stdout: JSON.stringify(result, null, 2), stderr: '' };
     return { code: 0, stdout: formatRecommendations(result), stderr: '' };
   } catch (err) {