fix: resolve acceptance test findings (#9)

## Summary

- Fix `.gitignore` crash on read-only repos with external `--output-dir`
- Add symlink `.gitignore` guard
- Fix version-pinned curl URLs (v1.0.0 → main)
- Add SHA256 checksum to README manual install
- Use `$RUNNER_TEMP` in release workflow
- Add sudo warning to install.sh
- README: TOC, uninstall section, agent/CI docs, colour env vars,
install.sh env vars
- Agent example in `--help` output
- 3 new bats tests
- Bump to v1.0.2

## Test plan

- [x] shellcheck clean
- [x] shfmt clean
- [x] 231/231 bats tests pass

---------

Signed-off-by: K1-R1 <77465250+K1-R1@users.noreply.github.com>

Author: K1-R1

.github/workflows/release.yml

@@ -123,14 +123,14 @@ jobs:
           tarball_url="https://github.com/K1-R1/smoosh/archive/refs/tags/${TAG_NAME}.tar.gz"
 
           # Compute SHA256 from the release tarball.
-          curl -fsSL "${tarball_url}" -o /tmp/smoosh-src.tar.gz
-          sha256="$(sha256sum /tmp/smoosh-src.tar.gz | awk '{print $1}')"
+          curl -fsSL "${tarball_url}" -o "$RUNNER_TEMP/smoosh-src.tar.gz"
+          sha256="$(sha256sum "$RUNNER_TEMP/smoosh-src.tar.gz" | awk '{print $1}')"
 
           # Clone, patch, push.
           git clone \
             "https://x-access-token:${COMMITTER_TOKEN}@github.com/K1-R1/homebrew-tap.git" \
-            /tmp/homebrew-tap
-          cd /tmp/homebrew-tap
+            "$RUNNER_TEMP/homebrew-tap"
+          cd "$RUNNER_TEMP/homebrew-tap"
           git config user.email "github-actions[bot]@users.noreply.github.com"
           git config user.name "github-actions[bot]"
 

CHANGELOG.md

@@ -7,6 +7,45 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+## [1.0.2] - 2026-03-17
+
+### Fixed
+
+- `.gitignore` auto-update no longer crashes on read-only repos when
+  `--output-dir` points outside the repository root. The `.gitignore` write
+  is now skipped (with a warning) since an external absolute path in
+  `.gitignore` would be meaningless anyway.
+- README and `install.sh` header comment no longer pin curl install URLs to
+  `v1.0.0` — now reference `main` branch so users always get the latest
+  install script.
+
+### Security
+
+- `.gitignore` auto-update skips symlinks with a warning, preventing the
+  `cp` + `mv` pattern from overwriting the symlink target.
+- `install.sh` now warns before falling back to `sudo` for installation,
+  making privilege escalation visible in `curl | bash` contexts.
+- README manual install instructions now include SHA256 checksum
+  verification step.
+- Release workflow uses `$RUNNER_TEMP` instead of world-readable `/tmp` for
+  intermediate files.
+
+### Added
+
+- Table of contents in README for quick navigation.
+- Uninstall section in README (Homebrew and manual paths, shadow binary
+  note).
+- Agent/CI usage section in README with JSON schema example, recommended
+  commands, and automation flags table.
+- `--no-color` flag documented in README configuration reference table.
+- Colour environment variable precedence documented (`--no-color` >
+  `NO_COLOR` > `FORCE_COLOR` > `CLICOLOR` > TTY auto-detect).
+- `install.sh` environment variables documented in README (`SMOOSH_VERSION`,
+  `SMOOSH_INSTALL_DIR`, `SMOOSH_NO_CONFIRM`, `SMOOSH_NO_VERIFY`).
+- Agent/CI example added to `--help` output.
+- 3 new bats tests: external `--output-dir` skips `.gitignore`, symlink
+  `.gitignore` is not followed, `--help` includes agent example.
+
 ## [1.0.1] - 2026-03-15
 
 ### Fixed
@@ -64,6 +103,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - Output path shown relative to repo root
 - Demo recordings: interactive mode flow and power-user flags
 
-[Unreleased]: https://github.com/K1-R1/smoosh/compare/v1.0.1...HEAD
+[Unreleased]: https://github.com/K1-R1/smoosh/compare/v1.0.2...HEAD
+[1.0.2]: https://github.com/K1-R1/smoosh/compare/v1.0.1...v1.0.2
 [1.0.1]: https://github.com/K1-R1/smoosh/compare/v1.0.0...v1.0.1
 [1.0.0]: https://github.com/K1-R1/smoosh/releases/tag/v1.0.0

README.md

@@ -16,6 +16,8 @@ ChatGPT, or your own RAG pipeline. Pure bash, zero dependencies.
 
 </div>
 
+**[Quick Start](#quick-start)** · **[Why smoosh?](#why-smoosh)** · **[Features](#features)** · **[Installation](#installation)** · **[Uninstall](#uninstall)** · **[Usage](#usage)** · **[AI Tools](#using-smoosh-with-ai-tools)** · **[Agent / CI](#agents-and-ci-pipelines)** · **[Config Reference](#configuration-reference)** · **[FAQ](#faq)**
+
 ## Quick Start
 
 ```bash
@@ -94,24 +96,48 @@ brew install K1-R1/tap/smoosh
 ### curl (macOS / Linux / Git Bash)
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/K1-R1/smoosh/v1.0.0/install.sh | bash
+curl -fsSL https://raw.githubusercontent.com/K1-R1/smoosh/main/install.sh | bash
 ```
 
 Installs to `/usr/local/bin`. Override with:
 
 ```bash
 SMOOSH_INSTALL_DIR="$HOME/.local/bin" \
-  curl -fsSL https://raw.githubusercontent.com/K1-R1/smoosh/v1.0.0/install.sh | bash
+  curl -fsSL https://raw.githubusercontent.com/K1-R1/smoosh/main/install.sh | bash
 ```
 
+The installer supports these environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `SMOOSH_INSTALL_DIR` | `/usr/local/bin` | Installation directory |
+| `SMOOSH_VERSION` | latest | Pin a specific version (e.g. `1.0.1`) |
+| `SMOOSH_NO_CONFIRM` | `0` | Set to `1` to skip confirmation prompt |
+| `SMOOSH_NO_VERIFY` | `0` | Set to `1` to skip checksum verification (unsafe) |
+
 ### Manual
 
 ```bash
 curl -fsSL https://github.com/K1-R1/smoosh/releases/latest/download/smoosh -o smoosh
+curl -fsSL https://github.com/K1-R1/smoosh/releases/latest/download/smoosh.sha256 -o smoosh.sha256
+sha256sum -c smoosh.sha256
 chmod +x smoosh
 sudo mv smoosh /usr/local/bin/
 ```
 
+### Uninstall
+
+```bash
+# Homebrew
+brew uninstall smoosh
+
+# curl / manual
+rm "$(which smoosh)"
+```
+
+If you installed via both methods, check `which smoosh` after removing one — a
+second copy may remain in a different location.
+
 ## Usage
 
 ### Basics
@@ -242,6 +268,49 @@ grounded in your actual code.
 
 Works with any ChatGPT plan that supports file uploads.
 
+### Agents and CI pipelines
+
+smoosh is designed to be called by AI agents and CI pipelines, not just humans.
+
+**Pre-flight check** — estimate size before generating output:
+
+```bash
+smoosh --json --dry-run --all .
+```
+
+```json
+{
+  "dry_run": true,
+  "repo": "my-project",
+  "files": [
+    {"path": "README.md", "words": 194, "chunk": 1},
+    {"path": "src/main.py", "words": 312, "chunk": 1}
+  ],
+  "total_words": 506,
+  "estimated_tokens": 658,
+  "estimated_chunks": 1
+}
+```
+
+**Generate output:**
+
+```bash
+smoosh --no-interactive --json --all .
+```
+
+**Key flags for automation:**
+
+| Flag | Purpose |
+| --- | --- |
+| `--no-interactive` | Skip TTY detection and prompts |
+| `--json` | Structured JSON to stdout (status messages go to stderr) |
+| `--quiet` | Output file paths only, one per line |
+| `--dry-run` | Preview without writing files |
+| `--no-color` | Disable colour escape codes |
+
+Exit codes 0–7 are differentiated for programmatic decision-making — see
+[Configuration Reference](#configuration-reference) below.
+
 ## Configuration Reference
 
 | Flag | Default | Description |
@@ -262,10 +331,14 @@ Works with any ChatGPT plan that supports file uploads.
 | `--quiet` | — | Print output paths only (stdout) |
 | `--json` | — | Structured JSON to stdout |
 | `--no-interactive` | — | Skip interactive mode even in a TTY |
+| `--no-color` | — | Disable colour output |
 | `--no-check-secrets` | — | Skip the basic secrets scan |
 | `--version` | — | Print version and exit 0 |
 | `--help` | — | Print full usage and exit 0 |
 
+**Colour control:** `--no-color` flag > `NO_COLOR` env var > `FORCE_COLOR` >
+`CLICOLOR` > TTY auto-detect. See [no-color.org](https://no-color.org/).
+
 **Exit codes:**
 
 | Code | Meaning |