Add CLAUDE.md project guide and worktree documentation

CLAUDE.md gives Claude Code instant context on architecture, commands, conventions, security-critical modules, and public API surface. docs/CLAUDE_WORKTREES.md is a beginner-friendly guide to using Claude Code with git worktrees for isolated feature work. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-22 20:45:09 -05:00
parent 1630d044aa
commit 7aeb26e003
2 changed files with 334 additions and 0 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,110 @@
+# Stegasoo — Claude Code Project Guide
+
+Stegasoo is a secure steganography toolkit with hybrid photo + passphrase + PIN authentication.
+Version 4.2.1 · Python >=3.11 · MIT License
+
+## Quick commands
+
+```bash
+pip install -e ".[dev]"                     # Install for development (includes all extras)
+pytest                                       # Run tests (coverage reported automatically)
+black src/ tests/ frontends/                 # Format code
+ruff check src/ tests/ frontends/ --fix      # Lint (auto-fix)
+mypy src/                                    # Type check
+pre-commit run --all-files                   # Run all pre-commit hooks
+PYTHONPATH=src python -m stegasoo.cli        # Run CLI directly without install
+```
+
+## Architecture
+
+```
+src/stegasoo/          Core library
+  crypto.py              Argon2id / PBKDF2 key derivation + AES-256-GCM encryption
+  steganography.py       LSB spatial embedding
+  dct_steganography.py   DCT domain embedding (JPEG-safe, needs [dct] extras)
+  validation.py          Input validation for all security factors
+  constants.py           All magic numbers, crypto params, limits
+  models.py              Dataclasses (EncodeResult, DecodeResult, etc.)
+  encode.py / decode.py  High-level encode/decode orchestration
+  channel.py             Channel key management (v4.0+)
+  compression.py         Zstandard / zlib / lz4 payload compression
+  cli.py                 Click CLI entry point
+  generate.py            Credential generation (passphrase, PIN, RSA keys)
+  exceptions.py          Exception hierarchy (all inherit StegasooError)
+  __init__.py            Public API surface (__all__)
+
+frontends/web/         Flask web UI  (entry: app.py)
+frontends/api/         FastAPI REST API  (entry: main.py)
+frontends/cli/         CLI extras
+
+tests/                 Pytest suite
+  test_stegasoo.py       Single test file covering core library
+```
+
+### Entry points
+
+| Interface | Entry point | Install extra |
+|-----------|-------------|---------------|
+| CLI | `stegasoo.cli:main` (`stegasoo` command) | `[cli]` |
+| Web UI | `frontends/web/app.py` | `[web]` |
+| REST API | `frontends/api/main.py` | `[api]` |
+
+## Code conventions
+
+- **Formatter**: Black, 100-char line length
+- **Linter**: Ruff — rules E, F, I, N, W, UP (E501 ignored). N803/N806 suppressed in `dct_steganography.py` for colorspace variable names
+- **Type hints**: Required on all new code. `mypy` with `ignore_missing_imports = true`
+- **Pre-commit hooks**: ruff, ruff-format, trailing-whitespace, end-of-file-fixer, check-yaml, check-toml, check-added-large-files (1MB), check-merge-conflict, debug-statements, bandit (excludes tests/)
+- **Branch naming**: `feature/`, `fix/`, `docs/`, `refactor/`
+- **Commits**: Imperative mood, clear subject line. Include what + why
+
+## Security-critical modules
+
+These files implement the cryptographic and steganographic core. Changes require extra care, thorough test coverage, and careful review:
+
+- **`crypto.py`** — Argon2id KDF (256 MB / 4 iterations / 4 parallelism) + PBKDF2 fallback (600K iterations) → AES-256-GCM authenticated encryption
+- **`steganography.py`** — LSB spatial embedding/extraction
+- **`dct_steganography.py`** — DCT domain embedding with Reed-Solomon error correction
+- **`validation.py`** — Input validation for all security factors (PIN, passphrase, image, RSA key, channel key)
+- **`constants.py`** — Crypto parameters (salt sizes, iteration counts, Argon2 memory cost, format versions). Do not change these casually — they affect backward compatibility and security margins
+
+## Public API
+
+`src/stegasoo/__init__.py` defines the full public API surface via `__all__`. Any new public function must be:
+1. Imported in `__init__.py`
+2. Added to the `__all__` list
+
+## Testing
+
+- Single test file: `tests/test_stegasoo.py`
+- Requires `pip install -e ".[dev]"` (includes DCT dependencies)
+- Coverage is reported automatically via pytest config (`--cov=stegasoo --cov-report=term-missing`)
+- Run: `pytest` (no extra flags needed)
+
+## Worktree workflow
+
+When working on features or fixes that touch multiple files, prefer using a git worktree for isolation:
+
+```bash
+# Claude Code can create worktrees automatically via /worktree or EnterWorktree
+# Manual creation:
+git worktree add .claude/worktrees/<name> -b <branch-name>
+```
+
+### Guidelines for worktree usage
+
+- **Use worktrees for**: multi-file refactors, experimental changes, anything that might need to be discarded
+- **Worktree location**: `.claude/worktrees/` (gitignored by Claude Code)
+- **Branch from**: always branch from `main` unless working on a version branch (e.g., `4.2`)
+- **Naming**: use the same conventions as branches — `feature/description`, `fix/description`, etc.
+- **Cleanup**: worktrees in `.claude/worktrees/` are ephemeral. Remove with `git worktree remove <path>` when done
+- **Testing in worktrees**: run `pip install -e ".[dev]"` inside the worktree before running tests, since the editable install points to the worktree's source
+- **Merging back**: create a PR from the worktree branch, or merge locally into `main`
+
+## Useful context
+
+- BIP-39 wordlist lives at `src/stegasoo/data/bip39-words.txt` (used for passphrase generation)
+- Docker support: `src/stegasoo/Dockerfile` + `docs/DOCKER_QUICKSTART.md`
+- Raspberry Pi builds: `rpi/` directory
+- AUR packages: `aur/`, `aur-cli/`, `aur-api/`
+- Version is defined in both `pyproject.toml` and `src/stegasoo/__init__.py` — keep them in sync