docs(agents): link plain-text references to the split topic files

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

8 files changed, 16 insertions, 11 deletions

diff --git a/AGENTS/ARCH/BUILD.md b/AGENTS/ARCH/BUILD.md
index dcad28d..2e4cc69 100644
--- a/AGENTS/ARCH/BUILD.md
+++ b/AGENTS/ARCH/BUILD.md
@@ -8,7 +8,7 @@ development files to build; NONE supports both outputs.
 The following commands use Debian/Ubuntu's versioned compiler names:
 
 ```bash
-# Prepare dependencies using the recommendations in doc/build.md.
+# Prepare dependencies using the recommendations in doc/build.md (see DEPENDENCIES.md).
 cmake -S . -B build -DCPSC_RUN_MODE=EMBEDDED \
   -DCMAKE_C_COMPILER=clang-23 -DCMAKE_CXX_COMPILER=clang++-23
 cmake --build build
@@ -26,7 +26,8 @@ automatically. Manually linking emitted `.ll` files still requires a C++ driver
 TRY/CATCH/ENDTRY and bare THROW are compiler extensions.
 Runtime checks print the source line and error reason to stderr before throwing
 anonymous exceptions; the final handler in generated main
-prints `Unhandled exception. Program terminated.` to stderr and returns 1.
-Nightly CI runs compiler tests, including embedded exception execution, on
+prints `Unhandled exception. Program terminated.` to stderr and returns 1
+(lowering details: [RUNTIME_CHECKS_EXCEPTIONS.md](../SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md)).
+[Nightly CI](NIGHTLY.md) runs compiler tests, including embedded exception execution, on
 Linux, Windows and macOS with LLVM 23. Platform-specific changes require
 successful checks on the native runner.
diff --git a/AGENTS/ARCH/DRIVER.md b/AGENTS/ARCH/DRIVER.md
index 69a2402..49a85be 100644
--- a/AGENTS/ARCH/DRIVER.md
+++ b/AGENTS/ARCH/DRIVER.md
@@ -1,6 +1,8 @@
 # Driver behavior
 
-Driver behavior (`tools/driver/main.cc`):
+Driver behavior (`tools/driver/main.cc`). CodeGen-side unit and entry-point invariants are in
+[CONVENTIONS/EXCEPTIONS_AND_UNITS.md](../CONVENTIONS/EXCEPTIONS_AND_UNITS.md); diagnostic
+style is in [CONVENTIONS/SYMBOLS_AND_ERRORS.md](../CONVENTIONS/SYMBOLS_AND_ERRORS.md).
 
 - One or more source files, with optional `-S`, `-o path`, `-r` and `-no-std`; options may appear among inputs.
   Each stream is parsed independently. INCLUDE paths are relative to the including file,
diff --git a/AGENTS/ARCH/INSTALL.md b/AGENTS/ARCH/INSTALL.md
index 4c609c5..bf6a1bc 100644
--- a/AGENTS/ARCH/INSTALL.md
+++ b/AGENTS/ARCH/INSTALL.md
@@ -36,7 +36,8 @@ generate `build/doc/cpsc.1`. The section 1 source is `doc/cpsc.1.md`; section 7
 `doc/language/**/*.7.md`. `doc` builds every page, preserving the language
 category subdirectories, as `.7` on Unix or `.html` on Windows. Sources are discovered with
 CONFIGURE_DEPENDS; per-page commands regenerate only changed pages.
-`cmake/ManualLinks.lua` renders cross-references as man names or local HTML links.
+`cmake/ManualLinks.lua` renders cross-references as man names or local HTML links
+(manual source rules: [MAN.md](../MAN.md)).
 Windows `mingw32-make -C build install` builds the HTML manual and invokes
 `install.ps1` through Windows PowerShell with the build directory and
 `CMAKE_INSTALL_PREFIX`. The default Windows prefix is the per-user Programs
diff --git a/AGENTS/ARCH/OVERVIEW.md b/AGENTS/ARCH/OVERVIEW.md
index 6984646..5bb4a86 100644
--- a/AGENTS/ARCH/OVERVIEW.md
+++ b/AGENTS/ARCH/OVERVIEW.md
@@ -14,7 +14,7 @@ files ──> Lexer ──> Parser ──> vector<unique_ptr<StmtAST>> ──> C
 Fixed value representation (ABI — much code infers types backwards from these):
 INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`. STRING is the standard-library class `%record.STRING`, owning a std::string handle; C_STRING is a raw NUL-terminated pointer. User-defined types (§4): enum = `i64` (0-based ordinal),
 pointer = opaque `ptr`, record = named struct `%record.NAME`. Enums and pointers are LLVM-identical to INTEGER/C_STRING **by design** — their identity lives in the type
