release: beta → main (next stable)

.ai/architecture.yaml

@@ -22,12 +22,12 @@ components:
       validationProvider.ts: Input validation with Quick Fixes
       componentBrowserProvider.ts: Component browser webview UI
       componentDetector.ts: Detect GitLab CI component usage in YAML
-      componentHtmlRenderer.ts: Render component docs as HTML
+      hoverContentBuilder.ts: Build the hover popup's markdown body (vscode-free, unit-tested)
     depends_on:
     - services
     - utils
     - types
-    - templates
+    - webview
   services:
     location: src/services/
     purpose: Business logic and data management
@@ -77,14 +77,17 @@ components:
     depends_on:
     - types
     - utils
-  templates:
-    location: src/templates/
-    purpose: HTML template generation for webview UIs
+  webview:
+    location: src/webview/
+    purpose: Helpers and assets for the webview documents rendered by the providers
     files:
-      detachedComponent.ts: Detached component view template
-      helpers/htmlBuilder.ts: HTML construction helper
-      helpers/styleBuilder.ts: CSS style helper
-      index.ts: Public exports
+      webviewHtml.ts: Nonce, Content-Security-Policy and asset-URI helpers for webview documents
+      inlineMarkdown.ts: HTML escaping and inline-Markdown rendering (vscode-free, unit-tested)
+      scriptData.ts: Safe JSON serialization for embedding data in a script block (vscode-free, unit-tested)
+      clientInlineMarkdown.ts: Source text for the browser-side twin of renderInlineMarkdown (vscode-free, unit-tested)
+      styles/: Stylesheets built to out/webview/styles/ and loaded via a CSP'd link
+    notes: Assets under styles/ (and client/ as scripts are extracted) are built by the webview esbuild
+      context and resolved at runtime through assetUri; they are not bundled into out/extension.js.
     depends_on:
     - types
   constants:
@@ -213,8 +216,8 @@ data_flow:
     component: componentService
     action: Fetch component details (cache-first)
   - step: 4
-    component: componentHtmlRenderer
-    action: Render documentation as HTML using templates/helpers
+    component: hoverContentBuilder
+    action: Build the hover markdown body (a MarkdownString, not HTML)
   - step: 5
     component: hoverProvider
     action: Display hover card

.ai/decisions.yaml

@@ -124,6 +124,42 @@ decisions:
     - .release-it/vscode-version.js
     - package.json (release:main, release:beta scripts)
     title: Release It
+  DEPENDABOT_TARGETS_BETA:
+    date: '2026-09-14'
+    status: accepted
+    context: Dependabot defaulted to the repository default branch (main), which is the stable
+      release line. Bumps opened there duplicated what had already landed on beta, and a merge
+      to main auto-cuts a stable release.
+    decision: 'Set target-branch: "beta" on every ecosystem in .github/dependabot.yml (npm,
+      github-actions, pip)'
+    rationale:
+    - A push to main runs release-it with .release-it.json and cuts a stable GitHub release, so
+      a routine dependency bump merged there ships a release out of band
+    - main trails beta by everything not yet released, so bumps against main duplicate versions
+      beta already carries (e.g. #291/#292/#295 re-proposed bumps merged weeks earlier)
+    - Retargeting such a PR to beta conflicts on package-lock.json, since beta has moved
+    - Updates reach main the same way every other change does, through the beta -> main release PR
+    implementation:
+      config: '.github/dependabot.yml, target-branch: "beta" on each of the three package-ecosystem
+        entries'
+      flow: dependabot -> beta -> release PR -> main
+    alternatives_considered:
+    - name: leave_targeting_main
+      rejected_because: Ships stable releases from dependency bumps and produces duplicate PRs
+    - name: retarget_each_pr_by_hand
+      rejected_because: Lockfile conflicts on every npm PR; recurring manual work
+    consequences:
+      positive:
+      - Dependency updates follow the same path as feature work
+      - No stable release cut by a dependency bump
+      - No duplicate bumps against a stale branch
+      negative:
+      - A security fix reaches main only when the next release PR merges
+    references:
+    - .github/dependabot.yml
+    - .release-it.json
+    - .release-it.beta.json
+    title: Dependabot Targets Beta
   MODULAR_SERVICE_SPLIT:
     date: '2026'
     status: accepted

.ai/index.yaml

@@ -25,9 +25,9 @@ keys:
   - providers
   - scripts
   - services
-  - templates
   - types
   - utils
+  - webview
   workflows:
   - add_configuration_option
   - add_new_command
@@ -43,6 +43,7 @@ keys:
   - BATCH_API_REQUESTS
   - CACHE_COMPONENTS
   - CENTRALIZED_ERROR_HANDLING
+  - DEPENDABOT_TARGETS_BETA
   - EXTENSION_HOST_TEST_LAYER
   - FILE_SIZE_POLICY
   - MOCHA_OVER_JEST

.ai/workflows.yaml

@@ -145,6 +145,7 @@ common_commands:
   debug: F5 (in VS Code)
   package: npm run package
   lint: npm run lint
+  lint_ci: npm run lint:ci (eslint + stylelint with GitHub annotation formatters; run by CI)
 git_workflow:
   branch_naming: feature/description or fix/description
   commit_format: 'type(scope): description'

.github/dependabot.yml

@@ -6,11 +6,18 @@
 # in osv-scanner.toml that the Argus scan honors. Do NOT add a dev-dep `ignore:` here to suppress
 # those alerts -- `ignore:` also stops the version-update PRs below, which are how dev tools stay
 # current and how a transitive fix (e.g. serialize-javascript >= 7.0.5) actually lands.
+#
+# Every ecosystem below sets `target-branch: "beta"`. Without it Dependabot opens against the default
+# branch (`main`), which is the STABLE release line: a push there auto-cuts a stable GitHub release, so a
+# routine dependency bump would ship one out of band. `main` also trails `beta` by whatever has not been
+# released yet, so bumps opened against it duplicate what already landed on `beta` and conflict on the
+# lockfile when retargeted. Everything reaches `main` through the beta -> main release PR instead.
 version: 2
 updates:
   # Maintain npm dependencies
   - package-ecosystem: "npm"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"
@@ -68,6 +75,7 @@ updates:
   # Maintain GitHub Actions
   - package-ecosystem: "github-actions"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"
@@ -85,6 +93,7 @@ updates:
   # Maintain pre-commit hooks
   - package-ecosystem: "pip"
     directory: "/"
+    target-branch: "beta"
     schedule:
       interval: "weekly"
       day: "monday"

.github/workflows/ci.yml

@@ -27,7 +27,7 @@ jobs:
         run: npm ci
 
       - name: Run lint
-        run: npm run lint
+        run: npm run lint:ci
 
       - name: Run compile
         run: node esbuild.js

.github/workflows/security-hardening.yml

@@ -19,8 +19,10 @@ permissions:
 jobs:
   argus-hardening:
     name: Argus Reusable Hardening
-    # Pinned to the commit for Argus v1.11.0 for supply-chain safety.
-    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@9b444d8975f4a2253cc53e09a7c5837e5b509d24
+    # SHA-pinned rather than tag-pinned for supply-chain safety: a tag can be moved, a commit cannot.
+    # Dependabot bumps this SHA and names the tag it resolves to in the PR title, so read the version there
+    # rather than trusting a hand-written one here (this comment claimed v1.11.0 through three bumps past it).
+    uses: huntridge-labs/argus/.github/workflows/reusable-security-hardening.yml@3fb133a5d03ec81a7a534cf451dd19991e04a975
     with:
       scanners: codeql,gitleaks,osv,dependency-review
       enable_code_security: true