Piper Morgan Alpha Testing Guide

Version: 0.8.0 (First Alpha Release) Last Updated: October 24, 2025 For: Alpha Wave 2 Testers

Before You Begin - Prerequisites Checklist

Required Software:

Required Accounts & Keys:

Optional but Recommended:

Time Commitment:

Important Disclaimers - Please Read

⚠️ ALPHA SOFTWARE WARNING ⚠️

This is pre-release alpha software (version 0.8.0). By proceeding, you acknowledge:

  1. Expected Issues: Bugs, crashes, and incomplete features are normal
  2. Data Loss Risk: Your data may be lost at any time without warning
  3. No Production Use: Do NOT use for mission-critical or time-sensitive work
  4. Employer Systems: Do NOT install on employer hardware without written permission
  5. API Charges: You are responsible for all LLM API costs incurred
  6. Security: Not security audited - use test data only, no sensitive information
  7. No Warranty: Software provided “as-is” without any warranty whatsoever
  8. No Support SLA: Best-effort support only, no guaranteed response times

See ALPHA_AGREEMENT.md for complete legal terms.

Windows Alpha Tester Setup

For Windows testers, we recommend using WSL2 (Windows Subsystem for Linux).

Quick Start: Windows with WSL2

WSL2 provides the smoothest setup experience on Windows:

# 1. Run as Administrator
wsl --install
wsl --set-default-version 2
wsl --install -d Ubuntu-22.04

# 2. Inside Ubuntu terminal
sudo apt update && sudo apt upgrade -y
sudo apt install python3.11 python3.11-venv git

# 3. Clone and setup
git clone https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 4. Run setup wizard (same as below)
python main.py setup

Alternative: Native Windows Setup

If you prefer not to use WSL2, follow the guided setup below but use:

Known Windows Issues for Alpha Testers

  1. Clone failures: Ensure you have long path support enabled: 
    # Run as Administrator
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

  2. Python not found: Reinstall from https://www.python.org/downloads and check “Add Python to PATH”

  3. Path errors in commands: Use backslashes (Windows-native) or quotes with forward slashes: 
    python main.py setup              # Works on all platforms
python -c "import sys; print(sys.version)"  # Also works

Guided Setup Instructions

Step 1: Clone the Repository

git clone https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product

Note: On Windows, use the WSL2 terminal or PowerShell with proper path handling

Step 2: Create Virtual Environment

python3.12 -m venv venv
# Requires Python 3.11 or 3.12 - verify with: python --version
source venv/bin/activate  # On Windows: venv\Scripts\activate

Step 3: Install Dependencies

pip install -r requirements.txt

Step 4: Run Interactive Setup Wizard

This is the key difference from manual setup!

python main.py setup

The setup wizard will:

Expected output:

==================================================
Welcome to Piper Morgan Alpha!
==================================================

Let's get you set up (takes about 5 minutes)

1. System Check
   ✓ Docker installed
   ✓ Python 3.9+
   ✓ Port 8001 available
   ✓ Database accessible

