@prismer/runtime 2.2.55 → 2.2.63

package/built-in-skills/prismer-youtube-content/LICENSE.hermes

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+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.

package/built-in-skills/prismer-youtube-content/PROVENANCE.md

@@ -0,0 +1,7 @@
+# Resource provenance
+
+Imported from hermes-agent skills/media/youtube-content at 1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4.
+
+Prismer receiver: prismer-youtube-content. Native replacement: youtube-content; this is not an alias. Preserve all source resources at their relative paths; merge packs live under references/youtube-content/. Source file hashes and content review: docs/bugfix223/audit-creative-media-coverage.json. Local corrections and remaining live acceptance: docs/bugfix223/implementation-creative.md.
+
+LICENSE.hermes preserves Nous Research MIT terms. External libraries, fonts, services and media have separate licenses; no third-party binary assets were included.

package/built-in-skills/prismer-youtube-content/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: prismer-youtube-content
+scope: common
+category: media
+description: "YouTube transcripts to summaries, threads, blogs."
+version: 1.0.0
+author: Teknium (teknium1), Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  nativeReplaces: [youtube-content]
+  hermes:
+    tags: [YouTube, Video, Transcripts, Media]
+    related_skills: []
+---
+
+# YouTube Content Tool
+
+## When to use
+
+Use when the user shares a YouTube URL or video link, asks to summarize a video, requests a transcript, or wants to extract and reformat content from any YouTube video. Transforms transcripts into structured content (chapters, summaries, threads, blog posts).
+
+Extract transcripts from YouTube videos and convert them into useful formats.
+
+## Setup
+
+Use `uv` so the dependency is installed into the same task-local isolated environment
+that runs the helper script:
+
+```bash
+uv pip install youtube-transcript-api==1.2.2
+```
+
+## Helper Script
+
+`SKILL_DIR` is the directory containing this SKILL.md file. The script accepts any standard YouTube URL format, short links (youtu.be), shorts, embeds, live links, or a raw 11-character video ID.
+
+```bash
+# JSON output with metadata
+uv run python SKILL_DIR/scripts/fetch_transcript.py "https://youtube.com/watch?v=VIDEO_ID"
+
+# Plain text (good for piping into further processing)
+uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --text-only
+
+# With timestamps
+uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --timestamps
+
+# Specific language with fallback chain
+uv run python SKILL_DIR/scripts/fetch_transcript.py "URL" --language tr,en
+```
+
+## Output Formats
+
+After fetching the transcript, format it based on what the user asks for:
+
+- **Chapters**: Group by topic shifts, output timestamped chapter list
+- **Summary**: Concise 5-10 sentence overview of the entire video
+- **Chapter summaries**: Chapters with a short paragraph summary for each
+- **Thread**: Twitter/X thread format — numbered posts, each under 280 chars
+- **Blog post**: Full article with title, sections, and key takeaways
+- **Quotes**: Notable quotes with timestamps
+
+### Example — Chapters Output
+
+```
+00:00 Introduction — host opens with the problem statement
+03:45 Background — prior work and why existing solutions fall short
+12:20 Core method — walkthrough of the proposed approach
+24:10 Results — benchmark comparisons and key takeaways
+31:55 Q&A — audience questions on scalability and next steps
+```
+
+## Workflow
+
+1. **Fetch** the transcript using the helper script with `--text-only --timestamps` via `uv run python`.
+2. **Validate**: confirm the output is non-empty and in the expected language. If empty, retry without `--language` to get any available transcript. If still empty, tell the user the video likely has transcripts disabled.
+3. **Chunk if needed**: if the transcript exceeds ~50K characters, split into overlapping chunks (~40K with 2K overlap) and summarize each chunk before merging.
+4. **Transform** into the requested output format. If the user did not specify a format, default to a summary.
+5. **Verify**: re-read the transformed output to check for coherence, correct timestamps, and completeness before presenting.
+
+## Error Handling
+
+- **Transcript disabled**: tell the user; suggest they check if subtitles are available on the video page.
+- **Private/unavailable video**: relay the error and ask the user to verify the URL.
+- **No matching language**: retry without `--language` to fetch any available transcript, then note the actual language to the user.
+- **Dependency missing**: run `uv pip install youtube-transcript-api==1.2.2` and retry.

package/built-in-skills/prismer-youtube-content/provenance/category-DESCRIPTION.md

