recala-cli 0.6.0__py3-none-any.whl

recala_cli/commands/org.py

@@ -0,0 +1,352 @@
+"""`recala company` (also `recala org`): create or choose the company, and read its website.
+
+A brand-new account already holds one empty company (the sign-up made it); its
+first setup fills that one in rather than creating a second. The market (the
+country the company sells in) travels with the website scan, where the portal's
+wizard sends it too.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli import config
+from recala_cli.client import RecalaClient
+from recala_cli.endpoints import CREDITS_SUMMARY, ME, ONBOARDING_SAVE, ONBOARDING_SCRAPE, ORG_CREATE, ORG_SHOW, ORG_UPDATE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.display import human_data
+from recala_cli.parallel import run_parallel
+from recala_cli.polling import indicator
+from recala_cli.organizations import organization_description, organization_label
+from recala_cli.prompts import ask
+from recala_cli.runtime import command_runner, common_options, confirm, json_option, open_client, accepted_yes_option, dry_run_option
+
+#: The scan's own entity types, as the wizard sends them back (products and competitors also as lists).
+_ENTITY_TYPES = ("industry", "product", "service", "audience", "competitor", "keyword", "location")
+_SCAN_TIMEOUT_SECONDS = 180.0
+
+
+def _describe_org(result: dict[str, Any]) -> str:
+    org = result.get("org") or {}
+    lines = [org.get("name") or "(unnamed company)", f"  id:       {str(org.get('id', ''))[:8]}"]
+    fields = (("website", org.get("website_url")), ("blog", org.get("blog_base_url")),
+              ("language", org.get("language")), ("timezone", org.get("timezone") or result.get("timezone")),
+              ("plan", (result.get("plan") or {}).get("name")), ("niche", org.get("niche")))
+    lines.extend(f"  {label + ':':<9} {value}" for label, value in fields if value)
+    return "\n".join(lines)
+
+
+@click.group()
+def org() -> None:
+    """Create, choose or scan the company you act on."""
+
+
+@org.command("show")
+@common_options
+@command_runner(human=_describe_org)
+def show(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Show the active company: website, language, timezone and plan."""
+    client = open_client(ctx, org_flag)
+    assert client.org_id is not None  # open_client refuses to build one without it
+    org_id = client.org_id
+    # --json is the API's own document (agents read the plan with `credits --json`); a person also sees the plan.
+    wants_plan = not ctx.obj.get("as_json")
+    found = run_parallel({
+        "identity": lambda: client.call(ORG_SHOW, path={"org_id": org_id}),
+        "plan": lambda: _plan_or_none(client) if wants_plan else None,
+    })
+    identity: dict[str, Any] = found["identity"]
+    return {**identity, "plan": found["plan"]} if found["plan"] else identity
+
+
+def _plan_or_none(client: RecalaClient) -> dict[str, str] | None:
+    """The plan is a nicety on this view: any failing read leaves the company shown without it."""
+    try:
+        summary = client.call(CREDITS_SUMMARY) or {}
+    except CliError:
+        return None
+    name = summary.get("plan_name") or summary.get("plan")
+    return {"name": str(name), "key": str(summary.get("plan") or "")} if name else None
+
+
+def _describe_memberships(result: dict[str, Any]) -> str:
+    active = result.get("active_org")
+    lines = [
+        f"{'*' if m['org_id'] == active else ' '} {m['name']}  {m['role']}  [{m['org_id'][:8]}]"
+        for m in result["memberships"]
+    ]
+    return "\n".join(lines) if lines else "No companies yet."
+
+
+@org.command("list")
+@json_option
+@command_runner(human=_describe_memberships)
+def list_orgs(ctx: click.Context) -> dict[str, Any]:
+    """Every company this credential may act on; * marks the active one."""
+    client = open_client(ctx, None, require_org=False)
+    me: dict[str, Any] = client.call(ME)
+    return {"memberships": me["memberships"], "active_org": ctx.meta.get("resolved_org")}
+
+
+def _describe_selection(ctx: click.Context, result: dict[str, Any]) -> str:
+    org_id = result["org_id"]
+    org = ctx.meta.get("organization_names", {}).get(org_id) or {"org_id": org_id}
+    if not org.get("name"):
+        return f"Active company: {org_id}"
+    return f"Using {organization_description(org)} [{org_id[:8]}]"
+
+
+@org.command("use")
+@json_option
+@command_runner(contextual_human=_describe_selection)
+@click.argument("org_id", metavar="ORG")
+def use(ctx: click.Context, org_id: str) -> dict[str, Any]:
+    """Choose the company later commands act on.
+
+    ORG is its name, slug or id."""
+    if config.is_org_id(org_id.strip()):
+        org_id = org_id.strip()
+        if not ctx.obj.get("as_json"):
+            try:
+                client = open_client(ctx, org_id, require_org=False)
+                client.org_id = org_id
+                organization_label(ctx, client)
+            except CliError:
+                pass  # choosing a known id still works offline, as it did before
+    else:
+        open_client(ctx, org_id, require_org=False)
+        org_id = ctx.meta["resolved_org"]
+    config.set_active_org(org_id)
+    return {"org_id": org_id}
+
+
+# ── create or fill in ───────────────────────────────────────────────────────────
+
+
+def blank_company(memberships: list[dict[str, Any]]) -> dict[str, Any] | None:
+    """The empty company a brand-new account was given at sign-up: the only one, owned, with no website yet."""
+    owned = [m for m in memberships if m.get("role") == "owner"]
+    if len(memberships) == 1 and len(owned) == 1 and not owned[0].get("website_url"):
+        return owned[0]
+    return None
+
+
+def remember_market(org_id: str, market: str | None) -> None:
+    if market:
+        progress = config.onboarding_progress(org_id)
+        config.save_onboarding_progress(org_id, {**progress, "market": market.upper()})
+
+
+def create_or_fill(ctx: click.Context, client: RecalaClient, *, name: str, website: str, language: str,
+                   market: str | None, use: bool = True) -> dict[str, Any]:
+    """Fill in the account's blank company, else create a new one; it becomes the active company unless use=False."""
+    me = client.call(ME) or {}
+    memberships = me.get("memberships") or []
+    blank = blank_company(memberships)
+    previous_id = config.active_org()
+    # Only a company the credential still lists can be switched back to; a deleted one is not offered.
+    previous = next((m for m in memberships if m.get("org_id") == previous_id), None)
+    fields = {"name": name, "website_url": website, "language": language}
+    if blank:
+        confirm(ctx, client, f"Set up your company as {name} ({website}, {language})?")
+        client.org_id = blank["org_id"]
+        updated = client.call(ORG_UPDATE, path={"org_id": blank["org_id"]}, json=fields) or {}
+        created = {"created": False, "filled_in": True, "org": updated.get("org") or {"id": blank["org_id"], **fields}}
+    else:
+        confirm(ctx, client, f"Create the company {name} ({website}, {language})?")
+        created = client.call(ORG_CREATE, json=fields) or {}
+    org_id = str((created.get("org") or {}).get("id") or "")
+    if not org_id:
+        raise CliError(ExitCode.ERROR, "org_not_created", "Recala did not return the new company's id.")
+    if use:
+        config.set_active_org(org_id)
+    client.org_id = org_id
+    remember_market(org_id, market)
+    return {**created, "market": (market or "").upper() or None, "active": use,
+            "previous_active_org": previous if previous and previous["org_id"] != org_id else None}
+
+
+def _describe_created(result: dict[str, Any]) -> str:
+    """Which company later commands act on, said out loud: creating one switches to it unless --no-use."""
+    org, previous = result.get("org") or {}, result.get("previous_active_org")
+    name, short = org.get("name"), str(org.get("id") or "")[:8]
+    lines = [f"{'Set up' if result.get('filled_in') else 'Created'} {name} [{short}]."]
+    if result.get("active", True):
+        if previous:
+            lines.append(f"{name} is now the active company: later commands act on it, "
+                         f"not on {previous.get('name') or previous['org_id']}.")
+            lines.append(f"Switch back: recala company use {previous['org_id'][:8]}")
+        else:
+            lines.append(f"{name} is now the active company.")
+    else:
+        kept = f"{previous.get('name') or previous['org_id']} is still the active company." if previous \
+            else "No company is active yet."
+        lines.append(f"{kept} To act on {name}: recala company use {short}")
+    return "\n".join(lines)
+
+
+@org.command("create")
+@common_options
+@command_runner(human=_describe_created)
+@click.option("--name", default=None, help="The company's name, as readers know it.")
+@click.option("--website", default=None, help="Its website, e.g. https://cometa.cards")
+@click.option("--language", default=None, help="The language it publishes in (ISO code, e.g. es).")
+@click.option("--market", default=None, help="The country it sells in (ISO code, e.g. ES).")
+@click.option("--use/--no-use", default=True, show_default=True,
+              help="Make the new company the active one that later commands act on.")
+@accepted_yes_option
+@dry_run_option
+def create(ctx: click.Context, org_flag: str | None, name: str | None, website: str | None, language: str | None,
+           market: str | None, use: bool) -> dict[str, Any]:
+    """Create a company and make it active.
+
+    Fills in the empty company a new account starts with, else creates another; --no-use keeps the
+    current active company. For the guided setup (company, website, author, first topics), run
+    recala onboard instead.
+    """
+    client = open_client(ctx, org_flag, require_org=False)
+    return create_or_fill(
+        ctx, client,
+        name=ask(ctx, name, label="Company name", flag="--name"),
+        website=ask(ctx, website, label="Website", flag="--website"),
+        language=ask(ctx, language, label="Language it publishes in (es, en, ...)", flag="--language").lower(),
+        market=ask(ctx, market, label="Country it sells in (ES, US, ...)", flag="--market", default="").upper() or None,
+        use=use,
+    )
+
+
+# ── website scan ────────────────────────────────────────────────────────────────
+
+
+def _names(entities: list[dict[str, Any]], kind: str) -> list[str]:
+    """Names of one kind; a service business's services are its products (the server saves both as products)."""
+    kinds = {"product", "service"} if kind == "product" else {kind}
+    return [str(e.get("name")) for e in entities if e.get("entity_type") in kinds and e.get("name")]
+
+
+def describe_scan(scan: dict[str, Any]) -> str:
+    scan = human_data(scan)
+    entities = scan.get("entities") or []
+    brand = scan.get("brand") or {}
+    website = scan.get("website") or {}
+    lines = [f"  {website.get('title') or website.get('url')}"]
+    if brand.get("core_description") or website.get("description"):
+        lines.append(f"  {brand.get('core_description') or website.get('description')}")
+    if brand.get("brand_tone"):
+        lines.append(f"  Tone: {brand['brand_tone']}" + (f", {brand['brand_style']}" if brand.get("brand_style") else ""))
+    found = False
+    for label, kind in (("Industry", "industry"), ("Products", "product"), ("Audiences", "audience"),
+                        ("Competitors", "competitor"), ("Keywords", "keyword")):
+        names = _names(entities, kind)
+        if names:
+            found = True
+            lines.append(f"  {label + ':':<12} {', '.join(names[:8])}")
+    if not found:
+        lines.append("  No products, audiences or competitors could be taken from the site's own text.")
+    if website.get("blog_url"):
+        lines.append(f"  Blog:        {website['blog_url']}")
+    for warning in (brand.get("voice_warning"), (scan.get("knowledge_ingestion") or {}).get("warning")):
+        if warning:
+            lines.append(f"  Note: {warning}")
+    if scan.get("scrape_thin"):
+        lines.append("  Warning: the site had almost no readable text. Check the address.")
+    return "\n".join(lines)
+
+
+_PALETTE_SOURCES = {"page": "the site's own declared colours", "brandfetch": "Brandfetch",
+                    "llm_css_scrape": "the site's styling"}
+
+
+def scan_findings(scan: dict[str, Any]) -> dict[str, Any]:
+    """What the scan actually found, as counts an agent can branch on."""
+    entities = scan.get("entities") or []
+    brand = scan.get("brand") or {}
+    niche = _names(entities, "industry")
+    return {
+        "products": len(_names(entities, "product")),
+        "audiences": len(_names(entities, "audience")),
+        "competitors": len(_names(entities, "competitor")),
+        "niche": niche[0] if niche else None,
+        "voice": bool((brand.get("brand_voice") or brand.get("brand_tone"))
+                      and brand.get("voice_status") not in {"unknown", "failed"}),
+        "palette_source": None if scan.get("palette_source") in {"", "none"} else scan.get("palette_source"),
+    }
+
+
+def describe_findings(result: dict[str, Any]) -> str:
+    found = result.get("found") or {}
+    if not (found.get("products") or found.get("audiences") or found.get("competitors")
+            or found.get("niche") or found.get("voice")):
+        return "Read the website but found nothing usable: no products, audiences, competitors, niche or voice."
+    parts = [f"{found['products']} products", f"{found['audiences']} audiences", f"{found['competitors']} competitors"]
+    parts.append(f"niche {found['niche']}" if found.get("niche") else "no niche")
+    parts.append("voice read from the site" if found.get("voice") else "no voice")
+    if found.get("palette_source"):
+        parts.append(f"colours from {_PALETTE_SOURCES.get(found['palette_source'], found['palette_source'])}")
+    return "Saved what Recala found on the website: " + ", ".join(parts) + "."
+
+
+def save_scan_payload(scan: dict[str, Any], *, website: str, market: str | None, brand_name: str) -> dict[str, Any]:
+    """What the portal's wizard sends to save-entities after the person confirms the scan."""
+    entities = [e for e in scan.get("entities") or [] if e.get("entity_type") in _ENTITY_TYPES and e.get("name")]
+    brand = scan.get("brand") or {}
+    payload: dict[str, Any] = {
+        "entities": [{"name": e["name"], "entity_type": e["entity_type"], "description": e.get("description") or "",
+                      "confidence": e.get("confidence") or 0.9, "source": e.get("source") or "website"}
+                     for e in entities],
+        "products": [{"name": name} for name in _names(entities, "product")],
+        "competitors": [{"name": name} for name in _names(entities, "competitor")],
+        "website_url": website,
+        "author_display_name": brand_name or None,
+        "blog_base_url": (scan.get("website") or {}).get("blog_url") or None,
+        "brand_tone": brand.get("brand_tone") or None,
+        "brand_style": brand.get("brand_style") or None,
+        "content_scope": "national" if market else "local",
+        "replace_existing": False,
+        "onboarding_method": "website",
+        "channel": "cli",
+    }
+    if market:
+        payload["country"] = market
+    return {key: value for key, value in payload.items() if value is not None}
+
+
+def scan_website(ctx: click.Context, client: RecalaClient, *, website: str | None) -> dict[str, Any]:
+    org = (client.call(ORG_SHOW, path={"org_id": str(client.org_id)}) or {}).get("org") or {}
+    address = website or org.get("website_url")
+    if not address:
+        raise CliError(ExitCode.CONFLICT, "no_website", "This company has no website yet: recala company create")
+    # Reading the site is already a write: the server saves the brand it finds and spends a model call.
+    confirm(ctx, client, f"Read {address} and save the brand Recala finds there?")
+    with indicator(ctx, f"Reading {address}") as spinner:
+        scan = client.call(ONBOARDING_SCRAPE, json={"url": address}, timeout=_SCAN_TIMEOUT_SECONDS) or {}
+        if spinner is not None:
+            spinner.done(f"Read {address}")
+    if not (ctx.find_root().obj or {}).get("as_json"):
+        click.echo(describe_scan(scan), err=True)
+    if scan.get("scrape_thin"):
+        raise CliError(ExitCode.CONFLICT, "scrape_thin",
+                       f"Recala could not read {address}: double-check the address (recala company create --website).")
+    market = config.onboarding_progress(str(client.org_id)).get("market")
+    confirm(ctx, client, "Save these findings?",
+            machine_summary=f"Save these findings for {org.get('name') or 'this company'}?")
+    saved = client.call(ONBOARDING_SAVE, json=save_scan_payload(scan, website=address, market=market,
+                                                               brand_name=org.get("name") or "")) or {}
+    config.save_onboarding_progress(str(client.org_id), {**config.onboarding_progress(str(client.org_id)),
+                                                          "scanned": True})
+    return {"scan": scan, "saved": saved, "found": scan_findings(scan)}
+
+
+@org.command("scan")
+@common_options
+@command_runner(human=describe_findings)
+@click.option("--website", default=None, help="Read this address instead of the company's website.")
+@accepted_yes_option
+@dry_run_option
+def scan(ctx: click.Context, org_flag: str | None, website: str | None) -> dict[str, Any]:
+    """Read the website; save what you confirm.
+
+    Brand, products, audiences and competitors."""
+    return scan_website(ctx, open_client(ctx, org_flag), website=website)

