docs: self-document evidence schema, fix GitHub setup, align evidence types

Add description fields to every property in evidence.schema.json so AI agents
and contributors reading the schema understand exactly what each field requires
(grain, specificity, what counts as a limitation). This makes the schema
self-documenting rather than requiring cross-referencing with agent guides.

Fix docs/GITHUB_SETUP.md to remove outdated 'no configured Git remote'
message and reference the canonical GitHub URL.

Fix literature-scout.md to use exact schema evidence_type enum values
(primary-source, peer-reviewed-study, dataset, field-report, expert-review,
replication, negative-result) and clarify suggested_next_issue semantics:
required field in schema, but opening a GitHub issue is optional.

Author: cschanhniem

docs/GITHUB_SETUP.md

@@ -29,6 +29,8 @@ Field-Tested
 
 The canonical label manifest is `.github/labels.yml`. `pnpm validate` checks that every governance-required label is present in that file.
 
-## Remote Limitation
+## GitHub Repository
 
-This local repository currently has no configured Git remote. Remote setup, Wiki enablement, and Project board creation require a GitHub repository URL and maintainer permissions.
+The canonical remote is at `https://github.com/Open-Problem-Lab/open-problem-lab`.
+
+To sync labels from `.github/labels.yml`, use the `github-label-sync` tool or the GitHub API. To enable Wiki publishing, configure the `update-wiki.yml` workflow and enable the Wiki on the repository settings page.

schemas/evidence.schema.json

@@ -2,6 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://open-problem-lab.local/schemas/evidence.schema.json",
   "title": "Evidence Record",
+  "description": "A single verified evidence record in a problem pack. Every claim that enters canonical truth requires one or more evidence records. The burden of proof sits with the submitter — reviewers need enough information to attack the claim.",
   "type": "object",
   "additionalProperties": false,
   "required": [
@@ -19,18 +20,22 @@
   "properties": {
     "id": {
       "type": "string",
-      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "Unique identifier for this evidence record. Use kebab-case. Example: who-malaria-fact-sheet-2024"
     },
     "problem_id": {
       "type": "string",
-      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*/[a-z0-9]+(?:-[a-z0-9]+)*$"
+      "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*/[a-z0-9]+(?:-[a-z0-9]+)*$",
+      "description": "The problem pack this evidence belongs to. Must match the id field in problem.json. Example: climate-health/malaria-early-warning-africa"
     },
     "claim": {
       "type": "string",
-      "minLength": 20
+      "minLength": 20,
+      "description": "One specific, falsifiable statement this source supports. State what the source can prove and at what grain. Do not state what it cannot prove here — use the limitations field for that."
     },
     "evidence_type": {
       "type": "string",
+      "description": "The type of evidence. Use the most specific type that applies.",
       "enum": [
         "primary-source",
         "dataset",
@@ -45,39 +50,47 @@
       "type": "object",
       "additionalProperties": false,
       "required": ["title", "url"],
+      "description": "The source document or dataset. Use the original source, not a secondary report about it.",
       "properties": {
         "title": {
           "type": "string",
-          "minLength": 4
+          "minLength": 4,
+          "description": "Full title of the source document or dataset. Do not abbreviate."
         },
         "url": {
           "type": "string",
-          "format": "uri"
+          "format": "uri",
+          "description": "Direct, stable URL to the source. Prefer DOIs, archived URLs, or official permanent pages over search results or blog posts."
         }
       }
     },
     "source_date": {
       "type": "string",
-      "format": "date"
+      "format": "date",
+      "description": "Publication or last-updated date of the source in ISO 8601 format (YYYY-MM-DD). If only the year is known, use YYYY-01-01 and note the uncertainty in limitations."
     },
     "access_date": {
       "type": "string",
-      "format": "date"
+      "format": "date",
+      "description": "Date you accessed the source in ISO 8601 format (YYYY-MM-DD). Required because URLs and content change."
     },
     "method": {
       "type": "string",
-      "minLength": 10
+      "minLength": 10,
+      "description": "How you assessed what the source proves. Describe which sections you reviewed and what analytical steps you applied. A reviewer should be able to replicate your assessment."
     },
     "limitations": {
       "type": "array",
       "items": {
         "type": "string",
         "minLength": 5
       },
-      "minItems": 1
+      "minItems": 1,
+      "description": "What this source cannot prove. Be specific: name the grain, geography, time period, or causal claims that exceed what the source supports. 'Results may vary' is not a limitation."
     },
     "confidence": {
       "type": "string",
+      "description": "Your confidence that this evidence record accurately represents what the source proves. Not confidence that the claim itself is true in the world.",
       "enum": ["high", "medium", "low", "unknown"]
     }
   }