@mutagent/helix 0.1.0-alpha.14

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/install-paths.md

@@ -0,0 +1,57 @@
+# Install Paths — Per-Platform Reference
+
+> Per-platform install locations for the `mutagent-diagnostics` skill binding and agent files.
+> Used by `scripts/cli/init.ts` (`pnpx @mutagent/diagnostics init`) to determine where to
+> install on each detected platform.
+
+## Detection + Install Table
+
+| Platform | Detection marker | Skill path | Agents path | Binding format |
+|---|---|---|---|---|
+| Claude Code | `~/.claude/` exists | `~/.claude/skills/mutagent-diagnostics/` | `~/.claude/agents/` | `.md` |
+| Codex | `~/.codex/` exists | `~/.codex/skills/mutagent-diagnostics/` | `~/.codex/agents/` | `.toml` |
+| Cursor | `.cursor/` in CWD exists | `.cursor/rules/` (project-scoped) | n/a (no agent primitive yet) | `.mdc` |
+
+## Notes
+
+### Claude Code
+
+- Detection: `~/.claude/` directory presence (filesystem probe — not env var).
+- Skill: full skill directory copied to `~/.claude/skills/mutagent-diagnostics/`.
+- Agents: `assets/agents/*.md` symlinked (or copied) to `~/.claude/agents/`.
+  Use `scripts/cli/install-agents.ts --scope=user` for user-scope install.
+- **Session restart required** after install: the `subagent_type` registry caches at boot.
+
+### Codex
+
+- Detection: `~/.codex/` directory presence.
+- Skill: full skill directory copied to `~/.codex/skills/mutagent-diagnostics/`.
+- Agents: `assets/agents/*.md` **transcoded** `.md → .toml` (YAML frontmatter → `[agent]` TOML block)
+  and written to `~/.codex/agents/`.
+  Use `scripts/cli/install-agents.ts --transcode-only --to codex <input.md> <output.toml>`.
+- See `references/source-platforms/codex.md` for the full TOML format spec.
+
+### Cursor
+
+- Detection: `.cursor/` directory in the **current working directory** (project-scoped; no
+  user-global `~/.cursor/` detection implemented in v0.1).
+- Skill: skill rules copied to `.cursor/rules/mutagent-diagnostics.mdc` (project-scoped).
+- Agents: **no agent primitive** on Cursor yet.
+- See `references/target-platforms/local-cursor.md` (Binding Surface & Install Path) for current Cursor binding state and TODO. (Cursor is an apply target, not a trace source — PR-016.)
+
+## Path resolution rules
+
+- All `~/` prefixes resolve via `os.homedir()` at runtime — never hardcoded `~` expansion.
+- CWD-relative paths (Cursor) resolve from `process.cwd()` at install time.
+- Idempotent: re-running `pnpx @mutagent/diagnostics init` on an already-installed path is safe.
+  Existing files are not clobbered unless `--force` is passed.
+
+## Per-platform trigger / activation
+
+| Platform | How to invoke mutagent-diagnostics after install |
+|---|---|
+| Claude Code | Slash command `/mutagent-diagnostics` OR natural language "diagnose my agents" |
+| Codex | Invoke agent by name from Codex session (agent primitive in `~/.codex/agents/`) |
+| Cursor | `.mdc` rule injected as a Cursor Background Agents rule (TBD — see `target-platforms/local-cursor.md`) |
+
+See also: `SKILL.md §1 — Triggers` for the canonical natural-language activation list.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/langfuse.md

