feat: add brief output mode for user-ready summaries

Author: wwb1942

.github/workflows/ci.yml

@@ -44,5 +44,45 @@ jobs:
               'warnings': ['w'], 'errors': []
           })
           assert compact['summary_source'] == 'arxiv_abstract'
+          brief = mod.as_brief({
+              'paper_id': 'x',
+              'title': 'Test Paper',
+              'status': 'ok',
+              'source_used': 'alphaxiv+arxiv',
+              'summary_source': 'alphaxiv_report',
+              'best_summary': 'This paper introduces a retrieval-augmented planner for long-horizon tasks. It addresses brittle multi-step planning in dynamic environments. The method combines a planner, a verifier, and a memory cache. It uses iterative self-correction with retrieved demonstrations.',
+              'alphaxiv_status': 'available',
+              'arxiv_status': 'available',
+              'resolved_alphaxiv_url': 'u1',
+              'resolved_arxiv_url': 'u2',
+              'alphaxiv_report': 'This paper introduces a retrieval-augmented planner for long-horizon tasks. It addresses brittle multi-step planning in dynamic environments. The method combines a planner, a verifier, and a memory cache. It uses iterative self-correction with retrieved demonstrations.',
+              'alphaxiv_description': '',
+              'arxiv_abstract': 'This paper introduces a retrieval-augmented planner for long-horizon tasks.',
+              'warnings': [],
+              'errors': [],
+          })
+          assert 'Paper: Test Paper (x)' in brief
+          assert 'Problem solved:' in brief
+          assert 'Core method:' in brief
+          assert 'Source: alphaXiv report. Confidence: higher.' in brief
+          brief_fallback = mod.as_brief({
+              'paper_id': 'y',
+              'title': 'Fallback Paper',
+              'status': 'ok',
+              'source_used': 'arxiv',
+              'summary_source': 'arxiv_abstract',
+              'best_summary': 'We study efficient adaptation for vision models. The problem is updating large models under tight compute budgets. Our method trains a low-rank adapter and freezes the backbone.',
+              'alphaxiv_status': 'thin',
+              'arxiv_status': 'available',
+              'resolved_alphaxiv_url': 'u1',
+              'resolved_arxiv_url': 'u2',
+              'alphaxiv_report': '',
+              'alphaxiv_description': 'Short overview only.',
+              'arxiv_abstract': 'We study efficient adaptation for vision models. The problem is updating large models under tight compute budgets. Our method trains a low-rank adapter and freezes the backbone.',
+              'warnings': ['AlphaXiv page fetched, but only a short overview was available.'],
+              'errors': [],
+          })
+          assert 'Source: arXiv abstract fallback. Confidence: basic (alphaXiv: thin).' in brief_fallback
+          assert 'Worth reading? Abstract-first; alphaXiv was thin, so this brief relies on arXiv.' in brief_fallback
           print('offline normalization smoke test ok')
           PY

CHANGELOG.md

@@ -6,6 +6,16 @@ All notable changes to this repository will be documented in this file.
 
 - Ongoing documentation and release polish.
 
+## [v0.3.1] - 2026-03-13
+
+### Added
+
+- `--format brief` for a deterministic, compact, user-facing paper brief
+
+### Changed
+
+- documented the new brief mode and its arXiv-first fallback behavior when alphaXiv is thin or unavailable
+
 ## [v0.3.0] - 2026-03-13
 
 ### Added

README.md

@@ -45,7 +45,7 @@ In those cases, use this skill as a fast first-pass filter, then inspect the ori
 - fetch alphaXiv overview pages when available
 - extract embedded overview / report fields
 - fall back to the arXiv abstract when alphaXiv is thin or unavailable
-- return structured output in JSON or Markdown
+- return structured output in JSON, Markdown, verbose text, or a compact user-facing brief
 
 ## Quick examples
 
@@ -73,19 +73,19 @@ python3 scripts/alphaxiv_lookup.py 'https://www.alphaxiv.org/overview/2603.07612
 python3 scripts/alphaxiv_lookup.py '2603.07612' --format json-compact
 ```
 
-### Plain-text brief
+### Plain-text detail view
 
 ```bash
 python3 scripts/alphaxiv_lookup.py '2603.07612' --format text
 ```
 
-### Increase timeout for slow upstreams
+### Compact user-facing brief
 
 ```bash
-python3 scripts/alphaxiv_lookup.py '2603.07612' --format json --timeout 40
+python3 scripts/alphaxiv_lookup.py '2603.07612' --format brief
 ```
 
-### Adjust timeout for flaky upstreams
+### Increase timeout for slow upstreams
 
 ```bash
 python3 scripts/alphaxiv_lookup.py '2603.07612' --format json --timeout 40
@@ -109,6 +109,19 @@ The JSON output may include:
 - `arxiv_abstract`
 - `notes`
 
+## `--format brief`
+
+`--format brief` emits a deterministic, compact paper brief meant to be pasted directly to a user. It uses only retrieved fields and keeps working when alphaXiv is thin or unavailable by leaning on the arXiv fallback.
+
+Structure:
+
+- paper title + id
+- one-line takeaway
+- problem solved
+- core method
+- worth reading verdict
+- source / confidence hint
+
 ## Repository layout
 
 - `SKILL.md` — skill instructions and trigger guidance
@@ -125,6 +138,7 @@ The JSON output may include:
 - Technical skill slug remains `alphaxiv-paper-lookup`
 - If alphaXiv fetch fails, is rate-limited, or has only a thin overview, the workflow falls back to arXiv as needed
 - The JSON output now exposes `status`, `source_used`, `summary_source`, `best_summary`, `alphaxiv_status`, `arxiv_status`, `warnings`, and `errors` for easier downstream handling
+- `--format brief` prefers the best retrieved summary, but can still produce a useful user-facing brief from the arXiv abstract alone
 - AlphaXiv is treated as a shortcut, not a replacement for reading the full paper when exact details matter
 
 ## License

SKILL.md

@@ -19,6 +19,7 @@ Prefer alphaXiv first because it often exposes an AI-generated overview that is
    - Use `--format json` for full structured output.
    - Use `--format json-compact` when you want a smaller machine-friendly payload.
    - Use `--format text` for a clean plain-text brief.
+   - Use `--format brief` for a concise user-ready brief.
 3. Read the returned fields in this priority order:
    - `best_summary`
    - `alphaxiv_report`