Feature Specification: New Pricing + Free Credits Policy

Feature Branch: 001-new-pricing Created: 2025-10-22 Status: Draft Input: User description: “New Pricing + Free Credits Policy”

User Scenarios & Testing (mandatory)

User Story 1 - New User Onboarding with Free Credits (Priority: P1)

A new user signs up for Tenki and receives 1,000 free minutes (normalized to 2 vCPU runners) to explore the platform without requiring payment information upfront. They can access all features and offerings during this trial period.

Why this priority: This is the primary entry point for all new users and directly addresses the problem of acquiring users while deferring payment collection until value is demonstrated.

Independent Test: Can be fully tested by creating a new account, running jobs on various runner sizes, and verifying that free minutes are properly calculated and consumed based on vCPU scaling (e.g., 500 minutes on 4 vCPU, 250 minutes on 8 vCPU).

Acceptance Scenarios:

1. Given a new user signs up for Tenki, When their account is created, Then they receive 1,000 free minutes normalized to 2 vCPU runners
2. Given a user has free minutes remaining, When they use a 2 vCPU runner for 10 minutes, Then 10 minutes are deducted from their balance
3. Given a user has free minutes remaining, When they use a 4 vCPU runner for 10 minutes, Then 20 minutes are deducted from their balance (scaled by vCPU ratio)
4. Given a user has free minutes remaining, When they use an 8 vCPU runner for 10 minutes, Then 40 minutes are deducted from their balance (scaled by vCPU ratio)
5. Given a new user with free credits, When they access the platform, Then they can use all features and runner types without restrictions

User Story 2 - Payment Information Collection After Free Credits (Priority: P1)

When a user exhausts their 1,000 free minutes, the system prompts them to enter credit card information to continue using the platform on a pay-as-you-go basis.

Why this priority: This is the critical conversion point from free trial to paid customer and directly addresses the problem of verifying payment intent before allowing continued usage.

Independent Test: Can be tested by consuming all free minutes and verifying that the system blocks further usage until valid payment information is provided, then allows continued usage after payment details are entered.

Acceptance Scenarios:

1. Given a user has consumed all 1,000 free minutes, When they attempt to run a new job, Then they are prompted to enter credit card information before proceeding
2. Given a user is prompted for payment, When they enter valid credit card details, Then their account transitions to pay-as-you-go billing and jobs can proceed
3. Given a user is prompted for payment, When they close the prompt without entering payment details, Then their jobs remain blocked until payment is provided
4. Given a user has entered payment information, When they consume additional minutes, Then usage is tracked and billed according to PAYG pricing

User Story 3 - Pay-As-You-Go Usage and Billing (Priority: P2)

A paid user runs CI/CD jobs on various runner types and is charged per-minute based on the runner SKU pricing. They receive transparent billing for their actual usage with no upfront commitments.

Why this priority: This is the core revenue model for the platform and must work reliably for sustainable business operations.

Independent Test: Can be tested by running jobs on different runner SKUs, verifying per-minute charges match the pricing table, and confirming accurate invoice generation.

Acceptance Scenarios:

1. Given a paid user runs a job on a 2c-4GB x64 runner for 10 minutes, When billing is calculated, Then they are charged $0.03 (10 min × $0.003/min)
2. Given a paid user runs a job on a 4c-8GB x64 runner for 15 minutes, When billing is calculated, Then they are charged $0.09 (15 min × $0.006/min)
3. Given a paid user with 40 concurrent jobs included, When they run 40 or fewer concurrent jobs, Then no additional concurrency charges apply
4. Given a paid user, When they view their billing dashboard, Then they see itemized usage by runner type, duration, and total costs

User Story 4 - Add-On Purchase and Management (Priority: P2)

A user on the PAYG plan purchases optional add-ons such as macOS M4 runner access, priority support, or priority queue boost to enhance their experience.

Why this priority: Add-ons provide upsell opportunities and feature-based segmentation, addressing the problem of revenue expansion and feature monetization.

Independent Test: Can be tested by purchasing an add-on (e.g., macOS access for $39/month), verifying access is granted, and confirming the recurring charge appears on invoices.

Acceptance Scenarios:

