@prismer/runtime 2.0.8 → 2.2.63

package/built-in-skills/tdd/tests.md

@@ -0,0 +1,61 @@
+# Good and Bad Tests
+
+## Good Tests
+
+**Integration-style**: Test through real interfaces, not mocks of internal parts.
+
+```typescript
+// GOOD: Tests observable behavior
+test("user can checkout with valid cart", async () => {
+  const cart = createCart();
+  cart.add(product);
+  const result = await checkout(cart, paymentMethod);
+  expect(result.status).toBe("confirmed");
+});
+```
+
+Characteristics:
+
+- Tests behavior users/callers care about
+- Uses public API only
+- Survives internal refactors
+- Describes WHAT, not HOW
+- One logical assertion per test
+
+## Bad Tests
+
+**Implementation-detail tests**: Coupled to internal structure.
+
+```typescript
+// BAD: Tests implementation details
+test("checkout calls paymentService.process", async () => {
+  const mockPayment = jest.mock(paymentService);
+  await checkout(cart, payment);
+  expect(mockPayment.process).toHaveBeenCalledWith(cart.total);
+});
+```
+
+Red flags:
+
+- Mocking internal collaborators
+- Testing private methods
+- Asserting on call counts/order
+- Test breaks when refactoring without behavior change
+- Test name describes HOW not WHAT
+- Verifying through external means instead of interface
+
+```typescript
+// BAD: Bypasses interface to verify
+test("createUser saves to database", async () => {
+  await createUser({ name: "Alice" });
+  const row = await db.query("SELECT * FROM users WHERE name = ?", ["Alice"]);
+  expect(row).toBeDefined();
+});
+
+// GOOD: Verifies through interface
+test("createUser makes user retrievable", async () => {
+  const user = await createUser({ name: "Alice" });
+  const retrieved = await getUser(user.id);
+  expect(retrieved.name).toBe("Alice");
+});
+```

package/built-in-skills/team/SKILL.md

@@ -1,5 +1,6 @@
 ---
 name: team
+scope: persistence
 description: Invite humans into a workspace, propose collaborators for a project, and inspect the current human team. Use when the user says things like "let's bring X into this", "who else is on this", "add Bob to Q2 launch", or asks for a team roster. NEVER mints invites silently — the human must press a button.
 ---
 
@@ -9,7 +10,7 @@ Use this skill when work needs another human in the loop. The workspace + projec
 
 ## ⛔ Hard rules — human-in-loop
 
-1. **Never auto-send an invite.** Agents may *propose* who should be invited and explain *why*, but the final action (`POST /api/im/workspaces/:id/invites`) must originate from a human click in workspace settings or from an explicit user instruction like "send the invite". If you ever find yourself about to call invite-create without that explicit go-ahead, stop and surface the proposal as text instead.
+1. **Never auto-send an invite.** Agents may propose who should be invited and why. This skill's supported route for the final action is the human click in workspace settings. Even when the user asks to send an invite, route them to that UI; do not invent an invite CLI or bypass the supported confirmation path with a raw endpoint.
 2. **Never expose member emails.** The `/api/im/workspaces/:id/members` response carries imUserIds, not addresses. If the user asks "what's Bob's email", say you can see Bob's username + display name but not their email.
 3. **Distinguish workspace member from project member.** Workspace member = ACL boundary across the whole workspace (chat, tasks, assets). Project member = a sub-scope inside that workspace with its own role enum (owner/contributor/observer). Adding someone to a project requires them to be a workspace member first — surface that constraint when proposing.
 4. **Never silently re-add a removed member.** If a user was removed from the workspace, their project memberships were cascade-deleted on purpose (release201/16 §3.2.3). Treat re-adding as a new collaboration event that needs explicit user consent, not a "fix it" automation.
@@ -19,7 +20,7 @@ Use this skill when work needs another human in the loop. The workspace + projec
 - The user names someone who isn't already on the workspace: *"Have Maya look at this"*, *"Loop Bob in on Q2 launch"*.
 - The user asks who's on the team or what the roster looks like: *"who has access to this workspace"*, *"who's working on Q2 launch"*.
 - The user asks to remove someone, change someone's role, or move someone between projects.
-- An agent (e.g. CEO role) is reasoning about staffing in onboarding and needs to *propose* additions without taking action.
+- An agent (e.g. Team Manager role) is reasoning about staffing in onboarding and needs to *propose* additions without taking action.
 
 ## What the platform exposes
 

package/built-in-skills/web-artifacts-builder/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: web-artifacts-builder
-description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
+scope: coding
+description: Suite of tools for creating elaborate, multi-component Prismer HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
 license: Complete terms in LICENSE.txt
 ---
 
@@ -27,7 +28,7 @@ registers the asset so the chat renderer can offer a preview/open button.
 
 # Web Artifacts Builder
 
-To build powerful frontend claude.ai artifacts, follow these steps:
+To build powerful frontend Prismer artifacts, follow these steps:
 1. Initialize the frontend repo using `scripts/init-artifact.sh`
 2. Develop your artifact by editing the generated code
 3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
