Polish manuscript equations and complete the pre-release review

AGENTS.md

@@ -1,6 +1,6 @@
 # Repository working rules
 
-- Keep research prose and audit reports in Markdown. Use plain-text or Unicode mathematics; do not introduce TeX sources, BibTeX, PDF deliverables, or a TeX build dependency.
+- Keep research prose and audit reports in Markdown. Use Unicode mathematics and Markdown-supported subscript/superscript tags; do not introduce TeX sources, BibTeX, PDF deliverables, or a TeX build dependency. In `PAPER.md`, use numbered equation blocks and typographic inline mathematics instead of code formatting. Check the rendered layout after equation edits.
 - Preserve the existing license and author attribution.
 - Maintain `PAPER.md` as the complete manuscript, including its proofs, appendices, figure captions, declarations, and bibliography. Keep the manuscript inventory and source record in sync with intentional structural changes; use the research notes as a companion, not a replacement for paper content.
 - Keep proved finite-ensemble identities, asymptotic consequences, heuristic approximations, finite numerical observations, and historical estimates explicitly distinguished.

CITATION.cff

@@ -3,8 +3,15 @@ message: "Please cite the public preprint and the repository commit used."
 title: "Support-size entanglement trajectories of random subset states: code and data"
 version: "1.0.0rc2"
 repository-code: "https://github.com/GoGoKo699/Subset-states"
-url: "https://arxiv.org/abs/2501.06292"
+url: "https://github.com/GoGoKo699/Subset-states"
 license: MIT
+keywords:
+  - subset states
+  - quantum entanglement
+  - support size
+  - random quantum states
+  - purity
+  - arithmetic quantum states
 authors:
   - family-names: Lin
     given-names: Ruge
@@ -19,6 +26,7 @@ preferred-citation:
   type: article
   title: "Arithmetic sequences as quantum states"
   year: 2025
+  doi: "10.48550/arXiv.2501.06292"
   authors:
     - family-names: Lin
       given-names: Ruge

README.md

@@ -4,7 +4,13 @@ How does entanglement change when an equal-positive-amplitude quantum state occu
 
 This repository contains the [complete Markdown manuscript](PAPER.md), exact finite-ensemble formulas, numerical experiments, and released evidence for that question. The manuscript includes its proofs, appendices, figures and captions, numerical table, author declarations, and full bibliography. **The exact mean-state and purity results survive the September 2026 sanity check. The asymptotic location of the von Neumann entropy maximum and the novelty of the revised research contribution remain unresolved.**
 