2. User Account Setup
   Username: [you'll enter this]
   Email: [you'll enter this]
   Password: [secure, hidden input - min 8 chars]
   Confirm password: [must match]
   ✓ Password set securely
   ✓ Account created

3. API Key Configuration
   [Guided prompts for OpenAI/Anthropic keys]
   ✓ API keys validated and stored

✅ Setup Complete!

Step 5: Configure Your Preferences

After setup, personalize your experience:

python main.py preferences

This 2-minute questionnaire configures:

Step 6: Verify Installation

python main.py status

You should see:

==================================================
Piper Morgan System Status
==================================================

Database:
  ✓ PostgreSQL connected
     Users: 1, Size: 15.2 MB

API Keys:
User: [your-username]
  ✓ openai: Valid
  ✓ anthropic: Valid (or ○ Not configured)

Performance:
  ✓ Database response: 12ms

Recommendations:
  ✓ All systems operational!

Step 7: First Run

python main.py

The server will start and automatically open http://localhost:8001 in your browser.

Login with your credentials:

After login, you’ll see the Piper Morgan chat interface.

Test Scenarios to Try

Start with these simple tests to verify everything works:

  1. Basic Chat: “Hello, what can you help me with?”
  2. Task Creation: “Add a todo: Review Q3 metrics”
  3. Information Query: “What tasks do I have?”
  4. File Upload: Upload a PDF or DOCX file (max 10MB) and ask for analysis
  5. Document Summary: “Summarize the document I just uploaded”
  6. Preference Check: “How do you prefer to communicate?” (should reflect your settings)
  7. Multi-User Test: If testing with others, verify you can’t see their data

Exploring Piper’s New Features (Nov 22-23, 2025)

Lists, Todos, and Projects Management

  1. Create a List
    • Navigate to http://localhost:8001/lists
    • Click “Create New List” button
    • Enter name: “Alpha Testing Tasks”
    • Enter description: “Testing the Lists feature”
    • Verify list appears in the list view
  2. Share a List
    • Open the list you just created
    • Click “Share” button
    • Enter another user’s email (if multi-user testing)
    • Select role: Editor
    • Verify sharing modal shows success
  3. Test Permission Badges
    • Notice “Owner” badge on your list
    • If shared with another user, verify their role badge shows
  4. Repeat for Todos and Projects
    • Navigate to /todos and /projects
    • Same CRUD operations available
    • Test that all three resource types work consistently

File Management

  1. Upload a File
    • Navigate to http://localhost:8001/files
    • Click “Upload File” or drag-and-drop a file
    • Supported formats: PDF, DOCX, TXT, MD, JSON (max 10MB)
    • Verify file appears in file list with correct metadata
  2. Download a File
    • Click “Download” button on uploaded file
    • Verify file downloads correctly
  3. Delete a File
    • Click “Delete” button on a file
    • Verify file is removed from list
  4. Test File Privacy
    • Files are owner-based (private to you)
    • Other users should NOT see your files

Permission System

  1. Conversational Permission Commands Try these in the chat interface:
    • “share my Alpha Testing Tasks list with [email] as editor”
    • “who can access my Alpha Testing Tasks?”
    • “show me shared lists”
    • “give [email] viewer access to my project plan”
  2. Role-Based Access Testing (requires 2 users)
    • Create a list as User A
    • Share with User B as “Viewer”
    • Log in as User B
    • Verify: Can view list but NOT edit/delete
    • Share same list with User C as “Editor”
    • Log in as User C
    • Verify: CAN edit and update list

Standup Generation

  1. Generate a Standup
    • Navigate to http://localhost:8001/standup
    • Click “Generate Standup” button
    • Wait 2-3 seconds for AI generation
    • Verify standup report appears with meaningful content
    • Note: First standup may be generic if no prior activity
  2. Test with Activity
    • Create some lists, todos, upload files
    • Generate standup again
    • Verify it reflects your recent activity

Authentication & Logout

  1. Test Logout
    • Click user menu (top right corner of page)
    • Click “Logout” button
    • Verify you’re redirected to login page
    • Verify session is cleared (can’t access /lists without login)
  2. Test Login After Logout
    • Enter your credentials on login page
    • Verify you can log back in
    • Verify your data is still there (lists, files, etc.)

Navigation & Polish

  1. Test Breadcrumbs
    • Navigate to /lists, /todos, /projects, /files, /standup
    • Verify each page shows breadcrumb: Home › [Page Name]
    • Click “Home” in breadcrumb, verify navigation works
  2. Test Page Consistency
    • Check that Settings pages are on unified grid
    • Verify no “My Lists” prefix (should just be “Lists”)
    • Check that Integrations page shows placeholder (not 404)
    • Check Privacy & Data settings has informative content

Troubleshooting

Setup Wizard Issues

“Docker not installed” or “Docker not running”

The setup wizard will guide you through Docker installation with platform-specific instructions. If you encounter issues:

“Python 3.9+ not found”

“Port 8001 not available”

“Database not accessible”

Runtime Issues

“No LLM provider configured”

High API costs

Preference changes not taking effect

Login issues

File upload issues

New Features Troubleshooting (Nov 22-23, 2025)

Can’t create lists/todos?

Files page shows “coming soon”?

Standup button hangs or does nothing?

Can’t log out?

Permission sharing not working?

Providing Feedback

We need your feedback to improve! Please report:

What to Report

How to Report

  1. GitHub Issues: Preferred for bugs (if comfortable with GitHub)
  2. Email: christian@[domain] for private feedback
  3. Weekly Check-in: Optional 15-minute calls available

Helpful Feedback Format

SETUP METHOD: [wizard/manual]
WHAT I TRIED: [specific action]
WHAT I EXPECTED: [expected result]
WHAT HAPPENED: [actual result]
ERROR MESSAGE: [if any]
SYSTEM STATUS: [output of `python main.py status`]
SEVERITY: [blocker/major/minor]

Privacy & Data Collection

Advanced: Manual Setup (If Wizard Fails)

If the setup wizard fails, you can fall back to manual configuration:

  1. Environment Variables: Copy .env.example to .env and edit
  2. Database: Run docker-compose up -d db
  3. API Keys: Manually add to .env file
  4. Database Migration: Run database setup scripts

See original testing guide for detailed manual steps.

Questions?

Remember: This is alpha software (version 0.8.0) with a guided setup experience. The wizard handles most complexity, but you’re still testing early prototype software.

If guided setup seems overwhelming, a hosted version is planned for 2026.

Thank you for being an early adopter and helping us perfect the onboarding experience! 🚀

See Also

Last updated: November 23, 2025 Software version: 0.8.0 Guide version: 2.2 (Nov 22-23 Features + Testing Scenarios)