Improve discoverability and self-documentation of @tool

[PerishCode]

Problem

runseal @tool --help exposes a long flat list of built-in tools, but it is still hard to understand what is actually available and how each tool is meant to be used at low cost.

As a first-time reader, I can see names like:

• json get
• fs list
• ssh script run
• cloudflare zone dns-record update

There is some partial discoverability today: if you try certain intermediate paths such as runseal @tool json get --help or runseal @tool ssh script --help, the command returns a usage: line.

That helps a bit, but it is still not the same as having a formal, progressive help surface.

I still do not know, at low cost:

• which paths support only fallback usage: output vs real structured help
• what the exact argv contract is beyond the one-line summary
• what input/output shape to expect for JSON-oriented commands
• which commands are intended for end users vs wrapper authors
• how to discover a namespace progressively instead of reading one large flat list

The current top-level help says:

@tool is the runseal atomic tool runtime.

That is directionally useful, but still too abstract when trying to actually learn the built-in tool surface.

Why this matters

@tool looks like an important low-level building block for wrapper authors, but the current discovery path is relatively expensive:

1. run runseal @tool --help
2. read a flat command inventory
3. probe subpaths and infer behavior from usage: errors
4. potentially go to source code to understand details

That makes the built-in tool surface harder to adopt than it needs to be.

Repro context

• runseal v0.6.0-beta.1
• observed on macOS
• started from runseal --help, then runseal @tool --help
• additional probes:
  • runseal @tool json --help -> unknown tool command: json --help
  • runseal @tool fs --help -> unknown tool command: fs --help
  • runseal @tool json get --help -> usage: runseal @tool json get <json> <path>
  • runseal @tool ssh script --help -> usage: runseal @tool ssh script run|capture --config <path> --host <host> --file <path> -- <args...>
  • runseal @tool cloudflare zone dns-record --help -> usage: runseal @tool cloudflare zone dns-record list|create|update ...

Suggested improvements

Any subset of these would help a lot:

1. Add hierarchical help:
   • runseal @tool <namespace> --help
   • runseal @tool <namespace> <command> --help
2. Keep the current compact usage: behavior if desired, but pair it with a richer help mode.
3. Add short examples for each command in help output.
4. Distinguish clearly between:
   • wrapper-author primitives
   • user-facing operational helpers
5. Add one machine-readable listing mode, for example:
   • runseal @tool --json
   • or runseal @tool @list
6. Add a docs page dedicated to @tool, with namespace-by-namespace examples.

Expected outcome

A user should be able to discover the built-in tool surface incrementally and answer “what can this command do, what arguments does it expect, and what does it print?” without needing to inspect the implementation.

[PerishCode]

Implemented the first concrete slice of this in #41, now merged to main and shipped in v0.6.0-beta.5.

What changed:

• Added progressive help for @tool namespace paths:
  • runseal @tool <namespace> --help
  • runseal @tool <namespace> <group> --help
  • existing concrete command --help paths now return success-state help instead of falling through to unknown tool command in the covered cases
• Added integration coverage for representative paths such as:
  • @tool json --help
  • @tool json get --help
  • @tool ssh script --help
  • @tool cloudflare zone dns-record --help

Examples that now work as intended:

• runseal @tool json --help
• runseal @tool fs --help
• runseal @tool ssh script --help
• runseal @tool cloudflare zone dns-record --help

Shipped via:

• PR: tool: add progressive help #41
• commit: 8b77ea2
• beta release: v0.6.0-beta.5

What this does not do yet:

• no machine-readable @tool --json listing yet
• no command-by-command examples beyond the current usage/help text
• no stronger taxonomy split between wrapper-author primitives and operator-facing helpers yet

So the discoverability problem is materially improved, but not fully exhausted. I think the next logical step, if we keep pushing, is a structured listing mode rather than a larger prose doc surface.

[PerishCode]

Tried this again on v0.6.0-beta.5.

The change is definitely useful: namespace-level discovery is now much better, and runseal @tool json --help / runseal @tool fs --help are enough to get oriented quickly.

That said, I still find the flow a bit not-quite-in-hand once I go past the namespace layer.

What still feels rough in practice:

• many group paths still only return compact usage: lines rather than a proper help page
  • runseal @tool ssh config --help -> usage: runseal @tool ssh config host|identities ...
  • runseal @tool cloudflare zone --help -> usage: runseal @tool cloudflare zone get|ruleset|dns-record ...
• concrete commands still tend to stop at argv shape, without enough guidance on flags / behavior / output shape
  • runseal @tool ssh config identities --help -> usage: runseal @tool ssh config host <host> --config <path>
  • runseal @tool cloudflare zone dns-record update --help -> usage: runseal @tool cloudflare zone dns-record list|create|update ...
  • runseal @tool fs list --help is better because it already exposes optional flags inline: [--glob <pattern>] [--files] [--dirs] [--require-nonempty]

So my current take is:

• namespace-level help: good enough now
• group-level help: still thin
• concrete command help: still inconsistent

If you keep iterating on this, I think the highest-value next slice is:

1. make every intermediate group path return a real help page, not just usage:
2. make every concrete command --help show its optional flags and one minimal example
3. keep the machine-readable listing idea on the roadmap, but I agree it is probably after the above

In short: materially improved, but I would still keep the issue open for another pass.

[PerishCode]

Follow-up pass is now in #42.

This round does not just add more help text; it changes the help model itself.

What changed:

• moved @tool progressive help onto a flat dot-path registry model
  • examples: ssh.config, ssh.config.identities, cloudflare.zone.dns-record.update
• argv path parsing is now uniform: path -> dot-key -> one registry lookup -> one shared renderer
• that replaced the earlier path-shape branching / large nested matching approach

Coverage expanded in the same pass:

• json.*
• string.*
• regex.*
• int.*
• process.*
• archive.local*
• fs*
• gitee.repo*
• gitee.pr*
• github.pr.checks.probe
• ssh.config*
• ssh.script*
• cloudflare.config*
• cloudflare.api*
• cloudflare.zone*
• cloudflare.zone.ruleset*
• cloudflare.zone.dns-record*
• cloudflare.account*
• cloudflare.redirect-rule.exact

So the current state is closer to a real progressive help substrate rather than a collection of special cases. After merge/release I will update this thread with the shipped beta.

[PerishCode]

Shipped now.

• PR: tool: unify progressive help registry #42
• merge commit: b36eb8b
• beta release run: 27199260071
• current beta: v0.6.0-beta.6

This is the pass that moved @tool progressive help onto the flat dot-path registry model and expanded coverage across the current built-in tool surface.

At this point the issue is no longer just "namespace help exists"; the underlying help substrate is also in much better shape for future expansion (@tool --json, richer examples, stricter taxonomy, etc.).

[PerishCode]

Retried on v0.6.0-beta.6.

This is much better overall. The structural change in #42 is visible in practice: group-level help is now substantially more usable, and many concrete commands have real help pages with flags and examples.

Examples that now look good:

• runseal @tool ssh config --help
• runseal @tool ssh config identities --help
• runseal @tool cloudflare zone --help
• runseal @tool cloudflare zone dns-record update --help
• runseal @tool fs list --help

I do still see two remaining inconsistencies worth tightening:

1. Some concrete commands still only return the older compact usage: form

   • runseal @tool json get --help -> usage: runseal @tool json get <json> <path>

2. Some concrete commands do not seem to intercept --help at all and instead continue into normal arg validation

   • runseal @tool gitee pr merge --help -> Error: --owner is required

So my updated take is:

• the main discoverability issue is largely resolved in beta.6
• the remaining work is now mostly consistency cleanup across the concrete command surface

If you want one more pass after this, I would focus specifically on the invariant:

• every valid @tool ... --help path should render help successfully
• no valid help path should fall through into required-flag validation
• no concrete command should regress to bare usage: if the newer richer renderer exists for its peers

[PerishCode]

One more consistency pass is in #43.

This round specifically targeted the invariant discussed above:

