psyclaw 0.28.0 → 0.28.2

package/vendor/nature-skills/skills/nature-figure/references/multipanel-evidence-architecture.md

@@ -0,0 +1,268 @@
+# Multi-panel evidence architecture
+
+Use this reference when planning, restructuring, or auditing a manuscript
+figure with several labelled panels, or when mapping a Results evidence chain
+onto a sequence of figures. Read it together with the
+[Nature Results–Discussion corpus guidance](../../nature-shared/core/nature-results-discussion.md)
+when figure order must mirror the manuscript's claim escalation.
+
+## Contents
+
+- [Status and scope](#status-and-scope)
+- [Start from the figure-level claim](#start-from-the-figure-level-claim)
+- [Give panels different inferential roles](#give-panels-different-inferential-roles)
+- [Choose an evidence-chain archetype](#choose-an-evidence-chain-archetype)
+- [Corpus pattern anchors](#corpus-pattern-anchors)
+- [Align figure order with Results claim escalation](#align-figure-order-with-results-claim-escalation)
+- [Assign visual hierarchy from evidence hierarchy](#assign-visual-hierarchy-from-evidence-hierarchy)
+- [Decide whether a panel belongs in the main figure](#decide-whether-a-panel-belongs-in-the-main-figure)
+- [Run the multi-panel audit](#run-the-multi-panel-audit)
+
+## Status and scope
+
+This is **corpus-derived Nature-style guidance, not an official journal
+requirement**. It was distilled from author-supplied readings of flagship
+*Nature* papers on MIRA (`s41586-026-10675-5`), centromere architecture
+(`s41586-026-10841-9`), Robin (`s41586-026-10652-y`) and TabPFN
+(`s41586-024-08328-6`), then generalized for Nature Portfolio manuscript
+figures. Current journal instructions, article-type rules, the actual evidence
+and the scientific question always take precedence.
+
+Do not copy a published paper's panel count or letter order as a template. The
+stable pattern is inferential: a figure usually answers one Results-level
+scientific question, while its panels perform different jobs in the evidence
+chain needed to answer it.
+
+## Start from the figure-level claim
+
+Before choosing plots, write:
+
+```text
+Results-level question:
+Figure-level claim:
+What could overturn that claim?
+Decisive evidence:
+Panel sequence:
+  a — question | evidence role | necessary comparison
+  b — question | evidence role | necessary comparison
+  c — question | evidence role | necessary comparison
+Destination of displaced material: main figure | another figure | Extended Data/SI
+```
+
+Treat `one figure = one major claim` as a strong planning default, not a rigid
+counting rule. A figure may contain several subordinate findings when all are
+necessary to establish, qualify or bound the same higher-level claim. If a
+panel establishes a separate major claim, give it another figure or Results
+unit. If a panel can disappear without weakening or changing the figure-level
+inference, merge it, move it to Extended Data/SI, or delete it.
+
+Panel letters mark reading order; they do not assign universal functions.
+Panel `a` need not always be a schematic, and panel `d` need not always be a
+stress test. Choose roles from the scientific logic.
+
+## Give panels different inferential roles
+
+Select the smallest sufficient set. A figure does not need every role.
+
+| Evidence role | Question it answers |
+|---|---|
+| Setup or schematic | What system, intervention, workflow or contrast is being tested? |
+| Representative example | What does the phenomenon look like in a concrete case? |
+| Primary quantitative evidence | Does the central effect or capability exist? |
+| Baseline or control | Does it exceed a credible alternative or survive the relevant control? |
+| Decomposition | Which components, strata or variables account for the effect? |
+| Stratification | Does the conclusion hold across scientifically meaningful conditions? |
+| Orthogonal validation | Is the conclusion recovered with another assay, measure or evidence type? |
+| Perturbation or stress test | Does the claim survive an attack, or fail as predicted when a necessary relation is disrupted? |
+| Boundary or failure case | Where does the effect weaken, reverse or stop generalizing? |
+| Mechanistic evidence | What bounded explanation is supported for why the effect occurs? |
+
+Panels are independently **necessary**, not independent stories. Covering one
+panel should remove a distinct inferential step that the other panels cannot
+recover. Prefer role diversity over metric diversity.
+
+Weak mirror layout:
+
+`a: R2 -> b: R2 pairwise tests -> c: MAPE -> d: MAPE pairwise tests`
+
+This contains four panels but often only two inferential roles: overall
+performance and pairwise evidence. A secondary metric can be useful, but it
+does not earn a main panel merely by being another metric.
+
+Stronger claim-driven layout:
+
+`a: perturbation design -> b: decisive comparison -> c: full distribution or residual -> d: decomposition or boundary`
+
+This progresses from what was changed, to what happened, to which alternative
+was rejected, to what explains or limits the remaining effect.
+
+## Choose an evidence-chain archetype
+
+### Validation envelope
+
+Use when the figure asks whether one system, simulator, intervention or model
+capability is credible:
+
+`define the capability -> establish it -> test distinct failure modes -> attack the claim -> bound it`
+
+Consistency, leakage, safety, bias and adversarial robustness can belong in one
+figure when they are different ways the same credibility claim could fail. Do
+not present them as unrelated metric panels.
+
+### Scale-to-instance chain
+
+Use when a population-level pattern needs biological, clinical or physical
+interpretation:
+
+`global map or distribution -> quantity -> spatial relation or scale -> internal structure -> representative exception or instance`
+
+The representative example should explain, localize or challenge the aggregate
+pattern; it should not be a decorative anecdote.
+
+### Discovery sequence
+
+Use when each result changes the next scientific question:
+
+`hypothesis -> decisive experiment -> analysis -> refined hypothesis -> next test -> mechanism validation`
+
+At manuscript level, the figure sequence can carry this discovery loop. Keep
+only steps that alter the claim or motivate the next test; do not reproduce a
+chronological laboratory notebook.
+
+### Capability ladder
+
+Use when a method paper makes progressively stronger claims:
+
+`what it is -> what behaviour it learned -> whether it outperforms alternatives -> whether the gain survives harder conditions -> what broader ability follows`
+
+Within a benchmark figure, combine complementary support such as aggregate
+performance, per-dataset generality and efficiency. In the following figure,
+move to a stronger question such as robustness, confounding or broader
+capability instead of redrawing the same ranking.
+
+Across these archetypes, a reusable Figure-level chain is:
+
+`establish -> compare or control -> stress-test or discriminate -> broaden -> bound`
+
+Use only the moves the claim needs.
+
+## Corpus pattern anchors
+
+Use these author-supplied readings as reasoning examples, not layouts to copy:
+
+- **MIRA — validation envelope.** One figure asks whether the patient agent is
+  a credible evaluation environment, with panels probing consistency,
+  information leakage and adversarial robustness as different failure modes.
+  Later figures ask separate higher-level questions about intervention
+  capability, medication, admission decisions and bias robustness. The metrics
+  are grouped by the claim they can overturn, not by data type.
+- **Centromere architecture — scale to instance.** A resource/map figure first
+  defines the study object. A later variation figure moves through count,
+  spatial relation, scale and internal structure before showing informative
+  examples. The panels collectively explain which dimensions constitute the
+  variation rather than announcing five unrelated discoveries.
+- **Robin — discovery sequence.** The figure progression follows hypothesis
+  generation, wet-lab testing, analysis and refined mechanism or hypothesis.
+  The sequence preserves the scientific discovery loop because each result
+  changes what is tested next.
+- **TabPFN — capability ladder.** Early figures explain the system and learned
+  behaviour; a benchmark figure combines aggregate performance, per-dataset
+  generality and tuning-time efficiency; a later figure asks whether that
+  performance claim survives uninformative features, outliers, reduced data
+  and stronger competitors. The later figure escalates the claim instead of
+  repeating that performance is good.
+
+These examples support three portable distinctions:
+
+1. several attacks on one claim can belong in one figure
+2. population summaries and representative cases can be complementary steps
+   in one figure
+3. a later figure should normally ask a deeper question than the preceding
+   figure
+
+## Align figure order with Results claim escalation
+
+The relationship works at two scales:
+
+- **Within a figure:** panels are different sentences in one compact Results
+  argument.
+- **Across figures:** each figure should make a stronger or different claim
+  that creates the next scientific question.
+
+For example:
+
+`Fig. 1: What is it? -> Fig. 2: Is the evaluation or resource credible? -> Fig. 3: Does the phenomenon exist? -> Fig. 4: Does it beat alternatives? -> Fig. 5: Does the claim survive harder conditions? -> Fig. 6: What mechanism, generality or boundary follows?`
+
+This is an archetype, not a mandatory six-figure template. Apply the
+claim-escalation audit from the shared Results–Discussion guidance. If two
+figures can both be summarized as `X performs well`, merge them, demote the
+weaker evidence, or revise the later figure around a deeper discriminator.
+
+## Assign visual hierarchy from evidence hierarchy
+
+- Give the decisive evidence the hero position or largest visual area.
+- Keep controls and robustness panels quieter, but large enough to judge.
+- Use one condition, cohort or method mapping consistently across panels.
+- Do not force equal panel sizes when inferential importance differs.
+- Use a setup schematic only when readers need it to interpret the evidence;
+  do not add a decorative panel `a` by habit.
+- Make the attack, negative result or failure boundary visible when it changes
+  the figure-level claim.
+- Keep axes, uncertainty definitions, sample definitions and comparator labels
+  consistent whenever panels invite direct comparison. Disclose any change in
+  `n`, denominator, cohort, estimator or scale.
+
+## Decide whether a panel belongs in the main figure
+
+Use the necessity test:
+
+1. What unique inference disappears if this panel is removed?
+2. Does that inference establish, advance, qualify or bound the figure-level
+   claim?
+3. Is it a distinct evidence role, or the same result under another metric,
+   estimator, seed, threshold or visual encoding?
+
+Then route it:
+
+- **Main figure:** decisive evidence, a necessary control, a central
+  falsification, or a conclusion-changing boundary.
+- **Extended Data/SI:** reassurance, provenance detail, secondary metrics,
+  alternative estimators, expanded subgroup views or robustness that does not
+  change the central interpretation.
+- **Another figure:** a genuinely separate major claim or the next rung of the
+  manuscript's claim escalation.
+- **Delete or merge:** a repeated view with no independent inference gain.
+
+Do not hide a result that changes the conclusion merely because it is negative
+or complicates the layout.
+
+## Run the multi-panel audit
+
+Complete this table before drawing and again after the final render:
+
+| Panel | Scientific question | Evidence role | Decisive comparison | Unique inference gain | Claim dependency | Destination |
+|---|---|---|---|---|---|---|
+| a |  |  |  |  |  |  |
+| b |  |  |  |  |  |  |
+| c |  |  |  |  |  |  |
+
+Audit the full figure:
+
+- Can the figure-level claim be stated in one sentence with a verb?
+- Do the panels collectively answer one Results-level question?
+- Does every panel add a distinct inferential role rather than only a new
+  metric or chart type?
+- Does the panel order form a readable chain rather than a dashboard grid?
+- Is the strongest evidence visually dominant?
+- Are central controls, attacks and failure boundaries present?
+- Would a moved panel fit Extended Data/SI without weakening the main claim?
+- Does the next figure ask the question created by this figure?
+- Can the caption explain what is shown and how to read it without replaying
+  the full Results argument?
+- At final physical size, are dependencies, shared encodings, uncertainty and
+  panel transitions still legible?
+
+The final design rule is: **do not begin with the number of datasets, metrics
+or panels available. Begin with the one sentence the figure must establish,
+then choose the few different evidence roles a skeptical reader needs to
+believe it.**

package/vendor/nature-skills/skills/nature-figure/references/nature-2026-observations.md

@@ -0,0 +1,124 @@
+# 2026 Nature Sample Observations
+
+## Contents
+
+- [Archetype 1: Schematic-led composite](#archetype-1-schematic-led-composite)
+- [Archetype 2: Dark image plate](#archetype-2-dark-image-plate)
+- [Archetype 3: Clinical triptych](#archetype-3-clinical-triptych)
+- [Archetype 4: Dense categorical physical-science panel](#archetype-4-dense-categorical-physical-science-panel)
+- [Archetype 5: Asymmetric mixed-modality figure](#archetype-5-asymmetric-mixed-modality-figure)
+- [Cross-cutting Nature rules from the sample](#cross-cutting-nature-rules-from-the-sample)
+- [Palette guidance by modality](#palette-guidance-by-modality)
+- [What not to copy blindly](#what-not-to-copy-blindly)
+
+
+This note captures page-level figure patterns observed from a local 2026 sample of `Nature`
+papers, plus one `Nature Biomedical Engineering` paper used as a clinical / ML-adjacent
+cross-check.
+
+Sampled figure sources:
+
+- `s41586-026-10408-8` — wide schematic-led materials figure with supporting quant panels
+- `s41586-026-10426-6` — dark whole-brain image plate with repeated views
+- `s41586-026-10393-y` — clinical triptych: longitudinal lines, forest plots, summary bars
+- `s41586-026-10257-5` — dense categorical stacked-area panels with direct labels
+- `s41586-026-10439-1` — asymmetric genomics figure with one dominant circular panel
+- `Expert-level detection of pathologies...` — compact medical / ML figure conventions
+
+## Archetype 1: Schematic-led composite
+
+Seen in the printable meta-assemblies paper.
+
+Actionable rules:
+
+- Let the schematic occupy roughly `45–60%` of figure height.
+- Use the **same physical/material palette** in the supporting plots; do not switch to generic method colors below the schematic.
+- Zoom callouts should use one repeated accent style across the figure, for example a single dashed red outline family.
+- Reserve at least one supporting panel for a real-world photograph or experimental snapshot when the story needs scale validation.
+- Supporting quantitative panels should be smaller, cleaner and less saturated than the schematic so the eye reads the page in the intended order.
+
+## Archetype 2: Dark image plate
+
+Seen in the astrocyte brain-network figure.
+
+Actionable rules:
+
+- Use a black facecolor only for the image plate region, not for the whole page.
+- Pair grayscale context with one or two fluorescent channels; the sample repeatedly used cyan and magenta.
+- Keep crops, scale bars and view boxes geometrically consistent across rows and columns.
+- Use white gutters and white scale bars so the plate stays legible after print/export compression.
+- Put row labels and channel labels directly on the image plate; avoid detached legends.
+
+Recommended accent set for this modality:
+
+```python
+CYAN = "#22D7E6"
+MAGENTA = "#FF2AD4"
+GREY_CONTEXT = "#B8B8B8"
+```
+
+## Archetype 3: Clinical triptych
+
+Seen in the OTOF gene-therapy paper.
+
+Actionable rules:
+
+- Top row: line plots or longitudinal summaries, usually sharing one legend strip above the row.
+- Middle row: forest-plot style effects with a dashed vertical reference line and light category bands.
+- Bottom row: compact summary bars, often binary or stacked-percentage bars.
+- Keep columns semantically parallel. If the first column is `ABR`, the next columns should reuse the same row logic rather than introducing a new layout.
+- Baseline / reference series can be black or dark grey; follow-up or intervention groups can use a restrained warm/cool sequence.
+
+Recommended design signal:
+
+- Legends belong outside the data region when there are many timepoints.
+- Group bands in forest plots should be pale and subordinate, never more salient than the confidence intervals.
+
+## Archetype 4: Dense categorical physical-science panel
+
+Seen in the condensation-sequence figure.
+
+Actionable rules:
+
+- Direct-label regions when the plot has many semantically intrinsic categories.
+- Use hatching or texture overlays when neighboring fills are close in luminance or may print poorly.
+- Reuse the exact same axis limits and panel geometry across the full grid.
+- Prefer embedded labels over a detached mega-legend when each panel repeats the same categorical structure.
+
+## Archetype 5: Asymmetric mixed-modality figure
+
+Seen in the rediploidization genomics figure.
+
+Actionable rules:
+
+- Do not force equal panel sizes. Let the biologically central panel dominate.
+- Use small supporting plots around the hero panel to answer narrower questions.
+- Keep a tight, reused color mapping across all modalities, for example `wave 1 / wave 2 / wave 3` or `baseline / highlight / neutral`.
+- Use whitespace and alignment, not decorative frames, to signal grouping.
+
+## Cross-cutting Nature rules from the sample
+
+- Panel labels are small bold lowercase letters near the top-left corner, not large badges.
+- Figure pages are narrative, not dashboard-like. A dominant panel is normal.
+- Legends are often omitted if direct labeling is possible.
+- Background discipline matters more than ornament. White for charts, black only for image plates.
+- Saturated colors are used sparingly and usually mean either a true experimental channel or a highlighted subgroup.
+- When several modalities coexist, keep axis-heavy plots visually quieter than schematics or imaging panels.
+- Gutters are slightly larger when dark panels touch light panels or when modalities change.
+
+## Palette guidance by modality
+
+- Materials / mechanism pages:
+  `aqua`, `teal`, `lilac`, `soft violet`, with one red accent for callouts only.
+- Imaging plates:
+  `black` + `grey context` + `cyan` + `magenta`.
+- Clinical quantitative figures:
+  `black baseline`, then restrained warm/cool follow-up hues, with pale group shading.
+- Genomics / systems figures:
+  `neutral greys` plus one `red family` and one `blue family` for highlighted biological states.
+
+## What not to copy blindly
+
+- Do not import a bright multi-hue palette just because one sampled physical-science figure used many fills. That only works when the categories are intrinsic phases/materials and directly labeled.
+- Do not place all Nature figures on black backgrounds; that was specific to the imaging plate archetype.
+- Do not force a legend into every panel. Many sampled figures read better with direct labels or one shared legend strip.

package/vendor/nature-skills/skills/nature-figure/references/nature-article-requirements.md

@@ -0,0 +1,149 @@
+# Flagship Nature Article figure requirements
+
+Use this reference for figures submitted to the flagship journal **Nature**.
+Keep initial-review files separate from accepted-in-principle production files,
+and do not apply these formats automatically to Nature Portfolio subjournals.
+
+## Contents
+
+1. Stage gate
+2. Initial-submission figures
+3. Legend contract
+4. Production dimensions and typography
+5. Main-figure production files
+6. Extended Data production files
+7. Accessibility and image integrity
+8. Delivery audit
+9. Official sources
+
+## 1. Stage gate
+
+Record one stage before auditing:
+
+- `initial_submission`: figures may be embedded in the Word/PDF manuscript;
+  production-quality files are not required
+- `revision`: follow both the public guide and the editor's instructions
+- `accepted_in_principle`: supply production-quality main figures and Extended
+  Data using their different file contracts
+
+Do not fail an initial submission solely because it lacks separate editable
+production artwork. Do fail it when the displayed data are unreadable,
+misrepresented, incomplete or impossible for referees to assess.
+
+## 2. Initial-submission figures
+
+- Prefer figures embedded with manuscript text in one Word or PDF file.
+- Put each figure legend on the same page as its figure.
+- Use enough resolution for referees to evaluate the data.
+- If embedding is impractical, supply separate files or an accessible
+  repository route and confirm every figure is cited.
+- Run the statistics, source-data and image-integrity checks even though final
+  artwork formatting is deferred.
+
+## 3. Legend contract
+
+For every flagship Nature figure legend:
+
+- keep the complete legend below 250 words
+- begin with a brief title sentence for the whole figure
+- follow with a concise description of what each panel depicts
+- do not use the legend to narrate results or duplicate Methods
+- include definitions needed to understand the figure in isolation
+- state exact `n`, replicate definition, center/spread, error bars, test,
+  correction and P-value display where applicable
+- identify adaptations and permissions when third-party material is used
+
+Table legends begin with a short title sentence; explanatory detail may go in
+footnotes.
+
+## 4. Production dimensions and typography
+
+For accepted-in-principle main figures:
+
+- use 89 mm for a single-column figure or 183 mm for a double-column figure
+- do not exceed 170 mm height, leaving room for the legend
+- keep ordinary figure text between 5 pt and 7 pt at final size
+- label multi-panel figures with 8 pt bold upright lowercase `a`, `b`, `c`, etc.
+- use a consistent sans-serif typeface, preferably Arial or Helvetica
+- use Courier or another monospaced font for amino-acid sequences
+- keep all text editable, do not outline it, and embed TrueType 2 or 42 fonts
+- arrange panels alphabetically where practical and minimize unused space
+
+## 5. Main-figure production files
+
+Main figures require vector artwork with editable layers.
+
+Preferred:
+
+- `.ai`
+- `.eps`
+- editable `.pdf`
+
+Also accepted by the current research figure guide when properly prepared:
+
+- layered Photoshop artwork
+- PowerPoint converted to PDF
+- plain `.svg`
+- Excel
+- `.ps`
+
+Do not submit flattened `.jpeg`, `.tiff` or `.png` as the final main-figure
+production file merely because the workflow also creates those formats for QA
+or preview. Keep all components embedded rather than externally linked and aim
+to keep each file below 50 MB.
+
+## 6. Extended Data production files
+
+Extended Data has a different production contract:
+
+- save in RGB
+- use no more than 300 dpi
+- keep each file at or below 10 MB
+- use `.jpeg` preferably, or `.tiff`/`.eps`
+- fit each item on one page with room for its legend or footnotes
+- use the journal's required filename pattern based on the corresponding
+  author's surname and the ED figure/table number
+
+Do not send a main figure through the Extended Data file route or vice versa.
+
+## 7. Accessibility and image integrity
+
+- include axis lines and tick marks
+- label every axis and place units in parentheses
+- avoid background gridlines, drop shadows, decorative icons, patterns,
+  overlapping labels and coloured text
+- use an accessible palette; do not rely on red/green or rainbow scales
+- supply artwork in RGB; photographic images need at least 300 dpi, with
+  450 dpi preferred for the highest online-proof resolution
+- keep scale bars and their labels editable rather than flattened into images
+- use scale bars instead of magnification factors
+
+For microscopy, gels, blots or other processed images, load the image-integrity
+section of `../../nature-shared/core/research-compliance.md`. Record raw-file
+provenance, crop, contrast, gamma, pseudocolour, stitching, lane rearrangement
+and processing software.
+
+## 8. Delivery audit
+
+Return:
+
+| Item | Stage | Required contract | Current file/evidence | Status | Action |
+|---|---|---|---|---|---|
+
+Before approval:
+
+- run `scripts/validate_figure.py` on plotting source
+- run `scripts/audit_pdf_text.py` on exported PDF text
+- run `scripts/audit_figure_collisions.py` after every generated or layout-affecting revision and resolve every rendered collision FAIL
+- inspect every panel and the assembled figure at final physical size
+- verify that preview/export bundles are not mislabeled as the journal's final
+  accepted upload formats
+
+## 9. Official sources
+
+Verified 2026-08-08:
+
+- Nature initial submission: <https://www.nature.com/nature/for-authors/initial-submission>
+- Preparing figures: <https://research-figure-guide.nature.com/figures/preparing-figures-our-specifications/>
+- Building and exporting figure panels: <https://research-figure-guide.nature.com/figures/building-and-exporting-figure-panels/>
+- Image integrity: <https://www.nature.com/nature-portfolio/editorial-policies/image-integrity>

package/vendor/nature-skills/skills/nature-figure/references/openrouter-image-generation.md

@@ -0,0 +1,141 @@
+# OpenRouter Image Generation for Manuscript Schematics
+
+## Contents
+
+- [Source](#source)
+- [Safety and scientific integrity](#safety-and-scientific-integrity)
+- [Prompt contract](#prompt-contract)
+- [Script usage](#script-usage)
+- [Recommended defaults](#recommended-defaults)
+- [Follow-up QA](#follow-up-qa)
+
+
+Use this reference only when the user explicitly asks to generate a paper schematic, graphical abstract, mechanism diagram, or concept illustration through OpenRouter / GPT Image 2 / an image-generation API.
+
+Read `ai-graphical-abstract-workflow.md` first. Complete its journal-policy gate,
+communication brief, scientific-review plan, and provenance plan before making a
+real API call. If submission eligibility has not been verified, mark the result
+as an internal design draft rather than a submission-ready asset.
+
+Do not use this route for quantitative plots, data panels, heatmaps, microscopy plates, blots, or figure assembly unless the user explicitly wants an AI-generated draft illustration. Keep data-driven figures in the Python or R route.
+
+## Source
+
+OpenRouter's dedicated Images API uses:
+
+- model discovery: `GET https://openrouter.ai/api/v1/images/models`
+- generation: `POST https://openrouter.ai/api/v1/images`
+- default model for this skill: `openai/gpt-image-2`
+
+Authentication uses `OPENROUTER_API_KEY` as a bearer token.
+
+## Safety and scientific integrity
+
+- Treat generated images as draft visual concepts, not evidence.
+- Do not treat a Nature Careers article as permission to submit generative-AI
+  artwork. Verify the exact target journal's current official rules and keep
+  internal usefulness separate from submission eligibility.
+- Do not invent quantitative values, p-values, spectra, microscopy findings, institution logos, author photos, journal marks, or unsupported mechanisms.
+- Prefer short labels and simple shapes. AI image models can misspell text; final publication labels should usually be redrawn in Illustrator, Inkscape, PowerPoint, or a Python/R vector workflow.
+- If the schematic could be interpreted as a data panel, explicitly mark it as conceptual.
+- Do not send confidential manuscript content to OpenRouter without user permission.
+
+## Prompt contract
+
+Before calling the API, collect or infer:
+
+1. article title or central claim
+2. key biological/material/computational entities
+3. cause-effect mechanism or workflow stages
+4. desired layout, such as left-to-right pipeline, circular mechanism, split before/after, or graphical abstract
+5. target aspect ratio and output format
+6. any labels that must appear, keeping them short
+7. things that must be excluded
+8. target journal, policy URL, access date, and intended AI-use disclosure
+
+Write a compact prompt with:
+
+- visual role: "Nature-style graphical abstract" or "clean scientific mechanism schematic"
+- composition: panel flow, hierarchy, and focal element
+- style: flat vector-like, restrained palette, high contrast, white or transparent background
+- scientific constraints: no fabricated numbers, no extra organs/cells/materials, no logos
+- output constraints: minimal text, editable downstream, journal-safe
+
+## Script usage
+
+Use the bundled script for reproducible calls:
+
+```bash
+export OPENROUTER_API_KEY="sk-or-..."
+python skills/nature-figure/scripts/generate_openrouter_schematic.py \
+  --title "Paper title" \
+  --abstract-file abstract.txt \
+  --panel-map "left: problem; center: proposed mechanism; right: validated outcome" \
+  --outdir outputs/schematic \
+  --basename graphical_abstract \
+  --aspect-ratio 16:9 \
+  --resolution 2K \
+  --quality high
+```
+
+Dry-run without network or API key:
+
+```bash
+python skills/nature-figure/scripts/generate_openrouter_schematic.py \
+  --title "Self-healing cementitious sensor" \
+  --abstract "A composite sensor couples chloride ingress with recoverable piezoresistive response." \
+  --panel-map "left: marine exposure; center: ion transport and microcrack healing; right: signal recovery curve" \
+  --dry-run
+```
+
+Use a fully custom prompt:
+
+```bash
+python skills/nature-figure/scripts/generate_openrouter_schematic.py \
+  --prompt-file schematic_prompt.md \
+  --raw \
+  --outdir outputs/schematic
+```
+
+Use one or more reference images:
+
+```bash
+python skills/nature-figure/scripts/generate_openrouter_schematic.py \
+  --prompt-file schematic_prompt.md \
+  --reference-image draft_layout.png \
+  --reference-image https://example.com/style-reference.png
+```
+
+The script saves generated files plus `request_metadata.json` in the output directory.
+
+Use another OpenAI-compatible images endpoint (`--api-url`, or `SCHEMATIC_IMAGE_API_URL`) when the user already pays for a gateway instead of OpenRouter. The response shape (`data[].b64_json` or `data[].url`) is the same, so nothing else changes; the endpoint actually called is recorded in `request_metadata.json`. Example with OrcaRouter:
+
+```bash
+export ORCAROUTER_API_KEY="sk-orca-..."
+python skills/nature-figure/scripts/generate_openrouter_schematic.py \
+  --api-url https://api.orcarouter.ai/v1/images/generations \
+  --api-key-env ORCAROUTER_API_KEY \
+  --model openai/gpt-image-2 \
+  --title "Paper title" \
+  --outdir outputs/schematic
+```
+
+## Recommended defaults
+
+- `model`: `openai/gpt-image-2`
+- `aspect_ratio`: `16:9` for graphical abstracts, `4:3` for mechanism figures, `1:1` for cover-like concepts
+- `resolution`: `2K` for review drafts; use higher only when needed
+- `quality`: `high`
+- `output_format`: `png`
+- `background`: `opaque` unless the user asks for transparent
+
+## Follow-up QA
+
+After generation:
+
+1. inspect the image visually
+2. check whether labels are legible and spelled correctly
+3. list any scientific hallucinations or unsupported visual claims
+4. recommend which labels or arrows should be redrawn as vector objects
+5. keep the generated image and metadata together for provenance
+6. report separate verdicts for internal design use and submission eligibility