paperstack-cli 0.1.0__py3-none-any.whl

paperstack/cli.py

@@ -0,0 +1,779 @@
+"""Review critical reads and inspect source-backed paper records from one CLI.
+
+Review lookup uses a clone, `$PAPERSTACK_DIR`, or a GitHub-backed cache.
+Remote corpus access uses gh authentication without reading or storing its token.
+Exit codes: 0 hit, 1 no match, 2 ambiguous, 3 unavailable corpus.
+"""
+
+from __future__ import annotations
+
+import argparse
+import contextlib
+import fcntl
+import io
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+import tarfile
+import tempfile
+import time
+from pathlib import Path
+
+import yaml
+
+
+def warn(msg: str) -> None:
+    print(f"paperstack: {msg}", file=sys.stderr)
+
+
+FAIL = 3
+
+
+def die(msg: str, code: int = FAIL) -> None:
+    warn(msg)
+    raise SystemExit(code)
+
+
+REPO = os.environ.get("PAPERSTACK_REPO", "MilkClouds/my-paperstack")
+
+
+def _ttl() -> int:
+    """Parse lazily so invalid configuration does not break --help."""
+    raw = os.environ.get("PAPERSTACK_TTL", "3600")
+    try:
+        return int(raw)
+    except ValueError:
+        warn(f"PAPERSTACK_TTL={raw!r} is not a whole number of seconds; using 3600")
+        return 3600
+
+
+TTL = _ttl()
+
+# Keep caches separate across PAPERSTACK_REPO values.
+CACHE = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "paperstack" / REPO.replace("/", "_")
+CORPUS = CACHE / "corpus"
+STAGED = CACHE / "corpus.old"
+CHECKED = CACHE / "last-checked"
+SHA_FILE = ".paperstack-sha"  # Moves atomically with the corpus.
+LOCK = CACHE / "lock"
+
+
+def gh(*args: str, binary: bool = False) -> bytes | str | None:
+    """Return gh stdout, or None on failure."""
+    try:
+        p = subprocess.run(["gh", *args], capture_output=True, timeout=120, check=False)
+    except FileNotFoundError:
+        return None
+    except subprocess.TimeoutExpired:
+        return None
+    if p.returncode != 0:
+        return None
+    return p.stdout if binary else p.stdout.decode().strip()
+
+
+def remote_sha() -> str | None:
+    return gh("api", f"repos/{REPO}/commits/main", "--jq", ".sha") or None
+
+
+def local_sha() -> str | None:
+    f = CORPUS / SHA_FILE
+    return f.read_text().strip() if f.is_file() else None
+
+
+def valid(d: Path) -> bool:
+    """Return whether a directory contains entries."""
+    e = d / "entries"
+    return e.is_dir() and any(e.glob("*.md"))
+
+
+@contextlib.contextmanager
+def cache_lock():
+    """Serialize cache writes; yield False when the lock is busy."""
+    CACHE.mkdir(parents=True, exist_ok=True)
+    fd = os.open(LOCK, os.O_CREAT | os.O_RDWR, 0o644)
+    try:
+        try:
+            fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except OSError:
+            yield False
+            return
+        yield True
+    finally:
+        os.close(fd)
+
+
+def install(staged: Path) -> bool:
+    """Publish a staged corpus without exposing partial data."""
+    CACHE.mkdir(parents=True, exist_ok=True)
+    try:
+        shutil.rmtree(STAGED, ignore_errors=True)
+        if CORPUS.exists():
+            os.replace(CORPUS, STAGED)
+        os.replace(staged, CORPUS)
+    except OSError as e:
+        warn(f"could not publish the downloaded corpus ({e})")
+        return False
+    shutil.rmtree(STAGED, ignore_errors=True)
+    return True
+
+
+def recover() -> bool:
+    """Restore the backup left by an interrupted install."""
+    if valid(CORPUS) or not valid(STAGED):
+        return False
+    with cache_lock() as mine:
+        if not mine or valid(CORPUS) or not valid(STAGED):
+            return False
+        try:
+            os.replace(STAGED, CORPUS)
+        except OSError as e:
+            warn(f"could not recover the cached corpus ({e})")
+            return False
+    warn("recovered the cached corpus from an interrupted sync")
+    return True
+
+
+def sync(force: bool = False) -> bool:
+    """Update the cache from main."""
+    with cache_lock() as mine:
+        if not mine:
+            warn("another paperstack is syncing; using the cache as it stands")
+            return valid(CORPUS)
+        return _sync(force)
+
+
+def _sync(force: bool) -> bool:
+    sha = remote_sha()
+    if not sha:
+        return False
+    CHECKED.parent.mkdir(parents=True, exist_ok=True)
+    if not force and local_sha() == sha and valid(CORPUS):
+        CHECKED.touch()
+        return True
+
+    # Pin the archive to the recorded commit.
+    blob = gh("api", f"repos/{REPO}/tarball/{sha}", binary=True)
+    if not blob:
+        return False
+
+    tmp = Path(tempfile.mkdtemp(dir=CACHE, prefix=".staging-"))
+    try:
+        try:
+            with tarfile.open(fileobj=io.BytesIO(blob), mode="r:gz") as tar:
+                tar.extractall(tmp, filter="data")
+        except (tarfile.TarError, OSError, EOFError) as e:
+            warn(f"the downloaded archive is unreadable ({e})")
+            return False
+        roots = [p for p in tmp.iterdir() if p.is_dir()]
+        if len(roots) != 1 or not valid(roots[0]):
+            return False
+        (roots[0] / SHA_FILE).write_text(sha + "\n")
+        if not install(roots[0]):
+            return False
+    finally:
+        shutil.rmtree(tmp, ignore_errors=True)
+    # Only successful syncs refresh the TTL.
+    CHECKED.touch()
+    return True
+
+
+def stale() -> bool:
+    if not CHECKED.is_file():
+        return True
+    return time.time() - CHECKED.stat().st_mtime > TTL
+
+
+def git_toplevel() -> Path | None:
+    try:
+        p = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired):
+        return None
+    return Path(p.stdout.strip()) if p.returncode == 0 else None
+
+
+def resolve(offline: bool = False, force_sync: bool = False) -> Path:
+    if env := os.environ.get("PAPERSTACK_DIR"):
+        d = Path(env).expanduser()
+        if not valid(d):
+            die(f"PAPERSTACK_DIR={env} has no entries/")
+        if force_sync:
+            warn("--sync does not apply to PAPERSTACK_DIR; reading it as-is")
+        return d
+
+    if (top := git_toplevel()) and valid(top):
+        if force_sync:
+            warn(f"--sync does not apply to the working tree at {top}; reading it as-is")
+        return top
+
+    recover()
+    have = valid(CORPUS)
+    if offline:
+        if not have:
+            die("no local corpus and --offline was given; drop --offline to fetch one")
+        return CORPUS
+
+    if (force_sync or not have or stale()) and not sync(force=force_sync):
+        if not have:
+            die(
+                f"cannot reach {REPO} and there is no cached copy.\n"
+                "  gh is how this authenticates: check `gh auth status`, then `gh auth login`"
+            )
+        warn(f"cannot reach {REPO}; using the cached copy from {(local_sha() or 'unknown')[:7]}")
+    if not valid(CORPUS):
+        die("the cached corpus is unusable and could not be replaced")
+    return CORPUS
+
+
+class FrontLoader(yaml.SafeLoader):
+    """SafeLoader that preserves YAML 1.1 boolean-like words."""
+
+
+FrontLoader.yaml_implicit_resolvers = {
+    k: [(tag, rx) for tag, rx in v if tag != "tag:yaml.org,2002:bool"]
+    for k, v in yaml.SafeLoader.yaml_implicit_resolvers.items()
+}
+
+
+def split_front(text: str) -> tuple[str, str] | None:
+    """Split frontmatter on delimiter lines."""
+    lines = text.splitlines(keepends=True)
+    if not lines or lines[0].strip() != "---":
+        return None
+    for i, ln in enumerate(lines[1:], 1):
+        if ln.strip() == "---":
+            return "".join(lines[1:i]), "".join(lines[i + 1 :])
+    return None
+
+
+def as_list(v) -> list[str]:
+    """Normalize a frontmatter scalar or sequence to strings."""
+    if v is None:
+        return []
+    if isinstance(v, (str, bool, int, float)):
+        v = [v]
+    return [("yes" if x is True else "no" if x is False else str(x)) for x in v]
+
+
+def load(root: Path) -> list[dict]:
+    out = []
+    for p in sorted((root / "entries").glob("*.md")):
+        text = p.read_text(encoding="utf-8")
+        parts = split_front(text)
+        if not parts:
+            continue
+        fm, body = parts
+        try:
+            meta = yaml.load(fm, Loader=FrontLoader) or {}
+        except yaml.YAMLError:
+            warn(f"{p.name}: frontmatter is not valid YAML, skipped")
+            continue
+        if not isinstance(meta, dict):
+            warn(f"{p.name}: frontmatter is not a mapping, skipped")
+            continue
+        meta["key"] = p.stem
+        meta["body"] = body.strip()
+        meta["name"] = next((ln[2:].strip() for ln in body.splitlines() if ln.startswith("# ")), p.stem)
+        out.append(meta)
+    return out
+
+
+def quality(e: dict) -> str:
+    """Return the grade or ungraded."""
+    q = e.get("quality")
+    return str(q) if q not in (None, "") else "ungraded"
+
+
+def lead(e: dict, label: str) -> str:
+    """Extract a labeled lead line."""
+    tag = f"**{label}.**"
+    for ln in e["body"].splitlines():
+        if ln.startswith(tag):
+            return ln[len(tag) :].strip()
+    return ""
+
+
+def searchable(e: dict) -> str:
+    """Flatten entry values for search."""
+    parts: list[str] = []
+
+    def walk(v) -> None:
+        if isinstance(v, dict):
+            for x in v.values():
+                walk(x)
+        elif isinstance(v, (list, tuple)):
+            for x in v:
+                walk(x)
+        elif v is not None:
+            parts.append(str(v))
+
+    walk(e)
+    return "\n".join(parts).lower()
+
+
+def find(entries: list[dict], q: str) -> list[dict]:
+    """Return the first nonempty tier of increasingly broad matches."""
+    ql = q.lower()
+    for pick in (
+        lambda e: e["key"].lower() == ql,
+        lambda e: str(e.get("id", "")).lower() in (ql, f"arxiv:{ql}"),
+        lambda e: ql in e["name"].lower() or ql in e["key"].lower(),
+        lambda e: ql in str(e.get("title", "")).lower(),
+    ):
+        if hits := [e for e in entries if pick(e)]:
+            return hits
+    return []
+
+
+def strip_body(e: dict) -> dict:
+    return {k: v for k, v in e.items() if k != "body"}
+
+
+def one_line(e: dict) -> str:
+    bits = [f"{quality(e):<9}", e["key"]]
+    if e["name"] != e["key"]:
+        bits.append(f"({e['name']})")
+    return "  ".join(bits)
+
+
+def show(e: dict, brief: bool) -> None:
+    head = [e["name"], f"  {quality(e)}"]
+    meta = " · ".join(str(x) for x in (e.get("id"), e.get("venue"), ", ".join(as_list(e.get("lab")))) if x)
+    print("".join(head))
+    if meta:
+        print(meta)
+    print(f"tags: {', '.join(as_list(e.get('tags')))}    entries/{e['key']}.md")
+    print()
+    for label in ("One-liner", "Why read it", "Read it anyway"):
+        if v := lead(e, label):
+            print(f"{label}. {v}\n")
+    if not brief:
+        body = e["body"]
+        cut = body.find("## What it is")
+        if cut >= 0:
+            print(body[cut:])
+
+
+def _output(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="machine-readable output")
+
+
+def _offline(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--offline", action="store_true", help="never touch the network")
+
+
+def _review_commands(sub) -> None:
+    """Add commands that read or change the authored review corpus."""
+    s = sub.add_parser("show", help="review by key, id, or name")
+    s.add_argument("query", help="citation key, CURIE, method name, or title fragment")
+    s.add_argument("--brief", action="store_true", help="skip the two long sections")
+    _output(s)
+    _offline(s)
+
+    s = sub.add_parser("search", help="search review title, tags, and body")
+    s.add_argument("query", help="text to find in the authored review corpus")
+    _output(s)
+    _offline(s)
+
+    s = sub.add_parser("list", help="filter review frontmatter")
+    s.add_argument("--quality")
+    s.add_argument("--tag")
+    _output(s)
+    _offline(s)
+
+    s = sub.add_parser("sync", help="refresh the review cache")
+    s.add_argument("--force", action="store_true")
+
+    s = sub.add_parser("init", help="initialize an ungraded review scaffold")
+    s.add_argument("key", help="explicit citation key and filename stem")
+    s.add_argument("--id", required=True, help="registered CURIE or URL")
+    s.add_argument("--title", required=True, help="verified verbatim title")
+    s.add_argument("--editor", required=True)
+
+    s = sub.add_parser("check", help="validate the review corpus")
+    s.add_argument("--style", action="store_true", help="include prose-length warnings")
+    s = sub.add_parser("audit", help="compare review titles and venues with the local DBLP index")
+    _output(s)
+    _offline(s)
+
+    s = sub.add_parser("citations", help="update citation counts for all arXiv reviews")
+    s.add_argument("--fetch", action="store_true", help="fetch live counts from Semantic Scholar")
+    _output(s)
+
+
+def _review_init(root: Path, a: argparse.Namespace) -> int:
+    if not re.fullmatch(r"[a-z0-9]+", a.key):
+        die("review key must contain only lowercase ASCII letters and digits")
+    path = root / "entries" / f"{a.key}.md"
+    if path.exists():
+        die(f"review already exists: {path}", 1)
+    if any(str(entry.get("id")) == a.id for entry in load(root)):
+        die(f"a review with id {a.id!r} already exists", 1)
+    if any("\n" in value or "\r" in value for value in (a.id, a.title, a.editor)):
+        die("review id, title, and editor must each fit on one line")
+    if not re.fullmatch(r"([a-z][a-z0-9.]*:[^ ]+|https?://[^ ]+)", a.id):
+        die("review id must be a registered CURIE or URL")
+    title = json.dumps(a.title, ensure_ascii=False)
+    editor = json.dumps(a.editor, ensure_ascii=False)
+    body = f"""---
+id: {a.id}
+title: {title}
+quality: TODO
+tags: []
+editor: {editor}
+---
+
+# {a.title}
+
+**One-liner.** TODO
+
+**Why read it.** TODO
+
+## What it is / What it shows
+
+TODO
+
+## Critical read and limits
+
+**Verdict.** TODO
+"""
+    path.write_text(body, encoding="utf-8")
+    print(path)
+    return 0
+
+
+def _writable_review_root(command: str) -> Path:
+    if env := os.environ.get("PAPERSTACK_DIR"):
+        root = Path(env).expanduser()
+    else:
+        root = git_toplevel()
+    if root is None or not valid(root):
+        die(f"{command} requires a paperstack working tree or PAPERSTACK_DIR")
+    return root
+
+
+def _review_audit(entries: list[dict], *, json_output: bool) -> int:
+    from . import dblp_index
+
+    if not dblp_index.installed():
+        die("review audit requires the local index; run `paperstack index dblp install`")
+    report = []
+    try:
+        matches_by_entry = dblp_index.search_many([str(entry.get("title", "")) for entry in entries])
+    except RuntimeError as exc:
+        die(f"DBLP index lookup failed: {exc}")
+    for entry, matches in zip(entries, matches_by_entry, strict=True):
+        item = {
+            "key": entry["key"],
+            "id": entry.get("id"),
+            "title": entry.get("title"),
+            "current_venue": entry.get("venue"),
+            "status": "no_match" if not matches else "matched" if len(matches) == 1 else "ambiguous",
+            "dblp_matches": [
+                {key: match.get(key) for key in ("title", "dblp_key", "venue", "year", "entry_type", "doi", "url")}
+                for match in matches
+            ],
+        }
+        report.append(item)
+    if json_output:
+        print(json.dumps(report, ensure_ascii=False, indent=2))
+    else:
+        for item in report:
+            if item["status"] == "no_match":
+                continue
+            match = item["dblp_matches"][0]
+            venue = item["current_venue"] or "(absent)"
+            print(f"{item['key']}\n  review: {venue}\n  dblp:   {match['venue']} ({match['dblp_key']})")
+            if item["status"] == "ambiguous":
+                print(f"  status: {len(item['dblp_matches'])} candidates; manual review required")
+        counts = {
+            status: sum(item["status"] == status for item in report) for status in ("matched", "ambiguous", "no_match")
+        }
+        print("  ".join(f"{key}: {value}" for key, value in counts.items()), file=sys.stderr)
+    return 0
+
+
+def _run_review(a: argparse.Namespace) -> int:
+    cmd = a.review_cmd
+    if cmd == "sync":
+        if not sync(force=a.force):
+            die(f"could not reach {REPO}; check `gh auth status`")
+        print(f"{CORPUS}  {(local_sha() or '?')[:7]}", file=sys.stderr)
+        return 0
+
+    if cmd == "init":
+        return _review_init(_writable_review_root("review init"), a)
+    if cmd == "citations":
+        from . import citations
+
+        root = _writable_review_root("review citations")
+        entries = load(root)
+        try:
+            document, changed = citations.update(root, entries, live=a.fetch)
+        except (OSError, TypeError, ValueError) as exc:
+            die(f"citation update failed: {exc}")
+        if a.json:
+            print(json.dumps(document, indent=2))
+        else:
+            suffix = " (cached values only; pass --fetch for live counts)" if not a.fetch else ""
+            print(
+                f"{root / 'citations.json'}: {len(document['papers'])}/{len(citations.collect(entries))} entries, "
+                f"{changed} changed{suffix}"
+            )
+        return 0
+    root = resolve(offline=getattr(a, "offline", False))
+    if cmd == "check":
+        checker = root / "scripts" / "build" / "check.sh"
+        if not checker.is_file():
+            die("review check requires a paperstack clone with scripts/build/check.sh")
+        argv = [str(checker), "--style"] if a.style else [str(checker)]
+        return subprocess.run(argv, cwd=root, check=False).returncode
+    entries = load(root)
+    if not entries:
+        die(f"no entries under {root}")
+    if cmd == "audit":
+        return _review_audit(entries, json_output=a.json)
+    if cmd == "show":
+        hits = find(entries, a.query)
+        if not hits:
+            die(f"nothing matches {a.query!r}", 1)
+        if len(hits) > 1:
+            warn(f"{a.query!r} matches {len(hits)} reviews:")
+            for e in hits:
+                print(f"  {one_line(e)}", file=sys.stderr)
+            return 2
+        if a.json:
+            print(json.dumps(hits[0], ensure_ascii=False, indent=2, default=str))
+        else:
+            show(hits[0], a.brief)
+        return 0
+
+    if cmd == "search":
+        ql = a.query.lower()
+        hits = [e for e in entries if ql in searchable(e)]
+    else:
+        hits = [
+            e
+            for e in entries
+            if (not a.quality or quality(e) == a.quality) and (not a.tag or a.tag in as_list(e.get("tags")))
+        ]
+    if a.json:
+        print(json.dumps([strip_body(e) for e in hits], ensure_ascii=False, indent=2, default=str))
+    else:
+        order = {"excellent": 0, "good": 1, "fair": 2, "poor": 3}
+        for e in sorted(hits, key=lambda e: (order.get(quality(e), 9), e["key"])):
+            print(one_line(e))
+        print(f"{len(hits)} reviews", file=sys.stderr)
+    return 0 if hits else 1
+
+
+def _paper_cache() -> Path:
+    base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return Path(os.environ.get("PAPERSTACK_PAPERS_DIR", base / "paperstack" / "papers"))
+
+
+def _run_paper(a: argparse.Namespace) -> int:
+    from . import metadata
+
+    ref = None
+    if a.paper_cmd == "metadata":
+        try:
+            ref = metadata.PaperRef.parse(a.paper_ref)
+        except ValueError as exc:
+            die(str(exc))
+    if a.offline and a.paper_cmd in ("metadata", "search"):
+        from . import dblp_index
+
+        local_search = a.paper_cmd == "search" and a.source == "dblp"
+        local_metadata = (
+            a.paper_cmd == "metadata" and a.source == "dblp" and ref is not None and ref.kind in ("dblp", "doi")
+        )
+        if not dblp_index.installed() or not (local_search or local_metadata):
+            die("offline paper lookup is available only through an installed DBLP index")
+    if a.paper_cmd == "metadata":
+        enabled = None if a.source == "all" else {a.source}
+        try:
+            results = metadata.fetch_all(ref, enabled, local_only=a.offline)
+        except RuntimeError as exc:
+            die(f"DBLP index lookup failed: {exc}")
+        metadata.print_results(results, json_output=a.json)
+        return 0 if any(item["status"] == "ok" for item in results) else 1
+    if a.paper_cmd == "search":
+        try:
+            result = metadata.search(a.source, a.query, local_only=a.offline)
+        except RuntimeError as exc:
+            die(f"DBLP index lookup failed: {exc}")
+        metadata.print_results(result, json_output=a.json)
+        return 0 if result["status"] == "ok" else 1
+
+    try:
+        ref = metadata.PaperRef.parse(a.paper_ref)
+    except ValueError as exc:
+        die(str(exc))
+    if ref.kind != "arxiv":
+        die(f"paper {a.paper_cmd} currently requires an arxiv: reference")
+    if a.paper_cmd == "read":
+        from .content import arxiv_source
+
+        arxiv_source.CACHE_DIR = _paper_cache()
+        cached_source = arxiv_source.CACHE_DIR / ref.value / "src"
+        if a.offline and a.refresh:
+            die("--offline and --refresh cannot be used together")
+        if a.offline and (not cached_source.is_dir() or not arxiv_source._tex_candidates(cached_source)):
+            die(f"no complete cached source for arxiv:{ref.value}")
+        argv = ["read", ref.value]
+        if a.outline:
+            argv.append("--outline")
+        elif a.section_id:
+            argv.extend(["--section", a.section_id])
+        if a.refresh:
+            argv.append("--refresh")
+        argv.extend(["--start", str(a.start), "--max-chars", str(a.max_chars)])
+        arxiv_source.main(argv)
+        return 0
+    if a.paper_cmd == "pdf":
+        from .content import arxiv_pdf
+
+        arxiv_pdf.CACHE_DIR = _paper_cache()
+        cached_pdf = arxiv_pdf.CACHE_DIR / ref.value / "paper.md"
+        if a.offline and (not cached_pdf.is_file() or cached_pdf.stat().st_size <= 1000):
+            die(f"no complete cached PDF conversion for arxiv:{ref.value}")
+        if not arxiv_pdf.convert(ref.value):
+            return 1
+        return 0
+    raise AssertionError(a.paper_cmd)
+
+
+def _run_index(a: argparse.Namespace) -> int:
+    from . import dblp_index
+
+    try:
+        if a.dblp_cmd == "status":
+            info = dblp_index.status()
+        elif a.dblp_cmd == "install":
+            warn("installing the selected-venue DBLP snapshot; this may take a minute")
+            info = dblp_index.install()
+        elif a.dblp_cmd == "update":
+            warn("checking for a newer selected-venue DBLP snapshot")
+            info = dblp_index.update()
+        elif a.dblp_cmd == "remove":
+            if not a.yes:
+                die("index removal requires --yes")
+            dblp_index.remove()
+            info = {"installed": False, "removed": True}
+        else:
+            raise AssertionError(a.dblp_cmd)
+    except (OSError, RuntimeError, TypeError, ValueError, tarfile.TarError) as exc:
+        die(f"DBLP index operation failed: {exc}")
+    if a.json:
+        print(json.dumps(info, indent=2))
+    else:
+        for key, value in info.items():
+            print(f"{key}: {value}")
+    return 0
+
+
+def main() -> int:
+    formatter = argparse.RawDescriptionHelpFormatter
+    ap = argparse.ArgumentParser(
+        prog="paperstack",
+        description=__doc__.split("\n")[0],
+        epilog="""typical workflow:
+  paperstack review search "RH20T"                 find an existing critical read
+  paperstack review show chen2024rh20tp            read the authored judgment
+  paperstack paper metadata arxiv:2403.19622       inspect source records
+  paperstack paper read arxiv:2403.19622 --outline inspect the paper structure
+  paperstack paper read arxiv:2403.19622 --section 3
+
+Use `review` for the curated corpus and `paper` for external paper facts and contents.
+Run `paperstack <group> --help` for group-specific examples.""",
+        formatter_class=formatter,
+    )
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    review = sub.add_parser(
+        "review",
+        help="authored critical reads and judgments",
+        description="Search, read, and maintain the authored critical-review corpus.",
+        epilog="""examples:
+  paperstack review search "flow matching"
+  paperstack review show black2024pi0 --brief
+  paperstack review show arxiv:2410.24164 --json
+  paperstack review list --quality poor --tag vla
+
+Use `paperstack paper ...` when you need external metadata or the paper body.""",
+        formatter_class=formatter,
+    )
+    review_sub = review.add_subparsers(dest="review_cmd", required=True)
+    _review_commands(review_sub)
+
+    paper = sub.add_parser(
+        "paper",
+        help="source-backed paper facts and contents",
+        description="Inspect external source records and read arXiv paper contents without choosing a citation.",
+        epilog="""examples:
+  paperstack paper search "Attention Is All You Need" --source dblp
+  paperstack paper metadata arxiv:2403.19622
+  paperstack paper read arxiv:2403.19622 --outline
+  paperstack paper read arxiv:2403.19622 --section 3
+
+Use `paperstack review ...` to find or read an authored critical judgment.""",
+        formatter_class=formatter,
+    )
+    paper_sub = paper.add_subparsers(dest="paper_cmd", required=True)
+    s = paper_sub.add_parser("metadata", help="fetch source records without choosing between them")
+    s.add_argument("paper_ref", help="arxiv:, doi:, dblp:, or openreview: reference")
+    s.add_argument(
+        "--source",
+        choices=("all", "semantic_scholar", "dblp", "crossref", "openreview", "acl_anthology", "arxiv"),
+        default="all",
+    )
+    _output(s)
+    _offline(s)
+    s = paper_sub.add_parser("search", help="search one metadata source")
+    s.add_argument("query", help="paper title or other source-specific search text")
+    s.add_argument("--source", choices=("s2", "dblp", "crossref", "openreview", "arxiv"), default="s2")
+    _output(s)
+    _offline(s)
+    s = paper_sub.add_parser("read", help="read the LaTeX body, outline, or one section")
+    s.add_argument("paper_ref", help="arxiv: reference")
+    mode = s.add_mutually_exclusive_group()
+    mode.add_argument("--outline", action="store_true", help="print numbered section headings only")
+    mode.add_argument("--section", dest="section_id", help="print one section by outline number")
+    s.add_argument("--refresh", action="store_true", help="replace the cached arXiv source")
+    s.add_argument("--start", type=int, default=0, help="start at this character offset")
+    s.add_argument("--max-chars", type=int, default=0, help="truncate output after this many characters")
+    _offline(s)
+    s = paper_sub.add_parser("pdf", help="download and convert a native PDF submission")
+    s.add_argument("paper_ref", help="arxiv: reference")
+    _offline(s)
+
+    index = sub.add_parser("index", help="optional local lookup indexes")
+    index_sub = index.add_subparsers(dest="index_cmd", required=True)
+    dblp = index_sub.add_parser("dblp", help="selected-venue DBLP index")
+    dblp_sub = dblp.add_subparsers(dest="dblp_cmd", required=True)
+    for command in ("status", "install", "update"):
+        _output(dblp_sub.add_parser(command))
+    s = dblp_sub.add_parser("remove")
+    s.add_argument("--yes", action="store_true")
+    _output(s)
+
+    a = ap.parse_args()
+
+    if a.cmd == "paper":
+        return _run_paper(a)
+    if a.cmd == "index":
+        return _run_index(a)
+    return _run_review(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())