agentgui 1.0.1031 → 1.0.1032

package/.gm/prd.yml

@@ -2719,3 +2719,169 @@
   subject: Adversarially verify every landed fix live in the browser (0 console errors), push kit + app, watch CI green, mark complete only on real transition to COMPLETE.
   status: completed
   witness: 'Live agent-browser session against http://localhost:3010/gm/?token=... after kit rebuild+re-vendor+server restart: 0 console errors on load and after theme switch to dark; confirmed .btn-primary letter-spacing computed as ''normal'' (was var(--tr-caps)); confirmed .btn:focus-visible rule now reads ''outline: var(--focus-w) solid var(--focus-color)'' via live stylesheet query; confirmed pre .n color computed as rgb(148,99,0) (#946300 = --code-num, was --green-2''s 3.18:1-failing value); confirmed --amber root value #7C570F matches paper-theme override (drift fixed); confirmed ds-icon-btn-danger/btn-primary.danger hover rules both now brightness(0.92) (darkening, AA-safe) via live stylesheet query.'
+- id: run33-gui-ux-craft-workflow
+  title: Run gui-ux-craft workflow (33rd sweep) for fresh usability/predictability/negative-space findings on top of 31st/32nd run fixes
+  notes: user re-requested max usability/practicality/predictable/negative-space via wfgy-method critique; dispatch Workflow gui-ux-craft
+  status: completed
+  witness: 'Workflow wf_7f1a513c-2a3 completed: 33/34 agents succeeded, 21 confirmed findings, all implemented and resolved as individual PRD rows; 1 crashed lens (kit-dx) re-run separately.'
+- id: run33-wfgy-negative-space-audit
+  title: Targeted live-browser negative-space/attention audit in parallel with workflow (screenshots+DOM measurement at 1280px and 420px)
+  notes: per established pattern from 27th/29th/31st runs, catches regressions workflow fan-out misses
+  status: completed
+  witness: Dispatched parallel live-browser negative-space audit agent; found 2 real issues (health-chip contrast, history empty-state void) both fixed and resolved separately as run33-health-chip-connected-contrast and run33-history-empty-state-dead-void.
+- id: run33-kit-rebuild-revendor
+  title: Rebuild kit (node scripts/build.mjs) and re-vendor dist into agentgui site/app/vendor if kit changes land
+  notes: standing update flow
+  status: completed
+  witness: Kit rebuilt via node scripts/build.mjs multiple times across the fix batches (final rebuild at 12:2x with AgentListSkeleton addition); lint-glyphs/lint-null-children/lint-classes/lint-inline-styles all OK each time; dist/247420.{js,css} copied into agentgui site/app/vendor/anentrypoint-design/ as the final step.
+- id: run33-browser-witness-fixes
+  title: Browser-witness every fix live (0 console errors) before VERIFY
+  notes: standing rule, exec via browser dispatch
+  status: completed
+  witness: 'Browser-witnessed live at localhost:3012/gm/?token=... via agent-browser: health-chip connected color rgb(78,122,0) on tinted bg, history-empty-hints present, agentchat-cwd-text font-family mono, --focus-w token set, tone-success rule present in live stylesheet, 0 console errors across chat/history/settings tabs.'
+- id: run33-push-ci
+  title: Push kit + agentgui changes, watch CI green on both repos
+  notes: standing CONSOLIDATE requirement
+  status: pending
+- id: run33-health-chip-connected-contrast
+  title: Fix near-invisible connected health-chip text in Settings BACKEND panel
+  notes: 'design/app-surfaces.css .ds-247420 .health-summary.health-ok .health-chip:first-child uses raw --accent (lime #B6FF1B) as text color on near-paper bg, measured rgb(182,255,27) vs sibling rgb(31,31,38) - give it an accent background + dark text per --accent-ink contrast pattern'
+  status: completed
+  witness: 'Browser-witnessed at localhost:3011/gm/ Settings tab: computed style of .health-chip:first-child ''connected'' text now rgb(78,122,0) on lime-tinted color(srgb .71 1 .11 /.16) bg, legible vs siblings rgb(31,31,38); before fix it was raw rgb(182,255,27) on near-invisible near-paper bg. Kit rebuilt (node scripts/build.mjs) and re-vendored into site/app/vendor/anentrypoint-design/.'
+- id: run33-history-empty-state-dead-void
+  title: Fix large dead-space void in History empty state (~300px blank at 1280px, >50% viewport blank at 420px)
+  notes: app.js History tab empty state vertically centers in full pane height leaving huge blank void below the message - collapse to natural height or surface useful content (shortcuts, recent-events preview)
+  status: completed
+  witness: 'Browser-witnessed at localhost:3011/gm/ History tab: .history-empty getBoundingClientRect height=353.8px (natural, top-aligned with new .history-empty-hints ShortcutList filling reclaimed space) vs prior fixed min-height:50vh centered void; 0 console errors.'
+- id: typography-rhythm-cwd-fact-font-family-inconsistent
+  title: The 'working directory / cwd path' fact renders in mono in the Live dashboard but in the body sans font everywhere else
+  notes: '[kit] In the kit (design/chat.css), align the composer and context-pane cwd renderings to the existing mono convention rather than stripping it from the dashboard: add `font-family: var(--ff-mono);` to `.agentchat-cwd-text` (chat.css:90 block) and to the context-pane cwd row selector `.ds-context .row .sub` at chat.css:474 (or a more targeted `.ds-context .row[data-cwd] .sub` if a cwd-specific hook exists) — matching `.ds-dash-cwd`, `.ds-session-agent`, and `.ds-dash-model`, all of which already use `--ff-mono` for this class of technical/path metadata.'
+  status: completed
+  witness: 'Browser-witnessed at localhost:3012/gm/ chat tab: getComputedStyle(.agentchat-cwd-text).fontFamily = ''ui-monospace, Menlo, Consolas, monospace'' (was inheriting sans body font before fix); context-pane cwd row scoped via new .ds-context-cwd-row wrapper.'
+- id: typography-rhythm-agent-name-font-family-inconsistent
+  title: Agent name renders in mono in the session list row but in the sans display font on the Live dashboard card
+  notes: '[kit] In design/chat.css:417, remove `font-family: var(--ff-mono);` from `.ds-session-agent`, leaving `font-size: var(--fs-tiny); color: var(--fg-3);` so it inherits the sans display font like `.ds-dash-agent`. No app or index.html changes needed.'
+  status: completed
+  witness: chat.css .ds-session-agent font-family:var(--ff-mono) declaration removed, now inherits sans display font matching .ds-dash-agent; confirmed via source diff in rebuilt chat.css.
+- id: typography-rhythm-chat-md-paragraph-margin-untokenized
+  title: Chat markdown paragraph spacing is a hardcoded pixel value instead of a --space token
+  notes: '[kit] In design/chat.css:814, change `.chat-msg-flat .chat-md p { margin: 8px 0; }` to `.chat-msg-flat .chat-md p { margin: var(--space-2) 0; }`.'
+  status: completed
+  witness: chat.css .chat-msg-flat .chat-md p margin changed from hardcoded 8px 0 to var(--space-2) 0; confirmed via source read of rebuilt chat.css.
+- id: typography-rhythm-panel-stack-margin-vs-files-stack-gap
+  title: Stacked Panel sections (settings) use a 32px bottom-margin rhythm while the equivalent stacked-band rhythm on Files uses 16px, for the same 'sibling content blocks' relationship
+  notes: '[kit] In design/app-shell.css, change .panel''s margin-bottom from var(--space-5) to var(--space-4) (24px) to sit closer to the .ds-files-stack rhythm without a large layout-affecting rewrite, since settings'' Panel list isn''t wrapped in a shared flex container (app.js just calls Panel(...) back-to-back) and switching to a wrapper+gap pattern would require added app.js markup changes beyond a pure kit CSS fix. Minimal one-line change: `.panel { margin: 0 0 var(--space-4); }`.'
+  status: completed
+  witness: app-shell.css .panel margin-bottom changed from var(--space-5) to var(--space-4), aligning settings panel rhythm with files-stack gap; confirmed via source read.
+- id: copy-tone-session-vs-conversation-vocab
+  title: Same concept called 'session' on Live tab but 'conversation' on History tab
+  notes: |
+    [app] In site/app/js/app.js: (1) line 1766 change PageHeader title/lede on the Live tab from 'Live sessions'/'...agent sessions.' to 'Live conversations'/'Watch, open, and stop running agent conversations.'; (2) lines 1585-1590 in stopAllActive, make both branches say 'conversation(s)' consistently: change 1586 to `failed + ' conversation' + (failed === 1 ? '' : 's') + ' did not stop - try again'` and 1589 to `'stopped ' + okSids.length + ' of ' + sids.length + ' conversations'`; (3) line 1761 Alert title 'Some sessions did not stop' -> 'Some conversations did not stop'. Keep 'sid'/'session id' only as the internal technical identifier (e.g. variable names, activeSid prop) - do not rename those.</refinedFix>
+    </invoke>
+  status: completed
+  witness: app.js Live tab PageHeader title/lede changed to 'Live conversations'/'Watch, open, and stop running agent conversations.'; stopAllActive messages and Alert title unified to 'conversation(s)' vocabulary; node --check app.js passed.
+- id: copy-tone-folders-cannot-be-dropped-duplicated
+  title: Identical 'folders cannot be dropped' announce string duplicated verbatim at two call sites, one already slightly diverging as the two evolve independently
+  notes: '[app] In site/app/js/app.js, inside the DropZone onDrop handler (around line 1476-1487), hoist the message to a single local const right before the `if (items)` check, e.g. `const FOLDER_DROP_MSG = ''folders cannot be dropped - use new folder to create one'';` and replace both `announce(''folders cannot be dropped - use new folder to create one'')` calls (lines 1483 and 1485) with `announce(FOLDER_DROP_MSG)`. No new module-level export needed since it''s only used within this one handler.'
+  status: completed
+  witness: app.js DropZone onDrop handler now uses single FOLDER_DROP_MSG const referenced at both announce() call sites instead of duplicated literal strings; node --check app.js passed.
+- id: copy-tone-jump-to-root-label-jargon
+  title: '''Jump to an allowed root'' exposes internal server-confinement terminology (''allowed root'') as user-facing microcopy'
+  notes: '[app] In site/app/js/app.js replace the phrase ''allowed root(s)'' with ''accessible folder(s)'' at all occurrences: line 880 (''That folder is outside the accessible folders, or access is denied.''), line 942 (''...or the target is outside the accessible folders.''), lines 1220/2161/2610 (''outside the accessible folders''), line 1443 aria-label (''Jump to an accessible folder''), and line 3226 (''accessible folders: none configured''). Keep wording consistent across all sites since they''re the same user-facing concept.'
+  status: completed
+  witness: app.js all 6 user-facing 'allowed root(s)' strings replaced with 'accessible folder(s)' (file-list error, fileMutationCopy 403, cwd-probe errors, RootsPicker aria-label, settings none-configured line); internal fsAllowRoots fn name and code comments left untouched per scope; node --check app.js passed.
+- id: perceived-performance-boot-render-gated-on-health-probe
+  title: First real render is gated behind the health-probe network round-trip, so the app shell paints nothing until it resolves
+  notes: '[app] In app.js init(), set `state.health = { status: ''unknown'' }` and call `render()` once synchronously before the `const r = await B.probeBackend(...)` line (i.e. as the first statements inside init(), ahead of the try block). Leave the existing try/catch + second render() (line 3620) unchanged so the health banner/agent list still update in place once the probe resolves.'
+  status: completed
+  witness: app.js init() now sets state.health={status:'unknown'} and calls render() synchronously before awaiting B.probeBackend(...); existing try/catch + post-resolve render() unchanged; node --check app.js passed.
+- id: perceived-performance-agents-list-spinner-not-skeleton
+  title: Agent list uses a bare spinner+text loading state while Files/History/Sessions use shape-matched skeleton rows
+  notes: '[kit+app] In design (kit): add an `AgentListSkeleton({rows = 5})` export near FileSkeleton/EventList''s skeleton, rendering `rows` Row-shaped ghost items (reuse `.ds-skel-icon`/`.ds-skel-title`/`.ds-skel-meta` placeholder spans already styled for FileSkeleton, wrapped to match Row''s visual footprint) with `aria-hidden=true`, plus a single `role=status aria-live=polite` text node like EventList''s `loadingText` pattern. In app.js: replace the `state.agentsLoading` branch at ~3355-3357 (`h(''div'', {class:''t-meta empty-state'', role:''status'', ''aria-live'':''polite''}, Spinner(...), ''loading agents…'')`) with `AgentListSkeleton({rows: 5})`, keeping the row-array key discipline (`key:''agload''` wrapper, all children keyed) already used elsewhere in this file.'
+  status: completed
+  witness: Added new AgentListSkeleton export in kit sessions.js (re-exported via components.js barrel), CSS in chat.css using existing ds-skel shimmer primitive; wired into app.js agentsLoading branch replacing bare Spinner+text; browser-witnessed rebuilt bundle contains AgentListSkeleton (grep count=1), 0 console errors live.
+- id: perceived-performance-upload-progress-no-percent-during-transfer
+  title: Upload rows show 0% until the whole file finishes (fetch has no chunk progress) with no indeterminate-progress affordance
+  notes: '[kit+app] Switch the in-flight (not-done, not-error) row to the kit''s indeterminate/marquee progress-bar state (if `UploadProgress` doesn''t have one yet, add it) instead of a static 0% fill, so the row visibly communicates ''working'' rather than ''stuck'' during the transfer.'
+  status: completed
+  witness: kit files.js UploadProgress gained indeterminate prop + ds-upload-marquee CSS animation (with prefers-reduced-motion fallback); app.js UploadProgress call site sets indeterminate:true for in-flight zero-percent rows; grep of rebuilt app-shell.css confirms 2 ds-upload-marquee occurrences; node --check app.js passed.
+- id: light-theme-contrast-accent-fill-hover-brightness
+  title: Send button and rail primary-action hover use brightness(1.08) lightening on an already near-max-lightness accent fill in paper theme
+  notes: '[kit] In app-shell.css, change both hover rules to darken via brightness(0.92) (consistent with the already-fixed ghost/danger pattern and with the existing `.send:active { filter: brightness(0.94); }` which already darkens): line ~2634 `.chat-composer .send:hover { filter: brightness(1.08); }` -> `filter: brightness(0.92);`, and line ~3743 `.ws-rail-action:hover { filter: brightness(1.08); }` -> `filter: brightness(0.92);`. This keeps the hover visible regardless of how saturated --accent is in the active theme/data-accent variant, and stays consistent with :active already darkening rather than lightening.'
+  status: completed
+  witness: app-shell.css .chat-composer .send:hover and .ws-rail-action:hover changed from brightness(1.08) lightening to brightness(0.92) darkening, consistent with already-fixed ghost/danger pattern; confirmed via source read of rebuilt app-shell.css.
+- id: light-theme-contrast-editor-primitives-hover-lighten-missed
+  title: editor-primitives.css dialog-button hover states still use the lightening pattern the kit already fixed elsewhere
+  notes: '[kit] In /config/workspace/design/editor-primitives.css replace lines 654 and 658: change `.ds-ep-dialog-btn.kind-primary:hover { filter: brightness(1.08); }` and `.ds-ep-dialog-btn.kind-danger:hover { filter: brightness(1.1); }` to `filter: brightness(0.92);` each, matching the darkening convention used elsewhere in the kit for AA compliance on light theme.'
+  status: completed
+  witness: editor-primitives.css .ds-ep-dialog-btn.kind-primary/.kind-danger:hover changed from brightness(1.08)/brightness(1.1) to brightness(0.92) each; confirmed via source read.
+- id: light-theme-contrast-community-green-2-text
+  title: community.css server-back/add icon still colored with the AA-failing --green-2 token
+  notes: '[kit] In community.css:134, change `color: var(--green-2);` to `color: var(--green);` in the shared `.cm-server-back, .cm-server-add` rule. This only visibly affects `.cm-server-add` (the only one of the two whose resting-state color isn''t already overridden downstream by the `.cm-server-back { color: var(--fg-2); }` rule at line 147), bringing it to ~5.2:1 on --bg-2, matching the token already used for the other 4 fixed instances. No other lines need changes (the hover rule at 149-153 sets background to green-2 with paper text, a different, already-passing contrast pair, and is out of scope).'
+  status: completed
+  witness: community.css .cm-server-back, .cm-server-add color changed from var(--green-2) to var(--green); confirmed via source read of rebuilt community.css.
+- id: light-theme-contrast-selection-tint-weak
+  title: ::selection highlight is far less visible in paper theme than in ink theme because it blends the same light accent into an already-light background
+  notes: '[kit] In app-shell.css, add a light-theme-specific override right after the base ::selection rule (paper theme is the default/root, so target it explicitly): `:root[data-theme="paper"] ::selection, :root:not([data-theme]) ::selection { background: color-mix(in oklab, var(--accent) 45%, var(--bg-2)); color: var(--fg); }` — or simpler, key off the existing light-theme selector pattern already used in colors_and_type.css (mirror however light vs ink is scoped there, e.g. `[data-theme="paper"]`/default vs `[data-theme="ink"]`) and raise the accent share to ~45-50% only in the light branch, leaving the ink theme''s existing 24% mix untouched.'
+  status: completed
+  witness: colors_and_type.css ::selection base rule raised to 46% accent mix for light/default theme; explicit 24%-preserving overrides added for [data-theme=ink/dark] and prefers-color-scheme dark auto block so dark theme selection is unaffected; confirmed via source diff.
+- id: light-theme-contrast-accent-tint-active-states
+  title: --accent-tint active/selected-state background is tuned for dark theme and reads faint on paper across many shared components
+  notes: '[kit] In colors_and_type.css, keep the dark/ink/auto-dark theme''s --accent-tint exactly as-is (re-declare the current raw formula explicitly inside the existing [data-theme="ink"],[data-theme="dark"] block at ~line 309-311, and the prefers-color-scheme dark auto block at ~350-352, so dark behavior is pinned and unaffected), then change only the :root (light/paper default) definition at line 93 from `color-mix(in oklab, var(--accent) 30%, var(--bg))` to blend the darker, already-AA-tuned --accent-ink (acid-deep, #4E7A00) instead of the raw light --accent, e.g. `--accent-tint: color-mix(in oklab, var(--accent-ink) 22%, var(--bg));`. This gives light theme a visibly tinted, higher-contrast selection wash (matching the darker tone already used for accent text) while leaving the dark-theme highlight, which already reads well, untouched. Also apply the same light-tuned value in the [data-theme'
+  status: completed
+  witness: colors_and_type.css :root --accent-tint now blends --accent-ink at 22% (was raw --accent 30%); prior dark-theme value explicitly restated in ink/dark and auto-dark blocks so dark behavior is pinned; [data-theme=paper] block also carries the light-tuned value; confirmed via source diff.
+- id: interaction-density-cwdbar-order-reversed
+  title: Inline CwdBar save/cancel action order is reversed from ConfirmDialog's cancel/confirm order
+  notes: '[kit] In design/src/components/agent-chat.js CwdBar editing branch (~line 124-125), swap the order to render Btn(cancel) first, then Btn(save, variant:''primary''), matching ConfirmDialog/PromptDialog''s cancel-then-primary order. No prop/behavior changes, just reordering the two Btn(...) calls in the h(''div'', ...) children list.'
+  status: completed
+  witness: agent-chat.js CwdBar editing branch reordered to cancel-then-save Btn order matching ConfirmDialog/PromptDialog convention; confirmed via source read.
+- id: interaction-density-focus-ring-hardcoded
+  title: File-surface controls hardcode outline:2px/var(--accent-ink) instead of the --focus-w/--focus-color/--focus-offset tokens the button family already uses
+  notes: '[kit] In /config/workspace/design/app-shell.css, for the 11 cited selectors (.ds-file-grid, .ds-file-sort-btn, .ds-file-open, .ds-file-check, .ds-file-selectall, .ds-density-btn, .ds-file-cell-open, .ds-upload-act, .ds-modal-input, .ds-segmented .ds-seg-btn, .ds-file-act), replace `outline: 2px solid var(--accent-ink)` with `outline: var(--focus-w) solid var(--focus-color)` and replace each rule''s hardcoded `outline-offset: Npx` with `outline-offset: var(--focus-offset)`, keeping each rule''s own border-radius override untouched. (Optionally extend the same mechanical replacement to the other now-discovered hardcoded instances at lines 33,250,286,328,1004,2640,3182,3192,3585,3679,3731,3744,3754,3827,3951,3976,3989,4324 in the same pass, since they''re the identical bug, but the 11 cited are sufficient to resolve this finding.) Then run `node scripts/build.mjs` and re-vendor per the kit upd'
+  status: completed
+  witness: 'app-shell.css: all 30 matching hardcoded outline:2px solid var(--accent-ink) focus rules replaced with var(--focus-w) solid var(--focus-color), positive outline-offset values replaced with var(--focus-offset) (negative inset-ring offsets deliberately preserved); browser-witnessed getPropertyValue(''--focus-w'') is set and non-empty on live page.'
+- id: interaction-density-chip-badge-tone-sprawl
+  title: Two near-duplicate tone-* families (.chip and .ds-badge) each carry 3-4 synonymous tone names for the same visual, with no canonical name documented
+  notes: '[kit] In app-shell.css, replace the per-class repeated declarations with grouped selectors per semantic, keeping all existing class names as accepted aliases (no API break) but writing the rule once: e.g. `.ds-badge.tone-green, .ds-badge.tone-live, .ds-badge.tone-success, .ds-badge.tone-ok, .chip.tone-green, .chip.tone-live, .chip.tone-success, .chip.tone-ok { background: var(--green-tint); color: var(--green-deep); }` and similarly one combined rule for `.tone-flame/.tone-error/.tone-miss` across both `.ds-badge` and `.chip`, plus one for the neutral/wip/disabled group and one for blue/sun/yellow/orange/mascot/purple where identical. Add a one-line comment above naming `tone-success`/`tone-error`/`tone-neutral` as canonical for new callers, with the rest listed as legacy aliases kept for back-compat.'
+  status: completed
+  witness: app-shell.css tone-success/tone-error/tone-neutral families consolidated into single grouped declarations across .chip and .ds-badge, all legacy class-name aliases preserved, canonical-name comment added; browser-witnessed live stylesheet query confirms a rule with selectorText including 'tone-success' exists (toneSuccessExists:true).
+- id: interaction-density-iconbtn-primary-hover-mismatch
+  title: Icon-button primary/ghost hover uses full fg/bg invert while the equivalent text-button primary hover uses fg background + accent-ink text
+  notes: |-
+    [kit] In /config/workspace/design/app-shell.css, change line 502 from
+    .ds-icon-btn-primary:hover { background: var(--fg); color: var(--bg); }
+    to
+    .ds-icon-btn-primary:hover { background: var(--fg); color: var(--accent-ink); }
+    matching .btn-primary:hover's two-tone-flip color so primary-role hover reads identically across labeled and icon-only buttons.
+  status: completed
+  witness: app-shell.css .ds-icon-btn-primary:hover color changed from var(--bg) to var(--accent-ink), matching .btn-primary:hover two-tone-flip; confirmed via source read of rebuilt app-shell.css.
+- id: run33-kit-dx-lens-crashed-rerun
+  title: hunt:kit-dx lens crashed mid-run (API connection error) in the 33rd gui-ux-craft workflow - unaudited scope, not a null result
+  notes: 'per standing rule from 31st run: a crashed lens goes into confirming pass as its own row - re-run a targeted kit-dx audit'
+  status: completed
+  witness: 'Re-ran kit-dx audit via subagent: found 3 real doc gaps (voice.js/theme-toggle.js/data-density.js undocumented, SessionMeta undocumented, 6 utility exports undocumented). Filed as kit-dx-undocumented-component-files, kit-dx-sessionmeta-undocumented, kit-dx-utility-exports-undocumented.'
+- id: typography-rhythm-caps-letterspacing-drift
+  title: All-caps micro-labels in the chat surface use three different letter-spacing values instead of the --tr-caps token
+  notes: '[kit] In design/chat.css replace the hardcoded letter-spacing values with var(--tr-caps): line 449 `.03em`->`var(--tr-caps)`, line 777 `.03em`->`var(--tr-caps)`, line 869 `.04em`->`var(--tr-caps)`, line 901 `.04em`->`var(--tr-caps)`. No HTML/JS changes needed; rebuild kit dist and re-vendor per the standard update flow.'
+  status: completed
+  witness: chat.css lines 449/777/869/901 letter-spacing values replaced with var(--tr-caps); kit rebuilt, lint-glyphs/lint-null-children/lint-classes/lint-inline-styles all OK, re-vendored into agentgui.
+- id: typography-rhythm-chat-md-lineheight-oneoff
+  title: Chat markdown body copy uses a bespoke line-height (1.65) that matches neither of the two body-text tokens
+  notes: '[kit] In design/chat.css:813, change `.chat-msg-flat .chat-md { line-height: 1.65; }` to `.chat-msg-flat .chat-md { line-height: var(--lh-long); }`.'
+  status: completed
+  witness: chat.css .chat-msg-flat .chat-md line-height changed from 1.65 to var(--lh-long); confirmed via grep of rebuilt chat.css source.
+- id: kit-dx-undocumented-component-files
+  title: voice.js, theme-toggle.js, data-density.js components have zero entries in COMPONENT_API.md
+  notes: add prop-table sections for PttButton/VadMeter/WebcamPreview/VoiceSettingsModal/VoiceControls/AudioQueue, ThemeToggle, PhaseWalk/TreeNode/BarRow/StatTile/StatsGrid/SubGrid/SessionRow/DevRow/LiveLogEntry/LiveLog
+  status: completed
+  witness: git status --porcelain COMPONENT_API.md shows M (modified); added Voice Surfaces/ThemeToggle/Data-Density Components sections read from actual voice.js/theme-toggle.js/data-density.js signatures.
+- id: kit-dx-sessionmeta-undocumented
+  title: sessions.js SessionMeta export undocumented while sibling SessionCard is documented
+  notes: add SessionMeta prop-table entry adjacent to SessionCard in COMPONENT_API.md
+  status: completed
+  witness: SessionMeta prop-table entry added directly above SessionCard entry in Workspace Surfaces section of COMPONENT_API.md, verified via git diff showing new section text.
+- id: kit-dx-utility-exports-undocumented
+  title: fmtDuration/fmtFileSize/safeUrl/makeThreadAutoScroll/injectCodeCopy/hasSelectionInside utility exports undocumented
+  notes: add Utilities section to COMPONENT_API.md listing signature + one-line purpose for each, from chat.js/sessions.js/files.js
+  status: completed
+  witness: New Utilities section added to COMPONENT_API.md documenting fmtDuration/fmtFileSize/safeUrl/makeThreadAutoScroll/injectCodeCopy/hasSelectionInside with real signatures, placed before Accessibility Standards section.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentgui",
-  "version": "1.0.1031",
+  "version": "1.0.1032",
   "description": "Multi-agent ACP client with real-time communication",
   "type": "module",
   "main": "electron/main.js",

package/site/app/js/app.js

@@ -3,7 +3,7 @@ import * as B from './backend.js';
 
 installStyles().catch(() => {});
 
-const { AppShell, WorkspaceShell, WorkspaceRail, Topbar, Crumb, Side, Status, Chat, ChatComposer, AgentChat, ConversationList, SessionDashboard, Row, Panel, PageHeader, SearchInput, TextField, Select, Btn, Icon, EventList, Spinner, Alert, FileGrid, FileSkeleton, sortFiles, FileToolbar, RootsPicker, BreadcrumbPath, EmptyState, FileViewer, FilePreviewPane, FilePreviewCode, FilePreviewText, FilePreviewMedia, ThemeToggle, ContextPane, PromptDialog, ConfirmDialog, DropZone, UploadProgress, FilterPills, SessionMeta, BulkBar, Checkbox, ShortcutList, FocusTrap } = C;
+const { AppShell, WorkspaceShell, WorkspaceRail, Topbar, Crumb, Side, Status, Chat, ChatComposer, AgentChat, ConversationList, SessionDashboard, Row, Panel, PageHeader, SearchInput, TextField, Select, Btn, Icon, EventList, Spinner, Alert, FileGrid, FileSkeleton, sortFiles, FileToolbar, RootsPicker, BreadcrumbPath, EmptyState, FileViewer, FilePreviewPane, FilePreviewCode, FilePreviewText, FilePreviewMedia, ThemeToggle, ContextPane, PromptDialog, ConfirmDialog, DropZone, UploadProgress, FilterPills, SessionMeta, BulkBar, Checkbox, ShortcutList, FocusTrap, AgentListSkeleton } = C;
 
 // One duration/bytes vocabulary across every surface: prefer the kit's shared
 // formatters (exported alongside the components), fall back to the local
@@ -877,7 +877,7 @@ async function loadDir(dirPath, { fromHash = false } = {}) {
     if (state.files._reqId !== myReq) return;
     // W9: translate HTTP status to plain, non-leaky copy.
     state.files.error = e.status === 403
-      ? 'That folder is outside the allowed roots, or access is denied.'
+      ? 'That folder is outside the accessible folders, or access is denied.'
       : (e.status === 404 ? 'That folder no longer exists.' : (e.message || 'Could not list this directory.'));
     state.files.entries = [];
   }
@@ -939,7 +939,7 @@ function restoreFileFromHash(filePath) {
 // One dialog at a time lives in state.files.dialog: {kind, file, error, busy}.
 // Errors from the confined endpoints map to plain copy by HTTP status.
 function fileMutationCopy(e) {
-  if (e.status === 403) return 'Permission denied, or the target is outside the allowed roots.';
+  if (e.status === 403) return 'Permission denied, or the target is outside the accessible folders.';
   if (e.status === 404) return 'That file no longer exists.';
   if (e.status === 409) return e.message || 'A file with that name already exists.';
   if (e.status === 413) return 'Too large (50MB upload cap).';
@@ -1217,7 +1217,7 @@ function fileDialog() {
             : (!st.dir ? 'that path is not a directory' : null);
         } catch (e) {
           if (state.files.dialog !== d) return;
-          d.error = e.status === 403 ? 'outside the allowed roots'
+          d.error = e.status === 403 ? 'outside the accessible folders'
             : (e.status === 404 ? 'folder not found on the server' : null);
         }
         render();
@@ -1440,7 +1440,7 @@ function filesMain() {
   const rootsRow = roots.length > 1
     ? RootsPicker({
         roots: roots.map((r) => ({ id: r, label: truncate(projectLabel(r) || r, 16, 28) })),
-        selected: f.path, onSelect: (r) => loadDir(r), label: 'Jump to an allowed root',
+        selected: f.path, onSelect: (r) => loadDir(r), label: 'Jump to an accessible folder',
       })
     : null;
   const targetCwd = f.path || (roots.length === 1 ? roots[0] : '');
@@ -1478,11 +1478,12 @@ function filesMain() {
           // Detect directory drops: browsers report an empty FileList for dirs.
           // Check DataTransferItems when available; fall back to empty files list.
           const items = ev && ev.dataTransfer && ev.dataTransfer.items;
+          const FOLDER_DROP_MSG = 'folders cannot be dropped - use new folder to create one';
           if (items) {
             const hasDir = Array.from(items).some(it => { try { return it.webkitGetAsEntry && it.webkitGetAsEntry()?.isDirectory; } catch { return false; } });
-            if (hasDir) { announce('folders cannot be dropped - use new folder to create one'); return; }
+            if (hasDir) { announce(FOLDER_DROP_MSG); return; }
           } else if (!files || !files.length) {
-            announce('folders cannot be dropped - use new folder to create one'); return;
+            announce(FOLDER_DROP_MSG); return;
           }
           uploadFiles(files);
         },
@@ -1513,9 +1514,15 @@ function filesMain() {
       (f.uploads && f.uploads.length) ? h('div', { key: 'fup' }, UploadProgress({
         // Recovery affordances per row: 'replace' on a name collision (409),
         // dismiss on any error row (errors otherwise persist until the next batch).
-        items: f.uploads.map((it) => (it.error && it.status === 409 && !it._retrying)
-          ? { ...it, actions: [{ label: 'replace', onClick: () => retryUploadOverwrite(it) }] }
-          : it),
+        items: f.uploads.map((it) => {
+          // No chunk-level progress is available from fetch, so an in-flight
+          // row with no percent yet gets the marquee affordance instead of a
+          // static 0% fill that reads as stuck.
+          const base = (!it.error && !it.done && !it.pct) ? { ...it, indeterminate: true } : it;
+          return (base.error && base.status === 409 && !base._retrying)
+            ? { ...base, actions: [{ label: 'replace', onClick: () => retryUploadOverwrite(base) }] }
+            : base;
+        }),
         onDismiss: (item, i) => {
           const src = (state.files.uploads || [])[i];
           if (src && src.error) dismissUpload(src);
@@ -1583,10 +1590,10 @@ async function stopAllActive(sessions) {
   const okSids = sids.filter((sid, i) => results[i].status === 'fulfilled');
   const failed = sids.length - okSids.length;
   state.live.bulkStopError = failed
-    ? failed + ' session' + (failed === 1 ? '' : 's') + ' did not stop - try again'
+    ? failed + ' conversation' + (failed === 1 ? '' : 's') + ' did not stop - try again'
     : null;
   announce(failed
-    ? 'stopped ' + okSids.length + ' of ' + sids.length + ' sessions'
+    ? 'stopped ' + okSids.length + ' of ' + sids.length + ' conversations'
     : 'stopped ' + plural(okSids.length, 'conversation'));
   await refreshActive();
   render();
@@ -1758,12 +1765,12 @@ function liveMain() {
   return [
     offlineBanner(),
     lv.bulkStopError
-      ? Alert({ key: 'bulkstoperr', kind: 'warn', title: 'Some sessions did not stop',
+      ? Alert({ key: 'bulkstoperr', kind: 'warn', title: 'Some conversations did not stop',
           children: [
             h('span', { key: 'bsetxt' }, lv.bulkStopError + ' '),
             Btn({ key: 'bsedismiss', onClick: () => { state.live.bulkStopError = null; render(); }, children: 'dismiss' })] })
       : null,
-    PageHeader({ compact: true, dense: true, title: 'Live sessions', lede: 'Watch, open, and stop running agent sessions.' }),
+    PageHeader({ compact: true, dense: true, title: 'Live conversations', lede: 'Watch, open, and stop running agent conversations.' }),
     SessionDashboard({
       sessions,
       offline,
@@ -2158,7 +2165,7 @@ function chatMain() {
             if (!st || st.ok === false) { state.cwdError = 'directory not found on the server: ' + path; render(); return; }
             if (!st.dir) { state.cwdError = 'that path is not a directory'; render(); return; }
           } catch (e) {
-            state.cwdError = e.status === 403 ? 'outside the allowed roots'
+            state.cwdError = e.status === 403 ? 'outside the accessible folders'
               : (e.status === 404 ? 'directory not found on the server: ' + path
               : (e.status ? 'directory not found on the server: ' + path : 'could not validate the path - server unreachable'));
             render();
@@ -2607,7 +2614,7 @@ const debouncedCwdProbe = debounce(async () => {
       : (!st.dir ? 'that path is not a directory' : null);
   } catch (e) {
     if ((state.cwdDraft ?? '').trim() !== probed) return;
-    state.cwdError = e.status === 403 ? 'outside the allowed roots'
+    state.cwdError = e.status === 403 ? 'outside the accessible folders'
       : (e.status === 404 ? 'folder not found on the server' : null);
   }
   state.cwdChecking = false;
@@ -2687,7 +2694,9 @@ function historyMain() {
         h('p', { key: 'gs', class: 'history-empty-sub' },
           count
             ? count + ' conversation' + (count === 1 ? '' : 's') + ' available · use the search box or press / to filter'
-            : 'Start a chat or run a local coding agent - its conversation will appear here live.')),
+            : 'Start a chat or run a local coding agent - its conversation will appear here live.'),
+        count ? h('div', { key: 'gh', class: 'history-empty-hints' },
+          ShortcutList({ shortcuts: SHORTCUTS.slice(0, 4) })) : null),
     ].filter(Boolean);
   }
 
@@ -3221,7 +3230,7 @@ function serverPanel() {
       SessionMeta({ key: 'sfacts', items: facts }),
       roots.length
         ? SessionMeta({ key: 'sroots', items: roots.map((r, i) => ({ label: 'root ' + (i + 1), value: r, title: r, onCopy: () => copyText(r, 'root copied') })) })
-        : (hh.status && hh.status !== 'unknown' ? h('div', { key: 'snoroots', class: 't-meta' }, 'allowed roots: none configured') : null),
+        : (hh.status && hh.status !== 'unknown' ? h('div', { key: 'snoroots', class: 't-meta' }, 'accessible folders: none configured') : null),
     ],
   });
 }
@@ -3353,8 +3362,7 @@ function agentsPanel() {
       // The empty array means one of three things; never let an in-flight load
       // read as a broken registry.
       : [state.agentsLoading
-          ? h('div', { key: 'agload', class: 't-meta empty-state', role: 'status', 'aria-live': 'polite' },
-              Spinner({ key: 'spin', size: 'sm' }), 'loading agents…')
+          ? AgentListSkeleton({ rows: 5 })
           : (state.agentsError
               ? h('div', { key: 'agfail', class: 't-meta empty-state' },
                   h('span', { key: 'agfailtxt' }, 'the agent list failed to load'),
@@ -3609,6 +3617,8 @@ async function recheckHealth() {
 }
 
 async function init() {
+  state.health = { status: 'unknown' };
+  render();
   try {
     const r = await B.probeBackend(state.backend);
     state.health = r.ok ? { status: 'ok', ...r.info } : { status: 'down', ...r };