129 lines
6.2 KiB
Markdown
129 lines
6.2 KiB
Markdown
---
|
|
spec: docs/specs/agents/requirements/settings-profile-layout.md
|
|
created: 2026-08-13
|
|
status: building
|
|
---
|
|
|
|
# Implementation Plan: Simplify the agent settings profile layout
|
|
|
|
## Overview
|
|
|
|
Move profile creation into each installed-agent card header and remove the
|
|
redundant profile-count/action row from the card body. Reorder the existing
|
|
installed-agent toolbar so refresh/rescan is immediately before the rightmost
|
|
agent-creation action. Preserve the current profile rows and agent-level
|
|
controls, then prove the layout and navigation on desktop and mobile.
|
|
|
|
The change is frontend-only. No API, store, persistence, or locale contract is
|
|
needed because the existing translated labels and routes are reused.
|
|
|
|
## Frontend
|
|
|
|
### Agent profile sub-list
|
|
|
|
- `apps/web/components/settings/agents/agent-profiles-section.tsx`
|
|
- Remove the profile-count/empty-state header row and its creation link.
|
|
- Keep the existing profile rows and their actions in the card body.
|
|
- Avoid rendering an empty profile body when no saved profiles exist; the
|
|
card header supplies the setup action.
|
|
|
|
### Installed-agent card
|
|
|
|
- `apps/web/components/settings/installed-agent-card.tsx`
|
|
- Add the existing `New profile` link to the configured agent's header,
|
|
alongside agent-level controls, using the existing `?mode=create` route.
|
|
- Keep `Setup profile` as the only header creation action for an agent with
|
|
no saved record.
|
|
- Preserve touch-sized header actions on mobile and the existing status,
|
|
authentication, and runtime-update controls.
|
|
|
|
### Installed-agent toolbar
|
|
|
|
- `apps/web/app/settings/agents/page.tsx`
|
|
- Reorder the current header controls so the refresh/rescan button is
|
|
immediately before the existing Add TUI Agent action and the latter is
|
|
rightmost.
|
|
- Add stable test IDs for the toolbar and the two ordered controls if the
|
|
existing markup does not provide a reliable scoped selector.
|
|
- Keep the terminal action available and keep the current agent-creation
|
|
behavior and label.
|
|
|
|
## Tests
|
|
|
|
- **What:** A configured agent shows profile creation in the card header,
|
|
profile rows have no count/action sub-header, and an unconfigured agent has
|
|
only its setup action.
|
|
**File:** `apps/web/components/settings/agents/agent-profiles-section.test.tsx`
|
|
and `apps/web/components/settings/installed-agent-card.test.tsx`.
|
|
**How:** React Testing Library assertions against the rendered card/list,
|
|
including the creation link target and absence of count/empty-state copy.
|
|
- **What:** Existing profile-row duplicate/delete behavior remains intact.
|
|
**File:** `apps/web/components/settings/agents/agent-profiles-section.test.tsx`
|
|
**How:** Keep and rerun the current store read-after-write tests.
|
|
- **What:** The installed-agent toolbar keeps terminal available and orders
|
|
refresh/rescan directly before the rightmost agent-creation action.
|
|
**File:** `apps/web/e2e/tests/settings/agent-profile-layout.spec.ts`
|
|
**How:** Navigate through the real settings page, scope the toolbar by its
|
|
test ID, assert the ordered controls, and verify the configured card's
|
|
**New profile** link route.
|
|
|
|
## E2E Tests
|
|
|
|
- **Scenario:** GIVEN a configured agent with one or more profiles, WHEN the
|
|
user opens `/settings/agents`, THEN the card header contains **New profile**,
|
|
profile rows are directly below it, and no profile-count/action row exists.
|
|
**File:** `apps/web/e2e/tests/settings/agent-profile-layout.spec.ts`.
|
|
- **Scenario:** GIVEN a phone viewport below 768px, WHEN the user opens the
|
|
agents settings page, THEN the same creation action and ordered toolbar are
|
|
touch-reachable and the document has no horizontal overflow.
|
|
**File:** `apps/web/e2e/tests/settings/mobile-agent-profile-layout.spec.ts`.
|
|
**What to verify:** Use the configured `mobile-chrome` project, assert the
|
|
header action hitbox is at least 44px, use `.tap()` for the creation action,
|
|
and assert the settings document remains contained.
|
|
|
|
## Mobile design contract
|
|
|
|
- Desktop outcome: manage an agent's saved profiles and create another profile
|
|
from the same agent card.
|
|
- Mobile entry point: the installed-agent card on `/settings/agents`; no new
|
|
drawer, route, or mobile-only control is needed because the action is a
|
|
direct link and the existing settings scroll container remains the sole
|
|
vertical scroll owner.
|
|
- Nearest shipped exemplar: the managed runtime update controls on the same
|
|
agent card, whose mobile E2E coverage verifies 44px controls and no document
|
|
overflow. Reuse its touch-sized action treatment and existing card geometry.
|
|
- Mobile hierarchy: agent identity/status first, creation and agent-level
|
|
controls in the header, then profile rows in one vertical list.
|
|
- Presentation: inline card-header action; no drawer is justified because
|
|
profile creation is a direct destination rather than a temporary choice.
|
|
- Shared state and logic: reuse the existing agent/profile store data and route
|
|
handlers; only the placement and responsive classes change.
|
|
|
|
## Verification Results
|
|
|
|
Passed.
|
|
|
|
- Component regression coverage passed: `cd apps/web && pnpm test -- components/settings/agents/agent-profiles-section.test.tsx components/settings/installed-agent-card.test.tsx` (8 tests).
|
|
- Static checks passed: `cd apps/web && pnpm run typecheck`, the focused ESLint command from task 01, and `cd apps/web && pnpm run i18n:check` (with the repository's existing advisory catalog warnings).
|
|
- Desktop managed E2E passed: `cd apps/web && pnpm e2e:run --project chromium tests/settings/agent-profile-layout.spec.ts` (2 tests).
|
|
- Mobile managed E2E passed: `cd apps/web && pnpm e2e:run --project mobile-chrome tests/settings/mobile-agent-profile-layout.spec.ts` (1 test).
|
|
- Review follow-up coverage passed for both setup routes, the saved-empty profile body guard, and the toolbar ordering invariant.
|
|
|
|
## Implementation Waves And Parallel Candidates
|
|
|
|
Wave 1:
|
|
|
|
- [x] [task-01-agent-settings-layout](task-01-agent-settings-layout.md)
|
|
|
|
Wave 2:
|
|
|
|
- [x] [task-02-agent-settings-e2e](task-02-agent-settings-e2e.md)
|
|
|
|
The tasks are sequential because the E2E selectors and layout assertions
|
|
depend on the component markup from task 01.
|
|
|
|
## Open Questions
|
|
|
|
- None. The existing **Add TUI Agent** control is treated as the requested
|
|
agent-creation action; its semantics and translated label remain unchanged.
|