[medium] Release 0.5.0: evidence, onboarding, and frontend contracts

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Portable frontend workflow skills for planning, implementation, review, and visual QA.",
   "author": {
     "name": "Yevgeniy Tyan"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Frontend workflow skills for React and Next.js planning, implementation, review, and visual QA.",
   "skills": "./skills/"
 }

.github/ISSUE_TEMPLATE/agent-behavior-bug.yml

@@ -20,7 +20,7 @@ body:
     attributes:
       label: WebDev Agent Kit version
       description: Provide the release tag, commit, or archive name.
-      placeholder: v0.4.0
+      placeholder: v0.5.0
     validations:
       required: true
   - type: dropdown
@@ -102,3 +102,28 @@ body:
       description: Link a public repository or provide enough sanitized context to reproduce.
     validations:
       required: false
+  - type: dropdown
+    id: evidence-kind
+    attributes:
+      label: Evidence kind
+      options:
+        - Observed agent run
+        - Observed installation
+        - Configuration snapshot
+        - Synthetic replay
+    validations:
+      required: true
+  - type: input
+    id: client-model
+    attributes:
+      label: Client version and model
+      description: Include client surface, exact version, model ID, OS, and shell; use unknown when unavailable.
+    validations:
+      required: true
+  - type: textarea
+    id: repetition
+    attributes:
+      label: Repetitions and retained evidence
+      description: Include fresh-session runs, failures and successes, trace locations, and any near-miss prompt. Never count a fixture as a live pass.
+    validations:
+      required: false

.github/ISSUE_TEMPLATE/compatibility-report.yml

@@ -7,8 +7,6 @@ body:
     attributes:
       label: Preliminary checks
       options:
-        - label: I verified the archive against SHA256SUMS.
-          required: true
         - label: I searched existing issues for this client and version.
           required: true
   - type: dropdown
@@ -27,7 +25,7 @@ body:
     id: version
     attributes:
       label: Kit version and archive
-      placeholder: v0.4.0, webdev-agent-kit-codex.tar.gz
+      placeholder: v0.5.0, webdev-agent-kit-codex.tar.gz
     validations:
       required: true
   - type: input
@@ -66,3 +64,46 @@ body:
       description: List exact commands and distinguish passed, failed, blocked, and skipped checks.
     validations:
       required: true
+  - type: dropdown
+    id: evidence-kind
+    attributes:
+      label: Evidence kind
+      options:
+        - Observed agent run
+        - Observed installation
+        - Configuration snapshot
+        - Synthetic replay
+    validations:
+      required: true
+  - type: input
+    id: client-model
+    attributes:
+      label: Client version and model
+      description: Include client surface, exact version, model ID, OS, and shell; use unknown when unavailable.
+    validations:
+      required: true
+  - type: textarea
+    id: repetition
+    attributes:
+      label: Repetitions and retained evidence
+      description: Include fresh-session runs, failures and successes, trace locations, and any near-miss prompt. Never count a fixture as a live pass.
+    validations:
+      required: false
+  - type: dropdown
+    id: checksum
+    attributes:
+      label: Checksum result
+      options:
+        - Matched the same release SHA256SUMS
+        - Mismatch
+        - Could not verify
+        - Not an archive installation
+    validations:
+      required: true
+  - type: textarea
+    id: installation-stage
+    attributes:
+      label: Installation stage and upgrade state
+      description: Distinguish extracted, discovered, adapted, and exercised. For upgrades include old/new versions, active target/alias, preserved files, and rollback result.
+    validations:
+      required: true

AGENTS.md

@@ -11,6 +11,7 @@ tags:
     - 'docs/entrypoint'
 parent: []
 related:
+    - '[[skills/frontend-prototype-explorer/SKILL|Frontend Prototype Explorer]]'
     - '[[common/runtime-policy-index|Runtime Policy Index]]'
     - '[[common/core/runtime-core-policy|Portable Runtime Core Policy]]'
     - '[[common/policy-precedence|Policy Precedence]]'
@@ -63,10 +64,11 @@ Select skills from their `name` and `description`; the user need not name one. F
 ## Compact Skill Index
 
 - Plan: `goal-planner` defines outcomes; `execution-plan-manager` slices work; `loop-workflow-planner` governs bounded iteration.
