Skip to content

docs: fix user-facing accuracy for --confirm, camera, and doctor - #121

Merged
DLANSAMA merged 1 commit into
mainfrom
docs/user-facing-accuracy
Aug 14, 2026
Merged

docs: fix user-facing accuracy for --confirm, camera, and doctor#121
DLANSAMA merged 1 commit into
mainfrom
docs/user-facing-accuracy

Conversation

@DLANSAMA

Copy link
Copy Markdown
Owner

PR 2 of the documentation reconciliation pass (user-facing accuracy). Each behavioral claim was checked against the cited source before editing.

What was wrong

Shipped user docs still described older behaviour in four places. README / AGENTS.md / SECURITY.md already had the current story; these files did not.

--confirm on job / send is not an exit-5 refusal

print / stop / pause / resume / delete / gcode refuse without --confirm (exit 5, "status": "confirmation_required"). job / send still download → slice → upload and exit 0 with "status": "uploaded_not_printed" — only the print step is withheld.

Verified in bambu_cli/job/orchestrate.py (the uploaded_not_printed path), bambu_cli/commands/{print_cmd,device,files,gcode}.py (the refusal path), tests/test_json_contract_cli.py (NON_REFUSING_CONFIRM_COMMANDS), and docs/api.md’s refusal-contract paragraph (already correct).

  • docs/troubleshooting.md — split the two cases
  • docs/manual.md — agent-safety paragraph and “Safety first” bullet
  • docs/api.md — dropped “may upload”; upload does run

Camera streamer is fail-closed / opt-in

A failed direct grab does not start the Docker streamer unless camera_allow_streamer / --allow-camera-streamer. Pin mismatch, and any ssl.SSLError with a pin configured, hard-abort (never streamer). No pin + insecure_tls unset: the direct grab refuses before sending the access code.

Verified in bambu_cli/commands/snapshot.py (streamer_is_allowed, pin/SSLError abort), bambu_cli/protocols/camera.py (raise before sendall when unpinned), SECURITY.md camera-pin-fallback row.

  • docs/troubleshooting.md — removed “falls back to a small streamer container” / “trying Docker streamer”
  • docs/manual.md Camera snapshots — P1/A1-direct vs X1-needs-opt-in + loopback camera_port

doctor fingerprint output is not “always print the SHA-256”

Once pinned, human plate doctor is hex-free on a match unless -v. IP is also -v-only. --json always carries certificate_fingerprint.

Verified in bambu_cli/commands/doctor.py. One handoff line was not copied verbatim: on mismatch, doctor warns and shows the first eight hex chars of the live cert — it does not print expected vs actual (that wording belongs to the MQTT/FTPS pin check in tlspin.py). The live hex on a mismatch is in plate doctor --json.

Smaller items

  • docs/manual.md slice precedence now STL > STEP/STP > OBJ > 3MF > G-code (.stp is first-class in bambu_cli/constants.py DOWNLOAD_LINK_EXTENSION_PRIORITY and slicer/cmd.py). tests/package_contents_smoke.py snippet lock updated to match.
  • docs/api.md and SECURITY.md sdist-relative links to quality-roadmap.md / test-backlog.md now use GitHub blob URLs and say those files are repo-only (not in the sdist).

Checks

  • uv run python -m pytest tests/test_docs_consistency.py -q — 7 passed
  • python scripts/cli_help_smoke.py — 21 subcommands ok
  • check_agent_docs_current() snippet lock — ok

No numbers were retouched (PR 1 / #120 already reconciled those).

Split job/send --confirm from the exit-5 refusal commands, document the
fail-closed camera streamer (opt-in, not auto-fallback), describe doctor
fingerprint output as actually implemented, include STP next to STEP, and
point sdist readers at GitHub for repo-only quality docs.
@DLANSAMA
DLANSAMA merged commit 120a516 into main Aug 14, 2026
6 checks passed
@DLANSAMA
DLANSAMA deleted the docs/user-facing-accuracy branch August 14, 2026 13:07
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