AI Manager experience alignment¶

Status: Current | Last reviewed: 2026-10-12

This implements the recommended path from the prototype experience audit in apps/ai-manager and the independent studio/design/apps/ai-manager export. The root index.html supplies the initial visual reference. Lynn's subsequent designer changes take visual precedence while the application retains working configuration, navigation, persistence and runtime behavior.

Implemented experience¶

Surface	Change	Capability retained
Typography	The exact reference Open Sans v44 files are bundled locally. Home uses a 32px heading; browse headings use a 26px desktop maximum, editor identity 17px bold, inspector identity the shared semibold label size, and repository card titles 16px bold.	Existing editor document formatting and inline prompt tokens.
Navigation	Tools & Templates and Configuration use full labels. Design with AI uses the reference lightning glyph; Notifications uses the matching outline bell. Collapsed navigation is a 64px icon-only rail with 40px buttons and 18px icons.	Existing routes, permissions, unread badges, hover/focus tooltips and full mobile labels.
Home	Activity stays at 24 hours; Conversations has 24h/30d/90d/12mo ranges; remove Import, promotion, recents and Manage Favorites; exact reference icons, stat tiles, activity rows linking to the corresponding agent/workflow editor, portfolio and grouped favorite cards.	Real permission-filtered inventory/activity, duration data, creation menu, search, favorites and responsive navigation.
Repository header	Shared white brand/notification header with Import/New agent; Agents title sits below the band.	Mobile navigation, both import formats and all creation paths.
Search and filters	Reference 52px search field and placeholder, personal-filter pills, checkbox panel with one Type group (Voice Agent, Chat Agent, Copilot, Translation Agent, Background Agent, Multi-Agent), and sorting inside Filters. No result count, type tabs or list/grid switch.	Status/date/ownership/favorite/recent filters, background agents, loading/retry/empty states and 20-result pagination.
Repository cards	Reference palettes, glyphs and 48px bands with simple type headings (such as Voice Agent), no duplicate type pills, single-line agent names, and unshaded footer with status/version/date on the left and the favorite heart alone on the right. Published agents with a draft show amber Unpublished Changes.	Manage actions, real publication/version/date data, searchable/editable tags and saved favorites.
Canvas header	Show the agent icon, friendly agent type, subagent count and version subtitle and status pill; keep Agent Canvas centered in the toolbar, bounded by identity/actions. Opening, closing or resizing Node Configuration and Preview does not move the heading.	Draft/published distinction, presence, autosave status, validation and publish/open-draft actions.
Secondary actions	More contains Export and Delete agent; Settings, Activity and Test stay visible. Version selection stays in the canvas header; Activity → Change History spans drafts and published versions with per-entry version labels. Editable draft names support inline rename.	Version navigation, actual performance/export handlers and delete confirmation.
Preview	Small vertical edge tab; no toolbar shortcut or full-height collapsed rail.	Phone, chat, translation and copilot testing, configuration gates and full-screen preview.
Notifications	One header bell for editor validation, readiness, page actions, save failures and Preview connection errors.	Real blocker reasons, live counts, automatic resolution and dismissible action messages.
Activity	Centered modal with Change History and Conversation History underline tabs; no repeated tab titles.	Existing audit API, expandable changes, paginated conversations, transcript/recording viewer and return to the same list page.
Canvas/node detail	Full-width canvas, theme-aware dot grid, accent borders, two-line node headings, read-only behavior counts and a zoom strip with percentage and Fit view.	Existing automatic graph layout, stage/pencil configuration access, undo/redo, zoom and minimap.
Canvas View	Compact control with Structural, Mini Map directly below it, and Sub-Agents when applicable; remove the canvas Variables list.	Browser-local preferences and keyboard undo/redo; inline prompt variables and runtime configuration keep their meaning.
Inspector	Stronger stage identity/description; Behavior first, Properties second; a closed inspector leaves no rail; clicking empty canvas closes it.	A node selection reopens it; incomplete stages still default to required Properties and unsupported Behavior tabs stay absent.
Expanded workspace	Persistent collapsible library beside the active instruction editor; hide it on Properties.	Main/smart-subagent prompts, greeting, capabilities, tools, variables, logic, guided steps and Copy full prompt.
Settings	Reference labels and white underline tabs: Identity & Branding, Conversation Controls, Media & Recording, Routing Rules, Compliance & Security; additional Connections/Cost Estimates where applicable. Variants is hidden from Routing Rules.	Conditional provider/channel rules, independently saved operations, stored runtime profiles and publish-time materialization.
Settings feedback	Explain automatic draft saving; Done closes; published configuration is disabled.	Agent-level permissions on connections and operations remain separate from draft configuration.
Cost failure	Show an inline error and retain Refresh when the service fails or returns an incomplete estimate.	Existing live cost calculation and assumption-saving APIs.

