# Set up LLMQuant Data on Hermes

You are reading this because a Hermes user asked you to connect LLMQuant Data.
This document is written for the installing agent. A human can follow it too,
but the first reader is the agent doing the setup.

Work top to bottom. Stop and ask the user only where a step says you need
human input.

## Trust contract

These are hard constraints.

1. **Do not take over Hermes.** Only change the `llmquant-data` entry inside
   `~/.hermes/config.yaml`, the selected LLMQuant skills, the copied LLMQuant
   persona/template files, and cron jobs the user approves.
2. **Prefer the hosted Remote MCP URL.** Use stdio only when the user asks for
   a local Node.js process.
3. **Back up before editing config.** Copy `~/.hermes/config.yaml` to a
   timestamped backup before writing it.
4. **Show the diff before writing.** Mask API keys and URL tokens in the diff.
5. **Never echo secrets.** Do not print the user's API key or Remote MCP URL in
   chat, logs, shell history, or any file except `config.yaml`.
6. **Do not change the user's model without consent.** DeepSeek is the
   recommended baseline, but model credentials and provider choice belong to
   the user.

If a step would break one of these rules, stop and tell the user.

## Step 0 - Check this Hermes instance

Run:

```bash
hermes --version
hermes model --help
hermes skills tap --help
hermes skills --help
hermes cron --help
hermes mcp --help
```

Confirm:

- Hermes is installed and on PATH.
- `hermes model` exists. Hermes docs use it as the provider/model setup flow.
- `hermes skills tap add` exists.
- `hermes cron` shows list/create/pause/resume commands.
- `hermes mcp --help` does not tempt you into using `hermes mcp add --env`.
  That path was buggy on some Hermes versions (observed on v0.18.x).

Carry these operational notes forward:

- Cron expressions run in the host machine's local time on some Hermes
  versions (as of v0.18.x). Still confirm next-run time after scheduling.
- `every 3d` parsed on some Hermes versions (as of v0.18.x).
- `hermes skills tap add` may only register a source. It may not install the
  skills. You must verify with `hermes skills list`.

Report the version and anything surprising to the user in one short message.

## Step 1 - Confirm the model baseline

These playbooks are written for a cost-conscious **DeepSeek** baseline.

Check the current model:

```bash
hermes config get model --json
hermes status
```

If Hermes already uses DeepSeek, continue.

If not, ask:

> These playbooks are tuned for DeepSeek as the baseline model. Do you want me
> to leave your current Hermes model unchanged, or do you want to switch Hermes
> to DeepSeek first? If you want to switch, please run `hermes model` and choose
> a DeepSeek model, or let me guide you through it.

Do not enter or request a DeepSeek API key unless the user explicitly asks you
to help with model setup. The LLMQuant Data key in Step 2 is a separate secret.

## Step 2 - Get LLMQuant credentials from the user

This step needs a human.

Ask the user:

> Please go to https://llmquantdata.com and sign in. For Hermes, the easiest
> path is Dashboard -> Connect -> Remote MCP URL. Paste that URL here. If you
> prefer a local stdio process, paste an API key from Dashboard -> API Keys
> instead. I will not echo it back.

Use exactly one:

- Remote MCP URL, shaped like `https://mcp.llmquantdata.com/u/<token>/mcp`;
- API key, for stdio fallback.

If the user gives both, ask which one to use. If the value looks malformed,
ask them to copy it again.

## Step 3 - Write the MCP config

Back up:

```bash
cp ~/.hermes/config.yaml ~/.hermes/config.yaml.bak.$(date +%Y%m%d-%H%M%S)
```

If `~/.hermes/config.yaml` does not exist, create it with a top-level
`mcp_servers:` block.

Update exactly one `llmquant-data` entry. Do not append duplicate YAML keys.

### Remote form, recommended

```yaml
mcp_servers:
  llmquant-data:
    url: "https://mcp.llmquantdata.com/u/<token>/mcp"
```

### stdio form, fallback

```yaml
mcp_servers:
  llmquant-data:
    command: "npx"
    args: ["-y", "@llmquant/data-mcp"]
    env:
      LLMQUANT_API_KEY: "<the key the user gave you>"
```

Show the masked diff and ask for approval. Then write the file.

Reload MCP in Hermes, or restart Hermes.

Verify:

- `config.yaml` parses as YAML;
- there is exactly one `llmquant-data` entry;
- Hermes reloads without an MCP error.

## Step 4 - Smoke-test for 0 credits

Call `personal_profile`.

Outcomes:

- Clean response, including an empty profile: auth works.
- Unauthorized: the URL or API key is wrong. Redo Step 2 and Step 3.
- Tool missing: MCP reload or skill/tool discovery failed. Recheck Step 3.

Read `meta.remainingCredits` and tell the user:

> Connected. You have <remainingCredits> LLMQuant credits left. Keep runs lean:
> keeping a small watchlist and skipping optional deep dives keeps credit use
> low.

