From ea518be5c3e5114744d5a0bb68095c28ebf940df Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Wed, 2 Sep 2026 08:11:11 -0600 Subject: [PATCH 1/2] 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 `-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 --- reference/configuration/overview.md | 4 ++++ reference/mcp/cli.md | 2 +- reference/mcp/configuration.md | 2 +- reference/mcp/migration.md | 4 ++-- reference/resources/resource-api.md | 2 +- release-notes/v5-lincoln/v5-migration.md | 2 +- 6 files changed, 10 insertions(+), 6 deletions(-) diff --git a/reference/configuration/overview.md b/reference/configuration/overview.md index 73f6f98fc..7c079192e 100644 --- a/reference/configuration/overview.md +++ b/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 Instances upgraded from v4 +Before v5 this file was named `harperdb-config.yaml`, and that name is still supported. Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml` when only the older file is present, then writes later changes — including those made by `set_configuration` — back to whichever file it found. Upgrading does not rename the file, so an upgraded instance keeps its `harperdb-config.yaml` until you rename it. A fresh install always creates `harper-config.yaml`. +::: + 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). diff --git a/reference/mcp/cli.md b/reference/mcp/cli.md index fe8c8b767..a572610db 100644 --- a/reference/mcp/cli.md +++ b/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 `/sockets/operations-server`. +The UDS path is derived from `operationsApi.network.domainSocket` in `harper-config.yaml` and is typically `/sockets/operations-server`. ### Network HTTPS / HTTP diff --git a/reference/mcp/configuration.md b/reference/mcp/configuration.md index 205c26098..2915d5d82 100644 --- a/reference/mcp/configuration.md +++ b/reference/mcp/configuration.md @@ -6,7 +6,7 @@ title: MCP Configuration -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: diff --git a/reference/mcp/migration.md b/reference/mcp/migration.md index bcc7cb977..0315772df 100644 --- a/reference/mcp/migration.md +++ b/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: diff --git a/reference/resources/resource-api.md b/reference/resources/resource-api.md index a52683332..1f121d540 100644 --- a/reference/resources/resource-api.md +++ b/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 { diff --git a/release-notes/v5-lincoln/v5-migration.md b/release-notes/v5-lincoln/v5-migration.md index 8a95f9ba5..905475ab4 100644 --- a/release-notes/v5-lincoln/v5-migration.md +++ b/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: From f050b625241849d4b5a2f516e3f15c5c496ff8c0 Mon Sep 17 00:00:00 2001 From: Ethan Arrowood Date: Wed, 2 Sep 2026 12:56:09 -0600 Subject: [PATCH 2/2] docs(configuration): anchor the upgraded-instance note on settings_path MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- reference/configuration/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/reference/configuration/overview.md b/reference/configuration/overview.md index 7c079192e..112327b24 100644 --- a/reference/configuration/overview.md +++ b/reference/configuration/overview.md @@ -9,8 +9,8 @@ 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 Instances upgraded from v4 -Before v5 this file was named `harperdb-config.yaml`, and that name is still supported. Harper looks for `harper-config.yaml` first and falls back to `harperdb-config.yaml` when only the older file is present, then writes later changes — including those made by `set_configuration` — back to whichever file it found. Upgrading does not rename the file, so an upgraded instance keeps its `harperdb-config.yaml` until you rename it. A fresh install always creates `harper-config.yaml`. +:::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.