@@ -0,0 +1,3 @@
+---
+description: Skills for working with media content — YouTube transcripts, GIF search, music generation, and audio visualization.
+---

package/built-in-skills/prismer-youtube-content/references/output-formats.md

@@ -0,0 +1,56 @@
+# Output Format Examples
+
+## Chapters
+
+```
+00:00 Introduction
+02:15 Background and motivation
+05:30 Main approach
+12:45 Results and evaluation
+18:20 Limitations and future work
+21:00 Q&A
+```
+
+## Summary
+
+A 5-10 sentence overview covering the video's main points, key arguments, and conclusions. Written in third person, present tense.
+
+## Chapter Summaries
+
+```
+## 00:00 Introduction (2 min)
+The speaker introduces the topic of X and explains why it matters for Y.
+
+## 02:15 Background (3 min)
+A review of prior work in the field, covering approaches A, B, and C.
+```
+
+## Thread (Twitter/X)
+
+```
+1/ Just watched an incredible talk on [topic]. Here are the key takeaways: 🧵
+
+2/ First insight: [point]. This matters because [reason].
+
+3/ The surprising part: [unexpected finding]. Most people assume [common belief], but the data shows otherwise.
+
+4/ Practical takeaway: [actionable advice].
+
+5/ Full video: [URL]
+```
+
+## Blog Post
+
+Full article with:
+- Title
+- Introduction paragraph
+- H2 sections for each major topic
+- Key quotes (with timestamps)
+- Conclusion / takeaways
+
+## Quotes
+
+```
+"The most important thing is not the model size, but the data quality." — 05:32
+"We found that scaling past 70B parameters gave diminishing returns." — 12:18
+```

