okrame · okrame · Mar 20, 2026 · Mar 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -30,7 +30,7 @@ ignition/deployments/chain-84532
 *apps/notes/
 .claudeignore
 *.claude/
-CLAUDE.md
+*.md
 *myplans
 .vercel/
 /tests/scan-engine.test.ts

diff --git a/apps/docs/docs/how-it-works/protocol-flow.md b/apps/docs/docs/how-it-works/protocol-flow.md
@@ -1,9 +1,9 @@
 ---
 sidebar_position: 2
-title: Protocol Flow
+title: Protocol Flow (wip)
 ---
 
-# Protocol Flow (WIP...)
+# Protocol Flow (PAGE WIP...)
 
 This page details the full handshake exchange — the sequence of on-chain events, cryptographic operations, and key derivations that establish an encrypted channel. For the conceptual overview, see [Handshake](../concepts/handshake.md).
 

diff --git a/apps/docs/docs/how-it-works/ratchet-internals.md b/apps/docs/docs/how-it-works/ratchet-internals.md
@@ -1,9 +1,9 @@
 ---
 sidebar_position: 3
-title: Ratchet Internals
+title: Ratchet Internals (wip)
 ---
 
-# Ratchet Internals (WIP...)
+# Ratchet Internals (PAGE WIP...)
 
 Implementation details of the Double Ratchet. For the conceptual overview, see [Double Ratchet](../concepts/ratchet/double-ratchet.md).
 

diff --git a/apps/docs/docs/how-it-works/wire-format.md b/apps/docs/docs/how-it-works/wire-format.md
@@ -1,9 +1,9 @@
 ---
 sidebar_position: 1
-title: Wire Format
+title: Wire Format (wip)
 ---
 
-# Wire Format (WIP...)
+# Wire Format (PAGE WIP...)
 
 This page describes how ratchet messages are packed into bytes for on-chain submission, and how recipients process them.
 

diff --git a/apps/docs/docs/overview.md b/apps/docs/docs/overview.md
@@ -15,49 +15,42 @@ The premise is simple. If messaging infrastructure depends on someone’s goodwi
 
 ## Why it exists
 
