LINBEE-30104 | docs: set the token in settings.json env instead of a shell export

README.md

@@ -39,13 +39,17 @@ AI agents write code the same way whether the target is a calm, well-tested modu
 /plugin install agentic-advisor@linearb-ai
 ```
 
-**2. Create a LinearB API token** (**LinearB → Settings → API Tokens → Create API Token**, [step-by-step guide](https://linearb.helpdocs.io/article/79fmogrxw3-how-to-generate-release-api-tokens)) and export it:
+**2. Create a LinearB API token** (**LinearB → Settings → API Tokens → Create API Token**, [step-by-step guide](https://linearb.helpdocs.io/article/79fmogrxw3-how-to-generate-release-api-tokens)) and add it to `~/.claude/settings.json` under `env`, so every Claude Code session gets it however you launch it:
 
-```sh
-export LINEARB_API_TOKEN="<your LinearB API token>"
+```json
+{
+  "env": {
+    "LINEARB_API_TOKEN": "<your LinearB API token>"
+  }
+}
 ```
 
-**3. Restart Claude Code** from that shell. Hooks and the skill read the environment at launch.
+**3. Restart Claude Code.** Hooks and the skill read the environment at launch.
 
 <details>
 <summary><strong>Prefer one terminal command?</strong></summary>
@@ -54,7 +58,7 @@ export LINEARB_API_TOKEN="<your LinearB API token>"
 claude plugin marketplace add linear-b/agent-plugins && claude plugin install agentic-advisor@linearb-ai
 ```
 
-Then run `/reload-plugins` in Claude Code, or restart it if you just exported the token.
+Then run `/reload-plugins` in Claude Code, or restart it if you just added the token.
 </details>
 
 <details>

plugins/agentic-advisor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-advisor",
-  "version": "1.4.3",
+  "version": "1.4.4",
   "description": "Before writing code, grades how fragile the target is from LinearB health signals + local git history (rework, incidents, fix/revert density, code ownership) and holds the agent to a matching effort level (LOW/MEDIUM/HIGH) — lean on calm repos, defensive on fragile ones. Auto-triggers via a bundled hook and can report each effort decision to your LinearB org as usage telemetry.",
   "author": {
     "name": "LinearB",

plugins/agentic-advisor/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [1.4.4] - 2026-10-15
+
+### Changed
+
+- Setup now puts `LINEARB_API_TOKEN` in `~/.claude/settings.json` under `env` instead of a shell `export`, so every Claude Code session gets it however it is launched (the docs and the skill's missing-token hint both say so).
+
 ## [1.4.3] - 2026-10-15
 
 ### Fixed

plugins/agentic-advisor/README.md

@@ -13,7 +13,7 @@ At the start of a code task, a bundled hook auto-invokes the `agentic-advisor` s
 /plugin install agentic-advisor@linearb-ai
 ```
 
-Then export `LINEARB_API_TOKEN` (see [Setup](#usage-telemetry-on-by-default)) and restart Claude Code — hooks load at startup.
+Then add `LINEARB_API_TOKEN` to `~/.claude/settings.json` under `env` (see [Setup](#usage-telemetry-on-by-default)) and restart Claude Code — hooks load at startup.
 
 ## What you'll see
 
@@ -65,19 +65,21 @@ Decision events also carry `tags.evidence` (the verdict's evidence snippet), `ta
 
 All of this is sent **only to your own LinearB org** — the org your `LINEARB_API_TOKEN` belongs to — over HTTPS to your LinearB API (`public-api.linearb.io` unless you set `LINEARB_API_URL`); nothing goes anywhere else. It's the same data you can already see in your LinearB workspace, readable there by the metric name `agentic_advisor.effort_decision` (group by contributor / repo / effort level).
 
-**Setup** — this plugin reads LinearB entirely through the **public API** (no MCP connector). Create an org-scoped API token (**LinearB → Settings → API Tokens → Create API Token**) and export it — the *same* token both reads health signals and reports telemetry:
+**Setup** — this plugin reads LinearB entirely through the **public API** (no MCP connector). Create an org-scoped API token (**LinearB → Settings → API Tokens → Create API Token**) and add it to `~/.claude/settings.json` under `env`; the *same* token both reads health signals and reports telemetry. Rolling out to the whole org? Put the same `env` block in your Claude Code managed settings instead (see the repo README).
 
-```sh
-export LINEARB_API_TOKEN="<your LinearB API token>"
-# On-prem or regional LinearB? Point the plugin at your API (default https://public-api.linearb.io):
-# export LINEARB_API_URL="https://<your-linearb-api-host>"
+```json
+{
+  "env": {
+    "LINEARB_API_TOKEN": "<your LinearB API token>"
+  }
+}
 ```
 
-Then **launch Claude Code from a shell that has it exported** (hooks and the skill read the env at launch — a token added to an already-running session isn't seen until you restart; if you rely on `~/.zshrc`, start Claude from an interactive shell). The token is handed to `curl` on stdin, never as a command-line argument, and it is never printed or logged. **Without a token the skill degrades to MEDIUM effort** (it never blocks).
+On-prem or regional LinearB? Also add `"LINEARB_API_URL": "https://<your-linearb-api-host>"` (default `https://public-api.linearb.io`). Then **restart Claude Code** (hooks and the skill read the env at launch). If your org's managed settings already set `LINEARB_API_TOKEN`, that value wins over yours. The token is handed to `curl` on stdin, never as a command-line argument, and it is never printed or logged. **Without a token the skill degrades to MEDIUM effort** (it never blocks).
 
 ## Requirements
 
-- **`LINEARB_API_TOKEN`** exported (see Setup) — used for both reading signals and reporting. Without it, the skill degrades to MEDIUM rather than failing.
+- **`LINEARB_API_TOKEN`** set (see Setup) — used for both reading signals and reporting. Without it, the skill degrades to MEDIUM rather than failing.
 - `jq`, `git`, and `curl` on PATH (used by the bundled hooks and the skill's API calls).
 - `python3` (optional): without it grades are still reported, but token counts and grading time are left out.
 - No MCP connector required.

plugins/agentic-advisor/skills/agentic-advisor/SKILL.md

@@ -38,7 +38,7 @@ set -o pipefail   # with curl -f, a failed request fails the whole pipeline inst
 
 **A failed call is not an empty result.** With `-f`, any HTTP 4xx/5xx or timeout makes `curl` exit non-zero (e.g. `curl: (22) The requested URL returned error: 401`). Treat that signal as **unavailable** — a failed repositories call is not "repo not found", a failed measurements call is not "dormant" — and **never grade LOW from missing data.** **HTTP 401/403 means the token is invalid or expired:** stop calling, grade **MEDIUM (signals unavailable)**, and tell the user to refresh `LINEARB_API_TOKEN`.
 
-**Token gate:** if `LINEARB_API_TOKEN` is empty, do **not** call — grade **MEDIUM** with the evidence `LINEARB_API_TOKEN not set`, print the verdict, then tell the user in one plain sentence that LinearB signals and usage reporting stay off until they export `LINEARB_API_TOKEN` in the shell they start Claude Code from and restart it (see the plugin README). Then continue. Never block the task. The same token authenticates both these reads and the optional reporter hook. On any timeout or non-2xx, treat that one signal as unavailable rather than failing the task.
+**Token gate:** if `LINEARB_API_TOKEN` is empty, do **not** call — grade **MEDIUM** with the evidence `LINEARB_API_TOKEN not set`, print the verdict, then tell the user in one plain sentence that LinearB signals and usage reporting stay off until they add `LINEARB_API_TOKEN` to `~/.claude/settings.json` under `env` and restart Claude Code (see the plugin README). Then continue. Never block the task. The same token authenticates both these reads and the optional reporter hook. On any timeout or non-2xx, treat that one signal as unavailable rather than failing the task.
 
 ## Before Gathering Signals (cheap exits)