Metadata-Version: 2.4
Name: atto
Version: 0.1.0
Summary: Genealogy agent kit — vault, playbook, portals, redacted share
Requires-Python: >=3.12
Requires-Dist: argon2-cffi>=23.1.0
Requires-Dist: cryptography>=43.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pytest>=9.1.1
Requires-Dist: ruff>=0.15.22
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.6.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Atto

**Atto** — Italian civil-record genealogy agent kit (*atto* = act/record). Local PII vault, human-gated truth merges, find-plan deep links, redacted family share.

**Honest pitch:** you browse archives in the browser; Atto organizes notes and only updates the tree when you Approve. Cassette/sample demos are practice data, not discovery.

**User data lives outside the repo:** `~/AttoVault/<project-id>/`. Never commit vault contents. Synthetic fixtures only under `fixtures/`.

| Surface | Path | Role |
|---------|------|------|
| CLI engine | `packages/` + `uv run atto` | Vault, portals, truth, share, wire |
| Desktop shell | [`apps/desktop/`](apps/desktop/README.md) | Tauri 2 + React UI over allowlisted IPC (M14) |
| AI sidecar | [`docs/ai-sidecar.md`](docs/ai-sidecar.md) · `atto ai pack` · `atto find plan` · `atto-mcp` | Strip-safe context + find deep-links + allowlisted MCP |
| Agents | [`AGENTS.md`](AGENTS.md) | Coding-agent hard NEVERs |
| Security | [`SECURITY.md`](SECURITY.md) | Threat model, passphrase/stdin, share perimeter |
| Cloudflare share | [`docs/cloudflare-share.md`](docs/cloudflare-share.md) | Pages deploy + Access allowlist |
| Progress | [`PROGRESS.md`](PROGRESS.md) | Module board + golden-path proofs |

## Layers (v1)

| Layer | Modules | Role |
|-------|---------|------|
| Intake | M1 | Dump-anything → vault via content-addressed blobs |
| Vault | M2, M13 | Encrypted project store + audit log (`identity_secret` envelope) |
| Strip | M3 | LLM proxy / secret-strip — full SSN never outbound by default |
| Truth | M4 | GEDCOM + evidence packets; **human gate only** (`atto truth approve` is the only path that writes `truth.ged`) |
| Playbook | M5, M10, FIND | Italian-era task graph; intake→FIND.md deep links; extract soft priors |
| Portals | M6–M9 | FamilySearch, Antenati (local IIIF only), Ancestry-class, HTR bridge |
| Share | M11 | Redacted static site (last-4 SSN; build asserts) + CF Pages/Access |
| Concierge | M12 | Encrypted bundle export/import + retention/destroy |
| Wire | W | Composition-root golden path (synthetic Rossi) |
| Desktop | M14 | Tauri shell — Home / Inbox / Approve / Tree / Share / Secrets / Research |

Security is the ship gate: vault encryption, secret-strip, redacted share, Access-gated family deploy.

## Dev

```bash
uv sync --all-extras
uv run pytest
uv run ruff check .
```

Python 3.12 · uv · pytest · ruff. Packages live under `packages/`.

Desktop (separate toolchain):

```bash
cd apps/desktop && npm install && npm run tauri dev
# proofs: cargo test (src-tauri/) · npm test · see apps/desktop/README.md
```

### Intake dump

```bash
atto project new rossi-demo
atto intake add fixtures/rossi/act_birth_marco.png fixtures/rossi/oral.txt --project rossi-demo
atto intake list --project rossi-demo
```

Copies files into `raw/<sha256>.<ext>` and updates `intake-manifest.json` (kinds: doc|photo|text|oral).

### Wire golden path (synthetic Rossi)

```bash
ATTO_VAULT_ROOT=$(mktemp -d) uv run atto wire demo --project rossi-cli --auto-approve
```

Composes intake → cassette portals → human-gate approve → share build → audit verify. Fixture SSNs are 900-series only.

### Share (local build + Cloudflare)

```bash
atto share build --project rossi-demo --mode family
atto share deploy --project rossi-demo --pages-project atto-rossi --dry-run
atto share cf-check --json
atto share access-plan --pages-project atto-rossi --project rossi-demo --email you@example.com
```

Primary share URL after deploy: `/tree/` (Topola). Family live deploy fails closed without Access unless `--allow-ungated`. Details: [`docs/cloudflare-share.md`](docs/cloudflare-share.md).

### HTR (Transkribus mock)

```bash
atto htr submit --project rossi-demo --image fixtures/rossi/act_birth_marco.png
# optional: TRANSKRIBUS_API_KEY → live_stub path (still no HTTP in v1)
# K177: no LLM-NAS in v1
```

Writes `inbox/evidence/ep_*.json` with `merge: HUMAN_GATE_REQUIRED`.

### Audit verify

```bash
atto audit verify --project <id>
# optional: --vault-root ~/AttoVault
```

Checks the project’s hash-chained `audit/audit.log.jsonl` (exit 0 ok / 1 fail).

## License posture

- **Kit DEFAULT: proprietary** (operator product). Do not assume open-source redistribution of the kit.
- **Isolated sharealike / GPL surfaces:** comune lists via pinned `codice-fiscale-js` fetch (CC-BY-SA) at install time — not vendored into the kit; Tint (GPL) is runtime-download only, never vendored, private optional module.
- Keep GPL/CC-BY-SA code and data **out of the proprietary kit tree** except behind documented isolation boundaries.
- **Vendored Topola** (Apache-2.0) under `packages/share/vendor/topola/` — see `VENDOR.md`.

## Guardrails

- Fake SSNs: **900-series only** (e.g. `900-00-1234`).
- CI privacy grep rejects real operator surnames and non-900 full SSNs in `fixtures/`.
- No `git push` from implementer lanes without operator gate.