Deliberate model decisions¶

Agent identity labels come from lib/agent-labels.ts: Voice Agent, Chat Agent, Copilot, Translation Agent, Background Agent and Multi-Agent. Editor headers, repository cards/rows, favorites, management tables and templates share these labels. Subtype takes precedence over transport (so a translation agent stays a Translation Agent); incomplete records fall back to a friendly transport mapping or Agent, never an internal slug. Configured subagents produce Multi-Agent and a separate count, using the shared stage walker for flat, parallel and swimlane pipelines. Repository search also matches the base type, and the Multi-Agent filter can be combined with base-type filters. Management tables have one Type column instead of separate transport and subtype columns. Runtime type values, creation options and A2A eligibility remain unchanged.

Repository status filters are fixed to Published, Draft and Unpublished Changes. repositoryItems derives publication only from version_status; a missing published version is Draft, including older active/inactive workflows. repositoryPublicationStatus adds Unpublished Changes when a published entry has has_draft. Generation jobs and template identity no longer override publication. Published filtering still includes entries with unpublished changes. Legacy status=Pending Changes selects Unpublished Changes, and status=Has draft selects Draft plus Unpublished Changes; unsupported status bookmarks clear the status selection. Home excludes templates via source.is_template, and its published counts use publication data rather than activation or job state.

The reference's independent-agent nested canvas is not the shipped subagent model. Nodes continue to represent pipeline stages. Their behavior summaries are read-only counts; selecting a stage or its pencil opens the existing inspector, where prompt scopes, smart/guided subagents, shared tools, variables and handoff behavior retain their existing meaning. No new saved-agent link or runtime graph schema is introduced.

The reference's Settings Save button only closes its modal. The implemented settings retain real automatic draft saving, make it visible in the footer, and preserve explicit saves for operations, connections and cost assumptions. There is no new Cancel action that falsely implies an already saved edit can be discarded.

Activity uses the existing data components in a modal presentation. Conversations request seven records using the existing search cursor API, scoped to the base agent across versions. The list stays mounted while a transcript is open, so Back restores its cursor and keyboard focus. Change History retains its 20-record pagination and existing diff expansion. Other full-page consumers retain their filters and cards.

Notifications come from page validation/readiness state and scoped sources in Preview and autosave. Blocking conditions remain enforced by the existing publish/test handlers. Messages are deduplicated, sorted by severity and reset when the selected agent/version changes. Active conditions cannot be dismissed; transient action feedback can. Form-specific errors with local retry controls remain within their dialogs.

Prompt library contract¶

PromptLibraryWorkspace uses the existing tenant-scoped GET /api/prompt-templates response { templates: PromptTemplate[] } and prompt-templates:all client cache. It provides loading, empty, search-empty, failure/retry and read-only states. Requests do not require a new backend API.

