pixelcola · pixelcola · May 12, 2026 · May 12, 2026 · May 12, 2026 · May 12, 2026
diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/check.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "Verify README install docs match CLI project facts"}
+{"file": ".trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md", "reason": "Verify README uses valid uv tool commands"}
diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/implement.jsonl
@@ -0,0 +1,2 @@
+{"file": ".trellis/spec/backend/index.md", "reason": "README install docs should stay aligned with CLI project facts"}
+{"file": ".trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md", "reason": "Official uv tool command verification for README install docs"}
diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/prd.md
@@ -0,0 +1,55 @@
+# docs: update README installation instructions
+
+## Goal
+
+Update `README.md` so users can install, update, and uninstall `sing-cli` with `uv tool`, and install runtime executables with Scoop.
+
+## What I already know
+
+* The user requested README documentation for:
+  * `uv tool install sing-cli`
+  * `uv tool upgrade sing-cli`
+  * `uv tool uninstall sing-cli`
+  * `scoop install sing-box nssm`
+* `README.md` currently documents runtime requirements and command usage, but not CLI installation.
+* The project exposes the CLI command through `pyproject.toml` as `sing = "sing_cli.main:main"`.
+
+## Assumptions
+
+* The README should keep the existing concise structure.
+* Scoop is documented as the recommended way to install `sing-box.exe` and `nssm.exe` on Windows.
+
+## Requirements
+
+* Add a README section for installing, updating, and uninstalling `sing-cli` with `uv tool`.
+* Add a README example showing `scoop install sing-box nssm` for runtime dependencies.
+* Preserve existing command behavior documentation.
+* Keep published docs free of editor notes, migration commentary, and one-off explanatory footnotes.
+
+## Acceptance Criteria
+
+* [x] `README.md` includes `uv tool install sing-cli`.
+* [x] `README.md` includes `uv tool upgrade sing-cli`.
+* [x] `README.md` includes `uv tool uninstall sing-cli`.
+* [x] `README.md` includes `scoop install sing-box nssm`.
+* [x] The README remains visually consistent with the existing concise style.
+
+## Definition of Done
+
+* Documentation updated.
+* Diff reviewed for scope.
+* No code tests are required because this is a README-only change.
+
+## Out of Scope
+
+* Changing CLI behavior.
+* Adding package publishing automation.
+* Adding installation logic to the CLI.
+
+## Technical Notes
+
+* Relevant files inspected:
+  * `README.md`
+  * `.trellis/spec/backend/index.md`
+  * `uv tool --help`
+  * `.trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md`
diff --git a/...tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md b/...tasks/archive/2026-05/05-12-readme-install-uv-tool/research/uv-tool-commands.md
@@ -0,0 +1,14 @@
+# uv tool commands
+
+## Finding
+
+`uv tool` installs tools with `uv tool install`, upgrades installed tools with `uv tool upgrade`, and removes tools with `uv tool uninstall`.
+
+## Sources
+
+* Official uv guide, "Using tools": https://docs.astral.sh/uv/guides/tools/
+* Official uv CLI reference: https://docs.astral.sh/uv/reference/cli/
+
+## Impact on README
+
+Use `uv tool upgrade sing-cli` for the update action. `uv tool update sing-cli` is not a documented `uv tool` command in the official uv CLI reference and is not present in local `uv tool --help`.
diff --git a/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json b/.trellis/tasks/archive/2026-05/05-12-readme-install-uv-tool/task.json
@@ -0,0 +1,26 @@
+{
+  "id": "readme-install-uv-tool",
+  "name": "readme-install-uv-tool",
+  "title": "docs: update README installation instructions",
+  "description": "",
+  "status": "completed",
+  "dev_type": null,
+  "scope": null,
+  "package": null,
+  "priority": "P2",
+  "creator": "pixelcola",
+  "assignee": "pixelcola",
+  "createdAt": "2026-05-12",
+  "completedAt": "2026-05-12",
+  "branch": null,
+  "base_branch": "docs/readme-install-uv-tool",
+  "worktree_path": null,
+  "commit": null,
+  "pr_url": null,
+  "subtasks": [],
+  "children": [],
+  "parent": null,
+  "relatedFiles": [],
+  "notes": "",
+  "meta": {}
+}
diff --git a/.trellis/workspace/pixelcola/index.md b/.trellis/workspace/pixelcola/index.md
@@ -8,7 +8,7 @@
 
 <!-- @@@auto:current-status -->
 - **Active File**: `journal-1.md`
-- **Total Sessions**: 5
+- **Total Sessions**: 6
 - **Last Active**: 2026-05-12
 <!-- @@@/auto:current-status -->
 
@@ -19,7 +19,7 @@
 <!-- @@@auto:active-documents -->
 | File | Lines | Status |
 |------|-------|--------|
-| `journal-1.md` | ~172 | Active |
+| `journal-1.md` | ~205 | Active |
 <!-- @@@/auto:active-documents -->
 
 ---
@@ -29,6 +29,7 @@
 <!-- @@@auto:session-history -->
 | # | Date | Title | Commits | Branch |
 |---|------|-------|---------|--------|
+| 6 | 2026-05-12 | Update README installation instructions | `49680f6` | `docs/readme-install-uv-tool` |
 | 5 | 2026-05-12 | Fix restart active profile | `010e59e` | `fix/restart-active-config` |
 | 4 | 2026-05-12 | Fix Windows subprocess output decoding | `e90a676` | `fix/windows-subprocess-output-decoding` |
 | 3 | 2026-05-12 | Use NSSM for Windows service | `72c1b0d` | `fix/use-nssm-service` |

diff --git a/.trellis/workspace/pixelcola/journal-1.md b/.trellis/workspace/pixelcola/journal-1.md
@@ -170,3 +170,36 @@ Changed sing restart to use the active profile without accepting a profile argum
 ### Next Steps
 
 - None - task complete
+
+
+## Session 6: Update README installation instructions
+
+**Date**: 2026-05-12
+**Task**: Update README installation instructions
+**Branch**: `docs/readme-install-uv-tool`
+
+### Summary
+
+Documented Scoop runtime dependency installation and uv tool install, upgrade, and uninstall commands for sing-cli.
+
+### Main Changes
+
+(Add details)
+
+### Git Commits
+
+| Hash | Message |
+|------|---------|
+| `49680f6` | (see git log) |
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
diff --git a/README.md b/README.md
@@ -6,6 +6,32 @@ Windows CLI for installing and controlling the `sing-box` Windows service.
 
 `sing-box.exe` and `nssm.exe` must be available in `PATH`. `sing install --bin <path>` can use a custom `sing-box.exe` path.
 
+On Windows, install the runtime executables with Scoop:
+
+```powershell
+scoop install sing-box nssm
+```
+
+## Installation
+
+Install `sing-cli`:
+
+```powershell
+uv tool install sing-cli
+```
+
+Update `sing-cli`:
+
+```powershell
+uv tool upgrade sing-cli
+```
+
+Uninstall `sing-cli`:
+
+```powershell
+uv tool uninstall sing-cli
+```
+
 ## Commands
 
 | Command | Description |
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		{"file": ".trellis/spec/backend/index.md", "reason": "Verify README install docs match CLI project facts"}
		{"file": ".trellis/tasks/05-12-readme-install-uv-tool/research/uv-tool-commands.md", "reason": "Verify README uses valid uv tool commands"}