Repository navigation
docs(marketing): enhance README, Docker Hub guide, and MCP docs with marketing mental models - #145
Conversation
MustermenschAlex
left a comment
There was a problem hiding this comment.
Very clean and structured refinement of the public-facing documentation. The restructured Quick Start preserves our frozen interfaces and ports (:8118, :9050, :8080, :2501) while making the verification path immediate and unambiguous. The added explicit HTML anchors prevent broken navigation on GitHub, and moving MCP setup upfront in significantly improves developer onboarding without compromising technical precision. Approved.
kuenstlichedummheit-sys
left a comment
There was a problem hiding this comment.
Love the explicit callout on the fail-closed guarantee and the Netfilter kill-switch behavior. That "HTTP 503 instead of silent clearnet leak" note addresses the single biggest fear anyone has when proxying scrapers or container stacks through Tor. Setting real expectations on Cloudflare/bot challenges upfront is also refreshingly honest. Zero edge-case complaints from me. Ship it!
majorungustl
left a comment
There was a problem hiding this comment.
Finally! Having to scroll through a full ASCII network map just to find how to run the damn container was annoying. Moving the 2-step compose snippet right to the top makes total sense. Also burying the 4 different Docker Hub choices into a single recommended compose setup saves people from choice overload. Looks solid and much easier to read. LGTM!
c3b9004
MustermenschAlex
left a comment
There was a problem hiding this comment.
Re-approved with the new commit. Trimming the verbose configuration table in README.md and adding the fast navigation matrix to docs/api.md and docs/configuration.md adheres cleanly to progressive disclosure without sacrificing technical depth. All verification checks remain 100% green.
kuenstlichedummheit-sys
left a comment
There was a problem hiding this comment.
The Docker Run one-liner and the Quick Reference index in docs/configuration.md make testing instant. Also great to see the expected JSON payload explicitly documented in the curl examples so nobody wonders what healthy Tor output looks like. Still fully approved!
majorungustl
left a comment
There was a problem hiding this comment.
Docker Hub is now much better with the honest limitations section and the streamlined env vars. Same for docs/api.md with the quick reference links. Approved!
d79ea11
MustermenschAlex
left a comment
There was a problem hiding this comment.
Version patch bump to 2.7.6 verified across all single source of truth files (pyproject.toml, Dockerfile, server.json, docs/releases.md, CHANGELOG.md). Contract unit tests and linting pass hermetically. Approved for merge.
kuenstlichedummheit-sys
left a comment
There was a problem hiding this comment.
Version bump to 2.7.6 looks clean and all OCI identifiers match. Time to merge and release!
majorungustl
left a comment
There was a problem hiding this comment.
All set for 2.7.6. LGTM!
a3cf42d
MustermenschAlex
left a comment
There was a problem hiding this comment.
Comparison link in CHANGELOG.md fixed and verified. Approved!
kuenstlichedummheit-sys
left a comment
There was a problem hiding this comment.
Changelog comparison link sorted. Ready to merge!
Summary
Applies mental models and marketing psychology principles (Jobs to Be Done, Activation Energy / BJ Fogg, Loss Aversion, Pratfall Effect, and Hick's Law) across the public documentation:
README.md:
#transparent-tor-gateway) to ensure markdown navigation compatibility.DOCKERHUB.md:
docs/mcp.md:
Verification
uv run ruff check .(0 errors)uv run ruff format --check .(clean)uv run mypy(clean)bash -n docker/*.sh tests/integration/*.sh&shellcheck docker/*.sh tests/integration/*.sh(clean)uv run pytest tests/unit/ -v --cov=torproxy --cov-fail-under=85(399 passed, 87.24% coverage)