document

name	document
description	Create or update a crate's README documentation
argument-hint	<crate-path>

Parse $ARGUMENTS:

• The first argument is the crate path. Replace $TARGET with it.

Crate Documentation

Analyze the Rust crate at $TARGET and create or update its README.md.

If a README already exists, preserve any manually written content that is still accurate and fill in missing sections. If no README exists, create one from scratch.

README Structure

Follow this section order. Every section is required unless marked optional.

1. Title and Summary

# henyey-<crate>

One-line description of the crate's purpose.

2. Overview

One paragraph explaining what the crate does and where it sits relative to other henyey crates. Mention the key upstream stellar-core component it corresponds to if applicable.

3. Architecture

A single diagram showing the crate's internal structure or its relationship to adjacent crates. Pick the ONE type that best fits:

• STATE MACHINE — for crates with explicit state enums or modal behavior.
• DATA FLOW — for crates that transform or route data.
• MODULE DEPENDENCY — for crates with 5+ internal modules.
• SEQUENCE — for crates with complex multi-step protocols.

Use Mermaid syntax so diagrams render on GitHub. Keep diagrams focused — max 15 nodes.

4. Key Types

A table of the crate's important public types:

| Type | Description |
|------|-------------|
| `Foo` | ... |

Aim for 5-15 rows. Include traits, important enums, and config structs. Omit internal helpers.

5. Usage

2-3 short code examples showing the main API patterns. Cover the most common use cases: construction, the primary operation, and one edge case or secondary pattern (e.g., catchup mode, error handling).

Use rust fenced code blocks. Examples should compile conceptually but do not need to be runnable standalone.

6. Module Layout

A table mapping each source file to its purpose:

| Module | Description |
|--------|-------------|
| `lib.rs` | ... |
| `foo.rs` | ... |

7. Design Notes (optional)

Include only if the crate has non-obvious design decisions that a new contributor would find surprising. Examples: savepoint semantics, change coalescing rules, determinism constraints, thread-safety approach.

Skip this section entirely if there is nothing surprising — do not pad with obvious statements.

8. stellar-core Mapping

A table mapping Rust modules to upstream stellar-core C++ files:

| Rust | stellar-core |
|------|--------------|
| `foo.rs` | `src/bar/Foo.cpp` |

This is critical for parity work. If the crate has no upstream equivalent, say so and omit the table.

9. Parity Status

## Parity Status

See [PARITY_STATUS.md](PARITY_STATUS.md) for detailed stellar-core parity analysis.

Only include if $TARGET/PARITY_STATUS.md exists.

Guidelines

• Read all source files before writing. Understand the crate before documenting it.
• Be precise about types and APIs — verify names against the actual code.
• Do not document test code or stellar-core/.
• When updating an existing README, diff your changes mentally against what's there. Preserve accurate content, fix stale content, add missing sections.
• Keep the total README under 250 lines for small crates (<5 modules) and under 600 lines for large ones.