From 7589c9f71ca8cc09bf87da84261f812705ffe48d Mon Sep 17 00:00:00 2001
From: diegosouzapw <diegosouzapw@users.noreply.github.com>
Date: Wed, 5 Aug 2026 16:15:34 -0300
Subject: [PATCH] fix(docs): repair the #7786 squash contamination on
 release/v3.8.50
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The #7786 squash accidentally committed its worktree copy
(.claude/worktrees/feat-7786/**, since untracked) and leaked probe tests
(repro-8522/probe-9033/repro-8956 — each now green via #9355/#9385/#9354)
plus a stray changelog.d/fixes/9159-fix.plan.md describing an UNMERGED fix
(would fabricate a changelog entry at release time — removed; #9159's own
PR ships its fragment).

This restores the PR's actual deliverable at the right paths: the
management-auth terminology guide (now with the required MDX frontmatter),
its docs test (3/3 green) and its changelog fragment.
---
 .../7786-management-auth-terminology-docs.md  |  1 +
 changelog.d/fixes/9159-fix.plan.md            |  1 -
 docs/guides/MANAGEMENT-AUTH.md                | 47 +++++++++++++++++++
 tests/unit/management-auth-docs.test.ts       | 27 +++++++++++
 4 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 changelog.d/features/7786-management-auth-terminology-docs.md
 delete mode 100644 changelog.d/fixes/9159-fix.plan.md
 create mode 100644 docs/guides/MANAGEMENT-AUTH.md
 create mode 100644 tests/unit/management-auth-docs.test.ts

diff --git a/changelog.d/features/7786-management-auth-terminology-docs.md b/changelog.d/features/7786-management-auth-terminology-docs.md
new file mode 100644
index 0000000000..4a5fca7f9d
--- /dev/null
+++ b/changelog.d/features/7786-management-auth-terminology-docs.md
@@ -0,0 +1 @@
+- **docs:** add management authentication terminology guide ([#7786](https://github.com/diegosouzapw/OmniRoute/issues/7786))
diff --git a/changelog.d/fixes/9159-fix.plan.md b/changelog.d/fixes/9159-fix.plan.md
deleted file mode 100644
index 22d84fba2a..0000000000
--- a/changelog.d/fixes/9159-fix.plan.md
+++ /dev/null
@@ -1 +0,0 @@
-- fix(management): authorize mcp:connect-only keys on loopback/LAN when requireLogin is enabled (#9159)
\ No newline at end of file
diff --git a/docs/guides/MANAGEMENT-AUTH.md b/docs/guides/MANAGEMENT-AUTH.md
new file mode 100644
index 0000000000..25e0d7ae59
--- /dev/null
+++ b/docs/guides/MANAGEMENT-AUTH.md
@@ -0,0 +1,47 @@
+---
+title: "Management Authentication"
+version: 3.8.50
+lastUpdated: 2026-08-05
+---
+
+# Management Authentication
+
+OmniRoute uses four distinct credential families for management access. This guide
+distinguishes them by purpose, scope, and locality.
+
+| Credential              | Scope              | Locality      | Use Case                          |
+|-------------------------|--------------------|---------------|-----------------------------------|
+| Dashboard JWT session   | Full management    | Localhost      | Web dashboard login               |
+| CLI machine-id token    | Full management    | Per-machine    | `omniroute` CLI commands          |
+| Scoped `oma_` token     | Configurable scope | External       | Automation / CI / API access      |
+| Manage-scope API key    | `manage` scope     | External       | Management API calls              |
+
+## Dashboard JWT Session
+
+Generated on dashboard login (`/api/auth/login`). Stored in HTTP-only cookie.
+Valid for the session duration. Cannot be used from external hosts.
+
+## CLI Machine-ID Token
+
+Created by `omniroute auth login` on first use. Stored in `~/.omniroute/auth.json`.
+Used by the CLI for all management operations. Tied to the machine identity.
+
+## Scoped `oma_` Access Token
+
+Created via dashboard or CLI with configurable scopes (e.g., `manage`, `read`).
+Format: `oma_<random-hex>`. Used for programmatic access from external systems.
+
+## Manage-Scope API Key
+
+Standard API key with the `manage` scope enabled. Created in dashboard API Keys page.
+Used for management API calls from external hosts.
+
+## Header Examples
+
+```
+Authorization: Bearer oma_abc123def456
+Authorization: Bearer <standard-api-key-with-manage-scope>
+Cookie: omniroute_session=<jwt-token>
+```
+
+See `docs/reference/API_REFERENCE.md` for endpoint-specific auth requirements.
diff --git a/tests/unit/management-auth-docs.test.ts b/tests/unit/management-auth-docs.test.ts
new file mode 100644
index 0000000000..35410e81c3
--- /dev/null
+++ b/tests/unit/management-auth-docs.test.ts
@@ -0,0 +1,27 @@
+import { describe, it } from "node:test";
+import { ok } from "node:assert/strict";
+import { readFileSync } from "node:fs";
+
+describe("Management auth documentation (#7786)", () => {
+  const docPath = "docs/guides/MANAGEMENT-AUTH.md";
+  const content = readFileSync(docPath, "utf-8");
+
+  it("exists and has content", () => {
+    ok(content.length > 500, "should have substantial content");
+    ok(content.includes("Dashboard JWT session"));
+    ok(content.includes("CLI machine-id token"));
+    ok(content.includes("oma_"));
+  });
+
+  it("documents all four credential families", () => {
+    const families = ["Dashboard JWT", "CLI machine-id", "oma_", "Manage-scope"];
+    for (const f of families) {
+      ok(content.includes(f), `should document ${f}`);
+    }
+  });
+
+  it("mentions relevant auth header examples", () => {
+    ok(content.includes("Authorization"));
+    ok(content.includes("Bearer"));
+  });
+});