docs: complete component setup and usage guides

README.md

@@ -81,9 +81,9 @@ Generation or repair completing does not mean every candidate passes. Inspect bo
 | --- | --- |
 | [brinfo](brinfo/README.md) | Extract function condition chains from HIR and MIR. |
 | [focxt](focxt/README.md) | Construct code context for each focal function. |
-| `focxt/call_chain/` | Extract calls and type dependencies through `cargo call-chain`. |
+| [focxt/call_chain](focxt/call_chain/README.md) | Extract calls and type dependencies through `cargo call-chain`. |
 | [utgen](utgen/README.md) | Generate tests, check compilation, repair tests, and collect coverage. |
-| `build-utils/` | Configure the compiler library search path during builds. |
+| [build-utils](build-utils/README.md) | Configure the compiler library search path during builds. |
 | [examples](examples/README.md) | The minimal fixture, bundled bytes target, and usage instructions. |
 | `docker/` | Container build and run scripts. |
 | [docs](docs/README.md) | Technical guide, validation guides, and ASE 2025 materials. |

brinfo/README.md

@@ -1,19 +1,41 @@
 # brinfo
 
-This tool is used to extract the condition chains of functions or methods in a specified project.
+brinfo extracts condition chains for Rust functions and methods using the compiler's HIR and MIR. In [PALM](../README.md), these chains supply path constraints for test generation.
 
-## Build
+## Build and install
 
