Quick Capture

Quick Capture lets users type natural language into a single input bar and have it parsed by AI into a fully structured entity record. The system detects the appropriate entity type, generates a title, populates content fields, and optionally suggests relations to existing entities based on the current page context.

Overview

Quick Capture solves the friction of structured data entry. Instead of navigating to a creation form, selecting a type, and filling in fields one by one, users type something like "New opportunity: automate invoice processing, estimated savings $200K/year, medium effort" and the system handles the rest.

The feature lives in features/capture/ and is available in the sidebar via the CaptureBar component. It is page-context-aware: if a user is viewing the opportunity entity type list, the parser biases toward creating an opportunity. If viewing a specific entity detail page, the parser may suggest a relation to that entity.

Key Concepts

ParseResult -- The Zod-validated output schema from the AI parser. Contains:

• entityTypeSlug -- which entity type to create
• title -- a generated title for the new record
• content -- field values matching the entity type's JSON schema
• suggestedRelations -- optional links to existing entities (target ID + relationship type)

Page Context -- The usePageContext() hook reads the current URL pathname to determine whether the user is on an entity type list page or an entity detail page. Reserved routes (dashboard, chat, feed, etc.) return empty context.

Two-Step Flow -- Capture uses a confirm-before-create pattern. The AI parses the input and shows a preview card. The user can edit the title, review extracted fields, then confirm or discard.

How It Works

1. User Input

The CaptureBar component renders a compact input field in the sidebar with a keyboard shortcut (Cmd+Shift+K on Mac, Ctrl+Shift+K elsewhere). The user types a free-text description and presses Enter.

2. AI Parsing

The parseCapture() server action:

1. Validates input with Zod — text must be 1 to CAPTURE_MAX_LENGTH characters (10,000; generous enough to cover in-flow dictation or a pasted email/meeting-note dump). On failure, throws a typed CaptureInputError with a user-facing message and logs the ZodError to Sentry at warning level via captureNonFatal (tagged capture-parse:input-validation). The clients mirror the cap via maxLength={CAPTURE_MAX_LENGTH} so typing stops at the limit before the server is hit; raw text is never used as the entity title — the AI generates the title separately via ParseResultSchema.title.
2. Fetches all available entity types with their JSON schemas
3. Builds a prompt that includes type descriptions and page context
4. Calls safeGenerateObject() (wrapping generateObject()) with the ParseResultSchema to produce structured output — failures on the AI output side surface as a grouped Sentry warning plus a clean StructuredGenerationError, not an unhandled ZodError.
5. Returns the ParseResult to the client

The AI receives the full set of entity types and their schemas, so it can pick the most appropriate type and populate fields accurately.

3. Preview and Confirm

The CapturePreview component renders a card showing:

• Entity type as a badge
• Editable title
• Extracted content fields as key-value pairs
• Suggested relations as link badges

The user can edit the title inline, then click Confirm or Discard.

4. Entity Creation

The createFromCapture() server action:

1. Validates the ParseResult with Zod
2. Creates the entity via the standard createEntity() action
3. Tags the entity with metadata.created_via: "quick_capture" for traceability — provenance markers live on metadata, NOT content, because content keys are validated against the entity type's json_schema.properties and any unknown key throws EntityValidationError. Mirrors the convention in features/entities/server/resolve-relation-targets.ts (metadata: { created_via: "relation_inline" }).
4. Creates any suggested relations in entity_relations (using Promise.allSettled so relation failures do not block entity creation)

API Reference

Server Actions

Schemas

Hooks

Components

Pure Functions

For Agents

Agents do not interact with Quick Capture directly. Instead, they use the standard entity tools:

• createEntity -- create a record with structured content
• createRelation -- link two entities
• listEntityTypes -- discover available types and their schemas

Quick Capture is a human-facing convenience layer that ultimately calls the same createEntity() action that agents use.

Related Modules

• Entity System (features/entities/) -- provides createEntity() and entity type schemas
• Chat (features/chat/) -- an alternative path for AI-assisted record creation via conversation
• Navigation (features/navigation/) -- CaptureBar is rendered in the sidebar layout