release: prepare Doc2FAQ v0.3.1 with neutral Q&A examples

CHANGELOG.md

@@ -2,14 +2,19 @@
 
 All notable Doc2FAQ changes are recorded here. Version numbers follow semantic versioning; entries describe shipped source functionality and do not imply an external AI service.
 
-## Unreleased
+## 0.3.1
 
 ### Fixed
 
 - Avoid excessive regex backtracking on whitespace-heavy input in both FAQ modes.
 - Discard pending draft results and errors after the source, example, imported text, or mode changes.
 - Preserve separate client and provider responsibility suggestions while still filtering duplicates for the same party.
 
+### Changed
+
+- Replaced the document placeholder with neutral Q&A prompts and the Generate Mode sample with a team knowledge guide, removing payment and fee examples from the interface.
+- Added instructions for rebuilding and restarting the versioned JAR, handling occupied ports, and publishing the matching release artifact.
+
 ## 0.3.0
 
 ### Added

README.md

@@ -6,9 +6,17 @@ Doc2FAQ is a Java 21 / Spring Boot document-to-FAQ workbench. Paste text or uplo
 
 Created by **Okan Tiktas** · [OKAN-SOFTWARE](https://github.com/OKAN-SOFTWARE).
 
-> **Source version: v0.3.0.** The version in `pom.xml` identifies this build. For published tags, release downloads, and announcements, see [GitHub Releases](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases). This source version does not by itself publish a GitHub Release.
+> **Source version: v0.3.1.** The version in `pom.xml` identifies this build. For published tags, release downloads, and announcements, see [GitHub Releases](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases). This source version does not by itself publish a GitHub Release.
 
-## What's new in v0.3.0
+## What's fixed in v0.3.1
+
+- Whitespace-heavy input no longer causes excessive backtracking in FAQ question parsing.
+- Draft responses and errors are discarded after the source or mode changes, preventing stale results from being exported.
+- Client and provider responsibilities are treated as distinct topics, preserving both FAQ suggestions.
+
+The document placeholder now uses neutral Q&A prompts, and Generate Mode's sample uses a team knowledge guide instead of payment terms.
+
+## Features introduced in v0.3.0
 
 - **Extract Mode:** Find explicit Markdown question headings and Q:/A: pairs; do not invent questions or answers.
 - **Generate Mode:** Suggest questions from regular documents, such as service agreements, policies, and résumés, using section headings and the source's own words.
@@ -135,6 +143,26 @@ mvn spring-boot:run
 
 Open **http://localhost:8080**.
 
+## Build and run the JAR
+
+After updating your checkout to the latest `main`, run these commands from the directory containing `pom.xml`:
+
+```cmd
+mvn -B -ntp clean verify
+node --test src/test/js/*.test.cjs
+java -jar target/doc2faq-0.3.1.jar
+```
+
+The JavaScript checks require Node.js. Keep the terminal open while the app runs, and use **Ctrl+C** to stop it. Open **http://localhost:8080** and refresh the browser to load the updated frontend.
+
+If port 8080 is occupied, stop the previous Doc2FAQ process or use an alternate port:
+
+```cmd
+java -jar target/doc2faq-0.3.1.jar --server.port=8081
+```
+
+Then open **http://localhost:8081**. Merging source changes does not update an existing JAR or a running Java process; rebuild and restart to use the fixes. Published JARs must be built from the corresponding release commit.
+
 ## Using the app
 
 1. Paste your document's text or choose a `.txt`, `.md`, `.pdf`, or `.docx` file.
@@ -147,20 +175,20 @@ Example document for **Generate Mode**:
 
 ```markdown
 ## Services
-Website monitoring, routine software updates, and uptime reviews.
+The team provides onboarding guides and a shared knowledge base.
 
-## Payment Terms
-The client pays USD 1,200 within fifteen days of receiving an invoice.
+## Technical Skills
+Members share guides on document organization and clear technical writing.
 ```
 
 Example suggested output:
 
 ```markdown
 ## What services are included?
-Website monitoring, routine software updates, and uptime reviews.
+The team provides onboarding guides and a shared knowledge base.
 
-## When and how are payments due?
-The client pays USD 1,200 within fifteen days of receiving an invoice.
+## Which skills and technologies are listed?
+Members share guides on document organization and clear technical writing.
 ```
 
 Generate Mode preserves explicit FAQ pairs, then suggests questions for additional sections while filtering repeated common topics and boilerplate appendix headings. The answer text is sourced from the document. Generated question phrasing is heuristic; this is *not* legal advice or an automated contract interpretation service.
@@ -208,11 +236,11 @@ The `/api/faqs/preview` endpoint deliberately returns zero results if there are
 ## Tests
 
 ```bash
-mvn test
-mvn package
+mvn -B -ntp clean verify
+node --test src/test/js/*.test.cjs
 ```
 
-GitHub Actions automatically runs `mvn -B -ntp verify` on pushes and pull requests. Tests cover both modes, duplicate-topic filtering, FAQ appendix/title exclusions, natural question wording, document import errors, API validation, and output limits.
+GitHub Actions automatically runs the Java and JavaScript checks on pushes and pull requests. Tests cover both modes, whitespace-heavy parsing, stale responses and errors, distinct client/provider topics, FAQ appendix/title exclusions, document import errors, API validation, output limits, and export safety. The frontend tests require Node.js and have no npm dependencies.
 
 ## Troubleshooting
 

docs/RELEASING.md

@@ -1,38 +1,56 @@
 # Doc2FAQ release checklist
 
-This is the procedure for publishing **v0.3.0** from the protected `main` branch. Preparing a PR and changing the Maven version do **not** publish the release.
+This is the procedure for publishing **v0.3.1** from the protected `main` branch. Preparing a PR, merging fixes, and changing the Maven version do **not** replace an existing release JAR or publish a new GitHub Release.
 
 ## Before publishing
 
-1. Merge the version-finalization PR into `main` after the required `build-and-test` check passes.
-2. Verify the `main` branch has the release commit and the `pom.xml` version is exactly `0.3.0` (not `0.3.0-SNAPSHOT`).
-3. Run the GitHub Actions build or verify locally with Java 21 and Maven 3.6.3+:
-
+1. Merge the v0.3.1 release PR into `main` after the `build-and-test` check passes.
+2. Update a clean local checkout to the merged release commit:
+
+   ```cmd
+   git switch main
+   git pull --ff-only origin main
+   git status --short
+   git rev-parse HEAD
+   ```
+
+   Confirm `git status --short` is empty. Record the commit SHA; the release tag and attached JAR must correspond to this commit. Verify the project version in `pom.xml` is exactly `0.3.1` (not `0.3.1-SNAPSHOT`).
+3. Build and test with JDK 21, Maven 3.6.3+, and Node.js:
+
    ```cmd
-mvn -B -ntp clean verify
-```
+   mvn -B -ntp clean verify
+   node --test src/test/js/*.test.cjs
+   ```
+
+   Continue only when both checks pass. The runnable artifact is **`target/doc2faq-0.3.1.jar`**; do not upload the `.jar.original` file or rename an older JAR.
+4. Stop any previous Doc2FAQ instance, then smoke-test the actual packaged artifact:
+
+   ```cmd
+   java -jar target/doc2faq-0.3.1.jar
+   ```
+
+   Confirm the startup log identifies **v0.3.1**. Open `http://localhost:8080` and refresh the browser. If another application owns port 8080, use `--server.port=8081` and open `http://localhost:8081` instead. Keep this terminal open while testing; use **Ctrl+C** to stop the app.
 
-4. Open `http://localhost:8080` with `mvn spring-boot:run` and smoke-test:
-   - Extract Mode: the fictional maintenance agreement produces six explicit FAQ entries.
-   - Generate Mode: the same example produces nine source-grounded entries after duplicate and appendix filtering.
+   - Extract Mode: `Q: Does this run locally?` followed by `A: Yes, without an external AI service.` on the next line produces one FAQ.
+   - Generate Mode: separate `## Client Responsibilities` and `## Provider Responsibilities` sections, each with a source paragraph, produce separate client and provider FAQs.
    - Review: edit, reorder, remove, and add FAQ entries.
-   - Export: Markdown, JSON, and HTML downloads contain the expected questions and answers.
-5. Confirm the repository has no existing `v0.3.0` tag or Release. Do not replace an existing tag.
+   - Export: Markdown, JSON, and HTML downloads contain the expected edited questions and answers; HTML escapes document markup.
+5. Confirm the repository has no existing **v0.3.1** tag or Release. Keep the existing v0.3.0 tag, Release, and JAR unchanged.
 
 ## Publish using GitHub
 
 1. Open [Draft a new release](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases/new).
-2. Choose **Create new tag**, enter **`v0.3.0`**, and target the current **`main`** branch.
-3. Use release title: **Doc2FAQ v0.3.0 — Generate Mode, Review & Multi-Format Export**.
-4. Copy the **0.3.0** section of [CHANGELOG.md](../CHANGELOG.md) into the Release notes. Describe the deterministic nature of generation and limits honestly.
-5. Optionally attach the runnable `target/doc2faq-0.3.0.jar` built by Maven, after validating it starts with Java 21. GitHub automatically supplies source-code archives.
-6. Review all fields and select **Publish release**. This is the public publication step; do it only when ready.
+2. Choose **Create new tag**, enter **`v0.3.1`**, and target the recorded release commit SHA. If selecting `main`, verify its current SHA still matches the commit used to build the JAR.
+3. Use release title: **Doc2FAQ v0.3.1 — Parsing and Draft Reliability Fixes**.
+4. Copy the **0.3.1** section of [CHANGELOG.md](../CHANGELOG.md) into the Release notes. State that the fixes cover whitespace-heavy parsing, stale draft responses, and distinct client/provider responsibilities. Public-server hardening remains future work.
+5. Attach the tested **`target/doc2faq-0.3.1.jar`**. GitHub automatically supplies source-code archives; those archives do not replace the runnable JAR.
+6. Review the tag, commit, notes, and attached filename, then select **Publish release** when ready.
 
 ## Verify after publishing
 
-- Confirm [Releases](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases) includes **v0.3.0** and targets the exact release commit on `main`.
+- Confirm [Releases](https://github.com/OKAN-SOFTWARE/Doc2FAQ/releases) includes **v0.3.1**, its tag points to the recorded release commit, and the downloadable asset is **`doc2faq-0.3.1.jar`**.
 - Verify the GitHub Actions check for the tag, if triggered, completes successfully.
-- Download the source archive or JAR from the release page and confirm the version and local startup.
-- Leave any future PDF/DOCX output feature work for a separate branch and release.
+- Download the attached JAR to a separate folder, run it with Java 21, and confirm the startup version, health endpoint, and client/provider generation behavior.
+- Leave subscriptions, accounts, PDF/DOCX exports, and public-hosting hardening for separate changes.
 
 **License:** MIT · Copyright © 2026 Okan Tiktas.

pom.xml

@@ -11,7 +11,7 @@
     </parent>
     <groupId>com.okansoftware</groupId>
     <artifactId>doc2faq</artifactId>
-    <version>0.3.0</version>
+    <version>0.3.1</version>
     <name>Doc2FAQ</name>
     <description>Privacy-conscious document-to-FAQ preview workbench</description>
     <properties>

src/main/resources/static/app.js

@@ -16,19 +16,19 @@ const extractExample = [
   "A: No. Both modes use local, deterministic processing."
 ].join("\n");
 const generateExample = [
-  "# Website Maintenance Agreement",
+  "# Team Knowledge Guide",
   "",
   "## Services",
-  "The provider performs website monitoring, software updates, and uptime checks.",
+  "The team provides onboarding guides, project templates, and a shared knowledge base.",
   "",
-  "## Payment Terms",
-  "The client pays USD 1,200 per month within fifteen calendar days of invoicing.",
+  "## Team Responsibilities",
+  "Team members keep project notes current and review shared documents for clarity.",
   "",
-  "## Term",
-  "The agreement begins November 1, 2026, and lasts three months.",
+  "## Knowledge Sharing",
+  "Useful examples and project decisions are collected in the shared notes.",
   "",
-  "## Termination",
-  "Either party may terminate with fifteen calendar days of written notice."
+  "## Support",
+  "Ask questions in the team channel and include the steps needed to reproduce a problem."
 ].join("\n");
 
 const $ = (id) => document.getElementById(id);

src/main/resources/static/index.html

@@ -54,7 +54,7 @@ <h1 id="hero-title">Turn long documents into <em>clear answers.</em></h1>
             </select>
             <p id="mode-description" class="mode-description">Extract questions already written in the document.</p>
             <label for="source-text" class="field-label">DOCUMENT CONTENT</label>
-            <textarea id="source-text" maxlength="50000" spellcheck="false" placeholder="## Services&#10;Website monitoring and routine updates.&#10;&#10;## Payment Terms&#10;The fee is $120 per month."></textarea>
+            <textarea id="source-text" maxlength="50000" spellcheck="false" placeholder="Q: How can I organize my notes?&#10;A: Use clear headings and group related topics.&#10;&#10;Q: What makes a helpful answer?&#10;A: Keep it clear, concise, and based on the source."></textarea>
             <div class="input-meta"><span id="char-count">0 / 50,000 characters</span><span>UTF-8 text</span></div>
             <div class="actions">
               <button type="button" id="generate-btn" class="button button-primary">Extract FAQ draft <span aria-hidden="true">↗</span></button>