@@ -0,0 +1,178 @@
+# Langfuse — Source Platform Reference
+
+> **POST-FLIP (UniTF):** the diagnostics skill no longer fetches or normalizes
+> Langfuse traces itself. Fetch + normalize now live in `@mutagent/tools` and run
+> UPSTREAM via `mutagent-cli trace fetch --platform langfuse …`, which emits a
+> UniTF JSONL + `manifest.json`. The skill READS that handover via
+> `scripts/normalize/read-unitf.ts` (Step 3.7). This doc is now reference material
+> for **shaping the upstream CLI query** (filter coverage, quirks, CLI-vs-REST).
+> Run `mutagent-cli trace --help` for the fetch surface.
+
+> CLI-first per PR-001 and OQ-1 (REST fallback only when the CLI cannot express
+> the operation — see CLI vs REST below).
+> **Official CLI docs: https://langfuse.com/docs/api-and-data-platform/features/cli**
+> Upstream docs: https://langfuse.com/docs
+> Public API reference: https://api.reference.langfuse.com
+
+## Why a CLI (and why clients will have one)
+
+Langfuse CLIs are the **primary way sources and targets interact with + update
+trace data** in a Langfuse deployment; the **REST API is the fallback** for
+operations the CLI cannot express. Clients running diagnostics will most often
+have either the `langfuse` CLI installed or Langfuse-as-platform reachable, so
+the skill's fetch layer is CLI-first (`langfuse traces list --json`) and degrades
+to the documented REST endpoints when the CLI is absent or a filter is
+CLI-unsupported. The skill must stay compatible with both surfaces.
+
+## Install
+
+> Official CLI docs: https://langfuse.com/docs/api-and-data-platform/features/cli
+>
+> During onboarding the skill checks whether the `langfuse` CLI is on PATH
+> (`scripts/setup/detect.ts --cli langfuse`). If it is MISSING, onboarding shows
+> this docs link + the install command below and **asks for explicit approval
+> before installing** (approve-to-install gate, PR-021 — see
+> `references/workflows/onboarding.md` Phase 2). It NEVER auto-installs; on decline
+> the skill continues via the REST fallback documented under "CLI vs REST" below.
+
+```bash
+pip install langfuse   # Python SDK + CLI
+# OR
+npm install -g langfuse
+```
+
+## Auth
+
+Set in `.mutagentrc` (or the environment — the skill reads them at runtime,
+never hardcoded):
+```
+LANGFUSE_SECRET_KEY=sk-...
+LANGFUSE_PUBLIC_KEY=pk-...
+LANGFUSE_HOST=https://cloud.langfuse.com  # or self-hosted URL (local dev: http://localhost:3033)
+```
+
+## CLI Operation Manual
+
+### List traces (with filters)
+
+```bash
+langfuse traces list \
+  --from "7daysAgo" \
+  --to "now" \
+  --agent-id "search-agent" \
+  --has-feedback \
+  --score-below 3 \
+  --has-error \
+  --limit 100 \
+  --json
+```
+
+> POST-FLIP: the arg-builder + REST pager that used to live in the skill
+> (`scripts/fetch/langfuse.ts`) were REMOVED. The upstream `mutagent-cli trace
+> fetch --platform langfuse` (in `@mutagent/tools`) now owns these flags and the
+> CLI-vs-REST fallback; the flags above document the query surface it accepts.
+
+### Fetch single trace (with observations)
+
+```bash
+langfuse traces get --trace-id tr_abc123 --json
+```
+
+### List scores (for scale auto-discovery)
+
+```bash
+langfuse scores list --limit 100 --json
+```
+
+### Filter by skill tag
+
+```bash
+langfuse traces list --tag "skill:mutagent-diagnostics" --json
+```
+
+---
+
+## Filter-Coverage Matrix — what we can ACTUALLY filter on
+
+> **Operator priority (Wave-5.1).** Empirically verified 2026-06-01 against a
+> live local Langfuse stack (docker-compose, `:3033`) using the public REST API
+> `GET /api/public/traces`. The CLI flags above are sugar over these same REST
+> filters; an operation is only as reliable as its underlying REST/field support.
+>
+> **KEY FINDING — Langfuse has NO native "agent ID".** There is no first-class
+> agent identifier on a trace. The skill approximates an agent by:
+> `trace.name` (the closest proxy — exact-match filterable), `tags`
+> (e.g. `skill:<name>`, `host:<runtime>`), or `metadata.*` (NOT server-side
+> filterable — must post-filter client-side). Plan diagnostics scoping around
+> `name` + `tags`, not an agent-ID.
+
+| Operation (filter on…) | Supported? | Via which field | REST param (`/api/public/traces`) | CLI flag | Notes |
+|---|---|---|---|---|---|
+| Agent identity | ⚠️ proxy only | `trace.name` (exact) **or** `tags` | `name=` / `tags=` | `--agent-id`* / `--tag` | No native agent-ID; `--agent-id` maps to a `name`/`tag` proxy. |
+| Trace name | ✅ yes | `trace.name` | `name=` (EXACT match) | `--agent-id`* | `name=probe` → hit; `name=prob` → 0. No prefix/substring. |
+| Tags | ✅ yes | `trace.tags[]` | `tags=` | `--tag` | Matches traces carrying the tag (`skill:mutagent-diagnostics` → 3). |
+| Metadata | ❌ no (server) | `trace.metadata.*` | — (ignored) | — | `metadata=` is silently ignored — returns ALL. Post-filter client-side. |
+| User ID | ✅ yes | `trace.userId` | `userId=` | — | Native column. `userId=` filters server-side (often null in our traces). |
+| Session ID | ✅ yes | `trace.sessionId` | `sessionId=` | `--session-id` | Exact match (`sessionId=probe-…` → 1). |
+| Time window | ✅ yes | `trace.timestamp` | `fromTimestamp=` / `toTimestamp=` | `--from` / `--to` | ISO8601 server-side; CLI also accepts relative (`7daysAgo`). |
+| Environment | ✅ yes | `trace.environment` | `environment=` | — | Native column (`default`). |
+| Release / Version | ✅ yes | `trace.release` / `.version` | `release=` / `version=` | — | Native columns. |
+| Order | ✅ yes | any sortable column | `orderBy=timestamp.desc` | — | e.g. `timestamp.desc`. |
+| **Score value / threshold** | ❌ NOT on traces-list | — | — (ignored on `/traces`) | `--score-below`† | `scoreValue=`/`minScore=` are IGNORED by `/api/public/traces`. Use `/api/public/scores` then join, OR client-side post-filter on the embedded `scores[]`. |
+| **Error / level=ERROR** | ❌ NOT on traces-list | observation `.level` | — (ignored on `/traces`) | `--has-error`† | `level=`/`hasError=` are IGNORED by `/api/public/traces`. Use `GET /api/public/observations?level=ERROR` then join to traces, OR client-side post-filter. |
+| **Has-feedback** | ⚠️ derived | embedded `scores[]` | — | `--has-feedback`† | No native traces-list param. Derived client-side: `trace.scores.length > 0` (this is what `normalizeLangfuseTrace` does). |
+
+`*` `--agent-id` is a convenience flag in the skill's arg-builder; it has no
+native Langfuse equivalent — it routes to a `name`/`tag` proxy filter.
+`†` `--score-below` / `--has-error` / `--has-feedback` are CLI conveniences. They
+are NOT supported as native `/api/public/traces` query params: the traces-list
+endpoint silently ignores unknown params (returns the full set). Where the CLI
+implements them it does so via the scores/observations endpoints or by
+client-side post-filtering. The skill's tier0 census
+(`scripts/tier0/langfuse.ts`) computes error/feedback/low-score rates
+CLIENT-SIDE from the normalized `TraceMetadata`, so coverage does not depend on
+server-side support for these three.
+
+### Semantic search
+
+- Semantic / free-text search across trace content: **NOT supported.**
+
+---
+
+## CLI vs REST — operational reality (Wave-5.1)
+
+| Need | CLI (`langfuse …`) | REST fallback | Skill behavior |
+|---|---|---|---|
+| List traces in a window | `traces list --from … --json` | `GET /api/public/traces?fromTimestamp=…` | `mutagent-cli trace fetch --platform langfuse` (upstream; CLI-first, REST fallback when the `langfuse` CLI is absent). |
+| Single trace + observations | `traces get --trace-id … --json` | `GET /api/public/traces/{id}` | upstream CLI fetch → UniTF; the skill reads the projected trace. |
+| Error filtering | `--has-error` (CLI sugar) | `GET /api/public/observations?level=ERROR` | tier0 derives `hasError` client-side from observations. |
+| Score / low-score filtering | `--score-below N` (CLI sugar) | `GET /api/public/scores` + join | tier0 derives low-score client-side from embedded `scores[]`. |
+| Seeding test traces | — | `POST /api/public/ingestion` (async worker) | T2 integration seeds SYNTHETIC traces this way (NO client data). |
+
+The fetch→normalize half of this chain (and its live REST-backed verification)
+now lives in `@mutagent/tools`; the skill consumes the resulting UniTF. Any
+operation the CLI cannot express (score/level/metadata server-side filtering)
+falls back to REST or client-side post-filtering as noted above — handled
+upstream by `mutagent-cli trace fetch`, not by the skill.
+
+> Note: the internal `.claude/skills/langfuse-cli/` toolkit is a benchmark
+> cross-verification tool for dev use — it is NOT this skill's source/target
+> adapter. The source/target interaction surface is the public `langfuse` CLI
+> (CLI-first) + the public REST API (fallback).
+
+## Normalization (moved upstream)
+
+Langfuse-record → UniTF normalization is owned by the `@mutagent/tools` langfuse
+adapter and produced by `mutagent-cli trace fetch --platform langfuse --export
+<traces.jsonl>`. Inside the skill there is a SINGLE platform-agnostic read path:
+
+```bash
+# Read the handed-over UniTF JSONL (+ manifest) → TraceMetadata[] + EntityContext:
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). The per-platform
+Langfuse normalizer + its live round-trip verification now live in
+`@mutagent/tools`.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/local-jsonl.md

@@ -0,0 +1,55 @@
+# Local JSONL — Source Platform Reference
+
+> For `.jsonl` / `.ndjson` trace files on the local filesystem.
+> No CLI needed — pure file reads.
+>
+> The ensure-cli gate (PR-021 — `references/workflows/onboarding.md` Phase 2)
+> reports `status: not-required` for this source: there is no platform CLI to
+> install. Filtering is client-side via `grep`/`jq` (see below). Tooling docs:
+> `jq` — https://jqlang.github.io/jq/manual/ (optional, for advanced filtering).
+
+## Format
+
+One JSON object per line. Flexible schema — unknown fields are ignored.
+
+Minimal required fields for a trace:
+```json
+{"id": "tr_001", "messages": [...], "startTime": "2026-05-27T10:00:00Z"}
+```
+
+## Fetching traces (filter examples)
+
+```bash
+# All traces with errors:
+grep '"hasError":true' traces.jsonl
+
+# By agent ID:
+grep '"agentId":"search-agent"' traces.jsonl
+
+# By time window (using jq):
+jq 'select(.startTime >= "2026-05-20")' traces.jsonl
+
+# With feedback:
+grep '"hasFeedback":true' traces.jsonl
+```
+
+## Filter/Search Support
+
+See `references/filter-search-matrix.md`. All filtering is post-read client-side. Full grep/jq support on all dimensions. Semantic search not supported.
+
+## Normalization (moved upstream — UniTF flip)
+
+The skill no longer normalizes local NDJSON itself. `mutagent-cli trace fetch
+--platform local-ndjson --export <traces.jsonl>` (in `@mutagent/tools`) reads the
+raw file and emits a UniTF JSONL + `manifest.json`; the skill READS that handover
+via the single platform-agnostic reader:
+
+```bash
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). The bad-line
+tolerance (blank lines skipped; malformed lines counted-but-visible, F-S7) is
+preserved by the reader. Run `mutagent-cli trace --help` for the fetch surface.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/openobserve.md

