Skip to content

Cara Copilot & Hub

StatusShipped
LinearPIN-490 ↗
ModuleCara ↗

Two surfaces for the same assistant: a draggable widget opened from the floating "C" button (page-aware — it knows which screen you're on), and the full-page Hub at /cara with saved threads. Replies arrive as one complete message (no token streaming) rendered as Markdown. Tasks and email integrations are September — their action cards exist but the backends don't.

Prerequisites

  • Role: any login with Cara access.
  • For SOV generation: an awarded bid.
  • Test data: a PDF from docs-pdfs/ for the attachment check.

1. The widget

Bottom-right floating "C" button (tooltip Ask Cara; click-only, no keyboard shortcut). It opens a draggable 380×560 panel:

  • Header: Cara mark, status line "Online · sees this screen", a copper Full page link (→ /cara), and X to close.
  • Empty state: "Ask Cara anything — she can see this screen and help with whatever you're working on."
  • Drag it around — position persists across pages and reloads, and it must re-clamp on window resize (never stranded off-screen). After dragging, a Reset to starting position button appears.
  • The floating button hides while the panel is open and on /cara routes.

2. Page-awareness (PIN-490)

On registered surfaces the status line changes to "Online · viewing {surface}" and the widget switches to a scoped thread with a one-time kickoff message; a Back to general chat button returns to the quick-chat thread. Currently registered surfaces: the bid SOV tab and the project Billing tab. On unregistered pages the widget stays in general chat — that's expected, not a bug.

3. The Hub

/cara: greeting "Hi {firstName} — how can I help?", a composer ("Ask Cara anything — bids, vendors, estimates, or a general question…"), and four action cards: Summarize my pipeline, Summarize my to-do list, Look up a vendor, Review my emails & draft replies.

⚠ Cards 2 and 4 are rendered but their integrations (Tasks, email) are September scope — poor answers there are backlog items, not launch bugs. Cards 1 and 3 are fair game.

Threads sidebar: New thread, per-thread Rename / Archive / Delete, untitled threads show "New conversation". Threads persist across sessions.

4. The composer

  • Enter sends, Shift+Enter newline.
  • Attach files (paperclip) — attach a docs-pdfs/ PDF and ask a question about it.
  • Deep Think toggle ("Use a slower, more thorough model").
  • Generated documents button opens the docs modal.
  • While waiting: your message appears immediately, a thinking spinner shows, then the full reply lands at once. A failed send must remove the optimistic bubble, not leave a ghost.
  • Replies render Markdown: tables, code blocks, links (copper, open in new tab). There is no citation chip UI — links inline only.

5. SOV generation (awarded bid)

Awarded bid → SOV tab: empty state "Generate your SOV…" with Generate SOV with Cara. Cara proposes G703 line items covering the contract amount:

  • A balance chip reads Balanced (green) or +$X over / $X short (amber).
  • Approve SOV is disabled until balanced (tooltip "SOV total must equal the contract amount before approving") — ask Cara to adjust line items until they sum exactly.
  • Approve (permission-gated) → toast "SOV approved"; then Export PDF appears.
  • Unauthorized roles see "Contact your PM or Estimating lead to generate the SOV."

6. Budget cap

When the monthly Cara budget is exhausted, the panel shows "Monthly Cara budget exceeded — contact admin." and the composer disables with a matching placeholder. If you ever see raw errors instead of this state, that's a bug.

Verification Checklist

  • Widget opens/closes, drags, persists position, re-clamps on resize
  • On the SOV/Billing surfaces the status line names the surface and a scoped thread starts once (no duplicate kickoff)
  • Hub cards 1 & 3 return sensible data-grounded answers
  • Attachment + question about the attached PDF works
  • Thread rename/archive/delete work; threads survive relogin
  • SOV: Approve stays disabled until balanced; approval toasts and enables PDF export
  • Failed send removes the optimistic bubble
  • No console errors throughout

Known Issues / Current Gaps

  • 🕐 Cara × Tasks and email-to-task are September — the Hub cards exist but the integrations don't.
  • No token streaming and no citation UI — single complete Markdown reply is the intended UX.
Updating this walkthrough

Run the full flow yourself end-to-end. If it passes, bump last_verified: in the frontmatter to today's date. If any step fails, fix the doc or the code in the same PR — drift is the enemy.