Piper Morgan Alpha Testing Guide

Version: 0.8.5 Last Updated: January 27, 2026 For: Alpha Testers

Quick Navigation

This guide has three main sections:

Section Description Start Here If…
Chapter 1: Setup Prerequisites, installation, configuration You’re setting up for the first time
Chapter 2: Testing Test scenarios, features to explore You already have an account and want to start testing
Chapter 3: Troubleshooting Common issues and solutions Something isn’t working

Already have an account? Jump directly to Chapter 2: Testing.

Chapter 1: Setup

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.5). 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.

What’s New in 0.8.5

MUX-IMPLEMENT Complete - Full accessibility and design polish:

Accessibility Improvements (#428, #429, #430):

Architecture:

What’s New in 0.8.4.3

Fresh Install Fixes - Critical fixes for new alpha testers (#605-#609):

What’s New in 0.8.4.2

Calendar Bug Fixes - Major improvements to TEMPORAL handler:

Other Fixes:

What’s New in 0.8.4.1

Bug Fixes:

Architecture Improvement:

What’s New in 0.8.4

Integration Settings (Epic #543) - All integration credentials can now be managed from Settings → Integrations:

Portfolio Onboarding (#490) - New users now experience conversational project setup:

Bug Fixes:

What’s New in 0.8.3.2

Interactive Standup Assistant - The standup feature now supports conversational interactions. Start with “let’s write a standup” or “/standup” and Piper will guide you through the process interactively:

Standup Monitoring Dashboard - Behind the scenes, all standup conversations are now tracked with structured logging for debugging and performance analysis.

Epic #242 Complete - The Interactive Standup Conversation feature (CONV-MCP-STANDUP-INTERACTIVE) is now fully implemented with:

What’s New in 0.8.3

Integration Health Dashboard - New dashboard at Settings → Integrations showing real-time status of all integrations. One-click “Test” buttons let you verify each integration is working. Visual status indicators show healthy, degraded, or failed states with helpful fix suggestions.

OAuth Connection Management - Connect and disconnect Slack and Google Calendar directly from the Settings page. No more editing environment variables - just click “Connect” and authorize through the OAuth flow. Connected integrations show account details (workspace name, email).

Notion in Setup Wizard - The setup wizard now includes Notion API key configuration. Enter your key and see immediate validation with workspace name confirmation before saving.

Stable Core Features - Setup, login, chat, lists, todos, and file management are stable. Focus your testing on the new integration features: the dashboard, OAuth connections, and Notion setup.

Bug Fixes - Calendar OAuth now works reliably (state persistence fix). Toast notifications are visible and readable (7-second duration). Breadcrumb navigation no longer overlaps.

Windows Alpha Tester Setup

Best Option: Use the Automated Setup Script

We’ve created a Windows batch file that automates the entire setup process:

REM Fast clone (~91MB instead of ~800MB) - recommended for alpha testers
git clone --depth 1 -b production https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
.\scripts\alpha-setup.bat

The script will:

Alternative: WSL2 (Windows Subsystem for Linux)

If you prefer a Linux-like environment on Windows, WSL2 provides a smooth setup experience:

# 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 (uses bash script - faster)
# --depth 1 gives you a fast ~91MB download (vs ~800MB full history)
git clone --depth 1 -b production https://github.com/mediajunkie/piper-morgan-product.git
cd piper-morgan-product
./scripts/alpha-setup.sh

Manual Setup (If You Prefer Full Control)

If you prefer not to use automated scripts, follow the guided setup below. On Windows, 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
    • IMPORTANT: Check “Add Python to PATH” during installation
    • Restart Command Prompt/PowerShell after installing
  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
  4. Docker Desktop not running: The setup script will fail if Docker Desktop isn’t running
    • Start Docker Desktop before running the setup script
    • Wait for it to fully initialize (check system tray)

Guided Setup Instructions

Step 1: Clone the Repository

# --depth 1 gives you a fast ~91MB download (vs ~800MB full history)
# You get all the code, just not the git history (which you don't need for testing)
git clone --depth 1 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: Start Server for First-Time Setup

New in 0.8.2+: Setup now uses a visual web interface by default.

python main.py
# → Opens http://localhost:8001/setup (GUI setup wizard)

The GUI setup wizard will automatically open in your browser and guide you through:

See the Setup Wizard Walkthrough section below for detailed screenshots and step-by-step guidance.

Alternative: Command-Line Setup

If you prefer the original command-line interface:

python main.py setup

This will run the CLI setup wizard with prompts in your terminal. Both methods configure the same settings - use whichever you’re comfortable with.

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.

Setup Wizard Walkthrough (New in 0.8.2)

The GUI setup wizard provides a visual, step-by-step interface for configuration. Here’s what to expect at each stage:

Step 1: Welcome Screen

Setup Wizard - Welcome

The welcome screen introduces the setup process and explains what will be configured. Click “Get Started” to begin.

Step 2: System Health Check

Setup Wizard - Health Check

Automatic validation of your system:

If any checks fail, the wizard provides specific guidance on how to fix them.

Step 3: API Key Configuration

Setup Wizard - API Keys

Configure your LLM API keys through a web form interface. This is much easier than the command-line method - you can see what you’re typing, correct mistakes easily, and get immediate validation feedback.

Supports:

You can configure one, two, or all three providers. At least one is required.

Step 4: User Account Creation

Setup Wizard - User Creation

Create your admin account:

The form provides real-time feedback on password strength and format requirements.

Step 5: Setup Complete

Setup Wizard - Success

Setup confirmation screen with:

Click the button to go to the login page and start using Piper Morgan.

Chapter 2: Testing

This chapter covers what to test and how. If you’re already set up, start here.

Test Scenarios to Try

Note for 0.8.4 Testers: Setup, login, chat, and core workflows are stable. Focus your testing on the new Integration Settings and Portfolio Onboarding and continue validating the Interactive Standup Assistant.

Priority Testing Areas

  1. Interactive Standup Assistant - Try “let’s write a standup” or “/standup” in chat
  2. Standup Conversations - Test preference gathering, refinement requests, completing standups
  3. Integration Dashboard - Settings → Integrations, test buttons, health status display
  4. OAuth Connections - Connect/disconnect Slack and Calendar from Settings
  5. Workflow Management - Lists, todos, projects (CRUD operations, sharing, permissions)

Basic Functionality Tests

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 Features

Lists, Todos, and Projects Management

Basic CRUD Operations (test these first):

  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. Edit and Delete
    • Open the list you created
    • Edit the name or description
    • Try deleting a list (should show confirmation)
  3. Repeat for Todos and Projects
    • Navigate to /todos and /projects
    • Same CRUD operations available
    • Test that all three resource types work consistently

File Management

Basic File Operations (test these first):

  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

Interactive Standup Assistant (New in 0.8.3.2)

  1. Start a Standup Conversation
    • In the chat, say “let’s write a standup” or “/standup”
    • Piper should respond with initial guidance
    • Verify conversation flow starts properly
  2. Test Preference Gathering
    • Tell Piper your preferences: “I prefer bullet points” or “keep it concise”
    • Verify Piper acknowledges and remembers your preference
    • Generate content should reflect your stated style
  3. Test Iterative Refinement
    • Ask Piper to make changes: “add more detail about the bug fix” or “make it shorter”
    • Verify Piper updates the standup accordingly
    • Previous versions should be saved for comparison
  4. Complete the Standup
    • Say “looks good, let’s use this” or “finalize”
    • Verify standup is marked complete
    • Check that performance is fast (sub-500ms responses)
  5. Edge Cases to Test
    • Abandon a standup mid-conversation (say “nevermind” or navigate away)
    • Start multiple standups in one session
    • Long conversations (10+ turns) - verify memory isn’t growing unbounded

Quick Standup Generation (Legacy)

  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

Advanced Testing (Multi-User Sharing)

Note: These features require multiple user accounts and are considered advanced. Focus on basic CRUD operations first.

Sharing Lists, Todos, and Projects

  1. Share a List
    • Open a list you created
    • Click “Share” button
    • Enter another user’s email (if multi-user testing)
    • Select role: Editor
    • Verify sharing modal shows success
  2. Test Permission Badges
    • Notice “Owner” badge on your list
    • If shared with another user, verify their role badge shows

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

Chapter 3: Troubleshooting

Troubleshooting

Setup Wizard Issues

GUI setup wizard not loading?

“Docker not installed” or “Docker not running”

The setup wizard (GUI or CLI) 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

Feature-Specific Troubleshooting

Can’t create lists/todos/projects?

Files page not loading or shows errors?

Interactive Standup issues?

Quick Standup generation hangs or fails?

Logout not working?

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.5). The GUI setup wizard handles most complexity, but you’re still testing early-stage software. Expect bugs and incomplete features.

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

Thank you for being an early adopter and helping us improve! 🚀

See Also

Last updated: January 19, 2026 Software version: 0.8.5