v0.7: one-click install — pyproject, console scripts, user units, hermes wiring

A clone + ./install.sh + ./launch-brave.sh + sign in once. Nothing else.

pyproject.toml declares the one real dependency (websockets) and maps the
repo-root-is-the-package layout, which retires the PYTHONPATH=<parent> line
every unit used to carry.

cli.py backs three console scripts. They exist because `python3 -m socialmag`
run from INSIDE a clone dies at `import asyncio`: the repo root is the package
dir, so it ships selectors.py and queue.py, and python puts the current
directory first on sys.path. `cd socialmag` is the first thing anyone does
after a clone, so the documented workaround failed at exactly the moment it
would be tried. A generated bin/ script never puts cwd on sys.path.

The same trap bit `python3 -m venv` inside install.sh — the installer was
broken by the thing it exists to fix. Every python3 call now runs from /.

deploy/user/*.in replaces root system units with systemd --user templates:
no User=, WantedBy=default.target, venv paths, @REPO@/@VENV@/@CDP_ENDPOINT@
substituted at install time. deploy/home/ is untouched and still live here.

launch-brave.sh carries --disable-background-timer-throttling. That is
load-bearing, not tidiness: five of six platforms are read in a hidden tab, and
a throttled background tab stops running the timers those pages use to fetch
their own data — the reads come back empty with no error.

install.sh checks the mcp package in hermes's own interpreter and refuses to
continue without it. Hermes treats mcp as optional and silently no-ops the
whole subsystem when it is missing, so a server that never loaded looks exactly
like one that loaded and did nothing.

It will not merge into an existing mcp_servers: key — it backs up config.yaml
and appends only when the key is absent, otherwise it prints the block. Blind
YAML merging is how someone's other servers disappear.

Verified end-to-end in a sandbox with a fake HOME and stubbed systemctl:
real MCP initialize handshake from inside the repo dir returns all 7 tools;
hermes's own yaml parser re-reads the written config with every pre-existing
key intact; a second run leaves the mcp_servers key count at 1; launch-brave.sh
exits 1 against a busy port; no unsubstituted @PLACEHOLDER@ in any rendered unit.

Not fixed, pre-existing: server.py reports SERVER_VERSION 0.1.0 while the repo
is at v0.7. The handshake shows 0.1.0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

README.md

@@ -4,17 +4,57 @@ MCP server that posts, reads, and replies across 6 platforms — Threads, Facebo
 Instagram, YouTube, TikTok, and Twitter/X — by driving abang's already-logged-in
 Brave over CDP. No API keys, no OAuth.
 
+## Install
+
+```bash
+git clone https://github.com/juxtapo9090/socialmag.git
+cd socialmag
+./install.sh
+```
+
+That builds a venv, installs the package, writes four systemd **user** units,
+and registers socialmag with Hermes as an MCP server. Then, once:
+
+```bash
+./launch-brave.sh      # opens Brave on the debugging port, own profile
+```
+
+Sign in to your platforms in that window. socialmag stores no passwords — it
+drives the session that now belongs to that browser profile, which is why this
+step is yours and cannot be scripted.
+
+Afterwards: dashboard at `http://127.0.0.1:8321/dashboard.html`, a refresh pass
+every 30 minutes, and `socialmag` / `socialmag-refresh` / `socialmag-openbridge`
+on the venv's `PATH`.
+
+⚠️ **Hermes treats the `mcp` Python package as optional.** Without it, every
+`mcp_servers` entry is ignored — no error, one debug log line. `install.sh`
+checks for it in Hermes's own interpreter and refuses to continue rather than
+leave you with a server that looks registered and never loads.
+
+⚠️ **`install.sh` will not merge into an existing `mcp_servers:` key.** It backs
+up `config.yaml` and appends only when the key is absent; otherwise it prints the
+block for you to paste. Blind YAML merging is how someone's other servers vanish.
+
+⚠️ **User units stop at logout** unless `sudo loginctl enable-linger $USER`.
+The installer says so when linger is off.
+
 ## Run
 
 ```bash
-cd /mnt/playground/Playground_V2
-python3 -m socialmag            # stdio MCP server, logs to stderr
+socialmag              # stdio MCP server, logs to stderr
 ```
 
-⚠️ **Must run as a package.** `python3 socialmag/server.py` puts the package
-dir first on `sys.path`, where `selectors.py` and `queue.py` shadow the stdlib
-modules `asyncio` imports — asyncio then dies at import with
-`module 'selectors' has no attribute 'SelectSelector'`. Run `-m`.
+⚠️ **Use the console script, not `python3 -m socialmag`, from inside the repo.**
+The repo root is the package dir, so it ships `selectors.py` and `queue.py` —
+names the stdlib also uses. Python puts the current directory first on
+`sys.path`, so from inside a clone, asyncio's own `import selectors` finds ours
+and dies with `module 'selectors' has no attribute 'SelectSelector'`. The
+generated `bin/socialmag` never puts the current directory on `sys.path`, so it
+works from anywhere. `-m` still works from outside the repo.
+
+The same trap bites `python3 -m venv` during install, which is why `install.sh`
+runs every `python3` from `/`.
 
 Brave must be listening on `http://127.0.0.1:9336` (`cdp.py:29`,
 `DEFAULT_HTTP_ENDPOINT`). Override with `SOCIALMAG_CDP_ENDPOINT`.
@@ -25,7 +65,7 @@ for this server, but no code looks at it — grep says the only env var consulte
 the default endpoint is already `:9336`. Change the port there and nothing happens,
 silently. Fix the name in the config, or teach `server.py` to read the port.
 
-Requires `websockets` (17.1 present on this box). Everything else is stdlib.
+Requires `websockets`. Everything else is stdlib.
 
 ## Tools