# UX-Refactor Phase 1 — Shared CONTRACT (binding)

> Authored by the Phase-1 contract agent (the ONLY agent that edits
> `packages/shared/src/types.ts` + `apps/web/src/lib/adapter.ts` +
> `apps/web/src/lib/types.ts` this run). Leaf builders (S01/S02/S03 FE + the
> sidecar route leaves) and the integrator MUST align to the names + shapes below.
>
> Grounded in: `shared-types-delta.md §9`, `backend-api-delta.md` Phase-1 group,
> gap cards `S01 §6`, `S02 §6`, `S03 §6`. Mockups are directional; PRD acceptance wins.
>
> **Verification:** `npx tsc --build packages/shared` → exit 0;
> `npx tsc --noEmit --project apps/web/tsconfig.json` → exit 0 (adapter + FE types
> resolve against the rebuilt shared dist). The `/api/*` routes do NOT exist yet —
> the adapter methods compile as fetch wrappers; the route leaves build the servers.

---

## 1. New shared types — `packages/shared/src/types.ts`

Added as a `// === UX-Refactor Command vocabulary (PRD §12.3 / shared-types-delta §9) ===`
block. Exported via the barrel (`packages/shared/src/index.ts` `export * from './types.js'`),
so `import { … } from '@waggle/shared'` resolves them. **String-literal unions, all exported.**

> Phase-0 already shipped the §15.2 unions (`WorkspaceType`, `Scope`, `Confidence`,
> `MemoryKind`, `ArtifactKind`, `AgentType`, `AutonomyLevel`, `ExtensionType`) and
> `WorkspaceConfigV2` in this same file. This run adds ONLY the Command vocabulary.

```ts
export type CommandCategory =
  | 'search' | 'launch' | 'create' | 'run' | 'navigate' | 'extend';

export type CommandResultType =
  | 'workspace' | 'memory' | 'artifact' | 'session' | 'person'
  | 'agent' | 'skill' | 'command' | 'connector' | 'mcp' | 'automation';

export interface CommandAction {
  route?: string;
  endpoint?: string;
  payload?: Record<string, unknown>;
}

export interface CommandResult {
  id: string;
  type: CommandResultType;
  title: string;
  subtitle?: string;
  category: CommandCategory;
  icon?: string;
  requiresApproval?: boolean;      // §12.3 permission-gated → approval prompt
  action?: CommandAction;
}

export interface Command {            // execute request body
  id?: string;                       // structured command resolves via id
  input?: string;                    // OR natural-language command string
  category?: CommandCategory;
  type?: CommandResultType;
  workspaceId?: string;
  payload?: Record<string, unknown>;
}
```

> **Field-name note (binding):** `shared-types-delta §9` is the source of truth, so
> `CommandResult` uses `category: CommandCategory` + `type: CommandResultType`.
> Gap card S03 §6 sketched alternate field names (`kind`/`objectType`) — those are
> SUPERSEDED. Leaves must use `category`/`type`. S03's local `SearchResult`
> interface (`GlobalSearch.tsx:17-25`) is replaced by this shared `CommandResult`.

---

## 2. New FE view-model types — `apps/web/src/lib/types.ts`

Added in a `// ── UX-Refactor Phase 1 view-models ──` block. The top of the file
now re-exports the shared Command vocabulary so palette FE can import the whole
contract from `lib/types`:

```ts
import type {
  WorkspaceType, CommandCategory, CommandResultType, CommandResult, CommandAction,
} from '@waggle/shared';
export type { CommandCategory, CommandResultType, CommandResult, CommandAction };
```

### S01 — Home Cockpit
```ts
export interface RecentWorkspaceCard {
  id: string; name: string; group: string;
  summary?: string; lastActive: string;
  pendingCount: number; continueSessionId?: string;
}
export interface SuggestedAction {
  label: string; workspaceId: string; sessionId?: string; kind: string;
}
export interface UpNextItem {
  id: string; label: string; workspaceId?: string; at?: string;
  kind: 'event' | 'task' | 'schedule';
}
export interface HomeBriefing {
  greeting: string; userName?: string; date: string;
  recentWorkspaces: RecentWorkspaceCard[];
  suggestedActions: SuggestedAction[];
  upNext: UpNextItem[];
  activeModels?: string[];
  isFirstRun: boolean;
  /** P2 amendment — J08 (D6): personal-mind memories with status 'unreviewed'.
   *  The FE types this optional for back-compat with pre-P2 sidecars. */
  needsReviewCount: number;
}
export interface OvernightFailure {
  id: string; label: string; automationId?: string; error: string; at: string;
}
export interface OvernightSummary {
  consolidated: number; artifactsCreated: number; automationsCompleted: number;
  failures: OvernightFailure[];
  window?: { from: string; to: string };
}
export interface QuickCaptureInput {
  kind: 'note' | 'task' | 'link' | 'file'; content: string; workspaceId?: string;
}
```

