KeyCode17 · KeyCode17 · May 18, 2026 · May 17, 2026
diff --git a/README.md b/README.md
@@ -2,27 +2,97 @@
 
 A Rust-built solver service for PerimeterX (HUMAN Security) protection. Given a target URL on a per-domain allowlist, returns a valid `_px3` cookie bundle that a downstream authorized client can use to issue requests as if from a real browser.
 
-> **Status:** Pre-MVP. Planning artifacts only. No Rust code yet.
+> **Status:** v1.2.0 published to crates.io as the `pxsolver-*` family of crates. MVP gate hit at v1.0.0; v1.1.0 added a Camoufox-backed Cloudflare bypass path; v1.2.0 renamed the published library crates. See [GitHub Releases](https://github.com/KeyCode17/px-solver/releases) for the per-version notes.
 
 ## What this is
 
-- A REST API service backed by a stealth-patched Chromium pool (`chromiumoxide` + manual CDP patches).
-- A **challenge pipeline** that routes each request to the correct vendor handler. v1 ships the **PerimeterX** handler; stubs exist for Cloudflare, Turnstile, hCaptcha/reCAPTCHA, and DataDome so they slot in cleanly in v2.
-- An API-key + per-domain allowlist + audit log layer that bounds dual-use abuse.
+- A REST API service backed by a stealth-patched Chromium pool (`chromiumoxide` + manual CDP patches) and, for Cloudflare-fronted targets, a Camoufox/geckodriver pool ([ADR-0020](docs/adr/0020-adopt-camoufox-via-fantoccini-geckodriver.md)).
+- A **challenge pipeline** that routes each request to the correct vendor handler. v1 ships the **PerimeterX** handler and a Camoufox-backed **Cloudflare** handler; stubs exist for Turnstile, hCaptcha/reCAPTCHA, and DataDome so they slot in cleanly in v2.
+- An API-key + per-domain allowlist + audit log layer that bounds dual-use abuse ([ADR-0007](docs/adr/0007-api-key-and-domain-allowlist-guardrails.md)).
 
 ## What this is **not**
 
 - **Not** a native PerimeterX sensor generator. v1 defeats PX by **avoidance** (real Chromium passes the challenge legitimately), not by **defeat** (rebuilding the sensor payload from scratch). The codebase is structured so a native solver can be added; the reverse-engineering work itself is out of v1 scope. See [ADR-0010](docs/adr/0010-defer-native-sensor-generator.md) and [ADR-0013](docs/adr/0013-re-methodology-and-scope.md).
 - **Not** an anonymous public solver. Every request requires an API key; every target requires an explicit allowlist entry with `tos_reviewed: true`. See [ADR-0007](docs/adr/0007-api-key-and-domain-allowlist-guardrails.md) and [`docs/011-sow-dual-use.md`](docs/011-sow-dual-use.md).
-- **Not** a Cloudflare / Turnstile / DataDome / captcha solver in v1. The pipeline routes to those handlers when their protections are detected, but their `solve()` methods return `NotImplemented` until v2. Many passive edge layers (Fastly, CloudFront, Cloudflare silent scoring, Turnstile invisible mode) are **incidentally** defeated by running real Chromium with stealth — but no success rate is committed for them. See [ADR-0014](docs/adr/0014-challenge-pipeline-architecture.md) and [ADR-0015](docs/adr/0015-v1-ships-pipeline-with-perimeterx-handler-only.md).
+- **Not** a Turnstile / DataDome / captcha solver in v1. The pipeline routes to those handlers when their protections are detected, but their `solve()` methods return `NotImplemented` until v2. Many passive edge layers (Fastly, CloudFront, Cloudflare silent scoring, Turnstile invisible mode) are **incidentally** defeated by running real Chromium or Camoufox with stealth — but no success rate is committed for them. See [ADR-0014](docs/adr/0014-challenge-pipeline-architecture.md) and [ADR-0015](docs/adr/0015-v1-ships-pipeline-with-perimeterx-handler-only.md).
+
+## Install
+
+From source:
+
+```bash
+git clone https://github.com/KeyCode17/px-solver
+cd px-solver
+cargo build --release
+```
+
+From crates.io:
+
+```bash
+cargo install pxsolver-server pxsolver-cli
+```
+
+The 16 `pxsolver-*` library crates are also published individually for downstream Rust users; in source the workspace exposes them under the short `px-*` aliases.
+
+## Quickstart
+
+1. Generate a key and add an allowlist entry:
+
+   ```bash
+   cargo run -p px-cli -- keys generate --id ops1 --note "first operator"
+   # paste the printed id + argon2_hash into config/keys.yaml
+
+   cargo run -p px-cli -- allowlist add \
+     --domain pedidosya.com.ar \
+     --justification "internal price observability"
+   ```
+
+2. Start the server:
+
+   ```bash
+   PX_BIND=127.0.0.1:8080 \
+   PX_KEYS=config/keys.yaml \
+   PX_ALLOWLIST=config/allowlist.yaml \
+   cargo run -p px-server
+   ```
+
+3. Solve a target:
+
+   ```bash
+   curl -X POST http://127.0.0.1:8080/v1/solve \
+     -H "Authorization: Bearer ops1:<secret>" \
+     -H "content-type: application/json" \
+     -d '{"url":"https://www.pedidosya.com.ar/","proxy":null}'
+   ```
+
+   Response shape:
+
+   ```json
+   {
+     "data": {
+       "user_agent": "Mozilla/5.0 ...",
+       "solve_ms": 10273,
+       "cache_hit": false,
+       "handler": "perimeterx",
+       "cookies": [{"name":"_px3","value":"...","domain":".pedidosya.com.ar","path":"/"}],
+       "expires_at": 1747500000
+     },
+     "status": "solved"
+   }
+   ```
+
+For systemd, reverse proxy, and key rotation workflows see [`docs/deployment.md`](docs/deployment.md).
 
 ## Documentation
 
 | Doc | Purpose |
 |---|---|
 | [`docs/000-sow-index.md`](docs/000-sow-index.md) | Statement of Work index + deliverable traceability |
-| [`docs/adr/README.md`](docs/adr/README.md) | Architecture Decision Records (15 ADRs as of 2026-05-16) |
+| [`docs/adr/README.md`](docs/adr/README.md) | Architecture Decision Records (23 ADRs as of 2026-05-17) |
 | [`docs/phase/README.md`](docs/phase/README.md) | Phase plan (00–04 critical path + R research) |
+| [`docs/deployment.md`](docs/deployment.md) | Fresh-Linux install, systemd, reverse proxy, key generation, allowlist editing |
+| [`docs/threat-model.md`](docs/threat-model.md) | Misuse vectors + mitigations |
+| [`docs/dual-use-policy.md`](docs/dual-use-policy.md) | Operator commitments per [`docs/011-sow-dual-use.md`](docs/011-sow-dual-use.md) |
 | [`docs/standards/axum-best-practice.md`](docs/standards/axum-best-practice.md) | Coding standard (Clean Architecture, ≤200 LOC/file, no `unwrap`) |
 | [`docs/standards/design-patterns.md`](docs/standards/design-patterns.md) | Canonical inventory of patterns + Rust idioms + anti-patterns |
 | [`px-research/README.md`](px-research/README.md) | Research-track home (RE captures, deobfuscation notes) |
@@ -32,4 +102,4 @@ A Rust-built solver service for PerimeterX (HUMAN Security) protection. Given a
 
 ## License
 
-To be selected before the first public push. Proposed: **AGPL-3.0-or-later**, to discourage closed-source resale as an anonymous SaaS.
+**AGPL-3.0-or-later** — chosen to discourage closed-source resale as an anonymous SaaS. The license is declared in the workspace `Cargo.toml`; a top-level `LICENSE` file is tracked as a follow-up.