Document configurable module roots as next phase

AGENTS.md

@@ -190,6 +190,16 @@ Tier 3: parsed 714 files, 714 clean (100.0%), 0 with errors, 0 PsiErrorElements
    optional work remain. `#asm` bodies are intentionally consumed opaquely, so
    nothing inside them has PSI yet.
 
+### Next planned increment
+
+- Add persistent project settings for configurable Jai module/import roots.
+- Use those roots consistently for `#import`/`#load` resolution, completion,
+  symbol navigation, and find-usages.
+- Include configured external `.jai` directories in indexing/search scope so
+  standard-library and custom-module usages are discoverable across files.
+- Add headless tests for settings persistence, custom-root resolution,
+  completion, go-to-definition, and cross-root find-usages.
+
 ### Open questions for the user (unanswered)
 
 Scope (Phases 0–4 vs 0–7), compiler integration, target IDEs, JDK policy. See

CHANGELOG.md

@@ -31,7 +31,8 @@
   not have inner PSI.
 - `#asm` bodies remain intentionally opaque; assembly instructions do not have
   inner PSI or structure entries.
-- Import resolution uses the project/module roots and the local Jai installation;
+- Import resolution currently uses fixed project/module roots and the local Jai
-  custom compiler `-import_dir` arguments are not discovered yet.
+  installation; configurable module roots and custom compiler `-import_dir`
+  arguments are planned.
 - Module-qualified members, procedure parameters, and struct fields do not yet
   have symbol resolution.

README.md

@@ -23,8 +23,10 @@ never from online material (see `AGENTS.md`).
 - Rename and find-usages for declaration names and their resolved references
 
 Remaining code-insight gaps include module-qualified members, parameters, and
-struct fields. Formatting, inspections, and compiler integration are planned
+struct fields. The next planned increment is configurable project module/import
-later. See `docs/BUILD_PLAN.md` for the phase plan.
+roots, including indexed search scope for external standard-library and custom
+module directories. Formatting, inspections, and compiler integration are
+planned later. See `docs/BUILD_PLAN.md` for the phase plan.
 
 ## Install it locally
 

docs/BUILD_PLAN.md

@@ -169,7 +169,8 @@ Each phase has a machine-checkable gate. Do not advance without a green gate.
 | **2** | `SyntaxHighlighter`, color settings page, commenter, brace matcher | Tier 1 golden dumps; highlighter maps every token type |
 | **3** | `.bnf` grammar, generated parser + PSI, `ParserDefinition` | Tier 2 golden trees; Tier 3 corpus parse ≥ target — **done, 100.0% (714/714)** |
 | **4** | Structure view, folding, `#import`/`#load` reference resolution + go-to-definition | Tier 4 fixture tests — **done** |
-| **5** | Completion (keywords, directives, module names), rename, find-usages | Tier 4 fixture tests — **done** (70-test suite) |
+| **5** | Completion (keywords, directives, module names), rename, find-usages | Tier 4 fixture tests — **done** (71-test suite) |
+| **5a** | Configurable Jai module/import roots and indexed external search scope | Tier 4 settings, resolution, completion, navigation, and find-usages tests |
 | **6** | Formatter, code style settings | Formatter round-trip: formatting the corpus is idempotent |
 | **7** | Inspections (e.g. `#must` misuse), quick fixes, live templates | Tier 4 + `verifyPlugin` |
 | **8** | Optional: run-configuration to invoke the `jai` compiler, parse its error output | Integration test against `~/.local/jai/bin` |
@@ -207,6 +208,7 @@ corpus-scale invariant that needs no human judgment.
    setup, works today), or install a system JDK via Homebrew? I'd default to the
    wrapper.
 
-Phases 0–5 are now implemented and verified headlessly. The remaining decision
+Phases 0–5 are implemented and verified headlessly. The next planned increment
-is whether to continue with the optional formatter, inspections, and compiler
+is Phase 5a: configurable module/import roots and indexed external search scope.
-integration work in Phases 6–8.
+After that, decide whether to continue with the optional formatter, inspections,
+and compiler integration work in Phases 6–8.