fix(docs): digestability

Author: jktrn-osec

docs-v2/src/content/docs/v2/fundamentals/cpi.mdx

@@ -41,7 +41,13 @@ pub fn deposit(ctx: &mut Context<Deposit>, lamports: u64) -> Result<()> {
 }
 ```
 
-The module exposes `transfer{:rs}`, `create_account{:rs}`, `allocate{:rs}`, `assign{:rs}`, `*_with_seed{:rs}` variants for each, and the nonce-account family. The `with_seed{:rs}` variants are useful when a base address is owned by another program and the resulting account address is derived deterministically.
+The module exposes typed wrappers for the System Program instructions:
+
+| Wrappers | Use for |
+| --- | --- |
+| `transfer{:rs}`, `create_account{:rs}`, `allocate{:rs}`, `assign{:rs}` | Ordinary signed account creation and lamport movement. |
+| `*_with_seed{:rs}` variants of each | Cases where the base address is owned by another program and the resulting account address is derived deterministically. |
+| The nonce-account family | Nonce account creation, withdrawal, authorization, and advance. |
 
 ## SPL token CPI
 
@@ -152,4 +158,9 @@ ctx.accounts.profile.reacquire_borrow_mut(ctx.program_id)?;
 
 That missing `Deref{:rs}` is intentional. It prevents accidental use with checked pinocchio CPI builders that would re-borrow the same account views.
 
-`CpiContext::invoke(data){:rs}` uses pinocchio's `invoke_signed_unchecked{:rs}`. Anchor keeps that path safe for ordinary typed CPI by making CPI account structs hold `CpiHandle<'a>{:rs}` values that borrow the typed account wrappers for the duration of the call. Rust rejects concurrent typed mutable access, while pinocchio's account borrow state still catches stale raw-borrow cases after the CPI.
+`CpiContext::invoke(data){:rs}` uses pinocchio's `invoke_signed_unchecked{:rs}`. The path stays safe for ordinary typed CPI because CPI account structs hold `CpiHandle<'a>{:rs}` values that borrow the typed account wrappers for the duration of the call.
+
+Two layers catch aliasing:
+
+- Rust rejects concurrent typed mutable access at compile time.
+- pinocchio's account borrow state catches stale raw-borrow cases after the CPI returns.

docs-v2/src/content/docs/v2/programs/account-types.mdx

@@ -94,7 +94,9 @@ The nested fields are flattened into the outer account list. `Nested<T>{:rs}` do
 
 `Signer{:rs}`, `Program<T>{:rs}`, `SystemAccount{:rs}`, `UncheckedAccount{:rs}`, and `Sysvar<T>{:rs}` keep ordinary Anchor code readable. `UncheckedAccount{:rs}` performs no validation, so pair it with explicit constraints or handler checks before trusting it.
 
-`Sysvar<T>{:rs}` accepts the pinocchio sysvar types whose payload can be read directly into a typed value: `Clock{:rs}`, `Rent{:rs}`, and `Instructions{:rs}`. `SlotHashes{:rs}` deliberately does not implement `SysvarId{:rs}`, so `Sysvar<SlotHashes>{:rs}` fails to compile with a missing-trait diagnostic. Programs that need slot-hash data should call the partial-read syscall directly through pinocchio.
+`Sysvar<T>{:rs}` accepts the pinocchio sysvar types whose payload can be read directly into a typed value. The supported types are `Clock{:rs}`, `Rent{:rs}`, and `Instructions{:rs}`.
+
+`SlotHashes{:rs}` deliberately does not implement `SysvarId{:rs}`, so `Sysvar<SlotHashes>{:rs}` fails to compile with a missing-trait diagnostic. Programs that need slot-hash data should call the partial-read syscall directly through pinocchio.
 
 ## Trait surface
 

docs-v2/src/content/docs/v2/programs/extensibility.mdx

@@ -93,7 +93,9 @@ pub trait AccountConstraint<A> {
 - `update{:rs}` runs inside an `update(...){:rs}` constraint clause
 - `exit{:rs}` always runs during the account exit phase
 
-Once the impl is in scope, a constraint marker named `my_namespace::key{:rs}` becomes available as `#[account(my_namespace::key = value)]{:rs}` on any account field. The `anchor-spl-v2` crate is built on top of this pattern, using it to implement `token::*{:rs}` and `mint::*{:rs}` as a downstream crate rather than baking them into the core derive. Its `associated_token{:rs}` module currently exposes associated token address derivation helpers.
+Once the impl is in scope, a constraint marker named `my_namespace::key{:rs}` becomes available as `#[account(my_namespace::key = value)]{:rs}` on any account field.
+
+The `anchor-spl-v2` crate is built on this pattern. It implements `token::*{:rs}` and `mint::*{:rs}` as a downstream crate rather than baking them into the core derive. Its `associated_token{:rs}` module currently exposes associated token address derivation helpers.
 
 ## `Id{:rs}` for `Program<T: Id>{:rs}`
 

