headscale: describe an acl change in english, read the diff, then save

The policy editor now opens read-only behind an Edit button, and edit mode brings up an assistant:
describe the change, get a complete revised document back, read a line diff of it, and only then press
Save. Nobody writes an ACL from memory — it is HuJSON in Tailscale's grammar keyed to names only the
server knows — and that, not typing speed, is what made this screen unusable.

The model never touches Headscale. It proposes text, the text lands in the editor's draft, and the
existing Save button is still the only thing that leaves the browser. A model that could write the ACL
directly is one that can partition the network the owner is connected through.

The sidecar calls officer-anthropic-proxy on loopback for one request with a timeout — no session, no
agent, nothing persisted. It sends the draft on screen plus the tailnet's vocabulary (user, node and tag
names) and no credentials of any kind. It does not validate the reply either: Headscale owns the only
parser that counts, same argument as policy.ts.

src/servers/sidecar/headscale/assist.ts

@@ -0,0 +1,153 @@
+import type { OfficerContext } from './routes';
+import { badRequest, methodNotAllowed, readJson } from './routes';
+import { activeClient } from './active';
+import { arrayField, toNode, toUser } from './normalize';
+import { askClaude, ProxyUnavailable } from './claude-proxy';
+
+// `POST /_officer/policy/assist` — describe a change in English, get a complete revised policy back.
+//
+// The ACL is the one document in this app that nobody can write from memory: HuJSON, Tailscale's grammar,
+// and every rule keyed to user, tag and host names that only this server knows. The gap this closes is not
+// "typing is slow", it is "I do not know what the file is supposed to look like".
+//
+// THREE THINGS THIS DELIBERATELY DOES NOT DO.
+//
+//  1. **It never saves.** The proposal comes back as text and lands in the editor as a draft. Headscale is
+//     written to by exactly one thing, the Save button, and it is pressed by a person who has read the diff.
+//     A model that could write the ACL directly is a model that can partition the network the owner is
+//     connected through — including the SSH route back in to fix it.
+//  2. **It never validates.** Same argument as policy.ts: Headscale owns the only parser that counts, and a
+//     proposal that looks fine here and is refused on save is a normal, visible outcome.
+//  3. **It sends no credentials.** The prompt carries user names, node names and tags — the vocabulary the
+//     rules must reference — and nothing else. No API keys, no pre-auth keys, no node addresses.
+//
+// The current document is sent in full and the reply must be the full replacement, not a patch. Patches
+// against a hand-formatted HuJSON file are where comments and alignment get silently destroyed, and this
+// file's whole premise is that those are worth keeping.
+
+const MODEL = 'claude-sonnet-5';
+const MAX_TOKENS = 8_000;
+/** A prompt long enough to be an essay is a prompt that should be a conversation. Cheap guard, not a limit. */
+const MAX_PROMPT_CHARS = 2_000;
+/** Enough context to write rules against without pasting an entire large tailnet into the request. */
+const MAX_NODES = 60;
+
+const SYSTEM = `You are helping the owner of a self-hosted Headscale server edit their tailnet's ACL policy.
+
+The policy is a HuJSON document (JSON with // comments and trailing commas) in Tailscale's ACL format:
+groups, tagOwners, hosts, acls, ssh, autoApprovers. Headscale implements a subset — it has no Tailscale SaaS
+features such as nodeAttrs postures, and grants are supported only in recent versions, so prefer classic
+"acls" entries unless the existing document already uses grants.
+
+Rules for your reply, in this order:
+
+1. First, one short paragraph of plain English: what you changed and, where it matters, what it now allows or
+   denies. No preamble, no restating the request.
+2. Then the COMPLETE new policy document inside a single fenced code block tagged hujson. Not a patch, not an
+   excerpt — the whole file, ready to replace what is there.
+
+Preserve the existing document's comments, key order and indentation wherever your change does not touch
+them; they are hand-maintained and the owner reads this file. Only reference users, tags and hosts that exist
+in the context given to you, or that you also define in the same document. If the request is ambiguous enough
+that you would have to guess at something consequential, say so in the paragraph and make the narrower,
+safer choice rather than asking a question — the owner reviews a diff before anything is saved.
+
+If the request cannot be expressed in this policy at all, say why in the paragraph and return the document
+unchanged in the code block.`;
+
+type TailnetContext = { users: string[]; tags: string[]; nodes: string[] };
+
+/**
+ * The vocabulary a usable rule has to be written in: who exists, what tags are in use, what the machines are
+ * called. Best-effort — a server that will not answer these still gets an assistant, just a less informed
+ * one, which beats failing the request over context that is an optimisation.
+ */
+async function readContext(userId: number): Promise<TailnetContext> {
+  const client = await activeClient(userId);
+  if (client instanceof Response) return { users: [], tags: [], nodes: [] };
+
+  try {
+    const [userBody, nodeBody] = await Promise.all([client.call('/api/v1/user'), client.call('/api/v1/node')]);
+
+    const users = arrayField(userBody, 'users')
+      .map((raw) => toUser(raw)?.name)
+      .filter((name): name is string => !!name);
+
+    const nodes = arrayField(nodeBody, 'nodes').map(toNode);
+    const tags = [...new Set(nodes.flatMap((node) => node.tags))].sort();
+    const named = nodes.slice(0, MAX_NODES).map((node) => {
+      const owner = node.user?.name ?? 'unknown';
+      const tagged = node.tags.length ? ` [${node.tags.join(' ')}]` : '';
+      return `${node.name} (user: ${owner})${tagged}`;
+    });
+
+    return { users, tags, nodes: named };
+  } catch {
+    return { users: [], tags: [], nodes: [] };
+  }
+}
+
+function buildPrompt(policy: string, request: string, context: TailnetContext): string {
+  const lines = [
+    'Current policy document:',
+    '```hujson',
+    policy.trim() || '// (this server has no policy yet)',
+    '```',
+    '',
+    'This tailnet:',
+    `- users: ${context.users.length ? context.users.join(', ') : '(none)'}`,
+    `- tags in use: ${context.tags.length ? context.tags.join(', ') : '(none)'}`,
+    `- machines: ${context.nodes.length ? context.nodes.join('; ') : '(none)'}`,
+  ];
+  if (context.nodes.length === MAX_NODES) lines.push(`  (first ${MAX_NODES} shown)`);
+  lines.push('', 'Requested change:', request.trim());
+  return lines.join('\n');
+}
+
+/**
+ * Split the reply into the explanation and the document.
+ *
+ * The fence is the contract, so a reply without one is a failure to report rather than something to salvage:
+ * feeding half an answer into the editor as if it were a policy is worse than saying the model didn't comply.
+ */
+function splitReply(text: string): { explanation: string; policy: string } | null {
+  const match = text.match(/```(?:hujson|json|jsonc)?\s*\n([\s\S]*?)```/);
+  if (!match || !match[1]?.trim()) return null;
+  return { explanation: text.slice(0, match.index).trim(), policy: match[1].replace(/\s+$/, '') };
+}
+
+/** `POST /_officer/policy/assist {prompt, policy}` → `{explanation, policy}`. Nothing is written upstream. */
+export async function handlePolicyAssistRoute(ctx: OfficerContext, rest: string[]): Promise<Response> {
+  if (rest.length > 0) return badRequest('unexpected path');
+  if (ctx.req.method !== 'POST') return methodNotAllowed();
+
+  const body = await readJson(ctx.req);
+  const request = typeof body?.prompt === 'string' ? body.prompt.trim() : '';
+  if (!request) return badRequest('prompt is required');
+  if (request.length > MAX_PROMPT_CHARS) return badRequest(`prompt must be under ${MAX_PROMPT_CHARS} characters`);
+  // The draft on screen, not the saved document: the owner may have edited it, and a proposal built against
+  // a version they cannot see would come back as a diff full of changes they never asked for.
+  const policy = typeof body?.policy === 'string' ? body.policy : '';
+
+  const context = await readContext(ctx.userId);
+
+  try {
+    const reply = await askClaude({
+      model: MODEL,
+      maxTokens: MAX_TOKENS,
+      system: SYSTEM,
+      prompt: buildPrompt(policy, request, context),
+    });
+
+    const split = splitReply(reply);
+    if (!split) {
+      return Response.json({ error: 'the model did not return a policy document — try rephrasing' }, { status: 502 });
+    }
+    return Response.json({ explanation: split.explanation, policy: split.policy });
+  } catch (err) {
+    if (err instanceof ProxyUnavailable) {
+      return Response.json({ error: err.message, code: 'assistant_unavailable' }, { status: 503 });
+    }
+    throw err;
+  }
+}

src/servers/sidecar/headscale/claude-proxy.ts

@@ -0,0 +1,97 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+// One-shot model calls, for sidecar features that need a sentence of reasoning rather than an agent.
+//
+// The target is `officer-anthropic-proxy` on loopback — the same process Claude Code itself talks to. It
+// holds the owner's OAuth credential and refreshes it; callers hold nothing. Its `x-api-key` is a locally
+// generated secret it writes to its own state file, so authenticating is a file read, not a credential this
+// sidecar is given. That file is written by the proxy and read by everyone else; see claude/state.ts
+// (`readProxySecretFromDisk`), which does the same thing for the agent.
+//
+// Not imported from claude/state.ts on purpose: that module initialises paths and a lock for a sidecar this
+// one is not. Twenty lines of file read is a better dependency than another sidecar's lifecycle.
+//
+// This is a REQUEST-SCOPED call with a timeout, not a session. Anything conversational belongs in the chat
+// surface, which already exists and already persists.
+
+const PROXY_PORT = process.env.ANTHROPIC_PROXY_PORT ?? '5051';
+const DATA_PATH = process.env.DATA_PATH ?? '';
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+/** The proxy is not running, has no token, or refused us. Distinct from the model declining to answer. */
+export class ProxyUnavailable extends Error {}
+
+/**
+ * The proxy's own generated secret. Empty means "not on disk yet" — it persists on a debounce, so a
+ * freshly installed machine has a window where the file exists without it.
+ */
+function readProxySecret(): string {
+  try {
+    const file = join(DATA_PATH, 'sidecar', 'claude-state.json');
+    if (!existsSync(file)) return '';
+    const parsed = JSON.parse(readFileSync(file, 'utf-8')) as { proxySecret?: unknown };
+    return typeof parsed.proxySecret === 'string' ? parsed.proxySecret : '';
+  } catch {
+    return '';
+  }
+}
+
+type AskParams = { model: string; system: string; prompt: string; maxTokens: number; timeoutMs?: number };
+
+type MessagesResponse = { content?: { type?: string; text?: string }[]; error?: { message?: string } };
+
+/**
+ * One user turn, one reply, as plain text.
+ *
+ * The system prompt is sent as two blocks with Claude Code's own identity first. The proxy authenticates
+ * with a Claude Pro/Max OAuth token, and that credential is issued to the CLI — asking it to be something
+ * else is a request the upstream is entitled to refuse. (Measured 2026-08-06: a plain assistant prompt is
+ * currently accepted too. Keeping the block costs ~14 tokens and removes the question.)
+ */
+export async function askClaude({ model, system, prompt, maxTokens, timeoutMs }: AskParams): Promise<string> {
+  const secret = readProxySecret();
+  if (!secret) throw new ProxyUnavailable('the Claude proxy has not started yet — try again in a moment');
+
+  let res: Response;
+  try {
+    res = await fetch(`http://127.0.0.1:${PROXY_PORT}/v1/messages`, {
+      method: 'POST',
+      headers: { 'x-api-key': secret, 'anthropic-version': '2023-06-01', 'content-type': 'application/json' },
+      body: JSON.stringify({
+        model,
+        max_tokens: maxTokens,
+        system: [
+          { type: 'text', text: "You are Claude Code, Anthropic's official CLI for Claude." },
+          { type: 'text', text: system },
+        ],
+        messages: [{ role: 'user', content: prompt }],
+      }),
+      signal: AbortSignal.timeout(timeoutMs ?? DEFAULT_TIMEOUT_MS),
+    });
+  } catch (err) {
+    if (err instanceof Error && err.name === 'TimeoutError') throw new ProxyUnavailable('the model took too long');
+    throw new ProxyUnavailable('the Claude proxy is not reachable');
+  }
+
+  const body = (await res.json().catch(() => null)) as MessagesResponse | null;
+
+  if (!res.ok) {
+    const detail = body?.error?.message;
+    // 401/429 are the proxy's own credential problems and read as "unavailable"; anything else is upstream
+    // saying something specific about this request, which is worth passing through.
+    if (res.status === 401 || res.status === 429) {
+      throw new ProxyUnavailable(detail ?? `the Claude proxy returned ${res.status}`);
+    }
+    throw new Error(detail ?? `the model returned ${res.status}`);
+  }
+
+  const text = (body?.content ?? [])
+    .filter((block) => block.type === 'text' && typeof block.text === 'string')
+    .map((block) => block.text)
+    .join('')
+    .trim();
+
+  if (!text) throw new Error('the model returned an empty reply');
+  return text;
+}

