ayshadogo · Oct 19, 2026 · Oct 19, 2026
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,7 +2,7 @@
 
 ## Dev Environment Setup
 
-1. Install Rust: https://rustup.rs
+1. Install Rust: [rustup, the Rust toolchain installer](https://rustup.rs)
 2. Add Wasm target:
    ```bash
    rustup target add wasm32-unknown-unknown
@@ -156,5 +156,5 @@ the output.
 
 ## Resources
 
-- [Soroban Documentation](https://developers.stellar.org/docs/smart-contracts)
-- [Soroban SDK](https://docs.rs/soroban-sdk)
+- [Stellar smart contracts documentation (Soroban)](https://developers.stellar.org/docs/smart-contracts)
+- [soroban-sdk Rust crate API reference (docs.rs)](https://docs.rs/soroban-sdk)
diff --git a/contracts/README.md b/contracts/README.md
@@ -10,7 +10,7 @@
 
 ## Versioning
 
-All crates follow semantic versioning. Query a live contract with `get_version` / `get_version_metadata`. See [../docs/VERSIONING.md](../docs/VERSIONING.md).
+All crates follow semantic versioning. Query a live contract with `get_version` / `get_version_metadata`. See [the contract versioning guide (VERSIONING.md)](../docs/VERSIONING.md).
 
 ## Architecture
 
@@ -46,7 +46,7 @@ cargo test
 
 ## Deploy
 
-See [../scripts/deploy_testnet.sh](../scripts/deploy_testnet.sh)
+See [the testnet deployment script (deploy_testnet.sh)](../scripts/deploy_testnet.sh)
 
 ## Contract Addresses (Testnet)
 

diff --git a/docs/ADRs/README.md b/docs/ADRs/README.md
@@ -30,14 +30,14 @@ graph LR
 
 | ADR ID | Title | Status | Date | Component |
 |--------|-------|--------|------|-----------|
-| [ADR-0000](0000-template.md) | Standard Architecture Decision Record Template | Accepted | 2026-01-15 | All |
-| [ADR-0001](0001-soroban-smart-contract-platform.md) | Adoption of Stellar Soroban Rust Smart Contract Platform | Accepted | 2026-01-20 | Core / Platform |
-| [ADR-0002](0002-escrow-architecture-and-state-machine.md) | Escrow Contract State Machine and CEI Pattern | Accepted | 2026-02-01 | Escrow |
-| [ADR-0003](0003-commission-agreement-milestone-flow.md) | Multi-Milestone Commission Agreements and Concurrency Locks | Accepted | 2026-02-15 | Commission Agreement |
-| [ADR-0004](0004-dispute-resolution-and-arbitration.md) | Autonomous Dispute Arbiter & Cross-Contract Resolution | Accepted | 2026-03-01 | Dispute Arbiter |
-| [ADR-0005](0005-platform-fee-and-revenue-distribution.md) | Dynamic Platform Fee Governance and Multi-Party Splits | Accepted | 2026-03-10 | Platform Config / Revenue |
-| [ADR-0006](0006-event-driven-architecture.md) | Structured Event Emission for Off-Chain Indexing | Accepted | 2026-03-25 | All Contracts |
-| [ADR-0007](0007-storage-data-model-and-ttl-management.md) | Soroban Storage Tiering and TTL Extension Strategy | Accepted | 2026-04-05 | Storage / Lifecycle |
+| [ADR-0000 (`0000-template.md`)](0000-template.md) | Standard Architecture Decision Record Template | Accepted | 2026-01-15 | All |
+| [ADR-0001 (`0001-soroban-smart-contract-platform.md`)](0001-soroban-smart-contract-platform.md) | Adoption of Stellar Soroban Rust Smart Contract Platform | Accepted | 2026-01-20 | Core / Platform |
+| [ADR-0002 (`0002-escrow-architecture-and-state-machine.md`)](0002-escrow-architecture-and-state-machine.md) | Escrow Contract State Machine and CEI Pattern | Accepted | 2026-02-01 | Escrow |
+| [ADR-0003 (`0003-commission-agreement-milestone-flow.md`)](0003-commission-agreement-milestone-flow.md) | Multi-Milestone Commission Agreements and Concurrency Locks | Accepted | 2026-02-15 | Commission Agreement |
+| [ADR-0004 (`0004-dispute-resolution-and-arbitration.md`)](0004-dispute-resolution-and-arbitration.md) | Autonomous Dispute Arbiter & Cross-Contract Resolution | Accepted | 2026-03-01 | Dispute Arbiter |
+| [ADR-0005 (`0005-platform-fee-and-revenue-distribution.md`)](0005-platform-fee-and-revenue-distribution.md) | Dynamic Platform Fee Governance and Multi-Party Splits | Accepted | 2026-03-10 | Platform Config / Revenue |
+| [ADR-0006 (`0006-event-driven-architecture.md`)](0006-event-driven-architecture.md) | Structured Event Emission for Off-Chain Indexing | Accepted | 2026-03-25 | All Contracts |
+| [ADR-0007 (`0007-storage-data-model-and-ttl-management.md`)](0007-storage-data-model-and-ttl-management.md) | Soroban Storage Tiering and TTL Extension Strategy | Accepted | 2026-04-05 | Storage / Lifecycle |
 
 ---
 

diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md
@@ -2,7 +2,7 @@
 
 Reference for the public Soroban entry points in the workspace contracts, plus
 the shared helper modules. Error codes and canonical suggestions for every
-value are in [docs/error_codes.md](./error_codes.md).
+value are in [the error codes reference (error_codes.md)](./error_codes.md).
 
 Conventions:
 
@@ -43,7 +43,7 @@ Conventions:
 | `get_idempotency_record(admin, caller, key)` | `Option<IdempotencyRecord>` | |
 | `extend_idempotency_ttl(admin, caller, key, ledgers)` | `Result<(), EscrowError>` | |
 
-Semantics in [docs/IDEMPOTENCY.md](./IDEMPOTENCY.md).
+Semantics in [the idempotency specification (IDEMPOTENCY.md)](./IDEMPOTENCY.md).
 
 ### Timeouts (closes #665)
 
@@ -60,7 +60,7 @@ Semantics in [docs/IDEMPOTENCY.md](./IDEMPOTENCY.md).
 
 `TimeoutPolicy { timeout_ledgers, max_attempts }`, `CallAttempt { started_ledger,
 deadline_ledger, attempts, retry_after_ledger }`. Full semantics in
-[docs/TIMEOUT_POLICY.md](./TIMEOUT_POLICY.md).
+[the timeout policy guide (TIMEOUT_POLICY.md)](./TIMEOUT_POLICY.md).
 
 ### Admin / lifecycle / ops
 
@@ -70,8 +70,8 @@ deadline_ledger, attempts, retry_after_ledger }`. Full semantics in
 `route_to_canary`, `set_rollback_trigger`, `trigger_rollback`,
 `should_rollback`, `get_rollout_state`; `health_check`,
 `get_health_metrics`, `get_sla_targets`, `detect_anomaly`, `report_ok`,
-`report_error`. See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AND_EMERGENCY.md),
-[docs/UPGRADE.md](./UPGRADE.md), [docs/SLA.md](./SLA.md).
+`report_error`. See [the pause and emergency runbook (PAUSE_AND_EMERGENCY.md)](./PAUSE_AND_EMERGENCY.md),
+[the upgrade procedures (UPGRADE.md)](./UPGRADE.md), [the SLA definitions (SLA.md)](./SLA.md).
 
 ## contracts/platform_config
 
