1 files changed, 122 insertions, 0 deletions
diff --git a/docs/USAGE.md b/docs/USAGE.md
new file mode 100644
index 0000000..df194b6
--- /dev/null
+++ b/docs/USAGE.md
@@ -0,0 +1,122 @@
+# PDF2TXT + Translator — How to use it
+
+This guide assumes you have never run a web page from a folder before. It takes about
+two minutes.
+
+## What this program is
+
+PDF2TXT reads the text inside a PDF and gives it to you as plain text you can copy or
+save. Everything happens inside your own browser: the PDF is not uploaded to us or to
+anyone else. There is no installation, no account and no internet connection needed for
+the text extraction itself.
+
+---
+
+## Step 1 — Start the app
+
+A browser will not load the PDF engine from a file you double-click, so start a tiny
+local web server first. You only do this once per session.
+
+**On Linux / macOS**
+
+1. Open a Terminal.
+2. Type these two lines, pressing Enter after each:
+
+```bash
+cd path/to/pdf2txt
+python3 -m http.server 8000
+```
+
+3. Leave that window open. It must stay running while you use the app.
+
+**On Windows**
+
+1. Install Python 3 from python.org if you do not have it (tick "Add Python to PATH").
+2. Open the folder `pdf2txt` in File Explorer.
+3. Click the address bar, type `cmd` and press Enter.
+4. Type `python -m http.server 8000` and press Enter.
+
+**Then**, in any browser, open:
+
+```
+http://localhost:8000/src/index.html
+```
+
+You will see a dark page titled **PDF2TXT + Translator** with a **Main** and a
+**Config** tab. If the page is blank or text extraction fails, you opened
+`src/index.html` by double-clicking instead of through `http://localhost:8000` — go back
+to Step 1.
+
+## Step 2 — Load your PDF
+
+- Drag the PDF from your file manager and drop it on the big dashed box, **or** click
+  the box and pick the file.
+- The app shows the file name, the number of pages and the file size.
+- Click **Load File**. A progress bar counts the pages while the text is extracted.
+- One file at a time. To start over, click **🗑️ New**.
+
+You can also skip the PDF entirely: paste text into **Or paste text directly** and click
+**Load Pasted Text**.
+
+## Step 3 — Check and edit the text
+
+The extracted text appears in the editor under **2. Edit & Select Parts**. You can type
+in it, fix line breaks, or delete pages you do not want. **Select All**, **Deselect All**
+and **⛶ Fullscreen** help with long documents.
+
+## Step 4 — Take the text out
+
+- **Download TXT** saves a file called `extracted.txt`.
+- **Copy All** copies everything to the clipboard so you can paste it into Word, Google
+  Docs, an email, and so on.
+
+Both buttons use whatever is currently in the editor — your edits included.
+
+## Step 5 (optional) — Translate
+
+Translation uses a language model that runs through **Ollama**, and it is entirely
+optional. Extraction, editing, copy and download work without it.
+
+1. Install Ollama from ollama.com.
+2. In a terminal run: `ollama pull translategemma:latest`
+3. Back in the app, open the **Config** tab and set **API Source** to
+   `Local (localhost:11434)`.
+4. Open the **Translate** section. Set **Translation Model** to
+   `translategemma:latest`.
+5. Choose your **Target** language from the 16 offered and press **🔄 Translate**.
+
+Things worth knowing before you translate:
+
+- The package ships with **API Source** set to `Proxied (/ollama)` and **Translation
+  Model** set to `glm-5.3-flash:cloud`. Both are cloud settings. For an offline run you
+  must change them as in steps 3 and 4.
+- Long documents are sent in 1,500-character pieces, one after another, so a big book
+  takes a while. Use the pause/stop buttons if needed.
+- The **Clean** and **Validate** steps also use a model (`llama3.2:latest` by default). If
+  you only want a translation, choose the workflow `Translate Only`.
+- Machine translation is a draft, not a certified translation. Check names, numbers and
+  legal wording yourself.
+
+## Limits you should know
+
+- **No OCR.** If the PDF is a scan (a photo of a page), there is no text inside it and
+  the result will be empty. This tool reads text layers only.
+- **No batch mode.** One document per run.
+- **No upload.** Because nothing leaves your computer, there is no cloud backup and no
+  sync between devices.
+- **Memory-bound.** Very large PDFs are limited by your browser's memory, not by an
+  artificial page cap.
+- **Layout is flattened.** Columns and tables come out as a stream of text and may need
+  tidying in the editor.
+
+## Your purchase and the download link
+
+The download link you received from the store is **permanent for that purchase**: you can
+open it again later to re-download the same package, with no expiry and no subscription.
+Keep the link (or the email containing it) somewhere safe, and keep your own copy of the
+`pdf2txt` folder as a backup — it is a plain folder of files, so copying it is enough.
+
+## Licence
+
+MIT © 2026 Akan Goksu Valdes. The PDF engine in `vendor/` is PDF.js, licensed under
+Apache-2.0. See `LICENSE` in the package folder.