[codex] Polish responsive TUI experience

CONTEXT.md

@@ -52,22 +52,68 @@ _Avoid_: Installed skill, Skillpack-created skill
 The cross-provider view of discovered skills, their provenance, availability, and health.
 _Avoid_: Skill editor, authoring workspace
 
+**Provider Instance**:
+A discovered skill as represented by one Skill Provider, including that provider's availability and provenance for the skill.
+_Avoid_: Skill Group row, duplicate
+
+**Terminal Envelope**:
+The terminal size range the TUI deliberately designs and verifies for: a full baseline layout at 80x24, a compact usable layout down to 60x18, and a minimal too-small layout below that.
+_Avoid_: Responsive target, screen size
+
+**Terminal Compatibility**:
+The TUI's ability to remain understandable across terminals with different color, glyph, width, and resize behavior.
+_Avoid_: Pretty terminal rendering, theme support
+
+**Terminal UI Test**:
+A test that verifies the rendered Skillpack TUI state and keyboard-driven interaction from the user's terminal perspective.
+_Avoid_: CLI I/O Test, unit test
+
+**CLI I/O Test**:
+A test that verifies the Skillpack command process contract through standard input, standard output, signals, and terminal control sequences.
+_Avoid_: Terminal UI Test, component test
+
 **Scan Root**:
 A directory Skillpack inspects to discover provider, shared global, or project skills.
 _Avoid_: Skill, provider, install source
 
-**Health Signal**:
-A deterministic inventory finding that helps the user understand a skill's provider coverage, provenance, or loadability.
-_Avoid_: Security score, quality rating
+**Inventory Notice**:
+A non-problem inventory fact that helps the user understand provider coverage, provenance, or grouping confidence.
+_Avoid_: Warning, issue
+
+**Inventory Issue**:
+A deterministic inventory finding that means a Provider Instance likely needs attention or a user decision.
+_Avoid_: Notice, security score, quality rating
+
+Inventory Notices include update opportunities, unmanaged local provenance, and weak name-only relationships. Inventory Issues are reserved for findings that directly affect reliability or safe operation, such as invalid `SKILL.md` files, broken symlinks, and provider state that conflicts with the discovered filesystem state.
+
+**Update Opportunity**:
+A known newer version for a managed Global Skill. It is useful action context, not evidence that the current skill is broken.
+_Avoid_: Inventory Issue, stale skill warning
 
 **Skill Group**:
-The inventory row that collects provider-specific instances believed to represent the same skill.
+A relationship object that collects Provider Instances believed to represent the same skill.
 _Avoid_: Duplicate, provider row
 
+**Inventory Row**:
+The primary row in Skill Inventory. It should represent the object the user can inspect or act on directly.
+_Avoid_: Abstract grouping, hidden provider selection
+
+**Relationship-Aware Ordering**:
+An inventory ordering model where Provider Instance rows remain individually actionable but related instances are kept near each other when possible.
+_Avoid_: Provider partitioning, abstract group row
+
+**Related Providers**:
+The main-list hint that a Provider Instance has confirmed same-skill relationships in other providers. It should only be based on strong provenance evidence and should not include name-only matches.
+_Avoid_: Duplicate badge, weak match count
+
 **Skill Identity**:
 The evidence Skillpack uses to decide which provider-specific instances belong to the same Skill Group.
 _Avoid_: Display name, directory name
 
+**Name-Only Relationship**:
+A weak relationship between Provider Instances based only on normalized skill names, without path or source provenance confirming they are the same skill.
+_Avoid_: Confirmed relationship, duplicate
+
 **Disable Strategy**:
 The provider-specific mechanism Skillpack uses to make a skill unavailable to an agent.
 _Avoid_: Universal toggle, hidden directory rule

README.md

@@ -39,9 +39,9 @@ node packages/tui/dist/skillpack.js
 
 ## Quick Start
 