docs-v2/src/content/docs/v2/programs/pod-types.mdx

@@ -11,7 +11,11 @@ To make `T: Pod{:rs}` easy to satisfy, Anchor ships a small set of alignment-1 w
 
 ## Integer wrappers
 
-`PodU16{:rs}`, `PodU32{:rs}`, `PodU64{:rs}`, `PodU128{:rs}`, and the signed counterparts (`PodI16{:rs}`, `PodI32{:rs}`, `PodI64{:rs}`, `PodI128{:rs}`) store an integer as `[u8; N]{:rs}` with native little-endian encoding. Alignment 1 means no padding around the field, so wide integer fields sit flush against neighbors in a `#[repr(C)]{:rs}` struct. `PodU8{:rs}` and `PodI8{:rs}` are re-exported as type aliases for native `u8{:rs}` and `i8{:rs}` because the primitive types are already alignment 1 and need no wrapper:
+The unsigned wrappers are `PodU16{:rs}`, `PodU32{:rs}`, `PodU64{:rs}`, and `PodU128{:rs}`. The signed wrappers are `PodI16{:rs}`, `PodI32{:rs}`, `PodI64{:rs}`, and `PodI128{:rs}`. Each stores an integer as `[u8; N]{:rs}` with native little-endian encoding.
+
+Alignment 1 means no padding around the field, so wide integer fields sit flush against their neighbors in a `#[repr(C)]{:rs}` struct.
+
+`PodU8{:rs}` and `PodI8{:rs}` are type aliases for native `u8{:rs}` and `i8{:rs}`. The primitives are already alignment 1, so no wrapper is needed:
 
 ```rust title="lib.rs" showLineNumbers=false
 #[account]
@@ -48,7 +52,9 @@ pub struct Listing {
 
 ## `PodVec<T, MAX>{:rs}`
 
-`PodVec<T, MAX>{:rs}` is a fixed-capacity vector with a `u16{:rs}` length prefix, stored inline in the account rather than behind a heap pointer. The on-disk layout is `[len:u16][T; MAX]{:rs}` with no padding, since `T{:rs}` must itself be alignment-1 for the surrounding `#[account]{:rs}` struct to be `Pod{:rs}`. `MAX{:rs}` is baked into the type so the compiler knows the exact size at every site:
+`PodVec<T, MAX>{:rs}` is a fixed-capacity vector with a `u16{:rs}` length prefix, stored inline in the account rather than behind a heap pointer. The on-disk layout is `[len:u16][T; MAX]{:rs}` with no padding.
+
+`T{:rs}` must itself be alignment-1 so the surrounding `#[account]{:rs}` struct can be `Pod{:rs}`. `MAX{:rs}` is baked into the type so the compiler knows the exact size at every call site:
 
 ```rust title="lib.rs" showLineNumbers=false
 #[account]
@@ -61,7 +67,16 @@ pub struct MultisigConfig {
 }
 ```
 
-Mutators come in panicking and fallible pairs. `.push{:rs}`, `.extend_from_slice{:rs}`, and `.set_from_slice{:rs}` panic on overflow. `.try_push{:rs}` and `.try_extend_from_slice{:rs}` return `Result<(), CapacityError>{:rs}`. Indexing accessors (`.as_slice{:rs}`, `.iter{:rs}`, `.get{:rs}`, `.pop{:rs}`, and friends) panic when the stored length prefix exceeds `MAX{:rs}`, which can happen on a `PodVec{:rs}` cast from attacker-controlled bytes. Pair them with `.try_as_slice{:rs}`, `.try_get{:rs}`, `.try_pop{:rs}`, or call `.validate(){:rs}` once at load time. Length-only helpers (`.len{:rs}`, `.is_empty{:rs}`, `.capacity{:rs}`, `.clear{:rs}`, `.truncate{:rs}`) never index into `data{:rs}` and are always safe.
+Methods fall into four groups:
+
+| Group | Methods | Behavior |
+| --- | --- | --- |
+| Panicking mutators | `.push{:rs}`, `.extend_from_slice{:rs}`, `.set_from_slice{:rs}` | Panic on overflow. |
+| Fallible mutators | `.try_push{:rs}`, `.try_extend_from_slice{:rs}` | Return `Result<(), CapacityError>{:rs}`. |
+| Indexing accessors | `.as_slice{:rs}`, `.iter{:rs}`, `.get{:rs}`, `.pop{:rs}` | Panic when the stored length prefix exceeds `MAX{:rs}`. Pair with `.try_as_slice{:rs}`, `.try_get{:rs}`, `.try_pop{:rs}`. |
+| Length-only helpers | `.len{:rs}`, `.is_empty{:rs}`, `.capacity{:rs}`, `.clear{:rs}`, `.truncate{:rs}` | Never index into `data{:rs}`. Always safe. |
+
+The indexing-accessor panic can fire when a `PodVec{:rs}` is cast from attacker-controlled bytes whose length prefix exceeds `MAX{:rs}`. Either use the fallible variants at the call site or call `.validate(){:rs}` once at load time to reject bad bytes up front.
 
 Reach for `PodVec{:rs}` when the upper bound is small and known ahead of time. For genuinely open-ended data, use `BorshAccount<T>{:rs}` with a regular `Vec<T>{:rs}` instead.
 

