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

test/manifest.bats

@@ -462,3 +462,48 @@ m_file_src()   { mkdir -p "$HOME/keystores"; printf 'KS\x00\x01\x02\xffDATA\n' >
   [ -f packages/api/.dev.vars ]
   [ "$(cat packages/api/.dev.vars)" = "API=1" ]
 }
+
+# ─── E: jq gating + install hints + help ───────────────────────────────
+
+# Helper: PATH with age but without jq. macOS ships /usr/bin/jq, so
+# /usr/bin must be excluded too — needed tools are symlinked explicitly.
+m_nojq_path() {
+  local fake="$TEST_TMPDIR/nojq-bin"
+  mkdir -p "$fake"
+  local t
+  for t in age age-keygen git basename dirname mktemp grep sed tr cut cksum stat head tail sort uniq wc env touch find diff cmp; do
+    command -v "$t" >/dev/null 2>&1 && ln -sf "$(command -v "$t")" "$fake/$t"
+  done
+  rm -f "$fake/jq"
+  echo "$fake:/bin"
+}
+
+@test "manifest-less push works without jq (manifest features skipped)" {
+  init_with_remote
+  create_project_dir nojqproj
+  local p; p=$(m_nojq_path)
+  run env PATH="$p" "$SECRETS_BIN" push
+  [ "$status" -eq 0 ]
+  [ -f "$SECRETS_DIR/nojqproj/.env.age" ]
+  [ ! -f ".secrets.json" ]
+  [[ "$output" == *"jq"* ]] || false
+}
+
+@test "push dies with an install hint when a manifest exists but jq is missing" {
+  init_with_remote
+  create_project_dir needjq
+  printf '{"version":2,"dotenv":[".env"]}\n' > .secrets.json
+  local p; p=$(m_nojq_path)
+  run env PATH="$p" "$SECRETS_BIN" push
+  [ "$status" -eq 1 ]
+  [[ "$output" == *"'jq' is not installed"* ]] || false
+}
+
+@test "help documents add, --frozen, --dry-run and the manifest" {
+  run "$SECRETS_BIN" help
+  [ "$status" -eq 0 ]
+  [[ "$output" == *"secrets add"* ]] || false
+  [[ "$output" == *"--frozen"* ]] || false
+  [[ "$output" == *"--dry-run"* ]] || false
+  [[ "$output" == *".secrets.json"* ]] || false
+}