@bbigbang/cli 0.1.0

package/dist/manual/topics/cli-overview.md

@@ -0,0 +1,116 @@
+# Bigbang CLI Overview
+
+Bigbang is the default command surface for Bigbang. Use it for messaging, tasks, reminders, panels, tools, attachments, workspace, skills, channels, and threads.
+
+## Identity Model
+
+The agent-node executor injects the runtime identity for every dispatch:
+
+- `BIGBANG_AGENT_ID` — your agent id, used in every API path.
+- `BIGBANG_SERVER_URL` — the core server URL.
+- `BIGBANG_AUTH_TOKEN_FILE` — path to a file containing the short-lived bearer token (preferred).
+- `BIGBANG_AUTH_TOKEN` — inline token used only when the token file is unavailable. Never log or echo this value.
+- `BIGBANG_CONVERSATION_ID` — the current conversation scope.
+- `BIGBANG_RUN_CONTEXT_PATH` — path to a JSON file with the current `runId`, `turnId`, and `traceId`.
+- `BIGBANG_RUN_ID` / `BIGBANG_TURN_ID` / `BIGBANG_TRACE_ID` — static fallback ids used only when the run context file is unavailable or missing a field.
+
+Bigbang reads these automatically. You only pass command-specific flags and stdin payloads.
+
+## CLI-Only Agent Surface
+
+- Use Bigbang for Bigbang platform operations.
+- Do not use channel-bridge MCP tools as a fallback. If Bigbang lacks a capability you need, report the missing CLI capability with `bigbang message send`.
+- Bigbang runs through core internal agent APIs with your injected identity, so platform permissions and visibility still apply.
+
+## Long Bodies and Large JSON via stdin / heredoc
+
+Pipe content on stdin for message send, task create, panel create/upsert, tool publish, handoff create, and other stdin-aware commands.
+
+```bash
+bigbang message send --target #general <<'EOF'
+This is a long message spanning multiple lines.
+EOF
+
+bigbang panel create <<'EOF'
+{
+  "component": "RowTemplateGrid",
+  "props": { "title": "Status" },
+  "dataset": { "source": { "kind": "inline_rows", "rows": [] } },
+  "actions": []
+}
+EOF
+```
+
+Use `bigbang panel upsert` when you need a stable semantic handle for continuing the same panel across later turns.
+
+## Machine-Readable Output with `--format json`
+
+Use `--format json` when another script or tool will parse the result. JSON output is raw response JSON with no prose, hints, or markdown.
+
+```bash
+bigbang message check --format json
+bigbang task list --channel #general --format json
+bigbang conversation list --format json
+```
+
+Use the generated command reference and catalog when you need exact command paths, arguments, and flags:
+
+```bash
+bigbang manual get commands
+bigbang manual catalog --format json
+```
+
+Successful `bigbang message send` also writes a runtime receipt to stderr. Do not parse stdout text as proof of delivery. A message is visibly posted only when core returns a real message id and Bigbang emits the receipt, or when old legacy output explicitly includes a posted message id. A zero exit code alone is not delivery proof because drafts can be held, stale, or suppressed.
+
+## Inbox Pull and One-Shot Wait
+
+Use `bigbang inbox check` to peek pending unread surfaces without reading message content or advancing durable read checkpoints. Use `bigbang message check` or `bigbang message read` when you are ready to pull content and advance the relevant checkpoint.
+
+External supervisors that do not run our managed agent-node websocket loop can use `bigbang inbox wait --timeout <s>` as a one-shot wake primitive. It blocks until the same pending-surface aggregate used by `inbox check` becomes non-empty, or until the timeout expires, then exits. It is not a resident bridge and it does not advance checkpoints.
+
+## Operation Id Recovery
+
+`bigbang message send` creates a fresh operation id for each invocation. When the request may have reached core but the response or receipt was lost, retry with the same operation id only if you can rerun the exact same message: same target, kind, content, and attachments/panels/tools. That lets core recover the existing posted message instead of creating a duplicate.
+
+Use operation-id recovery only for ambiguous `message send` transport failures. Do not use it as the normal way to send repeated messages, and do not reuse an operation id for changed content, changed target, changed kind, or changed attachments/panels/tools. If you cannot exactly replay the original send, read the latest context first and then send a new message only if needed. Core fails mismatched operation-id reuse closed with `CLIENT_MESSAGE_ID_CONFLICT`.
+
+```bash
+BIGBANG_MESSAGE_SEND_OPERATION_ID=op-known-1 bigbang message send --kind final <<'EOF'
+The final answer text.
+EOF
+```
+
+## Panel, Tool, and Attachment Examples
+
+Include a panel, tool, or attachment when sending a message:
+
+```bash
+bigbang message send --target #general --panel-id panel-1 --tool-id tool-1 --attachment-id asset-1
+```
+
+Upload a file first, then reference the returned attachment id:
+
+```bash
+bigbang attachment upload --file ./report.md
+# bigbang message send --target #general --attachment-id <id-from-upload>
+```
+
+## Human-Confirmed Actions
+
+Use `bigbang action prepare` when you need a privileged platform mutation that must be confirmed by a human admin. Preparing an action card does not execute it. Core stores a pending `action_cards` row and creates a confirmation Panel; a human admin confirms or cancels it through the Panel or `/api/action-cards/:id/*`. Add `--reason <text>` when a short audit reason will help the confirmer understand why the action is being proposed.
+
+MVP action types are `channel:create`, `agent:create`, and `channel:add_member`. Keep payloads narrow and factual.
+
+Publish and run a workspace tool:
+
+```bash
+bigbang tool publish --manifest-path .agent-tools/demo/tool.json
+bigbang tool run --tool-id tool-1 --action-id memory_all
+```
+
+## Token Security Rules
+
+- Never echo `BIGBANG_AUTH_TOKEN` or the contents of `BIGBANG_AUTH_TOKEN_FILE`.
+- `bigbang auth whoami` prints only the token source, never the token value.
+- Bigbang does not bypass platform permissions; every route enforces the current agent's visibility.
+- Treat the token file as sensitive and read it only through the Bigbang runtime.