vscode: establish CHANGELOG/README image-asset convention + audit past 4 weeks of merged PRs for usable visuals

[amrmelsayed]

Context

The vscode extension's packages/vscode/CHANGELOG.md and README.md ship to two public surfaces: the VS Code Marketplace and the Open VSX Registry. Both render markdown including images via standard ![alt](url) syntax, but only absolute URLs (e.g. raw.githubusercontent.com) render reliably across both surfaces. Currently the CHANGELOG is entirely text — no images — which makes feature releases harder to evaluate at a glance on the Marketplace listing.

Separately, since the documentation flow stabilized ~4 weeks ago, several merged PRs have included screenshots in their PR descriptions (typically dragged in as github.com/user-attachments/assets/<uuid> URLs). Those visuals exist but aren't surfaced anywhere users will see them — they're stuck in the PR body, invisible to anyone browsing the Marketplace.

This issue tackles both:

1. Establish the asset-hosting convention so future CHANGELOG/README entries have a clear, low-friction path to add visuals
2. Audit the past 4 weeks of merged PRs to inventory existing images that could be reused — feeds the convention validation by exercising it against real assets

Why PIR

• Multi-phase work with a real human-input pause: the audit produces a candidate-image catalog that the architect needs to review before deciding which images go where. PIR's dev-approval gate is exactly the surface for that pause
• Design decisions at plan-approval: folder structure naming, URL pattern (raw.githubusercontent.com vs commit-pinned SHAs), per-version subfolder convention, size/format guidelines
• Visual deliverable that needs running-app-equivalent verification: after integration, the architect should render the updated CHANGELOG/README locally (via marked or VS Code's markdown preview) to confirm images load before merge

Scope — three phases

Phase 1: Establish the convention

Author a new doc file at packages/vscode/docs/changelog-and-readme-assets.md (or similar location) documenting:

1. Folder structure for hosted assets:
   • Recommended starting point: packages/vscode/docs/changelog-assets/<version>/<name>.png for per-version per-feature images
   • README assets in packages/vscode/docs/readme-assets/<name>.png (no version subfolder since README is "current state")
   • Plan-approval should decide the exact folder names; the structure above is the proposal
2. URL pattern: absolute URLs pointing at raw.githubusercontent.com/cluesmith/codev/main/<path>
   • Branch-pinned (/main/) by default
   • Commit-SHA-pinned (/<sha>/) when an asset MUST stay stable against future force-pushes — rare
3. Image format and size:
   • PNG / JPG for screenshots; animated GIF for short interaction demos (5-15 sec, < 2MB)
   • Hard limit: 500KB per static image, 2MB per GIF — beyond that, hurts Marketplace page load
   • Tools recommendation: pngquant for PNG compression, gifski/gifsicle for GIF optimization
4. Alt text discipline: every image gets descriptive alt text (Marketplace screen readers consume it)
5. Commit convention: image assets land in the same PR that introduces the CHANGELOG entry referencing them (no orphaned assets, no stale references)
6. Markdown HTML hint: GitHub's <picture><source media="(prefers-color-scheme: dark)" srcset="..."></picture> dark-mode pattern — note whether it renders on both Marketplaces or only one (Marketplace's renderer may strip HTML beyond a whitelist; needs verification)

Phase 2: Audit past 4 weeks of merged PRs

# Find merged PRs from past 4 weeks
gh pr list --state merged --search "merged:>=$(date -v-4w +%Y-%m-%d)" --limit 100 \
  --json number,title,body,mergedAt

For each PR returned:

• Scan the body for image URLs matching these patterns:
  • https://github.com/user-attachments/assets/[a-f0-9-]+
  • https://raw.githubusercontent.com/[^)]+\.(png|jpg|jpeg|gif|webp)
  • <img[^>]+src="[^"]+" (HTML embed form)
• For each image found:
  • Download the asset to packages/vscode/docs/changelog-assets/audit-2026-05/<pr-number>-<seq>.png (using a temporary audit folder; final placement comes after the architect-review pause)
  • Record: source PR number, original URL, fetched local filename, brief one-line description of what the image illustrates (inferred from surrounding PR-body text)
• Produce an inventory file at packages/vscode/docs/changelog-assets/audit-2026-05/INVENTORY.md with a table:

