From 4da9407ec5522f4dde8814fa4979b6afc8c2ff1a Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Mon, 25 Aug 2025 22:32:35 -0400
Subject: [PATCH 01/10] feat(docs): update introduction page with architecture
 section and new cards

---
 docs/introduction.mdx | 31 +++++++++++++++++++++++--------
 1 file changed, 23 insertions(+), 8 deletions(-)

diff --git a/docs/introduction.mdx b/docs/introduction.mdx
index fc62981..7d3afb2 100644
--- a/docs/introduction.mdx
+++ b/docs/introduction.mdx
@@ -21,6 +21,16 @@ Find all the information you need to get started with OpenTDF.
   walk you through some of the basic concepts within the OpenTDF platform.
 </Callout>
 
+<Callout
+  title="Architecture"
+  callToAction={{
+    label: "Learn more",
+    link: "/architecture",
+  }}
+>
+  Learn about the core components of the OpenTDF platform and how they work together in a standards-based architecture.
+</Callout>
+
 <Cards
   height={300}
   columns={3}
@@ -34,19 +44,24 @@ Find all the information you need to get started with OpenTDF.
     },
     {
       name: "Policy",
-      description: `The OpenTDF Policy engine enables creation, enforcement, and subscription to policies. By
-      using attribute-based access control (ABAC) policies, the OpenTDF Policy engine can enforce flexible,
-      fine-grained access control based on entity entitlements.`,
+      description: `The OpenTDF Policy engine enables creation, enforcement, and subscription to policies using attribute-based access control (ABAC) to enforce flexible, fine-grained access control.`,
       url: "/components/policy",
     },
     {
       name: "Authorization",
-      description: `The OpenTDF Authorization service enables policy driven, access based decisions using
-      attribute-based access control (ABAC) based on entity entitlements. These decisions are used to enforce
-      both data privacy and application security, ensuring consistent policy enforcement across all policy
-      enforcement points.`,
+      description: `The Authorization service enables policy driven, access based decisions using entity entitlements to enforce consistent data privacy and application security.`,
       url: "/components/authorization",
     },
+    {
+      name: "Key Access",
+      description: "The Key Access service manages the cryptographic keys required for TDF encryption and decryption, enforcing access control decisions by granting or denying key requests.",
+      url: "/components/key_access",
+    },
+    {
+      name: "Entity Resolution",
+      description: "The Entity Resolution service gathers and resolves entity attributes from various sources, providing the context needed for the Authorization service to make decisions.",
+      url: "/components/entity_resolution",
+    },
   ]}
 />
 
@@ -70,4 +85,4 @@ Find all the information you need to get started with OpenTDF.
       url: "/components/cli",
     },
   ]}
-/>
+/>
\ No newline at end of file

From bf393f0fe018dc559672664f203a37cf4e99cafc Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Thu, 18 Sep 2025 17:33:04 -0400
Subject: [PATCH 02/10] Updates to policy docs

---
 docs/components/policy/attributes.md          | 14 ++++++-
 docs/components/policy/index.md               | 34 +++++++++++----
 docs/components/policy/key_access_grants.md   |  6 +++
 docs/components/policy/key_access_registry.md | 41 +++----------------
 docs/components/policy/resource_mappings.md   |  6 ++-
 5 files changed, 54 insertions(+), 47 deletions(-)

diff --git a/docs/components/policy/attributes.md b/docs/components/policy/attributes.md
index 58d1451..484b776 100644
--- a/docs/components/policy/attributes.md
+++ b/docs/components/policy/attributes.md
@@ -69,6 +69,18 @@ style C fill:#0697e4f5,stroke:#333,stroke-width:1px,color:black
 
 These attributes will now be used to drive access decisions based on policies in the platform.
 
+## Attribute Rules
+
+Attribute definitions have a rule that determines how the values of the attribute are evaluated. The following rules are available:
+
+- **ALL_OF**: All of the values in the attribute must be present in the entity's entitlements.
+- **ANY_OF**: Any of the values in the attribute must be present in the entity's entitlements.
+- **HIERARCHY**: The values of the attribute are ordered, and the entity must have an entitlement that is greater than or equal to the value in the policy.
+
+## Key Association
+
+Keys can be associated with attributes and values. This allows for more granular access control. For example, you can require that an entity has a specific key in addition to the required attributes.
+
 ## Unsafe Actions
 
 Certain actions on policy attributes are considered "unsafe" because they may inadvertently affect access control, potentially granting or removing access unintentionally. Deactivating a Namespace, for example, cascades to deactivate its Definitions and their Values. Similarly, deactivating a Definition deactivates its Values.
@@ -90,4 +102,4 @@ Unsafe actions on policy attributes include:
   - Reactivation (does not bubble up to reactivate the definition or namespace).
   - Deletion (permanently removes the value without affecting the parent definition or namespace).
 
-These mutations can retroactively change access to existing and new TDFs, making it crucial to handle them with caution.
+These mutations can retroactively change access to existing and new TDFs, making it crucial to handle them with caution.
\ No newline at end of file
diff --git a/docs/components/policy/index.md b/docs/components/policy/index.md
index bcb98c2..d9bd936 100644
--- a/docs/components/policy/index.md
+++ b/docs/components/policy/index.md
@@ -7,22 +7,38 @@ slug: /components/policy
 Policy is the all-encompassing name for configuration of cryptographically-bound Attribute Based Access Control (ABAC) within the Platform.
 
 ```mermaid
-graph LR;
-  Data<-- Resource Mappings -->Attributes;
-  Attributes<-- Subject Mappings -->Entities;
+graph TD
+    subgraph "External Concepts"
+        ENTITIES[Entities]
+        DATA[Data]
+    end
+
+    subgraph "Policy Components"
+        SM[Subject Mappings]
+        RM[Resource Mappings]
+        ATTR[Attributes]
+        ACTIONS[Actions]
+        KM[Key Mappings]
+    end
+
+    ENTITIES --> SM --> ATTR
+    DATA --> RM
+    ACTIONS --> RM
+    RM --> ATTR
+    ATTR --> KM
 ```
 
 TDF creation and decryption are driven by the Policy within a Platform instance and the TDF manifest. In other words, on a TDF decryption request, the platform services (KAS, Authorization) compare attributes on the TDF against the requester's entitlements to make a decision to release the key or not.
 
 Components of Policy include:
 
-- Attributes
+- [Attributes](./attributes.md)
   - Namespaces
   - Definitions
   - Values
-- Actions
-- Subject Mappings
+- [Actions](./actions.md)
+- [Subject Mappings](./subject_mappings.md)
   - Subject Condition Sets
-- Registered Resources
-- Resource Mappings
-- Key Access Grants (KAS Grants)
+- [Registered Resources](./registered_resources.md)
+- [Resource Mappings](./resource_mappings.md)
+- [Key Mappings](./keymanagement/key_mappings.md)
\ No newline at end of file
diff --git a/docs/components/policy/key_access_grants.md b/docs/components/policy/key_access_grants.md
index 58ff929..4aeeca2 100644
--- a/docs/components/policy/key_access_grants.md
+++ b/docs/components/policy/key_access_grants.md
@@ -5,6 +5,12 @@ In v0.7.0 of the platform creating grants is now deprecated in favor of
 [key mappings](./keymanagement/key_mappings.md). Version 0.7.0 of the platform
 will error when attempting to assign key access servers to attributes.
 :::
+
+If you currently have Key Access Grants defined, it is recommended to follow the [migration steps](./key_access_grants.md#migration-to-key-mappings).
+
+:::warning
+All migration steps should be completed in one go. As soon as a new key map is created, kas-grants are no longer used; this might result in TDFs being generated without the correct keys being used if the migration is not completed.
+:::
 Key Access Grants (KAS Grants) are associations between a registered Key Access Server (KAS) and an Attribute. These grants can be applied at the namespace, definition, or value level of an attribute.
 
 KAS Grants enable key split behaviors on TDFs with attributes, facilitating various collaboration scenarios around shared policies. Grants follow the specificity matrix below, which determines the KAS public keys used for encryption in various KAS grant scenarios:
diff --git a/docs/components/policy/key_access_registry.md b/docs/components/policy/key_access_registry.md
index 867b5ba..9e576f9 100644
--- a/docs/components/policy/key_access_registry.md
+++ b/docs/components/policy/key_access_registry.md
@@ -5,43 +5,12 @@ The Key Access Server (KAS) Registry within the platform policy is a store of kn
 Within platform policy, a registered KAS instance has the following key attributes:
 
 1. **URI**: The location where the KAS is accessible. This must be unique among all KAS instances registered in the platform.
-2. **Public Key Location**:
-   1. **Remote**: A public key available at an endpoint, such as `https://kas-one.com/public_key`.
-   2. **Cached**: One or more public keys stored within the platform policy database (see the example below).
+2. **Keys**: Each KAS can have multiple keys associated with it. These keys are used to encrypt and decrypt TDFs.
 
-These traits are essential for managing KAS Grants to attributes and their associated key splits in encryption and decryption processes.
+## Base Key
 
-#### Cached Key Example
+A KAS can have a base key, which is the default key that is used for encryption. If no other key is specified, the base key will be used.
 
-```json5
-{
-  "cached": {
-    // One or more known public keys for the KAS
-    "keys": [
-      {
-        // x509 ASN.1 content in PEM format
-        "pem": "<your PEM certificate>",
-        // key identifier 
-        "kid": "<your key id>",
-        // key algorithm (see below)
-        "alg": 1
-      }
-    ]
-  }
-}
-```
+## Key Mappings
 
-1. The `"pem"` field should contain the full certificate, for example:
-   `-----BEGIN CERTIFICATE-----
-MIIB...5Q=
------END CERTIFICATE-----
-`.
-
-2. The `"kid"` field represents the key identifier, which is primarily used for key rotation.
-
-3. The `"alg"` field specifies the key algorithm used:
-
-| Key Algorithm     | `alg` Value |
-| ----------------- | ----------- |
-| `rsa:2048`        | 1           |
-| `ec:secp256r1`    | 5           |
+Keys can be mapped to namespaces, attribute definitions, and attribute values. When an SDK client creates a TDF with an attribute that has a mapped key, the client will use the mapped key to encrypt the payload.
\ No newline at end of file
diff --git a/docs/components/policy/resource_mappings.md b/docs/components/policy/resource_mappings.md
index e6f14a2..22096ae 100644
--- a/docs/components/policy/resource_mappings.md
+++ b/docs/components/policy/resource_mappings.md
@@ -9,8 +9,12 @@ A Resource Mapping contains:
 
 The primary consumer of a Resource Mapping is a Policy Decision Point (PDP), which processes data, applies logic using the known terms, and relies on them to map the data to Attribute Values. By mapping a set of terms to a given attribute value, a Policy Enforcement Point (PEP) can properly apply the TDF to the resource data using the appropriate attribute values.
 
+## Resource Mapping Groups
+
+Resource Mapping Groups allow you to group resource mappings together. This can be useful for organizing and managing your resource mappings.
+
 # Examples
 
 Alice is a system administrator. She defines an Attribute definition called color with values like red, green, blue, purple, etc. For the Attribute Value `https://demo.com/attr/color/value/purple'`, she would define a Resource Mapping for processing data that may involve terms like `indigo`, `lilac`, `plum`, or `lavender`.
 
-Bob is a system administrator in the US Department of Defense (DoD). Bob defines a hierarchical attribute called classification with values of `topsecret`, `secret`, `confidential`, and `unclassified`. He needs to create a resource mapping that defines a normalization of the various short forms and acronyms that map to each of these classification levels. For the `topsecret` attribute value, he might include terms like `ts`, `top secret`, and `top-secret`. Whereas for unclassified he might include `u`, `uc`, or other variations.
+Bob is a system administrator in the US Department of Defense (DoD). Bob defines a hierarchical attribute called classification with values of `topsecret`, `secret`, `confidential`, and `unclassified`. He needs to create a resource mapping that defines a normalization of the various short forms and acronyms that map to each of these classification levels. For the `topsecret` attribute value, he might include terms like `ts`, `top secret`, and `top-secret`. Whereas for unclassified he might include `u`, `uc`, or other variations.
\ No newline at end of file

From c25bde2302f4ebc7a43f78d638e25697abe2467c Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Mon, 6 Oct 2025 18:57:03 -0400
Subject: [PATCH 03/10] Restructured via Diataxis

---
 .gitignore                                    |   6 +
 docs/explanation/_category_.json              |  10 +
 .../data-centric-security/_category_.json     |   8 +
 .../data-centric-security/index.md            | 109 +++++
 docs/explanation/index.mdx                    |  54 +++
 .../platform-architecture/_category_.json     |   8 +
 .../platform-architecture/index.md}           |   0
 .../trusted-data-format/_category_.json       |   8 +
 docs/explanation/trusted-data-format/index.md | 127 +++++
 docs/getting-started/_category_.yaml          |   1 -
 docs/how-to/_category_.json                   |  10 +
 docs/how-to/index.mdx                         |  38 ++
 .../sdk-recipes}/_category_.json              |   0
 .../sdk-recipes}/authorization.mdx            |   0
 docs/how-to/sdk-recipes/index.mdx             |  51 +++
 .../{sdks => how-to/sdk-recipes}/overview.mdx |   2 +-
 docs/how-to/sdk-recipes/policy.mdx            |  35 ++
 docs/how-to/sdk-recipes/tdf.mdx               |  10 +
 docs/index.mdx                                | 186 ++++++++
 docs/introduction.mdx                         |  88 ----
 docs/reference/_category_.json                |  10 +
 docs/reference/index.mdx                      |  51 +++
 docs/sdks/policy.mdx                          |  35 --
 docs/sdks/tdf.mdx                             |  10 -
 docs/tutorials/_category_.json                |  10 +
 docs/tutorials/index.mdx                      |  34 ++
 docs/tutorials/your-first-tdf/_category_.json |   8 +
 .../tutorials/your-first-tdf/configuration.md | 433 ++++++++++++++++++
 .../your-first-tdf}/index.mdx                 |   2 +-
 docusaurus.config.ts                          |   8 +-
 .../v2/authorization.openapi.yaml             |  55 ++-
 specs/policy/actions/actions.openapi.yaml     | 100 ++++
 .../policy/attributes/attributes.openapi.yaml | 100 ++++
 .../key_access_server_registry.openapi.yaml   |   3 +
 .../keymanagement/key_management.openapi.yaml |  21 +-
 specs/policy/objects.openapi.yaml             |  44 ++
 .../obligations/obligations.openapi.yaml      | 368 ++++++++++-----
 .../registered_resources.openapi.yaml         | 100 ++++
 .../resource_mapping.openapi.yaml             | 100 ++++
 .../subject_mapping.openapi.yaml              | 100 ++++
 specs/policy/unsafe/unsafe.openapi.yaml       | 103 +++++
 src/css/custom.css                            |  48 ++
 src/pages/index.tsx                           | 176 ++++++-
 43 files changed, 2409 insertions(+), 261 deletions(-)
 create mode 100644 docs/explanation/_category_.json
 create mode 100644 docs/explanation/data-centric-security/_category_.json
 create mode 100644 docs/explanation/data-centric-security/index.md
 create mode 100644 docs/explanation/index.mdx
 create mode 100644 docs/explanation/platform-architecture/_category_.json
 rename docs/{architecture.mdx => explanation/platform-architecture/index.md} (100%)
 create mode 100644 docs/explanation/trusted-data-format/_category_.json
 create mode 100644 docs/explanation/trusted-data-format/index.md
 delete mode 100644 docs/getting-started/_category_.yaml
 create mode 100644 docs/how-to/_category_.json
 create mode 100644 docs/how-to/index.mdx
 rename docs/{sdks => how-to/sdk-recipes}/_category_.json (100%)
 rename docs/{sdks => how-to/sdk-recipes}/authorization.mdx (100%)
 create mode 100644 docs/how-to/sdk-recipes/index.mdx
 rename docs/{sdks => how-to/sdk-recipes}/overview.mdx (85%)
 create mode 100644 docs/how-to/sdk-recipes/policy.mdx
 create mode 100644 docs/how-to/sdk-recipes/tdf.mdx
 create mode 100644 docs/index.mdx
 delete mode 100644 docs/introduction.mdx
 create mode 100644 docs/reference/_category_.json
 create mode 100644 docs/reference/index.mdx
 delete mode 100644 docs/sdks/policy.mdx
 delete mode 100644 docs/sdks/tdf.mdx
 create mode 100644 docs/tutorials/_category_.json
 create mode 100644 docs/tutorials/index.mdx
 create mode 100644 docs/tutorials/your-first-tdf/_category_.json
 create mode 100644 docs/tutorials/your-first-tdf/configuration.md
 rename docs/{getting-started => tutorials/your-first-tdf}/index.mdx (99%)

diff --git a/.gitignore b/.gitignore
index 71d35fc..5bad750 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,8 +11,11 @@ docs/SDK-Samples/
 # Generated files
 .docusaurus
 .cache-loader
+docs/.index.json
 # Ignore all generated _category_.json files in docs/spec
 /docs/spec/**/_category_.json
+# Backup files
+*.backup
 
 # Misc
 .DS_Store
@@ -30,6 +33,9 @@ node_modules
 /docs/spec/index.md
 /docs/spec/**/*.md
 /docs/components/cli/
+/docs/reference/cli/
+/docs/reference/api/
+/docs/reference/specifications/
 /docs/getting-started/configuration.md
 
 /.idea/
