Acquisition polish: hello/access onboarding and easier first-run docs

ACQUISITION.md

@@ -1,15 +1,32 @@
 # Acquisition Brief — BotScope
 
 **Date:** 2026-09-21  
-**Status:** Briefing document only. **No acquisition has occurred** by virtue of this file.
+**Status:** Briefing document only. **No acquisition has occurred** by virtue of this file.  
+**No valuation** is stated in this document.
 
-## What the project does
+## Problem
 
-Internet-wide bot traffic census / local analyzer: federates public crawler IP panels and optional CDN estimates; local log/session analysis and Qt Observatory.
+Operators and researchers lack a transparent, evidence-gated picture of automated Internet traffic versus human-likely traffic. Existing tools often force certainty, conflate a single site’s logs with “the Internet,” or require cloud accounts before a first measurement.
 
-## Problem
+BotScope addresses this with:
+
+- An **Internet-wide census surface** (Global Observatory) that federates public crawler/IP panels and optional CDN estimates
+- A **local measurement workstation** (CLI + native Qt Observatory) for authorized logs, sessions, and live capture
+- An **UNKNOWN-first** classification posture with provenance badges (OBSERVED / CLASSIFIED / INFERRED)
+
+## Product surfaces
 
-Operators lack a transparent, evidence-gated picture of automation traffic vs human traffic.
+| Surface | How to reach it | Notes |
+|---------|-----------------|-------|
+| CLI | `botscope <command>` | Headless analyze, hello, doctor, federation, … |
+| First-run | `botscope hello` | Offline demo end-to-end; no GUI/network/API keys |
+| Ease of access | `botscope access` / `botscope quickstart` | Install paths, data locations, privacy defaults |
+| Desktop Observatory | `botscope` or `botscope gui` | Native Qt / PySide6 — not a website |
+| Global Observatory | GUI **Global** page / `botscope federation` | Zero-auth public sources; Radar optional |
+| Python API | `from botscope import Analyzer` | Same pipeline as CLI |
+| PyPI package | `pip install botscope` / `botscope[gui]` | v2.0.0 |
+
+Network contribution stays **OFF by default**. Zero-config for local logs: no account, no cloud profile, no API key.
 
 ## What is included in a transaction (typical)
 
@@ -24,30 +41,68 @@ Operators lack a transparent, evidence-gated picture of automation traffic vs hu
 - Operator-published IP range data / Cloudflare Radar data
 - Third-party dependency source
 - Buyer cloud accounts or secrets
-- Fabricated user/revenue metrics (none claimed)
+- Fabricated user/revenue/census metrics (none claimed)
 
 ## Maturity
 
-v2.0.0 on PyPI; short git history (≈9 commits). Single human maintainer + Dependabot.
-
-## Deployment model
-
-pip install; CLI `botscope`; optional GUI; optional Cloudflare Radar token.
+v2.0.0 on PyPI; short git history. Single human maintainer + Dependabot. See `docs/acquisition/EXECUTIVE_SUMMARY.md`.
 
 ## Technical differentiation
 
-Evidence-gated classification with UNKNOWN-first posture; federated public panels; optional local GUI Observatory.
+- Evidence-gated classification with UNKNOWN-first posture
+- Federated public panels for an Internet-wide census story (local KPIs stay dataset-scoped)
+- Offline-first first-run (`botscope hello`) and diagnostics (`botscope doctor`)
+- Optional local GUI Observatory and live capture extras
 
 ## Transferable IP / third-party / limitations
 
-See `docs/acquisition/IP_AUDIT.md`, `TRANSFER_MANIFEST.md`, `BOTSCOPE_DILIGENCE.md`.
+See:
+
+- `docs/acquisition/IP_AUDIT.md`
+- `docs/acquisition/TRANSFER_MANIFEST.md`
+- `docs/acquisition/BOTSCOPE_DILIGENCE.md`
+- `docs/acquisition/DEPENDENCY_AUDIT.md`
+
+## Demo path (buyer / evaluator)
+
+Fresh machine, no secrets required for the minimal path:
+
+```bash
+pip install botscope
+botscope doctor
+botscope hello
+botscope hello --keep-session demo.bscope
+botscope access
+```
+
+With GUI extras:
+
+```bash
+pip install 'botscope[gui]'
+botscope gui
+```
+
+From a clone (contributors / diligence):
+
+```bash
+git clone https://github.com/theworker02/botscope.git && cd botscope
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e '.[dev]'
+botscope hello
+pytest -q
+```
+
+Expected: commands exit 0; demo output is labeled **DEMO**; no fabricated Internet-wide rates. Detailed script: `docs/acquisition/BUYER_DEMO.md`. First-hour operator guide: `docs/guides/EASE_OF_ACCESS.md`.
 
 ## Handoff / evaluation
 