| PR | Image | Source URL | Local file | What it shows |
|----|-------|------------|------------|---------------|
| #886 | 1 | https://github.com/user-attachments/assets/... | 886-1.png | Backlog tree grouped by area, showing 4 groups |
| #886 | 2 | https://github.com/user-attachments/assets/... | 886-2.png | Backlog before grouping (flat list) for comparison |
| #890 | 1 | ... | 890-1.png | Builders tree grouped by area, mirroring #886 |

This phase commits the audit folder + inventory to the PR's worktree but does NOT yet integrate any images into the actual CHANGELOG/README. That integration is Phase 3, gated on the architect's review.

Phase 3 (after dev-approval gate): Integrate per architect guidance

When the architect reviews the running worktree at the dev-approval gate, they will look at the inventory and provide guidance like:

"Use #886/1 in the CHANGELOG entry for the area-grouping (currently lines 9-10 of [Unreleased] → What's new). Skip #890/1 as redundant. Move #886/2 into README's 'Backlog' section as a before/after pair."

The builder applies this guidance:

• Promote the chosen images from the audit folder to the canonical folder (changelog-assets/<version>/ or readme-assets/) with descriptive names
• Insert the ![alt](url) references into the appropriate CHANGELOG and/or README locations
• Delete the audit folder (changelog-assets/audit-2026-05/) since it was scratch — anything not promoted is intentionally discarded
• Verify renderings via local markdown preview before opening the PR

Acceptance criteria

Phase 1 (convention doc)

• packages/vscode/docs/changelog-and-readme-assets.md exists; covers folder structure, URL pattern, image format/size guidelines, alt-text discipline, commit convention, dark-mode HTML hint with rendering caveats
• Convention referenced from packages/vscode/CONTRIBUTING.md (if exists) or packages/vscode/README.md so future contributors find it

Phase 2 (audit)

• All merged PRs from merged:>=<4-weeks-ago-date> audited
• All image URLs found in PR bodies enumerated
• All images downloaded to a temporary audit-2026-05/ folder (or equivalent)
• INVENTORY.md produced with the table format above
• Audit folder + inventory committed to the builder's PR worktree

Phase 3 (integration — runs AFTER architect provides guidance at dev-approval)

• Promoted images live at canonical paths (changelog-assets/<version>/ or readme-assets/)
• CHANGELOG entries reference promoted images via raw.githubusercontent.com/cluesmith/codev/main/<path> URLs
• README updated per architect guidance
• Audit folder deleted (no leftover scratch assets)
• Local markdown render (e.g. vscode --command markdown.showPreview on the CHANGELOG) confirms all images load without 404s

General

• Image total size budget: < 2 MB across all newly-added assets in this PR (to keep the extension package small)
• No regression to existing CHANGELOG text content
• All committed images compressed (PNG via pngquant, GIF via gifsicle)

Out of scope

• Backfilling CHANGELOG entries for releases earlier than the past 4 weeks — too much work; if a prior entry needs an image, file a separate issue per entry
• Verifying that <picture> dark-mode HTML actually renders on both Marketplaces beyond documenting the caveat in the convention doc — empirical verification on the live Marketplaces would require a release, which is its own cycle
• Adding images for unreleased features that haven't shipped yet — only document what's actually merged
• Converting existing text-only entries to image-augmented entries beyond the architect-selected ones in Phase 3 — wholesale rework belongs to a separate effort
• Establishing video conventions — videos don't render in Marketplace markdown (HTML <video> is stripped); GIFs are the only motion format covered

Plan-phase design questions

These should be locked in at plan-approval:

1. Folder layout: docs/changelog-assets/<version>/ vs docs/changelog/<version>/assets/ vs media/changelog/<version>/ — pick one
2. Per-version subfolder for changelog: yes (my proposal — clean pruning when old versions drop off the page) vs no (flat folder, simpler navigation)
3. Branch-pinned vs SHA-pinned URLs: should the convention be raw.githubusercontent.com/.../main/... (auto-updates as repo changes) or commit-SHA (immutable)? Trade-off: branch-pinned breaks if main is force-pushed (rare in this repo); SHA-pinned requires updating URLs whenever an asset changes
4. Image compression mandatory or optional: hard CI check (lint rejects uncompressed PNGs above a threshold) vs documented-but-not-enforced
5. Audit folder naming: audit-YYYY-MM/ (date-stamped, my proposal) vs audit/ (single perpetual folder, simpler but no temporal context if multiple audits happen)

Related

