Skip to content

docs: surface orphan pages and add compaction, commands, and user-settings docs#3683

Merged
gtardif merged 8 commits into
mainfrom
docs/p0-coverage
Jul 16, 2026
Merged

docs: surface orphan pages and add compaction, commands, and user-settings docs#3683
gtardif merged 8 commits into
mainfrom
docs/p0-coverage

Conversation

@aheritier

@aheritier aheritier commented Jul 16, 2026

Copy link
Copy Markdown
Contributor

What

Closes several end-user documentation coverage gaps in the docs site:

  • Navigation: surfaces five existing-but-unlinked pages in docs/data/nav.yml — Kanban Board, Background Jobs, Scheduler, ChatGPT, NVIDIA.
  • New guide: docs/guides/compaction/index.md — task-oriented Context & Compaction guide (automatic compaction, /compact / /context, tool-result trimming, context gauge, cost across compaction).
  • New reference: docs/configuration/commands/index.md — custom slash commands (prompt, URL, and agent-switching commands; reusable command groups; --disable-commands).
  • New reference: docs/configuration/user-settings/index.md — full user-settings reference and precedence rules.
  • Cross-links added from the agents, models, and TUI pages.

Notes

Docs-only. All flags/fields/commands verified against source (agent-schema.json, pkg/userconfig, pkg/compaction, cmd/root/*.go); locally reviewed for factual accuracy. Passes canonical check + markdownlint.

Note

This PR (#3683) and #3684 both touch docs/configuration/agents/index.md. Whichever merges second will need a trivial rebase.

@aheritier
aheritier requested a review from a team as a code owner July 16, 2026 13:26
@aheritier aheritier added area/docs Documentation changes kind/docs Documentation-only changes labels Jul 16, 2026
…ng, and per-frontend behavior

Corrects three factual errors from local review:
- $1/$2 and !`command` never existed; the resolver (pkg/runtime/commands.go)
  supports ${args[0]}, ${args.join(" ")}, ${tool_name({...})}, and the legacy
  !tool_name(...) bang syntax.
- agent: can target any agent in the team (team.Team.Agent), not just one
  listed in the current agent's sub_agents (agent_router.go, team.go,
  agent-schema.json already documented this correctly).
- url precedence over agent only holds in the full TUI (handlers.go); the
  lean TUI (leantui/update.go) only dispatches resolved text and never
  opens a browser or switches agents, and the CLI (cli/runner.go) switches
  agents but never checks url.
warn_on_cache_miss exists on main (pkg/userconfig/userconfig.go, defaults
false) and is exposed in the Notifications settings tab
(pkg/tui/dialog/settings.go) but was missing from the reference table and
complete example.

The blanket 'CLI flags override user settings' claim doesn't hold for
--yolo/--hide-tool-results: applyUserSettings (cmd/root/run.go) reapplies a
saved true setting on top of an explicit --yolo=false /
--hide-tool-results=false because those flags don't track whether they were
explicitly passed. --lean and --theme do track this and override correctly.
URL-only commands on the CLI and lean TUI still dispatch the resolved
(usually empty) text as a user message and can trigger a model turn —
they just don't open the browser. Align with the correct wording
already used at lines 29 and 218.
@gtardif
gtardif merged commit bf3d92f into main Jul 16, 2026
24 of 25 checks passed
@gtardif
gtardif deleted the docs/p0-coverage branch July 16, 2026 14:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation changes kind/docs Documentation-only changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants