docs: reshape navigation, add concept/reference content, drop BoxRun

[Mandalorian-Wang]

Summary

This PR reshapes the BoxLite documentation site along three axes that
are tightly coupled — they have to land together to make sense.

1. Navigation

The single user-facing tab "BoxLite" is reordered into 8 groups in
user-cognition order:

Introduction → Get Started → Concepts → Tutorials →
How-to Guides → SDK Reference → Architecture → Resources

Why: the previous sidebar mixed Tutorial / How-to / Reference /
Explanation in one bucket called "Guides", buried the What is BoxLite /
Why BoxLite story behind installation, and still surfaced BoxRun even
though boxlite-ai/boxrun has been archived.

Concrete moves:

• Promote Concepts to its own top-level group so sandbox primitives
  (lifecycle / execution / filesystem / network / snapshot) finally have
  a home that isn't a sub-section of Get Started.
• Rename "Guides" → "How-to Guides" so the Diátaxis quadrant is
  unambiguous from the sidebar label alone. Sharpen tutorials/index
  and guides/index to state explicitly that tutorials are task-shaped
  step-by-steps and how-to guides are production patterns.
• Move design-principles into Introduction and rename it to
  "Why BoxLite". Append a competitor-dimension comparison table
  (deployment model / isolation / state / SDK languages) without
  naming products.
• Hide the Development tab from public navigation. The two
  internal-facing files (development/cli, development/rust-style)
  stay in the repo for direct linking but no longer surface in the
  sidebar.

2. New pages (8) + content corrections to existing pages

REST API reference (reference/rest/index.mdx):

• Endpoint inventory taken from the canonical OpenAPI spec.
• Every JSON snippet is real curl output captured from a live
  boxlite serve --port 8100 running on the validation host —
  create / start / exec / SSE output / snapshot / metrics / errors.
• Documents the URL shape /v1/{prefix}/..., the SSE event vocabulary
  (stdout / stderr base64 + exit with duration_ms + exit_code),
  and the uniform error envelope { error: { message, type, code } }.

5 concept deep-dives (concepts/):

• lifecycle — states (configured / running / stopping /
  stopped / paused / unknown), the valid transition table, and
  the precondition table for start / stop / remove / exec.
• execution — exec vs run, streaming, stdin, kill,
  resize_tty, timeout patterns, exit-code conventions.
• filesystem — copy_in / copy_out vs volume vs base64;
  ephemeral vs QCOW2-persistent disks; cross-box sharing.
• network — enabled/disabled mode, allowlist semantics, port
  forwarding, host-side secret substitution, no host privileges
  required.
• snapshot — snapshot vs clone vs export, disk-only boundary made
  explicit (no in-memory checkpoint, no host-volume capture).

Tutorial (tutorials/snapshot-fork-restore.mdx):

• End-to-end clone-based fork walkthrough; full Python script.
• Output block in the page is real stdout from a real run, not a
  synthesized example.

Go SDK reference (reference/go/index.mdx):

• API surface (Runtime, Box, options, NetworkSpec, Secret, ExecResult)
  documented from the user's perspective.
• Quick Start verified end-to-end against the main branch +
  locally-built native lib.
• Honest Known issue callout for the published v0.8.2
  wire-format mismatch with workaround using a Go module replace.

Corrections to existing pages along the way:

• Scrub every BoxRun reference from index.mdx,
  guides/ai-agent-integration.mdx, llms.txt, and CLAUDE.md. The
  product no longer exists as a separate surface.
• Trim getting-started/core-concepts.mdx to remove the Lifecycle /
  Images / Resource configuration / Security material that is now
  better placed in (respectively) the Concepts deep-dives, the
  per-language quickstarts, How-to Guides → AI Agent Integration, and
  Architecture → Security. Page keeps its only unique contribution —
  the SimpleBox / CodeBox / BrowserBox / ComputerBox / InteractiveBox
  decision table.
• Multi-language tab fixes caught while validating Quick Starts:
  • Python: low-level Execution.wait() returns an ExecResult that
    carries only exit_code + error_message; stdout / stderr
    live on the SimpleBox wrapper. Tutorial uses the appropriate
    pattern (consume stdout iterator, then await wait()).
  • Node: SimpleBox.exec(...) returns ExecResult directly — no
    .wait() step. Earlier multi-language tabs had the wrong shape.
  • Go: SimpleBox-style wrappers don't exist; reference describes
    the Runtime/Box API only.
  • box.snapshot is a property accessor, not a method
    (box.snapshot.create(name=...)).
  • box.stop() invalidates the handle; reattach via
    runtime.get(id).

3. Authoring conventions (CLAUDE.md)

Three rules that apply to every future doc edit:

1. Ground every factual claim in real code. Verify against the SDK
   or the upstream BoxLite source before writing or editing. Don't
   document what the code doesn't do.
2. Stay strictly in the user's SDK frame. No internal source
   paths, no Rust struct definitions, no pub / Vec<T> /
   Option<T> syntax in user-facing copy. Allowed external links: SDK
   module paths users import, README, OpenAPI spec, upstream
   examples/.
3. Every demo code block must be end-to-end validated. Install the
   real SDK, run in a clean environment matching the page's stated
   prerequisites, capture and match actual stdout. If you can't run it,
   don't ship it as runnable.

4. Polish and asset hygiene

• getting-started/index.mdx → getting-started/install.mdx. Mintlify
  was absorbing the /index-suffixed page into the group header,
  leaving "Installation" un-clickable in the sidebar. The new path is
  a plain Mintlify route. All inbound links rewritten across faq /
  quickstart-nodejs / guides/index / llms.txt / Python & Rust
  references.
• Logo and favicon: pull logo/{light,dark}.png from
  boxlite-website/public so docs share the marketing brand assets.
  Replace the 1 MB favicon.svg with the 30 KB favicon.png (the
  same square icon the marketing site uses).

What is intentionally NOT included

• A dedicated introduction/vs-competitors page — held back until
  legal / marketing review. The neutral comparison table inside
  Why BoxLite is the stand-in.
• Splitting architecture/networking-storage.mdx into separate
  networking + storage pages — left for a follow-up after the
  Concepts pages have stabilised.
• DX tooling (Copy-for-LLM button, Mermaid diagrams, RAG search) —
  not in scope here.

Test plan

• npx mint broken-links → no broken links found.
• Python Quick Start runs end-to-end on macOS Apple Silicon
  against a real micro-VM (python:slim).
• Node.js Quick Start runs end-to-end on macOS Apple Silicon
  against a real micro-VM (python:slim).
• Go Quick Start runs end-to-end on macOS Apple Silicon against
  a main-built native library (STDOUT: Hello from BoxLite Go!).
• tutorials/snapshot-fork-restore.mdx script runs end-to-end;
  captured stdout matches the Output block in the page.
• REST examples captured live from boxlite serve v0.8.2; URLs,
  JSON shapes, and SSE events all verified.
• Sidebar renders 8 groups in the documented order; Installation
  is clickable; Development tab is hidden.
• Search the site for BoxRun / boxrun returns only changelog
  history, no live references.

🤖 Generated with Claude Code