diff --git a/ui/src/index.css b/ui/src/index.css
index 14e234e4e3..c76beed8ae 100644
--- a/ui/src/index.css
+++ b/ui/src/index.css
@@ -1470,7 +1470,7 @@ span.paperclip-mention-chip[data-mention-kind="external-object"] {
   --hex-eab308: #eab308; /* ActivityCharts.tsx — priority 'medium'; also the 0.5-0.8 success-rate bar tint. */
   --hex-6b7280: #6b7280; /* ActivityCharts.tsx — priority 'low' + unknown-status statusColors fallback. */
   --hex-10b981: #10b981; /* ActivityCharts.tsx — >=0.8 success-rate bar tint; also the run-activity 'succeeded' segment. */
-  --hex-737373: #737373; /* ActivityCharts.tsx — run activity "other" segment tint. */
+  --hex-737373: #737373; /* ActivityCharts.tsx — run activity 'other' segment tint. */
   --project-none: #64748b; /* Semantic rename of --hex-64748b (DECISION-SHEET.md A3, value unchanged). 'No project assigned' muted-slate fallback (TOKEN-AUDIT.md 1.3) across Routines/MarkdownEditor/RoutineRunVariablesDialog/RoutineList/IssueColumns/editable-sections; also ActivityCharts.tsx status 'backlog'. */
   --project-seed: #6366f1; /* Semantic rename of --hex-6366f1 (DECISION-SHEET.md A3, value unchanged). Project-color-fallback indigo seed default (ProjectDetail/PipelineSettings/IssueProperties/NewIssueDialog) — new-project-color-picker-seed family per TOKEN-AUDIT.md 1.3. */
   --liveness-blue: #2563eb; /* DECISION-SHEET.md A6: IssueChatThread.tsx human-message 'liveness blue' bubble (PAP-95 rev 5). Same value as --status-task-in_progress by coincidence, decoupled on purpose so a future status-hue change doesn't drag the chat bubble along. */
diff --git a/ui/src/pages/AgentDetail.instructions.test.tsx b/ui/src/pages/AgentDetail.instructions.test.tsx
new file mode 100644
index 0000000000..a255227770
--- /dev/null
+++ b/ui/src/pages/AgentDetail.instructions.test.tsx
@@ -0,0 +1,389 @@
+// @vitest-environment jsdom
+
+import type { ComponentProps } from "react";
+import { flushSync } from "react-dom";
+import { createRoot, type Root } from "react-dom/client";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { Agent, AgentInstructionsBundle, AgentInstructionsFileDetail, AgentInstructionsFileSummary } from "@paperclipai/shared";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PromptsTab } from "./AgentDetail";
+
+const mockAgentsApi = vi.hoisted(() => ({
+  instructionsBundle: vi.fn(),
+  instructionsFile: vi.fn(),
+  updateInstructionsBundle: vi.fn(),
+  saveInstructionsFile: vi.fn(),
+  deleteInstructionsFile: vi.fn(),
+}));
+
+const markdownEditorRenderMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../api/agents", () => ({
+  agentsApi: mockAgentsApi,
+}));
+
+vi.mock("../api/assets", () => ({
+  assetsApi: {
+    uploadImage: vi.fn(async () => ({ contentPath: "/assets/uploaded-image.png" })),
+  },
+}));
+
+vi.mock("../context/CompanyContext", () => ({
+  useCompany: () => ({ selectedCompanyId: "company-1" }),
+}));
+
+vi.mock("../context/SidebarContext", () => ({
+  useSidebar: () => ({ isMobile: false }),
+}));
+
+vi.mock("@/adapters/use-adapter-capabilities", () => ({
+  useAdapterCapabilities: () => () => ({
+    supportsInstructionsBundle: true,
+    supportsSkills: true,
+    supportsLocalAgentJwt: true,
+    requiresMaterializedRuntimeSkills: false,
+    supportsModelProfiles: true,
+  }),
+}));
+
+vi.mock("../components/MarkdownEditor", () => ({
+  MarkdownEditor: ({
+    value,
+    onChange,
+    placeholder,
+    contentClassName,
+    imageUploadHandler,
+  }: {
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    contentClassName?: string;
+    imageUploadHandler?: (file: File) => Promise<string>;
+  }) => {
+    markdownEditorRenderMock({
+      value,
+      contentClassName,
+      hasImageUploadHandler: Boolean(imageUploadHandler),
+    });
+    return (
+      <textarea
+        data-testid="markdown-editor"
+        aria-label="Markdown editor"
+        className={contentClassName}
+        placeholder={placeholder}
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+      />
+    );
+  },
+}));
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+(globalThis as any).IS_REACT_ACT_ENVIRONMENT = true;
+
+async function act(callback: () => void | Promise<void>) {
+  let result: void | Promise<void> = undefined;
+  flushSync(() => {
+    result = callback();
+  });
+  await result;
+}
+
+async function flushReact() {
+  await act(async () => {
+    await Promise.resolve();
+    await new Promise((resolve) => window.setTimeout(resolve, 0));
+  });
+}
+
+async function waitFor<T>(assertion: () => T): Promise<T> {
+  let lastError: unknown;
+  for (let i = 0; i < 20; i++) {
+    try {
+      return assertion();
+    } catch (error) {
+      lastError = error;
+      await flushReact();
+    }
+  }
+  throw lastError;
+}
+
+function setNativeValue(element: HTMLInputElement | HTMLTextAreaElement, value: string) {
+  const prototype = element instanceof HTMLTextAreaElement
+    ? HTMLTextAreaElement.prototype
+    : HTMLInputElement.prototype;
+  const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+  setter?.call(element, value);
+  element.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+function buttonByText(container: HTMLElement, text: string) {
+  const button = Array.from(container.querySelectorAll("button"))
+    .find((candidate) => candidate.textContent?.trim() === text);
+  if (!button) throw new Error(`Button not found: ${text}`);
+  return button as HTMLButtonElement;
+}
+
+function makeAgent(overrides: Partial<Agent> = {}): Agent {
+  return {
+    id: "agent-1",
+    companyId: "company-1",
+    name: "Codex Coder",
+    urlKey: "codexcoder",
+    role: "engineer",
+    title: null,
+    icon: null,
+    status: "active",
+    reportsTo: null,
+    capabilities: null,
+    adapterType: "codex_local",
+    adapterConfig: {},
+    runtimeConfig: {},
+    budgetMonthlyCents: 0,
+    spentMonthlyCents: 0,
+    pauseReason: null,
+    pausedAt: null,
+    permissions: { canCreateAgents: false },
+    lastHeartbeatAt: null,
+    metadata: null,
+    createdAt: new Date("2026-01-01T00:00:00Z"),
+    updatedAt: new Date("2026-01-01T00:00:00Z"),
+    ...overrides,
+  };
+}
+
+function makeSummary(
+  path: string,
+  entryFile: string,
+  overrides: Partial<AgentInstructionsFileSummary> = {},
+): AgentInstructionsFileSummary {
+  const markdown = path.toLowerCase().endsWith(".md");
+  return {
+    path,
+    size: 24,
+    language: markdown ? "markdown" : "text",
+    markdown,
+    isEntryFile: path === entryFile,
+    editable: true,
+    deprecated: false,
+    virtual: false,
+    ...overrides,
+  };
+}
+
+function makeDetail(
+  summary: AgentInstructionsFileSummary,
+  content = "# Agent instructions",
+  overrides: Partial<AgentInstructionsFileDetail> = {},
+): AgentInstructionsFileDetail {
+  return {
+    ...summary,
+    content,
+    ...overrides,
+  };
+}
+
+function makeBundle(
+  entryFile: string,
+  files: AgentInstructionsFileSummary[],
+  overrides: Partial<AgentInstructionsBundle> = {},
+): AgentInstructionsBundle {
+  return {
+    agentId: "agent-1",
+    companyId: "company-1",
+    mode: "managed",
+    rootPath: "/paperclip/agents/agent-1/instructions",
+    managedRootPath: "/paperclip/agents/agent-1/instructions",
+    entryFile,
+    resolvedEntryPath: `/paperclip/agents/agent-1/instructions/${entryFile}`,
+    editable: true,
+    warnings: [],
+    legacyPromptTemplateActive: false,
+    legacyBootstrapPromptTemplateActive: false,
+    files,
+    ...overrides,
+  };
+}
+
+describe("PromptsTab instruction editor", () => {
+  let container: HTMLDivElement;
+  let root: Root | null;
+  let queryClient: QueryClient;
+  let saveAction: (() => void) | null;
+
+  beforeEach(() => {
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = null;
+    queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false }, mutations: { retry: false } },
+    });
+    saveAction = null;
+    markdownEditorRenderMock.mockClear();
+    Object.values(mockAgentsApi).forEach((mock) => mock.mockReset());
+    mockAgentsApi.updateInstructionsBundle.mockResolvedValue({});
+    mockAgentsApi.saveInstructionsFile.mockImplementation(async (_agentId, data) => ({
+      path: data.path,
+      size: data.content.length,
+      language: "markdown",
+      markdown: true,
+      isEntryFile: true,
+      editable: true,
+      deprecated: false,
+      virtual: false,
+      content: data.content,
+    }));
+    mockAgentsApi.deleteInstructionsFile.mockResolvedValue({});
+  });
+
+  afterEach(async () => {
+    if (root) {
+      await act(async () => {
+        root?.unmount();
+      });
+    }
+    queryClient.clear();
+    container.remove();
+    document.body.innerHTML = "";
+    vi.clearAllMocks();
+  });
+
+  async function renderPromptsTab(
+    bundle: AgentInstructionsBundle,
+    details: Record<string, AgentInstructionsFileDetail>,
+    props: Partial<ComponentProps<typeof PromptsTab>> = {},
+  ) {
+    mockAgentsApi.instructionsBundle.mockResolvedValue(bundle);
+    mockAgentsApi.instructionsFile.mockImplementation(async (_agentId: string, path: string) => {
+      const detail = details[path];
+      if (!detail) throw new Error(`Missing detail for ${path}`);
+      return detail;
+    });
+
+    root = createRoot(container);
+    await act(async () => {
+      root?.render(
+        <QueryClientProvider client={queryClient}>
+          <PromptsTab
+            agent={props.agent ?? makeAgent()}
+            companyId={props.companyId ?? "company-1"}
+            onDirtyChange={props.onDirtyChange ?? vi.fn()}
+            onSaveActionChange={props.onSaveActionChange ?? ((next) => { saveAction = next; })}
+            onCancelActionChange={props.onCancelActionChange ?? vi.fn()}
+            onSavingChange={props.onSavingChange ?? vi.fn()}
+          />
+        </QueryClientProvider>,
+      );
+    });
+    await flushReact();
+  }
+
+  it("uses server markdown metadata for extensionless files and saves MarkdownEditor drafts", async () => {
+    const summary = makeSummary("AGENTS", "AGENTS", {
+      language: "markdown",
+      markdown: true,
+    });
+    await renderPromptsTab(
+      makeBundle("AGENTS", [summary]),
+      { AGENTS: makeDetail(summary, "# Current") },
+    );
+
+    const editor = await waitFor(() => {
+      const candidate = container.querySelector<HTMLTextAreaElement>('[data-testid="markdown-editor"]');
+      expect(candidate).not.toBeNull();
+      return candidate!;
+    });
+    expect(markdownEditorRenderMock).toHaveBeenLastCalledWith(expect.objectContaining({
+      contentClassName: expect.not.stringContaining("font-mono"),
+      hasImageUploadHandler: true,
+      value: "# Current",
+    }));
+
+    await act(async () => {
+      setNativeValue(editor, "# Updated");
+    });
+    await waitFor(() => {
+      expect(saveAction).toEqual(expect.any(Function));
+    });
+
+    saveAction?.();
+    await waitFor(() => {
+      expect(mockAgentsApi.saveInstructionsFile).toHaveBeenCalledWith(
+        "agent-1",
+        {
+          path: "AGENTS",
+          content: "# Updated",
+          clearLegacyPromptTemplate: false,
+        },
+        "company-1",
+      );
+    });
+  });
+
+  it("uses the Markdown editor for pending new .md files before server metadata exists", async () => {
+    const summary = makeSummary("settings.json", "settings.json", {
+      language: "json",
+      markdown: false,
+    });
+    await renderPromptsTab(
+      makeBundle("settings.json", [summary]),
+      { "settings.json": makeDetail(summary, "{\n  \"ok\": true\n}") },
+    );
+
+    await waitFor(() => {
+      expect(container.querySelector<HTMLTextAreaElement>('textarea[placeholder="File contents"]')).not.toBeNull();
+    });
+
+    await act(async () => {
+      buttonByText(container, "+").click();
+    });
+    await flushReact();
+    const input = container.querySelector<HTMLInputElement>('input[placeholder="TOOLS.md"]');
+    expect(input).not.toBeNull();
+
+    await act(async () => {
+      setNativeValue(input!, "notes.md");
+      buttonByText(container, "Create").click();
+    });
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="markdown-editor"]')).not.toBeNull();
+    });
+    expect(mockAgentsApi.instructionsFile).not.toHaveBeenCalledWith("agent-1", "notes.md", "company-1");
+  });
+
+  it("falls back to extension detection for existing .md files when metadata is missing", async () => {
+    const summary = makeSummary("FALLBACK.md", "FALLBACK.md", {
+      language: "text",
+      markdown: undefined,
+    });
+    await renderPromptsTab(
+      makeBundle("FALLBACK.md", [summary]),
+      { "FALLBACK.md": makeDetail(summary, "# Fallback", { markdown: undefined }) },
+    );
+
+    await waitFor(() => {
+      expect(container.querySelector("[data-testid=\"markdown-editor\"]")).not.toBeNull();
+      expect(markdownEditorRenderMock).toHaveBeenLastCalledWith(expect.objectContaining({
+        value: "# Fallback",
+      }));
+    });
+  });
+
+  it("keeps the raw textarea when server metadata marks an .md file as non-Markdown", async () => {
+    const summary = makeSummary("NOTES.md", "NOTES.md", {
+      language: "text",
+      markdown: false,
+    });
+    await renderPromptsTab(
+      makeBundle("NOTES.md", [summary]),
+      { "NOTES.md": makeDetail(summary, "raw instructions") },
+    );
+
+    await waitFor(() => {
+      expect(container.querySelector('[data-testid="markdown-editor"]')).toBeNull();
+      expect(container.querySelector<HTMLTextAreaElement>('textarea[placeholder="File contents"]')?.value).toBe("raw instructions");
+    });
+  });
+});
diff --git a/ui/src/pages/AgentDetail.tsx b/ui/src/pages/AgentDetail.tsx
index 6006c3152c..0a8720d52d 100644
--- a/ui/src/pages/AgentDetail.tsx
+++ b/ui/src/pages/AgentDetail.tsx
@@ -179,6 +179,17 @@ function isMarkdown(pathValue: string) {
   return pathValue.toLowerCase().endsWith(".md");
 }
 
