Help: show task, model and common options in brief help

README.md

@@ -120,7 +120,7 @@ tinyagent --read-only --cwd ~/src/project -t "Review error handling in pkg/api"
 cat review-task.md | tinyagent --read-only -t - -o review.json
 ```
 
-Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview and `tinyagent --help --verbose` for every flag. Subcommands are shortcuts for common flags: `tinyagent sandbox`, `tinyagent memory list`, `tinyagent ratchet list`, `tinyagent planner --first`, `tinyagent plugins list`, `tinyagent tinygo status` (see [CLI reference](docs/subcommands.md)); each one alone, such as `tinyagent sandbox`, prints its help.
+Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview: usage, two examples, the common options (`-t/--task`, including `-t -` for stdin; `-m/--model` with its providers and default; `-c`, `--cwd`, `--resume`, `--read-only`, `-o`, `--json`, `--check`, `--update`, `-V`) and the subcommands, and `tinyagent --help --verbose` for every flag. Subcommands are shortcuts for common flags: `tinyagent sandbox`, `tinyagent memory list`, `tinyagent ratchet list`, `tinyagent planner --first`, `tinyagent plugins list`, `tinyagent tinygo status` (see [CLI reference](docs/subcommands.md)); each one alone, such as `tinyagent sandbox`, prints its help.
 
 ## Features
 
@@ -133,7 +133,7 @@ Run `tinyagent --help` (or plain `tinyagent` at a terminal) for the overview and
 - A task planner that can require a plan before any change.
 - Run budgets: turn cap, cost limit and token limit (`--token-limit`), with an 80% warning to the model; delegates, workers and `--attempts` share the budget, and a run that hits it can be resumed.
 - Verify before stop (`--verify-on-stop`): a run that changed files isn't accepted until a test or build command passes; otherwise it is marked unverified. Optional computational checks (`--verify-check`, e.g. lint, type check, tests) run in order, cheapest first, before the run may finish; see [Computational checks](docs/verify.md#computational-checks). An optional inferential review (`--verify-review`) runs last, once every check passes, and reports the model's findings; see [Inferential review](docs/verify.md#inferential-review).
-- Help everywhere: `tinyagent` or `tinyagent <subcommand>` alone at a terminal prints help; `--help --verbose` lists every flag by section.
+- Help everywhere: `tinyagent` or `tinyagent <subcommand>` alone at a terminal prints help (the top-level one shows how to pass the task, pick the model and the common options); `--help --verbose` lists every flag by section.
 - `tinyagent --update`: checksum-verified self-update with step-by-step progress and a `#` download bar.
 - Undo for file edits, workspace rewind, resume and follow-up runs.
 - Sandboxed commands with a network allowlist, permission rules, hooks, untrusted-content lockdown and file-access rules.

cmd/tinyagent/help.go

@@ -23,16 +23,44 @@ tinyagent --help --verbose for every flag, or see docs/subcommands.md.
 // helpBrief is the default --help output: usage, one sentence, every
 // subcommand with a one-line description (built from subcommands, so none
 // can be left out), and pointers to the detailed views.
