Align docs and skills on stdlib paths, LSP keywords, and ion-build.

Updates README, tests/README, and agent skills for CONTRIBUTING, IDE limitations, ION_BUILD, and src/build/ checklists.

Author: Cod-e-Codes

.cursor/skills/adding-ion-features/SKILL.md

@@ -128,7 +128,7 @@ cargo test lexer::
 - Breaking single-file merge path while fixing multi-file (test both)
 - Weakening no-escape or Send rules to make a test pass
 - Large parser refactors bundled with feature work
-- Forgetting to register new keywords in lexer **and** LSP keyword lists (`src/lsp/server.rs`, `ion-vscode/syntaxes/ion.tmLanguage.json`) if applicable; rebuild `ion-lsp` after compiler changes
+- Forgetting to register new keywords in lexer **and** LSP keyword lists (`src/lsp/util.rs` `KEYWORDS`, `ion-vscode/syntaxes/ion.tmLanguage.json`) if applicable; rebuild `ion-lsp` after compiler changes
 
 ## Examples
 

.cursor/skills/adding-ion-features/references/stage-checklist.md

@@ -50,8 +50,15 @@
 - [ ] Includes and forward decls for multi-file headers
 - [ ] Drop/defer/spawn/channel paths emit correct runtime calls
 
+## Project build (`src/build/`)
+
+- [ ] `manifest.rs` updated for new or changed `ion.toml` fields (ION_SPEC §10.1)
+- [ ] `driver.rs` / `c_toolchain.rs` if compile or link steps change
+- [ ] `paths.rs` if stdlib or import discovery changes (shared with LSP via `discover_import_config`)
+- [ ] Smoke tests: `tests/build_hello/`, `tests/build_bad_main/`
+
 ## LSP (`src/lsp/`)
 
 - [ ] Parser errors surface in diagnostics
-- [ ] New keywords in completion list if maintained manually
+- [ ] New keywords in `src/lsp/util.rs` `KEYWORDS` and TextMate grammar
 - [ ] Rebuild: `cargo build --release --bin ion-lsp`

.cursor/skills/finding-ion-bugs/SKILL.md

@@ -70,6 +70,7 @@ cargo clippy -- -D warnings
 | Wrong or missing C | `src/cgen/`, `src/ir/mod.rs` | Compare `.c` output; `cgen` rows in `test_expectations.tsv` |
 | Link / runtime crash | `runtime/ion_runtime.c`, generated calls | `gcc` link line from README |
 | Import / multi-file | `src/compiler/mod.rs` | `--mode multi` |
+| `ion-build` / manifest failure | `src/build/` (`manifest.rs`, `driver.rs`, `paths.rs`) | `tests/build_hello/`, `tests/build_bad_main/` |
 | Test harness false pass/fail | `tests/test_runner.sh`, TSV row | Empty `must_match` on `cgen` rows fails harness self-check |
 | LSP wrong, CLI correct | `src/lsp/` | LSP parses buffer + disk imports; formats errors differently than CLI |
 

.cursor/skills/ion-lang/SKILL.md

@@ -101,7 +101,7 @@ Read these when the task matches:
 - References cannot escape functions, structs, enums, channels, or `spawn` - reject at type-check time.
 - `extern "C"` calls require `unsafe` blocks.
 - Multi-file mode: `--mode multi --output <name> <main.ion>` generates per-module `.c`/`.h`.
-- Stdlib: `import "stdlib/io.ion" as io;` (resolved via `ion.toml` / `ION_STDLIB` / project `stdlib/`). Bare `import "io.ion"` also resolves when `io.ion` is on a search path.
+- Stdlib: `import "stdlib/io.ion" as io;` resolves via manifest `stdlib_paths`, `ION_STDLIB`, `{project_root}/stdlib`, then install-relative `stdlib/` next to the compiler. Bare `import "io.ion"` also resolves when `io.ion` is on a search path.
 - `ion build` (`ion-build` binary): project manifest at `ion.toml`; see ION_SPEC §10.1.
 - Integration tests: add `tests/test_*.ion` plus one row in `tests/test_expectations.tsv` (see `ion-integration-tests` skill). Run `cd tests && ./test_runner.sh` to verify.
 - Fn literals are capture-free only; references to outer bindings are rejected with `ClosureCapture`.

.cursor/skills/ion-lsp-vscode/SKILL.md

@@ -73,7 +73,7 @@ Adjust path for OS (no `.exe` on Linux/macOS).
 8. **References**, **document symbols**, **signature help**, **semantic tokens**
 9. **`did_change_watched_files`** - re-check open files whose import dependencies changed
 
-Known limitations (ION_SPEC §10.2): built-in methods have signature hover but no go-to-definition target; type names in annotations have no goto (no spans on `Type` nodes).
+Known limitations: built-in methods have signature hover but no go-to-definition target (ION_SPEC §10.2); type names in annotations have no goto (§10.3; no spans on `Type` nodes).
 
 ### CLI vs LSP error text
 

.cursor/skills/writing-ion-code/SKILL.md

@@ -56,7 +56,7 @@ fn main() -> int {
 }
 ```
 
-Import paths like `import "stdlib/io.ion" as io;` resolve via stdlib search paths (`ion.toml`, `ION_STDLIB`, project `stdlib/`). Same-directory and `../` relative paths still work. Use `pub fn` in library modules; call with `alias::name(...)`.
+Import paths like `import "stdlib/io.ion" as io;` resolve via stdlib search paths (`ion.toml` `stdlib_paths`, `ION_STDLIB`, project `stdlib/`, then install-relative `stdlib/` next to the compiler). Same-directory and `../` relative paths still work. Use `pub fn` in library modules; call with `alias::name(...)`.
 
 ## Core syntax (verified)
 

README.md

@@ -29,6 +29,7 @@ Known limitations: [ION_SPEC.md section 10.3](ION_SPEC.md#103-known-limitations)
 | Resource | Contents |
 |----------|----------|
 | [ION_SPEC.md](ION_SPEC.md) | Language semantics, grammar, stdlib contracts |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Build, test, lint, and PR expectations |
 | [tests/README.md](tests/README.md) | Integration test catalog |
 | [examples/](examples/) | Runnable example programs |
 
@@ -65,7 +66,7 @@ Ion has a VS Code / Cursor extension that provides:
 - Completion: prefix-filtered keywords, builtins, and file symbols
 - Go to definition: variables, function calls, and user-defined methods; imported `mod::func` opens the module file
 
-Limitations: built-in methods (`Vec::push`, etc.) do not go to definition. Full list in [ION_SPEC.md section 10.3](ION_SPEC.md#103-known-limitations).
+Limitations: built-in methods (`Vec::push`, etc.) and type names in annotations do not go to definition. Full list in [ION_SPEC.md section 10.3](ION_SPEC.md#103-known-limitations).
 
 **Installation:**
 

tests/README.md

@@ -299,11 +299,12 @@ Special cases (not in the manifest):
 ## Environment Variables
 
 - `COMPILER`: Path to the ion-compiler binary (default: `../target/release/ion-compiler`)
+- `ION_BUILD`: Path to the ion-build binary (default: `../target/release/ion-build`)
 - `CC`: C compiler to use (default: `gcc`)
 - `RUNTIME_OBJ`: Path to the precompiled runtime object file (default: `.ion_test_runtime.o` in `tests/`). Rebuilt when `runtime/ion_runtime.c` is newer than the object.
 
 Example:
 ```bash
-COMPILER=../target/debug/ion-compiler CC=clang ./test_runner.sh
+COMPILER=../target/debug/ion-compiler ION_BUILD=../target/debug/ion-build CC=clang ./test_runner.sh
 ```