docs-v2/src/content/docs/v2/reference/cli.mdx

@@ -240,17 +240,21 @@ Use on-chain IDLs carefully while this version is alpha because IDL shapes may c
 
 The `codama` subcommand converts an Anchor IDL to a Codama IDL tree and renders client libraries through the `@codama/cli` toolchain. It is the path for generating cross-language clients from a single program description.
 
+### Convert
+
 ```console showLineNumbers=false
 $ <blue>anchor</blue> codama convert target/idl/counter.json <dim>-o</dim> target/codama-counter.json
 ```
 
 `convert{:bash}` translates an Anchor IDL JSON file into a Codama IDL JSON tree rooted at a `rootNode`. The conversion runs in-process and mirrors the reference TypeScript implementation in `@codama/nodes-from-anchor`, so the output is stable against the JavaScript toolchain.
 
+### Generate
+
 ```console showLineNumbers=false
 $ <blue>anchor</blue> codama generate <dim>-l</dim> js,rust <dim>-p</dim> clients target/idl/counter.json
 ```
 
-`generate{:bash}` runs the same conversion in-process and then hands the result to `@codama/cli` (run via `npx --yes codama` by default) to render clients in one or more languages. Each language is written under `<path>/<language>/{:dir}` and uses the matching `@codama/renderers-*` package:
+`generate{:bash}` runs the same conversion in-process, then hands the result to `@codama/cli` (run via `npx --yes codama` by default) to render clients in one or more languages. Each language is written under `<path>/<language>/{:dir}` and uses the matching `@codama/renderers-*` package:
 
 | Language | Renderer package           |
 | -------- | -------------------------- |
@@ -259,15 +263,17 @@ $ <blue>anchor</blue> codama generate <dim>-l</dim> js,rust <dim>-p</dim> client
 | `rust`   | `@codama/renderers-rust`   |
 | `go`     | `@codama/renderers-go`     |
 
-Useful flags:
+### Flags
 
 | Flag | Description |
 | --- | --- |
 | `<dim>-l</dim> <dim><language></dim>` | Languages to generate. Repeat or comma-separate: `<dim>-l</dim> <dim>js,go</dim> <dim>-l</dim> <dim>rust</dim>`. |
 | `<dim>-p</dim> <dim><path></dim>` | Base output directory. Default: `clients{:dir}`. |
 | `<dim>-o</dim> <dim><file></dim>` | (Convert only) Write Codama IDL JSON to a file instead of stdout. |
 
-`generate{:bash}` shells out to `npx{:bash}`, so the host needs a Node.js toolchain on `PATH`. The Codama IDL is versioned independently from the Anchor IDL, so the rendered clients depend on the `@codama/nodes` version stamped into `rootNode.version`.
+<Callout variant="note" title="Operational notes">
+  `generate{:bash}` shells out to `npx{:bash}`, so the host needs a Node.js toolchain on `PATH`. The Codama IDL is versioned independently from the Anchor IDL, so rendered clients depend on the `@codama/nodes` version stamped into `rootNode.version`.
+</Callout>
 
 ## `<blue>anchor</blue> account`
 

docs-v2/src/content/docs/v2/reference/feature-flags.mdx

@@ -17,7 +17,11 @@ description: 'Reference for the `alloc{:toml}`, `guardrails{:toml}`, `account-re
 
 ## `alloc{:toml}` (default)
 
