docs(canton): align with new canton-specs and canton-contracts repo structure

content/canton/get-started.mdx

@@ -13,7 +13,7 @@ This guide covers the prerequisites and the basic project wiring for building on
 
 ## Prerequisites
 
-- **JDK 21**: the Daml toolchain runs on Java. Install a recent OpenJDK 21 build and make sure `JAVA_HOME` points at it.
+- **JDK 21+**: the Daml toolchain runs on Java. Install any JDK 21 or newer - e.g. OpenJDK or Eclipse Adoptium both work - and make sure `JAVA_HOME` points at it.
 - **DPM (Daml Package Manager)**: Digital Asset's package manager and SDK installer. Install it, then use it to provision the Daml SDK / Canton baseline:
 
 ```bash
@@ -27,15 +27,16 @@ dpm install 3.4.11   # or the baseline pinned in your project's daml.yaml
 
 OpenZeppelin's Canton library is distributed as Daml packages: each primitive is its own DAR, so you add only the ones you need.
 
-**1. Get the DARs.** Clone [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts) and build the library packages:
+**1. Get the DARs.** The source of truth for production DARs is the [`dars/released/`](https://github.com/OpenZeppelin/canton-contracts/tree/main/dars) directory in `OpenZeppelin/canton-contracts`: it holds immutable DARs copied from tagged GitHub Releases, indexed in `dars/manifest.yaml` with the package IDs and SHA-256 digests operators need for verification and vetting. No production releases have been published yet, so for now build the library packages from source:
 
 ```bash
 git clone https://github.com/OpenZeppelin/canton-contracts.git
 cd canton-contracts
+dpm install
 dpm build --all
 ```
 
-Each package's DAR lands in its own `.daml/dist/` directory (for example `pausable/.daml/dist/oz-pausable-0.1.0.dar`).
+Library packages live under `packages/`, grouped by category (`packages/access/` for authorization and ownership, `packages/security/` for operational security). Each package's DAR lands in its own `.daml/dist/` directory (for example `packages/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar`).
 
 **2. Declare them as data-dependencies.** In your project's `daml.yaml`, reference the built DARs under `data-dependencies` (not `dependencies`, which is for the SDK's own libraries):
 
@@ -48,9 +49,9 @@ dependencies:
   - daml-prim
   - daml-stdlib
 data-dependencies:
-  - ../canton-contracts/access-control/.daml/dist/oz-access-control-0.1.0.dar
-  - ../canton-contracts/ownable/.daml/dist/oz-ownable-0.1.0.dar
-  - ../canton-contracts/pausable/.daml/dist/oz-pausable-0.1.0.dar
+  - ../canton-contracts/packages/access/access-control-v1/.daml/dist/openzeppelin-access-control-v1-0.1.0.dar
+  - ../canton-contracts/packages/access/ownable-v1/.daml/dist/openzeppelin-ownable-v1-0.1.0.dar
+  - ../canton-contracts/packages/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar
 build-options:
   - --target=2.1
 ```
@@ -60,7 +61,7 @@ Adjust the paths to wherever you cloned the repo, and pin the exact versions fro
 **3. Import and build.** Import the modules you declared and build your project:
 
 ```daml
-import OpenZeppelin.Pausable
+import OpenZeppelin.PausableV1
 ```
 
 ```bash

content/canton/index.mdx

@@ -2,7 +2,7 @@
 title: OpenZeppelin for Canton
 ---
 
-OpenZeppelin is building a suite of secure, reusable building blocks for the [Canton Network](https://www.canton.network/), the privacy-enabled network of applications built on [Daml](https://www.digitalasset.com/developers). This section is the home for OpenZeppelin's Canton documentation: the general-purpose library, the settlement primitive, and the Reference Implementations that show how they fit together.
+OpenZeppelin is building a suite of secure, reusable building blocks for the [Canton Network](https://www.canton.network/), the privacy-enabled network of applications built on [Daml](https://docs.digitalasset.com/). This section is the home for OpenZeppelin's Canton documentation: the general-purpose library, the settlement primitive, and the Reference Implementations that show how they fit together.
 
 <Callout type="info">
   The Canton ecosystem stack is under active development. Components are labelled
@@ -21,7 +21,7 @@ Foundational Daml modules that other packages and applications compose on top of
 
 ## Settlement
 
-- **[Settlement (CIP-112)](/canton/settlement)**: An experimental, interface-shaped settlement engine for atomic multi-leg, value-moving delivery-versus-payment, aligned with the Canton Token Standard.
+- **[Settlement (CIP-112)](/canton/settlement)**: An experimental, interface-shaped settlement engine for atomic multi-leg, value-moving delivery-versus-payment, aligned with the Canton Token Standard. Developed as executable research in [`OpenZeppelin/canton-specs`](https://github.com/OpenZeppelin/canton-specs).
 
 ## Reference Implementations
 

content/canton/library/access-control.mdx

@@ -7,12 +7,15 @@ Access Control is a standalone, token-agnostic role-based access control (RBAC)
 The package is independent: it has no dependency on [Ownable](/canton/library/ownable) or [Pausable](/canton/library/pausable), so a project that wants only RBAC imports only this one package.
 
 <Callout type="warn">
-  Version 0.x, unstable, not yet public API. Interfaces may change before a 1.0
-  release. Source: [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).
+  Experimental and work in progress. This package is version 0.x, unaudited,
+  and not yet a stable public API: interfaces may change before a 1.0 release,
+  and it is not intended for production use. Source:
+  [`packages/access/access-control-v1`](https://github.com/OpenZeppelin/canton-contracts/tree/main/packages/access/access-control-v1)
+  in `OpenZeppelin/canton-contracts`.
 </Callout>
 
 ```daml
-import OpenZeppelin.AccessControl
+import OpenZeppelin.AccessControlV1
 ```
 
 ## The Daml Model

content/canton/library/index.mdx

@@ -5,8 +5,10 @@ title: Library
 The OpenZeppelin library for Canton is a set of foundational Daml modules that other packages and applications compose on top of. It brings the patterns developers know from OpenZeppelin's Solidity contracts (role-based access control, ownership, emergency stop) to Daml, adapted to Canton's authorization and privacy model rather than translated literally.
 
 <Callout type="warn">
-  Version 0.x, unstable, not yet public API. Interfaces may change before a 1.0
-  release. Source: [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).
+  Experimental and work in progress. All library packages are version 0.x,
+  unaudited, and not yet a stable public API: interfaces may change before a
+  1.0 release, and they are not intended for production use. Source:
+  [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).
 </Callout>
 
 ## Packages
@@ -19,7 +21,9 @@ Each primitive ships as its **own independent Daml package**: its own DAR, with
 
 ## Design Philosophy
 
-**Independence at the package boundary.** Daml has no inheritance, and its unit of reuse is the DAR. The library therefore delivers OpenZeppelin's decoupled-module promise at the package level: three packages, three DARs, zero cross-dependencies. A project that only needs pausing imports only `oz-pausable`.
+**Independence at the package boundary.** Daml has no inheritance, and its unit of reuse is the DAR. The library therefore delivers OpenZeppelin's decoupled-module promise at the package level: three packages, three DARs, zero cross-dependencies. A project that only needs pausing imports only `openzeppelin-pausable-v1`.
+
+**Versioned packages and modules.** Each component is released as a versioned package (`openzeppelin-<component>-v1`) with a matching module suffix (`OpenZeppelin.<Component>V1`). Compatible upgrades keep the package name; a breaking change ships as a sibling `-v2` package instead of mutating `-v1`.
 
 **Adapted, not transliterated.** Where Daml's model differs from the EVM (monomorphic templates, no global state lookups, signatory-based authority), each primitive adopts the idiomatic Daml shape and documents the divergence on its page.
 
@@ -30,9 +34,9 @@ Each primitive ships as its **own independent Daml package**: its own DAR, with
 Add the package(s) you need as data-dependencies of your Daml project and import the module:
 
 ```daml
-import OpenZeppelin.AccessControl
-import OpenZeppelin.Ownable
-import OpenZeppelin.Pausable
+import OpenZeppelin.AccessControlV1
+import OpenZeppelin.OwnableV1
+import OpenZeppelin.PausableV1
 ```
 
 See [Get Started](/canton/get-started) for toolchain setup, and each package page for its templates, choices, and usage patterns.

content/canton/library/ownable.mdx

@@ -7,12 +7,15 @@ Ownable is a standalone, token-agnostic single-owner primitive for Daml. It is t
 The package is independent: it carries no role type and has no dependency on [Access Control](/canton/library/access-control), so a project that wants only "an owner" imports only this one package.
 
 <Callout type="warn">
-  Version 0.x, unstable, not yet public API. Interfaces may change before a 1.0
-  release. Source: [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).
+  Experimental and work in progress. This package is version 0.x, unaudited,
+  and not yet a stable public API: interfaces may change before a 1.0 release,
+  and it is not intended for production use. Source:
+  [`packages/access/ownable-v1`](https://github.com/OpenZeppelin/canton-contracts/tree/main/packages/access/ownable-v1)
+  in `OpenZeppelin/canton-contracts`.
 </Callout>
 
 ```daml
-import OpenZeppelin.Ownable
+import OpenZeppelin.OwnableV1
 ```
 
 ## Why Transfer Is Always Two-Step in Daml

content/canton/library/pausable.mdx

@@ -7,12 +7,15 @@ Pausable is a standalone, token-agnostic emergency-stop switch for Daml. It is t
 The package is independent: it carries no role type and depends on no other OpenZeppelin package, so a project that wants only a pause switch imports only this one package.
 
 <Callout type="warn">
-  Version 0.x, unstable, not yet public API. Interfaces may change before a 1.0
-  release. Source: [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).
+  Experimental and work in progress. This package is version 0.x, unaudited,
+  and not yet a stable public API: interfaces may change before a 1.0 release,
+  and it is not intended for production use. Source:
+  [`packages/security/pausable-v1`](https://github.com/OpenZeppelin/canton-contracts/tree/main/packages/security/pausable-v1)
+  in `OpenZeppelin/canton-contracts`.
 </Callout>
 
 ```daml
-import OpenZeppelin.Pausable
+import OpenZeppelin.PausableV1
 ```
 
 ## What "Paused" Means on a UTXO Ledger

content/canton/reference-implementations.mdx

@@ -6,34 +6,35 @@ Reference Implementations (RIs) are complete application blueprints that show ho
 
 <Callout type="info">
   The four RIs below are in the research and design phase: each has a complete,
-  reviewed design document, and their application logic is being built out.
-  These sections will expand with code walkthroughs and integration guides as
-  each implementation lands.
+  reviewed design document, maintained as a reference architecture in
+  [`OpenZeppelin/canton-specs`](https://github.com/OpenZeppelin/canton-specs/tree/main/docs/reference-architectures),
+  and their application logic is being built out. These sections will expand
+  with code walkthroughs and integration guides as each implementation lands.
 </Callout>
 
 ## Privacy-Preserving DEX
 
 An exchange design adapted to Canton's privacy model. Its organizing primitive is the atomic delivery-versus-payment (DvP) swap: a trade is two legs (asset against payment) settled all-or-nothing through the settlement engine, so no party is ever left half-filled. Canton's projection model keeps each trader's positions and flows visible only to the parties involved, which changes how order flow, pricing, and liquidity have to be designed compared to a public-mempool chain.
 
-**Full design document:** [Canton Reference DEX: Architectural Overview](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/ri-reports/01-dex.md)
+**Full design document:** [Privacy-Preserving DEX](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/reference-architectures/dex.md)
 
 ## Lending Protocol
 
 A fixed-rate, open-term, overcollateralized, permissioned lending protocol designed for institutional participants. It covers the vault, collateral, borrow, repay, and liquidation flows, with authorization built on the library's role and ownership primitives and value movement running through the settlement engine.
 
-**Full design document:** [Institutional Lending Protocol on Canton](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/ri-reports/02-lending.md)
+**Full design document:** [Institutional Lending Protocol](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/reference-architectures/lending.md)
 
 ## Cross-Chain Stablecoin Payments
 
 An architectural blueprint for private, atomic settlement on Canton of stablecoin payments that originate on external blockchains. It resolves the tension between cross-chain liquidity and enterprise privacy requirements: institutional participants settle externally-originated payments on Canton without exposing their flows to the originating chain.
 
-**Full design document:** [Cross-Chain Stablecoin Payment Orchestration on Canton](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/ri-reports/03-cross-chain-stablecoin.md)
+**Full design document:** [Cross-Chain Stablecoin Payment Orchestration](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/reference-architectures/cross-chain-stablecoin.md)
 
 ## Confidential Auction Launchpad
 
 A launchpad for institutional, regulated, confidential token distribution. It uses Canton's sub-transaction privacy to establish a sealed-bid environment by protocol design rather than cryptographic obfuscation: bids, allocations, and settlement details are visible only to explicitly authorized parties via native ledger projection, with no commit-reveal scheme required.
 
-**Full design document:** [Confidential Auction Launchpad on Canton](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/ri-reports/04-confidential-auction.md)
+**Full design document:** [Confidential Auction Launchpad](https://github.com/OpenZeppelin/canton-specs/blob/main/docs/reference-architectures/confidential-auction.md)
 
 ## How They Relate to the Library
 

content/canton/settlement.mdx

@@ -24,9 +24,11 @@ At a high level the primitive covers:
 
 ## Status
 
-This primitive builds and is exercised two ways: an in-memory test suite against mock token interfaces, and a set of interoperability exemplars (an ERC-20-style facade, a wallet-driven settlement lifecycle, and app-provider activity attribution) that run against a local Canton ledger over the Ledger API. Importing the real Canton Token Standard packages and promoting the primitive into the general library are tracked as follow-on work. See [`OpenZeppelin/canton-specs`](https://github.com/OpenZeppelin/canton-specs) for the current engine, its threat model, and the interop exemplars.
+This primitive builds and is exercised two ways: an in-memory test suite against mock token interfaces, and a set of interoperability exemplars (an ERC-20-style facade, a wallet-driven settlement lifecycle, and app-provider activity attribution) that run against a local Canton ledger over the Ledger API. Importing the real Canton Token Standard packages and promoting the primitive into [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts) as a released package are tracked as follow-on work.
+
+The settlement engine is developed as executable research in [`OpenZeppelin/canton-specs`](https://github.com/OpenZeppelin/canton-specs), the research and incubation workspace: the [settlement experiments](https://github.com/OpenZeppelin/canton-specs/tree/main/experiments/settlement) hold the current engine, its architecture and threat model, and a regulated-settlement exemplar, while the [interoperability experiments](https://github.com/OpenZeppelin/canton-specs/tree/main/experiments/interoperability) hold the live-ledger evidence.
 
 ## Related
 
 - [Reference Implementations](/canton/reference-implementations), which compose settlement into complete applications.
-- [Library](/canton), the access-control, ownable, and pausable primitives settlement builds on.
+- [Library](/canton/library), the access-control, ownable, and pausable primitives settlement builds on.