1. Given a PAYG user, When they purchase macOS M4 runner access for $39/month, Then they can create and run jobs on macOS runners
2. Given a user without macOS access, When they attempt to use macOS runners, Then they are prompted to purchase the add-on
3. Given a user purchases priority support for $250/month, When they submit a support request, Then it is routed to the priority queue with private chat access
4. Given a user purchases priority queue boost for $49/month per workspace, When their jobs are queued, Then they receive higher priority in job scheduling
5. Given a user with add-ons, When they view their billing, Then add-on charges are itemized separately from usage charges

User Story 5 - Additional Concurrent Job Slot Purchase (Priority: P3)

A user exceeding the 40 included concurrent job slots purchases additional slots at $7/slot/month for x64 runners or $49/slot/month for macOS M4 runners.

Why this priority: This supports teams with high parallelism needs and provides incremental revenue, but is less critical than core pricing and add-ons.

Independent Test: Can be tested by running more than 40 concurrent jobs, purchasing additional slots, and verifying jobs execute in parallel up to the new limit.

Acceptance Scenarios:

1. Given a user with 40 included concurrent slots, When they attempt to run 50 concurrent jobs, Then 10 jobs are queued until slots become available
2. Given a user, When they purchase 10 additional x64 concurrent slots, Then they are charged $70/month and can run up to 50 concurrent x64 jobs
3. Given a user, When they purchase 5 additional macOS M4 concurrent slots, Then they are charged $245/month and can run up to 45 concurrent macOS jobs (assuming base 40 applies to all runner types)

User Story 6 - Storage Billing (Priority: P3)

A user stores build artifacts, caches, and other data on the platform and is billed $0.20 per GB per month for storage consumption.

Why this priority: Storage is a necessary cost component but secondary to compute billing in terms of implementation priority and revenue impact.

Independent Test: Can be tested by uploading data, tracking storage usage over time, and verifying charges match $0.20/GB/month prorated.

Acceptance Scenarios:

1. Given a user stores 50 GB of data, When monthly billing is calculated, Then they are charged $10 for storage
2. Given a user uploads 20 GB on day 15 of the month, When monthly billing is calculated, Then they are charged approximately $2 (prorated for half month)
3. Given a user has 10 GB of transparent cache included, When they use 10 GB or less total storage, Then no storage charges apply [NEEDS CLARIFICATION: Is the 10GB transparent cache counted toward the $0.20/GB storage billing, or is it separate?]

User Story 7 - Enterprise Custom Pricing Inquiry (Priority: P3)

An enterprise customer with predictable, high-volume usage requests committed use discounts and white-glove onboarding through a sales inquiry process.

Why this priority: Enterprise deals provide revenue predictability and larger contracts, but represent a smaller percentage of total users and require sales team involvement.

Independent Test: Can be tested by submitting an enterprise inquiry form, receiving a response from sales, and negotiating custom pricing terms outside the automated PAYG system.

Acceptance Scenarios:

1. Given a user interested in enterprise pricing, When they submit an inquiry, Then they are contacted by the sales team within [NEEDS CLARIFICATION: response SLA not specified - 24 hours? 48 hours?]
2. Given an enterprise customer commits to a minimum usage level, When their contract is established, Then they receive discounted per-minute rates compared to PAYG
3. Given an enterprise customer, When they onboard, Then they receive dedicated success engineer support for migration and setup

User Story 8 - Premium Runner Pricing (Priority: P3)

A user opts to use premium runners (indicated by “Premium Pricing” in the SKU table) and is charged an additional fee on top of the base runner cost.

Why this priority: Premium runners provide differentiated service levels but are an optional enhancement to the base offering.

Independent Test: Can be tested by selecting a premium runner option, running a job, and verifying the charge includes the base price plus the premium surcharge.

Acceptance Scenarios:

1. Given a user runs a job on a premium 2c-4GB runner for 10 minutes, When billing is calculated, Then they are charged $0.045 (10 min × ($0.003 + $0.0015)/min)
2. Given a user runs a job on a premium 4c-8GB runner for 10 minutes, When billing is calculated, Then they are charged $0.090 (10 min × ($0.006 + $0.003)/min)
3. Given a user, When they select a runner, Then they can choose between standard and premium options with clear pricing displayed [NEEDS CLARIFICATION: What specific benefits do premium runners provide - faster provisioning, dedicated resources, better SLA?]

Edge Cases