diff --git a/docs/explanation/_category_.json b/docs/explanation/_category_.json
new file mode 100644
index 0000000..e92fa29
--- /dev/null
+++ b/docs/explanation/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Understanding OpenTDF",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn the core concepts behind OpenTDF, data-centric security, and how the platform implements zero-trust data protection through the Trusted Data Format."
+  },
+  "collapsible": true,
+  "collapsed": false
+}
\ No newline at end of file
diff --git a/docs/explanation/data-centric-security/_category_.json b/docs/explanation/data-centric-security/_category_.json
new file mode 100644
index 0000000..fe19690
--- /dev/null
+++ b/docs/explanation/data-centric-security/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Data-Centric Security",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Understand the fundamental shift from perimeter-based security to data-centric protection, where policies travel with data."
+  }
+}
\ No newline at end of file
diff --git a/docs/explanation/data-centric-security/index.md b/docs/explanation/data-centric-security/index.md
new file mode 100644
index 0000000..d6697d5
--- /dev/null
+++ b/docs/explanation/data-centric-security/index.md
@@ -0,0 +1,109 @@
+# What is Data-Centric Security?
+
+**Data-centric security** represents a fundamental shift in how we protect information. Instead of focusing on securing networks, devices, or applications, data-centric security protects the data itself. This means that access controls, policies, and protections are directly attached to data objects, traveling with them wherever they go.
+
+## The Traditional Problem
+
+In traditional **perimeter-based security**, organizations build walls around their networks and systems:
+
+```mermaid
+graph LR
+    subgraph "Corporate Network"
+        DB[(Database)]
+        APP[Application]
+        FILES[File Server]
+    end
+    
+    FIREWALL[🔥 Firewall]
+    INTERNET[🌐 Internet]
+    USER[👤 User]
+    
+    INTERNET --> FIREWALL
+    FIREWALL --> DB
+    FIREWALL --> APP
+    FIREWALL --> FILES
+    USER --> FIREWALL
+```
+
+**Problems with this approach:**
+- **Data leaves the perimeter**: Once data is shared, copied, or moved, control is lost
+- **Insider threats**: Users inside the perimeter have broad access
+- **Breach consequences**: If perimeter is breached, all internal data is at risk
+- **Remote work challenges**: Extending perimeter to remote users is complex
+- **Third-party sharing**: No control once data reaches partners or vendors
+
+## The Data-Centric Solution
+
+Data-centric security inverts this model by making **data self-protecting**:
+
+```mermaid
+graph TD
+    DATA[🔒 Protected Data]
+    POLICY[📋 Access Policy]
+    USER1[👤 Alice]
+    USER2[👤 Bob]
+    USER3[👤 Charlie]
+    
+    DATA -.-> POLICY
+    POLICY --> USER1
+    POLICY --> USER2
+    POLICY -.-> USER3
+    
+    classDef granted fill:#90EE90
+    classDef denied fill:#FFB6C1
+    classDef data fill:#87CEEB
+    
+    class USER1,USER2 granted
+    class USER3 denied
+    class DATA data
+```
+
+**Benefits of this approach:**
+- **Policy travels with data**: Controls remain effective regardless of location
+- **Fine-grained access**: Decisions based on user, context, and data sensitivity
+- **Zero-trust ready**: No assumptions about network security or user location
+- **Audit trail**: Complete visibility into who accessed what, when, and where
+- **Revocable access**: Policies can be updated or revoked in real-time
+
+## How OpenTDF Implements Data-Centric Security
+
+OpenTDF uses the **Trusted Data Format (TDF)** to implement data-centric security:
+
+1. **Cryptographic Binding**: Access policies are cryptographically bound to encrypted data
+2. **Attribute-Based Control**: Fine-grained access decisions using user and data attributes
+3. **Key Management**: Centralized key services enforce policy decisions
+4. **Standards-Based**: Built on the proven NIST ABAC (Attribute-Based Access Control) model
+
+## Real-World Example
+
+Consider a confidential financial report:
+
+**Traditional Security:**
+- File stored on secure file server
+- Access controlled by network permissions
+- If shared via email → no control
+- If copied to USB → no control  
+- If partner accesses → no control
+
+**Data-Centric Security with OpenTDF:**
+- File encrypted as TDF with policy: "Only Finance team members can access"
+- Policy travels with the file everywhere
+- Authorization checked every time someone tries to open it
+- Access can be revoked or modified at any time
+- Complete audit trail of all access attempts
+
+## Zero-Trust Integration
+
+Data-centric security is a cornerstone of **zero-trust architecture**:
+
+- **Never trust, always verify**: Every data access request is authenticated and authorized
+- **Assume breach**: Data remains protected even if systems are compromised  
+- **Least privilege**: Users get minimal access needed for their role
+- **Context-aware**: Access decisions consider location, time, device, and behavior
+
+## Next Steps
+
+- Learn about the [Trusted Data Format](/explanation/trusted-data-format) that makes this possible
+- Understand [how OpenTDF fits into Zero-Trust architecture](/explanation/data-centric-security/zero-trust-architecture) 
+- See the [benefits compared to traditional approaches](/explanation/data-centric-security/traditional-vs-data-centric)
+- Explore [real-world use cases](/explanation/data-centric-security/use-cases)
\ No newline at end of file
diff --git a/docs/explanation/index.mdx b/docs/explanation/index.mdx
new file mode 100644
index 0000000..b29d84a
--- /dev/null
+++ b/docs/explanation/index.mdx
@@ -0,0 +1,54 @@
+---
+sidebar_position: 1
+---
+
+import Cards from "@site/src/components/Cards";
+
+# Understanding OpenTDF
+
+OpenTDF is a comprehensive platform for implementing **data-centric security** using **zero-trust principles**. This section explains the fundamental concepts that make OpenTDF unique and powerful for protecting sensitive data throughout its lifecycle.
+
+## Core Concepts
+
+<Cards
+  height={280}
+  columns={2}
+  items={[
+    {
+      name: "Data-Centric Security",
+      description: "Learn how OpenTDF shifts security from perimeter-based to data-focused protection, where policies travel with the data wherever it goes.",
+      url: "/explanation/data-centric-security",
+    },
+    {
+      name: "Trusted Data Format (TDF)",
+      description: "Understand how TDF cryptographically binds access control policies to data objects, creating self-protecting data.",
+      url: "/explanation/trusted-data-format",
+    },
+    {
+      name: "Attribute-Based Access Control",
+      description: "Explore how ABAC enables fine-grained, flexible access control using attributes, policies, and entitlements.",
+      url: "/reference/specifications/concepts/access_control",
+    },
+    {
+      name: "Platform Architecture",
+      description: "Discover how OpenTDF's four core services work together to implement the NIST ABAC model for data protection.",
+      url: "/explanation/platform-architecture",
+    },
+  ]}
+/>
+
+## Why OpenTDF Matters
+
+In traditional security models, once data leaves a secure perimeter, control is often lost. OpenTDF changes this by:
+
+- **Binding policy to data**: Access controls are cryptographically attached to data objects
+- **Enabling zero-trust data**: Data remains protected regardless of where it travels
+- **Providing granular control**: Fine-tuned access decisions based on context and attributes
+- **Maintaining compliance**: Comprehensive audit trails and policy enforcement
+
+## Next Steps
+
+1. **New to data-centric security?** Start with [Data-Centric Security](/explanation/data-centric-security)
+2. **Want to understand TDF?** Read about the [Trusted Data Format](/explanation/trusted-data-format)  
+3. **Ready to try it?** Jump to our [first tutorial](/tutorials/your-first-tdf)
+4. **Need specific help?** Check our [how-to guides](/how-to)
\ No newline at end of file
diff --git a/docs/explanation/platform-architecture/_category_.json b/docs/explanation/platform-architecture/_category_.json
new file mode 100644
index 0000000..21b42b4
--- /dev/null
+++ b/docs/explanation/platform-architecture/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Platform Architecture",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Understand how OpenTDF's core services work together to implement data-centric security using the NIST ABAC model."
+  }
+}
\ No newline at end of file
diff --git a/docs/architecture.mdx b/docs/explanation/platform-architecture/index.md
similarity index 100%
rename from docs/architecture.mdx
rename to docs/explanation/platform-architecture/index.md
diff --git a/docs/explanation/trusted-data-format/_category_.json b/docs/explanation/trusted-data-format/_category_.json
new file mode 100644
index 0000000..7da2582
--- /dev/null
+++ b/docs/explanation/trusted-data-format/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Trusted Data Format",
+  "position": 2,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn how the Trusted Data Format (TDF) cryptographically binds access control policies to data objects."
+  }
+}
\ No newline at end of file
diff --git a/docs/explanation/trusted-data-format/index.md b/docs/explanation/trusted-data-format/index.md
new file mode 100644
index 0000000..0a96926
--- /dev/null
+++ b/docs/explanation/trusted-data-format/index.md
@@ -0,0 +1,127 @@
+# What is the Trusted Data Format (TDF)?
+
+The **Trusted Data Format (TDF)** is the core innovation that makes data-centric security possible. TDF is a standardized container format that cryptographically binds access control policies directly to encrypted data, creating **self-protecting data objects**.
+
+## The Core Concept
+
+Traditional file encryption separates the encrypted data from access controls. TDF changes this by creating a single package that contains:
+
+1. **Encrypted payload** - The actual data, encrypted with strong cryptography
+2. **Policy object** - Access control rules defining who can decrypt the data  
+3. **Key access information** - References to keys and key servers
+4. **Metadata** - Additional information about the data and its protection
+
+```mermaid
+graph TD
+    subgraph "TDF File"
+        PAYLOAD[🔒 Encrypted Data]
+        POLICY[📋 Access Policy]
+        KEYINFO[🔑 Key Access Info]
+        METADATA[ℹ️ Metadata]
+    end
+    
+    POLICY -.-> PAYLOAD
+    KEYINFO -.-> PAYLOAD
+    METADATA -.-> PAYLOAD
+    
+    classDef tdf fill:#87CEEB,stroke:#4682B4,stroke-width:2px
+    class PAYLOAD,POLICY,KEYINFO,METADATA tdf
+```
+
+## How TDF Works
+
+When someone tries to access a TDF file, here's what happens:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant TDF as TDF File
+    participant KAS as Key Access Server
+    participant AuthZ as Authorization Service
+    
+    User->>TDF: Open TDF file
+    TDF->>User: Extract policy & key info
+    User->>KAS: Request decryption key
+    KAS->>AuthZ: Check authorization
+    AuthZ->>AuthZ: Evaluate policy against user attributes
+    AuthZ-->>KAS: Decision (grant/deny)
+    
+    alt Authorized
+        KAS-->>User: Return decryption key
+        User->>TDF: Decrypt with key
+        TDF-->>User: Decrypted data
+    else Denied
+        KAS-->>User: Access denied
+    end
+```
+
+## Key Benefits of TDF
+
+### 1. **Policy Travels with Data**
+Unlike traditional access controls that exist separately from data, TDF embeds the policy directly in the file. The policy goes wherever the data goes - shared folders, email attachments, cloud storage, partner networks.
+
+### 2. **Fine-Grained Access Control**
+TDF policies use **Attribute-Based Access Control (ABAC)** to make nuanced decisions based on:
+- User attributes (role, clearance, department)
+- Environmental context (location, time, device)
+- Data classifications (sensitivity, project, compliance requirements)
+
+### 3. **Real-Time Policy Updates**
+Even after a TDF is created and shared, policies can be updated in real-time:
+- Revoke access immediately if needed
+- Add new authorized users
+- Change access conditions (e.g., restrict to business hours)
+- Add obligations (e.g., watermarking requirements)
+
+### 4. **Complete Audit Trail**
+Every access attempt is logged, providing:
+- Who tried to access what data
+- When and from where
+- Whether access was granted or denied
+- What actions were performed
+
+## TDF vs. NanoTDF
+
+OpenTDF supports two format variants:
+
+| Feature | **TDF (Full Format)** | **NanoTDF (Compact)** |
+|---------|----------------------|------------------------|
+| **Size Overhead** | ~1KB | ~50 bytes |
+| **Best For** | Files, documents | IoT, streaming, embedded |
+| **Policy Features** | Full ABAC policies | Simple attribute checks |
+| **Key Management** | Full key splitting | Simplified key handling |
+| **Use Cases** | Document protection, file sharing | Sensor data, real-time streams |
+
+## Real-World Example
+
+Consider a medical research document:
+
+**Without TDF (Traditional):**
+- File encrypted with password or certificate
+- Access rules stored separately in system permissions
+- If shared outside system → no access control
+- No audit trail for external access
+
+**With TDF:**
+- File packaged as TDF with policy: "Only researchers with IRB approval can access"
+- Policy includes obligations: "Must watermark with user ID"
+- File can be safely shared with external partners
+- All access attempts logged regardless of location
+- Access can be revoked instantly if needed
+
+## Standards and Interoperability
+
+TDF is built on open standards:
+- **JSON-based manifest** for policy definition
+- **Standard encryption algorithms** (AES, RSA, ECC)
+- **NIST ABAC model** for access control
+- **Open specification** for vendor interoperability
+
+This ensures that TDF files can be processed by different implementations and integrated into existing security infrastructure.
+
+## Next Steps
+
+- Learn about [cryptographic binding](/explanation/trusted-data-format/cryptographic-binding) in detail
+- Understand the [TDF vs NanoTDF comparison](/explanation/trusted-data-format/tdf-vs-nanotdf)
+- See the complete [TDF lifecycle](/explanation/trusted-data-format/tdf-lifecycle) from creation to consumption
+- Try creating your first TDF in our [tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
diff --git a/docs/getting-started/_category_.yaml b/docs/getting-started/_category_.yaml
deleted file mode 100644
index 951e677..0000000
--- a/docs/getting-started/_category_.yaml
+++ /dev/null
@@ -1 +0,0 @@
-position: 2
diff --git a/docs/how-to/_category_.json b/docs/how-to/_category_.json
new file mode 100644
index 0000000..8fdca4a
--- /dev/null
+++ b/docs/how-to/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "How-to Guides",
+  "position": 3,
+  "link": {
+    "type": "generated-index",
+    "description": "Practical guides for specific problems and tasks. Find recipes for deployment, integration, troubleshooting, and common use cases."
+  },
+  "collapsible": true,
+  "collapsed": true
+}
\ No newline at end of file
diff --git a/docs/how-to/index.mdx b/docs/how-to/index.mdx
new file mode 100644
index 0000000..1549aa3
--- /dev/null
+++ b/docs/how-to/index.mdx
@@ -0,0 +1,38 @@
+---
+sidebar_position: 1
+---
+
+import Cards from "@site/src/components/Cards";
+
+# How-to Guides
+
+Practical guides for specific tasks like deployment, integration, troubleshooting, and common use cases. These goal-oriented guides assume you understand the basic concepts and provide step-by-step instructions to solve real problems.
+
+## SDK Integration
+
+<Cards
+  height={280}
+  columns={1}
+  items={[
+    {
+      name: "SDK Recipes",
+      description: "Code examples and patterns for integrating OpenTDF SDKs into your applications. Learn how to encrypt, decrypt, and manage TDF files programmatically.",
+      url: "/how-to/sdk-recipes",
+    },
+  ]}
+/>
+
+## Coming Soon
+
+More how-to guides covering:
+
+- **Deployment**: Setting up OpenTDF in production environments
+- **Configuration**: Configuring services for different use cases
+- **Troubleshooting**: Solving common issues and debugging problems
+- **Integration**: Connecting OpenTDF with existing systems
+
+## Need Different Information?
+
+- **Learning the concepts?** Start with our [explanation section](/explanation)
+- **Following a tutorial?** Check our [step-by-step tutorials](/tutorials)
+- **Looking for reference details?** Visit our [API documentation](/reference)
\ No newline at end of file
diff --git a/docs/sdks/_category_.json b/docs/how-to/sdk-recipes/_category_.json
similarity index 100%
rename from docs/sdks/_category_.json
rename to docs/how-to/sdk-recipes/_category_.json
diff --git a/docs/sdks/authorization.mdx b/docs/how-to/sdk-recipes/authorization.mdx
similarity index 100%
rename from docs/sdks/authorization.mdx
rename to docs/how-to/sdk-recipes/authorization.mdx
diff --git a/docs/how-to/sdk-recipes/index.mdx b/docs/how-to/sdk-recipes/index.mdx
new file mode 100644
index 0000000..3924a86
--- /dev/null
+++ b/docs/how-to/sdk-recipes/index.mdx
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+import Cards from "@site/src/components/Cards";
+
+# SDK Recipes
+
+Code examples and patterns for integrating OpenTDF SDKs into your applications. These practical recipes show you how to encrypt, decrypt, and manage TDF files programmatically using the OpenTDF SDKs.
+
+## Available Recipes
+
+<Cards
+  height={280}
+  columns={2}
+  items={[
+    {
+      name: "Overview",
+      description: "Getting started with OpenTDF SDKs, installation, and basic setup patterns across different languages.",
+      url: "/how-to/sdk-recipes/overview",
+    },
+    {
+      name: "TDF Operations", 
+      description: "Creating, encrypting, and decrypting TDF files. Learn the core operations for protecting your data.",
+      url: "/how-to/sdk-recipes/tdf",
+    },
+    {
+      name: "Policy Management",
+      description: "Working with attributes, policies, and access controls through the SDK. Define who can access your data.",
+      url: "/how-to/sdk-recipes/policy",
+    },
+    {
+      name: "Authorization",
+      description: "Implementing authorization flows, handling entitlements, and managing access decisions in your applications.",
+      url: "/how-to/sdk-recipes/authorization",
+    },
+  ]}
+/>
+
+## Getting Started
+
+1. **Start with [Overview](/how-to/sdk-recipes/overview)** to understand SDK basics and setup
+2. **Learn [TDF Operations](/how-to/sdk-recipes/tdf)** to protect your first data file  
+3. **Explore [Policy Management](/how-to/sdk-recipes/policy)** to control access to your data
+4. **Implement [Authorization](/how-to/sdk-recipes/authorization)** for production applications
+
+## Need Different Information?
+
+- **New to the concepts?** Check our [explanation section](/explanation) first
+- **Following a tutorial?** Try our [step-by-step tutorials](/tutorials)
+- **Looking for API details?** Visit the [API reference](/reference)
\ No newline at end of file
diff --git a/docs/sdks/overview.mdx b/docs/how-to/sdk-recipes/overview.mdx
similarity index 85%
rename from docs/sdks/overview.mdx
rename to docs/how-to/sdk-recipes/overview.mdx
index 8b4e6eb..342e438 100644
--- a/docs/sdks/overview.mdx
+++ b/docs/how-to/sdk-recipes/overview.mdx
@@ -6,7 +6,7 @@ sidebar_position: 1
 
 OpenTDF supports native SDKs in the Go, Java and JavaScript languages. 
 
-Please refer to the [SDK Feature Matrix](../appendix/matrix.mdx#sdk) in the Appendix for the supported features in each SDK.
+Please refer to the [SDK Feature Matrix](../../appendix/matrix.mdx#sdk) in the Appendix for the supported features in each SDK.
 
 ## Repositories
 
diff --git a/docs/how-to/sdk-recipes/policy.mdx b/docs/how-to/sdk-recipes/policy.mdx
new file mode 100644
index 0000000..beab7c3
--- /dev/null
+++ b/docs/how-to/sdk-recipes/policy.mdx
@@ -0,0 +1,35 @@
+---
+sidebar_position: 3
+---
+
+import CreateNamespace from '../../../code_samples/policy_code/create_namespace.mdx'
+import ListNamespaces from '../../../code_samples/policy_code/list_namespaces.mdx'
+import CreateAttribute from '../../../code_samples/policy_code/create_attribute.mdx'
+import ListAttributes from '../../../code_samples/policy_code/list_attributes.mdx'
+import CreateConditionSet from '../../../code_samples/policy_code/create_subject_condition_set.mdx'
+import CreateSubjectMapping from '../../../code_samples/policy_code/create_subject_mapping.mdx'
+import ListSubjectMapping from '../../../code_samples/policy_code/list_subject_mapping.mdx'
+
+
+
+
+
+
+
+
+# Managing Policy
+
+<CreateNamespace />
+
+<ListNamespaces />
+
+<CreateAttribute />
+
+<ListAttributes />
+
+<CreateConditionSet />
+
+<CreateSubjectMapping />
+
+<ListSubjectMapping />
+
diff --git a/docs/how-to/sdk-recipes/tdf.mdx b/docs/how-to/sdk-recipes/tdf.mdx
new file mode 100644
index 0000000..be69b96
--- /dev/null
+++ b/docs/how-to/sdk-recipes/tdf.mdx
@@ -0,0 +1,10 @@
+---
+sidebar_position: 4
+---
+
+import EncryptionTDF from '../../../code_samples/tdf/encryption_ztdf.mdx'
+
+
+# Creating TDF's
+
+<EncryptionTDF />
\ No newline at end of file
diff --git a/docs/index.mdx b/docs/index.mdx
new file mode 100644
index 0000000..35fab27
--- /dev/null
+++ b/docs/index.mdx
@@ -0,0 +1,186 @@
+---
+sidebar_position: 1
+title: OpenTDF - Protect the Data, Build the Future
+description: Persistent data centric security that extends owner control wherever data travels.
+keywords:
+  - data-centric security
+  - zero trust
+  - trusted data format
+  - TDF
+  - ABAC
+  - attribute-based access control
+  - OpenTDF
+---
+
+import React from "react";
+import Callout from "@site/src/components/Callout";
+import Cards from "@site/src/components/Cards";
+
+<div className="hero hero--primary">
+  <div className="container">
+    <div className="row">
+      <div className="col col--8 col--offset-2">
+        <h1 className="hero__title">OpenTDF: A toolkit for zero trust, data-centric security</h1>
+        <p className="hero__subtitle">
+          <strong>OpenTDF</strong> is an open source system for implementing data centric security. 
+          It provides the basic services required to enable the definition, application, 
+          and enforcement of attribute based policies using the Trust Data Format (TDF). 
+          TDF is an open standard that enables you to cryptographically bind 
+          attribute based access control (ABAC) policy to a data object so that 
+          the policy travels with the data wherever it goes.
+        </p>
+        <p className="hero__subtitle">
+          OpenTDF builds upon <strong>a decade of experience at Virtru</strong> 
+          protecting data objects at scale using the Trusted Data Format 
+          for organizations of all sizes and across all industries.
+        </p>
+        <div className="hero__cta">
+          <a className="button button--secondary button--lg" href="/tutorials/your-first-tdf">
+            Get Started
+          </a>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>
+
+<div style={{padding: '4rem 0'}}>
+
+## Find What You Need
+
+<Cards
+  height={320}
+  columns={2}
+  items={[
+    {
+      name: "📚 Understanding",
+      description: "Learn the core concepts behind OpenTDF, data-centric security, and how the platform implements zero-trust data protection.",
+      url: "/explanation",
+      accentColor: "primary"
+    },
+    {
+      name: "🎯 Learn Step-by-Step", 
+      description: "Hands-on tutorials that teach you to use OpenTDF progressively, from your first TDF to building secure applications.",
+      url: "/tutorials",
+      accentColor: "secondary"
+    },
+    {
+      name: "🔧 Solve Problems",
+      description: "Practical guides for specific tasks like deployment, integration, troubleshooting, and common use cases.",
+      url: "/how-to",
+      accentColor: "success"
+    },
+    {
+      name: "📖 Reference",
+      description: "Complete API documentation, specifications, CLI commands, SDK references, and configuration details.",
+      url: "/reference", 
+      accentColor: "info"
+    },
+  ]}
+/>
+
+## Quick Start Paths
+
+<Callout
+  title="New to Data-Centric Security?"
+  callToAction={{
+    label: "Start with Concepts",
+    link: "/explanation",
+  }}
+>
+  Begin by understanding what makes OpenTDF unique and how it solves data protection challenges that traditional security models can't address.
+</Callout>
+
+<Callout
+  title="Ready to Try OpenTDF?"
+  callToAction={{
+    label: "Start Your First Tutorial",
+    link: "/tutorials/your-first-tdf",
+  }}
+>
+  Jump into a hands-on tutorial that walks you through setting up OpenTDF locally and creating your first protected data file.
+</Callout>
+
+<Callout
+  title="Need to Solve a Specific Problem?"
+  callToAction={{
+    label: "Browse How-to Guides",
+    link: "/how-to",
+  }}
+>
+  Find practical recipes for deployment, integration, policy management, and troubleshooting common issues.
+</Callout>
+
+## Why Zero Trust and OpenTDF?
+
+Today's cybersecurity landscape is increasingly adopting and requiring **Zero Trust models and frameworks**. Zero Trust operates on the principle of "never trust, always verify," ensuring that every access request is authenticated, authorized, and encrypted, regardless of its origin. 
+
+**OpenTDF implements this model** by providing an open-source framework, specification, and set of services that prioritizes the protection and integrity of data at every stage. By integrating OpenTDF's data security features with a Zero Trust architecture, organizations can:
+
+- **Enforce strict access controls** with attribute-based policies
+- **Ensure data is continuously monitored** throughout its lifecycle
+- **Maintain comprehensive visibility** into data interactions
+- **Minimize the risk of data breaches** through cryptographic binding
+- **Foster a secure environment** where data can be shared and utilized with confidence
+
+Together, Zero Trust and OpenTDF empower businesses to uphold the highest standards of data security in an interconnected world.
+
+## Project Overview and Current State
+
+In 2023, the OpenTDF team undertook a **significant re-architecture** of the OpenTDF platform to enhance its extensibility and interoperability, responding to the evolving needs of our diverse user base and the dynamic cybersecurity landscape. See our [GitHub Organization Page](https://github.com/opentdf/) to navigate the new repositories.
+
+This comprehensive overhaul involved:
+- **Simplifying core service components** for better maintainability
+- **Adopting standardized policy schemas** for interoperability  
+- **Improving platform APIs and SDKs** in both developer experience and capability
+- **Focusing on extensibility** to enable customization for specific use cases
+
+Through the sponsorship of **Virtru** and its partners, the OpenTDF project has been meeting the needs of customers across industries and use cases. Check out [Virtru Data Security Platform](https://www.virtru.com/data-security-platform) for more.
+
+## What Makes OpenTDF Different
+
+- **Policy Travels with Data**: Unlike traditional access controls, TDF policies are cryptographically bound to the data itself
+- **Zero-Trust by Design**: Data remains protected regardless of network boundaries or storage location  
+- **Fine-Grained Control**: Attribute-based access control enables precise, contextual authorization decisions
+- **Standards-Based**: Built on the proven NIST ABAC model for interoperability and compliance
+- **Developer-Friendly**: SDKs for Go, Java, and JavaScript make integration straightforward
+
+## OpenTDF in Action
+
+Ideas for leveraging OpenTDF in your own applications:
+
+<Cards
+  height={280}
+  columns={2}
+  items={[
+    {
+      name: "🔒 Secure IoT Sensor Data",
+      description: "From full-motion video to biometric devices, attach access controls and preserve data integrity to guard against data spoofing.",
+      url: "/explanation",
+      accentColor: "primary"
+    },
+    {
+      name: "🤝 Secure Data Sharing",
+      description: "Securely share data with partners, customers, and suppliers, and maintain control over who can access it.",
+      url: "/explanation",
+      accentColor: "secondary"
+    },
+  ]}
+/>
+
+## Join Our Community
+
+Virtru, the sponsor of the OpenTDF developer community, would love to hear from you! We're developers, too, and as we mature the project, we're curious what you're building, and what kind of problems you may be encountering or are trying to solve.
+
+You can provide anonymous feedback or share your contact information for access to curated resources, updates, and responses to your questions.
+
+- **🗣️ [GitHub Discussions](https://github.com/orgs/opentdf/discussions)** - Join conversations with the community
+- **📝 [Share Feedback](https://www.virtru.com/feedback)** - Help us improve OpenTDF
+- **🚀 [Showcase](https://github.com/orgs/opentdf/discussions/categories/show-and-tell)** - Show what you're building
+- **🗺️ [Roadmap](https://github.com/orgs/opentdf/discussions/1806)** - See what's coming next
+
+---
+
+**Ready to protect your data?** Choose your path above and start building with OpenTDF.
+
+</div>
diff --git a/docs/introduction.mdx b/docs/introduction.mdx
deleted file mode 100644
index 7d3afb2..0000000
--- a/docs/introduction.mdx
+++ /dev/null
@@ -1,88 +0,0 @@
----
-sidebar_position: 1
----
-
-import React from "react";
-import Callout from "@site/src/components/Callout";
-import Cards from "@site/src/components/Cards";
-
-# Welcome to OpenTDF Docs
-
-Find all the information you need to get started with OpenTDF.
-
-<Callout
-  title="Quick Start"
-  callToAction={{
-    label: "Learn more",
-    link: "/getting-started",
-  }}
->
-  This guide will walk you through setting up a new OpenTDF platform locally and
-  walk you through some of the basic concepts within the OpenTDF platform.
-</Callout>
-
-<Callout
-  title="Architecture"
-  callToAction={{
-    label: "Learn more",
-    link: "/architecture",
-  }}
->
-  Learn about the core components of the OpenTDF platform and how they work together in a standards-based architecture.
-</Callout>
-
-<Cards
-  height={300}
-  columns={3}
-  items={[
-    {
-      name: "TDF",
-      description: `
-        The Trust Data Format (TDF) is an open standard that enables the cryptographic binding ofattribute-based
-         access control (ABAC) policy to a data object so that the policy travels with the data.`,
-      url: "/spec/schema/opentdf",
-    },
-    {
-      name: "Policy",
-      description: `The OpenTDF Policy engine enables creation, enforcement, and subscription to policies using attribute-based access control (ABAC) to enforce flexible, fine-grained access control.`,
-      url: "/components/policy",
-    },
-    {
-      name: "Authorization",
-      description: `The Authorization service enables policy driven, access based decisions using entity entitlements to enforce consistent data privacy and application security.`,
-      url: "/components/authorization",
-    },
-    {
-      name: "Key Access",
-      description: "The Key Access service manages the cryptographic keys required for TDF encryption and decryption, enforcing access control decisions by granting or denying key requests.",
-      url: "/components/key_access",
-    },
-    {
-      name: "Entity Resolution",
-      description: "The Entity Resolution service gathers and resolves entity attributes from various sources, providing the context needed for the Authorization service to make decisions.",
-      url: "/components/entity_resolution",
-    },
-  ]}
-/>
-
-### Explore by Feature
-
-<Cards
-  accentColor="secondary"
-  height={200}
-  columns={2}
-  items={[
-    {
-      name: "SDK",
-      description:
-        "Learn about the Trust Data Format (TDF) and how it enables the cryptographic binding of attribute-based access control (ABAC) policy to a data object.",
-      url: "/category/sdk",
-    },
-    {
-      name: "CLI",
-      description:
-        "Learn about the OpenTDF CLI tool (otdfctl) and how it can be used to manage the OpenTDF platform.",
-      url: "/components/cli",
-    },
-  ]}
-/>
\ No newline at end of file
diff --git a/docs/reference/_category_.json b/docs/reference/_category_.json
new file mode 100644
index 0000000..9d475cf
--- /dev/null
+++ b/docs/reference/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Reference",
+  "position": 4,
+  "link": {
+    "type": "generated-index",
+    "description": "Comprehensive reference material including API documentation, specifications, CLI commands, SDK references, and configuration details."
+  },
+  "collapsible": true,
+  "collapsed": true
+}
\ No newline at end of file
diff --git a/docs/reference/index.mdx b/docs/reference/index.mdx
new file mode 100644
index 0000000..9bd888c
--- /dev/null
+++ b/docs/reference/index.mdx
@@ -0,0 +1,51 @@
+---
+sidebar_position: 1
+---
+
+import Cards from "@site/src/components/Cards";
+
+# Reference Documentation
+
+Complete API documentation, specifications, CLI commands, SDK references, and configuration details. This section provides comprehensive technical information for developers and system administrators.
+
+## API Documentation
+
+<Cards
+  height={280}
+  columns={2}
+  items={[
+    {
+      name: "Platform APIs",
+      description: "Complete REST API reference for all OpenTDF platform services including policy management, authorization, and key access.",
+      url: "/reference/api",
+    },
+    {
+      name: "Specifications",
+      description: "Technical specifications for the OpenTDF format, protocol, and schemas. Essential for implementers and integrators.",
+      url: "/reference/specifications",
+    },
+  ]}
+/>
+
+## Available References
+
+### Platform APIs
+- **Policy Service**: Manage attributes, namespaces, and access policies  
+- **Authorization Service**: Handle access decisions and entitlements
+- **Key Access Service**: Control cryptographic key distribution
+- **Entity Resolution**: Map entities to attributes for authorization
+
+### Specifications
+- **TDF Format**: Technical specification for Trusted Data Format files
+- **Protocol**: Communication protocols between platform services  
+- **Schema**: JSON schemas and data structure definitions
+- **Concepts**: Detailed explanations of core platform concepts
+
+### CLI Tools
+- **otdfctl**: Command-line interface documentation and examples
+
+## Need Different Information?
+
+- **Learning the concepts?** Start with our [explanation section](/explanation)
+- **Following a tutorial?** Check our [step-by-step tutorials](/tutorials) 
+- **Looking for practical examples?** Visit our [how-to guides](/how-to)
\ No newline at end of file
diff --git a/docs/sdks/policy.mdx b/docs/sdks/policy.mdx
deleted file mode 100644
index 3b273e4..0000000
--- a/docs/sdks/policy.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-sidebar_position: 3
----
-
-import CreateNamespace from '../../code_samples/policy_code/create_namespace.mdx'
-import ListNamespaces from '../../code_samples/policy_code/list_namespaces.mdx'
-import CreateAttribute from '../../code_samples/policy_code/create_attribute.mdx'
-import ListAttributes from '../../code_samples/policy_code/list_attributes.mdx'
-import CreateConditionSet from '../../code_samples/policy_code/create_subject_condition_set.mdx'
-import CreateSubjectMapping from '../../code_samples/policy_code/create_subject_mapping.mdx'
-import ListSubjectMapping from '../../code_samples/policy_code/list_subject_mapping.mdx'
-
-
-
-
-
-
-
-
-# Managing Policy
-
-<CreateNamespace />
-
-<ListNamespaces />
-
-<CreateAttribute />
-
-<ListAttributes />
-
-<CreateConditionSet />
-
-<CreateSubjectMapping />
-
-<ListSubjectMapping />
-
diff --git a/docs/sdks/tdf.mdx b/docs/sdks/tdf.mdx
deleted file mode 100644
index 0c44178..0000000
--- a/docs/sdks/tdf.mdx
+++ /dev/null
@@ -1,10 +0,0 @@
----
-sidebar_position: 4
----
-
-import EncryptionTDF from '../../code_samples/tdf/encryption_ztdf.mdx'
-
-
-# Creating TDF's
-
-<EncryptionTDF />
\ No newline at end of file
diff --git a/docs/tutorials/_category_.json b/docs/tutorials/_category_.json
new file mode 100644
index 0000000..7dd6574
--- /dev/null
+++ b/docs/tutorials/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Learn OpenTDF",
+  "position": 2,
+  "link": {
+    "type": "generated-index", 
+    "description": "Step-by-step tutorials that teach you to use OpenTDF. Start here if you're new to data-centric security or want to build your skills progressively."
+  },
+  "collapsible": true,
+  "collapsed": false
+}
\ No newline at end of file
diff --git a/docs/tutorials/index.mdx b/docs/tutorials/index.mdx
new file mode 100644
index 0000000..7894ae1
--- /dev/null
+++ b/docs/tutorials/index.mdx
@@ -0,0 +1,34 @@
+---
+sidebar_position: 1
+---
+
+import Cards from "@site/src/components/Cards";
+
+# Learn OpenTDF
+
+Step-by-step tutorials that teach you to use OpenTDF. Start here if you're new to data-centric security or want to build your skills progressively.
+
+## Available Tutorials
+
+<Cards
+  height={280}
+  columns={1}
+  items={[
+    {
+      name: "Your First TDF",
+      description: "Get hands-on experience creating and decrypting your first Trusted Data Format file. Learn the basics of data-centric security by protecting a simple text file.",
+      url: "/tutorials/your-first-tdf",
+    },
+  ]}
+/>
+
+## Learning Path
+
+1. **Start Here**: [Your First TDF](/tutorials/your-first-tdf) - Learn the fundamentals by creating your first protected data file
+2. **Coming Soon**: More tutorials covering advanced topics like policy management, SDK integration, and production deployments
+
+## Need Help?
+
+- **New to the concepts?** Start with our [explanation section](/explanation) to understand the theory behind data-centric security
+- **Looking for specific solutions?** Check our [how-to guides](/how-to) for practical recipes
+- **Need reference information?** Visit our [API documentation](/reference) for complete technical details
\ No newline at end of file
diff --git a/docs/tutorials/your-first-tdf/_category_.json b/docs/tutorials/your-first-tdf/_category_.json
new file mode 100644
index 0000000..8f545ac
--- /dev/null
+++ b/docs/tutorials/your-first-tdf/_category_.json
@@ -0,0 +1,8 @@
+{
+  "label": "Your First TDF",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Learn OpenTDF by creating your first Trusted Data Format file. This tutorial walks you through setting up the platform, creating policies, and encrypting data."
+  }
+}
\ No newline at end of file
diff --git a/docs/tutorials/your-first-tdf/configuration.md b/docs/tutorials/your-first-tdf/configuration.md
new file mode 100644
index 0000000..45f4461
--- /dev/null
+++ b/docs/tutorials/your-first-tdf/configuration.md
@@ -0,0 +1,433 @@
+---
+id: configuration
+sidebar_position: 20
+title: Configuration
+---
+
+# Platform Configuration
+
+This guide provides details about the configuration setup for the platform, including the logger, services , and server configurations.
+
+The platform leverages [viper](https://github.com/spf13/viper) to help load configuration.
+
+- [Platform Configuration](#platform-configuration)
+  - [Deployment Mode](#deployment-mode)
+    - [Service Negation](#service-negation)
+  - [SDK Configuration](#sdk-configuration)
+  - [Logger Configuration](#logger-configuration)
+  - [Server Configuration](#server-configuration)
+    - [Crypto Provider](#crypto-provider)
+  - [Database Configuration](#database-configuration)
+    - [Tracing Configuration](#tracing-configuration)
+  - [Services Configuration](#services-configuration)
+    - [Key Access Server (KAS)](#key-access-server-kas)
+    - [Authorization](#authorization)
+    - [Policy](#policy)
+    - [Casbin Endpoint Authorization](#casbin-endpoint-authorization)
+      - [Key Aspects of Authorization Configuration](#key-aspects-of-authorization-configuration)
+      - [Configuration in opentdf-example.yaml](#configuration-in-opentdf-exampleyaml)
+      - [Role Permissions](#role-permissions)
+      - [Managing Authorization Policy](#managing-authorization-policy)
+  - [Cache Configuration](#cache-configuration)
+
+## Deployment Mode
+
+The platform is designed as a modular monolith, meaning that all services are built into and run from the same binary. However, these services can be grouped and run together based on specific needs. The available service groups are:
+
+- all: Runs every service that is registered within the platform.
+- core: Runs essential services, including policy, authorization, and wellknown services.
+- kas: Runs the Key Access Server (KAS) service.
+
+### Service Negation
+
+You can exclude specific services from any mode using the negation syntax `-servicename`:
+
+- **Syntax**: `mode: <base-mode>,-<service1>,-<service2>`
+- **Constraint**: At least one positive mode must be specified (negation-only modes like `-kas` will result in an error)
+- **Available services**: `policy`, `authorization`, `kas`, `entityresolution`, `wellknown`
+
+**Examples:**
+```yaml
+# Run all services except Entity Resolution Service
+mode: all,-entityresolution
+
+# Run core services except Policy Service  
+mode: core,-policy
+
+# Run all services except both KAS and Entity Resolution
+mode: all,-kas,-entityresolution
+```
+
+| Field  | Description                                                                   | Default | Environment Variable |
+| ------ | ----------------------------------------------------------------------------- | ------- | -------------------- |
+| `mode` | Drives which services to run. Supported modes: `all`, `core`, `kas`. Use `-servicename` to exclude specific services (e.g., `all,-entityresolution`) | `all`   | OPENTDF_MODE         |
+
+## SDK Configuration
+
+The sdk configuration is used when operating the service in mode `kas`. When running in mode `core` or `all` an in-process communication is leveraged over an in-memory grpc server.
+
+Root level key `sdk_config`
+
+| Field                        | Description                                 | Default | Environment Variable             |
+| ---------------------------- | ------------------------------------------- | ------- | -------------------------------- |
+| `core.endpoint`              | The core platform endpoint to connect to    |         | OPENTDF_SDK_CONFIG_ENDPOINT      |
+| `core.plaintext`             | Use a plaintext grpc connection             | `false` | OPENTDF_SDK_CONFIG_PLAINTEXT     |
+| `core.insecure`              | Use an insecure tls connection              | `false` |                                  |
+| `entityresolution.endpoint`  | The entityresolution endpoint to connect to |         |                                  |
+| `entityresolution.plaintext` | Use a plaintext ERS grpc connection         | `false` |                                  |
+| `entityresolution.insecure`  | Use an insecure tls connection              | `false` |                                  |
+| `client_id`                  | OAuth client id                             |         | OPENTDF_SDK_CONFIG_CLIENT_ID     |
+| `client_secret`              | The clients credentials                     |         | OPENTDF_SDK_CONFIG_CLIENT_SECRET |
+
+## Logger Configuration
+
+The logger configuration is used to define how the application logs its output.
+
+Root level key `logger`
+
+| Field    | Description                      | Default  | Environment Variable  |
+| -------- | -------------------------------- | -------- | --------------------- |
+| `level`  | The logging level.               | `info`   | OPENTDF_LOGGER_LEVEL  |
+| `type`   | The format of the log output.    | `json`   | OPENTDF_LOGGER_TYPE   |
+| `output` | The output destination for logs. | `stdout` | OPENTDF_LOGGER_OUTPUT |
+
+Example:
+
+```yaml
+logger:
+  level: debug
+  type: text
+  output: stdout
+```
+
+## Server Configuration
+
+The server configuration is used to define how the application runs its server.
+
+Root level key `server`
+
+| Field                   | Description                                                                                                   | Default | Environment Variable                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------- | ------- | ------------------------------------ |
+| `auth.audience`         | The audience for the IDP.                                                                                     |         | OPENTDF_SERVER_AUTH_AUDIENCE         |
+| `auth.issuer`           | The issuer for the IDP.                                                                                       |         | OPENTDF_SERVER_AUTH_ISSUER           |
+| `auth.policy`           | The Casbin policy for enforcing authorization on endpoints. Described [below](#casbin-endpoint-authorization) |         |                                      |
+| `auth.cache_refresh`    | Interval in which the IDP jwks should be refreshed                                                            | `15m`   | OPENTDF_SERVER_AUTH_CACHE_REFRESH    |
+| `auth.dpopskew`         | The amount of time drift allowed between when the client generated a dpop proof and the server time.          | `1h`    | OPENTDF_SERVER_AUTH                  |
+| `auth.skew`             | The amount of time drift allowed between a tokens `exp` claim and the server time.                            | `1m`    | OPENTDF_SERVER_AUTH_SKEW             |
+| `auth.public_client_id` | [DEPRECATED] The oidc client id. This is leveraged by otdfctl.                                                |         | OPENTDF_SERVER_AUTH_PUBLIC_CLIENT_ID |
+| `auth.enforceDPoP`      | If true, DPoP bindings on Access Tokens are enforced.                                                         | `false` | OPENTDF_SERVER_AUTH_ENFORCEDPOP      |
+| `cryptoProvider`        | A list of public/private keypairs and their use. Described [below](#crypto-provider)                          | empty   |                                      |
+| `enable_pprof`          | Enable golang performance profiling                                                                           | `false` | OPENTDF_SERVER_ENABLE_PPROF          |
+| `grpc.reflection`       | The configuration for the grpc server.                                                                        | `true`  | OPENTDF_SERVER_GRPC_REFLECTION       |
+| `public_hostname`       | The public facing hostname for the server.                                                                    |         | OPENTDF_SERVER_PUBLIC_HOSTNAME       |
+| `host`                  | The host address for the server.                                                                              | `""`    | OPENTDF_SERVER_HOST                  |
+| `port`                  | The port number for the server.                                                                               | `9000`  | OPENTDF_SERVER_PORT                  |
+| `tls.enabled`           | Enable tls.                                                                                                   | `false` | OPENTDF_SERVER_TLS_ENABLED           |
+| `tls.cert`              | The path to the tls certificate.                                                                              |         | OPENTDF_SERVER_TLS_CERT              |
+| `tls.key`               | The path to the tls key.                                                                                      |         | OPENTDF_SERVER_TLS_KEY               |
+
+Example:
+
+```yaml
+server:
+  grpc:
+    reflection: true
+  port: 8081
+  tls:
+    enabled: true
+    cert: /path/to/cert
+    key: /path/to/key
+  auth:
+    enabled: true
+    audience: https://example.com
+    issuer: https://example.com
+  cryptoProvider:
+    standard:
+      keys:
+        - kid: r1
+          alg: rsa:2048
+          private: kas-private.pem
+          cert: kas-cert.pem
+        - kid: e1
+          alg: ec:secp256r1
+          private: kas-ec-private.pem
+          cert: kas-ec-cert.pem
+```
+
+### Crypto Provider
+
+To configure the Key Access Server,
+you must define a set of one or more public keypairs
+and a method for loading and using them.
+
+The crypto provider is implemented as an interface,
+allowing multiple implementations.
+
+Root level key `cryptoProvider`
+
+Environment Variable: `OPENTDF_SERVER_CRYPTOPROVIDER_STANDARD='[{"alg":"rsa:2048","kid":"k1","private":"kas-private.pem","cert":"kas-cert.pem"}]'`
+
+| Field                               | Description                                                               | Default    |
+| ----------------------------------- | ------------------------------------------------------------------------- | ---------- |
+| `cryptoProvider.type`               | The type of crypto provider to use.                                       | `standard` |
+| `cryptoProvider.standard.*.alg`     | An enum for the associated crypto type. E.g. `rsa:2048` or `ec:secp256r1` |            |
+| `cryptoProvider.standard.*.kid`     | A short, globally unique, stable identifier for this keypair.             |            |
+| `cryptoProvider.standard.*.private` | Path to the private key as a PEM file.                                    |            |
+| `cryptoProvider.standard.*.cert`    | (Optional) Path to a public cert for the keypair.                         |            |
+
+## Database Configuration
+
+The database configuration is used to define how the application connects to its database.
+
+Root level key `db`
+
+| Field                                  | Description                                   | Default     | Environment Variables                           |
+| -------------------------------------- | --------------------------------------------- | ----------- | ----------------------------------------------- |
+| `host`                                 | The host address for the database.            | `localhost` | OPENTDF_DB_HOST                                 |
+| `port`                                 | The port number for the database.             | `5432`      | OPENTDF_DB_PORT                                 |
+| `database`                             | The name of the database.                     | `opentdf`   | OPENTDF_DB_DATABASE                             |
+| `user`                                 | The username for the database.                | `postgres`  | OPENTDF_DB_USER                                 |
+| `password`                             | The password for the database.                | `changeme`  | OPENTDF_DB_PASSWORD                             |
+| `sslmode`                              | The ssl mode for the database                 | `prefer`    | OPENTDF_DB_SSLMODE                              |
+| `schema`                               | The schema for the database.                  | `opentdf`   | OPENTDF_DB_SCHEMA                               |
+| `runMigration`                         | Whether to run the database migration or not. | `true`      | OPENTDF_DB_RUNMIGRATION                         |
+| `connect_timeout_seconds`              | Connection timeout duration (seconds).        | `15`        | OPENTDF_DB_CONNECT_TIMEOUT_SECONDS              |
+| `pool`                                 | Pool configuration settings.                  |             |                                                 |
+| `pool.max_connection_count`            | Maximum number of connections per pool.       | `4`         | OPENTDF_DB_POOL_MAX_CONNECTION_COUNT            |
+| `pool.min_connection_count`            | Minimum number of connections per pool.       | `0`         | OPENTDF_DB_POOL_MIN_CONNECTION_COUNT            |
+| `pool.max_connection_lifetime_seconds` | Maximum seconds per connection lifetime.      | `3600`      | OPENTDF_DB_POOL_MAX_CONNECTION_LIFETIME_SECONDS |
+| `pool.min_idle_connections_count`      | Minimum number of idle connections per pool.  | `0`         | OPENTDF_DB_POOL_MIN_IDLE_CONNECTIONS_COUNT      |
+| `pool.max_connection_idle_seconds`     | Maximum seconds allowed for idle connection.  | `1800`      | OPENTDF_DB_POOL_MAX_CONNECTION_IDLE_SECONDS     |
+| `pool.health_check_period_seconds`     | Interval seconds per health check.            | `60`        | OPENTDF_DB_POOL_HEALTH_CHECK_PERIOD_SECONDS     |
+
+
+
+
+Example:
+
+```yaml
+db:
+  host: localhost
+  port: 5432
+  database: opentdf
+  user: postgres
+  password: changeme
+  sslmode: require
+  schema: opentdf
+  runMigration: false
+  connect_timeout_seconds: 15
+  pool:
+    max_connection_count: 4
+    min_connection_count: 0
+    max_connection_lifetime_seconds: 3600
+    min_idle_connections_count: 0
+    max_connection_idle_seconds: 1800
+    health_check_period_seconds: 60
+```
+
+### Tracing Configuration
+
+| Field                 | Description                     | Default | Environment Variable               |
+| --------------------- | ------------------------------- | ------- | ---------------------------------- |
+| `trace.enabled`       | Enable distributed tracing      | `false` | OPENTDF_SERVER_TRACE_ENABLED       |
+| `trace.provider.name` | Tracing provider (file or otlp) | `otlp`  | OPENTDF_SERVER_TRACE_PROVIDER_NAME |
+
+For file provider:
+- `trace.provider.file.path`: Path to trace file output
+- `trace.provider.file.prettyPrint`: Enable pretty-printed JSON
+- `trace.provider.file.maxSize`: Maximum file size in MB
+- `trace.provider.file.maxBackups`: Maximum number of backup files
+- `trace.provider.file.maxAge`: Maximum age of files in days
+- `trace.provider.file.compress`: Enable compression of trace files
+
+For OTLP provider:
+- `trace.provider.otlp.protocol`: Protocol to use (grpc or http/protobuf)
+- `trace.provider.otlp.endpoint`: Endpoint URL for the collector
+- `trace.provider.otlp.insecure`: Whether to use an insecure connection
+- `trace.provider.otlp.headers`: Headers to include in OTLP requests
+
+## Services Configuration
+
+Root level key `services`
+
+### Key Access Server (KAS)
+
+Root level key `kas`
+
+Environment Variable: `OPENTDF_SERVICES_KAS_KEYRING='[{"kid":"k1","alg":"rsa:2048"},{"kid":"k2","alg":"ec:secp256r1"}]'`
+
+| Field                             | Description                                                                     | Default  |
+| --------------------------------- | ------------------------------------------------------------------------------- | -------- |
+| `keyring.*.kid`                   | Which key id this is binding                                                    |          |
+| `keyring.*.alg`                   | (Optional) Associated algorithm. (Allows reusing KID with different algorithms) |          |
+| `keyring.*.legacy`                | Indicates this may be used for TDFs with no key ID; default if all unspecified. | inferred |
+| `preview_features.ec_tdf_enabled` | Whether tdf based ecc support is enabled.                                       | `false`  |
+| `preview_features.key_management` | Whether new key management features are enabled.                                | `false`  |
+| `root_key`                        | Key needed when new key_management functionality is enabled.                    |          |
+
+
+Example:
+
+```yaml
+services:
+  kas:
+    keyring:
+      - kid: e2
+        alg: ec:secp256r1
+      - kid: e1
+        alg: ec:secp256r1
+        legacy: true
+      - kid: r2f
+        alg: rsa:2048
+      - kid: r1
+        alg: rsa:2048
+        legacy: true
+```
+
+### Authorization
+
+Root level key `authorization`
+
+| Field        | Description                     | Default                                | Environment Variables                     |
+| ------------ | ------------------------------- | -------------------------------------- | ----------------------------------------- |
+| `rego.path`  | Path to rego policy file        | Leverages embedded rego policy         | OPENTDF_SERVICES_AUTHORIZATION_REGO_PATH  |
+| `rego.query` | Rego query to execute in policy | `data.opentdf.entitlements.attributes` | OPENTDF_SERVICES_AUTHORIZATION_REGO_QUERY |
+
+Example:
+
+```yaml
+services:
+  authorization:
+    rego:
+      path: /path/to/policy.rego
+      query: data.opentdf.entitlements.attributes
+```
+
+### Policy
+
+Root level key `policy`
+
+| Field                        | Description                                            | Default | Environment Variables                              |
+| ---------------------------- | ------------------------------------------------------ | ------- | -------------------------------------------------- |
+| `list_request_limit_default` | Policy List request limit default when not provided    | 1000    | OPENTDF_SERVICES_POLICY_LIST_REQUEST_LIMIT_DEFAULT |
+| `list_request_limit_max`     | Policy List request limit maximum enforced by services | 2500    | OPENTDF_SERVICES_POLICY_LIST_REQUEST_LIMIT_MAX     |
+
+Example:
+
+```yaml
+services:
+  policy:
+    list_request_limit_default: 1000
+    list_request_limit_max: 2500
+```
+
+### Casbin Endpoint Authorization
+
+OpenTDF uses Casbin to manage authorization policies. This document provides an overview of how to configure and manage the default authorization policy in OpenTDF.
+
+#### Key Aspects of Authorization Configuration
+
+2. **Username Claim**: The claim in the OIDC token that should be used to extract a username.
+3. **Group Claim**: The claim in the OIDC token that should be used to find the group claims.
+4. **Map (Deprecated)**: Mapping between policy roles and IdP roles.
+4. **Extension**: Policy that will extend the builtin policy
+4. **CSV**: The authorization policy in CSV format. This will override the builtin policy.
+5. **Model**: The Casbin policy model. This should only be set if you have a deep understanding of how casbin works.
+
+#### Configuration in opentdf-example.yaml
+
+Below is an example configuration snippet from
+opentdf-example.yaml:
+
+```yaml
+server:
+  auth:
+    enabled: true
+    enforceDPoP: false
+    # public_client_id: 'opentdf-public' # DEPRECATED
+    audience: 'http://localhost:8080'
+    issuer: http://keycloak:8888/auth/realms/opentdf
+    policy:
+      
+      ## Deprecated
+      ## Dot notation is used to access nested claims (i.e. realm_access.roles)
+      claim: "realm_access.roles"
+
+      ## Dot notation is used to access the username claim
+      username_claim: "email"
+
+      ## Dot notation is used to access the groups claim
+      group_claim: "realm_access.roles"
+      
+      ## Deprecated: Use standard casbin policy groupings (g, <user/group>, <role>)
+      ## Maps the external role to the OpenTDF role
+      ## Note: left side is used in the policy, right side is the external role
+      map:
+        standard: opentdf-standard
+        admin: opentdf-admin
+
+      ## Policy that will extend the builtin policy.
+      extension: |
+        p, role:admin, *, *, allow
+        p, role:standard, policy:attributes, read, allow
+        p, role:standard, policy:subject-mappings, read, allow
+        g, opentdf-admin, role:admin
+        g, alice@opentdf.io, role:standard
+
+      ## Custom policy (see examples https://github.com/casbin/casbin/tree/master/examples)
+      ## This will overwrite the builtin policy. Use with caution. 
+      csv: |
+        p, role:admin, *, *, allow
+        p, role:standard, policy:attributes, read, allow
+        p, role:standard, policy:subject-mappings, read, allow
+        p, role:standard, policy:resource-mappings, read, allow
+        p, role:standard, policy:kas-registry, read, allow
+        p, role:unknown, entityresolution.EntityResolutionService.ResolveEntities, write, allow
+        p, role:unknown, kas.AccessService/Rewrap, *, allow
+
+      ## Custom model (see https://casbin.org/docs/syntax-for-models/)
+      ## Avoid setting this unless you have a deep understanding of how casbin works. 
+      model: |
+        [request_definition]
+        r = sub, res, act, obj
+        
+        [policy_definition]
+        p = sub, res, act, obj, eft
+        
+        [role_definition]
+        g = _, _
+        
+        [policy_effect]
+        e = some(where (p.eft == allow)) && !some(where (p.eft == deny))
+        
+        [matchers]
+        m = g(r.sub, p.sub) && globOrRegexMatch(r.res, p.res) && globOrRegexMatch(r.act, p.act) && globOrRegexMatch(r.obj, p.obj)
+```
+
+#### Role Permissions
+
+- **Admin**: Can perform all operations.
+- **Standard User**: Can read.
+- **Public Endpoints**: Accessible without specific roles.
+
+#### Managing Authorization Policy
+
+Admins can manage the authorization policy directly in the YAML configuration file. For detailed configuration options, refer to the [Casbin documentation](https://casbin.org/docs/en/syntax-for-models).
+
+## Cache Configuration
+
+The platform supports a cache manager to improve performance for frequently accessed data. You can configure the cache backend and its resource usage.
+
+Root level key `cache`
+
+| Field                    | Description                                                      | Default      |
+|--------------------------|------------------------------------------------------------------|--------------|
+| `ristretto.max_cost`      | Maximum cost for the cache (e.g. 100mb, 1gb)                     | `1gb`        |
+
+Example:
+
+```yaml
+cache:
+  ristretto:
+    max_cost: 1gb              # Maximum cost (i.e. 1mb, 1gb) for the cache (default: 1gb)
+```
diff --git a/docs/getting-started/index.mdx b/docs/tutorials/your-first-tdf/index.mdx
similarity index 99%
rename from docs/getting-started/index.mdx
rename to docs/tutorials/your-first-tdf/index.mdx
index c0622da..f35578a 100644
--- a/docs/getting-started/index.mdx
+++ b/docs/tutorials/your-first-tdf/index.mdx
@@ -1,5 +1,5 @@
 ---
-slug: /getting-started
+slug: /tutorials/your-first-tdf
 ---
 # Getting Started
 
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 3657ed1..1877ee1 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -111,7 +111,7 @@ const config: Config = {
         {
           type: "doc",
           position: "left",
-          docId: "introduction",
+          docId: "index",
           label: "Docs",
         },
         {
@@ -146,12 +146,12 @@ const config: Config = {
           title: "Support",
           items: [
             {
-              label: "Getting Started",
-              to: "/getting-started/configuration",
+              label: "Tutorials",
+              to: "/tutorials",
             },
             {
               label: "Documentation",
-              to: "/introduction",
+              to: "/",
             },
             {
               label: "GitHub Discussions",
diff --git a/specs/authorization/v2/authorization.openapi.yaml b/specs/authorization/v2/authorization.openapi.yaml
index 47de4d9..270fde5 100644
--- a/specs/authorization/v2/authorization.openapi.yaml
+++ b/specs/authorization/v2/authorization.openapi.yaml
@@ -296,6 +296,25 @@ components:
           title: resources
           maxItems: 1000
           minItems: 1
+        fulfillableObligationFqns:
+          type: array
+          items:
+            type: string
+            description: |+
+              if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+              ```
+              this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+              ```
+
+          title: fulfillable_obligation_fqns
+          description: |+
+            obligations (fully qualified values) the requester is capable of fulfilling
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
+            if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+            ```
+            this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+            ```
+
       title: GetDecisionMultiResourceRequest
       required:
         - entityIdentifier
@@ -306,6 +325,9 @@ components:
          1. one entity reference (actor)
          2. one action
          3. multiple resources
+
+         If entitled, checks obligation policy: fulfillable obligations must satisfy all triggered.
+
          Note: this is a more performant bulk request for multiple resource decisions, up to 1000 per request
         action.name must be provided:
         ```
