instar 1.3.788 → 1.3.789

package/dashboard/index.html

@@ -562,7 +562,17 @@
     /* F3 — Dashboard UX Standard: every tab's plain-language purpose line.
        One muted, readable sentence directly under the tab header telling a
        non-expert what the tab is for and what they can do here. Enforced by
-       tests/unit/dashboard-tab-purpose.test.ts. */
+       tests/unit/dashboard-tab-purpose.test.ts.
+
+       F7 — CANONICAL purpose-line class. `.tab-purpose` is the shared vocabulary
+       every NEW tab should use for its purpose line. Three legacy variants still
+       exist and carry their own deliberately-distinct sizing — `.ph-intro`
+       (Process-Health design-system intro, larger), `.features-subtitle`, and
+       `.dropzone-subtitle` — all recognized by the F3 floor test. Per the spec
+       (docs/specs/dashboard-ux-standard.md, FD-3) F7 is soft-first: consolidating
+       those three into `.tab-purpose` is a tracked migration (it changes their
+       visual size, so it is done deliberately, not big-bang). Until then: reach
+       for `.tab-purpose`; do not add a fifth variant or an inline-styled line. */
     .tab-purpose {
       font-size: 13px;
       color: var(--text-dim);
@@ -2950,7 +2960,7 @@
       </div>
       <div class="file-content-panel" id="fileContentPanel">
         <div class="file-content-header" id="fileContentHeader" style="display:none">
-          <button class="files-back-btn" onclick="filesGoBack()">&larr;</button>
+          <button class="files-back-btn" onclick="filesGoBack()" title="Back" aria-label="Back">&larr;</button>
           <div class="breadcrumbs" id="fileBreadcrumbs"></div>
           <div class="file-badges" id="fileBadges"></div>
         </div>
@@ -3229,7 +3239,7 @@
         Multi-spec project plans. Each project groups related pieces of work and only advances to its next round once its required checks pass.
       </div>
       <div id="projectsEmpty" style="padding:40px;text-align:center;color:var(--text-dim);display:none">
-        No active projects. Create one via <code>POST /projects</code> with a plan-doc path.
+        No active projects yet. Ask your agent to start one from a plan document, and it'll appear here.
       </div>
       <div id="projectsList" style="display:flex;flex-direction:column;gap:12px"></div>
     </div>
@@ -3260,7 +3270,7 @@
       </div>
       <div id="initiativesDigest" style="display:none;padding:12px;border:1px solid var(--border);border-radius:6px;background:var(--bg-dim)"></div>
       <div id="initiativesEmpty" style="padding:40px;text-align:center;color:var(--text-dim);display:none">
-        No initiatives to display. Create one via <code>POST /initiatives</code>.
+        No initiatives yet. Ask your agent to create one, and it'll appear here.
       </div>
       <div id="initiativesList" style="display:flex;flex-direction:column;gap:12px"></div>
     </div>
@@ -3945,7 +3955,7 @@
   <!-- WhatsApp QR panel (hidden by default) -->
   <div class="wa-qr-backdrop" id="waQrBackdrop" style="display:none" onclick="closeQrPanel()"></div>
   <div class="wa-qr-panel" id="waQrPanel" style="display:none">
-    <button class="wa-close" onclick="closeQrPanel()">&times;</button>
+    <button class="wa-close" onclick="closeQrPanel()" title="Close" aria-label="Close">&times;</button>
     <h3>WhatsApp Connection</h3>
     <p id="waQrMsg">Scan this QR code with WhatsApp to connect</p>
     <div id="waQrContainer"></div>
@@ -7649,7 +7659,7 @@
 
       detail.innerHTML = '<div class="job-detail-header">'
         + '<div>'
-        + '<button class="back-btn" onclick="jobsGoBack()" style="display:none;margin-right:8px">&larr;</button>'
+        + '<button class="back-btn" onclick="jobsGoBack()" style="display:none;margin-right:8px" title="Back" aria-label="Back">&larr;</button>'
         + '<h3>' + esc(displayName) + '</h3>'
         + '<div class="job-desc">' + esc(job.description || '') + '</div>'
         + '</div>'
@@ -9420,7 +9430,7 @@
       try {
         const data = await apiFetch(info.endpoint);
         panel.innerHTML = '<div class="cap-content-panel">' +
-          '<div class="cap-content-header"><span>' + esc(info.label) + '</span><button onclick="document.getElementById(\'capContentBrowser\').innerHTML=\'\'" style="border:none;background:none;color:var(--text-dim);cursor:pointer;font-size:14px">&times;</button></div>' +
+          '<div class="cap-content-header"><span>' + esc(info.label) + '</span><button onclick="document.getElementById(\'capContentBrowser\').innerHTML=\'\'" style="border:none;background:none;color:var(--text-dim);cursor:pointer;font-size:14px" title="Close" aria-label="Close">&times;</button></div>' +
           '<div class="cap-content-body">' + renderBrowsableContent(info.renderer, data) + '</div></div>';
       } catch (e) {
         panel.innerHTML = '<div style="padding:12px;color:var(--red);font-size:12px">Failed to load: ' + esc(e.message) + '</div>';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.788",
+  "version": "1.3.789",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-07-09T06:42:14.302Z",
-  "instarVersion": "1.3.788",
+  "generatedAt": "2026-07-09T07:11:33.686Z",
+  "instarVersion": "1.3.789",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.789.md

@@ -0,0 +1,44 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+- **Every dashboard control is now labeled (Dashboard UX Standard F5).** Four icon-only buttons
+  (the Files back arrow, the QR-panel close, the Jobs back arrow, and the capability-content
+  close) shipped as a bare `←` / `×` glyph with no accessible name — a user (or screen reader)
+  had to guess. Each now carries a `title` + `aria-label`. A build-time floor
+  (`dashboard-controls-labeled.test.ts`) fails if any future button ships icon-only.
+- **Empty states speak plain language, not API jargon (F6).** Two empty states told the operator
+  to "Create one via `POST /projects`" / "`POST /initiatives`" — meaningless to the person
+  reading the dashboard. They now say "Ask your agent to start one … and it'll appear here." A
+  floor (`dashboard-empty-states.test.ts`) fails on a bare or jargon-leaking empty state.
+- **Shared purpose-line vocabulary documented (F7, soft-first).** `.tab-purpose` is marked the
+  canonical purpose-line class; the three legacy variants (`ph-intro`, `features-subtitle`,
+  `dropzone-subtitle`) are documented for a tracked, deliberate migration (per spec FD-3, not a
+  big-bang restyle).
+- **Broken-asset floor (F8).** `dashboard-assets-resolve.test.ts` fails if a referenced local
+  image/icon has no file on disk.
+
+## What to Tell Your User
+
+A few more dashboard papercuts are gone: every button now has a readable label (better for
+accessibility too), and the "nothing here yet" messages tell you what to do in plain English
+instead of showing a developer command. Nothing to enable — it lands with the release.
+
+## Summary of New Capabilities
+
+- None — UX polish plus three build-time floors (F5 control labeling, F6 empty-state clarity,
+  F8 asset resolution) that fail the build if a future change regresses them.
+
+## Evidence
+
+`tests/unit/dashboard-controls-labeled.test.ts` (F5): scans every `<button>` in
+`dashboard/index.html`, asserts each has visible text, `title`, or `aria-label` (population floor
+≥30). `tests/unit/dashboard-empty-states.test.ts` (F6): audits the `*Empty*` resting-state
+containers (population floor ≥6) for a real sentence and no `POST /…`/curl jargon.
+`tests/unit/dashboard-assets-resolve.test.ts` (F8): every static local `src`/`url(...)` ref
+resolves to a real file (logo.png confirmed present). All 7 dashboard floor tests green (13
+cases, 1 browser-gated skip). Display-only markup + build-time floors — no runtime surface;
+machine-local static asset; rollback is a plain revert.

package/upgrades/side-effects/dashboard-f5-f8.md

@@ -0,0 +1,22 @@
+# Side-effects review — Dashboard UX Standard floors F5–F8
+
+**Change:** `dashboard/index.html` (F5 button labels, F6 empty-state de-jargoning, F7 canonical-class doc) + three static floor tests (`dashboard-controls-labeled` F5, `dashboard-empty-states` F6, `dashboard-assets-resolve` F8). Spec: `docs/specs/dashboard-ux-standard.md` (converged + approved, shipped in #1404). Tier 1 — display-only markup + build-time CI floors; no runtime `src/` change, no decision logic.
+
+## Phase 1 — Principle check (signal vs authority)
+Does this touch a decision point that gates information flow / blocks actions / constrains agent behavior? **No.** The changes are (a) HTML label/text attributes rendered to the operator and (b) static test files that fail a *build* if the dashboard regresses. The tests are build-time CI floors, not runtime authorities — they never gate a message, session, or agent action. Signal-vs-authority does not apply (no runtime decision surface).
+
+## Phase 4 — Side-effects review
+1. **Over-block:** the floor tests could reject legitimate markup. F5 accepts a button labeled by visible text OR `title` OR `aria-label` OR dynamic (`${…}`/concatenated) content — the full current button population passes; a button labeled *only* by an adjacent element (not itself) would false-flag, acceptable because self-labeling is the accessibility norm and easily satisfied. F6 requires a ≥4-word sentence in each `*Empty*` container — a legitimately terse state would flag, but the 4-word floor is lenient. F8 excludes `data:`/`http(s)`/dynamic `${}` srcs, so only real static local refs are checked. No legitimate current markup is rejected (all 7 dashboard tests green).
+2. **Under-block:** F5 checks `<button>` only, not `<select>`/`<input>` labeling (a tracked F5 follow-up <!-- tracked: topic-29723 -->). F6 audits `*Empty*`-id containers, not every conceivable resting state. F8 checks static local refs only. These are honest partial floors that raise the bar without claiming totality — not regressions.
+3. **Level-of-abstraction fit:** correct layer. A UI-consistency standard is enforced at build time over the shipped markup; there is no smarter runtime gate this should feed (it is not a runtime concern). It extends the existing dashboard-floor test family (`dashboard-tab-purpose`, `dashboard-panel-placement`, `dashboard-nav-reachability`, `dashboard-viewport-scroll`) — same pattern, same layer.
+4. **Signal vs authority compliance:** compliant by absence — no blocking authority added (build-time test, not runtime gate). See Phase 1.
+5. **Interactions:** the new F5/F6/F8 tests are independent scans over `index.html`; none shadows another. The F7 change is a CSS *comment* only — it does not alter the `.tab-purpose` rule and the F3 `dashboard-tab-purpose` test (which recognizes all four purpose-line classes) still passes. No double-fire, no race with cleanup.
+6. **External surfaces:** changes the dashboard HTML the operator sees — 4 icon buttons gain accessible names, 2 empty states lose API jargon ("POST /projects" → plain language). Strictly additive/clarifying; no behavior, endpoint, or data change. No surface visible to other agents/users/systems. No timing/conversation-state dependency.
+7. **Multi-machine posture:** **machine-local BY DESIGN** — `dashboard/index.html` is a static asset shipped in the package and served by each machine's own server; every machine serves the identical shipped file, so there is nothing to replicate, proxy, or transfer. No durable state, no generated URL, no user-facing notice. A single-machine assumption is correct here, not a defect.
+8. **Rollback cost:** trivial — `git revert` the commit. Display-only markup + additive tests; no migration, no agent-state repair, no data change.
+
+## Phase 4.5 — No deferrals
+The two under-block follow-ups (F5 select/input labeling; broader F6 coverage) are tracked <!-- tracked: topic-29723 -->. F7 hard-consolidation is deliberately soft-first per the spec's FD-3, not an orphan deferral. No partial fix of an in-scope item is shipped.
+
+## Phase 5 — Second pass
+Not required: no block/allow, session-lifecycle, coherence, or sentinel/guard/gate/watchdog surface (Tier 1, display-only).