@anvia/cli 1.2.0 → 1.3.0

package/dist/skills/anvia-rag/references/graph-rag.md

@@ -0,0 +1,115 @@
+# Graph RAG
+
+Use a knowledge graph when the questions are about connections (which incidents
+affect which products, who owns what) — vectors find similar text, graphs
+traverse relationships. The two compose: managed ingestion embeds chunks for a
+vector store while extracting facts for the graph.
+
+Core primitives live in `@anvia/graph`; provisioning, persistence, and queries
+belong to adapters (`@anvia/neo4j`, `@anvia/memgraph`).
+
+## Schema first
+
+```ts
+import { defineGraphSchema } from "@anvia/graph";
+
+const schema = defineGraphSchema({
+  nodes: {
+    Product: {
+      description: "A product or service.",
+      identity: ["id"],
+      properties: z.strictObject({ id: z.string(), name: z.string() }),
+    },
+  },
+  relationships: {
+    AFFECTS: {
+      description: "An incident affects a product.",
+      from: "Incident",
+      to: "Product",
+      properties: z.strictObject({ severity: z.enum(["low", "medium", "high"]) }),
+    },
+  },
+});
+```
+
+Design the schema from the questions, not the source tables. `identity` fields
+are how facts merge — wrong identity modeling duplicates entities forever.
+
+## Ingestion
+
+```ts
+import { ingestGraphText } from "@anvia/graph";
+
+const ingestion = await ingestGraphText({
+  graph,
+  document: { id: "incident-42", text, metadata: { tenant: "acme" } },
+  extractionModel,
+  embeddingModel,
+  chunking: {
+    strategy: "recursive",
+    maxSize: 1_000,
+    overlap: 100,
+    separators: ["\n\n", "\n", " "],
+  },
+  conflict: "error",
+  orphanEntities: "delete",
+  factConflicts: {
+    entity: { properties: { summary: "prefer-longest", aliases: "union", confidence: "max" } },
+  },
+});
+```
+
+- Managed graphs accept the same raw-text shape as vector ingestion, so reuse
+  your chunking settings. `ingestGraphDocuments()` batches; `ingestGraphTextToStores()`
+  writes graph + vector store in one call.
+- Two conflict policies: `factConflicts` (disagreements between chunks, rejected
+  by default — strategies like `prefer-longest`, `union`, `max`), and `conflict`
+  (collisions with already-stored facts). Read both errors; they carry fact
+  type, stable key, identity, and source chunk IDs.
+- Graph and vector writes are separate transactions. On partial failure
+  (`GraphIngestionStageError`) reconcile from the returned `receipt` — persist
+  ingestion status and retry the incomplete stage yourself.
+- Reuse `ingestion.vectorDocuments` for the vector upsert instead of
+  re-embedding. Existing graph registrations are read-only ingestion targets.
+
+## Search tool
+
+```ts
+import { createGraphSearchTool } from "@anvia/graph";
+
+const searchGraph = createGraphSearchTool({
+  name: "search_graph",
+  description: "Search connected entities and supporting evidence.", // required — no default
+  graph,
+  model: embeddingModel,
+  search: { type: "vector", seeds: ["entities"], topK: 8 },
+  traversal: {
+    relationships: ["AFFECTS"],
+    direction: "both",
+    maxDepth: 2,
+    maxNodes: 40,
+    maxRelationships: 80,
+  },
+  evidence: { type: "chunks", maxChunks: 12 },
+});
+```
+
+- `search` has two modes: `{ type: "vector", seeds, topK }` and
+  `{ type: "hybrid", seeds, topK, candidatesPerSeed, rrfK }` — hybrid fuses
+  vector similarity with per-seed graph matches. Prefer it when seed names
+  alone miss paraphrased entities.
+- Bound everything: `maxDepth`, `maxNodes`, `maxRelationships`, `maxChunks`.
+  Unbounded traversal is the graph equivalent of `topK: 1000`.
+- Evidence modes depend on the registration: managed graphs hydrate stored
+  chunks, existing-graph registrations use `{ type: "none" }`.
+- One search tool per question shape, as with vector tools — graph and vector
+  tools coexist on the same agent when some questions are relational and some
+  are textual.
+
+## Exploration
+
+Adapters implementing `GraphExplorer` expose bounded `overview` / `expand`
+views for visualization (Studio's graph explorer, `@anvia/react`
+`useGraphExplorer`). Explorer IDs are opaque and provider-specific — follow-up
+expansion only, never persistence. Adapters cap requests, return truncation
+metadata, and omit stored embeddings and reserved `__anvia_*` properties.

