# Configuration reference

Every environment variable, every path, and the precedence rule between them.

Research Scan reads configuration from the environment and from a `.env` file. One
module in the package does that reading, which is what allows every secret to be
redacted before anything is logged or cached.

## Precedence

```
process environment  >  ~/.config/research-scan/.env  >  ./.env
```

Exporting a variable for a single command always wins, without editing a file.

## Credentials

These are treated as secrets: masked in every output, redacted from logs and from
the HTTP cache.

| Variable | Required | Needed for |
|---|---|---|
| `OPENALEX_API_KEY` | **Yes** | OpenAlex, the primary source. `doctor` exits 3 without it. |
| `S2_API_KEY` | No | Semantic Scholar. Search and citation-graph expansion work without it, throttled to roughly a third of the rate; `doctor` warns. |
| `NCBI_API_KEY` | No | PubMed only: 10 req/s instead of 3. |

## Public settings

Not secrets, and shown in full in diagnostic output.

| Variable | What it does |
|---|---|
| `OPENALEX_MAILTO` | Your email. Raises OpenAlex to 5 req/s and joins the Crossref polite pool. Strongly recommended. |
| `RESEARCH_SCAN_RUN` | The run directory to operate on, instead of the newest. |
| `RESEARCH_SCAN_MCP_DATA` | Where the MCP adapter keeps run directories. Defaults to `~/.local/share/research-scan-mcp/runs/`, one directory per scan id. |

`OPENALEX_MAILTO` is the one people skip and then wonder about rate limits. It
costs nothing and multiplies your throughput.

## Paths

| Path | What it is |
|---|---|
| `~/.config/research-scan/.env` | The credential store. Mode `0600`, in a `0700` directory. |
| `~/.cache/research-scan/http.sqlite` | The 7-day HTTP cache. |
| `./.env` | A repo-local override, lowest precedence. |
| `research/scans/<YYYY-MM-DD>-<slug>/` | Run directories, relative to the working directory. |
| `~/.local/share/research-scan-mcp/runs/<scan_id>/` | Run directories under the MCP adapter. |

## How the file is written

`research-scan configure` writes `~/.config/research-scan/.env` through a
temporary file and an atomic replace, and **merges** rather than overwrites:
variables it does not ask about, and comments, survive untouched.

To write it by hand instead, `.env.example` in the main repo is the template.

## Reading the current state

```bash
research-scan doctor --verbose
```

Shows every credential, masked to its last four characters, with the origin of
each value — `user-config`, `local-env` or the process environment — plus the
resolved paths. `doctor --json` carries the same under `keys` and `paths`.

## The HTTP cache

Responses are cached for seven days in `~/.cache/research-scan/http.sqlite`. Every
network-touching stage takes `--no-cache` to bypass it.

`doctor` always bypasses the cache: a readiness check that could pass on
yesterday's cached response would not be a readiness check.

Deleting the file is safe. It will be recreated.