@yagni-app/code-staging 1.0.6-staging.1249.1 → 1.0.6-staging.1257.1

package/README.md

@@ -173,62 +173,87 @@ environment is recorded in `~/.yagni-code/config.json`. A pre-profiles
 
 ### OTel export (opt-in)
 
-Point sessions at **your own** OpenTelemetry collector (Datadog Agent, Grafana
-Alloy, an OTLP-native backend) and every session — including `/go` stage
-children and subagents — emits a per-prompt span tree: interaction → LLM
-request → tool calls, following the OTel GenAI semantic conventions. Nothing is
-exported unless you configure an endpoint.
-
-Enable it one of four ways (first match wins):
-
-- `OTEL_EXPORTER_OTLP_ENDPOINT=…` in the environment (a personal override —
-  handy for pointing one session at a scratch collector), or
-- `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=…` in the environment — the per-signal
-  form Claude Code setups use (e.g.
-  `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://otlp.datadoghq.com/v1/traces`
-  with `OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf`); the launcher
-  bridges it to the generic var pi-otel reads, so a Claude Code OTel env
-  lights up YAGNI Code traces with no extra config, or
+Point sessions at **your own** OpenTelemetry collector (Datadog, Grafana
+Cloud, a Datadog Agent or Grafana Alloy, any OTLP-native backend) and every
+session — including `/go` stage children and subagents — exports three
+signals in the shape Claude Code's telemetry uses, under a `yagni_code`
+prefix instead of `claude_code`:
+
+- **Traces:** a per-prompt span tree, `yagni_code.interaction` →
+  `yagni_code.llm_request` and `yagni_code.tool`, carrying both the flat
+  Claude Code attributes (`model`, `input_tokens`, `cost_usd`, `tool_name`)
+  and the OTel GenAI conventions (`gen_ai.*`) that LLM-observability
+  products read.
+- **Metrics:** `yagni_code.session.count`, `token.usage` (by `type` and
+  `model`), `cost.usage`, `lines_of_code.count`, `commit.count`,
+  `pull_request.count`, `code_edit_tool.decision`, `active_time.total`.
+- **Log events:** `user_prompt`, `assistant_response`, `api_request`,
+  `api_error`, `tool_result`, `tool_decision`, `permission_mode_changed`
+  (as `event.name`, body `yagni_code.<name>`), with `session.id`,
+  `organization.id`, `terminal.type`, and a per-prompt `prompt.id`.
+
+Nothing is exported unless you configure an endpoint. Enable it one of three
+ways (first match wins):
+
+- the standard OTel env in your shell — the generic
+  `OTEL_EXPORTER_OTLP_ENDPOINT` (a base URL; `/v1/<signal>` is appended for
+  http transports) or the per-signal
+  `OTEL_EXPORTER_OTLP_{TRACES,METRICS,LOGS}_ENDPOINT` a Claude Code setup
+  already carries — so a machine configured for Claude Code lights up with
+  no extra config (with per-signal endpoints only, exactly those signals
+  export; nothing falls back to a localhost collector), or
 - **workspace settings** (the zero-setup path): a workspace admin sets the
   endpoint, protocol, and any collector headers (e.g. a Datadog API key) once