package/dist/skills/anvia-rag/references/pipeline.md

@@ -0,0 +1,81 @@
+# Chunk and Embed Pipeline
+
+## Chunk
+
+`chunkText` from `@anvia/core/documents` splits raw text before embedding. Keep
+chunk ids stable and traceable to the source:
+
+```ts
+import { chunkText } from "@anvia/core/documents";
+import type { Document } from "@anvia/core/completion";
+
+const chunks = chunkText({
+  text,
+  strategy: "recursive",
+  maxSize: 80,
+  overlap: 10,
+  separators: ["\n\n", "\n", " "],
+}).map((chunk): Document => ({
+  id: `${path}#chunk=${chunk.index}`,
+  text: chunk.text,
+  additionalProps: {
+    source: path,
+    mediaType: "text/plain",
+    chunkIndex: String(chunk.index),
+  }),
+}));
+```
+
+Small overlap preserves cross-boundary context. Record provenance
+(`source`, `mediaType`, `chunkIndex`) in `additionalProps` — retrieval results
+are only as citable as the metadata you store.
+
+## Embed
+
+`embedDocuments` from `@anvia/core/embeddings` maps domain objects to embedded
+documents with explicit selectors. The same model instance must embed documents
+and queries:
+
+```ts
+import { embedDocuments } from "@anvia/core/embeddings";
+import { loadTransformersEmbeddingModel } from "@anvia/transformers";
+
+const model = await loadTransformersEmbeddingModel({ modelId: "Xenova/all-MiniLM-L6-v2" });
+const { documents: embedded } = await embedDocuments({
+  model,
+  documents: reports,
+  id: (report) => report.id,
+  content: (report) => report.text,
+  metadata: (report) => ({ desk: report.desk, priority: report.priority }),
+});
+```
+
+- `id` must be stable across re-index runs or upserts will duplicate.
+- `content` is what gets embedded — keep titles with bodies, drop boilerplate.
+- `metadata` carries everything you will filter or display on (`desk`,
+  `priority`, `source`). You cannot filter on what you did not store.
+- Custom models implement `EmbeddingModel` (`provider`, `modelId`,
+  `dimensions`, `embedTexts`). Production embeddings can also come from
+  provider packages (e.g. Mistral) — same `embedDocuments` contract.
+
+## Retrieve
+
+```ts
+import { InMemoryVectorStore, retrieveDocuments, vectorFilter } from "@anvia/core/vector-store";
+
+const store = InMemoryVectorStore.fromDocuments({
+  documents: embedded,
+  index: { type: "lsh", numTables: 8, numHyperplanes: 1, seed: 11 }, // opt-in for scale
+});
+const results = await retrieveDocuments({
+  store,
+  model,
+  query: "earnings risk remains elevated",
+  topK: 3,
+  filter: vectorFilter.and(vectorFilter.eq("desk", "markets"), vectorFilter.gt("priority", 2)),
+});
+```
+
+Start with exact retrieval (`topK`, metadata filters) before adding approximate
+indexes — LSH trades recall for speed and needs a fixed `seed` for reproducible
+evals.

package/dist/skills/anvia-rag/references/rag-tool.md

@@ -0,0 +1,43 @@
+# RAG Search Tool
+
+Give the agent retrieval as a tool, not as pasted context. `createVectorSearchTool`
+from `@anvia/core/vector-store` wraps a store + embedding model with a routing
+description and `topK`:
+
+```ts
+import { Agent } from "@anvia/core/agent";
+import { createVectorSearchTool } from "@anvia/core/vector-store";
+
+const searchRunbooks = createVectorSearchTool({
+  store,
+  model: embeddingModel,
+  name: "search_runbooks",
+  description: "Search incident runbooks for relevant operational guidance.",
+  topK: 2,
+});
+
+const agent = new Agent({
+  id: "agent",
+  model: agentModel,
+  instructions: "Use the runbook search tool before answering incident questions.",
+  maxTurns: 2,
+  tools: [searchRunbooks],
+});
+```
+
+## Rules
+
+- The tool `description` is routing text: say when to call it, not how vectors
+  work. It is optional (a generic default exists), but always set it — the
+  default cannot route when several corpora exist. One tool per corpus with a
+  distinct description beats one generic `search_docs` tool.
+- Keep `topK` small (2–5). The agent reads what the tool returns — large `topK`
+  burns context and degrades answers.
+- Instruct the agent to call search _before_ answering, and to cite `source`
+  metadata from the results. Retrieval without citation requirements produces
+  confident paraphrases of nothing.
+- For static context that always applies (system rules, tiny glossaries), use
+  `Agent.context` (`Document` / `VectorContext`) instead of a tool — tools are
+  for corpora too large to fit the prompt.
+- Close vector clients (`vectorClient.close()`) when the process ends;
+  in-memory stores need no lifecycle.

package/dist/skills/anvia-rag/references/stores.md

@@ -0,0 +1,68 @@
+# Vector Store Selection
+
+Core contracts live in `@anvia/core/vector-store`
+(`InMemoryVectorStore`, `retrieveDocuments`, `vectorFilter`,
+`createVectorSearchTool`). Durable backends live in adapter packages:
+
+| Package           | Backend  | Best for                                  |
+| ----------------- | -------- | ----------------------------------------- |
+| `@anvia/chroma`   | Chroma   | local dev with persistence                |
+| `@anvia/lancedb`  | LanceDB  | embedded local persistence, no server     |
+| `@anvia/qdrant`   | Qdrant   | self-hosted production                    |
+| `@anvia/pgvector` | pgvector | teams already on Postgres                 |
+| `@anvia/milvus`   | Milvus   | large-scale self-hosted                   |
+| `@anvia/pinecone` | Pinecone | managed production                        |
+| `@anvia/redis`    | Redis    | existing Redis infra, hybrid search needs |
+| `@anvia/weaviate` | Weaviate | managed / hybrid search features          |
+
+For connected-entity questions (which incidents affect which products), add a
+knowledge graph alongside the vector store — see `graph-rag.md`. Vectors find
+similar text; graphs traverse relationships.
+
+## Hybrid (dense + sparse) retrieval
+
+Keyword-ish recall problems ("error 0x8007", exact identifiers) are a sparse
+retrieval problem. `retrieveDocuments` has a hybrid overload — pass
+`models: { dense, sparse }` instead of `model`, and the store's `searchHybrid`
+fuses both rankings (`fusion` controls the strategy):
+
+```ts
+import { embedSparseQuery } from "@anvia/core/embeddings"; // SparseEmbeddingModel
+// embedSparseTexts embeds documents' sparse side at ingestion
+
+const results = await retrieveDocuments({
+  store: hybridStore, // e.g. HybridVectorStore or a backend supporting searchHybrid
+  query,
+  models: { dense: embeddingModel, sparse: sparseModel },
+  topK: 5,
+});
+```
+
+Reach for hybrid when plain dense search misses exact tokens; keep pure dense
+when it does not — hybrid adds an ingestion and store-compatibility cost.
+
+## Client store pattern
+
+```ts
+import { ChromaVectorClient } from "@anvia/chroma";
+
+const vectorClient = new ChromaVectorClient();
+const store = vectorClient.vectorStore<Runbook>({
+  collectionName: "anvia_runbooks",
+  dimensions: 384, // must match the embedding model output
+});
+await store.ensure();
+await store.upsert({ documents: embedded });
+// ... retrieve ...
+await vectorClient.close();
+```
+
+## Rules
+
+- `dimensions` must match the embedding model — a 384-dim MiniLM index queried
+  with another model's vectors fails silently on quality, not loudly on types.
+- One model instance (or at least one model id) per collection. Never mix
+  embedding models in the same collection.
+- `ensure()` before `upsert`; `close()` clients when the process ends.
+- Start with `InMemoryVectorStore.fromDocuments` for spikes and tests, then
+  migrate to a client store — the `retrieveDocuments` call does not change.

package/dist/skills/anvia-rag/scripts/check-rag.sh

@@ -0,0 +1,75 @@
+#!/bin/sh
+# Heuristic checks for Anvia retrieval/RAG code in an app directory.
+# Usage: sh scripts/check-rag.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "rag OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+FILES=$(grep -rln --include='*.ts' \
+  -e 'embedDocuments' -e 'retrieveDocuments' -e 'createVectorSearchTool' -e 'createGraphSearchTool' -e 'vectorStore' \
+  "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" 2>/dev/null | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "rag OK (no retrieval code found)"
+  exit 0
+fi
+
+# 1. embedDocuments needs explicit id/content/metadata selectors.
+if echo "$FILES" | xargs grep -l 'embedDocuments' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A8 'embedDocuments(' 2>/dev/null | grep -q 'content:' || {
+    violation "embedDocuments without content selector (see references/pipeline.md)."
+  }
+fi
+
+# 2. Client vector stores need dimensions matching the embedding model.
+if echo "$FILES" | xargs grep -l 'vectorStore' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A5 'vectorStore' 2>/dev/null | grep -q 'dimensions' || {
+    violation "vectorStore without dimensions (see references/stores.md)."
+  }
+fi
+
+# 3. One search tool per corpus needs a routing description (warning: a generic default exists).
+if echo "$FILES" | xargs grep -l 'createVectorSearchTool' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A7 'createVectorSearchTool(' 2>/dev/null | grep -q 'description' || {
+    warning "createVectorSearchTool without description falls back to a generic default (see references/rag-tool.md)."
+  }
+fi
+
+# 4. Graph search tools have no default description — one is required.
+if echo "$FILES" | xargs grep -l 'createGraphSearchTool' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -A7 'createGraphSearchTool(' 2>/dev/null | grep -q 'description' || {
+    violation "createGraphSearchTool without description (see references/graph-rag.md)."
+  }
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "rag OK"
+  exit 0
+fi
+echo "See skills/anvia-rag/references/ for fixes."
+exit 1

package/dist/skills/anvia-studio/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: anvia-studio
+description: Run and inspect Anvia agents in Studio — local serving, playground, traces, approvals, sessions, evals, and observability.
+---
+
+# Anvia Studio Skill
+
+Use this skill when the user wants to run agents locally and see what happens:
+serving agents/pipelines over HTTP, using the playground, inspecting traces and
+sessions, exercising tool approvals, running eval suites, or wiring
+observability.
+
+## Process
+
+1. Serve the agents (`references/serve.md`) — smallest `Studio` that runs.
+2. Debug through the inspectors (`references/inspect.md`) — playground first,
+   then traces, approvals, sessions.
+3. Wire observability (`references/observe.md`) — only when runs must be
+   auditable or production-like.
+4. Run `scripts/check-studio.sh` from the app root before claiming done.
+
+## Minimal slice
+
+```ts
+import { Agent } from "@anvia/core";
+import { OpenAIClient } from "@anvia/openai";
+import { Studio } from "@anvia/studio";
+
+const client = new OpenAIClient({ apiKey: process.env.OPENAI_API_KEY });
+const agent = new Agent({
+  id: "support",
+  model: client.completionModel({ modelId: "gpt-6-astra", api: "responses" }),
+  name: "Support",
+  description: "Answers support questions.",
+  instructions: "Answer support questions clearly.",
+});
+
+await new Studio([agent]).serve({ port: 4021 });
+// Open http://localhost:4021/ui/playground
+```
+
+## Output
+
+Studio is a development surface, not production hosting. Point to the relevant
+reference file instead of pasting its contents into chat.

package/dist/skills/anvia-studio/references/inspect.md

@@ -0,0 +1,33 @@
+# Inspectors
+
+Debug in this order: playground → traces → approvals → sessions. Each surface
+answers a different question.
+
+- **Playground** — chat with a registered agent or team, switch models per run
+  (Studio can expose a shared multi-provider catalog with per-agent allow
+  lists), restore control choices from session metadata. First stop for
+  "what does it do?".
+- **Trace browser + session logs** — what actually happened: messages, tool
+  activity, usage, realtime log stream. First stop for "why did it do that?".
+- **Tool approval workflows** — exercise `requiresApproval` tools and question
+  prompts end to end; approvals resolve through the same interaction responses
+  the API uses.
+- **Eval suite runner** — run registered `runEvalSuite` configurations from the
+  UI. Keep the suite definitions in code (see the `anvia-evals` skill); Studio
+  runs them, it does not own them.
+- **Direct tool + MCP inspectors** — invoke tools by hand, including MCP tools.
+  Studio reads MCP provenance from `Agent.mcpServers`, so `McpClient`
+  `tools.prefix` values stay visible here.
+- **Memory explorer** — users, conversations, messages, transcript steps from
+  the session store. Empty here plus working chat means the store is not the
+  one the agent writes to — check `stores.sessions`.
+- **Pipelines** — graph, logs, run history, replay-from-history.
+- **Knowledge** — static/dynamic context, dynamic tools, retrieval log. First
+  stop for "why didn't it retrieve?".
+- **Status dashboard** — storage adapters, record counts, enabled capabilities.
+  First stop for "is anything even configured?".
+- **Graphs** — bounded overview/expansion over registered `GraphExplorer`
+  graphs (`@anvia/neo4j`, `@anvia/memgraph`); no raw queries accepted.
+
+Sandbox/browser registrations add loopback-only noVNC desktop views with explicit
+takeover leases — local debugging conveniences, not an auth model.

package/dist/skills/anvia-studio/references/observe.md

@@ -0,0 +1,34 @@
+# Observability
+
+Studio's own surfaces (realtime log stream, trace browser, status dashboard)
+cover development. Production-like auditing needs the observability packages:
+
+- `@anvia/langfuse` — tracing, eval reporting, scoring, prompt/dataset helpers.
+- `@anvia/otel` — OpenTelemetry adapters.
+- `@anvia/lens` — native Lens integration (see the cookbook's lens-native example).
+
+## Rules
+
+- Close observability clients in Studio's `onShutdown` — they are caller-owned
+  resources and outlive runs:
+
+```ts
+await new Studio([agent]).serve({
+  port: 4021,
+  shutdownTimeoutMs: 30_000,
+  onShutdown: async () => {
+    await Promise.all([lens.close(), langfuse.close(), otelSdk.shutdown()]); // otelSdk is your OTel SDK instance, not an Anvia export
+  },
+});
+```
+
+- Redact before export: `createPiiRedactor` ships with both `@anvia/langfuse`
+  and `@anvia/lens`. Wrap exporters with it so customer data never reaches
+  trace payloads in the first place.
+- For application logs alongside traces, `@anvia/logger` provides
+  `createConsoleLogger`, `createPinoLogger`, and `createLoggerObserver`.
+- Report evals to observability (Langfuse eval reporting, trace refs via
+  `resolveEvalTraceRef`) when runs must be auditable — see the `anvia-evals`
+  skill's `references/running.md`.
+- Never commit keys, private prompts, customer data, or trace payloads. Read
+  credentials from the environment at the boundary, same as provider keys.

package/dist/skills/anvia-studio/references/serve.md

@@ -0,0 +1,65 @@
+# Serving Agents
+
+`@anvia/studio` serves local agents, pipelines, and agent teams over HTTP with
+a browser UI. Register what you already built — Studio does not redefine agents.
+
+```ts
+import { Agent, AgentTeam } from "@anvia/core/agent";
+import { Studio } from "@anvia/studio";
+
+const researcher = new Agent({ id: "researcher", model });
+const team = new AgentTeam({ id: "research-team", model, members: [researcher] });
+await new Studio([researcher, team]).serve({ port: 4021 });
+```
+
+- `serve({ port })` starts HTTP + UI; `.start()` is the non-awaited variant.
+  Without a port, Studio uses `RUNNER_PORT`, then falls back to `4021`.
+- The playground lives at `/ui/playground`.
+- A Studio with only teams opens its first team automatically; agent and team
+  IDs occupy separate namespaces.
+
+## Sessions
+
+Studio uses an in-memory store by default — sessions, traces, and run history
+vanish on restart. Persist with SQLite:
+
+```ts
+import { Studio, createSqliteSessionStore } from "@anvia/studio";
+
+new Studio([agent], {
+  stores: { sessions: createSqliteSessionStore({ path: ".anvia/studio.sqlite" }) },
+}).start();
+```
+
+SQLite uses dedicated `anvia_studio_*` tables, so it can share an application
+database without touching product tables.
+
+## Lifecycle
+
+- `serve()` handles `SIGINT`/`SIGTERM`: stops accepting work, aborts active
+  Agent and Pipeline runs, waits for cancellation observers, then runs
+  `onShutdown` — close observability clients and other caller-owned resources
+  there.
+- `shutdown()` drains the same way for application-managed lifecycles;
+  `close()` aborts without waiting (compatibility only).
+
+## Runs
+
+The primary execution API is `POST /agents/:agentId/runs`: it streams JSONL
+events and accepts interaction-resume bodies, so scripts and CI can drive an
+agent without the browser UI.
+
+## Teams
+
+Team runs stream JSONL events (`POST /teams/:teamId/runs`), with steer, cancel,
+and per-interaction resolve endpoints. Approvals and questions surface as cards
+labeled with the requesting member; several members may block at once. Team
+tasks are page-local and ephemeral — they never enter saved agent sessions.
+
+## Rules
+
+- Studio provides no authentication. Apply auth middleware to execution routes
+  before exposing it beyond localhost.
+- Disconnecting a stream or shutting down cancels the run and its pending
+  interactions — completed runs leave the live registry (later control calls
+  404), and team runs are not resumable.

package/dist/skills/anvia-studio/scripts/check-studio.sh

@@ -0,0 +1,59 @@
+#!/bin/sh
+# Heuristic checks for Anvia Studio code in an app directory.
+# Usage: sh scripts/check-studio.sh [--dir <app-root>]
+# Fails with a list of violations; passes silently with "studio OK".
+
+DIR="."
+if [ "$1" = "--dir" ] && [ -n "$2" ]; then
+  DIR="$2"
+fi
+
+ROOTS_FOUND=0
+for root in "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server"; do
+  if [ -d "$root" ]; then
+    ROOTS_FOUND=1
+    break
+  fi
+done
+if [ "$ROOTS_FOUND" -eq 0 ]; then
+  echo "ERROR: no src/app/lib/server directory under '$DIR' — nothing was checked."
+  echo "Run from the app root or pass --dir <app-root>."
+  exit 1
+fi
+
+fail=0
+violation() {
+  echo "VIOLATION: $1"
+  fail=1
+}
+warning() {
+  echo "WARNING: $1"
+}
+
+FILES=$(grep -rln --include='*.ts' \
+  -e 'new Studio(' -e '@anvia/studio' \
+  "$DIR/src" "$DIR/app" "$DIR/lib" "$DIR/server" 2>/dev/null | sort -u)
+
+if [ -z "$FILES" ]; then
+  echo "studio OK (no Studio code found)"
+  exit 0
+fi
+
+# 1. Studio must serve something.
+if echo "$FILES" | xargs grep -h -e 'new Studio(' 2>/dev/null | grep -q -e 'new Studio(\s*\[\s*\]' -e 'new Studio(\s*)'; then
+  violation "new Studio with no registered agents/teams (see references/serve.md)."
+fi
+
+# 2. Observability clients are caller-owned: close them in onShutdown (warning only).
+if echo "$FILES" | xargs grep -l -e '@anvia/langfuse' -e '@anvia/otel' -e '@anvia/lens' 2>/dev/null | grep -q .; then
+  echo "$FILES" | xargs grep -h -e 'onShutdown' 2>/dev/null | grep -q 'onShutdown' || {
+    warning "observability clients without onShutdown — they will leak on exit (see references/observe.md)."
+  }
+fi
+
+if [ "$fail" -eq 0 ]; then
+  echo "studio OK"
+  exit 0
+fi
+echo "See skills/anvia-studio/references/ for fixes."
+exit 1

package/dist/skills/release-notes/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: release-notes
+description: Draft concise product release notes from a list of shipped changes.
+---
+
+# Release Notes Skill
+
+Use this skill when the user asks for release notes, changelogs, launch notes, or a concise product update.
+
+## Process
+
+1. Read `references/style.md`.
+2. Run `scripts/draft.sh` with the shipped changes as one argument.
+3. Rewrite the script output into final release notes for the requested audience.
+
+## Output
+
+Keep the final answer short, concrete, and grouped by user-visible capability.

package/dist/skills/release-notes/references/style.md

@@ -0,0 +1,6 @@
+# Release Notes Style
+
+- Start with a one-line summary.
+- Use 3 to 5 bullets.
+- Prefer user-visible benefits over implementation details.
+- Mention breaking changes only when they affect users.

package/dist/skills/release-notes/scripts/draft.sh

@@ -0,0 +1,22 @@
+#!/bin/sh
+# Draft release-notes skeleton from a list of shipped changes (one argument,
+# one change per line). The skill rewrites this skeleton into final notes.
+
+changes="$1"
+
+if [ -z "$changes" ]; then
+  echo "usage: draft.sh \"<shipped changes, one per line>\"" >&2
+  exit 1
+fi
+
+printf 'Draft release notes\n====================\n\n'
+printf 'Summary: <one sentence covering the theme of these changes>\n\n'
+printf 'Changes:\n'
+printf '%s\n' "$changes" | while IFS= read -r line; do
+  if [ -n "$line" ]; then
+    case "$line" in
+      "- "*) line="${line#- }" ;;
+    esac
+    printf -- '- %s\n' "$line"
+  fi
+done