ShrubberyDocs
Sign in

Capture Flow (Smart Paste, URL Drop, Manual)

Overview

Capture is Pillar I of the Shrubbery engine — the moment a chaotic input (a meeting transcript, a chat dump, a Jira link, a typed sentence) becomes a Draft Shrubbery on the Garden. Four entry points exist: Smart Paste, URL Drop, Manual Contract, and the Inbox API (covered in its own guide). All four converge on the same Draft row pipeline.

Actors

  • Lead — initiates capture in the in-app Capture surface. Always the resulting assigner on the row.
  • Squire — only present on the Smart Paste path. The Squire reads the raw text via /api/gather and produces structured fields (objective, deadline, suggested assignee). The Squire never auto-sends; the Lead always reviews and confirms.
  • Knight — does not participate in capture. The Knight first sees a Shrubbery once the Lead promotes the Draft to Pending_Handshake via the Garden's Send action.
  • External System — for URL Drop, the source tracker (Jira / Linear / GitHub) is recorded as (external_system, external_id) on the row but is otherwise passive.

Flow

  1. Lead opens the Capture surface (Hybrid Ingestion Hub) and picks a tab.
  2. Smart Paste path — Lead pastes raw text → Squire extracts fields server-side via /api/gather using the Lead's BYOK provider key → returns one structured candidate. The Lead reviews and saves → Draft row inserted, actor_kind = user, source = smart_paste.
  3. URL Drop path — Lead pastes a Jira/Linear/GitHub URL → server parses host + external ID → creates an "Execute External Request" Shrubbery linked via (external_system, external_id). No AI involvement → Draft row inserted, source = url_drop.
  4. Manual Contract path — Lead fills a Mad-Libs form: "I am asking [Knight] to [objective] by [date]." Pure structured input, no AI → Draft row inserted, source = manual_contract. Already carries the assignee from the picker.
  5. All three paths terminate identically: a single Draft row in public.shrubberies, an audit event of type created with the source name, and the row appearing in the Lead's Garden Draft column. The Lead promotes it to Pending_Handshake from the Detail Sheet when ready.

Edge cases

  • No BYOK key for Smart Paste — /api/gather returns a clear error directing the Lead to BYOK settings. Pillar II purity rule: there is no platform-side AI fallback after Sprint 14.
  • Smart Paste low-confidence extraction — Squire still returns a Draft, but the Lead sees a confidence indicator and can edit fields before saving. The Squire never commits without review.
  • URL Drop with unknown host — falls back to a Manual-Contract-style form pre-filled with the URL as the source excerpt; no external mapping persisted.
  • Manual Contract self-handshake — assigning to one's own email is disallowed at the resolver; the Knight must be a different user.
  • Duplicate external mapping — uniqueness is (external_system, external_id, assigner), so two Leads may independently track the same Jira ticket without collision.
  • Manual Contract pre-filled assignee, then forgotten on Send — Sprint 24 candidate (see backlog). Today the dashboard's Send step demands re-entry; the picker value should auto-fill from the Draft.

Last updated: 17 May 2026