@tideorg/mcp 1.4.2 → 1.9.1

package/mcp-server/dist/server.js

@@ -162,13 +162,20 @@ const REFERENCE_APP_DIRS = listDirectories("reference-apps");
 export function createServer() {
     const server = new McpServer({
         name: "@tideorg/mcp",
-        version: "1.4.1",
+        version: "1.9.1",
     });
     // 1. List available content
-    server.tool("tide_list", "List all available content in the Tide agent pack by category", {
-        category: z
-            .enum(["canon", "playbooks", "skills", "prompts", "adapters", "scenarios", "all"])
-            .describe("Which category to list, or 'all' for everything"),
+    server.registerTool("tide_list", {
+        description: "List all available content in the Tide agent pack by category",
+        inputSchema: {
+            category: z
+                .enum(["canon", "playbooks", "skills", "prompts", "adapters", "scenarios", "all"])
+                .describe("Which category to list, or 'all' for everything"),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
     }, async ({ category }) => {
         const sections = {};
         if (category === "all" || category === "canon")
@@ -189,42 +196,83 @@ export function createServer() {
         return textResponse(text);
     });
     // 2. Read a specific canon file
-    server.tool("tide_canon", "Read a canon file (invariants, anti-patterns, concepts, framework-matrix, feature-mapping, troubleshooting, tidecloak-bootstrap, etc.)", { name: z.string().describe(`Canon file name. Available: ${CANON_FILES.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_canon", {
+        description: "Read a canon file (invariants, anti-patterns, concepts, framework-matrix, feature-mapping, troubleshooting, tidecloak-bootstrap, etc.)",
+        inputSchema: { name: z.string().describe(`Canon file name. Available: ${CANON_FILES.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         const content = readPackFile("canon", name);
         if (!content)
             return errorResponse(`Canon file '${name}' not found. Available: ${CANON_FILES.join(", ")}`);
         return textResponse(content);
     });
     // 3. Read a playbook
-    server.tool("tide_playbook", "Read a step-by-step playbook for a specific Tide task", { name: z.string().describe(`Playbook name. Available: ${PLAYBOOK_FILES.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_playbook", {
+        description: "Read a step-by-step playbook for a specific Tide task",
+        inputSchema: { name: z.string().describe(`Playbook name. Available: ${PLAYBOOK_FILES.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         const content = readPackFile("playbooks", name);
         if (!content)
             return errorResponse(`Playbook '${name}' not found. Available: ${PLAYBOOK_FILES.join(", ")}`);
         return textResponse(content);
     });
     // 4. Read a skill
-    server.tool("tide_skill", "Read a composable skill definition", { name: z.string().describe(`Skill name. Available: ${SKILL_DIRS.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_skill", {
+        description: "Read a composable skill definition",
+        inputSchema: { name: z.string().describe(`Skill name. Available: ${SKILL_DIRS.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         const content = readSkill(name);
         if (!content)
             return errorResponse(`Skill '${name}' not found. Available: ${SKILL_DIRS.join(", ")}`);
         return textResponse(content);
     });
     // 5. Read a prompt file
-    server.tool("tide_prompt", "Read a reusable starter prompt from the pack", { name: z.string().describe(`Prompt file name. Available: ${PROMPT_FILES.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_prompt", {
+        description: "Read a reusable starter prompt from the pack",
+        inputSchema: { name: z.string().describe(`Prompt file name. Available: ${PROMPT_FILES.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         const content = readPackFile("prompts", name);
         if (!content)
             return errorResponse(`Prompt '${name}' not found. Available: ${PROMPT_FILES.join(", ")}`);
         return textResponse(content);
     });
     // 6. Read an adapter file
-    server.tool("tide_adapter", "Read an adapter instruction file (AGENTS, CLAUDE, replit)", { name: z.string().describe(`Adapter file name. Available: ${ADAPTER_FILES.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_adapter", {
+        description: "Read an adapter instruction file (AGENTS, CLAUDE, replit)",
+        inputSchema: { name: z.string().describe(`Adapter file name. Available: ${ADAPTER_FILES.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         const content = readPackFile("adapters", name);
         if (!content)
             return errorResponse(`Adapter '${name}' not found. Available: ${ADAPTER_FILES.join(", ")}`);
         return textResponse(content);
     });
     // 7. List available scenarios
-    server.tool("tide_list_scenarios", "List all available scenario patterns under reference-apps/", async () => {
+    server.registerTool("tide_list_scenarios", {
+        description: "List all available scenario patterns under reference-apps/",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async () => {
         if (REFERENCE_APP_DIRS.length === 0)
             return textResponse("No scenarios found under reference-apps/");
         const lines = REFERENCE_APP_DIRS.map((name) => {
@@ -234,7 +282,14 @@ export function createServer() {
         return textResponse(`Available scenarios:\n\n${lines.join("\n")}`);
     });
     // 8. Read scenario summary
-    server.tool("tide_scenario", "Read a scenario summary from reference-apps/<scenario>/scenario.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_scenario", {
+        description: "Read a scenario summary from reference-apps/<scenario>/scenario.md",
+        inputSchema: { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         if (!scenarioExists(name))
             return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
         const scenarioContent = readScenarioFile(name, "scenario.md");
@@ -245,7 +300,14 @@ export function createServer() {
         return textResponse(text);
     });
     // 9. Read scenario manifest
-    server.tool("tide_scenario_manifest", "Read a scenario manifest from reference-apps/<scenario>/manifest.yaml", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_scenario_manifest", {
+        description: "Read a scenario manifest from reference-apps/<scenario>/manifest.yaml",
+        inputSchema: { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         if (!scenarioExists(name))
             return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
         const content = readScenarioFile(name, "manifest.yaml");
@@ -254,7 +316,14 @@ export function createServer() {
         return textResponse(content);
     });
     // 10. Read scenario role/policy matrix
-    server.tool("tide_scenario_roles", "Read a scenario role-policy matrix from reference-apps/<scenario>/role-policy-matrix.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_scenario_roles", {
+        description: "Read a scenario role-policy matrix from reference-apps/<scenario>/role-policy-matrix.md",
+        inputSchema: { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         if (!scenarioExists(name))
             return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
         const content = readScenarioFile(name, "role-policy-matrix.md");
@@ -263,7 +332,14 @@ export function createServer() {
         return textResponse(content);
     });
     // 11. Read scenario bootstrap sequence
-    server.tool("tide_scenario_bootstrap", "Read a scenario bootstrap sequence from reference-apps/<scenario>/bootstrap-sequence.md", { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) }, async ({ name }) => {
+    server.registerTool("tide_scenario_bootstrap", {
+        description: "Read a scenario bootstrap sequence from reference-apps/<scenario>/bootstrap-sequence.md",
+        inputSchema: { name: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`) },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ name }) => {
         if (!scenarioExists(name))
             return errorResponse(`Scenario '${name}' not found. Available: ${REFERENCE_APP_DIRS.join(", ")}`);
         const content = readScenarioFile(name, "bootstrap-sequence.md");
@@ -272,7 +348,14 @@ export function createServer() {
         return textResponse(content);
     });
     // 12. Choose best matching scenario
-    server.tool("tide_choose_scenario", "Match a user request to a known scenario pattern before falling back to generic playbooks", { situation: z.string().describe("Describe the app or problem, e.g. 'build an organisation password manager'") }, async ({ situation }) => {
+    server.registerTool("tide_choose_scenario", {
+        description: "Match a user request to a known scenario pattern before falling back to generic playbooks",
+        inputSchema: { situation: z.string().describe("Describe the app or problem, e.g. 'build an organisation password manager'") },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ situation }) => {
         const matches = REFERENCE_APP_DIRS
             .map((scenario) => scoreScenarioMatch(scenario, situation))
             .filter((m) => m.score > 0)
@@ -307,7 +390,14 @@ export function createServer() {
         ].join("\n\n"));
     });
     // 13. Recommend the right playbook
-    server.tool("tide_choose_playbook", "Recommend the right playbook for a given situation", { situation: z.string().describe("Describe what the builder wants to do, e.g. 'add login to a new Next.js app'") }, async ({ situation }) => {
+    server.registerTool("tide_choose_playbook", {
+        description: "Recommend the right playbook for a given situation",
+        inputSchema: { situation: z.string().describe("Describe what the builder wants to do, e.g. 'add login to a new Next.js app'") },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ situation }) => {
         const lower = situation.toLowerCase();
         const scenarioMatches = REFERENCE_APP_DIRS
             .map((scenario) => scoreScenarioMatch(scenario, situation))
@@ -350,6 +440,7 @@ export function createServer() {
             { keywords: ["iga", "approval", "governance", "admin panel"], name: "setup-iga-admin-panel", reason: "IGA admin panel setup" },
             { keywords: ["bootstrap", "realm", "init", "initialize"], name: "bootstrap-realm-from-template", reason: "Bootstrap realm from template" },
             { keywords: ["start", "run tidecloak", "launch"], name: "start-tidecloak-dev", reason: "Start TideCloak dev instance" },
+            { keywords: ["hosted", "managed", "skycloak", "cloud", "saas", "no infrastructure", "no infra"], name: "provision-tidecloak-skycloak", reason: "Provision hosted TideCloak via Skycloak (managed, no self-hosting)" },
         ];
         for (const rule of rules) {
             if (rule.keywords.some((kw) => lower.includes(kw))) {
@@ -362,8 +453,92 @@ export function createServer() {
         const text = matches.map((m) => `**${m.name}** — ${m.reason}`).join("\n");
         return textResponse(`Recommended playbook(s):\n\n${text}`);
     });
-    // 14. Read the gap register
-    server.tool("tide_gaps", "Read the gap register — what is still uncertain or unresolved in the pack", async () => {
+    // 14. Security gap analysis entry point
+    server.registerTool("tide_security_analysis", {
+        description: "Analyze an EXISTING (possibly non-Tide) system for security gaps and map them to Tide capabilities. Returns the Security Analyst role instructions, the security gap mapping table (SG-01…SG-18), and the runtime-probe procedures. Use this when the user asks 'do a security analysis', 'where is my auth weak', or 'what would Tide change about my security'.",
+        inputSchema: {
+            include_runtime_probes: z
+                .boolean()
+                .optional()
+                .describe("Include the runtime-confirmation probe procedures (canon/security-runtime-probes.md). Only relevant when the operator is authorized to probe a live target. Defaults to true."),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async ({ include_runtime_probes }) => {
+        const skill = readSkill("tide-security-analyst");
+        const mapping = readPackFile("canon", "security-gap-mapping");
+        const featureMapping = readPackFile("canon", "feature-mapping");
+        const runtimeProbes = readPackFile("canon", "security-runtime-probes");
+        if (!skill || !mapping) {
+            return errorResponse("Security analysis assets missing. Expected skills/tide-security-analyst/SKILL.md and canon/security-gap-mapping.md.");
+        }
+        const withRuntime = include_runtime_probes !== false;
+        return textResponse([
+            "# Tide Security Analysis — operating instructions",
+            "",
+            "You are running a security gap analysis of an EXISTING system. Follow the Security Analyst role below.",
+            "Work through the gap mapping (SG-01 … SG-18) exhaustively against the target. Every finding needs a named",
+            "trust concentration and evidence with a confidence tag. The out-of-scope section is mandatory.",
+            "",
+            "Two tiers: run the STATIC sweep always. Run the RUNTIME confirmation tier only with explicit authorization",
+            "to test a live target — it is governed by the authorization gate in the runtime-probes doc below.",
+            "",
+            "---",
+            "",
+            "## Role: Security Analyst",
+            "",
+            skill,
+            "",
+            "---",
+            "",
+            "## Security Gap Mapping (SG-01 … SG-18)",
+            "",
+            mapping,
+            featureMapping
+                ? "\n---\n\n## Feature Mapping (Tide capability sourcing — cite this for replacements)\n\n" + featureMapping
+                : "",
+            withRuntime && runtimeProbes
+                ? "\n---\n\n## Runtime Confirmation Probes (opt-in, authorized targets only)\n\n" + runtimeProbes
+                : "",
+        ].join("\n"));
+    });
+    // 15. Hosting options (self-host vs partner-hosted / Skycloak)
+    server.registerTool("tide_hosting", {
+        description: "Explain where TideCloak can run: self-hosted vs partner-hosted (Skycloak, a managed TideCloak-as-a-service). Returns the hosting decision, the trust model, the Skycloak API reference, and the provisioning playbook. Use when the user asks about a hosted/managed option, not wanting to run their own infrastructure, or 'can someone host TideCloak for us'.",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async () => {
+        const hosting = readPackFile("canon", "hosting-options");
+        const playbook = readPackFile("playbooks", "provision-tidecloak-skycloak");
+        if (!hosting) {
+            return errorResponse("Hosting assets missing. Expected canon/hosting-options.md.");
+        }
+        return textResponse([
+            "# Tide Hosting Options",
+            "",
+            "Where TideCloak runs is an infrastructure choice separate from app integration. Resolve self-host vs",
+            "hosted BEFORE bootstrap (I-17). State the honest trust-model caveats to the operator, not just the benefits.",
+            "",
+            "---",
+            "",
+            hosting,
+            playbook
+                ? "\n---\n\n## Provisioning Playbook: Hosted TideCloak via Skycloak\n\n" + playbook
+                : "",
+        ].join("\n"));
+    });
+    // 16. Read the gap register
+    server.registerTool("tide_gaps", {
+        description: "Read the gap register — what is still uncertain or unresolved in the pack",
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+        },
+    }, async () => {
         const full = join(PACK_ROOT, "GAP_REGISTER.md");
         if (!existsSync(full))
             return errorResponse("GAP_REGISTER.md not found");
@@ -389,6 +564,21 @@ export function createServer() {
         const promptContent = readPackFile("prompts", "secure-existing-app") ?? "";
         return { messages: [{ role: "user", content: { type: "text", text: promptContent } }] };
     });
+    server.prompt("tide-security-analysis", "Analyze an existing system for security gaps and map them to Tide", async () => {
+        const promptContent = readPackFile("prompts", "security-gap-analysis") ?? "";
+        const skill = readSkill("tide-security-analyst") ?? "";
+        const mapping = readPackFile("canon", "security-gap-mapping") ?? "";
+        const runtimeProbes = readPackFile("canon", "security-runtime-probes") ?? "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `${promptContent}\n\n---\n\nSecurity Analyst role instructions:\n\n${skill}\n\n---\n\nSecurity gap mapping:\n\n${mapping}\n\n---\n\nRuntime confirmation probes (authorized targets only):\n\n${runtimeProbes}`,
+                    },
+                }],
+        };
+    });
     server.prompt("tide-build-from-scenario", "Start building a Tide app from a known scenario pattern", {
         scenario: z.string().describe(`Scenario name. Available: ${REFERENCE_APP_DIRS.join(", ")}`),
         framework: z.enum(["nextjs", "react-vite", "vanilla"]).describe("Target framework"),
@@ -411,5 +601,17 @@ export function createServer() {
                 }],
         };
     });
+    server.prompt("tide-mcp-qa", "Run the pre-release QA gate on the Tide MCP pack and issue a SHIP/BLOCK verdict", async () => {
+        const skill = readSkill("tide-mcp-qa") ?? "";
+        return {
+            messages: [{
+                    role: "user",
+                    content: {
+                        type: "text",
+                        text: `Act as the MCP QA Engineer and decide whether the Tide MCP pack is safe to release.\n\nFollow the role below. First run the deterministic gate: \`cd mcp-server && npm test\` — a red or crashed gate is an automatic BLOCK. Then do the semantic review and honesty audit the gate cannot see, drive a sample of eval cases, and emit the Release Readiness Report with a single verdict (SHIP / SHIP_WITH_WARNINGS / BLOCK). Do not edit tests or doctrine to make a check pass.\n\n---\n\n${skill}`,
+                    },
+                }],
+        };
+    });
     return server;
 }

package/package.json

@@ -1,45 +1,48 @@
-{
-  "name": "@tideorg/mcp",
-  "version": "1.4.2",
-  "description": "MCP server exposing Tide operational guidance — canon, playbooks, skills, prompts, adapters, and scenarios for AI coding agents",
-  "type": "module",
-  "bin": {
-    "tide-agent-pack": "mcp-server/dist/index.js"
-  },
-  "scripts": {
-    "build": "cd mcp-server && npm run build",
-    "prepublishOnly": "npm run build"
-  },
-  "files": [
-    "mcp-server/dist/",
-    "canon/",
-    "playbooks/",
-    "skills/",
-    "prompts/",
-    "adapters/",
-    "reference-apps/",
-    "GAP_REGISTER.md"
-  ],
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.1",
-    "zod": "^3.24.0"
-  },
-  "keywords": [
-    "mcp",
-    "tidecloak",
-    "tide",
-    "auth",
-    "security",
-    "threshold-cryptography",
-    "ai-agent",
-    "coding-agent"
-  ],
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/tide-foundation/tide-agent-pack"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "@tideorg/mcp",
+  "version": "1.9.1",
+  "description": "MCP server exposing Tide operational guidance — canon, playbooks, skills, prompts, adapters, and scenarios for AI coding agents",
+  "type": "module",
+  "bin": {
+    "tide-agent-pack": "mcp-server/dist/index.js"
+  },
+  "scripts": {
+    "build": "cd mcp-server && npm run build",
+    "test": "cd mcp-server && npm test",
+    "prepublishOnly": "npm run build"
+  },
+  "files": [
+    "mcp-server/dist/",
+    "canon/",
+    "playbooks/",
+    "skills/",
+    "prompts/",
+    "adapters/",
+    "reference-apps/",
+    "GAP_REGISTER.md",
+    "PRIVACY.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "keywords": [
+    "mcp",
+    "tidecloak",
+    "tide",
+    "auth",
+    "security",
+    "threshold-cryptography",
+    "ai-agent",
+    "coding-agent"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tide-foundation/tide-agent-pack"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/playbooks/add-auth-nextjs-existing.md

@@ -298,7 +298,9 @@ export function ProfileButton() {
 import { useTideCloak } from '@tidecloak/nextjs';
 
 export function ProfileButton() {
-  const { authenticated, user, login, logout } = useTideCloak();
+  // useTideCloak() has no `user` object. Read claims via getValueFromIdToken /
+  // getValueFromToken (e.g. getValueFromIdToken('preferred_username')).
+  const { authenticated, login, logout } = useTideCloak();
 
   if (!authenticated) {
     return <button onClick={login}>Login</button>;
@@ -334,34 +336,37 @@ export async function GET(req) {
 }
 ```
 
-**After** (Tide - manual JWT verification):
+**After** (Tide - server-side JWT verification):
 
-You must implement server-side JWT verification. Tide SDK does not provide automatic API protection.
+Tide ships a server-side verification helper. `@tidecloak/nextjs/server` exports `verifyTideCloakToken(config, token, allowedRoles?)` (re-exported from `@tidecloak/verify`). Use it instead of hand-rolling JWKS verification.
 
-See [verify-jwt-server-side.md](verify-jwt-server-side.md) for full implementation.
-
-**Quick pattern** (based on keylessh):
+**Quick pattern** (supported helper):
 ```typescript
 // app/api/users/route.ts
 import { NextRequest } from 'next/server';
-import { verifyTideJWT } from '@/lib/auth/tideJWT';  // See verify-jwt-server-side.md
+import { verifyTideCloakToken } from '@tidecloak/nextjs/server';
+import tcConfig from '../../../data/tidecloak.json';
 
 export async function GET(req: NextRequest) {
   const authHeader = req.headers.get('authorization');
   if (!authHeader) {
     return Response.json({ error: 'Unauthorized' }, { status: 401 });
   }
+  // Accepts "Bearer <jwt>" or "DPoP <jwt>"
+  const token = authHeader.replace(/^(Bearer|DPoP) /, '');
 
-  try {
-    const jwt = await verifyTideJWT(authHeader.replace('Bearer ', ''));
-    return Response.json({ users: [...] });
-  } catch (err) {
+  // Arg order is (config, token, allowedRoles) — config FIRST.
+  const payload = await verifyTideCloakToken(tcConfig, token, []);
+  if (!payload) {
     return Response.json({ error: 'Invalid token' }, { status: 401 });
   }
+  return Response.json({ users: [...] });
 }
 ```
 
-**Critical**: You must create `lib/auth/tideJWT.ts` with local JWKS verification. See [verify-jwt-server-side.md](verify-jwt-server-side.md) for exact implementation.
+`verifyTideCloakToken` verifies the signature against the adapter's embedded `jwk` (local JWKS), checks the issuer/`azp`, and optionally enforces `allowedRoles`. It returns the decoded payload on success and `false` on failure.
+
+**If you need the manual version** (or DPoP proof re-verification): see [verify-jwt-server-side.md](verify-jwt-server-side.md), which shows the same checks hand-rolled with `jose` in `lib/auth/tideJWT.ts`.
 
 ---
 
@@ -390,13 +395,24 @@ export const config = {
 };
 ```
 
-**After** (Tide - client-side route guard):
+**After** (Tide options):
+
+Option A — **use the Tide-provided proxy/middleware helpers.** `@tidecloak/nextjs/server` ships `createTideCloakProxy` (Next.js 16+ `proxy.ts`, Node runtime) and `createTideCloakMiddleware` (Edge `middleware.ts`, still supported). These replace a NextAuth-style middleware export and perform real token verification via `verifyTideCloakToken`:
+```typescript
+// proxy.ts (Next.js 16+)  — or middleware.ts on 15 and earlier
+import { createTideCloakProxy } from '@tidecloak/nextjs/server';
+import tcConfig from './data/tidecloak.json';
 
-**Remove proxy.ts / middleware.ts** if it only checks auth. Tide provider handles client-side auth state.
+export default createTideCloakProxy(tcConfig);
+
+export const config = {
+  matcher: ['/dashboard/:path*', '/admin/:path*'],
+};
+```
 
-For API protection, use server-side JWT verification (Step 8), not proxy/middleware.
+Option B — **remove proxy.ts / middleware.ts** and rely on the client-side provider for UX gating plus server-side JWT verification in each API route (Step 8). Do this if you do not want request-interception at all.
 
-**Warning**: `proxy.ts` (and legacy `middleware.ts`) route protection is UI gating only, NOT real authorization. See [canon/feature-mapping.md](../canon/feature-mapping.md#protected-routes-vs-protected-apis).
+**Warning**: A plain, hand-written `proxy.ts` / `middleware.ts` that only checks cookie presence is UI gating only, NOT real authorization. The `createTideCloakProxy` / `createTideCloakMiddleware` helpers above DO verify the token, but you should still verify JWTs inside API routes (Step 8) as the authoritative enforcement point. See [canon/feature-mapping.md](../canon/feature-mapping.md#protected-routes-vs-protected-apis).
 
 If you want client-side route guards, implement in component:
 ```typescript
@@ -632,7 +648,7 @@ grep -r "from 'next-auth\|from \"next-auth" . --include="*.tsx" --include="*.ts"
 
 **Cause**: Old auth proxy or middleware still active.
 
-**Fix**: Remove or update `proxy.ts` (or legacy `middleware.ts`). Tide has no built-in Next.js request interception. Implement client-side route guards (Step 9) or server-side JWT verification.
+**Fix**: Remove or update `proxy.ts` (or legacy `middleware.ts`). Either switch it to Tide's `createTideCloakProxy` / `createTideCloakMiddleware` from `@tidecloak/nextjs/server` (Step 9, Option A), or remove it and rely on client-side route guards plus server-side JWT verification (Step 8).
 
 ---
 

package/playbooks/add-auth-nextjs-fresh.md

@@ -83,7 +83,7 @@ ls -la app/ 2>/dev/null && echo "App Router" || echo "Pages Router"
 npm install @tidecloak/nextjs
 ```
 
-**Verify version**: All `@tidecloak/*` packages are currently at `0.13.x`. Run `npm view @tidecloak/nextjs version` to confirm. Do not assume `1.0.0`.
+**Verify version**: `@tidecloak/*` packages are currently at `0.13.33` (run `npm view @tidecloak/nextjs version` to confirm/pin). Do not assume `1.0.0`.
 
 **Next.js 16+ bundler**: Next.js 16 defaults to Turbopack. The Tide SDK requires webpack for `strictExportPresence = false` and `@tidecloak/react` ESM alias. Update `package.json` scripts:
 ```json

package/playbooks/add-rbac-nextjs.md

@@ -137,13 +137,18 @@ Tide E2EE uses tag-based roles for **self-encryption** (user-bound, private data
 // Client-side E2EE with role enforcement (self-encryption)
 const { doEncrypt, doDecrypt } = useTideCloak();
 
+// Both take a single argument: an ARRAY of items. Each encrypt item is
+// { data, tags }; the tags drive the _tide_<tag>.self* role check.
 // Requires _tide_ssn.selfencrypt role
-const ciphertext = await doEncrypt('ssn', '123-45-6789');
+const [ciphertext] = await doEncrypt([{ data: '123-45-6789', tags: ['ssn'] }]);
 
+// doDecrypt takes the array of encrypted items ({ encrypted, tags }).
 // Requires _tide_ssn.selfdecrypt role
-const plaintext = await doDecrypt('ssn', ciphertext);
+const [plaintext] = await doDecrypt([{ encrypted: ciphertext, tags: ['ssn'] }]);
 ```
 
+**Signature note**: The `useTideCloak()` `doEncrypt`/`doDecrypt` are single-argument (`data`) wrappers. `data` is an array so you can encrypt/decrypt multiple fields in one call. This matches the shapes in [setup-forseti-e2ee.md](setup-forseti-e2ee.md) and [configure-e2ee-roles-and-policies.md](configure-e2ee-roles-and-policies.md). Do NOT call them with positional `(tag, value)` arguments — that form does not exist.
+
 Fabric enforces roles cryptographically. See [canon/concepts.md#tag-based-e2ee-roles](../canon/concepts.md#tag-based-e2ee-roles).
 
 **Self-encryption is user-bound**: only the encrypting user can decrypt. Giving another user the `selfdecrypt` role does NOT let them decrypt your data. For shared data between users, use policy-governed VVK encryption with a Forseti contract instead. See [setup-forseti-e2ee.md](setup-forseti-e2ee.md) and [canon/anti-patterns.md AP-24](../canon/anti-patterns.md#ap-24-using-self-encryption-for-shared-data-between-users).