-  in the web app under Settings → YAGNI Code → Trace export. Every session in
-  the workspace picks it up at launch — nothing to install or configure on
-  developer machines. Header values are encrypted at rest server-side and the
-  launch-time copy is cached at mode `0600`, the same posture as your device
-  token. Or,
-- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` to the repo's
-  `.pi/settings.json` so one repo's sessions export without per-machine setup.
-
-Standard OTel env vars are honored (`OTEL_EXPORTER_OTLP_PROTOCOL`,
-`OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_SERVICE_NAME` — defaults to `yagni-code`),
-and `PI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
-export state and probes the endpoint live (unreachable → a warning with a
-hint, never an exit-code flip).
-
-Two recipes for common collectors:
-
-- **Datadog, direct SaaS (no agent):** endpoint
-  `https://otlp.datadoghq.com/v1/traces` (US1; other sites have their own
-  host — `otlp.us3.datadoghq.com`, `otlp.us5.datadoghq.com`,
-  `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`), protocol `http/protobuf`
-  (Datadog's direct trace intake does not accept gRPC), header
-  `dd-api-key=<your Datadog API key>`. Use the full path, not `/v1/` — the
-  endpoint is passed through verbatim, no path is appended for you.
+  in the web app under Settings → YAGNI Code → Telemetry export. Every
+  session in the workspace picks it up at launch — nothing to install or
+  configure on developer machines. Header values are encrypted at rest
+  server-side and the launch-time copy is cached at mode `0600`, the same
+  posture as your device token. Or,
+- commit `{ "otel": { "endpoint": "http://<collector>:4317" } }` (optionally
+  with `protocol`, `headers`, `serviceName`) to the repo's `.pi/settings.json`
+  so one repo's sessions export without per-machine setup. Header values
+  must not contain commas (they travel as a comma-separated list); one that
+  does is dropped.
+
+The rest of the standard OTel env is honored the way Claude Code honors it:
+`OTEL_EXPORTER_OTLP_PROTOCOL` (and per-signal), `OTEL_EXPORTER_OTLP_HEADERS`
+(and per-signal), `OTEL_SERVICE_NAME` (defaults to `yagni-code`),
+`OTEL_RESOURCE_ATTRIBUTES`, `OTEL_{METRICS,LOGS,TRACES}_EXPORTER=none` to
+switch one signal off, `OTEL_METRIC_EXPORT_INTERVAL` /
+`OTEL_LOGS_EXPORT_INTERVAL`, `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE`
+(default `delta`), and the `OTEL_METRICS_INCLUDE_*` cardinality flags.
+`YAGNI_OTEL_DISABLED=1` is the kill switch. `yagni doctor` shows the current
+export state and sends one real record per signal, printing the collector's
+own verdict (a 403 is a bad key, a 404 a bad path or site).
+
+Three recipes for common collectors:
+
+- **Datadog, direct SaaS (no agent):** endpoint `https://otlp.datadoghq.com`
+  (US1; other sites have their own host — `otlp.us3.datadoghq.com`,
+  `otlp.us5.datadoghq.com`, `otlp.datadoghq.eu`, `otlp.ap1.datadoghq.com`),
+  protocol `http/protobuf` (Datadog's direct intake does not accept gRPC),
+  header `dd-api-key=<your Datadog API key>`. Add `dd-otlp-source=llmobs`
+  (the workspace preset does) to have the traces routed into LLM
+  Observability as well as APM; the launcher scopes that header to the
+  traces request. Traces show in APM under service `yagni-code`, metrics
+  under `yagni_code.*`, events in Log Explorer as `service:yagni-code`.
 - **Datadog Agent:** endpoint `http://<agent-host>:4317`, protocol `grpc`, no
   key (the agent forwards with its own). OTLP ingest ships in the agent but
   is off by default — enable it with
   `otlp_config.receiver.protocols.grpc.endpoint: 0.0.0.0:4317` in
   `datadog.yaml`.
-- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-…-0.grafana.net:443/otlp`,
-  protocol `http/protobuf`, header `authorization=<the raw MTgx… value>` (the
-  `Basic ` scheme is added for you).
+- **Grafana Cloud:** endpoint `https://otlp-gateway-prod-<region>.grafana.net/otlp`
+  (the base URL from your stack's OTLP page — signals go to `/otlp/v1/traces`
+  and friends), protocol `http/protobuf`, header `authorization=<the raw
+  MTgx… value>` (the `Basic ` scheme is added for you).
 
 Two things are enforced and not configurable:
 
-- **Metadata only.** Token counts, cost, tier, finish reasons, and tool-call
-  ids export; prompt and response text never do — a settings file or env var
-  asking for content capture is overridden.
-- **Cost is your contracted rate.** `pi.cost.usd` is computed from your
+- **Metadata only.** Token counts, cost, tier, durations, tool names, and
+  payload sizes export; prompt text, model output, tool arguments, and tool
+  results never do — `OTEL_LOG_USER_PROMPTS` and `OTEL_LOG_TOOL_DETAILS` are
+  deliberately not honored.
+- **Cost is your contracted rate.** `cost_usd` is computed from your
   workspace's tier rate card, and the exported model name is the opaque tier
   id (`advanced`, `peak`, …), so traces never fingerprint the backing model.
 

package/dist/claudeCompat.d.ts

@@ -34,6 +34,23 @@ export declare const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
 export declare const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
 /** `.claude/rules` dirs for the extension's rules injection (delimiter-joined). */
 export declare const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+/**
+ * Plugin MCP servers for the extension's MCP client: a JSON array of
+ * `{ plugin, sourcePath, gated, servers }`. `${CLAUDE_PLUGIN_ROOT}` is already
+ * expanded to the plugin's install dir; other `${VAR}` references are left for
+ * the extension's normal env expansion. `gated` marks servers that came from
+ * repo config (repo marketplace, project-scope `enabledPlugins`) and must pass
+ * the same approval the repo's `.mcp.json` would.
+ */
+export declare const CLAUDE_PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+export interface PluginMcpEnvEntry {
+    plugin: string;
+    sourcePath: string;
+    gated: boolean;
+    servers: Record<string, unknown>;
+}
+/** The MCP payload entries for a set of plugins (those without servers are skipped). */
+export declare function pluginMcpEntries(plugins: PluginAssets[], gated: boolean): PluginMcpEnvEntry[];
 export interface ClaudeAssetDirs {
     skills: string | null;
     commands: string | null;
@@ -61,6 +78,9 @@ export interface ClaudeCompatDecision {
     /** `.claude/rules` dirs, user first so project rules win in the prompt. */
     userRulesDirs: string[];
     projectRulesDirs: string[];
+    /** Plugin MCP servers, split by the same trust posture (project ones are approval-gated too). */
+    userMcp: PluginMcpEnvEntry[];
+    projectMcp: PluginMcpEnvEntry[];
     /** Ask the user for a trust decision before wiring any project content. */
     needsPrompt: boolean;
 }

package/dist/claudeCompat.js

@@ -32,11 +32,50 @@ import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmdirSyn
 import { homedir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { discoverClaudePlugins } from "./claudePlugins.js";
+import { pluginsHome, readLedger } from "./pluginStore.js";
 export const CLAUDE_COMPAT_DISABLE_ENV = "YAGNI_DISABLE_CLAUDE_COMPAT";
 /** Plugin `agents/` dirs for the extension's subagent discovery (delimiter-joined). */
 export const CLAUDE_AGENT_DIRS_ENV = "YAGNI_CLAUDE_AGENT_DIRS";
 /** `.claude/rules` dirs for the extension's rules injection (delimiter-joined). */
 export const CLAUDE_RULES_DIRS_ENV = "YAGNI_CLAUDE_RULES_DIRS";
+/**
+ * Plugin MCP servers for the extension's MCP client: a JSON array of
+ * `{ plugin, sourcePath, gated, servers }`. `${CLAUDE_PLUGIN_ROOT}` is already
+ * expanded to the plugin's install dir; other `${VAR}` references are left for
+ * the extension's normal env expansion. `gated` marks servers that came from
+ * repo config (repo marketplace, project-scope `enabledPlugins`) and must pass
+ * the same approval the repo's `.mcp.json` would.
+ */
+export const CLAUDE_PLUGIN_MCP_ENV = "YAGNI_CLAUDE_PLUGIN_MCP";
+const PLUGIN_ROOT_VAR = "${CLAUDE_PLUGIN_ROOT}";
+function expandPluginRoot(value, root) {
+    if (typeof value === "string")
+        return value.split(PLUGIN_ROOT_VAR).join(root);
+    if (Array.isArray(value))
+        return value.map((v) => expandPluginRoot(v, root));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value))
+            out[k] = expandPluginRoot(v, root);
+        return out;
+    }
+    return value;
+}
+/** The MCP payload entries for a set of plugins (those without servers are skipped). */
+export function pluginMcpEntries(plugins, gated) {
+    const out = [];
+    for (const plugin of plugins) {
+        if (!plugin.mcp)
+            continue;
+        out.push({
+            plugin: plugin.key,
+            sourcePath: plugin.mcp.sourcePath,
+            gated,
+            servers: expandPluginRoot(plugin.mcp.servers, plugin.root),
+        });
+    }
+    return out;
+}
 function dirsToArgv(dirs) {
     const argv = [];
     if (dirs.skills)
@@ -60,7 +99,8 @@ export function decideClaudeCompat(probe) {
     const projectArgv = [...dirsToArgv(probe.project), ...pluginsToArgv(probe.projectPlugins)];
     const projectAgentDirs = probe.projectPlugins.flatMap((p) => p.agentDirs);
     const projectRulesDirs = probe.project.rules ? [probe.project.rules] : [];
-    const hasProjectContent = projectArgv.length > 0 || projectAgentDirs.length > 0 || projectRulesDirs.length > 0;
+    const projectMcp = pluginMcpEntries(probe.projectPlugins, true);
+    const hasProjectContent = projectArgv.length > 0 || projectAgentDirs.length > 0 || projectRulesDirs.length > 0 || projectMcp.length > 0;
     return {
         userArgv: [...dirsToArgv(probe.user), ...pluginsToArgv(probe.userPlugins)],
         projectArgv,
@@ -68,6 +108,8 @@ export function decideClaudeCompat(probe) {
         projectAgentDirs,
         userRulesDirs: probe.user.rules ? [probe.user.rules] : [],
         projectRulesDirs,
+        userMcp: pluginMcpEntries(probe.userPlugins, false),
+        projectMcp,
         needsPrompt: probe.interactive && hasProjectContent && probe.projectTrust === null,
     };
 }
@@ -210,7 +252,11 @@ export async function claudeCompatArgs(deps) {
     const projectTrust = readTrustDecision(deps.agentDir, deps.cwd);
     let plugins;
     try {
-        plugins = discoverClaudePlugins({ cwd: deps.cwd, homeDir: home });
+        plugins = discoverClaudePlugins({
+            cwd: deps.cwd,
+            homeDir: home,
+            yagniLedger: readLedger(pluginsHome(env, home)),
+        });
     }
     catch {
         plugins = { user: [], project: [] };
@@ -246,11 +292,17 @@ export async function claudeCompatArgs(deps) {
         ...decision.userRulesDirs,
         ...(trusted === true ? decision.projectRulesDirs : []),
     ];
+    const mcpEntries = [
+        ...decision.userMcp,
+        ...(trusted === true ? decision.projectMcp : []),
+    ];
     const extraEnv = {};
     if (agentDirs.length > 0)
         extraEnv[CLAUDE_AGENT_DIRS_ENV] = agentDirs.join(delimiter);
     if (rulesDirs.length > 0)
         extraEnv[CLAUDE_RULES_DIRS_ENV] = rulesDirs.join(delimiter);
+    if (mcpEntries.length > 0)
+        extraEnv[CLAUDE_PLUGIN_MCP_ENV] = JSON.stringify(mcpEntries);
     return { argv, env: extraEnv };
 }
 /** Whether pi's trust file exists yet (used only for messaging). */

package/dist/claudePlugins.d.ts

@@ -17,10 +17,19 @@
  *    relative-path source loads on the project side, unless explicitly
  *    disabled via `enabledPlugins`.
  *
- * Deliberately NOT here: network installation of any kind, plugin hooks, MCP
- * servers (standard MCP support lives in `src/mcpCommand.ts` + the extension's
- * `mcp/` module — see `yagni mcp --help`), LSP servers, themes, output styles.
- * Discovery is read-only.
+ * Three sources, first wins on the same `name@marketplace`:
+ *
+ * 0. YAGNI's own ledger (`~/.yagni-code/plugins`, written by `yagni plugin`;
+ *    see pluginStore.ts) — handed in by the caller as `yagniLedger`.
+ * 1. Claude Code's ledger + `enabledPlugins` (mirrored read-only).
+ * 2. The repo's own `.claude-plugin/marketplace.json`.
+ *
+ * Plugin MCP servers (`.mcp.json` at the plugin root, or the manifest's
+ * `mcpServers`) are collected here and bridged by the launcher into the
+ * extension's MCP client (see claudeCompat.ts). Deliberately NOT here:
+ * network installation (that is pluginStore.ts), plugin hooks, LSP servers,
+ * themes, output styles — those are reported as `unsupported` so `yagni
+ * plugin list` can say so. Discovery is read-only.
  *
  * Everything is fail-soft: malformed JSON, missing dirs, or hostile path
  * entries degrade to "that plugin absent" — never a failed launch. Path
@@ -28,9 +37,21 @@
  * inside the expected root) so a malicious `source` or component override
  * cannot reach outside its repo/plugin.
  */
+import type { PluginLedger } from "./pluginStore.js";
+export type PluginOrigin = "yagni" | "claude-code" | "repo-marketplace";
+export interface PluginMcp {
+    /** File the servers came from (plugin `.mcp.json` or `plugin.json`). */
+    sourcePath: string;
+    /** Raw `mcpServers` map; validated by the extension, `${CLAUDE_PLUGIN_ROOT}` expanded by the launcher. */
+    servers: Record<string, unknown>;
+}
 export interface PluginAssets {
     /** The plugin's name (marketplace-entry name — the `enabledPlugins` key half). */
     name: string;
+    /** `name@marketplace` when the marketplace is known; else the bare name. */
+    key: string;
+    origin: PluginOrigin;
+    version: string | null;
     /** Absolute plugin root directory. */
     root: string;
     /** Dirs (or a lone root SKILL.md file) for pi `--skill`. */
@@ -39,6 +60,14 @@ export interface PluginAssets {
     commandPaths: string[];
     /** Dirs of Claude Code-format agent markdown for subagent discovery. */
     agentDirs: string[];
+    mcp: PluginMcp | null;
+    /** Component kinds present in the plugin that YAGNI Code does not bridge. */
+    unsupported: string[];
+}
+export interface PluginMeta {
+    key?: string;
+    origin?: PluginOrigin;
+    version?: string | null;
 }
 export interface DiscoveredClaudePlugins {
     /** Enabled via the user's own `~/.claude` config; loads without ceremony. */
@@ -71,9 +100,18 @@ export interface EnableState {
 export declare function readEnabledPlugins(cwd: string, homeDir: string): Map<string, EnableState>;
 /** `~/.claude/plugins/known_marketplaces.json` → marketplace name → checkout dir. */
 export declare function readKnownMarketplaces(homeDir: string): Map<string, string>;
+/**
+ * Names and versions from marketplace/plugin JSON become path segments under
+ * the plugin home (`cache/<mp>/<plugin>/<version>`), so they must be plain
+ * single segments: no separators, no `.`/`..`, nothing starting with `-`.
+ */
+export declare const SAFE_SEGMENT: RegExp;
+export declare function isSafeSegment(value: unknown): value is string;
 export interface MarketplaceEntry {
     name: string;
     source: unknown;
+    version?: string;
+    description?: string;
 }
 export interface Marketplace {
     name: string;
@@ -98,10 +136,12 @@ export declare function resolveLocalPluginRoot(mp: Marketplace, entry: Marketpla
  * discovery reads whole dirs), root `SKILL.md` fallback. Null when the plugin
  * has nothing we can bridge.
  */
-export declare function pluginAssets(root: string, name: string): PluginAssets | null;
+export declare function pluginAssets(root: string, name: string, meta?: PluginMeta): PluginAssets | null;
 export interface DiscoverPluginsDeps {
     cwd: string;
     homeDir: string;
+    /** YAGNI's own ledger (`readLedger` from pluginStore.ts); wins over the mirrored Claude Code state. */
+    yagniLedger?: PluginLedger;
 }
 /**
  * All locally-present Claude Code plugin content relevant to `cwd`, split by

package/dist/claudePlugins.js

@@ -17,10 +17,19 @@
  *    relative-path source loads on the project side, unless explicitly
  *    disabled via `enabledPlugins`.
  *
- * Deliberately NOT here: network installation of any kind, plugin hooks, MCP
- * servers (standard MCP support lives in `src/mcpCommand.ts` + the extension's
- * `mcp/` module — see `yagni mcp --help`), LSP servers, themes, output styles.
- * Discovery is read-only.
+ * Three sources, first wins on the same `name@marketplace`:
+ *
+ * 0. YAGNI's own ledger (`~/.yagni-code/plugins`, written by `yagni plugin`;
+ *    see pluginStore.ts) — handed in by the caller as `yagniLedger`.
+ * 1. Claude Code's ledger + `enabledPlugins` (mirrored read-only).
+ * 2. The repo's own `.claude-plugin/marketplace.json`.
+ *
+ * Plugin MCP servers (`.mcp.json` at the plugin root, or the manifest's
+ * `mcpServers`) are collected here and bridged by the launcher into the
+ * extension's MCP client (see claudeCompat.ts). Deliberately NOT here:
+ * network installation (that is pluginStore.ts), plugin hooks, LSP servers,
+ * themes, output styles — those are reported as `unsupported` so `yagni
+ * plugin list` can say so. Discovery is read-only.
  *
  * Everything is fail-soft: malformed JSON, missing dirs, or hostile path
  * entries degrade to "that plugin absent" — never a failed launch. Path
@@ -151,10 +160,20 @@ export function readKnownMarketplaces(homeDir) {
     }
     return out;
 }
+// ── marketplace file ────────────────────────────────────────────────────────
+/**
+ * Names and versions from marketplace/plugin JSON become path segments under
+ * the plugin home (`cache/<mp>/<plugin>/<version>`), so they must be plain
+ * single segments: no separators, no `.`/`..`, nothing starting with `-`.
+ */
+export const SAFE_SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+export function isSafeSegment(value) {
+    return typeof value === "string" && SAFE_SEGMENT.test(value);
+}
 /** Parse `<root>/.claude-plugin/marketplace.json`; null when absent/unusable. */
 export function readMarketplace(root) {
     const parsed = readJsonObject(join(root, ".claude-plugin", "marketplace.json"));
-    if (!parsed || typeof parsed.name !== "string" || parsed.name.length === 0)
+    if (!parsed || !isSafeSegment(parsed.name))
         return null;
     if (!Array.isArray(parsed.plugins))
         return null;
@@ -166,10 +185,16 @@ export function readMarketplace(root) {
     for (const item of parsed.plugins) {
         if (!item || typeof item !== "object" || Array.isArray(item))
             continue;
-        const name = item.name;
-        if (typeof name !== "string" || name.length === 0)
+        const entry = item;
+        const name = entry.name;
+        if (!isSafeSegment(name))
             continue;
-        plugins.push({ name, source: item.source });
+        plugins.push({
+            name,
+            source: entry.source,
+            ...(isSafeSegment(entry.version) ? { version: entry.version } : {}),
+            ...(typeof entry.description === "string" ? { description: entry.description } : {}),
+        });
     }
     return { name: parsed.name, root, pluginRoot, plugins };
 }
@@ -212,13 +237,17 @@ function asStringArray(value) {
  * discovery reads whole dirs), root `SKILL.md` fallback. Null when the plugin
  * has nothing we can bridge.
  */
-export function pluginAssets(root, name) {
+export function pluginAssets(root, name, meta = {}) {
     if (!isDirectory(root))
         return null;
-    const manifest = readJsonObject(join(root, ".claude-plugin", "plugin.json")) ?? {};
+    const manifestPath = join(root, ".claude-plugin", "plugin.json");
+    const manifest = readJsonObject(manifestPath) ?? {};
+    // Default component locations go through the same containment check as
+    // manifest-declared ones: a `skills` symlink pointing outside the plugin
+    // must not hand that directory to pi.
     const skillPaths = [];
-    const defaultSkills = join(root, "skills");
-    if (isDirectory(defaultSkills))
+    const defaultSkills = containedExistingPath(root, "skills");
+    if (defaultSkills && isDirectory(defaultSkills))
         skillPaths.push(defaultSkills);
     const manifestSkills = asStringArray(manifest.skills);
     for (const rel of manifestSkills) {
@@ -227,8 +256,8 @@ export function pluginAssets(root, name) {
             skillPaths.push(contained);
     }
     if (skillPaths.length === 0 && manifestSkills.length === 0) {
-        const rootSkill = join(root, "SKILL.md");
-        if (isFile(rootSkill))
+        const rootSkill = containedExistingPath(root, "SKILL.md");
+        if (rootSkill && isFile(rootSkill))
             skillPaths.push(rootSkill);
     }
     const componentPaths = (manifestValue, defaultDir) => {
@@ -242,14 +271,62 @@ export function pluginAssets(root, name) {
             }
             return out;
         }
-        const def = join(root, defaultDir);
-        return isDirectory(def) ? [def] : [];
+        const def = containedExistingPath(root, defaultDir);
+        return def && isDirectory(def) ? [def] : [];
     };
     const commandPaths = componentPaths(manifest.commands, "commands");
     const agentDirs = componentPaths(manifest.agents, "agents").filter(isDirectory);
-    if (skillPaths.length === 0 && commandPaths.length === 0 && agentDirs.length === 0)
+    const mcp = pluginMcp(root, manifest, manifestPath);
+    const unsupported = [];
+    if (manifest.hooks !== undefined || isDirectory(join(root, "hooks")) || isFile(join(root, "hooks.json")))
+        unsupported.push("hooks");
+    if (manifest.lspServers !== undefined || isFile(join(root, ".lsp.json")))
+        unsupported.push("lsp");
+    if (manifest.outputStyles !== undefined)
+        unsupported.push("output styles");
+    if (skillPaths.length === 0 && commandPaths.length === 0 && agentDirs.length === 0 && !mcp)
         return null;
-    return { name, root, skillPaths, commandPaths, agentDirs };
+    const version = meta.version ?? (typeof manifest.version === "string" ? manifest.version : null);
+    return {
+        name,
+        key: meta.key ?? name,
+        origin: meta.origin ?? "claude-code",
+        version,
+        root,
+        skillPaths,
+        commandPaths,
+        agentDirs,
+        mcp,
+        unsupported,
+    };
+}
+/**
+ * A plugin's MCP servers, per Claude Code's rules: the manifest `mcpServers`
+ * field (an inline map, or a contained path to a JSON file with one), else
+ * `.mcp.json` at the plugin root. Malformed → null (fail-soft).
+ */
+function pluginMcp(root, manifest, manifestPath) {
+    const field = manifest.mcpServers;
+    if (field && typeof field === "object" && !Array.isArray(field)) {
+        return { sourcePath: manifestPath, servers: field };
+    }
+    const candidates = [];
+    if (typeof field === "string") {
+        const contained = containedExistingPath(root, field);
+        if (contained && isFile(contained))
+            candidates.push(contained);
+    }
+    const rootFile = containedExistingPath(root, ".mcp.json");
+    if (rootFile && isFile(rootFile))
+        candidates.push(rootFile);
+    for (const path of candidates) {
+        const parsed = readJsonObject(path);
+        const servers = parsed?.mcpServers;
+        if (servers && typeof servers === "object" && !Array.isArray(servers)) {
+            return { sourcePath: path, servers: servers };
+        }
+    }
+    return null;
 }
 function resolveInstalledRoot(key, installed, marketplaces, realCwd) {
     const entries = (installed.get(key) ?? []).filter((e) => isDirectory(e.installPath));
@@ -295,14 +372,40 @@ export function discoverClaudePlugins(deps) {
         const user = [];
         const project = [];
         const seen = new Set();
+        // YAGNI-installed plugins are the user's own explicit action (`yagni
+        // plugin install`), so both scopes load without ceremony; a project-scope
+        // install applies only inside its repo.
+        for (const [key, entries] of Object.entries(deps.yagniLedger?.plugins ?? {})) {
+            const applicable = entries.filter((e) => {
+                if (!e.enabled || !isDirectory(e.installPath))
+                    return false;
+                if (e.scope === "user")
+                    return true;
+                const real = typeof e.projectPath === "string" ? realOrNull(e.projectPath) : null;
+                return !!real && (realCwd === real || realCwd.startsWith(real + sep));
+            });
+            const chosen = applicable.find((e) => e.scope === "project") ?? applicable[0];
+            if (!chosen)
+                continue;
+            const at = key.lastIndexOf("@");
+            const assets = pluginAssets(chosen.installPath, at > 0 ? key.slice(0, at) : key, {
+                key,
+                origin: "yagni",
+                version: chosen.version,
+            });
+            if (!assets)
+                continue;
+            seen.add(key);
+            user.push(assets);
+        }
         for (const [key, state] of enabled) {
-            if (!state.enabled)
+            if (!state.enabled || seen.has(key))
                 continue;
             const root = resolveInstalledRoot(key, installed, marketplaces, realCwd);
             if (!root)
                 continue;
             const at = key.lastIndexOf("@");
-            const assets = pluginAssets(root, at > 0 ? key.slice(0, at) : key);
+            const assets = pluginAssets(root, at > 0 ? key.slice(0, at) : key, { key, origin: "claude-code" });
             if (!assets)
                 continue;
             seen.add(key);
@@ -322,7 +425,12 @@ export function discoverClaudePlugins(deps) {
                     resolveInstalledRoot(key, installed, marketplaces, realCwd);
                 if (!root)
                     continue;
-                const assets = pluginAssets(root, entry.name);
+                const declared = entry.version;
+                const assets = pluginAssets(root, entry.name, {
+                    key,
+                    origin: "repo-marketplace",
+                    version: typeof declared === "string" ? declared : null,
+                });
                 if (!assets)
                     continue;
                 seen.add(key);

package/dist/cli.js

@@ -24,6 +24,7 @@ import { DISTRIBUTION } from "./distribution.js";
 import { connectCommand } from "./connectClaudeCode.js";
 import { goCommand } from "./goHeadless.js";
 import { mcpCommand } from "./mcpCommand.js";
+import { pluginCommand } from "./pluginCommand.js";
 import { login } from "./login.js";
 import { logout } from "./logout.js";
 import { tokenCommand } from "./token.js";
@@ -247,10 +248,10 @@ async function runDefault(passthroughArgs) {
     catch {
         compat = { argv: [], env: {} };
     }
-    // OTel export: load pi-otel only when an OTLP endpoint is configured — the
-    // user's env, the workspace's admin-set config (fetched fail-soft, cached),
-    // or the repo's .pi/settings.json, in that order. undefined keeps the
-    // launch untouched. See otel.ts for the policy.
+    // OTel export: on only when an OTLP endpoint is configured — the user's
+    // env, the workspace's admin-set config (fetched fail-soft, cached), or the
+    // repo's .pi/settings.json, in that order. undefined keeps the launch
+    // untouched. See otel.ts for the policy.
     const otel = await resolveOtelLaunchWithWorkspace({
         env: process.env,
         cwd: process.cwd(),
@@ -520,6 +521,10 @@ export const HELP_TEXT = [
     "                           add-from-claude, and more — run `yagni mcp` for",
     "                           details. OAuth servers authenticate via the",
     "                           /mcp panel in a session.",
+    "  yagni plugin <subcommand> Claude Code plugins from a marketplace: marketplace",
+    "                           add, install, uninstall, update, list — run",
+    "                           `yagni plugin` for details. Skills, commands,",
+    "                           agents, and bundled MCP servers load on launch.",
     "  yagni token              Output the active environment's API token (for helpers).",
     "  yagni use <name>         Switch the active environment (sticky).",
     "                           Presets: prod, local. Others need --base-url <url>.",
@@ -665,6 +670,11 @@ export async function main(argv) {
     if (command === "mcp") {
         return mcpCommand(rest);
     }
+    // Claude Code plugin marketplaces: install/remove/update from YAGNI itself
+    // (state under ~/.yagni-code/plugins; Claude Code's own installs still mirror).
+    if (command === "plugin") {
+        return pluginCommand(rest);
+    }
     // The headless pipeline entry. `go` is a real subcommand, not passthrough:
     // the interactive run stays `/go` inside a session, and a `yagni go` without
     // --headless is refused with usage rather than launched as an agent prompt.