[albertwoo]

What changes

Two changes to dotnet cui, both about being readable by a person or an agent:

1. The tool carries the documentation (D11) — docs, docs read, docs search answer from
   the guide embedded in the package, offline, before any project is resolved.
2. The command line is declared, not parsed by hand (D12) — System.CommandLine owns the
   grammar, so the help cannot disagree with the parser.

dotnet tool install -g CuiSharp.Tools
dotnet cui docs                          # the 14 task topics and the bundled documents
dotnet cui docs read debugging           # a topic, whole
dotnet cui docs search "decimate chart"  # ranked sections, each with the read that opens it
dotnet cui api ChartOpts --json          # exact declarations
dotnet cui tree -a 15036                 # drive a live window by pid

The bug that prompted the rewrite

The hand-written help had drifted from the hand-written parser:

Help said	Parser did
-a, --attach [id]	-a took no value → the id became a positional word
—	-t, --target <id> worked but was documented nowhere

So dotnet cui click "中文" -a 15036 searched for a widget whose label was 中文 15036 and
correctly reported that none existed. The label was fine; the grammar was not.

What the declared grammar gives a reader

• a mistyped verb names the verb meant: clik Save → Did you mean `dotnet cui click`?
• a bad value is a sentence about the value (as a whole number), not a CLR type name
• --json exists only on the four commands that answer JSON, so it cannot be typed where it would
  be ignored
• --version answers with a version instead of falling through to the help screen
• usage errors exit 2 on stderr; a bare dotnet cui prints the help there rather than into a pipeline
• a repeated option is refused instead of being decided by whichever occurrence came last
• --help works per verb, and dotnet cui click --help does not demand the label it is explaining

Two rules survive because the wire protocol needs them: everything after a standalone -- goes to
the app untouched, and a value is a value even when it begins with a dash (--wait-text -loading).

Design

The verbs are the app's wire protocol, not the tool's invention. Grammar.Resolve re-serialises
one command's typed arguments into exactly one protocol line (click Save, wheel 120 400 -8), so
the parser changed and the protocol did not. Cli.Options keeps its shape and Cli.Run keeps
dispatching, so the headless client, the live client and the offline answers are untouched.

A topic is a named list of doc#section pointers resolved at load, not a second copy of the
prose — every sentence keeps one home, and a renamed heading fails a test rather than leaving a
topic that answers confidently and misleads. The pages are embedded, and a test compares the bytes
with the checked-in files.

Verification

• Release build -warnaserror and dotnet format --verify-no-changes — clean
• 947 + 28 tests passed, 0 failed (95 of them the CLI grammar)
• regen.ps1 -NoNative -NoDiff — bindgen no diff, self-test 14/14, export-api: no diff
• verify-template.ps1 including AOT — file-based app still 1,163,264 B; System.CommandLine is a
  dependency of the tool only, so no app binary moved
• Installed tool, isolated --tool-path, empty directory, no repo, no network: --help, --version,
  docs, docs read, docs search, api --json, icons, ps all answer
• Against a real live window: tree -a 15036, click "中文" -a 15036, click "中文" -a and
  --attach=15036 all drive it, and the click visibly switches the app's language badge

Honest limits

• The generated usage line reads dotnet-cui [command], which is the installed shim's own name;
  dotnet cui is the documented invocation. S.CL 3.0 exposes no hook to rename the root.
• A value that looks like a flag is still a value (--project --json sets the project to --json)
  because --wait-text -loading requires that rule.
• -a 15036 and a bare -a are both accepted; the bare form needs exactly one live window.
• Per-harness skill registration is deliberately not generated; dotnet cui docs is the portable
  form (docs/PLAN.md).
• skills/cui-dotnet/api/*.md (59 pages, ~200 KB) are embedded, taking the tool package to 516 KB.