From e1e1112541a80e902ad3d4e85b39c709a1c6aea9 Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:12:32 +0000
Subject: [PATCH 1/2] Rewrite public about/help pages for first-time users

Co-authored-by: s-t-h <23210341+s-t-h@users.noreply.github.com>
---
 app/phagegap/templates/about/contact.html     |  49 ++++----
 .../templates/about/descriptions.html         | 111 +++++++-----------
 app/phagegap/templates/about/legal.html       | 103 +++++-----------
 app/phagegap/templates/about/usage.html       |  84 +++++++++++--
 4 files changed, 167 insertions(+), 180 deletions(-)

diff --git a/app/phagegap/templates/about/contact.html b/app/phagegap/templates/about/contact.html
index 2ed7c7d..78ebab5 100644
--- a/app/phagegap/templates/about/contact.html
+++ b/app/phagegap/templates/about/contact.html
@@ -1,37 +1,28 @@
-<section id="code-availability" class="about-section">
-	<h1>Code availability</h1>
-	<p>
-		The source code of this project is freely available on GitHub: 
-		<code><a href="https://github.com/Integrative-Transcriptomics/PhageGap">Integrative-Transcriptomics/PhageGap</a></code>
-		contains the code base for this web application.
-		<code><a href="https://github.com/Integrative-Transcriptomics/phage_dark_matter">Integrative-Transcriptomics/phage_dark_matter</a></code>
-		contains the code base for the underlying prediction model.
-	</p>
-</section>
-
 <section id="contact" class="about-section">
 	<h1>Contact</h1>
-	<address style="font-family: monospace; font-size: smaller">
-		Simon Hackl [simon.hackl(at)uni-tuebingen.de]
-		<br />
-		Integrative Transcriptomics, Institute for Bioinformatics and
-		Medical Informatics, University Tübingen
-		<br />
-		Sand 14, 72076 Tübingen, Germany
-	</address>
+	<p>For questions or issues, use the project repository or contact the listed maintainer.</p>
+	<ul>
+		<li>
+			<b>Project repository:</b>
+			<a href="https://github.com/Integrative-Transcriptomics/PhageGap" target="_blank" rel="noopener">Integrative-Transcriptomics/PhageGap</a>
+		</li>
+		<li>
+			<b>Maintainer contact:</b>
+			Simon Hackl (<code>simon.hackl(at)uni-tuebingen.de</code>)
+		</li>
+		<li>
+			<b>Affiliation:</b>
+			Integrative Transcriptomics, Institute for Bioinformatics and Medical Informatics, University Tübingen
+		</li>
+	</ul>
 </section>
 
 <section id="citation" class="about-section">
-	<h1>Citation</h1>
-	<p>If you use this software, please cite it as below:</p>
+	<h2>Citation</h2>
+	<p>If you use this software, please cite:</p>
 	<div class="remark" style="font-family: monospace; font-size: smaller">
 		<p><i>PhageGAP: Prediction of phage protein function using protein language models</i></p>
-		<p>
-			Simon Hackl, Mona Scheurenbrand, Kay Nieselt, Maik Wolfram-Schauerte
-		</p>
-		<p>
-			Unpublished. GitHub:
-			<code><a href="https://github.com/Integrative-Transcriptomics/PhageGap">Integrative-Transcriptomics/PhageGap</a></code>
-		</p>
+		<p>Simon Hackl, Mona Scheurenbrand, Kay Nieselt, Maik Wolfram-Schauerte</p>
+		<p>Unpublished software; source code on GitHub.</p>
 	</div>
-</section>
\ No newline at end of file
+</section>
diff --git a/app/phagegap/templates/about/descriptions.html b/app/phagegap/templates/about/descriptions.html
index 08bc68a..bdf768f 100644
--- a/app/phagegap/templates/about/descriptions.html
+++ b/app/phagegap/templates/about/descriptions.html
@@ -1,73 +1,50 @@
-<section id="overview" class="about-section">
-	<h1>Overview</h1>
-	<p>
-		Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
-		invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
-		accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
-		sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
-		elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-		sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
-		kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-	</p>
+<section id="results-and-terms" class="about-section">
+	<h1>Results and terms</h1>
+	<p>This page explains the main items shown after you run <code>Function Classification</code>.</p>
 </section>
 
