AGENTS.md@packages/client/src/components/folder git:20261019.a95630fA

Immutable. This exact content never changes and is served at /api/v1/blob/30a05996c9118b28.

# DOX — packages/client/src/components/folder

Files in this directory. One row per source file. See change: fold-oversized-agents-directories.

| File | Purpose |
|------|---------|
| `CwdGonePill.tsx` | Red `folder missing` pill (`--tint-red-*`, 11 px) in the desktop session card TITLE row (after name, before time) when `session.cwdMissing`; git-independent. i18n `common.cwdGone`, testid `cwd-gone-pill`. See changes: add-worktree-lifecycle-actions, compact-session-card-header. |
| `DirectoryHomeView.tsx` | Directory home page for the bare `/folder/:encodedCwd` route. → see `DirectoryHomeView.tsx.AGENTS.md` Mounts `<YoloComposerStrip cwd/>` after `AgentSelect`, directly above `<CommandInput>`. See change: fix-yolo-indicator-overflow. |
| `folder-menu-labels.ts` | Pure label builders for the folder actions menu's directory group. `projectSetupLabel(status, base, updateBadge)` → `Project setup… n/N` tally (from the checklist) + localized `● update` badge (on `setupOutdated`); bare label when the checklist is absent. See change: add-folder-action-banner. |
| `FolderActionBanner.tsx` | Tier-0 full-width call-to-action banner for a directory card (replaces the deleted `FolderActionBar`). One banner max by a fixed severity ladder `failure > running > retrust > init-needed > setup`; test id `folder-banner-{setup,init-needed,retrust,failed,running}-<cwd>`, setup action `folder-banner-setup-action-<cwd>`. Setup rung ("Not a pi project yet", info, `mdiTextBoxCheckOutline`) gates on the REQUIRED `.pi/settings.json` checklist entry AND on `isProjectRoot` (pinned/workspace/positive-git). Setup action calls `onInitializeProject(cwd)` directly; no spawn tracking — the row's `useInitStatus` re-probes on session idle/ended + tab-visible, so the banner clears however setup was launched and survives remounts; `sessions` prop removed. `setupState` moved to `lib/init-setup-state.ts` (re-exported here). See change: fix-project-setup-completion-state. Hook rungs re-host `WorktreeInitButton` (chip/trust dialog). Colours ONLY from `--severity-{info,warning,error}-{bg,fg,border}`. Exports `FolderActionBanner`, `computeBannerRung`, `setupState`, `BannerRung`. Fail-open: absent/uninterpretable checklist → no banner; checklist wins over the deprecated `configured` boolean. See change: add-folder-action-banner. `compact` prop renders the rung as a one-line warning chip (`folder-banner-chip-<cwd>`) that reveals the full banner on activation; the accordion/`folder-banner` path trades vertical space for a disclosure. See change: add-focus-mode-and-card-block-toggles. |
| `FolderActionsMenu.tsx` | The folder header's single trailing control. `mdiFolderCogOutline` trigger (`folder-actions-menu-<cwd>`, `aria-haspopup=menu`, `aria-expanded`, `stopPropagation`) → grouped popover / mobile sheet (`folder-actions-menu-panel-<cwd>`, `role=menu`, `data-menu-form=sheet|popover`). Exports `FolderActionsMenu`, `FolderMenuItem`; RE-exports `FOLDER_MENU_GROUPS`/`FolderMenuGroup` from `dashboard-plugin-runtime/folder-menu-contributions` (one taxonomy for host + plugins). Host-owned group order `workspace → directory → create → open → maintenance`; a group renders only when non-empty (`folder-menu-group-<group>`). Merges caller `items` (host, keep declared order) with `useFolderMenuItems(cwd)` contributions — read HERE, so an OPEN menu converges on a late-mounting section. `FolderMenuItem` gains `badge?` (renders `folder-menu-badge-<id>`, part of the accessible name) + `disabled?` (`aria-disabled`, stays focusable per APG, callback never fires, menu stays open); `onSelect` wrapped in try/catch so a plugin throw cannot take the sidebar down. See change: move-slot-actions-to-menu. Items `role=menuitem` + `folder-menu-item-<id>`; `FolderMenuItem.node` lets an item render its own node (add-to-workspace keeps `add-to-workspace-btn-<cwd>` + its popover). Caller owns `open` — `SessionList` keys it by SCOPE `folder:<cwd>`. ArrowDown/Up rove `[role=menuitem]`; Escape closes + refocuses trigger; outside mousedown/touchstart closes. Sheet gates on `useMobile()` (compound `<768w OR <600h`, reused verbatim) via `DialogPortal`; desktop PORTALS via `LayerPortal` + a `fixed` panel positioned from `usePopoverFlip`'s `triggerRect`/`flipUp`/`anchorRight`. BOTH forms carry the `z-popover` layer token (never inline `absolute z-50`) — portaling escapes each `SessionCard`'s `isolate` stacking context, the fix for the folder-menu UNDERLAP (z-index/layering/stacking-context). `mdiDotsHorizontal` REJECTED — `WorktreeActionsMenu` already renders it inside the folder body. See change: add-folder-actions-menu. See change: add-overlay-layering-system (spec overlay-layering). Optional `radioGroup: FolderMenuRadioGroup` rendered FIRST as `role=menuitemradio` (`folder-menu-radio-<id>`, aria-checked); focus on checked item at open (re-run after first measure); ArrowUp/Down rove radios + menuitems; select → close + focus trigger. See change: session-list-group-by. `FolderMenuItem.tone`; rows apply tone icon/row classes + `data-action-tone`; badge uses `--accent-orange-text`. See change: colorize-actions-menus. |
| `FolderEditorView.tsx` | Folder-scoped internal Monaco pane. Wraps `FolderSplitProvider` (`SplitWorkspaceProvider` keyed by `folderPaneId(cwd)`), renders… → see `FolderEditorView.tsx.AGENTS.md` |
| `FolderHomeContainer.tsx` | Data shell for the folder home. Calls `useFolderCommands(cwd)` + `useModelCatalogue({seedFromCache})`, renders `DirectoryHomeView` with `commands`/`commandsOrigin`/`models`. Exports `FolderHomeContainer`, `FolderHomeContainerProps`. Per-cwd hooks live here so a frozen overlay underlay gets its own data. `React.lazy` from `App.tsx` (own chunk, keeps the index gzip under the `mdi-chunk-size` cap). See change: redesign-directory-home-split. |
| `FolderSpawnButtons.tsx` | Stacked spawn buttons in folder header: `+ New Session` (green, always) + `+ New Worktree` (orange, gated by `showWorktree`). Min-height 44px on mobile. Exports `FolderSpawnButtons`. See change: align-ui-with-theme-tokens: palette → `--tint-green-*` / `--tint-orange-*` (tint fg on its own tint bg). Tint/target recipe via `tint-action-*` / `tap-target` utilities (index chunk cap). |
| `FolderSplitProvider.tsx` | `SplitWorkspaceProvider` keyed `folderPaneId(cwd)` + terminal wiring, `defaultMode="split"` (first visit opens Split). Shared by `FolderEditorView` + directory home. Exports `FolderSplitProvider`, `FolderSplitProviderProps`. See change: redesign-directory-home-split. |
| `FolderStatusCapsule.tsx` | The folder header's ONE liveness surface, in BOTH collapse states. Exports `FolderStatusCapsule`. Replaces the raw `(N)` count + `FolderNeedsYouPill` + `FolderStatusRollup`. Segments render in fixed severity order `CAPSULE_SEGMENT_ORDER` (needs-you > error > working > idle); zero counts absent; no countable sessions → no capsule. Non-idle segments are `<button>`s navigating to `firstIds[bucket]`; idle is an inert `<span>` (not a disabled button) that still carries an aria-label. Test ids `folder-status-capsule-<cwd>` + `folder-capsule-seg-{needs-you,error,working,idle}-<cwd>`, plus `data-capsule-segment` for order assertions. Counts cap at `999+`. Owns the per-candidate `WidgetBarProbe` (absent/undefined = unclassified = excluded, so needs-you never flashes high). Colors from `--status-*` only, never `--severity-*`. `flex-none` + `whitespace-nowrap` — sheds nothing; the folder name absorbs width pressure. Activation calls `stopPropagation()` then routes through `SessionList`'s existing reveal path (`onSeekToCard`), which owns guarded expand, layout-settled scroll and the hidden/filtered degrade notices. See change: unify-folder-status-capsule. `WidgetBarProbe` now exported (reused by SessionList lane classifier). See change: session-list-group-by. |
| `starter-cards.ts` | Pure starter helpers. `buildStarters(commands)` → ≤6 cards: folder-scope skills → prompts → global skills; builtin/extension never. `withStarterInserted(draft, name)` puts `/<name> ` at draft start, replacing a leading slash token; never sends. Exports `buildStarters`, `withStarterInserted`, `Starter`. See change: redesign-directory-home-split. |