docs(12-01): complete CLI key input plan

- SUMMARY.md with execution results and decisions
- STATE.md updated with position, metrics, decisions
- ROADMAP.md updated with phase 12 progress
- REQUIREMENTS.md: KEY-01, KEY-02, KEY-07 marked complete

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.planning/phases/12-user-key-input/12-01-SUMMARY.md

@@ -0,0 +1,127 @@
+---
+phase: 12-user-key-input
+plan: 01
+subsystem: crypto
+tags: [clap, hex, aes-256, key-management, cli]
+
+# Dependency graph
+requires:
+  - phase: 08-rust-directory-archiver
+    provides: "pack/unpack/inspect with hardcoded key"
+provides:
+  - "CLI --key (hex) and --key-file (raw) key input for pack/unpack"
+  - "inspect works without key (header only) or with key (full TOC listing)"
+  - "KeySource enum and resolve_key() in key.rs"
+  - "All archive functions parameterized by user-provided key"
+affects: [12-02-PLAN, kotlin-decoder]
+
+# Tech tracking
+tech-stack:
+  added: [hex 0.4]
+  patterns: [key-parameterized archive API, clap arg group for mutually exclusive key sources]
+
+key-files:
+  created: []
+  modified:
+    - Cargo.toml
+    - src/cli.rs
+    - src/key.rs
+    - src/archive.rs
+    - src/main.rs
+    - src/crypto.rs
+    - tests/round_trip.rs
+    - tests/golden.rs
+
+key-decisions:
+  - "KeyArgs as top-level clap flatten (not per-subcommand) so --key goes before subcommand"
+  - "inspect accepts optional key: without key shows header only, with key shows full TOC"
+  - "LEGACY_KEY kept as #[cfg(test)] constant for golden vectors"
+  - "Password option uses Option<Option<String>> for future interactive prompt support"
+
+patterns-established:
+  - "Key threading: all archive functions accept explicit key parameter instead of global state"
+  - "cmd_with_key() test helper for CLI integration tests"
+
+requirements-completed: [KEY-01, KEY-02, KEY-07]
+
+# Metrics
+duration: 5min
+completed: 2026-02-26
+---
+
+# Phase 12 Plan 01: User Key Input Summary
+
+**CLI key input via --key (hex) and --key-file (raw bytes), replacing hardcoded constant, with inspect working keyless for header metadata**
+
+## Performance
+
+- **Duration:** 5 min
+- **Started:** 2026-02-26T20:47:52Z
+- **Completed:** 2026-02-26T20:53:36Z
+- **Tasks:** 2
+- **Files modified:** 8
+
+## Accomplishments
+- Removed hardcoded KEY constant from production code; all archive functions now parameterized by key
+- Added --key (64-char hex) and --key-file (32-byte raw file) as mutually exclusive CLI args
+- inspect works without a key (shows header metadata + "TOC is encrypted" message) and with a key (full entry listing)
+- All 47 tests pass: 25 unit + 7 golden + 15 integration (6 new tests added)
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Add CLI key args and refactor key.rs + archive.rs signatures** - `acff31b` (feat)
+2. **Task 2: Update tests and verify round-trip with explicit key** - `551e499` (test)
+
+## Files Created/Modified
+- `Cargo.toml` - Added hex 0.4 dependency
+- `src/cli.rs` - Added KeyArgs struct with --key, --key-file, --password as clap arg group
+- `src/key.rs` - Replaced hardcoded KEY with KeySource enum and resolve_key() function
+- `src/archive.rs` - Refactored pack/unpack/inspect to accept key parameter
+- `src/main.rs` - Wired CLI key args to key resolution and archive functions
+- `src/crypto.rs` - Updated tests to use local TEST_KEY constant
+- `tests/golden.rs` - Updated to use local KEY constant instead of imported
+- `tests/round_trip.rs` - All tests updated with --key, 6 new tests added
+
+## Decisions Made
+- KeyArgs placed at top-level Cli struct (not per-subcommand) so --key goes BEFORE the subcommand name
+- inspect accepts optional key: without key shows only header fields, with key decrypts and shows full TOC
+- LEGACY_KEY kept as #[cfg(test)] constant in key.rs for golden test vector compatibility
+- Password field uses `Option<Option<String>>` to support both `--password mypass` and `--password` (future interactive prompt)
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 1 - Bug] Fixed wrong-key test assertion**
+- **Found during:** Task 2 (test_rejects_wrong_key)
+- **Issue:** Wrong key causes TOC decryption failure ("invalid padding or wrong key") before HMAC check on individual files. The test expected "HMAC" or "verification" in stderr.
+- **Fix:** Broadened assertion to also accept "Decryption failed" or "wrong key" in error message
+- **Files modified:** tests/round_trip.rs
+- **Verification:** Test passes with actual error behavior
+- **Committed in:** 551e499 (Task 2 commit)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 bug fix in test)
+**Impact on plan:** Trivial test assertion fix. No scope creep.
+
+## Issues Encountered
+None
+
+## User Setup Required
+None - no external service configuration required.
+
+## Next Phase Readiness
+- Key input foundation complete for Plan 02 (Argon2 password-based key derivation)
+- --password CLI arg already accepted (returns "not yet implemented" error)
+- KeySource::Password variant ready for Plan 02 implementation
+
+## Self-Check: PASSED
+
+All 9 files verified present. Both task commits (acff31b, 551e499) found in git log.
+
+---
+*Phase: 12-user-key-input*
+*Completed: 2026-02-26*