Add indexing roadmap

Author: AJenbo

docs/ARCHITECTURE.md

@@ -23,6 +23,18 @@ Both features follow the same principle for vendor code: the Composer classmap i
 
 The two walkers differ in scope because GTI only needs class declarations (which live in PSR-4 roots), while Find References needs any usage of a symbol, which could be in a standalone script, config file, or `index.php` at the project root.
 
+## Design Philosophy
+
+PHPantom is built in layers. Each layer is independently useful and independently testable.
+
+- **Layer 0: Stubs.** Embedded PHP standard library types. Available immediately, no project context needed.
+- **Layer 1: Single file.** Parse the open file, extract classes/functions/symbols. Completion, hover, and go-to-definition work within the file with no cross-file resolution at all.
+- **Layer 2: On-demand resolution.** When a symbol references a class in another file, resolve it through the classmap or PSR-4 and parse that file. Only the files actually needed are touched.
+- **Layer 3: Classmap.** A name-to-path index covering the whole project. Enables class name completion and O(1) cross-file lookup. Built from Composer's output or self-generated via a fast byte-level scan.
+- **Layer 4: Full index (opt-in).** Background-parse every file in the classmap. Enables workspace symbols, fast find-references, and rich completion item detail.
+
+Each layer builds on the one below it. A bug in classmap generation doesn't break single-file completion. A slow full index doesn't block on-demand resolution. New features can be developed and tested against the lower layers without waiting for a full project scan. This is also why PHPantom starts fast: Layer 0-2 are ready in milliseconds, Layer 3 takes seconds, and Layer 4 (when enabled) fills in over the following minute.
+
 ## Module Layout
 
 ```

docs/todo.md

@@ -27,6 +27,7 @@ with each step.
 | [Bug Fixes](todo/bugs.md) | Incorrect behaviour that should be fixed regardless of feature priority |
 | [Configuration](todo/config.md) | Per-project `.phpantom.toml` file, PHP version override, diagnostic tool toggles, prompt-and-remember settings |
 | [Refactoring](todo/refactor.md) | Technical debt and cleanup tasks. Gate check between sprints: clear all items before starting the next sprint |
+| [Indexing](todo/indexing.md) | Self-generated classmap, staleness detection, parallel file processing, full background indexing, disk cache |
 
 ---
 
@@ -37,7 +38,25 @@ diagnostics, unused-import dimming, and implement missing methods.
 
 ---
 
-## Sprint 2 — Refactoring & references
+## Sprint 2 — Self-generated classmap (0.5.0)
+
+PHPantom currently requires `composer dump-autoload -o` for cross-file
+resolution. When the classmap is missing or incomplete, the user gets
+no diagnostics, no cross-file completion, and no explanation why. The
+self-scan fallback builds a classmap ourselves so everything works out
+of the box. This also covers non-Composer projects.
+
+| # | Item | Effort | Domain | Doc Link |
+|---|---|---|---|---|
+| 80 | Self-generated classmap fallback | Medium-High | Indexing | [indexing.md — Phase 1](todo/indexing.md#phase-1-self-generated-classmap) |
+
+**After Sprint 2:** PHPantom works without any setup beyond opening a
+PHP project. The README can drop the `composer dump-autoload -o`
+requirement to a performance tip instead of a prerequisite.
+
+---
+
+## Sprint 3 — Refactoring
 
 Extract Function is the remaining refactoring pillar. Inline Variable,
 Extract Variable, and Inline Function/Method round out the core
@@ -54,7 +73,7 @@ tracking infrastructure they depend on, and both are now complete.
 
 ---
 
-## Sprint 3 — Close the LSP feature gap
+## Sprint 4 — Close the LSP feature gap
 
 These items close the most commonly expected LSP feature surface gaps.
 Each one removes a reason someone might look elsewhere.
@@ -67,14 +86,15 @@ Each one removes a reason someone might look elsewhere.
 | 22 | Selection Ranges (`textDocument/selectionRange`) | Low | LSP Features | [lsp-features.md §13](todo/lsp-features.md#13-selection-ranges-textdocumentselectionrange) |
 | 23 | Type Definition (`textDocument/typeDefinition`) | Low | LSP Features | [lsp-features.md §14](todo/lsp-features.md#14-type-definition-textdocumenttypedefinition) |
 | 24 | PHPDoc block generation on `/**` | Medium | LSP Features | [lsp-features.md §3](todo/lsp-features.md#3-phpdoc-block-generation-on-) |
+| 81 | Work-done progress for GTI and Find References | Low | LSP Features | [lsp-features.md §18](todo/lsp-features.md#18-work-done-progress-for-gti-and-find-references) |
 
-**After Sprint 3:** PHPantom covers every commonly expected LSP feature
+**After Sprint 4:** PHPantom covers every commonly expected LSP feature
 and surpasses the field on type intelligence, generics, Laravel, and
 performance. No feature gaps remain for typical day-to-day editing.
 
 ---
 
-## Sprint 4 — Type intelligence depth & polish
+## Sprint 5 — Type intelligence depth & polish
 
 Type intelligence depth is PHPantom's defining advantage. This sprint
 deepens that lead and rounds out the remaining feature surface.
@@ -96,14 +116,14 @@ deepens that lead and rounds out the remaining feature surface.
 | 39 | Simplify with null coalescing / null-safe operator (code action) | Medium | Code Actions | [actions.md §2](todo/actions.md#2-simplify-with-null-coalescing--null-safe-operator) |
 | 40 | Inlay hints (`textDocument/inlayHint`) | Medium | LSP Features | [lsp-features.md §9](todo/lsp-features.md#9-inlay-hints-textdocumentinlayhint) |
 
-**After Sprint 5:** PHPantom has a complete, polished LSP feature set.
+**After Sprint 6:** PHPantom has a complete, polished LSP feature set.
 Users moving to Zed/Neovim/Helix lose nothing on the intelligence side
 and gain 1000× faster startup. The remaining gaps are Blade and
 formatting (not our domain).
 
 ---
 
-## Sprint 5 — Deep type accuracy & Laravel excellence
+## Sprint 6 — Deep type accuracy & Laravel excellence
 
 These items push type resolution accuracy beyond what any tool offers.
 They're the long tail that makes PHPantom the definitive choice for
@@ -137,7 +157,7 @@ complementary inbound direction.
 
 ---
 
-## Sprint 6 — Blade support
+## Sprint 7 — Blade support
 
 Blade is a multi-phase project tracked in [todo/blade.md](todo/blade.md).
 Shipping Blade support makes PHPantom the first open-source PHP language