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 (2026 papers only; current counts via /api/proxy/jobs/stats)
When NOT to use
- General web search or non-academic content -> use
oma-search
- Translating papers -> use
oma-translation
- 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; OpenAlex and Semantic Scholar fallbacks
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
- Identify mode and source artifact/query.
- Resolve paper identity through Knows or OpenAlex when needed.
- Load sidecar spec and mode-specific protocol.
Scenes
- PREPARE: Select mode and gather source or remote identifiers.
- ACQUIRE: Fetch paper metadata, sidecar sections, or local source text.
- REASON: Extract claims, evidence, relations, provenance, or comparison structure.
- ACT: Generate, lint, review, analyze, compare, or fetch sidecar data.
- VERIFY: Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator.
- 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, review coverage and type-appropriate links. Preserve source-anchored questions/definitions; never add unsupported relations to satisfy a quota.
Exit
- Success: requested sidecar operation completes with validation status.
- Partial success: missing metadata, fallback source, or validation warnings are explicit.
Logical Operations
Actions
| Action |
SSL primitive |
Evidence |
| Select mode |
SELECT |
Generate/Validate/Review/Analyze/Compare/Remote |
| Read paper or sidecar |
READ |
Source files or YAML |
| Request remote data |
REQUEST |
Knows/OpenAlex APIs |
| Infer claims/evidence/relations |
INFER |
Sidecar generation/analysis |
| Write sidecar |
WRITE |
.knows.yaml outputs |
| Validate sidecar |
VALIDATE |
oma scholar lint |
| Report result |
NOTIFY |
Summary or lint report |
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
| Scope |
Resource target |
LOCAL_FS |
Paper drafts, sidecar YAML, review sidecars |
NETWORK |
knows.academy and OpenAlex APIs |
PROCESS |
oma scholar CLI and lint |
USER_DATA |
User-provided paper content and research notes |
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
- Local generation targets v0.9.0 production compatibility /
paper@1 (review sidecars use review@1). This is narrower than complete canonical schema conformance; see resources/sidecar-spec.md.
- Host LLM generates sidecars: never shell out to
anthropic SDK or external LLM CLI; this skill runs inside an agent
- Anti-fabrication: if DOI/venue/year is not visible in source, omit the key entirely; never write
doi: TODO or guess
- Top-level metadata:
title, authors, venue, year live at the top level (no metadata wrapper)
- Field names are exact:
statement_type, evidence_type, predicate, artifact_type (not type/claim)
- Provenance has SINGLE actor:
provenance.actor is one object, NOT a provenance.actors array
- Confidence is an object:
{claim_strength: ..., extraction_fidelity: ...}, both from high|medium|low
- Coverage is an object:
coverage.statements (4-value enum) + coverage.evidence (3-value enum)
- Closed enums: actor
tool|person|org (never ai/llm/model); artifact role subject|supporting|cited; predicates in present tense
- Numbers unquoted:
value: 22, never value: '22'
- Relation coverage: review the local ratio/orphan warnings; add only source-supported, type-appropriate relations. Claims with evidence use
supported_by; definitions and open questions can remain source-anchored. A ratio of 1.5 is diagnostic, not a graph-padding quota.
- ID format: descriptive kebab-case with prefix:
stmt:privacy-budget-tradeoff, ev:cifar10-accuracy-table, art:paper
- Validate before sharing: run
oma scholar lint after Generate and Review; cross-record refs (record_id#local_id) in review sidecars are recognized and not flagged as dangling
- Remote API has no auth:
https://knows.academy/api/proxy/* is public; do not invent auth headers
- Partial fetch param is
section (singular): fixed enum statements|evidence|relations|artifacts|citation
- Fallback API keys are optional:
OPENALEX_API_KEY (metadata enrichment) and S2_API_KEY (Semantic Scholar dedicated rate limit) both improve throughput but the cascade degrades gracefully without them
- Sidecar content stays English: schema fields, IDs, statement text follow upstream convention; user-facing responses follow
oma-config.yaml language
- Contract scope: local generation rules and lint track production compatibility, not the complete canonical v0.9 schema. Preserve canonical imported shapes and report local-lint incompatibilities. Do not claim full schema compliance or add
$schema without validation against that exact schema; see resources/upstream-spec-cache.md.
Modes
| Mode |
Trigger |
Output |
| Generate |
"create sidecar from this paper / abstract / draft", "generate .knows.yaml" |
{paper}.knows.yaml (host LLM emits, then oma scholar lint validates) |
| Validate |
"lint this sidecar", "validate .knows.yaml" |
Pass/fail report with file:line issues |
| Review |
"peer review this paper as sidecar" |
{paper}.review.knows.yaml |
| Analyze |
"summarize this sidecar", "what claims does it make?" |
Natural-language answer |
| Compare |
"compare paper A and paper B structurally" |
Diff table (claims/methods/evidence) |
| Remote |
"find papers on X", "fetch sidecar :id", "get claims only for :id" |
Search results / sidecar payload |
Provider Fallback (knows.academy → OpenAlex → Semantic Scholar)
knows.academy currently indexes only 2026 papers (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,
then to Semantic Scholar (AI TL;DR, citation + influential-citation
counts) when OpenAlex also has nothing. See resources/fallback-providers.md.
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, DOI, arXiv:<id>, CorpusId:<n>)
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.
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"
# Semantic Scholar: AI TL;DR + citation/influential-citation counts
oma scholar get "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>§ion=statements"
curl -s "https://knows.academy/api/proxy/jobs/stats" # platform health
Configuration
Project-specific settings: config/scholar-config.yaml. One key is user-tunable and lives elsewhere — read scholar.base_url from .agents/oma-config.yaml first and fall back to api.base_url in the skill config. Everything else there (endpoint paths, timeouts, id prefixes, lint rules) is protocol shape, not preference.
Troubleshooting
| Issue |
Solution |
[ERROR] *.value: numeric value '22' is quoted |
Remove quotes: value: '22' -> value: 22 |
[ERROR] provenance.actor.type: 'ai' is not allowed |
Change to tool, person, or org |
[ERROR] *.type: use \statement_type` instead of `type`` |
Rename type -> statement_type (or evidence_type/predicate/artifact_type) |
[ERROR] provenance.actors: v0.9 spec uses singular \actor`` |
Replace actors: [{...}] array with actor: {...} object |
[ERROR] *.object_ref: reference 'X' does not match any defined id |
Fix the subject_ref/object_ref to point to a real id, OR use --lenient if consuming third-party data (cross-record record_id#local_id refs are recognized and never flagged) |
[WARN] relations: avg relations/statement is N.NN (target ≥ 1.5) |
Review coverage; add only supported, type-appropriate links, never pad the graph |
[WARN] statements: only N statements; most papers warrant ≥ 8 |
Expected when generating from abstract only; full-paper Generate should hit 15+ |
[WARN] *.predicate: past-tense '...' is suspicious |
Switch to present tense (evaluated_on -> evaluates_on) |
| Remote API returns empty results |
Try broader query; check /api/proxy/jobs/stats; CLI auto-falls-back to OpenAlex |
knows.academy search failed: fetch failed (stderr) |
Platform timeout; fallback to OpenAlex is automatic; retry later for sidecars |
| OpenAlex 403/429 |
Set OPENALEX_API_KEY (see resources/setup-openalex.md) |
semanticscholar error: HTTP 429 (stderr) |
Anonymous pool throttled; CLI retries once then skips the source. Set S2_API_KEY (free form at semanticscholar.org/product/api) for a dedicated limit |
| YAML won't parse |
Check indentation; numbers/booleans must be unquoted; strings with : need quotes |
References
- Execution steps (follow for the selected task):
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
1---2name: oma-scholar3description: Search academic literature and generate, validate, or compare Knows4 paper sidecars. Use for claim/evidence analysis and literature synthesis.5metadata:6 source: https://skillmd.com/skills/tuyv/oma-scholar7---89# Scholar - Research Paper Sidecar Companion1011## Scheduling1213### Goal14Search, fetch, generate, validate, analyze, review, and compare scholarly paper sidecars using the Knows `.knows.yaml` spec for token-efficient research workflows.1516### Intent signature17- User asks for academic literature search, sidecar generation, sidecar validation, paper claims/evidence summary, structural paper comparison, or peer review as sidecar.18- User references Knows, `.knows.yaml`, knows.academy, OpenAlex, claims, evidence, relations, or paper sidecars.1920### When to use2122- Reading research papers token-efficiently via Knows sidecars (~700 tokens for claims-only vs ~10K for full PDF)23- Generating `.knows.yaml` sidecars from your own paper drafts, LaTeX, or research notes24- Validating sidecar structure (rule-based) before sharing25- Producing peer reviews as sidecars26- Querying or summarizing existing sidecars27- Structurally comparing two papers (claims, methods, evidence)28- Searching/fetching sidecars from `knows.academy` (2026 papers only; current counts via `/api/proxy/jobs/stats`)2930### When NOT to use3132- General web search or non-academic content -> use `oma-search`33- Translating papers -> use `oma-translation`34- PDF parsing only (no sidecar) -> use `oma-pdf`35- Submitting sidecars back to knows.academy -> out of scope (host LLM only consumes/produces locally)36- Full peer-review workflow with editor system -> out of scope3738### Expected inputs39- Paper, abstract, draft, LaTeX, research notes, sidecar file, DOI, OpenAlex ID, Knows record ID, or search query40- Desired mode: generate, validate, review, analyze, compare, or remote fetch41- Optional strictness, section filter, or CI behavior4243### Expected outputs44- `.knows.yaml` sidecar, review sidecar, lint report, search/fetch result, natural-language analysis, or structural comparison45- Sidecars conforming to v0.9.0 / `paper@1` profile46- Validation status and warnings before sharing generated sidecars4748### Dependencies49- `oma scholar` CLI subcommands50- knows.academy public API; OpenAlex and Semantic Scholar fallbacks51- `resources/sidecar-spec.md`, API endpoints, OpenAlex setup, upstream cache, checklist, and execution protocol5253### Control-flow features54- Branches by mode, source availability, Knows/OpenAlex coverage, strict vs lenient validation, and fetched section55- Reads/writes YAML sidecars and may call public APIs56- Avoids fabrication when source evidence is missing5758## Structural Flow5960### Entry611. Identify mode and source artifact/query.622. Resolve paper identity through Knows or OpenAlex when needed.633. Load sidecar spec and mode-specific protocol.6465### Scenes661. **PREPARE**: Select mode and gather source or remote identifiers.672. **ACQUIRE**: Fetch paper metadata, sidecar sections, or local source text.683. **REASON**: Extract claims, evidence, relations, provenance, or comparison structure.694. **ACT**: Generate, lint, review, analyze, compare, or fetch sidecar data.705. **VERIFY**: Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator.716. **FINALIZE**: Return sidecar, report, summary, or comparison with caveats.7273### Transitions74- If knows.academy lacks the paper, fall back to OpenAlex metadata/abstract.75- If generating a sidecar, run lint before sharing.76- If consuming third-party sidecars with dangling references, use lenient mode when appropriate.77- If source evidence is absent, omit fields instead of guessing.7879### Failure and recovery80- If remote API times out, retry or use OpenAlex fallback.81- If YAML fails parsing, fix indentation and scalar types.82- If relation density or orphan statements warn, review coverage and type-appropriate links. Preserve source-anchored questions/definitions; never add unsupported relations to satisfy a quota.8384### Exit85- Success: requested sidecar operation completes with validation status.86- Partial success: missing metadata, fallback source, or validation warnings are explicit.8788## Logical Operations8990### Actions91| Action | SSL primitive | Evidence |92|--------|---------------|----------|93| Select mode | `SELECT` | Generate/Validate/Review/Analyze/Compare/Remote |94| Read paper or sidecar | `READ` | Source files or YAML |95| Request remote data | `REQUEST` | Knows/OpenAlex APIs |96| Infer claims/evidence/relations | `INFER` | Sidecar generation/analysis |97| Write sidecar | `WRITE` | `.knows.yaml` outputs |98| Validate sidecar | `VALIDATE` | `oma scholar lint` |99| Report result | `NOTIFY` | Summary or lint report |100101### Tools and instruments102- `oma scholar search|resolve|get|lint`103- Knows public API, OpenAlex fallback, sidecar spec, checklist104105### Canonical command path106```bash107oma scholar search "<query>"108oma scholar resolve "<title-or-doi>"109oma scholar get "<record-id-or-doi>"110oma scholar lint "<paper.knows.yaml>"111```112113### Resource scope114| Scope | Resource target |115|-------|-----------------|116| `LOCAL_FS` | Paper drafts, sidecar YAML, review sidecars |117| `NETWORK` | knows.academy and OpenAlex APIs |118| `PROCESS` | `oma scholar` CLI and lint |119| `USER_DATA` | User-provided paper content and research notes |120121### Preconditions122- Mode and source are identifiable.123- Spec rules are available for generation or validation.124125### Effects and side effects126- May create local sidecar or review sidecar files.127- May query public scholarly APIs.128- Does not submit sidecars back to knows.academy.129130### Guardrails1311321. **Local generation targets v0.9.0 production compatibility / `paper@1`** (review sidecars use `review@1`). This is narrower than complete canonical schema conformance; see `resources/sidecar-spec.md`.1332. **Host LLM generates sidecars**: never shell out to `anthropic` SDK or external LLM CLI; this skill runs inside an agent1343. **Anti-fabrication**: if DOI/venue/year is not visible in source, **omit the key entirely**; never write `doi: TODO` or guess1354. **Top-level metadata**: `title`, `authors`, `venue`, `year` live at the top level (no `metadata` wrapper)1365. **Field names are exact**: `statement_type`, `evidence_type`, `predicate`, `artifact_type` (not `type`/`claim`)1376. **Provenance has SINGLE actor**: `provenance.actor` is one object, NOT a `provenance.actors` array1387. **Confidence is an object**: `{claim_strength: ..., extraction_fidelity: ...}`, both from `high|medium|low`1398. **Coverage is an object**: `coverage.statements` (4-value enum) + `coverage.evidence` (3-value enum)1409. **Closed enums**: actor `tool|person|org` (never `ai`/`llm`/`model`); artifact role `subject|supporting|cited`; predicates in present tense14110. **Numbers unquoted**: `value: 22`, never `value: '22'`14211. **Relation coverage**: review the local ratio/orphan warnings; add only source-supported, type-appropriate relations. Claims with evidence use `supported_by`; definitions and open questions can remain source-anchored. A ratio of 1.5 is diagnostic, not a graph-padding quota.14312. **ID format**: descriptive kebab-case with prefix: `stmt:privacy-budget-tradeoff`, `ev:cifar10-accuracy-table`, `art:paper`14413. **Validate before sharing**: run `oma scholar lint` after Generate and Review; cross-record refs (`record_id#local_id`) in review sidecars are recognized and not flagged as dangling14514. **Remote API has no auth**: `https://knows.academy/api/proxy/*` is public; do not invent auth headers14615. **Partial fetch param is `section` (singular)**: fixed enum `statements|evidence|relations|artifacts|citation`14716. **Fallback API keys are optional**: `OPENALEX_API_KEY` (metadata enrichment) and `S2_API_KEY` (Semantic Scholar dedicated rate limit) both improve throughput but the cascade degrades gracefully without them14817. **Sidecar content stays English**: schema fields, IDs, statement text follow upstream convention; user-facing responses follow `oma-config.yaml` `language`14918. **Contract scope**: local generation rules and lint track production compatibility, not the complete canonical v0.9 schema. Preserve canonical imported shapes and report local-lint incompatibilities. Do not claim full schema compliance or add `$schema` without validation against that exact schema; see `resources/upstream-spec-cache.md`.150151### Modes152153| Mode | Trigger | Output |154|------|---------|--------|155| **Generate** | "create sidecar from this paper / abstract / draft", "generate `.knows.yaml`" | `{paper}.knows.yaml` (host LLM emits, then `oma scholar lint` validates) |156| **Validate** | "lint this sidecar", "validate `.knows.yaml`" | Pass/fail report with file:line issues |157| **Review** | "peer review this paper as sidecar" | `{paper}.review.knows.yaml` |158| **Analyze** | "summarize this sidecar", "what claims does it make?" | Natural-language answer |159| **Compare** | "compare paper A and paper B structurally" | Diff table (claims/methods/evidence) |160| **Remote** | "find papers on X", "fetch sidecar :id", "get claims only for :id" | Search results / sidecar payload |161162### Provider Fallback (knows.academy → OpenAlex → Semantic Scholar)163164`knows.academy` currently indexes **only 2026 papers** (mostly arXiv). For165older or non-2026 papers (Transformer 2017, BERT 2018, classics, journals),166the skill automatically falls back to **OpenAlex** for metadata and abstract,167then to **Semantic Scholar** (AI TL;DR, citation + influential-citation168counts) when OpenAlex also has nothing. See `resources/fallback-providers.md`.169170Use the `oma scholar` CLI subcommands:171172```bash173# Hybrid search: knows first, OpenAlex fallback174oma scholar search "vision language action"175176# Cross-source resolve: figures out which source has the right paper177oma scholar resolve "Attention Is All You Need"178179# Get by id (knows record_id, OpenAlex W-id, DOI, arXiv:<id>, CorpusId:<n>)180oma scholar get "10.48550/arXiv.1706.03762"181```182183When OpenAlex returns the answer (knows.academy lacks the paper), use the184returned abstract as input to **Mode 1 Generate** to produce a local sidecar.185186### Quick Reference187188#### Search (knows + auto OpenAlex fallback)189```bash190oma scholar search "diffusion super resolution"191oma scholar search --year-min 2024 "vision language action"192```193194#### Find one specific paper195```bash196oma scholar resolve "Attention Is All You Need"197# returns top hit from each source + recommendation198```199200#### Fetch a sidecar or work201```bash202# knows.academy full sidecar203oma scholar get "knows:generated/reconvla/1.0.0"204205# Partial fetch (claims only, ~700 tokens, 93% reduction vs PDF)206oma scholar get --section statements "knows:generated/reconvla/1.0.0"207208# By DOI or OpenAlex W-id (works regardless of knows.academy availability)209oma scholar get "10.48550/arXiv.1706.03762"210211# Semantic Scholar: AI TL;DR + citation/influential-citation counts212oma scholar get "arXiv:1706.03762"213```214215When knows.academy is unreachable, `get knows:...` automatically falls back216to OpenAlex by extracting the slug from the record_id. The result is marked217with `fallback: "openalex"` and contains metadata + abstract, useful for218running Mode 1 Generate locally.219220#### Validate221```bash222# Strict mode for own Generate output (default)223oma scholar lint paper.knows.yaml224225# Lenient mode for third-party / fetched sidecars226oma scholar lint --lenient remote.knows.yaml227228# Treat warnings as failures (CI mode)229oma scholar lint --fail-on-warning paper.knows.yaml230```231232About **47% of knows.academy-served sidecars contain at least one dangling233cross-reference** (typo in `subject_ref`/`object_ref`, measured across 15234production samples). Use `--lenient` when consuming third-party records so235these surface as warnings rather than blocking errors.236237#### Raw API (when CLI is unavailable)238```bash239curl -s "https://knows.academy/api/proxy/search?q=..."240curl -s "https://knows.academy/api/proxy/sidecars/<encoded-id>"241curl -s "https://knows.academy/api/proxy/partial?record_id=<id>§ion=statements"242curl -s "https://knows.academy/api/proxy/jobs/stats" # platform health243```244245### Configuration246247Project-specific settings: `config/scholar-config.yaml`. One key is user-tunable and lives elsewhere — read `scholar.base_url` from `.agents/oma-config.yaml` first and fall back to `api.base_url` in the skill config. Everything else there (endpoint paths, timeouts, id prefixes, lint rules) is protocol shape, not preference.248249### Troubleshooting250251| Issue | Solution |252|-------|----------|253| `[ERROR] *.value: numeric value '22' is quoted` | Remove quotes: `value: '22'` -> `value: 22` |254| `[ERROR] provenance.actor.type: 'ai' is not allowed` | Change to `tool`, `person`, or `org` |255| `[ERROR] *.type: use \`statement_type\` instead of \`type\`` | Rename `type` -> `statement_type` (or `evidence_type`/`predicate`/`artifact_type`) |256| `[ERROR] provenance.actors: v0.9 spec uses singular \`actor\`` | Replace `actors: [{...}]` array with `actor: {...}` object |257| `[ERROR] *.object_ref: reference 'X' does not match any defined id` | Fix the `subject_ref`/`object_ref` to point to a real id, OR use `--lenient` if consuming third-party data (cross-record `record_id#local_id` refs are recognized and never flagged) |258| `[WARN] relations: avg relations/statement is N.NN (target ≥ 1.5)` | Review coverage; add only supported, type-appropriate links, never pad the graph |259| `[WARN] statements: only N statements; most papers warrant ≥ 8` | Expected when generating from abstract only; full-paper Generate should hit 15+ |260| `[WARN] *.predicate: past-tense '...' is suspicious` | Switch to present tense (`evaluated_on` -> `evaluates_on`) |261| Remote API returns empty results | Try broader query; check `/api/proxy/jobs/stats`; CLI auto-falls-back to OpenAlex |262| `knows.academy search failed: fetch failed` (stderr) | Platform timeout; fallback to OpenAlex is automatic; retry later for sidecars |263| OpenAlex 403/429 | Set `OPENALEX_API_KEY` (see `resources/setup-openalex.md`) |264| `semanticscholar error: HTTP 429` (stderr) | Anonymous pool throttled; CLI retries once then skips the source. Set `S2_API_KEY` (free form at semanticscholar.org/product/api) for a dedicated limit |265| YAML won't parse | Check indentation; numbers/booleans must be unquoted; strings with `:` need quotes |266267## References268269- Execution steps (follow for the selected task): `resources/execution-protocol.md`270- Sidecar spec rules: `resources/sidecar-spec.md`271- API endpoints: `resources/api-endpoints.md`272- OpenAlex setup: `resources/setup-openalex.md`273- Upstream spec snapshot: `resources/upstream-spec-cache.md`274- Post-generation checklist: `resources/checklist.md`275- CLI subcommands: `oma scholar search|resolve|get|lint` (implementation under `cli/commands/scholar/`)276- Context loading: `../_shared/core/context-loading.md`277- Quality principles: `../_shared/core/quality-principles.md`278- i18n rules: `../../rules/i18n-guide.md`