phylaxsystems · czepluch · Jan 15, 2026 · Jan 15, 2026 · Jan 15, 2026 · Jan 15, 2026
diff --git a/credible/architecture-linea.mdx b/credible/architecture-linea.mdx
@@ -0,0 +1,70 @@
+---
+title: 'Linea / Besu Integration'
+description: 'High-level integration of the Credible Layer with Linea via Besu plugins'
+---
+
+This page summarizes the Linea integration pattern at a high level. It focuses on interface boundaries
+and the enforcement flow without internal implementation details.
+
+## Integration Pattern
+
+Linea uses a **plugin pattern** that integrates directly with the Besu node through its plugin system
+and delegates assertion execution to a sidecar process.
+
+Key characteristics:
+
+- **Plugin-based enforcement**: Besu plugins hook into block building to validate transactions
+- **Sidecar execution**: Assertions run in the Credible Layer sidecar alongside the node
+- **Low-latency flow**: Validation happens during block building and returns a valid/invalid decision
+
+## System Overview
+
+```mermaid
+---
+title: Linea Besu Integration (High Level)
+---
+flowchart LR
+  subgraph BesuNode["Linea Besu Node"]
+    TxPool["Transaction Pool"]
+    Builder["Block Builder"]
+    Plugin["Credible Layer Plugin"]
+  end
+
+  subgraph SidecarGroup["Enforcer Sidecar"]
+    SidecarSvc["Assertion Enforcer"]
+    Engine["Assertion Execution Engine"]
+    Store["Assertion Store"]
+    SidecarSvc --> Engine
+    Engine --> Store
+  end
+
+  Registry["Registry Data<br/>(On-Chain Events)"]
+  DA["Assertion DA"]
+
+  TxPool --> Builder
+  Builder --> Plugin
+  Plugin --> SidecarSvc
+  SidecarSvc --> Plugin
+  SidecarSvc --> Registry
+  SidecarSvc --> DA
+```
+
+## Validation Flow
+
+1. The block builder selects a candidate transaction.
+2. The plugin sends the transaction to the sidecar for assertion validation.
+3. The sidecar executes applicable assertions and returns a decision.
+4. The block builder includes valid transactions and drops invalid ones.
+
+## Notes
+
+- The plugin uses Besu’s transaction selection hooks to validate transactions during block building.
+- The sidecar relies on registry data (from on-chain events) and assertion data to determine applicable assertions.
+- This integration does not change core protocol rules; it runs alongside the existing block builder.
+
+## Related Docs
+
+- [Network Integration Overview](/credible/network-integration)
+- [Assertion Enforcer](/credible/assertion-enforcer)
+- [Assertion DA](/credible/assertion-da)
+- [OP Stack](/credible/architecture-op-stack)
diff --git a/credible/architecture-op-stack.mdx b/credible/architecture-op-stack.mdx
@@ -5,6 +5,14 @@ description: 'OP Stack specific implementation of the Credible Layer'
 
 The OP Stack implementation uses [Rollup-Boost](https://github.com/flashbots/rollup-boost) to connect an external sidecar assertion validation components with the L2 sequencer through a bridge proxy.
 
+<Note>
+For the general integration path, see [Network Integration Overview](/credible/network-integration).
+</Note>
+
+<Note>
+Looking for the Besu/Linea pattern? See [Linea / Besu Integration](/credible/architecture-linea).
+</Note>
+
 ## Architecture Diagram
 
 ```mermaid
@@ -39,9 +47,9 @@ end
 SequencerEL --> |Fallback Blocks + Validation| RollupBoost
 
 AssertionDA --> |Serve Assertions| AssertionEnforcerBlockBuilder
-AssertionEnforcerCLI --> |Submit Assertions| AssertionEnforcerDapp
-AssertionEnforcerDapp --> |OAuth| AssertionEnforcerCLI
-AssertionEnforcerDapp --> |Submit Assertions| AssertionDA
+AssertionEnforcerCLI --> |Store bytecode| AssertionDA
+AssertionEnforcerCLI --> |Auth + submit metadata| AssertionEnforcerDapp
+AssertionEnforcerDapp --> |Fetch assertions| AssertionDA
 
 AssertionEnforcerEL <--> |Pulls State + Txs| SequencerEL
 AssertionEnforcerEL <--> |Provide Best Transactions| AssertionEnforcerBlockBuilder

diff --git a/credible/architecture-overview.mdx b/credible/architecture-overview.mdx
@@ -22,7 +22,7 @@ The Credible Layer consists of four core components:
 
 The Credible Layer is a **sidecar security infrastructure** that validates transactions against developer-defined security rules (assertions) before they are included in blocks. As a sidecar, it runs alongside the L2 network's main components, intercepting transactions during block building and ensuring they don't violate any deployed security rules.
 
-The Assertion Enforcer is operated by the network's sequencer. Networks that integrate the Credible Layer run this sidecar as part of their sequencer infrastructure. This means you're not adding new trust assumptions: if you trust the network to include your transactions, you can trust it to enforce your assertions.
+The Assertion Enforcer is operated by the network's block builder or sequencer. Networks that integrate the Credible Layer run this sidecar as part of their block production infrastructure. This means enforcement does not rely on external execution services beyond the network you already trust to include transactions.
 
 ### System Architecture
 
@@ -43,7 +43,7 @@ flowchart LR
 
     subgraph network["Network"]
         direction LR
-        VALIDATOR["Network Validator"]
+        VALIDATOR["Block Builder / Sequencer"]
         REGISTRY["Credible Layer<br/>Contracts"]
     end
 
@@ -57,7 +57,7 @@ flowchart LR
     CLI -->|"Submit"| DAPP
     DAPP -->|"Deploy"| REGISTRY
 
-    VALIDATOR -->|"Transaction"| PhEVM
+    VALIDATOR -->|"Candidate Tx"| PhEVM
     PhEVM -->|"Valid/Invalid"| VALIDATOR
     PhEVM -.->|"Fetch"| DA
     PhEVM -.->|"Check"| REGISTRY
@@ -77,16 +77,16 @@ flowchart LR
 
 The diagram shows two main flows:
 
-**Development Flow**: Developers use [`pcl`](/credible/store-submit-assertions) to develop and test assertions. `pcl` stores assertion code in [Assertion DA](/credible/assertion-da), then submits to the [Credible dApp](/credible/dapp-overview). The dApp deploys assertions to the on-chain [Credible Layer Contracts](/credible/credible-layer-contracts).
+**Development Flow**: Developers use [`pcl`](/credible/store-submit-assertions) to develop and test assertions. `pcl` stores assertion code in [Assertion DA](/credible/assertion-da), then submits to the [Credible dApp](/credible/dapp-overview). The dApp deploys assertions to the on-chain [Credible Layer Contracts](/credible/credible-layer-contracts) so they can be enforced by the network.
 
-**Runtime Flow**: The network validator sends transactions to the [Assertion Enforcer](/credible/assertion-enforcer) during block production. The enforcer fetches relevant assertions and executes them via [PhEVM](/credible/phevm). Valid transactions are included in blocks; invalid transactions are dropped.
+**Runtime Flow**: The block builder or sequencer sends transactions to the [Assertion Enforcer](/credible/assertion-enforcer) during block production. The enforcer uses its registry snapshot (from on-chain events) and cached assertion bytecode (from [Assertion DA](/credible/assertion-da)) to execute relevant assertions via [PhEVM](/credible/phevm). Valid transactions are included in blocks; invalid transactions are dropped.
 
 ### How It Works
 
 1. **Assertion Deployment**: Developers write and submit assertions through `pcl` and the dApp, which are stored in Assertion DA and deployed on-chain
 2. **Transaction Validation**: The network sends transactions to the Assertion Enforcer during block production
 3. **Assertion Execution**: The Assertion Enforcer simulates each transaction and validates it against relevant assertions using PhEVM
-4. **Validation Results**: The Assertion Enforcer returns valid/invalid results to the network validator
+4. **Validation Results**: The Assertion Enforcer returns valid/invalid results to the block builder or sequencer
 5. **Security Enforcement**: Only valid transactions are included in blocks, preventing security violations before they reach the blockchain
 
 ## Transaction Flow
@@ -99,10 +99,11 @@ title: Transaction Validation Flow
 ---
 flowchart LR
     USER["User"] -->|"Submits Transaction"| MP["Mempool"]
-    MP --> SIDECAR["Assertion Enforcer<br/>(Sidecar)"]
-
-    SIDECAR -->|"Valid"| BLOCK["Block"]
+    MP --> BUILDER["Block Builder / Sequencer"]
+    BUILDER -->|"Candidate Tx"| SIDECAR["Assertion Enforcer<br/>(Sidecar)"]
+    SIDECAR -->|"Valid"| BUILDER
     SIDECAR -->|"Invalid"| DROP["Dropped"]
+    BUILDER -->|"Include"| BLOCK["Block"]
 
     classDef user fill:#9e9e9e,stroke:#616161,stroke-width:2px,color:#fff
     classDef mempool fill:#64b5f6,stroke:#1976d2,stroke-width:2px,color:#fff
@@ -127,6 +128,42 @@ flowchart LR
 The Assertion Enforcer is integrated with the block builder. During block production, the block builder invokes the Assertion Enforcer to validate transactions before including them.
 </Note>
 
+## Incident Lifecycle (Public View)
+
+When an assertion is violated, the incident is recorded and exposed for transparency and alerts.
+
+```mermaid
+---
+title: Incident Lifecycle
+---
+flowchart LR
+    ENFORCER["Assertion Enforcer"] --> DAPP["Credible dApp"]
+    DAPP --> DASH["Transparency Dashboard"]
+    DAPP --> ALERTS["Slack/PagerDuty Alerts"]
+
+    classDef enforcer fill:#7b1fa2,stroke:#4a148c,stroke-width:2px,color:#fff
+    classDef dapp fill:#388e3c,stroke:#1b5e20,stroke-width:2px,color:#fff
+    classDef output fill:#0288d1,stroke:#01579b,stroke-width:2px,color:#fff
+
+    class ENFORCER enforcer
+    class DAPP dapp
+    class DASH,ALERTS output
+```
+
+## Integration Paths
+
+<CardGroup cols={2}>
+  <Card title="dApp Integration Overview" icon="browser" href="/credible/dapp-integration">
+    How protocols deploy and manage assertions
+  </Card>
+  <Card title="Network Integration Overview" icon="sitemap" href="/credible/network-integration">
+    How networks and sequencers integrate enforcement
+  </Card>
+  <Card title="Interface Overview" icon="diagram-project" href="/credible/interfaces-overview">
+    High-level component boundaries and dependencies
+  </Card>
+</CardGroup>
+
 For details on the assertion validation process, see [Assertion Enforcer](/credible/assertion-enforcer#validation-process).
 
 ## System Components
@@ -179,4 +216,7 @@ For concrete assertion examples and real-world use cases, explore the [Assertion
   <Card title="Cheatcodes Reference" icon="book" href="/credible/cheatcodes-reference">
     Detailed reference for assertion functions
   </Card>
+  <Card title="Trust Model" icon="shield-check" href="/credible/trust-model">
+    Guarantees, assumptions, and failure modes
+  </Card>
 </CardGroup>
diff --git a/credible/assertion-da.mdx b/credible/assertion-da.mdx
@@ -59,7 +59,7 @@ pcl store MyAssertion
 2. Uploads flattened source code and compiler options to Assertion DA
 3. Returns the assertion ID (Keccak256 hash of the bytecode) and DA prover signature
 
-Only the contract owner (the address returned by the contract's `owner()` function) can deploy, modify, or remove assertions for their contract. This is enforced on-chain by the Credible Layer smart contracts, which verify ownership before allowing any assertion management operations. During the early phase of the project, there is also a manual whitelist in place. Ownership verification will be expanded and improved in future versions to support additional ownership patterns and multisig integration. See [Ownership Verification](/credible/ownership-verification) for details.
+Only authorized admins can deploy, modify, or remove assertions for their contracts. This is enforced on-chain by the Credible Layer smart contracts, which verify administrative authority (such as owner-based checks or approved allowlists) before allowing assertion management operations. Ownership verification will be expanded and improved in future versions to support additional ownership patterns and multisig integration. See [Ownership Verification](/credible/ownership-verification) for details.
 
 ### Retrieving Assertions
 
@@ -108,7 +108,7 @@ The protocol intentionally omits bytecode validation because:
 
 **Integrity**: The Keccak256 hash verification ensures assertions haven't been modified. Each assertion ID uniquely corresponds to its bytecode.
 
-**Transparency**: All assertions are publicly accessible, enabling users and auditors to verify security measures.
+**Transparency**: Assertions can be retrieved via Assertion DA, enabling users and auditors to verify security measures.
 
 **Incentive Alignment**: Invalid assertions only harm the developer who submitted them, as they will fail execution deterministically.
 

diff --git a/credible/assertion-enforcer.mdx b/credible/assertion-enforcer.mdx
@@ -7,9 +7,9 @@ The Assertion Enforcer is a sidecar component that validates transactions agains
 
 ## Role in the System
 
-The Assertion Enforcer sits between the mempool and block production:
+The Assertion Enforcer operates inside the block production pipeline:
 
-1. Receives transactions from the network validator
+1. Receives candidate transactions from the block builder or sequencer
 2. Identifies which assertions apply to each transaction
 3. Invokes [PhEVM](/credible/phevm) to execute assertions against transaction states
 4. Returns validation results (valid/invalid) to the network
@@ -20,7 +20,7 @@ The Assertion Enforcer sits between the mempool and block production:
 As a [sidecar](/credible/glossary#sidecar), the Assertion Enforcer:
 
 - **Operates independently** from the main L2 infrastructure
-- **Integrates without code changes** to the sequencer
+- **Integrates alongside block builders** without changing core protocol rules
 - **Scales separately** from the main network components
 - **Fails gracefully** without affecting L2 operations
 
@@ -79,7 +79,7 @@ flowchart LR
 
 ### Step-by-Step
 
-1. **Identify Relevant Assertions**: The Assertion Enforcer queries the [on-chain registry](/credible/credible-layer-contracts) to find which assertions apply to the contracts the transaction interacts with
+1. **Identify Relevant Assertions**: The Assertion Enforcer consults registry data (indexed from [on-chain events](/credible/credible-layer-contracts)) to find which assertions apply to the contracts the transaction interacts with
 
 2. **Fetch Assertion Bytecode**: Assertion bytecode is retrieved from internal cache (populated from [Assertion DA](/credible/assertion-da) when assertions are deployed)
 
@@ -99,9 +99,16 @@ flowchart LR
 The Assertion Enforcer integrates with block builders to ensure only valid transactions enter blocks:
 
 - Transactions that would violate assertions are dropped before block inclusion
-- The network validator receives clear valid/invalid signals
+- The block builder or sequencer receives clear valid/invalid signals
 - Block production continues normally with validated transactions
 
+## Operational Expectations (Public)
+
+- **Non-invasive**: Runs alongside existing block builders without changing consensus rules
+- **Deterministic**: Results are based on on-chain state and assertion code only
+- **Staging support**: Networks can validate assertions before enforcing them in production
+- **Transparent outcomes**: Incidents are visible in the dApp and dashboard
+
 ## Forced Inclusion Transactions
 
 Forced inclusion transactions (such as L1→L2 deposits) require special handling since they must be included regardless of assertion results. The Credible Layer has mitigation pathways for these scenarios.
@@ -119,3 +126,13 @@ To ensure high-performance validation, the Assertion Enforcer maintains an inter
 
 This caching strategy ensures validation latency doesn't impact block production times.
 
+## Learn More
+
+<CardGroup cols={2}>
+  <Card title="Network Integration" icon="sitemap" href="/credible/network-integration">
+    High-level integration for networks and sequencers
+  </Card>
+  <Card title="Trust Model" icon="shield-check" href="/credible/trust-model">
+    Guarantees, assumptions, and failure modes
+  </Card>
+</CardGroup>
diff --git a/credible/credible-introduction.mdx b/credible/credible-introduction.mdx
@@ -27,23 +27,32 @@ The Credible Layer is security infrastructure that enables developers to link se
   <Card title="Start Building" icon="rocket" href="/credible/pcl-quickstart">
     Write and deploy your first assertion. Get from zero to protected in minutes.
   </Card>
+  <Card title="Evaluate Credible Layer" icon="list-check" href="/credible/evaluate-credible-layer">
+    A quick checklist for dApps and networks.
+  </Card>
   <Card title="Understand at a High Level" icon="compass" href="/credible/credible-layer-overview">
     Non-technical overview of how the Credible Layer prevents exploits.
   </Card>
   <Card title="Evaluate the Architecture" icon="gears" href="/credible/architecture-overview">
     Technical deep dive into system design, transaction flow, and integration requirements.
   </Card>
+  <Card title="Integrate as a Protocol" icon="browser" href="/credible/dapp-integration">
+    High-level adoption flow for protocol teams.
+  </Card>
   <Card title="Browse Examples" icon="book" href="/assertions-book/assertions-book-intro">
     Explore assertion patterns and see how real-world hacks could have been prevented.
   </Card>
+  <Card title="Integrate as a Network" icon="sitemap" href="/credible/network-integration">
+    High-level integration for networks and sequencers.
+  </Card>
 </CardGroup>
 
 ## Key Benefits
 
 - **Pre-execution prevention** — Exploits are blocked before they execute, not detected after
 - **No contract changes** — Add protection to any contract, including immutable ones
 - **Transparent & verifiable** — All rules are public Solidity, auditable by anyone
-- **No external dependencies** — Runs natively within the network, no SaaS or APIs
+- **No external execution services** — Enforcement runs within the network’s block-building flow
 - **Zero false positives** — Binary enforcement based on your rules, no AI guessing
 
 ## Community & Support

diff --git a/credible/credible-layer-contracts.mdx b/credible/credible-layer-contracts.mdx
@@ -9,6 +9,10 @@ The Credible Layer Contracts are the on-chain smart contracts that power the pro
 The contracts are open source and available on [GitHub](https://github.com/phylaxsystems/credible-layer-contracts).
 </Info>
 
+<Note>
+For how these contracts fit into the overall system, see [Interface Overview](/credible/interfaces-overview).
+</Note>
+
 ## Components
 
 ```mermaid

diff --git a/credible/credible-layer-overview.mdx b/credible/credible-layer-overview.mdx
@@ -15,7 +15,7 @@ Phylax's real-time security system detects and pre-emptively removes exploits be
 
 At a glance:
 
-- **Security rules** are defined by the protocol team and deployed as on-chain [assertions](/credible/glossary#assertion)
+- **Security rules** are defined by the protocol team and deployed on-chain as [assertions](/credible/glossary#assertion)
 - **The network** validates every transaction against relevant assertions before adding them to blocks
 - **Invalid transactions** are [dropped](/credible/glossary#drop). If an assertion fails, the transaction never executes
 
@@ -55,6 +55,17 @@ Assertions enable a wide range of security and compliance use cases:
 
 For concrete examples and implementations, explore the [Assertions Book](/assertions-book/assertions-book-intro).
 
+## Who It's For
+
+<CardGroup cols={2}>
+  <Card title="Protocol Teams" icon="code" href="/credible/dapp-integration">
+    Deploy and manage assertions to protect your contracts
+  </Card>
+  <Card title="Networks & Sequencers" icon="sitemap" href="/credible/network-integration">
+    Integrate enforcement into block building
+  </Card>
+</CardGroup>
+
 ## How It Works
 
 ### Defining Security Rules
@@ -163,6 +174,8 @@ For the full technical flow, see [Architecture](/credible/architecture-overview)
 The Credible Layer is designed as neutral middleware that preserves decentralization for both dApps and networks. Learn more about [why neutrality matters](/credible/neutrality).
 </Note>
 
+For interface boundaries and integration touchpoints, see [Interface Overview](/credible/interfaces-overview).
+
 ## Next Steps
 
 Ready to dive deeper?

diff --git a/credible/dapp-incidents.mdx b/credible/dapp-incidents.mdx
@@ -5,6 +5,11 @@ description: 'View incidents prevented by the Credible Layer'
 
 Incidents show when transactions were dropped because they violated assertions protecting contracts. This happens when a transaction that interacted with an assertion-protected contract was dropped by the [Enforcer](/credible/glossary#assertion-enforcer) because it caused an assertion to revert.
 
+<Note>
+For the end-to-end flow, see the incident lifecycle diagram in
+[Architecture Overview](/credible/architecture-overview#incident-lifecycle-public-view).
+</Note>
+
 ## How Incidents Are Grouped
 
 An incident represents the invalidation of an assertion over a one-hour time period. Multiple dropped transactions can belong to the same incident if they violate the same assertion within that window.
@@ -101,4 +106,3 @@ Incident viewing is read-only. You cannot modify or delete incident records.
     Understand how assertion validation works
   </Card>
 </CardGroup>
-