-The `alloc{:toml}` feature enables `extern crate alloc{:rs}` and re-exports the `alloc{:rs}` crate under `anchor_lang_v2::__alloc{:rs}` so generated macro code can reach `Vec{:rs}`, `String{:rs}`, and other heap-allocated types without forcing each user crate to import them. Disabling the feature is only sensible for embedded targets that have no heap, and the ergonomic cost is significant. Most realistic user code that touches `Vec{:rs}` or `String{:rs}` will not compile with `alloc{:toml}` turned off.
+The `alloc{:toml}` feature enables `extern crate alloc{:rs}` and re-exports the `alloc{:rs}` crate under `anchor_lang_v2::__alloc{:rs}`. Generated macro code reaches `Vec{:rs}`, `String{:rs}`, and other heap-allocated types through that re-export, so user crates do not have to import `alloc{:rs}` themselves.
+
+<Callout variant="note" title="When to disable">
+  Only embedded targets without a heap have a reason to turn `alloc{:toml}` off. The ergonomic cost is significant. Most realistic user code that touches `Vec{:rs}` or `String{:rs}` will not compile without it.
+</Callout>
 
 ## `guardrails{:toml}` (default)
 
@@ -27,16 +31,20 @@ The `guardrails{:toml}` feature enables a small set of runtime checks that catch
 - `is_writable{:rs}` enforcement in data-account `load_mut{:rs}` paths returns an error when the account is not marked `mut{:rs}`
 - executable checks on `Program<T>{:rs}` reject non-program accounts before CPI
 
-Disabling the feature drops those guardrail-only emits, which saves roughly 300 bytes of binary and 1 to 2 CU per account. Only turn it off in production after the program has been thoroughly tested, since the runtime safety net is what catches accidental misuse during development:
+Disabling the feature drops those guardrail-only emits, which saves roughly 300 bytes of binary and 1 to 2 CU per account:
 
 ```toml title="Cargo.toml" showLineNumbers=false
 [dependencies]
 anchor-lang-v2 = { git = "...", branch = "anchor-next", default-features = false, features = ["alloc", "account-resize"] }
 ```
 
+<Callout variant="warning" title="Don't disable lightly">
+  The runtime safety net is what catches accidental misuse during development. Only turn `guardrails{:toml}` off in production after the program has been thoroughly tested.
+</Callout>
+
 ## `account-resize{:toml}` (default)
 
-The `account-resize{:toml}` feature enables `realloc_account{:rs}` along with the pinocchio entrypoint hook that writes `data_len{:rs}` into `RuntimeAccount.padding{:rs}` for every non-duplicate account, which is what allows `AccountView::resize(){:rs}` to enforce the `MAX_PERMITTED_DATA_INCREASE{:rs}` cap.
+The `account-resize{:toml}` feature enables `realloc_account{:rs}` and adds a pinocchio entrypoint hook. The hook writes `data_len{:rs}` into `RuntimeAccount.padding{:rs}` for every non-duplicate account, which is what lets `AccountView::resize(){:rs}` enforce the `MAX_PERMITTED_DATA_INCREASE{:rs}` cap.
 
 Disabling the feature saves roughly 300 bytes of binary and 2 CU per account, but only when the program never calls `realloc_account{:rs}` in the first place.
 
@@ -46,23 +54,43 @@ Disabling the feature saves roughly 300 bytes of binary and 2 CU per account, bu
 
 ## `const-rent{:toml}` (off)
 
-The `const-rent{:toml}` feature folds `rent_exempt_lamports{:rs}` to a compile-time constant by combining pinocchio's `DEFAULT_LAMPORTS_PER_BYTE{:rs}` and `ACCOUNT_STORAGE_OVERHEAD{:rs}`, which lets `create_account{:rs}` skip the `Rent::get(){:rs}` sysvar call entirely.
+The `const-rent{:toml}` feature folds `rent_exempt_lamports{:rs}` to a compile-time constant by combining pinocchio's `DEFAULT_LAMPORTS_PER_BYTE{:rs}` and `ACCOUNT_STORAGE_OVERHEAD{:rs}`. With the constant in place, `create_account{:rs}` skips the `Rent::get(){:rs}` sysvar call entirely. The savings come out to roughly 90 CU per `create_account{:rs}` CPI.
 
-The savings come out to roughly 90 CU per `create_account{:rs}` CPI. The trade-off is that if Solana changes the rent formula in the future (for example, through a SIMD like SIMD-0194), programs built with `const-rent{:toml}` will compute stale values until they are rebuilt. The feature is off by default precisely so programs pick up runtime formula changes transparently.
+<Callout variant="warning" title="Rent-formula drift">
+  If Solana changes the rent formula in the future (for example, through a SIMD like SIMD-0194), programs built with `const-rent{:toml}` will compute stale values until they are rebuilt. The feature is off by default so programs pick up runtime formula changes transparently.
+</Callout>
 