-To build brinfo, run `cargo build` in the `brinfo` directory.
+Follow the [project prerequisites](../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root:
+
+```sh
+cargo build -p brinfo --locked
+cargo install --path brinfo --locked
+```
+
+Installation places `cargo-brinfo` and its companion compiler driver `brinfo` in Cargo's binary directory. Ensure that directory is in `PATH`; invoke analysis through `cargo brinfo`. No model configuration is needed.
 
 ## Usage
 
-Navigate to the directory of the project or subproject you want to analyze. In the root directory of the project being analyzed, you need to add a file named `rust-toolchain.toml` :
+Use a working copy of a standalone crate with the same pinned toolchain. For the test-generation workflow, [preprocess and analyze with utgen](../utgen/README.md#analysis): it runs brinfo and focxt and checks that their outputs agree.
 
-```toml
-[toolchain]
-channel = "nightly-2025-03-19"
-components = ["rust-src", "rustc-dev", "llvm-tools-preview"]
+To run only condition-chain extraction, enter the prepared target crate:
+
+```sh
+cd /absolute/path/to/target-crate
+cargo clean
+cargo brinfo
 ```
 
-You can start by running `cargo clean` to clear the existing build cache, and then run `cargo brinfo` in that directory to start the analysis.
+The wrapper analyzes the crate's `lib` and `bin` targets through `cargo check`. Clearing the build cache ensures the compiler analysis runs even if the crate was previously checked. Use a fresh working copy without previous analysis output when repeating an experiment; `cargo clean` does not remove PALM's output files.
+
+## Output
+
+Paths are relative to the target crate:
+
+| Path | Contents |
+| --- | --- |
+| `brinfo/name_map.json` | Full function names mapped to encoded artifact identifiers. |
+| `brinfo/brdata/<encoded>.json` | Function source and location, condition chains, and representative-chain selection. |
+
+Use the index to locate artifacts. Pass its full function names to `utgen gen --functions-file` or `utgen fix --functions-file` to select functions. Generation also needs [focxt](../focxt/README.md) output from the same prepared source.
+
+For an offline check on the bundled fixture, see [minimal pipeline validation](../docs/minimal-pipeline.md). The [technical guide](../docs/palm-rust-unit-test-generation.md) explains condition-chain extraction in more detail.

build-utils/README.md

@@ -0,0 +1,15 @@
+# build-utils
+
+build-utils is an internal build dependency of [PALM](../README.md). The tool crates call `build_utils::setup_build()` from their `build.rs` scripts to configure the runtime search path for Rust compiler libraries.
+
+`setup_build()` reads `rustc --print sysroot` and emits a linker rpath pointing to that toolchain's `lib` directory. Use the [pinned toolchain and components](../README.md#prerequisites) when building PALM.
+
+## Build
+
+From the PALM repository root:
+
+```sh
+cargo build -p build-utils --locked
+```
+
+This crate is built automatically with the tools. It has no CLI or separate installation step. To check its effect on the tool binaries, build the workspace with `cargo build --workspace --locked` and run the [development checks](../README.md#development-checks).

focxt/README.md

@@ -1,26 +1,46 @@
 # focxt
 
-This tool is capable of analyzing the context for a specified Rust crate.
+focxt constructs the source context for each focal function in [PALM](../README.md). It combines compiler-derived calls and types with source-level modules, declarations, and implementations to produce context for test-generation prompts.
 
-## Build
+## Build and install
+
+Follow the [project prerequisites](../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root:
 
 ```sh
-cargo build
+cargo build -p call_chain -p focxt --locked
+cargo install --path focxt/call_chain --locked
+cargo install --path focxt --locked
 ```
 
+focxt invokes `cargo call-chain` at runtime, so install [call_chain](call_chain/README.md) as well as focxt and keep Cargo's binary directory in `PATH`. Rebuild and install both together after changes to their shared analysis data. No model configuration is needed.
+
 ## Usage
 
-```bash
-A rust program to get focal context for a crate.
+Use a working copy of a standalone crate with the same pinned toolchain. For the test-generation workflow, [preprocess and analyze with utgen](../utgen/README.md#analysis): it runs both brinfo and focxt and validates their outputs.
 
-Usage: focxt --crate <CRATE_PATH>
+To construct context directly from prepared source:
 
-Options:
-  -c, --crate <CRATE_PATH>  Sets crate path
-  -h, --help                Print help
-  -V, --version             Print version
+```sh
+focxt --crate /absolute/path/to/target-crate
 ```
 
-`focxt -c crate_path` or `focxt --crate crate_path`
+`-c` is the short form of `--crate`. focxt runs `cargo clean` and `cargo call-chain` inside the target before building context; running call-chain separately is unnecessary for this command. Start with a fresh working copy when repeating analysis, since build-cache cleanup does not remove previous context artifacts.
+
+## Output
+
+Paths are relative to the target crate:
+
+| Path | Contents |
+| --- | --- |
+| `focxt/impl_informations.json` | Function identities, source locations, and encoded artifact identifiers from call-chain. |
+| `focxt/<encoded>.rs` | Per-function context used by utgen. |
+| `focxt/callsandtypes/<encoded>.json` | Direct calls and type dependencies from call-chain. |
+| `focxt/new_callsandtypes/<encoded>.json` | Calls and types expanded during context construction. |
+
+Additional text files under `focxt/` describe parsed declarations and module trees for debugging. Generation also requires [brinfo](../brinfo/README.md) output from the same prepared source.
+
+## Scope and checks
+
+Function contexts use call-chain's compiler identities and source positions, including distinct generic trait impls and reference receivers. Recoverable macro-generated method bodies are associated with their enclosing source impl; this is not general macro expansion.
 
-Function contexts use call-chain's compiler identities and source positions, including distinct generic trait impls and reference receivers. Recoverable macro-generated method bodies are associated with their enclosing source impl; this is not general macro expansion. Rebuild focxt and call-chain together. See the [bytes analysis validation](../docs/bytes-analysis.md) for release builds, reproducible checks, and current limits.
+See [minimal pipeline validation](../docs/minimal-pipeline.md) for an offline fixture check and [bytes analysis validation](../docs/bytes-analysis.md) for release builds, reproducible checks, and current limits. The [technical guide](../docs/palm-rust-unit-test-generation.md) explains context selection in more detail.

focxt/call_chain/README.md

@@ -0,0 +1,40 @@
+# call_chain
+
+call_chain extracts function identities, direct calls, and type dependencies for [focxt](../README.md). It is a compiler-analysis component of [PALM](../../README.md), with the Cargo command `cargo call-chain` and a library shared with focxt.
+
+## Build and install
+
+Follow the [project prerequisites](../../README.md#prerequisites), including the pinned `nightly-2025-03-19` toolchain. From the PALM repository root:
+
+```sh
+cargo build -p call_chain --locked
+cargo install --path focxt/call_chain --locked
+```
+
+Installation provides `cargo-call-chain` and its companion compiler driver `call-chain`. Keep Cargo's binary directory in `PATH` and invoke the tool through `cargo call-chain`. No model configuration is needed.
+
+## Usage
+
+focxt runs call-chain automatically. Use [utgen analysis](../../utgen/README.md#analysis) for the complete analysis stage, or [focxt](../README.md#usage) to construct context directly.
+
+To inspect only compiler-derived calls and types, enter a fresh working copy of a prepared standalone crate using the same pinned toolchain:
+
+```sh
+cd /absolute/path/to/target-crate
+cargo clean
+cargo call-chain
+```
+
+The wrapper analyzes `lib` and `bin` targets through `cargo check`. Clearing the build cache ensures analysis executes after an earlier check; it does not remove previous `focxt/` output.
+
+## Output
+
+Paths are relative to the target crate:
+
+| Path | Contents |
+| --- | --- |
+| `focxt/impl_informations.json` | Function and impl identities, source locations, and encoded artifact identifiers. |
+| `focxt/callsandtypes/<encoded>.json` | Direct calls and type dependencies for each function. |
+| `focxt/basic_blocks/<encoded>.txt` | MIR basic blocks and locals for debugging. |
+
+call-chain supplies compiler data; focxt produces the per-function `.rs` context files used by generation. Changes to shared data should be checked with both tools. See [minimal pipeline validation](../../docs/minimal-pipeline.md) and [bytes analysis validation](../../docs/bytes-analysis.md).

utgen/README.md

@@ -2,6 +2,8 @@
 
 utgen generates Rust tests from condition chains and focal context, checks compilation, repairs compilation errors, and collects coverage and execution statistics.
 
+For a first run, start with [PALM's offline quick start](../README.md#quick-start), then follow the [two-function model trial](../examples/README.md#prepare-a-small-model-trial). This page is the detailed command reference.
+
 ## Prerequisites
 
 Model configuration is loaded at runtime, once per `gen` or `fix` command. Building, installing, running help, `pre-process`, `analyze`, and `coverage` do not require it.
@@ -60,6 +62,8 @@ cargo build -p utgen --locked
 cargo install --path utgen --locked
 ```
 
+The `analyze` command also requires [brinfo](../brinfo/README.md), [focxt](../focxt/README.md), and [call_chain](../focxt/call_chain/README.md) on `PATH`. Use the [root installer](../README.md#installation) to install all tools. Installing utgen alone does not install these companion executables.
+
 ## Testing
 
 ```sh