From f9a8857d0eb4b11513cb085f9a698f940cf642a8 Mon Sep 17 00:00:00 2001 From: Jacob Prall Date: Wed, 5 Aug 2026 14:23:55 -0700 Subject: [PATCH] Set expectations for the first-run 401, and drop the docs tests MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean-room testing showed that an unauthenticated first session reports an HTTP 401 once. The adapter's metadata bootstrap is unconditional and exposes no setting to suppress it, so this is inherent rather than a defect: Pi starts, all 21 skills load, and `settings.autoAuth` stays false so nothing opens a browser. Say so in README.md. A first-run 401 with no explanation reads as a broken install, which is the difference between users authenticating and users uninstalling. Record the same in SPEC.md §5 alongside the bootstrap it follows from. Remove tests/package/docs.test.ts. Asserting on prose with regexes couples the suite to wording rather than behavior, so it breaks on harmless rewrites while proving little. Documentation-claim consistency moves to the manual T-0 review. Co-authored-by: Cursor --- README.md | 5 +++++ docs/SPEC.md | 6 ++++++ tests/package/docs.test.ts | 41 -------------------------------------- 3 files changed, 11 insertions(+), 41 deletions(-) delete mode 100644 tests/package/docs.test.ts diff --git a/README.md b/README.md index 61d46fa..9819397 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,11 @@ connection to populate its local tool-metadata cache, but it does not open an OA bootstrap cannot connect, Pi and the Render skills continue to work; authenticated MCP operations connect on demand. +Because that bootstrap runs before you have credentials, the first session reports once that the +Render server requires authentication (an HTTP 401). This is expected, not a failure — Pi and all +21 skills load normally. Run `/mcp-auth render` when you want the Render tools, and the notice +stops. + ## Auth - **OAuth (recommended, interactive):** run `/mcp-auth render` in a session — no API key needed. diff --git a/docs/SPEC.md b/docs/SPEC.md index 48b2b4a..701829b 100644 --- a/docs/SPEC.md +++ b/docs/SPEC.md @@ -238,6 +238,12 @@ metadata cache does not exist, the first session makes a best-effort connection Failure is contained to MCP and MUST NOT prevent Pi or the Render skills from loading. Authenticated operations connect on demand after that bootstrap. +The bootstrap is unconditional and the adapter exposes no setting to suppress it, so on a clean run +with no credentials it reports an HTTP 401 once. `settings.autoAuth` stays at its default of `false`, +which is what keeps that from escalating into an unprompted browser flow. `README.md` MUST set this +expectation, because a first-run 401 that looks like breakage is the difference between an install +users trust and one they abandon. + `RENDER_API_KEY` MUST be passed by environment variable reference (`bearerTokenEnv`), never inlined as a literal. This package checks only whether a non-empty value is present to select the auth mode; the adapter resolves the value when connecting, so the secret never enters the config diff --git a/tests/package/docs.test.ts b/tests/package/docs.test.ts deleted file mode 100644 index d52a68c..0000000 --- a/tests/package/docs.test.ts +++ /dev/null @@ -1,41 +0,0 @@ -import { readFileSync } from "node:fs"; -import { join } from "node:path"; -import { fileURLToPath } from "node:url"; -import { describe, expect, it } from "vitest"; - -const repoRoot = fileURLToPath(new URL("../..", import.meta.url)); -const readme = readFileSync(join(repoRoot, "README.md"), "utf8"); -const spec = readFileSync(join(repoRoot, "docs/SPEC.md"), "utf8"); -const changelog = readFileSync(join(repoRoot, "CHANGELOG.md"), "utf8"); -const installCommand = "pi install https://github.com/render-lab/render-pi-plugin"; - -describe("release documentation", () => { - it("uses the GitHub installation source consistently", () => { - expect(readme).toContain(installCommand); - expect(spec).toContain(installCommand); - expect(readme).not.toContain("pi install npm:"); - expect(spec).not.toContain("pi install npm:"); - expect(spec).not.toContain("github.com/render-oss/pi-render"); - }); - - it("documents lazy included MCP support and both authentication paths", () => { - expect(readme).toMatch(/no separate\s+MCP/i); - expect(readme).toMatch(/lazy/i); - expect(readme).toMatch(/clean first run.*metadata/is); - expect(readme).toMatch(/Pi and the Render skills continue to work/i); - expect(readme).toContain("/mcp-auth render"); - expect(readme).toContain("RENDER_API_KEY"); - }); - - it("explains how to keep the skills while disabling MCP", () => { - expect(readme).toContain("pi config"); - expect(readme).toMatch(/skills-only/i); - }); - - it("states the deliberately limited v1 scope in release notes", () => { - expect(changelog).toContain("## 0.1.0"); - expect(changelog).toMatch(/does not include.*slash commands/is); - expect(changelog).toMatch(/subagent/i); - expect(changelog).toMatch(/Blueprint validation hook/i); - }); -});