Only a PromptTemplateEditor explicitly marked libraryTarget registers an insertion callback. In PromptSection, this is the active main prompt or smart subagent instruction field. Greeting editors and generated prompt previews never register. Insertion calls the existing CodeMirror insertAtCursor API: it inserts at the current selection, falling back to the document end before the editor has been focused.

The insertion is copied text, not a stored link to a template. References remain in that text, but template defaults and bindings are not imported. Authors use the existing Variables panel to configure required values and sources. No editor selection, library filter or visibility state is persisted into agent configuration.

Prototype fixes and limits¶

No new service or database migration is required. Home adds nullable timing fields to its existing production response, using existing timestamps; see the Home contract. Both copies include these prototype-only corrections:

Cost estimate and assumption requests return explicit 503 responses in the offline export. The shared UI explains that a connected cost service is required. It does not show invented pricing or accept an empty success body.
The mock collaboration writer updates entity name/description in detail and repository responses as the real PATCH /api/auth/collab-config does. It also resolves an existing :draft overlay when no redirect metadata is present.
An omitted explicit :vN fixture can use the exact matching published base capture. It reads the original captured snapshot, never the mutable draft overlay. Other uncaptured versions return 404. Created/published mock version snapshots continue to use their explicit stored records.
Offline Home supplies nine explicitly synthetic recent entries with duration and running/failed states. Favorite add/remove/filter operations persist in the browser store, so Quick Access is functional in the export.
Offline Activity supplies 15 synthetic conversations and 24 sample changes for an existing selected agent. Cursor/page requests, transcript lookup and expanded change details use the production response shapes. Sample callers, designers and source labels identify the data as synthetic; no recordings or production activity are fabricated in the connected application.

Prototype saves use browser storage and the local Yjs loopback. They do not prove database persistence, service connectivity, phone-call success or cost calculation in a deployed environment.

Maintaining both repositories¶

Shared components, styling, supporting helpers, mocks and the regression suite were applied as focused changes after checking the design baseline. The editor page differs between repositories: production has newer performance/preview features. Each page receives the same small preview-prop and canvas-container patch instead of replacing either entire file.

The design repository retains its own package configuration, startup commands, mock boundary and history. Changes are local working-tree changes in both repositories; committing/publishing the independent design repository and updating the parent gitlink remain normal release steps.

Verification¶

The designer import passes 37 unique browser checks against the application source in prototype mode, covering the editor, Home, repository and service forms. The version submenu has both mouse and keyboard coverage. The 45 focused canvas, lane, accent, repository, auxiliary-editor and integration-default unit checks pass, as does npm run typecheck; scoped lint reports no errors and 25 warnings. The status-pill fixture reflects the designer's 4.8px internal gap. This UI import changes no production API or generated schema.

The regression suite is apps/ai-manager/prototype/e2e/editor-experience.spec.ts. Run it against an already-running prototype instance:

E2E_BASE_URL=http://127.0.0.1:3107 npm run test:prototype -- editor-experience.spec.ts
npm run typecheck

The suite first verifies the PROTOTYPE badge before editing any fixture. It covers repository controls, keyboard menus, delete cancellation, Preview, Canvas View, insertion at the instruction cursor, unchanged greetings, save/reload, published snapshot preservation, library retry, settings navigation/persistence, published read-only controls and mobile sizing.

Validated in both repositories on 2026-09-23: typecheck and scoped ESLint pass; all 7 browser tests pass in each app; the final keyboard/mobile follow-up passes in each app. The 27 existing pipeline-shape and empty-room checks also pass. At 1440 × 1000 the first repository row is at approximately y=301 (previously approximately y=509). At 390 × 844 neither the repository nor expanded editor introduces horizontal page overflow. Twenty shared files match byte-for-byte; the editor pages retain their baseline differences with the same focused patch. No production API/spec source changed, so no OpenAPI regeneration was required.

Desktop review captures and verification output are in artifacts/ai-manager-ui-implementation-2026-09-23/. Live backend and deployment checks are outside this local UI validation.

Settings correction and designer branch follow-up¶

The settings correction matches the root reference's 14px semibold tab labels, transparent row/selected backgrounds, no raised shadow and 2px teal underline. Privacy redaction moves to Compliance & Security, traffic/fallback to Routing Rules, and costing to Cost Estimates. Availability follows actual configuration; new mock-only retention, queue or audit fields are not added. Both source copies share the settings implementation and preserve existing save/version behavior.

The application imports the reviewed feature/lynn-wip delta from design main a5501eb through 9ad4d91. The import retains Lynn's header/menu placement, canvas controls, inspector rail, node/edge styling and lane palette. The toolbar-based heading calculation remains to prevent the title moving when the inspector opens. The prototype comment overlay is already absent in the app. The version selector uses a submenu within More so its choices remain reachable with arrow keys and Enter; the standalone selector retains its own dropdown. The imported design change log retains the designer's handoff notes. Prototype recents handlers and reset-badge styling stay within prototype mode; production APIs and startup configuration are unchanged.

The follow-up visual review contains the corrected settings in both copies, light/dark/mobile views and verification results. The original implementation screenshots above remain the record of the earlier alignment pass.

Compact panels, notifications and Activity follow-up¶

The requested follow-up is implemented in both copies. The closed Preview tab measures 28 × 93px; Activity measures 1056 × 736px at a 1440px desktop viewport. On a 390px phone it stays within the viewport, with Back and pagination visible. The full-screen Preview header hosts the bell while it covers the main header. Switching Activity tabs unmounts the transcript player so recordings do not keep playing behind Change History; list pagination and selection are preserved.

Verification: 15 unique browser checks pass for the real app source in prototype mode and 18 for the design export, including the three Lynn feedback checks. One DOM-order assertion was corrected and passed on its focused rerun. Final transcript and full-screen notification changes also passed focused checks. Both typechecks and scoped lint pass (41 existing lint warnings each); all 11 canvas-history unit tests pass in each copy. Twenty desktop/mobile/dark captures show no browser exceptions or horizontal page overflow. No deployment, remote push, production API mutation or live recording/call validation was performed.

See the itemized follow-up and visual comparison and verification manifest.

Home reference follow-up — 2026-09-23¶

components/studio/ReferenceIcons.tsx copies the master SVG paths and stroke geometry. app/studio-home.css contains the Home-only palette, spacing and type rules; sidebar rules remain in studio.css. Open Sans loads the master's 300/400/600/700 weights, including italic faces. This matters for 500-weight labels: the master selects its 400 face, whereas the previous variable font rendered a heavier 500 face.

Home omits the static reference's nonfunctional New Workflow button; the existing New Agent menu provides all five creation types, including Background agent. Real inventory, names, favorites and warning counts replace the reference's sample values. No conversation growth percentage or stale-agent warning is invented. Favorite cards render every saved favorite in the two reference groups. The sidebar preserves available routes and permissions, using the reference icons for the corresponding built-in destinations.

prototype/e2e/home-reference.spec.ts compares 664 computed properties across 50 visible elements against measurements captured from the master HTML. Its fixture also records all 17 copied SVG definitions. SVG checks compare geometry, stroke width/caps/joins, displayed size and contextual color. The fixture excludes invisible inherited border colors and text properties on textless containers; transparent zero-size Tailwind shadow placeholders are normalized. Dynamic text, counts and resulting card heights are not pixel-equality assertions.

The Home follow-up passes 15 browser checks per copy (seven Home and eight editor) and four duration unit checks per copy. Both typechecks and scoped lint pass. Mobile drawer typography and hover states have additional assertions. A transient Retry test race was fixed by keeping the injected failure active until the click. The connected local API returned 200 and 50 records with numeric-or-null durations and end timestamps. An initial 401 was a test hostname mismatch, resolved in the transient test context without changing the stored session. The visual report is artifacts/home-reference-followup-2026-09-23/report.html.

