dromad 0.1.0__tar.gz

dromad-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Sillings
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dromad-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: dromad
+Version: 0.1.0
+Summary: GEO research tools for coding agents: multi-engine prompt runs, fanout, citation analysis and page audits
+Keywords: geo,ai-search,citations,llm,cli,agents
+Author: John Sillings
+Author-email: John Sillings <john@johnsillings.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: typer>=0.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.7
+Requires-Python: >=3.12
+Project-URL: Homepage, https://dromad.dev
+Project-URL: Documentation, https://dromad.dev/docs
+Project-URL: CLI reference, https://dromad.dev/docs/cli
+Project-URL: For agents, https://dromad.dev/docs/agents
+Description-Content-Type: text/markdown
+
+# dromad
+
+The Dromad command-line client: GEO research tools built primarily for coding agents.
+
+Dromad asks ChatGPT, Claude and Gemini the questions your customers ask, with each engine's web search on, and records what each one answered and which sources it cited. It counts those citations across runs, generates the questions worth asking, and audits the pages involved. Dromad records evidence and counts it; the reasoning over it is yours or your agent's.
+
+```sh
+pip install dromad        # or: uv tool install dromad · pipx install dromad
+dromad login              # opens the browser to approve this device
+dromad prompt "best search APIs for AI agents"
+```
+
+`dromad` talks to the hosted service at [dromad.dev](https://dromad.dev); you need an account there, and sign-up is by invitation for now. Every command prints readable output by default and one stable JSON document with `--json`, so an agent can drive it directly. For CI and agents without a browser, set `DROMAD_API_KEY` instead of logging in.
+
+- [Docs](https://dromad.dev/docs): what Dromad records, the quickstart, and what it costs.
+- [CLI reference](https://dromad.dev/docs/cli): every command, with real output.
+- [For agents](https://dromad.dev/docs/agents): which command when, and how they compose.
+
+This package contains the command, the HTTP client under it, and the pydantic schemas that define the API contract. It depends on typer, httpx and pydantic, and nothing else. Python 3.12 or newer. MIT licensed.

dromad-0.1.0/README.md

@@ -0,0 +1,19 @@
+# dromad
+
+The Dromad command-line client: GEO research tools built primarily for coding agents.
+
+Dromad asks ChatGPT, Claude and Gemini the questions your customers ask, with each engine's web search on, and records what each one answered and which sources it cited. It counts those citations across runs, generates the questions worth asking, and audits the pages involved. Dromad records evidence and counts it; the reasoning over it is yours or your agent's.
+
+```sh
+pip install dromad        # or: uv tool install dromad · pipx install dromad
+dromad login              # opens the browser to approve this device
+dromad prompt "best search APIs for AI agents"
+```
+
+`dromad` talks to the hosted service at [dromad.dev](https://dromad.dev); you need an account there, and sign-up is by invitation for now. Every command prints readable output by default and one stable JSON document with `--json`, so an agent can drive it directly. For CI and agents without a browser, set `DROMAD_API_KEY` instead of logging in.
+
+- [Docs](https://dromad.dev/docs): what Dromad records, the quickstart, and what it costs.
+- [CLI reference](https://dromad.dev/docs/cli): every command, with real output.
+- [For agents](https://dromad.dev/docs/agents): which command when, and how they compose.
+
+This package contains the command, the HTTP client under it, and the pydantic schemas that define the API contract. It depends on typer, httpx and pydantic, and nothing else. Python 3.12 or newer. MIT licensed.

dromad-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[project]
+name = "dromad"
+version = "0.1.0"
+description = "GEO research tools for coding agents: multi-engine prompt runs, fanout, citation analysis and page audits"
+readme = "README.md"
+requires-python = ">=3.12"
+# The client only. The hosted service it talks to is not part of this package.
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "John Sillings", email = "john@johnsillings.com" }]
+keywords = ["geo", "ai-search", "citations", "llm", "cli", "agents"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+# The whole dependency surface of `pip install dromad`. The hosted service is a
+# separate distribution; nothing here may pull a web framework or ORM.
+# tests/test_structure.py pins this list.
+dependencies = [
+    "typer>=0.12",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[project.urls]
+Homepage = "https://dromad.dev"
+Documentation = "https://dromad.dev/docs"
+"CLI reference" = "https://dromad.dev/docs/cli"
+"For agents" = "https://dromad.dev/docs/agents"
+
+[project.scripts]
+dromad = "dromad.cli.main:app"
+
+[build-system]
+requires = ["uv_build>=0.11.0,<0.12"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+# The server's pytest plugin is installed in the shared workspace venv. It must
+# not configure a Django project inside the client's suite.
+addopts = "-p no:django"

dromad-0.1.0/src/dromad/__init__.py

@@ -0,0 +1,14 @@
+"""Dromad: GEO research tools for coding agents.
+
+This distribution is the client half of Dromad: the ``dromad`` command, the
+HTTP client under it, and the pydantic schemas in :mod:`dromad.schemas` that
+are the contract with the hosted service. The service imports those schemas;
+nothing here imports the service.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("dromad")
+except PackageNotFoundError:  # a source tree on sys.path without an install
+    __version__ = "0.0.0+unknown"

dromad-0.1.0/src/dromad/cli/analyses.py

@@ -0,0 +1,62 @@
+"""``dromad analyses list`` and ``dromad analyses show``."""
+
+import typer
+
+from dromad import config
+from dromad.cli.citations import render_citations
+from dromad.cli.fanout import render_fanout
+from dromad.cli.output import emit_json, errors_reported, table
+from dromad.client import Client
+from dromad.schemas.analyses import CitationAnalysis
+from dromad.schemas.ids import IdKind, is_id
+
+app = typer.Typer(help="Inspect analyses: results derived from runs.", no_args_is_help=True)
+
+JSON_OPTION = typer.Option(False, "--json", help="Print one JSON document to stdout.")
+API_URL_OPTION = typer.Option(None, "--api-url", help="Dromad server.")
+
+
+@app.command("list")
+def list_analyses(
+    kind: str | None = typer.Option(None, "--kind", help="Only one kind: fanout or citations."),
+    limit: int = typer.Option(20, "--limit", min=1, max=200),
+    api_url: str | None = API_URL_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Your analyses, newest first."""
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        listing = client.list_analyses(kind=kind, limit=limit)
+    if as_json:
+        emit_json(listing)
+        return
+    if not listing.items:
+        typer.echo(
+            'No analyses yet. Generate your first questions:\n\n  dromad fanout "AI search API"'
+        )
+        return
+    rows = [
+        [a.id, a.kind, a.status, a.run_count, a.created_at.strftime("%Y-%m-%d %H:%M"), a.subject]
+        for a in listing.items
+    ]
+    typer.echo(table(rows, ["ID", "KIND", "STATUS", "RUNS", "CREATED", "SUBJECT"]))
+
+
+@app.command("show")
+def show(
+    analysis_id: str = typer.Argument(..., help="An analysis ID (fa_… or ca_…)."),
+    api_url: str | None = API_URL_OPTION,
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """One analysis, in full."""
+    if not is_id(analysis_id, IdKind.FANOUT_ANALYSIS, IdKind.CITATION_ANALYSIS):
+        raise typer.BadParameter(
+            f"{analysis_id!r} is not an analysis ID (fa_… or ca_…)", param_hint="ANALYSIS_ID"
+        )
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        analysis = client.get_analysis(analysis_id)
+    if as_json:
+        emit_json(analysis)
+    elif isinstance(analysis, CitationAnalysis):
+        typer.echo(render_citations(analysis))
+    else:
+        typer.echo(render_fanout(analysis))

dromad-0.1.0/src/dromad/cli/audit.py

@@ -0,0 +1,167 @@
+"""``dromad audit`` — what one page looks like to a crawler, and what follows."""
+
+import time
+
+import typer
+
+from dromad import config
+from dromad.cli.exit_codes import ExitCode
+from dromad.cli.output import emit_json, errors_reported, info
+from dromad.client import Client
+from dromad.client.errors import DromadError
+from dromad.schemas.audit import AuditReport, AuditResult
+from dromad.schemas.runs import TERMINAL_RUN_STATUSES, Run
+
+STATUS_MARK = {"fail": "✗", "error": "!", "pass": "✓", "not_applicable": "–"}
+
+
+def _line(label: str, value) -> str:
+    return f"{label:<12} {value}"
+
+
+def render_audit(result: AuditResult, run_id: str) -> str:
+    fetch, content, meta, structure = (
+        result.fetch,
+        result.content,
+        result.metadata,
+        result.structure,
+    )
+    lines = [result.page.url]
+    if result.page.final_url != result.page.url:
+        lines.append(f"  → {result.page.final_url}")
+    hops = len(fetch.redirect_chain)
+    parts = [f"{fetch.status} {fetch.http_status or ''}".strip(), fetch.content_type or "–"]
+    parts.append(f"{fetch.elapsed_ms} ms")
+    if hops:
+        parts.append(f"{hops} redirect{'s' if hops > 1 else ''}")
+    if fetch.robots_txt and fetch.robots_txt.allows_page is False:
+        parts.append("robots.txt disallows")
+    lines += ["", _line("Fetched", " · ".join(parts))]
+    if fetch.error:
+        lines.append(_line("", fetch.error))
+    if meta.title is not None or content.extraction_method:
+        lines += [
+            _line("Title", meta.title or "—"),
+            _line("Description", meta.description or "—"),
+            _line("Canonical", meta.canonical or "—"),
+            _line("Language", meta.lang or "—"),
+        ]
+        links = content.links
+        lines.append(
+            _line(
+                "Content",
+                f"{content.word_count:,} words · {content.code_blocks} code blocks · "
+                f"{content.tables} tables · {links.total} links ({links.internal} internal) · "
+                f"via {content.extraction_method}",
+            )
+        )
+        if content.likely_js_dependent:
+            lines.append(
+                _line("", "looks like a JavaScript shell (Dromad does not run JavaScript)")
+            )
+        skips = len(structure.level_skips)
+        lines.append(
+            _line(
+                "Outline",
+                # The outline is the main content's; whether the page has an h1
+                # at all is the missing_h1 finding, which looks at the whole page.
+                f"{len(structure.headings)} headings in the main content · "
+                f"{skips} level skip{'s' if skips != 1 else ''}",
+            )
+        )
+        if meta.structured_data_types or meta.structured_data_errors:
+            types = ", ".join(meta.structured_data_types) or "—"
+            errors = (
+                f" · {meta.structured_data_errors} unparseable"
+                if meta.structured_data_errors
+                else ""
+            )
+            lines.append(_line("Structured", types + errors))
+        if meta.dates.published or meta.dates.modified:
+            lines.append(
+                _line(
+                    "Dates",
+                    f"published {meta.dates.published or '—'} · modified {meta.dates.modified or '—'}",
+                )
+            )
+    if meta.llms_txt:
+        probes = " · ".join(
+            f"{p.url.split('://', 1)[-1]} "
+            + (f"found ({p.links} links)" if p.found else str(p.http_status or "no response"))
+            for p in meta.llms_txt
+        )
+        lines.append(_line("llms.txt", probes))
+
+    lines += ["", "FINDINGS"]
+    width = max(len(f.key) for f in result.findings) if result.findings else 0
+    for finding in result.findings:
+        mark = STATUS_MARK.get(finding.status, "?")
+        head = f"  {mark} {finding.key:<{width}}  {finding.status:<14} {finding.severity:<6} {finding.evidence_level}"
+        lines.append(head.rstrip())
+        for item in finding.items:
+            lines.append(f"      {item.summary}")
+        if finding.status in ("not_applicable", "error") and finding.reason:
+            lines.append(f"      {finding.reason}")
+    lines += ["", f"Run {run_id}"]
+    return "\n".join(lines)
+
+
+def render_audit_run(run: Run) -> str:
+    if isinstance(run.result, AuditResult):
+        return render_audit(run.result, run.id)
+    if run.error:
+        return "\n".join(
+            [
+                f"{run.input.get('url', '')}",
+                f"✗  {run.error.code}",
+                run.error.message,
+                f"Retryable: {'yes' if run.error.retryable else 'no'}",
+                f"Run {run.id}",
+            ]
+        )
+    return f"{run.input.get('url', '')}\n…  {run.status}\nRun {run.id}"
+
+
+def wait_for_run(client: Client, run_id: str, *, timeout: float) -> Run:
+    deadline = time.monotonic() + timeout
+    while True:
+        remaining = deadline - time.monotonic()
+        run = client.get_run(run_id, wait=max(0, min(30, int(remaining))))
+        if run.status in TERMINAL_RUN_STATUSES:
+            return run
+        if time.monotonic() >= deadline:
+            raise DromadError(
+                "timeout",
+                f"Run {run_id} is still running after {timeout:g}s. It continues; "
+                f"check it with `dromad runs show {run_id}`.",
+                retryable=True,
+            )
+
+
+def audit(
+    url: str = typer.Argument(..., help="The page to audit."),
+    wait: bool = typer.Option(True, "--wait/--no-wait", help="Wait for the result (default)."),
+    timeout: int = typer.Option(180, "--timeout", help="Seconds to wait."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document to stdout."),
+) -> None:
+    """Fetch one page as a crawler would and report its facts and findings.
+
+    Every finding says how strongly it is backed (evidence_level): an observed
+    fact, an established consequence, a suggestive signal, or an experimental
+    hypothesis. The result is a run (dr_…) that keeps the full captured page.
+    """
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        run = client.create_audit(url)
+        if wait:
+            info(f"Auditing {url} · run {run.id}")
+            run = wait_for_run(client, run.id, timeout=timeout)
+    if as_json:
+        if isinstance(run.result, AuditResult):
+            emit_json(AuditReport(run_id=run.id, **run.result.model_dump()))
+        else:
+            emit_json(run)
+    else:
+        typer.echo(render_audit_run(run))
+    if run.status == "failed":
+        raise typer.Exit(int(ExitCode.FAILURE))

dromad-0.1.0/src/dromad/cli/auth.py

@@ -0,0 +1,136 @@
+"""``dromad login``, ``dromad logout``, ``dromad whoami``."""
+
+import os
+import socket
+import time
+import webbrowser
+from datetime import UTC, datetime
+
+import typer
+
+from dromad import config
+from dromad.cli.output import emit_json, errors_reported, info
+from dromad.client import Client
+from dromad.client.errors import ApiError, ConnectionFailed, DromadError
+from dromad.schemas.auth import CLIAuthStatus
+
+# Indirection so tests can run the polling loop without waiting.
+_sleep = time.sleep
+_monotonic = time.monotonic
+
+JSON_OPTION = typer.Option(False, "--json", help="Print one JSON document to stdout.")
+
+
+def _default_client_name() -> str:
+    return f"dromad CLI on {socket.gethostname()}"
+
+
+def login(
+    api_url: str | None = typer.Option(
+        None, "--api-url", help="Dromad server (default: DROMAD_API_URL, else dromad.dev)."
+    ),
+    name: str | None = typer.Option(
+        None, "--name", help="How this device appears under your account's sessions."
+    ),
+    no_browser: bool = typer.Option(
+        False, "--no-browser", help="Print the sign-in URL instead of opening it."
+    ),
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Sign in through the browser and store a CLI token for this device."""
+    with errors_reported(as_json=as_json):
+        settings = config.resolve(api_url)
+        with Client(settings.api_url, token=None) as client:
+            start = client.cli_auth_start(name or _default_client_name())
+            info("To sign in, open this URL in a browser:")
+            info(f"\n  {start.verification_uri_complete}\n")
+            info(f"and check that it shows the code  {start.user_code}\n")
+            if not no_browser:
+                try:
+                    webbrowser.open(start.verification_uri_complete)
+                except webbrowser.Error:
+                    pass
+            info("Waiting for approval…")
+
+            deadline = _monotonic() + start.expires_in
+            while True:
+                _sleep(start.interval)
+                poll = client.cli_auth_poll(start.device_code)
+                if poll.status == CLIAuthStatus.APPROVED and poll.token and poll.token_id:
+                    break
+                if poll.status == CLIAuthStatus.DENIED:
+                    raise DromadError("access_denied", "Sign-in was denied in the browser.")
+                if poll.status != CLIAuthStatus.PENDING or _monotonic() > deadline:
+                    raise DromadError(
+                        "expired_token",
+                        "The sign-in request expired before it was approved. "
+                        "Run `dromad login` again.",
+                    )
+
+        path = config.save_credentials(
+            config.StoredCredentials(
+                api_url=settings.api_url,
+                token=poll.token,
+                token_id=poll.token_id,
+                email=poll.email or "",
+                created_at=datetime.now(UTC),
+            )
+        )
+    if as_json:
+        emit_json({"email": poll.email, "token_id": poll.token_id, "api_url": settings.api_url})
+    else:
+        info(f"Logged in as {poll.email}.")
+        info(f"Credentials saved to {path}")
+
+
+def logout(as_json: bool = JSON_OPTION) -> None:
+    """Revoke this device's CLI token and delete the local credentials."""
+    with errors_reported(as_json=as_json):
+        stored = config.load_credentials()
+        revoked = False
+        if stored is not None:
+            try:
+                with Client(stored.api_url, stored.token) as client:
+                    client.revoke_cli_token()
+                revoked = True
+            except ApiError as exc:
+                # Already revoked or expired server-side: nothing left to undo.
+                if exc.status != 401:
+                    raise
+            except ConnectionFailed:
+                info(
+                    f"Could not reach {stored.api_url} to revoke the token; "
+                    "removing the local credentials anyway. Revoke it from "
+                    "your account's sessions page."
+                )
+            config.delete_credentials()
+    env_key_set = bool(os.environ.get(config.ENV_API_KEY))
+    if as_json:
+        emit_json(
+            {
+                "logged_out": stored is not None,
+                "token_revoked": revoked,
+                "api_key_env_set": env_key_set,
+            }
+        )
+        return
+    info("Logged out." if stored is not None else "Not logged in.")
+    if env_key_set:
+        info(f"{config.ENV_API_KEY} is still set; unset it to stop using that key.")
+
+
+def whoami(
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = JSON_OPTION,
+) -> None:
+    """Show which account and credential the CLI is using."""
+    with errors_reported(as_json=as_json):
+        settings = config.resolve(api_url)
+        with Client.from_settings(settings) as client:
+            me = client.me()
+    if as_json:
+        emit_json(me)
+        return
+    typer.echo(me.email)
+    typer.echo(f"{me.credential.kind} {me.credential.id} ({me.credential.name})")
+    typer.echo(f"source {settings.source} · {settings.api_url}")

dromad-0.1.0/src/dromad/cli/citations.py

@@ -0,0 +1,133 @@
+"""``dromad citations`` — what a set of prompt runs cited, counted."""
+
+import typer
+
+from dromad import config
+from dromad.cli.output import emit_json, errors_reported, table
+from dromad.cli.render import short_url
+from dromad.client import Client
+from dromad.schemas.analyses import CitationAnalysis
+from dromad.schemas.ids import IdKind, is_id
+
+
+def _pct(numerator: int, denominator: int) -> str:
+    return f"{round(100 * numerator / denominator)}%" if denominator else "–"
+
+
+def _n(count: int, noun: str) -> str:
+    return f"{count} {noun}{'' if count == 1 else 's'}"
+
+
+def render_citations(analysis: CitationAnalysis, *, top: int = 10) -> str:
+    t = analysis.totals
+    lines = [
+        f"{t.runs} prompt runs · {t.prompts} prompts · {t.engines} engines",
+        f"{t.citations} citations · {t.unique_cited_urls} unique URLs · "
+        f"{t.unique_cited_domains} unique domains",
+    ]
+    unknowns = []
+    if t.retrieved_not_cited:
+        unknowns.append(f"{t.retrieved_not_cited} sources seen but not cited")
+    if t.citation_status_unknown:
+        unknowns.append(f"{t.citation_status_unknown} with citation status unknown")
+    if t.unresolved_sources:
+        unknowns.append(f"{t.unresolved_sources} unresolved redirects")
+    if unknowns:
+        lines.append(" · ".join(unknowns))
+
+    if analysis.domains:
+        rows = [
+            [d.domain, d.citations, d.pages, d.runs, d.prompts, ", ".join(d.engines)]
+            for d in analysis.domains[:top]
+        ]
+        lines += ["", table(rows, ["DOMAIN", "CITATIONS", "PAGES", "RUNS", "PROMPTS", "ENGINES"])]
+
+    if len(analysis.engines) > 1:
+        rows = [
+            [e.engine, e.runs, e.runs_with_citations, e.citations, e.unique_cited_domains]
+            for e in analysis.engines
+        ]
+        lines += ["", table(rows, ["ENGINE", "RUNS", "WITH CITATIONS", "CITATIONS", "DOMAINS"])]
+
+    if analysis.pages:
+        lines += ["", "TOP PAGES"]
+        for n, page in enumerate(analysis.pages[:top], 1):
+            lines.append(
+                f"  {n:>2}  {short_url(page.url, 70)}  · {_n(page.citations, 'citation')} · "
+                f"{_n(page.runs, 'run')} · {', '.join(page.engines)}"
+            )
+
+    overlap = analysis.overlap
+    if overlap.engines > 1:
+        by = overlap.domains_by_engine_count
+        parts = [f"by {n}: {by[str(n)]}" for n in range(overlap.engines, 0, -1)]
+        lines += ["", "CROSS-ENGINE OVERLAP", "  cited domains " + " · ".join(parts)]
+        if overlap.domains_cited_by_every_engine:
+            lines.append(
+                "  cited by every engine: " + ", ".join(overlap.domains_cited_by_every_engine)
+            )
+
+    if analysis.textual_mentions:
+        lines += ["", "TEXTUAL MENTIONS  (naive whole-word match in answer text)"]
+        for m in analysis.textual_mentions:
+            lines.append(
+                f"  {m.term}  {m.runs_mentioning} of {m.runs} runs · "
+                f"{m.prompts_mentioning} of {m.prompts} prompts · {m.occurrences} occurrences"
+            )
+
+    for c in analysis.domain_coverage:
+        engines = " · ".join(f"{e.engine} {e.cited_runs}/{e.runs}" for e in c.by_engine)
+        lines += [
+            "",
+            f"DOMAIN COVERAGE  {c.domain}",
+            f"  cited in {c.cited_runs} of {c.runs} runs ({_pct(c.cited_runs, c.runs)}) · "
+            f"{c.cited_prompts} of {c.prompts} prompts · {c.citations} citations",
+            f"  by engine: {engines}",
+        ]
+        if c.unknown_runs:
+            lines.append(
+                f"  {_n(c.unknown_runs, 'run')} did not expose citations; the rate is a floor"
+            )
+        if c.pages:
+            lines.append(f"  pages cited: {', '.join(short_url(p, 60) for p in c.pages[:top])}")
+        if c.prompts_seen_not_cited:
+            lines.append(f"  seen but not cited on {_n(len(c.prompts_seen_not_cited), 'prompt')}")
+        if c.prompts_absent:
+            lines.append(
+                f"  absent from {_n(len(c.prompts_absent), 'prompt')}, e.g. “{c.prompts_absent[0]}”"
+            )
+
+    if analysis.excluded_runs:
+        lines += ["", f"Excluded {len(analysis.excluded_runs)} runs:"]
+        lines += [f"  {e.run_id}  {e.reason}" for e in analysis.excluded_runs]
+    lines += ["", f"Analysis {analysis.id} · {analysis.method}"]
+    return "\n".join(lines)
+
+
+def citations(
+    ids: list[str] = typer.Argument(..., help="Run IDs (dr_…) and/or batch IDs (rq_…)."),
+    brand: list[str] = typer.Option(
+        [], "--brand", "-b", help="A term to count in answers (repeatable). Naive word match."
+    ),
+    domain: list[str] = typer.Option(
+        [], "--domain", "-d", help="A domain to report coverage for (repeatable)."
+    ),
+    top: int = typer.Option(10, "--top", min=1, help="Rows per table."),
+    api_url: str | None = typer.Option(None, "--api-url", help="Dromad server."),
+    as_json: bool = typer.Option(False, "--json", help="Print one JSON document to stdout."),
+) -> None:
+    """Count what a set of prompt runs cited: domains, pages, engines, overlap.
+
+    Only citations an engine showed are counted; sources whose citation
+    status was not exposed are reported as unknown. The result is a durable
+    analysis (ca_…).
+    """
+    bad = [i for i in ids if not is_id(i, IdKind.RUN, IdKind.REQUEST_BATCH)]
+    if bad:
+        raise typer.BadParameter(f"not a run or batch ID: {', '.join(bad)}", param_hint="IDS")
+    with errors_reported(as_json=as_json), Client.from_settings(config.resolve(api_url)) as client:
+        analysis = client.create_citation_analysis(ids, brands=brand, domains=domain)
+    if as_json:
+        emit_json(analysis)
+    else:
+        typer.echo(render_citations(analysis, top=top))

dromad-0.1.0/src/dromad/cli/exit_codes.py

@@ -0,0 +1,14 @@
+"""Process exit codes. Stable: scripts and agents branch on them.
+
+0  the command did what it was asked
+1  the operation failed (the server refused it, an engine failed, no connection)
+2  the command could not be attempted (bad arguments, not logged in, bad config)
+"""
+
+from enum import IntEnum
+
+
+class ExitCode(IntEnum):
+    OK = 0
+    FAILURE = 1
+    USAGE = 2