### Getting Started with RUNSTR

Source: https://github.com/healthnotelabs/runstr/blob/main/README.md

Instructions to clone the repository, install dependencies, and run the development server for the RUNSTR application. It also includes commands to sync with Android and launch Android Studio.

```bash
git clone https://github.com/TheWildHustle/Nostr-Run-Club.git
npm install
npm run dev
npx cap sync android
npx cap open android
```

--------------------------------

### Environment Example

Source: https://github.com/healthnotelabs/runstr/blob/main/tmpfiles.txt

An example file related to environment configuration.

```md
.env.example
```

--------------------------------

### Setup Tests

Source: https://github.com/healthnotelabs/runstr/blob/main/tmpfiles.txt

General setup or configuration tests for the testing environment.

```javascript
src/tests/setup.js
```

--------------------------------

### NDK Integration and Setup

Source: https://github.com/healthnotelabs/runstr/blob/main/fully-functional-NIP60.md

Handles the integration and setup of the NDK (Nostr Development Kit), enabling communication and interaction with the Nostr network.

```javascript
✅ NDK integration and setup
```

--------------------------------

### README Files

Source: https://github.com/healthnotelabs/runstr/blob/main/tmpfiles.txt

Various README files providing project information, setup instructions, and changelogs.

```md
ANDROID.md
```

```md
CHANGELOG.md
```

```md
DEBUG-EMPTY-FEED.md
```

```md
LICENSE
```

```md
NOSTR-TOOLS-MIGRATION.md
```

```md
README-NIP29-CHANGES.md
```

```md
README-NIP29.md
```

```md
README-RUN-CLUB.md
```

```md
README-task-master.md
```

```md
README.md
```

```md
TEST-README.md
```

--------------------------------

### Recommended Starting Order for Implementation

Source: https://github.com/healthnotelabs/runstr/blob/main/stats-ui-improvements.md

Provides a prioritized order for tackling implementation tasks, starting with quick wins and progressing to complex features.

```plaintext
1. Text changes and removals (Tasks 1-5)
2. Navigation routing updates (Task 6)
3. Blossom improvements (Tasks 7-8)
4. Complex functionality (Tasks 9-10)
```

--------------------------------

### Project Initialization

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Commands to initialize a new Task Master project, either when installed globally or locally.

```bash
# If installed globally
task-master init

# If installed locally
npx task-master-init
```

--------------------------------

### Install react-hot-toast

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

Installs the react-hot-toast library, a lightweight and dependency-free toast notification system, into the project's dependencies.

```shell
npm install react-hot-toast
# or
yarn add react-hot-toast
```

--------------------------------

### Listing Tasks with Options

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/README.md

Provides examples of how to use the `list` command to display tasks. It shows how to filter by status and include subtask details in the output.

```bash
# List all tasks
task-master list

# List tasks with a specific status
task-master list --status=pending

# List tasks and include their subtasks
task-master list --with-subtasks

# List tasks with a specific status and include their subtasks
task-master list --status=pending --with-subtasks
```

--------------------------------

### Install Dependencies and Build for Android

Source: https://github.com/healthnotelabs/runstr/blob/main/ANDROID.md

Commands to install project dependencies and build the RUNSTR application for Android.

```bash
npm install
npm run build:android
```

--------------------------------

### Example Cursor AI Interactions

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Provides example prompts for interacting with the Cursor AI agent for various development workflows, including project initialization, task management, implementation assistance, subtask handling, managing changes, completing work, and analyzing task complexity.

```bash
# Starting a new project
I've just initialized a new project with Claude Task Master. I have a PRD at scripts/prd.txt.
Can you help me parse it and set up the initial tasks?

# Working on tasks
What's the next task I should work on? Please consider dependencies and priorities.

# Implementing a specific task
I'd like to implement task 4. Can you help me understand what needs to be done and how to approach it?

# Managing subtasks
I need to regenerate the subtasks for task 3 with a different approach. Can you help me clear and regenerate them?

# Handling changes
We've decided to use MongoDB instead of PostgreSQL. Can you update all future tasks to reflect this change?

# Completing work
I've finished implementing the authentication system described in task 2. All tests are passing.
Please mark it as complete and tell me what I should work on next.

# Analyzing complexity
Can you analyze the complexity of our tasks to help me understand which ones need to be broken down further?

# Viewing complexity report
Can you show me the complexity report in a more readable format?
```

--------------------------------

### Global Installation

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Commands for installing the Task Master CLI tool globally or locally within a project using npm.

```bash
# Install globally
npm install -g task-master-ai

# OR install locally within your project
npm install task-master-ai
```

--------------------------------

### Meta-Development Script CLI Usage

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/README.md

