box-index-rebuild

name	box-index-rebuild
description	Rebuild a folder's _index.json (or the whole workspace's indexes) by walking the local Box Drive filesystem and re-reading every memory's frontmatter. Also resolves Box Drive .conflict files that arise when two clients write the same index, and detects stale companions whose binary changed. FS-only, no Box API.
argument-hint	[<relative-folder-path>] [--check] [--companions-only] [--team=<name>]

/box-index-rebuild

If you see unfamiliar placeholders or need to check which tools are connected, see CONNECTORS.md.

Scan folders on the local Box Drive mount, re-read memory frontmatter, write fresh _index.json files. The source of truth is always the memory files themselves; the index is derived state. Rebuilding from source is always safe.

Usage

/box-index-rebuild [<relative-folder-path>] [--check] [--companions-only] [--team=<name>]

Examples:

• /box-index-rebuild — rebuild every per-folder index in the workspace
• /box-index-rebuild memories/ — rebuild just one folder
• /box-index-rebuild --check — diagnostic only; don't write
• /box-index-rebuild --companions-only — only check companion hash freshness
• /box-index-rebuild --team=engineering — rebuild one team's subtree

What to do

1. Verify workspace + backend. Read _box-memory.json; confirm backend: local; confirm Box Drive writable.
2. Determine target folders. Workspace-wide / folder-scoped / team-scoped per args.
3. List local FS of target folder. Capture every file: relative path, size, mtime.
4. Parse memory files. For each *.md (excluding README.md, _*.json, anything starting with _):
   • Read file content
   • Parse YAML frontmatter (between --- delimiters)
   • Extract: id, slug, title, kind, status, team, tags, related, companion_for, sha256, created_at, updated_at
   • If frontmatter malformed (missing required fields, no --- delimiters), capture in orphans[] list with the problem. Don't drop.
5. Build entry list + inverted maps:
   • by_id[<mem_id>] → entries array index
   • by_slug[<slug>] → mem_id
   • by_wikilink[<title>] → mem_id
   • by_kind[<kind>] → [mem_id, ...]
   • by_tag[<tag>] → [mem_id, ...]
   • by_status[<status>] → [mem_id, ...]
   • by_companion_for[<binary_relative_path>] → mem_id (companion entries)
6. Detect collisions. Same id across two files → conflict (should never happen; if it does, surface for user). Same slug across two status: active memories → conflict; flag both.
7. Companion staleness check (also runs in --companions-only mode):
   • For each companion entry, locate the binary at <workspace>/<companion_for.local_path>
   • Compute current SHA256 of the binary
   • Compare to stored companion_for.sha256
   • Match → companion current
   • Differ → mark as stale: true in the new index; add to stale_companions[] report; suggest /box-companion <relative-path> to regenerate
   • Binary missing from local FS → mark as orphaned: true; add to orphan_companions[]; surface separately (the binary may be in Box cloud but not synced locally yet, OR it was deleted)
8. Handle .conflict files. Box Drive creates files like _index.json.conflict-<timestamp> when two writers wrote the same path:
   • If detected, parse both and merge by union of entries + most-recent-updated_at-wins per entry ID
   • After successful merge, delete the .conflict files
   • Surface in the report so the user knows a merge happened
9. Stale lockfile detection. If _box-memory.lock exists and renewed_at is >30s old, force-remove it (it's stuck). Mention in the report.
10. Acquire workspace lock, write the new _index.json atomically, release lock. Skip writes if --check mode.
11. Rebuild rollup at workspace root (_index.json) after all per-folder indexes are fresh.
12. Report:

✓ Index rebuild complete (or check complete).

Scope:                 <workspace | folder | team>
Folders processed:     <N>
Memories indexed:      <N>
Companions indexed:    <N>

Issues found:
  Stale companions:    <N>   (hash mismatch — binary changed since review)
  Orphan companions:   <N>   (binary not in local FS; may not be synced yet)
  Frontmatter errors:  <N>   (parse failures — see below)
  ID collisions:       <N>
  Slug collisions:     <N>
  .conflict files merged:  <N>
  Stale lockfile removed:  <yes/no>

For each stale companion, give:

- companion: <relative path> (id: <mem_...>)
  binary:     <binary relative path>
  reviewed:   <reviewed_at>
  stored sha: <hash>
  current sha: <hash>
  → /box-companion <relative path>   to regenerate

For each frontmatter error:

- file:   <relative path>
  error:  <e.g. "missing 'id' field", "no closing --- delimiter">
  → fix manually, or move to <workspace>/_archive/

Check mode (--check)

Same scan; don't write. Compare what the rebuild WOULD produce against the current _index.json. Report drift:

• Entries in current index that don't exist in source (binary deleted from local FS — may be Box Drive un-syncing OR true delete)
• Entries in source that aren't in current index (added files not yet indexed)
• Entries where frontmatter doesn't match current entry (modified files)

Useful before committing to a rebuild — "what would change?"

Performance

• Each file read is one local FS read. 200 memories → ~200 reads. Fast.
• For 1000+ memory workspaces, batch by folder.
• Rollup rebuild reads only per-folder indexes (much cheaper than full rebuild).

When to suggest rebuild

After other skills detect drift (recall returning stale results, write hitting unexpected slug collisions), suggest:

Note: rebuild detected <N> issues. Resolve before relying on recall for those memories.

Don't

• Don't modify memory files during rebuild. Index is derived; sources are authoritative.
• Don't delete orphan or frontmatter-error files — surface them; let the user decide.
• Don't rebuild silently if non-trivial drift was found. Always report what changed.
• Don't call Box's API or read any URL.

Errors

• Permission denied on a folder → "Skipped folder <path> — no read access"
• Frontmatter parse failure on a memory → captured in report, doesn't fail the rebuild
• Cannot read a memory file → captured as "unreadable", doesn't fail the rebuild
• Lock cannot be acquired → another writer is active OR a stale lock — force-remove if >30s stale and retry