Oma Scholar

Scholar - Research Paper Sidecar Companion

Scheduling

Goal

Search, fetch, generate, validate, analyze, review, and compare scholarly paper sidecars using the Knows .knows.yaml spec for token-efficient research workflows.

Intent signature

• User asks for academic literature search, sidecar generation, sidecar validation, paper claims/evidence summary, structural paper comparison, or peer review as sidecar.
• User references Knows, .knows.yaml, knows.academy, OpenAlex, claims, evidence, relations, or paper sidecars.

When to use

• Reading research papers token-efficiently via Knows sidecars (~700 tokens for claims-only vs ~10K for full PDF)
• Generating .knows.yaml sidecars from your own paper drafts, LaTeX, or research notes
• Validating sidecar structure (rule-based) before sharing
• Producing peer reviews as sidecars
• Querying or summarizing existing sidecars
• Structurally comparing two papers (claims, methods, evidence)
• Searching/fetching sidecars from knows.academy (~50K papers indexed)

When NOT to use

• General web search or non-academic content -> use oma-search
• Translating papers -> use oma-translator
• PDF parsing only (no sidecar) -> use oma-pdf
• Submitting sidecars back to knows.academy -> out of scope (host LLM only consumes/produces locally)
• Full peer-review workflow with editor system -> out of scope

Expected inputs

• Paper, abstract, draft, LaTeX, research notes, sidecar file, DOI, OpenAlex ID, Knows record ID, or search query
• Desired mode: generate, validate, review, analyze, compare, or remote fetch
• Optional strictness, section filter, or CI behavior

Expected outputs

• .knows.yaml sidecar, review sidecar, lint report, search/fetch result, natural-language analysis, or structural comparison
• Sidecars conforming to v0.9.0 / paper@1 profile
• Validation status and warnings before sharing generated sidecars

Dependencies

• oma scholar CLI subcommands
• knows.academy public API and OpenAlex fallback
• resources/sidecar-spec.md, API endpoints, OpenAlex setup, upstream cache, checklist, and execution protocol

Control-flow features

• Branches by mode, source availability, Knows/OpenAlex coverage, strict vs lenient validation, and fetched section
• Reads/writes YAML sidecars and may call public APIs
• Avoids fabrication when source evidence is missing

Structural Flow

Entry

1. Identify mode and source artifact/query. 2. Resolve paper identity through Knows or OpenAlex when needed. 3. Load sidecar spec and mode-specific protocol.

Scenes

1. PREPARE: Select mode and gather source or remote identifiers. 2. ACQUIRE: Fetch paper metadata, sidecar sections, or local source text. 3. REASON: Extract claims, evidence, relations, provenance, or comparison structure. 4. ACT: Generate, lint, review, analyze, compare, or fetch sidecar data. 5. VERIFY: Validate schema, enums, IDs, relations, and provenance. 6. FINALIZE: Return sidecar, report, summary, or comparison with caveats.

Transitions

• If knows.academy lacks the paper, fall back to OpenAlex metadata/abstract.
• If generating a sidecar, run lint before sharing.
• If consuming third-party sidecars with dangling references, use lenient mode when appropriate.
• If source evidence is absent, omit fields instead of guessing.

Failure and recovery

• If remote API times out, retry or use OpenAlex fallback.
• If YAML fails parsing, fix indentation and scalar types.
• If relation density or orphan statements warn, add supported-by relations when source evidence supports them.

Exit

• Success: requested sidecar operation completes with validation status.
• Partial success: missing metadata, fallback source, or validation warnings are explicit.

Logical Operations

Actions

Tools and instruments

• oma scholar search|resolve|get|lint
• Knows public API, OpenAlex fallback, sidecar spec, checklist

Canonical command path

oma scholar search "<query>"
oma scholar resolve "<title-or-doi>"
oma scholar get "<record-id-or-doi>"
oma scholar lint "<paper.knows.yaml>"

Resource scope

Preconditions

• Mode and source are identifiable.
• Spec rules are available for generation or validation.

Effects and side effects

• May create local sidecar or review sidecar files.
• May query public scholarly APIs.
• Does not submit sidecars back to knows.academy.

Guardrails