@@ -93,7 +93,7 @@ deadline_ledger, attempts, retry_after_ledger }`. Full semantics in
 | `is_promotion_active()` | `bool` |
 
 `Error` codes: `InvalidTier=6`, `InvalidPromotion=7`, `InvalidReferralBps=8`,
-`PromotionNotActive=9`. Fee math details in [docs/FEES.md](./FEES.md).
+`PromotionNotActive=9`. Fee math details in [the fee calculation documentation (FEES.md)](./FEES.md).
 
 ### Token metadata / admin
 
@@ -149,6 +149,6 @@ Run the crate doc-tests for interactive copies: `cargo test --doc -p shared`.
 ## Error codes
 
 Numeric code → cause → suggestion handle mapping is defined once in
-`contracts/*/src/errors.rs` and documented in [docs/error_codes.md](./error_codes.md).
+`contracts/*/src/errors.rs` and documented in [the error codes reference (error_codes.md)](./error_codes.md).
 Every contract exposes `get_suggestion(code)` and a unit test asserting each
 code's Display + suggestion.
diff --git a/docs/COMMUNICATION_TEMPLATES.md b/docs/COMMUNICATION_TEMPLATES.md
@@ -4,7 +4,7 @@
 
 Do **not** include secret keys, unreleased WASM hashes that embed secrets, or individual user balances. Post to the status page, Discord `#status`, and email `ops@` / `users@` as applicable.
 
