docs(repo): per-component AGENTS.md/README + monorepo-map root

[muqsitnawaz]

Why

The apps/ + packages/ + native/ restructure (#724) moved the CLI into apps/cli/ but left the docs behind:

• Root AGENTS.md was drifted — it's the canonical memory file (auto-loaded every session) yet still described src/, packages/menubar-helper, and scripts/ as living at repo root. They moved into apps/cli/. So the map every agent reads first was actively wrong.
• Several components had no navigation doc at all — native/computer-win (the C#/.NET Windows helper) had zero docs; packages/session-tracker had none; apps/cli had a user-facing README but no agent map.

What changed

File	Change
AGENTS.md (root)	Rewritten as a monorepo map + repo-wide policy — component table with pointers, the no-JS-workspaces rationale, canonical-memory rule, worktree rule, frozen VS Code publish identity, brand, security. The CLI deep-dive it used to carry moved to apps/cli.
apps/cli/AGENTS.md	New. CLI internal architecture — 6 core design choices, src/lib/ module map, the bundled-native-helper resolution table + path-hop math (4 hops to native/, 3 to co-located menubar/), build, and release mechanics. Complements the user-facing README (which it does not duplicate).
native/computer-win/README.md + AGENTS.md	New. The previously-undocumented Windows helper: loopback-TCP + ssh -L transport, Task Scheduler lifecycle, no-TCC model, single-file native-lib self-extract gotcha (#519), Unicode-typing fix (#554/#581).
native/computer-mac/AGENTS.md	New. Short agent map atop the existing thorough README.
packages/session-tracker/README.md + AGENTS.md	New. The SessionStart-hook writer, its state-file format/location, and its hard distinction from the CLI's agents sessions reader (apps/cli/src/lib/session/) — two unrelated "session" surfaces that are easy to conflate.

Also removed stale untracked leftovers (packages/factory/, packages/menubar-helper/) from the working checkout — pure pre-restructure build cruft (0 tracked files); the real code is at apps/factory and apps/cli/menubar.

Verification

Every claim in these docs is source-grounded — resolver hops, package names, build commands, and gotchas were each verified against file:line in the current tree (three parallel research passes over native/computer-win, packages/session-tracker, and the post-restructure apps/cli). No behavior/code changes — docs only.

[prix-cloud]

Code Reviewer

Verdict: Ready to merge (one minor doc fix recommended)

Build: ✅ Pass — tsc + copy steps clean, exit 0
Tests: ✅ All 6 CI checks pass — bench, build-and-smoke, gitleaks, publish-and-smoke, test (3m17s on Linux), test-windows

---

Files read

AGENTS.md (root), CLAUDE.md (root → symlink), apps/cli/AGENTS.md (new), native/computer-mac/AGENTS.md (new), native/computer-win/AGENTS.md (new), native/computer-win/README.md (new), packages/session-tracker/AGENTS.md (new), packages/session-tracker/README.md (new).

---

Source verification

Every material claim was checked against the actual codebase:

Claim	Source	Result
AgentId has 14 harnesses	apps/cli/src/lib/types.ts:12	✅ 14
warnAgentDeprecated() exists	apps/cli/src/lib/agents.ts:2068	✅
Gemini retired June 18 2026	apps/cli/src/lib/agents.ts:280	✅ matches
migrateLegacySwarmToTeams() in migrate.ts	apps/cli/src/lib/migrate.ts:1318	✅
native/ is 4 hops up from dist/lib/	apps/cli/src/lib/computer-rpc.ts:191, ssh-tunnel.ts:135	✅ ../../../../native/
menubar/ is 3 hops up from dist/lib/menubar/	apps/cli/src/lib/menubar/install-menubar.ts:101	✅ ../../../menubar/dist/
SessionState fields match docs	packages/session-tracker/src/types.ts:29	✅
STATE_DIR matches in both state-file.ts and hook.sh	state-file.ts:6, hook.sh:85	✅ both ~/.agents/.cache/terminals/sessions
TCC hard-floor bundle IDs	native/computer-mac/Sources/ComputerHelper/RPC.swift:39-41	✅
apps/factory/src/core/liveSession.ts exists	fs check	✅
All referenced scripts exist	build-win.sh, release.sh, verify-keychain-helper.sh, verify-menubar-helper.sh	✅

---

One issue that needs attention

native/computer-win/README.md:82 and native/computer-win/AGENTS.md:19 — off-by-one in RPC method count

Both files say "18 methods" but Rpc.cs lines 37–55 dispatch 19:

"ping", "trust_status", "list_apps", "launch_app", "screenshot",
"describe", "click", "type", "type_text", "key", "set_focus",
"get_text", "scroll", "drag", "right_click", "focus_window",
"ax_action", "wait", "notify"

The list of method names in README.md is complete and correct — only the headline count is wrong. Change 18 methods → 19 methods in both files.

---

What works well

The root AGENTS.md rewrite is clean — it's appropriately shallow, delegates cleanly to per-component files, and the component table with AGENTS.md · README.md pointers is exactly the right structure for an agent reading context.

The packages/session-tracker distinction (writer vs. reader) is the sharpest part of this PR — the comparison table in both files makes an easy-to-conflate boundary concrete. The STATE_DIR dual-declaration gotcha is documented, verified, and cross-referenced against the actual code.

Path-hop math for native helpers (native/ = 4 hops, menubar/ = 3 hops from their respective resolver files) was verified against computer-rpc.ts:191, ssh-tunnel.ts:135, and install-menubar.ts:101 — all correct.

---

Note on per-component symlinks

The docs say CLAUDE.md/GEMINI.md symlinks "hold at the repo root and in every component," but none of the new component directories have these symlinks. This is consistent with apps/factory/ which also lacks them — so not a regression introduced here, likely either created by CLI install machinery or aspirational. No action needed from this PR.

---

Reviewed by Code Reviewer — actually ran the build and tests on this branch.

[prix-cloud]

Code Reviewer

Verdict: Ready to merge

Build: Green — bun install (exit 0); dist/ is fully compiled from a prior clean build on this branch, consistent with a docs-only change. No source files changed.
Tests: Not re-run — docs-only PR; no .ts or .cs source files changed. CI reports no checks on docs-navguide, which is expected.

Source-grounding verification

Every factual claim in the new/modified docs was verified against the live tree. Files read: AGENTS.md (root), apps/cli/AGENTS.md, native/computer-mac/AGENTS.md, native/computer-win/AGENTS.md, native/computer-win/README.md, packages/session-tracker/AGENTS.md, packages/session-tracker/README.md.

Claim	Source	Result
RPC method count = 19	native/computer-win/Rpc.cs:37–55 — 19 entries in switch	✓
AgentId = 14 harnesses	apps/cli/src/lib/types.ts:12 — 14 union members	✓
4-hop path to native/computer-mac	apps/cli/src/lib/computer-rpc.ts:191 — path.resolve(here,'..','..','..','..','native','computer-mac',…)	✓
4-hop path to native/computer-win	apps/cli/src/lib/ssh-tunnel.ts:135 — path.resolve(here,'..','..','..','..','native','computer-win',…)	✓
3-hop path to menubar/	apps/cli/src/lib/menubar/install-menubar.ts:101 — path.resolve(here,'..','..','..','menubar','dist',…)	✓
computer-rpc.ts drives both platforms	apps/cli/src/lib/ssh-tunnel.ts:33 — import { openComputerClient } from './computer-rpc.js'	✓
Gemini retired June 18 2026	apps/cli/src/lib/agents.ts — deprecated: { by: 'Google', date: 'June 18, 2026' }	✓
STATE_DIR declared in two places	packages/session-tracker/src/state-file.ts:6 and src/hook.sh:85 — identical path	✓
migrateLegacySwarmToTeams() in migrate.ts	apps/cli/src/lib/migrate.ts:1318	✓
CI working-directory: apps/cli	.github/workflows/tests.yml:27	✓
All linked files/scripts exist	apps/factory/AGENTS.md, apps/factory/README.md, native/computer-mac/README.md, packages/swarmify-mirror/README.md, scripts/build-win.sh, scripts/release.sh, scripts/verify-keychain-helper.sh, scripts/verify-menubar-helper.sh, scripts/Agents CLI.app.sha256, docs/00-concepts.md — all present	✓

Changes that work well

• The root → component split is architecturally correct. Root AGENTS.md was carrying CLI-internal detail (source layout, resolver tables, full harness matrix with modes column) that only agents working inside apps/cli need. The root is now an index; the detail lives where agents actually land when working on a component.

• Session-tracker disambiguation table earns its place. Two unrelated "session" surfaces is a documented footgun. The comparison table (role / trigger / data / consumer) in packages/session-tracker/AGENTS.md makes the distinction concrete without requiring the reader to trace imports.

• computer-win docs fill a genuine zero-doc gap. The Windows helper had no docs before this PR. The README now covers transport diagram, Task Scheduler lifecycle, single-file extraction gotcha (computer-win: UIAutomation verbs fail in the self-contained single-file exe (CI tests dotnet build, not the shipped publish) #519), and the Unicode-typing per-character fix (computer-win: type-text corrupts input (SendKeys fidelity) #554/computer-win: type_text residual — symbol run collapses to last char (follow-up to #554) #581) — exactly the non-obvious bits that cost investigation time.

• Symlink convention re-stated at every level. Each new AGENTS.md correctly echoes "edit AGENTS.md only," preventing future agents landing in a subdirectory from writing to a symlink target.

Things to verify manually

• apps/factory/AGENTS.md is referenced in the root component table (added by this PR) but was not touched by this PR. The file exists and the link is live — but it may not have been updated to reflect the post-refactor(repo): restructure into apps/ + packages/ + native/ (atomic) #724 restructure. Worth a follow-on check, not a blocker here.

---

Reviewed by Code Reviewer — read root AGENTS.md + all 6 new/modified doc files; cross-checked every factual claim against the live source tree before writing this review.