• packages/vscode/CHANGELOG.md — the file this convention serves
• packages/vscode/README.md — secondary consumer of the same convention
• Recent CHANGELOG entries in [Unreleased] (under What's new for vscode: group backlog by area (area/* label namespace, predictable across views) #811, vscode: group builders in the tree by area (area/* label namespace, identical to backlog) #818, vscode: capitalize area group header labels in backlog and builders trees #885+vscode: UPPERCASE area group header labels in backlog and builders trees (supersedes #885's Capitalized form) #895, and Bug fixes for vscode: builder changed-file rows render grey instead of SCM colors #799, vscode: builder cleanup no longer closes the terminal tab — regression of 3.0.2 behavior #883, Duplicate / debug-looking command titles in VS Code Feature Contributions tab #838, Review comment commands missing 'Codev:' prefix in Feature Contributions tab #839, codev.telemetry setting description reads as informational, not as a control #840) — candidates for image augmentation per architect's Phase 3 guidance

Discovered while

User design discussion on 2026-05-28 about whether images and videos can be embedded in the extension's CHANGELOG.md and which hosting patterns are safe across Marketplace + Open VSX. Confirmed raw.githubusercontent.com is the reliable universal path; PR-attachment URLs work today but lack the discoverability and stability commitment of committed-to-repo assets.

---

Phase 2 audit results (executed 2026-05-28)

The audit has been executed. 6 of 59 merged PRs in the window 2026-04-30 → 2026-05-28 contained images in their PR body — 17 images total, all hosted at github.com/user-attachments/assets/<uuid>, all PNG, none animated, none using dark-mode <picture> pairs.

Full inventory with descriptions, local filenames, and architect-decision notes is at:

• packages/vscode/docs/changelog-assets/audit-2026-05/INVENTORY.md (committed in the Phase 2 PR alongside the downloaded assets)

Discovered assets by PR

PR	Title	Image source URLs
#731	feat: runnable worktrees + VSCode review tooling (#689 + #690)	1 (right-click context menu), 2 (Run Dev Server terminal)
#740	fix(vscode): lower engines.vscode floor for fork compatibility	1 (Cursor), 2 (AWS Kiro), 3 (Antigravity), 4 (Windsurf)
#771	feat(vscode): builder diffs, terminal image paste, backlog & Builders-tree polish	1 (accordion-collapse), 2 (full-extension preview)
#779	feat(vscode): idle-waiting builders, sidebar polish, and PIR default-branch fix	1 (composite: count badge + idle-waiting + inline backlog)
#785	feat(vscode): dev-workflow batch — Open Dev URL rows, per-engineer config	1 (local-override indicator), 2 (config.local.json editor), 3 (Open Dev URL rows), 4 (tree/list toggle)
#833	[#829] afx workspace recover: revive builders after reboot	1 (before recovery), 2 (dry-run output), 3 (builders revived), 4 (Claude session resumption)

Headline observations for Phase 3 architect review

1. Strong README-hero candidates: #771-2 (full-extension preview, 3020x1728) — would need downsizing; #731-1 (right-click context menu — small, focused).
2. CHANGELOG-entry-per-feature candidates: the four #785 images each map 1:1 to a feature bullet in [Unreleased]; clean fit.
3. Compatibility matrix candidate: the four #740 fork screenshots — best as a single 2x2 collage in README rather than four separate CHANGELOG entries.
4. Out-of-package: #833's four images are for the afx workspace recover CLI feature, not the VSCode extension. The architect may skip the entire #833 batch when scoping to the vscode-package CHANGELOG/README.
5. Alt-text deficit: 14 of 17 images use the placeholder alt text "image"; only #740's four are descriptively alt'd ("cursor" / "aws-kiro" / "antigravity" / "windsurf"). Promoted images will all need re-authored alt text per the convention's accessibility criterion.
6. No animated content: zero GIFs in the corpus. The convention's GIF guidelines remain documented-but-unexercised until a future PR introduces one.
7. No raw.githubusercontent.com URLs in the corpus: 100% of in-PR images use the user-attachments/assets/<uuid> form — confirms the convention this issue establishes is genuinely new ground for the repo.
8. Raw-bytes budget: 10.9 MB across all 17 images uncompressed. The convention's <500KB-per-image and <2MB-total-per-PR budgets will require pngquant on most images before promotion. Notably #771-2 (2.3 MB) and the four #740 shots (~1.1 MB each) exceed the per-image limit and must be downsized/compressed.

The audit folder + INVENTORY.md is committed in the Phase 2 PR for architect review at the dev-approval gate.