Document ion-build as the primary workflow in README, skills, and spec.

Replace manual gcc-first usage with ion.toml manifests and per-example build commands; document ion-build --manifest in ION_SPEC section 10.1.

Author: Cod-e-Codes

.cursor/skills/ion-integration-tests/SKILL.md

@@ -15,7 +15,7 @@ paths:
 
 End-to-end tests: Ion → C → gcc → run executable → assert exit code (or assert compile failure).
 
-The harness runs tests under `tests/` only. Files in `examples/` are documented demos - compile and run them manually (see [README.md](../../../README.md)); they are not in the integration manifest.
+The harness runs tests under `tests/` only. Files in `examples/` are documented demos; build and run them with `ion-build` and per-example manifests (see [README.md](../../../README.md#example-programs)). Regenerate committed `examples/*.c` snapshots with `ion-compiler` after codegen changes.
 
 **Example output policy:** Top-level single-file examples commit one merged `.c` next to the `.ion`. `text_summary/` commits one `.c` plus `sample.txt`. Multi-file `data_lib/` keeps `.ion` only (see `examples/data_lib/README.md`).
 
@@ -29,7 +29,7 @@ for f in examples/*.ion; do ./target/release/ion-compiler "$f"; done
 
 Multi-file `examples/data_lib/` has no committed `.c`; see `examples/data_lib/README.md`.
 
-Link and run like integration tests (`gcc` + `runtime/ion_runtime.c` + `-lpthread`; on Windows MinGW add `-lws2_32`).
+To build examples, use `ion-build` (see README). Manual `gcc` + `runtime/ion_runtime.c` is for the test harness and advanced debugging only.
 
 ## Run tests
 
@@ -56,7 +56,7 @@ COMPILER=../target/debug/ion-compiler ION_BUILD=../target/debug/ion-build CC=cla
 RUNTIME_OBJ=/tmp/ion_runtime.o ./test_runner.sh
 ```
 
-**Harness link step:** On startup, `test_runner.sh` precompiles `runtime/ion_runtime.c` once to `RUNTIME_OBJ` (default `.ion_test_runtime.o`) and links that object for each `run` test and `test_multifile`. Same `gcc` flags as before; manual example compiles below still use `ion_runtime.c` directly.
+**Harness link step:** On startup, `test_runner.sh` precompiles `runtime/ion_runtime.c` once to `RUNTIME_OBJ` (default `.ion_test_runtime.o`) and links that object for each `run` test and `test_multifile`. This path uses `ion-compiler` and `gcc` directly, not `ion-build`. Example programs under `examples/` use `ion-build` per README.
 
 **Windows:** Use Git Bash, not WSL. Rebuild release after compiler changes. Stop `ion-lsp` if build fails with "Access is denied".
 

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

@@ -56,7 +56,7 @@ fn main() -> int {
 }
 ```
 
-Import paths are string literals relative to the compiling file. 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`, `ION_STDLIB`, project `stdlib/`). Same-directory and `../` relative paths still work. Use `pub fn` in library modules; call with `alias::name(...)`.
 
 ## Core syntax (verified)
 
@@ -123,7 +123,7 @@ Fn literals lower to static C functions and must not reference outer bindings (o
 
 ## Documentation comments
 
-Ion uses plain `//` line comments only — no `///` or `//!`. Contiguous `//` lines **immediately above** a declaration (no blank line before the declaration) are attached as documentation for IDE hover; the same rule applies when `pub` precedes the item. A blank line breaks association. File-level overview comments go at the top of the file before imports. Section-divider comment blocks in examples should be separated from declarations by a blank line. See ION_SPEC §12.6.
+Ion uses plain `//` line comments only. No `///` or `//!`. Contiguous `//` lines **immediately above** a declaration (no blank line before the declaration) are attached as documentation for IDE hover; the same rule applies when `pub` precedes the item. A blank line breaks association. File-level overview comments go at the top of the file before imports. Section-divider comment blocks in examples should be separated from declarations by a blank line. See ION_SPEC section 12.6.
 
 **Unsafe and FFI**
 
@@ -144,16 +144,19 @@ Built-ins: `Vec<T>`, `String`, `Box<T>`, `Option<T>`, `Result<T, E>` (define enu
 
 ## Build and verify
 
-With `ion.toml` at the project root (or example directory):
+With `ion.toml` in the project or example directory (or `examples/*.toml` with `--manifest`):
 
 ```powershell
 cargo build --release --bin ion-build
-.\target\release\ion-build.exe build
-.\target\<output>.exe
+cd examples   # or example subdirectory with ion.toml
+..\target\release\ion-build.exe build --manifest spawn_channel.toml
+.\target\spawn_channel.exe
 echo $LASTEXITCODE
 ```
 
-For a single file without a manifest, use `ion-compiler` plus manual `gcc` (see `ion-lang` skill). On Windows add `-lws2_32` for channel/spawn programs. Stop `ion-lsp` if rebuild fails with "Access is denied".
+Multi-file: `cd examples\data_lib` then `..\..\target\release\ion-build.exe build`. See [examples/data_lib/README.md](../../../examples/data_lib/README.md).
+
+For codegen inspection or `tests/` integration harness work, use `ion-compiler` plus manual `gcc` (see `ion-lang` skill). On Windows add `-lws2_32` for channel/spawn when linking manually. Stop `ion-lsp` if rebuild fails with "Access is denied".
 
 For programs under `tests/`, follow the `ion-integration-tests` skill (`test_expectations.tsv` row required).
 

.cursor/skills/writing-ion-code/references/verified-patterns.md

@@ -117,7 +117,14 @@ fn main() -> int {
 
 Non-`pub` items are file-private. Qualified names use `alias::item`.
 
-Multi-file compile (manual):
+Multi-file build (`ion-build` with `mode = "multi"` in `ion.toml`):
+
+```powershell
+cd examples\data_lib
+..\..\target\release\ion-build.exe build
+```
+
+Manual codegen only (emits `.c`/`.h` in cwd):
 
 ```bash
 ./target/release/ion-compiler --mode multi --output app path/to/main.ion

ION_SPEC.md

@@ -1194,6 +1194,8 @@ cargo build --release --bin ion-build
 .\target\release\ion-build.exe build
 ```
 
+Manifest discovery walks upward from the current directory for a file named `ion.toml`. To use another filename (for example `examples/http_server.toml`), pass `--manifest <path>`; the manifest's parent directory is the project root and `main` paths are relative to that directory.
+
 `ion-compiler` remains available for codegen inspection, LSP internals, and integration tests that grep `.c` output. It does not require `ion.toml`.
 
 **`ion.toml` fields (tooling, not language semantics):**

README.md

@@ -114,7 +114,7 @@ Source: [examples/hello_world_safe.ion](examples/hello_world_safe.ion). For a mi
 
 ### Advanced: Manual Transpile and Link
 
-For codegen inspection or debugging, use `ion-compiler` directly:
+For codegen inspection, integration test workflows, or debugging generated C, use `ion-compiler` directly (see [ION_SPEC.md section 10.1](ION_SPEC.md#101-project-build-ion-build)):
 
 ```bash
 ./target/release/ion-compiler examples/hello_world.ion
@@ -123,107 +123,77 @@ gcc examples/hello_world.c runtime/ion_runtime.c -o hello_world \
 ./hello_world
 ```
 
-### Single-File Mode (Default)
+The integration harness (`tests/test_runner.sh`) calls `ion-compiler` and `gcc` this way. Application development should use `ion-build` instead.
 
-**Step 1: Compile Ion to C**
+### Project manifests (`ion.toml`)
 
-```bash
-./target/release/ion-compiler input.ion
-```
-
-This generates `input.c` in the same directory as the source file.
-
-**Step 2: Compile C to Executable**
-
-The generated C code requires the Ion runtime library:
-
-```bash
-gcc input.c runtime/ion_runtime.c -o input -I. -I.. -Iruntime -I../runtime -lpthread
-```
+`ion-build` discovers `ion.toml` by walking up from the current directory. Required fields: `name`, `main`, `output`. Common optional fields: `mode` (`single` or `multi`), `out_dir` (default `target`), `cflags`, `ldflags`, `stdlib_paths`.
 
-**Required flags:**
-- `input.c` - generated C file
-- `runtime/ion_runtime.c` - Ion runtime (when running from project root)
-- `-I. -I.. -Iruntime -I../runtime` - include paths for runtime headers
-- `-lpthread` - pthread library (required for channels and spawn)
-- `-o input` - output executable name
+Root [ion.toml](ion.toml) builds [examples/hello_world_safe.ion](examples/hello_world_safe.ion). Per-example manifests live under [examples/](examples/) (for example `spawn_channel.toml`, `http_server.toml`, `examples/data_lib/ion.toml`). Use `--manifest path` when the file is not named `ion.toml`:
 
-**Step 3: Run**
-
-```bash
-./input
+```powershell
+cd examples
+..\target\release\ion-build.exe build --manifest http_server.toml
+.\target\http_server.exe
 ```
 
-### FFI with POSIX Functions
-
-If your Ion program uses FFI names that conflict with Ion keywords (`recv`, `send`), add `-D` flags when linking:
+FFI programs that rename C symbols (for example `recv_sys`) set compile-time `-D` flags in `cflags`, not `ldflags`. See [examples/http_server.toml](examples/http_server.toml).
 
-```bash
-gcc http_server.c runtime/ion_runtime.c -o http_server \
-    -I. -I.. -Iruntime -I../runtime -lpthread \
-    -Drecv_sys=recv -Dsend_sys=send -Dclose=closesocket -lws2_32
-```
+### Multi-file projects
 
-On Linux or macOS, omit `-lws2_32` and `-Dclose=closesocket`. `ion_net_init()` is a no-op outside Windows.
+Multi-file mode (`mode = "multi"` in `ion.toml`) transpiles each module to `.c`/`.h`, compiles objects, and links one executable. Artifacts default to `out_dir` (usually `target/`), not the source tree.
 
-### Multi-File Mode
-
-```bash
-./target/release/ion-compiler --mode multi --output myprogram main.ion
+```powershell
+cd examples\data_lib
+..\..\target\release\ion-build.exe build
+.\target\data_lib.exe
 ```
 
-This parses imported modules, generates `.c` and `.h` per module, compiles object files, and links with the runtime. The `--output` flag sets the executable name (defaults to the main module name). Multi-file mode handles compilation and linking; you do not need to run `gcc` manually.
+For manual multi-file codegen in the source directory (no `ion-build`), use `ion-compiler --mode multi --output NAME main.ion`. See [examples/data_lib/README.md](examples/data_lib/README.md).
 
 ## Example Programs
 
-Top-level `examples/*.ion` files each have a checked-in merged `examples/*.c` codegen snapshot. Regenerate after compiler codegen changes:
+Top-level `examples/*.ion` files each have a checked-in merged `examples/*.c` codegen snapshot. Regenerate after compiler codegen changes (from repo root, relative paths keep portable banners):
 
 ```bash
 for f in examples/*.ion; do ./target/release/ion-compiler "$f"; done
 ./target/release/ion-compiler examples/text_summary/text_summary.ion
 ```
 
-Top-level single-file examples (including `channel_worker.ion`) commit a merged `.c` snapshot next to the `.ion`. The `text_summary/` subdirectory also commits one `.c` (it needs `sample.txt`). Multi-file `examples/data_lib/` keeps only `.ion` sources; see [examples/data_lib/README.md](examples/data_lib/README.md) for build output (`.c`/`.h` generated in place, not committed).
-
-Compile and run any single-file example:
-
-```bash
-./target/release/ion-compiler examples/spawn_channel.ion
-gcc examples/spawn_channel.c runtime/ion_runtime.c -o spawn_channel \
-    -I. -Iruntime -lpthread -lws2_32   # omit -lws2_32 on Linux/macOS
-./spawn_channel
-```
+Committed `.c` snapshots are for review and `ion-compiler` regression; building and running examples uses `ion-build` and the manifests below.
 
-For `http_server.ion`, add `-Drecv_sys=recv -Dsend_sys=send` when linking.
+**Build and run** (from `examples/` unless noted):
 
-| File | What it demonstrates |
-|------|---------------------|
-| [examples/hello_world.ion](examples/hello_world.ion) | Minimal FFI `write()` to stdout |
-| [examples/hello_world_safe.ion](examples/hello_world_safe.ion) | stdlib `io` module |
-| [examples/spawn_channel.ion](examples/spawn_channel.ion) | `spawn` with cross-thread channels |
-| [examples/http_server.ion](examples/http_server.ion) | Sockets, FFI, concurrent clients via `spawn` |
-| [examples/showcase.ion](examples/showcase.ion) | Mixed language features: tuples, `+=`, `push_byte`, spawn/channels, capture-free fn literals |
-| [examples/access_log.ion](examples/access_log.ion) | Log parsing, `loop`/`break`, match guards, spawn, channels, fmt/io |
-| [examples/minimal.ion](examples/minimal.ion) | Smallest valid program |
-| [examples/channel_worker.ion](examples/channel_worker.ion) | Channel worker: `spawn` sums jobs from a channel |
-| [examples/text_summary/text_summary.ion](examples/text_summary/text_summary.ion) | `fs` file read, string iteration, line/word/byte counts |
-| [examples/data_lib/main.ion](examples/data_lib/main.ion) | Multi-module library (`catalog.ion`); see [data_lib/README.md](examples/data_lib/README.md) |
+```powershell
+# Single-file example with a manifest in examples/
+..\target\release\ion-build.exe build --manifest spawn_channel.toml
+.\target\spawn_channel.exe
 
-Build `data_lib` (multi-file):
+# http_server (FFI cflags in http_server.toml)
+..\target\release\ion-build.exe build --manifest http_server.toml
 
-```powershell
-cd examples\data_lib
+# text_summary (has its own ion.toml; needs sample.txt in that directory)
+cd text_summary
 ..\..\target\release\ion-build.exe build
-.\target\data_lib.exe
+.\target\text_summary.exe
 ```
 
-Or with `ion-compiler` directly (emits `.c`/`.h` in the current directory):
+On Linux or macOS, use `./target/release/ion-build` and drop `.exe`. Windows channel/spawn builds add `-lws2_32` automatically.
 
-```bash
-cd examples/data_lib
-../../target/release/ion-compiler --mode multi --output data_lib main.ion
-./data_lib
-```
+| File | Manifest | What it demonstrates |
+|------|----------|---------------------|
+| [examples/hello_world.ion](examples/hello_world.ion) | (use `ion-compiler` only; no stdlib) | Minimal FFI `write()` to stdout |
+| [examples/hello_world_safe.ion](examples/hello_world_safe.ion) | [hello_world_safe.toml](examples/hello_world_safe.toml) or root [ion.toml](ion.toml) | stdlib `io` module |
+| [examples/spawn_channel.ion](examples/spawn_channel.ion) | [spawn_channel.toml](examples/spawn_channel.toml) | `spawn` with cross-thread channels |
+| [examples/http_server.ion](examples/http_server.ion) | [http_server.toml](examples/http_server.toml) | Sockets, FFI, concurrent clients via `spawn` |
+| [examples/showcase.ion](examples/showcase.ion) | [showcase.toml](examples/showcase.toml) | Mixed language features |
+| [examples/access_log.ion](examples/access_log.ion) | [access_log.toml](examples/access_log.toml) | Log parsing, spawn, channels, fmt/io |
+| [examples/minimal.ion](examples/minimal.ion) | (transpile-only with `ion-compiler`) | Smallest valid program |
+| [examples/channel_worker.ion](examples/channel_worker.ion) | [channel_worker.toml](examples/channel_worker.toml) | Channel worker |
+| [examples/text_summary/text_summary.ion](examples/text_summary/text_summary.ion) | [text_summary/ion.toml](examples/text_summary/ion.toml) | `fs` read, string iteration, counts |
+| [examples/data_lib/main.ion](examples/data_lib/main.ion) | [data_lib/ion.toml](examples/data_lib/ion.toml) | Multi-module library; see [data_lib/README.md](examples/data_lib/README.md) |
+
+`examples/data_lib/` keeps only `.ion` sources; `ion-build` writes `.c`, `.h`, and the executable under `examples/data_lib/target/` (not committed).
 
 ## Project Structure
 
@@ -233,8 +203,9 @@ cd examples/data_lib
 │   ├── lexer/      # Tokenizer
 │   ├── parser/     # AST construction
 │   ├── ast/        # AST node definitions
-│   ├── compiler/   # Compilation driver (module resolution, cycle detection)
-│   ├── tc/         # Type Checker (safety checks, visibility, qualified names)
+│   ├── compiler/   # Module resolution, import paths
+│   ├── build/      # ion.toml, ion-build driver, C toolchain
+│   ├── tc/         # Type checker (safety, visibility, qualified names)
 │   ├── ir/         # Intermediate representation
 │   └── cgen/       # C code generator
 ├── runtime/        # C runtime headers