@@ -79,7 +80,7 @@ To bundle the React app into a single HTML artifact:
 bash scripts/bundle-artifact.sh
 ```
 
-This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be directly shared in Claude conversations as an artifact.
+This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be directly shared in Prismer conversations as an artifact.
 
 **Requirements**: Your project must have an `index.html` in the root directory.
 

package/built-in-skills/web-artifacts-builder/scripts/bundle-artifact.sh

@@ -1,5 +1,5 @@
 #!/bin/bash
-set -e
+set -euo pipefail
 
 echo "📦 Bundling React app to single HTML artifact..."
 
@@ -31,17 +31,19 @@ if [ ! -f ".parcelrc" ]; then
 EOF
 fi
 
-# Clean previous build
-echo "🧹 Cleaning previous build..."
-rm -rf dist bundle.html
+# Only clean the directory created by this invocation.
+BUILD_DIR=$(mktemp -d "./.artifact-build.XXXXXX")
+trap 'rm -rf -- "$BUILD_DIR"' EXIT
 
 # Build with Parcel
 echo "🔨 Building with Parcel..."
-pnpm exec parcel build index.html --dist-dir dist --no-source-maps
+pnpm exec parcel build index.html --dist-dir "$BUILD_DIR/dist" --no-source-maps
 
 # Inline everything into single HTML
 echo "🎯 Inlining all assets into single HTML file..."
-pnpm exec html-inline dist/index.html > bundle.html
+pnpm exec html-inline "$BUILD_DIR/dist/index.html" > "$BUILD_DIR/bundle.html"
+test -s "$BUILD_DIR/bundle.html"
+mv -- "$BUILD_DIR/bundle.html" bundle.html
 
 # Get file size
 FILE_SIZE=$(du -h bundle.html | cut -f1)
@@ -51,4 +53,4 @@ echo "✅ Bundle complete!"
 echo "📄 Output: bundle.html ($FILE_SIZE)"
 echo ""
 echo "You can now use this single HTML file as an artifact in Claude conversations."
-echo "To test locally: open bundle.html in your browser"
+echo "To test locally: open bundle.html in your browser"

package/built-in-skills/web-artifacts-builder/scripts/init-artifact.sh

@@ -1,7 +1,13 @@
 #!/bin/bash
 
 # Exit on error
-set -e
+set -euo pipefail
+
+PROJECT_NAME="${1:-}"
+if [[ ! "$PROJECT_NAME" =~ ^[a-zA-Z0-9][a-zA-Z0-9_-]*$ ]] || [[ -e "$PROJECT_NAME" ]]; then
+  echo 'Usage: init-artifact.sh <new-project-name>; target must not exist' >&2
+  exit 1
+fi
 
 # Detect Node version
 NODE_VERSION=$(node -v | cut -d'v' -f2 | cut -d'.' -f1)
@@ -14,77 +20,39 @@ if [ "$NODE_VERSION" -lt 18 ]; then
   exit 1
 fi
 
-# Set Vite version based on Node version
-if [ "$NODE_VERSION" -ge 20 ]; then
-  VITE_VERSION="latest"
-  echo "✅ Using Vite latest (Node 20+)"
-else
-  VITE_VERSION="5.4.11"
-  echo "✅ Using Vite $VITE_VERSION (Node 18 compatible)"
-fi
+VITE_VERSION="5.4.11"
 
 # Detect OS and set sed syntax
 if [[ "$OSTYPE" == "darwin"* ]]; then
-  SED_INPLACE="sed -i ''"
+  SED_INPLACE=(sed -i '')
 else
-  SED_INPLACE="sed -i"
+  SED_INPLACE=(sed -i)
 fi
 
 # Check if pnpm is installed. Release 201 sandbox image bakes pnpm@9.
-# If pnpm is missing the image is out of date (or we're in a dev env);
-# try corepack as a per-user fallback (no sudo), else fail loudly so the
-# agent surfaces the missing-baseline error rather than installing pnpm
-# at task time and contaminating the workdir.
+# Do not change global Corepack/pnpm state from a project scaffold.
 if ! command -v pnpm &> /dev/null; then
-  echo "📦 pnpm not found. Trying corepack..."
-  if command -v corepack &> /dev/null; then
-    corepack enable
-    corepack prepare pnpm@9 --activate
-  else
-    echo "❌ Error: pnpm is required but neither pnpm nor corepack is available."
-    echo "   Sandbox image is missing pnpm — rebuild the daemon image with the"
-    echo "   release 201 baseline (infra/sandbox-image/Dockerfile.daemon)."
-    exit 1
-  fi
-fi
-
-# Check if project name is provided
-if [ -z "$1" ]; then
-  echo "❌ Usage: ./create-react-shadcn-complete.sh <project-name>"
+  echo "pnpm is required; install it explicitly before running this scaffold." >&2
   exit 1
 fi
 
-PROJECT_NAME="$1"
-SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-COMPONENTS_TARBALL="$SCRIPT_DIR/shadcn-components.tar.gz"
-
-# Check if components tarball exists
-if [ ! -f "$COMPONENTS_TARBALL" ]; then
-  echo "❌ Error: shadcn-components.tar.gz not found in script directory"
-  echo "   Expected location: $COMPONENTS_TARBALL"
-  exit 1
-fi
 
 echo "🚀 Creating new React + Vite project: $PROJECT_NAME"
 
-# Create new Vite project (always use latest create-vite, pin vite version later)
-pnpm create vite "$PROJECT_NAME" --template react-ts
+# Use a fixed template compatible with the declared Node baseline.
+pnpm dlx create-vite@5.5.5 "$PROJECT_NAME" --template react-ts
 
 # Navigate into project directory
 cd "$PROJECT_NAME"
 
 echo "🧹 Cleaning up Vite template..."
-$SED_INPLACE '/<link rel="icon".*vite\.svg/d' index.html
-$SED_INPLACE 's/<title>.*<\/title>/<title>'"$PROJECT_NAME"'<\/title>/' index.html
+"${SED_INPLACE[@]}" '/<link rel="icon".*vite\.svg/d' index.html
+"${SED_INPLACE[@]}" 's/<title>.*<\/title>/<title>'"$PROJECT_NAME"'<\/title>/' index.html
 
 echo "📦 Installing base dependencies..."
 pnpm install
 
-# Pin Vite version for Node 18
-if [ "$NODE_VERSION" -lt 20 ]; then
-  echo "📌 Pinning Vite to $VITE_VERSION for Node 18 compatibility..."
-  pnpm add -D vite@$VITE_VERSION
-fi
+pnpm add -D "vite@$VITE_VERSION"
 
 echo "📦 Installing Tailwind CSS and dependencies..."
 pnpm install -D tailwindcss@3.4.1 postcss autoprefixer @types/node tailwindcss-animate
@@ -101,7 +69,7 @@ export default {
 EOF
 
 echo "📝 Configuring Tailwind with shadcn theme..."
-cat > tailwind.config.js << 'EOF'
+cat > tailwind.config.cjs << 'EOF'
 /** @type {import('tailwindcss').Config} */
 module.exports = {
   darkMode: ["class"],
@@ -284,10 +252,6 @@ echo "📦 Installing shadcn/ui dependencies..."
 pnpm install @radix-ui/react-accordion @radix-ui/react-aspect-ratio @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-collapsible @radix-ui/react-context-menu @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-hover-card @radix-ui/react-label @radix-ui/react-menubar @radix-ui/react-navigation-menu @radix-ui/react-popover @radix-ui/react-progress @radix-ui/react-radio-group @radix-ui/react-scroll-area @radix-ui/react-select @radix-ui/react-separator @radix-ui/react-slider @radix-ui/react-slot @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-toggle @radix-ui/react-toggle-group @radix-ui/react-tooltip
 pnpm install sonner cmdk vaul embla-carousel-react react-day-picker react-resizable-panels date-fns react-hook-form @hookform/resolvers zod
 
-# Extract shadcn components from tarball
-echo "📦 Extracting shadcn/ui components..."
-tar -xzf "$COMPONENTS_TARBALL" -C src/
-
 # Create components.json for reference
 echo "📝 Creating components.json config..."
 cat > components.json << 'EOF'
@@ -297,7 +261,7 @@ cat > components.json << 'EOF'
   "rsc": false,
   "tsx": true,
   "tailwind": {
-    "config": "tailwind.config.js",
+    "config": "tailwind.config.cjs",
     "css": "src/index.css",
     "baseColor": "slate",
     "cssVariables": true,
@@ -313,6 +277,15 @@ cat > components.json << 'EOF'
 }
 EOF
 
+mkdir -p src/lib
+cat > src/lib/utils.ts << 'EOF'
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+export function cn(...inputs: ClassValue[]) { return twMerge(clsx(inputs)); }
+EOF
+# Fetch the published component registry instead of a nonexistent local archive.
+pnpm dlx shadcn@2.3.0 add --all --yes
+
 echo "✅ Setup complete! You can now use Tailwind CSS and shadcn/ui in your project."
 echo ""
 echo "📦 Included components (40+ total):"

package/built-in-skills/webapp-qa/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/built-in-skills/webapp-qa/NOTICE.md

@@ -0,0 +1,37 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## Engineering adaptation (2026-09-23)
+
+Source: https://github.com/NousResearch/hermes-agent/tree/1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4/skills/software-development/dogfood
+
+Upstream authors: Teknium (teknium1), Hermes Agent.
+Hermes MIT copyright (c) 2025 Nous Research is preserved in LICENSE.
+All bundled references/templates/scripts remain covered by that notice unless
+an additional license is explicitly supplied. External CLI binaries, services,
+accounts and downloaded assets are not redistributed by this skill and retain
+their own terms. No API keys or third-party runtime packages are bundled.
+
+Prismer modifications: unique discovery/ownership mapping where applicable,
+resource-path and authorization corrections, bounded helpers, honest readiness
+and verification states. See docs/bugfix223/implementation-engineering.md in the
+source repository for resource mapping, tests and remaining live acceptance.

package/built-in-skills/webapp-qa/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: webapp-qa
+scope: common
+description: Perform scoped exploratory QA of a web application, reproduce defects, collect screenshots and console evidence, and deliver a prioritized report.
+license: MIT
+metadata:
+  nativeReplaces: [dogfood]
+  upstream: Hermes Agent skills/software-development/dogfood at 1a1f4a59e2
+---
+# Web Application QA
+
+For the full five-phase exploratory method, read references/dogfood/GUIDE.md;
+its taxonomy and report-template links resolve within this bundle.
+
+Use the user-supplied target URL, scope and existing test accounts. Inspect the
+available browser tools or Playwright setup first; never invent browser tool
+names. Without a working browser, report the blocker and limit claims to checks
+actually performed.
+
+1. Map the main user journeys, navigation, forms and error/empty states.
+2. Exercise each journey with positive and negative inputs. Inspect console and
+   network failures after navigation and significant interactions.
+3. Inspect screenshots at desktop and mobile sizes for clipping, overlap,
+   loading failures and keyboard accessibility.
+4. Reproduce each suspected defect. Record URL, exact steps, expected/actual
+   behavior, console evidence and screenshot file. Separate application bugs
+   from unavailable dependencies or test-environment failures.
+5. Deduplicate, prioritize by user impact, and use references/issue-taxonomy.md
+   plus templates/dogfood-report-template.md as report structure.
+6. State tested, untested and blocked areas. Passing HTTP status alone is not a
+   passing user journey. Never fill missing evidence with plausible descriptions.
+7. Attach the report and requested evidence as task-bound assets using the
+   actual platform delivery contract. Do not invent flags or use MEDIA markers.
+
+Use a task-owned local fixture for browser-tool smoke tests before touching a
+live account. Record desktop/mobile viewport, keyboard, console, clipping and
+positive/negative form results independently; a fixture does not certify the
+user's real application.
+
+Keep test mutations within the user's authorized scope. Do not submit real
+payments or send external messages as incidental QA actions.

package/built-in-skills/webapp-qa/references/dogfood/GUIDE.md

@@ -0,0 +1,161 @@
+
+# Dogfood: Systematic Web Application QA Testing
+
+## Overview
+
+This skill guides you through systematic exploratory QA testing of web applications using the browser toolset. You will navigate the application, interact with elements, capture evidence of issues, and produce a structured bug report.
+
+## Tool mapping and authorization
+
+Resolve actual browser tools from the native browser-use entry or an installed
+Playwright harness. The browser_* calls below are historical pseudocode, not
+registered tool names. Map operations to the exposed schema before executing;
+never invent @eN handles. Preserve the user's live session. Use only authorized
+test mutations; payments, external messages and destructive writes need their
+own explicit scope. Use a unique task-owned output directory.
+
+## Prerequisites
+
+- Browser toolset must be available (`browser_navigate`, `browser_snapshot`, `browser_click`, `browser_type`, `browser_vision`, `browser_console`, `browser_scroll`, `browser_back`, `browser_press`)
+- A target URL and testing scope from the user
+
+## Inputs
+
+The user provides:
+1. **Target URL** — the entry point for testing
+2. **Scope** — what areas/features to focus on (or "full site" for comprehensive testing)
+3. **Output directory** (optional) — where to save screenshots and the report (default: `./dogfood-output`)
+
+## Workflow
+
+Follow this 5-phase systematic workflow:
+
+### Phase 1: Plan
+
+1. Create the output directory structure:
+   ```
+   {output_dir}/
+   ├── screenshots/       # Evidence screenshots
+   └── report.md          # Final report (generated in Phase 5)
+   ```
+2. Identify the testing scope based on user input.
+3. Build a rough sitemap by planning which pages and features to test:
+   - Landing/home page
+   - Navigation links (header, footer, sidebar)
+   - Key user flows (sign up, login, search, checkout, etc.)
+   - Forms and interactive elements
+   - Edge cases (empty states, error pages, 404s)
+
+### Phase 2: Explore
+
+For each page or feature in your plan:
+
+1. **Navigate** to the page:
+   ```
+   browser_navigate(url="https://example.com/page")
+   ```
+
+2. **Take a snapshot** to understand the DOM structure:
+   ```
+   browser_snapshot()
+   ```
+
+3. **Check the console** for JavaScript errors:
+   ```
+   browser_console(clear=true)
+   ```
+   Do this after every navigation and after every significant interaction. Silent JS errors are high-value findings.
+
+4. **Take an annotated screenshot** to visually assess the page and identify interactive elements:
+   ```
+   browser_vision(question="Describe the page layout, identify any visual issues, broken elements, or accessibility concerns", annotate=true)
+   ```
+   Use only handles returned by the actual browser tool. Re-snapshot after navigation or a stale-handle failure.
+
+5. **Test interactive elements** systematically:
+   - Click buttons and links: `browser_click(ref="@eN")`
+   - Fill forms: `browser_type(ref="@eN", text="test input")`
+   - Test keyboard navigation: `browser_press(key="Tab")`, `browser_press(key="Enter")`
+   - Scroll through content: `browser_scroll(direction="down")`
+   - Test form validation with invalid inputs
+   - Test empty submissions
+
+6. **After each interaction**, check for:
+   - Console errors: `browser_console()`
+   - Visual changes: `browser_vision(question="What changed after the interaction?")`
+   - Expected vs actual behavior
+
+### Phase 3: Collect Evidence
+
+For every issue found:
+
+1. **Take a screenshot** showing the issue:
+   ```
+   browser_vision(question="Capture and describe the issue visible on this page", annotate=false)
+   ```
+   Save the `screenshot_path` from the response — you will reference it in the report.
+
+2. **Record the details**:
+   - URL where the issue occurs
+   - Steps to reproduce
+   - Expected behavior
+   - Actual behavior
+   - Console errors (if any)
+   - Screenshot path
+
+3. **Classify the issue** using the issue taxonomy (see `../issue-taxonomy.md`):
+   - Severity: Critical / High / Medium / Low
+   - Category: Functional / Visual / Accessibility / Console / UX / Content
+
+### Phase 4: Categorize
+
+1. Review all collected issues.
+2. De-duplicate — merge issues that are the same bug manifesting in different places.
+3. Assign final severity and category to each issue.
+4. Sort by severity (Critical first, then High, Medium, Low).
+5. Count issues by severity and category for the executive summary.
+
+### Phase 5: Report
+
+Generate the final report using the template at `../../templates/dogfood-report-template.md`.
+
+The report must include:
+1. **Executive summary** with total issue count, breakdown by severity, and testing scope
+2. **Per-issue sections** with:
+   - Issue number and title
+   - Severity and category badges
+   - URL where observed
+   - Description of the issue
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Screenshot references (use an attached task asset with its explicit path for inline images)
+   - Console errors if relevant
+3. **Summary table** of all issues
+4. **Testing notes** — what was tested, what was not, any blockers
+
+Save the report to `{output_dir}/report.md`.
+
+## Tools Reference
+
+| Tool | Purpose |
+|------|---------|
+| `browser_navigate` | Go to a URL |
+| `browser_snapshot` | Get DOM text snapshot (accessibility tree) |
+| `browser_click` | Click an element by ref (`@eN`) or text |
+| `browser_type` | Type into an input field |
+| `browser_scroll` | Scroll up/down on the page |
+| `browser_back` | Go back in browser history |
+| `browser_press` | Press a keyboard key |
+| `browser_vision` | Screenshot + AI analysis; use `annotate=true` for element labels |
+| `browser_console` | Get JS console output and errors |
+
+## Tips
+
+- **Always check `browser_console()` after navigating and after significant interactions.** Silent JS errors are among the most valuable findings.
+- **Use `annotate=true` with `browser_vision`** when you need to reason about interactive element positions or when the snapshot refs are unclear.
+- **Test with both valid and invalid inputs** — form validation bugs are common.
+- **Scroll through long pages** — content below the fold may have rendering issues.
+- **Test navigation flows** — click through multi-step processes end-to-end.
+- **Check responsive behavior** at named desktop/mobile viewports, inspect screenshots and horizontal overflow, and test keyboard focus. Record untested breakpoints.
+- **Don't forget edge cases**: empty states, very long text, special characters, rapid clicking.
+- When reporting screenshots to the user, include an attached task asset with its explicit path so they can see the evidence inline.

package/built-in-skills/webapp-qa/references/issue-taxonomy.md

@@ -0,0 +1,109 @@
+# Issue Taxonomy
+
+Use this taxonomy to classify issues found during dogfood QA testing.
+
+## Severity Levels
+
+### Critical
+The issue makes a core feature completely unusable or causes data loss.
+
+**Examples:**
+- Application crashes or shows a blank white page
+- Form submission silently loses user data
+- Authentication is completely broken (can't log in at all)
+- Payment flow fails and charges the user without completing the order
+- Security vulnerability (e.g., XSS, exposed credentials in console)
+
+### High
+The issue significantly impairs functionality but a workaround may exist.
+
+**Examples:**
+- A key button does nothing when clicked (but refreshing fixes it)
+- Search returns no results for valid queries
+- Form validation rejects valid input
+- Page loads but critical content is missing or garbled
+- Navigation link leads to a 404 or wrong page
+- Uncaught JavaScript exceptions in the console on core pages
+
+### Medium
+The issue is noticeable and affects user experience but doesn't block core functionality.
+
+**Examples:**
+- Layout is misaligned or overlapping on certain screen sections
+- Images fail to load (broken image icons)
+- Slow performance (visible loading delays > 3 seconds)
+- Form field lacks proper validation feedback (no error message on bad input)
+- Console warnings that suggest deprecated or misconfigured features
+- Inconsistent styling between similar pages
+
+### Low
+Minor polish issues that don't affect functionality.
+
+**Examples:**
+- Typos or grammatical errors in text content
+- Minor spacing or alignment inconsistencies
+- Placeholder text left in production ("Lorem ipsum")
+- Favicon missing
+- Console info/debug messages that shouldn't be in production
+- Subtle color contrast issues that don't fail WCAG requirements
+
+## Categories
+
+### Functional
+Issues where features don't work as expected.
+
+- Buttons/links that don't respond
+- Forms that don't submit or submit incorrectly
+- Broken user flows (can't complete a multi-step process)
+- Incorrect data displayed
+- Features that work partially
+
+### Visual
+Issues with the visual presentation of the page.
+
+- Layout problems (overlapping elements, broken grids)
+- Broken images or missing media
+- Styling inconsistencies
+- Responsive design failures
+- Z-index issues (elements hidden behind others)
+- Text overflow or truncation
+
+### Accessibility
+Issues that prevent or hinder access for users with disabilities.
+
+- Missing alt text on meaningful images
+- Poor color contrast (fails WCAG AA)
+- Elements not reachable via keyboard navigation
+- Missing form labels or ARIA attributes
+- Focus indicators missing or unclear
+- Screen reader incompatible content
+
+### Console
+Issues detected through JavaScript console output.
+
+- Uncaught exceptions and unhandled promise rejections
+- Failed network requests (4xx, 5xx errors in console)
+- Deprecation warnings
+- CORS errors
+- Mixed content warnings (HTTP resources on HTTPS page)
+- Excessive console.log output left from development
+
+### UX (User Experience)
+Issues where functionality works but the experience is poor.
+
+- Confusing navigation or information architecture
+- Missing loading indicators (user doesn't know something is happening)
+- No feedback after user actions (e.g., button click with no visible result)
+- Inconsistent interaction patterns
+- Missing confirmation dialogs for destructive actions
+- Poor error messages that don't help the user recover
+
+### Content
+Issues with the text, media, or information on the page.
+
+- Typos and grammatical errors
+- Placeholder/dummy content in production
+- Outdated information
+- Missing content (empty sections)
+- Broken or dead links to external resources
+- Incorrect or misleading labels