-<section id="protein-embeddings" class="about-section">
-	<h2>Protein embeddings</h2>
-	<p>
-		Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
-		invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
-		accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
-		sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
-		elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-		sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
-		kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-	</p>
+<section id="global-embedding-landscape" class="about-section">
+	<h2>Global Embedding Landscape</h2>
+	<ul>
+		<li><b>Reference points:</b> proteins from the built-in reference metadata, grouped by functional category color.</li>
+		<li><b>User Data:</b> proteins from your submission.</li>
+		<li><b>Click a User Data point:</b> opens linked details (prediction bars, nearest-neighbor alignment, structure, and optional genomic focus).</li>
+		<li><b>Nearest-neighbor link:</b> a line is drawn from the selected user protein to its nearest reference protein.</li>
+	</ul>
 </section>
 
-<section id="prediction-model" class="about-section">
-	<h2>Prediction model</h2>
-	<p>
-		Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
-		invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
-		accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
-		sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
-		elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-		sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
-		kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-	</p>
+<section id="prediction-values" class="about-section">
+	<h2>Function Prediction values</h2>
+	<ul>
+		<li><code>top1</code>, <code>top2</code>, <code>top3</code>: three ranked predicted labels.</li>
+		<li><code>P(top1)</code>, <code>P(top2)</code>, <code>P(top3)</code>: corresponding probabilities.</li>
+		<li><code>nearest_neighbor_ID</code>: closest reference protein used for detailed comparison.</li>
+		<li><code>nearest_neighbor_distance</code>: distance to that reference in embedding space (smaller means closer).</li>
+	</ul>
 </section>
 
-<section id="functional-classes" class="about-section">
-	<h2>Functional classes</h2>
-	<p>
-		Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
-		invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
-		accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
-		sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
-		elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-		sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
-		kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-	</p>
-	<table class="table striped compact">
-		<thead>
-			<tr>
-				<th>Class</th>
-				<th>Description</th>
-			</tr>
-		</thead>
-		<tbody>
-			<tr>
-				<td>Class A</td>
-				<td>Lorem ipsum dolor sit amet.</td>
-			</tr>
-			<tr>
-				<td>Class B</td>
-				<td>Lorem ipsum dolor sit amet.</td>
-			</tr>
-			<tr>
-				<td>Class C</td>
-				<td>Lorem ipsum dolor sit amet.</td>
-			</tr>
-		</tbody>
-	</table>
-</section>
\ No newline at end of file
+<section id="nearest-neighbor-views" class="about-section">
+	<h2>Nearest-neighbor views</h2>
+	<ul>
+		<li><b>Sequence Alignment:</b> residue-level comparison between your selected protein and its nearest neighbor.</li>
+		<li><b>Structure view:</b> nearest-neighbor 3D structure with alignment-based coloring; available quality values may include mean pLDDT and predicted TM-score.</li>
+	</ul>
+</section>
+
+<section id="genomic-context-meaning" class="about-section">
+	<h2>Genomic Context</h2>
+	<p>After GFF upload, CDS features are shown by genomic position and strand.</p>
+	<ul>
+		<li>If a CDS <code>Name</code> matches a submitted protein ID, its block is colored by the predicted category.</li>
+		<li>Feature tooltips can show <code>ID</code>, <code>locus_tag</code>, position, strand, product, and predicted category.</li>
+	</ul>
+</section>
+
+<section id="functional-categories" class="about-section">
+	<h2>Functional categories used in the interface</h2>
+	<p>Reference proteins are displayed in these top-level categories:</p>
+	<div class="remark">
+		Replication, NA processing, Structural, Assembly, Translation, Anti-Defense, Effectors, Host takeover, Lysis, Lysogeny, AMGs
+	</div>
+	<p>Predicted labels (<code>top1</code> etc.) are displayed alongside their mapped top-level category in tooltips and charts.</p>
+</section>
diff --git a/app/phagegap/templates/about/legal.html b/app/phagegap/templates/about/legal.html
index 6f6ec2e..f81909b 100644
--- a/app/phagegap/templates/about/legal.html
+++ b/app/phagegap/templates/about/legal.html
@@ -1,91 +1,48 @@
 <section id="legal-information" class="about-section">