-- Design: `design-screenshot-spec` converts supplied visual evidence; `frontend-design-intelligence` grounds product patterns; `frontend-design-director` sets visual direction.
+- Design: `design-screenshot-spec` converts supplied visual evidence; `frontend-design-intelligence` grounds product patterns; `frontend-design-director` sets visual direction; `frontend-prototype-explorer` tests unresolved UI or state decisions.
 - Build: `frontend-architecture-planner` defines ownership; `greenfield-project-builder` plans a first vertical slice; `frontend-layout-implementer` implements an approved spec in its target stack.
 - Quality: `frontend-bugfix-debugger` fixes evidence-first defects; `frontend-refactor-surgeon` preserves behavior; `frontend-linter-manager` runs or repairs scoped lint; `frontend-visual-qa` checks rendered evidence; `frontend-quality-reviewer` performs independent review.
 - Context and tooling: `project-onboarding-adapter` initializes pointers and local facts; `project-context-adapter` refreshes them; `mcp-toolchain-manager` maps tool capabilities; `pattern-library-manager` maintains reusable patterns; `agent-rules-skill-author` maintains this bundle.
+- Updates: `webdev-kit-updater` reconciles installed versions with upstream diffs, preserving local changes.
 
 ## Change Boundaries
 

CHANGELOG.md

@@ -11,6 +11,7 @@ tags:
     - 'release-management'
 parent: []
 related:
+    - '[[docs/release/0.5.0-checklist|0.5.0 Release Checklist]]'
     - '[[README|WebDev Agent Kit README]]'
     - '[[AGENTS|Canonical Agent Policy]]'
     - '[[docs/install/README|Installation Guides]]'
@@ -29,6 +30,45 @@ Use this changelog for source-bundle and distribution-target changes that affect
 
 ### Added
 