-Launch `skillpack` to see all discovered skills grouped by provider. Use `↑↓` arrow keys to navigate, `Tab` / `Shift+Tab` to switch between provider tabs (All, Codex, Claude, Global), and `/` to search.
+Launch `skillpack` to see discovered skills grouped into Skill Groups with provider status and Health Signals. Use `↑↓` arrow keys to navigate, `Tab` / `Shift+Tab` to filter by provider (All, Codex, Claude, Global), and `/` to search.
 
-Press `Space` to toggle a Codex or Claude provider instance on or off, `Enter` to view details, `p` to inspect read-only Project Skills, `s` to inspect Settings and Scan Roots, `i` to install a skills.sh Global Skill, or `u` to open manual updates. Plugin-owned skills require confirmation because the action toggles the owning plugin and affects sibling skills from the same plugin.
+Press `Enter` to inspect a Skill Group, then use left/right to choose a provider instance before taking instance-level actions. Press `p` to inspect read-only Project Skills, `s` to inspect Settings and Scan Roots, `i` to install a skills.sh Global Skill, or `u` to open manual updates. Plugin-owned skills require confirmation because the action toggles the owning plugin and affects sibling skills from the same plugin.
 
 ## Keyboard Shortcuts
 
@@ -50,8 +50,7 @@ Press `Space` to toggle a Codex or Claude provider instance on or off, `Enter` t
 | Key | Action | Description |
 |-----|--------|-------------|
 | `↑` / `↓` | Navigate | Move selection up / down |
-| `Space` | Toggle | Enable or disable a selected Codex or Claude skill; plugin-owned skills ask for confirmation |
-| `Enter` | Detail | Open skill detail view |
+| `Enter` | Detail | Open Skill Group detail view |
 | `Tab` / `Shift+Tab` | Switch tab | Cycle through All / Codex / Claude / Global |
 | `/` | Search | Fuzzy match on name + description |
 | `Esc` | Clear search | Clear the active search filter |
@@ -66,6 +65,7 @@ Press `Space` to toggle a Codex or Claude provider instance on or off, `Enter` t
 | Key | Action | Description |
 |-----|--------|-------------|
 | `Esc` | Back | Return to list view |
+| `←` / `→` | Provider instance | Switch the selected provider instance inside the Skill Group |
 | `Space` | Toggle | Enable or disable a Codex or Claude skill; plugin-owned skills ask for confirmation |
 | `o` / `O` | Open folder | Open skill directory in system file manager |
 | `d` | Delete | Remove a skills.sh-managed Global Skill with confirmation |
@@ -78,7 +78,7 @@ Skillpack stores its configuration at `~/.config/skillpack/config.json`. On firs
 ```json
 {
   "editor": "vi",
-  "autoCheckUpdates": true,
+  "autoCheckUpdates": false,
   "projectSkillsDirs": [
     ".codex/skills",
     ".claude/skills",
@@ -107,15 +107,12 @@ class MyProvider extends BaseProvider {
   readonly displayName = 'My Platform';
   readonly basePaths = ['/path/to/skills'];
   readonly capabilities: ProviderCapabilities = {
-    canInstall: true,
-    canUninstall: true,
-    canUpdate: false,
     canToggle: true,
-    canCreate: true,
   };
 
-  override async uninstall(name: string) { /* ... */ }
-  override async create(template) { /* return Skill */ }
+  override async scan() { /* return provider-native Skill instances */ }
+  override async setEnabled(skill, enabled) { /* update provider-native availability */ }
+  override getDisableStrategy(skill) { /* describe the availability mechanism */ }
 }
 ```
 

docs/adr/0012-group-inventory-by-skill.md

@@ -1,3 +1,7 @@
+---
+status: superseded by ADR-0036
+---
+
 # Group inventory by Skill
 
 Skillpack's primary inventory view will group provider-specific instances by normalized Skill identity rather than rendering each instance as a separate top-level row. This makes cross-provider coverage, duplication, provenance, and drift visible first, while detailed instance-level actions remain available inside the Skill Group detail view.

docs/adr/0014-limit-v1-health-signals-to-structural-provenance.md

