recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/article.py

@@ -0,0 +1,835 @@
+"""`recala article`: read, edit, AI-edit, hand over for review, share. (Approving and publishing: slice 4.)"""
+
+from __future__ import annotations
+
+import uuid
+from hashlib import sha256
+from datetime import datetime
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+from pathlib import Path
+from typing import Any
+
+import click
+
+from recala_cli.client import RecalaClient
+from recala_cli.ids import id_arguments, resolve_article_id, resolve_person_id, resolve_topic_id
+from recala_cli.endpoints import (
+    APPOINTMENT_BOOK,
+    APPOINTMENT_CANCEL,
+    ARTICLE_APPROVE,
+    ARTICLE_REGENERATE,
+    ARTICLE_RECHECK,
+    ARTICLE_BODY,
+    ARTICLE_COMMENTS,
+    ARTICLE_PERSON,
+    ARTICLE_READINESS,
+    ARTICLE_REDRAFT_APPLY,
+    ARTICLE_REDRAFT_LATEST,
+    ARTICLE_REDRAFT_START,
+    ARTICLE_REPUBLISH,
+    ARTICLE_REQUEST_CHANGES,
+    ARTICLE_SHOW,
+    ARTICLE_SUBMIT,
+    ARTICLE_UNPUBLISH,
+    ARTICLE_VERSION,
+    ARTICLE_VERSIONS,
+    ARTICLES_LIST,
+    BILLING_CREDITS,
+    COST_PREVIEW,
+    GENERATE_FROM_TOPIC,
+    REVIEW_LINK_CREATE,
+    REVIEW_LINK_REVOKE,
+    REVIEW_LINK_SHOW,
+    SHARE_TOKEN_ROTATE,
+)
+from recala_cli.display import display_name, terminal_text
+from recala_cli import config
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.human import (
+    RECHECK_VERDICT_CODES, cost_sentence, describe_local_fields, describe_comments, describe_creation, describe_cost_refusal, describe_edit, describe_fields, describe_schedule,
+    describe_recheck, publish_state_words, recheck_findings,
+)
+from recala_cli.labels import action_sentence, named_local_result, named_result, resource_label
+from recala_cli.views import company_timezone, local_time
+from recala_cli.polling import indicator, poll_until
+from recala_cli.article_runs import (describe_run, ensure_outcome, failed_rerun, hold_text, resume_command,
+                                     wait_for_article)
+from recala_cli.runtime import (
+    accepted_yes_option, dry_run_option,
+    command_runner, common_options, confirm, ignored_yes_option, open_client, optional_read, yes_option,
+)
+
+
+def project_article(detail: dict[str, Any], *, markdown: bool = False) -> dict[str, Any]:
+    """The CLI's promise about one article; the API's full payload stays behind it."""
+    article = detail.get("article") or {}
+    shown = {
+        "id": article.get("id"),
+        "title": article.get("article_title") or article.get("topic"),
+        "topic": article.get("topic"),
+        "publish_status": article.get("cms_publish_status"),
+        "review_status": article.get("review_status"),
+        "person_id": article.get("person_id"),
+        "word_count": article.get("word_count"),
+        "grade": article.get("evaluation_grade") or None,  # the API stores "" for an article it never graded
+        "score": article.get("evaluation_score"),
+        "created_at": article.get("created_at"),
+        "hold": detail.get("hold"),
+        "brand_asks": detail.get("brand_asks") or [],
+        "change_requests": detail.get("revision_requests") or [],
+    }
+    if article.get("language"):
+        shown["language"] = article["language"]
+    if markdown:
+        shown["markdown"] = article.get("markdown_content") or ""
+    return shown
+
+
+_optional = optional_read
+
+
+@click.group()
+def article() -> None:
+    """Articles: read, edit, AI-edit, hand over for review, share."""
+
+
+def article_date(row):
+    return str(row.get("published_at") or row.get("scheduled_at") or row.get("created_at") or "")
+
+
+def _status_of(row):
+    return str(row.get("cms_publish_status") or row.get("review_status") or "draft").replace("_", " ")
+
+
+def describe_articles(ctx, result):
+    zone = company_timezone(ctx, result)
+    rows = result["articles"]
+    lines = [f"{local_time(article_date(a), zone)}  {_status_of(a)}  "
+             f"{a.get('article_title') or a.get('topic')}  "
+             f"{('[' + a['language'] + ']  ') if a.get('language') else ''}[{str(a['id'])[:8]}]" for a in rows]
+    total = result.get("total")
+    if isinstance(total, int):
+        lines.append(f"{len(rows)} of {total} articles" if len(rows) != total else f"{total} articles")
+    return "\n".join(lines)
+
+
+@article.command("list")
+@common_options
+@command_runner(contextual_human=describe_articles)
+@click.option("--limit", type=click.IntRange(1, 100), default=50, show_default=True)
+@click.option("--offset", type=click.IntRange(0), default=0, show_default=True)
+@click.option("--status", default=None, help="Only articles in this state, e.g. published or draft.")
+@click.option("--language", default=None, help="Only articles in this language, e.g. de.")
+def list_articles(ctx: click.Context, org_flag: str | None, limit: int, offset: int, status: str | None,
+                  language: str | None) -> dict[str, Any]:
+    """The company's articles, newest first."""
+    listed: dict[str, Any] = open_client(ctx, org_flag).call(ARTICLES_LIST, params={"limit": limit, "offset": offset})
+    rows = [a for a in listed.get("articles") or []
+            if (not status or _status_of(a) == status.replace("_", " ").lower())
+            and (not language or str(a.get("language") or "").lower() == language.lower())]
+    listed["articles"] = sorted(rows, key=article_date, reverse=True)
+    return listed
+
+
+@article.command("show")
+@common_options
+@command_runner(contextual_human=lambda ctx, a: f"{a['title']}\n{article_state_line(a)}"
+                                + change_request_lines(a["change_requests"])
+                                + (f"\n\n{a['markdown']}" if "markdown" in a else "")
+                                + ("\n" + hold_text(ctx.meta["shown_article"]["hold"], a["id"], ctx=ctx)
+                                   if a.get("hold") else ""))
+@click.option("--markdown", is_flag=True, help="Include the article's text.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def show(ctx: click.Context, org_flag: str | None, markdown: bool, article_id: str) -> dict[str, Any]:
+    """One article: status, author, hold, questions.
+
+    The open questions too, and the text with --markdown."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    detail = client.call(ARTICLE_SHOW, path={"article_id": article_id})
+    shown = project_article(detail, markdown=markdown)
+    ctx.meta["shown_article"] = shown
+    return shown
+
+
+def article_state_line(shown: dict[str, Any]) -> str:
+    """Grade, review, publishing and length in words: never a snake_case state or "None"."""
+    grade = f"Grade {shown['grade']}" if shown.get("grade") else "Not graded"
+    review = str(shown.get("review_status") or "draft").replace("_", " ")
+    published = publish_state_words(shown.get("publish_status"))
+    words = f" · {shown['word_count']} words" if shown.get("word_count") is not None else ""
+    return f"  {grade} · {review} · {published}{words}"
+
+
+def change_request_lines(requests: list[dict[str, Any]]) -> str:
+    """What the reviewer asked to change, open ones first; nothing when there were none."""
+    if not requests:
+        return ""
+    ordered = sorted(requests, key=lambda request: request.get("resolved_at") is not None)
+    open_count = sum(request.get("resolved_at") is None for request in requests)
+    lines = [f"Change requests ({open_count} open):"]
+    for request in ordered:
+        state = "Open" if request.get("resolved_at") is None else "Resolved"
+        section = f" ({request['section_key']})" if request.get("section_key") else ""
+        lines.append(f"  {state}{section}: {' '.join(str(request.get('feedback') or '').split())}")
+    return "\n" + "\n".join(lines)
+
+
+def describe_article_status(ctx, result):
+    shown = ctx.meta["shown_article"]
+    last_rerun = result.get("last_rerun")
+    return (f"{shown['title']}\nAuthor: {ctx.meta.get('author_label') or 'not configured'}\n"
+            + describe_fields({k: v for k, v in result.items() if k not in {"id", "person_id", "last_rerun"}})
+            + (f"\nLast re-run: {display_name(last_rerun.get('message'))}" if last_rerun else "")
+            + ("\n" + hold_text(shown["hold"], shown["id"], ctx=ctx) if shown.get("hold") else ""))
+
+
+@article.command("status")
+@common_options
+@command_runner(contextual_human=describe_article_status)
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def status(ctx: click.Context, org_flag: str | None, article_id: str) -> dict[str, Any]:
+    """Where the article stands now.
+
+    Review, publishing, author, hold, versions and review link."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    detail = client.call(ARTICLE_SHOW, path={"article_id": article_id})
+    shown = project_article(detail)
+    ctx.meta["shown_article"] = shown
+    if shown.get("person_id"):
+        ctx.meta["author_label"] = resource_label(ctx, client, "person", shown["person_id"], result_subject=False)
+    versions = _optional(client, ARTICLE_VERSIONS, article_id=article_id)
+    link = _optional(client, REVIEW_LINK_SHOW, article_id=article_id)
+    return {
+        "id": shown["id"],
+        "review_status": shown["review_status"],
+        "publish_status": shown["publish_status"],
+        "person_id": shown["person_id"],
+        "grade": shown["grade"],
+        "score": shown["score"],
+        "held": shown["hold"] is not None,
+        "versions": None if versions is None else len(versions.get("versions") or []),
+        "review_token": None if link is None else link.get("review_token"),
+        **({"last_rerun": last_rerun} if (last_rerun := failed_rerun(detail.get("recovery"))) else {}),
+    }
+
+
+@article.command("versions")
+@common_options
+@command_runner(contextual_human=named_local_result(describe_local_fields))
+@click.option("--show", "number", type=click.IntRange(1), default=None, help="One version's text and changes.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def versions(ctx: click.Context, org_flag: str | None, number: int | None, article_id: str) -> dict[str, Any]:
+    """Every saved version of the article.
+
+    --show N prints one of them."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    resource_label(ctx, client, "article", article_id)
+    if number is None:
+        listed: dict[str, Any] = client.call(ARTICLE_VERSIONS, path={"article_id": article_id})
+        return listed
+    one: dict[str, Any] = client.call(ARTICLE_VERSION, path={"article_id": article_id, "number": str(number)})
+    return one
+
+
+def describe_link_warnings(result: dict[str, Any]) -> str:
+    lines = [f"Link warning (line {warning['line']}): {warning['url']} — {warning['reason']}"
+             for warning in result.get('link_warnings') or []]
+    if result.get('link_policy_error'):
+        lines.append('Link policy could not be checked; the edit was saved.')
+    return ''.join('\n' + line for line in lines)
+
+
+@article.command("edit")
+@common_options
+@command_runner(contextual_human=named_result(lambda result: describe_edit(result) + describe_link_warnings(result)))
+@click.option("--body-file", type=click.Path(exists=True, dir_okay=False, path_type=Path),
+              help="Replace the text with this Markdown file.")
+@click.option("--ai", "notes", multiple=True, help="An AI edit: one note per --ai (a paid model call; 3 per article).")
+@click.option("--wait", is_flag=True, help="With --ai: wait until the AI draft is ready.")
+@click.option("--timeout", type=click.IntRange(10, 3600), default=600, show_default=True)
+@click.option("--apply", is_flag=True,
+              help="Keep the finished AI draft's changes (all but --undo); this also hands the article over for review.")
+@click.option("--undo", default="", help="With --apply: comma-separated change numbers to undo, e.g. 2,5.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@accepted_yes_option
+@dry_run_option
+def edit(ctx: click.Context, org_flag: str | None, body_file: Path | None, notes: tuple[str, ...], wait: bool, timeout: int,
+         apply: bool, undo: str, article_id: str) -> dict[str, Any]:
+    """Edit the text, or ask for and keep an AI edit.
+
+    --body-file replaces the text, --ai "notes" asks for an AI edit, --apply keeps the AI draft."""
+    chosen = [bool(body_file), bool(notes), apply]
+    if sum(chosen) != 1:
+        raise click.UsageError("Choose one: --body-file, --ai or --apply.")
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    path = {"article_id": article_id}
+    label = resource_label(ctx, client, "article", article_id)
+    if body_file:
+        confirm(ctx, client, f"Replace the text of {label} with {body_file.name}?")
+        edited: dict[str, Any] = client.call(ARTICLE_BODY, path=path, json={"markdown_content": body_file.read_text()})
+        return edited
+    if apply:
+        latest = client.call(ARTICLE_REDRAFT_LATEST, path=path).get("redraft") or {}
+        if not latest.get("id"):
+            raise CliError(ExitCode.CONFLICT, "no_redraft", "This article has no AI draft to keep.")
+        choices = {number.strip(): "undo" for number in undo.split(",") if number.strip()}
+        confirm(ctx, client, f"Keep the AI draft's changes on {label}? This also hands it over for review.")
+        applied: dict[str, Any] = client.call(
+            ARTICLE_REDRAFT_APPLY, path={**path, "redraft_id": latest["id"]}, json={"choices": choices}
+        )
+        return applied
+    confirm(ctx, client, f"Ask for an AI edit of {label} (a paid model call)?")
+    started: dict[str, Any] = client.call(ARTICLE_REDRAFT_START, path=path, json={"notes": list(notes)})
+    if not wait:
+        return started
+    return wait_for_redraft(ctx, client, path, timeout, label=f"Writing the AI draft of {label}")
+
+
+def wait_for_redraft(ctx: click.Context, client: RecalaClient, path: dict[str, str], timeout: int, *,
+                     label: str = "Writing the AI draft") -> dict[str, Any]:
+    """Watch the AI edit with the shared pacing: a read a minute, a pause after a slow read, none in tick minutes."""
+
+    def read() -> dict[str, Any]:
+        current: dict[str, Any] = client.call(ARTICLE_REDRAFT_LATEST, path=path)
+        redraft = current.get("redraft") or {}
+        if redraft.get("status") == "failed":  # raised inside, so the wait ends as stopped, never as done
+            error = redraft.get("error") or {}
+            reason = error.get("message") or "Recala gave no reason."
+            if error.get("reason"):
+                reason = f"{reason} ({error['reason']})"
+            raise CliError(ExitCode.CONFLICT, "redraft_failed", f"The AI edit failed: {reason}", details=current)
+        return current
+
+    return poll_until(ctx, read, lambda current: (current.get("redraft") or {}).get("status") != "running",
+                      label=label, timeout_seconds=timeout)
+
+
+@article.command("person")
+@common_options
+@command_runner(contextual_human=action_sentence("Author assigned to"))
+@click.option("--person", "person_id", required=True, help="The author (recala authors list) who signs this article.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@accepted_yes_option
+@dry_run_option
+def person(ctx: click.Context, org_flag: str | None, person_id: str, article_id: str) -> dict[str, Any]:
+    """Link the article to the named person who will sign it."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    person_id = resolve_person_id(client, person_id)
+    label = resource_label(ctx, client, "article", article_id)
+    author_label = resource_label(ctx, client, "person", person_id, result_subject=False)
+    confirm(ctx, client, f"Make {author_label} the author who signs {label}?",
+            machine_summary=f"Make {person_id} the author who signs article {article_id}?")
+    linked: dict[str, Any] = client.call(ARTICLE_PERSON, path={"article_id": article_id}, json={"person_id": person_id})
+    return linked
+
+
+@article.command("submit")
+@common_options
+@command_runner(contextual_human=action_sentence("In review"))
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@accepted_yes_option
+@dry_run_option
+def submit(ctx: click.Context, org_flag: str | None, article_id: str) -> dict[str, Any]:
+    """Hand the article over for the person's review."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Hand {label} over for review?")
+    submitted: dict[str, Any] = client.call(ARTICLE_SUBMIT, path={"article_id": article_id})
+    return submitted
+
+
+@article.command("request-changes")
+@common_options
+@command_runner(contextual_human=action_sentence("Changes requested for"))
+@click.option("--note", required=True, help="What should change.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@accepted_yes_option
+@dry_run_option
+def request_changes(ctx: click.Context, org_flag: str | None, note: str, article_id: str) -> dict[str, Any]:
+    """Send the article back with a change request."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Send {label} back with your change request?")
+    requested: dict[str, Any] = client.call(ARTICLE_REQUEST_CHANGES, path={"article_id": article_id},
+                                            json={"feedback": note})
+    return requested
+
+
+@article.command("comments")
+@common_options
+@command_runner(contextual_human=named_result(describe_comments))
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def comments(ctx: click.Context, org_flag: str | None, article_id: str) -> dict[str, Any]:
+    """Comments left through the review link."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    resource_label(ctx, client, "article", article_id)
+    listed: dict[str, Any] = client.call(ARTICLE_COMMENTS, path={"article_id": article_id})
+    return listed
+
+
+@article.command("share")
+@common_options
+@command_runner(contextual_human=named_local_result(describe_local_fields))
+@ignored_yes_option
+@click.option("--review-link", "create", is_flag=True, help="Turn the review link on (or replace it).")
+@click.option("--rotate", is_flag=True, help="Replace the article's share token; the old link stops working.")
+@click.option("--revoke", is_flag=True, help="Turn the review link off.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@dry_run_option
+def share(ctx: click.Context, org_flag: str | None, yes: bool, create: bool, rotate: bool, revoke: bool,
+          article_id: str) -> dict[str, Any]:
+    """Show or manage the article's review link.
+
+    --review-link makes one; --rotate / --revoke kill the old one (after you confirm)."""
+    if sum([create, rotate, revoke]) > 1:
+        raise click.UsageError("Choose one of --review-link, --rotate, --revoke.")
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    if rotate or revoke:
+        confirm(ctx, client, f"Anyone holding the current link for {label} will lose access. Go ahead?", yes=yes,
+                machine_summary="Anyone holding the current link will lose access. Go ahead?")
+    elif create:
+        confirm(ctx, client, f"Turn on the review link for {label}?")
+    endpoint = (REVIEW_LINK_CREATE if create else SHARE_TOKEN_ROTATE if rotate
+                else REVIEW_LINK_REVOKE if revoke else REVIEW_LINK_SHOW)
+    answer: dict[str, Any] = client.call(endpoint, path={"article_id": article_id})
+    if answer.get("review_token"):  # the page the web app serves for a share token: {web}/share/{token}
+        answer = {**answer, "review_url": f"{config.web_url()}/share/{answer['review_token']}"}
+    return answer
+
+
+# ── slice 4: approving, publishing, spending ─────────────────────────────────
+
+#: Starting a run and each status read use short, independent HTTP requests.
+_GENERATION_TIMEOUT_SECONDS = 60.0
+
+
+@article.command("approve")
+@common_options
+@command_runner(contextual_human=action_sentence("Approved"))
+@yes_option
+@click.option("--read", is_flag=True, help="Show the current text and acknowledge reading it before approval.")
+@click.option(
+    "--reconfirm-current", is_flag=True,
+    help=("Refresh approval of an already-approved original; "
+          "requires a human session and current checks."),
+)
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@dry_run_option
+def approve(
+    ctx: click.Context, org_flag: str | None, yes: bool, article_id: str,
+    read: bool = False, reconfirm_current: bool = False,
+) -> dict[str, Any]:
+    """Approve the article; its named author signs it.
+
+    A key needs the publish scope; its owner is on record."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    return approve_article(
+        ctx, client, article_id, yes=yes, read=read, reconfirm_current=reconfirm_current
+    )
+
+
+def approve_article(
+    ctx: click.Context, client: RecalaClient, article_id: str, *,
+    yes: bool = False, read: bool = False, reconfirm_current: bool = False,
+) -> dict[str, Any]:
+    label = resource_label(ctx, client, "article", article_id)
+    payload = {}
+    if read:
+        detail = client.call(ARTICLE_SHOW, path={"article_id": article_id})
+        current_text = (detail.get("article") or {}).get("markdown_content")
+        if not isinstance(current_text, str) or not current_text.strip():
+            raise CliError(ExitCode.CONFLICT, "article_body_unavailable", "The current text is unavailable. Read the saved article before approving it.")
+        # What the person reads is sanitized; the receipt below hashes the exact stored body.
+        click.echo(terminal_text(current_text, keep_layout=True), err=True)
+        payload["json"] = {"read_receipt": {"body_sha256": sha256(current_text.encode("utf-8")).hexdigest()}}
+    if reconfirm_current:
+        payload.setdefault("json", {})["reconfirm_current"] = True
+    confirm(ctx, client, f"Approve {label}? Approving is the author's signature on it.", publishes=True, yes=yes)
+    try:
+        approved: dict[str, Any] = client.call(ARTICLE_APPROVE, path={"article_id": article_id}, **payload)
+    except CliError as error:
+        if error.code == "invalid_transition" and (error.details or {}).get("from") == "draft":
+            selector = article_id if ctx.obj.get("as_json") else article_id[:8]
+            error.message = f"Submit it for review first: recala article submit {selector}"
+        elif error.code == "below_minimum_grade_unread":
+            selector = article_id if ctx.obj.get("as_json") else article_id[:8]
+            error.message = (f"Read the current text with recala article show {selector} --markdown, "
+                             f"then acknowledge it with recala article approve {selector} --read.")
+        raise
+    return approved
+
+
+@article.command("unpublish")
+@common_options
+@command_runner(contextual_human=action_sentence("Unpublished"))
+@yes_option
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@dry_run_option
+def unpublish(ctx: click.Context, org_flag: str | None, yes: bool, article_id: str) -> dict[str, Any]:
+    """Take a published article off the site (the CMS first)."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Unpublish {label}? This takes the page off the site.", publishes=True, yes=yes)
+    done: dict[str, Any] = client.call(ARTICLE_UNPUBLISH, path={"article_id": article_id})
+    return done
+
+
+def republish_preview(detail: dict[str, Any]) -> dict[str, Any]:
+    """Preview the stored article; the POST still enforces the server's publish gates."""
+    shown = project_article(detail)
+    cms_response = (detail.get("article") or {}).get("cms_response") or {}
+    if detail.get("hold"):
+        would = "refused"
+        reason = "This article is held for review, so it cannot go to your site yet."
+    elif shown["review_status"] != "approved":
+        would = "refused"
+        reason = "This article is not approved. Have the named author approve it before republishing."
+    elif not shown["person_id"]:
+        would = "refused"
+        reason = "This article has no named author. Link the person who signs it before republishing."
+    elif cms_response.get("post_id"):
+        would = "update_existing"
+        reason = "Would update the existing page on your site (Recala re-checks approval and proof first)."
+    else:
+        would = "publish_new"
+        reason = "Would publish a new page on your site (Recala re-checks approval and proof first)."
+    return {"dry_run": True, "title": shown["title"] or "Untitled", "review_status": shown["review_status"],
+            "publish_status": shown["publish_status"], "live_url": cms_response.get("post_url"),
+            "would": would, "reason": reason}
+
+
+def describe_republish(ctx: click.Context, result: dict[str, Any]) -> str:
+    if result.get("dry_run"):
+        next_command = "status" if result["would"] == "refused" else "republish"
+        return (f"{result['title']}: {result['reason']}\n"
+                f"Next: recala article {next_command} {ctx.params['article_id'][:8]}")
+    action = {"updated": "Updated", "created": "Published"}.get(result.get("action"), "Republished")
+    sentence = f"{action} {ctx.meta['result_subject']} on your site"
+    return sentence + (f": {result['post_url']}" if result.get("post_url") else ".")
+
+
+@article.command("republish")
+@common_options
+@command_runner(contextual_human=describe_republish)
+@yes_option
+@click.option("--dry-run", is_flag=True, help="Preview updating or publishing the article; change nothing.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def republish(ctx: click.Context, org_flag: str | None, yes: bool, dry_run: bool, article_id: str) -> dict[str, Any]:
+    """Publish corrections to your site.
+
+    Updates the existing page when one is recorded."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    if dry_run:
+        return republish_preview(client.call(ARTICLE_SHOW, path={"article_id": article_id}))
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Republish {label}? This updates its page on your site, or publishes it if it has none.", publishes=True, yes=yes)
+    done: dict[str, Any] = client.call(ARTICLE_REPUBLISH, path={"article_id": article_id})
+    return done
+
+
+def _readiness(client: RecalaClient, article_id: str) -> dict[str, Any]:
+    answer: dict[str, Any] = client.call(ARTICLE_READINESS, path={"article_id": article_id})
+    return answer
+
+
+@article.command("schedule")
+@common_options
+@command_runner(contextual_human=named_result(describe_schedule))
+@yes_option
+@click.option("--at", "at", required=True, type=click.DateTime(["%Y-%m-%dT%H:%M", "%Y-%m-%d %H:%M"]),
+              help="Local time in the company's timezone, e.g. 2026-10-06T09:00.")
+@click.option("--tz", default=None, help="Timezone (default: the company's).")
+@click.option("--dry-run", is_flag=True, help="Show whether it can be scheduled; change nothing.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def schedule(ctx: click.Context, org_flag: str | None, yes: bool, at: datetime, tz: str | None, dry_run: bool,
+             article_id: str) -> dict[str, Any]:
+    """Schedule an approved article to publish at a time."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    if dry_run:
+        resource_label(ctx, client, "article", article_id)
+        ready = _readiness(client, article_id)
+        candidate = ready.get("candidate") or {}
+        return {"dry_run": True, "can_schedule": bool(candidate.get("can_schedule")), "blockers": candidate.get("blockers") or [],
+                "timezone": tz or ready.get("timezone"), "destination": ready.get("destination")}
+    return schedule_article(ctx, client, article_id, at=at, tz=tz, yes=yes)
+
+
+#: Calendar blockers that need more than their code to be understood.
+BLOCKER_HINTS = {
+    "sanity_on_demand_only": "sanity_on_demand_only (this Recala server publishes Sanity articles on demand only; "
+                             "scheduling needs SANITY_SCHEDULING_ENABLED)",
+}
+
+
+def local_instant(at: datetime, zone: str) -> datetime:
+    """The wall-clock time the person typed, in the company's timezone, with its offset (the API refuses a bare time)."""
+    try:
+        return at.replace(tzinfo=ZoneInfo(zone))
+    except ZoneInfoNotFoundError as error:
+        raise CliError(ExitCode.USAGE, "invalid_timezone", f"{zone} is not a timezone (e.g. Europe/Madrid).") from error
+
+
+def schedule_article(ctx: click.Context, client: RecalaClient, article_id: str, *, at: datetime, tz: str | None,
+                     yes: bool = False) -> dict[str, Any]:
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Schedule {label} for {at:%Y-%m-%d %H:%M}? It publishes then without asking "
+            "again.", publishes=True, yes=yes)
+    ready = _readiness(client, article_id)
+    candidate = ready.get("candidate") or {}
+    if not candidate.get("can_schedule"):
+        blockers = [BLOCKER_HINTS.get(b, b) for b in candidate.get("blockers") or ["unknown"]]
+        raise CliError(ExitCode.CONFLICT, "not_ready", f"This article cannot be scheduled yet: {', '.join(blockers)}.")
+    zone = tz or ready.get("timezone") or "UTC"
+    body: dict[str, Any] = {
+        "scheduled_at": local_instant(at, zone).isoformat(), "timezone": zone,
+        "article_revision": candidate["article_revision"], "operation_id": str(uuid.uuid4()),
+    }
+    version = (candidate.get("appointment") or {}).get("version")
+    if version:
+        body["expected_version"] = version
+    booked: dict[str, Any] = client.call(APPOINTMENT_BOOK, path={"article_id": article_id}, json=body)
+    return booked
+
+
+@article.command("unschedule")
+@common_options
+@command_runner(contextual_human=action_sentence("Unscheduled"))
+@yes_option
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@dry_run_option
+def unschedule(ctx: click.Context, org_flag: str | None, yes: bool, article_id: str) -> dict[str, Any]:
+    """Cancel the article's scheduled publication."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Cancel the scheduled publication of {label}?", publishes=True, yes=yes)
+    appointment = (_readiness(client, article_id).get("candidate") or {}).get("appointment") or {}
+    if not appointment.get("version"):
+        raise CliError(ExitCode.CONFLICT, "not_scheduled", "This article has no scheduled publication.")
+    cancelled: dict[str, Any] = client.call(
+        APPOINTMENT_CANCEL, path={"article_id": article_id},
+        json={"expected_version": appointment["version"], "operation_id": str(uuid.uuid4())},
+    )
+    return cancelled
+
+
+@article.command("create")
+@common_options
+@command_runner(contextual_human=lambda ctx, result: describe_creation(
+    result, topic_label=ctx.meta.get("creation_topic_label")) if result.get("dry_run") else describe_run(result, ctx=ctx))
+@ignored_yes_option
+@click.option("--topic", "queue_id", required=True, help="The topic id (recala topics list) to write.")
+@click.option("--dry-run", is_flag=True, help="Show the cost preview and the balance; spend nothing.")
+@click.option("--no-wait", is_flag=True, help="Start the run and return its id immediately.")
+@id_arguments(queue_id="topic")
+def create(ctx: click.Context, org_flag: str | None, yes: bool, queue_id: str, dry_run: bool, no_wait: bool) -> dict[str, Any]:
+    """Write a new article from a topic. Uses one article of the plan; always previews the cost first."""
+    client = open_client(ctx, org_flag)
+    queue_id = resolve_topic_id(client, queue_id)
+    if dry_run:
+        preview: dict[str, Any] = client.call(COST_PREVIEW, json={"action": "create_article", "queue_id": queue_id})
+        if not ctx.obj.get("as_json"):
+            label = resource_label(ctx, client, "topic", queue_id)
+            ctx.meta["creation_topic_label"] = f"topic [{queue_id[:8]}]" if label == f"topic {queue_id}" else label
+        return {"dry_run": True, "preview": preview, "credits": _optional(client, BILLING_CREDITS)}
+    return create_article(ctx, client, queue_id, yes=yes, no_wait=no_wait)
+
+
+def create_article(ctx: click.Context, client: RecalaClient, queue_id: str, *, yes: bool = False, no_wait: bool = False) -> dict[str, Any]:
+    """Preview the cost, then write the article (minutes). An unknown outcome is never retried blind."""
+    label = resource_label(ctx, client, "topic", queue_id)
+    confirm(ctx, client, f"Write a new article from {label}? It uses one of the plan's articles (see the cost "
+            "with --dry-run).", yes=yes,
+            machine_summary="Write a new article from this topic? It uses one of the plan's articles (see the cost "
+                            "with --dry-run).")
+    headers = {"Prefer": "respond-async", **preview_headers(client, queue_id=queue_id)}
+    try:
+        with indicator(ctx, "Writing the article (research, draft, checks)") as spinner:
+            created: dict[str, Any] = client.call(GENERATE_FROM_TOPIC, path={"queue_id": queue_id},
+                                                  extra_headers=headers, timeout=_GENERATION_TIMEOUT_SECONDS)
+            if spinner is not None:
+                spinner.done("Article run started")
+    except CliError as error:
+        if error.exit_code != ExitCode.UNAVAILABLE:
+            raise
+        raise CliError(ExitCode.UNAVAILABLE, "outcome_unknown",
+                       "The article may or may not have been created. Check `recala article list` before trying again; "
+                       "never retry blind.", error.status) from error
+    ensure_outcome(created, client, ctx=ctx)
+    if created.get("run_id"):
+        created["check_command"] = resume_command(client, str(created["run_id"]))
+        return created if no_wait else wait_for_article(ctx, client, str(created["run_id"]))
+    if not ctx.obj.get("as_json") and created.get("article_id"):
+        created["title"] = resource_label(ctx, client, "article", str(created["article_id"]))
+    return created
+
+
+#: The topic review gate's refusals (the API's review/queue_gate.py).
+_TOPIC_GATE_CODES = ("topic_not_approved", "topic_dismissed")
+
+
+def preview_headers(client: RecalaClient, **target: str) -> dict[str, str]:
+    """Bind credit-spending requests to the server's allowed, target-specific preview."""
+    preview = client.call(COST_PREVIEW, json={"action": "create_article", **target}) or {}
+    if not preview.get("allowed"):
+        if gate := next((code for code in preview.get("blockers") or [] if code in _TOPIC_GATE_CODES), None):
+            raise CliError(ExitCode.CONFLICT, gate, describe_cost_refusal(preview),  # the API's own 409 for it
+                           details={"code": gate, "queue_id": target.get("queue_id", "")})
+        raise CliError(ExitCode.PAYMENT_REQUIRED, "not_allowed",
+                       f"Not created: {', '.join(preview.get('blockers') or ['refused'])}.")
+    return {"X-Recala-Cost-Preview": preview["preview_id"]} if preview.get("preview_id") else {}
+
+
+@article.command("run")
+@common_options
+@command_runner(contextual_human=lambda ctx, result: describe_run(result, ctx=ctx))
+@click.argument("queue_id")
+def run_status(ctx, org_flag, queue_id):
+    """Wait for an existing creation run.
+
+    Never starts or pays for another run."""
+    return wait_for_article(ctx, open_client(ctx, org_flag), queue_id)
+
+
+@article.command("regenerate")
+@common_options
+@command_runner(contextual_human=lambda ctx, result: (
+    f"Dry run: re-running {result['title']} would cost: {result['cost']}. Nothing was started."
+    if result.get("dry_run") else describe_run(result, ctx=ctx)))
+@ignored_yes_option
+@click.option("--dry-run", is_flag=True, help="Show the re-run cost; start nothing.")
+@click.argument("article_id")
+@id_arguments(article_id="article")
+def regenerate(ctx, org_flag, yes, dry_run, article_id):
+    """Re-run a held article, after a cost preview.
+
+    Confirm the cost, then wait for review or another hold."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    headers, cost = regeneration_preview(client, article_id, as_json=ctx.obj.get("as_json"))
+    if dry_run:
+        return {"dry_run": True, "article_id": article_id, "title": label, "cost": cost}
+    if not ctx.obj.get("as_json"):
+        click.echo(f"Cost: {cost}.", err=True)
+    confirm(ctx, client, f"Re-run {label}? {cost}.", yes=yes)
+    try:
+        started = client.call(ARTICLE_REGENERATE, path={"article_id": article_id}, extra_headers=headers)
+    except CliError as error:
+        if error.code == "regenerate_cost_changed":
+            raise CliError(ExitCode.CONFIRMATION_REQUIRED, "confirmation_required", error.message, error.status) from error
+        if error.status == 409:
+            error.message = "This article cannot be re-run in its current state. " + error.message + f" Check: recala article status {article_id}"
+        raise
+    if not ctx.obj.get("as_json"):
+        click.echo(f"Charge mode: {started.get('charge_mode', 'reported by server')}", err=True)
+    try:
+        result = wait_for_article(ctx, client, article_id, regeneration=True,
+                                  regenerate_id=started.get("regenerate_id"))
+    except CliError as error:
+        error.details = {**(error.details or {}), "charge_mode": started.get("charge_mode"),
+                         "regenerate_id": started.get("regenerate_id")}
+        raise
+    return {**result, "charge_mode": started.get("charge_mode")}
+
+
+def regeneration_preview(client, article_id, *, as_json=False):
+    """Sessions and keys use the same read-only, target-specific cost receipt."""
+    try:
+        preview = client.call(COST_PREVIEW, json={"action": "create_article", "article_id": article_id}) or {}
+    except CliError as error:
+        if error.exit_code in {ExitCode.NOT_AUTHENTICATED, ExitCode.FORBIDDEN}:
+            raise
+        raise CliError(ExitCode.CONFIRMATION_REQUIRED, "confirmation_required",
+                       "The re-run cost could not be previewed. Nothing was sent; request a fresh preview by running this command again.") from error
+    payment = preview.get("payment") or {}
+    how = payment.get("how")
+    if (preview.get("action") != "create_article" or preview.get("target") != article_id
+            or how not in {"free_rerun", "internal", "managed", "credit", "none_left"}):
+        message = "A matching re-run cost preview is required. Nothing was sent; run this command again."
+        if (not as_json and preview.get("action") == "create_article" and preview.get("target") == article_id
+                and preview.get("allowed") is False and preview.get("blockers")):
+            message = describe_cost_refusal(preview)
+        raise CliError(ExitCode.CONFIRMATION_REQUIRED, "confirmation_required",
+                       message)
+    if not preview.get("allowed"):
+        raise CliError(ExitCode.PAYMENT_REQUIRED, "not_allowed",
+                       f"Not re-run: {', '.join(preview.get('blockers') or ['refused'])}." if as_json else
+                       describe_cost_refusal(preview))
+    cost = regeneration_cost(preview)
+    headers = {"X-Recala-Cost-Preview": preview["preview_id"]} if preview.get("preview_id") else {}
+    headers["X-Recala-Regenerate-Amount"] = "1900" if how == "none_left" else "0"
+    return headers, cost
+
+
+def regeneration_cost(preview):
+    """The server's answer in words: only a hold of our own gate is a free re-run.
+
+    A plan article, an internal or managed run is named as such; the legacy PAYG
+    price is EUR 19. The API still enforces every plan gate.
+    """
+    how = (preview.get("payment") or {}).get("how")
+    if how == "free_rerun":
+        return "free re-run"
+    if how == "none_left":
+        return "EUR 19 will be charged"
+    return cost_sentence(preview)
+
+
+@article.command("recheck")
+@common_options
+@command_runner(human=lambda r: f"{r['title']}: checks passed; ready for review." + describe_link_warnings(r))
+@click.argument("article_id")
+@id_arguments(article_id="article")
+@accepted_yes_option
+@dry_run_option
+def recheck(ctx, org_flag, article_id):
+    """Check an edited article again.
+
+    Shows what still blocks approval."""
+    client = open_client(ctx, org_flag)
+    article_id = resolve_article_id(client, article_id)
+    label = resource_label(ctx, client, "article", article_id)
+    confirm(ctx, client, f"Check {label} again?")
+    try:
+        with indicator(ctx, f"Checking {label}"):
+            result = client.call(ARTICLE_RECHECK, path={"article_id": article_id})
+        if not result.get("passed"):
+            raise CliError(ExitCode.CONFLICT, "recheck_blocked", result.get("message") or describe_fields(result), details=result)
+    except CliError as error:
+        details = error.details or {}
+        if error.code in RECHECK_VERDICT_CODES or any(isinstance(details.get(key), list) for key in ("findings", "failures")):
+            error.exit_code = ExitCode.CONFLICT
+            error.details = {**details, "findings": recheck_findings(error.code, error.message, details)}
+            if not ctx.obj.get("as_json"):
+                error.message = describe_recheck(ctx, label, article_id, error.message, error.details)
+        raise
+    return {**result, "title": ctx.meta.get("result_subject", label)}