-	<h1>Legal information</h1>
+	<h1>Legal and privacy information</h1>
+	<p>This page summarizes legal and privacy-relevant behavior visible in this repository.</p>
 </section>
 
-<section id="cookie-usage" class="about-section">
-	<h2>Cookie usage</h2>
+<section id="license" class="about-section">
+	<h2>License</h2>
 	<p>
-		We use a strictly necessary non-tracking session cookie so that you can
-		access your data. (1) Your data will not be accessible to other people.
-		(2) No personalized data is collected or shared with third parties and you 
-		will not be tracked by this cookie. The cookie will automatically expire
-		after 24 you close your browser. By using our website, you consent to the
-		use of this cookie.
+		PhageGAP is distributed under the GNU General Public License v3.0.
+		See <a href="https://www.gnu.org/licenses/gpl-3.0.en.html" target="_blank" rel="noopener">GNU GPL-3.0</a> and the repository <code>LICENSE</code> file.
 	</p>
 </section>
 
-<section id="medical-disclaimer" class="about-section">
-	<h2>Medical disclaimer</h2>
-	<p>
-		If medical information is provided on this site, it is provided as an
-		information resource only, and is not to be used or relied on for any
-		diagnostic or treatment purposes.
-	</p>
+<section id="cookie-and-session-use" class="about-section">
+	<h2>Cookie and session use</h2>
+	<ul>
+		<li>A consent cookie named <code>phagegap_consent</code> is required before API requests are accepted.</li>
+		<li>A server session cookie named <code>phagegap_session</code> is used for request protection (including CSRF token handling).</li>
+		<li>Session cookie settings in this repository include <code>Secure</code>, <code>HttpOnly</code>, and <code>SameSite=Lax</code>.</li>
+	</ul>
 </section>
 
-<section id="content-liability" class="about-section">
-	<h2>Content liability</h2>
+<section id="data-handling" class="about-section">
+	<h2>Data handling (repository-based scope)</h2>
+	<ul>
+		<li>This repository implements FASTA and GFF upload/submit endpoints and returns analysis data to the browser.</li>
+		<li>This repository does not implement user accounts or a database-backed project storage layer.</li>
+		<li>Users can explicitly export results/session files locally from the browser via toolbar actions.</li>
+	</ul>
 	<p>
-		The contents of our pages were created with the utmost care. However, we
-		cannot guarantee the accuracy, completeness and actuality of the
-		content. As a service provider, we are responsible for our own content
-		on these pages under the general laws according to § 7 TMG. According to
-		§§ 8 to 10 TMG, however, we are not obligated as a service provider to
-		monitor transmitted or stored third-party information or to investigate
-		circumstances that indicate illegal activity. Obligations to remove or
-		block the use of information under the general laws remain unaffected.
-		However, liability in this regard is only possible from the point in
-		time at which a concrete infringement of the law becomes known. If we
-		become aware of such infringements, we will remove this content
-		immediately.
+		This summary reflects only this codebase. It does not by itself define external infrastructure policy or retention beyond this repository.
 	</p>
 </section>
 
-<section id="link-liability" class="about-section">
-	<h2>Link liability</h2>
+<section id="disclaimer" class="about-section">
+	<h2>Disclaimer</h2>
 	<p>
-		This page may contain links to external websites of third parties, on
-		whose contents we have no influence. We cannot take any liability for
-		these external contents. The respective provider or operator of the
-		pages is always responsible for the content of the linked pages. The
-		linked pages were checked for possible legal violations at the time of
-		linking. Illegal contents were not recognizable at the time of linking.
-		However, a permanent control of the contents of the linked pages is not
-		reasonable without concrete evidence of a violation of the law. If we
-		become aware of any infringements, we will remove such links
-		immediately.
+		The software is provided without warranty as described in GPL-3.0.
+		Use results as computational support and verify findings in your own analysis workflow.
 	</p>
 </section>
 
