hyperledger-cacti · RafaelAPB · Aug 27, 2026 · Aug 26, 2026
diff --git a/README.md b/README.md
@@ -50,8 +50,8 @@ This repository is organized as a Yarn Workspace:
 │   │   └── config/                   # Adapter configuration files (gateway + adapter YAML configs)
 │   └── extensions/
 │       └── carbon-credit/            # Extending core gateway logic with business-related functionality
-├── examples/                         # Future: full-fledged example applications (empty for now)
-├── packages/                         # Future: test packages migrated from cacti (empty for now)
+├── examples/                         # Example applications and workshop projects
+├── packages/                         # Shared test fixtures and integration-test packages
 ├── Makefile                          # Orchestrates all demo cases
 ├── package.json                      # Workspace configuration
 └── tsconfig.json                     # TypeScript compiler configuration
@@ -61,6 +61,8 @@ This repository is organized as a Yarn Workspace:
 
 ## Case Descriptions
 
+Active workspaces under [examples](./examples/) and [packages](./packages/) include a README describing their purpose, setup, API surface, usage, and validation guidance.
+
 ### Extensions Cases
 
 These use cases demonstrate the usage of the extensions available in the gateway:

diff --git a/examples/cacti-starter/README.md b/examples/cacti-starter/README.md
@@ -1,84 +1,73 @@
-# Cacti Starter: Minimal Onboarding Template
+# @hyperledger-cacti/cacti-starter
 
-Welcome to the Hyperledger Cacti Starter! This template provides the simplest possible "Hello World" experience for new contributors. It demonstrates Level 2 architecture (API Server + Plugin) with minimal setup.
+## Overview
 
-## Quick Start
+A minimal Hyperledger Cacti application that starts the Cacti API server with the in-memory keychain plugin. It provides a small, editable onboarding example for local development.
 
-```bash
-cd examples/cacti-starter
-./bootstrap.sh
-./run.sh
-```
+### Target Audience
+
+- [x] Application developers
+- [x] Contributors
+- [ ] Operators
 
