---
name: tcl-whatis
description: Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs.
---

# tcl-whatis

Runtime introspection for Tcl commands in the punkshell repo. Asks the live
interpreter instead of grepping source, so it resolves aliases, ensembles and
subcommand chains, autoloads the providing module, and reports which of the
repo's several module copies (src/modules vs bootsupport vs kit-internal
zipfs) is actually loaded.

## Command

Run from the repo root (`punk91` lives in `bin/`; any punkshell kit works):

    punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? <command> ?subcommand?...

- `<command>` - Tcl command name, qualified or not (e.g. `punk::args::parse`,
  `corp`). If not already loaded, the longest namespace-prefix package match
  is `package require`d automatically.
- `?subcommand?...` - ensemble/subcommand words: `whatis string is` resolves
  the chain to `::tcl::string::is` (via punk::ns::cmdinfo) and reports that
  origin's synopsis - no prior knowledge of the implementing namespace needed.
  Unresolvable trailing words are reported in a `warning:` line.
- `-body` - append the runtime proc body. Line numbers are file-relative when
  the `def:` line was located, so they match the origin file exactly.
- `-doc` - append the full argument documentation as plain ANSI-free text
  with the argument section of EVERY command form (punk::ns::cmdhelp
  -return text). Large for big commands; prefer the default synopsis unless
  you need per-argument help text, defaults and choices.

Exit codes: 0 ok, 1 command not found, 2 usage error.

## Output fields

    command:  string is                    the queried words
    alias:    -> punk::ns::cmdhelp         alias chain, if any
    resolves: ::tcl::string::is            chain/alias resolution target
    kind:     proc | ensemble | native command
    package:  punk::args 999999.0a1.0      providing package + loaded version
    origin:   C:/repo/.../src/modules/punk/args-999999.0a1.0.tm
    def:      <origin-file>:6528           proc definition line in origin file
    synopsis: one usage line per command form (from the punk::args definition)

Ensembles report their namespace and subcommand map instead of `def:`.

## -doc output structure (parsing contract)

- Column-0 lines containing `TYPE:` are argument rows, one line each:
  `name  TYPE:type(constraints) ?DEFAULT:'val'? ?MULTI:yes?`. Optional
  arguments show as `?name?`, repeatable ones as `name...`.
- Indented lines under a row are that argument's help text (never flags,
  even when a line starts with `-word`).
- Choices are markdown-style bullets: `` - `choice` - label text``, with
  label continuation lines indented past the bullet dash. The backticked
  token is the choice (it may carry a trailing marker glyph); everything
  after the closing backtick is label/documentation.
- Multiform commands render one ` --ARGUMENTS (form 'name')-- ` section per
  form under a single common header (description + all-forms synopsis).

## Caveats

- Keep the `src` launch argument: it loads the working-tree modules under
  `src/modules` (versions like 999999.0a1.0) so `origin`/`def` point at
  editable files. Without it the kit-stamped copies inside the executable are
  introspected (`//zipfs:/...` paths, older versions) and the report says so
  in a `warning:` line.
- Load noise ("src mode: registered ...") goes to stderr; read stdout only
  (append `2>/dev/null` in bash, `2>$null` in PowerShell).
- To edit a proc, go to the `def:` file:line and Read the file there; do not
  build edits from `-body` output text.
- `def: (no proc definition found ...)` means the proc was generated at
  runtime - `-body` output is then the only source.
- Trust `origin:` over assumptions about which module copy is loaded; this
  repo has several coexisting copies of many modules and ties do not always
  resolve the way you expect.