BringID · mikhaildobs · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026 · Feb 26, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -71,3 +71,51 @@ Append `use context7` to your prompt when asking about Semaphore (e.g., "create
 - `NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID` — WalletConnect project ID
 - `NEXT_PUBLIC_ALCHEMY_API_KEY` — Alchemy API key (used for Base and Base Sepolia RPCs)
 - `E2E_PRIVATE_KEY` — Private key for e2e headless wallet (in .env.local, never committed)
+
+## Documentation standards
+
+These rules apply to all files in the `docs/` folder.
+
+### Writing
+
+- Use second-person voice ("you").
+- Assume the reader has a crypto wallet (MetaMask) and understands transactions, gas, and network switching. Don't explain these basics.
+- List prerequisites at the start of procedural content.
+- Add language tags on all fenced code blocks.
+- Add alt text on all images.
+- Use relative paths for internal links.
+- Use sentence case for all headings (capitalize only the first word and proper nouns).
+- Prefer active voice and direct language.
+- Remove unnecessary words while maintaining clarity.
+- Break complex instructions into clear numbered steps.
+- Use broadly applicable examples rather than overly specific business cases.
+
+### Language and tone
+
+- No promotional language.
+- Limit conjunction overuse (moreover, furthermore, additionally).
+- No editorializing ("it's important to note", "in conclusion").
+- No undue emphasis on routine concepts.
+
+### Formatting
+
+- Use bold, italics, and other formatting only when it serves understanding, not visual appeal.
+- Clean structure with no emoji or decorative elements.
+
+### Content strategy
+
+- Document just enough for user success.
+- Prioritize accuracy and usability.
+- Make content evergreen where possible.
+- Search existing docs before adding new content to avoid duplication.
+- Start with the smallest reasonable change.
+
+## Documentation roadmap
+
+Three integration guides in `docs/`:
+
+1. **Register a new app** (`guide-register-app.md`) — register via App Manager, view app settings
+2. **Integrate BringID SDK** (planned) — add the `bringid` package to a frontend
+3. **Integrate BringID smart contract** (planned) — call CredentialRegistry directly
+
+Registering an app is a prerequisite for SDK usage. The App Manager also handles app management (status, recovery timelock, admin transfer) and custom scorer configuration, covered in the existing `guide-set-custom-scores.md` and `guide-verify-integration.md`.
diff --git a/README.md b/README.md
@@ -56,5 +56,7 @@ The network switcher in the header allows switching between networks at any time
 
 ## Documentation
 
-- [Guide: Creating an App & Setting a Custom Scorer](docs/guide-create-app-and-custom-scorer.md)
+- [Guide: Register an app](docs/guide-register-app.md)
+- [Guide: Set custom scores](docs/guide-set-custom-scores.md)
+- [Guide: Verify your integration](docs/guide-verify-integration.md)
 - [Video Walkthrough](e2e/videos/walkthrough.mp4)
diff --git a/docs/guide-create-app-and-custom-scorer.md b/docs/guide-create-app-and-custom-scorer.md
diff --git a/docs/guide-register-app.md b/docs/guide-register-app.md
@@ -0,0 +1,41 @@
+# Register a new app
+
+Go to the [BringID App Manager](https://manager.bringid.org/apps/new) to register a new app and get the App ID required for integration.
+
+## Register app onchain
+
+![Registration form with recovery timelock fields](../e2e/screenshots/02-register-app-form.png)
+
+1. Connect a crypto wallet. Your connected wallet becomes the app admin.
+2. Set the recovery timelock (see below).
+3. Click **Create App** and confirm the transaction in your wallet. Apps are registered onchain in the BringID CredentialRegistry contract.
+
+### Recovery timelock
+
+Recovery lets users replace the key proving ownership of their credentials. If a user loses access to their wallet, they can re-authenticate through a verification flow to link a new key. The timelock sets a waiting period between initiating and finalizing recovery — during this window, the user cannot generate proofs with either key, which prevents double-spend.
+
+Choose a preset (1 day to 1 year) or enter a custom value in seconds. Setting the value to 0 disables key recovery entirely.
+
+The right value depends on how often users interact with your app:
+
+- Faucet dispensing tokens every 24 hours — set to 1 day
+- Weekly promotion where unique users register within a week — set to 1 week
+- One-time airdrop claimed by unique humans — disable recovery (set to 0)
+
+This setting can be changed later from the app settings page.
+
+## Get App ID
+
+After the transaction confirms, a success banner displays your new App ID.
+
+![Success banner showing the new App ID](../e2e/screenshots/03b-register-app-success.png)
+
+Copy and pass the App ID to the BringID SDK to integrate it with your app.
+
+## What's next
+
+Manage app settings, transfer admin to another wallet, or set custom scores on the settings page.
+
+---
+
+Next: [Set custom scores](guide-set-custom-scores.md)
diff --git a/docs/guide-set-custom-scores.md b/docs/guide-set-custom-scores.md
@@ -0,0 +1,60 @@
+# Guide: Set custom scores
+
+Deploy a custom scorer and configure per-credential-group scores for your app.
+
+---
+
+## Step 1: Deploy a custom scorer
+
+The Deploy Custom Scorer page (`/apps/{appId}/scorer/deploy`) guides you through a **3-step wizard**:
+
+![Deploy Scorer Wizard](../e2e/screenshots/annotated/05-deploy-scorer.png)
+
+### Step 1a: Deploy scorer contract
+
+Click **Deploy New Scorer**. This deploys a new `DefaultScorer` instance via `ScorerFactory.create()`. Once confirmed, the wizard advances and displays your scorer's contract address.
+
+> **Tip:** If you previously deployed a scorer, it will appear in the "You already have N deployed scorer(s)" section with a **Reuse** button, letting you skip this step.
+
+### Step 1b: Set scorer on app
+
+The wizard shows: *"Scorer deployed at `0x47e5...7bf5`"*
+
+Click **Set App Scorer** to call `CredentialRegistry.setAppScorer(appId, scorerAddress)`. Once confirmed, the wizard advances to Step 3.
+
+### Step 1c: Done
+
+A yellow warning banner indicates:
+
+> **Almost done — set your scores**
+> Your custom scorer is deployed but all scores are currently set to **0**. You need to set scores before your app can calculate humanity scores.
+
+Click **Set Scores** to configure your custom scores.
+
+---
+
+## Step 2: Set custom scores
+
+The Manage Scores page (`/apps/{appId}/scorer/manage`) displays all 15 credential groups in an editable table:
+
+![Manage Custom Scores](../e2e/screenshots/annotated/06-manage-scores.png)
+
+
+### Edit and save scores
+
+1. Click **Copy defaults** in the Custom Score column header to pre-fill all fields with BringID's default scores, or enter your desired scores manually. For example:
+   - Farcaster (Low): `5`
+   - Farcaster (Medium): `10`
+   - Farcaster (High): `20`
+
+2. The **Save** button updates to show how many scores you've changed: **"Save 3 Score(s)"**
+
+3. Click the Save button. This calls `DefaultScorer.setScores(ids[], scores[])` in a single batch transaction.
+
+4. Confirm the transaction. The table refreshes with your new scores.
+
+> **Reset** — Click the Reset link in the Custom Score column header to discard all unsaved changes.
+
+---
+
+Next: [Verify your integration](guide-verify-integration.md)
diff --git a/docs/guide-verify-integration.md b/docs/guide-verify-integration.md
@@ -0,0 +1,10 @@
+# Guide: Verify your integration
+
+After saving scores, click **Check Integration** at the bottom of the Manage Scores page. This opens the **SDK Demo** page pre-configured with your app.
+
+![SDK Demo](../e2e/screenshots/annotated/08-demo-page.png)
+
+The Demo page lets you test:
+
+- **verifyHumanity** — Start the BringID humanity verification flow (opens a modal)
+- **verifyProofs** — Verify on-chain proofs and see the score breakdown by credential group