# Atto Setup Guide

**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 computer | 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 + **bundled** `atto` engine (no Terminal) |
| **`atto` wheel** (optional) | CLI/`uv` or MCP — **buyer claim download only**, not on the public kit |
| This guide | Zero → first Find plan |

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

---

## 1. Requirements

### macOS (Apple Silicon)

- Apple Silicon Mac (M1–M4) · macOS 13+ recommended  
- ~500 MB free disk  
- Internet when you open archive sites in your browser  
- **No Terminal** for the normal kit — the engine ships inside Atto.app  

### Refund

**No refunds.** Atto is a digital download. Once the kit or license claim is available, the sale is final on Stripe. Wrong-platform purchases (Intel Mac; expected Windows SmartScreen for a new publisher) are not refund reasons. EU/UK: immediate digital delivery means you lose the 14-day withdrawal right once the claim is available — see youratto.com/terms. 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 (x86_64 — CLI + desktop beta)

- Ubuntu 22.04 / 24.04 (or similar glibc Linux)  
- **Desktop beta (unsigned, invite-only):** email support@youratto.com with your Stripe receipt for a private `.deb` / AppImage link (not a public GitHub download)  
- **CLI engine (public):**  
  https://youratto.com/kit/v0.1.0/linux/atto-x86_64-unknown-linux-gnu  
- No Python / `uv` required for the frozen engine. Vault default: `~/AttoVault/`  
- `.deb` needs: `sudo apt install libwebkit2gtk-4.1-0` (if not pulled automatically)  
- AppImage: `chmod +x Atto_*.AppImage` — if FUSE fails, use `--appimage-extract`  

```bash
# CLI
chmod +x atto-x86_64-unknown-linux-gnu
./atto-x86_64-unknown-linux-gnu --help
./atto-x86_64-unknown-linux-gnu license status   # expect state: licensed (exit 0)

# Desktop (.deb) — after Support sends the private installer
sudo dpkg -i ./Atto_*_amd64.deb || sudo apt-get install -f -y
atto-desktop &
```

**Windows** (x64) is a desktop kit alongside Mac, at https://youratto.com/kit/v0.1.0/windows/ — Authenticode-signed via Azure Artifact Signing (publisher: Claudio Barone). SmartScreen may still warn once for a new publisher while reputation builds.

---

## 2. Install (macOS — no Terminal)

1. Open the DMG → drag **Atto.app** to Applications (or any folder you like)  
2. Open **Atto** (double-click; see Gatekeeper above if macOS warns)  
3. On Home you should see **Engine ready** — the engine is inside the app  

If Home shows **Something’s missing from this install**, re-download the DMG from https://youratto.com/kit/v0.1.0/ (old kits required a Terminal wheel install). Support: https://youratto.com/support/

Optional CLI / MCP wheel (power users only) is in §7 — **not** required for the desktop app.

---

## 3. Import your license (required, no Terminal)

Atto stays locked until a valid `license.json` is imported. This is a two-click step:

1. Open the **claim link** from your purchase email (or the page Stripe showed after checkout) and download `license.json`  
2. In Atto, click **Import license** in the bar at the top of the window and pick that file  
3. The banner turns into **Licensed to …**. If not, click **Check again**  
4. **Standard kit:** paste your claim link once under **Register this computer** (or keep `claim_token` beside `license.json`) so this machine is registered — there is no separate Activate step. **Pro (2 seats):** use **Activate this machine** on each machine.  

That is all. No folders to find, no commands to type.

**Claim link says it expired?** The download link is deliberately short-lived (about 5 minutes). Reopen the claim page and it works again — your purchase is fine. Lost the email entirely: support@youratto.com with your Stripe receipt.

<details>
<summary>Fallback: place the file by hand</summary>

**Prefer Import license** (steps above). Use Terminal only if the file picker is broken.

**Find the real file first.** Browsers often rename downloads (`license (1).json`) or put them on Desktop — do **not** assume `~/Downloads/license.json`.

Mac / Linux — list candidates:

```bash
ls -la ~/Downloads/*license* 2>/dev/null
ls -la ~/Desktop/*license* 2>/dev/null
```

When you know the full path, copy it (paste **your** path):

```bash
mkdir -p ~/.atto
cp "/path/to/your/license.json" ~/.atto/license.json
```

Windows PowerShell (do **not** use `mkdir -p ~/.atto`):

```powershell
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.atto" | Out-Null
Copy-Item -Path "C:\path\to\your\license.json" -Destination "$env:USERPROFILE\.atto\license.json"
```

Then reopen Atto or click **Check again**.

</details>

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

---

