# Cloak Documentation

This file is the canonical index for AI coding agents integrating with Cloak.

## AI Entrypoints

- [AI integration](/ai-tools/ai-integration): Read order and one-shot prompt templates.
- [LLM full export](/llms-full.txt): Single-file context pack for AI agents.
- [TypeScript SDK LLM reference](/sdk/llms.txt): Exhaustive `@cloak.dev/sdk` contract map and runtime invariants.
- [Rust SDK LLM reference](/sdk/rust/llms.txt): Exhaustive `cloak-sdk` (Rust crate) contract map and runtime invariants.
- [Well-known alias](/.well-known/llms.txt): Compatibility path for tools that probe `.well-known`.

## Documentation

### Getting Started

- [Platform Overview](/platform/overview): How Cloak fits together across SDK, programs, and circuits.
- [Cloak SDKs](/sdk/introduction): Language picker — pick TypeScript or Rust.

### Platform

- [Platform Components](/platform/components): Runtime boundaries for each subsystem.
- [Transaction Flows](/platform/transaction-flows): Deposit, transfer, withdraw, and swap lifecycle details.
- [Viewing Keys and Compliance](/architecture/viewing-keys-compliance): Key model, registration lifecycle, history behavior.

### TypeScript SDK (`@cloak.dev/sdk`)

- [Quickstart](/sdk/quickstart): Minimal mainnet setup with SOL send and withdraw examples.
- [Code Examples](/sdk/examples): Production-style snippets for common integration flows.
- [Solana Kit integration](/sdk/kit-integration): Integrate Cloak SDK in Kit-standardized codebases.
- [Core concepts](/sdk/core-concepts): UTXO model, fee semantics, viewing-key behavior, root retries.
- [UTXO Transactions](/sdk/utxo-transactions): Primary production APIs (`transact`, `fullWithdraw`, `swapWithChange`).
- [Wallet integration](/sdk/wallet-integration): wallet-adapter wiring and secure signing patterns.
- [Error handling](/sdk/error-handling): Retry categories and diagnostics strategy.
- [API reference](/sdk/api-reference): Public exports and key type signatures.
- [TypeScript SDK LLM reference](/sdk/llms.txt): Deep AI-oriented export map for all runtime surfaces.

### Rust SDK (`cloak-sdk`)

- [Introduction](/sdk/rust/introduction): Scope, install, minimal setup, TS→Rust mental model.
- [Quickstart](/sdk/rust/quickstart): First SOL deposit end-to-end with `TransactOptions`.
- [Core concepts](/sdk/rust/core-concepts): How Rust types map to protocol primitives.
- [API reference](/sdk/rust/api-reference): `TransactOptions`, `TransactResult`, `Relay`, and helper types.
- [Error handling](/sdk/rust/error-handling): `Error` enum variants and retry semantics.
- [Rust SDK LLM reference](/sdk/rust/llms.txt): Dense AI-oriented reference for the `cloak-sdk` crate.

### Protocol and Runtime

- [Protocol Architecture](/protocol/architecture): End-to-end runtime path from client to on-chain state.
- [Shield Pool Program](/protocol/shield-pool): Program behavior relevant to integrators.
- [Fee Model](/protocol/fee-model): Constants, formula, and per-flow breakdown for the on-chain fee.
- [Circuits Package](/packages/circuits): Proof circuit build and hosting pipeline.
- [Security](/operations/security): Trust boundaries and security controls.

### AI Tooling

- [Cursor setup](/ai-tools/cursor): Rules and prompt pack for Cursor.
- [Claude Code setup](/ai-tools/claude-code): Rules and prompt pack for Claude Code.
- [Windsurf setup](/ai-tools/windsurf): Rules and prompt pack for Windsurf.

### User Guide (plain-language, non-developer)

- [What is Cloak?](/guide/what-is-cloak): Plain-language positioning — what Cloak does and who it's for.
- [How Cloak works](/guide/how-it-works): The four user flows — shield, private send, private swap, unshield.
- [Your private balance and backup file](/guide/private-balance): Custody model — UTXOs, the backup file, loss and recovery semantics.
- [Fees](/guide/fees): Who pays what per action; free shielding, 0.3% to leave the pool.
- [Payment links](/guide/payment-links): Single-use bearer links — pay without the recipient's address, or get paid without revealing yours.
- [Security](/guide/security): Audit status, threat model, what Cloak cannot do, governance.
- [Compliance and proof of funds](/guide/compliance): Viewing-key selective disclosure, reports, screening.
- [Verified addresses](/guide/verified-addresses): Canonical program ID and official links (anti-scam).
- [FAQ](/guide/faq): Honest answers to trust, custody, recovery, fee, and privacy questions.
- [Glossary](/guide/glossary): Plain-language definitions of Cloak and privacy terms.
- [Supported wallets and tokens](/guide/wallets-and-tokens): Wallet list and tokens per action.
- [Your Solana wallet is a public diary](/learn/wallet-public-diary): Why on-chain privacy matters.
- [Zero-knowledge, without the math](/learn/zero-knowledge-without-the-math): ZK proofs explained plainly.
- [Privacy is not anonymity](/learn/privacy-is-not-anonymity): Accountable privacy vs hiding.
- [Prove your funds privately](/learn/prove-your-funds-privately): Selective disclosure in practice.

## Integration Tips For Agents

- Pick the SDK that matches the host app: TypeScript for web/Node, Rust for server/CLI/program clients.
- Use SDK defaults for program, relay, and circuits in standard integrations.
- Keep tx amounts as `bigint` (TS) or `u64` / `i64` (Rust) end-to-end — no float math.
- Treat stale-root failures as retryable (both SDK transaction paths already do this by default).
- Never log private keys, viewing keys (`nk`), seed material, or raw note payloads.
- Transaction signatures are public and can be logged for support/debugging.
- For one-shot work, start with `/ai-tools/ai-integration`.

## Minimal Script Contract (TypeScript — for vague/short prompts)

- MUST generate one keypair-only CLI script for private SOL send using `@cloak.dev/sdk`.
- MUST use CLI shape: `npx tsx send-sol-private.ts <recipientPubkey> <lamports>`.
- MUST parse recipient/amount from `process.argv` (not env vars).
- MUST require env vars: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only.
- MUST use flow: `transact(...)` deposit then `fullWithdraw(...)` send.
- MUST keep `programId` fixed to `CLOAK_PROGRAM_ID` internally; do not ask users to configure it.
- MUST call `process.exit(0)` on success and `process.exit(1)` on failure.
- MUST NOT request `SENDER_PRIVATE_KEY` or any raw secret env var.
- MUST NOT use `RECIPIENT_ADDRESS`/`SEND_LAMPORTS` env vars for the CLI contract.
- MUST NOT use `AMOUNT_SOL` + float parsing; accept lamports input and keep amount math in `bigint`.
- MUST NOT add custom stale-root retry loops unless app policy explicitly asks for extra retries beyond SDK defaults.

## Minimal Script Contract (Rust — for vague/short prompts)

- MUST generate one `cargo run`-able binary for private SOL send using the `cloak-sdk` crate.
- MUST use CLI shape: `cargo run -- <recipientPubkey> <lamports>` (parsed from `std::env::args`).
- MUST require env vars: `SOLANA_RPC_URL` and `KEYPAIR_PATH` only.
- MUST use `cloak_sdk::core::transact::transact(opts)` with a deposit shape then a withdraw shape.
- MUST populate `opts.rpc` (via `SolanaRpc::new(...)`), `opts.payer` (via `Arc<Keypair>`), and `opts.relay_url` for the withdraw.
- MUST use `CLOAK_PROGRAM_ID` and `NATIVE_SOL_MINT` from `cloak_sdk::constants` — do not expose as config.
- MUST use `std::process::exit(0)` on success and `std::process::exit(1)` on failure (or return `Result<()>` from `main`).
- MUST keep amounts as `u64` / `i64`; no float parsing.
- MUST NOT request private-key bytes via env var; load from the `KEYPAIR_PATH` JSON file.
- MUST NOT add custom retry loops — the SDK retries RootNotFound/BlockhashExpired/StaleProofState internally.