"""obol help - guided walkthrough of all commands."""
import sys


def setup_parser(subparsers):
    p = subparsers.add_parser("help", help="Guided command reference")
    p.add_argument("topic", nargs="?", help="Topic: setup, monitoring, security, config, admin")
    p.set_defaults(func=cmd_help)


TOPICS = {
    "setup": """\
  GETTING STARTED
  ───────────────

  1. Sign up at https://obol.grayowlresearch.com
  2. Copy your API key from the dashboard
  3. Run:

     obol setup <your_api_key>

     This saves your key, finds AI agents on your machine,
     registers them, and installs monitoring hooks. One command.

  4. Verify everything works:

     obol diagnose

  5. You're done. Use your agent normally — Obol monitors
     in the background.
""",
    "monitoring": """\
  MONITORING YOUR AGENTS
  ──────────────────────

  obol status                     Overview dashboard
  obol agents                     List registered agents
  obol events                     Recent events (all agents)
  obol events --agent 5           Events for a specific agent
  obol events --since 1h          Events from the last hour
  obol tail --agent 5             Live event stream (follows)
  obol watch                      Interactive live dashboard

  Obol records every tool call your agent makes: what it did,
  what it targeted, whether it succeeded, and whether it looks
  anomalous. All detection runs on your machine.
""",
    "security": """\
  SECURITY & DETECTION
  ────────────────────

  obol alerts                     View open security alerts
  obol alerts --unresolved        Only unresolved alerts
  obol review                     Session detection summary
  obol review --session <SID>     Review a specific session
  obol explain <flag>             What does a detection flag mean?

  False positive management:
    obol fp <alert-id> --allow    Mark alert as false positive
    obol allow <flag>             Suppress a flag locally
    obol allow list               Show all suppressions
    obol allow remove <id>        Remove a suppression

  If enforce mode blocks something you need:
    obol override <CODE>          One-time bypass (60s)
    obol unlock                   Remove full lockdown
""",
    "config": """\
  CONFIGURATION
  ─────────────

  obol config show                Current settings
  obol config set KEY VALUE       Change a setting
  obol whoami                     Account info + connection check

  Enforcement modes:
    obol config set enforcement_mode audit     Log only (default)
    obol config set enforcement_mode alert     Log + notifications
    obol config set enforcement_mode enforce   Log + notifications + blocking

  Pause/resume:
    obol disable                  Temporarily remove hooks
    obol enable                   Restore hooks

  Maintenance:
    obol retry                    Resend failed events
    obol prune --older-than 30    Clean old local audit logs
    obol repair                   Fix corrupted hooks
""",
    "admin": """\
  ADMIN (GOR operators only)
  ──────────────────────────

  obol admin monitor              24/7 ops dashboard
  obol admin stats                Quick system stats

  These commands require an admin-tier API key and are not
  available to regular users.
""",
}


def cmd_help(args):
    topic = args.topic

    if topic and topic in TOPICS:
        print()
        print(TOPICS[topic])
        return

    if topic and topic not in TOPICS:
        print(f"\n  Unknown topic: {topic}")
        print(f"  Available: {', '.join(TOPICS.keys())}")
        print()
        return

    # Full help
    print("""
  OBOL — Trust infrastructure for AI agents
  ══════════════════════════════════════════

  Quick start:
    obol setup <api_key>          Install everything in one command
    obol diagnose                 Verify it's working

  Monitor:
    obol status                   Overview dashboard
    obol tail --agent <ID>        Live event stream
    obol events                   Recent events
    obol watch                    Interactive dashboard

  Security:
    obol alerts                   View security alerts
    obol review                   Session detection summary
    obol explain <flag>           What does this flag mean?
    obol fp <alert-id>            Mark false positive
    obol allow <flag>             Suppress a known-good pattern

  Configure:
    obol config show              Current settings
    obol config set KEY VALUE     Change setting
    obol whoami                   Account info
    obol disable / enable         Pause or resume monitoring

  Enforce mode:
    obol override <CODE>          One-time bypass when blocked
    obol unlock                   Remove lockdown

  Maintain:
    obol retry                    Resend failed events
    obol prune                    Clean old audit logs
    obol repair                   Fix corrupted hooks

  ──────────────────────────────────────────
  Dig deeper into any topic:

    obol help setup               Getting started walkthrough
    obol help monitoring          All monitoring commands
    obol help security            Alerts, detection, false positives
    obol help config              Settings, modes, maintenance
    obol help admin               Operator tools (GOR only)

  Docs: https://obol.grayowlresearch.com
""")