-*name*, enforced upstream (see CONVENTIONS.md). Allocation byte sizes are never computed
+*name*, enforced upstream (see [CONVENTIONS/TYPES.md](../CONVENTIONS/TYPES.md)). Allocation byte sizes are never computed
 host-side: the module has no DataLayout string, so every allocation size is a null-GEP
 `sizeof` constant (`TypeSystem::getSizeOfConstant`) folded by the backend.
 
@@ -24,7 +24,7 @@ CScalar/CPointer identities are canonical C types, not pseudocode alias names;
 native widths and signedness come from sizeof/type traits, while floating formats
 come from numeric_limits (long double size alone is insufficient). Programs use
 the compiler's build ABI; cross-target emission is not implemented. EXTERN "C"
-declarations call C functions from INCLUDE_OBJ objects (see SUBSYSTEMS.md).
+declarations call C functions from INCLUDE_OBJ objects (see [SUBSYSTEMS/EXTERN.md](../SUBSYSTEMS/EXTERN.md)).
 CTypeGen handles typed numeric conversions, casts, native arithmetic and I/O.
 Crossing C/pseudocode domains requires a cast, including literals. C arithmetic
 uses C++ promotions, except that / always returns pseudocode REAL.
diff --git a/AGENTS/CONVENTIONS.md b/AGENTS/CONVENTIONS.md
index b764915..5bf7c6e 100644
--- a/AGENTS/CONVENTIONS.md
+++ b/AGENTS/CONVENTIONS.md
@@ -1,7 +1,8 @@
 # Load-bearing conventions
 
 These invariants span modules. Violating any of them breaks code you didn't touch.
-(Overview and build instructions: `ARCH.md`.) The details are split by topic under
+(Overview and build instructions: [ARCH/OVERVIEW.md](ARCH/OVERVIEW.md),
+[ARCH/BUILD.md](ARCH/BUILD.md).) The details are split by topic under
 `AGENTS/CONVENTIONS/`.
 
 - [LEXING.md](CONVENTIONS/LEXING.md) — English-only project text, raw `int` tokens,
diff --git a/AGENTS/EXTENDING.md b/AGENTS/EXTENDING.md
index 668941b..5728ac5 100644
--- a/AGENTS/EXTENDING.md
+++ b/AGENTS/EXTENDING.md
@@ -1,6 +1,6 @@
 # Extension recipes
 
-Step-by-step patterns for adding features. Read `CONVENTIONS.md` first — every recipe
+Step-by-step patterns for adding features. Read [CONVENTIONS.md](CONVENTIONS.md) first — every recipe
 below assumes those invariants.
 
 **New statement:** token in `Lexer.h` enum + keyword match in `Lexer.cc`'s if-chain →
diff --git a/AGENTS/SUBSYSTEMS.md b/AGENTS/SUBSYSTEMS.md
index a11cf33..d3a7dba 100644
--- a/AGENTS/SUBSYSTEMS.md
+++ b/AGENTS/SUBSYSTEMS.md
@@ -1,7 +1,7 @@
 # Subsystem notes
 
 Deep-dives on the CodeGen helper subsystems, split by topic under `SUBSYSTEMS/`.
-(Invariants: `CONVENTIONS.md`; known bugs: `PITFALLS.md`.)
+(Invariants: [CONVENTIONS.md](CONVENTIONS.md); known bugs: [PITFALLS.md](PITFALLS.md).)
 
 - [Arrays](SUBSYSTEMS/ARRAYS.md): `ArrayHandler` storage, checked indexing, array
   parameters and array OUTPUT.
diff --git a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
index c80f825..8cec5e9 100644
--- a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
+++ b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
@@ -51,5 +51,5 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Related: [class lifetime](CLASS
 - Native binaries require the C++ runtime; EmbeddedRunner defines its statically linked
   ABI symbols with ORC `absoluteSymbols`, while LLJIT with JITLink manages unwind frames
   (generic EH-frame on Linux, compact-unwind or EH-frame on macOS, COFF SEH registration
-  on Windows x86_64).
+  on Windows x86_64); see [ARCH/EMBEDDED_RUNNER.md](../ARCH/EMBEDDED_RUNNER.md).
 - Nightly CI exercises embedded exception execution on all three platforms.