Configuration reference¶

Configuration keys phpbotscout reads, with types, defaults, and the environment-variable mapping.

Every key is readable from a config file, an environment variable under the PHPBOTSCOUT prefix, or any other source the store is given. See Run the bot for a worked example.

Where configuration is read from¶

Layers, lowest precedence first. A later layer overrides an earlier one key by key; a layer that is absent is simply empty, not an error.

1. The config files — by default /etc/phpbotscout/config.yaml then $HOME/.phpbotscout/config.yaml
2. A project-local .phpbotscout.yaml, found by walking up from the working directory
3. Environment variables under the PHPBOTSCOUT prefix
4. CLI flags you actually changed

There is no shipped-defaults layer. The framework supports one, but phpbotscout embeds no assets/config.yaml, so a key you delete from your file falls back to the default compiled into the code — the value in the tables below — rather than to a shipped file. The config init writes is a starting point, not a floor beneath your edits.

--config replaces the default files rather than adding to them, and it also suppresses the project-local layer. Naming a config file means "use this one": a file the caller did not name, and may not know is there, must not override files they did name.

phpbotscout config path prints the files being read, with each one's role. Use it before believing anything else on this page about where a value came from.

The environment-variable mapping¶

Dots become underscores and the whole key is upper-cased, under the PHPBOTSCOUT prefix:

Credential values are the exception, and are never read this way. gitlab.auth.env and discord.auth.env hold the name of a variable, and the secret is read from the variable that name points at.

Most commands refuse to run without a config file¶

With none of the candidate files present, any command that reads configuration exits with:

ERRO failed to load configuration: no config file found hints="Run 'phpbotscout init' to create a configuration."

phpbotscout init writes $HOME/.phpbotscout/config.yaml. A project-local .phpbotscout.yaml in the working directory satisfies the check on its own, which is the quickest way to run against a throwaway configuration.

discord¶

The bot is one Discord application with one token, so the credential is discord.auth, set once for every server. Exactly one auth mode may be set. Two is an error rather than a preference, because silently choosing one of them is the wrong behaviour where a credential is concerned.

The per-server keys (answer_budget, ai.*, corpus and forum_scopes) are read at start. A change needs a restart, and is not warned about.

A corpus prefix narrows what discovery found and can never add to it. A prefix that matches no indexed source is not refused, because the index is empty on a fresh install until its first refresh. It is logged at startup instead:

WARN a server's corpus matches no indexed source; it will decline everything until one does space=... corpus=[...]

Several servers¶

One serve process can serve several servers, such as a stage server that rehearses a setting and the production server that gets it once it has earned it. One application is invited to each, with one token.

Each server's data is kept apart in the one database. Questions, answers and topics record their server, and a topic never spans two. The documentation index is shared. The user-hash salt is one per deployment, so a person is the same pseudonym in every server, and forget finds everything in one pass.

A server with its own corpus or ai.* is answered by its own answering service. A server with its own answer_budget spends it alone, so stage using up its hour never blocks production. review works on one server at a time. See spec 0029.

Rows recorded before servers were recorded have no server. On the first start with exactly one server configured, they are adopted into it, and the count is logged. With several configured they stay unassigned, because nothing says where they came from, and the log says so:

WARN questions recorded before servers were assigned belong to no server questions=12 detail="start once with only their server configured to adopt them"

Supervision¶

How the daemon restarts the Discord connection when it goes wrong. Every value is validated at startup. A value left at zero takes its default, and a negative one, which would silently switch supervision off, is refused.

health¶

index¶

Fetching over SSH¶

Over HTTPS every fetch counts against the forge's web rate limit, which an hourly refresh of the whole corpus can exhaust. Over SSH it does not, so a deployment should set a key. Use a key that does nothing else, registered on the bot's own forge account, and keep both files readable by the bot alone:

index:
  ssh:
    key: /home/phpbotscout/.config/phpbotscout/git_ed25519
    known_hosts: /home/phpbotscout/.config/phpbotscout/known_hosts

Build the known-hosts file once, and compare its fingerprints with the ones the forge publishes before trusting it. ssh-keyscan asks the network, which is what the file pins against:

