docs: add README, install, commands, and troubleshooting documentation

README.md: project overview, quick start, command table, install/uninstall summary. docs/install.md: prerequisites, install/uninstall procedures, install location, PATH behavior, status-line setup. docs/commands.md: all 9 commands with syntax, flags, examples, query resolution, env vars, exit codes. docs/troubleshooting.md: practical fixes for PATH, status line, doctor failures, delete protection, file locations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-06 17:44:25 -04:00
parent 44e3c38248
commit 401092f55a
4 changed files with 645 additions and 0 deletions
@@ -0,0 +1,104 @@
+# Install and Uninstall
+
+## Prerequisites
+
+- **Go 1.26+** -- install with `winget install GoLang.Go`
+- **just** (optional task runner) -- install with `winget install Casey.Just`
+
+## Local Install (Windows)
+
+Build from the local repo and install to `%LOCALAPPDATA%\ctask\bin`:
+
+```powershell
+cd C:\Users\Warren\claude_tasks\ctask_v0.1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/install.ps1
+```
+
+Or with just:
+
+```powershell
+just install
+```
+
+### What gets installed
+
+| File | Location |
+|------|----------|
+| ctask.exe | `%LOCALAPPDATA%\ctask\bin\ctask.exe` |
+| ctask-statusline.sh | `%LOCALAPPDATA%\ctask\bin\ctask-statusline.sh` |
+| ctask-statusline.ps1 | `%LOCALAPPDATA%\ctask\bin\ctask-statusline.ps1` |
+
+The install script:
+- Builds `ctask.exe` from the local repo
+- Copies the binary and status-line helpers to the install directory
+- Adds `%LOCALAPPDATA%\ctask\bin` to the user PATH if not already present
+- Creates a `.ctask-path-added` marker to track PATH ownership
+
+**Open a new terminal** after install for PATH changes to take effect.
+
+### Verify
+
+```powershell
+ctask --version
+ctask doctor
+```
+
+## Dev Build (no install)
+
+```powershell
+cd C:\Users\Warren\claude_tasks\ctask_v0.1
+go build -o ctask.exe .
+```
+
+Or: `just build`
+
+This produces a local `ctask.exe` in the repo directory without installing it.
+
+## Status Line Setup
+
+After install, configure Claude Code to show ctask session context. Add to `~/.claude/settings.json`:
+
+```json
+{
+  "statusLine": {
+    "type": "command",
+    "command": "bash /c/Users/<you>/AppData/Local/ctask/bin/ctask-statusline.sh"
+  }
+}
+```
+
+Replace `<you>` with your Windows username. Run `ctask doctor` to get the exact path for your system.
+
+## Uninstall
+
+```powershell
+cd C:\Users\Warren\claude_tasks\ctask_v0.1
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts/uninstall.ps1
+```
+
+Or: `just uninstall`
+
+### What uninstall removes
+
+- `ctask.exe`, `ctask-statusline.sh`, `ctask-statusline.ps1` from the install directory
+- The PATH entry, **only if** the install script originally added it (tracked by `.ctask-path-added` marker)
+- The empty install directory after files are removed
+
+### What uninstall does NOT remove
+
+- Your workspace data (`%USERPROFILE%\ai-workspaces` or wherever `CTASK_ROOT` points)
+- Task folders, notes, session logs, or any workspace contents
+- The Claude Code `statusLine` configuration in `~/.claude/settings.json`
+- PATH entries that were added manually (not by the install script)
+
+## Remote / Public Install
+
+Not available. This project is not published to any package registry, GitHub release, or remote Go module. Build and install locally from the repo.
+
+## Running Tests
+
+```powershell
+go test ./... -v -count=1
+```
+
+Or: `just test`