ReineiraOS · grimnote · Jun 15, 2026 · Jun 15, 2026
@@ -34,6 +34,18 @@ pnpm --filter @reineira-os/escrow test       # Test escrow only
 pnpm --filter @reineira-os/recourse test    # Test recourse only
 ```
 
+## Documentation
+
+| Document                                               | Description                                                        |
+| ------------------------------------------------------ | ------------------------------------------------------------------ |
+| [Whitepaper](docs/ReineiraOS-Whitepaper.pdf)           | Protocol design and primitive definitions (cited as `§X` in code). |
+| [Litepaper](docs/ReineiraOS-Litepaper.pdf)             | Condensed overview.                                                |
+| [Implementation Status](docs/IMPLEMENTATION-STATUS.md) | What is shipped, partial, and planned vs. the whitepaper.          |
+
+The protocol is **testnet · pre-audit · upgradeable** and not yet
+feature-complete — see [Implementation Status](docs/IMPLEMENTATION-STATUS.md)
+before relying on any whitepaper section. Full docs: [docs.reineira.xyz](https://docs.reineira.xyz).
+
 ## License
 
 This repository is multi-licensed by layer — see [LICENSE](LICENSE) and [NOTICE](NOTICE):

@@ -0,0 +1,93 @@
+# Implementation Status
+
+> **Maturity: testnet · pre-audit · upgradeable.** The protocol is under active
+> development and is **not yet feature-complete**. This document is the
+> authoritative record of what is implemented, what is partial, and what is
+> still planned, mapped to the whitepaper. It exists so that the relationship
+> between the specification and the deployed code is explicit rather than
+> assumed. Where this document and the whitepaper disagree, **this document
+> describes the code; the whitepaper describes the design intent.**
+
+**Last reviewed:** 2026-06-15
+
+## How to read this
+
+| Status         | Meaning                                                                        |
+| -------------- | ------------------------------------------------------------------------------ |
+| ✅ Implemented | Contracts/services exist and carry test coverage. Pre-audit; not yet hardened. |
+| 🟡 Partial     | The interface and wiring exist, but the production logic is a stub or mock.    |
+| ⏳ Planned     | Specified in the whitepaper; not yet started in this repo.                     |
+
+"Pre-audit" applies to **everything** below: no contract in this repository has
+completed an external security audit, and all core contracts are UUPS-upgradeable
+on testnet. Treat every line as subject to change.
+
+## By package
+
+| Package                      | Status         | Notes                                                                                                              |
+| ---------------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `@reineira-os/shared`        | ✅ Implemented | Base contracts, interfaces, and mocks shared across packages.                                                      |
+| `@reineira-os/escrow`        | ✅ Implemented | Confidential FHE escrow + CCTP V2 cross-chain USDC. Core settlement paths covered by tests.                        |
+| `@reineira-os/recourse`      | 🟡 Partial     | Pools, factory, registry, coverage manager, and router ship; underwriter policy and LP rewards do not (see below). |
+| `@reineira-os/orchestration` | 🟡 Partial     | Operator registration, staking, tasks, fees, and slashing are in progress — not yet finished.                      |
+| `@reineira-os/operators`     | 🟡 Partial     | Off-chain operator infrastructure (NestJS) — in progress, not yet finished.                                        |
+| `@reineira-os/sdk`           | ✅ Implemented | TypeScript client for the protocol.                                                                                |
+
+## By whitepaper section
+
+| §     | Area                         | Status         | Notes                                                                          |
+| ----- | ---------------------------- | -------------- | ------------------------------------------------------------------------------ |
+| §5    | Reineira Settlement Standard | ✅ Implemented | Open RSS interfaces present.                                                   |
+| §6    | Escrow engine                | ✅ Implemented | Confidential escrow + cross-chain settlement.                                  |
+| §7.2  | Recourse pool roles          | ✅ Implemented | Pool Creator / Manager / LP roles enforced in plain and confidential pools.    |
+| §7.10 | Underwriter policy           | 🟡 Partial     | `IUnderwriterPolicy` is pluggable; only mocks ship. No production risk model.  |
+| §7.x  | LP reward accounting         | 🟡 Partial     | `pendingRewards()` / `claimRewards()` are stubs (see Known gaps).              |
+| §8    | Operator network             | 🟡 Partial     | On-chain staking/tasks/fees/slashing and off-chain services both in progress.  |
+| §9    | Cross-chain (L2/L3)          | 🟡 Partial     | CCTP V2 USDC paths ship; full L3 graduation path is roadmap.                   |
+| §10   | Security                     | 🟡 Partial     | ReentrancyGuard, access control, replay protection in place; **no audit yet.** |
+| §11   | Governance                   | ⏳ Planned     | Ownable/UUPS today; decentralized governance is future work.                   |
+| §12   | Tokenomics                   | ⏳ Planned     | No token. Described as design intent only.                                     |
+| §13   | Licensing                    | ✅ Implemented | Per-layer licensing live — see [LICENSE](../LICENSE) / [NOTICE](../NOTICE).    |
+
+## Known gaps
+
+These are the items most likely to surprise a reviewer reading the code against
+the whitepaper. They are disclosed deliberately.
+
+1. **Underwriter policy is pluggable but not yet filled in (§7.10).**
+   The `recourse` package ships the `IUnderwriterPolicy` interface and mocks
+   (`MockUnderwriterPolicy`, `MockConfidentialUnderwriterPolicy`) that return a
+   stored constant for `evaluateRisk()` / `judge()`. There is **no production
+   risk-scoring or dispute policy** in this repository yet. Pools accept any
+   `IUnderwriterPolicy`-conforming contract; supplying a real one is the work
+   that remains.
+
+2. **LP reward accounting is a stub (§7.x).**
+   `pendingRewards()` returns `0` (`_encryptedZero` in the confidential pool) and
+   `claimRewards()` validates ownership and emits `RewardsClaimed` **without
+   transferring any value**. Premium distribution to LPs is not yet implemented.
+   Manager premium withdrawal (`claimPremiums`) is implemented.
+
+3. **Capital model is a single flat pool.**
+   Pools hold one undifferentiated capital bucket. Tranching / waterfall
+   seniority described as design intent is not implemented.
+
+4. **Operator network is still in progress (§8).**
+   Both the on-chain `orchestration` package (registration, staking, tasks,
+   fees, slashing) and the off-chain `operators` services are under active
+   development and are not yet feature-complete.
+
+5. **No external audit.**
+   No contract here has been audited. All core contracts are upgradeable on
+   testnet. Do not treat any deployment as production-grade.
+
+## How this is published
+
+This file is the engineering-level record that travels with the code. The same
+readiness picture is intended to be reflected, in product language, in:
+
+- the **whitepaper** (an Implementation Status / roadmap note), and
+- **[docs.reineira.xyz](https://docs.reineira.xyz)** (a public status page).
+
+If you find a discrepancy between the code and any of these surfaces, that is a
+bug in the documentation — please open an issue.
@@ -0,0 +1,25 @@
+# Documentation
+
+Canonical specification and reference documents for the ReineiraOS protocol.
+
+## Papers
+
+| Document   | In this repo                                             | Canonical (hosted)                             |
+| ---------- | -------------------------------------------------------- | ---------------------------------------------- |
+| Whitepaper | [ReineiraOS-Whitepaper.pdf](./ReineiraOS-Whitepaper.pdf) | https://reineira.xyz/ReineiraOS-Whitepaper.pdf |
+| Litepaper  | [ReineiraOS-Litepaper.pdf](./ReineiraOS-Litepaper.pdf)   | https://reineira.xyz/ReineiraOS-Litepaper.pdf  |
+
+The whitepaper is the document referenced throughout the contract NatSpec (e.g.
+`whitepaper §7.2`, `§7.10`). The in-repo copy is the snapshot that the code in
+this commit was written against; the hosted copy at
+[reineira.xyz](https://reineira.xyz) is the latest published version.
+
+## Status
+
+- [IMPLEMENTATION-STATUS.md](./IMPLEMENTATION-STATUS.md) — what is shipped,
+  what is partial, and what is still on the roadmap, mapped to whitepaper
+  sections. **Read this before assuming any whitepaper section is fully
+  implemented.**
+
+Full developer documentation is published at
+[docs.reineira.xyz](https://docs.reineira.xyz).