-Most encrypted messaging systems solve the "cryptography problem" well. What they leave intact is the *trust* problem: a server stores your messages, a company controls the keys to that server, and a jurisdiction controls the company. Even unbreakable encryption can be switched off if someone can shut down the server it runs on.
+Most encrypted messaging systems solve the "cryptography problem" well, but what they leave intact is the trust problem. This can be declined as a server storing your messages, a company controlling the keys to that server and/or a jurisdiction controlling the company. In other words, we know that even unbreakable encryption can be switched off if someone can shut down the server it runs on.
 
 To nail down the point one can read the [Trustless Manifesto](https://trustlessness.eth.limo/general/2025/11/11/the-trustless-manifesto.html) framing
 
 > "The only defense is trustless design: systems whose correctness and fairness depend only on math and consensus, never on the goodwill of intermediaries."
 
 So, what if clients query event logs from a single immutable contract?
 
-Of course, average users still depend on RPC providers to read the chain, and on bundlers or paymasters if using account abstraction for gas sponsorship. The protocol itself, however, owns none of that infrastructure and it only requires that *some* path to Ethereum exists, and any provider is replaceable by another (see [metadata privacy](./concepts/security/metadata-privacy.md) for the RPC-level privacy implications).
+Of course, average users still depend on RPC providers to read the chain, and on bundlers or paymasters if using account abstraction for gas sponsorship. The protocol itself, however, only requires that *some* path to Ethereum exists, and any provider is replaceable by another. A curious RPC provider or indexer that observes who fetches which events is currently a concern, though importantly, metadata privacy is still preserved from external observers on-chain (see [Metadata Privacy](concepts/security/metadata-privacy.md)). The practical answer for the retrieval layer today is running your own blockchain node, and we're actively working on private retrieval techniques that would make even that unnecessary.
 
 ## The walk-away test
 
 Vitalik Buterin proposed a simple litmus test for decentralized systems:
 
 > "If your team and servers disappeared tomorrow, would your application still be usable?"
 
-Verbeth is designed toward passing this test. The reader of these docs can decide herself if this truly the case.
+Verbeth is designed toward passing this test. The reader of these docs can decide herself if this in fact the case.
 
-> To get all the nice [cryptographic guarantees](concepts/security/cryptographic-guarantees.md), ratchet sessions, pending messages, and contact metadata live in app-managed storage via [`SessionStore`](how-it-works/wire-format.md) and [`PendingStore`](how-it-works/wire-format.md) interfaces that each application implements. If an app disappears without exporting that state, the on-chain ciphertext is preserved but users lose the keys to decrypt it. This is an explicit design choice: the protocol does not prescribe *where* you store your state, only that you must store it. 
+> To get all the nice [cryptographic guarantees](concepts/security/cryptographic-guarantees.md), ratchet sessions, pending messages, and contact metadata live in app-managed storage via [`SessionStore`](how-it-works/wire-format.md) and [`PendingStore`](how-it-works/wire-format.md) interfaces that each application implements. If an app disappears without exporting that state, the on-chain ciphertext is preserved but users lose the keys to decrypt it. This is because the protocol does not prescribe where you store your state, only that you must store it. 
 
-A companion question matters just as much. If the original team wanted to interfere, could they stop the system from working or selectively prevent people from using it?  
-The answer is left to the reader here too. 
+A companion question matters just as much: "If the original team wanted to interfere, could they stop the system from working or selectively prevent people from using it?"   
+Again, the answer is left to the readers. Suffice to say that Verbeth bets everything on [full-stack openness](https://vitalik.eth.limo/general/2025/09/24/openness_and_verifiability.html).
 
 ## Own your messages
 
 Shane Mac, co-founder of XMTP Labs, put it well:
 
-> "Private servers require 'trust me' — but having no private server means 'you don't have to trust me.'"
+> "Private servers require 'trust me', but having no private server means 'you don't have to trust me.'"
 >
 > — [Privacy Trends for 2026, a16z crypto](https://a16zcrypto.com/posts/article/privacy-trends-moats-quantum-data-testing/)
 
-Verbeth takes this further: your messages live on a public blockchain, encrypted, forever. They are not hosted *for* you by a service that can revoke access. They are *yours* in the same way your ETH is yours — anyone can verify they exist, but only you hold the keys.
+In Verbeth, messages live on a public blockchain, forever encrypted, so they are not hosted for you by a service that can revoke access. They are yours in the same way your ETH is yours.
 
-This means persistence is an app-level decision, not a protocol-level lock-in. An application built on Verbeth might store decrypted messages locally, back up encrypted session state to IPFS, or sync across devices via a user-controlled cloud. The protocol doesn't mandate a storage backend — it ensures that *no single app is the gatekeeper*. If one client shuts down, another can pick up where it left off, provided the user has their session state.
+An application built on Verbeth might store decrypted messages locally, back up encrypted session state to IPFS, or sync across devices via a user-controlled cloud. The protocol doesn't mandate a storage backend, so if one client shuts down, another can pick up where it left off, provided the user has their session state.
 
-Vitalik's case for [full-stack openness](https://vitalik.eth.limo/general/2025/09/24/openness_and_verifiability.html) reinforces this: genuine openness means equality of access, verifiability, and no vendor lock-in. In Verbeth, every layer is inspectable — from the Solidity contract to the TypeScript SDK to the on-chain ciphertext itself.
 
-## What Verbeth does NOT do
-
-- **Deniability** — on-chain transactions are permanent and attributable. There is no way to deny having sent a message. This is a feature for some use cases and a limitation for others (see [Threat Model](./concepts/security/threat-model.md#non-repudiation)).
-- **Metadata privacy from RPC providers** — without self-hosting or future private retrieval techniques, query patterns are visible to your RPC provider (see [Metadata Privacy](./concepts/security/metadata-privacy.md)).
-- **Active quantum post-compromise security** — an adversary with both a quantum computer *and* device access can track keys through classical DH ratchet steps (see [Cryptographic Guarantees](./concepts/security/cryptographic-guarantees.md#against-quantum-adversary)).
-- **Spam filtering** — Ethereum's gas model provides economic resistance, but the protocol does not filter content.
 
 ## Protocol stack
 
@@ -80,22 +73,4 @@ Vitalik's case for [full-stack openness](https://vitalik.eth.limo/general/2025/0
 └─────────────────────────────────────┘
 ```
 
-**Application** — your client. Manages UI, message display, and local persistence via `SessionStore` / `PendingStore`.
-
-**VerbethClient** — the high-level SDK entry point. Orchestrates handshakes, encrypts and decrypts messages, manages ratchet state. Works with EOAs directly and supports [Safe accounts](https://safe.global) for session keys, gas sponsorship, and multi-sig recovery via `SafeSessionSigner`.
-
-**@verbeth/sdk** — core cryptographic modules: [identity binding](./concepts/identity.md), [hybrid handshake](./concepts/handshake.md) (X25519 + ML-KEM-768), and the [Double Ratchet](./concepts/ratchet/double-ratchet.md) with [topic ratcheting](./concepts/ratchet/topic-ratcheting.md).
-
-**VerbethV1 Contract** — a single immutable contract on Base that emits `Handshake`, `HandshakeResponse`, and `MessageSent` events. Nothing more.
-
-**Ethereum** — the transport and persistence layer. Event logs are immutable, globally available, and censorship-resistant.
-
-## When to use Verbeth
-
-**When non-repudiation matters**: audit trails, regulated workflows, legal agreements, on-chain governance, or any context where *who said what, and when* must be publicly and permanently verifiable — and where that is a feature, not a liability.
-
-**When you need messaging without trust assumptions**: coordination between DAOs, cross-org communication, whistleblowing channels where the medium itself must be beyond any party's control.
-
-**When durability matters more than ephemerality**: Verbeth messages cannot be deleted. 
 
-For protocol details, see the [Handshake](./concepts/handshake.md) and [Double Ratchet](./concepts/ratchet/double-ratchet.md) concepts, or the [Protocol Flow](./how-it-works/protocol-flow.md) for the full on-chain sequence.
diff --git a/apps/docs/docs/roadmap/metadata-privacy-psi.md b/apps/docs/docs/roadmap/metadata-privacy-psi.md
@@ -1,12 +1,12 @@
 ---
 sidebar_position: 1
-title: Private Set Intersection for Topic Queries
+title: Private Append-Only Mailbox Sync (wip) 
 ---
 
-# Private Set Intersection for Topic Queries
+# Private Append-Only Mailbox Sync
 
 :::note Planned feature
-This page describes a planned extension that is not yet implemented. The design is stable enough to document; the implementation timeline is not fixed.
+This page describes a planned extension that is not yet implemented.
 :::
 
 ## Problem
@@ -18,12 +18,3 @@ When a client calls `eth_getLogs` to fetch messages, the RPC provider learns:
 - IP address (unless routed through Tor/VPN)
 
 Even though topic hashes are not directly reversible to identities, a malicious or compromised provider can correlate query patterns with message emission timing to probabilistically link senders and recipients.
-
-## Labeled APSI
-
-work in progres...
-
-## References
-
-- [Microsoft APSI library](https://github.com/microsoft/APSI)
-- [Labeled PSI paper — Chen et al. 2021](https://eprint.iacr.org/2021/1116)