box for muse

Setup prompt to copy

---
name: box
description: Search, read, cite, and save Box files through the user's connected Box account. Gather customer files and candidate contract evidence from a named folder.
---

# Box for Muse

Independent community connector by Dan O'Leary, a Box and Meta alumnus.
Not sponsored, endorsed, or maintained by Box or Meta.

## Connection and scope

Install location: `~/workspace/skills/box/`. Run the commands below relative to
that directory. Requires Python 3 and Muse's platform helper at
`/opt/hatch/skills/skill-creator/bin/dynamic_credentials.py`, plus the user's
connected `custom.box` credential. PDF text extraction requires `pdftotext`.

Authenticate only through the platform helper. It supplies a surrogate in
request headers; the CLI does not retrieve or store real tokens. Never collect
secrets in chat, flags, files, or environment variables. Refresh belongs to
Muse; this CLI does not implement or prove token refresh.

Each user supplies their own grant and instructions. No authorization from the
author transfers with this skill. Box's permissions and Muse's approval controls
still apply. This connector does not enforce a sandbox scope at the OAuth level.

## Commands

- `bin/box identity`: connected identity. Avoid repeating login in receipts.
- `bin/box search "query" --folder-id ID --limit 10 --offset 0`: native Box search.
  Folder scope is optional only when the user intends a wider search.
- `bin/box list-folder ID --limit 100 --offset 0`: browse folder contents.
- `bin/box get-file ID`: metadata and stable Box source link.
- `bin/box read-file ID --text`: verified download and bounded text extraction.
- `bin/box read-file ID --out PATH`: save downloaded bytes locally.
- `bin/box create-folder "name" --parent-id ID`: create in an explicit destination.
- `bin/box save-document PATH --parent-id ID [--name NAME]`: upload a new file;
  successful verification requires destination, checksum, size and exact readback.
- `bin/boxwork gather-customer-files --folder-id ID --customer NAME --alias ALIAS
  [--alias ALT] [--case CASE] [--include-evidence]`: bounded descendant traversal. Aliases are OR;
  supplied alias and case constraints must both match. Repeat `--customer` to
  start another group. Confirmed means identifiers matched, not approval or
  business relevance. Inspect ambiguous and unassessed files and coverage gaps.
- `bin/boxwork review-contracts --folder-id ID --year YYYY`: evidence triage.
  Reads every file within the folder/page/file bounds. `candidate_expirations`
  and `candidate_outside_year` are language clues requiring review, not legal
  conclusions. Historical clauses, date grammar and amendment naming can mislead
  heuristics. `expiring_in_year` and `outside_year` remain empty. Never state
  "all contracts expiring" from this output. Review source clauses, amendments,
  renewal conditions and notice deadlines. `assessment_complete` remains false.

Exit 0 means the command's stated checks passed, not global completeness.
Exit 1 means failure; exit 2 means an ambiguous write, incomplete coverage or
review required. Contract triage exits 2 even when candidate extraction succeeds.

## Run one customer-gather operation

For meeting preparation, add `--include-evidence` to return text already read by
gather, capped at 8,000 UTF-8 bytes per file and 32,000 bytes total. This adds no
downloads. Inspect each `evidence` and `evidence_summary`: partial extraction and
output truncation remain incomplete, and filename-only matches may have no text.
Unverified or uncertain-version text is omitted. Reuse this returned evidence
for the brief; read selected missing content only when necessary.

For a customer-file request, run one foreground `gather-customer-files` command
and collect its result before starting individual file reads. Reuse its file
IDs, source versions and coverage, plus any text already returned in this task.
After it finishes, read only selected files whose needed content is still
missing. Do not run background gathering alongside duplicate individual reads.

While a read awaits Muse approval, wait for that operation's outcome; do not
start another read or retry to obtain a second approval prompt. If a command
has returned a process handle, collect that process's result instead of
relaunching it. After bounded retries finish with a timeout or denial, preserve
the gap and report the useful verified results as partial. Do not invent a
cause, claim the missing file is irrelevant, or restart the workflow merely to
obtain a clean result.

## Evidence and failure behavior

Cite file links and the version actually read. Folder-list metadata is separate
from verified content evidence. Inspect `version_changed_during_read` and
`version_check_note`; disclose unavailable current-version checks. Customer
content matches cannot confirm using partial, unreadable or uncertain-version
content. Newer draft terms do not supersede approved terms without evidence.

A pagination `complete` flag means a terminal collection page, not all content
in Box. Follow `next_offset`; stop at the offset ceiling with explicit gaps.
Search indexing may lag. Use direct folder listing when scoped search misses a
known file. Never silently treat an incomplete search as absence.

Read/upload limit is 20 MiB per file and response. DOCX document.xml is limited
to 8 MiB decompressed. Text previews stop at 20,000 characters with truncation
reported. DOCX extraction is partial: headers, footers and notes omitted;
tables flattened. Scanned PDFs may need OCR, which is not implemented. Images
can be attached, but this CLI does not extract their text.

GET retries are bounded. Honor Retry-After; long waits are returned as deferred.
Do not replay POST after timeout, oversized response or 5xx. Reconciliation is
read-only and does not prove that a discovered pre-existing item was created by
this request. Report ambiguous outcomes, even when the user hoped for success.

For 401/403, distinguish credential

src/box/SKILL.md from the repo, Apache-2.0 licence. Read it before pasting. Muse asks before it acts.