src/servers/sidecar/headscale/policy.ts

@@ -2,6 +2,7 @@ import type { OfficerContext } from './routes';
 import { badRequest, methodNotAllowed, readJson } from './routes';
 import { HeadscaleError } from './client';
 import { activeClient } from './active';
+import { handlePolicyAssistRoute } from './assist';
 
 // The ACL policy — /_officer/policy. One HuJSON document that decides which node may reach which, so it is
 // the highest-consequence thing this app can write and the only place a typo silently partitions a network.
@@ -103,8 +104,10 @@ async function putPolicy(ctx: OfficerContext): Promise<Response> {
   }
 }
 
-/** Dispatch `/_officer/policy`. No sub-paths: there is exactly one policy per server. */
+/** Dispatch `/_officer/policy`. One policy per server, plus the drafting assistant beside it. */
 export async function handlePolicyRoute(ctx: OfficerContext, rest: string[]): Promise<Response> {
+  // `/policy/assist` proposes a document; it never writes one. See assist.ts.
+  if (rest[0] === 'assist') return handlePolicyAssistRoute(ctx, rest.slice(1));
   if (rest.length > 0) return badRequest('unexpected path');
   if (ctx.req.method === 'GET') return getPolicy(ctx);
   if (ctx.req.method === 'PUT') return putPolicy(ctx);

src/workspaces/officerdev/src/apps/Headscale/PolicyAssistant.tsx

@@ -0,0 +1,177 @@
+import { useMemo, useState } from 'react';
+import { Check, Loader2, Sparkles, Wand2, X } from 'lucide-react';
+import { useHeadscalePolicyAssist, assistFailure } from './useHeadscalePolicy';
+import { collapseUnchanged, diffCounts, diffLines } from './diff';
+import { Button, Card, ErrorNote } from './Cards';
+
+// Ask for a policy change in English; read the diff; decide.
+//
+// The whole point of this panel is the middle step. The model is good at the grammar — HuJSON, tagOwners,
+// the src/dst shapes — and has no idea which of the owner's machines matter, so its proposal is a draft to
+// be read, not an answer to be trusted. Nothing here writes to Headscale: Apply puts the text in the editor
+// above and the existing Save button is still the only thing that leaves the browser.
+//
+// The diff is against what is CURRENTLY in the editor, which is also what was sent up, so it always shows
+// exactly what accepting would change on screen — including edits the owner made and hasn't saved.
+
+const EXAMPLES = [
+  'let everyone reach the machines tagged tag:server on port 22',
+  'stop the phones from reaching anything except the DNS server',
+  'add a group for family with just my own user in it',
+];
+
+const DiffBody = ({ before, after }: { before: string; after: string }) => {
+  const lines = useMemo(() => diffLines(before, after), [before, after]);
+  const rows = useMemo(() => collapseUnchanged(lines), [lines]);
+  const { added, removed } = useMemo(() => diffCounts(lines), [lines]);
+
+  if (!added && !removed) {
+    return <p className="px-3 py-2.5 text-[11px] text-zinc-500">No change — the proposal matches what you have.</p>;
+  }
+
+  return (
+    <>
+      <div className="flex items-center gap-3 border-b border-white/10 px-3 py-1.5 text-[11px]">
+        <span className="text-emerald-400">+{added}</span>
+        <span className="text-red-400">−{removed}</span>
+        <span className="text-zinc-600">unchanged lines collapsed</span>
+      </div>
+      <div className="max-h-72 overflow-auto p-1 font-mono text-[11px] leading-relaxed">
+        {rows.map((row, index) =>
+          row === null ? (
+            <div key={index} className="px-2 py-1 text-center text-zinc-700 select-none">
+              ⋯
+            </div>
+          ) : (
+            <div
+              key={index}
+              className={`px-2 whitespace-pre-wrap ${
+                row.kind === 'add'
+                  ? 'bg-emerald-500/10 text-emerald-300'
+                  : row.kind === 'remove'
+                    ? 'bg-red-500/10 text-red-300'
+                    : 'text-zinc-500'
+              }`}
+            >
+              {row.kind === 'add' ? '+' : row.kind === 'remove' ? '−' : ' '} {row.text}
+            </div>
+          ),
+        )}
+      </div>
+    </>
+  );
+};
+
+type PolicyAssistantProps = {
+  /** The text on screen right now. Sent up as the base, and diffed against. */
+  policy: string;
+  /** Accepting a proposal — puts it in the editor's draft. Never saves. */
+  onApply: (policy: string) => void;
+  disabled?: boolean;
+};
+
+export const PolicyAssistant = ({ policy, onApply, disabled }: PolicyAssistantProps) => {
+  const assist = useHeadscalePolicyAssist();
+  const [prompt, setPrompt] = useState('');
+  // The proposal lives here, not in the mutation's `data`, so that discarding it is a real state change and
+  // a second ask doesn't briefly show the previous answer against the new base.
+  const [proposal, setProposal] = useState<{ explanation: string; policy: string } | null>(null);
+
+  const ask = async () => {
+    const request = prompt.trim();
+    if (!request || assist.isPending) return;
+    setProposal(null);
+    try {
+      setProposal(await assist.mutateAsync({ prompt: request, policy }));
+    } catch {
+      // Rendered from `assist.error` below — mutateAsync rejecting is the same failure twice.
+    }
+  };
+
+  const apply = () => {
+    if (!proposal) return;
+    onApply(proposal.policy);
+    setProposal(null);
+    setPrompt('');
+    assist.reset();
+  };
+
+  return (
+    <Card>
+      <div className="flex items-center gap-2 border-b border-white/10 px-3 py-2">
+        <Sparkles className="h-3.5 w-3.5 text-primary" />
+        <span className="text-xs font-medium text-zinc-200">Describe the change</span>
+        <span className="ml-auto text-[11px] text-zinc-600">Proposes a document — never saves it</span>
+      </div>
+
+      <div className="flex flex-col gap-2 p-3">
+        <textarea
+          value={prompt}
+          onChange={(ev) => setPrompt(ev.target.value)}
+          onKeyDown={(ev) => {
+            // Enter sends: this is a one-line instruction far more often than a paragraph, and shift-enter
+            // is still there for the times it isn't.
+            if (ev.key === 'Enter' && !ev.shiftKey) {
+              ev.preventDefault();
+              void ask();
+            }
+          }}
+          rows={2}
+          spellCheck={false}
+          disabled={disabled}
+          placeholder="e.g. give my laptop SSH access to everything tagged tag:server"
+          className="w-full resize-y rounded-lg border border-white/10 bg-black/40 px-3 py-2 text-sm leading-relaxed text-zinc-100 outline-none transition-colors placeholder:text-zinc-600 focus:border-primary/50 disabled:opacity-50"
+        />
+
+        <div className="flex flex-wrap items-center gap-2">
+          {!prompt.trim() &&
+            EXAMPLES.map((example) => (
+              <button
+                key={example}
+                type="button"
+                onClick={() => setPrompt(example)}
+                disabled={disabled}
+                className="cursor-pointer rounded-full border border-white/10 px-2.5 py-1 text-[11px] text-zinc-500 transition-colors hover:border-white/20 hover:text-zinc-300 disabled:opacity-40"
+              >
+                {example}
+              </button>
+            ))}
+          <div className="ml-auto">
+            <Button variant="primary" onClick={() => void ask()} disabled={!prompt.trim() || assist.isPending}>
+              {assist.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Wand2 className="h-3.5 w-3.5" />}
+              {assist.isPending ? 'Drafting…' : 'Ask'}
+            </Button>
+          </div>
+        </div>
+
+        {assist.error && <ErrorNote>{assistFailure(assist.error)}</ErrorNote>}
+      </div>
+
+      {proposal && (
+        <div className="border-t border-white/10">
+          {proposal.explanation && (
+            <p className="px-3 py-2.5 text-xs leading-relaxed whitespace-pre-wrap text-zinc-300">
+              {proposal.explanation}
+            </p>
+          )}
+          <div className="border-t border-white/10">
+            <DiffBody before={policy} after={proposal.policy} />
+          </div>
+          <div className="flex items-center gap-2 border-t border-white/10 px-3 py-2">
+            <span className="text-[11px] text-zinc-600">Applying only fills the editor — you still press Save.</span>
+            <span className="ml-auto flex items-center gap-2">
+              <Button onClick={() => setProposal(null)}>
+                <X className="h-3.5 w-3.5" />
+                Discard
+              </Button>
+              <Button variant="primary" onClick={apply}>
+                <Check className="h-3.5 w-3.5" />
+                Apply to editor
+              </Button>
+            </span>
+          </div>
+        </div>
+      )}
+    </Card>
+  );
+};

src/workspaces/officerdev/src/apps/Headscale/PolicyView.tsx

@@ -1,7 +1,8 @@
 import { useEffect, useRef, useState } from 'react';
-import { AlertTriangle, FileLock2, Loader2, RotateCcw, Save, ShieldCheck } from 'lucide-react';
+import { AlertTriangle, FileLock2, Loader2, Pencil, RotateCcw, Save, ShieldCheck } from 'lucide-react';
 import { timeAgo } from './format';
 import { useHeadscalePolicy, policySaveFailure, type PolicySaveFailure } from './useHeadscalePolicy';
+import { PolicyAssistant } from './PolicyAssistant';
 import { Card, SectionHeader, Button, ErrorNote } from './Cards';
 import { ViewShell } from './ViewShell';
 
@@ -9,6 +10,11 @@ import { ViewShell } from './ViewShell';
 // hand-kept alignment are half the document's value to whoever maintains it, and a rich editor that
 // reformats or a client-side parser that disagrees with Headscale would both destroy more than they add.
 //
+// It opens READ-ONLY behind an Edit button. This is the document that decides which machine can reach
+// which, it is usually being looked at rather than changed, and a textarea focused by a stray click is a
+// way to alter it without meaning to. Edit mode also brings up the assistant, because "I do not know what
+// this file should look like" is the actual reason this screen was hard to use.
+//
 // Validation is entirely Headscale's. It has the only parser that counts: it resolves groups, tags and
 // host aliases, and it is what will actually enforce the result. Officer sends the text up untouched and
 // shows the verdict verbatim — including the line and column, which is the whole reason to show it at all.
@@ -68,6 +74,7 @@ export const PolicyView = () => {
   const { policy, isLoading, error, save } = useHeadscalePolicy();
 
   const [draft, setDraft] = useState<string | null>(null);
+  const [editing, setEditing] = useState(false);
   const [failure, setFailure] = useState<PolicySaveFailure | null>(null);
   // Sticky for the session: once a server has refused a write, every later save would refuse identically,
   // and re-discovering that by pressing save again is not information.
@@ -86,6 +93,8 @@ export const PolicyView = () => {
       await save.mutateAsync(text);
       setDraft(null);
       setSavedAt(Date.now());
+      // A clean save is the end of the edit, not the start of the next one — back to reading.
+      setEditing(false);
     } catch (err) {
       const parsed = policySaveFailure(err);
       setFailure(parsed);
@@ -93,13 +102,19 @@ export const PolicyView = () => {
     }
   };
 
-  useSaveShortcut(() => void submit(), dirty && !readOnly);
+  useSaveShortcut(() => void submit(), editing && dirty && !readOnly);
 
   const revert = () => {
     setDraft(null);
     setFailure(null);
   };
 
+  /** Leaving edit mode throws the draft away — there is nowhere else for unsaved text to go. */
+  const stopEditing = () => {
+    revert();
+    setEditing(false);
+  };
+
   return (
     <ViewShell isLoading={isLoading} error={error} label="the access policy">
       <div className="mx-auto flex max-w-4xl flex-col gap-3">
@@ -107,18 +122,31 @@ export const PolicyView = () => {
           title="Access policy"
           subtitle="HuJSON — JSON with comments and trailing commas. Headscale validates it on save; nothing is stored unless it passes."
           action={
-            <div className="flex items-center gap-2">
-              {dirty && !readOnly && (
-                <Button onClick={revert} disabled={save.isPending}>
+            editing ? (
+              <div className="flex items-center gap-2">
+                <Button onClick={stopEditing} disabled={save.isPending}>
                   <RotateCcw className="h-3.5 w-3.5" />
-                  Revert
+                  {dirty ? 'Discard' : 'Done'}
                 </Button>
-              )}
-              <Button variant="primary" onClick={() => void submit()} disabled={!dirty || !!readOnly || save.isPending}>
-                {save.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Save className="h-3.5 w-3.5" />}
-                {save.isPending ? 'Validating…' : 'Save'}
+                <Button
+                  variant="primary"
+                  onClick={() => void submit()}
+                  disabled={!dirty || !!readOnly || save.isPending}
+                >
+                  {save.isPending ? <Loader2 className="h-3.5 w-3.5 animate-spin" /> : <Save className="h-3.5 w-3.5" />}
+                  {save.isPending ? 'Validating…' : 'Save'}
+                </Button>
+              </div>
+            ) : (
+              <Button
+                onClick={() => setEditing(true)}
+                disabled={!!readOnly}
+                title={readOnly ? 'This server will not accept written policies' : undefined}
+              >
+                <Pencil className="h-3.5 w-3.5" />
+                Edit
               </Button>
-            </div>
+            )
           }
         />
 
@@ -126,6 +154,18 @@ export const PolicyView = () => {
         {failure?.kind === 'rejected' && <Rejected message={failure.message} />}
         {failure?.kind === 'unknown' && <ErrorNote>{failure.message}</ErrorNote>}
 
+        {editing && (
+          <PolicyAssistant
+            policy={text}
+            onApply={(proposed) => {
+              setDraft(proposed);
+              setFailure(null);
+              setSavedAt(null);
+            }}
+            disabled={save.isPending}
+          />
+        )}
+
         <Card>
           <textarea
             value={text}
@@ -136,8 +176,11 @@ export const PolicyView = () => {
             }}
             spellCheck={false}
             autoComplete="off"
+            readOnly={!editing}
             placeholder={'{\n  "acls": [\n    { "action": "accept", "src": ["*"], "dst": ["*:*"] },\n  ],\n}'}
-            className="block h-[28rem] w-full resize-y bg-black/40 p-4 font-mono text-[12px] leading-relaxed text-zinc-200 outline-none placeholder:text-zinc-700"
+            className={`block h-[28rem] w-full resize-y p-4 font-mono text-[12px] leading-relaxed outline-none placeholder:text-zinc-700 ${
+              editing ? 'bg-black/40 text-zinc-200' : 'bg-black/20 text-zinc-400'
+            }`}
           />
           <div className="flex flex-wrap items-center gap-3 border-t border-white/10 px-3 py-2 text-[11px] text-zinc-500">
             <span>
@@ -158,7 +201,8 @@ export const PolicyView = () => {
 
         <p className="px-1 text-[11px] leading-relaxed text-zinc-600">
           This document decides which node may reach which. A policy that saves cleanly can still cut a machine off —
-          Headscale checks that the document is valid, not that it is what you meant. Ctrl/Cmd-S saves.
+          Headscale checks that the document is valid, not that it is what you meant.
+          {editing ? ' Ctrl/Cmd-S saves.' : ' Press Edit to change it.'}
         </p>
       </div>
     </ViewShell>

src/workspaces/officerdev/src/apps/Headscale/diff.ts

@@ -0,0 +1,77 @@
+// A line diff, for showing what a proposed policy actually changes before anyone saves it.
+//
+// Hand-rolled rather than a dependency: this is one screen showing one document, the inputs are a few
+// hundred lines at most, and the alternative is adding a package to the frozen lockfile for forty lines of
+// well-understood algorithm. If a second surface ever needs a diff, that trade flips.
+
+export type DiffLine = { kind: 'same' | 'add' | 'remove'; text: string };
+
+/** Longest common subsequence table over the two line arrays. O(n·m) — fine at document scale. */
+function lcsLengths(a: string[], b: string[]): number[][] {
+  const table: number[][] = Array.from({ length: a.length + 1 }, () => new Array<number>(b.length + 1).fill(0));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i]![j] = a[i] === b[j] ? table[i + 1]![j + 1]! + 1 : Math.max(table[i + 1]![j]!, table[i]![j + 1]!);
+    }
+  }
+  return table;
+}
+
+/** Every line of both documents, in order, tagged with what happened to it. */
+export function diffLines(before: string, after: string): DiffLine[] {
+  const a = before.split('\n');
+  const b = after.split('\n');
+  const table = lcsLengths(a, b);
+
+  const out: DiffLine[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length && j < b.length) {
+    if (a[i] === b[j]) {
+      out.push({ kind: 'same', text: a[i]! });
+      i++;
+      j++;
+    } else if (table[i + 1]![j]! >= table[i]![j + 1]!) {
+      out.push({ kind: 'remove', text: a[i]! });
+      i++;
+    } else {
+      out.push({ kind: 'add', text: b[j]! });
+      j++;
+    }
+  }
+  while (i < a.length) out.push({ kind: 'remove', text: a[i++]! });
+  while (j < b.length) out.push({ kind: 'add', text: b[j++]! });
+  return out;
+}
+
+/**
+ * Drop long runs of unchanged lines, keeping `context` either side of every change.
+ *
+ * A policy is mostly unchanged by any one edit, and an unabridged diff buries the three lines that matter.
+ * `null` marks each elision so the view can draw a gap rather than pretend the lines are adjacent.
+ */
+export function collapseUnchanged(lines: DiffLine[], context = 3): (DiffLine | null)[] {
+  const keep = new Array<boolean>(lines.length).fill(false);
+  lines.forEach((line, index) => {
+    if (line.kind === 'same') return;
+    for (let k = Math.max(0, index - context); k <= Math.min(lines.length - 1, index + context); k++) keep[k] = true;
+  });
+
+  const out: (DiffLine | null)[] = [];
+  let gap = false;
+  lines.forEach((line, index) => {
+    if (keep[index]) {
+      out.push(line);
+      gap = false;
+    } else if (!gap) {
+      out.push(null);
+      gap = true;
+    }
+  });
+  return out;
+}
+
+export const diffCounts = (lines: DiffLine[]) => ({
+  added: lines.filter((l) => l.kind === 'add').length,
+  removed: lines.filter((l) => l.kind === 'remove').length,
+});

src/workspaces/officerdev/src/apps/Headscale/useHeadscalePolicy.ts

@@ -29,6 +29,32 @@ export function policySaveFailure(err: unknown): PolicySaveFailure {
   }
 }
 
+/** What the assistant proposes. Never saved by the hook — PolicyView puts it in the draft. */
+export type PolicyProposal = { explanation: string; policy: string };
+
+/** The assistant's failures are all one sentence to the owner; only the sidecar's `error` field is useful. */
+export function assistFailure(err: unknown): string {
+  const raw = (err as { message?: unknown } | null)?.message;
+  if (typeof raw !== 'string' || !raw) return 'The assistant could not be reached';
+  try {
+    const parsed = JSON.parse(raw) as { error?: unknown };
+    return typeof parsed.error === 'string' && parsed.error ? parsed.error : 'The assistant could not be reached';
+  } catch {
+    return raw.slice(0, 300);
+  }
+}
+
+/**
+ * Ask for a revised policy in English. Separate from `useHeadscalePolicy` because it is a different kind of
+ * thing: no cache, no query key, nothing to invalidate — one request, one answer, discarded on reload.
+ */
+export function useHeadscalePolicyAssist() {
+  const { post } = useClient();
+  return useMutation({
+    mutationFn: (input: { prompt: string; policy: string }) => post<PolicyProposal>(`${PATH}/assist`, input),
+  });
+}
+
 export function useHeadscalePolicy() {
   const { get, put } = useClient();
   const qc = useQueryClient();