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

package/skills/oma-scholar/SKILL.md

@@ -0,0 +1,276 @@
+---
+name: oma-scholar
+description: Search academic literature and generate, validate, or compare Knows
+  paper sidecars. Use for claim/evidence analysis and literature synthesis.
+---
+
+# 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
+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**: Check the supported local contract, IDs, relations, and provenance; report lint limitations. Full canonical conformance requires the exact schema validator.
+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, 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
+```bash
+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
+
+1. **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`.
+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 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.
+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 and Review; cross-record refs (`record_id#local_id`) in review sidecars are recognized and not flagged as dangling
+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. **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
+17. **Sidecar content stays English**: schema fields, IDs, statement text follow upstream convention; user-facing responses follow `oma-config.yaml` `language`
+18. **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:
+
+```bash
+# 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)
+```bash
+oma scholar search "diffusion super resolution"
+oma scholar search --year-min 2024 "vision language action"
+```
+
+#### Find one specific paper
+```bash
+oma scholar resolve "Attention Is All You Need"
+# returns top hit from each source + recommendation
+```
+
+#### Fetch a sidecar or work
+```bash
+# 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
+```bash
+# 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)
+```bash
+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`. 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`

package/skills/oma-scholar/config/scholar-config.yaml

@@ -0,0 +1,79 @@
+# oma-scholar configuration
+# Knows sidecar generation and remote access settings
+
+# Remote API
+# `base_url` is the one user-tunable key here (self-hosted knows instances).
+# Set it as `scholar.base_url` in .agents/oma-config.yaml, which wins and which
+# `oma update` preserves — this file is overwritten and supplies only the
+# shipped default. Everything else below is protocol shape.
+api:
+  base_url: https://knows.academy
+  endpoints:
+    search: /api/proxy/search
+    sidecar: /api/proxy/sidecars/{record_id}
+    partial: /api/proxy/partial
+    stats: /api/proxy/jobs/stats
+  # No auth required for proxy endpoints
+  timeout_seconds: 30
+
+# Partial-fetch defaults: fields you can request individually
+# (must match `oma scholar get --section` enum; methods/provenance are NOT
+# available via partial fetch — fetch the full sidecar for those)
+partial_fields:
+  available:
+    - statements
+    - evidence
+    - relations
+    - artifacts
+    - citation
+  default_for_summary:
+    - statements
+    - citation
+
+# Semantic Scholar fallback (optional key)
+# Tier-3 search fallback + `get arXiv:<id>` / `CorpusId:<n>` direct fetch.
+# Anonymous use shares a global pool (429s under load; CLI retries once).
+semanticscholar:
+  env_var: S2_API_KEY          # sent as x-api-key header
+  key_request_url: https://www.semanticscholar.org/product/api
+
+# OpenAlex metadata enrichment (optional)
+# Used during Generate mode to backfill DOI/venue/year when missing
+openalex:
+  enabled_when_key_present: true
+  env_var: OPENALEX_API_KEY
+  # Polite-pool email also accepted for higher anonymous rate limits
+  polite_pool_env_var: OPENALEX_EMAIL
+  signup_url: https://openalex.org/
+  settings_url: https://openalex.org/settings/api
+  # Free daily allowance (no key): $1 value, ~10K list calls, ~1K search calls
+
+# Sidecar generation defaults
+generation:
+  # Minimum number of statements before warning user about under-extraction
+  min_statements_complex_paper: 15
+  # Average relations per statement (relation wiring quality threshold)
+  min_relations_per_statement: 1.5
+  # ID format
+  # Methods are statements (statement_type: method) and use "stmt:"; actors have no ids
+  id_prefixes:
+    statement: "stmt:"
+    evidence: "ev:"
+    relation: "rel:"
+    artifact: "art:"
+    representation: "rep:"
+
+# Output behavior
+output:
+  # When no output path is specified:
+  # "same_dir" = output next to the input source file
+  # "cwd" = output in current working directory
+  default_location: same_dir
+  filename_pattern: "{base}.knows.yaml"
+  review_filename_pattern: "{base}.review.knows.yaml"
+  overwrite: false  # Prompt before overwriting existing files
+
+# Lint behavior
+lint:
+  command: "oma scholar lint"
+  fail_on_warning: false

package/skills/oma-scholar/resources/api-endpoints.md

@@ -0,0 +1,174 @@
+# 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}
+```
+
+```bash
+curl -s "https://knows.academy/api/proxy/search?q=diffusion+super+resolution"
+```
+
+Response shape (verified):
+```json
+{
+  "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).
+
+```bash
+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.
+
+```bash
+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:
+```json
+{
+  "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
+```
+
+```bash
+curl -s "https://knows.academy/api/proxy/jobs/stats"
+```
+
+Returns processing queue health (response shape verified; values are a point-in-time example):
+```json
+{
+  "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`
+
+Fetch the schema at this ID when canonical validation is required. If that fetch fails during the run, record the error and use `upstream-spec-cache.md` and `sidecar-spec.md` for local compatibility checks. A successful `oma scholar lint` result does not validate the complete canonical JSON Schema. For failed sidecar/API requests, follow the Error Handling table below and the existing cascade in `fallback-providers.md`.
+
+## 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
+
+| Status | Meaning | Recovery |
+|--------|---------|----------|
+| 404 | record_id not found | Verify ID via `/search`; the record may not be sidecared yet |
+| 422 | Validation error (bad params) | Check `section` value against the allowed enum |
+| 5xx | Platform issue | Retry once; check `/jobs/stats` |
+| Timeout | Network / slow response | Retry with longer timeout; fall back to local sidecar if cached |
+
+## URL Encoding
+
+`record_id` contains `:` and `/`, so always URL-encode when placing in a path or query parameter. Examples:
+
+```bash
+# 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

package/skills/oma-scholar/resources/checklist.md

@@ -0,0 +1,92 @@
+# Local Production Compatibility Checklist (v0.9.0)
+
+Run this for local-profile Generate/Review output. This checklist and local lint
+do not validate the complete canonical schema. Preserve wider canonical shapes
+in imported records (including author objects, imported provenance, and normative
+modality); report incompatibilities instead of destructively normalizing them.
+
+## Top-Level Structure
+
+- [ ] `title` is set at the **top level** (not `metadata.title`)
+- [ ] Local-generation `authors` is a top-level list of strings; preserve author objects in canonical imported records
+- [ ] `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
+
+- [ ] Local-generation `provenance.origin` is `machine` or `author`; canonical imports can include `imported` (report local-lint incompatibility)
+- [ ] `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` (review sidecars use the same enum — no `review_comment`)
+- [ ] Local generation uses observed modalities `descriptive`, `empirical`, `theoretical`; preserve canonical imported `normative` values
+- [ ] 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
+
+- [ ] Relations are source-supported and appropriate to each statement type
+- [ ] Claims with evidence use `supported_by`; source-anchored questions/definitions are not given fabricated support
+- [ ] Ratio warnings prompt a coverage review, not graph padding
+- [ ] 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
+- [ ] Review sidecars (Mode 3): cross-record refs use the `record_id#local_id` grammar (e.g., `knows:examples/resnet/1.0.0#stmt:main-contribution`) — lint accepts these; bare foreign ids are still errors
+
+## 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
+
+- [ ] Newly generated local-profile output passes `oma scholar lint`; imported-record incompatibilities are reported without loss of canonical data
+- [ ] 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 (diagnostic target 1.5; no fabricated links)
+- 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")