README value-prop restructure + typed tool registration (nanocodex comparison, Workstream A)

[dennisonbertram]

Two units of work from a comparison against nanocodex, a small library-first Rust agents SDK.

README restructure

Lead with a two-paragraph value prop (local-first agent; one command, three surfaces — TUI, headless CLI, streamed HTTP API; no separate control plane), then use-case-driven sections that each open with working commands. The duplicated "What You Get" list is folded into the opener, contributor material is consolidated under "Develop this repository", and the repository map is compressed to the core directories. No factual changes — the thin-client/auto-start claims were verified against scripts/go-code.sh and cmd/harnesscli.

Typed tool registration (Workstream A)

tools.NewTyped / tools.MustTyped (internal/harness/tools/typed.go) build a Tool from a typed handler function, deriving the Parameters JSON schema by reflection from the args struct: json-tag names, omitempty/pointer optionality, desc/min/max/enum tags, nested structs, slices, maps. The schema and its decode target become one artifact that cannot drift, and per-tool unmarshal/marshal boilerplate disappears — the Go answer to nanocodex's #[tool] macro.

• Pilot migrations: glob and git_status. typed_parity_test.go locks their generated schemas against the pre-migration hand-written literals via canonical-JSON comparison, plus metadata and behavior tests (glob match/limit/error paths; git_status's absent-key-defaults-to-porcelain behavior preserved via *bool).
• Both styles coexist: NewTyped wraps the existing Tool/Handler types, so the registry, ParallelSafe/Mutating flags, policy wrapping, and approval machinery are untouched. Remaining tools migrate opportunistically.
• One deliberate error-message change: glob with empty raw args now fails pattern is required instead of a JSON parse error (the typed wrapper tolerates absent args as zero-value).
• Workstreams B (incremental internal/harness split via type aliases) and C (public Go client over the HTTP/SSE API) are planned in docs/design/nanocodex-comparison-plan.md; durable intent recorded in docs/logs/long-term-thinking-log.md.

Verification

• go test ./internal/harness/tools/... — new suites green (8 TestNewTyped* + parity/behavior tests)
• go build ./internal/... ./cmd/..., go vet ./internal/harness/tools/
• go test ./internal/server/... -run TestRunSmoke and harness Registry|Catalog tests green
• Pre-existing, unrelated failures verified against the unmodified tree via git stash: benchmarks/terminal_bench/reference_solutions doesn't build (no main), and TestEnsureWorkspaceRootUsable/non-writable_root fails when running as root

🤖 Generated with Claude Code

https://claude.ai/code/session_01UkCYKvrAo8QA9qRy4A7v3v

---

Generated by Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fd84f90da8

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Add the new design doc to the index

This commit adds a new file under docs/design, but docs/design/INDEX.md still has no entry for nanocodex-comparison-plan.md. AGENTS.md directs agents to maintain folder indexes via docs/runbooks/documentation-maintenance.md, which requires updating the local INDEX.md immediately after adding a file, so the documented navigation future agents rely on is now stale; please add a concise index entry for this plan.

Useful? React with 👍 / 👎.