Onorca

Orca Documentation Audit

Orca is a real, actively-shipping developer product (a desktop "ADE" for running parallel AI coding agents) with a substantial docs tree — but the docs contradict each other on where to register the CLI, whether there's an account system, how mobile pairing works, and they ship a permission-bypass flag for every agent by default while burying it in a footnote. There's also no machine-readable index for the agents the product is built to serve.

1. CLI registration lives in two different settings menus depending on which page you read (critical)

Location: /docs/cli/overview, /docs/cli/reference, /docs/troubleshooting vs /docs/settings, /docs/remote-servers

Problem: Three pages tell you to register the CLI under Settings → Experimental → CLI: /docs/cli/overview ("register it under Settings → Experimental → CLI"), /docs/cli/reference ("Register the CLI under Settings -> Experimental -> CLI"), and /docs/troubleshooting ("Register the CLI under Settings → Experimental → CLI"). But /docs/settings documents it under General ("Orca CLI — register the bundled command-line tool"), and /docs/remote-servers says "install the bundled CLI from Settings -> General -> Orca CLI."

Consequence: A developer (or an agent following the docs) trying to enable the orca command goes to Experimental, doesn't find it, and concludes the feature is missing — or vice versa. This is the literal first step for every CLI, orchestration, and skills workflow on the site, so the contradiction blocks the product's headline automation surface. The troubleshooting page meant to rescue a "command not found" error sends you to the wrong place too.

The fix: Pick one canonical location, fix the other set of pages to match, and add a one-line "as of vX the CLI toggle moved to General" note if it actually moved.

2. Telemetry page asserts "Orca has no account system" while pairing, switching, and usage all depend on one (critical)

Location: /docs/telemetry vs /docs/mobile, homepage

Problem: /docs/telemetry states twice that there is no account: "No account, email, IP address, or user name is collected" and "No user account information (Orca has no account system)." But /docs/mobile's pairing troubleshooting says "make sure your desktop and phone are signed into the same Orca account" and describes "switching agent accounts," and the homepage mobile section says you can "check usage, switch accounts."

Consequence: This is a privacy-trust claim, not a cosmetic one. A security- or compliance-minded developer reads "no account system" as a hard guarantee, then sees account sign-in and account switching on other pages and can't tell whether the telemetry promise is real or sloppy. Either the telemetry copy is wrong (there is an account) or the other pages are using "account" loosely — and the docs never disambiguate, undermining the entire privacy page.

The fix: Define the terms precisely. If "account" elsewhere means a per-agent provider login (Claude/Codex credentials) rather than an Orca-hosted account, say exactly that on the telemetry page and stop using "Orca account" on the mobile page. If Orca does have its own account, remove the "no account system" claim.

3. Mobile pairing is documented two ways, and absolute claims ("no cloud relay", "desktop is always the source of truth") don't account for the headless mode (critical)

Location: /docs/mobile vs /docs/remote-servers

Problem: /docs/mobile describes pairing as: paste a one-time code, "the desktop is always the source of truth," and "Closing the desktop app drops the connection — there is no cloud relay." /docs/remote-servers describes a different mechanism: run a headless orca serve --mobile-pairing on a server with no desktop, then "Scan the Mobile pairing QR." On top of that, /docs/mobile promises "push notifications when an agent finishes" on the same page that says there is no cloud relay.

Consequence: The mobile page states its rules as absolutes ("always," "there is no cloud relay") that the remote-servers page directly contradicts — a phone can pair to a headless orca serve where no desktop is the source of truth. A developer reading either page in isolation can't tell whether serverless pairing is supported. And "no cloud relay" sitting next to "push notifications when an agent finishes" reads as a contradiction the docs never resolve: push delivery to a phone normally rides some external service, so the reader can't reason about where their device token or notifications actually travel.

The fix: Document the two pairing modes side by side (desktop-attached paste flow vs headless orca serve QR flow), scope the "desktop is the source of truth" / "no cloud relay" statements to the desktop-attached mode, and explain how push notifications reach the phone (local network? a notification service?) so the no-relay claim and the push feature are reconciled.

