chore: merge feedback into main

.gitleaksignore

@@ -0,0 +1,2 @@
+# A captured RPC fetch response used as a test fixture, not a secret
+scripts/harness/lib/ttl.test.ts:generic-api-key:22

AGENTS.md

@@ -20,18 +20,23 @@ result. Three states per side, none skipped: **pending, priced, claimed**.
 
 What the contracts enforce:
 
-1. **Entry is gated** by a post-KYC allowlist, checked on the receiver of a
-   subscription (enforced on share claim in contracts today; request-time
-   check is targeted for a future milestone) and on every share transfer.
+1. **Only allowlisted addresses enter.** The post-KYC allowlist is checked
+   when a subscription is requested, again when its shares are minted, and on
+   every share transfer.
 2. **A covered claim always pays.** Once priced and covered, a cash claim cannot
    be blocked by a pause, a stale valuation, or the investor losing their
-   allowlist place. Priced claims are never re-priced and never identity-gated;
-   a delisted, non-frozen investor leaves through the exit-only cash path.
-3. **Cancellation is atomic and single-step**, open only until the attestation
-   that prices the request is accepted. There is no instant exit.
-
-Five authorities, each a native Stellar multisig: governance, compliance,
-attestation, treasury, guardian. Testnet only. Not audited.
+   allowlist place. Priced claims are never re-priced, and a cash payout never
+   needs the identity check; a delisted, non-frozen investor leaves through
+   the exit-only cash path, including a deposit that was priced before the
+   delisting. A compliance freeze holds the claim until it is lifted.
+3. **Cancellation is atomic and single-step**, open only while the vault cannot
+   price the request: the attestation that prices it closes cancellation, and
+   cancellation reopens if that report expires, the NAV is paused or the vault
+   is paused. There is no instant exit.
+
+Five authorities, each meant to be a native Stellar multisig: governance,
+compliance, attestation, treasury, guardian. The deploy script gives each one
+key for now. Testnet only. Not audited.
 
 ## Reference base
 
@@ -48,7 +53,9 @@ does not carry over. Read it for Soroban and OZ mechanics only.
 - **Tests:** `cargo test` from the repo root runs every workspace member against
   the in-memory `Env`. There is no unit-test runner for `app/` or `app-lib/`;
   `e2e/` runs Playwright separately. CI runs `cargo test --locked` on every pull
-  request.
+  request except one that changes only Markdown files outside `docs/evidence/`:
+  that one skips the Rust and local-network jobs. The secret scan runs on
+  every pull request.
 - **Toolchain:** `nix develop` provides it, or rustup honours
   `rust-toolchain.toml`.
 
@@ -80,7 +87,13 @@ apply as the corresponding code lands here.
   `scripts/generate-clients.mjs`, which reads the contract ids and RPC URL of
   `ADDRESSES_ENV` (default `staging`) from `environments.toml` and writes
   `app-lib/clients/<contract>/` from each contract's on-chain spec, with Node
-  alone. Those generated types are the only contract types; `app-lib/contracts.ts`
+  alone. `development` declares no ids: there the script resolves each
+  `[development.contracts.<name>]` block plus an alias named `asset` through
+  `stellar contract alias show`, so CI builds the app against the contracts
+  the branch just deployed. The scaffold registers the block aliases when it
+  deploys; the asset is a Stellar Asset Contract a developer registers once with
+  `stellar contract asset deploy --asset native --alias asset --source me`
+  against the local network. Those generated types are the only contract types; `app-lib/contracts.ts`
   re-exports them and builds each runtime client with `new Client(...)` from its
   generated `src/index`, whose embedded spec means no page fetches a contract's
   instance or Wasm. Vite dedupes `@stellar/stellar-sdk` so a client's nested copy
@@ -89,10 +102,13 @@ apply as the corresponding code lands here.
   A fresh clone builds `app` with no cargo, no stellar CLI and no local network,
   but needs RPC access to the selected network at build time. A local scaffold
   build writes the same directory from the WASM.