• What happens when a user’s payment method fails after exhausting free credits? Are jobs blocked immediately or is there a grace period?
• How are partial minutes billed (e.g., a job that runs for 3.5 minutes)?
• What happens if a user deletes stored data mid-month? Is storage billing prorated daily?
• How are concurrent job limits enforced when a user has both x64 and macOS runners? Are the limits separate or combined?
• What happens when a user downgrades or cancels add-ons mid-billing cycle? Do they receive prorated refunds or credits?
• How are discounts (up to 50% offered by sales) applied to the billing system? Are they percentage discounts or fixed credits?
• What happens when a user exhausts free credits in the middle of a running job? Is the job terminated or allowed to complete?
• How is abuse detection handled for users who repeatedly create new accounts to exploit free credits?

Requirements (mandatory)

Functional Requirements

Free Credits System

• FR-001: System MUST allocate 1,000 free minutes (normalized to 2 vCPU runners) to all new user accounts upon creation
• FR-002: System MUST scale free minute consumption based on runner vCPU count (e.g., 4 vCPU uses 2× minutes, 8 vCPU uses 4× minutes)
• FR-003: System MUST track free minute balance in real-time and display remaining balance to users
• FR-004: System MUST allow users with free minutes to access all runner types and platform features without restrictions
• FR-005: System MUST prevent job execution when free minutes are exhausted and payment information has not been provided

Payment Collection

• FR-006: System MUST prompt users to enter credit card information when free minutes are exhausted
• FR-007: System MUST validate and securely store payment information using industry-standard tokenization
• FR-008: System MUST transition user accounts from free trial to PAYG billing status after payment information is collected
• FR-009: System MUST block job execution for users who decline to provide payment information after exhausting free credits

Pay-As-You-Go Billing

• FR-010: System MUST calculate per-minute charges for all runner types according to the defined pricing table (x64, macOS, premium)
• FR-011: System MUST track actual usage time for each job execution down to the minute
• FR-012: System MUST generate itemized invoices showing usage by runner type, duration, and cost
• FR-013: System MUST charge payment methods on a monthly billing cycle for accumulated usage
• FR-014: System MUST include 40 concurrent job slots in all PAYG accounts at no additional charge
• FR-015: System MUST include 10 GB of transparent caching in all PAYG accounts at no additional charge

Add-On Management

• FR-016: System MUST allow users to purchase macOS M4 runner access for $39/month per workspace
• FR-017: System MUST allow users to purchase priority support for $250/month
• FR-018: System MUST allow users to purchase priority queue boost for $49/month per workspace
• FR-019: System MUST restrict access to add-on features until the corresponding add-on is purchased
• FR-020: System MUST bill add-on charges as recurring monthly fees separate from usage charges
• FR-021: System MUST allow users to enable, disable, or modify add-ons at any time
• FR-022: System MUST grant macOS runner access only to users with the macOS add-on active
• FR-023: System MUST route support requests to priority queue for users with priority support add-on
• FR-024: System MUST prioritize job scheduling for workspaces with priority queue boost add-on

Concurrent Job Slot Management

• FR-025: System MUST allow users to purchase additional concurrent job slots at $7/slot/month for x64 runners
• FR-026: System MUST allow users to purchase additional concurrent job slots at $49/slot/month for macOS M4 runners
• FR-027: System MUST enforce concurrent job limits based on base allocation plus purchased slots
• FR-028: System MUST queue jobs that exceed concurrent slot limits until slots become available

Storage Billing

• FR-029: System MUST track total storage consumption for each user account across artifacts, caches, and data
• FR-030: System MUST bill storage at $0.20 per GB per month
• FR-031: System MUST calculate storage billing based on average daily usage over the billing period
• FR-032: System MUST display current storage usage and projected monthly costs to users

Runner Pricing

• FR-033: System MUST support all x64 runner SKUs with specified pricing (2c-4GB through 64c-256GB)
• FR-034: System MUST support macOS runner SKUs with specified pricing (6 vCPU, 12 vCPU)
• FR-035: System MUST support premium pricing tier for eligible x64 runner SKUs with additional charges
• FR-036: System MUST clearly display runner pricing to users when selecting runner types

Enterprise Tier