4. Orca pre-fills a permission-bypass flag for every agent by default, documented as a footnote (critical)

Location: /docs/agents/supported (vs /docs/first-session, /docs/install)

Problem: Under "Permissions default," the docs state Orca "pre-fills each supported CLI's permission-bypass flag for new launches" — --dangerously-skip-permissions for Claude, --dangerously-bypass-approvals-and-sandbox for Codex, --yolo for "Gemini / Cursor / Crush / Kimi / Rovo Dev / Hermes / GitHub Copilot / Command Code, plus the equivalent flag for every other agent that exposes one," justified because "worktrees are disposable." This is not surfaced in the quickstart (/docs/first-session, "the single most important page in the docs") where users actually launch their first agent, nor in /docs/install.

Consequence: Flags literally named --dangerously-* and --yolo disable each agent's own approval/sandbox prompts by default, for every agent. A developer who points an agent at a worktree that touches credentials or runs against an SSH/remote target — both flows the same docs actively promote — may never realize approvals were auto-bypassed, because the only place it's stated is a sub-section of the supported-agents page. "Worktrees are disposable" does not hold for the SSH/remote targets in /docs/ssh and /docs/remote-servers, where the working tree is a machine you own.

The fix: Surface this default prominently in /docs/first-session and the onboarding flow, document the exact per-agent flag in a parseable table, document how to turn the bypass off, and make it opt-in (or at minimum loudly flagged) for remote/SSH worktrees where the "disposable" rationale fails.

5. No llms.txt or llms-full.txt for a product whose entire pitch is agents (significant)

Location: /llms.txt (HTTP 404), /llms-full.txt (HTTP 404)

Problem: Both https://www.onorca.dev/llms.txt and /llms-full.txt return 404. Orca ships installable agent "skills" (npx skills add …), an MCP registry, and a CLI explicitly marketed for "scripts or AI agents," yet provides no llms.txt index for its own docs.

Consequence: The product's primary audience — AI coding agents indexing the docs — has no curated entry point and must crawl marketing pages, a collapsed FAQ, and 20+ doc routes to assemble context. For a tool that bills itself as the "Agent Development Environment," shipping no agent-readable docs index is a conspicuous gap and makes the docs harder for the exact consumer Orca courts.

The fix: Publish /llms.txt (a linked index of the doc routes with one-line descriptions) and ideally /llms-full.txt (concatenated docs body). The CLI reference and agents/supported pages are the highest-value entries to list first.

6. The product is branded five different things across its own surfaces (significant)

Location: Homepage, /docs, footer, GitHub README

Problem: The homepage H1 says "Ship 100x With The Agent IDE" while its own body sections call Orca an "ADE (Agent Development Environment)." /docs opens "Orca is a desktop IDE." The footer calls it "The worktree IDE for AI coding agents." The GitHub README tagline is "The AI Orchestrator for 100x builders." That's five labels — Agent IDE, ADE, desktop IDE, worktree IDE, and AI Orchestrator — for one product, including a direct H1-vs-body conflict within the homepage.

Consequence: A developer evaluating the tool — or an agent extracting a one-line description — gets a different category answer on every page. The "ADE, not an IDE" positioning (the homepage even has a section titled "Agent-first, end to end" arguing the ADE distinction) is undercut by the docs and footer literally calling it an IDE, so the central marketing thesis reads as inconsistent.

The fix: Choose one primary noun (the "ADE" framing seems intended) and use it consistently in the homepage H1, footer, /docs intro, and README tagline. If "IDE" is kept as a familiar shorthand, define the ADE→IDE relationship once and stop alternating.

7. Agent name spellings diverge between the README and the canonical supported-agents page (significant)

Location: github.com/stablyai/orca README vs /docs/agents/supported

Problem: The README's agent list names "OpenClaude," "MiMo Code," "oh-my-pi," and "Hermes Agent." The canonical /docs/agents/supported page calls these "OpenClaw," "OMP," "Pi," and "Hermes," and never lists "MiMo Code" at all.

Consequence: Agent identifiers are values users and scripts type (e.g. orca worktree create --agent <name>). When the marketing list and the canonical list disagree on the spelling — OpenClaude vs OpenClaw, oh-my-pi vs Pi/OMP — a developer can't tell which string the combobox or --agent flag actually accepts, and "MiMo Code" appears supported per the README but is undocumented in the reference.

The fix: Make /docs/agents/supported the single source of truth with the exact accepted identifier per agent, regenerate the README list from it, and either document or remove "MiMo Code."

8. Agent count is stated as both 60+ and 25+ on the same homepage (significant)

Location: Homepage hero vs homepage comparison table (vs README enumeration)

Problem: The homepage hero says "Built-in agent support for … and 60+ more." The same homepage's comparison table row reads "25+ built-in agents (Claude, Codex, Gemini…)." Neither matches the README's enumerated list, which names roughly 30 specific agents plus "any CLI agent."

Consequence: Two numbers on a single page (60+ vs 25+) disagree by more than 2x, and neither matches the actual enumerated list. A developer deciding whether their preferred agent is supported gets no reliable count, and the headline "60+" looks inflated against the page's own comparison table.

The fix: Settle on the real supported count and use it everywhere, or replace the count with "any CLI agent" framing (which the README already uses: "if it runs in a terminal, it runs in Orca").

9. Footer copyright is attributed to "Lovecast Inc." — a name that appears nowhere else (significant)

Location: Homepage footer

Problem: The footer reads "© 2026 Lovecast Inc. All rights reserved." Yet the same footer links to "Stably", "Privacy", and "Terms"; the GitHub org is "stablyai" and the README is published under stablyai/orca; and the company is "Backed by Y Combinator." "Lovecast Inc." is not referenced on any other audited surface.

Consequence: Copyright/entity attribution is a legal-trust signal. A developer doing diligence sees a company name in the copyright line that matches nothing else on the site — not the GitHub org, not the "Stably" footer link — and can't tell which legal entity actually operates Orca. A stale-template or wrong-entity footer erodes confidence and muddies who the linked Terms bind them to.

The fix: Correct the footer to the operating entity that owns the Terms/Privacy and GitHub org, or, if Lovecast Inc. is the real holding entity, reconcile it with the rest of the branding and explain the relationship.

10. Usage tracking covers five agents on one page and two on another (significant)

Location: /docs/agents/usage-tracking vs /docs/agents/supported

Problem: /docs/agents/usage-tracking says "Orca reads local usage state for Claude Code, Codex, Gemini, OpenCode, and Kimi Code" (five) and surfaces it in the status bar. But /docs/agents/supported marks the "usage" capability only on Claude Code and Codex ("Deep integration: usage, hot-swap").

Consequence: Usage/rate-limit tracking is a headline feature (the homepage promotes "check usage"). A Gemini, OpenCode, or Kimi Code user reads the usage-tracking page, expects a status-bar readout, and may find nothing — because the capability matrix says it's Claude/Codex-only. Developers can't tell which agents actually get the feature.

The fix: Reconcile the supported scope. If usage tracking truly works for five agents, mark it on all five rows in /docs/agents/supported; otherwise narrow the usage-tracking page to the two the matrix confirms.

11. Bitbucket, Azure DevOps, and Gitea are referenced as supported but never have setup docs (significant)

Location: /docs/review/github

Problem: The provider section states "Bitbucket, Azure DevOps, and Gitea pull requests appear in the worktree sidebar and the Checks panel alongside GitHub and GitLab," and that the worktree flow "checks them for remote conflicts before pushing." But the "Connecting a provider" instructions on the same page only describe GitHub and GitLab, and no connection or setup documentation for Bitbucket, Azure DevOps, or Gitea appears anywhere in the docs.