-- When a tool must drive `cargo` directly rather than the CLI, set
-  `SOROBAN_SDK_BUILD_SYSTEM_SUPPORTS_SPEC_SHAKING_V2=1`. The build script fails
-  without it and its error names neither the variable nor this way out, so
-  coverage runs and size checks look impossible until you read the SDK source.
+- When `cargo` itself builds a contract for the Wasm target, rather than
+  `stellar contract build` (a size check with
+  `cargo build --release --target wasm32v1-none`, for example), set
+  `SOROBAN_SDK_BUILD_SYSTEM_SUPPORTS_SPEC_SHAKING_V2=1`. soroban-sdk's build
+  script stops that build without it, and its error names neither the variable
+  nor this way out. Host builds such as `cargo test` and `cargo clippy` never
+  need it.
 - Change a contract's `__constructor` and you must change its `constructor_args`
   in `environments.toml` in the same commit. Otherwise the scaffold build still
   exits 0 and CI fails minutes later on a client count, naming neither the
@@ -111,15 +127,54 @@ Not recorded here on purpose. The reference base kept them in this file and they
 drifted: its `AGENTS.md` and its generated client pointed at two different vault
 contracts. The addresses emitted by the deploy script are authoritative.
 
+## Code conventions
+
+- **Crate names.** Shared crates in `crates/` start with `strata-`
+  (`strata-timelock`, `strata-storage`, `strata-bindings`), so a path such as
+  `strata_timelock::DAY_DURATION` reads as the kit's own code.
+- **Addresses in entrypoints.** In an entrypoint the kit defines, `caller` is
+  the account that must sign the call, and `holder` is the account whose
+  position, request or balance the call is about. When one account is both, the
+  entrypoint takes `holder` and that account signs. The two ends of a share
+  transfer are `from` and `to`, and other addresses are named for what they
+  are (`custodian`, `vault`, the allowlisted `account`). OpenZeppelin trait
+  methods keep their own names (`operator`, `user_address`).
+- **Named errors.** Contract code fails with a named error variant, never with
+  `unwrap`, `expect` or a bare `panic!`. Tests may unwrap. Each contract
+  declares its error enum through `strata_bindings::error_enum!`, which fails
+  the build if a code leaves the contract's block (`docs/kit-spec.md`, section
+  7).
+- **No boolean switches.** A new entrypoint does one thing. Two behaviours get
+  two functions, like `freeze_partial_tokens` and `unfreeze_partial_tokens`,
+  not one function that takes a `bool`.
+- **Guards.** Each precondition is a `pub(crate) fn` in the contract's
+  `guards.rs`. Its name is the condition it checks (`positive_amount`,
+  `not_winding_down`), and it panics with a named error when the condition
+  fails. An entrypoint calls its guards first and then does its work, so its
+  preconditions are the first lines a reader sees.
+- **Doc comments.** Every public entrypoint has one, in OpenZeppelin's style: a
+  one-line summary, then `# Arguments` with units (asset base units, share base
+  units, WAD prices, seconds or ledgers), `# Errors`, `# Events` and
+  `# Authorization`. Every error variant's doc says when it happens. Keep them
+  short: they are stored in the Wasm as part of the contract spec, which keeps
+  1,024 bytes of each doc and drops the rest without a warning.
+  `every_contract_doc_fits_the_spec` (`crates/strata-bindings/tests/spec_docs.rs`)
+  fails when one is longer.
+- **Design notes.** Each contract's `lib.rs` opens with a `//! # Design`
+  section: five to ten bullets, each a choice and its trade-off, in plain words
+  and with no issue numbers or decision ids.
+- **Exact pins.** Every crates.io dependency, dev-dependencies included, is
+  pinned with `=` to the version in `Cargo.lock`.
+
 ## Conventions
 
 - Conventional Commits, imperative, subject ≤ 50 chars. **No AI attribution.**
 - Issue-first: every PR closes an issue (`Closes #N`). Branches are
   `feat/<issue>-<desc>`, `fix/...`, `chore/...`.
 - Issue bodies follow the templates in `.github/ISSUE_TEMPLATE/`, 200 words of
   prose hard cap. Titles are natural language with no prefix.
-- Exact dependency pins. Dependencies are never upgraded mid-milestone; each
-  migration is its own issue in the following one.
+- Dependencies are never upgraded mid-milestone; each migration is its own
+  issue in the following one.
 - Estimates live in the `Estimate` field of the
   [project board](https://github.com/orgs/BootNodeDev/projects/29), not in issue
   bodies.

Cargo.toml

@@ -1,7 +1,6 @@
 [workspace]
 resolver = "2"
 members = ["crates/*", "contracts/*"]
-exclude = ["fixtures/upgrade-target"]
 
 [workspace.package]
 edition = "2021"