From abc2335ea203c6ef64c0cdd02651712cdabe3d3b Mon Sep 17 00:00:00 2001
From: Vojtech Rysanek <vrysanek@groupon.com>
Date: Wed, 6 May 2026 11:00:59 +0400
Subject: [PATCH 1/2] docs(marketplace): document two-step fallback for
 marketplace registration
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The 'Git channel' block previously showed only the direct '/plugin
marketplace add https://x:$AGNES_PAT@…' path. That path fails on
macOS/Windows against a private-CA Agnes instance because Bun-compiled
'claude' ignores the OS trust store and CA env vars on the marketplace
HTTPS path (see the existing rationale in app/web/setup_instructions.py).

Document the two-step fallback explicitly:

  git clone https://x:$AGNES_PAT@agnes.example.com/marketplace.git/ \
    ~/agnes-marketplace
  claude plugin marketplace add ~/agnes-marketplace

System 'git' honors GIT_SSL_CAINFO + the OS trust store, so the clone
succeeds where direct add fails; pointing Claude Code at the local clone
then sidesteps the Bun TLS path entirely. The dashboard-served setup
payload already branches between the two automatically based on
platform; the docs now match that behavior for manual flows.

Also note the optional 'remote set-url' hardening to strip the PAT from
the cloned repo's origin (mirrors what the dashboard payload does).
---
 CLAUDE.md | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 13c3af9..cb0d483 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -363,10 +363,32 @@ User registration inside Claude Code:
 # ZIP channel (typically via a SessionStart hook that unpacks into ./marketplace/)
 curl -H "Authorization: Bearer $AGNES_PAT" https://agnes.example.com/marketplace.zip
 
-# Git channel — one-time registration
+# Git channel — one-time registration. Two paths; pick the first that works.
+
+# (a) Direct registration — preferred when it works.
 /plugin marketplace add https://x:$AGNES_PAT@agnes.example.com/marketplace.git/
+
+# (b) Two-step fallback — required when (a) fails. Bun-compiled `claude` on
+#     macOS / Windows ignores the OS trust store and CA env vars on the
+#     marketplace HTTPS path, so direct add can fail with TLS errors against
+#     a private-CA Agnes instance even when system tools work fine. System
+#     `git` honors GIT_SSL_CAINFO + the OS trust store, so cloning manually
+#     and pointing Claude Code at the local clone sidesteps the Bun TLS path
+#     entirely.
+git clone https://x:$AGNES_PAT@agnes.example.com/marketplace.git/ ~/agnes-marketplace
+claude plugin marketplace add ~/agnes-marketplace
+# Optional hardening: strip the PAT from the cloned repo's origin so it
+# doesn't sit in plaintext at ~/agnes-marketplace/.git/config — re-clone via
+# the dashboard's setup flow when the PAT rotates.
+git -C ~/agnes-marketplace remote set-url origin https://agnes.example.com/marketplace.git/
 ```
 
+The dashboard-served setup payload (see `app/web/setup_instructions.py`) already
+branches between (a) and (b) automatically based on platform when a private CA
+is in play. The block above is the manual equivalent for users registering
+outside that flow (e.g. operators bringing up a new instance, or
+analysts whose first attempt failed and need to retry by hand).
+
 ## Hybrid Queries (BigQuery + Local)
 
 For tables too large to sync locally, use hybrid queries that JOIN local data with on-demand BigQuery results:

From a7d19206d74e6511454eecadca388bcd1fd3ae58 Mon Sep 17 00:00:00 2001
From: ZdenekSrotyr <zdenek.srotyr@keboola.com>
Date: Wed, 6 May 2026 09:27:42 +0200
Subject: [PATCH 2/2] =?UTF-8?q?release:=200.38.1=20=E2=80=94=20docs(market?=
 =?UTF-8?q?place)=20two-step=20fallback?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 CHANGELOG.md   | 13 +++++++++++++
 pyproject.toml |  2 +-
 2 files changed, 14 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6b40d45..9a787fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -10,6 +10,19 @@ CalVer image tags (`stable-YYYY.MM.N`, `dev-YYYY.MM.N`) are produced for every C
 
 ## [Unreleased]
 
+## [0.38.1] — 2026-05-06
+
+### Internal
+- `CLAUDE.md` — `Claude Code marketplace endpoint` section now documents the
+  two-step fallback (system `git clone` + local `claude plugin marketplace
+  add`) for users registering manually against a private-CA Agnes instance.
+  Bun-compiled `claude` ignores the OS trust store and CA env vars on the
+  marketplace HTTPS path, so direct `/plugin marketplace add` over HTTPS can
+  fail with TLS errors on macOS / Windows even when system tools work fine.
+  The dashboard-served setup payload (`app/web/setup_instructions.py`)
+  already branches between the two automatically based on platform; the
+  doc snippet now matches that behavior for manual flows.
+
 ## [0.38.0] — 2026-05-06
 
 ### Added
diff --git a/pyproject.toml b/pyproject.toml
index 40106fe..54d552e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "agnes-the-ai-analyst"
-version = "0.38.0"
+version = "0.38.1"
 description = "Agnes — AI Data Analyst platform for AI analytical systems"
 requires-python = ">=3.11,<3.14"
 license = "MIT"