@@ -1,3 +1,7 @@
+---
+status: superseded by ADR-0037
+---
+
 # Limit v1 Health Signals to structure and provenance
 
 Skillpack v1 will surface deterministic Health Signals: provider coverage, inferred versus confirmed Skill Identity, enabled or disabled state, missing or invalid `SKILL.md`, broken symlinks, available skills.sh updates, and unmanaged Global Skills. Security or risk scoring is out of scope for v1 because it requires a separate threat model and would be easy to overstate.

docs/adr/0018-defer-llm-advisory-guidance.md

@@ -1,3 +1,3 @@
 # Defer LLM advisory guidance
 
-Skillpack v1 will show deterministic inventory facts and Health Signals only, not LLM-generated best-practice recommendations. Advisory workflows such as overlap analysis, content quality review, and risk suggestions are deferred until the inventory model is stable enough for users to distinguish facts from recommendations.
+Skillpack v1 will show deterministic inventory facts, Inventory Issues, and Inventory Notices only, not LLM-generated best-practice recommendations. Advisory workflows such as overlap analysis, content quality review, and risk suggestions are deferred until the inventory model is stable enough for users to distinguish facts from recommendations.

docs/adr/0019-use-manual-update-checks.md

@@ -1,3 +1,3 @@
 # Use manual update checks
 
-Skillpack v1 will not check skills.sh updates automatically on startup. The TUI should load local inventory first and let users explicitly run update checks from the Updates section or a focused action, avoiding startup delays and network failures in the primary inventory experience.
+Skillpack v1 will not check skills.sh updates automatically on startup. The TUI should load local inventory first and let users explicitly run update checks from a focused action on a skills.sh-managed Global Skill, avoiding startup delays and network failures in the primary inventory experience. Provider rows that reference shared Global Skill content may show provenance, but update actions belong to the Global Skill row; the main inventory list should not expose a generic update shortcut.

docs/adr/0021-use-explain-before-action-detail-views.md

@@ -1,3 +1,3 @@
 # Use explain-before-action detail views
 
-Skillpack detail views will show summary, Skill Identity confidence, provider instances, paths and resolved paths, Disable Strategy, Health Signals, and skills.sh metadata before exposing valid actions. This keeps lifecycle operations grounded in visible provider-native state instead of blind toggles.
+Skillpack detail views will show summary, Skill Identity confidence, provider instances, paths and resolved paths, Disable Strategy, Inventory Issues, Inventory Notices, and skills.sh metadata before exposing valid actions. This keeps lifecycle operations grounded in visible provider-native state instead of blind toggles.

docs/adr/0023-support-responsive-terminal-envelope.md

@@ -0,0 +1,3 @@
+# Support responsive Terminal Envelope
+
+Skillpack will treat 80x24 as the full TUI baseline, support a compact usable layout down to 60x18, and show a minimal too-small layout below that. This keeps polish work grounded in explicit terminal constraints instead of chasing every possible terminal size with the same dense layout.

docs/adr/0024-prioritize-frequent-use-efficiency-in-the-tui.md

@@ -0,0 +1,3 @@
+# Prioritize frequent-use efficiency in the TUI
+
+Skillpack will optimize TUI polish for frequent-use efficiency while keeping enough inline state, empty states, and errors for first-time clarity. This means dense rows, compact shortcuts, and direct action feedback should take precedence over persistent tutorial-style explanatory copy in the main flow.

docs/adr/0025-preserve-core-skill-state-in-compact-layouts.md

@@ -0,0 +1,3 @@
+# Preserve core Skill state in compact layouts
+
+When the TUI enters compact layouts, Skillpack will preserve the selected Skill name, Skill Provider, Skill Availability, and Inventory Issue state before secondary metadata. Counts, long paths, descriptions, notices, and some shortcut labels may be shortened or hidden first so narrow terminals still answer what the user is focused on, where it applies, and what action is safe.

docs/adr/0026-centralize-responsive-tui-layout-rules.md

@@ -0,0 +1,3 @@
+# Centralize responsive TUI layout rules
+
+Skillpack will centralize shared responsive TUI rules in small layout primitives and hooks while letting each view decide its essential content. The current views repeat terminal row calculations and fixed column widths, so common handling for Terminal Envelope bands, truncation, reserved chrome, and shortcut overflow should keep responsive behavior consistent without making every view identical.

docs/adr/0027-keep-inventory-as-a-dense-list.md

@@ -0,0 +1,3 @@
+# Keep Inventory as a dense list
+
+Skillpack will keep the main Skill Inventory as a table-like dense list rather than a card-style layout. The list should become more forgiving through adaptive column widths, clearer selected state, compact badges, and better empty or error states, because card layouts would spend too much vertical space inside the compact Terminal Envelope.

docs/adr/0028-use-sectioned-detail-view-for-compact-terminals.md

@@ -0,0 +1,3 @@
+# Use sectioned Detail view for compact terminals
+
+Skillpack Detail views will keep summary and provider-native state visible first, then expose Paths, Source, Description, Findings, and Actions as sections when terminal space is constrained. Findings contain Inventory Issues and Inventory Notices without treating non-problem notices as warnings. At the full 80x24 Terminal Envelope baseline the view may read as one page when content fits, but compact layouts should prevent long paths or descriptions from crowding out Skill Availability and action state. The Description content itself should wrap into readable visual lines and scroll within its bounded region instead of truncating long prose to one ellipsized row.

docs/adr/0029-use-bounded-scrolling-in-all-content-views.md

@@ -0,0 +1,3 @@
+# Use bounded scrolling in all content views
+
+Every Skillpack content view that can exceed the viewport will use explicit bounded scrolling within the Terminal Envelope. Inventory, Project Skills, Settings, Updates results, Install results, and Detail sections should reserve stable space for headers and status bars, then scroll only their content region so compact terminals do not hide navigation or action state.

docs/adr/0030-use-adaptive-shortcuts-with-help-overlay.md

@@ -0,0 +1,3 @@
+# Use adaptive shortcuts with help overlay
+
+Skillpack will make the shortcut/status bar adaptive across the Terminal Envelope: full labels at baseline widths, reduced high-priority shortcuts in compact widths, and a `?` help overlay for the complete shortcut list. This avoids overflowing narrow terminals while keeping keyboard discovery available without persistent tutorial text.

docs/adr/0031-confirm-destructive-and-broad-actions.md

@@ -0,0 +1,3 @@
+# Confirm destructive and broad actions
+
+Skillpack will require clear confirmation for actions that delete content, update content, or toggle a Plugin-Owned Skill whose provider state affects sibling skills. Ordinary provider-native single-Skill availability toggles may remain one-keystroke actions, but they should produce transient success or error feedback so the user can verify the result without rescanning mentally.

docs/adr/0032-keep-direct-shortcuts-primary.md

@@ -0,0 +1,3 @@
+# Keep direct shortcuts primary
+
+Skillpack will keep direct keyboard shortcuts as the primary interaction model for the TUI polish pass. A full command palette is deferred until the responsive layout and contextual help model are stable, because adding another navigation model now would increase complexity without addressing the current Terminal Envelope problems.

docs/adr/0033-do-not-rely-on-color-or-glyphs-alone.md

@@ -0,0 +1,3 @@
+# Do not rely on color or glyphs alone
+
+Skillpack TUI state will remain understandable without relying on color or symbolic glyphs alone. Colors and tasteful glyphs may improve scanning, but important state such as enabled, disabled, warning, update available, and read-only should also have text labels or an ASCII-safe fallback to preserve Terminal Compatibility.

docs/adr/0034-defer-mouse-support-for-tui-polish.md

@@ -0,0 +1,3 @@
+# Defer mouse support for TUI polish
+
+Skillpack will not include mouse support in the current TUI polish pass. Keyboard behavior, bounded scrolling, action clarity, and Terminal Envelope responsiveness are the priority because they directly affect the existing TUI management workflow.

