# Documentation index

Read the row matching the task; follow section links before reading whole documents.

| Task | Read |
| --- | --- |
| Requirements and scope | [Spec: solution](spec.md#solution), [user stories](spec.md#user-stories), [out of scope](spec.md#out-of-scope) |
| Modifier taps, holds and timing controls | [Input timing spec](spec.md#input-timing-and-modifier-taps), [delivery](implementation-plan.md#input-timing-delivery), [scoped acceptance](validation.md#input-timing-and-modifier-tap-acceptance) |
| Implementation contracts | [Spec: implementation decisions](spec.md#implementation-decisions) |
| Delivery, design review and feasibility | [Design revision](implementation-plan.md#design-revision), [plan: detailed milestones](implementation-plan.md#detailed-milestones), [feasibility gates](implementation-plan.md#feasibility-gates) |
| Test design and release validation | [Spec: testing decisions](spec.md#testing-decisions), [plan: coverage matrix](implementation-plan.md#coverage-matrix) |
| Pi acceptance, phased testing and agent recovery | [Current phases](implementation-plan.md#detailed-milestones), [baseline audit](validation.md#baseline-identity-and-schema-evidence), [guidance inventory](validation.md#model-visible-guidance-inventory), [scenario catalog](validation.md#alignment-scenario-catalog) |
| Release checks, capability coverage and pending acceptance | [0.1.1 preparation and release notes](validation.md#011-release-preparation), [verified 0.1.0 npm release](validation.md#npm-publication-receipt), [0.1.0 release preparation](validation.md#first-release-preparation), [current release audit](validation.md#final-release-audit), [capability coverage](validation.md#capability-coverage), [validation history](validation.md) |
| Pi interfaces and sources | [Pi extension research](pi-extension-research.md) (research context; current spec takes precedence over earlier proposals) |
| Domain terminology | [Glossary](../GLOSSARY.md) |
| Current Pi-first acceptance scope | [ADR 0004](adr/0004-pi-first-acceptance.md) |
| Windows default apps, existing windows and foreground | [Accepted policy](spec.md#default-apps-workspaces-and-foreground), [ADR 0005](adr/0005-default-apps-and-workspace-reuse.md), [delivery cases](implementation-plan.md#default-app-and-workspace-delivery), [current support](windows.md#default-apps-and-workspaces) |
| Historical reference-parity decision | [Superseded ADR 0001](adr/0001-preserve-reference-behavior.md) |
| Stronger native window identity design | [Lifetime plan](implementation-plan.md#window-lifetime-design), [ADR 0002](adr/0002-window-lifetime-references.md) |
| Publish or read issues | [Issue tracker](agents/issue-tracker.md), [triage labels](agents/triage-labels.md) |
| What works, remaining outcomes, next work and cleanup decisions | [Progress summary](tickets.md#current-progress), [delivery map](tickets.md#delivery-outcomes-and-ownership), [execution queue](tickets.md#execution-queue), [cleanup dispositions](tickets.md#cleanup-dispositions), [original obligations](tickets.md#original-issue-disposition) |
| Worker setup, protocol and test evidence | [Runtime and validation](runtime.md) |
| Exclusive control, human handback and emergency stopping | [Control contract](spec.md#exclusive-control), [delivery/test slices](implementation-plan.md#exclusive-control-delivery), [ADR 0003](adr/0003-exclusive-desktop-control.md), [current stopping implementation](stopping.md), [control acceptance](validation.md#control-interruption-acceptance) |
| Control indicators, preview and recording acceptance | [Indicators](indicators.md), [Snipping Tool receipt](validation.md#snipping-tool-recording-acceptance) |
| Desktop ownership and operation lifecycle | [Ownership](ownership.md) |
| Native window discovery and validation | [Windows discovery](windows.md), [accessibility observations](windows.md#accessibility-observations), [targeting acceptance reconciliation](validation.md#pi-targeting-and-accessibility-reconciliation), [OCR failures](validation.md#pi-ocr-failure-acceptance), [locked sessions](windows.md#locked-session-refusals) |
| Scoped browser/mixed agent acceptance | [Held-navigation cancellation](validation.md#scoped-held-navigation-cancellation), [Partial-observation recovery](validation.md#scoped-partial-observation-recovery), [mixed outcome evidence](validation.md#scoped-mixed-browsernative-outcome), [runner prerequisites](validation.md#reproduce-automated-checks), [ordinary workspace actor outcomes](validation.md#ordinary-pi-workspace-actor-preparation) |
| Scoped native document and visual agent acceptance | [Document workflow](validation.md#native-document-workflow), [handback continuation](validation.md#native-cancellation-and-handback-continuation), [opt-in visual runner](windows.md#scoped-visual-agent-check), [A04 evidence](validation.md#visual-ocr-association-preflight) |
| Lifetime-bound native targeting and stale-reference behavior | [Window references](windows.md#window-lifetime-references), [accepted design](implementation-plan.md#window-lifetime-design) |
| Native interop alternatives and tradeoffs | [Native interop research](native-interop-research.md) |
| Guarded desktop pointer and dedicated input validation | [Pointer actions](pointer.md), [single-click holds/deadlines](pointer.md#single-click-holds-and-deadlines), [popup/menu/cross-process drop and restoration acceptance](validation.md#scoped-pointer-and-restoration-acceptance) |
| Text, chords, keypress timing, clipboard preservation and validation | [Text entry](text.md), [keypress timing](text.md#keypress-holds-and-deadlines), [text pacing](text.md#sendinput-pacing-and-deadlines), [chord/editor-focus acceptance](validation.md#pi-chords-and-editor-focus-acceptance), [clipboard acceptance](validation.md#pi-clipboard-contention-and-privacy-acceptance) |
| Personal settings, commands and tool loading | [Settings](settings.md) |
| Browser reads/actions, dedicated profiles, idle cleanup and fixtures | [Browser](browser.md) |
| Domain-document consumer rules | [Domain docs](agents/domain.md) |

## Repository layout

```text
README.md              project entry point
AGENTS.md              short contributor rules and routing
GLOSSARY.md            domain terms
src/                   flat TypeScript modules
tests/                 tests and native smoke fixtures
assets/                packaged resources and runtime notices
docs/
  README.md            this index
  spec.md              authoritative requirements
  implementation-plan.md  delivery, feasibility and coverage
  pi-extension-research.md  cited Pi interface research
  adr/                 durable decision rationale
  agents/              issue tracker, triage and domain configuration
```

Use the existing source, test and asset directories. Keep responsibility-named modules such as extension, launcher, worker, desktop, browser, settings and stop; split by demonstrated complexity rather than pre-creating a directory per module.