package/built-in-skills/prismer-youtube-content/scripts/fetch_transcript.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+Fetch a YouTube video transcript and output it as structured JSON.
+
+Usage:
+    uv run python3 fetch_transcript.py <url_or_video_id> [--language en,tr] [--timestamps]
+
+Output (JSON):
+    {
+        "video_id": "...",
+        "language": "en",
+        "segments": [{"text": "...", "start": 0.0, "duration": 2.5}, ...],
+        "full_text": "complete transcript as plain text",
+        "timestamped_text": "00:00 first line\n00:05 second line\n..."
+    }
+
+Install dependency:  uv pip install youtube-transcript-api
+"""
+
+import argparse
+import json
+import re
+import sys
+import math
+from urllib.parse import urlparse, parse_qs
+
+
+def extract_video_id(url_or_id: str) -> str:
+    """Extract the 11-character video ID from various YouTube URL formats."""
+    url_or_id = url_or_id.strip()
+    if re.fullmatch(r'[a-zA-Z0-9_-]{11}', url_or_id):
+        return url_or_id
+    url = urlparse(url_or_id)
+    if url.scheme not in ('https', 'http') or url.username or url.password:
+        raise ValueError('Expected a YouTube URL or exact 11-character video ID')
+    if url.hostname == 'youtu.be':
+        candidate = url.path.removeprefix('/')
+    elif url.hostname in ('youtube.com', 'www.youtube.com', 'm.youtube.com'):
+        parts = url.path.strip('/').split('/')
+        if url.path == '/watch':
+            ids = parse_qs(url.query).get('v', [])
+            candidate = ids[0] if len(ids) == 1 else ''
+        else:
+            candidate = parts[1] if len(parts) == 2 and parts[0] in ('shorts', 'embed', 'live') else ''
+    else:
+        raise ValueError('Unsupported video host')
+    if not re.fullmatch(r'[a-zA-Z0-9_-]{11}', candidate):
+        raise ValueError('Invalid video ID')
+    return candidate
+
+
+def format_timestamp(seconds: float) -> str:
+    """Convert seconds to HH:MM:SS or MM:SS format."""
+    total = int(seconds)
+    h, remainder = divmod(total, 3600)
+    m, s = divmod(remainder, 60)
+    if h > 0:
+        return f"{h}:{m:02d}:{s:02d}"
+    return f"{m}:{s:02d}"
+
+
+def fetch_transcript(video_id: str, languages: list = None):
+    """Fetch transcript segments from YouTube.
+
+    Returns transcript metadata and normalized source segments.
+    Compatible with youtube-transcript-api v1.x.
+    """
+    try:
+        from youtube_transcript_api import YouTubeTranscriptApi
+    except ImportError:
+        print("Error: youtube-transcript-api not installed. Run: uv pip install youtube-transcript-api",
+              file=sys.stderr)
+        sys.exit(1)
+
+    api = YouTubeTranscriptApi()
+    result = api.fetch(video_id, languages=languages or ['en'])
+
+    # v1.x returns FetchedTranscriptSnippet objects; normalize to dicts
+    segments = [
+        {"text": seg.text, "start": seg.start, "duration": seg.duration}
+        for seg in result
+    ]
+    if not segments or not any(seg['text'].strip() for seg in segments):
+        raise ValueError('No transcript content found')
+    for seg in segments:
+        if not all(isinstance(seg[k], (float, int)) and math.isfinite(seg[k]) and seg[k] >= 0
+                   for k in ('start', 'duration')):
+            raise ValueError('Invalid transcript timing')
+    return {'segments': segments, 'language': result.language_code,
+            'is_generated': result.is_generated}
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Fetch YouTube transcript as JSON")
+    parser.add_argument("url", help="YouTube URL or video ID")
+    parser.add_argument("--language", "-l", default=None,
+                        help="Comma-separated language codes (e.g. en,tr). Default: en")
+    parser.add_argument("--timestamps", "-t", action="store_true",
+                        help="Include timestamped text in output")
+    parser.add_argument("--text-only", action="store_true",
+                        help="Output plain text instead of JSON")
+    args = parser.parse_args()
+
+    languages = [l.strip() for l in args.language.split(",")] if args.language else None
+
+    try:
+        video_id = extract_video_id(args.url)
+        if languages is not None and not all(languages):
+            raise ValueError('Language codes cannot be empty')
+        transcript = fetch_transcript(video_id, languages)
+        segments = transcript['segments']
+    except Exception as e:
+        error_msg = str(e)
+        if "disabled" in error_msg.lower():
+            print(json.dumps({"error": "Transcripts are disabled for this video."}))
+        elif "no transcript" in error_msg.lower():
+            print(json.dumps({"error": "No transcript found. Try specifying a language with --language."}))
+        else:
+            print(json.dumps({"error": error_msg}))
+        sys.exit(1)
+
+    full_text = " ".join(seg["text"] for seg in segments)
+    timestamped = "\n".join(
+        f"{format_timestamp(seg['start'])} {seg['text']}" for seg in segments
+    )
+
+    if args.text_only:
+        print(timestamped if args.timestamps else full_text)
+        return
+
+    result = {
+        **transcript,
+        "video_id": video_id,
+        "source_url": f"https://www.youtube.com/watch?v={video_id}",
+        "segment_count": len(segments),
+        "duration": format_timestamp(max(s['start'] + s['duration'] for s in segments)),
+        "full_text": full_text,
+    }
+    if args.timestamps:
+        result["timestamped_text"] = timestamped
+
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/built-in-skills/research-arxiv/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+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.

package/built-in-skills/research-arxiv/NOTICE.md

@@ -0,0 +1,4 @@
+Adapted from Nous Research Hermes Agent skills/research/arxiv,
+revision 1a1f4a59e252e1dc0137e7b2e7bcc8b0381d19c4 (MIT; see LICENSE).
+Prismer changes: version-preserving Atom parser, bounded HTTP and CLI validation,
+structured output, task delivery and citation integration.

package/built-in-skills/research-arxiv/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: research-arxiv
+scope: common
+category: research
+description: "Search arXiv papers by keyword, author, category, or ID."
+version: 1.0.0
+author: Hermes Agent
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  nativeReplaces: [arxiv]
+  upstream: Hermes Agent skills/research/arxiv at 1a1f4a59e2
+  hermes:
+    tags: [Research, Arxiv, Papers, Academic, Science, API]
+    related_skills: [office-artifacts, evidence-citations]
+---
+
+# arXiv Research
+
+Search and retrieve academic papers from arXiv via their REST API. No API key.
+Use the shipped Python 3.9+ standard-library script relative to this installed
+skill directory, not a hardcoded Hermes repository path:
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning" --max 5 --json
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 1706.03762v1 --json
+```
+
+The script preserves versioned identifiers and full abstracts, bounds response
+size and retries transient HTTP errors, and rejects malformed feeds/options.
+`unknown` metadata is a coverage gap, not permission to invent dates. Use
+`evidence-citations` for quotations and `office-artifacts` for PDFs. Attach only
+requested file outputs through `cloud task attach`/`cloud deliver`; honor PKF
+carrier instructions for inline answers. Abstract retrieval is not full-paper reading.
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Search papers | `curl "https://export.arxiv.org/api/query?search_query=all:QUERY&max_results=5"` |
+| Get specific paper | `curl "https://export.arxiv.org/api/query?id_list=2402.03300"` |
+| Read abstract (web) | `web_extract(urls=["https://arxiv.org/abs/2402.03300"])` |
+| Read full paper (PDF) | `web_extract(urls=["https://arxiv.org/pdf/2402.03300"])` |
+
+## Searching Papers
+
+The API returns Atom XML. Use an XML parser (the shipped script), not grep/sed.
+
+### Basic search
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?search_query=all:GRPO+reinforcement+learning&max_results=5"
+```
+
+### Clean output
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning" --max 5 --sort date
+```
+
+## Search Query Syntax
+
+| Prefix | Searches | Example |
+|--------|----------|---------|
+| `all:` | All fields | `all:transformer+attention` |
+| `ti:` | Title | `ti:large+language+models` |
+| `au:` | Author | `au:vaswani` |
+| `abs:` | Abstract | `abs:reinforcement+learning` |
+| `cat:` | Category | `cat:cs.AI` |
+| `co:` | Comment | `co:accepted+NeurIPS` |
+
+### Boolean operators
+
+```
+# AND (default when using +)
+search_query=all:transformer+attention
+
+# OR
+search_query=all:GPT+OR+all:BERT
+
+# AND NOT
+search_query=all:language+model+ANDNOT+all:vision
+
+# Exact phrase
+search_query=ti:"chain+of+thought"
+
+# Combined
+search_query=au:hinton+AND+cat:cs.LG
+```
+
+## Sort and Pagination
+
+| Parameter | Options |
+|-----------|---------|
+| `sortBy` | `relevance`, `lastUpdatedDate`, `submittedDate` |
+| `sortOrder` | `ascending`, `descending` |
+| `start` | Result offset (0-based) |
+| `max_results` | Number of results (default 10, max 30000) |
+
+```bash
+# Latest 10 papers in cs.AI
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?search_query=cat:cs.AI&sortBy=submittedDate&sortOrder=descending&max_results=10"
+```
+
+## Fetching Specific Papers
+
+```bash
+# By arXiv ID
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?id_list=2402.03300"
+
+# Multiple papers
+curl --fail --silent --show-error --max-time 30 "https://export.arxiv.org/api/query?id_list=2402.03300,2401.12345,2403.00001"
+```
+
+## BibTeX Generation
+
+Retrieve structured metadata using `--json`, retaining the complete versioned ID.
+Register the inspected abstract/PDF URL and title with `evidence-citations`, then
+export its escaped `--style bibtex` entries. For article-specific author/year/
+primaryClass fields, use only returned metadata and a BibTeX serializer; leave
+missing fields absent rather than inventing a category or author. Compile the
+actual bibliography and verify rendered URLs and unresolved-citation warnings.
+
+## Reading Paper Content
+
+After finding a paper, read it:
+
+```
+# Abstract page (fast, metadata + abstract)
+web_extract(urls=["https://arxiv.org/abs/2402.03300"])
+
+# Full paper (PDF → markdown via Firecrawl)
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+```
+
+For local PDF processing, see `office-artifacts`. Use an available extraction
+tool; these examples do not imply a Firecrawl account or full-text entitlement.
+
+## Common Categories
+
+| Category | Field |
+|----------|-------|
+| `cs.AI` | Artificial Intelligence |
+| `cs.CL` | Computation and Language (NLP) |
+| `cs.CV` | Computer Vision |
+| `cs.LG` | Machine Learning |
+| `cs.CR` | Cryptography and Security |
+| `stat.ML` | Machine Learning (Statistics) |
+| `math.OC` | Optimization and Control |
+| `physics.comp-ph` | Computational Physics |
+
+Full list: https://arxiv.org/category_taxonomy
+
+## Helper Script
+
+The `scripts/search_arxiv.py` script handles XML parsing and provides clean output:
+
+```bash
+python3 "<skill-dir>/scripts/search_arxiv.py" "GRPO reinforcement learning"
+python3 "<skill-dir>/scripts/search_arxiv.py" "transformer attention" --max 10 --sort date
+python3 "<skill-dir>/scripts/search_arxiv.py" --author "Yann LeCun" --max 5
+python3 "<skill-dir>/scripts/search_arxiv.py" --category cs.AI --sort date
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 2402.03300
+python3 "<skill-dir>/scripts/search_arxiv.py" --id 2402.03300,2401.12345
+```
+
+No dependencies — uses only Python stdlib.
+
+---
+
+## Semantic Scholar (Citations, Related Papers, Author Profiles)
+
+arXiv doesn't provide citation data or recommendations. The optional **Semantic
+Scholar API** provides JSON. Check current endpoint access, authentication and
+rate-limit responses; do not assume a fixed public or API-key quota.
+
+### Get paper details + citations
+
+```bash
+# By arXiv ID
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300?fields=title,authors,citationCount,referenceCount,influentialCitationCount,year,abstract" | python -m json.tool
+
+# By Semantic Scholar paper ID or DOI
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example?fields=title,citationCount"
+```
+
+### Get citations OF a paper (who cited it)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/citations?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
+```
+
+### Get references FROM a paper (what it cites)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:2402.03300/references?fields=title,authors,year,citationCount&limit=10" | python -m json.tool
+```
+
+### Search papers (alternative to arXiv search, returns JSON)
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/search?query=GRPO+reinforcement+learning&limit=5&fields=title,authors,year,citationCount,externalIds" | python -m json.tool
+```
+
+### Get paper recommendations
+
+```bash
+curl --fail --silent --show-error --max-time 30 -X POST "https://api.semanticscholar.org/recommendations/v1/papers/" \
+  -H "Content-Type: application/json" \
+  -d '{"positivePaperIds": ["arXiv:2402.03300"], "negativePaperIds": []}' | python -m json.tool
+```
+
+### Author profile
+
+```bash
+curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/author/search?query=Yann+LeCun&fields=name,hIndex,citationCount,paperCount" | python -m json.tool
+```
+
+### Useful Semantic Scholar fields
+
+`title`, `authors`, `year`, `abstract`, `citationCount`, `referenceCount`, `influentialCitationCount`, `isOpenAccess`, `openAccessPdf`, `fieldsOfStudy`, `publicationVenue`, `externalIds` (contains arXiv ID, DOI, etc.)
+
+---
+
+## Complete Research Workflow
+
+1. **Discover**: `python3 "<skill-dir>/scripts/search_arxiv.py" "your topic" --sort date --max 10`
+2. **Assess impact**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID?fields=citationCount,influentialCitationCount"`
+3. **Read abstract**: `web_extract(urls=["https://arxiv.org/abs/ID"])`
+4. **Read full paper**: `web_extract(urls=["https://arxiv.org/pdf/ID"])`
+5. **Find related work**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/paper/arXiv:ID/references?fields=title,citationCount&limit=20"`
+6. **Get recommendations**: POST to Semantic Scholar recommendations endpoint
+7. **Track authors**: `curl --fail --silent --show-error --max-time 30 "https://api.semanticscholar.org/graph/v1/author/search?query=NAME"`
+
+## Rate Limits
+
+| API | Rate | Auth |
+|-----|------|------|
+| arXiv | Space requests by at least 3 seconds; honor server limits | No key for public metadata |
+| Semantic Scholar | Honor current service limits and Retry-After | Endpoint/account dependent |
+
+## Notes
+
+- arXiv returns Atom XML — use the helper script or parsing snippet for clean output
+- Semantic Scholar returns JSON — pipe through `python -m json.tool` for readability
+- arXiv IDs: old format (`hep-th/0601001`) vs new (`2402.03300`)
+- PDF: `https://arxiv.org/pdf/{id}` — Abstract: `https://arxiv.org/abs/{id}`
+- HTML (when available): `https://arxiv.org/html/{id}`
+- For local PDF processing, see `office-artifacts`.
+
+## ID Versioning
+
+- `arxiv.org/abs/1706.03762` always resolves to the **latest** version
+- `arxiv.org/abs/1706.03762v1` points to a **specific** immutable version
+- When generating citations, preserve the version suffix you actually read to prevent citation drift (a later version may substantially change content)
+- The API `<id>` field returns the versioned URL (e.g., `http://arxiv.org/abs/1706.03762v7`)
+
+## Withdrawn Papers
+
+Papers can be withdrawn after submission. When this happens:
+- The `<summary>` field contains a withdrawal notice (look for "withdrawn" or "retracted")
+- Metadata fields may be incomplete
+- Always check the summary before treating a result as a valid paper