From 186943c8abe8be7ba8270013f8e76696db4f8728 Mon Sep 17 00:00:00 2001
From: blankie <blankie@tuta.com>
Date: Thu, 2 Jul 2026 23:54:07 +0000
Subject: [PATCH] docs(contributing): expand with setup, conventions, and PR
 guidelines

---
 CONTRIBUTING.md | 75 +++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 73 insertions(+), 2 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6807493..f096cb4 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,3 +1,74 @@
-This is a one-person project maintained in spare time. Bug reports and patches are welcome, but there are no guarantees around response time, acceptance, or ongoing support.
+# Contributing to TinyWeb
 
-Code was generated by LLMs. If you submit a PR, assume I'll review it the same way — I'll look for whether it works and whether it fits, not whether it's idiomatic or perfectly styled.
+Thanks for helping. TinyWeb is a decentralized search engine built for the
+Reticulum mesh. Contributions that respect its architecture and constraints
+are welcome.
+
+## Before you start
+
+- Open an issue first for anything beyond a small bug fix to discuss the approach.
+- One change per pull request. Keep it focused and reviewable.
+- TinyWeb has no authentication by design — PRs adding login or user accounts
+  are outside scope unless the architecture changes.
+
+## Setup
+
+```bash
+pip install -r requirements.txt
+python app.py
+```
+
+Open `http://127.0.0.1:8080`. Run with `--bind 0.0.0.0` for LAN access
+(see [SECURITY.md](SECURITY.md) about the risks of exposing an unauthenticated app).
+
+## Running checks
+
+Run the test suite before submitting:
+
+```bash
+python -m pytest
+```
+
+## What fits TinyWeb
+
+- Bug fixes, performance improvements, and mesh reliability work
+- New handlers or integrations that respect the no-JS, no-CSS-framework constraint
+- Documentation and test coverage
+- Edge case handling and error recovery
+
+## What doesn't fit
+
+- Authentication, user accounts, or session systems (by design)
+- JavaScript or CSS frameworks (Tailwind, Bootstrap, React, etc.)
+- Dependencies that assume internet connectivity or cloud infrastructure
+- Database backends other than SQLite
+- Features that break local-first or mesh-native operation
+
+## Pull requests
+
+- Target `main`.
+- Describe what changed and why.
+- Include test output or manual test steps.
+- Screenshots for anything visual.
+- Use [Conventional Commits](https://www.conventionalcommits.org):
+  `fix(search): ...`, `feat(rns): ...`, `docs(readme): ...`
+
+LLM-generated PRs should be preceded by an issue. Unannounced bulk PRs may
+be closed without review.
+
+## Code conventions
+
+- No inline `style=""` except for functional margins/padding/alignment
+- No JavaScript or CSS frameworks
+- No Unicode emoji in UI — use HTML entities or plain text
+- No hardcoded paths — use `DATA_DIR` or `TINYWEB_DATA_DIR` env var
+- No hardcoded domains, IPs, or destination hashes
+
+## Issue reports
+
+Include: install method, OS, steps to reproduce, expected vs actual.
+For mesh issues: interface type, RNS destination hash if relevant.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Report privately — don't post exploits in issues.