### S02 — Workspace Desktop
```ts
export interface WorkspaceStateItem {
  id: string; content: string; date?: string;
  freshness?: 'fresh' | 'aging' | 'stale';
}
export interface WorkspaceStateView {       // FE mirror of server WorkspaceState
  active: WorkspaceStateItem[];
  openQuestions: WorkspaceStateItem[];
  pending: WorkspaceStateItem[];            // pending + blocked seed the Tasks tab
  blocked: WorkspaceStateItem[];
  completed: WorkspaceStateItem[];
  stale: WorkspaceStateItem[];
  recentDecisions: WorkspaceStateItem[];
  nextActions: SuggestedAction[];
}
export interface WorkspaceActivityEvent {
  id: string | number; ts: string; type: string; actor?: string; summary: string;
}
```

> The FE `Workspace` interface already carries the Phase-0 optional V2 fields
> (`type`, `status`, `description`, `agentIds`, `connectorIds`, `mcpIds`,
> `updatedAt`) — leaves consume those; do not re-add them.

---

## 3. New adapter methods — `apps/web/src/lib/adapter.ts`

Pattern matched to existing siblings: thin `await this.fetch(path[, init])` →
`res.json()`. Base URL + bearer-token + 403-tier handling all come from the
shared `this.fetch()` wrapper. All exposed on the `LocalAdapter` instance
exported as `adapter` (and the default export). Routes are net-new (do not exist
yet) — these compile and run as fetch wrappers; calls will 404 until the route
leaves land.

| Method (signature) | HTTP | Endpoint | Screen |
|---|---|---|---|
| `getHomeBriefing(): Promise<HomeBriefing>` | GET | `/api/home/briefing` | S01 |
| `getHomeOvernight(since?: string): Promise<OvernightSummary>` | GET | `/api/home/overnight[?since=<iso>]` | S01 |
| `quickCapture(input: QuickCaptureInput): Promise<{ frameId: string }>` | POST | `/api/quick-capture` | S01 |
| `getWorkspaceState(id: string): Promise<WorkspaceStateView>` | GET | `/api/workspaces/:id/state` | S01, S02 |
| `getWorkspaceActivity(id: string, limit = 50): Promise<{ events: WorkspaceActivityEvent[] }>` | GET | `/api/workspaces/:id/activity?limit=` | S02 |
| `commandSearch(q: string, scope?: string): Promise<{ results: CommandResult[] }>` | GET | `/api/command/search?q=[&scope=]` | S00, S03 |
| `commandRecent(): Promise<{ recent: CommandResult[] }>` | GET | `/api/command/recent` | S03 |
| `commandSuggestions(): Promise<{ suggestions: CommandResult[] }>` | GET | `/api/command/suggestions` | S03 |
| `commandExecute(payload: Command): Promise<{ ok: boolean; result?: unknown }>` | POST | `/api/command/execute` | S00, S03 |

### Binding notes for the route + FE leaves
- **Response envelopes are exact.** `commandSearch` returns `{ results: CommandResult[] }`,
  `commandRecent` returns `{ recent: CommandResult[] }`, `commandSuggestions` returns
  `{ suggestions: CommandResult[] }` (distinct keys — do not collapse). `getWorkspaceActivity`
  returns `{ events: [...] }`. `getHomeBriefing` / `getHomeOvernight` / `getWorkspaceState`
  return the bare object (no envelope).
- **B4 (founder-ratified):** `commandExecute` posts to the **singular** `/api/command/execute`,
  which the route leaf ALIASES onto the existing handler. The existing plural
  `/api/commands/execute` (`adapter.executeCommand`) is NOT renamed and stays as-is.
- **C9:** the Command Center permission prompt (`CommandResult.requiresApproval`) reuses the
  chat approvals pipeline (`useChat().pendingApproval` / `ApprovalRequest`), not a new mechanism.
- **C5/C7 do not change this contract** but constrain consumers: Overview chat is a read-only
  preview deep-linking to the Chat tab; Tasks tab seeds from `WorkspaceStateView.pending` +
  `.blocked`.
- **Artifact/agent facets** in `CommandResultType` are intentionally present-but-gated — S05/S09
  substrate is not built yet; command search ships with the available facets only.

---

## 4. Files touched this run (scope lock)

- `packages/shared/src/types.ts` — added Command vocabulary block.
- `apps/web/src/lib/types.ts` — added Phase-1 FE view-models + shared re-export.
- `apps/web/src/lib/adapter.ts` — added 9 Phase-1 methods + 2 import lines.
- `docs/ux-refactor/_phase1-contract.md` — this note.

NOT touched (by contract): `Desktop.tsx`, `lib/dock-tiers.ts`, any `index.ts` route
registrar, any `routes/*.ts`, any component. Those belong to the leaf builders.