ShrubberyDocs
API ReferenceSign in
Guide

Capture Flow (Smart Paste, URL Drop, Manual)

Four entry points turn a chaotic input into a tracked Draft on the Garden: Smart Paste, URL Drop, Manual Contract, and the Inbox API.

01 · Overview

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.

02 · Actors

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.
03 · Flow

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.
04 · Edge cases

Edge cases

  • No BYOK key for Smart Paste — /api/gather returns 400 no_byok_key directing the Lead to /settings/integrations. 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.
  • Smart Paste upstream provider failure — if the BYOK provider rejects the call (invalid key, exhausted quota, model unavailable), /api/gather returns 502 upstream_failure with the provider's message surfaced verbatim; treat it as an opaque debugging string, not a stable code. Rate-limited callers get 429 rate_limited with a Retry-After header.
  • Smart Paste extracts nothing — the Squire validates its output against the DraftShrubberiesResponse schema and never writes a row itself; any extraction it declines to make returns drafts: [] rather than an error. There are no prompt-injection mitigations beyond the system prompt, so the empty-result path is the safety net.
  • 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.
05 · Related

Last updated: 17 May 2026