Create a new analysis design document.

Creates a YAML file in .insight/designs/ with 'in_review' status. theme_id must match [A-Z][A-Z0-9]* pattern (e.g., 'FP', 'TX', 'DEFAULT').

methodology: Analysis method dict with required 'method' key. Example: {"method": "OLS", "package": "statsmodels", "reason": "..."} WARNING: Should rarely be None — methodology is a core design field.

Returns: dict with id, title, status, message

Partially update an existing analysis design.

Only provided fields are updated. Returns the updated design as a dict, or an error dict if design_id not found. Status changes must go through transition_design_status.

Retrieve an analysis design by ID.

Returns the full design as a dict, or an error dict if not found.

List all analysis designs, optionally filtered by status.

Args: status: Optional filter (in_review|revision_requested|analyzing|supported|rejected|inconclusive)

Returns: dict with 'designs' list and 'count' integer

Register a new data source in the catalog.

Update an existing data source in the catalog.

Get the column schema for a data source.

Search the data catalog using full-text search.

Get domain knowledge entries for a data source.

Transition a design to the given target status.

Valid transitions depend on the current status:

• in_review -> revision_requested, analyzing, supported, rejected, inconclusive

• revision_requested -> in_review

• analyzing -> in_review

• supported, rejected, inconclusive -> (terminal, no transitions)

Returns: dict with design_id, status on success; {error} on failure

Save a review comment and transition the design status.

The design must be in reviewable status (in_review or revision_requested). Valid post-review statuses: revision_requested, analyzing, supported, rejected, inconclusive.

Returns: dict with comment_id, design_id, status_after, message

Save a batch of review comments and transition the design status.

The design must be in reviewable status (in_review or revision_requested). Each comment can optionally include target_section and target_content for inline anchoring.

Valid status_after values: revision_requested, analyzing, supported, rejected, inconclusive.

Returns: dict with batch_id and status_after on success; {error} on failure

Get review comments for a design.

Returns all review batches sorted by created_at descending (newest first). Returns empty list if no reviews exist or file is corrupted.

Extract domain knowledge from review comments as preview.

Returns extracted entries for user review before persistence. Call save_extracted_knowledge() to persist confirmed entries.

Returns: dict with design_id, entries, count, message

Persist user-confirmed knowledge entries to extracted_knowledge.yaml.

Call extract_domain_knowledge() first to get preview entries, then pass confirmed (optionally adjusted) entries here.

Args: design_id: The design ID the entries were extracted from entries: List of dicts with keys: key, content, category, affects_columns

Returns: dict with design_id, saved_entries, count, message

Get aggregated project context including all domain knowledge.

Returns sources, knowledge entries, rules, and counts from both catalog and review-extracted knowledge.

Suggest cautions for the given table/source names.

Searches all domain knowledge entries (catalog and extracted) by matching affects_columns against provided table names.

Args: table_names: Comma-separated string of table/source names

Returns: dict with table_names, cautions, count

Suggest knowledge entries relevant to a design section.

Filters by category via SECTION_KNOWLEDGE_MAP, then applies per-category matching strategies (theme_id, source_ids, FTS5, lineage).

Args: section: Design section name (e.g., hypothesis_statement, metrics) theme_id: Theme ID to match findings/context by source_ids: Comma-separated source IDs for caution/definition matching hypothesis_text: Text to search via FTS5 for methodology matching parent_id: Design ID to walk ancestor chain for finding collection

Returns: dict with section, suggestions, total