npm - @tideorg/mcp - Versions diffs - 1.4.0 - Mend

@tideorg/mcp 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (76) hide show

package/GAP_REGISTER.md +117 -0
package/README.md +38 -0
package/adapters/AGENTS.md +241 -0
package/adapters/CLAUDE.md +146 -0
package/adapters/replit.md +224 -0
package/canon/anti-patterns.md +2133 -0
package/canon/concepts.md +816 -0
package/canon/custom-contracts.md +533 -0
package/canon/delegation.md +195 -0
package/canon/feature-mapping.md +637 -0
package/canon/framework-matrix.md +1125 -0
package/canon/invariants.md +851 -0
package/canon/redirect-handler.md +254 -0
package/canon/tidecloak-bootstrap.md +287 -0
package/canon/tidecloak-endpoints.md +294 -0
package/canon/troubleshooting.md +1494 -0
package/canon/version-policy.md +89 -0
package/mcp-server/dist/index.d.ts +2 -0
package/mcp-server/dist/index.js +605 -0
package/package.json +45 -0
package/playbooks/add-auth-nextjs-existing.md +799 -0
package/playbooks/add-auth-nextjs-fresh.md +654 -0
package/playbooks/add-rbac-nextjs.md +190 -0
package/playbooks/bootstrap-realm-from-template.md +170 -0
package/playbooks/configure-e2ee-roles-and-policies.md +196 -0
package/playbooks/deploy-tidecloak-docker.md +792 -0
package/playbooks/diagnose-broken-login.md +234 -0
package/playbooks/diagnose-missing-roles-or-claims.md +253 -0
package/playbooks/initialize-admin-and-link-account.md +235 -0
package/playbooks/migrate-from-existing-auth.md +198 -0
package/playbooks/protect-api-nextjs.md +451 -0
package/playbooks/protect-routes-nextjs.md +544 -0
package/playbooks/setup-forseti-e2ee.md +756 -0
package/playbooks/setup-iga-admin-panel.md +344 -0
package/playbooks/setup-server-delegation.md +142 -0
package/playbooks/start-tidecloak-dev.md +130 -0
package/playbooks/verify-jwt-server-side.md +439 -0
package/prompts/add-admin-approval-flow.md +50 -0
package/prompts/build-private-customer-portal.md +85 -0
package/prompts/migrate-generic-auth-to-tide.md +67 -0
package/prompts/secure-existing-app.md +80 -0
package/reference-apps/INDEX.md +87 -0
package/reference-apps/encrypted-communication/anti-patterns.md +123 -0
package/reference-apps/encrypted-communication/bootstrap-sequence.md +152 -0
package/reference-apps/encrypted-communication/manifest.yaml +100 -0
package/reference-apps/encrypted-communication/role-policy-matrix.md +80 -0
package/reference-apps/encrypted-communication/scenario.md +134 -0
package/reference-apps/git-pr-signing-service/anti-patterns.md +61 -0
package/reference-apps/git-pr-signing-service/bootstrap-sequence.md +157 -0
package/reference-apps/git-pr-signing-service/manifest.yaml +80 -0
package/reference-apps/git-pr-signing-service/role-policy-matrix.md +99 -0
package/reference-apps/git-pr-signing-service/scenario.md +169 -0
package/reference-apps/iga-admin-governance/anti-patterns.md +133 -0
package/reference-apps/iga-admin-governance/bootstrap-sequence.md +153 -0
package/reference-apps/iga-admin-governance/manifest.yaml +87 -0
package/reference-apps/iga-admin-governance/role-policy-matrix.md +67 -0
package/reference-apps/iga-admin-governance/scenario.md +126 -0
package/reference-apps/organisation-password-manager/anti-patterns.md +71 -0
package/reference-apps/organisation-password-manager/bootstrap-sequence.md +127 -0
package/reference-apps/organisation-password-manager/manifest.yaml +86 -0
package/reference-apps/organisation-password-manager/role-policy-matrix.md +59 -0
package/reference-apps/organisation-password-manager/scenario.md +107 -0
package/reference-apps/policy-governed-signing/anti-patterns.md +67 -0
package/reference-apps/policy-governed-signing/bootstrap-sequence.md +128 -0
package/reference-apps/policy-governed-signing/manifest.yaml +78 -0
package/reference-apps/policy-governed-signing/role-policy-matrix.md +62 -0
package/reference-apps/policy-governed-signing/scenario.md +113 -0
package/skills/tide-diagnostics/SKILL.md +99 -0
package/skills/tide-integration/SKILL.md +136 -0
package/skills/tide-learning-capture/SKILL.md +174 -0
package/skills/tide-rbac-and-e2ee/SKILL.md +214 -0
package/skills/tide-reviewer/SKILL.md +133 -0
package/skills/tide-route-and-api-protection/SKILL.md +201 -0
package/skills/tide-scenario-resolver/SKILL.md +81 -0
package/skills/tide-setup/SKILL.md +218 -0
package/skills/tide-solutions-architect/SKILL.md +130 -0

