Polish README and JOSS manuscript visuals

MANIFEST.in

@@ -15,3 +15,5 @@ recursive-include src/diffractscout/benchmark_data *.cif *.json
 
 recursive-include docs/joss *.md *.json
 include scripts/check_joss_artifacts.py
+
+recursive-include paper *.pdf *.json

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/hero.svg" width="100%" alt="DiffractScout: provenance-first phase scouting and indexed powder diffraction references.">
+  <img src="docs/assets/hero.png" width="100%" alt="DiffractScout: Traceable powder-diffraction references. AI-generated conceptual illustration.">
 </p>
 
 # DiffractScout
@@ -27,6 +27,8 @@ for retained formats, engine differences and validation limits.
 
 ## Why this software exists
 
+<p align="center"><img src="paper/fig_workflow.png" width="100%" alt="Workflow from structure inputs to a verified diffraction-reference bundle."></p>
+
 Candidate-phase assessment commonly involves several disconnected operations: interpret an alloy grade, enumerate chemical subsystems, query a computed-materials database, download structures, inspect CIF metadata, calculate theoretical reflections, locate elastic constants, and prepare tables for experimental planning. Ad hoc scripts often lose the relationship between the provider record, exact CIF setting, tensor basis, diffraction settings, and final spreadsheet.
 
 DiffractScout represents that chain as one research object. It supports two entry points:

README.zh-CN.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="docs/assets/hero.svg" width="100%" alt="DiffractScout：可追溯的候选相筛选与理论粉末衍射参考工作流。">
+  <img src="docs/assets/hero.png" width="100%" alt="DiffractScout: Traceable powder-diffraction references. AI-generated conceptual illustration.">
 </p>
 
 # DiffractScout 中文说明

docs/assets/hero-generation.json

@@ -0,0 +1,12 @@
+{
+  "name": "DiffractScout",
+  "subtitle": "Traceable powder-diffraction references",
+  "palette": "Warm ivory, ink navy, cobalt blue and muted copper",
+  "motif": "A crystalline unit-cell wireframe transitioning through three beautifully arranged translucent document sheets into a crisp idealized powder-diffraction stick pattern. The sheets imply a CIF and provenance record. No scientific numerical values, fake interface, or illegible paragraph text.",
+  "tool": "image_gen built-in; model identifier not exposed",
+  "revision": null,
+  "prompt": "Create one exceptionally polished scientific software README cover banner, wide landscape approximately 2.4:1 aspect ratio, premium editorial art direction, high resolution. Project: DiffractScout. Palette: Warm ivory, ink navy, cobalt blue and muted copper. Concept: A crystalline unit-cell wireframe transitioning through three beautifully arranged translucent document sheets into a crisp idealized powder-diffraction stick pattern. The sheets imply a CIF and provenance record. No scientific numerical values, fake interface, or illegible paragraph text. Compose generous negative space and sharply legible refined sans-serif typography integrated with the scientific motif. Exact text, no other copy: \"DiffractScout\" large, \"Traceable powder-diffraction references\" smaller, and a discreet \"Conceptual illustration\". Make name/subtitle read immediately at GitHub width. Restrained three-dimensional material, carefully controlled highlights, precise linework, sophisticated hierarchy and balanced composition. No generic AI neon clouds, no random particles, no badges, no claims, no photoreal experimental data, no fake application screenshot, no watermarks or publisher branding. This is an editorial cover, not a quantitative paper figure.",
+  "created_on": "2026-09-27",
+  "purpose": "README conceptual cover only, not experimental data or software output",
+  "sha256": "af2419e8a167f26909203ab2d04153a78fef7a3f5604a943c713896bdef63f2c"
+}

docs/joss/submission-record.json

