Make q2 agents-info more agent-friendly

Open
#1,115 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
48/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
rust

Research direction

Start by locating the q2 agents-info index generation and lookup code, especially suggestions(), then inspect the CLI command definitions for q2 docs and q2 render. The issue describes several possible improvements but does not choose which to implement; agree on scope before changing behavior. Done means the selected CLI improvement works as described and has coverage for its lookup or output behavior.

Written by the indexing model from the issue text.

Description

Some friction I hit using q2 agents-info (0.42.0) from an AI agent:

  1. The index is mostly error codes. q2 agents-info prints ~62 KB (~15k tokens), of which 347 error-reference entries are ~56 KB. Listing the error reference as a single entry (full list behind --list or a flag) would shrink it to ~7 KB.
  2. A bare error code doesn't resolve. q2 agents-info Q-2-38 fails, and the suggestions rank errors/markdown/Q-2-3.md above the exact Q-2-38.md (substring match in suggestions()).
  3. Diagnostics don't point to their page. A render error shows [Q-2-38] Unclosed Attribute Specifier; a hint like see: q2 agents-info errors/markdown/Q-2-38.md would close the loop.
  4. No search in the CLI. The MCP docs tool can search; the CLI can only list or fetch. Something like q2 docs llms --search <terms> would match it.

Smaller: 59 of the 69 non-error pages have no description in the index. Separately, q2 render emits ANSI colours and OSC 8 links when stderr is piped, even with NO_COLOR=1.

Dominant language
Rust
Stars
302
Forks
22
Avg merge
5h 2m
Merged PRs (30d)
213

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from quarto-dev/q2

All issues in quarto-dev/q2

Similar issues

More Rust issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.