-Swagger UI: [http://127.0.0.1:4000/api/v1/api-docs/](http://127.0.0.1:4000/api/v1/api-docs/)
+> This example disables authentication and TLS for simplicity. Do not use this configuration in production.
 
-## Test the Keychain Plugin
+## Install
 
-In a new terminal:
+Use Node.js 20.20.0 and Corepack-enabled Yarn. From this directory:
 
 ```bash
-./test.sh
+./bootstrap.sh
 ```
 
-## Architecture
+The bootstrap script installs the repository dependencies and prepares the starter configuration.
 
-- **API Server**: Runs the Cacti REST API
-- **Plugin**: Only `@hyperledger/cactus-plugin-keychain-memory` is loaded
-- **No JWT, No TLS**: Authentication and encryption are disabled for simplicity
+## Configuration
 
-> **Note on TLS configuration**: Even though TLS is disabled in this starter (`"apiTlsEnabled": false`), the Cacti v3 framework configuration schema strictly enforces the presence of TLS certificate strings and validates them when booting its internal gRPC server. Because of this, the `.config.json` includes dummy self-signed certificates. This is the correct setup for a local development "No TLS" environment in v3. For a production environment, you would replace these strings with real CA-signed certificates and set TLS to true.
+The .config.json file configures the API server on port 4000 and loads @hyperledger-cacti/cactus-plugin-keychain-memory. The example includes self-signed certificate material because the Cacti configuration schema requires certificate values even when apiTlsEnabled is false.
 
-```mermaid
-graph TD
-    Client[Client or curl] -->|HTTP POST| API[Cacti API Server 4000]
-    API -->|Route Request| Plugin[Keychain Memory Plugin]
-    Plugin -->|Store Data| Mem[(In-Memory Storage)]
-```
+For production deployments, enable TLS, use certificates issued for the deployment, and configure an appropriate authorization protocol.
 
-## Purpose
+## API Summary
 
-- Help new contributors get started in minutes
-- Provide a working, hackable Cacti setup
-- Avoid all unnecessary complexity
+The example exposes the API server and the endpoints registered by the in-memory keychain plugin. Swagger UI is available at http://127.0.0.1:4000/api/v1/api-docs/ while the application is running.
 
----
+Relevant Cacti packages:
 
-## Environment Setup (Ubuntu / Linux)
+- [Cacti API server](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-cmd-api-server)
+- [In-memory keychain plugin](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-plugin-keychain-memory)
 
-If you are starting from scratch on Ubuntu, follow these prerequisites to get your environment ready:
+## Usage
 
-#### 1. Git
+Start the example:
 
 ```bash
-sudo apt update
-sudo apt install -y git
+./run.sh
 ```
 
-#### 2. Node.js (v20.20.0) & npm
+The request flow is:
 
-Use nvm (Node Version Manager):
-
-```bash
-curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
-source ~/.bashrc
-nvm install 20.20.0
-nvm use 20.20.0
+```mermaid
+graph TD
+    Client[Client or curl] -->|HTTP request| API[Cacti API Server :4000]
+    API -->|Route request| Plugin[In-memory keychain plugin]
+    Plugin -->|Store data| Memory[(Process memory)]
 ```
 
-#### 3. Yarn (via Corepack)
+## Testing
+
+With the application running, use a second terminal:
 
 ```bash
-corepack enable
+./test.sh
 ```
 
-#### 4. Docker Engine & Compose
+The script exercises the keychain endpoint exposed by the starter.
 
-Docker is required if you plan to run blockchain ledgers.
+## Contributing
 
-```bash
-sudo apt install -y docker.io docker-compose
-sudo systemctl start docker
-sudo systemctl enable docker
-sudo usermod -aG docker $USER
-newgrp docker
-```
+See the repository [contribution guidelines](../../CONTRIBUTING.md).
+
+## Acknowledgments
+
+This example uses Hyperledger Cacti packages maintained in the [main Cacti repository](https://github.com/hyperledger-cacti/cacti).
diff --git a/examples/cactus-common-example-server/README.md b/examples/cactus-common-example-server/README.md
@@ -1,16 +1,73 @@
-# `@hyperledger/cactus-common-example-server`
+# @hyperledger-cacti/cactus-common-example-server
 
-This is a module for common server setup used by some sample application. Do not use on production.
+## Overview
 
-## Usage samples
-	- [cactus-example-electricity-trade](../../examples/cactus-example-electricity-trade)
-	- [cactus-example-discounted-asset-trade](../../examples/cactus-example-discounted-asset-trade)
+Shared server-side utilities retained for Cacti demo applications. The package contains verifier, routing interface, business logic plugin, configuration, and transaction-signing helpers.
 
-## Docker
-- Docker image of this package is used mostly as a base for other applications and plugins (BLP, socketio connectors).
-- Docker build process will use artifacts from the latest build. Make sure `./dist` contains the version you want to dockerize.
+### Target Audience
 
-```
-# Build
-docker build . -t cactus-common-example-server
-```
+- [x] Application developers
+- [x] Contributors
+- [ ] Operators
+
+> This package supports demonstrations and tests. It is not intended for production use.
+
+## Install
+
+Install repository dependencies from the cacti-demos root:
+
+~~~bash
+yarn install
+yarn workspace @hyperledger-cacti/cactus-common-example-server run build
+~~~
+
+## API Summary
+
+The public API exports:
+
+- Verifier and ledger-event utilities
+- Routing types and transaction-management helpers
+- Socket.IO server startup and business logic plugin configuration
+- BusinessLogicPlugin, BusinessLogicBase, and LedgerOperation
+- TransactionSigner and configuration-reading utilities
+
+The implementation builds on [Cacti Common](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-common) and [Cacti Core API](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-core-api).
+
+## Usage
+
+Import only the utility required by the consuming example:
+
+~~~typescript
+import {
+  BusinessLogicPlugin,
+  TransactionSigner,
+} from "@hyperledger-cacti/cactus-common-example-server";
+~~~
+
+Refer to src/main/typescript/public-api.ts for the complete supported export surface.
+
+## Container Image
+
+The Docker image is primarily a base for demo applications and plugins. Build the TypeScript output before building the image:
+
+~~~bash
+yarn workspace @hyperledger-cacti/cactus-common-example-server run build
+docker build examples/cactus-common-example-server -t cactus-common-example-server
+~~~
+
+## Testing
+
+The package contains unit tests under src/test/typescript/unit. It does not define a standalone test script. From the repository root, validate compilation and repository formatting with:
+
+~~~bash
+yarn run build:dev:backend
+yarn run lint
+~~~
+
+## Contributing
+
+See the repository [contribution guidelines](../../CONTRIBUTING.md).
+
+## License
+
+The package metadata declares the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).
diff --git a/examples/cactus-example-cbdc-bridging-backend/README.md b/examples/cactus-example-cbdc-bridging-backend/README.md
@@ -1,52 +1,95 @@
-# Hyperledger Cactus Example - CBDC Bridging between Fabric and Besu Backend
+# @hyperledger-cacti/cactus-example-cbdc-bridging-backend
 
-## Running the Test Suites
+## Overview
 
-> Make sure you have all the dependencies set up as explained in `BUILD.md`
+Backend for the CBDC bridging example. It demonstrates an asset transfer workflow between Hyperledger Fabric and Hyperledger Besu using Cacti ledger connectors, SATP Hermes gateways, keychain storage, and IPFS-backed object storage.
 
-On the terminal, issue the following commands in the project root:
+### Target Audience
 
-1. `yarn run configure`
-2. `yarn run start:example-cbdc-bridging-app`
+- [x] Application developers
+- [x] Contributors
+- [ ] Operators
 
-Wait for the output to show the message `CbdcBridgingApp running...`
+> This application is an integration example and is not production-ready.
 
-In a second terminal run the following commands from the project root: 3. `cd examples/cactus-example-cbdc-bridging-backend` 4. `yarn run test`
+## Install
 
-## Running the Example Application Locally
+Use Node.js 20.20.0 and install dependencies from the cacti-demos root:
 
-> Make sure you have all the dependencies set up as explained in `BUILD.md`
+```bash
+yarn install
+```
+
+Docker is required because the example provisions test ledger infrastructure.
+
+## Configuration
+
+The process.env file in this directory defines the local service addresses and ports:
+
+| Variable                  | Purpose                               |
+| :------------------------ | :------------------------------------ |
+| API_HOST                  | Hostname used by the backend services |
+| API_SERVER_1_PORT         | Fabric connector API port             |
+| API_SERVER_2_PORT         | Besu connector API port               |
+| API_GATEWAY_1_BLO_PORT    | Gateway 1 OpenAPI service port        |
+| API_GATEWAY_2_BLO_PORT    | Gateway 2 OpenAPI service port        |
+| API_GATEWAY_1_CLIENT_PORT | Gateway 1 SATP client port            |
+| API_GATEWAY_2_CLIENT_PORT | Gateway 2 SATP client port            |
+| API_GATEWAY_1_SERVER_PORT | Gateway 1 SATP server port            |
+| API_GATEWAY_2_SERVER_PORT | Gateway 2 SATP server port            |
+
+Review the file before changing ports because the frontend and integration tests expect compatible endpoint values.
+
+## API Summary
+
+The package exports CbdcBridgingApp and its options. Its HTTP contract is defined in src/main/yml/openapi.yml and generated into the TypeScript sources during the repository build.
+
+The example integrates these Cacti packages:
 
-On the terminal, issue the following commands:
+- [Cacti API client](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-api-client)
+- [Cacti API server](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-cmd-api-server)
+- [Besu connector](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-plugin-ledger-connector-besu)
+- [Fabric connector](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-plugin-ledger-connector-fabric)
+- [SATP Hermes](https://github.com/hyperledger-cacti/cacti/tree/main/packages/cactus-plugin-satp-hermes)
+- [IPFS object store](https://github.com/hyperledger-cacti/cacti/tree/main/extensions/cactus-plugin-object-store-ipfs)
 
-1. `yarn run configure`
-2. `yarn run start:example-cbdc-bridging-app`
+## Usage
 
-Wait for the output to show the message `CbdcBridgingApp running...`
+Start the backend from the repository root:
 
-## Running with a different configuration
+```bash
+yarn workspace @hyperledger-cacti/cactus-example-cbdc-bridging-backend run start
+```
+
+Wait for CbdcBridgingApp running... before starting the frontend or integration tests.
+
+### Debugging in Visual Studio Code
+
+1. Open .vscode/template.launch.json.
+2. Copy the Example: CBDC Bridging Fabric-EVM App configuration into .vscode/launch.json.
+3. Select that configuration in Run and Debug.
+4. Start the debugger and wait for the backend startup message.
+
+## Testing
 
-There is a `process.env` file where you can change the following variables:
+Run the Cucumber suite:
 
+```bash
+yarn workspace @hyperledger-cacti/cactus-example-cbdc-bridging-backend run test
 ```
-API_HOST=localhost // the path where the backend will be running
-API_SERVER_1_PORT=4000 // port assign to the FabricConnectorApi
-API_SERVER_2_PORT=4100 // port assign to the BesuConnectorApi
-API_GATEWAY_1_BLO_PORT=4010 // port assign to the Gateway1's OpenApi Service
-API_GATEWAY_2_BLO_PORT=4110 // port assign to the Gateway2's SATP Service
-API_GATEWAY_1_CLIENT_PORT=3011 // port assign to the Gateway1's SATP Client Service
-API_GATEWAY_2_CLIENT_PORT=3111 // port assign to the Gateway2's SATP Client Service
-API_GATEWAY_1_SERVER_PORT=3010 // port assign to the Gateway1's SATP Server Service
-API_GATEWAY_2_SERVER_PORT=3110 // port assign to the Gateway2's SATP Server Service
+
+Run the Jest integration suite:
+
+```bash
+yarn workspace @hyperledger-cacti/cactus-example-cbdc-bridging-backend run test:integration
 ```
 
-## Debugging the Example Application Locally
+These tests provision external services and require Docker.
+
+## Contributing
+
+See the repository [contribution guidelines](../../CONTRIBUTING.md).
 
-On the terminal, issue the following commands (steps 1 to 6) and then perform the rest of the steps manually.
+## License
 
-1. `yarn run configure`
-2. Locate the `.vscode/template.launch.json` file
-3. Within that file locate the entry named `"Example: CBDC Bridging Fabric-EVM App"`
-4. Copy the VSCode debug definition object from 2) to your `.vscode/launch.json` file
-5. At this point the VSCode `Run and Debug` panel on the left should have an option also titled `"Example: CBDC Bridging Fabric-EVM App"` which starts the application
-6. Wait for the output to show the message `CbdcBridgingApp running...`
+The package metadata declares the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0).