socialcli 0.3.0__py3-none-any.whl

socialctl/cli.py

@@ -0,0 +1,1766 @@
+"""The socialcli command-line interface."""
+
+from __future__ import annotations
+
+import http.server
+import hashlib
+import hmac
+import json
+import os
+import sys
+import urllib.parse
+import warnings
+import webbrowser
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+import httpx
+import typer
+from socialctl.approval_cli import read_approval
+import yaml
+
+from socialctl.authflow import (
+    AYUDA_META,
+    EstadoInvalido,
+    canjear_codigo,
+    construir_url_autorizacion,
+    generar_code_verifier,
+    generar_state,
+    intercambiar_token_meta,
+    obtener_paginas_meta,
+    verificar_state,
+)
+from socialctl.brands import (
+    AccountsInvalido,
+    Brand,
+    BrandNoEncontrada,
+    BrandYaExiste,
+    NombreDeMarcaInvalido,
+    cargar_brand,
+    crear_brand,
+)
+from socialctl.media import MediaInvalida, MediaNoEncontrada
+from socialctl.media_cli import media_app
+from socialctl.management.cli import changes_app, content_app
+from socialctl.management.comments_cli import comments_app
+from socialctl.management.meta_cli import meta_app
+from socialctl.management.stories_cli import story_app
+from socialctl.management.groups_cli import group_app
+from socialctl.migration_cli import migration_app
+from socialctl.schedule_remote import remote_app, is_remote, REMOTE_NOTICE
+from socialctl.native_schedule.cli import native_app
+from socialctl.metricas import LECTORES, leer_red  # noqa: F401  (importarlo registra)
+from socialctl.metricas.almacen import (
+    RETENCION_SNAPSHOTS_DIAS,
+    cargar_snapshot,
+    guardar_snapshot,
+    limpiar_snapshots_antiguos,
+    snapshot_anterior,
+)
+from socialctl.metricas.modelos import EstadoLectura, Snapshot
+from socialctl.metricas.piezas import PiezasIlegibles, actualizar_piezas
+from socialctl.metricas.resumen import escribir_resumen
+from socialctl.metricas.slugs import asignar_slugs
+from socialctl.models import Platform, Post, PostStatus
+from socialctl.workspace import default_root
+from socialctl.postfile import PostNoEncontrado, cargar_post
+from socialctl.publication_status import describe_result_with_observation
+from socialctl.read_reports import safe_error
+from socialctl.publish_output import PublishOutput
+from socialctl.publisher import (
+    PersistenciaError,
+    anexar_historial,
+    guardar_resultado,
+    publicar,
+    render_preview,
+    validar_todo,
+)
+from socialctl.scheduler import (
+    ScheduleEntry,
+    ScheduleError,
+    ScheduleStore,
+    approval_hash,
+    approval_review_reason,
+    now_utc,
+    parse_scheduled_at,
+    schedule_digest,
+)
+
+app = typer.Typer(help="Publish and manage your social content. Setup: brand new NAME, credentials generate-key/configure (headless), account login, then connect PLATFORM. Run agent-guide for the complete workflow.")
+
+
+@app.command('agent-guide')
+def agent_guide(topic: str = typer.Argument('setup', help='setup, publish, schedule, inbox, errors, permissions or all')):
+    """Read a focused agent guide offline, without an account or workspace."""
+    from socialctl.agent_guide import guide
+    try:
+        typer.echo(guide(topic))
+    except ValueError as error:
+        typer.echo(str(error),err=True)
+        raise typer.Exit(2) from None
+
+
+@app.command('report')
+def brand_report(
+    brand_nombre: str = typer.Option(..., '--brand'),
+    root: Path = typer.Option(default_root(), '--root'),
+    days: str = typer.Option('7', '--days', help='Daily comparison window, 1..365.'),
+    as_of: str | None = typer.Option(None, '--as-of', help='Last allowed snapshot date, YYYY-MM-DD.'),
+    top: str = typer.Option('5', '--top', help='Top observed items per platform, 1..50.'),
+    only: str | None = typer.Option(None, '--only'),
+    json_output: bool = typer.Option(False, '--json'),
+):
+    """Report growth and top content from saved snapshots; no network or account access."""
+    from socialctl.metricas.insights import build_report, render_report
+    from socialctl.read_reports import ReadReport, emit_report
+    exit_code = None
+    try:
+        window, limit = int(days), int(top)
+        day = date.fromisoformat(as_of) if as_of else date.today()
+        platform = Platform(only) if only else None
+        if not 1 <= window <= 365 or not 1 <= limit <= 50:
+            raise ValueError()
+    except ValueError:
+        result = ReadReport(status='error', errors=[{'code':'invalid_report_options',
+            'action':'correct_input', 'retryable':False,
+            'message':'Use days 1..365, top 1..50, a YYYY-MM-DD date and a supported platform.'}])
+        exit_code = 2
+    else:
+        try:
+            marca = cargar_brand(root, brand_nombre)
+            result = build_report(marca, days=window, as_of=day, top=limit, only=platform)
+        except (*_EXCEPCIONES_MARCA, OSError, ValueError, OverflowError):
+            result = ReadReport(status='error', errors=[{'code':'report_workspace_unavailable',
+                'action':'inspect_workspace', 'retryable':False}])
+    if json_output:
+        code = emit_report(result)
+    else:
+        typer.echo(render_report(result) if result.data else result.errors[0].get('message', result.errors[0]['code']))
+        from socialctl.read_reports import read_exit_code
+        code = read_exit_code(result.status)
+    raise typer.Exit(exit_code if exit_code is not None else code)
+
+
+@app.command('delivery-options')
+def show_delivery_options(
+    brand_nombre: str = typer.Option(..., '--brand'),
+    root: Path = typer.Option(default_root(), '--root'),
+    json_output: bool = typer.Option(False, '--json'),
+):
+    """Explain delivery modes and limits; does not authenticate or send media."""
+    from socialctl.delivery_options import delivery_options
+    result = delivery_options(_cargar_marca(root, brand_nombre))
+    if json_output:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        typer.echo('SocialCli does not store customer media on its SaaS server.')
+        for platform, row in result['platforms'].items():
+            typer.echo(f"{platform}: {row['selected_delivery']} — {row['instruction']}")
+
+
+def _show_version(value: bool):
+    if value:
+        from importlib.metadata import version
+        typer.echo('SocialCli ' + version('socialcli'))
+        raise typer.Exit()
+
+
+@app.callback()
+def main_options(version: bool = typer.Option(False, '--version', callback=_show_version,
+                                               is_eager=True, help='Show the installed SocialCli version.')):
+    pass
+
+from socialctl.connections.credential_cli import credentials_app
+app.add_typer(credentials_app, name="credentials")
+brand_app = typer.Typer(help="Brand management.")
+app.add_typer(brand_app, name="brand")
+app.add_typer(content_app, name="content")
+app.add_typer(changes_app, name="changes")
+app.add_typer(comments_app, name="comments")
+app.add_typer(meta_app, name="meta")
+app.add_typer(story_app, name="story")
+app.add_typer(group_app, name="group")
+app.add_typer(migration_app, name="queue-migration")
+app.add_typer(remote_app, name="schedule-remote")
+app.add_typer(native_app, name="native-schedule")
+app.add_typer(media_app, name="media")
+
+from socialctl.inventory_cli import register as register_inventory
+register_inventory(app, content_app)
+
+from socialctl.connections.cli import register as register_connections
+register_connections(app)
+from socialctl.connections.account_cli import account_app
+app.add_typer(account_app,name="account")
+from socialctl.management.community_batch_cli import register as register_community_batches
+register_community_batches(changes_app, default_root())
+from socialctl.inbox_cli import register as register_inbox
+register_inbox(app, default_root())
+from socialctl.youtube_data import register as register_youtube_data
+register_youtube_data(app)
+from socialctl.youtube_data_service import register as register_youtube_data_service
+register_youtube_data_service(app)
+
+RAIZ_POR_DEFECTO = default_root()
+
+# Excepciones que cargar_brand puede lanzar y que el CLI debe convertir en un
+# mensaje claro (nunca en una traza de Python).
+_EXCEPCIONES_MARCA = (BrandNoEncontrada, NombreDeMarcaInvalido, AccountsInvalido)
+
+# Excepciones que cargar_post puede lanzar. PostInvalido, SlugInvalido (la de
+# postfile.py) y NombreDeMediaInvalido son subclases de ValueError -ver sus
+# docstrings en socialctl/postfile.py-, así que capturar ValueError basta
+# para las tres sin tener que importarlas una a una.
+_EXCEPCIONES_POST = (PostNoEncontrado, MediaNoEncontrada, MediaInvalida, ValueError)
+
+# YouTube y TikTok comparten el mismo puerto/redirect_uri de callback local:
+# cada intento de `auth` levanta y cierra su propio servidor de un solo uso
+# (ver `_esperar_codigo`), así que no hay conflicto entre ellos aunque se
+# ejecuten en momentos distintos.
+PUERTO_CALLBACK = 8723
+REDIRECT_URI_OAUTH = f"http://localhost:{PUERTO_CALLBACK}/callback"
+TIMEOUT_CALLBACK_S = 300.0  # 5 minutos: tiempo razonable para completar el login en el navegador
+
+_PAGINA_LISTO = (
+    "<!doctype html><html><head><meta charset='utf-8'>"
+    "<title>socialcli</title></head><body>"
+    "<h1>Done. You can close this tab.</h1>"
+    "</body></html>"
+)
+
+# Hallazgo de revisión: la página que ve el usuario al volver del navegador
+# decía siempre "Listo" aunque la redirección trajera un `error` (el usuario
+# canceló la autorización o el proveedor la rechazó) o un `state` que no
+# coincide (posible CSRF, o simplemente una pestaña vieja de un intento
+# anterior). Las tres páginas son estáticas y fijas a propósito -nunca
+# interpolan `error`, `error_description` ni `state`- porque ese contenido
+# lo controla el proveedor (o quien sea que golpee el puerto del callback) y
+# podría llevar algo inesperado; `_pagina_para` elige entre las tres sin
+# volcar ningún dato de la petición.
+_PAGINA_ERROR_AUTORIZACION = (
+    "<!doctype html><html><head><meta charset='utf-8'>"
+    "<title>socialcli</title></head><body>"
+    "<h1>Authorization did not complete.</h1>"
+    "<p>Return to the terminal for details.</p>"
+    "</body></html>"
+)
+_PAGINA_ESTADO_INVALIDO = (
+    "<!doctype html><html><head><meta charset='utf-8'>"
+    "<title>socialcli</title></head><body>"
+    "<h1>Something went wrong with this authorization and it was not used.</h1>"
+    "<p>Return to the terminal and run the 'auth' command again.</p>"
+    "</body></html>"
+)
+
+
+def _pagina_para(recibido: dict[str, str], estado_esperado: str | None) -> str:
+    """Select the static OAuth callback page matching the result."""
+    if "error" in recibido:
+        return _PAGINA_ERROR_AUTORIZACION
+    if estado_esperado is not None and recibido.get("state") != estado_esperado:
+        return _PAGINA_ESTADO_INVALIDO
+    return _PAGINA_LISTO
+
+
+# Aviso adicional que se muestra justo antes de publicar en una red cuya
+# publicación implica una espera larga y silenciosa si no se avisa (hallazgo
+# de revisión: el CLI no daba ninguna señal de vida mientras Instagram
+# sondeaba el procesado del vídeo, hasta 5 minutos según la cadencia que
+# recomienda Meta -ver `InstagramAdapter` en `socialctl/adapters/
+# instagram.py`-). Un diccionario y no un `if` disperso porque el mismo
+# patrón podría hacer falta para otra red el día de mañana.
+_AVISO_ESPERA_LARGA = {
+    Platform.INSTAGRAM: (
+        ' (Instagram may take several minutes to verify video processing; allow it time)'
+    ),
+}
+
+
+def _mostrar_progreso(platform: Platform) -> None:
+    """Report the active platform before publication."""
+    typer.echo(f"Publishing on {platform.value}...{_AVISO_ESPERA_LARGA.get(platform, '')}")
+
+
+def _esperar_codigo(
+    puerto: int,
+    estado_esperado: str | None = None,
+    timeout_s: float = TIMEOUT_CALLBACK_S,
+) -> dict[str, str]:
+    """Run a single-use localhost callback server and return the authorization code."""
+    recibido: dict[str, str] = {}
+
+    class _Manejador(http.server.BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            consulta = urllib.parse.urlparse(self.path).query
+            recibido.update(dict(urllib.parse.parse_qsl(consulta)))
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(_pagina_para(recibido, estado_esperado).encode("utf-8"))
+
+        def log_message(self, *args: object) -> None:  # silencia el log del servidor
+            pass
+
+    try:
+        servidor = http.server.HTTPServer(("localhost", puerto), _Manejador)
+    except OSError as exc:
+        raise RuntimeError(
+            f'could not open port {puerto} in localhost ({exc}). Is another process using it? Close it and try again.'
+        ) from None
+
+    servidor.timeout = timeout_s
+    try:
+        servidor.handle_request()
+    finally:
+        servidor.server_close()
+
+    return recibido
+
+
+def _fallar(mensaje: str) -> None:
+    """Print an error and exit the command with code 1."""
+    typer.echo(mensaje)
+    raise typer.Exit(1)
+
+
+def _confirmar(mensaje: str) -> bool:
+    """Request explicit confirmation; empty input or EOF declines. English and legacy Spanish affirmative inputs are accepted."""
+    if not sys.stdin.isatty():
+        _fallar("Noninteractive approval required: show the complete preview, then use --approval-fingerprint DIGEST or --approval-stdin; --yes remains available for commands that document it. No input was read.")
+    typer.echo(f"{mensaje} [y/N]: ", nl=False)
+    while True:
+        try:
+            valor = input().strip().lower()
+        except EOFError:
+            valor = "n"
+        if valor in ("y", "yes", "s", "si", "sí"):
+            return True
+        if valor in ("n", "no", ""):
+            return False
+        typer.echo("Unrecognized answer (enter 'y' or 'n'): ", nl=False)
+
+
+def _cargar_marca(root: Path, nombre: str) -> Brand:
+    """Load the explicitly named brand or exit with a readable error."""
+    try:
+        return cargar_brand(root, nombre)
+    except _EXCEPCIONES_MARCA as exc:
+        _fallar(str(exc))
+
+
+def _cargar_post_con_avisos(brand: Brand, slug: str, *, avisos: list[str] | None = None, source_link: bool = False) -> Post:
+    """Load a post and display any loading warnings."""
+    with warnings.catch_warnings(record=True) as capturados:
+        warnings.simplefilter("always")
+        try:
+            post = cargar_post(brand, slug)
+        except _EXCEPCIONES_POST as exc:
+            for aviso in capturados:
+                typer.echo(f"WARNING: {aviso.message}")
+            typer.echo(str(exc))
+            raise typer.Exit(1)
+
+    for aviso in capturados:
+        if avisos is None:
+            typer.echo(f"WARNING: {aviso.message}")
+        else:
+            avisos.append(f"WARNING: {aviso.message}")
+    from socialctl.source_links import apply_source_mapping
+    try:
+        return apply_source_mapping(brand, post, required=source_link)
+    except ValueError as exc:
+        _fallar(str(exc))
+
+
+def _mostrar_comentario(result):
+    if result.publication_id:
+        typer.echo(f'Durable attempt: {result.publication_id}')
+    if result.first_comment_status:
+        typer.echo(f"First comment: {result.first_comment_status} (media: {result.platform_id or 'unconfirmed'})")
+    if result.first_comment_change_id:
+        typer.echo(f'Comment ChangeSet: {result.first_comment_change_id}')
+    for warning in result.warnings:
+        typer.echo(f"WARNING: {safe_error(warning)}")
+
+
+def _publicar_impl(
+    post: Post,
+    brand: Brand,
+    *,
+    dry_run: bool,
+    yes: bool,
+    only: list[Platform] | None,
+    motivo_exclusion: str = "not requested with --only",
+    retry_guard: bool = False,
+    approval_fingerprint: str | None = None,
+    approval_stdin: bool = False,
+    report=None,
+) -> None:
+    """Validate, preview and publish an already loaded post; shared by publish and retry."""
+    if only is not None:
+        destinos = [d for d in only if d in post.platforms]
+    else:
+        destinos = list(post.platforms)
+
+    errores = validar_todo(post, brand)
+    preview = render_preview(post, errores, brand=brand,
+        destinos=destinos if only is not None else None, motivo_exclusion=motivo_exclusion)
+    typer.echo(preview)
+    if report is not None:
+        report.preview = preview
+
+    if only is not None and not destinos:
+        _fallar(
+            "none of the requested platforms are in this post; there is nothing to publish."
+        )
+
+    errores_bloqueantes = {p: es for p, es in errores.items() if p in destinos}
+    if any(errores_bloqueantes.values()):
+        if report is not None:
+            report.add_error("validation_failed")
+        typer.echo("\nNothing will be published: fix the problems above.")
+        raise typer.Exit(1)
+
+    def publication_digest(current_post, current_brand):
+        document = {"schema": "socialcli.publish.preview.v1", "slug": current_post.slug,
+                    "platforms": {p.value: approval_hash(current_post, current_brand, p) for p in destinos}}
+        return hashlib.sha256(json.dumps(document, sort_keys=True, separators=(",", ":")).encode()).hexdigest()
+    try:
+        displayed_digest = publication_digest(post, brand)
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    typer.echo(f"Approval digest: {displayed_digest}")
+    if report is not None:
+        report.preview = preview + f"\nApproval digest: {displayed_digest}"
+    if dry_run:
+        if report is not None:
+            report.status = "preview"
+        typer.echo("\n--dry-run: nothing was published.")
+        raise typer.Exit(0)
+
+    exact_approval = approval_fingerprint is not None or approval_stdin
+    if exact_approval:
+        try:
+            supplied = read_approval(approval_fingerprint, approval_stdin=approval_stdin)
+        except ValueError as exc:
+            _fallar(str(exc))
+        if not hmac.compare_digest(supplied, displayed_digest):
+            _fallar("approval does not match the complete preview; run --dry-run and approve the current content")
+    if not yes and not exact_approval:
+        try:
+            confirmado = _confirmar(f"\nPublish on the {len(destinos)} platforms?")
+        except KeyboardInterrupt:
+            # Typer/Click convierten un Ctrl+C no atrapado en el código de
+            # salida 130 sin imprimir nada (ver `_main` en typer/core.py):
+            # correcto -no se publica nada-, pero deja al usuario sin
+            # confirmación visual, a diferencia de cualquier otro camino de
+            # cancelación de este comando, que sí dice "Cancelado". Aquí se
+            # informa y se relanza tal cual (nunca se traga la
+            # interrupción), para que typer siga terminando con 130 como
+            # siempre.
+            typer.echo("\nCanceled. Nothing was published.")
+            raise
+        if not confirmado:
+            if report is not None:
+                report.status = "cancelled"
+            typer.echo("Canceled. Nothing was published.")
+            raise typer.Exit(0)
+
+    from socialctl.source_links import verify_source_mapping
+    try:
+        current_brand = _cargar_marca(brand.raiz.parent, brand.nombre)
+        current_post = _cargar_post_con_avisos(current_brand, post.slug)
+        if (publication_digest(current_post, current_brand) != displayed_digest
+                or publication_digest(post, brand) != displayed_digest):
+            _fallar("content changed after the preview; run --dry-run again")
+        verify_source_mapping(brand, post)
+    except ValueError as exc:
+        _fallar(str(exc))
+
+    reporting = {}
+    if report is not None:
+        report.begin_write()
+        reporting = {'on_result': report.observe_safely}
+    resultados = publicar(post, brand, solo=destinos, on_progreso=_mostrar_progreso,
+                          retry_guard=retry_guard, **reporting)
+    if report is not None:
+        for result in resultados:
+            report.observe_safely(result)
+
+    typer.echo("")
+    for r in resultados:
+        estado = describe_result_with_observation(r)
+        typer.echo(f"{r.platform.value}: {estado} {safe_error(r.url or r.error or '')}".rstrip())
+        _mostrar_comentario(r)
+
+    try:
+        guardar_resultado(post, brand, resultados)
+        anexar_historial(post, brand, resultados)
+        if report is not None:
+            report.persistence = {"complete": True}
+    except PersistenciaError as exc:
+        if report is not None:
+            report.add_error("persistence_failed")
+        typer.echo(f"\n{safe_error(str(exc))}")
+        typer.echo(
+            'Publication WAS attempted for the results above; only saving them to disk failed.'
+        )
+        raise typer.Exit(1)
+
+    if any(r.status is PostStatus.ERROR for r in resultados):
+        raise typer.Exit(1)
+
+
+@brand_app.command("new")
+def brand_new(
+    nombre: str = typer.Argument(..., metavar="NAME", help="Name of the new brand."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Create a new brand directory from templates."""
+    try:
+        brand = crear_brand(root, nombre)
+    except (BrandYaExiste, NombreDeMarcaInvalido) as exc:
+        _fallar(str(exc))
+
+    typer.echo(f"Brand created at {brand.raiz}")
+    typer.echo("Next: complete brand.md and accounts.yml, then authenticate each platform.")
+
+
+def _auth_meta(brand: Brand, platform: Platform) -> None:
+    """Authenticate Facebook or Instagram using the configured Page's token."""
+    typer.echo(AYUDA_META)
+
+    client_id = typer.prompt("Meta app ID")
+    client_secret = typer.prompt("Meta app secret", hide_input=True)
+    token_usuario = typer.prompt(
+        "Paste the USER token obtained from the Graph API Explorer",
+        hide_input=True,
+    )
+
+    page_id = (brand.cuentas.get("facebook") or {}).get("page_id")
+    if not page_id:
+        _fallar(
+            f"facebook.page_id is missing in {brand.raiz / 'accounts.yml'}: configure it before authenticating Facebook or Instagram (both publish with that Page's token)."
+        )
+
+    typer.echo("Exchanging the token with Meta (this may take a few seconds)...")
+    try:
+        with httpx.Client(timeout=30) as client:
+            token_larga_duracion = intercambiar_token_meta(
+                client_id, client_secret, token_usuario, client
+            )
+            paginas = obtener_paginas_meta(token_larga_duracion, client)
+    except RuntimeError as exc:
+        _fallar(str(exc))
+
+    pagina = next((p for p in paginas if p.get("id") == page_id), None)
+    if pagina is None:
+        disponibles = ", ".join(
+            f"{p.get('name')!r} ({p.get('id')!r})" for p in paginas
+        ) or 'none'
+        _fallar(
+            f'the Page with ID {page_id!r} (configured in accounts.yml) is not among the Pages administered by the user who authorized the token. Available Pages: {disponibles}.'
+        )
+
+    token_pagina = pagina.get("access_token")
+    if not isinstance(token_pagina, str) or not token_pagina:
+        _fallar("Meta did not return a valid page token for that Page.")
+
+    brand.guardar_secreto(platform, {"access_token": token_pagina})
+    typer.echo(f"Credentials for {platform.value} saved for {brand.nombre}.")
+
+
+def _auth_oauth_redireccion(
+    brand: Brand, platform: Platform, *, youtube_management: bool = False
+) -> None:
+    """Authenticate YouTube or TikTok through a localhost redirect."""
+    if platform is Platform.YOUTUBE:
+        client_id = typer.prompt("Google Cloud client_id")
+        client_secret = typer.prompt("Google Cloud client_secret", hide_input=True)
+        credenciales_app = {"client_id": client_id, "client_secret": client_secret}
+        identificador = client_id
+    else:
+        client_key = typer.prompt("TikTok client_key")
+        client_secret = typer.prompt("TikTok client_secret", hide_input=True)
+        credenciales_app = {"client_key": client_key, "client_secret": client_secret}
+        identificador = client_key
+
+    estado = generar_state()
+    code_verifier = generar_code_verifier()
+
+    url = construir_url_autorizacion(
+        platform,
+        identificador,
+        REDIRECT_URI_OAUTH,
+        state=estado,
+        code_verifier=code_verifier,
+        youtube_management=youtube_management,
+    )
+    typer.echo(f"Opening the browser to authorize {platform.value}...")
+    typer.echo(url)
+    webbrowser.open(url)
+
+    try:
+        recibido = _esperar_codigo(PUERTO_CALLBACK, estado)
+    except RuntimeError as exc:
+        _fallar(str(exc))
+
+    if "error" in recibido:
+        detalle = recibido.get("error_description") or recibido["error"]
+        _fallar(f"{platform.value} rejected authorization: {detalle}")
+
+    try:
+        verificar_state(estado, recibido.get("state"))
+    except EstadoInvalido as exc:
+        _fallar(str(exc))
+
+    codigo = recibido.get("code")
+    if not codigo:
+        _fallar(
+            'no authorization code was received (was the tab closed before login completed?). Try again.'
+        )
+
+    try:
+        with httpx.Client(timeout=30) as client:
+            secreto = canjear_codigo(
+                platform, codigo, credenciales_app, REDIRECT_URI_OAUTH, client,
+                code_verifier=code_verifier,
+            )
+    except RuntimeError as exc:
+        _fallar(str(exc))
+
+    if platform is Platform.TIKTOK:
+        _guardar_open_id_tiktok(brand, secreto)
+
+    brand.guardar_secreto(platform, secreto)
+    typer.echo(f"Credentials for {platform.value} saved for {brand.nombre}.")
+
+
+def _guardar_open_id_tiktok(brand: Brand, secreto: dict) -> None:
+    """Save the newly exchanged TikTok open_id in accounts.yml when available."""
+    open_id = secreto.pop("open_id", None)
+    if not open_id:
+        typer.echo(
+            "Warning: TikTok did not return the account open_id. The access token was saved. Add tiktok.open_id manually in accounts.yml (see that section's comment or SETUP.md)."
+        )
+        return
+
+    try:
+        anterior = brand.guardar_open_id_tiktok(open_id)
+    except Exception:
+        typer.echo(
+            f"Warning: could not save open_id automatically in {brand.raiz / 'accounts.yml'} (check the structure of the 'tiktok:' section). The access token was saved; add tiktok.open_id manually."
+        )
+        return
+
+    if anterior is not None:
+        typer.echo(
+            f"Warning: TikTok open_id in accounts.yml changes from '{anterior}' to '{open_id}'."
+        )
+    else:
+        typer.echo(f"TikTok open_id saved in accounts.yml: {open_id}")
+
+
+@app.command()
+def auth(
+    red: str = typer.Argument(..., metavar="PLATFORM", help="Platform to authenticate, or status."),
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to authenticate."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    management: bool = typer.Option(
+        False,
+        "--management",
+        help="YouTube: also request youtube.force-ssl to edit metadata.",
+    ),
+    status_platform: Platform | None = typer.Option(None, "--platform", help="Explicit platform for auth status."),
+    json_output: bool = typer.Option(False, "--json", help="auth status: versioned output."),
+    no_browser: bool = typer.Option(False, '--no-browser', help='Print the SaaS connection link for the user without opening it.'),
+    analytics: bool = typer.Option(False, '--analytics', help='Request analytics access through the SaaS connection flow.'),
+    timeout: float = typer.Option(600, '--timeout', min=1, max=600, help='Maximum SaaS browser connection wait in seconds.'),
+    replace_independent: bool = typer.Option(False, '--replace-independent', help='Permit replacing independent credentials with browser approval.'),
+    independent: bool = typer.Option(False, '--independent', help='Legacy developer-owned app setup; requires an interactive terminal and your own app credentials.'),
+) -> None:
+    """Connect through SocialCli after account login; use connect for the full flow."""
+    if red == "status":
+        from socialctl.inventory_cli import show_auth_status
+        show_auth_status(root, brand_nombre, status_platform, json_output)
+        return
+    brand = _cargar_marca(root, brand_nombre)
+
+    try:
+        platform = Platform(red)
+    except ValueError:
+        validas = ", ".join(p.value for p in Platform)
+        _fallar(f'unknown platform: {red!r}. Valid platforms: {validas}')
+
+    from socialctl.connections.cli import acquire_brand_lock, interactive_terminal
+    from socialctl.connections.account_cli import metadata as account_metadata, connect_saas
+    try:
+        lock_fd = acquire_brand_lock(brand)
+    except ValueError as exc:
+        _fallar(str(exc))
+    try:
+        if account_metadata(brand):
+            if independent:
+                _fallar('This workspace uses SocialCli SaaS. Use socialcli connect; developer credentials are not required.')
+            if platform is Platform.TIKTOK and (management or analytics):
+                _fallar('TikTok does not accept --management or --analytics in this connection flow.')
+            connect_saas(brand, platform, no_browser=no_browser or not interactive_terminal(),
+                         management=management, analytics=analytics, timeout=timeout,
+                         replace_independent=replace_independent)
+            return
+        if brand.leer_secreto(platform).get("auth_mode") == "broker":
+            if not independent:
+                _fallar('Existing shared credentials were preserved. Use socialcli account login --brand NAME --no-browser, '
+                        'then socialcli account migrate ' + platform.value + ' --brand NAME for an eligible legacy connection, '
+                        'or account attach for an existing SaaS connection. Do not repeat OAuth or replace credentials silently.')
+            _fallar("a shared connection already exists; run socialcli disconnect for this platform before independent-app auth")
+
+        if not independent:
+            _fallar('Sign in first with socialcli account login --brand NAME --no-browser, then run socialcli connect '
+                    + platform.value + ' --brand NAME --no-browser. SocialCli users do not need developer app credentials. '
+                    'Legacy developer-owned app setup requires explicit --independent.')
+        if not interactive_terminal():
+            _fallar('Independent app setup requires an interactive terminal. For SocialCli SaaS, use account login followed by connect --no-browser.')
+        if no_browser or analytics or replace_independent:
+            _fallar('--no-browser, --analytics and --replace-independent belong to the SaaS connection flow.')
+
+        if management and platform is not Platform.YOUTUBE:
+            _fallar("--management is only available for YouTube")
+
+        if platform in (Platform.FACEBOOK, Platform.INSTAGRAM):
+            _auth_meta(brand, platform)
+        else:
+            _auth_oauth_redireccion(
+                brand, platform, youtube_management=management
+            )
+    except typer.Exit:
+        raise
+    except (KeyboardInterrupt, typer.Abort):
+        _fallar('Connection cancelled.')
+    except ValueError as exc:
+        _fallar(str(exc))
+    except Exception:
+        _fallar('Could not connect safely; existing credentials were preserved.')
+    finally:
+        import os
+        os.close(lock_fd)
+
+
+@app.command()
+def publish(
+    slug: str,
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to publish."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show the preview without publishing."),
+    yes: bool = typer.Option(False, "--yes", help="Skip the confirmation prompt."),
+    only: list[str] = typer.Option(None, "--only", help="Publish only on these platforms."),
+    source_link: bool = typer.Option(False, "--source-link", help="Require this exact post in source-videos.yml before previewing."),
+    approval_fingerprint: str | None = typer.Option(None, "--approval-fingerprint", "--approval", "--approval-digest", help="Exact digest of the approved complete preview."),
+    approval_stdin: bool = typer.Option(False, "--approval-stdin", help="Explicitly read one approved digest line from stdin."),
+    json_output: bool = typer.Option(False, "--json", help="One JSON result; complete preview and approval UI on stderr."),
+) -> None:
+    """Validate every platform, display the complete preview, then publish approved content."""
+    with PublishOutput(json_output, command="publish", brand=brand_nombre, slug=slug) as report:
+        brand = _cargar_marca(root, brand_nombre)
+        post = _cargar_post_con_avisos(brand, slug, source_link=source_link)
+
+        destinos: list[Platform] | None = None
+        if only:
+            try:
+                destinos = [Platform(r) for r in only]
+            except ValueError:
+                validas = ", ".join(p.value for p in Platform)
+                _fallar(f"--only contains an unknown platform. Valid platforms: {validas}")
+
+        _publicar_impl(post, brand, dry_run=dry_run, yes=yes, only=destinos, report=report, approval_fingerprint=approval_fingerprint, approval_stdin=approval_stdin)
+
+
+@app.command("schedule")
+def schedule(
+    slug: str,
+    at: str = typer.Option(..., "--at", help="ISO 8601 timestamp with timezone."),
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to schedule."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show the preview without saving the queue."),
+    yes: bool = typer.Option(False, "--yes", help="Approve the queue without another prompt."),
+    only: list[str] = typer.Option(None, "--only", help="Schedule only these platforms."),
+    approval_digest: str | None = typer.Option(None, "--approval-fingerprint", "--approval", "--approval-digest", help="Digest of the previously approved preview."),
+    approval_stdin: bool = typer.Option(False, "--approval-stdin", help="Explicitly read one approved digest line from stdin."),
+    preview_json: bool = typer.Option(False, "--preview-json", hidden=True),
+) -> None:
+    """Validate and add a Facebook/Instagram post to the local queue."""
+    if preview_json and (not dry_run or yes or approval_digest or approval_stdin):
+        _fallar("--preview-json requires --dry-run and does not support approval")
+    brand = _cargar_marca(root, brand_nombre)
+    if is_remote(brand.raiz):
+        _fallar(REMOTE_NOTICE)
+    preview_warnings: list[str] = []
+    post = _cargar_post_con_avisos(brand, slug, avisos=preview_warnings if preview_json else None)
+    try:
+        scheduled_at = parse_scheduled_at(at)
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    if only:
+        try:
+            destinos = [Platform(item) for item in only]
+        except ValueError:
+            _fallar("--only allows youtube, facebook, instagram or tiktok")
+    else:
+        destinos = list(post.platforms)
+    destinos = [p for p in destinos if p in (Platform.FACEBOOK, Platform.INSTAGRAM)]
+    if not destinos:
+        _fallar("schedule only supports Facebook and Instagram, and the post contains neither")
+    if any(p not in post.platforms for p in destinos):
+        _fallar("the post does not contain all requested platforms")
+    try:
+        displayed_hashes = {p.value: approval_hash(post, brand, p) for p in destinos}
+        displayed_digest = schedule_digest(post.slug, displayed_hashes, scheduled_at)
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    errores = validar_todo(post, brand)
+    preview = render_preview(post, errores, brand=brand, destinos=destinos, motivo_exclusion="not requested for this schedule")
+    bloqueantes = [p for p in destinos if errores.get(p)]
+    if preview_json:
+        from socialctl.schedule_remote import SchedulePreview
+        try:
+            response = SchedulePreview(protocol="socialctl.schedule-preview.v1",
+                                       valid=not bloqueantes, preview="\n".join([*preview_warnings, preview]),
+                                       digest=displayed_digest, scheduled_at=scheduled_at.isoformat())
+        except ValueError:
+            _fallar("unsafe preview; review the content locally before continuing")
+        typer.echo(response.model_dump_json())
+        raise typer.Exit(1 if bloqueantes else 0)
+    typer.echo(preview)
+    typer.echo(f"Approval digest: {displayed_digest}")
+    if bloqueantes:
+        typer.echo("\nNothing will be scheduled: fix the problems above.")
+        raise typer.Exit(1)
+    if dry_run:
+        typer.echo(f"\n--dry-run: would schedule for {scheduled_at.isoformat()}.")
+        raise typer.Exit(0)
+    if approval_digest is not None or approval_stdin:
+        try:
+            approval_digest = read_approval(approval_digest, approval_stdin=approval_stdin)
+        except ValueError as exc:
+            _fallar(str(exc))
+    if approval_digest is not None and not hmac.compare_digest(approval_digest, displayed_digest):
+        _fallar("digest does not match the approved preview; run --dry-run and approve the current content")
+    if not yes and approval_digest is None and not _confirmar(f"\nSave {len(destinos)} schedule(s) to the local queue?"):
+        typer.echo("Canceled. No schedule was saved.")
+        raise typer.Exit(0)
+    # Re-read disk/account changes as well as media bytes after confirmation.
+    current_brand = _cargar_marca(root, brand_nombre)
+    current_post = _cargar_post_con_avisos(current_brand, slug)
+    try:
+        if ({p.value: approval_hash(current_post, current_brand, p) for p in destinos} != displayed_hashes
+                or {p.value: approval_hash(post, brand, p) for p in destinos} != displayed_hashes):
+            _fallar("content changed after the preview; run --dry-run again")
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    store = ScheduleStore(brand.raiz)
+    now = now_utc()
+    nuevas = []
+    for platform in destinos:
+        entry = ScheduleEntry(
+            id=f"{post.slug}/{platform.value}", brand=brand.nombre, slug=post.slug,
+            platform=platform.value, scheduled_at=scheduled_at, status="approved",
+            created_at=now, updated_at=now,
+            content_hash=displayed_hashes[platform.value],
+        )
+        nuevas.append(entry)
+    try:
+        store.add_many(nuevas)
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    for entry in nuevas:
+        typer.echo(f"Scheduled: {entry.id} → {scheduled_at.isoformat()}")
+    typer.echo(f"Queue updated: {len(destinos)} entry/entries.")
+
+
+@app.command("schedule-status")
+def schedule_status(
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose queue to inspect."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Display the brand's scheduling queue."""
+    brand = _cargar_marca(root, brand_nombre)
+    if is_remote(brand.raiz):
+        typer.echo(REMOTE_NOTICE)
+        return
+    entries = ScheduleStore(brand.raiz).load()
+    if not entries:
+        typer.echo("The queue is empty.")
+        return
+    for entry in entries:
+        error = " — error recorded (details omitted)" if entry.last_error else ""
+        typer.echo(f"{entry.id} | {entry.scheduled_at.isoformat()} | {entry.status} | attempts={entry.attempts}{error}")
+
+
+@app.command("schedule-batch")
+def schedule_batch(
+    fichero: Path,
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to schedule."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    dry_run: bool = typer.Option(False, "--dry-run", help="Show previews without saving the queue."),
+    yes: bool = typer.Option(False, "--yes", help="Skip the prompt after showing previews."),
+) -> None:
+    """Schedule multiple posts atomically from a YAML batch."""
+    brand = _cargar_marca(root, brand_nombre)
+    if is_remote(brand.raiz):
+        _fallar(REMOTE_NOTICE)
+    try:
+        datos = yaml.safe_load(fichero.read_text(encoding="utf-8"))
+    except (OSError, yaml.YAMLError) as exc:
+        _fallar(f"could not read the batch {fichero}: {exc}")
+    if not isinstance(datos, list) or not datos:
+        _fallar("batch must be a nonempty YAML list")
+    nuevas: list[ScheduleEntry] = []
+    previews: list[
+        tuple[int, Post, list[Platform], datetime, dict[Platform, list]]
+    ] = []
+    aprobaciones: list[tuple[Post, Platform, str]] = []
+    problemas: list[str] = []
+    now = now_utc()
+    for index, item in enumerate(datos, start=1):
+        if not isinstance(item, dict) or not isinstance(item.get("slug"), str) or not isinstance(item.get("at"), str):
+            _fallar(f"entry {index} in the batch requires 'slug' and 'at'")
+        try:
+            at = parse_scheduled_at(item["at"])
+            post = _cargar_post_con_avisos(brand, item["slug"])
+        except ScheduleError as exc:
+            _fallar(f"entry {index}: {exc}")
+        only = item.get("only", ["facebook", "instagram"])
+        if not isinstance(only, list):
+            _fallar(f"entry {index}: 'only' must be a list")
+        try:
+            plataformas = [Platform(value) for value in only]
+        except ValueError:
+            _fallar(f"entry {index}: unknown platform in 'only'")
+        plataformas = [p for p in plataformas if p in (Platform.FACEBOOK, Platform.INSTAGRAM) and p in post.platforms]
+        errores = validar_todo(post, brand)
+        if any(errores.get(p) for p in plataformas):
+            problemas.append(
+                f"entry {index} ({post.slug}): validation problems found"
+            )
+        previews.append((index, post, plataformas, at, errores))
+        for platform in plataformas:
+            try:
+                content_hash = approval_hash(post, brand, platform)
+            except ScheduleError as exc:
+                _fallar(f"entry {index} ({post.slug}/{platform.value}): {exc}")
+            nuevas.append(ScheduleEntry(
+                id=f"{post.slug}/{platform.value}", brand=brand.nombre,
+                slug=post.slug, platform=platform.value, scheduled_at=at,
+                status="approved", created_at=now, updated_at=now,
+                content_hash=content_hash,
+            ))
+            aprobaciones.append((post, platform, content_hash))
+    for index, post, plataformas, at, errores in previews:
+        typer.echo(
+            f"\n=== Entry {index}: {post.slug} → {at.isoformat()} ==="
+        )
+        typer.echo(
+            render_preview(
+                post,
+                errores,
+                brand=brand,
+                destinos=plataformas,
+                motivo_exclusion='not included in this batch entry',
+            )
+        )
+    typer.echo(f"Valid entries: {len(nuevas)}")
+    for entry in sorted(nuevas, key=lambda value: value.scheduled_at):
+        typer.echo(f"  {entry.id} → {entry.scheduled_at.isoformat()}")
+    if problemas:
+        typer.echo("\nNothing will be scheduled: fix the problems above.")
+        _fallar("; ".join(problemas))
+    if dry_run:
+        typer.echo("--dry-run: the queue was not saved.")
+        raise typer.Exit(0)
+    if not yes and not _confirmar("Save this batch to the local queue?"):
+        typer.echo("Canceled. No schedule was saved.")
+        raise typer.Exit(0)
+    # Las huellas se toman antes de renderizar. Se vuelven a calcular tras la
+    # aprobación para que ni ``--yes`` ni una mutación concurrente de la media
+    # puedan convertir en aprobada una carga distinta de la que se mostró.
+    for post, platform, displayed_hash in aprobaciones:
+        try:
+            current_hash = approval_hash(post, brand, platform)
+        except ScheduleError as exc:
+            _fallar(
+                f"{post.slug}/{platform.value}: could not reverify "
+                f"approval after the preview: {exc}"
+            )
+        if not hmac.compare_digest(current_hash, displayed_hash):
+            _fallar(
+                f"{post.slug}/{platform.value}: content, media or account "
+                "changed after the preview; run --dry-run again and approve "
+                "the new content"
+            )
+    try:
+        ScheduleStore(brand.raiz).add_many(nuevas)
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    typer.echo(f"Queue updated: {len(nuevas)} entry/entries.")
+
+
+@app.command("schedule-cancel")
+def schedule_cancel(
+    entry_id: str,
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose schedule to cancel."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Cancel a schedule that has not run."""
+    brand = _cargar_marca(root, brand_nombre)
+    store = ScheduleStore(brand.raiz)
+    try:
+        store.cancel(entry_id, now_utc())
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    typer.echo(f"Canceled: {entry_id}")
+
+
+@app.command("schedule-reschedule")
+def schedule_reschedule(
+    entry_id: str,
+    at: str = typer.Option(..., "--at", help="New ISO 8601 timestamp with timezone."),
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose schedule to change."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Change the time of a pending schedule."""
+    brand = _cargar_marca(root, brand_nombre)
+    try:
+        scheduled_at = parse_scheduled_at(at)
+        store = ScheduleStore(brand.raiz)
+        store.reschedule(entry_id, scheduled_at, now_utc())
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    typer.echo(f"Rescheduled: {entry_id} → {scheduled_at.isoformat()}")
+
+
+@app.command("run-due")
+def run_due(
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose queue to run."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Run approved publications whose scheduled time has arrived, once."""
+    brand = _cargar_marca(root, brand_nombre)
+    store = ScheduleStore(brand.raiz)
+    from socialctl.executor import heartbeat
+    try:
+        with store.executor_lock():
+            heartbeat(store, "started", now_utc())
+            try:
+                _run_due_locked(brand, store)
+            except BaseException:
+                try:
+                    heartbeat(store, "error", now_utc())
+                except ScheduleError:
+                    pass  # Preserve original failure; previous started heartbeat becomes stale.
+                raise
+            heartbeat(store, "finished", now_utc())
+    except ScheduleError as exc:
+        _fallar(str(exc))
+
+
+def _run_due_locked(brand: Brand, store: ScheduleStore) -> None:
+    """Process the queue while holding its executor lock."""
+    store.assert_ready()
+    recuperadas = store.recover_stale()
+    if recuperadas:
+        typer.echo(
+            f"Isolated {recuperadas} interrupted execution(s) for manual review."
+        )
+    from socialctl.executor import admitted_groups
+    due = (entry for group in admitted_groups(store, now_utc(), clock=now_utc) for entry in group)
+    for candidate in due:
+        entry = store.claim_due(candidate.id, now_utc(), expected=candidate)
+        if entry is None:
+            continue
+        try:
+            platform = Platform(entry.platform)
+            post = _cargar_post_con_avisos(brand, entry.slug)
+            review_reason = approval_review_reason(
+                entry.content_hash, post, brand, platform
+            )
+            if review_reason is not None:
+                store.transition(
+                    entry.id,
+                    {"running"},
+                    status="manual_review",
+                    moment=now_utc(),
+                    last_error=review_reason,
+                )
+                typer.echo(f"{entry.id}: manual_review — {review_reason}")
+                continue
+            pp = post.platforms[platform]
+            legacy_approved_platforms = frozenset()
+            if pp.content_origin is None and pp.source_video_id is None:
+                # The stored v2 hash above authorizes only this unchanged entry.
+                legacy_approved_platforms = frozenset({platform})
+                typer.echo(f"{entry.id}: legacy entry: source unverified")
+            errores = validar_todo(
+                post, brand, legacy_approved_platforms=legacy_approved_platforms
+            ).get(platform, [])
+            if errores:
+                error = "; ".join(e.motivo for e in errores)
+                store.transition(
+                    entry.id,
+                    {"running"},
+                    status="error",
+                    moment=now_utc(),
+                    last_error=error,
+                )
+                typer.echo(f"{entry.id}: validation error — {error}")
+                continue
+            if platform is Platform.INSTAGRAM:
+                from socialctl.hosted_media import verify_scheduled_instagram
+                verify_scheduled_instagram(post, brand, entry=entry)
+            typer.echo(f"Publishing {entry.id}...")
+            def persist_media(result):
+                store.transition(entry.id, {"running"}, status="running", moment=now_utc(),
+                                 platform_id=result.platform_id)
+                guardar_resultado(post, brand, [result])
+
+            from socialctl.scheduler import occurrence_id
+            occurrence = occurrence_id(brand.raiz, entry)
+            resultados = publicar(post, brand, solo=[platform], on_progreso=_mostrar_progreso,
+                on_media_result=persist_media, occurrence_ids={platform: occurrence},
+                approval_provenance=f"schedule:{entry.id}:{entry.content_hash}",
+                legacy_approved_platforms=legacy_approved_platforms)
+            resultado = resultados[0]
+            store.transition(
+                entry.id,
+                {"running"},
+                status="running",
+                moment=now_utc(),
+                platform_id=resultado.platform_id,
+            )
+            guardar_resultado(post, brand, resultados)
+            anexar_historial(post, brand, resultados)
+            status = "published" if resultado.status is PostStatus.PUBLICADO else ("manual_review" if resultado.riesgo_duplicado else "error")
+            store.transition(
+                entry.id,
+                {"running"},
+                status=status,
+                moment=now_utc(),
+                last_error=resultado.error,
+                platform_id=resultado.platform_id,
+            )
+            typer.echo(f"{entry.id}: {status}")
+            _mostrar_comentario(resultado)
+        except Exception as exc:
+            error = (
+                f"execution interrupted ({type(exc).__name__}): confirm the "
+                "remote result before retrying"
+            )
+            store.transition(
+                entry.id,
+                {"running"},
+                status="manual_review",
+                moment=now_utc(),
+                last_error=error,
+            )
+            typer.echo(f"{entry.id}: manual_review — {error}")
+
+
+@app.command("schedule-health")
+def schedule_health(
+    brand_nombre: str = typer.Option(..., "--brand"),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO),
+) -> None:
+    """Display durable executor health; stale means no heartbeat for more than three minutes."""
+    from socialctl.executor import health
+    brand = _cargar_marca(root, brand_nombre)
+    if is_remote(brand.raiz):
+        typer.echo(REMOTE_NOTICE)
+        return
+    try:
+        typer.echo(json.dumps(health(ScheduleStore(brand.raiz), now_utc()), ensure_ascii=False))
+    except ScheduleError as exc:
+        _fallar(str(exc))
+
+
+@app.command("schedule-install")
+def schedule_install(
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to install the agent for."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+) -> None:
+    """Install the local queue executor using macOS launchd or Linux systemd user timers."""
+    brand = _cargar_marca(root, brand_nombre)
+    try:
+        ScheduleStore(brand.raiz).assert_ready()
+    except ScheduleError as exc:
+        _fallar(str(exc))
+    if sys.platform.startswith('linux'):
+        from socialctl.scheduler_systemd import install, SupervisorError
+        try:
+            supervisor = install(brand.nombre,root)
+        except (SupervisorError,OSError) as exc:
+            _fallar(str(exc) if isinstance(exc,SupervisorError) else 'Could not save Linux scheduler units')
+        typer.echo(f"Linux user timer installed and active: {supervisor['unit']}.timer")
+        typer.echo('Original media stays on this customer-owned machine; keep it powered on and connected.')
+        if supervisor['survives_logout'] is not True:
+            typer.echo(f'Logout persistence is unverified. The operator can enable it with loginctl enable-linger {os.getuid()}; then run schedule-doctor.')
+        return
+    from socialctl.scheduler_launchd import install, SupervisorError
+    try:
+        supervisor = install(brand.nombre, root)
+    except (SupervisorError, OSError) as exc:
+        _fallar(str(exc) if isinstance(exc, SupervisorError) else 'Could not save macOS scheduler configuration.')
+    typer.echo(f"Agent installed and verified: {supervisor['unit']}")
+    typer.echo('launchd runs the queue every 60 seconds while this user is logged in; keep the Mac powered on, awake and connected.')
+
+
+@app.command('schedule-doctor')
+def schedule_doctor(
+    brand_nombre: str = typer.Option(..., '--brand'),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO),
+    json_output: bool = typer.Option(False, '--json'),
+):
+    """Check local executor evidence. A heartbeat cannot prove future availability."""
+    from socialctl.executor import health
+    brand = _cargar_marca(root, brand_nombre)
+    if is_remote(brand.raiz):
+        result = {'version': 1, 'status': 'attention_required', 'server_media_storage': False,
+                  'persistent_supervision': 'unverified', 'unattended_delivery_guaranteed': False,
+                  'error': {'code': 'remote_executor_unverified', 'action': 'user_action',
+                            'message': 'Inspect the configured customer-owned remote executor; this command does not transfer media.'}}
+    else:
+        try:
+            observation = health(ScheduleStore(brand.raiz), now_utc())
+        except ScheduleError:
+            observation = {'state': 'unreadable', 'stale': True}
+        if observation.get('state') == 'error':
+            diagnostic = {'code': 'executor_error', 'action': 'user_action',
+                          'message': 'The executor reported an error; inspect its log before relying on the queue.'}
+        elif observation['stale']:
+            diagnostic = {'code': 'executor_unverified', 'action': 'user_action',
+                          'message': 'No recent executor evidence.'}
+        else:
+            diagnostic = {'code': 'supervision_unverified', 'action': 'user_action',
+                          'message': 'A recent execution was observed; persistent supervision still needs verification.'}
+        result = {'version': 1, 'brand': brand.nombre, 'status': 'attention_required',
+                  'heartbeat': observation, 'persistent_supervision': 'unverified',
+                  'unattended_delivery_guaranteed': False, 'server_media_storage': False,
+                  'error': diagnostic,
+                  'instruction': 'Keep the original files, credentials and a supervised executor available on '
+                      'the customer-owned machine. Use schedule-install on macOS or Linux. '
+                      'Do not promise delivery from an ephemeral Muse/Grok session.'}
+        if sys.platform.startswith('linux'):
+            from socialctl.scheduler_systemd import inspect
+            supervisor = inspect(brand.nombre,root)
+            result['supervisor'] = supervisor
+            supervised = (supervisor['configuration_matches'] and supervisor['enabled'] and supervisor['active']
+                          and supervisor['survives_logout'] is True and supervisor['service_failed'] is False)
+            if supervised:
+                result['persistent_supervision'] = 'verified_now'
+                if not observation['stale'] and observation.get('state') != 'error':
+                    result['status'] = 'ready'
+                    result['error'] = None
+            elif observation.get('state') != 'error' and not observation['stale']:
+                if supervisor['service_failed']:
+                    code,message = 'supervisor_service_failed','The Linux service failed; inspect journalctl --user before relying on the queue.'
+                elif supervisor['active'] and supervisor['survives_logout'] is not True:
+                    code,message = 'logout_persistence_unverified','The timer is active, but persistence after logout requires operator-verified linger.'
+                else:
+                    code,message = 'supervision_unverified','An enabled active Linux user timer with matching configuration was not verified.'
+                result['error'] = {'code':code,'message':message,'action':'user_action'}
+        elif sys.platform == 'darwin':
+            from socialctl.scheduler_launchd import inspect
+            supervisor = inspect(brand.nombre, root)
+            result['supervisor'] = supervisor
+            supervised = all(supervisor[key] is True for key in
+                             ('configuration_matches', 'registered', 'enabled', 'active')) and supervisor['service_failed'] is False
+            if supervised:
+                result['persistent_supervision'] = 'verified_now'
+                if not observation['stale'] and observation.get('state') == 'finished':
+                    result['status'] = 'ready'
+                    result['error'] = None
+            elif observation.get('state') != 'error' and not observation['stale']:
+                failed = supervisor['service_failed'] is True
+                result['error'] = {
+                    'code': 'supervisor_service_failed' if failed else 'supervision_unverified',
+                    'message': ('The macOS scheduler last execution failed; inspect its logs and launchctl before relying on the queue.'
+                                if failed else 'A matching registered and enabled macOS scheduler with successful execution was not verified.'),
+                    'action': 'user_action'}
+
+    if json_output:
+        typer.echo(json.dumps(result, indent=2))
+    else:
+        typer.echo(result['error']['message'] if result['error'] else 'Executor and persistent supervision verified now; future delivery still depends on this machine.')
+        typer.echo(result.get('instruction', ''))
+    raise typer.Exit(0 if result['status'] == 'ready' else 1)
+
+
+@app.command("schedule-uninstall")
+def schedule_uninstall(
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose agent to remove."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace containing the brand's scheduler."),
+) -> None:
+    """Remove this workspace's local queue supervisor without deleting queue or media."""
+    if sys.platform.startswith('linux'):
+        from socialctl.scheduler_systemd import uninstall, SupervisorError
+        try:
+            removed = uninstall(brand_nombre,root)
+        except (SupervisorError,OSError) as exc:
+            _fallar(str(exc) if isinstance(exc,SupervisorError) else 'Could not remove Linux scheduler units')
+        typer.echo('Linux timer removed. An already running approved operation may finish; queue and media are preserved.' if removed else 'No Linux scheduler units found for this workspace and brand.')
+        return
+    from socialctl.scheduler_launchd import uninstall, SupervisorError
+    try:
+        removed = uninstall(brand_nombre, root)
+    except (SupervisorError, OSError) as exc:
+        _fallar(str(exc) if isinstance(exc, SupervisorError) else 'Could not remove macOS scheduler configuration.')
+    typer.echo('macOS scheduler removed; queue, media and credentials are preserved. Review any interrupted operation before retrying.'
+               if removed else 'No macOS scheduler found for this workspace and brand. Legacy and unrelated jobs were preserved.')
+
+
+@app.command()
+def retry(
+    slug: str,
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand to retry."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    yes: bool = typer.Option(False, "--yes", help="Skip the confirmation prompt."),
+    json_output: bool = typer.Option(False, "--json", help="One JSON result; complete preview and approval UI on stderr."),
+) -> None:
+    """Retry failed platforms only after validation and preview, excluding outcomes that may duplicate publications."""
+    with PublishOutput(json_output, command="retry", brand=brand_nombre, slug=slug) as report:
+        _retry_impl(slug, brand_nombre, root, yes, report=report)
+
+
+def _retry_impl(slug, brand_nombre, root, yes, *, report=None):
+    brand = _cargar_marca(root, brand_nombre)
+    post = _cargar_post_con_avisos(brand, slug)
+
+    from socialctl.publication_steps import retry_media_blockers, CommentError
+    try:
+        protected = retry_media_blockers(brand, post.slug, post.platforms)
+    except CommentError as exc:
+        _fallar(str(exc))
+    if report is not None:
+        report.retry["blocked"] = sorted(p.value for p in protected)
+        for platform in protected:
+            report.add_error("operation_uncertain", platform=platform.value)
+    for platform, reasons in protected.items():
+        for reason in reasons:
+            typer.echo(f"{platform.value}: {reason}. See comments publication-status / retry-first.")
+
+    fichero = brand.dir_posts / post.slug / "resultado.json"
+    if not fichero.exists():
+        if protected:
+            _fallar("resultado.json is missing; the durable journal requires reconciliation, not another upload.")
+        _fallar(f'no previous attempt in {fichero}; nothing to retry.')
+
+    try:
+        contenido = json.loads(fichero.read_text(encoding="utf-8"))
+        if not isinstance(contenido, dict):
+            raise ValueError("JSON root is not an object")
+        entradas = contenido["resultados"]
+        if not isinstance(entradas, list):
+            raise ValueError("'resultados' is not a list")
+        previos: dict[str, dict] = {}
+        for entrada in entradas:
+            if not isinstance(entrada, dict) or not isinstance(entrada.get("platform"), str):
+                raise ValueError("a 'resultados' entry does not have the expected structure")
+            previos[entrada["platform"]] = entrada
+    except (json.JSONDecodeError, KeyError, ValueError, TypeError) as exc:
+        _fallar(f"could not parse {fichero}: {exc}")
+
+    fallidas = {
+        plataforma for plataforma, entrada in previos.items()
+        if entrada.get("status") == PostStatus.ERROR.value
+    }
+    if not fallidas:
+        typer.echo("There are no failed platforms to retry.")
+        raise typer.Exit(1 if protected else 0)
+
+    actuales = {p.value for p in post.platforms}
+    faltantes = sorted(fallidas - actuales)
+    vigentes = sorted(fallidas & actuales)
+
+    if faltantes:
+        typer.echo(
+            f"Warning: post.yml no longer includes {', '.join(faltantes)} "
+            "(they failed in the previous attempt); they will not be retried."
+        )
+
+    if not vigentes:
+        typer.echo("No failed platform remaining in this post can be retried.")
+        raise typer.Exit(0)
+
+    # Estrictamente `is True`, no `bool(...)`: un valor no booleano colado en
+    # el JSON (p. ej. la cadena "false", que `bool("false")` evaluaría como
+    # verdadera) nunca debe convertir una red en "arriesgada" por accidente.
+    # Una entrada sin este campo -de un resultado.json anterior a que
+    # existiera- también cae aquí, y por tanto no se considera arriesgada
+    # (ver docstring de esta función para la justificación).
+    arriesgadas = sorted(
+        p for p in vigentes if previos[p].get("riesgo_duplicado") is True
+    )
+    seguras = [p for p in vigentes if p not in arriesgadas and Platform(p) not in protected]
+
+    if report is not None:
+        report.retry["blocked"] = sorted(set(report.retry["blocked"]) | set(arriesgadas))
+        report.retry["selected"] = seguras
+        for platform in arriesgadas:
+            if Platform(platform) not in protected:
+                report.add_error("operation_uncertain", platform=platform)
+
+    if arriesgadas:
+        typer.echo(
+            "\nWARNING: these platforms will not be retried automatically because of "
+            "duplicate publication risk (the previous attempt warned "
+            "that the content may have been published):"
+        )
+        for p in arriesgadas:
+            typer.echo(f"  - {p}: {safe_error(previos[p].get('error') or '')}")
+        typer.echo(
+            "Check the account manually before publishing on these platforms again "
+            "(for example: socialcli publish ... --only <platform> --yes)."
+        )
+
+    if not seguras:
+        raise typer.Exit(1)
+
+    typer.echo(f"\nRetrying: {', '.join(seguras)}")
+
+    codigo_publish = 0
+    try:
+        _publicar_impl(
+            post, brand, dry_run=False, yes=yes,
+            only=[Platform(p) for p in seguras],
+            motivo_exclusion="not retried in this attempt",
+            retry_guard=True,
+            report=report,
+        )
+    except typer.Exit as exc:
+        codigo_publish = exc.exit_code or 0
+
+    if arriesgadas or protected or codigo_publish:
+        raise typer.Exit(1)
+
+
+#: Días seguidos en fallo tras los que `stats` avisa por pantalla. Tres, como
+#: pide el spec (§5): uno puede ser un corte de red, dos una coincidencia;
+#: tres seguidos es un token caducado que lleva días comiéndose el histórico.
+DIAS_DE_FALLO_PARA_AVISAR = 3
+
+
+def _redes_en_fallo(snapshot: Snapshot) -> set[Platform]:
+    """Return platforms with error or missing-credential read states."""
+    return {
+        platform
+        for platform, lectura in snapshot.redes.items()
+        if lectura.estado
+        in (EstadoLectura.ERROR, EstadoLectura.SIN_CREDENCIALES)
+    }
+
+
+def _avisar_de_fallos_persistentes(marca: Brand, snapshot: Snapshot) -> None:
+    """Warn when a platform fails in three consecutive snapshots."""
+    anterior = snapshot_anterior(marca, antes_de=snapshot.fecha)
+    if anterior is None:
+        return
+    trasanterior = snapshot_anterior(marca, antes_de=anterior.fecha)
+    if trasanterior is None:
+        return
+
+    persistentes = (
+        _redes_en_fallo(snapshot)
+        & _redes_en_fallo(anterior)
+        & _redes_en_fallo(trasanterior)
+    )
+    for platform in sorted(persistentes, key=lambda p: p.value):
+        typer.echo(
+            f"WARNING: {platform.value} has gone {DIAS_DE_FALLO_PARA_AVISAR} days "
+            f"without a successful read (also on {anterior.fecha.isoformat()} and "
+            f"on {trasanterior.fecha.isoformat()}). This usually means an "
+            f"expired token: run socialcli auth {platform.value} "
+            f"--brand {marca.nombre}"
+        )
+
+
+def _limpiar_snapshots_y_avisar(marca: Brand) -> None:
+    """Apply one-year snapshot retention and report deletions or failures."""
+    borrados, fallidos = limpiar_snapshots_antiguos(marca)
+    if borrados:
+        nombres = ", ".join(ruta.name for ruta in borrados)
+        typer.echo(
+            f"Cleanup: deleted {len(borrados)} snapshot(s) older than "
+            f"{RETENCION_SNAPSHOTS_DIAS} days ({nombres})."
+        )
+    for ruta, exc in fallidos:
+        typer.echo(
+            f"WARNING: could not delete the old snapshot {ruta} ({exc}). "
+            "It remains on disk; delete it manually to free the space."
+        )
+
+
+def _fusionar_snapshot_del_dia(marca: Brand, nuevo: Snapshot) -> Snapshot:
+    """Merge selected-platform reads with today's snapshot, retaining other platforms and previous good data when a read fails."""
+    anterior = cargar_snapshot(marca, nuevo.fecha)
+    if anterior is None:
+        return nuevo
+
+    fusionadas = dict(anterior.redes)
+    for platform, lectura in nuevo.redes.items():
+        previa = anterior.redes.get(platform)
+        if (
+            lectura.estado is not EstadoLectura.OK
+            and previa is not None
+            and previa.estado is EstadoLectura.OK
+        ):
+            fusionadas[platform] = previa.model_copy(
+                update={"estado": lectura.estado, "error": lectura.error}
+            )
+        else:
+            fusionadas[platform] = lectura
+
+    return Snapshot(fecha=nuevo.fecha, marca=nuevo.marca, redes=fusionadas)
+
+
+class MetricsPersistenceError(Exception):
+    def __init__(self, saved, not_saved, message, snapshot_path):
+        super().__init__(message)
+        self.saved, self.not_saved, self.snapshot_path = list(saved), list(not_saved), snapshot_path
+
+
+def _guardar_lo_leido(marca: Brand, snapshot: Snapshot, *, structured: bool = False) -> Path:
+    """Write the day's snapshot, editorial inventory and report atomically, reporting any incomplete set of writes."""
+    pasos = (
+        ("today's snapshot", lambda: guardar_snapshot(marca, snapshot)),
+        ("piezas.yml", lambda: actualizar_piezas(marca, snapshot)),
+        ("resumen.md", lambda: escribir_resumen(marca, snapshot)),
+    )
+
+    escritos: list[str] = []
+    pendientes = [nombre for nombre, _ in pasos]
+    ruta_del_snapshot: Path | None = None
+
+    for nombre, escribir in pasos:
+        try:
+            ruta = escribir()
+        except PiezasIlegibles as exc:
+            if structured:
+                raise MetricsPersistenceError(escritos, pendientes, str(exc), ruta_del_snapshot) from None
+            _fallar_guardando(
+                escritos, pendientes,
+                f"could not update piezas.yml: {exc}",
+                "That file was preserved: its editorial content "
+                "cannot be retrieved again from an API.",
+            )
+        except OSError as exc:
+            if structured:
+                raise MetricsPersistenceError(escritos, pendientes, str(exc), ruta_del_snapshot) from None
+            _fallar_guardando(
+                escritos, pendientes,
+                f"could not write {nombre}: {exc}",
+                "Files are written "
+                "atomically, so unsaved files retain their "
+                "complete previous content.",
+            )
+        escritos.append(f"{nombre} ({ruta})")
+        pendientes.remove(nombre)
+        if ruta_del_snapshot is None:
+            ruta_del_snapshot = ruta
+
+    assert ruta_del_snapshot is not None  # el primer paso siempre lo fija
+    return ruta_del_snapshot
+
+
+def _fallar_guardando(
+    escritos: list[str], pendientes: list[str], motivo: str, coletilla: str
+) -> None:
+    """Exit stats with a clear account of saved and unsaved files."""
+    lineas = [f"ERROR: {motivo}"]
+    lineas.append(
+        "Saved: " + "; ".join(escritos) + "."
+        if escritos
+        else "None of this run's files were saved."
+    )
+    if pendientes:
+        lineas.append("Not saved: " + ", ".join(pendientes) + ".")
+    if coletilla:
+        lineas.append(coletilla)
+    _fallar("\n".join(lineas))
+
+
+def _metric_read_label(state: str) -> str:
+    """Render English metric-read labels while preserving stored state codes."""
+    return {"sin_credenciales": "missing_credentials", "sin_permiso": "missing_permission",
+            "no_disponible": "unavailable"}.get(state, state)
+
+
+@app.command()
+def stats(
+    brand_nombre: str = typer.Option(..., "--brand", help="Brand whose metrics to read."),
+    root: Path = typer.Option(RAIZ_POR_DEFECTO, help="Workspace directory containing brands."),
+    only: list[str] = typer.Option(None, "--only", help="Read only these platforms."),
+    desde: str = typer.Option(
+        None, "--since", "--desde", help="Only content published since this date (YYYY-MM-DD)."
+    ),
+    json_output: bool = typer.Option(False, "--json", help="Print a versioned report; progress goes to stderr."),
+    timeout: float = typer.Option(300, "--timeout", help="Total read time limit in seconds; use --only to give one platform the full budget."),
+) -> None:
+    """Read platform metrics and save a brand snapshot. Selected-platform reads merge with today's data; YouTube API data expires after six days; other snapshots expire after one year."""
+    def invalid(message):
+        if json_output:
+            from socialctl.read_reports import ReadReport, emit_report, safe_error
+            emit_report(ReadReport(status='error', errors=[{'code':'invalid_input','message':safe_error(message)}]))
+            raise typer.Exit(2)
+        _fallar(message)
+    try:
+        marca = cargar_brand(root, brand_nombre)
+    except _EXCEPCIONES_MARCA as exc:
+        invalid(str(exc))
+
+    fecha_desde = None
+    if desde is not None:
+        try:
+            fecha_desde = date.fromisoformat(desde)
+        except ValueError:
+            invalid(f"'--since {desde}' is not a valid YYYY-MM-DD date.")
+
+    # Mismo patrón que `publish` (`socialctl/cli.py:638-643`): la opción se
+    # declara como texto y se convierte aquí, para que una red desconocida dé
+    # un mensaje en español en vez del error de click, que sale en inglés.
+    destinos: list[Platform]
+    if only:
+        try:
+            destinos = [Platform(r) for r in only]
+        except ValueError:
+            validas = ", ".join(p.value for p in Platform)
+            invalid(f"--only contains an unknown platform. Valid platforms: {validas}")
+    else:
+        destinos = list(LECTORES)
+
+    from socialctl.read_budget import ReadBudget, ReadDeadlineExceeded, read_client
+    from socialctl.metricas.modelos import LecturaRed
+    try:
+        budget = ReadBudget(timeout)
+    except ValueError as exc:
+        invalid(str(exc))
+    redes = {}
+    from socialctl.read_budget import ReadProgress
+    progress = ReadProgress('stats')
+    interrupted = False
+    try:
+        transport = read_client(budget, progress=progress)
+    except Exception as exc:
+        from socialctl.read_reports import fail_read
+        fail_read(exc,json_output=json_output)
+    with progress, transport as client:
+        for index, platform in enumerate(destinos):
+            if interrupted:
+                redes[platform] = LecturaRed(estado=EstadoLectura.ERROR, error='Read interrupted; platform not started', failure_code='not_attempted')
+                continue
+            try:
+                with budget.share(len(destinos) - index):
+                    budget.check()
+                    if sys.stderr.isatty():
+                        typer.echo(f"Reading {platform.value}...", err=True)
+                    redes[platform] = leer_red(platform, marca, client, fecha_desde)
+                    redes[platform].observed_at = datetime.now(timezone.utc)
+            except KeyboardInterrupt:
+                interrupted = True
+                redes[platform] = LecturaRed(estado=EstadoLectura.ERROR, error='Read interrupted; results may be incomplete', failure_code='read_interrupted')
+            except ReadDeadlineExceeded as exc:
+                redes[platform] = LecturaRed(estado=EstadoLectura.ERROR, error=str(exc), failure_code='read_deadline')
+
+    from socialctl.read_reports import safe_error
+    for lectura in redes.values():
+        lectura.warnings = [safe_error(warning) for warning in lectura.warnings]
+        if lectura.error:
+            lectura.error = safe_error(lectura.error)
+        for piece in lectura.piezas:
+            if 'enriquecimiento_fallido' in piece.especificas:
+                piece.especificas['enriquecimiento_fallido'] = safe_error(str(piece.especificas['enriquecimiento_fallido']))
+    snapshot = Snapshot(fecha=date.today(), marca=marca.nombre, redes=redes)
+
+    # Con `--only`, fusiona con el snapshot que ya hubiera hoy en vez de
+    # reemplazarlo (ver `_fusionar_snapshot_del_dia`); sin `--only` no se
+    # toca nada aquí y la lectura completa sigue sobrescribiendo como
+    # siempre. `redes` (usado más abajo para el resumen por pantalla y el
+    # código de salida) sigue siendo la lectura de HOY, sin fusionar: lo que
+    # se cuenta ahí es lo que ha pasado en ESTA ejecución.
+    reused = set()
+    if only:
+        previous = cargar_snapshot(marca, snapshot.fecha)
+        if previous:
+            reused = {p for p, r in previous.redes.items() if p not in redes or
+                      (r.estado is EstadoLectura.OK and redes[p].estado is not EstadoLectura.OK)}
+        snapshot = _fusionar_snapshot_del_dia(marca, snapshot)
+
+    # ANTES de guardar y de actualizar `piezas.yml`: el slug enlaza cada
+    # pieza con el post que la publicó, y tiene que llegar a los dos ficheros.
+    asignar_slugs(marca, snapshot)
+
+    persistence_error = None
+    try:
+        ruta = _guardar_lo_leido(marca, snapshot, structured=json_output)
+    except MetricsPersistenceError as exc:
+        persistence_error = exc
+        ruta = exc.snapshot_path
+
+    if json_output:
+        from contextlib import redirect_stdout
+        from socialctl.read_reports import ReadReport, emit_report, safe_error
+        with redirect_stdout(sys.stderr):
+            _limpiar_snapshots_y_avisar(marca)
+            _avisar_de_fallos_persistentes(marca, snapshot)
+        coverage, errors = [], []
+        for p, r in redes.items():
+            warnings = r.warnings + [piece.especificas['enriquecimiento_fallido'] for piece in r.piezas
+                        if 'enriquecimiento_fallido' in piece.especificas]
+            complete = r.estado is EstadoLectura.OK and not warnings
+            observed = snapshot.redes[p].observed_at
+            coverage.append({'platform':p.value, 'complete':complete, 'state':r.estado.value,
+                             'fresh':p not in reused and r.estado is EstadoLectura.OK,
+                             'observed_at':observed.isoformat() if observed else None,
+                             'source':'previous_snapshot' if p in reused else 'current_read'})
+            if not complete:
+                errors.append({'platform':p.value, 'code':r.failure_code or {EstadoLectura.SIN_CREDENCIALES:'authorization_unavailable', EstadoLectura.SIN_PERMISO:'permissions_required'}.get(r.estado,'read_partial'), 'message':safe_error(r.error or '; '.join(warnings) or r.estado.value)})
+        if persistence_error:
+            errors.append({'operation':'persistence', 'code':'persistence_failed', 'message':safe_error(str(persistence_error))})
+        successes = sum(r.estado is EstadoLectura.OK for r in redes.values())
+        status = 'ok' if not errors else ('partial' if successes else 'error')
+        data = {'brand':marca.nombre, 'snapshot_path':str(ruta) if ruta else None,
+                'snapshot':snapshot.model_dump(mode='json'),
+                'merged_existing_platforms':sorted(p.value for p in reused)}
+        if persistence_error:
+            data['persistence'] = {'saved':persistence_error.saved, 'not_saved':persistence_error.not_saved}
+        report = ReadReport(status=status, coverage=coverage, errors=errors, data=data)
+        raise typer.Exit(emit_report(report))
+
+    typer.echo("")
+    for platform, lectura in redes.items():
+        if lectura.estado is EstadoLectura.OK:
+            typer.echo(f"{platform.value}: ok, {len(lectura.piezas)} content items")
+            for warning in lectura.warnings:
+                typer.echo(f"{platform.value}: partial — {warning}")
+        else:
+            typer.echo(f"{platform.value}: {_metric_read_label(lectura.estado.value)} — {lectura.error}")
+
+    typer.echo(f"\nSnapshot: {ruta}")
+
+    # Retención (spec §3): corre con cada `stats`, después de guardar el
+    # snapshot de hoy -nunca antes-, para que un fallo al borrar un fichero
+    # viejo no se lleve por delante una lectura que ya ha costado cuota de
+    # API en las cuatro redes.
+    _limpiar_snapshots_y_avisar(marca)
+
+    # El tercer punto de la cadencia del spec (§5). Va después del resumen por
+    # red para que lo último que se lea sea lo que hay que hacer.
+    _avisar_de_fallos_persistentes(marca, snapshot)
+
+    if all(l.estado is not EstadoLectura.OK for l in redes.values()):
+        raise typer.Exit(1)
+    if persistence_error or any(l.estado is not EstadoLectura.OK or l.warnings or
+            any('enriquecimiento_fallido' in piece.especificas for piece in l.piezas)
+            for l in redes.values()):
+        raise typer.Exit(3)
+
+
+if __name__ == "__main__":
+    app()