[nwparker]

ELI5

Remove the reference notes that have drifted from the implementation. Orca behaves the same; contributors can use the code and tests, with older notes still available in Git history.

What Changed

• Delete all 64 tracked files under docs/reference and remove their .gitignore exceptions.
• Remove links from the README and its translations, contributor guidance, agent instructions, PR template, and reliability manifest. Keep the existing inline engineering rules.
• Remove the Antigravity assertion and three headless-server example checks that read deleted documents. Keep the captured-transcript readiness tests, fixtures, and startup-code checks unchanged.
• Fix an inherited CI failure in the Claude hook lifecycle test: close each relay HTTP connection so advancing fake time cannot race reuse of an expired socket. Production hook handling is unchanged.

Why

These implementation notes are out of sync with the code. Removing the directory avoids continuing to maintain a second description of the implementation. Keeping the existing inline rules avoids discarding the constraints already documented in AGENTS.md.

Linked Issue

N/A — maintainer-requested cleanup.

Visual Proof

N/A — no UI or interaction changes.

Testing

• I manually tested these changes locally
• Automated tests added/updated, or explained why not below

Full CI run passed all ten test shards, static analysis and typechecking, Node 18 hooks, relay integration, repository guards, and final verification.

Validated on macOS:

• ORCA_BACKGROUND_LAUNCH=1 pnpm test src/main/startup/single-instance-lock-headless-exit.test.ts src/main/agent-hooks/server-claude-task-wakeup-lifecycle.test.ts src/main/runtime/antigravity-readiness-transcripts.test.ts — 69 passed, 10 existing skips.
• ORCA_BACKGROUND_LAUNCH=1 pnpm tc:node — passed.
• pnpm run check:code-quality:changed — passed.
• pnpm run check:readme-local-links — passed.
• pnpm run check:reliability-gates — passed.
• git diff --cached --check — passed before committing.

No new tests needed for document deletion. The removed assertions checked fixture names and server examples in deleted documents, not runtime behavior. Full builds and platform UI tests were not run because runtime implementation is unchanged.

Review

Checked build and packaging configuration, public docs sources, and repository references. Electron packaging excludes docs; the public documentation site uses docs/site/content/docs.

Agent skill upstream boundary

• Not applicable; this change copies or mechanically translates no upstream skill-installer material.

Notes

The directory also contained contributor and headless-server guidance, so this intentionally removes that documentation. Historical references remain in code comments, diagnostic text, and an older implementation checklist; those paths will no longer resolve in the current checkout. This does not change execution on macOS, Linux, Windows, SSH hosts, mobile, or folder workspaces.

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]

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: fa3bc1b6-4141-4593-ba8e-c374918e85dd

📥 Commits

Reviewing files that changed from the base of the PR and between e4e6c57 and f349dd9.

📒 Files selected for processing (1)

• src/main/startup/single-instance-lock-headless-exit.test.ts

💤 Files with no reviewable changes (1)

• src/main/startup/single-instance-lock-headless-exit.test.ts

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

---

📝 Walkthrough

Walkthrough

The pull request deletes the docs/reference/ documents and removes their ignore exceptions. It removes links to those documents from repository guidance, installation notes, and a reliability-gate entry. The pull request template changes its upstream-boundary checkbox. The transcript test no longer checks the deleted readiness evidence document; its readiness expectations remain unchanged. The startup test replaces documentation-based systemd assertions with source-text checks. A remote-hook test helper adds a connection-close request header.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to f349d

This is a documentation cleanup with small test adjustments, and runtime behavior is unchanged. No merge-blocking risk was identified.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly identifies the primary change: removing stale internal reference documentation.
Description check	✅ Passed	The description follows the required template, explains the scope and rationale, records testing and review details, and addresses the maintainer exception for the linked issue. The final command chec…

• Fix all pre-merge checks with AI

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Commit to this branch
• Create a new PR

• Autopilot · 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.}