From a3e424895724e02ad7d18afdbe4e750eb16733b3 Mon Sep 17 00:00:00 2001 From: Owen Qwen Date: Wed, 24 Jun 2026 03:15:46 -0500 Subject: [PATCH] Refresh documentation for v0.2.3 --- README.md | 151 +++---- ROADMAP.md | 30 +- docs/README.md | 15 +- docs/access-modes.md | 83 ++++ docs/commands.md | 93 +++++ docs/configuration.md | 138 ++++--- docs/glossary.md | 29 ++ docs/platforms.md | 60 +++ docs/providers.md | 102 +++++ docs/troubleshooting.md | 160 ++++++++ docs/workflows.md | 131 ++++++ ...0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md | 375 ++++++++++++++++++ tests/docs_tests.rs | 69 ++++ 13 files changed, 1279 insertions(+), 157 deletions(-) create mode 100644 docs/access-modes.md create mode 100644 docs/commands.md create mode 100644 docs/glossary.md create mode 100644 docs/platforms.md create mode 100644 docs/providers.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/workflows.md create mode 100644 plans/V0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md diff --git a/README.md b/README.md index e6977eb..2b98dd4 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,18 @@ # Cassady / Cass -Cassady (`cass`) is a minimal Rust terminal coding agent with a looped chat UI, filesystem tools, access modes, JSONL conversation persistence, and OpenAI-compatible LLM support. The default endpoint is Fireworks. +Cassady (`cass`) is a terminal coding agent written in Rust. It runs an interactive chat in your project, can inspect files, apply exact edits, run shell commands when the active safety mode allows them, and persist sessions for later resume. Cassady currently talks to OpenAI-compatible providers. -## Install +The project installs two equivalent commands, `cass` and `cassady`; examples use `cass`. + +## Current scope and limitations + +- Provider support is OpenAI-compatible chat/completions APIs only. +- The primary interface is an interactive terminal UI. +- Config and conversation state live under `~/.cass`. +- Windows binaries are built for releases, but deeper Windows terminal, path, shell, and filesystem polish is planned for a later release. +- Cassady is not an installer, updater, or package manager. + +## Install from source ```sh cargo install --path . @@ -11,109 +21,104 @@ cargo install --path . This installs both commands: ```sh -cass -cassady +cass --version +cassady --version ``` -## Configure +## First use -On first run, Cass starts an interactive setup wizard if it cannot find a usable provider/model/API key: +Start Cassady in a project directory: ```sh cass ``` -You can also run the wizard explicitly: +If Cassady cannot resolve a usable provider, model, or API key, it offers to run setup before opening a chat. You can also run setup explicitly: ```sh cass setup -``` - -The wizard uses clean keyboard prompts: `↑`/`↓` moves, `Space` selects providers, and `Enter` submits. It supports configuring multiple OpenAI-compatible providers at once: OpenAI, xAI, Fireworks, Groq, OpenRouter, OpenCode Zen, OpenCode Go, Cerebras, Novita, Together, and custom OpenAI-compatible endpoints. It asks for API key environment variables, tries to fetch models from `GET /models`, lets you retry model discovery or enter a model id manually if discovery fails, saves config, validates setup, and starts a new session when ready. - -By default, Cass still ships with Fireworks defaults: - -- base URL: `https://api.fireworks.ai/inference/v1` -- model: `accounts/fireworks/models/qwen3p7-plus` -- API key: `"$FIREWORKS_API_KEY"` - -Set your selected provider key, for example: - -```sh -export FIREWORKS_API_KEY=... -``` - -User preferences live at `~/.cass/config.json`: - -```json -{ - "default_model": "accounts/fireworks/models/qwen3p7-plus", - "default_access_mode": "read-only", - "show_reasoning": false -} -``` - -Provider connection details belong in `~/.cass/providers.json`. Model metadata belongs in `~/.cass/models.json`. API keys may be literal strings or environment-variable references like `"$FIREWORKS_API_KEY"`. - -Validate config with: - -```sh cass check +cass ``` -Extra global instructions can be placed in `~/.cass/global.md`. +The setup wizard lets you choose one or more OpenAI-compatible providers, enter the API key environment-variable name, discover models from `GET /models` when the key is available, or enter a model id manually. -Bundled documentation from this build is embedded into the binary and installed to `~/.cass/docs` on startup. See `~/.cass/docs/configuration.md` for full configuration docs. - -## Usage +Set your provider key in the shell where you run Cassady. For example, on macOS/Linux: ```sh -cass [--model MODEL] [--base-url URL] [--api-key-env ENV] [--cwd PATH] +export OPENAI_API_KEY=... +``` + +In PowerShell: + +```powershell +$env:OPENAI_API_KEY = "..." +``` + +Run `cass check` any time to validate JSON config, provider/model references, active model resolution, and API key availability. + +## Everyday usage + +```sh +cass [--model MODEL] [--cwd PATH] cass --resume cass --resume cass check cass setup ``` -`cass --resume` without an ID lists chats for the current directory. +`cass --resume` without an id lists saved chats for the current directory. When Cassady exits a chat, it prints a resume command for that session. -## Keys +Common in-chat commands: -- Type `/`: show command autocomplete, including command arguments like `/model ` and `/new` -- `Up`/`Down`: move through an autocomplete menu -- `Enter`: fill autocomplete selection when a menu is open; otherwise send message / run command -- `Tab`: cycle reasoning effort (`off` → `low` → `medium` → `high`; required-reasoning models skip `off`) -- `Ctrl-J`: insert newline -- `Shift-Tab`: cycle access mode while idle (`read-only` → `workspace-edit` → `full-access`) -- `Ctrl-O`: toggle compact/full tool output display -- `Ctrl-Shift-R`: toggle reasoning display -- `Up`/`Down` or mouse wheel: scroll transcript when no autocomplete menu is open -- `PageUp`/`PageDown`: transcript scroll -- `Ctrl-C` twice within 1.5 seconds: exit +- `/model `: switch to a model from `~/.cass/models.json`. +- `/new`: create a new chat for the current directory. +- `/resume `: resume a saved chat for the current directory. +- `/status`: show chat id, model, mode, cwd, record count, and current status. -## Commands +Helpful keys: -- `cass check`: validate Cass config files -- `cass setup`: choose an OpenAI-compatible provider/model and save config -- `/model `: switch the model for future turns; model autocomplete lists entries from `~/.cass/models.json` -- `/new`: create a new chat for the current directory -- `/resume `: resume a saved chat; chat autocomplete lists chats for the current directory -- `/status`: show current chat status +- `/`: show command autocomplete. +- `Enter`: send the message or accept an autocomplete item. +- `Ctrl-J` or `Ctrl-Enter`: insert a newline. +- `Shift-Tab`: cycle access mode while idle. +- `Tab`: cycle reasoning effort while idle. +- `Ctrl-O`: toggle compact/full tool output display. +- `Ctrl-Shift-R` or `Ctrl-R`: toggle reasoning display. +- `Esc`: request turn cancellation while a turn is running. +- `Ctrl-C` twice within 1.5 seconds: exit. -On exit Cass prints: +## Safety model -```text -Resume this chat with: cass --resume -``` +Cassady exposes tools according to the active access mode: -## Tools +- `read-only`: read/list/search the workspace and bundled docs. No edits or shell commands. +- `workspace-edit`: read/list/search plus write/edit inside the launch workspace. Shell commands require explicit approval. +- `full-access`: read/write/edit broadly under your OS permissions and run shell commands without the workspace-edit approval prompt. Bundled docs remain read-only. -Tool calls are shown compactly by default; press `Ctrl-O` to expand full tool output. +Use `--readonly`, `--workspace-edit`, or `--full-access` to choose a mode at launch, or press `Shift-Tab` while idle. -Reasoning is hidden by default unless `show_reasoning` is enabled; press `Ctrl-Shift-R` to toggle it. Press `Tab` to choose the reasoning effort for future turns. Model metadata controls whether reasoning is supported or required and how the effort is sent to the provider. When providers stream reasoning fields, Cass persists that reasoning and sends it back in future model context using the provider's reasoning field, such as `reasoning_content` or `reasoning`. +## Configuration and docs -Read-only mode allows `ls`, `read`, and `grep` within the launch cwd/`--cwd` and the bundled docs directory at `~/.cass/docs`. +Cassady stores user-editable files in `~/.cass`: -Workspace-edit mode allows `ls`, `read`, `grep`, `write`, and `edit` inside the launch workspace. Bundled Cass docs remain read-only. Shell commands are available but require explicit approval before execution. +- `config.json`: active defaults and preferences. +- `providers.json`: provider base URLs and API key references. +- `models.json`: model metadata. +- `global.md`: optional global instructions added to new chats. +- `docs/`: bundled documentation installed from the current binary. -Full-access mode additionally allows broader filesystem access under the user's OS permissions. Mutating tools use atomic writes where practical: Cass writes to a temporary file first, then renames it into place after validation/write success. `write` and `edit` are always blocked under `~/.cass/docs`. The `shell` tool runs commands via `sh -c` in the launch working directory with a configurable timeout (default 30 seconds) and streams stdout/stderr into the transcript while the command is running. +API key references should usually be written as environment variables such as `"$OPENAI_API_KEY"`. + +Detailed bundled docs live in this repository under [`docs/`](docs/README.md) and are installed to `~/.cass/docs` at runtime. + +## More documentation + +- [Commands](docs/commands.md) +- [Configuration](docs/configuration.md) +- [Providers and models](docs/providers.md) +- [Access modes and tool safety](docs/access-modes.md) +- [Workflows](docs/workflows.md) +- [Troubleshooting](docs/troubleshooting.md) +- [Platform notes](docs/platforms.md) +- [Glossary](docs/glossary.md) diff --git a/ROADMAP.md b/ROADMAP.md index a2f4809..78a69f9 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -96,22 +96,22 @@ This release focuses on making Cassady feel reliable and native when the CLI is ## v0.2.3 — Documentation and README Refresh -This release focuses on making Cassady understandable, trustworthy, and easy to operate by rewriting the README and bringing all bundled documentation up to date with the current CLI behavior. The work should cover user-facing documentation only; broad CLI feature work and Windows-specific runtime improvements are deferred to v0.2.4. +This release focuses on making Cassady understandable, trustworthy, and easy to operate by rewriting the README and bringing all bundled documentation up to date with the current CLI behavior. The work should cover user-facing documentation only; broad CLI feature work and Windows-specific runtime improvements are deferred to v0.2.4. See `plans/V0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md`. ### README Rewrite -- [ ] **Rewrite the README around the current Cassady experience.** Replace stale or incomplete sections with a clear, accurate guide to what Cassady is, who it is for, and how to start using it. +- [x] **Rewrite the README around the current Cassady experience.** Replace stale or incomplete sections with a clear, accurate guide to what Cassady is, who it is for, and how to start using it. - Add a concise product summary, core capabilities, supported workflows, and current limitations. - Document both `cass` and `cassady` command names where relevant. - Keep examples aligned with the current setup wizard, active provider/model configuration, access modes, tools, and TUI behavior. - Remove outdated MVP language, obsolete commands, and instructions that no longer match the code. -- [ ] **Add a complete first-use walkthrough.** Make the README guide a new user from launching the CLI to a successful first chat without requiring them to infer missing steps. +- [x] **Add a complete first-use walkthrough.** Make the README guide a new user from launching the CLI to a successful first chat without requiring them to infer missing steps. - Cover first-run setup, `cass setup`, `cass check`, provider selection, API key environment variables, model discovery, and manual model entry fallback. - Include copy/paste-ready examples for common providers without exposing secrets or implying one provider is required. - Explain what happens when setup is incomplete and how the user should recover. -- [ ] **Document everyday workflows.** Add practical examples for the CLI actions users are most likely to perform after setup. +- [x] **Document everyday workflows.** Add practical examples for the CLI actions users are most likely to perform after setup. - Starting a chat in a project workspace. - Asking Cassady to inspect files, explain code, propose edits, and apply edits. - Reviewing tool calls, collapsed tool output, edit diffs, and assistant Markdown rendering. @@ -119,23 +119,23 @@ This release focuses on making Cassady understandable, trustworthy, and easy to ### Reference Documentation -- [ ] **Create or refresh the CLI command reference.** Document all supported commands, flags, aliases, and expected output modes in one place. +- [x] **Create or refresh the CLI command reference.** Document all supported commands, flags, aliases, and expected output modes in one place. - Include `cass`, `cassady`, `setup`, `check`, chat startup behavior, config overrides, access-mode flags, and any non-interactive/script-friendly commands. - Show when commands are interactive versus non-interactive. - Keep examples shell-neutral where possible, and label platform-specific syntax when needed. -- [ ] **Rewrite the configuration reference.** Explain where config lives, how active provider/model selection works, and how users should safely edit or validate config. +- [x] **Rewrite the configuration reference.** Explain where config lives, how active provider/model selection works, and how users should safely edit or validate config. - Document provider entries, model entries, active defaults, API key environment variable names, custom OpenAI-compatible providers, and model IDs. - Explain precedence between config files, environment variables, command-line overrides, and setup wizard changes. - Include valid example config snippets and common invalid configurations with fixes. -- [ ] **Document providers and model setup thoroughly.** Add a dedicated guide for built-in OpenAI-compatible providers and custom provider setup. +- [x] **Document providers and model setup thoroughly.** Add a dedicated guide for built-in OpenAI-compatible providers and custom provider setup. - List supported built-in providers, base URLs, expected API key env vars, and any known model-discovery limitations. - Explain the difference between provider configuration, model selection, and API key availability. - Document manual model entry, provider health checks, and how `cass check` reports provider problems. - Explicitly note protocols or providers that are not supported yet to avoid user confusion. -- [ ] **Document access modes and tool safety.** Make the security model understandable before users let Cassady inspect or edit a repository. +- [x] **Document access modes and tool safety.** Make the security model understandable before users let Cassady inspect or edit a repository. - Explain `read-only`, `workspace-edit`, and `full-access` in user-facing terms. - Document what read, write, edit, shell, and bundled-doc access mean in each mode. - Explain shell approval prompts, optional destructive-operation confirmation, workspace boundaries, symlink handling, and edit diff review. @@ -143,43 +143,43 @@ This release focuses on making Cassady understandable, trustworthy, and easy to ### Usage Guides and Troubleshooting -- [ ] **Add troubleshooting for common failure modes.** Give users actionable fixes for the errors they are most likely to hit. +- [x] **Add troubleshooting for common failure modes.** Give users actionable fixes for the errors they are most likely to hit. - Missing API keys, invalid env vars, unreachable provider URLs, model discovery failures, unsupported model IDs, and rate/authentication errors. - Broken or incomplete config, unreadable config paths, invalid TOML/JSON if applicable, and permission problems. - Terminal rendering issues, non-interactive terminals, redirected output, shell command failures, and cancellation behavior. - File edit failures, failed exact-text replacements, binary/large files, line ending issues, and workspace access denials. -- [ ] **Add task-oriented examples.** Include short, realistic examples that demonstrate how Cassady should be used on real projects. +- [x] **Add task-oriented examples.** Include short, realistic examples that demonstrate how Cassady should be used on real projects. - Code explanation and navigation. - Safe file editing with diff review. - Running tests or build commands with shell approval. - Updating config or switching providers/models. - Resuming work after a failed provider request or cancelled turn. -- [ ] **Document platform expectations without duplicating future Windows work.** Add accurate notes for macOS, Linux, and Windows users while keeping deep Windows CLI usability improvements scoped to v0.2.4. +- [x] **Document platform expectations without duplicating future Windows work.** Add accurate notes for macOS, Linux, and Windows users while keeping deep Windows CLI usability improvements scoped to v0.2.4. - Include path, shell, and environment-variable examples for each platform when documentation needs them. - Mark known Windows limitations clearly until the v0.2.4 work lands. - Avoid promising installer, package manager, or auto-update behavior that is not implemented. ### Documentation Quality and Maintenance -- [ ] **Improve prose quality and readability.** Rewrite docs in clear sentences and paragraphs instead of relying on long, list-heavy outlines. +- [x] **Improve prose quality and readability.** Rewrite docs in clear sentences and paragraphs instead of relying on long, list-heavy outlines. - Use bullets and tables only when they improve scanning, such as setup steps, command references, provider lists, or troubleshooting checklists. - Prefer short explanatory paragraphs for concepts, workflows, tradeoffs, and safety guidance. - Avoid turning every section into nested bullets; the README should feel like polished documentation, not an implementation checklist. -- [ ] **Synchronize README, bundled docs, and CLI help text.** Ensure every user-facing description of commands, modes, providers, setup, and tools says the same thing. +- [x] **Synchronize README, bundled docs, and CLI help text.** Ensure every user-facing description of commands, modes, providers, setup, and tools says the same thing. - Audit README, docs, inline help, setup prompts, `cass check` guidance, and release notes templates for contradictions. - Update terminology consistently: Cassady/Cass, provider, model, workspace, access mode, tool call, tool result, and session. - Make sure future docs can be updated from one source of truth where practical. -- [ ] **Improve documentation structure and navigation.** Make the docs easy to scan and hard to misuse. +- [x] **Improve documentation structure and navigation.** Make the docs easy to scan and hard to misuse. - Add a table of contents or clear section links where the document is long. - Move long reference material out of the README when it distracts from first-use guidance, and link to it clearly. - Add a glossary for recurring concepts such as workspace, provider, model, access mode, context, and tool call. - Ensure headings, examples, and filenames follow a consistent style. -- [ ] **Verify documentation against the actual CLI.** Treat docs as tested user experience, not prose written from memory. +- [x] **Verify documentation against the actual CLI.** Treat docs as tested user experience, not prose written from memory. - Run the documented commands and update examples to match real output. - Check every internal link, file path, command name, provider URL, env var, and config snippet. - Add lightweight docs checks where practical, such as link validation or command-output smoke tests. diff --git a/docs/README.md b/docs/README.md index 74d15b8..b84317e 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,16 @@ # Cass bundled docs -These docs are embedded into the `cass` binary at build time and installed to `~/.cass/docs` when Cass starts. +These docs are embedded into the `cass`/`cassady` binary at build time and installed to `~/.cass/docs` when Cassady starts. -Cass tools may list, search, and read this directory. Mutating tools are blocked from writing here, even in full-access mode. +Cassady tools may list, search, and read this directory. Mutating tools are blocked from writing here, even in full-access mode. -- [Configuration](configuration.md): first-run setup, `cass setup`, `config.json`, `providers.json`, `models.json`, and `cass check`. +## Contents + +- [Commands](commands.md): CLI forms, global flags, in-chat commands, and keys. +- [Configuration](configuration.md): `~/.cass` files, setup, precedence, schema examples, and validation. +- [Providers and models](providers.md): built-in OpenAI-compatible providers, custom endpoints, model discovery, and reasoning metadata. +- [Access modes and tool safety](access-modes.md): what tools can read, write, edit, and run in each mode. +- [Workflows](workflows.md): common ways to inspect code, apply edits, run checks, switch models, and resume chats. +- [Troubleshooting](troubleshooting.md): symptoms, likely causes, fixes, and verification commands. +- [Platform notes](platforms.md): macOS, Linux, and Windows environment/path notes. +- [Glossary](glossary.md): short definitions for Cassady terms. diff --git a/docs/access-modes.md b/docs/access-modes.md new file mode 100644 index 0000000..78b10ae --- /dev/null +++ b/docs/access-modes.md @@ -0,0 +1,83 @@ +# Access modes and tool safety + +Cassady exposes tools according to the active access mode. Choose a mode at startup with `--readonly`, `--workspace-edit`, or `--full-access`, or press `Shift-Tab` while idle to cycle modes. + +The launch cwd is the current directory unless `--cwd PATH` is provided. In read-only and workspace-edit modes, that cwd is the workspace root. + +## Tool matrix + +| Tool area | read-only | workspace-edit | full-access | +| --- | --- | --- | --- | +| List/read/grep workspace files | yes | yes | yes | +| Read bundled docs under `~/.cass/docs` | yes | yes | yes | +| Write/edit workspace files | no | yes | yes | +| Write/edit bundled docs | no | no | no | +| Shell commands | no | approval required | yes | +| Read outside workspace/docs | no | no | yes | +| Write outside workspace | no | no | yes, except bundled docs | + +## Tools + +- `ls`: list files. +- `read`: read file contents. +- `grep`: search file contents. +- `write`: create or overwrite files when writes are allowed. +- `edit`: apply exact old-text/new-text replacements when writes are allowed. +- `shell`: run `sh -c` in the launch cwd with an optional timeout, defaulting to 30 seconds. + +Shell output is streamed into the transcript while the command runs. The final shell result includes stdout, stderr, and exit code. Timed-out commands are killed and reported as failures. + +## Read policy + +In `read-only` and `workspace-edit`, Cassady can read only: + +- the launch workspace root; and +- the installed bundled docs directory. + +A path that resolves outside those roots is denied with a message like: + +```text +path escapes read-only roots: /path/outside (allowed roots: ...) +``` + +In `full-access`, read/list/search actions are allowed subject to normal OS permissions. + +## Write policy + +In `read-only`, write and edit tools are unavailable. + +In `workspace-edit`, write and edit tools are allowed only inside the launch workspace. Paths that resolve outside the workspace are denied with a message like: + +```text +write path escapes workspace-edit root: /path/outside (workspace root: ...) +``` + +In `full-access`, write and edit tools are allowed broadly subject to OS permissions, but writes under the bundled docs directory are still blocked: + +```text +writes are blocked under read-only docs directory: ... +``` + +`write` uses atomic writes where practical. `edit` requires every `old_text` to match exactly once in the original file and rejects overlapping replacements. + +## Shell approvals and destructive-operation setting + +- `read-only`: shell is unavailable. +- `workspace-edit`: shell requires a UI approval prompt. Press `y` to approve, `n` or `Esc` to deny. +- `full-access`: shell is allowed by policy without the workspace-edit approval prompt. + +`config.json` accepts `confirm_destructive_operations` as a stored compatibility preference, but the current runtime policy is the access-mode and shell-approval behavior described above. + +If approval is denied, the tool result says: + +```text +user denied approval for this tool call +``` + +## Practical guidance + +- Start in `read-only` when asking for explanations or audits. +- Use `workspace-edit` for normal coding work in a repository. +- Use `full-access` only when you intentionally want Cassady to operate outside the launch workspace or run shell commands without the approval prompt. +- Review tool call output and diffs before continuing after edits. +- Keep secrets in environment variables; do not ask Cassady to write literal API keys into project files. diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..193c427 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,93 @@ +# Commands + +Cassady installs two equivalent binaries: `cass` and `cassady`. This page uses `cass`, but the same options and subcommands apply to `cassady`. + +## Top-level forms + +```sh +cass [OPTIONS] +cassady [OPTIONS] +cass check [OPTIONS] +cass setup [OPTIONS] +cass --resume [CHAT_ID] +``` + +Run `cass --help`, `cass check --help`, or `cass setup --help` for the help generated by the current binary. + +## Startup behavior + +- `cass` starts a new interactive chat in the current directory. +- `cass --cwd PATH` starts from `PATH` instead. +- `cass --resume CHAT_ID` loads a saved chat. +- `cass --resume` lists chats for the current directory. +- If setup is incomplete, `cass` offers to run the interactive setup wizard before starting a chat. + +On exit, Cassady prints a command like: + +```text +Resume this chat with: cass --resume +``` + +## Global options + +- `--resume [CHAT_ID]`: resume a chat, or list chats for the current cwd when no id is provided. +- `--model MODEL`: use `MODEL` for this session. +- `--base-url URL`: override the active provider's OpenAI-compatible base URL for this session. +- `--api-key-env ENV`: read the API key from environment variable `ENV` for this session. +- `--cwd PATH`: use `PATH` as the launch cwd and workspace root. +- `--readonly`: force read-only mode. +- `--workspace-edit`: force workspace-edit mode. +- `--full-access`: force full-access mode. +- `--help`: show help. +- `--version`: show version. + +The three access-mode flags conflict with one another. + +## Subcommands + +### `cass check` + +Validates Cassady configuration under `~/.cass`: + +- JSON syntax and schema. +- duplicate provider/model ids. +- model/provider references. +- active provider and model resolution. +- active API key availability. + +Missing API keys for inactive providers are warnings. A missing active API key is an error and `cass check` exits with a non-zero status. + +### `cass setup` + +Runs the interactive setup wizard in a terminal. It configures OpenAI-compatible providers, API key environment-variable references, and first models. It updates `config.json`, `providers.json`, and `models.json` while preserving unrelated entries where possible. + +## In-chat commands + +Type `/` to open command autocomplete. + +- `/model `: switch the model for future turns. Autocomplete lists models from `~/.cass/models.json`. +- `/new`: create a new chat for the current directory. +- `/resume `: resume a saved chat from the current directory. Autocomplete lists matching chats. +- `/status`: show chat id, state, model, access mode, cwd, record count, and current status. + +Local commands can be used only when the agent is idle. + +## Keys + +- `Enter`: accept an autocomplete item when a menu is open; otherwise send the current message. +- `Ctrl-J` or `Ctrl-Enter`: insert a newline. +- `Up`/`Down`: move through autocomplete items when a menu is open; otherwise scroll the transcript. +- Mouse wheel: scroll transcript. +- `PageUp`/`PageDown`: scroll transcript by larger steps. +- `Shift-Tab`: cycle access mode while idle: `read-only` → `workspace-edit` → `full-access`. +- `Tab`: cycle reasoning effort while idle. Models that require reasoning skip `off`; models without reasoning metadata start at `off`. +- `Ctrl-O`: toggle compact/full tool output display. +- `Ctrl-Shift-R` or `Ctrl-R`: toggle reasoning display. +- `y`: approve a pending tool approval prompt. +- `n` or `Esc`: deny a pending tool approval prompt. +- `Esc`: request cancellation while a turn is running. +- `Ctrl-C`: request cancellation while busy; press twice within 1.5 seconds to exit. + +## Output notes + +Tool calls are shown compactly by default. Press `Ctrl-O` to expand full tool output. Provider-streamed reasoning is hidden by default unless `show_reasoning` is enabled in config or toggled at runtime. diff --git a/docs/configuration.md b/docs/configuration.md index 79e6b32..5726522 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -1,12 +1,31 @@ # Configuration -Cass reads user-editable config files from `~/.cass`. +Cassady reads user-editable config files from `~/.cass`. -- `config.json`: user preferences, such as the default model and access mode. +- `config.json`: user preferences, active defaults, and compatibility fields. - `providers.json`: provider connection definitions. - `models.json`: model metadata. +- `global.md`: optional global instructions included in new chats. +- `conversations/`: saved JSONL chats. +- `docs/`: bundled docs installed from the current binary. -Cass creates `providers.json` and `models.json` automatically if they are missing. The default provider is Fireworks. On first run, Cass can also launch an interactive setup wizard to choose an OpenAI-compatible provider and first model. +Cassady creates `providers.json` and `models.json` automatically if they are missing. The default provider is Fireworks. + +## Setup wizard + +Run: + +```sh +cass setup +``` + +Cassady also offers setup automatically when `cass` cannot resolve a usable active provider, model, or API key before starting a chat. + +The wizard uses keyboard prompts: `↑`/`↓` moves through choices, `Space` selects providers in the multi-select screen, and `Enter` submits. Text fields use the same prompt style instead of falling back to plain line input. + +The wizard supports configuring multiple OpenAI-compatible providers at once. If more than one provider is configured, setup asks which one should be active first. If the selected API key environment variable is set, Cassady tries to fetch models from `GET {base_url}/models` and lets you choose one. If discovery fails, it offers a retry before falling back to manual model entry. If the API key is not set, setup asks for a model id manually. + +Setup stores API keys as environment-variable references such as `"$OPENAI_API_KEY"` by default. After setup, Cassady writes/updates `config.json`, `providers.json`, and `models.json`, validates them, and starts a chat only when the active API key is available in the current shell. ## `config.json` @@ -16,26 +35,31 @@ Example: ```json { - "default_model": "accounts/fireworks/models/qwen3p7-plus", + "default_provider": "openai", + "default_model": "gpt-4.1", + "default_reasoning_effort": "medium", "default_access_mode": "read-only", "context_message_limit": 80, "model_tool_result_limit": 24000, "ui_tool_result_limit": 4000, - "show_reasoning": false + "show_reasoning": false, + "confirm_destructive_operations": false } ``` Fields: -- `default_provider`: optional provider id from `providers.json`. If omitted, Cass infers the provider from `default_model` when possible. +- `default_provider`: optional provider id from `providers.json`. If omitted, Cassady infers the provider from `default_model` when possible. - `default_model`: optional model id to use by default. +- `default_reasoning_effort`: optional `off`, `low`, `medium`, or `high`, clamped to model metadata. - `default_access_mode`: `"read-only"`, `"workspace-edit"`, or `"full-access"`. -- `context_message_limit`: optional legacy upper bound for recent non-system messages. Cass primarily budgets context from model metadata (`context_length` and `max_output_tokens`), compacts older tool outputs when needed, and trims only along valid tool-call boundaries. +- `context_message_limit`: optional legacy upper bound for recent non-system messages. Cassady primarily budgets context from model metadata and trims along valid tool-call boundaries. - `model_tool_result_limit`: optional max bytes of tool output sent back to the model. - `ui_tool_result_limit`: optional max bytes of tool output shown in the UI unless full output is toggled. -- `show_reasoning`: optional boolean, defaults to `false`. Shows provider-streamed reasoning in the transcript. Reasoning is persisted and sent back in future model context using the provider's reasoning field, such as `reasoning_content` or `reasoning`. +- `show_reasoning`: optional boolean, defaults to `false`. Shows provider-streamed reasoning in the transcript. +- `confirm_destructive_operations`: optional compatibility preference currently stored in config. -Deprecated compatibility fields from older Cass versions are still accepted: `provider`, `model`, `base_url`, and `api_key_env`. Prefer moving provider connection details to `providers.json`. +Deprecated compatibility fields from older Cassady versions are still accepted: `provider`, `model`, `base_url`, and `api_key_env`. Prefer moving provider connection details to `providers.json`. ## `providers.json` @@ -45,15 +69,13 @@ Example: { "providers": [ { - "id": "fireworks", - "name": "Fireworks", + "id": "openai", + "name": "OpenAI", "kind": "openai-compatible", - "base_url": "https://api.fireworks.ai/inference/v1", - "api_key": "$FIREWORKS_API_KEY", - "default_model": "accounts/fireworks/models/qwen3p7-plus", - "models": [ - "accounts/fireworks/models/qwen3p7-plus" - ] + "base_url": "https://api.openai.com/v1", + "api_key": "$OPENAI_API_KEY", + "default_model": "gpt-4.1", + "models": ["gpt-4.1"] } ] } @@ -65,11 +87,11 @@ Fields: - `name`: optional display name. - `kind`: required provider kind. Currently only `"openai-compatible"` is supported. - `base_url`: required OpenAI-compatible API base URL. -- `api_key`: required string. Use either a literal key or an environment-variable reference like `"$FIREWORKS_API_KEY"`. -- `default_model`: optional model id to use when no default model is configured. +- `api_key`: required string. Use either a literal key or an environment-variable reference like `"$OPENAI_API_KEY"`. +- `default_model`: optional model id used when no default model is configured. - `models`: optional list of model ids associated with this provider. -Only strings that start with `$` are resolved as environment variables. Cass does not expand partial strings or `${NAME}` syntax. +Only strings that start with `$` are resolved as environment variables. Cassady does not expand partial strings or `${NAME}` syntax. ## `models.json` @@ -79,10 +101,10 @@ Example: { "models": [ { - "id": "accounts/fireworks/models/qwen3p7-plus", - "provider": "fireworks", - "display_name": "Qwen 3p7 Plus", - "context_length": 262144, + "id": "gpt-4.1", + "provider": "openai", + "display_name": "GPT-4.1", + "context_length": 1047576, "max_output_tokens": 32768, "supports_tools": true, "supports_streaming": true, @@ -107,45 +129,22 @@ Fields: - `supports_tools`: optional boolean, defaults to `true`. - `supports_streaming`: optional boolean, defaults to `true`. - `reasoning`: optional object. Defaults to reasoning support enabled with medium effort for model entries. - - `supported`: optional boolean, defaults to `true`. Set to `false` for models that do not accept reasoning controls. - - `required`: optional boolean, defaults to `false`. If `true`, Cass will not cycle reasoning effort to `off`. - - `default_effort`: optional `off`, `low`, `medium`, or `high`; defaults to `medium`. Cannot be `off` when `required` is `true`. - - `request_format`: optional `reasoning_effort` or `reasoning_object`; defaults to `reasoning_effort`. `reasoning_effort` sends a top-level `"reasoning_effort": "medium"`; `reasoning_object` sends `"reasoning": { "effort": "medium" }`. + - `supported`: optional boolean, defaults to `true`. + - `required`: optional boolean, defaults to `false`. + - `default_effort`: optional `off`, `low`, `medium`, or `high`; defaults to `medium`. Cannot effectively be `off` when `required` is `true`. + - `request_format`: optional `reasoning_effort` or `reasoning_object`; defaults to `reasoning_effort`. -Reasoning effort is a runtime per-turn setting. Press `Tab` to cycle it while idle. For models with reasoning metadata, the default effort is `medium` unless overridden by `default_effort`; for models without metadata, reasoning starts `off`. +Reasoning effort is a runtime per-turn setting. Press `Tab` to cycle it while idle. Provider-streamed reasoning is persisted and sent back in future model context using the provider's reasoning field, such as `reasoning_content` or `reasoning`. -## Setup wizard +## Precedence -Run: - -```sh -cass setup -``` - -Cass also offers setup automatically when `cass` cannot resolve a usable active provider/model/API key before starting a chat. - -The wizard uses keyboard prompts: `↑`/`↓` moves through choices, `Space` selects providers in the multi-select screen, and `Enter` submits. Text fields use the same prompt style instead of falling back to plain line input. On an empty install, Cass opens this menu before reading default Fireworks settings, even if `FIREWORKS_API_KEY` is already set. - -The wizard supports configuring multiple OpenAI-compatible providers at once: - -| Provider | Base URL | Suggested env var | -| --- | --- | --- | -| OpenAI | `https://api.openai.com/v1` | `OPENAI_API_KEY` | -| xAI | `https://api.x.ai/v1` | `XAI_API_KEY` | -| Fireworks | `https://api.fireworks.ai/inference/v1` | `FIREWORKS_API_KEY` | -| Groq | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` | -| OpenRouter | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | -| OpenCode Zen | `https://opencode.ai/zen/v1` | `OPENCODE_API_KEY` | -| OpenCode Go | `https://opencode.ai/zen/go/v1` | `OPENCODE_API_KEY` | -| Cerebras | `https://api.cerebras.ai/v1` | `CEREBRAS_API_KEY` | -| Novita | `https://api.novita.ai/v3/openai` | `NOVITA_API_KEY` | -| Together | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` | - -There is also a custom OpenAI-compatible option. Custom setup asks for provider name, provider id, base URL, API key environment variable, and first model id. If you configure more than one provider, setup asks which one Cass should use first. - -Setup stores API keys as environment-variable references like `"$GROQ_API_KEY"` by default. If the selected environment variable is set, Cass tries to fetch models from `GET {base_url}/models` and lets you choose one. If discovery fails, Cass offers a retry before falling back to manual model entry. If the API key is not set, Cass asks you to enter a model id manually. - -After setup, Cass writes/updates `config.json`, `providers.json`, and `models.json`, validates them, and starts a new chat only when the active API key is available in the current shell. +- CLI access-mode flags override `default_access_mode` for the current session. +- `--model` overrides the configured default model for the current session. +- `--base-url` overrides the active provider base URL for the current session. +- `--api-key-env ENV` makes the active provider read `$ENV` for the current session. +- `config.json` preferences override built-in defaults. +- Provider defaults in `providers.json` are used when no configured model is selected. +- Environment variables provide the actual API key value when `api_key` starts with `$`. ## Check configuration @@ -155,14 +154,21 @@ Run: cass check ``` -This validates JSON syntax, expected schema, duplicate provider/model ids, model/provider references, active provider/model resolution, and API key environment-variable availability. Missing API keys for inactive providers are warnings; a missing active provider API key is an error. When setup is incomplete, `cass check` prints actionable next steps such as `export PROVIDER_API_KEY=...`, `cass check`, and `cass`. +This validates JSON syntax, expected schema, duplicate provider/model ids, model/provider references, active provider/model resolution, and API key environment-variable availability. Missing API keys for inactive providers are warnings; a missing active provider API key is an error. -## Ask Cass to edit config - -Run Cass in full-access mode and ask it to read these docs before editing: +When setup is incomplete, `cass check` prints actionable next steps such as: ```text -Read ~/.cass/docs/configuration.md, then add an OpenAI-compatible provider named Together using TOGETHER_API_KEY and add model metadata for meta-llama/Llama-3.1-70B-Instruct-Turbo. +export PROVIDER_API_KEY=... +cass check +cass ``` -After Cass edits the files, run `cass check`. +## Safe manual editing + +1. Edit one file at a time. +2. Keep provider ids and model provider references in sync. +3. Prefer API key env references over literal keys. +4. Run `cass check` before starting a chat. + +Invalid JSON, unknown fields, duplicate ids, and missing provider/model links are reported by `cass check` with the file that failed. diff --git a/docs/glossary.md b/docs/glossary.md new file mode 100644 index 0000000..f9cbf13 --- /dev/null +++ b/docs/glossary.md @@ -0,0 +1,29 @@ +# Glossary + +**Access mode**: The safety policy controlling which tools are available. Current modes are `read-only`, `workspace-edit`, and `full-access`. + +**Active provider**: The provider Cassady resolves for the current session after applying config and CLI overrides. + +**Bundled docs**: Markdown files embedded into the binary at build time and installed to `~/.cass/docs`. Cassady can read them; writes under this directory are blocked. + +**Cassady / Cass**: The project name is Cassady. The short command is `cass`; `cassady` is also installed. + +**Chat**: A persisted conversation with a model for one workspace. Chats are saved under `~/.cass/conversations` and can be resumed. + +**Config root**: The `~/.cass` directory containing config, conversations, global instructions, and installed docs. + +**Exact edit**: An `edit` tool replacement where each `old_text` must match exactly once in the original file before anything is written. + +**Global instructions**: Optional text in `~/.cass/global.md` included in new chat system prompts. + +**Model metadata**: The `models.json` entry describing a model id, owning provider, display name, context limits, tool/streaming support, and reasoning behavior. + +**OpenAI-compatible provider**: A provider exposing an API compatible with the OpenAI-style chat/completions behavior Cassady uses. + +**Provider**: A connection definition in `providers.json`, including id, base URL, API key reference, and optional default model. + +**Reasoning effort**: Runtime setting (`off`, `low`, `medium`, `high`) used for models with reasoning support. Press `Tab` while idle to cycle it. + +**Tool call**: A model-requested operation such as `ls`, `read`, `grep`, `write`, `edit`, or `shell`. + +**Workspace**: The launch cwd, either the current directory or the path passed with `--cwd`. In workspace-edit mode, writes must stay inside this root. diff --git a/docs/platforms.md b/docs/platforms.md new file mode 100644 index 0000000..7152e8e --- /dev/null +++ b/docs/platforms.md @@ -0,0 +1,60 @@ +# Platform notes + +Cassady is a terminal CLI. Most behavior is shared across platforms, but environment-variable syntax, paths, and terminal behavior differ. + +## macOS and Linux + +Set an API key for the current shell: + +```sh +export OPENAI_API_KEY=... +cass check +cass +``` + +Use normal POSIX paths: + +```sh +cass --cwd /Users/alex/project +cass --cwd /home/alex/project +``` + +Shell tools run through `sh -c` from the launch cwd. + +## Windows + +Release builds include a Windows x86_64 binary. Use PowerShell syntax for environment variables: + +```powershell +$env:OPENAI_API_KEY = "..." +cass check +cass +``` + +Example path usage: + +```powershell +cass --cwd C:\Users\alex\project +``` + +Current docs and examples are primarily terminal-CLI oriented. Deeper Windows polish for terminal behavior, path handling, shell behavior, filesystem edge cases, and release usability is planned for a later release. Avoid assuming every Windows path or shell edge case is polished in the current version. + +## Config location + +Cassady currently stores config under the home directory at: + +```text +~/.cass +``` + +That directory contains `config.json`, `providers.json`, `models.json`, `global.md`, `conversations/`, and installed bundled docs. + +## Non-interactive contexts + +- `cass check` is suitable for scripts and CI because it prints text and exits non-zero on errors. +- `cass setup` requires an interactive terminal. +- `cass` chat is an interactive terminal UI. + +## Release artifacts + +When using release archives, each archive contains both `cass` and `cassady`. Put the extracted binaries somewhere on your `PATH` or run them by explicit path. Cassady itself does not install, update, or manage PATH entries. diff --git a/docs/providers.md b/docs/providers.md new file mode 100644 index 0000000..c4276d4 --- /dev/null +++ b/docs/providers.md @@ -0,0 +1,102 @@ +# Providers and models + +Cassady currently supports OpenAI-compatible providers. A provider supplies the base URL and API key; a model entry supplies metadata for one model id used with that provider. + +## Built-in setup catalog + +The setup wizard offers these provider templates: + +| Provider | Provider id | Base URL | Suggested API key env var | +| --- | --- | --- | --- | +| OpenAI | `openai` | `https://api.openai.com/v1` | `OPENAI_API_KEY` | +| xAI | `xai` | `https://api.x.ai/v1` | `XAI_API_KEY` | +| Fireworks | `fireworks` | `https://api.fireworks.ai/inference/v1` | `FIREWORKS_API_KEY` | +| Groq | `groq` | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` | +| OpenRouter | `openrouter` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | +| OpenCode Zen | `opencode-zen` | `https://opencode.ai/zen/v1` | `OPENCODE_API_KEY` | +| OpenCode Go | `opencode-go` | `https://opencode.ai/zen/go/v1` | `OPENCODE_API_KEY` | +| Cerebras | `cerebras` | `https://api.cerebras.ai/v1` | `CEREBRAS_API_KEY` | +| Novita | `novita` | `https://api.novita.ai/v3/openai` | `NOVITA_API_KEY` | +| Together | `together` | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` | + +There is also a custom OpenAI-compatible option. Custom setup asks for provider name, provider id, base URL, API key environment variable, and first model id. + +## Model discovery + +When the selected API key environment variable is available, setup tries: + +```text +GET {base_url}/models +``` + +If the provider returns model ids, setup lets you choose one. If discovery fails, setup offers a retry and then falls back to manual model entry. Some OpenAI-compatible providers do not expose `/models` or require different permissions; manual entry is normal in that case. + +## Custom provider requirements + +A custom provider should expose OpenAI-compatible chat completions behavior at the configured base URL. Cassady may use: + +- streamed assistant text; +- tool call requests and tool results; +- optional reasoning fields or reasoning request controls; +- optional `/models` discovery during setup. + +Provider protocols that are not OpenAI-compatible are not currently supported. + +## Provider vs model metadata + +`providers.json` answers: how does Cassady connect? + +- provider id; +- base URL; +- API key reference; +- optional default model; +- optional list of associated model ids. + +`models.json` answers: what does this model support? + +- model id sent to the provider; +- owning provider id; +- display name; +- context length and max output tokens; +- tool and streaming support; +- reasoning support and request format. + +`config.json` selects active defaults, such as `default_provider`, `default_model`, and `default_access_mode`. + +## Reasoning metadata + +Reasoning metadata controls how the runtime reasoning effort behaves: + +- `supported: false`: reasoning effort stays `off`. +- `required: true`: `Tab` cycles through `low`, `medium`, and `high` without `off`. +- `default_effort`: starting effort for the model. +- `request_format: "reasoning_effort"`: sends a top-level `reasoning_effort` string. +- `request_format: "reasoning_object"`: sends a `reasoning` object with an effort. + +Reasoning display is separate. `show_reasoning` controls whether provider-streamed reasoning is visible in the transcript; press `Ctrl-Shift-R` or `Ctrl-R` to toggle it at runtime. + +## Switching models + +Use one of these approaches: + +```sh +cass --model MODEL +``` + +or inside a chat: + +```text +/model MODEL +``` + +The in-chat model autocomplete lists entries from `~/.cass/models.json`. Switching the model also updates the default model and reasoning effort in `config.json` for future sessions. + +## Health checks + +Run: + +```sh +cass check +``` + +This confirms that the active provider and model resolve and that the active API key environment variable is set. Missing inactive-provider keys are warnings; missing active-provider keys are errors. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 0000000..e1ad176 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,160 @@ +# Troubleshooting + +Use `cass check` first for configuration problems. It validates files, provider/model references, and API key availability. + +## Missing active API key + +Symptom: `cass check` reports that an environment variable is not set, or chat startup says the API key is not available. + +Likely cause: the active provider's `api_key` is an env reference such as `"$OPENAI_API_KEY"`, but that variable is not set in the current shell. + +Fix on macOS/Linux: + +```sh +export OPENAI_API_KEY=... +cass check +cass +``` + +Fix in PowerShell: + +```powershell +$env:OPENAI_API_KEY = "..." +cass check +cass +``` + +## Invalid API key reference + +Symptom: the key is not resolved the way you expect. + +Likely cause: Cassady only treats strings that start with `$` as environment references. It does not expand partial strings or `${NAME}` syntax. + +Fix: + +```json +{ "api_key": "$OPENAI_API_KEY" } +``` + +## Provider URL unreachable + +Symptom: setup model discovery fails or a turn reports a provider error. + +Likely causes: + +- wrong `base_url`; +- network or proxy problem; +- provider outage; +- provider requires a different OpenAI-compatible path. + +Fix: verify the base URL in `providers.json`, retry setup, or enter the model id manually if only `/models` discovery is failing. + +## `/models` discovery fails + +Symptom: setup cannot fetch models. + +Likely cause: some providers do not expose `GET /models`, require extra permissions, or return a non-standard shape. + +Fix: choose retry if the failure is temporary; otherwise enter the model id manually. Then run `cass check`. + +## Unsupported or invalid model id + +Symptom: chat starts but the provider rejects the model. + +Likely cause: the model id in `models.json` or `config.json` is not valid for the provider. + +Fix: update the model id with `cass setup`, edit `models.json`, or launch with: + +```sh +cass --model MODEL_ID +``` + +Then verify with a small prompt. + +## Rate limit or authentication errors + +Symptom: the assistant says the provider returned an error. + +Likely cause: provider-side authentication, quota, billing, or rate limit. + +Fix: confirm the API key, provider account status, selected model, and provider dashboard. Cassady forwards provider failures into the chat but cannot resolve account-level issues. + +## Invalid JSON or unknown config fields + +Symptom: `cass check` reports a parsing or schema error for `config.json`, `providers.json`, or `models.json`. + +Likely cause: invalid JSON, comments, trailing commas, misspelled fields, or a field in the wrong file. + +Fix: remove comments/trailing commas, compare against [Configuration](configuration.md), and run: + +```sh +cass check +``` + +## Workspace access denied + +Symptom: tool output says a path escapes allowed roots or workspace-edit root. + +Likely cause: the active mode is `read-only` or `workspace-edit`, and the path resolves outside the launch cwd or bundled docs. + +Fix: start from the intended project directory, pass `--cwd PATH`, or intentionally use `--full-access` when broad filesystem access is needed. + +## Shell unavailable or waiting for approval + +Symptom: shell is denied or Cassady asks for approval. + +Rules: + +- `read-only`: shell is unavailable. +- `workspace-edit`: shell requires approval. +- `full-access`: shell is allowed by policy. + +Fix: switch mode with `Shift-Tab` while idle or launch with the desired access flag. + +## Shell command failed or timed out + +Symptom: shell result includes stderr, non-zero exit code, or timeout. + +Likely cause: the command itself failed, the working directory is wrong, dependencies are missing, or the timeout was too short. + +Fix: inspect stdout/stderr, verify cwd in `/status`, and ask Cassady to rerun the smallest relevant command. + +## Exact-text edit failed + +Symptom: edit reports `old_text not found`, `old_text is not unique`, or overlapping edits. + +Likely cause: the file changed, whitespace differs, line endings differ, or the replacement text is too broad. + +Fix: ask Cassady to re-read the file and retry with a smaller unique `old_text`. For repeated blocks, include nearby unique context. + +## Binary, large, or unsupported files + +Symptom: read/edit output is confusing or fails. + +Likely cause: the file is binary, too large for useful display, or not valid UTF-8 for text edits. + +Fix: ask Cassady to list metadata or use project-specific tools through approved shell commands. Avoid direct text edits on binary files. + +## CRLF or line-ending confusion + +Symptom: exact-text edits fail even when the text appears to match. + +Likely cause: Windows CRLF line endings or invisible whitespace differences. + +Fix: re-read the exact target region and preserve the line endings in `old_text`, or use a smaller unique snippet. + +## Terminal rendering problems + +Symptom: the UI appears garbled or keys do not behave as expected. + +Likely cause: unsupported terminal features, redirected stdin/stdout, or platform-specific terminal behavior. + +Fix: run Cassady in an interactive terminal. Use `cass check` for non-interactive validation. Windows runtime polish is planned for a later release. + +## Setup says it is interactive + +Symptom: `cass setup` fails with `setup is interactive; run cass setup in a terminal`. + +Likely cause: stdin is not a terminal. + +Fix: run setup directly in a terminal, not through a non-interactive script or redirected input. diff --git a/docs/workflows.md b/docs/workflows.md new file mode 100644 index 0000000..209b9c1 --- /dev/null +++ b/docs/workflows.md @@ -0,0 +1,131 @@ +# Workflows + +This page shows common Cassady workflows. Exact tool calls depend on the model and the prompt; use these examples as patterns rather than scripts. + +## Start in a workspace + +```sh +cd /path/to/project +cass +``` + +Or choose a workspace explicitly: + +```sh +cass --cwd /path/to/project +``` + +Ask for read-only exploration first: + +```text +Explain the structure of this repository. Do not edit files yet. +``` + +## Inspect and explain code + +Start in read-only mode or press `Shift-Tab` until the status shows `read-only`. + +```text +Find where configuration is loaded and summarize the precedence rules. +``` + +Cassady can use `ls`, `read`, and `grep` to inspect the workspace and bundled docs. + +## Apply a focused edit + +Use workspace-edit mode: + +```sh +cass --workspace-edit +``` + +Then ask for a precise change: + +```text +Update the README install section to mention both cass and cassady. Keep the rest unchanged. +``` + +Cassady may use `edit` or `write`. Edit results include a diff-like summary. If an exact-text edit fails, ask Cassady to re-read the file and retry with a smaller unique replacement. + +## Run tests or builds + +Shell is denied in read-only mode and requires approval in workspace-edit mode. + +```text +Run the smallest relevant Rust test for this change, then summarize the result. +``` + +When the approval prompt appears, press `y` to approve or `n`/`Esc` to deny. Shell commands run with `sh -c` from the launch cwd and default to a 30-second timeout unless the model requests another timeout. + +## Switch model + +Inside a chat: + +```text +/model MODEL_ID +``` + +Autocomplete lists models from `~/.cass/models.json`. Switching models is allowed only when idle. Cassady persists the last used model and reasoning effort into `config.json`. + +You can also launch with a model override: + +```sh +cass --model MODEL_ID +``` + +## Resume a chat + +List chats for the current directory: + +```sh +cass --resume +``` + +Resume a specific chat: + +```sh +cass --resume CHAT_ID +``` + +Inside the UI: + +```text +/resume CHAT_ID +``` + +`/resume` autocomplete lists saved chats for the current directory. + +## Start fresh without leaving + +```text +/new +``` + +This creates a new chat for the same cwd and model while preserving your current configuration. + +## Check status + +```text +/status +``` + +The status block includes chat id, state, model, mode, cwd, record count, and the current status message. + +## Cancel and continue + +While a turn is running: + +- Press `Esc` or `Ctrl-C` to request turn cancellation. +- Press `Ctrl-C` twice within 1.5 seconds to exit. + +Cassady records cancelled tool calls and a cancellation message so the conversation can continue cleanly. + +## Ask Cassady to edit its config + +Config files live under `~/.cass`, outside a normal project workspace. To inspect them, use `full-access` or edit them manually. After manual changes, run: + +```sh +cass check +``` + +Prefer `cass setup` for provider/model changes when possible. diff --git a/plans/V0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md b/plans/V0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md new file mode 100644 index 0000000..58398b9 --- /dev/null +++ b/plans/V0_2_3_DOCUMENTATION_README_REFRESH_PLAN.md @@ -0,0 +1,375 @@ +# v0.2.3 Documentation and README Refresh Implementation Plan + +## Goal + +v0.2.3 refreshes Cassady's user-facing documentation so a new or returning user can understand what Cassady does, configure it successfully, use it safely in a project, and recover from common failures without reading the source. The README should become the polished entry point, while bundled docs under `docs/` should provide accurate reference material that the CLI can install into `~/.cass/docs`. + +Success statement: + +> A user can start from the README, run the documented setup/check/chat commands, understand the current provider/model/access-mode model, and find accurate troubleshooting guidance for the shipped v0.2.3 CLI. + +## Scope + +### In scope + +- Rewrite `README.md` around the current Cassady experience. +- Refresh bundled docs in `docs/`, which are embedded by `src/docs.rs` and installed to `~/.cass/docs`. +- Add or split reference docs for commands, configuration, providers/models, access modes/tool safety, workflows, troubleshooting, platform notes, and glossary terms. +- Audit and update CLI help text in `src/cli.rs` only where it contradicts or underspecifies documented behavior. +- Verify documented commands and examples against the actual CLI behavior. +- Add lightweight documentation tests where practical, especially for bundled-doc presence and link integrity. +- Keep documentation for both command names: `cass` and `cassady`. +- Clearly describe current limitations and defer deep Windows runtime improvements to v0.2.4. + +### Out of scope + +- Broad CLI feature work or behavior changes beyond correcting inaccurate help text. +- Windows terminal, filesystem, shell, and process usability fixes planned for v0.2.4. +- Installer, package manager, code signing, auto-update, or PATH setup documentation that implies unsupported release channels. +- Adding new provider protocols such as Anthropic-native APIs. +- Reworking config formats or access-mode policy implementation. +- Creating exhaustive model catalogs for providers. + +## Context and Current State + +Relevant files: + +- `README.md`: current root overview; accurate in places but short and reference-heavy. +- `docs/README.md`: bundled-doc index installed at runtime. +- `docs/configuration.md`: current bundled configuration/setup reference; includes substantial v0.2.2 setup details. +- `src/docs.rs`: embeds all files in `docs/`; changing docs changes the build-time docs hash. +- `src/cli.rs`: Clap definitions for global flags and `check`/`setup` subcommands. +- `src/check.rs`: rendered `cass check` output and next-step wording. +- `src/setup.rs`: setup wizard prompts and provider catalog. +- `src/config.rs`: config file schema, defaults, precedence, provider/model resolution. +- `src/access.rs`, `src/security.rs`, and `src/tools/*`: access-mode/tool behavior that docs must describe accurately. +- `src/app.rs`, `src/ui/render.rs`, `src/ui/events.rs`: chat commands, keys, rendering, cancellation, tool display, reasoning toggles. +- `tests/docs_tests.rs`: current docs-related test coverage. + +Existing documentation facts to preserve when accurate: + +- Cassady ships two binaries, `cass` and `cassady`. +- `cass` starts chat by default; `cass setup` runs the setup wizard; `cass check` validates config non-interactively. +- Config lives under `~/.cass` today, with bundled docs installed to `~/.cass/docs`. +- Provider/model configuration uses `config.json`, `providers.json`, and `models.json`. +- OpenAI-compatible providers are the only supported provider kind. +- API keys should usually be environment-variable references such as `"$FIREWORKS_API_KEY"`. +- Access modes are `read-only`, `workspace-edit`, and `full-access`. +- Tool output is compact by default; `Ctrl-O` toggles full tool output. +- Reasoning is hidden by default; `Ctrl-Shift-R` toggles display and `Tab` cycles effort. + +## Design Principles + +1. **Docs are product UX.** Write polished explanatory prose, not a dump of implementation checklists. +2. **Verify before claiming.** Every command, flag, env var, provider URL, config field, keybinding, and output snippet should be checked against the code or an actual run. +3. **README first, references second.** Keep `README.md` focused on orientation, first use, common workflows, and links; move long tables and detailed references into `docs/`. +4. **One terminology set.** Use consistent names: Cassady/Cass, workspace, session/chat, provider, model, access mode, tool call, tool result, setup wizard, bundled docs. +5. **Avoid future promises.** Mention Windows limitations and planned v0.2.4 work without promising unimplemented terminal/process/path behavior. +6. **Security-forward but practical.** Explain what Cassady can read, write, and run before encouraging users to grant broader access. + +## Documentation Architecture + +Use this structure unless implementation reveals a simpler split is better: + +```text +README.md + +docs/README.md +docs/commands.md +docs/configuration.md +docs/providers.md +docs/access-modes.md +docs/workflows.md +docs/troubleshooting.md +docs/platforms.md +docs/glossary.md +``` + +### Root README role + +`README.md` should be the public landing page and fast-start guide. Suggested sections: + +1. `# Cassady / Cass` +2. Short product summary and current limitations. +3. Install from source for development/current release usage. +4. First use walkthrough. +5. Everyday workflows. +6. Safety model summary. +7. Commands and key shortcuts summary. +8. Configuration and providers summary with links. +9. Troubleshooting quick links. +10. Bundled docs and repository docs map. + +Keep the README concise enough to read top-to-bottom. Move long provider tables, config schemas, and troubleshooting matrices into bundled docs. + +### Bundled docs role + +Bundled docs are installed to `~/.cass/docs` and are accessible to Cassady's docs tools. They should be self-contained enough to help a user inside a session. + +- `docs/README.md`: index with short descriptions and links to all bundled docs. +- `docs/commands.md`: complete CLI command, flag, alias, startup, interactive-vs-non-interactive, resume, and output-mode reference. +- `docs/configuration.md`: config file locations, schemas, examples, precedence, validation, safe editing. +- `docs/providers.md`: built-in OpenAI-compatible provider catalog, custom providers, model discovery, manual model entry, health checks, unsupported protocols. +- `docs/access-modes.md`: read/write/edit/shell/docs access by mode, approvals, denied examples, workspace boundaries, symlink notes, diff review. +- `docs/workflows.md`: task-oriented examples for chat, file inspection, edits, test/build commands, model switching, cancellation recovery. +- `docs/troubleshooting.md`: actionable fixes for setup, provider/API, config, terminal, shell, edit, access, and line-ending failures. +- `docs/platforms.md`: macOS/Linux/Windows notes, env var examples, path examples, known Windows limitations, no installer promises. +- `docs/glossary.md`: definitions for recurring concepts. + +## Detailed Content Requirements + +### README rewrite + +Include a current, concise product description: + +```md +Cassady (`cass`) is a terminal coding agent written in Rust. It runs an interactive chat in your project, can inspect files, propose and apply edits, run approved shell commands, and persist sessions for later resume. It currently talks to OpenAI-compatible providers. +``` + +Document limitations explicitly: + +- Only OpenAI-compatible chat/completions-style providers are supported. +- Built-in docs and examples assume a terminal CLI workflow. +- Windows support exists through cross-built binaries but deep Windows runtime polish is planned for v0.2.4. +- Cassady is not an installer/updater/package manager. + +### First-use walkthrough + +Show a linear path: + +```sh +cass +# or explicitly: +cass setup +cass check +cass +``` + +Cover: + +- First-run setup trigger when active provider/model/API key cannot be resolved. +- Provider selection from built-ins or custom OpenAI-compatible endpoint. +- API key env vars, with POSIX and PowerShell examples labelled clearly. +- Model discovery via `GET /models`, retry, and manual model id fallback. +- What happens if setup writes config but the API key is still missing. +- How to recover with `cass setup` and `cass check`. + +### Command reference + +Document these top-level forms based on `src/cli.rs`: + +```sh +cass [OPTIONS] +cassady [OPTIONS] +cass check [OPTIONS] +cass setup [OPTIONS] +cass --resume [CHAT_ID] +``` + +Document global options: + +- `--resume [CHAT_ID]` +- `--model MODEL` +- `--base-url URL` +- `--api-key-env ENV` +- `--cwd PATH` +- `--readonly` +- `--workspace-edit` +- `--full-access` +- `--help` +- `--version` + +Also document in-chat commands and keys from current behavior, including `/model`, `/new`, `/resume`, `/status`, `/`, `Tab`, `Shift-Tab`, `Ctrl-O`, `Ctrl-Shift-R`, scrolling, multiline input, and double `Ctrl-C` exit. Verify exact command names in code before finalizing. + +### Configuration reference + +Keep `docs/configuration.md` as the canonical config reference. It should explain: + +- Location under `~/.cass` and current portability caveat. +- `config.json`, `providers.json`, `models.json` responsibilities. +- Default provider/model behavior and compatibility fields. +- Precedence between config files, CLI overrides, setup wizard changes, and env vars. +- API key reference syntax: only strings beginning with `$` are env refs; no partial expansion or `${NAME}` syntax unless code supports it. +- Safe manual edits and `cass check` validation. +- Valid and invalid JSON examples with fixes. + +### Provider and model guide + +Create `docs/providers.md` and move long provider details there. Include the v0.2.2 provider catalog: + +| Provider | Provider id | Base URL | Suggested API key env var | +| --- | --- | --- | --- | +| OpenAI | `openai` | `https://api.openai.com/v1` | `OPENAI_API_KEY` | +| xAI | `xai` | `https://api.x.ai/v1` | `XAI_API_KEY` | +| Fireworks | `fireworks` | `https://api.fireworks.ai/inference/v1` | `FIREWORKS_API_KEY` | +| Groq | `groq` | `https://api.groq.com/openai/v1` | `GROQ_API_KEY` | +| OpenRouter | `openrouter` | `https://openrouter.ai/api/v1` | `OPENROUTER_API_KEY` | +| OpenCode Zen | `opencode-zen` | `https://opencode.ai/zen/v1` | `OPENCODE_API_KEY` | +| OpenCode Go | `opencode-go` | `https://opencode.ai/zen/go/v1` | `OPENCODE_API_KEY` | +| Cerebras | `cerebras` | `https://api.cerebras.ai/v1` | `CEREBRAS_API_KEY` | +| Novita | `novita` | `https://api.novita.ai/v3/openai` | `NOVITA_API_KEY` | +| Together | `together` | `https://api.together.xyz/v1` | `TOGETHER_API_KEY` | + +Also explain: + +- Provider configuration vs model metadata vs active defaults. +- Model discovery limits and manual model id entry. +- `supports_tools`, `supports_streaming`, and reasoning metadata in user-facing terms. +- Unsupported provider protocols and what a custom OpenAI-compatible provider must implement. + +### Access modes and tool safety + +Create `docs/access-modes.md`. Include a mode/tool matrix such as: + +| Tool area | read-only | workspace-edit | full-access | +| --- | --- | --- | --- | +| List/read/grep workspace files | yes | yes | yes | +| Write/edit workspace files | no | yes | yes | +| Read bundled docs | yes | yes | yes | +| Write bundled docs | no | no | no | +| Shell commands | no or denied unless code says otherwise | approval required | approval/destructive confirmation as implemented | +| Outside workspace | no | no | allowed subject to OS permissions | + +Verify exact shell availability and approval behavior from `src/access.rs`, `src/security.rs`, and `src/tools/shell.rs` before publishing this table. + +Include denied-operation examples with realistic wording based on actual errors, not invented output if the code differs. + +### Workflows and examples + +Create `docs/workflows.md` with short examples for: + +- Starting a chat in a workspace. +- Asking Cassady to inspect files and explain code. +- Asking for a proposed edit, reviewing tool calls, and applying edits. +- Running tests or builds with shell approval. +- Switching model with `/model `. +- Resuming sessions with `cass --resume` and `/resume`. +- Cancelling a turn and continuing cleanly. + +Examples should be realistic but not overly long. Avoid implying that Cassady will always make a specific sequence of tool calls. + +### Troubleshooting + +Create `docs/troubleshooting.md` organized by symptom. Include: + +- Missing active API key. +- Invalid env var references. +- Provider URL unreachable. +- `/models` discovery failure. +- Unsupported/invalid model id. +- Rate limit/authentication errors. +- Invalid JSON or unreadable config files. +- Terminal rendering issues and redirected output caveats. +- Shell command failures and approval/cancellation behavior. +- Exact-text edit failures. +- Binary/large/unsupported files. +- CRLF/line-ending confusion. +- Workspace access denials and symlink/bundled-doc restrictions. + +Each entry should include: symptom, likely cause, fix, and command to verify when applicable. + +### Platform notes + +Create `docs/platforms.md` with careful current-state language: + +- macOS/Linux examples can use POSIX shell syntax such as `export NAME=...`. +- Windows examples should be labelled and use PowerShell syntax such as `$env:OPENAI_API_KEY = "..."`. +- Document Windows path examples without claiming every Windows path edge case is polished. +- State that v0.2.4 is planned to improve Windows terminal, path, shell, and filesystem behavior. +- Avoid installation-channel promises beyond current source/release-artifact facts. + +## Implementation Steps + +1. **Inventory current behavior.** + - Run `cargo run -- --help`, `cargo run -- check --help`, and `cargo run -- setup --help`. + - Review `src/cli.rs`, `src/setup.rs`, `src/config.rs`, `src/access.rs`, `src/security.rs`, `src/tools/*`, and relevant UI command/key handling. + - Record exact command names, flags, config fields, provider catalog entries, access rules, and keybindings. + +2. **Design the docs map.** + - Confirm the final bundled docs file list. + - Decide which details stay in `README.md` and which move to `docs/`. + - Keep `docs/README.md` as the navigable index. + +3. **Rewrite `README.md`.** + - Replace stale MVP/default-only language with current v0.2.2+ behavior. + - Add first-use walkthrough, everyday workflows, safety summary, limitations, and links to detailed docs. + - Keep examples copy/paste-ready and label platform-specific syntax. + +4. **Refresh bundled reference docs.** + - Update `docs/configuration.md` instead of duplicating schema details elsewhere. + - Add `docs/commands.md`, `docs/providers.md`, `docs/access-modes.md`, `docs/workflows.md`, `docs/troubleshooting.md`, `docs/platforms.md`, and `docs/glossary.md` as needed. + - Update `docs/README.md` links and summaries. + +5. **Synchronize CLI help text.** + - Make minimal edits to `src/cli.rs` descriptions if help text conflicts with the refreshed docs. + - Do not change command behavior in this release unless a documentation verification step uncovers a severe typo or misleading help string. + +6. **Add lightweight docs validation.** + - Extend `tests/docs_tests.rs` or add a new docs test to ensure all linked bundled docs exist. + - Consider checking that `docs/README.md` links are relative and valid. + - If practical, add a test that important terms or command names appear in the bundled docs index. + +7. **Verify examples.** + - Run documented help/check/setup commands where safe. + - Use a temporary Cass root or environment isolation for config examples when possible. + - Verify internal links and fenced command snippets manually or with tests. + +8. **Final consistency pass.** + - Search for old terminology, obsolete commands, stale provider data, and outdated MVP wording. + - Ensure README, bundled docs, CLI help, and roadmap use the same terms. + - Run formatting/tests. + +## Tests and Verification + +Automated checks: + +```sh +cargo fmt --check +cargo test --locked --all-targets +``` + +Docs-specific checks to add or perform: + +- `tests/docs_tests.rs` validates bundled docs install/embedding behavior still passes. +- New or updated test validates `docs/README.md` links resolve to existing bundled docs files. +- `cargo run -- --help` output matches `docs/commands.md`. +- `cargo run -- check --help` and `cargo run -- setup --help` output are documented accurately. +- `cargo run -- check` behavior is represented accurately, preferably with a temp config root if the code supports test helpers. + +Manual review checklist: + +- Every internal Markdown link works. +- Every command name exists. +- Every flag is spelled exactly as Clap exposes it. +- Every provider URL/env var matches setup's provider catalog. +- Every config field in examples is accepted by the current parser. +- Access-mode descriptions match current policy code. +- Windows notes are cautious and do not include v0.2.4 promises as current behavior. + +## Documentation Deliverables + +Required: + +- Updated `README.md`. +- Updated `docs/README.md`. +- Updated `docs/configuration.md`. +- New command/provider/access/workflow/troubleshooting/platform/glossary docs, unless the implementer chooses a smaller file split and preserves all required content. +- Any necessary tiny CLI help text corrections. +- Updated docs tests. + +Not required: + +- Release notes, unless the release process is being run. +- Website docs. +- Generated `dist/` artifacts. + +## Acceptance Criteria + +- `README.md` accurately describes current Cassady behavior and guides first use from setup through first chat. +- Bundled docs provide complete references for commands, config, providers/models, access modes/tool safety, workflows, troubleshooting, platforms, and glossary concepts. +- Documentation covers both `cass` and `cassady` command names. +- Provider catalog, API key env vars, config examples, access mode descriptions, and keybindings match the code. +- Windows documentation is accurate but clearly defers deep Windows runtime polish to v0.2.4. +- Obsolete MVP language, stale commands, and misleading defaults are removed. +- Internal links resolve and docs tests cover bundled-doc navigation where practical. +- `cargo fmt --check` and `cargo test --locked --all-targets` pass before release handoff. diff --git a/tests/docs_tests.rs b/tests/docs_tests.rs index 126d3f0..91f4975 100644 --- a/tests/docs_tests.rs +++ b/tests/docs_tests.rs @@ -1,3 +1,4 @@ +use std::path::Path; use tempfile::tempdir; #[test] @@ -18,3 +19,71 @@ fn install_extracts_bundled_docs_with_stamp() { let second_install = cassady::docs::install(root.path()).unwrap(); assert_eq!(second_install, docs_dir); } + +#[test] +fn bundled_docs_links_resolve() { + let docs_root = Path::new(env!("CARGO_MANIFEST_DIR")).join("docs"); + + for entry in std::fs::read_dir(&docs_root).unwrap() { + let path = entry.unwrap().path(); + if path.extension().and_then(|ext| ext.to_str()) != Some("md") { + continue; + } + let text = std::fs::read_to_string(&path).unwrap(); + for target in markdown_links(&text) { + if target.starts_with("http://") + || target.starts_with("https://") + || target.starts_with('#') + { + continue; + } + let target_path = target.split('#').next().unwrap_or(target.as_str()); + if target_path.is_empty() { + continue; + } + assert!( + docs_root.join(target_path).is_file(), + "{} links to missing bundled doc: {target}", + path.display() + ); + } + } +} + +#[test] +fn expected_bundled_docs_exist() { + let docs_root = Path::new(env!("CARGO_MANIFEST_DIR")).join("docs"); + for file in [ + "README.md", + "commands.md", + "configuration.md", + "providers.md", + "access-modes.md", + "workflows.md", + "troubleshooting.md", + "platforms.md", + "glossary.md", + ] { + assert!(docs_root.join(file).is_file(), "missing docs/{file}"); + } +} + +fn markdown_links(text: &str) -> Vec { + let mut links = Vec::new(); + let bytes = text.as_bytes(); + let mut i = 0; + while i < bytes.len() { + if bytes[i] == b'[' { + if let Some(close) = text[i..].find("](") { + let start = i + close + 2; + if let Some(end) = text[start..].find(')') { + links.push(text[start..start + end].to_string()); + i = start + end + 1; + continue; + } + } + } + i += 1; + } + links +}