docs/adr/0035-verify-tui-layout-at-terminal-envelope-sizes.md

@@ -0,0 +1,3 @@
+# Verify TUI layout at Terminal Envelope sizes
+
+Responsive TUI changes will be verified at the Terminal Envelope sizes: 80x24, 60x18, and below-minimum dimensions. Tests should focus on shared layout helpers and representative view states for visible core state, bounded scrolling, stable reserved regions, and no obvious overflow, with manual terminal smoke checks before release rather than exhaustive snapshots of every row.

docs/adr/0036-use-provider-instance-rows-with-relationship-aware-ordering.md

@@ -0,0 +1,5 @@
+# Use Provider Instance rows with relationship-aware ordering
+
+Skillpack's primary inventory view will render Provider Instances as the actionable top-level rows, superseding ADR-0012's Skill Group row model. Skill Groups remain useful relationship objects for detail views and ordering, but the main list should not hide provider-specific availability, provenance, or actions behind an abstract group row.
+
+Provider Instance rows in the All view should use relationship-aware ordering: related instances are clustered near each other when possible, while provider tabs still filter to the provider-specific inventory. The main list may show a lightweight Related Providers hint for confirmed relationships only. Weak name-only relationships are detail-level context, not main-list grouping evidence.

docs/adr/0037-split-inventory-notices-from-inventory-issues.md

@@ -0,0 +1,5 @@
+# Split Inventory Notices from Inventory Issues
+
+Skillpack will replace the broad Health Signal bucket with Inventory Notices and Inventory Issues. Notices are non-problem context such as update opportunities, unmanaged local provenance, and weak name-only relationships; Issues are deterministic findings that directly affect safe operation or require attention, such as invalid `SKILL.md` files, broken symlinks, or provider state that conflicts with the filesystem.
+
+This split prevents the main inventory from warning on normal skill states while still making genuinely actionable problems visible without requiring the user to open every detail view.

docs/adr/0038-split-tui-ui-tests-from-cli-io-tests.md

@@ -0,0 +1,15 @@
+# Split TUI UI Tests from CLI I/O Tests
+
+Skillpack will test terminal UI behavior separately from the command process contract. Terminal UI Tests render an injectable application surface with Ink Testing Library and mocked Skillpack state so view routing, keyboard interaction, search, help, and terminal envelope behavior can be verified without scanning user directories; CLI I/O Tests exercise an injectable CLI runner that owns stdin, stdout, signals, alternate screen buffer control, and process exit, with only a thin process-level smoke test for the built binary.
+
+Snapshots are limited to stable golden frames such as the inventory, detail, help, and too-small terminal states after ANSI output and dynamic values are normalized. Interaction tests use semantic assertions instead of broad snapshots.
+
+The first Terminal UI Test suite will use shared inventory fixture builders and cover user-path behavior before mutation success paths: navigation, detail routing, search, help, terminal envelope states, and the entry or confirmation state for toggle, update, remove, and install flows. Real provider mutations and external commands remain outside Ink UI tests.
+
+Terminal UI Tests will share a harness that fixes terminal size, normalizes output, controls glyph mode, supplies Skillpack inventory fixtures, and provides a mock SkillManager with only the methods exercised by the views. Individual tests should not each invent stream setup, environment setup, or manager mocks.
+
+The first UI and CLI I/O suites prioritize deterministic serial execution over parallel speed. They must unmount Ink renders explicitly and avoid sharing mutable stream, environment, or process-exit state across tests.
+
+Tests isolate side effects by layer. Terminal UI Tests do not open system file managers, run external skill commands, or send real process signals; those paths use mocks or are deferred. CLI I/O Tests exercise terminal control, unmount, wait, and exit behavior through an injectable runner, with real signals limited to a spawned child process smoke test.
+
+This keeps user-facing Ink behavior testable without coupling it to provider scanning, while still protecting the terminal lifecycle guarantees that are easy to break around alternate screen buffer teardown.