-Reach for `const-rent{:toml}` when the 90 CU per `create_account{:rs}` matters more than rent-formula drift safety, and when the program is built and re-deployed often enough that refreshing the constant is part of the normal release cycle.
+<Callout variant="tip" title="When to enable">
+  Reach for `const-rent{:toml}` when 90 CU per `create_account{:rs}` matters more than rent-formula drift safety, and when the program is rebuilt and redeployed often enough that refreshing the constant is part of the normal release cycle.
+</Callout>
 
 ## `compat{:toml}` (off)
 
-The `compat{:toml}` feature exposes a small set of v1-shaped helpers for programs in the middle of porting. The most useful one is `debug!(msg){:rs}`, a logging macro shaped like `msg!{:rs}` that accepts any Rust format string (including `{:?}{:rs}`, `{:x}{:rs}`, and dynamic width specifiers) by routing through `alloc::format!{:rs}`. The feature also re-exports the v1 `error!{:rs}`, `err!{:rs}`, and `pubkey!{:rs}` macros, the `Pubkey{:rs}` type alias, and the `AccountViewCompat{:rs}` extension trait so existing call sites compile without rewrites.
+The `compat{:toml}` feature exposes a small set of v1-shaped helpers for programs in the middle of porting. The most useful is `debug!(msg){:rs}`, a logging macro shaped like `msg!{:rs}` that accepts any Rust format string by routing through `alloc::format!{:rs}`. That covers `{:?}{:rs}`, `{:x}{:rs}`, and dynamic width specifiers, none of which native `msg!{:rs}` supports.
+
+The remaining helpers re-expose v1 names so existing call sites compile without rewrites:
 
-The trade-off is cost. `debug!{:rs}` is meaningfully more expensive than the native `msg!{:rs}` because of the heap allocation and fmt-trait dispatch, so the feature is off by default to keep production binaries from accidentally shipping the heavier path.
+| Helper | Form |
+| --- | --- |
+| `error!{:rs}`, `err!{:rs}`, `pubkey!{:rs}` | Macros |
+| `Pubkey{:rs}` | Type alias for `Address{:rs}` |
+| `AccountViewCompat{:rs}` | Extension trait on pinocchio's `AccountView{:rs}` |
+
+<Callout variant="warning" title="`debug!{:rs}` cost">
+  `debug!{:rs}` is meaningfully more expensive than the native `msg!{:rs}` because of the heap allocation and fmt-trait dispatch. The feature is off by default to keep production binaries from accidentally shipping the heavier path.
+</Callout>
 
 ## `event-cpi{:toml}` (off)
 
-The `event-cpi{:toml}` feature wires the self-CPI event emit pattern through Anchor's derives. When enabled it adds the `#[event_cpi]{:rs}` accounts attribute and the `emit_cpi!{:rs}` macro, and the `#[program]{:rs}` dispatcher reserves an 8-byte tag at the top of instruction data so emitted events can be recovered from instruction history by indexers that cannot read transaction logs.
+The `event-cpi{:toml}` feature wires the self-CPI event emit pattern through Anchor's derives. When enabled, it adds the `#[event_cpi]{:rs}` accounts attribute and the `emit_cpi!{:rs}` macro.
+
+The `#[program]{:rs}` dispatcher then reserves an 8-byte tag at the top of instruction data. Indexers that cannot read transaction logs can recover emitted events from instruction history through that tag.
 
-The feature is off by default so the dispatcher does not pay the tag check on programs that do not use event CPIs. See [Events](/docs/v2/programs/events/) for the call shape.
+<Callout variant="note" title="Why off by default">
+  The dispatcher would pay the 8-byte tag check on every instruction. Programs that do not use event CPIs avoid that cost by keeping `event-cpi{:toml}` off.
+</Callout>
+
+See [Events](/docs/v2/programs/events/) for the call shape.
 
 ## `testing{:toml}` (off)
 
@@ -72,7 +100,9 @@ The `testing{:toml}` feature exposes the `anchor_lang_v2::testing{:rs}` module,
 $ <blue>cargo</blue> test <dim>-p</dim> anchor-lang-v2 <dim>--features</dim> testing
 ```
 
-The feature is off by default so production BPF binaries never ship the test scaffold.
+<Callout variant="note" title="Why off by default">
+  Production BPF binaries should never ship the test scaffold, so `testing{:toml}` stays opt-in.
+</Callout>
 
 ## Recipe: minimal binary, prod profile