1. Target spec is v0.9.0 / `paper@1` profile: verified against production sidecars from knows.academy; see resources/sidecar-spec.md 2. Host LLM generates sidecars: never shell out to anthropic SDK or external LLM CLI; this skill runs inside an agent 3. Anti-fabrication: if DOI/venue/year is not visible in source, omit the key entirely; never write doi: TODO or guess 4. Top-level metadata: title, authors, venue, year live at the top level (no metadata wrapper) 5. Field names are exact: statement_type, evidence_type, predicate, artifact_type (not type/claim) 6. Provenance has SINGLE actor: provenance.actor is one object, NOT a provenance.actors array 7. Confidence is an object: {claim_strength: ..., extraction_fidelity: ...}, both from high|medium|low 8. Coverage is an object: coverage.statements (4-value enum) + coverage.evidence (3-value enum) 9. Closed enums: actor tool|person|org (never ai/llm/model); artifact role subject|supporting|cited; predicates in present tense 10. Numbers unquoted: value: 22, never value: '22' 11. Relation density: average ≥1.5 relations per statement; every claim needs supported_by evidence (lint warns when ratio is below; orphan statements warned per-id) 12. ID format: descriptive kebab-case with prefix: stmt:privacy-budget-tradeoff, ev:cifar10-accuracy-table, art:paper 13. Validate before sharing: run oma scholar lint after Generate 14. Remote API has no auth: https://knows.academy/api/proxy/* is public; do not invent auth headers 15. Partial fetch param is `section` (singular): fixed enum statements|evidence|relations|artifacts|citation 16. OpenAlex key is optional: metadata enrichment only; gracefully degrade when missing 17. Sidecar content stays English: schema fields, IDs, statement text follow upstream convention; user-facing responses follow oma-config.yaml language 18. Spec drift awareness: our local rules track v0.9.0 production behavior, which differs from the upstream knows.md natural-language description; refresh resources/upstream-spec-cache.md periodically

Modes

Provider Fallback (knows.academy → OpenAlex)

knows.academy currently indexes only 2026 papers (~50K, mostly arXiv). For older or non-2026 papers (Transformer 2017, BERT 2018, classics, journals), the skill automatically falls back to OpenAlex for metadata and abstract.

Use the oma scholar CLI subcommands:

# Hybrid search: knows first, OpenAlex fallback
oma scholar search "vision language action"

# Cross-source resolve: figures out which source has the right paper
oma scholar resolve "Attention Is All You Need"

# Get by id (knows record_id, OpenAlex W-id, or DOI)
oma scholar get "10.48550/arXiv.1706.03762"

When OpenAlex returns the answer (knows.academy lacks the paper), use the returned abstract as input to Mode 1 Generate to produce a local sidecar.

How to Execute

Follow resources/execution-protocol.md step by step for the selected mode.

Quick Reference

Search (knows + auto OpenAlex fallback)

oma scholar search "diffusion super resolution"
oma scholar search --year-min 2024 "vision language action"

Find one specific paper

oma scholar resolve "Attention Is All You Need"
# returns top hit from each source + recommendation

Fetch a sidecar or work

# knows.academy full sidecar
oma scholar get "knows:generated/reconvla/1.0.0"

# Partial fetch (claims only, ~700 tokens, 93% reduction vs PDF)
oma scholar get --section statements "knows:generated/reconvla/1.0.0"

# By DOI or OpenAlex W-id (works regardless of knows.academy availability)
oma scholar get "10.48550/arXiv.1706.03762"

When knows.academy is unreachable, get knows:... automatically falls back to OpenAlex by extracting the slug from the record_id. The result is marked with fallback: "openalex" and contains metadata + abstract, useful for running Mode 1 Generate locally.

Validate

# Strict mode for own Generate output (default)
oma scholar lint paper.knows.yaml

# Lenient mode for third-party / fetched sidecars
oma scholar lint --lenient remote.knows.yaml

# Treat warnings as failures (CI mode)
oma scholar lint --fail-on-warning paper.knows.yaml

About 47% of knows.academy-served sidecars contain at least one dangling cross-reference (typo in subject_ref/object_ref, measured across 15 production samples). Use --lenient when consuming third-party records so these surface as warnings rather than blocking errors.

Raw API (when CLI is unavailable)

curl -s "https://knows.academy/api/proxy/search?q=..."
curl -s "https://knows.academy/api/proxy/sidecars/<encoded-id>"
curl -s "https://knows.academy/api/proxy/partial?record_id=<id>&section=statements"
curl -s "https://knows.academy/api/proxy/jobs/stats"   # platform health

Configuration