## 4. First launch (guided)

1. Open **Atto.app**
2. On **Home**, create a short project name (e.g. `my-family`) — use lowercase letters, digits, hyphens, or underscores (for example `my-family` or `rossi_1`). You do **not** need to pick a folder  
3. On **Home**, open **Who are you looking for?** — fill in a name, rough birth year, and town (or load **Try a practice example**) → click **Find records for …**  
4. On **Find**, click a link under **Open & check** (preferred — Atto opens the archive, then takes you to **Documents** to capture) or **Open only** (just the browser). To rebuild links later, use **Build search links** / **Rebuild links**.  
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  

**Practice** tools on Find use made-up sample records that ship with the app. They are not real finds and they never change your tree.

---

## 5. Approve (human gate)

1. Open **Approve**  
2. Review one suggestion at a time  
3. **Add to tree** only when the act matches — that is the merge (Import GEDCOM is the other human write path)  

A find that is not attached to a person yet cannot be added. Choose who the record is about on **Find** or **Documents** first — for handwriting readings there is a **Who is this record about?** picker — or use Documents → **Add person (Approve once)**, or import a GEDCOM so there is someone to attach it to.

---

## 6. Tree & Share (later)

- A new project starts with an **empty tree**. Import a GEDCOM or approve your first find and the chart appears.  

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

---

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

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

The optional **MCP/CLI wheel is a buyer claim download**, not a public kit file. After Stripe checkout, open your claim page on `license.youratto.com` and use **Download MCP/CLI wheel** (claim-gated; link expires in ~5 minutes — refresh the claim page for a new one). Anonymous kit URLs do not serve `.whl` files.

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

1. Download the wheel from the claim page, then install the MCP extra:

```bash
cd ~/Downloads   # or wherever the claim-page wheel was saved
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.
   MCP may open allowlisted research URLs in your browser; it does not scrape archive HTML into your vault. Do not paste scraped pages into Approve.
4. 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 computer.

---

## Licensing recap

Importing the license is **§3** above — do it right after install. The same claim page also offers the optional MCP/CLI wheel (never a public kit file).

Kit files (DMG, this guide): https://youratto.com/kit/v0.1.0/ — MCP/CLI wheel is claim-only.

### Windows (x64)

Windows installer is **Authenticode-signed** via Azure Artifact Signing (publisher: Claudio Barone):

https://youratto.com/kit/v0.1.0/windows/

1. Buy on Stripe → claim `license.json`. Friend comps: ask Support for an invite.
2. Download `Atto_0.1.11_x64-setup.zip` from the Windows kit page.
3. Confirm the **zip** SHA-256 against published `SHA256SUMS.txt` (entry for the Windows zip; hash starts `c325f015…`) **before** you run anything.
4. Unzip, run the `.exe`. SmartScreen may still warn once for a new publisher while reputation builds — if so, **More info → Run anyway** (not a refund reason). Quit Atto first if upgrading — install over the old app; your vault stays put.
5. Import `license.json` before using Home / Documents / Find.
6. Later updates: in Atto → Home → **Advanced — updates & support** → **Check for updates** (or re-download the zip and install over — your vault stays on disk).

Without a license, Atto's app features stay locked. Your vault folder is always ordinary files on your disk — never encrypted, never held hostage.

---

## Troubleshooting

| Symptom | Fix |
|---------|-----|
| Something’s missing from this install | Re-download the current kit from youratto.com/kit (or Home → Check for updates). Engine is bundled. Old kits needed Terminal — this one does not. |
| Optional CLI `atto: command not found` | Only if you installed the wheel: `uv tool update-shell` or `export PATH="$HOME/.local/bin:$PATH"` |
| Find plan empty | Save a note with Subject / Birth / Place (or `Comune:` / `Year:` lines) first |
| Practice run | Made-up sample data by design — use **Open & check** / **Open only** links for real archives |
| Approve queue empty | Finds only reach Approve once they are attached to a person. On Documents use **Add person (Approve once)**, import a GEDCOM, or pick the person on Find before reading handwriting. |
| Tree looks blank | A new project starts empty. Import a GEDCOM, add a person on Documents, or approve your first find. |
| Citizenship checklist | Find → build checklist; update doc status; Reveal playbook folder |
| Gatekeeper / “damaged” | Right-click → Open (should be rare — build is notarized) |
| License required / vault locked | Claim `license.json` from Stripe → **Import license** in Atto (§3) |
| Claim download link expired | Normal — reopen the claim page for a fresh link |
| Windows SmartScreen | May warn once for a new publisher (Azure-signed); More info → Run anyway — not a refund reason |

---

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