Document completion scope and gaps

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,
+- **Phase 5** — basic completion for keywords, directives, and module/file
-  and find-usages for declaration names.
+  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

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.

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
+Remaining code-insight gaps include symbol-aware completion for declarations
-struct fields. Formatting, inspections, and compiler integration are planned
+and imported symbols, plus module-qualified members, parameters, and struct
-later. See `docs/BUILD_PLAN.md` for the phase plan.
+fields. Formatting, inspections, and compiler integration are planned later.
+See `docs/BUILD_PLAN.md` for the phase plan.
 
 ## Install it locally
 

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 |