-See `docs/acquisition/HANDOFF_PLAN.md` and `BUYER_DEMO.md`.
+- `docs/acquisition/HANDOFF_PLAN.md`
+- `docs/acquisition/BUYER_DEMO.md`
+- `docs/acquisition/BUYER_DUE_DILIGENCE_CHECKLIST.md`
+- `docs/acquisition/CHANGE_OF_CONTROL_CHECKLIST.md`
 
 ## Acquisition contact
 
 GitHub [@theworker02](https://github.com/theworker02) · https://github.com/theworker02/botscope
 
-No valuation is stated in this document.
+Commercial / license questions: see root `COMMERCIAL.md` and `SUPPORT.md`.

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to BotScope are documented here. Only features that exist in the repository are listed.
 
+## [Unreleased]
+
+### Added
+
+- **`botscope hello`** — offline first-run demo analysis with friendly summary (`--json`, `--keep-session PATH`); no GUI, network, or API keys required
+- **`botscope access`** — ease-of-access checklist (install paths, zero-config claims, data locations, GUI, network-off guidance, doctor)
+- Richer **`botscope quickstart`** covering install, hello, demo, analyze, GUI, doctor, Global Observatory, and privacy defaults
+- **`botscope.onboarding`** helpers module (testable summary / checklist builders)
+- Docs: expanded `ACQUISITION.md`, `docs/guides/EASE_OF_ACCESS.md`, FEATURES/README updates for hello/access
+
 ## [2.0.0] — 2026-09-18
 
 Major release: measurement workstation, Global Observatory estimates, bundled ML, and live multi-sensor capture.

FEATURES.md

@@ -14,7 +14,7 @@ Labels reflect repository reality for BotScope **v2.0.0**.
 | Privacy transforms | IMPLEMENTED | `botscope.privacy` | |
 | Network client (OFF default) | IMPLEMENTED | `botscope.network` | |
 | Signatures packs | IMPLEMENTED | `botscope.signatures` | |
-| CLI | IMPLEMENTED | `botscope.cli` | live/capture/flows/geo/eval/federation/… |
+| CLI | IMPLEMENTED | `botscope.cli` | live/capture/flows/geo/eval/federation/hello/access/… |
 | Desktop Observatory GUI | IMPLEMENTED | `botscope.gui` | Native Qt/PySide6 (not a website) |
 | Global Observatory | IMPLEMENTED | `botscope.sources`, `gui.global_observatory` | Zero-auth federation; Radar OPTIONAL_AUTH |
 | Internet estimate headline | IMPLEMENTED | `botscope.estimation.internet` | Opens with ≥2 weighted traffic shares + uncertainty |
@@ -35,6 +35,8 @@ Labels reflect repository reality for BotScope **v2.0.0**.
 | ASN offline table | IMPLEMENTED | `botscope.asn` | Optional local CSV/JSON |
 | Enrich composer | IMPLEMENTED | `botscope.enrich` | ASN/geo/static + optional rDNS |
 | Demo corpus | IMPLEMENTED | `botscope.demo` | Synthetic |
+| First-run hello | IMPLEMENTED | `botscope.onboarding`, `cli` | `botscope hello` — offline demo summary; `--json` / `--keep-session` |
+| Ease-of-access checklist | IMPLEMENTED | `botscope.onboarding`, `cli` | `botscope access` + richer `botscope quickstart` |
 | Labeled eval fixtures | IMPLEMENTED | `datasets/fixtures` | Mini labeled JSONL |
 | Provenance inspector | IMPLEMENTED | `botscope.provenance` | |
 | Quality scorecard | IMPLEMENTED | `botscope.quality` | |

README.md

@@ -24,6 +24,34 @@ BotScope is an **Internet-wide bot traffic census**: the Global Observatory fede
 
 ---
 
+## Try in 60 seconds
+
+No GUI, no network, no API keys — just a labeled offline demo:
+
+```bash
+pip install botscope
+botscope hello
+```
+
+Optional: save a session or emit JSON:
+
+```bash
+botscope hello --keep-session hello.bscope
+botscope hello --json
+```
+
+Then explore the checklist and desktop app:
+
+```bash
+botscope access
+pip install "botscope[gui]"   # if you want the Observatory
+botscope gui
+```
+
+First-hour guide: [`docs/guides/EASE_OF_ACCESS.md`](docs/guides/EASE_OF_ACCESS.md).
+
+---
+
 ## Screenshots
 
 <p align="center">
@@ -131,6 +159,7 @@ Environment check and synthetic demo:
 
 ```bash
 botscope doctor
+botscope hello
 botscope demo --output demo_analysis.bscope
 botscope open demo_analysis.bscope
 ```
@@ -161,7 +190,7 @@ print(result.automation_fraction)
 print(result.stats.by_category)
 ```
 
-More detail: [`docs/guides/QUICKSTART.md`](docs/guides/QUICKSTART.md) · [`docs/guides/INSTALLATION.md`](docs/guides/INSTALLATION.md)
+More detail: [`docs/guides/EASE_OF_ACCESS.md`](docs/guides/EASE_OF_ACCESS.md) · [`docs/guides/QUICKSTART.md`](docs/guides/QUICKSTART.md) · [`docs/guides/INSTALLATION.md`](docs/guides/INSTALLATION.md)
 
 ---
 
@@ -171,6 +200,8 @@ More detail: [`docs/guides/QUICKSTART.md`](docs/guides/QUICKSTART.md) · [`doc
 
 | Command | Purpose |
 |---------|---------|
+| `hello` | Offline first-run demo summary (no GUI/network/API keys) |
+| `access` | Ease-of-access checklist (install, data dirs, privacy) |
 | `doctor` | Environment / policy diagnostics |
 | `demo` | Analyze bundled synthetic corpus (always labeled DEMO) |
 | `analyze` | Analyze an authorized log or PCAP |

SUPPORT.md

@@ -1,8 +1,10 @@
 # Support
 
-- **Docs:** start with [README.md](README.md), [docs/guides/QUICKSTART.md](docs/guides/QUICKSTART.md), and [FEATURES.md](FEATURES.md)
+- **Docs:** start with [README.md](README.md), [docs/guides/EASE_OF_ACCESS.md](docs/guides/EASE_OF_ACCESS.md), [docs/guides/QUICKSTART.md](docs/guides/QUICKSTART.md), and [FEATURES.md](FEATURES.md)
+- **First run:** `pip install botscope` then `botscope hello` (GUI: `pip install 'botscope[gui]'`)
 - **Bugs / features:** GitHub Issues (use the templates under `.github/ISSUE_TEMPLATE/`)
 - **Security:** [SECURITY.md](SECURITY.md)
+- **Acquisition:** [ACQUISITION.md](ACQUISITION.md) · [docs/acquisition/](docs/acquisition/)
 - **Diagnostics:** run `botscope doctor` or `botscope doctor --bundle support.zip` and attach only sanitized output
 
-BotScope is an alpha research/engineering tool. Please label DEMO analyses clearly and do not treat local shares as Internet-wide statistics.
+BotScope is a **v2.0.0 beta** research/engineering tool. Please label DEMO analyses clearly. Local Observatory shares stay dataset-scoped; the **Global Observatory** census and any gated Internet headline are separate from a single local log and must not be conflated.

docs/README.md

@@ -2,13 +2,14 @@
 
 BotScope documentation mirrors repository reality. Status labels you may see: **IMPLEMENTED**, **PARTIAL**, **EXPERIMENTAL**, **PLANNED**, **RESEARCH**, **NOT IMPLEMENTED**.
 
-Start here if you are new: [guides/QUICKSTART.md](guides/QUICKSTART.md).
+Start here if you are new: [guides/EASE_OF_ACCESS.md](guides/EASE_OF_ACCESS.md) or [guides/QUICKSTART.md](guides/QUICKSTART.md).
 
 ## Guides
 
 | Doc | Description |
 |-----|-------------|
-| [guides/QUICKSTART.md](guides/QUICKSTART.md) | Install → doctor → demo → first analysis |
+| [guides/EASE_OF_ACCESS.md](guides/EASE_OF_ACCESS.md) | First-hour path: hello, access, data locations, privacy |
+| [guides/QUICKSTART.md](guides/QUICKSTART.md) | Install → doctor → hello/demo → first analysis |
 | [guides/INSTALLATION.md](guides/INSTALLATION.md) | Extras, venv, verification |
 | [guides/FAQ.md](guides/FAQ.md) | Common questions |
 | [guides/TROUBLESHOOTING.md](guides/TROUBLESHOOTING.md) | Failure modes and fixes |
@@ -71,6 +72,7 @@ Internal phase notes and checklists live under [development/](development/). Pre
 
 - [../README.md](../README.md) — project overview  
 - [../FEATURES.md](../FEATURES.md) — feature matrix  
+- [../ACQUISITION.md](../ACQUISITION.md) — acquisition briefing  
 - [../CHANGELOG.md](../CHANGELOG.md) — releases  
 - [../CONTRIBUTING.md](../CONTRIBUTING.md) — contribution guidelines  
 - [../SECURITY.md](../SECURITY.md) — vulnerability reporting  

docs/acquisition/BUYER_DEMO.md

@@ -9,6 +9,7 @@ git clone https://github.com/theworker02/botscope.git && cd botscope
 python3 -m venv .venv && source .venv/bin/activate
 pip install -e '.[dev]'
 botscope doctor
+botscope hello
 botscope demo
 pytest -q
 ```