docs(reference): use harper-config.yaml consistently in v5 (#661)

* docs(reference): use harper-config.yaml consistently in v5

The v5 docs used both `harper-config.yaml` and the pre-v5
`harperdb-config.yaml`. Two pages contradicted each other outright:
`resources/resource-api.md` told readers to set
`authentication.enableSessions` in `harperdb-config.yaml` while
`security/jwt-authentication.md` put the sibling `authentication` token
timeouts in `harper-config.yaml`.

`harper-config.yaml` is the correct name. In HarperFast/harper,
`utility/hdbTerms.ts` labels `HDB_CONFIG_FILE` ('harperdb-config.yaml')
"Old Harper Root Config File" and `HARPER_CONFIG_FILE`
('harper-config.yaml') "Harper Root Config File". Every resolver prefers
the new name and falls back to the old one only when the new file is
absent (`config/configUtils.ts` getConfigFilePath and setConfigValue,
`bin/run.ts`, `utility/logging/harper_logger.ts`), and all writes target
the new name (`configUtils.ts` initial write, `installer.ts` boot-props
`settings_path`, and `<timestamp>-harper-config.yaml.bak` backups).

Replaces the five remaining occurrences in `reference/`, plus one in
`release-notes/v5-lincoln/v5-migration.md` that described current v5
module-loading behavior with the legacy name. `reference_versioned_docs/version-v4/`
is left alone, as is the 5.0 release note that documents the rename itself.

Also adds a note to `reference/configuration/overview.md`: with the legacy
spelling gone from every other v5 page, an instance upgraded from v4 that
still has `harperdb-config.yaml` on disk had no signal anywhere in the v5
docs. The note states the loader's actual behavior, including that
upgrading does not rename the file.

This fixes a docs-side bug that propagates into HarperFast/skills, which
generates agent-facing rules from these pages. The `checking-authentication`
rule (HarperFast/skills#81) pulled both sections into one rule, so it tells
agents to set `enableSessions` in `harperdb-config.yaml` in one step and
`operationTokenTimeout` in `harper-config.yaml` in another.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(configuration): anchor the upgraded-instance note on settings_path

The note claimed Harper looks for `harper-config.yaml` first and falls
back to `harperdb-config.yaml`, then writes later changes back to
whichever file it found. That describes only the root-path override path.

`configUtils.ts` getConfigFilePath does the new-name-first lookup inside
`if (cmdArgs)`, where `cmdArgs` is `getEnvCliRootPath()` — a `ROOTPATH`
environment variable or `--ROOTPATH` argument. With neither set, which is
the normal installed case, it returns the literal `settings_path` from the
boot properties file. `installer.ts` writes `settings_path` only on a fresh
install (it exits early when either config file already exists), and
nothing in `upgrade/` repoints it, so an upgraded node keeps naming
`harperdb-config.yaml`. Renaming the file therefore breaks startup rather
than migrating it, and because setConfigValue resolves the file by its own
directory lookup that prefers the new name, leaving both files present can
send startup and configuration writes to different files.

Rewrites the note around `settings_path` as the thing that actually
selects the file, and drops the precedence claim.

Reported by @kriszyp in review.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

Author: Ethan-Arrowood

reference/configuration/overview.md

@@ -9,6 +9,10 @@ title: Configuration Overview
 
 Harper is configured through a [YAML](https://yaml.org/) file called `harper-config.yaml` located in the Harper root directory. By default the root directory is a folder named `hdb` in the home directory of the current user.
 
+:::note Which file your instance reads
+The active config file is the one named by `settings_path` in Harper's boot properties file (usually `~/.harperdb/hdb_boot_properties.file`); a `ROOTPATH` environment variable or `--ROOTPATH` argument overrides it. A fresh v5 install records `harper-config.yaml`, but an instance upgraded from v4 keeps whatever its boot properties already named — usually `harperdb-config.yaml`, which Harper still reads. Upgrading neither renames the file nor repoints `settings_path`, so renaming it alone will break startup; update `settings_path` in the same step, and avoid leaving both files in the root directory at once.
+:::
+
 Some configuration values are pre-populated in the config file on install, regardless of whether they are used.
 
 For a complete reference of all available configuration options, see [Configuration Options](./options.md).

reference/mcp/cli.md

@@ -31,7 +31,7 @@ harper mcp [subcommand] [flags]
 
 With no `--target` flag, the CLI connects to the Harper running on the same host via the operations API Unix Domain Socket — the same socket `bin/cliOperations` uses. Filesystem permissions on the socket are the access gate; no credentials are required or sent.
 
-The UDS path is derived from `operationsApi.network.domainSocket` in `harperdb-config.yaml` and is typically `<rootPath>/sockets/operations-server`.
+The UDS path is derived from `operationsApi.network.domainSocket` in `harper-config.yaml` and is typically `<rootPath>/sockets/operations-server`.
 
 ### Network HTTPS / HTTP
 

reference/mcp/configuration.md

@@ -6,7 +6,7 @@ title: MCP Configuration
 
 <VersionBadge version="v5.1.0" />
 
-All MCP configuration lives under the top-level `mcp:` block in `harperdb-config.yaml`. Each profile (`operations`, `application`) is enabled by the **presence** of its sub-block — there is no separate `enabled` flag. A minimal "turn it on" config is therefore just:
+All MCP configuration lives under the top-level `mcp:` block in `harper-config.yaml`. Each profile (`operations`, `application`) is enabled by the **presence** of its sub-block — there is no separate `enabled` flag. A minimal "turn it on" config is therefore just:
 
 ```yaml
 mcp:

reference/mcp/migration.md

@@ -23,13 +23,13 @@ This page covers what changes for you and how to migrate.
 | Rate limiting                | Not present                                      | Per-session, per-tool token-bucket on both profiles                                             |
 | Audit logging                | Operations API audit log only                    | Dedicated `mcp.audit` category with credential redaction                                        |
 | Per-attribute permissions    | Not honored in the tool surface                  | Narrowed at schema-derivation time                                                              |
-| Config                       | Env vars + addon's own JSON                      | Top-level `mcp:` block in `harperdb-config.yaml`                                                |
+| Config                       | Env vars + addon's own JSON                      | Top-level `mcp:` block in `harper-config.yaml`                                                  |
 
 ## Migration checklist
 
 ### 1. Enable the built-in MCP surface
 
-Add an `mcp:` block to `harperdb-config.yaml`. The minimal "turn it on" form is:
+Add an `mcp:` block to `harper-config.yaml`. The minimal "turn it on" form is:
 
 ```yaml
 mcp:

reference/resources/resource-api.md

@@ -745,7 +745,7 @@ async get(target) {
 
 ### Session and Login from a Resource
 
-The context returned by `getContext()` exposes `login` and `session` for handling sign-in/out flows in a custom Resource. Sessions require `authentication.enableSessions: true` in `harperdb-config.yaml`.
+The context returned by `getContext()` exposes `login` and `session` for handling sign-in/out flows in a custom Resource. Sessions require `authentication.enableSessions: true` in `harper-config.yaml`.
 
 ```typescript
 export class SignIn extends Resource {

release-notes/v5-lincoln/v5-migration.md

@@ -120,7 +120,7 @@ The `blob.save()` method has been removed. Please use the `saveBeforeCommit` fla
 
 Harper v5 loads application modules through Node.js's VM module API, giving each application its own module cache and a `harper` module scoped to that application — the `logger` it exports is tagged with the application name, and `config` reflects that application's own configuration. By default (`vm-current-context`), applications share JavaScript intrinsics (`Object`, `Array`, `Promise`, and so on) with Harper. Sharing intrinsics avoids the compatibility problems that separate per-application intrinsics can cause — most commonly `instanceof` and other identity checks failing for values that cross the application/Harper boundary.
 
-All module loading behavior is controlled by the `applications` section in `harperdb-config.yaml`:
+All module loading behavior is controlled by the `applications` section in `harper-config.yaml`:
 
 ```yaml
 applications: