docs: reposition around undercollateralized lending for leverage

README.md

@@ -6,8 +6,8 @@ This web application contains all documentation for t1. It was forked from the [
 
 ### t1 documentation currently has two sections:
 
-- Intro - General t1 information or concepts useful for using t1
-- Integrations - e.g. xChainRead API documentation
+- Intro - the credit protocol (programmable custody, margin accounts, the risk engine, lending pools), the TEE and Real-Time Proving infrastructure under it, the long-term network design, and the ecosystem
+- Integrations - how to offer leverage on a venue, how to provide lending liquidity, and the underlying primitives (xChainRead, ERC-7683, Docker dApps)
 
 ### TODOs:
 

docs/integration/7683/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "ERC-7683",
-  "position": 2
+  "position": 5
 }

docs/integration/docker/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "Docker dApps",
-  "position": 3
+  "position": 6
 }

docs/integration/integration.md

@@ -4,4 +4,22 @@ sidebar_label: Integration Overview
 sidebar_position: 1
 ---
 
-Use the sidebar on the left to learn about using t1's infrastructure and integrate your app.
+# Integration Overview
+
+There are two ways to build with t1, depending on what you bring to it.
+
+## Offer leverage to your users
+
+You operate a venue — an exchange, a prediction market, a trading app — and you want your users to trade with borrowed capital without your taking custody of it. t1 issues each of them a [margin account](../intro/protocol/margin-accounts.md) whose key enforces a policy you and your lenders agree on, and handles liquidation itself.
+
+→ [Offer Leverage on Your Venue](./leverage.md)
+
+## Provide lending liquidity
+
+You have capital and want it earning on undercollateralized loans without counterparty exposure, a legal agreement, or a KYC program to administer. Set up a pool with your own parameters, or deposit into an existing one.
+
+→ [Provide Lending Liquidity](./lending.md)
+
+---
+
+t1 also exposes the primitives the credit protocol is built on — [xChainRead](./xChainRead/overview.md), [ERC-7683](./7683/solver-integration.md), and [Docker dApps](./docker/overview.md) — for developers integrating them directly. They are in the sidebar.

docs/integration/lending.md

@@ -0,0 +1,28 @@
+---
+title: Provide Lending Liquidity
+sidebar_label: Provide Liquidity
+sidebar_position: 3
+---
+
+# Provide Lending Liquidity
+
+Deposit capital into a t1 [lending pool](../intro/protocol/lending-pools.md) and it is lent to borrowers on undercollateralized terms. Repayment is enforced by the borrower's [margin account](../intro/protocol/margin-accounts.md), not promised by the borrower.
+
+## What you are relying on
+
+- **Liquidations attested in real time.** Each decision is attested by the enclave that made it, so you can verify a close rather than infer it from a term sheet or take it on report.
+- **Risk parameters customizable per pool.** Venues, assets, maximum position size, liquidation threshold, and interest are yours to set.
+- **No counterparty legal exposure.** The margin account is the counterparty, so there is no agreement to draft and no debtor to pursue.
+- **Permissionless borrowers, no KYC to administer.** Borrowers are anonymous by design, so you run no identity program.
+
+What you are still exposed to is market risk: a position can gap through its liquidation threshold, or the book behind it can be too thin to unwind at the modeled price. [Residual risk](../intro/protocol/risk-engine.md#residual-risk) covers this, and the maximum size and liquidation threshold you set are the levers over it.
+
+## Two ways in
+
+**Deposit into an existing pool.** Fastest path. You accept the pool's policy as written and start earning on its terms.
+
+**Set up your own pool.** You define the policy — which venues the capital may reach, how much exposure a single account may carry, and where liquidation triggers. Every margin account that borrows from your pool is bound to that policy at the moment its key is created, and the binding cannot be changed afterwards. You also set what borrowing costs, which is a pool parameter rather than part of that binding and can be retuned.
+
+## Get in touch
+
+Pool creation and institutional deposits are handled with us directly. Join the [Discord](https://discord.com/invite/qVEUA6jmGZ) or email [can@t1protocol.com](mailto:can@t1protocol.com).

docs/integration/leverage.md

@@ -0,0 +1,32 @@
+---
+title: Offer Leverage on Your Venue
+sidebar_label: Offer Leverage
+sidebar_position: 2
+---
+
+# Offer Leverage on Your Venue
+
+Your users trade with borrowed capital on your venue, and you never hold it. t1 issues each of them a [margin account](../intro/protocol/margin-accounts.md) controlled by an encumbered key, extends credit into it from a [lending pool](../intro/protocol/lending-pools.md), and runs liquidation itself.
+
+## What you get
+
+- **Leverage on a venue you already operate.** Users trade with borrowed capital on your venue. You are never the custodian of it and never the lender of record.
+- **Margin accounts.** Credit is issued against a policy you help define, with liquidation handled by the protocol rather than by your operations team.
+- **Cross-venue and cross-chain collateralization.** One collateral base per user, positions across separate venues and chains. A user's margin on your venue is not stranded there.
+
+## What it means for your users
+
+They keep direction rights over the capital and never get withdrawal rights over it, which is the property that lets the loan be undercollateralized in the first place. They do not hand custody of their own deposit to you, and they do not pass KYC to borrow. See [Programmable Custody](../intro/protocol/programmable-custody.md) for the mechanism.
+
+## What integrating involves
+
+The shape of the work depends on whether your venue settles on-chain or runs an off-chain orderbook, but the pieces are the same in both cases:
+
+1. **Agree the policy.** Which venues and assets the account may touch, the maximum position size, and the liquidation threshold. This is what your lenders are pricing, and it is bound into the account's key at creation.
+2. **Connect the venue.** t1's risk engine needs to read positions and prices from your venue, and the encumbered key needs to be able to place and cancel orders on it.
+3. **Point your frontend at the account.** Your users deposit into their margin account and trade from it. The signature gate is transparent to them until it rejects something the policy forbids.
+4. **Source the liquidity.** Either bring your own lenders or draw on existing pools.
+
+## Get in touch
+
+There is no self-serve onboarding yet; venue integrations are done with us directly. Join the [Discord](https://discord.com/invite/qVEUA6jmGZ) or email [can@t1protocol.com](mailto:can@t1protocol.com).

docs/integration/xChainRead/_category_.json

@@ -1,4 +1,4 @@
 {
   "label": "xChainRead",
-  "position": 1
+  "position": 4
 }

docs/intro/ecosystem.md

@@ -0,0 +1,25 @@
+---
+id: ecosystem
+title: Ecosystem
+sidebar_position: 2
+---
+
+t1's credit infrastructure already powers two applications. They differ in the venue they lend against and the policy their pools run.
+
+## amplifi
+
+**Permissionless prime brokerage for prediction markets and perpDEXs.** Up to **10×** leverage on Polymarket, with no KYC and no custody transfer: a trader deposits margin, draws credit against it, and trades a Polymarket position from an account that can only repay the pool and release what is left once the loan is covered.
+
+[amplifi.finance →](https://amplifi.finance/?utm_source=t1-docs&utm_medium=website&utm_campaign=t1docs-credit&utm_content=ecosystem-page&utm_term=10x-polymarket)
+
+## juiced
+
+**Leverage on memecoins before they list on perpDEXs.** Up to **5×** on Robinhood Chain. The interesting case for programmable custody, because these markets have no perpetual venue to borrow against.
+
+[juiced.exchange →](https://juiced.exchange/?utm_source=t1-docs&utm_medium=website&utm_campaign=t1docs-credit&utm_content=ecosystem-page&utm_term=robinhood-chain)
+
+## Building on t1
+
+The same infrastructure is available to other venues and applications. If you operate a venue and want your users to trade with borrowed capital you never hold, see [Offer Leverage on Your Venue](../integration/leverage.md). If you want to put capital behind a policy, see [Provide Lending Liquidity](../integration/lending.md).
+
+Both applications are moving onto the full architecture described in [Programmable Custody](./protocol/programmable-custody.md); [Rollout](./protocol/programmable-custody.md#rollout) covers where that stands.

docs/intro/glossary.md

@@ -1,9 +1,45 @@
 ---
 id: glossary
 title: Glossary
-sidebar_position: 4
+sidebar_position: 5
 ---
 
+## Programmable custody
+
+t1's name for custody that is enforced by code rather than by an institution. A margin account's private key is held inside a [TEE](#tee) and bound to a [loan policy](#loan-policy) at creation, so the key signs a transaction only if the policy permits it. The borrower can direct the capital and can never withdraw it. See [Programmable Custody](/intro/protocol/programmable-custody).
+
+## Private key encumbrance
+
+The academic term for a key whose holder cannot use it freely, because the conditions under which it will sign are fixed outside their control. Programmable custody is an applied form of it.
+
+## Encumbered key
+
+The keypair controlling a [margin account](#margin-account). Generated inside the TEE, with the private half never leaving it, and bound to a loan policy at the moment of creation. The binding cannot be redone, so an account's policy is fixed for its whole life.
+
+## Margin account
+
+The account t1 lends into: one per borrower, holding their own deposit plus the credit drawn against it, and appearing as the trading address at every venue the policy permits. Positions held on separate venues resolve into this single account. See [Margin Accounts](/intro/protocol/margin-accounts).
+
+## Loan policy
+
+The rules an encumbered key enforces: the permitted venues and assets, the maximum position size, and the liquidation threshold. Set by the lender when a [lending pool](#lending-pool) is created, and immutable thereafter. A pool's interest rate is a separate parameter and is not fixed this way.
+
+## Signature gate
+
+The point at which a policy is applied. Every transaction an account would make — a borrower's trade, a withdrawal attempt, a liquidation — is presented to the encumbered key, which signs it or does not.
+
+## Lending pool
+
+Where credit comes from. Lenders deposit capital into a pool, the pool carries a loan policy, and every margin account borrowing from it is bound to that policy. A lender wanting different parameters creates a different pool. See [Lending Pools](/intro/protocol/lending-pools).
+
+## LTV
+
+_Loan-to-value_ is the ratio of the credit drawn against a margin account to the current value of what backs it. The policy's _liquidation threshold_ is the LTV at which the risk engine begins closing the position.
+
+## Liquidation
+
+Closing a position to protect the lender's principal when an account's LTV crosses its liquidation threshold. On t1 a liquidation is an ordinary transaction through the signature gate — it is permitted by the policy, so the key signs it, and the borrower has no way to block it. See [Risk Engine and Liquidation](/intro/protocol/risk-engine).
+
 ## TEE
 
 _Trusted Execution Environments_ ([TEEs](https://tee.fyi/)) are specialized hardware-based environments that isolate sensitive computations and data from the rest of the system, ensuring that data is processed correctly and (optionally) privately.
@@ -12,10 +48,18 @@ In particular, TEEs provide verifiable computation guarantees through a process
 
 Optionally, TEEs can preserve privacy by keeping sensitive data and execution logic concealed from the broader system and external observers.
 
+## Remote attestation
+
+The proof a TEE produces of which code it is running. For a lender it is the load-bearing piece: it is what turns "the policy is enforced" from a claim about t1's behavior into a claim about a published binary with a verifiable measurement.
+
 ## ZKP
 
 A _zero-knowledge (ZK) proof_ is a cryptographic protocol that enables one entity (the prover) to convince another one (the verifier) that a particular claim is true without disclosing any details about the claim itself. ZKPs used in blockchains are mostly used due to their succinctness property—meaning that the work required by the verifier to check the proof is substantially smaller than the work of re-running the computation required to reach the claim independently.
 
+## RTP
+
+_Real-Time Proving_ is the ability to prove state transitions in a rollup within one base layer block, which is 12 seconds for Ethereum L1. For example, this allows previous rollup deposits to be withdrawn immediately (real-time settlement). In the credit protocol it is what lets positions on separate venues resolve into one margin account with proven, rather than reported, state.
+
 ## Reth
 
 [_Reth_](https://github.com/paradigmxyz/reth) (aka _Rust Ethereum_) is an Ethereum execution node implementation focused on being user-friendly, modular, and efficient. Reth is an execution client compatible with all Ethereum consensus client implementations that support the Engine API. As a full Ethereum node, Reth will allow users to sync the complete Ethereum blockchain from genesis and interact with it (and its historical state, if in archive mode) once synced.
@@ -24,14 +68,10 @@ A _zero-knowledge (ZK) proof_ is a cryptographic protocol that enables one entit
 
 [_Execution Extensions_](https://www.paradigm.xyz/2024/05/reth-exex) (aka _ExEx_) are a feature of Reth that allows developers to receive comprehensive data about a newly “mined” block in an observer-listener pattern. Thanks to this, developers can perform actions based on certain changes on the blockchain in an efficient and seamless way.
 
-## RTP
-
-_Real-Time Proving_ is the ability to prove state transitions in a rollup within one base layer block, which is 12 seconds for Ethereum L1. For example, this allows previous rollup deposits to be withdrawn immediately (real-time settlement).
-
 ## Sequencer
 
-_Sequencers_ are a highly decentralized set of nodes tasked with blindly finalizing the ordering of partially-encrypted transactions in a t1 block. Since Sequencers only order transactions rather than executing them (meaning lower hardware and network requirements, in particular no TEE requirement), t1 can achieve high decentralization and censorship resistance. Sequencers provide proofs of _Sequencing Consensus_. For details, check t1's [litepaper](/intro/resources#t1-litepaper).
+A term from t1's [long-term network design](/intro/protocol/architecture). _Sequencers_ are a highly decentralized set of nodes tasked with blindly finalizing the ordering of partially-encrypted transactions in a t1 block. Since Sequencers only order transactions rather than executing them (meaning lower hardware and network requirements, in particular no TEE requirement), t1 can achieve high decentralization and censorship resistance. Sequencers provide proofs of _Sequencing Consensus_. For details, check t1's [litepaper](/intro/resources#t1-vision-litepaper).
 
 ## Executor
 
-_Executors_ are a network of TEE-enabled nodes tasked with executing state changes given the ordered sequences of transaction bundles determined by the Sequencers. Executors provide proofs of _Execution Consensus_. For details, check t1's [litepaper](/intro/resources#t1-litepaper).
+A term from t1's [long-term network design](/intro/protocol/architecture). _Executors_ are a network of TEE-enabled nodes tasked with executing state changes given the ordered sequences of transaction bundles determined by the Sequencers. Executors provide proofs of _Execution Consensus_. For details, check t1's [litepaper](/intro/resources#t1-vision-litepaper).

docs/intro/protocol/architecture.md

@@ -1,10 +1,16 @@
 ---
 id: architecture
-title: Architecture
-sidebar_position: 4
+title: Network Architecture
+sidebar_position: 8
 ---
 
-t1 is a TEE-enabled cross-chain application infrastructure that leverages defense-in-depth to achieve real-time proving. In the  near term (v1), we're building towards achieving RTP with TEE proofs. In the long term, t1 will become a permissionless and decentralized network that will complement TEE proofs with crypto-economic security and bespoke zero-knowledge proofs. You can read more about our long term architecture in our [litepaper](https://docs.t1protocol.com/intro/resources).
+:::note
+
+This page describes t1's long-term design as a permissionless, decentralized network, as set out in the [Vision Litepaper](../resources.md). The credit protocol running today is built on the TEE infrastructure described in [Programmable Custody](./programmable-custody.md), [TEE](./tee.md), and [Real-Time Proving](./rtp.md), and does not depend on the network below having shipped.
+
+:::
+
+As a network, t1 is a TEE-enabled cross-chain application infrastructure that leverages defense-in-depth to achieve real-time proving. In the  near term (v1), we're building towards achieving RTP with TEE proofs. In the long term, t1 will become a permissionless and decentralized network that will complement TEE proofs with crypto-economic security and bespoke zero-knowledge proofs. You can read more about our long term architecture in our [litepaper](https://docs.t1protocol.com/intro/resources).
 
 ### Network Architecture v1