From 2077894896ca1b8dcdfef20866b4f644caa2da08 Mon Sep 17 00:00:00 2001 From: Owen Qwen Date: Wed, 24 Jun 2026 03:02:51 -0500 Subject: [PATCH] Update roadmap and agent instructions --- AGENTS.md | 392 +++++++++++++++++++++++++++++++++++++++++++++++++++++ ROADMAP.md | 185 +++++++++++++++++++++++++ 2 files changed, 577 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..8686351 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,392 @@ +# AGENTS.md + +## Release process: build artifacts and create a draft GitHub release + +Use this process when preparing a Cassady (`cass`) release. Always create the GitHub release as a **draft** first; do not publish the final release unless the user explicitly asks. + +### 1. Review prior releases for consistency + +```sh +git fetch origin --tags +gh release list --repo owenqwenstarsky/cassady --limit 5 +gh release view --repo owenqwenstarsky/cassady --json tagName,body --jq '.tagName + "\n\n" + .body' +``` + +Keep release notes consistent with the existing format: + +- Title: `## Cassady vX.Y.Z` +- One short summary paragraph. +- `### Downloads` with four bullets in this order: macOS Apple Silicon, Linux x86_64, Linux ARM64, Windows x86_64. +- Note that each archive contains both `cass` and `cassady`; mention SHA-256 files. +- `### Highlights` with concise user-facing bullets. +- Optional `### Upgrade notes` only when compatibility, config, or migration details matter. +- `### Install from source` with a `cargo install --git ... --tag vX.Y.Z` command. +- `### Verification` listing the exact test/build commands used. + +### 2. Confirm the version and starting state + +```sh +git status --short +VERSION=$(awk -F\" '/^version = / { print $2; exit }' Cargo.toml) +TAG="v${VERSION}" +echo "$TAG" +git log --oneline --decorate -20 +``` + +If the version is wrong, update `Cargo.toml` and `Cargo.lock` first, then commit that change before tagging. Release tags should point at the intended release commit on `main`. + +### 3. Run verification before packaging + +```sh +cargo +stable test --locked --all-targets +``` + +### 4. Build all release binaries + +Prerequisites for cross-builds: stable Rust, `cargo-zigbuild`, Zig, and the needed Rust targets. + +```sh +rustup target add aarch64-apple-darwin x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu x86_64-pc-windows-gnu +cargo install cargo-zigbuild --locked +``` + +Build the same four targets used by previous releases: + +```sh +cargo +stable build --release --locked --target aarch64-apple-darwin +cargo +stable zigbuild --release --locked --target x86_64-unknown-linux-gnu +cargo +stable zigbuild --release --locked --target aarch64-unknown-linux-gnu +cargo +stable zigbuild --release --locked --target x86_64-pc-windows-gnu +``` + +### 5. Rebuild the `dist/` artifacts + +This creates the unpacked artifact directories, compressed archives, and checksum files for the current `$TAG`. Generate checksums from inside `dist/` so the `.sha256` files contain archive names without a `dist/` prefix. + +```sh +VERSION=$(awk -F\" '/^version = / { print $2; exit }' Cargo.toml) +TAG="v${VERSION}" + +rm -rf \ + "dist/cassady-${TAG}-aarch64-apple-darwin"* \ + "dist/cassady-${TAG}-x86_64-unknown-linux-gnu"* \ + "dist/cassady-${TAG}-aarch64-unknown-linux-gnu"* \ + "dist/cassady-${TAG}-x86_64-pc-windows-gnu"* + +mkdir -p dist + +for target in aarch64-apple-darwin x86_64-unknown-linux-gnu aarch64-unknown-linux-gnu; do + name="cassady-${TAG}-${target}" + mkdir -p "dist/${name}" + cp "target/${target}/release/cass" "dist/${name}/cass" + cp "target/${target}/release/cassady" "dist/${name}/cassady" + cp README.md "dist/${name}/README.md" + tar -C dist -czf "dist/${name}.tar.gz" "${name}" +done + +win_target=x86_64-pc-windows-gnu +win_name="cassady-${TAG}-${win_target}" +mkdir -p "dist/${win_name}" +cp "target/${win_target}/release/cass.exe" "dist/${win_name}/cass.exe" +cp "target/${win_target}/release/cassady.exe" "dist/${win_name}/cassady.exe" +cp README.md "dist/${win_name}/README.md" +(cd dist && zip -qr "${win_name}.zip" "${win_name}") + +(cd dist && for artifact in cassady-${TAG}-*.tar.gz cassady-${TAG}-*.zip; do + shasum -a 256 "$artifact" > "${artifact}.sha256" +done) +``` + +Sanity-check the generated artifacts: + +```sh +ls -lh dist/cassady-${TAG}-*.tar.gz dist/cassady-${TAG}-*.zip dist/cassady-${TAG}-*.sha256 +for sum in dist/cassady-${TAG}-*.sha256; do (cd dist && shasum -a 256 -c "$(basename "$sum")"); done +tar -tzf "dist/cassady-${TAG}-aarch64-apple-darwin.tar.gz" | head +unzip -l "dist/cassady-${TAG}-x86_64-pc-windows-gnu.zip" | head +``` + +### 6. Write the release notes + +Create `dist/RELEASE_NOTES_${TAG}.md` using the same structure as prior releases. Use this template and replace the summary/highlights with the actual changes: + +````md +## Cassady vX.Y.Z + +Cassady vX.Y.Z ... + +### Downloads + +- macOS Apple Silicon: `cassady-vX.Y.Z-aarch64-apple-darwin.tar.gz` +- Linux x86_64: `cassady-vX.Y.Z-x86_64-unknown-linux-gnu.tar.gz` +- Linux ARM64: `cassady-vX.Y.Z-aarch64-unknown-linux-gnu.tar.gz` +- Windows x86_64: `cassady-vX.Y.Z-x86_64-pc-windows-gnu.zip` + +Each archive contains both `cass` and `cassady`. SHA-256 checksum files are included for every archive. + +### Highlights + +- ... + +### Upgrade notes + +... + +### Install from source + +```sh +cargo install --git https://github.com/owenqwenstarsky/cassady --tag vX.Y.Z +``` + +### Verification + +Built and tested with: + +```sh +cargo +stable test --locked --all-targets +cargo +stable build --release --locked --target aarch64-apple-darwin +cargo +stable zigbuild --release --locked --target x86_64-unknown-linux-gnu +cargo +stable zigbuild --release --locked --target aarch64-unknown-linux-gnu +cargo +stable zigbuild --release --locked --target x86_64-pc-windows-gnu +``` +```` + +Check the notes before uploading: + +```sh +sed -n '1,220p' "dist/RELEASE_NOTES_${TAG}.md" +``` + +### 7. Tag the release commit + +Only tag after tests pass, artifacts are built, and release notes are ready. + +```sh +git fetch origin --tags +git status --short # should be clean except generated dist/ files +git tag -a "$TAG" -m "Cassady ${TAG}" +git push origin "$TAG" +``` + +If the tag already exists, stop and ask before deleting or moving it. + +### 8. Create the GitHub release as a draft + +Upload only the current version's archives and checksum files. Keep `--draft` and `--verify-tag` in the command. + +```sh +gh release create "$TAG" \ + "dist/cassady-${TAG}-aarch64-apple-darwin.tar.gz" \ + "dist/cassady-${TAG}-aarch64-apple-darwin.tar.gz.sha256" \ + "dist/cassady-${TAG}-x86_64-unknown-linux-gnu.tar.gz" \ + "dist/cassady-${TAG}-x86_64-unknown-linux-gnu.tar.gz.sha256" \ + "dist/cassady-${TAG}-aarch64-unknown-linux-gnu.tar.gz" \ + "dist/cassady-${TAG}-aarch64-unknown-linux-gnu.tar.gz.sha256" \ + "dist/cassady-${TAG}-x86_64-pc-windows-gnu.zip" \ + "dist/cassady-${TAG}-x86_64-pc-windows-gnu.zip.sha256" \ + --repo owenqwenstarsky/cassady \ + --title "Cassady ${TAG}" \ + --notes-file "dist/RELEASE_NOTES_${TAG}.md" \ + --draft \ + --verify-tag +``` + +Verify the draft: + +```sh +gh release view "$TAG" --repo owenqwenstarsky/cassady --json tagName,name,isDraft,isPrerelease,assets --jq . +``` + +Do **not** publish the draft or mark it as the final/latest release unless the user explicitly asks. + +## Roadmap process: write a new release entry in `ROADMAP.md` + +Use this process when planning a future Cassady release. Follow the existing newest-first format in `ROADMAP.md` so new entries look like prior releases. + +### 1. Review the existing roadmap format + +```sh +sed -n '1,220p' ROADMAP.md +ls plans +``` + +Current conventions: + +- Keep the `# Cassady (Cass) Roadmap` title at the top. +- Add the newest release immediately below the title, above older releases. +- Use headings like `## vX.Y.Z — Short Theme` for planned releases. +- Add `✅ Completed` to the heading only after the release is actually complete. +- Start with a short paragraph: `This release focuses on ...`. +- If there is a detailed plan, reference it with a sentence like: See `plans/PLAN_FILE.md`. +- Group work under `###` area headings such as `Interactive Setup`, `Agent Control`, or `Safety and Reviewability`. +- Use checklist items: `- [ ]` for planned work, `- [x]` for completed work. +- Write main tasks as bold, user-facing outcomes: `**Add a first-run setup wizard.** ...`. +- Use indented bullets for scope details, constraints, and explicit deferrals. + +### 2. Decide the release scope + +Before editing `ROADMAP.md`, identify: + +- Version number: `vX.Y.Z`. +- Short theme: a concise release name after the em dash. +- One-paragraph goal: what the release changes for users. +- 2-4 major areas to group the work. +- Concrete checklist tasks under each area. +- Any intentionally deferred work, especially broad integrations or risky scope. +- Optional plan file under `plans/` if the release needs deeper implementation detail. + +Prefer roadmap items that describe outcomes and acceptance criteria, not implementation minutiae. Keep them concise enough to scan. + +### 3. Insert the new entry + +Place the new release section directly under the top-level title: + +```md +# Cassady (Cass) Roadmap + +## vX.Y.Z — Short Release Theme + +This release focuses on ... See `plans/VX_Y_Z_SHORT_PLAN.md`. + +### Area Name + +- [ ] **User-facing task title.** Describe the outcome in one sentence. + - Add key behavior or acceptance criteria. + - Note constraints or non-goals. + +- [ ] **Second task title.** Describe the next outcome. + - Include compatibility, docs, tests, or safety requirements when relevant. + +### Another Area + +- [ ] **Another task title.** Describe the outcome. + - Keep details specific and checkable. + +## vPrevious — Existing Theme ✅ Completed +``` + +If there is no detailed plan file yet, omit the `See ...` sentence rather than linking to a nonexistent file. + +### 4. Keep old entries stable + +- Do not reorder completed releases except to insert the new release at the top. +- Do not rewrite old completed scopes unless correcting a clear error. +- Use `[x]` only for work that has landed. +- Add `✅ Completed` only when the release has shipped or the user explicitly asks to mark it complete. +- Keep wording consistent with earlier entries: concise headings, bold task names, and nested details. + +### 5. Check the edit + +```sh +sed -n '1,180p' ROADMAP.md +git diff -- ROADMAP.md +``` + +## Plan process: write implementation plans in `plans/` + +Use this process when creating or updating an implementation plan. All project plans belong in the `plans/` directory; do not put new plan documents at the repository root. + +### 1. Review previous plans first + +```sh +ls plans +sed -n '1,240p' plans/V0_2_2_ONBOARDING_SETUP_WIZARD_PLAN.md +sed -n '1,220p' plans/V0_2_1_MESSAGE_RENDERING_POLISH_PLAN.md +sed -n '1,220p' plans/V0_2_1_COLLAPSED_TOOL_DENSITY_PLAN.md +``` + +Also read any plan that is directly related to the new work. For example, read `plans/SECURITY_ACCESS_MODES_PLAN.md` before planning access-control work, or `plans/PROVIDER_MODEL_CONFIG_PLAN.md` before planning provider/config changes. + +### 2. Choose the plan filename + +Write new plans under `plans/` using uppercase snake-case names: + +- Release-scoped plan: `plans/VX_Y_Z_SHORT_THEME_PLAN.md`, e.g. `plans/V0_2_3_CONTEXT_MANAGEMENT_PLAN.md`. +- Feature/follow-up plan: `plans/FEATURE_OR_AREA_PLAN.md`, e.g. `plans/SECURITY_ACCESS_MODES_PLAN.md`. +- Follow-up to an existing release plan: include the version and specific topic, e.g. `plans/V0_2_1_COLLAPSED_TOOL_DENSITY_PLAN.md`. + +Prefer one focused plan per coherent feature or release theme. Do not edit `plans/PLAN.md` for new release work; it is the historical MVP plan. + +### 3. Match the existing plan structure + +Most plans should use this shape, adapted to the task size: + +````md +# vX.Y.Z Short Theme Implementation Plan + +## Goal + +State the user-facing outcome in a short paragraph. If helpful, add a success statement. + +## Scope + +### In scope + +- Concrete included work. +- Supported behavior and user-visible changes. + +### Out of scope + +- Explicit non-goals and deferred work. +- Integrations or risky scope that should not be pulled into this plan. + +## Context or Current State + +Describe the relevant files, modules, existing behavior, and constraints. + +## Design Principles + +1. Principle that guides tradeoffs. +2. Safety, compatibility, or UX constraint. +3. Simplicity or deferral rule. + +## Design + +Describe the proposed behavior and architecture. Include tables, examples, CLI output, JSON shapes, or module/type sketches when they make implementation clearer. + +## Implementation Steps + +1. First concrete code/docs step. +2. Next step. +3. Final integration step. + +## Tests + +- Specific unit/integration tests to add or update. +- Manual checks when automated tests are not enough. + +## Documentation + +- README, bundled docs, release notes, or roadmap updates required. + +## Acceptance Criteria + +- Checkable condition that proves the plan is done. +- `cargo fmt` and `cargo test --locked --all-targets` pass. +```` + +For small follow-ups, it is okay to use the shorter style from `V0_2_1_COLLAPSED_TOOL_DENSITY_PLAN.md`: `Context`, `Goal`, `Scope`, `Design`, `Implementation Steps`, and `Acceptance Criteria`. + +### 4. Writing guidelines + +- Keep plans implementation-oriented but readable by a future agent. +- Be explicit about in-scope vs out-of-scope work to prevent scope creep. +- Mention exact files/modules when known, such as `src/ui/render.rs` or `src/config.rs`. +- Include examples of expected CLI output, JSON, or UI text when behavior matters. +- Add compatibility and migration notes when config, storage, provider behavior, or public commands change. +- Add docs and tests sections for any user-facing change. +- Prefer ordered implementation steps over vague tasks. +- Do not mark roadmap items complete just because a plan was written. + +### 5. Check the plan + +```sh +sed -n '1,260p' plans/YOUR_PLAN_FILE.md +git diff -- plans/YOUR_PLAN_FILE.md ROADMAP.md +``` + +## General project notes + +- This is a Rust project. Use `cargo test --locked --all-targets` before handing off code changes when practical. +- Keep release notes user-facing and concise; avoid dumping raw commit logs. +- `dist/` contains generated release artifacts. Rebuild current-version files rather than editing archives by hand. diff --git a/ROADMAP.md b/ROADMAP.md index 34b05ac..a2f4809 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -1,5 +1,190 @@ # Cassady (Cass) Roadmap +## v0.2.4 — Windows CLI Usability + +This release focuses on making Cassady feel reliable and native when the CLI is run on Windows. It covers runtime usability after `cass` or `cassady` is already available on the machine; installers, package managers, PATH setup, code signing, and update delivery are intentionally out of scope. + +### Terminal Experience + +- [ ] **Make interactive rendering robust in Windows terminals.** Ensure chat, setup, confirmation prompts, streamed output, spinners, diffs, and tool summaries render cleanly in Windows Terminal, PowerShell, Command Prompt, and common VS Code integrated terminals. + - Enable or gracefully detect ANSI/VT support instead of emitting broken escape sequences. + - Respect `NO_COLOR`, non-interactive output, redirected stdout/stderr, and narrow terminal widths. + - Avoid relying on glyphs, emoji, box drawing, or cursor control sequences that render poorly on default Windows fonts. + - Keep wrapping and cursor positioning correct for multi-line input, Markdown output, and long tool-call summaries. + +- [ ] **Harden keyboard handling on Windows.** Make the TUI and prompts respond predictably to Windows console input events. + - Verify `Enter`, `Backspace`, `Delete`, arrow keys, `Home`, `End`, `PageUp`, `PageDown`, `Tab`, and paste behavior. + - Preserve existing `Ctrl-C` cancellation semantics and handle `Ctrl-Break`/console close events gracefully where supported. + - Ensure `Esc` cancellation and prompt dismissal work consistently across PowerShell, Command Prompt, and Windows Terminal. + +- [ ] **Improve plain CLI output for Windows users.** Commands such as `cass check`, setup diagnostics, validation errors, and usage text should remain readable without a fully interactive terminal. + - Prefer actionable Windows examples using PowerShell syntax when the current platform is Windows. + - Avoid POSIX-only command snippets in runtime guidance unless explicitly labeled. + - Keep error messages copy/paste-friendly and free of terminal control characters when output is redirected. + +### Windows Paths and Files + +- [ ] **Support Windows path syntax everywhere the CLI accepts paths.** Normalize and validate paths consistently across arguments, tool calls, diffs, session metadata, and model-visible file references. + - Handle drive-letter paths such as `C:\Users\name\project`, rooted paths such as `\temp`, UNC paths such as `\\server\share\repo`, and mixed `/`/`\` separators. + - Preserve user-facing paths in a readable Windows form while using canonicalized paths for safety decisions. + - Avoid treating `:` in drive letters as URL schemes or command separators. + - Add tests for relative path resolution from Windows workspaces and for paths containing spaces, apostrophes, parentheses, brackets, and non-ASCII characters. + +- [ ] **Respect Windows filesystem semantics in workspace policy.** Keep read, write, edit, and shell safety checks correct on NTFS and common Windows filesystems. + - Account for case-insensitive path comparisons, symlinks, junctions, directory symlinks, and network shares. + - Prevent workspace escapes through `..`, junctions, symlink targets, alternate path spellings, and UNC aliases. + - Handle reserved device names, trailing dots/spaces, invalid filename characters, and long-path edge cases with clear errors. + - Preserve current access modes (`read-only`, `workspace-edit`, `full-access`) with Windows-specific authorization tests. + +- [ ] **Handle line endings and encodings cleanly.** Make file reads, edits, diffs, and generated files predictable on Windows projects. + - Preserve existing CRLF/LF style when editing files where practical. + - Render diffs clearly even when files use CRLF line endings. + - Avoid corrupting UTF-8 with BOM, UTF-16, or non-UTF-8 files; detect unsupported text encodings and explain the limitation. + - Keep binary-file detection reliable for Windows executables, images, archives, and generated build artifacts. + +### Shell and Process Integration + +- [ ] **Use the right shell behavior on Windows.** Make `shell` tool execution, approval prompts, command summaries, cancellation, and exit status reporting work with Windows process semantics. + - Prefer PowerShell-friendly examples and diagnostics while still supporting `cmd.exe`-style commands when users provide them. + - Quote paths with spaces safely and avoid POSIX-only escaping in Windows-generated commands. + - Surface the actual executable, working directory, exit code, stdout, and stderr in a way users can debug. + - Cancel long-running child processes cleanly, including process trees where possible. + +- [ ] **Normalize environment-variable handling.** Ensure provider API key checks, diagnostics, setup guidance, and spawned tools work with Windows environment conventions. + - Treat environment variable names consistently despite Windows case-insensitive lookup behavior. + - Show PowerShell examples such as `$env:OPENAI_API_KEY = "..."` for temporary values. + - Avoid relying on POSIX shell expansion, `export`, `$VAR`, or `~` in Windows-specific guidance. + +- [ ] **Support common Windows external commands and editors.** When Cassady suggests or launches helper commands, make the behavior compatible with typical Windows environments. + - Detect missing tools and explain alternatives rather than assuming Unix utilities are present. + - Avoid hard dependencies on `sh`, `bash`, `grep`, `sed`, `cat`, `less`, or `/tmp` during normal CLI operation. + - Respect configured editor/browser commands and quote file paths correctly when opening files or URLs. + +### Config, State, and Session Usability + +- [ ] **Use Windows-appropriate runtime locations.** Keep config, logs, caches, sessions, temporary files, and diagnostics in locations that align with Windows conventions. + - Prefer the existing cross-platform directory abstraction where available, and verify behavior with `APPDATA`, `LOCALAPPDATA`, `TEMP`, and `USERPROFILE`. + - Expand `~` and environment-derived paths consistently in config values. + - Keep session history portable enough to display Windows paths without breaking transcript replay. + +- [ ] **Make diagnostics expose Windows-specific context.** Improve `cass check` and error reports so Windows users can understand terminal, filesystem, shell, and config problems quickly. + - Include OS, architecture, terminal detection, active shell, config path, workspace path, and access mode when relevant. + - Clearly distinguish provider/API-key failures from Windows runtime issues. + - Recommend Windows-native remediation steps without mentioning installation tasks. + +- [ ] **Keep aliases and command parsing consistent.** Ensure `cass` and `cassady` subcommands, flags, config overrides, and path arguments behave the same on Windows as on Unix-like systems. + - Validate quoting behavior for arguments containing spaces and backslashes. + - Ensure help text and examples do not imply shell features unavailable in PowerShell or Command Prompt. + - Keep machine-readable output stable across platforms when output is consumed by scripts. + +### Verification and Documentation + +- [ ] **Add Windows-focused automated coverage.** Add unit and integration tests that exercise Windows path parsing, policy checks, config discovery, line endings, environment variables, and command rendering. + - Use platform-gated tests for behavior that can only run on Windows. + - Add platform-independent tests for Windows path strings where possible. + - Include regression tests for spaces in paths, UNC paths, CRLF edits, and workspace escape attempts. + +- [ ] **Run a manual Windows CLI acceptance pass.** Validate the release on a real Windows environment, not just cross-compilation. + - Test PowerShell, Command Prompt, Windows Terminal, and VS Code integrated terminal. + - Exercise interactive chat, first-run setup, `cass check`, tool approvals, file read/edit/diff, shell cancellation, and redirected output. + - Record any unsupported terminal or shell behavior as explicit known limitations. + +- [ ] **Update runtime documentation for Windows usage.** Refresh README and bundled docs with Windows-specific CLI usage guidance while avoiding installation instructions. + - Document PowerShell environment-variable examples, path examples, terminal expectations, and known limitations. + - Include troubleshooting for broken colors, bad wrapping, path authorization failures, CRLF diffs, and missing Unix helper commands. + - Keep all Windows guidance consistent with existing access modes and safety policies. + +## 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. + +### 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. + - 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. + - 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. + - 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. + - Cancelling a turn, recovering after cancellation, and exiting cleanly. + +### Reference Documentation + +- [ ] **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. + - 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. + - 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. + - 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. + - Add examples of denied operations and the exact kind of message a user should expect. + +### Usage Guides and Troubleshooting + +- [ ] **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. + - 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. + - 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. + - 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. + - 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. + - 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. + - 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. + - Complete the release only when README and bundled docs accurately reflect the shipped CLI. + ## v0.2.2 — First-Run Onboarding and Setup Wizard ✅ Completed This release focuses on making Cassady easy to start using from a fresh install. See `plans/V0_2_2_ONBOARDING_SETUP_WIZARD_PLAN.md`.