* feat(skills): ship orca-cli as a first-generation hybrid stub
Convert the installable orca-cli SKILL.md from a full fat guide into a
hybrid discovery stub: a safe CLI resolver, an `orca skills get orca-cli`
pointer, and a bounded read-only fallback for pre-guide binaries. The
version-matched command reference now lives only in the Orca binary
(embedded guide table, served by `orca skills get`), so the distributed
file can no longer drift from the binary that runs the commands.
- generator projects STUB_TOPICS from skill-stubs/<name>.md, reusing the
guide's own frontmatter so the routing/description surface is unchanged;
the embedded full guide (bundled-skill-guides.ts) is untouched.
- manifest regenerated: orca-cli releaseRevision 32->33 as an append-only
snapshot; existing fat installs classify `outdated` and get the targeted
`npx skills update` nudge (no in-app writes).
- tests: command-guidance assertions repointed to the guide source (their
home now), plus stub-projection + safety coverage.
Only orca-cli converts; the other skills stay fat. Per
notes/skill-freshness-design.md, the E.3 pointer-compliance spike and the
E.5 RC window remain before any further thinning. allowed-tools is
intentionally not added yet (frontmatter kept byte-identical to the guide).
* fix(skills): distinguish guide lookup failures
* chore(skills): refresh released skill mapping
* Add version-matched bundled skill guides
* Clarify skill freshness rollout PRs
* Add canonical skills show alias
* fix(skills): address guide review feedback
* fix(skills): make guide commands cross-platform
* fix(skills): apply the ORCA convention to the emulator guides
Review follow-up: the emulator guides still instructed literal
`orca emulator ...` in sh fences with no Linux disambiguation, so on
unmanaged Linux they could launch the GNOME screen reader — the exact
failure the executable-selection preamble prevents. Both emulator
guides now carry the preamble and ORCA placeholder across fences,
tables, and prose, and the cross-platform safety test covers all four
converted guides. Also replaces computer-use's "unless a block names a
shell" carve-out, which contradicted its own POSIX example, with the
unconditional placeholder rule.
On Linux the CLI installs as orca-ide so it never shadows /usr/bin/orca
(GNOME's screen reader), but agent-facing surfaces (orca-cli skill,
dispatch preambles, CLI hints) all invoke bare `orca` — so on stock
Ubuntu an agent inside an Orca terminal launched the screen reader,
which started speaking (#7904).
Fix: prepend a userData-scoped shim dir (bare `orca` -> bundled
orca-ide launcher, or the stable AppImage) to the PATH of every
packaged-Linux managed PTY, mirroring the existing dev-mode cli/bin
prepend. The user's own shells — and their real screen reader command —
stay untouched. Also flip the orca-cli skill probe to prefer orca-ide
so agents outside Orca terminals never execute the screen reader.
Fixes#7904
Co-authored-by: Orca <help@stably.ai>
* fix(runtime): explain full worktree id selectors (#7432)
* Fix full worktree id selectors for bare repo ids and doc guidance
- Reject bare repo-id selectors up front via a shared validator instead
of relying on worktree-list scanning, so RPC callers no longer trigger
an unnecessary rescan just to detect the mistake
- Propagate the structured worktree_id_requires_full_path code through
RPC error mapping so callers get a typed error, not just a message
- Update orca-cli, orca-emulator, and orchestration skill docs to show
the full `<repo-id>::<path>` id shape and stop implying a bare repo
id is a valid worktree selector
---------
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
* skills: prefer agent-first worktree launch; avoid empty shell tabs
Document Orca's first-terminal behavior so agents do not leave dead
shell tabs: --agent runs in the first terminal (one tab), bare
worktree create + terminal create leaves shell + agent (two tabs).
Also: re-resolve live handles via terminal list after create, message
one handle only, and prefer orchestration check --inject over terminal
send for pure orchestration pings. Aligns with CLI docs
(--agent launches the selected agent in the first terminal).
* fix skill guidance for agent-first worktrees
---------
Co-authored-by: Jinjing <6427696+AmethystLiang@users.noreply.github.com>
- Explain that `--no-parent` only controls Orca lineage, not the Git
base branch, and detail how to target independent top-level work.
- Define full handoffs as ownership transfer and forbid the use of
orchestration dispatch injection for them.
- Update CLI help text for `orca worktree create` to reflect the
lineage and base-branch guidance.
- Add tests to verify that these guidance patterns exist in the skill
markdown files.
- Document and update the CLI help, specs, and tests to explicitly guide
users toward `orca terminal create --worktree active --command <agent>`
to launch a fresh agent session in the current checkout.
- Update orchestration and orca-cli skills to prefer active-worktree
terminals when dependent on uncommitted files or active branch state,
distinguishing them from separate worktree creation.
Adds an RPM Linux package target and renames the Linux CLI command to orca-ide to avoid shadowing GNOME Orca, while preserving macOS and Windows CLI command behavior.\n\nFollow-up hardening keeps the Linux launcher executable, removes only old Orca-managed Linux/WSL orca launchers during migration, preserves AppImage/deb artifact names, and updates package/release tests for the RPM asset.
Sharpens the routing boundary so agents reliably pick the right skill:
orchestration owns agent-to-agent messaging (writes that target another
AI agent's terminal), while orca-cli owns worktrees, browser, and
non-agent terminal I/O — including reads and waits on agent terminals.
Validated against adversarial routing tests.
Co-authored-by: Orca <help@stably.ai>
* fix(skills): remove broken doc references in orca-cli SKILL.md
Three files listed under ## References do not exist in the repository:
docs/orca-cli-focused-v1-status.md, docs/orca-cli-v1-spec.md, and
docs/orca-runtime-layer-design.md. Agents following the skill would hit
dead links when trying to resolve ambiguous CLI behavior. Replace the
stale list with a general pointer to the docs/ directory.
Co-Authored-By: Claude Code <noreply@anthropic.com>
* docs: remove stale Orca CLI doc index
---------
Co-authored-by: claude[bot] <claude[bot]@users.noreply.github.com>
Co-authored-by: Claude Code <noreply@anthropic.com>
Co-authored-by: Neil <4138956+nwparker@users.noreply.github.com>
Add guidance for coding agents to keep worktree comments updated at meaningful
checkpoints, making work-in-progress status visible in the Orca UI without
explicit user requests.
Jinwoo Hong
Jinjing
Brennan Benson
NeilandOrca
Rod BoevandJinjing
ryushioneandJinjing
WolfieandWolfgang Schoenberger
Emad Fussi