Project-specific settings: config/scholar-config.yaml

Troubleshooting

References

• Execution steps: resources/execution-protocol.md
• Sidecar spec rules: resources/sidecar-spec.md
• API endpoints: resources/api-endpoints.md
• OpenAlex setup: resources/setup-openalex.md
• Upstream spec snapshot: resources/upstream-spec-cache.md
• Post-generation checklist: resources/checklist.md
• CLI subcommands: oma scholar search|resolve|get|lint (implementation under cli/commands/scholar/)
• Context loading: ../_shared/core/context-loading.md
• Quality principles: ../_shared/core/quality-principles.md
• i18n rules: ../../rules/i18n-guide.md

knows.academy API Endpoints

Base URL: https://knows.academy

All endpoints are public proxies. No authentication required, so do not invent or send Authorization headers.

Search

GET /api/proxy/search?q={query}
GET /api/proxy/search?q={query}&discipline={field}

curl -s "https://knows.academy/api/proxy/search?q=diffusion+super+resolution"

Response shape (verified):

{
  "results": [
    {
      "record_id": "knows:generated/{slug}/{version}",
      "profile": "paper@1",
      "title": "...",
      "summary": "...",
      "venue": "...",
      "year": 2026,
      "discipline": null,
      "keywords": [],
      "coverage_statements": "exhaustive",
      "coverage_evidence": "key_evidence_only",
      "provenance_origin": "machine",
      "provenance_actor_name": "knows-gen",
      "version_record": "1.0.0",
      "lint_passed": true,
      "download_count": 0,
      "created_at": "...",
      "stats": {...}
    }
  ]
}

record_id format: knows:generated/{slug}/{version} includes colons and slashes that must be URL-encoded when used as a path/query param.

Fetch Full Sidecar

GET /api/proxy/sidecars/{record_id}

The full v0.9.0 record (~22 KB / ~4.5K tokens, 55% smaller than the source PDF).

RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('knows:generated/{slug}/1.0.0', safe=''))")
curl -s "https://knows.academy/api/proxy/sidecars/${RID}"

Partial Fetch (Token-Saving)

GET /api/proxy/partial?record_id={id}&section={one_of}

Note: parameter is `section` (singular), value must match ^(statements|evidence|relations|artifacts|citation)$.

Available sections (verified):

• statements (typically ~700 tokens, 93% reduction vs full PDF)
• evidence
• relations
• artifacts
• citation

Not available via partial fetch: methods (statement_type), provenance. Fetch the full sidecar instead.

RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('knows:generated/{slug}/1.0.0', safe=''))")

# Just the claims
curl -s "https://knows.academy/api/proxy/partial?record_id=${RID}&section=statements"

# Evidence only
curl -s "https://knows.academy/api/proxy/partial?record_id=${RID}&section=evidence"

Response shape:

{
  "record_id": "...",
  "items": [...]
}

When to use partial vs full:

• "What claims does this paper make?" -> section=statements only
• "What experiments?" -> section=evidence
• "What does it cite?" -> section=citation (or section=artifacts filtered by role: cited)
• Multi-section analysis -> fetch full sidecar (cheaper than 3 partial calls)

Platform Stats

GET /api/proxy/jobs/stats

curl -s "https://knows.academy/api/proxy/jobs/stats"

Returns processing queue health (verified):

{
  "pending": 10735,
  "running": 288,
  "completed": 37897,
  "failed": 1243,
  "skipped": 433,
  "total": 50596
}

Use this for:

• Health check before bulk operations
• Estimating coverage ("how many papers are in the index?")
• Diagnosing slow responses

Skill Self-Description

GET /api/proxy/skill/knows.md

The canonical generation guide (natural language, slightly different from the JSON Schema). Refresh upstream-spec-cache.md from here.

JSON Schema (Reference)

Schema id used by sidecars: https://knows.dev/schema/record-0.9.json

The host knows.dev is currently unreachable (HTTPS times out as of 2026-04-25), so schema cannot be fetched directly. The oma scholar lint subcommand implements rules empirically derived from production records.

Rate Limiting

No hard limits documented. Be polite:

• Avoid bursting more than ~10 req/sec
• Cache responses locally for repeated queries within a session
• Prefer partial fetch over full when possible

Error Handling

URL Encoding

record_id contains : and /, so always URL-encode when placing in a path or query parameter. Examples:

# Bash with python3
RID=$(python3 -c "import urllib.parse; print(urllib.parse.quote('$RAW_RID', safe=''))")

# Or with jq
echo -n "$RAW_RID" | jq -sRr @uri

Notes

• Endpoints starting with /api/proxy/ are stable public routes
• Direct (non-proxy) endpoints may exist but are not contract-stable; do not rely on them
• This skill only consumes the API. Submission/upload is out of scope

Post-Generation Checklist (v0.9.0)

Run this after Mode 1 (Generate) or Mode 3 (Review) before reporting done.

Top-Level Structure

• [ ] title is set at the top level (not metadata.title)
• [ ] authors is a top-level list of strings
• [ ] venue, year, doi keys present only if visible in source (no TODO/TBD)
• [ ] knows_version set (e.g., "0.9.0")
• [ ] profile set (e.g., "paper@1")
• [ ] subject_ref points to an art: artifact id
• [ ] coverage is an object with statements and evidence keys (each from its own enum)
• [ ] provenance is present with single actor object (not actors array)
• [ ] version block has spec, record, source
• [ ] freshness block has as_of, update_policy

Provenance

• [ ] provenance.origin is machine or author
• [ ] provenance.actor.type is tool, person, or org (never ai/llm/model)
• [ ] provenance.actor.name is set
• [ ] provenance.method describes how the sidecar was produced (e.g., extraction)
• [ ] provenance.generated_at is a valid ISO timestamp

IDs

• [ ] All IDs use descriptive kebab-case (no stmt:c1, ev:001)
• [ ] Type prefixes correct: stmt:, ev:, rel:, art:, rep:
• [ ] No duplicate IDs across the document

Field Names

• [ ] Statements use statement_type (not type or claim)
• [ ] Evidence uses evidence_type
• [ ] Relations use predicate
• [ ] Artifacts use artifact_type

Statement Internals

• [ ] Each statement has statement_type from: claim, method, limitation, assumption, definition, question
• [ ] Each statement has modality from: descriptive, empirical, theoretical
• [ ] Each statement has status (commonly asserted)
• [ ] confidence is an object: {claim_strength: ..., extraction_fidelity: ...}, both from high|medium|low
• [ ] source_anchors reference a valid representation_ref (e.g., rep:paper-pdf)

Values

• [ ] Numbers unquoted (value: 22, not value: '22')
• [ ] coverage.statements from: exhaustive, main_claims_only, key_claims_and_limitations, partial
• [ ] coverage.evidence from: exhaustive, key_evidence_only, partial
• [ ] artifacts[].role from: subject, supporting, cited
• [ ] Predicates use present tense (evaluates_on, not evaluated_on)

Relations

• [ ] Every statement has at least one relation (incoming or outgoing)
• [ ] Every claim has a supported_by relation pointing to evidence
• [ ] Average relations-per-statement ratio ≥ 1.5
• [ ] Methods have at least one of: implements, uses, evaluates_on, documents
• [ ] No dangling references; every subject_ref and object_ref points to an existing id

Density

• [ ] Statement count appropriate for paper length (complex papers ≥ 15)
• [ ] Limitations and discussion mined for additional statements
• [ ] No important section ignored (abstract, methods, results, discussion, limits)

Lint

• [ ] oma scholar lint returns 0 errors
• [ ] Warnings reviewed (recommended-key warnings are usually acceptable for local drafts)

Anti-Fabrication

• [ ] No fabricated DOIs, ORCIDs, or URLs
• [ ] No "TODO", "TBD", "N/A" placeholder values
• [ ] All quoted statement text is paraphrased or quoted accurately from source
• [ ] No invented author names or affiliations

Final Report to User

Include:

• Output file path
• Counts: statements, evidence, relations, artifacts
• Ratio: relations/statements (target ≥ 1.5)
• Lint status: clean / N warnings / N errors
• Fields explicitly omitted due to anti-fabrication (e.g., "DOI not visible; please paste if you have it")

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 v0.9.0 spec rules in sidecar-spec.md. 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

For every statement, ensure at least one supported_by relation pointing to evidence. Aim for average ≥1.5 relations per statement. Common patterns:

Step 4: Optional Metadata Enrichment

If OPENALEX_API_KEY is set and DOI/venue/year are missing:

# Sketch — actual enrichment is best done via host LLM with a curl call
curl -s "https://api.openalex.org/works?search={title}&api_key=$OPENALEX_API_KEY" \
  | jq '.results[0] | {doi, host_venue, publication_year}'

