Skip to content

docs: finish the task-structure pass, and document two CLI paths it uncovered - #63

Merged
Mandalorian-Wang merged 1 commit into
boxlite-ai:mainfrom
Mandalorian-Wang:docs/task-structure-2
Oct 21, 2026
Merged

Mandalorian-Wang merged 1 commit into
boxlite-ai:mainfrom
Mandalorian-Wang:docs/task-structure-2

Conversation

@Mandalorian-Wang

Copy link
Copy Markdown
Contributor

Workstream B, the remaining three pages. Completes the batch started in
#62.

Page Body headings, before → after
raw-streams 0 → 4
data-across-boxes 0 → 5
cost-controls 1 → 4

No code or facts changed except where a surface was missing.

The rule paid for itself again

Checking "where does the user actually do this?" per task — the discipline the plan
added after the network-policy miss — turned up two CLI paths none of these pages
mentioned, and one limitation worth more than either.

data-across-boxes now opens with the proof in six commands

Instead of a 190-line script. Run end to end before writing it down:

boxlite volume create --name handoff-demo
boxlite create python --name box-a -v handoff-demo:/data
boxlite exec box-a -- sh -c 'echo "produced by box A" > /data/handoff.txt'
boxlite rm -f box-a                      # the box is gone, the volume is not
boxlite create python --name box-b -v handoff-demo:/data
boxlite exec box-b -- cat /data/handoff.txt
# produced by box A

cost-controls: the CLI closes only half the bill

boxlite create takes --auto-stop, with a friendlier grammar than the SDK — 30s,
15m, 2h, 7d instead of raw seconds. It refuses --auto-delete:

$ boxlite create python --name cost-b --auto-delete 1h
Error: invalid argument: remove-on-stop is incompatible with detach=true.
Detached boxes should use auto_delete=0 ... for manual lifecycle control.

--auto-stop 15m alone succeeds on the same command, so this is specific to
auto-delete on a detached box, not a bad flag pairing. The page now says you can close
the compute half of the bill from the CLI and need an SDK for the disk half —
the fact, rather than the tidier story of "both work everywhere".

Two tables where a sentence was doing too much work

  • raw-streams — a return-value table for read(): data, b"" at end-of-stream,
    ValueError on read(0), and a closed-connection error after close(). That the
    empty read is the only EOF signal was one clause inside a paragraph.
  • data-across-boxes — a table of which paths survive a box. Writing outside the
    mount is the single mistake this page exists to prevent, and it was a trailing
    sentence.

Checks

python3 scripts/lint-docs.py .          → 180 pages checked, no soft promises
python3 scripts/gen-llms-txt.py --check → llms.txt is up to date
python3 scripts/check-structure.py .    → clean
mint broken-links                       → no broken links found

Every box and volume created for this was removed; the account is back to its two
pre-existing boxes and no volumes.

Stacked on #62.

🤖 Generated with Claude Code

@mintlify

mintlify Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Preview approval required

This pull request comes from a fork, so Mintlify won't build a preview until someone with write access approves commit 3a2bab0.

Approve preview

@coderabbitai

coderabbitai Bot commented Oct 21, 2026 •

Copy link
Copy Markdown

Important

  • 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: QUIET
  • Plan: Advanced
  • Run ID: bdb7c1c6-65ff-4eb0-aff6-068a4ec94842
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

…ncovered

Workstream B, the remaining three pages. Headings per page, before and
after: raw-streams 0 -> 4, data-across-boxes 0 -> 5, cost-controls 1 -> 4.
No code or facts changed except where a surface was missing.

Checking "where does the user do this?" per task — the rule the plan
added after the network-policy miss — turned up two CLI paths none of
these pages mentioned, and one limitation worth more than the paths.

data-across-boxes now opens with the whole proof in six commands rather
than a 190-line script. Run end to end before writing it:

  boxlite volume create --name handoff-demo
  boxlite create python --name box-a -v handoff-demo:/data
  boxlite exec box-a -- sh -c 'echo "produced by box A" > /data/handoff.txt'
  boxlite rm -f box-a
  boxlite create python --name box-b -v handoff-demo:/data
  boxlite exec box-b -- cat /data/handoff.txt
  produced by box A

cost-controls: `boxlite create` takes `--auto-stop` with a friendlier
grammar than the SDK — `30s`, `15m`, `2h`, `7d` instead of raw seconds.
It refuses `--auto-delete`, though:

  $ boxlite create python --name cost-b --auto-delete 1h
  Error: invalid argument: remove-on-stop is incompatible with
  detach=true. Detached boxes should use auto_delete=0 ... for manual
  lifecycle control.

`--auto-stop 15m` alone succeeds on the same command, so this is
specific to auto-delete on a detached box, not a bad flag pair. The page
says you can close the compute half of the bill from the CLI and must
use an SDK for the disk half, which is the fact rather than the tidier
story.

Also:

- raw-streams gained a return-value table for read(): data, b"" at
  end-of-stream, ValueError on read(0), and a closed-connection error
  after close(). The empty read being the only EOF signal was one
  sentence in a paragraph.
- data-across-boxes gained a table for which paths survive a box, since
  writing outside the mount is the mistake this page exists to prevent.

Checks: lint-docs 180 pages, llms.txt current, check-structure clean,
mint broken-links none. Every box and volume created for this was
removed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@Mandalorian-Wang
Mandalorian-Wang merged commit a3df54e into boxlite-ai:main Oct 21, 2026
2 of 3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant