# Render complete Better Harness reports in Cursor Canvas

## Traceability

- Spec ID: `cursor-canvas-report`
- Status: Implemented

## Intent

Give Cursor users the same durable, complete Better Harness report experience
that Qoder users receive, while using Cursor's public Canvas SDK and native IDE
actions. Cursor session scans should automatically retain any workspace-scoped
Context Usage snapshot that Cursor has already materialized, and the report
renderer should present that evidence as one section of the full report rather
than as a standalone Context Usage page.

The existing Qoder Canvas, Markdown, and HTML routes remain unchanged. JSON
analysis remains parser-safe and does not acquire an implicit file-write side
effect.

## Acceptance Scenarios

- AC-1: A Cursor session analysis for a workspace discovers existing native
  `context-usage-*.canvas.data.json` snapshots only below that workspace's
  Cursor project directory. It projects bounded token/category/item metadata,
  omits raw item text, and reports missing snapshots as unobserved rather than
  as zero usage.
- AC-2: `harness analyze --platform cursor --format json` includes the bounded
  Context Usage projection in its exact summary facts when observed, without
  changing Qoder, Markdown, or HTML behavior and without writing files unless
  an explicit output option is supplied.
- AC-3: `harness render --mode cursor-canvas` accepts the same complete reviewed
  `summary + findings` contract as Qoder Canvas and writes a deterministic
  `findings.json`, `canvas.json`, and `report.canvas.tsx` bundle.
- AC-4: The generated Cursor Canvas renders the complete Better Harness reader
  flow: introduction and Fluency dimensions, project usage, AI Agent Practice,
  Context Window, prioritized findings, suggestions, and evidence/methodology.
  Context Window remains visible as unavailable when no native snapshot exists.
- AC-5: The Canvas uses only the public `cursor/canvas` surface. Finding handoff
  dispatches `newComposerChat`, safe file-backed evidence dispatches `openFile`
  with an optional selection, and an observed source conversation dispatches
  `openAgent`. Action payloads are transport data and raw session ids are not
  printed as reader copy.
- AC-6: Render-time validation proves the final TSX parses as TSX, imports only
  the public `cursor/canvas` surface, contains the complete report
  sections, and binds the public Canvas actions. Validation does not depend on
  Qoder's runtime declarations.
- AC-7: A bounded real-workspace smoke completes the Cursor scan and then
  produces a validated `cursor-canvas` bundle from the resulting report data.
  The generated TSX can be transformed successfully with the repository's
  shipped TSX transform.

## Non-goals

- Reproduce Cursor's proprietary Context Usage implementation or copy its
  generated template.
- Decode Cursor `store.db`, synthesize missing system/tool definitions, or claim
  token attribution that Cursor did not materialize.
- Make Canvas generation a side effect of every JSON command.
- Refactor the existing Qoder Canvas template in the same change.
- Add comprehensive unit coverage before the first end-to-end render smoke;
  focused contract tests may follow once the runnable path is proven.

## Plan and Tasks

1. Extend the Cursor session provider with an optional, workspace-qualified
   native Context Usage source and a privacy-bounded projection.
2. Thread Context Usage through the task-loop source, summary-facts projection,
   complete report contract, and Canvas split/merge path.
3. Add the `cursor-canvas` renderer and a standalone Cursor SDK template that
   embeds the merged complete report while retaining the sibling JSON artifacts
   as the durable data contract.
4. Add Cursor-specific validation using the existing module-boundary scanner
   and TSX transform, then register the mode in report routing and CLI help.
5. Run a real Cursor scan followed by a complete report projection/render and
   inspect the generated artifacts and transformed module.

The Cursor renderer remains capability-owned under `scripts/harness-analysis/`
and the template remains under `templates/canvas/`; the `.cursor-plugin` shell
does not own report judgment or schema.

## Test and Review Evidence

- AC-1/AC-2: Run `node scripts/session-analysis.mjs insights --platform cursor
  --workspace <workspace> --format json` and `node scripts/better-harness.mjs
  harness analyze --platform cursor --workspace <workspace> --format json`.
  Inspect the bounded projection and confirm no raw item `text` is retained.
- AC-3/AC-4/AC-5: Render a complete Agent Work Loop report with `--mode
  cursor-canvas`; inspect all three artifacts and the generated action bindings.
- AC-6: Run the Cursor Canvas validator against the final run directory and
  transform `report.canvas.tsx` with `transformCanvasSource`.
- AC-7: Use a temporary run directory for the real scan/render smoke and retain
  the command output plus artifact inventory as review evidence.
- Risk: Cursor's native snapshot schema and public Canvas SDK may change. Fail
  closed on malformed snapshots, retain an explicit schema/status boundary,
  and avoid private command ids or internal protobuf imports.
- Risk: native snapshot items may contain raw prompt or tool text. Persist only
  labels, token/character counts, hierarchy, and safe file references; never
  copy the native `text` field into analysis or report artifacts.
- Risk: Cursor actions can expose local identity or files. Keep ids as hidden
  action transport, render safe paths only when already admitted by the report,
  and omit unavailable actions instead of inventing targets.

## Implementation Evidence

- AC-1/AC-2: Real Cursor scans covered both an observed native snapshot
  (`56,860 / 300,000`, seven categories, 119 bounded items) and the explicit
  unobserved Better Harness workspace state; projected items retained no raw
  `text` and did not print absolute labels.
- AC-3/AC-4/AC-5/AC-6: `harness render --mode cursor-canvas --validate` wrote
  exactly `findings.json`, `canvas.json`, and `report.canvas.tsx`; validation
  passed data, module-boundary, complete-section, action-binding, and TSX
  transform checks with `cursor/canvas` as the sole import.
- AC-7: Cursor 3.13.10 opened the generated managed Canvas and rendered the
  overview, strengths, Fluency chart, AI Agent Practice, Context Window,
  findings boundary, and evidence/methodology sections. The unavailable Context
  Window state remained explicit for the Better Harness workspace.
- Repository verification: `npm test` passed 1,051 tests, `npm run pack:verify`
  passed both npm and runtime ZIP inventories, the generated doc-link graph was
  current, and the local preview returned `ok` from `/health` plus a transformed
  `/canvas-module.js`.