Demonstrates how to execute the meta-development script commands, either globally installed or locally within the project. It lists the available commands for managing development tasks.

```bash
# If installed globally
task-master [command] [options]

# If using locally within the project
node scripts/dev.js [command] [options]

# To see detailed usage information
task-master --help
node scripts/dev.js --help
```

--------------------------------

### NDK Wallet Package Installation

Source: https://github.com/healthnotelabs/runstr/blob/main/ecash-implementation.md

Details the installation of the `@nostr-dev-kit/ndk-wallet` package, which provides essential classes for NDKCashuWallet and NDTNutzapMonitor functionality.

```bash
npm install @nostr-dev-kit/ndk-wallet
```

--------------------------------

### Endpoint Discovery for Blossom Servers

Source: https://github.com/healthnotelabs/runstr/blob/main/memory-bank/blossom-music-integration.md

Provides example code for discovering endpoints on Blossom servers, covering both subdomain and direct domain patterns. It lists potential URLs to try for fetching data.

```javascript
// For blossom.band (subdomain pattern)
endpoints = [
  `https://${npub}.blossom.band/list/${pubkey}`,
  `https://blossom.band/list/${pubkey}`,
  `https://blossom.band/api/list/${pubkey}`
];

// For cdn.satellite.earth (direct pattern)  
endpoints = [
  `https://cdn.satellite.earth/list/${pubkey}`,
  `https://cdn.satellite.earth/api/list/${pubkey}`
];
```

--------------------------------

### Gradual Migration Phases

Source: https://github.com/healthnotelabs/runstr/blob/main/NIP60-Ecash-Wallet-Brainstorm.md

Outlines a three-phase approach for gradually migrating from NWC to Cashu wallets, starting with a dual-wallet UI and eventually transitioning to Cashu-only.

```plaintext
Phase 1:     [NWC] + [Cashu] (dual wallet UI)
Phase 2:     [Cashu] primary, [NWC] optional
Phase 3:     [Cashu] only
```

--------------------------------

### Initial Task Generation from PRD

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Guides on how to use Cursor's AI chat to generate tasks from a Product Requirements Document (PRD) using the task-master parse-prd command.

```bash
Please use the task-master parse-prd command to generate tasks from my PRD. The PRD is located at scripts/prd.txt.
```

```bash
task-master parse-prd scripts/prd.txt
```

--------------------------------

### Task Master MCP Setup in Cursor

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Instructions for configuring the Task Master MCP server within Cursor settings to enable integrated task management.

```APIDOC
Cursor Settings:
  MCP Section:
    Add New MCP Server:
      Name: "Task Master"
      Type: "Command"
      Command: "npx -y task-master-mcp"
```

--------------------------------

### Updating Tasks with a Prompt

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/README.md

Demonstrates the usage of the `update` command to modify tasks. It shows how to specify a starting task ID and provide a prompt for the update, affecting subsequent tasks.

```bash
# Update tasks starting from ID 4 with a new prompt
task-master update --from=4 --prompt="Refactor tasks from ID 4 onward to use Express instead of Fastify"

