# G-050 punk::ns::synopsis argument-validity marking and status-aware returns

Status: proposed
Scope: src/modules/punk/ns-999999.0a1.0.tm (synopsis), src/modules/punk/args-999999.0a1.0.tm (synopsis renderer), src/tests/modules/punk/ns/testsuites/ns/cmdhelp.test (synopsis pins)
Acceptance: see GOALS.md index entry (canonical).

## Context

'i <cmd> <args...>' (cmdhelp) marks supplied argument words for validity; 's <cmd>
<args...>' (synopsis) does not - its output is identical whether the trailing words are
valid, invalid or absent (pinned 2026-07-10: synopsis_GAP_no_argument_validity_marking).
The user-facing intent is parity: the synopsis line(s) should show which supplied words
validated (goodarg style) and where the first problem is (badarg style), with the same
info/error scheme signalling as the usage table.

Separately, synopsis's handling of curried aliases is length-arithmetic based: the
`excess` computation (ns-999999.0a1.0.tm, "This isn't quite right.. e.g see: s pse"
REVIEW comment) counts args_remaining vs supplied words and lreplaces that many leading
synopsis words with resolved_args. For a curried alias the substituted command renders
as the braced alias target (e.g `{::ns::realcmd curriedarg} ...`) rather than the alias
name (pinned: synopsis_curried_alias_shows_braced_target).

## Approach

Consume the G-049 parse-status structure: parse the trailing words against the resolved
definition (same docid resolution as cmdhelp via cmdinfo), then render the synopsis with
per-word marking derived from the status, and expose the status in the dict return.
Replacing the excess-args arithmetic with an actual parse against the resolved definition
is the same change - the parse knows how many words the definition consumed and how the
curried words map onto leaders.

Also worth addressing while in there: the existing in-source note that treating the
synopsis line as a Tcl list for lreplace is risky with ANSI content ("todo - consider
always using 'punk::args::synopsis -return dict' and operating on that list to rebuild
string").

## Notes

- Depends on G-049 (status structure). G-044's hint display is a future consumer of the
  same API - keep the marking function reusable outside synopsis/cmdhelp rendering.
- Existing string-shape tests: args testsuite synopsis.test and the installed
  test::punk::args synopsis tests ("must be no leading space" convention) - marking must
  be ANSI-only so ansistripped output stays stable, or those tests get a documented
  update.