diff --git a/apps/api/src/routes/semantic-models.integration.test.ts b/apps/api/src/routes/semantic-models.integration.test.ts
index 7fe1083..44692fe 100644
--- a/apps/api/src/routes/semantic-models.integration.test.ts
+++ b/apps/api/src/routes/semantic-models.integration.test.ts
@@ -2,6 +2,7 @@ import { describe, it, expect, vi, beforeEach } from "vitest";
 
 const mocks = vi.hoisted(() => ({
   updateModelExtensions: vi.fn(),
+  updateDatasetMetadata: vi.fn(),
   exists: vi.fn(),
 }));
 
@@ -12,6 +13,7 @@ vi.mock("@archmax/core/config/env", () => ({
 vi.mock("@archmax/core/services/semantic-model-files", () => ({
   SemanticModelFileService: class {
     updateModelExtensions = mocks.updateModelExtensions;
+    updateDatasetMetadata = mocks.updateDatasetMetadata;
     exists = mocks.exists;
   },
 }));
@@ -68,3 +70,63 @@ describe("PATCH /semantic-models/:name/extensions", () => {
     expect(res.status).not.toBe(200);
   });
 });
+
+describe("PATCH /semantic-models/:name/datasets/:datasetName", () => {
+  it("updates dataset metadata and returns ok", async () => {
+    mocks.updateDatasetMetadata.mockResolvedValue(true);
+
+    const payload = {
+      description: "Order line items",
+      ai_context: { instructions: "Use for revenue analysis" },
+      fields: [{ name: "total_price", description: "Line total in USD" }],
+    };
+
+    const res = await app.request(`${BASE}/my-model/datasets/orders`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(payload),
+    });
+
+    expect(res.status).toBe(200);
+    const body = await jsonBody<{ ok: boolean }>(res);
+    expect(body.ok).toBe(true);
+    expect(mocks.updateDatasetMetadata).toHaveBeenCalledWith("proj1", "my-model", "orders", payload);
+  });
+
+  it("returns 404 when the dataset does not exist", async () => {
+    mocks.updateDatasetMetadata.mockResolvedValue(false);
+
+    const res = await app.request(`${BASE}/my-model/datasets/missing`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ description: "x" }),
+    });
+
+    expect(res.status).toBe(404);
+  });
+
+  it("returns 400 when the service rejects an unknown field", async () => {
+    mocks.updateDatasetMetadata.mockRejectedValue(new Error('Unknown field "ghost" in dataset "orders"'));
+
+    const res = await app.request(`${BASE}/my-model/datasets/orders`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fields: [{ name: "ghost", description: "x" }] }),
+    });
+
+    expect(res.status).toBe(400);
+    const body = await jsonBody<{ error: string }>(res);
+    expect(body.error).toMatch(/Unknown field/);
+  });
+
+  it("returns 400 for an invalid field entry payload", async () => {
+    const res = await app.request(`${BASE}/my-model/datasets/orders`, {
+      method: "PATCH",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ fields: [{ description: "missing name" }] }),
+    });
+
+    expect(res.status).not.toBe(200);
+    expect(mocks.updateDatasetMetadata).not.toHaveBeenCalled();
+  });
+});
diff --git a/apps/api/src/routes/semantic-models.ts b/apps/api/src/routes/semantic-models.ts
index bddb466..05ab7de 100644
--- a/apps/api/src/routes/semantic-models.ts
+++ b/apps/api/src/routes/semantic-models.ts
@@ -2,7 +2,7 @@ import { Hono } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v4";
 import { getEnv } from "@archmax/core/config/env";
-import { semanticModelSchema, customExtensionSchema } from "@archmax/core/services/semantic-model-schema";
+import { semanticModelSchema, customExtensionSchema, aiContextSchema } from "@archmax/core/services/semantic-model-schema";
 import { SemanticModelFileService } from "@archmax/core/services/semantic-model-files";
 import { AppError } from "../utils/errors";
 
@@ -95,6 +95,42 @@ const app = new Hono()
       return c.json({ ok: true });
     },
   )
