# Static report library migration checklist

Use this inventory and acceptance record to move report folders, HTML slide
decks, Markdown, SQL, JSON, images, and agent publishing workflows into shared,
versioned context.

Do not cut over from the source library until every required gate is either
passed or recorded as an approved exception.

## 1. Source inventory

```yaml
source:
  system: Reporter
  captured_at: 2026-08-03T00:00:00Z
  captured_by: noam@company.example

products:
  - slug: product-a
    name: Product A
    target_space: product-a

folders:
  - slug: weekly-reviews
    name: Weekly reviews
    product: product-a
    target_folder: weekly-reviews
    source_audience: company
    target_visibility: workspace

reports:
  - slug: retention-review
    title: Retention review
    product: product-a
    folders: [weekly-reviews]
    owner: analyst@company.example
    source_revision: 4
    entry_file: index.html
    visibility: workspace
    public_url: null
    files:
      - path: index.html
        sha256: "<source hash>"
      - path: analysis.sql
        sha256: "<source hash>"
      - path: data/evidence.json
        sha256: "<source hash>"
      - path: assets/chart.png
        sha256: "<source hash>"
```

## 2. Mapping rules

| Source concept | Handover target | Rule |
| --- | --- | --- |
| Product or business area | Space | One durable company segment |
| Folder | Folder inside a Space | Navigation only, never an ACL |
| Report directory | Handover | Preserve one stable identity |
| Republished report | Revision | Never overwrite an old revision |
| Entry HTML file | Entry artifact | Preserve all relative paths |
| Supporting files | Artifacts | Keep bytes, media type, path, and hash |
| Folder allow-list | Visibility and grants | Translate explicitly |
| Public URL | Publication or redirect | Verify before cutover |
| MCP publisher | Human or service identity | Preserve attribution |

## 3. Pilot selection

Choose a pilot containing:

- one public report;
- one company-only report;
- one restricted report;
- one multi-file HTML report with nested JavaScript, CSS, image, and JSON
  assets;
- one Markdown or SQL-heavy report;
- one report updated by an agent;
- one report with an unresolved review thread;
- one report referenced from Slack or external documentation.

## 4. Import verification

For every pilot report, record:

```yaml
verification:
  source_slug: retention-review
  target_handover_id: hov_example
  target_revision: 1
  counts_match: true
  hashes_match: true
  nested_paths_match: true
  entry_renders_desktop: true
  entry_renders_mobile: true
  in_report_navigation_works: true
  files_download: true
  search_finds_title_and_content: true
  ownership_preserved: true
  visibility_matches: true
  public_link_verified: not_applicable
  exceptions: []
```

## 5. Human and agent acceptance

- [ ] A company member can find and open the migrated work.
- [ ] An unauthorized identity cannot retrieve restricted artifacts.
- [ ] A human can annotate selected text or code on the imported revision.
- [ ] An authorized agent can search for the handover.
- [ ] The agent can read files and unresolved annotations.
- [ ] A second identity can pull the complete work package.
- [ ] A successor can publish a new revision with expected-revision checking.
- [ ] History shows the importer and successor as distinct actors.
- [ ] Service credentials are named, scoped, revocable, and not embedded in
      files.

## 6. Cutover gate

```yaml
cutover:
  inventory_exceptions_approved: false
  pilot_acceptance_passed: false
  production_batches_verified: false
  public_redirects_verified: false
  mcp_default_switch_ready: false
  rollback_tested: false
  rollback_window_ends: null
  approved_by: []
  decision: keep_dual_run
```

Set `decision: cut_over` only when all required checks pass. Switching the
default MCP or automation destination should be a separate reversible change.

## 7. Post-cutover

- Keep the source read-only through the rollback window.
- Monitor failed publishes, missing artifacts, authorization failures, and
  broken public links.
- Reconcile any revisions created during the dual-run window.
- Update runbooks, MCP host configuration, and onboarding material.
- Preserve the migration handover, source identifiers, mapping decisions,
  exception approvals, and final link audit.

## Continue

- Migration guide:
  https://handover.sh/guides/migrate-static-report-folders-to-shared-ai-context
- Reporter migration runbook:
  https://handover.sh/docs/reporter-migration
- Imports and exports:
  https://handover.sh/docs/imports-and-exports
- Install Handover:
  https://handover.sh/install