@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

package/framework/standards/backend/integrations/neon-auth/neon-auth.md

@@ -125,16 +125,19 @@ real sign-in attempt, not after debugging a mysterious "session never sticks" bu
 
 ### SDK Initialization
 
+`lib/auth/client.ts` — `createAuthClient` takes the public auth URL as a positional argument, and the
+React hooks are re-exported from the client instance for ergonomic imports:
+
 ```typescript
-// lib/auth/client.ts
 'use client';
 import { createAuthClient } from '@neondatabase/auth/next';
-// createAuthClient takes the public auth URL as a positional argument
 export const authClient = createAuthClient(process.env.NEXT_PUBLIC_AUTH_URL!);
-// Re-export the React hooks from the client instance for ergonomic imports
 export const { useSession } = authClient;
+```
+
+`lib/auth/server.ts`:
 
-// lib/auth/server.ts
+```typescript
 import { createNeonAuth } from '@neondatabase/auth/next/server';
 export const auth = createNeonAuth({
   baseUrl: process.env.NEON_AUTH_BASE_URL!,
@@ -152,8 +155,9 @@ Import the Tailwind styles for the UI components in `globals.css`:
 @import '@neondatabase/auth-ui/tailwind';
 ```
 
+`app/providers.tsx`:
+
 ```tsx
-// app/providers.tsx
 'use client';
 import { NeonAuthUIProvider } from '@neondatabase/auth-ui';
 import { authClient } from '@/lib/auth/client';
@@ -169,8 +173,9 @@ export function Providers({ children }: { children: React.ReactNode }) {
 
 ### Auth API Route
 
+`app/api/auth/[...path]/route.ts`:
+
 ```typescript
-// app/api/auth/[...path]/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const { GET, POST } = auth.handler();
@@ -182,8 +187,9 @@ export const { GET, POST } = auth.handler();
 
 ### Sign In / Sign Up Pages
 
+`app/auth/sign-in/page.tsx`:
+
 ```tsx
-// app/auth/sign-in/page.tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignInPage() {
@@ -193,8 +199,11 @@ export default function SignInPage() {
     </div>
   );
 }
+```
+
+`app/auth/sign-up/page.tsx`:
 
-// app/auth/sign-up/page.tsx
+```tsx
 import { AuthView } from '@neondatabase/auth-ui';
 
 export default function SignUpPage() {
@@ -208,8 +217,9 @@ export default function SignUpPage() {
 
 ### Server-Side Auth Check
 
+`app/dashboard/page.tsx`:
+
 ```typescript
-// app/dashboard/page.tsx
 import { auth } from '@/lib/auth/server';
 import { redirect } from 'next/navigation';
 
