arkaos 2.2.2 → 2.3.1

package/scripts/tools/okr_cascade.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+"""OKR Cascade Generator -- ArkaOS v2.
+
+Generates cascading OKRs (Company -> Product -> Team) from a strategy type.
+Supports strategies: growth, retention, revenue, innovation.
+Outputs alignment scores and a visual cascade dashboard.
+
+Usage:
+    python okr_cascade.py growth
+    python okr_cascade.py retention --teams "Engineering,Design,Data"
+    python okr_cascade.py revenue --contribution 0.4 --json
+"""
+from __future__ import annotations
+import argparse, json, sys
+from dataclasses import dataclass, field, asdict
+from datetime import datetime
+from typing import Dict, List
+
+@dataclass
+class KeyResult:
+    """A single measurable key result."""
+    id: str; title: str; target: float = 0.0; parent_id: str = ""
+
+@dataclass
+class Objective:
+    """An objective containing key results."""
+    id: str; title: str; owner: str = ""; parent_id: str = ""
+    key_results: List[KeyResult] = field(default_factory=list)
+
+@dataclass
+class OKRLevel:
+    """A set of objectives at one organisational level."""
+    level: str; objectives: List[Objective] = field(default_factory=list)
+
+STRATEGIES: Dict[str, Dict[str, List[str]]] = {
+    "growth": {
+        "objectives": ["Accelerate user acquisition and market expansion",
+                       "Achieve product-market fit in new segments",
+                       "Build a sustainable growth engine"],
+        "key_results": ["Increase MAU by {pct}%", "Achieve {pct}% MoM growth rate",
+                        "Reduce CAC by {pct}%"],
+    },
+    "retention": {
+        "objectives": ["Create lasting customer value and loyalty",
+                       "Deliver a superior user experience",
+                       "Maximise customer lifetime value"],
+        "key_results": ["Improve retention to {pct}%", "Increase NPS by {pct} points",
+                        "Reduce churn to below {pct}%"],
+    },
+    "revenue": {
+        "objectives": ["Drive sustainable revenue growth",
+                       "Optimise monetisation strategy", "Expand revenue per customer"],
+        "key_results": ["Grow ARR by {pct}%", "Increase ARPU by {pct}%",
+                        "Achieve {pct}% gross margin"],
+    },
+    "innovation": {
+        "objectives": ["Lead the market through product innovation",
+                       "Establish leadership in key capability areas",
+                       "Build sustainable competitive differentiation"],
+        "key_results": ["Launch {pct} breakthrough features",
+                        "Achieve {pct}% revenue from new products",
+                        "Reduce time-to-market by {pct}%"],
+    },
+}
+PRODUCT_PREFIX = {"growth": "Build viral product features for",
+                  "retention": "Design sticky experiences for",
+                  "revenue": "Optimise product monetisation for",
+                  "innovation": "Ship innovative features for"}
+
+def _quarter() -> str:
+    now = datetime.now()
+    return f"Q{(now.month - 1) // 3 + 1} {now.year}"
+
+def generate_cascade(strategy: str, teams: List[str], contribution: float,
+                     target: float) -> Dict:
+    """Generate the full Company -> Product -> Team cascade."""
+    tpl, quarter = STRATEGIES[strategy], _quarter()
+    company = OKRLevel(level="Company")
+    for i, obj_title in enumerate(tpl["objectives"]):
+        obj = Objective(id=f"CO-{i+1}", title=obj_title, owner="CEO")
+        for j, kr_tpl in enumerate(tpl["key_results"]):
+            obj.key_results.append(KeyResult(
+                id=f"CO-{i+1}-KR{j+1}",
+                title=kr_tpl.replace("{pct}", str(int(target))), target=target))
+        company.objectives.append(obj)
+    prefix = PRODUCT_PREFIX.get(strategy, "Product:")
+    product = OKRLevel(level="Product")
+    for co in company.objectives:
+        po = Objective(id=co.id.replace("CO", "PO"),
+                       title=f"{prefix} {co.title.lower()}",
+                       owner="Head of Product", parent_id=co.id)
+        for kr in co.key_results:
+            po.key_results.append(KeyResult(
+                id=kr.id.replace("CO", "PO"), title=f"[Product] {kr.title}",
+                target=round(kr.target * contribution, 1), parent_id=kr.id))
+        product.objectives.append(po)
+    team_levels: List[OKRLevel] = []
+    share = round(1.0 / max(len(teams), 1), 2)
+    for team in teams:
+        tl = OKRLevel(level=f"Team:{team}")
+        for po in product.objectives:
+            to = Objective(id=po.id.replace("PO", team[:3].upper()),
+                           title=f"[{team}] {po.title}",
+                           owner=f"{team} Lead", parent_id=po.id)
+            for kr in po.key_results[:2]:
+                to.key_results.append(KeyResult(
+                    id=kr.id.replace("PO", team[:3].upper()),
+                    title=f"[{team}] {kr.title}",
+                    target=round(kr.target * share, 1), parent_id=kr.id))
+            tl.objectives.append(to)
+        team_levels.append(tl)
+    return {"quarter": quarter, "strategy": strategy, "company": company,
+            "product": product, "teams": team_levels, "contribution": contribution}
+
+def alignment_scores(cascade: Dict) -> Dict[str, float]:
+    """Calculate vertical alignment, coverage, balance, and overall scores."""
+    linked = total = 0
+    for lvl in [cascade["product"]] + cascade["teams"]:
+        for obj in lvl.objectives:
+            total += 1
+            linked += 1 if obj.parent_id else 0
+    vertical = round((linked / max(total, 1)) * 100, 1)
+    co_krs = sum(len(o.key_results) for o in cascade["company"].objectives)
+    po_krs = sum(len(o.key_results) for o in cascade["product"].objectives)
+    coverage = round((po_krs / max(co_krs, 1)) * 100, 1)
+    counts = [len(t.objectives) for t in cascade["teams"]]
+    avg = sum(counts) / max(len(counts), 1)
+    variance = sum((c - avg) ** 2 for c in counts) / max(len(counts), 1)
+    balance = round(max(0, 100 - variance * 10), 1)
+    overall = round(vertical * 0.4 + coverage * 0.3 + balance * 0.3, 1)
+    return {"vertical": vertical, "coverage": coverage, "balance": balance, "overall": overall}
+
+def format_dashboard(cascade: Dict, scores: Dict[str, float]) -> str:
+    """Render a plain-text dashboard."""
+    lines = ["=" * 60, "OKR CASCADE DASHBOARD",
+             f"Quarter: {cascade['quarter']}  |  Strategy: {cascade['strategy'].upper()}",
+             f"Product contribution: {cascade['contribution'] * 100:.0f}%",
+             "=" * 60, "", "COMPANY OKRS"]
+    for o in cascade["company"].objectives:
+        lines.append(f"  {o.id}: {o.title}")
+        for kr in o.key_results:
+            lines.append(f"    {kr.id}: {kr.title}")
+    lines += ["", "PRODUCT OKRS"]
+    for o in cascade["product"].objectives:
+        lines.append(f"  {o.id}: {o.title}  (supports {o.parent_id})")
+        for kr in o.key_results:
+            lines.append(f"    {kr.id}: {kr.title}  [target: {kr.target}]")
+    lines += ["", "TEAM OKRS"]
+    for tl in cascade["teams"]:
+        lines.append(f"  --- {tl.level} ---")
+        for o in tl.objectives:
+            lines.append(f"    {o.id}: {o.title}")
+            for kr in o.key_results:
+                lines.append(f"      {kr.id}: {kr.title}  [target: {kr.target}]")
+    lines += ["", "ALIGNMENT SCORES", "-" * 40]
+    for k, v in scores.items():
+        tag = "[OK]" if v >= 80 else "[!!]" if v >= 60 else "[XX]"
+        lines.append(f"  {tag} {k.title()}: {v}%")
+    if scores["overall"] >= 80:
+        lines.append("\n  Overall alignment is GOOD (>= 80%)")
+    elif scores["overall"] >= 60:
+        lines.append("\n  Overall alignment NEEDS ATTENTION (60-80%)")
+    else:
+        lines.append("\n  Overall alignment is POOR (< 60%)")
+    return "\n".join(lines)
+
+def to_json(cascade: Dict, scores: Dict[str, float]) -> str:
+    """Serialise the full cascade to JSON."""
+    def _level(lvl: OKRLevel) -> Dict:
+        return {"level": lvl.level, "objectives": [asdict(o) for o in lvl.objectives]}
+    return json.dumps({"quarter": cascade["quarter"], "strategy": cascade["strategy"],
+        "contribution": cascade["contribution"], "company": _level(cascade["company"]),
+        "product": _level(cascade["product"]),
+        "teams": [_level(t) for t in cascade["teams"]],
+        "alignment_scores": scores}, indent=2)
+
+def main() -> int:
+    """Entry point."""
+    parser = argparse.ArgumentParser(
+        description="Generate cascading OKRs (Company -> Product -> Team)")
+    parser.add_argument("strategy", choices=list(STRATEGIES.keys()),
+                        help="Strategy type for OKR generation")
+    parser.add_argument("--teams", "-t", default="Growth,Platform,Mobile,Data",
+                        help="Comma-separated team names (default: Growth,Platform,Mobile,Data)")
+    parser.add_argument("--contribution", "-c", type=float, default=0.3,
+                        help="Product contribution fraction 0-1 (default: 0.3)")
+    parser.add_argument("--target", type=float, default=30,
+                        help="Numeric target for KR templates (default: 30)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+    if not 0 < args.contribution <= 1:
+        print("Error: --contribution must be between 0 and 1", file=sys.stderr)
+        return 2
+    teams = [t.strip() for t in args.teams.split(",") if t.strip()]
+    if not teams:
+        print("Error: at least one team is required", file=sys.stderr)
+        return 2
+    cascade = generate_cascade(args.strategy, teams, args.contribution, args.target)
+    scores = alignment_scores(cascade)
+    if args.json:
+        print(to_json(cascade, scores))
+    else:
+        print(format_dashboard(cascade, scores))
+    return 0 if scores["overall"] >= 60 else 1
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tools/rice_prioritizer.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""RICE Prioritizer -- rank features by Reach, Impact, Confidence, Effort.
+RICE = (Reach x Impact x Confidence) / Effort.
+Part of ArkaOS v2 -- stdlib-only, no pip dependencies.
+"""
+from __future__ import annotations
+import argparse, json, sys
+from dataclasses import asdict, dataclass, field
+from typing import Dict, List
+
+IMPACT_MAP: Dict[str, float] = {"massive": 3.0, "high": 2.0, "medium": 1.0, "low": 0.5, "minimal": 0.25}
+CONFIDENCE_MAP: Dict[str, int] = {"high": 100, "medium": 80, "low": 50}
+EFFORT_MAP: Dict[str, int] = {"xl": 13, "l": 8, "m": 5, "s": 3, "xs": 1}
+
+@dataclass
+class Feature:
+    name: str
+    reach: int = 0
+    impact: str = "medium"
+    confidence: str = "medium"
+    effort: str = "m"
+    description: str = ""
+    rice_score: float = 0.0
+    category: str = ""
+
+@dataclass
+class PortfolioAnalysis:
+    total_features: int = 0
+    total_effort_months: int = 0
+    total_reach: int = 0
+    average_rice: float = 0.0
+    quick_wins: List[str] = field(default_factory=list)
+    big_bets: List[str] = field(default_factory=list)
+
+@dataclass
+class RICEResult:
+    features: List[Feature] = field(default_factory=list)
+    analysis: PortfolioAnalysis = field(default_factory=PortfolioAnalysis)
+
+
+# ---------------------------------------------------------------------------
+# Core logic
+# ---------------------------------------------------------------------------
+
+def calculate_rice(reach: int, impact: str, confidence: str, effort: str) -> float:
+    """Compute the RICE score for a single feature."""
+    i = IMPACT_MAP.get(impact.lower(), 1.0)
+    c = CONFIDENCE_MAP.get(confidence.lower(), 50) / 100.0
+    e = EFFORT_MAP.get(effort.lower(), 5)
+    if e == 0:
+        return 0.0
+    return round((reach * i * c) / e, 2)
+
+
+def _categorize(feature: Feature) -> str:
+    """Classify a feature as quick-win, big-bet, fill-in, or time-sink."""
+    imp = feature.impact.lower()
+    eff = feature.effort.lower()
+    high_impact = imp in ("massive", "high")
+    low_effort = eff in ("xs", "s")
+    high_effort = eff in ("l", "xl")
+    if high_impact and low_effort:
+        return "quick-win"
+    if high_impact and high_effort:
+        return "big-bet"
+    if not high_impact and low_effort:
+        return "fill-in"
+    return "time-sink"
+
+
+def prioritize(raw_features: List[Dict]) -> RICEResult:
+    """Score, rank, and analyze a list of feature dicts."""
+    features: List[Feature] = []
+    for raw in raw_features:
+        f = Feature(
+            name=raw.get("name", "Unnamed"),
+            reach=int(raw.get("reach", 0)),
+            impact=str(raw.get("impact", "medium")),
+            confidence=str(raw.get("confidence", "medium")),
+            effort=str(raw.get("effort", "m")),
+            description=str(raw.get("description", "")),
+        )
+        f.rice_score = calculate_rice(f.reach, f.impact, f.confidence, f.effort)
+        f.category = _categorize(f)
+        features.append(f)
+
+    features.sort(key=lambda f: f.rice_score, reverse=True)
+
+    quick_wins = [f.name for f in features if f.category == "quick-win"]
+    big_bets = [f.name for f in features if f.category == "big-bet"]
+    total_effort = sum(EFFORT_MAP.get(f.effort.lower(), 5) for f in features)
+    total_reach = sum(f.reach for f in features)
+    avg_rice = round(sum(f.rice_score for f in features) / len(features), 2) if features else 0.0
+
+    analysis = PortfolioAnalysis(
+        total_features=len(features),
+        total_effort_months=total_effort,
+        total_reach=total_reach,
+        average_rice=avg_rice,
+        quick_wins=quick_wins[:5],
+        big_bets=big_bets[:5],
+    )
+
+    return RICEResult(features=features, analysis=analysis)
+
+
+# ---------------------------------------------------------------------------
+# Output formatting
+# ---------------------------------------------------------------------------
+
+def _format_text(result: RICEResult) -> str:
+    """Human-readable RICE report."""
+    lines = [
+        "=" * 60,
+        "  RICE PRIORITIZATION RESULTS",
+        "=" * 60,
+        "",
+        "  Rank  RICE     Category     Feature",
+        "  ----  -------  ----------   -------",
+    ]
+    for i, f in enumerate(result.features, 1):
+        lines.append(f"  {i:<4}  {f.rice_score:>7.1f}  {f.category:<12} {f.name}")
+
+    a = result.analysis
+    lines += [
+        "",
+        "-" * 60,
+        "  PORTFOLIO ANALYSIS",
+        "-" * 60,
+        f"  Total features:      {a.total_features}",
+        f"  Total effort:        {a.total_effort_months} person-months",
+        f"  Total reach:         {a.total_reach:,} users",
+        f"  Average RICE score:  {a.average_rice}",
+        "",
+    ]
+
+    if a.quick_wins:
+        lines.append("  Quick Wins (high impact, low effort):")
+        for name in a.quick_wins:
+            lines.append(f"    - {name}")
+    else:
+        lines.append("  Quick Wins: none identified")
+
+    lines.append("")
+    if a.big_bets:
+        lines.append("  Big Bets (high impact, high effort):")
+        for name in a.big_bets:
+            lines.append(f"    - {name}")
+    else:
+        lines.append("  Big Bets: none identified")
+
+    lines.append("=" * 60)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# Input loading
+# ---------------------------------------------------------------------------
+
+def _load_features(source: str) -> List[Dict]:
+    """Parse JSON from a string. Expects a list of feature objects."""
+    data = json.loads(source)
+    if isinstance(data, dict) and "features" in data:
+        data = data["features"]
+    if not isinstance(data, list):
+        raise ValueError("Expected a JSON array of feature objects.")
+    return data
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    """Entry point. Returns 0=success, 1=warnings, 2=errors."""
+    parser = argparse.ArgumentParser(
+        description="RICE Prioritizer -- rank features by Reach, Impact, Confidence, Effort.",
+    )
+    parser.add_argument(
+        "input", nargs="?", default=None,
+        help="JSON file with features, or inline JSON string",
+    )
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    # Load input
+    raw_json: str = ""
+    try:
+        if args.input:
+            # Try as file first, then as inline JSON
+            try:
+                with open(args.input, "r", encoding="utf-8") as fh:
+                    raw_json = fh.read()
+            except (FileNotFoundError, IsADirectoryError):
+                raw_json = args.input
+        elif not sys.stdin.isatty():
+            raw_json = sys.stdin.read()
+        else:
+            parser.print_help()
+            return 2
+    except OSError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+
+    if not raw_json.strip():
+        print("Error: no input provided.", file=sys.stderr)
+        return 2
+
+    try:
+        features = _load_features(raw_json)
+    except (json.JSONDecodeError, ValueError) as exc:
+        print(f"Error: invalid JSON -- {exc}", file=sys.stderr)
+        return 2
+
+    if not features:
+        print("Error: feature list is empty.", file=sys.stderr)
+        return 2
+
+    result = prioritize(features)
+
+    if args.json:
+        print(json.dumps(asdict(result), indent=2))
+    else:
+        print(_format_text(result))
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tools/saas_metrics.py

@@ -0,0 +1,234 @@
+#!/usr/bin/env python3
+"""SaaS Metrics Calculator -- ArkaOS v2.
+
+Calculates Quick Ratio, net MRR, growth rate, and optional LTV/CAC
+from MRR components. Assigns health status: Critical / Watch / Healthy / Excellent.
+
+Adapted from claude-skills/finance/saas-metrics-coach/scripts/quick_ratio_calculator.py
+
+Usage:
+    python saas_metrics.py --new-mrr 10000 --churned 3000
+    python saas_metrics.py --new-mrr 10000 --expansion 2000 --churned 3000 --contraction 500
+    python saas_metrics.py --new-mrr 10000 --churned 2000 --prev-mrr 50000 --ltv 3600 --cac 900 --json
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, asdict
+from typing import Optional
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class MRRComponents:
+    """Raw MRR inputs."""
+    new_mrr: float
+    expansion_mrr: float
+    churned_mrr: float
+    contraction_mrr: float
+    previous_mrr: Optional[float] = None
+
+@dataclass
+class SaaSMetrics:
+    """Calculated SaaS metrics."""
+    quick_ratio: Optional[float]
+    quick_ratio_display: str
+    net_new_mrr: float
+    growth_mrr: float
+    lost_mrr: float
+    current_mrr: Optional[float]
+    mrr_growth_rate: Optional[float]
+    ltv_cac_ratio: Optional[float]
+    status: str
+    interpretation: str
+    new_mrr_pct: float
+    expansion_mrr_pct: float
+    churned_mrr_pct: float
+    contraction_mrr_pct: float
+
+# ---------------------------------------------------------------------------
+# Calculation
+# ---------------------------------------------------------------------------
+
+def calculate_metrics(
+    components: MRRComponents,
+    ltv: Optional[float] = None,
+    cac: Optional[float] = None,
+) -> SaaSMetrics:
+    """Calculate all SaaS metrics from MRR components."""
+    growth = components.new_mrr + components.expansion_mrr
+    lost = components.churned_mrr + components.contraction_mrr
+    net_new = growth - lost
+
+    # Quick Ratio
+    if lost == 0:
+        qr = None if growth == 0 else float("inf")
+        qr_display = "0.00" if growth == 0 else "inf"
+    else:
+        qr = round(growth / lost, 2)
+        qr_display = f"{qr:.2f}"
+
+    # Status
+    if qr is None or (isinstance(qr, float) and qr < 1):
+        status, interp = "Critical", "Losing revenue faster than gaining -- unsustainable"
+    elif qr == float("inf") or qr >= 4:
+        status, interp = "Excellent", "Strong efficient growth -- gaining 4x+ faster than losing"
+    elif qr >= 2:
+        status, interp = "Healthy", "Good growth efficiency -- gaining 2x+ faster than losing"
+    else:
+        status, interp = "Watch", "Marginal growth -- barely gaining more than losing"
+
+    # Breakdown percentages
+    new_pct = round((components.new_mrr / growth) * 100, 1) if growth > 0 else 0.0
+    exp_pct = round((components.expansion_mrr / growth) * 100, 1) if growth > 0 else 0.0
+    churn_pct = round((components.churned_mrr / lost) * 100, 1) if lost > 0 else 0.0
+    contr_pct = round((components.contraction_mrr / lost) * 100, 1) if lost > 0 else 0.0
+
+    # Current MRR and growth rate
+    current_mrr = (components.previous_mrr + net_new) if components.previous_mrr is not None else None
+    mrr_growth = None
+    if components.previous_mrr and components.previous_mrr > 0:
+        mrr_growth = round((net_new / components.previous_mrr) * 100, 2)
+
+    # LTV/CAC
+    ltv_cac = round(ltv / cac, 2) if ltv and cac and cac > 0 else None
+
+    return SaaSMetrics(
+        quick_ratio=qr if qr != float("inf") else None,
+        quick_ratio_display=qr_display,
+        net_new_mrr=round(net_new, 2),
+        growth_mrr=round(growth, 2),
+        lost_mrr=round(lost, 2),
+        current_mrr=round(current_mrr, 2) if current_mrr is not None else None,
+        mrr_growth_rate=mrr_growth,
+        ltv_cac_ratio=ltv_cac,
+        status=status,
+        interpretation=interp,
+        new_mrr_pct=new_pct,
+        expansion_mrr_pct=exp_pct,
+        churned_mrr_pct=churn_pct,
+        contraction_mrr_pct=contr_pct,
+    )
+
+# ---------------------------------------------------------------------------
+# Formatters
+# ---------------------------------------------------------------------------
+
+def format_report(m: SaaSMetrics, components: MRRComponents) -> str:
+    """Render a plain-text report."""
+    lines = [
+        "=" * 60,
+        "SAAS METRICS ANALYSIS",
+        "=" * 60,
+        "",
+        f"QUICK RATIO: {m.quick_ratio_display}",
+        f"Status: {m.status}",
+        f"{m.interpretation}",
+        "",
+        "MRR COMPONENTS",
+        f"  Growth MRR (New + Expansion): ${m.growth_mrr:,.2f}",
+        f"    New MRR:        ${components.new_mrr:,.2f}  ({m.new_mrr_pct:.1f}%)",
+        f"    Expansion MRR:  ${components.expansion_mrr:,.2f}  ({m.expansion_mrr_pct:.1f}%)",
+        f"  Lost MRR (Churned + Contraction): ${m.lost_mrr:,.2f}",
+        f"    Churned MRR:      ${components.churned_mrr:,.2f}  ({m.churned_mrr_pct:.1f}%)",
+        f"    Contraction MRR:  ${components.contraction_mrr:,.2f}  ({m.contraction_mrr_pct:.1f}%)",
+        "",
+        f"  Net new MRR: ${m.net_new_mrr:,.2f}",
+    ]
+
+    if m.current_mrr is not None:
+        lines.append(f"  Current MRR: ${m.current_mrr:,.2f}")
+    if m.mrr_growth_rate is not None:
+        lines.append(f"  MRR growth rate: {m.mrr_growth_rate:.2f}%")
+    if m.ltv_cac_ratio is not None:
+        lines += [
+            "",
+            "UNIT ECONOMICS",
+            f"  LTV/CAC ratio: {m.ltv_cac_ratio:.2f}x",
+        ]
+        if m.ltv_cac_ratio >= 3:
+            lines.append("  Healthy -- LTV/CAC >= 3x")
+        elif m.ltv_cac_ratio >= 1:
+            lines.append("  Watch -- LTV/CAC between 1x and 3x")
+        else:
+            lines.append("  Critical -- LTV/CAC below 1x")
+
+    lines += [
+        "",
+        "BENCHMARKS",
+        "  Quick Ratio < 1.0 = Critical (net revenue loss)",
+        "  Quick Ratio 1-2   = Watch    (marginal growth)",
+        "  Quick Ratio 2-4   = Healthy  (good efficiency)",
+        "  Quick Ratio > 4   = Excellent (strong growth)",
+        "",
+        "=" * 60,
+    ]
+    return "\n".join(lines)
+
+
+def to_json(m: SaaSMetrics) -> str:
+    """Serialise metrics to JSON."""
+    return json.dumps(asdict(m), indent=2)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    """Entry point."""
+    parser = argparse.ArgumentParser(
+        description="SaaS Metrics Calculator -- Quick Ratio, net MRR, LTV/CAC",
+    )
+    parser.add_argument("--new-mrr", type=float, required=True,
+                        help="New MRR from new customers")
+    parser.add_argument("--expansion", type=float, default=0.0,
+                        help="Expansion MRR from upsells (default: 0)")
+    parser.add_argument("--churned", type=float, required=True,
+                        help="Churned MRR from lost customers")
+    parser.add_argument("--contraction", type=float, default=0.0,
+                        help="Contraction MRR from downgrades (default: 0)")
+    parser.add_argument("--prev-mrr", type=float, default=None,
+                        help="Previous month total MRR (for growth rate)")
+    parser.add_argument("--ltv", type=float, default=None,
+                        help="Customer lifetime value (for LTV/CAC)")
+    parser.add_argument("--cac", type=float, default=None,
+                        help="Customer acquisition cost (for LTV/CAC)")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+
+    args = parser.parse_args()
+
+    if args.new_mrr < 0 or args.churned < 0:
+        print("Error: MRR values must be non-negative", file=sys.stderr)
+        return 2
+
+    components = MRRComponents(
+        new_mrr=args.new_mrr,
+        expansion_mrr=args.expansion,
+        churned_mrr=args.churned,
+        contraction_mrr=args.contraction,
+        previous_mrr=args.prev_mrr,
+    )
+
+    metrics = calculate_metrics(components, ltv=args.ltv, cac=args.cac)
+
+    if args.json:
+        print(to_json(metrics))
+    else:
+        print(format_report(metrics, components))
+
+    exit_code = 0
+    if metrics.status == "Critical":
+        exit_code = 2
+    elif metrics.status == "Watch":
+        exit_code = 1
+    return exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())