# Confluence Backup/Restore & Search Index — Agent Guidance

Covers `src/tools/backup-restore.ts` (12 tools) and `index-management.ts` (4) — both genuinely
destructive/high-risk instance-maintenance surfaces, grouped together because they share the same
operating discipline: read status before acting, and know exactly which operations here are
irreversible. Confirmed live 2026-08-20; see `docs/plans/2026-08-20-full-api-coverage.md` batches
12 and 13 for the full record, including a real backup-and-restore-search lifecycle.

## Restore operations are the highest-risk tools in this entire project

`admin_create_site_restore_job`, `admin_create_space_restore_job`, and their `_from_upload`
variants **replace live content with the backup's contents** — there is no undo short of restoring
a more recent backup. These four are the only tools in the whole 183-tool surface that were
deliberately never live-tested against a real instance (see `UNVERIFIED_TOOLS` in
`scripts/implemented-operations.mjs` for the full reasoning) — not because the code is unproven
(backup creation, job management, and file download all share the same request/response
conventions and *were* verified), but because there's no scoped, disposable way to test an actual
restore. Confirm with the caller before ever invoking one of these four for real, and confirm which
backup file you're restoring from — `admin_list_restore_files`/`admin_find_backup_restore_jobs`
first.

## `admin_find_backup_restore_jobs` needs a filter or it lies

Confirmed live: with **no** `jobScope`/`jobOperation`/`spaceKey`/`owner` filter at all, this
returns an empty array even when real jobs exist — a job findable by ID via
`admin_get_backup_restore_job` was completely absent from an unfiltered list. Pass at least
`jobScope` (`"SITE"` or `"SPACE"`) or `jobOperation` (`"BACKUP"` or `"RESTORE"`) — either alone is
enough to make real results appear. Don't read an empty unfiltered result as "no jobs have ever
run."

## Backup jobs are asynchronous; poll `admin_get_backup_restore_job`

`admin_create_site_backup_job`/`admin_create_space_backup_job` return immediately with a job
reference. Poll `admin_get_backup_restore_job` for `jobState` (`QUEUED` → `PROCESSING` →
`FINISHED`) rather than assuming the backup exists right after the create call returns — confirmed
live, even a small space backup takes a few seconds to actually finish.

## `admin_download_backup_file` won't embed large files

Backup files can be many megabytes. Below 200KB, the tool inlines the file as base64; above that,
it returns only `sizeBytes`/`contentType` metadata — confirmed live against a real 693KB backup,
correctly reported as too large rather than blowing up the response. If you need the actual bytes
of a large backup, that has to happen outside this tool.

## Index management: two tools require `confirm: true`

`trigger_reindex` and `unindex_all_content` both throw a real `McpError` if called with
`confirm: false` or omitted — this project's stand-in for MCP elicitation-based confirmation (same
convention alces-mcp uses for its own destructive admin tools). Get the caller's explicit go-ahead,
then call again with `confirm: true`.

**`unindex_all_content` genuinely breaks search until you reindex.** Confirmed live: after calling
it, a real CQL search via `search_content`/`search_entities` returns nothing for content that
definitely exists, until `trigger_reindex` completes. If you ever call `unindex_all_content` for a
real reason, follow it with `trigger_reindex` (scoped to the whole instance, not just one space) —
don't leave search broken.

`reset_reindex_job` is the low-risk one here — it just clears a stuck/errored job's status, doesn't
touch content or the index itself, and isn't confirm-gated.