Maintenance and recovery

Most Hansard maintenance can refresh one derived layer without rebuilding the entire archive. Start with diagnostics, then choose the narrowest command that matches the stale data.

Check health in the app

Open Settings → Indexing & Imports to see the watcher status, whether search indexing is paused, the source-selection mode, the sources scanned in Custom mode, and the rolling import window. Use Review incomplete runs when a lifecycle-only session was deliberately hidden from Conversations and Stats. Open Settings → About to confirm the running package version and update status.

For a missing conversation, return to Conversations, select Reset filters, then set Source and Time deliberately before repairing any data. The app exposes current state; status, doctor, logs, reimports, rebuilds, and destructive recovery remain explicit terminal operations so their scope and output can be reviewed.

Routine checks

hansard status
hansard doctor
hansard index status
hansard watcher status

status reports active paths, watcher state, session counts, index state, sync, and recent writes. doctor checks required and recommended system tools, bounded configured-source inventory, search state, autostart, and remote sync. Run hansard doctor --deep when an archive-wide parser-version, missing-source, or import-health audit is needed.

Use --json with status or doctor for machine-readable diagnostics.

Choose the right refresh

Re-read provider source history when importer semantics changed or sessions are missing.

hansard import --source cursor --since all

Re-derive viewer payloads and compressed view pages from archived transcript and event files. Provider source history is not read.

hansard rebuild
hansard rebuild --provider cursor --since 90d
hansard rebuild --force --since all

Recreate local indexes used by history, recall, memories, and viewer lists.

hansard index rebuild

Running rebuild cannot apply a new provider parser because it starts from the normalized transcript and events already in the archive. Conversely, a healthy archive does not need a source reimport merely because its search index is stale.

Maintain the watcher and memories

Restart the background process after configuration or runtime changes:

hansard watcher restart
hansard watcher logs --follow

The watcher also maintains Stats without blocking imports: it waits for a 60-second quiet period before warming common payloads and performs one full SQLite fact reconciliation after 4 a.m. local time each day. A manual hansard index rebuild remains the narrow recovery command when an immediate search or Stats refresh is needed.

Run a provider-memory backup outside the automatic watcher schedule:

hansard memory backup

Unchanged memory content updates its check time without creating a duplicate snapshot.

Preserve a session before repair

Export the normalized five-file bundle and attachments:

hansard export <session-id> --out ./session-export

Include preserved raw files only when the destination can protect unredacted provider data:

hansard export <session-id> \
  --out ./session-export-with-raw \
  --include-raw

Recover missing provider files

When hansard doctor reports that original source files have aged out, preview individual files that can be restored from raw preservation:

hansard restore-sources claude --dry-run

The restore command writes only missing individual files to their recorded original paths. It never overwrites existing files and does not restore shared SQLite stores. Follow a successful restore with a complete provider import:

hansard restore-sources claude
hansard import --source claude --since all

Claude Code has a dedicated backup repair with explicit write confirmation:

hansard repair claude-code-backups --dry-run
hansard repair claude-code-backups --yes
hansard import --source claude --since all

For preserved ChatGPT or Claude.ai exports, restore-sources lists the newest raw exports and the explicit commands needed to import them again.

Package upgrades

A normal package upgrade does not require an archive rebuild:

npm install -g hansard@latest

If the watcher is running, restart it so the long-running process loads the new code. Reopen an active Hansard app or browser viewer as well.

hansard watcher restart

Hansard checks the configured npm registry for newer releases from interactive CLI commands and the app’s About page. Successful checks and notices are limited to once daily. Disable them with hansard config set updates.checkOnStartup false.

Full refresh when release notes require it

hansard update is the destructive local refresh path. It clears local agent-session archive/index data, import fingerprints, cache/spool state, and local sync bookkeeping before reimporting configured sources. It does not delete remote objects or original provider histories.

Review health and verify that the configured original sources still exist.
Preview the exact update scope.
Terminal window
```
hansard update --dry-run --since all
```
Restore any provider files that exist only in raw backups.
Run the refresh only when the release notes require it.
Terminal window
```
hansard update --yes --since all
```
Verify the result.
Terminal window
```
hansard doctor
hansard status
```

Update keeps configuration, redaction rules, web-account labels, the memory archive, device-local Deep Recall research threads, saved classifications, manually imported web-chat archives, unavailable-source archives, original provider histories, and recall integrations. Use --sources <a,b,c> to override the configured sources for that refresh, --no-index to skip index rebuilding, or --no-restart to leave a previously running watcher stopped.

Reset, delete, and uninstall

These commands have distinct scopes:

Command	Effect
`hansard delete <session-id>`	Removes one archived copy; the provider history is untouched.
`hansard reset --dry-run`	Previews removal of Hansard config, state, logs, indexes, reveal cache, and local archive objects.
`hansard reset --yes`	Performs that local reset for fresh setup. Original provider histories and recall integration files remain.
`hansard uninstall --keep-data`	Stops the watcher and disables login startup while retaining archive and configuration data.
`hansard uninstall`	Also removes local Hansard data after confirmation; integration files are listed for manual cleanup.

Prefer an exported session, a narrow rebuild, or a source-specific reimport before using reset.