# Musebook / Spider CLAWD companion

Spider CLAWD walks between the posts visible in your X tab, frames the post it
is investigating and sends a small capture to your local research engine.
Musebook's [/crawler](https://musebook.trade/crawler) pairs with that engine to
show the real findings, sources, runs and activity.

The complete Gem Search research engine is adapted here: durable extension
capture, JEV topic/ticker/contract/phrase detection, author diversity and signal
velocity, bounded public-page crawling, four local rule checks and four optional
Grok reviewers: Lookout, Maker, Skeptic and Runner. All local storage remains on
your computer; Grok receives evidence excerpts only when you enable it locally.

## Connect your feed

Python **3.11+** on macOS, Linux or Windows through WSL2, and Chrome/Chromium are
enough for research. No Python packages,
wallet or npm install are required. The extension includes the shared Spider
CLAWD character bundle; WebGL uses Three.js and falls back to the JavaScript
character when WebGL is unavailable.

1. Unzip the companion download and open a terminal in `spider-clawd-companion/`.
2. Run `python3 app.py` and open **http://127.0.0.1:8787**.
3. Choose **Connections** and **Copy pairing code**.
4. Open `chrome://extensions`, turn on **Developer mode**, choose **Load unpacked**
   and select the companion's `extension/` folder. Alternatively unzip the
   extension download and load that folder.
5. Open the Spider CLAWD extension popup and paste the pairing code. On X, click
   **Release Spider CLAWD on this tab**. Optional auto-scroll works only while
   the tab is visible. Pause and dismiss remain available in its overlay.
6. Open **https://musebook.trade/crawler**, choose **Connect your feed**, paste the
   same pairing code and click **Connect companion**. If Chrome asks, allow Musebook to access your
   local network. Findings appear after the research engine's next pass, normally
   within ten seconds; pause changes reach an open extension within a minute.

The engine binds only to `127.0.0.1`; it does not become a public hosted service.
Pairing authorizes your Musebook browser page to read and control this local
research process. The page keeps its pairing code only in this tab's memory;
disconnecting clears it and reloading requires pairing again. The extension
stores its separate copy in trusted extension storage until you disconnect it.

## Grok and inputs

Copy `.env.example` to `.env` locally, set `XAI_API_KEY`, `GROK_ENABLED=1` and your
desired `GROK_MODEL`, then restart Python. The supplied default is `grok-4.7`.
The default allowance is **12 requests per rolling 24 hours**; one four-seat
review uses four requests, including failed calls. API keys are never returned
by the pairing bridge. Local rules work without a key, and unavailable or
disabled model reviews are shown explicitly.

The hosted [CLAWD Brain](docs/CLAWD_BRAIN.md) remembers real research and conversations through server-side Mem0. Review the [cloud capture controls](docs/PRIVACY.md) before pairing private sources.

Musebook's hosted market enrichment and OpenMarket charts use Musebook's own
server configuration. You do not need an OpenMarket key for the companion or
its browser pairing. Your optional local xAI key enables only the companion's
Grok reviewers.

Import research JSON using the shape in [docs/DATA_FORMAT.md](docs/DATA_FORMAT.md).
`python3 app.py --autopilot` also watches `data/inbox/` and the optional free
Hacker News feed. Copy `topics.example.json` to `topics.json` to define your own
topics. The bridge accepts its own research exports by revalidating their source
captures; it never trusts imported verdicts or model votes.

For a fictional walkthrough, open **http://127.0.0.1:8787/spider-demo** or run
`python3 scripts/spider_demo.py`. Samples remain marked as synthetic. The X
extension uses posts rendered in your active tab rather than a paid X firehose.

## Launch handoff

Musebook pairing creates a concept draft and opens **Musebook /launchpad** with
`source=spider-clawd`. The form receives the proposed name, symbol and description
for your review. It
cannot call the local financial APIs, access wallets or dispatch transactions.
The complete original launch module is retained for explicit local developer
use, disabled at startup unless **`--allow-launch`** is supplied. Environment
variables alone do not enable dispatch. Read [SETUP.md](SETUP.md) and
[docs/AUTOLAUNCH.md](docs/AUTOLAUNCH.md) before opting in; research started through
the hosted import, demo, refresh and autopilot endpoints never enters that queue.

## Verify and package

```sh
python3 -m unittest discover -s tests
python3 tests/http_extension_smoke.py
npm ci --ignore-scripts
npm test
python3 scripts/package_extension.py
```

The Musebook repository also includes
`cloudflare/scripts/package-spider-clawd.py`, which deterministically packages
both downloads using an explicit source whitelist. Neither download contains
`.env`, local databases, captures, wallets, keys or `node_modules`.

## Attribution

Adapted from [Gem Search](https://github.com/h100envy/gem-search). Copyright
**(c) 2026 Gem Search contributors**, MIT; the original license is included
unchanged in [LICENSE](LICENSE) and both downloads. Internal protocol/module
names remain compatible with the original engine. [UPSTREAM.md](UPSTREAM.md)
records the adaptation. The shared Musebook character uses Three.js, with its
MIT notice included in the character distribution.

See [the paired research API](docs/BRIDGE.md) for the browser connection boundary
and [privacy](docs/PRIVACY.md) for local storage, page memory and exports.