@meddleware/docs 0.0.1

package/docs/access-gate/api/interfaces/OwnedObjectsClient.md

@@ -0,0 +1,49 @@
+# Interface: OwnedObjectsClient
+
+Defined in: types.ts:111
+
+Minimal structural subset of a core Sui client used for owned-object listing (`SuiGrpcClient`).
+
+## Properties
+
+### core
+
+> **core**: `object`
+
+Defined in: types.ts:112
+
+#### listOwnedObjects()
+
+> **listOwnedObjects**(`options`): `Promise`\<\{ `cursor`: `string`; `hasNextPage`: `boolean`; `objects`: `CoreObject`[]; \}\>
+
+##### Parameters
+
+###### options
+
+###### cursor?
+
+`string`
+
+###### include?
+
+\{ `json?`: `boolean`; \}
+
+###### include.json?
+
+`boolean`
+
+###### limit?
+
+`number`
+
+###### owner
+
+`string`
+
+###### type?
+
+`string`
+
+##### Returns
+
+`Promise`\<\{ `cursor`: `string`; `hasNextPage`: `boolean`; `objects`: `CoreObject`[]; \}\>

package/docs/access-gate/api/interfaces/SuiObjectClient.md

@@ -0,0 +1,37 @@
+# Interface: SuiObjectClient
+
+Defined in: types.ts:124
+
+Minimal structural subset of a core Sui client used for a typed single-object read.
+
+## Properties
+
+### core
+
+> **core**: `object`
+
+Defined in: types.ts:125
+
+#### getObject()
+
+> **getObject**(`options`): `Promise`\<\{ `object`: `CoreObject`; \}\>
+
+##### Parameters
+
+###### options
+
+###### include?
+
+\{ `json?`: `boolean`; \}
+
+###### include.json?
+
+`boolean`
+
+###### objectId
+
+`string`
+
+##### Returns
+
+`Promise`\<\{ `object`: `CoreObject`; \}\>

package/docs/access-gate/api/type-aliases/PersonalMessageSigner.md

@@ -0,0 +1,17 @@
+# Type Alias: PersonalMessageSigner
+
+> **PersonalMessageSigner** = (`message`) => `Promise`\<\{ `signature`: `string`; \}\>
+
+Defined in: proof.ts:36
+
+A wallet-provided personal-message signer (e.g. wallet-standard `sui:signPersonalMessage`).
+
+## Parameters
+
+### message
+
+`Uint8Array`
+
+## Returns
+
+`Promise`\<\{ `signature`: `string`; \}\>

package/docs/access-gate/api/typedoc-sidebar.json

@@ -0,0 +1 @@
+[{"text":"Interfaces","collapsed":true,"items":[{"text":"AccessGateConfig","link":"/docs/access-gate/api/interfaces/AccessGateConfig.md"},{"text":"AccessProof","link":"/docs/access-gate/api/interfaces/AccessProof.md"},{"text":"Challenge","link":"/docs/access-gate/api/interfaces/Challenge.md"},{"text":"GateAdminContext","link":"/docs/access-gate/api/interfaces/GateAdminContext.md"},{"text":"OwnedAccessNft","link":"/docs/access-gate/api/interfaces/OwnedAccessNft.md"},{"text":"OwnedGate","link":"/docs/access-gate/api/interfaces/OwnedGate.md"},{"text":"OwnedObjectsClient","link":"/docs/access-gate/api/interfaces/OwnedObjectsClient.md"},{"text":"SuiObjectClient","link":"/docs/access-gate/api/interfaces/SuiObjectClient.md"}]},{"text":"Type Aliases","collapsed":true,"items":[{"text":"PersonalMessageSigner","link":"/docs/access-gate/api/type-aliases/PersonalMessageSigner.md"}]},{"text":"Functions","collapsed":true,"items":[{"text":"buildAccessProof","link":"/docs/access-gate/api/functions/buildAccessProof.md"},{"text":"buildAirdropTx","link":"/docs/access-gate/api/functions/buildAirdropTx.md"},{"text":"buildConsumeTx","link":"/docs/access-gate/api/functions/buildConsumeTx.md"},{"text":"buildCreateGateTx","link":"/docs/access-gate/api/functions/buildCreateGateTx.md"},{"text":"buildMakeGateImmutableTx","link":"/docs/access-gate/api/functions/buildMakeGateImmutableTx.md"},{"text":"buildPurchaseTx","link":"/docs/access-gate/api/functions/buildPurchaseTx.md"},{"text":"buildSetAutoBurnAtZeroTx","link":"/docs/access-gate/api/functions/buildSetAutoBurnAtZeroTx.md"},{"text":"buildSetDefaultUsesTx","link":"/docs/access-gate/api/functions/buildSetDefaultUsesTx.md"},{"text":"buildSetNftDescriptionTx","link":"/docs/access-gate/api/functions/buildSetNftDescriptionTx.md"},{"text":"buildSetNftImageUrlTx","link":"/docs/access-gate/api/functions/buildSetNftImageUrlTx.md"},{"text":"buildSetNftNameTx","link":"/docs/access-gate/api/functions/buildSetNftNameTx.md"},{"text":"buildSetPausedTx","link":"/docs/access-gate/api/functions/buildSetPausedTx.md"},{"text":"buildSetPaymentRecipientTx","link":"/docs/access-gate/api/functions/buildSetPaymentRecipientTx.md"},{"text":"buildSetPriceTx","link":"/docs/access-gate/api/functions/buildSetPriceTx.md"},{"text":"buildSetSoulboundTx","link":"/docs/access-gate/api/functions/buildSetSoulboundTx.md"},{"text":"decodeAccessProof","link":"/docs/access-gate/api/functions/decodeAccessProof.md"},{"text":"encodeAccessProof","link":"/docs/access-gate/api/functions/encodeAccessProof.md"},{"text":"fetchAccessNftById","link":"/docs/access-gate/api/functions/fetchAccessNftById.md"},{"text":"fetchAccessNfts","link":"/docs/access-gate/api/functions/fetchAccessNfts.md"},{"text":"fetchAdminCaps","link":"/docs/access-gate/api/functions/fetchAdminCaps.md"},{"text":"fetchChallenge","link":"/docs/access-gate/api/functions/fetchChallenge.md"},{"text":"fetchGate","link":"/docs/access-gate/api/functions/fetchGate.md"},{"text":"fetchOwnedGates","link":"/docs/access-gate/api/functions/fetchOwnedGates.md"},{"text":"ownsAccessNft","link":"/docs/access-gate/api/functions/ownsAccessNft.md"},{"text":"parseAdminCap","link":"/docs/access-gate/api/functions/parseAdminCap.md"},{"text":"parseGate","link":"/docs/access-gate/api/functions/parseGate.md"},{"text":"parseOwnedAccessNft","link":"/docs/access-gate/api/functions/parseOwnedAccessNft.md"},{"text":"personalMessageForNonce","link":"/docs/access-gate/api/functions/personalMessageForNonce.md"}]}]

package/docs/access-gate/index.md

@@ -0,0 +1,61 @@
+# Access Gate
+
+Create NFT **passes** that gate access to something — content, an API, an app, a download — with
+ownership verified on-chain. Operators manage gates at
+[sui-access-gate.meddleware.co.uk](https://sui-access-gate.meddleware.co.uk).
+
+## What it is
+
+An **access gate** is an on-chain object with a price and rules. Anyone can **purchase** a pass
+(an NFT) from it; holding a valid pass is the proof of access. Passes can be **unlimited** (a
+membership) or **single-use** (spent once), and optionally **soulbound** (non-transferable).
+
+There are two perspectives:
+
+- **Operators** create and manage gates (set the price, airdrop passes, pause, freeze).
+- **Buyers/holders** purchase a pass and use it to access whatever the gate protects.
+
+## When to use it
+
+- You want to **sell access** — a paid community, premium content, a members' area.
+- You want to **gate an API or app** behind on-chain ownership (pair it with the
+  [nft-gate gateway](/access-gate/reference), which puts any HTTP service behind a gate).
+- You want to gate **encrypted content** — combine it with [Sealed Storage](/sealed-storage/), where
+  a pass becomes the key.
+- You want **single-use tickets** or **memberships** represented as NFTs.
+
+## How a purchase works
+
+1. A buyer calls **purchase** on the gate and pays the price.
+2. The payment is split on-chain: a **commission** goes to the platform treasury, the rest to the
+   gate's **operator** — atomically, in one transaction. Overpayment is refunded.
+3. The buyer receives the pass NFT.
+
+No operator co-signature is needed — purchase is permissionless and atomic.
+
+## Single-use vs unlimited
+
+- **Unlimited pass** — acts as ongoing membership; using it doesn't consume it.
+- **Single-use** — carries a number of uses; **consuming** one is done on-chain by the owner and
+  emits a verifiable event (with a **nonce**) that a verifier binds to. Off-chain systems can't spend
+  a pass on your behalf.
+
+When a single-use pass hits zero, the gate's policy decides: auto-burn it, or return it as a spent
+receipt.
+
+## Soulbound passes
+
+A gate can mint **soulbound** (non-transferable) passes — useful when access should be tied to one
+identity and not resold. The non-transferability is enforced at the contract level.
+
+## Commission
+
+Every purchase routes a commission (in basis points, capped on-chain at 10%) to the platform
+treasury; the rest goes to the operator. The rate is set in shared on-chain config and shown in the
+[DAO console](/dao/). Operators don't set the commission — only the price.
+
+## Next
+
+- **[Using it](/access-gate/using)** — create and manage a gate; buy and use a pass.
+- **[Reference](/access-gate/reference)** — objects, entry functions, events, the gateway, and the
+  SDK API.

package/docs/access-gate/reference.md

@@ -0,0 +1,111 @@
+# Access Gate — reference
+
+The on-chain `access_gate` contract, its gateway, and the client SDK. Move tables are curated from
+source; the TypeScript SDK reference is [auto-generated](#sdk-api).
+
+## Deployed identifiers (testnet)
+
+| Thing | ID |
+| --- | --- |
+| `access_gate` package | `0x0bedd0b27d993d3292ca6a5315f7562de8bc0ff3752b445b4c53252c76f2d20d` |
+| `PlatformConfig` object | `0x7c5aed0ce7f29a4dfb60657858df31c12410a67098b4bcdd1d8cb1e531be4884` |
+
+Mainnet identifiers are pending.
+
+## Objects
+
+### `Gate` (shared)
+
+```
+Gate {
+  price_mist         // pass price in MIST
+  payment_recipient  // operator address that receives the post-commission amount
+  default_uses       // 0 ⇒ unlimited pass; N ⇒ single-use with N uses
+  soulbound          // whether minted passes are non-transferable
+  auto_burn_at_zero  // spent single-use pass: delete (true) or return as receipt (false)
+  paused             // purchases blocked while true
+  admin_cap_id       // the AdminCap authorised to manage this gate
+}
+```
+
+### Passes
+
+- **`AccessNFT`** (has `store`) — a transferable pass.
+- **`SoulboundAccessNFT`** (no `store`) — non-transferable; only the contract's `consume`/`burn` can
+  destroy it.
+
+Both wrap **`AccessData`** `{ gate_id, variant, minted_epoch }`, where **`AccessVariant`** is
+`UnlimitedPass` or `SingleUse { uses_remaining }`.
+
+### `AdminCap`
+
+Owned capability authorising management of one gate (`{ gate_id }`). Authorisation is by
+`cap.gate_id == object::id(gate)`.
+
+## Entry functions
+
+| Function | Who | Effect |
+| --- | --- | --- |
+| `create_gate` | anyone | Create a gate; mints an `AdminCap` to the creator. |
+| `purchase` | anyone | Pay `price_mist`; commission → treasury, remainder → `payment_recipient`; mint pass; refund overpayment. |
+| `consume` | pass owner | Spend one use of a single-use pass; emits `AccessConsumedEvent { nonce }`. |
+| `airdrop` | AdminCap | Grant a pass to an address without payment. |
+| `burn` | pass owner | Voluntarily destroy a pass; emits `AccessBurnedEvent`. |
+| admin setters | AdminCap | Update price / recipient / paused / etc. |
+| `make_gate_immutable` | AdminCap | **Irreversible** — consumes the AdminCap; ends settings + airdrops. |
+| `set_platform_treasury`, `set_commission_bps` | platform admin | Platform-only; not exposed in the operator console. |
+
+## Events
+
+| Event | Emitted when | Key fields |
+| --- | --- | --- |
+| `GateCreatedEvent` | a gate is created | gate config |
+| `AccessMintedEvent` | a pass is purchased/airdropped | recipient, gate |
+| `AccessConsumedEvent` | a single-use pass is spent | **`nonce`**, address |
+| `AccessBurnedEvent` | a pass is burned | id |
+
+::: warning Event pruning
+Sui testnet prunes old events after ~3 months. Systems that need a reliable gate list should read
+**`AdminCap` ownership → `Gate`** rather than replaying `GateCreatedEvent` (this is what the
+[DAO console](/dao/) does).
+:::
+
+## Error codes
+
+| Code | Constant | Meaning |
+| --- | --- | --- |
+| 1 | `E_PAUSED` | Gate is paused |
+| 2 | `E_INSUFFICIENT_PAYMENT` | Payment below price |
+| 3 | `E_NOT_SINGLE_USE` | Consume called on an unlimited pass |
+| 4 | `E_NO_USES_REMAINING` | Single-use pass already exhausted |
+| 5 | `E_WRONG_GATE` | NFT/cap doesn't belong to the supplied gate |
+
+## Gateway (nft-gate)
+
+Any HTTP service can be placed **behind** a gate using the nft-gate reverse proxy. It verifies a
+signed proof and on-chain pass ownership, failing **closed** on any ambiguity.
+
+- **Personal message signed by the wallet:** `nft-gate:access:<nonce>`
+- **Proof token** (`Authorization: Bearer …` or `X-Access-Proof`): base64 of
+
+```json
+{ "address": "0x…", "nonce": "…", "signature": "…", "consumeDigest": "…" }
+```
+
+The gateway consumes the nonce immediately (single-use replay protection) and, for single-use passes,
+verifies the on-chain consumption by digest. Two wire-identical implementations exist (Cloudflare
+Workers and Rust); running one is a [self-host / `dev.`](#developer-note) topic.
+
+## SDK API
+
+The full `@meddleware/nft-gate-client` API — PTB builders (`create_gate`, `purchase`, `consume`,
+airdrop, admin setters), ownership reads, and the challenge/proof helpers — is generated here:
+
+- [NFT-gate client API](./api/)
+
+## Developer note
+
+Deploying the gateway, integrating the SDK into your own app, and white-label operation are
+`dev.meddleware.co.uk` topics, planned in the `access-gate-sui`, `nft-gate`, and `nft-gate-client`
+package docs. This page is the on-chain contract and wire-protocol reference users and bots can rely
+on.

package/docs/access-gate/using.md

@@ -0,0 +1,68 @@
+# Access Gate — using it
+
+Two audiences: **operators** who run gates, and **buyers** who hold passes.
+
+## For operators
+
+Manage gates in the [operator console](https://sui-access-gate.meddleware.co.uk). You'll need a
+[Sui wallet](/getting-started).
+
+### Create a gate
+
+1. **Connect** your wallet and open **Create gate**.
+2. Set the pass details:
+   - **Name** — shown to buyers and in the DAO console.
+   - **Price** (in SUI) — what a buyer pays.
+   - **Uses** — `0` for an unlimited membership pass, or `N` for single-use with N uses.
+   - **Soulbound** — whether passes are non-transferable.
+   - **Auto-burn at zero** — for single-use, whether a spent pass is deleted or kept as a receipt.
+3. Confirm. Creating the gate gives your wallet an **admin capability** (`AdminCap`) for it.
+
+### Manage a gate
+
+Under **My gates**, each gate you administer offers:
+
+- **Settings** — update price and metadata (via the AdminCap).
+- **Pause** — temporarily stop purchases.
+- **Airdrop** — grant passes directly to addresses (no payment).
+- **Freeze** — see below.
+
+### Freeze (irreversible)
+
+::: warning Freezing is permanent
+**Freeze** makes a gate immutable: it consumes the AdminCap and permanently ends all settings and
+airdrops. Purchases and consumption keep working. The console guards this behind a typed **FREEZE**
+confirmation. There is no undo.
+:::
+
+## For buyers / holders
+
+### Buy a pass
+
+Purchase from the gate (through whatever surface the operator exposes — the console, a link, or an
+app integrating the gate). You pay the price; the commission and operator split happen on-chain; you
+receive the pass NFT. Overpayment is refunded automatically.
+
+### Use a pass
+
+- For **access checks** (e.g. a gated relay or API), your wallet signs a short challenge and the
+  service verifies you hold a valid pass on-chain.
+- For **single-use** passes, **consuming** a use is an on-chain action you take as the owner; it emits
+  a verifiable event that the service binds to. This is why an off-chain service can't silently spend
+  your pass.
+
+### Use a pass to unlock encrypted content
+
+If content was sealed to a gate with [Sealed Storage](/sealed-storage/), holding a valid pass lets you
+**decrypt** it — provide your pass when unlocking.
+
+## Common questions
+
+**Who receives my payment?** Split on-chain: a capped commission to the platform treasury, the rest
+to the operator.
+
+**Can the operator take my pass back?** No — it's your NFT. (A soulbound pass can't be transferred by
+anyone, including you.)
+
+**What's a nonce for?** When you consume a single-use pass, the emitted **nonce** lets a verifier
+confirm *that specific* consumption, rather than trusting a bare address.

package/docs/architecture.md

@@ -0,0 +1,61 @@
+# How the tools fit together
+
+The four tools are useful on their own, but they're designed to compose. This page shows how.
+
+## The building blocks
+
+| Tool | Provides | Depends on |
+| --- | --- | --- |
+| **Access Gate** | NFT passes that prove someone is allowed access | Sui only |
+| **Walrus Storage** | Decentralised file (blob) storage | Sui + Walrus |
+| **Sealed Storage** | Client-side encryption with on-chain access rules | Walrus + Seal + (optionally) Access Gate |
+| **DAO** | A read-only view of the platform: treasury, commission, gates | Access Gate on-chain state |
+
+## Sealed Storage = Walrus + Seal + Access Gate
+
+The clearest example of composition is **[Sealed Storage](/sealed-storage/)**. When you seal a file:
+
+1. **Seal** encrypts it in your browser, under a **policy** you choose.
+2. **Walrus** stores the resulting ciphertext — publicly, because it's useless without the key.
+3. The **policy** decides who can decrypt. One built-in policy is **Access Gate NFT ownership**: only
+   holders of a valid pass for a chosen gate can unlock the content.
+
+So an Access Gate pass can act as the key to encrypted Walrus content — three tools, one flow.
+
+```
+        ┌─────────────┐   encrypt in browser    ┌──────────────┐
+  file  │    Seal     │ ───────────────────────▶│  ciphertext  │
+        └─────────────┘                          └──────┬───────┘
+               ▲                                         │ store
+        policy │ (who may decrypt)                       ▼
+        ┌──────┴───────┐                          ┌──────────────┐
+        │ Access Gate  │  ← pass holders only     │    Walrus    │
+        │  (NFT pass)  │                          │   storage    │
+        └──────────────┘                          └──────────────┘
+```
+
+## How gated Walrus uploads work
+
+**[Walrus Storage](/walrus-storage/)** can route uploads through a **relay**. Meddleware's relay can
+be **gated** by an Access Gate NFT: you prove you hold a valid pass, and the relay accepts your
+upload. A commission on gate purchases funds the service. If you don't need the gated relay, uploads
+fall back to the public relay.
+
+## Where the DAO fits
+
+The **[DAO console](/dao/)** doesn't create anything — it *observes*. It reads the platform's
+on-chain configuration: the treasury address, the **commission rate** charged on Access Gate
+purchases, the community gates the treasury controls, and a live feed of gate activity (passes sold,
+used, burned). It's the transparency window over the Access Gate economics.
+
+## The commission thread
+
+One number ties the economics together: the **commission** (in basis points) charged on-chain when an
+Access Gate pass is purchased. It's set in a shared `PlatformConfig` object, capped on-chain, routed
+to the treasury, and shown in the DAO console. The web apps can't change it — only an on-chain admin
+capability can. This is the pattern throughout: **economics live in the smart contracts.**
+
+## Next
+
+- [DAO](/dao/) · [Walrus Storage](/walrus-storage/) · [Sealed Storage](/sealed-storage/) ·
+  [Access Gate](/access-gate/)

package/docs/dao/index.md

@@ -0,0 +1,71 @@
+# DAO
+
+The **DAO console** is a read-only window onto the Meddleware platform's on-chain state. Open it at
+[sui-dao.meddleware.co.uk](https://sui-dao.meddleware.co.uk) (it's also the default view in the
+[tools hub](https://sui.meddleware.co.uk)).
+
+## What it is
+
+A dashboard that reads directly from Sui and shows:
+
+- the platform **treasury** balance and address,
+- the **commission rate** charged on Access Gate purchases,
+- the **community gates** the treasury controls,
+- a live feed of **gate activity** (passes sold, used, burned).
+
+You do **not** need to connect a wallet to browse it — everything shown is public on-chain data.
+
+## When to use it
+
+- You want to **verify** the platform's commission rate or treasury address.
+- You want to see **how many gates** exist and their prices.
+- You're tracking **activity** — how many passes have been sold or used.
+- You hold a platform admin capability and want to confirm the tool **detects** it (see
+  [Governance](#governance)).
+
+If you want to *create* a gate, that's the [Access Gate](/access-gate/) tool, not this one.
+
+## The tabs
+
+### Overview
+
+At-a-glance: treasury balance, commission rate, counters for active gates and accesses
+minted/consumed, and a recent-activity feed.
+
+### Treasury
+
+The commission rate (shown both as a percentage and in **basis points**), the treasury's live SUI
+balance, and its address, plus a table of **Community Gates** the treasury controls — each with its
+name, price, and object ID (linked to a Sui explorer).
+
+### Proposals
+
+Reserved for on-chain governance proposals. This is a **placeholder** today — the governance module
+isn't deployed yet, so the tab shows an empty state. It will list fundraising/governance proposals
+when that module ships.
+
+### Governance
+
+Shows the platform parameters (commission rate, the **10% / 1000 bps hard cap** enforced on-chain,
+treasury address) and an **Admin Actions** panel. If you connect a wallet that holds a
+`PlatformAdminCap`, the console detects it; admin controls will appear here as they're implemented.
+Wallets without the capability simply see that privileged actions aren't available.
+
+### History
+
+A paginated log of on-chain gate events — **Access Sold**, **Access Used**, **Access Burned** — each
+with the associated address and transaction, linked to a Sui explorer.
+
+## How "active gates" is counted
+
+The console finds gates by looking up the **admin capabilities** the treasury owns, then resolving the
+gate each one controls — rather than replaying historical events. This matters because Sui testnet
+**prunes** old events after a few months, which would otherwise make a naive event-based count read
+as zero. The capability-based approach always reflects live reality. (The technical details are in
+[Reference](/dao/reference).)
+
+## Commission, in one line
+
+When someone buys an Access Gate pass, a share of the price — `commission_bps / 10000` — goes to the
+treasury and the rest to the gate's operator. The rate is read live from on-chain config and is
+capped at 10%.

package/docs/dao/reference.md

@@ -0,0 +1,94 @@
+# DAO — reference
+
+Shapes and identifiers the DAO console reads. These are **on-chain** objects and events from the
+`access_gate` package; the console only displays them.
+
+## Deployed identifiers (testnet)
+
+| Thing | ID |
+| --- | --- |
+| `access_gate` package | `0x0bedd0b27d993d3292ca6a5315f7562de8bc0ff3752b445b4c53252c76f2d20d` |
+| `PlatformConfig` object | `0x7c5aed0ce7f29a4dfb60657858df31c12410a67098b4bcdd1d8cb1e531be4884` |
+
+Mainnet identifiers are pending. The console reads these from its build-time configuration; on a
+Sui explorer you can inspect them directly.
+
+## `PlatformConfig`
+
+The shared object holding platform-wide settings.
+
+```json
+{
+  "treasury": "0x…",        // address that receives commission
+  "commission_bps": 20       // commission in basis points (20 = 0.20%)
+}
+```
+
+The console derives the commission percentage as `commission_bps / 100` and enforces awareness of the
+on-chain hard cap of **1000 bps (10%)**.
+
+## `Gate`
+
+A shared object representing one access class. The console surfaces a subset of its fields:
+
+```json
+{
+  "nft_name": "My Community Pass",
+  "price_mist": "1000000000",   // price in MIST (1 SUI = 1e9 MIST)
+  "paused": false,
+  "frozen": false,
+  "admin_cap_id": "0x…"          // the AdminCap authorised to manage this gate
+}
+```
+
+## `AdminCap`
+
+The owned capability that authorises managing a gate. Gate discovery walks the treasury's `AdminCap`
+objects and resolves each gate:
+
+```json
+{
+  "gate_id": "0x…"   // the Gate this cap administers
+}
+```
+
+**Why capability-based discovery?** Sui testnet fullnodes prune old events (including the one-time
+`GateCreatedEvent`) after ~3 months, so counting gates from events under-reports. Reading
+`treasury → AdminCap objects → Gate` always reflects live on-chain reality.
+
+## Events
+
+The History tab and activity counters read these event types (emitted by `access_gate`):
+
+| Event | Meaning | Key fields |
+| --- | --- | --- |
+| `AccessMintedEvent` | A pass was purchased/minted | recipient, gate |
+| `AccessConsumedEvent` | A single-use pass was spent | `nonce`, address |
+| `AccessBurnedEvent` | A pass was burned | id |
+
+Example (as decoded JSON):
+
+```json
+{
+  "type": "AccessConsumedEvent",
+  "recipient": "0x…",
+  "nonce": "…",
+  "txDigest": "…",
+  "checkpoint": "12345678"
+}
+```
+
+The console queries each event type independently and merges them, sorted by checkpoint
+(newest first), tolerating any single type being pruned or unavailable.
+
+## Roadmap: `vault_dao`
+
+The **Proposals** and **Governance actions** are placeholders pending an on-chain `vault_dao` module.
+When it ships, proposals will be read from its registry; the console's display shapes are already
+stable so wiring it in won't change the UI.
+
+::: tip Developer note
+Full SDK/contract API reference (entry functions, exhaustive event schemas) is being consolidated for
+`dev.meddleware.co.uk`. The [Access Gate reference](/access-gate/reference) already lists the gate
+contract's entry points and events, which is the on-chain source these DAO views read.
+:::

package/docs/getting-started.md

@@ -0,0 +1,59 @@
+# Getting started
+
+Everything here runs on [Sui](https://sui.io). You interact with each tool through its hosted web app
+using a **Sui wallet**. This page covers the basics that apply to all of them.
+
+## 1. Get a Sui wallet
+
+Install a Sui wallet browser extension (for example [Slush](https://slush.app/), the official Sui
+wallet, or any wallet that supports the Sui wallet standard). Create or import an account and keep
+your recovery phrase safe — no one at Meddleware can recover it for you.
+
+## 2. Choose a network: testnet vs mainnet
+
+Sui has separate networks:
+
+- **Testnet** — a free sandbox using **test** SUI with no real value. Best for trying things out. The
+  Meddleware tools currently run against **testnet**.
+- **Mainnet** — the real network, where SUI has value. Some tools are mainnet-pending; each app shows
+  its current network in the header.
+
+Make sure your wallet is set to the **same network** as the app you're using. On testnet you can get
+free test SUI from the [Sui faucet](https://faucet.sui.io/).
+
+::: tip You need a little SUI for gas
+Every on-chain action (a purchase, an upload registration, extending a blob) costs a small **gas**
+fee in SUI. On testnet this is free from the faucet; on mainnet it's real but typically tiny.
+:::
+
+## 3. Open a tool and connect
+
+Each tool has its own subdomain, and they're all linked from the **tools hub**:
+
+| Tool | App |
+| --- | --- |
+| Tools hub | [sui.meddleware.co.uk](https://sui.meddleware.co.uk) |
+| DAO console | [sui-dao.meddleware.co.uk](https://sui-dao.meddleware.co.uk) |
+| Walrus Storage | [sui-walrus.meddleware.co.uk](https://sui-walrus.meddleware.co.uk) |
+| Sealed Storage | [sui-seal.meddleware.co.uk](https://sui-seal.meddleware.co.uk) |
+| Access Gate | [sui-access-gate.meddleware.co.uk](https://sui-access-gate.meddleware.co.uk) |
+
+Click **Connect** and approve the connection in your wallet. The tools hub shares one wallet
+connection across every tool embedded in it.
+
+- **Browsing** the [DAO console](/dao/) needs **no wallet** — it's read-only.
+- **Uploading, encrypting, buying, or managing** needs a connected wallet to sign transactions.
+
+## 4. Understand what's on-chain
+
+A recurring theme across these tools: **the blockchain is the source of truth.** Prices, ownership,
+commission, and access rules are enforced by Sui smart contracts, not by the web app. The apps are
+thin front-ends — they show you state and help you build transactions, but they can't override what
+the chain says. Anything an app displays can be independently verified on a
+[Sui explorer](https://suiscan.xyz).
+
+## Next steps
+
+- **[How the tools fit together](/architecture)** — the big picture.
+- Jump into a tool: [DAO](/dao/) · [Walrus Storage](/walrus-storage/) ·
+  [Sealed Storage](/sealed-storage/) · [Access Gate](/access-gate/).