feat(docs): comprehensive VS Code docs (finos#2532)

* feat(docs): comprehensive VS Code Extension reference manual

Closes finos#2531.

Adds the new docs/docs/working-with-calm/vscode-extension.md reference
manual modelled on calm-hub.md (PR finos#2523). 14 sections cover overview,
installation, activity bar / tree view / search, interactive preview,
themes (4-variant gallery), layout engines, real-time validation, hover,
timeline, multi-doc navigation, live docify, configuration reference,
and schema-developer mode. Cross-links one-way to the beginner tutorial,
the core-concept widgets/timelines pages, and the CLI docify section —
no existing docs are modified (the manual is complementary).

Extends the screenshot tool (PR finos#2530 / issue finos#2529) with per-shot
workbench-settings overrides and an optional workspaceFile, then
implements 8 new shots: tree-search, 4 theme variants, 2 layout variants,
and the preview's Template tab. Two TODO shots remain (hover, timeline)
with the docs sections describing the feature textually and linking back
to the issue.

Implementation notes:

- launch.ts gains `settingsOverrides` so each shot can pre-seed the
  user-data-dir with the specific workbench/extension settings it needs
  (themes, layout engine, etc.).
- shots.ts gains `workspaceFile` for fixtures whose entry point isn't
  architecture.json (timeline uses arch-v1.json).
- index.ts supports SHOOT_ONLY=<name1,name2> for development iteration
  without overwriting the manifest mid-flow.
- New fixtures: timeline/ (multi-version + calm-timeline.json) and
  docify-template/ (architecture + Handlebars template).
- 12 of 14 shots implemented, 2 declared TODO. Smoke test passes
  (63 assertions). Docusaurus build is clean (no broken anchors).

* refactor(vscode): apply pre-PR review feedback

- Clarify SHOOT_ONLY example in index.ts; previous example named a shot
  whose `implemented` flag is false, which would have produced zero
  outputs.
- Note in shots.ts that `waitForDiagramRendered` returns on timeout
  rather than throwing, so a regression in the preview can silently
  produce a degraded PNG. Manual PR-diff review remains the gate.
- Mark the 08-hover setup body as scaffolding retained for the TODO
  follow-up, so its dead-code state reads intentional.
- Drop the empty `<div className="vscode-extension-theme-gallery">`
  wrapper in the docs page; no CSS rule referenced it.
- Normalise "VSCode" → "VS Code" in the Getting Help link label for
  consistency with the page title.

* docs(vscode): batched feedback — timeline, mapping, sidebar label

- Rename sidebar label to "CALM Tools (VSCode)" via sidebar_label
  frontmatter (page title and URL unchanged).
- Remove the tutorial-pointer paragraph from the intro; the manual stands
  on its own and the cross-link remains in Getting Help.
- Drop the Hover Information section entirely.
- Implement the timeline shot. The trick is firing onDidSaveTextDocument
  after the editor focuses the file — the initial
  onDidChangeActiveTextEditor on cold launch can race the extension's
  onStartupFinished activation and miss timeline detection. Manifest now
  has 13 implemented + 1 skipped (08-hover).
- Expand the Timeline Navigation section with a working screenshot, a
  full calm-timeline.json example, how the extension renders timeline
  mode (sidebar replaces Nodes/Relationships/Flows with the moments
  list), and when to use it.
- Expand Multi-Document Navigation with a how-it-works overview, the
  exact rules around mapping syntax (relative paths resolve against the
  mapping file's directory, not the workspace root), a complete worked
  example with a full workspace layout, and a troubleshooting list. All
  facts verified against navigation-service.ts.

* chore(review): address Copilot review feedback

- Rewrite the Documentation Generation section to describe the preview's
  three tabs accurately: Docify is the renderer, Template is a source
  viewer, Model is the parsed model. The previous prose called the
  Template tab a "live Handlebars renderer" — verifying against
  template-tab.view.ts, the Template tab is just `<pre>` of escaped
  source.
- Re-shoot 10-docify clicking the Docify tab; capture now shows the
  rendered "Architecture Overview" + Client → Calls → Service diagram
  rather than raw template text.
- Tidy the Interactive Preview section's tab breakdown to match.
- Fix the Search & Filter section: the palette title is "Search Model
  Elements"; "Search CALM Architecture Elements" is the prompt inside
  the input box, not the command label.
- Normalise the sidebar label to "CALM Tools (VS Code)" with a space,
  matching the page title and the rest of the prose.

* fix(vscode): restore working light/dark theme shots; drop HC variants

The previous attempt to fix the High Contrast Light screenshot regressed
the working light shot by moving workbench.colorTheme out of the seeded
settings into a runtime Color Theme picker call. The picker doesn't
work reliably under --extensionDevelopmentPath on VSCode 1.121 because
the theme list is registered asynchronously and the picker's highlighted
row stays at "Searching for themes..." when Enter fires.

Restore the working setting-at-launch approach for the standard light
and dark themes (Default Light Modern / Default Dark Modern), which IS
honoured at launch. The two HC variants are not honoured by the same
path on this VSCode version regardless of label form (Default High
Contrast Light, Light High Contrast, etc.). Mark them implemented:false
with an explanatory block comment.

The docs page's theme gallery is now light + dark only, with a short
note that HC variants follow the same pattern and can be selected
manually. Removes the two broken HC PNGs.

Also adds the window.autoDetectColorScheme / autoDetectHighContrast
settings to WORKBENCH_SETTINGS — harmless in the current state but
defensive against future OS-driven theme overrides.

Author: rocketstack-matt

calm-plugins/vscode/screenshots/fixtures/docify-template/architecture.json

@@ -0,0 +1,32 @@
+{
+    "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
+    "unique-id": "docify-demo",
+    "name": "Docify Demo",
+    "description": "Small architecture used by the docify-template fixture to demonstrate live documentation generation.",
+    "nodes": [
+        {
+            "unique-id": "client",
+            "node-type": "webclient",
+            "name": "Client",
+            "description": "A web client."
+        },
+        {
+            "unique-id": "service",
+            "node-type": "service",
+            "name": "Service",
+            "description": "A backend service."
+        }
+    ],
+    "relationships": [
+        {
+            "unique-id": "client-to-service",
+            "description": "Calls",
+            "relationship-type": {
+                "connects": {
+                    "source": { "node": "client" },
+                    "destination": { "node": "service" }
+                }
+            }
+        }
+    ]
+}

calm-plugins/vscode/screenshots/fixtures/docify-template/architecture.md

@@ -0,0 +1,15 @@
+# {{name}}
+
+{{description}}
+
+## Components
+
+{{#each nodes}}
+- **{{name}}** ({{node-type}}) — {{description}}
+{{/each}}
+
+## Interactions
+
+{{#each relationships}}
+- {{description}}
+{{/each}}

calm-plugins/vscode/screenshots/fixtures/timeline/arch-v1.json

@@ -0,0 +1,30 @@
+{
+    "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
+    "nodes": [
+        {
+            "unique-id": "web-app",
+            "name": "Web Application",
+            "description": "Frontend web application",
+            "node-type": "webclient"
+        },
+        {
+            "unique-id": "api-service",
+            "name": "API Service",
+            "description": "Backend API service",
+            "node-type": "service"
+        }
+    ],
+    "relationships": [
+        {
+            "unique-id": "web-to-api",
+            "description": "Web app calls API",
+            "relationship-type": {
+                "connects": {
+                    "source": { "node": "web-app" },
+                    "destination": { "node": "api-service" }
+                }
+            }
+        }
+    ]
+}
+

calm-plugins/vscode/screenshots/fixtures/timeline/arch-v2.json

@@ -0,0 +1,46 @@
+{
+    "$schema": "https://calm.finos.org/release/1.2/meta/calm.json",
+    "nodes": [
+        {
+            "unique-id": "web-app",
+            "name": "Web Application",
+            "description": "Frontend web application",
+            "node-type": "webclient"
+        },
+        {
+            "unique-id": "api-service",
+            "name": "API Service",
+            "description": "Backend API service",
+            "node-type": "service"
+        },
+        {
+            "unique-id": "database",
+            "name": "Database",
+            "description": "Persistent data store",
+            "node-type": "database"
+        }
+    ],
+    "relationships": [
+        {
+            "unique-id": "web-to-api",
+            "description": "Web app calls API",
+            "relationship-type": {
+                "connects": {
+                    "source": { "node": "web-app" },
+                    "destination": { "node": "api-service" }
+                }
+            }
+        },
+        {
+            "unique-id": "api-to-db",
+            "description": "API stores data",
+            "relationship-type": {
+                "connects": {
+                    "source": { "node": "api-service" },
+                    "destination": { "node": "database" }
+                }
+            }
+        }
+    ]
+}
+

calm-plugins/vscode/screenshots/fixtures/timeline/calm-timeline.json

@@ -0,0 +1,31 @@
+{
+    "$schema": "https://calm.finos.org/release/1.2/meta/calm-timeline.json",
+    "current-moment": "initial",
+    "moments": [
+        {
+            "unique-id": "initial",
+            "node-type": "moment",
+            "name": "Initial Architecture",
+            "description": "The initial architecture design",
+            "valid-from": "2024-01-01",
+            "details": {
+                "detailed-architecture": "arch-v1.json"
+            }
+        },
+        {
+            "unique-id": "enhanced",
+            "node-type": "moment",
+            "name": "Enhanced Architecture",
+            "description": "Architecture with additional components",
+            "valid-from": "2024-06-01",
+            "details": {
+                "detailed-architecture": "arch-v2.json"
+            }
+        }
+    ],
+    "metadata": {
+        "title": "Test Timeline",
+        "description": "Timeline for testing VSCode plugin timeline navigation"
+    }
+}
+

calm-plugins/vscode/screenshots/src/index.ts

@@ -33,13 +33,26 @@ async function main() {
 
     const entries: ManifestEntry[] = []
 
+    // Optional filter via SHOOT_ONLY=03-tree-search,04-preview-hero to
+    // iterate one or a few shots without running the whole set. Useful while
+    // developing. Names not in `implementedShots` (i.e. `implemented: false`)
+    // are still ignored — the filter narrows the implemented set, it doesn't
+    // bypass the implementation flag.
+    const onlyEnv = process.env.SHOOT_ONLY?.trim()
+    const allowed = onlyEnv ? new Set(onlyEnv.split(',').map((s) => s.trim())) : null
+    const todoShots = shots.filter((s) => !s.implemented && (!allowed || allowed.has(s.name)))
+
     for (const shot of implementedShots) {
-        const fixturePath = path.join(FIXTURES_DIR, shot.fixture, 'architecture.json')
-        console.log(`\n[shoot] ${shot.name}  fixture=${shot.fixture}`)
+        if (allowed && !allowed.has(shot.name)) continue
+
+        const workspaceFile = shot.workspaceFile ?? 'architecture.json'
+        const fixturePath = path.join(FIXTURES_DIR, shot.fixture, workspaceFile)
+        console.log(`\n[shoot] ${shot.name}  fixture=${shot.fixture}/${workspaceFile}`)
 
         const { window, cleanup } = await launchVSCodeWithExtension({
             extensionPath: EXTENSION_DIR,
             workspacePath: fixturePath,
+            settingsOverrides: shot.settings,
         })
 
         try {
@@ -60,9 +73,18 @@ async function main() {
         }
     }
 
-    const skipped = shots
-        .filter((s) => !s.implemented)
-        .map((s) => ({ name: s.name, reason: 'TODO — see issue #2529' }))
+    const skipped = todoShots.map((s) => ({
+        name: s.name,
+        reason: 'TODO — see issue #2529',
+    }))
+
+    if (allowed) {
+        console.log(
+            `\n[shoot] SHOOT_ONLY active — manifest NOT updated. Run a full shoot to regenerate the manifest.`
+        )
+        console.log(`[shoot] ${entries.length} shot(s) written.`)
+        return
+    }
 
     const manifest: Manifest = {
         generatedAt: new Date().toISOString(),

calm-plugins/vscode/screenshots/src/launch.ts

@@ -24,6 +24,13 @@ const WORKBENCH_SETTINGS = {
     'workbench.tips.enabled': false,
     'workbench.welcomePage.walkthroughs.openOnInstall': false,
     'extensions.ignoreRecommendations': true,
+    // Auto-detect quietly overrides an explicit `workbench.colorTheme` when
+    // the OS reports a different colour scheme or contrast state. Disabling
+    // both so per-shot theme overrides are honoured — particularly the
+    // High Contrast variants, which were otherwise silently swapped back to
+    // their non-HC counterparts on a non-HC OS.
+    'window.autoDetectColorScheme': false,
+    'window.autoDetectHighContrast': false,
 }
 
 // Bumping this is intentional and requires regenerating every PNG in the same PR.
@@ -32,7 +39,13 @@ export const PINNED_VSCODE_VERSION = '1.121.0'
 
 export interface LaunchOptions {
     extensionPath: string
+    // Path passed to VSCode as the workspace argument — either a single file
+    // (opens with that file active) or a folder (opens a folder workspace).
     workspacePath: string
+    // Optional workbench-settings overrides merged into the seeded settings.json
+    // for this launch. Used by shots that need a specific theme, layout engine,
+    // or any other setting that has to be in place before the first paint.
+    settingsOverrides?: Record<string, unknown>
 }
 
 export interface LaunchResult {
@@ -58,9 +71,10 @@ export async function launchVSCodeWithExtension(opts: LaunchOptions): Promise<La
     // from the first paint — no flash of the secondary side bar.
     const userDir = path.join(userDataDir, 'User')
     mkdirSync(userDir, { recursive: true })
+    const mergedSettings = { ...WORKBENCH_SETTINGS, ...(opts.settingsOverrides ?? {}) }
     writeFileSync(
         path.join(userDir, 'settings.json'),
-        JSON.stringify(WORKBENCH_SETTINGS, null, 2) + '\n'
+        JSON.stringify(mergedSettings, null, 2) + '\n'
     )
 
     const args = [