From 93887f0d68ff73be48b3f97df73894bf26fed486 Mon Sep 17 00:00:00 2001
From: Flo <g-gitlab@zeidler.ms>
Date: Tue, 31 Mar 2026 00:18:21 +0200
Subject: [PATCH] docs: update README for v0.1.0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add safety review gate description, OSINT signing key advisory,
test running instructions, per-org signing key recommendation,
and fix placeholder URL in quick start.

Closes: #14

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 22 ++++++++++++++++++++--
 1 file changed, 20 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index e4d27de..4033e8f 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,9 @@ Protects against history rewriting, supply chain attacks, credential theft, and
 ## Quick Start
 
 ```bash
-# Download and run
-curl -O https://raw.githubusercontent.com/<you>/git-hardening/main/git-harden.sh
+# Clone and run
+git clone https://github.com/YOUR_ORG/git-hardening.git
+cd git-hardening
 chmod +x git-harden.sh
 
 # Audit your current config (no changes)
@@ -21,6 +22,8 @@ chmod +x git-harden.sh
 ./git-harden.sh -y
 ```
 
+On first interactive run, the script asks you to confirm you've reviewed it for safety. If you haven't, it prints instructions for piping it to Claude Code or Gemini CLI for an automated review.
+
 ## What It Does
 
 The script runs in two phases:
@@ -63,6 +66,8 @@ The script includes an interactive wizard that:
 
 With `-y`, the script auto-detects the best available key. If no key exists, signing config is prepared but not enabled (to avoid breaking commits).
 
+**Privacy note:** The signing wizard warns that reusing the same signing key across personal and work accounts enables cross-platform identity correlation (OSINT risk). For identity separation, generate dedicated keys per context and use git's `includeIf` for per-org config.
+
 ## Usage
 
 ```
@@ -122,6 +127,19 @@ The script prints (but does not apply) server/org-level recommendations:
 - Use fine-grained, short-lived tokens in CI/CD
 - Maintain an allowed signers file in repos
 - Clone untrusted repos with `--no-recurse-submodules`
+- Use separate signing keys per org to prevent cross-platform identity correlation (OSINT)
+
+## Running Tests
+
+```bash
+# Run the BATS test suite (64 tests)
+./test/run.sh
+
+# Requires bats-core submodules — init them if needed
+git submodule update --init --recursive
+```
+
+Tests run in an isolated `$HOME` (via `mktemp`) and never touch your real git or SSH config.
 
 ## License