@@ -0,0 +1,102 @@
+# OpenObserve — Source Platform Reference
+
+> **POST-FLIP (UniTF):** the diagnostics skill does not fetch or normalize
+> OpenObserve traces itself. Fetch + normalize live in `@mutagent/tools` and run
+> UPSTREAM via `mutagent-cli trace fetch --platform openobserve …`, which emits a
+> UniTF JSONL + `manifest.json`. The skill READS that handover via
+> `scripts/normalize/read-unitf.ts` (Step 3.7). This doc is reference material for
+> **shaping the upstream CLI query** (auth, endpoints, quirks). Run
+> `mutagent-cli trace --help` for the fetch surface.
+>
+> Transport = **REST** (HTTP Basic auth). OpenObserve stores OpenTelemetry spans,
+> so the adapter maps OpenObserve span rows → the shared OTel span shape and reuses
+> the otel normalizer (`sourcePlatform: "openobserve"`). Upstream contract:
+> `mutagent-tools/references/adapter-research/openobserve.md` (cited sources O1–O8).
+
+## Access patterns
+
+OpenObserve exposes two complementary trace endpoints; the adapter uses SQL search:
+
+| Endpoint | Use |
+|---|---|
+| `GET /api/{org}/{stream}/traces/latest` | list recent trace summaries by window (root span only) |
+| `POST /api/{org}/_search` | full SQL over spans — the adapter's primary path (window-scoped `SELECT * FROM "{stream}"`) |
+
+The adapter runs a single window-scoped `_search`, pages by `from`/`size`, and
+groups the returned span rows by `trace_id` into full `UnifiedTrace`s — no per-trace
+N+1 request storm.
+
+## Auth
+
+HTTP Basic auth: `Authorization: Basic base64(email:password)`. Set env vars (read
+at runtime, never hardcoded — the CLI passes only env-var NAME refs, not raw secrets):
+
+```
+OPENOBSERVE_URL=http://localhost:5080          # self-hosted; cloud: https://api.openobserve.ai
+OPENOBSERVE_ORG=default                          # org id path segment (default "default")
+OPENOBSERVE_STREAM=default                       # trace stream name (default "default")
+# EITHER email + password (→ Basic base64(email:password)):
+OPENOBSERVE_EMAIL=you@example.com
+OPENOBSERVE_PASSWORD=...
+# OR a single pre-issued token (cloud). If it starts with "Basic "/"Bearer " it is
+# sent verbatim; otherwise it is sent as `Basic <token>`:
+OPENOBSERVE_AUTH=...
+```
+
+`--endpoint-ref` / `--credential-ref` override the URL / auth env-var NAMES.
+
+## CLI Operation Manual
+
+```bash
+# Size the window (cheap)
+mutagent-cli trace count --platform openobserve --since 24h
+
+# Fetch + normalize → UniTF JSONL + sibling manifest
+mutagent-cli trace fetch --platform openobserve --since 24h \
+  --export .mutagent/traces/oo1/traces.jsonl
+
+# Pin a single trace
+mutagent-cli trace fetch --platform openobserve --trace <trace_id> --since 7d
+```
+
+Window bounds are required by `_search`; when `--since/--until` are omitted the
+adapter defaults to a 24h lookback ending at `now` so the required bounds hold.
+
+## Filter/Search Support
+
+| Filter | Support | How |
+|---|---|---|
+| Time window | ✅ | `start_time`/`end_time` (µs) — partition-pruned in `_search` |
+| Single trace | ✅ | `WHERE trace_id = '…'` |
+| Agent / service / keyword / scope | ⚠️ core-side | applied by the CLI's canonical filter pass over normalized UniTF |
+| Error / feedback | ⚠️ derived | `span_status = "ERROR"` → UniTF `status: "error"`; derived client-side downstream |
+
+## Quirks (grounded in the research doc's Open Questions)
+
+- **Timestamp unit** (OO-G2): `_search` uses microseconds; some fields are nanoseconds.
+  The adapter auto-detects by magnitude (µs vs ns vs ms vs s) — no unit assumption.
+- **Root span sentinel** (OO-G1): `parent_span_id` may be `null`, `""`, or omitted —
+  all three map to a root span.
+- **GenAI attribute duality** (OO-G5/G6): GenAI fields appear both inside `attributes`
+  (canonical dotted keys) and as promoted top-level columns. The adapter prefers the
+  canonical `attributes` value; Mastra aliases (`ai_usage_*` / `ai_model_name`) fill the
+  OTel semconv keys only when the canonical field is absent (priority: OTel > Mastra).
+- **Stream name** (OO-G4): never hardcoded — `OPENOBSERVE_STREAM` (default `"default"`).
+- **Cloud auth** (OO-G7): a cloud-issued token is supported via `OPENOBSERVE_AUTH`
+  (Bearer/Basic pass-through). An MCP transport is a future task (UT-3), not built.
+
+## Normalization (moved upstream — UniTF flip)
+
+OpenObserve span rows → UniTF normalization lives in the `@mutagent/tools`
+openobserve adapter and runs UPSTREAM via `mutagent-cli trace fetch --platform
+openobserve --export <traces.jsonl>`. The skill READS the resulting UniTF JSONL
+(+ manifest) via the single platform-agnostic reader:
+
+```bash
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). Run
+`mutagent-cli trace --help` for the fetch surface.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/source-platforms/otel.md

@@ -0,0 +1,63 @@
+# OpenTelemetry — Source Platform Reference
+
+> CLI-first per OQ-1.
+> Upstream docs: https://opentelemetry.io/docs/
+> **Official tooling/protocol docs: https://opentelemetry.io/docs/specs/otlp/**
+>
+> NOTE: OpenTelemetry has **no single canonical CLI** — trace access is
+> backend-specific (Jaeger / Tempo / Honeycomb), each with its own API/CLI.
+> Onboarding therefore treats OTel as `status: not-required` in the ensure-cli
+> gate (PR-021 — `references/workflows/onboarding.md` Phase 2): there is nothing
+> to install, so the skill links these docs and proceeds via the REST/curl fetch
+> shown below. Per-backend docs:
+> - Jaeger: https://www.jaegertracing.io/docs/
+> - Tempo (Grafana): https://grafana.com/docs/tempo/
+> - Honeycomb: https://docs.honeycomb.io/
+
+## Access patterns
+
+OTel spans are accessed via an OTLP-compatible backend. Common options:
+- Jaeger: https://www.jaegertracing.io/
+- Tempo (Grafana): https://grafana.com/docs/tempo/
+- Honeycomb: https://www.honeycomb.io/
+
+## Auth
+
+Set in `.mutagentrc` per your backend:
+```
+OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer sk-...
+```
+
+## CLI Operation Manual (Jaeger example)
+
+```bash
+# List traces (Jaeger UI API)
+curl -s "http://localhost:16686/api/traces?service=my-agent&limit=100" | jq .
+
+# Fetch specific trace
+curl -s "http://localhost:16686/api/traces/{traceId}" | jq .
+
+# Filter by error
+curl -s "http://localhost:16686/api/traces?service=my-agent&tags=%7B%22error%22%3A%22true%22%7D"
+```
+
+## Filter/Search Support
+
+See `references/filter-search-matrix.md`. Key: most OTel filtering is client-side post-fetch grep because CLI tooling varies per backend. `span.status.code == 2` = ERROR.
+
+## Normalization (moved upstream — UniTF flip)
+
+OTLP-JSON spans → UniTF normalization now lives in the `@mutagent/tools` otel
+adapter and runs UPSTREAM via `mutagent-cli trace fetch --platform otel --export
+<traces.jsonl>` (input: array of OTel spans / OTLP JSON). The skill READS the
+resulting UniTF JSONL (+ manifest) via the single platform-agnostic reader:
+
+```bash
+bun scripts/cli/run.sh scripts/normalize/read-unitf.ts \
+  --in <traces.jsonl> --manifest <manifest.json> \
+  --out-metadata /tmp/traces-metadata.json --out-entity /tmp/entity-context.json
+```
+
+Reader: `scripts/normalize/read-unitf.ts` (+ `unitf-adapter.ts`). Run
+`mutagent-cli trace --help` for the fetch surface.

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/cloud-rest.md

@@ -0,0 +1,84 @@
+# Cloud REST — Target Platform Reference
+
+> Apply target: Remote cloud services accessed via REST API (e.g., Langfuse, hosted OTel, custom agent API).
+> Target class: `remote`
+> Apply branch: remote (read-before-write required; idempotency required; HITL gate for all mutations)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `remote` |
+| Mutability | REST mutations via idempotent API calls |
+| Isolation | No local isolation — all changes are live |
+
+## Key Constraints
+
+- **Read before write (PR-003)**: always GET the resource before PATCH/PUT/DELETE
+- **Idempotency (PR-012)**: use `uuidgen` client-side idempotency keys for all mutations; retry-safe
+- **HITL gate (PR-014)**: ALL remote mutations require user confirmation via HITL HTML before execution
+- **No destructive ops without gate**: DELETE operations require explicit `AskUserQuestion` in Claude Code; numbered chat-multi-choice elsewhere
+
+## Supported Services
+
+| Service | Auth | Base URL |
+|---------|------|----------|
+| Langfuse | `LANGFUSE_SECRET_KEY` + `LANGFUSE_PUBLIC_KEY` | `https://cloud.langfuse.com` or self-hosted |
+| Custom REST Agent | Bearer token | User-configured |
+
+## How Remedies Are Applied
+
+1. **GET resource** — confirm current state matches expected (read-before-write)
+2. **Render HITL HTML** — show proposed change to user
+3. **User confirms** — via AskUserQuestion (Claude Code) or numbered chat option
+4. **PATCH/POST** with idempotency key — execute mutation
+5. **Verify** — re-GET to confirm applied state
+6. **Emit audit** — `audit.json` + `audit.md` per PR-013
+
+## Idempotency Pattern
+
+```typescript
+const idempotencyKey = crypto.randomUUID(); // uuidgen equivalent
+
+await fetch(`${baseUrl}/api/resource`, {
+  method: 'PATCH',
+  headers: {
+    'Content-Type': 'application/json',
+    'Idempotency-Key': idempotencyKey,
+    'Authorization': `Bearer ${apiKey}`,
+  },
+  body: JSON.stringify(patch),
+});
+```
+
+## Auth Configuration
+
+Keys are referenced by name only — never inline values. From `.mutagentrc`:
+```
+LANGFUSE_SECRET_KEY=<key>
+LANGFUSE_PUBLIC_KEY=<key>
+LANGFUSE_HOST=https://cloud.langfuse.com
+```
+
+## Remedy Categories
+
+- **Score annotation**: POST score to a trace (e.g., flag false positive in Langfuse)
+- **Trace annotation**: add metadata tag to a trace
+- **Dataset update**: add or update evaluation dataset entries
+- **Config sync**: update remote agent config via REST API
+
+## Audit
+
+```json
+{
+  "targetPlatform": "cloud-rest",
+  "targetClass": "remote",
+  "remedyType": "score-annotation",
+  "idempotencyKey": "<uuid>",
+  "resourceUrl": "https://cloud.langfuse.com/api/...",
+  "before": {},
+  "after": {},
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```

