Skip to content

docs(marketing): enhance README, Docker Hub guide, and MCP docs with marketing mental models - #145

Merged
hapheus merged 4 commits into
mainfrom
docs/marketing-psychology-enhancements
Nov 12, 2026
Merged

hapheus merged 4 commits into
mainfrom
docs/marketing-psychology-enhancements

Conversation

@hapheus

@hapheus hapheus commented Nov 12, 2026

Copy link
Copy Markdown
Owner

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:

    • Reformulates hero value proposition around tangible customer outcomes (Zero Clearnet Leaks, Transparent Gateway, Native AI Agent MCP, Dynamic Circuit Control).
    • Streamlines Quick Start into a 2-step aha-moment (Start & Verify) to drastically reduce initial activation energy, moving advanced identity/country controls into an expandable section.
    • Adds a prominent Leak-Proof Guarantee (Fail-Closed) callout addressing deep user loss aversion regarding clearnet IP leaks.
    • Introduces an honest When to Use torproxy (and when not to) section leveraging the Pratfall Effect to set clear expectations and elevate credibility.
    • Moves the architecture diagram directly behind the quickstart and use cases.
    • Adds explicit HTML anchors (#transparent-tor-gateway) to ensure markdown navigation compatibility.
  • DOCKERHUB.md:

    • Resolves choice overload (Hick's Law) by consolidating startup methods into a clear recommended path (Docker Compose) followed by dedicated mode showcases.
    • Promotes native Model Context Protocol (MCP) support for Claude Desktop and Cursor.
    • Adds trust and verification badges (Non-Root, Fail-Closed, OpenSSF Best Practices).
    • Adds the Fail-Closed Leak-Proof guarantee.
  • docs/mcp.md:

    • Moves immediate copy-paste Quickstart examples (Claude Desktop, Cursor, Antigravity, Smithery) to Section 1 before architectural/dual-transport deep-dives to minimize time-to-value for AI developers.

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)

@MustermenschAlex MustermenschAlex left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 kuenstlichedummheit-sys left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
majorungustl previously approved these changes Nov 12, 2026

@majorungustl majorungustl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

@MustermenschAlex MustermenschAlex left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 kuenstlichedummheit-sys left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
majorungustl previously approved these changes Nov 12, 2026

@majorungustl majorungustl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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!

@MustermenschAlex MustermenschAlex left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 kuenstlichedummheit-sys left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Version bump to 2.7.6 looks clean and all OCI identifiers match. Time to merge and release!

majorungustl
majorungustl previously approved these changes Nov 12, 2026

@majorungustl majorungustl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All set for 2.7.6. LGTM!

@MustermenschAlex MustermenschAlex left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Comparison link in CHANGELOG.md fixed and verified. Approved!

@kuenstlichedummheit-sys kuenstlichedummheit-sys left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changelog comparison link sorted. Ready to merge!

@majorungustl majorungustl left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM!

@hapheus
hapheus merged commit 1a99efe into main Nov 12, 2026
12 checks passed
@hapheus
hapheus deleted the docs/marketing-psychology-enhancements branch November 12, 2026 14:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants