ci: merge staging to master

docs/README.md

@@ -3,7 +3,7 @@ slug: /
 displayed_sidebar: docs
 ---
 
-# **Welcome to the Polykey documentation**
+# Welcome to the Polykey documentation
 
 - [Tutorials:](https://polykey.com/docs/tutorials) Step-by-step guides that
   introduce Polykey through practical outcomes.

docs/theory/receipt-rails-operational-flow.md

@@ -0,0 +1,239 @@
+# Receipt Rails Operational Flow
+
+This document outlines the fundamental operational flow of the Polykey
+ecosystem, which we call the Receipt Rails. It illustrates the complete
+lifecycle of a verifiable event, from the initial grant of authority to the
+final acceptance of a cryptographic receipt by a third party.
+
+The core principle of the Receipt Rails is to create a standardized, secure, and
+auditable process for proving that a specific action was performed or a specific
+outcome was achieved. This is accomplished through a sequence of interactions
+between four key actors: the Principal (who grants authority), the Subject (who
+performs the action), the Resource (the target of the action), and the Verifier
+(who accepts the proof).
+
+Below are two diagrams. The first provides a high-level, summary view of the
+entire flow. The second diagram is a detailed, technical zoom-in on the most
+critical and complex step: the Enforcement of a capability. Understanding both
+is key to grasping the full power and flexibility of the system.
+
+## Core Operational Flow (Summary View)
+
+This diagram shows the end-to-end lifecycle. It begins with a Principal issuing
+a Grant, which authorizes a Subject to perform an action. The Subject then
+presents this authority to an Enforcement Point, which results in the minting of
+verifiable receipts. These receipts are then assembled into a View for a
+Verifier, who can accept them for settlement, compliance, or payment.
+
+```mermaid
+---
+title: The Receipt Rails - Core Operational Flow
+config:
+  theme: redux-color
+---
+sequenceDiagram
+  participant P as Principal (P)<br>- Sigchain (P)<br>- Vault (leases/policy)
+  participant S as Subject (S)<br>- Sigchain (S)
+  participant R as Resource / ToA / SoA<br>(e.g., API, Power Grid, Door Lock)
+  participant V as Verifier / Auditor / Escrow<br>(TAP/RAM acceptance)
+
+  autonumber
+  Note over P: Issue Grant G<br>[write G to P’s Sigchain]
+  P ->> S: notify/ref (push or pull) for G
+
+  rect rgba(0,0,0,0.04)
+    note left of P: Enforcement Variants
+    alt Principal-side CEP (placement=P, bridging=true) [PS-BA]
+      S ->> P: Present capability (Presentation)
+      Note over P: Enforce at P CEP (mediate / derive / reveal)<br>Write Access PoAR on P's sigchain<br>Deliver PoAR to S
+    else Resource-side CEP (placement=R, bridging=false) [native]
+      S ->> R: Present capability (Presentation)
+      Note over S,R: Enforce at Resource CEP<br>Write Access PoAR on R's sigchain<br>Deliver PoAR to S
+    else Subject-side CEP (placement=S, bridging=false) [SSA wallet/session]
+      S ->> S: Present capability (internal Presentation)
+      S ->> S: Derive short-scope token
+      S ->> R: ToA API call (using token)
+      Note over S: Write Access PoAR on S's sigchain
+    else Subject-side CEP (placement=S, bridging=true) [SS-BA, rare]
+      S ->> S: Present capability (internal Presentation)
+      S ->> S: Derive or reveal using S-owned lease
+      S ->> R: ToA API call
+      Note over S: Write Access PoAR on S's sigchain
+    end
+  end
+
+  opt UseReceipt (optional, TAP may require)
+    S ->> S: Write UseReceipt (ref G & PoAR P)
+  end
+
+  opt Outcome measurable
+    Note over S,R: Measuring agent writes VOR where observed
+    alt Subject-side measurer
+        S ->> S: Write VOR
+    else Resource-native measurer
+        R ->> R: Write VOR
+    end
+  end
+
+  par Either P or S assembles View
+    P ->> V: ViewReceipt {G, PoAR, Use?, VOR?} (with lens & tapProfile)
+    S ->> V: ViewReceipt {G, PoAR, Use?, VOR?} (with lens & tapProfile)
+  end
+
+  V ->> V: Accept/Settle (per TAP/RAM)
+  Note right of V: Accept / Pay / Comply
+
+  Note over P,S: Storage/Durability:<br>- Hot: recent envelopes + index<br>- Seal: Merkle segments + SegmentReceipt<br>- Cold: Custody (S3/MinIO/IPFS, E2E enc)<br>- Escrow: PinningReceipt<br>- Anchors: AnchorReceipt (hash-only)
+```
+
+### How to Read This Diagram
+
+- Participants:
+  - P (Principal): The entity granting authority (e.g., a DevOps lead, a
+    homeowner).
+  - S (Subject): The entity performing the action (e.g., a CI/CD runner, a smart
+    lock app).
+  - R (Resource): The target of the action (e.g., a Kubernetes API, a Power
+    Grid, a Door Lock).
+  - V (Verifier): The entity that needs proof (e.g., an Auditor, an Insurer, an
+    Escrow agent).
+- The Happy Path: The numbered steps show the ideal flow from Issue Grant G to
+  Accept/Settle.
+- Enforcement Variants (The `alt` block): This block is a high-level summary of
+  the four ways that authority can be enforced, depending on where the
+  "gatekeeper" (the CEP) is located. This is the most complex part of the
+  system, and it is expanded in full detail in the second diagram.
+- Receipts (`opt` blocks): The flow generates several types of receipts. The
+  Access PoAR (Proof of Action) is the primary receipt proving the action was
+  authorized. The UseReceipt is an optional acknowledgment from the Subject, and
+  the VOR (Verifiable Outcome Receipt) is a separate proof of the result.
+- Durability (Bottom Note): This note shows the layered approach to storage,
+  ensuring receipts are both readily available ("Hot") and securely archived for
+  the long term ("Cold"), with options for independent verification
+  ("Escrow/Anchors").
+
+## Enforcement Variants - Detailed View
+
+This diagram is a detailed zoom-in of the "Enforcement Variants" block from the
+first diagram. It shows the precise mechanics of how a capability is verified
+and enforced in each of the four possible architectural patterns. The choice of
+pattern depends on whether the Resource is a modern, PK-native system or a
+legacy one, and on the security requirements of the transaction.
+
+```mermaid
+---
+title: Enforcement Variants - Detailed View of CEP Placements and Modes
+config:
+  theme: redux-color
+---
+sequenceDiagram
+  participant P as Principal (P)<br>- Sigchain (P)<br>- Vault (leases/policy)
+  participant S as Subject (S)<br>- Sigchain (S)
+  participant R as Resource / ToA / SoA<br>(e.g., API, Power Grid, Door Lock)
+  participant V as Verifier / Auditor / Escrow<br>(TAP/RAM acceptance)
+
+  autonumber
+
+  alt Principal-side CEP (placement=P, bridging=true) [PS-BA]
+    Note over P: If P and R are the same trust boundary<br>this is effectively native (colocated)<br>bridging=false, PoAR still on P's sigchain
+    S ->> P: Present capability (Presentation)
+    break Verification fails at P
+      Note over P: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
+      Note over P: Write DenyReceipt on P's sigchain
+      P ->> S: Deliver DenyReceipt
+    end
+    alt Mediate at P
+      Note over P: Verify Presentation + Bind + fresh LeaseRef<br>Record requestDigest vs Allowed-Surface
+      P ->> R: ToA API call
+      R -->> P: Result
+      P -->> S: Result (if requester expects data)
+    else Derive at P
+      Note over P: Verify Presentation + Bind + fresh LeaseRef
+      P ->> S: Short-scope token (session-bound)
+      S ->> R: ToA API call (using token)
+      R -->> S: Result
+    else Reveal at P (last resort)
+      Note over P: Break-glass<br>dual-control, tiny ttl/scope, audit correlation, immediate revoke
+      P ->> S: Raw secret
+      S ->> R: ToA API call (bearer)
+      R -->> S: Result
+    end
+    Note over P: Write Access PoAR on P's sigchain<br>exposureMode = mediate/derive/reveal
+    P ->> S: Deliver PoAR
+
+  else Resource-side CEP (placement=R, bridging=false) [native]
+    S ->> R: Present capability (Presentation)
+    break Verification fails at R
+      Note over R: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
+      Note over R: Write DenyReceipt on R's sigchain
+      R ->> S: Deliver DenyReceipt
+    end
+    Note over R: Enforce at Resource CEP
+    R -->> S: Result (if requester expects data)
+    Note over R: Write Access PoAR on R's sigchain
+    R ->> S: Deliver PoAR
+
+  else Subject-side CEP (placement=S, bridging=false) [SSA wallet/session]
+    Note over S: S does not hold long-lived upstream lease.
+    S ->> S: Present capability (internal Presentation)
+    break Verification fails at S
+      Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
+      Note over S: Write DenyReceipt on S's sigchain
+      %% Optional notify P for audit
+      S -->> P: Notify DenyReceipt (policy-dependent)
+    end
+    S ->> S: Derive short-scope token (federated/workload identity)
+    S ->> R: ToA API call (using token)
+    R -->> S: Result
+    Note over S: Write Access PoAR on S's sigchain
+
+  else Subject-side CEP (placement=S, bridging=true) [SS-BA, rare]
+    S ->> S: Present capability (internal Presentation)
+    break Verification fails at S
+      Note over S: Deny path<br>Mint DenyReceipt with reason code<br>(binding_mismatch, lease_stale, surface_violation, rate_limit)
+      Note over S: Write DenyReceipt on S's sigchain
+      %% Optional notify P for audit
+      S -->> P: Notify DenyReceipt (policy-dependent)
+    end
+    alt Mediate at S (no token egress)
+      Note over S: Mediate only when S wants to ensure that no token ever leaves the CEP
+      S ->> R: ToA API call using S-held lease (or short-scope token retained at S)
+      R -->> S: Result
+    else Derive at S (preferred)
+      S ->> S: Derive short-scope token from S-held lease
+      S ->> R: ToA API call (using token)
+      R -->> S: Result
+    else Reveal at S (last resort)
+      Note over S: Break-glass only when S owns upstream<br>tiny ttl/scope, dual-control, audit correlation, immediate revoke
+      S ->> S: Reveal raw secret to caller
+      S ->> R: ToA API call (bearer)
+      R -->> S: Result
+    end
+    Note over S: Write Access PoAR on S's sigchain
+  end
+```
+
+### How to Read This Diagram
+
+- The Four Variants (`alt` blocks):
+  - Principal-side CEP [PS-BA]: This is the default pattern for bridging to
+    legacy systems. The Principal's agent acts as a secure "butler" (a Bridge
+    Adapter), holding the master key and interacting with the legacy Resource on
+    the Subject's behalf. It details the three modes: Mediate, Derive, and
+    Reveal.
+  - Resource-side CEP [native]: This is the ideal, end-state pattern for modern,
+    PK-native systems. The Resource itself has a built-in enforcement point. It
+    can verify the Subject's capability directly, without an intermediary.
+  - Subject-side CEP [SSA wallet/session]: This pattern is for federated
+    identity scenarios. The Subject's agent uses its own strong identity (e.g.,
+    a cloud workload identity) to Derive a temporary credential directly from
+    the Resource.
+  - Subject-side CEP [SS-BA, rare]: This is a rare pattern used only when the
+    Subject itself owns the master key to a legacy system it needs to bridge.
+- The Deny Path (`break` blocks): Each variant includes an explicit flow for
+  what happens when verification fails. The enforcing CEP mints a DenyReceipt
+  with a reason code, providing a verifiable audit trail of failed attempts.
+- PoAR Provenance: Crucially, this diagram shows who mints the Access PoAR in
+  each case. The rule is simple: the enforcer mints the proof. This means the
+  PoAR is written to the sigchain of P, R, or S, depending on the variant used.
+  This is fundamental to the system's distributed and verifiable nature.