-var helpBrief = helpHeader + "\n" + helpFooter
+var helpBrief = helpIntro + "\n" + helpEssentials + helpSubcommands() + "\n" + helpFooter
+
+// helpEssentials is the brief help's Examples and Common options: how to
+// pass the task, pick the model and provider, and the most-used flags.
+// TestBriefHelpShowsEssentials checks each flag named here exists.
+var helpEssentials = `Examples:
+  tinyagent -t "fix the failing test in ./pkg"
+  git diff | tinyagent -t - -m anthropic/claude-sonnet-4-5 --read-only
+
+Common options:
+  -t, --task string    the task/prompt; "-" reads it from stdin
+  -m, --model string   provider/model: openai, anthropic, openrouter or ollama
+                       (default $AGENT_MODEL, else config model, else ` + builtinModel + `)
+  -c, --config path    YAML config (default: user config if present)
+      --cwd dir        working directory (default .)
+      --resume path    continue or follow up a run saved with -o <path>
+      --read-only      only read files; no edits or commands
+  -o, --output path    write the trajectory JSON
+      --json           write run events as JSONL to stdout
+      --check          show resolved config, model and key status; no model call
+      --update         update to the latest release, showing each step
+  -V, --version        print the version
+
+`
 
 // helpHeader is helpIntro plus the Subcommands section; --help --verbose
 // prints it before the flag sections and helpFooter after them.
 var helpHeader = buildHelpHeader()
 
 func buildHelpHeader() string {
+	return helpIntro + "\n" + helpSubcommands()
+}
+
+// helpSubcommands is the Subcommands section: every subcommand with its
+// one-line description.
+func helpSubcommands() string {
 	var b strings.Builder
-	b.WriteString(helpIntro)
-	b.WriteString("\nSubcommands:\n")
+	b.WriteString("Subcommands:\n")
 	width := 0
 	for _, s := range subcommands {
 		width = max(width, len(s.name))

cmd/tinyagent/help_test.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 	"os"
 	"reflect"
+	"regexp"
 	"sort"
 	"strings"
 	"testing"
@@ -21,8 +22,8 @@ func TestDefaultHelpIsBrief(t *testing.T) {
 			t.Fatalf("%v exit = %d", args, code)
 		}
 		lines := strings.Split(strings.TrimSuffix(got, "\n"), "\n")
-		if len(lines) > 15 {
-			t.Errorf("%v: %d lines, want <= 15:\n%s", args, len(lines), got)
+		if len(lines) > 40 {
+			t.Errorf("%v: %d lines, want <= 40:\n%s", args, len(lines), got)
 		}
 		for _, l := range lines {
 			if len(l) > helpWidth {
@@ -38,6 +39,32 @@ func TestDefaultHelpIsBrief(t *testing.T) {
 	}
 }
 
+// TestBriefHelpShowsEssentials checks the brief help shows how to pass the
+// task (including stdin), the model/provider and its default, and the
+// common options, and that every flag it names is a real flag.
+func TestBriefHelpShowsEssentials(t *testing.T) {
+	_, got, _ := runWith(t, "--help")
+	for _, want := range []string{
+		"Examples:\n", "Common options:\n", "-t, --task", `"-" reads it from stdin`,
+		"-m, --model", "openai, anthropic, openrouter or ollama", "$AGENT_MODEL", builtinModel,
+		"-c, --config", "--cwd", "--resume", "--read-only", "-o, --output", "--json",
+		"--check", "--update", "-V, --version",
+	} {
+		if !strings.Contains(got, want) {
+			t.Errorf("brief help lacks %q:\n%s", want, got)
+		}
+	}
+	if strings.Index(got, "Common options:") > strings.Index(got, "Subcommands:") {
+		t.Errorf("want Common options before Subcommands:\n%s", got)
+	}
+	fs := newFlagSet(&options{})
+	for _, name := range regexp.MustCompile(`(?:^|[\s|(/])--?([a-zA-Z][a-z-]*)`).FindAllStringSubmatch(helpEssentials, -1) {
+		if fs.Lookup(name[1]) == nil {
+			t.Errorf("brief help names unknown flag -%s", name[1])
+		}
+	}
+}
+
 // TestHelpListsEverySubcommand checks --help names every registered
 // subcommand (including tinygo) on its own line with a description, and no
 // subcommand that doesn't exist.

docs/subcommands.md

@@ -23,7 +23,7 @@ Six subcommands are shortcuts for existing flags. They rewrite the command line
 - Any other flag (`-t`, `-m`, `--cwd`, ...) can follow. `--` followed by words is the task: `tinyagent planner --first -- fix the bug`.
 - The first word counts as a subcommand only when it is exactly the name and is alone or followed by an option, `--`, a known action or `help`. So `tinyagent memory leaks in parser` is not a subcommand; it fails as before with "pass the task with -t". To start a task with one of these words, use `-t "memory ..."`.
 - An unknown option exits 2 with `unknown <sub> option --x (see tinyagent <sub> --help)`.
-- Help: `tinyagent <sub> --help`, `-h`, `tinyagent <sub> help` or `tinyagent help <sub>`. A bare `tinyagent <sub>` with nothing after it prints the same help. For `ratchet`, `plugins` and `tinygo` that's always so; for `sandbox`, `memory` and `planner` it's so at an interactive terminal, and with stdin piped or redirected they still run with their flags (so without `-t` they exit 2 with `--task is required`, as before). Plain `tinyagent --help` (or `tinyagent` with no arguments at a terminal; with stdin piped and no arguments it still exits 2 with `--task is required`) shows the usage line and every subcommand (`sandbox`, `memory`, `ratchet`, `planner`, `plugins`, `tinygo`) with a one-line description; `tinyagent --help --verbose` lists every flag, grouped into sections (task, model and provider, run control, verify before stop, attempts, review, output and logging, sandbox and permissions, context and tools, project rules (ratchet), memory and planner, plugins and TinyGo, rewind, workflow and eval, setup and info).
+- Help: `tinyagent <sub> --help`, `-h`, `tinyagent <sub> help` or `tinyagent help <sub>`. A bare `tinyagent <sub>` with nothing after it prints the same help. For `ratchet`, `plugins` and `tinygo` that's always so; for `sandbox`, `memory` and `planner` it's so at an interactive terminal, and with stdin piped or redirected they still run with their flags (so without `-t` they exit 2 with `--task is required`, as before). Plain `tinyagent --help` (or `tinyagent` with no arguments at a terminal; with stdin piped and no arguments it still exits 2 with `--task is required`) shows the usage line, two examples, a Common options block (`-t/--task` with `-t -` for stdin, `-m/--model` with the providers `openai`, `anthropic`, `openrouter`, `ollama` and its default — `$AGENT_MODEL`, else the config's model, else `openai/gpt-4o` — then `-c/--config`, `--cwd`, `--resume`, `--read-only`, `-o/--output`, `--json`, `--check`, `--update`, `-V/--version`), and every subcommand (`sandbox`, `memory`, `ratchet`, `planner`, `plugins`, `tinygo`) with a one-line description; `tinyagent --help --verbose` lists every flag, grouped into sections (task, model and provider, run control, verify before stop, attempts, review, output and logging, sandbox and permissions, context and tools, project rules (ratchet), memory and planner, plugins and TinyGo, rewind, workflow and eval, setup and info).
 - `ratchet` records [project rules](ratchet.md) learned from agent failures.
 - `plugins rollback` and `plugins prune` manage the plugin module version store; see [Plugins](plugins.md#webassembly-plugin-modules).
 - `tinygo` manages the TinyGo compiler used to build Go plugin modules. **TinyGo is an external dependency, not part of tinyagent:** it is never embedded in the tinyagent binary or repository. tinyagent downloads a pinned TinyGo release on first use (or with `tinygo install`), verifies its SHA-256 checksum and caches it locally; `tinygo update` moves to the version pinned in the current build.