chore(repo): hygiene + docs restructure

AGENTS.md

@@ -17,3 +17,10 @@ A good comment answers questions like:
 Don't bother explaining *what* the code does — that's what reading the code is for. Explain *why it exists*, *why it's shaped this way*, and *what would make it wrong*.
 
 Make agentic development and decision-making **transparent in the diff**, not in a doc that drifts.
+
+## Directory conventions
+
+Two top-level folders look superficially similar but mean very different things. Do not mix them.
+
+- `vendor/` — read-only **source code references** kept locally so future-you can grep the original implementation of something we wrap or interoperate with. Never imported, never built, never shipped. Examples: `claude-code-src/`, vendored upstream checkouts for bug-bisection.
+- `third_party/` — pinned **runtime artifacts** that we ship inside packaged Agent Code (or that the release pipeline fetches at build time). Each tool gets its own directory with a `manifest.json` (version + per-arch sha256 + URL template), `README.md`, `LICENSE.md`, and a `.gitignore` that keeps `cache/` and `build/` out of git. Binaries are NEVER committed — the manifest plus `scripts/runtime-tools/<tool>` is the source of truth, and version bumps are one-file PRs against `manifest.json`. Examples: `third_party/mitmproxy/`, `third_party/tmux/`. See issues #119 and #120 for the full bundling plan.

MANIFESTO.md

@@ -32,10 +32,6 @@ The whole app is built for efficient development. All terminals are tmux-persist
 
 ## Structure
 
-One of the principles I understood early is that getting open-source contributors on board with something like this is hard. So Agent Code is dependent on 4 separate projects that it imports as packages, all more broadly scoped, which will hopefully attract more open-source attention.
-
-## Structure
-
 One of the principles I understood early is that getting open-source contributors on board with something like this is hard. So Agent Code is dependent on 4 separate projects that it imports as packages — all more broadly scoped, which will hopefully attract more open-source attention.
 
 **1. Headless Claude Code and Codex**

docs/README.md

@@ -0,0 +1,27 @@
+# Agent Code docs
+
+Layout and status conventions. Superseded/closed material moves to `archive/`
+and carries a `Status:`/`ARCHIVED` header — a doc without one is meant to be
+live.
+
+## Live
+
+- **`rendering/`** — the current rendering engine. `rendering-rewrite-plan-2026-07.md`
+  is canonical; `residue-plan-2026-07.md` and `session-recording-plan-2026-07.md`
+  are its live follow-ons; `legacy-deletion-manifest.md` is the cutover contract;
+  `rendering-knowledge-dump.md` is the evidence bible. `research-2026-07/` holds
+  the supporting research (rewrite research at the top level, the
+  session-recording research under `session-recording/`).
+- **`design/`** — living subsystem design (conditions, ghost system).
+- **`plans_and_ideas/`** — active/near-term plans and idea notes.
+- **`superpowers/`** — dated planning space: `plans/` (feature/fix plans) and
+  `specs/` (design specs). Accumulates by date; a plan carries a `Status:` header
+  once it ships or is superseded.
+- **`command-style.md`** — command-authoring conventions.
+- **`screenshots/`** — README assets.
+
+## Archived (`archive/`)
+
+- **`codex-rewrite-render/`** — the pre-rewrite rendering notebook (superseded).
+- **`issue-investigations/`** — investigations for issues now closed.
+- **`audit-plans/`** — the deep-audit roadmap and its completed execution logs.

docs/codex-rewrite-render/README.md → docs/archive/codex-rewrite-render/README.md

@@ -1,3 +1,10 @@
+> **ARCHIVED / SUPERSEDED (2026-07-07).** This was the first-principles working
+> notebook for the feed-rendering rewrite. It has been fully absorbed into the
+> canonical plan `docs/rendering/rendering-rewrite-plan-2026-07.md` and its
+> research digest `docs/rendering/research-2026-07/rewrite-notebook-extraction.md`.
+> Kept for history; reads present-tense but describes the OLD `deriveFeedRenderModel`
+> approach, which the ownership-ledger pipeline (`src/renderer/src/rendering/`) replaced.
+
 # Codex Render Rewrite Notes
 
 This directory is the working notebook for rebuilding feed rendering from first principles while keeping live streaming.

docs/issue-investigations/147-multi-instance-policy.md → docs/archive/issue-investigations/147-multi-instance-policy.md

@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue #147: Multiple Agent Code Instances
 
 ## Issue Summary

docs/issue-investigations/152-dispatch-terminals.md → docs/archive/issue-investigations/152-dispatch-terminals.md

@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue 152: Add terminal sessions to Dispatch Mode
 
 ## Issue summary

docs/issue-investigations/154-undo-close.md → docs/archive/issue-investigations/154-undo-close.md

@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issue 154: Extend Undo Close History and Retention
 
 ## Issue Summary

docs/issue-investigations/180-181-rendered-link-activation.md → docs/archive/issue-investigations/180-181-rendered-link-activation.md

@@ -1,3 +1,5 @@
+> **ARCHIVED (2026-07-07).** The investigated issue is closed; kept as history.
+
 # Issues #180 and #181: Rendered Link Activation
 
 ## Issue Summaries

docs/rendering/session-recording-plan-2026-07.md

@@ -5,7 +5,7 @@ stream**, replayable deterministically through the real pipeline in the
 test suite. GitHub issue: #467.
 
 This plan is the synthesis of four research sweeps (full reports in
-`research-2026-07/rec-research-{seam,precedent,tap,priorart}.md`): the
+`research-2026-07/session-recording/rec-research-{seam,precedent,tap,priorart}.md`): the
 replay seam, the existing corpus/journal machinery to reuse, the IPC tap
 point, and prior art + the OOM constraints a continuous recorder must
 respect.
@@ -222,7 +222,7 @@ one file per session per app-run. `0o600`.
 - `ch` is one of the 9 allowlisted channels.
 - `payload` is the channel's payload **verbatim** (post-coalesce for
   jsonl-entries). Full table of the 9 channel shapes:
-  `research-2026-07/rec-research-tap.md`.
+  `research-2026-07/session-recording/rec-research-tap.md`.
 - `t` (monotonic) drives replay ordering; `wall` is injected as the fold's
   clock during replay so wall-clock-dependent fold behavior (the orphan
   sweep, `unreadSince`/phase stamps) is deterministic. The ledger itself is