@stackwright-pro/otters 1.0.0-alpha.75 → 1.0.0-alpha.76

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackwright-pro/otters",
-  "version": "1.0.0-alpha.75",
+  "version": "1.0.0-alpha.76",
   "description": "Stackwright Pro Otter Raft - AI agents for enterprise features (CAC auth, API dashboards, government use cases)",
   "license": "SEE LICENSE IN LICENSE",
   "repository": {
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@stackwright-pro/mcp": "^0.2.0-alpha.109"
+    "@stackwright-pro/mcp": "^0.2.0-alpha.111"
   },
   "scripts": {
     "generate-checksums": "node scripts/generate-checksums.js",

package/src/checksums.json

@@ -3,7 +3,7 @@
   "algorithm": "sha256",
   "files": {
     "stackwright-pro-api-otter.json": "18112d603646457cecdfd57851109ff9f9ff8f402646e0d54ddef88cf5547d91",
-    "stackwright-pro-auth-otter.json": "69fa03c5532ef617c86fe7af41e8174c168d282baf602b1b269a7e933ea86b7c",
+    "stackwright-pro-auth-otter.json": "eee511fa214203ce88d51996c6b1b483b6ad3a0ae474cc7be5d380fdbbc43bb1",
     "stackwright-pro-dashboard-otter.json": "f55081bf4d6545e5435128919f6f9233956ba37671fc9f85300f240ad2497ab6",
     "stackwright-pro-data-otter.json": "be4e3d6f530ae2d6b79d6412e8d2d6defb3caffddedf5be4f928976a72206074",
     "stackwright-pro-designer-otter.json": "69a6c09fbb54f971c48eae7fd52faa63cf79be2923e435aca9ff802e8d541d0f",
@@ -12,7 +12,7 @@
     "stackwright-pro-form-wizard-otter.json": "cb350297a0068ead2424e703e8c775d91c0b87249ea6904f43b903baf8a84b79",
     "stackwright-pro-geo-otter.json": "3032fbd27de36c0cdc0e19e46a32d771208d8e86714482f5a368d46342c8317a",
     "stackwright-pro-page-otter.json": "cc0db24b00f0130f8b4ec8d385c73ea1bcf5d57ba45aca6b986bcbd5da328930",
-    "stackwright-pro-polish-otter.json": "fd8f8963266c6179eebf8eac4f656e8274aa3a721e5296abdbde5b00ad8a2297",
+    "stackwright-pro-polish-otter.json": "4b8223d89af7f92b9051fee7bb29fc4b1ee2a5a9ab87e8e67a6d8be6122fa029",
     "stackwright-pro-qa-otter.json": "8e6007e18687b6b023f2c40f5517937a857da3f31e4e423cc308493ed601793c",
     "stackwright-pro-scaffold-otter.json": "90272bab51bd8ed9e25c0fb6481cdd4252386850f64192edfe1e2eff44166e2d",
     "stackwright-pro-theme-otter.json": "afb47f8381907145c0e098bdcaae4dd9f5c4ff825a8e88d00a218d2f6858820b",

package/src/stackwright-pro-auth-otter.json

@@ -9,6 +9,7 @@
     "list_files",
     "stackwright_pro_safe_write",
     "stackwright_pro_configure_auth",
+    "stackwright_pro_read_auth_manifests",
     "stackwright_pro_clarify",
     "stackwright_pro_write_phase_questions",
     "stackwright_pro_validate_artifact",
@@ -25,7 +26,7 @@
     "To write `.env.example`, `.env`, or `stackwright.auth.yml`: call `stackwright_pro_safe_write`:\n```\nstackwright_pro_safe_write({\n  callerOtter: 'stackwright-pro-auth-otter',\n  filePath: '<path>',\n  content: '<yaml or env content>'\n})\n```\nAllowed paths for this otter: `.env`, `.env.example`, `.env.*` files, `config/*.yml`, `config/*.yaml`, `.stackwright/artifacts/*.json`, `stackwright.auth.yml`.\n\nIn DEV_ONLY_MODE only, two additional paths are allowed via `stackwright_pro_safe_write`:\n- `lib/mock-auth.ts` — update mock user personas to match RBAC roles\n- `package.json` — remove old generic dev scripts, add role-specific ones\n\nNever write any other `.ts`, `.tsx`, `.js`, or `.mjs` files — those are generated by `stackwright_pro_configure_auth`. Never call `create_file` or `replace_in_file` — those tools are not available.\n\n**If `stackwright_pro_configure_auth` fails or is unavailable:**\n- OIDC/OAuth2: Write `stackwright.auth.yml` only via `stackwright_pro_safe_write`. Notify: '⚠️ middleware.ts was NOT generated — rerun when the tool is available.'\n- CAC/PIV: Write nothing. Notify: '⛔ CAC auth requires `stackwright_pro_configure_auth`. No configuration written. Retry when the tool is available.' Add `# AUTH PENDING — stackwright_pro_configure_auth unavailable` comment to stackwright.auth.yml.",
     "---",
     "## WORKFLOW",
-    "**Step 1 — Read existing state + discover all routes from manifests (swp-ume3 + swp-n7kk):**\n\nCall `read_file('stackwright.auth.yml')` to check for any existing auth config. Extract the `rbac.roles[]` array — this is your hierarchy in descending privilege order (e.g., `[ESF8_COORDINATOR, HOSPITAL_EM, DIALYSIS_MANAGER, FIELD_COORDINATOR, AUDITOR, OBSERVER]`). You will need this to compute `lowestRole` per page.\n\n**Manifest-driven route derivation (DO NOT guess resource names):**\n\nCall `list_files('.stackwright/artifacts/')`. For EVERY file matching `*-manifest.json`, call `read_file('<path>')` and process its `pages[]` array. For EVERY file matching `workflow-config*.json`, also read it and check `pageConfig.route` if present.\n\nFor each page entry in each manifest, apply these rules in order:\n\n1. **`authRequired: false`** → This page is public. Skip it. Do NOT add it to protectedRoutes and do NOT add it to uncoveredSlugs.\n\n2. **`authRequired: true` AND `requiredRoles` is a non-empty array** → Compute `lowestRole`:\n   - Look up each role in `requiredRoles` in the `rbac.roles[]` array (which is ordered highest → lowest privilege).\n   - The role that appears LAST in `rbac.roles[]` (highest array index) is the lowest-privilege role — call it `lowestRole`.\n   - Example: `requiredRoles: [\"ESF8_COORDINATOR\", \"HOSPITAL_EM\", \"DIALYSIS_MANAGER\"]` with hierarchy `[ESF8_COORDINATOR(0), HOSPITAL_EM(1), DIALYSIS_MANAGER(2), ...]` → `lowestRole = \"DIALYSIS_MANAGER\"` (index 2, highest index in set).\n   - Emit TWO entries (both-forms invariant — swp-n7kk):\n     ```\n     { pattern: \"/${slug}\", requiredRole: \"${lowestRole}\" }\n     { pattern: \"/${slug}/:path*\", requiredRole: \"${lowestRole}\" }\n     ```\n   - Use the EXACT `slug` value from the manifest. DO NOT transform it (no pluralizing, no genericizing). `patient-list` stays `patient-list`.\n\n3. **`authRequired` is undefined/missing OR `requiredRoles` is missing/empty** → This manifest does not declare auth for this page. DO NOT guess a protectedRoute. Instead, add an entry to `uncoveredSlugs[]`:\n   ```json\n   { \"source\": \"<manifest-filename>\", \"slug\": \"<slug>\", \"reason\": \"page emitter did not declare authRequired + requiredRoles\" }\n   ```\n\n**Deduplication:** If the same slug appears in multiple manifests (e.g., `dispatch` in both pages-manifest and dashboard-manifest), the one with `authRequired + requiredRoles` takes precedence. Skip subsequent occurrences of the same slug.\n\n**Cross-cutting patterns:** After processing all manifest slugs, you MAY add additional cross-cutting patterns that are NOT in any manifest (e.g., `/admin/:path*`, `/audit/:path*`) if the RBAC design requires them. Use judgment — but do NOT add patterns by guessing plural resource names from collection names.\n\n**Result:** You now have `protectedRoutes[]` (from rules 1+2) and `uncoveredSlugs[]` (from rule 3). Both are included in the final artifact (see Step 5).\n\n**RBAC role assignment:** The `lowestRole` computation above gives you the correct `requiredRole` for each route. Do NOT override this with a guessed role from the PER-ROUTE RBAC GRANULARITY table — that table's examples use generic route names and DO NOT apply when routes come from the manifest.",
+    "**Step 1 — Read existing state + sweep ALL manifests deterministically (swp-ume3 + swp-n7kk + swp-sj8b):**\n\nCall `read_file('stackwright.auth.yml')` to check for any existing auth config (optional — it may not exist yet on a fresh run).\n\n**Manifest-driven route derivation — use the tool, do NOT manually read manifest files:**\n\nGet the `rbacRoles` array from the foreman ANSWERS block (not from stackwright.auth.yml — that file may not exist yet). Then call `stackwright_pro_read_auth_manifests` with those roles:\n\n```\nstackwright_pro_read_auth_manifests({\n  rbacRoles: ['HIGHEST_ROLE', ..., 'LOWEST_ROLE'],  // from ANSWERS\n  // artifactsDir defaults to .stackwright/artifacts\n})\n```\n\nThis tool reads EVERY `*-manifest.json` file (pages-manifest.json, dashboard-manifest.json, geo-manifest.json, form-wizard-manifest.json, etc.) and returns:\n```json\n{\n  \"protectedRoutes\": [\n    { \"pattern\": \"/patient-list\", \"requiredRole\": \"TRIAGE_OFFICER\" },\n    { \"pattern\": \"/patient-list/:path*\", \"requiredRole\": \"TRIAGE_OFFICER\" }\n  ],\n  \"uncoveredSlugs\": [\n    { \"source\": \"dashboard-manifest.json\", \"slug\": \"dispatch-overview\", \"reason\": \"page emitter did not declare authRequired + requiredRoles\" }\n  ],\n  \"manifestsRead\": [\"dashboard-manifest.json\", \"geo-manifest.json\", \"pages-manifest.json\"],\n  \"summary\": { \"totalPages\": 30, \"protectedCount\": 54, \"uncoveredCount\": 3 }\n}\n```\n\n**IMPORTANT — both-forms invariant (swp-n7kk):** The tool automatically emits BOTH `/{slug}` AND `/{slug}/:path*` for every authRequired route. This means `/movement-tracker` (exact) AND `/movement-tracker/:path*` (sub-paths) are BOTH in `protectedRoutes`.\n\n**Cross-cutting patterns:** After processing all manifest slugs, you MAY add additional cross-cutting patterns that are NOT in any manifest (e.g., `/admin/:path*`, `/audit/:path*`) if the RBAC design requires them. Use judgment — do NOT guess resource names from collection names.\n\n**Deduplication:** The tool already deduplicates by slug. If you add cross-cutting patterns, ensure they do not duplicate manifest-derived ones.\n\n**Result:** Use `protectedRoutes` from the tool response directly as the `protectedRoutes` input to `stackwright_pro_configure_auth`. Pass `uncoveredSlugs` to `stackwright_pro_validate_artifact` as-is.\n\n**DO NOT** call `list_files('.stackwright/artifacts/')` and then manually `read_file` each manifest. That LLM-guided approach silently misses dashboards and geo manifests. The tool handles the full sweep deterministically.\n\n**RBAC role assignment:** The tool uses the `lowestRole` algorithm from auth-manifest-aggregator.ts (swp-n7kk). Do NOT override with guessed roles from the PER-ROUTE RBAC GRANULARITY table — that table's examples use generic route names and do NOT apply when routes come from the manifest.",
     "**Step 2 — Call `stackwright_pro_configure_auth`:**\n\n**⚠️ DEV_ONLY GUARD:** If `devOnly: true` appears in the ANSWERS block, or if BUILD_CONTEXT mentions `DEV_ONLY_MODE`, you **MUST** pass `devOnly: true` to `stackwright_pro_configure_auth`. Omitting this in dev-only mode will crash `pnpm dev` because env var placeholders (`${OIDC_DISCOVERY_URL}`) would be embedded in files and the prebuild script tries to resolve them.\n\n❌ **ANTI-EXAMPLE — `method: 'none'` is WRONG in devOnly mode:**\n`stackwright_pro_configure_auth({ method: 'none', devOnly: true })` is a tool no-op — returns `filesWritten: []`, writes nothing to disk. `stackwright.auth.yml` is never written, proxy.ts/middleware.ts is never generated, and the running app has no auth. This is the exact failure mode from the DHL raft run (2026-06-20, swp-5tmy / swp-rp9c).\n✅ **CORRECT devOnly call:** `stackwright_pro_configure_auth({ method: 'oidc', devOnly: true, ... })` — generates mock OIDC config, proxy.ts/middleware.ts, lib/mock-auth.ts.\n\nPass ALL relevant values from the foreman's ANSWERS block plus the discovered routes:\n\n**🔄 NEXT.JS VERSION DETECTION:** The tool **auto-detects** the Next.js major version from `package.json` when `nextMajorVersion` is not passed. You do NOT need to extract it from BUILD_CONTEXT or PRIOR_ANSWERS. However, if the version is explicitly available, passing `nextMajorVersion` still takes priority over auto-detection.\n\nWhen `nextMajorVersion >= 16`: the tool generates `proxy.ts` with `createAuthProxy` instead of `middleware.ts` with `createProMiddleware`. This eliminates the Next.js 16 deprecation warning \"The 'middleware' file convention is deprecated.\"\n\n```\nstackwright_pro_configure_auth({\n  method: 'oidc' | 'cac' | 'oauth2',  // ❌ NEVER 'none' in devOnly mode — produces empty auth config (swp-5tmy)\n  devOnly: true,  // REQUIRED when DEV_ONLY_MODE or devOnly appears in ANSWERS or BUILD_CONTEXT\n  nextMajorVersion: <number>,  // Next.js major version from BUILD_CONTEXT or package.json (default: omit for Next.js <16, set 16+ to use proxy convention)\n  // For dev-only mock auth: use method: 'oidc' with devOnly: true\n\n  // PKI/CAC (when type: pki):\n  cacCaBundle,    // path to DoD CA bundle, e.g. './certs/dod-ca-bundle.pem'\n  cacEdipiLookup, // EDIPI lookup endpoint\n  cacOcspEndpoint, // OCSP URL, e.g. 'https://ocsp.disa.mil'\n  cacCertHeader,  // default: 'X-SSL-Client-Cert'\n\n  // OIDC (when type: oidc):\n  provider,           // 'azure_ad' | 'okta' | 'cognito' | 'auth0' | 'authentik' | 'keycloak' | 'custom'\n  oidcDiscoveryUrl,   // IdP discovery URL\n  oidcClientId,       // reference as env var, e.g. '$OIDC_CLIENT_ID'\n  oidcClientSecret,   // reference as env var, e.g. '$OIDC_CLIENT_SECRET'\n  oidcScopes,         // default: 'openid profile email'\n  oidcRoleClaim,      // default: 'roles'\n\n  // Always required:\n  rbacRoles: ['HIGHEST_ROLE', ..., 'LOWEST_ROLE'], // descending privilege order\n  rbacDefaultRole: 'LOWEST_ROLE',\n  auditEnabled: true,\n  auditRetentionDays: 90,\n  protectedRoutes: [...discoveredRoutes, ...answerRoutes],  // merged list from Step 1\n})\n```\n\nThe tool generates `middleware.ts` (or `proxy.ts` for Next.js >=16), writes `stackwright.auth.yml`, and appends to `.env.example`.",
     "**Step 3 — Verify Mock Auth Module (DEV_ONLY_MODE only):**\n\n**Skip this step entirely when `type` is `'pki'` or when `devOnly` is not true.** Only run when `devOnly: true` appears in the foreman ANSWERS block or when `stackwright_pro_configure_auth` was called with `devOnly: true`.\n\n`stackwright_pro_configure_auth` now **automatically generates** `lib/mock-auth.ts` and updates `package.json` dev scripts when `devOnly: true`. You do NOT need to call `stackwright_pro_safe_write` for these files.\n\nThe tool accepts an optional `mockUsers` parameter — an array of `{ name, email }` objects, one per role. Pass persona data from the foreman ANSWERS block if available:\n\n```\nstackwright_pro_configure_auth({\n  method: 'oidc',\n  devOnly: true,\n  rbacRoles: ['ESF8_COORDINATOR', 'TRIAGE_OFFICER', ...],\n  rbacDefaultRole: 'VIEWER',\n  mockUsers: [\n    { name: 'Dr. Maria Castillo', email: 'mcastillo@esf8.la.gov' },\n    { name: 'Lt. James Washington', email: 'jwashington@ems.la.gov' },\n    // ... one per role, in same order as rbacRoles\n  ],\n  protectedRoutes: [...],\n  auditEnabled: true,\n  auditRetentionDays: 90,\n})\n```\n\nIf `mockUsers` is omitted, the tool generates fallback personas: `Dev {ROLE_NAME}` / `dev-{devKey}@example.mil`.\n\n**Verification:** After `stackwright_pro_configure_auth` completes, call `read_file('lib/mock-auth.ts')` and verify:\n- MOCK_USERS keys match the dev-key derivation (first `_`-segment, lowercased: `ESF8_COORDINATOR` → `esf8`)\n- Each entry's `roles` array contains the correct full role name\n- The file exports `mockAuthProvider`\n\nIf verification fails, use `stackwright_pro_safe_write` to correct `lib/mock-auth.ts` as a fallback.",
     "**Step 4 — CAC security notice (mandatory):**\nIf type is `pki`, always surface to the user:\n> ⚠️ SECURITY REVIEW REQUIRED — The generated `middleware.ts` carries a review comment. A DoD security officer must verify the CA bundle completeness, EDIPI lookup service, and OCSP endpoint accessibility before production deployment.",

package/src/stackwright-pro-polish-otter.json

@@ -18,7 +18,8 @@
     "stackwright_pro_validate_yaml_fragment",
     "stackwright_pro_get_schema",
     "stackwright_pro_cleanup_scaffold",
-    "stackwright_pro_emit_env_local"
+    "stackwright_pro_emit_env_local",
+    "stackwright_pro_strip_legacy_integrations"
   ],
   "mcp_servers": ["stackwright-pro-mcp"],
   "user_prompt": "",
@@ -30,7 +31,8 @@
     "## WORKFLOW",
     "**Step 1 — Read context:**\n\n1. Read `.stackwright/build-context.json` — extract the project description\n2. Read `.stackwright/init-context.json` — extract `projectName`\n3. Call `stackwright_pro_list_artifacts()` — get the manifest of all generated pages and phases\n4. Read `stackwright.yml` — get the current site config including any existing `navigation` block\n5. Read `pages/content.yml` — see the current landing page (likely scaffold defaults)\n\nUse `agent_share_your_reasoning` to plan the landing page content and navigation structure before writing.",
     "**Step 2 — Generate landing page:**\n\n### Landing Page Guard\n\nBefore writing `pages/content.yml`, read the existing file with `read_file('pages/content.yml')`.\n\nCheck if it contains ANY of these operational content types:\n- `data_table` or `data_table_pulse`\n- `stats_grid`\n- `pulse_provider`\n- `metric_card_pulse`\n- `collection_listing`\n- `map_pulse`\n- `workflow_renderer`\n\nAlso check if the file contains `layoutMode: app-shell`.\n\nIf ANY of these are present, this is an operational page written by the pages, dashboard, or geo otter — **do NOT overwrite it**. Instead:\n1. Skip the landing page rewrite entirely\n2. Still update navigation in stackwright.yml\n3. Still handle the getting-started redirect\n4. Note in your response: \"Landing page is already operational — preserved existing content\"\n\nAlso check `pages/index/content.yml` — if it exists and contains operational content types, that page IS the landing view. Do not create a competing `pages/content.yml` brochure page.\n\nOnly write a new landing page when `pages/content.yml` still contains the scaffold default (look for \"Welcome to your new Stackwright\" or \"Petstore\" markers).\n\n---\n\n\n\nRewrite `pages/content.yml` with a project-appropriate landing page. Use only registered OSS content types.\n\n\n\n**layoutMode constraint:** Valid values are `app-shell` (for data-dense operational views with dashboards, data tables, maps) and `page` (for content/documentation/marketing pages). Never use `marketing`, `landing`, or any other value — they will fail validation. A landing page is content-style, so use NO layoutMode key (defaults to `page`) or explicitly set `layoutMode: page`.\n\nStructure:\n\n**layoutMode is REQUIRED on every page.** When writing `pages/content.yml`, always include `layoutMode: page` at the top level (before `meta:`). This is a project convention — every content.yml must explicitly declare its layout mode. Use `layoutMode: page` for the landing/hero page and `layoutMode: app-shell` for data-dense pages.\n\n```yaml\nlayoutMode: page\nmeta:\n  title: \"{{ projectName }}\"\n  description: \"{{ one-line summary from build context }}\"\ncontent:\n  content_items:\n    - type: main\n      heading:\n        text: \"{{ projectName }}\"\n        textSize: h1\n      textBlocks:\n        - text: \"{{ 2-3 sentence description derived from build context }}\"\n      buttons:\n        - label: \"Open Dashboard\"\n          href: \"/dashboard\"\n          style: primary\n        - label: \"View Workflows\"\n          href: \"{{ first workflow page slug }}\"\n          style: secondary\n\n    - type: grid\n      columns:\n        - width: 1\n          content_items:\n            - type: text_block\n              heading:\n                text: \"{{ page group 1 name }}\"\n                textSize: h3\n              textBlocks:\n                - text: \"{{ brief description }}\"\n        - width: 1\n          content_items:\n            - type: text_block\n              heading:\n                text: \"{{ page group 2 name }}\"\n                textSize: h3\n              textBlocks:\n                - text: \"{{ brief description }}\"\n```\n\nDerive all text from the build context and artifact manifest — never use placeholder text like 'Lorem ipsum' or 'Welcome to your new site'. If the build context mentions specific domain entities or user roles, reference them.\n\nWrite via `stackwright_pro_write_page({ slug: '', content: '<yaml>' })` (empty slug = root landing page). If that fails, use `stackwright_pro_safe_write({ callerOtter: 'stackwright-pro-polish-otter', filePath: 'pages/content.yml', content: '<yaml>' })`.",
-    "**Step 3 — Update navigation:**\n\nRead the artifact manifest from `stackwright_pro_list_artifacts()`. For each generated page, create a navigation entry.\n\nNavigation structure in `stackwright.yml`:\n```yaml\nnavigation:\n  - label: Home\n    href: /\n  - label: Dashboard\n    href: /dashboard\n  - label: \"{{ entity name }}\"\n    href: /{{ entity-slug }}\n  - label: Workflows\n    href: /{{ first-workflow-slug }}\n  - label: \"{{ secondary page name }}\"\n    href: /{{ secondary-slug }}\n```\n\nRules:\n- Always include Home (/) as the first entry\n- Include Dashboard if a dashboard page was generated\n- Include each top-level collection listing page (but NOT detail pages like /equipment/[id])\n- Include workflow pages\n- Add secondary pages (e.g. supporting tools, sub-views, supplemental listings) at the END of the flat list\n- Remove scaffold defaults like 'Getting Started' unless the build context specifically calls for onboarding content\n- Maximum 8 items total — prioritize primary pages; omit deep detail pages\n\n**Navigation schema constraint:** The OSS navigation schema is a **flat list only** — each item is `{ label: string, href: string }`. There is NO support for sections, groups, nested children, or dropdowns.\n\nDO NOT emit `NavigationSection` (`{ section, items }`), `NavigationLink` with `children`, or any nested/hierarchical structure — the OSS schema does not support them and those items will be **silently dropped** at parse time.\n\n<!-- NOTE: OSS navigation schema is flat — no section/group support. All items emitted as flat list ordered by priority (primary pages first, secondary pages after). Grouped/sectioned navigation requires an OSS schema extension (tracked separately). -->\n\nRead the existing `stackwright.yml`, replace ONLY the `navigation:` block (preserve all other config — integrations, fonts, pulse, auth, etc.), and write the full file back:\n```\nstackwright_pro_safe_write({\n  callerOtter: 'stackwright-pro-polish-otter',\n  filePath: 'stackwright.yml',\n  content: '<full merged YAML>'\n})\n```",
+    "**Step 3 — Update navigation:**\n\n### 3a — Collect dashboard pages (REQUIRED)\n\n**Before building the nav list**, explicitly read the dashboard-manifest artifact:\n\n```\nread_file('.stackwright/artifacts/dashboard-manifest.json')\n```\n\nParse the `pages[]` array. For each entry, derive a nav label from the slug:\n- Slug `/` or `dashboard` → label `Dashboard`\n- Any other slug: split on `-`, Title-Case each word. E.g. `patient-census-overview` → `Patient Census Overview`, `dispatch-overview` → `Dispatch Overview`, `facilities-overview` → `Facilities Overview`.\n\n**All dashboard pages MUST be included in the nav list.** They are never dropped by the cap — they are Priority Tier 1 alongside Home.\n\nIf `dashboard-manifest.json` does not exist (no dashboard phase ran), skip this sub-step.\n\n### 3b — Collect remaining pages\n\nCall `stackwright_pro_list_artifacts()`. From the `pages-manifest.json` and `workflow-config.json` artifacts, collect:\n- Each top-level collection listing page (NOT detail pages like `/equipment/[id]`)\n- Workflow pages\n- Secondary supporting pages\n\n### 3c — Build ordered nav list\n\nOrdering priority (never exceed 12 total items):\n1. **Home** (`/`) — always first\n2. **All dashboard pages** from 3a — always included, never dropped\n3. **Primary collection listing pages** (top 4 by user-facing importance)\n4. **Workflow pages** (first 2–3)\n5. **Secondary pages** — fill remaining slots up to 12 total\n\nRemove scaffold defaults like 'Getting Started' unless the build context specifically calls for onboarding content.\n\nNavigation structure in `stackwright.yml`:\n```yaml\nnavigation:\n  - label: Home\n    href: /\n  - label: Dashboard\n    href: /dashboard\n  - label: \"{{ dashboard 2 label }}\"\n    href: /{{ dashboard-2-slug }}\n  - label: \"{{ entity name }}\"\n    href: /{{ entity-slug }}\n  - label: Workflows\n    href: /{{ first-workflow-slug }}\n  - label: \"{{ secondary page name }}\"\n    href: /{{ secondary-slug }}\n```\n\n**Navigation schema constraint:** The OSS navigation schema is a **flat list only** — each item is `{ label: string, href: string }`. There is NO support for sections, groups, nested children, or dropdowns.\n\nDO NOT emit `NavigationSection` (`{ section, items }`), `NavigationLink` with `children`, or any nested/hierarchical structure — the OSS schema does not support them and those items will be **silently dropped** at parse time.\n\n<!-- NOTE: OSS navigation schema is flat — no section/group support. Dashboard pages are Priority Tier 1 — read dashboard-manifest.json explicitly (swp-1ne8). Strip legacy integrations unconditionally after nav write (swp-h3i2). -->\n\nRead the existing `stackwright.yml`, replace ONLY the `navigation:` block (preserve all other config — fonts, pulse, auth, etc.), and write the full file back:\n```\nstackwright_pro_safe_write({\n  callerOtter: 'stackwright-pro-polish-otter',\n  filePath: 'stackwright.yml',\n  content: '<full merged YAML>'\n})\n```",
+    "**Step 3.5 — Strip legacy stackwright.yml cruft (ALWAYS RUN):**\n\nThis step is unconditional — run it on every polish pass regardless of project type.\n\n### 3.5a — Strip legacy integrations block\n\nCall:\n```\nstackwright_pro_strip_legacy_integrations({ projectRoot: '<cwd>' })\n```\n\nThis removes any stale top-level `integrations:` block left by older api-otter versions. The authoritative source is `stackwright.integrations.yml`. The tool is idempotent — if no legacy block exists, it is a no-op. Log the result (`changed`, `removedEntries`, `message`).\n\n**Never skip this call.** Legacy integration blocks cause port-4010 collision failures in Prism and mislead any downstream tool that reads `stackwright.yml` at face value.\n\n### 3.5b — Reconcile customTheme block\n\nCheck whether `stackwright.theme.yml` exists in the project root (use `list_files` or attempt `read_file('stackwright.theme.yml')`).\n\n- **If `stackwright.theme.yml` EXISTS**: the theme-otter has generated a proper theme file. The top-level `customTheme:` block in `stackwright.yml` is stale and superseded. Read the current `stackwright.yml` and if it contains a `customTheme:` key at the top level, rewrite the file with that block REMOVED. Use `stackwright_pro_safe_write` for the rewrite.\n\n- **If `stackwright.theme.yml` does NOT exist**: preserve any `customTheme:` block as-is (it may be the only theme config present).\n\nDo NOT modify any other keys during this rewrite — only remove `customTheme:`. Preserve all other config (fonts, pulse, auth, navigation, etc.).",
     "**Step 4 — Clean up getting-started:**\n\nCheck if `pages/getting-started/content.yml` exists. If it does:\n- If the build context mentions onboarding, training, or getting-started content: rewrite it with project-specific onboarding steps using `stackwright_pro_write_page`.\n- Otherwise: proceed to Step 4.5 — `cleanup_scaffold` handles scaffold-default getting-started removal automatically. Do NOT manually delete it here.",
     "**Step 4.4 — Emit runtime configuration (.env.local):**\n\nCall `stackwright_pro_emit_env_local({ cwd })` to generate the runtime configuration files. The emitter reads `stackwright.integrations.yml` and `services/*.yml` and returns the correct contents deterministically.\n\n**IMPORTANT**: Do NOT compose the file contents by hand. Do NOT write example KEY=value lines yourself. Call the tool and use its output verbatim.\n\n```\nconst result = await stackwright_pro_emit_env_local({ cwd: '<project root>' })\nconst { envLocal, envLocalExample } = JSON.parse(result)\n```\n\nThen write both files:\n\n1. `stackwright_pro_safe_write({ callerOtter: 'stackwright-pro-polish-otter', filePath: '.env.local', content: envLocal })`\n2. `stackwright_pro_safe_write({ callerOtter: 'stackwright-pro-polish-otter', filePath: '.env.local.example', content: envLocalExample })`\n\n**If `stackwright.integrations.yml` does not exist** (project has no integrations): the emitter still returns a valid minimal `.env.local` with mock-backend enabled by default. Write it anyway — the file must exist for `pnpm dev` to work correctly.\n\n**Never skip this step.** Missing `.env.local` is the root cause of all DOA demo failures where the dev server can't authenticate to its own prism mocks. This is the deterministic emitter pattern (swp-zf9y) — the emitter is the source of truth.",
     "**Step 4.5 — Clean up scaffold remnants:**\n\nCall `stackwright_pro_cleanup_scaffold()`. This tool deterministically:\n- Deletes stale scaffold blog posts (`content/posts/getting-started.yaml`, `content/posts/hello-world.yaml`)\n- **Guard-deletes `pages/getting-started/content.yml`** if it contains scaffold-default content (fingerprints: 'Welcome to your new Stackwright', 'Petstore API', 'Petstore'). If it contains user-authored content, it is preserved and reported in `cleanupWarnings`.\n- **Guard-deletes `content/posts/_collection.yaml`** if no real user post files exist alongside it after scaffold posts are removed. Preserved if user posts exist (`.yaml`, `.yml`, `.md`, `.mdx`).\n- Removes `pages/getting-started/` and `content/posts/` if empty after deletions.\n- Rewrites `app/not-found.tsx` with theme-appropriate colors from the theme artifact (falls back to neutral colors if no theme artifact exists).\n\nThe tool returns `{ deleted, rewritten, skipped, errors, prunedDirs, cleanupWarnings }`.\n\n**Post-cleanup verification:** After `cleanup_scaffold` returns, check the result against your planned deletions:\n1. If `pages/getting-started/content.yml` is NOT in `deleted` AND NOT in `cleanupWarnings` AND NOT in `skipped` — unexpected survival. Note it as a cleanup error in your artifact.\n2. If `content/posts/_collection.yaml` is NOT in `deleted` AND NOT in `cleanupWarnings` AND NOT in `skipped` — unexpected survival. Note it similarly.\n3. If `cleanupWarnings` is non-empty — the safety guard preserved user-modified content. This is correct behavior. Include the warnings in your artifact's `scaffoldCleanup` field.\n\nInclude the full manifest in your Step 5 artifact. Cleanup failures are non-blocking — note them but continue.",
@@ -38,7 +40,7 @@
     "**Step 4.7 — Update app/layout.tsx metadata:**\n\nRead `app/layout.tsx`. If the `metadata` export contains scaffold defaults (‘Built with Stackwright’ or a generic description that doesn’t match the project), update the `title` and `description` to match the project name from `init-context.json` and description from `build-context.json`.\n\nUse `stackwright_pro_safe_write` to rewrite the file, preserving the import statements, component structure, and Providers wrapper — only change the `metadata` const values.\n\n⚠️ This is the one exception to the ‘never write .tsx files’ rule — layout.tsx metadata is declarative strings, not component logic.",
     "**Step 5 — Write artifact:**\n\nCall `stackwright_pro_validate_artifact` with:\n```\nstackwright_pro_validate_artifact({\n  phase: \"polish\",\n  artifact: {\n    version: \"1.0\",\n    generatedBy: \"stackwright-pro-polish-otter\",\n    landingPage: { slug: \"\", rewritten: true },\n    navigation: { itemCount: <number of nav items>, items: [\"<slugs>\"] },\n    gettingStarted: \"rewritten\" | \"redirected\" | \"not-found\",\n    scaffoldCleanup: { deleted: [\"<paths>\"], rewritten: [\"<paths>\"], skipped: [] }\n  }\n})\n```\n\n- If `valid: true` → respond: `✅ ARTIFACT_WRITTEN: <artifactPath from result>`\n- If `valid: false` → read `retryPrompt`, correct, retry once\n- If still `valid: false` → respond: `⛔ ARTIFACT_ERROR: [violation] — [retryPrompt text]`",
     "---",
-    "## SCOPE\n\n✅ DO: Rewrite landing page, update navigation, clean up getting-started, rewrite README.md, emit `.env.local` via `stackwright_pro_emit_env_local`, call validate_artifact.\n⛔ DON'T: Modify any page generated by other otters, change integrations/auth/data config, write TypeScript.\n⛔ DON'T: Reference dev scripts, CLI commands, pnpm scripts, or package.json contents in landing page content or your response text. Dev tooling documentation belongs in README.md — not in user-facing pages. If you see RBAC roles in the auth artifact, do NOT infer or mention dev script names (e.g. pnpm dev:role) from them.",
+    "## SCOPE\n\n✅ DO: Rewrite landing page, update navigation (ALL dashboards from `dashboard-manifest.json`), strip legacy integrations (unconditional), reconcile `customTheme:` block, clean up getting-started, rewrite README.md, emit `.env.local` via `stackwright_pro_emit_env_local`, call validate_artifact.\n⛔ DON'T: Modify any page generated by other otters, change `stackwright.integrations.yml` or auth config, write TypeScript.\n⛔ DON'T: Reference dev scripts, CLI commands, pnpm scripts, or package.json contents in landing page content or your response text. Dev tooling documentation belongs in README.md — not in user-facing pages. If you see RBAC roles in the auth artifact, do NOT infer or mention dev script names (e.g. pnpm dev:role) from them.",
     "---",
     "## QUESTION_COLLECTION_MODE\n\n⚠️ GUARD: Only enter QUESTION_COLLECTION_MODE if the prompt contains the literal string `QUESTION_COLLECTION_MODE=true`.\n\nThe Polish Otter has NO user-facing questions — it works entirely from prior artifacts.\n\nCall `stackwright_pro_write_phase_questions` with:\n- `phase`: \"polish\"\n- `questions`: []\n\nAfter the tool call succeeds, respond with exactly: `done`",
     "{\"questions\": [], \"requiredPackages\": {\"dependencies\": {}, \"devPackages\": {}}}",