Consequence: A developer on Bitbucket/Azure DevOps/Gitea reads that their PRs are supported, goes to connect the provider, and finds no instructions on how to authenticate or configure it. The feature is advertised but unreachable from the docs.

The fix: Either add connection/setup docs for the three referenced providers, or scope the claim to what's actually documented and mark the rest as "planned."

12. A second CLI command name orca-ide appears only on one page (significant)

Location: /docs/remote-servers

Problem: /docs/remote-servers notes "On some Linux installs, the registered command may be **orca-ide**; use whichever command is installed." This alternate binary name is mentioned nowhere in /docs/cli/overview, /docs/cli/reference, or /docs/troubleshooting — all of which assume the command is orca.

Consequence: A Linux/server user whose binary is orca-ide follows the CLI reference, types orca status, gets "command not found," and the troubleshooting page (which only knows about orca) can't help. Scripts and the installable skills all hardcode orca. Developers can't tell when orca-ide applies or how to normalize it.

The fix: Document the orca vs orca-ide situation once in /docs/cli/overview and /docs/troubleshooting, explain when each name is installed, and recommend a stable alias so scripts/skills work regardless.

13. The marketing FAQ ships questions with no answers in the static DOM (significant)

Location: Homepage FAQ

Problem: The homepage FAQ accordion renders 11 questions ("What is Orca?", "How does Orca use git worktrees?", "Is Orca free?", etc.) but the answers are collapsed and not present in the static DOM — they don't render for crawlers or non-JS agents.

Consequence: For a product whose stated audience is agents, an agent (or any non-JS fetch) parsing the homepage gets a list of questions and zero answers — the FAQ is invisible to exactly the consumer Orca targets, and to search/AI indexers. The most basic "What is Orca / Is it free" answers are unreachable without executing client JS.

The fix: Server-render the FAQ answers (or include them in the static HTML / an llms.txt) so the content is parseable without JavaScript.

14. WSL is a documented Windows shell on one page and silently absent on two others (minor)

Location: /docs/terminal vs /docs/install, /docs/settings

Problem: /docs/terminal documents three Windows shells: "configurable between PowerShell, Command Prompt, and WSL," including WSL filesystem handling (\\wsl.localhost\…, wsl.exe -d <distro>, /mnt/<drive>/…). But /docs/install says only "PowerShell or CMD," and /docs/settings lists "Windows default shell (PowerShell or CMD)."

Consequence: A Windows developer who works in WSL reads the install and settings pages, sees no WSL support, and may assume Orca can't drive their WSL repos — missing a feature that's fully implemented and documented one page over. The settings page, meant to be the authoritative control reference, omits one of the three actual shell options.

The fix: Add WSL to the Windows-shell description on /docs/install and /docs/settings so all three pages list the same three shells.

15. The install page omits the AUR packages the rest of the docs depend on (minor)

Location: /docs/install vs /docs/remote-servers, GitHub README

Problem: /docs/install lists only AppImage and .deb for Linux, plus a Homebrew cask for macOS. But /docs/remote-servers instructs Linux server users to "install the packaged build from AUR: yay -S stably-orca-bin" (or stably-orca-git to build from source), and the README documents the same AUR packages.

Consequence: Same "documented one page over" gap as the WSL issue: a Linux user who treats /docs/install as the canonical install reference never learns the AUR packages exist, and the remote-servers flow assumes a package the install page never introduced.

The fix: Add the AUR packages (stably-orca-bin, stably-orca-git) to the Linux section of /docs/install so the canonical install page lists every supported distribution channel.

16. The terminal is called both "the same xterm.js terminal VS Code uses" and a bespoke "Ghostty-class terminal w/ WebGL" (minor)

Location: /docs/terminal vs homepage

Problem: /docs/terminal says the terminal is "the same xterm.js-based terminal VS Code uses, with a few additions." The homepage markets a "Ghostty-class terminal w/ WebGL + splits" and "Ghostty-inspired terminals," and lists "Ghostty-class terminal w/ WebGL + splits" as a comparison-table differentiator versus other tools.