package/mutagent-diagnostics/.claude/skills/mutagent-diagnostics/references/target-platforms/local-claude.md

@@ -0,0 +1,65 @@
+# Local Claude (Claude Code) — Target Platform Reference
+
+> Apply target: Claude Code running on the local machine.
+> Target class: `local-agent`
+> Apply branch: local-agent (read-verify-only; no code edits; git BG-worktree for self-diagnostics PRs)
+
+## Classification
+
+| Dimension | Value |
+|-----------|-------|
+| Target class | `local-agent` |
+| Mutability | read-verify; HITL via HTML |
+| Isolation | N/A (agent runs in its own session) |
+
+## How Remedies Are Applied
+
+Claude Code remedies are **configuration changes**, not code edits.
+
+1. **Read before write (PR-003)**: read `~/.claude/settings.json` (or project `.claude/settings.json`) before proposing edits
+2. **HITL gate (PR-014)**: HTML report + markdown remedy proposal rendered; user applies in Claude Code settings UI or confirms before file edit
+3. **BG-worktree only (PR-004)**: if remedy involves committing configuration to `.claude/` in the project, a separate worktree branch is opened — no direct main-branch commits
+
+## Config Targets
+
+| File | Purpose |
+|------|---------|
+| `~/.claude/settings.json` | Global user settings |
+| `<project>/.claude/settings.json` | Project-scoped settings |
+| `<project>/.claude/skills/` | Installed skill bundles |
+| `CLAUDE.md` | Project instructions (human-authored) |
+
+## Capability Probing
+
+```bash
+# Check Claude Code is installed
+which claude || npx claude --version
+
+# List recent projects
+ls ~/.claude/projects/
+
+# Check settings
+cat ~/.claude/settings.json 2>/dev/null
+```
+
+## Remedy Categories (iter-8 locked)
+
+- **Skill install**: copy skill bundle to `.claude/skills/<skill-name>/`
+- **Settings update**: patch `~/.claude/settings.json` key
+- **CLAUDE.md addendum**: append or insert a section via PR (BG worktree)
+- **Session cleanup**: no automated session cleanup — surfaced as informational finding only
+
+## Audit
+
+Auditor emits `audit.json` + `audit.md` per PR-013. All fields required:
+```json
+{
+  "targetPlatform": "local-claude",
+  "targetClass": "local-agent",
+  "remedyType": "skill-install",
+  "before": {},
+  "after": {},
+  "diagnosedAtHash": "<git-hash>",
+  "appliedAtHash": "<git-hash>"
+}
+```