docs: explain GitHub operating model and token economics

README.md

@@ -9,6 +9,48 @@ It keeps the operating model separate from any target product:
 - live operational state is local by default and is not committed;
 - GitHub is used for development of this framework through issues, pull requests, process changes, disputes and checks.
 
+## Why GitHub Is Part Of The OS
+
+The local v4 runtime proved that agent work needs explicit state, roles, tasks, audit trails and disputes. The problem is that a purely local control plane makes every fresh agent spend tokens rediscovering the same context: which tasks exist, what changed, what was reviewed, which dispute was resolved and what the current policy is.
+
+GitHub is used here as the durable shared control plane for developing this framework. It gives us native IDs, timelines, review surfaces, status checks, permissions and project views without asking an agent to rebuild those structures from chat history or local logs.
+
+This does not make GitHub the executor. Local runtime still handles fast agent work, tmux sessions, file IPC, target-packs and machine-local state. GitHub handles the shared coordination artifacts that benefit from durability, search, links and review.
+
+## What Moved From Local Runtime To GitHub
+
+For framework development, these responsibilities move from local-only files into GitHub-native surfaces:
+
+- Work intake moves from ad hoc local task files to GitHub Issues created from task forms.
+- Formal disputes move from only `auditor_logs/DISPUTE-NNN.md` to `type:dispute` issues with evidence and resolution.
+- Review and audit of framework changes move from local audit notes to Pull Requests, review comments, required checks and linked evidence.
+- Shared lifecycle visibility moves from only `STATE.md` and task metadata to labels and GitHub Projects.
+- Deterministic process checks move from agent-written audit text to GitHub Actions.
+- Process changes move from chat decisions to `type:process-change` issues and reviewed PRs.
+- Public framework memory moves into versioned docs in this repository instead of hidden chat context.
+
+These local pieces remain local by design:
+
+- `STATE.md`, because it describes one machine's live runtime.
+- `targets/*.local.md`, because target paths are machine-specific.
+- `tasks/TASK-*.md`, because local execution tasks can be temporary and target-specific.
+- `inbox/`, `outbox/`, tmux sessions and logs, because they are runtime transport.
+- credentials and environment files, because they must not become artifacts.
+
+## Token Economics
+
+The split saves tokens by moving deterministic coordination out of the model's context window:
+
+- GitHub Issues provide compact, structured task context instead of long chat replay.
+- Issue and PR timelines preserve handoff history without requiring agents to summarize every turn.
+- Labels and Projects answer "what state is this in?" without scanning all local files.
+- Pull request diffs focus review on changed lines instead of full-repository rereads.
+- GitHub Actions run repeatable checks with zero LLM tokens.
+- Templates reduce prompt size by making required fields predictable.
+- Local target-packs keep target context as file references, so dispatch envelopes can point to artifacts instead of embedding content.
+
+The expected economy is simple: humans and agents spend tokens on judgment, design, code and audit; GitHub spends ordinary compute on indexing, status, routing, checks and durable timelines.
+
 ## Quick Start
 
 1. Read `AGENTS.md`.