• every valid @tool ... --help path should render help successfully
• valid help paths should not fall through into required-flag validation

Concrete fixes in this pass include:

• runseal @tool json get --help now returns a real help page instead of the older compact usage: form
• runseal @tool gitee pr merge --help now renders help instead of falling through to --owner is required
• runseal @tool archive local import --help now renders command help directly

The same cleanup also split a few previously grouped concrete-command registry nodes into explicit keys so the help surface is more uniform.

[PerishCode]

A substantial part of this has now landed and is available in .\n\nWhat shipped:\n\n- progressive hierarchical help for paths\n- flat dot-path registry internally, with layered lookup externally\n- richer namespace / subgroup help instead of only fallback strings\n- examples on concrete entries\n\nExamples that now work as proper progressive help:\n\n- Usage: runseal @tool json [args]

JSON helpers:
get print one JSON value
empty print true when JSON length is zero
len print JSON array/object/string length
pretty ... print formatted JSON
find print first object with field=value
filter ... print objects with field matching values\n- Usage: runseal @tool json pretty [args]

Print formatted JSON with explicit input mode selection.

Modes:
value pretty-print one JSON argument
stdin read JSON from stdin and print formatted output
file read one file and write formatted JSON

Examples:
runseal @tool json pretty value '{"a":1}'
echo '{"a":1}' | runseal @tool json pretty stdin
runseal @tool json pretty file input.json output.json\n- Usage: runseal @tool json pretty value

Pretty-print one JSON argument with indentation.

Examples:
runseal @tool json pretty value '{"a":1}'\n- Usage: runseal @tool ssh config [args]

SSH config helpers:
host --config print true when any Host pattern matches
identities --config [--base ] print IdentityFile paths as JSON

Examples:
runseal @tool ssh config host bandwagon --config ~/.ssh/config
runseal @tool ssh config identities --config ~/.ssh/config\n- Usage: runseal @tool cloudflare zone dns-record [args]

Cloudflare DNS record helpers:
list --zone-id [--name ] list records in one zone
create --zone-id --json create one record
update --zone-id --record-id --json update one record\n\nThis also got exercised again while landing the new JSON pretty modes, so the help tree and the command tree were updated together rather than drifting.\n\nWhat is still not done from this issue:\n\n- no machine-readable / listing mode yet\n- no explicit end-user vs wrapper-author classification layer yet\n- no standalone docs page yet beyond help text / README absorption\n\nSo I would treat this issue as partially addressed in beta, with the remaining gap now mostly around machine-readable discovery and classification rather than basic progressive help.

[PerishCode]

A substantial part of this has now landed and is available in v0.6.0-beta.8.

What shipped:

• progressive hierarchical help for @tool paths
• flat dot-path registry internally, with layered lookup externally
• richer namespace / subgroup help instead of only fallback usage: strings
• examples on concrete entries

Examples that now work as proper progressive help:

• runseal @tool json --help
• runseal @tool json pretty --help
• runseal @tool json pretty value --help
• runseal @tool ssh config --help
• runseal @tool cloudflare zone dns-record --help

This also got exercised again while landing the new JSON pretty modes, so the help tree and the command tree were updated together rather than drifting.

What is still not done from this issue:

• no machine-readable @tool --json / listing mode yet
• no explicit end-user vs wrapper-author classification layer yet
• no standalone docs page yet beyond help text / README absorption

So I would treat this issue as partially addressed in beta, with the remaining gap now mostly around machine-readable discovery and classification rather than basic progressive help.

[PerishCode]

Retested locally on v0.6.0-beta.8.

The original issue is resolved enough to close:

• progressive help now works across namespace, group, and concrete command layers
• the previously inconsistent cases I called out (json get --help, gitee pr merge --help, archive local import --help) now render proper help successfully
• the overall help surface now feels low-cost to navigate in normal use

I still agree there are worthwhile follow-ups, but they now feel like separate enhancement topics rather than blockers for this issue:

• machine-readable @tool --json / listing mode
• explicit end-user vs wrapper-author classification
• standalone docs beyond help text

So I am closing this one as addressed.