skills: address review on the SSH recipe and the parity guard

- ssh-host create script: route the bootstrap ssh through the chosen jump host or proxy command, refuse both at once, use StrictHostKeyChecking=accept-new instead of a blind ssh-keyscan append, and pass gh_token/project_root/repo_url/repo_ref to the remote bash via printf %q so a quote in a value cannot break out of the command.
- per-workspace-env envelope: the step-10 workspace test the user asked for is no longer forbidden by the same paragraph.
- linear guides: name the full verb, ORCA linear list-issues.
- parity guard: a prefix reference such as ORCA linear --help or ORCA emulator --webcam now has its flags checked against every command under that prefix; only an exact path or an explicit ... was checked before.

skill-guides/linear-tickets.md

@@ -115,7 +115,7 @@ ORCA linear list --filter assigned --limit 10 --workspace all --json
 ORCA linear list --filter open --team <key-or-id> --workspace <workspaceId> --json
 ```
 
-Use `list-issues` when MCP-compatible filters or cursor pagination are needed.
+Use `ORCA linear list-issues` when MCP-compatible filters or cursor pagination are needed.
 
 - Omitting `--limit` returns every match and reports `result.meta.limit` as `null`, so filter before listing a large workspace. `--limit <n>` caps the read.
 - When a cap held results back, `--json` sets `result.truncated` and `result.meta.hasMore`; human output prints `truncated: showing N`. Check `truncated` before reporting a count, then page with `--cursor` until it is false.

skill-guides/orca-linear.md

@@ -112,7 +112,7 @@ ORCA linear list --filter assigned --limit 10 --workspace all --json
 ORCA linear list --filter open --team <key-or-id> --workspace <workspaceId> --json
 ```
 
-Use `list-issues` when MCP-compatible filters or cursor pagination are needed.
+Use `ORCA linear list-issues` when MCP-compatible filters or cursor pagination are needed.
 
 - Omitting `--limit` returns every match and reports `result.meta.limit` as `null`, so filter before listing a large workspace. `--limit <n>` caps the read.
 - When a cap held results back, `--json` sets `result.truncated` and `result.meta.hasMore`; human output prints `truncated: showing N`. Check `truncated` before reporting a count, then page with `--cursor` until it is false.

skill-guides/orca-per-workspace-env.md

@@ -40,8 +40,8 @@ detecting provider CLIs and their login state, scaffolding and editing files und
 explicit OK before anything that provisions a paid resource. The paid steps are the base snapshot,
 the auth snapshot, and `--provision`. One OK covers the whole `--provision` fix-and-rerun loop, so
 do not re-ask per iteration. Stop for the interactive agent login, which you cannot drive: the user runs
-it and tells you when it finished. Never create an Orca workspace, commit, choose a plan or region,
-invent a scope, project, or billing id, or write a credential into a script, `userData`, the state
+it and tells you when it finished. Never create an Orca workspace except for the step-10 test the user asked for. Never commit,
+choose a plan or region, invent a scope, project, or billing id, or write a credential into a script, `userData`, the state
 file, or a commit.
 
 ## The branch that shapes everything

skill-guides/orca-per-workspace-env/references/ssh-host.md

@@ -69,18 +69,26 @@ set -euo pipefail
 : "${identity_file:=}"; : "${jump_host:=}"; : "${proxy_command:=}"   # avoid set -u aborts on optionals
 gh_token="${GH_TOKEN:-${GITHUB_TOKEN:-$(command -v gh >/dev/null 2>&1 && gh auth token 2>/dev/null || true)}}"
 ssh_target="${ssh_username}@${host}"
-ssh_opts=(-p "$ssh_port"); [ -n "$identity_file" ] && ssh_opts+=(-i "$identity_file")
+if [ -n "$jump_host" ] && [ -n "$proxy_command" ]; then
+  echo "set jump_host or proxy_command, not both" >&2; exit 1
+fi
 # A fresh host's key isn't in known_hosts, and a StrictHostKeyChecking prompt HANGS a
-# non-interactive create. Pre-add the key (or set the option) so it can't block.
-ssh-keyscan -p "$ssh_port" "$host" >> "$HOME/.ssh/known_hosts" 2>/dev/null || true
+# non-interactive create. accept-new records the first key seen and never prompts; if the
+# provider publishes the host fingerprint, compare it after the first connection.
+ssh_opts=(-p "$ssh_port" -o StrictHostKeyChecking=accept-new)
+[ -n "$identity_file" ] && ssh_opts+=(-i "$identity_file")
+[ -n "$jump_host" ] && ssh_opts+=(-J "$jump_host")
+[ -n "$proxy_command" ] && ssh_opts+=(-o "ProxyCommand=$proxy_command")
 
-# 1. ensure the repo is present and at the right commit on the host (NO orca serve here)
-ssh "${ssh_opts[@]}" "$ssh_target" \
-  "GH_TOKEN='$gh_token' GIT_TERMINAL_PROMPT=0 bash -lc '
-     set -euo pipefail
-     [ -d \"$project_root/.git\" ] || git clone \"$repo_url\" \"$project_root\"
-     cd \"$project_root\" && git fetch origin \"$repo_ref\" && git checkout -B \"$repo_ref\" FETCH_HEAD
-   '" >&2
+# 1. ensure the repo is present and at the right commit on the host (NO orca serve here).
+#    printf %q quotes every value for the remote shell, so a space or quote in a path or
+#    ref cannot break out of the command.
+remote_sync='set -euo pipefail
+  [ -d "$project_root/.git" ] || git clone "$repo_url" "$project_root"
+  cd "$project_root" && git fetch origin "$repo_ref" && git checkout -B "$repo_ref" FETCH_HEAD'
+ssh "${ssh_opts[@]}" "$ssh_target" "$(printf \
+  'GH_TOKEN=%q GIT_TERMINAL_PROMPT=0 project_root=%q repo_url=%q repo_ref=%q bash -lc %q' \
+  "$gh_token" "$project_root" "$repo_url" "$repo_ref" "$remote_sync")" >&2
 
 # 2. print the SSH connection block (NO pairingCode, NO orca serve). host/port/username tell Orca's
 #    relay how to dial in; identityFile/jumpHost/proxyCommand/portForwards are emitted when set.

src/cli/skill-guide-cli-parity.test.ts

@@ -139,10 +139,13 @@ function parityFailures(invocation: Invocation): string[] {
     }
   }
   if (command === null) {
-    // An incomplete reference like `ORCA emulator ...` names a real prefix and pins no flags.
+    // A prefix reference such as `ORCA emulator ...` or `ORCA linear --help` names no exact
+    // path, but its flags still have to belong to some command under that prefix.
     if (pathPrefixes.has(tokens.join(' '))) {
-      return failures
+      command = tokens.join(' ')
     }
+  }
+  if (command === null) {
     failures.push(
       describeFailure(invocation, `no COMMAND_SPECS path or alias for "${tokens.join(' ')}"`)
     )
@@ -174,4 +177,13 @@ describe('skill guides only name commands and flags the CLI defines', () => {
   it('resolves every ORCA invocation against COMMAND_SPECS', () => {
     expect(invocations.flatMap(parityFailures)).toEqual([])
   })
+
+  it('checks flags on a prefix reference against every command under it', () => {
+    const at = (text: string) => parityFailures({ file: 'x.md', line: 1, text })
+    expect(at('ORCA emulator ...')).toEqual([])
+    expect(at('ORCA linear --help')).toEqual([])
+    expect(at('ORCA emulator --webcam')).toEqual([
+      expect.stringContaining('--webcam is not a flag of "emulator"')
+    ])
+  })
 })