-Run these inside a [maintenance window](./MAINTENANCE_WINDOWS.md).
+Run these inside a [maintenance window (MAINTENANCE_WINDOWS.md)](./MAINTENANCE_WINDOWS.md).
 
 ## Scheduled maintenance (T–72h / T–48h / T–24h)
 

diff --git a/docs/COMPREHENSIVE_API_DOCS.md b/docs/COMPREHENSIVE_API_DOCS.md
@@ -59,8 +59,8 @@ contracts/
 └── mentorship/           # Mentorship program contract  (NEW — #613)
 ```
 
-See [docs/architecture.md](./architecture.md) and the individual ADRs under
-[docs/ADRs/](./ADRs/) for design rationale.
+See [the architecture guide (architecture.md)](./architecture.md) and the individual ADRs under
+[the Architecture Decision Records index (docs/ADRs/)](./ADRs/) for design rationale.
 
 ---
 
@@ -91,7 +91,7 @@ cargo test --workspace
 ./scripts/deploy_testnet.sh
 ```
 
-See [docs/DEPLOY.md](./DEPLOY.md) for full deployment instructions.
+See [the deployment runbook (DEPLOY.md)](./DEPLOY.md) for full deployment instructions.
 
 ---
 
@@ -520,7 +520,7 @@ pub struct FeeBreakdown {
 | 10 | `AlreadyReviewed` | reputation | Reviewer already submitted | One review per commission |
 | 11 | `InvalidRating` | reputation | Rating outside 1–5 | Pass a value between 1 and 5 |
 
-Full error code documentation: [docs/error_codes.md](./error_codes.md).
+Full error code documentation: [the error codes reference (error_codes.md)](./error_codes.md).
 
 ---
 
@@ -629,7 +629,7 @@ The `rating` parameter must be an integer between 1 and 5 inclusive.
 ### Contract paused
 
 If a contract is in the paused state, all mutating transactions will fail.
-Only the admin may call `unpause`.  See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AND_EMERGENCY.md).
+Only the admin may call `unpause`.  See [the pause and emergency runbook (PAUSE_AND_EMERGENCY.md)](./PAUSE_AND_EMERGENCY.md).
 
 ---
 
@@ -641,4 +641,4 @@ Only the admin may call `unpause`.  See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AN
 - Usage and certification events are immutable once emitted; build audit
   pipelines on top of event streams.
 - For the full threat model and audit checklist see
-  [docs/SECURITY_REVIEW_CHECKLIST.md](./SECURITY_REVIEW_CHECKLIST.md).
+  [the security review checklist (SECURITY_REVIEW_CHECKLIST.md)](./SECURITY_REVIEW_CHECKLIST.md).
diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md
@@ -819,7 +819,7 @@ Topics are listed as `[contract address, …]`, since the contract address is al
 
 ### dispute_arbiter
 
-> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)"
+> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004 (0004-dispute-resolution-and-arbitration.md)](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)"
 
 Source: `contracts/dispute_arbiter/`
 
@@ -1487,7 +1487,7 @@ Each shape is emitted from exactly one site; there are no repeats. This crate pu
 
 ### platform_config
 
-> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4)
+> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005 (0005-platform-fee-and-revenue-distribution.md)](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4)
 
 Source: `contracts/platform_config/`
 

diff --git a/docs/DEVELOPER_ENVIRONMENT.md b/docs/DEVELOPER_ENVIRONMENT.md
@@ -9,12 +9,12 @@ Before you begin, ensure you have the following software installed on your syste
 ### Required Software
 | Software | Version | Description | Installation Link |
 |----------|---------|-------------|-------------------|
