Help & troubleshooting.

Ask squeezy first

In a session, /help lists every topic, grouped: getting started, agent workflow and tools, configuration, models and providers, permissions and sandbox, files and sessions, and the rest. /help <topic> opens one of them. /help /<command> -- /help /report, say -- gives one slash command's purpose, usage, arguments, and worked examples.

A topic or command squeezy recognizes is answered from documentation compiled into the binary. Nothing is fetched and no model is called, so the answer costs nothing and works offline. Three topics -- config, providers, and modes -- also quote the matching parts of your own settings, with credentials and other secret-shaped values masked.

Away from a session, squeezy help prints the same topics at a shell prompt and squeezy help <topic> the same page. Topics you can only act on inside a session are listed separately at the end, so everything above that line is something you can run right now. A name with no page exits non-zero, so a typo in a script does not read as success.

/help                 # every topic, grouped
/help permissions     # one topic
/help /report         # one slash command
squeezy help          # the same pages, at a shell

Questions the index does not answer

Ask /help a question in your own words and it goes to doc-help: a short-lived helper that searches squeezy's own documentation and source code, both compiled into the binary, and then answers. This path uses the Help route -- shared Utility by default -- so before it starts squeezy writes a line into the transcript naming that provider and model, noting that the turn may cost money, and saying what web access will do in this session.

Every answer lists the docs, source files, and links it drew on, then ends with where it came from: a local curated answer, a doc-help model answer, or a doc-help web answer. Those citations are checked: a file against what is actually in the binary, a link against the pages that answer's own run retrieved -- a page it fetched, or a result its own search returned. An address that only appeared inside what a result quoted does not count. An answer that cites nothing, cites a file that does not resolve, or links a page that run never retrieved, is discarded and you get the local answer instead.

Rate the last answer with Ctrl+G for helpful, or Ctrl+R then Shift+D for not helpful. A rating sends one anonymous signal -- the topic name, whether a local or a model answer replied, the verdict, and the version you are running -- and never your question or the answer text. It rides the same channel as the rest of squeezy's telemetry, so turning that off turns ratings off too.

Some questions turn on facts no bundled doc can hold: whether a model has shipped yet, what a provider supports today. doc-help can ground those on a live lookup and cites the URL it used. That path is on by default and gated twice more before it can run: your permission policy must not deny web access, and websearch or webfetch must survive your tool filters. The default policy sets web access to ask, so every lookup stops and asks you first.

help_mode controls how far doc-help can go. The default, model_with_web, permits the permission-gated live lookup described above. model keeps the model on the bundled docs and source, while bundled answers from the local corpus alone and makes no provider call.

[subagents]
help_mode = "model_with_web"  # default; use "model" for no web or "bundled" for no model
# help_route = "help-model"     # a complete Model profile
# help_base_model = "parent"    # advanced alternative on the parent provider

In either model-backed mode, an unset model choice uses the one shared Utility route used by Build, Plan, and Orchestrate. Utility keeps its provider account and model together. It tries an explicit Utility assignment, the Build Provider profile's Utility default, and a known economical model before falling back to the complete Build route.

Set help_route to choose a complete Model profile or an exact Provider-profile model. For the advanced provider-local form, set help_base_model to an exact Base model ID on the parent Provider profile; utility selects shared Utility and parent selects the current coding model. These two overrides are alternatives, so set only one.

When startup looks wrong

In a session, run /doctor. It checks in the background and prints the report into the transcript, against the configuration this session actually resolved. At a shell, squeezy doctor does the same work. Either way you get the verdict on the first line and then one row per check -- ok, a warning, or an error -- with failures sorted to the top. The shell form exits 1 when any check fails and 0 when every check passes or only warns, so a script can gate on it.

The rows cover which settings layers this run merged and in what order, where your settings file lives, which environment variables are overriding a setting, the credential for your configured provider, session and cache storage paths, the code knowledge database, MCP servers, skills, hooks, your session cost cap, and whether the shell sandbox can run on this machine. That is usually enough to spot a missing key, the wrong provider, or a settings file that is not being read. A run that is not clean points you at squeezy help troubleshooting, the offline guide.

--probe adds the live checks, and only the shell form has it. It asks your provider to list its models -- one authenticated request, enough to prove the credential and the base URL reach the service -- and starts every enabled MCP server to confirm it comes up and advertises tools, then shuts them down again. A provider with no model-list endpoint has its stored credential checked instead. The flag is opt-in because it touches the network and launches those servers as child processes. --only <check> narrows the run to one check or one family, and --json emits the whole report for tooling.

/doctor
squeezy doctor
squeezy doctor --only provider --only session_store
squeezy doctor --probe
squeezy doctor --json

Reporting an issue

Three paths, each showing you the contents before anything leaves your machine. /feedback <what happened> sends a short note and nothing more: the sentence you typed, with secret-shaped values masked. /report packages a whole session into a redacted archive -- the one you are in, or an earlier one by id. At a shell, squeezy report <session_id> does the same.

/report asks what happened, collects the available evidence, and lets you review content groups before creating one local ZIP. It never uploads an archive. /feedback remains for suggestions, praise, and comments; its Report a problem action transfers your draft into the diagnostic flow.

/report
squeezy report --latest
squeezy report --startup
squeezy report <session_id> --dry-run
squeezy report <session_id> --exclude conversation --output problem.zip

Share the archive privately with the developer support team using the appropriate channel. It masks secrets but still includes conversation and tool content. The manifest explains missing evidence. Managed reports and logs expire after 30 days by default; an explicit output file is yours to keep.