diff --git a/src/features/instance/applications/components/ApplicationsSidebar/FileTypeIcon.tsx b/src/features/instance/applications/components/ApplicationsSidebar/FileTypeIcon.tsx
index b6101d708..9422a6c58 100644
--- a/src/features/instance/applications/components/ApplicationsSidebar/FileTypeIcon.tsx
+++ b/src/features/instance/applications/components/ApplicationsSidebar/FileTypeIcon.tsx
@@ -1,15 +1,22 @@
+import { isEnvFile } from '@/lib/env/envFile';
 import {
 	CodeIcon,
 	FileCode2Icon,
 	FileIcon,
 	FileImageIcon,
 	FileJsonIcon,
+	FileKeyIcon,
 	FileTypeIcon as LucideFileTypeIcon,
 } from 'lucide-react';
 
-export function FileTypeIcon({ extension }: { readonly extension: string | null }) {
+export function FileTypeIcon({ extension, filename }: { readonly extension: string | null; filename?: string }) {
 	const iconClassName = 'w-4 h-4 mr-2 shrink-0';
 
+	// `.env` files are matched by full name, not extension (`.env.local`'s "extension" is `local`).
+	if (isEnvFile(filename)) {
+		return <FileKeyIcon className={`${iconClassName} text-amber-500`} />;
+	}
+
 	switch (extension) {
 		case 'js':
 		case 'jsx':
diff --git a/src/features/instance/applications/components/ApplicationsSidebar/ItemTitle.tsx b/src/features/instance/applications/components/ApplicationsSidebar/ItemTitle.tsx
index 4b77cfba9..3d74e8bcc 100644
--- a/src/features/instance/applications/components/ApplicationsSidebar/ItemTitle.tsx
+++ b/src/features/instance/applications/components/ApplicationsSidebar/ItemTitle.tsx
@@ -28,7 +28,7 @@ export function ItemTitle({ title, item, context }: {
 						pkg={!!item.data?.package || item.data.path === importedApplications}
 					/>
 				)
-				: <FileTypeIcon extension={parseFileExtension(title)} />}
+				: <FileTypeIcon extension={parseFileExtension(title)} filename={title} />}
 			<span className="text-nowrap pointer-events-none">{title}{content ? '*' : ''}</span>
 			{item.data?.package && <LockedIcon />}
 		</>
diff --git a/src/features/instance/applications/components/ContentViewer.tsx b/src/features/instance/applications/components/ContentViewer.tsx
index 27f0e4de3..b875da681 100644
--- a/src/features/instance/applications/components/ContentViewer.tsx
+++ b/src/features/instance/applications/components/ContentViewer.tsx
@@ -3,6 +3,7 @@ import { isDirectory } from '@/features/instance/applications/context/isDirector
 import { useEditorView } from '@/features/instance/applications/hooks/useEditorView';
 import { useReadMeUrlTransformer } from '@/features/instance/applications/lib/readMeUrlTransform';
 import { useCopyToClipboard } from '@/hooks/useCopyToClipboard';
+import { isProtectedEnvFile } from '@/lib/env/envFile';
 import { isBinaryFile } from '@/lib/string/binaryFileType';
 import { getMediaFileType, MediaFileType } from '@/lib/string/mediaFileType';
 import { CopyIcon, FileArchive } from 'lucide-react';
@@ -11,6 +12,7 @@ import Markdown from 'react-markdown';
 import remarkGfm from 'remark-gfm';
 import { newApplication } from './ApplicationsSidebar/specialItems';
 import { DirectoryPlaceholder } from './DirectoryPlaceholder';
+import { EnvEditorView } from './EnvEditorView';
 import { NewApplication } from './NewApplication';
 import { TextEditorView } from './TextEditorView';
 import './directoryReadMe.css';
@@ -56,6 +58,15 @@ export function ContentViewer() {
 		return <BinaryFilePreview name={openedEntry?.name} />;
 	}
 
+	// Secret-bearing `.env` files get a managed secrets panel instead of the raw
+	// text editor, so values aren't flashed on screen or clobbered by accident.
+	// Template files (`.env.example` etc.) hold placeholders, not secrets, and
+	// fall through to the text editor. Keyed by path so per-file state (selection,
+	// raw-editor toggle) resets when switching files.
+	if (isProtectedEnvFile(openedEntry?.name)) {
+		return <EnvEditorView key={openedEntry?.path} />;
+	}
+
 	return <TextEditorView />;
 }
 
diff --git a/src/features/instance/applications/components/EnvEditorView/EnvEditorView.test.tsx b/src/features/instance/applications/components/EnvEditorView/EnvEditorView.test.tsx
new file mode 100644
index 000000000..1bc7a5b8d
--- /dev/null
+++ b/src/features/instance/applications/components/EnvEditorView/EnvEditorView.test.tsx
@@ -0,0 +1,281 @@
+/**
+ * @vitest-environment jsdom
+ */
+import type { FileEntry } from '@/features/instance/applications/context/fileEntry';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import type { AxiosInstance } from 'axios';
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { EnvEditorView } from './index';
+
+/*
+ The view is exercised against a mocked per-instance operations client, so both Harper behaviors
+ are covered: older versions returning the raw `.env` text (plaintext mode: click-to-reveal,
+ whole-file writes) and >= 5.2 returning `protected: true` (protected mode: key-level operations,
+ nothing revealable).
+ */
+
+const openedEntry: FileEntry = {
+	name: '.env',
+	path: 'myapp/.env',
+	project: 'myapp',
+};
+
+const post = vi.fn();
+const instanceClient = { post } as unknown as AxiosInstance;
+
+vi.mock('@/config/useInstanceClient', () => ({
+	useInstanceClientIdParams: () => ({ instanceClient, entityId: 'test-instance', entityType: 'instance' }),
+}));
+
+vi.mock('@/features/instance/applications/hooks/useEditorView', () => ({
+	useEditorView: () => ({ openedEntry }),
+}));
+
+// Avoids the router dependency of the real sessionStorage-backed hook; the raw-buffer
+// interplay it powers isn't under test here.
+const setContent = vi.fn();
+vi.mock('@/features/instance/applications/context/editorFileContent', () => ({
+	useEditorFileContent: () => ({ content: undefined, setContent }),
+}));
+
+vi.mock('@/hooks/usePermissions', () => ({
+	useInstanceBrowseManagePermission: () => true,
+}));
+
+// The raw-text escape hatch mounts Monaco; a marker div is enough to assert the handoff.
+vi.mock('@/features/instance/applications/components/TextEditorView', () => ({
+	TextEditorView: () => <div data-testid="raw-text-editor" />,
+}));
+
+// Radix dialogs rely on a couple of DOM APIs jsdom doesn't implement.
+beforeAll(() => {
+	Element.prototype.hasPointerCapture ??= () => false;
+	Element.prototype.setPointerCapture ??= () => undefined;
+	Element.prototype.releasePointerCapture ??= () => undefined;
+	Element.prototype.scrollIntoView ??= () => undefined;
+	if (typeof window.PointerEvent === 'undefined') {
+		window.PointerEvent = class extends MouseEvent {} as typeof PointerEvent;
+	}
+});
+
+afterEach(() => {
+	cleanup();
+	vi.clearAllMocks();
+});
+
+const PLAINTEXT_FILE = '# note\nAPI_KEY=secret123\nDB_URL=postgres://x\n';
+
+/** Routes mocked operation calls; returns the calls recorded for later assertions. */
+function mockOperations({ fileResponse }: { fileResponse: Record<string, unknown> }) {
+	post.mockImplementation((_url: string, body: { operation: string; key?: string }) => {
+		switch (body.operation) {
+			case 'get_component_file':
+				return Promise.resolve({ data: fileResponse });
+			case 'set_component_file':
+				return Promise.resolve({ data: { message: 'ok' } });
+			case 'set_env_value':
+				return Promise.resolve({ data: { message: 'ok', keys: ['API_KEY', 'DB_URL', body.key] } });
+			case 'delete_env_value':
+				return Promise.resolve({ data: { message: 'ok', keys: ['DB_URL'] } });
+			default:
+				return Promise.reject(new Error(`Unexpected operation ${body.operation}`));
+		}
+	});
+}
+
+function renderView() {
+	const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+	return render(
+		<QueryClientProvider client={queryClient}>
+			<EnvEditorView />
+		</QueryClientProvider>,
+	);
+}
+
+function operationCalls(operation: string) {
+	return post.mock.calls.filter(([, body]) => body.operation === operation).map(([, body]) => body);
+}
+
+describe('EnvEditorView (plaintext mode — Harper < 5.2 returns raw text)', () => {
+	function mockPlaintext() {
+		mockOperations({
+			fileResponse: { message: PLAINTEXT_FILE, size: PLAINTEXT_FILE.length, mtime: 'x', birthtime: 'x' },
+		});
+	}
+
+	it('lists keys with masked values and reveals one only on demand', async () => {
+		mockPlaintext();
+		renderView();
+
+		expect(await screen.findByText('API_KEY')).toBeTruthy();
+		expect(screen.getByText('DB_URL')).toBeTruthy();
+		// No value is in the document until deliberately revealed.
+		expect(screen.queryByText('secret123')).toBeNull();
+
+		fireEvent.click(screen.getAllByTitle('Reveal value')[0]);
+		expect(screen.getByText('secret123')).toBeTruthy();
+
+		// And it can be hidden again.
+		fireEvent.click(screen.getByTitle('Hide value'));
+		expect(screen.queryByText('secret123')).toBeNull();
+	});
+
+	it('adds a secret by rewriting the whole file, preserving comments and other keys', async () => {
+		mockPlaintext();
+		renderView();
+		await screen.findByText('API_KEY');
+
+		fireEvent.click(screen.getByRole('button', { name: /add/i }));
+		fireEvent.change(await screen.findByLabelText('Key'), { target: { value: 'NEW_KEY' } });
+		fireEvent.change(screen.getByLabelText('Value'), { target: { value: 'two words' } });
+
+		const submit = screen.getByRole('button', { name: /add secret/i });
+		await waitFor(() => expect(submit.hasAttribute('disabled')).toBe(false));
+		fireEvent.click(submit);
+
+		await waitFor(() => expect(operationCalls('set_component_file')).toHaveLength(1));
+		expect(operationCalls('set_component_file')[0]).toMatchObject({
+			project: 'myapp',
+			file: '.env',
+			payload: `# note\nAPI_KEY=secret123\nDB_URL=postgres://x\nNEW_KEY='two words'\n`,
+		});
+	});
+
+	it('edits a secret in place after click-to-reveal pre-fills the current value', async () => {
+		mockPlaintext();
+		renderView();
+
+		fireEvent.click(await screen.findByText('API_KEY'));
+		const revealButton = await screen.findByRole('button', { name: /reveal current value/i });
+		fireEvent.click(revealButton);
+
+		const textarea = screen.getByLabelText('Value') as HTMLTextAreaElement;
+		expect(textarea.value).toBe('secret123');
+		fireEvent.change(textarea, { target: { value: 'rotated' } });
+
+		const save = screen.getByRole('button', { name: /save/i });
+		await waitFor(() => expect(save.hasAttribute('disabled')).toBe(false));
+		fireEvent.click(save);
+
+		await waitFor(() => expect(operationCalls('set_component_file')).toHaveLength(1));
+		expect(operationCalls('set_component_file')[0]).toMatchObject({
+			payload: '# note\nAPI_KEY=rotated\nDB_URL=postgres://x\n',
+		});
+	});
+
+	it('deletes a secret through the edit dialog with a two-click confirm', async () => {
+		mockPlaintext();
+		renderView();
+
+		fireEvent.click(await screen.findByText('DB_URL'));
+		const deleteButton = await screen.findByRole('button', { name: /delete/i });
+		fireEvent.click(deleteButton);
+		// First click arms the confirmation; nothing is written yet.
+		expect(operationCalls('set_component_file')).toHaveLength(0);
+		fireEvent.click(screen.getByRole('button', { name: /confirm delete/i }));
+
+		await waitFor(() => expect(operationCalls('set_component_file')).toHaveLength(1));
+		expect(operationCalls('set_component_file')[0]).toMatchObject({
+			payload: '# note\nAPI_KEY=secret123\n',
+		});
+	});
+
+	it('offers the raw text editor as an escape hatch', async () => {
+		mockPlaintext();
+		renderView();
+		await screen.findByText('API_KEY');
+
+		fireEvent.click(screen.getByRole('button', { name: /edit as text/i }));
+		expect(screen.getByTestId('raw-text-editor')).toBeTruthy();
+
+		fireEvent.click(screen.getByRole('button', { name: /secrets view/i }));
+		expect(await screen.findByText('API_KEY')).toBeTruthy();
+	});
+});
+
+describe('EnvEditorView (protected mode — Harper >= 5.2 masks values)', () => {
+	const MASKED = 'API_KEY=********\nDB_URL=********\n';
+
+	function mockProtected() {
+		mockOperations({
+			fileResponse: {
+				protected: true,
+				keys: ['API_KEY', 'DB_URL'],
+				message: MASKED,
+				size: MASKED.length,
+				mtime: 'x',
+				birthtime: 'x',
+			},
+		});
+	}
+
+	it('lists key names with nothing revealable and no raw-text escape hatch', async () => {
+		mockProtected();
+		renderView();
+
+		expect(await screen.findByText('API_KEY')).toBeTruthy();
+		expect(screen.getByText('DB_URL')).toBeTruthy();
+		expect(screen.queryByTitle('Reveal value')).toBeNull();
+		expect(screen.queryByRole('button', { name: /edit as text/i })).toBeNull();
+	});
+
+	it('adds a secret through set_env_value and shows the returned key list', async () => {
+		mockProtected();
+		renderView();
+		await screen.findByText('API_KEY');
+
+		fireEvent.click(screen.getByRole('button', { name: /add/i }));
+		fireEvent.change(await screen.findByLabelText('Key'), { target: { value: 'NEW_KEY' } });
+		fireEvent.change(screen.getByLabelText('Value'), { target: { value: 's3cret' } });
+
+		const submit = screen.getByRole('button', { name: /add secret/i });
+		await waitFor(() => expect(submit.hasAttribute('disabled')).toBe(false));
+		fireEvent.click(submit);
+
+		await waitFor(() => expect(operationCalls('set_env_value')).toHaveLength(1));
+		expect(operationCalls('set_env_value')[0]).toMatchObject({
+			project: 'myapp',
+			file: '.env',
+			key: 'NEW_KEY',
+			value: 's3cret',
+			replicated: false,
+		});
+		// The key list from the operation response lands in the table without a refetch.
+		expect(await screen.findByText('NEW_KEY')).toBeTruthy();
+		expect(operationCalls('get_component_file')).toHaveLength(1);
+		// The whole-file write path is never used against a protected file.
+		expect(operationCalls('set_component_file')).toHaveLength(0);
+	});
+
+	it('replaces a value through set_env_value without offering a reveal', async () => {
+		mockProtected();
+		renderView();
+
+		fireEvent.click(await screen.findByText('API_KEY'));
+		await screen.findByRole('button', { name: /save/i });
+		expect(screen.queryByRole('button', { name: /reveal current value/i })).toBeNull();
+
+		fireEvent.change(screen.getByLabelText('New value'), { target: { value: 'rotated' } });
+		const save = screen.getByRole('button', { name: /save/i });
+		await waitFor(() => expect(save.hasAttribute('disabled')).toBe(false));
+		fireEvent.click(save);
+
+		await waitFor(() => expect(operationCalls('set_env_value')).toHaveLength(1));
+		expect(operationCalls('set_env_value')[0]).toMatchObject({ key: 'API_KEY', value: 'rotated' });
+	});
+
+	it('deletes a secret through delete_env_value and drops it from the table', async () => {
+		mockProtected();
+		renderView();
+
+		fireEvent.click(await screen.findByText('API_KEY'));
+		const deleteButton = await screen.findByRole('button', { name: /delete/i });
+		fireEvent.click(deleteButton);
+		fireEvent.click(screen.getByRole('button', { name: /confirm delete/i }));
+
+		await waitFor(() => expect(operationCalls('delete_env_value')).toHaveLength(1));
+		expect(operationCalls('delete_env_value')[0]).toMatchObject({ key: 'API_KEY', replicated: false });
+		await waitFor(() => expect(screen.queryByText('API_KEY')).toBeNull());
+	});
+});
diff --git a/src/features/instance/applications/components/EnvEditorView/index.tsx b/src/features/instance/applications/components/EnvEditorView/index.tsx
new file mode 100644
index 000000000..1b04f66db
--- /dev/null
+++ b/src/features/instance/applications/components/EnvEditorView/index.tsx
@@ -0,0 +1,185 @@
+/**
+ * A secrets-style editor for an application's `.env` files, replacing the raw text editor so
+ * values aren't flashed on screen (or clobbered) by accident. It adapts to what the connected
+ * Harper can do, duck-typed off the `get_component_file` response rather than a version check:
+ *
+ *  - Older Harper returns the raw file text → keys and values are parsed client-side, values are
+ *    masked behind a deliberate click-to-reveal, and every add/edit/delete rewrites the whole
+ *    file through `set_component_file` (merge-preserving, comments intact). An "Edit as text"
+ *    escape hatch keeps the raw Monaco editor available.
+ *
+ *  - Harper >= 5.2 protects `.env` files (`protected: true`, masked message, key names only) →
+ *    values can never be read back, so there is no reveal and no raw editing (saving the masked
+ *    rendering would destroy the real values); adds/edits/deletes go through the key-level
+ *    `set_env_value` / `delete_env_value` operations instead.
+ *
+ * Template files (`.env.example` etc.) never reach this view — they aren't secret and keep the
+ * plain text editor (see ContentViewer).
+ */
+import { Button } from '@/components/ui/button';
+import { useInstanceClientIdParams } from '@/config/useInstanceClient';
+import { useEditorFileContent } from '@/features/instance/applications/context/editorFileContent';
+import { useEditorView } from '@/features/instance/applications/hooks/useEditorView';
+import { SecretRow, SecretsManager } from '@/features/instance/secrets/SecretsManager';
+import { useInstanceBrowseManagePermission } from '@/hooks/usePermissions';
+import { useDeleteEnvValue, useSetEnvValue } from '@/integrations/api/instance/applications/envValues';
+import {
+	getComponentFileQueryKey,
+	getComponentFileQueryOptions,
+	GetComponentFileResponse,
+} from '@/integrations/api/instance/applications/getComponentFile';
+import { useSetComponentFile } from '@/integrations/api/instance/applications/setComponentFile';
+import { parseEnv, removeEnvKeys, renderMaskedEnv, upsertEnvValues } from '@/lib/env/envFile';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { CodeIcon, ShieldCheckIcon, Table2Icon } from 'lucide-react';
+import { useCallback, useMemo, useState } from 'react';
+import { TextEditorView } from '../TextEditorView';
+
+export function EnvEditorView() {
+	const instanceParams = useInstanceClientIdParams();
+	const queryClient = useQueryClient();
+	const { openedEntry } = useEditorView();
+	const canManageBrowseInstance = useInstanceBrowseManagePermission();
+
+	const path = openedEntry?.path ?? '';
+	const project = openedEntry?.project ?? '';
+	const file = path.split('/').slice(1).join('/');
+	const fileQueryKey = getComponentFileQueryKey({ file, project, ...instanceParams });
+	const { data, isFetching, refetch } = useQuery(
+		getComponentFileQueryOptions({ file, project, ...instanceParams }),
+	);
+
+	// Unsaved edits from the raw text view. The secrets table is a GUI over the same buffer the
+	// text editor shows, so it parses (and writes back) the dirty content when there is any.
+	const { content: updatedFileContent, setContent } = useEditorFileContent(
+		!!openedEntry && !openedEntry.package && path,
+	);
+
+	const isProtected = data?.protected === true;
+	const rawText = updatedFileContent ?? data?.message;
+
+	const rows = useMemo<SecretRow[]>(() => {
+		if (!data) {
+			return [];
+		}
+		if (isProtected) {
+			return (data.keys ?? []).map((name) => ({ name }));
+		}
+		return Object.entries(parseEnv(rawText ?? '')).map(([name, value]) => ({ name, value }));
+	}, [data, isProtected, rawText]);
+
+	const canManage = !!openedEntry && !openedEntry.package && canManageBrowseInstance;
+
+	/*
+	 Persistence, per mode. Plaintext-mode writes go through the ordinary whole-file save and then
+	 sync the query cache (the EditorViewProvider derives the opened contents from it). Protected-
+	 mode writes go through the key-level operations, whose responses carry the resulting key list.
+	 */
+	const { mutateAsync: writeComponentFile } = useSetComponentFile();
+	const { mutateAsync: setEnvValueAsync } = useSetEnvValue();
+	const { mutateAsync: deleteEnvValueAsync } = useDeleteEnvValue();
+
+	const writeWholeFile = useCallback(async (next: string) => {
+		await writeComponentFile({ ...instanceParams, project, file, payload: next });
+		queryClient.setQueryData<GetComponentFileResponse>(
+			fileQueryKey,
+			(old) => old && { ...old, message: next },
+		);
+		setContent(undefined); // the raw buffer (dirty edits included) is now saved
+	}, [writeComponentFile, instanceParams, project, file, queryClient, fileQueryKey, setContent]);
+
+	const applyProtectedKeys = useCallback((keys: string[]) => {
+		queryClient.setQueryData<GetComponentFileResponse>(
+			fileQueryKey,
+			(old) => old && { ...old, keys, message: renderMaskedEnv(keys) },
+		);
+	}, [queryClient, fileQueryKey]);
+
+	const onSet = useCallback(async (key: string, value: string) => {
+		if (isProtected) {
+			const response = await setEnvValueAsync({ ...instanceParams, project, file, key, value });
+			applyProtectedKeys(response.keys);
+		} else {
+			await writeWholeFile(upsertEnvValues(rawText ?? '', { [key]: value }));
+		}
+	}, [isProtected, setEnvValueAsync, instanceParams, project, file, applyProtectedKeys, writeWholeFile, rawText]);
+
+	const onDelete = useCallback(async (key: string) => {
+		if (isProtected) {
+			const response = await deleteEnvValueAsync({ ...instanceParams, project, file, key });
+			applyProtectedKeys(response.keys);
+		} else {
+			await writeWholeFile(removeEnvKeys(rawText ?? '', key));
+		}
+	}, [isProtected, deleteEnvValueAsync, instanceParams, project, file, applyProtectedKeys, writeWholeFile, rawText]);
+
+	const [selectedName, setSelectedName] = useState<string | undefined>(undefined);
+	const onRefresh = useCallback(() => refetch(), [refetch]);
+
+	// The raw-text escape hatch, for plaintext mode only: on a protected file the editor would
+	// show the masked rendering, and saving that back would overwrite the real values.
+	const [showRawEditor, setShowRawEditor] = useState(false);
+	if (showRawEditor && !isProtected) {
+		return (
+			<>
+				<TextEditorView />
+				<Button
+					type="button"
+					variant="defaultOutline"
+					size="sm"
+					className="absolute top-11 right-4 z-10"
+					onClick={() => setShowRawEditor(false)}
+				>
+					<Table2Icon /> Secrets view
+				</Button>
+			</>
+		);
+	}
+
+	return (
+		<div className="pt-12 px-4 pb-8 max-w-4xl">
+			<div className="mb-4">
+				<h2 className="text-lg font-semibold text-foreground">{openedEntry?.name}</h2>
+				<p className="text-sm text-muted-foreground">
+					{isProtected
+						? (
+							<>
+								<ShieldCheckIcon className="inline-block size-4 me-1 align-text-bottom" />
+								This Harper version protects environment secrets: values stay on the instance and are edited by key —
+								they can be replaced or removed, but never read back.
+							</>
+						)
+						: 'Values are masked to prevent accidental disclosure. Revealing one is a deliberate action.'}
+				</p>
+				{!isProtected && updatedFileContent !== undefined && (
+					<p className="text-sm text-muted-foreground mt-1">
+						Showing unsaved changes from the text editor — saving a secret writes those too.
+					</p>
+				)}
+			</div>
+			<SecretsManager
+				rows={rows}
+				isFetching={isFetching}
+				onRefresh={onRefresh}
+				canManage={canManage}
+				selectedName={selectedName}
+				onSelectName={setSelectedName}
+				addDescription={isProtected
+					? 'The value is written to this application’s env file on the instance. It can be replaced or removed later, but never read back.'
+					: `The value is written to ${openedEntry?.name ?? 'this env file'} in this application.`}
+				editDescription={isProtected
+					? 'The current value can’t be shown — this Harper version never returns secret values. Enter a new value to replace it, or delete the secret.'
+					: 'Reveal the current value, or enter a replacement.'}
+				onSet={onSet}
+				onDelete={canManage ? onDelete : undefined}
+			>
+				{!isProtected && (
+					<Button variant="defaultOutline" onClick={() => setShowRawEditor(true)}>
+						<CodeIcon />
+						<span className="hidden lg:inline-block">Edit as text</span>
+					</Button>
+				)}
+			</SecretsManager>
+		</div>
+	);
+}
diff --git a/src/features/instance/secrets/SecretModals.tsx b/src/features/instance/secrets/SecretModals.tsx
new file mode 100644
index 000000000..de8a6a495
--- /dev/null
+++ b/src/features/instance/secrets/SecretModals.tsx
@@ -0,0 +1,322 @@
+/**
+ * Add/edit dialogs shared by every secrets surface: the cluster-level Secrets config page and the
+ * application editor's `.env` panel. The surfaces differ in copy and in what they can show (a
+ * plaintext `.env` can reveal the current value; encrypted/protected stores cannot), so both are
+ * injected — the dialogs own the form shell, validation, toasts, and the deliberate
+ * click-to-reveal affordance.
+ */
+import { Button } from '@/components/ui/button';
+import {
+	Dialog,
+	DialogContent,
+	DialogDescription,
+	DialogFooter,
+	DialogHeader,
+	DialogTitle,
+} from '@/components/ui/dialog';
+import { Form } from '@/components/ui/form/Form';
+import { FormControl } from '@/components/ui/form/FormControl';
+import { FormDescription } from '@/components/ui/form/FormDescription';
+import { FormField } from '@/components/ui/form/FormField';
+import { FormItem } from '@/components/ui/form/FormItem';
+import { FormLabel } from '@/components/ui/form/FormLabel';
+import { FormMessage } from '@/components/ui/form/FormMessage';
+import { Input } from '@/components/ui/input';
+import { Textarea } from '@/components/ui/textarea';
+import { ENV_KEY_REGEX, ENV_VALUE_MASK } from '@/lib/env/envFile';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { EyeIcon, Save, Trash2 } from 'lucide-react';
+import { ReactNode, useCallback, useMemo, useState } from 'react';
+import { useForm } from 'react-hook-form';
+import { toast } from 'sonner';
+import { z } from 'zod';
+
+const secretKeySchema = z
+	.string()
+	.trim()
+	.min(1)
+	.regex(ENV_KEY_REGEX, { error: 'Letters, numbers, underscore, dash and dot only.' });
+
+export function AddSecretModal({
+	description,
+	valueDescription,
+	existingKeys,
+	onSubmit,
+	isModalOpen,
+	setIsModalOpen,
+}: {
+	description: ReactNode;
+	valueDescription?: ReactNode;
+	/** Keys that already exist — adding one of these is rejected (edit it instead). */
+	existingKeys?: string[];
+	/** Persist the new secret; reject to keep the dialog open and surface the error. */
+	onSubmit: (data: { key: string; value: string }) => Promise<unknown>;
+	isModalOpen: boolean;
+	setIsModalOpen: (open: boolean) => void;
+}) {
+	const schema = useMemo(
+		() =>
+			z.object({
+				key: secretKeySchema.refine((key) => !existingKeys?.includes(key), {
+					error: 'This key already exists — edit it instead.',
+				}),
+				value: z.string().min(1),
+			}),
+		[existingKeys],
+	);
+	const form = useForm({
+		resolver: zodResolver(schema),
+		defaultValues: { key: '', value: '' },
+	});
+	// Destructured unconditionally so react-hook-form tracks all three (see EditSecretModal).
+	const { isDirty, isValid, isSubmitting: isPending } = form.formState;
+
+	const onSubmitClick = useCallback(
+		async (formData: z.infer<typeof schema>) => {
+			try {
+				await onSubmit(formData);
+				form.reset();
+				toast.success(`Secret "${formData.key}" saved.`);
+				setIsModalOpen(false);
+			} catch (error) {
+				toast.error(String(error));
+			}
+		},
+		[onSubmit, form, setIsModalOpen],
+	);
+
+	const onClickCancel = useCallback(() => {
+		form.reset();
+		setIsModalOpen(false);
+	}, [form, setIsModalOpen]);
+
+	return (
+		<Dialog onOpenChange={setIsModalOpen} open={isModalOpen}>
+			<DialogContent aria-describedby={undefined}>
+				<Form {...form}>
+					<form
+						id="add-secret-form"
+						name="add-secret-form"
+						onSubmit={form.handleSubmit(onSubmitClick)}
+						className="grid gap-4 my-4"
+					>
+						<DialogHeader>
+							<DialogTitle>Add Secret</DialogTitle>
+							<DialogDescription>{description}</DialogDescription>
+						</DialogHeader>
+
+						<FormField
+							control={form.control}
+							name="key"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="pb-1">Key</FormLabel>
+									<FormControl>
+										<Input type="text" autoComplete="off" autoCapitalize="off" autoFocus={true} {...field} />
+									</FormControl>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<FormField
+							control={form.control}
+							name="value"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="pb-1">Value</FormLabel>
+									{valueDescription && <FormDescription>{valueDescription}</FormDescription>}
+									<FormControl>
+										<Textarea autoComplete="off" autoCapitalize="off" rows={3} {...field} />
+									</FormControl>
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						<DialogFooter>
+							<div className="flex justify-between w-full">
+								<Button
+									variant="destructiveOutline"
+									type="button"
+									className="rounded-full"
+									onClick={onClickCancel}
+									disabled={isPending}
+								>
+									Cancel
+								</Button>
+								<Button
+									type="submit"
+									variant="submit"
+									className="rounded-full"
+									disabled={isPending || !isDirty || !isValid}
+								>
+									<Save /> Add Secret
+								</Button>
+							</div>
+						</DialogFooter>
+					</form>
+				</Form>
+			</DialogContent>
+		</Dialog>
+	);
+}
+
+const EditSecretSchema = z.object({ value: z.string().min(1) });
+
+export function EditSecretModal({
+	name,
+	description,
+	valueDescription,
+	currentValue,
+	onSave,
+	onDelete,
+	closeModal,
+	children,
+}: {
+	name: string;
+	description: ReactNode;
+	valueDescription?: ReactNode;
+	/**
+	 * The secret's current plaintext value, when the source can be read (older Harper `.env`
+	 * files). Not pre-filled: the field starts masked and the value only appears after a
+	 * deliberate click-to-reveal. Omit when the value can't be read back (encrypted/protected).
+	 */
+	currentValue?: string;
+	/** Persist the replacement value; reject to keep the dialog open and surface the error. */
+	onSave: (value: string) => Promise<unknown>;
+	/** Remove the secret entirely (second click confirms). Omit to hide the delete button. */
+	onDelete?: () => Promise<unknown>;
+	closeModal: () => void;
+	/** Extra content rendered between the value field and the footer (e.g. a grants editor). */
+	children?: ReactNode;
+}) {
+	const form = useForm({ resolver: zodResolver(EditSecretSchema), defaultValues: { value: '' } });
+	// Destructured unconditionally: react-hook-form only tracks formState fields that are actually
+	// read during render, and the short-circuiting `disabled` expression below would otherwise
+	// never read `isValid` while the form is pristine — leaving Save disabled after a single
+	// change event (e.g. a pasted value).
+	const { isDirty, isValid, isSubmitting } = form.formState;
+	const [isDeleting, setIsDeleting] = useState(false);
+	const busy = isSubmitting || isDeleting;
+
+	// Revealing fills the field with the current value without marking the form dirty, so Save
+	// stays disabled until the user actually changes something.
+	const [revealed, setRevealed] = useState(false);
+	const onRevealClick = useCallback(() => {
+		form.setValue('value', currentValue ?? '', { shouldDirty: false });
+		setRevealed(true);
+	}, [form, currentValue]);
+
+	const onSubmitClick = useCallback(
+		async (formData: z.infer<typeof EditSecretSchema>) => {
+			try {
+				await onSave(formData.value);
+				toast.success(`Secret "${name}" updated.`);
+				closeModal();
+			} catch (error) {
+				toast.error(String(error));
+			}
+		},
+		[onSave, name, closeModal],
+	);
+
+	// Deleting a secret can break running applications, so require a second click to confirm.
+	const [confirmingDelete, setConfirmingDelete] = useState(false);
+	const onDeleteClick = useCallback(async () => {
+		if (!confirmingDelete) {
+			setConfirmingDelete(true);
+			return;
+		}
+		setIsDeleting(true);
+		try {
+			await onDelete?.();
+			toast.success(`Secret "${name}" deleted.`);
+			closeModal();
+		} catch (error) {
+			toast.error(String(error));
+		} finally {
+			setIsDeleting(false);
+		}
+	}, [confirmingDelete, onDelete, name, closeModal]);
+
+	return (
+		<Dialog onOpenChange={closeModal} open={true}>
+			<DialogContent aria-describedby={undefined}>
+				<Form {...form}>
+					<form onSubmit={form.handleSubmit(onSubmitClick)} className="grid gap-4 my-4">
+						<DialogHeader>
+							<DialogTitle>{name}</DialogTitle>
+							<DialogDescription>{description}</DialogDescription>
+						</DialogHeader>
+
+						<FormField
+							control={form.control}
+							name="value"
+							render={({ field }) => (
+								<FormItem>
+									<FormLabel className="pb-1">{currentValue !== undefined ? 'Value' : 'New value'}</FormLabel>
+									{valueDescription && <FormDescription>{valueDescription}</FormDescription>}
+									<FormControl>
+										<Textarea
+											autoComplete="off"
+											autoCapitalize="off"
+											autoFocus={true}
+											rows={3}
+											placeholder={currentValue !== undefined && !revealed ? ENV_VALUE_MASK : undefined}
+											{...field}
+										/>
+									</FormControl>
+									{currentValue !== undefined && !revealed && (
+										<Button type="button" variant="defaultOutline" size="sm" onClick={onRevealClick}>
+											<EyeIcon /> Reveal current value
+										</Button>
+									)}
+									<FormMessage />
+								</FormItem>
+							)}
+						/>
+
+						{children}
+
+						<DialogFooter>
+							<div className="flex justify-between w-full">
+								{onDelete
+									? (
+										<Button
+											variant="destructiveOutline"
+											type="button"
+											className="rounded-full"
+											onClick={onDeleteClick}
+											disabled={busy}
+										>
+											<Trash2 /> {confirmingDelete ? 'Confirm delete' : 'Delete'}
+										</Button>
+									)
+									: (
+										<Button
+											variant="destructiveOutline"
+											type="button"
+											className="rounded-full"
+											onClick={closeModal}
+											disabled={busy}
+										>
+											Cancel
+										</Button>
+									)}
+								<Button
+									type="submit"
+									variant="submit"
+									className="rounded-full"
+									disabled={busy || !isDirty || !isValid}
+								>
+									<Save /> Save
+								</Button>
+							</div>
+						</DialogFooter>
+					</form>
+				</Form>
+			</DialogContent>
+		</Dialog>
+	);
+}
diff --git a/src/features/instance/secrets/SecretsManager.tsx b/src/features/instance/secrets/SecretsManager.tsx
new file mode 100644
index 000000000..fd2c95ab6
--- /dev/null
+++ b/src/features/instance/secrets/SecretsManager.tsx
@@ -0,0 +1,203 @@
+/**
+ * A browse/add/edit/delete surface for a key/value secret store, shared by the cluster-level
+ * Secrets config page and the application editor's `.env` panel. The caller owns the data source
+ * and persistence (injected as promises) plus the user-facing copy; this component owns the
+ * table, the deliberate click-to-reveal affordance, and the add/edit dialogs.
+ */
+import { SimpleBrowseDataTable } from '@/components/SimpleBrowseDataTable';
+import { Button } from '@/components/ui/button';
+import { useRefreshClick } from '@/hooks/useRefreshClick';
+import { ENV_VALUE_MASK } from '@/lib/env/envFile';
+import { ColumnDef, Row } from '@tanstack/react-table';
+import { EyeIcon, EyeOffIcon, PlusIcon, RefreshCwIcon, TriangleAlertIcon } from 'lucide-react';
+import { MouseEvent, ReactNode, useCallback, useMemo, useState } from 'react';
+import { AddSecretModal, EditSecretModal } from './SecretModals';
+
+export interface SecretRow {
+	name: string;
+	/**
+	 * The plaintext value, when the source can be read (older Harper `.env` files). Rendered
+	 * masked with a click-to-reveal toggle. Leave undefined when values can't be read back
+	 * (encrypted/protected stores) — the cell shows a plain mask.
+	 */
+	value?: string;
+	/** A per-row caution (e.g. "encrypted under a stale key"), shown as an alert icon. */
+	warning?: string;
+}
+
+export function SecretsManager({
+	rows,
+	isFetching,
+	onRefresh,
+	canManage = true,
+	selectedName,
+	onSelectName,
+	nameHeader = 'Key',
+	addDescription,
+	editDescription,
+	valueDescription,
+	onSet,
+	onDelete,
+	renderEditExtras,
+	children,
+}: {
+	rows: SecretRow[];
+	isFetching?: boolean;
+	/** Re-load the rows; shown as a Refresh toolbar button when provided. */
+	onRefresh?: () => Promise<unknown>;
+	/** false renders a read-only listing: no add button, no row-click editing. */
+	canManage?: boolean;
+	/** Controlled selection — the named secret's edit dialog is open. */
+	selectedName?: string;
+	onSelectName: (name: string | undefined) => void;
+	nameHeader?: string;
+	addDescription: ReactNode;
+	editDescription: ReactNode;
+	valueDescription?: ReactNode;
+	/** Persist a key/value pair — both adding a new secret and replacing an existing value. */
+	onSet: (key: string, value: string) => Promise<unknown>;
+	/** Remove a secret by key. Omit to hide the delete affordance. */
+	onDelete?: (key: string) => Promise<unknown>;
+	/** Extra per-secret content for the edit dialog (e.g. a grants editor). */
+	renderEditExtras?: (name: string) => ReactNode;
+	/** Extra toolbar actions, rendered after Refresh/Add. */
+	children?: ReactNode;
+}) {
+	const columns = useMemo<Array<ColumnDef<SecretRow>>>(() => [
+		{
+			header: nameHeader,
+			accessorKey: 'name',
+			enableSorting: false,
+		},
+		{
+			id: 'value',
+			header: 'Value',
+			enableSorting: false,
+			cell: ({ row }) => <SecretValueCell value={row.original.value} warning={row.original.warning} />,
+		},
+	], [nameHeader]);
+
+	const onRowClick = useCallback(
+		(row?: Row<SecretRow>) => onSelectName(row?.original?.name),
+		[onSelectName],
+	);
+
+	const [isAddModalOpen, setIsAddModalOpen] = useState(false);
+	const existingKeys = useMemo(() => rows.map((row) => row.name), [rows]);
+	const selectedRow = useMemo(() => rows.find((row) => row.name === selectedName), [rows, selectedName]);
+
+	const onRefreshClick = useRefreshClick(onRefresh ?? (() => Promise.resolve()));
+
+	return (
+		<>
+			<SimpleBrowseDataTable
+				columns={columns}
+				data={rows}
+				isFetching={isFetching}
+				onRowClick={canManage ? onRowClick : undefined}
+			>
+				{onRefresh && (
+					<Button
+						variant="defaultOutline"
+						onClick={onRefreshClick}
+						accessKey="r"
+						disabled={isFetching}
+					>
+						<RefreshCwIcon />
+						<span className="hidden lg:inline-block">
+							<u>R</u>efresh
+						</span>
+					</Button>
+				)}
+				{canManage && (
+					<Button
+						variant="positiveOutline"
+						onClick={() => setIsAddModalOpen(true)}
+						accessKey="a"
+						disabled={isAddModalOpen}
+					>
+						<PlusIcon />
+						<span>
+							<u>A</u>dd
+						</span>
+					</Button>
+				)}
+				{children}
+			</SimpleBrowseDataTable>
+			{isAddModalOpen && (
+				<AddSecretModal
+					isModalOpen={isAddModalOpen}
+					setIsModalOpen={setIsAddModalOpen}
+					description={addDescription}
+					valueDescription={valueDescription}
+					existingKeys={existingKeys}
+					onSubmit={({ key, value }) => onSet(key, value)}
+				/>
+			)}
+			{selectedName && selectedRow && (
+				<EditSecretModal
+					key={selectedRow.name}
+					name={selectedRow.name}
+					description={editDescription}
+					valueDescription={valueDescription}
+					currentValue={selectedRow.value}
+					onSave={(value) => onSet(selectedRow.name, value)}
+					onDelete={onDelete && (() => onDelete(selectedRow.name))}
+					closeModal={() => onSelectName(undefined)}
+				>
+					{renderEditExtras?.(selectedRow.name)}
+				</EditSecretModal>
+			)}
+		</>
+	);
+}
+
+/**
+ * A masked secret value. When the plaintext is available, an eye toggle reveals it — a
+ * deliberate action, so screens shared over a call don't flash secrets by accident.
+ */
+function SecretValueCell({ value, warning }: { value?: string; warning?: string }) {
+	const [revealed, setRevealed] = useState(false);
+
+	const warningIcon = warning && (
+		<TriangleAlertIcon
+			className="inline-block size-4 text-amber-500 shrink-0"
+			aria-label={warning}
+		>
+			<title>{warning}</title>
+		</TriangleAlertIcon>
+	);
+
+	if (value === undefined) {
+		return (
+			<span className="inline-flex items-center gap-1 max-w-full" title={warning}>
+				{ENV_VALUE_MASK}
+				{warningIcon}
+			</span>
+		);
+	}
+
+	// Row clicks open the edit dialog, so keep the toggle from bubbling into a selection.
+	const onToggleClick = (event: MouseEvent) => {
+		event.stopPropagation();
+		setRevealed((current) => !current);
+	};
+
+	return (
+		<span className="inline-flex items-center gap-1 max-w-full">
+			<Button
+				type="button"
+				variant="ghost"
+				size="sm"
+				className="px-1"
+				onClick={onToggleClick}
+				title={revealed ? 'Hide value' : 'Reveal value'}
+			>
+				{revealed ? <EyeOffIcon /> : <EyeIcon />}
+				<span className="sr-only">{revealed ? 'Hide value' : 'Reveal value'}</span>
+			</Button>
+			<span className={revealed ? 'font-mono' : undefined}>{revealed ? value : ENV_VALUE_MASK}</span>
+			{warningIcon}
+		</span>
+	);
+}
diff --git a/src/integrations/api/instance/applications/envValues.ts b/src/integrations/api/instance/applications/envValues.ts
new file mode 100644
index 000000000..a9b82efbe
--- /dev/null
+++ b/src/integrations/api/instance/applications/envValues.ts
@@ -0,0 +1,73 @@
+/**
+ * Key-level `.env` operations (Harper >= 5.2, HarperFast/harper#1527).
+ *
+ * On these versions `get_component_file` masks secret-bearing `.env` files (`protected: true`),
+ * so the editor can no longer read-modify-write the whole file. These operations edit single
+ * keys server-side instead, preserving every other key, comment, and formatting — and never
+ * echo values back.
+ */
+import { InstanceClientConfig, InstanceTypeConfig } from '@/config/instanceClientConfig';
+import { useMutation } from '@tanstack/react-query';
+
+/** Both operations respond with the resulting key list (names only — never values). */
+export interface EnvValueResponse {
+	message: string;
+	keys: string[];
+}
+
+export interface SetEnvValueRequest extends InstanceClientConfig, InstanceTypeConfig {
+	project: string;
+	file: string;
+	key: string;
+	value: string;
+}
+
+export async function setEnvValue({
+	instanceClient,
+	entityType,
+	project,
+	file,
+	key,
+	value,
+}: SetEnvValueRequest): Promise<EnvValueResponse> {
+	const { data } = await instanceClient.post<EnvValueResponse>('/', {
+		operation: 'set_env_value',
+		project,
+		file,
+		key,
+		value,
+		replicated: entityType === 'cluster',
+	});
+	return data;
+}
+
+export function useSetEnvValue() {
+	return useMutation({ mutationFn: setEnvValue });
+}
+
+export interface DeleteEnvValueRequest extends InstanceClientConfig, InstanceTypeConfig {
+	project: string;
+	file: string;
+	key: string;
+}
+
+export async function deleteEnvValue({
+	instanceClient,
+	entityType,
+	project,
+	file,
+	key,
+}: DeleteEnvValueRequest): Promise<EnvValueResponse> {
+	const { data } = await instanceClient.post<EnvValueResponse>('/', {
+		operation: 'delete_env_value',
+		project,
+		file,
+		key,
+		replicated: entityType === 'cluster',
+	});
+	return data;
+}
+
+export function useDeleteEnvValue() {
+	return useMutation({ mutationFn: deleteEnvValue });
+}
diff --git a/src/integrations/api/instance/applications/getComponentFile.ts b/src/integrations/api/instance/applications/getComponentFile.ts
index 5f7c60e48..123dea2fa 100644
--- a/src/integrations/api/instance/applications/getComponentFile.ts
+++ b/src/integrations/api/instance/applications/getComponentFile.ts
@@ -15,6 +15,13 @@ export interface GetComponentFileResponse {
 	message: string;
 	mtime: string;
 	size: number;
+	/**
+	 * Harper >= 5.2 marks secret-bearing `.env` files as protected: `message` is a value-free
+	 * `KEY=********` rendering, `keys` lists the key names, and the real values are never
+	 * returned. Older versions return the raw file text with neither field.
+	 */
+	protected?: boolean;
+	keys?: string[];
 }
 
 export async function getComponentFile({
diff --git a/src/lib/env/envFile.test.ts b/src/lib/env/envFile.test.ts
new file mode 100644
index 000000000..8980e63c0
--- /dev/null
+++ b/src/lib/env/envFile.test.ts
@@ -0,0 +1,264 @@
+import { describe, expect, it } from 'vitest';
+import {
+	ENV_VALUE_MASK,
+	formatEnvValue,
+	isEnvFile,
+	isExampleEnvFile,
+	isProtectedEnvFile,
+	parseEnv,
+	parseEnvKeys,
+	removeEnvKeys,
+	renderMaskedEnv,
+	upsertEnvValues,
+} from './envFile';
+
+/**
+ * Ported from Harper core's `unitTests/utility/envFile.test.js` (HarperFast/harper#1527) so this
+ * client-side port stays behaviorally in lockstep with the server-side module. The literal
+ * expectations below were validated against the real `dotenv` parser in that suite.
+ */
+describe('envFile', () => {
+	describe('isEnvFile', () => {
+		it('matches .env and .env.<suffix>', () => {
+			expect(isEnvFile('.env')).toBe(true);
+			expect(isEnvFile('.env.local')).toBe(true);
+			expect(isEnvFile('.env.production')).toBe(true);
+			expect(isEnvFile('app/.env')).toBe(true);
+			expect(isEnvFile('deep/nested/.env.test')).toBe(true);
+		});
+
+		it('does not match non-env files', () => {
+			expect(isEnvFile('env.js')).toBe(false);
+			expect(isEnvFile('config.env')).toBe(false);
+			expect(isEnvFile('config.env.ts')).toBe(false);
+			expect(isEnvFile('.environment')).toBe(false);
+			expect(isEnvFile('.envrc')).toBe(false);
+			expect(isEnvFile('')).toBe(false);
+			expect(isEnvFile(undefined)).toBe(false);
+		});
+	});
+
+	describe('isExampleEnvFile / isProtectedEnvFile', () => {
+		it('treats template env files as examples that are not protected', () => {
+			for (
+				const f of [
+					'.env.example',
+					'.env.sample',
+					'.env.template',
+					'.env.local.example',
+					'.ENV.SAMPLE',
+					'app/.env.example',
+				]
+			) {
+				expect(isEnvFile(f), `isEnvFile ${f}`).toBe(true);
+				expect(isExampleEnvFile(f), `isExampleEnvFile ${f}`).toBe(true);
+				expect(isProtectedEnvFile(f), `isProtectedEnvFile ${f}`).toBe(false);
+			}
+		});
+
+		it('treats real env files as protected, not examples (case-insensitive)', () => {
+			for (const f of ['.env', '.env.local', '.env.production', 'deep/.env', '.ENV', '.Env.Production']) {
+				expect(isExampleEnvFile(f), `isExampleEnvFile ${f}`).toBe(false);
+				expect(isProtectedEnvFile(f), `isProtectedEnvFile ${f}`).toBe(true);
+			}
+		});
+
+		it('does not treat non-env files as examples even with a template suffix', () => {
+			expect(isExampleEnvFile('config.example')).toBe(false);
+			expect(isProtectedEnvFile('config.example')).toBe(false);
+			expect(isProtectedEnvFile('env.js')).toBe(false);
+		});
+	});
+
+	describe('parseEnv', () => {
+		it('parses bare, quoted, and commented assignments with dotenv semantics', () => {
+			const text = [
+				'# comment',
+				'BARE=plain',
+				'SPACED=  padded value  ',
+				"SINGLE='kept  literal # not a comment'",
+				'DOUBLE="line1\\nline2"',
+				'INLINE=value # trailing comment',
+				'EMPTY=',
+			].join('\n');
+			expect(parseEnv(text)).toEqual({
+				BARE: 'plain',
+				SPACED: 'padded value',
+				SINGLE: 'kept  literal # not a comment',
+				DOUBLE: 'line1\nline2',
+				INLINE: 'value',
+				EMPTY: '',
+			});
+		});
+
+		it('supports multi-line quoted values and export prefixes', () => {
+			const text = 'export CERT="l1\nl2\nl3"\nNAME=keep\n';
+			expect(parseEnv(text)).toEqual({ CERT: 'l1\nl2\nl3', NAME: 'keep' });
+		});
+
+		it('keeps the last assignment of a duplicated key', () => {
+			expect(parseEnv('FOO=1\nFOO=2\n')).toEqual({ FOO: '2' });
+		});
+	});
+
+	describe('parseEnvKeys', () => {
+		it('returns key names in file order, ignoring comments and blanks', () => {
+			const text = '# a comment\nAPI_KEY=secret123\n\nDB_URL=postgres://x\n';
+			expect(parseEnvKeys(text)).toEqual(['API_KEY', 'DB_URL']);
+		});
+
+		it('handles export prefixes and de-dupes (last wins, single entry)', () => {
+			const text = 'export FOO=1\nFOO=2\nBAR=3\n';
+			expect(parseEnvKeys(text)).toEqual(['FOO', 'BAR']);
+		});
+
+		it('returns no keys for empty text', () => {
+			expect(parseEnvKeys('')).toEqual([]);
+			expect(parseEnvKeys('# only a comment\n')).toEqual([]);
+		});
+	});
+
+	describe('renderMaskedEnv', () => {
+		it('renders one masked line per key and never leaks a value', () => {
+			expect(renderMaskedEnv(['API_KEY', 'DB_URL'])).toBe(`API_KEY=${ENV_VALUE_MASK}\nDB_URL=${ENV_VALUE_MASK}\n`);
+		});
+
+		it('is empty for no keys', () => {
+			expect(renderMaskedEnv([])).toBe('');
+		});
+	});
+
+	describe('formatEnvValue', () => {
+		// round-trip: writing KEY=<formatted> and parsing it back yields the original value
+		const roundTrips = (value: string) => parseEnv(`KEY=${formatEnvValue(value)}\n`).KEY;
+
+		it('leaves simple values bare', () => {
+			expect(formatEnvValue('abc123')).toBe('abc123');
+			expect(formatEnvValue('postgres://u:p@h:5432/db?ssl=true')).toBe('postgres://u:p@h:5432/db?ssl=true');
+		});
+
+		it('emits an empty value bare', () => {
+			expect(formatEnvValue('')).toBe('');
+			expect(roundTrips('')).toBe('');
+		});
+
+		it('quotes values with spaces, #, or leading/trailing whitespace', () => {
+			for (const v of ['hello world', 'has#hash', '  padded  ', 'a=b c']) {
+				expect(roundTrips(v), `failed round trip for ${JSON.stringify(v)}`).toBe(v);
+			}
+		});
+
+		it('round-trips quote characters', () => {
+			expect(roundTrips('has"double')).toBe('has"double');
+			expect(roundTrips("has'single")).toBe("has'single");
+			expect(roundTrips('back`tick')).toBe('back`tick');
+		});
+
+		it('round-trips backslashes and newlines', () => {
+			expect(roundTrips('a\\b\\c')).toBe('a\\b\\c');
+			expect(roundTrips('line1\nline2')).toBe('line1\nline2');
+			expect(roundTrips("has'single\nand newline")).toBe("has'single\nand newline");
+		});
+
+		it('throws only on the unrepresentable both-quotes case', () => {
+			expect(() => formatEnvValue(`both ' and "`)).toThrow();
+		});
+	});
+
+	describe('upsertEnvValues', () => {
+		it('replaces an existing value in place, preserving everything else', () => {
+			const text = '# header\nAPI_KEY=old\nDB_URL=postgres://x\n# trailing note\n';
+			const result = upsertEnvValues(text, { API_KEY: 'rotated' });
+			expect(result).toBe('# header\nAPI_KEY=rotated\nDB_URL=postgres://x\n# trailing note\n');
+			expect(parseEnv(result)).toEqual({ API_KEY: 'rotated', DB_URL: 'postgres://x' });
+		});
+
+		it('appends a new key without disturbing others', () => {
+			const text = 'API_KEY=secret\n';
+			const result = upsertEnvValues(text, { NEW_ONE: 'x' });
+			expect(result).toBe('API_KEY=secret\nNEW_ONE=x\n');
+		});
+
+		it('upserts multiple keys at once (replace + append)', () => {
+			const text = 'A=1\nB=2\n';
+			const result = upsertEnvValues(text, { B: '22', C: '3' });
+			expect(parseEnv(result)).toEqual({ A: '1', B: '22', C: '3' });
+			expect(result.startsWith('A=1\nB=22\n')).toBe(true);
+		});
+
+		it('creates content from an empty file', () => {
+			expect(upsertEnvValues('', { A: '1', B: '2' })).toBe('A=1\nB=2\n');
+		});
+
+		it('preserves the export prefix and indentation when updating', () => {
+			expect(upsertEnvValues('export FOO=old\n', { FOO: 'new' })).toBe('export FOO=new\n');
+		});
+
+		it('collapses a duplicate assignment of an updated key so the new value wins', () => {
+			const text = 'FOO=1\nFOO=2\n';
+			const result = upsertEnvValues(text, { FOO: '9' });
+			expect(result).toBe('FOO=9\n');
+			expect(parseEnv(result)).toEqual({ FOO: '9' });
+		});
+
+		it('does not corrupt a multi-line quoted value belonging to another key', () => {
+			// CERT spans 3 lines; a continuation line looks like an assignment (OTHER=...).
+			const text = 'CERT="line1\nOTHER=line2\nline3"\nNAME=keep\n';
+			const result = upsertEnvValues(text, { OTHER: 'injected' });
+			// CERT stays intact, OTHER is appended as a brand-new key (the look-alike was inside CERT).
+			const parsed = parseEnv(result);
+			expect(parsed.CERT).toBe('line1\nOTHER=line2\nline3');
+			expect(parsed.NAME).toBe('keep');
+			expect(parsed.OTHER).toBe('injected');
+		});
+
+		it('quotes a value that needs it when writing', () => {
+			const result = upsertEnvValues('A=1\n', { B: 'two words' });
+			expect(result).toBe("A=1\nB='two words'\n");
+			expect(parseEnv(result).B).toBe('two words');
+		});
+
+		it('adds new keys to a file with no trailing newline', () => {
+			expect(upsertEnvValues('A=1', { B: '2' })).toBe('A=1\nB=2\n');
+		});
+
+		it('treats a single-quoted value ending in a backslash as closed on its line', () => {
+			// A Windows path closes on its own line; the following key must not be swallowed as a
+			// continuation (which would corrupt it and append a duplicate).
+			const text = "WINPATH='C:\\Users\\name\\'\nNEXT=keep\n";
+			const result = upsertEnvValues(text, { NEXT: 'changed' });
+			expect(result.includes("WINPATH='C:\\Users\\name\\'"), 'WINPATH preserved verbatim').toBe(true);
+			expect(parseEnv(result).NEXT).toBe('changed');
+			expect((result.match(/^NEXT=/gm) || []).length, 'NEXT updated in place, not duplicated').toBe(1);
+		});
+
+		it('treats a backtick-quoted value ending in a backslash as closed on its line', () => {
+			// dotenv treats backtick values literally (like single quotes), so this closes on its line.
+			const text = 'WINPATH=`C:\\Users\\name\\`\nNEXT=keep\n';
+			const result = upsertEnvValues(text, { NEXT: 'changed' });
+			expect(result.includes('WINPATH=`C:\\Users\\name\\`'), 'WINPATH preserved verbatim').toBe(true);
+			expect(parseEnv(result).NEXT).toBe('changed');
+			expect((result.match(/^NEXT=/gm) || []).length, 'NEXT updated in place, not duplicated').toBe(1);
+		});
+	});
+
+	describe('removeEnvKeys', () => {
+		it('removes a single key, leaving the rest', () => {
+			const text = '# note\nA=1\nB=2\nC=3\n';
+			expect(removeEnvKeys(text, 'B')).toBe('# note\nA=1\nC=3\n');
+		});
+
+		it('removes multiple keys', () => {
+			expect(parseEnv(removeEnvKeys('A=1\nB=2\nC=3\n', ['A', 'C']))).toEqual({ B: '2' });
+		});
+
+		it('removes a multi-line quoted value entirely', () => {
+			const text = 'CERT="l1\nl2\nl3"\nNAME=keep\n';
+			expect(removeEnvKeys(text, 'CERT')).toBe('NAME=keep\n');
+		});
+
+		it('is a no-op when the key is absent', () => {
+			expect(removeEnvKeys('A=1\n', 'Z')).toBe('A=1\n');
+		});
+	});
+});
diff --git a/src/lib/env/envFile.ts b/src/lib/env/envFile.ts
new file mode 100644
index 000000000..4ee65858e
--- /dev/null
+++ b/src/lib/env/envFile.ts
@@ -0,0 +1,233 @@
+/**
+ * Client-side helpers for inspecting and editing `.env` files.
+ *
+ * This is a browser-safe port of Harper core's `utility/envFile.ts` (HarperFast/harper#1527) and
+ * must stay behaviorally in lockstep with it: the filename matching decides which files the
+ * editor treats as secret stores, and the parse/serialise logic mirrors what `set_env_value` /
+ * `delete_env_value` do server-side, so a Studio edit against an older (pre-5.2) Harper writes
+ * exactly the file a newer Harper would have produced.
+ *
+ * Parsing follows dotenv 16's exact semantics (the parser Harper's runtime loader uses):
+ *
+ *   - keys match `[\w.-]+`, optionally prefixed with `export `;
+ *   - an unquoted value runs to the first `#` (inline comment) or newline;
+ *   - single-quoted values are taken literally (only the surrounding quotes are stripped) and may
+ *     span multiple lines;
+ *   - double-quoted values are stripped of their quotes and then have `\n`/`\r` expanded — dotenv
+ *     does NOT un-escape `\"` or `\\`, which constrains how we serialise values below.
+ */
+
+/** The placeholder substituted for every value in a masked rendering. */
+export const ENV_VALUE_MASK = '********';
+
+/** dotenv's accepted key character set. Keys written through the API must match this. */
+export const ENV_KEY_REGEX = /^[\w.-]+$/;
+
+// An assignment line: optional indentation + optional `export ` prefix, a key, `=`, then the raw
+// value text. The value may begin a quoted region that continues onto subsequent lines.
+const ASSIGNMENT_LINE = /^(\s*(?:export\s+)?)([\w.-]+)\s*=(.*)$/;
+
+function basename(file: string): string {
+	return file.split('/').pop() ?? '';
+}
+
+/**
+ * True for `.env` and `.env.<suffix>` (e.g. `.env.local`), matched by basename at any depth.
+ * Case-insensitive: a protection feature should err toward over-matching (e.g. catch `.ENV` on a
+ * case-insensitive filesystem) rather than let a secret slip through on a casing technicality.
+ */
+export function isEnvFile(file: string | undefined): boolean {
+	if (!file) { return false; }
+	const base = basename(file).toLowerCase();
+	return base === '.env' || base.startsWith('.env.');
+}
+
+// Template/example env files conventionally hold placeholders, not real secrets, so they are NOT
+// protected — the editor reads and writes them verbatim like any other file. Matched by suffix.
+const EXAMPLE_ENV_SUFFIXES = ['.example', '.sample', '.template'];
+
+/** True for non-secret template env files: `.env.example`, `.env.sample`, `.env.template`, … */
+export function isExampleEnvFile(file: string | undefined): boolean {
+	if (!isEnvFile(file)) { return false; }
+	const base = basename(file!).toLowerCase();
+	return EXAMPLE_ENV_SUFFIXES.some((suffix) => base.endsWith(suffix));
+}
+
+/** True for `.env*` files whose values should be masked/guarded — i.e. excluding template files. */
+export function isProtectedEnvFile(file: string | undefined): boolean {
+	return isEnvFile(file) && !isExampleEnvFile(file);
+}
+
+/**
+ * Parse env-file text into key/value pairs with dotenv 16's exact semantics (duplicate keys —
+ * last assignment wins). This is what Harper's runtime loader sees, so what this returns is what
+ * the application actually gets.
+ */
+export function parseEnv(text: string): Record<string, string> {
+	const result: Record<string, string> = {};
+	if (!text) { return result; }
+	// dotenv's LINE regex, verbatim: quoted values may span lines; unquoted values stop at `#`.
+	const line =
+		/(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+	const normalized = text.replace(/\r\n?/g, '\n');
+	let match: RegExpExecArray | null;
+	while ((match = line.exec(normalized)) !== null) {
+		const key = match[1];
+		let value = (match[2] ?? '').trim();
+		const quote = value[0];
+		value = value.replace(/^(['"`])([\s\S]*)\1$/gm, '$2');
+		if (quote === '"') {
+			value = value.replace(/\\n/g, '\n').replace(/\\r/g, '\r');
+		}
+		result[key] = value;
+	}
+	return result;
+}
+
+/** The key names of an env file, in file order, de-duplicated — exactly what the runtime loads. */
+export function parseEnvKeys(text: string): string[] {
+	if (!text) { return []; }
+	return Object.keys(parseEnv(text));
+}
+
+/** A value-free rendering of an env file: one `KEY=********` line per key. */
+export function renderMaskedEnv(keys: string[]): string {
+	if (!keys || keys.length === 0) { return ''; }
+	return keys.map((key) => `${key}=${ENV_VALUE_MASK}`).join('\n') + '\n';
+}
+
+/**
+ * Serialise a value so that a dotenv-semantics parse recovers it verbatim.
+ *
+ * dotenv only *expands* escapes inside double quotes (`\n`, `\r`) and never un-escapes `\"`/`\\`,
+ * so single quotes — which it treats literally — are the most faithful container:
+ *   - no special chars                 -> bare;
+ *   - no single quote                  -> single-quoted (handles spaces, `#`, `"`, `\`, newlines);
+ *   - single quote but no `"`/`\`/`\r` -> double-quoted with newlines encoded as `\n`;
+ *   - both quote styles                -> unrepresentable; throws.
+ */
+export function formatEnvValue(value: string): string {
+	if (value === '') { return ''; }
+	// Bare is safe only without whitespace, `#` (would begin an inline comment), or any quote
+	// character. Backslash and `=` stay literal in unquoted values, so they don't force quoting.
+	if (!/[\s#'"`]/.test(value)) { return value; }
+	if (!value.includes("'")) { return `'${value}'`; }
+	if (!value.includes('"') && !value.includes('\\') && !value.includes('\r')) {
+		return `"${value.replace(/\n/g, '\\n')}"`;
+	}
+	throw new Error('Environment value contains an unsupported combination of quote characters');
+}
+
+// Does `s` contain an unescaped `quote`? A backslash escapes the following character, but only for
+// double-quoted values — dotenv treats single-quoted and backtick-quoted values literally, so a
+// value ending in `\` (e.g. a Windows path `'C:\Users\name\'`) still closes at that quote.
+function closesQuote(s: string, quote: string): boolean {
+	const backslashEscapes = quote !== "'" && quote !== '`';
+	for (let i = 0; i < s.length; i++) {
+		if (backslashEscapes && s[i] === '\\') {
+			i++;
+			continue;
+		}
+		if (s[i] === quote) { return true; }
+	}
+	return false;
+}
+
+// Index of the last line occupied by the value that starts at `lines[startIdx]`. Unquoted values
+// are single-line; quoted values extend until their matching quote closes.
+function valueEndLine(lines: string[], startIdx: number, rawValue: string): number {
+	const trimmed = rawValue.replace(/^\s+/, '');
+	const quote = trimmed[0];
+	if (quote !== '"' && quote !== "'" && quote !== '`') { return startIdx; }
+	if (closesQuote(trimmed.slice(1), quote)) { return startIdx; }
+	for (let j = startIdx + 1; j < lines.length; j++) {
+		if (closesQuote(lines[j], quote)) { return j; }
+	}
+	return lines.length - 1; // unterminated — treat the remainder of the file as the value
+}
+
+interface ScanState {
+	eol: string;
+	endedWithNewline: boolean;
+	lines: string[];
+}
+
+function beginScan(text: string): ScanState {
+	const eol = text.includes('\r\n') ? '\r\n' : '\n';
+	const endedWithNewline = /\r?\n$/.test(text);
+	const lines = text.length ? text.split(/\r?\n/) : [];
+	if (endedWithNewline) {
+		// Drop the empty element the trailing newline produces.
+		lines.pop();
+	}
+	return { eol, endedWithNewline, lines };
+}
+
+/**
+ * Insert or update the given keys, leaving every other line — comments, blank lines, untouched
+ * keys, and their formatting — exactly as it was. Existing keys are replaced in place (a duplicate
+ * later assignment of an updated key is dropped so the new value wins, as dotenv keeps the last);
+ * new keys are appended. The file is created from empty text transparently.
+ */
+export function upsertEnvValues(text: string, updates: Record<string, string>): string {
+	const pending = new Map(Object.entries(updates));
+	const applied = new Set<string>();
+	const { eol, endedWithNewline, lines } = beginScan(text);
+
+	const out: string[] = [];
+	for (let i = 0; i < lines.length; i++) {
+		const match = ASSIGNMENT_LINE.exec(lines[i]);
+		if (match) {
+			const [, prefix, key] = match;
+			const end = valueEndLine(lines, i, match[3]);
+			if (pending.has(key)) {
+				if (!applied.has(key)) {
+					out.push(`${prefix}${key}=${formatEnvValue(pending.get(key)!)}`);
+					applied.add(key);
+				}
+				// otherwise drop the duplicate assignment of an already-updated key
+			} else {
+				for (let j = i; j <= end; j++) { out.push(lines[j]); }
+			}
+			i = end;
+			continue;
+		}
+		out.push(lines[i]);
+	}
+
+	let appended = false;
+	for (const [key, value] of pending) {
+		if (applied.has(key)) { continue; }
+		out.push(`${key}=${formatEnvValue(value)}`);
+		appended = true;
+	}
+
+	let result = out.join(eol);
+	if (result.length > 0 && (endedWithNewline || appended)) { result += eol; }
+	return result;
+}
+
+/** Remove the given keys (and any continuation lines of multi-line values), leaving the rest. */
+export function removeEnvKeys(text: string, keys: string | string[]): string {
+	const removeSet = new Set(Array.isArray(keys) ? keys : [keys]);
+	if (removeSet.size === 0 || !text) { return text; }
+	const { eol, endedWithNewline, lines } = beginScan(text);
+
+	const out: string[] = [];
+	for (let i = 0; i < lines.length; i++) {
+		const match = ASSIGNMENT_LINE.exec(lines[i]);
+		if (match) {
+			const end = valueEndLine(lines, i, match[3]);
+			if (!removeSet.has(match[2])) {
+				for (let j = i; j <= end; j++) { out.push(lines[j]); }
+			}
+			i = end;
+			continue;
+		}
+		out.push(lines[i]);
+	}
+
+	let result = out.join(eol);
+	if (result.length > 0 && endedWithNewline) { result += eol; }
+	return result;
+}