diff --git a/docs/concepts.mdx b/docs/concepts.mdx
new file mode 100644
index 00000000..a7cf7836
--- /dev/null
+++ b/docs/concepts.mdx
@@ -0,0 +1,92 @@
+---
+title: "Core Concepts"
+description: "The five things every Lit app is made of — accounts, API keys, wallets (PKPs), Lit Actions, and groups — and how they fit together."
+---
+
+Every Lit integration, whether it signs or encrypts, is assembled from the same five pieces. This page defines each one once, shows how they connect, and points to the administrative page where you manage it.
+
+```
+Account (your identity; holds the credit balance)
+ ├── Account API key (master credential — admin only, never ship it)
+ ├── Usage API keys (scoped, rotatable — what your app actually uses)
+ └── Group (the permission boundary)
+ ├── PKP (wallet) — a key pair the network holds for you
+ └── Lit Action (CID) — the code allowed to use those PKPs
+```
+
+When you call the `/core/v1/lit_action` endpoint, the server checks — before running anything — that your API key is allowed to execute that action code in a group, and that the PKP the action wants to use is permitted in the same group. That single rule is the whole security model from the developer's side.
+
+## Account
+
+Your account is your identity on Lit. Creating one registers it on-chain (on Base) and takes about 15 seconds; everything you create afterwards — keys, wallets, groups — hangs off it, and its credit balance pays for metered operations.
+
+Accounts come in two ownership flavors: **API mode** (the default — a server-generated API key is the credential) and **ChainSecured mode** (a wallet you control owns the account on-chain). Start in API mode; you can convert later, one-way.
+
+
+ Ownership models, converting API → ChainSecured, and transferring ownership.
+
+
+## API keys: account key vs. usage keys
+
+Lit has exactly two kinds of API key, and confusing them is the most common first-day mistake:
+
+| | Account key | Usage key |
+|---|---|---|
+| Created | Once, at account creation — **shown once, never again** | On demand, as many as you like |
+| Scope | Full admin access to the account | Only the groups it's been granted |
+| Rotatable | No — it *is* your account identity | Yes — create and delete freely |
+| Belongs in | A secrets manager, admin tooling | Your dApp, servers, cron jobs |
+
+Rule of thumb: the account key *configures*, usage keys *execute*. Anything that ships to production or to a user should hold a usage key scoped to one group.
+
+
+ Permission fields, key lifecycle, and managing keys via Dashboard or API.
+
+
+## PKPs (wallets)
+
+A Programmable Key Pair is a real wallet — an elliptic-curve key pair — whose private key lives inside the Lit network's TEE and never leaves it. Your account can mint many. A PKP does two jobs:
+
+- **Signing** — an authorized Lit Action retrieves the key with `Lit.Actions.getPrivateKey({ pkpId })` and signs messages or transactions with it (via ethers.js).
+- **Encryption** — `Lit.Actions.Encrypt` / `Lit.Actions.Decrypt` use an AES key derived from a PKP, so "who can decrypt" reduces to "which actions may use this PKP."
+
+Because a PKP is an ordinary EVM key pair, its address can hold funds, own NFTs, and be verified with `ecrecover` — the difference is that *code*, not a person with a seed phrase, decides when it signs.
+
+
+ Mint wallets from the Dashboard, or via `POST /core/v1/create_wallet`.
+
+
+## Lit Actions
+
+A Lit Action is an immutable JavaScript program: you publish it to IPFS, and its content hash (CID) becomes both its address and a permanent commitment to its behavior — change one byte and you have a different action. Actions run inside the network's TEE with access to the [Lit Actions SDK](/lit-actions/chipotle): PKP signing, encryption/decryption, and plain `fetch` to any HTTP endpoint.
+
+For quick iteration you can also pass raw code to the run endpoint without publishing to IPFS — permission checks then apply to the hash of that code.
+
+
+ The runtime, PKP access, proofs, and a minimal example.
+
+
+## Groups
+
+A group is the permission boundary that ties the other pieces together. It contains the PKPs that may be used, the action CIDs that may run, and it's what usage keys are scoped to. On-chain, this lives in the `AccountConfig` contract — the network enforces it on every call.
+
+Typical setup: one group per app (or per environment), holding that app's PKP(s) and permitted action(s), with one usage key granted `execute_in_groups` for it.
+
+
+ How on-chain group configuration binds PKPs, CIDs, and keys.
+
+
+## Funding and metering
+
+Running actions and *write* management calls (creating keys, PKPs, groups) consume credits from your account balance; all *read* calls are free. An unfunded metered call fails with `402 Payment Required`. You can fund with a credit card, [crypto](/management/crypto), or [LITKEY](/management/litkey).
+
+
+ Credit packages, per-call and per-second rates, and funding options.
+
+
+## Where to next
+
+- [Quick Start](/quickstart) — create an account and run your first action.
+- [Signing guide](/guides/signing) — from a fresh account to a verified signature.
+- [Encryption guide](/guides/encryption) — the encrypt/decrypt round trip.
+- [Architecture](/architecture/index) — how the TEE, the chain, and IPFS establish trust.
diff --git a/docs/docs.json b/docs/docs.json
index 9fdfbf70..e3af319e 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -12,30 +12,23 @@
{
"tab": "Building on Lit Protocol",
"pages": [
- "index",
- "quickstart",
{
- "group": "Management",
- "pages": [
- "management/dashboard",
- "management/api_direct",
- "management/account_modes",
- "management/pricing",
- "management/crypto",
- "management/litkey",
- "management/api_keys",
- "management/errors"
- ]
+ "group": "Get Started",
+ "pages": ["index", "quickstart", "concepts"]
+ },
+ {
+ "group": "Build for Your Use Case",
+ "pages": ["guides/signing", "guides/encryption"]
},
{
"group": "Lit Actions",
"pages": [
"lit-actions/index",
- "lit-actions/imports",
- "lit-actions/wasm",
"lit-actions/examples",
"lit-actions/patterns",
"lit-actions/secrets",
+ "lit-actions/imports",
+ "lit-actions/wasm",
"lit-actions/limits",
{
"group": "Migration",
@@ -54,6 +47,19 @@
"lit-triggers/examples"
]
},
+ {
+ "group": "Administration",
+ "pages": [
+ "management/dashboard",
+ "management/api_direct",
+ "management/api_keys",
+ "management/account_modes",
+ "management/pricing",
+ "management/crypto",
+ "management/litkey",
+ "management/errors"
+ ]
+ },
{
"group": "Architecture",
"pages": [
@@ -66,19 +72,19 @@
{
"group": "Security & Verification",
"pages": [
- "architecture/verification/attestation",
- "architecture/verification/quick-verify",
"architecture/verification/index",
+ "architecture/verification/quick-verify",
+ "architecture/verification/attestation",
"architecture/verification/onchain-kms",
"architecture/verification/upgrade-governance",
- "architecture/verification/full-verification",
- "architecture/verification/chain-of-trust"
+ "architecture/verification/chain-of-trust",
+ "architecture/verification/full-verification"
]
}
]
},
{
- "group": "Actions Reference",
+ "group": "Reference",
"pages": ["lit-actions/chipotle"]
}
]
diff --git a/docs/guides/encryption.mdx b/docs/guides/encryption.mdx
new file mode 100644
index 00000000..6fe21d7d
--- /dev/null
+++ b/docs/guides/encryption.mdx
@@ -0,0 +1,151 @@
+---
+title: "Encryption & Decryption"
+description: "From a fresh account to an encrypt/decrypt round trip: seal a secret under a vault PKP, store the ciphertext anywhere, and decrypt it only from code you've authorized on-chain."
+---
+
+This guide takes you from nothing to a working **encrypt/decrypt round trip**, then shows the pattern nearly every real integration uses it for: keeping API keys and credentials out of your code while still using them inside a Lit Action. Administrative pages are linked where you meet them.
+
+The model in two sentences: `Lit.Actions.Encrypt` seals data with an AES key derived — inside the TEE — from a PKP you own, and that key never exists outside the enclave. So "who can decrypt this?" reduces to "which action code is permitted to use that PKP?", which is on-chain configuration you control.
+
+If PKPs, groups, or usage keys are new to you, keep [Core Concepts](/concepts) open in a second tab. Coming from Lit V1 / Naga access-control conditions? Read [the model comparison](/lit-actions/migration/encryption) first — this is a different (and simpler) approach.
+
+## What you'll build
+
+1. A **vault PKP** — the key your ciphertexts are sealed under.
+2. An action that **encrypts** a secret and returns the ciphertext.
+3. An action that **decrypts** it — and only runs because you've authorized it.
+
+
+
+ If you haven't yet, follow the [Quick Start](/quickstart) through funding: create an account (store the account API key — it's shown once) and add at least $5.00 of credits. Metered calls without credits fail with `402 Payment Required`.
+
+ Admin reference: [API Keys](/management/api_keys) · [Pricing](/management/pricing) · [Errors](/management/errors).
+
+
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/create_wallet" \
+ -H "X-Api-Key: YOUR_ACCOUNT_KEY"
+ ```
+
+ The returned `wallet_address` is your `pkpId`. Treat one PKP as one **trust boundary**: everything encrypted under it is decryptable by any action allowed to use it. Separate app secrets from user data by minting separate PKPs — see [PKP wallets as data vaults](/lit-actions/patterns#encrypt--decrypt--pkp-wallets-as-data-vaults).
+
+
+
+
+
+ ```javascript
+ const result = await client.litAction({
+ apiKey: accountApiKey,
+ code: `
+ async function main({ pkpId, secret }) {
+ const ciphertext = await Lit.Actions.Encrypt({ pkpId, message: secret });
+ return { ciphertext };
+ }
+ `,
+ jsParams: { pkpId: '0xYOUR_VAULT_PKP', secret: 'my-api-key-or-anything' }
+ });
+ console.log(result.response);
+ ```
+
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/lit_action" \
+ -H "Content-Type: application/json" \
+ -H "X-Api-Key: YOUR_ACCOUNT_KEY" \
+ -d '{
+ "code": "async function main({ pkpId, secret }) { const ciphertext = await Lit.Actions.Encrypt({ pkpId, message: secret }); return { ciphertext }; }",
+ "js_params": { "pkpId": "0xYOUR_VAULT_PKP", "secret": "my-api-key-or-anything" }
+ }'
+ ```
+
+
+
+
+ The plaintext transits this one request (over TLS, into the TEE). For most secrets that's fine — encrypt once from a trusted machine. Never log it, and never leave it in shell history you don't control.
+
+
+
+
+ The ciphertext is safe to store in public: a database, IPFS, a smart contract, an environment variable, even hardcoded in client code. Its confidentiality comes from the PKP-derived key in the TEE, not from where it sits. Storage trade-offs are covered in [Secrets → where to put the ciphertext](/lit-actions/secrets).
+
+
+
+ ```javascript
+ const result = await client.litAction({
+ apiKey: accountApiKey,
+ code: `
+ async function main({ pkpId, ciphertext }) {
+ const plaintext = await Lit.Actions.Decrypt({ pkpId, ciphertext });
+ return { plaintext };
+ }
+ `,
+ jsParams: { pkpId: '0xYOUR_VAULT_PKP', ciphertext: 'FROM_STEP_3' }
+ });
+ ```
+
+ Round trip complete. In production you'll rarely *return* the plaintext like this — you'll **use** it inside the action (call an API with it, sign with it) and return only the result. Returning or logging decrypted secrets is the #1 leak path; see [common mistakes](/lit-actions/secrets#common-mistakes).
+
+
+
+ Right now your account key can run any code against the vault PKP. Locking it down is on-chain configuration:
+
+ 1. **Pin the decrypt action.** Publish your decrypting action to IPFS, [register the CID in a group](/management/dashboard#5-register-ipfs-cids-actions), and add the vault PKP to the same group. Now only that exact code can ever produce the plaintext.
+ 2. **Scope a usage key** to `execute_in_groups: [thatGroup]` for whatever service calls it — it can trigger the decrypt flow but can't run arbitrary code against your vault.
+ 3. **Gate inside the action** if you need caller-level rules: token balance, NFT ownership, a caller signature. The gate is plain JavaScript — see [gating logic](/lit-actions/patterns#gating-logic--aka-access-control-conditions).
+
+ The enforcement split — what the chain guarantees vs. what your action code guarantees — is summarized in [Secrets → what's enforced where](/lit-actions/secrets#whats-enforced-where).
+
+ Admin reference: [API Keys](/management/api_keys) · [Groups](/architecture/groups) · [Dashboard](/management/dashboard).
+
+
+
+## The pattern you'll actually use: encrypted secrets inside actions
+
+Most encryption use on Lit isn't "encrypt user files" — it's **giving your action a secret without giving it to anyone else**. Encrypt an API key once, pass the ciphertext as a `js_params` value (or hardcode it in the action), and decrypt at runtime inside the TEE:
+
+```javascript
+// js_params: { pkpId, city, encryptedWeatherApiKey }
+async function main({ pkpId, city, encryptedWeatherApiKey }) {
+ const apiKey = await Lit.Actions.Decrypt({ pkpId, ciphertext: encryptedWeatherApiKey });
+ const res = await fetch(
+ `https://api.openweathermap.org/data/2.5/weather?q=${city}&units=metric&appid=${apiKey}`
+ );
+ const { main: weather } = await res.json();
+ return { temp: weather.temp }; // the key itself never leaves the enclave
+}
+```
+
+The same shape secures paid RPC URLs, database connection strings, LLM API keys, and webhook signing secrets. Full treatment: [Secrets](/lit-actions/secrets) and [securing RPC URLs](/lit-actions/patterns#securing-rpc-urls--hiding-api-keys-with-encryption).
+
+## Where encryption goes from here
+
+
+
+ The full vault model: minting, permitting, storing, bundling multiple secrets, and rotation.
+
+
+ Decrypt only for callers who hold a token or NFT, or who sign a challenge — gates written as plain JS.
+
+
+ How PKP-derived encryption differs from BLS access-control conditions, and when to use each.
+
+
+ Exact signatures for Lit.Actions.Encrypt and Lit.Actions.Decrypt.
+
+
+ A dark pool that stores every order as ciphertext in Postgres and matches batches inside the enclave.
+
+
+ Decrypt a credential, act on it, sign the result — the two primitives compose in one action.
+
+
+
+## Administrative checklist for an encryption app
+
+- [ ] Separate vault PKPs per trust boundary (app secrets vs. user data) — [Patterns](/lit-actions/patterns#multiple-pkps-in-a-single-action--separating-app-secrets-from-user-signing)
+- [ ] Decrypt action published to IPFS, CID pinned in a group with the vault PKP — [Dashboard](/management/dashboard#5-register-ipfs-cids-actions)
+- [ ] Usage keys scoped to that group only; account key never ships — [API Keys](/management/api_keys)
+- [ ] No action returns or logs plaintext secrets — [Common mistakes](/lit-actions/secrets#common-mistakes)
+- [ ] Rotation plan: re-encrypt, replace ciphertext, invalidate the old secret upstream — [Secrets](/lit-actions/secrets)
+- [ ] Credit balance monitored; decrypt calls are metered like any action — [Pricing](/management/pricing)
diff --git a/docs/guides/signing.mdx b/docs/guides/signing.mdx
new file mode 100644
index 00000000..abb91fee
--- /dev/null
+++ b/docs/guides/signing.mdx
@@ -0,0 +1,166 @@
+---
+title: "Signing"
+description: "From a fresh account to a signature you can verify: mint a network-held wallet (PKP), sign a message from a Lit Action, and check the signature locally."
+---
+
+This guide takes you from nothing to a **verified signature**: a wallet whose private key lives inside Lit's TEE, a few lines of JavaScript that sign with it, and a local check that proves the signature is real. At each step, the administrative page that covers it in depth is linked — skim them now, come back when you productionize.
+
+If the nouns below (PKP, usage key, group) are new, keep [Core Concepts](/concepts) open in a second tab.
+
+## What you'll build
+
+1. A **PKP** — a real EVM wallet the network holds for you.
+2. A **Lit Action** that signs a message with that PKP.
+3. A local verification that the signature recovers to the PKP's address.
+
+Total cost is a few cents of credits; total time is about five minutes.
+
+
+
+ Create an account in the [Dashboard](https://dashboard.chipotle.litprotocol.com/dapps/dashboard/) (**New User** tab) or via the API:
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/new_account" \
+ -H "Content-Type: application/json" \
+ -d '{"account_name":"My Signing App","account_description":""}'
+ ```
+
+ The response contains your **account API key** — it is shown exactly once, so store it now, and never ship it in client code. Account creation takes ~15 seconds because it registers your account on-chain (Base).
+
+ Admin reference: [API Keys](/management/api_keys) · [Account Modes](/management/account_modes) (this guide uses the default API mode).
+
+
+
+ Running actions and write management calls consume credits; reads are free. Click **Add Funds** in the Dashboard (minimum $5.00, card, [crypto](/management/crypto), or [LITKEY](/management/litkey)). Unfunded metered calls return `402 Payment Required`.
+
+ Admin reference: [Pricing](/management/pricing) · [Errors](/management/errors).
+
+
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/create_wallet" \
+ -H "X-Api-Key: YOUR_ACCOUNT_KEY"
+ ```
+
+ Note the returned `wallet_address` — that address **is** your `pkpId` in the code below, and it's what signatures will recover to. The private key was generated inside the TEE and will never leave it.
+
+ Admin reference: [Dashboard → Wallets](/management/dashboard#4-request-new-pkps-wallets).
+
+
+
+ Run this action with your account key (we'll scope a production key in step 6):
+
+
+
+ ```javascript
+ const result = await client.litAction({
+ apiKey: accountApiKey,
+ code: `
+ async function main({ pkpId, message }) {
+ const wallet = new ethers.Wallet(
+ await Lit.Actions.getPrivateKey({ pkpId })
+ );
+ const signature = await wallet.signMessage(message);
+ return { message, signature };
+ }
+ `,
+ jsParams: { pkpId: '0xYOUR_PKP_ADDRESS', message: 'Hello from Lit' }
+ });
+ console.log(result.response);
+ ```
+
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/lit_action" \
+ -H "Content-Type: application/json" \
+ -H "X-Api-Key: YOUR_ACCOUNT_KEY" \
+ -d '{
+ "code": "async function main({ pkpId, message }) { const wallet = new ethers.Wallet(await Lit.Actions.getPrivateKey({ pkpId })); const signature = await wallet.signMessage(message); return { message, signature }; }",
+ "js_params": { "pkpId": "0xYOUR_PKP_ADDRESS", "message": "Hello from Lit" }
+ }'
+ ```
+
+
+
+ You can also paste the same code into the Dashboard's [Action Runner](/management/dashboard#7-run-lit-actions).
+
+
+
+ The point of Lit signing is that anyone can check the result without trusting you or Lit's API. In any Node script or browser console:
+
+ ```javascript
+ import { ethers } from 'ethers'; // v5: ethers.utils.verifyMessage
+
+ const recovered = ethers.utils.verifyMessage('Hello from Lit', signature);
+ console.log(recovered === '0xYOUR_PKP_ADDRESS'); // true
+ ```
+
+ If it recovers to your PKP's address, the message was signed by a key that only exists inside the TEE — and only code permitted on-chain could use it. The same check works on-chain via `ecrecover`, which is how smart contracts consume Lit signatures.
+
+
+
+ For a real app you don't want "any code, master key." Two changes:
+
+ 1. **Pin your action.** Publish the action code to IPFS and [register its CID in a group](/management/dashboard#5-register-ipfs-cids-actions), and add your PKP to the same group. Now only that exact code can sign with that wallet.
+ 2. **Mint a usage key** with `execute_in_groups` limited to that group, and put *that* key in your app:
+
+ ```bash
+ curl -s -X POST "https://api.chipotle.litprotocol.com/core/v1/add_usage_api_key" \
+ -H "Content-Type: application/json" \
+ -H "X-Api-Key: YOUR_ACCOUNT_KEY" \
+ -d '{
+ "name": "signing-app",
+ "description": "Signs with the app PKP only",
+ "can_create_groups": false,
+ "can_delete_groups": false,
+ "can_create_pkps": false,
+ "manage_ipfs_ids_in_groups": [],
+ "add_pkp_to_groups": [],
+ "remove_pkp_from_groups": [],
+ "execute_in_groups": [YOUR_GROUP_ID]
+ }'
+ ```
+
+
+ Freshly-granted permissions are **eventually consistent** — the first `/lit_action` call right after minting a key or adding a grant can fail for a beat. Poll the real call until it succeeds rather than sleeping a fixed amount. Details: [run lit-action](/management/api_direct#7-run-lit-action).
+
+
+ Admin reference: [API Keys](/management/api_keys) · [Groups](/architecture/groups) · full API walkthrough in [Using the API directly](/management/api_direct).
+
+
+
+## Where signing goes from here
+
+The message signature above is the atom; everything else is that atom plus conditions, transactions, or different curves.
+
+
+
+ Construct, sign, and broadcast an ETH transfer from your PKP — it's a normal wallet, so fund its address first.
+
+
+ Only sign when a condition holds — an API result, a contract read, a sanctions screen.
+
+
+ Every action has a key derived from its own IPFS CID — sign with code identity, no PKP needed.
+
+
+ Fetch data, aggregate it, and deliver a signature any contract can verify with ecrecover.
+
+
+ Derive an ed25519 wallet from an action's identity key and sign Solana transactions.
+
+
+ Threshold ECDSA/FROST where Lit holds one share and literally cannot sign without you.
+
+
+
+Want a signature produced on a schedule or in response to an event, with no server of your own? See [Lit Triggers](/lit-triggers/index).
+
+## Administrative checklist for a signing app
+
+- [ ] Account key lives in a secrets manager; only usage keys ship — [API Keys](/management/api_keys)
+- [ ] Usage key scoped with `execute_in_groups` to exactly one group — [API Keys](/management/api_keys)
+- [ ] Action published to IPFS and its CID pinned in the group — [Dashboard](/management/dashboard#5-register-ipfs-cids-actions)
+- [ ] Credit balance monitored (metered calls fail with `402` when empty) — [Pricing](/management/pricing) · [Errors](/management/errors)
+- [ ] If the PKP sends transactions, its address holds gas on the target chain
+- [ ] Decided on an ownership model (API vs. ChainSecured) — [Account Modes](/management/account_modes)
diff --git a/docs/index.mdx b/docs/index.mdx
index fb311b99..0c6165af 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -1,55 +1,79 @@
---
title: "Lit Protocol"
-description: "One programmable runtime for everything between an event and a signed action. Read from any source, compute inside a chain-secured TEE, write to any chain or API — with no backend to trust."
+description: "Signing and encryption, programmable. Run JavaScript inside a chain-secured TEE that can sign on any chain and encrypt or decrypt data — with no backend to trust."
---
-Lit is a programmable runtime that reads data from any source, runs your JavaScript inside a chain-secured TEE, and signs on any chain or API. Keys never leave the enclave, and the code that's allowed to use them is governed on-chain. You get the speed and expressiveness of a single trusted runtime, with the auditability of a smart contract.
+Lit gives your app two cryptographic superpowers without a backend to trust: **signing** (wallets whose keys never leave a secure enclave, driven by code you control) and **encryption** (data only your authorized code can decrypt). Both are powered by [Lit Actions](/lit-actions/index) — immutable JavaScript programs that run inside a chain-secured TEE, with key permissions governed on-chain.
- Create an account, fund it, and run your first Lit Action in a few minutes — via the Dashboard or the REST API.
+ Create an account, fund it, and run your first Lit Action in a few minutes — then follow the guide for your use case below.
-## Build
+## What do you want to build?
-The fastest paths to a running integration.
+Pick your use case. Each guide takes you from a fresh account to a working, verifiable result, and flags the administrative pieces (keys, funding, permissions) as you meet them.
-
-
- Web GUI for accounts, API keys, wallets (PKPs), IPFS actions, and groups.
-
-
- Drive the same workflows from cURL, the lightweight JS SDK, or your own client built from the OpenAPI spec.
+
+
+ Create a wallet the network holds for you, sign messages and transactions from code, and verify every signature. Covers conditional signing, EVM and Solana, and non-custodial co-signing.
-
- JavaScript that runs inside the network's TEE — read, decide, sign, in one file.
+
+ Encrypt secrets so only code you've authorized on-chain can decrypt them. Covers the encrypt/decrypt round trip, storing ciphertext anywhere, and using encrypted API keys inside actions.
-## Use cases
+Not sure which nouns mean what? [Core Concepts](/concepts) explains the five things every Lit app is made of — accounts, API keys, wallets (PKPs), actions, and groups — in one page.
+
+## Use cases in the wild
-Patterns you can build on one programmable runtime.
+Patterns people build on these two primitives, with runnable code for each.
-
+
Read state on one chain, sign on another — bridges, mirrors, and replays without a multisig in the middle.
-
- Aggregate any HTTP or RPC feed inside the TEE, sign the result with a PKP, deliver it anywhere a signature is trusted.
+
+ Aggregate any HTTP or RPC feed inside the TEE, sign the result, deliver it anywhere a signature is trusted.
-
+
Sign only when on- or off-chain conditions hold — sanctions screens, price thresholds, KYC checks, dispute windows.
-
- Encrypt API keys, credentials, or user data under a PKP — decryptable only by an action you've authorized on-chain.
+
+ Encrypt API keys, credentials, or user data — decryptable only by an action you've authorized on-chain.
-## Concepts
+## Administer your account
+
+Everything you need to operate what you build — you'll meet each of these inside the guides, and they're all collected under **Administration** in the sidebar.
+
+
+
+ Web GUI for accounts, API keys, wallets (PKPs), IPFS actions, and groups.
+
+
+ Your master account key vs. scoped, rotatable usage keys — and how to manage both.
+
+
+ Credit-based billing, what's metered vs. free, and paying by card, crypto, or LITKEY.
+
+
+ API mode vs. ChainSecured mode — picking an ownership model and migrating between them.
+
+
+ Drive every management workflow from cURL, the lightweight JS SDK, or your own OpenAPI client.
+
+
+ What `402 Payment Required` and friends mean, and how to fix them.
+
+
+
+## How it works
How the runtime works and how trust is established.
@@ -63,33 +87,11 @@ How the runtime works and how trust is established.
How API keys, scopes, and account ownership combine to authorize requests.
-
- Bind Programmable Key Pairs to permitted action CIDs and usage keys.
-
Attest that the enclave is running the code it claims to be running.
-## Operate
-
-Account ownership, billing, and key management.
-
-
-
- API mode vs. ChainSecured mode — picking an ownership model and migrating between them.
-
-
- Account keys vs. usage keys, and how to scope them.
-
-
- Credit-based billing, how requests are metered, and how to add funds.
-
-
- Open-source repos, deployment ownership, and the tradeoffs of operating your own Lit stack.
-
-
-
## Reference
diff --git a/docs/lit-actions/chipotle.mdx b/docs/lit-actions/chipotle.mdx
index 9a905c53..993da6b9 100644
--- a/docs/lit-actions/chipotle.mdx
+++ b/docs/lit-actions/chipotle.mdx
@@ -129,7 +129,7 @@ Diagnostic functions for inspecting the runtime state of a Lit Action.
Log and return details of all modules imported by this Lit Action. Returns an array of objects with the resolved CDN URL and SHA-384 integrity hash for each imported module. The details are also written to the action's console log via the print opCode.
-Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<{url: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), hash: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)}\>** Array of imported module details
+Returns **[Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array)\<\{url: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String), hash: [string](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String)\}\>** Array of imported module details
## Runtime Globals
diff --git a/docs/lit-actions/imports.mdx b/docs/lit-actions/imports.mdx
index 32a339f9..4f415c9b 100644
--- a/docs/lit-actions/imports.mdx
+++ b/docs/lit-actions/imports.mdx
@@ -279,7 +279,7 @@ The first time the network sees this version it is fetched from jsDelivr, double
Because the import specifier (including the version) is part of your action's source, the version you pin is baked into the action's IPFS CID:
-- A published npm version is **immutable** — npm will not let you republish different bytes under the same version number. So a pinned import always resolves to the same code, which keeps your action's CID — and therefore its [action-derived identity key](/lit-actions/patterns#action-identity-signing-immutable-proofs) — stable.
+- A published npm version is **immutable** — npm will not let you republish different bytes under the same version number. So a pinned import always resolves to the same code, which keeps your action's CID — and therefore its [action-derived identity key](/lit-actions/patterns#action-identity-signing--immutable-proofs) — stable.
- Bumping the version (`@1.0.0` → `@1.1.0`) changes the action source, which produces a new CID and a new action identity. Treat a dependency bump like any other change to action code: re-deploy, re-permission, and — if you rely on action-identity signing — update any verifier that pins the old address.
This is a feature: anyone verifying your action can read the import statement and see exactly which version of your logic it runs.
@@ -345,7 +345,7 @@ Module imports operate under the same security model as the rest of the Lit Acti
Module imports are subject to the same [resource limits](/lit-actions/limits) as the rest of your action:
-- **Memory** — Imported modules count toward the action's memory limit (default 128 MB).
+- **Memory** — Imported modules count toward the action's memory limit (default 64 MB).
- **Timeout** — Module fetch time counts toward the action's execution timeout (default 15 minutes).
- **Network** — Module fetches use a separate HTTP client from the action's `fetch()` API and do not count toward the per-action fetch limit. However, they share the same execution timeout.
- **Module size** — Individual modules are capped at 10 MB.
diff --git a/docs/lit-actions/migration/changes.mdx b/docs/lit-actions/migration/changes.mdx
index 9fb0afa6..1744ad36 100644
--- a/docs/lit-actions/migration/changes.mdx
+++ b/docs/lit-actions/migration/changes.mdx
@@ -1,4 +1,7 @@
-# Lit Actions: Migration from Datil or Naga
+---
+title: "Migration from Datil or Naga"
+description: "How deprecated Naga Lit Actions SDK calls map to their current equivalents."
+---
This document is a reference for developers migrating from the Naga Lit Actions SDK to the current SDK.
It covers all actions available in both generations and explains how deprecated Naga actions map to current equivalents.
@@ -7,7 +10,7 @@ It covers all actions available in both generations and explains how deprecated
The current Lit Actions SDK is a streamlined runtime focused on cryptographic key operations and action identity.
Many capabilities that previously required runtime API calls — permission checking, access control, multi-party signing coordination — are now handled **on-chain** through the security model managed by the
-[Dashboard application](https://developer.litprotocol.com/) or accessed directly on-chain.
+[Dashboard application](https://dashboard.chipotle.litprotocol.com/dapps/dashboard/) or accessed directly on-chain.
> **Deprecated actions** generally have equivalent functionality derived through the combination of **new actions** and the **on-chain security settings** provided by the Dashboard application (or accessed directly on-chain).
> Permissions, group membership, and access control are now encoded at account-creation time rather than checked dynamically at execution time.
diff --git a/docs/management/dashboard.mdx b/docs/management/dashboard.mdx
index 04f676a2..8c79e6ad 100644
--- a/docs/management/dashboard.mdx
+++ b/docs/management/dashboard.mdx
@@ -1,3 +1,7 @@
+---
+title: "Dashboard"
+description: "Step-by-step walkthrough of the web management GUI: accounts, funds, usage keys, PKPs, IPFS actions, groups, and running actions."
+---
## Using the Dashboard
diff --git a/docs/quickstart.mdx b/docs/quickstart.mdx
index ef52a37f..5e95197c 100644
--- a/docs/quickstart.mdx
+++ b/docs/quickstart.mdx
@@ -5,6 +5,8 @@ description: "Go from zero to a running Lit Action in a few minutes using the Li
This guide walks you through creating an account, funding it, and running your first Lit Action. You can do everything from the [**Dashboard**](https://dashboard.chipotle.litprotocol.com/dapps/dashboard/) (web GUI) or directly against the [**REST API**](https://api.chipotle.litprotocol.com/).
+Once you're set up here, jump to the guide for your use case: [**Signing**](/guides/signing) (network-held wallets, verifiable signatures) or [**Encryption & decryption**](/guides/encryption) (secrets only your authorized code can read). If any terminology below is unfamiliar, [Core Concepts](/concepts) defines it all in one page.
+
## Zero to Lit Action
1. [Create an account via the Dashboard](/management/dashboard#1-request-a-new-account-or-log-in), note down your API key. Account creation takes ~15 seconds — it registers your account on-chain (Base).
@@ -55,8 +57,16 @@ The Dashboard is just your human-friendly configuration tool. Once your account
## Next steps
+**Build for your use case:**
+
+- [Signing guide](/guides/signing) — mint a wallet (PKP), sign from an action, verify the signature locally
+- [Encryption guide](/guides/encryption) — encrypt a secret, store the ciphertext anywhere, decrypt only from authorized code
+- [Core Concepts](/concepts) — accounts, API keys, PKPs, actions, and groups in one page
+
+**Go deeper:**
+
- [Lit Actions Overview](/lit-actions/index) — what they are and how they run
-- [Examples](/lit-actions/examples) — signing, encryption, HTTP fetching, contract calls
+- [Examples](/lit-actions/examples) — 18 runnable patterns, from a signed message to bridges, oracles, and MPC co-signing
- [Architecture](/architecture/index) — the TEE / on-chain / IPFS layers
- [Chain Secured](/architecture/chain-secured) — why your keys' authority lives on-chain, and how an attested TEE enforces it
- [OpenAPI Spec](https://api.chipotle.litprotocol.com/core/v1/openapi.json) / [Swagger UI](https://api.chipotle.litprotocol.com/core/v1/swagger-ui)