+function shouldUseMarkdownInstructionsEditor(input: {
+  selectedFileExists: boolean;
+  selectedPath: string;
+  detail?: { markdown?: boolean } | null;
+  summary?: { markdown?: boolean } | null;
+}) {
+  const metadataMarkdown = input.detail?.markdown ?? input.summary?.markdown;
+  if (typeof metadataMarkdown === "boolean") return metadataMarkdown;
+  return isMarkdown(input.selectedPath);
+}
+
 function formatEnvForDisplay(envValue: unknown, censorUsernameInLogs: boolean): string {
   const env = asRecord(envValue);
   if (!env) return "<unable-to-parse>";
@@ -1951,7 +1962,7 @@ function ConfigurationTab({
 
 /* ---- Prompts Tab ---- */
 
-function PromptsTab({
+export function PromptsTab({
   agent,
   companyId,
   onDirtyChange,
@@ -2190,6 +2201,12 @@ function PromptsTab({
 
   const currentContent = selectedFileExists ? (selectedFileDetail?.content ?? "") : "";
   const displayValue = draft ?? currentContent;
+  const useMarkdownEditor = shouldUseMarkdownInstructionsEditor({
+    selectedFileExists,
+    selectedPath: selectedOrEntryFile,
+    detail: selectedFileDetail,
+    summary: selectedFileSummary,
+  });
   const bundleDirty = Boolean(
     bundleDraft &&
       (
@@ -2664,14 +2681,14 @@ function PromptsTab({
 
           {selectedFileExists && fileLoading && !selectedFileDetail ? (
             <PromptEditorSkeleton />
-          ) : isMarkdown(selectedOrEntryFile) ? (
+          ) : useMarkdownEditor ? (
             <MarkdownEditor
               key={selectedOrEntryFile}
               value={displayValue}
               onChange={(value) => setDraft(value ?? "")}
               placeholder="# Agent instructions"
               className="min-w-0 overflow-hidden"
-              contentClassName="min-h-(--sz-420px) max-w-full break-words text-sm font-mono"
+              contentClassName="min-h-(--sz-420px) max-w-full break-words text-sm leading-7"
               imageUploadHandler={async (file) => {
                 const namespace = `agents/${agent.id}/instructions/${selectedOrEntryFile.replaceAll("/", "-")}`;
                 const asset = await uploadMarkdownImage.mutateAsync({ file, namespace });