Documentation

The glossary, the formulas, and the project file format. Everything here is plain and machine-readable on purpose — agents and technical users can construct a BidVariance project file by hand.

The portable project format

A BidVariance project is a single JSON document, schema bidvariance.project.v1. You own the file: export it, edit it, re-import it, keep it in git. Validation is strict — unknown schema versions and malformed files are rejected with clear messages, never silently repaired.

JSON Schema (draft-07) Glossary as JSON Formulas as JSON

Example

{
  "schema": "bidvariance.project.v1",
  "projectName": "Warehouse WMS Integration",
  "currency": "USD",
  "contractPrice": 150000,
  "targetMargin": 0.25,
  "confidenceTarget": 0.80,
  "plannedStartDate": "2026-10-01",
  "promisedCompletionDate": "2027-02-15",
  "projectFixedCosts": 6000,
  "overhead": 12000,
  "notes": "Signed LOI; vendor API docs are thin.",
  "tasks": [
    {
      "id": "t1",
      "name": "Discovery & requirements",
      "optimistic": 8, "likely": 10, "pessimistic": 15,
      "fixedCost": 0, "dailyBurnRate": 900,
      "deps": []
    },
    {
      "id": "t2",
      "name": "Middleware build",
      "optimistic": 18, "likely": 25, "pessimistic": 45,
      "fixedCost": 2000, "dailyBurnRate": 1000,
      "deps": ["t1"]
    }
  ],
  "risks": [
    {
      "id": "r1",
      "name": "Client approval delay",
      "probability": 0.35,
      "costOptimistic": 1000, "costLikely": 3000, "costPessimistic": 8000,
      "scheduleOptimistic": 2, "scheduleLikely": 5, "schedulePessimistic": 12,
      "affectedTaskId": "",
      "notes": "Happened on the last two projects."
    }
  ],
  "settings": {
    "distribution": "beta-pert",
    "iterations": 25000,
    "seed": 123456
  }
}

Rules

schema must be exactly "bidvariance.project.v1". Newer versions are rejected with a clear message (never silently reinterpreted).
Estimates must satisfy optimistic ≤ likely ≤ pessimistic; equal values make the task deterministic.
deps lists task ids that must Finish-to-Start before this task; the graph must be acyclic; unknown ids are rejected.
A risk with empty affectedTaskId is project-wide: its cost adds to total cost and its delay pushes the final delivery date.
currency is a label only — BidVariance never converts exchange rates.
settings.seed (uint32 or null) makes runs reproducible.
Unknown fields produce import warnings and are dropped, not guessed at.

An AI agent can prepare this file from a task list; the licensed app then runs the full analysis locally. There is no paid API in this version — the engine is the browser app you own.

Glossary

Monte Carlo simulation: Running the same project model thousands of times, drawing plausible values for every uncertain input each run, and measuring the spread of results (cost, duration, profit) instead of trusting one fixed estimate.
Beta-PERT distribution: A smooth probability distribution built from three estimates: optimistic, most likely, and pessimistic. With lambda = 4 its mean equals the classic PERT weighted average (O + 4M + P) / 6.
Optimistic (O): The best realistic case for a task's duration or cost — everything goes right, but it is still a real outcome, not a fantasy.
Most likely (M): The single most plausible value for a task's duration or cost if you had to pick one number.
Pessimistic (P): The genuinely bad-but-possible case. The width of the O–P range is where estimation risk lives.
Percentile (P50, P80, P90): A value that a given share of simulated outcomes falls at or below. P80 cost means 80% of simulated runs cost that amount or less.
P50: The median. Half of simulated outcomes are at or below it. A midpoint, not a safe commitment — quoting at P50 is a coin flip.
P80: The value 80% of simulated outcomes fall at or below. A common commercial reference level for bids and deadlines.
P90: The 90% level — more conservative, appropriate when the downside of overrun is expensive.
Deadline confidence: The share of simulation runs that finish on or before the promised completion date.
Probability of loss: The share of simulations where total project cost exceeds the contract price — the bid loses money.
Gross margin: (Contract price − total cost) / contract price. This is margin, not markup.
Target margin probability: The share of simulations where gross margin is at least the target the user sets.
Daily burn rate: Cost per day while a task runs: fully-loaded people cost, tools, travel. Task cost = fixed cost + duration × burn rate.
Fixed cost: A one-off cost charged to a task or project regardless of duration: licences, hardware, subcontractor minimums.
Overhead: A fixed allocation of company overhead to a project. Entered as an absolute amount to avoid double-counting; BidVariance never applies percentage overhead automatically.
Discrete risk event: A named event that either happens or does not (client approval delay, vendor API limitation), with a probability and cost/schedule impacts sampled when it fires. Separate from ordinary estimate uncertainty.
Finish-to-Start dependency: A task starts only after all of its predecessor tasks finish. The only dependency type in the MVP.
DAG (directed acyclic graph): The task dependency graph. 'Acyclic' means no circular chains (A after B after A), which would make scheduling impossible. BidVariance rejects cycles before simulating.
Minimum defensible quote: The price at which the target margin is achieved with the chosen confidence.
Reverse pricing: Working backwards from a margin and confidence target to the price required, rather than forecasting outcomes for a price already chosen.
Seed: A number that starts the pseudo-random generator. The same project inputs, iteration count, and seed reproduce the exact same simulation.
Deterministic task: A task whose optimistic, most likely, and pessimistic values are identical. It contributes no uncertainty — it always takes exactly that value.
Contingency: Money or time added to absorb uncertainty. BidVariance makes contingency visible as the gap between P50 and P80/P90 instead of an arbitrary percentage.
Markup: Cost multiplied up to set a price. Different from margin: a 25% markup on cost is only a 20% margin on price. BidVariance works in margin.

Also available as JSON: /docs/glossary.json.

Formulas

Every calculation BidVariance performs is listed with its exact form on the methodology page and, machine-readable, in /docs/formulas.json. The short version: Beta-PERT (λ = 4) sampling, topological Finish-to-Start scheduling, transparent cost aggregation, empirical percentiles, and requiredPrice = costQuantile(confidence) / (1 − targetMargin).

License activation

After checkout on Gumroad you receive a license key by email. Open the app, paste the key once, and the browser stores a signed entitlement session (HttpOnly cookie) for 30 days; after that, re-entering the key re-verifies it in seconds. Verification sends only the key and product id — never project data. A license can be deactivated on a device from the app footer.