Docs update: --porcelain machine-readable output flag (v0.7.0)

[Sephyi]

Context

CommitBee v0.7.0 (shipping in roughly the next 1–2 weeks) introduces a new --porcelain flag for machine-readable output. The feature is tracked upstream in Sephyi/commitbee#6. This issue tracks the corresponding documentation updates needed here before (or shortly after) v0.7.0 ships.

Summary of what the flag does

--porcelain puts CommitBee into a machine-readable output mode:

• stdout contains exactly the sanitized commit message plus a single trailing \n
• All spinners, live-streamed LLM JSON, info/warning lines, tracing output, and ANSI styling are silenced
• Errors still flow to stderr (plain-text, no ANSI / OSC8 hyperlinks) with a non-zero exit code so scripts can detect failure without parsing stdout
• Implies --dry-run and --no-split
• Rejected at argument-parse time (exit code 2) when combined with --yes, --clipboard, --show-prompt, --verbose, -n/--generate, or any subcommand
• The stdout structural contract (one message, trailing \n, UTF-8, no decoration) is stable from v0.7.0 onward; the content (wording) depends on the configured LLM and is not stability-guaranteed

Pages that need edits

• content/docs/commands-and-flags.md — Add --porcelain as a new flag entry covering behaviour, stdout contract, implied flags, and the full rejected-combinations table. Natural placement is near --clipboard and --dry-run since they're thematically related (output-destination flags).
• content/docs/getting-started.md — Consider adding a short Piping into other tools example under Usage:

  # Validate the generated message
  commitbee --porcelain | commitlint
  
  # Preview with syntax highlighting
  commitbee --porcelain | bat -l gitcommit

• content/docs/advanced-workflows.md — Add a Piping and scripting section covering editor integrations, validators, prepare-commit-msg hooks, and release-notes pipelines. Include the stability caveat (structural vs content).
• content/docs/ci-cd-integration.md — Mention --porcelain as the recommended way to integrate CommitBee into CI pipelines; it replaces the current --dry-run --yes 2>/dev/null workaround and no longer swallows real errors.
• content/docs/git-hooks.md — The prepare-commit-msg example can be simplified with --porcelain:

  # before
  MSG=$(commitbee --yes --dry-run 2>/dev/null)
  if [ $? -eq 0 ] && [ -n "$MSG" ]; then
      printf '%s\n' "$MSG" > "$COMMIT_MSG_FILE"
  fi
  
  # after (v0.7.0+)
  commitbee --porcelain > "$COMMIT_MSG_FILE"

  Worth calling out that the new form surfaces real errors (they reach stderr with a non-zero exit), which the previous 2>/dev/null workaround hid.
• content/docs/troubleshooting.md — Add a brief section Using --porcelain in scripts and getting errors. Point readers at stderr (which carries the error message) and the non-zero exit code.

Reference material

• Upstream issue: Add --porcelain flag for clean, pipeable commit-message output commitbee#6
• CLI implementation: on the development branch of Sephyi/commitbee, shipping in v0.7.0
• Install for preview:

  cargo install --git https://github.com/Sephyi/commitbee --branch development commitbee

Timing

CommitBee v0.7.0 release is targeted for roughly the next 1–2 weeks. Docs updates should land either before the release or very shortly after.

Notes for the writer

• The stability caveat (structural contract stable, content LLM-dependent) is worth making explicit in commands-and-flags.md so users don't file bugs when message wording changes between LLM versions.
• --porcelain and the future --format=<json|…> modifier are designed to be orthogonal: the first controls stdout cleanliness, the second will control output shape. Mentioning this forward-compat design preempts "why not just --json?" questions.
• The flagship example pitch for --porcelain is integration — piping into validators, editors, hooks, and CI. Lead with that, not with "silences output."