[antoinetoussaint-byte]

Choosing which tools a solution gets — and noticing that a new module version offers one more — had every part already built and no way to read them together:

• the catalog is contracts/runnables/index.json, which "in a composed workspace arrives inside a third-party module package", so a released module already ships its own tool list;
• the answer is runnable-scope-selections, keyed MODULE__OPERATION, per environment, where [] declines;
• the judgement is core's ResolveScopeSlots plus generate's own declinableOperation / unknownSelectionKey.

Nothing joined them. "What does records 0.5.1 offer, and which of it has staging granted?" meant reading generated JSON by hand, and an operation added by a new module version was invisible: unanswered looks exactly like absent.

What this adds

codefly list runnables already lists derived operations beside declared ones. It now carries the two facts a picker needs.

The owner's exposure, with --tools or --env, repeated and never completed — the model-facing name and the explicit effect. An operation with no exposure is listed without one: absent means not exposed, an unstated effect is not read-only. --tools keeps only the exposed ones, which is what a composition can grant as a tool.

The grant, with --env, judged by the rules generate runnable-bindings judges it by rather than by whether an answer exists:

grant	meaning
selected	its answer resolves every scope slot the owner declared, or it declares none
declined	answered [] — installed for no resource, granted no authority, offered as no tool
needs-scopes	its owner asks for scope slots nobody has answered
invalid	generation refuses this answer, and the row carries core's reason

needs-scopes is the piece that was missing. A module version that adds an operation adds a row nothing answers, so a new tool surfaces as work to do, and the listing names the key — DOCUMENTS__RUNTIME_WORKER_GRPC_APPLY_TEXT — that the grant is written under.

An answer naming no operation is reported beside the rows (unanswered_keys in --json) rather than dropped: a mistyped key answers no question and leaves its operation reading as unanswered, which is the one thing a listing must not hide.

The grant is the generator's own judgement, not a second opinion

The first shape of this change decided the state from len(selections) == 0, so any non-empty answer read as selected. A deep review (persisted as report r2, fixes as x2) found that wrong on three configurations, all of them ones a person actually produces:

• an operation declaring collection and source in an environment answering only collection → reported granted, run refused with "declares required scope slot "source" but no ScopeSelection was supplied for it";
• a typo in a slot: name, or a selection with an empty invoke list → same;
• [] against an operation with no slots → reported declined, while declinableOperation refuses it with "there is nothing to decline; remove the entry".

So the listing now builds the operation's core spec and calls ResolveScopeSlots itself, and reports invalid with core's own words. That was possible without duplicating anything because operationSpec took nothing from the endpoint descriptor but the method spelling, which the listing already holds: it moved to (*runnables.Operation).Spec, alongside BindingKey and GrantOf, in pkg/runnables where both callers hold one spelling. cmd/generate.RunnableBindingKey is now a thin alias, and cmd/list no longer imports cmd/generate at all.

Output contracts kept

• The default table is unchanged — the tool columns appear only with --tools or --env, so anything parsing it keeps working.
• --json without --env is still the array it always was; the object (runnables, unanswered_keys) appears only under the new flag.
• tool and grant live on the listing's own row type rather than the shared Identity, so show runnable --json is untouched (git diff origin/main -- cmd/show/ is empty) and does not state the same exposure twice.

Validation

• go build ./..., go vet ./cmd/list/ ./cmd/generate/ ./pkg/runnables/ — clean. gofmt clean. golangci-lint run ./cmd/list/... ./cmd/generate/... ./pkg/runnables/... — 0 issues.
• go test ./cmd/list/ ./cmd/generate/ ./pkg/runnables/... ./cmd/show/ -count=1 — all ok.
• docs/commands.md carries the flags, the four-state grant table and the unanswered_keys behaviour; docs/cli-reference.md regenerated through its own gate (TestCLIReferenceIsCurrent).
• Twelve tests in cmd/list/runnables_grants_test.go over a fixture whose operation declares a tool and a required slot: the exposure as declared; needs-scopes naming the open slot; selected on a resolving answer; declined on []; invalid on a partial answer, on an undeclared slot name, and on an illegal decline; an orphan key reported while its operation still reads unanswered; the default table's columns; the array-shaped --json; an undeclared environment refused; and --tools listing nothing when the owner exposed nothing. Reverting the resolve and the decline rule fails three of them — they are regression tests, not decoration.

Not in scope

This reads the answer; it does not write one. Granting is still editing runnable-scope-selections by hand. A codefly grant runnable <key> --env that writes the selection, and the console page that would consume this --json, are the next steps and belong in their own changes.

🤖 Generated with Claude Code