# Source Map

Use this reference when QQsci must explain where a claim, parameter, citation
suggestion, or comparison value came from.

## Purpose

A source map is an evidence-location table. It prevents QQsci from treating a
paper, note, or figure as a vague supporting source. Each entry must connect one
manuscript claim or extracted value to a specific source and location.

Use source maps for:

- manuscript claim-evidence checks
- citation-supported writing and DOI-only Word comments
- performance comparison tables
- original-paper parameter extraction
- figure, table, and Supporting Information values
- reviewer-risk audits based on missing evidence
- follow-up questions such as `where did this number come from?`

## Minimum Schema

| Field | Meaning |
|---|---|
| `source_id` | Stable local ID such as `SM001`, `CIT002`, or `TAB003` |
| `manuscript_target` | Sentence, paragraph, figure claim, table row, or Word comment target |
| `claim_or_value` | The claim, parameter, or citation point being supported |
| `source` | Paper title, Zotero key, DOI, uploaded file, note, or URL |
| `source_location` | Page, section, figure, table, scheme, equation, caption, or SI location |
| `evidence_type` | `direct_text`, `table_value`, `figure_reading`, `SI_value`, `calculated`, `background_review`, `metadata_only` |
| `extraction_method` | Direct quote/paraphrase, manual reading, plot digitization, unit conversion, formula calculation, or note-derived candidate |
| `support_grade` | `strong`, `partial`, `background`, `limiting`, `contradictory`, or `metadata_only` |
| `caveat` | Missing page, approximate value, figure-only reading, unit conversion, reused citation risk, or needs original PDF |
| `next_action` | Use directly, verify original PDF, send to qqcites, ask qqzot, add DOI-only Word comment, or exclude |

## Compact Output Template

Use this table by default:

| ID | Target | Claim/value | Source | Location | Evidence type | Support | Caveat |
|---|---|---|---|---|---|---|---|
| SM001 | Fig. 4 table row | Maximum curvature = xxx cm-1 | DOI / Zotero key | Fig. 4c / SI Note S3 | figure_reading | partial | approximate; needs digitization |

## Evidence Types

- `direct_text`: the paper directly states the claim or value in prose.
- `table_value`: the value is directly reported in a table.
- `figure_reading`: the value is read from a plot or image. Mark approximate.
- `SI_value`: the value is in Supporting Information. Give SI figure/table/note.
- `calculated`: QQsci calculated the value from reported data. Keep the formula
  and units.
- `background_review`: review article supports broad field context but not a
  specific experimental value.
- `metadata_only`: only title, abstract, DOI, or note metadata is available.
  Do not use as final support for a specific claim.

## Routing Rules

- If the task is citation ranking, send the source map candidates to `qqcites`.
- If the source needs Zotero metadata, item keys, child notes, or local PDF
  lookup, use `qqzot`.
- If the output must be organized in Obsidian, use `QQnote-skill` after Zotero
  retrieval.
- If Word comments are needed, QQsci decides the citation logic, then QQwrite or
  the Word-comment workflow adds DOI-only comments.

## Rules For Values

- Preserve the original unit and the normalized unit.
- For curvature, explicitly record whether the source reports `cm-1`, radius,
  bending angle, displacement, or a figure-only value.
- For light intensity, keep the original unit such as `mW cm-2`, `W m-2`, or
  `sun`.
- For humidity actuation, record RH range, humidity step, maximum curvature,
  minimum curvature, and calculated curvature change.
- If a value was converted, show the conversion rule in `caveat` or a short note.
- If the value cannot be verified in the original paper, mark `metadata_only` or
  `needs original PDF`; do not present it as confirmed.

## Rules For Citations

- One manuscript sentence can map to several source-map rows when it contains
  several claims.
- Do not let one paper support unrelated claims only because it is broadly
  relevant.
- Mark reused papers when the same DOI has already been assigned to another
  nearby sentence.
- Review articles can support background, field status, material families, and
  general challenges. Primary papers are preferred for exact experimental
  methods, parameters, mechanisms, and performance values.
- Contradictory or limiting evidence should be kept in the map instead of hidden.

## Final Response Pattern

For normal manuscript work, return:

1. Revised or drafted text.
2. Source map table.
3. Missing evidence or verification needs.
4. Handoff notes for `qqcites`, `qqzot`, `QQnote-skill`, or `qqwrite` when
   needed.