docs: rewrite README with complete usage guide

[beogip]

Summary

• Rewrote the Usage section with working examples derived from the test fixture (tests/fixtures/dummy-tool.ts)
• Added examples for all three output levels (L1 data, L2 classification, L3 instructions), error handling with ToolError, built-in schema/help subcommands, and programmatic .invoke()
• Added a "Code-First Agents Pattern" section linking to the spec repo for readers new to the pattern
• Fixed the old Usage example which used a non-existent API

Test plan

• Verify all code examples match the current API surface
• Confirm links to the spec repo and spec file resolve correctly
• Review rendered markdown on GitHub for formatting

[greptile-apps]

Greptile Summary

This PR rewrites the README's Usage section with working examples derived from tests/fixtures/dummy-tool.ts, covering all three output levels, error handling, built-in subcommands, and programmatic .invoke(). It also adds a "Code-First Agents Pattern" section linking to the spec repo.

• All code snippets have been verified against src/output-helpers.ts, src/tool-class.ts, and src/args.ts — the Tool constructor, subcommand, run, and invoke signatures, l1Output/l2Output/l3Output helpers, ToolError, and all five documented framework error codes (unknown_subcommand, input_validation_error, schema_violation, non_object_return, unexpected_error) match the implementation exactly.
• The two issues flagged in previous review threads — the missing non_object_return error code and the ToolError example that leaked user input into the error-code slot — are both addressed in this PR.

Confidence Score: 5/5

Documentation-only change; no runtime code is modified. All code examples match the current implementation.

Every code snippet in the new Usage section was cross-checked against the source files and the dummy-tool.ts fixture. API signatures, output helpers, error codes, CLI flag parsing, and the .invoke() contract are all accurately represented. No new source files are touched.

No files require special attention.

Important Files Changed

Filename	Overview
README.md	Complete usage guide rewrite — all code examples match the current API surface and fixture; previous thread issues (missing non_object_return error code, ToolError code-slot misuse) are resolved in this PR.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["tool.run(argv) / tool.invoke(name, args)"] --> B{Builtin subcommand?}
    B -- "schema / help" --> C["Return schema/help envelope\n{ok: true, ...}"]
    B -- No --> D{Registered subcommand?}
    D -- No --> E["unknown_subcommand envelope\n{ok: false, error: 'unknown_subcommand'}"]
    D -- Yes --> F[Validate input against Zod schema]
    F -- Fail --> G["input_validation_error envelope\n{ok: false, error: 'input_validation_error'}"]
    F -- Pass --> H["await handler(validatedInput)"]
    H -- "throws ToolError" --> I["toolError envelope\n{ok: false, error: customCode}"]
    H -- "throws Error" --> J["unexpected_error envelope\n{ok: false, error: 'unexpected_error'}"]
    H -- "non-object return" --> K["non_object_return envelope\n{ok: false, error: 'non_object_return'}"]
    H -- "plain object" --> L["Stamp ok: true, validate output schema"]
    L -- Fail --> M["schema_violation envelope\n{ok: false, error: 'schema_violation'}"]
    L -- Pass --> N["Success envelope\n{ok: true, message, ...data}"]

Loading

_{Reviews (2): Last reviewed commit: "docs: fix ToolError example and add miss..." | Re-trigger Greptile}