docs: improve notarization and audit trail docs

.cargo/config.toml

@@ -0,0 +1,3 @@
+[alias]
+docs-notarization = "doc -p notarization"
+docs-audit-trail = "doc -p audit_trail"

README.md

@@ -9,48 +9,114 @@
 
 <p align="center">
   <a href="#introduction">Introduction</a> ◈
+  <a href="#where-to-start">Where To Start</a> ◈
+  <a href="#toolkits">Toolkits</a> ◈
   <a href="#documentation-and-resources">Documentation & Resources</a> ◈
   <a href="#bindings">Bindings</a> ◈
   <a href="#contributing">Contributing</a>
 </p>
 
 ---
 
-# IOTA Notarization
+# IOTA Notarization And Audit Trail
 
 ## Introduction
 
-IOTA Notarization enables the creation of immutable, on-chain records for any arbitrary data. This is achieved by storing the data, or a hash of it, inside a dedicated Move object on the IOTA ledger. This process provides a verifiable, timestamped proof of the data's existence and integrity at a specific point in time.
+This repository contains two complementary IOTA ledger toolkits for verifiable on-chain data workflows:
 
-IOTA Notarization is composed of two primary components:
+- **IOTA Notarization**
+  Best when you want a proof object for arbitrary data, documents, hashes, or latest-state notarization flows.
+- **IOTA Audit Trail**
+  Best when you want shared audit records with sequential entries, role-based access control, locking, and tagging.
 
-- **Notarization Move Package**: The on-chain smart contracts that define the behavior and structure of notarization objects.
-- **Notarization Library (Rust/Wasm)**: A client-side library that provides developers with convenient functions to create, manage, and verify `Notarization` objects on the network.
+Each toolkit is available as:
 
-## Documentation and Resources
+- a **Move package** for the on-chain contracts
+- a **Rust SDK** for typed client access and transaction builders
+- **wasm bindings** for JavaScript and TypeScript integrations
 
