oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-scholar/resources/execution-protocol.md

@@ -0,0 +1,224 @@
+# Scholar - Execution Protocol
+
+Choose the mode based on user intent, then follow its steps.
+
+## Mode 1: Generate
+
+Create a `.knows.yaml` sidecar from a paper, draft, or research notes.
+
+### Step 0: Gather Source
+
+1. Identify input: PDF path, LaTeX file, plain text, or pasted content
+2. If PDF and only path is given -> chain via `oma-pdf` first to extract markdown
+3. Determine output path: `{base}.knows.yaml` next to input (or as configured)
+
+### Step 1: Read Source Thoroughly
+
+- Read the entire source: abstract, methods, results, discussion, limitations
+- Identify: claims, methods, evidence (tables/figures), datasets, code/repo links, cited works, assumptions
+- Note paper metadata: title, authors, venue, year, DOI (only if visible)
+
+### Step 2: Draft Sidecar Structure
+
+Use the local production compatibility rules in `sidecar-spec.md`; they do not establish full canonical-schema conformance. Top-level structure:
+
+- `knows_version: "0.9.0"`, `profile: "paper@1"`, `subject_ref: art:paper`
+- **Top-level metadata**: `title`, `authors`, `venue`, `year` (no `metadata` wrapper); omit `doi`/`venue`/`year` if not visible
+- `summary`: one-paragraph overview
+- `coverage`: object with `statements` and `evidence` enums (NOT a single value)
+- `provenance`: `origin`, single `actor` object (`type: tool|person|org`), `generated_at`, `method`
+- `version`: `{spec, record, source}`
+- `freshness`: `{as_of, update_policy}`
+- `artifacts`: list (`art:` prefix, `artifact_type`, `role: subject|supporting|cited`); include `representations` for the source
+- `statements`: list (`stmt:` prefix, `statement_type`, `modality`, `status`, `confidence` object, `source_anchors`)
+- `evidence`: list (`ev:` prefix, `evidence_type`)
+- `relations`: list (`rel:` prefix, `predicate` in present tense, `subject_ref`, `object_ref`)
+- `actions`: usually empty for paper profile
+
+### Step 3: Wire Relations
+
+Use relations appropriate to the statement type and supported by the source.
+Claims with evidence use `supported_by`; methods may use `uses`, `implements`,
+or `evaluates_on`. Definitions and open questions can remain source-anchored
+without invented empirical support. The lint ratio target of 1.5 is a coverage
+diagnostic, not a requirement to pad the graph. Common patterns:
+
+| Subject | Predicate | Object |
+|---------|-----------|--------|
+| Claim | `supported_by` | Evidence |
+| Claim | `depends_on` | Assumption |
+| Method | `evaluates_on` | Dataset |
+| Method | `implements` | Code repo |
+| Paper | `cites` | Other paper (optional `citation_intent`) |
+| Claim | `challenged_by` | Counter-claim / prior work |
+
+### Step 4: Optional Metadata Enrichment
+
+If `OPENALEX_API_KEY` is set and DOI/venue/year are missing:
+
+```bash
+# PAPER_TITLE is the source title; inspect candidates before selecting a record.
+curl -s --get "https://api.openalex.org/works" \
+  --data-urlencode "search=$PAPER_TITLE" \
+  --data-urlencode "api_key=$OPENALEX_API_KEY" \
+  | jq '.results[] | {id, title, doi, publication_year, authorships, primary_location}'
+```
+
+If the key is not set, skip enrichment and tell the user how to set it (point to `setup-openalex.md`).
+
+Verify candidate identity against the source title, authors, year, and any
+existing DOI/arXiv identifier before enrichment. A title-search ranking is not
+identity proof. Confirm a selected DOI with a DOI lookup; omit disputed fields
+when candidates remain ambiguous. A curated catalog is an external source,
+and local structural lint cannot verify that it describes the same paper.
+Mention in the final report which fields were enriched rather than extracted from source.
+
+### Step 5: Lint
+
+Always validate before reporting done:
+
+```bash
+oma scholar lint {output}.knows.yaml
+```
+
+For newly generated local-profile output, fix reported issues and re-run. For imported canonical records, preserve valid wider shapes, report local-lint incompatibilities, and do not silently normalize away information.
+
+### Step 6: Report
+
+Tell the user:
+- Output path
+- Statement count, evidence count, relations/statement ratio
+- Any fields omitted due to anti-fabrication (e.g., "DOI not extracted; visible in source? If yes, paste it.")
+- Lint status
+
+## Mode 2: Validate
+
+Lint an existing `.knows.yaml`.
+
+### Steps
+
+1. Confirm input file exists and ends with `.knows.yaml`, `.yaml`, or `.json`
+2. Decide strictness based on origin:
+   - **Own Generate output** → strict (default)
+   - **Third-party / remote sidecar** → `--lenient` (dangling refs become warnings)
+3. Run lint:
+   ```bash
+   oma scholar lint {input}
+   # OR for fetched sidecars:
+   oma scholar lint --lenient {input}
+   ```
+4. Read output; group findings by severity (error/warning)
+5. Report file:line for each issue with the rule violated and the fix
+6. Offer to apply fixes if the user agrees
+
+## Mode 3: Review
+
+Generate a peer-review sidecar covering what claims need stronger evidence, what assumptions are unstated, and what limitations are missing.
+
+### Steps
+
+1. Read the source paper (or its existing sidecar)
+2. For each statement in the paper, evaluate:
+   - Is `supported_by` evidence sufficient?
+   - Is `depends_on` assumption explicit?
+   - Are limitations acknowledged?
+3. Produce review sidecar at `{base}.review.knows.yaml` with:
+   - `profile: "review@1"` (not `paper@1`)
+   - top-level `coverage`: `{statements: key_claims_and_limitations, evidence: partial}`
+   - `statements` capturing reviewer assertions using the **closed `statement_type`
+     enum**: weaknesses and strengths as `claim`, identified gaps as `limitation`,
+     open issues as `question` (there is no `review_comment` type)
+   - `relations` linking the reviewed paper's claims to reviewer weaknesses via
+     `predicate: challenged_by`, using the **cross-record reference grammar**
+     `record_id#local_id` for the original paper's side:
+
+   ```yaml
+   relations:
+     - id: rel:generalization-challenges-main-claim
+       predicate: challenged_by
+       subject_ref: "knows:examples/resnet/1.0.0#stmt:main-contribution"  # original paper's claim
+       object_ref: "stmt:missing-ablation-study"                          # this review's weakness
+   ```
+
+4. Lint and report (same as Generate). `oma scholar lint` recognizes
+   `record_id#local_id` cross-record refs and does not flag them as dangling.
+
+## Mode 4: Analyze / Query
+
+Answer natural-language questions over an existing sidecar.
+
+### Steps
+
+1. Locate sidecar: local path or `oma scholar get "{record_id}"` from knows.academy
+2. For token efficiency, prefer **partial fetch** when only a subset is needed.
+   The query param is **`section` (singular)**; allowed values are `statements|evidence|relations|artifacts|citation`:
+   - "What claims does this paper make?" -> `?section=statements`
+   - "What are the experimental results?" -> `?section=evidence`
+   - "Who do they cite?" -> `?section=citation` (or `?section=artifacts` filtered by `role: cited`)
+3. Parse YAML, traverse structure to answer
+4. Cite IDs (`stmt:...`, `ev:...`) so the user can verify
+
+## Mode 5: Compare
+
+Structural diff between two sidecars.
+
+### Steps
+
+1. Load both sidecars (local or remote)
+2. Build comparison table:
+   - **Claims overlap**: shared `statement_type` themes
+   - **Method differences**: same dataset? different metrics?
+   - **Evidence quality**: relations-per-statement ratio for each
+   - **Citation overlap**: shared `artifacts` with `role: cited`
+3. Output a markdown table; cite specific IDs from each paper
+4. Optional: surface opposing claims (search for `predicate: challenged_by` relations or `citation_intent: contradicts` on `cites`)
+
+## Mode 6: Remote (with OpenAlex / Semantic Scholar fallback)
+
+Search and fetch from knows.academy first, then fall back to OpenAlex when the
+paper isn't in the (2026-only) knows.academy index, then to Semantic Scholar
+(AI TL;DR + citation counts) when OpenAlex also has nothing.
+
+### Recommended path: `oma scholar` (handles cascade automatically)
+
+```bash
+# Hybrid search
+oma scholar search "<query>"
+
+# Cross-source resolve (decides which source has the right paper)
+oma scholar resolve "<title>"
+
+# Get specific record (knows id, OpenAlex W-id, DOI, arXiv:<id>, CorpusId:<n>)
+oma scholar get [--section <one>] "<id>"
+```
+
+See `resources/fallback-providers.md` for full cascade design.
+
+### Manual cascade (raw curl)
+
+1. **knows.academy search**: `curl -s "{base}/api/proxy/search?q={query}"`
+2. If hits → fetch sidecar:
+   - Full: `/api/proxy/sidecars/{record_id}`
+   - Partial: `/api/proxy/partial?record_id={id}&section=statements|evidence|relations|artifacts|citation`
+3. If no hits OR clearly wrong paper (cross-source title similarity < 0.7) →
+   **OpenAlex fallback**:
+   - `curl -s "https://api.openalex.org/works?search={query}"` (anonymous OK)
+   - Or by DOI: `https://api.openalex.org/works/doi:{doi}`
+   - Reconstruct abstract from `abstract_inverted_index`
+4. If user wants a sidecar from the OpenAlex result → transition to **Mode 1 Generate**
+   using the abstract as the source text. The local sidecar will not be on
+   knows.academy but is structurally identical.
+5. **Stats** (health check): `curl -s "{base}/api/proxy/jobs/stats"`
+6. If user asks for analysis after fetch, transition to **Mode 4** (Analyze)
+
+## Error Recovery
+
+| Error | Recovery |
+|-------|----------|
+| `oma scholar` not found | Run `oma install` to install / update the CLI |
+| Lint script reports many errors | Fix top error first; re-run; cascading errors often resolve together |
+| Remote API timeout | Retry once; if still failing, check `/api/proxy/jobs/stats` |
+| Empty search results | Broaden query; remove quotes; try keyword-only |
+| YAML parse error after Generate | Re-emit with stricter quoting on string values containing `:` `#` `&` `*` |
+| Source PDF has no text layer | Chain via `oma-pdf` with hybrid OCR mode first |
+| OpenAlex 403/429 | Tell user to set `OPENALEX_API_KEY`; see `setup-openalex.md` |

