arkaos 2.0.0 → 2.0.2

package/README.md

@@ -1,22 +1,25 @@
 # ArkaOS
 
-**The Operating System for AI Agent Teams.** 56 specialized agents across 16 departments, backed by 116 enterprise frameworks. One install. Full company capability.
+**The Operating System for AI Agent Teams.** 62 agents across 17 departments, 250+ skills backed by 116 enterprise frameworks, 8 Python CLI tools. One install.
 
 ```
 npx arkaos install
 ```
 
+[![Tests](https://github.com/andreagroferreira/arka-os/actions/workflows/test.yml/badge.svg)](https://github.com/andreagroferreira/arka-os/actions) [![npm](https://img.shields.io/npm/v/arkaos)](https://www.npmjs.com/package/arkaos) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
 ## What ArkaOS Does
 
-ArkaOS orchestrates AI agents that cover every business function. Not just code. Marketing, brand, finance, strategy, sales, operations, product management, e-commerce, communities, content, and more.
+ArkaOS orchestrates AI agents that cover every business function. Not just code. Marketing, brand, finance, strategy, sales, operations, compliance, product management, e-commerce, communities, content, and more.
 
-Each agent has a defined role, personality, expertise, and authority level. They work in squads, follow structured workflows, and every output passes through a mandatory Quality Gate before reaching you.
+Each agent has a defined role, personality, expertise, and authority level. They work in squads, follow YAML workflows, and every output passes through a mandatory Quality Gate.
 
 ```
 You: "validate my saas idea for a scheduling tool"
+
 ArkaOS: → Routes to SaaS department
         → Tiago (SaaS Strategist) leads validation workflow
-        → Market sizing, competitor analysis, business model, pricing, MVP scope
+        → Market sizing, competitor analysis, business model, pricing
         → Financial viability check by Leonor (Financial Analyst)
         → Quality Gate: Marta, Eduardo, Francisca review
         → Delivers: validated report with go/no-go recommendation
@@ -25,108 +28,127 @@ ArkaOS: → Routes to SaaS department
 ## Install
 
 ```bash
-# Auto-detects your AI runtime
-npx arkaos install
-
-# Or specify the runtime
+npx arkaos install              # auto-detects runtime
 npx arkaos install --runtime claude-code
 npx arkaos install --runtime codex
 npx arkaos install --runtime gemini
 npx arkaos install --runtime cursor
 ```
 
-Requires: Node.js 18+ and Python 3.11+
-
-## 16 Departments, 56 Agents
-
-| Department | Prefix | Agents | What It Does |
-|-----------|--------|--------|-------------|
-| Development | `/dev` | 9 | Features, APIs, architecture, security, CI/CD, testing |
-| Marketing | `/mkt` | 4 | SEO, paid ads, content, email, growth loops |
-| Brand & Design | `/brand` | 4 | Brand identity, UX/UI, design systems, naming |
-| Finance | `/fin` | 3 | Financial models, valuation, fundraising, unit economics |
-| Strategy | `/strat` | 3 | Five Forces, Blue Ocean, BMC, competitive intelligence |
-| E-Commerce | `/ecom` | 4 | Store optimization, CRO, RFM, pricing, marketplace |
-| Knowledge | `/kb` | 3 | Research, Zettelkasten, personas, Obsidian curation |
-| Operations | `/ops` | 2 | Automation (n8n, Zapier), SOPs, bottleneck analysis |
-| Project Mgmt | `/pm` | 3 | Scrum, Kanban, Shape Up, discovery, roadmaps |
-| SaaS | `/saas` | 3 | Validation, metrics, PLG, pricing, customer success |
-| Landing Pages | `/landing` | 4 | Sales copy, funnels, offers, launches, affiliates |
-| Content | `/content` | 4 | Viral design, hooks, scripts, repurposing (1 to 30+) |
-| Communities | `/community` | 2 | Telegram, Discord, Skool groups, membership monetization |
-| Sales | `/sales` | 2 | Pipeline, proposals, SPIN selling, negotiation |
-| Leadership | `/lead` | 2 | Team health, hiring, feedback, OKRs, culture |
-| Organization | `/org` | 1 | Org design, team topologies, scaling operations |
-| **Quality Gate** | (auto) | 3 | Mandatory review on every workflow. Veto power. |
+Requires Node.js 18+ and Python 3.11+.
+
+**Upgrading from v1?** Run `npx arkaos migrate`
+
+## 17 Departments, 62 Agents
+
+| Department | Prefix | Agents | Skills | What It Does |
+|-----------|--------|--------|--------|-------------|
+| Development | `/dev` | 9 | 41 | Features, APIs, architecture, security, CI/CD, RAG, agents |
+| Marketing | `/mkt` | 4 | 14 | SEO, paid ads, email, growth loops, programmatic SEO |
+| Brand & Design | `/brand` | 4 | 12 | Brand identity, UX/UI, design systems, naming |
+| Finance | `/fin` | 3 | 8 | DCF valuation, unit economics, CISO advisory |
+| Strategy | `/strat` | 3 | 9 | Five Forces, Blue Ocean, BMC, CTO/board advisory |
+| E-Commerce | `/ecom` | 4 | 12 | Store optimization, CRO, RFM, pricing |
+| Knowledge | `/kb` | 3 | 12 | Research, Zettelkasten, personas, Obsidian |
+| Operations | `/ops` | 2 | 15 | Automation, SOPs, GDPR, ISO 27001, SOC 2, risk |
+| Project Mgmt | `/pm` | 3 | 13 | Scrum, Shape Up, discovery, agile PO |
+| SaaS | `/saas` | 3 | 15 | Validation, metrics, PLG, scaffolding |
+| Landing Pages | `/landing` | 4 | 15 | Sales copy, funnels, offers, page generation |
+| Content | `/content` | 4 | 14 | Viral design, hooks, scripts, repurposing |
+| Communities | `/community` | 2 | 14 | Groups, membership, gamification |
+| Sales | `/sales` | 2 | 10 | Pipeline, SPIN selling, negotiation |
+| Leadership | `/lead` | 2 | 10 | Team health, OKRs, culture, hiring |
+| Organization | `/org` | 1 | 10 | Org design, team topologies |
+| **Quality Gate** | (auto) | 3 | — | Mandatory on every workflow. Veto power. |
 
 ## How It Works
 
 **Just describe what you need.** ArkaOS routes it to the right squad.
 
 ```
-"add user authentication"     → /dev feature
-"create a brand for my app"   → /brand identity
-"plan our Q3 budget"          → /fin budget
-"design a sales funnel"       → /landing funnel
-"grow my Discord community"   → /community grow
-"write viral hooks for TikTok"→ /content hook
+"add user authentication"      → /dev feature
+"create a brand for my app"    → /brand identity
+"plan our Q3 budget"           → /fin budget
+"design a sales funnel"        → /landing funnel
+"are we GDPR compliant?"       → /ops gdpr-compliance
+"score these headlines"        → python scripts/tools/headline_scorer.py
 ```
 
-Or use explicit commands: `/dev feature "user auth"`, `/saas validate "scheduling tool"`, `/strat blue-ocean "AI tools market"`
+Or use explicit commands: `/dev feature "user auth"`, `/saas validate "scheduling tool"`
+
+## Python CLI Tools
+
+8 stdlib-only tools for quantitative analysis. No dependencies.
+
+```bash
+python scripts/tools/headline_scorer.py "10x Your Revenue" --json
+python scripts/tools/seo_checker.py page.html --json
+python scripts/tools/rice_prioritizer.py features.json --json
+python scripts/tools/dcf_calculator.py --revenue 1000000 --growth 20 --json
+python scripts/tools/tech_debt_analyzer.py src/ --json
+python scripts/tools/saas_metrics.py --new-mrr 50000 --json
+python scripts/tools/brand_voice_analyzer.py content.txt --json
+python scripts/tools/okr_cascade.py growth --json
+```
 
 ## Agent DNA
 
-Every agent has a complete behavioral profile built from 4 frameworks:
+Every agent has a behavioral profile from 4 frameworks:
 
-- **DISC** — How they communicate (Driver, Inspirer, Supporter, Analyst)
+- **DISC** — How they communicate
 - **Enneagram** — What motivates them (9 types with wings)
-- **Big Five** — Personality traits on a 0-100 scale
-- **MBTI** — How they process information (16 types, cognitive functions)
-
-This creates agents with consistent, realistic personalities that communicate differently based on their role and the situation.
+- **Big Five** — Personality traits (0-100 scale)
+- **MBTI** — How they process information
 
 ## Quality Gate
 
-Nothing reaches you without approval from all three reviewers:
+Nothing reaches you without all three reviewers:
+
+- **Marta** (CQO) — orchestrates and issues final verdict
+- **Eduardo** — text quality: spelling, grammar, tone, AI patterns
+- **Francisca** — technical quality: code, tests, UX, security
 
-- **Marta** (CQO) orchestrates the review and issues the final verdict
-- **Eduardo** reviews all text: spelling, grammar, tone, AI patterns
-- **Francisca** reviews all technical output: code quality, tests, UX, security
+APPROVED or REJECTED. No exceptions.
 
-Binary verdict: APPROVED or REJECTED. No exceptions. No soft approvals.
+## The Conclave
+
+Personal AI advisory board with 20 real-world advisor personas (Munger, Dalio, Bezos, Naval, Jobs, Sinek, etc.). Matched to your behavioral DNA via 17-question profiling.
+
+```
+/arka conclave         # Start profiling
+/arka conclave ask     # Ask all advisors
+/arka conclave debate  # Advisors debate a topic
+```
 
 ## Enterprise Frameworks
 
-ArkaOS agents don't improvise. They apply validated frameworks:
+ArkaOS agents apply validated frameworks, not generic prompts:
 
 | Area | Frameworks |
 |------|-----------|
-| Development | Clean Code, SOLID, DDD, TDD, DORA Metrics, OWASP Top 10 |
+| Development | Clean Code, SOLID, DDD, TDD, DORA, OWASP, MITRE ATT&CK |
 | Branding | Primal Branding, StoryBrand, 12 Archetypes, Positioning |
 | Strategy | Porter's Five Forces, Blue Ocean, BMC, Wardley Maps, 7 Powers |
-| Finance | DCF Valuation, Unit Economics, COSO ERM, FP&A, Venture Deals |
+| Finance | DCF Valuation, Unit Economics, COSO ERM, ALE Risk Quantification |
 | Marketing | AARRR, Growth Loops, Schwartz 5 Levels, PLG, STEPPS |
-| GTM/Launch | Hormozi Grand Slam, Value Ladder, PLF, Crossing the Chasm |
-| Organization | Team Topologies, Five Dysfunctions, OKRs, Netflix Culture |
-| PM | Scrum, Kanban, Shape Up, Continuous Discovery, Monte Carlo |
+| Compliance | GDPR, ISO 27001, SOC 2, ISO 31000, ISO 9001 |
+| PM | Scrum, Kanban, Shape Up, Continuous Discovery, RICE |
 
 ## Multi-Runtime
 
-ArkaOS works with any AI coding tool:
-
-| Runtime | Status | Features |
-|---------|--------|----------|
-| Claude Code | Primary | Hooks, subagents, MCP, 1M context |
-| Codex CLI | Supported | Subagents, sandboxed execution |
-| Gemini CLI | Supported | Subagents, MCP, 1M context |
-| Cursor | Supported | Agent mode, MCP |
+| Runtime | Status |
+|---------|--------|
+| Claude Code | Primary — hooks, subagents, MCP, 1M context |
+| Codex CLI | Supported — subagents, sandboxed execution |
+| Gemini CLI | Supported — subagents, MCP, 1M context |
+| Cursor | Supported — agent mode, MCP |
 
 ## Architecture
 
 ```
 User Input
   ↓
-Synapse (8-layer context injection, <1ms)
+Synapse (8-layer context injection)
   ↓
 Orchestrator (/do → department routing)
   ↓
@@ -134,21 +156,25 @@ Squad (YAML workflow with phases and gates)
   ↓
 Quality Gate (Marta + Eduardo + Francisca)
   ↓
-Obsidian (all output saved to vault)
+Output (Obsidian vault + structured deliverables)
 ```
 
-Built with: Python core engine, Node.js installer, Bash hooks, YAML workflows.
+Built with: Python core engine, Node.js installer, Bash hooks, YAML workflows, 1688 tests.
 
-## Community & Pro
+## Commands
 
-**Community Edition** (this repo): 56 agents, 16 departments, ~216 commands, full workflow engine.
+```bash
+npx arkaos install      # Install
+npx arkaos update       # Update to latest
+npx arkaos migrate      # Migrate from v1
+npx arkaos doctor       # Health check
+npx arkaos uninstall    # Remove
+```
 
-**Pro** (coming soon): Additional agents, premium skills, knowledge packs, priority support.
+## Contributing
 
-## License
+See [CONTRIBUTING.md](.github/CONTRIBUTING.md). PRs welcome — all changes require review.
 
-MIT
-
----
+## License
 
-**ArkaOS** — WizardingCode
+MIT — [WizardingCode](https://wizardingcode.com)

package/VERSION

@@ -1 +1 @@
-2.0.0
+2.0.2

package/bin/arkaos

@@ -6,7 +6,7 @@
 
 set -euo pipefail
 
-VERSION="2.0.0-alpha.1"
+VERSION=$(node -p "require('$(dirname "$(readlink -f "$0")")/../package.json').version" 2>/dev/null || echo "2.0.0")
 INSTALL_DIR="${HOME}/.arkaos"
 REPO_ROOT=""
 

package/config/constitution.yaml

@@ -118,6 +118,10 @@ enforcement_levels:
       - id: complexity-assessment
         rule: "Assess task complexity before starting. Route to appropriate workflow tier."
 
+      - id: communication-standard
+        rule: "Bottom-line first output. Lead with answer, then why, then how. Confidence tags on assessments."
+        enforcement: "See config/standards/communication.md for full standard"
+
 tier_hierarchy:
   description: "Agent authority levels inspired by SpaceX/Google/Anthropic org structures"
   tiers:

package/config/hooks/user-prompt-submit-v2.sh

@@ -19,7 +19,18 @@ _hook_ms() {
 }
 
 # ─── Paths ───────────────────────────────────────────────────────────────
-ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+# Resolve ARKAOS_ROOT: env var → .repo-path → npm package → fallback
+if [ -n "${ARKAOS_ROOT:-}" ]; then
+  : # already set
+elif [ -f "$HOME/.arkaos/.repo-path" ]; then
+  ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+elif [ -d "$HOME/.arkaos" ]; then
+  ARKAOS_ROOT="$HOME/.arkaos"
+else
+  ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+fi
+export ARKAOS_ROOT
+
 CACHE_DIR="/tmp/arkaos-context-cache"
 CACHE_TTL=300  # Constitution cache: 5 minutes
 
@@ -35,46 +46,17 @@ if [ -z "$user_input" ]; then
   user_input=$(echo "$input" | head -c 2000)
 fi
 
-# ─── Try Python Synapse engine first ─────────────────────────────────────
+# ─── Try Python Synapse bridge first ────────────────────────────────────
 python_result=""
-if command -v python3 &>/dev/null; then
-  python_result=$(python3 -c "
-import sys, os
-sys.path.insert(0, '${ARKAOS_ROOT}')
-try:
-    from core.synapse.engine import create_default_engine
-    from core.synapse.layers import PromptContext
-    from core.governance.constitution import load_constitution
-    import subprocess
+BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
 
-    # Load constitution for L0
-    const_path = '${ARKAOS_ROOT}/config/constitution.yaml'
-    compressed = ''
-    if os.path.exists(const_path):
-        c = load_constitution(const_path)
-        compressed = c.compress_for_context()
+if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
+  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
+    | ARKAOS_ROOT="$ARKAOS_ROOT" python3 "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
 
-    # Detect git branch
-    branch = ''
-    try:
-        branch = subprocess.run(['git', 'rev-parse', '--abbrev-ref', 'HEAD'],
-                                capture_output=True, text=True, timeout=2).stdout.strip()
-    except Exception:
-        pass
-
-    # Create engine and inject
-    engine = create_default_engine(constitution_compressed=compressed)
-    ctx = PromptContext(
-        user_input='''${user_input}''',
-        cwd=os.getcwd(),
-        git_branch=branch,
-    )
-    result = engine.inject(ctx)
-    print(result.context_string)
-except Exception as e:
-    print(f'[arkaos:error] {e}', file=sys.stderr)
-    print('')
-" 2>/dev/null)
+  if [ -n "$bridge_output" ]; then
+    python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
+  fi
 fi
 
 # ─── Fallback: Bash-only context (if Python unavailable) ────────────────

package/core/budget/__init__.py

@@ -0,0 +1,6 @@
+"""Token budget system — tracking and enforcement for agent operations."""
+
+from core.budget.schema import BudgetConfig, BudgetUsage, BudgetSummary, TierBudget
+from core.budget.manager import BudgetManager
+
+__all__ = ["BudgetConfig", "BudgetUsage", "BudgetSummary", "TierBudget", "BudgetManager"]

package/core/budget/manager.py

@@ -0,0 +1,193 @@
+"""Budget manager — track, enforce, and report on token budgets."""
+
+import json
+from datetime import date, datetime
+from pathlib import Path
+from typing import Optional
+
+from core.budget.schema import BudgetConfig, BudgetSummary, BudgetUsage, TierBudget
+
+
+class BudgetManager:
+    """Manages token budget allocation, tracking, and enforcement.
+
+    Budgets are tier-based with monthly reset. Usage is persisted to JSON.
+    Tier 0 agents have unlimited budgets. Other tiers need Tier 0 approval
+    when usage exceeds the approval threshold (default 80%).
+    """
+
+    def __init__(self, storage_path: str | Path = "", config: BudgetConfig | None = None) -> None:
+        self._config = config or BudgetConfig()
+        self._usages: list[BudgetUsage] = []
+        self._counter: int = 0
+        self._storage_path = Path(storage_path) if storage_path else None
+        if self._storage_path and self._storage_path.exists():
+            self._load()
+
+    def record_usage(
+        self,
+        agent_id: str,
+        tokens: int,
+        tier: int = 2,
+        department: str = "",
+        workflow_id: str = "",
+        task_id: str = "",
+        description: str = "",
+        approved_by: str = "",
+    ) -> BudgetUsage:
+        """Record a token usage event."""
+        self._counter += 1
+        usage = BudgetUsage(
+            id=f"usage-{self._counter:06d}",
+            agent_id=agent_id,
+            department=department,
+            tier=tier,
+            tokens=tokens,
+            workflow_id=workflow_id,
+            task_id=task_id,
+            description=description,
+            timestamp=datetime.now().isoformat(),
+            approved_by=approved_by,
+        )
+        self._usages.append(usage)
+        self._save()
+        return usage
+
+    def get_period_usage(self, tier: int, department: str = "") -> int:
+        """Get total tokens used this billing period for a tier/department."""
+        period_start = self._current_period_start()
+        total = 0
+        for u in self._usages:
+            if u.tier != tier:
+                continue
+            if department and u.department != department:
+                continue
+            if u.timestamp and u.timestamp >= period_start.isoformat():
+                total += u.tokens
+        return total
+
+    def get_remaining(self, tier: int, department: str = "") -> int:
+        """Get remaining tokens for this period. Returns -1 for unlimited."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return -1
+        used = self.get_period_usage(tier, department)
+        return max(0, budget.monthly_tokens - used)
+
+    def check_budget(self, tier: int, estimated_tokens: int, department: str = "") -> bool:
+        """Check if there's enough budget for an operation. True = OK."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return True
+
+        # Check per-task limit
+        if budget.per_task_max > 0 and estimated_tokens > budget.per_task_max:
+            return False
+
+        # Check remaining monthly budget
+        remaining = self.get_remaining(tier, department)
+        return estimated_tokens <= remaining
+
+    def needs_approval(self, tier: int, department: str = "") -> bool:
+        """Check if usage has exceeded the approval threshold."""
+        budget = self._config.get_tier_budget(tier)
+        if budget.is_unlimited:
+            return False
+        used = self.get_period_usage(tier, department)
+        return used >= (budget.monthly_tokens * budget.approval_threshold)
+
+    def get_summary(self, tier: int, department: str = "") -> BudgetSummary:
+        """Get a complete budget summary for a tier/department."""
+        budget = self._config.get_tier_budget(tier)
+        used = self.get_period_usage(tier, department)
+        period_start = self._current_period_start()
+
+        if budget.is_unlimited:
+            return BudgetSummary(
+                tier=tier,
+                department=department,
+                period_start=period_start.isoformat(),
+                allocated=0,
+                used=used,
+                remaining=-1,
+                percent_used=0,
+                is_unlimited=True,
+                usage_count=self._count_period_usages(tier, department),
+            )
+
+        remaining = max(0, budget.monthly_tokens - used)
+        percent = (used / budget.monthly_tokens * 100) if budget.monthly_tokens > 0 else 0
+        overruns = sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+            and u.is_overrun_approved
+        )
+
+        return BudgetSummary(
+            tier=tier,
+            department=department,
+            period_start=period_start.isoformat(),
+            allocated=budget.monthly_tokens,
+            used=used,
+            remaining=remaining,
+            percent_used=round(percent, 1),
+            is_unlimited=False,
+            needs_approval=self.needs_approval(tier, department),
+            usage_count=self._count_period_usages(tier, department),
+            overruns=overruns,
+        )
+
+    def reset_monthly(self) -> int:
+        """Archive old usages and start a new billing period. Returns archived count."""
+        period_start = self._current_period_start()
+        old = [u for u in self._usages if u.timestamp < period_start.isoformat()]
+        self._usages = [u for u in self._usages if u.timestamp >= period_start.isoformat()]
+        self._save()
+        return len(old)
+
+    def _current_period_start(self) -> date:
+        """Get the start of the current billing period."""
+        today = date.today()
+        day = self._config.billing_start_day
+        if today.day >= day:
+            return date(today.year, today.month, day)
+        # Previous month
+        month = today.month - 1
+        year = today.year
+        if month < 1:
+            month = 12
+            year -= 1
+        return date(year, month, day)
+
+    def _count_period_usages(self, tier: int, department: str = "") -> int:
+        period_start = self._current_period_start()
+        return sum(
+            1 for u in self._usages
+            if u.tier == tier
+            and (not department or u.department == department)
+            and u.timestamp >= period_start.isoformat()
+        )
+
+    def _save(self) -> None:
+        if self._storage_path is None:
+            return
+        self._storage_path.parent.mkdir(parents=True, exist_ok=True)
+        data = {
+            "counter": self._counter,
+            "usages": [u.model_dump(mode="json") for u in self._usages],
+        }
+        with open(self._storage_path, "w") as f:
+            json.dump(data, f, indent=2)
+
+    def _load(self) -> None:
+        if self._storage_path is None or not self._storage_path.exists():
+            return
+        content = self._storage_path.read_text().strip()
+        if not content:
+            return
+        data = json.loads(content)
+        self._counter = data.get("counter", 0)
+        for udata in data.get("usages", []):
+            self._usages.append(BudgetUsage.model_validate(udata))

package/core/budget/schema.py

@@ -0,0 +1,82 @@
+"""Budget schema — token allocation, usage tracking, and summaries."""
+
+from datetime import date, datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TierBudget(BaseModel):
+    """Token budget for a single agent tier."""
+    tier: int
+    monthly_tokens: int          # 0 = unlimited
+    per_task_max: int            # 0 = unlimited
+    approval_threshold: float = 0.8  # Needs Tier 0 approval at this % used
+
+    @property
+    def is_unlimited(self) -> bool:
+        return self.monthly_tokens == 0
+
+
+# Default tier budgets (configurable via BudgetConfig)
+DEFAULT_TIER_BUDGETS = {
+    0: TierBudget(tier=0, monthly_tokens=0, per_task_max=0),           # Unlimited
+    1: TierBudget(tier=1, monthly_tokens=5_000_000, per_task_max=500_000),
+    2: TierBudget(tier=2, monthly_tokens=2_000_000, per_task_max=200_000),
+    3: TierBudget(tier=3, monthly_tokens=1_000_000, per_task_max=100_000),
+}
+
+
+class BudgetConfig(BaseModel):
+    """Budget configuration for the system."""
+    tier_budgets: dict[int, TierBudget] = Field(default_factory=lambda: dict(DEFAULT_TIER_BUDGETS))
+    billing_start_day: int = 1  # Day of month billing resets
+
+    def get_tier_budget(self, tier: int) -> TierBudget:
+        return self.tier_budgets.get(tier, DEFAULT_TIER_BUDGETS.get(tier, TierBudget(tier=tier, monthly_tokens=1_000_000, per_task_max=100_000)))
+
+
+class BudgetUsage(BaseModel):
+    """A single token usage record."""
+    id: str
+    agent_id: str
+    department: str = ""
+    tier: int = 2
+    tokens: int = 0
+    workflow_id: str = ""
+    task_id: str = ""
+    description: str = ""
+    timestamp: str = ""
+    approved_by: str = ""  # Tier 0 agent who approved overrun
+
+    @property
+    def is_overrun_approved(self) -> bool:
+        return bool(self.approved_by)
+
+
+class BudgetSummary(BaseModel):
+    """Current budget status for a tier or department."""
+    tier: int
+    department: str = ""
+    period_start: str = ""
+    period_end: str = ""
+    allocated: int = 0          # Monthly allocation
+    used: int = 0               # Tokens used this period
+    remaining: int = 0          # Tokens remaining
+    percent_used: float = 0.0   # 0-100
+    is_unlimited: bool = False
+    needs_approval: bool = False  # >80% threshold
+    usage_count: int = 0        # Number of operations this period
+    overruns: int = 0           # Number of approved overruns
+
+    @property
+    def status(self) -> str:
+        if self.is_unlimited:
+            return "UNLIMITED"
+        if self.percent_used >= 100:
+            return "EXCEEDED"
+        if self.needs_approval:
+            return "APPROVAL_REQUIRED"
+        if self.percent_used >= 50:
+            return "MODERATE"
+        return "HEALTHY"