QUA-1806: Refresh Agent Q deep-dive pages and copy review

[RafaelOsiro]

Overview

Refreshes the Agent Q deep-dive pages to document v2026.5.7 changes (templates/tags tools, Office attachment support, clearer agent-chat error messages) and applies a fresh-eyes copy review on conversations.md, in-action.md, and limits.md. The review removes em-dashes, drops backend-implementation phrasing, fixes a factual UI/tool label reference, and reformats long paragraphs and table cells for readability. Numbers and links are preserved.

Key Changes

• agent-q/deep-dive/conversations.md: tightened intro; reworded Smart Suggestions to remove internal-heuristic phrasing and call out the new Workflow step label; rephrased the three-phase Understanding Responses section (added "Thinking..." indicator detail, replaced the non-existent "List Anomalies" label with "List Quality Checks"); reformatted the partial-list note as bullets and added quality check templates alongside tags; clarified that the context badge only appears in the floating chat widget; rewrote "How Compression Works" in plain language (numbers preserved: 4 turns, 10 messages, 3,000 chars, 300 chars); removed em-dashes from prose and example dialogs.
• agent-q/deep-dive/in-action.md: added a Manage check templates bullet and expanded the Manage tags bullet (apply / catalog / role gating); added 4 quality check template tools and 5 tag CRUD tools to the Available Tools tables; aligned the manage_tags table description with the bullet; replaced the intro em-dash with a colon; removed the deprecated frameborder="0" attribute from the two Loom iframes.
• agent-q/deep-dive/limits.md: added Error Reference rows for Unsupported file format, HTTP 400 Bad Request, and HTTP 422 Unprocessable Content; rewrote token consumption descriptions, truncation strategy, and compression bullets in plainer language with refreshed truncation values (250/300 characters); simplified the Session ownership note; split the Input Limits paragraph into three (guardrail bypass, paste behavior, file attachments); replaced em-dashes in this section with periods.

Pages to Test

• http://localhost:8000/agent-q/deep-dive/conversations/
• http://localhost:8000/agent-q/deep-dive/in-action/
• http://localhost:8000/agent-q/deep-dive/limits/

[greptile-apps]

Greptile Summary

This PR refreshes three Agent Q deep-dive documentation pages for v2026.5.7, adding new tools (quality check templates, tag CRUD) to in-action.md, new Error Reference rows to limits.md, and applying a copy review across all three files that removes em-dashes, drops internal-implementation phrasing, and reformats long paragraphs for readability.

• in-action.md: Documents 4 new quality check template tools and 5 tag CRUD tools in the Available Tools tables; expands the Operations bullet with template/tag management detail; removes the deprecated frameborder=\"0\" attribute from both Loom iframes.
• limits.md: Updates mechanical compression truncation values (100→250 chars user, 150→300 chars assistant), adds Unsupported file format, HTTP 400, and HTTP 422 error rows, and splits the Input Limits paragraph for clarity.
• conversations.md: Fixes the step label from "List Anomalies" to "List Quality Checks", adds the "Thinking..." indicator detail, notes the Workflow step label, and rewrites the compression section in plain language while preserving all published numbers.

Confidence Score: 4/5

Safe to merge — changes are documentation-only with no code impact.

The copy review is clean and the new tool entries in in-action.md and limits.md are internally consistent. Two small items in conversations.md are worth a second look: the "around 3,000 characters" description for the mechanical compression stage uses a number that limits.md attributes to the LLM-generated summary, not the per-message truncation; and the narrowed context-badge scope to the floating widget leaves the full-page interface behavior undocumented.

docs/agent-q/deep-dive/conversations.md — the compression description and context-badge scope sentence.

Important Files Changed

Filename	Overview
docs/agent-q/deep-dive/conversations.md	Copy refresh: tightened intro, updated "List Anomalies" → "List Quality Checks", added Workflow step label detail, clarified context badge scope to floating widget, rewrote compression section in plain language. Two minor inconsistencies: mechanical-summary "3,000 chars" figure doesn't align with limits.md per-message truncation values, and the badge-scope narrowing leaves full-page context behavior undocumented.
docs/agent-q/deep-dive/in-action.md	Added 4 quality check template tools and 5 tag CRUD tools to the Available Tools tables, expanded the Operations bullet list with template/tag detail, removed deprecated frameborder="0" from two Loom iframes, and replaced em-dash with colon in the intro. Changes are internally consistent and no issues found.
docs/agent-q/deep-dive/limits.md	Updated mechanical compression truncation values (100→250 chars user, 150→300 chars assistant), added three new Error Reference rows, split the Input Limits paragraph, removed the per-pod rate-limit note, and simplified truncation strategy prose. All numbers are internally consistent; changes appear intentional and accurate.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User Message] --> B{Thinking Phase}
    B --> C[Tool Execution Phase]
    C --> D{Result Size}
    D -->|≤ 8,000 chars| E[Full Result to LLM]
    D -->|> 8,000 chars| F[Truncate: trim lists to small sample\nappend truncation note]
    F --> E
    E --> G[LLM Response]

    subgraph Memory["Conversation Memory Management"]
        H{Session Length} -->|Recent 4 turns| I[Kept verbatim]
        H -->|Older turns| J[Mechanical Compression\nUser: 250 chars · Assistant: 300 chars\nTool results dropped]
        H -->|≥ 10 messages| K[LLM Summary\nup to 3,000 chars\npersists across sessions]
        L[History tool results\nbeyond last 2 messages] --> M[Truncated to 300 chars]
        N[Saved chat history\nper tool output] --> O[Capped at 500 chars]
    end

    G --> Memory

Loading

_{Reviews (1): Last reviewed commit: "docs(agent-q): refresh deep-dive pages f..." | Re-trigger Greptile}

[greptile-apps]

Mechanical summary size may conflict with limits reference

Step 2 says mechanical compression condenses older turns "into a compact summary (around 3,000 characters)," but limits.md attributes 3,000 characters specifically to the LLM-generated summary (step 3). The limits table for mechanical compression only lists per-message truncation values (250 chars user / 300 chars assistant), not a defined 3,000-char total. A reader cross-referencing both pages may incorrectly conclude that either stage produces a 3,000-char result, or that the limits table is incomplete. Consider replacing "around 3,000 characters" in step 2 with language that matches the per-message truncation values documented in limits.md.

[greptile-apps]

Context badge scope may leave full-page interface unexplained

The sentence now reads "When you open the floating chat widget from a page, the injected context appears as a badge…" — restricting the badge to the floating widget only. This is a factual narrowing from the previous text ("The injected context appears as a badge above the input box"). If context injection also works in the full-page Agent Q interface (just without the badge), users may be left wondering whether they can rely on context there at all. A brief note clarifying the full-page behavior ("context is still injected in the full-page interface, but the badge is only shown in the floating widget") would eliminate the ambiguity.