# 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.
- [SDK LLM reference](/sdk/llms.txt): Exhaustive `@cloak.dev/sdk` 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.
- [Getting started with Cloak SDK](/sdk/introduction): Current SDK runtime guide with web3.js and Solana Kit options.
- [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.

### 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.

### SDK

- [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.
- [SDK LLM reference](/sdk/llms.txt): Deep AI-oriented export map for all runtime surfaces.

### 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.
- [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.

## Integration Tips For Agents

- Prefer UTXO APIs for new integrations.
- Use SDK defaults for program, relay, and circuits in standard integrations.
- Keep tx amounts as `bigint` end-to-end.
- Treat stale-root failures as retryable (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 (for vague/short prompts)

- MUST generate one keypair-only CLI script for private SOL send.
- 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.