-| Rust | 1.75+ | Primary language for smart contract development | https://www.rust-lang.org/tools/install |
-| Soroban CLI | Latest | Stellar's smart contract development toolkit | https://developers.stellar.org/docs/build/sdks-and-tools/soroban-cli |
-| Node.js | 18.x+ | For TypeScript SDK and frontend development | https://nodejs.org/ |
-| Git | 2.40+ | Version control | https://git-scm.com/downloads |
-| Docker | 24.x+ | For local testing and containerized services | https://www.docker.com/get-started/ |
-| VS Code | Latest | Recommended IDE with Rust/Soroban extensions | https://code.visualstudio.com/ |
+| Rust | 1.75+ | Primary language for smart contract development | [Rust installation guide](https://www.rust-lang.org/tools/install) |
+| Soroban CLI | Latest | Stellar's smart contract development toolkit | [Soroban CLI setup guide](https://developers.stellar.org/docs/build/sdks-and-tools/soroban-cli) |
+| Node.js | 18.x+ | For TypeScript SDK and frontend development | [Node.js download page](https://nodejs.org/) |
+| Git | 2.40+ | Version control | [Git download page](https://git-scm.com/downloads) |
+| Docker | 24.x+ | For local testing and containerized services | [Docker get started guide](https://www.docker.com/get-started/) |
+| VS Code | Latest | Recommended IDE with Rust/Soroban extensions | [Visual Studio Code download](https://code.visualstudio.com/) |
 
 ### System Requirements
 - **Operating System**: Windows 10+, macOS 13+, or Linux (Ubuntu 20.04+)
@@ -255,6 +255,6 @@ If you encounter issues not listed here:
 ## Additional Resources
 
 - [Stellar Developer Documentation](https://developers.stellar.org/)
-- [Soroban Documentation](https://developers.stellar.org/docs/build/smart-contracts/overview)
-- [StellarAid Architecture Guide](architecture.md)
-- [Deployment Configuration Guide](DEPLOYMENT_CONFIGURATION.md)
+- [Soroban smart contracts overview](https://developers.stellar.org/docs/build/smart-contracts/overview)
+- [StellarAid Architecture Guide (architecture.md)](architecture.md)
+- [Deployment Configuration Guide (DEPLOYMENT_CONFIGURATION.md)](DEPLOYMENT_CONFIGURATION.md)
diff --git a/docs/OPERATIONAL_RUNBOOK.md b/docs/OPERATIONAL_RUNBOOK.md
@@ -96,7 +96,7 @@ Key metrics to monitor:
 ### Maintenance windows
 
 Planned pauses and upgrades run inside the windows defined in
-[docs/MAINTENANCE_WINDOWS.md](../docs/MAINTENANCE_WINDOWS.md) (Tuesday /
+[the maintenance windows guide (MAINTENANCE_WINDOWS.md)](../docs/MAINTENANCE_WINDOWS.md) (Tuesday /
 Thursday 02:00–04:00 UTC, plus emergency). Follow that document for pause
 order, state backup, upgrade timeline, and communication templates.
 

diff --git a/docs/QUERY_OPTIMIZATION.md b/docs/QUERY_OPTIMIZATION.md
@@ -2,7 +2,7 @@
 
 > Closes **#650** — implement query optimization.
 >
-> Related: [STORAGE.md](./STORAGE.md), [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md), [RETENTION_AND_PRUNING.md](./RETENTION_AND_PRUNING.md).
+> Related: [STORAGE.md](./STORAGE.md), [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md), [RETENTION_AND_PRUNING.md](./RETENTION_AND_PRUNING.md).
 
 ---
 
@@ -146,7 +146,7 @@ benchmark.
   `temporary()` one. It is cleared on both the success and error paths, and a
   panic reverts the whole transaction, so it is correct — but `temporary()`
   storage would be the cheaper primitive for a mutex (see
-  [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md), which
+  [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md), which
   classes mutex locks as temporary). Worth revisiting; not changed here.
 - `extend_escrow_ttl` is called on write and on dispute, with the dispute TTL
   configurable. The retention behaviour is deliberate and is documented in
@@ -183,7 +183,7 @@ benchmark.
   contract entry point and cannot be added cheaply: it would need a second
   storage key per record, written and pruned in lockstep, doubling the write
   cost of the hottest money-moving path in the workspace. **If such a query is
-  needed, build it off-chain from events** ([ADR-0006](./ADRs/0006-event-driven-architecture.md)),
+  needed, build it off-chain from events** ([ADR-0006 (0006-event-driven-architecture.md)](./ADRs/0006-event-driven-architecture.md)),
   which is what the correlation events in
   [CONTRACTS.md](./CONTRACTS.md) are for.
 - Nothing in the workspace scans a persistent keyspace on-chain. That is a

diff --git a/docs/RETENTION_AND_PRUNING.md b/docs/RETENTION_AND_PRUNING.md
@@ -3,7 +3,7 @@
 > Closes **#651** — add contract state pruning strategy.
 >
 > Related: [STORAGE.md](./STORAGE.md),
-> [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md),
+> [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md),
 > [QUERY_OPTIMIZATION.md](./QUERY_OPTIMIZATION.md),
 > [OPERATIONAL_RUNBOOK.md](./OPERATIONAL_RUNBOOK.md),
 > [EMERGENCY_PROCEDURES.md](./EMERGENCY_PROCEDURES.md).

diff --git a/docs/SECURITY_REVIEW_CHECKLIST.md b/docs/SECURITY_REVIEW_CHECKLIST.md
@@ -162,8 +162,8 @@ The following items must be complete before engaging an external auditor:
 - [x] This checklist reviewed and signed off by the team lead
 - [x] Dependency tree audited with `cargo audit` — no critical CVEs
 - [x] Deployment scripts reviewed for secret exposure
-- [x] Architecture diagrams up to date ([docs/architecture.md](./architecture.md))
-- [x] ADRs written for non-obvious design decisions ([docs/ADRs/](./ADRs/))
+- [x] Architecture diagrams up to date ([the architecture guide (architecture.md)](./architecture.md))
+- [x] ADRs written for non-obvious design decisions ([the Architecture Decision Records index (docs/ADRs/)](./ADRs/))
 - [ ] Formal verification scope agreed with auditor (in progress)
 - [ ] Bug-bounty programme scope defined (planned for Phase 2)
 

diff --git a/docs/STORAGE.md b/docs/STORAGE.md
@@ -11,7 +11,7 @@ Per-contract storage layout and TTL policy for every crate in the workspace.
 >   storage-layout observations behind it.
 > - **Interfaces, events and errors:** [CONTRACTS.md](./CONTRACTS.md).
 > - **Dependency supply chain:** §9 of this document.
-> - **Design rationale:** [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md).
+> - **Design rationale:** [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md).
 
 ## How to read this
 
@@ -375,7 +375,7 @@ No other ledger-denominated constants exist. `voting_period` and `timelock_ledge
 
 ### dispute_arbiter
 
-> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)"
+> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004 (0004-dispute-resolution-and-arbitration.md)](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)"
 
 Source: `contracts/dispute_arbiter/`
 
@@ -666,7 +666,7 @@ The crate declares no ledger-denominated constant at all. The `3000` (30% max ro
 
 ### platform_config
 
-> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4)
+> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005 (0005-platform-fee-and-revenue-distribution.md)](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4)
 
 Source: `contracts/platform_config/`
 

diff --git a/docs/TOKEN_SETUP.md b/docs/TOKEN_SETUP.md
@@ -21,4 +21,4 @@ cargo run --bin worker -- setup-token
 
 - Asset Code: `AID`
 - Network: Testnet (default), Mainnet
-- Horizon: https://horizon-testnet.stellar.org
+- Horizon: [Stellar Testnet Horizon API (`https://horizon-testnet.stellar.org`)](https://horizon-testnet.stellar.org)
diff --git a/docs/UPGRADE_AND_ROLLBACK.md b/docs/UPGRADE_AND_ROLLBACK.md
@@ -4,7 +4,7 @@ This document describes the safe process for upgrading Soroban contracts and rol
 
 > **Closes #595** — Backward compatibility strategy for upgrades with state migration functions and upgrade safety checks.
 
-Version numbers, compatibility rules, and `get_version` querying are defined in [VERSIONING.md](./VERSIONING.md). Run upgrades inside a [maintenance window](./MAINTENANCE_WINDOWS.md).
+Version numbers, compatibility rules, and `get_version` querying are defined in [VERSIONING.md](./VERSIONING.md). Run upgrades inside a [maintenance window (MAINTENANCE_WINDOWS.md)](./MAINTENANCE_WINDOWS.md).
 
 ## Upgrade Safety Architecture
 

diff --git a/docs/error_codes.md b/docs/error_codes.md
@@ -108,8 +108,8 @@ enum yet or not:
 
 Both are raised **before** the state change they protect, so a rejected call
 leaves nothing behind. See
-[the balance module](../contracts/campaign/src/balance.rs) and
-[the sanitization module](../contracts/campaign/src/sanitize.rs).
+[the balance module (`balance.rs`)](../contracts/campaign/src/balance.rs) and
+[the sanitization module (`sanitize.rs`)](../contracts/campaign/src/sanitize.rs).
 
 ## New codes