arkaos 2.2.2 → 2.3.1

package/scripts/tools/brand_voice_analyzer.py

@@ -0,0 +1,192 @@
+#!/usr/bin/env python3
+"""Brand Voice Analyzer -- score content 0-100 for voice consistency and readability.
+Part of ArkaOS v2 -- stdlib-only, no pip dependencies.
+"""
+from __future__ import annotations
+import argparse, json, re, sys
+from dataclasses import asdict, dataclass, field
+from typing import Dict, List
+
+VOICE_DIMENSIONS: Dict[str, Dict[str, List[str]]] = {
+    "formality": {
+        "formal": ["hereby", "therefore", "furthermore", "pursuant", "regarding",
+                    "accordingly", "henceforth", "notwithstanding", "whereas"],
+        "casual": ["hey", "cool", "awesome", "stuff", "yeah", "gonna", "wanna",
+                    "kinda", "gotta", "yep"],
+    },
+    "tone": {
+        "professional": ["expertise", "solution", "optimize", "leverage", "strategic",
+                         "implement", "framework", "methodology", "deliverable"],
+        "friendly": ["happy", "excited", "love", "enjoy", "together", "share",
+                      "amazing", "wonderful", "great", "fun"],
+    },
+    "perspective": {
+        "authoritative": ["proven", "research shows", "experts agree", "data indicates",
+                          "studies confirm", "evidence suggests"],
+        "conversational": ["you might", "let's explore", "we think", "imagine if",
+                           "have you ever", "picture this"],
+    },
+}
+
+@dataclass
+class SentenceAnalysis:
+    count: int = 0
+    average_length: float = 0.0
+    variety: str = "low"
+    shortest: int = 0
+    longest: int = 0
+
+@dataclass
+class VoiceDimension:
+    dominant: str = ""
+    scores: Dict[str, int] = field(default_factory=dict)
+
+@dataclass
+class AnalysisResult:
+    word_count: int = 0
+    readability_score: float = 0.0
+    readability_grade: str = ""
+    overall_score: int = 0
+    voice_profile: Dict[str, VoiceDimension] = field(default_factory=dict)
+    sentence_analysis: SentenceAnalysis = field(default_factory=SentenceAnalysis)
+    recommendations: List[str] = field(default_factory=list)
+
+def _count_syllables(word: str) -> int:
+    word = word.lower().strip(".,!?;:'\"")
+    count, prev = 0, False
+    for ch in word:
+        v = ch in "aeiou"
+        if v and not prev:
+            count += 1
+        prev = v
+    if word.endswith("e") and count > 1:
+        count -= 1
+    return max(1, count)
+
+
+def _flesch_reading_ease(text: str) -> float:
+    sentences = [s.strip() for s in re.split(r"[.!?]+", text) if s.strip()]
+    words = text.split()
+    if not sentences or not words:
+        return 0.0
+    syllables = sum(_count_syllables(w) for w in words)
+    score = 206.835 - 1.015 * (len(words) / len(sentences)) - 84.6 * (syllables / len(words))
+    return round(max(0.0, min(100.0, score)), 1)
+
+def _readability_grade(score: float) -> str:
+    if score >= 80: return "Easy"
+    if score >= 60: return "Standard"
+    if score >= 40: return "Fairly Difficult"
+    if score >= 20: return "Difficult"
+    return "Very Difficult"
+
+def _analyze_sentences(text: str) -> SentenceAnalysis:
+    sentences = [s.strip() for s in re.split(r"[.!?]+", text) if s.strip()]
+    if not sentences:
+        return SentenceAnalysis()
+    lengths = [len(s.split()) for s in sentences]
+    avg = sum(lengths) / len(lengths)
+    unique = len(set(lengths))
+    variety = "high" if unique >= 5 else ("medium" if unique >= 3 else "low")
+    return SentenceAnalysis(count=len(sentences), average_length=round(avg, 1),
+                            variety=variety, shortest=min(lengths), longest=max(lengths))
+
+def _score_voice(text: str) -> Dict[str, VoiceDimension]:
+    text_lower = text.lower()
+    profile: Dict[str, VoiceDimension] = {}
+    for dimension, categories in VOICE_DIMENSIONS.items():
+        scores = {cat: sum(1 for kw in kws if kw in text_lower) for cat, kws in categories.items()}
+        dominant = max(scores, key=scores.get) if sum(scores.values()) > 0 else "neutral"
+        profile[dimension] = VoiceDimension(dominant=dominant, scores=scores)
+    return profile
+
+def _compute_overall(readability: float, sentence: SentenceAnalysis) -> int:
+    variety_map = {"high": 100, "medium": 60, "low": 30}
+    return round(readability * 0.50 + variety_map.get(sentence.variety, 30) * 0.25
+                 + min(100, sentence.count * 20) * 0.25)
+
+def _generate_recommendations(result: AnalysisResult) -> List[str]:
+    recs: List[str] = []
+    if result.readability_score < 30:
+        recs.append("Simplify language -- shorter words and sentences improve readability.")
+    elif result.readability_score > 80:
+        recs.append("Content is very easy to read -- verify this matches your audience.")
+    if result.sentence_analysis.variety == "low":
+        recs.append("Vary sentence length for better rhythm and engagement.")
+    if result.sentence_analysis.longest > 35:
+        recs.append(f"Longest sentence is {result.sentence_analysis.longest} words -- consider splitting.")
+    if result.word_count < 100:
+        recs.append("Very short content -- consider expanding for depth.")
+    for dim, vd in result.voice_profile.items():
+        if sum(vd.scores.values()) == 0:
+            recs.append(f"No clear {dim} signals detected -- add stronger voice cues.")
+    return recs
+
+def analyze(text: str) -> AnalysisResult:
+    """Run the full brand voice analysis on *text*."""
+    readability = _flesch_reading_ease(text)
+    sentence = _analyze_sentences(text)
+    result = AnalysisResult(word_count=len(text.split()), readability_score=readability,
+                            readability_grade=_readability_grade(readability),
+                            voice_profile=_score_voice(text), sentence_analysis=sentence)
+    result.overall_score = _compute_overall(readability, sentence)
+    result.recommendations = _generate_recommendations(result)
+    return result
+
+def _format_text(result: AnalysisResult) -> str:
+    lines = ["=" * 60,
+             f"  BRAND VOICE ANALYSIS   Overall Score: {result.overall_score}/100",
+             "=" * 60,
+             f"  Word Count:       {result.word_count}",
+             f"  Readability:      {result.readability_score}/100 ({result.readability_grade})",
+             "", "  Voice Profile:"]
+    for dim, vd in result.voice_profile.items():
+        detail = ", ".join(f"{k}={v}" for k, v in vd.scores.items())
+        lines.append(f"    {dim:<16} {vd.dominant:<16} ({detail})")
+    lines += ["", "  Sentence Analysis:",
+              f"    Count:          {result.sentence_analysis.count}",
+              f"    Avg length:     {result.sentence_analysis.average_length} words",
+              f"    Variety:        {result.sentence_analysis.variety}",
+              f"    Shortest:       {result.sentence_analysis.shortest} words",
+              f"    Longest:        {result.sentence_analysis.longest} words",
+              "", "  Recommendations:"]
+    for rec in result.recommendations:
+        lines.append(f"    - {rec}")
+    lines.append("=" * 60)
+    return "\n".join(lines)
+
+def main() -> int:
+    """Entry point. Returns exit code: 0=success, 1=warnings, 2=errors."""
+    parser = argparse.ArgumentParser(
+        description="Brand Voice Analyzer -- score content 0-100 for voice consistency and readability.")
+    parser.add_argument("file", nargs="?", default=None,
+                        help="Text file to analyze (reads stdin if omitted)")
+    parser.add_argument("--json", action="store_true", help="Output results as JSON")
+    args = parser.parse_args()
+    try:
+        if args.file:
+            with open(args.file, "r", encoding="utf-8") as fh:
+                text = fh.read()
+        elif not sys.stdin.isatty():
+            text = sys.stdin.read()
+        else:
+            parser.print_help()
+            return 2
+    except FileNotFoundError:
+        print(f"Error: file not found -- {args.file}", file=sys.stderr)
+        return 2
+    except OSError as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 2
+    if not text.strip():
+        print("Error: input is empty.", file=sys.stderr)
+        return 2
+    result = analyze(text)
+    if args.json:
+        print(json.dumps(asdict(result), indent=2))
+    else:
+        print(_format_text(result))
+    return 1 if result.overall_score < 40 else 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tools/dcf_calculator.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""DCF Calculator -- ArkaOS v2.
+
+Discounted Cash Flow valuation with projected FCF, terminal value,
+enterprise value, equity value, and WACC-vs-terminal-growth sensitivity table.
+
+Usage:
+    python dcf_calculator.py --revenue 10000000 --growth 0.15 --margin 0.12 --wacc 0.10
+    python dcf_calculator.py --revenue 5e6 --growth 0.20 --margin 0.15 --wacc 0.09 --json
+    python dcf_calculator.py --revenue 5e6 --growth 0.20 --margin 0.15 --wacc 0.09 --net-debt 1e6
+"""
+from __future__ import annotations
+import argparse, json, sys
+from dataclasses import dataclass, field, asdict
+from typing import Dict, List, Optional
+
+@dataclass
+class Projection:
+    """Single year projection."""
+    year: int; revenue: float; fcf: float; discount_factor: float; pv_fcf: float
+
+@dataclass
+class DCFResult:
+    """Complete DCF valuation output."""
+    wacc: float; terminal_growth: float; years: int
+    projections: List[Projection]
+    terminal_value: float; pv_terminal: float; pv_fcf_total: float
+    enterprise_value: float; net_debt: float; equity_value: float
+    shares: Optional[float] = None; value_per_share: Optional[float] = None
+
+def run_dcf(revenue: float, growth: float, margin: float, wacc: float,
+            terminal_growth: float = 0.025, years: int = 5,
+            net_debt: float = 0.0, shares: Optional[float] = None) -> DCFResult:
+    """Run a full DCF valuation and return structured results."""
+    projections: List[Projection] = []
+    pv_fcf_total, current_revenue = 0.0, revenue
+    for yr in range(1, years + 1):
+        current_revenue *= 1 + growth
+        fcf = current_revenue * margin
+        df = (1 + wacc) ** yr
+        pv = fcf / df
+        pv_fcf_total += pv
+        projections.append(Projection(year=yr, revenue=current_revenue, fcf=fcf,
+                                      discount_factor=df, pv_fcf=pv))
+    terminal_fcf = projections[-1].fcf
+    tv = (terminal_fcf * (1 + terminal_growth)) / (wacc - terminal_growth)
+    pv_tv = tv / ((1 + wacc) ** years)
+    ev = pv_fcf_total + pv_tv
+    eq = ev - net_debt
+    vps = (eq / shares) if shares and shares > 0 else None
+    return DCFResult(wacc=wacc, terminal_growth=terminal_growth, years=years,
+        projections=projections, terminal_value=tv, pv_terminal=pv_tv,
+        pv_fcf_total=pv_fcf_total, enterprise_value=ev, net_debt=net_debt,
+        equity_value=eq, shares=shares, value_per_share=vps)
+
+def sensitivity_table(result: DCFResult, steps: int = 5) -> Dict:
+    """Build a WACC vs terminal-growth sensitivity grid for enterprise value."""
+    wacc_range = [round(result.wacc + (i - steps // 2) * 0.01, 4) for i in range(steps)]
+    growth_range = [round(result.terminal_growth + (i - steps // 2) * 0.005, 4)
+                    for i in range(steps)]
+    terminal_fcf, years = result.projections[-1].fcf, result.years
+    table: List[List[Optional[float]]] = []
+    for w in wacc_range:
+        row: List[Optional[float]] = []
+        for g in growth_range:
+            if w <= g or w <= 0:
+                row.append(None); continue
+            pv_fcf = sum(p.fcf / ((1 + w) ** p.year) for p in result.projections)
+            tv = (terminal_fcf * (1 + g)) / (w - g)
+            row.append(round(pv_fcf + tv / ((1 + w) ** years), 2))
+        table.append(row)
+    return {"wacc_values": wacc_range, "growth_values": growth_range, "ev_table": table}
+
+def _fmt(val: float) -> str:
+    """Format a monetary value for display."""
+    if abs(val) >= 1e9: return f"${val / 1e9:,.2f}B"
+    if abs(val) >= 1e6: return f"${val / 1e6:,.2f}M"
+    if abs(val) >= 1e3: return f"${val / 1e3:,.1f}K"
+    return f"${val:,.2f}"
+
+def format_text(result: DCFResult, sens: Dict) -> str:
+    """Render human-readable report."""
+    lines = ["=" * 65, "DCF VALUATION ANALYSIS", "=" * 65, "",
+        f"WACC: {result.wacc * 100:.2f}%  |  Terminal growth: "
+        f"{result.terminal_growth * 100:.2f}%  |  Projection: {result.years} years",
+        "", "PROJECTED CASH FLOWS",
+        f"  {'Year':>5}  {'Revenue':>14}  {'FCF':>14}  {'PV(FCF)':>14}",
+        "  " + "-" * 52]
+    for p in result.projections:
+        lines.append(f"  {p.year:>5}  {_fmt(p.revenue):>14}  "
+                     f"{_fmt(p.fcf):>14}  {_fmt(p.pv_fcf):>14}")
+    lines += ["", "VALUATION SUMMARY",
+        f"  PV of projected FCFs:  {_fmt(result.pv_fcf_total)}",
+        f"  Terminal value:        {_fmt(result.terminal_value)}",
+        f"  PV of terminal value:  {_fmt(result.pv_terminal)}",
+        f"  Enterprise value:      {_fmt(result.enterprise_value)}",
+        f"  Net debt:              {_fmt(result.net_debt)}",
+        f"  Equity value:          {_fmt(result.equity_value)}"]
+    if result.value_per_share is not None:
+        lines.append(f"  Value per share:       ${result.value_per_share:,.2f}")
+    lines += ["", "SENSITIVITY: Enterprise Value (WACC vs Terminal Growth)", ""]
+    header = f"  {'WACC \\\\ g':>10}"
+    for g in sens["growth_values"]:
+        header += f"  {g * 100:>7.2f}%"
+    lines.append(header)
+    lines.append("  " + "-" * (10 + 10 * len(sens["growth_values"])))
+    for i, w in enumerate(sens["wacc_values"]):
+        row = f"  {w * 100:>9.2f}%"
+        for val in sens["ev_table"][i]:
+            row += f"  {_fmt(val):>8}" if val is not None else f"  {'N/A':>8}"
+        lines.append(row)
+    lines += ["", "=" * 65]
+    return "\n".join(lines)
+
+def to_json(result: DCFResult, sens: Dict) -> str:
+    """Serialise to JSON."""
+    payload = asdict(result)
+    payload["sensitivity"] = sens
+    for p in payload["projections"]:
+        for k in ("revenue", "fcf", "pv_fcf", "discount_factor"):
+            p[k] = round(p[k], 2)
+    for k in ("terminal_value", "pv_terminal", "pv_fcf_total",
+              "enterprise_value", "equity_value"):
+        payload[k] = round(payload[k], 2)
+    if payload["value_per_share"] is not None:
+        payload["value_per_share"] = round(payload["value_per_share"], 2)
+    return json.dumps(payload, indent=2)
+
+def main() -> int:
+    """Entry point."""
+    parser = argparse.ArgumentParser(
+        description="DCF Valuation Calculator -- enterprise and equity valuation")
+    parser.add_argument("--revenue", type=float, required=True,
+                        help="Base annual revenue (e.g. 10000000 or 1e7)")
+    parser.add_argument("--growth", type=float, required=True,
+                        help="Annual revenue growth rate as decimal (e.g. 0.15)")
+    parser.add_argument("--margin", type=float, required=True,
+                        help="Free cash flow margin as decimal (e.g. 0.12)")
+    parser.add_argument("--wacc", type=float, required=True,
+                        help="Weighted average cost of capital (e.g. 0.10)")
+    parser.add_argument("--terminal-growth", type=float, default=0.025,
+                        help="Terminal growth rate (default: 0.025)")
+    parser.add_argument("--years", type=int, default=5,
+                        help="Projection years (default: 5)")
+    parser.add_argument("--net-debt", type=float, default=0.0,
+                        help="Net debt to subtract for equity value (default: 0)")
+    parser.add_argument("--shares", type=float, default=None,
+                        help="Shares outstanding for per-share value")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+    if args.wacc <= args.terminal_growth:
+        print("Error: WACC must be greater than terminal growth rate", file=sys.stderr)
+        return 2
+    if args.revenue <= 0:
+        print("Error: revenue must be positive", file=sys.stderr)
+        return 2
+    result = run_dcf(revenue=args.revenue, growth=args.growth, margin=args.margin,
+                     wacc=args.wacc, terminal_growth=args.terminal_growth,
+                     years=args.years, net_debt=args.net_debt, shares=args.shares)
+    sens = sensitivity_table(result)
+    if args.json:
+        print(to_json(result, sens))
+    else:
+        print(format_text(result, sens))
+    return 0
+
+if __name__ == "__main__":
+    sys.exit(main())

package/scripts/tools/headline_scorer.py

@@ -0,0 +1,215 @@
+#!/usr/bin/env python3
+"""Headline Scorer -- rates headlines 0-100 across 6 dimensions.
+Part of ArkaOS v2 -- stdlib-only, no pip dependencies.
+"""
+from __future__ import annotations
+import argparse, json, re, sys
+from dataclasses import asdict, dataclass, field
+from typing import Dict, List, Tuple
+
+POWER_WORDS = frozenset({
+    # urgency / scarcity
+    "now", "today", "instantly", "immediately", "urgent", "limited",
+    "exclusive", "last", "hurry", "deadline", "expires", "fast",
+    # value / benefit
+    "free", "save", "proven", "guaranteed", "results", "boost",
+    "increase", "grow", "maximize", "unlock", "secret", "revealed",
+    "transform", "master", "ultimate", "best", "top", "powerful",
+    # curiosity / intrigue
+    "discover", "uncover", "surprising", "shocking", "hidden",
+    "unknown", "insider", "hack", "trick", "truth",
+    # authority
+    "experts", "researchers", "scientists", "officially", "certified",
+    "award-winning", "world-class",
+    # ease
+    "easy", "simple", "effortless", "quick", "step-by-step",
+    "foolproof", "beginner", "without",
+    # negative triggers
+    "avoid", "stop", "never", "mistake", "fail", "warning", "danger",
+    "worst", "deadly", "risky",
+})
+
+EMOTIONAL_TRIGGERS = frozenset({
+    "love", "hate", "fear", "hope", "joy", "pain", "anger", "envy",
+    "trust", "doubt", "regret", "pride", "shame", "relief", "success",
+    "failure", "happiness", "frustration", "excitement", "anxiety",
+    "lonely", "powerful", "confident", "inspired",
+})
+
+JARGON_WORDS = frozenset({
+    "synergy", "leverage", "disruptive", "paradigm", "scalable",
+    "bandwidth", "holistic", "ecosystem", "utilize", "facilitate",
+    "ideate", "incentivize", "stakeholders", "deliverables",
+    "actionable", "bespoke", "granular",
+})
+
+WEIGHTS: Dict[str, float] = {"power_words": 0.25, "emotional_triggers": 0.15,
+    "numbers": 0.15, "length": 0.20, "specificity": 0.15, "clarity": 0.10}
+
+@dataclass
+class DimensionScore:
+    score: int
+    weight: str
+    detail: str
+
+@dataclass
+class HeadlineResult:
+    headline: str
+    overall_score: int = 0
+    grade: str = ""
+    breakdown: Dict[str, DimensionScore] = field(default_factory=dict)
+
+def _tokenize(headline: str) -> List[str]:
+    return re.findall(r"\b\w+(?:[-']\w+)*\b", headline.lower())
+
+
+def _score_power_words(tokens: List[str]) -> Tuple[int, List[str]]:
+    found = [t for t in tokens if t in POWER_WORDS]
+    score = min(100, len(found) * 35 + (10 if found else 0))
+    return score, found
+
+
+def _score_emotional(tokens: List[str]) -> Tuple[int, List[str]]:
+    found = [t for t in tokens if t in EMOTIONAL_TRIGGERS]
+    score = min(100, len(found) * 50)
+    return score, found
+
+
+def _score_numbers(headline: str) -> Tuple[int, List[str]]:
+    nums = re.findall(r"\b\d+(?:[,.]\d+)?%?\b", headline)
+    return (100 if nums else 0), nums
+
+
+def _score_length(tokens: List[str]) -> Tuple[int, str]:
+    n = len(tokens)
+    if 6 <= n <= 12:
+        return 100, f"{n} words -- optimal (6-12)"
+    if n < 6:
+        return max(0, 40 + (n - 1) * 12), f"{n} words -- too short (6-12 optimal)"
+    return max(0, 100 - (n - 12) * 10), f"{n} words -- too long (6-12 optimal)"
+
+
+def _score_specificity(headline: str) -> Tuple[int, List[str]]:
+    signals: List[str] = []
+    if re.search(r"\b\d+\b", headline):
+        signals.append("number")
+    if re.search(r"\b(?:in \d+|within \d+|\d+ (?:days?|weeks?|months?|hours?|minutes?))\b", headline, re.I):
+        signals.append("timeframe")
+    if re.search(r"\b(?:how to|step|guide|checklist|strategy|system|framework|formula)\b", headline, re.I):
+        signals.append("concrete format")
+    if re.search(r"\b\d+%\b", headline):
+        signals.append("percentage")
+    return min(100, len(signals) * 34), signals
+
+
+def _score_clarity(tokens: List[str]) -> Tuple[int, List[str]]:
+    found = [t for t in tokens if t in JARGON_WORDS]
+    return max(0, 100 - len(found) * 30), found
+
+
+# ---------------------------------------------------------------------------
+# Core scoring
+# ---------------------------------------------------------------------------
+
+def score_headline(headline: str) -> HeadlineResult:
+    """Score a single headline across all dimensions."""
+    tokens = _tokenize(headline)
+    pw_s, pw_f = _score_power_words(tokens)
+    et_s, et_f = _score_emotional(tokens)
+    nm_s, nm_f = _score_numbers(headline)
+    ln_s, ln_n = _score_length(tokens)
+    sp_s, sp_f = _score_specificity(headline)
+    cl_s, cl_f = _score_clarity(tokens)
+
+    breakdown = {
+        "power_words": DimensionScore(pw_s, "25%", f"found: {', '.join(pw_f) or 'none'}"),
+        "emotional_triggers": DimensionScore(et_s, "15%", f"found: {', '.join(et_f) or 'none'}"),
+        "numbers": DimensionScore(nm_s, "15%", f"found: {', '.join(nm_f) or 'none'}"),
+        "length": DimensionScore(ln_s, "20%", ln_n),
+        "specificity": DimensionScore(sp_s, "15%", f"signals: {', '.join(sp_f) or 'none'}"),
+        "clarity": DimensionScore(cl_s, "10%", f"jargon: {', '.join(cl_f) or 'none'}"),
+    }
+
+    overall = round(sum(breakdown[k].score * WEIGHTS[k] for k in WEIGHTS))
+    grade = "A" if overall >= 85 else "B" if overall >= 70 else "C" if overall >= 55 else "D" if overall >= 40 else "F"
+
+    return HeadlineResult(headline=headline, overall_score=overall, grade=grade, breakdown=breakdown)
+
+
+# ---------------------------------------------------------------------------
+# Output
+# ---------------------------------------------------------------------------
+
+def _format_text(results: List[HeadlineResult]) -> str:
+    """Human-readable multi-headline report."""
+    lines: List[str] = []
+    for r in results:
+        lines.append("-" * 60)
+        lines.append(f"  Headline: {r.headline}")
+        lines.append(f"  Score:    {r.overall_score}/100   Grade: {r.grade}")
+        lines.append("-" * 60)
+        for name, ds in r.breakdown.items():
+            bar_len = round(ds.score / 10)
+            bar = "#" * bar_len + "." * (10 - bar_len)
+            lines.append(f"  {name:<20} [{bar}] {ds.score:>3}/100  {ds.detail}")
+        lines.append("")
+
+    if len(results) > 1:
+        avg = round(sum(r.overall_score for r in results) / len(results))
+        best = max(results, key=lambda r: r.overall_score)
+        lines.append("=" * 60)
+        lines.append(f"  {len(results)} headlines analyzed  |  Avg score: {avg}/100")
+        lines.append(f"  Best: \"{best.headline[:50]}\" ({best.overall_score}/100)")
+        lines.append("=" * 60)
+    return "\n".join(lines)
+
+
+# ---------------------------------------------------------------------------
+# CLI
+# ---------------------------------------------------------------------------
+
+def main() -> int:
+    """Entry point. Returns 0=success, 1=warnings, 2=errors."""
+    parser = argparse.ArgumentParser(
+        description="Headline Scorer -- rates headlines 0-100 across 6 dimensions.",
+    )
+    parser.add_argument("headline", nargs="?", help="Single headline to score")
+    parser.add_argument("--file", help="Text file with one headline per line")
+    parser.add_argument("--json", action="store_true", help="Output as JSON")
+    args = parser.parse_args()
+
+    if args.headline:
+        headlines = [args.headline]
+    elif args.file:
+        try:
+            with open(args.file, "r", encoding="utf-8") as fh:
+                headlines = [ln.strip() for ln in fh if ln.strip()]
+        except FileNotFoundError:
+            print(f"Error: file not found -- {args.file}", file=sys.stderr)
+            return 2
+        except OSError as exc:
+            print(f"Error: {exc}", file=sys.stderr)
+            return 2
+    elif not sys.stdin.isatty():
+        headlines = [ln.strip() for ln in sys.stdin if ln.strip()]
+    else:
+        parser.print_help()
+        return 2
+
+    if not headlines:
+        print("Error: no headlines provided.", file=sys.stderr)
+        return 2
+
+    results = [score_headline(h) for h in headlines]
+
+    if args.json:
+        print(json.dumps([asdict(r) for r in results], indent=2))
+    else:
+        print(_format_text(results))
+
+    avg = sum(r.overall_score for r in results) / len(results)
+    return 1 if avg < 50 else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())