From d1ce3e7a7be326627689280407d8cde2be106a57 Mon Sep 17 00:00:00 2001 From: Suppaseth Charoenkarnka Date: Tue, 19 May 2026 14:15:38 +0700 Subject: [PATCH] =?UTF-8?q?docs(update):=20warn=20about=20WebFetch=20summa?= =?UTF-8?q?rization=20=C2=B7=20prefer=20curl=20-fsSL=20for=20raw=20fetches?= =?UTF-8?q?=20(v2.4.13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a Known Gotcha to skills/update/SKILL.md explaining that WebFetch may post-process (paraphrase/truncate) content even with raw.githubusercontent.com URLs and explicit "return verbatim" prompts. Recommends `curl -fsSL` via the Bash tool for the four raw-content paths in /update: plugin.json + settings.json JSON parsing, PLUGIN-CHANGELOG.md verbatim display, and SKILL.md self-update bootstrap. Also adds inline ⚠️ pointers at each of the four WebFetch call sites in the step prose so a reader following the steps top-to-bottom hits the gotcha at the relevant moment, not only at the end of the document. Closes the coherence gap that 3-round review flagged: warning lives at the bottom but step prose says "use WebFetch". No behavior change — this is a documentation-only PR; the actual WebFetch calls remain in place and are correctly out of scope for a patch bump. A follow-up v2.5.0 PR can swap the JSON-parse sites to curl with PowerShell Invoke-WebRequest fallback when ready. --- .claude/plugins/onebrain/.claude-plugin/plugin.json | 2 +- .claude/plugins/onebrain/skills/update/SKILL.md | 10 ++++++---- PLUGIN-CHANGELOG.md | 9 +++++++-- 3 files changed, 14 insertions(+), 7 deletions(-) diff --git a/.claude/plugins/onebrain/.claude-plugin/plugin.json b/.claude/plugins/onebrain/.claude-plugin/plugin.json index 575dc368..5241a9a2 100644 --- a/.claude/plugins/onebrain/.claude-plugin/plugin.json +++ b/.claude/plugins/onebrain/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "onebrain", - "version": "2.4.12", + "version": "2.4.13", "description": "OneBrain — Where human and AI thinking become one. A powerful thinking partner powered by AI synergy.", "author": { "name": "OneBrain Contributors" diff --git a/.claude/plugins/onebrain/skills/update/SKILL.md b/.claude/plugins/onebrain/skills/update/SKILL.md index 2dfc8f75..3c5f181a 100644 --- a/.claude/plugins/onebrain/skills/update/SKILL.md +++ b/.claude/plugins/onebrain/skills/update/SKILL.md @@ -19,9 +19,9 @@ Update OneBrain system files from GitHub to the latest version. 3. Read new version from repo's `plugin.json` on the mapped branch using `WebFetch` — never use `git` commands (they hang on Windows waiting for credentials): `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/.claude/plugins/onebrain/.claude-plugin/plugin.json` where `{branch}` is the mapped branch from step 2. - Parse the `version` field from the JSON response. + Parse the `version` field from the JSON response. (⚠️ JSON parsing — see Known Gotchas: WebFetch may summarize; use `curl -fsSL` if a version mismatch is suspected.) 4. If equal → say: ✅ Already up to date — v{X.X.X}. and stop -5. If newer → WebFetch `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/PLUGIN-CHANGELOG.md`; display before proceeding (do not skip or summarize): +5. If newer → WebFetch `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/PLUGIN-CHANGELOG.md`; display before proceeding (do not skip or summarize — and if the fetched content already looks paraphrased, re-fetch via `curl -fsSL`; see Known Gotchas): ``` ────────────────────────────────────────────────────────────── @@ -73,7 +73,7 @@ where `{branch}` is the branch mapped from `update_channel` in step 2 of Version Steps: 1. **Early bootstrap — download the latest SKILL.md:** - Use WebFetch + Write to download this file from GitHub and write to vault. `{vault_root}` = the vault's absolute path (the current working directory — the directory containing `.claude/`). + Use WebFetch + Write to download this file from GitHub and write to vault. `{vault_root}` = the vault's absolute path (the current working directory — the directory containing `.claude/`). (⚠️ If the written SKILL.md looks paraphrased or shorter than the source, refetch via `curl -fsSL` — see Known Gotchas. A summarized self-update bootstrap corrupts the instructions the agent is about to follow.) Raw URL: `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/.claude/plugins/onebrain/{path}` @@ -105,7 +105,7 @@ Steps: and `[agent_folder]/context/` → `[archive_folder]/[agent_folder]/context.YYYY-MM-DD/` (if context/ exists). The `[agent_folder]` literal under `[archive_folder]/` mirrors the source's relative path so users who remapped `folders.agent` in vault.yml see backups land in the matching subfolder. b. Sync remaining files — run these two sub-steps in parallel, then clean cache after both complete: - **Full vault sync:** run `onebrain vault-sync --branch {branch}` (the CLI defaults the vault root to the current working directory; explicit `"$PWD"` was Bash-only and broke on PowerShell/cmd). Downloads the full GitHub tarball, syncs plugin folder (with stale file cleanup), copies README.md/CONTRIBUTING.md/CHANGELOG.md/PLUGIN-CHANGELOG.md to vault root (overwrite), merges CLAUDE.md/GEMINI.md/AGENTS.md (vault is primary; injects new repo `@` imports only), pins plugin to vault, and clears plugin cache. - - **Settings merge:** WebFetch `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/.claude/settings.json`, then merge into `[vault]/.claude/settings.json`. Merge strategy (never overwrite, always additive): `permissions.allow` → union; `enabledPlugins` → merge keys (skip any `onebrain@*` key whose marketplace points to a `directory` source — repo-dev-only, not valid in vault context); `extraKnownMarketplaces` → skip (repo-dev-only config, not valid in vault context); `hooks` → skip (handled by migration Step 6). + - **Settings merge:** WebFetch `https://raw.githubusercontent.com/onebrain-ai/onebrain/{branch}/.claude/settings.json`, then merge into `[vault]/.claude/settings.json` (⚠️ JSON parsing — refetch via `curl -fsSL` if the response is not valid JSON; see Known Gotchas). Merge strategy (never overwrite, always additive): `permissions.allow` → union; `enabledPlugins` → merge keys (skip any `onebrain@*` key whose marketplace points to a `directory` source — repo-dev-only, not valid in vault context); `extraKnownMarketplaces` → skip (repo-dev-only config, not valid in vault context); `hooks` → skip (handled by migration Step 6). c. Once all step 3b sub-steps are complete, load `[vault]/.claude/plugins/onebrain/skills/update/references/migration-steps.md` and run all 8 migration steps d. Bump `plugin.json` version to `{new}` (last — completion signal; do not bump early) 4. Write migration log. Follow `../_shared/audit-log-format.md` (canonical frontmatter umbrella tag, failure mode) with these specifics for `/update`: @@ -200,3 +200,5 @@ Dry run complete — {N} files would be created, {M} modified, {P} deleted. - **Failure recovery path:** If interrupted before step 3d (plugin.json bump), re-running /update will retry from step 1. The early bootstrap (download SKILL.md) is idempotent — safe to repeat. - **CLI update delegates to `onebrain update`.** Do not call `npm install -g @onebrain-ai/cli` or `bun install -g @onebrain-ai/cli` from this skill — `onebrain update` is the single source of truth for the CLI bump (version check, package-manager choice, validation). Raw npm/bun is reserved for first-time CLI bootstrap, which is a README/install-script concern, not a `/update` concern. + +- **WebFetch may return summarized markdown — use `curl -fsSL` when raw content is required.** WebFetch can post-process content even with `raw.githubusercontent.com` URLs and explicit "return verbatim" prompts. Anywhere `/update` parses JSON (`plugin.json`, `settings.json`) or downloads/displays files verbatim (`PLUGIN-CHANGELOG.md`, `SKILL.md`), prefer `curl -fsSL ` via the Bash tool instead. Symptoms of a summarized fetch: version mismatch on `plugin.json`, truncated/paraphrased changelog display, corrupted SKILL.md after self-update bootstrap. diff --git a/PLUGIN-CHANGELOG.md b/PLUGIN-CHANGELOG.md index 4a70b6ff..6db69195 100644 --- a/PLUGIN-CHANGELOG.md +++ b/PLUGIN-CHANGELOG.md @@ -1,6 +1,6 @@ --- -latest_version: 2.4.12 -released: 2026-05-13 +latest_version: 2.4.13 +released: 2026-05-19 --- # Plugin Changelog @@ -11,6 +11,11 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). > **Versioning:** Plugin version is tracked in `plugin.json`. Bump when ANY harness config changes — skills, agents, hooks, INSTRUCTIONS, Gemini settings, slash commands, etc. > For CLI binary (`@onebrain-ai/cli`) changes, see [CHANGELOG.md](CHANGELOG.md). +## v2.4.13 — 2026-05-19 + +- docs(update): add Known Gotcha about WebFetch returning summarized markdown — recommend `curl -fsSL` for raw-content fetches (`plugin.json`/`settings.json` JSON parsing, `PLUGIN-CHANGELOG.md` verbatim display, `SKILL.md` self-update bootstrap). Symptoms section helps diagnose silent corruption from summarized fetches. +- docs(update): add inline ⚠️ pointers at the four WebFetch call sites (version check, changelog display, SKILL.md bootstrap, settings.json merge) directing readers to the Known Gotcha when raw-content semantics matter — closes the "warning lives at the bottom but step prose says use WebFetch" coherence gap. + ## v2.4.12 — 2026-05-13 - docs(INSTRUCTIONS): rewrite "Headless invocation" section to describe the real contract — scheduler now goes through `onebrain run-skill` which spawns `claude -p "/skill args" --add-dir ` (the previous `claude --vault X --skill /name --headless` shape was never implemented on any binary; see CLI v2.3.3 for the fix)