docs: define v0.1 product and architecture contract

docs/adr/0001-version-the-json-contract.md

@@ -0,0 +1,16 @@
+---
+status: accepted
+---
+
+# Version the JSON contract by compatibility boundary
+
+Automation agents are the primary interface consumers, so success and error
+shapes must remain predictable across upgrades. The project publishes reviewed
+JSON Schema files under `schemas/v1/`: optional fields may be added within v1
+and consumers must ignore unknown fields, while removing a field or changing
+its type or meaning requires a new major schema version. The CLI initially
+emits only its current schema rather than carrying multiple encoders; golden
+fixtures and schema validation gate every success and error change. JSON mode
+also preserves strict stream framing: a success is the only stdout document, a
+failure is the only stderr document, and progress or diagnostic logs never
+share either stream.

docs/adr/0002-keep-exit-statuses-coarse.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Keep exit statuses coarse
+
+Shell callers need broad control-flow signals, while automation agents need
+precise diagnoses. The CLI therefore reserves exit statuses for success,
+invalid invocation, runtime failure, timeout, and interruption; the versioned
+JSON `error.code` carries the detailed failure taxonomy. This avoids maintaining
+two overlapping error classifications that could drift apart.

docs/adr/0003-default-to-json-everywhere.md

@@ -0,0 +1,13 @@
+---
+status: accepted
+---
+
+# Default to JSON everywhere
+
+Automation agents are the primary consumers, so the shortest invocation must
+produce the stable machine interface. The CLI defaults to JSON regardless of
+whether stdout is a terminal or pipe; human-readable presentation requires
+`--format human`. Avoiding TTY-dependent format selection ensures that the same
+command has the same framing and semantics in every execution environment.
+JSON mode never emits interactive prompts; required confirmation is represented
+as a structured error and satisfied by an explicit flag.

docs/adr/0004-never-reuse-partial-analysis.md

@@ -0,0 +1,11 @@
+---
+status: accepted
+---
+
+# Never reuse a partial Analysis
+
+Ghidra preserves analyzer results completed before its analysis timeout, but
+automation consumers cannot safely infer which facts are missing. New Analyses
+are therefore built in staging and promoted atomically only after full success;
+a timeout, interruption, or analysis failure preserves the Diagnostic Log,
+removes the partial staging project, and leaves no reusable Analysis.

docs/adr/0005-analyze-a-staged-sample-snapshot.md

@@ -0,0 +1,13 @@
+---
+status: accepted
+---
+
+# Analyze a staged Sample snapshot
+
+Passing the caller's path to Ghidra after hashing creates a race in which the
+bytes analyzed may differ from the recorded Sample identity. The CLI instead
+copies the input through a read-only handle into private staging while hashing,
+verifies that source metadata did not change during the copy, and gives only
+that snapshot to Ghidra. The extra temporary I/O and disk use buy reproducible
+identity, isolate Java from the caller's path, and allow the snapshot to be
+removed after either success or failure.

docs/adr/0006-sandbox-the-ghidra-worker.md

@@ -0,0 +1,14 @@
+---
+status: accepted
+---
+
+# Sandbox the Ghidra worker
+
+Ghidra parses adversarial Samples through a large Java analysis engine, while
+the Rust harness must manage trusted locks, store data, and atomic promotion.
+The harness therefore remains outside a narrow sandbox containing only the
+Ghidra/JVM worker and its invocation capabilities. Bubblewrap is the default
+Linux backend, with explicit external-harness and disabled modes for
+environments that cannot nest it. This limits a compromised worker's access
+without turning the CLI into a daemon or allowing arbitrary sandbox-runner
+commands.