If the key is not set, skip enrichment and tell the user how to set it (point to setup-openalex.md).

Step 5: Lint

Always validate before reporting done:

oma scholar lint {output}.knows.yaml

If lint fails, fix the reported issues and re-run until clean.

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:

   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:

• top-level coverage: {statements: key_claims_and_limitations, evidence: partial}
• statements capturing reviewer assertions, each with statement_type: review_comment (or limitation)
• relations linking review comments to original paper statements via predicate: critiques or extends

4. Lint and report (same as Generate)

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 contradicting claims (search for predicate: contradicts patterns)

Mode 6: Remote (with OpenAlex 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.

Recommended path: oma scholar (handles cascade automatically)

# 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, or DOI)
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

Fallback Provider Cascade

oma-scholar queries knows.academy first, then falls back to OpenAlex 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

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 ─────────────────► return metadata + abstract (no sidecar)
                                  ↓
                             user wants deeper? → Mode 1 Generate locally

CLI Reference (oma scholar)

Search both sources

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

# 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"

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 both

oma scholar resolve "Attention Is All You Need"

Returns the best match from each source 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)

Neither is required.

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

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

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

export OPENALEX_API_KEY="your_key_here"

Option B: Persisted in ~/.claude/.env (recommended)

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:

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:

export OPENALEX_EMAIL="you@example.com"

This puts you in the "polite pool" with better latency, no key required.

Verify

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/

Knows Sidecar Spec: Generation Rules (v0.9.0)