@@ -45,7 +45,8 @@
   },
   "ai_assistance": {
     "current_round": "OpenAI Codex, GPT-6, 2026-09-27: repository audit, packaging, tests, documentation, manuscript and bibliography preparation, validation and Git integration.",
-    "historical_disclosure": "Retain project-specific disclosures; AbsSAXS AI history is not copied to these projects."
+    "historical_disclosure": "Retain project-specific disclosures; AbsSAXS AI history is not copied to these projects.",
+    "visual_revision": "2026-09-27: Codex revised reproducible manuscript figure scripts, captured real application widgets and prepared conceptual README covers using the built-in image-generation tool (model identifier not exposed). Prompt and image provenance are retained in the repository. Final author review remains pending."
   },
   "submission_date": null,
   "related_publications": [

docs/joss/visual-provenance.md

@@ -0,0 +1,16 @@
+# Visual sources and reproduction
+
+The September 2026 visual revision separates editorial illustrations from research-software evidence.
+
+- `docs/assets/hero.png` is an AI-generated **conceptual illustration** for the README. It is not detector data, a calculated result, or an application screenshot. The prompt, tool description and file hash are in `hero-generation.json` beside it. The built-in image tool did not expose a model identifier; no specific model-version claim is made.
+- The editable section headers use repository-owned SVG. The previous SVG cover remains as an alternative source asset.
+- Manuscript diagrams and numerical plots are generated by the repository scripts below, with SVG and PDF vector exports and 450 dpi PNGs. Scientific arrays, reflection positions, and solver observations are not modified by an image-generation model.
+- Numerical demonstrations use only the bundled synthetic fixtures and actual software calculations. AnisoScope's interface figure, where applicable, is captured from real Qt widgets; the capture JSON records its inputs and hash.
+
+From the repository root, with the project's dependencies and Matplotlib installed:
+
+```bash
+python paper/make_figures.py
+```
+
+Inspect the generated images and recompile `paper/paper.md` using the official draft-PDF workflow after any figure change. The README cover is not included as a scientific manuscript figure. Synthetic verification is not independent reproduction of the Acta Materialia experimental study.

paper/README.md

@@ -1,38 +1,9 @@
-# JOSS paper sources
+# JOSS manuscript and figure sources
 
-This directory contains the JOSS manuscript and its reproducible figures:
+The current manuscript is `paper.md`; bibliography is `paper.bib`. The two figures are generated by `python paper/make_figures.py` from the software workflow and the bundled synthetic FCC fixture. PNG (450 dpi), SVG and PDF exports are retained. The script verifies the generated result bundle before plotting.
 
-- **paper.md**: Markdown manuscript with the required JOSS sections and YAML metadata.
-- **paper.bib**: cited crystallography, software, data-service, and source-project records.
-- **fig_workflow.png** and **fig_validation.png**: manuscript figures; their editable SVGs are retained beside them.
-- **make_figures.py**: deterministic source for the two figures.
-- **paper.pdf**: a generated preview only. It is stale after any manuscript, bibliography, or figure change. The Open Journals draft build is authoritative.
+`paper.pdf` is a generated preview, not publication evidence. The exact-source artifact from the Open Journals draft-PDF workflow is authoritative after every manuscript or figure change. Official draft watermarks and publication-field placeholders remain in this preview.
 
-The current four-page A4 preview was generated by the [Open Journals build on 26 September 2026](https://github.com/D-sudoasd/DiffractScout/actions/runs/36242597087) from [commit a09ee1b](https://github.com/D-sudoasd/DiffractScout/commit/a09ee1b0e48de4bf07898bceda4bec46b70dab43). Its source files and PDF bytes were checked against the workflow artifact, and all four rendered pages and the extracted text were inspected. The DRAFT watermark and placeholder journal DOI, volume, and page fields belong to the official preview template.
+Current author confirmations, actual-use records and outstanding submission requirements are maintained in [docs/joss](../docs/joss/README.md). Earlier readiness records do not override that record. The Acta Materialia DOI is identified; historical software revision and operation-to-output mapping still require processing records. Final human review remains pending.
 
-The manuscript describes a bounded workflow contribution: linking candidate records, source CIFs, calculation settings, diagnostic states, theoretical references, and their exported result bundle. It does not claim a new diffraction or elasticity algorithm. The developer reports prior use in several published materials-science papers; those records and their exact software-version links have not yet been provided for citation-level traceability.
-
-## Submission inputs still required
-
-Complete these items before submitting to JOSS:
-
-1. **Public development history.** The repository became public at 10:02:29 UTC on 12 August 2026. The current JOSS guidance asks for more than six months of public development history when a repository is recent, with sustained development and supporting release, issue, or pull-request evidence. On the manuscript date of 26 September 2026, this period is not yet met; submission should be after 10:02:29 UTC on 12 February 2027, and 15 February 2027 is a practical earliest date if development and the other criteria remain adequate.
-2. **Published-use evidence.** Provide representative paper titles and DOI or stable links, identify where DiffractScout was used in each study, and give the software version or commit where possible. The manuscript currently attributes this use to the developer's report and does not cite unidentified papers.
-3. **Funding and acknowledgements.** Provide any funding body and grant identifiers and state whether funders influenced software design, data collection, analysis, or publication. If there was no external financial support, confirm that explicitly. Add any additional acknowledgements that belong in the manuscript.
-4. **Author list.** Delun Gong's name, ORCID, and affiliation were confirmed for this draft. Confirm that the author list is complete and that all listed authors agree to authorship.
-5. **Human review of AI-assisted work.** Earlier repository work and this revision used OpenAI GPT-5.6 Pro, OpenAI Codex GPT-6, and cooperating assistant agents across software, tests, figures, documentation, and manuscript work. Automated checks are described in the manuscript, but no assertion that the human author has completed review is made. The responsible author must review, edit, and validate every AI-assisted contribution and make the core design decisions before the JOSS AI disclosure can assert compliance.
-6. **Submission date.** Update the JOSS metadata date to the actual submission date if the submission happens after this draft.
-7. **Archived software citation.** JOSS requests a tagged, archived software release with a DOI after successful review. At that stage, replace or supplement the source-repository citation in paper.bib with the DOI for the reviewed release; do not invent a DOI beforehand.
-
-The independent analytic benchmark and synthetic fixtures are software checks. They are not experimental validation and should not be presented as research-use evidence.
-
-## Figures
-
-Regenerate figures from the current package:
-
-    python -m pip install -e ".[paper]"
-    SOURCE_DATE_EPOCH=1786492800 python paper/make_figures.py
-
-## Paper build
-
-Build the draft with .github/workflows/draft-pdf.yml or Docker through scripts/build_paper.sh. Render and inspect every page after the paper source is frozen. The checked-in paper.pdf is not updated as part of a manuscript-only revision.
+See [visual provenance](../docs/joss/visual-provenance.md) for conceptual README covers versus reproducible scientific plots.