> ## Documentation Index
> Fetch the complete documentation index at: https://docs.prbe.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Backfill

> Import work you have already done — a folder, saved coding sessions, or both.

Backfill is the no-connector path: it reads a folder on this machine, works out what is in it, uploads what it finds and describes it.

## Starting an import

**Wizard**

```bash theme={null}
npx probe-research            # → Backfill → Import research work
```

The wizard is the better door for this, and not only because it has screens. It runs the import **in the background**, so a large folder does not hold your terminal; it survives a disconnect and resumes after a restart; and it shows you the plan before anything uploads.

> **[Import research work](/wizard/import.md)**
>
> The picker, the two run modes, and what gets reviewed before it writes.

> **[Existing imports](/wizard/imports.md)**
>
> Watch one, read its result, resume what was interrupted.

**Command**

```bash theme={null}
probe backfill /path/to/work --project existing-project
probe backfill --transcripts-only
```

Direct `probe backfill` is **synchronous** — it holds the terminal until it finishes.

To drive the wizard's own background lane unattended instead:

```bash theme={null}
probe wizard --action backfill --folder /srv/work/folding --yes
probe wizard --action transcripts --yes
```

`--folder` is required headless: without it the wizard opens a picker, which needs a TTY.

Both doors share the same file-coverage records and delivery receipts, so **completed uploads are reused whichever one you came through** — switching between them costs nothing.

## What it reads

| Kind | Becomes |
| - | - |
| Files | Artifacts on the chosen anchor, deduplicated by content |
| A GitHub checkout | Placement context from bounded commit history, plus the attached code source |
| Coding-agent transcripts | Standalone sessions in the knowledgebase |
| Local W\&B run directories | Runs and metric history — see [W\&B](/integrations/wandb.md) |

> [!NOTE]
>
> **References remain references.** A file recorded as a pointer to bytes you keep elsewhere is never silently turned into an upload.
>
> **Sessions import as standalone.** Backfill verifies their native session identity and preserves immutable retries, but it does not infer or create links to projects, experiments or runs. Nothing is guessed.

## Reviewing before it writes

Folder imports either review placement before writing, or use the explicit automatic-approval option — which is never selected for you.

File and Git reconstruction drafts are saved for **explicit publication review**. The agent's reading of your folder is a draft until you say otherwise.

The import writes each project's description and its own block on the project's Overview page. No later step generates the rest of the page: a project's [summary](/tracking/summaries.md) is kept by whoever records work on it, your coding agent or the Probe daemon.

## What is left out

Not everything in a folder is research. The agent leaves out code for a shipped product (its web or mobile app, CLI or service, with that product's tests and assets), vendored code, build output and caches; research code, configs, notebooks, results, logs and checkpoints stay, even inside a product's repository. The review lists each left-out row with its file count and why, and nothing in it is uploaded.

Left-out files are recorded as excluded and stay settled when their bytes change. To classify them again:

```bash theme={null}
probe backfill /path/to/work --review-excluded
```

## Resuming

```bash theme={null}
probe backfill /path/to/work --source-id <id>       # the folder moved, same destination
probe backfill /path/to/work --import-changed       # review files that changed since
probe backfill /path/to/work --import-unverified    # review unresolved legacy matches
probe backfill /path/to/work --retry-dead           # plan files again that failed every attempt
```

Rerun to resume. Coverage of current files is reported **separately** from pending delivery, so "we read everything" and "everything arrived" are never conflated.

> [!WARNING]
>
> A resume delivers the **saved plan and the saved file versions**. New or changed files are not silently added to that delivery — that is what `--import-changed` is for. A retry can never quietly widen its own scope.

## Transcripts only

```bash theme={null}
probe backfill --transcripts-only
```

Imports saved coding-agent histories without touching any folder. The picker detects them independently of which agents you currently have installed.

> [!NOTE]
>
> Protocol-2 transcript imports require a compatible engine, API and tap release. An older combination imports at the earlier protocol rather than failing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.