Jake
3770815fbf
Closes the code-side v0.1 ship gate. All quality gates green: cargo fmt/clippy/test (~327 tests), npm check (0/0), vitest 13/13, scripts/dogfood-rebrand-drill.sh 8/8. Phase F — first-run onboarding promoted to v0.1 - FirstRunPage with skip-to-main + failure recovery + event recording - Six onboarding commands (record/list/has-completed + lumotia_events) - Storage migration v17 (onboarding_events + lumotia_events tables) UI hardening (in-scope items from v0.1-ui-hardening.md) - StatusPill + PostCaptureCard components, 21st preview entry - Sidebar recording-as-sacred-state (opacity + aria-disabled, reduced-motion) - Settings 6-section regroup + Help section + Activation log + Privacy toggle - Error-state copy sweep (DictationPage + SettingsPage, plain-language) - Global :focus-visible rule, textarea outlines restored - Ctrl+K / Ctrl+, / Escape bindings in +layout LLM resilience - rule_based_extract_tasks (regex-free imperative-verb extractor) + extract_tasks_with_fallback wrapper — task extraction never returns zero - tokio::time::timeout(120s) wraps cleanup/tags/tasks commands Release artefacts - LICENSE (canonical AGPL-3.0), CHANGELOG (Keep-a-Changelog format) - v0.1-release-notes, privacy-and-ai-use, install-warnings, tester-onboarding-kit, tester-acceptance-runbook, code-signing-setup, apple-silicon-rb08-runbook, virtual-audio-setup, v0.1-contrast-audit - Workspace versioning + AGPL spdx; npm exact-pin (10 ranges removed) - AppImage SHA-256 sidecar in build.yml - README v0.1 section + Reporting-issues; canonical repo slug Closure pass — items moved from human-required to code-complete - KI-02 Linux idle inhibit: zbus 5 → org.freedesktop.login1.Manager.Inhibit - KI-03 Windows sleep prevention: SetThreadExecutionState(ES_CONTINUOUS|...) - acquire/release_idle_inhibit Tauri commands, wired in DictationPage - Diagnostic-bundle frontend wire-up (Settings → Help button) - WCAG-AA contrast fix via .btn-filled-text utility (no token changes) - 8 destructive-action sites wrapped in plain-language confirm() guards - KNOWN-ISSUES.md + v0.1-known-limitations.md updated (KI-02/03 fixed) Scripts - pre-tag-verify.sh, tag-day.sh, smoke-linux + driver - parse-diagnostic-bundle.sh, parse-activation-log.py Per-item audit trail: docs/release/v0.1-completion-status.md Remaining: W-01…W-08 (signing certs, hardware probes, smoke matrix, tester recruitment) — see docs/release/v0.1-known-limitations.md.
140 lines
5.7 KiB
Markdown
140 lines
5.7 KiB
Markdown
---
|
||
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).
|