feat: jq gating, platform-aware install hints, stage-1 docs (EGB-677 stage 1)

- jq required only when .secrets.json exists or is being written;
  manifest-less projects run jq-free (features skipped with a notice) —
  clone-and-run for v1 users survives (no-jq fixture excludes /usr/bin,
  macOS ships jq there now)
- check_cmd: platform-aware hints (brew/apt-get/dnf/generic) instead of
  hardcoded brew — correct guidance on Linux/CI
- cmd_help: add command, push flags, manifest section with example
- README: manifest section, external files rewritten around
  .secrets.json (legacy .secrets-files documented as absorbed),
  troubleshooting entries, command table, test instructions
- CLAUDE.md: manifest architecture notes, bash-3.2 '[[ ]] || false'
  testing convention, project structure refresh

CLAUDE.md

@@ -16,9 +16,14 @@ cd ~/my-project && ./secrets pull # Pull + decrypt .env* files
 
 ```bash
 brew install bats-core
-bats test/secrets.bats
+bats test/          # runs secrets.bats + manifest.bats
 ```
 
+**bash 3.2 assertion gotcha:** bats runs under system bash 3.2, where a
+failing `[[ ]]` mid-test does NOT fail the test (the ERR trap skips `[[`
+compound commands). Every standalone `[[ ... ]]` assertion MUST end with
+`|| false`. Single-bracket `[ ]` assertions are unaffected.
+
 ## Architecture
 
 Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rekey.
@@ -26,6 +31,7 @@ Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rek
 - Encryption: `age` with key files (not passphrases — age passphrases are non-scriptable)
 - Storage: Private git repo at `~/.secrets/`
 - Convention: Tracks `.env`, `.env.*`, and `.dev.vars` (not `.envrc`, `.environment-*`)
+- Manifest (EGB-677 stage 1): committed `.secrets.json` is the source of truth for what syncs — `dotenv[]` (project-relative, nested ok, `@` allowed; rail rejects `..`/absolute/symlink) + `external[]` (`properties`/`file`). Push discovery auto-adds (gated by committed `options.autoAdd`, default ON; `--frozen`/`--dry-run` overrides), bootstraps the manifest on first push (written only after ≥1 blob encrypts), and absorbs a legacy `.secrets-files` (gradle-properties → `properties`; on pull the legacy file is superseded with a warning). v1 store layout unchanged in stage 1: nested entries land at `<project>/<relpath>.age`; `properties` blobs keep the legacy `.gradle-properties.age` suffix until the stage-2 store migration. jq is a hard dep only when a manifest exists/is written; manifest-less projects run jq-free (manifest features skipped with a notice). `check_cmd` prints platform-aware install hints.
 - External files: `.secrets-files` manifest tracks designated keys from files outside the project (e.g. `~/.gradle/gradle.properties`, merged not overwritten — EGB-531) and whole binary files (type `file`, e.g. an Android upload keystore — EGB-652); see below
 - Workspaces: `--workspaces` flag reads `package.json` workspaces, requires `jq`
 - Safety: Pre-commit hook rejects plaintext secret files (`.env`, `.dev.vars`, `gradle.properties`)
@@ -34,10 +40,11 @@ Single bash script (`secrets`) with subcommands: init, push, pull, list, rm, rek
 ## Project Structure
 
 ```
-secrets              # CLI script (~600 lines bash)
+secrets              # CLI script (~2000 lines bash)
 hooks/pre-commit     # Pre-commit hook template
 test/
-  secrets.bats       # bats-core test suite (126 tests)
+  secrets.bats       # bats-core test suite (133 tests)
+  manifest.bats      # EGB-677 .secrets.json manifest tests (41 tests)
   test_helper.bash   # Shared setup/teardown
 README.md            # User-facing documentation
 CLAUDE.md            # This file