From ede8522716801a2985b8325114081b720f23dfe2 Mon Sep 17 00:00:00 2001
From: hgranthorner <37941012+hgranthorner@users.noreply.github.com>
Date: Wed, 5 Aug 2026 10:43:30 -0400
Subject: [PATCH] Document completion scope and gaps

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

diff --git a/AGENTS.md b/AGENTS.md
index 86b2fb4..0604454 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -120,8 +120,10 @@ Tier 3: parsed 714 files, 714 clean (100.0%), 0 with errors, 0 PsiErrorElements
   `#import`/`#load` path references with standard go-to-definition resolution.
   Headless tests cover source-ordered declarations, nested structure members,
   folding ranges, local `#load`, and Jai module directories.
-- **Phase 5** — completion, same-file and imported symbol navigation, rename,
-  and find-usages for declaration names.
+- **Phase 5** — basic completion for keywords, directives, and module/file
+  paths; same-file and imported symbol navigation; rename; and find-usages for
+  declaration names. Symbol-aware identifier/member completion remains future
+  work.
 - **Phase 5a** — persistent project settings for Jai module/import roots,
   shared root-aware resolution and completion, and indexed external Jai library
   sources. Headless tests cover state round-tripping, the Settings panel,
@@ -186,6 +188,14 @@ Tier 3: parsed 714 files, 714 clean (100.0%), 0 with errors, 0 PsiErrorElements
   `JaiReferenceHostMixin` from the BNF. Do not remove the mixin and expect a
   `PsiReferenceContributor` to be queried through the standard reference service.
 
+### Known code-insight gaps
+
+- Completion currently offers keywords, compiler directives, and module/file
+  paths, but not declarations, imported symbols, parameters, struct fields, or
+  module-qualified members.
+- Module-qualified members, procedure parameters, and struct fields also do
+  not yet have symbol resolution.
+
 ### In progress — pick up here
 
 1. **Phases 6+** — formatter, inspections, compiler integration, and other
diff --git a/CHANGELOG.md b/CHANGELOG.md
index eb3f352..6c285e5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -33,5 +33,7 @@
   not have inner PSI.
 - `#asm` bodies remain intentionally opaque; assembly instructions do not have
   inner PSI or structure entries.
+- Symbol-aware completion for declarations and imported symbols is not yet
+  implemented.
 - Module-qualified members, procedure parameters, and struct fields do not yet
-  have symbol resolution.
+  have symbol resolution or completion.
diff --git a/README.md b/README.md
index 3f27781..a92cf3b 100644
--- a/README.md
+++ b/README.md
@@ -18,15 +18,17 @@ never from online material (see `AGENTS.md`).
 - Brace matching, including the Jai-only `.{` struct-literal and `.[`
   array-literal openers
 - Basic completion for keywords, directives, and Jai module/file paths
+  (symbol-aware identifier completion is not implemented yet)
 - Project settings for ordered Jai module/import roots
 - Go-to-definition for procedures and types in the same file and through
   `#import`/`#load`, including configured external roots
 - Indexed external Jai roots so find-usages can cross project/library boundaries
 - 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.
+Remaining code-insight gaps include symbol-aware completion for declarations
+and imported symbols, plus module-qualified members, parameters, and struct
+fields. 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 b4ffad7..2e0de93 100644
--- a/docs/BUILD_PLAN.md
+++ b/docs/BUILD_PLAN.md
@@ -180,6 +180,14 @@ corpus-scale invariant that needs no human judgment.
 
 ---
 
+### Completion follow-up (not yet scheduled)
+
+Phase 5 completion is intentionally limited to keywords, compiler directives,
+and `#import`/`#load` module and file paths. It does not yet offer declarations,
+imported symbols, parameters, struct fields, or module-qualified members.
+Symbol-aware completion is a possible follow-up before or after Phase 6, but it
+is not currently a committed milestone.
+
 ## 5. Risks and how the plan handles them
 
 | Risk | Mitigation |