recala_cli/commands/profile.py

@@ -0,0 +1,70 @@
+"""`recala company profile show`: the brand profile the articles are written in (read-only).
+
+It gathers what the portal's brand and profile pages show: the author and voice, the positioning
+and the default article intent. Changing it stays in the portal.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import click
+
+from recala_cli.display import display_name
+from recala_cli.endpoints import PROFILE_AUTHOR, PROFILE_INTENT, PROFILE_POSITIONING
+from recala_cli.runtime import command_runner, common_options, open_client, optional_read
+
+CHANGE_IN_PORTAL = "To change any of this, use Brand and Settings in the portal."
+
+
+def _line(label: str, value: Any) -> str | None:
+    text = display_name(value) if isinstance(value, str) else ", ".join(display_name(item) for item in value or [])
+    return f"  {label}: {text}" if text else None
+
+
+def _section(title: str, rows: list[str | None]) -> list[str]:
+    present = [row for row in rows if row]
+    return [f"{title}:", *present] if present else []
+
+
+def describe_profile(profile: dict[str, Any]) -> str:
+    author, positioning = profile.get("author") or {}, profile.get("positioning") or {}
+    where = ", ".join(part for part in (author.get("city"), author.get("region"), author.get("country")) if part)
+    blocks = [
+        _section("Author", [_line("Name", author.get("author_display_name")), _line("Title", author.get("author_title")),
+                            _line("Bio", author.get("author_bio"))]),
+        _section("Voice", [_line("Tone", author.get("brand_tone")), _line("Voice", author.get("brand_voice")),
+                           _line("Personality", author.get("brand_personality")), _line("Style", author.get("brand_style")),
+                           _line("Writing guidelines", author.get("writing_guidelines")),
+                           _line("Never say", author.get("forbidden_phrases"))]),
+        _section("Company", [_line("Industry", author.get("niche")), _line("Language", author.get("language")),
+                             _line("Where", where), _line("Reaches", author.get("content_scope"))]),
+        _section("Positioning", [_line("One line", positioning.get("one_line_pov")), _line("Who we are", positioning.get("who_we_are")),
+                                 _line("Market", positioning.get("market_category")),
+                                 _line("Persona", positioning.get("author_persona")),
+                                 *[_line(f"Against {wedge['name']}", wedge.get("our_wedge_vs_them"))
+                                   for wedge in positioning.get("wedges") or [] if wedge.get("name")]]),
+        _section("Articles", [_line("Default intent", (profile.get("intent") or {}).get("default_intent"))]),
+    ]
+    lines = [line for block in blocks for line in block]
+    return "\n".join([*lines, CHANGE_IN_PORTAL] if lines else ["The brand profile is empty.", CHANGE_IN_PORTAL])
+
+
+@click.group()
+def profile() -> None:
+    """The company's brand profile: author, voice and positioning."""
+
+
+@profile.command("show")
+@common_options
+@command_runner(human=describe_profile)
+def show(ctx: click.Context, org_flag: str | None) -> dict[str, Any]:
+    """Show the author, voice and positioning.
+
+    Also the default intent the articles are written with."""
+    client = open_client(ctx, org_flag)
+    return {
+        "author": optional_read(client, PROFILE_AUTHOR),
+        "positioning": optional_read(client, PROFILE_POSITIONING),
+        "intent": optional_read(client, PROFILE_INTENT),
+    }

