Merge pull request #196 from keboola/docs/marketplace-setup-fallback

docs(marketplace): document two-step fallback for marketplace registration

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

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:

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"