docs(panel): v002.1 readiness panel developer guide

CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format follows Keep a Changelog. Entries here describe repository changes
+under review and do not claim a published extension, marketplace package, tag,
+release, or stable API/ABI.
+
+## [Unreleased]
+
+The 2026-05-07 v002.1 PR ramp is grouped below. Late-day additions after
+the initial changelog pass are appended after the first #124-#129 stack.
+
+### Status Surface
+
+- Added local read-only KV260 status readers, example JSON fixtures, CLI output,
+  documentation, and a VS Code prototype panel for launcher NPU status and lab
+  trace manifest data. [#124](https://github.com/pccxai/systemverilog-ide/pull/124)
+
+### UI Theme
+
+- Integrated copied pccx aperture logo assets, a prototype extension icon, the
+  pccx SystemVerilog Light color theme, and a copied-asset notice. [#125](https://github.com/pccxai/systemverilog-ide/pull/125)
+
+### Preflight Binding
+
+- Extended the read-only launcher status data with serial preflight snapshot
+  fields and surfaced tty, kernel, XRT, and timestamp values with missing-data
+  defaults. [#126](https://github.com/pccxai/systemverilog-ide/pull/126)
+
+### Polish
+
+- Rendered readiness details in a no-script VS Code webview with status pills,
+  evidence-path details, and maintainer empty states while retaining the
+  output-channel fallback. [#127](https://github.com/pccxai/systemverilog-ide/pull/127)
+
+### Palette
+
+- Added v002.1 command-palette navigation for the status panel, runbook, project
+  board, and trace help through the read-only panel or VS Code external URL
+  opening. [#128](https://github.com/pccxai/systemverilog-ide/pull/128)
+
+### Docs
+
+- Added the v002.1 readiness panel developer guide covering local enablement,
+  launcher-side data environment names, panel pill semantics, feedback routing,
+  and command-palette entries. [#129](https://github.com/pccxai/systemverilog-ide/pull/129)
+
+### Preflight Summary
+
+- Added a read-only board preflight summary card that parses bounded local
+  transcript fields, exposes a configurable transcript path, and keeps a
+  graceful empty state when no transcript is captured. [#130](https://github.com/pccxai/systemverilog-ide/pull/130)
+
+### Theme Variant
+
+- Added the pccx SystemVerilog Dark theme beside the light theme, including
+  manifest wiring, README listing, and JSON theme validation coverage. [#132](https://github.com/pccxai/systemverilog-ide/pull/132)
+
+### Settings
+
+- Added a checked settings schema for panel data sources, refresh interval, and
+  log level, mirrored the schema into the VS Code prototype contributions, and
+  normalized the settings at runtime. [#133](https://github.com/pccxai/systemverilog-ide/pull/133)
+
+### Keymap
+
+- Added default shortcuts for the read-only v002.1 PCCX commands and locked the
+  command-to-key mapping in the VS Code prototype manifest test. [#134](https://github.com/pccxai/systemverilog-ide/pull/134)
+
+### Developer Environment
+
+- Added a development Dockerfile for Python, Node, open HDL tools, OSS CAD
+  Suite, XRT utilities, Xilinx bootgen, OpenOCD, and openFPGALoader. [#135](https://github.com/pccxai/systemverilog-ide/pull/135)
+
+### Settings Docs
+
+- Added a dedicated VS Code prototype settings reference, linked it from the
+  prototype README, and covered schema-to-doc alignment in tests. [#136](https://github.com/pccxai/systemverilog-ide/pull/136)
+
+### Examples
+
+- Added a text-only first-use guide covering command palette, Problems and
+  Output panels, status-bar expectations, and the no-screenshot evidence
+  boundary. [#137](https://github.com/pccxai/systemverilog-ide/pull/137)
+
+### Quickstart
+
+- Added a five-step SV-IDE quickstart for install, panel, preflight, status, and
+  JSON export, with links from the root README and VS Code prototype README. [#138](https://github.com/pccxai/systemverilog-ide/pull/138)
+
+### Test Taxonomy
+
+- Added a T0-T7 test taxonomy for the Python CLI, checked examples, VS Code
+  prototype, boundary guards, and manual review evidence. [#139](https://github.com/pccxai/systemverilog-ide/pull/139)
+
+### Theme Docs
+
+- Added theme consistency rules for paired light and dark themes, including
+  structural parity, color keys, token buckets, and shared semantic roles. [#140](https://github.com/pccxai/systemverilog-ide/pull/140)
+
+### Guardrails
+
+- This changelog summarizes the #124-#130 and #132-#140 PR stack only; it does
+  not add or claim launcher execution, pccx-lab execution, serial writes, SSH,
+  board commands, provider calls, telemetry, uploads, write-back, packaging,
+  tags, or release flow.
+- This changelog makes no marketplace flow claim and no stable API/ABI claim.

docs/v002.1-readiness-panel-guide.md

@@ -0,0 +1,133 @@
+# v002.1 Readiness Panel Developer Guide
+
+This guide is for maintainers wiring or reviewing the local read-only KV260
+readiness panel in the VS Code prototype. The panel is a status surface over
+existing JSON inputs. It does not probe the board, open serial ports, execute
+launcher or lab commands, run inference, package the extension, publish builds,
+or write status back to any repository.
+
+## Scope
+
+The current panel stack is split across the v002.1 branches:
+
+- `pccxai/systemverilog-ide#124` adds the local `Kv260StatusPanel`, the
+  `pccxSystemVerilog.showKv260StatusPanel` command, and the
+  `sv-ide kv260-status` / `pccx-ide kv260-status` CLI text and JSON surface.
+- `pccxai/systemverilog-ide#126` extends the launcher status reader with the
+  serial preflight snapshot fields provided by the launcher side.
+- `pccxai/systemverilog-ide#127` renders the no-script VS Code webview:
+  aperture mark, metadata, color status pills, empty states, and collapsible
+  evidence-path details.
+- `pccxai/systemverilog-ide#128` adds the v002.1 command-palette entries for
+  the panel, runbook link, project board link, and trace inspect help.
+
+## Enablement
+
+Use the local VS Code prototype scaffold under `editors/vscode-prototype`.
+Load it in an Extension Development Host from this checkout, then open the
+Command Palette and run either panel command:
+
+- `PCCX SystemVerilog: Show KV260 Status Panel (Experimental)`
+- `PCCX: Show KV260 Status Panel`
+
+For non-UI review, run the local CLI status surface from the repository root:
+
+```bash
+PYTHONPATH=src python3 -m pccx_ide_cli kv260-status --format text
+PYTHONPATH=src python3 -m pccx_ide_cli kv260-status --format json
+```
+
+By default the CLI reads the tiny fixtures in
+`docs/examples/kv260-status/`. Maintainers can pass local JSON files with
+`--launcher-status` and `--trace-manifest` when reviewing a handoff. Keep
+those files local unless the values have already been scrubbed for review.
+
+## Live Data Inputs
+
+The IDE panel does not read serial credentials or environment values. Live
+board evidence enters the panel only after the owning launcher code writes a
+launcher status JSON object with a `serial_probe` snapshot.
+
+Launcher-side serial preflight, from `pccxai/pccx-llm-launcher#72`, reads these
+environment variable names:
+
+- `KVFPGA_TTY`: preferred KV260 serial tty path. If absent, the launcher may
+  attempt its own tty detection.
+- `KVFPGA_USER`: serial login username used by the launcher preflight.
+- `KVFPGA_PASSWORD`: serial login password used by the launcher preflight.
+- `KVFPGA_HOST`: intentionally ignored by the launcher serial backend for this
+  tty path.
+
+The IDE-visible fields are the resulting JSON fields, not the environment
+values: `launcher.serial_probe.status`, `tty_port`, `login_ok`,
+`kernel_uname`, `xrt_present`, and `last_preflight_at`. Missing, blocked, or
+not-run launcher input must stay visible as pending or failed panel state; the
+IDE must not compensate by probing hardware itself.
+
+The trace side comes from the pccx-lab trace manifest contract in
+`pccxai/pccx-lab#160`. The panel currently displays manifest metadata such as
+schema version, bitstream UUID, AXI base, ISA version, frame count, source
+kind, and runbook reference.
+
+## Pill Semantics
+
+Each checklist row maps to a fixed status pill:
+
+- `PASS`: the required value is present and true for that row.
+- `PENDING`: launcher serial preflight has not run or no launcher status input
+  is configured.
+- `FAIL`: launcher serial preflight ran but the row is missing, false, or
+  blocked.
+
+The current checklist rows are:
+
+- `serial tty port`: evidence path `launcher.serial_probe.tty_port`
+- `serial login`: evidence path `launcher.serial_probe.login_ok`
+- `XRT present`: evidence path `launcher.serial_probe.xrt_present`
+- `serial preflight timestamp`: evidence path
+  `launcher.serial_probe.last_preflight_at`
+
+Treat a `PENDING` or `FAIL` row as a launch-path gate. The panel reports the
+state; it does not decide that a hardware run is allowed.
+
+## Command Palette Entries
+
+PR #128 contributes these command IDs and titles:
+
+| Command ID | Title | Behavior |
+| --- | --- | --- |
+| `pccxSystemVerilog.showKv260StatusPanel` | `PCCX SystemVerilog: Show KV260 Status Panel (Experimental)` | Opens the read-only KV260 status panel. |
+| `pccxSystemVerilog.v0021.showKv260StatusPanel` | `PCCX: Show KV260 Status Panel` | Opens the same read-only panel through the v002.1 command namespace. |
+| `pccxSystemVerilog.v0021.openRunbook` | `PCCX: Open v002.1 Runbook` | Opens the v002.1 KV260 runbook URL through VS Code external navigation. |
+| `pccxSystemVerilog.v0021.openProjectBoard` | `PCCX: Open Project Board` | Opens the PCCX project board URL through VS Code external navigation. |
+| `pccxSystemVerilog.v0021.showTraceInspectHelp` | `PCCX: Show Trace Inspect Help` | Opens the pccx-lab trace pipeline doc URL through VS Code external navigation. |
+
+The three URL commands are navigation-only. They must not call GitHub APIs,
+inspect project data, execute lab commands, or infer trace status locally.
+
+## Feedback Routing
+
+File panel and command-palette feedback in
+`https://github.com/pccxai/systemverilog-ide/issues`. Include the command ID,
+which JSON input path was used, the pill state, and the evidence path shown by
+the panel. Do not include passwords, tokens, private tty paths, private home
+paths, or raw board logs unless they have been reviewed for disclosure.
+
+Route launcher serial preflight issues to
+`https://github.com/pccxai/pccx-llm-launcher/issues`, especially anything about
+tty discovery, login, XRT probing, or the `serial_probe` JSON shape.
+
+Route trace manifest and `trace inspect` issues to
+`https://github.com/pccxai/pccx-lab/issues`.
+
+## Review Guardrails
+
+- Keep the panel read-only and data-boundary-first.
+- Do not add serial, SSH, shell, board-command, launcher-command, or lab-command
+  execution to the panel path.
+- Do not add telemetry, upload, write-back, packaging, release, or tag flows.
+- Do not print environment values in docs, tests, logs, PR bodies, or issues.
+- Do not present `PASS` rows as proof of runtime inference, post-route signoff,
+  or hardware throughput.
+- Keep new v002.1 commands explicit and command-palette discoverable; avoid
+  background polling, file watchers, and implicit workspace scans.