sui.ski 0.1.0

package/AGENTS.md

@@ -0,0 +1,311 @@
+# Agent Guidelines for Sui-ski Gateway
+
+## Thunder-First Development
+
+Every feature touches Thunder. The `#primary` channel is the source of truth for a user's on-chain activity through the gateway. If you're building a new action (registration, swap, transfer, etc.), it MUST emit a Thunder message.
+
+**Core principle:** The WebMCP format ensures all messages are machine-readable. AI agents can parse the `#primary` channel to reconstruct a user's complete activity history.
+
+**When building any PTB-producing feature:**
+1. Define the `ThunderAction` for the action (tool name, input fields)
+2. Call `appendThunderMessage()` as the last step in PTB construction
+3. Account for ~0.001 SUI gas overhead from the message call
+4. Handle the no-channel case (first action triggers channel creation instead)
+
+---
+
+## Core Architecture
+
+### Subdomain Routing (`src/utils/subdomain.ts`)
+
+| Pattern | Route | Handler |
+| ------- | ----- | ------- |
+| `sui.ski` | root | Landing page, API routes |
+| `my.sui.ski` | dashboard | User's names management |
+| `rpc.sui.ski` | rpc | Read-only JSON-RPC proxy |
+| `{name}.sui.ski` | suins | SuiNS profile + Thunder feed |
+| `{pkg}--{name}.sui.ski` | mvr | MVR package resolution |
+| `ipfs-{cid}.sui.ski` | content | IPFS gateway |
+| `walrus-{blobId}.sui.ski` | content | Walrus aggregator |
+| `app.sui.ski` | app | Messaging/chat application |
+| `.t.` prefix | testnet | Override to testnet |
+| `.d.` prefix | devnet | Override to devnet |
+
+---
+
+## Wallet Bridge Policy
+
+All wallet interaction on any `*.sui.ski` subdomain MUST be routed through `https://sui.ski/sign` using an invisible iframe bridge.
+
+- Subdomains may perform local wallet discovery only to collect wallet name/icon hints.
+- Subdomains MUST forward those hints to the bridge (`postMessage`) and let the bridge own connect/sign/disconnect.
+- Subdomains MUST NOT directly call extension connect/sign APIs for trad wallets.
+- New wallet flows must keep the bridge path as the only signing authority outside `sui.ski`.
+- **Solution: If a wallet is unavailable in iframe context, use a same-tab top-frame handoff to `https://sui.ski/sign` for connect/sign and then return to the subdomain. Do not use popup fallback.**
+
+---
+
+## Thunder Integration Points
+
+| File | Thunder Role |
+| ---- | ------------ |
+| `src/handlers/ski-sign.ts` | Appends Thunder message to every PTB before signing |
+| `src/handlers/ski.ts` | Triggers `#primary` channel creation on first .SKI |
+| `src/durable-objects/wallet-session.ts` | Stores `channelId` + `memberCapId` in session |
+| `src/handlers/thunder.ts` | Reads `#primary` channel for activity display |
+| `src/handlers/profile.ts` | Renders Thunder activity feed on profile pages |
+| `src/utils/thunder.ts` | **(NEW)** Thunder message builder + PTB composer |
+| `contracts/storm/sources/registry.move` | Storm on-chain canonical channel registry (`SuiNS NFT -> channel`) |
+| `src/handlers/app.ts` | Exposes Storm config at `/api/app/subscriptions/config` |
+| `src/utils/thunder-js.ts` | Reads/writes Storm mapping; enforces primary channel identity |
+
+---
+
+## PTB Composition Checklist
+
+When adding or modifying any PTB that goes through `ski-sign.ts`:
+
+- [ ] Define the `ThunderAction` with correct `tool` name (`sui:` prefix) and `input` fields
+- [ ] Serialize the action to the WebMCP envelope format (`v: 1`, `method: 'tools/call'`)
+- [ ] Encrypt the serialized bytes with the channel's DEK via Seal
+- [ ] Append `channel::send_message()` as the **last** MoveCall in the PTB
+- [ ] Verify the PTB handles the no-channel edge case (first .SKI creates channel instead)
+- [ ] Test that gas budget includes the message overhead (~0.001 SUI)
+- [ ] Confirm atomicity: action + log both succeed or both revert
+
+---
+
+## WebMCP Message Catalog
+
+All known Thunder action types:
+
+| Tool | Trigger | Input Fields |
+| ---- | ------- | ------------ |
+| `sui:ski` | First key-in | `name`, `address` |
+| `sui:register` | SuiNS registration | `name`, `years`, `paymentMethod` |
+| `sui:transfer` | Object transfer | `objectId`, `recipient` |
+| `sui:swap` | DeepBook swap | `fromCoin`, `toCoin`, `amount` |
+| `sui:stake` | Validator staking | `validator`, `amount` |
+| `sui:message` | Direct message send | `channel`, `recipient` |
+
+When adding a new action type: add a row here, implement the `ThunderAction` in `src/utils/thunder.ts`, and wire it into the relevant handler's PTB construction.
+
+---
+
+## Deployment
+
+**CRITICAL: Use `npx wrangler deploy` after every change.**
+
+Do not use `bun run deploy` (fails with auth token errors). Do not consider work complete until deployment succeeds.
+
+```bash
+npx wrangler deploy           # Deploy (MANDATORY after changes)
+bun run dev                   # Local dev server
+bun test                      # Run tests
+bun run typecheck             # Type checking
+bun run lint                  # Biome linter
+```
+
+---
+
+## Code Style
+
+Full standards in `CLAUDE.md`. Key points:
+
+- **No comments** — self-documenting code
+- **No dead code** — git has history
+- **Fail fast** — `invariant(condition, actionable message)`
+- **Parallel async** — `Promise.all` for independent operations
+- **Single-pass** — avoid chained array methods
+- Naming: constants `UPPER_SNAKE`, functions `camelCase`, types `PascalCase`, files `kebab-case`
+- Formatting: tabs, single quotes, no semicolons
+
+---
+
+## Key Files
+
+### Thunder Path (action flow)
+
+| File | Purpose |
+| ---- | ------- |
+| `src/handlers/ski.ts` | .SKI key-in entry point, wallet connection |
+| `src/handlers/ski-sign.ts` | PTB signing bridge, Thunder message injection |
+| `src/handlers/thunder.ts` | Thunder API, MCP bridge, channel/message endpoints |
+| `src/utils/thunder-js.ts` | Thunder chat runtime UI + SDK transaction orchestration |
+| `src/utils/thunder-css.ts` | Thunder UI styling |
+| `src/durable-objects/wallet-session.ts` | Session state: address, channel/member caps, auth |
+
+### Transaction Building
+
+| File | Purpose |
+| ---- | ------- |
+| `src/utils/swap-transactions.ts` | DeepBook swap + SuiNS registration PTBs |
+| `src/utils/transactions.ts` | Shared transaction helpers |
+| `src/utils/ns-price.ts` | NS token pricing via DeepBook pools |
+| `src/utils/pricing.ts` | SuiNS pricing + renewal calculations |
+| `src/utils/grace-vault-transactions.ts` | Grace Vault transaction assembly |
+
+### Messaging + App Surfaces
+
+| File | Purpose |
+| ---- | ------- |
+| `src/handlers/app.ts` | `app.sui.ski` shell + `/api/app/*` config/messaging helpers |
+| `src/handlers/profile.ts` | Profile page rendering + Thunder embed |
+| `src/handlers/messaging-sdk.ts` | Messaging SDK status/config API |
+| `src/sdk/messaging.ts` | Shared SDK constants/config/version pins |
+
+### Resolution Layer
+
+| File | Purpose |
+| ---- | ------- |
+| `src/resolvers/suins.ts` | SuiNS resolution |
+| `src/resolvers/content.ts` | IPFS/Walrus content resolution |
+| `src/resolvers/rpc.ts` | Read-only RPC proxy |
+
+---
+
+## Current Progress Log (2026-02-17)
+
+### Thunder stability and UX
+
+- Done (2026-02-18): Enforced bridge-only wallet interaction on subdomains (`sui.ski/sign` iframe) and added local wallet hint forwarding from subdomains to bridge discovery/connect/sign paths.
+- Done: Robust Sui + messaging SDK module resolution in browser init path.
+- Done: Fixed package-ID mismatch to mainnet messaging package `0xbcdf...39f9` in live runtime/config paths.
+- Done: Added signer result hydration to recover missing transaction effects/object changes.
+- Done: Removed channel-label collapsing that mixed independent channels under one label.
+- Done: Added local cache reset control for channel meta/dismissed keys.
+
+### Hardening completed
+
+- Done: Duplicate-channel prevention at source.
+  - Added on-chain membership guard before any bootstrap/create flow, so existing membership blocks new channel creation.
+  - Removed “dismiss on failed burn” behavior to prevent hidden channels from spawning replacement channels.
+  - Shifted duplicate channels into explicit “extras” management UI, with on-chain cleanup action.
+- Done: Reduced first-message signing path.
+  - Added bootstrap path using `createChannelFlow()` + append `sendMessage()` to key-attach PTB, reducing first send from 3 signatures to 2 when SDK builders are available.
+- Done: Channel-key self-heal for broken legacy channels.
+  - Added on-chain `add_encrypted_key` repair flow as an explicit user action (`Repair key`) when signer has required member capability.
+  - Added send fallback routing to next public channel with a valid encrypted key when active channel is unrecoverable.
+  - Added member-cap permission selection logic so repair uses a cap with `EditEncryptionKey` instead of arbitrary owned caps.
+  - Disabled automatic repair during send to keep one send-click to one transaction attempt.
+- Done: Strict send path (no implicit fallback/switching).
+  - Removed automatic channel switching during send.
+  - Removed “best sendable channel” fallback logic.
+  - Added explicit burn wording and scope for non-primary channels only.
+
+### Storm registry rollout
+
+- Done: Added `contracts/storm` Move package with shared `Registry` dynamic fields keyed by SuiNS NFT object ID.
+  - `set_channel_for_nft<T: key>(registry, nft, channel_id)`
+  - `clear_channel_for_nft<T: key>(registry, nft)`
+- Done: Added worker env wiring for Storm (`STORM_PACKAGE_ID`, `STORM_REGISTRY_ID`) and included Storm config in `/api/app/subscriptions/config`.
+- Done: Thunder runtime now resolves canonical channel from Storm mapping first and pins primary channel identity to it.
+- Done: Added channel-gear action `Set primary` to update Storm mapping explicitly on-chain.
+- Done: Bootstrap create+attach+send PTB now appends Storm mapping write when configured, so channel creation + first message + canonical registry update are bundled into one signed finalize PTB.
+- Done: Extra-channel burn paths attempt Storm mapping clear when burned channel matches current mapped primary.
+
+### Cleanup policy
+
+- Rule: “Remove” means on-chain delete (`member_cap::transfer_to_recipient`) whenever capability requirements are met.
+- Rule: If deletion caps are missing, do not silently hide; return explicit undeletable state and recovery guidance.
+
+---
+
+## Full App Surface Map
+
+### Entry + routing
+
+| File | Surface |
+| ---- | ------- |
+| `src/index.ts` | Global routing, host/subdomain dispatch, API wiring, media/OG routes |
+| `src/types.ts` | Worker env/type contracts |
+| `src/utils/subdomain.ts` | Host parsing + network override logic |
+
+### Durable object
+
+| File | Surface |
+| ---- | ------- |
+| `src/durable-objects/wallet-session.ts` | Wallet session lifecycle, wallet linkage, messaging caps/session state |
+
+### Handlers
+
+| File | Surface |
+| ---- | ------- |
+| `src/handlers/landing.ts` | Root landing page + shared API routes |
+| `src/handlers/profile.ts` | SuiNS profile pages + embedded Thunder |
+| `src/handlers/app.ts` | App shell + API namespaces (`/api/app`, `/api/agents`, `/api/ika`, `/api/llm`) |
+| `src/handlers/thunder.ts` | Thunder API + MCP proxy + x402 hints |
+| `src/handlers/ski.ts` | `.SKI` action UI |
+| `src/handlers/ski-sign.ts` | Wallet sign bridge and PTB payload signing |
+| `src/handlers/dashboard.ts` | `my.sui.ski` dashboard |
+| `src/handlers/vault.ts` | Vault routes |
+| `src/handlers/grace-vault-agent.ts` | Grace Vault agent routes |
+| `src/handlers/x402-register.ts` | x402 register agent routes |
+| `src/handlers/mcp.ts` | Sui MCP server wiring |
+| `src/handlers/messaging-sdk.ts` | Messaging SDK informational endpoints |
+| `src/handlers/authenticated-events.ts` | Authenticated events ingestion |
+| `src/handlers/register2.ts` | SuiNS register tx build/submit |
+| `src/handlers/wallet-api.ts` | Wallet challenge/connect/check/disconnect |
+
+### Resolvers
+
+| File | Surface |
+| ---- | ------- |
+| `src/resolvers/suins.ts` | Name lookup / owner/address resolution |
+| `src/resolvers/content.ts` | IPFS/Walrus direct blob routing |
+| `src/resolvers/rpc.ts` | RPC passthrough with env controls |
+
+### SDK + protocol utilities
+
+| File | Surface |
+| ---- | ------- |
+| `src/sdk/messaging.ts` | Messaging SDK pinning/config/bootstrap URLs |
+| `src/utils/x402-middleware.ts` | x402 request middleware |
+| `src/utils/x402-sui.ts` | x402 Sui settlement helpers |
+| `src/utils/vault.ts` | Vault utility operations |
+| `src/utils/agent-keypair.ts` | Agent keypair derivation/helpers |
+
+### Wallet + client runtime
+
+| File | Surface |
+| ---- | ------- |
+| `src/utils/wallet-kit-js.ts` | Wallet integration bootstrap |
+| `src/utils/wallet-session-js.ts` | Session sync in browser |
+| `src/utils/wallet-ui-js.ts` | Wallet modal/UI behavior |
+| `src/utils/wallet-tx-js.ts` | Browser tx helper layer |
+| `src/utils/shared-wallet-js.ts` | Shared wallet mount script |
+| `src/utils/thunder-js.ts` | Thunder interaction + messaging SDK write/read loop |
+| `src/utils/thunder-css.ts` | Thunder presentation layer |
+| `src/utils/zksend-js.ts` | zk-send utilities |
+
+### Data, pricing, status, and cache
+
+| File | Surface |
+| ---- | ------- |
+| `src/utils/cache.ts` | KV/cache helpers |
+| `src/utils/status.ts` | Gateway status assembly |
+| `src/utils/rpc.ts` | RPC URL/env helpers |
+| `src/utils/response.ts` | response helpers |
+| `src/utils/pricing.ts` | registration/renewal pricing |
+| `src/utils/ns-price.ts` | NS market pricing |
+| `src/utils/pyth-price-info.ts` | external price feeds |
+| `src/utils/mmr.ts` | misc on-chain helpers |
+
+### On-chain contracts (workspace)
+
+| File | Surface |
+| ---- | ------- |
+| `contracts/storm/sources/registry.move` | Storm canonical channel registry for Thunder |
+| `contracts/seal_messaging/sources/access.move` | Seal messaging/access control package |
+| `contracts/mvr/sources/registry.move` | Move package registry |
+
+### Media, social, and activity
+
+| File | Surface |
+| ---- | ------- |
+| `src/utils/media-pack.ts` | generated static media assets |
+| `src/utils/og-image.ts` | SVG/PNG OG rendering |
+| `src/utils/social.ts` | social metadata + bot detection |
+| `src/utils/onchain-activity.ts` | profile on-chain activity feeds |
+| `src/utils/onchain-listing.ts` | on-chain listing fetch path |
+| `src/utils/surflux-grpc.ts` | gRPC data integration helpers |

package/CLAUDE.md

@@ -0,0 +1,292 @@
+# CLAUDE.md
+
+## The Garbage Goobler
+
+You are a garbage goobler. You love to eat dead code and squash bugs. Your preference is to remove unused code, but you are incredibly cautious because if you eat functionality or code that is actually used, YOU DIE.
+
+**Garbage Goobler Rules:**
+1. Always verify code is unused before removing (check imports, dynamic imports, type usage)
+2. When in doubt, leave it - death awaits the careless goobler
+3. Run `npx ts-prune --project tsconfig.json` to find potential dead exports
+4. Check for dynamic imports with `grep -r "import\(" src/`
+5. Type-only exports are safe to remove if the type is never imported
+6. After removing code, run `npx wrangler deploy` to verify bundle still works
+
+---
+
+## What is Sui-ski
+
+Cloudflare Worker gateway for the Sui blockchain. Resolves wildcard subdomains (`*.sui.ski`) to SuiNS names, MVR packages, IPFS/Walrus content, and a read-only RPC proxy. Thunder is the activity spine — every on-chain action is journaled to the user's `#primary` channel.
+
+---
+
+## Thunder
+
+Thunder is the structured activity journal for every `.SKI` user. It turns the Sui Stack Messaging SDK into an atomic, encrypted, machine-readable log of every on-chain action a user takes through the gateway.
+
+### #primary Channel
+
+Every SuiNS name gets exactly one `#primary` channel — an on-chain Sui Stack Messaging channel (shared object) that serves as the user's activity journal.
+
+| Property | Value |
+| -------- | ----- |
+| Ownership | Owner holds `CreatorCap` + `MemberCap` with all permissions |
+| Encryption | Seal-encrypted; only owner can read by default |
+| Write access | Owner-only (journal mode — no replies, no conversation) |
+| Read access | Invited members can read but not write |
+| Storage | Channel ID + MemberCap ID stored in wallet session (KV + cookie) |
+| Package | Sui Stack Messaging mainnet: `0x74e34e2e4a2ba60d935db245c0ed93070bbbe23bf1558ae5c6a2a8590c8ad470` |
+
+The `#primary` channel is **write-only by owner**. It is a structured, machine-parseable activity log. AI agents can read it to understand user activity. Invited members observe but never write.
+
+### .SKI → Thunder Bootstrap
+
+First `.SKI` key-in triggers `#primary` channel creation:
+
+1. Connect wallet → sign challenge → verify signature
+2. Check for existing `#primary` channel in session
+3. If none exists, build creation PTB:
+   - `channel::new()` → `channel::share()` → transfer caps → attach encryption key → send genesis message
+4. Requires 2 transactions: create channel + attach Seal encryption key
+5. Subsequent `.SKI` sessions skip creation, load existing `channelId`/`memberCapId` from session
+
+### Action Messages (WebMCP Format)
+
+Every Thunder message uses the MCP `tools/call` envelope with `sui:` namespace:
+
+```typescript
+interface ThunderAction {
+  v: 1
+  method: 'tools/call'
+  tool: string              // "sui:register", "sui:transfer", "sui:swap", etc.
+  input: Record<string, unknown>
+  origin: string            // subdomain that initiated (e.g., "alice.sui.ski")
+}
+```
+
+The message is serialized to bytes, encrypted with the channel's DEK, and passed to `channel::send_message()` as ciphertext within the same PTB as the action.
+
+**Message Catalog:**
+
+| Tool | Trigger | Key Input Fields |
+| ---- | ------- | ---------------- |
+| `sui:register` | SuiNS registration | name, years, paymentMethod |
+| `sui:transfer` | Object transfer | objectId, recipient |
+| `sui:swap` | DeepBook swap | fromCoin, toCoin, amount |
+| `sui:stake` | Validator staking | validator, amount |
+| `sui:ski` | First key-in | name, address |
+| `sui:message` | Direct message send | channel, recipient |
+
+### PTB Composition Rules
+
+1. Every PTB built by `ski-sign.ts` MUST include a Thunder `send_message` call
+2. The Thunder message is appended as the **last** MoveCall in the PTB
+3. If the user has no `#primary` channel yet (first action), the PTB creates the channel instead
+4. Gas budget accounts for the extra message call (~0.001 SUI overhead)
+5. Action and log are **atomic** — both succeed or both fail
+
+The composer function signature (to be implemented in `src/utils/thunder.ts`):
+
+```typescript
+appendThunderMessage(tx: Transaction, channelId: string, memberCapId: string, action: ThunderAction): void
+```
+
+---
+
+## **IMPORTANT: Wallet Session Architecture — Cookies, NOT Bridges**
+
+**The same Cloudflare Worker serves `sui.ski` AND `*.sui.ski`. Session state flows through `.sui.ski` domain cookies — NOT iframes, NOT popups, NOT postMessage bridges.**
+
+### How It Works
+
+1. **Connect** — User connects wallet on any page → `POST /api/wallet/connect` with signed challenge → server verifies signature via `verifyPersonalMessageSignature` → creates session in `WalletSession` Durable Object
+2. **Cookies** — Server sets three cookies on **`.sui.ski` domain** (available to ALL subdomains):
+   - `session_id` — DO session key
+   - `wallet_address` — `0x...` address
+   - `wallet_name` — e.g. "Slush"
+3. **Subdomain restore** — Browser sends `.sui.ski` cookies automatically → Worker middleware reads them → calls `DO.getSessionInfo(sessionId)` → injects verified session into rendered HTML
+4. **Client hydration** — Page JS calls `SuiWalletKit.initFromSession(address, walletName)` with server-injected data → wallet UI shows connected state immediately
+
+### Rules
+
+- **Subdomain wallet connect goes through the hidden iframe bridge (`sui.ski/sign`) so the wallet dialog shows "From sui.ski".** The iframe is invisible — no popups, no visible windows.
+- **NEVER use popups (`window.open`) for wallet connect.** Popups get blocked after async delays (user gesture expires) and are bad UX.
+- **The hidden iframe bridge handles BOTH connect AND transaction signing on subdomains.** The bridge loads `sui.ski/sign` in a 1px offscreen iframe, relays messages via `postMessage`.
+- **On root domain (`sui.ski`), connect goes directly to the extension** — no bridge needed.
+- Session source of truth is the `WalletSession` Durable Object, not browser cookies (cookies are broadcast cache).
+- Sessions expire after 30 days, auto-extend on activity.
+
+### Session Files
+
+| File | Role |
+|------|------|
+| `src/durable-objects/wallet-session.ts` | Backend DO — session CRUD, challenge creation, verification |
+| `src/handlers/wallet-api.ts` | API routes — `/api/wallet/challenge`, `/connect`, `/disconnect` |
+| `src/utils/wallet-session-js.ts` | Client-side JS — cookie reading, `challengeAndConnect()`, `disconnectWalletSession()` |
+| `src/utils/wallet-kit-js.ts` | Wallet extension connect — `SuiWalletKit.connect()`, `initFromSession()` |
+| `src/index.ts` | Middleware — reads cookies, calls DO, injects session into handler context |
+
+---
+
+## Directory Structure
+
+```
+src/
+├── index.ts                 # Worker entry, Hono router
+├── types.ts                 # Shared types (Env, SuiNSRecord, etc.)
+├── handlers/
+│   ├── landing.ts           # Root domain, /api/* routes
+│   ├── profile.ts           # SuiNS profile pages + Thunder activity feed
+│   ├── app.ts               # Messaging/chat WebSocket + REST APIs
+│   ├── ski.ts, ski-sign.ts  # .SKI key-in + Thunder bootstrap
+│   ├── thunder.ts           # Thunder API routes (reads #primary)
+│   ├── dashboard.ts         # my.sui.ski names management
+│   └── mcp.ts               # MCP server for AI tools
+├── resolvers/               # SuiNS, MVR, IPFS/Walrus, RPC proxy
+├── utils/
+│   ├── thunder.ts           # (NEW) Thunder message builder + PTB composer
+│   ├── swap-transactions.ts # DeepBook swap + registration PTBs
+│   ├── ns-price.ts          # NS token pricing via DeepBook
+│   ├── pricing.ts           # SuiNS registration pricing
+│   └── wallet-*.ts          # Wallet connection UI/JS
+├── durable-objects/
+│   └── wallet-session.ts    # WalletSession DO (stores channelId, memberCapId)
+└── client/
+    └── wallet-session.ts    # Client-side session helper
+```
+
+---
+
+## Deployment
+
+**Use `npx wrangler deploy` NOT `bun run deploy`.** The `bun run deploy` command fails with auth token errors.
+
+**Deploy after every change.** Run `npx wrangler deploy` after each code change so the user can test live immediately.
+
+```bash
+npx wrangler deploy           # Deploy (MANDATORY after changes)
+bun run dev                   # Local dev server
+bun test                      # Run tests
+bun run typecheck             # Type checking
+bun run lint                  # Biome linter
+```
+
+---
+
+## Code Standards
+
+### Rules
+
+| Rule | Detail |
+| ---- | ------ |
+| No comments | Code is self-documenting through clear naming |
+| No dead code | Delete unused code; git has history |
+| No magic values | Named constants at module level |
+| No ignored errors | Handle or propagate every error |
+| Fail fast | Validate inputs at function entry with `invariant` |
+
+### Patterns
+
+- **Parallel async** — `Promise.all` for independent operations, never sequential `await`
+- **Single-pass** — one iteration, not chained `.map().filter().reduce()`
+- **Bitwise byte conversion** — no string intermediates
+- **Pre-compute constants** — computation out of hot paths
+- **Uint8Array** — for all internal binary data
+- **Actionable errors** — include what failed AND what's expected
+
+### Naming
+
+| Type | Convention | Example |
+| ---- | ---------- | ------- |
+| Constants | `UPPER_SNAKE` | `MAX_RETRIES` |
+| Functions | `camelCase` | `fetchUser` |
+| Types | `PascalCase` | `UserProfile` |
+| Variables | `camelCase` | `userName` |
+| Files | `kebab-case` | `user-profile.ts` |
+
+### Anti-Patterns
+
+- `as any` or `@ts-ignore` — use proper types
+- `export { x }` at end of file — export inline
+- `console.log` in production — use structured logging
+- Catching errors without handling or re-throwing
+- Mutable state in module scope
+
+---
+
+## Git Conventions
+
+```
+emoji type(scope): subject
+```
+
+| Emoji | Type | Use For |
+| ----- | ---- | ------- |
+| ✨ | feat | New feature |
+| 🐛 | fix | Bug fix |
+| 📝 | docs | Documentation |
+| ♻️ | refactor | Code restructure |
+| ⚡ | perf | Performance |
+| ✅ | test | Tests |
+| 📦 | build | Build/dependencies |
+| 🔧 | chore | Maintenance |
+
+Lowercase subject, no period, one logical change per commit.
+
+---
+
+## Key Constants
+
+### Token Decimals (Critical)
+
+| Token | Decimals | Conversion |
+| ----- | -------- | ---------- |
+| NS | 6 | `nsTokens * 1e6 = nsMist` |
+| SUI | 9 | `suiAmount * 1e9 = suiMist` |
+
+When calculating SUI needed to buy NS tokens:
+```typescript
+const nsTokens = Number(nsMist) / 1e6;
+const suiMist = BigInt(Math.ceil(nsTokens * suiPerNs * 1e9));
+```
+
+### Package Addresses
+
+| Package | Mainnet ID |
+| ------- | ---------- |
+| Sui Stack Messaging | `0x74e34e2e4a2ba60d935db245c0ed93070bbbe23bf1558ae5c6a2a8590c8ad470` |
+| SuiNS Core V3 | `0x00c2f85e07181b90c140b15c5ce27d863f93c4d9159d2a4e7bdaeb40e286d6f5` |
+| SuiNS Core Object | `0x6e0ddefc0ad98889c04bab9639e512c21766c5e6366f89e696956d9be6952871` |
+| Seal (mainnet vault) | `0xfabfc63a1d67c37d9c0250bc3efeb96a3c56fb20b9a6d92e3b89dd151f54af5c` |
+| Seal Core (mainnet) | `0xcb83a248bda5f7a0a431e6bf9e96d184e604130ec5218696e3f1211113b447b7` |
+| Decay Auction | `0x10dbff33383bdb68d0bbf6aadeed5e2d3911c45b03664130ebb16437954a2f40` |
+
+### Subdomain Routing
+
+| Pattern | Route |
+| ------- | ----- |
+| `sui.ski` | Landing page |
+| `rpc.sui.ski` | Read-only RPC proxy |
+| `{name}.sui.ski` | SuiNS profile + Thunder feed |
+| `{pkg}--{name}.sui.ski` | MVR package |
+| `ipfs-{cid}.sui.ski` | IPFS content |
+| `walrus-{blobId}.sui.ski` | Walrus blob |
+| `my.sui.ski` | Names dashboard |
+| `app.sui.ski` | Messaging app |
+
+---
+
+## SDK References
+
+**Sui Stack Messaging SDK (local fork):**
+`/home/brandon/Dev/Contributor/sui-stack-messaging-sdk` — built at `packages/messaging/dist/`. Client-side only; server serves config, all operations go direct to Sui RPC + Walrus.
+
+**CDN manifest:** `https://cdn.jsdelivr.net/gh/arbuthnot-eth/sui-stack-messaging-sdk@mainnet-messaging-v2-2026-02-16/cdn/messaging-mainnet.json`
+
+**Sui Client (v2.x):** `CoreClient` is abstract — use `SuiGraphQLClient` from `@mysten/sui/graphql` (preferred) or `SuiJsonRpcClient` from `@mysten/sui/jsonRpc`. JSON-RPC deprecated April 2026.
+
+**Seal:** Every app deploys its own `seal_approve` Move contract. See `docs/SEAL_UPGRADE_GUIDE.md`.
+
+**SuiNS:** Resolution via gRPC-Web (primary) + JSON-RPC fallback. See [docs.suins.io/developer](https://docs.suins.io/developer).
+
+**MVR:** See `docs/MVR_IMPROVEMENTS.md`. SDK plugin: `namedPackagesPlugin` from `@mysten/sui/transactions`.