@cam5/baby-bird 0.1.0 → 0.1.1

package/README.md

@@ -60,6 +60,7 @@ bb --json | jq         machine-readable tour
 bb --dump-prompt       print the prompt instead of calling the model
 bb --refresh           regenerate even if a cached tour exists
 bb --preset claude-sonnet
+bb --no-progress       no live status block
 ```
 
 ### What does bare `bb` tour?
@@ -93,6 +94,8 @@ All keys, with defaults:
     "args": [],                // extra argv appended to the preset's command
     "command": null,           // a whole custom invocation; when set, "preset" is ignored
     "promptVia": null,         // "stdin" (default) or "arg" (replace {prompt} in argv)
+    "kind": null,              // "claude" (streams progress from the Claude Code CLI) or "plain"; default from the preset
+    "jsonSchema": false,       // Claude kind: also pass --json-schema so the CLI validates the answer (see below)
     "timeoutMs": 180000,
     "maxPromptBytes": 200000,  // larger diffs are truncated, biggest files first
     "env": {}                  // extra environment for the command
@@ -103,11 +106,21 @@ All keys, with defaults:
     "exclude": ["**/pnpm-lock.yaml", "**/package-lock.json", "**/yarn.lock", "**/Cargo.lock",
                 "**/*.min.*", "**/dist/**", "**/*.snap", "**/*.map"]
   },
-  "render": { "color": "auto", "pager": "auto", "maxExcerptLines": 60, "width": null },
+  "render": {
+    "color": "auto", "pager": "auto", "maxExcerptLines": 60, "width": null,
+    "highlight": "auto",       // syntax colors in excerpts on 256-color terminals; "always" | "never"
+    "theme": "dark"            // background tint palette for added/removed lines; "light" for light terminals
+  },
   "cache":  { "enabled": true, "dir": null }  // default $XDG_CACHE_HOME/baby-bird
 }
 ```
 
+### While it generates
+
+On a terminal, `bb` shows a small live status block on stderr (stdout stays clean for piping): a spinner with the current stage and elapsed time, then, for Claude presets, a reasoning indicator, and finally each section title as the answer takes shape. If the CLI rejects an answer against the schema you see that too, and the section list starts over when the model resubmits. When the tour lands the block is replaced by one dim summary line (time, tokens, model). Turn it off with `--no-progress`; it is also off when stderr is not a TTY or `--debug` is on.
+
+About that reasoning indicator: Claude Code's print mode (2.1.x) streams thinking *heartbeats* roughly every second but with empty text, both in the deltas and in the final message, so `bb` shows a pulse trail that grows with each heartbeat rather than the words. The rolling text window is implemented and takes over automatically whenever a runner does include reasoning text.
+
 ### LLM presets
 
 The model is just a command: the prompt goes in on stdin, the answer comes out on stdout. Built-in presets:
@@ -141,8 +154,16 @@ bb --preset local
 BB_LLM_COMMAND='llm -m gpt-4.1' bb
 ```
 
+Presets have a `kind`. The built-in Claude presets are `"claude"`: `bb` appends `--output-format stream-json --verbose --include-partial-messages` so the status block can show reasoning heartbeats and section titles as they stream; the answer text is then extracted like any other (fences, prose, and the odd unescaped quote are tolerated, with one repair round-trip if needed). Everything else is `"plain"`: stdout is the answer. Set `"kind": "claude"` on your own preset when it wraps the Claude Code CLI, or `llm.kind` to override for a run.
+
+`llm.jsonSchema: true` additionally passes `--json-schema` so the CLI validates the answer itself. It is off by default: on Claude Code 2.1.270 the model's first structured call is rejected about five times in six (it emits tool-call placeholders such as `$PARAMETER_NAME` as top-level keys), and although the CLI makes it retry, every rejection costs a full extra answer. Worth re-checking on newer versions.
+
 The effective command is part of the cache key, so switching presets regenerates the tour instead of reusing another model's.
 
+### Excerpt highlighting
+
+On a 256-color terminal, excerpts get language-aware token colors (keywords, strings, comments) chosen by file extension, and added/removed lines are marked by a bold `+`/`-` sign plus a subtle green/red row tint underneath, so both signals read at once. The token palette never uses green or red. Turn it off with `--no-highlight` or `render.highlight: "never"`, and pick `--theme light` (or `render.theme`) on a light terminal background. Files with no known language keep the plain green/red rendering.
+
 ### Code host
 
 With `codehost.provider` set to `gh` (the default), `bb` uses the `gh` CLI to find the current branch's pull request. Its base branch decides what to compare against and its title and body are included in the prompt. Nothing else is read, and no tokens are handled by `bb`. If `gh` is missing or not logged in, the lookup is silently skipped. Set the provider to `none` to turn it off.