package/skills/oma-scholar/resources/fallback-providers.md

@@ -0,0 +1,143 @@
+# Fallback Provider Cascade
+
+`oma-scholar` queries `knows.academy` first, then falls back to OpenAlex, then
+Semantic Scholar for records the platform doesn't have. The fallback is what
+makes the skill useful beyond the (currently 2026-only) knows.academy index.
+
+## Coverage Matrix
+
+| Source | Coverage | Gives | Doesn't give |
+|--------|----------|-------|--------------|
+| **knows.academy** | **2026 only**, mostly arXiv (verified empirically; current counts via `/api/proxy/jobs/stats`) | Full v0.9 sidecar (claims, evidence, relations, methods) | Pre-2026 papers, full text |
+| **OpenAlex** | ~240M works, all years | Title, authors, year, venue, DOI, abstract (reconstructed), OA PDF URL, citation count, references | Structured claims/evidence (no sidecar) |
+| **Semantic Scholar** | ~214M papers, all years (Ai2) | AI TL;DR, abstract (verbatim), citation + influential-citation counts, arXiv/DOI/CorpusId cross-ids, OA PDF URL | Structured claims/evidence; anonymous access 429s under load |
+
+When a paper is in **both**, prefer knows.academy (richer structure). When a
+paper is **only in OpenAlex** (most pre-2026 work), use OpenAlex metadata as
+the source for **Mode 1 Generate**, where the host LLM produces a local sidecar from
+the abstract.
+
+## Cascade Logic
+
+```
+search "query"
+   │
+   ├─ knows.academy ── any hits? ──► return immediately (sidecars available)
+   │     │
+   │     no hits
+   │     ▼
+   ├─ openalex ──── any hits? ────► return metadata + abstract (no sidecar)
+   │     │
+   │     no hits
+   │     ▼
+   └─ semanticscholar ───────────► return metadata + TL;DR + citations
+                                  ↓
+                             user wants deeper? → Mode 1 Generate locally
+```
+
+`--always-fallback` includes every tier regardless of earlier hits.
+
+## CLI Reference (`oma scholar`)
+
+### Search both sources
+
+```bash
+oma scholar search "vision language action"
+```
+
+Returns JSON with:
+- `primary`: which source returned hits
+- `fallback`: which source was used as fallback (if any)
+- `results`: unified list with `source: "knows.academy" | "openalex"` per item
+
+### Get a specific record
+
+```bash
+# knows.academy sidecar
+oma scholar get "knows:generated/reconvla/1.0.0"
+
+# Partial fetch (saves up to 93% tokens)
+oma scholar get --section statements "knows:generated/reconvla/1.0.0"
+
+# OpenAlex by DOI
+oma scholar get "10.48550/arXiv.1706.03762"
+
+# OpenAlex by W-id
+oma scholar get "W2147144213"
+
+# Semantic Scholar: TL;DR + citation/influential-citation counts
+oma scholar get "arXiv:1706.03762"
+oma scholar get "CorpusId:13756489"
+```
+
+When `oma scholar get` is asked for a `knows:...` id and the platform is
+unreachable, the command extracts the slug from the record_id and searches
+OpenAlex for the same paper, returning metadata with a `fallback: "openalex"`
+marker. The user can then run **Mode 1 Generate** from the abstract.
+
+### Resolve a title across all sources
+
+```bash
+oma scholar resolve "Attention Is All You Need"
+```
+
+Returns the best match from each source (knows.academy, OpenAlex, Semantic
+Scholar) side-by-side, plus a recommendation.
+
+## When Fallback is Needed
+
+Fallback to OpenAlex is the right move when:
+
+- **Pre-2026 papers**: knows.academy doesn't index them
+- **Cross-archive coverage**: non-arXiv venues, journals, books
+- **Citation counts**: knows.academy doesn't track citations; OpenAlex does
+- **Reference resolution**: when a sidecar's `cites` predicate points to a paper not in knows.academy
+
+Fallback is NOT needed for:
+- Recent (2026) arXiv papers, since knows.academy has them with rich sidecars
+- Full-text reading, since neither source provides full text; fetch the OA PDF and use `oma-pdf`
+
+## Local Generate from Fallback Result
+
+When OpenAlex returns metadata + abstract, but you want a structured sidecar:
+
+```
+1. oma scholar get <doi>        → get title, authors, year, venue, abstract
+2. (optional) download OA PDF   → oma-pdf to extract full text
+3. Mode 1 Generate              → host LLM produces .knows.yaml using sidecar-spec.md
+4. oma scholar lint             → validate locally
+```
+
+The locally-generated sidecar is **not registered** with knows.academy; it's
+yours. If you want it shared, that's a separate publishing flow (out of scope
+for this skill).
+
+## Authentication
+
+OpenAlex anonymous use is free up to ~$1/day. For higher limits or polite
+pool access, see `setup-openalex.md`. The skill works without any key.
+
+`oma scholar` reads:
+- `OPENALEX_API_KEY`: passed as `?api_key=` (recommended)
+- `OPENALEX_EMAIL`: passed as `?mailto=` (polite pool, no signup)
+- `S2_API_KEY`: Semantic Scholar key, passed as the `x-api-key` header
+
+None are required. Without `S2_API_KEY`, Semantic Scholar uses the shared
+anonymous pool, which 429s under load; the CLI retries once after a short
+delay, then skips the source. Request a free key via the form at
+https://www.semanticscholar.org/product/api (delivered by email; grants a
+dedicated 1 req/sec).
+
+## Trust Considerations
+
+- **knows.academy sidecars are AI-generated**: all have `provenance.origin: machine`. Verified `lint_passed: true` is platform-internal; our local `oma scholar lint` finds dangling refs in ~47% (use `--lenient` when consuming)
+- **OpenAlex metadata is curated**: generally reliable for title/authors/DOI/year, but venue and abstract can be missing for older works
+- **Reconstructed abstracts** from OpenAlex's inverted index are exact (no paraphrasing), but punctuation/formatting may be lossy
+- **Semantic Scholar TL;DRs are AI-generated** (Ai2's TLDR model): good `summary` seeds for Mode 1 Generate, but verify against the abstract before citing; citation counts differ from OpenAlex's (different corpora)
+
+## Limitations
+
+- arXiv-only papers without DOI may show `doi: None` in OpenAlex
+- Some 2026 papers exist in both sources with slightly different titles; `resolve` does case-insensitive contain matching as a heuristic
+- knows.academy proxy can timeout under load; fallback to OpenAlex is automatic
+- OpenAlex rate-limits: respect ~10 req/sec courtesy limit

package/skills/oma-scholar/resources/setup-openalex.md

@@ -0,0 +1,85 @@
+# OpenAlex API Key Setup (Optional)
+
+OpenAlex powers metadata enrichment during Generate mode by backfilling missing DOI, venue, and year from a vast academic catalog. **The skill works without a key**, but enrichment is skipped.
+
+## When you need this
+
+- You frequently generate sidecars from raw text/LaTeX where DOI is not visible
+- You want DOI/venue auto-resolved from the title
+- You hit anonymous rate limits ("$1/day" allowance exhausted)
+
+## Free Tier (Generous)
+
+Without any key, OpenAlex grants $1/day equivalent free quota:
+- **Unlimited** single-entity lookups
+- **10,000** list/filter calls per day
+- **1,000** search calls per day
+- **100** content downloads per day
+
+For most users, anonymous use is enough.
+
+## Get a Key (30 seconds)
+
+1. Sign up: https://openalex.org/
+2. Generate key: https://openalex.org/settings/api
+3. Copy the key
+
+## Configure
+
+### Option A: Per-shell environment
+
+```bash
+export OPENALEX_API_KEY="your_key_here"
+```
+
+### Option B: Persisted in `~/.claude/.env` (recommended)
+
+```bash
+mkdir -p ~/.claude
+echo 'OPENALEX_API_KEY=your_key_here' >> ~/.claude/.env
+```
+
+Some Claude Code setups source this file automatically; if not, source it from your shell rc:
+
+```bash
+echo '[ -f ~/.claude/.env ] && set -a && . ~/.claude/.env && set +a' >> ~/.zshrc
+```
+
+### Option C: Polite-pool email only (no key)
+
+If you don't want to sign up but want priority, set just an email:
+
+```bash
+export OPENALEX_EMAIL="you@example.com"
+```
+
+This puts you in the "polite pool" with better latency, no key required.
+
+## Verify
+
+```bash
+curl -s "https://api.openalex.org/works?search=attention+is+all+you+need&api_key=$OPENALEX_API_KEY" \
+  | head -c 500
+```
+
+A 200 response with JSON results means the key is live.
+
+## Pricing Beyond Free Tier
+
+OpenAlex uses pay-as-you-go past the daily free allowance, with no monthly subscription. Most academic users never exceed the free tier. See https://openalex.org/pricing for current rates.
+
+## Skill Behavior
+
+When this skill needs metadata enrichment:
+
+1. Check `OPENALEX_API_KEY` env var
+2. If set -> use authenticated calls
+3. If not set, check `OPENALEX_EMAIL` -> anonymous polite-pool
+4. If neither, fall back to anonymous calls
+5. On 403/429 -> stop enrichment, tell user to set the key, leave fields omitted (anti-fabrication)
+
+## Privacy
+
+- The key (or email) is sent to OpenAlex servers as a query parameter
+- No source paper content is sent to OpenAlex; only title/author search strings
+- OpenAlex is operated by OurResearch (a non-profit); see their privacy policy at https://openalex.org/