ssh-keyscan gitlab.com > known_hosts
ssh-keygen -lf known_hosts

The SSH URL each source is fetched from is the one the forge reports, and it must name the host in gitlab.url.api (GitLab.com when unset). A source whose SSH URL is missing or names another host fails on its own, with the reason recorded. A clone made over HTTPS is switched to SSH on its next fetch, without cloning again.

An hour is the default because documentation changes on the timescale of a working day, not a minute. The refresh also runs once at startup, so a daemon restarted after downtime does not wait a full interval to catch up.

Written as a Go duration string (30m, 2h, 90s). It is parsed by phpbotscout rather than by the decoder, so a config file and the live store accept exactly the same values.

respond¶

The window counts from the last activity, not from when the thread was opened, so a conversation that is still going after two days is still answered. Threads are restored from the answer records at startup, so a restart does not forget them.

The budget exists because anyone on a public server can mention the bot and each answer is a model call somebody pays for. It is a single ceiling for the whole bot rather than one per person: one ceiling needs nothing stored and bounds every runaway you have not thought of, at the cost that one person hammering the bot takes it away from everybody for the rest of the hour. Pick a number with that in mind, and expect to raise it once you have traffic to look at.

answer¶

Each entry:

A line is added when the question names the upstream or one of its aliases, or names the wrapper and uses one of its terms. Names and terms match whole words, case-insensitively, so a name that is also an ordinary word (vault) belongs in terms, where the wrapper has to be named too. At most two lines are added, in the order declared.

answer:
  upstreams:
    - upstream: FFmpeg
      wrapper: phpboyscout/ffmpeg-wasi
      names: [ffmpeg-wasi]
      terms: [bitrate, bitrates, codec, codecs, encoder, encoders, filter, filters]
      docs: https://ffmpeg.org/documentation.html
      version: tag
    - upstream: disgo
      wrapper: phpboyscout/go/comms-discord
      names: [comms-discord]
      terms: [intent, intents, gateway, shard, shards]
      docs: https://pkg.go.dev/github.com/disgoorg/disgo
      version: github.com/disgoorg/disgo

An entry that does not validate stops serve and ask from starting, and a change to one while serve runs is refused whole, keeping the entries in use and logging why.

gitlab¶

Discovery and cloning both read this section. Keys follow the toolkit's forge convention, so they behave identically to every other tool in the estate.

Resolution runs in that order and falls back to GITLAB_TOKEN when the section names nothing. Note that auth.env is the name of a variable, not its value.

The token needs the Maintainer role on the group: discovery reads each repository's Pages settings to locate its documentation site, and GitLab gates that endpoint behind it. A weaker token does not silently exclude repositories — they are reported as unresolved by index sources.

Cloning itself needs no token, since the corpus is public by construction. With index.ssh.key set, cloning uses that key and never the token.

phpboyscout/go-tool-base   rejected  unresolved  could not read the documentation site: GET https://gitlab.com/api/v4/projects/phpboyscout%2Fgo-tool-base/pages: 403 {message: 403 Forbidden}

ai¶

Read by ask and by serve when they compose an answer. Retrieval never touches these keys, so ask --retrieval-only works with none of them set.

A server can override either with discord.guilds[].ai.provider and discord.guilds[].ai.model, so stage can trial a model before production gets it.

Which providers actually work¶

Only the Anthropic provider module is linked into the binary, so two names work:

Any other name fails before a request is made:

ERRO ask: build openai client: unable to construct client: unsupported provider: openai

This is not a configuration mistake you can work around from the config file. Adding a provider means linking its module into the build, and it would also have to support the one-shot client ask builds. One-shot is load-bearing: without it a long-running client re-sends every previous exchange, is unsafe for concurrent use, and, in a shared channel, makes one person's question part of the context for the next person's.

Which model you get¶

With ai.provider: claude and ai.model unset, requests go to the chat module's default model, DefaultModelClaude, a larger model that moves with that module's releases. That is not the model the project selected on measurement, which is Claude Haiku 4.5 (claude-haiku-4-5). Nothing in this repository sets ai.model, so a deployment that wants Haiku has to say so:

ai:
  provider: claude
  model: claude-haiku-4-5

