recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/skills.py

@@ -0,0 +1,92 @@
+"""`recala skills`: the agent skills that ship with this CLI, same version, installed where the agent looks.
+
+The skills travel inside the package (``recala_cli/skills``), so a skill never names a
+command this CLI does not have (tests/test_skills.py checks every command they use).
+``install`` copies each skill and gives it the shared CLI contract as
+``references/recala-cli-contract.md``.
+"""
+
+from __future__ import annotations
+
+import shutil
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+import click
+
+from recala_cli import __version__
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, json_option
+
+CONTRACT = "recala-cli-contract.md"
+
+
+def bundled() -> Path:
+    return Path(str(resources.files("recala_cli") / "skills"))
+
+
+def frontmatter(skill_md: Path) -> dict[str, str]:
+    """The ``name`` and ``description`` of a SKILL.md (Agent Skills format), plus its version."""
+    text = skill_md.read_text()
+    if not text.startswith("---\n"):
+        return {}
+    head = text[4:text.index("\n---", 4)]
+    fields: dict[str, str] = {}
+    for line in head.splitlines():
+        key, _, value = line.strip().partition(":")
+        if key in ("name", "description", "version", "requires") and value.strip():
+            fields[key] = value.strip()
+    return fields
+
+
+def skill_dirs() -> list[Path]:
+    return sorted(path for path in bundled().iterdir() if (path / "SKILL.md").is_file())
+
+
+@click.group()
+def skills() -> None:
+    """Agent skills for Claude Code, Codex and others.
+
+    SKILL.md files, versioned with this CLI."""
+
+
+@skills.command("list")
+@json_option
+@command_runner(human=lambda r: "\n".join(f"{s['name']:<34} {s['version']}" for s in r["skills"]))
+def list_skills(ctx: click.Context) -> dict[str, Any]:
+    """The skills this CLI ships."""
+    listed = []
+    for path in skill_dirs():
+        meta = frontmatter(path / "SKILL.md")
+        listed.append({"name": meta.get("name", path.name), "version": meta.get("version", ""),
+                       "description": meta.get("description", "")})
+    return {"cli_version": __version__, "skills": listed}
+
+
+@skills.command("install")
+@json_option
+@command_runner(human=lambda r: "\n".join(r["installed"]) + f"\n{len(r['installed'])} skills in {r['dir']}")
+@click.option("--dir", "target", type=click.Path(file_okay=False, path_type=Path), default=Path(".claude/skills"),
+              show_default=True, help="Where the agent reads skills (a project's .claude/skills, or ~/.claude/skills).")
+@click.option("--force", is_flag=True, help="Replace skills already installed there.")
+def install(ctx: click.Context, target: Path, force: bool) -> dict[str, Any]:
+    """Copy every skill into --dir.
+
+    With the CLI contract as a reference."""
+    sources = skill_dirs()
+    clashes = [path.name for path in sources if (target / path.name).exists()]
+    if clashes and not force:
+        raise CliError(ExitCode.CONFLICT, "already_installed",
+                       f"Already installed in {target}: {', '.join(clashes)}. Re-run with --force to replace them.")
+    installed = []
+    for source in sources:
+        destination = target / source.name
+        if destination.exists():
+            shutil.rmtree(destination)
+        shutil.copytree(source, destination)
+        references = destination / "references"
+        references.mkdir(exist_ok=True)
+        shutil.copyfile(bundled() / CONTRACT, references / CONTRACT)
+        installed.append(str(destination))
+    return {"dir": str(target), "installed": installed, "cli_version": __version__}

recala_cli/commands/slot_topic.py

