[bbingz]

Summary

Headless orca serve operators already had orca skills install / update in the Linux server reference, but not a full path for discovering skills, installing the common serve set (CLI, orchestration, Linear, computer-use), handling integrations/secrets, or verifying after upgrade.

• Catalog version-matched skills and skills get for reading without install
• Common install recipes for orchestration / Linear / computer-use
• Host-side integration and secret handling (gh, Linear, display/a11y)
• Update/verify after package upgrades; clarify install runs on the serve machine

Fixes #11885

Test plan

• pnpm exec vitest run src/main/startup/single-instance-lock-headless-exit.test.ts

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: dfc298ff-b25a-4fdb-9fa8-af4a4c6f3f3c

📥 Commits

Reviewing files that changed from the base of the PR and between dd8d81e263061dce378e0857aa754c5f0036cb30 and 72261ca.

📒 Files selected for processing (1)

• docs/reference/headless-linux-server.md

🚧 Files skipped from review as they are similar to previous changes (1)

• docs/reference/headless-linux-server.md

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The headless Linux server guide now documents commands for inspecting bundled skills and reading guides. It adds skill installation examples, verification steps, integration requirements, credential handling, and host-specific requirements. It also explains how to refresh skills after upgrades and clarifies that install and update commands run on the executing host, with SSH and WSL forwarding behavior documented.

Priority: ⬇️ Low

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description explains the main documentation changes, includes issue #11885, and records one test. However, it does not use the required template sections and omits required content such as ELI5, e…	Rewrite the description using the repository template. Complete ELI5, What Changed, Why, Linked Issue, Visual Proof, Testing, AI Disclosure, Review, Agent skill upstream boundary, Notes, and Checklist sections. Mark Visual Proof as N/A with…

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly identifies the documentation change: expanding the headless serve host agent-skills installation guide.
Linked Issues check	✅ Passed	The changes meet the coding requirements in #11885. The guide documents bundled-skill discovery, skills get limitations, installation for orca-cli, orchestration, orca-linear, and `computer-us…
Out of Scope Changes check	✅ Passed	The diff is limited to docs/reference/headless-linux-server.md. The added tables, commands, integration guidance, deployment notes, verification steps, and update workflow directly support #11885. N…
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…

Full details: Description check

Explanation

The description explains the main documentation changes, includes issue #11885, and records one test. However, it does not use the required template sections and omits required content such as ELI5, explicit What Changed and Why sections, Visual Proof or N/A, review notes, upstream-boundary confirmation, and checklist status.

Resolution

Rewrite the description using the repository template. Complete ELI5, What Changed, Why, Linked Issue, Visual Proof, Testing, AI Disclosure, Review, Agent skill upstream boundary, Notes, and Checklist sections. Mark Visual Proof as N/A with a reason if no UI or interaction changes exist, and document the relevant validation and platform considerations.

• Fix all pre-merge checks with AI

---

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: 3

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bb86e594-e075-4b83-afb1-9caa7c2ceb9c

📥 Commits

Reviewing files that changed from the base of the PR and between 04f7123 and 1f2d460bb5d750f2af865f26ca503b20dbfa8b05.

📒 Files selected for processing (1)

• docs/reference/headless-linux-server.md

[bbingz]

Review follow-up (batch 4)

Addressed confirmed medium findings from campaign review:

1. Linear setup — document real path: connect against this host runtime from a paired client; tokens under ~/.orca via safeStorage (no skill-documented env secret path / no orca linear connect CLI). Verify with orca linear team list.
2. Post-install verification — orca skills get only dumps bundled CLI guides; install proof is install exit + agent skills list / path.
3. computer-use — AT-SPI + session bus (XDG_RUNTIME_DIR / DBUS_SESSION_BUS_ADDRESS), not macOS accessibility + Xvfb alone; probe via orca computer capabilities --json.

Also prefer orca-linear over dual install of legacy linear-tickets.

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

docs/reference/headless-linux-server.md (1)

789-790: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Use update or reinstall to refresh agent-side guides.

orca skills get and rereading a guide only display the bundled guide. They do not update copies already installed for agents. Replace “re-read or re-install” with “run orca skills update or reinstall” so this section matches the later upgrade procedure.

♻️ Duplicate comments (1)

docs/reference/headless-linux-server.md (1)

860-867: ⚠️ Potential issue | 🟠 Major

Keep GH_TOKEN out of agent environments.

The guide permits GH_TOKEN in the environment of the same user that runs agents, then recommends environment variables. If orca serve inherits that variable, child agent processes can read it. Document gh credential-store authentication or a helper that injects GH_TOKEN only for the gh command. Verify child-process environment filtering before retaining this guidance.

#!/bin/bash
set -euo pipefail
rg -n -C 8 'GH_TOKEN|GITHUB_TOKEN|process\.env|spawn|fork|exec|env:' . \
  --glob '!node_modules' --glob '!dist' --glob '!build' || true

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 767ab795-7e69-4eea-a09b-871d61eb1ff1

📥 Commits

Reviewing files that changed from the base of the PR and between 1f2d460bb5d750f2af865f26ca503b20dbfa8b05 and 498264d285ffa8399ebbec8e9fb1db4367353308.

📒 Files selected for processing (1)

• docs/reference/headless-linux-server.md

[bbingz]

Closing: docs/reference/headless-linux-server.md was removed in #26328, and the npx-based install steps no longer match #31688.