Consequence: A developer reads two different stories about what the terminal actually is — a commodity VS Code component versus a bespoke high-performance renderer — and can't tell which is the real capability they're evaluating. (xterm.js does ship a WebGL renderer addon, so these may be reconcilable, but the docs never say so — leaving the marketing claim and the technical doc looking like they describe different products.)

The fix: State the relationship once: e.g. "built on xterm.js with the WebGL renderer and Ghostty-inspired theming/splits." Then use consistent language on the homepage and /docs/terminal.

17. Codex and Claude hot-swap are called "identical" on one page and described differently on the other (minor)

Location: /docs/agents/codex-hot-swap vs /docs/agents/claude-code

Problem: /docs/agents/codex-hot-swap says swapping "is instant — Orca rewrites the active credential pointer, it does not re-authenticate," and "The same flow works for Claude Code accounts" / "works identically." But /docs/agents/claude-code says the Claude swap "holds the in-progress switch behind a guard so you don't trigger overlapping auth refreshes" — implying auth-refresh behavior the Codex page says doesn't happen.

Consequence: A developer relying on "instant, no re-auth, identical" for Claude may be surprised by the guarded behavior during live sessions (e.g. a switch that waits). The canonical Claude-swap details only live on the Codex page, so the two descriptions can't be reconciled without reading both.

The fix: Document the Claude swap's guard behavior on /docs/agents/codex-hot-swap (or stop calling the flows "identical") so the two pages describe the same mechanism.

18. The "bring your own subscription" list is narrower than the supported-agents set (minor)

Location: /docs intro vs /docs/agents/supported, /docs/first-session

Problem: /docs ("What is Orca?") frames BYO as "bring your own Claude, Codex, or OpenCode subscription" (and lists "Claude, Codex, or Cursor CLI" as the agents you "already pay for"). But /docs/agents/supported and /docs/first-session name Gemini, Cursor CLI, and many more as supported agents whose credentials Orca forwards.

Consequence: The "what do I need to bring" list looks narrower than the actual supported set. A Gemini or Cursor user reading the intro can't tell whether their subscription is usable, even though other pages confirm it is. The intro page also disagrees with itself on which three agents it names.

The fix: Make the BYO list match the supported-agents page, or replace the enumerated list with "any supported agent's subscription" and link to /docs/agents/supported.

What they do well

• /docs/review/commit-push and /docs/ssh are exemplary — internally consistent, specific about real git semantics (--force-with-lease, no silent force-push, explicit amend confirmation) and honest about platform caveats (remote-file Download is "desktop-only … relies on Electron's save dialog").
• The CLI surface is genuinely rich and example-heavy — worktree, terminal, browser-automation, and orchestration commands come with copy-pasteable --json examples and a clear agent-skills install path (npx skills add …).
• The telemetry page (its self-contradiction aside) is unusually candid — naming the vendor (PostHog Cloud, US region), the kill-switches (DO_NOT_TRACK=1, ORCA_TELEMETRY_DISABLED=1), and an explicit "what we never send" list.

Top 3 recommendations

1. Fix the contradictions that break setup or trust first — one canonical CLI-registration location (issue 1), a single answer to "is there an account system" (issue 2), one mobile-pairing model with consistent transport claims (issue 3), and — most importantly — surface the per-agent permission-bypass default where users actually launch agents and make it opt-in for remote/SSH targets (issue 4). These are where a developer or agent gets stuck, or unknowingly disables safety prompts.
2. Make the docs agent-readable — ship /llms.txt (and ideally /llms-full.txt), server-render the FAQ answers, and make /docs/agents/supported the single source of truth for agent identifiers and per-agent capabilities (usage tracking, hot-swap). The product targets agents; the docs should be parseable by them.
3. Pick one name and one set of facts — converge the IDE/ADE/Orchestrator branding (5 labels), the 25+/60+ agent count, the supported-agent spellings, the footer's legal entity, and the install channels (WSL, AUR) so the canonical pages stop disagreeing with the marketing surfaces and with each other.