docs(agents): collapse duplicated passages into single-home links

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

15 files changed, 35 insertions, 36 deletions

diff --git a/AGENTS/ARCH/DRIVER.md b/AGENTS/ARCH/DRIVER.md
index 49a85be..af3925a 100644
--- a/AGENTS/ARCH/DRIVER.md
+++ b/AGENTS/ARCH/DRIVER.md
@@ -35,7 +35,7 @@ style is in [CONVENTIONS/SYMBOLS_AND_ERRORS.md](../CONVENTIONS/SYMBOLS_AND_ERROR
   compilation, such as file I/O errors, use `fatal error:`. The driver prints
   `compilation terminated.` once on compilation failure, including argument errors.
   Multi-input lexer/parser/codegen diagnostics append the source path after the line number;
-  Diagnostics.h keeps single-input diagnostic text unchanged.
+  single-input diagnostics (Diagnostics.h) do not append it.
   Execution-stage failures do not print that line. Check the exit code rather
   than grepping stderr.
 - Successful compilation overwrites the output, but paths aliasing any input source
diff --git a/AGENTS/ARCH/EMBEDDED_RUNNER.md b/AGENTS/ARCH/EMBEDDED_RUNNER.md
index 7fe0780..0899254 100644
--- a/AGENTS/ARCH/EMBEDDED_RUNNER.md
+++ b/AGENTS/ARCH/EMBEDDED_RUNNER.md
@@ -30,6 +30,6 @@
   Initialize the JIT before looking up `main` and deinitialize while its code is
   still mapped. Execution failures return 1 without `compilation terminated.`.
   No external runner or PATH lookup is used; `-r` alone runs in memory.
-  Platform-specific changes require native CI verification.
+  Platform-specific changes require native CI verification ([BUILD.md](BUILD.md)).
 
 The embedded JIT lazily loads the captured C++ standard-library and compiler-support archives using StaticLibraryDefinitionGenerator. Members defining exception ABI or unwind symbols are filtered so all exception frames use the host runtime; additional host ABI functions are exposed explicitly. Archive buffers own their extracted bytes for the JIT lifetime.
diff --git a/AGENTS/ARCH/INSTALL.md b/AGENTS/ARCH/INSTALL.md
index bf6a1bc..fa21bac 100644
--- a/AGENTS/ARCH/INSTALL.md
+++ b/AGENTS/ARCH/INSTALL.md
@@ -2,7 +2,8 @@
 
 On Linux, `make -C build install` builds the manual and calls the POSIX
 `install.sh` to copy `cpsc` into `CMAKE_INSTALL_PREFIX/bin` and all manuals into
-`CMAKE_INSTALL_PREFIX/share/cpsc/man/man1` and `man7` (default prefix `/usr/local`).
+`CMAKE_INSTALL_PREFIX/share/cpsc/man/man1` and `man7` (default prefix `/usr/local`);
+section 7 pages are installed together in `man7` without category subdirectories.
 Linux man-db registration appends a deduplicated MANDATORY_MANPATH entry to
 `/etc/manpath.config` or `/etc/man_db.conf` as root, or `~/.manpath` as a user.
 macOS root registration uses `/usr/local/etc/man.d/cpsc.conf`; user installation
@@ -47,6 +48,7 @@ The release target explicitly passes the configured Windows flag to
 host platform. Windows packages `cpsc.exe`, `doc/cpsc.html`, `doc/language/**/*.html`, `install.ps1` and
 `LICENSE` as `build/cpsc-VERSION-Windows-ARCH.zip` using CMake's default Deflate
 compression. Unix retains `.tar.xz`, the POSIX installer and the man pages.
+Generated files and release packages preserve the language category layout.
 Linux smoke tests can configure an isolated build with `-DWIN32=TRUE` to exercise
 HTML/ZIP packaging; the resulting renamed Linux executable is only a test fixture,
 not a usable Windows release.
diff --git a/AGENTS/ARCH/LINKING.md b/AGENTS/ARCH/LINKING.md
index d0efe81..7bf1ecd 100644
--- a/AGENTS/ARCH/LINKING.md
+++ b/AGENTS/ARCH/LINKING.md
@@ -30,7 +30,7 @@ prefix, and leaves LLVM itself installed. Source and build caches are versioned;
 the resulting local `lib/cmake/lld` takes precedence over shared system packages.
 The helper's build-time linker can use the installed LLVM dylib; cpsc still links
 the LLD archives and static LLVM components.
-Both macOS configurations explicitly select the SDK with `CMAKE_OSX_SYSROOT`
+Both macOS builds (the LLD helper and cpsc) explicitly select the SDK with `CMAKE_OSX_SYSROOT`
 before compiler detection, so imported SDK include paths do not precede libc++.
 The nightly macOS job's helper caching and LLVM bottle checks are described in
 [NIGHTLY.md](NIGHTLY.md#macos-lld-helper-and-desktop-caches).
diff --git a/AGENTS/ARCH/NIGHTLY.md b/AGENTS/ARCH/NIGHTLY.md
index 8afb53e..00bbe4a 100644
--- a/AGENTS/ARCH/NIGHTLY.md
+++ b/AGENTS/ARCH/NIGHTLY.md
@@ -17,7 +17,7 @@ the current working directory on startup; macOS keeps the compiler inside the ap
 Native runner tests check prefilled input, EOF, diagnostics, output before exit,
 stopping and restart. Portable packages are checked for the desktop executable,
 compiler and notices, then run with toolchain directories removed from PATH.
-The publish job requires both Bundle packages alongside the original four packages.
+The publish job requires both Bundle packages alongside the four compiler and VSIX packages.
 See [`bundle/AGENTS/DEVELOPMENT.md`](../../bundle/AGENTS/DEVELOPMENT.md) for the shared editor and build details.
 
 The Linux compiler and plugin jobs use Ubuntu 24.04 x86_64; the macOS compiler
@@ -35,7 +35,8 @@ packaged binary and checks native generation plus `.ll` output without tool look
 Windows system directories, excluding MSYS2 and LLVM. The macOS check also
 verifies arm64 and rejects non-system dynamic libraries. The plugin uses
 Node.js 22, `npm ci --ignore-scripts` and
-`npm run package`, then checks VSIX contents. Each job retains its checked package
+`npm run package` (which runs the plugin's syntax checks and tests before packaging),
+then checks VSIX contents. Each job retains its checked package
 as a separate Actions artifact for one day, failing if the package is missing.
 Compiler jobs enable
 BUILD_TESTING and run all CTest cases with the push SHA as seed before
@@ -50,7 +51,7 @@ Compiler and VSIX package names use HEAD's UTC commit timestamp and short ID.
 The VSIX internal version is `YYYYMMDD.HHMMSS.0+commit`, with leading zeros
 removed from the numeric time component. Before committing workflow changes, run
 actionlint, simulate release API calls, and smoke-test the packages locally;
-do not modify the real release for local verification.
+do not contact or modify the real release for local verification.
 
 ## macOS LLD helper and desktop caches
 
@@ -64,5 +65,4 @@ compiler/library content, workspace path and helper script hash. No fallback key
 restores a build from a different toolchain. Homebrew updates and the LLVM archive
 symbol check still run before cache lookup. Windows and macOS desktop jobs cache
 compiled Rust dependencies after selecting the toolchain, including on failure;
-project crates rebuild with the current compiler payload. Rust release optimization
-and archive compression settings are unchanged.
+project crates rebuild with the current compiler payload.
diff --git a/AGENTS/ARCH/OVERVIEW.md b/AGENTS/ARCH/OVERVIEW.md
index 5bb4a86..820c5bb 100644
--- a/AGENTS/ARCH/OVERVIEW.md
+++ b/AGENTS/ARCH/OVERVIEW.md
@@ -12,7 +12,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),
+INTEGER = `i64`, REAL = `double`, BOOLEAN = `i1`, CHAR = `i8`. STRING is the standard-library class `%record.STRING` (not a builtin pointer type), 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/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
diff --git a/AGENTS/CONVENTIONS/CALLS.md b/AGENTS/CONVENTIONS/CALLS.md
index 261b06f..1942ded 100644
--- a/AGENTS/CONVENTIONS/CALLS.md
+++ b/AGENTS/CONVENTIONS/CALLS.md
@@ -23,13 +23,13 @@ bridge C void* and nominal pseudocode pointer types.
   invoke a same-class BYREF OVERLOAD NEW when defined; STRING-bearing aggregates
   clone their owned fields. Other classes without a copy constructor copy bits; class
   rvalues transfer ownership. Other values use `emitCoercedExpr`.
-- Top-level prototypes are pre-registered (after the TYPE pre-pass) before statement
-  emission, so call-before-definition is fine; a call with no registered signature is
-  a compile error. Method prototypes are pre-registered too.
+- Top-level prototypes are pre-registered at the start of `compile()` (after the TYPE
+  pre-pass) before statement emission, so call-before-definition is fine; a call with
+  no registered signature is a compile error (no extern is fabricated). Method
+  prototypes are pre-registered too.
 - OVERLOAD signatures append canonical parameter types to the link name; ordinary
-  names except MAIN get no mangling. `getOverloads` filters by visibility and
-  `resolveCall` selects exact static types/ranks. Return types, modes and bounds
-  never distinguish overloads.
+  names except MAIN get no mangling. Overload sets, visibility filtering and exact
+  selection: [SUBSYSTEMS/FUNCTIONS.md](../SUBSYSTEMS/FUNCTIONS.md#signatures-and-call-resolution).
 - In all cases, `emitPrototype` rejects names that collide with runtime/libc symbols
   (`isReservedRuntimeName`), builtins, or enum values. Signatures retain the first
   declaration spelling for LLVM lookup, independently of call-site casing.
diff --git a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
index 023354d..deed7ec 100644
--- a/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
+++ b/AGENTS/CONVENTIONS/EXCEPTIONS_AND_UNITS.md
@@ -14,7 +14,7 @@ Part of [Load-bearing conventions](../CONVENTIONS.md).
 - `RuntimeCheck::emitCheck` prints the source line and error reason to stderr before
   throwing. Generated main catches anything unhandled, prints the generic termination
   message to stderr, and returns 1. Explicit bare THROW prints no diagnostic itself.
-- Arrays in TRY and CATCH use separate block scopes; scalars retain existing function
+- Arrays in TRY and CATCH use separate block scopes; scalars keep function
   scope.
 
 **Compilation units and entry points.**
diff --git a/AGENTS/CONVENTIONS/TYPES.md b/AGENTS/CONVENTIONS/TYPES.md
index ff6ddf8..664782e 100644
--- a/AGENTS/CONVENTIONS/TYPES.md
+++ b/AGENTS/CONVENTIONS/TYPES.md
@@ -9,11 +9,9 @@ resolves the string to `TypeInfo{LLVMType, Kind, per-kind payload}`. The parser'
 outside a RETURNS clause via its `AllowVoid` flag); other unknown types only fail
 (softly) in CodeGen.
 
-**Fixed IR representation per builtin type.** INTEGER = `i64`, REAL = `double`,
-BOOLEAN = `i1`, CHAR = `i8`. STRING is the ordinary standard-library class
-`%record.STRING`, not a builtin pointer type. C_STRING remains a raw NUL-terminated C
-pointer. Some arithmetic code still infers types backwards from LLVM widths;
-preserve the builtin scalar ABI.
+**Fixed IR representation per builtin type.** The table lives in
+[ARCH/OVERVIEW.md](../ARCH/OVERVIEW.md). Some arithmetic code still infers types
+backwards from LLVM widths; preserve the builtin scalar ABI.
 
 **C aliases are structural within the C domain.** `CIdentity` retains the canonical
 C base type and pointer levels independently of the alias `Name`. Use `sameType`
@@ -42,7 +40,5 @@ and handles C/user kinds before builtin arithmetic. `coerceValueToType` hard-err
 (not `Symbols`, so they survive FunctionGen's save/clear/restore). Expression
 resolution order is `Symbols` first, then enum constants; collisions with
 DECLARE/array/parameter/function names are compile errors at declaration time, so
-the order can never shadow. TYPE declarations are top-level only, registered by
-`compile()`'s two-pass pre-scan (names first — pointer pointees may
-forward-reference; definitions second, in source order — a by-value record field
-requires its record type to be already complete).
+the order can never shadow. TYPE declarations are top-level only and registered in
+two passes; see [SUBSYSTEMS/USER_TYPES.md](../SUBSYSTEMS/USER_TYPES.md#registration).
diff --git a/AGENTS/MAN.md b/AGENTS/MAN.md
index 80e563c..b581c92 100644
--- a/AGENTS/MAN.md
+++ b/AGENTS/MAN.md
@@ -21,6 +21,6 @@ Use relative Markdown links between source pages, including `../` when crossing
 
 ## Build and verification
 
-`doc`, `install` and `release` generate all manuals with Pandoc; ordinary builds do not need it. CMake discovers language sources recursively and preserves categories in generated files and release packages. Windows installs HTML with the same category layout. Unix installs all section 7 pages together in `PREFIX/share/cpsc/man/man7`, alongside the command page in `man1`; manpath registration is handled by the installer.
+Generation, installation and packaging of the manuals (Pandoc, `doc`/`install`/`release` targets, category layout, manpath registration) are described in [ARCH/INSTALL.md](ARCH/INSTALL.md).
 
 Before committing, run `cmake --build build --target doc`, check the affected links and render a changed page with `man -l build/doc/language/keyword/cpsc-keyword-if.7` (use the relevant path). For formatting-only edits, a comparison of Pandoc's man output before and after is sufficient. For path changes, also check HTML links, package contents and a DESTDIR installation. Keep verification simple; do not add a test framework for manual edits.
diff --git a/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md b/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
index 5df620b..727a1af 100644
--- a/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
+++ b/AGENTS/SUBSYSTEMS/CLASS_LIFETIME.md
@@ -50,7 +50,8 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Builds on [classes](CLASSES.md)
 - emitOwnedValue constructs lvalue copies and keeps pending arguments Alive until
   marshalling succeeds. RETURN copies lvalues and transfers rvalues.
 - Records and BYVAL arrays recursively clone STRING-bearing fields/elements. Other
-  owning class fields retain the existing shallow-copy limits.
+  owning class fields are copied shallowly (see the
+  [copy limits](../PITFALLS/classes.md#copy-limits)).
 - StackObject::Temporary uses statement cleanup and deferred temporary-only cleanup
   before local handlers, while ordinary objects remain function-scoped.
 - Function-result method receivers are materialized by the same path as operator
@@ -58,4 +59,4 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Builds on [classes](CLASSES.md)
 - Assignment first selects an exact member OPERATOR<-; without one, STRING-bearing
   aggregate assignment clones string fields from lvalues or transfers them from rvalues,
   releasing the target's old string fields without invoking the enclosing class
-  destructor; other classes retain their existing bitwise assignment behavior.
+  destructor; other classes are assigned bitwise.
diff --git a/AGENTS/SUBSYSTEMS/FUNCTIONS.md b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
index 523d114..0297c48 100644
--- a/AGENTS/SUBSYSTEMS/FUNCTIONS.md
+++ b/AGENTS/SUBSYSTEMS/FUNCTIONS.md
@@ -28,16 +28,16 @@ canonical parameter list (MAIN uses internal __cps_main).
   overload-set map (`FunctionGen::getOverloads`, filtered by unit visibility).
 - `resolveCall` selects exact static parameter types/ranks for OVERLOAD, while a single
   ordinary definition keeps implicit conversions.
-- Parameter keys exclude return types, modes and bounds; equivalent C aliases use
+- Parameter keys exclude return types, modes and bounds (they never distinguish
+  overloads); equivalent C aliases use
   CIdentity. Every same-name definition must be OVERLOAD; duplicate keys fail even
   across invisible units.
 - FunctionGen tracks prototype registration separately from source names and indexes
   signatures by LLVM link name for RETURN (`getSignatureByLink`).
 - `CodeGen::marshalCallArgs` consumes the selected FuncSig, and `getExprTypeInfo`
   resolves the same calls without emitting IR.
-- Top-level prototypes are pre-registered at the start of `compile()` (after the TYPE
-  pre-pass), so calls may precede definitions; calling a name with no signature is a
-  compile error (no extern is fabricated).
+- Prototype pre-registration (calls may precede definitions): see
+  [CONVENTIONS/CALLS.md](../CONVENTIONS/CALLS.md).
 
 ## Operator overloads (`OperatorGen.cc`)
 
diff --git a/AGENTS/SUBSYSTEMS/MEMORY.md b/AGENTS/SUBSYSTEMS/MEMORY.md
index 8c61585..8b0ccfc 100644
--- a/AGENTS/SUBSYSTEMS/MEMORY.md
+++ b/AGENTS/SUBSYSTEMS/MEMORY.md
@@ -9,7 +9,7 @@ resize helpers and a linked list of live allocation start addresses.
 ## Tracking
 
 - Explicit MALLOC/REALLOC and keyword NEW allocations enter the list; STRING/ARRAY
-  internals retain their existing ownership.
+  internals are not tracked here and keep their own ownership.
 - Helpers use RuntimeCheck and ExceptionHandler, including source-line arguments and
   per-function unwind preparation.
 - Sizes accept INTEGER and C integers and convert to native size_t.
diff --git a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
index 8cec5e9..fdd10fb 100644
--- a/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
+++ b/AGENTS/SUBSYSTEMS/RUNTIME_CHECKS_EXCEPTIONS.md
@@ -52,4 +52,4 @@ Part of the [subsystem notes](../SUBSYSTEMS.md). Related: [class lifetime](CLASS
   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); see [ARCH/EMBEDDED_RUNNER.md](../ARCH/EMBEDDED_RUNNER.md).
-- Nightly CI exercises embedded exception execution on all three platforms.
+- CI coverage of embedded exception execution: [ARCH/BUILD.md](../ARCH/BUILD.md).
diff --git a/AGENTS/TESTING.md b/AGENTS/TESTING.md
index 08b7bbd..a43d0fb 100644
--- a/AGENTS/TESTING.md
+++ b/AGENTS/TESTING.md
@@ -22,6 +22,6 @@ All commands run without a shell and retain their exact argv, working directory,
 
 Perl generators use Random.pm's SHA-256 sequence with explicit big-endian extraction, fixed group identity and decimal counter. `generator-vectors.json` pins 100 records plus boundaries using the all-zero 40-character seed; update a vector only when deliberately changing a generator, and verify repeatability and a different seed. C++ references must avoid undefined behavior and implement the specification independently. Use arithmetic closed forms or standard containers where they provide an independent oracle. Record platform-dependent C behavior as such; never call it CIE behavior.
 
-Before committing a test change, build the affected references and run the affected CTest cases. Compiler defects may fail: inspect retained diagnostics and document the failure accurately. Before committing workflow changes, run actionlint and retain the existing release API simulation/package smoke checks without contacting the real release. No compiler implementation changes belong in a tests-only task.
+Before committing a test change, build the affected references and run the affected CTest cases. Compiler defects may fail: inspect retained diagnostics and document the failure accurately. Workflow changes follow the commit checks in [ARCH/NIGHTLY.md](ARCH/NIGHTLY.md). No compiler implementation changes belong in a tests-only task.
 
 The explicit STRING library integration fixture lives in `tests/library/exp-string`. CMake copies it to the build tree as `test-cases/i/exp-string`, where relative source paths reach the built library and its object file. It passes -no-std to avoid loading a second library copy. Manifests may supply compiler_args for every native/IR/runner compiler invocation. It uses the ordinary native/runner harness and appears as `i/exp-string` in CTest.