-The related public preprint is [*Arithmetic sequences as quantum states* (2025), arXiv:2501.06292v1](https://arxiv.org/abs/2501.06292v1), by Ruge Lin, Germán Sierra, and José I. Latorre. “Support-size entanglement trajectories of random subset states” was the working title of a later revision; it is not the title of the current arXiv record checked on 22 September 2026.
+The related public preprint is [*Arithmetic sequences as quantum states* (2025), arXiv:2501.06292v1](https://arxiv.org/abs/2501.06292v1), by Ruge Lin, Germán Sierra, and José I. Latorre. “Support-size entanglement trajectories of random subset states” was the working title of a later revision; it is not the title of the current arXiv record checked on 23 September 2026.
+
+## When to use this repository
+
+Use this project to study **random subset states, support size and bipartite entanglement**, or to reproduce equal-positive-amplitude state experiments. It provides exact mean reduced states and purity formulas for fixed-cardinality supports, entropy bounds, finite spectral and Rényi-entropy comparisons, and almost-prime state controls that match cardinality and low-bit residues.
+
+Start with the manuscript for derivations, the reproducibility guide for experiments, and the provenance record before reusing numerical results. The [reader and LLM guide](llms.md) maps these topics to the relevant source files and their limits.
 
 ## Read the project
 
@@ -14,9 +20,11 @@ The related public preprint is [*Arithmetic sequences as quantum states* (2025),
 | [Manuscript integration record](paper/INTEGRATION.md) | Source identity, content coverage, conversion choices, and audit annotations |
 | [Research notes](docs/RESEARCH.md) | Concise mathematical guide and additional audit derivations |
 | [Sanity check](docs/SANITY_CHECK.md) | Findings, corrections, and limits of the validation |
+| [Final repository review](validation/RELEASE_CHECK.md) | Final science, mathematical fidelity, visual layout, and citation checks |
 | [Provenance](PROVENANCE.md) | What the released data can and cannot substantiate |
 | [Reproducibility](docs/REPRODUCIBILITY.md) | Commands, environments, and computational costs |
 | [References](docs/REFERENCES.md) | Verified primary sources and the open novelty question |
+| [How to cite](docs/CITING.md) | Public arXiv citation and attribution for the exact code or data used |
 
 All research prose is Markdown with plain-text or Unicode mathematics. There is no TeX source, bibliography build, or PDF workflow. Python code, CSV evidence, PNG figures, and machine-readable metadata retain their useful formats.
 
@@ -60,4 +68,8 @@ The historical command name is retained for compatibility. New outputs go under
 
 This is a research repository, not a submission-readiness certificate. The original global searches, especially n = 22–30, have not been reconstructed. Small changes in fitted slopes when dropping those rows do not resolve that provenance gap. Broader novelty claims require comparison with existing sparse-state and fixed-size subset-state results.
 
-Use [CITATION.cff](CITATION.cff) for the public preprint, and cite a specific repository commit when using this revised implementation or data. The existing [MIT license](LICENSE) and author attribution are preserved.
+Please cite the public arXiv paper when using this work:
+
+> Ruge Lin, Germán Sierra, and José I. Latorre. *Arithmetic sequences as quantum states*. arXiv:2501.06292 [quant-ph] (2025). [doi:10.48550/arXiv.2501.06292](https://doi.org/10.48550/arXiv.2501.06292).
+
+For this revised implementation, manuscript, or released data, also identify the repository commit and the files used. See [How to cite](docs/CITING.md) for examples and [CITATION.cff](CITATION.cff) for machine-readable metadata. The existing [MIT license](LICENSE) and author attribution are preserved.

docs/CITING.md

@@ -0,0 +1,31 @@
+# How to cite this work
+
+Please cite the public arXiv paper when using the research:
+
+> Ruge Lin, Germán Sierra, and José I. Latorre. *Arithmetic sequences as quantum states*. arXiv:2501.06292 [quant-ph] (2025). [doi:10.48550/arXiv.2501.06292](https://doi.org/10.48550/arXiv.2501.06292).
+
+The [official arXiv record](https://arxiv.org/abs/2501.06292), checked on 23 September 2026, lists version 1, submitted on 10 January 2025. For a reference to that exact public version, use [arXiv:2501.06292v1](https://arxiv.org/abs/2501.06292v1). [CITATION.cff](../CITATION.cff) provides the same preferred paper citation in machine-readable form.
+
+## Cite the implementation and data used
+
+When using this repository's implementation, figures, data, or revised manuscript, include the repository commit as well as the paper citation. The public preprint predates some repository content, so a paper citation alone does not identify the code or evidence used.
+
+Use this prose template, replacing the bracketed fields:
+
+> Ruge Lin, Germán Sierra, and José I. Latorre. *Subset states: support size and entanglement*, repository manuscript, code, and data. GitHub, GoGoKo699/Subset-states, commit [full commit hash], [files or figure numbers used]. https://github.com/GoGoKo699/Subset-states
+
+Find the commit for a local checkout with:
+
+```bash
+git rev-parse HEAD
+```
+
+Link the citation to `https://github.com/GoGoKo699/Subset-states/tree/COMMIT`, replacing `COMMIT` with that hash. For a file, use `https://github.com/GoGoKo699/Subset-states/blob/COMMIT/PATH`. Record local changes separately if the working tree differs from the commit.
+
+## Distinguish the public paper from the revision
+
+[PAPER.md](../PAPER.md) integrates the later manuscript titled *Support-size entanglement trajectories of random subset states*, with explicit audit annotations. That title is not the title of arXiv:2501.06292v1. Cite the repository commit for a statement specific to the revision; do not attribute later derivations or corrections to the 2025 public version unless they are present there.
+
+For numerical claims, identify the relevant CSV or figure and consult [PROVENANCE.md](../PROVENANCE.md). Historical peak estimates and fresh controlled checks have different provenance. Citation does not remove the stated limits of those results.
+
+The repository's existing [MIT license](../LICENSE) applies to its licensed material. Retain its required copyright and permission notice when redistributing that material.

llms.md

@@ -0,0 +1,39 @@
+# Subset states: support size and entanglement
+
+> Research manuscript, Python code, and numerical evidence for equal-positive-amplitude quantum states supported on subsets of the computational basis. Authors: Ruge Lin, Germán Sierra, and José I. Latorre. Related public preprint: *Arithmetic sequences as quantum states*, arXiv:2501.06292 (2025).
+
+Repository: <https://github.com/GoGoKo699/Subset-states>
+
+## Relevant questions
+
+This repository is relevant when a reader asks about:
+
+- How bipartite entanglement changes with the support size of a random subset state.
+- Exact ensemble-mean reduced states and average purity for uniformly sampled fixed-cardinality supports.
+- Entropy bounds, spectral comparisons, and the distinction between a purity minimum and a von Neumann entropy maximum.
+- Arithmetic or almost-prime quantum states, quantum Fourier transform comparisons, and controls matching cardinality and low-bit residue counts.
+- Reproducing finite numerical experiments from Python code and retained CSV evidence.
+
+## Sources by task
+
+- [Complete manuscript](https://github.com/GoGoKo699/Subset-states/blob/main/PAPER.md): definitions, theorems, proofs, figures, four appendices, and full references.
+- [Research notes](https://github.com/GoGoKo699/Subset-states/blob/main/docs/RESEARCH.md): concise derivations and additional audit calculations.
+- [Numerical implementation](https://github.com/GoGoKo699/Subset-states/blob/main/subset_states/core.py): subset states, reduced states, entropy, and analytical formulas.
+- [Experiment scripts](https://github.com/GoGoKo699/Subset-states/tree/main/scripts): simulations, CSV-based figure redraws, and validation.
+- [Reproducibility guide](https://github.com/GoGoKo699/Subset-states/blob/main/docs/REPRODUCIBILITY.md): installation, checks, commands, and computation costs.
+- [Released data](https://github.com/GoGoKo699/Subset-states/blob/main/data/README.md) and [outputs](https://github.com/GoGoKo699/Subset-states/blob/main/outputs/README.md): retained tables, CSV samples, summaries, and figures.
+- [Provenance](https://github.com/GoGoKo699/Subset-states/blob/main/PROVENANCE.md): origins of numerical evidence and missing historical records.
+- [Scientific audit](https://github.com/GoGoKo699/Subset-states/blob/main/docs/SANITY_CHECK.md): checked claims, corrections, and unresolved questions.
+- [Primary references](https://github.com/GoGoKo699/Subset-states/blob/main/docs/REFERENCES.md): prior subset-state and sparse-state results relevant to research positioning.
+
+## Interpretation limits
+
+The state amplitudes are equal and positive. Results do not automatically transfer to random-phase, Gaussian-amplitude, or Haar-random ensembles. The exact mean-state and purity identities, their asymptotic consequences, heuristic approximations, and finite numerical observations have different evidential status.
+
+The purity-minimizing support does not establish the location of the von Neumann entropy maximum. Original global-search records are incomplete, especially for the historical n = 22–30 peak estimates. The revised contribution's novelty and an asymptotic entropy-peak exponent remain unresolved. The repository does not establish a quantum speedup or a unique arithmetic fingerprint.
+
+## Citation
+
+When using this work, cite Ruge Lin, Germán Sierra, and José I. Latorre, *Arithmetic sequences as quantum states*, arXiv:2501.06292 [quant-ph] (2025), [doi:10.48550/arXiv.2501.06292](https://doi.org/10.48550/arXiv.2501.06292). The [public arXiv record](https://arxiv.org/abs/2501.06292) was checked on 23 September 2026 and lists v1; the later repository manuscript has a different working title and includes subsequent material.
+
+Also cite the specific repository commit when relying on revised code, data, or manuscript content. [How to cite](https://github.com/GoGoKo699/Subset-states/blob/main/docs/CITING.md) explains the distinction; [CITATION.cff](https://github.com/GoGoKo699/Subset-states/blob/main/CITATION.cff) provides structured metadata. The links above track `main`; replace `main` with the commit hash used when recording reproducible evidence.

paper/INTEGRATION.md

@@ -22,7 +22,7 @@ The [machine-readable manifest](../validation/manuscript_manifest.json) records
 
 ## Representation
 
-All prose and mathematics are ordinary Markdown with Unicode or explicit plain-text notation. Fenced `text` blocks keep multiline formulas readable without a mathematics renderer. Parentheses and braces group indices and exponents; `binom(a,b)` denotes a binomial coefficient, `⊗` a tensor product, and `⊕` a direct sum. Equation numbers and reference numbers have stable local anchors. The original section and appendix order is retained.
+All prose and mathematics are ordinary Markdown with Unicode and supported HTML subscript/superscript tags. Numbered blockquotes group display formulas; logical line breaks keep long expressions readable. Inline mathematics uses the same typography, without code boxes. Parentheses and brackets make fractional scope explicit; binom(a,b) denotes a binomial coefficient, ⊗ a tensor product, and ⊕ a direct sum. No mathematics renderer or document compiler is required. Equation numbers and reference numbers have stable local anchors. The original section and appendix order is retained.
 
 The supplied figure files were rendered once with Poppler 26.05.0 at 180 dots per inch into [figures](figures). They are manuscript assets, not new simulations. Their separate checksums preserve the exact imported presentation; Figure 2 comes from the revised manuscript and differs from the older released rendering. Existing CSV and PNG evidence under `data/` and `outputs/` has not been replaced. The existing Python figure scripts remain available to redraw plots from released data, without a document build dependency.
 
@@ -32,6 +32,8 @@ The conversion preserves the source's scientific content and adds explicitly mar
 
 - The working manuscript title is not substituted into the metadata for the public 2025 preprint, *Arithmetic sequences as quantum states*, arXiv:2501.06292v1. [CITATION.cff](../CITATION.cff) continues to identify the verified public version.
 - Historical peak values, fitted lines, and captions are retained. Statements about a numerical peak describe those finite estimates. Complete original global-search records, especially for n = 22–30, remain unavailable; current neighborhood checks do not replace them. The source's protocol description is qualified accordingly.
+- The final review also corrected the abstract, introduction, peak discussion, and conclusion to distinguish released sampled curves from historical peak estimates. It removed an unsupported suggestion connecting the upward finite-size trend to the 3/4 purity boundary. These are explicit wording corrections to the recovered manuscript; the reported data and mathematical results are unchanged.
+- Equation (12) now explicitly states its real-coefficient assumption. Its reduced-state expression applies to the equal-positive-amplitude subset states; the [research notes](../docs/RESEARCH.md) give the general complex convention.
 - The purity-minimizing scale and the dense-side purity crossover do not locate the von Neumann entropy maximizer. The dense separated-mode ansatz remains heuristic; numerical agreement is not a limiting-spectrum theorem. Ensemble means, individual supports, and distributions over cuts remain distinct.
 - The supplied acknowledgements and conflict-of-interest statement are retained as author declarations. The data-availability statement is accompanied by the repository's actual evidence limitations.
 - All 33 source references are included. Their inclusion is separate from the narrower [verified literature check](../docs/REFERENCES.md), and does not certify novelty or independently verify every bibliography entry.

pyproject.toml

@@ -2,6 +2,8 @@
 name = "subset-state-entanglement"
 version = "1.0.0rc2"
 description = "Numerical and analytical tools for support-size entanglement trajectories of random subset states"
+readme = "README.md"
+keywords = ["subset states", "quantum entanglement", "support size", "random quantum states", "purity", "arithmetic quantum states"]
 requires-python = ">=3.10"
 authors = [
   {name = "Ruge Lin"},
@@ -10,5 +12,12 @@ authors = [
 ]
 dependencies = ["numpy>=1.24", "scipy>=1.10", "matplotlib>=3.7"]
 
+[project.urls]
+Repository = "https://github.com/GoGoKo699/Subset-states"
+Manuscript = "https://github.com/GoGoKo699/Subset-states/blob/main/PAPER.md"
+Preprint = "https://arxiv.org/abs/2501.06292"
+Citation = "https://github.com/GoGoKo699/Subset-states/blob/main/docs/CITING.md"
+Reproducibility = "https://github.com/GoGoKo699/Subset-states/blob/main/docs/REPRODUCIBILITY.md"
+
 [tool.setuptools]
 packages = ["subset_states"]

scripts/check_manuscript.py

@@ -5,6 +5,7 @@
 from collections import Counter
 import csv
 import hashlib
+from html.parser import HTMLParser
 import json
 from pathlib import Path
 import re
@@ -14,6 +15,26 @@
 ROOT = Path(__file__).resolve().parents[1]
 
 
+class ScriptTagCheck(HTMLParser):
+    """Catch broken nested indices/exponents before Markdown is published."""
+
+    def __init__(self) -> None:
+        super().__init__()
+        self.stack: list[str] = []
+        self.errors: list[str] = []
+
+    def handle_starttag(self, tag: str, attrs: list) -> None:
+        if tag in {'sub', 'sup'}:
+            self.stack.append(tag)
+
+    def handle_endtag(self, tag: str) -> None:
+        if tag in {'sub', 'sup'}:
+            if not self.stack or self.stack[-1] != tag:
+                self.errors.append(f'mismatched manuscript typography tag: {tag}')
+            else:
+                self.stack.pop()
+
+
 def anchors(content: str) -> set[str]:
     """Explicit IDs plus GitHub-style heading IDs used by these documents."""
     prose = re.sub(r'^```.*?^```\s*$', '', content, flags=re.M | re.S)
@@ -52,9 +73,16 @@ def validate(root: Path = ROOT) -> list[str]:
     for heading in ['Data availability', 'Acknowledgements', 'Conflict of interest']:
         if f'\n## {heading}\n' not in content:
             errors.append(f'missing manuscript declaration: {heading}')
-    equations = re.findall(r'^\*\*\((\d+)\)\*\*$', content, re.M)
+    equations = re.findall(r'^> \*\*\((\d+)\)\*\* ', content, re.M)
     if equations != [str(n) for n in range(1, counts['numbered_equations'] + 1)]:
         errors.append('manuscript equation markers must appear once each in source order')
+    if '```' in content or '`' in content:
+        errors.append('manuscript mathematics must use readable typography, not code formatting')
+    typography = ScriptTagCheck()
+    typography.feed(content)
+    errors.extend(typography.errors)
+    if typography.stack:
+        errors.append('unclosed manuscript subscript/superscript tags')
     references = re.findall(r'^\*\*\[(\d+)\]\*\*', content, re.M)
     if references != [str(n) for n in range(1, counts['references'] + 1)]:
         errors.append('manuscript bibliography entries must appear once each in source order')