docs/theory/trust-operating-system.md

@@ -0,0 +1,103 @@
+# Trust Operating System
+
+In today's interconnected world, trust is fracturing. Opaque, centralized
+systems are struggling to keep pace with the complexity of global trade, AI
+agency, and the need for digital sovereignty. A new foundation is needed.
+
+Polykey is building the open, interoperable infrastructure that allows diverse,
+sovereign actors to transact with cryptographic certainty. We turn real-world
+actions into settlement-grade receipts, enabling a new era of secure, efficient,
+and trustworthy collaboration. We believe the future is not about closed,
+competing stacks, but about shared, open protocols that create value for
+everyone.
+
+## Ecosystem Flywheel Map
+
+This single diagram provides the complete, top-level map of Polykey's ecosystem
+virtuous cycle, showing how each layer and component logically enables the next,
+from the deepest "why" to the most practical "where."
+
+```mermaid
+---
+title: "Polykey Ecosystem Flywheel Map: From Verifiable Security to a Verifiable Economy"
+config:
+  layout: elk
+  htmlLabels: true
+---
+flowchart TB
+  subgraph GRN["<span style='white-space: nowrap'>THE GRAND NARRATIVE (The 'Why')</span>"]
+    GRN1["Trust Operating System:<br>From Sovereign Stacks to The Interoperability Regime (Federated Model)"]
+    GRN2["Our Mission: Build the 'Receipt Rails' - a neutral, verifiable utility for the cyber-physical economy."]
+  end
+  subgraph AF["<span style='white-space: nowrap'>THE ACCEPTANCE FRAMEWORK (The 'So What?')</span>"]
+    direction LR
+    TAP["TAP (Threat & Acceptance Policy)<br> - The Rulebook"]
+    RAM["RAM <br>(Receipt Acceptance Memo)<br> - The Social Contract"]
+    ATN["Accredited Trust Network (ATN)<br>- The Governance Body"]
+  end
+  subgraph RE["<span style='white-space: nowrap'>THE RECEIPT ENGINE (The 'What')</span>"]
+    direction LR
+    PoAR["PoAR (Proof of Action)"]
+    VOR["VOR (Verifiable Outcome Record)"]
+    ViewRec["ViewReceipt & E-Pack<br>(Settlement-Grade Evidence)"]
+  end
+  subgraph AFAB["<span style='white-space: nowrap'>THE AUTHORITY FABRIC (The 'How')</span>"]
+    direction LR
+    Ident["Identity (Gestalts)"]
+    Capab["Capabilities<br>(Identity- & Secret-Bound)"]
+    Sigchain["Sigchain (The Verifiable Ledger)"]
+  end
+  subgraph RW["<span style='white-space: nowrap'>THE REAL WORLD (The 'Where' - Wedges & Primitives)</span>"]
+    direction LR
+    Polykey["The Polykey Vault<br>(Cold Storage for Authority Assets)"]
+    CEP["The CEP / Bridge Adapter<br>(The Enforcement Point / The Legacy Bridge)"]
+    Wedge["The Wedge Portfolio<br>(DevOps, Identity, Energy, Supply Chain, etc.)"]
+  end
+  TAP --> RAM
+  RAM --> ATN
+  PoAR --> VOR
+  VOR --> ViewRec
+  Ident --> Capab
+  Capab --> Sigchain
+  Polykey --> CEP
+  CEP --> Wedge
+  GRN -- Informs & Justifies --> AF
+  AF -- Governs & Validates --> RE
+  RE -- Is Enabled By & Built On --> AFAB
+  AFAB -- Manages & Secures --> RW
+```
+
+### How to Read This Diagram
+
+1. **The Grand Narrative (Top):** This is the mission. It's the big story about
+   the global shift towards a new way of organizing trust.
+2. **The Acceptance Framework (Layer 2):** This is the crucial socio-technical
+   layer that translates the vision into something the real world can accept.
+   The TAP is a set of rules, the RAM is the proof that powerful entities
+   (insurers, regulators) agree to the rules, and the ATN is the resulting
+   network of trusted actors.
+3. **The Receipt Engine (Layer 3):** This is the core "product" of the system.
+   It's the engine that runs on the authority fabric to produce the valuable
+   artifacts (PoARs, VORs, and ViewReceipts) that are governed by the Acceptance
+   Framework.
+4. **The Authority Fabric (Layer 4):** This is the foundational technology, the
+   "how." It's the deep, non-consensus innovation of Polykey: the combination of
+   sovereign Identity, a rich Capability model, and the immutable Sigchain
+   ledger.
+5. **The Real World (Bottom):** This is where the rubber meets the road.
+   - The **Polykey Vault** is the essential primitive for securely storing the
+     "cold" assets of the Authority Fabric.
+   - The **CEP / Bridge Adapter** is the enforcement point that connects the
+     Authority Fabric to the real world, allowing it to mint receipts.
+   - The **Wedge Portfolio** is the strategic application of this entire stack
+     to solve specific, high-value problems in the market.
+
+### The Flywheel Effect
+
+- Success in the Wedges proves the value of the entire stack.
+- This drives adoption of the Primitives (Vaults, CEPs).
+- Which generates more activity in the Authority Fabric and the Receipt Engine.
+- Which creates more demand for a robust Acceptance Framework (more TAPs and
+  RAMs).
+- Which, in turn, validates and strengthens the Grand Narrative, attracting more
+  partners and capital to launch new Wedges.

docusaurus.config.ts

@@ -240,11 +240,15 @@ const config: Config = {
     defaultLocale: 'en',
     locales: ['en'],
   },
+  markdown: {
+    mermaid: true
+  },
   // This ensures that `/x.md` is generated as `/x/index.html` and not `/x.html`.
   // Which is the expected directory layout for most web servers.
   trailingSlash: undefined,
   staticDirectories: ['static'],
   plugins: [pluginSVGR, pluginDocs, pluginTheme, pluginGTag, pluginTailwind],
+  themes: ['@docusaurus/theme-mermaid'],
   themeConfig,
 };