@@ -0,0 +1,94 @@
+"""`recala topics waiting-slots` and `replace-slot`: a date that stopped and waits for a person."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.display import display_name
+from recala_cli.endpoints import ESCALATED_SLOTS, SLOT_TOPIC_REPLACE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.ids import is_short_id, matching_prefix
+from recala_cli.labels import action_sentence
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option, dry_run_option
+from recala_cli.views import company_timezone, local_time, timezone_label
+
+
+def replace_command(slot_id: str) -> str:
+    return f"recala topics replace-slot {slot_id[:8]} <topic>"
+
+
+def describe_waiting(ctx: click.Context, result: dict[str, Any]) -> str:
+    if not result["slots"]:
+        return "No date is waiting for a person."
+    zone = company_timezone(ctx, result)
+    lines = [f"Dates waiting for a person {timezone_label(zone)}"]
+    for slot in result["slots"]:
+        lines.append(f"  {local_time(slot['scheduled_at'], zone)}  {display_name(slot.get('topic')) or '(no topic)'}")
+        lines.append(f"    {slot['reason']}")
+        lines.append(f"    {slot['refusal_message'] or 'Replace it: ' + replace_command(slot['id'])}")
+    if result["candidates"]:
+        lines.append("Topics these dates may take:")
+        lines.extend(f"  {display_name(row['topic'])}  [{row['id'][:8]}]" for row in result["candidates"])
+    else:
+        lines.append("No topic in Up next can take these dates. Add one: recala topics up-next add <title>")
+    return "\n".join(lines)
+
+
+def resolve_slot(slots: list[dict[str, Any]], selector: str) -> dict[str, Any]:
+    matches = [row for row in slots if row["id"] == selector] or (
+        matching_prefix(slots, selector) if is_short_id(selector) else [])
+    if len(matches) != 1:
+        raise CliError(ExitCode.USAGE, "slot_ambiguous" if matches else "slot_not_found",
+                       f"{'Several dates match' if matches else 'No date waiting for a person matches'} {selector}. "
+                       "See: recala topics waiting-slots")
+    return matches[0]
+
+
+def resolve_candidate(candidates: list[dict[str, Any]], selector: str) -> dict[str, Any]:
+    matches = [row for row in candidates if row["id"] == selector] or (
+        matching_prefix(candidates, selector) if is_short_id(selector) else
+        [row for row in candidates if str(row["topic"]).casefold() == selector.casefold()])
+    if len(matches) == 1:
+        return matches[0]
+    choices = "\n".join(f"{display_name(row['topic'])} [{row['id'][:8]}]" for row in candidates)
+    raise CliError(ExitCode.USAGE, "replacement_not_writable",
+                   f"This date can't take {selector}. It can take:\n{choices or 'no topic right now'}")
+
+
+@click.command("waiting-slots")
+@common_options
+@command_runner(contextual_human=describe_waiting)
+def waiting_slots(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Dates waiting for a person, and their topics."""
+    result: dict[str, Any] = open_client(ctx, org_flag).call(ESCALATED_SLOTS)
+    return result
+
+
+@click.command("replace-slot")
+@common_options
+@command_runner(contextual_human=action_sentence("Topic replaced"))
+@click.argument("slot")
+@click.argument("topic")
+@accepted_yes_option
+@dry_run_option
+def replace_slot(ctx: click.Context, org_flag: str | None, slot: str, topic: str) -> dict[str, Any]:
+    """Replace the topic on a date waiting for a person.
+
+    SLOT is an id from `recala topics waiting-slots`. TOPIC is an id or exact title from that list."""
+    client = open_client(ctx, org_flag)
+    waiting = client.call(ESCALATED_SLOTS)
+    row = resolve_slot(waiting["slots"], slot)
+    if row["refusal"]:
+        raise CliError(ExitCode.CONFLICT, row["refusal"], row["refusal_message"])
+    replacement = resolve_candidate(waiting["candidates"], topic)
+    day = local_time(row["scheduled_at"], company_timezone(ctx, waiting))
+    title = display_name(replacement["topic"])
+    ctx.meta["result_subject"] = f"{day} will publish {title}"
+    confirm(ctx, client, f"Replace \"{display_name(row.get('topic'))}\" with \"{title}\" on {day}?")
+    result: dict[str, Any] = client.call(
+        SLOT_TOPIC_REPLACE, path={"slot_id": row["id"]},
+        json={"topic_id": replacement["id"], "expected_topic_id": row["topic_id"]},
+    )
+    return result

recala_cli/commands/status.py