+  .patch(
+    "/:name/datasets/:datasetName",
+    zValidator(
+      "json",
+      z.object({
+        description: z.string().optional(),
+        ai_context: aiContextSchema,
+        fields: z
+          .array(
+            z.object({
+              name: z.string().min(1),
+              description: z.string().optional(),
+              ai_context: aiContextSchema,
+            }),
+          )
+          .optional(),
+      }),
+    ),
+    async (c) => {
+      const svc = getFileService();
+      const body = c.req.valid("json");
+      let updated: boolean;
+      try {
+        updated = await svc.updateDatasetMetadata(
+          param(c, "projectId"),
+          param(c, "name"),
+          param(c, "datasetName"),
+          body,
+        );
+      } catch (err) {
+        throw AppError.badRequest(err instanceof Error ? err.message : "Invalid dataset update");
+      }
+      if (!updated) throw AppError.notFound("Dataset not found");
+      return c.json({ ok: true });
+    },
+  )
   .delete("/:name", async (c) => {
     const projectId = param(c, "projectId");
     const name = param(c, "name");
diff --git a/apps/docs/src/content/docs/guides/semantic-models.mdx b/apps/docs/src/content/docs/guides/semantic-models.mdx
index c9891a4..d28e931 100644
--- a/apps/docs/src/content/docs/guides/semantic-models.mdx
+++ b/apps/docs/src/content/docs/guides/semantic-models.mdx
@@ -150,6 +150,21 @@ The AI builder automatically creates groups when building models with 4 or more
 
 Groups use a 4-color CI palette: `sage`, `rose`, `blue`, `purple`. Colors are assigned automatically when creating groups.
 
+## Dataset Detail Panel
+
+Click any dataset node in the graph view to open the **dataset detail panel**, a vertical panel that slides in from the right edge of the graph. The panel shows the selected dataset's metadata in one place:
+
+- **Description** — the dataset's summary
+- **AI description** — the `ai_context` instructions surfaced to AI agents
+- **Synonyms** and **Examples** — the `ai_context` synonyms and examples, one entry per line
+- **Fields** — every field with its data type and description
+
+The panel spans the full height of the editor (alongside the Graph / Tree / YAML toolbar). Click a different node to switch the panel to that dataset, and use the close button in the panel header to collapse it (the node stays selected in the graph). Clicking the empty canvas clears the selection. Drag the panel's left edge to resize it.
+
+### Editing and Saving
+
+The description, AI description, synonyms, examples, and each field's description are editable directly in the panel. Make your edits and click **Save** to persist them. Saving updates only the selected dataset's YAML file — `source`, field expressions, `view_query`, and other custom extensions are left untouched. The **Save** button stays disabled until you make a change. This is a quick way to correct or enrich metadata without opening the YAML or the chat agent.
+
 ## AI Context
 
 Every entity (model, dataset, field, relationship, metric) supports `ai_context`, either a plain string or a structured object with `instructions`, `synonyms`, and `examples`. This metadata is surfaced to AI agents through MCP tools, helping them understand what the data means and how to use it.
diff --git a/apps/frontend/src/components/layout/panel-resize-handle.tsx b/apps/frontend/src/components/layout/panel-resize-handle.tsx
index ca04a0c..18330b9 100644
--- a/apps/frontend/src/components/layout/panel-resize-handle.tsx
+++ b/apps/frontend/src/components/layout/panel-resize-handle.tsx
@@ -5,6 +5,7 @@ export function useResizablePanel(
   defaultWidth: number,
   min = 180,
   max = 480,
+  invert = false,
 ) {
   const [width, setWidth] = useState(() => {
     try {
@@ -36,9 +37,8 @@ export function useResizablePanel(
       document.body.style.userSelect = "none";
 
       function onMouseMove(ev: MouseEvent) {
-        setWidth(
-          Math.max(min, Math.min(max, startW + ev.clientX - startX)),
-        );
+        const delta = invert ? startX - ev.clientX : ev.clientX - startX;
+        setWidth(Math.max(min, Math.min(max, startW + delta)));
       }
 
       function onMouseUp() {
@@ -51,7 +51,7 @@ export function useResizablePanel(
       document.addEventListener("mousemove", onMouseMove);
       document.addEventListener("mouseup", onMouseUp);
     },
-    [min, max],
+    [min, max, invert],
   );
 
   return { width, onMouseDown };
diff --git a/apps/frontend/src/components/model-visualization/dataset-detail-panel.tsx b/apps/frontend/src/components/model-visualization/dataset-detail-panel.tsx
new file mode 100644
index 0000000..7f7c101
--- /dev/null
+++ b/apps/frontend/src/components/model-visualization/dataset-detail-panel.tsx
@@ -0,0 +1,292 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { X, Save, Loader2, Database } from "lucide-react";
+import {
+  Button,
+  Textarea,
+  Label,
+  Badge,
+  Separator,
+  ScrollArea,
+  cn,
+} from "@archmax/ui";
+import type { AiContext, AiContextObject, DatasetFull } from "./types";
+import { getAiContextObject, getFieldDataType } from "./types";
+import { useUpdateDatasetMetadata, type DatasetMetadataPatch } from "./use-dataset-metadata";
+
+interface DatasetDetailPanelProps {
+  projectId: string;
+  modelName: string;
+  dataset: DatasetFull;
+  onClose: () => void;
+  className?: string;
+}
+
+interface EditState {
+  description: string;
+  aiInstructions: string;
+  /** Synonyms/examples are edited as one entry per line. */
+  synonymsText: string;
+  examplesText: string;
+  fieldDescriptions: Record<string, string>;
+}
+
+/** Parse a one-per-line editor value into a trimmed, non-empty list. */
+function parseList(text: string): string[] {
+  return text
+    .split("\n")
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+function listEqual(a: string, b: string): boolean {
+  const pa = parseList(a);
+  const pb = parseList(b);
+  return pa.length === pb.length && pa.every((v, i) => v === pb[i]);
+}
+
+function deriveState(ds: DatasetFull): EditState {
+  const fieldDescriptions: Record<string, string> = {};
+  for (const f of ds.fields) fieldDescriptions[f.name] = f.description ?? "";
+  const ai = getAiContextObject(ds.ai_context);
+  return {
+    description: ds.description ?? "",
+    aiInstructions: ai.instructions ?? "",
+    synonymsText: (ai.synonyms ?? []).join("\n"),
+    examplesText: (ai.examples ?? []).join("\n"),
+    fieldDescriptions,
+  };
+}
+
+/**
+ * Merge a fresh on-disk snapshot into the working editor state, preserving
+ * fields the user has actively edited (where `current` diverges from the
+ * previous `baseline`) while refreshing untouched fields to their latest
+ * persisted value. This keeps the panel in sync with background refetches
+ * without clobbering in-progress edits.
+ */
+function resyncUntouched(current: EditState, baseline: EditState, next: EditState): EditState {
+  const fieldDescriptions: Record<string, string> = {};
+  for (const name of Object.keys(next.fieldDescriptions)) {
+    const cur = current.fieldDescriptions[name] ?? "";
+    const base = baseline.fieldDescriptions[name] ?? "";
+    fieldDescriptions[name] = cur !== base ? cur : next.fieldDescriptions[name];
+  }
+  return {
+    description: current.description !== baseline.description ? current.description : next.description,
+    aiInstructions:
+      current.aiInstructions !== baseline.aiInstructions ? current.aiInstructions : next.aiInstructions,
+    synonymsText: !listEqual(current.synonymsText, baseline.synonymsText)
+      ? current.synonymsText
+      : next.synonymsText,
+    examplesText: !listEqual(current.examplesText, baseline.examplesText)
+      ? current.examplesText
+      : next.examplesText,
+    fieldDescriptions,
+  };
+}
+
+function isAiDirty(edit: EditState, baseline: EditState): boolean {
+  return (
+    edit.aiInstructions !== baseline.aiInstructions ||
+    !listEqual(edit.synonymsText, baseline.synonymsText) ||
+    !listEqual(edit.examplesText, baseline.examplesText)
+  );
+}
+
+function isDirty(edit: EditState, baseline: EditState): boolean {
+  if (edit.description !== baseline.description) return true;
+  if (isAiDirty(edit, baseline)) return true;
+  return Object.keys(baseline.fieldDescriptions).some(
+    (name) => (edit.fieldDescriptions[name] ?? "") !== baseline.fieldDescriptions[name],
+  );
+}
+
+/**
+ * Build an `ai_context` payload from the editable instructions, synonyms, and
+ * examples. Returns "" to clear the context entirely when nothing remains.
+ */
+function buildAiContext(edit: EditState): AiContext {
+  const next: AiContextObject = {};
+  const instructions = edit.aiInstructions.trim();
+  const synonyms = parseList(edit.synonymsText);
+  const examples = parseList(edit.examplesText);
+  if (instructions) next.instructions = instructions;
+  if (synonyms.length > 0) next.synonyms = synonyms;
+  if (examples.length > 0) next.examples = examples;
+  if (!next.instructions && !next.synonyms && !next.examples) return "";
+  return next;
+}
+
+export function DatasetDetailPanel({
+  projectId,
+  modelName,
+  dataset,
+  onClose,
+  className,
+}: DatasetDetailPanelProps) {
+  const [baseline, setBaseline] = useState<EditState>(() => deriveState(dataset));
+  const [edit, setEdit] = useState<EditState>(baseline);
+  const baselineRef = useRef(baseline);
+  baselineRef.current = baseline;
+  const lastNameRef = useRef(dataset.name);
+
+  // Keep the editor in sync with the latest `dataset` prop. Switching datasets
+  // fully resets; a background refetch of the same dataset refreshes the
+  // baseline and any untouched fields while preserving in-progress edits.
+  useEffect(() => {
+    const next = deriveState(dataset);
+    if (lastNameRef.current !== dataset.name) {
+      lastNameRef.current = dataset.name;
+      setBaseline(next);
+      setEdit(next);
+      return;
+    }
+    setEdit((cur) => resyncUntouched(cur, baselineRef.current, next));
+    setBaseline(next);
+  }, [dataset]);
+
+  const mutation = useUpdateDatasetMetadata(projectId, modelName);
+
+  const dirty = isDirty(edit, baseline);
+
+  const handleSave = useCallback(() => {
+    const patch: DatasetMetadataPatch = {};
+    if (edit.description !== baseline.description) patch.description = edit.description;
+    if (isAiDirty(edit, baseline)) {
+      patch.ai_context = buildAiContext(edit);
+    }
+    const changedFields = Object.keys(baseline.fieldDescriptions)
+      .filter((name) => (edit.fieldDescriptions[name] ?? "") !== baseline.fieldDescriptions[name])
+      .map((name) => ({ name, description: edit.fieldDescriptions[name] ?? "" }));
+    if (changedFields.length > 0) patch.fields = changedFields;
+    if (Object.keys(patch).length === 0) return;
+    mutation.mutate({ datasetName: dataset.name, patch });
+  }, [edit, baseline, dataset, mutation]);
+
+  return (
+    <div className={cn("flex h-full flex-col bg-muted", className)}>
+      <div className="flex items-start justify-between gap-2 border-b border-border px-4 py-3">
+        <div className="min-w-0">
+          <div className="flex items-center gap-1.5">
+            <Database className="h-3.5 w-3.5 shrink-0 text-muted-foreground" />
+            <h2 className="truncate text-sm font-medium">{dataset.name}</h2>
+          </div>
+          <p className="truncate text-xs text-muted-foreground" title={dataset.source}>
+            {dataset.source}
+          </p>
+        </div>
+        <div className="flex shrink-0 items-center gap-1">
+          <button
+            onClick={handleSave}
+            disabled={!dirty || mutation.isPending}
+            className="inline-flex items-center gap-1 rounded-md bg-foreground px-1.5 py-0.5 text-[10px] font-medium text-background transition-colors hover:bg-foreground/80 disabled:opacity-50"
+          >
+            {mutation.isPending ? (
+              <Loader2 className="h-3 w-3 animate-spin" />
+            ) : (
+              <Save className="h-3 w-3" />
+            )}
+            Save
+          </button>
+          <Button variant="ghost" size="icon-sm" onClick={onClose} title="Close panel">
+            <X className="h-3.5 w-3.5" />
+          </Button>
+        </div>
+      </div>
+
+      <ScrollArea className="flex-1 min-h-0">
+        <div className="space-y-5 p-4">
+          <section className="space-y-1.5">
+            <Label htmlFor="dataset-description">Description</Label>
+            <Textarea
+              id="dataset-description"
+              value={edit.description}
+              onChange={(e) => setEdit((cur) => ({ ...cur, description: e.target.value }))}
+              placeholder="Summarize what this dataset represents…"
+              rows={3}
+              className="text-xs"
+            />
+          </section>
+
+          <section className="space-y-1.5">
+            <Label htmlFor="dataset-ai-context">AI description</Label>
+            <Textarea
+              id="dataset-ai-context"
+              value={edit.aiInstructions}
+              onChange={(e) => setEdit((cur) => ({ ...cur, aiInstructions: e.target.value }))}
+              placeholder="Guidance for AI agents using this dataset…"
+              rows={4}
+              className="text-xs"
+            />
+          </section>
+
+          <section className="space-y-1.5">
+            <Label htmlFor="dataset-synonyms">Synonyms</Label>
+            <Textarea
+              id="dataset-synonyms"
+              value={edit.synonymsText}
+              onChange={(e) => setEdit((cur) => ({ ...cur, synonymsText: e.target.value }))}
+              placeholder="One synonym per line…"
+              rows={2}
+              className="text-xs"
+            />
+          </section>
+
+          <section className="space-y-1.5">
+            <Label htmlFor="dataset-examples">Examples</Label>
+            <Textarea
+              id="dataset-examples"
+              value={edit.examplesText}
+              onChange={(e) => setEdit((cur) => ({ ...cur, examplesText: e.target.value }))}
+              placeholder="One example per line…"
+              rows={2}
+              className="text-xs"
+            />
+          </section>
+
+          <Separator />
+
+          <section className="space-y-3">
+            <div className="flex items-center justify-between">
+              <Label>Fields</Label>
+              <span className="text-xs text-muted-foreground tabular-nums">{dataset.fields.length}</span>
+            </div>
+            {dataset.fields.length === 0 ? (
+              <p className="text-xs text-muted-foreground">This dataset has no fields.</p>
+            ) : (
+              <div className="space-y-3">
+                {dataset.fields.map((field) => {
+                  const dataType = getFieldDataType(field);
+                  return (
+                    <div key={field.name} className="rounded-xl border border-border bg-card p-3">
+                      <div className="flex items-center justify-between gap-2">
+                        <span className="truncate font-mono text-xs font-medium">{field.name}</span>
+                        {dataType && (
+                          <Badge variant="secondary" className="shrink-0 text-[10px]">
+                            {dataType}
+                          </Badge>
+                        )}
+                      </div>
+                      <Textarea
+                        value={edit.fieldDescriptions[field.name] ?? ""}
+                        onChange={(e) =>
+                          setEdit((cur) => ({
+                            ...cur,
+                            fieldDescriptions: { ...cur.fieldDescriptions, [field.name]: e.target.value },
+                          }))
+                        }
+                        placeholder="Describe this field…"
+                        rows={2}
+                        className="mt-2 text-xs"
+                      />
+                    </div>
+                  );
+                })}
+              </div>
+            )}
+          </section>
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
diff --git a/apps/frontend/src/components/model-visualization/model-graph-view.tsx b/apps/frontend/src/components/model-visualization/model-graph-view.tsx
index a911769..084caf5 100644
--- a/apps/frontend/src/components/model-visualization/model-graph-view.tsx
+++ b/apps/frontend/src/components/model-visualization/model-graph-view.tsx
@@ -23,6 +23,7 @@ import type { SemanticModelFull, ModelDiff, CustomExtension, DatasetGroup } from
 import {
   getRelationshipColumns,
   getFieldDataType,
+  getAiInstructions,
   parseDatasetGroups,
   serializeDatasetGroups,
   getGroupColor,
@@ -56,12 +57,7 @@ function parsePosition(extensions?: CustomExtension[]): { x: number; y: number }
 
 function getDescription(ds: SemanticModelFull["datasets"][number]): string | undefined {
   if (ds.description) return ds.description;
-  const ctx = (ds as Record<string, unknown>).ai_context;
-  if (typeof ctx === "string") return ctx;
-  if (ctx && typeof ctx === "object" && "instructions" in ctx) {
-    return (ctx as { instructions?: string }).instructions;
-  }
-  return undefined;
+  return getAiInstructions(ds.ai_context) || undefined;
 }
 
 function autoLayout(
@@ -253,6 +249,8 @@ interface ModelGraphViewProps {
   model: SemanticModelFull;
   diff: ModelDiff;
   className?: string;
+  selectedDataset?: string | null;
+  onSelectDataset?: (name: string | null) => void;
 }
 
 export function ModelGraphView({
@@ -261,6 +259,8 @@ export function ModelGraphView({
   model,
   diff,
   className,
+  selectedDataset = null,
+  onSelectDataset,
 }: ModelGraphViewProps) {
   const initial = useMemo(() => buildNodesAndEdges(model, diff), [model, diff]);
   const [nodes, setNodes, onNodesChange] = useNodesState(initial.nodes);
@@ -432,8 +432,19 @@ export function ModelGraphView({
   );
 
   const allNodes = useMemo(
-    () => [...groupBoxNodes, ...nodes] as Node[],
-    [groupBoxNodes, nodes],
+    () => [
+      ...groupBoxNodes,
+      ...nodes.map((n) => (n.selected === (n.id === selectedDataset) ? n : { ...n, selected: n.id === selectedDataset })),
+    ] as Node[],
+    [groupBoxNodes, nodes, selectedDataset],
+  );
+
+  const handleNodeClick = useCallback(
+    (_e: React.MouseEvent, node: Node) => {
+      if (node.type !== "dataset") return;
+      onSelectDataset?.(node.id);
+    },
+    [onSelectDataset],
   );
 
   const handleNodeContextMenu = useCallback(
@@ -451,6 +462,11 @@ export function ModelGraphView({
     setRenamingGroupId(null);
   }, []);
 
+  const handlePaneClick = useCallback(() => {
+    dismissMenu();
+    onSelectDataset?.(null);
+  }, [dismissMenu, onSelectDataset]);
+
   const findGroupForDataset = useCallback(
     (dsName: string) => groups.find((g) => g.datasets.includes(dsName)),
     [groups],
@@ -562,9 +578,10 @@ export function ModelGraphView({
         onNodeDragStart={handleNodeDragStart}
         onNodeDrag={handleNodeDrag}
         onNodeDragStop={handleNodeDragStop}
+        onNodeClick={handleNodeClick}
         onNodeContextMenu={handleNodeContextMenu}
         onMoveEnd={handleMoveEnd}
-        onPaneClick={dismissMenu}
+        onPaneClick={handlePaneClick}
         nodeTypes={nodeTypes}
         defaultViewport={savedViewport ?? undefined}
         fitView={!savedViewport}
diff --git a/apps/frontend/src/components/model-visualization/model-visualization.tsx b/apps/frontend/src/components/model-visualization/model-visualization.tsx
index b23c02a..314d6f4 100644
--- a/apps/frontend/src/components/model-visualization/model-visualization.tsx
+++ b/apps/frontend/src/components/model-visualization/model-visualization.tsx
@@ -6,8 +6,10 @@ import { toast } from "sonner";
 import { ModelYamlView } from "./model-yaml-view";
 import { ModelTreeView } from "./model-tree-view";
 import { ModelGraphView } from "./model-graph-view";
+import { DatasetDetailPanel } from "./dataset-detail-panel";
 import { useModelDiff } from "./use-model-diff";
 import type { SemanticModelFull } from "./types";
+import { PanelResizeHandle, useResizablePanel } from "@/components/layout/panel-resize-handle";
 import { api } from "@/lib/api";
 
 const DEFAULT_TAB = "graph";
@@ -39,11 +41,27 @@ export function ModelVisualization({
   modelName,
 }: ModelVisualizationProps) {
   const [tab, setTab] = useState(() => getTabPreference(modelName));
+  const [selectedDataset, setSelectedDataset] = useState<string | null>(null);
+  const [panelOpen, setPanelOpen] = useState(false);
+  const { width: panelWidth, onMouseDown: onPanelResize } = useResizablePanel(
+    "archmax:dataset-panel-width",
+    360,
+    280,
+    560,
+    true,
+  );
 
   useEffect(() => {
     setTab(getTabPreference(modelName));
+    setSelectedDataset(null);
+    setPanelOpen(false);
   }, [modelName]);
 
+  const handleSelectDataset = useCallback((name: string | null) => {
+    setSelectedDataset(name);
+    setPanelOpen(name !== null);
+  }, []);
+
   const handleTabChange = useCallback(
     (value: string) => {
       setTab(value);
@@ -66,6 +84,10 @@ export function ModelVisualization({
 
   const diff = useModelDiff(model ?? null);
 
+  const selectedDatasetData = selectedDataset
+    ? model?.datasets.find((d) => d.name === selectedDataset) ?? null
+    : null;
+
   const handleDownload = useCallback(async () => {
     try {
       const res = await api.api.projects[":projectId"]["semantic-models"][":name"].yaml.$get({
@@ -101,59 +123,82 @@ export function ModelVisualization({
     );
   }
 
+  const showPanel = tab === "graph" && panelOpen && !!selectedDatasetData && !model.hasConflicts;
+
   return (
-    <div className="flex h-full flex-col">
-      <Tabs value={tab} onValueChange={handleTabChange} className="flex-1 min-h-0 flex flex-col">
-        <div className="grid grid-cols-[1fr_auto_1fr] items-center px-4 pt-2">
-          <div />
-          <TabsList variant="pill">
-            <TabsTrigger value="graph">
-              <Network className="h-3.5 w-3.5" />
-              Graph
-            </TabsTrigger>
-            <TabsTrigger value="tree">
-              <TreePine className="h-3.5 w-3.5" />
-              Tree
-            </TabsTrigger>
-            <TabsTrigger value="yaml">
-              <Code className="h-3.5 w-3.5" />
-              YAML
-            </TabsTrigger>
-          </TabsList>
-          <div className="flex justify-end">
-            <Button variant="ghost" size="icon-sm" onClick={handleDownload} title="Download YAML">
-              <Download className="h-3.5 w-3.5" />
-            </Button>
+    <div className="flex h-full">
+      <div className="flex min-w-0 flex-1 flex-col">
+        <Tabs value={tab} onValueChange={handleTabChange} className="flex-1 min-h-0 flex flex-col">
+          <div className="grid grid-cols-[1fr_auto_1fr] items-center px-4 pt-2">
+            <div />
+            <TabsList variant="pill">
+              <TabsTrigger value="graph">
+                <Network className="h-3.5 w-3.5" />
+                Graph
+              </TabsTrigger>
+              <TabsTrigger value="tree">
+                <TreePine className="h-3.5 w-3.5" />
+                Tree
+              </TabsTrigger>
+              <TabsTrigger value="yaml">
+                <Code className="h-3.5 w-3.5" />
+                YAML
+              </TabsTrigger>
+            </TabsList>
+            <div className="flex justify-end">
+              <Button variant="ghost" size="icon-sm" onClick={handleDownload} title="Download YAML">
+                <Download className="h-3.5 w-3.5" />
+              </Button>
+            </div>
           </div>
-        </div>
-
-        <TabsContent value="graph" className="flex-1 min-h-0">
-          {model.hasConflicts ? (
-            <ConflictBanner />
-          ) : (
-            <ModelGraphView
-              key={modelName}
+
+          <TabsContent value="graph" className="flex-1 min-h-0">
+            {model.hasConflicts ? (
+              <ConflictBanner />
+            ) : (
+              <ModelGraphView
+                key={modelName}
+                projectId={projectId}
+                modelName={modelName}
+                model={model}
+                diff={diff}
+                className="h-full"
+                selectedDataset={selectedDataset}
+                onSelectDataset={handleSelectDataset}
+              />
+            )}
+          </TabsContent>
+
+          <TabsContent value="tree" className="flex-1 min-h-0">
+            {model.hasConflicts ? (
+              <ConflictBanner />
+            ) : (
+              <ModelTreeView model={model} diff={diff} className="h-full" />
+            )}
+          </TabsContent>
+
+          <TabsContent value="yaml" className="flex-1 min-h-0">
+            <ModelYamlView projectId={projectId} modelName={modelName} className="h-full" />
+          </TabsContent>
+        </Tabs>
+      </div>
+
+      {showPanel && selectedDatasetData && (
+        <>
+          <PanelResizeHandle onMouseDown={onPanelResize} />
+          <div
+            className="h-full shrink-0 animate-in slide-in-from-right duration-200"
+            style={{ width: panelWidth }}
+          >
+            <DatasetDetailPanel
               projectId={projectId}
               modelName={modelName}
-              model={model}
-              diff={diff}
-              className="h-full"
+              dataset={selectedDatasetData}
+              onClose={() => setPanelOpen(false)}
             />
-          )}
-        </TabsContent>
-
-        <TabsContent value="tree" className="flex-1 min-h-0">
-          {model.hasConflicts ? (
-            <ConflictBanner />
-          ) : (
-            <ModelTreeView model={model} diff={diff} className="h-full" />
-          )}
-        </TabsContent>
-
-        <TabsContent value="yaml" className="flex-1 min-h-0">
-          <ModelYamlView projectId={projectId} modelName={modelName} className="h-full" />
-        </TabsContent>
-      </Tabs>
+          </div>
+        </>
+      )}
     </div>
   );
 }
diff --git a/apps/frontend/src/components/model-visualization/types.ts b/apps/frontend/src/components/model-visualization/types.ts
index 7512012..5bc593c 100644
--- a/apps/frontend/src/components/model-visualization/types.ts
+++ b/apps/frontend/src/components/model-visualization/types.ts
@@ -1,6 +1,15 @@
+export type AiContextObject = {
+  instructions?: string;
+  synonyms?: string[];
+  examples?: string[];
+};
+
+export type AiContext = string | AiContextObject;
+
 export interface SemanticModelFull {
   name: string;
   description?: string;
+  ai_context?: AiContext;
   datasets: DatasetFull[];
   relationships: RelationshipFull[];
   metrics: MetricFull[];
@@ -13,6 +22,7 @@ export interface DatasetFull {
   name: string;
   source: string;
   description?: string;
+  ai_context?: AiContext;
   fields: FieldFull[];
   custom_extensions?: CustomExtension[];
   [key: string]: unknown;
@@ -22,6 +32,7 @@ export interface FieldFull {
   name: string;
   expression: string | { dialects?: Array<{ dialect: string; expression: string }> };
   description?: string;
+  ai_context?: AiContext;
   label?: string;
   custom_extensions?: CustomExtension[];
   [key: string]: unknown;
@@ -148,6 +159,16 @@ export function getExpressionString(
   return expr.dialects?.[0]?.expression ?? "";
 }
 
+export function getAiContextObject(ctx?: AiContext): AiContextObject {
+  if (!ctx) return {};
+  if (typeof ctx === "string") return { instructions: ctx };
+  return ctx;
+}
+
+export function getAiInstructions(ctx?: AiContext): string {
+  return getAiContextObject(ctx).instructions ?? "";
+}
+
 export function getRelationshipColumns(r: RelationshipFull): { from: string[]; to: string[] } {
   return {
     from: r.fromColumns ?? r.from_columns ?? [],
diff --git a/apps/frontend/src/components/model-visualization/use-dataset-metadata.ts b/apps/frontend/src/components/model-visualization/use-dataset-metadata.ts
new file mode 100644
index 0000000..fdaf1bc
--- /dev/null
+++ b/apps/frontend/src/components/model-visualization/use-dataset-metadata.ts
@@ -0,0 +1,34 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { toast } from "sonner";
+import { api } from "@/lib/api";
+import type { AiContext } from "./types";
+
+export interface DatasetMetadataPatch {
+  description?: string;
+  ai_context?: AiContext;
+  fields?: Array<{ name: string; description?: string; ai_context?: AiContext }>;
+}
+
+export function useUpdateDatasetMetadata(projectId: string, modelName: string) {
+  const queryClient = useQueryClient();
+  return useMutation({
+    mutationFn: async ({ datasetName, patch }: { datasetName: string; patch: DatasetMetadataPatch }) => {
+      const res = await api.api.projects[":projectId"]["semantic-models"][":name"].datasets[
+        ":datasetName"
+      ].$patch({
+        param: { projectId, name: modelName, datasetName },
+        json: patch,
+      });
+      if (!res.ok) {
+        const data = await res.json().catch(() => null);
+        throw new Error((data as { error?: string } | null)?.error ?? "Failed to save dataset");
+      }
+      return res.json();
+    },
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ["semantic-model", projectId, modelName] });
+      toast.success("Dataset saved");
+    },
+    onError: (err) => toast.error(err instanceof Error ? err.message : "Failed to save dataset"),
+  });
+}
diff --git a/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx b/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
index 79091a3..68868d3 100644
--- a/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
+++ b/apps/frontend/src/routes/_auth/$projectId/connections/index.tsx
@@ -128,6 +128,7 @@ function ConnectionsPage() {
     mutationFn: async () => {
       const res = await api.api.projects[":projectId"].connections.reinit.$post({
         param: { projectId: project._id },
+        query: {},
       });
       const body = (await res.json()) as
         | { ok: true; tableCount: number }
diff --git a/apps/frontend/src/routes/_auth/$projectId/mcp-access.tsx b/apps/frontend/src/routes/_auth/$projectId/mcp-access.tsx
index d82cf42..83bee1c 100644
--- a/apps/frontend/src/routes/_auth/$projectId/mcp-access.tsx
+++ b/apps/frontend/src/routes/_auth/$projectId/mcp-access.tsx
@@ -416,7 +416,7 @@ function CreateTokenDialog({
         },
       });
       if (!res.ok) {
-        const err = await res.json() as { error?: string };
+        const err = (await res.json()) as unknown as { error?: string };
         throw new Error(err.error || "Failed to create token");
       }
       return res.json() as Promise<{ token: string }>;
diff --git a/openspec/changes/add-dataset-detail-panel/design.md b/openspec/changes/add-dataset-detail-panel/design.md
new file mode 100644
index 0000000..e3d1138
--- /dev/null
+++ b/openspec/changes/add-dataset-detail-panel/design.md
@@ -0,0 +1,48 @@
+## Context
+
+The graph view (`model-visualization/`) is a React Flow canvas that loads the full `SemanticModelFull` via a single GET and refetches every 10s. Dataset nodes currently support only React Flow's built-in selection ring; there is no detail/inspector surface and no frontend write path for semantic metadata. Existing writes are extensions-only PATCH routes (graph positions, groups) and a full `PUT /:name` that replaces the entire model (used by the agent/tests, never by the UI).
+
+This change adds a right-side detail panel for viewing and lightly editing dataset metadata. Two decisions carry real trade-offs: the panel mechanism (overlay Sheet vs inline resizable column) and the save write path (full PUT-with-merge vs a new granular PATCH).
+
+## Goals / Non-Goals
+
+- **Goals**
+  - View a dataset's AI description / `ai_context`, summary/description, and per-field descriptions from the graph.
+  - Slide-in panel anchored to the far right of the graph area, collapsible/closable.
+  - Manual editing of dataset description, `ai_context`, and per-field descriptions with an explicit Save.
+  - A surgical, race-safe persistence path that does not rewrite unrelated model content.
+- **Non-Goals**
+  - Editing fields' `expression` / `view_query` / source mappings (semantic SQL stays agent-owned).
+  - Adding/removing datasets, fields, relationships, or metrics from the panel.
+  - Editing relationships or metrics (datasets only in this change).
+  - Real-time collaborative editing or conflict resolution beyond last-write-wins on a single dataset file.
+
+## Decisions
+
+- **Decision: Panel is an inline resizable right column scoped to the Graph tab, not a global overlay Sheet.**
+  - The panel lives inside the Graph `TabsContent` in `ModelVisualization`, mirroring the existing left-sidebar pattern (`useResizablePanel` + `PanelResizeHandle`) already used on the models page. It slides in when a dataset is selected and collapses/closes via a toggle, leaving the graph canvas to reflow into the freed width.
+  - Alternatives considered: `Sheet` overlay (used by `monitoring.tsx`). Rejected as the primary because an overlay floats above and obscures the graph, breaking the "click node → see it in context" flow and the graph's pan/zoom. A Sheet is also modal-ish on small screens. The inline column keeps node and details visible together.
+
+- **Decision: Persist edits via a new granular `PATCH /:name/datasets/:datasetName` route, not full PUT-with-merge.**
+  - The route accepts a partial dataset metadata payload (`description?`, `ai_context?`, and `fields?: Array<{ name, description?, ai_context? }>` keyed by field name). A new `SemanticModelFileService.updateDatasetMetadata` reads the single dataset YAML file, merges the provided metadata, preserves all other content (`source`, `primary_key`, `fields[].expression`, `custom_extensions`, `view_query`), and writes atomically (temp file + rename), consistent with `updateDatasetExtensions`.
+  - Alternatives considered: PUT-with-merge (read cached `SemanticModelFull`, splice the edited dataset, PUT the whole model). Rejected: it races with the 10s refetch and the agent, rewrites every dataset file on each save, and risks clobbering concurrent agent edits to other datasets. The granular PATCH only touches the one dataset file, matching the existing extensions-PATCH precedent.
+
+- **Decision: Selection state lives in `ModelVisualization`, lifted out of React Flow.**
+  - `ModelGraphView` gains an `onSelectDataset(name | null)` callback wired to `onNodeClick`; `onPaneClick` clears selection. The selected dataset name and panel open/collapsed state are owned by `ModelVisualization` so the panel persists across node clicks and the panel content re-reads from the already-loaded `SemanticModelFull`.
+
+- **Decision: Add explicit `ai_context` to frontend `DatasetFull` / `FieldFull` types.**
+  - Replaces the current `[key: string]: unknown` cast access. The type mirrors `aiContextSchema` (string | `{ instructions?, synonyms?, examples? }`).
+
+## Risks / Trade-offs
+
+- **Stale edits vs 10s refetch / agent writes** → On successful save, invalidate the `["semantic-model", projectId, modelName]` query so the panel reflects the canonical file; last-write-wins per dataset file is acceptable for a single-user system.
+- **Editing while the agent is streaming changes** → Save targets only the selected dataset file; other datasets are untouched. Acceptable given non-goals.
+- **Field list size** → Datasets can have many fields; the field section is scrollable and field edits send only changed fields keyed by name.
+
+## Migration Plan
+
+Additive only. New API route + file-service method + new frontend component. No schema or data migrations. Existing YAML files remain valid; the PATCH merges into whatever metadata already exists.
+
+## Open Questions
+
+- Should `ai_context` be editable as raw structured fields (instructions/synonyms/examples) or a single instructions textarea in this iteration? Initial implementation edits the `instructions` string and the dataset `description`; full structured editing can follow.
diff --git a/openspec/changes/add-dataset-detail-panel/proposal.md b/openspec/changes/add-dataset-detail-panel/proposal.md
new file mode 100644
index 0000000..d0a8260
--- /dev/null
+++ b/openspec/changes/add-dataset-detail-panel/proposal.md
@@ -0,0 +1,26 @@
+# Change: Dataset Detail Panel in Graph View
+
+## Why
+
+The semantic model graph view lets users see datasets and their relationships, but there is no way to browse the full semantic metadata (AI description / `ai_context`, summary, per-field descriptions) for a dataset, nor to correct it manually. Today the only way to edit this metadata is through the AI chat agent or by hand-editing YAML. Users need an inline, reviewable surface to inspect and lightly edit dataset metadata directly from the graph.
+
+## What Changes
+
+- Clicking a dataset node in the graph view selects it and opens a vertical detail panel on the far right of the graph area.
+- The panel slides in from the right and can be collapsed/closed again; its open/collapsed state is preserved while navigating between datasets.
+- The panel displays the selected dataset's semantic metadata: name, source, AI description / `ai_context` (instructions, synonyms, examples), summary/description, and a list of fields with their descriptions and `ai_context`.
+- The panel includes editable inputs for the dataset description, `ai_context`, and per-field descriptions, plus a **Save** button that persists manual edits.
+- A new granular API write path persists dataset metadata edits without rewriting the entire model: `PATCH /api/projects/:projectId/semantic-models/:name/datasets/:datasetName`, backed by a new `SemanticModelFileService.updateDatasetMetadata` method that merges metadata into the dataset's YAML file atomically.
+- Frontend `SemanticModelFull` / `DatasetFull` / `FieldFull` types gain an explicitly-typed `ai_context` field so the panel reads metadata without unsafe casts.
+
+## Impact
+
+- Affected specs: `semantic-models`
+- Affected code:
+  - `apps/frontend/src/components/model-visualization/model-graph-view.tsx` (node click → selection state)
+  - `apps/frontend/src/components/model-visualization/model-visualization.tsx` (host the panel inside the Graph tab)
+  - new `apps/frontend/src/components/model-visualization/dataset-detail-panel.tsx`
+  - `apps/frontend/src/components/model-visualization/types.ts` (typed `ai_context`)
+  - `apps/api/src/routes/semantic-models.ts` (new dataset metadata PATCH route)
+  - `packages/core/src/services/semantic-model-files.ts` (`updateDatasetMetadata`)
+  - `apps/docs` (graph view documentation page)
diff --git a/openspec/changes/add-dataset-detail-panel/specs/semantic-models/spec.md b/openspec/changes/add-dataset-detail-panel/specs/semantic-models/spec.md
new file mode 100644
index 0000000..77f3db7
--- /dev/null
+++ b/openspec/changes/add-dataset-detail-panel/specs/semantic-models/spec.md
@@ -0,0 +1,109 @@
+## ADDED Requirements
+
+### Requirement: Dataset Detail Panel in Graph View
+
+The system SHALL render a vertical dataset detail panel anchored to the far-right edge of the graph view area. The panel SHALL be hidden by default and SHALL slide in from the right when a user clicks a dataset node in the graph. Clicking a dataset node SHALL set it as the selected dataset; clicking the empty graph pane SHALL clear the selection. The panel SHALL be collapsible/closable via a control in the panel header, and closing the panel SHALL NOT clear the underlying graph selection ring. While the panel is open, clicking a different dataset node SHALL update the panel content to that dataset without closing the panel. The graph canvas SHALL reflow to use the remaining width while the panel is open.
+
+#### Scenario: Clicking a dataset opens the panel
+
+- **WHEN** a user clicks a dataset node in the graph view
+- **THEN** the dataset detail panel slides in from the far right
+- **AND** the panel displays the clicked dataset's metadata
+
+#### Scenario: Switching datasets updates the open panel
+
+- **WHEN** the detail panel is open and the user clicks a different dataset node
+- **THEN** the panel content updates to the newly clicked dataset
+- **AND** the panel remains open
+
+#### Scenario: Closing the panel
+
+- **WHEN** the user clicks the close/collapse control in the panel header
+- **THEN** the panel slides out and the graph canvas reclaims the freed width
+
+#### Scenario: Clicking the empty pane clears selection
+
+- **WHEN** a dataset is selected and the user clicks the empty graph pane
+- **THEN** the dataset selection is cleared
+
+### Requirement: Dataset Detail Panel Content
+
+The dataset detail panel SHALL display, for the selected dataset, the dataset name, source reference, the AI description / `ai_context` (rendered as instructions, synonyms, and examples when `ai_context` is a structured object, or as text when it is a string), the dataset description/summary, and a scrollable list of the dataset's fields. Each field entry SHALL show the field name, its data type (from the COMMON `data_type` custom extension when present), its description, and its `ai_context`. The panel SHALL read this metadata from the already-loaded full semantic model and SHALL NOT require an additional fetch.
+
+#### Scenario: Panel shows dataset AI description and summary
+
+- **WHEN** the selected dataset has a `description` and an `ai_context` object with `instructions`
+- **THEN** the panel displays both the description and the AI instructions
+
+#### Scenario: Panel lists fields with descriptions
+
+- **WHEN** the selected dataset has fields with `description` and `data_type` COMMON extensions
+- **THEN** the panel lists each field with its name, data type, and description
+
+#### Scenario: Dataset with no AI context
+
+- **WHEN** the selected dataset has no `ai_context`
+- **THEN** the panel omits the AI description section without error
+
+### Requirement: Manual Dataset Metadata Editing
+
+The dataset detail panel SHALL provide editable inputs for the dataset description, the dataset `ai_context` instructions, the dataset `ai_context` synonyms and examples (each edited as one entry per line), and each field's description. The panel SHALL include a **Save** button that persists the edits via the dataset metadata update API. The Save button SHALL be disabled when there are no unsaved changes and SHALL show a pending state while the request is in flight. On success, the system SHALL show a success toast ("Dataset saved") and invalidate the cached semantic model so the panel reflects the persisted content. On failure, the system SHALL show an error toast with the server message and SHALL preserve the user's in-progress edits.
+
+#### Scenario: Saving edited dataset metadata
+
+- **WHEN** the user edits the dataset description and clicks Save
+- **THEN** the edit is persisted via the dataset metadata update API
+- **AND** a "Dataset saved" success toast is shown
+- **AND** the cached semantic model is invalidated
+
+#### Scenario: Save disabled with no changes
+
+- **WHEN** the panel is open and the user has made no edits
+- **THEN** the Save button is disabled
+
+#### Scenario: Save failure preserves edits
+
+- **WHEN** a save request fails
+- **THEN** an error toast with the server message is shown
+- **AND** the user's in-progress edits remain in the inputs
+
+#### Scenario: Editing synonyms and examples
+
+- **WHEN** the user enters synonyms and examples (one per line) and clicks Save
+- **THEN** the dataset's `ai_context` is persisted with the corresponding `synonyms` and `examples` arrays
+- **AND** clearing all of instructions, synonyms, and examples removes the `ai_context` entirely
+
+### Requirement: Dataset Metadata Update API
+
+The system SHALL expose a `PATCH /api/projects/:projectId/semantic-models/:name/datasets/:datasetName` endpoint, protected by session-based admin auth, that accepts a partial dataset metadata payload `{ description?: string; ai_context?: AiContext; fields?: Array<{ name: string; description?: string; ai_context?: AiContext }> }`. The endpoint SHALL atomically merge the provided metadata into the dataset's YAML file without altering `source`, `primary_key`, `unique_keys`, field `expression` values, `custom_extensions`, or the dataset `view_query`. Field entries SHALL be matched by `name`; unknown field names SHALL be rejected with a descriptive error. Requests targeting a non-existent model or dataset SHALL return a 404. The `SemanticModelFileService` SHALL provide an `updateDatasetMetadata` method that reads the dataset file, merges the metadata, and writes it back atomically (temp file + rename).
+
+#### Scenario: Patch updates dataset description and ai_context
+
+- **WHEN** a PATCH request is sent with `{ description: "Order line items", ai_context: { instructions: "Use for revenue analysis" } }`
+- **THEN** the dataset YAML file's `description` and `ai_context` are updated
+- **AND** the dataset's `source`, fields' `expression`, and `custom_extensions` are unchanged
+
+#### Scenario: Patch updates individual field descriptions
+
+- **WHEN** a PATCH request includes `fields: [{ name: "total_price", description: "Line total in USD" }]`
+- **THEN** only the `total_price` field's description is updated
+- **AND** all other fields are unchanged
+
+#### Scenario: Patch with unknown field name is rejected
+
+- **WHEN** a PATCH request references a field name not present in the dataset
+- **THEN** the API returns an error and no changes are written
+
+#### Scenario: Patch targets non-existent dataset
+
+- **WHEN** a PATCH request targets a dataset name that does not exist in the model
+- **THEN** the API returns a 404 error
+
+### Requirement: Typed AI Context on Frontend Model Types
+
+The frontend `SemanticModelFull`, `DatasetFull`, and `FieldFull` TypeScript types SHALL include an explicitly-typed optional `ai_context` field matching the schema shape (a string, or an object with optional `instructions`, `synonyms`, and `examples`). The graph view and detail panel SHALL read `ai_context` through this typed field rather than via an untyped index-signature cast.
+
+#### Scenario: Detail panel reads typed ai_context
+
+- **WHEN** the detail panel renders a dataset whose `ai_context` is a structured object
+- **THEN** it reads `instructions`, `synonyms`, and `examples` through the typed `ai_context` field without an unsafe cast
diff --git a/openspec/changes/add-dataset-detail-panel/tasks.md b/openspec/changes/add-dataset-detail-panel/tasks.md
new file mode 100644
index 0000000..490cef4
--- /dev/null
+++ b/openspec/changes/add-dataset-detail-panel/tasks.md
@@ -0,0 +1,35 @@
+## 1. Core file service
+
+- [x] 1.1 Add `updateDatasetMetadata(projectId, modelName, datasetName, metadata)` to `SemanticModelFileService` in `packages/core/src/services/semantic-model-files.ts` — read the dataset YAML, merge `description`/`ai_context`/per-field metadata (matched by field name), preserve all other content, write atomically (temp file + rename); throw on unknown field names and on missing dataset/model
+- [x] 1.2 Add unit tests for `updateDatasetMetadata` (merge, field matching by name, unknown-field rejection, preservation of `source`/`expression`/`custom_extensions`/`view_query`, missing dataset error)
+
+## 2. API route
+
+- [x] 2.1 Add `PATCH /:name/datasets/:datasetName` to `apps/api/src/routes/semantic-models.ts` with a Zod body schema for the partial metadata payload; wire to `updateDatasetMetadata`; return 404 for missing model/dataset; keep session auth consistent with sibling routes
+- [x] 2.2 Add integration tests for the new route (success, partial field update, unknown field rejection, 404 cases)
+
+## 3. Frontend types
+
+- [x] 3.1 Add explicitly-typed optional `ai_context` to `SemanticModelFull`, `DatasetFull`, and `FieldFull` in `apps/frontend/src/components/model-visualization/types.ts`
+- [x] 3.2 Update `model-graph-view.tsx` to read `ai_context` via the typed field (remove the cast in `getDescription`)
+
+## 4. Graph selection wiring
+
+- [x] 4.1 Lift selected-dataset state into `ModelVisualization` (`model-visualization.tsx`) and pass an `onSelectDataset` callback + selected name to `ModelGraphView`
+- [x] 4.2 In `model-graph-view.tsx`, wire `onNodeClick` to select a dataset and `onPaneClick` to clear selection (preserving existing context-menu/pane-dismiss behavior)
+
+## 5. Detail panel component
+
+- [x] 5.1 Create `apps/frontend/src/components/model-visualization/dataset-detail-panel.tsx` rendering dataset name, source, AI description/`ai_context`, description/summary, and a scrollable field list (name, data type, description, ai_context)
+- [x] 5.2 Make the panel an inline resizable/collapsible right column scoped to the Graph tab (reuse `useResizablePanel` + `PanelResizeHandle`); slide in on selection, collapse/close via header control
+- [x] 5.3 Add editable inputs for dataset description, `ai_context` instructions, and per-field descriptions with dirty-state tracking
+- [x] 5.4 Add a `useUpdateDatasetMetadata` mutation hook (typed `api` client) with cache invalidation of `["semantic-model", projectId, modelName]` and success/error toasts; wire the Save button (disabled when clean, pending state in flight)
+
+## 6. Documentation
+
+- [x] 6.1 Update the graph view documentation in `apps/docs` to describe the dataset detail panel: opening via node click, collapsing, viewing AI/field metadata, and manual editing + Save
+
+## 7. Verification
+
+- [x] 7.1 Run `pnpm typecheck` and `pnpm lint` (and `pnpm --filter @archmax/api build`) — all exit 0
+- [x] 7.2 Run `npx vitest run` for affected packages
diff --git a/openspec/changes/add-llm-prompt-caching/design.md b/openspec/changes/add-llm-prompt-caching/design.md
new file mode 100644
index 0000000..53957e8
--- /dev/null
+++ b/openspec/changes/add-llm-prompt-caching/design.md
@@ -0,0 +1,58 @@
+## Context
+
+The agent stack is **deepagents** (LangGraph) with **`ChatOpenAI`** (`@langchain/openai`) pointed at OpenRouter by default (`AGENT_API_BASE_URL=https://openrouter.ai/api/v1`, `AGENT_MODEL=anthropic/claude-sonnet-4.6`). The agent is assembled in `packages/core/src/services/agent.ts:45-88` via `createDeepAgent({ model, backend, tools, memory, systemPrompt, middleware })`. The system prompt is passed as a plain string (`buildSystemPrompt(connections)`), and deepagents' memory middleware appends an optional project `AGENTS.md`.
+
+There is no prompt caching today and no token-usage tracking. The constraint is that the **system prompt is sent as an OpenAI-style `{ role: "system" }` message** through the chat-completions wire format.
+
+### Key external constraints (verified)
+
+- OpenRouter supports Anthropic prompt caching via **explicit per-block `cache_control: { type: "ephemeral" }` breakpoints** placed on message **content blocks**. Per-block breakpoints work across all Anthropic-compatible OpenRouter providers (Anthropic, Bedrock, Vertex). ([OpenRouter prompt caching docs](https://openrouter.ai/docs/guides/best-practices/prompt-caching))
+- Anthropic allows a **maximum of 4 explicit breakpoints**; the cache covers `tools` → `system` → `messages` in order, up to and including the marked block.
+- Caching only triggers for prefixes **> ~1024 tokens** — our ~47 KB system prompt easily clears this.
+- Top-level (automatic) `cache_control` is **not** reliably honored over the OpenAI-compat path; explicit per-block breakpoints on the system message are the robust route.
+- `session_id` in the request body enables **provider sticky routing**, which maximizes cache hits across the many requests in a tool loop and across turns.
+- LangChain reports cache usage on the response as `usage_metadata.input_token_details.cache_read` / `cache_creation`.
+
+## Goals / Non-Goals
+
+- Goals:
+  - Cache the stable prompt prefix (tool definitions + system prompt) for Anthropic/Claude models so tool-loop iterations and follow-up turns are billed at the cached rate.
+  - Keep the existing OpenAI-compatible provider configuration; no required provider switch.
+  - Make caching safe-by-default: on for supported models, transparent no-op otherwise, and disableable via env.
+  - Observe cache effectiveness (cache_read / cache_creation tokens).
+- Non-Goals:
+  - Switching the default client to `@langchain/anthropic` (kept as a documented alternative only).
+  - Caching frequently changing per-turn content beyond the stable prefix.
+  - Building a full cost dashboard / persisted token-accounting model (logging only for now).
+  - Caching the short single-shot title-generation call (negligible benefit).
+
+## Decisions
+
+- **Decision: Inject breakpoints via a LangChain model-wrapping middleware, not by hand-building messages.** deepagents owns message assembly (system string + memory + history + tool results), so the only stable interception point is a middleware that rewrites the outgoing request just before the model call. The middleware converts the system message's string content into a single content block `[{ type: "text", text, cache_control: { type: "ephemeral", ttl } }]`. This places one breakpoint at the end of the static prefix (tools + system), which is the dominant repeated content.
+  - Alternatives considered: (a) Passing a structured `systemPrompt` to `createDeepAgent` — rejected, the API takes a string and memory mutates it. (b) Top-level automatic `cache_control` — rejected, unreliable over chat-completions. (c) Switching to `ChatAnthropic` direct — rejected as default (breaks provider-agnostic config) but noted as an option since `@langchain/anthropic@^1.4.0` is already a dependency.
+
+- **Decision: Provider-aware activation.** The middleware only injects breakpoints when caching is enabled AND the model id indicates an Anthropic/Claude model (e.g. contains `claude`/`anthropic`). For other models (OpenAI, Gemini, Ollama) it is a no-op, relying on those providers' implicit caching. This prevents sending unsupported syntax to providers that reject extra breakpoints.
+
+- **Decision: Per-conversation sticky routing.** Pass the conversation id as `session_id` (via OpenRouter request extra body) so the tool loop and subsequent turns route to the same provider and reuse the cache. The conversation id is already available at the worker/API call site.
+
+- **Decision: Configuration.**
+  - `AGENT_PROMPT_CACHE_ENABLED` (default `true`) — master switch.
+  - `AGENT_PROMPT_CACHE_TTL` (default `5m`; accepts `5m` or `1h`) — maps to ephemeral default vs `{ ttl: "1h" }`. 1h costs more on writes but survives long pauses.
+
+- **Decision: Lightweight observability.** Handle `on_chat_model_end` in `processAgentStream` to read `usage_metadata` and accumulate `cache_read` / `cache_creation` / `input` / `output` tokens for the run. Log a single structured summary per agent run (worker + in-process API path). No new DB model in this change.
+
+## Risks / Trade-offs
+
+- **Risk: OpenRouter passthrough quirks for cache_control over chat-completions.** → Validate against the live default model during implementation; ship behind `AGENT_PROMPT_CACHE_ENABLED` so it can be disabled instantly if a provider rejects it.
+- **Risk: Cache invalidation from non-deterministic prefix content.** Connection context ordering or tool-arg serialization changes break the prefix hash. → Ensure `buildConnectionContext` output is stable/ordered; mark only content that is byte-identical across requests.
+- **Risk: 1h TTL increases write cost** if conversations are short. → Default to 5m; document the trade-off.
+- **Trade-off: Single breakpoint** (tools+system) rather than multiple. Keeps us well under the 4-breakpoint limit and covers the largest repeated payload; a rolling message-history breakpoint can be added later if usage data justifies it.
+
+## Migration Plan
+
+- Purely additive and backward-compatible. New env vars default to caching-on; existing deployments gain caching automatically for Claude models with no config change. Set `AGENT_PROMPT_CACHE_ENABLED=false` to restore prior behavior. No data migration.
+
+## Open Questions
+
+- Should cache usage be surfaced in the UI (per-message token/cost badge) or kept to server logs for now? (Proposed: logs only in this change.)
+- Should the playground/test agent also use sticky routing keyed by test-run id? (Proposed: yes, reuse the same helper.)
diff --git a/openspec/changes/add-llm-prompt-caching/proposal.md b/openspec/changes/add-llm-prompt-caching/proposal.md
new file mode 100644
index 0000000..6cfcd1d
--- /dev/null
+++ b/openspec/changes/add-llm-prompt-caching/proposal.md
@@ -0,0 +1,26 @@
+# Change: Enable LLM Prompt Caching for the Semantic Model Agent
+
+## Why
+
+The semantic model agent resends a large, static prefix on every LLM call: a ~47 KB system prompt (`packages/core/prompts/semantic-model-agent.md`), the connection context, the optional project `AGENTS.md`, and the full tool-definition list. A single user turn runs many model→tool→model iterations, so this prefix is re-billed as fresh input tokens on each iteration and again on every follow-up turn. With Claude (the default model via OpenRouter), prompt caching can serve this stable prefix at ~10% of the input price after the first write, cutting input-token cost dramatically for these tool-heavy conversations.
+
+## What Changes
+
+- Inject Anthropic-style `cache_control: { type: "ephemeral" }` breakpoints on the stable prompt prefix (tool definitions + system prompt) so the provider caches it across tool-loop iterations and across turns.
+- Add OpenRouter sticky routing via a per-conversation `session_id` so repeated requests hit the same provider endpoint and reuse the cache.
+- Make caching **provider-aware and configurable**: enabled by default, automatically a no-op for providers/models that don't support explicit breakpoints, controllable via new env vars (`AGENT_PROMPT_CACHE_ENABLED`, `AGENT_PROMPT_CACHE_TTL`).
+- Capture and log per-call cache token usage (`cache_read` / `cache_creation`) so cost savings are observable.
+- Apply the same caching helper to the playground/test agent, which is also tool-loop heavy.
+- Update `.env.example` and the documentation site with the new configuration.
+
+## Impact
+
+- Affected specs: `semantic-model-agent`
+- Affected code:
+  - `packages/core/src/services/agent.ts` (LLM construction, agent assembly)
+  - `packages/core/src/services/agent-middleware.ts` (new cache-control middleware)
+  - `packages/core/src/services/agent-stream.ts` (capture `usage_metadata` on model end)
+  - `packages/core/src/services/playground-agent.ts` (reuse caching helper)
+  - `packages/core/src/config/env.ts` (new env vars)
+  - `apps/worker/src/processor.ts` / `apps/api/src/routes/agent.ts` (pass conversation id as session key, log usage)
+  - `.env.example`, `apps/docs` (configuration docs)
diff --git a/openspec/changes/add-llm-prompt-caching/specs/semantic-model-agent/spec.md b/openspec/changes/add-llm-prompt-caching/specs/semantic-model-agent/spec.md
new file mode 100644
index 0000000..782526b
--- /dev/null
+++ b/openspec/changes/add-llm-prompt-caching/specs/semantic-model-agent/spec.md
@@ -0,0 +1,56 @@
+## ADDED Requirements
+
+### Requirement: LLM Prompt Caching
+
+The agent SHALL cache the stable prompt prefix (tool definitions and system prompt) so that repeated LLM calls within a single tool-loop turn and across follow-up turns reuse cached input tokens instead of re-billing the full prefix. For Anthropic/Claude models served via the configured OpenAI-compatible endpoint, the agent MUST inject an explicit `cache_control: { type: "ephemeral" }` breakpoint on the system message content block so the provider caches everything up to and including that block.
+
+The breakpoint MUST be placed on content that is byte-identical across consecutive requests of the same conversation; per-turn varying content (the incoming user message, tool results) MUST NOT be marked for caching.
+
+#### Scenario: System prefix cached across tool-loop iterations
+- **WHEN** an agent turn performs multiple model→tool→model iterations using a Claude model
+- **THEN** the first model call writes the tool+system prefix to the provider cache
+- **AND** subsequent iterations in the same turn read that prefix from cache rather than re-billing it as fresh input tokens
+
+#### Scenario: Cache reused on a follow-up turn
+- **WHEN** the user sends a follow-up message in the same conversation while the cache is still live
+- **THEN** the agent's first LLM call for that turn reads the previously cached prefix
+
+#### Scenario: Sticky provider routing
+- **WHEN** the agent issues multiple LLM requests for one conversation through OpenRouter
+- **THEN** the requests include the conversation identifier as the session/sticky-routing key
+- **AND** the requests are routed to the same provider endpoint to maximize cache hits
+
+### Requirement: Provider-Aware Cache Activation
+
+Prompt caching SHALL be provider-aware and configurable. Caching MUST be controlled by an `AGENT_PROMPT_CACHE_ENABLED` environment variable that defaults to enabled, and a cache lifetime controlled by `AGENT_PROMPT_CACHE_TTL` (default `5m`, also accepting `1h`). When the configured model does not support explicit cache breakpoints (e.g. non-Anthropic models), the agent MUST NOT inject `cache_control` markers and MUST continue operating normally.
+
+#### Scenario: Caching disabled via configuration
+- **WHEN** `AGENT_PROMPT_CACHE_ENABLED` is set to `false`
+- **THEN** the agent issues LLM requests without any `cache_control` breakpoints
+- **AND** behaves identically to the pre-caching implementation
+
+#### Scenario: Non-Anthropic model is a no-op
+- **WHEN** `AGENT_MODEL` points to a non-Anthropic model (e.g. an OpenAI or Ollama model)
+- **THEN** the agent does not inject explicit `cache_control` markers
+- **AND** the LLM request succeeds without provider errors
+
+#### Scenario: Configurable cache TTL
+- **WHEN** `AGENT_PROMPT_CACHE_TTL` is set to `1h`
+- **THEN** injected `cache_control` breakpoints request the 1-hour ephemeral lifetime
+- **AND** when unset, the default 5-minute ephemeral lifetime is used
+
+### Requirement: Cache Token Usage Logging
+
+The agent run pipeline SHALL capture per-call LLM token usage, including cache read and cache creation token counts, and log a structured summary for each completed agent run so that caching effectiveness and cost savings are observable.
+
+#### Scenario: Cache usage captured on model completion
+- **WHEN** an LLM call completes and the provider returns usage metadata with `cache_read` and/or `cache_creation` token counts
+- **THEN** those counts are accumulated for the agent run
+
+#### Scenario: Run usage summary logged
+- **WHEN** an agent run finishes (in the worker or the in-process API path)
+- **THEN** a structured log entry records total input, output, cache-read, and cache-creation tokens for the run
+
+#### Scenario: Missing usage metadata tolerated
+- **WHEN** a provider returns no cache usage fields
+- **THEN** the run completes normally and the logged cache counts are zero
diff --git a/openspec/changes/add-llm-prompt-caching/tasks.md b/openspec/changes/add-llm-prompt-caching/tasks.md
new file mode 100644
index 0000000..cf20949
--- /dev/null
+++ b/openspec/changes/add-llm-prompt-caching/tasks.md
@@ -0,0 +1,37 @@
+## 1. Configuration
+
+- [ ] 1.1 Add `AGENT_PROMPT_CACHE_ENABLED` (default `true`) and `AGENT_PROMPT_CACHE_TTL` (default `5m`, accepts `5m`/`1h`) to the Zod env schema in `packages/core/src/config/env.ts`
+- [ ] 1.2 Add both vars (with comments) to `.env.example`
+
+## 2. Caching middleware & helper
+
+- [ ] 2.1 Add a provider-aware helper that decides whether the configured `AGENT_MODEL` supports explicit cache breakpoints (Anthropic/Claude check)
+- [ ] 2.2 Implement a LangChain model-wrapping middleware in `packages/core/src/services/agent-middleware.ts` that, when enabled, rewrites the outgoing system message content into a single `{ type: "text", text, cache_control: { type: "ephemeral", ttl } }` block
+- [ ] 2.3 Register the middleware in `createSemlayerAgent` (`packages/core/src/services/agent.ts`) alongside the existing tool-error-recovery middleware
+- [ ] 2.4 Reuse the helper/middleware in `createPlaygroundAgent` (`packages/core/src/services/playground-agent.ts`)
+
+## 3. Sticky routing
+
+- [ ] 3.1 Thread the conversation id (and test-run id for playground) to the LLM client as the OpenRouter `session_id` / sticky-routing key
+- [ ] 3.2 Verify `session_id` is sent on every request in the tool loop (worker path `apps/worker/src/processor.ts` and in-process path `apps/api/src/routes/agent.ts`)
+
+## 4. Token usage observability
+
+- [ ] 4.1 Handle `on_chat_model_end` in `processAgentStream` (`packages/core/src/services/agent-stream.ts`) to read `usage_metadata` (input, output, `cache_read`, `cache_creation`) and accumulate per-run totals
+- [ ] 4.2 Log a structured per-run usage summary in the worker and in-process API completion paths
+
+## 5. Validation
+
+- [ ] 5.1 Manually verify against the default model (`anthropic/claude-sonnet-4.6` via OpenRouter) that a second call within a turn reports `cache_read` tokens
+- [ ] 5.2 Verify a non-Anthropic model (e.g. an OpenAI model) runs without injected breakpoints and without provider errors
+- [ ] 5.3 Verify `AGENT_PROMPT_CACHE_ENABLED=false` produces requests with no `cache_control` markers
+
+## 6. Tests
+
+- [ ] 6.1 Unit test the provider-aware activation helper (Anthropic vs non-Anthropic model ids; enabled/disabled flag)
+- [ ] 6.2 Unit test the middleware rewrites the system message into a cache-controlled content block only when active, and leaves messages untouched otherwise
+- [ ] 6.3 Unit test usage accumulation in `processAgentStream` (cache fields present and absent)
+
+## 7. Documentation
+
+- [ ] 7.1 Document `AGENT_PROMPT_CACHE_ENABLED` and `AGENT_PROMPT_CACHE_TTL` (defaults, TTL trade-off, provider support) in the agent configuration page of `apps/docs`
diff --git a/packages/core/src/services/semantic-model-files.test.ts b/packages/core/src/services/semantic-model-files.test.ts
index c1150e7..f5697c1 100644
--- a/packages/core/src/services/semantic-model-files.test.ts
+++ b/packages/core/src/services/semantic-model-files.test.ts
@@ -258,6 +258,107 @@ describe("SemanticModelFileService.updateDatasetExtensions", () => {
   });
 });
 
+describe("SemanticModelFileService.updateDatasetMetadata", () => {
+  let tmpDir: string;
+  let svc: SemanticModelFileService;
+  const projectId = "proj1";
+  const dsPath = () => join(tmpDir, projectId, "src", "test-model", "orders.yaml");
+
+  beforeEach(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "smfs-meta-test-"));
+    svc = new SemanticModelFileService(tmpDir);
+    const dsDir = join(tmpDir, projectId, "src", "test-model");
+    await mkdir(dsDir, { recursive: true });
+    const dsYaml = yaml.dump({
+      dataset: {
+        name: "orders",
+        source: "shop.public.orders",
+        primary_key: ["id"],
+        description: "old description",
+        fields: [
+          {
+            name: "total_price",
+            expression: { dialects: [{ dialect: "ANSI_SQL", expression: "total_price" }] },
+            description: "old field description",
+            custom_extensions: [{ vendor_name: "COMMON", data: '{"data_type":"DECIMAL"}' }],
+          },
+          {
+            name: "status",
+            expression: { dialects: [{ dialect: "ANSI_SQL", expression: "status" }] },
+            description: "",
+          },
+        ],
+        custom_extensions: [{ vendor_name: "COMMON", data: '{"view_query":"SELECT * FROM orders"}' }],
+      },
+    });
+    await writeFile(join(dsDir, "orders.yaml"), dsYaml, "utf-8");
+  });
+
+  afterEach(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+  });
+
+  it("updates dataset description and ai_context, preserving source/fields/extensions", async () => {
+    const ok = await svc.updateDatasetMetadata(projectId, "test-model", "orders", {
+      description: "Order line items",
+      ai_context: { instructions: "Use for revenue analysis" },
+    });
+    expect(ok).toBe(true);
+
+    const parsed = yaml.load(await readFile(dsPath(), "utf-8")) as { dataset: Record<string, unknown> };
+    const ds = parsed.dataset;
+    expect(ds.description).toBe("Order line items");
+    expect(ds.ai_context).toEqual({ instructions: "Use for revenue analysis" });
+    expect(ds.source).toBe("shop.public.orders");
+    expect(ds.primary_key).toEqual(["id"]);
+    expect(ds.custom_extensions).toEqual([
+      { vendor_name: "COMMON", data: '{"view_query":"SELECT * FROM orders"}' },
+    ]);
+    const fields = ds.fields as Record<string, unknown>[];
+    expect(fields[0].expression).toEqual({ dialects: [{ dialect: "ANSI_SQL", expression: "total_price" }] });
+  });
+
+  it("updates only the targeted field description, leaving others untouched", async () => {
+    const ok = await svc.updateDatasetMetadata(projectId, "test-model", "orders", {
+      fields: [{ name: "total_price", description: "Line total in USD" }],
+    });
+    expect(ok).toBe(true);
+
+    const parsed = yaml.load(await readFile(dsPath(), "utf-8")) as { dataset: Record<string, unknown> };
+    const fields = parsed.dataset.fields as Record<string, unknown>[];
+    expect(fields[0].description).toBe("Line total in USD");
+    expect(fields[0].custom_extensions).toEqual([{ vendor_name: "COMMON", data: '{"data_type":"DECIMAL"}' }]);
+    expect(fields[1].description).toBe("");
+  });
+
+  it("throws and writes nothing for an unknown field name", async () => {
+    const before = await readFile(dsPath(), "utf-8");
+    await expect(
+      svc.updateDatasetMetadata(projectId, "test-model", "orders", {
+        fields: [{ name: "does_not_exist", description: "x" }],
+      }),
+    ).rejects.toThrow(/Unknown field "does_not_exist"/);
+    expect(await readFile(dsPath(), "utf-8")).toBe(before);
+  });
+
+  it("clears ai_context when given an empty value", async () => {
+    await svc.updateDatasetMetadata(projectId, "test-model", "orders", {
+      ai_context: { instructions: "temp" },
+    });
+    await svc.updateDatasetMetadata(projectId, "test-model", "orders", { ai_context: "" });
+
+    const parsed = yaml.load(await readFile(dsPath(), "utf-8")) as { dataset: Record<string, unknown> };
+    expect(parsed.dataset.ai_context).toBeUndefined();
+  });
+
+  it("returns false for a non-existent dataset", async () => {
+    const ok = await svc.updateDatasetMetadata(projectId, "test-model", "missing", {
+      description: "x",
+    });
+    expect(ok).toBe(false);
+  });
+});
+
 describe("SemanticModelFileService.cleanupLegacyAgentsMd", () => {
   let tmpDir: string;
   let svc: SemanticModelFileService;
diff --git a/packages/core/src/services/semantic-model-files.ts b/packages/core/src/services/semantic-model-files.ts
index fc471da..8caa15b 100644
--- a/packages/core/src/services/semantic-model-files.ts
+++ b/packages/core/src/services/semantic-model-files.ts
@@ -11,10 +11,35 @@ import {
   type SemanticModel,
   type Dataset,
   type CustomExtension,
+  type AiContext,
 } from "./semantic-model-schema";
 
 const YAML_OPTS = { lineWidth: 120, noRefs: true };
 
+export interface DatasetFieldMetadataPatch {
+  name: string;
+  description?: string;
+  ai_context?: AiContext;
+}
+
+export interface DatasetMetadataPatch {
+  description?: string;
+  ai_context?: AiContext;
+  fields?: DatasetFieldMetadataPatch[];
+}
+
+/**
+ * Set or clear an entity's `ai_context` in place. An `undefined` value (or
+ * empty string) removes the key so we never persist a blank context block.
+ */
+function applyAiContext(entity: Record<string, unknown>, value: AiContext): void {
+  if (value === undefined || value === "") {
+    delete entity.ai_context;
+    return;
+  }
+  entity.ai_context = value;
+}
+
 function stripEmptyExtensions<T extends Record<string, unknown>>(obj: T): T {
   const result: Record<string, unknown> = { ...obj };
   // The derived `viewQuery` mirror is never serialised — its truth lives
@@ -395,6 +420,62 @@ export class SemanticModelFileService {
     return true;
   }
 
+  /**
+   * Merge editable semantic metadata (dataset `description`/`ai_context` and
+   * per-field `description`/`ai_context`) into a single dataset file without
+   * touching `source`, `primary_key`, field `expression` values,
+   * `custom_extensions`, or the `view_query`. Field entries are matched by
+   * `name`; an unknown field name throws. Returns `false` when the dataset
+   * file does not exist (caller maps this to a 404).
+   */
+  async updateDatasetMetadata(
+    projectId: string,
+    modelName: string,
+    datasetName: string,
+    metadata: DatasetMetadataPatch,
+  ): Promise<boolean> {
+    assertSafeSegment(modelName, "model name");
+    assertSafeSegment(datasetName, "dataset name");
+    const dir = await this.resolveWorkDir(projectId);
+    const filePath = join(dir, modelName, `${datasetName}.yaml`);
+    let rawContent: string;
+    try {
+      rawContent = await readFile(filePath, "utf-8");
+    } catch {
+      return false;
+    }
+
+    const wrapper = yaml.load(rawContent) as Record<string, unknown>;
+    const ds = (wrapper.dataset ?? wrapper) as Record<string, unknown>;
+
+    if (metadata.description !== undefined) {
+      ds.description = metadata.description;
+    }
+    if (Object.prototype.hasOwnProperty.call(metadata, "ai_context")) {
+      applyAiContext(ds, metadata.ai_context);
+    }
+
+    if (metadata.fields && metadata.fields.length > 0) {
+      const existingFields = Array.isArray(ds.fields) ? (ds.fields as Record<string, unknown>[]) : [];
+      const byName = new Map(existingFields.map((f) => [f.name as string, f]));
+      for (const patch of metadata.fields) {
+        const target = byName.get(patch.name);
+        if (!target) {
+          throw new Error(`Unknown field "${patch.name}" in dataset "${datasetName}"`);
+        }
+        if (patch.description !== undefined) {
+          target.description = patch.description;
+        }
+        if (Object.prototype.hasOwnProperty.call(patch, "ai_context")) {
+          applyAiContext(target, patch.ai_context);
+        }
+      }
+    }
+
+    await this.atomicWrite(filePath, yaml.dump({ dataset: ds }, YAML_OPTS));
+    return true;
+  }
+
   /**
    * One-time cleanup of the formerly auto-generated project-root `AGENTS.md`
    * summary. The `AGENTS.md` slot is now reserved for optional user-authored
diff --git a/packages/core/src/services/semantic-model-schema.ts b/packages/core/src/services/semantic-model-schema.ts
index 998d303..7f20dea 100644
--- a/packages/core/src/services/semantic-model-schema.ts
+++ b/packages/core/src/services/semantic-model-schema.ts
@@ -168,6 +168,7 @@ export type SemanticModel = z.infer<typeof semanticModelSchema> & {
  */
 export type Dataset = z.infer<typeof datasetSchema> & { viewQuery?: string | null };
 export type Field = z.infer<typeof fieldSchema>;
+export type AiContext = z.infer<typeof aiContextSchema>;
 export type Relationship = z.infer<typeof relationshipSchema>;
 export type Metric = z.infer<typeof metricSchema>;
 export type Expression = z.infer<typeof expressionSchema>;