package/canon/redirect-handler.md ADDED Viewed

@@ -0,0 +1,254 @@
+# Tide Post-Auth Redirect Handler
+Tide auth uses OIDC authorization code flow. After authentication at TideCloak, the browser is redirected back to the application at the configured `redirectUri`. A real page or route must exist at that URI. Without it, the user lands on a 404 or blank page and login completion fails.
+---
+## Rule
+**Every Tide-enabled app must have a working page or route at its configured `redirectUri`.** The Tide SDK provider must be active on that page to process the OIDC callback (extract the auth code and exchange it for tokens).
+This applies whether using the default redirect path or a custom one.
+**Default redirect path**: `/auth/redirect`
+**ASSUMED**: The default redirect URI path convention is `/auth/redirect`. If a different path is used, the corresponding route must exist.
+---
+## Why This Matters
+1. TideCloak redirects the browser to `redirectUri?code=...&state=...` after authentication.
+2. The Tide SDK on the target page reads the URL parameters and completes the token exchange.
+3. If no page exists at the redirect URI, the browser shows a 404. The SDK never runs. Login appears to fail silently.
+4. If the page exists but the SDK provider is not active there, the auth code is ignored.
+---
+## Framework-Specific Guidance
+### Vanilla JS / Vite (Static)
+**Default redirect path**: `/auth/redirect`
+**Required file**: `public/auth/redirect.html`
+This file must include the Tide SDK initialization script so the SDK can process the callback.
+```html
+<!-- public/auth/redirect.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <title>Completing login...</title>
+</head>
+<body>
+  <p>Completing login...</p>
+  <script type="module" src="/auth.js"></script>
+</body>
+</html>
+```
+**If using a custom redirectUri**: the corresponding HTML file must exist in `public/` at the matching path, and it must load the SDK.
+**Verification**:
+```bash
+# Check the file exists
+test -f public/auth/redirect.html && echo "Found" || echo "Missing"
+# Check it is accessible
+curl http://localhost:3000/auth/redirect.html
+```
+---
+### React SPA (Vite)
+**Default redirect path**: `/auth/redirect`
+**Required**: A route that renders at `/auth/redirect` within the SPA.
+React SPAs serve `index.html` for all paths when the dev server or production server has SPA fallback enabled. If SPA fallback is configured (Vite dev server does this by default), the SDK provider on the root page handles the callback automatically.
+**For production builds** served by a static file server without SPA fallback, create a physical file or configure server-side rewrite rules.
+**Option A — React Router route** (recommended if using React Router):
+```tsx
+// src/pages/AuthRedirect.tsx
+export default function AuthRedirect() {
+  return <p>Completing login...</p>;
+}
+// In your router config:
+// <Route path="/auth/redirect" element={<AuthRedirect />} />
+```
+**Option B — Verify SPA fallback** (if not using React Router):
+The Vite dev server serves `index.html` for all unmatched routes. The SDK provider on the root page processes the callback. For production, ensure your static host is configured for SPA fallback (e.g., `_redirects` file for Netlify, `vercel.json` rewrites, or nginx `try_files`).
+**If using a custom redirectUri**: the matching route or SPA fallback path must resolve to a page where the SDK provider is active.
+**Verification**:
+```bash
+# In dev mode, verify the path resolves (should return HTML, not 404)
+curl http://localhost:5173/auth/redirect
+```
+---
+### Next.js App Router
+**Default redirect path**: `/auth/redirect`
+**Required file**: `app/auth/redirect/page.tsx` (or `src/app/auth/redirect/page.tsx` if the project uses `src/`)
+This page processes the OIDC callback using the SDK's `useAuthCallback` hook, then redirects the user:
+- On success: to the `returnUrl` (where the user was before login) or home (`/`)
+- On error or missing PKCE verifier (e.g. page refresh): back to home
+- On direct navigation (no callback params): back to home
+```tsx
+// app/auth/redirect/page.tsx
+"use client";
+import { useAuthCallback } from "@tidecloak/nextjs";
+import { useEffect, useState } from "react";
+// Separated so useAuthCallback only runs after hydration (avoids SSR window error).
+function RedirectHandler() {
+  const { isProcessing, isSuccess, error } = useAuthCallback({
+    onSuccess: (returnUrl) => {
+      window.location.assign(returnUrl || "/");
+    },
+    onError: () => {
+      window.location.assign("/");
+    },
+    onMissingVerifierRedirectTo: "/",
+  });
+  useEffect(() => {
+    const params = new URLSearchParams(window.location.search);
+    if (!params.has("code") && !params.has("error")) {
+      window.location.assign("/");
+    }
+  }, []);
+  if (error) {
+    return <p>Authentication failed: {error.message}</p>;
+  }
+  if (isProcessing || !isSuccess) {
+    return <p>Completing login...</p>;
+  }
+  return <p>Redirecting...</p>;
+}
+export default function AuthRedirectPage() {
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  if (!mounted) return <p>Loading...</p>;
+  return <RedirectHandler />;
+}
+```
+**Do not** use a bare placeholder page (e.g., `return <p>Completing login...</p>` with no callback handling). The page must actively process the OIDC callback and redirect the user.
+**If using a custom redirectUri**: the corresponding App Router page must exist at the matching path.
+**Verification**:
+```bash
+# Check the file exists (adjust for src/ if needed)
+test -f app/auth/redirect/page.tsx && echo "Found" || echo "Missing"
+# Check the route resolves
+curl http://localhost:3000/auth/redirect
+# Should return HTML, not 404
+```
+---
+### Next.js Pages Router
+**Default redirect path**: `/auth/redirect`
+**Required file**: `pages/auth/redirect.tsx` (or `src/pages/auth/redirect.tsx` if the project uses `src/`)
+The SDK provider in `_app.tsx` covers all pages.
+```tsx
+// pages/auth/redirect.tsx
+export default function AuthRedirectPage() {
+  return <p>Completing login...</p>;
+}
+```
+**If using a custom redirectUri**: the corresponding Pages Router file must exist at the matching path.
+**Verification**:
+```bash
+test -f pages/auth/redirect.tsx && echo "Found" || echo "Missing"
+curl http://localhost:3000/auth/redirect
+```
+---
+## Diagnostic: Missing Redirect Handler
+**Symptom**: Login at TideCloak succeeds (credentials accepted) but the user lands on a 404 page or a blank page instead of returning to the app authenticated.
+**Diagnostic steps**:
+1. Check the configured `redirectUri`:
+   ```bash
+   # Next.js
+   grep 'REDIRECT_URI' .env.local .env
+   grep 'redirectUri' app/providers.tsx app/layout.tsx pages/_app.tsx 2>/dev/null
+   # React/Vite
+   cat public/tidecloak.json | grep redirect 2>/dev/null
+   # Vanilla JS
+   grep 'redirectUri' public/auth.js public/*.js 2>/dev/null
+   ```
+2. Check the handler exists at the redirect path:
+   ```bash
+   # Next.js App Router
+   test -f app/auth/redirect/page.tsx || test -f src/app/auth/redirect/page.tsx
+   # Next.js Pages Router
+   test -f pages/auth/redirect.tsx || test -f src/pages/auth/redirect.tsx
+   # React/Vite (check SPA fallback or physical file)
+   curl -s -o /dev/null -w "%{http_code}" http://localhost:5173/auth/redirect
+   # Vanilla JS
+   test -f public/auth/redirect.html
+   ```
+3. Verify the TideCloak client allows the redirect URI:
+   - TideCloak Admin → Clients → {client} → Settings → Valid Redirect URIs
+   - Must include the full redirect URI (e.g., `http://localhost:3000/auth/redirect`)
+**Fix**: Create the missing handler file or route using the examples above. Update TideCloak client settings to include the redirect URI.
+---
+## Anti-Patterns
+- **AP-REDIR-01**: Setting `redirectUri` to a path that does not exist in the app. Login completes at TideCloak but the user sees a 404.
+- **AP-REDIR-02**: Creating the redirect page but not including the SDK provider. The page renders but the auth code is never processed.
+- **AP-REDIR-03**: Assuming the redirect handler is optional. Without it, every login attempt fails to complete.
+- **AP-REDIR-04**: Using `redirectUri: window.location.origin` (root) without verifying the SDK is active on the landing page. This works when the root page has the SDK but breaks if the root redirects elsewhere.
+---
+## Relation to Other Invariants
+- **I-06 (CSP)**: Even with a correct redirect handler, CSP violations block the SWE iframe and cause login to hang.
+- **I-07 (Silent SSO)**: The `silent-check-sso.html` file handles silent token refresh, not the post-auth redirect. Both are required.
+- **Redirect URI mismatch**: If the URI configured in the SDK does not match the TideCloak client's Valid Redirect URIs list, TideCloak rejects the request before the redirect handler is even reached. See `diagnose-broken-login`.

package/canon/tidecloak-bootstrap.md ADDED Viewed

@@ -0,0 +1,287 @@
+# TideCloak Bootstrap — Canon
+Canonical reference for starting TideCloak and preparing a realm before any app-level Tide integration begins.
+Bootstrap is infrastructure work. It produces a running TideCloak with a configured realm, a linked admin, and an exported adapter JSON. App integration (SDK wiring, route protection, API auth) is a separate concern covered by the app-level canon and playbooks.
+---
+## Bootstrap Paths
+| Path | When to use | How |
+|------|-------------|-----|
+| **Generated app** (default) | New project from template | `npm run init` runs the bundled init script. Handles everything below automatically. |
+| **Manual / BYO TideCloak** (advanced) | Existing TideCloak instance, custom realm, or non-template project | Follow the playbook chain: `start-tidecloak-dev` → `bootstrap-realm-from-template` → `initialize-admin-and-link-account`. |
+### Generated app flow
+Templates include `scripts/init-tidecloak.sh` and a `"init"` script in package.json. The dev workflow is:
+```bash
+npm install
+npm run init    # starts TideCloak, creates realm, exports tidecloak.json
+npm run dev
+```
+The init script:
+1. Starts TideCloak dev container (Docker required)
+2. Creates realm from bundled template
+3. Runs Tide licensing + IGA setup
+4. Creates admin user with `tide-realm-admin` role
+5. Prints an invite link (admin must open in browser to link Tide account)
+6. Waits for account linking
+7. Approves change requests
+8. Exports `data/tidecloak.json` with Tide extensions
+After init, the app is ready. No manual TideCloak configuration needed.
+**Bootstrap order rule**: Always run bootstrap before writing app code. If the app imports `tidecloak.json` at compile time (e.g., TypeScript `import tcConfig from '../../data/tidecloak.json'`), create an empty placeholder file (`echo '{}' > data/tidecloak.json`) before the first build. The init script overwrites it with the real adapter. Add `data/tidecloak.json` to `.gitignore`.
+### Manual / BYO TideCloak flow
+For projects that do not use the init script, follow the manual sequence below. This is also the path for connecting to an existing TideCloak instance.
+---
+## Scope Boundary
+| Concern | Covered here | Covered elsewhere |
+|---------|-------------|-------------------|
+| Docker container lifecycle | Yes | — |
+| Realm creation from template | Yes | — |
+| Tide licensing + IGA enablement | Yes | — |
+| Admin user creation + account linking | Yes | — |
+| Change request approval (bootstrap phase) | Yes | `setup-iga-admin-panel` for runtime |
+| Adapter JSON export | Yes | — |
+| E2EE role + policy setup | Yes (realm prep) | `setup-forseti-e2ee` for app-level |
+| SDK wiring, provider, CSP | No | `add-auth-nextjs-fresh` et al. |
+| JWT verification, DPoP | No | `verify-jwt-server-side` |
+---
+## Docker Images
+| Image | Use when | Forseti support | `tide-roles-mapper` | ORK env vars required |
+|-------|----------|----------------|---------------------|-----------------------|
+| `tideorg/tidecloak-dev:latest` | Standard development, full Tide protocol | Yes | **Yes** | **No** — built-in defaults |
+| `tideorg/tidecloak-stg-dev:latest` | Staging, testing pre-release features | Yes | **No** — silently dropped on import | **Yes** — must be provided |
+**Staging mapper gap**: The `tide-roles-mapper` protocolMapper provider exists on the production image (`tidecloak-dev`) but not staging (`tidecloak-stg-dev`). Realm import silently drops the mapper with no warning. Include standard Keycloak role mappers (`realm roles`, `client roles`) as fallback in the template alongside the Tide-specific mapper. VERIFIED (learning-batch-004, L-06).
+Use `tidecloak-dev` for standard development. It has built-in ORK/threshold defaults and does not need `KC_HOSTNAME`, `SYSTEM_HOME_ORK`, `USER_HOME_ORK`, `THRESHOLD_T`, `THRESHOLD_N`, or `PAYER_PUBLIC`. Use `tidecloak-stg-dev` only when testing against pre-release Tide features.
+**Do not append `start-dev` or any command** to `docker run`. TideCloak images have a pre-configured entrypoint — appending `start-dev` (a vanilla Keycloak convention) breaks Tide initialization. See AP-39.
+### Dev image docker run (tidecloak-dev)
+```bash
+sudo docker run -d --name tidecloak \
+  -v ./data:/opt/keycloak/data/h2 \
+  -p 8080:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=password \
+  tideorg/tidecloak-dev:latest
+```
+### Staging image docker run (tidecloak-stg-dev)
+```bash
+sudo docker run -d --name tidecloak \
+  -v ./data:/opt/keycloak/data/h2 \
+  -p 8080:8080 \
+  -e KC_BOOTSTRAP_ADMIN_USERNAME=admin \
+  -e KC_BOOTSTRAP_ADMIN_PASSWORD=password \
+  -e KC_HOSTNAME=http://localhost:8080 \
+  -e SYSTEM_HOME_ORK=https://sork1.tideprotocol.com \
+  -e USER_HOME_ORK=https://sork1.tideprotocol.com \
+  -e THRESHOLD_T=3 \
+  -e THRESHOLD_N=5 \
+  -e PAYER_PUBLIC=20000011d6a0e8212d682657147d864b82d10e92776c15ead43dcfdc100ebf4dcfe6a8 \
+  tideorg/tidecloak-stg-dev:latest
+```
+---
+## Required Environment Variables
+### Core (both images)
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `KC_BOOTSTRAP_ADMIN_USERNAME` | Initial admin user | `admin` |
+| `KC_BOOTSTRAP_ADMIN_PASSWORD` | Initial admin password | `password` |
+### Tide protocol (staging image only — tidecloak-stg-dev)
+The dev image (`tidecloak-dev`) has these built in. Only set these for `tidecloak-stg-dev`.
+| Variable | Purpose | Example |
+|----------|---------|---------|
+| `KC_HOSTNAME` | Public-facing URL | `http://localhost:8080` |
+| `SYSTEM_HOME_ORK` | Tide network entry point | `https://sork1.tideprotocol.com` |
+| `USER_HOME_ORK` | User-facing ORK URL | `https://sork1.tideprotocol.com` |
+| `THRESHOLD_T` | Signing threshold | `3` |
+| `THRESHOLD_N` | Total ORK nodes | `5` |
+| `PAYER_PUBLIC` | Payer ORK public key | hex string |
+**Anti-pattern:** Omitting Tide env vars. Without `SYSTEM_HOME_ORK`, `USER_HOME_ORK`, `THRESHOLD_T`, `THRESHOLD_N`, and `PAYER_PUBLIC`, the Tide IdP provider does not initialize. Required actions like `link-tide-account-action` never register, and the init script fails with "Could not find configuration for Required Action". VERIFIED.
+---
+## Initialization Sequence
+Order matters. Do not skip or reorder steps.
+| # | Step | API / action | Produces |
+|---|------|-------------|----------|
+| 1 | Clean previous state | `docker rm`, clear `data/keycloakdb*`, `chown 1000:1000 data/` | Clean slate |
+| 2 | Start container | `docker run` with correct image + env vars | Running TideCloak |
+| 3 | Wait for readiness | Poll `GET /` until 200 | Reachable server |
+| 4 | Get master admin token | `POST /realms/master/protocol/openid-connect/token` | Bearer token |
+| 5 | Create realm | `POST /admin/realms` with realm.json template | Realm + client |
+| 6 | Initialize Tide + enable IGA | `POST /admin/realms/{realm}/vendorResources/setUpTideRealm` then `POST /admin/realms/{realm}/tide-admin/toggle-iga` | License activated, VRK generated, IGA enabled |
+| 7 | Approve client + role change requests | `sign` + `commit` on `/tide-admin/change-set/clients/requests` AND `/roles/requests`. **Roles must be approved here** — `setUpTideRealm` creates `tide-realm-admin` as a draft when IGA is enabled. Without approval, role lookups in Step 8c fail. | Client config + roles committed |
+| 8 | Create admin user | `POST /admin/realms/{realm}/users` | User creation change request created |
+| 8b | Approve user creation | `sign` + `commit` on `/tide-admin/change-set/users/requests` | User queryable. **Must happen before role assignment.** |
+| 8c | Assign tide-realm-admin role | Assign `tide-realm-admin` client role on `realm-management`. Validate role lookup returns a role, not an error. | Admin user has role |
+| 9 | Generate invite link | `POST /tideAdminResources/get-required-action-link` with `["link-tide-account-action"]` | URL for admin to link Tide account |
+| 10 | Wait for account linking | Poll user `tideUserKey` attribute until non-empty | Admin has Tide identity |
+| 11 | Approve role assignment change requests | `sign` + `commit` on `/tide-admin/change-set/users/requests` and `/roles/requests` | Admin roles committed |
+| 12 | Update CustomAdminUIDomain | `PUT /identity-provider/instances/tide` then `POST /vendorResources/sign-idp-settings` | Enclave approval popups work from app origin |
+| 13 | Export adapter JSON | `GET /vendorResources/get-installations-provider?clientId={uuid}&providerId=keycloak-oidc-keycloak-json` | `tidecloak.json` with `jwk`, `vendorId`, `homeOrkUrl` |
+---
+## Critical Endpoint Details
+### setUpTideRealm
+- Path: `POST /admin/realms/{realm}/vendorResources/setUpTideRealm`
+- Content-Type: `application/x-www-form-urlencoded` (NOT JSON)
+- Body: `email=admin@yourorg.com` (required, URL-encoded)
+- Handles license activation automatically. No manual "Manage License" step needed.
+**Anti-pattern:** Using `/tide-admin/setUpTideRealm`. Wrong path. Returns 404. VERIFIED.
+**Anti-pattern:** Sending JSON to this endpoint. Causes "Could not create tide realm" (`email is null or empty`). VERIFIED.
+### toggle-iga
+- Path: `POST /admin/realms/{realm}/tide-admin/toggle-iga`
+- Content-Type: `application/x-www-form-urlencoded`
+- Body: `isIGAEnabled=true`
+### Approve/commit change requests
+- Sign: `POST /admin/realms/{realm}/tide-admin/change-set/sign`
+- Commit: `POST /admin/realms/{realm}/tide-admin/change-set/commit`
+- Both accept JSON: `{ "changeSetId": "...", "changeSetType": "...", "actionType": "..." }`
+- For batch: use `/sign/batch` and `/commit/batch` with `{ "changeSets": [...] }`
+### Adapter config export
+- Path: `GET /admin/realms/{realm}/vendorResources/get-installations-provider`
+- Query: `clientId={uuid}&providerId=keycloak-oidc-keycloak-json`
+- The `jwk` field is only present when IGA is enabled.
+---
+## Realm Template Requirements
+The realm.json template must include ALL of the following. Missing any section causes silent failures.
+| Section | Required for | Failure if missing |
+|---------|-------------|-------------------|
+| `requiredActions` with `link-tide-account-action` | Admin invite links | Invite link generation fails |
+| `authenticationFlows` with `tidebrowser` | Tide login flow | Login uses default Keycloak flow, not Tide |
+| `authenticatorConfig` with `defaultProvider: tide` | IdP redirect | Users not redirected to Tide IdP |
+| `browserFlow: "tidebrowser"` | Flow binding | Auth flow not activated |
+| `protocolMappers` (Tide User Key, IGA Role Mapper, vuid) | JWT claims | Missing `tideuserkey`, `vuid`, roles in tokens |
+| `components` (user profile) | User attributes | Attribute storage fails |
+| `roles.realm` with `_tide_enabled` in default composite | Voucher system | Users cannot perform Tide operations |
+| `UPDATE_PASSWORD` disabled | Tide auth model | Password update prompt conflicts with PRISM |
+**Anti-pattern:** Creating a minimal realm.json. Every section above is mandatory. VERIFIED.
+**Anti-pattern:** Including `identityProviders` in realm template when `setUpTideRealm` runs after import. `setUpTideRealm` creates the Tide IDP internally. A duplicate `tide` IDP in the template causes `ModelDuplicateException`, which breaks licensing and prevents `tide-realm-admin` from being created. Remove `identityProviders` from the template. VERIFIED (LEARNINGS-batch-006 L-01).
+**Anti-pattern:** Placing `unmanagedAttributePolicy` at realm top level. Keycloak 26+ expects it inside `components.org.keycloak.userprofile.UserProfileProvider[0].config.kc.user.profile.config` as part of the embedded JSON string. Top-level placement causes HTTP 400 on import or silently drops `tideUserKey`/`vuid` attributes during account linking. VERIFIED (LEARNINGS-batch-006 L-02).
+**Duplicate default role warning**: TideCloak may create a duplicate default role during IGA-enabled realm setup (e.g., `default-roles-myapp-1` alongside `default-roles-myapp`). The duplicate is empty — new users assigned to it get none of the `_tide_*` voucher roles. After user creation, explicitly verify the user has `_tide_*` roles. If missing, assign them via admin API. With IGA enabled, role assignment change-sets require browser enclave approval (`requiresApprovalPopup: true`). VERIFIED (learning-batch-004, L-08).
+### Manual realm creation (without template)
+If creating a realm without the full template (e.g., `POST /admin/realms` with `{"realm":"myapp","enabled":true}`), you must manually register `link-tide-account-action`:
+```bash
+curl -X POST "$TIDECLOAK_URL/admin/realms/$REALM_NAME/authentication/register-required-action" \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"providerId":"link-tide-account-action","name":"Link Tide Account"}'
+```
+Without this, invite links redirect to VERIFY_PROFILE or the default login flow instead of Tide account linking. VERIFIED (session-001).
+### Admin user profile requirements
+When creating the admin user, always set `firstName` and `lastName`:
+```json
+{"username":"admin","email":"admin@yourorg.com","firstName":"Admin","lastName":"User","enabled":true}
+```
+If these fields are empty, TideCloak's `VERIFY_PROFILE` required action fires before the Tide account linking flow, blocking bootstrap. Alternatively, disable `VERIFY_PROFILE` as a default required action on the realm. VERIFIED (session-001).
+### Bootstrap script fail-fast rule
+The bootstrap/init script must check the HTTP status of every critical step and abort on failure. In particular:
+- Realm import (`POST /admin/realms`) must return 2xx. If it returns 400/409/500, stop. Do not continue to licensing or IGA.
+- `setUpTideRealm` must return 200. If it fails, the realm is unlicensed and all subsequent steps are invalid.
+**Anti-pattern:** Continuing bootstrap after realm import failure. Later steps (licensing, IGA, user creation) either fail silently or produce garbage state. Agent wastes multiple rounds debugging cascaded failures. VERIFIED (session-001).
+---
+## Data Directory Rules
+- Mount `./data:/opt/keycloak/data/h2`, never the project root.
+- Run `mkdir -p ./data && sudo chown -R 1000:1000 ./data` before starting.
+- Clear stale DB files between fresh setups: `sudo rm -f ./data/keycloakdb*`
+- Never mount a docker-compose named volume on a standalone `docker run`.
+**Failure mode:** Mounting `.:/opt/keycloak/data/h2` (project root) causes `AccessDeniedException` because Docker writes DB files as UID 1000. VERIFIED.
+**Failure mode:** Stale DB files cause "Could not open file keycloakdb.mv.db". VERIFIED.
+---
+## Dev vs Production Separation
+| Aspect | Dev (this canon) | Production |
+|--------|-----------------|------------|
+| Database | H2 embedded | External PostgreSQL (not documented — contact Tide) |
+| Image | `tidecloak-dev` (prod) or `tidecloak-stg-dev` (staging) | `tidecloak-dev` is production-grade |
+| Threshold | T=3/N=5 minimum | T=14/N=20 on live network |
+| SSL | `sslRequired: external` (HTTP on localhost OK) | HTTPS required everywhere |
+| Admin password | Hardcoded in script | Secret management system |
+| VRK keys | Per-environment, never shared | Per-environment, never shared |
+**Anti-pattern:** Using `THRESHOLD_T=1` in any environment. Single-ORK compromise breaks security. VERIFIED.
+**Anti-pattern:** Sharing VRK keys between environments. Breaks rotation lifecycle. VERIFIED.
+---
+## Verification
+Bootstrap is complete when:
+- [ ] TideCloak container running, `curl http://localhost:8080` returns 200
+- [ ] Realm exists with Tide IdP configured
+- [ ] IGA is enabled
+- [ ] Admin user has `tide-realm-admin` client role on `realm-management`
+- [ ] Admin has linked their Tide account (`tideUserKey` attribute non-empty)
+- [ ] All bootstrap change requests approved and committed
+- [ ] CustomAdminUIDomain set to app origin
+- [ ] Adapter JSON exported with `jwk`, `vendorId`, `homeOrkUrl` fields present