Do not schedule anything until this smoke test passes.

## Step 5 - Install the skills and persona

Tap both skill sources — this repo's playbooks and the LLMQuant analysis
skills — then verify:

```bash
hermes skills tap add LLMQuant/llmquant-hermes
hermes skills tap add LLMQuant/skills
hermes skills list
```

From this repo you should see `llmquant-setup`, `morning-brief`,
`earnings-watch`, `13f-diff`, `portfolio-pulse`, and `polymarket-watch`,
plus the analysis skills from `LLMQuant/skills`.

Tap may register a source without installing it on some Hermes versions. If
skills are missing from the list, install them through this Hermes version's
skill flow, or clone each repo and copy its `skills/` into `~/.hermes/skills/`:

```bash
mkdir -p ~/.hermes/skills ~/.hermes/repos
for repo in LLMQuant/llmquant-hermes LLMQuant/skills; do
  dir=~/.hermes/repos/$(basename "$repo")
  [ -d "$dir" ] || git clone https://github.com/$repo "$dir"
  cp -R "$dir"/skills/* ~/.hermes/skills/
done
```

Then install the persona and workspace template (ask first). Make sure this
repo is on disk, then copy:

```bash
dir=~/.hermes/repos/llmquant-hermes
[ -d "$dir" ] || git clone https://github.com/LLMQuant/llmquant-hermes "$dir"
cp "$dir"/templates/SOUL.md ~/.hermes/SOUL.md
```

Copy `~/.hermes/repos/llmquant-hermes/templates/AGENTS.md` into the Hermes
workdir that will own the market jobs. Ask the user to edit:

- `watchlist.tickers`
- `watchlist.macro_indicators`
- `watchlist.13f_managers`
- `watchlist.prediction_market_topics`
- `delivery.default`
- `model.baseline`

## Step 6 - Show value now

Do not jump to cron. Cron is an advanced, always-on feature the user cannot see
work until its next scheduled run. Get them to a real answer in the first
minute instead.

Do both:

1. Suggest a first question the user can ask Hermes right now, for example:

   > How do you see NVIDIA's price action these past few days?

2. Offer to run the `morning-brief` playbook manually right now, so the user
   sees a full report immediately:

   > Want me to run the morning-brief playbook once right now, so you see a full
   > report? It uses your saved watchlist, company news, and macro context.

Run the playbook only after the user agrees, using the skill's own `SKILL.md`
as the template. This manual run is the first-value moment. Scheduling can wait.

Tell the user they can trigger any installed skill themselves with a slash
command — e.g. `/morning-brief`, or `/13f-diff` followed by an instruction —
and can ask questions in plain language any time. The `LLMQuant/skills`
analysis skills work the same way: `/llmquant-equities NVDA`,
`/llmquant-macro`, `/llmquant-portfolio`, and the rest shown by
`hermes skills list`.

## Optional - Put it on a schedule

Only after the user has seen a manual run and wants it to keep running on its
own.

Ask:

1. Which playbook first?
2. Which delivery channel?
3. What local time?
4. What watchlist size should the first run use?

Recommended first jobs:

- Conservative: `portfolio-pulse` weekly.
- Product feel: `morning-brief` on a few weekdays, then daily if the user wants
  it.

Use the chosen skill's own `SKILL.md` as the command template.

Example shape:

```bash
hermes cron create "0 8 * * 1-5" "Run the morning-brief playbook with my saved watchlist, company news, and macro context." \
  --skill morning-brief \
  --name "morning-brief" \
  --deliver telegram
```

After creating the job:

1. verify it immediately with `hermes cron trigger` — you do not have to wait
   for the next scheduled run to confirm the job works;
2. run `hermes cron list`;
3. confirm the next scheduled run time in the user's local time. On some Hermes
   versions (as of v0.18.x) cron expressions evaluate in host-local time.

## Common failures

- **Unauthorized smoke test**: the API key or Remote MCP URL is wrong or
  revoked. Ask the user to re-copy it from Dashboard.
- **`npx` missing**: stdio needs Node.js. Switch to Remote MCP URL if the user
  does not want local Node.js.
- **`hermes mcp add --env` produced a broken config**: remove that entry and
  write the YAML manually. On some Hermes versions (v0.18.x) it wrote the env
  flag into `args`, not `env`.
- **Skills not listed after tap**: tap may have registered only the source.
  Install the skills or copy them into `~/.hermes/skills/`, then list again.
- **Cron fires at the wrong local time**: edit the cron expression after
  checking the host timezone and `hermes cron list` next-run output.
- **Insufficient credits**: start with `portfolio-pulse`, shrink the
  watchlist, lower the cadence, buy a Starter Credit Pack, or use Beta Pass.

Once all steps pass, LLMQuant Data is connected, DeepSeek is the intended
baseline model, and the user has seen a real answer — either a first question
or a manual `morning-brief` run. Scheduling a standing job is optional from
there.