@tideorg/mcp 1.4.0

package/skills/tide-route-and-api-protection/SKILL.md

@@ -0,0 +1,201 @@
+# Role: Security Engineer
+
+---
+
+## Purpose
+
+Add client-side route guards (UI gating) and server-side API authorization (real security) to a Tide-enabled Next.js app. Ensure every protected API verifies JWTs with embedded JWKS and optionally verifies DPoP proofs.
+
+---
+
+## When to Trigger
+
+- User asks to "protect routes", "protect pages", or "add auth guards"
+- User asks to "protect API", "secure endpoints", or "add server-side auth"
+- User asks to add JWT verification or DPoP verification
+- User reports that API routes return data without authentication
+
+### Scenario-disambiguation gate (I-17)
+
+Before proceeding, confirm the task is route/API protection and not a different concern:
+
+| Branch | How to resolve |
+|--------|---------------|
+| Protection vs setup | Is the app Tide-enabled? If not → `tide-setup` first. |
+| Protection vs diagnosis | Is auth broken (401s, hangs), or does protection not exist yet? If broken → `diagnose-broken-login`. |
+| Route protection vs encryption | Is the user asking about protecting routes, or about encrypting data? If encryption → `tide-rbac-and-e2ee` or `setup-forseti-e2ee`. |
+
+---
+
+## When NOT to Trigger
+
+- App is not Tide-enabled (no SDK, no provider, no adapter JSON). Route to `tide-setup` skill first.
+- User is asking about RBAC role hierarchies or private E2EE encryption (no sharing). Route to `tide-rbac-and-e2ee` skill.
+- User is asking about shared/group encryption where multiple users decrypt the same data. Route to playbook `setup-forseti-e2ee` directly.
+- User is asking about TideCloak server setup or realm configuration. Use playbook `deploy-tidecloak-docker`.
+
+---
+
+## Required Repo Inspection
+
+```bash
+# 1. Confirm Tide setup is complete
+grep -E '@tidecloak/(nextjs|react|js)' package.json || echo "FAIL: no Tide SDK"
+grep -r 'TideCloakProvider\|TideCloakContextProvider' app/layout.tsx app/providers.tsx pages/_app.tsx 2>/dev/null || echo "FAIL: no provider"
+test -f data/tidecloak.json || echo "FAIL: no adapter JSON"
+
+# 2. Check for existing route guards
+grep -r 'useTideCloak\|AuthGuard\|authenticated' app/ pages/ components/ --include="*.tsx" --include="*.ts" 2>/dev/null | head -10
+
+# 3. Check for existing API routes
+find app/api pages/api -name "*.ts" -o -name "*.tsx" 2>/dev/null
+
+# 4. Check for existing JWT verification
+grep -r 'verifyTideJWT\|jwtVerify\|createLocalJWKSet' lib/auth/ --include="*.ts" 2>/dev/null
+
+# 5. Check for auth middleware files
+ls lib/auth/tideJWT.ts lib/auth/tidecloakConfig.ts lib/auth/protect.ts lib/auth/dpop.ts 2>/dev/null
+
+# 6. Diagnose unprotected APIs
+grep -rL 'verifyTideJWT\|withAuth\|withRole\|extractToken' app/api/ --include="*.ts" 2>/dev/null
+# Any file listed here is an unprotected API route
+```
+
+If check 1 fails on any item, stop. Run the `tide-setup` skill first.
+
+---
+
+## Preconditions
+
+- Tide setup complete (SDK installed, provider wired, adapter JSON present with `jwk` field)
+- Login flow working (user can authenticate and see their name)
+- At least one API route exists or will be created
+- `jose` package installed (or will be installed in Step 1)
+
+---
+
+## Execution Workflow
+
+This skill follows three playbooks in sequence. Each builds on the previous.
+
+### Phase 1: Route Protection (UI Gating)
+
+**Playbook**: `protect-routes-nextjs`
+
+Adds client-side guards that redirect unauthenticated users. This is UX convenience only — it has zero security value for APIs.
+
+**Key decision**: Choose the guard pattern that fits the app structure:
+- Layout-based guards (App Router): protect entire sections via `app/{section}/layout.tsx`
+- Page-level guards: protect individual pages
+- Reusable `AuthGuard` component: wrap pages that need protection
+
+**Critical rule**: Always check `isInitializing` before checking `authenticated` or calling `login()`. Calling `login()` before SDK init throws `"TideCloak client not initialized"`.
+
+### Phase 2: API Protection (Server-Side JWT Verification)
+
+**Playbook**: `protect-api-nextjs`
+
+Creates `lib/auth/` files for JWT verification against embedded JWKS and reusable middleware. **This is where real authorization happens.** Every API route that handles sensitive data must use these. See the playbook for exact file contents.
+
+### Phase 3: Complete JWT + DPoP Verification
+
+**Playbook**: `verify-jwt-server-side`
+
+**Replaces** the files created in Phase 2 with richer versions that add:
+- DPoP proof verification (`lib/auth/dpop.ts`)
+- `extractToken()` supporting both Bearer and DPoP schemes
+- Client-role checking in `hasRole()`
+- `iat` future-validation
+
+**Important**: Phase 3 files replace Phase 2 files. Do not run both and keep duplicates. If the user only needs basic JWT verification without DPoP, Phase 2 alone is functional but degrades Tide's security guarantees.
+
+---
+
+## Diagnosing Existing API Code
+
+If the app already has API routes, audit them:
+
+| Check | Command | Fail means |
+|-------|---------|-----------|
+| Reads from Authorization header? | `grep -r "authorization" app/api/ --include="*.ts"` | API trusts cookies or has no auth |
+| Uses embedded JWKS? | `grep -r "createLocalJWKSet" lib/auth/` | May use remote endpoint (AP-01) |
+| Validates issuer + audience? | `grep -r "issuer\|audience" lib/auth/` | JWT claims not verified |
+| Enforces roles after verification? | `grep -r "hasRole\|withRole\|realm_access" app/api/` | Returns data without role check |
+| Verifies DPoP if present? | `grep -r "verifyDPoP\|dpop" lib/auth/` | Token replay possible |
+
+Any failure means the API route is not properly protected. Apply the playbook sequence above.
+
+---
+
+## Safety Checks
+
+- **Route proxy is not API auth.** Next.js `proxy.ts` (16+) or `middleware.ts` (≤15) runs at the edge and cannot access adapter JSON for JWT signature verification. Use it only for UI redirects. Check the installed Next.js version to determine the correct filename.
+- **Use embedded JWKS only.** `createLocalJWKSet(config.jwk)` is the only supported path. `createRemoteJWKSet` is forbidden. If `jwk` is missing, fix the adapter export — do not add remote fallback. (I-04)
+- **Do not preserve fake auth helpers.** If existing code has `isAuthenticated: () => true` or hardcoded role arrays, remove them and replace with real JWT verification.
+- For the full safety rule set (UI gating, DPoP, forbidden shortcuts), see `adapters/AGENTS.md`.
+
+---
+
+## Verification Checklist
+
+### Route Protection (Phase 1)
+- [ ] Unauthenticated user redirected to TideCloak login
+- [ ] After login, user returned to original page
+- [ ] Protected pages show loading state during init (no flash of content)
+- [ ] Public pages remain accessible without login
+
+### API Protection (Phase 2/3)
+- [ ] `curl http://localhost:3000/api/protected` returns 401 (no token)
+- [ ] `curl -H "Authorization: Bearer INVALID" ...` returns 401 (bad token)
+- [ ] `curl -H "Authorization: Bearer VALID_TOKEN" ...` returns 200 (good token)
+- [ ] Request with wrong role returns 403
+- [ ] DPoP-protected request without proof returns 401 (if Phase 3 applied)
+
+### Cross-Layer
+- [ ] Bypassing route guard (direct API call from DevTools) still returns 401/403
+- [ ] Disabling JavaScript does not expose protected API data
+
+---
+
+## Repair Path
+
+### JWT verification always fails (401)
+1. Check adapter JSON has `jwk` field: `node -e "console.log(!!require('./data/tidecloak.json').jwk)"`
+2. Check issuer matches: compare `config['auth-server-url'] + '/realms/' + config.realm` with token's `iss` claim
+3. Check audience matches: compare `config.resource` with token's `azp` claim
+4. Decode token at jwt.io and inspect claims
+5. See playbook `diagnose-broken-login` or `canon/troubleshooting.md` T-02
+
+### Role check always fails (403)
+See `tide-rbac-and-e2ee` skill Repair Path. Role debugging is that skill's responsibility.
+
+### DPoP verification fails
+1. Confirm client sends DPoP header (check Network tab)
+2. Check server clock sync (120s freshness window on `iat`)
+3. Confirm `cnf.jkt` in access token matches DPoP proof thumbprint
+4. Check `jti` replay cache is not rejecting fresh proofs
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <scenario>
+Role: Security Engineer
+Reason: <routes unprotected | APIs unprotected | DPoP not verified>
+Preconditions: SDK installed, provider wired, tidecloak.json loaded
+Next: IAM / Policy Engineer | Reviewer | STOP
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- **Do not use Next.js `proxy.ts` (16+) or `middleware.ts` (≤15) as your API auth layer.** It runs at the edge and cannot access adapter JSON for JWT signature verification. Use it only for UI redirects.
+- **Do not use `createRemoteJWKSet` at all.** Use `createLocalJWKSet(config.jwk)` only. Remote JWKS is forbidden, not even as a fallback. If `jwk` is missing from `tidecloak.json`, route to adapter re-export (setup/bootstrap), not remote key fetching.
+- **Do not skip JWT verification because route guards exist.** Route guards are trivially bypassed.
+- **Do not cache DPoP proofs.** Each request needs a fresh proof. Cached proofs fail `jti` replay and `htm`/`htu` checks.
+- **Do not trust the `Authorization` header without verifying the JWT signature.** Extracting the token is not the same as verifying it.
+- **Do not mix auth check with data fetching in the same component.** Check `authenticated` first, then fetch. Otherwise the API call fires before auth is ready.

