# Atto Setup Guide (v0.1.0)

**Product:** Atto — local Italian civil-record genealogy workbench  
**Price model:** One-time DIY kit (**you** do the archive browsing)  
**Support:** support@youratto.com

---

## What Atto is (and is not)

| Atto does | Atto does **not** |
|-----------|-------------------|
| Keep notes, scans, and your tree private on this Mac | Automatically download your ancestors’ acts from Italy |
| Build a **Find plan** with ready-made browser links | Scrape Antenati / FamilySearch for you |
| Let **you Approve** before anything enters the tree | Auto-merge guesses into GEDCOM |
| Track a citizenship **document checklist** (status words + soft-flags only) | Tell you that you are eligible, “grandfathered,” or file at a consulate |

**You browse archives. Atto organizes. Tree writes are human-gated: Approve merges, or Import a GEDCOM you already own.**

### Privacy (short)

- Vault stays on disk (`~/AttoVault/`) unless **you** publish a family share or opt into AI suggest  
- Full SSN is stripped before LLM packs; family Publish expects Cloudflare Access (fail-closed)  
- AI is suggest-only — never self-approves the tree  

### This is / isn’t (citizenship)

| This is | This isn’t |
|---------|------------|
| An organizer for *copie integrali*, US vitals, apostille, translation | An attorney or eligibility verdict |
| Status labels: Identified → Requested → Received → … → Recognized | “Ready to File / Approved / You are eligible” |
| Soft-flags for comune (Circ. 26185) vs consular Prenot@Mi tracks | Equating Prenot@Mi screenshots with municipal a-bis |
---

## What you installed

| Piece | Role |
|-------|------|
| **Atto.app** | Desktop UI |
| **`atto` CLI** (wheel) | Engine behind the UI — **required** for this kit |
| This guide | Zero → first Find plan |

Your files live in a private folder on this Mac (default `~/AttoVault/`). Nothing is uploaded to an Atto cloud — there isn’t one for your vault.

---

## 1. Requirements

### macOS (desktop kit — primary)

- Apple Silicon Mac (M1–M4) · macOS 13+ recommended  
- ~500 MB free disk  
- Internet when you open archive sites in your browser  
- **Terminal once** to install the engine wheel (step 2)  

### Refund

**No refunds.** Atto is a digital download. Once the kit or license claim is available, the sale is final on Stripe. Support: support@youratto.com.

### Gatekeeper (first open)

This build is **Apple-notarized** (Developer ID). First open should work with a normal double-click.

If macOS still warns (rare, usually after downloading):

1. Finder → right-click **Atto.app** → **Open** → **Open**  
2. Or: **System Settings → Privacy & Security** → allow Atto  

### Linux (CLI engine only — no GUI yet)

- x86_64 Ubuntu 22.04 / 24.04 (or similar glibc Linux)  
- Download `atto-x86_64-unknown-linux-gnu` from  
  https://youratto.com/kit/v0.1.0/linux/atto-x86_64-unknown-linux-gnu  
- No Python / `uv` required. Vault default: `~/AttoVault/`  
- Desktop `.deb` / AppImage is **not** in this kit yet  

```bash
chmod +x atto-x86_64-unknown-linux-gnu
./atto-x86_64-unknown-linux-gnu --help
./atto-x86_64-unknown-linux-gnu license status   # soft-gate; never locks vault
./atto-x86_64-unknown-linux-gnu project new my-family
```

Windows is not shipped.

---

## 2. Install the `atto` engine (macOS — required)

The app will show a red **Engine not found** banner on Home until this works.

```bash
# Install uv (if you do not have it)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Put uv tools on your PATH (needed in *new* Terminal windows)
uv tool update-shell
# Then close Terminal and open a new window, OR for this window only:
#   export PATH="$HOME/.local/bin:$PATH"

# From the folder where you downloaded the kit files:
cd ~/Downloads   # or wherever the kit saved
uv tool install ./atto-*.whl
atto --help
```

Then quit and reopen Atto. The desktop app looks for `~/.local/bin/atto` even when GUI PATH is limited.

If it still fails:

```bash
export ATTO_BIN="$(which atto)"
open -a Atto
```

---

## 3. First launch (guided)

1. Open **Atto.app** (right-click → Open the first time)  
2. On **Home**, create a short project name (e.g. `my-family`) — you do **not** need to pick a folder  
3. Use **Guided first run**: edit the note (or keep the practice example) → **Save note & open Find plan**  
4. On **Research**, click the first **Open:** link — that is *you* searching in the browser  
5. Optional: **Citizenship document checklist** — track *copie integrali*, US vitals, apostille, translation (not legal advice; never files for you). Use **Reveal playbook folder** to open `CITIZENSHIP.md` / `FIND.md` in Finder.  
6. When you later save an act and create a suggestion, use **Approve** before it enters the tree  

**Sample demo** buttons on Research use fake practice data. They are not real finds.

---

## 4. Approve (human gate)

1. Open **Approve**  
2. Review one suggestion at a time  
3. **Approve** only when the act matches — Approve merges evidence into your tree (Import GEDCOM is the other human write path)  

---

## 5. Tree & Share (later)

- **Tree** needs an imported GEDCOM or Approved people  

**Share** / **Secrets** stay under **More** until the tree has people. Family **Publish** needs a Cloudflare account and Wrangler (Access email gate).

---

## 6. Optional — AI helper (MCP) for Cursor / Claude

**Skip this entirely** if you don’t want AI tools near your family files. The Mac app does not need MCP.

If you already use **Cursor**, **Claude Code**, or **Claude Desktop**:

1. Reinstall the engine with the MCP extra (same folder as your kit wheel):

```bash
cd ~/Downloads   # or your kit folder
uv tool install --force "./atto-*.whl[mcp]"
atto-mcp --help
```

2. Add Atto to your MCP config (Cursor: `~/.cursor/mcp.json` or project `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "atto": {
      "command": "atto-mcp",
      "args": [],
      "env": {
        "ATTO_VAULT_ROOT": "/Users/YOUR_USERNAME/AttoVault"
      }
    }
  }
}
```

3. Restart the AI app. Treat suggestions as research help only — **Approve** in Atto remains the only way to change the tree.

Full write-up: https://youratto.com/mcp/

You do **not** need to upload a skill to a marketplace. MCP is a local connection on your Mac.

---

## License (optional soft-gate)

Atto works **without** a license file — your vault at `~/AttoVault/` is never locked. No DRM.

Buy on Stripe → claim page → download `license.json` → save as `~/.atto/license.json` → the soft banner goes quiet.

**Stripe buy / claim:** https://buy.stripe.com/3cI00jdsI49h0fI7BIb3q00  

Kit files (DMG, wheel, this guide): https://youratto.com/kit/v0.1.0/

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Engine not found | `uv tool install ./atto-*.whl` then `uv tool update-shell` + new Terminal; reopen Atto |
| `atto: command not found` | `export PATH="$HOME/.local/bin:$PATH"` or `uv tool update-shell` |
| Find plan empty | Save a note with Subject / Birth / Place (or `Comune:` / `Year:` lines) first |
| Practice / sample demo | Fake data by design — use **Open:** links for real archives |
| Citizenship checklist | Research → build checklist; update doc status; Reveal playbook folder |
| Gatekeeper / “damaged” | Right-click → Open (should be rare — build is notarized) |
| Soft license banner | Expected until you claim `license.json` from Stripe — vault still works |

---

Thank you for buying the DIY kit. Research takes patience; Atto keeps the filing honest.