From bddfb70fc0651f2be04a8b1a24db13649686dee2 Mon Sep 17 00:00:00 2001
From: blankie <blankie@tuta.com>
Date: Tue, 9 Jun 2026 03:06:38 +0000
Subject: [PATCH] README: add transparency sections, TOC, update project
 structure

---
 README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 64 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 90c10c8..eca20ee 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,27 @@
 
 A personal, decentralized search engine built on the [Reticulum](https://reticulum.network/) mesh network. You save pages you find. They are stored locally and shared over a mesh network so other people can find them too.
 
+## Contents
+
+- [About this project](#about-this-project)
+- [Features](#features)
+- [Performance & Scale](#performance--scale)
+- [Docker](#docker)
+- [Data storage](#data-storage)
+- [Getting started](#getting-started)
+- [Remote gateway](#remote-gateway)
+- [How it works](#how-it-works)
+- [Known rough edges](#known-rough-edges)
+- [Forum plugin](#forum-plugin)
+- [Project structure](#project-structure)
+- [Security](#security)
+- [Maintenance](#maintenance)
+- [Dependencies](#dependencies)
+
+## About this project
+
+Code generated by LLMs. Built by one person.
+
 ## Features
 
 - **Personal search index** — Save pages you find valuable, search them with full-text search (SQLite FTS5)
@@ -13,6 +34,19 @@ A personal, decentralized search engine built on the [Reticulum](https://reticul
 - **Mesh-native** — Works over Reticulum without the internet; encrypted and decentralized by default
 - **Forum plugin** — Optional link-sharing discussion board over the mesh (see Forum section below)
 
+### What sharing means
+
+Once a subscriber syncs your pages, you have no control over their copy.
+No revocation, no DRM, no expiry. If you shared a page, assume it's out
+there permanently.
+
+Tag-based sharing (`private`, `public`) is advisory. The software
+respects these tags in its API response, but there is no technical
+mechanism preventing a subscriber from re-sharing your data.
+
+Deletion is local only. Removing a page from your index does not
+propagate to subscribers.
+
 ## Performance & Scale
 
 ### Search Speed
@@ -166,6 +200,18 @@ This connects over Reticulum and serves the remote instance at `http://localhost
 3. **Subscribe** — Add a friend's destination hash on `/subscriptions` to sync their shared index
 4. **Customize** — Edit your site name, HTML template, and sharing settings on `/style`
 
+## Known rough edges
+
+- Single-user UI
+- All-or-nothing sharing per mode
+- Manual sync (except optional forum auto-sync)
+- No recrawling
+- No browser extension — bookmarklet only
+- Desktop-oriented
+- JSON-only import
+- Forum threads prune after 30 days by default
+- Best-effort maintenance
+
 ## Forum plugin
 
 TinyWeb ships with an optional [tinyweb-forum](https://codeberg.org/tinyweb/tinyweb-forum) plugin — a decentralized link-sharing discussion board that runs in-process alongside TinyWeb.
@@ -196,7 +242,15 @@ For full feature docs, see the [tinyweb-forum README](https://codeberg.org/tinyw
 ```
 app.py          — Entry point: boots Reticulum, starts HTTP gateway
 gateway.py      — HTTP-to-RNS bridge (local or remote dispatch)
-handlers.py     — Route dispatcher and all request handlers
+handlers/       — Route dispatcher and request handlers
+  __init__.py   — Dispatch logic + re-exports
+  _helpers.py   — CSRF, FTS sanitizer, pagination, response builders
+  search.py     — Search (BM25, hybrid, trusted/remote results)
+  pages.py      — Add/edit/delete/bulk/bookmark handlers
+  subscriptions.py — Sync, sharing, API, subscription CRUD
+  customize.py  — Settings form, about page
+  tags.py       — Tag list and browse
+  data.py       — Export, import, semantic reindex
 db.py           — SQLite database, FTS5, URL fetching, SSRF protection
 templates.py    — HTML template rendering and escaping
 rns_client.py   — Reticulum client for fetching remote site lists
@@ -218,6 +272,15 @@ Other hardening measures:
 - **Identity file protection** — The Reticulum identity key is restricted to owner-only permissions (0600)
 - **Forum caveats** — See [tinyweb-forum Security](https://codeberg.org/tinyweb/tinyweb-forum#security) for forum-specific risks (voluntary retractions, block gossip manipulation, no rate limiting)
 
+#### Not hardened
+
+- No HTTPS
+- No authentication
+- No encryption-at-rest
+- No rate limiting
+- Bookmarklet token sent as a plain URL parameter
+- Forum moderation is gossip-based — block lists can be manipulated
+
 ## Maintenance
 
 ### Database Vacuum