diff --git a/docs/user-walkthrough.md b/docs/user-walkthrough.md new file mode 100644 index 00000000..aafcb68d --- /dev/null +++ b/docs/user-walkthrough.md @@ -0,0 +1,300 @@ +# Archipelago User Walkthrough + +A complete guide to setting up and using Archipelago, from hardware to daily use. Each section describes what the user sees and does, serving as the basis for video tutorials. + +--- + +## Part 1: Hardware & Preparation + +### What You Need + +- **Hardware**: Any x86_64 PC (Intel NUC, mini PC, old desktop) or Raspberry Pi 5 + - Minimum: 4GB RAM, 32GB SSD + - Recommended: 8GB+ RAM, 1TB+ NVMe SSD (for Bitcoin full node) +- **USB drive**: 8GB+ for the installer +- **Network**: Ethernet cable (recommended) or WiFi +- **Monitor + keyboard**: For initial setup (optional if using headless mode) +- **Another computer**: To flash the USB and access the web UI + +### Step 1: Download the ISO + +> **Screenshot**: Browser showing the Archipelago releases page with download buttons for x86_64 and ARM64 ISOs. + +1. Go to the Archipelago releases page +2. Download the latest `archipelago-auto-installer-*.iso` for your architecture +3. Verify the checksum matches the published hash + +### Step 2: Flash the USB Drive + +> **Screenshot**: Balena Etcher with the ISO selected and a USB drive ready to flash. + +1. Download [Balena Etcher](https://etcher.io) (free, cross-platform) +2. Insert your USB drive +3. Open Etcher, select the downloaded ISO +4. Select your USB drive +5. Click "Flash!" — wait for completion (2-5 minutes) + +### Step 3: Boot from USB + +> **Screenshot**: BIOS boot menu showing USB drive as an option. + +1. Insert the flashed USB into your target hardware +2. Power on and enter BIOS/boot menu (usually F2, F12, or Del during boot) +3. Select the USB drive as the boot device +4. The installer will start automatically + +--- + +## Part 2: Installation + +### Step 4: Auto-Installer Runs + +> **Screenshot**: Terminal showing the auto-installer progress — partitioning, copying files, setting up the system. + +The auto-installer handles everything: +- Partitions the target disk (erases existing data) +- Copies the Archipelago system +- Installs the bootloader +- Pre-loads container images for offline app installation + +**Duration**: 5-15 minutes depending on hardware speed. + +### Step 5: First Boot + +> **Screenshot**: Console showing systemd services starting — archipelago.service, nginx, podman. + +1. Remove the USB drive when prompted +2. The system reboots into Archipelago +3. Services start automatically (takes 30-60 seconds) +4. If a monitor is connected, the kiosk mode launches showing the web UI + +--- + +## Part 3: First-Time Setup (Onboarding) + +### Step 6: Connect to the Web UI + +> **Screenshot**: Browser address bar showing `http://192.168.1.x` with the Archipelago splash screen loading. + +1. Find your server's IP address: + - Check your router's DHCP client list + - Or connect a monitor — the IP is shown on the kiosk display +2. Open a browser on any device on the same network +3. Navigate to `http://` +4. The splash screen plays the Archipelago intro animation + +### Step 7: Tap to Start + +> **Screenshot**: The splash screen with "Tap anywhere to begin" text and cosmic background animation. + +1. The intro screen shows the Archipelago logo with atmospheric music +2. Tap or click anywhere to proceed +3. A typing animation welcomes you: "Welcome, Noderunner" + +### Step 8: Login Screen + +> **Screenshot**: The login screen with a password field and glass-morphism design. + +1. Enter the default password: `password123` +2. Click "Login" +3. You'll be prompted to change this password immediately + +### Step 9: Choose Your Path (Onboarding) + +> **Screenshot**: The onboarding path selection screen showing three options: Bitcoin Node, Home Server, Full Sovereignty. + +The onboarding wizard guides you through setup: + +1. **Choose your path**: + - **Bitcoin Node**: Bitcoin Knots + LND + Mempool (focused) + - **Home Server**: Bitcoin + Home Assistant + File Manager (balanced) + - **Full Sovereignty**: Everything — Bitcoin, Lightning, Nostr, VPN, Cloud (maximum) + +2. **Create your identity**: + > **Screenshot**: DID creation screen showing the generated decentralized identifier. + + - A DID (Decentralized Identifier) is generated for your node + - This is your sovereign digital identity — no third party needed + +3. **Backup your seed**: + > **Screenshot**: Seed phrase display with 12 words and a "I've saved this" checkbox. + + - Write down or save your backup passphrase + - This is the only way to recover your node if hardware fails + - Store it securely offline + +4. **Verify your backup**: + > **Screenshot**: Verification screen asking to confirm specific words from the backup. + + - Confirm you've saved your backup by entering requested words + +5. **Setup complete**: + > **Screenshot**: Completion screen with confetti animation and "Enter your node" button. + + - Click to enter the dashboard + +--- + +## Part 4: The Dashboard (Daily Use) + +### Step 10: Home Screen + +> **Screenshot**: The Archipelago dashboard with glass-card layout — system status, Bitcoin sync progress, quick actions. + +The home screen shows: +- **System status**: CPU, RAM, disk usage, uptime +- **Bitcoin sync progress**: Block height, peer count, sync percentage +- **Quick actions**: Start/stop apps, check notifications +- **Node identity**: Your DID and Nostr public key + +### Step 11: My Apps + +> **Screenshot**: The Apps page showing installed containers as glass cards — Bitcoin Knots (running), LND (running), Mempool (stopped). + +- View all installed applications +- **Green dot**: Running +- **Red dot**: Stopped +- Click an app to see details, logs, and actions +- Start/stop apps with one click + +### Step 12: App Details + +> **Screenshot**: Bitcoin Knots detail page showing sync status, peer count, block height, and action buttons. + +Each app detail page shows: +- Container status and health +- Live logs (scrollable) +- Start / Stop / Restart buttons +- Launch button (opens the app's own UI in a new tab) +- Resource usage + +### Step 13: Marketplace + +> **Screenshot**: The Marketplace page with curated app cards — each showing name, description, and install button. + +- Browse available applications +- Install with one click +- Apps are verified containers with security hardening +- Categories: Bitcoin, Lightning, Home, Nostr, Other + +### Step 14: Cloud (File Manager) + +> **Screenshot**: The Cloud page showing folders (Documents, Photos, Music) with breadcrumb navigation. + +- Browse files stored on your node +- Upload and download files +- Organized with breadcrumb navigation +- Files are stored locally — not in the cloud + +### Step 15: Server Status + +> **Screenshot**: The Server page showing CPU/RAM/Disk gauges, Tor status, and network information. + +- Real-time system metrics +- Tor connectivity status and .onion address +- DNS configuration +- VPN status +- Federation peers (if configured) + +### Step 16: Web5 Identity + +> **Screenshot**: The Web5 page showing DID document, Nostr public key, and credential management. + +- View your decentralized identity (DID) +- Manage verifiable credentials +- Publish your identity to Nostr relays +- Create and verify presentations + +### Step 17: Settings + +> **Screenshot**: The Settings page with sections for password, appearance, system update, and shutdown. + +- Change password +- Configure TOTP two-factor authentication +- Check for system updates +- Restart or shutdown the server +- Reset onboarding (for testing) + +--- + +## Part 5: Advanced Operations + +### Accessing via Tor + +> **Screenshot**: Browser showing the .onion address in the Tor Browser URL bar. + +1. Install [Tor Browser](https://torproject.org) +2. Find your .onion address in Settings > Server +3. Access your node from anywhere in the world via Tor + +### Federation (Multi-Node) + +> **Screenshot**: Federation page showing connected peer nodes with status indicators. + +1. Generate an invite code from Server > Federation +2. Share the code with a trusted peer +3. They join using the code on their node +4. Monitor peer status and deploy apps remotely + +### Hardware Wallet Integration + +> **Screenshot**: PSBT signing flow — creating a transaction, scanning QR with hardware wallet. + +1. Create a PSBT (Partially Signed Bitcoin Transaction) from Web5 +2. Transfer to your hardware wallet (QR code or file) +3. Sign on the hardware wallet +4. Import the signed PSBT back to finalize and broadcast + +### Controller / Gamepad Navigation + +> **Screenshot**: Dashboard with visible focus indicators showing controller navigation in action. + +Archipelago supports Xbox-style controller navigation: +- **D-pad / Arrow keys**: Navigate between elements +- **A / Enter**: Select / activate +- **B / Escape**: Go back +- **Bumpers**: Switch between pages +- Focus indicators show the current selection + +--- + +## Part 6: Maintenance + +### Regular Tasks + +| Task | Frequency | How | +|------|-----------|-----| +| Check for updates | Weekly | Settings > System Update | +| Review app health | Daily (glance) | Home screen status cards | +| Backup | Monthly | Settings > Backup | +| Check disk space | Monthly | Server status page | + +### Updating Archipelago + +1. Go to Settings > System Update +2. Click "Check for Updates" +3. If available, click "Install Update" +4. The system restarts automatically — do not power off during update + +### Creating a Backup + +1. Go to Settings > Backup +2. Enter a passphrase (remember this!) +3. Click "Create Backup" +4. Download the backup file and store it safely offline + +--- + +## Quick Reference + +| Action | Where | +|--------|-------| +| Start/stop an app | My Apps > App Card > Start/Stop | +| Install new app | Marketplace > Find App > Install | +| Check system health | Home or Server page | +| Change password | Settings > Security | +| Enable 2FA | Settings > Security > TOTP | +| View logs | My Apps > App > Logs | +| Access via Tor | Settings > Server > Tor Address | +| Restart server | Settings > System > Restart | +| Create backup | Settings > Backup | diff --git a/loop/plan.md b/loop/plan.md index f25cfe0f..5b309a80 100644 --- a/loop/plan.md +++ b/loop/plan.md @@ -386,7 +386,7 @@ - [x] **FINALDOC-01** — Write comprehensive troubleshooting guide. Create `docs/troubleshooting.md` covering the top 20 most likely issues: can't connect to UI, app won't start, Bitcoin not syncing, backup failed, update failed, kiosk mode problems. Include diagnostic commands and solutions. -- [ ] **FINALDOC-02** — Create video/screenshot walkthrough documentation. Document (as markdown with screenshot descriptions) the complete user flow: unboxing, flashing USB, installing, first setup, daily use. These become the basis for future video tutorials. +- [x] **FINALDOC-02** — Create video/screenshot walkthrough documentation. Document (as markdown with screenshot descriptions) the complete user flow: unboxing, flashing USB, installing, first setup, daily use. These become the basis for future video tutorials. - [ ] **FINALDOC-03** — Finalize all Architecture Decision Records. Review and complete all ADRs. Add new ones for Year 3 decisions. Ensure every significant technical decision is documented.