medawar 0.1.0__tar.gz

medawar-0.1.0/.gitignore

@@ -0,0 +1,11 @@
+.venv
+**/__pycache__/**
+*.pyc
+.pytest_cache/
+.env
+
+# agent-core copy for the Docker build (scripts/fetch-agent-core.sh)
+.agent-core/
+
+# Local credentials (service-account keys): never committed
+secrets/

medawar-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: medawar
+Version: 0.1.0
+Summary: Review your scientific papers from the terminal with Medawar
+Project-URL: Homepage, https://medawar.science
+Project-URL: Documentation, https://medawar.science/docs/cli/
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: pdf
+Requires-Dist: weasyprint>=62; extra == 'pdf'
+Description-Content-Type: text/markdown
+
+# Medawar CLI
+
+Review your scientific paper from the terminal with
+[Medawar](https://medawar.science): structure, abstract, language, references,
+statistics, ethics statements and more, with each finding located in your text.
+
+```bash
+pip install medawar        # or: uv tool install medawar / pipx install medawar
+
+medawar login                       # approve in your browser
+medawar review paper.pdf            # every check
+medawar review ./latex-project --only title,abstract --report review.html
+medawar findings paper.pdf          # cached results, no network
+medawar skills                      # the checks, and what each costs
+medawar expert-review paper.pdf     # independent human reviewers (asks first)
+medawar expert-review status        # where your expert reviews stand
+```
+
+Papers can be a PDF or Word file, a `.tex` file or LaTeX project directory,
+Markdown, or an Overleaf project (`overleaf://<id>` or its URL). LaTeX,
+Markdown and Overleaf projects are parsed on your machine; PDF and Word files
+are uploaded and read by the review engine.
+
+Extractions and reviews are cached locally (`medawar cache path`), so running
+one more check never re-uploads or re-reads the paper.
+
+PDF reports (`--report review.pdf`) need `pip install "medawar[pdf]"`;
+`.html` reports work out of the box.
+
+Reviews use your Medawar plan's credits: a free trial covers one full review.
+Plans, credits and the full documentation: <https://medawar.science/docs/cli/>.

medawar-0.1.0/medawar/README.md

@@ -0,0 +1,31 @@
+# Medawar CLI
+
+Review your scientific paper from the terminal with
+[Medawar](https://medawar.science): structure, abstract, language, references,
+statistics, ethics statements and more, with each finding located in your text.
+
+```bash
+pip install medawar        # or: uv tool install medawar / pipx install medawar
+
+medawar login                       # approve in your browser
+medawar review paper.pdf            # every check
+medawar review ./latex-project --only title,abstract --report review.html
+medawar findings paper.pdf          # cached results, no network
+medawar skills                      # the checks, and what each costs
+medawar expert-review paper.pdf     # independent human reviewers (asks first)
+medawar expert-review status        # where your expert reviews stand
+```
+
+Papers can be a PDF or Word file, a `.tex` file or LaTeX project directory,
+Markdown, or an Overleaf project (`overleaf://<id>` or its URL). LaTeX,
+Markdown and Overleaf projects are parsed on your machine; PDF and Word files
+are uploaded and read by the review engine.
+
+Extractions and reviews are cached locally (`medawar cache path`), so running
+one more check never re-uploads or re-reads the paper.
+
+PDF reports (`--report review.pdf`) need `pip install "medawar[pdf]"`;
+`.html` reports work out of the box.
+
+Reviews use your Medawar plan's credits: a free trial covers one full review.
+Plans, credits and the full documentation: <https://medawar.science/docs/cli/>.

medawar-0.1.0/medawar/cache.py

@@ -0,0 +1,117 @@
+"""Local cache of papers, extractions and reviews, keyed by content hash.
+
+Layout under the cache dir (platformdirs user_cache_dir("medawar")):
+
+    papers/<content_hash>/
+        meta.json          source path, kind, title, extraction_id, timestamps
+        payload.json       engine extraction payload
+        reviews/<key>.json one review (engine Review JSON + fetched_at),
+                           key = "all" or the sorted requested skills joined by "+"
+
+A cached payload means `review --only x` never re-uploads or re-extracts.
+"""
+from __future__ import annotations
+
+import json
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from medawar.engine.models import Finding, Review
+
+ALL_SKILLS_KEY = "all"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def review_key(skills: list[str] | None) -> str:
+    return "+".join(sorted(set(skills))) if skills else ALL_SKILLS_KEY
+
+
+def _write_json(path: Path, data: Any) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")
+    tmp.replace(path)
+
+
+def _read_json(path: Path) -> Any | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+
+class PaperCache:
+    """One paper's entry."""
+
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    @property
+    def exists(self) -> bool:
+        return (self.root / "meta.json").exists()
+
+    def meta(self) -> dict[str, Any]:
+        return _read_json(self.root / "meta.json") or {}
+
+    def update_meta(self, **fields: Any) -> None:
+        meta = self.meta()
+        meta.setdefault("created_at", _now())
+        meta.update(fields, updated_at=_now())
+        _write_json(self.root / "meta.json", meta)
+
+    @property
+    def extraction_id(self) -> int | str | None:
+        return self.meta().get("extraction_id")
+
+    def payload(self) -> dict[str, Any] | None:
+        return _read_json(self.root / "payload.json")
+
+    def save_extraction(self, payload: dict[str, Any], extraction_id: int | str | None) -> None:
+        _write_json(self.root / "payload.json", payload)
+        self.update_meta(extraction_id=extraction_id, title=payload.get("title"))
+
+    def save_review(self, review: Review, skills: list[str] | None) -> Path:
+        path = self.root / "reviews" / f"{review_key(skills)}.json"
+        _write_json(path, {"fetched_at": _now(), "review": review.model_dump(mode="json")})
+        return path
+
+    def reviews(self) -> list[tuple[str, Review]]:
+        """Cached reviews, oldest first."""
+        entries = []
+        for path in (self.root / "reviews").glob("*.json"):
+            data = _read_json(path)
+            if data and "review" in data:
+                entries.append((data.get("fetched_at", ""), Review.model_validate(data["review"])))
+        return sorted(entries, key=lambda e: e[0])
+
+    def merged_findings(self) -> tuple[list[Finding], list[str]]:
+        """Each skill's findings from the newest review that ran it, so
+        `review --only x` refreshes x without hiding the other skills.
+        Returns (findings, skills covered)."""
+        latest_by_skill: dict[str, Review] = {}
+        for _, review in self.reviews():
+            if review.status != "completed":
+                continue
+            for skill in review.skills_run() or review.skills_requested or []:
+                latest_by_skill[skill] = review
+        findings = [
+            f for skill, review in latest_by_skill.items()
+            for f in review.findings if f.skill == skill
+        ]
+        return findings, sorted(latest_by_skill)
+
+
+class LocalCache:
+    def __init__(self, root: Path) -> None:
+        self.root = root
+
+    def paper(self, content_hash: str) -> PaperCache:
+        return PaperCache(self.root / "papers" / content_hash)
+
+    def clear(self) -> None:
+        shutil.rmtree(self.root / "papers", ignore_errors=True)

medawar-0.1.0/medawar/cli/__init__.py

@@ -0,0 +1 @@
+"""User-facing commands that work on papers through medawar-api."""

medawar-0.1.0/medawar/cli/commands.py

@@ -0,0 +1,429 @@
+"""Paper commands of the `medawar` CLI: login, skills, extract, review,
+findings, cache. They talk to medawar-api (MEDAWAR_API_URL), which proxies
+the CMM engine, and keep extractions and reviews in the local cache.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import webbrowser
+from pathlib import Path
+
+import httpx
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from medawar.cache import LocalCache
+from medawar.cli import device_login
+from medawar.cli.credentials import credentials_path, load_token, save_token
+from medawar.config import get_medawar_settings
+from medawar.engine.client import EngineClient, EngineError
+from medawar.engine.flow import ReviewRunner
+from medawar.engine.models import SEVERITIES, Finding, Progress, Review
+from medawar.papers.errors import PaperError
+from medawar.papers.overleaf import OverleafAuth
+from medawar.papers.prepare import PreparedPaper, prepare
+from medawar.papers.sources import resolve
+from medawar.report import ReportError, write_report
+
+console = Console()
+err_console = Console(stderr=True)
+
+_SEVERITY_STYLE = {"critical": "bold red", "major": "yellow", "minor": "dim"}
+
+
+def make_client() -> EngineClient:
+    """Engine client for medawar-api with the user's token. Tests patch this."""
+    token = load_token()
+    if not token:
+        err_console.print("[red]Not logged in.[/red] Run `medawar login` first.")
+        raise typer.Exit(1)
+    settings = get_medawar_settings()
+    return EngineClient.for_user(
+        settings.medawar_api_url, token, timeout=settings.engine_http_timeout_s
+    )
+
+
+def make_api_client() -> httpx.Client:
+    """medawar-api client with the user's token, for the account routes the
+    engine client does not cover (expert reviews). Tests patch this."""
+    token = load_token()
+    if not token:
+        err_console.print("[red]Not logged in.[/red] Run `medawar login` first.")
+        raise typer.Exit(1)
+    settings = get_medawar_settings()
+    return httpx.Client(base_url=settings.medawar_api_url.rstrip("/"),
+                        headers={"Authorization": f"Bearer {token}"},
+                        timeout=settings.engine_http_timeout_s)
+
+
+def make_login_client() -> httpx.Client:
+    """Unauthenticated client for the login endpoints. Tests patch this."""
+    return httpx.Client(base_url=get_medawar_settings().medawar_api_url.rstrip("/"), timeout=30)
+
+
+def make_cache() -> LocalCache:
+    return LocalCache(get_medawar_settings().cache_dir())
+
+
+def _fail(message: str) -> typer.Exit:
+    err_console.print(f"[red]{message}[/red]")
+    return typer.Exit(1)
+
+
+def _engine_fail(e: PaperError | EngineError) -> typer.Exit:
+    if isinstance(e, EngineError) and e.status_code == 401:
+        return _fail(f"{e}. Run `medawar login` again.")
+    return _fail(str(e))
+
+
+def _parse_only(only: str | None) -> list[str] | None:
+    skills = [s.strip() for s in (only or "").split(",") if s.strip()]
+    return skills or None
+
+
+def _prepared(path: Path) -> PreparedPaper:
+    try:
+        return prepare(path)
+    except PaperError as e:
+        raise _fail(str(e))
+
+
+def _print_findings(title: str | None, findings: list[Finding], skills: list[str]) -> None:
+    counts = {sev: sum(1 for f in findings if f.severity == sev) for sev in SEVERITIES}
+    console.print(f"\n[bold]{title or '(untitled manuscript)'}[/bold]")
+    console.print(
+        f"{len(findings)} findings: [bold red]{counts['critical']} critical[/bold red], "
+        f"[yellow]{counts['major']} major[/yellow], {counts['minor']} minor "
+        f"[dim]({len(skills)} checks: {', '.join(skills)})[/dim]\n"
+    )
+    for f in sorted(findings, key=lambda x: (SEVERITIES.index(x.severity), x.skill)):
+        style = _SEVERITY_STYLE[f.severity]
+        where = f" [dim]{f.location}[/dim]" if f.location else ""
+        tags = f" [magenta]{', '.join(f.tags)}[/magenta]" if f.tags else ""
+        console.print(f"[{style}]{f.severity.upper():8}[/{style}] [cyan]{f.skill}[/cyan]{where}{tags}")
+        if f.quote:
+            console.print(f"         [italic]\"{f.quote}\"[/italic]")
+        if f.explanation:
+            console.print(f"         {f.explanation}")
+        if f.suggestion:
+            console.print(f"         [green]-> {f.suggestion}[/green]")
+
+
+def _write_report(review: Review, out: Path, findings=None, skills=None) -> None:
+    try:
+        written = write_report(review, out, findings=findings, skills=skills)
+    except ReportError as e:
+        err_console.print(f"[yellow]{e}[/yellow]")
+        return
+    err_console.print(f"Report written to {written}")
+
+
+def _progress_printer(status):
+    def on_progress(job_status: str, progress: Progress | None) -> None:
+        detail = ""
+        if progress is not None and progress.percentage is not None:
+            detail = f" {progress.percentage:.0f}%"
+        if progress is not None and progress.message:
+            detail += f" {progress.message}"
+        status.update(f"{job_status}{detail}")
+    return on_progress
+
+
+async def _with_runner(coro_factory):
+    settings = get_medawar_settings()
+    with err_console.status("contacting medawar-api") as status:
+        async with make_client() as client:
+            runner = ReviewRunner(
+                client, cache=make_cache(), timeout=settings.engine_poll_timeout_s,
+                on_progress=_progress_printer(status),
+            )
+            return await coro_factory(runner)
+
+
+def _device_login() -> str:
+    with make_login_client() as client:
+        try:
+            grant = device_login.start(client)
+            console.print(
+                f"\nOpen [cyan]{grant.verification_uri}[/cyan] and enter the code "
+                f"[bold]{grant.user_code}[/bold]\n(or open {grant.verification_uri_complete})\n"
+            )
+            webbrowser.open(grant.verification_uri_complete)
+            with console.status("Waiting for you to approve the login in your browser..."):
+                return device_login.wait_for_token(client, grant)
+        except device_login.LoginError as e:
+            raise _fail(str(e))
+
+
+def login(
+    service: str = typer.Argument("medawar", help="'medawar' (your account) or 'overleaf'."),
+    token: str | None = typer.Option(None, "--token", help="API token (medawar only)."),
+) -> None:
+    """Sign in to Medawar (in your browser), or store Overleaf access."""
+    if service == "medawar":
+        value = token.strip() if token is not None else _device_login()
+        if not value:
+            raise _fail("Nothing stored.")
+        path = save_token(value)
+        console.print(f"[green]Signed in.[/green] Token saved to {path} (mode 0600)")
+        return
+    if service != "overleaf":
+        raise _fail(f"Unknown service: {service}. Use 'medawar' or 'overleaf'.")
+    existing = OverleafAuth.load()
+    console.print(
+        "\n[bold cyan]Overleaf credentials[/bold cyan]\n\n"
+        "Two transports are supported, in order:\n"
+        "  1. Git Bridge (preferred). Create a token at\n"
+        "     https://www.overleaf.com/user/settings, Account, Git Authentication Tokens.\n"
+        "  2. Zip download (fallback). Copy your [cyan]overleaf_session2[/cyan] cookie\n"
+        "     from a logged-in browser session. Lasts as long as the cookie does.\n\n"
+        "Press Enter to leave a field unchanged.\n"
+    )
+    git_input = console.input(
+        f"  Git Bridge token [dim]{'(keep)' if existing.git_token else '(none)'}[/dim]: "
+    ).strip()
+    cookie_input = console.input(
+        f"  Session cookie [dim]{'(keep)' if existing.session_cookie else '(none)'}[/dim]: "
+    ).strip()
+    new_git = git_input or existing.git_token
+    new_cookie = cookie_input or existing.session_cookie
+    if not new_git and not new_cookie:
+        raise _fail("Nothing stored. At least one of the two is required.")
+    path = OverleafAuth(git_token=new_git, session_cookie=new_cookie).save()
+    console.print(f"\n[green]Saved.[/green] {path} (mode 0600)")
+
+
+def skills() -> None:
+    """List the review checks the engine can run."""
+
+    async def run():
+        async with make_client() as client:
+            return await client.list_skills()
+
+    try:
+        catalog = asyncio.run(run())
+    except EngineError as e:
+        raise _engine_fail(e)
+    table = Table("name", "description", "depends on", "credits")
+    for s in catalog:
+        table.add_row(s.name, s.description or "", ", ".join(s.depends_on),
+                      "" if s.credits is None else str(s.credits))
+    console.print(table)
+
+
+def extract(
+    paper: str = typer.Argument(..., help="File, LaTeX project directory, or Overleaf URL."),
+) -> None:
+    """Extract a paper once and cache the result; later reviews reuse it."""
+    try:
+        with resolve(paper) as path:
+            prepared = _prepared(path)
+            payload, extraction_id = asyncio.run(_with_runner(lambda r: r.extract(prepared)))
+    except (PaperError, EngineError) as e:
+        raise _engine_fail(e)
+    console.print(f"[bold]{payload.get('title') or '(untitled manuscript)'}[/bold]")
+    console.print(
+        f"{len(payload.get('sections') or [])} sections, "
+        f"{len(payload.get('references') or [])} references, "
+        f"{len(payload.get('visual_elements') or [])} figures/tables"
+    )
+    source = f"engine extraction {extraction_id}" if extraction_id else "parsed locally"
+    console.print(f"[dim]{source}; cached as {prepared.content_hash[:12]}[/dim]")
+
+
+def review(
+    paper: str = typer.Argument(..., help="File, LaTeX project directory, or Overleaf URL."),
+    only: str | None = typer.Option(None, "--only", help="Comma-separated checks, e.g. title,abstract."),
+    as_json: bool = typer.Option(False, "--json", help="Print the engine review as JSON."),
+    report: Path | None = typer.Option(None, "--report", help="Write an .html or .pdf report."),
+) -> None:
+    """Review a paper (all checks, or --only some), reusing its cached extraction."""
+    skill_list = _parse_only(only)
+    try:
+        with resolve(paper) as path:
+            prepared = _prepared(path)
+            result = asyncio.run(_with_runner(lambda r: r.review(prepared, skill_list)))
+    except (PaperError, EngineError) as e:
+        raise _engine_fail(e)
+    if as_json:
+        console.print_json(json.dumps(result.model_dump(mode="json")))
+    elif result.status != "completed":
+        raise _fail(f"Review {result.status}: {result.error or 'unknown error'}")
+    else:
+        _print_findings(result.title, result.findings, result.skills_run())
+        if result.unavailable_reviews:
+            console.print(f"[yellow]Not available right now: "
+                          f"{', '.join(result.unavailable_reviews)}[/yellow]")
+    if report is not None and result.status == "completed":
+        _write_report(result, report)
+    if result.status != "completed":
+        raise typer.Exit(1)
+
+
+def findings(
+    paper: str = typer.Argument(..., help="File or LaTeX project directory reviewed before."),
+    as_json: bool = typer.Option(False, "--json"),
+    report: Path | None = typer.Option(None, "--report", help="Write an .html or .pdf report."),
+) -> None:
+    """Show cached findings: each check's newest result, no network call."""
+    try:
+        with resolve(paper) as path:
+            prepared = _prepared(path)
+    except PaperError as e:
+        raise _fail(str(e))
+    entry = make_cache().paper(prepared.content_hash)
+    reviews = [r for _, r in entry.reviews() if r.status == "completed"]
+    if not reviews:
+        raise _fail("No cached review for this paper. Run `medawar review` first.")
+    merged, covered = entry.merged_findings()
+    latest = reviews[-1]
+    if as_json:
+        console.print_json(json.dumps(
+            {"title": latest.title, "skills": covered,
+             "findings": [f.model_dump(mode="json") for f in merged]}
+        ))
+    else:
+        _print_findings(latest.title, merged, covered)
+    if report is not None:
+        _write_report(latest, report, findings=merged, skills=covered)
+
+
+def cache(
+    action: str = typer.Argument("path", help="'path' or 'clear'."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Clear without asking."),
+) -> None:
+    """Show where the cache lives, or clear it."""
+    local = make_cache()
+    if action == "path":
+        console.print(str(local.root))
+        console.print(f"[dim]credentials: {credentials_path()}[/dim]")
+        return
+    if action != "clear":
+        raise _fail(f"Unknown action: {action}. Use 'path' or 'clear'.")
+    if not yes and not typer.confirm(f"Delete every cached paper under {local.root}?"):
+        raise typer.Exit(1)
+    local.clear()
+    console.print("[green]Cache cleared.[/green]")
+
+
+# Expert reviews: independent human reviewers, double-blind (medawar-api
+# /v1/expert-reviews). Reviewers read PDF and Word files only.
+_EXPERT_REVIEW_SUFFIXES = (".pdf", ".docx", ".doc")
+_EXPERT_STATUS = {
+    "pending_payment": "waiting for payment",
+    "submitting": "sending to the reviewers",
+    "submitted": "received",
+    "analyzing": "reading the manuscript",
+    "matching_reviewers": "finding reviewers",
+    "inviting": "inviting reviewers",
+    "in_review": "in review",
+    "reviews_ready": "reviews ready",
+    "failed": "failed",
+}
+
+
+def _api_error(response: httpx.Response) -> str:
+    try:
+        detail = response.json().get("detail")
+    except ValueError:
+        return f"medawar-api answered {response.status_code}"
+    if isinstance(detail, dict):
+        return detail.get("error") or str(detail)
+    return str(detail or f"medawar-api answered {response.status_code}")
+
+
+def _api(client: httpx.Client, method: str, url: str, **kwargs) -> dict:
+    try:
+        response = client.request(method, url, **kwargs)
+    except httpx.HTTPError as e:
+        raise _fail(f"Could not reach medawar-api: {e}")
+    if response.status_code >= 400:
+        raise _fail(_api_error(response))
+    return response.json()
+
+
+def _request_expert_review(client: httpx.Client, paper: Path, yes: bool) -> None:
+    if not paper.is_file():
+        raise _fail(f"Not a file: {paper}")
+    if paper.suffix.lower() not in _EXPERT_REVIEW_SUFFIXES:
+        raise _fail("Expert reviewers read PDF and Word files: export your manuscript to PDF.")
+    offer = _api(client, "GET", "/v1/expert-reviews/offer")
+    if offer["mode"] in ("upgrade", "unavailable"):
+        raise _fail(offer.get("reason") or "Expert reviews are not available.")
+    console.print("\n[bold]Expert review[/bold]: independent human reviewers read your manuscript.\n")
+    for point in offer["consent"]["points"]:
+        console.print(f"  - {point}")
+    if offer["mode"] == "included":
+        console.print(f"\nIncluded in your plan ({offer['included_left']} left this period).")
+    else:
+        console.print(f"\nPrice: {offer['price']['display']}, paid by card on a Stripe page.")
+    if not yes and not typer.confirm("\nDo you agree and want to go ahead?"):
+        raise typer.Exit(1)
+    with open(paper, "rb") as fh:
+        upload = _api(client, "POST", "/v1/uploads", files={"file": (paper.name, fh)})
+    request = _api(client, "POST", "/v1/expert-reviews",
+                   json={"upload_path": upload["path"], "consent": True})
+    if request.get("checkout_url"):
+        console.print(f"\nPay here to start it: {request['checkout_url']}")
+        webbrowser.open(request["checkout_url"])
+    else:
+        console.print("\n[green]Requested.[/green] We email you when the reviews are ready.")
+    console.print(f"Follow it: medawar expert-review status {request['id']}")
+
+
+def _print_expert_review(item: dict) -> None:
+    console.print(f"[bold]{item.get('title') or item['filename']}[/bold]  "
+                  f"[dim]{item['id']}[/dim]")
+    console.print(f"Status: {_EXPERT_STATUS.get(item['status'], item['status'])}")
+    if item.get("error"):
+        console.print(f"[yellow]{item['error']}[/yellow]")
+    counts = item.get("counts")
+    if counts:
+        console.print(f"Reviewers: {counts['invited']} invited, {counts['accepted']} accepted, "
+                      f"{counts['completed']} finished")
+    if item.get("summary_markdown"):
+        console.print(f"\n[bold]Summary[/bold]\n{item['summary_markdown']}")
+    for review in item.get("reviews") or []:
+        console.print(f"\n[bold]{review['reviewer']}[/bold]"
+                      + (" [dim](late)[/dim]" if review["late"] else ""))
+        for comment in review["comments"]:
+            if comment["quote"]:
+                console.print(f"  [dim]> {comment['quote']}[/dim]")
+            console.print(f"  {comment['comment']}")
+    publication = item.get("publication")
+    if publication and publication["eligible"] and not publication["published_url"]:
+        console.print(f"\nThe reviewers endorse it: you may publish it with its reviews on "
+                      f"our partner's public journal: {publication['publish_url']}")
+
+
+def expert_review(
+    target: str = typer.Argument(..., help="A PDF or Word manuscript, or 'status'."),
+    review_id: str | None = typer.Argument(None, help="With 'status': one request's id."),
+    yes: bool = typer.Option(False, "--yes", "-y", help="Agree without asking."),
+) -> None:
+    """Ask independent human expert reviewers to review a manuscript, or follow requests."""
+    with make_api_client() as client:
+        if target != "status":
+            _request_expert_review(client, Path(target), yes)
+            return
+        if review_id:
+            _print_expert_review(_api(client, "GET", f"/v1/expert-reviews/{review_id}"))
+            return
+        items = _api(client, "GET", "/v1/expert-reviews")["expert_reviews"]
+    if not items:
+        console.print("No expert reviews yet.")
+        return
+    table = Table("Id", "Manuscript", "Status", "Updated")
+    for item in items:
+        table.add_row(item["id"], item.get("title") or item["filename"],
+                      _EXPERT_STATUS.get(item["status"], item["status"]),
+                      (item.get("updated_at") or "")[:10])
+    console.print(table)
+
+
+def register(app: typer.Typer) -> None:
+    for command in (login, skills, extract, review, findings, cache):
+        app.command()(command)
+    app.command("expert-review")(expert_review)

medawar-0.1.0/medawar/cli/credentials.py

@@ -0,0 +1,33 @@
+"""The user's medawar-api token, stored by `medawar login` (device flow, see
+medawar/cli/device_login.py, or `--token`)."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from medawar.config import get_medawar_settings
+
+
+def credentials_path() -> Path:
+    return get_medawar_settings().config_dir() / "credentials.json"
+
+
+def load_token() -> str | None:
+    """MEDAWAR_TOKEN wins over the stored token."""
+    settings = get_medawar_settings()
+    if settings.medawar_token:
+        return settings.medawar_token
+    path = credentials_path()
+    try:
+        return json.loads(path.read_text()).get("api_token") or None
+    except (OSError, ValueError):
+        return None
+
+
+def save_token(token: str) -> Path:
+    path = credentials_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps({"api_token": token}, indent=2))
+    os.chmod(path, 0o600)
+    return path