-<section id="data-privacy" class="about-section">
-	<h2>Data privacy</h2>
-	<p>
-		The use of our website is possible without providing personal data and
-		no processed data is stored. If personal data (such as name, address or
-		e-mail addresses) is collected, this is on a voluntary basis. This data
-		will not be passed on to third parties without your express consent. We
-		point out that data transmission over the Internet (e.g. communication
-		by e-mail) may yield security gaps. Complete protection of data against
-		access by third parties is not possible. The use of contact data
-		published within the framework of the impressum by third parties for the
-		purpose of sending advertising and information material is hereby
-		expressly prohibited. The operators of the pages expressly reserve the
-		right to take legal action in the event of the sending of advertising
-		information, such as spam e-mails.
-	</p>
+<section id="required-legal-details" class="about-section">
+	<h2>Additional legal details</h2>
+	<!-- TODO: Add legally required provider/impressum details (responsible entity, address, and official contact channel). -->
+	<!-- TODO: Add deployment-specific privacy details (hosting provider, log retention, and any external processors), if applicable. -->
+	<p>Some deployment-specific legal details are not defined in this repository and must be provided by the operating institution.</p>
 </section>
-
-<section id="copyright" class="about-section">
-	<h2>Copyright</h2>
-	<p>
-		This program is free software: you can redistribute it and/or modify it
-		under the terms of the GNU General Public License as published by the
-		Free Software Foundation, either version 3 of the License, or (at your
-		option) any later version. This program is distributed in the hope that
-		it will be useful, but WITHOUT ANY WARRANTY; without even the implied
-		warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-		GNU General Public License for more details: <a
-		href="https://www.gnu.org/licenses/gpl-3.0.en.html"
-		target="_blank">www.gnu.org/licenses/gpl-3.0.en</a>.
-	</p>
-</section>
\ No newline at end of file
diff --git a/app/phagegap/templates/about/usage.html b/app/phagegap/templates/about/usage.html
index 42abd13..2852d48 100644
--- a/app/phagegap/templates/about/usage.html
+++ b/app/phagegap/templates/about/usage.html
@@ -1,12 +1,74 @@
 <section id="usage" class="about-section">