recala_cli/commands/questions.py

@@ -0,0 +1,246 @@
+"""Read the company's tracked questions and confirm its first baseline."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter, defaultdict
+from typing import Any
+
+import click
+from click.core import ParameterSource
+
+from recala_cli.endpoints import QUESTION_PANEL, QUESTION_PANEL_BASELINE
+from recala_cli.errors import CliError, ExitCode
+from recala_cli.runtime import command_runner, common_options, confirm, open_client, accepted_yes_option, dry_run_option
+from recala_cli.views import company_timezone, engine_name, local_time, question_counts, timezone_label
+
+NOT_ENABLED = "Question tracking is not switched on for this company yet."
+BASELINE_REFUSALS = {
+    (403, "human_only"): (
+        "Starting a baseline needs a person signed in, not an API key. Run: recala login"
+    ),
+    (403, "ai_checks_not_in_plan"): "Your plan does not include AI checks.",
+    (409, "baseline_exists"): (
+        "A baseline already exists; your questions are measured on the plan's schedule. "
+        "See: recala questions"
+    ),
+    (409, "panel_run_in_progress"): "A baseline is already running. See: recala questions",
+    (422, "second_language_not_in_plan"): "That language is not included in your plan.",
+}
+language_option = click.option(
+    "--language", default=None, metavar="xx",
+    help="Panel language: two lowercase letters (default: the company's language).",
+)
+all_option = click.option("--all", "all_questions", is_flag=True,
+                          help="Show every tracked question in human output (JSON always includes all).")
+
+# question_panel/engines.py, engine.py, cron.py and DataForSEO's failure kinds.
+_ERROR_PHRASES = {  # each reads after a count: "3 had no AI overview"
+    "timeout": "timed out", "blocked": "were blocked", "lost": "were lost", "error": "failed",
+    "empty_serp": "found no search results", "no_ai_overview": "had no AI overview",
+    "ai_overview_without_sources": "had an AI overview with no readable sources",
+    "empty_answer": "came back empty", "no_sources": "named no sources",
+    "unresolved_sources": "had sources that could not be resolved",
+    "payment_required": "were refused by the data provider (payment needed)",
+    "auth": "were refused by the data provider (sign-in)", "rate_limited": "hit the data provider's rate limit",
+    "invalid_request": "were invalid requests", "provider_unavailable": "met an unavailable data provider",
+}
+_OTHER_PHRASE = "had another problem"
+
+
+def _language_body(language: str | None) -> dict[str, str]:
+    if language is None:
+        return {}
+    if not re.fullmatch(r"[a-z]{2}", language):
+        raise CliError(
+            ExitCode.USAGE, "invalid_language",
+            "--language must be two lowercase letters, for example: es.",
+        )
+    return {"language": language}
+
+
+def _describe_measurements(view: dict[str, Any], zone: str | None) -> list[str]:
+    """Keep rolling ownership and latest per-question citations separate, per engine."""
+    labels = {}
+    latest_by_engine = defaultdict(list)
+    for area in view["panel"].get("areas") or []:
+        for question in area["questions"]:
+            for engine, tier in (question.get("tiers") or {}).items():
+                label = tier.get("label")
+                labels[engine] = label if label and label != engine else engine_name(engine)
+                if tier.get("latest"):
+                    latest_by_engine[engine].append(tier["latest"])
+
+    lines = []
+    for engine, counts in view.get("summary", {}).items():
+        if counts.get("owned") is not None:
+            lines.append(
+                f"{labels.get(engine, engine_name(engine))}: {counts['owned']} owned questions "
+                f"in the last {view['window_days']} days."
+            )
+    for engine, latest in latest_by_engine.items():
+        measured = [
+            check for check in latest
+            if check["status"] == "ok" and isinstance(check.get("own_domain_cited"), bool)
+        ]
+        cited = sum(check["own_domain_cited"] for check in measured)
+        result = (
+            f"{cited} of {len(measured)} measured questions cited"
+            if measured else "no usable measurements"
+        )
+        when = local_time(max((check.get("run_at") or "" for check in latest), default=""), zone)
+        lines.append(
+            f"Latest {labels[engine]} checks: {result}; "
+            f"{len(latest) - len(measured)} without a usable answer (most recent: {when})."
+        )
+    return lines
+
+
+def _citation_state(latest: dict[str, Any]) -> str:
+    cited = latest.get("own_domain_cited")
+    if latest.get("status") != "ok" or not isinstance(cited, bool):
+        return "unknown"
+    return "cited" if cited else "not cited"
+
+
+def _question_lines(view: dict[str, Any], *, all_questions: bool) -> list[str]:
+    panel = view["panel"]
+    available, total = question_counts(panel)
+    limit = available if all_questions else min(10, available)
+    engines = dict.fromkeys(view.get("summary") or {})
+    for area in panel.get("areas") or []:
+        for question in area.get("questions") or []:
+            engines.update(dict.fromkeys(question.get("tiers") or {}))
+    lines, shown = [], 0
+    for area in panel.get("areas") or []:
+        questions = (area.get("questions") or [])[:max(0, limit - shown)]
+        if not questions:
+            continue
+        lines.append(f"\n{area.get('area') or 'Other questions'}")
+        for question in questions:
+            tiers = question.get("tiers") or {}
+            results = (f"{engine_name(engine)}: {_citation_state((tiers.get(engine) or {}).get('latest') or {})}"
+                       for engine in engines)
+            lines += [f"  {question['question']}", "    " + " · ".join(results)]
+            shown += 1
+    lines.append(f"Showing {shown} of {total} questions."
+                 + (" All: recala questions --all" if not all_questions and shown < total else ""))
+    return lines
+
+
+def _failure_lines(view: dict[str, Any]) -> list[str]:
+    """Failed checks over the whole window, in words. The latest-check summary above counts only each question's
+    newest check, so this line names its own scope instead of repeating "unknown"."""
+    failures = defaultdict(Counter)
+    for failure in view.get("engine_failures") or []:
+        failures[failure["engine"]][_ERROR_PHRASES.get(failure.get("error_kind"), _OTHER_PHRASE)] += failure["count"]
+    days = view.get("window_days")
+    window = f"in the last {days} days" if days else "recently"
+    lines = []
+    for engine, counts in failures.items():
+        total = sum(counts.values())
+        reasons = ", ".join(f"{count} {phrase}" for phrase, count in counts.items())
+        lines.append(f"{engine_name(engine)}: {total} check{'' if total == 1 else 's'} {window} "
+                     f"gave no usable answer ({reasons})")
+    return lines
+
+
+def _describe_questions(ctx: click.Context, view: dict[str, Any]) -> str:
+    zone = company_timezone(ctx, view)
+    baseline = view.get("baseline")
+    run = view.get("latest_run")
+    if baseline is None:
+        running = bool(run) and run.get("status") == "running"
+        lines = ["No baseline yet." + ("" if running else " Start it: recala questions baseline")]
+    elif baseline.get("captured_at"):
+        lines = [f"Baseline captured at {local_time(baseline['captured_at'], zone)}."]
+    else:
+        lines = ["Baseline exists; its capture date is not recorded."]
+    if run:
+        lines.append(f"Latest {run['kind'].replace('_', ' ')} run is {run['status'].replace('_', ' ')}.")
+    panel = view["panel"]
+    groups = ", ".join(
+        f"{count} {group.replace('_', ' ')}"
+        for group, count in (panel.get("by_group") or {}).items()
+    )
+    lines.insert(0, timezone_label(zone))
+    lines.append(f"Tracking {question_counts(panel)[1]} questions" + (f" ({groups})" if groups else "") + ".")
+    lines.extend(_describe_measurements(view, zone))
+    lines.extend(_failure_lines(view))
+    lines.extend(_question_lines(view, all_questions=ctx.meta.get("all_questions", False)))
+    return "\n".join(lines)
+
+
+@click.group(invoke_without_command=True)
+@common_options
+@language_option
+@all_option
+@click.pass_context
+def questions(
+    ctx: click.Context, org_flag: str | None, as_json: bool, language: str | None,
+    all_questions: bool,
+) -> None:
+    """Show tracked questions.
+
+    Start their baseline with: recala questions baseline"""
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(show, org_flag=org_flag, as_json=as_json, language=language, all_questions=all_questions)
+        return
+    typed = [name for name in ("org_flag", "as_json", "language", "all_questions")
+             if ctx.get_parameter_source(name) is ParameterSource.COMMANDLINE]
+    if typed:
+        # The subcommand never sees them: a baseline would start for another company or language.
+        raise click.UsageError(
+            f"Put --org, --json, --language and --all after the subcommand: "
+            f"recala questions {ctx.invoked_subcommand} --org <company>", ctx)
+
+
+@questions.command("show")
+@common_options
+@language_option
+@all_option
+@command_runner(contextual_human=_describe_questions)
+def show(ctx: click.Context, org_flag: str | None, language: str | None, all_questions: bool) -> dict[str, Any]:
+    """Show the baseline, tracked questions and latest measurements."""
+    params = _language_body(language)
+    ctx.meta["all_questions"] = all_questions
+    client = open_client(ctx, org_flag)
+    try:
+        return client.call(QUESTION_PANEL, params=params)
+    except CliError as error:
+        if error.status == 404:
+            error.message = NOT_ENABLED
+        raise
+
+
+def _describe_started(result: dict[str, Any]) -> str:
+    return (
+        f"Baseline started ({result['size']} questions, plan {result['plan']}). "
+        "It runs in the background; check it with: recala questions"
+    )
+
+
+@questions.command("baseline")
+@common_options
+@language_option
+@command_runner(human=_describe_started)
+@accepted_yes_option
+@dry_run_option
+def baseline(ctx: click.Context, org_flag: str | None, language: str | None) -> dict[str, Any]:
+    """Start the question baseline (asks first).
+
+    Uses your plan's AI-check allowance."""
+    body = _language_body(language)
+    client = open_client(ctx, org_flag)
+    confirm(ctx, client, "Start the question baseline? This uses your plan's AI-check allowance.")
+    try:
+        return client.call(QUESTION_PANEL_BASELINE, json=body)
+    except CliError as error:
+        message = BASELINE_REFUSALS.get((error.status, error.code))
+        if error.status == 404:
+            message = NOT_ENABLED
+        elif error.status == 403 and message is None:
+            message = "Only the company owner or assigned staff can start it."
+        if message:
+            error.message = message
+        raise