From c85bfe57c841fe0af8a00275027956125b1a1688 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Wed, 3 Jun 2026 12:54:57 -0400
Subject: [PATCH 1/5] fix(ambient-ui): address CodeRabbit review findings from
 #1638

- Guard JSON array parsers against null/primitive entries (isRecord filter)
- Preserve temperature=0 as valid (only null maxTokens/timeout at zero)
- Normalize repo URLs when merging to avoid .git suffix mismatches
- Fix hydration mismatch: initialize tab state server-safe, sync from URL in useEffect

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../src/adapters/__tests__/mappers.test.ts    |  4 +-
 components/ambient-ui/src/adapters/mappers.ts | 71 +++++++++++--------
 .../[sessionId]/_components/resources-tab.tsx | 13 ++--
 .../[projectId]/sessions/[sessionId]/page.tsx | 12 ++--
 4 files changed, 58 insertions(+), 42 deletions(-)

diff --git a/components/ambient-ui/src/adapters/__tests__/mappers.test.ts b/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
index 156b4fdf1f..cc72f87f0b 100644
--- a/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
+++ b/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
@@ -333,11 +333,11 @@ describe('mapSdkSessionToDomain', () => {
       expect(domain.timeout).toBe(7200)
     })
 
-    it('returns null for zero temperature, maxTokens, timeout', () => {
+    it('preserves zero temperature but nulls zero maxTokens and timeout', () => {
       const sdk = makeSdkSession({ llm_temperature: 0, llm_max_tokens: 0, timeout: 0 })
       const domain = mapSdkSessionToDomain(sdk)
 
-      expect(domain.temperature).toBeNull()
+      expect(domain.temperature).toBe(0)
       expect(domain.maxTokens).toBeNull()
       expect(domain.timeout).toBeNull()
     })
diff --git a/components/ambient-ui/src/adapters/mappers.ts b/components/ambient-ui/src/adapters/mappers.ts
index a648c67efb..82d1bf2aa5 100644
--- a/components/ambient-ui/src/adapters/mappers.ts
+++ b/components/ambient-ui/src/adapters/mappers.ts
@@ -70,45 +70,50 @@ function parseJsonObject(raw: string): Record<string, string> {
 const VALID_REPO_STATUSES: ReadonlySet<string> = new Set(['Cloning', 'Ready', 'Failed'])
 const VALID_CONDITION_STATUSES: ReadonlySet<string> = new Set(['True', 'False', 'Unknown'])
 
+function isRecord(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v)
+}
+
 function parseRepos(raw: string): DomainRepo[] {
-  return parseJsonArray(raw).map((item) => {
-    const r = item as Record<string, unknown>
-    return {
+  return parseJsonArray(raw)
+    .filter(isRecord)
+    .map((r) => ({
       url: String(r.url ?? ''),
       branch: r.branch ? String(r.branch) : null,
       name: r.name ? String(r.name) : null,
       autoPush: Boolean(r.autoPush),
-    }
-  })
+    }))
 }
 
 function parseReconciledRepos(raw: string): DomainReconciledRepo[] {
-  return parseJsonArray(raw).map((item) => {
-    const r = item as Record<string, unknown>
-    const status = String(r.status ?? '')
-    return {
-      url: String(r.url ?? ''),
-      name: r.name ? String(r.name) : null,
-      status: VALID_REPO_STATUSES.has(status) ? (status as ReconciledRepoStatus) : null,
-      currentActiveBranch: r.currentActiveBranch ? String(r.currentActiveBranch) : null,
-      defaultBranch: r.defaultBranch ? String(r.defaultBranch) : null,
-      clonedAt: r.clonedAt ? String(r.clonedAt) : null,
-    }
-  })
+  return parseJsonArray(raw)
+    .filter(isRecord)
+    .map((r) => {
+      const status = String(r.status ?? '')
+      return {
+        url: String(r.url ?? ''),
+        name: r.name ? String(r.name) : null,
+        status: VALID_REPO_STATUSES.has(status) ? (status as ReconciledRepoStatus) : null,
+        currentActiveBranch: r.currentActiveBranch ? String(r.currentActiveBranch) : null,
+        defaultBranch: r.defaultBranch ? String(r.defaultBranch) : null,
+        clonedAt: r.clonedAt ? String(r.clonedAt) : null,
+      }
+    })
 }
 
 function parseConditions(raw: string): DomainCondition[] {
-  return parseJsonArray(raw).map((item) => {
-    const c = item as Record<string, unknown>
-    const status = String(c.status ?? 'Unknown')
-    return {
-      type: String(c.type ?? ''),
-      status: VALID_CONDITION_STATUSES.has(status) ? (status as ConditionStatus) : 'Unknown',
-      reason: c.reason ? String(c.reason) : null,
-      message: c.message ? String(c.message) : null,
-      lastTransitionTime: c.lastTransitionTime ? String(c.lastTransitionTime) : null,
-    }
-  })
+  return parseJsonArray(raw)
+    .filter(isRecord)
+    .map((c) => {
+      const status = String(c.status ?? 'Unknown')
+      return {
+        type: String(c.type ?? ''),
+        status: VALID_CONDITION_STATUSES.has(status) ? (status as ConditionStatus) : 'Unknown',
+        reason: c.reason ? String(c.reason) : null,
+        message: c.message ? String(c.message) : null,
+        lastTransitionTime: c.lastTransitionTime ? String(c.lastTransitionTime) : null,
+      }
+    })
 }
 
 function emptyToNull(value: string): string | null {
@@ -116,7 +121,11 @@ function emptyToNull(value: string): string | null {
 }
 
 function numberOrNull(value: number): number | null {
-  return value === 0 || value === undefined || value === null ? null : value
+  return value === undefined || value === null ? null : value
+}
+
+function positiveNumberOrNull(value: number): number | null {
+  return value === undefined || value === null || value === 0 ? null : value
 }
 
 export function mapSdkSessionToDomain(sdk: Session): DomainSession {
@@ -130,8 +139,8 @@ export function mapSdkSessionToDomain(sdk: Session): DomainSession {
     projectId: emptyToNull(sdk.project_id),
     model: emptyToNull(sdk.llm_model),
     temperature: numberOrNull(sdk.llm_temperature),
-    maxTokens: numberOrNull(sdk.llm_max_tokens),
-    timeout: numberOrNull(sdk.timeout),
+    maxTokens: positiveNumberOrNull(sdk.llm_max_tokens),
+    timeout: positiveNumberOrNull(sdk.timeout),
     workflowId: emptyToNull(sdk.workflow_id),
     prompt: emptyToNull(sdk.prompt),
     sdkRestartCount: sdk.sdk_restart_count ?? 0,
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
index 30cb4db5a3..88bcdf9a7c 100644
--- a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
@@ -29,20 +29,25 @@ type MergedRepo = {
   clonedAt: string | null
 }
 
+function normalizeUrl(url: string): string {
+  return url.replace(/\.git$/, '').replace(/\/$/, '')
+}
+
 function mergeRepos(
   repos: DomainRepo[],
   reconciledRepos: DomainReconciledRepo[],
 ): MergedRepo[] {
   const reconciledByUrl = new Map(
-    reconciledRepos.map(r => [r.url, r]),
+    reconciledRepos.map(r => [normalizeUrl(r.url), r]),
   )
 
   const seen = new Set<string>()
   const result: MergedRepo[] = []
 
   for (const repo of repos) {
-    seen.add(repo.url)
-    const reconciled = reconciledByUrl.get(repo.url)
+    const key = normalizeUrl(repo.url)
+    seen.add(key)
+    const reconciled = reconciledByUrl.get(key)
     result.push({
       url: repo.url,
       name: reconciled?.name ?? repo.name ?? baseNameFromUrl(repo.url),
@@ -53,7 +58,7 @@ function mergeRepos(
   }
 
   for (const reconciled of reconciledRepos) {
-    if (!seen.has(reconciled.url)) {
+    if (!seen.has(normalizeUrl(reconciled.url))) {
       result.push({
         url: reconciled.url,
         name: reconciled.name ?? baseNameFromUrl(reconciled.url),
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/page.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/page.tsx
index 251d3c73a9..bf38f1c2fe 100644
--- a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/page.tsx
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/page.tsx
@@ -1,6 +1,6 @@
 'use client'
 
-import { useState } from 'react'
+import { useState, useEffect } from 'react'
 import { useParams } from 'next/navigation'
 import { Skeleton } from '@/components/ui/skeleton'
 import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs'
@@ -21,12 +21,14 @@ import { ConfigTab } from './_components/config-tab'
 
 export default function SessionDetailPage() {
   const { sessionId } = useParams<{ projectId: string; sessionId: string }>()
-  const [activeTab, setActiveTab] = useState(() => {
-    if (typeof window === 'undefined') return 'overview'
-    return new URL(window.location.href).searchParams.get('tab') ?? 'overview'
-  })
+  const [activeTab, setActiveTab] = useState('overview')
   const { data: session, isLoading, error } = useSession(sessionId)
 
+  useEffect(() => {
+    const tab = new URL(window.location.href).searchParams.get('tab')
+    if (tab) setActiveTab(tab)
+  }, [])
+
   const handleTabChange = (value: string) => {
     setActiveTab(value)
     const url = new URL(window.location.href)

From 50a861c11318d765a0e15537bdd9de0b11c1268f Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Wed, 3 Jun 2026 13:04:51 -0400
Subject: [PATCH 2/5] fix(ambient-ui): widen number helper signatures,
 normalize baseNameFromUrl

- Widen numberOrNull/positiveNumberOrNull params to number | null | undefined
- Use normalizeUrl in baseNameFromUrl to handle trailing slashes and .git

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 components/ambient-ui/src/adapters/mappers.ts                 | 4 ++--
 .../sessions/[sessionId]/_components/resources-tab.tsx        | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/components/ambient-ui/src/adapters/mappers.ts b/components/ambient-ui/src/adapters/mappers.ts
index 82d1bf2aa5..77f490eb19 100644
--- a/components/ambient-ui/src/adapters/mappers.ts
+++ b/components/ambient-ui/src/adapters/mappers.ts
@@ -120,11 +120,11 @@ function emptyToNull(value: string): string | null {
   return value || null
 }
 
-function numberOrNull(value: number): number | null {
+function numberOrNull(value: number | null | undefined): number | null {
   return value === undefined || value === null ? null : value
 }
 
-function positiveNumberOrNull(value: number): number | null {
+function positiveNumberOrNull(value: number | null | undefined): number | null {
   return value === undefined || value === null || value === 0 ? null : value
 }
 
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
index 88bcdf9a7c..8a5812dada 100644
--- a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/resources-tab.tsx
@@ -73,7 +73,7 @@ function mergeRepos(
 }
 
 function baseNameFromUrl(url: string): string {
-  const segments = url.replace(/\.git$/, '').split('/')
+  const segments = normalizeUrl(url).split('/').filter(Boolean)
   return segments[segments.length - 1] || url
 }
 

From f0ec9004e746238faeec588c69cb449d52654475 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Wed, 3 Jun 2026 13:20:21 -0400
Subject: [PATCH 3/5] feat(ambient-ui): add Agents view and Session creation

- Agents view: table with name, model, owner, current session link,
  last active. Row click opens detail panel (Sheet) showing quick info,
  expandable prompt, and annotations
- Session create: Sheet form with name, agent select, prompt, model,
  and collapsible advanced settings (temperature, max tokens, timeout)
- Domain types, ports, adapters, mappers for agents (full port/adapter layer)
- Session create port/adapter extension with domain-to-SDK mapping
- useCreateSession mutation hook with cache invalidation
- Agents nav item in sidebar
- "+ New Session" button on sessions page and empty state

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../src/adapters/__tests__/mappers.test.ts    | 119 +++++++-
 components/ambient-ui/src/adapters/mappers.ts |  24 +-
 .../ambient-ui/src/adapters/sdk-agents.ts     |  50 ++++
 .../ambient-ui/src/adapters/sdk-client.ts     |  10 +-
 .../ambient-ui/src/adapters/sdk-sessions.ts   |  24 +-
 .../agents/_components/agent-detail-panel.tsx | 245 +++++++++++++++++
 .../agents/_components/agents-table.tsx       | 180 ++++++++++++
 .../(dashboard)/[projectId]/agents/page.tsx   |  81 ++++++
 .../_components/create-session-sheet.tsx      | 260 ++++++++++++++++++
 .../(dashboard)/[projectId]/sessions/page.tsx |  31 ++-
 .../ambient-ui/src/components/app-sidebar.tsx |   1 +
 components/ambient-ui/src/domain/types.ts     |  29 ++
 components/ambient-ui/src/ports/agents.ts     |   6 +
 components/ambient-ui/src/ports/sessions.ts   |   3 +-
 .../ambient-ui/src/queries/query-keys.ts      |   6 +
 .../ambient-ui/src/queries/use-agents.ts      |  37 +++
 .../ambient-ui/src/queries/use-sessions.ts    |  14 +-
 17 files changed, 1104 insertions(+), 16 deletions(-)
 create mode 100644 components/ambient-ui/src/adapters/sdk-agents.ts
 create mode 100644 components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agent-detail-panel.tsx
 create mode 100644 components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agents-table.tsx
 create mode 100644 components/ambient-ui/src/app/(dashboard)/[projectId]/agents/page.tsx
 create mode 100644 components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/_components/create-session-sheet.tsx
 create mode 100644 components/ambient-ui/src/ports/agents.ts

diff --git a/components/ambient-ui/src/adapters/__tests__/mappers.test.ts b/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
index cc72f87f0b..290342c269 100644
--- a/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
+++ b/components/ambient-ui/src/adapters/__tests__/mappers.test.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect } from 'vitest'
-import { mapSdkSessionToDomain, mapSdkProjectToDomain, mapSessionMessageToDomain } from '../mappers'
+import { mapSdkSessionToDomain, mapSdkProjectToDomain, mapSessionMessageToDomain, mapSdkAgentToDomain } from '../mappers'
 import type { SdkSessionMessageShape } from '../mappers'
-import type { Session, Project } from 'ambient-sdk'
+import type { Session, Project, Agent } from 'ambient-sdk'
 
 function makeSdkSession(overrides: Partial<Session> = {}): Session {
   return {
@@ -454,3 +454,118 @@ describe('mapSessionMessageToDomain', () => {
     expect(domain.payload).toBe(complexPayload)
   })
 })
+
+function makeSdkAgent(overrides: Partial<Agent> = {}): Agent {
+  return {
+    id: 'agent-001',
+    kind: 'Agent',
+    href: '/api/ambient/v1/agents/agent-001',
+    created_at: '2026-02-01T09:00:00Z',
+    updated_at: '2026-02-01T10:00:00Z',
+    annotations: '{}',
+    bot_account_name: '',
+    current_session_id: '',
+    description: 'A test agent',
+    display_name: 'Test Agent',
+    environment_variables: '',
+    labels: '',
+    llm_max_tokens: 4096,
+    llm_model: 'claude-sonnet-4-20250514',
+    llm_temperature: 0.7,
+    name: 'test-agent',
+    owner_user_id: 'user-42',
+    parent_agent_id: '',
+    project_id: 'proj-123',
+    prompt: 'You are a helpful agent.',
+    repo_url: 'https://github.com/org/repo',
+    resource_overrides: '',
+    workflow_id: 'wf-1',
+    ...overrides,
+  }
+}
+
+describe('mapSdkAgentToDomain', () => {
+  it('maps snake_case fields to camelCase', () => {
+    const sdk = makeSdkAgent()
+    const domain = mapSdkAgentToDomain(sdk)
+
+    expect(domain.id).toBe('agent-001')
+    expect(domain.name).toBe('test-agent')
+    expect(domain.displayName).toBe('Test Agent')
+    expect(domain.description).toBe('A test agent')
+    expect(domain.model).toBe('claude-sonnet-4-20250514')
+    expect(domain.ownerUserId).toBe('user-42')
+    expect(domain.projectId).toBe('proj-123')
+    expect(domain.prompt).toBe('You are a helpful agent.')
+    expect(domain.repoUrl).toBe('https://github.com/org/repo')
+    expect(domain.workflowId).toBe('wf-1')
+    expect(domain.createdAt).toBe('2026-02-01T09:00:00Z')
+    expect(domain.updatedAt).toBe('2026-02-01T10:00:00Z')
+  })
+
+  it('maps empty string fields to null', () => {
+    const sdk = makeSdkAgent({
+      display_name: '',
+      description: '',
+      llm_model: '',
+      owner_user_id: '',
+      current_session_id: '',
+      project_id: '',
+      prompt: '',
+      repo_url: '',
+      workflow_id: '',
+    })
+    const domain = mapSdkAgentToDomain(sdk)
+
+    expect(domain.displayName).toBeNull()
+    expect(domain.description).toBeNull()
+    expect(domain.model).toBeNull()
+    expect(domain.ownerUserId).toBeNull()
+    expect(domain.currentSessionId).toBeNull()
+    expect(domain.projectId).toBeNull()
+    expect(domain.prompt).toBeNull()
+    expect(domain.repoUrl).toBeNull()
+    expect(domain.workflowId).toBeNull()
+  })
+
+  it('parses valid annotations JSON to Record', () => {
+    const annotations = JSON.stringify({ team: 'platform', tier: 'production' })
+    const sdk = makeSdkAgent({ annotations })
+    const domain = mapSdkAgentToDomain(sdk)
+
+    expect(domain.annotations).toEqual({ team: 'platform', tier: 'production' })
+  })
+
+  it('returns empty Record for invalid annotations', () => {
+    const sdk = makeSdkAgent({ annotations: 'broken{' })
+    const domain = mapSdkAgentToDomain(sdk)
+    expect(domain.annotations).toEqual({})
+  })
+
+  it('parses valid labels JSON to Record', () => {
+    const labels = JSON.stringify({ env: 'dev', app: 'backend' })
+    const sdk = makeSdkAgent({ labels })
+    const domain = mapSdkAgentToDomain(sdk)
+
+    expect(domain.labels).toEqual({ env: 'dev', app: 'backend' })
+  })
+
+  it('returns empty Record for invalid labels', () => {
+    const sdk = makeSdkAgent({ labels: '["a"]' })
+    const domain = mapSdkAgentToDomain(sdk)
+    expect(domain.labels).toEqual({})
+  })
+
+  it('handles null created_at and updated_at', () => {
+    const sdk = makeSdkAgent({ created_at: null, updated_at: null })
+    const domain = mapSdkAgentToDomain(sdk)
+    expect(domain.createdAt).toBe('')
+    expect(domain.updatedAt).toBe('')
+  })
+
+  it('maps current_session_id when present', () => {
+    const sdk = makeSdkAgent({ current_session_id: 'sess-abc' })
+    const domain = mapSdkAgentToDomain(sdk)
+    expect(domain.currentSessionId).toBe('sess-abc')
+  })
+})
diff --git a/components/ambient-ui/src/adapters/mappers.ts b/components/ambient-ui/src/adapters/mappers.ts
index 77f490eb19..3bdba65db7 100644
--- a/components/ambient-ui/src/adapters/mappers.ts
+++ b/components/ambient-ui/src/adapters/mappers.ts
@@ -1,6 +1,6 @@
-import type { Session, Project } from 'ambient-sdk'
+import type { Session, Project, Agent } from 'ambient-sdk'
 import type {
-  DomainSession, DomainProject, DomainSessionMessage, SessionPhase, SessionEventType,
+  DomainSession, DomainProject, DomainSessionMessage, DomainAgent, SessionPhase, SessionEventType,
   DomainRepo, DomainReconciledRepo, DomainCondition, ReconciledRepoStatus, ConditionStatus,
 } from '@/domain/types'
 
@@ -168,6 +168,26 @@ export function mapSdkProjectToDomain(sdk: Project): DomainProject {
   }
 }
 
+export function mapSdkAgentToDomain(sdk: Agent): DomainAgent {
+  return {
+    id: sdk.id,
+    name: sdk.name,
+    displayName: emptyToNull(sdk.display_name),
+    description: emptyToNull(sdk.description),
+    model: emptyToNull(sdk.llm_model),
+    ownerUserId: emptyToNull(sdk.owner_user_id),
+    currentSessionId: emptyToNull(sdk.current_session_id),
+    projectId: emptyToNull(sdk.project_id),
+    prompt: emptyToNull(sdk.prompt),
+    repoUrl: emptyToNull(sdk.repo_url),
+    workflowId: emptyToNull(sdk.workflow_id),
+    annotations: parseAnnotations(sdk.annotations),
+    labels: parseJsonObject(sdk.labels),
+    createdAt: sdk.created_at ?? '',
+    updatedAt: sdk.updated_at ?? '',
+  }
+}
+
 export type SdkSessionMessageShape = {
   id: string
   session_id: string
diff --git a/components/ambient-ui/src/adapters/sdk-agents.ts b/components/ambient-ui/src/adapters/sdk-agents.ts
new file mode 100644
index 0000000000..0a95c06b4d
--- /dev/null
+++ b/components/ambient-ui/src/adapters/sdk-agents.ts
@@ -0,0 +1,50 @@
+import type { AgentAPI } from 'ambient-sdk'
+import type { AgentsPort } from '@/ports/agents'
+import type { DomainAgent, ListParams, PaginatedResult } from '@/domain/types'
+import { mapSdkAgentToDomain } from './mappers'
+import { getAgentAPI } from './sdk-client'
+
+function sanitizeSearch(value: string): string {
+  return value.replace(/['"%;\\]/g, '')
+}
+
+function buildSdkListOptions(projectId: string, params?: ListParams) {
+  const search = params?.search
+    ? `project_id = '${sanitizeSearch(projectId)}' and name like '%${sanitizeSearch(params.search)}%'`
+    : `project_id = '${sanitizeSearch(projectId)}'`
+
+  return {
+    page: params?.page ?? 1,
+    size: params?.size ?? 20,
+    search,
+    orderBy: params?.orderBy,
+  }
+}
+
+function createSdkAgentsAdapter(api: AgentAPI): AgentsPort {
+  return {
+    async list(projectId: string, params?: ListParams): Promise<PaginatedResult<DomainAgent>> {
+      const opts = buildSdkListOptions(projectId, params)
+      const result = await api.list(opts)
+      const items = result.items.map(mapSdkAgentToDomain)
+      const page = opts.page
+      const size = opts.size
+      return {
+        items,
+        total: result.total,
+        page,
+        size,
+        hasMore: page * size < result.total,
+      }
+    },
+
+    async get(agentId: string): Promise<DomainAgent> {
+      const agent = await api.get(agentId)
+      return mapSdkAgentToDomain(agent)
+    },
+  }
+}
+
+export function createAgentsAdapter(api?: AgentAPI): AgentsPort {
+  return createSdkAgentsAdapter(api ?? getAgentAPI())
+}
diff --git a/components/ambient-ui/src/adapters/sdk-client.ts b/components/ambient-ui/src/adapters/sdk-client.ts
index 597020ac37..f94d7bee3b 100644
--- a/components/ambient-ui/src/adapters/sdk-client.ts
+++ b/components/ambient-ui/src/adapters/sdk-client.ts
@@ -1,5 +1,5 @@
 import type { AmbientClientConfig } from 'ambient-sdk'
-import { SessionAPI, ProjectAPI } from 'ambient-sdk'
+import { SessionAPI, ProjectAPI, AgentAPI } from 'ambient-sdk'
 
 // BFF proxy config: empty baseUrl produces relative URLs like /api/ambient/v1/sessions
 // which hit the Next.js BFF proxy. No token needed — the proxy adds it server-side.
@@ -13,6 +13,7 @@ const bffConfig: AmbientClientConfig = {
 
 let sessions: SessionAPI | null = null
 let projects: ProjectAPI | null = null
+let agents: AgentAPI | null = null
 
 export function getSessionAPI(): SessionAPI {
   if (!sessions) {
@@ -28,6 +29,13 @@ export function getProjectAPI(): ProjectAPI {
   return projects
 }
 
+export function getAgentAPI(): AgentAPI {
+  if (!agents) {
+    agents = new AgentAPI(bffConfig)
+  }
+  return agents
+}
+
 export function getConfig(): AmbientClientConfig {
   return bffConfig
 }
diff --git a/components/ambient-ui/src/adapters/sdk-sessions.ts b/components/ambient-ui/src/adapters/sdk-sessions.ts
index d2f7d7e881..2f6c2f9770 100644
--- a/components/ambient-ui/src/adapters/sdk-sessions.ts
+++ b/components/ambient-ui/src/adapters/sdk-sessions.ts
@@ -1,6 +1,6 @@
-import type { SessionAPI } from 'ambient-sdk'
+import type { SessionAPI, SessionCreateRequest } from 'ambient-sdk'
 import type { SessionsPort } from '@/ports/sessions'
-import type { DomainSession, ListParams, PaginatedResult } from '@/domain/types'
+import type { DomainSession, DomainSessionCreateRequest, ListParams, PaginatedResult } from '@/domain/types'
 import { mapSdkSessionToDomain } from './mappers'
 import { getSessionAPI } from './sdk-client'
 
@@ -21,6 +21,20 @@ function buildSdkListOptions(projectId: string, params?: ListParams) {
   }
 }
 
+function mapDomainCreateToSdk(request: DomainSessionCreateRequest): SessionCreateRequest {
+  const sdkReq: SessionCreateRequest = {
+    name: request.name,
+    project_id: request.projectId,
+  }
+  if (request.agentId) sdkReq.agent_id = request.agentId
+  if (request.prompt) sdkReq.prompt = request.prompt
+  if (request.model) sdkReq.llm_model = request.model
+  if (request.temperature !== undefined) sdkReq.llm_temperature = request.temperature
+  if (request.maxTokens !== undefined) sdkReq.llm_max_tokens = request.maxTokens
+  if (request.timeout !== undefined) sdkReq.timeout = request.timeout
+  return sdkReq
+}
+
 function createSdkSessionsAdapter(api: SessionAPI): SessionsPort {
   return {
     async list(projectId: string, params?: ListParams): Promise<PaginatedResult<DomainSession>> {
@@ -43,6 +57,12 @@ function createSdkSessionsAdapter(api: SessionAPI): SessionsPort {
       return mapSdkSessionToDomain(session)
     },
 
+    async create(request: DomainSessionCreateRequest): Promise<DomainSession> {
+      const sdkReq = mapDomainCreateToSdk(request)
+      const session = await api.create(sdkReq)
+      return mapSdkSessionToDomain(session)
+    },
+
     async stop(sessionId: string): Promise<void> {
       await api.stop(sessionId)
     },
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agent-detail-panel.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agent-detail-panel.tsx
new file mode 100644
index 0000000000..1bef9437d4
--- /dev/null
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agent-detail-panel.tsx
@@ -0,0 +1,245 @@
+'use client'
+
+import { useState } from 'react'
+import Link from 'next/link'
+import type { LucideIcon } from 'lucide-react'
+import {
+  Pin,
+  Tag,
+  Ticket,
+  GitPullRequest,
+  GitBranch,
+  FolderGit2,
+  Layers,
+  ExternalLink,
+  MessageCircle,
+  User,
+  Play,
+  DollarSign,
+  Siren,
+  Bot,
+  AlertTriangle,
+} from 'lucide-react'
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+} from '@/components/ui/sheet'
+import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import { Badge } from '@/components/ui/badge'
+import { MetaRow, NoValue } from '@/app/(dashboard)/[projectId]/sessions/[sessionId]/_components/meta-row'
+import { getRegisteredAnnotation } from '@/domain/annotations'
+import type { DomainAgent } from '@/domain/types'
+import { formatRelativeTime } from '@/lib/format-timestamp'
+
+const ICON_MAP: Record<string, LucideIcon> = {
+  pin: Pin, tag: Tag, ticket: Ticket, layers: Layers, play: Play, bot: Bot,
+  siren: Siren, user: User, 'dollar-sign': DollarSign,
+  'git-pull-request': GitPullRequest, 'git-branch': GitBranch,
+  'folder-git-2': FolderGit2, 'external-link': ExternalLink,
+  'message-circle': MessageCircle, 'alert-triangle': AlertTriangle,
+}
+
+const PROMPT_TRUNCATE_LENGTH = 200
+
+function isClickableValue(value: string): boolean {
+  return /^https?:\/\//.test(value)
+}
+
+export function AgentDetailPanel({
+  agent,
+  projectId,
+  onClose,
+}: {
+  agent: DomainAgent | null
+  projectId: string
+  onClose: () => void
+}) {
+  const [promptExpanded, setPromptExpanded] = useState(false)
+
+  const isOpen = agent !== null
+
+  const annotationEntries = agent ? Object.entries(agent.annotations) : []
+  const labelEntries = agent ? Object.entries(agent.labels) : []
+
+  const promptNeedsTruncation =
+    agent?.prompt != null && agent.prompt.length > PROMPT_TRUNCATE_LENGTH
+  const displayPrompt =
+    agent?.prompt != null
+      ? promptNeedsTruncation && !promptExpanded
+        ? agent.prompt.slice(0, PROMPT_TRUNCATE_LENGTH) + '...'
+        : agent.prompt
+      : null
+
+  return (
+    <Sheet open={isOpen} onOpenChange={(open) => { if (!open) onClose() }}>
+      <SheetContent side="right" className="sm:max-w-lg overflow-y-auto">
+        {agent && (
+          <>
+            <SheetHeader>
+              <SheetTitle>{agent.displayName ?? agent.name}</SheetTitle>
+              {agent.displayName && (
+                <SheetDescription className="font-mono text-xs">
+                  {agent.name}
+                </SheetDescription>
+              )}
+            </SheetHeader>
+
+            <div className="space-y-6 px-4 pb-4">
+              <Card>
+                <CardHeader>
+                  <CardTitle className="text-base">Quick Info</CardTitle>
+                </CardHeader>
+                <CardContent>
+                  <dl className="grid grid-cols-1 sm:grid-cols-2 gap-x-8 gap-y-3 text-sm">
+                    <MetaRow label="Model" value={agent.model ?? <NoValue />} />
+                    <MetaRow label="Owner" value={agent.ownerUserId ?? <NoValue />} />
+                    <MetaRow
+                      label="Current Session"
+                      value={
+                        agent.currentSessionId ? (
+                          <Link
+                            href={`/${projectId}/sessions/${agent.currentSessionId}`}
+                            className="text-xs font-mono text-link underline hover:text-link-hover"
+                            onClick={(e) => e.stopPropagation()}
+                          >
+                            {agent.currentSessionId}
+                          </Link>
+                        ) : (
+                          <NoValue />
+                        )
+                      }
+                    />
+                    <MetaRow
+                      label="Repository"
+                      value={
+                        agent.repoUrl ? (
+                          <a
+                            href={agent.repoUrl}
+                            target="_blank"
+                            rel="noopener noreferrer"
+                            className="text-xs text-link underline hover:text-link-hover truncate"
+                          >
+                            {agent.repoUrl}
+                          </a>
+                        ) : (
+                          <NoValue />
+                        )
+                      }
+                    />
+                    <MetaRow label="Workflow ID" value={agent.workflowId ? <span className="font-mono text-xs">{agent.workflowId}</span> : <NoValue />} />
+                    <MetaRow label="Description" value={agent.description ?? <NoValue />} />
+                    <MetaRow label="Created" value={agent.createdAt ? formatRelativeTime(agent.createdAt) : <NoValue />} />
+                    <MetaRow label="Updated" value={agent.updatedAt ? formatRelativeTime(agent.updatedAt) : <NoValue />} />
+                  </dl>
+                </CardContent>
+              </Card>
+
+              {displayPrompt != null && (
+                <Card>
+                  <CardHeader>
+                    <CardTitle className="text-base">Prompt</CardTitle>
+                  </CardHeader>
+                  <CardContent>
+                    <pre className="whitespace-pre-wrap text-sm font-mono">{displayPrompt}</pre>
+                    {promptNeedsTruncation && (
+                      <button
+                        type="button"
+                        className="mt-2 py-1 text-sm text-muted-foreground underline hover:text-foreground"
+                        onClick={() => setPromptExpanded((prev) => !prev)}
+                      >
+                        {promptExpanded
+                          ? 'Show less'
+                          : `Show more (${agent.prompt!.length.toLocaleString()} chars)`}
+                      </button>
+                    )}
+                  </CardContent>
+                </Card>
+              )}
+
+              {annotationEntries.length > 0 && (
+                <Card>
+                  <CardHeader>
+                    <CardTitle className="text-base">
+                      Annotations ({annotationEntries.length})
+                    </CardTitle>
+                  </CardHeader>
+                  <CardContent>
+                    <Table>
+                      <TableHeader>
+                        <TableRow>
+                          <TableHead>Key</TableHead>
+                          <TableHead>Value</TableHead>
+                        </TableRow>
+                      </TableHeader>
+                      <TableBody>
+                        {annotationEntries.map(([key, value]) => {
+                          const registered = getRegisteredAnnotation(key)
+                          const Icon = registered?.icon ? ICON_MAP[registered.icon] : null
+                          const clickable = isClickableValue(value)
+                          return (
+                            <TableRow key={key}>
+                              <TableCell className="font-mono text-xs">
+                                <span className="inline-flex items-center gap-1.5">
+                                  {Icon && <Icon className="size-3.5 shrink-0 text-muted-foreground" />}
+                                  {registered ? registered.label : key}
+                                </span>
+                              </TableCell>
+                              <TableCell className="text-sm">
+                                {clickable ? (
+                                  <a
+                                    href={value}
+                                    target="_blank"
+                                    rel="noopener noreferrer"
+                                    className="truncate text-link underline hover:text-link-hover"
+                                  >
+                                    {value}
+                                  </a>
+                                ) : (
+                                  value
+                                )}
+                              </TableCell>
+                            </TableRow>
+                          )
+                        })}
+                      </TableBody>
+                    </Table>
+                  </CardContent>
+                </Card>
+              )}
+
+              {labelEntries.length > 0 && (
+                <Card>
+                  <CardHeader>
+                    <CardTitle className="text-base">
+                      Labels ({labelEntries.length})
+                    </CardTitle>
+                  </CardHeader>
+                  <CardContent>
+                    <div className="flex flex-wrap gap-2">
+                      {labelEntries.map(([key, value]) => (
+                        <Badge key={key} variant="secondary" className="text-xs">
+                          {key}: {value}
+                        </Badge>
+                      ))}
+                    </div>
+                  </CardContent>
+                </Card>
+              )}
+            </div>
+          </>
+        )}
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agents-table.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agents-table.tsx
new file mode 100644
index 0000000000..fd8c4e7ba8
--- /dev/null
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/_components/agents-table.tsx
@@ -0,0 +1,180 @@
+'use client'
+
+import { useState } from 'react'
+import {
+  useReactTable,
+  getCoreRowModel,
+  getFilteredRowModel,
+  getSortedRowModel,
+  createColumnHelper,
+  flexRender,
+} from '@tanstack/react-table'
+import type { SortingState } from '@tanstack/react-table'
+import { ChevronUp, ChevronDown } from 'lucide-react'
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from '@/components/ui/table'
+import type { DomainAgent } from '@/domain/types'
+import { formatRelativeTime } from '@/lib/format-timestamp'
+
+const col = createColumnHelper<DomainAgent>()
+
+const agentColumns = [
+  col.accessor((row) => row.displayName ?? row.name, {
+    id: 'name',
+    header: 'Name',
+    cell: info => (
+      <div>
+        <span className="font-medium">{info.getValue()}</span>
+        {info.row.original.displayName && (
+          <span className="ml-2 text-xs text-muted-foreground">
+            {info.row.original.name}
+          </span>
+        )}
+      </div>
+    ),
+  }),
+  col.accessor('model', {
+    header: 'Model',
+    cell: info => (
+      <span className="text-muted-foreground text-xs">
+        {info.getValue() ?? '—'}
+      </span>
+    ),
+  }),
+  col.accessor('ownerUserId', {
+    header: 'Owner',
+    cell: info => (
+      <span className="text-sm text-muted-foreground">
+        {info.getValue() ?? '—'}
+      </span>
+    ),
+  }),
+  col.accessor('currentSessionId', {
+    header: 'Current Session',
+    cell: info => {
+      const sessionId = info.getValue()
+      if (!sessionId) return <span className="text-muted-foreground">{'—'}</span>
+      return (
+        <span className="text-xs font-mono text-foreground truncate max-w-[120px] inline-block">
+          {sessionId}
+        </span>
+      )
+    },
+  }),
+  col.display({
+    id: 'lastActive',
+    header: 'Last Active',
+    enableSorting: true,
+    sortingFn: (rowA, rowB) => {
+      return new Date(rowA.original.updatedAt).getTime() - new Date(rowB.original.updatedAt).getTime()
+    },
+    cell: ({ row }) => (
+      <span className="text-muted-foreground text-xs">
+        {row.original.updatedAt ? formatRelativeTime(row.original.updatedAt) : '—'}
+      </span>
+    ),
+  }),
+]
+
+export function AgentsTable({
+  agents,
+  searchFilter,
+  onSelectAgent,
+}: {
+  agents: DomainAgent[]
+  searchFilter: string
+  onSelectAgent: (agent: DomainAgent) => void
+}) {
+  const [sorting, setSorting] = useState<SortingState>([
+    { id: 'lastActive', desc: true },
+  ])
+
+  const table = useReactTable({
+    data: agents,
+    columns: agentColumns,
+    getCoreRowModel: getCoreRowModel(),
+    getFilteredRowModel: getFilteredRowModel(),
+    getSortedRowModel: getSortedRowModel(),
+    globalFilterFn: 'includesString',
+    state: {
+      globalFilter: searchFilter,
+      sorting,
+    },
+    onSortingChange: setSorting,
+  })
+
+  return (
+    <div className="rounded-md border">
+      <Table>
+        <TableHeader>
+          {table.getHeaderGroups().map(headerGroup => (
+            <TableRow key={headerGroup.id}>
+              {headerGroup.headers.map(header => {
+                const canSort = header.column.getCanSort()
+                const sorted = header.column.getIsSorted()
+
+                return (
+                  <TableHead
+                    key={header.id}
+                    className={canSort ? 'cursor-pointer select-none' : undefined}
+                    onClick={canSort ? header.column.getToggleSortingHandler() : undefined}
+                  >
+                    <div className="flex items-center gap-1">
+                      {header.isPlaceholder
+                        ? null
+                        : flexRender(header.column.columnDef.header, header.getContext())}
+                      {canSort && sorted === 'asc' && (
+                        <ChevronUp className="size-3.5 text-foreground" />
+                      )}
+                      {canSort && sorted === 'desc' && (
+                        <ChevronDown className="size-3.5 text-foreground" />
+                      )}
+                      {canSort && !sorted && (
+                        <ChevronDown className="size-3.5 text-muted-foreground/40" />
+                      )}
+                    </div>
+                  </TableHead>
+                )
+              })}
+            </TableRow>
+          ))}
+        </TableHeader>
+        <TableBody>
+          {table.getRowModel().rows.length ? (
+            table.getRowModel().rows.map(row => (
+              <TableRow
+                key={row.id}
+                className="cursor-pointer group"
+                tabIndex={0}
+                onClick={() => onSelectAgent(row.original)}
+                onKeyDown={(e) => {
+                  if (e.key === 'Enter') {
+                    onSelectAgent(row.original)
+                  }
+                }}
+              >
+                {row.getVisibleCells().map(cell => (
+                  <TableCell key={cell.id}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </TableCell>
+                ))}
+              </TableRow>
+            ))
+          ) : (
+            <TableRow>
+              <TableCell colSpan={agentColumns.length} className="h-24 text-center text-muted-foreground">
+                No agents match your filter.
+              </TableCell>
+            </TableRow>
+          )}
+        </TableBody>
+      </Table>
+    </div>
+  )
+}
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/page.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/page.tsx
new file mode 100644
index 0000000000..2292e74554
--- /dev/null
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/agents/page.tsx
@@ -0,0 +1,81 @@
+'use client'
+
+import { useState } from 'react'
+import { useParams } from 'next/navigation'
+import { Bot } from 'lucide-react'
+import { Input } from '@/components/ui/input'
+import { Skeleton } from '@/components/ui/skeleton'
+import { EmptyState } from '@/components/empty-state'
+import { useAgents } from '@/queries/use-agents'
+import type { DomainAgent } from '@/domain/types'
+import { AgentsTable } from './_components/agents-table'
+import { AgentDetailPanel } from './_components/agent-detail-panel'
+
+export default function AgentsPage() {
+  const { projectId } = useParams<{ projectId: string }>()
+  const [search, setSearch] = useState('')
+  const [selectedAgent, setSelectedAgent] = useState<DomainAgent | null>(null)
+  const { data, isLoading, error } = useAgents(projectId)
+
+  if (error) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-xl font-semibold">Agents</h1>
+        <p className="text-sm text-destructive">
+          Failed to load agents: {error.message}
+        </p>
+      </div>
+    )
+  }
+
+  if (isLoading) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-xl font-semibold">Agents</h1>
+        <div className="space-y-3">
+          <Skeleton className="h-8 w-64" />
+          <Skeleton className="h-[400px] w-full" />
+        </div>
+      </div>
+    )
+  }
+
+  const agents = data?.items ?? []
+
+  if (agents.length === 0) {
+    return (
+      <div className="space-y-6">
+        <h1 className="text-xl font-semibold">Agents</h1>
+        <EmptyState
+          icon={Bot}
+          title="No agents"
+          description="This project has no agents yet."
+        />
+      </div>
+    )
+  }
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <h1 className="text-xl font-semibold">Agents</h1>
+        <Input
+          placeholder="Filter by name, model, or owner..."
+          value={search}
+          onChange={e => setSearch(e.target.value)}
+          className="max-w-xs"
+        />
+      </div>
+      <AgentsTable
+        agents={agents}
+        searchFilter={search}
+        onSelectAgent={setSelectedAgent}
+      />
+      <AgentDetailPanel
+        agent={selectedAgent}
+        projectId={projectId}
+        onClose={() => setSelectedAgent(null)}
+      />
+    </div>
+  )
+}
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/_components/create-session-sheet.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/_components/create-session-sheet.tsx
new file mode 100644
index 0000000000..408990988f
--- /dev/null
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/_components/create-session-sheet.tsx
@@ -0,0 +1,260 @@
+'use client'
+
+import { useState } from 'react'
+import { useRouter, useParams } from 'next/navigation'
+import {
+  Sheet,
+  SheetContent,
+  SheetHeader,
+  SheetTitle,
+  SheetDescription,
+  SheetFooter,
+} from '@/components/ui/sheet'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Textarea } from '@/components/ui/textarea'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { useCreateSession } from '@/queries/use-sessions'
+import { useAgents } from '@/queries/use-agents'
+import type { DomainSessionCreateRequest } from '@/domain/types'
+
+const MODEL_OPTIONS = [
+  'claude-sonnet-4-20250514',
+  'claude-opus-4-20250514',
+  'claude-haiku-35-20241022',
+] as const
+
+export function CreateSessionSheet({
+  open,
+  onOpenChange,
+}: {
+  open: boolean
+  onOpenChange: (open: boolean) => void
+}) {
+  const router = useRouter()
+  const { projectId } = useParams<{ projectId: string }>()
+  const createSession = useCreateSession()
+  const { data: agentsData } = useAgents(projectId, { size: 100 })
+
+  const [name, setName] = useState('')
+  const [agentId, setAgentId] = useState('')
+  const [prompt, setPrompt] = useState('')
+  const [model, setModel] = useState('')
+  const [showAdvanced, setShowAdvanced] = useState(false)
+  const [temperature, setTemperature] = useState('')
+  const [maxTokens, setMaxTokens] = useState('')
+  const [timeout, setTimeout] = useState('')
+  const [error, setError] = useState<string | null>(null)
+
+  const agents = agentsData?.items ?? []
+
+  function resetForm() {
+    setName('')
+    setAgentId('')
+    setPrompt('')
+    setModel('')
+    setShowAdvanced(false)
+    setTemperature('')
+    setMaxTokens('')
+    setTimeout('')
+    setError(null)
+  }
+
+  async function handleSubmit(e: React.FormEvent) {
+    e.preventDefault()
+    setError(null)
+
+    if (!name.trim()) {
+      setError('Name is required.')
+      return
+    }
+
+    const request: DomainSessionCreateRequest = {
+      name: name.trim(),
+      projectId,
+    }
+
+    if (agentId) request.agentId = agentId
+    if (prompt.trim()) request.prompt = prompt.trim()
+    if (model) request.model = model
+
+    if (showAdvanced) {
+      const tempVal = parseFloat(temperature)
+      if (!isNaN(tempVal)) request.temperature = tempVal
+
+      const maxTokVal = parseInt(maxTokens, 10)
+      if (!isNaN(maxTokVal) && maxTokVal > 0) request.maxTokens = maxTokVal
+
+      const timeoutVal = parseInt(timeout, 10)
+      if (!isNaN(timeoutVal) && timeoutVal > 0) request.timeout = timeoutVal
+    }
+
+    try {
+      const session = await createSession.mutateAsync(request)
+      resetForm()
+      onOpenChange(false)
+      router.push(`/${projectId}/sessions/${session.id}`)
+    } catch (err) {
+      setError(err instanceof Error ? err.message : 'Failed to create session.')
+    }
+  }
+
+  return (
+    <Sheet open={open} onOpenChange={(v) => { if (!v) resetForm(); onOpenChange(v) }}>
+      <SheetContent side="right" className="sm:max-w-lg overflow-y-auto">
+        <SheetHeader>
+          <SheetTitle>New Session</SheetTitle>
+          <SheetDescription>
+            Create a new agentic session in this project.
+          </SheetDescription>
+        </SheetHeader>
+
+        <form onSubmit={handleSubmit} className="flex flex-col gap-4 px-4 pb-4">
+          <div className="space-y-1.5">
+            <label htmlFor="session-name" className="text-sm font-medium">
+              Name <span className="text-destructive">*</span>
+            </label>
+            <Input
+              id="session-name"
+              placeholder="my-session"
+              value={name}
+              onChange={e => setName(e.target.value)}
+              required
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <label htmlFor="session-agent" className="text-sm font-medium">
+              Agent
+            </label>
+            <Select value={agentId} onValueChange={setAgentId}>
+              <SelectTrigger id="session-agent" className="w-full">
+                <SelectValue placeholder="Select an agent (optional)" />
+              </SelectTrigger>
+              <SelectContent>
+                {agents.map(agent => (
+                  <SelectItem key={agent.id} value={agent.id}>
+                    {agent.displayName ?? agent.name}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <div className="space-y-1.5">
+            <label htmlFor="session-prompt" className="text-sm font-medium">
+              Prompt
+            </label>
+            <Textarea
+              id="session-prompt"
+              placeholder="Describe what this session should do..."
+              value={prompt}
+              onChange={e => setPrompt(e.target.value)}
+              className="min-h-24"
+            />
+          </div>
+
+          <div className="space-y-1.5">
+            <label htmlFor="session-model" className="text-sm font-medium">
+              Model
+            </label>
+            <Select value={model} onValueChange={setModel}>
+              <SelectTrigger id="session-model" className="w-full">
+                <SelectValue placeholder="Select a model (optional)" />
+              </SelectTrigger>
+              <SelectContent>
+                {MODEL_OPTIONS.map(m => (
+                  <SelectItem key={m} value={m}>
+                    {m}
+                  </SelectItem>
+                ))}
+              </SelectContent>
+            </Select>
+          </div>
+
+          <button
+            type="button"
+            className="text-sm text-muted-foreground underline hover:text-foreground text-left"
+            onClick={() => setShowAdvanced(prev => !prev)}
+          >
+            {showAdvanced ? 'Hide advanced settings' : 'Show advanced settings'}
+          </button>
+
+          {showAdvanced && (
+            <div className="space-y-4 rounded-md border p-4">
+              <div className="space-y-1.5">
+                <label htmlFor="session-temperature" className="text-sm font-medium">
+                  Temperature
+                </label>
+                <Input
+                  id="session-temperature"
+                  type="number"
+                  step="0.1"
+                  min="0"
+                  max="2"
+                  placeholder="0.7"
+                  value={temperature}
+                  onChange={e => setTemperature(e.target.value)}
+                />
+              </div>
+
+              <div className="space-y-1.5">
+                <label htmlFor="session-max-tokens" className="text-sm font-medium">
+                  Max Tokens
+                </label>
+                <Input
+                  id="session-max-tokens"
+                  type="number"
+                  min="1"
+                  placeholder="4096"
+                  value={maxTokens}
+                  onChange={e => setMaxTokens(e.target.value)}
+                />
+              </div>
+
+              <div className="space-y-1.5">
+                <label htmlFor="session-timeout" className="text-sm font-medium">
+                  Timeout (seconds)
+                </label>
+                <Input
+                  id="session-timeout"
+                  type="number"
+                  min="1"
+                  placeholder="3600"
+                  value={timeout}
+                  onChange={e => setTimeout(e.target.value)}
+                />
+              </div>
+            </div>
+          )}
+
+          {error && (
+            <p className="text-sm text-destructive">{error}</p>
+          )}
+
+          <SheetFooter className="px-0">
+            <Button
+              type="button"
+              variant="outline"
+              onClick={() => { resetForm(); onOpenChange(false) }}
+            >
+              Cancel
+            </Button>
+            <Button
+              type="submit"
+              disabled={createSession.isPending || !name.trim()}
+            >
+              {createSession.isPending ? 'Creating...' : 'Create Session'}
+            </Button>
+          </SheetFooter>
+        </form>
+      </SheetContent>
+    </Sheet>
+  )
+}
diff --git a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/page.tsx b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/page.tsx
index 49efae8969..6afe14f6a6 100644
--- a/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/page.tsx
+++ b/components/ambient-ui/src/app/(dashboard)/[projectId]/sessions/page.tsx
@@ -2,8 +2,9 @@
 
 import { useState, useCallback } from 'react'
 import { useParams } from 'next/navigation'
-import { Monitor } from 'lucide-react'
+import { Monitor, Plus } from 'lucide-react'
 import { Input } from '@/components/ui/input'
+import { Button } from '@/components/ui/button'
 import { Skeleton } from '@/components/ui/skeleton'
 import { EmptyState } from '@/components/empty-state'
 import { useSessions } from '@/queries/use-sessions'
@@ -11,12 +12,14 @@ import { useAgentNames } from '@/queries/use-agents'
 import type { SessionPhase } from '@/domain/types'
 import { FleetTable } from './_components/fleet-table'
 import { FleetSummary } from './_components/fleet-summary'
+import { CreateSessionSheet } from './_components/create-session-sheet'
 
 export default function FleetPage() {
   const { projectId } = useParams<{ projectId: string }>()
   const [search, setSearch] = useState('')
   const [phaseFilter, setPhaseFilter] = useState<SessionPhase | null>(null)
   const [filteredCount, setFilteredCount] = useState<number | undefined>(undefined)
+  const [createOpen, setCreateOpen] = useState(false)
   const { data, isLoading, error } = useSessions(projectId)
   const { data: agentNames } = useAgentNames(projectId)
 
@@ -57,7 +60,14 @@ export default function FleetPage() {
           icon={Monitor}
           title="No sessions"
           description="This project has no agentic sessions yet. Create one to get started."
+          action={
+            <Button onClick={() => setCreateOpen(true)}>
+              <Plus className="mr-1.5 size-4" />
+              New Session
+            </Button>
+          }
         />
+        <CreateSessionSheet open={createOpen} onOpenChange={setCreateOpen} />
       </div>
     )
   }
@@ -66,12 +76,18 @@ export default function FleetPage() {
     <div className="space-y-4">
       <div className="flex items-center justify-between">
         <h1 className="text-xl font-semibold">Sessions</h1>
-        <Input
-          placeholder="Filter by name, agent, or model..."
-          value={search}
-          onChange={e => setSearch(e.target.value)}
-          className="max-w-xs"
-        />
+        <div className="flex items-center gap-2">
+          <Input
+            placeholder="Filter by name, agent, or model..."
+            value={search}
+            onChange={e => setSearch(e.target.value)}
+            className="max-w-xs"
+          />
+          <Button onClick={() => setCreateOpen(true)} size="sm">
+            <Plus className="mr-1.5 size-4" />
+            New Session
+          </Button>
+        </div>
       </div>
       <FleetSummary
         sessions={sessions}
@@ -86,6 +102,7 @@ export default function FleetPage() {
         phaseFilter={phaseFilter}
         onFilteredCountChange={handleFilteredCountChange}
       />
+      <CreateSessionSheet open={createOpen} onOpenChange={setCreateOpen} />
     </div>
   )
 }
diff --git a/components/ambient-ui/src/components/app-sidebar.tsx b/components/ambient-ui/src/components/app-sidebar.tsx
index 1e8d5e4daa..30ecb367f7 100644
--- a/components/ambient-ui/src/components/app-sidebar.tsx
+++ b/components/ambient-ui/src/components/app-sidebar.tsx
@@ -30,6 +30,7 @@ type AppSidebarProps = {
 
 const projectNavItems = [
   { label: 'Sessions', icon: Monitor, href: 'sessions' },
+  { label: 'Agents', icon: Bot, href: 'agents' },
 ] as const
 
 export function AppSidebar({ projectId }: AppSidebarProps) {
diff --git a/components/ambient-ui/src/domain/types.ts b/components/ambient-ui/src/domain/types.ts
index a2fdea308c..02ad7c7072 100644
--- a/components/ambient-ui/src/domain/types.ts
+++ b/components/ambient-ui/src/domain/types.ts
@@ -105,6 +105,35 @@ export type DomainSessionMessage = {
   createdAt: string
 }
 
+export type DomainAgent = {
+  id: string
+  name: string
+  displayName: string | null
+  description: string | null
+  model: string | null
+  ownerUserId: string | null
+  currentSessionId: string | null
+  projectId: string | null
+  prompt: string | null
+  repoUrl: string | null
+  workflowId: string | null
+  annotations: Record<string, string>
+  labels: Record<string, string>
+  createdAt: string
+  updatedAt: string
+}
+
+export type DomainSessionCreateRequest = {
+  name: string
+  projectId: string
+  agentId?: string
+  prompt?: string
+  model?: string
+  temperature?: number
+  maxTokens?: number
+  timeout?: number
+}
+
 export type FeedbackItem = {
   id: string
   type: 'element' | 'region'
diff --git a/components/ambient-ui/src/ports/agents.ts b/components/ambient-ui/src/ports/agents.ts
new file mode 100644
index 0000000000..4c429ef24e
--- /dev/null
+++ b/components/ambient-ui/src/ports/agents.ts
@@ -0,0 +1,6 @@
+import type { DomainAgent, ListParams, PaginatedResult } from '@/domain/types'
+
+export type AgentsPort = {
+  list: (projectId: string, params?: ListParams) => Promise<PaginatedResult<DomainAgent>>
+  get: (agentId: string) => Promise<DomainAgent>
+}
diff --git a/components/ambient-ui/src/ports/sessions.ts b/components/ambient-ui/src/ports/sessions.ts
index 397ec27d95..2bcf5f2c7d 100644
--- a/components/ambient-ui/src/ports/sessions.ts
+++ b/components/ambient-ui/src/ports/sessions.ts
@@ -1,8 +1,9 @@
-import type { DomainSession, ListParams, PaginatedResult } from '@/domain/types'
+import type { DomainSession, DomainSessionCreateRequest, ListParams, PaginatedResult } from '@/domain/types'
 
 export type SessionsPort = {
   list: (projectId: string, params?: ListParams) => Promise<PaginatedResult<DomainSession>>
   get: (sessionId: string) => Promise<DomainSession>
+  create: (request: DomainSessionCreateRequest) => Promise<DomainSession>
   stop: (sessionId: string) => Promise<void>
   start: (sessionId: string) => Promise<DomainSession>
   delete: (sessionId: string) => Promise<void>
diff --git a/components/ambient-ui/src/queries/query-keys.ts b/components/ambient-ui/src/queries/query-keys.ts
index 8d817dfbc7..b50b2e6b1f 100644
--- a/components/ambient-ui/src/queries/query-keys.ts
+++ b/components/ambient-ui/src/queries/query-keys.ts
@@ -21,6 +21,12 @@ export const queryKeys = {
   },
   agents: {
     all: ['agents'] as const,
+    lists: () => [...queryKeys.agents.all, 'list'] as const,
+    list: (projectId: string, params?: ListParams) =>
+      [...queryKeys.agents.lists(), projectId, params] as const,
+    details: () => [...queryKeys.agents.all, 'detail'] as const,
+    detail: (agentId: string) =>
+      [...queryKeys.agents.details(), agentId] as const,
     names: (projectId: string) =>
       [...queryKeys.agents.all, 'names', projectId] as const,
   },
diff --git a/components/ambient-ui/src/queries/use-agents.ts b/components/ambient-ui/src/queries/use-agents.ts
index 1cb4b543e9..d0a7e48131 100644
--- a/components/ambient-ui/src/queries/use-agents.ts
+++ b/components/ambient-ui/src/queries/use-agents.ts
@@ -1,6 +1,9 @@
 'use client'
 
 import { useQuery } from '@tanstack/react-query'
+import type { AgentsPort } from '@/ports/agents'
+import type { ListParams } from '@/domain/types'
+import { createAgentsAdapter } from '@/adapters/sdk-agents'
 import { queryKeys } from './query-keys'
 
 type AgentNameEntry = {
@@ -9,6 +12,40 @@ type AgentNameEntry = {
   displayName: string | null
 }
 
+let defaultPort: AgentsPort | null = null
+
+function getDefaultPort(): AgentsPort {
+  if (!defaultPort) {
+    defaultPort = createAgentsAdapter()
+  }
+  return defaultPort
+}
+
+export function useAgents(
+  projectId: string,
+  params?: ListParams,
+  port?: AgentsPort,
+) {
+  const adapter = port ?? getDefaultPort()
+  return useQuery({
+    queryKey: queryKeys.agents.list(projectId, params),
+    queryFn: () => adapter.list(projectId, params),
+    enabled: !!projectId,
+  })
+}
+
+export function useAgent(
+  agentId: string,
+  port?: AgentsPort,
+) {
+  const adapter = port ?? getDefaultPort()
+  return useQuery({
+    queryKey: queryKeys.agents.detail(agentId),
+    queryFn: () => adapter.get(agentId),
+    enabled: !!agentId,
+  })
+}
+
 export function useAgentNames(projectId: string) {
   return useQuery({
     queryKey: queryKeys.agents.names(projectId),
diff --git a/components/ambient-ui/src/queries/use-sessions.ts b/components/ambient-ui/src/queries/use-sessions.ts
index baf1e205fb..d332861c46 100644
--- a/components/ambient-ui/src/queries/use-sessions.ts
+++ b/components/ambient-ui/src/queries/use-sessions.ts
@@ -2,7 +2,7 @@
 
 import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query'
 import type { SessionsPort } from '@/ports/sessions'
-import type { DomainSession, ListParams, SessionPhase } from '@/domain/types'
+import type { DomainSession, DomainSessionCreateRequest, ListParams, SessionPhase } from '@/domain/types'
 import { createSessionsAdapter } from '@/adapters/sdk-sessions'
 import { queryKeys } from './query-keys'
 
@@ -125,3 +125,15 @@ export function useDeleteSession(port?: SessionsPort) {
     },
   })
 }
+
+export function useCreateSession(port?: SessionsPort) {
+  const queryClient = useQueryClient()
+  const adapter = port ?? getDefaultPort()
+
+  return useMutation({
+    mutationFn: (request: DomainSessionCreateRequest) => adapter.create(request),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: queryKeys.sessions.all })
+    },
+  })
+}

From 510bbf8124b310b44d24bc7ebf4b4b18026fc20f Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Wed, 3 Jun 2026 13:22:31 -0400
Subject: [PATCH 4/5] fix(ambient-ui): use project-scoped AgentAPI instances

AgentAPI.basePath() requires config.project to build the URL
/projects/{project}/agents. Create a per-call AgentAPI with the
project from the request instead of a singleton without project.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .../ambient-ui/src/adapters/sdk-agents.ts     | 29 +++++++++----------
 .../ambient-ui/src/adapters/sdk-client.ts     | 11 +------
 2 files changed, 15 insertions(+), 25 deletions(-)

diff --git a/components/ambient-ui/src/adapters/sdk-agents.ts b/components/ambient-ui/src/adapters/sdk-agents.ts
index 0a95c06b4d..8b2c0cdfa7 100644
--- a/components/ambient-ui/src/adapters/sdk-agents.ts
+++ b/components/ambient-ui/src/adapters/sdk-agents.ts
@@ -1,36 +1,38 @@
-import type { AgentAPI } from 'ambient-sdk'
+import { AgentAPI } from 'ambient-sdk'
 import type { AgentsPort } from '@/ports/agents'
 import type { DomainAgent, ListParams, PaginatedResult } from '@/domain/types'
 import { mapSdkAgentToDomain } from './mappers'
-import { getAgentAPI } from './sdk-client'
+import { getConfig } from './sdk-client'
 
 function sanitizeSearch(value: string): string {
   return value.replace(/['"%;\\]/g, '')
 }
 
-function buildSdkListOptions(projectId: string, params?: ListParams) {
-  const search = params?.search
-    ? `project_id = '${sanitizeSearch(projectId)}' and name like '%${sanitizeSearch(params.search)}%'`
-    : `project_id = '${sanitizeSearch(projectId)}'`
+function getProjectScopedAPI(projectId: string): AgentAPI {
+  return new AgentAPI({ ...getConfig(), project: projectId })
+}
 
+function buildSdkListOptions(params?: ListParams) {
   return {
     page: params?.page ?? 1,
     size: params?.size ?? 20,
-    search,
+    search: params?.search
+      ? `name like '%${sanitizeSearch(params.search)}%'`
+      : undefined,
     orderBy: params?.orderBy,
   }
 }
 
-function createSdkAgentsAdapter(api: AgentAPI): AgentsPort {
+export function createAgentsAdapter(): AgentsPort {
   return {
     async list(projectId: string, params?: ListParams): Promise<PaginatedResult<DomainAgent>> {
-      const opts = buildSdkListOptions(projectId, params)
+      const api = getProjectScopedAPI(projectId)
+      const opts = buildSdkListOptions(params)
       const result = await api.list(opts)
-      const items = result.items.map(mapSdkAgentToDomain)
       const page = opts.page
       const size = opts.size
       return {
-        items,
+        items: result.items.map(mapSdkAgentToDomain),
         total: result.total,
         page,
         size,
@@ -39,12 +41,9 @@ function createSdkAgentsAdapter(api: AgentAPI): AgentsPort {
     },
 
     async get(agentId: string): Promise<DomainAgent> {
+      const api = new AgentAPI({ ...getConfig(), project: '_' })
       const agent = await api.get(agentId)
       return mapSdkAgentToDomain(agent)
     },
   }
 }
-
-export function createAgentsAdapter(api?: AgentAPI): AgentsPort {
-  return createSdkAgentsAdapter(api ?? getAgentAPI())
-}
diff --git a/components/ambient-ui/src/adapters/sdk-client.ts b/components/ambient-ui/src/adapters/sdk-client.ts
index f94d7bee3b..bc4d740393 100644
--- a/components/ambient-ui/src/adapters/sdk-client.ts
+++ b/components/ambient-ui/src/adapters/sdk-client.ts
@@ -1,5 +1,5 @@
 import type { AmbientClientConfig } from 'ambient-sdk'
-import { SessionAPI, ProjectAPI, AgentAPI } from 'ambient-sdk'
+import { SessionAPI, ProjectAPI } from 'ambient-sdk'
 
 // BFF proxy config: empty baseUrl produces relative URLs like /api/ambient/v1/sessions
 // which hit the Next.js BFF proxy. No token needed — the proxy adds it server-side.
@@ -13,8 +13,6 @@ const bffConfig: AmbientClientConfig = {
 
 let sessions: SessionAPI | null = null
 let projects: ProjectAPI | null = null
-let agents: AgentAPI | null = null
-
 export function getSessionAPI(): SessionAPI {
   if (!sessions) {
     sessions = new SessionAPI(bffConfig)
@@ -29,13 +27,6 @@ export function getProjectAPI(): ProjectAPI {
   return projects
 }
 
-export function getAgentAPI(): AgentAPI {
-  if (!agents) {
-    agents = new AgentAPI(bffConfig)
-  }
-  return agents
-}
-
 export function getConfig(): AmbientClientConfig {
   return bffConfig
 }

From d5e4d0e18241383a4c364e30f62ed15c7a568f38 Mon Sep 17 00:00:00 2001
From: John Sell <jsell@redhat.com>
Date: Wed, 3 Jun 2026 13:44:39 -0400
Subject: [PATCH 5/5] spec(ambient-ui): reframe as SDLC ops dashboard with
 agent authoring

Amend the ambient-ui spec to reflect the product's dual-persona vision:
operations monitoring (high-frequency, work-outcome-centric) and agent
authoring (low-frequency, prototyping workbench for GitOps codification).

Key changes:
- Dashboard as default landing page with attention queue, active work
  cards, and recent activity feed
- Sidebar restructured into Operate/Build/Configure groups
- Work view replaces Issues view (aggregated SDLC artifacts)
- Agent detail promoted from Sheet to full page with tabs: Overview
  (editable), Sessions (test history), Config (YAML export)
- Agent CRUD and lifecycle badges (Draft vs GitOps)
- needs-input annotation for agent-flagged human attention
- Sessions table gains Work Item and Review Status columns
- Fleet renamed to Sessions everywhere for consistency
- Migration section: route stability, phased rollout, tab param compat

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 specs/ambient-ui/ambient-ui.spec.md | 354 ++++++++++++++++++++++------
 1 file changed, 285 insertions(+), 69 deletions(-)

diff --git a/specs/ambient-ui/ambient-ui.spec.md b/specs/ambient-ui/ambient-ui.spec.md
index a691d08112..5be29ec63e 100644
--- a/specs/ambient-ui/ambient-ui.spec.md
+++ b/specs/ambient-ui/ambient-ui.spec.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-The Ambient UI is the platform's operations console for monitoring and managing agent workloads. It treats agents as execution engines — not chat partners — and provides project-scoped observability, credential management, schedule monitoring, and annotation-driven extensibility. It replaces the existing frontend over time but coexists functionally as a separate component during migration.
+The Ambient UI is the platform's agentic SDLC operations dashboard. It serves two primary workflows: **operations monitoring** (high-frequency, low-duration — "what needs my attention?") and **agent authoring** (low-frequency, high-duration — building, testing, and iterating on agent definitions before codifying them for GitOps). The UI is organized around work outcomes (Jira tickets, PRs, reviews, incidents) rather than infrastructure primitives. Sessions and agents are the execution layer — accessible but secondary to the work they produce. It replaces the existing frontend over time but coexists functionally as a separate component during migration.
 
 The Ambient UI interacts exclusively with the ambient-api-server API via the generated TypeScript SDK. It has no dependency on the legacy backend.
 
@@ -125,7 +125,7 @@ The Ambient UI SHALL scope all operational views to a single active project. The
 #### Scenario: Project-scoped views
 
 - GIVEN a user selects project "platform"
-- WHEN they navigate to Fleet, Agents, Schedules, Issues, or Settings
+- WHEN they navigate to Sessions, Agents, Schedules, Work, or Settings
 - THEN all data displayed is scoped to the "platform" project
 - AND the active project name is visible in a breadcrumb on every view
 
@@ -138,23 +138,28 @@ The Ambient UI SHALL scope all operational views to a single active project. The
 
 ### Requirement: Sidebar Navigation
 
-The Ambient UI sidebar SHALL contain two sections separated by a visual divider:
+The Ambient UI sidebar SHALL contain three groups separated by visual dividers and group labels:
 
-**Project-scoped** (requires active project):
-- Fleet (session monitoring)
-- Agents (agent registry)
+**Operate** (project-scoped, high-frequency monitoring):
+- Dashboard (attention queue + active work + recent completions — default landing page)
+- Work (aggregated SDLC artifacts: PRs, tickets, MRs, incidents)
+- Sessions (session monitoring, route: `/sessions`)
 - Schedules (cron management)
-- Issues (aggregated integration references)
-- Settings (project configuration, permissions, API keys, feature flags)
 
-**Global**:
+**Build** (project-scoped, agent authoring and configuration):
+- Agents (agent registry, authoring workbench, test sessions)
+
+**Configure** (cross-cutting):
 - Credentials (credential management and project/agent binding)
+- Settings (project configuration, permissions, API keys, feature flags)
+
+The Dashboard sidebar item SHALL display a badge count of items requiring human attention. The group labels ("Operate", "Build", "Configure") SHALL be rendered as muted section headers, not clickable items.
 
 #### Scenario: Navigation breadcrumbs
 
 - GIVEN a user is viewing a session detail in the "platform" project
 - WHEN the breadcrumb renders
-- THEN it displays: `platform > Fleet > session-name`
+- THEN it displays: `platform > Sessions > session-name`
 - AND each segment is clickable to navigate to that level
 
 ### Requirement: Keyboard Navigation
@@ -163,7 +168,7 @@ The Ambient UI SHALL support keyboard-first navigation for power users.
 
 #### Scenario: Table navigation
 
-- GIVEN a user is viewing the Fleet table
+- GIVEN a user is viewing the Sessions table
 - WHEN they press `j` or `k`
 - THEN the selection moves down or up through table rows
 - AND `Enter` opens the selected session's detail view
@@ -185,29 +190,120 @@ Global search SHALL be implemented client-side by querying multiple API endpoint
 
 ---
 
-## Fleet View (Session Monitoring)
+## Dashboard (Default Landing Page)
+
+### Requirement: Attention-First Landing
+
+The Dashboard SHALL be the default landing page when a user selects a project. It SHALL answer three questions in priority order: "What needs my attention?", "What is actively being worked on?", and "What completed recently?"
+
+#### Scenario: Attention banner
+
+- GIVEN sessions exist with `phase: Failed` or annotations `ambient-code.io/review/status: "needs-review"` or `ambient-code.io/agent/needs-input`
+- WHEN the Dashboard renders
+- THEN an attention banner appears at the top showing counts of items requiring human action
+- AND each item is a clickable link to the relevant session or work item
+- AND the sidebar "Dashboard" item displays a badge with the total attention count
+
+#### Scenario: Nothing needs attention
+
+- GIVEN no sessions are failed, no reviews are pending, no agents need input
+- WHEN the Dashboard renders
+- THEN the attention banner is hidden
+- AND the sidebar badge is not displayed
+
+#### Scenario: Active work section
+
+- GIVEN sessions with integration annotations (`ambient-code.io/jira/issue`, `ambient-code.io/github/pr`)
+- WHEN the Dashboard renders
+- THEN it displays active work items as cards, grouped by integration reference
+- AND each card shows the work item identifier (Jira key, PR number) as the primary heading
+- AND session/agent information appears as secondary metadata within the card
+
+#### Scenario: Sessions without integration annotations
+
+- GIVEN sessions with no integration annotations
+- WHEN the Dashboard renders
+- THEN they appear as session cards with the session name as the primary identifier
+- AND they are visually distinct from work-item-linked cards (lighter weight, no colored border)
+
+#### Scenario: Recent activity feed
+
+- GIVEN completed sessions exist
+- WHEN the Dashboard renders
+- THEN a compact timeline shows the last N completed work items with reference, outcome, duration, and cost
+
+### Requirement: Needs-Input Annotation
+
+Agents SHALL be able to signal that they are blocked on human input by writing the annotation `ambient-code.io/agent/needs-input`. The value SHALL describe the type of input needed (e.g., `"approval"`, `"clarification"`, `"credentials"`, `"review"`).
+
+Sessions with this annotation SHALL surface in the Dashboard attention banner and SHALL display a distinct, non-muted badge in the Sessions table — at least as prominent as the Phase badge.
+
+#### Scenario: Agent flags need for input
+
+- GIVEN a Running session where the agent writes `ambient-code.io/agent/needs-input: "approval"`
+- WHEN the Dashboard renders
+- THEN the attention banner includes this session with label "Waiting for approval"
+- AND the Sessions table shows an amber "Needs Input" badge on this session's row
+
+---
+
+## Work View (SDLC Artifacts)
 
-### Requirement: Session Fleet Table
+### Requirement: Aggregated Work Items
 
-The Fleet view SHALL display a table of all sessions in the active project. Each row SHALL show operational data answering: "Does this session need my attention?"
+The Work view SHALL aggregate all registered integration annotations (`ambient-code.io/jira/issue`, `ambient-code.io/github/pr`, `ambient-code.io/gitlab/mr`, `ambient-code.io/oncall/incident`) across sessions in the active project.
 
-The table SHALL display: Phase (with activity indicator), Session Name, Agent, Duration, Model, Last Activity, and Cost.
+The view SHALL display work items as first-class objects, with sessions shown as subordinate detail. It SHALL support tabs for each artifact type (Pull Requests, Tickets, Merge Requests, Incidents), with counts on each tab.
+
+#### Scenario: Work view rendering
+
+- GIVEN sessions in a project with various integration annotations
+- WHEN the Work view renders
+- THEN it displays tabbed tables: Pull Requests, Tickets, Merge Requests, Incidents
+- AND each tab label includes a count of items
+- AND each row shows the reference, enriched details (if available), linked sessions, agent, and status
+
+#### Scenario: Work item attention grouping
+
+- GIVEN work items in various states
+- WHEN the Work view renders
+- THEN items are grouped within each tab: "Needs Attention" (needs-review, failed, changes-requested) at top, "In Progress" (linked to running sessions) in middle, "Done" (completed, merged) at bottom — collapsed by default
+
+#### Scenario: Work item status filtering
+
+- GIVEN the Work view with items in various statuses
+- WHEN the user selects a status filter
+- THEN only matching items are displayed
+
+Status filtering requires enrichment data. When enrichment is unavailable, the status filter SHALL be hidden.
+
+---
+
+## Sessions View (Session Monitoring)
+
+### Requirement: Session Table
+
+The Sessions view SHALL display a table of all sessions in the active project. Each row SHALL show operational data answering: "Does this session need my attention?"
+
+The table SHALL display: Phase (with activity indicator), Work Item (primary integration annotation as chip), Review Status (from `ambient-code.io/review/status`), Session Name, Agent, Duration, Last Activity, Cost, and Chat action.
+
+The Work Item column SHALL show the first matching integration annotation in priority order: Jira issue, then GitHub PR, then GitLab MR, then Gerrit change. Sessions without integration annotations display "—". The Review Status column SHALL render as a colored badge: `needs-review` = amber, `approved` = green, `changes-requested` = red.
 
 Phase SHALL be the single status indicator. There SHALL NOT be a separate "Status" column. When a session is Running and the agent is actively working, the Phase badge SHALL display a pulsing indicator.
 
 Cost is annotation-driven: the UI reads the `ambient-code.io/cost/estimate` annotation value. Sessions without this annotation display "—" in the Cost column.
 
-#### Scenario: Fleet table rendering
+#### Scenario: Sessions table rendering
 
 - GIVEN a project with 15 sessions in various phases
-- WHEN the Fleet view renders
+- WHEN the Sessions view renders
 - THEN each session appears as a single-line row
 - AND the Phase badge shows: Running (green), Completed (blue), Failed (red), Stopped (gray), Pending (amber)
 - AND Running sessions with active agents show a pulsing dot on the Phase badge
 
-#### Scenario: Fleet filtering
+#### Scenario: Sessions filtering
 
-- GIVEN the Fleet table is displayed
+- GIVEN the Sessions table is displayed
 - WHEN the user types in the search field or selects a phase filter
 - THEN the table filters to matching sessions
 - AND summary stats update to reflect the filtered set
@@ -215,28 +311,28 @@ Cost is annotation-driven: the UI reads the `ambient-code.io/cost/estimate` anno
 #### Scenario: Empty fleet
 
 - GIVEN a project with no sessions
-- WHEN the Fleet view renders
+- WHEN the Sessions view renders
 - THEN a centered empty state is displayed with an explanation and suggested action
 
 ### Requirement: Registered Annotation Indicators
 
-Sessions with registered annotations SHALL display compact visual indicators in the Fleet table. Indicators SHALL appear as small, muted icons to the right of the session name — never as inline chips that break the table's horizontal scan line.
+Sessions with registered annotations SHALL display compact visual indicators in the Sessions table. Indicators SHALL appear as small, muted icons to the right of the session name — never as inline chips that break the table's horizontal scan line.
 
-Only annotations with registered keys SHALL produce indicators. Unregistered annotations SHALL NOT produce any visual element in the Fleet table or any other operational view.
+Only annotations with registered keys SHALL produce indicators. Unregistered annotations SHALL NOT produce any visual element in the Sessions table or any other operational view.
 
 Full annotation details SHALL be available on hover (as a popover) or in the session detail view.
 
 #### Scenario: Annotation indicators in fleet
 
 - GIVEN a session with annotations `ambient-code.io/jira/issue: "HYPERFLEET-234"` and `ambient-code.io/github/pr: "org/repo#1847"`
-- WHEN the Fleet table renders
+- WHEN the Sessions table renders
 - THEN the session row shows small muted icons (Jira icon, PR icon) next to the session name
 - AND hovering over the session name reveals a popover with full annotation details
 
 #### Scenario: Unregistered annotation ignored
 
 - GIVEN a session with annotation `ambient-code.io/desired-phase: "Running"`
-- WHEN the session appears in the Fleet table or any operational view
+- WHEN the session appears in the Sessions table or any operational view
 - THEN no visual element is produced for that annotation
 
 ### Requirement: Virtual Folder Tree (ambient-code.io/ui/path)
@@ -250,11 +346,11 @@ The annotation value is a forward-slash-delimited string (e.g., `"backend/auth"`
 - GIVEN sessions with `ambient-code.io/ui/path` annotations like `"backend/auth"`, `"backend/testing"`, `"infra/networking"`
 - WHEN the user toggles the folder tree
 - THEN a tree panel appears showing the parsed hierarchy with session counts per node
-- AND clicking a folder filters the Fleet table to sessions with that path prefix
+- AND clicking a folder filters the Sessions table to sessions with that path prefix
 
 ### Requirement: Bulk Session Operations
 
-The Fleet table SHALL support selecting multiple sessions and performing bulk operations.
+The Sessions table SHALL support selecting multiple sessions and performing bulk operations.
 
 #### Scenario: Bulk stop
 
@@ -265,7 +361,7 @@ The Fleet table SHALL support selecting multiple sessions and performing bulk op
 
 ### Requirement: Session Detail (Workload Inspector)
 
-Clicking a session in the Fleet table SHALL open a detail view with tabbed content. The detail view SHALL include a sticky action bar with session lifecycle controls.
+Clicking a session in the Sessions table SHALL open a detail view with tabbed content. The detail view SHALL include a sticky action bar with session lifecycle controls.
 
 **Action bar:** Stop (when Running), Restart (when terminal), Clone, Export, Delete. Destructive actions (Stop, Delete) SHALL require confirmation.
 
@@ -380,38 +476,132 @@ Any view that displays a session (fleet table row, session detail header, chat t
 
 ### Requirement: Timestamp Toggle
 
-The Fleet table's "Last Activity" column SHALL support toggling between relative time ("12s ago") and absolute time ("10:42:18 AM EST").
+The Sessions table's "Last Activity" column SHALL support toggling between relative time ("12s ago") and absolute time ("10:42:18 AM EST").
 
 #### Scenario: Timestamp format toggle
 
-- GIVEN the Fleet table displays relative timestamps
+- GIVEN the Sessions table displays relative timestamps
 - WHEN the user clicks the toggle on the column header
 - THEN all timestamps switch to absolute format with explicit timezone
 - AND the preference persists for the session
 
 ---
 
-## Agents View
+## Agents View (Authoring Workbench)
+
+The Agents view serves two personas: operators who need a quick registry glance, and agent authors who build, test, and iterate on agent definitions before codifying them for GitOps management via `acpctl apply`.
 
 ### Requirement: Agent Registry Table
 
-The Agents view SHALL display a table of agents in the active project. Clicking an agent row SHALL open a right-side detail panel.
+The Agents view SHALL display a table of agents in the active project. The table SHALL display: Name, Source (prototype/production badge), Model, Owner, Current Session (clickable), Last Active.
+
+Clicking an agent row SHALL navigate to the agent detail page.
+
+The page SHALL include a "+ New Agent" button for creating agents directly in the UI.
+
+#### Scenario: Agent table rendering
+
+- GIVEN a project with 5 agents
+- WHEN the Agents view renders
+- THEN each agent appears as a row with name, source badge, model, owner, current session link, and last active timestamp
+- AND prototype agents display a "Draft" badge
+- AND production agents (managed via GitOps) display a "GitOps" badge
+
+#### Scenario: Empty agents state
+
+- GIVEN a project with no agents
+- WHEN the Agents view renders
+- THEN an empty state is displayed with a "Create Agent" action button
 
-The table SHALL display: Name, Model, Owner, Current Session (clickable), Inbox (unread count), Last Active.
+### Requirement: Agent Detail Page
 
-There SHALL be only ONE interaction pattern for agent rows: clicking anywhere on the row opens the sidebar panel.
+Clicking an agent in the registry table SHALL navigate to a dedicated agent detail page at `/{projectId}/agents/{agentId}`. The detail page SHALL use a tabbed layout with three tabs: Overview, Sessions, Config.
 
-#### Scenario: Agent sidebar panel
+The page header SHALL display the agent name, lifecycle badge (Draft/GitOps), and action buttons: "Run Test Session" and "Export YAML".
 
-- GIVEN the user clicks an agent row
-- WHEN the sidebar panel slides in from the right
-- THEN it displays: Quick Info (model, owner, current session link, last active), Annotations (registered annotations only), Inbox messages (last 3-5 with sender, preview, timestamp), Recent Sessions (clickable, navigate to workload inspector), Prompt Preview (truncated, expandable), Chat section (collapsible, for direct agent interaction)
+#### Scenario: Overview tab (authoring surface)
 
-#### Scenario: Agent session navigation
+- GIVEN an agent detail page for a Draft agent
+- WHEN the Overview tab renders
+- THEN it displays editable fields: prompt (textarea), model (select), repository URL, description
+- AND a "Save Changes" action persists edits via the API
+- AND registered annotations render with icons and labels
 
-- GIVEN the agent sidebar shows "Current Session: pr-review-auth-42"
-- WHEN the user clicks the session name
-- THEN the view navigates to the Workload Inspector for that session
+#### Scenario: Overview tab (GitOps-managed agent)
+
+- GIVEN an agent detail page for a GitOps-managed agent
+- WHEN the Overview tab renders
+- THEN fields are read-only with a banner: "This agent is managed via GitOps. Edits here will not persist."
+- AND the "Run Test Session" action remains available
+
+#### Scenario: Sessions tab (test history)
+
+- GIVEN an agent with 10 past sessions
+- WHEN the Sessions tab renders
+- THEN it displays a session table filtered to sessions for this agent
+- AND each row shows phase, name, duration, cost, and created timestamp
+- AND clicking a session navigates to the session detail page
+
+#### Scenario: Config tab (YAML export)
+
+- GIVEN an agent detail page
+- WHEN the Config tab renders
+- THEN it displays a YAML preview of the agent definition (the format consumed by `acpctl apply`)
+- AND "Copy to Clipboard" and "Download YAML" actions are available
+
+#### Scenario: Run Test Session
+
+- GIVEN the user clicks "Run Test Session" on an agent detail page
+- WHEN the create session sheet opens
+- THEN the agent is pre-selected and the form is pre-filled with the agent's model, prompt, and repos
+- AND the user can override any field before submitting
+- AND on success, the new session appears in the agent's Sessions tab
+
+### Requirement: Agent Lifecycle Badge
+
+Agents SHALL display a lifecycle badge indicating whether they are managed in the UI (prototype/draft) or via GitOps (production). The badge SHALL be derived from the `ambient-code.io/managed-by` annotation:
+
+- `ambient-code.io/managed-by: "gitops"` → "GitOps" badge (muted, with git-branch icon)
+- No annotation or any other value → "Draft" badge (default)
+
+#### Scenario: Prototype agent
+
+- GIVEN an agent without `ambient-code.io/managed-by` annotation
+- WHEN it appears in the registry table or detail page
+- THEN it displays a "Draft" badge
+- AND all fields are editable in the Overview tab
+
+#### Scenario: Production agent
+
+- GIVEN an agent with `ambient-code.io/managed-by: "gitops"`
+- WHEN it appears in the registry table or detail page
+- THEN it displays a "GitOps" badge
+- AND fields are read-only in the Overview tab
+
+### Requirement: Agent CRUD
+
+The Agents view SHALL support creating, editing, and deleting agents.
+
+#### Scenario: Create agent
+
+- GIVEN the user clicks "+ New Agent"
+- WHEN the creation form opens
+- THEN it displays fields: name (required), display name, model, prompt, repository URL, description
+- AND submitting creates the agent via the API
+
+#### Scenario: Edit agent
+
+- GIVEN the user edits fields on a Draft agent's Overview tab
+- WHEN they click "Save Changes"
+- THEN the agent is updated via the API
+- AND a success notification confirms the save
+
+#### Scenario: Delete agent
+
+- GIVEN the user clicks "Delete" on an agent
+- WHEN confirmation is provided
+- THEN the agent is deleted via the API
+- AND the user is navigated back to the agents list
 
 ---
 
@@ -526,7 +716,7 @@ All registered annotation keys SHALL use the `ambient-code.io/` namespace prefix
 
 | Key | Example Value | UI Behavior |
 |-----|---------------|-------------|
-| `ambient-code.io/ui/path` | `"backend/auth"` | Virtual folder tree grouping in Fleet view |
+| `ambient-code.io/ui/path` | `"backend/auth"` | Virtual folder tree grouping in Sessions view |
 | `ambient-code.io/ui/pinned` | `"true"` | Pin icon next to session name; sorts to top |
 | `ambient-code.io/ui/priority` | `"high"` | Colored priority icon (red/amber/gray) left of session name |
 | `ambient-code.io/ui/tag` | `"docs"` | Muted tag chip in annotation popover |
@@ -542,9 +732,11 @@ All registered annotation keys SHALL use the `ambient-code.io/` namespace prefix
 | `ambient-code.io/review/status` | `"needs-review"` | Status badge (amber/green/red). This is external review metadata, distinct from session phase. |
 | `ambient-code.io/review/reviewer` | `"@mchen"` | Reviewer reference |
 | `ambient-code.io/triggered-by` | `"schedule/nightly"` | Provenance indicator with contextual icon |
-| `ambient-code.io/cost/estimate` | `"$4.12"` | Muted cost display in Fleet table |
+| `ambient-code.io/cost/estimate` | `"$4.12"` | Muted cost display in Sessions table |
 | `ambient-code.io/oncall/incident` | `"INC-003"` | Red incident chip with alert icon |
 | `ambient-code.io/parent-agent` | `"orchestrator"` | Agent delegation reference |
+| `ambient-code.io/agent/needs-input` | `"approval"` | Amber attention badge; surfaces in Dashboard attention queue. Values: `approval`, `clarification`, `credentials`, `review` |
+| `ambient-code.io/managed-by` | `"gitops"` | Agent lifecycle badge: "GitOps" (managed externally) vs "Draft" (UI-managed prototype) |
 
 #### Scenario: Registered annotation rendered
 
@@ -556,7 +748,7 @@ All registered annotation keys SHALL use the `ambient-code.io/` namespace prefix
 #### Scenario: Unregistered annotation not rendered
 
 - GIVEN a session with annotation `ambient-code.io/desired-phase: "Running"`
-- WHEN the session appears in the Fleet table or any operational view
+- WHEN the session appears in the Sessions table or any operational view
 - THEN no visual element is produced for that annotation
 - AND the annotation is visible ONLY in the raw annotations table in the Details tab
 
@@ -595,26 +787,7 @@ The enrichment endpoint specification is out of scope for this document and SHAL
 
 ## Issues View
 
-### Requirement: Aggregated Integration References
-
-The Issues view SHALL aggregate all registered integration annotations (`ambient-code.io/jira/issue`, `ambient-code.io/github/pr`, `ambient-code.io/gitlab/mr`) across sessions in the active project into dedicated tables.
-
-The view SHALL support search and status filtering.
-
-#### Scenario: Issues view rendering
-
-- GIVEN sessions in a project with various integration annotations
-- WHEN the Issues view renders
-- THEN it displays separate tables for Jira Issues, Pull Requests, and Merge Requests
-- AND each row shows the reference, enriched details (if available), linked sessions, and agent
-
-#### Scenario: Issue status filtering
-
-- GIVEN the Issues view with Jira issues in various statuses
-- WHEN the user selects "In Progress" from the status filter
-- THEN only Jira issues with "In Progress" status are displayed
-
-Status filtering requires enrichment data. When enrichment is unavailable, the status filter SHALL be hidden.
+**Note:** The Issues view has been superseded by the Work View (see "Work View (SDLC Artifacts)" section above). The Work view provides the same aggregated integration references with richer grouping by attention-need and tabbed artifact types. The sidebar label is "Work" rather than "Issues" to reflect the broader scope (all SDLC artifacts, not just bug-tracking items).
 
 ---
 
@@ -732,12 +905,12 @@ The Ambient UI SHALL use Server-Sent Events as the primary mechanism for real-ti
 - THEN the UI receives them via `GET /api/ambient/v1/sessions/{id}/events` SSE stream
 - AND renders them in real-time without polling
 
-#### Scenario: Fleet table polling
+#### Scenario: Sessions table polling
 
-- GIVEN a user is viewing the Fleet table
+- GIVEN a user is viewing the Sessions table
 - WHEN a session's phase changes
 - THEN the UI detects the change via periodic polling of `GET /api/ambient/v1/sessions` (5s interval)
-- AND the Fleet table row updates on the next poll cycle
+- AND the Sessions table row updates on the next poll cycle
 
 No list-watch endpoint exists for sessions today. Polling is the interim mechanism.
 
@@ -869,6 +1042,44 @@ The default connection uses the BFF's configured API server URL and the JWT from
 
 ---
 
+## Migration
+
+### URL Routes
+
+All existing routes SHALL remain stable. The sidebar label changes do NOT imply URL path changes:
+
+| Sidebar Label | Route Path | Status |
+|---------------|-----------|--------|
+| Dashboard | `/{projectId}` (root project route) | New — becomes default landing |
+| Work | `/{projectId}/work` | New |
+| Sessions | `/{projectId}/sessions` | Existing — unchanged |
+| Agents | `/{projectId}/agents` | Existing — unchanged |
+| Agents Detail | `/{projectId}/agents/{agentId}` | New — replaces Sheet with page |
+| Schedules | `/{projectId}/schedules` | New |
+| Credentials | `/credentials` | New (global) |
+| Settings | `/{projectId}/settings` | New |
+
+When the Dashboard page ships, the project picker and project selector SHALL navigate to `/{projectId}` instead of `/{projectId}/sessions`. Direct navigation to `/{projectId}/sessions` SHALL continue to work.
+
+### Session Detail Tabs
+
+Tab URL param values SHALL remain stable: `?tab=overview`, `?tab=logs`, `?tab=resources`, `?tab=config`, `?tab=chat`. These names match the current implementation and SHALL NOT change.
+
+### Agent Detail: Sheet to Page Migration
+
+The existing `AgentDetailPanel` Sheet component SHALL be replaced by a full page at `/{projectId}/agents/{agentId}`. The Sheet component MAY be retained as a lightweight preview when clicking agent names in the Sessions table, but the primary agent detail surface is the page.
+
+### Phased Rollout
+
+New sidebar items SHALL be added incrementally as their pages are implemented. Items SHALL NOT appear in the sidebar until their page exists (no disabled "Coming soon" stubs). Recommended order:
+
+1. Dashboard page + sidebar restructure (Operate/Build/Configure groups)
+2. Agent detail page (replaces Sheet)
+3. Work view
+4. Schedules, Credentials, Settings
+
+---
+
 ## API Dependencies
 
 This section documents API endpoints and capabilities that this spec depends on but which do not yet exist. These are not requirements of this spec — they are requirements on other specs.
@@ -878,7 +1089,7 @@ This section documents API endpoints and capabilities that this spec depends on
 | Annotation enrichment endpoint (resolve `ambient-code.io/jira/issue` etc. against bound credentials) | Annotation enrichment, Issues view status filtering | Not yet specified | Render raw annotation values as clickable chips |
 | `GET /credentials/{cred_id}/role_bindings` (scoped query) | Credential binding display | Planned, not implemented | Use generic `GET /role_bindings` filtered by `credential_id` |
 | Cross-resource search endpoint | Global search | Not planned | Client-side aggregation across multiple list endpoints |
-| Session list-watch endpoint (`GET /sessions?watch=true`) | Fleet real-time phase updates | Not available | Poll `GET /sessions` at 5s interval |
+| Session list-watch endpoint (`GET /sessions?watch=true`) | Sessions real-time phase updates | Not available | Poll `GET /sessions` at 5s interval |
 | SSE availability guarantee (runner reachability) | Logs/Chat real-time streaming | Runner returns 502 when unreachable | Fall back to polling `GET /sessions/{id}/messages` |
 
 ## Design Decisions
@@ -893,6 +1104,11 @@ This section documents API endpoints and capabilities that this spec depends on
 | Cost as annotation, not API field | Cost is agent-computed and written as `ambient-code.io/cost/estimate`. No API-level cost computation. |
 | Tool metrics computed client-side | The API stores raw SessionMessages. Aggregating tool call stats is a UI concern, not an API concern. |
 | SSE for sessions, polling for rest | Sessions have real-time SSE streams. Credentials, schedules, and agents change infrequently — polling is sufficient and simpler. |
-| Single interaction pattern per entity | Agent rows: sidebar only (no expand + sidebar). Fleet rows: detail view only. Reduces cognitive load per Krug's "Don't Make Me Think." |
+| Single interaction pattern per entity | Agent rows: navigate to detail page. Session rows: navigate to detail page. Reduces cognitive load per Krug's "Don't Make Me Think." |
 | Chat sidebar is app-level, not tab-level | The sidebar lives in the root layout, not the session detail page. This enables cross-page persistence. State is managed via React context at the dashboard layout level. |
 | Feedback delivery is context-dependent | Running session → session message (immediate). Stopped session → agent inbox (queued). Matches the platform's existing message model. |
+| Work-centric IA, not infrastructure-centric | The UI is organized around work outcomes (PRs, tickets, reviews) rather than infrastructure primitives (sessions, agents). Sessions and agents are accessible but secondary. Sidebar groups: Operate (Dashboard, Work, Sessions, Schedules), Build (Agents), Configure (Credentials, Settings). |
+| Agent detail is a page, not a sheet | The authoring workflow requires editing prompts, comparing test runs, and exporting YAML. A slide-out sheet is too narrow for sustained work. Agent detail mirrors the session detail tabbed-page pattern. |
+| Agents as authoring playground | The UI serves as a prototyping workbench for agent definitions. Teams experiment in the UI, then export to YAML for GitOps management via `acpctl apply`. Draft vs GitOps lifecycle badges distinguish prototype from production agents. |
+| Progressive disclosure, not mode switching | The operator and agent author share one navigation structure at different depths of engagement. No modal "Operations Mode" vs "Authoring Mode". Group labels (Operate/Build) provide wayfinding without mode complexity. |
+| Dashboard as default landing | The most frequent question ("what needs my attention?") should be answered without clicking anything. The Dashboard is the project-level entry point, replacing the session list as the default. |