This is the v0.9.0 record shape verified against knows.academy production sidecars (JSON Schema id: https://knows.dev/schema/record-0.9.json, profile paper@1). For the upstream natural-language description see upstream-spec-cache.md.

Top-level Structure (paper@1 profile)

$schema: "https://knows.dev/schema/record-0.9.json"
knows_version: "0.9.0"
record_id: "knows:generated/{slug}/1.0.0"   # only for published records; omit for local drafts
profile: "paper@1"
subject_ref: "art:paper"                      # points to the artifact representing the paper itself

# Top-level metadata (NOT inside a `metadata` block)
title: "..."
authors: ["..."]
venue: "..."          # only if visible in source
year: 2026            # only if visible in source
summary: "..."

# Coverage is an object, not a single value
coverage:
  statements: exhaustive | main_claims_only | key_claims_and_limitations | partial
  evidence: exhaustive | key_evidence_only | partial

license: "CC-BY-4.0"   # if known

artifacts: [...]
statements: [...]
evidence: [...]
relations: [...]
actions: []            # usually empty for paper profile

# Provenance has SINGLE actor (object), not actors (array)
provenance:
  origin: machine | author
  actor:
    name: "knows-gen"
    type: tool         # tool | person | org   (NEVER ai/llm/model)
    version: "0.9.0"
  generated_at: "2026-04-25T00:00:00Z"
  method: extraction

version:
  spec: "0.9.0"
  record: "1.0.0"
  source: original

freshness:
  as_of: "2026-04-25T00:00:00Z"
  update_policy: versioned

Statement Shape

- id: stmt:descriptive-kebab-case
  statement_type: claim    # claim | method | limitation | assumption | definition | question
  modality: empirical      # descriptive | empirical | theoretical
  text: "..."
  about_ref: art:paper     # what the statement is about (usually the subject artifact)
  status: asserted
  source_anchors:
    - representation_ref: rep:paper-pdf
      locator_type: section
      locator: "Section 5"
  confidence:
    claim_strength: high       # high | medium | low
    extraction_fidelity: high  # high | medium | low
  provenance:
    origin: machine
    actor:
      name: "knows-gen"
      type: tool
    generated_at: "..."

Statement Type Frequencies (252 statements / 15 papers)

Evidence Shape

- id: ev:descriptive-kebab-case
  evidence_type: table_result   # see frequencies below
  summary: "..."
  source_anchors: [...]
  provenance: {...}

Evidence Type Frequencies (138 evidence / 15 papers)

Artifact Shape

- id: art:paper
  artifact_type: paper       # see frequencies below
  role: subject              # subject | supporting | cited
  title: "..."
  identifiers:
    url: "https://arxiv.org/abs/..."
    doi: "..."     # OMIT entirely if not visible in source
  representations:
    - id: rep:paper-pdf
      media_type: application/pdf
      locator:
        type: path | url
        value: "..."

Artifact Type Frequencies (50 artifacts / 15 papers)

Artifact Role Frequencies (50 / 15 papers)

Relation Shape

- id: rel:descriptive-kebab-case
  predicate: supported_by  # see "Predicates" section below
  subject_ref: stmt:...
  object_ref: ev:... | stmt:... | art:...

Field Naming (copy exactly)

Value Constraints

Numeric Values

# Correct
- value: 22
- accuracy: 0.945

# Wrong
- value: '22'        # never quote numbers
- accuracy: "0.945"

Anti-Fabrication

If a field is not visible in source, omit the key entirely.

# Wrong
doi: TODO
venue: TBD

# Correct (just omit the keys)
title: "Paper Title"
authors: ["A. Author"]

Applies to: doi, venue, year, ORCIDs, GitHub URLs, dataset URLs.

ID Format

Descriptive kebab-case with type prefix. Never use opaque IDs.

# Correct
- id: stmt:standard-transformer-fails-unseen-tokens
- id: ev:lemma-41-contraction-proof
- id: rel:collapse-causes-failure
- id: art:paper
- id: rep:paper-pdf

# Wrong
- id: stmt:c1
- id: ev:001
- id: rel:r-23

Predicates

Verified frequencies across 330 relations in 15 production sidecars:

Less common predicates valid per upstream natural-language doc (not yet observed):

extends, contradicts, critiques, generalizes,
specializes, introduces, refutes, replicates

# Wrong tense (warning)
predicate: evaluated_on

# Correct
predicate: evaluates_on

# Passive forms accepted in production
predicate: supported_by
predicate: used_by
predicate: challenged_by

Relation Wiring (CRITICAL)

Average ≥1.5 relations per statement. Minimum patterns:

Common Mistakes Cheatsheet

Statement Density Guidance

• Short methods paper: 8-12 statements
• Standard ML paper: 12-18 statements
• Complex/long paper: 15+ required
• Survey/review paper: 20+ recommended

If under-extracted, re-read:

• Limitations sections
• Discussion/conclusions
• Footnotes and ablation studies

Upstream Spec Cache

This file is a snapshot of the canonical Knows skill description. Source: https://knows.academy/api/proxy/skill/knows.md

How to refresh

curl -s https://knows.academy/api/proxy/skill/knows.md \
  > .agents/skills/oma-scholar/resources/upstream-spec-cache.md.new
diff .agents/skills/oma-scholar/resources/upstream-spec-cache.md \
     .agents/skills/oma-scholar/resources/upstream-spec-cache.md.new

If the diff shows meaningful changes, update: 1. This file with the new content 2. sidecar-spec.md if rules changed 3. SKILL.md if mode descriptions changed

Recommend refreshing every 1-2 weeks until the upstream stabilizes.

---

Snapshot (captured 2026-04-25)

# Knows Sidecar Skill — Complete Reference

## Overview

Knows is a structured YAML companion specification for research papers that enables LLM agents to access claims, evidence, and relations directly. A KnowsRecord is a schema-validated sidecar file that sits alongside PDFs.

## Core Modes

**Generate**: Create `.knows.yaml` from paper text, LaTeX, or research ideas
**Validate**: Run structural checks via `scripts/lint.py`
**Review**: Generate peer reviews as sidecars
**Analyze/Query**: Summarize or answer questions from existing sidecars
**Compare**: Diff two papers structurally
**Remote**: Search/download sidecars from knows.academy platform

## Critical Rules for Generation

### Field Naming (Copy Exactly)
- Statements: `statement_type` (not `type` or `claim`)
- Evidence: `evidence_type` (not `type`)
- Relations: `predicate` (not `type`)
- Artifacts: `artifact_type` (not `type`)
- Actors: `type: tool|person|org` (never `ai`, `llm`, `model`)

### Value Constraints
- Numbers unquoted: `value: 22` not `value: '22'`
- Actor origin: `origin: machine` for AI-generated, `author` for human curation
- Confidence: `high|medium|low` only
- Coverage statements: `exhaustive|main_claims_only|key_claims_and_limitations|partial`
- Artifact roles: `subject|supporting|cited` only

### Anti-Fabrication
"If the exact DOI is not visible in the PDF text, omit the `doi` key entirely. Do NOT write `doi: TODO`." Same principle applies to venue and year — omit unknown fields rather than placeholder them.

### Relation Wiring
Every statement needs ≥1.5 relations per statement on average. Minimum patterns:
- Claims: `supported_by` evidence, optionally `depends_on` assumptions
- Evidence: must be `object_ref` of at least one relation
- Methods: `evaluates_on` dataset, `implements` repo, or `documents` paper

### ID Format
Use descriptive kebab-case with prefix: `stmt:privacy-budget-tradeoff`, `ev:cifar10-accuracy-table`, `rel:ablation-supports-claim` — never numbered IDs like `stmt:c1`.

## Post-Generation Checklist

1. Verify statement count (complex papers need 15+)
2. Wire relations systematically per required patterns
3. Run sanitize if YAML won't parse: `python3 scripts/sanitize.py`
4. Lint validation: `python3 scripts/lint.py` until 0 errors
5. Verify metadata: `python3 scripts/verify_metadata.py` (with `--auto-enrich` if DOI missing)

## Common Mistakes

| Error | Wrong | Correct |
|---|---|---|
| Actor type | `type: ai` | `type: tool` |
| Observation value | `'22'` | `22` |
| Artifact field | `type: paper` | `artifact_type: paper` |
| Wrong tense | `evaluated_on` | `evaluates_on` |
| Fabricated DOI | `doi: "TODO"` | Omit entirely |
| Missing metric | `qualitative_value: "..."` | Add `metric: "name"` |

## Dependencies

- **Always available**: YAML template, JSON Schema, generation prompt
- **For lint**: `pip install pyyaml jsonschema`
- **For CLI**: `pip install knows-sidecar`
- **For LLM generation**: `pip install anthropic`
- **For verify**: Free OpenAlex/CrossRef API (set `OPENALEX_API_KEY` in `~/.claude/.env`)

---

Local Adaptations

Where our local skill diverges from upstream (recorded for spec drift tracking):

1. Generation engine: upstream suggests pip install anthropic; we use the host LLM directly (no subprocess SDK call). Cost and key savings. 2. Validation tooling: upstream references pip install knows-sidecar; that package is not yet on PyPI (verified 2026-04-25). We ship rule-based validation as the oma scholar lint CLI subcommand (TypeScript, no Python dependency). 3. JSON Schema host unreachable: production sidecars reference https://knows.dev/schema/record-0.9.json but the host's HTTPS port times out. We cannot redistribute or fetch the schema, so lint encodes empirically-derived rules instead. 4. Submission: not implemented. This skill is read/generate-only, not a publisher.

v0.9.0 Production Spec: Differences From Upstream knows.md

The upstream knows.md document above describes a simplified shape; production sidecars served by knows.academy/api/proxy/sidecars/* follow the v0.9.0 schema which differs significantly. Our `sidecar-spec.md` reflects v0.9.0 production. Key differences:

v0.9.0 Production-Only Fields

Not mentioned in upstream knows.md but present in every production sidecar:

• $schema: URL of the JSON Schema (currently unreachable but referenced)
• knows_version: e.g., "0.9.0"
• record_id: knows:generated/{slug}/{version} for published records
• profile: e.g., "paper@1"
• subject_ref: points to the artifact representing the paper itself
• summary: one-paragraph overview
• license: e.g., "CC-BY-4.0"
• actions: list (typically empty for paper profile)
• version: {spec, record, source}
• freshness: {as_of, update_policy}

Statement Extra Fields (v0.9.0)

Not mentioned in upstream knows.md:

• modality: empirical \| theoretical \| descriptive
• about_ref: what the statement is about (usually the subject artifact)
• status: observed value asserted
• source_anchors: list of {representation_ref, locator_type, locator} pointers
• provenance: per-statement provenance block (same shape as top-level)

Artifact Extra Fields (v0.9.0)

• identifiers: {url, doi, ...} (omit unknown keys)
• representations: list of {id: rep:..., media_type, locator: {type, value}}

Predicate Vocabulary (Verified in Production)

Across 330 relations in 15 production sidecars, the following predicates appear (descending frequency):

supported_by, depends_on, evaluates_on, limited_by, documents,
uses, challenged_by, cites, implements, used_by, defines

Other predicates from upstream natural-language doc, valid per the spec but not yet observed in our sample: extends, contradicts, critiques, generalizes, specializes, introduces, refutes, replicates.

Vocabulary Survey (15 production sidecars / 2026-04-25)

Field enums verified by frequency, all production AI-generated (origin: machine):