recala-cli 0.6.0__py3-none-any.whl

recala_cli/onboarding.py

@@ -0,0 +1,522 @@
+"""Server facts, the terminal checklist and actionable agent onboarding steps."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import datetime
+from shlex import quote
+from typing import Any
+from zoneinfo import ZoneInfo
+
+from recala_cli import config
+from recala_cli.parallel import run_parallel
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import (
+    ARTICLES_LIST,
+    AUTOAPPROVE_SHOW,
+    CADENCE_SHOW,
+    CALENDAR,
+    CMS_STATUS,
+    CREDITS_SUMMARY,
+    GSC_STATUS,
+    ME,
+    ORG_SHOW,
+    PEOPLE_LIST,
+    PUBLICATION_PLAN,
+    QUESTION_PANEL,
+    TOPICS_LIST,
+    TOPICS_SCOUT_STATUS,
+)
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import feature_switched_off, optional_read, sanity_or_none
+from recala_cli.views import PAY_LINK_STEP, pay_link_step
+
+
+@dataclass
+class Facts:
+    me: dict[str, Any] | None = None
+    org: dict[str, Any] = field(default_factory=dict)
+    progress: dict[str, Any] = field(default_factory=dict)
+    people: list[dict[str, Any]] = field(default_factory=list)
+    cms: dict[str, Any] | None = None
+    gsc: dict[str, Any] | None = None
+    sanity: dict[str, Any] | None = None
+    summary: dict[str, Any] | None = None
+    panel: dict[str, Any] = field(default_factory=dict)
+    topics: dict[str, Any] = field(default_factory=dict)
+    scout: dict[str, Any] = field(default_factory=dict)
+    articles: list[dict[str, Any]] = field(default_factory=list)
+    calendar: dict[str, Any] = field(default_factory=dict)
+    cadence: dict[str, Any] = field(default_factory=dict)
+    approval: dict[str, Any] = field(default_factory=dict)
+    publication_plan: dict[str, Any] = field(default_factory=dict)
+    refusals: dict[str, dict[str, Any]] = field(default_factory=dict)
+
+
+def gather(client: RecalaClient | None, calendar_window: dict[str, str] | None = None,
+           *, agent: bool = False, parallel: bool = False) -> Facts:
+    """Everything onboarding and status read. ``parallel`` asks the independent questions at the same time."""
+    if client is None:
+        return Facts()
+    me = client.call(ME)
+    if not client.org_id:
+        return Facts(me=me)
+    reads = {
+        "org": lambda: (optional_read(client, ORG_SHOW, org_id=str(client.org_id)) or {}).get("org") or {},
+        "people": lambda: [p for p in (optional_read(client, PEOPLE_LIST) or {}).get("people") or []
+                           if p.get("is_active", True)],
+        "cms": lambda: optional_read(client, CMS_STATUS),
+        "gsc": lambda: optional_read(client, GSC_STATUS),
+        "summary": lambda: optional_read(client, CREDITS_SUMMARY),
+        "panel": lambda: optional_read(client, QUESTION_PANEL) or {},
+        "topics": lambda: optional_read(client, TOPICS_LIST, params={"limit": 20, "offset": 0}) or {},
+        "scout": lambda: optional_read(client, TOPICS_SCOUT_STATUS) or {},
+        "articles": lambda: (optional_read(client, ARTICLES_LIST, params={"limit": 50, "offset": 0}) or {}
+                             ).get("articles") or [],
+        "calendar": lambda: _read_calendar(client, calendar_window) if calendar_window else {},
+    }
+    found = run_parallel(reads) if parallel else {name: read() for name, read in reads.items()}
+    facts = Facts(me=me, progress=config.onboarding_progress(str(client.org_id)), **found)
+    if (facts.cms or {}).get("provider") == "Sanity":
+        facts.sanity = sanity_or_none(client)
+    if agent:
+        if facts.summary is None:
+            facts.summary = _agent_read(client, CREDITS_SUMMARY, facts, "plan")
+        facts.cadence = _agent_read(client, CADENCE_SHOW, facts, "cadence")
+        facts.approval = _agent_read(client, AUTOAPPROVE_SHOW, facts, "autoapprove")
+        if _cadence(facts)[0] and _autoapprove(facts)[0]:
+            facts.publication_plan = _agent_read(client, PUBLICATION_PLAN, facts, "autorun")
+    if facts.progress.get("completion_not_saved"):
+        previous = facts.progress.get("completion_state")
+        if (previous is not None and previous != completion_state(facts)) or _autorun(facts)[0]:
+            mark(str(client.org_id), completion_not_saved=None, completion_state=None)
+            facts.progress.update(completion_not_saved=None, completion_state=None)
+    return facts
+
+
+def completion_state(facts):
+    return {"completed": bool(facts.org.get("onboarding_completed")),
+            "up_next": sorted(str(row.get("id")) for row in facts.topics.get("up_next") or [])}
+
+
+def _agent_read(client: RecalaClient, endpoint, facts: Facts, key: str) -> dict[str, Any]:
+    try:
+        return client.call(endpoint) or {}
+    except CliError as error:
+        if error.status not in (403, 404) and not feature_switched_off(error):
+            raise
+        command = {"cadence": "cadence set", "autoapprove": "autoapprove on"}.get(key, "onboard")
+        facts.refusals[key] = {"code": error.code, "message": error.message,
+                              "next": refusal_action(error, command)}
+        return {}
+
+
+def _read_calendar(client: RecalaClient, window: dict[str, str]) -> dict[str, Any]:
+    """Scheduling is optional during onboarding: switched off reads as disabled, absent as empty;
+    other calendar failures remain errors."""
+    try:
+        return client.call(CALENDAR, params=window)
+    except CliError as error:
+        if feature_switched_off(error):
+            return {"enabled": False}
+        if error.exit_code in (ExitCode.NOT_FOUND, ExitCode.FORBIDDEN):
+            return {}
+        raise
+
+
+@dataclass(frozen=True)
+class Step:
+    key: str
+    title: str
+    command: str
+    check: Callable[[Facts], tuple[bool, str]]
+
+
+def _login(f: Facts) -> tuple[bool, str]:
+    return bool(f.me), str(((f.me or {}).get("user") or {}).get("email") or "")
+
+
+def _company(f: Facts) -> tuple[bool, str]:
+    detail = " · ".join(str(f.org[k]) for k in ("name", "website_url", "language") if f.org.get(k))
+    return bool(f.org.get("website_url")), detail
+
+
+def _scan(f: Facts) -> tuple[bool, str]:
+    done = bool(f.progress.get("scanned") or (f.org.get("core_description") and f.org.get("niche")))
+    return done, "read and confirmed" if done else ""
+
+
+def _authors(f: Facts) -> tuple[bool, str]:
+    return bool(f.people), ", ".join(str(p.get("display_name")) for p in f.people[:3])
+
+
+def _cms(f: Facts) -> tuple[bool, str]:
+    cms = f.cms or {}
+    return bool(cms.get("connected")), str(cms.get("provider") or "") if cms.get("connected") else ""
+
+
+def _plan(f: Facts) -> tuple[bool, str]:
+    summary = f.summary or {}
+    done = summary.get("plan") == "internal" or (
+        summary.get("plan") in {"self_serve", "go", "managed"} and summary.get("status") in {"active", "ending"}
+    )
+    period = summary.get("period") or {}
+    detail = str(summary.get("plan_name") or summary.get("plan_key") or summary.get("plan") or "Plan unavailable")
+    if period:
+        detail += f": {period.get('allowance')} articles per period, {period.get('left')} left"
+    elif summary.get("plan") == "internal":
+        detail += ": unlimited"
+    return done, detail if done else "Human payment required; billing is managed outside this command"
+
+
+def _topics(f: Facts) -> tuple[bool, str]:
+    total = int(f.topics.get("total") or 0)
+    done = total > 0 or f.scout.get("state") == "done"
+    detail = f"{total} topics" if total else ("Scout complete; no topics found" if done else str(f.scout.get("error_message") or ""))
+    return done, detail
+
+
+def _agent_plan(facts: Facts) -> tuple[bool, str]:
+    allowed = (facts.summary or {}).get("scout_allowed") is True
+    legacy_done, detail = _plan(facts)
+    if allowed and not legacy_done:
+        detail = "Scouting entitlement confirmed"
+    return allowed, detail
+
+
+def _agent_topics(facts: Facts) -> tuple[bool, str]:
+    return bool(topic_choices(facts)), _topics(facts)[1]
+
+
+STEPS = (
+    Step("login", "Sign in", "recala login", _login),
+    Step("company", "Company", "recala company create --name ... --website ... --language es --market ES", _company),
+    Step("scan", "Website scan", "recala company scan", _scan),
+    Step("authors", "Author who signs", "recala author add --name ... --role ... --bio-link ...", _authors),
+    Step("cms", "Publishing (CMS)", "recala cms connect --provider sanity   (or: --provider wordpress)", _cms),
+    Step("plan", "Plan", f"Human: {PAY_LINK_STEP}; then recala status", _plan),
+    Step("topics", "First topics scout", "recala topics scout", _topics),
+)
+STEP_KEYS = tuple(step.key for step in STEPS)
+
+
+def evaluate(facts: Facts, *, agent: bool = False) -> list[dict[str, Any]]:
+    rows = []
+    for step in AGENT_STEPS if agent else STEPS:
+        done, detail = step.check(facts)
+        if agent and step.key == "authors":
+            done = bool(_active_people(facts))
+        if agent:
+            rows.append({"key": step.key, "title": step.title, "done": done,
+                         "detail": detail, **agent_action(step.key, facts)})
+            continue
+        rows.append({"key": step.key, "title": step.title, "done": done, "detail": detail, "command": step.command})
+    return rows
+
+
+def next_step(rows: list[dict[str, Any]]) -> dict[str, Any] | None:
+    return next((row for row in rows if not row["done"]), None)
+
+
+def checklist_rows(rows: list[dict[str, Any]]) -> list[tuple[str, str, str]]:
+    upcoming = next_step(rows)
+    return [(row["title"], "done" if row["done"] else ("now" if row is upcoming else "next"), row["detail"]) for row in rows]
+
+
+def mark(org_id: str, **flags: Any) -> None:
+    config.save_onboarding_progress(org_id, {**config.onboarding_progress(org_id), **flags})
+
+
+def topic_choices(facts: Facts) -> list[dict[str, Any]]:
+    seen, rows = set(), []
+    for section in ("up_next", "backlog", "queued", "processing", "other"):
+        for row in facts.topics.get(section) or []:
+            if row.get("id") not in seen and row.get("review_decision") != "dismissed":
+                seen.add(row.get("id"))
+                rows.append(row)
+    return rows
+
+
+def _approve_topics(facts: Facts) -> tuple[bool, str]:
+    approved = [row for row in topic_choices(facts) if row.get("review_decision") == "approved"]
+    return bool(approved), ", ".join(row["topic"] for row in approved[:3])
+
+
+def _complete(facts: Facts) -> tuple[bool, str]:
+    return bool(facts.org.get("onboarding_completed")), "Company setup saved; Up next filled"
+
+
+def _cadence(facts: Facts) -> tuple[bool, str]:
+    cadence = facts.cadence.get("cadence") or {}
+    return bool(cadence.get("days") and cadence.get("local_time") and cadence.get("timezone")
+                and cadence.get("autopilot_enabled")), "Publication days, time and auto-run consent saved"
+
+
+def _signer(facts: Facts) -> dict[str, Any] | None:
+    signer_id = facts.approval.get("default_author_person_id")
+    return next((person for person in _active_people(facts) if person.get("id") == signer_id), None)
+
+
+def _active_people(facts: Facts) -> list[dict[str, Any]]:
+    return [person for person in facts.people
+            if person.get("id") and person.get("display_name") and person.get("is_active", True)]
+
+
+def _autoapprove(facts: Facts) -> tuple[bool, str]:
+    signer = _signer(facts)
+    return bool(facts.approval.get("auto_approve_passing") and signer), str((signer or {}).get("display_name") or "")
+
+
+def _scheduled_slot(facts: Facts) -> dict[str, Any] | None:
+    return next((slot for slot in sorted(facts.publication_plan.get("slots") or [],
+                                        key=lambda slot: slot.get("scheduled_at") or "")
+                 if slot.get("scheduled_at") and slot.get("state") in {
+                     "would_assign", "bound", "scheduled", "approved"}
+                 and slot.get("next_state") not in {"blocked", "needs_attention"}
+                 and slot.get("reason") not in {"active_author_required", "no_signer"}), None)
+
+
+def _autorun(facts: Facts) -> tuple[bool, str]:
+    flags = facts.publication_plan.get("flags") or {}
+    ready = all(flags.get(key) is True for key in (
+        "cadence_autopilot_enabled", "publish_cadence_enabled", "publication_calendar_enabled",
+        "write_ahead_enabled", "auto_approve_passing_enabled"))
+    plan_cadence = facts.publication_plan.get("cadence") or {}
+    cadence_ready = "cadence" not in facts.publication_plan or plan_cadence.get("autopilot_enabled") is True
+    return bool(ready and cadence_ready and not facts.publication_plan.get("entitlement_refusal")
+                and _scheduled_slot(facts)), "Server automation enabled and first scheduled slot verified"
+
+
+AGENT_STEPS = (*(Step(step.key, step.title, step.command,
+                     {"plan": _agent_plan, "topics": _agent_topics}.get(step.key, step.check)) for step in STEPS),
+    Step("approve_topics", "Approve first topics", "recala topics approve {topic_id}", _approve_topics),
+    Step("complete", "Save company setup", "recala onboard --step complete", _complete),
+    Step("cadence", "Publication cadence", "recala cadence set", _cadence),
+    Step("autoapprove", "Automatic approval and signer", "recala autoapprove on", _autoapprove),
+    Step("autorun", "Verify auto-run", "recala plan --json", _autorun),
+)
+
+
+def question(field: str, ask: str, example: Any, default: Any = None) -> dict[str, Any]:
+    return {"field": field, "ask": ask, "example": example, "default": default, "required": True}
+
+
+def _company_action(facts: Facts) -> dict[str, Any]:
+    memberships = [member for member in (facts.me or {}).get("memberships") or []
+                   if member.get("website_url")]
+    if not facts.org.get("id") and memberships:
+        choices = [{"value": member["org_id"], "label": member["name"]} for member in memberships]
+        pick = question("company", "Which existing company should we finish setting up?", choices[0]["label"],
+                        choices[0]["label"] if len(choices) == 1 else None)
+        pick["choices"] = choices
+        return {"why": "Select the existing company to resume its setup.", "questions": [pick],
+                "command": "recala company use {company} --json",
+                "done_when": "The existing company is selected for subsequent onboarding reads."}
+    return {"why": "Identify the company, its website and the readers it serves.",
+            "questions": [
+                question("name", "What is the company's name?", "Cometa", facts.org.get("name")),
+                question("website", "What is the company's website?", "https://recala.co", facts.org.get("website_url")),
+                question("language", "Which language should articles use?", "es", facts.org.get("language")),
+                question("market", "Which country does the company sell in?", "ES",
+                         facts.progress.get("market") or facts.org.get("country_code")),
+            ], "command": "recala company create --name {name} --website {website} --language {language} --market {market} --json",
+            "done_when": "The selected company has its confirmed name, website and article language."}
+
+
+def _author_action(facts: Facts) -> dict[str, Any]:
+    return {"why": "Every article needs a real named person to sign it.",
+            "questions": [
+                question("author_name", "Who will sign the articles? Give their full name.", "Ana Cometa"),
+                question("role", "What is that person's role?", "Founder"),
+                question("bio_link", "What is their public bio or profile URL?", "https://recala.co"),
+            ], "command": "recala author add --name {author_name} --role {role} --bio-link {bio_link} --json",
+            "done_when": "The human's named signing person is an active company author."}
+
+
+def _approval_action(facts: Facts) -> dict[str, Any]:
+    choices = [{"value": row["id"], "label": row.get("topic")} for row in topic_choices(facts)]
+    pick = question("topic_id", "Which topic should Recala keep? Choose by title; repeat for each topic you want.",
+                    choices[0]["label"] if choices else "A topic title")
+    pick["choices"] = choices
+    return {"why": "The person chooses which proposed topics Recala may write.", "questions": [pick],
+            "command": "recala topics approve {topic_id} --json",
+            "done_when": "At least one topic the person chose has review_decision approved."}
+
+
+def _cadence_days(facts: Facts) -> str | None:
+    existing = (facts.cadence.get("cadence") or {}).get("days")
+    days = ("mon", "tue", "wed", "thu", "fri", "sat", "sun")
+    if existing:
+        return ",".join(days[day] for day in existing)
+    allowance = ((facts.summary or {}).get("period") or {}).get("allowance")
+    if allowance is None or allowance < 5:
+        return None  # Every weekly weekday can occur five times in a monthly period.
+    count = min(7, int(allowance // 5))
+    return ",".join(days[day] for day in sorted((0, 3, 1, 4, 2, 5, 6)[:count]))
+
+
+def _cadence_action(facts: Facts) -> dict[str, Any]:
+    cadence = facts.cadence.get("cadence") or {}
+    allowance = ((facts.summary or {}).get("period") or {}).get("allowance")
+    why = "Choose when Recala should prepare and publish articles within the plan's allowance."
+    if allowance is not None and allowance < 5:
+        why += f" Weekly slots can exceed {allowance} articles per period; auto-run pauses when credits run out."
+    return {"why": why, "questions": [
+        question("days", "Which publication weekdays? Use comma-separated mon through sun.", "mon", _cadence_days(facts)),
+        question("time", "At what local time should articles appear?", "09:00", cadence.get("local_time")),
+        question("tz", "Which IANA timezone should the schedule use?", "Europe/Madrid",
+                 _cadence_timezone(facts)),
+        question("autopilot", "Allow Recala to assign topics and generate articles automatically on this cadence?", True, False),
+    ], "command": "recala cadence set --days {days} --time {time} --tz {tz} --autopilot --json",
+        "done_when": "Publication days, local time and timezone are saved with autopilot_enabled true."}
+
+
+def _cadence_timezone(facts: Facts) -> str | None:
+    saved = (facts.cadence.get("cadence") or {}).get("timezone")
+    if saved:
+        return saved
+    # The server and organizations column both default to UTC without a person's
+    # choice. Only a saved cadence proves UTC is the intended local timezone.
+    known = facts.org.get("timezone") or facts.cadence.get("timezone")
+    return known if known != "UTC" else None
+
+
+def _autoapprove_action(facts: Facts) -> dict[str, Any]:
+    choices = [{"value": person["id"], "label": person["display_name"]} for person in _active_people(facts)]
+    names = ", ".join(str(choice["label"]) for choice in choices)
+    author = question("author", "Which named person will sign? Choose by name.", names,
+                      choices[0]["label"] if len(choices) == 1 else None)
+    author["choices"] = choices
+    return {"why": "Automatic approval requires the person's consent and an active named signer.",
+            "questions": [question("autoapprove", f"Allow passing drafts to be approved automatically, signed by {names}?", True, False), author],
+            "command": "recala autoapprove on --author {author} --json",
+            "done_when": "auto_approve_passing is true and default_author_person_id identifies an active named person."}
+
+
+def _autorun_action(facts: Facts) -> dict[str, Any]:
+    action = {"why": "Verify server automation and the first planned publication date.",
+              "command": "recala plan --json", "done_when": "All automation flags are enabled and the plan has a usable scheduled slot."}
+    states = {slot.get(field) for slot in facts.publication_plan.get("slots") or []
+              for field in ("state", "reason", "next_state")}
+    states.update(facts.publication_plan.get(field) for field in ("entitlement_refusal", "reason"))
+    if "cadence" in facts.publication_plan:
+        plan_cadence = facts.publication_plan["cadence"]
+        if not plan_cadence:
+            states.add("missing_cadence")
+        elif not plan_cadence.get("autopilot_enabled"):
+            states.add("autopilot_off")
+    remedies = {
+        "missing_cadence": "cadence", "cadence_not_configured": "cadence", "autopilot_off": "cadence",
+        "no_approved_topic": "approve_topics", "empty_up_next": "approve_topics",
+        "no_signer": "autoapprove", "active_author_required": "autoapprove",
+        "publication_destination_missing": "cms",  # before not_entitled: the slot states share the refusal
+        "not_entitled": "plan", "no_article_credit": "plan",
+        "write_ahead_window_missed": "cadence",
+    }
+    if not _autorun(facts)[0]:
+        remedy = next((target for state, target in remedies.items() if state in states), None)
+        if remedy == "approve_topics" and _approve_topics(facts)[0]:
+            remedy = "complete"  # Refresh Up next even after initial onboarding was saved.
+        if remedy:
+            recovery = agent_action(remedy, facts)
+            return {**recovery, "why": "Resolve the publication plan blocker: " +
+                    ", ".join(sorted(str(state) for state in states if state)),
+                    "done_when": action["done_when"]}
+    if facts.publication_plan and not _autorun(facts)[0]:
+        action["human_action"] = {"what": "Ask Recala support to resolve the plan's disabled automation flags or slot blockers; then run recala plan --json.",
+                                  "where": "Recala support, with the recala plan --json report"}
+    return action
+
+
+def agent_action(key: str, facts: Facts) -> dict[str, Any]:
+    billing = config.web_url() + "/portal/billing"
+    basic = {
+        "login": {"why": "Authorize the agent to act for your company.", "command": "recala login",
+                  "human_action": {"what": "Run the login command and approve its device code in your browser.", "where": "The verification URL printed by recala login"},
+                  "done_when": "recala whoami --json identifies the signed-in person."},
+        "scan": {"why": "Read the company's own site to establish its products, audience and voice.",
+                 "command": "recala company scan --json", "done_when": "The website scan is saved and its facts are confirmed."},
+        "cms": {"why": "Connect the place where signed articles will appear.",
+                "questions": [question("provider", "Which CMS do you use: sanity or wordpress?", "sanity",
+                                       str((facts.cms or {}).get("provider") or "").lower() or None)],
+                "command": "recala cms connect --provider {provider}",
+                "human_action": {"what": "Run this command in your terminal; supply CMS connection details and type the secret only at its hidden prompt, or provide it through the environment or --token-stdin.",
+                                 "where": "Your terminal, using CMS project settings or WordPress application passwords"},
+                "done_when": "recala connect status --json reports the CMS connected."},
+        "plan": {"why": "An active paid plan supplies scouting and article allowances.", "command": "recala onboard --json",
+                 "human_action": {"what": "Activate and pay for Go or Self-serve yourself, then rerun the command.", "where": billing},
+                 "done_when": "The server's billing summary reports scout_allowed true (internal, enabled dogfood or paid entitlement)."},
+        "topics": {"why": "Find the first topics from the company's confirmed facts.", "command": "recala topics scout --json",
+                   "done_when": "The company has topics to review by title."},
+        "complete": {"why": "Save completed company setup and fill Up next for scheduling.",
+                     "command": "recala onboard --step complete --apply --json", "done_when": "The server reports onboarding_completed true."},
+    }
+    builders = {"company": _company_action, "authors": _author_action,
+                "approve_topics": _approval_action, "cadence": _cadence_action,
+                "autoapprove": _autoapprove_action, "autorun": _autorun_action}
+    action = builders[key](facts) if key in builders else basic[key]
+    action.setdefault("questions", [])
+    if key == "topics" and facts.scout.get("state") == "done" and not topic_choices(facts):
+        action.update(command="recala topics add {topic} --json",
+                      questions=[question("topic", "No topics were found. What buyer question should Recala cover first?", "How do study cards help learning?")])
+    if facts.org.get("id") and key not in {"login", "company"} and " --org " not in action["command"]:
+        action["command"] += " --org " + quote(str(facts.org["id"]))
+    if key in facts.refusals:
+        refusal = facts.refusals[key]
+        action.update({field: value for field, value in refusal.items() if field != "next"})
+        action.update(refusal["next"])
+    if key == "complete" and facts.progress.get("completion_not_saved"):
+        error = CliError(ExitCode.CONFLICT, "completion_not_saved", facts.progress["completion_not_saved"])
+        recovery = refusal_action(error)
+        action.update(code=error.code, message=error.message,
+                      human_action={**recovery.get("human_action", {}),
+                                    "what": error.message + " Resolve this with Recala support,"
+                                            " then run the command again."})
+    return action
+
+
+def refusal_action(error: CliError, command: str = "onboard") -> dict[str, Any]:
+    """One recovery mapping for onboarding and its later write commands."""
+    if (error.details or {}).get("next"):
+        return error.details["next"]
+    if error.exit_code == ExitCode.NOT_AUTHENTICATED:
+        return {"command": "recala login", "human_action": {
+            "what": "Sign in and approve the device code yourself.",
+            "where": "The browser verification URL printed by recala login"}}
+    if error.code == "human_payment_required":
+        return {"command": "recala onboard --json", "human_action": {
+            "what": "Activate and pay for Go or Self-serve yourself, then resume onboarding.",
+            "where": pay_link_step()}}
+    if error.exit_code in {ExitCode.FORBIDDEN, ExitCode.CONFIRMATION_REQUIRED}:
+        return {"command": "recala whoami --json", "human_action": {
+            "what": "Ask the company owner to authorize or perform this action; keep the existing credential boundaries.",
+            "where": "The company owner's terminal; recala grant records session consent"}}
+    if error.code == "completion_not_saved" or "not enabled" in error.message.lower():
+        return {"command": "recala onboard --json", "human_action": {
+            "what": "Ask Recala support to resolve the unverified setup or disabled server feature, then resume onboarding.",
+            "where": "Recala support, with the refusal code and message"}}
+    return {"command": {"cadence set": "recala cadence show --json",
+                        "autoapprove on": "recala autoapprove show --json",
+                        "topics approve": "recala topics list --json"}.get(command, "recala onboard --json")}
+
+
+def explain_refusal(error: CliError, command: str) -> None:
+    if error.exit_code == ExitCode.USAGE:
+        return  # CLI input errors already name the required flag; preserve their contract.
+    recovery = refusal_action(error, command)
+    if "Next:" not in error.message and recovery["command"] not in error.message:
+        human = (recovery.get("human_action") or {}).get("what")
+        error.message += f" Next: {human + ' ' if human else ''}{recovery['command']}."
+    error.details = {**(error.details or {}), "code": error.code,
+                     "message": error.message, "next": recovery}
+
+
+def auto_run_summary(facts: Facts) -> str | None:
+    if not all(step.check(facts)[0] for step in AGENT_STEPS):
+        return None
+    slot = _scheduled_slot(facts)
+    cadence = facts.cadence["cadence"]
+    date = datetime.fromisoformat(slot["scheduled_at"]).astimezone(ZoneInfo(cadence["timezone"]))
+    name = _signer(facts)["display_name"]
+    return (f"Recala will prepare and automatically approve passing articles for {facts.org.get('name')}, "
+            f"signed by {name}, for publication starting {date.isoformat()} ({cadence['timezone']}), within the plan's allowance.")