Insights deferred — 2026-09-23¶

Insights is removed from the sidebar, secondary links and the current screen experience in both apps. Old /dashboard/insights bookmarks return to Home. Its reporting composition is retained as an unmounted component, with protected analytics APIs unchanged. See the future-review note. This supersedes earlier references to Insights as an available screen.

Service Properties and auxiliary editors¶

Properties suppresses service-field helper descriptions while retaining selectors, voice previews, validation, and conditional operational warnings. Background Audio volume displays 0–100% and stores the existing 0–1 value. Service fields grouped as turn_detection are excluded from Properties Advanced and shown within Behavior's Turn Control capability; Nova Sonic endpointing uses its existing config key without migration. Auxiliary editors reuse the ordinary service form with a fixed type, no identity/capability controls, and a div wrapper inside the parent form. Runtime-backed defaults and prompt overrides are documented in scripted subagents.

Voice authoring follow-up — 2026-09-25¶

Input and Output use neutral card surfaces and borders; lane dots still identify frame types. Settings displays the stable agent ID without the version suffix. The shared friendly agent type helper also ships in the standalone design export.

Definition-driven language controls display friendly names while preserving provider codes and declared options. String parameters with options render as selectors. Scribe Realtime defaults to scribe_v2_realtime; keyterms use removable string-array chips rather than a JSON textarea. Audio sample-rate controls are hidden without removing stored schema fields: Pipecat's Polly adapter synthesizes 16 kHz PCM and resamples to the service/pipeline rate, while channel configuration drives routing.

Integration selection remains tenant/source/capability scoped. Migration 067_provider_voice_capabilities.sql upgrades only the exact historical default capability sets from migration 019: AWS gains TTS; OpenAI and ElevenLabs gain STT. Order does not matter and repeat execution changes nothing. Connect-only, empty and explicitly restricted sets are preserved. No DDL changes are involved; the migration is registered in the city forward-migration list. Three affected profiles in the Vanguard agent 3032 tenant were repaired and checked through the live API.

The prototype's voice-authoring.ts MSW handler provides capability-filtered profiles, auxiliary-default simulation, a small Polly catalog and local recorded Polly samples. Production still resolves auxiliary settings in Python. Prototype recordings demonstrate playback; changing engine or region does not regenerate these recordings. Published configuration remains read-only. Browser coverage is in prototype/e2e/service-properties.spec.ts and editor-chrome.spec.ts.

Polly previews share the other providers' default sentence: “The sky is the limit when the business reaches for the stars.” The manager forwards TTS_PREVIEW_PHRASE to the orchestrator so a manager-level override applies consistently. The internal handler falls back to that same default; prototype recordings use the standard sentence.

September 28 Lynn branch integration¶

Design main and feature/lynn-wip share the reconciled UI. September 25 friendly labels, neutral Input/Output cards, auxiliary voice controls and publication semantics remain intact. Lynn's shared header, compact controls, inline rename, Test label and spinner are imported into the application. The Enterprise brand badge remains fixed presentation text, not a tenant entitlement claim.

GET /api/dashboard/conversation-count?range=24h|30d|90d|12mo requires AIManager:ManageAgents and enabled agent authoring. It defaults to 30d, rejects unknown ranges with 400, and counts the current tenant's conversations (including tests) using parameterized intervals and tenant context. Its window is independent of the Home activity feed. Conversation links carry the range into search, including test calls and the rolling start timestamp. Prototype counts remain synthetic samples. This endpoint is internal UI API, not a management-token scope expansion. The page-header notification bell uses the existing notification API.

Activity → Change History hosts the existing VersionSelector. Inline rename uses the settings writer with the complete current settings object. Autosave retains Lynn's 900ms minimum spinner but requires a live gateway and no unacknowledged edits before showing Saved; alive:false produces the existing retry/error state.