@diottodev/runic 1.0.0 → 1.1.0

package/research/patent/skills/patent/references/legal_disclaimer_discipline.md

@@ -0,0 +1,137 @@
+# Legal Disclaimer Discipline — When + Why Mandatory
+
+This reference answers exactly one decision: **for which sub-use-cases does the patent skill require a legal disclaimer in the DOCX, and what does the disclaimer need to say?**
+
+## The Core Rule
+
+Patent law has **immediate financial + legal consequences**. The skill produces **search signal**, not legal advice. A reader who confuses the two and skips attorney consultation can face:
+
+- Patent infringement liability (FTO failure → lawsuit)
+- Patent application rejection (novelty failure → expensive abandoned application)
+- Wasted R&D investment (proceeding on a confidence the search couldn't actually justify)
+
+**The disclaimer is a safety property**, comparable to drafts-only in inbox-triage. It prevents foreseeable user harm.
+
+## When Disclaimer Is Mandatory
+
+| Sub-use-case | Disclaimer mandatory? | Rationale |
+|---|---|---|
+| **Novelty search** | YES (Q6 triggers it) | Prosecution decisions have legal consequences |
+| **Freedom-to-operate** | YES (Q6 triggers it) | Shipping decisions have liability consequences |
+| **Competitive landscape** | Optional (recommended) | Lower legal exposure; more strategic than legal |
+| **Acquisition diligence** | Optional (strongly recommended) | M&A context — legal review usually already part of process |
+| **Litigation prior-art** | Optional (strongly recommended) | Litigation context — counsel almost always involved |
+
+For **mandatory** sub-use-cases, the disclaimer:
+1. Appears in **Executive Summary** footer (Section 1)
+2. Appears in **Strategy + Recommendations** body (Section 7)
+3. Appears in **Audit Log** as a final reminder (Section 8)
+
+For **optional** sub-use-cases, the disclaimer appears only in Section 8 as a reminder.
+
+## What the Disclaimer Says
+
+### Mandatory version (novelty + FTO)
+
+> **⚖️ Legal Disclaimer:** This document is **search signal, not legal advice**. The verdict ({NOVEL/CLEAR/etc.}) is a technical assessment based on the patents found in this session's tool calls. **Patent novelty and freedom-to-operate determinations have legal consequences and require qualified counsel.**
+>
+> **Before any filing or licensing decision:**
+> - Consult a registered patent attorney in your jurisdiction(s)
+> - Provide them this dossier as starting material; they will conduct independent verification + opinion
+> - Their opinion is privileged and admissible; this skill's output is neither
+>
+> The skill does not establish attorney-client privilege. The skill's verdict does not constitute a legal opinion.
+
+### Optional version (landscape, diligence, litigation)
+
+> **⚖️ Reminder:** This document is search signal. Patent attorney consultation is recommended for any decisions arising from this analysis.
+
+## Why Disclaimer Discipline Matters
+
+### Reason 1: Legal liability framing
+
+Without disclaimer, a user could (in extreme cases) claim the skill misled them into a legal decision. Disclaimer makes the skill's role unambiguous: **technical assessment, not legal opinion**.
+
+### Reason 2: Setting realistic expectations
+
+Even a well-executed patent search has limits:
+
+- Some patents may not be indexed in queried sources (especially recent applications)
+- Some patents may be classified in unexpected CPC classes
+- Some art may be in non-patent literature (academic papers, products, manuals)
+- Some art may be in different languages (non-English jurisdictions)
+
+The disclaimer tells the user: "I did the best technical search I could; counsel will catch what I might have missed."
+
+### Reason 3: Privileged communication
+
+Attorney-client conversations are **privileged** — not admissible against the user in litigation. This skill's output is **not privileged**. If the user later faces litigation, opposing counsel can subpoena the dossier as evidence of what the user knew.
+
+The disclaimer reminds users to NOT rely solely on the dossier for high-stakes decisions; an attorney's opinion provides privilege.
+
+### Reason 4: Jurisdiction-specific nuance
+
+Patent law varies by jurisdiction:
+
+- **First-to-file vs first-to-invent** (US switched to first-to-file in 2013; some countries differ)
+- **Grace periods** (US has 1-year; many countries have none)
+- **Doctrine of equivalents** (varies by jurisdiction)
+- **Inequitable conduct** (US-specific; may affect prosecution strategy)
+
+The skill cannot capture all jurisdictional nuance. Counsel can.
+
+## Anti-Patterns
+
+### Skipping disclaimer because user said "I'm a patent attorney"
+
+The user might be a patent attorney, but they might also be running this for a less-experienced colleague or client. The disclaimer is **always** in the document because the document might outlive the original requester.
+
+### Burying disclaimer in fine print
+
+Mandatory-sub-use-case disclaimer appears in Sections 1, 7, and 8 — three locations. Reader cannot miss it.
+
+### Replacing disclaimer with "consult your attorney"
+
+The disclaimer must be specific about what the skill does and doesn't claim. "Consult your attorney" alone is insufficient; the disclaimer also needs to clarify:
+- What the verdict means (technical assessment)
+- What counsel adds (privilege, jurisdiction expertise, opinion)
+- What's not covered (non-patent prior art, language coverage gaps)
+
+### Conflating disclaimer with legal-advice disclaimer
+
+Some skills use generic "this is not legal advice" boilerplate. The patent skill's disclaimer is specifically about patent novelty/FTO determinations and the role of qualified counsel — not generic.
+
+### Removing disclaimer to "make the document feel more authoritative"
+
+Authority comes from technical rigor (claim-text extraction, family resolution, CPC class follow-up), not from omitting safety disclaimers. The disclaimer **enhances** authority by making the skill's role transparent.
+
+## Operational Checklist
+
+For novelty + FTO (mandatory):
+
+- [ ] Disclaimer in Executive Summary (Section 1) footer
+- [ ] Disclaimer in Strategy section (Section 7)
+- [ ] Disclaimer in Audit Log (Section 8) as final reminder
+- [ ] Disclaimer text matches template above (don't paraphrase the legal language)
+- [ ] Q6 attorney-status answer recorded in audit log
+
+For landscape + diligence + litigation (optional):
+
+- [ ] Reminder version in Audit Log (Section 8)
+- [ ] Strategy section (Section 7) includes "consult patent attorney for [decision-specific context]"
+
+## Citations (7 sources)
+
+1. **MPEP §1.4 + §1.5 — *Manual of Patent Examining Procedure* (USPTO).** Source for the role of registered patent attorneys/agents in prosecution. The disclaimer's reference to "qualified counsel" tracks USPTO's registration framework.
+
+2. **AIPLA *Code of Ethics* — American Intellectual Property Law Association.** Source for the privileged-communication framing. AIPLA's guidance on lay-vs-attorney communication informs the "this skill is not privileged" disclaimer language.
+
+3. **35 USC §282 — *Presumption of validity*.** US patent statute. Source for understanding what "valid" means legally + why a search-signal verdict is not a legal validity opinion.
+
+4. **35 USC §271 — *Infringement of patent*.** Source for the FTO disclaimer framing. Liability for infringement is a legal determination; the skill's "CLEAR/FLAGGED/HIGH RISK" verdict is technical.
+
+5. **EPO Guidelines for Examination, Part E.** Source for European-jurisdiction differences (no grace period, different inventive-step analysis). The disclaimer's "jurisdiction-specific nuance" caveat tracks these variations.
+
+6. **PCT Article 39 — Patent Cooperation Treaty.** Source for the cross-jurisdiction prosecution complexity that justifies counsel involvement. PCT national-phase entries each require local-counsel coordination.
+
+7. **Fischer, T., & Henkel, J., "Patent Trolls on Markets for Technology" — *Research Policy* 41(9), 2012.** Empirical evidence for the cost of FTO mistakes. Patent assertion entities (PAEs) have made FTO failures financially severe; the disclaimer's emphasis on counsel reflects this risk reality.

package/research/patent/skills/patent/references/sub_use_case_routing.md

@@ -0,0 +1,252 @@
+# Sub-Use-Case Routing — The 5 Patent Search Strategies
+
+This reference answers exactly one decision: **given the user's Q2 commitment, which search strategy / ranking heuristic / DOCX emphasis applies?**
+
+The patent skill refuses to be a generic "patent search". Q2 is mandatory. The 5 sub-use-cases use **fundamentally different** strategies — running a novelty search and calling it FTO produces wrong answers in dangerous ways.
+
+## Why Sub-Use-Case Commitment Matters
+
+| Sub-use-case | Wrong-strategy danger |
+|---|---|
+| Novelty | Generic search misses claim-text proximity → false negatives ("looks novel, isn't") |
+| FTO | Generic search includes expired/abandoned patents → false positives ("looks blocked, isn't") |
+| Landscape | Generic search misses CPC class trends → incomplete competitive picture |
+| Diligence | Generic search misses assignment chain → ownership-verification gaps |
+| Litigation | Generic search includes art after priority date → useless for invalidation |
+
+The 5 strategies are **not interchangeable**. The skill enforces commitment to prevent strategy mismatches.
+
+## Strategy 1: Novelty Search
+
+### Question being answered
+
+"Am I novel enough to file? Is there art that anticipates or makes obvious my invention?"
+
+### Search emphasis
+
+- **Narrow** queries on invention-specific terminology (don't drown in adjacent art)
+- **Claims-text focused** (the legal test is claim-by-claim anticipation)
+- **Pre-filing date irrelevant** — anything published before user's filing is potential art
+
+### Query plan
+
+1. 3 narrow Google Patents queries on invention-specific terms
+2. 2 broad concept queries with synonyms (Google Patents + Espacenet)
+3. 1 CPC class-restricted query (after class identification from initial hits)
+4. (Optional Lens.org) forward citations from any closest art
+
+**Total: 6-7 sequential queries.**
+
+### Ranking heuristic
+
+Rank by **claim-text overlap** with user's invention description (Q1). Top hits are those whose claim 1 most overlaps in technical terminology. Surface independent claim 1 verbatim for each top-5 hit.
+
+### Verdict scale
+
+- **NOVEL** — closest hit has <30% claim-text overlap; clear differentiation possible
+- **POTENTIALLY NOVEL** — 30-60% overlap; differentiation possible but requires careful claim drafting
+- **NOT NOVEL** — >60% overlap; invention as described is anticipated by closest art
+
+### DOCX emphasis
+
+- Section 2 (Closest Prior Art): expanded — 8-10 hits with full claim-1 text
+- Section 7 (Strategy): claim-differentiation suggestions
+- Sections 3 + 5 (Landscape + Geographic): abbreviated
+- Mandatory legal disclaimer footer
+
+## Strategy 2: Freedom-to-Operate
+
+### Question being answered
+
+"If I ship in jurisdiction X, will I get sued for infringement?"
+
+### Search emphasis
+
+- **Active patents only** — expired/abandoned patents can't sue
+- **Jurisdiction-filtered** — FTO only matters where user sells
+- **Date filter:** priority date < today (no pending applications without published claims)
+- **Independent + dependent claims** — both relevant to infringement analysis
+
+### Query plan
+
+1. Per jurisdiction (Q3): 2-3 queries with jurisdiction filter (US: USPTO; EP: Espacenet; etc.)
+2. Active-status filter applied to all
+3. CPC class follow-up after initial hits
+4. (Optional) assignment chain check for active assignee context
+
+**Total: 8-15 sequential queries (scales with # of jurisdictions).**
+
+### Ranking heuristic
+
+Rank by **claim-by-claim infringement risk**. For each active patent: which independent claims would the user's product practice? High risk = at least one independent claim covers user's product as designed.
+
+### Verdict scale (per jurisdiction)
+
+- **CLEAR** — no active patents pose infringement risk
+- **FLAGGED** — 1-2 active patents may pose risk; design-around viable
+- **HIGH RISK** — 3+ active patents pose risk; design changes required OR licensing path needed
+
+### DOCX emphasis
+
+- Section 6 (FTO Flags): expanded — per-flag risk per jurisdiction
+- Section 5 (Geographic Coverage): expanded
+- Section 7 (Strategy): design-around hints + jurisdiction strategy
+- Mandatory legal disclaimer footer
+
+## Strategy 3: Competitive Landscape
+
+### Question being answered
+
+"Who else plays in this technology space? What are the trends?"
+
+### Search emphasis
+
+- **Broader queries** on the technology space (NOT the specific invention)
+- **CPC class identification** drives the analysis
+- **Top filer tally** — who files most patents in the space
+- **10-year filing trend** by year per top-5 filer
+
+### Query plan
+
+1. 2-3 broad queries on the technology space
+2. CPC class extraction from top hits
+3. 1 query per top-5 filer to gauge their portfolio
+4. (Optional Lens.org) citation graph for foundational patents
+
+**Total: 8-10 sequential queries.**
+
+### Ranking heuristic
+
+Rank by filer count + recency. Top-5 filers + 3 emerging entrants (filers with first patent in last 2 years).
+
+### Verdict scale
+
+- **CONCENTRATED** — top-3 filers own >60% of patents in the space
+- **COMPETITIVE** — top-10 filers own 60-90%; mature competitive market
+- **EMERGING** — long tail of filers; market is still defining itself
+
+### DOCX emphasis
+
+- Section 3 (Patent Landscape): expanded — top filers table + 10-yr trend + CPC distribution
+- Section 5 (Geographic Coverage): expanded
+- Sections 2 + 4 (Closest Art + Citation Graph): abbreviated
+- Section 7 (Strategy): who-to-watch list + emerging-entrants signal
+- Legal disclaimer optional (lower legal exposure)
+
+## Strategy 4: Acquisition Diligence
+
+### Question being answered
+
+"Does target company actually own the patents they claim? Is there portfolio depth?"
+
+### Search emphasis
+
+- **Specific assignee searches** — target company + subsidiaries + named inventors
+- **Assignment chain check** — USPTO assignment recordation
+- **Family resolution** — deduplicate same-invention across jurisdictions
+- **Portfolio scope** — are patents in core business areas or peripheral?
+
+### Query plan
+
+1. 2-3 assignee-name queries (Google Patents + USPTO assignee search)
+2. Subsidiary searches if user provides org chart
+3. Inventor searches for key named inventors
+4. Assignment recordation lookups for ownership verification
+5. Family resolution across all hits
+
+**Total: 6-12 sequential queries.**
+
+### Ranking heuristic
+
+Group by family. Within family, surface earliest priority. Across families, rank by:
+- Citation count (foundational vs niche)
+- Filing recency (active R&D vs legacy)
+- Claim breadth (broad coverage vs narrow)
+
+### Verdict scale
+
+- **PORTFOLIO VERIFIED** — claimed patents owned, assignment chains clean, no orphans
+- **PARTIAL VERIFICATION** — some claimed patents not found OR assignment chain unclear
+- **OWNERSHIP RISK** — significant claimed patents not owned by target OR major assignment gaps
+
+### DOCX emphasis
+
+- Section 3 (Patent Landscape): expanded as portfolio table
+- Section 5 (Geographic Coverage): expanded
+- Section 7 (Strategy): red flags in portfolio + ownership-verification flags
+- Legal disclaimer optional but recommended (M&A context)
+
+## Strategy 5: Litigation Prior-Art
+
+### Question being answered
+
+"Can I invalidate this specific patent? What art exists before its priority date?"
+
+### Search emphasis
+
+- **Target patent input required** (number)
+- **Priority date extraction** — sets the prior-art cutoff
+- **Search before priority date in same CPC classes**
+- **Adjacent-claim-language search** — art that uses similar claim language
+
+### Query plan
+
+1. Fetch target patent (extract priority date + claims + CPC classes)
+2. CPC class queries with date filter (priority < target's priority)
+3. Keyword queries on independent claim language with date filter
+4. (Optional Lens.org) forward citations from target's cited art
+
+**Total: 5-8 sequential queries.**
+
+### Ranking heuristic
+
+Rank by **knock-out potential** — claim-by-claim anticipation/obviousness. Highest rank: art that anticipates ALL elements of target's broadest independent claim.
+
+### Verdict scale
+
+- **KNOCK-OUT FOUND** — art clearly anticipates all elements of broadest claim
+- **STRONG OBVIOUSNESS COMBINATION** — multiple pieces of art combine to cover all elements
+- **WEAK OBVIOUSNESS** — art relevant but anticipation/obviousness argument is uphill
+- **NO MATERIAL ART FOUND** — patent appears strong against this prior-art set
+
+### DOCX emphasis
+
+- Section 2 (Closest Prior Art): expanded — ranked knock-out candidates with claim-language overlap
+- Section 7 (Strategy): per-claim invalidity analysis
+- Sections 3 + 5 (Landscape + Geographic): abbreviated
+- Legal disclaimer optional but recommended (litigation context)
+
+## Out-of-Scope Topics (Flagged at Intake)
+
+| Topic | Why out of scope |
+|---|---|
+| Trademark | Different legal regime, different sources (USPTO TESS not Patent Office) |
+| Copyright | No formal search system; rights attach automatically |
+| Trade secret | By definition, not in public records |
+
+If user asks for any of these → halt at intake, recommend appropriate skill or attorney.
+
+## Operational Checklist
+
+- [ ] Q2 sub-use-case picked (no "all of them")
+- [ ] `scripts/sub_use_case_router.py` returns query plan + ranking heuristic + DOCX flags
+- [ ] Search emphasis matches sub-use-case (not generic)
+- [ ] Verdict scale per sub-use-case applied
+- [ ] DOCX emphasis adjusted (not all 8 sections expanded for every sub-use-case)
+- [ ] Legal disclaimer mandatory for novelty + FTO; optional for landscape/diligence/litigation but recommended
+
+## Citations (7 sources)
+
+1. **MPEP (Manual of Patent Examining Procedure) — USPTO.** Source for the legal definitions of novelty (35 USC §102) vs FTO (no explicit USC; case law) vs anticipation/obviousness. The verdict scales follow MPEP terminology.
+
+2. **35 USC §102 + §103 — US patent statute.** Source for the priority-date-as-cutoff rule for novelty (§102) and the obviousness combination doctrine (§103) that drives litigation prior-art ranking.
+
+3. **WIPO Patent Cooperation Treaty (PCT) procedural docs.** Source for the cross-jurisdiction family discipline. PCT applications generate national-phase entries in many jurisdictions; the family resolver follows WIPO's family-id taxonomy.
+
+4. **EPO Guidelines for Examination — European Patent Office.** Source for the EP-specific FTO discipline. EP active-status filtering uses EPO's "in force" status field.
+
+5. **USPTO Patent Public Search documentation.** Source for the USPTO PPS query syntax and assignment-recordation lookup endpoints used in acquisition diligence.
+
+6. **Google Patents search documentation + advanced operators.** Source for the keyword + CPC class + date filter syntax. Google Patents indexes all PCT national-phase entries plus most jurisdictions' grant data.
+
+7. **Lens.org API documentation (https://docs.api.lens.org).** Source for the citation-graph queries. Lens.org's citation API exposes forward + backward citations with citation-count thresholds for foundational-patent identification.

package/research/patent/skills/patent/scripts/citation_tracker.py

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""citation_tracker.py — Patent skill three-count audit across multi-source patent search.
+
+Stdlib-only. Mirrors litreview/grants/dossier trackers but adapted for patent's
+4-source workflow:
+
+  - Google Patents (workhorse, no auth)
+  - Espacenet (global)
+  - USPTO PPS (US deep dive)
+  - Lens.org (BYOK, citation graph)
+
+Tracked counts:
+  - searches_per_source       (broken out by source)
+  - patents_received_total
+  - patents_cited_total
+  - patents_cited_by_source
+  - sub_use_case               (recorded at start; drives audit verbatim)
+  - lens_byok_used             (boolean — surfaced in audit log)
+
+Enforces 1s sequential discipline across ALL sources combined.
+
+Usage:
+    python citation_tracker.py --action start --session patent-MS-novelty-20260515 --invention "..." --sub-use-case novelty
+    python citation_tracker.py --action record_search --session ... --source google_patents --query "..."
+    python citation_tracker.py --action record_received --session ... --source google_patents --count 10
+    python citation_tracker.py --action record_cited --session ... --source google_patents --patent-num "US10000000B2"
+    python citation_tracker.py --action record_lens_byok --session ...
+    python citation_tracker.py --action status --session ...
+    python citation_tracker.py --action close --session ...
+"""
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+SESSIONS_DIR = Path.home() / ".patent_sessions"
+MIN_GAP_SECONDS = 1.0
+VALID_SOURCES = ["google_patents", "espacenet", "uspto", "lens", "websearch"]
+VALID_SUB_USE_CASES = ["novelty", "fto", "landscape", "diligence", "litigation"]
+
+
+def session_path(name: str) -> Path:
+    return SESSIONS_DIR / f"{name}.json"
+
+
+def load_session(name: str) -> Dict[str, Any]:
+    p = session_path(name)
+    if not p.exists():
+        raise FileNotFoundError(f"Session not found: {name}")
+    return json.loads(p.read_text(encoding="utf-8"))
+
+
+def save_session(name: str, data: Dict[str, Any]) -> None:
+    SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+    session_path(name).write_text(json.dumps(data, indent=2), encoding="utf-8")
+
+
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+def now_ts() -> float:
+    return datetime.now(timezone.utc).timestamp()
+
+
+def action_start(name: str, invention: Optional[str], sub_use_case: Optional[str]) -> Dict[str, Any]:
+    if session_path(name).exists():
+        raise FileExistsError(f"Session already exists: {name}")
+    if sub_use_case and sub_use_case not in VALID_SUB_USE_CASES:
+        raise ValueError(f"Invalid sub-use-case '{sub_use_case}'. Pick from: {VALID_SUB_USE_CASES}")
+    data: Dict[str, Any] = {
+        "session": name,
+        "invention": invention or "",
+        "sub_use_case": sub_use_case or "",
+        "started_at": now_iso(),
+        "ended_at": None,
+        "lens_byok_used": False,
+        "searches": [],
+        "received_log": [],
+        "cited": [],
+        "counts": {
+            "searches_total": 0,
+            "searches_by_source": {s: 0 for s in VALID_SOURCES},
+            "received_total": 0,
+            "received_by_source": {s: 0 for s in VALID_SOURCES},
+            "cited_total": 0,
+            "cited_by_source": {s: 0 for s in VALID_SOURCES},
+        },
+    }
+    save_session(name, data)
+    return data
+
+
+def action_record_search(name: str, source: str, query: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if source not in VALID_SOURCES:
+        raise ValueError(f"Invalid source '{source}'. Pick from: {VALID_SOURCES}")
+    if data["searches"]:
+        last_ts = data["searches"][-1].get("ts", 0)
+        gap = now_ts() - last_ts
+        if gap < MIN_GAP_SECONDS:
+            raise RuntimeError(
+                f"Sequential discipline violated: {gap:.2f}s gap (need >= {MIN_GAP_SECONDS}s). "
+                f"Wait {MIN_GAP_SECONDS - gap:.2f}s more."
+            )
+    data["searches"].append({"source": source, "query": query, "at": now_iso(), "ts": now_ts()})
+    data["counts"]["searches_total"] += 1
+    data["counts"]["searches_by_source"][source] += 1
+    save_session(name, data)
+    return data
+
+
+def action_record_received(name: str, source: str, count: int) -> Dict[str, Any]:
+    data = load_session(name)
+    if source not in VALID_SOURCES:
+        raise ValueError(f"Invalid source '{source}'")
+    data["received_log"].append({"source": source, "count": count, "at": now_iso()})
+    data["counts"]["received_total"] += count
+    data["counts"]["received_by_source"][source] += count
+    save_session(name, data)
+    return data
+
+
+def action_record_cited(name: str, source: str, patent_num: str, title: Optional[str]) -> Dict[str, Any]:
+    data = load_session(name)
+    if source not in VALID_SOURCES:
+        raise ValueError(f"Invalid source '{source}'")
+    if any(c["patent_num"] == patent_num for c in data["cited"]):
+        return data
+    data["cited"].append({"source": source, "patent_num": patent_num, "title": title, "at": now_iso()})
+    data["counts"]["cited_total"] += 1
+    data["counts"]["cited_by_source"][source] += 1
+    save_session(name, data)
+    return data
+
+
+def action_record_lens_byok(name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    data["lens_byok_used"] = True
+    save_session(name, data)
+    return data
+
+
+def action_status(name: str) -> Dict[str, Any]:
+    return load_session(name)
+
+
+def action_close(name: str) -> Dict[str, Any]:
+    data = load_session(name)
+    if data.get("ended_at") is None:
+        data["ended_at"] = now_iso()
+        save_session(name, data)
+    return data
+
+
+def render_status_human(data: Dict[str, Any]) -> str:
+    out: List[str] = []
+    out.append(f"Session:           {data['session']}")
+    out.append(f"Invention:         {data.get('invention', '(unset)')}")
+    out.append(f"Sub-use-case:      {data.get('sub_use_case', '(unset)')}")
+    out.append(f"Lens.org BYOK:     {'YES' if data.get('lens_byok_used') else 'no (citation graph skipped)'}")
+    out.append(f"Started:           {data['started_at']}")
+    out.append(f"Ended:             {data.get('ended_at') or '(active)'}")
+    out.append("")
+    c = data["counts"]
+    out.append(f"Total searches:    {c['searches_total']}")
+    out.append("By source:")
+    for src, n in c["searches_by_source"].items():
+        if n > 0:
+            out.append(f"  {src:<18s} {n}")
+    out.append("")
+    out.append(f"Patents received:  {c['received_total']}")
+    out.append(f"Patents cited:     {c['cited_total']}")
+    out.append("Cited by source:")
+    for src, n in c["cited_by_source"].items():
+        if n > 0:
+            out.append(f"  {src:<18s} {n}")
+    out.append("")
+    out.append("Audit block (paste in DOCX Section 8):")
+    out.append(
+        f"  Searches: {c['searches_total']} (Google Patents: {c['searches_by_source'].get('google_patents', 0)}, "
+        f"Espacenet: {c['searches_by_source'].get('espacenet', 0)}, "
+        f"USPTO: {c['searches_by_source'].get('uspto', 0)}, "
+        f"Lens.org: {c['searches_by_source'].get('lens', 0)}). "
+        f"Patents received: {c['received_total']}. Patents cited: {c['cited_total']}. "
+        f"Lens.org BYOK: {'used' if data.get('lens_byok_used') else 'not provided (citation graph skipped)'}."
+    )
+    return "\n".join(out)
+
+
+def main(argv: List[str]) -> int:
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("--action", required=True, choices=["start", "record_search", "record_received", "record_cited", "record_lens_byok", "status", "list", "close"])
+    parser.add_argument("--session")
+    parser.add_argument("--invention")
+    parser.add_argument("--sub-use-case", choices=VALID_SUB_USE_CASES)
+    parser.add_argument("--source", choices=VALID_SOURCES)
+    parser.add_argument("--query")
+    parser.add_argument("--count", type=int)
+    parser.add_argument("--patent-num")
+    parser.add_argument("--title")
+    parser.add_argument("--output", choices=["human", "json"], default="human")
+    args = parser.parse_args(argv)
+
+    try:
+        if args.action == "start":
+            result = action_start(args.session, args.invention, args.sub_use_case)
+        elif args.action == "record_search":
+            result = action_record_search(args.session, args.source, args.query)
+        elif args.action == "record_received":
+            result = action_record_received(args.session, args.source, args.count)
+        elif args.action == "record_cited":
+            result = action_record_cited(args.session, args.source, args.patent_num, args.title)
+        elif args.action == "record_lens_byok":
+            result = action_record_lens_byok(args.session)
+        elif args.action == "status":
+            result = action_status(args.session)
+        elif args.action == "close":
+            result = action_close(args.session)
+        else:
+            SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+            result = [{"session": p.stem, "data": json.loads(p.read_text(encoding="utf-8"))} for p in sorted(SESSIONS_DIR.glob("*.json"))]
+    except (FileNotFoundError, FileExistsError, ValueError, RuntimeError) as e:
+        print(f"error: {e}", file=sys.stderr); return 2
+
+    if args.output == "json":
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        if args.action == "list":
+            print(json.dumps(result, indent=2, default=str))
+        else:
+            print(render_status_human(result))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))