• FR-037: System MUST provide a mechanism for users to request enterprise pricing and custom contracts
• FR-038: System MUST support custom pricing configurations for enterprise accounts with committed use discounts
• FR-039: System MUST allow sales team to configure account-specific discounts up to 50%
• FR-040: System MUST support white-glove onboarding workflows for enterprise customers

Annual Prepayment Options (Internal)

• FR-041: System MUST support 12-month prepayment for priority queue boost at $499 (15% discount)
• FR-042: System MUST support 12-month prepayment for macOS M4 access at $399 (15% discount)
• FR-043: System MUST apply prepaid add-ons to user accounts for 12-month duration

Abuse Prevention

• FR-044: System MUST implement mechanisms to detect and prevent abuse patterns (repeated free credit exploitation, cryptocurrency mining, unauthorized Minecraft servers)
• FR-045: System MUST require payment information as a verification gate to prevent abusive users from continuing operations

Key Entities

• User Account: Represents an individual or organization using Tenki, with free credit balance, payment status, billing tier, and usage history
• Free Credit Balance: The remaining free minutes available to a user, normalized to 2 vCPU baseline, consumed based on runner vCPU scaling
• Payment Method: Tokenized credit card information associated with a user account for billing purposes
• Add-On Subscription: A purchased add-on feature (macOS access, priority support, priority queue boost) with recurring billing
• Concurrent Job Slot: Allocated capacity for running parallel jobs, includes base allocation plus purchased additional slots
• Runner SKU: A specific runner configuration (vCPU, memory) with associated per-minute pricing
• Usage Record: A log of job execution including runner type, duration, and calculated cost
• Invoice: A monthly billing statement showing itemized usage charges, add-on fees, and total amount due
• Enterprise Contract: A custom pricing agreement with committed use discounts and negotiated terms
• Storage Allocation: The amount of data stored by a user, tracked for billing at $0.20/GB/month
• Workspace: An organizational unit within a user account, relevant for workspace-specific add-ons (priority queue boost, macOS access)

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: 90% of new users successfully start their first job using free credits within 24 hours of signup
• SC-002: Free credit system accurately scales minute consumption across all runner SKU types with 100% precision
• SC-003: Payment conversion rate from free to paid users reaches at least 15% within 30 days of signup
• SC-004: Billing calculations are accurate to the cent with zero disputes related to calculation errors in the first 90 days
• SC-005: Users can view real-time usage and cost projections with data latency under 5 minutes
• SC-006: Add-on purchases are reflected in user accounts and billing within 60 seconds of confirmation
• SC-007: Abuse detection mechanisms block at least 95% of identified abusive patterns (mining, unauthorized servers) within 24 hours of detection
• SC-008: Enterprise inquiry response time averages under 24 hours during business days
• SC-009: Concurrent job limits are enforced in real-time with zero jobs exceeding purchased slot allocation
• SC-010: Monthly revenue predictability improves by at least 30% through enterprise contracts and add-on subscriptions within 6 months of launch
• SC-011: Customer support tickets related to billing and pricing decrease by 40% compared to the previous pricing model within 3 months
• SC-012: Average revenue per user (ARPU) increases by at least 20% through add-on adoption within 6 months

Assumptions

• Users understand vCPU-based scaling of free credits and can calculate their effective free minutes for different runner sizes
• Industry-standard payment processing (Stripe or similar) is available and integrated for secure credit card handling
• Enterprise sales team has capacity and process to handle custom pricing negotiations and white-glove onboarding
• Abuse detection can leverage usage patterns, payment verification, and potentially behavioral analysis to identify bad actors
• Storage billing is calculated daily and averaged over the monthly billing period for prorated charges
• Partial minutes are rounded up to the next whole minute for billing purposes (industry standard for compute billing)
• Payment method failures trigger automated retry logic and user notifications before blocking service
• Annual prepayment options are available to sales team but not publicly advertised on the pricing page
• The 10 GB transparent cache is included in base PAYG pricing and does not count toward the $0.20/GB storage billing
• Concurrent job limits are enforced separately for x64 and macOS runners (not combined)
• Add-ons can be canceled at any time but billing continues through the end of the current billing cycle (no prorated refunds)
• Discounts applied by sales team are percentage-based and apply to all usage charges, not just specific SKUs
• Jobs in progress when free credits are exhausted are allowed to complete before payment is required
• Free credit abuse is mitigated by requiring unique email verification and detecting suspicious signup patterns.