box-init

name	box-init
description	Bootstrap a box-memory workspace on the local Box Drive mount. Creates folder structure, writes workspace config, seeds index files. FS-only - no Box API calls, no metadata template creation (the on-prem variant runs Personal-tier behavior; Business+ metadata templates are out of scope for air-gap mode). Use when the user wants to set up a Box-memory workspace under their local Box Drive folder.
argument-hint	[workspace-name] [--team=<team>] [--parent=<relative-path>]

/box-init

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

Bootstrap a fresh box-memory workspace under the local Box Drive mount. Box Drive syncs it to Box cloud on its own schedule.

Usage

/box-init [workspace-name] [--team=<team>] [--parent=<relative-path>]

Examples:

• /box-init — workspace named box-memory at the Box Drive root
• /box-init my-vault — workspace named my-vault
• /box-init my-vault --team=engineering — workspace plus an extra team subtree
• /box-init my-vault --parent=Projects — workspace under <mount>/Projects/my-vault

What to do

1. Verify backend. Call box-drive-detect first. If it fails (no mount, not writable, Box Drive not running), surface the error and stop. Never escalate to a network path — this plugin is air-gapped from Box by construction.
2. Resolve workspace path. <box_drive_mount>/<parent_or_empty>/<workspace-name>. Default workspace-name is box-memory. If <workspace-name> already exists, check for _box-memory.json inside:
   • Exists → don't overwrite. Offer (a) use-existing, (b) create alongside with a different name, (c) re-initialize (confirm twice; never deletes memory files, only config).
   • Doesn't exist → proceed.
3. Create folder structure via local mkdir -p:
   • <workspace>/memories/
   • <workspace>/files/
   • <workspace>/companions/ (if companion_layout = "folder" — default is "sibling", in which case skip)
   • <workspace>/teams/<default-team>/memories/
   • <workspace>/teams/<default-team>/files/
4. Acquire workspace lock before writing config. See "Lockfile protocol" below.
5. Write _box-memory.json at workspace root:

{
  "version": 1,
  "schema_version": 1,
  "workspace_name": "<name>",
  "workspace_owner_app": "box-memory-onprem",
  "created_at": "<ISO now>",
  "updated_at": "<ISO now>",
  "backend": "local",
  "local_backend": { ...from box-drive-detect... },
  "tier": "personal",
  "capabilities": {
    "custom_metadata_templates": false,
    "body_search": false,
    "metadata_query_api": false,
    "retention_policies": false,
    "legal_holds": false,
    "compliance": []
  },
  "teams": ["<default-team>"],
  "agents": ["<agent identifier>"],
  "settings": {
    "default_team": "<default-team>",
    "companion_layout": "sibling",
    "include_superseded_in_recall": false,
    "rebuild_index_on_drift": true
  }
}

Notes:

• capabilities.compliance stays empty by default. User declares it (e.g., ["hipaa", "fedramp-moderate"]) in workspace config later if needed. The plugin trusts the declaration; it can't verify compliance posture from local-FS.
• tier: "personal" is the default; metadata-template-dependent features are out of scope for this on-prem variant. Users who need Business+ template queries should also install the cloud box-memory plugin and use it for those workflows.

6. Seed _index.json in every memory-holding folder (workspace memories/, each team's memories/). Empty entries; initialized inverted maps:

{
  "version": 1,
  "folder_path": "memories/",
  "updated_at": "<ISO now>",
  "backend": "local",
  "entry_count": 0,
  "entries": [],
  "by_id": {},
  "by_slug": {},
  "by_wikilink": {},
  "by_kind": {},
  "by_tag": {},
  "by_status": {},
  "by_companion_for": {}
}

Note: file_id field on entries is null in the on-prem variant (Box Drive assigns Box file IDs only after upload). The canonical key is local_path (relative path from workspace root).

7. Release lock (delete _box-memory.lock).
8. Write a brief workspace README at the workspace root explaining the layout (for humans browsing Box web UI later).
9. Report. Workspace name, absolute path, default team, settings. Suggested next: /box-write to save a memory.

Lockfile protocol

When writing _box-memory.json or any _index.json:

1. Acquire lock: create <workspace>/_box-memory.lock with O_CREAT|O_EXCL. Lock body (JSON):

{ "writer": "box-memory-onprem", "skill": "box-init", "pid": <pid>, "started_at": "<ISO>", "renewed_at": "<ISO>" }

2. If lock exists, check renewed_at:
   • If <30 s old → another live writer; retry up to 3 times with 5 s backoff. After 3 fails, surface to user.
   • If ≥30 s old → stale; overwrite the lock and proceed.
3. While holding the lock, update renewed_at every 10 s if the operation takes longer than that.
4. Write the target file atomically: write <file>.tmp, fsync, rename to <file>.
5. Release lock: delete <workspace>/_box-memory.lock.

The lockfile itself is in the Box Drive mount — Box Drive syncs it, so a second machine writing concurrently sees it (eventually). This is best-effort eventual consistency, not transactional. Document that to the user.

Idempotency

Running with the same name is safe: existing folders reused; never overwrites _box-memory.json without explicit confirmation; never deletes memory files. Setup is structure only.

Errors

• Box Drive not detected → see box-drive-detect's error guidance
• Mount not writable → check Box Drive is running + signed in
• Lock cannot be acquired after retries → another writer is active or stuck; tell the user and recommend /box-index-rebuild to check for stale locks

Don't

• Don't create a workspace outside the Box Drive mount path. The whole point is Box Drive handles sync.
• Don't try to apply a Box metadata template — that requires Box API; this plugin is air-gapped from it. Users wanting metadata templates use the cloud variant.
• Don't write memory files during init. Setup is structure only.
• Don't fail because box-drive-detect returned a sync state of unknown. As long as the mount is writable, init succeeds; sync state is informational.