modified README

README.md

@@ -1,31 +1,81 @@
-# pyhdwallet v1.0.4
+# pyhdwallet v1.0.5
 
-A secure, offline command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin.
+A secure, offline-first command-line tool for generating and recovering BIP39 HD wallets with support for Ethereum, Solana, and Bitcoin. It supports optional PGP-encrypted payloads (ASCII-armored `.asc`) and deterministic AES-encrypted ZIP wallet artifacts written under a local `.wallet/` folder.
 
 ## Purpose
 
-pyhdwallet helps you create new wallets or recover from existing mnemonics/seeds, with built-in PGP encryption for secure storage. It's designed for privacy-conscious users who want offline, auditable wallet management.
+pyhdwallet helps create new wallets or recover from existing mnemonics/seeds with offline operation, auditable derivation, and optional encryption for safer storage. PGP encryption produces an ASCII-armored PGP message suitable for saving as `.asc`.[3]
+
+## Repository layout
+
+- `src/pyhdwallet.py` — main CLI script
+- `.wallet/` — generated wallet artifacts (recommend adding to `.gitignore`)
+- `requirements.in`, `requirements.txt`
+- `README.md`, `playbook.md`, `LICENSE`
 
 ## Installation
 
 1. Ensure Python 3.11+ is installed.
-2. Clone/download the repo.
-3. Create a virtual environment: `python -m venv .venv && source .venv/bin/activate`
-4. Install dependencies: `pip install -r requirements.txt`
+1. Clone/download the repo.
+1. Create and activate a virtual environment:
 
-## Basic Usage
+```bash
+python -m venv .venv
+source .venv/bin/activate
+```
 
-Run the tool with a subcommand. For help, use `-h`.
+1. Install dependencies:
 
-- Generate a wallet: `python ./src/pyhdwallet.py gen --chains ethereum --addresses 3`
-- Recover from mnemonic: `python ./src/pyhdwallet.py recover --mnemonic "your words" --chains bitcoin`
-- Fetch PGP key: `python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc"`
-- Run tests: `python ./src/pyhdwallet.py test`
+```bash
+python -m pip install -r requirements.txt
+```
 
-For detailed examples and security tips, see `playbook.md`.
+## Basic usage
+
+Run the tool with a subcommand. For help, use `-h` (e.g., `gen -h`, `recover -h`).
+
+```bash
+# Generate (prints mnemonic by default; intended for debug/test)
+python ./src/pyhdwallet.py gen
+
+# Generate and save an AES-encrypted ZIP artifact into ./.wallet (password prompted)
+python ./src/pyhdwallet.py gen --file
+
+# Generate with PGP encryption + ZIP artifact (ZIP contains only encrypted .asc payload)
+python ./src/pyhdwallet.py gen --pgp-pubkey-file pubkeys/mykey.asc --file
+
+# Recover from mnemonic (prefer --interactive to avoid shell history)
+python ./src/pyhdwallet.py recover --interactive
+
+# Recover and save AES ZIP artifact
+python ./src/pyhdwallet.py recover --interactive --file
+
+# Fetch PGP public key (online)
+python ./src/pyhdwallet.py fetchkey "https://example.com/key.asc" --out mykey.asc
+
+# Run tests
+python ./src/pyhdwallet.py test
+```
+
+## Notes on `--file`, AES ZIP, and PGP
+
+- `--file` writes **only** an AES-encrypted ZIP (no raw `.json`/`.asc` is left on disk), using `pyzipper`.[4]
+- If `--pgp-pubkey-file` is set, the ZIP contains a single ASCII-armored PGP message (`.asc`) created with PGPy-style `PGPMessage.new(...)` then `pubkey.encrypt(...)`.[3]
+
+## About `--force`
+
+The tool includes a safety guard: if stdout is piped/redirected (non-TTY), it refuses to print sensitive output unless `--force` is set. Checking whether stdout is a terminal is commonly done via `isatty()`.
+
+Example:
+
+```bash
+python ./src/pyhdwallet.py gen > out.txt          # likely refused (non-TTY)
+python ./src/pyhdwallet.py gen --force > out.txt  # forced (dangerous)
+```
 
 ## Security
 
-- Operates offline by default.
-- Use `--off-screen` for high-security operations.
-- Always verify PGP keys and run on trusted systems.
+- Designed to run offline; `gen`, `recover`, and `test` block network access in-process.
+- Use `--off-screen` to suppress printing sensitive data to stdout.
+- Prefer `--file` (AES ZIP) and optionally combine with `--pgp-pubkey-file` for stronger at-rest security.
+- For detailed examples and operational guidance, see `playbook.md`.