+- Instruction-only `webdev-kit-updater` and public bootstrap guidance for older
+  installations: pinned upstream diffs, three-way client-package reconciliation,
+  protected local state, conflict gates, installation records, and rollback.
+- Component-level design evidence with selected-layer/property attribution and
+  a product decision register covering navigation, forms, states, persistence,
+  responsive behavior, and motion. Unresolved choices are clarified with the user
+  before dependent implementation.
+- First-run checks, upgrade/rollback guidance, canonical alias matrix, and reproducible screenshot, bugfix, review, and verification examples.
+- Project fact provenance and verification templates; sanitized findings from two real-project configuration snapshots, with no live success claims.
+- Host instruction migration with reachable local rules, verbatim backup, coverage map, and repeat-run preservation (issue #66).
+- Design-system reuse and component substitution guidance, plus purpose-specific naming that preserves external API contracts (issue #66 comments).
+
+- Experimental `frontend-prototype-explorer` for bounded, disposable UI and state experiments, with observations, user judgments, and decision handoff.
+- Optional product-domain glossary template integrated into onboarding, refresh, planning, implementation, and review.
+- Nineteen reproducible live behavior scenarios, a dependency-free frontend fixture, and a client-neutral opt-in runner with retained evidence. Static and synthetic checks do not claim real client success.
+
+### Changed
+
+- Design intake accepts Figma links and automatically prefers available MCP reads,
+  then browser/computer use when MCP is missing, failing, or incomplete. Supplied
+  screenshots remain a standalone path with explicit confidence and coverage.
+- Design direction and intelligence now keep recommendations separate from user
+  decisions; implementation consumes confirmed scope. Optional read-only design
+  providers replace the former screenshot-only prohibition without auto-setup or
+  canvas writes. Existing skill names and the 0.5.0 release version are preserved.
+- Native plugin onboarding and context refresh resolve host overlays outside the plugin and avoid dangling shared-policy pointers.
+- Contributor reports capture client/model/OS, evidence kind, repeat outcomes, and installation stages; checksum failures are reportable.
+- Release validation rejects unsafe Windows paths, duplicate/case-colliding members, unexpected roots, and unsafe archive types before extraction; preservation fixtures include local plans and unrelated client rules.
+- Live preparation checks cover all canonical targets, isolated screenshot references, fixture path safety, and run provenance. Windows logs remain synthetic until exercised on real clients.
+
+- Independent review now distinguishes fresh context from same-session self-review and can seek reproducible counterexamples without forcing findings.
+- Feature plans prefer demonstrable frontend scenarios and explicit slice blockers; analysis checks dependencies and high-impact assumptions without extending the question limit.
+- Verification now permits scoped browser-dependent functional outcomes, including save/reload, URL navigation, downloads, and recovery, without requiring visual changes or new tests.
+- Source and portable-target metadata advance to 0.5.0 with 21 skills. Existing installation contracts, test-authoring permissions, and lightweight routing remain unchanged.
+
+## 0.4.0
+
+### Added
+
 - Added an open-source community foundation with governance, support, roadmap,
   conduct, ownership, issue forms, and pull request guidance.
 - Added structured issue intake for agent behavior, client compatibility,

ROADMAP.md

@@ -11,6 +11,10 @@ tags:
     - 'planning/public'
 parent: []
 related:
+    - '[[docs/install/first-run]]'
+    - '[[docs/install/upgrade]]'
+    - '[[docs/architecture/field-evidence]]'
+    - '[[docs/architecture/reproducible-workflows]]'
     - '[[README|WebDev Agent Kit]]'
     - '[[GOVERNANCE|Project Governance]]'
     - '[[CHANGELOG|WebDev Agent Kit Changelog]]'
@@ -26,23 +30,31 @@ is recorded in `CHANGELOG.md`.
 
 ## Current
 
-- Improve first-time installation and adaptation clarity.
-- Publish reproducible examples of scoped fixes, screenshot-driven frontend
-  work, review, and verification behavior.
-- Stabilize the `0.4.x` runtime, planning contracts, and release artifacts.
-- Collect real agent-behavior and client-compatibility reports.
-- Keep Codex, Claude Code, Cursor, and VS Code alias documentation aligned with
-  their validated target contracts.
+- Prepare `0.5.0` while retaining the `0.4.x` target contracts and local plans.
+- Validate first-run and upgrade guidance against real client installations;
+  [first-run checks](docs/install/first-run.md) and
+  [upgrade/rollback](docs/install/upgrade.md) are implemented in the release candidate.
+- Exercise the public [reproducible workflows](docs/architecture/reproducible-workflows.md)
+  for scoped fixes, screenshots, review, migration, and verification boundaries.
+- Collect actual agent-behavior and client-compatibility runs through the expanded
+  issue forms. [Field evidence](docs/architecture/field-evidence.md) currently
+  contains two configuration snapshots, not cross-client behavior passes.
+- Keep Codex, Claude Code, Cursor, and VS Code aliases aligned with their
+  canonical contracts; installation and archive validation remain release gates.
 
 ## Next
 
 - Expand live behavior evidence without weakening deterministic static evals.
-- Improve upgrade, migration, and compatibility guidance between releases.
-- Add focused React and Next.js workflows only where repeated user evidence
-  demonstrates a distinct gap.
-- Improve contributor fixtures for triggers, near misses, Windows sandbox
-  behavior, and release archive installation.
-- Refine community patterns and anti-patterns from public, reproducible cases.
+  The runner records provenance; completed adapters still require human assessment.
+- Confirm upgrade and rollback across published versions with retained local
+  overlays, host instruction migration, and native client discovery evidence.
+- Add focused React and Next.js workflows only when repeated user runs show a
+  distinct gap. Two React/Vite configurations do not meet that threshold.
+- Exercise Windows shell/sandbox fixtures on actual Windows clients. Synthetic
+  log replays and Windows archive-path rejection are contributor checks, not
+  proof of real sandbox compatibility.
+- Refine community patterns and anti-patterns from public, reproducible cases,
+  preserving failures and near misses alongside successful runs.
 
 ## Exploring
 

adapters/claude-code.md

@@ -19,7 +19,7 @@ depends_on:
 
 # Claude Code Client Adapter
 
-Purpose: map portable behavior to Claude Code discovery and project instructions without redefining workflow policy.
+Purpose: map portable policy to Claude Code discovery and project instructions.
 
 ## Discovery
 
@@ -31,9 +31,14 @@ Purpose: map portable behavior to Claude Code discovery and project instructions
 
 Plugin installation does not authorize project-file edits. If the project separately uses `.agents/AGENTS.md`, propose the exact root `CLAUDE.md` import `@.agents/AGENTS.md`. Create or merge it only after explicit user approval; never overwrite existing instructions.
 
+Resolve reusable paths under the plugin root and `project/**` under host
+`.agents/project/`. Never write host facts into the shared plugin.
+
 ## Tool Boundary
 
-Detect tools from the current Claude Code registry and verified project capability facts. A native Claude Code tool can satisfy a capability without a named MCP server. Do not infer availability from packages, config, provider names, or another client's metadata. Use the portable fallback when a capability is absent and report the resulting verification limit.
+Detect tools from the current registry and verified project facts. Native tools
+can satisfy capabilities. Packages, config, provider names, and another client's
+metadata do not prove availability. Use declared fallbacks and report limits.
 
 ## Output Boundary
 

bundle-manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "webdev-agent-kit",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "license": "Apache-2.0",
   "description": "Internal source and distribution inventory for the WebDev Agent Kit skill bundle.",
   "portable_core": "common/core/runtime-core-policy.md",
@@ -23,6 +23,7 @@
     "frontend-design-intelligence",
     "frontend-layout-implementer",
     "frontend-linter-manager",
+    "frontend-prototype-explorer",
     "frontend-quality-reviewer",
     "frontend-refactor-surgeon",
     "frontend-visual-qa",
@@ -32,7 +33,8 @@
     "mcp-toolchain-manager",
     "pattern-library-manager",
     "project-context-adapter",
-    "project-onboarding-adapter"
+    "project-onboarding-adapter",
+    "webdev-kit-updater"
   ],
   "targets": {
     "claude-code": {

common/anti-patterns.md

@@ -52,8 +52,12 @@ Load only the template relevant to the current code risk:
 
 ## Workflow Anti-Patterns
 
-- Using Figma MCP, live Figma inspection, Figma canvas editing, Figma file creation, Figma whiteboard, design-system generation, or Code Connect workflows.
-- Treating a Figma URL, file key, node id, or Figma whiteboard reference as sufficient source material.
+- Editing Figma canvases, creating files or whiteboards, generating design
+  systems, or writing Code Connect mappings during read-only design intake.
+- Treating a Figma URL as inspected evidence without opening its actual design,
+  or asking for screenshots before trying available MCP/browser read paths.
+- Assigning property-panel values to an unconfirmed selection, or inventing
+  product decisions from static screenshots instead of asking the user.
 - Implementing code before producing or receiving a `Design Implementation Spec`.
 - Guessing hidden component states, assets, token names, breakpoints, or interactions when the source material does not provide them.
 - Inventing CSS variables, tokens, theme names, breakpoint names, spacing names, typography names, or color names.

common/client-adaptation-policy.md

@@ -12,6 +12,7 @@ tags:
 parent:
     - '[[skills/project-onboarding-adapter/SKILL|Project Onboarding Adapter]]'
 related:
+    - '[[common/host-instruction-migration-rules|Host Instruction Migration]]'
     - '[[common/tool-capability-model|Tool Capability Model]]'
     - '[[common/mcp-installation-policy|MCP Installation Policy]]'
     - '[[adapters/claude-code|Claude Code Client Adapter]]'
@@ -44,11 +45,17 @@ Use only the pointer template linked by the matching adapter. Compatibility alia
 
 If a host project already has `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/**`, or client config files:
 
-1. Inspect only the minimal pointer section needed for adaptation.
+1. Inspect the minimal pointer section for detection; read the whole file before proposing or performing a migration.
 2. Do not overwrite existing instructions.
 3. Propose a merge when existing instructions are non-empty or ambiguous.
 4. Require user approval before editing existing host instructions.
 
+Explicit instruction-migration requests already authorize the requested
+replacement. Apply `common/host-instruction-migration-rules.md`: preserve all
+rules in reachable local overlays, retain a verbatim backup and coverage map,
+validate them, then replace the root with the minimal pointer. Generic
+adaptation still proposes a merge before replacing nonempty instructions.
+
 ## Client Profile
 
 Record detected client facts in local-only `project/client-profile.md`: