From 9122b5a5c031af31276cb5799900262ffd21d690 Mon Sep 17 00:00:00 2001
From: hgranthorner <37941012+hgranthorner@users.noreply.github.com>
Date: Tue, 4 Aug 2026 16:01:59 -0400
Subject: [PATCH] Document configurable module roots as next phase

---
 AGENTS.md          | 10 ++++++++++
 CHANGELOG.md       |  5 +++--
 README.md          |  6 ++++--
 docs/BUILD_PLAN.md | 10 ++++++----
 4 files changed, 23 insertions(+), 8 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 4e8eb55..52f4e9f 100644
--- a/AGENTS.md
+++ b/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
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1dbf95a..89b03b6 100644
--- a/CHANGELOG.md
+++ b/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;
-  custom compiler `-import_dir` arguments are not discovered yet.
+- Import resolution currently uses fixed project/module roots and the local Jai
+  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.
diff --git a/README.md b/README.md
index 58140f5..a8b49fd 100644
--- a/README.md
+++ b/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
-later. See `docs/BUILD_PLAN.md` for the phase plan.
+struct fields. The next planned increment is configurable project module/import
+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
 
diff --git a/docs/BUILD_PLAN.md b/docs/BUILD_PLAN.md
index 3802345..fbeae4f 100644
--- a/docs/BUILD_PLAN.md
+++ b/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
-is whether to continue with the optional formatter, inspections, and compiler
-integration work in Phases 6–8.
+Phases 0–5 are implemented and verified headlessly. The next planned increment
+is Phase 5a: configurable module/import roots and indexed external search scope.
+After that, decide whether to continue with the optional formatter, inspections,
+and compiler integration work in Phases 6–8.