> For the complete documentation index, see [llms.txt](https://docs.gofigr.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gofigr.io/features/document-assistant.md).

# Document Assistant

## Overview

The Document Assistant controls how figures relate to their source documents. Unlink a figure from a document while choosing what to keep—the figure in your library, the imported copy, or neither—with visual previews so you can see what each option affects before you confirm.

## 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