-- [Notarization Documentation Pages](https://docs.iota.org/developer/iota-notarization): Supplementing documentation with context around notarization and simple examples on library usage.
-- API References:
-  - [Rust API Reference](https://iotaledger.github.io/notarization/notarization/index.html): Package documentation (cargo docs).
+## Where To Start
 
-<!--  - [Wasm API Reference](https://docs.iota.org/references/iota-notarization/wasm/api_ref): Wasm Package documentation. -->
+### I want to notarize data
 
-- Examples:
-  - [Rust Examples](https://github.com/iotaledger/notarization/tree/main/examples/README.md): Practical code snippets to get you started with the library in Rust.
-  - [Wasm Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm/examples/README.md): Practical code snippets to get you started with the library in TypeScript/JavaScript.
+Use **IOTA Notarization** when your main need is proving the existence, integrity, or latest state of data on-chain.
+
+- [Notarization Rust SDK](./notarization-rs)
+- [Notarization Move Package](./notarization-move)
+- [Notarization Wasm SDK](./bindings/wasm/notarization_wasm)
+- [Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md)
+
+### I want audit records
+
+Use **IOTA Audit Trail** when you need shared audit records with permissions, capabilities, tagging, and write or delete controls.
+
+- [Audit Trail Rust SDK](./audit-trail-rs)
+- [Audit Trail Move Package](./audit-trail-move)
+- [Audit Trail Wasm SDK](./bindings/wasm/audit_trail_wasm)
+- [Audit Trail examples](./bindings/wasm/audit_trail_wasm/examples/README.md)
+
+### I want the on-chain contracts
+
+- [Notarization Move](./notarization-move)
+- [Audit Trail Move](./audit-trail-move)
+
+### I want application SDKs
+
+- [Notarization Rust](./notarization-rs)
+- [Audit Trail Rust](./audit-trail-rs)
+- [Notarization Wasm](./bindings/wasm/notarization_wasm)
+- [Audit Trail Wasm](./bindings/wasm/audit_trail_wasm)
+
+## Toolkits
+
+| Toolkit      | Best for                                                                 | Move Package                               | Rust SDK                               | Wasm SDK                                                 |
+| ------------ | ------------------------------------------------------------------------ | ------------------------------------------ | -------------------------------------- | -------------------------------------------------------- |
+| Notarization | Proof objects for documents, hashes, and updatable notarized state       | [`notarization-move`](./notarization-move) | [`notarization-rs`](./notarization-rs) | [`notarization_wasm`](./bindings/wasm/notarization_wasm) |
+| Audit Trail  | Shared sequential records with roles, capabilities, tagging, and locking | [`audit-trail-move`](./audit-trail-move)   | [`audit-trail-rs`](./audit-trail-rs)   | [`audit_trail_wasm`](./bindings/wasm/audit_trail_wasm)   |
+
+### Which one should I use?
+
+| Need                                                                      | Best fit     |
+| ------------------------------------------------------------------------- | ------------ |
+| Immutable or updatable proof object for arbitrary data                    | Notarization |
+| Simple proof-of-existence or latest-state notarization flow               | Notarization |
+| Shared sequential records with roles, capabilities, and record tag policy | Audit Trail  |
+| Team or system audit log with governance and operational controls         | Audit Trail  |
+
+## Documentation And Resources
+
+### IOTA Notarization
+
+- [Notarization Rust SDK README](./notarization-rs/README.md)
+- [Notarization Move Package README](./notarization-move/README.md)
+- [Notarization Wasm README](./bindings/wasm/notarization_wasm/README.md)
+- [Notarization examples](./bindings/wasm/notarization_wasm/examples/README.md)
+- [IOTA Notarization Docs Portal](https://docs.iota.org/developer/iota-notarization)
+
+### IOTA Audit Trail
+
+- [Audit Trail Rust SDK README](./audit-trail-rs/README.md)
+- [Audit Trail Move Package README](./audit-trail-move/README.md)
+- [Audit Trail Wasm README](./bindings/wasm/audit_trail_wasm/README.md)
+- [Audit Trail examples](./bindings/wasm/audit_trail_wasm/examples/README.md)
+
+### Shared
+
+- [Repository examples](./examples/README.md)
 
 ## Bindings
 
-[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) Bindings of this [Rust](https://www.rust-lang.org/) library to other programming languages:
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) bindings available in this repository:
 
-- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/notarization_wasm) (JavaScript/TypeScript)
+- [Web Assembly for IOTA Notarization](./bindings/wasm/notarization_wasm)
+- [Web Assembly for IOTA Audit Trail](./bindings/wasm/audit_trail_wasm)
 
 ## Contributing
 
-We would love to have you help us with the development of IOTA Notarization. Each and every contribution is greatly valued!
+We would love to have you help us with the development of IOTA Notarization and Audit Trail. Each and every contribution is greatly valued.
 
 Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
 
-To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included!
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
 
-The best place to get involved in discussions about this library or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).
+The best place to get involved in discussions about these libraries or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).

audit-trail-move/README.md

@@ -0,0 +1,90 @@
+![banner](https://github.com/iotaledger/notarization/raw/HEAD/.github/banner_notarization.png)
+
+<p align="center">
+  <a href="https://iota.stackexchange.com/" style="text-decoration:none;"><img src="https://img.shields.io/badge/StackExchange-9cf.svg?logo=stackexchange" alt="StackExchange"></a>
+  <a href="https://discord.gg/iota-builders" style="text-decoration:none;"><img src="https://img.shields.io/badge/Discord-9cf.svg?logo=discord" alt="Discord"></a>
+  <a href="https://github.com/iotaledger/notarization/blob/develop/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/iotaledger/notarization.svg" alt="Apache 2.0 license"></a>
+</p>
+
+<p align="center">
+  <a href="#introduction">Introduction</a> ◈
+  <a href="#modules">Modules</a> ◈
+  <a href="#development-and-testing">Development & Testing</a> ◈
+  <a href="#related-libraries">Related Libraries</a> ◈
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+# IOTA Audit Trail Move Package
+
+## Introduction
+
+`audit-trail-move` is the on-chain Move package behind IOTA Audit Trail.
+
+It defines the shared `AuditTrail` object and the supporting types needed for:
+
+- sequential record storage
+- role-based access control through capabilities
+- trail-wide locking for writes and deletions
+- record tags and role tag restrictions
+- immutable and updatable trail metadata
+- emitted events for trail and record lifecycle changes
+
+The package depends on `TfComponents` for reusable capability, role-map, and timelock primitives.
+
+## Modules
+
+- `audit_trail::main`
+  Core shared object, events, trail lifecycle, record mutation, metadata updates, roles, and capabilities.
+- `audit_trail::record`
+  Record payloads, initial records, and correction metadata.
+- `audit_trail::locking`
+  Locking configuration and lock evaluation helpers.
+- `audit_trail::permission`
+  Permission constructors and admin permission presets.
+- `audit_trail::record_tags`
+  Tag registry and role tag helpers.
+
+## Development And Testing
+
+Build the Move package:
+
+```bash
+cd audit-trail-move
+iota move build
+```
+
+Run the Move test suite:
+
+```bash
+cd audit-trail-move
+iota move test
+```
+
+Publish locally:
+
+```bash
+cd audit-trail-move
+./scripts/publish_package.sh
+```
+
+The publish script prints `IOTA_AUDIT_TRAIL_PKG_ID` and, on `localnet`, also exports `IOTA_TF_COMPONENTS_PKG_ID`.
+
+The package history files [`Move.lock`](./Move.lock) and [`Move.history.json`](./Move.history.json) are used by the Rust SDK to resolve and track deployed package versions.
+
+## Related Libraries
+
+- [Rust SDK](https://github.com/iotaledger/notarization/tree/main/audit-trail-rs/README.md)
+- [Wasm SDK](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/README.md)
+- [Repository Root](https://github.com/iotaledger/notarization/tree/main/README.md)
+
+## Contributing
+
+We would love to have you help us with the development of IOTA Audit Trail. Each and every contribution is greatly valued.
+
+Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
+
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
+
+The best place to get involved in discussions about this package or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).

audit-trail-rs/README.md

@@ -1 +1,61 @@
-# IOTA Audit Trail (WIP)
+![banner](https://github.com/iotaledger/notarization/raw/HEAD/.github/banner_notarization.png)
+
+<p align="center">
+  <a href="https://iota.stackexchange.com/" style="text-decoration:none;"><img src="https://img.shields.io/badge/StackExchange-9cf.svg?logo=stackexchange" alt="StackExchange"></a>
+  <a href="https://discord.gg/iota-builders" style="text-decoration:none;"><img src="https://img.shields.io/badge/Discord-9cf.svg?logo=discord" alt="Discord"></a>
+  <a href="https://github.com/iotaledger/notarization/blob/develop/LICENSE" style="text-decoration:none;"><img src="https://img.shields.io/github/license/iotaledger/notarization.svg" alt="Apache 2.0 license"></a>
+</p>
+
+<p align="center">
+  <a href="#introduction">Introduction</a> ◈
+  <a href="#documentation-and-resources">Documentation & Resources</a> ◈
+  <a href="#bindings">Bindings</a> ◈
+  <a href="#contributing">Contributing</a>
+</p>
+
+---
+
+# IOTA Audit Trail Rust SDK
+
+## Introduction
+
+`audit_trail` is the Rust SDK for reading and writing audit trails on the IOTA ledger.
+
+An audit trail is a shared on-chain object that stores a sequential series of records together with:
+
+- role-based access control backed by capabilities
+- trail-level locking rules for writes and deletions
+- tag registries for record categorization
+- immutable creation metadata and optional updatable metadata
+
+The crate provides:
+
+- read-only and signing client wrappers for the on-chain audit-trail package
+- typed trail handles for records, locking, access control, and tags
+- serializable Rust representations of on-chain objects and emitted events
+- transaction builders that integrate with the shared `product_common` transaction flow
+
+## Documentation And Resources
+
+- [Audit Trail Move Package](https://github.com/iotaledger/notarization/tree/main/audit-trail-move): On-chain contract package that defines the shared object model, permissions, locking, and events.
+- [Wasm SDK](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm): JavaScript and TypeScript bindings for browser and Node.js integrations.
+- [Wasm Examples](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm/examples/README.md): Runnable audit-trail examples for JS and TS consumers.
+- [Repository Examples](https://github.com/iotaledger/notarization/tree/main/examples/README.md): End-to-end examples across the broader repository.
+
+This README is also used as the crate-level rustdoc entry point, while the source files provide detailed API documentation for all public types and methods.
+
+## Bindings
+
+[Foreign Function Interface (FFI)](https://en.wikipedia.org/wiki/Foreign_function_interface) bindings of this Rust SDK to other programming languages:
+
+- [Web Assembly](https://github.com/iotaledger/notarization/tree/main/bindings/wasm/audit_trail_wasm) (JavaScript/TypeScript)
+
+## Contributing
+
+We would love to have you help us with the development of IOTA Audit Trail. Each and every contribution is greatly valued.
+
+Please review the [contribution](https://docs.iota.org/developer/iota-notarization/contribute) sections in the [IOTA Docs Portal](https://docs.iota.org/developer/iota-notarization/).
+
+To contribute directly to the repository, simply fork the project, push your changes to your fork and create a pull request to get them included.
+
+The best place to get involved in discussions about this library or to look for support at is the `#notarization` channel on the [IOTA Discord](https://discord.gg/iota-builders). You can also ask questions on our [Stack Exchange](https://iota.stackexchange.com/).