-	<h1>Usage</h1>
-	<p>
-		Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor
-		invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et
-		accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata
-		sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing
-		elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat,
-		sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita
-		kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.
-	</p>
-</section>
\ No newline at end of file
+	<h1>How to use PhageGAP</h1>
+
+	<h2>Quick start</h2>
+	<ol>
+		<li>Paste protein FASTA text and/or upload a FASTA file.</li>
+		<li>Click <code>Function Classification</code>.</li>
+		<li>Click a <code>User Data</code> point in the <code>Global Embedding Landscape</code> to inspect predictions, nearest-neighbor alignment, and structure.</li>
+		<li>Optionally add genomic context from a GFF file.</li>
+	</ol>
+</section>
+
+<section id="provide-protein-sequences" class="about-section">
+	<h2>1) Provide protein sequences</h2>
+	<p>You can submit sequence data by text input, file upload, or both together. PhageGAP combines both inputs into one analysis request.</p>
+	<ul>
+		<li>Input must contain valid FASTA records.</li>
+		<li>The first token after <code>&gt;</code> is used as <code>protein_ID</code>.</li>
+		<li>The full FASTA header line is kept as description text.</li>
+		<li>Use unique protein IDs. Duplicate IDs in one submission keep only the last record; IDs already loaded in the current session are not added again.</li>
+	</ul>
+	<pre><code>&gt;prot_001 putative capsid protein
+MNNR...
+&gt;prot_002 tail fiber protein
+MDSK...</code></pre>
+</section>
+
+<section id="run-analysis" class="about-section">
+	<h2>2) Run the analysis</h2>
+	<p>Click <code>Function Classification</code> to submit your proteins. New results are appended to your current session and shown as <code>User Data</code> in the landscape view.</p>
+	<p class="remark"><b>Important:</b> Classification and GFF uploads are rate-limited. If you submit again too quickly, wait and retry.</p>
+</section>
+
+<section id="explore-results" class="about-section">
+	<h2>3) Explore the results</h2>
+	<ul>
+		<li><b>Global Embedding Landscape:</b> shows reference proteins by category and your submitted proteins as <code>User Data</code>.</li>
+		<li><b>Function Prediction and Nearest Neighbor Structure:</b> top predictions (<code>top1</code>, <code>top2</code>, <code>top3</code>) with probabilities, plus nearest-neighbor structure.</li>
+		<li><b>Nearest Neighbor Sequence Alignment:</b> aligned residues for the selected protein and its nearest neighbor.</li>
+		<li><b>Selection tools:</b> clear selection, zoom the landscape, or maximize the structure panel.</li>
+	</ul>
+	<p>Click any <code>User Data</code> point to update all linked views.</p>
+</section>
+
+<section id="add-genomic-context" class="about-section">
+	<h2>4) Add genomic context</h2>
+	<p>Use <code>Add Genomic Context</code> in the toolbar to upload a <code>.gff</code> or <code>.gff3</code> file.</p>
+	<ul>
+		<li>Only <code>CDS</code> features are used.</li>
+		<li>Features should provide standard 9-column GFF records with <code>key=value</code> attributes.</li>
+		<li>For linking to submitted proteins, the GFF <code>Name</code> attribute must match FASTA protein IDs.</li>
+	</ul>
+	<p>When IDs match, predicted categories are shown on genomic features and selection in the landscape can zoom to local genomic neighborhoods.</p>
+</section>
+
+<section id="save-restore-export" class="about-section">
+	<h2>5) Save, restore, or export</h2>
+	<ul>
+		<li><code>Download Results</code>: exports current user results as TSV (<code>phagegap-results-YYYY-MM-DD.tsv</code>).</li>
+		<li><code>Download Session</code>: exports selected protein, user results, and genomic features as compressed JSON (<code>.json.gz</code>).</li>
+		<li><code>Reload Session</code>: restores a saved session file (<code>.gz</code> / <code>.json.gz</code>).</li>
+		<li><code>Screenshot</code>: saves a PNG image of the current analysis panels.</li>
+	</ul>
+</section>
+
+<section id="usage-notes" class="about-section">
+	<h2>Tips and important notes</h2>
+	<ul>
+		<li>You must accept the cookie consent banner before API-backed features are enabled.</li>
+		<li>At least one valid FASTA record is required.</li>
+		<li>Large requests may fail (server request size limit is approximately 500 KB).</li>
+	</ul>
+	<p>For interpretation guidance, see <a href="#results-and-terms">Results and terms</a>.</p>
+</section>

From d2514b954505b3ff43be7b1dea6421faa6e23b5c Mon Sep 17 00:00:00 2001
From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com>
Date: Fri, 21 Aug 2026 23:13:06 +0000
Subject: [PATCH 2/2] Add repository URL to citation section

Co-authored-by: s-t-h <23210341+s-t-h@users.noreply.github.com>
---
 app/phagegap/templates/about/contact.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/app/phagegap/templates/about/contact.html b/app/phagegap/templates/about/contact.html
index 78ebab5..30c85bd 100644
--- a/app/phagegap/templates/about/contact.html
+++ b/app/phagegap/templates/about/contact.html
@@ -23,6 +23,6 @@ <h2>Citation</h2>
 	<div class="remark" style="font-family: monospace; font-size: smaller">
 		<p><i>PhageGAP: Prediction of phage protein function using protein language models</i></p>
 		<p>Simon Hackl, Mona Scheurenbrand, Kay Nieselt, Maik Wolfram-Schauerte</p>
-		<p>Unpublished software; source code on GitHub.</p>
+		<p>Unpublished software; source code: <a href="https://github.com/Integrative-Transcriptomics/PhageGap" target="_blank" rel="noopener">https://github.com/Integrative-Transcriptomics/PhageGap</a></p>
 	</div>
 </section>