@@ -341,6 +363,25 @@ components:
         resource:
           title: resource
           $ref: '#/components/schemas/authorization.v2.Resource'
+        fulfillableObligationFqns:
+          type: array
+          items:
+            type: string
+            description: |+
+              if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+              ```
+              this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+              ```
+
+          title: fulfillable_obligation_fqns
+          description: |+
+            obligations (fully qualified values) the requester is capable of fulfilling
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
+            if provided, fulfillable_obligation_fqns must be between 1 and 50 in count with all valid FQNs:
+            ```
+            this.size() == 0 || (this.size() <= 50 && this.all(item, item.isUri()))
+            ```
+
       title: GetDecisionRequest
       required:
         - entityIdentifier
@@ -352,6 +393,8 @@ components:
          1. one entity reference (actor)
          2. one action
          3. one resource
+
+         If entitled, checks obligation policy: fulfillable obligations must satisfy all triggered.
         action.name must be provided:
         ```
         has(this.action.name)
@@ -362,9 +405,7 @@ components:
       properties:
         decision:
           title: decision
-          description: |-
-            decision on the resource optional list of obligations represented in URI format
-             repeated string obligations = 2;
+          description: decision on the resource
           $ref: '#/components/schemas/authorization.v2.ResourceDecision'
       title: GetDecisionResponse
       additionalProperties: false
@@ -457,6 +498,14 @@ components:
           title: decision
           description: decision result
           $ref: '#/components/schemas/authorization.v2.Decision'
+        requiredObligations:
+          type: array
+          items:
+            type: string
+          title: required_obligations
+          description: |-
+            obligations (fully qualified values) the PEP is required to fulfill on the given resource
+             i.e. https://<namespace>/obl/<definition name>/value/<value>
       title: ResourceDecision
       additionalProperties: false
     common.Metadata:
diff --git a/specs/policy/actions/actions.openapi.yaml b/specs/policy/actions/actions.openapi.yaml
index 3f4f224..ffe40af 100644
--- a/specs/policy/actions/actions.openapi.yaml
+++ b/specs/policy/actions/actions.openapi.yaml
@@ -665,6 +665,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -707,6 +782,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -735,6 +819,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -927,6 +1022,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/attributes/attributes.openapi.yaml b/specs/policy/attributes/attributes.openapi.yaml
index 0703961..dad552b 100644
--- a/specs/policy/attributes/attributes.openapi.yaml
+++ b/specs/policy/attributes/attributes.openapi.yaml
@@ -1240,6 +1240,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -1282,6 +1357,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -1310,6 +1394,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1502,6 +1597,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/kasregistry/key_access_server_registry.openapi.yaml b/specs/policy/kasregistry/key_access_server_registry.openapi.yaml
index a676adf..5e103fb 100644
--- a/specs/policy/kasregistry/key_access_server_registry.openapi.yaml
+++ b/specs/policy/kasregistry/key_access_server_registry.openapi.yaml
@@ -917,6 +917,9 @@ components:
           type: string
           title: config_json
           format: byte
+        manager:
+          type: string
+          title: manager
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/keymanagement/key_management.openapi.yaml b/specs/policy/keymanagement/key_management.openapi.yaml
index e481df3..61a3e43 100644
--- a/specs/policy/keymanagement/key_management.openapi.yaml
+++ b/specs/policy/keymanagement/key_management.openapi.yaml
@@ -353,6 +353,9 @@ components:
           type: string
           title: config_json
           format: byte
+        manager:
+          type: string
+          title: manager
         metadata:
           title: metadata
           description: Common metadata
@@ -409,7 +412,7 @@ components:
           title: name
           description: |-
             Required
-             The name of the key provider. (e.g. "AWS KMS", "Google Cloud KMS", "Azure Key Vault")
+             The name of the key provider. (e.g. "AWS KMS Instance 1", "Google Cloud KMS Instance 2")
         configJson:
           type: string
           title: config_json
@@ -417,6 +420,12 @@ components:
           description: |-
             Required
              JSON configuration for the key provider. This is unique to individual key providers.
+        manager:
+          type: string
+          title: manager
+          description: |-
+            Required
+             The type of key manager (e.g. "aws", "gcp", "azure", "opentdf.io/basic")
         metadata:
           title: metadata
           description: Common metadata
@@ -425,6 +434,7 @@ components:
       required:
         - name
         - configJson
+        - manager
       additionalProperties: false
       description: Provider Configuration Requests and Response Messages
     policy.keymanagement.CreateProviderConfigResponse:
@@ -473,6 +483,11 @@ components:
           title: name
           required:
             - name
+      properties:
+        manager:
+          type: string
+          title: manager
+          description: Optional - filter by manager type when searching by name
       title: GetProviderConfigRequest
       additionalProperties: false
     policy.keymanagement.GetProviderConfigResponse:
@@ -522,6 +537,10 @@ components:
           title: config_json
           format: byte
           description: Optional
+        manager:
+          type: string
+          title: manager
+          description: Optional
         metadata:
           title: metadata
           description: |-
diff --git a/specs/policy/objects.openapi.yaml b/specs/policy/objects.openapi.yaml
index e0bc4d1..e65c942 100644
--- a/specs/policy/objects.openapi.yaml
+++ b/specs/policy/objects.openapi.yaml
@@ -538,6 +538,9 @@ components:
           type: string
           title: config_json
           format: byte
+        manager:
+          type: string
+          title: manager
         metadata:
           title: metadata
           description: Common metadata
@@ -598,6 +601,9 @@ components:
           items:
             $ref: '#/components/schemas/policy.ObligationValue'
           title: values
+        fqn:
+          type: string
+          title: fqn
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
@@ -618,6 +624,11 @@ components:
         attributeValue:
           title: attribute_value
           $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
@@ -635,11 +646,28 @@ components:
         value:
           type: string
           title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
       title: ObligationValue
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PrivateKeyCtx:
       type: object
       properties:
@@ -753,6 +781,17 @@ components:
           $ref: '#/components/schemas/common.Metadata'
       title: ActionAttributeValue
       additionalProperties: false
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1001,6 +1040,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/obligations/obligations.openapi.yaml b/specs/policy/obligations/obligations.openapi.yaml
index 46256da..456ea7f 100644
--- a/specs/policy/obligations/obligations.openapi.yaml
+++ b/specs/policy/obligations/obligations.openapi.yaml
@@ -528,6 +528,40 @@ components:
         - SUBJECT_MAPPING_OPERATOR_ENUM_IN
         - SUBJECT_MAPPING_OPERATOR_ENUM_NOT_IN
         - SUBJECT_MAPPING_OPERATOR_ENUM_IN_CONTAINS
+    common.IdFqnIdentifier:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+          format: uuid
+        fqn:
+          type: string
+          title: fqn
+          minLength: 1
+          format: uri
+      title: IdFqnIdentifier
+      additionalProperties: false
+    common.IdNameIdentifier:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+          format: uuid
+        name:
+          type: string
+          title: name
+          maxLength: 253
+          minLength: 1
+          description: |+
+            Name must be an alphanumeric string, allowing hyphens and underscores but not as the first or last character. The stored name will be normalized to lower case.:
+            ```
+            this.matches('^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$')
+            ```
+
+      title: IdNameIdentifier
+      additionalProperties: false
     common.Metadata:
       type: object
       properties:
@@ -962,6 +996,9 @@ components:
           items:
             $ref: '#/components/schemas/policy.ObligationValue'
           title: values
+        fqn:
+          type: string
+          title: fqn
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
@@ -982,6 +1019,11 @@ components:
         attributeValue:
           title: attribute_value
           $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
@@ -999,6 +1041,14 @@ components:
         value:
           type: string
           title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.Metadata'
@@ -1046,6 +1096,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -1074,6 +1133,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1266,6 +1336,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
@@ -1275,16 +1350,24 @@ components:
     policy.obligations.AddObligationTriggerRequest:
       type: object
       properties:
-        obligationValueId:
-          type: string
-          title: obligation_value_id
+        obligationValue:
+          title: obligation_value
           description: Required
-        actionId:
-          type: string
-          title: action_id
-        attributeValueId:
-          type: string
-          title: attribute_value_id
+          $ref: '#/components/schemas/common.IdFqnIdentifier'
+        action:
+          title: action
+          description: Required
+          $ref: '#/components/schemas/common.IdNameIdentifier'
+        attributeValue:
+          title: attribute_value
+          description: Required
+          $ref: '#/components/schemas/common.IdFqnIdentifier'
+        context:
+          title: context
+          description: |-
+            Optional
+             The request context for this obligation value policy decisioning.
+          $ref: '#/components/schemas/policy.RequestContext'
         metadata:
           title: metadata
           description: |-
@@ -1292,6 +1375,10 @@ components:
              Common metadata
           $ref: '#/components/schemas/common.MetadataMutable'
       title: AddObligationTriggerRequest
+      required:
+        - obligationValue
+        - action
+        - attributeValue
       additionalProperties: false
       description: Triggers
     policy.obligations.AddObligationTriggerResponse:
@@ -1304,30 +1391,35 @@ components:
       additionalProperties: false
     policy.obligations.CreateObligationRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
-          title: id
-          required:
-            - id
       properties:
+        namespaceId:
+          type: string
+          title: namespace_id
+          format: uuid
+        namespaceFqn:
+          type: string
+          title: namespace_fqn
+          minLength: 1
+          format: uri
         name:
           type: string
           title: name
+          maxLength: 253
+          description: |+
+            Obligation name must be an alphanumeric string, allowing hyphens and underscores but not as the first or last character. The stored name will be normalized to lower case.:
+            ```
+            this.matches('^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$')
+            ```
+
         values:
           type: array
           items:
             type: string
+            maxLength: 253
+            pattern: ^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$
+            uniqueItems: true
           title: values
+          uniqueItems: true
           description: Optional
         metadata:
           title: metadata
@@ -1336,6 +1428,8 @@ components:
              Common metadata
           $ref: '#/components/schemas/common.MetadataMutable'
       title: CreateObligationRequest
+      required:
+        - name
       additionalProperties: false
     policy.obligations.CreateObligationResponse:
       type: object
@@ -1347,25 +1441,34 @@ components:
       additionalProperties: false
     policy.obligations.CreateObligationValueRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
-          title: id
-          required:
-            - id
       properties:
+        obligationId:
+          type: string
+          title: obligation_id
+          format: uuid
+        obligationFqn:
+          type: string
+          title: obligation_fqn
+          minLength: 1
+          format: uri
         value:
           type: string
           title: value
+          maxLength: 253
+          description: |+
+            Obligation value must be an alphanumeric string, allowing hyphens and underscores but not as the first or last character. The stored value will be normalized to lower case.:
+            ```
+            this.matches('^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$')
+            ```
+
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.obligations.ValueTriggerRequest'
+          title: triggers
+          description: |-
+            Optional
+             Combination of action and attribute_value that will trigger this obligation value policy decisioning.
         metadata:
           title: metadata
           description: |-
@@ -1373,6 +1476,8 @@ components:
              Common metadata
           $ref: '#/components/schemas/common.MetadataMutable'
       title: CreateObligationValueRequest
+      required:
+        - value
       additionalProperties: false
     policy.obligations.CreateObligationValueResponse:
       type: object
@@ -1384,21 +1489,16 @@ components:
       additionalProperties: false
     policy.obligations.DeleteObligationRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
+      properties:
+        id:
+          type: string
           title: id
-          required:
-            - id
+          format: uuid
+        fqn:
+          type: string
+          title: fqn
+          minLength: 1
+          format: uri
       title: DeleteObligationRequest
       additionalProperties: false
     policy.obligations.DeleteObligationResponse:
@@ -1411,21 +1511,16 @@ components:
       additionalProperties: false
     policy.obligations.DeleteObligationValueRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
+      properties:
+        id:
+          type: string
           title: id
-          required:
-            - id
+          format: uuid
+        fqn:
+          type: string
+          title: fqn
+          minLength: 1
+          format: uri
       title: DeleteObligationValueRequest
       additionalProperties: false
     policy.obligations.DeleteObligationValueResponse:
@@ -1438,21 +1533,16 @@ components:
       additionalProperties: false
     policy.obligations.GetObligationRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
+      properties:
+        id:
+          type: string
           title: id
-          required:
-            - id
+          format: uuid
+        fqn:
+          type: string
+          title: fqn
+          minLength: 1
+          format: uri
       title: GetObligationRequest
       additionalProperties: false
       description: Definitions
@@ -1466,21 +1556,16 @@ components:
       additionalProperties: false
     policy.obligations.GetObligationValueRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
+      properties:
+        id:
+          type: string
           title: id
-          required:
-            - id
+          format: uuid
+        fqn:
+          type: string
+          title: fqn
+          minLength: 1
+          format: uri
       title: GetObligationValueRequest
       additionalProperties: false
       description: Values
@@ -1499,7 +1584,15 @@ components:
           type: array
           items:
             type: string
+            minLength: 1
+            format: uri
+            maxItems: 250
+            minItems: 1
+            uniqueItems: true
           title: fqns
+          maxItems: 250
+          minItems: 1
+          uniqueItems: true
       title: GetObligationValuesByFQNsRequest
       additionalProperties: false
     policy.obligations.GetObligationValuesByFQNsResponse:
@@ -1531,7 +1624,15 @@ components:
           type: array
           items:
             type: string
+            minLength: 1
+            format: uri
+            maxItems: 250
+            minItems: 1
+            uniqueItems: true
           title: fqns
+          maxItems: 250
+          minItems: 1
+          uniqueItems: true
       title: GetObligationsByFQNsRequest
       additionalProperties: false
     policy.obligations.GetObligationsByFQNsResponse:
@@ -1558,22 +1659,16 @@ components:
       additionalProperties: false
     policy.obligations.ListObligationsRequest:
       type: object
-      oneOf:
-        - properties:
-            fqn:
-              type: string
-              title: fqn
-          title: fqn
-          required:
-            - fqn
-        - properties:
-            id:
-              type: string
-              title: id
-          title: id
-          required:
-            - id
       properties:
+        namespaceId:
+          type: string
+          title: namespace_id
+          format: uuid
+        namespaceFqn:
+          type: string
+          title: namespace_fqn
+          minLength: 1
+          format: uri
         pagination:
           title: pagination
           description: Optional
@@ -1599,6 +1694,8 @@ components:
         id:
           type: string
           title: id
+          format: uuid
+          description: Required
       title: RemoveObligationTriggerRequest
       additionalProperties: false
     policy.obligations.RemoveObligationTriggerResponse:
@@ -1615,11 +1712,19 @@ components:
         id:
           type: string
           title: id
+          format: uuid
           description: Required
         name:
           type: string
           title: name
-          description: Optional
+          maxLength: 253
+          description: |+
+            Optional
+            Obligation name must be an alphanumeric string, allowing hyphens and underscores but not as the first or last character. The stored name will be normalized to lower case.:
+            ```
+            size(this) > 0 ? this.matches('^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$') : true
+            ```
+
         metadata:
           title: metadata
           $ref: '#/components/schemas/common.MetadataMutable'
@@ -1642,13 +1747,32 @@ components:
         id:
           type: string
           title: id
+          format: uuid
           description: Required
         value:
           type: string
           title: value
-          description: Optional
+          maxLength: 253
+          description: |+
+            Optional
+            Obligation value must be an alphanumeric string, allowing hyphens and underscores but not as the first or last character. The stored value will be normalized to lower case.:
+            ```
+            size(this) > 0 ? this.matches('^[a-zA-Z0-9](?:[a-zA-Z0-9_-]*[a-zA-Z0-9])?$') : true
+            ```
+
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.obligations.ValueTriggerRequest'
+          title: triggers
+          description: |-
+            Optional
+             Obligation Triggers provided here will replace all existing records in the database.
         metadata:
           title: metadata
+          description: |-
+            Optional
+             Common metadata
           $ref: '#/components/schemas/common.MetadataMutable'
         metadataUpdateBehavior:
           title: metadata_update_behavior
@@ -1663,6 +1787,26 @@ components:
           $ref: '#/components/schemas/policy.ObligationValue'
       title: UpdateObligationValueResponse
       additionalProperties: false
+    policy.obligations.ValueTriggerRequest:
+      type: object
+      properties:
+        action:
+          title: action
+          description: Required. The ID of the action that will trigger this obligation value policy decisioning.
+          $ref: '#/components/schemas/common.IdNameIdentifier'
+        attributeValue:
+          title: attribute_value
+          description: Required. The attribute value ID that will trigger this obligation value policy decisioning.
+          $ref: '#/components/schemas/common.IdFqnIdentifier'
+        context:
+          title: context
+          description: Optional. The request context for this obligation value policy decisioning.
+          $ref: '#/components/schemas/policy.RequestContext'
+      title: ValueTriggerRequest
+      required:
+        - action
+        - attributeValue
+      additionalProperties: false
     connect-protocol-version:
       type: number
       title: Connect-Protocol-Version
diff --git a/specs/policy/registeredresources/registered_resources.openapi.yaml b/specs/policy/registeredresources/registered_resources.openapi.yaml
index 7bc73e2..75b03e5 100644
--- a/specs/policy/registeredresources/registered_resources.openapi.yaml
+++ b/specs/policy/registeredresources/registered_resources.openapi.yaml
@@ -875,6 +875,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -917,6 +992,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -1006,6 +1090,17 @@ components:
           $ref: '#/components/schemas/common.Metadata'
       title: ActionAttributeValue
       additionalProperties: false
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1198,6 +1293,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/resourcemapping/resource_mapping.openapi.yaml b/specs/policy/resourcemapping/resource_mapping.openapi.yaml
index 7e13ecd..a547dff 100644
--- a/specs/policy/resourcemapping/resource_mapping.openapi.yaml
+++ b/specs/policy/resourcemapping/resource_mapping.openapi.yaml
@@ -875,6 +875,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -917,6 +992,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -945,6 +1029,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1137,6 +1232,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/subjectmapping/subject_mapping.openapi.yaml b/specs/policy/subjectmapping/subject_mapping.openapi.yaml
index 69d6ed3..585aec2 100644
--- a/specs/policy/subjectmapping/subject_mapping.openapi.yaml
+++ b/specs/policy/subjectmapping/subject_mapping.openapi.yaml
@@ -911,6 +911,81 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
     policy.PageRequest:
       type: object
       properties:
@@ -953,6 +1028,15 @@ components:
           description: Total count of entire list
       title: PageResponse
       additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PublicKey:
       type: object
       oneOf:
@@ -981,6 +1065,17 @@ components:
       title: PublicKey
       additionalProperties: false
       description: Deprecated
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1198,6 +1293,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/specs/policy/unsafe/unsafe.openapi.yaml b/specs/policy/unsafe/unsafe.openapi.yaml
index 2ff949d..4ff4ed8 100644
--- a/specs/policy/unsafe/unsafe.openapi.yaml
+++ b/specs/policy/unsafe/unsafe.openapi.yaml
@@ -879,6 +879,9 @@ components:
           type: string
           title: config_json
           format: byte
+        manager:
+          type: string
+          title: manager
         metadata:
           title: metadata
           description: Common metadata
@@ -922,6 +925,90 @@ components:
           description: Keys for the namespace
       title: Namespace
       additionalProperties: false
+    policy.Obligation:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        namespace:
+          title: namespace
+          $ref: '#/components/schemas/policy.Namespace'
+        name:
+          type: string
+          title: name
+        values:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationValue'
+          title: values
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: Obligation
+      additionalProperties: false
+    policy.ObligationTrigger:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligationValue:
+          title: obligation_value
+          $ref: '#/components/schemas/policy.ObligationValue'
+        action:
+          title: action
+          $ref: '#/components/schemas/policy.Action'
+        attributeValue:
+          title: attribute_value
+          $ref: '#/components/schemas/policy.Value'
+        context:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.RequestContext'
+          title: context
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationTrigger
+      additionalProperties: false
+    policy.ObligationValue:
+      type: object
+      properties:
+        id:
+          type: string
+          title: id
+        obligation:
+          title: obligation
+          $ref: '#/components/schemas/policy.Obligation'
+        value:
+          type: string
+          title: value
+        triggers:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.ObligationTrigger'
+          title: triggers
+        fqn:
+          type: string
+          title: fqn
+        metadata:
+          title: metadata
+          $ref: '#/components/schemas/common.Metadata'
+      title: ObligationValue
+      additionalProperties: false
+    policy.PolicyEnforcementPoint:
+      type: object
+      properties:
+        clientId:
+          type: string
+          title: client_id
+          minLength: 1
+      title: PolicyEnforcementPoint
+      additionalProperties: false
     policy.PrivateKeyCtx:
       type: object
       properties:
@@ -974,6 +1061,17 @@ components:
           description: Required Base64 encoded public key in PEM format
       title: PublicKeyCtx
       additionalProperties: false
+    policy.RequestContext:
+      type: object
+      properties:
+        pep:
+          title: pep
+          $ref: '#/components/schemas/policy.PolicyEnforcementPoint'
+      title: RequestContext
+      required:
+        - pep
+      additionalProperties: false
+      description: Holds the context needed for obligation fulfillment
     policy.ResourceMapping:
       type: object
       properties:
@@ -1166,6 +1264,11 @@ components:
           items:
             $ref: '#/components/schemas/policy.ResourceMapping'
           title: resource_mappings
+        obligations:
+          type: array
+          items:
+            $ref: '#/components/schemas/policy.Obligation'
+          title: obligations
         metadata:
           title: metadata
           description: Common metadata
diff --git a/src/css/custom.css b/src/css/custom.css
index 066b404..915b8f5 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -239,6 +239,54 @@ Breakpoints:
   --vds-homepage-body-line-height: 1.5;
 }
 
+/* Hero section styling for homepage */
+.hero {
+  background: linear-gradient(135deg, var(--ifm-color-primary) 0%, var(--ifm-color-primary-dark) 100%);
+  color: white;
+  padding: 4rem 0;
+  margin-bottom: 0;
+}
+
+.hero__title {
+  font-size: 3rem;
+  font-weight: 600;
+  margin-bottom: 1.5rem;
+  line-height: 1.2;
+}
+
+.hero__subtitle {
+  font-size: 1.25rem;
+  font-weight: 300;
+  line-height: 1.6;
+  margin-bottom: 1.5rem;
+  opacity: 0.95;
+}
+
+.hero__cta {
+  margin-top: 2rem;
+}
+
+.hero__cta .button {
+  font-size: 1.125rem;
+  padding: 0.75rem 2rem;
+  border-radius: 6px;
+  font-weight: 500;
+}
+
+@media (max-width: 768px) {
+  .hero {
+    padding: 3rem 0;
+  }
+  
+  .hero__title {
+    font-size: 2rem;
+  }
+  
+  .hero__subtitle {
+    font-size: 1.125rem;
+  }
+}
+
 .homepage p {
   font-size: var(--vds-homepage-body-font-size);
   line-height: var(--vds-homepage-body-line-height);
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index 5304464..134a80a 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -14,8 +14,8 @@ export default function Home() {
         <Hero
           heading="OpenTDF: A toolkit for zero trust, data-centric security"
           callToAction={{
-            text: "Get Started",
-            url: "/getting-started",
+            text: "Get Started with OpenTDF",
+            url: "/tutorials/your-first-tdf",
           }}
         >
           <p>
@@ -31,7 +31,173 @@ export default function Home() {
           protecting data objects at scale using the Trusted Data Format 
           for organizations of all sizes and across all industries.
           </p>
+          <div style={{ 
+            position: 'relative',
+            display: 'flex',
+            justifyContent: 'center',
+            marginTop: '2rem',
+            zIndex: 5,
+            gap: '1rem',
+            flexWrap: 'wrap'
+          }}>
+            <button 
+              onClick={() => document.getElementById('find-what-you-need')?.scrollIntoView({ behavior: 'smooth' })}
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: '40px',
+                backgroundColor: 'transparent',
+                border: '2px solid var(--vds-color-blue-006)',
+                color: 'var(--vds-color-blue-006)',
+                fontWeight: 'bold',
+                borderRadius: '5px',
+                margin: '1rem',
+                padding: '2rem 1rem',
+                cursor: 'pointer',
+                textDecoration: 'none',
+                transition: 'all 0.3s ease'
+              }}
+              onMouseOver={(e) => {
+                e.currentTarget.style.backgroundColor = 'var(--vds-color-blue-006)';
+                e.currentTarget.style.color = 'var(--ifm-color-white)';
+              }}
+              onMouseOut={(e) => {
+                e.currentTarget.style.backgroundColor = 'transparent';
+                e.currentTarget.style.color = 'var(--vds-color-blue-006)';
+              }}
+            >
+              Learn More About OpenTDF
+            </button>
+          </div>
+          <p style={{ 
+            textAlign: 'center',
+            color: 'var(--vds-color-blue-007)', 
+            fontSize: '0.9rem',
+            marginTop: '1rem',
+            fontStyle: 'italic'
+          }}>
+            Want to get an instance of the OpenTDF Platform up and running? Click below!
+          </p>
         </Hero>
+
+        {/* Add spacing after hero section */}
+        <div style={{ padding: '40px 0' }}>
+          
+          {/* Find What You Need Section */}
+          <div id="find-what-you-need" className="container">
+            <div className="row">
+              <div className="col col--12">
+                <h2 style={{ textAlign: 'center', marginBottom: '1rem' }}>Find What You Need</h2>
+                <p style={{ textAlign: 'center', marginBottom: '1rem', fontSize: '1.1rem' }}>
+                  Choose your learning path based on what you want to accomplish
+                </p>
+                <p style={{ 
+                  textAlign: 'center', 
+                  marginBottom: '3rem', 
+                  fontSize: '1rem',
+                  fontStyle: 'italic',
+                  color: 'var(--ifm-color-emphasis-700)'
+                }}>
+
+                </p>
+              </div>
+            </div>
+            
+            <div className="row" style={{ marginBottom: '3rem' }}>
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-008)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>🚀 Tutorials</h3>
+                    <p><em>I want to learn by doing</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Step-by-step guides that take you by the hand through a series of steps to complete a project or solve a problem.</p>
+                    <ul>
+                      <li><strong><a href="/tutorials/your-first-tdf">Your First TDF</a></strong> - Get hands-on experience creating your first protected data file</li>
+                      <li><strong><a href="/tutorials">Complete Tutorial Series</a></strong> - Step-by-step guides for learning OpenTDF</li>
+                      <li><strong><a href="/getting-started/configuration">Platform Configuration</a></strong> - Set up OpenTDF services</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+              
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-008)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>📖 How-To Guides</h3>
+                    <p><em>I have a specific problem to solve</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Practical guides for common tasks and problems you'll encounter when working with OpenTDF.</p>
+                    <ul>
+                      <li><strong><a href="/how-to/sdk-recipes/tdf">Working with TDF Files</a></strong> - Encrypt and decrypt data with SDK examples</li>
+                      <li><strong><a href="/how-to/sdk-recipes/authorization">Authorization Patterns</a></strong> - Manage access control with practical examples</li>
+                      <li><strong><a href="/how-to/sdk-recipes">SDK Integration Recipes</a></strong> - Complete code examples and patterns</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+            </div>
+            
+            <div className="row" style={{ marginBottom: '3rem' }}>
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-lighter)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>💡 Explanations</h3>
+                    <p><em>I want to understand the concepts</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Big-picture explanations of how OpenTDF works and why it's built the way it is.</p>
+                    <ul>
+                      <li><strong><a href="/explanation/data-centric-security">Data-Centric Security</a></strong> - Core concepts and principles of OpenTDF</li>
+                      <li><strong><a href="/explanation/platform-architecture">Platform Architecture</a></strong> - How OpenTDF services work together</li>
+                      <li><strong><a href="/explanation/trusted-data-format">Trusted Data Format</a></strong> - Understanding TDF and self-protecting data</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+              
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-lighter)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>📚 Reference</h3>
+                    <p><em>I need to look up specific details</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Technical descriptions of the machinery and how to operate it.</p>
+                    <ul>
+                      <li><strong><a href="/reference/api">Platform APIs</a></strong> - Complete REST API reference for all services</li>
+                      <li><strong><a href="/reference/specifications">Technical Specifications</a></strong> - TDF format, protocols, and schemas</li>
+                      <li><strong><a href="/how-to/sdk-recipes">SDK Examples</a></strong> - Code examples and integration patterns</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
         <Columns>
           <Columns.Item title="Zero Trust and OpenTDF" subtitle="Why OpenTDF?">
             <p>
@@ -42,7 +208,7 @@ export default function Home() {
             that prioritizes the protection and integrity of data at every stage. 
             </p>
             <p>
-            By integrating OpenTDF’s data security features with a Zero Trust architecture, 
+            By integrating OpenTDF's data security features with a Zero Trust architecture, 
             organizations can enforce strict access controls, ensure data is continuously monitored, 
             and maintain comprehensive visibility into data interactions. This synergy not only 
             minimizes the risk of data breaches but also fosters a secure environment where data 
@@ -61,7 +227,7 @@ export default function Home() {
             This comprehensive overhaul involved simplifying core service components, 
             adopting standardized policy schemas, and improving platform APIs and SDKs both in 
             developer experience and in capability. By focusing on extensibility, we have enabled 
-            developers to customize and extend OpenTDF’s functionalities to suit specific use cases, 
+            developers to customize and extend OpenTDF's functionalities to suit specific use cases, 
             fostering innovation and adaptability. As we continue to advance, our focus remains on empowering the community with a secure, adaptable, 
             and interoperable platform that meets the highest standards of data protection and fosters collaborative innovation.
             </p>
@@ -101,4 +267,4 @@ export default function Home() {
       </Layout>
     </div>
   );
-}
+}
\ No newline at end of file

From 1b8bc2f2083455c332f763a218f4fa2ef43a70fd Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Tue, 7 Oct 2025 09:30:15 -0400
Subject: [PATCH 04/10] Update README, contributing and add style guide

---
 CONTRIBUTING.md | 458 ++++++++++++++++++++++++++++++++++++++++++++++--
 README.md       | 123 +++++++++++--
 STYLE_GUIDE.md  | 366 ++++++++++++++++++++++++++++++++++++++
 3 files changed, 922 insertions(+), 25 deletions(-)
 create mode 100644 STYLE_GUIDE.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a79b0a2..eb5383a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,25 +1,455 @@
-# Contributing
+# Contributing to OpenTDF Documentation
 
-The information below is meant for documentation contributors.
+> Thank you for your interest in improving OpenTDF documentation! This guide will help you contribute effectively.
 
+## Table of Contents
 
-## Prerequisites
+- [Getting Started](#getting-started)
+- [Types of Contributions](#types-of-contributions)
+- [Development Setup](#development-setup)
+- [Writing Guidelines](#writing-guidelines)
+- [Contribution Workflow](#contribution-workflow)
+- [Review Process](#review-process)
+- [Community Guidelines](#community-guidelines)
 
-- [Vale](https://vale.sh/docs/vale-cli/installation/)
+## Getting Started
 
+### Before You Begin
 
-## Check spelling and grammar for your changes
+1. **Check existing issues**: Look for [open documentation issues](https://github.com/opentdf/docs/issues) to see if someone's already working on what you want to improve
+2. **Read our style guide**: Familiarize yourself with our [Style Guide](STYLE_GUIDE.md)
+3. **Understand our structure**: Review how we organize content into four categories:
+   - 🚀 **Tutorials**: Learning-oriented, hands-on guides
+   - 📖 **How-To Guides**: Problem-solving, task-oriented instructions
+   - 💡 **Explanations**: Understanding-oriented, conceptual content
+   - 📚 **Reference**: Information-oriented, lookup material
 
-Install the required vale packages
-```shell
-vale sync
-```
+### What Makes a Good Contribution
+
+- **User-focused**: Addresses real user needs and pain points
+- **Tested**: All instructions and code examples actually work
+- **Clear**: Written in plain language appropriate for the audience
+- **Complete**: Includes necessary context, prerequisites, and next steps
+- **Consistent**: Follows our established style and formatting standards
+
+## Types of Contributions
+
+### 📝 Content Contributions
+
+**New Content:**
+
+- Tutorials for common use cases
+- How-to guides for specific problems
+- Explanations of complex concepts
+- Missing reference documentation
+
+**Content Improvements:**
+
+- Fix outdated information
+- Add missing steps or context
+- Improve clarity and organization
+- Add examples and code samples
+
+**Structure Improvements:**
+
+- Better organization within sections
+- Improved navigation between related topics
+- Cross-references and internal links
+
+### 🐛 Fixes and Updates
+
+**Quick Fixes:**
+
+- Typos and grammar errors
+- Broken links
+- Outdated screenshots
+- Missing or incorrect code
+
+**Larger Updates:**
+
+- Rewrite unclear sections
+- Update for new platform versions
+- Reorganize confusing content
+- Add missing prerequisites
+
+### 💡 Ideas and Suggestions
+
+**Discussion Topics:**
+
+- Content gaps you've noticed
+- User experience improvements
+- Structure and organization ideas
+- Technical accuracy concerns
+
+## Development Setup
+
+### Prerequisites
+
+- **Node.js**: Version specified in `.nvmrc` file
+- **npm**: For package management
+- **Git**: For version control
+- **Text editor**: With Markdown support recommended
+- **[Vale](https://vale.sh/docs/vale-cli/installation/)**: For grammar and style checking
+
+### Local Development Setup
+
+1. **Fork and clone the repository:**
+
+   ```bash
+   git clone https://github.com/YOUR-USERNAME/docs.git
+   cd docs
+   ```
+
+2. **Install dependencies:**
+
+   ```bash
+   nvm use  # Use correct Node version
+   npm ci   # Install exact versions from lock file
+   ```
+
+3. **Set up Vale for grammar checking:**
+
+   ```bash
+   vale sync  # Install required Vale packages
+   ```
+
+4. **Start development server:**
+
+   ```bash
+   npm run start
+   ```
+
+   This opens your browser to `http://localhost:3000` with live reloading.
+
+5. **Build and test:**
+
+   ```bash
+   npm run build  # Test production build
+   npm run serve  # Serve production build locally
+   ```
 