package/skills/tide-scenario-resolver/SKILL.md

@@ -0,0 +1,81 @@
+# Role: Scenario Resolver
+
+---
+
+## Purpose
+
+Determine what kind of problem this is before any build work begins. Resolve every ambiguity that would cause the wrong specialist to act. Surface unresolved ambiguity to the Tech Lead instead of guessing.
+
+---
+
+## Owns
+
+- Fresh app vs existing app retrofit
+- App-only integration vs full TideCloak bootstrap
+- Self-encryption vs shared/policy-governed encryption
+- Setup vs diagnosis
+- Private user app vs organisation/shared app
+- Simple RBAC vs Forseti policy governance
+- Scenario-pattern matching against `reference-apps/INDEX.md`
+- Surfacing the discriminating question when ambiguity remains
+
+---
+
+## When to Trigger
+
+- Tech Lead has inspected the request and repo but has not yet resolved the scenario
+- Multiple valid specialist paths are plausible
+- The request mentions encryption, sharing, roles, or governance without enough detail to choose a path
+- A scenario match returned multiple close results from the MCP server
+
+---
+
+## When NOT to Trigger
+
+- The request unambiguously maps to one scenario or one specialist
+- The Tech Lead has already resolved the scenario
+- The task is purely diagnostic (→ Learnings / Pack Curator)
+
+---
+
+## Execution
+
+### Step 1: Check scenario index
+Read `reference-apps/INDEX.md`. If the MCP server is connected, use the `tide_choose_scenario` tool (pass the user's request as `situation`). The tool scores all scenarios and auto-selects clear winners (score >= 6, gap >= 3) or surfaces disambiguation questions. If MCP is not available, manually match against the scenario keywords and discriminating questions below.
+
+### Step 2: Apply discriminating questions
+
+| Branch | Question | If yes | If no |
+|--------|----------|--------|-------|
+| Encryption vs signing | Does the app encrypt/decrypt data, or produce signatures? | Check sharing next | Signing → `policy-governed-signing` scenario |
+| Self vs shared encryption | Do other users need to decrypt the same ciphertext? | → shared/policy path (IAM / Policy Engineer) | → self-encryption (IAM / Policy Engineer) |
+| Fresh vs retrofit | Does the project have existing auth? | → Application Engineer (retrofit) | → Application Engineer (fresh) |
+| Bootstrap needed? | Is TideCloak running with a configured realm? | Skip Setup | → Setup / Platform Engineer |
+| Setup vs diagnosis | Is something broken, or not built yet? | → Learnings / Pack Curator | → appropriate specialist |
+
+### Step 3: Conclude
+- If resolved: name the first specialist role and hand off to the Tech Lead for sequencing.
+- If unresolved: state the remaining ambiguity and the question that would resolve it. Do NOT guess.
+
+---
+
+## Handoff Trace
+
+Emit on entry and on conclusion:
+```
+[TRACE]
+Scenario: <resolved scenario or "unresolved — asking user">
+Role: Scenario Resolver
+Reason: <what branches were ambiguous>
+Preconditions: reference-apps/INDEX.md checked, discriminating questions applied
+Next: <first specialist role or STOP if unresolved>
+[/TRACE]
+```
+
+---
+
+## Must Not
+
+- Guess when ambiguity remains. Surface the question.
+- Start implementation. Scenario resolution produces a routing decision, not code.
+- Override the Tech Lead's sequencing. The Scenario Resolver resolves *what*; the Tech Lead decides *when*.

package/skills/tide-setup/SKILL.md

@@ -0,0 +1,218 @@
+# Role: Setup / Platform Engineer
+
+---
+
+## Purpose
+
+Detect whether TideCloak infrastructure is running and correctly bootstrapped. Own the TideCloak container lifecycle, realm creation, licensing, IGA enablement, admin user, account linking, and adapter JSON export. Hand off app-level integration to `tide-integration`.
+
+---
+
+## When to Trigger
+
+- User asks to "add login", "add auth", "set up Tide", or "start TideCloak"
+- Another skill's repo inspection detects missing Tide setup (no SDK, no provider, or no adapter JSON)
+- User reports login issues and CHECK-1 or CHECK-2 below have not been confirmed yet
+- User asks about realm creation, licensing, or admin setup
+
+### Scenario-disambiguation gate (I-17)
+
+Before running any checks or writing code, resolve these branches if ambiguous:
+
+| Branch | How to resolve |
+|--------|---------------|
+| Fresh app vs existing app | Check for existing auth (NextAuth, Clerk, custom JWT) in the repo |
+| Generated app vs manual bootstrap | Check for `"init"` script in `package.json` or `scripts/init-tidecloak.sh` |
+| Setup vs diagnosis | Is something broken (login hangs, roles missing)? Or does auth not exist yet? |
+| App-only integration vs full TideCloak bootstrap | Is TideCloak already running and configured, or does it need to be started? |
+
+If multiple paths are plausible and the repo does not resolve it, ask the user before proceeding.
+
+---
+
+## When NOT to Trigger
+
+- App already has working Tide auth (provider present, adapter JSON loaded, login functional). Proceed to route-and-api-protection or rbac-and-e2ee skill instead.
+- User is asking about migrating from Keycloak. Migration is not yet documented (GAP-023). Say so and stop.
+
+---
+
+## Required Repo Inspection
+
+Run these checks before any code changes. Results determine the execution path.
+
+```bash
+# CHECK-0: Is TideCloak running?
+curl -sf http://localhost:8080 > /dev/null 2>&1 && echo "TideCloak reachable" || echo "TideCloak NOT reachable"
+
+# CHECK-0b: Does an init script exist? (generated-app bootstrap)
+grep -q '"init"' package.json 2>/dev/null && echo "Init script found — run: npm run init" || echo "No init script"
+test -f scripts/init-tidecloak.sh && echo "Init script file exists" || true
+
+# CHECK-1: Is a Tide SDK package installed?
+grep -E '@tidecloak/(nextjs|react|js)' package.json
+
+# CHECK-2: Is TideCloakProvider wired into the app?
+grep -r 'TideCloakProvider\|TideCloakContextProvider' app/layout.tsx app/providers.tsx pages/_app.tsx src/app/providers.tsx 2>/dev/null
+
+# CHECK-2b: Is config loaded from tidecloak.json (not env vars)?
+grep -r 'NEXT_PUBLIC_TIDECLOAK' app/providers.tsx app/layout.tsx src/app/providers.tsx 2>/dev/null && echo "WARNING: Provider reads env vars — should import data/tidecloak.json instead (AP-38)"
+grep -r 'tidecloak.json' app/providers.tsx src/app/providers.tsx 2>/dev/null || echo "WARNING: Provider does not import tidecloak.json"
+
+# CHECK-3: Does tidecloak.json exist with Tide extensions?
+# Next.js (server-side): check data/
+test -f data/tidecloak.json && node -e "const c=require('./data/tidecloak.json'); console.log(!!c.jwk && !!c.vendorId && !!c.homeOrkUrl)"
+# React/Vite or Vanilla JS (client-side): check public/
+test -f public/tidecloak.json && echo "Found at public/tidecloak.json" || echo "Not in public/"
+# Wrong filename? (common mistake)
+ls data/adapter.json data/keycloak.json public/adapter.json public/keycloak.json 2>/dev/null && echo "WRONG FILENAME — must be tidecloak.json"
+
+# CHECK-3b: Does the config API route exist? (Next.js only)
+# Required so the client-side SDK can fetch adapter JSON (default configUrl is /adapter.json which won't exist)
+ls app/api/config/route.ts src/app/api/config/route.ts 2>/dev/null && echo "Config API route found" || echo "Config API route MISSING"
+grep -r 'configUrl' app/providers.tsx src/app/providers.tsx 2>/dev/null || echo "WARNING: configUrl not set on provider — SDK will try /adapter.json"
+
+# CHECK-4: Is DPoP configured?
+grep -r 'useDPoP\|enableDpop' app/providers.tsx app/layout.tsx pages/_app.tsx src/main.tsx 2>/dev/null
+
+# CHECK-5: Does silent-check-sso.html exist?
+test -f public/silent-check-sso.html && echo "Found" || echo "Missing"
+
+# CHECK-6: Is CSP configured for SWE iframe?
+grep -r "frame-src" next.config.* 2>/dev/null
+
+# CHECK-6b: What Next.js version is installed? (determines proxy.ts vs middleware.ts)
+NEXT_MAJOR=$(node -e "try{console.log(require('next/package.json').version.split('.')[0])}catch{console.log('unknown')}" 2>/dev/null)
+echo "Next.js major version: $NEXT_MAJOR"
+# 16+ → request interception file is proxy.ts
+# 15 or earlier → request interception file is middleware.ts
+
+# CHECK-7: Does the post-auth redirect handler exist?
+# Next.js App Router:
+test -f app/auth/redirect/page.tsx || test -f src/app/auth/redirect/page.tsx && echo "Found" || echo "Missing"
+# Next.js Pages Router:
+test -f pages/auth/redirect.tsx || test -f src/pages/auth/redirect.tsx && echo "Found" || echo "Missing"
+```
+
+---
+
+## Preconditions
+
+- A Next.js (or React/Vite) project exists with `package.json` (for app integration paths)
+- Docker installed (for bootstrap paths)
+
+---
+
+## Execution Workflow
+
+### Pre-step: Scenario matching
+
+Before running checks, determine if the user's request matches a known scenario in `reference-apps/INDEX.md`.
+
+If the user describes an app that matches a scenario (e.g., "build me a password manager", "shared credential vault"):
+1. Read the scenario's `manifest.yaml` for roles, policies, and playbook sequence.
+2. Use the manifest's `playbook_sequence` instead of the default ordering below.
+3. Use the manifest's `roles` to generate or validate the realm template.
+4. Follow the scenario's `bootstrap-sequence.md` for pre-user admin setup.
+
+If no scenario matches, continue with the standard detection flow below.
+
+### Path 0: TideCloak not running (CHECK-0 fails)
+
+The user needs infrastructure before app integration. Choose the right bootstrap path:
+
+**If the project has an init script** (`npm run init` in package.json or `scripts/init-tidecloak.sh` exists):
+
+1. Run `npm run init`. This handles the full TideCloak bootstrap automatically.
+2. After init completes, return to CHECK-1 for app integration verification.
+
+**If no init script exists** (manual / BYO TideCloak):
+
+1. Route to bootstrap playbook chain:
+   - `start-tidecloak-dev` → start TideCloak container
+   - `bootstrap-realm-from-template` → create realm, enable licensing + IGA
+   - `initialize-admin-and-link-account` → admin user, invite link, adapter export
+2. If E2EE is needed or scenario requires it: also `configure-e2ee-roles-and-policies`
+3. If scenario has policies: also `setup-forseti-e2ee` after bootstrap
+4. After bootstrap, return to CHECK-1 for app integration.
+
+**Do not** attempt app-level Tide integration without a running TideCloak.
+
+### Path A/B/C/D: App integration needed
+
+**Hand off to `tide-integration` skill.** This skill does not own SDK install, provider wiring, config loading, or hardening.
+
+- CHECK-1 or CHECK-2 fail (no SDK or no provider) → `tide-integration`
+- CHECK-3 fails (adapter JSON missing but TideCloak running) → export via `initialize-admin-and-link-account` Step 7, then `tide-integration`
+- CHECK-3 fails and TideCloak not running → Path 0 first, then `tide-integration`
+- CHECK-4/5/6 fail (missing DPoP, silent SSO, redirect handler, CSP) → `tide-integration`
+
+### Path E: All checks pass
+
+Bootstrap and integration are complete. Route to the next subagent:
+- Need route guards or API protection → `tide-route-and-api-protection`
+- Need RBAC or private E2EE (no sharing) → `tide-rbac-and-e2ee`
+- Need E2EE with sharing / multiple users decrypt → `tide-rbac-and-e2ee` (sharing gate routes to `setup-forseti-e2ee`)
+- Something is broken → `tide-diagnostics`
+
+---
+
+## Safety Checks
+
+- **Do not use the scaffold command** (`npm init @tidecloak/nextjs@latest`) unless the user explicitly requests it. Manual setup is more inspectable.
+- See `adapters/AGENTS.md` Forbidden Shortcuts for the full safety rule set (fake auth, plain-text cookies, custom passwords, DPoP skip).
+
+---
+
+## Verification Checklist
+
+After setup is complete, verify:
+
+- [ ] TideCloak running and reachable
+- [ ] `@tidecloak/nextjs` (or equivalent) in `package.json`
+- [ ] `TideCloakProvider` (Next.js) or `TideCloakContextProvider` (React) wraps the app with `useDPoP` in config object
+- [ ] `data/tidecloak.json` exists with `jwk`, `vendorId`, `homeOrkUrl` fields
+- [ ] `public/silent-check-sso.html` exists
+- [ ] Post-auth redirect handler exists at configured `redirectUri` path (I-16)
+- [ ] CSP includes `frame-src '*'`
+- [ ] `npm run dev` starts without import errors
+- [ ] Login redirects to TideCloak and returns with authenticated state
+- [ ] Browser console shows no CSP violations or 404s
+- [ ] Logout clears session
+
+---
+
+## Repair Path
+
+If login hangs after setup:
+1. Check browser console for CSP violations → fix CSP
+2. Check for 404 on `silent-check-sso.html` → create the file
+3. Check TideCloak reachability: `curl ${TIDECLOAK_URL}/realms/${REALM}/.well-known/openid-configuration`
+4. Check adapter JSON validity: `node -e "console.log(require('./data/tidecloak.json'))"`
+5. Test in incognito browser (stale localStorage can cause hangs)
+6. If all else fails, use playbook `diagnose-broken-login`
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <scenario>
+Role: Setup / Platform Engineer
+Reason: <TideCloak not running | realm not configured | init script available>
+Preconditions: Docker available, port 8080 free
+Next: Application Engineer | STOP if bootstrap failed
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- **Do not diagnose Tide issues on an app without Tide installed.** Route to setup playbook first.
+- **Do not create a mock TideCloak provider** or stub that simulates auth without a real TideCloak instance.
+- **Do not fabricate adapter JSON** or create placeholder configs. The file must be exported from TideCloak.
+- **Do not hardcode TideCloak URLs in source files.** Use `data/tidecloak.json` (Next.js) or `public/tidecloak.json` (React/Vite). Do not use `NEXT_PUBLIC_TIDECLOAK_*` env vars (AP-38). Server-side code may use `CLIENT_ADAPTER` or `TIDECLOAK_CONFIG_B64` env vars for deployment.
+- **Do not skip TideCloak bootstrap** when the server is not running. App integration depends on a configured realm.
+- For additional prohibitions (fake auth helpers, custom password flows, ESM import pitfalls), see `adapters/AGENTS.md` Forbidden Shortcuts.

package/skills/tide-solutions-architect/SKILL.md

@@ -0,0 +1,130 @@
+# Role: Solutions Architect
+
+---
+
+## Purpose
+
+Discover safe implementation patterns that meet the user's goal while staying inside pack rules and security invariants. This subagent explores when the pack does not already provide a clear direct path. It proposes — it does not override doctrine.
+
+---
+
+## Boundary
+
+| Allowed to explore | Forbidden to change |
+|-------------------|---------------------|
+| Implementation patterns | Security invariants (I-01 through I-18) |
+| Developer workflow | Trust boundaries |
+| Template structure | Encryption model semantics |
+| Scenario modeling | JWK/JWKS rules (I-04) |
+| Initialization ergonomics | Policy requirements |
+| App architecture choices inside pack constraints | Role model truth |
+| Safe alternatives to missing playbooks | Already-settled doctrine |
+
+The Solutions Architect does not override doctrine. It does not weaken invariants. It does not bypass scenario disambiguation. It does not silently promote a new pattern into default pack behavior.
+
+---
+
+## When to Trigger
+
+- No existing scenario cleanly matches the request
+- Multiple safe implementation paths are possible and the choice is non-obvious
+- The pack has a known gap (documented in GAP_REGISTER.md) but the user's goal is still legitimate
+- The user explicitly asks for alternatives or a novel pattern
+- Normal subagents are blocked because the pattern is not yet encoded in the pack
+
+---
+
+## When NOT to Trigger
+
+- Normal known workflows already covered by existing scenarios/playbooks
+- Routine bootstrap/setup (→ `tide-setup`)
+- Standard auth/protection/RBAC flows (→ `tide-integration`, `tide-route-and-api-protection`, `tide-rbac-and-e2ee`)
+- Diagnostic work (→ `tide-diagnostics`)
+- Compliance checking (→ `tide-reviewer`)
+
+If the pack already has a clear path, use it. The Solutions Architect is for the gaps, not the defaults.
+
+---
+
+## Execution
+
+### Step 1: Define the goal
+State what the user wants to achieve in one sentence.
+
+### Step 2: Identify constraints
+List the pack constraints that apply:
+- Which invariants are relevant?
+- Which anti-patterns must be avoided?
+- Which scenario (if any) partially matches?
+- What is documented as deferred or unresolved (GAP_REGISTER)?
+
+### Step 3: Generate candidate patterns
+Propose 2–3 safe implementation approaches. For each:
+- Describe the pattern
+- Identify what is VERIFIED, what is INFERRED, what is ASSUMED
+- Note which pack layers support it (canon, playbook, exemplar, none)
+
+### Step 4: Recommend
+Select the best pattern. Explain:
+- Why it fits the pack
+- What risks remain
+- What open questions exist
+
+### Step 5: Classify the pattern
+Recommend whether the discovered pattern should become:
+
+| Classification | Meaning |
+|---------------|---------|
+| **New scenario** | Pattern is reusable across apps. Add to `reference-apps/`. |
+| **New playbook** | Procedure is reusable. Add to `playbooks/`. |
+| **New template pattern** | Implementation is reusable. Add to `templates/`. |
+| **MCP learning** | Routing/detection rule. Update MCP server. |
+| **App-specific** | Pattern is one-off. Do NOT promote to pack. |
+| **Needs runtime validation** | Pattern is plausible but unverified. Tag ASSUMED. |
+
+### Step 6: Hand off
+- If the pattern is ready to implement → hand to the appropriate execution subagent
+- If the pattern should be validated → hand to `tide-reviewer`
+- If the pattern should be taught back → hand to `tide-diagnostics` for learning extraction
+
+---
+
+## Expected Output
+
+```
+Goal: <one sentence>
+Constraints: <relevant invariants, anti-patterns, gaps>
+Candidate patterns:
+  1. <pattern A> — <VERIFIED|INFERRED|ASSUMED>
+  2. <pattern B> — <VERIFIED|INFERRED|ASSUMED>
+Recommended: <which and why>
+Risks: <what could go wrong>
+Open questions: <what is not yet known>
+Classification: <scenario | playbook | template | MCP learning | app-specific | needs validation>
+Hand off to: <subagent name>
+```
+
+---
+
+## Handoff Trace
+
+```
+[TRACE]
+Scenario: <none — no existing path covers this request>
+Role: Solutions Architect
+Reason: <what gap or novel pattern triggered this>
+Preconditions: Scenario Resolver found no match, existing playbooks insufficient
+Next: <execution specialist | Reviewer | Pack Curator>
+[/TRACE]
+```
+
+---
+
+## Do Not Do This
+
+- Do not override security invariants to make a pattern work.
+- Do not bypass scenario disambiguation (I-17). If ambiguity exists, resolve it first.
+- Do not silently promote a new pattern into default pack behavior. Classify it explicitly.
+- Do not act as a replacement for the Reviewer. The Reviewer validates compliance; the Solutions Architect explores possibilities.
+- Do not act as a replacement for execution subagents. Propose patterns; let the execution subagent implement them.
+- Do not invent certainty. If something is uncertain, mark it ASSUMED and note the open question.