cli+docs: --api surface index; route CLAUDE.md to llms.txt; name the lib HOFs in BUILTINS.md (#734)

[InauguralPhysicist]

Closes #734.

All three items, cheapest first, with item 3 as the code anchor.

1. CLAUDE.md routes to llms.txt

The "Writing .eigs code?" line in Task-specific procedures now names docs/llms.txt alongside the write-eigenscript skill — the repo's best AI-facing reference was previously reachable only from README.md line 424. On the overlap question the issue raises: kept as two documents with distinct jobs — the skill is the session-loaded trap list, llms.txt the shippable standalone reference — but they now cross-reference, and --api (below) removes the largest shared burden (name resolution) from both.

2. BUILTINS.md names the lib HOFs

The builtins-vs-library note now says explicitly that map, filter, reduce are NOT builtins, with both access forms (import list → list.filter of [xs, fn], or load_file of "lib/list.eigs" for bare names), and names the sort_by-IS-a-builtin contrast that made the omission actively misleading. The exact greps the issue ran (filter/map/reduce → zero hits) now land on the answer.

3. eigenscript --api [--json] — the machine-readable surface index

The missing third leg beside --lint --json and --test --json. One call answers "does X exist, and is it builtin, extension, or lib":

• builtins (249): enumerated from a scratch register_builtins env — never a hand list (the Name-keyed dispatch superinstruction hijacks a user-rebound 'dispatch' (silent wrong result); also fires on the parenthesized #355 form #459 lesson: the old hand-copied array drifted ~120 names behind the binary).
• extensions (86, by group gfx/http/http_request/db/model/net): from ext_names.h — the surface of the LANGUAGE, independent of this binary's build flags, so an agent learns the name exists and that it may need make http/make gfx.
• lib (815): every public top-level define of lib/*.eigs with its parameter list as written (defaults included; the no-paren form reports its implicit n), scraped from the same candidate directories the import resolver searches — shared helper lib_candidate_dirs, refactored out of the W021 table builder so the two can't drift apart.

Text mode is line-greppable:

builtin sort_by
extension net net_dial
lib list.filter(items, fn)

--json is the machine form; conventions stay in BUILTINS.md/STDLIB.md — this is for name resolution, per the issue's "resolve a name in one call instead of a text search".

The scratch env is freed explicitly (LSan can't trace tagged slots — same rule as builtin_name_env_free).

Tests

Suite [131]: pins the three kinds, the params capture, the filter/sort_by split that misled both of the issue's test agents, and (python3-gated) that --json parses and carries the same facts. --help documents the flag; llms.txt's helper section points at it.

Validation

• Release suite 3362/3362; ASan+UBSan detect_leaks=1 suite 3366/3366, leak tally 0 (the scratch-env free holds).
• tools/doc_drift_check.sh clean.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds a new CLI introspection surface (eigenscript --api [--json]) to mechanically resolve whether a name exists and whether it’s a builtin, extension (by group), or stdlib (lib/*.eigs) function, and updates docs to route AI/workflows toward the right references.

Changes:

• Introduce --api [--json] CLI flag and implement surface-index emission (builtins, extensions-by-group, and stdlib function signatures).
• Refactor/import-resolver-aligned lib directory discovery into a shared helper used by both W021 and --api.
• Update docs + changelog + test suite to document and pin the new index behavior.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/run_all_tests.sh	Adds suite [131] to pin --api text/JSON output and key classification facts.
src/main.c	Wires --api [--json] into the CLI help and dispatch.
src/lint.c	Refactors lib dir discovery and implements the eigs_api_dump surface index.
src/eigenscript.h	Declares eigs_api_dump in the public header.
docs/llms.txt	Points name-resolution workflows at eigenscript --api --json.
docs/BUILTINS.md	Clarifies map/filter/reduce are stdlib (lib/list.eigs), not builtins; points to --api.
CLAUDE.md	Routes .eigs writing guidance to docs/llms.txt and --api.
CHANGELOG.md	Documents the new --api feature and related discoverability fixes.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (1)

src/lint.c:1160

• In the JSON builtins array, the comma separator is keyed off the loop index i rather than whether an element was actually emitted. Since Env->names can contain NULL “slot-only” entries, the first emitted builtin can occur at i > 0, producing a leading comma and invalid JSON.

        fprintf(out, "{\"version\": \"%s\",\n \"builtins\": [",
                EIGENSCRIPT_VERSION);
        for (int i = 0; i < core->count; i++) {
            char esc[600];
            if (!core->names[i]) continue;
            json_escape(core->names[i], esc, sizeof(esc));
            fprintf(out, "%s\"%s\"", i ? ", " : "", esc);
        }

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated no new comments.

Suppressed comments (2)

tests/run_all_tests.sh:3461

• The new [131] --api test pins the list.filter(items, fn) case, but it doesn’t cover the implicit-parameter behavior that --api is supposed to report (parser.c defaults an empty param list, including define f(), to a single implicit n). Adding one assertion for a known stdlib function defined as define lock_new() would catch regressions (and will fail with the current --api implementation, which reports it as zero params).

if [ "$API_RC" = "0" ] \
   && echo "$API_OUT" | grep -q "^builtin sort_by$" \
   && echo "$API_OUT" | grep -q "^extension net net_dial$" \
   && echo "$API_OUT" | grep -q "^lib list.filter(items, fn)$" \
   && ! echo "$API_OUT" | grep -q "^builtin filter$"; then

src/lint.c:1080

• --api extracts lib function params by looking for '(' immediately after the name and then copying the raw substring until ')'. This diverges from the actual parser behavior in two concrete cases: (1) whitespace between the function name and '(' is allowed by the lexer/parser but will currently be treated as the implicit-n form, and (2) empty parens define f() currently record an empty params string even though parser.c defaults param_count==0 to the implicit single parameter n. This makes --api misreport a number of existing stdlib functions (e.g. lib/sync.eigs has define lock_new()), and also makes --api --json emit "params": [] for them.

        char params[1024];
        if (*p == '(') {
            p++;
            size_t q = 0;
            while (*p && *p != ')' && q + 1 < sizeof(params)) params[q++] = *p++;