@@ -0,0 +1,153 @@
+"""`recala status`: the active company at a glance.
+
+The plan with its caps and reset date, the connections with their next steps, the
+question panel, the articles, what is scheduled, and where onboarding stands.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections import Counter
+from functools import partial
+from typing import Any
+
+import click
+
+from recala_cli import ui
+from recala_cli.endpoints import BILLING_MANAGED_USAGE, ENTITLEMENTS, CADENCE_SHOW, PUBLICATION_PLAN, AUTOAPPROVE_SHOW
+from recala_cli.onboarding import Facts, evaluate, gather, next_step
+from recala_cli.commands.index import is_indexed, read_indexing
+from recala_cli.errors import CliError
+from recala_cli.parallel import run_parallel
+from recala_cli.human import publish_state_words
+from recala_cli.commands.reads import calendar_window
+from recala_cli.runtime import command_runner, common_options, open_client, optional_read
+from recala_cli.views import calendar_view, connection_lines, credit_lines, panel_lines, planned_calendar
+
+_PUBLISHED_STATES = {"published", "updated"}
+
+
+def dashboard(facts: Facts, *, entitlements: dict[str, Any] | None, managed: dict[str, Any] | None,
+              indexing: dict[str, Any] | None = None) -> dict[str, Any]:
+    rows = evaluate(facts)
+    states = Counter(str(a.get("cms_publish_status") or "draft") for a in facts.articles)
+    return {
+        "org": facts.org, "user": (facts.me or {}).get("user"),
+        "plan": {"summary": facts.summary, "entitlements": entitlements, "managed_usage": managed},
+        "connections": {"cms": facts.cms, "search_console": facts.gsc, "org": facts.org,
+                        **({"sanity": facts.sanity} if facts.sanity else {})},
+        "questions": facts.panel,
+        "articles": {"total": len(facts.articles), "by_publish_status": dict(states),
+                     "topics_waiting": int(facts.topics.get("total") or 0)},
+        "calendar": planned_calendar(facts.calendar, facts.publication_plan or facts.cadence),
+        "autopilot_blockers": autopilot_blockers(facts),
+        "indexing": indexing,
+        "onboarding": {"done": sum(1 for row in rows if row["done"]), "total": len(rows), "next": next_step(rows),
+                       "missing": [row for row in rows if not row["done"]]},
+    }
+
+
+def describe_dashboard(board: dict[str, Any], *, cadence: dict[str, Any] | None = None) -> str:
+    style = ui.Style.for_stream(sys.stdout)  # the dashboard is printed on stdout
+    org = board.get("org") or {}
+    calendar = board.get("calendar") or {}
+    zone = org.get("timezone") or (cadence or {}).get("timezone")
+    if not zone and calendar.get("timezone") != "UTC":
+        zone = calendar.get("timezone")
+    title = f"{style.accent('*')} {style.bold(org.get('name') or 'Your company')}"
+    lines = [title + style.dim(f"   {org.get('website_url') or ''}  {org.get('language') or ''}"), ""]
+    plan = board.get("plan") or {}
+    lines += [style.bold("Plan and credits")]
+    lines += [f"  {line}" for line in credit_lines(plan.get("summary") or {}, plan.get("entitlements"),
+                                                    plan.get("managed_usage"), show_question_cap=False, zone=zone or "UTC")]
+    lines += ["", style.bold("Connections")]
+    lines += [f"  {line}" for line in connection_lines(board.get("connections") or {}, zone=zone)]
+    lines += ["", style.bold("Questions")]
+    lines += [f"  {line}" for line in panel_lines(board.get("questions") or {}, plan.get("entitlements"))]
+    articles = board.get("articles") or {}
+    lines += ["", style.bold("Articles")]
+    in_words: Counter[str] = Counter()
+    for state, count in (articles.get("by_publish_status") or {}).items():
+        in_words[publish_state_words(state)] += count
+    counts = ", ".join(f"{n} {state}" for state, n in sorted(in_words.items()))
+    total = articles.get("total", 0)
+    lines.append(f"  {total} article{'' if total == 1 else 's'}" + (f" ({counts})" if counts else "")
+                 + f"; {articles.get('topics_waiting', 0)} topics waiting  ->  recala topics list")
+    lines.append("  " + indexing_line(board.get("indexing")))
+    if calendar:
+        calendar = {**calendar, "timezone": zone}
+        lines += [""] + [f"  {line}" if index else style.bold(line)
+                         for index, line in enumerate(calendar_view(calendar, style=style, cadence=cadence).splitlines())]
+    onboarding = board.get("onboarding") or {}
+    lines += ["", style.bold("Onboarding") + f"  {onboarding.get('done')}/{onboarding.get('total')} steps"]
+    upcoming = onboarding.get("next")
+    lines.append(f"  Next: {upcoming['title']}  ->  {upcoming['command']}" if upcoming
+                 else "  Complete.")
+    lines.extend(f"  Missing: {row['title']}  ->  {row['command']}" for row in onboarding.get("missing", []) if row != upcoming)
+    if board.get("autopilot_blockers"):
+        lines += ["", "Autopilot is on but cannot publish:"]
+        lines.extend("  " + reason for reason in board["autopilot_blockers"])
+    return "\n".join(lines)
+
+
+def autopilot_blockers(facts):
+    from recala_cli.onboarding import topic_choices
+    if not (facts.cadence.get("cadence") or {}).get("autopilot_enabled"):
+        return []
+    reasons = []
+    if not (facts.cms or {}).get("connected"):
+        reasons.append("No CMS connected -> recala cms connect --provider <sanity|wordpress>")
+    if not any(row.get("review_decision") == "approved" for row in topic_choices(facts)):
+        reasons.append("No approved topics -> recala topics approve <id>; then recala topics up-next add <title>")
+    active_ids = {person.get("id") for person in facts.people if person.get("is_active", True)}
+    if facts.approval.get("default_author_person_id") not in active_ids:
+        reasons.append("No active signer -> recala authors add --name <name>; recala autoapprove on --author <id>")
+    if facts.scout.get("state") == "failed":
+        reasons.append(f"Scout failing ({facts.scout.get('error_code') or 'failed'}) -> recala topics scout")
+    return reasons
+
+
+@click.command()
+@common_options
+@command_runner(contextual_human=lambda ctx, board: describe_dashboard(board, cadence=ctx.meta.get("status_cadence")))
+def status(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """The active company at a glance.
+
+    Plan and caps, connections, questions, articles, calendar, onboarding."""
+    client = open_client(ctx, org_flag)
+    # Every question that does not depend on another is asked at once; indexing waits for the article list.
+    answers = run_parallel({
+        "facts": lambda: gather(client, calendar_window(), parallel=True),
+        "cadence": lambda: optional_read(client, CADENCE_SHOW) or {},
+        "approval": lambda: optional_read(client, AUTOAPPROVE_SHOW) or {},
+        "plan": lambda: optional_read(client, PUBLICATION_PLAN, params={"weeks": 2}) or {},
+        "entitlements": lambda: optional_read(client, ENTITLEMENTS),
+        "managed": lambda: optional_read(client, BILLING_MANAGED_USAGE),
+    })
+    facts = answers["facts"]
+    facts.cadence, facts.approval, facts.publication_plan = answers["cadence"], answers["approval"], answers["plan"]
+    ctx.meta["status_cadence"] = (facts.publication_plan.get("cadence") or facts.cadence.get("cadence") or {})
+    entitlements = answers["entitlements"]
+    return dashboard(facts, entitlements=entitlements if (entitlements or {}).get("enabled") else None,
+                     managed=answers["managed"], indexing=indexing_of_listed(client, facts.articles))
+
+
+def indexing_of_listed(client, articles: list[dict[str, Any]], limit: int = 20) -> dict[str, Any] | None:
+    """Indexing for the dashboard from the article list already read: one inspection per published article, together."""
+    ids = [str(a["id"]) for a in articles if a.get("cms_publish_status") in _PUBLISHED_STATES][:limit]
+    try:
+        states = list(run_parallel({article_id: partial(read_indexing, client, article_id) for article_id in ids}).values())
+    except CliError as error:
+        return None if error.code == "indexing_not_enabled" else {"unavailable": error.message}
+    return {"published": len(ids), "indexed": sum(1 for state in states if is_indexed(state))}
+
+
+def indexing_line(indexing: dict[str, Any] | None) -> str:
+    if indexing is None:
+        return "Indexing: tracker not enabled yet"
+    if indexing.get("unavailable"):
+        return f"Indexing: unavailable right now ({indexing['unavailable']})"
+    if not indexing.get("published"):
+        return "Indexing: no published articles yet"
+    return (f"Indexing: {indexing['indexed']} of {indexing['published']} published articles indexed in Google"
+            "  ->  recala index status --all-published")

recala_cli/commands/topics.py

@@ -0,0 +1,328 @@
+"""`recala topics list`: the topic queue, as a projection agents can rely on."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+import click
+
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import TOPIC_ADD, TOPIC_APPROVE, TOPIC_DISMISS, TOPIC_WHY, TOPICS_LIST, TOPICS_SCOUT, TOPICS_SCOUT_STATUS, UP_NEXT_ADD, UP_NEXT_REMOVE, UP_NEXT_REORDER
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.human import describe_fields
+from recala_cli.ids import TOPIC_SECTIONS as SECTIONS, id_arguments, read_topics, resolve_topic, resolve_topic_id
+from recala_cli.labels import action_sentence, resource_label
+from recala_cli.polling import poll_until
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option, dry_run_option, accepted_yes_option, dry_run_option
+from recala_cli.views import pay_link_step, company_timezone, engine_name, local_time, timezone_label
+
+
+def project_topic(row: dict[str, Any]) -> dict[str, Any]:
+    """The CLI's promise per topic. The API row's internal fields (rationale, decay) stay out."""
+    return {
+        "id": row.get("id"),
+        "topic": row.get("topic"),
+        "status": row.get("status"),
+        "archetype": row.get("archetype"),
+        "score": row.get("effective_score"),
+        "article_id": row.get("article_id"),
+        "created_at": row.get("created_at"),
+    }
+
+
+#: A person reads this many topics per section; `--limit 0` shows the rest.
+PEOPLE_SECTION_ROWS = 20
+QUEUE_PAGE = 200
+
+
+def read_queue(client, *, limit: int | None = None, offset: int = 0) -> dict[str, Any]:
+    """The queue in as few calls as the API allows: one page of QUEUE_PAGE unless the backlog is longer."""
+    if limit:
+        return read_topics(client, limit=limit, offset=offset)
+    queue: dict[str, Any] = {name: [] for name in SECTIONS}
+    while True:
+        page = client.call(TOPICS_LIST, params={"limit": QUEUE_PAGE, "offset": offset})
+        for name in SECTIONS:
+            known = {row.get("id") for row in queue[name]}
+            queue[name] += [row for row in page.get(name) or [] if row.get("id") not in known]
+        queue["total"] = page.get("total") or 0
+        offset += QUEUE_PAGE
+        if offset >= queue["total"] or page.get("gated_count"):
+            return queue
+
+
+def _describe_topics(ctx: click.Context, result: dict[str, Any]) -> str:
+    show_all = ctx.meta.get("topics_show_all", False)
+    lines = []
+    for section in SECTIONS:
+        rows = result.get(section) or []
+        if rows:
+            shown = rows if show_all else rows[:PEOPLE_SECTION_ROWS]
+            lines.append(f"{section.replace('_', ' ').capitalize()} ({len(rows)})")
+            lines.extend(f"  {row['topic']}  [{str(row['id'])[:8]}]" for row in shown)
+            if len(shown) < len(rows):
+                lines.append(f"  {len(rows) - len(shown)} more: recala topics list --limit 0")
+    lines.append(f"{result.get('total', 0)} topics in total")
+    return "\n".join(lines)
+
+
+@click.group()
+def topics() -> None:
+    """Topics: what Recala proposes to write next."""
+
+
+def _scout_needs_plan(error: CliError) -> CliError:
+    """The server's refusal names the web billing page; the CLI names the command that makes a pay link."""
+    message = f"Topic scouting starts once a plan is active: {pay_link_step()}, then retry topic scouting."
+    details = {**(error.details or {}), "next": {"command": "recala topics scout", "human_action": {
+        "what": message, "where": "recala billing link --plan go"}}}
+    return CliError(error.exit_code, error.code, message, status=error.status, details=details)
+
+
+def scout_topics(ctx: click.Context, client: RecalaClient) -> dict[str, Any]:
+    """Resume a running scout, otherwise confirm a new one; preserve the server's gates."""
+    state = client.call(TOPICS_SCOUT_STATUS)
+    if state.get("state") != "running":
+        confirm(ctx, client, "Scout the first topics? This uses the company's recommendation allowance.")
+        try:
+            client.call(TOPICS_SCOUT, json={})
+        except CliError as error:
+            if error.code == "plan_activation_required":
+                raise _scout_needs_plan(error) from error
+            if error.code != "scout_running":
+                raise
+    result = poll_until(ctx, lambda: client.call(TOPICS_SCOUT_STATUS),
+                        lambda r: r.get("state") in ("done", "failed"), label="Scouting topics",
+                        timeout_seconds=960)
+    if result.get("state") == "failed":
+        raise CliError(ExitCode.CONFLICT, result.get("error_code") or "scout_failed",
+                       result.get("error_message") or "Topic scouting did not finish. Run recala topics scout to retry.")
+    return result
+
+
+@topics.command("scout")
+@common_options
+@command_runner(human=lambda r: f"Scout complete: {r.get('found', 0)} topics found. See: recala topics list")
+@accepted_yes_option
+@dry_run_option
+def scout(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Find new topics with the background scout.
+
+    The server's payment and entity gates apply."""
+    return scout_topics(ctx, open_client(ctx, org_flag))
+
+
+@topics.command("list")
+@common_options
+@command_runner(contextual_human=_describe_topics)
+@click.option("--section", type=click.Choice(SECTIONS), default=None, help="Only this section of the queue.")
+@click.option("--limit", type=click.IntRange(0, 200), default=None,
+              help="Fetch one page of this size. Default: every topic in the data, 20 per section on screen; 0 shows all.")
+@click.option("--offset", type=click.IntRange(0), default=0, show_default=True)
+def list_topics(ctx: click.Context, org_flag: str | None, section: str | None, limit: int | None, offset: int) -> dict[str, Any]:
+    """The topic queue, by section.
+
+    Up next, backlog, queued, processing, other."""
+    client = open_client(ctx, org_flag)
+    queue = read_queue(client, limit=limit, offset=offset)
+    ctx.meta["topics_show_all"] = limit is not None
+    wanted = (section,) if section else SECTIONS
+    result: dict[str, Any] = {name: [project_topic(row) for row in queue.get(name) or []] for name in wanted}
+    result["total"] = queue.get("total", 0)
+    return result
+
+
+def _describe_added_topic(ctx: click.Context, result: dict[str, Any]) -> str:
+    title = ctx.meta["added_topic"]
+    position = result.get("position")
+    if position is None:
+        return f"Added: {title}"
+    destination = "the top of Up next" if position == 1 else "Up next"
+    return f"Added to {destination} ({position} of {result.get('up_next_count', '?')}): {title}"
+
+
+@topics.command("add")
+@common_options
+@command_runner(contextual_human=_describe_added_topic)
+@click.argument("topic")
+@accepted_yes_option
+@dry_run_option
+def add_topic(ctx: click.Context, org_flag: str | None, topic: str) -> dict[str, Any]:
+    """Add your own topic (a buyer question) to the top of Up next."""
+    client = open_client(ctx, org_flag)
+    confirm(ctx, client, f"Add the topic \"{topic}\" to Up next?")
+    added: dict[str, Any] = client.call(TOPIC_ADD, json={"topic": topic})
+    ctx.meta["added_topic"] = (added.get("item") or {}).get("topic") or added.get("topic") or topic
+    return added
+
+
+@topics.command("approve")
+@common_options
+@command_runner(contextual_human=lambda ctx, r: action_sentence("Approved")(ctx, r) +
+                "\nNext: recala topics up-next add " + ctx.meta["up_next_selector"])
+@click.argument("topic_id")
+@id_arguments(topic_id="topic")
+@accepted_yes_option
+@dry_run_option
+def approve_topic(ctx: click.Context, org_flag: str | None, topic_id: str) -> dict[str, Any]:
+    """Keep a proposed topic."""
+    client = open_client(ctx, org_flag)
+    topic_id = resolve_topic_id(client, topic_id)
+    label = resource_label(ctx, client, "topic", topic_id)
+    from shlex import quote
+    subject = ctx.meta.get("result_subject", "")
+    ctx.meta["up_next_selector"] = quote(subject[1:-1] if subject.startswith('"') else topic_id)
+    confirm(ctx, client, f"Approve {label}?", machine_summary=f"Keep topic {topic_id}?")
+    kept: dict[str, Any] = client.call(TOPIC_APPROVE, path={"queue_id": topic_id})
+    return kept
+
+
+@topics.command("dismiss")
+@common_options
+@command_runner(contextual_human=action_sentence("Dropped"))
+@click.argument("topic_id")
+@id_arguments(topic_id="topic")
+@accepted_yes_option
+@dry_run_option
+def dismiss_topic(ctx: click.Context, org_flag: str | None, topic_id: str) -> dict[str, Any]:
+    """Drop a proposed topic from the queue."""
+    client = open_client(ctx, org_flag)
+    topic_id = resolve_topic_id(client, topic_id)
+    label = resource_label(ctx, client, "topic", topic_id)
+    confirm(ctx, client, f"Drop {label} from the queue?")
+    dropped: dict[str, Any] = client.call(TOPIC_DISMISS, path={"queue_id": topic_id})
+    return dropped
+
+
+#: What `recala topics why` tells a person whose topic waits for the company's own material.
+MATERIAL_HINT = ("This topic needs the company's own material: upload figures, cases or reports "
+                 "with: recala knowledge add <file>")
+
+
+def _without_empty(value: Any) -> Any:
+    """Drop blank strings, nulls, empty records and an unclassified kind, which a person cannot act on."""
+    if isinstance(value, dict):
+        kept = {key: _without_empty(item) for key, item in value.items()
+                if not (key == "kind" and item == "unknown")}
+        return {key: item for key, item in kept.items() if item not in (None, "", [], {})}
+    if isinstance(value, list):
+        return [item for item in map(_without_empty, value) if item not in (None, "", [], {})]
+    return value
+
+
+def describe_topic_why(ctx: click.Context, result: dict[str, Any]) -> str:
+    """Humanise evidence enums and instants, preserving free text, URLs and JSON."""
+    zone = company_timezone(ctx, result)
+    has_time = False
+    names = {"coverage_gap": "coverage gap", "exa_search": "Exa search", "trends": "search trends"}
+    enum_fields = {"kind", "lane", "basis", "status", "source", "engine", "archetype", "reason", "type",
+                   "reason_code", "required", "reachable", "tier", "level", "floor", "state", "missing"}
+
+    def human_value(value, field=""):
+        nonlocal has_time
+        if isinstance(value, dict):
+            return {key: human_value(item, key) for key, item in value.items()}
+        if isinstance(value, list):
+            return [human_value(item, field) for item in value]
+        if isinstance(value, str):
+            if re.match(r"^\d{4}-\d\d-\d\dT\d\d:", value):
+                has_time = True
+                return local_time(value, zone)
+            if field in enum_fields and re.fullmatch(r"[a-z][a-z0-9_]*", value, re.IGNORECASE):
+                return names.get(value.lower(), engine_name(value.lower()))
+        return value
+
+    details = {key: value for key, value in result.items() if key not in ("id", "topic")}
+    text = describe_fields(human_value(_without_empty(details)))
+    lines = []
+    if result.get("topic"):
+        lines.append(result["topic"] + (f" [{str(result['id'])[:8]}]" if result.get("id") else ""))
+    if has_time:
+        lines.append(timezone_label(zone))
+    readiness = result.get("topic_material_readiness") or {}
+    hint = [MATERIAL_HINT] if readiness.get("state") == "needs_company_material" else []
+    return "\n".join([*lines, text, *hint])
+
+
+@topics.command("why")
+@common_options
+@command_runner(contextual_human=describe_topic_why)
+@click.argument("topic_id")
+@id_arguments(topic_id="topic")
+def why_topic(ctx: click.Context, org_flag: str | None, topic_id: str) -> dict[str, Any]:
+    """Why Recala proposed this topic: the evidence behind it."""
+    client = open_client(ctx, org_flag)
+    topic_id = resolve_topic_id(client, topic_id)
+    rationale: dict[str, Any] = client.call(TOPIC_WHY, path={"item_id": topic_id})
+    return rationale
+
+
+@topics.group("up-next", invoke_without_command=True)
+@common_options
+@click.pass_context
+def up_next(ctx, org_flag, as_json):
+    """List and arrange the topics autopilot will write."""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(list_up_next, org_flag=org_flag, as_json=as_json)
+
+
+@up_next.command("list")
+@common_options
+@command_runner(human=lambda r: "\n".join(f"{i}. {row['topic']} [{str(row['id'])[:8]}]" for i, row in enumerate(r['up_next'], 1)) or "Up next is empty. Add a topic: recala topics up-next add <title>")
+def list_up_next(ctx, org_flag):
+    """List the ordered topics in Up next."""
+    data = read_queue(open_client(ctx, org_flag))
+    return {"up_next": data["up_next"]}
+
+
+def change_up_next(ctx, org_flag, topic, verb, position=None):
+    client = open_client(ctx, org_flag)
+    data = read_queue(client)
+    row = resolve_topic(data, topic)
+    ctx.meta["result_subject"] = row["topic"]
+    confirm(ctx, client, f"{verb.capitalize()} \"{row['topic']}\" {'in' if verb == 'move' else 'to' if verb == 'add' else 'from'} Up next?")
+    if verb == "move":
+        ordered = [entry['id'] for entry in data['up_next']]
+        if row['id'] not in ordered or position > len(ordered):
+            raise CliError(ExitCode.USAGE, "invalid_position", "Choose a topic and position shown by recala topics up-next list.")
+        ordered.remove(row['id'])
+        ordered.insert(position - 1, row['id'])
+        return client.call(UP_NEXT_REORDER, json={"ordered_ids": ordered})
+    return client.call(UP_NEXT_ADD if verb == "add" else UP_NEXT_REMOVE, json={"content_queue_id": row['id']})
+
+
+@up_next.command("add")
+@common_options
+@command_runner(contextual_human=action_sentence("Added to Up next"))
+@click.argument("topic")
+@accepted_yes_option
+@dry_run_option
+def add_up_next(ctx, org_flag, topic):
+    """Add an existing topic by id or exact title to Up next."""
+    return change_up_next(ctx, org_flag, topic, "add")
+
+
+@up_next.command("remove")
+@common_options
+@command_runner(contextual_human=action_sentence("Removed from Up next"))
+@click.argument("topic")
+@accepted_yes_option
+@dry_run_option
+def remove_up_next(ctx, org_flag, topic):
+    """Remove a topic from Up next.
+
+    By id or exact title; the API may refill it."""
+    return change_up_next(ctx, org_flag, topic, "remove")
+
+
+@up_next.command("move")
+@common_options
+@command_runner(contextual_human=action_sentence("Moved in Up next"))
+@click.argument("topic")
+@click.option("--position", type=click.IntRange(1), required=True, help="New position, starting at 1.")
+@accepted_yes_option
+@dry_run_option
+def move_up_next(ctx, org_flag, topic, position):
+    """Move a topic within the existing Up next order."""
+    return change_up_next(ctx, org_flag, topic, "move", position)