-Run vale on changed files:
-```shell
-git diff --name-only | xargs vale --glob='!blog/*'
+### Project Structure
+
+```bash
+docs/
+├── docs/                    # Main documentation content
+│   ├── tutorials/          # Learning-oriented guides
+│   ├── how-to/             # Problem-solving guides
+│   ├── explanation/        # Conceptual content
+│   └── reference/          # Lookup information
+├── src/                    # Website source code
+│   ├── components/         # React components
+│   ├── css/               # Styling
+│   └── pages/             # Custom pages (homepage, etc.)
+├── static/                # Static assets
+├── docusaurus.config.ts   # Site configuration
+└── sidebars.js           # Navigation configuration
 ```
 
-## Verify changes on the Docusaurus server
+### Working with Documentation
+
+**Creating new pages:**
+
+1. Add `.md` or `.mdx` files in appropriate `docs/` subdirectory
+2. Include proper frontmatter (title, sidebar position, etc.)
+3. Update navigation in `sidebars.js` if needed
+
+**Using MDX features:**
+
+- Import and use React components
+- Include interactive examples
+- Add custom styling when needed
+
+**Testing your changes:**
+
+- Always test locally before submitting
+- Verify all links work
+- Check responsive design on different screen sizes
+- Test any code examples you include
+- Run Vale for grammar and style checking:
+
+  ```bash
+  git diff --name-only | xargs vale --glob='!blog/*'
+  ```
+
+## Writing Guidelines
+
+### Content Standards
+
+**Follow our Style Guide**: See [STYLE_GUIDE.md](STYLE_GUIDE.md) for comprehensive guidelines on:
+
+- Voice and tone
+- Formatting standards
+- Code examples
+- Technical writing best practices
+
+**Content Categories**: Make sure your content fits the right category:
+
+- **Tutorials**: Step-by-step learning experiences
+  - Have clear learning objectives
+  - Build skills progressively
+  - Include explanations of what's happening
+  - End with what the user has accomplished
+
+- **How-To Guides**: Task-oriented problem solving
+  - Start with a clear problem statement
+  - Provide efficient, direct solutions
+  - Include troubleshooting for common issues
+  - Focus on practical outcomes
+
+- **Explanations**: Conceptual understanding
+  - Explain the "why" behind concepts
+  - Provide context and background
+  - Use examples and analogies
+  - Connect to broader themes
+
+- **Reference**: Factual information
+  - Comprehensive and accurate
+  - Well-organized for lookup
+  - Include examples for complex items
+  - Cross-reference related information
+
+### Technical Standards
+
+**Code Examples:**
+
+- Always specify programming language for syntax highlighting
+- Test all code examples to ensure they work
+- Include necessary imports and setup
+- Use realistic variable names and data
+- Add comments explaining non-obvious parts
+
+**Links and References:**
+
+- Use relative paths for internal links: `[Getting Started](../tutorials/getting-started)`
+- Test all external links regularly
+- Use descriptive link text: "View the API reference" not "click here"
+
+**Images and Media:**
+
+- Use images sparingly - they become outdated quickly
+- Provide alt text for accessibility
+- Optimize file sizes for web
+- Use consistent styling when possible
+
+## Contribution Workflow
+
+### 1. Planning Your Contribution
+
+**For small fixes** (typos, broken links, minor clarifications):
+
+- Create an issue or jump straight to a pull request
+- No need for extensive planning
+
+**For larger changes** (new content, major rewrites):
+
+1. **Create an issue** describing what you want to do and why
+2. **Discuss the approach** with maintainers before starting
+3. **Break large changes** into smaller, reviewable chunks
+
+### 2. Making Changes
+
+1. **Create a feature branch:**
+
+   ```bash
+   git checkout -b feature/improve-tutorial-xyz
+   ```
+
+2. **Make your changes:**
+   - Follow the style guide
+   - Test your changes locally
+   - Keep commits focused and atomic
+   - Run Vale on your changes:
+
+     ```bash
+     git diff --name-only | xargs vale --glob='!blog/*'
+     ```
+
+3. **Commit your changes:**
+
+   ```bash
+   git add .
+   git commit -m "docs: improve XYZ tutorial with clearer examples"
+   ```
+
+   **Commit Message Format:**
+   - `docs:` prefix for documentation changes
+   - Clear, concise description of what changed
+   - Use present tense: "add" not "added"
+
+4. **Push and create pull request:**
+
+   ```bash
+   git push origin feature/improve-tutorial-xyz
+   ```
+
+### 3. Pull Request Guidelines
+
+**PR Description should include:**
+
+- **What**: Clear description of changes made
+- **Why**: Explanation of motivation and context
+- **How**: Any relevant implementation details
+- **Testing**: How you verified the changes work
+
+**PR Title Format:**
+
+- `docs: brief description of changes`
+- Examples:
+  - `docs: add tutorial for TDF file encryption`
+  - `docs: fix broken links in API reference`
+  - `docs: improve clarity in platform architecture explanation`
+
+**Before submitting:**
+
+- [ ] Changes tested locally via `npm run start`
+- [ ] All links work correctly
+- [ ] Code examples are tested
+- [ ] Style guide followed
+- [ ] Vale checks passed
+- [ ] Screenshots updated if needed
+
+### 4. Addressing Review Feedback
+
+- **Respond promptly** to reviewer comments
+- **Ask questions** if feedback is unclear
+- **Make requested changes** in new commits (don't squash during review)
+- **Test again** after making changes
+- **Thank reviewers** for their time and input
+
+## Review Process
+
+### What to Expect
+
+**Timeline:**
+
+- Simple fixes: Usually reviewed within 2-3 days
+- Complex changes: May take 5-7 days depending on scope
+- Reviews may require multiple rounds of feedback
+
+**Review Criteria:**
+
+- **Technical accuracy**: Does the information work correctly?
+- **Style compliance**: Does it follow our style guide?
+- **User value**: Does this help users accomplish their goals?
+- **Completeness**: Is all necessary information included?
+
+### Types of Reviewers
+
+**Technical Reviewers**: Verify accuracy of technical content
+**Content Reviewers**: Focus on clarity, style, and user experience
+**Subject Matter Experts**: Review domain-specific content for accuracy
+
+### After Approval
+
+1. **Squash commits** if requested by reviewers
+2. **Update PR title/description** if needed
+3. **Merge** will be handled by maintainers
+4. **Changes go live** automatically when merged to main branch
+
+## Community Guidelines
+
+### Code of Conduct
+
+We follow OpenTDF's Code of Conduct. In summary:
+
+- **Be respectful** and inclusive
+- **Be collaborative** and helpful
+- **Be patient** with newcomers
+- **Focus on the work**, not personalities
+
+### Communication
+
+**GitHub Issues**: For bug reports, feature requests, and planning discussions
+**GitHub Discussions**: For general questions and community conversation
+**Pull Request Comments**: For specific feedback on changes
+
+### Getting Help
+
+**Stuck on something?**
+
+- Check existing documentation and issues first
+- Ask specific questions in GitHub discussions
+- Tag relevant maintainers in issues when appropriate
+- Be patient - maintainers are often volunteers
+
+**Want to help others?**
+
+- Answer questions in discussions
+- Review pull requests from other contributors
+- Help triage and organize issues
+- Share your expertise in your areas of knowledge
+
+## Quality Assurance
+
+### Grammar and Style Checking
+
+**Check spelling and grammar for your changes:**
+
+1. **Install Vale packages:**
+
+   ```bash
+   vale sync
+   ```
+
+2. **Run Vale on changed files:**
+
+   ```bash
+   git diff --name-only | xargs vale --glob='!blog/*'
+   ```
+
+3. **Address any issues** Vale identifies before submitting your PR
+
+### Verify Changes Locally
+
+**Always verify your changes on the Docusaurus server:**
+
+To verify the placement and style of your changes as well as ensure there are no breaking changes, follow the [local development instructions](#local-development-setup) for running the Docusaurus server locally.
+
+## Recognition
+
+We value all contributions to OpenTDF documentation! Contributors are recognized in:
+
+- **Release notes** for significant contributions
+- **Contributors list** in the repository
+- **Community highlights** in project communications
+- **Maintainer consideration** for regular, high-quality contributors
+
+## Quick Reference
+
+### Common Tasks
+
+**Fix a typo:**
+
+1. Fork repo → make change → submit PR
+2. No issue needed for obvious fixes
+
+**Add new tutorial:**
+
+1. Create issue to discuss scope and approach
+2. Write content following tutorial guidelines
+3. Test all steps thoroughly
+4. Submit PR with comprehensive description
+
+**Update outdated content:**
+
+1. Create issue describing what's outdated and why
+2. Update content and test changes
+3. Submit PR explaining what was updated
+
+**Report a problem:**
+
+1. Check if issue already exists
+2. Create detailed issue with steps to reproduce
+3. Include environment info when relevant
+
+### Resources
+
+- [Style Guide](STYLE_GUIDE.md) - Writing and formatting standards
+- [GitHub Issues](https://github.com/opentdf/docs/issues) - Bug reports and feature requests
+- [OpenTDF Platform](https://github.com/opentdf/platform) - Main project repository
+- [Live Documentation](https://docs.opentdf.io) - Current published docs
+
+---
 
-To verify the placement and style of your changes as well as ensure there are no breaking changes, follow the [instructions in the README](./README.md#local-development) for running the Docusaurus server locally.
\ No newline at end of file
+Thank you for contributing to OpenTDF documentation! Your efforts help developers and organizations implement data-centric security more effectively.
diff --git a/README.md b/README.md
index 357e476..fc785ff 100644
--- a/README.md
+++ b/README.md
@@ -1,26 +1,127 @@
-# Website
+# OpenTDF Documentation
+
+> The official documentation website for OpenTDF - an open source toolkit for zero trust, data-centric security.
+
+## About This Repository
+
+This repository contains the source code for the [OpenTDF documentation website](https://docs.opentdf.io), built using [Docusaurus](https://docusaurus.io/). The documentation provides comprehensive guides, tutorials, and reference materials for developers and organizations implementing data-centric security with OpenTDF.
+
+## What is OpenTDF?
+
+OpenTDF is an open source system for implementing data-centric security that enables:
+
+- **Zero Trust Data Protection**: Cryptographically bind access control policies to data objects
+- **Attribute-Based Access Control (ABAC)**: Fine-grained access decisions based on attributes and context
+- **Policy Travels with Data**: Security controls remain attached wherever data goes
+- **Trust Data Format (TDF)**: Open standard for self-protecting data
+
+## Documentation Structure
+
+Our documentation follows a user-needs approach with four main categories:
+
+- **🚀 Tutorials**: Step-by-step learning experiences for hands-on practice
+- **📖 How-To Guides**: Problem-solving recipes for specific tasks and integrations
+- **💡 Explanations**: Conceptual guides covering the "why" behind OpenTDF's design
+- **📚 Reference**: Technical specifications, API docs, and lookup information
+
+## Contributing
+
+We welcome contributions to improve our documentation! Please see our [Contributing Guide](CONTRIBUTING.md) for guidelines on:
+
+- Writing and editing documentation
+- Style and formatting standards
+- Review and approval process
+- Technical setup for contributors
+
+For style guidelines, please refer to our [Style Guide](STYLE_GUIDE.md).
+
+## Quick Links
+
+- **Live Documentation**: [docs.opentdf.io](https://docs.opentdf.io)
+- **OpenTDF Platform**: [github.com/opentdf/platform](https://github.com/opentdf/platform)
+- **TDF Format Spec**: [github.com/opentdf/spec](https://github.com/opentdf/spec)
+- **OpenTDF Organization**: [github.com/opentdf](https://github.com/opentdf)
+- **Community Discussions**: [GitHub Discussions](https://github.com/opentdf/platform/discussions)
+
+---
+
+## Local Development
 
 This website is built using [Docusaurus](https://docusaurus.io/), a modern static website generator.
 
-### Installation
+### Prerequisites
 
+Before you can run the documentation locally, you'll need Node.js and npm. We recommend using nvm (Node Version Manager) to manage Node.js versions.
+
+#### Option 1: Using nvm (Recommended)
+
+nvm allows you to install and switch between different Node.js versions easily.
+
+**Installation:**
+
+- **macOS/Linux**: Follow the installation instructions at [nvm GitHub repository](https://github.com/nvm-sh/nvm#installation-and-update)
+- **Windows**: Install nvm-windows from [nvm-windows releases](https://github.com/coreybutler/nvm-windows#installation--upgrades)
+
+**Verify installation:**
+
+```bash
+nvm --version  # macOS/Linux
+nvm version    # Windows
 ```
-$ nvm use
-$ npm ci
-```
+
+#### Option 2: Direct Node.js Installation
+
+If you prefer not to use nvm:
+
+1. **Visit [nodejs.org](https://nodejs.org/)** and download **Node.js version 22** (the version specified in our `.nvmrc` file)
+2. **Follow the installation instructions** for your operating system
+3. **Verify installation:**
+
+   ```bash
+   node --version  # Should show v22.x.x
+   npm --version   # Should show npm version
+   ```
+
+### Installation
+
+1. **Clone the repository:**
+
+   ```bash
+   git clone https://github.com/opentdf/docs.git
+   cd docs
+   ```
+
+2. **Use the correct Node.js version** (if using nvm):
+
+   ```bash
+   nvm use  # This reads the .nvmrc file and switches to Node.js v22
+   ```
+
+   If you don't have Node.js v22 installed via nvm:
+
+   ```bash
+   nvm install 22
+   nvm use 22
+   ```
+
+3. **Install dependencies:**
+
+   ```bash
+   npm ci  # Installs exact versions from package-lock.json
+   ```
 
 ### Local Development
 
-```
-$ npm run start
-```
+   ```bash
+   npm run start
+   ```
 
 This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
 
 ### Build
 
-```
-$ npm run build
-```
+   ```bash
+   npm run build
+   ```
 
 This command generates static content into the `build` directory and can be served using any static contents hosting service.
diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
new file mode 100644
index 0000000..bd8169c
--- /dev/null
+++ b/STYLE_GUIDE.md
@@ -0,0 +1,366 @@
+# OpenTDF Documentation Style Guide
+
+> Guidelines for writing clear, consistent, and user-friendly documentation for OpenTDF.
+
+## Table of Contents
+
+- [Writing Principles](#writing-principles)
+- [Voice and Tone](#voice-and-tone)
+- [Content Types](#content-types)
+- [Formatting Guidelines](#formatting-guidelines)
+- [Technical Writing Standards](#technical-writing-standards)
+- [Code Examples](#code-examples)
+- [Visual Elements](#visual-elements)
+- [Accessibility](#accessibility)
+
+## Writing Principles
+
+### 1. User-Centered Approach
+- **Start with user needs**: What is the user trying to accomplish?
+- **Provide context**: Explain why something matters before diving into how
+- **Be action-oriented**: Use active voice and clear imperatives
+- **Test your content**: Verify that instructions actually work
+
+### 2. Clarity Over Cleverness
+- **Write for scannable reading**: Use headers, bullet points, and short paragraphs
+- **Choose simple words**: Use "help" instead of "facilitate", "use" instead of "utilize"
+- **Be specific**: "Click the blue Save button" vs. "submit the form"
+- **Define acronyms**: Always spell out acronyms on first use (e.g., "Trusted Data Format (TDF)")
+
+### 3. Consistency
+- **Follow established patterns**: If one tutorial uses numbered steps, all should
+- **Use consistent terminology**: Don't alternate between "encrypt" and "protect"
+- **Maintain formatting standards**: Headers, code blocks, and links should be uniform
+
+## Voice and Tone
+
+### Voice (What We Sound Like)
+- **Expert but approachable**: We know what we're talking about, but we're here to help
+- **Direct and practical**: We focus on what users need to do
+- **Inclusive**: We assume various skill levels and backgrounds
+
+### Tone (How We Adapt to Context)
+- **Tutorials**: Encouraging and supportive ("Great job! Now let's...")
+- **How-To Guides**: Direct and efficient ("To solve X, do Y")
+- **Explanations**: Patient and thorough ("This concept is important because...")
+- **Reference**: Factual and precise ("This parameter accepts string values")
+
+### Language Guidelines
+- **Use second person ("you")** for instructions
+- **Use first person plural ("we")** when referring to OpenTDF team/community
+- **Avoid jargon** without explanation
+- **Use active voice**: "The platform encrypts data" not "Data is encrypted by the platform"
+
+## Content Types
+
+Our documentation follows four content categories. Each has specific characteristics:
+
+### 🚀 Tutorials (Learning-Oriented)
+**Purpose**: Teach concepts through guided practice
+**Structure**:
+- Clear learning objective
+- Prerequisites listed upfront
+- Numbered steps that build on each other
+- Explanations of what's happening
+- What the user should see/expect
+- Next steps or related tutorials
+
+**Example opening**:
+```markdown
+# Your First TDF File
+
+In this tutorial, you'll create your first Trusted Data Format (TDF) file and learn how OpenTDF protects data with cryptographic policies.
+
+**What you'll learn:**
+- How to encrypt a file using TDF
+- How access policies work
+- How to decrypt and access protected data
+
+**Prerequisites:**
+- OpenTDF platform running locally
+- Basic familiarity with command line
+```
+
+### 📖 How-To Guides (Problem-Oriented)
+**Purpose**: Solve specific real-world problems
+**Structure**:
+- Problem statement (what this solves)
+- Prerequisites (what you need)
+- Step-by-step solution
+- Troubleshooting common issues
+- Related guides
+
+**Example opening**:
+```markdown
+# Integrate OpenTDF with Existing Applications
+
+This guide shows how to add data protection to an existing application without major architectural changes.
+
+**Solves:** Adding TDF encryption to legacy systems
+**Prerequisites:** 
+- Existing application with file handling
+- OpenTDF SDK for your language
+```
+
+### 💡 Explanations (Understanding-Oriented)
+**Purpose**: Provide context and deepen understanding
+**Structure**:
+- What this concept is
+- Why it matters
+- How it fits into the bigger picture
+- Examples and analogies
+- Related concepts
+
+**Example opening**:
+```markdown
+# Data-Centric Security
+
+Data-centric security is a paradigm shift from traditional perimeter-based security models. Instead of protecting the network or application, data-centric security protects the data itself.
+
+## Why Traditional Security Falls Short
+
+In traditional models, once data crosses the security perimeter...
+```
+
+### 📚 Reference (Information-Oriented)
+**Purpose**: Provide precise technical information
+**Structure**:
+- Overview of what's documented
+- Organized by logical groups
+- Comprehensive parameter/option lists
+- Examples for each major item
+- Cross-references to related items
+
+**Example structure**:
+```markdown
+# Policy Service API Reference
+
+## Authentication Endpoints
+
+### POST /auth/login
+Authenticates a user and returns an access token.
+
+**Parameters:**
+- `username` (string, required): User's login name
+- `password` (string, required): User's password
+
+**Response:** 200 OK
+```json
+{
+  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "expires_in": 3600
+}
+```
+
+## Formatting Guidelines
+
+### Headers
+```markdown
+# Page Title (H1) - Only one per page
+## Section Title (H2) - Main sections
+### Subsection (H3) - Subsections within H2
+#### Detail Section (H4) - Only when necessary
+```
+
+### Lists
+**Use bullet points for unordered items:**
+```markdown
+- First item
+- Second item
+- Third item
+```
+
+**Use numbers for sequential steps:**
+```markdown
+1. First, do this
+2. Then, do this
+3. Finally, do this
+```
+
+### Emphasis
+- **Bold** for UI elements, important terms: "Click the **Save** button"
+- *Italics* for emphasis or first use of terms: "The *policy* defines access rules"
+- `Code formatting` for inline code, filenames, commands: "Edit the `config.yaml` file"
+
+### Links
+```markdown
+[Link text](URL) - External links
+[Link text](../path/to/page) - Internal relative links
+[Link text](/absolute/path) - Internal absolute links
+```
+
+### Callouts
+Use for important information:
+
+```markdown
+> **Note:** This is general information that's helpful to know.
+
+> **Warning:** This could cause problems if ignored.
+
+> **Tip:** This is a helpful suggestion or best practice.
+```
+
+## Technical Writing Standards
+
+### Code Examples
+
+#### Inline Code
+Use backticks for:
+- Commands: `npm install`
+- File names: `config.yaml`
+- Parameter names: `username`
+- Short code snippets: `const data = await encrypt(file)`
+
+#### Code Blocks
+Use fenced code blocks with language specification:
+
+```bash
+# Shell commands
+npm run start
+```
+
+```javascript
+// JavaScript examples
+const client = new TDFClient({
+  clientId: 'your-client-id',
+  platformEndpoint: 'http://localhost:8080'
+});
+```
+
+```yaml
+# Configuration files
+version: '3.8'
+services:
+  opentdf:
+    image: opentdf/platform
+```
+
+#### Code Block Guidelines
+- **Always specify the language** for syntax highlighting
+- **Include necessary imports** and context
+- **Use realistic examples** (not just "foo", "bar")
+- **Show complete, working examples** when possible
+- **Add comments** to explain non-obvious parts
+
+### File Paths and Commands
+
+**File paths:**
+- Use forward slashes: `docs/tutorials/getting-started.md`
+- Use relative paths from project root: `src/pages/index.tsx`
+- Use backticks: `src/components/Homepage/hero.tsx`
+
+**Commands:**
+- Show the full command: `npm install @opentdf/client`
+- Include relevant flags: `docker run -d --name opentdf opentdf/platform`
+- Use $ for shell prompts sparingly: `$ npm run start`
+
+### API Documentation
+
+**Endpoints:**
+```markdown
+### POST /api/v1/encrypt
+
+Encrypts data using the specified policy.
+
+**Parameters:**
+- `data` (string, required): The data to encrypt
+- `policy` (object, required): Encryption policy
+  - `attributes` (array): List of attribute values
+  - `dissem` (array): List of authorized recipients
+
+**Example Request:**
+```json
+{
+  "data": "sensitive information",
+  "policy": {
+    "attributes": ["classification:secret"],
+    "dissem": ["user1@example.com"]
+  }
+}
+```
+
+**Response:** 200 OK
+```json
+{
+  "tdf": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
+  "policy": {
+    "uuid": "550e8400-e29b-41d4-a716-446655440000"
+  }
+}
+```
+```
+
+## Visual Elements
+
+### Screenshots
+- Use screenshots sparingly - they become outdated quickly
+- When necessary, crop to show only relevant parts
+- Add clear captions explaining what the screenshot shows
+- Use consistent browser/OS when possible
+
+### Diagrams
+- Prefer simple text diagrams over complex images when possible
+- Use mermaid diagrams for flowcharts:
+
+```mermaid
+graph TD
+    A[User Request] --> B[Authorization Check]
+    B --> C{Authorized?}
+    C -->|Yes| D[Decrypt Data]
+    C -->|No| E[Access Denied]
+```
+
+### Tables
+Keep tables simple and scannable:
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `username` | string | Yes | User login name |
+| `password` | string | Yes | User password |
+| `remember` | boolean | No | Remember login (default: false) |
+
+## Accessibility
+
+### Writing for Accessibility
+- **Use descriptive link text**: "Download the installation guide" not "click here"
+- **Provide alt text** for images: `![OpenTDF architecture diagram showing...](diagram.png)`
+- **Use proper heading hierarchy** (don't skip from H1 to H3)
+- **Write descriptive page titles** and headings
+
+### Technical Accessibility
+- **Ensure good color contrast** in any visual elements
+- **Don't rely solely on color** to convey information
+- **Use semantic markup** (proper heading levels, lists, etc.)
+
+## Review Checklist
+
+Before submitting documentation changes:
+
+**Content:**
+- [ ] Is the purpose clear from the title and first paragraph?
+- [ ] Are prerequisites clearly stated?
+- [ ] Do all steps work as written?
+- [ ] Are code examples complete and tested?
+- [ ] Is the content at the appropriate technical level?
+
+**Style:**
+- [ ] Is the tone appropriate for the content type?
+- [ ] Are headers in logical hierarchy?
+- [ ] Are lists properly formatted?
+- [ ] Are links working and descriptive?
+- [ ] Is terminology consistent with other docs?
+
+**Technical:**
+- [ ] Do code blocks specify languages?
+- [ ] Are file paths correct?
+- [ ] Are API examples accurate?
+- [ ] Are there any broken internal links?
+
+## Getting Help
+
+- **Style questions**: Ask in GitHub discussions or documentation issues
+- **Technical accuracy**: Tag subject matter experts in pull requests
+- **Major changes**: Discuss in issues before implementing
+- **Examples**: Look at existing documentation in the same category
+
+Remember: Good documentation serves the user, not the writer. When in doubt, choose clarity and usefulness over perfection.
\ No newline at end of file

From 0dccec055f93e2f545f52a0f77e00bb0dae1fa88 Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Tue, 7 Oct 2025 10:46:48 -0400
Subject: [PATCH 05/10] Update gitignore for generated files

---
 .gitignore | 39 +++++++++++++++++++++++++--------------
 1 file changed, 25 insertions(+), 14 deletions(-)

diff --git a/.gitignore b/.gitignore
index 5bad750..7fcc537 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,9 +1,28 @@
+# Generated content from OpenAPI specs
 specs-processed/
 docs/OpenAPI-clients/
+
+# Generated content (legacy - can be removed if no longer used)
 docs/SDK-Samples/
 
+# Remote Content - Generated by docusaurus-plugin-remote-content
+# Specifications from opentdf/spec repo
+/docs/reference/trusted-data-format/specifications/index.md
+/docs/reference/trusted-data-format/specifications/**/*.md
+/docs/reference/trusted-data-format/specifications/**/_category_.json
+# CLI documentation from opentdf/otdfctl repo
+/docs/explanation/platform-architecture/components/cli/
+# Platform configuration from opentdf/platform repo
+/docs/how-to/getting-started/configuration.md
+# Static images from opentdf/spec repo
+/static/img/ecc_and_binding.svg
+/static/img/nanotdf.svg
+/static/img/symmetric_and_payload.svg
+/static/img/filecontents.svg
+
 # Dependencies
 /node_modules
+node_modules
 
 # Production
 /build
@@ -12,31 +31,23 @@ docs/SDK-Samples/
 .docusaurus
 .cache-loader
 docs/.index.json
-# Ignore all generated _category_.json files in docs/spec
-/docs/spec/**/_category_.json
-# Backup files
 *.backup
 
-# Misc
-.DS_Store
+# Environment files
 .env.local
 .env.development.local
 .env.test.local
 .env.production.local
 
+# Logs
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
-node_modules
 
-# Ignore Remote Content
-/docs/spec/index.md
-/docs/spec/**/*.md
-/docs/components/cli/
-/docs/reference/cli/
-/docs/reference/api/
-/docs/reference/specifications/
-/docs/getting-started/configuration.md
+# macOS
+.DS_Store
+
+
 
 /.idea/
 

From 34e99ab79a23a5d3d8f4da2cf60b3055aba967c3 Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Tue, 7 Oct 2025 11:40:00 -0400
Subject: [PATCH 06/10] - Restructure spec docs under reference - CLI docs
 under reference - Move appendix under reference - Move components under
 Architecture

---
 .../data-centric-security/index.md            |   8 +-
 .../traditional-vs-data-centric.md            | 215 ++++++++
 .../data-centric-security/use-cases.md        | 315 +++++++++++
 .../zero-trust-architecture.md                | 218 ++++++++
 docs/explanation/index.mdx                    |   2 +-
 .../platform-architecture/_category_.json     |   8 -
 .../components/_category_.json                |   2 +-
 .../components/authorization.md               |   0
 .../components/core/authz.md                  |   0
 .../components/core/index.md                  |   0
 .../components/entity_resolution.md           |   0
 .../components/key_access.md                  |   8 +-
 .../components/policy/actions.md              |   0
 .../components/policy/attributes.md           |   2 +-
 .../components/policy/index.md                |   2 +-
 .../components/policy/key_access_grants.md    |   2 +-
 .../components/policy/key_access_registry.md  |   0
 .../policy/keymanagement/base_key.md          |   2 +-
 .../components/policy/keymanagement/index.md  |   2 +-
 .../policy/keymanagement/key_managers.md      |   2 +-
 .../policy/keymanagement/key_mappings.md      |   2 +-
 .../policy/keymanagement/quickstart.md        |   2 +-
 .../components/policy/registered_resources.md |   0
 .../components/policy/resource_mappings.md    |   0
 .../components/policy/subject_mappings.md     |   0
 .../platform-architecture/index.md            |  24 +-
 .../cryptographic-binding.md                  | 300 ++++++++++
 docs/explanation/trusted-data-format/index.md |  12 +-
 .../trusted-data-format/tdf-lifecycle.md      | 511 ++++++++++++++++++
 .../trusted-data-format/tdf-vs-nanotdf.md     | 352 ++++++++++++
 docs/index.mdx                                |   1 -
 docs/{ => reference}/appendix/_category_.yaml |   0
 docs/{ => reference}/appendix/matrix.mdx      |   0
 docusaurus.config.ts                          |   4 +-
 src/utils/spec-documentation.ts               |  27 +-
 35 files changed, 1971 insertions(+), 52 deletions(-)
 create mode 100644 docs/explanation/data-centric-security/traditional-vs-data-centric.md
 create mode 100644 docs/explanation/data-centric-security/use-cases.md
 create mode 100644 docs/explanation/data-centric-security/zero-trust-architecture.md
 delete mode 100644 docs/explanation/platform-architecture/_category_.json
 rename docs/{ => explanation/platform-architecture}/components/_category_.json (96%)
 rename docs/{ => explanation/platform-architecture}/components/authorization.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/core/authz.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/core/index.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/entity_resolution.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/key_access.md (89%)
 rename docs/{ => explanation/platform-architecture}/components/policy/actions.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/policy/attributes.md (98%)
 rename docs/{ => explanation/platform-architecture}/components/policy/index.md (95%)
 rename docs/{ => explanation/platform-architecture}/components/policy/key_access_grants.md (99%)
 rename docs/{ => explanation/platform-architecture}/components/policy/key_access_registry.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/policy/keymanagement/base_key.md (95%)
 rename docs/{ => explanation/platform-architecture}/components/policy/keymanagement/index.md (97%)
 rename docs/{ => explanation/platform-architecture}/components/policy/keymanagement/key_managers.md (97%)
 rename docs/{ => explanation/platform-architecture}/components/policy/keymanagement/key_mappings.md (96%)
 rename docs/{ => explanation/platform-architecture}/components/policy/keymanagement/quickstart.md (99%)
 rename docs/{ => explanation/platform-architecture}/components/policy/registered_resources.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/policy/resource_mappings.md (100%)
 rename docs/{ => explanation/platform-architecture}/components/policy/subject_mappings.md (100%)
 create mode 100644 docs/explanation/trusted-data-format/cryptographic-binding.md
 create mode 100644 docs/explanation/trusted-data-format/tdf-lifecycle.md
 create mode 100644 docs/explanation/trusted-data-format/tdf-vs-nanotdf.md
 rename docs/{ => reference}/appendix/_category_.yaml (100%)
 rename docs/{ => reference}/appendix/matrix.mdx (100%)

diff --git a/docs/explanation/data-centric-security/index.md b/docs/explanation/data-centric-security/index.md
index d6697d5..181a43f 100644
--- a/docs/explanation/data-centric-security/index.md
+++ b/docs/explanation/data-centric-security/index.md
@@ -26,6 +26,7 @@ graph LR
 ```
 
 **Problems with this approach:**
+
 - **Data leaves the perimeter**: Once data is shared, copied, or moved, control is lost
 - **Insider threats**: Users inside the perimeter have broad access
 - **Breach consequences**: If perimeter is breached, all internal data is at risk
@@ -59,6 +60,7 @@ graph TD
 ```
 
 **Benefits of this approach:**
+
 - **Policy travels with data**: Controls remain effective regardless of location
 - **Fine-grained access**: Decisions based on user, context, and data sensitivity
 - **Zero-trust ready**: No assumptions about network security or user location
@@ -79,6 +81,7 @@ OpenTDF uses the **Trusted Data Format (TDF)** to implement data-centric securit
 Consider a confidential financial report:
 
 **Traditional Security:**
+
 - File stored on secure file server
 - Access controlled by network permissions
 - If shared via email → no control
@@ -86,6 +89,7 @@ Consider a confidential financial report:
 - If partner accesses → no control
 
 **Data-Centric Security with OpenTDF:**
+
 - File encrypted as TDF with policy: "Only Finance team members can access"
 - Policy travels with the file everywhere
 - Authorization checked every time someone tries to open it
@@ -104,6 +108,6 @@ Data-centric security is a cornerstone of **zero-trust architecture**:
 ## Next Steps
 
 - Learn about the [Trusted Data Format](/explanation/trusted-data-format) that makes this possible
-- Understand [how OpenTDF fits into Zero-Trust architecture](/explanation/data-centric-security/zero-trust-architecture) 
+- Understand [how OpenTDF fits into Zero-Trust architecture](/explanation/data-centric-security/zero-trust-architecture)
 - See the [benefits compared to traditional approaches](/explanation/data-centric-security/traditional-vs-data-centric)
-- Explore [real-world use cases](/explanation/data-centric-security/use-cases)
\ No newline at end of file
+- Explore [real-world use cases](/explanation/data-centric-security/use-cases)
diff --git a/docs/explanation/data-centric-security/traditional-vs-data-centric.md b/docs/explanation/data-centric-security/traditional-vs-data-centric.md
new file mode 100644
index 0000000..79dc098
--- /dev/null
+++ b/docs/explanation/data-centric-security/traditional-vs-data-centric.md
@@ -0,0 +1,215 @@
+# Traditional vs. Data-Centric Security
+
+Understanding the fundamental differences between traditional perimeter-based security and data-centric security is crucial for appreciating why OpenTDF represents such a significant advancement in data protection.
+
+## Traditional Perimeter-Based Security
+
+Traditional security models are built around the concept of **trusted networks** and **secure perimeters**:
+
+### Core Assumptions
+- **Network perimeter is secure**: Firewalls and network controls protect internal resources
+- **Inside is trusted**: Users and systems inside the network are generally trusted
+- **Outside is untrusted**: External networks and users require special access procedures
+- **Static access**: Permissions granted based on location and role, remain until revoked
+
+### Traditional Security Stack
+
+```mermaid
+graph TD
+    subgraph "Traditional Security Model"
+        FIREWALL[🔥 Network Firewall]
+        VPN[🔗 VPN Gateway]
+        IDS[👁️ Intrusion Detection]
+        AUTH[🔐 Network Authentication]
+        
+        subgraph "Secure Perimeter"
+            DB[(🗃️ Database)]
+            FILES[📁 File Servers]
+            APPS[💻 Applications]
+        end
+        
+        FIREWALL --> AUTH
+        VPN --> AUTH
+        IDS --> AUTH
+        AUTH --> DB
+        AUTH --> FILES
+        AUTH --> APPS
+    end
+    
+    EXTERNAL[🌐 External User] --> VPN
+    INTERNAL[👤 Internal User] --> AUTH
+```
+
+### Limitations of Traditional Approaches
+
+#### **1. Perimeter Erosion**
+Modern work patterns have fundamentally broken the perimeter model:
+
+| **Traditional Assumption** | **Modern Reality** |
+|---------------------------|-------------------|
+| Users work from office | Remote and hybrid work |
+| Corporate-owned devices | BYOD (Bring Your Own Device) |
+| Data stays on-premises | Cloud and SaaS applications |
+| Closed networks | Internet-connected everything |
+| Static infrastructure | Containerized, ephemeral services |
+
+#### **2. Data Mobility Problems**
+When data moves beyond the secure perimeter:
+
+- **Email attachments**: No control once sent
+- **Cloud storage**: Relies on third-party security
+- **Partner sharing**: Access controls don't transfer
+- **Mobile devices**: May not meet corporate security standards
+- **Offline access**: No way to revoke access to downloaded files
+
+#### **3. Insider Threat Blindness**
+Traditional models provide little protection against:
+
+- **Privileged users** with excessive access
+- **Compromised credentials** used from inside the network
+- **Data exfiltration** by legitimate users
+- **Accidental exposure** through oversharing
+
+## Data-Centric Security Model
+
+Data-centric security inverts the traditional model by making **data self-protecting**:
+
+### Core Principles
+- **Data is inherently protected**: Security travels with the data
+- **Zero trust**: No assumptions about network, location, or user
+- **Context-aware access**: Decisions based on real-time attributes
+- **Dynamic control**: Policies can be updated without touching data
+
+### Data-Centric Security Stack
+
+```mermaid
+graph TD
+    subgraph "Data-Centric Security Model"
+        TDF[🔒 Protected Data (TDF)]
+        POLICY[📋 Cryptographic Policies]
+        
+        subgraph "OpenTDF Platform"
+            KAS[🔑 Key Access Service]
+            AUTHZ[⚖️ Authorization Service]
+            ATTR[🏷️ Attribute Authority]
+        end
+        
+        TDF -.-> POLICY
+        POLICY --> KAS
+        KAS --> AUTHZ
+        AUTHZ --> ATTR
+    end
+    
+    ANYWHERE[🌍 Access from Anywhere] --> TDF
+    ANYTIME[⏰ Access at Any Time] --> TDF
+    ANYDEVICE[📱 Any Device] --> TDF
+```
+
+## Side-by-Side Comparison
+
+### **Data Protection**
+
+| **Aspect** | **Traditional** | **Data-Centric** |
+|------------|----------------|------------------|
+| **Protection Location** | Network perimeter | Bound to data object |
+| **Data Mobility** | Loses protection when shared | Protection travels with data |
+| **Access Control** | Network-based permissions | Cryptographic policy enforcement |
+| **Key Management** | Centralized, often static | Distributed, dynamic key access |
+| **Policy Updates** | Requires system changes | Real-time policy modifications |
+
+### **Access Patterns**
+
+| **Scenario** | **Traditional Approach** | **Data-Centric Approach** |
+|--------------|------------------------|--------------------------|
+| **Remote Access** | VPN required, full network access | Direct data access with per-object authorization |
+| **Partner Sharing** | Dedicated portals or VPN accounts | Share protected files directly |
+| **Mobile Devices** | MDM required, device enrollment | App-based access, device-agnostic |
+| **Cloud Migration** | Extend perimeter to cloud | Data protection independent of infrastructure |
+| **Offline Access** | Cached credentials, limited control | Cryptographic validation, full audit trail |
+
+### **Security Outcomes**
+
+| **Security Goal** | **Traditional** | **Data-Centric** |
+|------------------|----------------|------------------|
+| **Prevent Unauthorized Access** | Network controls | Cryptographic enforcement |
+| **Audit Data Access** | Network logs, often incomplete | Complete data access audit trail |
+| **Revoke Access** | Change network permissions | Immediate policy updates |
+| **Handle Compromised Systems** | Isolate compromised network segments | Individual data objects remain protected |
+| **Compliance** | Infrastructure-focused audits | Data-centric compliance evidence |
+
+## Real-World Comparison: Confidential Document
+
+Let's trace how a confidential financial report would be handled in each model:
+
+### **Traditional Security Scenario**
+
+1. **Creation**: Document saved on secure file server
+2. **Access Control**: Windows/LDAP permissions based on AD groups
+3. **Sharing Internal**: Users access via network share or email
+4. **Sharing External**: Upload to secure portal or send via encrypted email
+5. **Problems**:
+   - Email copy has no access controls
+   - Downloaded file can be freely shared
+   - No audit trail once file leaves network
+   - Cannot revoke access to existing copies
+
+### **Data-Centric Security Scenario**
+
+1. **Creation**: Document encrypted as TDF with policy "Finance team, business hours only"
+2. **Access Control**: Every open requires authorization check
+3. **Sharing Internal**: Share TDF file directly - policy travels with it
+4. **Sharing External**: Partner receives TDF file, authorization still required
+5. **Benefits**:
+   - All copies maintain protection
+   - Complete audit trail regardless of location
+   - Can revoke access in real-time
+   - Policy can be updated without re-encrypting
+
+## Migration Strategies
+
+### **Hybrid Approach**
+Most organizations transition gradually:
+
+1. **Start with high-value data**: Protect most sensitive documents first
+2. **Layer on existing security**: OpenTDF complements existing controls
+3. **Pilot with specific use cases**: External sharing, remote access scenarios
+4. **Expand coverage**: Gradually increase percentage of protected data
+
+### **Integration Points**
+Data-centric security integrates with traditional infrastructure:
+
+- **Identity providers**: Leverage existing LDAP, Active Directory, SAML
+- **Key management**: Can utilize existing HSMs and key vaults
+- **Audit systems**: Feed data access logs to existing SIEM platforms
+- **Applications**: SDK integration with minimal application changes
+
+## When to Choose Each Approach
+
+### **Traditional Security Still Appropriate For:**
+- **Network infrastructure** protection
+- **System administration** access
+- **Development environments** with low-sensitivity data
+- **Legacy applications** that cannot be modified
+
+### **Data-Centric Security Essential For:**
+- **Sensitive data sharing** with external parties
+- **Remote and mobile access** scenarios
+- **Cloud and multi-cloud** deployments
+- **Regulatory compliance** requirements (GDPR, HIPAA, etc.)
+- **Zero-trust architecture** implementations
+
+## The Future: Data-Centric by Default
+
+The industry trend is clear: data-centric security is becoming the default for sensitive information:
+
+- **Regulatory drivers**: Privacy laws require data protection, not just network security
+- **Business needs**: Digital transformation demands secure data sharing
+- **Threat landscape**: Advanced persistent threats bypass network controls
+- **Technology enablement**: Modern compute power makes cryptographic protection practical
+
+## Next Steps
+
+- Explore [specific use cases](use-cases) where data-centric security provides clear advantages
+- Learn about [Zero-Trust architecture integration](zero-trust-architecture) with OpenTDF
+- Understand the [platform architecture](/explanation/platform-architecture) that makes this possible
+- Try the [hands-on tutorial](/tutorials/your-first-tdf) to see data-centric security in action
\ No newline at end of file
diff --git a/docs/explanation/data-centric-security/use-cases.md b/docs/explanation/data-centric-security/use-cases.md
new file mode 100644
index 0000000..f2a6f30
--- /dev/null
+++ b/docs/explanation/data-centric-security/use-cases.md
@@ -0,0 +1,315 @@
+# Real-World Use Cases for Data-Centric Security
+
+Data-centric security with OpenTDF addresses challenges across industries and use cases where traditional perimeter-based security falls short. This page explores specific scenarios where OpenTDF provides clear advantages.
+
+## Financial Services
+
+### **Regulatory Compliance and Data Sharing**
+
+**Challenge**: Financial institutions must share sensitive customer data with regulators, auditors, and third-party service providers while maintaining strict compliance with regulations like SOX, PCI-DSS, and GDPR.
+
+**Traditional Approach Problems**:
+- Secure portals are cumbersome and limit data utility
+- Email encryption only protects data in transit
+- No control over data once it reaches external parties
+- Difficulty proving compliance with data handling requirements
+
+**OpenTDF Solution**:
+```mermaid
+graph LR
+    BANK[🏦 Bank] --> TDF[🔒 TDF Protected Data]
+    TDF --> REGULATOR[📋 Regulators]
+    TDF --> AUDITOR[🔍 Auditors]
+    TDF --> VENDOR[🏢 Service Providers]
+    
+    subgraph "Policy Controls"
+        ACCESS[Access: Business hours only]
+        AUDIT[Audit: All access logged]
+        REVOKE[Revocable: Instant policy updates]
+    end
+    
+    ACCESS -.-> TDF
+    AUDIT -.-> TDF
+    REVOKE -.-> TDF
+```
+
+**Implementation**:
+- Customer data encrypted as TDF with policies like "Auditor access during audit period only"
+- Real-time revocation when audit completes
+- Complete audit trail for compliance reporting
+- External parties receive protected data, not raw files
+
+**Outcomes**:
+- 95% reduction in time to share data securely
+- 100% audit trail coverage for regulatory compliance
+- Eliminated data exposure from uncontrolled sharing
+
+### **Cross-Border Data Transfer**
+
+**Challenge**: Global banks need to transfer customer data across jurisdictions while complying with data residency and privacy laws.
+
+**OpenTDF Solution**:
+- TDF policies enforce jurisdiction-specific access rules
+- Data can be physically stored in compliant locations
+- Access automatically denied if user location violates data residency requirements
+- Policy updates handle changing regulatory landscape
+
+## Healthcare
+
+### **Patient Data Sharing for Research**
+
+**Challenge**: Healthcare organizations want to participate in medical research while protecting patient privacy and maintaining HIPAA compliance.
+
+**Traditional Approach Problems**:
+- Data anonymization is complex and potentially reversible
+- Research partners require different levels of access
+- No way to audit how shared data is actually used
+- Difficulty revoking access if research terms change
+
+**OpenTDF Implementation**:
+```yaml
+# Example TDF Policy for Medical Research
+policy:
+  attributes:
+    - "data_type:patient_records"
+    - "study:cardiology_trial_2024"
+    - "sensitivity:phi"
+  rules:
+    - grant_if:
+        - user_role: "approved_researcher"
+        - location: "research_institution"
+        - purpose: "cardiology_study"
+        - time_limit: "2024-12-31"
+    - obligations:
+        - watermark: "Research Use Only - [USER_ID]"
+        - audit_frequency: "every_access"
+```
+
+**Outcomes**:
+- Researchers get access to necessary data without full patient records
+- Hospital maintains control even after data sharing
+- Complete audit trail for HIPAA compliance
+- Ability to revoke access if research ethics change
+
+### **Telemedicine and Remote Care**
+
+**Challenge**: COVID-19 accelerated telemedicine adoption, but sharing patient data with remote providers creates privacy and security risks.
+
+**OpenTDF Solution**:
+- Patient records protected as TDF files
+- Temporary access for consulting physicians
+- Location and device-based access controls
+- Automatic expiration after consultation period
+
+## Government and Defense
+
+### **Classified Information Sharing**
+
+**Challenge**: Intelligence agencies and defense contractors need to share classified information across organizations and security domains.
+
+**Traditional Approach Problems**:
+- Separate networks for each classification level
+- Physical media transfer for cross-domain sharing
+- Limited collaboration due to infrastructure constraints
+- Manual processes for declassification and sanitization
+
+**OpenTDF Implementation**:
+- Classification levels enforced through TDF policies
+- Cross-domain sharing without separate networks
+- Dynamic declassification through policy updates
+- Multi-level security through attribute-based policies
+
+**Example Policy Structure**:
+```yaml
+policy:
+  attributes:
+    - "classification:secret"
+    - "compartment:special_access_program"
+    - "nationality:us_only"
+  rules:
+    - grant_if:
+        - clearance_level: ">=secret"
+        - need_to_know: "special_access_program"
+        - citizenship: "us_citizen"
+        - location: "approved_facility"
+```
+
+### **Diplomatic Communications**
+
+**Challenge**: Diplomatic missions need secure communication that works across different IT infrastructures and potential adversarial environments.
+
+**OpenTDF Solution**:
+- Diplomatic cables protected with TDF
+- Access policies based on diplomatic rank and posting
+- Communication security independent of local IT infrastructure
+- Emergency revocation capabilities for crisis situations
+
+## Manufacturing and Supply Chain
+
+### **Intellectual Property Protection**
+
+**Challenge**: Manufacturing companies sharing design files and specifications with suppliers, partners, and offshore manufacturers while protecting intellectual property.
+
+**Traditional Problems**:
+- CAD files and specifications shared via email or portals
+- No control once files reach partner organizations
+- Industrial espionage and IP theft risks
+- Difficulty managing complex supply chain access needs
+
+**OpenTDF Solution**:
+```mermaid
+graph TD
+    OEM[🏭 OEM Manufacturer] --> TDF[🔒 Protected CAD Files]
+    
+    TDF --> SUPPLIER1[🔧 Supplier A: Engines only]
+    TDF --> SUPPLIER2[⚙️ Supplier B: Components only]  
+    TDF --> PARTNER[🤝 Joint Venture: Full access]
+    TDF --> OFFSHORE[🌏 Offshore: Limited time access]
+    
+    subgraph "Dynamic Policies"
+        PROJECT[Project-based access]
+        EXPIRY[Time-limited access]
+        LOCATION[Geographic restrictions]
+        AUDIT[Manufacturing audit trail]
+    end
+    
+    PROJECT -.-> TDF
+    EXPIRY -.-> TDF
+    LOCATION -.-> TDF
+    AUDIT -.-> TDF
+```
+
+**Implementation Example**:
+- CAD files protected with supplier-specific policies
+- "Engine supplier" can only access engine-related drawings
+- Access automatically expires when contract ends
+- Geographic restrictions prevent access from certain countries
+- Complete audit trail of who accessed what designs
+
+**Results**:
+- 80% reduction in IP theft incidents
+- Faster supplier onboarding with secure access
+- Improved collaboration without security compromises
+
+### **IoT and Sensor Data Protection**
+
+**Challenge**: Manufacturing IoT devices generate sensitive operational data that needs protection across supply chain and operational environments.
+
+**OpenTDF Solution (using NanoTDF)**:
+- Sensor data encrypted at source with lightweight NanoTDF
+- Production data protected even in multi-tenant cloud environments
+- Real-time policy updates for changing operational needs
+- Minimal overhead suitable for resource-constrained devices
+
+## Legal and Professional Services
+
+### **Attorney-Client Privilege Protection**
+
+**Challenge**: Law firms need to share privileged communications and documents with clients, co-counsel, and expert witnesses while maintaining attorney-client privilege.
+
+**Traditional Problems**:
+- Email encryption only protects transmission
+- Shared documents lose protection once downloaded
+- Difficulty managing access across multiple law firms
+- Risk of inadvertent privilege waiver through oversharing
+
+**OpenTDF Solution**:
+- Legal documents protected with TDF policies enforcing privilege rules
+- Access limited to authorized attorneys and clients
+- Automatic redaction capabilities based on user privileges
+- Complete audit trail to demonstrate privilege protection
+
+**Example Policy**:
+```yaml
+policy:
+  attributes:
+    - "privilege:attorney_client"
+    - "case:merger_2024"
+    - "sensitivity:highly_confidential"
+  rules:
+    - grant_if:
+        - role: "case_attorney"
+        - bar_admission: "active"
+        - conflict_check: "cleared"
+    - obligations:
+        - watermark: "ATTORNEY-CLIENT PRIVILEGED"
+        - no_forwarding: true
+        - audit_all_access: true
+```
+
+### **Cross-Border Legal Discovery**
+
+**Challenge**: International litigation requires sharing discovery documents across jurisdictions with different data protection laws.
+
+**OpenTDF Solution**:
+- Discovery documents protected with jurisdiction-aware policies
+- Automatic compliance with local data protection requirements
+- Selective disclosure based on relevance and privilege claims
+- Court-ordered access controls enforced cryptographically
+
+## Technology and SaaS
+
+### **Customer Data in Multi-Tenant SaaS**
+
+**Challenge**: SaaS providers need to protect customer data in multi-tenant environments while enabling necessary operational access.
+
+**OpenTDF Solution**:
+- Customer data protected with tenant-specific TDF policies
+- Support staff access limited by customer approval and audit requirements
+- Data protection independent of underlying cloud infrastructure
+- Customer retains control even over data in vendor systems
+
+### **DevOps and CI/CD Pipeline Security**
+
+**Challenge**: Protecting sensitive configuration, secrets, and code as they move through development, testing, and production pipelines.
+
+**OpenTDF Implementation**:
+- Configuration files and secrets protected as TDF
+- Environment-specific access policies (dev, staging, prod)
+- Automatic rotation and revocation capabilities
+- Audit trail for compliance and security monitoring
+
+## Key Success Patterns
+
+Across all these use cases, successful OpenTDF implementations share common characteristics:
+
+### **1. Start with High-Value, High-Risk Data**
+- Identify data that would cause significant harm if compromised
+- Focus on scenarios where traditional security has clear gaps
+- Demonstrate value with concrete business outcomes
+
+### **2. Integrate with Existing Workflows**
+- Minimize disruption to established business processes
+- Leverage existing identity and attribute systems
+- Provide familiar user experiences through SDK integration
+
+### **3. Plan for Policy Lifecycle Management**
+- Establish clear governance for policy creation and updates
+- Implement approval workflows for sensitive policy changes
+- Regular reviews and audits of policy effectiveness
+
+### **4. Measure and Monitor**
+- Track data access patterns and policy effectiveness
+- Monitor for unauthorized access attempts
+- Measure business impact: time savings, risk reduction, compliance costs
+
+## Implementation Considerations
+
+### **Technical Requirements**
+- Identity and attribute sources (LDAP, SAML, etc.)
+- Key management infrastructure
+- Application integration points
+- Audit and monitoring systems
+
+### **Organizational Requirements**
+- Policy governance processes
+- User training and change management
+- Legal and compliance review procedures
+- Incident response plan updates
+
+## Next Steps
+
+- Learn about the [technical architecture](/explanation/platform-architecture) that enables these use cases
+- Understand [Zero-Trust integration](zero-trust-architecture) for comprehensive security
+- Compare [traditional vs. data-centric](traditional-vs-data-centric) approaches in detail
+- Try implementing data protection for your use case in our [hands-on tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
diff --git a/docs/explanation/data-centric-security/zero-trust-architecture.md b/docs/explanation/data-centric-security/zero-trust-architecture.md
new file mode 100644
index 0000000..1a039e6
--- /dev/null
+++ b/docs/explanation/data-centric-security/zero-trust-architecture.md
@@ -0,0 +1,218 @@
+# Zero-Trust Architecture and OpenTDF
+
+Zero Trust represents a fundamental shift from traditional "trust but verify" security models to "never trust, always verify." OpenTDF is specifically designed to implement the data protection pillars of Zero Trust architecture, ensuring that data remains secure regardless of where it travels or who attempts to access it.
+
+## Zero Trust Principles
+
+Zero Trust architecture is built on several core principles:
+
+### 1. **Never Trust, Always Verify**
+Every access request must be authenticated, authorized, and encrypted, regardless of:
+- User location (inside or outside the network)
+- Device being used
+- Previous access history
+- Network security posture
+
+### 2. **Assume Breach**
+Operate under the assumption that:
+- The network perimeter is already compromised
+- Insider threats exist
+- Any system could be breached at any time
+- Traditional network controls are insufficient
+
+### 3. **Least Privilege Access**
+Grant users and applications:
+- Minimum access necessary to perform their job
+- Time-limited access when possible
+- Context-aware permissions based on risk assessment
+- Continuous monitoring and validation
+
+## How OpenTDF Enables Zero Trust
+
+OpenTDF implements Zero Trust specifically for data protection through several mechanisms:
+
+### **Cryptographic Policy Binding**
+
+Traditional security relies on network controls that can be bypassed. OpenTDF cryptographically binds access policies to data objects:
+
+```mermaid
+graph LR
+    subgraph "Traditional Zero Trust"
+        NET[Network Controls]
+        ID[Identity Verification]
+        DEV[Device Trust]
+    end
+    
+    subgraph "OpenTDF Zero Trust"
+        DATA[🔒 Self-Protecting Data]
+        POLICY[📋 Cryptographic Policy]
+        KEYS[🔑 Distributed Key Management]
+    end
+    
+    DATA -.-> POLICY
+    POLICY -.-> KEYS
+    
+    classDef opentdf fill:#87CEEB,stroke:#4682B4,stroke-width:2px
+    class DATA,POLICY,KEYS opentdf
+```
+
+### **Continuous Authorization**
+
+Unlike traditional access controls that grant broad permissions, OpenTDF enforces authorization on every data access:
+
+- **Real-time policy evaluation** for each access attempt
+- **Dynamic attribute checking** based on current context
+- **Immediate policy updates** without re-encrypting data
+- **Granular permissions** down to individual data objects
+
+### **Context-Aware Access Control**
+
+OpenTDF policies can incorporate Zero Trust contextual factors:
+
+```yaml
+# Example TDF Policy with Zero Trust Attributes
+policy:
+  attributes:
+    - "classification:confidential"
+    - "project:alpha"
+  rules:
+    - grant_if:
+        - user_role: "project_member" 
+        - device_compliance: "managed"
+        - location: "approved_countries"
+        - time: "business_hours"
+    - deny_if:
+        - risk_score: ">75"
+        - device_jailbroken: true
+```
+
+### **Zero Trust Data Mobility**
+
+Traditional Zero Trust often assumes data stays within controlled environments. OpenTDF extends Zero Trust protection to data wherever it goes:
+
+- **External sharing**: Partners and vendors receive protected data, not raw files
+- **Cloud migration**: Data protection independent of infrastructure
+- **Mobile access**: Consistent security across all devices and locations
+- **Offline scenarios**: Protection even when disconnected from central systems
+
+## Zero Trust + OpenTDF Architecture
+
+A complete Zero Trust implementation with OpenTDF typically includes:
+
+```mermaid
+graph TB
+    subgraph "Identity & Access"
+        IDP[Identity Provider]
+        MFA[Multi-Factor Auth]
+        RBA[Risk-Based Auth]
+    end
+    
+    subgraph "OpenTDF Platform"
+        AUTH[Authorization Service]
+        KAS[Key Access Server]
+        ATTR[Attribute Authority]
+    end
+    
+    subgraph "Protected Data"
+        TDF[🔒 TDF Files]
+        POLICY[📋 Policies]
+        AUDIT[📊 Audit Logs]
+    end
+    
+    subgraph "Clients & Applications"
+        SDK[OpenTDF SDK]
+        APP[Applications]
+        USERS[End Users]
+    end
+    
+    IDP --> AUTH
+    MFA --> AUTH
+    RBA --> AUTH
+    
+    AUTH --> KAS
+    ATTR --> AUTH
+    
+    KAS --> TDF
+    POLICY --> TDF
+    
+    SDK --> AUTH
+    SDK --> KAS
+    APP --> SDK
+    USERS --> APP
+    
+    classDef identity fill:#FFE4B5
+    classDef opentdf fill:#87CEEB
+    classDef data fill:#98FB98
+    classDef client fill:#F0E68C
+    
+    class IDP,MFA,RBA identity
+    class AUTH,KAS,ATTR opentdf
+    class TDF,POLICY,AUDIT data
+    class SDK,APP,USERS client
+```
+
+## Real-World Zero Trust Scenarios
+
+### **Remote Work Security**
+
+**Challenge**: Employees access sensitive data from unmanaged devices and networks.
+
+**OpenTDF Solution**:
+- Data protected with TDF regardless of access location
+- Policies enforce device compliance requirements
+- VPN not required - data is inherently protected
+- Real-time policy updates for changing threat landscape
+
+### **Third-Party Collaboration**
+
+**Challenge**: Sharing sensitive data with partners while maintaining control.
+
+**OpenTDF Solution**:
+- Partners receive TDF files, not raw data
+- Access automatically expires after project completion
+- Audit trail shows exactly how partners used the data
+- Revocation possible even after data has been shared
+
+### **Cloud Migration**
+
+**Challenge**: Maintaining security posture when moving to cloud providers.
+
+**OpenTDF Solution**:
+- Data protection independent of cloud provider security
+- Encryption keys managed separately from data storage
+- Consistent policy enforcement across multi-cloud environments
+- No vendor lock-in for security controls
+
+## Benefits of OpenTDF in Zero Trust
+
+1. **Data-Centric Protection**: Security travels with data, not just systems
+2. **Reduced Attack Surface**: Encrypted data useless without proper authorization
+3. **Simplified Compliance**: Built-in audit trails and policy enforcement
+4. **Operational Flexibility**: Share data safely without complex infrastructure
+5. **Future-Proof Security**: Standards-based approach adaptable to new threats
+
+## Implementation Considerations
+
+When implementing OpenTDF as part of Zero Trust strategy:
+
+### **Start with High-Value Data**
+- Identify most sensitive data assets
+- Implement TDF protection for critical documents first
+- Expand coverage based on risk assessment
+
+### **Integrate with Existing Identity Systems**
+- Leverage current identity providers and attribute sources
+- Align TDF policies with existing role-based access controls
+- Ensure consistent user experience across systems
+
+### **Plan for Policy Management**
+- Establish clear governance for TDF policy creation
+- Define approval workflows for policy changes
+- Implement regular policy reviews and updates
+
+## Next Steps
+
+- Learn about [traditional vs. data-centric security approaches](traditional-vs-data-centric)
+- Explore [real-world use cases](use-cases) for OpenTDF in Zero Trust environments
+- Understand the [platform architecture](/explanation/platform-architecture) that enables these capabilities
+- Try implementing Zero Trust data protection in our [tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
diff --git a/docs/explanation/index.mdx b/docs/explanation/index.mdx
index b29d84a..9c912f8 100644
--- a/docs/explanation/index.mdx
+++ b/docs/explanation/index.mdx
@@ -27,7 +27,7 @@ OpenTDF is a comprehensive platform for implementing **data-centric security** u
     {
       name: "Attribute-Based Access Control",
       description: "Explore how ABAC enables fine-grained, flexible access control using attributes, policies, and entitlements.",
-      url: "/reference/specifications/concepts/access_control",
+      url: "/reference/trusted-data-format/specifications/concepts/access_control",
     },
     {
       name: "Platform Architecture",
diff --git a/docs/explanation/platform-architecture/_category_.json b/docs/explanation/platform-architecture/_category_.json
deleted file mode 100644
index 21b42b4..0000000
--- a/docs/explanation/platform-architecture/_category_.json
+++ /dev/null
@@ -1,8 +0,0 @@
-{
-  "label": "Platform Architecture",
-  "position": 4,
-  "link": {
-    "type": "generated-index",
-    "description": "Understand how OpenTDF's core services work together to implement data-centric security using the NIST ABAC model."
-  }
-}
\ No newline at end of file
diff --git a/docs/components/_category_.json b/docs/explanation/platform-architecture/components/_category_.json
similarity index 96%
rename from docs/components/_category_.json
rename to docs/explanation/platform-architecture/components/_category_.json
index 5cbe449..5a3a89f 100644
--- a/docs/components/_category_.json
+++ b/docs/explanation/platform-architecture/components/_category_.json
@@ -1,6 +1,6 @@
 {
   "label": "Components and Services",
-  "position": 3,
+  "position": 2,
   "link": {
     "type": "generated-index",
     "description": "Authorization, Policy, Entity Resolution, Key Access, and a comprehensive command line are the key elements that make up the OpenTDF platform. These components work together to enforce attribute-based access control, manage cryptographic keys, and support secure data sharing through the use of the Trusted Data Format (TDF)."
diff --git a/docs/components/authorization.md b/docs/explanation/platform-architecture/components/authorization.md
similarity index 100%
rename from docs/components/authorization.md
rename to docs/explanation/platform-architecture/components/authorization.md
diff --git a/docs/components/core/authz.md b/docs/explanation/platform-architecture/components/core/authz.md
similarity index 100%
rename from docs/components/core/authz.md
rename to docs/explanation/platform-architecture/components/core/authz.md
diff --git a/docs/components/core/index.md b/docs/explanation/platform-architecture/components/core/index.md
similarity index 100%
rename from docs/components/core/index.md
rename to docs/explanation/platform-architecture/components/core/index.md
diff --git a/docs/components/entity_resolution.md b/docs/explanation/platform-architecture/components/entity_resolution.md
similarity index 100%
rename from docs/components/entity_resolution.md
rename to docs/explanation/platform-architecture/components/entity_resolution.md
diff --git a/docs/components/key_access.md b/docs/explanation/platform-architecture/components/key_access.md
similarity index 89%
rename from docs/components/key_access.md
rename to docs/explanation/platform-architecture/components/key_access.md
index ee6e49c..ec219fc 100644
--- a/docs/components/key_access.md
+++ b/docs/explanation/platform-architecture/components/key_access.md
@@ -35,8 +35,8 @@ KAS offers the following RPC methods:
 <img src="/img/kas_tdf_flow.svg" alt="KAS TDF Rewrap"/>
 
 1. The client extracts two pieces of information from the TDF:
-   1. [Key Access Object (KAO)](/spec/schema/opentdf/key_access_object): This contains the wrapped key and the policy binding.
-   2. The [Policy](/spec/schema/opentdf/policy) from the manifest.
+   1. [Key Access Object (KAO)](/reference/trusted-data-format/specifications/schema/opentdf/key_access_object): This contains the wrapped key and the policy binding.
+   2. The [Policy](/reference/trusted-data-format/specifications/schema/opentdf/policy) from the manifest.
 
 2. The client generates an ephemeral asymmetric key pair, used to wrap the KAO content (such as an AES encryption key that can access the TDF payload) from KAS.
 
@@ -84,7 +84,7 @@ At this point, the client is ready to make the rewrap request. The following is
 
 NanoTDF leverages the same KAS Rewrap Endpoint but the request body differs slightly from a TDF Rewrap call. 
 
-1. The client extracts the NanoTDF [Header](/spec/schema/nanotdf#331-header) and from that Header extracts the KAS URL.
+1. The client extracts the NanoTDF [Header](/reference/trusted-data-format/specifications/schema/nanotdf#331-header) and from that Header extracts the KAS URL.
 
 2. The client generates an ephemeral asymmetric key pair, used to wrap the shared secret originally generated on NanoTDF creation.
 
@@ -129,7 +129,7 @@ NanoTDF leverages the same KAS Rewrap Endpoint but the request body differs slig
     }
     ```
 
-1. KAS extracts the encrypted policy in the NanoTDF [Header](/spec/schema/nanotdf#331-header) and verifies the policy binding. 
+1. KAS extracts the encrypted policy in the NanoTDF [Header](/reference/trusted-data-format/specifications/schema/nanotdf#331-header) and verifies the policy binding.
   - If ECDSA Binding is enabled KAS will verify the use ECDSA to verify the signature otherwise it defaults to comparing the `GMAC`
 
 2. If the policy is valid and untampered, KAS calls the [Authorization Service](./authorization) to confirm whether the entity is allowed access to the NanoTDF. If authorized, KAS generates a new shared key with the clients ephemeral public key and uses `AES-GCM` to encrypt the shared secret used to encrypt the NanoTDF payload.
diff --git a/docs/components/policy/actions.md b/docs/explanation/platform-architecture/components/policy/actions.md
similarity index 100%
rename from docs/components/policy/actions.md
rename to docs/explanation/platform-architecture/components/policy/actions.md
diff --git a/docs/components/policy/attributes.md b/docs/explanation/platform-architecture/components/policy/attributes.md
similarity index 98%
rename from docs/components/policy/attributes.md
rename to docs/explanation/platform-architecture/components/policy/attributes.md
index 484b776..f1ceef0 100644
--- a/docs/components/policy/attributes.md
+++ b/docs/explanation/platform-architecture/components/policy/attributes.md
@@ -102,4 +102,4 @@ Unsafe actions on policy attributes include:
   - Reactivation (does not bubble up to reactivate the definition or namespace).
   - Deletion (permanently removes the value without affecting the parent definition or namespace).
 
-These mutations can retroactively change access to existing and new TDFs, making it crucial to handle them with caution.
\ No newline at end of file
+These mutations can retroactively change access to existing and new TDFs, making it crucial to handle them with caution.
diff --git a/docs/components/policy/index.md b/docs/explanation/platform-architecture/components/policy/index.md
similarity index 95%
rename from docs/components/policy/index.md
rename to docs/explanation/platform-architecture/components/policy/index.md
index d9bd936..53fc383 100644
--- a/docs/components/policy/index.md
+++ b/docs/explanation/platform-architecture/components/policy/index.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy
+slug: /explanation/platform-architecture/components/policy
 ---
 # Policy
 
diff --git a/docs/components/policy/key_access_grants.md b/docs/explanation/platform-architecture/components/policy/key_access_grants.md
similarity index 99%
rename from docs/components/policy/key_access_grants.md
rename to docs/explanation/platform-architecture/components/policy/key_access_grants.md
index 4aeeca2..ec6d29a 100644
--- a/docs/components/policy/key_access_grants.md
+++ b/docs/explanation/platform-architecture/components/policy/key_access_grants.md
@@ -6,7 +6,7 @@ In v0.7.0 of the platform creating grants is now deprecated in favor of
 will error when attempting to assign key access servers to attributes.
 :::
 
-If you currently have Key Access Grants defined, it is recommended to follow the [migration steps](./key_access_grants.md#migration-to-key-mappings).
+If you currently have Key Access Grants defined, it is recommended to follow the [migration steps](#migration-to-key-mappings).
 
 :::warning
 All migration steps should be completed in one go. As soon as a new key map is created, kas-grants are no longer used; this might result in TDFs being generated without the correct keys being used if the migration is not completed.
diff --git a/docs/components/policy/key_access_registry.md b/docs/explanation/platform-architecture/components/policy/key_access_registry.md
similarity index 100%
rename from docs/components/policy/key_access_registry.md
rename to docs/explanation/platform-architecture/components/policy/key_access_registry.md
diff --git a/docs/components/policy/keymanagement/base_key.md b/docs/explanation/platform-architecture/components/policy/keymanagement/base_key.md
similarity index 95%
rename from docs/components/policy/keymanagement/base_key.md
rename to docs/explanation/platform-architecture/components/policy/keymanagement/base_key.md
index 35c3efd..20a8775 100644
--- a/docs/components/policy/keymanagement/base_key.md
+++ b/docs/explanation/platform-architecture/components/policy/keymanagement/base_key.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy/keymanagement/base_key
+slug: /explanation/platform-architecture/components/policy/keymanagement/base_key
 ---
 
 # Base Key
diff --git a/docs/components/policy/keymanagement/index.md b/docs/explanation/platform-architecture/components/policy/keymanagement/index.md
similarity index 97%
rename from docs/components/policy/keymanagement/index.md
rename to docs/explanation/platform-architecture/components/policy/keymanagement/index.md
index 0176cb2..6aee0b2 100644
--- a/docs/components/policy/keymanagement/index.md
+++ b/docs/explanation/platform-architecture/components/policy/keymanagement/index.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy/keymanagement
+slug: /explanation/platform-architecture/components/policy/keymanagement
 ---
 
 # Key Management
diff --git a/docs/components/policy/keymanagement/key_managers.md b/docs/explanation/platform-architecture/components/policy/keymanagement/key_managers.md
similarity index 97%
rename from docs/components/policy/keymanagement/key_managers.md
rename to docs/explanation/platform-architecture/components/policy/keymanagement/key_managers.md
index a7f12a4..437af92 100644
--- a/docs/components/policy/keymanagement/key_managers.md
+++ b/docs/explanation/platform-architecture/components/policy/keymanagement/key_managers.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy/keymanagement/key_managers
+slug: /explanation/platform-architecture/components/policy/keymanagement/key_managers
 ---
 
 # Key Managers
diff --git a/docs/components/policy/keymanagement/key_mappings.md b/docs/explanation/platform-architecture/components/policy/keymanagement/key_mappings.md
similarity index 96%
rename from docs/components/policy/keymanagement/key_mappings.md
rename to docs/explanation/platform-architecture/components/policy/keymanagement/key_mappings.md
index d394f7a..81bb49c 100644
--- a/docs/components/policy/keymanagement/key_mappings.md
+++ b/docs/explanation/platform-architecture/components/policy/keymanagement/key_mappings.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy/keymanagement/key_mappings
+slug: /explanation/platform-architecture/components/policy/keymanagement/key_mappings
 ---
 
 # Key mappings
diff --git a/docs/components/policy/keymanagement/quickstart.md b/docs/explanation/platform-architecture/components/policy/keymanagement/quickstart.md
similarity index 99%
rename from docs/components/policy/keymanagement/quickstart.md
rename to docs/explanation/platform-architecture/components/policy/keymanagement/quickstart.md
index e7974cd..98b5ec1 100644
--- a/docs/components/policy/keymanagement/quickstart.md
+++ b/docs/explanation/platform-architecture/components/policy/keymanagement/quickstart.md
@@ -1,6 +1,6 @@
 ---
 sidebar_position: 1
-slug: /components/policy/keymanagement/quickstart
+slug: /explanation/platform-architecture/components/policy/keymanagement/quickstart
 ---
 
 # Quickstart for using the new key management architecture
diff --git a/docs/components/policy/registered_resources.md b/docs/explanation/platform-architecture/components/policy/registered_resources.md
similarity index 100%
rename from docs/components/policy/registered_resources.md
rename to docs/explanation/platform-architecture/components/policy/registered_resources.md
diff --git a/docs/components/policy/resource_mappings.md b/docs/explanation/platform-architecture/components/policy/resource_mappings.md
similarity index 100%
rename from docs/components/policy/resource_mappings.md
rename to docs/explanation/platform-architecture/components/policy/resource_mappings.md
diff --git a/docs/components/policy/subject_mappings.md b/docs/explanation/platform-architecture/components/policy/subject_mappings.md
similarity index 100%
rename from docs/components/policy/subject_mappings.md
rename to docs/explanation/platform-architecture/components/policy/subject_mappings.md
diff --git a/docs/explanation/platform-architecture/index.md b/docs/explanation/platform-architecture/index.md
index 1565510..521fd0c 100644
--- a/docs/explanation/platform-architecture/index.md
+++ b/docs/explanation/platform-architecture/index.md
@@ -2,7 +2,7 @@
 sidebar_position: 3
 ---
 
-# Architecture
+# Platform Architecture
 
 OpenTDF is built on a flexible, service-oriented architecture designed for robust and fine-grained access control. The platform consists of four core components that work together to protect data throughout its lifecycle. This architecture aligns with the well-established [National Institute of Standards and Technology (NIST)](https://www.nist.gov) model for [Attribute-Based Access Control (ABAC)](https://csrc.nist.gov/projects/attribute-based-access-control), ensuring a standards-based and interoperable approach.
 
@@ -46,37 +46,37 @@ graph TD
     class POLICY,AUTHZ,ERS,KAS opentdfService
     class ATTR_SOURCES,IDP,CLIENT externalSystem
 
-    click POLICY "components/policy/" "Go to Policy Service docs"
-    click AUTHZ "components/authorization" "Go to Authorization Service docs"
-    click ERS "components/entity_resolution" "Go to Entity Resolution Service docs"
-    click KAS "components/key_access" "Go to Key Access Server docs"
+    click POLICY "./components/policy/" "Go to Policy Service docs"
+    click AUTHZ "./components/authorization" "Go to Authorization Service docs"
+    click ERS "./components/entity_resolution" "Go to Entity Resolution Service docs"
+    click KAS "./components/key_access" "Go to Key Access Server docs"
 ```
 
-### [Policy Service](components/policy/)
+### [Policy Service](./components/policy/)
 
 The **Policy Service** is where all access control policies are defined and managed. It provides the tools and APIs to create a rich set of policies that govern data access. This includes not only attributes and their values, but also the definitions of **actions, obligations, and key access mappings**.
 
 In the context of the NIST ABAC model, the Policy Service functions as the **Policy Administration Point (PAP)**.
 
-### [Authorization Service](components/authorization)
+### [Authorization Service](./components/authorization)
 
 The **Authorization Service** is the core decision-making engine of the platform. It is responsible for evaluating the rich policies from the Policy Service against a set of attributes to render an authorization decision.
 
 In the context of the NIST ABAC model, it functions as the **Policy Decision Point (PDP)**.
 
-### [Entity Resolution Service (ERS)](components/entity_resolution)
+### [Entity Resolution Service (ERS)](./components/entity_resolution)
 
 The **Entity Resolution Service** is responsible for gathering the attributes about a subject needed for a decision. By default, it can derive attributes from claims in an authentication token. Optionally, it can be configured to connect to external attribute sources (LDAP, SQL) to "hydrate" the entity with more attributes.
 
 In the context of the NIST ABAC model, the ERS functions as the **Policy Information Point (PIP)**.
 
-### [Key Access Server (KAS)](components/key_access)
+### [Key Access Server (KAS)](./components/key_access)
 
 The **Key Access Server (KAS)** enforces access control decisions. Its role is more extensive than a typical enforcement point:
 
--   **Cryptographic Enforcement:** It enforces decisions by granting or withholding cryptographic keys for TDF decryption.
--   **Encryption Enablement:** It manages key exchanges and enables various TDF encryption modes.
+- **Cryptographic Enforcement:** It enforces decisions by granting or withholding cryptographic keys for TDF decryption.
+- **Encryption Enablement:** It manages key exchanges and enables various TDF encryption modes.
 
 In the context of the NIST ABAC model, the KAS functions as the **Policy Enforcement Point (PEP)**.
 
-Furthermore, the OpenTDF platform is designed for flexibility. Developers can **build and integrate their own custom PEPs**. These custom enforcement points can leverage the platform's robust Authorization (PDP) and Policy (PAP) services while implementing enforcement logic tailored to specific applications. These custom PEPs can also optionally interface with the KAS to take advantage of its powerful cryptographic capabilities.
\ No newline at end of file
+Furthermore, the OpenTDF platform is designed for flexibility. Developers can **build and integrate their own custom PEPs**. These custom enforcement points can leverage the platform's robust Authorization (PDP) and Policy (PAP) services while implementing enforcement logic tailored to specific applications. These custom PEPs can also optionally interface with the KAS to take advantage of its powerful cryptographic capabilities.
diff --git a/docs/explanation/trusted-data-format/cryptographic-binding.md b/docs/explanation/trusted-data-format/cryptographic-binding.md
new file mode 100644
index 0000000..5a81988
--- /dev/null
+++ b/docs/explanation/trusted-data-format/cryptographic-binding.md
@@ -0,0 +1,300 @@
+# Cryptographic Binding in TDF
+
+Cryptographic binding is the core innovation that makes TDF files self-protecting. Unlike traditional approaches where access controls exist separately from data, TDF cryptographically links policies directly to encrypted data, ensuring that security travels wherever the data goes.
+
+## What is Cryptographic Binding?
+
+Cryptographic binding means that access policies are mathematically tied to encrypted data through cryptographic mechanisms. The policy cannot be separated from the data without breaking the encryption, and the data cannot be decrypted without satisfying the policy requirements.
+
+```mermaid
+graph TD
+    subgraph "Traditional Approach"
+        DATA1[📄 Plaintext Data]
+        POLICY1[📋 Separate Policy]
+        STORAGE1[💾 File System ACLs]
+        
+        DATA1 -.-> STORAGE1
+        POLICY1 -.-> STORAGE1
+    end
+    
+    subgraph "TDF Cryptographic Binding"
+        DATA2[🔒 Encrypted Payload]
+        POLICY2[📋 Embedded Policy]
+        MANIFEST[📜 Signed Manifest]
+        
+        POLICY2 --> MANIFEST
+        DATA2 --> MANIFEST
+        MANIFEST -.-> TDF[🔐 TDF Container]
+    end
+    
+    classDef traditional fill:#FFE4B5,stroke:#DEB887
+    classDef tdf fill:#87CEEB,stroke:#4682B4,stroke-width:2px
+    
+    class DATA1,POLICY1,STORAGE1 traditional
+    class DATA2,POLICY2,MANIFEST,TDF tdf
+```
+
+## How Cryptographic Binding Works
+
+### 1. **Policy Integration During Encryption**
+
+When a TDF file is created, the access policy becomes an integral part of the encryption process:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant SDK as OpenTDF SDK
+    participant Policy as Policy Object
+    participant Crypto as Cryptographic Engine
+    participant TDF as TDF File
+    
+    App->>SDK: encrypt(data, policy)
+    SDK->>Policy: embed policy in manifest
+    SDK->>Crypto: generate data encryption key (DEK)
+    Crypto->>Crypto: encrypt data with DEK
+    SDK->>Policy: reference policy in key access info
+    SDK->>TDF: create TDF container
+    
+    Note over Policy,Crypto: Policy controls key access
+    Note over TDF: Policy travels with encrypted data
+```
+
+### 2. **Key Splitting and Policy Enforcement**
+
+TDF uses a split-key approach where the data encryption key (DEK) is protected by both cryptographic wrapping and policy enforcement:
+
+```yaml
+# TDF Manifest Structure (simplified)
+manifest:
+  encryptionInformation:
+    type: "split"
+    keyAccess:
+      - type: "wrapped"
+        url: "https://kas.example.com"
+        protocol: "kas"
+        wrappedKey: "encrypted_dek_material"
+  policy:
+    uuid: "policy-12345"
+    body:
+      dataAttributes:
+        - "https://example.com/attr/classification/secret"
+      dissem:
+        - "user@example.com"
+```
+
+The wrapped key can only be unwrapped by the Key Access Server (KAS) after policy validation.
+
+### 3. **Cryptographic Verification Chain**
+
+Every TDF access involves multiple cryptographic verifications:
+
+```mermaid
+graph TD
+    USER[👤 User Request] --> TDF[🔐 TDF File]
+    TDF --> VERIFY1{Verify TDF Integrity}
+    VERIFY1 --> POLICY[📋 Extract Policy]
+    POLICY --> KAS[🔑 Key Access Server]
+    KAS --> VERIFY2{Verify User Claims}
+    VERIFY2 --> AUTHZ[⚖️ Authorization Decision]
+    AUTHZ --> VERIFY3{Policy Satisfied?}
+    VERIFY3 -->|Yes| UNWRAP[🔓 Unwrap DEK]
+    VERIFY3 -->|No| DENY[❌ Access Denied]
+    UNWRAP --> DECRYPT[🔍 Decrypt Data]
+    
+    classDef verify fill:#FFE4B5,stroke:#DAA520
+    classDef success fill:#98FB98,stroke:#228B22
+    classDef failure fill:#FFB6C1,stroke:#DC143C
+    
+    class VERIFY1,VERIFY2,VERIFY3 verify
+    class UNWRAP,DECRYPT success
+    class DENY failure
+```
+
+## Types of Cryptographic Binding
+
+### **Strong Binding (Default)**
+- Policy embedded directly in TDF manifest
+- Signed manifest ensures integrity
+- Cannot modify policy without invalidating TDF
+- Suitable for most security-sensitive use cases
+
+### **Remote Policy Binding**
+- Policy UUID embedded in TDF, actual policy stored remotely
+- Allows for policy updates without re-encryption
+- Requires secure policy server infrastructure
+- Used for dynamic policy scenarios
+
+### **Hybrid Binding**
+- Core policy embedded, with references to external policy extensions
+- Balances security with flexibility
+- Common for complex organizational policies
+
+## Security Properties
+
+### **Integrity Protection**
+
+TDF manifest is cryptographically signed, ensuring:
+- **Policy tampering detection**: Any modification to embedded policies is detected
+- **Manifest authenticity**: Verification that TDF came from authorized source
+- **Version control**: Prevents downgrade attacks on policy versions
+
+```json
+{
+  "manifest": {
+    "payload": {
+      "type": "reference",
+      "url": "payload.bin",
+      "protocol": "zip",
+      "isEncrypted": true
+    },
+    "encryptionInformation": {...},
+    "policy": {...}
+  },
+  "signature": {
+    "algorithm": "HS256",
+    "keyAccess": {...},
+    "sig": "cryptographic_signature_here"
+  }
+}
+```
+
+### **Replay Attack Prevention**
+
+Each TDF contains unique cryptographic material:
+- **Unique DEKs**: Each TDF encrypted with unique data encryption key
+- **Nonce values**: Prevent cryptographic replay attacks
+- **Temporal binding**: Policies can include time-based restrictions
+
+### **Forward Security**
+
+Key management designed for forward security:
+- **Key rotation**: Regular rotation of key encryption keys (KEKs)
+- **Revocation support**: Ability to invalidate specific TDF access
+- **Perfect forward secrecy**: Compromise of long-term keys doesn't affect past sessions
+
+## Implementation Details
+
+### **Key Wrapping Process**
+
+1. **Generate DEK**: Create unique symmetric key for data encryption
+2. **Encrypt data**: Use DEK to encrypt actual payload
+3. **Wrap DEK**: Encrypt DEK with KAS public key
+4. **Policy association**: Link wrapped DEK to specific policy requirements
+5. **Manifest creation**: Embed all information in signed manifest
+
+### **Policy Evaluation Integration**
+
+The cryptographic binding ensures policy evaluation is mandatory:
+
+```python
+# Pseudocode for TDF decryption
+def decrypt_tdf(tdf_file, user_context):
+    manifest = extract_and_verify_manifest(tdf_file)
+    
+    # Cryptographic binding ensures this step cannot be bypassed
+    policy = manifest.policy
+    key_access_info = manifest.encryption_info.key_access
+    
+    # Policy evaluation required for key unwrapping
+    decision = evaluate_policy(policy, user_context)
+    if not decision.permit:
+        raise AccessDeniedException(decision.reason)
+    
+    # Only after policy satisfaction can key be unwrapped
+    dek = request_key_unwrap(key_access_info, user_context, decision)
+    
+    # Finally decrypt data
+    return decrypt_payload(tdf_file.payload, dek)
+```
+
+## Advanced Binding Techniques
+
+### **Multi-Authority Binding**
+
+For high-security scenarios, TDF can require approval from multiple authorities:
+
+```yaml
+keyAccess:
+  - type: "wrapped"
+    url: "https://kas1.example.com"  # Authority 1
+    policy: "classification_policy"
+  - type: "wrapped" 
+    url: "https://kas2.example.com"  # Authority 2
+    policy: "need_to_know_policy"
+    
+# Requires BOTH authorities to approve access
+splitPolicy: "all_required"
+```
+
+### **Hierarchical Policy Binding**
+
+Policies can reference parent policies for organizational hierarchies:
+
+```yaml
+policy:
+  uuid: "project_alpha_secret"
+  inherits: 
+    - "organizational_base_policy"
+    - "project_alpha_policy" 
+  overrides:
+    - attribute: "classification"
+      value: "secret"
+```
+
+### **Conditional Cryptographic Binding**
+
+Policies can specify different cryptographic requirements based on context:
+
+```yaml
+encryptionPolicy:
+  default:
+    algorithm: "AES-256-GCM"
+    keySize: 256
+  highSecurity:
+    when: 
+      - classification: "top_secret"
+    algorithm: "AES-256-GCM"  
+    keySize: 256
+    additionalProtection: "HSM_required"
+```
+
+## Benefits Over Traditional Approaches
+
+### **Tamper Evidence**
+- Any modification to policy or binding detected through signature verification
+- Cryptographic proof of policy violations
+- Immutable audit trail of access decisions
+
+### **Zero Trust Data**
+- No reliance on network perimeter security
+- Data protection independent of storage location
+- Works equally well in untrusted environments
+
+### **Scalable Policy Enforcement**
+- No need for complex access control infrastructure at every storage location
+- Policy decisions centralized but enforcement distributed
+- Consistent policy application across heterogeneous environments
+
+## Limitations and Considerations
+
+### **Key Management Complexity**
+- Requires robust key management infrastructure
+- Key escrow and recovery procedures needed
+- Operational complexity higher than simple encryption
+
+### **Performance Considerations**
+- Additional cryptographic operations during access
+- Network calls to policy decision points
+- Caching strategies needed for acceptable performance
+
+### **Policy Update Challenges**
+- Strong binding means policy changes may require re-encryption
+- Remote policy binding trades security for flexibility
+- Version control and migration strategies essential
+
+## Next Steps
+
+- Understand the differences between [TDF and NanoTDF formats](tdf-vs-nanotdf)
+- Learn about the complete [TDF lifecycle](tdf-lifecycle) from creation to consumption
+- Explore [platform architecture](/explanation/platform-architecture) supporting cryptographic binding
+- Try creating cryptographically bound TDF files in our [hands-on tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
diff --git a/docs/explanation/trusted-data-format/index.md b/docs/explanation/trusted-data-format/index.md
index 0a96926..18d2bc0 100644
--- a/docs/explanation/trusted-data-format/index.md
+++ b/docs/explanation/trusted-data-format/index.md
@@ -58,23 +58,30 @@ sequenceDiagram
 ## Key Benefits of TDF
 
 ### 1. **Policy Travels with Data**
+
 Unlike traditional access controls that exist separately from data, TDF embeds the policy directly in the file. The policy goes wherever the data goes - shared folders, email attachments, cloud storage, partner networks.
 
 ### 2. **Fine-Grained Access Control**
+
 TDF policies use **Attribute-Based Access Control (ABAC)** to make nuanced decisions based on:
+
 - User attributes (role, clearance, department)
 - Environmental context (location, time, device)
 - Data classifications (sensitivity, project, compliance requirements)
 
 ### 3. **Real-Time Policy Updates**
+
 Even after a TDF is created and shared, policies can be updated in real-time:
+
 - Revoke access immediately if needed
 - Add new authorized users
 - Change access conditions (e.g., restrict to business hours)
 - Add obligations (e.g., watermarking requirements)
 
 ### 4. **Complete Audit Trail**
+
 Every access attempt is logged, providing:
+
 - Who tried to access what data
 - When and from where
 - Whether access was granted or denied
@@ -97,12 +104,14 @@ OpenTDF supports two format variants:
 Consider a medical research document:
 
 **Without TDF (Traditional):**
+
 - File encrypted with password or certificate
 - Access rules stored separately in system permissions
 - If shared outside system → no access control
 - No audit trail for external access
 
 **With TDF:**
+
 - File packaged as TDF with policy: "Only researchers with IRB approval can access"
 - Policy includes obligations: "Must watermark with user ID"
 - File can be safely shared with external partners
@@ -112,6 +121,7 @@ Consider a medical research document:
 ## Standards and Interoperability
 
 TDF is built on open standards:
+
 - **JSON-based manifest** for policy definition
 - **Standard encryption algorithms** (AES, RSA, ECC)
 - **NIST ABAC model** for access control
@@ -124,4 +134,4 @@ This ensures that TDF files can be processed by different implementations and in
 - Learn about [cryptographic binding](/explanation/trusted-data-format/cryptographic-binding) in detail
 - Understand the [TDF vs NanoTDF comparison](/explanation/trusted-data-format/tdf-vs-nanotdf)
 - See the complete [TDF lifecycle](/explanation/trusted-data-format/tdf-lifecycle) from creation to consumption
-- Try creating your first TDF in our [tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
+- Try creating your first TDF in our [tutorial](/tutorials/your-first-tdf)
diff --git a/docs/explanation/trusted-data-format/tdf-lifecycle.md b/docs/explanation/trusted-data-format/tdf-lifecycle.md
new file mode 100644
index 0000000..efea33f
--- /dev/null
+++ b/docs/explanation/trusted-data-format/tdf-lifecycle.md
@@ -0,0 +1,511 @@
+# TDF Lifecycle: From Creation to Consumption
+
+Understanding the complete lifecycle of a Trusted Data Format (TDF) file helps you implement effective data-centric security. This document traces a TDF from initial creation through consumption, policy updates, and eventual expiration, highlighting the key interactions with OpenTDF platform services.
+
+## Lifecycle Overview
+
+```mermaid
+graph TD
+    subgraph "1. Creation Phase"
+        CREATE[📝 Create TDF]
+        POLICY[📋 Define Policy]
+        ENCRYPT[🔒 Encrypt Data]
+    end
+    
+    subgraph "2. Distribution Phase"
+        SHARE[📤 Share TDF]
+        STORE[💾 Store/Transit]
+        RECEIVE[📥 Recipients Receive]
+    end
+    
+    subgraph "3. Access Phase"
+        REQUEST[🔓 Access Request]
+        VALIDATE[✅ Validate Policy]
+        DECRYPT[🔍 Decrypt & Access]
+    end
+    
+    subgraph "4. Management Phase"
+        UPDATE[🔄 Update Policies]
+        AUDIT[📊 Audit Access]
+        REVOKE[❌ Revoke Access]
+    end
+    
+    subgraph "5. Expiration Phase"
+        EXPIRE[⏰ Policy Expiry]
+        CLEANUP[🗑️ Key Cleanup]
+        ARCHIVE[📦 Archive Logs]
+    end
+    
+    CREATE --> SHARE
+    SHARE --> REQUEST
+    REQUEST --> UPDATE
+    UPDATE --> EXPIRE
+    EXPIRE --> CREATE
+    
+    classDef creation fill:#87CEEB
+    classDef distribution fill:#98FB98
+    classDef access fill:#FFE4B5
+    classDef management fill:#F0E68C
+    classDef expiration fill:#FFB6C1
+    
+    class CREATE,POLICY,ENCRYPT creation
+    class SHARE,STORE,RECEIVE distribution
+    class REQUEST,VALIDATE,DECRYPT access
+    class UPDATE,AUDIT,REVOKE management
+    class EXPIRE,CLEANUP,ARCHIVE expiration
+```
+
+## Phase 1: Creation
+
+### **Step 1: Data Preparation**
+
+The lifecycle begins when an application or user wants to protect data:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant App as Application
+    participant SDK as OpenTDF SDK
+    participant Data as Source Data
+    
+    User->>App: "Protect this document"
+    App->>Data: Read source data
+    Data-->>App: Raw content
+    App->>SDK: prepare_for_encryption(content)
+    SDK-->>App: Ready for policy binding
+```
+
+### **Step 2: Policy Definition**
+
+Policies can be defined inline or reference existing templates:
+
+```javascript
+// Example: Creating TDF with inline policy
+const policy = {
+  dataAttributes: [
+    "https://company.com/attr/classification/confidential",
+    "https://company.com/attr/department/legal"
+  ],
+  dissem: [
+    "lawyer1@firm.com",
+    "lawyer2@firm.com"
+  ],
+  conditions: [
+    {
+      operator: "dateRange", 
+      binding: "$.currentTime",
+      value: ["2024-01-01", "2024-12-31"]
+    }
+  ]
+};
+```
+
+### **Step 3: Encryption Process**
+
+The SDK orchestrates the encryption with platform services:
+
+```mermaid
+sequenceDiagram
+    participant SDK as OpenTDF SDK
+    participant KAS as Key Access Service
+    participant Policy as Policy Service
+    participant Crypto as Crypto Engine
+    
+    SDK->>Policy: register_policy(policy_definition)
+    Policy-->>SDK: policy_uuid
+    
+    SDK->>Crypto: generate_dek()
+    Crypto-->>SDK: data_encryption_key
+    
+    SDK->>Crypto: encrypt_data(content, dek)
+    Crypto-->>SDK: encrypted_payload
+    
+    SDK->>KAS: wrap_key(dek, policy_uuid)
+    KAS-->>SDK: wrapped_key_material
+    
+    SDK->>SDK: create_tdf_container(payload, policy, wrapped_key)
+    SDK-->>SDK: complete_tdf_file
+```
+
+### **Creation Artifacts**
+
+At the end of creation phase:
+
+```
+TDF File Contents:
+┌─────────────────────────────┐
+│ manifest.json               │
+│ ├─ policy: {...}           │
+│ ├─ keyAccess: [{...}]      │
+│ └─ payload: "payload.bin"  │
+├─────────────────────────────┤
+│ payload.bin (encrypted)     │
+└─────────────────────────────┘
+
+Platform Records:
+- Policy Service: Policy definition and UUID
+- Key Access Service: Wrapped key material
+- Audit Service: TDF creation event
+```
+
+## Phase 2: Distribution
+
+### **Secure Sharing**
+
+TDF files can be shared through any channel because protection is inherent:
+
+```mermaid
+graph LR
+    TDF[🔐 TDF File] --> EMAIL[📧 Email]
+    TDF --> CLOUD[☁️ Cloud Storage]
+    TDF --> PORTAL[🌐 Web Portal]
+    TDF --> MOBILE[📱 Mobile App]
+    TDF --> API[🔌 API Transfer]
+    
+    EMAIL --> RECIPIENT1[👤 Recipient 1]
+    CLOUD --> RECIPIENT2[👤 Recipient 2]
+    PORTAL --> RECIPIENT3[👤 Recipient 3]
+    MOBILE --> RECIPIENT4[👤 Recipient 4]
+    API --> RECIPIENT5[👤 Recipient 5]
+    
+    classDef tdf fill:#87CEEB
+    classDef channel fill:#98FB98
+    classDef recipient fill:#FFE4B5
+    
+    class TDF tdf
+    class EMAIL,CLOUD,PORTAL,MOBILE,API channel
+    class RECIPIENT1,RECIPIENT2,RECIPIENT3,RECIPIENT4,RECIPIENT5 recipient
+```
+
+### **Distribution Properties**
+
+- **Channel Agnostic**: Works over email, cloud storage, APIs, etc.
+- **No Special Infrastructure**: Recipients don't need secure channels
+- **Integrity Preserved**: Cryptographic signatures detect tampering
+- **Policy Travels**: Access controls remain with data everywhere
+
+## Phase 3: Access and Consumption
+
+### **Access Request Flow**
+
+When a user attempts to open a TDF file:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client as Client App/SDK
+    participant TDF as TDF File
+    participant KAS as Key Access Service
+    participant AuthZ as Authorization Service
+    participant Attrs as Attribute Authority
+    participant Audit as Audit Service
+    
+    User->>Client: "Open TDF file"
+    Client->>TDF: Read TDF manifest
+    TDF-->>Client: Policy & key access info
+    
+    Client->>KAS: Request key unwrapping
+    Note over Client,KAS: Includes user identity & context
+    
+    KAS->>AuthZ: Evaluate access policy
+    AuthZ->>Attrs: Fetch user attributes
+    Attrs-->>AuthZ: User attribute values
+    AuthZ->>AuthZ: Apply policy rules
+    AuthZ-->>KAS: Decision (permit/deny + obligations)
+    
+    alt Access Granted
+        KAS-->>Client: Unwrapped decryption key
+        Client->>TDF: Decrypt payload
+        TDF-->>Client: Decrypted content
+        Client-->>User: Display content
+        
+        KAS->>Audit: Log successful access
+    else Access Denied
+        KAS-->>Client: Access denied + reason
+        Client-->>User: Show denial message
+        
+        KAS->>Audit: Log denied access attempt
+    end
+```
+
+### **Context-Aware Access**
+
+Access decisions consider multiple factors:
+
+```yaml
+# Example access context evaluation
+access_context:
+  user:
+    identity: "john.doe@company.com"
+    roles: ["legal_counsel", "project_alpha"]
+    clearance: "confidential"
+    department: "legal"
+  
+  environment:
+    time: "2024-06-15T14:30:00Z"
+    location: "US"
+    device: "managed_laptop"
+    ip_address: "10.0.1.45"
+    network: "corporate_vpn"
+  
+  request:
+    action: "read"
+    purpose: "legal_review"
+    client: "company_document_viewer"
+    
+policy_evaluation:
+  - check: "user.roles contains 'legal_counsel'" → ✅ PASS
+  - check: "current_time within business_hours" → ✅ PASS  
+  - check: "location in ['US', 'UK']" → ✅ PASS
+  - check: "device.managed == true" → ✅ PASS
+  
+result: PERMIT with obligations ["watermark", "audit_all_actions"]
+```
+
+### **Obligation Enforcement**
+
+Policies can specify obligations that must be enforced during access:
+
+- **Watermarking**: Add user identification to displayed content
+- **Audit Logging**: Record all user actions with the data
+- **Usage Restrictions**: Prevent printing, screenshots, or copying
+- **Time Limits**: Automatically close access after specified duration
+
+## Phase 4: Policy Management
+
+### **Dynamic Policy Updates**
+
+One of TDF's key advantages is the ability to update policies without re-encrypting data:
+
+```mermaid
+sequenceDiagram
+    participant Admin as Policy Admin
+    participant Policy as Policy Service
+    participant KAS as Key Access Service
+    participant Client as Client Apps
+    participant Audit as Audit Service
+    
+    Admin->>Policy: Update policy rules
+    Policy->>Policy: Validate new policy
+    Policy->>KAS: Notify policy change
+    KAS->>KAS: Update access control cache
+    
+    Note over Policy,KAS: Policy change takes effect immediately
+    
+    Client->>KAS: Next access request
+    KAS->>Policy: Get current policy (updated)
+    Policy-->>KAS: New policy rules
+    KAS-->>Client: Apply new access decision
+    
+    KAS->>Audit: Log policy change impact
+```
+
+### **Common Policy Updates**
+
+#### **Adding New Users**
+```json
+{
+  "operation": "add_dissem",
+  "policy_uuid": "legal-doc-123",
+  "new_users": ["newlawyer@firm.com"],
+  "effective_immediately": true
+}
+```
+
+#### **Time-Based Restrictions**
+```json
+{
+  "operation": "update_conditions", 
+  "policy_uuid": "project-data-456",
+  "conditions": [
+    {
+      "operator": "dateRange",
+      "binding": "$.currentTime", 
+      "value": ["2024-01-01", "2024-06-30"]  // Shortened access window
+    }
+  ]
+}
+```
+
+#### **Emergency Revocation**
+```json
+{
+  "operation": "revoke_access",
+  "policy_uuid": "confidential-report-789",
+  "reason": "security_incident",
+  "effective_immediately": true
+}
+```
+
+### **Policy Versioning**
+
+Policies are versioned to maintain audit trails:
+
+```
+Policy Evolution:
+v1.0: Initial policy - Legal team access only
+v1.1: Added external counsel to dissemination list
+v1.2: Restricted access to business hours only  
+v1.3: Extended expiration date
+v2.0: Added geographic restrictions
+v2.1: Emergency revocation - all access suspended
+```
+
+## Phase 5: Audit and Monitoring
+
+### **Comprehensive Audit Trail**
+
+Every interaction with TDF data is logged:
+
+```mermaid
+graph TD
+    subgraph "Audit Events"
+        CREATE_EVENT[📝 TDF Creation]
+        ACCESS_EVENT[🔓 Access Attempts]
+        POLICY_EVENT[📋 Policy Changes]
+        KEY_EVENT[🔑 Key Operations]
+    end
+    
+    subgraph "Event Details"
+        WHO[👤 Who: User identity]
+        WHAT[📄 What: Resource/action]
+        WHEN[⏰ When: Timestamp]
+        WHERE[🌍 Where: Location/device]
+        WHY[❓ Why: Decision rationale]
+    end
+    
+    CREATE_EVENT --> WHO
+    ACCESS_EVENT --> WHO
+    POLICY_EVENT --> WHO
+    KEY_EVENT --> WHO
+    
+    WHO --> WHAT
+    WHAT --> WHEN
+    WHEN --> WHERE
+    WHERE --> WHY
+    
+    classDef audit fill:#FFE4B5
+    classDef detail fill:#98FB98
+    
+    class CREATE_EVENT,ACCESS_EVENT,POLICY_EVENT,KEY_EVENT audit
+    class WHO,WHAT,WHEN,WHERE,WHY detail
+```
+
+### **Audit Event Examples**
+
+```json
+// TDF Access Event
+{
+  "event_type": "tdf_access_request",
+  "timestamp": "2024-06-15T14:30:22Z",
+  "tdf_uuid": "legal-contract-123",
+  "user": {
+    "identity": "john.doe@firm.com",
+    "attributes": ["role:lawyer", "clearance:confidential"]
+  },
+  "context": {
+    "location": "US",
+    "device": "managed_laptop_456", 
+    "ip_address": "10.0.1.45"
+  },
+  "decision": {
+    "result": "permit",
+    "policy_version": "v2.1",
+    "obligations": ["watermark", "audit_actions"]
+  }
+}
+
+// Policy Change Event  
+{
+  "event_type": "policy_update",
+  "timestamp": "2024-06-15T09:15:30Z", 
+  "policy_uuid": "legal-contract-123",
+  "admin": "admin@firm.com",
+  "changes": {
+    "added_users": ["newlawyer@firm.com"],
+    "removed_conditions": ["geographic_restriction"]
+  },
+  "reason": "Project team expansion"
+}
+```
+
+## Phase 6: Expiration and Cleanup
+
+### **Natural Expiration**
+
+TDF access can expire based on policy conditions:
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant KAS as Key Access Service
+    participant Policy as Policy Service
+    participant Audit as Audit Service
+    
+    Client->>KAS: Access request for expired TDF
+    KAS->>Policy: Check policy conditions
+    Policy-->>KAS: Policy expired (date/condition based)
+    KAS-->>Client: Access denied - policy expired
+    KAS->>Audit: Log expiration-based denial
+    
+    Note over KAS,Policy: Keys remain available for audit/recovery
+```
+
+### **Administrative Cleanup**
+
+After policy expiration, administrators can clean up resources:
+
+```
+Cleanup Process:
+1. Identify expired policies
+2. Archive audit logs
+3. Backup key material for compliance
+4. Remove active key access capabilities
+5. Update policy status to "archived"
+```
+
+### **Long-Term Retention**
+
+Even after expiration, some data may be retained:
+
+- **Audit logs**: For compliance and forensic purposes
+- **Policy definitions**: Historical record of access controls
+- **Key escrow**: For legal discovery or data recovery
+- **Usage analytics**: For policy effectiveness analysis
+
+## Lifecycle Best Practices
+
+### **Creation Best Practices**
+
+1. **Policy Templates**: Use standardized policy templates for consistency
+2. **Least Privilege**: Start with minimal access, expand as needed
+3. **Clear Expiration**: Always set appropriate expiration dates
+4. **Meaningful Names**: Use descriptive policy and TDF identifiers
+
+### **Distribution Best Practices**
+
+1. **Channel Selection**: Choose appropriate sharing mechanisms
+2. **Recipient Preparation**: Ensure recipients have necessary client software
+3. **Clear Instructions**: Provide guidance on accessing protected data
+4. **Backup Channels**: Have alternative distribution methods ready
+
+### **Management Best Practices**
+
+1. **Regular Reviews**: Periodically review and update policies
+2. **Automated Expiration**: Use time-based expiration for temporary access
+3. **Emergency Procedures**: Have processes for immediate revocation
+4. **Change Documentation**: Document all policy changes with rationale
+
+### **Monitoring Best Practices**
+
+1. **Real-time Alerts**: Monitor for unusual access patterns
+2. **Regular Reporting**: Generate access and policy reports
+3. **Compliance Tracking**: Ensure audit logs meet regulatory requirements
+4. **Performance Monitoring**: Track TDF access performance and user experience
+
+## Next Steps
+
+- Learn about [cryptographic binding](cryptographic-binding) that enables this lifecycle
+- Compare [TDF vs NanoTDF](tdf-vs-nanotdf) lifecycle differences
+- Understand the [platform architecture](/explanation/platform-architecture) supporting the TDF lifecycle
+- Try managing the complete lifecycle in our [hands-on tutorial](/tutorials/your-first-tdf)
\ No newline at end of file
diff --git a/docs/explanation/trusted-data-format/tdf-vs-nanotdf.md b/docs/explanation/trusted-data-format/tdf-vs-nanotdf.md
new file mode 100644
index 0000000..5e006ef
--- /dev/null
+++ b/docs/explanation/trusted-data-format/tdf-vs-nanotdf.md
@@ -0,0 +1,352 @@
+# TDF vs. NanoTDF: Choosing the Right Format
+
+OpenTDF supports two format variants: the full Trusted Data Format (TDF) and Nano Trusted Data Format (NanoTDF). Each is optimized for different use cases, with tradeoffs between features, security granularity, and overhead. Understanding these differences helps you choose the right format for your specific requirements.
+
+## Format Overview
+
+```mermaid
+graph TB
+    subgraph "TDF (Full Format)"
+        TDF_MANIFEST[📜 Rich JSON Manifest]
+        TDF_POLICY[📋 Full ABAC Policies]
+        TDF_KEYS[🔑 Multiple Key Access Methods]
+        TDF_PAYLOAD[📦 Encrypted Payload]
+        
+        TDF_MANIFEST --> TDF_POLICY
+        TDF_MANIFEST --> TDF_KEYS
+        TDF_MANIFEST --> TDF_PAYLOAD
+    end
+    
+    subgraph "NanoTDF (Compact)"
+        NANO_HEADER[📝 Binary Header &lpar;~50 bytes&rpar;]
+        NANO_POLICY[🏷️ Simple Attribute Tags]
+        NANO_KEY[🔐 Single Key Access]
+        NANO_PAYLOAD[📁 Encrypted Data]
+        
+        NANO_HEADER --> NANO_POLICY
+        NANO_HEADER --> NANO_KEY
+        NANO_HEADER --> NANO_PAYLOAD
+    end
+    
+    classDef tdf fill:#87CEEB,stroke:#4682B4
+    classDef nano fill:#98FB98,stroke:#228B22
+    
+    class TDF_MANIFEST,TDF_POLICY,TDF_KEYS,TDF_PAYLOAD tdf
+    class NANO_HEADER,NANO_POLICY,NANO_KEY,NANO_PAYLOAD nano
+```
+
+## Side-by-Side Comparison
+
+| **Aspect** | **TDF (Full Format)** | **NanoTDF (Compact)** |
+|------------|----------------------|------------------------|
+| **Header Overhead** | ~1KB+ (JSON manifest) | ~50 bytes (binary header) |
+| **Policy Complexity** | Full ABAC with complex rules | Simple attribute-based checks |
+| **Key Management** | Multiple KAS, key splitting | Single KAS, simplified keys |
+| **Payload Size Impact** | Negligible for files >10KB | Significant for small payloads |
+| **Feature Set** | Complete feature set | Essential features only |
+| **Processing Speed** | Slower (JSON parsing) | Faster (binary operations) |
+| **Ideal Use Cases** | Documents, files, rich policies | IoT data, streams, simple policies |
+
+## Detailed Comparison
+
+### Size and Overhead
+
+#### TDF Format
+```
+[TDF File Structure]
+┌─────────────────────────────┐
+│ ZIP Container               │
+├─────────────────────────────┤
+│ manifest.json (~800-2000B)  │ ← JSON manifest
+├─────────────────────────────┤
+│ payload.bin (variable)      │ ← Encrypted data
+└─────────────────────────────┘
+```
+
+**Overhead characteristics**:
+- **Fixed cost**: ~1KB regardless of payload size
+- **Negligible impact**: For files > 10KB (overhead < 10%)
+- **JSON flexibility**: Human-readable, extensible structure
+- **Multiple files**: Can contain multiple encrypted objects
+
+#### **NanoTDF Format**
+```
+[NanoTDF Structure]
+┌──────────────────┐
+│ Header (18B)     │ ← Fixed header
+├──────────────────┤
+│ KAS Info (~20B)  │ ← Key access information
+├──────────────────┤
+│ Policy (~10B)    │ ← Compact policy representation
+├──────────────────┤
+│ Payload (var)    │ ← Encrypted data
+└──────────────────┘
+```
+
+**Overhead characteristics**:
+- **Fixed cost**: ~50 bytes total overhead
+- **Significant impact**: For payloads < 1KB (overhead can be 5-50%)
+- **Binary efficiency**: Optimized for minimal size
+- **Single object**: One encrypted payload per NanoTDF
+
+### **Policy Capabilities**
+
+#### **TDF Full Policies**
+
+Rich policy expression with complex logic:
+
+```json
+{
+  "policy": {
+    "uuid": "complex-policy-123",
+    "body": {
+      "dataAttributes": [
+        "https://example.com/attr/classification/secret",
+        "https://example.com/attr/project/alpha"
+      ],
+      "dissem": [
+        "user1@company.com",
+        "user2@company.com"
+      ],
+      "rules": [
+        {
+          "effect": "permit",
+          "condition": {
+            "and": [
+              {"equals": ["$.user.department", "engineering"]},
+              {"dateRange": ["$.current.time", "2024-01-01", "2024-12-31"]},
+              {"in": ["$.user.location", ["US", "CA", "UK"]]}
+            ]
+          }
+        }
+      ]
+    }
+  }
+}
+```
+
+**TDF Policy Features**:
+- **Complex conditions**: Boolean logic, date ranges, string matching
+- **Multiple attributes**: Combine many data and user attributes
+- **Obligations**: Watermarking, audit requirements, etc.
+- **Dynamic references**: External policy stores, attribute authorities
+- **Rich dissemination**: Complex sharing rules and workflows
+
+#### **NanoTDF Simple Policies**
+
+Compact attribute-based policies:
+
+```
+Header Structure (binary):
+┌─────────┬─────────┬─────────┬─────────┐
+│ Version │ KAS URL │ Policy  │ Binding │
+│ (3B)    │ (var)   │ (var)   │ (var)   │
+└─────────┴─────────┴─────────┴─────────┘
+
+Policy Section:
+- Attribute list: [attr1, attr2, attr3]
+- Simple logic: "user must have ALL attributes"
+- No complex conditions or obligations
+```
+
+**NanoTDF Policy Features**:
+- **Attribute lists**: Simple "user must have these attributes"
+- **Basic logic**: AND/OR operations only
+- **No conditions**: Cannot express complex temporal or contextual rules
+- **Fixed dissemination**: Predefined sharing patterns
+- **Performance optimized**: Fast evaluation for real-time scenarios
+
+### **Key Management**
+
+#### **TDF Key Management**
+```yaml
+# TDF supports multiple key access methods
+encryptionInformation:
+  keyAccess:
+    - type: "wrapped"
+      url: "https://kas1.company.com"
+      wrappedKey: "encrypted_key_material_1"
+      policy: "primary_policy"
+    - type: "remote" 
+      url: "https://kas2.partner.com"
+      keyId: "shared_key_reference"
+      policy: "partner_policy"
+    - type: "split"
+      threshold: 2
+      shares:
+        - url: "https://kas3.backup.com"
+        - url: "https://kas4.backup.com"
+```
+
+**TDF Key Features**:
+- **Multiple KAS servers**: Redundancy and multi-authority scenarios
+- **Key splitting**: Require multiple parties for access (threshold schemes)
+- **Hierarchical keys**: Key derivation and rotation strategies
+- **Mixed methods**: Different key access methods per policy requirement
+
+#### **NanoTDF Key Management**
+```
+Single KAS approach:
+┌─────────────────────────────────────┐
+│ KAS URL: https://kas.company.com    │
+│ Wrapped Key: [encrypted_dek]        │
+│ Policy Reference: [simple_policy]   │
+└─────────────────────────────────────┘
+```
+
+**NanoTDF Key Features**:
+- **Single KAS**: One key access server per NanoTDF
+- **Wrapped keys**: Simple key wrapping, no splitting
+- **Fast unwrapping**: Optimized for high-throughput scenarios
+- **Minimal metadata**: Reduced key management overhead
+
+## Use Case Guidelines
+
+### **Choose TDF (Full Format) When:**
+
+#### **Document and File Protection**
+- **Office documents**: Word, Excel, PDF files
+- **Large files**: Where 1KB overhead is negligible
+- **Rich sharing**: Complex dissemination workflows
+- **Compliance**: Detailed audit and policy requirements
+
+**Example**: Legal contracts shared with multiple law firms, each with different access levels and time restrictions.
+
+#### **Complex Policy Requirements**
+- **Multi-attribute decisions**: Combine user role, location, time, project, etc.
+- **Dynamic policies**: Policies that change without re-encryption
+- **Obligations**: Watermarking, audit logging, usage restrictions
+- **Multi-authority**: Require approval from multiple policy authorities
+
+**Example**: Classified intelligence documents requiring approval from multiple agencies based on clearance level, need-to-know, and operational context.
+
+#### **Enterprise Integration**
+- **Rich identity systems**: LDAP, Active Directory with many attributes
+- **Complex workflows**: Approval processes, escalation procedures
+- **Audit requirements**: Detailed compliance and regulatory reporting
+- **Multi-tenant**: Different policy sets per customer or division
+
+### **Choose NanoTDF When:**
+
+#### **IoT and Sensor Data**
+- **Small payloads**: Sensor readings, telemetry data
+- **High frequency**: Thousands of messages per second
+- **Resource constraints**: Limited CPU, memory, bandwidth
+- **Simple policies**: Basic attribute checking sufficient
+
+**Example**: Industrial sensors sending encrypted temperature readings where only maintenance personnel should have access.
+
+#### **Real-Time Streaming**
+- **Low latency**: Minimal processing overhead required
+- **High throughput**: Process thousands of objects per second
+- **Simple decisions**: Fast policy evaluation critical
+- **Embedded systems**: Constrained computing environments
+
+**Example**: Financial trading systems encrypting market data feeds with role-based access controls.
+
+#### **Mobile and Edge Computing**
+- **Bandwidth constraints**: Minimize data transfer overhead
+- **Battery life**: Reduce computational overhead
+- **Simple policies**: Basic user/role-based access
+- **Offline scenarios**: Simplified policy evaluation when disconnected
+
+**Example**: Field service applications protecting customer data on mobile devices with limited connectivity.
+
+## Migration and Interoperability
+
+### **Format Selection Strategy**
+
+1. **Assess overhead tolerance**:
+   - Payload size distribution
+   - Network bandwidth constraints
+   - Storage cost considerations
+
+2. **Evaluate policy complexity**:
+   - Current access control requirements
+   - Future policy evolution needs
+   - Compliance and audit requirements
+
+3. **Consider performance requirements**:
+   - Throughput and latency needs
+   - Processing power constraints
+   - Real-time vs. batch processing
+
+### **Hybrid Deployments**
+
+Many organizations use both formats:
+
+```mermaid
+graph TD
+    subgraph "Document Management"
+        DOCS[📄 Office Documents] --> TDF[TDF Format]
+        REPORTS[📊 Reports] --> TDF
+    end
+    
+    subgraph "IoT Platform" 
+        SENSORS[📡 Sensor Data] --> NANO[NanoTDF Format]
+        TELEMETRY[📈 Telemetry] --> NANO
+    end
+    
+    subgraph "OpenTDF Platform"
+        KAS[🔑 Key Access Service]
+        POLICY[📋 Policy Service]
+        AUDIT[📋 Audit Service]
+    end
+    
+    TDF --> KAS
+    NANO --> KAS
+    TDF --> POLICY
+    NANO --> POLICY
+    TDF --> AUDIT
+    NANO --> AUDIT
+    
+    classDef tdf fill:#87CEEB
+    classDef nano fill:#98FB98
+    classDef platform fill:#FFE4B5
+    
+    class DOCS,REPORTS,TDF tdf
+    class SENSORS,TELEMETRY,NANO nano
+    class KAS,POLICY,AUDIT platform
+```
+
+### **Format Conversion**
+
+Converting between formats requires re-encryption:
+
+**TDF → NanoTDF**:
+- Simplify policy to attribute-only checks
+- Convert to single KAS if using multiple
+- Re-encrypt payload with NanoTDF format
+- Verify policy equivalence
+
+**NanoTDF → TDF**:
+- Expand simple policies to full ABAC format
+- Add rich policy context if needed
+- Re-encrypt with full TDF structure
+- Enhance with additional metadata
+
+## Implementation Considerations
+
+### **SDK Support**
+- **Full TDF**: Supported in all OpenTDF SDKs
+- **NanoTDF**: Available in performance-optimized SDKs
+- **Auto-selection**: Some SDKs choose format based on payload size
+
+### **Performance Testing**
+Always benchmark with your specific:
+- **Payload sizes**: Test with representative data
+- **Policy complexity**: Measure evaluation times
+- **Network conditions**: Consider latency and bandwidth
+- **Processing power**: Test on target hardware
+
+### **Future Evolution**
+- **NanoTDF v2**: Enhanced features while maintaining compact size
+- **Hybrid formats**: Best of both approaches
+- **Auto-optimization**: Dynamic format selection based on context
+
+## Next Steps
+
+- Learn about the complete [TDF lifecycle](tdf-lifecycle) covering both formats
+- Understand [cryptographic binding](cryptographic-binding) mechanisms in each format
+- Explore the [platform architecture](/explanation/platform-architecture) supporting both formats
+- Try both formats in our [hands-on tutorial](/tutorials/your-first-tdf) to see the differences
\ No newline at end of file
diff --git a/docs/index.mdx b/docs/index.mdx
index 35fab27..1f6082e 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 1
 title: OpenTDF - Protect the Data, Build the Future
 description: Persistent data centric security that extends owner control wherever data travels.
 keywords:
diff --git a/docs/appendix/_category_.yaml b/docs/reference/appendix/_category_.yaml
similarity index 100%
rename from docs/appendix/_category_.yaml
rename to docs/reference/appendix/_category_.yaml
diff --git a/docs/appendix/matrix.mdx b/docs/reference/appendix/matrix.mdx
similarity index 100%
rename from docs/appendix/matrix.mdx
rename to docs/reference/appendix/matrix.mdx
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index 1877ee1..e5acf20 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -224,7 +224,7 @@ const config: Config = {
       {
         name: "otdfctl",
         id: "otdfctl",
-        outDir: "docs/components/cli",
+        outDir: "docs/explanation/platform-architecture/components/cli",
         sourceBaseUrl: listRemote.buildRepoRawBaseUrl(otdfctl),
         documents: listRemote.listDocuments(otdfctl, ["docs/man/**/*.md"], []),
         modifyContent: (filename, content) => {
@@ -293,7 +293,7 @@ ${rawContent}
         name: "platform-configuration", // used by CLI, must be path safe
         sourceBaseUrl:
           "https://raw.githubusercontent.com/opentdf/platform/main/docs/", // the base url for the markdown (gets prepended to all of the documents when fetching)
-        outDir: "docs/getting-started", // the base directory to output to.
+        outDir: "docs/how-to/getting-started", // the base directory to output to.
         documents: ["Configuring.md"], // the file names to download
         modifyContent: (filename, content) => {
           let updatedContent = content;
diff --git a/src/utils/spec-documentation.ts b/src/utils/spec-documentation.ts
index 9244d4e..14b8f7b 100644
--- a/src/utils/spec-documentation.ts
+++ b/src/utils/spec-documentation.ts
@@ -7,6 +7,9 @@ function createCategoryJsonFiles(outDir: string) {
   const fs = require('fs');
   const path = require('path');
   
+  // Calculate the relative doc ID based on outDir
+  const docIdBase = outDir.replace('docs/', '').replace(/\/$/, '');
+  
   const categories = [
     {
       path: `${outDir}/_category_.json`,
@@ -15,7 +18,7 @@ function createCategoryJsonFiles(outDir: string) {
         position: 10,
         link: {
           type: "doc",
-          id: "spec/index"
+          id: `${docIdBase}/index`
         }
       }
     },
@@ -43,7 +46,7 @@ function createCategoryJsonFiles(outDir: string) {
         position: 2,
         link: {
           type: "doc",
-          id: "spec/schema/index"
+          id: `${docIdBase}/schema/index`
         }
       }
     },
@@ -54,7 +57,7 @@ function createCategoryJsonFiles(outDir: string) {
         position: 1,
         link: {
           type: "doc",
-          id: "spec/schema/opentdf/index"
+          id: `${docIdBase}/schema/opentdf/index`
         }
       }
     }
@@ -92,7 +95,7 @@ function createCategoryJsonFiles(outDir: string) {
  * - {outDir}/schema
  * - {outDir}/index.md
  */
-export function getSpecDocumentationPlugins(outDir: string = "docs/spec"): PluginConfig[] {
+export function getSpecDocumentationPlugins(outDir: string = "docs/reference/trusted-data-format/specifications"): PluginConfig[] {
 
   createCategoryJsonFiles(outDir);
 
@@ -110,7 +113,7 @@ export function getSpecDocumentationPlugins(outDir: string = "docs/spec"): Plugi
           if (filename === "README.md") {
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../../static/img/"
+              "../../../../../static/img/"
             );
             updatedContent = updatedContent.replaceAll(
               "# nanotdf - a compact binary TDF format",
@@ -175,7 +178,7 @@ ${updatedContent}`,
           // Always apply the diagram path replacement first
           let updatedContent = content.replaceAll(
             "../../diagrams/",
-            "../../../../static/img/"
+            "../../../../../../static/img/"
           );
 
           // Configuration map for file-specific frontmatter and processing
@@ -310,7 +313,7 @@ ${finalContent ? finalContent : ""}`;
           if (filename === "README.md") {
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../../../static/img/"
+              "../../../../../../static/img/"
             );
             // Fix segment link to point to integrity_information.md
             updatedContent = updatedContent.replaceAll(
@@ -344,7 +347,7 @@ ${updatedContent}`,
             
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../static/img/"
+              "../../../static/img/"
             );
             updatedContent = updatedContent.replaceAll(
               "protocol/protocol.md",
@@ -396,7 +399,7 @@ ${updatedContent}`,
           if (filename === "README.md") {
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../static/img/"
+              "../../../../static/img/"
             );
             // Replace all case-insensitive references to OpenTDF/README.md and nanotdf/README.md with ./opentdf and ./nanotdf
             updatedContent = updatedContent.replace(
@@ -435,7 +438,7 @@ ${updatedContent}`,
             
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../static/img/"
+              "../../../../static/img/"
             );
             // Fix broken markdown links with dynamic outDir name
             updatedContent = updatedContent.replaceAll(
@@ -469,7 +472,7 @@ ${updatedContent}`,
             
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../static/img/"
+              "../../../../static/img/"
             );
             // Fix broken markdown links with dynamic outDir name
             updatedContent = updatedContent.replaceAll(
@@ -505,7 +508,7 @@ ${updatedContent}`,
           if (filename === "protocol.md") {
             let updatedContent = content.replaceAll(
               "../../diagrams/",
-              "../../static/img/"
+              "../../../../static/img/"
             );
             // Fix broken markdown links as specified
             updatedContent = updatedContent.replaceAll(

From d9917d5a63227950374527708a0578a805970bee Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Wed, 8 Oct 2025 09:36:07 -0400
Subject: [PATCH 07/10] Fix link errors

---
 docs/explanation/platform-architecture/index.md | 16 ++++++++--------
 docs/how-to/sdk-recipes/overview.mdx            |  2 +-
 docs/reference/index.mdx                        |  4 ++--
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/docs/explanation/platform-architecture/index.md b/docs/explanation/platform-architecture/index.md
index 521fd0c..912a8d2 100644
--- a/docs/explanation/platform-architecture/index.md
+++ b/docs/explanation/platform-architecture/index.md
@@ -46,31 +46,31 @@ graph TD
     class POLICY,AUTHZ,ERS,KAS opentdfService
     class ATTR_SOURCES,IDP,CLIENT externalSystem
 
-    click POLICY "./components/policy/" "Go to Policy Service docs"
-    click AUTHZ "./components/authorization" "Go to Authorization Service docs"
-    click ERS "./components/entity_resolution" "Go to Entity Resolution Service docs"
-    click KAS "./components/key_access" "Go to Key Access Server docs"
+    click POLICY "/explanation/platform-architecture/components/policy/" "Go to Policy Service docs"
+    click AUTHZ "/explanation/platform-architecture/components/authorization" "Go to Authorization Service docs"
+    click ERS "/explanation/platform-architecture/components/entity_resolution" "Go to Entity Resolution Service docs"
+    click KAS "/explanation/platform-architecture/components/key_access" "Go to Key Access Server docs"
 ```
 
-### [Policy Service](./components/policy/)
+### [Policy Service](/explanation/platform-architecture/components/policy/)
 
 The **Policy Service** is where all access control policies are defined and managed. It provides the tools and APIs to create a rich set of policies that govern data access. This includes not only attributes and their values, but also the definitions of **actions, obligations, and key access mappings**.
 
 In the context of the NIST ABAC model, the Policy Service functions as the **Policy Administration Point (PAP)**.
 
-### [Authorization Service](./components/authorization)
+### [Authorization Service](/explanation/platform-architecture/components/authorization)
 
 The **Authorization Service** is the core decision-making engine of the platform. It is responsible for evaluating the rich policies from the Policy Service against a set of attributes to render an authorization decision.
 
 In the context of the NIST ABAC model, it functions as the **Policy Decision Point (PDP)**.
 
-### [Entity Resolution Service (ERS)](./components/entity_resolution)
+### [Entity Resolution Service (ERS)](/explanation/platform-architecture/components/entity_resolution)
 
 The **Entity Resolution Service** is responsible for gathering the attributes about a subject needed for a decision. By default, it can derive attributes from claims in an authentication token. Optionally, it can be configured to connect to external attribute sources (LDAP, SQL) to "hydrate" the entity with more attributes.
 
 In the context of the NIST ABAC model, the ERS functions as the **Policy Information Point (PIP)**.
 
-### [Key Access Server (KAS)](./components/key_access)
+### [Key Access Server (KAS)](/explanation/platform-architecture/components/key_access)
 
 The **Key Access Server (KAS)** enforces access control decisions. Its role is more extensive than a typical enforcement point:
 
diff --git a/docs/how-to/sdk-recipes/overview.mdx b/docs/how-to/sdk-recipes/overview.mdx
index 342e438..20e5229 100644
--- a/docs/how-to/sdk-recipes/overview.mdx
+++ b/docs/how-to/sdk-recipes/overview.mdx
@@ -6,7 +6,7 @@ sidebar_position: 1
 
 OpenTDF supports native SDKs in the Go, Java and JavaScript languages. 
 
-Please refer to the [SDK Feature Matrix](../../appendix/matrix.mdx#sdk) in the Appendix for the supported features in each SDK.
+Please refer to the [SDK Feature Matrix](../../reference/appendix/matrix.mdx#sdk) in the Appendix for the supported features in each SDK.
 
 ## Repositories
 
diff --git a/docs/reference/index.mdx b/docs/reference/index.mdx
index 9bd888c..844e6f0 100644
--- a/docs/reference/index.mdx
+++ b/docs/reference/index.mdx
@@ -17,12 +17,12 @@ Complete API documentation, specifications, CLI commands, SDK references, and co
     {
       name: "Platform APIs",
       description: "Complete REST API reference for all OpenTDF platform services including policy management, authorization, and key access.",
-      url: "/reference/api",
+      url: "/OpenAPI-clients",
     },
     {
       name: "Specifications",
       description: "Technical specifications for the OpenTDF format, protocol, and schemas. Essential for implementers and integrators.",
-      url: "/reference/specifications",
+      url: "/reference/trusted-data-format/specifications",
     },
   ]}
 />

From c9f4cd1c790251b0c30e6991945d3ed03e7ae8eb Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Wed, 8 Oct 2025 16:15:08 -0400
Subject: [PATCH 08/10] Fix broken links issue from gen-api docs

---
 src/utils/spec-documentation.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/utils/spec-documentation.ts b/src/utils/spec-documentation.ts
index 14b8f7b..47b52f5 100644
--- a/src/utils/spec-documentation.ts
+++ b/src/utils/spec-documentation.ts
@@ -359,7 +359,7 @@ ${updatedContent}`,
             );
             updatedContent = updatedContent.replaceAll(
               "(concepts/)",
-              "(category/concepts)"
+              "(/reference/trusted-data-format/specifications/concepts/access_control)"
             );
             updatedContent = updatedContent.replaceAll(
               "(protocol/)",

From 9139d774d6111d9a509fe59482ff2731ce6e09b7 Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Wed, 8 Oct 2025 22:38:24 -0400
Subject: [PATCH 09/10] Added new marketing home page

---
 docs/{index.mdx => documentation.mdx} |  17 +-
 docusaurus.config.ts                  |  10 +-
 src/css/custom.css                    |   3 +
 src/css/marketing.css                 | 228 ++++++++++++++
 src/pages/documentation.tsx           | 270 ++++++++++++++++
 src/pages/index.module.css            | 271 ++++++++++++++++
 src/pages/index.tsx                   | 436 ++++++++++++--------------
 7 files changed, 985 insertions(+), 250 deletions(-)
 rename docs/{index.mdx => documentation.mdx} (90%)
 create mode 100644 src/css/marketing.css
 create mode 100644 src/pages/documentation.tsx

diff --git a/docs/index.mdx b/docs/documentation.mdx
similarity index 90%
rename from docs/index.mdx
rename to docs/documentation.mdx
index 1f6082e..ed0c921 100644
--- a/docs/index.mdx
+++ b/docs/documentation.mdx
@@ -1,6 +1,6 @@
 ---
-title: OpenTDF - Protect the Data, Build the Future
-description: Persistent data centric security that extends owner control wherever data travels.
+title: Documentation
+description: Complete OpenTDF documentation - tutorials, guides, concepts, and reference materials.
 keywords:
   - data-centric security
   - zero trust
@@ -9,6 +9,8 @@ keywords:
   - ABAC
   - attribute-based access control
   - OpenTDF
+  - documentation
+sidebar_position: 1
 ---
 
 import React from "react";
@@ -19,14 +21,11 @@ import Cards from "@site/src/components/Cards";
   <div className="container">
     <div className="row">
       <div className="col col--8 col--offset-2">
-        <h1 className="hero__title">OpenTDF: A toolkit for zero trust, data-centric security</h1>
+        <h1 className="hero__title">OpenTDF Documentation</h1>
         <p className="hero__subtitle">
-          <strong>OpenTDF</strong> is an open source system for implementing data centric security. 
-          It provides the basic services required to enable the definition, application, 
-          and enforcement of attribute based policies using the Trust Data Format (TDF). 
-          TDF is an open standard that enables you to cryptographically bind 
-          attribute based access control (ABAC) policy to a data object so that 
-          the policy travels with the data wherever it goes.
+          Complete documentation for <strong>OpenTDF</strong> - an open source system for implementing data-centric security. 
+          Whether you're just getting started or building advanced integrations, find everything you need 
+          to understand, implement, and deploy OpenTDF's zero-trust data protection.
         </p>
         <p className="hero__subtitle">
           OpenTDF builds upon <strong>a decade of experience at Virtru</strong> 
diff --git a/docusaurus.config.ts b/docusaurus.config.ts
index e5acf20..6d1fd1e 100644
--- a/docusaurus.config.ts
+++ b/docusaurus.config.ts
@@ -109,10 +109,14 @@ const config: Config = {
       },
       items: [
         {
-          type: "doc",
+          to: "/documentation",
+          position: "left",
+          label: "Documentation",
+        },
+        {
+          href: "https://www.virtru.com/partners/",
+          label: "Partners",
           position: "left",
-          docId: "index",
-          label: "Docs",
         },
         {
           href: "https://github.com/opentdf",
diff --git a/src/css/custom.css b/src/css/custom.css
index 915b8f5..e3cf530 100644
--- a/src/css/custom.css
+++ b/src/css/custom.css
@@ -4,6 +4,9 @@
  * work well for content-centric websites.
  */
 
+/* Import marketing styles for homepage */
+@import './marketing.css';
+
 /* You can override the default Infima variables here. */
 /* :root {
   --ifm-color-primary: #2e8555;
diff --git a/src/css/marketing.css b/src/css/marketing.css
new file mode 100644
index 0000000..854baac
--- /dev/null
+++ b/src/css/marketing.css
@@ -0,0 +1,228 @@
+/* Marketing Homepage Styles */
+
+.marketing-hero {
+  padding: 4rem 0;
+  position: relative;
+  overflow: hidden;
+}
+
+.marketing-hero--primary {
+  background: linear-gradient(135deg, var(--ifm-color-primary) 0%, var(--ifm-color-primary-dark) 100%);
+  color: white;
+}
+
+.marketing-hero--secondary {
+  background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+  color: var(--ifm-color-gray-900);
+}
+
+.marketing-hero--dark {
+  background: linear-gradient(135deg, var(--ifm-color-gray-900) 0%, var(--ifm-color-gray-800) 100%);
+  color: white;
+}
+
+.marketing-hero--accent {
+  background: linear-gradient(135deg, var(--ifm-color-success) 0%, var(--ifm-color-success-dark) 100%);
+  color: white;
+}
+
+.hero-content {
+  display: flex;
+  align-items: center;
+  gap: 3rem;
+  min-height: 400px;
+}
+
+.hero-content--reverse {
+  flex-direction: row-reverse;
+}
+
+.hero-text {
+  flex: 1;
+}
+
+.hero-visual {
+  flex: 0 0 auto;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.hero-icon {
+  font-size: 8rem;
+  opacity: 0.9;
+  filter: drop-shadow(0 4px 8px rgba(0,0,0,0.1));
+}
+
+.hero-title {
+  font-size: 3.5rem;
+  font-weight: 800;
+  margin-bottom: 1.5rem;
+  line-height: 1.2;
+}
+
+.hero-subtitle {
+  font-size: 1.3rem;
+  margin-bottom: 2rem;
+  opacity: 0.9;
+  line-height: 1.6;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.hero-button {
+  padding: 0.75rem 2rem;
+  font-size: 1.1rem;
+  font-weight: 600;
+  border-radius: 8px;
+  text-decoration: none;
+  transition: all 0.2s ease;
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.hero-button--primary {
+  background: rgba(255,255,255,0.2);
+  color: white;
+  border: 2px solid rgba(255,255,255,0.3);
+}
+
+.hero-button--primary:hover {
+  background: rgba(255,255,255,0.3);
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+}
+
+.hero-button--secondary {
+  background: transparent;
+  color: inherit;
+  border: 2px solid currentColor;
+}
+
+.hero-button--secondary:hover {
+  background: currentColor;
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+}
+
+.hero-button--solid {
+  background: var(--ifm-color-primary);
+  color: white;
+  border: 2px solid var(--ifm-color-primary);
+}
+
+.hero-button--solid:hover {
+  background: var(--ifm-color-primary-dark);
+  border-color: var(--ifm-color-primary-dark);
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+  .hero-content {
+    flex-direction: column !important;
+    text-align: center;
+    gap: 2rem;
+    min-height: 300px;
+  }
+  
+  .hero-content--reverse {
+    flex-direction: column !important;
+  }
+  
+  .hero-title {
+    font-size: 2.5rem;
+  }
+  
+  .hero-subtitle {
+    font-size: 1.1rem;
+  }
+  
+  .hero-icon {
+    font-size: 5rem;
+  }
+  
+  .hero-actions {
+    justify-content: center;
+  }
+}
+
+/* Navigation Enhancement */
+.navbar {
+  backdrop-filter: blur(10px);
+  background: rgba(255, 255, 255, 0.95);
+  border-bottom: 1px solid rgba(0,0,0,0.1);
+}
+
+/* Animation Classes */
+.fade-in {
+  animation: fadeIn 0.8s ease-out;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(30px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.slide-in-right {
+  animation: slideInRight 1s ease-out;
+}
+
+@keyframes slideInRight {
+  from {
+    opacity: 0;
+    transform: translateX(50px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+.slide-in-left {
+  animation: slideInLeft 1s ease-out;
+}
+
+@keyframes slideInLeft {
+  from {
+    opacity: 0;
+    transform: translateX(-50px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* Visual enhancements */
+.hero-icon-container {
+  position: relative;
+}
+
+.hero-icon-container::before {
+  content: '';
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  transform: translate(-50%, -50%);
+  width: 120%;
+  height: 120%;
+  background: radial-gradient(circle, rgba(255,255,255,0.1) 0%, transparent 70%);
+  border-radius: 50%;
+  z-index: -1;
+}
\ No newline at end of file
diff --git a/src/pages/documentation.tsx b/src/pages/documentation.tsx
new file mode 100644
index 0000000..093e319
--- /dev/null
+++ b/src/pages/documentation.tsx
@@ -0,0 +1,270 @@
+import React from "react";
+import Layout from "@theme/Layout";
+import Head from "@docusaurus/Head";
+import { Columns, Hero, Features, Feedback } from "../components/Homepage";
+
+export default function Documentation() {
+  return (
+    <div className="homepage">
+      <Head>
+        <meta property="og:title" content="OpenTDF Documentation - Complete Developer Resources" />
+        <meta property="og:description" content="Comprehensive guides, tutorials, and references for implementing data-centric security with OpenTDF." />
+      </Head>
+      <Layout title="OpenTDF Documentation" description="Complete developer resources for OpenTDF">
+        <Hero
+          heading="OpenTDF Documentation: Your Complete Guide to Data-Centric Security"
+          callToAction={{
+            text: "Start with Your First TDF",
+            url: "/tutorials/your-first-tdf",
+          }}
+        >
+          <p>
+          OpenTDF is an open source system for implementing data centric security. 
+          It provides the basic services required to enable the definition, application, 
+          and enforcement of attribute based policies using the Trust Data Format (TDF). 
+          TDF is an open standard that enables you to cryptographically bind 
+          attribute based access control (ABAC) policy to a data object so that 
+          the policy travels with the data wherever it goes.
+          </p>
+          <p>
+          OpenTDF builds upon a decade of experience at Virtru 
+          protecting data objects at scale using the Trusted Data Format 
+          for organizations of all sizes and across all industries.
+          </p>
+          <div style={{ 
+            position: 'relative',
+            display: 'flex',
+            justifyContent: 'center',
+            marginTop: '2rem',
+            zIndex: 5,
+            gap: '1rem',
+            flexWrap: 'wrap'
+          }}>
+            <button 
+              onClick={() => document.getElementById('find-what-you-need')?.scrollIntoView({ behavior: 'smooth' })}
+              style={{
+                display: 'flex',
+                alignItems: 'center',
+                justifyContent: 'center',
+                height: '40px',
+                backgroundColor: 'transparent',
+                border: '2px solid var(--vds-color-blue-006)',
+                color: 'var(--vds-color-blue-006)',
+                fontWeight: 'bold',
+                borderRadius: '5px',
+                margin: '1rem',
+                padding: '2rem 1rem',
+                cursor: 'pointer',
+                textDecoration: 'none',
+                transition: 'all 0.3s ease'
+              }}
+              onMouseOver={(e) => {
+                e.currentTarget.style.backgroundColor = 'var(--vds-color-blue-006)';
+                e.currentTarget.style.color = 'var(--ifm-color-white)';
+              }}
+              onMouseOut={(e) => {
+                e.currentTarget.style.backgroundColor = 'transparent';
+                e.currentTarget.style.color = 'var(--vds-color-blue-006)';
+              }}
+            >
+              Learn More About OpenTDF
+            </button>
+          </div>
+          <p style={{ 
+            textAlign: 'center',
+            color: 'var(--vds-color-blue-007)', 
+            fontSize: '0.9rem',
+            marginTop: '1rem',
+            fontStyle: 'italic'
+          }}>
+            Want to get an instance of the OpenTDF Platform up and running? Click below!
+          </p>
+        </Hero>
+
+        {/* Add spacing after hero section */}
+        <div style={{ padding: '40px 0' }}>
+          
+          {/* Find What You Need Section */}
+          <div id="find-what-you-need" className="container">
+            <div className="row">
+              <div className="col col--12">
+                <h2 style={{ textAlign: 'center', marginBottom: '1rem' }}>Find What You Need</h2>
+                <p style={{ textAlign: 'center', marginBottom: '1rem', fontSize: '1.1rem' }}>
+                  Choose your learning path based on what you want to accomplish
+                </p>
+                <p style={{ 
+                  textAlign: 'center', 
+                  marginBottom: '3rem', 
+                  fontSize: '1rem',
+                  fontStyle: 'italic',
+                  color: 'var(--ifm-color-emphasis-700)'
+                }}>
+
+                </p>
+              </div>
+            </div>
+            
+            <div className="row" style={{ marginBottom: '3rem' }}>
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-008)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>🚀 Tutorials</h3>
+                    <p><em>I want to learn by doing</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Step-by-step guides that take you by the hand through a series of steps to complete a project or solve a problem.</p>
+                    <ul>
+                      <li><strong><a href="/tutorials/your-first-tdf">Your First TDF</a></strong> - Get hands-on experience creating your first protected data file</li>
+                      <li><strong><a href="/tutorials">Complete Tutorial Series</a></strong> - Step-by-step guides for learning OpenTDF</li>
+                      <li><strong><a href="/getting-started/configuration">Platform Configuration</a></strong> - Set up OpenTDF services</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+              
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-008)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>📖 How-To Guides</h3>
+                    <p><em>I have a specific problem to solve</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Practical guides for common tasks and problems you'll encounter when working with OpenTDF.</p>
+                    <ul>
+                      <li><strong><a href="/how-to/sdk-recipes/tdf">Working with TDF Files</a></strong> - Encrypt and decrypt data with SDK examples</li>
+                      <li><strong><a href="/how-to/sdk-recipes/authorization">Authorization Patterns</a></strong> - Manage access control with practical examples</li>
+                      <li><strong><a href="/how-to/sdk-recipes">SDK Integration Recipes</a></strong> - Complete code examples and patterns</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+            </div>
+            
+            <div className="row" style={{ marginBottom: '3rem' }}>
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-lighter)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>💡 Explanations</h3>
+                    <p><em>I want to understand the concepts</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Big-picture explanations of how OpenTDF works and why it's built the way it is.</p>
+                    <ul>
+                      <li><strong><a href="/explanation/data-centric-security">Data-Centric Security</a></strong> - Core concepts and principles of OpenTDF</li>
+                      <li><strong><a href="/explanation/platform-architecture">Platform Architecture</a></strong> - How OpenTDF services work together</li>
+                      <li><strong><a href="/explanation/trusted-data-format">Trusted Data Format</a></strong> - Understanding TDF and self-protecting data</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+              
+              <div className="col col--6">
+                <div className="card" style={{ 
+                  height: '100%', 
+                  padding: '2rem',
+                  backgroundColor: 'var(--vds-color-blue-lighter)',
+                  border: '1px solid var(--vds-color-blue-light)'
+                }}>
+                  <div className="card__header">
+                    <h3>📚 Reference</h3>
+                    <p><em>I need to look up specific details</em></p>
+                  </div>
+                  <div className="card__body">
+                    <p>Technical descriptions of the machinery and how to operate it.</p>
+                    <ul>
+                      <li><strong><a href="/reference/api">Platform APIs</a></strong> - Complete REST API reference for all services</li>
+                      <li><strong><a href="/reference/specifications">Technical Specifications</a></strong> - TDF format, protocols, and schemas</li>
+                      <li><strong><a href="/how-to/sdk-recipes">SDK Examples</a></strong> - Code examples and integration patterns</li>
+                    </ul>
+                  </div>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        <Columns>
+          <Columns.Item title="Zero Trust and OpenTDF" subtitle="Why OpenTDF?">
+            <p>
+            Today's cybersecurity landscape is increasingly adopting and requiring Zero Trust models and frameworks. 
+            Zero Trust operates on the principle of "never trust, always verify," 
+            ensuring that every access request is authenticated, authorized, and encrypted, 
+            regardless of its origin. OpenTDF implements this model by providing an open-source framework, specification, and set of services
+            that prioritizes the protection and integrity of data at every stage. 
+            </p>
+            <p>
+            By integrating OpenTDF's data security features with a Zero Trust architecture, 
+            organizations can enforce strict access controls, ensure data is continuously monitored, 
+            and maintain comprehensive visibility into data interactions. This synergy not only 
+            minimizes the risk of data breaches but also fosters a secure environment where data 
+            can be shared and utilized with confidence. Together, Zero Trust and OpenTDF empower businesses 
+            to uphold the highest standards of data security in an interconnected world.
+            </p>
+          </Columns.Item>
+          <Columns.Item title="Project Overview and Current State" subtitle="What's New">
+            <p>
+            In 2023, the OpenTDF team undertook a significant re-architecture 
+            of the OpenTDF platform to enhance its extensibility and interoperability, 
+            responding to the evolving needs of our diverse user base and the dynamic cybersecurity landscape.
+            See our {" "}<a href="https://github.com/opentdf/">Github Organization Page</a> to navigate the new repositories. 
+            </p>
+            <p>
+            This comprehensive overhaul involved simplifying core service components, 
+            adopting standardized policy schemas, and improving platform APIs and SDKs both in 
+            developer experience and in capability. By focusing on extensibility, we have enabled 
+            developers to customize and extend OpenTDF's functionalities to suit specific use cases, 
+            fostering innovation and adaptability. As we continue to advance, our focus remains on empowering the community with a secure, adaptable, 
+            and interoperable platform that meets the highest standards of data protection and fosters collaborative innovation.
+            </p>
+            <p>
+              Through the sponsorship of Virtru and its partners, the OpenTDF project has been
+              meeting the needs of customers across industries and use cases. Check out{" "}
+              <a href="https://www.virtru.com/data-security-platform">
+                Virtru Data Security Platform
+              </a>{" "}
+              for more.
+            </p>
+          </Columns.Item>
+        </Columns>
+        <Features
+          title="OpenTDF Examples"
+          description="Ideas for leveraging OpenTDF in your own applications"
+          imageUrl=""
+        >
+          {/* <Features.Item title="SecureCycle" description="SecureCycle is a sample application that demonstrates how OpenTDF safeguards private health information &hyphen; in this case, sensitive data related to period tracking and symptoms." icon="carbon:location-heart"
+          callToAction={{ title: 'Learn more', url: 'https://google.com' }} /> */}
+          <Features.Item title="Secure IoT Sensor Data" description="From full-motion video to biometric devices, attach access controls and preserve data integrity to guard against data spoofing." icon="carbon:fingerprint-recognition" />
+          <Features.Item title="Secure Data Sharing" description="Securely share data with partners, customers, and suppliers, and maintain control over who can access it." icon="carbon:ai-governance-lifecycle" />
+        </Features>
+        <Feedback
+          title="Share Your Feedback"
+        >
+          <p>
+            Virtru, the sponsor of the OpenTDF developer community, would love to hear from you!
+          </p>
+          <p>
+            We're developers, too, and as we mature the project, we're curious what you're building, and what kind of problems you may be encountering or are trying to solve.
+          </p>
+          <p>
+            You can provide anonymous feedback (name, email, and company are not required fields on this form), or share your contact information for access to curated resources, updates, and if you request a response.
+          </p>
+        </Feedback>
+      </Layout>
+    </div>
+  );
+}
\ No newline at end of file
diff --git a/src/pages/index.module.css b/src/pages/index.module.css
index d1a89ba..41ed7ea 100644
--- a/src/pages/index.module.css
+++ b/src/pages/index.module.css
@@ -3,3 +3,274 @@
  * and scoped locally.
  */
 
+/* Marketing Homepage Styles */
+
+/* Hero Sections */
+.marketing-hero {
+  padding: 6rem 0;
+  position: relative;
+  overflow: hidden;
+}
+
+.marketing-hero--primary {
+  background: linear-gradient(135deg, var(--ifm-color-primary) 0%, var(--ifm-color-primary-darker) 100%);
+  color: white;
+}
+
+.marketing-hero--secondary {
+  background: linear-gradient(135deg, #f8f9fa 0%, #e9ecef 100%);
+  color: var(--ifm-color-emphasis-800);
+}
+
+.marketing-hero--dark {
+  background: linear-gradient(135deg, #2c3e50 0%, #34495e 100%);
+  color: white;
+}
+
+.marketing-hero--accent {
+  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+  color: white;
+}
+
+/* Hero Content Layout */
+.hero-content {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+  gap: 4rem;
+  align-items: center;
+  min-height: 400px;
+}
+
+.hero-content--reverse {
+  grid-template-areas: "visual text";
+}
+
+.hero-content--reverse .hero-text {
+  grid-area: text;
+}
+
+.hero-content--reverse .hero-visual {
+  grid-area: visual;
+}
+
+.hero-text {
+  z-index: 2;
+}
+
+.hero-title {
+  font-size: 3rem;
+  font-weight: 800;
+  line-height: 1.2;
+  margin-bottom: 1.5rem;
+  background: linear-gradient(135deg, currentColor 0%, rgba(255,255,255,0.8) 100%);
+  background-clip: text;
+  -webkit-background-clip: text;
+}
+
+.hero-subtitle {
+  font-size: 1.25rem;
+  line-height: 1.6;
+  margin-bottom: 2rem;
+  opacity: 0.9;
+}
+
+/* Hero Actions */
+.hero-actions {
+  display: flex;
+  gap: 1rem;
+  flex-wrap: wrap;
+}
+
+.hero-button {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 1rem 2rem;
+  border-radius: 0.5rem;
+  font-weight: 600;
+  text-decoration: none;
+  transition: all 0.3s ease;
+  border: 2px solid;
+  font-size: 1rem;
+}
+
+.hero-button--primary {
+  background: rgba(255, 255, 255, 0.1);
+  border-color: rgba(255, 255, 255, 0.3);
+  color: white;
+  backdrop-filter: blur(10px);
+}
+
+.hero-button--primary:hover {
+  background: rgba(255, 255, 255, 0.2);
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
+}
+
+.hero-button--secondary {
+  background: transparent;
+  border-color: currentColor;
+  color: inherit;
+}
+
+.hero-button--secondary:hover {
+  background: currentColor;
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+}
+
+.hero-button--solid {
+  background: var(--ifm-color-primary);
+  border-color: var(--ifm-color-primary);
+  color: white;
+}
+
+.hero-button--solid:hover {
+  background: var(--ifm-color-primary-dark);
+  border-color: var(--ifm-color-primary-dark);
+  color: white;
+  text-decoration: none;
+  transform: translateY(-2px);
+  box-shadow: 0 10px 25px rgba(0, 0, 0, 0.15);
+}
+
+/* Hero Visual */
+.hero-visual {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  position: relative;
+}
+
+.hero-icon-container {
+  width: 200px;
+  height: 200px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  background: rgba(255, 255, 255, 0.1);
+  border-radius: 50%;
+  backdrop-filter: blur(10px);
+  border: 2px solid rgba(255, 255, 255, 0.2);
+}
+
+.hero-icon {
+  font-size: 4rem;
+  color: currentColor;
+}
+
+/* Animations */
+.fade-in {
+  animation: fadeIn 1s ease-out;
+}
+
+.slide-in-right {
+  animation: slideInRight 1s ease-out;
+}
+
+.slide-in-left {
+  animation: slideInLeft 1s ease-out;
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(30px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes slideInRight {
+  from {
+    opacity: 0;
+    transform: translateX(50px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+@keyframes slideInLeft {
+  from {
+    opacity: 0;
+    transform: translateX(-50px);
+  }
+  to {
+    opacity: 1;
+    transform: translateX(0);
+  }
+}
+
+/* Responsive Design */
+@media (max-width: 768px) {
+  .hero-content {
+    grid-template-columns: 1fr;
+    gap: 2rem;
+    text-align: center;
+  }
+  
+  .hero-content--reverse {
+    grid-template-areas: 
+      "text"
+      "visual";
+  }
+  
+  .hero-title {
+    font-size: 2.5rem;
+  }
+  
+  .hero-subtitle {
+    font-size: 1.1rem;
+  }
+  
+  .hero-actions {
+    justify-content: center;
+  }
+  
+  .hero-button {
+    padding: 0.875rem 1.5rem;
+    font-size: 0.9rem;
+  }
+  
+  .marketing-hero {
+    padding: 4rem 0;
+  }
+  
+  .hero-icon-container {
+    width: 150px;
+    height: 150px;
+  }
+  
+  .hero-icon {
+    font-size: 3rem;
+  }
+}
+
+@media (max-width: 480px) {
+  .hero-title {
+    font-size: 2rem;
+  }
+  
+  .hero-subtitle {
+    font-size: 1rem;
+  }
+  
+  .hero-actions {
+    flex-direction: column;
+    align-items: center;
+  }
+  
+  .hero-button {
+    width: 100%;
+    max-width: 280px;
+    justify-content: center;
+  }
+}
+
diff --git a/src/pages/index.tsx b/src/pages/index.tsx
index 134a80a..7231221 100644
--- a/src/pages/index.tsx
+++ b/src/pages/index.tsx
@@ -1,270 +1,230 @@
 import React from "react";
 import Layout from "@theme/Layout";
 import Head from "@docusaurus/Head";
-import { Columns, Hero, Features, Feedback } from "../components/Homepage";
+import styles from "./index.module.css";
 
 export default function Home() {
   return (
-    <div className="homepage">
+    <div className="marketing-homepage">
       <Head>
         <meta property="og:title" content="OpenTDF - Protect the Data, Build the Future" />
-        <meta property="og:description" content="Persistent data centric security that extends owner control wherever data travels." />
+        <meta property="og:description" content="Zero-trust data protection that travels with your data wherever it goes" />
       </Head>
-      <Layout title="OpenTDF" description="OpenTDF">
-        <Hero
-          heading="OpenTDF: A toolkit for zero trust, data-centric security"
-          callToAction={{
-            text: "Get Started with OpenTDF",
-            url: "/tutorials/your-first-tdf",
-          }}
-        >
-          <p>
-          OpenTDF is an open source system for implementing data centric security. 
-          It provides the basic services required to enable the definition, application, 
-          and enforcement of attribute based policies using the Trust Data Format (TDF). 
-          TDF is an open standard that enables you to cryptographically bind 
-          attribute based access control (ABAC) policy to a data object so that 
-          the policy travels with the data wherever it goes.
-          </p>
-          <p>
-          OpenTDF builds upon a decade of experience at Virtru 
-          protecting data objects at scale using the Trusted Data Format 
-          for organizations of all sizes and across all industries.
-          </p>
-          <div style={{ 
-            position: 'relative',
-            display: 'flex',
-            justifyContent: 'center',
-            marginTop: '2rem',
-            zIndex: 5,
-            gap: '1rem',
-            flexWrap: 'wrap'
-          }}>
-            <button 
-              onClick={() => document.getElementById('find-what-you-need')?.scrollIntoView({ behavior: 'smooth' })}
-              style={{
-                display: 'flex',
-                alignItems: 'center',
-                justifyContent: 'center',
-                height: '40px',
-                backgroundColor: 'transparent',
-                border: '2px solid var(--vds-color-blue-006)',
-                color: 'var(--vds-color-blue-006)',
-                fontWeight: 'bold',
-                borderRadius: '5px',
-                margin: '1rem',
-                padding: '2rem 1rem',
-                cursor: 'pointer',
-                textDecoration: 'none',
-                transition: 'all 0.3s ease'
-              }}
-              onMouseOver={(e) => {
-                e.currentTarget.style.backgroundColor = 'var(--vds-color-blue-006)';
-                e.currentTarget.style.color = 'var(--ifm-color-white)';
-              }}
-              onMouseOut={(e) => {
-                e.currentTarget.style.backgroundColor = 'transparent';
-                e.currentTarget.style.color = 'var(--vds-color-blue-006)';
-              }}
-            >
-              Learn More About OpenTDF
-            </button>
+      <Layout title="OpenTDF - Protect the Data, Build the Future" description="Zero-trust data protection that travels with your data wherever it goes">
+        
+        {/* Hero 1: Main Value Proposition */}
+        <section className="marketing-hero marketing-hero--primary">
+          <div className="container">
+            <div className="hero-content fade-in">
+              <div className="hero-text">
+                <h1 className="hero-title">Protect the Data, Build the Future</h1>
+                <p className="hero-subtitle">
+                  Zero-trust data protection that travels with your data wherever it goes. 
+                  OpenTDF cryptographically binds access control policies directly to data objects, 
+                  ensuring your data remains secure regardless of network boundaries or storage location.
+                </p>
+                <div className="hero-actions">
+                  <a href="/tutorials/your-first-tdf" className="hero-button hero-button--primary">
+                    <iconify-icon data-icon="mdi:rocket-launch" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Get Started
+                  </a>
+                  <a href="/documentation" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:book-open-variant" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    View Documentation
+                  </a>
+                </div>
+              </div>
+              <div className="hero-visual slide-in-right">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:shield-lock" className="hero-icon"></iconify-icon>
+                </div>
+              </div>
+            </div>
           </div>
-          <p style={{ 
-            textAlign: 'center',
-            color: 'var(--vds-color-blue-007)', 
-            fontSize: '0.9rem',
-            marginTop: '1rem',
-            fontStyle: 'italic'
-          }}>
-            Want to get an instance of the OpenTDF Platform up and running? Click below!
-          </p>
-        </Hero>
+        </section>
 
-        {/* Add spacing after hero section */}
-        <div style={{ padding: '40px 0' }}>
-          
-          {/* Find What You Need Section */}
-          <div id="find-what-you-need" className="container">
-            <div className="row">
-              <div className="col col--12">
-                <h2 style={{ textAlign: 'center', marginBottom: '1rem' }}>Find What You Need</h2>
-                <p style={{ textAlign: 'center', marginBottom: '1rem', fontSize: '1.1rem' }}>
-                  Choose your learning path based on what you want to accomplish
+        {/* Hero 2: Problem/Solution */}
+        <section className="marketing-hero marketing-hero--secondary">
+          <div className="container">
+            <div className="hero-content hero-content--reverse fade-in">
+              <div className="hero-text">
+                <h2 className="hero-title">Traditional Security Fails When Data Leaves the Perimeter</h2>
+                <p className="hero-subtitle">
+                  Once data crosses network boundaries, traditional security models lose control. 
+                  OpenTDF solves this by cryptographically binding policies to data objects themselves, 
+                  creating self-protecting data that enforces access controls anywhere it travels.
                 </p>
-                <p style={{ 
-                  textAlign: 'center', 
-                  marginBottom: '3rem', 
-                  fontSize: '1rem',
-                  fontStyle: 'italic',
-                  color: 'var(--ifm-color-emphasis-700)'
-                }}>
+                <div className="hero-actions">
+                  <a href="/explanation/data-centric-security" className="hero-button hero-button--solid">
+                    <iconify-icon data-icon="mdi:lightbulb-on" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Learn the Concepts
+                  </a>
+                  <a href="/explanation" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:eye" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    See Use Cases
+                  </a>
+                </div>
+              </div>
+              <div className="hero-visual slide-in-left">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:shield-alert" className="hero-icon" style={{color: '#dc3545'}}></iconify-icon>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
 
+        {/* Hero 3: Developer-First */}
+        <section className="marketing-hero marketing-hero--dark">
+          <div className="container">
+            <div className="hero-content fade-in">
+              <div className="hero-text">
+                <h2 className="hero-title">Built for Developers</h2>
+                <p className="hero-subtitle">
+                  Native SDKs for Go, Java, and JavaScript. RESTful APIs. Comprehensive documentation. 
+                  Get started in minutes, not months. OpenTDF provides the tools developers need to build 
+                  secure applications without sacrificing speed or simplicity.
                 </p>
+                <div className="hero-actions">
+                  <a href="/tutorials" className="hero-button hero-button--primary">
+                    <iconify-icon data-icon="mdi:code-tags" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Quick Start
+                  </a>
+                  <a href="/reference" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:api" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    API Reference
+                  </a>
+                </div>
+              </div>
+              <div className="hero-visual slide-in-right">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:code-brackets" className="hero-icon"></iconify-icon>
+                </div>
               </div>
             </div>
-            
-            <div className="row" style={{ marginBottom: '3rem' }}>
-              <div className="col col--6">
-                <div className="card" style={{ 
-                  height: '100%', 
-                  padding: '2rem',
-                  backgroundColor: 'var(--vds-color-blue-008)',
-                  border: '1px solid var(--vds-color-blue-light)'
-                }}>
-                  <div className="card__header">
-                    <h3>🚀 Tutorials</h3>
-                    <p><em>I want to learn by doing</em></p>
-                  </div>
-                  <div className="card__body">
-                    <p>Step-by-step guides that take you by the hand through a series of steps to complete a project or solve a problem.</p>
-                    <ul>
-                      <li><strong><a href="/tutorials/your-first-tdf">Your First TDF</a></strong> - Get hands-on experience creating your first protected data file</li>
-                      <li><strong><a href="/tutorials">Complete Tutorial Series</a></strong> - Step-by-step guides for learning OpenTDF</li>
-                      <li><strong><a href="/getting-started/configuration">Platform Configuration</a></strong> - Set up OpenTDF services</li>
-                    </ul>
-                  </div>
+          </div>
+        </section>
+
+        {/* Hero 4: Enterprise Trust */}
+        <section className="marketing-hero marketing-hero--accent">
+          <div className="container">
+            <div className="hero-content hero-content--reverse fade-in">
+              <div className="hero-text">
+                <h2 className="hero-title">Trusted by Organizations Worldwide</h2>
+                <p className="hero-subtitle">
+                  Built on a decade of Virtru's experience protecting data at scale. OpenTDF powers 
+                  secure data sharing for organizations across industries—from healthcare and finance 
+                  to government and defense. Battle-tested, enterprise-ready, open source.
+                </p>
+                <div className="hero-actions">
+                  <a href="https://virtru.com" className="hero-button hero-button--primary">
+                    <iconify-icon data-icon="mdi:domain" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Enterprise Solutions
+                  </a>
+                  <a href="/how-to" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:cog" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Deployment Guides
+                  </a>
                 </div>
               </div>
-              
-              <div className="col col--6">
-                <div className="card" style={{ 
-                  height: '100%', 
-                  padding: '2rem',
-                  backgroundColor: 'var(--vds-color-blue-008)',
-                  border: '1px solid var(--vds-color-blue-light)'
-                }}>
-                  <div className="card__header">
-                    <h3>📖 How-To Guides</h3>
-                    <p><em>I have a specific problem to solve</em></p>
-                  </div>
-                  <div className="card__body">
-                    <p>Practical guides for common tasks and problems you'll encounter when working with OpenTDF.</p>
-                    <ul>
-                      <li><strong><a href="/how-to/sdk-recipes/tdf">Working with TDF Files</a></strong> - Encrypt and decrypt data with SDK examples</li>
-                      <li><strong><a href="/how-to/sdk-recipes/authorization">Authorization Patterns</a></strong> - Manage access control with practical examples</li>
-                      <li><strong><a href="/how-to/sdk-recipes">SDK Integration Recipes</a></strong> - Complete code examples and patterns</li>
-                    </ul>
-                  </div>
+              <div className="hero-visual slide-in-left">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:office-building" className="hero-icon"></iconify-icon>
                 </div>
               </div>
             </div>
-            
-            <div className="row" style={{ marginBottom: '3rem' }}>
-              <div className="col col--6">
-                <div className="card" style={{ 
-                  height: '100%', 
-                  padding: '2rem',
-                  backgroundColor: 'var(--vds-color-blue-lighter)',
-                  border: '1px solid var(--vds-color-blue-light)'
-                }}>
-                  <div className="card__header">
-                    <h3>💡 Explanations</h3>
-                    <p><em>I want to understand the concepts</em></p>
-                  </div>
-                  <div className="card__body">
-                    <p>Big-picture explanations of how OpenTDF works and why it's built the way it is.</p>
-                    <ul>
-                      <li><strong><a href="/explanation/data-centric-security">Data-Centric Security</a></strong> - Core concepts and principles of OpenTDF</li>
-                      <li><strong><a href="/explanation/platform-architecture">Platform Architecture</a></strong> - How OpenTDF services work together</li>
-                      <li><strong><a href="/explanation/trusted-data-format">Trusted Data Format</a></strong> - Understanding TDF and self-protecting data</li>
-                    </ul>
-                  </div>
+          </div>
+        </section>
+
+        {/* Hero 5: Standards & Compliance */}
+        <section className="marketing-hero marketing-hero--secondary">
+          <div className="container">
+            <div className="hero-content fade-in">
+              <div className="hero-text">
+                <h2 className="hero-title">Standards-Based Security</h2>
+                <p className="hero-subtitle">
+                  Built on the proven NIST ABAC model for interoperability and compliance. 
+                  OpenTDF follows established standards for attribute-based access control, 
+                  ensuring your data protection strategy is future-proof and audit-ready.
+                </p>
+                <div className="hero-actions">
+                  <a href="/reference/trusted-data-format/specifications" className="hero-button hero-button--solid">
+                    <iconify-icon data-icon="mdi:certificate" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    View Specifications
+                  </a>
+                  <a href="/explanation/platform-architecture" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:chart-timeline-variant" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Architecture Overview
+                  </a>
                 </div>
               </div>
-              
-              <div className="col col--6">
-                <div className="card" style={{ 
-                  height: '100%', 
-                  padding: '2rem',
-                  backgroundColor: 'var(--vds-color-blue-lighter)',
-                  border: '1px solid var(--vds-color-blue-light)'
-                }}>
-                  <div className="card__header">
-                    <h3>📚 Reference</h3>
-                    <p><em>I need to look up specific details</em></p>
-                  </div>
-                  <div className="card__body">
-                    <p>Technical descriptions of the machinery and how to operate it.</p>
-                    <ul>
-                      <li><strong><a href="/reference/api">Platform APIs</a></strong> - Complete REST API reference for all services</li>
-                      <li><strong><a href="/reference/specifications">Technical Specifications</a></strong> - TDF format, protocols, and schemas</li>
-                      <li><strong><a href="/how-to/sdk-recipes">SDK Examples</a></strong> - Code examples and integration patterns</li>
-                    </ul>
-                  </div>
+              <div className="hero-visual slide-in-right">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:check-decagram" className="hero-icon" style={{color: '#28a745'}}></iconify-icon>
                 </div>
               </div>
             </div>
           </div>
-        </div>
+        </section>
 
-        <Columns>
-          <Columns.Item title="Zero Trust and OpenTDF" subtitle="Why OpenTDF?">
-            <p>
-            Today's cybersecurity landscape is increasingly adopting and requiring Zero Trust models and frameworks. 
-            Zero Trust operates on the principle of "never trust, always verify," 
-            ensuring that every access request is authenticated, authorized, and encrypted, 
-            regardless of its origin. OpenTDF implements this model by providing an open-source framework, specification, and set of services
-            that prioritizes the protection and integrity of data at every stage. 
-            </p>
-            <p>
-            By integrating OpenTDF's data security features with a Zero Trust architecture, 
-            organizations can enforce strict access controls, ensure data is continuously monitored, 
-            and maintain comprehensive visibility into data interactions. This synergy not only 
-            minimizes the risk of data breaches but also fosters a secure environment where data 
-            can be shared and utilized with confidence. Together, Zero Trust and OpenTDF empower businesses 
-            to uphold the highest standards of data security in an interconnected world.
-            </p>
-          </Columns.Item>
-          <Columns.Item title="Project Overview and Current State" subtitle="What's New">
-            <p>
-            In 2023, the OpenTDF team undertook a significant re-architecture 
-            of the OpenTDF platform to enhance its extensibility and interoperability, 
-            responding to the evolving needs of our diverse user base and the dynamic cybersecurity landscape.
-            See our {" "}<a href="https://github.com/opentdf/">Github Organization Page</a> to navigate the new repositories. 
-            </p>
-            <p>
-            This comprehensive overhaul involved simplifying core service components, 
-            adopting standardized policy schemas, and improving platform APIs and SDKs both in 
-            developer experience and in capability. By focusing on extensibility, we have enabled 
-            developers to customize and extend OpenTDF's functionalities to suit specific use cases, 
-            fostering innovation and adaptability. As we continue to advance, our focus remains on empowering the community with a secure, adaptable, 
-            and interoperable platform that meets the highest standards of data protection and fosters collaborative innovation.
-            </p>
-            <p>
-              Through the sponsorship of Virtru and its partners, the OpenTDF project has been
-              meeting the needs of customers across industries and use cases. Check out{" "}
-              <a href="https://www.virtru.com/data-security-platform">
-                Virtru Data Security Platform
-              </a>{" "}
-              for more.
+        {/* Hero 6: Community */}
+        <section className="marketing-hero marketing-hero--dark">
+          <div className="container">
+            <div className="hero-content hero-content--reverse fade-in">
+              <div className="hero-text">
+                <h2 className="hero-title">Join the Movement</h2>
+                <p className="hero-subtitle">
+                  Open source, open community. Shape the future of data-centric security with developers, 
+                  security professionals, and organizations from around the world. Contribute code, 
+                  share ideas, and help build the next generation of data protection.
+                </p>
+                <div className="hero-actions">
+                  <a href="https://github.com/opentdf" className="hero-button hero-button--primary">
+                    <iconify-icon data-icon="mdi:github" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    GitHub
+                  </a>
+                  <a href="https://github.com/orgs/opentdf/discussions" className="hero-button hero-button--secondary">
+                    <iconify-icon data-icon="mdi:forum" style={{fontSize: '1.2rem'}}></iconify-icon>
+                    Community Discussions
+                  </a>
+                </div>
+              </div>
+              <div className="hero-visual slide-in-left">
+                <div className="hero-icon-container">
+                  <iconify-icon data-icon="mdi:account-group" className="hero-icon"></iconify-icon>
+                </div>
+              </div>
+            </div>
+          </div>
+        </section>
+
+        {/* Final CTA Section */}
+        <section style={{padding: '4rem 0', textAlign: 'center', background: '#f8f9fa'}}>
+          <div className="container">
+            <h2 style={{fontSize: '2.5rem', marginBottom: '1rem', color: 'var(--ifm-color-primary)'}}>
+              Ready to Protect Your Data?
+            </h2>
+            <p style={{fontSize: '1.2rem', marginBottom: '2rem', opacity: 0.8}}>
+              Choose your path and start building with OpenTDF today.
             </p>
-          </Columns.Item>
-        </Columns>
-        <Features
-          title="OpenTDF Examples"
-          description="Ideas for leveraging OpenTDF in your own applications"
-          imageUrl=""
-        >
-          {/* <Features.Item title="SecureCycle" description="SecureCycle is a sample application that demonstrates how OpenTDF safeguards private health information &hyphen; in this case, sensitive data related to period tracking and symptoms." icon="carbon:location-heart"
-          callToAction={{ title: 'Learn more', url: 'https://google.com' }} /> */}
-          <Features.Item title="Secure IoT Sensor Data" description="From full-motion video to biometric devices, attach access controls and preserve data integrity to guard against data spoofing." icon="carbon:fingerprint-recognition" />
-          <Features.Item title="Secure Data Sharing" description="Securely share data with partners, customers, and suppliers, and maintain control over who can access it." icon="carbon:ai-governance-lifecycle" />
-        </Features>
-        <Feedback
-          title="Share Your Feedback"
-        >
-          <p>
-            Virtru, the sponsor of the OpenTDF developer community, would love to hear from you!
-          </p>
-          <p>
-            We're developers, too, and as we mature the project, we're curious what you're building, and what kind of problems you may be encountering or are trying to solve.
-          </p>
-          <p>
-            You can provide anonymous feedback (name, email, and company are not required fields on this form), or share your contact information for access to curated resources, updates, and if you request a response.
-          </p>
-        </Feedback>
+            <div style={{display: 'flex', gap: '1rem', justifyContent: 'center', flexWrap: 'wrap'}}>
+              <a href="/tutorials/your-first-tdf" className="hero-button hero-button--solid">
+                <iconify-icon data-icon="mdi:play-circle" style={{fontSize: '1.2rem'}}></iconify-icon>
+                Start Tutorial
+              </a>
+              <a href="/documentation" className="hero-button hero-button--secondary">
+                <iconify-icon data-icon="mdi:book-open-variant" style={{fontSize: '1.2rem'}}></iconify-icon>
+                Browse Documentation
+              </a>
+              <a href="https://github.com/opentdf" className="hero-button hero-button--secondary">
+                <iconify-icon data-icon="mdi:github" style={{fontSize: '1.2rem'}}></iconify-icon>
+                View Source
+              </a>
+            </div>
+          </div>
+        </section>
+        
       </Layout>
     </div>
   );
-}
\ No newline at end of file
+}

From 8eb2419dc2d25fe97fd3a3f1b1d9d95236515ee4 Mon Sep 17 00:00:00 2001
From: jp-ayyappan <jp@as2max.com>
Date: Thu, 9 Oct 2025 08:39:59 -0400
Subject: [PATCH 10/10] Fix button hover styles

---
 src/css/marketing.css | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/css/marketing.css b/src/css/marketing.css
index 854baac..ad90eb1 100644
--- a/src/css/marketing.css
+++ b/src/css/marketing.css
@@ -106,8 +106,8 @@
 }
 
 .hero-button--secondary:hover {
-  background: currentColor;
-  color: white;
+  background: rgba(255,255,255,0.6);
+  color: gray;
   text-decoration: none;
   transform: translateY(-2px);
 }