Skip to content

feat(agent): add qn agent context + agent discovery breadcrumbs (DX-5704)#35

Merged
johnpmitsch merged 1 commit into
mainfrom
dx-agent-context
Jun 15, 2026
Merged

feat(agent): add qn agent context + agent discovery breadcrumbs (DX-5704)#35
johnpmitsch merged 1 commit into
mainfrom
dx-agent-context

Conversation

@johnpmitsch

Copy link
Copy Markdown
Collaborator

What

Adds qn agent context — a new agent command group whose context subcommand prints a single, self-contained, version-stamped usage guide for AI agents — plus discovery breadcrumbs pointing to it.

Closes DX-5704 — https://linear.app/quicknode/issue/DX-5704/add-qn-agent-context-command-agent-discovery-breadcrumbs

Why

A coding agent dropped into qn has no single authoritative place to learn how to operate it correctly on the first try — auth resolution, the non-TTY output contract, exit-code semantics, confirmation gating, and retry/idempotency rules are scattered across --help and the SDK. This embeds one guide the agent can print offline, and points to it from where agents look.

What's in it

  • qn agent context — prints the guide to stdout, exits 0 with no auth and no network. Joins the no-SDK dispatch group (auth/completions), so it never triggers the API-key path. Guide is embedded via include_str! from src/commands/agent/context.md; leads with control-flow-critical material (auth, output contract, exit codes, confirmation, retry/idempotency) before the command catalog and workflow recipes.
  • Output contract — reads global.format directly (not resolve_format), so no flag → markdown (not the piped-default toon). -o json{ version, guide } envelope; -o yaml/-o toon/-o table → markdown + a one-line stderr notice (suppressed by --quiet). Workflow examples use the default format so piped agents get token-efficient toon; recipes model create-paused → show → activate and chain returned IDs.
  • Breadcrumbsqn --help footer line and a stderr tip after successful qn auth login, one canonical phrase reused in both.
  • stream create --fix-block-reorgs help now documents the false (disabled) default.
  • CLAUDE.md sync rule to keep context.md aligned with the command surface.

Out of scope (by decision)

Error-exit breadcrumbs (no changes to errors.rs/main.rs); -o json structured command catalog; error.hint envelope field; future qn agent install/mcp/doctor (namespace left open only).

Testing

  • cargo build --release, cargo clippy --all-targets -- -D warnings, cargo fmt --check — all clean.
  • cargo test — 229 pass.
  • Manual: offline exit 0 with empty config; version interpolated ({{VERSION}} gone); -o json valid envelope; -o toon prints markdown + stderr notice; --quiet suppresses it; breadcrumbs present in qn --help and qn agent --help; the stream recipe's flags parse and reach the API.

No automated tests added: the in-process harness doesn't capture stdout, and the behavior is "print an embedded string."

…-5704)

Give coding agents one self-contained place to learn how to operate `qn`
correctly on the first try.

`qn agent context` prints an embedded, version-stamped usage guide to stdout
and exits 0 with no auth and no network — it joins the no-SDK dispatch group
(auth/completions) so it never triggers the API-key path. The guide lives in
src/commands/agent/context.md (included via include_str!) and leads with the
control-flow-critical material (auth, output contract, exit codes, confirmation,
retry/idempotency) before the command catalog and workflow recipes.

Output contract: the command reads global.format directly rather than
resolve_format, so no flag means markdown (not the piped-default toon). `-o json`
emits a `{version, guide}` envelope; `-o yaml`/`-o toon`/`-o table` print markdown
plus a one-line stderr notice (suppressed by --quiet).

Discovery breadcrumbs point to the command from the two places agents look:
the top-level `qn --help` footer and a stderr tip after a successful
`qn auth login`, using one canonical pointer phrase.

Also documents the false (disabled) default on `stream create --fix-block-reorgs`,
and adds a CLAUDE.md rule to keep context.md in sync with the command surface.

Verified: release build, clippy -D warnings, and fmt --check clean; 229 tests pass.
@johnpmitsch johnpmitsch merged commit 4cdd0ac into main Jun 15, 2026
13 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants