docs: implement Kovina Repository Standard

.gitignore

@@ -42,3 +42,4 @@ OpenReader-Test-Cert.cer
 Thumbs.db
 .vscode/
 .idea/
+.wrangler

AGENTS.md

@@ -22,7 +22,7 @@ This repository is a local-first desktop PDF utility. Keep maintenance changes b
 - Tag releases with `vMAJOR.MINOR.PATCH`.
 - Packaged builds must inject the tag version into `main.py` via `scripts/inject_version.py`.
 - Source builds may remain `-dev`.
-- Update `RELEASE.md` if release mechanics change.
+- Update `docs/RELEASE.md` if release mechanics change.
 
 ## Build and Test
 

CLAUDE.md

@@ -62,7 +62,7 @@ python -m pytest tests/ -v
 - Tag releases with `vMAJOR.MINOR.PATCH`.
 - Version injected from tag via `scripts/inject_version.py`.
 - Source builds remain `-dev`.
-- Update `RELEASE.md` if release mechanics change.
+- Update `docs/RELEASE.md` if release mechanics change.
 
 ## Workflow
 
@@ -75,8 +75,8 @@ python -m pytest tests/ -v
 ## Documentation Rules
 
 - README should describe shipped behavior only.
-- ARCHITECTURE.md is the canonical architecture reference.
-- VERSIONING.md documents the versioning scheme.
+- docs/Architecture.md is the canonical architecture reference.
+- docs/VERSIONING.md documents the versioning scheme.
 - Keep CHANGELOG.md updated per Keep a Changelog format.
 - Keep Mac caveats visible for experimental platform status.
 

CONTRIBUTING.md

@@ -2,45 +2,6 @@
 
 Thanks for your interest in improving OpenReader.
 
-This project is free software. Contributions are accepted under the same [GNU AGPLv3](LICENSE) used by the project.
+This project is free software under the [GNU AGPLv3](LICENSE).
 
-## Local Setup
-
-```powershell
-python -m venv .venv
-.\.venv\Scripts\Activate.ps1
-python -m pip install -r requirements.txt
-python main.py
-```
-
-## Build on Windows
-
-```powershell
-.\scripts\build_windows.ps1
-```
-
-The executable is created at:
-
-```text
-dist\OpenReader.exe
-```
-
-## Build on macOS
-
-```bash
-chmod +x scripts/build_macos.sh
-./scripts/build_macos.sh
-```
-
-The app bundle is created at:
-
-```text
-dist/OpenReader.app
-```
-
-## Pull Requests
-
-- Keep the UI simple and native-looking.
-- Avoid network services; PDFs should stay local.
-- Test opening PDFs directly through command-line arguments.
-- Test search, text selection, merge, split, and compress behavior when changing document logic.
+For the full contributor guide — setup, workflow, PR process, and design playbooks — see [docs/Contributing.md](docs/Contributing.md).

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="assets/AppIcon.iconset/icon_256x256.png" alt="OpenReader" width="72">
+  <img src="assets/branding/AppIcon.iconset/icon_256x256.png" alt="OpenReader" width="72">
 </p>
 
 <h1 align="center" style="font-size: 2.75rem; font-weight: 700; letter-spacing: -0.02em; margin: 0.5rem 0 0.25rem;">
@@ -10,20 +10,24 @@
   Private PDF tools for your computer. No uploads. No accounts. No cloud.
 </p>
 
+<br>
+
 <p align="center">
-  <img src="assets/screenshots/reader-main.png" alt="OpenReader reading a PDF" width="880" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.15);">
+  <img src="assets/hero/reader-main.png" alt="OpenReader reading a PDF" width="880" style="border-radius: 12px; box-shadow: 0 8px 32px rgba(0,0,0,0.15);">
 </p>
 
 <p align="center" style="font-size: 0.95rem; color: #888; margin: 0.75rem 0 1.5rem;">
   Built for Windows 10 &amp; 11 · 100% Offline · Open Source · AI-ready
 </p>
 
+<br>
+
 <p align="center">
   <strong style="font-size: 1.15rem;">⭐ Get OpenReader</strong>
 </p>
 
 <p align="center">
-  <a href="https://apps.microsoft.com/detail/9MXDVW2645LL"><img alt="Microsoft Store" src="https://img.shields.io/badge/Microsoft%20Store%20(Recommended)-ff255f?style=for-the-badge&logo=microsoft&logoColor=white"></a>
+  <a href="https://apps.microsoft.com/detail/9MXDVW2645LL"><img alt="Microsoft Store (Recommended)" src="https://img.shields.io/badge/Microsoft%20Store%20(Recommended)-ff255f?style=for-the-badge&logo=microsoft&logoColor=white"></a>
   &nbsp;
   <a href="https://github.com/sparshsam/openreader/releases/latest"><img alt="Portable Release" src="https://img.shields.io/badge/Portable%20Release-1a1b26?style=for-the-badge&logo=github&logoColor=white"></a>
   &nbsp;
@@ -34,6 +38,18 @@
 
 ---
 
+## Gallery
+
+| Dark Mode | PDF Tools |
+|---|---|
+| ![Dark Mode](assets/screenshots/dark-mode.png) | ![PDF Tools: merge, split, compress](assets/screenshots/merge-split.png) |
+
+| About & Keyboard Shortcuts | Sample Document |
+|---|---|
+| ![About dialog with keyboard shortcuts](assets/screenshots/about.png) | ![Sample PDF loaded in OpenReader](assets/screenshots/sample-pdf.png) |
+
+---
+
 ## Why OpenReader
 
 | | |
@@ -49,24 +65,12 @@
 
 | | |
 |---|---|
-| **📖 Read** — Open PDFs, one-page or continuous scroll, fit-width zoom, page jump. | **📝 Annotate** — Highlight, underline, strikethrough, and sticky notes. Saved as native PDF annotations. |
-| **🔍 Search** — Full-document keyword search with match count and navigation. | **📚 Library search** — Index entire folders with SQLite FTS5 for cross-document BM25-ranked search. |
-| **🧠 Semantic search** — TF-IDF cosine similarity — meaning-based matching, no external ML. | **📊 Compare** — Side-by-side diff with color-coded changes and structured summary. |
-| **📑 Multi-tab** — Open several documents in one window with movable tabs. | **🌙 Dark mode** — System-aware theme with Auto/Light/Dark toggle. |
-| **🔧 PDF tools** — Merge, split, extract page ranges, compress. | **👁️ OCR fallback** — Automatic OCR on scanned/image-based pages when Tesseract is available. |
-| **💾 Session restore** — Remembers open documents and page positions across restarts. | **🤖 AI agent integration** — Built-in MCP server with 14 tools for automated PDF workflows. |
-
----
-
-## Screenshots
-
-| Dark Mode | PDF Tools |
-|---|---|
-| ![Dark Mode](assets/screenshots/dark-mode.png) | ![PDF Tools: merge, split, compress](assets/screenshots/merge-split.png) |
-
-| About & Keyboard Shortcuts | Sample Document |
-|---|---|
-| ![About dialog with keyboard shortcuts](assets/screenshots/about.png) | ![Sample PDF loaded in OpenReader](assets/screenshots/sample-pdf.png) |
+| <img src="assets/icons/feature-read.svg" width="28" height="28" alt=""> **Read** — Open PDFs, one-page or continuous scroll, fit-width zoom, page jump. | <img src="assets/icons/feature-annotate.svg" width="28" height="28" alt=""> **Annotate** — Highlight, underline, strikethrough, and sticky notes. Saved as native PDF annotations. |
+| <img src="assets/icons/feature-search.svg" width="28" height="28" alt=""> **Search** — Full-document keyword search with match count and navigation. | <img src="assets/icons/feature-session.svg" width="28" height="28" alt=""> **Library search** — Index entire folders with SQLite FTS5 for cross-document BM25-ranked search. |
+| <img src="assets/icons/feature-offline.svg" width="28" height="28" alt=""> **Semantic search** — TF-IDF cosine similarity — meaning-based matching, no external ML. | <img src="assets/icons/feature-compare.svg" width="28" height="28" alt=""> **Compare** — Side-by-side diff with color-coded changes and structured summary. |
+| <img src="assets/icons/feature-tabs.svg" width="28" height="28" alt=""> **Multi-tab** — Open several documents in one window with movable tabs. | <img src="assets/icons/feature-darkmode.svg" width="28" height="28" alt=""> **Dark mode** — System-aware theme with Auto/Light/Dark toggle. |
+| <img src="assets/icons/feature-tools.svg" width="28" height="28" alt=""> **PDF tools** — Merge, split, extract page ranges, compress. | <img src="assets/icons/feature-ocr.svg" width="28" height="28" alt=""> **OCR fallback** — Automatic OCR on scanned/image-based pages when Tesseract is available. |
+| <img src="assets/icons/feature-platform.svg" width="28" height="28" alt=""> **Session restore** — Remembers open documents and page positions across restarts. | <img src="assets/icons/feature-ai.svg" width="28" height="28" alt=""> **AI agent integration** — Built-in MCP server with 14 tools for automated PDF workflows. |
 
 ---
 
@@ -94,7 +98,16 @@ The focus is on reading and working with documents, not fighting the interface.
 
 ## Built With
 
-🐍 Python &nbsp;&nbsp;·&nbsp;&nbsp; 🪟 Qt 6 &nbsp;&nbsp;·&nbsp;&nbsp; 📄 MuPDF &nbsp;&nbsp;·&nbsp;&nbsp; 🔍 SQLite &nbsp;&nbsp;·&nbsp;&nbsp; 👁️ Tesseract &nbsp;&nbsp;·&nbsp;&nbsp; 🤖 MCP &nbsp;&nbsp;·&nbsp;&nbsp; 📦 PyInstaller &nbsp;&nbsp;·&nbsp;&nbsp; 🏪 MSIX
+<p align="center">
+  <img src="assets/icons/tech-python.svg" width="40" height="40" alt="Python">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-qt.svg" width="40" height="40" alt="Qt 6">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-mupdf.svg" width="40" height="40" alt="MuPDF">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-sqlite.svg" width="40" height="40" alt="SQLite">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-tesseract.svg" width="40" height="40" alt="Tesseract">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-mcp.svg" width="40" height="40" alt="MCP">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-pyinstaller.svg" width="40" height="40" alt="PyInstaller">&nbsp;&nbsp;&nbsp;&nbsp;
+  <img src="assets/icons/tech-msix.svg" width="40" height="40" alt="MSIX">
+</p>
 
 ---
 
@@ -132,4 +145,22 @@ Copyright &copy; 2026 Sparsh Sam.
 
 ---
 
+## Part of the Open Collection
+
+Open\* is a family of privacy-first, open-source applications. Every app is local-first, respects your data, and is built with care.
+
+| | App | Description | Links |
+|---|---|---|---|
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenReader** | Private PDF tools for your computer. | [Repo](https://github.com/sparshsam/openreader) · [Web](https://reader.kovina.org) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenLedger** | Local-first personal finance ledger. No noise. | [Repo](https://github.com/sparshsam/openledger) · [Web](https://ledger.kovina.org) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenProof** | Privacy-first proof-of-existence for files, onchain. | [Repo](https://github.com/sparshsam/openproof) · [Web](https://proof.kovina.org) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenSend** | Free, ad-free, open-source file sharing between devices. | [Repo](https://github.com/sparshsam/opensend) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenSnap** | Minimal always-on-top screenshot widget for Windows. | [Repo](https://github.com/sparshsam/opensnap) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenJournal** | Privacy-first local activity journal for Windows. | [Repo](https://github.com/sparshsam/openjournal) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenPalette** | Local-first color studio — harmonies, tokens, accessibility. | [Repo](https://github.com/sparshsam/openpalette) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenScrabble** | Multiplayer Scrabble with chat and shared boards. | [Repo](https://github.com/sparshsam/openscrabble) |
+| <img src="assets/icons/openreader.svg" width="28" height="28" alt=""> | **OpenSprout** | Privacy-minded plant care dashboard and watering logs. | [Repo](https://github.com/sparshsam/opensprout) |
+
+---
+
 *Last updated: June 2026*