update documentation

[holyfuchs]

Splits the documentation by the question each file answers: architecture.md (design and rationale), security.md (adversarial threat model, new), security-surface.md (dependency outages), risk-disclosures.md (costs when nothing goes wrong), and operations.md (owner/keeper runbook, new). architecture_old.md is deleted, and the duplicated sandwich and permissionless-rebalance sections are merged.

Corrects claims that no longer matched the code. redeem no longer flash-loans, so the documented ~50% cap on a single redemption does not exist. The vault does not inherit OpenZeppelin's ERC4626. "Health factor" is not a concept in this contract — the redeem gate is LTV against LTV_MAX. The availability matrix also had a false caveat about oracle reads, three wrong signatures, and two wrong access entries.

Documents what was missing entirely: emergency recovery is terminal — after the timelock the owner receives the whole position and redeem, redeemInKind and rebalance revert permanently — plus fee mechanics, and the zero-value defaults that leave a fresh vault inert (maxSlippageBps = 0 makes rebalance() a silent no-op rather than a revert).

Removes backtested swap-size figures, the "~2–3% of protocol TVL" pool sizing, and a borrow-rate history claim. These depend on the asset and the venue, and parameter selection belongs to whoever deploys and manages the vault.

Code

One behavioural fix: decimals() returned 18 while shares are scaled by collateralDecimals + 6, so a client formatting a WBTC vault balance was off by 10^4. Accounting was never affected — nothing internal reads decimals() — but integrators and front-ends were. Everything else is comments and natspec, including trimming tautological blocks from FeesLib, SwapLib and YieldTokenOracle.

Tests

Seven added. The notable one is rebalance surviving a collateral/loan-pool outage: that is the claim behind splitting harvest out of rebalance, and nothing asserted it. Also the five accrueFees availability cases, since it is the only _accrueFees consumer without logsVaultState, and the decimals scale.