feat(agent): add qn agent context + agent discovery breadcrumbs (DX-5704)#35
Merged
Conversation
…-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.
machito
approved these changes
Jun 15, 2026
machito
approved these changes
Jun 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds
qn agent context— a newagentcommand group whosecontextsubcommand 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
qnhas 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--helpand 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 viainclude_str!fromsrc/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.global.formatdirectly (notresolve_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.qn --helpfooter line and a stderr tip after successfulqn auth login, one canonical phrase reused in both.stream create --fix-block-reorgshelp now documents the false (disabled) default.context.mdaligned with the command surface.Out of scope (by decision)
Error-exit breadcrumbs (no changes to
errors.rs/main.rs);-o jsonstructured command catalog;error.hintenvelope field; futureqn 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.{{VERSION}}gone);-o jsonvalid envelope;-o toonprints markdown + stderr notice;--quietsuppresses it; breadcrumbs present inqn --helpandqn 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."