@@ -228,8 +238,9 @@ export default async function DashboardPage() {
 
 ### Client Component with User Data
 
+`components/UserProfile.tsx`:
+
 ```tsx
-// components/UserProfile.tsx
 'use client';
 import { useSession } from '@/lib/auth/client';
 
@@ -249,14 +260,15 @@ export function UserProfile() {
 
 ### Route Protection (Middleware)
 
+`middleware.ts`. The `runtime = 'nodejs'` line is **mandatory** for any `middleware.ts` that touches
+Neon Auth: Next.js middleware runs on the Edge runtime by default, and the network call the Neon Auth
+SDK makes to mint the session-data cookie times out inside the Edge sandbox on `next dev` — the request
+silently bounces back to sign-in even with a fully valid session, with no error surfaced.
+
 ```typescript
-// middleware.ts
 import { auth } from '@/lib/auth/server';
 
-// MANDATORY for any middleware.ts that touches Neon Auth. Next.js middleware runs on the Edge
-// runtime by default, and the network call the Neon Auth SDK makes to mint the session-data cookie
-// times out inside the Edge sandbox on `next dev` — the request silently bounces back to sign-in
-// even with a fully valid session, with no error surfaced. Force the Node.js runtime instead.
+// Mandatory: on the Edge runtime the SDK's session-cookie call times out and silently bounces to sign-in.
 export const runtime = 'nodejs';
 
 export default auth.middleware({
@@ -294,7 +306,6 @@ export default function ProtectedPage() {
 ## OAuth (Social Login)
 
 ```typescript
-// Trigger OAuth sign-in
 await authClient.signIn.social({
   provider: 'google',
   callbackURL: 'http://localhost:3000/auth/callback',
@@ -307,8 +318,9 @@ Configure OAuth providers in the Neon Console under Auth > Configuration.
 
 ## API Route Protection
 
+`app/api/protected/route.ts`:
+
 ```typescript
-// app/api/protected/route.ts
 import { auth } from '@/lib/auth/server';
 
 export const dynamic = 'force-dynamic';
@@ -348,34 +360,38 @@ backend's real prefix and the proxy's public prefix don't happen to match charac
 because this is a runtime routing mismatch (404, or the proxy calling itself), it **never shows up at
 build time**, only when a human clicks the page.
 
+`lib/api/prefixes.ts` — `BACKEND_API_PREFIX` is used ONLY by Server Components / Route Handlers
+calling the .NET backend directly (e.g. `https://api.example.com`; the backend's own routes have NO
+`/api` prefix); `PROXY_API_PREFIX` is used ONLY by Client Components calling the same-origin Next.js
+proxy, and matches `app/api/proxy/[...path]/route.ts`:
+
 ```typescript
-// lib/api/prefixes.ts
-// BACKEND_API_PREFIX: used ONLY by Server Components / Route Handlers calling the .NET backend directly.
-export const BACKEND_API_PREFIX = process.env.API_URL; // e.g. https://api.example.com — backend's own routes have NO /api prefix
+export const BACKEND_API_PREFIX = process.env.API_URL;
 
-// PROXY_API_PREFIX: used ONLY by Client Components calling the same-origin Next.js proxy.
-export const PROXY_API_PREFIX = '/api/proxy'; // matches app/api/proxy/[...path]/route.ts
+export const PROXY_API_PREFIX = '/api/proxy';
 ```
 
+The two call sites below — `app/(dashboard)/catalog/page.tsx`, a Server Component calling the backend
+directly, and `features/catalog/hooks/use-items.ts`, a Client Component going through the same-origin
+proxy — MUST resolve to the same backend route:
+
 ```typescript
-// app/(dashboard)/catalog/page.tsx — Server Component, direct backend call
 import { BACKEND_API_PREFIX } from '@/lib/api/prefixes';
 
 async function getItems() {
-  // cross-reference: PROXY_API_PREFIX below MUST resolve to the same backend route
   const res = await fetch(`${BACKEND_API_PREFIX}/catalog/items`, { next: { revalidate: 60 } });
   return res.json();
 }
 ```
 
+`features/catalog/hooks/use-items.ts`:
+
 ```typescript
-// features/catalog/hooks/use-items.ts — Client Component, via same-origin proxy
 import { PROXY_API_PREFIX } from '@/lib/api/prefixes';
 
 export function useItems() {
   return useQuery({
     queryKey: ['catalog', 'items'],
-    // cross-reference: BACKEND_API_PREFIX above MUST resolve to the same backend route
     queryFn: async () => (await fetch(`${PROXY_API_PREFIX}/catalog/items`)).json(),
   });
 }
@@ -435,31 +451,30 @@ Before marking any task that adds or touches an endpoint as done:
 
 ### JWT Bearer Configuration
 
+`Infrastructure/Auth/NeonAuthOptions.cs` — `BaseUrl` is the Neon Auth Base URL, e.g.
+`https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthOptions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 public sealed class NeonAuthOptions
 {
     public const string SectionName = "NeonAuth";
 
-    /// <summary>Neon Auth Base URL, e.g. https://ep-xxx.neonauth.us-east-2.aws.neon.build/neondb/auth</summary>
     public string BaseUrl { get; set; } = string.Empty;
 }
 ```
 
+`Infrastructure/Auth/NeonAuthJwksProvider.cs` fetches and caches Neon Auth's raw JWKS
+(`/.well-known/jwks.json` — there is no OIDC discovery document) for 15 minutes; an unknown `kid`
+forces one refresh, to survive key rotation without waiting out the TTL:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthJwksProvider.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using Microsoft.Extensions.Options;
 using Microsoft.IdentityModel.Tokens;
 
-/// <summary>
-/// Fetches and caches Neon Auth's raw JWKS (/.well-known/jwks.json — there is no OIDC discovery
-/// document). Cached for 15 minutes; a forced refresh happens once when an unknown `kid` is seen,
-/// to survive key rotation without waiting out the TTL.
-/// </summary>
 public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAuthOptions> options)
 {
     private static readonly TimeSpan CacheTtl = TimeSpan.FromMinutes(15);
@@ -473,7 +488,7 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
         var key = keySet.Keys.FirstOrDefault(k => k.Kid == kid);
         if (key is not null) return key;
 
-        // Unknown kid — could be key rotation. Force a single refresh before giving up.
+        // Unknown kid may be key rotation: refresh once before giving up.
         keySet = await GetKeySetAsync(forceRefresh: true, cancellationToken);
         return keySet.Keys.FirstOrDefault(k => k.Kid == kid);
     }
@@ -503,8 +518,9 @@ public sealed class NeonAuthJwksProvider(HttpClient httpClient, IOptions<NeonAut
 }
 ```
 
+`Infrastructure/Auth/NeonAuthServiceExtensions.cs`:
+
 ```csharp
-// Infrastructure/Auth/NeonAuthServiceExtensions.cs
 namespace {ProjectName}.Infrastructure.Auth;
 
 using System.Text;
@@ -527,9 +543,7 @@ public static class NeonAuthServiceExtensions
         services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
             .AddJwtBearer(options =>
             {
-                // Do NOT set options.Authority — Neon Auth serves no /.well-known/openid-configuration,
-                // so Authority-driven metadata refresh has nothing valid to fetch. ValidIssuer is set
-                // explicitly below instead.
+                // No options.Authority: Neon Auth serves no OIDC discovery document, so ValidIssuer is explicit.
                 options.TokenValidationParameters = new TokenValidationParameters
                 {
                     ValidateIssuer = true,
@@ -537,14 +551,12 @@ public static class NeonAuthServiceExtensions
                     ValidateAudience = false,
                     ValidateLifetime = true,
                     NameClaimType = "sub",
-                    // Trust in the signing key is established entirely inside SignatureValidator
-                    // below (fetched from our own cached JWKS) — this flag doesn't gate that path.
+                    // Key trust is established inside SignatureValidator below; this flag doesn't gate that path.
                     ValidateIssuerSigningKey = false,
                 };
             });
 
-        // A second Configure<TDep> pass with DI available — AddJwtBearer's own setup has already run,
-        // so this only *adds* the SignatureValidator to the TokenValidationParameters built above.
+        // Runs after AddJwtBearer's own setup, with DI available: it only adds the SignatureValidator.
         services.AddOptions<JwtBearerOptions>(JwtBearerDefaults.AuthenticationScheme)
             .Configure<NeonAuthJwksProvider>((options, jwks) =>
             {
@@ -561,9 +573,7 @@ public static class NeonAuthServiceExtensions
                     if (string.IsNullOrEmpty(kid))
                         throw new SecurityTokenInvalidSignatureException("Token is missing 'kid'.");
 
-                    // Blocking call: JWKS is cached in-memory (see NeonAuthJwksProvider), so this is
-                    // I/O-free on the hot path. SignatureValidator has no async overload in this
-                    // library version — only a cold-start / key-rotation miss ever awaits real I/O here.
+                    // Blocking is safe: SignatureValidator has no async overload and the JWKS is cached in memory.
                     var jwk = jwks.GetKeyAsync(kid, CancellationToken.None).GetAwaiter().GetResult()
                         ?? throw new SecurityTokenInvalidSignatureException($"No JWKS key found for kid '{kid}'.");
 
@@ -585,10 +595,7 @@ public static class NeonAuthServiceExtensions
                     if (!verifier.VerifySignature(signature))
                         throw new SecurityTokenInvalidSignatureException("Ed25519 signature verification failed.");
 
-                    // MUST return Microsoft.IdentityModel.JsonWebTokens.JsonWebToken — ASP.NET Core 8+
-                    // uses JsonWebTokenHandler internally. Returning a
-                    // System.IdentityModel.Tokens.Jwt.JwtSecurityToken here fails with IDX10506
-                    // ("SignatureValidator returned a token of an unexpected type").
+                    // Must be JsonWebToken: ASP.NET Core 8+ rejects a JwtSecurityToken here with IDX10506.
                     return jwt;
                 };
             });
@@ -600,6 +607,12 @@ public static class NeonAuthServiceExtensions
 }
 ```
 
+Two details of the validator above: it returns `Microsoft.IdentityModel.JsonWebTokens.JsonWebToken`
+because ASP.NET Core 8+ uses `JsonWebTokenHandler` internally — returning a
+`System.IdentityModel.Tokens.Jwt.JwtSecurityToken` fails with IDX10506 ("SignatureValidator returned a
+token of an unexpected type"); and the blocking `GetResult()` is I/O-free on the hot path, since only a
+cold-start or key-rotation miss ever awaits real I/O.
+
 ### Protected Endpoints
 
 ```csharp

package/framework/standards/frontend/design-system/ai-image-generation.md

@@ -43,7 +43,7 @@ Skipping this chain is the most common cause of a page whose images do not feel
 
 ```javascript
 // Generate a new image
-mcp__gemini_image_mcp__generate_image({
+mcp__gemini-image-mcp__generate_image({
   prompt: string,           // Text description (max 5000 chars, narrative style)
   aspectRatio?: "1:1" | "2:3" | "3:2" | "3:4" | "4:3" | "9:16" | "16:9",
   outputPath?: string,      // File path to save (e.g., "public/images/feature/hero.png")
@@ -51,25 +51,25 @@ mcp__gemini_image_mcp__generate_image({
 })
 
 // Edit an existing image
-mcp__gemini_image_mcp__edit_image({
+mcp__gemini-image-mcp__edit_image({
   imageSource: string,      // Path to image or image ID
   prompt: string,           // Short, targeted edit instructions (1-2 sentences)
   outputPath?: string,
 })
 
 // Continue editing last image
-mcp__gemini_image_mcp__continue_editing({
+mcp__gemini-image-mcp__continue_editing({
   prompt: string,           // One adjustment at a time
 })
 
 // List generated images
-mcp__gemini_image_mcp__list_images({
+mcp__gemini-image-mcp__list_images({
   type?: "generated" | "edited" | "all",
   limit?: number,
 })
 
 // Get image details
-mcp__gemini_image_mcp__get_image_info({
+mcp__gemini-image-mcp__get_image_info({
   imageId?: string,         // Defaults to last image
 })
 ```

package/framework/standards/integration/mcp/mcp-tools.md

@@ -5,32 +5,26 @@
 > **Keywords:** mcp, model-context-protocol, mcp-tools, context7, playwright, mcp-client
 > **Load When:** an MCP tool is used in any morph-spec phase
 
-**Verified against:** Claude Code MCP tooling — context7, Playwright; GitHub via `gh` CLI; Neon via `neonctl`. Last-verified: 2026-07-08.
+**Verified against:** Claude Code 2.1.282 MCP tooling — context7, Playwright (as plugin and as a project MCP server); GitHub via `gh` CLI; Neon via its MCP or `neonctl`. Last-verified: 2026-09-24.
 
 ---
 
 Reference for using Model Context Protocol (MCP) tools across morph-spec phases. Each phase benefits from different MCPs depending on what data is needed.
 
-## MCP Availability Detection
+## Tool Names Depend on Where the Server Is Configured
 
-Before using any MCP tool, check if it's available in the current session:
+The names below use the `.mcp.json` form, `mcp__<server>__<tool>`. The same server installed as a **plugin** is named `mcp__plugin_<plugin>_<server>__<tool>`: context7 from the plugin is `mcp__plugin_context7_context7__query-docs`, not `mcp__context7__query-docs`. Call the name that exists in your session. The tool part (`query-docs`, `browser_navigate`) is the same under both prefixes.
 
-```javascript
-// Pattern: Attempt the call — if the tool doesn't exist, Claude Code will report it
-// There is no "list MCPs" command; just try the most common operation
+In a morph persona the grant follows the same rule: the installer emits one `mcp__<name>` per spelling in the registry's `serverNames`, and a grant matches only its own spelling. If a tool you expect is missing, it may be deferred: load it with `ToolSearch` before calling it.
+
+## MCP Availability Detection
 
-// GitHub — o morph-spec NÃO usa MCP do GitHub: use o `gh` CLI via Bash
-// gh repo view --json name,defaultBranchRef,languages
+Before using any MCP tool, check if it's available in the current session. There is no "list MCPs" command: attempt the most common operation, and Claude Code reports a tool that doesn't exist. GitHub and Neon are not checked this way — o morph-spec NÃO usa MCP do GitHub nem do Neon: use o `gh` CLI (`gh repo view --json name,defaultBranchRef,languages`) e o `neonctl` + `psql` (`neonctl connection-string` dá a URL do banco) via Bash.
 
-// Context7 (library docs)
-await mcp__context7__resolve_library_id({ libraryName: "react" });
+```javascript
+await mcp__context7__resolve-library-id({ libraryName: "react" });
 
-// Playwright (browser automation)
 await mcp__playwright__browser_navigate({ url: "https://example.com" });
-
-// Neon — use `neonctl` CLI + `psql`
-// neonctl connection-string → get DB URL
-// psql <DB_URL> -c "SELECT ..."
 ```
 
 **Fallback rule:** If an MCP is not available, every phase has a manual alternative using Claude Code native tools (Read, Grep, Glob, Bash).
@@ -61,36 +55,31 @@ gh issue list --limit 10 --json title,labels
 | MCP | Use Case | Example |
 |-----|----------|---------|
 | **Playwright** | Navigate, screenshot, inspect live pages | `mcp__playwright__browser_navigate({ url })` |
-| **Context7** | Component library documentation | `mcp__context7__query_docs({ libraryId, query })` |
+| **Context7** | Component library documentation | `mcp__context7__query-docs({ libraryId, query })` |
+
+The screenshot is the visual reference; the snapshot is the accessibility tree (headings, buttons, inputs); the resize tests the mobile layout; Context7 brings the component docs for the UI spec.
 
 ```javascript
-// Screenshot existing app for design reference
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
 const screenshot = await mcp__playwright__browser_take_screenshot();
-// → Visual reference for UI/UX design
 
-// Inspect page structure via accessibility tree
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Structured element tree (headings, buttons, inputs, etc.)
 
-// Test responsive layout
 await mcp__playwright__browser_resize({ width: 375, height: 812 });
 const mobileScreenshot = await mcp__playwright__browser_take_screenshot();
 
-// Get MudBlazor component docs for UI specs
-const libId = await mcp__context7__resolve_library_id({
+const libId = await mcp__context7__resolve-library-id({
   libraryName: "mudblazor",
   query: "data grid with sorting and filtering"
 });
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: libId,
   query: "DataGrid component props and events"
 });
-
-// Fallback: WebSearch for component documentation
-// WebFetch for specific component API pages
 ```
 
+Fallback: WebSearch for component documentation, WebFetch for specific component API pages.
+
 ### Gemini Image MCP — AI Image Generation
 
 > Available in: **UI/UX** (preview generation), **Implement** (production assets)
@@ -103,29 +92,27 @@ const docs = await mcp__context7__query_docs({
 | `list_images` | Browse image generation history | `mcp__gemini-image-mcp__list_images({ type: "all" })` |
 | `get_image_info` | Get metadata about a specific image | `mcp__gemini-image-mcp__get_image_info({ imageId })` |
 
+Read `design-system.md` first to get the project colors and aesthetic direction. Keep edits short and targeted, and iterate with `continue_editing` one change at a time.
+
 ```javascript
-// Generate a hero image using design system tokens
-// Read design-system.md first to get project colors and aesthetic direction
-const image = await mcp__gemini_image_mcp__generate_image({
+const image = await mcp__gemini-image-mcp__generate_image({
   prompt: "A floating tablet showing a modern dashboard interface on a dark charcoal background with copper and gold accent lighting. Premium luxury aesthetic, photorealistic, cinematic lighting with warm rim light.",
   aspectRatio: "16:9",
   outputPath: "public/images/my-feature/hero-mockup.png"
 });
 
-// Edit an existing image (keep edits short and targeted)
-await mcp__gemini_image_mcp__edit_image({
+await mcp__gemini-image-mcp__edit_image({
   imageSource: "public/images/my-feature/hero-mockup.png",
   prompt: "Make the lighting warmer and add a subtle copper glow around the tablet edges."
 });
 
-// Iterate with continue_editing (one change at a time)
-await mcp__gemini_image_mcp__continue_editing({
+await mcp__gemini-image-mcp__continue_editing({
   prompt: "More contrast in the shadows."
 });
-
-// Fallback: Manual image creation, stock photos, or placeholder divs
 ```
 
+Fallback: manual image creation, stock photos, or placeholder divs.
+
 **Use cases by phase:**
 
 | Phase | Use Case | Tool |
@@ -143,7 +130,7 @@ await mcp__gemini_image_mcp__continue_editing({
 | Tool | Use Case | Example |
 |------|----------|---------|
 | **Neon CLI (`neonctl`) / psql** | Database schema, tables, relationships, RLS | `psql <DB_URL> -c "SELECT ..."` |
-| **Context7** | Library docs for architecture decisions | `mcp__context7__query_docs()` |
+| **Context7** | Library docs for architecture decisions | `mcp__context7__query-docs()` |
 | **GitHub CLI (`gh`)** | Check existing code patterns, PRs | `gh search code` (Bash) |
 
 ```bash
@@ -183,26 +170,26 @@ psql $(neonctl connection-string) -c "SELECT tablename, policyname, cmd, qual FR
 
 | MCP | Use Case | Example |
 |-----|----------|---------|
-| **Context7** | Verify library capabilities, API limits | `mcp__context7__query_docs()` |
+| **Context7** | Verify library capabilities, API limits | `mcp__context7__query-docs()` |
 | **GitHub CLI (`gh`)** | Check issue discussions, known limitations | `gh search issues` (Bash) |
 
+The answer confirms a capability or identifies a limitation for the spec update:
+
 ```javascript
-// Verify if library supports a required feature
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: "/mudblazor/mudblazor",
   query: "DataGrid server-side pagination with virtual scrolling"
 });
-// → Confirms capability or identifies limitation for spec update
-
-// Fallback: WebSearch for library capabilities
 ```
 
+Fallback: WebSearch for library capabilities.
+
 ### Phase 6 (Tasks) — Planning & Organization
 
 | Tool | Use Case | Example |
 |------|----------|---------|
 | **GitHub CLI (`gh`)** | Create issues from tasks, link to milestone | `gh issue create` (Bash) |
-| **Context7** | Estimate complexity based on library docs | `mcp__context7__query_docs()` |
+| **Context7** | Estimate complexity based on library docs | `mcp__context7__query-docs()` |
 
 ```bash
 # Create GitHub issues from tasks.json (if team uses GitHub Projects)
@@ -218,7 +205,7 @@ gh issue create --title "T001: Create Entity Lead" \
 |------|----------|---------|
 | **Neon CLI (`neonctl`) / psql** | Run migrations, create RLS policies | `dotnet ef database update` |
 | **GitHub CLI (`gh`)** | Create PR, push branches | `gh pr create` (Bash) |
-| **Context7** | Look up API usage during coding | `mcp__context7__query_docs()` |
+| **Context7** | Look up API usage during coding | `mcp__context7__query-docs()` |
 | **Playwright** | Smoke test deployed features, verify UI | `mcp__playwright__browser_navigate()` |
 | **Vercel** | Deploy, check logs, manage env vars | `mcp__vercel__list_projects()` |
 | **Azure CLI** | Resource management, deployments | `az` commands |
@@ -240,35 +227,23 @@ psql $(neonctl connection-string) -c "SELECT column_name, data_type FROM informa
 psql $(neonctl connection-string) -c "SELECT policyname, cmd, qual FROM pg_policies WHERE tablename = 'leads'"
 ```
 
+Look up the API while coding, then smoke test the deployed feature: the snapshot shows whether the page renders, the console messages catch JavaScript errors and failed API calls, and the screenshot goes to `recap.md`. Vercel covers deployment status, logs and environment variables.
+
 ```javascript
-// Lookup API during implementation
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: "/dotnet/efcore",
   query: "owned entity types configuration"
 });
 
-// Smoke test deployed feature via browser
 await mcp__playwright__browser_navigate({ url: "https://localhost:5001/leads" });
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Verify page renders correctly, check for errors
-
-// Check for console errors after deploy
 const logs = await mcp__playwright__browser_console_messages();
-// → Catch JavaScript errors, failed API calls
-
-// Screenshot for recap.md documentation
 const screenshot = await mcp__playwright__browser_take_screenshot();
 
-// === VERCEL (Deployment & Environment) ===
-
-// List projects
 const projects = await mcp__vercel__list_projects();
-
-// Check deployment status and logs
 const deployments = await mcp__vercel__get_deployments({ projectId: 'my-project' });
-const logs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
+const deploymentLogs = await mcp__vercel__get_deployment_logs({ deploymentId: deployments[0].uid });
 
-// Manage environment variables
 await mcp__vercel__manage_env_vars({
   projectId: 'my-project',
   action: 'set',
@@ -276,10 +251,10 @@ await mcp__vercel__manage_env_vars({
   value: process.env.DATABASE_URL,
   target: ['production', 'preview']
 });
-
-// PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: vercel CLI
 ```
 
+PRs/issues: sempre `gh` CLI (Bash). Deployments fallback: `vercel` CLI.
+
 ---
 
 ## MCP vs Native Tools Decision
@@ -306,76 +281,33 @@ await mcp__vercel__manage_env_vars({
 
 ### Browser (Playwright): Page Automation & Analysis
 
-```javascript
-// === SETUP ===
-// Playwright MCP: npx @playwright/mcp@latest
-// Config in .claude/settings.json or claude_desktop_config.json:
-// { "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }
+Setup: `npx @playwright/mcp@latest`, configured in `.claude/settings.json` or `claude_desktop_config.json` as `{ "mcpServers": { "playwright": { "command": "npx", "args": ["@playwright/mcp@latest"] } } }`.
 
-// === NAVIGATION & SNAPSHOT ===
+Prefer the accessibility snapshot to the screenshot: it is structured, LLM-friendly, and returns the element `ref`s that the interaction calls take. `browser_fill_form` replaces the field's existing value; `browser_handle_dialog` answers alert, confirm and prompt.
 
-// 1. Navigate to a page
+```javascript
 await mcp__playwright__browser_navigate({ url: "https://app.example.com/dashboard" });
-
-// 2. Take accessibility snapshot (preferred — structured, LLM-friendly)
 const snapshot = await mcp__playwright__browser_snapshot();
-// → Returns accessibility tree with element refs for interaction
-
-// 3. Take visual screenshot (requires --caps vision)
-const screenshot = await mcp__playwright__browser_take_screenshot();
-// → Returns PNG image of current page
-
-// === INTERACTION ===
+const screenshot = await mcp__playwright__browser_take_screenshot(); // requires --caps vision
 
-// 4. Click an element (use ref from snapshot)
 await mcp__playwright__browser_click({ element: "Submit button", ref: "s1e15" });
-
-// 5. Type into an input field
 await mcp__playwright__browser_type({ element: "Search input", ref: "s1e8", text: "query" });
-
-// 6. Fill a form field (replaces existing value)
 await mcp__playwright__browser_fill_form({ ref: "s1e8", value: "new value" });
-
-// 7. Select dropdown option
 await mcp__playwright__browser_select_option({ element: "Status", ref: "s1e12", values: ["active"] });
-
-// 8. Press keyboard key
 await mcp__playwright__browser_press_key({ key: "Enter" });
 
-// === TABS & NAVIGATION ===
-
-// 9. List open tabs
 const tabs = await mcp__playwright__browser_tabs();
-
-// 10. Navigate back
 await mcp__playwright__browser_navigate_back();
-
-// 11. Close current tab
 await mcp__playwright__browser_close();
 
-// === ADVANCED ===
-
-// 12. Evaluate JavaScript in page context
 const result = await mcp__playwright__browser_evaluate({
   expression: "document.querySelectorAll('.error').length"
 });
-
-// 13. Get console messages (debug)
 const logs = await mcp__playwright__browser_console_messages();
-
-// 14. Get network requests
 const requests = await mcp__playwright__browser_network_requests();
-
-// 15. Handle dialog (alert, confirm, prompt)
 await mcp__playwright__browser_handle_dialog({ accept: true });
-
-// 16. Resize viewport
-await mcp__playwright__browser_resize({ width: 375, height: 812 }); // iPhone viewport
-
-// 17. Save page as PDF (requires --caps pdf)
-await mcp__playwright__browser_pdf_save();
-
-// 18. Upload file
+await mcp__playwright__browser_resize({ width: 375, height: 812 });
+await mcp__playwright__browser_pdf_save(); // requires --caps pdf
 await mcp__playwright__browser_file_upload({ ref: "s1e20", paths: ["/path/to/file.png"] });
 ```
 
@@ -424,16 +356,15 @@ psql $(neonctl connection-string) -c "SELECT tc.table_name, kcu.column_name, ccu
 
 ### Context7: Library Research
 
+For any phase needing library documentation: resolve the library ID first, then query the specific documentation with it.
+
 ```javascript
-// Workflow for any phase needing library documentation
-// Step 1: Resolve library ID
-const lib = await mcp__context7__resolve_library_id({
+const lib = await mcp__context7__resolve-library-id({
   libraryName: "fluent-ui-blazor",
   query: "dialog component with form validation"
 });
 
-// Step 2: Query specific documentation
-const docs = await mcp__context7__query_docs({
+const docs = await mcp__context7__query-docs({
   libraryId: lib.id,
   query: "FluentDialog component usage with EditForm validation"
 });