See choosing a provider for why that model, and what phpbotscout does not do for what changing it does not buy you.

The AI credential is not on the credentials chain¶

gitlab.auth and discord.auth accept an env-var name, a keychain reference or a literal. The AI provider accepts none of them. ask builds its client without passing any credential configuration, so for ai.provider: claude the key is read from the well-known ANTHROPIC_API_KEY variable and from nowhere else. There is no ai.auth.env, no ai.auth.keychain, and no ai.token.

Without it:

ERRO ask: build claude client: unable to construct client: Anthropic API key is required but not provided

log¶

--debug overrides it for one invocation. An unrecognised value is ignored silently and logging stays at info — config get log.level will happily read back bogus while the logger never used it, so do not take that read as confirmation the level applied.

What happens when a value is wrong¶

serve validates before anything binds or connects, so a misconfiguration is a startup failure with a named field rather than a confusing error three layers downstream. These are the messages, verbatim:

Upgrading: auth moved to discord.auth¶

The credential used to sit on each guild, as discord.guilds[].auth. It is now discord.auth, set once, because the bot is one application with one token. A configuration that still names auth on a guild is refused at startup. A key that was read and silently ignored would be the quieter surprise.

To upgrade, move the auth block up a level:

discord:
  auth:
    env: DISCORD_PHPBOTSCOUT_TOKEN
  guilds:
    - space: "1531227937678954747"

Upgrading from channels¶

discord.guilds[].channels, the old channel allowlist, has been removed. A configuration that still names it is refused at startup. Ignoring it would quietly widen what the bot reads the moment it was upgraded, and that has to be the operator's choice.

To upgrade, delete channels. Then list any public channel the bot must not read under exclude_channels. See spec 0024.

Which channels the bot reads¶

The bot reads every text channel and forum that the server's @everyone role can view, and the public threads under them. It works this out from the server's @everyone permissions and the channel's own @everyone overwrite. A channel only some roles can see is not read.

Visibility is decided per message, so there is no list to keep in step. A channel made private stops being read from its next message. A new public channel is read without a restart. When visibility cannot be established, the message is dropped. Missing a public message is the cheaper mistake.

Private threads are never read. Announcement channels and the text chat of voice channels are never read, even when public.

Excluding a channel¶

Excluding a channel also excludes the threads hanging off it. You do not list thread IDs, and there is no key for doing so.

Discord models a thread as a channel with its own ID, so a thread is judged by its parent. An excluded channel cannot leak through a thread that outlived the exclusion. A thread whose parent cannot be determined is not read.

An excluded channel's messages are counted with every other dropped message, as one unlabelled number. Nothing about them is logged.

Two mistakes do not produce an error, and are worth knowing for that reason:

• An unrecognised log.level is ignored, silently, and logging stays at info.
• A missing index file is created rather than reported. ask opens the database at index.path and creates it when it is not there, so asking from the wrong working directory produces a new empty index and a decline, not an error. Only a path whose directory is missing fails, with ask: open index: store: open: unable to open database file: no such file or directory.

Hot-reload¶

discord.guilds[].exclude_channels applies immediately. space, discord.auth and post_answers are read once at start and require a restart, logging a warning that names the field so an ignored change is never a silent one. A guild's answer_budget, ai.*, corpus and forum_scopes also need a restart, without a warning.

answer.upstreams applies immediately; a change that does not validate is refused and the running entries stay.

index.refresh_interval, index.path, index.clones and index.ssh.* are read once at start. Changing any of them requires a restart. Clones under a directory the configuration no longer names are left where they are.

Keys phpbotscout does not have¶

Asked for often enough to be worth stating plainly:

• No key names a source to index. The corpus is enumerated from the forge and filtered by a predicate; configuration is a request to index and never an authority on visibility. See what the bot is allowed to read.
• No key sets a retrieval score threshold. ask --limit bounds how many passages are retrieved, and that is the only retrieval knob exposed.
• No key configures moderation or issue creation. Neither is built yet; see what phpbotscout does not do.
• No key changes chunk size, overlap or ranking weights. Those are compile-time constants; the values are in the indexing reference.
• No key for an AI credential. See the AI credential is not on the credentials chain.