[Jinwoo-H]

	Files	Added	Deleted	Net
Test	5	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​183	$\color{#cf222e}{\Huge{\mathbf{−}}}$​28	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​155
Prod	12	$\color{#1a7f37}{\Huge{\mathbf{+}}}$​1691	$\color{#cf222e}{\Huge{\mathbf{−}}}$​3792	$\color{#cf222e}{\Huge{\mathbf{−}}}$​2101

ELI5

The Orca CLI skill that Browser Use setup installs was telling agents about Orca's public-link publishing even when the user had publishing turned off. An agent asked for "a public link" could pick Orca and then ask the user to flip a setting. Now agents only learn about publishing when this Orca actually has it switched on, and even then only use it when the user asks for Orca by name.

What Changed

• Discovery metadata: the orca-cli skill description no longer advertises artifacts or skill sharing. This text is installed globally, so it cannot depend on a setting.
• Host-gated guide text: skill-guides/orca-cli.md and its references wrap publishing text in <!-- host-capability: … --> blocks. orca skills get asks the runtime it targets (settings.get, 2 s timeout) and serves a block only when that feature is on: artifactSharingEnabled for artifacts, agentSkillSharingEnabled for skill sharing. Skill sharing is also withheld for forwarded and remote invocations, which skills share refuses. Anything unreadable (Orca not running, sandboxed socket, headless or older host) withholds the text. This applies to the main guide, --full, --references, and --reference; asking for a withheld reference gives a short "turned off on this host" error.
• Explicit intent: when publishing is on, the guide says to use it only when the user asks to publish through Orca. A generic request for a public link does not select Orca, and a provider the user names wins. Denied-share recovery no longer tells the agent to ask the user to turn the setting on, unless the user asked for Orca by name.
• References: references/publishing.md is split into artifacts.md and skill-sharing.md so each can be gated on its own feature.
• --full is now put together when the command runs instead of at build time, so withheld references leave nothing behind. Output for every ungated guide is byte-identical to before (checked against a snapshot of all ten guides). The generated table also drops its duplicate copy of each reference.
• skills get contacts the runtime only when the text it serves has a gated block. Every other guide and reference stays local-only.

Why

Fixes STA-12225: Linear. Browser Use setup installs orca-cli globally, so its publishing text reached agents outside Orca. Publishing is off by default, so for most users that text was a dead end that turned into a settings detour.

Alternatives considered:

• Wording only: leaves the off-by-default feature advertised everywhere.
• A separate publishing skill installed from Settings: a settings toggle would then install and remove skills globally, and update-only runs could bring back skills the user removed.

Gating at serve time keeps one skill and needs no install migration. The runtime permission checks in artifacts share/update and skills share are unchanged and remain the real gate.

Existing installs: the guide is served live by the installed CLI, so updating Orca fixes the guide text for every existing install. The changed stub description reaches installs through the existing skill freshness nudge / Update skills flow. That flow is installed-only, so it never re-adds removed skills, and the released-digest ledger still recognizes the previous stub.

Linked Issue

STA-12225 (Linear)

Visual Proof

N/A: no UI change. The change is to the text that orca skills get serves.

Testing

• I manually tested these changes locally: ran skills get orca-cli --references against a live local Orca with both permissions on (all four references listed, about 1.2 s total).

• Automated tests added/updated: skill-guide-host-gate.test.ts drives orca skills get through main() with a mocked runtime and covers:

  • off, headless/older, and unreachable hosts across the guide, --full, --references, and --reference
  • an enabled host, which is queried once
  • remote and forwarded skill-sharing withholding
  • an ungated reference that never contacts the host
  • that every shipped block is well-formed and names a known capability

  A mutation that bypasses the gate fails 5 of the 8 tests.

• pnpm tc and the generated-artifact verifiers pass. A local pnpm check:changed run found only formatting and two type casts in the new test; both are fixed, and CI covers the rest.

Model selection itself (whether an agent picks a provider) is not unit-testable here. These tests cover what each host serves.

Review

Agent skill upstream boundary

• Not applicable, or this change copies or mechanically translates no upstream skill-installer source, tests, fixtures, registry entries, path tables, comments, or documentation.

Notes

• Cross-platform: no platform-specific code. The runtime call uses the existing CLI transport.
• Remote / mixed versions: the guide comes from the CLI on the host where the agent runs. A host that cannot report the setting withholds the text, which is safe because publishing is off by default. Older CLIs keep serving their old text until updated.
• Mobile: N/A.
• Folder workspaces: N/A.
• Performance: one local RPC, only for the gated orca-cli guide.
• Known gap: with an ambient ORCA_ENVIRONMENT, the guide asks the selected runtime, but artifacts commands always use the local desktop runtime. In that case artifact text can be withheld even though sharing would work. The mismatch only ever withholds text; it never shows text for a feature that is off.

Checklist

• This PR is small and focused
• I explained what changed and why (ELI5, the user-facing before/after, the mechanism, and why over the alternatives)
• Before/after screenshots or videos attached for UI changes, or N/A with reason
• Self-reviewed for correctness, security, and performance
• Cross-platform, SSH/remote, and path/shortcut impact considered (or N/A)
• pnpm lint, pnpm typecheck, pnpm test, and pnpm build pass (or CI will cover; local preferred)

[coderabbitai]

Walkthrough

The bundled guide generator no longer emits combined full Markdown. The skills handler composes full output from the guide and available references, filtering host-gated content using host settings. The Orca CLI guide and references update publishing instructions, and related skill metadata and digest records change.

Priority: Normal

Merge Risk: Low · up to 1efa6

Users may have difficulty finding how to revoke existing artifact links when publishing is disabled. Keep revocation guidance available; this is a bounded issue rather than a merge blocker.

Pre-merge checks: 4 · 1

Failed checks: 1 warning

Check name	Status	Explanation	Resolution
Docstring Coverage		Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surv…	Write docstrings for the functions missing them to satisfy the coverage threshold.

Passed checks: 4 passed

Check name	Status	Explanation
Title check		The title "Show Orca publishing guidance only when the host has it on" matches the main change: the orca-cli guide text is now gated at serve time by the host's artifact and skill-sharing settings. Th…
Description check		The description follows the repository template and fills in every required section. It has an ELI5 section, a What Changed section with the before and after and the gating mechanism, a Why section wi…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Title check

Explanation

The title "Show Orca publishing guidance only when the host has it on" matches the main change: the orca-cli guide text is now gated at serve time by the host's artifact and skill-sharing settings. The title is specific and concise, and it names the user-visible behavior rather than the mechanism. It does not mention the removed description text or the reference split, but that detail is not needed for the primary change.

Full details: Description check

Explanation

The description follows the repository template and fills in every required section. It has an ELI5 section, a What Changed section with the before and after and the gating mechanism, a Why section with alternatives considered, a Linked Issue (STA-12225), N/A for Visual Proof with a reason, a Testing section with manual and automated results, Notes on cross-platform, remote, and performance impact, and a completed checklist. The Review and Agent skill upstream boundary sections are also filled in. The AI Disclosure section is blank, which the template allows for internal contributors. The Linked Issue uses a Linear reference, not a GitHub issue number. The 'Fixes #' line from the template was replaced, so a maintainer may want to confirm this meets the repository's linking requirement.

Full details: Docstring Coverage

Explanation

Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 12 functions across 8 files. (6 skipped: 6 unsupported.)

Resolution

Write docstrings for the functions missing them to satisfy the coverage threshold.

Finishing Touches: 💡 1

📝 Generate docstrings: 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

---

Review info

Run configuration

• Source mode: Auto
• Repository: Unavailable
• Branch: Unavailable
• File: No configuration file from this repository applied
• Commit: Unavailable
• Layers: Repository UI
• Review profile: CHILL
• Plan: Advanced
• Run ID: 86cbe5dd-a3f9-4960-8741-0fdd3dda8f18

Commits

Reviewing files that changed from the base of the PR and between 84decfd and 1efa659.

Files selected for processing: 17

• config/scripts/generate-bundled-skill-guides.mjs
• config/scripts/generate-bundled-skill-guides.test.mjs
• resources/skills/current-manifest.json
• resources/skills/released-digests.json
• skill-guides/orca-cli.md
• skill-guides/orca-cli/references/artifacts.md
• skill-guides/orca-cli/references/skill-sharing.md
• skills/orca-cli/SKILL.md
• src/cli/bundled-skill-guides.ts
• src/cli/handlers/bundled-skill-guide-table.ts
• src/cli/handlers/skill-guide-get.ts
• src/cli/handlers/skill-guide-host-gate.test.ts
• src/cli/handlers/skill-guide-host-gate.ts
• src/cli/skills-reference-selector.test.ts
• src/cli/skills.test.ts
• src/cli/specs/bundled-guide-flags.test.ts
• src/main/skills/bundled-skill-install/bundled-skill-sources.ts

Files with no reviewable changes: 2

• src/cli/handlers/bundled-skill-guide-table.ts
• src/cli/skills-reference-selector.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 7 remain after this review.

[coderabbitai]

Minor · Functional Correctness · Quick win

Keep artifact revocation guidance available when publishing is off.

When artifactSharingEnabled is false, the host gate removes this entire reference. skills get orca-cli --reference artifacts then rejects the request. The guide says list, unshare, and delete remain available, but an agent cannot load their commands or the path and token rules needed to revoke an existing public link. Put those commands in an ungated reference; gate only share and update guidance. (raw.githubusercontent.com)