---
name: tester-onboarding-kit
type: release
tags: [release, v0.1, testers, onboarding, email-template, feedback]
description: "Recruitment email template, platform targets, day-3 check-in script, and feedback-collection protocol for the Lumotia v0.1 private beta (~20 testers)."
---

# Tester onboarding kit

## Inviting a tester

Paste this into Gmail. Fill in the three variables. Send from your personal address, not a mailing list.

```
Subject: Lumotia v0.1 — would you try it for me?

Hi {{NAME}},

I'm shipping v0.1 of Lumotia, a local-first dictation + task-capture desktop app.
Local-first means everything runs on your device. No cloud, no telemetry.

Would you install it on your {{PLATFORM}} and try the 10-step getting-started?
Should take 10–15 minutes.

Download: {{DOWNLOAD_URL}}
First-install warnings (SmartScreen / Gatekeeper): https://github.com/jakeadriansames/lumotia/blob/main/docs/release/install-warnings.md
What to do at each step: docs/release/tester-acceptance-runbook.md in the repo

What I'm looking for:
- Did anything confuse you?
- Did anything break?
- Did the cleanup and task extraction make sense?
- Would you use it again next week?

Reply with a few sentences when you're done. No form, no survey.

Thanks,
Jake
```

Variables:
- `{{NAME}}` — first name
- `{{PLATFORM}}` — "Linux", "macOS (Apple Silicon)", or "Windows 11"
- `{{DOWNLOAD_URL}}` — direct link to the platform artefact from the GitHub release

## How many testers, on which platforms

Target: 20 testers across three platforms. Bias toward Linux — it is the primary platform, bugs surface fastest, and iteration is quickest.

| Platform | Target count | Priority |
|---|---|---|
| Linux (Fedora or Ubuntu) | 8–10 | Primary — recruit first |
| macOS Apple Silicon | 5–7 | Best-effort — needed for RB-08 verification |
| Windows 11 | 3–5 | Best-effort |

For week 1 of private beta, 5–7 testers total across all platforms is realistic. The public-launch metric (20 strangers, post-tag) is separate.

When recruiting, prefer people who:
- Actually dictate or take notes for work
- Are comfortable with "this is pre-release software"
- Will reply honestly if something breaks (not just go quiet)

Avoid recruiting anyone who will feel obligated to say it's great.

## Day-3 check-in (if no reply)

Send this if a tester hasn't replied after three days:

```
Hi {{NAME}},

Just checking in on the Lumotia install. If you got stuck or something broke,
tell me what you saw — that is the most useful feedback I can get right now.

If you didn't get a chance to try it, no worries. Let me know and I'll follow
up later or remove you from the list.

Jake
```

Do not send a second nudge after this. Silence after two messages means the install failed silently or life happened.

## Feedback collection

**Routing replies.** Every reply goes into one of two places:

1. Real bug or confusing UX — add to `docs/release/v0.1-known-limitations.md` under "Reporting issues" or open a GitHub issue.
2. Deferred or unclear — add to a private scratch file (`docs/private/v0.1.1-deferred-notes.md`, not committed). Do not let it sit in your inbox.

After the first five replies: identify the three most common stumbling points and add workarounds to `docs/release/v0.1-known-limitations.md`. This is a required metric (see v0.1-checklist.md "Support burden signal").

**Activation log.** Ask testers who are comfortable to optionally share their activation log after three days of use: Settings → Privacy → Activation log. They paste the table into their reply. This is fully local and opt-in — never require it.

**Target state.** At least 70% of issues should be self-service (tester can describe what went wrong without a call). If you drop below 50%, improve docs and the diagnostic bundle flow before recruiting more testers.

## Once a tester replies

When a tester sends a reply that includes an activation log or a diagnostic bundle, use the parser scripts to extract actionable information in under a minute.

### Parsing an activation log

Testers paste their activation log table from Settings → Privacy → Activation log. Save the pasted content to a file and run:

```sh
python3 scripts/parse-activation-log.py path/to/tester-activation.json
```

Or if they pasted a plain table (not JSON), pipe it through `--paste`:

```sh
pbpaste | python3 scripts/parse-activation-log.py --paste   # macOS
xclip -o | python3 scripts/parse-activation-log.py --paste  # Linux
```

The script prints a one-screen summary covering all five activation metrics:

- **Activation** — was first capture within 3 min of opening the app?
- **Core value** — did they get ≥ 3 useful captures in the first 24 hours?
- **Retention** — did they return within 7 days?
- **Quality** — did extracted tasks get accepted/edited? (`?` — follow up qualitatively)
- **Trust** — can they articulate what stays local? (`?` — follow up qualitatively)

Items marked `?` are not in the activation log. Follow up with a direct question per the tester acceptance runbook.

### Parsing a diagnostic bundle

Testers who hit a reproducible bug can use Settings → About → Save diagnostic bundle to generate a `.zip`. They attach it to their reply. Run:

```sh
./scripts/parse-diagnostic-bundle.sh path/to/tester-bundle.zip
```

The script:

1. Checks the bundle passed the redaction deny-list (no audio, no transcripts, no `.db` files). A `FAIL` verdict means the bundler has a bug — do not share the bundle further.
2. Prints a content inventory, log error summary (top 3 patterns), and the non-secret preference values.
3. Exits non-zero if any check fails, so it can be piped into a CI-style workflow.

Both scripts require no installation beyond Python 3 (stdlib only) and `unzip` + `jq` (for the shell script; jq falls back to grep-based extraction if missing).