# Document Assistant

## Overview

GoFigr's Document Assistant enhancements give you fine-grained control over how figures relate to their source documents. The new unlink feature lets you cleanly separate figures from documents while preserving what you need—whether that's keeping the figure in your library, cleaning up imports, or removing outdated connections. With visual previews and clear options, managing figure-document relationships is now intuitive and safe.

## Key Benefits for Users

### Clean Up Your Library

* **Remove Unwanted Links**: Disconnect figures from documents without losing the figures
* **Delete Import Artifacts**: Remove figure revisions created during imports you want to undo
* **Maintain Organization**: Keep your figure library clean and well-organized

### Safe Operations

* **Visual Previews**: See exactly which figure you're about to unlink
* **Confirmation for Tracked Figures**: Extra confirmation prevents accidental deletion of important figures
* **Clear Options**: Understand exactly what will happen before you act

### Flexible Control

* **Unlink Only**: Keep the figure, just remove the document connection
* **Unlink and Delete**: Remove both the link and the figure revision
* **Per-Revision Control**: Act on specific revisions without affecting others

## Features

### Unlink Figures from Documents

When viewing a document (PowerPoint, Word, or Jupyter notebook), you can now unlink associated figures:

**The Unlink Button:**

* Located on each linked figure card in document view
* Red "Unlink" button with X icon
* Click to open the unlink modal

**What Unlinking Does:**

* Removes the connection between the figure and the document
* Figure remains in your library (unless you choose to delete)
* Document is unchanged
* Other figures remain linked

### Unlink Options

The unlink modal provides clear choices:

#### Option 1: Unlink Only (Default)

* Removes the figure-document association
* Figure revision remains in your library
* Safe for figures you want to keep
* No confirmation required

#### Option 2: Unlink and Delete Revision

* Removes the association AND deletes the figure revision
* For cleaning up unwanted imports
* Requires confirmation for tracked (non-imported) figures
* Imported figures can be deleted without extra confirmation

### Visual Preview

Before unlinking, you see:

**Figure Preview:**

* Thumbnail image of the figure
* Figure name
* Revision number
* Clickable link to the full figure view

**Context Information:**

* Which document the figure is linked to
* The anchor/location in the document
* Whether the figure is imported or tracked

### Confirmation for Tracked Figures

When deleting a tracked (non-imported) figure revision:

**Extra Safeguard:**

* Warning message explains the figure was created in your analysis (not imported)
* Text input requiring you to type "confirm delete"
* Prevents accidental deletion of original work
* Imported figures bypass this (easier to re-import if needed)

### Document View Integration

The unlink feature is seamlessly integrated into document views:

**From PowerPoint/Word View:**

* Open any imported document
* See list of extracted figures
* Each figure has an unlink button
* Actions apply per-figure

**From Notebook View:**

* Open any imported Jupyter notebook
* View code cells with their output figures
* Unlink individual figures while keeping the notebook

## How to Access

### From Document (Asset) View

1. Navigate to any asset (document) in your workspace
2. Click to view the asset revision
3. Scroll to see linked figures
4. Click "Unlink" on any figure card
5. Choose your options in the modal
6. Confirm the action

### From Document Tab

1. Open a figure that was imported from a document
2. Go to the "Source" or "Documents" tab
3. See all documents linked to this figure
4. Manage links from this view (reverse direction)

## Use Cases

### Cleaning Up Test Imports

After testing the import feature:

1. View the test document
2. Unlink all figures with "delete revision" checked
3. Figures are removed from your library
4. Document asset can also be deleted separately

### Removing Incorrect Links

If a figure was incorrectly linked:

1. Find the figure in the document view
2. Click Unlink
3. Keep "delete revision" unchecked
4. Link is removed, figure stays in library

### Reorganizing After Import

After importing, you may want different organization:

1. Unlink figures from original document
2. Move figures to a different analysis
3. Re-link to different documents if needed

### Undoing Accidental Imports

If you imported the wrong document:

1. Open the imported document
2. Unlink all figures (with delete)
3. Delete the document asset
4. Your library returns to its previous state

## Safety Features

### Imported vs. Tracked Figures

GoFigr distinguishes between:

**Imported Figures:**

* Created automatically during document import
* Marked with `is_imported = true`
* Can be deleted without extra confirmation
* Easy to re-import if needed

**Tracked Figures:**

* Created through the Python/R API or manual creation
* Represent original work
* Require extra confirmation to delete
* "Confirm delete" text input required

### What Confirmation Looks Like

For tracked figures:

```
This figure revision was created in your analysis (not imported).
Deleting it will permanently remove this revision.

To confirm deletion, please type "confirm delete" below:

[___________________]

[Cancel]  [Delete]
```

### Prevention of Mistakes

* Modal requires explicit action
* Checkbox for deletion is unchecked by default
* Visual preview shows exactly what's affected
* Link to view full figure before deciding

## Technical Details

### API Endpoint

```
POST /api/v4/asset_revision/{id}/unlink_figure/
{
  "figure_revision": "revision_id",
  "anchor": "optional_anchor",
  "delete_figure_revision": false
}
```

**Parameters:**

* `figure_revision`: API ID of the figure revision to unlink
* `anchor`: Optional anchor/position reference (for multi-position links)
* `delete_figure_revision`: Whether to delete the revision after unlinking

### Data Model

Links are stored in `AssetLinkedToFigure` model:

* `asset_revision`: The document revision
* `figure_revision`: The linked figure revision
* `use_type`: How the figure is used (e.g., "source")
* `anchor`: Position within the document

### Cache Invalidation

After unlinking:

* Asset revision cache is invalidated
* Linked figures list refreshes automatically
* UI updates without page reload

## Best Practices

### Before Unlinking

1. **Check the Preview**: Verify you're unlinking the right figure
2. **Consider Keeping**: Usually unlink-only is safer than delete
3. **Think About Re-Import**: Can you easily get this figure back?

### For Cleanup Operations

1. **Work Document by Document**: Clean up one import at a time
2. **Verify Before Bulk Actions**: Double-check before mass unlinking
3. **Keep Backups**: Important figures should have copies elsewhere

### For Organization

1. **Unlink Before Moving**: Clean up links before reorganizing
2. **Document Your Changes**: Note what you've unlinked for team awareness
3. **Regular Maintenance**: Periodically review and clean up links

## Related Features

### Document Preview

* View imported documents within GoFigr
* Navigate through slides/pages
* See which figures came from which locations

### Source Tracking

* Every figure knows its source document
* Bidirectional navigation between figures and documents
* Full provenance chain maintained

### Figure QC (Quality Control)

* Badges show figure import status
* Warning alerts for import-related issues
* Reproducibility tracking for non-imported figures


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gofigr.io/features/document-assistant.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.