# Update all tasks (default from=1)
task-master update --prompt="Add authentication to all relevant tasks"
```

--------------------------------

### Competition Configuration

Source: https://github.com/healthnotelabs/runstr/blob/main/RUNSTR_SEASON_1.md

Defines the configuration parameters for Season 1 of the RUNSTR competition, including pricing, start and end times, and the season title.

```typescript
SEASON_1: {
  passPrice: 10000, // sats
  startUtc: '2025-07-11T00:00:00Z',
  endUtc: '2025-09-11T23:59:59Z',
  title: 'RUNSTR SEASON 1'
}
```

--------------------------------

### Efficient Theme Switching with React Context

Source: https://github.com/healthnotelabs/runstr/blob/main/Design_overhaul.md

An example of an efficient theme switching mechanism using React Context, including initialization from localStorage or system preferences, handling system preference changes, and applying the theme to the document.

```javascript
// Example: Efficient theme switching
const ThemeProvider = ({ children }) => {
  const [theme, setTheme] = useState(() => {
    // Initialize from localStorage or system preference
    return localStorage.getItem('theme') || 
           (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
  });

  useEffect(() => {
    const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
    const handleChange = (e) => {
      if (!localStorage.getItem('theme')) {
        setTheme(e.matches ? 'dark' : 'light');
      }
    };

    mediaQuery.addEventListener('change', handleChange);
    return () => mediaQuery.removeEventListener('change', handleChange);
  }, []);

  // Apply theme to document
  useEffect(() => {
    document.documentElement.setAttribute('data-theme', theme);
    localStorage.setItem('theme', theme);
  }, [theme]);

  return (
    <ThemeContext.Provider value={{ theme, toggleTheme: () => setTheme(t => t === 'light' ? 'dark' : 'light') }}>
      {children}
    </ThemeContext.Provider>
  );
};

```

--------------------------------

### Nostr API - Fetching User Profiles

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

Demonstrates how to fetch user profiles using the Nostr Development Kit (NDK). This involves creating NDKUser objects for the desired public keys and then using `ndk.fetchProfiles()` to retrieve their profile metadata. The profiles can include name, picture, and other details.

```APIDOC
NDK.getUser(pubkey: string): NDKUser
  - Creates an NDKUser object for a given public key.

NDK.fetchProfiles(users: NDKUser[]): Promise<NostrProfile[]>
  - Fetches profile metadata for an array of NDKUser objects.
  - Parameters:
    - users: An array of NDKUser objects for whom to fetch profiles.
  - Returns:
    - A Promise that resolves to an array of NostrProfile objects.
    - Each NostrProfile object may contain properties like 'name', 'picture', 'about', etc.
  - Example Usage:
    ```typescript
    import NDK, { NDKUser } from '@nostr-dev-kit/ndk';

    const ndk = new NDK();
    await ndk.connect();

    const user1 = ndk.getUser({ pubkey: 'pubkey1...' });
    const user2 = ndk.getUser({ pubkey: 'pubkey2...' });

    const profiles = await ndk.fetchProfiles([user1, user2]);
    console.log(profiles);
    ```
  - Related Methods:
    - `NDK.getUser()`: To create NDKUser objects.
    - `NDKUser.fetchProfile()`: To fetch a single profile.
  - Error Conditions:
    - Network errors during fetching.
    - Invalid public keys.
```

--------------------------------

### getChallengeStatus Helper Function

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

A utility function that determines the status of a challenge ('Upcoming', 'Active', or 'Completed') based on its start and end timestamps relative to the current time. This is used to visually indicate the challenge's state in the UI.

```typescript
interface Challenge {
  start: number; // Unix timestamp
  end: number;   // Unix timestamp
}

function getChallengeStatus(challenge: Challenge): 'Upcoming' | 'Active' | 'Completed' {
  const now = Math.floor(Date.now() / 1000);

  if (now < challenge.start) {
    return 'Upcoming';
  } else if (now >= challenge.start && now <= challenge.end) {
    return 'Active';
  } else {
    return 'Completed';
  }
}
```

--------------------------------

### Replace Alerts with Toast Notifications

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

Replaces traditional JavaScript alert() calls with non-blocking toast notifications using the react-hot-toast library for a better mobile-wrapped application experience. This involves installing the library, adding a provider, and updating specific alert calls to toast equivalents.

```typescript
import toast from 'react-hot-toast';

// In TeamDetailPage.tsx
const handleJoinTeam = async () => {
  try {
    // ... join team logic ...
    toast.success('Successfully joined team!');
  } catch (err) {
    toast.error(err.message);
  }
};

// In TeamChallengesTab.tsx
const handleCreate = async () => {
  try {
    // ... create challenge logic ...
    toast.success('Challenge published!');
  } catch (err) {
    toast.error('Error creating challenge');
  }
};
```

```javascript
// Add the Toaster component in your main application layout file (e.g., App.tsx)
import { Toaster } from 'react-hot-toast';

function App() {
  return (
    <div>
      {/* ... other components ... */}
      <Toaster />
    </div>
  );
}
```

--------------------------------

### Button Component Usage Examples

Source: https://github.com/healthnotelabs/runstr/blob/main/design-progress.md

Examples of how the Button component is used with different variants and sizes for various actions like reloading, retrying, diagnosing, and navigation. These examples demonstrate the standardization of button styling for specific functionalities.

```jsx
Button variant="ghost" size="sm" // For clean, subtle actions like reload or navigation
Button variant="outline" // For primary retry actions or manual refresh
Button variant="secondary" // For secondary diagnostic actions
Button variant="outline" size="default" // For error recovery actions
```

--------------------------------

### Creating and Publishing Events: NDK vs. nostr-tools

Source: https://github.com/healthnotelabs/runstr/blob/main/NOSTR-TOOLS-MIGRATION.md

Shows how to create, sign, and publish Nostr events using both the NDK library and nostr-tools, including integration with NIP-07 for signing.

```javascript
// Old NDK approach
const event = new NDKEvent(ndk);
event.kind = 1;
event.content = "Hello Nostr!";
event.tags = [["t", "running"]];
await event.sign();
await event.publish();

// New nostr-tools approach
// Using NIP-07 browser extension
const event = {
  kind: 1,
  created_at: Math.floor(Date.now() / 1000),
  content: "Hello Nostr!",
  tags: [["t", "running"]],
  pubkey: await window.nostr.getPublicKey()
};

const signedEvent = await window.nostr.signEvent(event);
await pool.publish(relays, signedEvent);
```

--------------------------------

### Development Workflow Commands

Source: https://github.com/healthnotelabs/runstr/blob/main/Development_Framework.md

Common commands for developing, building, and deploying the RUNSTR application.

```bash
npm run dev
npm run build
npm run build:android
npm run android
```

--------------------------------

### Relay Pool Management with nostr-tools

Source: https://github.com/healthnotelabs/runstr/blob/main/NOSTR-TOOLS-MIGRATION.md

Demonstrates how to create a SimplePool instance and define a list of relays to connect to using the nostr-tools library.

```javascript
import { SimplePool } from 'nostr-tools';

// Create a relay pool
const pool = new SimplePool();

// List of relays to connect to
const relays = [
  'wss://relay.damus.io',
  'wss://relay.nostr.band',
  'wss://nostr-pub.wellorder.net',
  'wss://relay.current.fyi',
  'wss://nos.lol',
  'wss://relay.snort.social'
];
```

--------------------------------

### XP Award Examples

Source: https://github.com/healthnotelabs/runstr/blob/main/level_system.md

Examples demonstrating how XP (Experience Points) are awarded based on different workout activities and distances. This includes base XP and bonus XP for exceeding certain thresholds.

```APIDOC
XP Award Examples:

- 1.2 mile run: 10 XP (base)
- 3.5 mile cycle: 10 + (2 * 5) = 20 XP
- 5.8 mile walk: 10 + (4 * 5) = 30 XP
- 0.8 mile jog: 0 XP (below threshold)
```

--------------------------------

### Project Structure Overview

Source: https://github.com/healthnotelabs/runstr/blob/main/Development_Framework.md

Illustrates the typical directory structure for the RUNSTR project, organizing components, contexts, hooks, services, pages, and assets.

```bash
src/
├── components/     # Reusable UI components
├── contexts/       # React Context providers
├── hooks/          # Custom React hooks
├── services/       # Business logic and API services
├── pages/          # Route components
└── assets/         # Static assets and styles
```

--------------------------------

### RUNSTR Season 1 Production Readiness Summary

Source: https://github.com/healthnotelabs/runstr/blob/main/RUNSTR_SEASON_1.md

Confirms that RUNSTR Season 1 is production-ready, highlighting key completed implementation phases and supported features.

```plaintext
READY FOR LAUNCH 🚀

RUNSTR SEASON 1 is production-ready! All 10 implementation phases completed successfully. The system now supports:

- Paid Competition: Lightning payment season pass system
- Fair Play: Individual payment date tracking
- Great UX: Progressive loading and real-time feedback  
- Multi-Activity: Running, Walking, and Cycling support
- Performance: Optimized for many participants
- Production Quality: Clean, error-handled, cached code

Next Steps: Deploy to production and announce RUNSTR SEASON 1! 🏃‍♀️⚡
```

--------------------------------

### Enhanced Tag Structure Examples

Source: https://github.com/healthnotelabs/runstr/blob/main/TEAMS_IMPLEMENTATION_SUMMARY.md

This snippet provides examples of the enhanced tag structures used for team and challenge association in the project. It illustrates the different types of tags, including team info, UUIDs, member verification, and challenge names.

```json
[
  "team", 
  "33404:captain:uuid", 
  "relayHint", 
  "teamName"
] // Full team info

[
  "team_uuid", 
  "teamUUID"
] // Direct UUID for filtering

[
  "team_member", 
  "userPubkey"
] // Member verification

[
  "t", 
  "challenge:uuid"
] // Hashtag for discovery

[
  "challenge_uuid", 
  "challengeUUID"
] // Direct UUID for filtering

[
  "challenge_name", 
  "uuid", 
  "challengeName"
] // Name mapping
```

--------------------------------

### Enhanced Receive Experience

Source: https://github.com/healthnotelabs/runstr/blob/main/ecash-implementation.md

Provides shareable URL generation (including nostr: URLs) for easier token requests and multiple copy-to-clipboard options for pubkey, mint, and share URL.

```javascript
function generateShareUrl(pubkey, mintUrl) {
  return `nostr:${pubkey}?relay=${mintUrl}`;
}

function copyToClipboard(text) {
  navigator.clipboard.writeText(text).then(() => {
    console.log('Copied to clipboard');
  }).catch(err => {
    console.error('Failed to copy:', err);
  });
}
```

--------------------------------

### NIP60 Implementation Highlights

Source: https://github.com/healthnotelabs/runstr/blob/main/ecash-implementation.md

Summarizes the key aspects of the NIP60 implementation, including real minting/receiving, Nostr integration, cross-device sync, fallback mechanisms, and transaction management.

```APIDOC
NIP60 Implementation:
  - Real cashu token minting and receiving: Utilizes NDKCashuWallet for actual token operations.
  - Full Nostr social integration: Processes tokens from DMs (kind 4) and nutzaps (kind 9321).
  - Cross-device sync: Achieved through detection of Nostr events.
  - Graceful fallback: Supports simulation for development/testing environments.
  - Production-ready UI/UX: Includes mobile support and responsive design.
  - Comprehensive transaction management: Records all transactions with success indicators.
```

--------------------------------

### Settings.jsx Typography Conversion

Source: https://github.com/healthnotelabs/runstr/blob/main/design-progress.md

Example of converting headings in `Settings.jsx` to use semantic typography classes.

```javascript
// Assuming a heading element like <h1> or <h2>
<h1 className="page-title">Settings</h1>
```

--------------------------------

### Profile.jsx Typography Conversion

Source: https://github.com/healthnotelabs/runstr/blob/main/design-progress.md

Example of converting the main heading to `page-title` and supporting text to `secondary-text` in `Profile.jsx`.

```javascript
// Assuming a main heading and supporting text
<h1 className="page-title">User Profile</h1>
<p className="secondary-text">Details about the user.</p>
```

--------------------------------

### App Integration - Scheduler Start/Stop

Source: https://github.com/healthnotelabs/runstr/blob/main/rewards-memory.md

Manages the starting and stopping of the scheduler service within the application lifecycle.

```javascript
// In src/App.jsx
startScheduler()
stopScheduler()
```

--------------------------------

### Troubleshooting `task-master init`

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Provides alternative methods to run the `task-master init` script if it fails to respond, by executing it directly using Node.js from the local `node_modules` or after cloning the repository.

```bash
# Run init script directly from node_modules
node node_modules/claude-task-master/scripts/init.js

# Or, after cloning the repository
git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js
```

--------------------------------

### Core Wallet Implementation

Source: https://github.com/healthnotelabs/runstr/blob/main/fully-functional-NIP60.md

Provides the complete implementation for the ecash wallet, handling core logic for token creation, delivery, and management.

```jsx
✅ `src/components/EcashWalletConnector.jsx` - Full wallet implementation
```

--------------------------------

### Configuration Files

Source: https://github.com/healthnotelabs/runstr/blob/main/tmpfiles.txt

Configuration files for various tools and project settings.

```md
.hintrc
```

```md
.prettierrc.json
```

```md
.releaserc.json
```

```md
.windsurfrules
```

--------------------------------

### Connecting a Wallet (Discovery)

Source: https://github.com/healthnotelabs/runstr/blob/main/NIP60-Ecash-Wallet-Brainstorm.md

Compares the current approach of using a wallet service's connect method with a simplified event-driven approach that queries Nostr for wallet events.

```javascript
Current:  wallet.connect() → Complex connection logic
Simple:   queryWalletEvents(userPubkey) → [kind:17375, kind:10019 events]
```

--------------------------------

### Enhanced Logging for Debugging

Source: https://github.com/healthnotelabs/runstr/blob/main/memory-bank/blossom-music-integration.md

Provides example console logs to aid in debugging Blossom server interactions, capturing endpoint, authentication, and response details.

```javascript
console.log('🌸 Testing endpoint:', endpoint);
console.log('🌸 Auth header:', authHeader ? 'Present' : 'Missing');
console.log('🌸 Response status:', response.status);
console.log('🌸 Response headers:', response.headers);
console.log('🌸 Response body:', await response.text());
```

--------------------------------

### NDK Singleton Initialization and Connection Logic

Source: https://github.com/healthnotelabs/runstr/blob/main/bugfixes2.md

This snippet details the core logic within `ndkSingleton.js` responsible for initializing the NDK instance and managing its connection status. It highlights the use of `explicitRelayUrls` and the `ndkReadyPromise` which reflects the success of the `ndk.connect()` operation. This is crucial for understanding why the NDK might not be reporting as ready.

```JavaScript
import { NDK } from '@nostr-dev-kit/ndk';
import { explicitRelayUrls } from '../config/relays';

const ndk = new NDK({ explicitRelayUrls });
let ndkReadyPromise = ndk.connect();

// ... other logic ...

export const getNdk = async () => {
  await ndkReadyPromise;
  return ndk;
};

// Logging added for debugging:
console.log('NDK initialized with relays:', explicitRelayUrls);
ndkReadyPromise.then(() => console.log('NDK connected successfully'))
              .catch((error) => console.error('NDK connection failed:', error));

```

--------------------------------

### Update Tasks

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Updates tasks starting from a specified ID and provides context through a prompt. This is useful for batch updates or when providing additional information for task modifications.

```bash
task-master update --from=<id> --prompt="<prompt>"
```

--------------------------------

### Global Theming Approach Options

Source: https://github.com/healthnotelabs/runstr/blob/main/stats-ui-improvements.md

Outlines two strategies for global theming, with a note on assessing current CSS architecture.

```plaintext
Option A: Implement global design system/theme variables
Option B: Page-by-page color updates if global theming is complex
```

--------------------------------

### Technical Implementation Priorities - Phased Rollout

Source: https://github.com/healthnotelabs/runstr/blob/main/Teams_Implementation.md

Outlines the phased approach for technical implementation, starting with core team functionality and progressing through membership systems, events/challenges, and monetization.

```APIDOC
Development Phases:

Phase 1: Core Team Functionality
  1. Fix team detail page loading.
  2. Build team homepage dashboard.
  3. Implement member list display.
  4. Add captain message/pinning system.

Phase 2: Membership System
  1. Design join/leave team flow.
  2. Update 1301 records with team affiliation.
  3. Implement membership tracking.
  4. Build member management for captains.

Phase 3: Events & Challenges
  1. Design event creation system.
  2. Build challenge creation system.
  3. Implement participation tracking.
  4. Create filtered feeds for events/challenges.

Phase 4: Monetization
  1. Integrate Lightning payments.
  2. Implement subscription management.
  3. Build revenue sharing system.
  4. Create badge/status system.
```

--------------------------------

### Nostr Authentication (NIP-98) Example

Source: https://github.com/healthnotelabs/runstr/blob/main/memory-bank/blossom-music-integration.md

Illustrates how to use NIP-98 for Nostr authentication, typically involving generating and sending a signed event or token as part of an HTTP request header.

```javascript
// Assuming 'nostrTools' or similar library is available
// and 'getSignedNostrEvent' function is defined elsewhere

async function authenticateRequest(url) {
  const event = { /* ... Nostr event object ... */ };
  const signedEvent = await getSignedNostrEvent(event);
  
  return fetch(url, {
    method: 'GET',
    headers: {
      'Authorization': `Nostr ${JSON.stringify(signedEvent)}`
    }
  });
}
```

--------------------------------

### Task Master CLI Commands

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/README.md

This API documentation outlines the core commands for the task-master CLI tool. It details the functionality of `expand`, `next`, and `show` commands, including their parameters, usage, and the expected output or behavior. The `expand` command is used for task generation, `next` for task prioritization, and `show` for detailed task retrieval.

```APIDOC
task-master:
  expand --id=<task_id> [--num=<subtask_count>] [--prompt=<custom_prompt>] [--all] [--research] [--file=<tasks_file>]
    Expands a task into subtasks, optionally using a complexity report or custom parameters.
    Parameters:
      --id: The ID of the task to expand.
      --num: (Optional) The number of subtasks to generate.
      --prompt: (Optional) A custom prompt to guide subtask generation.
      --all: (Optional) Sorts tasks by complexity score when expanding.
      --research: (Optional) Preserves the research flag from complexity analysis.
      --file: (Optional) Path to a custom tasks file.

  next [--file=<tasks_file>]
    Determines and displays the next task to work on based on dependencies and priority.
    Parameters:
      --file: (Optional) Path to a custom tasks file.

  show <task_id> [--id=<task_id>] [--file=<tasks_file>]
    Displays detailed information about a specific task or subtask.
    Parameters:
      <task_id>: The ID of the task to show (e.g., 1 or 1.2).
      --id: (Optional) Alternative way to specify the task ID.
      --file: (Optional) Path to a custom tasks file.

Output Structure for Complexity Report (used by `expand`):
  {
    "meta": {
      "generatedAt": "timestamp",
      "tasksAnalyzed": integer,
      "thresholdScore": float,
      "projectName": "string",
      "usedResearch": boolean
    },
    "complexityAnalysis": [
      {
        "taskId": integer,
        "taskTitle": "string",
        "complexityScore": float,
        "recommendedSubtasks": integer,
        "expansionPrompt": "string",
        "reasoning": "string",
        "expansionCommand": "string"
      }
    ]
  }
```

--------------------------------

### Subscribing to Events: NDK vs. nostr-tools

Source: https://github.com/healthnotelabs/runstr/blob/main/NOSTR-TOOLS-MIGRATION.md

Illustrates the difference in subscribing to Nostr events between NDK and nostr-tools, including handling incoming events and end-of-stream signals.

```javascript
// Old NDK approach
const subscription = ndk.subscribe({
  kinds: [1],
  "#t": ["running"]
});

subscription.on('event', handleEvent);
subscription.on('eose', handleEose);

// New nostr-tools approach
const sub = pool.sub(relays, [{
  kinds: [1],
  "#t": ["running"]
}]);

sub.on('event', handleEvent);
sub.on('eose', handleEose);
```

--------------------------------

### Previous Implementation Log

Source: https://github.com/healthnotelabs/runstr/blob/main/fully-functional-NIP60.md

A log detailing the previous implementation of the ecash wallet, serving as a reference for historical context and development decisions.

```md
✅ `ecash-implementation.md` - Previous implementation log
```

--------------------------------

### Support Information

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/REWARDS-README.md

Details how to get support for issues or questions related to the RUNSTR scripts. It suggests checking console output, Nostr event data, relay connectivity, and dependencies.

```markdown
For issues or questions about these scripts:
- Check console output for error messages
- Review Nostr event data for completeness
- Verify relay connectivity and response times
- Ensure all dependencies are installed
```

--------------------------------

### AI-Driven Workflow: Task Discovery

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

How to ask the Cursor agent to discover available tasks, which involves running `task-master list` and `task-master next`.

```bash
What tasks are available to work on next?
```

--------------------------------

### Showing Task Details

Source: https://github.com/healthnotelabs/runstr/blob/main/scripts/README.md

The `show` command provides detailed information about a specific task or subtask. It displays basic details, full descriptions, implementation notes, test strategies, and subtask information. The command supports specifying the task ID directly or using the `--id` option, and can also target tasks from a custom file.

```bash
# Show details for a specific task
task-master show 1

# Alternative syntax with --id option
task-master show --id=1

# Show details for a subtask
task-master show --id=1.2

# Specify a different tasks file
task-master show 3 --file=custom-tasks.json
```

--------------------------------

### New CSS Variables Structure

Source: https://github.com/healthnotelabs/runstr/blob/main/Design_overhaul.md

Defines a new CSS variables structure for the RUNSTR project, including core colors, typography, spacing, and component tokens. It also includes a dark mode override example.

```css
:root {
  /* Core colors */
  --color-background: #ffffff;
  --color-background-dark: #000000;
  --color-surface: #f8f9fa;
  --color-surface-dark: #0f0f0f;
  
  /* Typography */
  --font-family-primary: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
  
  /* Spacing based on 4px grid */
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-6: 1.5rem;
  
  /* Component tokens */
  --border-radius-sm: 4px;
  --border-radius-md: 8px;
  --border-radius-lg: 12px;
}

[data-theme="dark"] {
  --color-background: var(--color-background-dark);
  --color-surface: var(--color-surface-dark);
  /* ... other dark mode overrides */
}
```

--------------------------------

### RUNSTR Deployment Checklist

Source: https://github.com/healthnotelabs/runstr/blob/main/RUNSTR_SEASON_1.md

A checklist for deploying the RUNSTR application, covering code quality, performance optimizations, testing procedures, and configuration settings.

```plaintext
DEPLOYMENT CHECKLIST

Code Quality:
- All debug code removed
- Production error handling implemented
- Mock data removed
- Console.log statements cleaned up
- Proper TypeScript typing

Performance:
- Caching system optimized
- Batch processing implemented
- Progressive loading working
- Memory usage optimized

Testing:
- Payment flow tested
- Participant addition verified
- Leaderboard display confirmed
- Activity filtering validated
- Error states handled

Configuration:
- Season dates set (July 11 - September 11, 2025)
- Price configured (10,000 sats)
- Activity modes working (Run/Walk/Cycle)
- NWC wallet integration ready
```

--------------------------------

### App-Level NDK Initialization

Source: https://github.com/healthnotelabs/runstr/blob/main/finish_teams_implementation.md

Implementation of persistent background NDK connections with separated data/signer concerns for optimal mobile UX. This involves updating the application's context and provider setup.

```jsx
// Updated App.jsx
// Switched from old NostrProvider.jsx to NostrContext.jsx
// Removed duplicate/unused NostrProvider.jsx file
// App now uses the comprehensive NDK singleton provider
```

```jsx
// Enhanced NostrContext.jsx
// Added canReadData state - true when NDK is connected (regardless of signer)
// Added needsSigner state - for future use when operations require signer
// Updated updateNdkStatus to set canReadData based on NDK connection
// Exposed new properties through context value
```

--------------------------------

### Update Zapstore CLI Version

Source: https://github.com/healthnotelabs/runstr/blob/main/ZAPSTORE_CLI_FIX.md

This snippet shows how to update the Zapstore CLI to the latest version by downloading the binary and installing it. It replaces an old hardcoded URL with a command to fetch the latest version.

```bash
# OLD (problematic):
ZAP_CLI_URL="https://cdn.zapstore.dev/0d684425c4bbd3fdecc58f7bf7fc55366d71b8ded9d68b3bbfcb3fcca1072325"

# NEW (fixed):
curl -L https://cdn.zapstore.dev/latest/zapstore-linux -o zapstore
yes | zapstore install zapstore  # Self-update to latest
```

--------------------------------

### AI-Driven Workflow: Task Implementation

Source: https://github.com/healthnotelabs/runstr/blob/main/README-task-master.md

Guidance on how to prompt the Cursor agent to implement a specific task, referencing its details and dependencies.

```bash
Let's implement task 3. What does it involve?
```

--------------------------------

### Questions for Clarification

Source: https://github.com/healthnotelabs/runstr/blob/main/stats-ui-improvements.md

Lists key questions requiring clarification before proceeding with implementation, focusing on Blossom images, global theming, and implementation priority.

```plaintext
1. Blossom Images: Individual pink flowers or one large bouquet?
2. Global Theming: Should we assess feasibility first or go page-by-page?
3. Implementation Priority: Any specific tasks you'd like to tackle first?
```

--------------------------------

### Global Competition Date Configuration

Source: https://github.com/healthnotelabs/runstr/blob/main/PHASE_4_IMPLEMENTATION_SUMMARY.md

Defines the global start and end dates for Season 1 of the RUNSTR competition. This configuration is used across various hooks and services to ensure consistent activity filtering.

```typescript
SEASON_1: {
  passPrice: 10000,
  startUtc: '2025-07-01T00:00:00Z', // Testing period: July 1-30
  endUtc: '2025-07-30T23:59:59Z',   // Testing period: July 1-30
  title: 'RUNSTR SEASON 1'
}
```

--------------------------------

### Server Discovery Process

Source: https://github.com/healthnotelabs/runstr/blob/main/memory-bank/blossom-music-integration.md

Details the process of discovering and trying Blossom endpoints across multiple servers. It shows the servers being searched, the configuration for a specific server, the expected subdomain, and the URLs being attempted.

```APIDOC
Server Discovery Process:

🔍 Searching <number> servers: <server_list>
🔧 Server config: <server_name> (<server_type>)
🌸 Expected subdomain: <subdomain_url>
🔍 Trying <server_name> endpoints: <endpoint_url>
```

--------------------------------

### NostrTeamsService - Prepare Pinned Message Update

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

Adds a helper function to the NostrTeamsService for preparing a new Nostr event that updates or sets a 'pinned_message' tag on a team event. This facilitates captains in pinning important messages for their teams.

```typescript
import { NostrEvent, finishEvent } from '@nostr-dev-kit/ndk';

// In NostrTeamsService.ts

async preparePinnedMessageUpdate(teamEvent: NostrEvent, newMessage: string, ndkInstance: any): Promise<NostrEvent> {
  const updatedEvent = {
    ...teamEvent,
    tags: [
      ...teamEvent.tags.filter(tag => tag[0] !== 'pinned_message'), // Remove existing pinned message tag
      ['pinned_message', newMessage], // Add the new pinned message tag
    ],
    content: teamEvent.content, // Keep original content or update if needed
    kind: teamEvent.kind, // Ensure kind is correct for team events
    created_at: Math.floor(Date.now() / 1000),
  };

  // Sign and publish the event using NDK
  const signedEvent = await ndkInstance.signEvent(updatedEvent);
  return signedEvent;
}
```

--------------------------------

### Team Stats Widget Component

Source: https://github.com/healthnotelabs/runstr/blob/main/teams_implementation_updates1.md

A UI component that displays the total distance run by a team for the current month. It utilizes the `useTeamActivity` hook to fetch and process the activity data, presenting the aggregated distance in a user-friendly format.

```typescript
import React from 'react';
import useTeamActivity from '../hooks/useTeamActivity';
import { NostrEvent } from '@nostr-dev-kit/ndk';

interface TeamStatsWidgetProps {
  workoutEvents: NostrEvent[];
}

const TeamStatsWidget: React.FC<TeamStatsWidgetProps> = ({ workoutEvents }) => {
  const { totalTeamDistance } = useTeamActivity(workoutEvents);

  return (
    <div className="team-stats-widget">
      <h3>Monthly Team Stats</h3>
      <p>Total Distance: {totalTeamDistance.toFixed(2)} km</p>
      {/* Add more stats as needed */}
    </div>
  );
}; 

export default TeamStatsWidget;
```

--------------------------------

### Test Bitvora With Demo

Source: https://github.com/healthnotelabs/runstr/blob/main/tmpfiles.txt

Tests for Bitvora functionality using demo data or scenarios.

```javascript
src/tests/test-bitvora-with-demo.mj
```