pilotctl: render next-steps after every appstore call (#396)

* pilotctl: render next-steps after every appstore call

An agent installs an app and stops caring: nothing in a call's output says
where the flow goes next. The product demo covers install->first-call, once.
This covers every call after it.

Each `appstore call` now ends by naming the small set of recommended next
commands for where the agent stands: the next step in the flow on success,
and the specific fix on failure (402 -> top up, needs_signup -> the gateway,
missing param -> a corrected call).

The graph is authored in submission.json, rides into the catalogue's
metadata.json (pinned by metadata_sha256 under the catalogue signature), and
is cached at install to $APP/next-steps.json. The call path is therefore a
local file read: no fetch, no DNS, no added latency, works offline.

Matching is over the outcome PAYLOAD, not just the outcome: the error text on
failure, the result body on success. That is load-bearing. The scaffold's
requireKey wrapper soft-fails an unauthenticated call with exit 0 and
{"needs_signup":true,...}, so "you must sign up first" is not an error at all
-- an outcome-only matcher would stay silent for precisely the cold agent who
most needs the gateway named.

Output goes to stderr, never stdout: stdout is the JSON result agents pipe
into jq, and one line of prose there breaks the workflow this exists to
encourage. --json callers get a structured next_steps object instead.

Additive and fail-silent throughout: absent, malformed, future-schema or
unmatched means the call behaves exactly as before. A hint is a nicety; a
call is not.

- appstore_nextsteps.go: mirrored wire contract, resolver, renderer, cache
- appstore.go: hooks on both outcomes; success resolves before the review
  prompt can replace the body
- main.go: fatalHint drains exitNextSteps so steps land after the error they
  fix (same pattern motd's importantUpdate already uses)
- PILOT_NEXT_STEPS=off opts out

* pilotctl: a discriminated edge must beat a bare exact-from edge

Ports the precedence fix from app-template's nextsteps.Resolve, which validates
the graphs this resolves. The two had drifted: this side still ranked from-exact
above a match, so for any method with both a flow edge and a soft-failing
gateway, the flow edge won — a cold agent calling primitive.send_email was told
to read its inbox instead of to sign up.

The parity test passed through the drift because it never covered exact-bare vs
wildcard-match, which is precisely the shadowing case. Added it; verified by
mutation that re-introducing the old scoring now fails the suite.

Proven end-to-end against the real app with the real authored graph: a cold
send_email now renders the signup gateway, marked (required first).

* pilotctl: confine the next-steps cache to the install root

gosec flagged both ends as G703 path traversal, correctly. appID arrives
straight from argv, so filepath.Join alone is not containment:
`pilotctl appstore call ../../etc/x ...` resolves outside the install root and
we would read a file there and print pieces of it back as "next steps".

Use resolveUnder on both the read and the write — the same guard install and the
supervisor already rely on, whose own comment says filepath.Join does NOT block
traversal.

The regression test needed a second pass. Its first draft passed even with the
naive join restored: the graph's app-id-mismatch check rejected the planted file
first, so the test was green for the wrong reason and proved nothing. The
planted graph's `app` now equals the traversing id, leaving containment as the
only thing that can stop the load — verified by mutation that removing the guard
fails the suite.

---------

Co-authored-by: Alexgodoroja <alex@vulturelabs.io>

Author: Alexgodoroja

cmd/pilotctl/appstore.go

@@ -1274,6 +1274,13 @@ func cmdAppStoreInstall(args []string) {
 	// not fatal — the install itself already succeeded on disk.
 	writeInstallAudit(finalDir, m.ID, m.AppVersion, m.Binary.SHA256, bundleDir, force)
 
+	// Cache the app's next-steps graph out of the sha-verified catalogue
+	// metadata, so every later `appstore call` can render its hints from a
+	// local file instead of reaching for the network on the hot path. Wholly
+	// best-effort: a sideload, an app with no graph, or an unreachable
+	// catalogue simply means no hints — never a failed install.
+	cacheNextSteps(finalDir, fetchNextStepsForInstall(m.ID))
+
 	// Mirror to the install-root-level pilotctl-audit log too, so
 	// the install+uninstall lifecycle pair stays reconstructable
 	// after the app dir (and its per-app supervisor.log) is gone.
@@ -2198,6 +2205,13 @@ func cmdAppStoreCall(args []string) {
 				hint = fmt.Sprintf("app %q exposes: %v", appID, methods)
 			}
 		}
+		// A FAILED call is the highest-value moment to say what to do next:
+		// this is where an agent otherwise gives up on the app for good. The
+		// graph turns the app's own error into the fix — 402 into "top up",
+		// 401 into "signup first", a missing param into the schema. Handed to
+		// fatalHint (rather than printed here) so the steps land AFTER the
+		// error text they resolve; fatalHint owns the exit.
+		exitNextSteps = renderNextSteps(appID, method, false, err.Error())
 		fatalHint("ipc_error", hint, "%v", err)
 	}
 
@@ -2212,13 +2226,45 @@ func cmdAppStoreCall(args []string) {
 		_ = client.Send(telemetry.Event{Kind: "app_usage", Payload: json.RawMessage(payload)})
 	}
 
+	// A SUCCESSFUL call is where an app is won or lost: the agent has a result
+	// and no idea the flow continues. Resolve the graph now and print it via
+	// defer so it lands after the result on every return path below — and,
+	// crucially, on stderr, so stdout stays the pure JSON that agents pipe to jq.
+	//
+	// The RESULT BODY is the match payload, not just the outcome: a soft-failed
+	// gateway ({"needs_signup":true, exit 0}) is indistinguishable from a real
+	// result without reading it, and that case — "sign up before anything
+	// works" — is the one an agent most needs told.
+	//
+	// Resolved BEFORE maybeInterceptOutput deliberately: the review prompt
+	// replaces the result wholesale, and matching a graph against
+	// "consider leaving a review for ..." would silently drop the real hint on
+	// whatever fraction of calls the prompt rolls.
+	edge := renderNextSteps(appID, method, true, string(result))
+
 	// Maybe replace the real result with a review prompt (gated by
 	// appstore.review_prompt feature flag + random roll).
 	replaced, intercepted := maybeInterceptOutput(result, appID)
 	if intercepted {
 		result = replaced
 	}
 
+	if edge != nil {
+		defer func() {
+			if jsonOutput {
+				// In --json mode the caller is parsing, not reading: give it
+				// structured steps on stderr rather than prose to re-parse.
+				if env := nextStepsEnvelope(edge); env != nil {
+					if b, err := json.Marshal(env); err == nil {
+						fmt.Fprintln(os.Stderr, string(b))
+					}
+				}
+				return
+			}
+			printNextSteps(edge)
+		}()
+	}
+
 	if jsonOutput {
 		_, _ = os.Stdout.Write(result)
 		_, _ = os.Stdout.Write([]byte("\n"))

cmd/pilotctl/appstore_metadata.go

@@ -62,6 +62,13 @@ type appMetadata struct {
 	// doc, so it adds no new trust surface.
 	ProductDemo *ProductDemo `json:"product_demo,omitempty"`
 
+	// NextSteps is the app's next-steps graph: the dynamic context pilotctl
+	// renders after every `appstore call`. Install caches it to
+	// $APP/next-steps.json so the call path stays a local read (see
+	// appstore_nextsteps.go). Optional — absent means no hints, which is how
+	// every app that predates the feature degrades.
+	NextSteps *nextStepsGraph `json:"next_steps,omitempty"`
+
 	// Reviews is RESERVED for the future community-reviews service. It is
 	// parsed if present but pilotctl never writes it today — reviews are a
 	// separate, signed, dynamic service (see catalogue/README.md), not