From 0454ab2baaa5255fa9ad5afa819d6ee6ae709446 Mon Sep 17 00:00:00 2001
From: Isaac Kargar <kargarisaac@gmail.com>
Date: Sat, 30 May 2026 21:13:47 +0300
Subject: [PATCH 1/3] Enhance context and skills management features by adding
 role filtering and a new skills page. Updated context page to support role
 selection and display, integrated role data into the Graph Explorer, and
 introduced a new SkillsPage component for managing skill targets and
 proposals.

---
 dashboard/app/context/page.tsx                |  43 +-
 dashboard/app/skills/page.tsx                 | 540 +++++++++++++++
 dashboard/components/GraphExplorer.tsx        | 176 +++--
 dashboard/components/RecordEditor.tsx         |  38 +-
 dashboard/components/Sidebar.tsx              |  23 +-
 dashboard/lib/api.ts                          |  71 +-
 dashboard/lib/labels.ts                       |  16 +
 dashboard/lib/types.ts                        | 104 +++
 src/lerim/agents/context_answerer/pipeline.py |  19 +
 src/lerim/agents/context_answerer/schemas.py  |  10 +
 .../agents/context_answerer/signatures.py     |   4 +
 src/lerim/agents/context_brief/pipeline.py    |  10 +
 src/lerim/agents/context_brief/schemas.py     |   4 +
 src/lerim/agents/context_brief/signatures.py  |   6 +-
 .../agents/trace_ingestion/persistence.py     |   3 +
 src/lerim/agents/trace_ingestion/pipeline.py  |  96 +++
 src/lerim/agents/trace_ingestion/schemas.py   |  31 +-
 .../agents/trace_ingestion/signatures.py      |  50 ++
 src/lerim/agents/working_memory/pipeline.py   |   7 +-
 src/lerim/agents/working_memory/signatures.py |   1 +
 src/lerim/context/__init__.py                 |  19 +
 src/lerim/context/retrieval.py                |  12 +
 src/lerim/context/roles.py                    | 144 ++++
 src/lerim/context/spec.py                     |  28 +
 src/lerim/context/store.py                    | 118 +++-
 src/lerim/context_brief.py                    |  17 +-
 src/lerim/mcp_server.py                       |   6 +
 src/lerim/server/api.py                       | 165 +++++
 src/lerim/server/cli.py                       | 205 +++++-
 src/lerim/server/httpd.py                     | 130 ++++
 src/lerim/skill_stewardship/__init__.py       |  12 +
 src/lerim/skill_stewardship/artifacts.py      | 274 ++++++++
 src/lerim/skill_stewardship/patching.py       |  69 ++
 src/lerim/skill_stewardship/pipeline.py       | 302 +++++++++
 src/lerim/skill_stewardship/repository.py     | 616 ++++++++++++++++++
 src/lerim/skill_stewardship/schemas.py        | 173 +++++
 src/lerim/skill_stewardship/signatures.py     |  32 +
 src/lerim/skill_stewardship/validation.py     |  83 +++
 .../trace_ingestion/test_persistence.py       |  32 +
 .../agents/trace_ingestion/test_pipeline.py   |  40 +-
 tests/unit/context/test_spec.py               |  23 +
 tests/unit/context/test_store.py              |  72 ++
 .../unit/skill_stewardship/test_artifacts.py  |  40 ++
 .../test_repository_and_pipeline.py           | 141 ++++
 tests/unit/test_context_brief.py              |  13 +
 45 files changed, 3937 insertions(+), 81 deletions(-)
 create mode 100644 dashboard/app/skills/page.tsx
 create mode 100644 src/lerim/context/roles.py
 create mode 100644 src/lerim/skill_stewardship/__init__.py
 create mode 100644 src/lerim/skill_stewardship/artifacts.py
 create mode 100644 src/lerim/skill_stewardship/patching.py
 create mode 100644 src/lerim/skill_stewardship/pipeline.py
 create mode 100644 src/lerim/skill_stewardship/repository.py
 create mode 100644 src/lerim/skill_stewardship/schemas.py
 create mode 100644 src/lerim/skill_stewardship/signatures.py
 create mode 100644 src/lerim/skill_stewardship/validation.py
 create mode 100644 tests/unit/skill_stewardship/test_artifacts.py
 create mode 100644 tests/unit/skill_stewardship/test_repository_and_pipeline.py

diff --git a/dashboard/app/context/page.tsx b/dashboard/app/context/page.tsx
index 5e2af5d5..049ed641 100644
--- a/dashboard/app/context/page.tsx
+++ b/dashboard/app/context/page.tsx
@@ -2,7 +2,7 @@
 
 import { useEffect, useState, useCallback, useRef } from "react";
 import { api } from "@/lib/api";
-import { formatRecordKind, formatScopeLabel } from "@/lib/labels";
+import { formatRecordKind, formatRecordRole, formatScopeLabel } from "@/lib/labels";
 import type { ContextRecord, IntelligenceResponse } from "@/lib/types";
 import RecordEditor from "@/components/RecordEditor";
 
@@ -12,10 +12,12 @@ export default function ContextPage() {
 	const [debouncedQuery, setDebouncedQuery] = useState("");
 	const [project, setProject] = useState("");
 	const [selectedType, setSelectedType] = useState("");
+	const [selectedRole, setSelectedRole] = useState("");
 	const [statusFilter, setStatusFilter] = useState("active");
 
 	/* ---- filter options from server ---- */
 	const [filterTypes, setFilterTypes] = useState<string[]>([]);
+	const [filterRoles, setFilterRoles] = useState<string[]>([]);
 	const [filterProjects, setFilterProjects] = useState<string[]>([]);
 
 	/* ---- data state ---- */
@@ -53,6 +55,7 @@ export default function ContextPage() {
 			.getRecordFilters()
 			.then((f) => {
 				setFilterTypes(f.types);
+				setFilterRoles(f.roles);
 				setFilterProjects(f.projects);
 			})
 			.catch(() => {
@@ -69,6 +72,7 @@ export default function ContextPage() {
 			if (debouncedQuery) params.q = debouncedQuery;
 			if (project) params.project = project;
 			if (selectedType) params.record_kind = selectedType;
+			if (selectedRole) params.record_role = selectedRole;
 			if (statusFilter) params.status = statusFilter;
 			const data = await api.getRecords(params);
 			setRecords(data.records);
@@ -78,7 +82,7 @@ export default function ContextPage() {
 		} finally {
 			setLoading(false);
 		}
-	}, [debouncedQuery, project, selectedType, statusFilter]);
+	}, [debouncedQuery, project, selectedRole, selectedType, statusFilter]);
 
 	useEffect(() => {
 		load();
@@ -100,6 +104,8 @@ export default function ContextPage() {
 		setSelected(record);
 	};
 
+	const operationalFilterRoles = filterRoles.filter((role) => role !== "general");
+
 	const scrollToIntel = () => {
 		setIntelCollapsed(false);
 		setTimeout(() => {
@@ -199,6 +205,34 @@ export default function ContextPage() {
 						))}
 					</div>
 
+					{operationalFilterRoles.length > 0 && (
+						<div className="mt-2 flex flex-wrap gap-1.5">
+							<button
+								onClick={() => setSelectedRole("")}
+								className={`rounded-full px-3 py-1 text-xs font-medium transition-colors ${
+									selectedRole === ""
+										? "bg-teal-400 text-slate-950"
+										: "bg-white/[0.04] text-[var(--text-muted)] hover:bg-white/[0.08] hover:text-[var(--text-secondary)]"
+								}`}
+							>
+								All roles
+							</button>
+							{operationalFilterRoles.map((role) => (
+								<button
+									key={role}
+									onClick={() => setSelectedRole(selectedRole === role ? "" : role)}
+									className={`rounded-full px-3 py-1 text-xs font-medium transition-colors ${
+										selectedRole === role
+											? "bg-teal-400 text-slate-950"
+											: "bg-white/[0.04] text-[var(--text-muted)] hover:bg-white/[0.08] hover:text-[var(--text-secondary)]"
+									}`}
+								>
+									{formatRecordRole(role)}
+								</button>
+							))}
+						</div>
+					)}
+
 					{/* ---- Error ---- */}
 					{error && (
 						<div className="mt-4 rounded-lg border border-red-500/20 bg-red-500/5 px-4 py-3 text-sm text-red-400">
@@ -246,6 +280,11 @@ export default function ContextPage() {
 														<span className="rounded bg-white/[0.06] px-1.5 py-0.5">
 															{formatRecordKind(record.record_kind)}
 														</span>
+														{record.record_role && record.record_role !== "general" && (
+															<span className="rounded bg-teal-400/10 px-1.5 py-0.5 text-teal-200">
+																{formatRecordRole(record.record_role)}
+															</span>
+														)}
 														{record.project && (
 															<span className="rounded bg-white/[0.06] px-1.5 py-0.5">
 																{formatScopeLabel(record.project)}
diff --git a/dashboard/app/skills/page.tsx b/dashboard/app/skills/page.tsx
new file mode 100644
index 00000000..dd972cbe
--- /dev/null
+++ b/dashboard/app/skills/page.tsx
@@ -0,0 +1,540 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { api } from "@/lib/api";
+import type { SkillProposal, SkillTarget } from "@/lib/types";
+import { useToast } from "@/components/Toast";
+
+export default function SkillsPage() {
+  const { addToast } = useToast();
+  const [targets, setTargets] = useState<SkillTarget[]>([]);
+  const [proposals, setProposals] = useState<SkillProposal[]>([]);
+  const [selectedTargetId, setSelectedTargetId] = useState<string>("");
+  const [selectedProposalId, setSelectedProposalId] = useState<string>("");
+  const [path, setPath] = useState("");
+  const [name, setName] = useState("");
+  const [description, setDescription] = useState("");
+  const [loading, setLoading] = useState(true);
+  const [busy, setBusy] = useState<string | null>(null);
+  const [editText, setEditText] = useState("");
+  const [selectedPatchIndex, setSelectedPatchIndex] = useState(0);
+
+  const load = useCallback(async () => {
+    setLoading(true);
+    try {
+      const [targetData, proposalData] = await Promise.all([
+        api.getSkillTargets(),
+        api.getSkillProposals(),
+      ]);
+      setTargets(targetData.targets);
+      setProposals(proposalData.proposals);
+      if (!selectedTargetId && targetData.targets[0]) setSelectedTargetId(targetData.targets[0].target_id);
+      if (!selectedProposalId && proposalData.proposals[0]) setSelectedProposalId(proposalData.proposals[0].proposal_id);
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Failed to load skills" });
+    } finally {
+      setLoading(false);
+    }
+  }, [addToast, selectedProposalId, selectedTargetId]);
+
+  useEffect(() => {
+    load();
+  }, [load]);
+
+  const selectedTarget = targets.find((target) => target.target_id === selectedTargetId) || targets[0] || null;
+  const filteredProposals = useMemo(
+    () => proposals.filter((proposal) => !selectedTarget || proposal.target_id === selectedTarget.target_id),
+    [proposals, selectedTarget],
+  );
+  const selectedProposal =
+    filteredProposals.find((proposal) => proposal.proposal_id === selectedProposalId) ||
+    filteredProposals[0] ||
+    null;
+  const selectedPatch = selectedProposal?.patch_json.patches[selectedPatchIndex] || null;
+
+  useEffect(() => {
+    setSelectedPatchIndex(0);
+  }, [selectedProposal?.proposal_id]);
+
+  useEffect(() => {
+    setEditText(selectedPatch?.after_text || "");
+  }, [selectedPatch?.after_text, selectedPatchIndex, selectedProposal?.proposal_id]);
+
+  const register = async () => {
+    if (!path.trim()) return;
+    setBusy("register");
+    try {
+      await api.addSkillTarget({
+        path: path.trim(),
+        name: name.trim() || undefined,
+        description: description.trim() || undefined,
+        update_mode: "review",
+      });
+      setPath("");
+      setName("");
+      setDescription("");
+      addToast({ type: "success", message: "Skill registered" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Could not register skill" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const refreshTarget = async (target: SkillTarget) => {
+    setBusy(`refresh:${target.target_id}`);
+    try {
+      await api.refreshSkillTarget(target.target_id);
+      addToast({ type: "success", message: "Refresh completed" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Refresh failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const toggleAutoApply = async (target: SkillTarget) => {
+    const enabled = target.update_mode !== "auto_apply";
+    setBusy(`mode:${target.target_id}`);
+    try {
+      await api.updateSkillTargetMode(target.target_id, {
+        update_mode: enabled ? "auto_apply" : "review",
+        auto_apply_policy: { ...target.auto_apply_policy, enabled, max_risk: "low" },
+      });
+      addToast({ type: "success", message: enabled ? "Auto-apply enabled" : "Auto-apply disabled" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Mode update failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const applyProposal = async (proposal: SkillProposal) => {
+    setBusy(`apply:${proposal.proposal_id}`);
+    try {
+      await api.applySkillProposal(proposal.proposal_id);
+      addToast({ type: "success", message: "Proposal applied" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Apply failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const rejectProposal = async (proposal: SkillProposal) => {
+    setBusy(`reject:${proposal.proposal_id}`);
+    try {
+      await api.rejectSkillProposal(proposal.proposal_id);
+      addToast({ type: "success", message: "Proposal rejected" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Reject failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  const saveEditedProposal = async (proposal: SkillProposal) => {
+    if (!selectedPatch) return;
+    setBusy(`edit:${proposal.proposal_id}`);
+    try {
+      await api.editSkillProposal(proposal.proposal_id, {
+        ...proposal.patch_json,
+        patches: proposal.patch_json.patches.map((patch, index) =>
+          index === selectedPatchIndex ? { ...patch, after_text: editText } : patch,
+        ),
+      });
+      addToast({ type: "success", message: "Proposal updated" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Edit failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
+  return (
+    <div className="space-y-5">
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <h1 className="text-lg font-semibold text-[var(--text)]">Skills</h1>
+          <p className="mt-1 max-w-2xl text-sm text-[var(--text-secondary)]">
+            Registered instruction artifacts, evidence-backed updates, and review gates.
+          </p>
+        </div>
+        <button
+          type="button"
+          onClick={load}
+          className="min-h-11 rounded-md border border-[var(--border)] px-4 text-sm font-medium text-[var(--text)] hover:bg-white/[0.05]"
+        >
+          Refresh
+        </button>
+      </div>
+
+      <section className="grid min-w-0 gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4 md:grid-cols-[minmax(0,1fr)_10rem]">
+        <div className="grid gap-3 md:grid-cols-3">
+          <input
+            value={path}
+            onChange={(event) => setPath(event.target.value)}
+            placeholder="Path to SKILL.md, AGENTS.md, or skill folder"
+            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] md:col-span-3"
+          />
+          <input
+            value={name}
+            onChange={(event) => setName(event.target.value)}
+            placeholder="Name"
+            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+          />
+          <input
+            value={description}
+            onChange={(event) => setDescription(event.target.value)}
+            placeholder="Improvement intent"
+            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] md:col-span-2"
+          />
+        </div>
+        <button
+          type="button"
+          onClick={register}
+          disabled={busy === "register" || !path.trim()}
+          className="min-h-11 rounded-md bg-[var(--accent-blue)] px-4 text-sm font-semibold text-white disabled:cursor-not-allowed disabled:opacity-50"
+        >
+          Register
+        </button>
+      </section>
+
+      <div className="grid min-w-0 gap-4 lg:grid-cols-[minmax(18rem,22rem)_minmax(0,1fr)]">
+        <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
+          <div className="border-b border-[var(--border)] px-4 py-3">
+            <h2 className="text-sm font-semibold text-[var(--text)]">Registered Skills</h2>
+          </div>
+          <div className="max-h-[34rem] overflow-y-auto p-2">
+            {loading && <div className="p-3 text-sm text-[var(--text-muted)]">Loading…</div>}
+            {!loading && targets.length === 0 && <div className="p-3 text-sm text-[var(--text-muted)]">No skills registered.</div>}
+            {targets.map((target) => (
+              <button
+                key={target.target_id}
+                type="button"
+                onClick={() => setSelectedTargetId(target.target_id)}
+                className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left transition-colors ${
+                  selectedTarget?.target_id === target.target_id
+                    ? "border-[var(--accent-blue)] bg-blue-500/10"
+                    : "border-[var(--border)] bg-white/[0.02] hover:bg-white/[0.05]"
+                }`}
+              >
+                <div className="flex items-center justify-between gap-2">
+                  <span className="truncate text-sm font-semibold text-[var(--text)]">{target.name}</span>
+                  <span className="rounded-full bg-white/[0.06] px-2 py-0.5 text-[10px] text-[var(--text-secondary)]">
+                    {target.update_mode}
+                  </span>
+                </div>
+                <div className="mt-1 truncate text-xs text-[var(--text-muted)]">{target.path}</div>
+                <div className="mt-2 flex flex-wrap gap-1.5 text-[10px] text-[var(--text-secondary)]">
+                  <span className="rounded bg-white/[0.05] px-1.5 py-0.5">{target.target_type}</span>
+                  <span className="rounded bg-white/[0.05] px-1.5 py-0.5">{target.file_count || 0} files</span>
+                </div>
+              </button>
+            ))}
+          </div>
+        </section>
+
+        <section className="min-w-0 space-y-4">
+          {selectedTarget && (
+            <div className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4">
+              <div className="flex flex-wrap items-start justify-between gap-3">
+                <div className="min-w-0">
+                  <h2 className="truncate text-base font-semibold text-[var(--text)]">{selectedTarget.name}</h2>
+                  <p className="mt-1 break-all text-xs text-[var(--text-muted)]">{selectedTarget.path}</p>
+                </div>
+                <div className="flex flex-wrap gap-2">
+                  <button
+                    type="button"
+                    onClick={() => refreshTarget(selectedTarget)}
+                    disabled={busy === `refresh:${selectedTarget.target_id}`}
+                    className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] hover:bg-white/[0.05] disabled:opacity-50"
+                  >
+                    Scan
+                  </button>
+                  <button
+                    type="button"
+                    onClick={() => toggleAutoApply(selectedTarget)}
+                    disabled={busy === `mode:${selectedTarget.target_id}`}
+                    className={`min-h-10 rounded-md px-3 text-xs font-semibold disabled:opacity-50 ${
+                      selectedTarget.update_mode === "auto_apply"
+                        ? "bg-emerald-400 text-slate-950"
+                        : "border border-[var(--border)] text-[var(--text)] hover:bg-white/[0.05]"
+                    }`}
+                  >
+                    Auto
+                  </button>
+                </div>
+              </div>
+              <div className="mt-4 grid gap-3 md:grid-cols-3">
+                <Metric label="Type" value={selectedTarget.target_type} />
+                <Metric label="Entry" value={selectedTarget.entry_file} />
+                <Metric label="Pending" value={String(filteredProposals.filter((proposal) => proposal.status === "pending_review").length)} />
+              </div>
+              <div className="mt-4 grid gap-3 lg:grid-cols-2">
+                <FileList title="Tracked Files" files={selectedTarget.files || []} />
+                <ManifestPanel target={selectedTarget} />
+              </div>
+            </div>
+          )}
+
+            <div className="grid min-w-0 gap-4 xl:grid-cols-[minmax(18rem,22rem)_minmax(0,1fr)]">
+            <ProposalList
+              proposals={filteredProposals}
+              selectedId={selectedProposal?.proposal_id || ""}
+              onSelect={setSelectedProposalId}
+            />
+            <ProposalReview
+              proposal={selectedProposal}
+              editText={editText}
+              onEditText={setEditText}
+              selectedPatchIndex={selectedPatchIndex}
+              onSelectPatch={setSelectedPatchIndex}
+              onSave={saveEditedProposal}
+              onApply={applyProposal}
+              onReject={rejectProposal}
+              busy={busy}
+            />
+          </div>
+        </section>
+      </div>
+    </div>
+  );
+}
+
+function Metric({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
+      <div className="text-[10px] uppercase text-[var(--text-muted)]">{label}</div>
+      <div className="mt-1 truncate text-sm font-medium text-[var(--text)]">{value}</div>
+    </div>
+  );
+}
+
+function FileList({ title, files }: { title: string; files: NonNullable<SkillTarget["files"]> }) {
+  return (
+    <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
+      <h3 className="text-xs font-semibold text-[var(--text)]">{title}</h3>
+      <div className="mt-2 max-h-44 space-y-1 overflow-y-auto">
+        {files.map((file) => (
+          <div key={file.relative_path} className="flex items-center justify-between gap-2 text-xs">
+            <span className="min-w-0 truncate text-[var(--text-secondary)]">{file.relative_path}</span>
+            <span className="shrink-0 rounded bg-white/[0.05] px-1.5 py-0.5 text-[10px] text-[var(--text-muted)]">
+              {file.file_role}
+            </span>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function ManifestPanel({ target }: { target: SkillTarget }) {
+  const manifest = target.manifest;
+  return (
+    <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
+      <h3 className="text-xs font-semibold text-[var(--text)]">Update Surfaces</h3>
+      <div className="mt-2 flex flex-wrap gap-1.5">
+        {(manifest?.allowed_update_surfaces || []).map((surface) => (
+          <span key={surface} className="rounded bg-emerald-400/10 px-2 py-1 text-[10px] text-emerald-200">
+            {surface}
+          </span>
+        ))}
+        {(manifest?.high_risk_surfaces || []).map((surface) => (
+          <span key={surface} className="rounded bg-amber-400/10 px-2 py-1 text-[10px] text-amber-200">
+            {surface}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function ProposalList({
+  proposals,
+  selectedId,
+  onSelect,
+}: {
+  proposals: SkillProposal[];
+  selectedId: string;
+  onSelect: (id: string) => void;
+}) {
+  return (
+    <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
+      <div className="border-b border-[var(--border)] px-4 py-3">
+        <h2 className="text-sm font-semibold text-[var(--text)]">Updates</h2>
+      </div>
+      <div className="max-h-[30rem] overflow-y-auto p-2">
+        {proposals.length === 0 && <div className="p-3 text-sm text-[var(--text-muted)]">No update proposals.</div>}
+        {proposals.map((proposal) => (
+          <button
+            key={proposal.proposal_id}
+            type="button"
+            onClick={() => onSelect(proposal.proposal_id)}
+            className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left ${
+              selectedId === proposal.proposal_id
+                ? "border-[var(--accent-blue)] bg-blue-500/10"
+                : "border-[var(--border)] bg-white/[0.02] hover:bg-white/[0.05]"
+            }`}
+          >
+            <div className="flex items-center justify-between gap-2">
+              <span className="line-clamp-1 text-sm font-semibold text-[var(--text)]">{proposal.title}</span>
+              <span className={`rounded-full px-2 py-0.5 text-[10px] ${riskClass(proposal.risk_level)}`}>
+                {proposal.risk_level}
+              </span>
+            </div>
+            <div className="mt-1 line-clamp-2 text-xs text-[var(--text-secondary)]">{proposal.summary}</div>
+            <div className="mt-2 text-[10px] text-[var(--text-muted)]">{proposal.status}</div>
+          </button>
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function ProposalReview({
+  proposal,
+  editText,
+  onEditText,
+  selectedPatchIndex,
+  onSelectPatch,
+  onSave,
+  onApply,
+  onReject,
+  busy,
+}: {
+  proposal: SkillProposal | null;
+  editText: string;
+  onEditText: (value: string) => void;
+  selectedPatchIndex: number;
+  onSelectPatch: (index: number) => void;
+  onSave: (proposal: SkillProposal) => void;
+  onApply: (proposal: SkillProposal) => void;
+  onReject: (proposal: SkillProposal) => void;
+  busy: string | null;
+}) {
+  if (!proposal) {
+    return (
+      <section className="min-w-0 rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4 text-sm text-[var(--text-muted)]">
+        Select an update proposal to review.
+      </section>
+    );
+  }
+  const patches = proposal.patch_json.patches;
+  const patch = patches[selectedPatchIndex] || patches[0];
+  return (
+    <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
+      <div className="border-b border-[var(--border)] p-4">
+        <div className="flex flex-wrap items-start justify-between gap-3">
+          <div>
+            <h2 className="text-base font-semibold text-[var(--text)]">{proposal.title}</h2>
+            <p className="mt-1 text-sm text-[var(--text-secondary)]">{proposal.summary}</p>
+          </div>
+          <span className={`rounded-full px-2.5 py-1 text-xs ${riskClass(proposal.risk_level)}`}>{proposal.risk_level}</span>
+        </div>
+        <div className="mt-3 flex flex-wrap gap-1.5">
+          {Array.from(new Set(patches.flatMap((item) => item.evidence_record_ids || []))).map((recordId) => (
+            <span key={recordId} className="rounded bg-white/[0.05] px-2 py-1 text-[10px] text-[var(--text-secondary)]">
+              {recordId}
+            </span>
+          ))}
+        </div>
+        {patches.length > 1 && (
+          <div className="mt-3 flex flex-wrap gap-2">
+            {patches.map((item, index) => (
+              <button
+                key={`${item.relative_path}:${index}`}
+                type="button"
+                onClick={() => onSelectPatch(index)}
+                className={`min-h-8 max-w-full rounded-md border px-2 text-xs ${
+                  index === selectedPatchIndex
+                    ? "border-[var(--accent-blue)] bg-blue-500/10 text-[var(--text)]"
+                    : "border-[var(--border)] text-[var(--text-secondary)] hover:bg-white/[0.05]"
+                }`}
+              >
+                <span className="block max-w-56 truncate">{item.relative_path}</span>
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+      {patch ? (
+        <div className="grid gap-0 lg:grid-cols-2">
+          <div className="border-b border-[var(--border)] p-4 lg:border-b-0 lg:border-r">
+            <div className="mb-2 flex items-center justify-between gap-2">
+              <h3 className="text-xs font-semibold text-[var(--text)]">Editable Result</h3>
+              <span className="text-[10px] text-[var(--text-muted)]">{patch.relative_path}</span>
+            </div>
+            <textarea
+              value={editText}
+              onChange={(event) => onEditText(event.target.value)}
+              className="h-[26rem] w-full resize-y rounded-md border border-[var(--border)] bg-black/30 p-3 font-mono text-xs leading-5 text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+            />
+          </div>
+          <div className="p-4">
+            <h3 className="mb-2 text-xs font-semibold text-[var(--text)]">Diff</h3>
+            <pre className="h-[26rem] overflow-auto rounded-md border border-[var(--border)] bg-black/30 p-3 text-xs leading-5 text-[var(--text-secondary)]">
+              {patch.diff_text || "No diff available until the proposal is regenerated."}
+            </pre>
+          </div>
+        </div>
+      ) : (
+        <div className="p-4 text-sm text-[var(--text-muted)]">This proposal has no patch.</div>
+      )}
+      <div className="flex flex-wrap items-center justify-between gap-3 border-t border-[var(--border)] p-4">
+        <ValidationState proposal={proposal} />
+        <div className="flex flex-wrap gap-2">
+          <button
+            type="button"
+            onClick={() => onSave(proposal)}
+            disabled={!patch || busy === `edit:${proposal.proposal_id}`}
+            className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] hover:bg-white/[0.05] disabled:opacity-50"
+          >
+            Save Edit
+          </button>
+          <button
+            type="button"
+            onClick={() => onReject(proposal)}
+            disabled={busy === `reject:${proposal.proposal_id}`}
+            className="min-h-10 rounded-md border border-red-400/30 px-3 text-xs font-medium text-red-200 hover:bg-red-400/10 disabled:opacity-50"
+          >
+            Reject
+          </button>
+          <button
+            type="button"
+            onClick={() => onApply(proposal)}
+            disabled={busy === `apply:${proposal.proposal_id}` || proposal.status === "applied"}
+            className="min-h-10 rounded-md bg-emerald-400 px-3 text-xs font-semibold text-slate-950 disabled:opacity-50"
+          >
+            Apply
+          </button>
+        </div>
+      </div>
+    </section>
+  );
+}
+
+function ValidationState({ proposal }: { proposal: SkillProposal }) {
+  const ok = proposal.validation_json?.ok;
+  const errors = proposal.validation_json?.errors || [];
+  return (
+    <div className="text-xs">
+      <span className={ok ? "text-emerald-300" : "text-amber-200"}>
+        {ok ? "Validation passed" : "Needs review"}
+      </span>
+      {errors.length > 0 && <span className="ml-2 text-[var(--text-muted)]">{errors[0]}</span>}
+    </div>
+  );
+}
+
+function riskClass(risk: string) {
+  if (risk === "high") return "bg-red-400/10 text-red-200";
+  if (risk === "medium") return "bg-amber-400/10 text-amber-200";
+  return "bg-emerald-400/10 text-emerald-200";
+}
diff --git a/dashboard/components/GraphExplorer.tsx b/dashboard/components/GraphExplorer.tsx
index 523ae980..4e2b606a 100644
--- a/dashboard/components/GraphExplorer.tsx
+++ b/dashboard/components/GraphExplorer.tsx
@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import {
   CanvasEvent,
   ComboEvent,
@@ -15,7 +15,7 @@ import {
   type NodeData,
 } from "@antv/g6";
 import { api } from "@/lib/api";
-import { formatRecordKind, formatScopeLabel, humanizeToken } from "@/lib/labels";
+import { formatRecordKind, formatRecordRole, formatScopeLabel, humanizeToken } from "@/lib/labels";
 import type { GraphEdge, GraphNode } from "@/lib/types";
 
 interface GraphExplorerProps {
@@ -23,6 +23,7 @@ interface GraphExplorerProps {
 }
 
 type ClusterBy = "semantic" | "off";
+type ColorBy = "type" | "role";
 type Selection =
   | { kind: "node"; node: GraphNode }
   | { kind: "edge"; edge: GraphEdge }
@@ -43,6 +44,7 @@ type ClusterSummary = {
   description: string;
   representativeTitles: string[];
   topKinds: string[];
+  topRoles: string[];
   topProjects: string[];
   color: string;
   nodes: GraphNode[];
@@ -83,6 +85,16 @@ const KIND_COLORS: Record<string, string> = {
   context_record: "#64748b",
 };
 
+const ROLE_COLORS: Record<string, string> = {
+  general: "#64748b",
+  procedure: "#22c55e",
+  gotcha: "#f59e0b",
+  failure_mode: "#fb7185",
+  artifact: "#38bdf8",
+  state_change: "#a78bfa",
+  eval_asset: "#2dd4bf",
+};
+
 const RELATION_COLORS: Record<GraphEdge["kind"], string> = {
   supports: "#4ade80",
   refines: "#60a5fa",
@@ -123,6 +135,11 @@ const CLUSTER_OPTIONS: Array<{ value: ClusterBy; label: string; hint: string }>
   { value: "off", label: "Off", hint: "Show records without cluster bubbles" },
 ];
 
+const COLOR_OPTIONS: Array<{ value: ColorBy; label: string; hint: string }> = [
+  { value: "type", label: "Kind", hint: "Color nodes by record kind" },
+  { value: "role", label: "Role", hint: "Color nodes by operational role" },
+];
+
 function edgeKey(edge: GraphEdge, index: number) {
   return edge.id || `${edge.source}:${edge.kind}:${edge.target}:${index}`;
 }
@@ -142,7 +159,10 @@ function shortLabel(value?: string | null, max = 34) {
   return label.length > max ? `${label.slice(0, max - 1)}...` : label;
 }
 
-function nodeColor(node: GraphNode) {
+function nodeColor(node: GraphNode, colorBy: ColorBy) {
+  if (colorBy === "role") {
+    return ROLE_COLORS[(node.record_role || "general").toLowerCase()] || "#64748b";
+  }
   return KIND_COLORS[(node.record_kind || "").toLowerCase()] || "#64748b";
 }
 
@@ -218,10 +238,12 @@ function clusterId(value: string) {
 function clusterDescription(nodes: GraphNode[]) {
   const titles = representativeTitles(nodes);
   const kinds = rankedValues(nodes.map((node) => node.record_kind), 2).map(formatRecordKind);
+  const roles = rankedValues(nodes.map((node) => node.record_role || "general"), 2).map(formatRecordRole);
   const projects = rankedValues(nodes.map((node) => node.project), 2).map(formatScopeLabel);
 
   const parts = [];
   if (kinds.length) parts.push(kinds.join(" / "));
+  if (roles.length && roles.some((role) => role !== "General")) parts.push(roles.join(" + "));
   if (projects.length) parts.push(projects.join(" + "));
   if (titles.length) parts.push(titles.slice(0, 2).join(" - "));
   return parts.join(" - ") || "No summary available";
@@ -277,6 +299,7 @@ function buildClusters(nodes: GraphNode[], edges: GraphEdge[], clusterBy: Cluste
       description: "",
       representativeTitles: [],
       topKinds: [],
+      topRoles: [],
       topProjects: [],
       color: CLUSTER_COLORS[clusters.size % CLUSTER_COLORS.length],
       nodes: [],
@@ -304,6 +327,7 @@ function buildClusters(nodes: GraphNode[], edges: GraphEdge[], clusterBy: Cluste
       description: clusterDescription(cluster.nodes),
       representativeTitles: representativeTitles(cluster.nodes),
       topKinds: rankedValues(cluster.nodes.map((node) => node.record_kind), 3).map(formatRecordKind),
+      topRoles: rankedValues(cluster.nodes.map((node) => node.record_role || "general"), 3).map(formatRecordRole),
       topProjects: rankedValues(cluster.nodes.map((node) => node.project), 3).map(formatScopeLabel),
     };
     return {
@@ -458,6 +482,7 @@ function buildGraphData(
   clusters: ClusterSummary[],
   nodeCluster: Map<string, string>,
   edgeLength: number,
+  colorBy: ColorBy,
 ): GraphData {
   const nodeIds = new Set(nodes.map((node) => node.id));
   const placements = clusterPlacements(clusters, edgeLength);
@@ -503,7 +528,7 @@ function buildGraphData(
         },
         data: {
           record: node,
-          color: nodeColor(node),
+          color: nodeColor(node, colorBy),
           label: shortLabel(node.label || formatRecordKind(node.record_kind), clusters.length ? 30 : 42),
           size: nodeSize(node, clusters.length === 0),
         } satisfies NodeDatumData,
@@ -677,6 +702,7 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
     truncated: false,
   });
   const [clusterBy, setClusterBy] = useState<ClusterBy>("semantic");
+  const [colorBy, setColorBy] = useState<ColorBy>("type");
   const [maxNodes, setMaxNodes] = useState(DEFAULT_MAX_NODES);
   const [edgeLength, setEdgeLength] = useState(DEFAULT_EDGE_LENGTH);
   const [selected, setSelected] = useState<Selection>(null);
@@ -705,8 +731,8 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
   );
 
   const graphData = useMemo(
-    () => buildGraphData(graph.nodes, graph.edges, clusters, nodeCluster, edgeLength),
-    [clusters, edgeLength, graph.edges, graph.nodes, nodeCluster],
+    () => buildGraphData(graph.nodes, graph.edges, clusters, nodeCluster, edgeLength, colorBy),
+    [clusters, colorBy, edgeLength, graph.edges, graph.nodes, nodeCluster],
   );
   const relationCounts = useMemo(() => {
     const counts = new Map<GraphEdge["kind"], number>();
@@ -721,6 +747,19 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
     });
     return counts;
   }, [graph.nodes]);
+  const recordRoleCounts = useMemo(() => {
+    const counts = new Map<string, number>();
+    graph.nodes.forEach((node) => {
+      const role = (node.record_role || "general").toLowerCase();
+      counts.set(role, (counts.get(role) || 0) + 1);
+    });
+    return counts;
+  }, [graph.nodes]);
+  const hasOperationalRoles = useMemo(
+    () => Array.from(recordRoleCounts.keys()).some((role) => role !== "general"),
+    [recordRoleCounts],
+  );
+  const legendCounts = colorBy === "role" ? recordRoleCounts : recordKindCounts;
 
   useEffect(() => {
     nodeByIdRef.current = nodeById;
@@ -728,7 +767,7 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
     clusterByIdRef.current = clusterById;
   }, [clusterById, edgeByKey, nodeById]);
 
-  async function loadGraph() {
+  const loadGraph = useCallback(async () => {
     setLoading(true);
     setError(null);
     try {
@@ -750,13 +789,18 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
     } finally {
       setLoading(false);
     }
-  }
+  }, [maxNodes]);
 
   useEffect(() => {
-    loadGraph();
-    // Initial load only. Refresh button applies max-node changes.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, []);
+    const reloadId = window.setTimeout(() => {
+      void loadGraph();
+    }, 180);
+    return () => window.clearTimeout(reloadId);
+  }, [loadGraph]);
+
+  useEffect(() => {
+    if (colorBy === "role" && !hasOperationalRoles) setColorBy("type");
+  }, [colorBy, hasOperationalRoles]);
 
   useEffect(() => {
     if (!containerRef.current || graphRef.current) return;
@@ -869,14 +913,41 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
               </button>
             ))}
           </div>
+          <div className="flex h-9 items-center gap-1 rounded-full border border-white/10 bg-white/[0.045] p-1 shadow-sm">
+            {COLOR_OPTIONS.map((option) => {
+              const disabled = option.value === "role" && !hasOperationalRoles;
+              return (
+              <button
+                key={option.value}
+                type="button"
+                title={disabled ? "No operational role records in this graph yet." : option.hint}
+                disabled={disabled}
+                onClick={() => {
+                  if (!disabled) setColorBy(option.value);
+                }}
+                className={`h-7 rounded-full px-3 text-xs font-medium transition ${
+                  colorBy === option.value
+                    ? "bg-teal-300 text-slate-950 shadow-[0_0_18px_rgba(45,212,191,0.24)]"
+                    : disabled
+                      ? "cursor-not-allowed text-slate-600"
+                      : "text-slate-300 hover:bg-white/8 hover:text-white"
+                }`}
+              >
+                {option.label}
+              </button>
+            );})}
+          </div>
           <label className="flex h-9 items-center gap-2 rounded-full border border-white/10 bg-white/[0.045] px-3 text-xs text-slate-300 shadow-sm">
-            Nodes
+            Limit
             <input
               type="number"
               min={40}
               max={400}
               value={maxNodes}
-              onChange={(event) => setMaxNodes(Number(event.target.value))}
+              onChange={(event) => {
+                const value = Number(event.target.value);
+                setMaxNodes(Number.isFinite(value) ? Math.max(40, Math.min(400, value)) : 40);
+              }}
               className="w-16 bg-transparent text-sm text-white outline-none"
             />
           </label>
@@ -909,20 +980,25 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
           <div className="pointer-events-none absolute inset-0 z-[1] bg-[radial-gradient(circle_at_center,transparent,rgba(2,6,23,0.62))]" />
           <div ref={containerRef} className="absolute inset-0 z-[2]" />
 
-          {!loading && !error && graph.nodes.length > 0 && recordKindCounts.size > 0 && (
+          {!loading && !error && graph.nodes.length > 0 && legendCounts.size > 0 && (
             <div className="pointer-events-none absolute bottom-4 left-4 z-10 max-w-[calc(100%-2rem)] rounded-2xl border border-white/10 bg-slate-950/72 p-3 shadow-2xl shadow-black/30 backdrop-blur-md">
-              <div className="mb-2 text-[10px] font-semibold uppercase tracking-[0.18em] text-slate-500">Node types</div>
+              <div className="mb-2 text-[10px] font-semibold uppercase tracking-[0.18em] text-slate-500">
+                {colorBy === "role" ? "Node roles" : "Node kinds"}
+              </div>
               <div className="flex flex-wrap gap-2">
-                {Array.from(recordKindCounts.entries()).sort((a, b) => b[1] - a[1]).map(([kind, count]) => (
-                  <div key={kind} className="flex items-center gap-2 rounded-full border border-white/10 bg-white/[0.045] px-2.5 py-1.5 text-xs text-slate-200">
+                {Array.from(legendCounts.entries()).sort((a, b) => b[1] - a[1]).map(([value, count]) => {
+                  const color = colorBy === "role" ? ROLE_COLORS[value] || "#64748b" : KIND_COLORS[value] || "#64748b";
+                  const label = colorBy === "role" ? formatRecordRole(value) : formatRecordKind(value);
+                  return (
+                  <div key={value} className="flex items-center gap-2 rounded-full border border-white/10 bg-white/[0.045] px-2.5 py-1.5 text-xs text-slate-200">
                     <span
                       className="h-2.5 w-2.5 rounded-full shadow-[0_0_14px_currentColor]"
-                      style={{ backgroundColor: KIND_COLORS[kind] || "#64748b", color: KIND_COLORS[kind] || "#64748b" }}
+                      style={{ backgroundColor: color, color }}
                     />
-                    <span className="font-medium">{formatRecordKind(kind)}</span>
+                    <span className="font-medium">{label}</span>
                     <span className="text-slate-500">{count}</span>
                   </div>
-                ))}
+                );})}
               </div>
             </div>
           )}
@@ -953,7 +1029,7 @@ export default function GraphExplorer({ onRecordClick }: GraphExplorerProps) {
           <DetailsPanel
             selection={selected}
             nodeById={nodeById}
-            recordKindCounts={recordKindCounts}
+            colorBy={colorBy}
             relationCounts={relationCounts}
             onOpenRecord={onRecordClick}
           />
@@ -974,13 +1050,13 @@ function Metric({ label, value }: { label: string; value: number }) {
 function DetailsPanel({
   selection,
   nodeById,
-  recordKindCounts,
+  colorBy,
   relationCounts,
   onOpenRecord,
 }: {
   selection: Selection;
   nodeById: Map<string, GraphNode>;
-  recordKindCounts: Map<string, number>;
+  colorBy: ColorBy;
   relationCounts: Map<GraphEdge["kind"], number>;
   onOpenRecord?: (recordId: string) => void;
 }) {
@@ -998,25 +1074,6 @@ function DetailsPanel({
           <span className="rounded-lg border border-white/10 bg-white/[0.035] px-2 py-2">records</span>
           <span className="rounded-lg border border-white/10 bg-white/[0.035] px-2 py-2">links</span>
         </div>
-        {recordKindCounts.size > 0 && (
-          <div className="mt-5">
-            <div className="mb-2 text-xs font-medium uppercase tracking-wide text-slate-500">Record types</div>
-            <div className="grid grid-cols-2 gap-2">
-              {Array.from(recordKindCounts.entries()).sort((a, b) => b[1] - a[1]).map(([kind, count]) => (
-                <div key={kind} className="rounded-xl border border-white/10 bg-white/[0.035] px-3 py-2">
-                  <div className="flex items-center gap-2">
-                    <span
-                      className="h-2.5 w-2.5 rounded-full shadow-[0_0_14px_currentColor]"
-                      style={{ backgroundColor: KIND_COLORS[kind] || "#64748b", color: KIND_COLORS[kind] || "#64748b" }}
-                    />
-                    <span className="text-xs font-semibold text-slate-100">{formatRecordKind(kind)}</span>
-                  </div>
-                  <div className="mt-1 text-[11px] text-slate-500">{count} records</div>
-                </div>
-              ))}
-            </div>
-          </div>
-        )}
         {relationCounts.size > 0 && (
           <div className="mt-5">
             <div className="mb-2 text-xs font-medium uppercase tracking-wide text-slate-500">Relationship catalog</div>
@@ -1064,7 +1121,10 @@ function DetailsPanel({
         </div>
 
         <div className="grid grid-cols-2 gap-3 text-xs">
-          <Detail label="Main types" value={selection.cluster.topKinds.join(", ") || "Unknown"} />
+          <Detail label="Main kinds" value={selection.cluster.topKinds.join(", ") || "Unknown"} />
+          {selection.cluster.topRoles.some((role) => role !== "General") && (
+            <Detail label="Roles" value={selection.cluster.topRoles.join(", ")} />
+          )}
           <Detail label="Projects" value={selection.cluster.topProjects.join(", ") || "Unscoped"} />
         </div>
 
@@ -1108,13 +1168,17 @@ function DetailsPanel({
     );
   }
 
+  const nodeRole = selection.node.record_role && selection.node.record_role !== "general"
+    ? formatRecordRole(selection.node.record_role)
+    : "";
+
   return (
     <div className="space-y-4">
       <div className="rounded-2xl border border-white/10 bg-white/[0.035] p-4">
-        <div className="mb-3 h-2 w-16 rounded-full shadow-[0_0_22px_currentColor]" style={{ backgroundColor: nodeColor(selection.node) }} />
+        <div className="mb-3 h-2 w-16 rounded-full shadow-[0_0_22px_currentColor]" style={{ backgroundColor: nodeColor(selection.node, colorBy) }} />
         <h2 className="text-base font-semibold leading-6 text-white">{selection.node.label || "Untitled record"}</h2>
         <p className="mt-1 text-xs text-slate-400">
-          {formatRecordKind(selection.node.record_kind)} - {formatScopeLabel(selection.node.project)} - {compactDate(selection.node.updated_at)}
+          {formatRecordKind(selection.node.record_kind)}{nodeRole ? ` - ${nodeRole}` : ""} - {formatScopeLabel(selection.node.project)} - {compactDate(selection.node.updated_at)}
         </p>
       </div>
 
@@ -1128,12 +1192,22 @@ function DetailsPanel({
       )}
 
       <div className="grid grid-cols-2 gap-3 text-xs">
-        <Detail label="Type" value={formatRecordKind(selection.node.record_kind)} />
+        <Detail label="Kind" value={formatRecordKind(selection.node.record_kind)} />
+        {nodeRole && <Detail label="Role" value={nodeRole} />}
         <Detail label="Confidence" value={`${Math.round((selection.node.confidence || 0) * 100)}%`} />
         <Detail label="Status" value={selection.node.status || "active"} />
         <Detail label="Project" value={formatScopeLabel(selection.node.project)} />
       </div>
 
+      {selection.node.role_payload && (
+        <div className="rounded-2xl border border-white/10 bg-white/[0.035] p-4">
+          <div className="text-xs font-medium uppercase tracking-wide text-slate-500">Role payload</div>
+          <pre className="mt-2 whitespace-pre-wrap break-words text-xs leading-5 text-slate-300">
+            {formatRolePayload(selection.node.role_payload)}
+          </pre>
+        </div>
+      )}
+
       {selection.node.tags && selection.node.tags.length > 0 && (
         <div className="flex flex-wrap gap-1.5">
           {selection.node.tags.slice(0, 10).map((tag) => (
@@ -1163,3 +1237,11 @@ function Detail({ label, value }: { label: string; value: string }) {
     </div>
   );
 }
+
+function formatRolePayload(payload: string) {
+  try {
+    return JSON.stringify(JSON.parse(payload), null, 2);
+  } catch {
+    return payload;
+  }
+}
diff --git a/dashboard/components/RecordEditor.tsx b/dashboard/components/RecordEditor.tsx
index 6c5765da..8b669f79 100644
--- a/dashboard/components/RecordEditor.tsx
+++ b/dashboard/components/RecordEditor.tsx
@@ -1,4 +1,4 @@
-import { formatRecordKind, formatScopeLabel } from "@/lib/labels";
+import { formatRecordKind, formatRecordRole, formatScopeLabel, humanizeToken } from "@/lib/labels";
 import type { ContextRecord } from "@/lib/types";
 
 interface RecordEditorProps {
@@ -6,6 +6,7 @@ interface RecordEditorProps {
 }
 
 export default function RecordEditor({ record }: RecordEditorProps) {
+  const rolePayload = parseRolePayload(record.role_payload);
   return (
     <div className="flex h-full flex-col rounded-lg border border-[var(--border)] bg-[var(--bg-subtle)]">
       <div className="flex items-center justify-between border-b border-[var(--border)] px-5 py-3">
@@ -22,6 +23,9 @@ export default function RecordEditor({ record }: RecordEditorProps) {
 
         <div className="flex flex-wrap items-center gap-3">
           <Pill label="Type" value={formatRecordKind(record.record_kind)} />
+          {record.record_role && record.record_role !== "general" && (
+            <Pill label="Role" value={formatRecordRole(record.record_role)} />
+          )}
           {record.project && <Pill label="Project" value={formatScopeLabel(record.project)} />}
           <Pill label="Status" value={record.status || "unknown"} />
         </div>
@@ -47,6 +51,20 @@ export default function RecordEditor({ record }: RecordEditorProps) {
           </div>
         </div>
 
+        {rolePayload.length > 0 && (
+          <div>
+            <p className="mb-1.5 text-xs font-medium text-[var(--text-secondary)]">Role Payload</p>
+            <div className="space-y-2 rounded-md border border-[var(--border)] bg-[var(--bg-card)] px-3 py-2">
+              {rolePayload.map(([key, value]) => (
+                <div key={key} className="grid gap-1 text-sm sm:grid-cols-[130px_minmax(0,1fr)]">
+                  <span className="text-xs font-medium text-[var(--text-muted)]">{humanizeToken(key)}</span>
+                  <span className="whitespace-pre-wrap break-words text-[var(--text)]">{value}</span>
+                </div>
+              ))}
+            </div>
+          </div>
+        )}
+
         <div className="grid gap-3 sm:grid-cols-2">
           <Field label="Created" value={record.created_at || "unknown"} />
           <Field label="Updated" value={record.updated_at || "unknown"} />
@@ -56,6 +74,24 @@ export default function RecordEditor({ record }: RecordEditorProps) {
   );
 }
 
+function parseRolePayload(payload?: string | null): Array<[string, string]> {
+  const text = payload?.trim();
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return [["payload", text]];
+    return Object.entries(parsed).map(([key, value]) => [key, renderPayloadValue(value)]);
+  } catch {
+    return [["payload", text]];
+  }
+}
+
+function renderPayloadValue(value: unknown): string {
+  if (Array.isArray(value)) return value.map(renderPayloadValue).join("\n");
+  if (value && typeof value === "object") return JSON.stringify(value, null, 2);
+  return String(value ?? "");
+}
+
 function Field({ label, value }: { label: string; value: string }) {
   return (
     <div>
diff --git a/dashboard/components/Sidebar.tsx b/dashboard/components/Sidebar.tsx
index a120d12d..b0c8460b 100644
--- a/dashboard/components/Sidebar.tsx
+++ b/dashboard/components/Sidebar.tsx
@@ -9,6 +9,7 @@ const NAV_ITEMS = [
 	{ href: "/memory", label: "Briefs", icon: MemoryIcon },
 	{ href: "/context", label: "Records", icon: BrainIcon },
 	{ href: "/context-graph", label: "Graph", icon: PipelineIcon },
+	{ href: "/skills", label: "Skills", icon: SkillsIcon },
 	{ href: "/operations", label: "Operations", mobileLabel: "Ops", icon: LogsIcon },
 	{ href: "/traces", label: "Sources", mobileLabel: "Sources", icon: TableIcon, secondary: true },
 ];
@@ -114,7 +115,7 @@ export default function Sidebar({
 					</Link>
 				</div>
 			</aside>
-			<nav aria-label="Mobile primary" className="fixed inset-x-0 bottom-0 z-40 grid grid-cols-4 gap-1 border-t border-[var(--border)] bg-[rgba(17,24,39,0.96)] px-1 pb-[calc(env(safe-area-inset-bottom)+0.5rem)] pt-2 backdrop-blur min-[420px]:grid-cols-8 md:hidden">
+				<nav aria-label="Mobile primary" className="fixed inset-x-0 bottom-0 z-40 grid grid-cols-5 gap-1 border-t border-[var(--border)] bg-[rgba(17,24,39,0.96)] px-1 pb-[calc(env(safe-area-inset-bottom)+0.5rem)] pt-2 backdrop-blur min-[520px]:grid-cols-9 md:hidden">
 				{[...NAV_ITEMS, { href: "/settings", label: "Settings", mobileLabel: "Settings", icon: GearIcon }].map(({ href, label, mobileLabel, icon: Icon }) => {
 					const active = isActiveRoute(pathname, href);
 					return (
@@ -299,6 +300,26 @@ function PipelineIcon({ className }: { className?: string }) {
 	);
 }
 
+function SkillsIcon({ className }: { className?: string }) {
+	return (
+		<svg
+			className={className}
+			xmlns="http://www.w3.org/2000/svg"
+			viewBox="0 0 24 24"
+			fill="none"
+			stroke="currentColor"
+			strokeWidth={2}
+			strokeLinecap="round"
+			strokeLinejoin="round"
+		>
+			<path d="M4 6h16" />
+			<path d="M4 12h10" />
+			<path d="M4 18h7" />
+			<path d="m16 17 2 2 4-5" />
+		</svg>
+	);
+}
+
 function LogsIcon({ className }: { className?: string }) {
 	return (
 		<svg
diff --git a/dashboard/lib/api.ts b/dashboard/lib/api.ts
index 3481b994..3add633e 100644
--- a/dashboard/lib/api.ts
+++ b/dashboard/lib/api.ts
@@ -16,6 +16,10 @@ import type {
   Session,
   SessionDetail,
   SessionsResponse,
+  SkillProposal,
+  SkillProposalsResponse,
+  SkillTarget,
+  SkillTargetsResponse,
   StatsResponse,
   TeamInfo,
   TimelineEvent,
@@ -91,6 +95,8 @@ function normalizeRecord(row: Record<string, unknown>): ContextRecord {
     title: asNullableString(row.title),
     body: asNullableString(row.body),
     record_kind: asNullableString(row.kind),
+    record_role: asNullableString(row.record_role) || "general",
+    role_payload: asNullableString(row.role_payload),
     project,
     tags: [],
     confidence: null,
@@ -403,8 +409,10 @@ async function queryRecords(params?: Record<string, string>): Promise<RecordsRes
     body: JSON.stringify({
       entity: "records",
       mode: "list",
-      scope: "all",
+      scope: params?.project ? "project" : "all",
+      project: params?.project || undefined,
       kind: params?.record_kind || undefined,
+      record_role: params?.record_role || undefined,
       status: params?.status || undefined,
       source_session_id: params?.source_session_id || undefined,
       order_by: "updated_at",
@@ -427,8 +435,10 @@ async function queryRecordVersions(params?: Record<string, string>): Promise<Rec
     body: JSON.stringify({
       entity: "versions",
       mode: "list",
-      scope: "all",
+      scope: params?.project ? "project" : "all",
+      project: params?.project || undefined,
       kind: params?.record_kind || undefined,
+      record_role: params?.record_role || undefined,
       source_session_id: params?.source_session_id || undefined,
       order_by: "updated_at",
       limit: Number(params?.limit || 5000),
@@ -516,6 +526,7 @@ export const api = {
     const data = await queryRecords({ limit: "500" });
     return {
       types: Array.from(new Set(data.records.map((record) => record.record_kind).filter((kind): kind is string => Boolean(kind)))).sort(),
+      roles: Array.from(new Set(data.records.map((record) => record.record_role).filter((role): role is string => Boolean(role)))).sort(),
       projects: Array.from(new Set(data.records.map((record) => record.project).filter((project): project is string => Boolean(project)))).sort(),
     };
   },
@@ -531,6 +542,62 @@ export const api = {
     return found;
   },
 
+  getSkillTargets: async (): Promise<SkillTargetsResponse> => {
+    return apiFetch<SkillTargetsResponse>("/api/skills/targets");
+  },
+
+  addSkillTarget: async (body: { path: string; name?: string; description?: string; update_mode?: string }) => {
+    return apiFetch<{ target: SkillTarget }>("/api/skills/targets", {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  },
+
+  updateSkillTargetMode: async (
+    targetId: string,
+    body: { update_mode: string; auto_apply_policy?: Record<string, unknown> },
+  ) => {
+    return apiFetch<{ target: SkillTarget }>(`/api/skills/targets/${encodeURIComponent(targetId)}/mode`, {
+      method: "POST",
+      body: JSON.stringify(body),
+    });
+  },
+
+  refreshSkillTarget: async (targetId: string) => {
+    return apiFetch<Record<string, unknown>>(`/api/skills/targets/${encodeURIComponent(targetId)}/refresh`, {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  },
+
+  getSkillProposals: async (params?: { target_id?: string; status?: string }): Promise<SkillProposalsResponse> => {
+    const query: Record<string, string> = {};
+    if (params?.target_id) query.target_id = params.target_id;
+    if (params?.status) query.status = params.status;
+    return apiFetch<SkillProposalsResponse>(`/api/skills/proposals${toQuery(query)}`);
+  },
+
+  applySkillProposal: async (proposalId: string) => {
+    return apiFetch<{ proposal: SkillProposal }>(`/api/skills/proposals/${encodeURIComponent(proposalId)}/apply`, {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  },
+
+  rejectSkillProposal: async (proposalId: string) => {
+    return apiFetch<{ proposal: SkillProposal }>(`/api/skills/proposals/${encodeURIComponent(proposalId)}/reject`, {
+      method: "POST",
+      body: JSON.stringify({}),
+    });
+  },
+
+  editSkillProposal: async (proposalId: string, patchJson: Record<string, unknown>) => {
+    return apiFetch<{ proposal: SkillProposal }>(`/api/skills/proposals/${encodeURIComponent(proposalId)}/edit`, {
+      method: "POST",
+      body: JSON.stringify({ patch_json: patchJson }),
+    });
+  },
+
   getLogs: async (_params?: Record<string, string>): Promise<LogsResponse> => ({ logs: [], total: 0 }),
 
   getPipelineStatus: async () => {
diff --git a/dashboard/lib/labels.ts b/dashboard/lib/labels.ts
index adcaa364..b1809133 100644
--- a/dashboard/lib/labels.ts
+++ b/dashboard/lib/labels.ts
@@ -7,6 +7,16 @@ const RECORD_KIND_LABELS: Record<string, string> = {
   episode: "Episode",
 };
 
+const RECORD_ROLE_LABELS: Record<string, string> = {
+  general: "General",
+  procedure: "Procedure",
+  gotcha: "Gotcha",
+  failure_mode: "Failure Mode",
+  artifact: "Artifact",
+  state_change: "State Change",
+  eval_asset: "Eval Asset",
+};
+
 const STATUS_LABELS: Record<string, string> = {
   active: "Active",
   archived: "Archived",
@@ -39,6 +49,12 @@ export function formatRecordKind(kind?: string | null): string {
   return RECORD_KIND_LABELS[trimmed] ?? humanizeToken(trimmed);
 }
 
+export function formatRecordRole(role?: string | null): string {
+  const trimmed = role?.trim();
+  if (!trimmed) return "General";
+  return RECORD_ROLE_LABELS[trimmed] ?? humanizeToken(trimmed);
+}
+
 export function formatScopeLabel(scope?: string | null): string {
   const trimmed = scope?.trim();
   return trimmed || "Unscoped";
diff --git a/dashboard/lib/types.ts b/dashboard/lib/types.ts
index dd9e949c..21786188 100644
--- a/dashboard/lib/types.ts
+++ b/dashboard/lib/types.ts
@@ -101,6 +101,8 @@ export interface ContextRecord {
   title: string | null;
   body: string | null;
   record_kind: string | null;
+  record_role: string | null;
+  role_payload: string | null;
   project: string | null;
   tags: string[];
   confidence: number | null;
@@ -146,9 +148,109 @@ export interface RecordVersionsResponse {
 
 export interface RecordFiltersResponse {
   types: string[];
+  roles: string[];
   projects: string[];
 }
 
+/* ----- Skill Stewardship --------------------------------------------- */
+
+export interface SkillTargetFile {
+  relative_path: string;
+  file_role: string;
+  size_bytes: number;
+  sha256: string;
+  text_preview?: string | null;
+  risk_surface: "low" | "medium" | "high";
+}
+
+export interface SkillAutoApplyPolicy {
+  enabled: boolean;
+  max_risk: "low" | "medium" | "high";
+  allow_entry_file_body: boolean;
+  allow_frontmatter: boolean;
+  allow_new_reference_files: boolean;
+  allow_scripts: boolean;
+  allow_assets: boolean;
+  allow_config_files: boolean;
+  max_changed_files: number;
+  max_added_lines: number;
+  require_validation: boolean;
+}
+
+export interface SkillManifest {
+  target_type: string;
+  entry_file: string;
+  instruction_files: string[];
+  supporting_files: string[];
+  required_frontmatter: string[];
+  known_frontmatter: string[];
+  allowed_update_surfaces: string[];
+  high_risk_surfaces: string[];
+  notes: string[];
+}
+
+export interface SkillTarget {
+  target_id: string;
+  name: string;
+  description: string | null;
+  path: string;
+  target_type: string;
+  entry_file: string;
+  scope_type: string;
+  scope_id: string | null;
+  update_mode: "review" | "auto_apply" | "paused";
+  auto_apply_policy: SkillAutoApplyPolicy;
+  status: string;
+  manifest: SkillManifest | null;
+  created_at: string | null;
+  updated_at: string | null;
+  file_count?: number;
+  files?: SkillTargetFile[];
+}
+
+export interface SkillPatch {
+  relative_path: string;
+  change_type: "modify" | "create";
+  risk: "low" | "medium" | "high";
+  rationale: string;
+  evidence_record_ids: string[];
+  before_text?: string | null;
+  after_text: string;
+  diff_text: string;
+}
+
+export interface SkillProposalPatchJson {
+  title: string;
+  summary: string;
+  risk_level: "low" | "medium" | "high";
+  signals: Array<Record<string, unknown>>;
+  patches: SkillPatch[];
+  auto_apply_eligible: boolean;
+}
+
+export interface SkillProposal {
+  proposal_id: string;
+  target_id: string;
+  title: string;
+  summary: string;
+  risk_level: "low" | "medium" | "high";
+  status: string;
+  patch_json: SkillProposalPatchJson;
+  validation_json: { ok?: boolean; checks?: string[]; errors?: string[] };
+  guard_json: { accepted?: boolean; reasons?: string[]; auto_apply_eligible?: boolean; risk_level?: string };
+  auto_apply_eligible: boolean;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface SkillTargetsResponse {
+  targets: SkillTarget[];
+}
+
+export interface SkillProposalsResponse {
+  proposals: SkillProposal[];
+}
+
 /* ----- Logs --------------------------------------------------------- */
 
 export interface LogEntry {
@@ -293,6 +395,8 @@ export interface GraphNode {
   confidence?: number | null;
   status?: string;
   record_kind?: string;
+  record_role?: string;
+  role_payload?: string | null;
   project?: string;
   tags?: string[];
   body?: string;
diff --git a/src/lerim/agents/context_answerer/pipeline.py b/src/lerim/agents/context_answerer/pipeline.py
index 6be41362..84c73f36 100644
--- a/src/lerim/agents/context_answerer/pipeline.py
+++ b/src/lerim/agents/context_answerer/pipeline.py
@@ -16,6 +16,7 @@
 from lerim.agents.model_runtime import ModelRuntime, build_model_runtime
 from lerim.config.settings import Config
 from lerim.context import ContextStore, ProjectIdentity
+from lerim.context.roles import ALLOWED_RECORD_ROLES, normalize_record_role
 from lerim.context.spec import (
     ALLOWED_KINDS,
     ALLOWED_STATUSES,
@@ -253,6 +254,7 @@ def execute_count(
         mode="count",
         project_ids=project_ids,
         kind=record_kind(action),
+        record_role=record_role(action),
         status=record_status(action),
         source_session_id=text(action.get("source_session_id")),
         created_since=text(action.get("created_since")),
@@ -277,6 +279,7 @@ def execute_list(
         mode="list",
         project_ids=project_ids,
         kind=record_kind(action),
+        record_role=record_role(action),
         status=record_status(action),
         source_session_id=text(action.get("source_session_id")),
         created_since=text(action.get("created_since")),
@@ -310,6 +313,7 @@ def execute_search(
         project_ids=project_ids,
         query=query,
         kind_filters=[kind] if (kind := record_kind(action)) else None,
+        role_filters=[role] if (role := record_role(action)) else None,
         statuses=[status] if (status := record_status(action)) else None,
         valid_at=text(action.get("valid_at")),
         include_archived=bool(action.get("include_archived") or action.get("valid_at")),
@@ -324,6 +328,8 @@ def execute_search(
                 "record_id": hit.record_id,
                 "project_id": hit.project_id,
                 "kind": hit.kind,
+                "record_role": hit.record_role,
+                "role_payload": hit.role_payload,
                 "title": hit.title,
                 "body": hit.body,
                 "decision": hit.decision,
@@ -354,6 +360,8 @@ def record_for_answer(row: dict[str, Any]) -> dict[str, Any]:
         "scope_type": row.get("scope_type"),
         "scope_id": row.get("scope_id"),
         "kind": row.get("kind"),
+        "record_role": row.get("record_role"),
+        "role_payload": row.get("role_payload"),
         "title": row.get("title"),
         "body": row.get("body"),
         "decision": row.get("decision"),
@@ -379,6 +387,17 @@ def record_kind(action: dict[str, Any]) -> str | None:
     return raw
 
 
+def record_role(action: dict[str, Any]) -> str | None:
+    """Return a canonical operational role filter."""
+    raw = str(action.get("record_role") or "").strip()
+    if not raw:
+        return None
+    role = normalize_record_role(raw)
+    if role not in ALLOWED_RECORD_ROLES:
+        raise ValueError(f"invalid_answer_record_role:{role}")
+    return role
+
+
 def record_status(action: dict[str, Any]) -> str | None:
     """Return a canonical status filter."""
     raw = normalize_record_status(action.get("status"), default="")
diff --git a/src/lerim/agents/context_answerer/schemas.py b/src/lerim/agents/context_answerer/schemas.py
index a798403b..9d4a9c7a 100644
--- a/src/lerim/agents/context_answerer/schemas.py
+++ b/src/lerim/agents/context_answerer/schemas.py
@@ -9,6 +9,15 @@
 
 ContextRetrievalActionType = Literal["count", "list", "search"]
 ContextRecordKind = Literal["decision", "preference", "constraint", "fact", "episode"]
+ContextRecordRole = Literal[
+    "general",
+    "procedure",
+    "gotcha",
+    "failure_mode",
+    "artifact",
+    "state_change",
+    "eval_asset",
+]
 
 
 class ContextRetrievalAction(BaseModel):
@@ -17,6 +26,7 @@ class ContextRetrievalAction(BaseModel):
     action_type: ContextRetrievalActionType
     query: str | None = None
     kind: ContextRecordKind | None = None
+    record_role: ContextRecordRole | None = None
     status: str | None = None
     source_session_id: str | None = None
     created_since: str | None = None
diff --git a/src/lerim/agents/context_answerer/signatures.py b/src/lerim/agents/context_answerer/signatures.py
index 4292263a..21f95b20 100644
--- a/src/lerim/agents/context_answerer/signatures.py
+++ b/src/lerim/agents/context_answerer/signatures.py
@@ -25,6 +25,10 @@ class PlanContextRetrieval(dspy.Signature):
     Use null when the question does not explicitly ask for one of those exact record kinds.
     Provider, setting, mechanism, requirement, state, source-of-truth, policy, and workflow words are topical words, not record-kind filters. Use kind null for them unless the user explicitly asks for a decision, preference, constraint, fact, or episode record.
 
+    Valid operational role filters:
+    - general, procedure, gotcha, failure_mode, artifact, state_change, eval_asset.
+    Use record_role only when the question explicitly asks for reusable procedures, gotchas, failure modes, artifacts, state changes, or eval assets.
+
     Planning rules:
     - Use count for "how many" questions.
     - Count questions should count current active records by default. Include archived records only when the user explicitly asks for archived, historical, previous, before, superseded, inactive, or all records.
diff --git a/src/lerim/agents/context_brief/pipeline.py b/src/lerim/agents/context_brief/pipeline.py
index 386fc9c5..ac5f2f96 100644
--- a/src/lerim/agents/context_brief/pipeline.py
+++ b/src/lerim/agents/context_brief/pipeline.py
@@ -68,6 +68,8 @@ def candidate_for_prompt(record: dict[str, Any]) -> dict[str, Any]:
     return {
         "record_id": record.get("record_id"),
         "kind": record.get("kind"),
+        "record_role": record.get("record_role"),
+        "role_payload": record.get("role_payload"),
         "title": record.get("title"),
         "body": record.get("body"),
         "decision": record.get("decision"),
@@ -82,15 +84,20 @@ def candidate_for_prompt(record: dict[str, Any]) -> dict[str, Any]:
 def candidate_profile(records: list[dict[str, Any]]) -> dict[str, Any]:
     """Return compact metadata that frames what the records can support."""
     kind_counts: dict[str, int] = {}
+    role_counts: dict[str, int] = {}
     record_ids_by_kind: dict[str, list[str]] = {}
+    record_ids_by_role: dict[str, list[str]] = {}
     newest_updated_at = ""
     newest_episode_updated_at = ""
     for record in records:
         kind = str(record.get("kind") or "unknown")
+        role = str(record.get("record_role") or "general")
         kind_counts[kind] = kind_counts.get(kind, 0) + 1
+        role_counts[role] = role_counts.get(role, 0) + 1
         record_id = str(record.get("record_id") or "")
         if record_id:
             record_ids_by_kind.setdefault(kind, []).append(record_id)
+            record_ids_by_role.setdefault(role, []).append(record_id)
         updated_at = str(record.get("updated_at") or "")
         newest_updated_at = max(newest_updated_at, updated_at)
         if kind == "episode":
@@ -99,7 +106,9 @@ def candidate_profile(records: list[dict[str, Any]]) -> dict[str, Any]:
     return {
         "candidate_count": len(records),
         "kind_counts": kind_counts,
+        "role_counts": role_counts,
         "record_ids_by_kind": record_ids_by_kind,
+        "record_ids_by_role": record_ids_by_role,
         "newest_updated_at": newest_updated_at or None,
         "newest_episode_updated_at": newest_episode_updated_at or None,
         "has_recent_flow_evidence": bool(episode_record_ids),
@@ -140,6 +149,7 @@ def draft_from_output(output: Any) -> ContextBriefDraft:
         constraints_preferences=memory_lines(
             payload.get("constraints_preferences") or []
         ),
+        operational_context=memory_lines(payload.get("operational_context") or []),
         project_facts=memory_lines(payload.get("project_facts") or []),
         open_risks=memory_lines(payload.get("open_risks") or []),
         follow_up_queries=memory_lines(payload.get("follow_up_queries") or []),
diff --git a/src/lerim/agents/context_brief/schemas.py b/src/lerim/agents/context_brief/schemas.py
index 587817be..bc0c3260 100644
--- a/src/lerim/agents/context_brief/schemas.py
+++ b/src/lerim/agents/context_brief/schemas.py
@@ -28,6 +28,10 @@ class ContextBriefDraftOutput(BaseModel):
         default_factory=list,
         description="Only cite candidate records whose kind is preference or constraint.",
     )
+    operational_context: list[ContextBriefLineDraft] = Field(
+        default_factory=list,
+        description="Reusable procedures, gotchas, failure modes, artifacts, state changes, and eval assets.",
+    )
     project_facts: list[ContextBriefLineDraft] = Field(
         default_factory=list,
         description="Only cite candidate records whose kind is fact.",
diff --git a/src/lerim/agents/context_brief/signatures.py b/src/lerim/agents/context_brief/signatures.py
index 0eb44d44..e808e699 100644
--- a/src/lerim/agents/context_brief/signatures.py
+++ b/src/lerim/agents/context_brief/signatures.py
@@ -13,7 +13,7 @@ class CompileContextBrief(dspy.Signature):
 
     Rules:
     - Use only the supplied candidate records.
-    - Produce the fixed fields: summary, start_here, current_handoff, decisions, constraints_preferences, project_facts, open_risks, follow_up_queries.
+    - Produce the fixed fields: summary, start_here, current_handoff, decisions, constraints_preferences, operational_context, project_facts, open_risks, follow_up_queries.
     - Every field must be a list of objects with text and record_ids.
     - Every non-empty line must include at least one exact record_id copied from the candidate records.
     - Put record IDs only in record_ids, never in text.
@@ -24,13 +24,15 @@ class CompileContextBrief(dspy.Signature):
     - Prefer final decisions, preferences, constraints, and stable facts over episode detail.
     - When a decision record has decision/why fields, write the current final decision plus why/how it should shape future work.
     - Respect source kinds exactly: decisions may cite only decision records; constraints_preferences may cite only preference or constraint records; project_facts may cite only fact records.
+    - Put procedure, gotcha, failure_mode, artifact, state_change, and eval_asset role records in operational_context when they are highly useful at startup.
+    - operational_context may cite any record kind, but only when the record_role is not general or the body directly describes reusable operational context.
     - Leave a section empty when there are no candidate records for that section's allowed kinds.
     - Do not place a fact, constraint, or preference in decisions just because it sounds important or rule-like.
     - Do not duplicate the same point in multiple detail sections. Choose the one section that matches the cited record kind.
     - Do not invent current workspace state beyond stored records.
     - Do not repeat the same memory across fields.
     - Select, do not enumerate. Leave out true-but-low-leverage records.
-    - Maximum lines: summary 2, start_here 4, current_handoff 4, decisions 8, constraints_preferences 8, project_facts 6, open_risks 4, follow_up_queries 3.
+    - Maximum lines: summary 2, start_here 4, current_handoff 4, decisions 8, constraints_preferences 8, operational_context 6, project_facts 6, open_risks 4, follow_up_queries 3.
     - The ideal output is useful in under 60 seconds at agent startup.
     """
 
diff --git a/src/lerim/agents/trace_ingestion/persistence.py b/src/lerim/agents/trace_ingestion/persistence.py
index 980895e2..7486e783 100644
--- a/src/lerim/agents/trace_ingestion/persistence.py
+++ b/src/lerim/agents/trace_ingestion/persistence.py
@@ -12,6 +12,7 @@
 from lerim.context import ContextStore, ProjectIdentity, ScopeIdentity
 from lerim.context.spec import (
     DURABLE_RECORD_KINDS,
+    DEFAULT_RECORD_ROLE,
     MAX_DURABLE_BODY_CHARS,
     MAX_EPISODE_BODY_CHARS,
     MAX_EPISODE_OUTCOMES_CHARS,
@@ -375,6 +376,8 @@ def _prepare_durable_record(value: Any) -> dict[str, Any] | None:
     evidence_refs = _reference_list(record.get("evidence_refs"))
     return {
         "kind": kind,
+        "record_role": _enum_text(record.get("record_role")) or DEFAULT_RECORD_ROLE,
+        "role_payload": record.get("role_payload"),
         "title": title,
         "body": body,
         "status": _status_value(record.get("status")) or "active",
diff --git a/src/lerim/agents/trace_ingestion/pipeline.py b/src/lerim/agents/trace_ingestion/pipeline.py
index 8741607e..450ce867 100644
--- a/src/lerim/agents/trace_ingestion/pipeline.py
+++ b/src/lerim/agents/trace_ingestion/pipeline.py
@@ -19,6 +19,7 @@
     persist_synthesized_extraction,
 )
 from lerim.agents.trace_ingestion.signatures import (
+    AnnotateOperationalRecordRoles,
     ExtractCodingProjectIdentitySlot,
     ExtractCodingStrategySlots,
     FilterDurableSignal,
@@ -123,6 +124,9 @@ def __init__(
         self.coding_polish_step = configured_steps.get("coding_polish") or dspy.Predict(
             PolishCodingEvalContextRecords
         )
+        self.role_annotation_step = configured_steps.get("role_annotation") or dspy.Predict(
+            AnnotateOperationalRecordRoles
+        )
         self.uses_real_model = any(
             configured_steps.get(name) is None
             for name in (
@@ -135,6 +139,7 @@ def __init__(
                 "project_identity",
                 "retention",
                 "coding_polish",
+                "role_annotation",
             )
         )
 
@@ -162,6 +167,7 @@ def forward(self) -> dict[str, Any]:
         self.synthesize_records(state)
         self.guard_records(state)
         self.polish_records(state)
+        self.annotate_record_roles(state)
         self.persist_records(state)
         return state
 
@@ -652,6 +658,63 @@ def apply_coding_retention(
             ), retention_observations
         return payload, []
 
+    def annotate_record_roles(self, state: dict[str, Any]) -> None:
+        """Annotate accepted durable records with operational roles."""
+        payload = dict(state.get("synthesized") or {})
+        records = list(payload.get("durable_records") or [])
+        if not records:
+            return
+        self.require_budget(state)
+        if self.progress:
+            print(
+                f"  trace-ingestion role_annotation {int(state['llm_calls']) + 1}/{self.max_model_steps}",
+                flush=True,
+            )
+        with self.model_context():
+            result, observations, attempts = call_model_step(
+                lambda: self.role_annotation_step(
+                    run_instruction=self.run_instruction,
+                    source_profile_context=self.source_profile_context,
+                    durable_findings_summary=_filtered_durable_findings_summary(state),
+                    implementation_summary=_implementation_summary(state),
+                    rejected_findings_summary=_rejected_durable_findings_summary(state),
+                    durable_records_json=json.dumps(records, ensure_ascii=True),
+                ),
+                stage="annotate_record_roles",
+                progress=self.progress,
+                progress_label="trace-ingestion",
+            )
+        state["llm_calls"] += attempts
+        annotations = role_annotations_by_index(
+            prediction_payload(result, output_field="roles"),
+            record_count=len(records),
+        )
+        annotated_records: list[dict[str, Any]] = []
+        role_counts: dict[str, int] = {}
+        for index, record in enumerate(records):
+            annotation = annotations.get(index) or {}
+            role = str(annotation.get("record_role") or record.get("record_role") or "general")
+            role_counts[role] = role_counts.get(role, 0) + 1
+            annotated_records.append(
+                {
+                    **record,
+                    "record_role": role,
+                    "role_payload": annotation.get("role_payload") or record.get("role_payload"),
+                }
+            )
+        state["synthesized"] = {**payload, "durable_records": annotated_records}
+        state["observations"].extend(
+            [
+                *observations,
+                observation(
+                    "annotate_record_roles",
+                    True,
+                    role_count_summary(role_counts),
+                    {"role_counts": role_counts},
+                ),
+            ]
+        )
+
     def persist_records(self, state: dict[str, Any]) -> None:
         """Persist synthesized records and finish the workflow."""
         observations, done, completion_summary = persist_synthesized_extraction(
@@ -687,3 +750,36 @@ def observation(
         "done": False,
         "completion_summary": "",
     }
+
+
+def role_annotations_by_index(
+    payload: dict[str, Any],
+    *,
+    record_count: int,
+) -> dict[int, dict[str, Any]]:
+    """Return validated role annotations keyed by durable-record index."""
+    annotations: dict[int, dict[str, Any]] = {}
+    for value in payload.get("annotations") or []:
+        annotation = prediction_payload(value)
+        index = annotation.get("record_index")
+        if not isinstance(index, int) or index < 0 or index >= record_count:
+            continue
+        role = str(annotation.get("record_role") or "").strip()
+        if not role:
+            continue
+        annotations[index] = {
+            "record_role": role,
+            "role_payload": annotation.get("role_payload"),
+        }
+    return annotations
+
+
+def role_count_summary(role_counts: dict[str, int]) -> str:
+    """Return a compact role-count summary for ingestion observations."""
+    if not role_counts:
+        return "roles=none"
+    parts = [
+        f"{role}={count}"
+        for role, count in sorted(role_counts.items(), key=lambda item: item[0])
+    ]
+    return "roles " + " ".join(parts)
diff --git a/src/lerim/agents/trace_ingestion/schemas.py b/src/lerim/agents/trace_ingestion/schemas.py
index 579b755a..2b1d87d1 100644
--- a/src/lerim/agents/trace_ingestion/schemas.py
+++ b/src/lerim/agents/trace_ingestion/schemas.py
@@ -2,13 +2,22 @@
 
 from __future__ import annotations
 
-from typing import Literal
+from typing import Any, Literal
 
 from pydantic import BaseModel, Field
 
 
 RecordKind = Literal["decision", "preference", "constraint", "fact"]
 RecordStatus = Literal["active", "archived"]
+RecordRole = Literal[
+    "general",
+    "procedure",
+    "gotcha",
+    "failure_mode",
+    "artifact",
+    "state_change",
+    "eval_asset",
+]
 
 
 class DurableFinding(BaseModel):
@@ -19,6 +28,7 @@ class DurableFinding(BaseModel):
     line: int | None = None
     quote: str | None = None
     note: str
+    record_role: RecordRole | None = None
 
 
 class ImplementationFinding(BaseModel):
@@ -71,6 +81,8 @@ class DurableRecordDraft(BaseModel):
     why: str | None = None
     alternatives: str | None = None
     consequences: str | None = None
+    record_role: RecordRole | None = None
+    role_payload: dict[str, Any] | None = None
     source_event_refs: list[str]
     evidence_refs: list[str]
 
@@ -85,10 +97,27 @@ class FixedKindRecordDraft(BaseModel):
     why: str | None = None
     alternatives: str | None = None
     consequences: str | None = None
+    record_role: RecordRole | None = None
+    role_payload: dict[str, Any] | None = None
     source_event_refs: list[str]
     evidence_refs: list[str]
 
 
+class RecordRoleAnnotation(BaseModel):
+    """Operational role annotation for one accepted durable record."""
+
+    record_index: int
+    record_role: RecordRole
+    role_payload: dict[str, Any] | None = None
+    rationale: str | None = None
+
+
+class RecordRoleAnnotationResult(BaseModel):
+    """Operational role annotations for accepted durable records."""
+
+    annotations: list[RecordRoleAnnotation] = Field(default_factory=list)
+
+
 class SynthesizedContextRecords(BaseModel):
     """Synthesized episode and durable records."""
 
diff --git a/src/lerim/agents/trace_ingestion/signatures.py b/src/lerim/agents/trace_ingestion/signatures.py
index 0ece1b33..899d6c1a 100644
--- a/src/lerim/agents/trace_ingestion/signatures.py
+++ b/src/lerim/agents/trace_ingestion/signatures.py
@@ -9,12 +9,48 @@
     CodingProjectIdentitySlotRecords,
     CodingRecordRetentionResult,
     CodingStrategySlotRecords,
+    RecordRoleAnnotationResult,
     SignalFilterResult,
     SourceWindowScan,
     SynthesizedContextRecords,
 )
 
 
+ROLE_ANNOTATION_INSTRUCTIONS = """
+You are Lerim's operational-role annotator. Classify already-accepted durable
+records by how future agents can use them. Return only structured output. Do
+not include <think> tags, hidden reasoning, markdown, or prose.
+
+Important:
+- Do not create, remove, rewrite, or re-rank records.
+- Annotate only records that clearly fit an operational role.
+- Use general when no specialized role is directly supported.
+- Roles are not record kinds. A decision, constraint, preference, or fact can
+  have any role when the source-supported future use matches.
+- Keep payload fields compact and evidence-backed.
+
+Valid roles:
+- general: ordinary durable context.
+- procedure: reusable way to perform a workflow.
+- gotcha: surprising trap, caveat, or thing to avoid.
+- failure_mode: failure cause plus correction or prevention.
+- artifact: important file, doc, command, endpoint, model, dataset, or output.
+- state_change: project moved from an old state to a new state.
+- eval_asset: reusable regression, assertion, fixture idea, or evaluator lesson.
+
+Payload keys by role:
+- procedure: trigger, steps, checks, failure_cases.
+- gotcha: condition, symptom, avoid, recover.
+- failure_mode: failure_step, wrong_assumption, correction, prevention_check.
+- artifact: artifact_type, locator, purpose, status.
+- state_change: subject, previous_state, current_state, applies_until.
+- eval_asset: failure_pattern, assertion, fixture_hint, evaluator_hint.
+
+Return one annotation for every durable record index. Use role_payload null for
+general or when the specialized role has no compact structured fields.
+"""
+
+
 def signature(inputs: list[str], output_name: str, output_type: type, instructions: str):
     """Create a typed DSPy signature from explicit fields and instructions."""
     fields = {name: (str, dspy.InputField(desc=name.replace("_", " "))) for name in inputs}
@@ -116,6 +152,20 @@ def signature(inputs: list[str], output_name: str, output_type: type, instructio
     instructions=OBSERVE_SOURCE_WINDOW_INSTRUCTIONS,
 )
 
+AnnotateOperationalRecordRoles = signature(
+    inputs=[
+        "run_instruction",
+        "source_profile_context",
+        "durable_findings_summary",
+        "implementation_summary",
+        "rejected_findings_summary",
+        "durable_records_json",
+    ],
+    output_name="roles",
+    output_type=RecordRoleAnnotationResult,
+    instructions=ROLE_ANNOTATION_INSTRUCTIONS,
+)
+
 FILTER_DURABLE_SIGNAL_INSTRUCTIONS = """
 You are Lerim's durable-signal filter.
 Return only structured output. Do not include <think> tags, hidden reasoning, markdown, or prose.
diff --git a/src/lerim/agents/working_memory/pipeline.py b/src/lerim/agents/working_memory/pipeline.py
index 80087b54..bc9a3147 100644
--- a/src/lerim/agents/working_memory/pipeline.py
+++ b/src/lerim/agents/working_memory/pipeline.py
@@ -218,6 +218,8 @@ def record_payload(record: dict[str, Any]) -> dict[str, Any]:
     return {
         "record_id": record.get("record_id"),
         "kind": record.get("kind"),
+        "record_role": record.get("record_role"),
+        "role_payload": record.get("role_payload"),
         "status": record.get("status"),
         "title": record.get("title"),
         "body": record.get("body"),
@@ -244,6 +246,7 @@ def recent_changes_payload(data: WorkingMemoryData) -> list[dict[str, Any]]:
             {
                 "record_id": record_id,
                 "kind": version.get("kind") or record.get("kind"),
+                "record_role": version.get("record_role") or record.get("record_role"),
                 "change_kind": version.get("change_kind"),
                 "changed_at": version.get("changed_at"),
                 "title": record.get("title"),
@@ -461,8 +464,10 @@ def append_sources(
             continue
         title = compact_text(record.get("title"), limit=100)
         kind = str(record.get("kind") or "record")
+        role = str(record.get("record_role") or "general")
+        role_text = f", role {role}" if role and role != "general" else ""
         updated_at = str(record.get("updated_at") or "")
-        lines.append(f"- `{record_id}` ({kind}, updated `{updated_at}`): {title}")
+        lines.append(f"- `{record_id}` ({kind}{role_text}, updated `{updated_at}`): {title}")
     if len(cited_record_ids) > WORKING_MEMORY_RECORD_LIMIT:
         remaining = len(cited_record_ids) - WORKING_MEMORY_RECORD_LIMIT
         lines.append(f"- {remaining} more cited record(s); run `lerim query versions list --scope project --json` for deeper detail.")
diff --git a/src/lerim/agents/working_memory/signatures.py b/src/lerim/agents/working_memory/signatures.py
index 075e3ddb..1c9d6e2a 100644
--- a/src/lerim/agents/working_memory/signatures.py
+++ b/src/lerim/agents/working_memory/signatures.py
@@ -20,6 +20,7 @@ class CompileWorkingMemory(dspy.Signature):
     - Every non-empty line must include at least one exact record_id copied from the supplied records.
     - Put record IDs only in record_ids, never in text.
     - Prefer current active records over superseded or archived records.
+    - When recent records have operational roles such as procedure, gotcha, failure_mode, artifact, state_change, or eval_asset, include the role's practical implication in recent_changes or current_context when it affects continuation.
     - When a record was superseded, explain the current replacement rather than repeating the old record as truth.
     - Put the most useful resume point in start_here. If there is no clear resume point, leave start_here empty.
     - Include open_questions only when a recent record explicitly supports an unresolved question.
diff --git a/src/lerim/context/__init__.py b/src/lerim/context/__init__.py
index 5d191332..fe69acdf 100644
--- a/src/lerim/context/__init__.py
+++ b/src/lerim/context/__init__.py
@@ -12,9 +12,20 @@
     resolve_scope_identity,
     scope_from_project,
 )
+from lerim.context.roles import (
+    ALLOWED_RECORD_ROLES,
+    DEFAULT_RECORD_ROLE,
+    MAX_ROLE_PAYLOAD_CHARS,
+    ROLE_PAYLOAD_KEYS,
+    RecordRole,
+    normalize_record_role,
+    normalize_role_payload,
+    role_payload_search_text,
+)
 from lerim.context.spec import (
     ALLOWED_CHANGE_KINDS,
     ALLOWED_KINDS,
+    ALLOWED_ROLES,
     ALLOWED_STATUSES,
     DURABLE_RECORD_KINDS,
     MAX_DURABLE_BODY_CHARS,
@@ -65,6 +76,8 @@ def __dir__() -> list[str]:
 __all__ = [
     "ALLOWED_CHANGE_KINDS",
     "ALLOWED_KINDS",
+    "ALLOWED_RECORD_ROLES",
+    "ALLOWED_ROLES",
     "ALLOWED_STATUSES",
     "ALLOWED_SCOPE_TYPES",
     "ContextStore",
@@ -78,10 +91,13 @@ def __dir__() -> list[str]:
     "MAX_EPISODE_USER_INTENT_CHARS",
     "MAX_EPISODE_WHAT_HAPPENED_CHARS",
     "MAX_RECORD_TITLE_CHARS",
+    "MAX_ROLE_PAYLOAD_CHARS",
     "ProjectIdentity",
+    "ROLE_PAYLOAD_KEYS",
     "RECORD_KIND_SPECS",
     "RecordChangeKind",
     "RecordKind",
+    "RecordRole",
     "RecordStatus",
     "ScopeIdentity",
     "clear_embedding_provider_cache",
@@ -89,10 +105,13 @@ def __dir__() -> list[str]:
     "get_embedding_provider",
     "normalize_record_kind",
     "normalize_record_payload",
+    "normalize_record_role",
     "normalize_record_status",
+    "normalize_role_payload",
     "record_search_text",
     "record_validation_message",
     "resolve_project_identity",
     "resolve_scope_identity",
+    "role_payload_search_text",
     "scope_from_project",
 ]
diff --git a/src/lerim/context/retrieval.py b/src/lerim/context/retrieval.py
index 9fe89503..03eaf007 100644
--- a/src/lerim/context/retrieval.py
+++ b/src/lerim/context/retrieval.py
@@ -9,6 +9,7 @@
 import sqlite_vec
 
 from lerim.config.settings import get_config
+from lerim.context.roles import DEFAULT_RECORD_ROLE
 
 RRF_K = 2
 DEFAULT_SEMANTIC_RRF_WEIGHT = 0.7
@@ -38,6 +39,8 @@ class SearchHit:
     user_intent: str | None = None
     what_happened: str | None = None
     outcomes: str | None = None
+    record_role: str = DEFAULT_RECORD_ROLE
+    role_payload: str | None = None
 
 
 def search_records(
@@ -46,6 +49,7 @@ def search_records(
     project_ids: list[str] | None,
     query: str,
     kind_filters: list[str] | None = None,
+    role_filters: list[str] | None = None,
     statuses: list[str] | None = None,
     valid_at: str | None = None,
     include_archived: bool = False,
@@ -68,6 +72,7 @@ def search_records(
             project_ids=project_ids,
             query=query,
             kind_filters=kind_filters,
+            role_filters=role_filters,
             statuses=statuses,
             valid_at=valid_at,
             include_archived=include_archived,
@@ -82,6 +87,7 @@ def search_records(
                     project_ids=project_ids,
                     query=query,
                     kind_filters=kind_filters,
+                    role_filters=role_filters,
                     statuses=statuses,
                     valid_at=valid_at,
                     include_archived=include_archived,
@@ -115,8 +121,10 @@ def search_records(
                 record_id=record_id,
                 project_id=str(row["project_id"]),
                 kind=str(row["kind"]),
+                record_role=str(row["record_role"]),
                 title=str(row["title"]),
                 body=str(row["body"]),
+                role_payload=row["role_payload"],
                 decision=row["decision"],
                 why=row["why"],
                 alternatives=row["alternatives"],
@@ -148,6 +156,7 @@ def semantic_candidates(
     valid_at: str | None,
     include_archived: bool,
     limit: int,
+    role_filters: list[str] | None = None,
     conn: sqlite3.Connection | None = None,
 ) -> list[tuple[str, float]]:
     """Return ranked semantic candidates from sqlite-vec nearest neighbors."""
@@ -156,6 +165,7 @@ def semantic_candidates(
     filter_sql, params = store._build_record_filter_sql(
         project_ids=project_ids,
         kind_filters=kind_filters,
+        role_filters=role_filters,
         statuses=statuses,
         source_session_id=None,
         created_since=None,
@@ -223,6 +233,7 @@ def lexical_candidates(
     valid_at: str | None,
     include_archived: bool,
     limit: int,
+    role_filters: list[str] | None = None,
     conn: sqlite3.Connection | None = None,
 ) -> list[tuple[str, float]]:
     """Return ranked lexical candidates from SQLite FTS."""
@@ -232,6 +243,7 @@ def lexical_candidates(
     filter_sql, params = store._build_record_filter_sql(
         project_ids=project_ids,
         kind_filters=kind_filters,
+        role_filters=role_filters,
         statuses=statuses,
         source_session_id=None,
         created_since=None,
diff --git a/src/lerim/context/roles.py b/src/lerim/context/roles.py
new file mode 100644
index 00000000..ef168843
--- /dev/null
+++ b/src/lerim/context/roles.py
@@ -0,0 +1,144 @@
+"""Operational role metadata for durable context records."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+import json
+from typing import Any
+
+
+class RecordRole(StrEnum):
+    """Operational role a context record can play for future agents."""
+
+    GENERAL = "general"
+    PROCEDURE = "procedure"
+    GOTCHA = "gotcha"
+    FAILURE_MODE = "failure_mode"
+    ARTIFACT = "artifact"
+    STATE_CHANGE = "state_change"
+    EVAL_ASSET = "eval_asset"
+
+
+ALLOWED_RECORD_ROLES = tuple(role.value for role in RecordRole)
+DEFAULT_RECORD_ROLE = RecordRole.GENERAL.value
+MAX_ROLE_PAYLOAD_CHARS = 4000
+ROLE_PAYLOAD_KEYS: dict[str, tuple[str, ...]] = {
+    RecordRole.PROCEDURE.value: ("trigger", "steps", "checks", "failure_cases"),
+    RecordRole.GOTCHA.value: ("condition", "symptom", "avoid", "recover"),
+    RecordRole.FAILURE_MODE.value: (
+        "failure_step",
+        "wrong_assumption",
+        "correction",
+        "prevention_check",
+    ),
+    RecordRole.ARTIFACT.value: ("artifact_type", "locator", "purpose", "status"),
+    RecordRole.STATE_CHANGE.value: (
+        "subject",
+        "previous_state",
+        "current_state",
+        "applies_until",
+    ),
+    RecordRole.EVAL_ASSET.value: (
+        "failure_pattern",
+        "assertion",
+        "fixture_hint",
+        "evaluator_hint",
+    ),
+}
+
+
+def normalize_record_role(value: Any) -> str:
+    """Return a canonical operational record role."""
+    text = str(value or DEFAULT_RECORD_ROLE).strip().lower().replace("-", "_")
+    if text not in ALLOWED_RECORD_ROLES:
+        raise ValueError(f"invalid_record_role:{value}")
+    return text
+
+
+def normalize_role_payload(*, role: str, value: Any) -> str | None:
+    """Normalize a role payload to compact JSON text."""
+    normalized_role = normalize_record_role(role)
+    if normalized_role == DEFAULT_RECORD_ROLE or value is None:
+        return None
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError as exc:
+            raise ValueError("invalid_role_payload_json") from exc
+    else:
+        parsed = value
+    if not isinstance(parsed, dict):
+        raise ValueError("invalid_role_payload_type")
+    allowed_keys = ROLE_PAYLOAD_KEYS.get(normalized_role, ())
+    cleaned = {
+        key: _normalize_payload_value(parsed.get(key))
+        for key in allowed_keys
+        if _normalize_payload_value(parsed.get(key)) is not None
+    }
+    if not cleaned:
+        return None
+    text = json.dumps(cleaned, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
+    if len(text) > MAX_ROLE_PAYLOAD_CHARS:
+        raise ValueError("role_payload_too_long")
+    return text
+
+
+def role_payload_search_text(role_payload: str | None) -> str:
+    """Return human-readable search text from a normalized role payload."""
+    text = str(role_payload or "").strip()
+    if not text:
+        return ""
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError:
+        return text[:MAX_ROLE_PAYLOAD_CHARS]
+    parts = _payload_search_parts(payload)
+    return "\n".join(parts)[:MAX_ROLE_PAYLOAD_CHARS]
+
+
+def _normalize_payload_value(value: Any) -> Any:
+    """Normalize one JSON-compatible payload value."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        text = " ".join(value.split())
+        return text or None
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return value
+    if isinstance(value, (list, tuple, set)):
+        cleaned = [_normalize_payload_value(item) for item in value]
+        cleaned = [item for item in cleaned if item is not None]
+        return cleaned or None
+    if isinstance(value, dict):
+        cleaned = {
+            str(key).strip(): _normalize_payload_value(item)
+            for key, item in value.items()
+            if str(key).strip()
+        }
+        cleaned = {key: item for key, item in cleaned.items() if item is not None}
+        return cleaned or None
+    text = " ".join(str(value).split())
+    return text or None
+
+
+def _payload_search_parts(value: Any, *, prefix: str = "") -> list[str]:
+    """Flatten a normalized JSON value into compact search lines."""
+    if isinstance(value, dict):
+        parts: list[str] = []
+        for key, item in value.items():
+            key_prefix = f"{prefix}.{key}" if prefix else str(key)
+            parts.extend(_payload_search_parts(item, prefix=key_prefix))
+        return parts
+    if isinstance(value, list):
+        return [
+            part
+            for index, item in enumerate(value, start=1)
+            for part in _payload_search_parts(item, prefix=f"{prefix}.{index}")
+        ]
+    text = str(value or "").strip()
+    return [f"{prefix}: {text}"] if prefix and text else []
diff --git a/src/lerim/context/spec.py b/src/lerim/context/spec.py
index 5aa1fb3a..82cd16f0 100644
--- a/src/lerim/context/spec.py
+++ b/src/lerim/context/spec.py
@@ -8,6 +8,14 @@
 import json
 from typing import Any
 
+from lerim.context.roles import (
+    ALLOWED_RECORD_ROLES,
+    DEFAULT_RECORD_ROLE,
+    normalize_record_role,
+    normalize_role_payload,
+    role_payload_search_text,
+)
+
 
 class RecordKind(StrEnum):
     """Canonical durable-context record kinds."""
@@ -38,6 +46,7 @@ class RecordChangeKind(StrEnum):
 ALLOWED_KINDS = tuple(kind.value for kind in RecordKind)
 ALLOWED_STATUSES = tuple(status.value for status in RecordStatus)
 ALLOWED_CHANGE_KINDS = tuple(change_kind.value for change_kind in RecordChangeKind)
+ALLOWED_ROLES = ALLOWED_RECORD_ROLES
 MAX_RECORD_TITLE_CHARS = 120
 MAX_EPISODE_BODY_CHARS = 1200
 MAX_DURABLE_BODY_CHARS = 850
@@ -243,6 +252,10 @@ def record_validation_message(code: str) -> str | None:
             "Durable record body is too long. Keep only the reusable "
             "rule/decision/fact and why it matters."
         ),
+        "invalid_record_role": "Record role must be one of the canonical operational roles.",
+        "invalid_role_payload_json": "Record role payload must be valid JSON.",
+        "invalid_role_payload_type": "Record role payload must be a JSON object.",
+        "role_payload_too_long": "Record role payload is too long. Keep only reusable structured fields.",
     }
     return messages.get(str(code or "").strip())
 
@@ -268,6 +281,8 @@ def normalize_record_payload(
     outcomes: Any,
     source_event_refs: Any = None,
     evidence_refs: Any = None,
+    record_role: Any = DEFAULT_RECORD_ROLE,
+    role_payload: Any = None,
 ) -> dict[str, Any]:
     """Normalize and validate one record payload against the shared spec."""
     kind_text = normalize_record_kind(kind)
@@ -276,6 +291,11 @@ def normalize_record_payload(
     status_text = normalize_record_status(status)
     if status_text not in ALLOWED_STATUSES:
         raise ValueError(f"invalid_status:{status}")
+    role_text = normalize_record_role(record_role)
+    normalized_role_payload = normalize_role_payload(
+        role=role_text,
+        value=role_payload,
+    )
     title_text = str(title or "").strip()
     body_text = str(body or "").strip()
     if not title_text:
@@ -308,6 +328,8 @@ def normalize_record_payload(
         "outcomes": _normalize_optional_text(outcomes),
         "source_event_refs": _normalize_reference_list(source_event_refs),
         "evidence_refs": _normalize_reference_list(evidence_refs),
+        "record_role": role_text,
+        "role_payload": normalized_role_payload,
     }
     if payload["status"] == "archived" and not payload["valid_until"]:
         payload["valid_until"] = payload["updated_at"]
@@ -342,10 +364,16 @@ def normalize_record_payload(
 def record_search_text(payload: dict[str, Any], *, index_text: str | None = None) -> str:
     """Build canonical search text from one normalized record payload."""
     parts: list[str] = [f"kind: {payload['kind']}"]
+    role = str(payload.get("record_role") or DEFAULT_RECORD_ROLE).strip()
+    if role:
+        parts.append(f"role: {role}")
     for field_name in SEARCH_TEXT_FIELDS:
         text = str(payload.get(field_name) or "").strip()
         if text:
             parts.append(f"{field_name}: {text}")
+    role_text = role_payload_search_text(payload.get("role_payload"))
+    if role_text:
+        parts.append(f"role_payload:\n{role_text}")
     extra = str(index_text or "").strip()
     if extra:
         parts.append(f"index_text: {extra}")
diff --git a/src/lerim/context/store.py b/src/lerim/context/store.py
index 07edc5b3..ee5075b4 100644
--- a/src/lerim/context/store.py
+++ b/src/lerim/context/store.py
@@ -31,6 +31,7 @@
 import lerim.context.retrieval as retrieval
 from lerim.context.spec import (
     ALLOWED_CHANGE_KINDS,
+    DEFAULT_RECORD_ROLE,
     normalize_record_payload,
     record_search_text,
 )
@@ -38,7 +39,7 @@
 if TYPE_CHECKING:
     from lerim.context.retrieval import SearchHit
 
-SCHEMA_VERSION = "7"
+SCHEMA_VERSION = "8"
 LOGGER = logging.getLogger(__name__)
 RECORDS_INDEX_GENERATION_KEY = "records_index_generation"
 RECORDS_FTS_GENERATION_KEY = "records_fts_generation"
@@ -254,6 +255,8 @@ def initialize(self) -> None:
                     source_name TEXT,
                     source_profile TEXT,
                     kind TEXT NOT NULL,
+                    record_role TEXT NOT NULL DEFAULT 'general',
+                    role_payload TEXT,
                     title TEXT NOT NULL,
                     body TEXT NOT NULL,
                     status TEXT NOT NULL,
@@ -292,6 +295,8 @@ def initialize(self) -> None:
                     record_id TEXT NOT NULL,
                     version_no INTEGER NOT NULL,
                     kind TEXT NOT NULL,
+                    record_role TEXT NOT NULL DEFAULT 'general',
+                    role_payload TEXT,
                     title TEXT NOT NULL,
                     body TEXT NOT NULL,
                     status TEXT NOT NULL,
@@ -373,6 +378,8 @@ def initialize(self) -> None:
                     updated_at UNINDEXED,
                     title,
                     body,
+                    record_role,
+                    role_payload,
                     decision,
                     why,
                     user_intent,
@@ -385,6 +392,7 @@ def initialize(self) -> None:
             self._migrate_scope_schema(conn)
             self._ensure_record_reference_schema(conn)
             self._ensure_record_index_text_schema(conn)
+            self._ensure_record_role_schema(conn)
             self._ensure_secondary_indexes(conn)
             self._validate_schema(conn)
             conn.execute(
@@ -459,6 +467,7 @@ def _ensure_secondary_indexes(self, conn: sqlite3.Connection) -> None:
             CREATE INDEX IF NOT EXISTS idx_records_project_id ON records(project_id);
             CREATE INDEX IF NOT EXISTS idx_records_scope ON records(scope_type, scope_id);
             CREATE INDEX IF NOT EXISTS idx_records_kind ON records(kind);
+            CREATE INDEX IF NOT EXISTS idx_records_role ON records(record_role);
             CREATE INDEX IF NOT EXISTS idx_records_status ON records(status);
             CREATE INDEX IF NOT EXISTS idx_records_created_at ON records(created_at);
             CREATE INDEX IF NOT EXISTS idx_records_updated_at ON records(updated_at);
@@ -548,9 +557,9 @@ def _refresh_existing_record_scopes(self, conn: sqlite3.Connection) -> None:
             )
 
     def _ensure_records_fts_schema(self, conn: sqlite3.Connection) -> None:
-        """Ensure the FTS table has scope columns, rebuilding from records if needed."""
+        """Ensure the FTS table has scope and role columns."""
         columns = self._table_columns(conn, "records_fts")
-        if columns and {"scope_type", "scope_id", "index_text"} <= columns:
+        if columns and {"scope_type", "scope_id", "record_role", "role_payload", "index_text"} <= columns:
             return
         conn.execute("DROP TABLE IF EXISTS records_fts")
         conn.execute(
@@ -563,6 +572,8 @@ def _ensure_records_fts_schema(self, conn: sqlite3.Connection) -> None:
                 updated_at UNINDEXED,
                 title,
                 body,
+                record_role,
+                role_payload,
                 decision,
                 why,
                 user_intent,
@@ -608,6 +619,20 @@ def _ensure_record_index_text_schema(self, conn: sqlite3.Connection) -> None:
             if "index_text" not in columns:
                 conn.execute(f"ALTER TABLE {table_name} ADD COLUMN index_text TEXT")
 
+    def _ensure_record_role_schema(self, conn: sqlite3.Connection) -> None:
+        """Add operational role columns to older record tables."""
+        for table_name in ("records", "record_versions"):
+            columns = self._table_columns(conn, table_name)
+            if not columns:
+                continue
+            if "record_role" not in columns:
+                conn.execute(
+                    f"ALTER TABLE {table_name} "
+                    "ADD COLUMN record_role TEXT NOT NULL DEFAULT 'general'"
+                )
+            if "role_payload" not in columns:
+                conn.execute(f"ALTER TABLE {table_name} ADD COLUMN role_payload TEXT")
+
     def _column_expr(self, columns: set[str], name: str, default_sql: str) -> str:
         """Return a SELECT expression for an existing column or SQL default."""
         return name if name in columns else default_sql
@@ -739,6 +764,8 @@ def _rebuild_records_table(self, conn: sqlite3.Connection) -> None:
                 source_name TEXT,
                 source_profile TEXT,
                 kind TEXT NOT NULL,
+                record_role TEXT NOT NULL DEFAULT 'general',
+                role_payload TEXT,
                 title TEXT NOT NULL,
                 body TEXT NOT NULL,
                 status TEXT NOT NULL,
@@ -775,18 +802,20 @@ def _rebuild_records_table(self, conn: sqlite3.Connection) -> None:
         source_event_refs = self._column_expr(columns, "source_event_refs", "NULL")
         evidence_refs = self._column_expr(columns, "evidence_refs", "NULL")
         index_text = self._column_expr(columns, "index_text", "NULL")
+        record_role = self._column_expr(columns, "record_role", "'general'")
+        role_payload = self._column_expr(columns, "role_payload", "NULL")
         conn.execute(
             f"""
             INSERT INTO records(
                 record_id, project_id, scope_type, scope_id, scope_label,
-                source_name, source_profile, kind, title, body, status,
+                source_name, source_profile, kind, record_role, role_payload, title, body, status,
                 source_session_id, source_event_refs, evidence_refs, index_text, created_at, updated_at, valid_from,
                 valid_until, superseded_by_record_id, decision, why,
                 alternatives, consequences, user_intent, what_happened, outcomes
             )
             SELECT
                 record_id, project_id, {scope_type}, {scope_id}, {scope_label},
-                {source_name}, {source_profile}, kind, title, body, status,
+                {source_name}, {source_profile}, kind, {record_role}, {role_payload}, title, body, status,
                 source_session_id, {source_event_refs}, {evidence_refs}, {index_text}, created_at, updated_at, valid_from,
                 valid_until, superseded_by_record_id, decision, why,
                 alternatives, consequences, user_intent, what_happened, outcomes
@@ -845,6 +874,8 @@ def _rebuild_record_versions_table(self, conn: sqlite3.Connection) -> None:
                 record_id TEXT NOT NULL,
                 version_no INTEGER NOT NULL,
                 kind TEXT NOT NULL,
+                record_role TEXT NOT NULL DEFAULT 'general',
+                role_payload TEXT,
                 title TEXT NOT NULL,
                 body TEXT NOT NULL,
                 status TEXT NOT NULL,
@@ -885,12 +916,14 @@ def _rebuild_record_versions_table(self, conn: sqlite3.Connection) -> None:
         source_event_refs = self._column_expr(columns, "source_event_refs", "NULL")
         evidence_refs = self._column_expr(columns, "evidence_refs", "NULL")
         index_text = self._column_expr(columns, "index_text", "NULL")
+        record_role = self._column_expr(columns, "record_role", "'general'")
+        role_payload = self._column_expr(columns, "role_payload", "NULL")
         conn.execute(
             f"""
             INSERT INTO record_versions(
                 version_id, project_id, scope_type, scope_id, scope_label,
                 source_name, source_profile, record_id, version_no, kind,
-                title, body, status, source_session_id, source_event_refs, evidence_refs,
+                record_role, role_payload, title, body, status, source_session_id, source_event_refs, evidence_refs,
                 index_text, created_at, updated_at,
                 valid_from, valid_until, superseded_by_record_id, decision, why,
                 alternatives, consequences, user_intent, what_happened, outcomes,
@@ -899,7 +932,7 @@ def _rebuild_record_versions_table(self, conn: sqlite3.Connection) -> None:
             SELECT
                 version_id, project_id, {scope_type}, {scope_id}, {scope_label},
                 {source_name}, {source_profile}, record_id, version_no, kind,
-                title, body, status, source_session_id, {source_event_refs}, {evidence_refs},
+                {record_role}, {role_payload}, title, body, status, source_session_id, {source_event_refs}, {evidence_refs},
                 {index_text}, created_at, updated_at,
                 valid_from, valid_until, superseded_by_record_id, decision, why,
                 alternatives, consequences, user_intent, what_happened, outcomes,
@@ -928,6 +961,8 @@ def _validate_schema(self, conn: sqlite3.Connection) -> None:
                 "scope_type",
                 "scope_id",
                 "kind",
+                "record_role",
+                "role_payload",
                 "title",
                 "body",
                 "status",
@@ -941,6 +976,8 @@ def _validate_schema(self, conn: sqlite3.Connection) -> None:
                 "scope_type",
                 "scope_id",
                 "version_no",
+                "record_role",
+                "role_payload",
                 "source_event_refs",
                 "evidence_refs",
                 "index_text",
@@ -976,6 +1013,8 @@ def _validate_schema(self, conn: sqlite3.Connection) -> None:
                 "updated_at",
                 "title",
                 "body",
+                "record_role",
+                "role_payload",
                 "decision",
                 "why",
                 "user_intent",
@@ -1142,7 +1181,7 @@ def _records_fts_metadata_fresh(self, conn: sqlite3.Connection) -> bool:
         if self._schema_meta_int(conn, RECORDS_FTS_GENERATION_KEY, default=-1) != generation:
             return False
         columns = self._table_columns(conn, "records_fts")
-        return {"record_id", "scope_type", "scope_id", "updated_at"} <= columns
+        return {"record_id", "scope_type", "scope_id", "updated_at", "record_role", "role_payload"} <= columns
 
     def _mark_records_fts_fresh(
         self, conn: sqlite3.Connection, *, generation: int | None = None
@@ -1589,6 +1628,7 @@ def fetch_record(
         filter_sql, params = self._build_record_filter_sql(
             project_ids=project_ids,
             kind_filters=None,
+            role_filters=None,
             source_profile=None,
             statuses=None,
             source_session_id=None,
@@ -1630,6 +1670,8 @@ def create_record(
         title: str,
         body: str,
         status: str = "active",
+        record_role: str | None = None,
+        role_payload: dict[str, Any] | str | None = None,
         record_id: str | None = None,
         created_at: str | None = None,
         updated_at: str | None = None,
@@ -1676,6 +1718,8 @@ def create_record(
             title=title,
             body=body,
             status=status,
+            record_role=record_role or DEFAULT_RECORD_ROLE,
+            role_payload=role_payload,
             source_session_id=session_id,
             created_at=effective_created_at,
             updated_at=effective_updated_at,
@@ -1719,12 +1763,12 @@ def create_record(
                 """
                 INSERT INTO records(
                     record_id, project_id, scope_type, scope_id, scope_label,
-                    source_name, source_profile, kind, title, body, status, source_session_id,
+                    source_name, source_profile, kind, record_role, role_payload, title, body, status, source_session_id,
                     source_event_refs, evidence_refs, index_text, created_at, updated_at,
                     valid_from, valid_until, superseded_by_record_id,
                     decision, why, alternatives, consequences, user_intent, what_happened, outcomes
                 )
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
                 """,
                 (
                     record_id,
@@ -1735,6 +1779,8 @@ def create_record(
                     payload["source_name"],
                     payload["source_profile"],
                     payload["kind"],
+                    payload["record_role"],
+                    payload["role_payload"],
                     payload["title"],
                     payload["body"],
                     payload["status"],
@@ -1834,6 +1880,8 @@ def _update_record_in_conn(
             title=changes.get("title", merged["title"]),
             body=changes.get("body", merged["body"]),
             status=changes.get("status", merged["status"]),
+            record_role=changes.get("record_role", merged["record_role"]),
+            role_payload=changes.get("role_payload", merged["role_payload"]),
             source_session_id=merged["source_session_id"],
             created_at=merged["created_at"],
             updated_at=effective_updated_at,
@@ -1868,6 +1916,8 @@ def _update_record_in_conn(
         )
         meaningful_fields = (
             "kind",
+            "record_role",
+            "role_payload",
             "title",
             "body",
             "status",
@@ -1900,7 +1950,7 @@ def _update_record_in_conn(
         conn.execute(
             """
             UPDATE records
-            SET kind=?, title=?, body=?, status=?, updated_at=?, valid_from=?,
+            SET kind=?, record_role=?, role_payload=?, title=?, body=?, status=?, updated_at=?, valid_from=?,
                 valid_until=?, superseded_by_record_id=?, decision=?, why=?,
                 alternatives=?, consequences=?, user_intent=?, what_happened=?, outcomes=?,
                 source_event_refs=?, evidence_refs=?, index_text=?
@@ -1908,6 +1958,8 @@ def _update_record_in_conn(
             """,
             (
                 payload["kind"],
+                payload["record_role"],
+                payload["role_payload"],
                 payload["title"],
                 payload["body"],
                 payload["status"],
@@ -2032,6 +2084,7 @@ def search(
         project_ids: list[str] | None,
         query: str,
         kind_filters: list[str] | None = None,
+        role_filters: list[str] | None = None,
         statuses: list[str] | None = None,
         valid_at: str | None = None,
         include_archived: bool = False,
@@ -2044,6 +2097,7 @@ def search(
             project_ids=project_ids,
             query=query,
             kind_filters=kind_filters,
+            role_filters=role_filters,
             statuses=statuses,
             valid_at=valid_at,
             include_archived=include_archived,
@@ -2093,6 +2147,8 @@ def index_health(self, *, project_ids: list[str] | None = None) -> dict[str, int
                             OR f.updated_at != r.updated_at
                             OR COALESCE(f.title, '') != COALESCE(r.title, '')
                             OR COALESCE(f.body, '') != COALESCE(r.body, '')
+                            OR COALESCE(f.record_role, '') != COALESCE(r.record_role, 'general')
+                            OR COALESCE(f.role_payload, '') != COALESCE(r.role_payload, '')
                             OR COALESCE(f.decision, '') != COALESCE(r.decision, '')
 	                       OR COALESCE(f.why, '') != COALESCE(r.why, '')
 	                       OR COALESCE(f.user_intent, '') != COALESCE(r.user_intent, '')
@@ -2187,6 +2243,7 @@ def query(
         mode: str,
         project_ids: list[str] | None = None,
         kind: str | None = None,
+        record_role: str | None = None,
         source_profile: str | None = None,
         status: str | None = None,
         source_session_id: str | None = None,
@@ -2216,6 +2273,7 @@ def query(
         unsupported_filters = self._unsupported_query_filters(
             entity_name=entity_name,
             kind=kind,
+            record_role=record_role,
             source_profile=source_profile,
             status=status,
             updated_since=updated_since,
@@ -2233,6 +2291,7 @@ def query(
                 mode=mode_name,
                 project_ids=project_ids,
                 kind=kind,
+                record_role=record_role,
                 source_profile=source_profile,
                 status=status,
                 source_session_id=source_session_id,
@@ -2252,6 +2311,7 @@ def query(
                 mode=mode_name,
                 project_ids=project_ids,
                 kind=kind,
+                record_role=record_role,
                 source_profile=source_profile,
                 status=status,
                 source_session_id=source_session_id,
@@ -2282,6 +2342,7 @@ def _unsupported_query_filters(
         *,
         entity_name: str,
         kind: str | None,
+        record_role: str | None,
         source_profile: str | None = None,
         status: str | None,
         updated_since: str | None,
@@ -2296,6 +2357,7 @@ def _unsupported_query_filters(
                 name
                 for name, value in (
                     ("kind", kind),
+                    ("record_role", record_role),
                     ("status", status),
                     ("source_profile", source_profile),
                     ("updated_since", updated_since),
@@ -2314,6 +2376,7 @@ def _query_records(
         mode: str,
         project_ids: list[str] | None,
         kind: str | None,
+        record_role: str | None,
         source_profile: str | None,
         status: str | None,
         source_session_id: str | None,
@@ -2331,6 +2394,7 @@ def _query_records(
         filter_sql, params = self._build_record_filter_sql(
             project_ids=project_ids,
             kind_filters=[kind] if kind else None,
+            role_filters=[record_role] if record_role else None,
             source_profile=source_profile,
             statuses=[status] if status else None,
             source_session_id=source_session_id,
@@ -2374,6 +2438,7 @@ def _query_versions(
         mode: str,
         project_ids: list[str] | None,
         kind: str | None,
+        record_role: str | None,
         source_profile: str | None,
         status: str | None,
         source_session_id: str | None,
@@ -2390,6 +2455,7 @@ def _query_versions(
         filter_sql, params = self._build_version_filter_sql(
             project_ids=project_ids,
             kind=kind,
+            record_role=record_role,
             source_profile=source_profile,
             status=status,
             source_session_id=source_session_id,
@@ -2502,6 +2568,8 @@ def _record_row_to_dict(self, row: sqlite3.Row) -> dict[str, Any]:
             "source_name": _row_value(row, "source_name"),
             "source_profile": _row_value(row, "source_profile"),
             "kind": str(row["kind"]),
+            "record_role": str(_row_value(row, "record_role", DEFAULT_RECORD_ROLE) or DEFAULT_RECORD_ROLE),
+            "role_payload": _row_value(row, "role_payload"),
             "title": str(row["title"]),
             "body": str(row["body"]),
             "status": str(row["status"]),
@@ -2560,6 +2628,8 @@ def _normalize_record_payload(
         outcomes: Any,
         source_event_refs: Any = None,
         evidence_refs: Any = None,
+        record_role: Any = DEFAULT_RECORD_ROLE,
+        role_payload: Any = None,
     ) -> dict[str, Any]:
         """Normalize and validate one record payload."""
         payload = normalize_record_payload(
@@ -2567,6 +2637,8 @@ def _normalize_record_payload(
             title=title,
             body=body,
             status=status,
+            record_role=record_role,
+            role_payload=role_payload,
             source_session_id=source_session_id,
             created_at=created_at,
             updated_at=updated_at,
@@ -2634,13 +2706,13 @@ def _insert_record_version(
             INSERT INTO record_versions(
                 version_id, project_id, scope_type, scope_id, scope_label,
                 source_name, source_profile, record_id, version_no, kind, title,
-                body, status, source_session_id, created_at, updated_at,
+                record_role, role_payload, body, status, source_session_id, created_at, updated_at,
                 source_event_refs, evidence_refs, index_text, valid_from, valid_until,
                 superseded_by_record_id, decision, why,
                 alternatives, consequences, user_intent, what_happened, outcomes,
                 change_kind, change_reason, changed_at, changed_by_session_id
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 _new_id("ver"),
@@ -2654,6 +2726,8 @@ def _insert_record_version(
                 version_no,
                 payload["kind"],
                 payload["title"],
+                payload["record_role"],
+                payload["role_payload"],
                 payload["body"],
                 payload["status"],
                 payload["source_session_id"],
@@ -2776,9 +2850,10 @@ def _upsert_fts(
             """
             INSERT INTO records_fts(
                 record_id, project_id, scope_type, scope_id, updated_at, title,
-                body, decision, why, user_intent, what_happened, index_text
+                body, record_role, role_payload, decision, why, user_intent,
+                what_happened, index_text
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 record_id,
@@ -2788,6 +2863,8 @@ def _upsert_fts(
                 payload["updated_at"],
                 payload["title"],
                 payload["body"],
+                payload.get("record_role") or DEFAULT_RECORD_ROLE,
+                payload.get("role_payload") or "",
                 payload["decision"] or "",
                 payload["why"] or "",
                 payload["user_intent"] or "",
@@ -2871,6 +2948,8 @@ def _ensure_records_fts_index(self, conn: sqlite3.Connection) -> bool:
                        OR f.updated_at != r.updated_at
                        OR COALESCE(f.title, '') != COALESCE(r.title, '')
                        OR COALESCE(f.body, '') != COALESCE(r.body, '')
+                       OR COALESCE(f.record_role, '') != COALESCE(r.record_role, 'general')
+                       OR COALESCE(f.role_payload, '') != COALESCE(r.role_payload, '')
                        OR COALESCE(f.decision, '') != COALESCE(r.decision, '')
                        OR COALESCE(f.why, '') != COALESCE(r.why, '')
                        OR COALESCE(f.user_intent, '') != COALESCE(r.user_intent, '')
@@ -3020,6 +3099,7 @@ def _build_record_filter_sql(
         updated_until: str | None,
         valid_at: str | None,
         include_archived: bool,
+        role_filters: list[str] | None = None,
         table_alias: str = "",
     ) -> tuple[str, list[Any]]:
         """Build reusable record filter fragments."""
@@ -3041,6 +3121,10 @@ def _build_record_filter_sql(
             placeholders = ", ".join("?" for _ in kind_filters)
             clauses.append(f"{prefix}kind IN ({placeholders})")
             params.extend(kind_filters)
+        if role_filters:
+            placeholders = ", ".join("?" for _ in role_filters)
+            clauses.append(f"{prefix}record_role IN ({placeholders})")
+            params.extend(role_filters)
         if statuses:
             placeholders = ", ".join("?" for _ in statuses)
             clauses.append(f"{prefix}status IN ({placeholders})")
@@ -3078,6 +3162,7 @@ def _build_version_filter_sql(
         *,
         project_ids: list[str] | None,
         kind: str | None,
+        record_role: str | None,
         source_profile: str | None,
         status: str | None,
         source_session_id: str | None,
@@ -3100,6 +3185,9 @@ def _build_version_filter_sql(
         if kind:
             clauses.append("kind = ?")
             params.append(kind)
+        if record_role:
+            clauses.append("record_role = ?")
+            params.append(record_role)
         if source_profile:
             clauses.append(
                 "LOWER(COALESCE(NULLIF(TRIM(source_profile), ''), 'coding')) = ?"
diff --git a/src/lerim/context_brief.py b/src/lerim/context_brief.py
index 3e6eb102..1aeac4db 100644
--- a/src/lerim/context_brief.py
+++ b/src/lerim/context_brief.py
@@ -25,6 +25,7 @@
     "current_handoff": 4,
     "decisions": 8,
     "constraints_preferences": 8,
+    "operational_context": 6,
     "project_facts": 6,
     "open_risks": 4,
     "follow_up_queries": 3,
@@ -92,6 +93,7 @@ class ContextBriefDraft:
     current_handoff: tuple[MemoryLine, ...] = ()
     decisions: tuple[MemoryLine, ...] = ()
     constraints_preferences: tuple[MemoryLine, ...] = ()
+    operational_context: tuple[MemoryLine, ...] = ()
     project_facts: tuple[MemoryLine, ...] = ()
     open_risks: tuple[MemoryLine, ...] = ()
     follow_up_queries: tuple[MemoryLine, ...] = ()
@@ -409,6 +411,7 @@ def keep_matching(section_name: str, lines: tuple[MemoryLine, ...]) -> tuple[Mem
             "constraints_preferences",
             draft.constraints_preferences,
         ),
+        operational_context=draft.operational_context,
         project_facts=keep_matching("project_facts", draft.project_facts),
         open_risks=draft.open_risks,
         follow_up_queries=draft.follow_up_queries,
@@ -434,6 +437,9 @@ def trim_context_brief_draft(draft: ContextBriefDraft) -> ContextBriefDraft:
         constraints_preferences=draft.constraints_preferences[
             : SECTION_LINE_LIMITS["constraints_preferences"]
         ],
+        operational_context=draft.operational_context[
+            : SECTION_LINE_LIMITS["operational_context"]
+        ],
         project_facts=draft.project_facts[: SECTION_LINE_LIMITS["project_facts"]],
         open_risks=draft.open_risks[: SECTION_LINE_LIMITS["open_risks"]],
         follow_up_queries=draft.follow_up_queries[
@@ -457,6 +463,7 @@ def iter_named_draft_lines(draft: ContextBriefDraft) -> tuple[tuple[str, MemoryL
         ("current_handoff", draft.current_handoff),
         ("decisions", draft.decisions),
         ("constraints_preferences", draft.constraints_preferences),
+        ("operational_context", draft.operational_context),
         ("project_facts", draft.project_facts),
         ("open_risks", draft.open_risks),
         ("follow_up_queries", draft.follow_up_queries),
@@ -576,6 +583,12 @@ def render_context_brief_markdown(
         items=draft.constraints_preferences[:12],
         seen_lines=seen_lines,
     )
+    append_memory_section(
+        lines,
+        title="Reusable Workflows & Gotchas",
+        items=draft.operational_context[:10],
+        seen_lines=seen_lines,
+    )
     append_memory_section(
         lines,
         title="Project Facts",
@@ -683,11 +696,13 @@ def format_source_reference_lines(
             continue
         title = str(record.get("title") or "Untitled").strip()
         kind = str(record.get("kind") or "record").strip()
+        role = str(record.get("record_role") or "general").strip()
+        role_text = f", role {role}" if role and role != "general" else ""
         updated_at = str(record.get("updated_at") or "").strip()
         source_session = str(record.get("source_session_id") or "").strip()
         source_text = f"; source_session: `{source_session}`" if source_session else ""
         lines.append(
-            f"- `{record_id}` ({kind}, updated `{updated_at}`): {title}{source_text}"
+            f"- `{record_id}` ({kind}{role_text}, updated `{updated_at}`): {title}{source_text}"
         )
     if len(cited_record_ids) > REFERENCE_LINE_LIMIT:
         remaining = len(cited_record_ids) - REFERENCE_LINE_LIMIT
diff --git a/src/lerim/mcp_server.py b/src/lerim/mcp_server.py
index 21b92019..e023a5a6 100644
--- a/src/lerim/mcp_server.py
+++ b/src/lerim/mcp_server.py
@@ -192,6 +192,7 @@ def lerim_context_search(
         scope: str = "all",
         project: str | None = None,
         kind: str | None = None,
+        record_role: str | None = None,
         status: str = "active",
         limit: int = 8,
     ) -> dict[str, Any]:
@@ -211,6 +212,7 @@ def _impl() -> dict[str, Any]:
                 project_ids=project_ids,
                 query=str(query),
                 kind_filters=[kind] if kind else None,
+                role_filters=[record_role] if record_role else None,
                 statuses=statuses,
                 limit=max(1, min(int(limit or 8), 50)),
             )
@@ -223,6 +225,8 @@ def _impl() -> dict[str, Any]:
                         "record_id": hit.record_id,
                         "project_id": hit.project_id,
                         "kind": hit.kind,
+                        "record_role": hit.record_role,
+                        "role_payload": hit.role_payload,
                         "title": hit.title,
                         "body": hit.body,
                         "status": hit.status,
@@ -246,6 +250,7 @@ def lerim_records_list(
         scope: str = "all",
         project: str | None = None,
         kind: str | None = None,
+        record_role: str | None = None,
         status: str | None = "active",
         source_profile: str | None = None,
         source_session_id: str | None = None,
@@ -260,6 +265,7 @@ def lerim_records_list(
                 scope=scope,
                 project=project,
                 kind=kind,
+                record_role=record_role,
                 status=status,
                 source_profile=source_profile,
                 source_session_id=source_session_id,
diff --git a/src/lerim/server/api.py b/src/lerim/server/api.py
index acad9d66..f96cc78f 100644
--- a/src/lerim/server/api.py
+++ b/src/lerim/server/api.py
@@ -57,6 +57,12 @@
 )
 from lerim.profiles import list_signal_packs
 from lerim.server.runtime import LerimRuntime
+from lerim.skill_stewardship.artifacts import artifact_name, scan_instruction_artifact
+from lerim.skill_stewardship.patching import apply_proposal
+from lerim.skill_stewardship.pipeline import guard_proposal, hydrate_patch_text, run_skill_stewardship_refresh
+from lerim.skill_stewardship.repository import SkillStewardshipRepository
+from lerim.skill_stewardship.schemas import AutoApplyPolicy, SkillProposalDraft
+from lerim.skill_stewardship.validation import validate_proposal
 from lerim.sessions.catalog import (
     count_all_session_state,
     count_fts_indexed,
@@ -455,6 +461,7 @@ def api_query(
     scope: str = "all",
     project: str | None = None,
     kind: str | None = None,
+    record_role: str | None = None,
     source_profile: str | None = None,
     status: str | None = None,
     source_session_id: str | None = None,
@@ -497,6 +504,7 @@ def api_query(
             mode=mode,
             project_ids=project_ids,
             kind=kind,
+            record_role=record_role,
             source_profile=source_profile,
             status=status,
             source_session_id=source_session_id,
@@ -532,6 +540,163 @@ def api_query(
     }
 
 
+def api_skill_target_add(
+    *,
+    path: str,
+    name: str | None = None,
+    description: str | None = None,
+    update_mode: str = "review",
+) -> dict[str, Any]:
+    """Register or refresh one instruction target from a filesystem path."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    base, manifest, files = scan_instruction_artifact(path)
+    target = repository.upsert_target(
+        name=name or artifact_name(path, manifest),
+        path=Path(path).expanduser().resolve(),
+        description=description,
+        manifest=manifest,
+        files=files,
+        update_mode=update_mode,
+    )
+    return {
+        "target": target.model_dump(),
+        "base_path": str(base),
+        "files": [item.model_dump(exclude={"text_preview"}) for item in files],
+        "error": False,
+    }
+
+
+def api_skill_targets() -> dict[str, Any]:
+    """List registered instruction targets with latest scanned files."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    targets = []
+    for target in repository.list_targets():
+        files = repository.target_files(target.target_id)
+        targets.append(
+            {
+                **target.model_dump(),
+                "file_count": len(files),
+                "files": [item.model_dump(exclude={"text_preview"}) for item in files],
+            }
+        )
+    return {"targets": targets, "error": False}
+
+
+def api_skill_target_show(target_id_or_name: str) -> dict[str, Any]:
+    """Return one instruction target, files, and related proposals."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    target = repository.get_target(target_id_or_name)
+    return {
+        "target": target.model_dump(),
+        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
+        "proposals": [item.model_dump() for item in repository.list_proposals(target_id=target.target_id)],
+        "error": False,
+    }
+
+
+def api_skill_target_mode(
+    *,
+    target_id_or_name: str,
+    update_mode: str,
+    auto_apply_policy: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Update target review mode and auto-apply policy."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    existing = repository.get_target(target_id_or_name)
+    policy = existing.auto_apply_policy
+    if auto_apply_policy is not None:
+        policy = AutoApplyPolicy.model_validate({**policy.model_dump(), **auto_apply_policy})
+    target = repository.update_target_mode(target_id_or_name, update_mode, policy)
+    return {"target": target.model_dump(), "error": False}
+
+
+def api_skill_refresh(target_id_or_name: str, *, record_limit: int = 80) -> dict[str, Any]:
+    """Run the LLM-backed skill stewardship proposal pipeline."""
+    result = run_skill_stewardship_refresh(
+        target_id_or_name,
+        record_limit=record_limit,
+        progress=False,
+    )
+    return {**result, "error": False}
+
+
+def api_skill_proposals(
+    *,
+    target_id: str | None = None,
+    status: str | None = None,
+) -> dict[str, Any]:
+    """List skill update proposals."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposals = repository.list_proposals(target_id=target_id, status=status)
+    return {"proposals": [proposal.model_dump() for proposal in proposals], "error": False}
+
+
+def api_skill_proposal_show(proposal_id: str) -> dict[str, Any]:
+    """Return one proposal with its target and files."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    target = repository.get_target(proposal.target_id)
+    return {
+        "proposal": proposal.model_dump(),
+        "target": target.model_dump(),
+        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
+        "error": False,
+    }
+
+
+def api_skill_proposal_apply(proposal_id: str) -> dict[str, Any]:
+    """Apply a proposal after user confirmation."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    applied = apply_proposal(repository=repository, proposal=proposal, applied_by="user")
+    return {"proposal": applied.model_dump(), "error": False}
+
+
+def api_skill_proposal_reject(proposal_id: str) -> dict[str, Any]:
+    """Reject a proposal from CLI or dashboard review."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.set_proposal_status(proposal_id, "rejected")
+    return {"proposal": proposal.model_dump(), "error": False}
+
+
+def api_skill_proposal_update(proposal_id: str, patch_json: dict[str, Any]) -> dict[str, Any]:
+    """Replace proposal patch JSON after dashboard editing."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    target = repository.get_target(proposal.target_id)
+    if target.manifest is None:
+        raise ValueError("target manifest is missing")
+    base = Path(target.path).expanduser().resolve()
+    if base.is_file():
+        base = base.parent
+    draft = hydrate_patch_text(base=base, draft=SkillProposalDraft.model_validate(patch_json))
+    guard = guard_proposal(draft=draft, policy=target.auto_apply_policy)
+    validation = validate_proposal(base_path=base, manifest=target.manifest, proposal=draft)
+    updated = repository.update_proposal_patch(
+        proposal_id=proposal_id,
+        draft=draft,
+        validation=validation,
+        guard=guard,
+    )
+    return {"proposal": updated.model_dump(), "error": False}
+
+
+def api_skill_runs(limit: int = 20) -> dict[str, Any]:
+    """List recent skill stewardship runs."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    return {"runs": repository.recent_runs(limit=limit), "error": False}
+
+
 def api_memory_reset(
     *,
     project: str | None = None,
diff --git a/src/lerim/server/cli.py b/src/lerim/server/cli.py
index 194b3fd7..966cc630 100644
--- a/src/lerim/server/cli.py
+++ b/src/lerim/server/cli.py
@@ -40,6 +40,15 @@
 )
 
 from lerim.server.api import (
+    api_skill_proposal_apply,
+    api_skill_proposal_reject,
+    api_skill_proposal_show,
+    api_skill_proposals,
+    api_skill_refresh,
+    api_skill_target_add,
+    api_skill_target_mode,
+    api_skill_target_show,
+    api_skill_targets,
     api_memory_reset,
     api_project_add,
     api_project_list,
@@ -1334,6 +1343,7 @@ def _cmd_query(args: argparse.Namespace) -> int:
         scope=scope,
         project=getattr(args, "project", None),
         kind=getattr(args, "kind", None),
+        record_role=getattr(args, "role", None),
         status=getattr(args, "status", None),
         source_profile=getattr(args, "source_profile", None),
         source_session_id=getattr(args, "source_session_id", None),
@@ -1369,6 +1379,7 @@ def _cmd_context_records(args: argparse.Namespace) -> int:
         scope=_normalize_scope(getattr(args, "scope", None)),
         project=getattr(args, "project", None),
         kind=requested_kind,
+        record_role=getattr(args, "role", None),
         status=getattr(args, "status", None),
         source_profile=getattr(args, "profile", None)
         or getattr(args, "source_profile", None),
@@ -1398,6 +1409,9 @@ def _cmd_context_records(args: argparse.Namespace) -> int:
     _emit(f"{len(rows)} records shown")
     if requested_kind:
         _emit(f"Kind: {requested_kind}")
+    requested_role = str(getattr(args, "role", "") or "").strip()
+    if requested_role:
+        _emit(f"Role: {requested_role}")
     if not rows:
         return 0
     for kind, group_rows in _group_record_rows_by_kind(rows).items():
@@ -1410,7 +1424,8 @@ def _cmd_context_records(args: argparse.Namespace) -> int:
             _emit(f"- {title_text}")
             _emit(
                 "  "
-                f"{row.get('record_id', '')} | {row.get('kind', '')} | {status} | "
+                f"{row.get('record_id', '')} | {row.get('kind', '')} | "
+                f"{row.get('record_role', 'general')} | {status} | "
                 f"{scope} | {row.get('source_profile', 'coding')}"
             )
             evidence = _evidence_summary(row)
@@ -2748,12 +2763,22 @@ def _shutdown(_signum: int, _frame: Any) -> None:
 
 
 def _cmd_skill(args: argparse.Namespace) -> int:
-    """Install Lerim skill files into coding agent directories."""
+    """Dispatch skill install, target, proposal, and refresh commands."""
     action = getattr(args, "skill_action", None)
-    if action != "install":
-        _emit("Usage: lerim skill install")
-        return 2
+    if action == "install":
+        return _cmd_skill_install()
+    if action == "target":
+        return _cmd_skill_target(args)
+    if action == "proposal":
+        return _cmd_skill_proposal(args)
+    if action == "refresh":
+        return _cmd_skill_refresh(args)
+    _emit("Usage: lerim skill install|target|proposal|refresh")
+    return 2
 
+
+def _cmd_skill_install() -> int:
+    """Install Lerim skill files into coding agent directories."""
     from lerim.skills import SKILLS_DIR
 
     skill_files = [SKILLS_DIR / "SKILL.md", SKILLS_DIR / "cli-reference.md"]
@@ -2779,6 +2804,111 @@ def _cmd_skill(args: argparse.Namespace) -> int:
     return 0
 
 
+def _cmd_skill_target(args: argparse.Namespace) -> int:
+    """Manage registered instruction targets."""
+    subaction = getattr(args, "target_action", None)
+    try:
+        if subaction == "add":
+            result = api_skill_target_add(
+                path=args.path,
+                name=getattr(args, "name", None),
+                description=getattr(args, "description", None),
+                update_mode=getattr(args, "mode", "review"),
+            )
+            target = result["target"]
+            _emit(f"Registered {target['name']} ({target['target_type']})")
+            _emit(f"- id: {target['target_id']}")
+            _emit(f"- path: {target['path']}")
+            _emit(f"- entry: {target['entry_file']}")
+            return 0
+        if subaction == "list":
+            result = api_skill_targets()
+            if getattr(args, "json", False):
+                _emit(json.dumps(result, indent=2, ensure_ascii=True))
+                return 0
+            for target in result["targets"]:
+                _emit(
+                    f"{target['target_id']}  {target['name']}  "
+                    f"{target['target_type']}  {target['update_mode']}  {target['path']}"
+                )
+            return 0
+        if subaction == "show":
+            result = api_skill_target_show(args.target)
+            _emit(json.dumps(result, indent=2, ensure_ascii=True))
+            return 0
+        if subaction == "auto-apply":
+            policy = {"enabled": bool(args.enable), "max_risk": args.risk}
+            mode = "auto_apply" if args.enable else "review"
+            result = api_skill_target_mode(
+                target_id_or_name=args.target,
+                update_mode=mode,
+                auto_apply_policy=policy,
+            )
+            target = result["target"]
+            _emit(f"Updated {target['name']} mode to {target['update_mode']}")
+            return 0
+    except (FileNotFoundError, KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    _emit("Usage: lerim skill target add|list|show|auto-apply")
+    return 2
+
+
+def _cmd_skill_proposal(args: argparse.Namespace) -> int:
+    """Review and apply skill update proposals."""
+    subaction = getattr(args, "proposal_action", None)
+    try:
+        if subaction == "list":
+            result = api_skill_proposals(
+                target_id=getattr(args, "target_id", None),
+                status=getattr(args, "status", None),
+            )
+            if getattr(args, "json", False):
+                _emit(json.dumps(result, indent=2, ensure_ascii=True))
+                return 0
+            for proposal in result["proposals"]:
+                _emit(
+                    f"{proposal['proposal_id']}  {proposal['status']}  "
+                    f"{proposal['risk_level']}  {proposal['title']}"
+                )
+            return 0
+        if subaction == "show":
+            result = api_skill_proposal_show(args.proposal)
+            _emit(json.dumps(result, indent=2, ensure_ascii=True))
+            return 0
+        if subaction == "apply":
+            result = api_skill_proposal_apply(args.proposal)
+            _emit(f"Applied {result['proposal']['proposal_id']}")
+            return 0
+        if subaction == "reject":
+            result = api_skill_proposal_reject(args.proposal)
+            _emit(f"Rejected {result['proposal']['proposal_id']}")
+            return 0
+    except (KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    _emit("Usage: lerim skill proposal list|show|apply|reject")
+    return 2
+
+
+def _cmd_skill_refresh(args: argparse.Namespace) -> int:
+    """Run LLM-backed proposal generation for a registered target."""
+    try:
+        result = api_skill_refresh(args.target, record_limit=args.record_limit)
+    except (KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    if getattr(args, "json", False):
+        _emit(json.dumps(result, indent=2, ensure_ascii=True))
+        return 0
+    _emit(f"Refresh run {result['run_id']}")
+    _emit(f"- records scanned: {result['records_scanned']}")
+    _emit(f"- signals: {result['signals_created']}")
+    _emit(f"- proposals: {len(result['proposals'])}")
+    _emit(f"- applied: {result['applied']}")
+    return 0
+
+
 def _cmd_auth_dispatch(args: argparse.Namespace) -> int:
     """Dispatch auth subcommands to the appropriate handler."""
     auth_command = getattr(args, "auth_command", None)
@@ -3230,6 +3360,7 @@ def build_parser() -> argparse.ArgumentParser:
     query.add_argument("--scope", choices=["all", "project"], default="all")
     query.add_argument("--project", help="Project name/path when --scope=project.")
     query.add_argument("--kind")
+    query.add_argument("--role", help="Filter records by operational role.")
     query.add_argument("--status")
     query.add_argument(
         "--source-profile",
@@ -3278,6 +3409,10 @@ def build_parser() -> argparse.ArgumentParser:
         dest="kind",
         help="Filter by durable record kind, for example fact or constraint.",
     )
+    context_records.add_argument(
+        "--role",
+        help="Filter by operational role, for example procedure or gotcha.",
+    )
     context_records.add_argument(
         "--status",
         help="Filter by storage record status, for example active or archived.",
@@ -3636,8 +3771,8 @@ def build_parser() -> argparse.ArgumentParser:
     skill = sub.add_parser(
         "skill",
         formatter_class=_F,
-        help="Install Lerim skill files into coding agent directories",
-        description="Install Lerim skill files into agent directories.",
+        help="Install Lerim skill files and manage watched skill updates",
+        description="Install Lerim skill files and manage registered instruction artifacts.",
     )
     skill_sub = skill.add_subparsers(dest="skill_action")
     skill_sub.add_parser(
@@ -3645,6 +3780,62 @@ def build_parser() -> argparse.ArgumentParser:
         formatter_class=_F,
         help="Copy skill files into agent directories",
     )
+    skill_target = skill_sub.add_parser(
+        "target",
+        formatter_class=_F,
+        help="Register, inspect, and configure watched instruction artifacts",
+    )
+    target_sub = skill_target.add_subparsers(dest="target_action")
+    target_add = target_sub.add_parser("add", formatter_class=_F, help="Register a skill or instruction path")
+    target_add.add_argument("path", help="Skill directory, SKILL.md, AGENTS.md, or related instruction file.")
+    target_add.add_argument("--name", help="Display name for this watched target.")
+    target_add.add_argument("--description", help="What Lerim should improve in this target.")
+    target_add.add_argument(
+        "--mode",
+        choices=["review", "auto_apply", "paused"],
+        default="review",
+        help="Update mode. Default: review.",
+    )
+    target_list = target_sub.add_parser("list", formatter_class=_F, help="List registered targets")
+    target_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+    target_show = target_sub.add_parser("show", formatter_class=_F, help="Show one registered target")
+    target_show.add_argument("target", help="Target id or name.")
+    target_auto = target_sub.add_parser(
+        "auto-apply",
+        formatter_class=_F,
+        help="Enable or disable low-risk automatic proposal application",
+    )
+    target_auto.add_argument("target", help="Target id or name.")
+    auto_group = target_auto.add_mutually_exclusive_group(required=True)
+    auto_group.add_argument("--enable", action="store_true", help="Enable auto-apply.")
+    auto_group.add_argument("--disable", dest="enable", action="store_false", help="Disable auto-apply.")
+    target_auto.add_argument("--risk", choices=["low", "medium", "high"], default="low")
+
+    skill_refresh = skill_sub.add_parser(
+        "refresh",
+        formatter_class=_F,
+        help="Run LLM-backed proposal generation for a target",
+    )
+    skill_refresh.add_argument("target", help="Target id or name.")
+    skill_refresh.add_argument("--record-limit", type=int, default=80)
+    skill_refresh.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+
+    skill_proposal = skill_sub.add_parser(
+        "proposal",
+        formatter_class=_F,
+        help="Review and apply skill update proposals",
+    )
+    proposal_sub = skill_proposal.add_subparsers(dest="proposal_action")
+    proposal_list = proposal_sub.add_parser("list", formatter_class=_F, help="List proposals")
+    proposal_list.add_argument("--target-id", help="Filter by target id.")
+    proposal_list.add_argument("--status", help="Filter by proposal status.")
+    proposal_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+    proposal_show = proposal_sub.add_parser("show", formatter_class=_F, help="Show one proposal")
+    proposal_show.add_argument("proposal", help="Proposal id.")
+    proposal_apply = proposal_sub.add_parser("apply", formatter_class=_F, help="Apply one proposal")
+    proposal_apply.add_argument("proposal", help="Proposal id.")
+    proposal_reject = proposal_sub.add_parser("reject", formatter_class=_F, help="Reject one proposal")
+    proposal_reject.add_argument("proposal", help="Proposal id.")
     skill.set_defaults(func=_cmd_skill)
 
     # ── auth ──────────────────────────────────────────────────────────
diff --git a/src/lerim/server/httpd.py b/src/lerim/server/httpd.py
index 5894152d..134d183b 100644
--- a/src/lerim/server/httpd.py
+++ b/src/lerim/server/httpd.py
@@ -43,6 +43,17 @@
     api_project_remove,
     api_queue_jobs,
     api_retry_all_dead_letter,
+    api_skill_proposal_apply,
+    api_skill_proposal_reject,
+    api_skill_proposal_show,
+    api_skill_proposal_update,
+    api_skill_proposals,
+    api_skill_refresh,
+    api_skill_runs,
+    api_skill_target_add,
+    api_skill_target_mode,
+    api_skill_target_show,
+    api_skill_targets,
     api_retry_job,
     api_skip_all_dead_letter,
     api_skip_job,
@@ -534,6 +545,8 @@ def _graph_node_payload(row: sqlite3.Row) -> dict[str, Any]:
         "label": row["label"],
         "kind": "record",
         "record_kind": row["record_kind"] if "record_kind" in keys and row["record_kind"] else row["node_type"],
+        "record_role": row["record_role"] if "record_role" in keys and row["record_role"] else "general",
+        "role_payload": row["role_payload"] if "role_payload" in keys else None,
         "summary": row["summary"],
         "project": row["scope_label"],
         "status": row["status"],
@@ -1049,6 +1062,7 @@ def _api_graph_query(self) -> None:
                 return
             node_rows = conn.execute(
                 f"""SELECT cn.node_id, cn.node_type, COALESCE(r.kind, cn.node_type) AS record_kind,
+                          COALESCE(r.record_role, 'general') AS record_role, r.role_payload,
                           cn.label, cn.summary, cn.status, cn.semantic_cluster,
                           cn.scope_label, cn.created_at, cn.updated_at
                    FROM context_nodes cn
@@ -1115,6 +1129,40 @@ def _handle_api_get(self, path: str, query: dict[str, list[str]]) -> None:
                 return
             self._json(api_unscoped(limit=limit))
             return
+        if path == "/api/skills/targets":
+            self._json(api_skill_targets())
+            return
+        if path == "/api/skills/proposals":
+            self._json(
+                api_skill_proposals(
+                    target_id=_query_param(query, "target_id") or None,
+                    status=_query_param(query, "status") or None,
+                )
+            )
+            return
+        if path == "/api/skills/runs":
+            self._json(api_skill_runs(limit=_parse_int(_query_param(query, "limit", "20"), 20, minimum=1, maximum=200)))
+            return
+        if path.startswith("/api/skills/targets/"):
+            target_id = unquote(path.split("/api/skills/targets/", 1)[1])
+            if not target_id:
+                self._error(HTTPStatus.BAD_REQUEST, "Missing target id")
+                return
+            try:
+                self._json(api_skill_target_show(target_id))
+            except KeyError as exc:
+                self._error(HTTPStatus.NOT_FOUND, str(exc))
+            return
+        if path.startswith("/api/skills/proposals/"):
+            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1])
+            if not proposal_id:
+                self._error(HTTPStatus.BAD_REQUEST, "Missing proposal id")
+                return
+            try:
+                self._json(api_skill_proposal_show(proposal_id))
+            except KeyError as exc:
+                self._error(HTTPStatus.NOT_FOUND, str(exc))
+            return
         no_query_handlers = {
             "/api/health": lambda: self._json(api_health()),
             "/api/live": self._api_live,
@@ -1247,6 +1295,7 @@ def _run_context_answerer() -> None:
                 "scope",
                 "project",
                 "kind",
+                "record_role",
                 "source_profile",
                 "status",
                 "source_session_id",
@@ -1279,6 +1328,7 @@ def _run_context_answerer() -> None:
                 scope=str(body.get("scope") or "all"),
                 project=str(body.get("project") or "").strip() or None,
                 kind=str(body.get("kind") or "").strip() or None,
+                record_role=str(body.get("record_role") or "").strip() or None,
                 source_profile=str(body.get("source_profile") or "").strip() or None,
                 status=str(body.get("status") or "").strip() or None,
                 source_session_id=str(body.get("source_session_id") or "").strip() or None,
@@ -1298,6 +1348,86 @@ def _run_context_answerer() -> None:
                 return
             self._json(result)
             return
+        if path == "/api/skills/targets":
+            body = read_body()
+            if body is None:
+                return
+            target_path = str(body.get("path") or "").strip()
+            if not target_path:
+                self._error(HTTPStatus.BAD_REQUEST, "Missing 'path'")
+                return
+            try:
+                self._json(
+                    api_skill_target_add(
+                        path=target_path,
+                        name=str(body.get("name") or "").strip() or None,
+                        description=str(body.get("description") or "").strip() or None,
+                        update_mode=str(body.get("update_mode") or "review"),
+                    )
+                )
+            except (FileNotFoundError, ValueError) as exc:
+                self._error(HTTPStatus.BAD_REQUEST, str(exc))
+            return
+        if path.startswith("/api/skills/targets/") and path.endswith("/refresh"):
+            target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/refresh", 1)[0])
+            body = read_body() or {}
+            try:
+                self._json(
+                    api_skill_refresh(
+                        target_id,
+                        record_limit=_parse_int(str(body.get("record_limit") or "80"), 80, minimum=1, maximum=500),
+                    )
+                )
+            except KeyError as exc:
+                self._error(HTTPStatus.NOT_FOUND, str(exc))
+            except Exception as exc:
+                logger.exception("skill refresh failed")
+                self._error(HTTPStatus.INTERNAL_SERVER_ERROR, f"Skill refresh failed: {exc}")
+            return
+        if path.startswith("/api/skills/targets/") and path.endswith("/mode"):
+            target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/mode", 1)[0])
+            body = read_body()
+            if body is None:
+                return
+            try:
+                self._json(
+                    api_skill_target_mode(
+                        target_id_or_name=target_id,
+                        update_mode=str(body.get("update_mode") or "review"),
+                        auto_apply_policy=body.get("auto_apply_policy") if isinstance(body.get("auto_apply_policy"), dict) else None,
+                    )
+                )
+            except (KeyError, ValueError) as exc:
+                self._error(HTTPStatus.BAD_REQUEST, str(exc))
+            return
+        if path.startswith("/api/skills/proposals/") and path.endswith("/apply"):
+            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/apply", 1)[0])
+            try:
+                self._json(api_skill_proposal_apply(proposal_id))
+            except (KeyError, ValueError) as exc:
+                self._error(HTTPStatus.BAD_REQUEST, str(exc))
+            return
+        if path.startswith("/api/skills/proposals/") and path.endswith("/reject"):
+            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/reject", 1)[0])
+            try:
+                self._json(api_skill_proposal_reject(proposal_id))
+            except KeyError as exc:
+                self._error(HTTPStatus.NOT_FOUND, str(exc))
+            return
+        if path.startswith("/api/skills/proposals/") and path.endswith("/edit"):
+            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/edit", 1)[0])
+            body = read_body()
+            if body is None:
+                return
+            patch_json = body.get("patch_json")
+            if not isinstance(patch_json, dict):
+                self._error(HTTPStatus.BAD_REQUEST, "Missing 'patch_json'")
+                return
+            try:
+                self._json(api_skill_proposal_update(proposal_id, patch_json))
+            except (KeyError, ValueError) as exc:
+                self._error(HTTPStatus.BAD_REQUEST, str(exc))
+            return
         if path == "/api/ingest":
             body = read_body()
             if body is None:
diff --git a/src/lerim/skill_stewardship/__init__.py b/src/lerim/skill_stewardship/__init__.py
new file mode 100644
index 00000000..7087bc37
--- /dev/null
+++ b/src/lerim/skill_stewardship/__init__.py
@@ -0,0 +1,12 @@
+"""Skill stewardship services for registered instruction artifacts."""
+
+from lerim.skill_stewardship.artifacts import scan_instruction_artifact
+from lerim.skill_stewardship.pipeline import run_skill_stewardship_refresh
+from lerim.skill_stewardship.repository import SkillStewardshipRepository
+
+__all__ = [
+    "SkillStewardshipRepository",
+    "run_skill_stewardship_refresh",
+    "scan_instruction_artifact",
+]
+
diff --git a/src/lerim/skill_stewardship/artifacts.py b/src/lerim/skill_stewardship/artifacts.py
new file mode 100644
index 00000000..d998b2a5
--- /dev/null
+++ b/src/lerim/skill_stewardship/artifacts.py
@@ -0,0 +1,274 @@
+"""Filesystem scanner for registered skill and instruction artifacts."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from lerim.skill_stewardship.schemas import ArtifactManifest, TargetFile, TargetType
+
+MAX_FILE_BYTES = 64_000
+MAX_SCAN_FILES = 80
+ENTRY_NAMES = ("SKILL.md", "AGENTS.md", "CLAUDE.md", "GEMINI.md", ".cursorrules", ".windsurfrules")
+KNOWN_SUPPORT_DIRS = {
+    "references",
+    "reference",
+    "examples",
+    "scripts",
+    "assets",
+    "agents",
+    ".clinerules",
+    ".cursor",
+    ".roo",
+}
+
+
+def scan_instruction_artifact(path: Path | str) -> tuple[Path, ArtifactManifest, list[TargetFile]]:
+    """Read a registered instruction path and return its detected manifest."""
+    root = Path(path).expanduser().resolve()
+    if not root.exists():
+        raise FileNotFoundError(f"instruction target not found: {root}")
+    base = root if root.is_dir() else root.parent
+    entry = _entry_file(root)
+    files = _target_files(root=root, base=base, entry=entry)
+    manifest = _manifest_for(root=root, base=base, entry=entry, files=files)
+    return base, manifest, files
+
+
+def artifact_name(path: Path | str, manifest: ArtifactManifest) -> str:
+    """Return a stable display name for a scanned artifact."""
+    root = Path(path).expanduser()
+    if root.is_file():
+        return root.stem
+    if manifest.entry_file == "SKILL.md":
+        return root.name
+    return root.name or manifest.entry_file
+
+
+def read_target_text(base: Path | str, relative_path: str) -> str:
+    """Read one target file as UTF-8 text with replacement for malformed bytes."""
+    target = _safe_child(Path(base).expanduser().resolve(), relative_path)
+    return target.read_text(encoding="utf-8", errors="replace")
+
+
+def _entry_file(root: Path) -> Path:
+    """Resolve the entry file for a registered file or directory."""
+    if root.is_file():
+        return root
+    for name in ENTRY_NAMES:
+        candidate = root / name
+        if candidate.is_file():
+            return candidate
+    markdown_files = sorted(root.glob("*.md"))
+    if markdown_files:
+        return markdown_files[0]
+    text_files = sorted(root.glob("*.txt"))
+    if text_files:
+        return text_files[0]
+    raise FileNotFoundError(f"instruction target has no supported entry file: {root}")
+
+
+def _target_files(*, root: Path, base: Path, entry: Path) -> list[TargetFile]:
+    """Collect bounded artifact files for review and proposal generation."""
+    candidates = [entry]
+    if root.is_dir():
+        for child in sorted(root.rglob("*")):
+            if child.is_file() and _belongs_to_artifact(root, child):
+                candidates.append(child)
+    seen: set[Path] = set()
+    files: list[TargetFile] = []
+    for candidate in candidates:
+        resolved = candidate.resolve()
+        if resolved in seen:
+            continue
+        seen.add(resolved)
+        if len(files) >= MAX_SCAN_FILES:
+            break
+        try:
+            stat = resolved.stat()
+        except OSError:
+            continue
+        relative_path = resolved.relative_to(base).as_posix()
+        preview = None
+        if _is_textish(resolved) and stat.st_size <= MAX_FILE_BYTES:
+            preview = resolved.read_text(encoding="utf-8", errors="replace")
+        files.append(
+            TargetFile(
+                relative_path=relative_path,
+                file_role=_file_role(root=root, entry=entry, path=resolved),
+                size_bytes=stat.st_size,
+                sha256=_sha256(resolved),
+                text_preview=preview,
+                risk_surface=_risk_surface(root=root, path=resolved),
+            )
+        )
+    return files
+
+
+def _manifest_for(*, root: Path, base: Path, entry: Path, files: list[TargetFile]) -> ArtifactManifest:
+    """Build a manifest for the detected instruction artifact type."""
+    target_type = _target_type(root=root, entry=entry)
+    entry_rel = entry.resolve().relative_to(base).as_posix()
+    frontmatter = _frontmatter(entry)
+    known_frontmatter = sorted(frontmatter.keys())
+    supporting = [item.relative_path for item in files if item.relative_path != entry_rel]
+    instruction_files = [
+        item.relative_path
+        for item in files
+        if item.file_role in {"entry", "rule", "context", "reference"} and _is_textish(Path(item.relative_path))
+    ]
+    required = ["name", "description"] if target_type == "codex_skill" else []
+    return ArtifactManifest(
+        target_type=target_type,
+        entry_file=entry_rel,
+        instruction_files=instruction_files or [entry_rel],
+        supporting_files=supporting,
+        required_frontmatter=required,
+        known_frontmatter=known_frontmatter,
+        allowed_update_surfaces=_allowed_surfaces(target_type),
+        high_risk_surfaces=_high_risk_surfaces(target_type),
+        notes=_manifest_notes(target_type=target_type, files=files),
+    )
+
+
+def _target_type(*, root: Path, entry: Path) -> TargetType:
+    """Classify known instruction artifact layouts from file structure."""
+    if entry.name == "SKILL.md":
+        if ".claude" in entry.parts or root.parent.name == "skills" and ".claude" in root.parts:
+            return "claude_skill"
+        if ".agents" in entry.parts or root.parent.name == "skills":
+            return "codex_skill"
+        return "agent_skill"
+    if entry.name == "AGENTS.md":
+        return "agents_md"
+    if entry.name == "GEMINI.md":
+        return "gemini_context"
+    if entry.name == ".cursorrules" or ".cursor" in entry.parts:
+        return "cursor_rules"
+    if entry.name == ".windsurfrules":
+        return "generic_markdown_bundle"
+    if root.name == ".clinerules" or ".clinerules" in entry.parts:
+        return "cline_rules"
+    if entry.name == "CLAUDE.md":
+        return "opencode_rules"
+    return "generic_markdown_bundle"
+
+
+def _belongs_to_artifact(root: Path, path: Path) -> bool:
+    """Return whether a child file should be considered part of an artifact."""
+    rel = path.resolve().relative_to(root.resolve())
+    if len(rel.parts) == 1:
+        return path.name in ENTRY_NAMES or path.suffix in {".md", ".txt", ".yaml", ".yml", ".json", ".toml"}
+    return rel.parts[0] in KNOWN_SUPPORT_DIRS and path.stat().st_size <= MAX_FILE_BYTES
+
+
+def _file_role(*, root: Path, entry: Path, path: Path) -> str:
+    """Classify one artifact file's role."""
+    if path.resolve() == entry.resolve():
+        return "entry"
+    rel = path.resolve().relative_to(root.resolve()) if root.is_dir() else Path(path.name)
+    if rel.parts and rel.parts[0] in {"scripts"}:
+        return "script"
+    if rel.parts and rel.parts[0] in {"assets"}:
+        return "asset"
+    if rel.parts and rel.parts[0] in {"agents", ".cursor", ".roo"}:
+        return "config"
+    if rel.parts and rel.parts[0] in {".clinerules"}:
+        return "rule"
+    if path.suffix in {".md", ".txt"}:
+        return "reference"
+    return "supporting"
+
+
+def _risk_surface(*, root: Path, path: Path) -> str:
+    """Classify update risk for a target file."""
+    try:
+        rel = path.resolve().relative_to(root.resolve()) if root.is_dir() else Path(path.name)
+    except ValueError:
+        rel = Path(path.name)
+    if rel.parts and rel.parts[0] in {"scripts", "assets", "agents", ".cursor", ".roo"}:
+        return "high"
+    if path.name == "SKILL.md":
+        return "medium"
+    return "low"
+
+
+def _frontmatter(path: Path) -> dict[str, Any]:
+    """Parse YAML frontmatter from a markdown-ish file."""
+    if not _is_textish(path):
+        return {}
+    text = path.read_text(encoding="utf-8", errors="replace")
+    if not text.startswith("---\n"):
+        return {}
+    end = text.find("\n---", 4)
+    if end < 0:
+        return {}
+    parsed = yaml.safe_load(text[4:end]) or {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+def _allowed_surfaces(target_type: TargetType) -> list[str]:
+    """Return update surfaces the proposal pipeline may target by default."""
+    if target_type in {"codex_skill", "claude_skill", "agent_skill"}:
+        return ["entry_file_body", "references", "examples"]
+    if target_type == "cline_rules":
+        return ["markdown_rule_files"]
+    if target_type == "gemini_context":
+        return ["context_body", "explicit_imports"]
+    return ["markdown_body"]
+
+
+def _high_risk_surfaces(target_type: TargetType) -> list[str]:
+    """Return update surfaces requiring explicit review."""
+    surfaces = ["scripts", "assets", "config_files", "frontmatter"]
+    if target_type == "codex_skill":
+        surfaces.append("agents/openai.yaml")
+    if target_type == "claude_skill":
+        surfaces.extend(["allowed-tools", "disable-model-invocation", "hooks", "mcp_config"])
+    return surfaces
+
+
+def _manifest_notes(*, target_type: TargetType, files: list[TargetFile]) -> list[str]:
+    """Summarize detected artifact constraints for the model."""
+    notes = [f"Detected instruction artifact type: {target_type}."]
+    if any(item.file_role == "script" for item in files):
+        notes.append("Script changes are high risk and require explicit review.")
+    if target_type in {"codex_skill", "claude_skill", "agent_skill"}:
+        notes.append("Keep SKILL.md concise; prefer referenced files for long detail.")
+    return notes
+
+
+def _is_textish(path: Path) -> bool:
+    """Return whether a file extension is safe to read as text."""
+    return path.name in ENTRY_NAMES or path.suffix.lower() in {".md", ".txt", ".yaml", ".yml", ".json", ".toml", ".py", ".sh"}
+
+
+def _sha256(path: Path) -> str:
+    """Hash a file for snapshot and drift detection."""
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(65536), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def _safe_child(base: Path, relative_path: str) -> Path:
+    """Resolve a child path and reject traversal outside the target base."""
+    resolved = (base / relative_path).resolve()
+    if base != resolved and base not in resolved.parents:
+        raise ValueError(f"path escapes instruction target: {relative_path}")
+    return resolved
+
+
+def manifest_json(manifest: ArtifactManifest, files: list[TargetFile]) -> str:
+    """Render a compact manifest JSON string for model input."""
+    payload = manifest.model_dump()
+    payload["files"] = [
+        item.model_dump(exclude={"text_preview"})
+        for item in files
+    ]
+    return json.dumps(payload, indent=2, ensure_ascii=True)
diff --git a/src/lerim/skill_stewardship/patching.py b/src/lerim/skill_stewardship/patching.py
new file mode 100644
index 00000000..bb2eabe2
--- /dev/null
+++ b/src/lerim/skill_stewardship/patching.py
@@ -0,0 +1,69 @@
+"""Apply approved instruction proposal patches with snapshots."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+from lerim.skill_stewardship.repository import SkillStewardshipRepository, utc_now
+from lerim.skill_stewardship.schemas import SkillProposal, SkillProposalDraft
+
+
+def apply_proposal(
+    *,
+    repository: SkillStewardshipRepository,
+    proposal: SkillProposal,
+    applied_by: str,
+) -> SkillProposal:
+    """Apply a persisted proposal after review or auto-apply guard approval."""
+    target = repository.get_target(proposal.target_id)
+    base = Path(target.path).expanduser().resolve()
+    if base.is_file():
+        base = base.parent
+    draft = SkillProposalDraft.model_validate(proposal.patch_json)
+    snapshot_root = _snapshot_root(repository.context_store.db_path.parent, proposal.proposal_id)
+    for patch in draft.patches:
+        target_file = _safe_child(base, patch.relative_path)
+        before_hash = _hash_text(target_file.read_text(encoding="utf-8", errors="replace")) if target_file.exists() else None
+        snapshot_path = None
+        if target_file.exists():
+            snapshot_path = str(_write_snapshot(snapshot_root, patch.relative_path, target_file))
+        target_file.parent.mkdir(parents=True, exist_ok=True)
+        target_file.write_text(patch.after_text, encoding="utf-8")
+        after_hash = _hash_text(patch.after_text)
+        repository.save_applied_version(
+            target_id=target.target_id,
+            proposal_id=proposal.proposal_id,
+            relative_path=patch.relative_path,
+            before_hash=before_hash,
+            after_hash=after_hash,
+            snapshot_path=snapshot_path,
+            applied_by=applied_by,
+        )
+    return repository.set_proposal_status(proposal.proposal_id, "applied")
+
+
+def _snapshot_root(base: Path, proposal_id: str) -> Path:
+    """Return the snapshot directory for one proposal application."""
+    return base / "skill-snapshots" / proposal_id / utc_now().replace(":", "-")
+
+
+def _write_snapshot(snapshot_root: Path, relative_path: str, target_file: Path) -> Path:
+    """Copy one before-file into the snapshot folder."""
+    snapshot_path = _safe_child(snapshot_root, relative_path)
+    snapshot_path.parent.mkdir(parents=True, exist_ok=True)
+    snapshot_path.write_bytes(target_file.read_bytes())
+    return snapshot_path
+
+
+def _safe_child(base: Path, relative_path: str) -> Path:
+    """Resolve a child path and reject traversal outside base."""
+    resolved = (base / relative_path).resolve()
+    if base != resolved and base not in resolved.parents:
+        raise ValueError(f"path escapes instruction target: {relative_path}")
+    return resolved
+
+
+def _hash_text(text: str) -> str:
+    """Hash file text for version metadata."""
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
diff --git a/src/lerim/skill_stewardship/pipeline.py b/src/lerim/skill_stewardship/pipeline.py
new file mode 100644
index 00000000..90bfd8b0
--- /dev/null
+++ b/src/lerim/skill_stewardship/pipeline.py
@@ -0,0 +1,302 @@
+"""LLM-backed pipeline for proposing instruction artifact updates."""
+
+from __future__ import annotations
+
+import difflib
+import json
+from pathlib import Path
+from typing import Any
+
+from lerim.agents.dspy_compat import dspy
+from lerim.agents.model_helpers import call_model_step, prediction_payload
+from lerim.agents.model_runtime import ModelRuntime, build_model_runtime
+from lerim.config.settings import Config, get_config
+from lerim.context import ContextStore
+from lerim.skill_stewardship.artifacts import manifest_json, read_target_text, scan_instruction_artifact
+from lerim.skill_stewardship.patching import apply_proposal
+from lerim.skill_stewardship.repository import SkillStewardshipRepository
+from lerim.skill_stewardship.schemas import (
+    AutoApplyPolicy,
+    ProposalGuardResult,
+    SkillPatch,
+    SkillProposal,
+    SkillProposalDraft,
+)
+from lerim.skill_stewardship.signatures import CompileSkillUpdateProposal
+from lerim.skill_stewardship.validation import validate_proposal
+
+DEFAULT_RECORD_LIMIT = 80
+PREFERRED_RECORD_ROLES = [
+    "procedure",
+    "gotcha",
+    "failure_mode",
+    "artifact",
+    "state_change",
+    "eval_asset",
+]
+
+
+class SkillStewardshipPipeline(dspy.Module):
+    """Scan one registered target and create evidence-backed update proposals."""
+
+    def __init__(
+        self,
+        *,
+        repository: SkillStewardshipRepository,
+        config: Config,
+        runtime: ModelRuntime | None = None,
+        compile_step: Any | None = None,
+        progress: bool = False,
+    ) -> None:
+        """Create the stewardship pipeline."""
+        super().__init__()
+        self.repository = repository
+        self.config = config
+        self.runtime = runtime
+        self.compile_step = compile_step or dspy.Predict(CompileSkillUpdateProposal)
+        self.progress = progress
+        self.adapter = dspy.JSONAdapter()
+
+    def forward(self, target_id_or_name: str, *, record_limit: int = DEFAULT_RECORD_LIMIT) -> dict[str, Any]:
+        """Run one target refresh and return run/proposal metadata."""
+        target = self.repository.get_target(target_id_or_name)
+        run_id = self.repository.create_run(target.target_id)
+        proposals: list[SkillProposal] = []
+        applied = 0
+        try:
+            base, manifest, files = scan_instruction_artifact(target.path)
+            refreshed = self.repository.upsert_target(
+                name=target.name,
+                path=Path(target.path),
+                description=target.description,
+                manifest=manifest,
+                files=files,
+                update_mode=target.update_mode,
+                auto_apply_policy=target.auto_apply_policy,
+            )
+            records = _candidate_records(self.repository.context_store, limit=record_limit)
+            draft = self._compile(target=refreshed, base=base, manifest=manifest, files=files, records=records)
+            draft = hydrate_patch_text(base=base, draft=draft)
+            guard = guard_proposal(draft=draft, policy=refreshed.auto_apply_policy)
+            validation = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+            signals = self.repository.save_signals(run_id=run_id, target_id=refreshed.target_id, draft=draft)
+            if draft.patches and guard.accepted:
+                status = "pending_review" if validation.ok else "failed_validation"
+                proposal = self.repository.save_proposal(
+                    run_id=run_id,
+                    target_id=refreshed.target_id,
+                    draft=draft,
+                    guard=guard,
+                    validation=validation,
+                    status=status,
+                )
+                proposals.append(proposal)
+                if validation.ok and _should_auto_apply(refreshed.update_mode, refreshed.auto_apply_policy, proposal):
+                    proposals[-1] = apply_proposal(
+                        repository=self.repository,
+                        proposal=proposal,
+                        applied_by="auto_apply",
+                    )
+                    applied += 1
+            self.repository.finish_run(
+                run_id=run_id,
+                status="completed",
+                records_scanned=len(records),
+                signals_created=signals,
+                proposals_created=len(proposals),
+                proposals_applied=applied,
+            )
+            return {
+                "run_id": run_id,
+                "target_id": refreshed.target_id,
+                "records_scanned": len(records),
+                "signals_created": signals,
+                "proposals": [proposal.model_dump() for proposal in proposals],
+                "applied": applied,
+            }
+        except Exception as exc:
+            self.repository.finish_run(
+                run_id=run_id,
+                status="failed",
+                records_scanned=0,
+                signals_created=0,
+                proposals_created=0,
+                error=f"{type(exc).__name__}: {exc}",
+            )
+            raise
+
+    def _compile(
+        self,
+        *,
+        target: Any,
+        base: Path,
+        manifest: Any,
+        files: Any,
+        records: list[dict[str, Any]],
+    ) -> SkillProposalDraft:
+        """Call the model to compile one proposal draft."""
+        if self.runtime is None:
+            self.runtime = build_model_runtime(config=self.config)
+        file_payload = [
+            {
+                "relative_path": item.relative_path,
+                "file_role": item.file_role,
+                "risk_surface": item.risk_surface,
+                "text": item.text_preview,
+            }
+            for item in files
+            if item.text_preview is not None
+        ]
+        with dspy.context(lm=self.runtime.lm, adapter=self.adapter):
+            result, _, _attempts = call_model_step(
+                lambda: self.compile_step(
+                    target_json=target.model_dump_json(),
+                    manifest_json=manifest_json(manifest, files),
+                    files_json=json.dumps(file_payload, ensure_ascii=True),
+                    records_json=json.dumps(records, ensure_ascii=True),
+                ),
+                stage="skill_update_compile",
+                progress=self.progress,
+                progress_label="skill-stewardship",
+                validate_result=_validate_compile_result,
+                validation_retry_target="complete SkillProposalDraft JSON object",
+            )
+        payload = prediction_payload(result, output_field="proposal")
+        return SkillProposalDraft.model_validate(payload)
+
+
+def run_skill_stewardship_refresh(
+    target_id_or_name: str,
+    *,
+    config: Config | None = None,
+    record_limit: int = DEFAULT_RECORD_LIMIT,
+    progress: bool = False,
+) -> dict[str, Any]:
+    """Refresh one registered target using the configured agent model."""
+    effective_config = config or get_config()
+    repository = SkillStewardshipRepository(ContextStore(effective_config.context_db_path))
+    pipeline = SkillStewardshipPipeline(repository=repository, config=effective_config, progress=progress)
+    return pipeline(target_id_or_name, record_limit=record_limit)
+
+
+def guard_proposal(*, draft: SkillProposalDraft, policy: AutoApplyPolicy) -> ProposalGuardResult:
+    """Apply deterministic safety gates to a model-authored proposal."""
+    reasons: list[str] = []
+    if not draft.patches:
+        return ProposalGuardResult(accepted=False, risk_level="low", auto_apply_eligible=False, reasons=["no_patch"])
+    risk = _highest_risk([draft.risk_level, *(patch.risk for patch in draft.patches)])
+    for patch in draft.patches:
+        if patch.risk == "high":
+            reasons.append(f"{patch.relative_path}: high-risk changes require manual review")
+        if not patch.evidence_record_ids:
+            reasons.append(f"{patch.relative_path}: missing evidence")
+        if patch.relative_path.split("/", 1)[0] in {"scripts", "assets"}:
+            reasons.append(f"{patch.relative_path}: scripts/assets are blocked from auto-apply")
+    auto_apply = (
+        policy.enabled
+        and risk == "low"
+        and len(draft.patches) <= policy.max_changed_files
+        and sum(max(0, len((patch.after_text or "").splitlines()) - len((patch.before_text or "").splitlines())) for patch in draft.patches)
+        <= policy.max_added_lines
+        and not reasons
+    )
+    return ProposalGuardResult(
+        accepted=all("missing evidence" not in reason for reason in reasons),
+        risk_level=risk,
+        auto_apply_eligible=auto_apply,
+        reasons=reasons,
+    )
+
+
+def _candidate_records(store: ContextStore, *, limit: int) -> list[dict[str, Any]]:
+    """Load high-value operational records for proposal generation."""
+    store.initialize()
+    role_rows: list[dict[str, Any]] = []
+    for role in PREFERRED_RECORD_ROLES:
+        result = store.query(
+            entity="records",
+            mode="list",
+            project_ids=None,
+            record_role=role,
+            status="active",
+            order_by="updated_at",
+            limit=max(1, limit // len(PREFERRED_RECORD_ROLES)),
+            include_total=False,
+        )
+        role_rows.extend(result.get("rows") or [])
+    if len(role_rows) >= limit:
+        return role_rows[:limit]
+    result = store.query(
+        entity="records",
+        mode="list",
+        project_ids=None,
+        status="active",
+        order_by="updated_at",
+        limit=limit - len(role_rows),
+        include_total=False,
+    )
+    seen = {row.get("record_id") for row in role_rows}
+    return role_rows + [row for row in result.get("rows") or [] if row.get("record_id") not in seen]
+
+
+def hydrate_patch_text(*, base: Path, draft: SkillProposalDraft) -> SkillProposalDraft:
+    """Attach before_text and unified diffs to model patches."""
+    patches: list[SkillPatch] = []
+    for patch in draft.patches:
+        before = ""
+        try:
+            before = read_target_text(base, patch.relative_path)
+        except FileNotFoundError:
+            before = ""
+        patches.append(
+            patch.model_copy(
+                update={
+                    "before_text": before,
+                    "diff_text": _diff_text(
+                        relative_path=patch.relative_path,
+                        before=before,
+                        after=patch.after_text,
+                    ),
+                }
+            )
+        )
+    return draft.model_copy(update={"patches": patches})
+
+
+def _diff_text(*, relative_path: str, before: str, after: str) -> str:
+    """Render a unified diff for UI and CLI review."""
+    return "".join(
+        difflib.unified_diff(
+            before.splitlines(keepends=True),
+            after.splitlines(keepends=True),
+            fromfile=f"a/{relative_path}",
+            tofile=f"b/{relative_path}",
+        )
+    )
+
+
+def _validate_compile_result(result: Any) -> str | None:
+    """Return a validation error string when model output is incomplete."""
+    payload = prediction_payload(result, output_field="proposal")
+    try:
+        SkillProposalDraft.model_validate(payload)
+    except Exception as exc:
+        return str(exc)
+    return None
+
+
+def _highest_risk(values: list[str]) -> str:
+    """Return the highest risk level from a list."""
+    order = {"low": 0, "medium": 1, "high": 2}
+    return max(values, key=lambda value: order.get(str(value), 0))
+
+
+def _should_auto_apply(update_mode: str, policy: AutoApplyPolicy, proposal: SkillProposal) -> bool:
+    """Return whether a persisted proposal should be auto-applied."""
+    validation_ok = bool(proposal.validation_json.get("ok"))
+    return (
+        update_mode == "auto_apply"
+        and policy.enabled
+        and proposal.auto_apply_eligible
+        and (validation_ok or not policy.require_validation)
+    )
diff --git a/src/lerim/skill_stewardship/repository.py b/src/lerim/skill_stewardship/repository.py
new file mode 100644
index 00000000..8faab558
--- /dev/null
+++ b/src/lerim/skill_stewardship/repository.py
@@ -0,0 +1,616 @@
+"""SQLite persistence for registered instruction targets and proposals."""
+
+from __future__ import annotations
+
+import json
+import sqlite3
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from lerim.context import ContextStore
+from lerim.skill_stewardship.schemas import (
+    ArtifactManifest,
+    AutoApplyPolicy,
+    InstructionTarget,
+    ProposalGuardResult,
+    SkillProposal,
+    SkillProposalDraft,
+    TargetFile,
+    ValidationResult,
+)
+
+
+def utc_now() -> str:
+    """Return an ISO UTC timestamp."""
+    return datetime.now(timezone.utc).isoformat()
+
+
+def new_id(prefix: str) -> str:
+    """Create a short prefixed identifier."""
+    return f"{prefix}_{uuid.uuid4().hex[:12]}"
+
+
+class SkillStewardshipRepository:
+    """Persist instruction targets, scans, runs, signals, and proposals."""
+
+    def __init__(self, context_store: ContextStore) -> None:
+        """Create a repository backed by Lerim's canonical context store."""
+        self.context_store = context_store
+
+    def initialize(self) -> None:
+        """Create stewardship tables and indexes."""
+        self.context_store.initialize()
+        with self.context_store.connect() as conn:
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS instruction_targets (
+                    target_id TEXT PRIMARY KEY,
+                    name TEXT NOT NULL,
+                    description TEXT,
+                    path TEXT NOT NULL UNIQUE,
+                    target_type TEXT NOT NULL,
+                    entry_file TEXT NOT NULL,
+                    scope_type TEXT NOT NULL DEFAULT 'global',
+                    scope_id TEXT,
+                    update_mode TEXT NOT NULL DEFAULT 'review',
+                    auto_apply_policy_json TEXT NOT NULL DEFAULT '{}',
+                    manifest_json TEXT NOT NULL DEFAULT '{}',
+                    status TEXT NOT NULL DEFAULT 'active',
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_target_files (
+                    file_id TEXT PRIMARY KEY,
+                    target_id TEXT NOT NULL,
+                    relative_path TEXT NOT NULL,
+                    file_role TEXT NOT NULL,
+                    size_bytes INTEGER NOT NULL,
+                    sha256 TEXT NOT NULL,
+                    risk_surface TEXT NOT NULL,
+                    text_preview TEXT,
+                    last_seen_at TEXT NOT NULL,
+                    FOREIGN KEY(target_id) REFERENCES instruction_targets(target_id),
+                    UNIQUE(target_id, relative_path)
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_update_runs (
+                    run_id TEXT PRIMARY KEY,
+                    target_id TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    started_at TEXT NOT NULL,
+                    finished_at TEXT,
+                    records_scanned INTEGER NOT NULL DEFAULT 0,
+                    signals_created INTEGER NOT NULL DEFAULT 0,
+                    proposals_created INTEGER NOT NULL DEFAULT 0,
+                    proposals_applied INTEGER NOT NULL DEFAULT 0,
+                    error TEXT,
+                    FOREIGN KEY(target_id) REFERENCES instruction_targets(target_id)
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_signals (
+                    signal_id TEXT PRIMARY KEY,
+                    run_id TEXT NOT NULL,
+                    target_id TEXT NOT NULL,
+                    record_id TEXT NOT NULL,
+                    version_id TEXT,
+                    signal_type TEXT NOT NULL,
+                    strength REAL NOT NULL,
+                    rationale TEXT NOT NULL,
+                    status TEXT NOT NULL DEFAULT 'new',
+                    created_at TEXT NOT NULL,
+                    FOREIGN KEY(target_id) REFERENCES instruction_targets(target_id),
+                    FOREIGN KEY(run_id) REFERENCES instruction_update_runs(run_id)
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_update_proposals (
+                    proposal_id TEXT PRIMARY KEY,
+                    run_id TEXT,
+                    target_id TEXT NOT NULL,
+                    title TEXT NOT NULL,
+                    summary TEXT NOT NULL,
+                    risk_level TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    patch_json TEXT NOT NULL,
+                    validation_json TEXT NOT NULL,
+                    guard_json TEXT NOT NULL,
+                    auto_apply_eligible INTEGER NOT NULL DEFAULT 0,
+                    created_at TEXT NOT NULL,
+                    updated_at TEXT NOT NULL,
+                    FOREIGN KEY(target_id) REFERENCES instruction_targets(target_id),
+                    FOREIGN KEY(run_id) REFERENCES instruction_update_runs(run_id)
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_proposal_records (
+                    proposal_id TEXT NOT NULL,
+                    record_id TEXT NOT NULL,
+                    version_id TEXT,
+                    PRIMARY KEY(proposal_id, record_id, version_id),
+                    FOREIGN KEY(proposal_id) REFERENCES instruction_update_proposals(proposal_id)
+                );
+
+                CREATE TABLE IF NOT EXISTS instruction_versions (
+                    version_id TEXT PRIMARY KEY,
+                    target_id TEXT NOT NULL,
+                    proposal_id TEXT,
+                    relative_path TEXT NOT NULL,
+                    before_hash TEXT,
+                    after_hash TEXT,
+                    snapshot_path TEXT,
+                    applied_at TEXT NOT NULL,
+                    applied_by TEXT NOT NULL,
+                    FOREIGN KEY(target_id) REFERENCES instruction_targets(target_id),
+                    FOREIGN KEY(proposal_id) REFERENCES instruction_update_proposals(proposal_id)
+                );
+
+                CREATE INDEX IF NOT EXISTS idx_instruction_targets_status ON instruction_targets(status);
+                CREATE INDEX IF NOT EXISTS idx_instruction_proposals_status ON instruction_update_proposals(status);
+                CREATE INDEX IF NOT EXISTS idx_instruction_proposals_target ON instruction_update_proposals(target_id);
+                CREATE INDEX IF NOT EXISTS idx_instruction_runs_target ON instruction_update_runs(target_id);
+                """
+            )
+
+    def upsert_target(
+        self,
+        *,
+        name: str,
+        path: Path,
+        description: str | None,
+        manifest: ArtifactManifest,
+        files: list[TargetFile],
+        update_mode: str = "review",
+        auto_apply_policy: AutoApplyPolicy | None = None,
+    ) -> InstructionTarget:
+        """Create or update a registered instruction target from a fresh scan."""
+        self.initialize()
+        now = utc_now()
+        policy = auto_apply_policy or AutoApplyPolicy()
+        with self.context_store.connect() as conn:
+            existing = conn.execute(
+                "SELECT target_id, created_at FROM instruction_targets WHERE path = ?",
+                (str(path),),
+            ).fetchone()
+            target_id = str(existing["target_id"]) if existing else new_id("it")
+            created_at = str(existing["created_at"]) if existing else now
+            conn.execute(
+                """
+                INSERT INTO instruction_targets(
+                    target_id, name, description, path, target_type, entry_file,
+                    scope_type, scope_id, update_mode, auto_apply_policy_json,
+                    manifest_json, status, created_at, updated_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, 'global', NULL, ?, ?, ?, 'active', ?, ?)
+                ON CONFLICT(path) DO UPDATE SET
+                    name=excluded.name,
+                    description=excluded.description,
+                    target_type=excluded.target_type,
+                    entry_file=excluded.entry_file,
+                    update_mode=excluded.update_mode,
+                    auto_apply_policy_json=excluded.auto_apply_policy_json,
+                    manifest_json=excluded.manifest_json,
+                    status='active',
+                    updated_at=excluded.updated_at
+                """,
+                (
+                    target_id,
+                    name,
+                    description,
+                    str(path),
+                    manifest.target_type,
+                    manifest.entry_file,
+                    update_mode,
+                    policy.model_dump_json(),
+                    manifest.model_dump_json(),
+                    created_at,
+                    now,
+                ),
+            )
+            self._replace_files(conn, target_id=target_id, files=files, seen_at=now)
+        return self.get_target(target_id)
+
+    def list_targets(self, *, include_archived: bool = False) -> list[InstructionTarget]:
+        """Return registered instruction targets."""
+        self.initialize()
+        where = "1=1" if include_archived else "status != 'archived'"
+        with self.context_store.connect() as conn:
+            rows = conn.execute(
+                f"SELECT * FROM instruction_targets WHERE {where} ORDER BY updated_at DESC"
+            ).fetchall()
+        return [self._target_from_row(row) for row in rows]
+
+    def get_target(self, target_id_or_name: str) -> InstructionTarget:
+        """Load one target by id or name."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            row = conn.execute(
+                """
+                SELECT * FROM instruction_targets
+                WHERE target_id = ? OR name = ?
+                ORDER BY updated_at DESC
+                LIMIT 1
+                """,
+                (target_id_or_name, target_id_or_name),
+            ).fetchone()
+        if row is None:
+            raise KeyError(f"instruction target not found: {target_id_or_name}")
+        return self._target_from_row(row)
+
+    def target_files(self, target_id: str) -> list[TargetFile]:
+        """Return the latest scanned files for a target."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT * FROM instruction_target_files
+                WHERE target_id = ?
+                ORDER BY relative_path ASC
+                """,
+                (target_id,),
+            ).fetchall()
+        return [self._file_from_row(row) for row in rows]
+
+    def update_target_mode(self, target_id_or_name: str, update_mode: str, policy: AutoApplyPolicy | None = None) -> InstructionTarget:
+        """Update review or auto-apply behavior for a target."""
+        target = self.get_target(target_id_or_name)
+        effective_policy = policy or target.auto_apply_policy
+        now = utc_now()
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                UPDATE instruction_targets
+                SET update_mode = ?, auto_apply_policy_json = ?, updated_at = ?
+                WHERE target_id = ?
+                """,
+                (update_mode, effective_policy.model_dump_json(), now, target.target_id),
+            )
+        return self.get_target(target.target_id)
+
+    def create_run(self, target_id: str) -> str:
+        """Create a stewardship run row and return its id."""
+        self.initialize()
+        run_id = new_id("sir")
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO instruction_update_runs(run_id, target_id, status, started_at)
+                VALUES (?, ?, 'running', ?)
+                """,
+                (run_id, target_id, utc_now()),
+            )
+        return run_id
+
+    def finish_run(
+        self,
+        *,
+        run_id: str,
+        status: str,
+        records_scanned: int,
+        signals_created: int,
+        proposals_created: int,
+        proposals_applied: int = 0,
+        error: str | None = None,
+    ) -> None:
+        """Persist final run counters."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                UPDATE instruction_update_runs
+                SET status = ?, finished_at = ?, records_scanned = ?, signals_created = ?,
+                    proposals_created = ?, proposals_applied = ?, error = ?
+                WHERE run_id = ?
+                """,
+                (
+                    status,
+                    utc_now(),
+                    records_scanned,
+                    signals_created,
+                    proposals_created,
+                    proposals_applied,
+                    error,
+                    run_id,
+                ),
+            )
+
+    def save_proposal(
+        self,
+        *,
+        run_id: str,
+        target_id: str,
+        draft: SkillProposalDraft,
+        guard: ProposalGuardResult,
+        validation: ValidationResult,
+        status: str,
+    ) -> SkillProposal:
+        """Persist one guarded proposal and its evidence links."""
+        self.initialize()
+        now = utc_now()
+        proposal_id = new_id("ip")
+        evidence_ids = sorted({record_id for patch in draft.patches for record_id in patch.evidence_record_ids})
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO instruction_update_proposals(
+                    proposal_id, run_id, target_id, title, summary, risk_level, status,
+                    patch_json, validation_json, guard_json, auto_apply_eligible,
+                    created_at, updated_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    proposal_id,
+                    run_id,
+                    target_id,
+                    draft.title,
+                    draft.summary,
+                    guard.risk_level,
+                    status,
+                    draft.model_dump_json(),
+                    validation.model_dump_json(),
+                    guard.model_dump_json(),
+                    1 if guard.auto_apply_eligible else 0,
+                    now,
+                    now,
+                ),
+            )
+            for record_id in evidence_ids:
+                conn.execute(
+                    """
+                    INSERT OR IGNORE INTO instruction_proposal_records(proposal_id, record_id, version_id)
+                    VALUES (?, ?, '')
+                    """,
+                    (proposal_id, record_id),
+                )
+        return self.get_proposal(proposal_id)
+
+    def save_signals(
+        self,
+        *,
+        run_id: str,
+        target_id: str,
+        draft: SkillProposalDraft,
+    ) -> int:
+        """Persist proposal signals and return the number saved."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            for signal in draft.signals:
+                conn.execute(
+                    """
+                    INSERT INTO instruction_signals(
+                        signal_id, run_id, target_id, record_id, version_id,
+                        signal_type, strength, rationale, status, created_at
+                    )
+                    VALUES (?, ?, ?, ?, ?, ?, ?, ?, 'new', ?)
+                    """,
+                    (
+                        new_id("is"),
+                        run_id,
+                        target_id,
+                        signal.record_id,
+                        signal.version_id,
+                        signal.signal_type,
+                        signal.strength,
+                        signal.rationale,
+                        utc_now(),
+                    ),
+                )
+        return len(draft.signals)
+
+    def list_proposals(self, *, target_id: str | None = None, status: str | None = None) -> list[SkillProposal]:
+        """Return proposals, optionally filtered by target and status."""
+        self.initialize()
+        clauses = ["1=1"]
+        params: list[Any] = []
+        if target_id:
+            clauses.append("target_id = ?")
+            params.append(target_id)
+        if status:
+            clauses.append("status = ?")
+            params.append(status)
+        with self.context_store.connect() as conn:
+            rows = conn.execute(
+                f"""
+                SELECT * FROM instruction_update_proposals
+                WHERE {' AND '.join(clauses)}
+                ORDER BY updated_at DESC
+                """,
+                tuple(params),
+            ).fetchall()
+        return [self._proposal_from_row(row) for row in rows]
+
+    def get_proposal(self, proposal_id: str) -> SkillProposal:
+        """Load one persisted proposal."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            row = conn.execute(
+                "SELECT * FROM instruction_update_proposals WHERE proposal_id = ?",
+                (proposal_id,),
+            ).fetchone()
+        if row is None:
+            raise KeyError(f"instruction proposal not found: {proposal_id}")
+        return self._proposal_from_row(row)
+
+    def set_proposal_status(self, proposal_id: str, status: str) -> SkillProposal:
+        """Move a proposal through the review lifecycle."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                UPDATE instruction_update_proposals
+                SET status = ?, updated_at = ?
+                WHERE proposal_id = ?
+                """,
+                (status, utc_now(), proposal_id),
+            )
+        return self.get_proposal(proposal_id)
+
+    def update_proposal_patch(
+        self,
+        *,
+        proposal_id: str,
+        draft: SkillProposalDraft,
+        validation: ValidationResult,
+        guard: ProposalGuardResult,
+    ) -> SkillProposal:
+        """Replace a proposal patch after user editing and validation."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                UPDATE instruction_update_proposals
+                SET patch_json = ?, validation_json = ?, guard_json = ?,
+                    risk_level = ?, auto_apply_eligible = ?, status = 'pending_review',
+                    updated_at = ?
+                WHERE proposal_id = ?
+                """,
+                (
+                    draft.model_dump_json(),
+                    validation.model_dump_json(),
+                    guard.model_dump_json(),
+                    guard.risk_level,
+                    1 if guard.auto_apply_eligible else 0,
+                    utc_now(),
+                    proposal_id,
+                ),
+            )
+        return self.get_proposal(proposal_id)
+
+    def save_applied_version(
+        self,
+        *,
+        target_id: str,
+        proposal_id: str,
+        relative_path: str,
+        before_hash: str | None,
+        after_hash: str | None,
+        snapshot_path: str | None,
+        applied_by: str,
+    ) -> None:
+        """Record an applied file version."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO instruction_versions(
+                    version_id, target_id, proposal_id, relative_path, before_hash,
+                    after_hash, snapshot_path, applied_at, applied_by
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                """,
+                (
+                    new_id("iv"),
+                    target_id,
+                    proposal_id,
+                    relative_path,
+                    before_hash,
+                    after_hash,
+                    snapshot_path,
+                    utc_now(),
+                    applied_by,
+                ),
+            )
+
+    def recent_runs(self, *, limit: int = 20) -> list[dict[str, Any]]:
+        """Return recent stewardship runs as dictionaries."""
+        self.initialize()
+        with self.context_store.connect() as conn:
+            rows = conn.execute(
+                """
+                SELECT r.*, t.name AS target_name
+                FROM instruction_update_runs r
+                JOIN instruction_targets t ON t.target_id = r.target_id
+                ORDER BY r.started_at DESC
+                LIMIT ?
+                """,
+                (max(1, int(limit)),),
+            ).fetchall()
+        return [dict(row) for row in rows]
+
+    def _replace_files(
+        self,
+        conn: sqlite3.Connection,
+        *,
+        target_id: str,
+        files: list[TargetFile],
+        seen_at: str,
+    ) -> None:
+        """Refresh target file rows after a scan."""
+        for file_info in files:
+            conn.execute(
+                """
+                INSERT INTO instruction_target_files(
+                    file_id, target_id, relative_path, file_role, size_bytes,
+                    sha256, risk_surface, text_preview, last_seen_at
+                )
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(target_id, relative_path) DO UPDATE SET
+                    file_role=excluded.file_role,
+                    size_bytes=excluded.size_bytes,
+                    sha256=excluded.sha256,
+                    risk_surface=excluded.risk_surface,
+                    text_preview=excluded.text_preview,
+                    last_seen_at=excluded.last_seen_at
+                """,
+                (
+                    new_id("itf"),
+                    target_id,
+                    file_info.relative_path,
+                    file_info.file_role,
+                    file_info.size_bytes,
+                    file_info.sha256,
+                    file_info.risk_surface,
+                    file_info.text_preview,
+                    seen_at,
+                ),
+            )
+
+    def _target_from_row(self, row: sqlite3.Row) -> InstructionTarget:
+        """Convert one target row into a typed model."""
+        policy_raw = json.loads(str(row["auto_apply_policy_json"] or "{}"))
+        manifest_raw = json.loads(str(row["manifest_json"] or "{}"))
+        return InstructionTarget(
+            target_id=str(row["target_id"]),
+            name=str(row["name"]),
+            description=row["description"],
+            path=str(row["path"]),
+            target_type=str(row["target_type"]),
+            entry_file=str(row["entry_file"]),
+            scope_type=str(row["scope_type"] or "global"),
+            scope_id=row["scope_id"],
+            update_mode=str(row["update_mode"] or "review"),
+            auto_apply_policy=AutoApplyPolicy.model_validate(policy_raw),
+            status=str(row["status"] or "active"),
+            manifest=ArtifactManifest.model_validate(manifest_raw) if manifest_raw else None,
+            created_at=str(row["created_at"]),
+            updated_at=str(row["updated_at"]),
+        )
+
+    def _file_from_row(self, row: sqlite3.Row) -> TargetFile:
+        """Convert one file row into a typed model."""
+        return TargetFile(
+            relative_path=str(row["relative_path"]),
+            file_role=str(row["file_role"]),
+            size_bytes=int(row["size_bytes"]),
+            sha256=str(row["sha256"]),
+            text_preview=row["text_preview"],
+            risk_surface=str(row["risk_surface"] or "low"),
+        )
+
+    def _proposal_from_row(self, row: sqlite3.Row) -> SkillProposal:
+        """Convert one proposal row into a typed model."""
+        return SkillProposal(
+            proposal_id=str(row["proposal_id"]),
+            target_id=str(row["target_id"]),
+            title=str(row["title"]),
+            summary=str(row["summary"]),
+            risk_level=str(row["risk_level"]),
+            status=str(row["status"]),
+            patch_json=json.loads(str(row["patch_json"] or "{}")),
+            validation_json=json.loads(str(row["validation_json"] or "{}")),
+            guard_json=json.loads(str(row["guard_json"] or "{}")),
+            auto_apply_eligible=bool(row["auto_apply_eligible"]),
+            created_at=str(row["created_at"]),
+            updated_at=str(row["updated_at"]),
+        )
diff --git a/src/lerim/skill_stewardship/schemas.py b/src/lerim/skill_stewardship/schemas.py
new file mode 100644
index 00000000..07d17cea
--- /dev/null
+++ b/src/lerim/skill_stewardship/schemas.py
@@ -0,0 +1,173 @@
+"""Typed contracts for skill stewardship targets, scans, and proposals."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+TargetType = Literal[
+    "codex_skill",
+    "claude_skill",
+    "agent_skill",
+    "agents_md",
+    "gemini_context",
+    "cline_rules",
+    "cursor_rules",
+    "opencode_rules",
+    "generic_markdown_bundle",
+]
+TargetStatus = Literal["active", "paused", "archived"]
+UpdateMode = Literal["review", "auto_apply", "paused"]
+ProposalStatus = Literal[
+    "draft",
+    "pending_review",
+    "approved",
+    "applied",
+    "rejected",
+    "superseded",
+    "failed_validation",
+]
+RiskLevel = Literal["low", "medium", "high"]
+SignalType = Literal[
+    "procedure_addition",
+    "procedure_refinement",
+    "guardrail_addition",
+    "anti_pattern",
+    "validator_addition",
+    "example_addition",
+    "reference_addition",
+    "trigger_refinement",
+    "stale_instruction",
+    "conflict_detected",
+]
+
+
+class AutoApplyPolicy(BaseModel):
+    """Target-level limits for automatic application."""
+
+    enabled: bool = False
+    max_risk: RiskLevel = "low"
+    allow_entry_file_body: bool = True
+    allow_frontmatter: bool = False
+    allow_new_reference_files: bool = True
+    allow_scripts: bool = False
+    allow_assets: bool = False
+    allow_config_files: bool = False
+    max_changed_files: int = 2
+    max_added_lines: int = 40
+    require_validation: bool = True
+
+
+class TargetFile(BaseModel):
+    """One file that belongs to a registered instruction target."""
+
+    relative_path: str
+    file_role: str
+    size_bytes: int
+    sha256: str
+    text_preview: str | None = None
+    tracked: bool = True
+    risk_surface: RiskLevel = "low"
+
+
+class ArtifactManifest(BaseModel):
+    """Detected instruction artifact shape and update boundaries."""
+
+    target_type: TargetType
+    entry_file: str
+    instruction_files: list[str] = Field(default_factory=list)
+    supporting_files: list[str] = Field(default_factory=list)
+    required_frontmatter: list[str] = Field(default_factory=list)
+    known_frontmatter: list[str] = Field(default_factory=list)
+    allowed_update_surfaces: list[str] = Field(default_factory=list)
+    high_risk_surfaces: list[str] = Field(default_factory=list)
+    notes: list[str] = Field(default_factory=list)
+
+
+class InstructionTarget(BaseModel):
+    """A user-registered skill or instruction artifact Lerim may improve."""
+
+    target_id: str
+    name: str
+    description: str | None = None
+    path: str
+    target_type: TargetType
+    entry_file: str
+    scope_type: str = "global"
+    scope_id: str | None = None
+    update_mode: UpdateMode = "review"
+    auto_apply_policy: AutoApplyPolicy = Field(default_factory=AutoApplyPolicy)
+    status: TargetStatus = "active"
+    manifest: ArtifactManifest | None = None
+    created_at: str | None = None
+    updated_at: str | None = None
+
+
+class SkillSignal(BaseModel):
+    """Evidence that a record may imply an update to a registered target."""
+
+    record_id: str
+    version_id: str | None = None
+    signal_type: SignalType
+    strength: float = Field(ge=0.0, le=1.0)
+    rationale: str
+
+
+class SkillPatch(BaseModel):
+    """One proposed file edit."""
+
+    relative_path: str
+    change_type: Literal["modify", "create"]
+    risk: RiskLevel
+    rationale: str
+    evidence_record_ids: list[str] = Field(default_factory=list)
+    before_text: str | None = None
+    after_text: str
+    diff_text: str
+
+
+class SkillProposalDraft(BaseModel):
+    """Model-authored proposal before persistence."""
+
+    title: str
+    summary: str
+    risk_level: RiskLevel
+    signals: list[SkillSignal] = Field(default_factory=list)
+    patches: list[SkillPatch] = Field(default_factory=list)
+    auto_apply_eligible: bool = False
+
+
+class ProposalGuardResult(BaseModel):
+    """Safety and quality review for a proposal."""
+
+    accepted: bool
+    risk_level: RiskLevel
+    auto_apply_eligible: bool
+    reasons: list[str] = Field(default_factory=list)
+
+
+class ValidationResult(BaseModel):
+    """Deterministic validation result for one proposal."""
+
+    ok: bool
+    checks: list[str] = Field(default_factory=list)
+    errors: list[str] = Field(default_factory=list)
+
+
+class SkillProposal(BaseModel):
+    """Persisted skill update proposal."""
+
+    proposal_id: str
+    target_id: str
+    title: str
+    summary: str
+    risk_level: RiskLevel
+    status: ProposalStatus
+    patch_json: dict[str, Any]
+    validation_json: dict[str, Any]
+    guard_json: dict[str, Any]
+    auto_apply_eligible: bool
+    created_at: str
+    updated_at: str
diff --git a/src/lerim/skill_stewardship/signatures.py b/src/lerim/skill_stewardship/signatures.py
new file mode 100644
index 00000000..9958b9da
--- /dev/null
+++ b/src/lerim/skill_stewardship/signatures.py
@@ -0,0 +1,32 @@
+"""DSPy signatures for evidence-backed instruction artifact updates."""
+
+from __future__ import annotations
+
+from lerim.agents.dspy_compat import dspy
+from lerim.skill_stewardship.schemas import SkillProposalDraft
+
+
+class CompileSkillUpdateProposal(dspy.Signature):
+    """Compile one small, evidence-backed update proposal for a registered instruction artifact.
+
+    Return only structured output. Do not include hidden reasoning, markdown outside fields, or prose.
+
+    Rules:
+    - Use only the supplied durable records as evidence.
+    - Propose no update when evidence is weak, one-off, private, or unrelated to the target.
+    - Respect the artifact manifest exactly. Do not invent unsupported files or directories.
+    - Every patch must cite at least one exact record_id in evidence_record_ids.
+    - Prefer small edits that improve future agent behavior.
+    - Preserve existing skill semantics unless the evidence clearly supports changing them.
+    - Do not add scripts, assets, permissions, MCP config, hooks, or tool allowlists unless the manifest and user policy explicitly allow them.
+    - Treat entry-file frontmatter and trigger descriptions as high risk.
+    - Keep SKILL.md and instruction entry files concise; place longer reusable details into supported reference files.
+    - If no proposal is warranted, return an empty patches list with a short summary explaining abstention.
+    """
+
+    target_json: str = dspy.InputField(desc="REGISTERED TARGET JSON")
+    manifest_json: str = dspy.InputField(desc="ARTIFACT MANIFEST JSON")
+    files_json: str = dspy.InputField(desc="CURRENT TARGET FILES JSON")
+    records_json: str = dspy.InputField(desc="CANDIDATE EVIDENCE RECORDS JSON")
+    proposal: SkillProposalDraft = dspy.OutputField(desc="Evidence-backed update proposal")
+
diff --git a/src/lerim/skill_stewardship/validation.py b/src/lerim/skill_stewardship/validation.py
new file mode 100644
index 00000000..e58d09d6
--- /dev/null
+++ b/src/lerim/skill_stewardship/validation.py
@@ -0,0 +1,83 @@
+"""Deterministic validation for proposed instruction artifact patches."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import yaml
+
+from lerim.skill_stewardship.schemas import ArtifactManifest, SkillProposalDraft, ValidationResult
+
+
+def validate_proposal(
+    *,
+    base_path: Path,
+    manifest: ArtifactManifest,
+    proposal: SkillProposalDraft,
+) -> ValidationResult:
+    """Validate proposal shape, paths, frontmatter, and artifact constraints."""
+    checks: list[str] = []
+    errors: list[str] = []
+    base = base_path.resolve()
+    changed_files = {patch.relative_path for patch in proposal.patches}
+    if not proposal.patches:
+        return ValidationResult(ok=True, checks=["abstained_no_patch"], errors=[])
+    checks.append("has_patch")
+    for patch in proposal.patches:
+        _validate_patch_path(base, patch.relative_path, errors)
+        if not patch.evidence_record_ids:
+            errors.append(f"{patch.relative_path}: missing evidence_record_ids")
+        if patch.change_type == "create" and not _new_file_allowed(manifest, patch.relative_path):
+            errors.append(f"{patch.relative_path}: new file is not allowed for {manifest.target_type}")
+        if patch.relative_path == manifest.entry_file:
+            if str(patch.before_text or "").startswith("---\n") and not patch.after_text.startswith("---\n"):
+                errors.append(f"{manifest.entry_file}: must preserve existing YAML frontmatter")
+            _validate_entry_text(manifest, patch.after_text, errors)
+    if len(changed_files) <= 3:
+        checks.append("bounded_changed_files")
+    else:
+        errors.append("proposal changes too many files for one review")
+    return ValidationResult(ok=not errors, checks=checks, errors=errors)
+
+
+def _validate_patch_path(base: Path, relative_path: str, errors: list[str]) -> None:
+    """Reject absolute paths and path traversal."""
+    path = Path(relative_path)
+    if path.is_absolute():
+        errors.append(f"{relative_path}: absolute paths are not allowed")
+        return
+    resolved = (base / path).resolve()
+    if base != resolved and base not in resolved.parents:
+        errors.append(f"{relative_path}: path escapes target")
+
+
+def _validate_entry_text(manifest: ArtifactManifest, text: str, errors: list[str]) -> None:
+    """Check required frontmatter for entry-file edits."""
+    if not manifest.required_frontmatter:
+        return
+    if not text.startswith("---\n"):
+        errors.append(f"{manifest.entry_file}: missing YAML frontmatter")
+        return
+    end = text.find("\n---", 4)
+    if end < 0:
+        errors.append(f"{manifest.entry_file}: unterminated YAML frontmatter")
+        return
+    parsed = yaml.safe_load(text[4:end]) or {}
+    if not isinstance(parsed, dict):
+        errors.append(f"{manifest.entry_file}: frontmatter must be a mapping")
+        return
+    for key in manifest.required_frontmatter:
+        if not str(parsed.get(key) or "").strip():
+            errors.append(f"{manifest.entry_file}: missing required frontmatter field {key}")
+
+
+def _new_file_allowed(manifest: ArtifactManifest, relative_path: str) -> bool:
+    """Return whether a target type supports creating this file."""
+    first = Path(relative_path).parts[0] if Path(relative_path).parts else ""
+    if manifest.target_type in {"codex_skill", "claude_skill", "agent_skill"}:
+        return first in {"references", "reference", "examples"}
+    if manifest.target_type == "cline_rules":
+        return relative_path.endswith((".md", ".txt"))
+    if manifest.target_type == "gemini_context":
+        return relative_path.endswith((".md", ".txt"))
+    return relative_path in manifest.instruction_files
diff --git a/tests/unit/agents/trace_ingestion/test_persistence.py b/tests/unit/agents/trace_ingestion/test_persistence.py
index ede0f425..525a06b6 100644
--- a/tests/unit/agents/trace_ingestion/test_persistence.py
+++ b/tests/unit/agents/trace_ingestion/test_persistence.py
@@ -174,3 +174,35 @@ def test_model_completion_summary_is_not_persisted(tmp_path) -> None:
     assert summary == "Trace ingestion completed: 1 durable record created."
     assert observations[-1]["content"] == summary
     assert "CSS" not in summary
+
+
+def test_persists_operational_role_metadata(tmp_path) -> None:
+    """Durable record role annotations are saved with the canonical record."""
+    ctx = _context(tmp_path)
+    prepare_context_store(ctx)
+    payload = _synthesized_payload()
+    payload["durable_records"][0]["record_role"] = "gotcha"
+    payload["durable_records"][0]["role_payload"] = {
+        "condition": "Replaying an already-ingested trace.",
+        "symptom": "The episode already exists.",
+        "avoid": "Do not create duplicate episode records.",
+        "recover": "Treat duplicate episodes as idempotent replays.",
+    }
+
+    observations, done, _summary = persist_synthesized_extraction(payload, ctx)
+
+    store = ContextStore(ctx.context_db_path)
+    rows = store.query(
+        entity="records",
+        mode="list",
+        project_ids=[ctx.project_identity.project_id],
+        record_role="gotcha",
+        limit=10,
+        include_archived=True,
+    )["rows"]
+
+    assert done is True
+    assert observations[1]["ok"] is True
+    assert len(rows) == 1
+    assert rows[0]["record_role"] == "gotcha"
+    assert "duplicate episode records" in rows[0]["role_payload"]
diff --git a/tests/unit/agents/trace_ingestion/test_pipeline.py b/tests/unit/agents/trace_ingestion/test_pipeline.py
index 524271a8..1ffcb8b7 100644
--- a/tests/unit/agents/trace_ingestion/test_pipeline.py
+++ b/tests/unit/agents/trace_ingestion/test_pipeline.py
@@ -35,6 +35,11 @@ def _pipeline_steps(steps):
         ),
         "retention": getattr(steps, "SelectCodingDurableRecords", _keep_all_records),
         "coding_polish": steps.PolishCodingEvalContextRecords,
+        "role_annotation": getattr(
+            steps,
+            "AnnotateOperationalRecordRoles",
+            _general_record_roles,
+        ),
     }
 
 
@@ -53,6 +58,17 @@ def _pass_through_records(**kwargs):
     return json.loads(kwargs["draft_records_json"])
 
 
+def _general_record_roles(**kwargs):
+    """Return general role annotations for every accepted durable record."""
+    records = json.loads(kwargs["durable_records_json"])
+    return {
+        "annotations": [
+            {"record_index": index, "record_role": "general", "role_payload": None}
+            for index, _record in enumerate(records)
+        ]
+    }
+
+
 class FakeModelSteps:
     """Model step double that exercises scan, filter, and synthesize phases."""
 
@@ -183,6 +199,24 @@ def ExtractCodingStrategySlots(self, **kwargs):
             "role_split_record": None,
         }
 
+    def AnnotateOperationalRecordRoles(self, **kwargs):
+        """Annotate the accepted record as a reusable extraction procedure."""
+        records = json.loads(kwargs["durable_records_json"])
+        assert records[0]["title"] == "Filter trace signal before synthesis"
+        return {
+            "annotations": [
+                {
+                    "record_index": 0,
+                    "record_role": "procedure",
+                    "role_payload": {
+                        "trigger": "Before writing durable records from a trace.",
+                        "steps": ["Filter durable signal before synthesis."],
+                        "checks": ["Reject local evidence."],
+                    },
+                }
+            ]
+        }
+
 
 class NoDurableFakeModelSteps:
     """Model step double for no-signal sessions with discarded source details."""
@@ -377,7 +411,7 @@ def test_trace_pipeline_filters_candidates_before_synthesis(tmp_path):
         trace_path=trace_path,
         config=make_config(tmp_path / ".lerim"),
         return_details=True,
-        max_llm_calls=5,
+        max_llm_calls=20,
         steps=_pipeline_steps(fake_runtime),
     )
 
@@ -390,6 +424,7 @@ def test_trace_pipeline_filters_candidates_before_synthesis(tmp_path):
         "synthesize_records",
         "guard_records",
         "polish_records",
+        "annotate_record_roles",
         "save_context",
         "save_context",
         "final_result",
@@ -405,6 +440,9 @@ def test_trace_pipeline_filters_candidates_before_synthesis(tmp_path):
         limit=10,
     )["rows"]
     assert sorted(row["kind"] for row in rows) == ["decision", "episode"]
+    decision = next(row for row in rows if row["kind"] == "decision")
+    assert decision["record_role"] == "procedure"
+    assert "Filter durable signal" in decision["role_payload"]
 
 
 def test_coding_fixture_slot_preserves_source_backed_body(tmp_path):
diff --git a/tests/unit/context/test_spec.py b/tests/unit/context/test_spec.py
index 4dd11c38..c20388e2 100644
--- a/tests/unit/context/test_spec.py
+++ b/tests/unit/context/test_spec.py
@@ -8,6 +8,7 @@
 from lerim.context.spec import (
     ALLOWED_CHANGE_KINDS,
     ALLOWED_KINDS,
+    ALLOWED_ROLES,
     ALLOWED_STATUSES,
     DURABLE_RECORD_KINDS,
     MAX_RECORD_TITLE_CHARS,
@@ -54,6 +55,7 @@ def test_allowed_value_tuples_follow_domain_enums():
     assert ALLOWED_KINDS == tuple(kind.value for kind in RecordKind)
     assert ALLOWED_STATUSES == tuple(status.value for status in RecordStatus)
     assert ALLOWED_CHANGE_KINDS == tuple(kind.value for kind in RecordChangeKind)
+    assert "procedure" in ALLOWED_ROLES
 
 
 def test_format_durable_record_kinds_is_human_readable():
@@ -141,3 +143,24 @@ def test_record_search_text_includes_typed_fields():
     assert "kind: decision" in text
     assert "decision: Use SQLite." in text
     assert "why: It keeps local context simple." in text
+
+
+def test_operational_role_payload_is_normalized_and_searchable():
+    payload = normalize_record_payload(
+        **_payload(
+            record_role="failure-mode",
+            role_payload={
+                "failure_step": "Trace replay",
+                "wrong_assumption": "Every replay can create a new episode.",
+                "correction": "Treat duplicate episodes as idempotent.",
+                "extra": "ignored",
+            },
+        )
+    )
+
+    text = record_search_text(payload)
+
+    assert payload["record_role"] == "failure_mode"
+    assert "extra" not in payload["role_payload"]
+    assert "role: failure_mode" in text
+    assert "wrong_assumption: Every replay can create a new episode." in text
diff --git a/tests/unit/context/test_store.py b/tests/unit/context/test_store.py
index d5d16c10..3ebc4f97 100644
--- a/tests/unit/context/test_store.py
+++ b/tests/unit/context/test_store.py
@@ -853,6 +853,27 @@ def test_create_record_preserves_source_evidence_refs(self, mock_seeded):
         assert rec["versions"][0]["source_event_refs"] == '["line:12","line:18"]'
         assert rec["versions"][0]["evidence_refs"] == '["Customer-provided cleaned trace"]'
 
+    def test_create_record_preserves_operational_role(self, mock_seeded):
+        store, pid = mock_seeded
+        rec = store.create_record(
+            project_id=pid,
+            session_id="sess_test",
+            kind="fact",
+            title="Replay duplicate episode gotcha",
+            body="Trace replay can encounter an existing episode.",
+            record_role="gotcha",
+            role_payload={
+                "condition": "Replaying an already-ingested trace.",
+                "symptom": "The episode already exists.",
+                "avoid": "Do not create duplicate episode records.",
+            },
+        )
+
+        assert rec["record_role"] == "gotcha"
+        assert "duplicate episode records" in rec["role_payload"]
+        assert rec["versions"][0]["record_role"] == "gotcha"
+        assert rec["versions"][0]["role_payload"] == rec["role_payload"]
+
     def test_create_episode(self, mock_seeded):
         store, pid = mock_seeded
         rec = _make_episode(store, pid)
@@ -1218,6 +1239,27 @@ def test_appends_version(self, mock_seeded):
         assert vs[1]["change_kind"] == "update"
         assert vs[1]["title"] == "V2 title"
 
+    def test_role_update_appends_version(self, mock_seeded):
+        store, pid = mock_seeded
+        rec = _make_decision(store, pid)
+
+        updated = store.update_record(
+            record_id=rec["record_id"],
+            session_id="sess_test",
+            project_ids=[pid],
+            changes={
+                "record_role": "procedure",
+                "role_payload": {
+                    "trigger": "Choosing the context store.",
+                    "steps": ["Use one SQLite database."],
+                },
+            },
+        )
+
+        assert updated["record_role"] == "procedure"
+        assert "Choosing the context store" in updated["role_payload"]
+        assert updated["versions"][0]["record_role"] == "procedure"
+
     def test_not_found_raises(self, mock_seeded):
         store, pid = mock_seeded
         with pytest.raises(ValueError, match="record_not_found"):
@@ -1648,6 +1690,36 @@ def test_kind_filter(self, mock_seeded):
         )
         assert all(r["kind"] == "decision" for r in result["rows"])
 
+    def test_record_role_filter(self, mock_seeded):
+        store, pid = mock_seeded
+        store.create_record(
+            project_id=pid,
+            session_id="sess_test",
+            kind="fact",
+            title="CLI gotcha",
+            body="The dashboard command may need the local backend.",
+            record_role="gotcha",
+            role_payload={"condition": "Launching the dashboard."},
+        )
+        _make_decision(store, pid)
+
+        listed = store.query(
+            entity="records",
+            mode="list",
+            project_ids=[pid],
+            record_role="gotcha",
+        )
+        versions = store.query(
+            entity="versions",
+            mode="list",
+            project_ids=[pid],
+            record_role="gotcha",
+            include_total=True,
+        )
+
+        assert [row["record_role"] for row in listed["rows"]] == ["gotcha"]
+        assert versions["total"] == 1
+
     def test_status_filter(self, mock_seeded):
         store, pid = mock_seeded
         rec = _make_decision(store, pid)
diff --git a/tests/unit/skill_stewardship/test_artifacts.py b/tests/unit/skill_stewardship/test_artifacts.py
new file mode 100644
index 00000000..a58a080d
--- /dev/null
+++ b/tests/unit/skill_stewardship/test_artifacts.py
@@ -0,0 +1,40 @@
+"""Tests for instruction artifact scanning."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from lerim.skill_stewardship.artifacts import scan_instruction_artifact
+
+
+def test_scans_codex_skill_manifest(tmp_path: Path) -> None:
+    """Codex-style skills expose SKILL.md plus standard support files."""
+    skill = tmp_path / ".agents" / "skills" / "clean-code"
+    (skill / "references").mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        "---\nname: clean-code\ndescription: Keep code simple.\n---\n\nUse small functions.\n",
+        encoding="utf-8",
+    )
+    (skill / "references" / "simplification.md").write_text("Avoid pass-through wrappers.\n", encoding="utf-8")
+
+    base, manifest, files = scan_instruction_artifact(skill)
+
+    assert base == skill
+    assert manifest.target_type == "codex_skill"
+    assert manifest.entry_file == "SKILL.md"
+    assert "name" in manifest.required_frontmatter
+    assert {item.relative_path for item in files} == {"SKILL.md", "references/simplification.md"}
+
+
+def test_scans_plain_agents_file(tmp_path: Path) -> None:
+    """A standalone AGENTS.md is treated as a plain instruction target."""
+    path = tmp_path / "AGENTS.md"
+    path.write_text("# Project Instructions\n\nRun tests before finishing.\n", encoding="utf-8")
+
+    base, manifest, files = scan_instruction_artifact(path)
+
+    assert base == tmp_path
+    assert manifest.target_type == "agents_md"
+    assert manifest.entry_file == "AGENTS.md"
+    assert files[0].relative_path == "AGENTS.md"
+
diff --git a/tests/unit/skill_stewardship/test_repository_and_pipeline.py b/tests/unit/skill_stewardship/test_repository_and_pipeline.py
new file mode 100644
index 00000000..42a1363c
--- /dev/null
+++ b/tests/unit/skill_stewardship/test_repository_and_pipeline.py
@@ -0,0 +1,141 @@
+"""Tests for skill stewardship persistence and deterministic guards."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from lerim.context import ContextStore
+from lerim.skill_stewardship.artifacts import scan_instruction_artifact
+from lerim.skill_stewardship.pipeline import guard_proposal, hydrate_patch_text
+from lerim.skill_stewardship.repository import SkillStewardshipRepository
+from lerim.skill_stewardship.schemas import AutoApplyPolicy, SkillPatch, SkillProposalDraft
+from lerim.skill_stewardship.validation import validate_proposal
+
+
+def test_repository_registers_target_and_files(tmp_path: Path) -> None:
+    """Target registration persists a manifest and tracked files."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+
+    target = repository.upsert_target(
+        name="demo",
+        path=base,
+        description="Improve demo",
+        manifest=manifest,
+        files=files,
+    )
+
+    assert repository.get_target(target.target_id).name == "demo"
+    assert repository.target_files(target.target_id)[0].relative_path == "SKILL.md"
+
+
+def test_guard_allows_low_risk_auto_apply_with_evidence() -> None:
+    """Low-risk bounded edits can become auto-apply eligible when policy allows it."""
+    draft = SkillProposalDraft(
+        title="Add simplification guard",
+        summary="Adds one reusable simplification reminder.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="references/simplification.md",
+                change_type="create",
+                risk="low",
+                rationale="Supported by repeated records.",
+                evidence_record_ids=["rec_123"],
+                after_text="Avoid pass-through wrappers that only call one function.\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = guard_proposal(draft=draft, policy=AutoApplyPolicy(enabled=True))
+
+    assert result.accepted is True
+    assert result.auto_apply_eligible is True
+
+
+def test_guard_blocks_missing_evidence() -> None:
+    """A patch without record evidence stays out of the review path."""
+    draft = SkillProposalDraft(
+        title="Unsupported change",
+        summary="No evidence.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Unsupported.",
+                evidence_record_ids=[],
+                after_text="text",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = guard_proposal(draft=draft, policy=AutoApplyPolicy(enabled=True))
+
+    assert result.accepted is False
+    assert result.auto_apply_eligible is False
+
+
+def test_validation_rejects_frontmatter_removal(tmp_path: Path) -> None:
+    """Entry file edits must preserve existing YAML frontmatter."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n", encoding="utf-8")
+    base, manifest, _files = scan_instruction_artifact(skill)
+    draft = SkillProposalDraft(
+        title="Bad edit",
+        summary="Drops metadata.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                before_text="---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n",
+                after_text="# Demo\n\nUpdated.\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+
+    assert result.ok is False
+    assert any("frontmatter" in error for error in result.errors)
+
+
+def test_hydrate_patch_text_recomputes_before_text_and_diff(tmp_path: Path) -> None:
+    """Edited proposals get fresh file content and unified diffs before validation."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("Use simple code.\n", encoding="utf-8")
+    draft = SkillProposalDraft(
+        title="Add wrapper guidance",
+        summary="Adds wrapper review guidance.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported by record.",
+                evidence_record_ids=["rec_1"],
+                after_text="Use simple code.\nRemove wrappers that only forward.\n",
+                diff_text="stale",
+            )
+        ],
+    )
+
+    hydrated = hydrate_patch_text(base=skill, draft=draft)
+
+    assert hydrated.patches[0].before_text == "Use simple code.\n"
+    assert "--- a/SKILL.md" in hydrated.patches[0].diff_text
+    assert "+Remove wrappers that only forward." in hydrated.patches[0].diff_text
diff --git a/tests/unit/test_context_brief.py b/tests/unit/test_context_brief.py
index 4f66eb4f..0e85260c 100644
--- a/tests/unit/test_context_brief.py
+++ b/tests/unit/test_context_brief.py
@@ -186,6 +186,7 @@ def test_context_brief_draft_has_fixed_sections_with_sections_fallback():
         "current_handoff",
         "decisions",
         "constraints_preferences",
+        "operational_context",
         "project_facts",
         "open_risks",
         "follow_up_queries",
@@ -276,6 +277,9 @@ def test_trim_context_brief_draft_keeps_startup_brief_compact():
         constraints_preferences=tuple(
             MemoryLine(f"Constraint {idx}", (f"rec_c{idx}",)) for idx in range(20)
         ),
+        operational_context=tuple(
+            MemoryLine(f"Workflow {idx}", (f"rec_o{idx}",)) for idx in range(20)
+        ),
         project_facts=tuple(MemoryLine(f"Fact {idx}", (f"rec_f{idx}",)) for idx in range(20)),
         sections=(
             MemorySection(
@@ -291,6 +295,7 @@ def test_trim_context_brief_draft_keeps_startup_brief_compact():
     assert len(trimmed.start_here) == 4
     assert len(trimmed.decisions) == 8
     assert len(trimmed.constraints_preferences) == 8
+    assert len(trimmed.operational_context) == 6
     assert len(trimmed.project_facts) == 6
     assert len(trimmed.sections[0].lines) == 6
 
@@ -311,6 +316,9 @@ def test_rendered_markdown_uses_fixed_section_order_and_sections_fallback(tmp_pa
         constraints_preferences=(
             MemoryLine("Respect the no-fallback rule", ("rec_constraint",)),
         ),
+        operational_context=(
+            MemoryLine("Rerun graph projection after changing graph payloads", ("rec_workflow",)),
+        ),
         project_facts=(MemoryLine("CLI code lives under src", ("rec_fact",)),),
         open_risks=(MemoryLine("Review queue still has risk", ("rec_risk",)),),
         follow_up_queries=(MemoryLine("Query the newest records", ("rec_query",)),),
@@ -334,6 +342,7 @@ def test_rendered_markdown_uses_fixed_section_order_and_sections_fallback(tmp_pa
             ("rec_handoff", "episode", "Resume the handoff"),
             ("rec_decision", "decision", "Keep SQLite canonical"),
             ("rec_constraint", "constraint", "Respect the no-fallback rule"),
+            ("rec_workflow", "fact", "Rerun graph projection after changing graph payloads"),
             ("rec_fact", "fact", "CLI code lives under src"),
             ("rec_risk", "episode", "Review queue still has risk"),
             ("rec_query", "fact", "Query the newest records"),
@@ -359,6 +368,7 @@ def test_rendered_markdown_uses_fixed_section_order_and_sections_fallback(tmp_pa
         "## Continuation Handoff",
         "## Decisions",
         "## Constraints & Preferences",
+        "## Reusable Workflows & Gotchas",
         "## Project Facts",
         "## Open Risks / Review Queue",
         "## Follow-up Queries",
@@ -367,6 +377,7 @@ def test_rendered_markdown_uses_fixed_section_order_and_sections_fallback(tmp_pa
     ]
     positions = [_markdown_heading_index(markdown, heading) for heading in headings]
     assert positions == sorted(positions)
+    assert "Rerun graph projection after changing graph payloads [rec_workflow]" in markdown
     assert "Render older agent sections last [rec_legacy]" in markdown
 
 
@@ -408,6 +419,7 @@ def test_rendered_markdown_contains_freshness_and_citations(tmp_path):
             {
                 "record_id": "rec_456",
                 "kind": "constraint",
+                "record_role": "gotcha",
                 "title": "Keep SQLite canonical",
                 "updated_at": "2026-04-30T00:00:00+00:00",
                 "source_session_id": "sess_2",
@@ -423,6 +435,7 @@ def test_rendered_markdown_contains_freshness_and_citations(tmp_path):
     assert "Use generated Context Brief [rec_123]" in markdown
     assert "Keep SQLite canonical [rec_456]" in markdown
     assert "`rec_123` (decision" in markdown
+    assert "`rec_456` (constraint, role gotcha" in markdown
     assert "source_session: `sess_1`" in markdown
 
 

From ae68d95978caa07ff0780a98e0a1be74f529a156 Mon Sep 17 00:00:00 2001
From: Isaac Kargar <kargarisaac@gmail.com>
Date: Sun, 31 May 2026 14:01:21 +0300
Subject: [PATCH 2/3] fix: harden skill stewardship review flow

---
 dashboard/app/skills/page.tsx                 | 660 +++++++++++++++---
 dashboard/components/LayoutShell.tsx          |   6 +-
 dashboard/lib/api.ts                          |   7 +-
 dashboard/lib/types.ts                        |   1 +
 docs/cli/skill.md                             |  62 +-
 src/lerim/agents/trace_ingestion/pipeline.py  |  15 +-
 src/lerim/context/__init__.py                 |   1 +
 src/lerim/context/retrieval.py                |   2 +-
 src/lerim/server/api.py                       | 224 ++----
 src/lerim/server/cli.py                       | 235 +------
 src/lerim/server/cli_skill.py                 | 246 +++++++
 src/lerim/server/http_skill_routes.py         | 165 +++++
 src/lerim/server/httpd.py                     | 128 +---
 src/lerim/server/skill_api.py                 | 207 ++++++
 src/lerim/skill_stewardship/artifacts.py      |  75 +-
 src/lerim/skill_stewardship/patching.py       | 162 ++++-
 src/lerim/skill_stewardship/pipeline.py       | 112 ++-
 src/lerim/skill_stewardship/repository.py     | 117 ++--
 src/lerim/skill_stewardship/schemas.py        |  13 +-
 src/lerim/skill_stewardship/validation.py     |  64 +-
 src/lerim/skills/cli-reference.md             |  45 +-
 tests/README.md                               |   1 +
 .../agents/trace_ingestion/test_pipeline.py   |  28 +
 tests/unit/context/test_store_search.py       |  51 ++
 tests/unit/server/test_api.py                 | 102 +++
 tests/unit/server/test_cli_commands.py        |   3 +-
 .../unit/skill_stewardship/test_artifacts.py  |  52 ++
 .../test_repository_and_pipeline.py           | 549 ++++++++++++++-
 28 files changed, 2606 insertions(+), 727 deletions(-)
 create mode 100644 src/lerim/server/cli_skill.py
 create mode 100644 src/lerim/server/http_skill_routes.py
 create mode 100644 src/lerim/server/skill_api.py

diff --git a/dashboard/app/skills/page.tsx b/dashboard/app/skills/page.tsx
index dd972cbe..6d5ce6b4 100644
--- a/dashboard/app/skills/page.tsx
+++ b/dashboard/app/skills/page.tsx
@@ -1,16 +1,21 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, type UIEvent } from "react";
 import { api } from "@/lib/api";
 import type { SkillProposal, SkillTarget } from "@/lib/types";
 import { useToast } from "@/components/Toast";
 
+type ConfirmAction =
+  | { kind: "apply"; proposal: SkillProposal }
+  | { kind: "reject"; proposal: SkillProposal }
+  | { kind: "auto_apply"; target: SkillTarget; enabled: boolean };
+
 export default function SkillsPage() {
   const { addToast } = useToast();
   const [targets, setTargets] = useState<SkillTarget[]>([]);
   const [proposals, setProposals] = useState<SkillProposal[]>([]);
-  const [selectedTargetId, setSelectedTargetId] = useState<string>("");
-  const [selectedProposalId, setSelectedProposalId] = useState<string>("");
+  const [selectedTargetId, setSelectedTargetId] = useState("");
+  const [selectedProposalId, setSelectedProposalId] = useState("");
   const [path, setPath] = useState("");
   const [name, setName] = useState("");
   const [description, setDescription] = useState("");
@@ -18,24 +23,30 @@ export default function SkillsPage() {
   const [busy, setBusy] = useState<string | null>(null);
   const [editText, setEditText] = useState("");
   const [selectedPatchIndex, setSelectedPatchIndex] = useState(0);
+  const [confirmAction, setConfirmAction] = useState<ConfirmAction | null>(null);
 
   const load = useCallback(async () => {
     setLoading(true);
     try {
-      const [targetData, proposalData] = await Promise.all([
-        api.getSkillTargets(),
-        api.getSkillProposals(),
-      ]);
+      const [targetData, proposalData] = await Promise.all([api.getSkillTargets(), api.getSkillProposals()]);
       setTargets(targetData.targets);
       setProposals(proposalData.proposals);
-      if (!selectedTargetId && targetData.targets[0]) setSelectedTargetId(targetData.targets[0].target_id);
-      if (!selectedProposalId && proposalData.proposals[0]) setSelectedProposalId(proposalData.proposals[0].proposal_id);
+      setSelectedTargetId((current) =>
+        current && targetData.targets.some((target) => target.target_id === current)
+          ? current
+          : targetData.targets[0]?.target_id || "",
+      );
+      setSelectedProposalId((current) =>
+        current && proposalData.proposals.some((proposal) => proposal.proposal_id === current)
+          ? current
+          : proposalData.proposals[0]?.proposal_id || "",
+      );
     } catch (err) {
       addToast({ type: "error", message: err instanceof Error ? err.message : "Failed to load skills" });
     } finally {
       setLoading(false);
     }
-  }, [addToast, selectedProposalId, selectedTargetId]);
+  }, [addToast]);
 
   useEffect(() => {
     load();
@@ -47,10 +58,9 @@ export default function SkillsPage() {
     [proposals, selectedTarget],
   );
   const selectedProposal =
-    filteredProposals.find((proposal) => proposal.proposal_id === selectedProposalId) ||
-    filteredProposals[0] ||
-    null;
+    filteredProposals.find((proposal) => proposal.proposal_id === selectedProposalId) || filteredProposals[0] || null;
   const selectedPatch = selectedProposal?.patch_json.patches[selectedPatchIndex] || null;
+  const hasUnsavedEdit = Boolean(selectedPatch && editText !== (selectedPatch.after_text || ""));
 
   useEffect(() => {
     setSelectedPatchIndex(0);
@@ -60,21 +70,43 @@ export default function SkillsPage() {
     setEditText(selectedPatch?.after_text || "");
   }, [selectedPatch?.after_text, selectedPatchIndex, selectedProposal?.proposal_id]);
 
+  const canDiscardEdits = useCallback(() => {
+    return !hasUnsavedEdit || window.confirm("Discard unsaved edits?");
+  }, [hasUnsavedEdit]);
+
+  const selectTarget = (targetId: string) => {
+    if (targetId === selectedTargetId || !canDiscardEdits()) return;
+    setSelectedTargetId(targetId);
+    setSelectedProposalId(proposals.find((proposal) => proposal.target_id === targetId)?.proposal_id || "");
+    setSelectedPatchIndex(0);
+  };
+
+  const selectProposal = (proposalId: string) => {
+    if (proposalId === selectedProposalId || !canDiscardEdits()) return;
+    setSelectedProposalId(proposalId);
+    setSelectedPatchIndex(0);
+  };
+
+  const selectPatch = (index: number) => {
+    if (index === selectedPatchIndex || !canDiscardEdits()) return;
+    setSelectedPatchIndex(index);
+  };
+
   const register = async () => {
     if (!path.trim()) return;
     setBusy("register");
     try {
-      await api.addSkillTarget({
+      const result = await api.addSkillTarget({
         path: path.trim(),
         name: name.trim() || undefined,
         description: description.trim() || undefined,
-        update_mode: "review",
       });
       setPath("");
       setName("");
       setDescription("");
       addToast({ type: "success", message: "Skill registered" });
       await load();
+      setSelectedTargetId(result.target.target_id);
     } catch (err) {
       addToast({ type: "error", message: err instanceof Error ? err.message : "Could not register skill" });
     } finally {
@@ -83,25 +115,25 @@ export default function SkillsPage() {
   };
 
   const refreshTarget = async (target: SkillTarget) => {
+    if (!canDiscardEdits()) return;
     setBusy(`refresh:${target.target_id}`);
     try {
       await api.refreshSkillTarget(target.target_id);
-      addToast({ type: "success", message: "Refresh completed" });
+      addToast({ type: "success", message: "Scan completed" });
       await load();
     } catch (err) {
-      addToast({ type: "error", message: err instanceof Error ? err.message : "Refresh failed" });
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Scan failed" });
     } finally {
       setBusy(null);
     }
   };
 
-  const toggleAutoApply = async (target: SkillTarget) => {
-    const enabled = target.update_mode !== "auto_apply";
+  const updateAutoApply = async (target: SkillTarget, enabled: boolean) => {
     setBusy(`mode:${target.target_id}`);
     try {
       await api.updateSkillTargetMode(target.target_id, {
         update_mode: enabled ? "auto_apply" : "review",
-        auto_apply_policy: { ...target.auto_apply_policy, enabled, max_risk: "low" },
+        auto_apply_policy: { ...target.auto_apply_policy, enabled },
       });
       addToast({ type: "success", message: enabled ? "Auto-apply enabled" : "Auto-apply disabled" });
       await load();
@@ -112,6 +144,31 @@ export default function SkillsPage() {
     }
   };
 
+  const toggleAutoApply = (target: SkillTarget) => {
+    const enabled = target.update_mode !== "auto_apply";
+    if (enabled) {
+      setConfirmAction({ kind: "auto_apply", target, enabled });
+      return;
+    }
+    updateAutoApply(target, false);
+  };
+
+  const updatePolicyRisk = async (target: SkillTarget, maxRisk: string) => {
+    setBusy(`mode:${target.target_id}`);
+    try {
+      await api.updateSkillTargetMode(target.target_id, {
+        update_mode: target.update_mode,
+        auto_apply_policy: { ...target.auto_apply_policy, max_risk: maxRisk },
+      });
+      addToast({ type: "success", message: "Policy updated" });
+      await load();
+    } catch (err) {
+      addToast({ type: "error", message: err instanceof Error ? err.message : "Policy update failed" });
+    } finally {
+      setBusy(null);
+    }
+  };
+
   const applyProposal = async (proposal: SkillProposal) => {
     setBusy(`apply:${proposal.proposal_id}`);
     try {
@@ -157,19 +214,30 @@ export default function SkillsPage() {
     }
   };
 
+  const confirmPendingAction = async () => {
+    const action = confirmAction;
+    setConfirmAction(null);
+    if (!action) return;
+    if (action.kind === "apply") await applyProposal(action.proposal);
+    if (action.kind === "reject") await rejectProposal(action.proposal);
+    if (action.kind === "auto_apply") await updateAutoApply(action.target, action.enabled);
+  };
+
   return (
     <div className="space-y-5">
       <div className="flex flex-wrap items-start justify-between gap-3">
         <div>
           <h1 className="text-lg font-semibold text-[var(--text)]">Skills</h1>
           <p className="mt-1 max-w-2xl text-sm text-[var(--text-secondary)]">
-            Registered instruction artifacts, evidence-backed updates, and review gates.
+            Registered instruction artifacts, evidence-backed proposals, and review gates.
           </p>
         </div>
         <button
           type="button"
-          onClick={load}
-          className="min-h-11 rounded-md border border-[var(--border)] px-4 text-sm font-medium text-[var(--text)] hover:bg-white/[0.05]"
+          onClick={() => {
+            if (canDiscardEdits()) load();
+          }}
+          className="min-h-11 rounded-md border border-[var(--border)] px-4 text-sm font-medium text-[var(--text)] outline-none hover:bg-white/[0.05] focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
         >
           Refresh
         </button>
@@ -177,63 +245,82 @@ export default function SkillsPage() {
 
       <section className="grid min-w-0 gap-3 rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4 md:grid-cols-[minmax(0,1fr)_10rem]">
         <div className="grid gap-3 md:grid-cols-3">
-          <input
-            value={path}
-            onChange={(event) => setPath(event.target.value)}
-            placeholder="Path to SKILL.md, AGENTS.md, or skill folder"
-            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] md:col-span-3"
-          />
-          <input
-            value={name}
-            onChange={(event) => setName(event.target.value)}
-            placeholder="Name"
-            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
-          />
-          <input
-            value={description}
-            onChange={(event) => setDescription(event.target.value)}
-            placeholder="Improvement intent"
-            className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] md:col-span-2"
-          />
+          <label className="grid gap-1 md:col-span-3">
+            <span className="text-xs font-medium text-[var(--text-secondary)]">Path</span>
+            <input
+              name="skill-path"
+              autoComplete="off"
+              value={path}
+              onChange={(event) => setPath(event.target.value)}
+              placeholder="Path to SKILL.md, AGENTS.md, or skill folder"
+              className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+            />
+          </label>
+          <label className="grid gap-1">
+            <span className="text-xs font-medium text-[var(--text-secondary)]">Name</span>
+            <input
+              name="skill-name"
+              autoComplete="off"
+              value={name}
+              onChange={(event) => setName(event.target.value)}
+              placeholder="Name"
+              className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+            />
+          </label>
+          <label className="grid gap-1 md:col-span-2">
+            <span className="text-xs font-medium text-[var(--text-secondary)]">Intent</span>
+            <input
+              name="skill-description"
+              autoComplete="off"
+              value={description}
+              onChange={(event) => setDescription(event.target.value)}
+              placeholder="Improvement intent"
+              className="min-h-11 rounded-md border border-[var(--border)] bg-black/20 px-3 text-sm text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+            />
+          </label>
         </div>
         <button
           type="button"
           onClick={register}
           disabled={busy === "register" || !path.trim()}
-          className="min-h-11 rounded-md bg-[var(--accent-blue)] px-4 text-sm font-semibold text-white disabled:cursor-not-allowed disabled:opacity-50"
+          className="min-h-11 self-end rounded-md bg-[var(--accent-blue)] px-4 text-sm font-semibold text-white outline-none hover:brightness-110 disabled:cursor-not-allowed disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
         >
           Register
         </button>
       </section>
 
-      <div className="grid min-w-0 gap-4 lg:grid-cols-[minmax(18rem,22rem)_minmax(0,1fr)]">
+      <div className="grid min-w-0 gap-4 lg:grid-cols-[minmax(16rem,20rem)_minmax(0,1fr)]">
         <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
           <div className="border-b border-[var(--border)] px-4 py-3">
             <h2 className="text-sm font-semibold text-[var(--text)]">Registered Skills</h2>
           </div>
-          <div className="max-h-[34rem] overflow-y-auto p-2">
-            {loading && <div className="p-3 text-sm text-[var(--text-muted)]">Loading…</div>}
-            {!loading && targets.length === 0 && <div className="p-3 text-sm text-[var(--text-muted)]">No skills registered.</div>}
+          <div className="max-h-[34rem] overflow-y-auto p-2" role="list">
+            {loading && <div className="p-3 text-sm text-[var(--text-muted)]">Loading...</div>}
+            {!loading && targets.length === 0 && (
+              <div className="p-3 text-sm text-[var(--text-muted)]">Register a path above to start.</div>
+            )}
             {targets.map((target) => (
               <button
                 key={target.target_id}
                 type="button"
-                onClick={() => setSelectedTargetId(target.target_id)}
-                className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left transition-colors ${
+                aria-pressed={selectedTarget?.target_id === target.target_id}
+                onClick={() => selectTarget(target.target_id)}
+                className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left outline-none transition-colors focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] ${
                   selectedTarget?.target_id === target.target_id
                     ? "border-[var(--accent-blue)] bg-blue-500/10"
                     : "border-[var(--border)] bg-white/[0.02] hover:bg-white/[0.05]"
                 }`}
+                role="listitem"
               >
                 <div className="flex items-center justify-between gap-2">
                   <span className="truncate text-sm font-semibold text-[var(--text)]">{target.name}</span>
                   <span className="rounded-full bg-white/[0.06] px-2 py-0.5 text-[10px] text-[var(--text-secondary)]">
-                    {target.update_mode}
+                    {formatMode(target.update_mode)}
                   </span>
                 </div>
                 <div className="mt-1 truncate text-xs text-[var(--text-muted)]">{target.path}</div>
                 <div className="mt-2 flex flex-wrap gap-1.5 text-[10px] text-[var(--text-secondary)]">
-                  <span className="rounded bg-white/[0.05] px-1.5 py-0.5">{target.target_type}</span>
+                  <span className="rounded bg-white/[0.05] px-1.5 py-0.5">{formatLabel(target.target_type)}</span>
                   <span className="rounded bg-white/[0.05] px-1.5 py-0.5">{target.file_count || 0} files</span>
                 </div>
               </button>
@@ -242,7 +329,7 @@ export default function SkillsPage() {
         </section>
 
         <section className="min-w-0 space-y-4">
-          {selectedTarget && (
+          {selectedTarget ? (
             <div className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4">
               <div className="flex flex-wrap items-start justify-between gap-3">
                 <div className="min-w-0">
@@ -254,7 +341,7 @@ export default function SkillsPage() {
                     type="button"
                     onClick={() => refreshTarget(selectedTarget)}
                     disabled={busy === `refresh:${selectedTarget.target_id}`}
-                    className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] hover:bg-white/[0.05] disabled:opacity-50"
+                    className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] outline-none hover:bg-white/[0.05] disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
                   >
                     Scan
                   </button>
@@ -262,48 +349,71 @@ export default function SkillsPage() {
                     type="button"
                     onClick={() => toggleAutoApply(selectedTarget)}
                     disabled={busy === `mode:${selectedTarget.target_id}`}
-                    className={`min-h-10 rounded-md px-3 text-xs font-semibold disabled:opacity-50 ${
+                    className={`min-h-10 rounded-md px-3 text-xs font-semibold outline-none disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] ${
                       selectedTarget.update_mode === "auto_apply"
-                        ? "bg-emerald-400 text-slate-950"
+                        ? "bg-emerald-400 text-slate-950 hover:brightness-110"
                         : "border border-[var(--border)] text-[var(--text)] hover:bg-white/[0.05]"
                     }`}
                   >
-                    Auto
+                    {selectedTarget.update_mode === "auto_apply" ? "Auto-apply on" : "Auto-apply off"}
                   </button>
                 </div>
               </div>
-              <div className="mt-4 grid gap-3 md:grid-cols-3">
-                <Metric label="Type" value={selectedTarget.target_type} />
+              <div className="mt-4 grid gap-3 md:grid-cols-4">
+                <Metric label="Type" value={formatLabel(selectedTarget.target_type)} />
                 <Metric label="Entry" value={selectedTarget.entry_file} />
-                <Metric label="Pending" value={String(filteredProposals.filter((proposal) => proposal.status === "pending_review").length)} />
+                <Metric label="Scope" value={formatLabel(selectedTarget.scope_type)} />
+                <Metric
+                  label="Pending"
+                  value={String(filteredProposals.filter((proposal) => proposal.status === "pending_review").length)}
+                />
               </div>
-              <div className="mt-4 grid gap-3 lg:grid-cols-2">
+              <div className="mt-4 grid gap-3 xl:grid-cols-3">
                 <FileList title="Tracked Files" files={selectedTarget.files || []} />
                 <ManifestPanel target={selectedTarget} />
+                <PolicyPanel
+                  target={selectedTarget}
+                  busy={busy === `mode:${selectedTarget.target_id}`}
+                  onRiskChange={(risk) => updatePolicyRisk(selectedTarget, risk)}
+                />
               </div>
             </div>
+          ) : (
+            <div className="rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4 text-sm text-[var(--text-muted)]">
+              Register a skill or instruction file to review updates.
+            </div>
           )}
 
-            <div className="grid min-w-0 gap-4 xl:grid-cols-[minmax(18rem,22rem)_minmax(0,1fr)]">
+          <div className="grid min-w-0 gap-4">
             <ProposalList
               proposals={filteredProposals}
               selectedId={selectedProposal?.proposal_id || ""}
-              onSelect={setSelectedProposalId}
+              hasTarget={Boolean(selectedTarget)}
+              onSelect={selectProposal}
             />
             <ProposalReview
               proposal={selectedProposal}
               editText={editText}
               onEditText={setEditText}
               selectedPatchIndex={selectedPatchIndex}
-              onSelectPatch={setSelectedPatchIndex}
+              onSelectPatch={selectPatch}
               onSave={saveEditedProposal}
-              onApply={applyProposal}
-              onReject={rejectProposal}
+              onApply={(proposal) => setConfirmAction({ kind: "apply", proposal })}
+              onReject={(proposal) => setConfirmAction({ kind: "reject", proposal })}
               busy={busy}
             />
           </div>
         </section>
       </div>
+
+      {confirmAction && (
+        <ConfirmDialog
+          action={confirmAction}
+          onCancel={() => setConfirmAction(null)}
+          onConfirm={confirmPendingAction}
+          busy={Boolean(busy)}
+        />
+      )}
     </div>
   );
 }
@@ -322,11 +432,12 @@ function FileList({ title, files }: { title: string; files: NonNullable<SkillTar
     <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
       <h3 className="text-xs font-semibold text-[var(--text)]">{title}</h3>
       <div className="mt-2 max-h-44 space-y-1 overflow-y-auto">
+        {files.length === 0 && <div className="text-xs text-[var(--text-muted)]">No tracked files.</div>}
         {files.map((file) => (
           <div key={file.relative_path} className="flex items-center justify-between gap-2 text-xs">
             <span className="min-w-0 truncate text-[var(--text-secondary)]">{file.relative_path}</span>
             <span className="shrink-0 rounded bg-white/[0.05] px-1.5 py-0.5 text-[10px] text-[var(--text-muted)]">
-              {file.file_role}
+              {formatLabel(file.file_role)}
             </span>
           </div>
         ))}
@@ -337,18 +448,20 @@ function FileList({ title, files }: { title: string; files: NonNullable<SkillTar
 
 function ManifestPanel({ target }: { target: SkillTarget }) {
   const manifest = target.manifest;
+  const surfaces = [...(manifest?.allowed_update_surfaces || []), ...(manifest?.high_risk_surfaces || [])];
   return (
     <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
       <h3 className="text-xs font-semibold text-[var(--text)]">Update Surfaces</h3>
       <div className="mt-2 flex flex-wrap gap-1.5">
+        {surfaces.length === 0 && <div className="text-xs text-[var(--text-muted)]">No surfaces detected.</div>}
         {(manifest?.allowed_update_surfaces || []).map((surface) => (
           <span key={surface} className="rounded bg-emerald-400/10 px-2 py-1 text-[10px] text-emerald-200">
-            {surface}
+            {formatLabel(surface)}
           </span>
         ))}
         {(manifest?.high_risk_surfaces || []).map((surface) => (
           <span key={surface} className="rounded bg-amber-400/10 px-2 py-1 text-[10px] text-amber-200">
-            {surface}
+            {formatLabel(surface)}
           </span>
         ))}
       </div>
@@ -356,41 +469,107 @@ function ManifestPanel({ target }: { target: SkillTarget }) {
   );
 }
 
+function PolicyPanel({
+  target,
+  busy,
+  onRiskChange,
+}: {
+  target: SkillTarget;
+  busy: boolean;
+  onRiskChange: (risk: string) => void;
+}) {
+  const policy = target.auto_apply_policy;
+  return (
+    <div className="rounded-md border border-[var(--border)] bg-black/10 p-3">
+      <div className="flex items-center justify-between gap-2">
+        <h3 className="text-xs font-semibold text-[var(--text)]">Auto-apply Policy</h3>
+        <span className="text-[10px] text-[var(--text-muted)]">{policy.enabled ? "Enabled" : "Disabled"}</span>
+      </div>
+      <label className="mt-3 grid gap-1 text-xs">
+        <span className="text-[var(--text-muted)]">Max risk</span>
+        <select
+          value={policy.max_risk}
+          disabled={busy}
+          onChange={(event) => onRiskChange(event.target.value)}
+          className="min-h-10 rounded-md border border-[var(--border)] bg-black/20 px-2 text-[var(--text)] outline-none disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+        >
+          <option value="low">Low</option>
+          <option value="medium">Medium</option>
+          <option value="high">High</option>
+        </select>
+      </label>
+      <div className="mt-3 grid grid-cols-3 gap-2 text-[10px] text-[var(--text-secondary)]">
+        <PolicyMetric label="Files" value={String(policy.max_changed_files)} />
+        <PolicyMetric label="Adds" value={String(policy.max_added_lines)} />
+        <PolicyMetric label="Removes" value={String(policy.max_removed_lines ?? 20)} />
+      </div>
+      <div className="mt-3 flex flex-wrap gap-1.5">
+        {policy.allow_entry_file_body && <PolicyChip label="Entry body" />}
+        {policy.allow_new_reference_files && <PolicyChip label="New references" />}
+        {policy.allow_scripts && <PolicyChip label="Scripts" />}
+        {policy.allow_assets && <PolicyChip label="Assets" />}
+        {policy.allow_frontmatter && <PolicyChip label="Frontmatter" />}
+      </div>
+    </div>
+  );
+}
+
+function PolicyMetric({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="rounded border border-[var(--border)] bg-white/[0.03] px-2 py-1">
+      <div className="text-[var(--text-muted)]">{label}</div>
+      <div className="text-[var(--text)]">{value}</div>
+    </div>
+  );
+}
+
+function PolicyChip({ label }: { label: string }) {
+  return <span className="rounded bg-white/[0.05] px-2 py-1 text-[10px] text-[var(--text-secondary)]">{label}</span>;
+}
+
 function ProposalList({
   proposals,
   selectedId,
+  hasTarget,
   onSelect,
 }: {
   proposals: SkillProposal[];
   selectedId: string;
+  hasTarget: boolean;
   onSelect: (id: string) => void;
 }) {
   return (
     <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
       <div className="border-b border-[var(--border)] px-4 py-3">
-        <h2 className="text-sm font-semibold text-[var(--text)]">Updates</h2>
+        <h2 className="text-sm font-semibold text-[var(--text)]">Update Proposals</h2>
       </div>
-      <div className="max-h-[30rem] overflow-y-auto p-2">
-        {proposals.length === 0 && <div className="p-3 text-sm text-[var(--text-muted)]">No update proposals.</div>}
+      <div className="max-h-[30rem] overflow-y-auto p-2" role="list">
+        {proposals.length === 0 && (
+          <div className="p-3 text-sm text-[var(--text-muted)]">
+            {hasTarget ? "No proposals yet. Scan this skill to draft updates." : "Register a skill first."}
+          </div>
+        )}
         {proposals.map((proposal) => (
           <button
             key={proposal.proposal_id}
             type="button"
+            aria-pressed={selectedId === proposal.proposal_id}
             onClick={() => onSelect(proposal.proposal_id)}
-            className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left ${
+            className={`mb-2 min-w-0 w-full rounded-md border p-3 text-left outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] ${
               selectedId === proposal.proposal_id
                 ? "border-[var(--accent-blue)] bg-blue-500/10"
                 : "border-[var(--border)] bg-white/[0.02] hover:bg-white/[0.05]"
             }`}
+            role="listitem"
           >
             <div className="flex items-center justify-between gap-2">
               <span className="line-clamp-1 text-sm font-semibold text-[var(--text)]">{proposal.title}</span>
               <span className={`rounded-full px-2 py-0.5 text-[10px] ${riskClass(proposal.risk_level)}`}>
-                {proposal.risk_level}
+                {formatLabel(proposal.risk_level)}
               </span>
             </div>
             <div className="mt-1 line-clamp-2 text-xs text-[var(--text-secondary)]">{proposal.summary}</div>
-            <div className="mt-2 text-[10px] text-[var(--text-muted)]">{proposal.status}</div>
+            <div className="mt-2 text-[10px] text-[var(--text-muted)]">{formatStatus(proposal.status)}</div>
           </button>
         ))}
       </div>
@@ -422,12 +601,22 @@ function ProposalReview({
   if (!proposal) {
     return (
       <section className="min-w-0 rounded-lg border border-[var(--border)] bg-[var(--bg-card)] p-4 text-sm text-[var(--text-muted)]">
-        Select an update proposal to review.
+        Select a proposal to review.
       </section>
     );
   }
   const patches = proposal.patch_json.patches;
   const patch = patches[selectedPatchIndex] || patches[0];
+  const hasUnsavedEdit = Boolean(patch && editText !== (patch.after_text || ""));
+  const canEdit = proposal.status === "pending_review" || proposal.status === "failed_validation";
+  const canReject = !["applied", "rejected", "superseded"].includes(proposal.status);
+  const applyBlocker = applyBlockerText(proposal, hasUnsavedEdit);
+  const canApply = !applyBlocker;
+  const diffText =
+    patch && hasUnsavedEdit
+      ? previewDiff(patch.relative_path, patch.before_text || "", editText)
+      : patch?.diff_text || "No diff available until the proposal is regenerated.";
+
   return (
     <section className="min-w-0 overflow-hidden rounded-lg border border-[var(--border)] bg-[var(--bg-card)]">
       <div className="border-b border-[var(--border)] p-4">
@@ -436,9 +625,19 @@ function ProposalReview({
             <h2 className="text-base font-semibold text-[var(--text)]">{proposal.title}</h2>
             <p className="mt-1 text-sm text-[var(--text-secondary)]">{proposal.summary}</p>
           </div>
-          <span className={`rounded-full px-2.5 py-1 text-xs ${riskClass(proposal.risk_level)}`}>{proposal.risk_level}</span>
+          <span className={`rounded-full px-2.5 py-1 text-xs ${riskClass(proposal.risk_level)}`}>
+            {formatLabel(proposal.risk_level)}
+          </span>
         </div>
         <div className="mt-3 flex flex-wrap gap-1.5">
+          <span className="rounded bg-white/[0.05] px-2 py-1 text-[10px] text-[var(--text-secondary)]">
+            {formatStatus(proposal.status)}
+          </span>
+          {proposal.status === "pending_review" && (
+            <span className="rounded bg-amber-400/10 px-2 py-1 text-[10px] text-amber-200">
+              Not applied
+            </span>
+          )}
           {Array.from(new Set(patches.flatMap((item) => item.evidence_record_ids || []))).map((recordId) => (
             <span key={recordId} className="rounded bg-white/[0.05] px-2 py-1 text-[10px] text-[var(--text-secondary)]">
               {recordId}
@@ -451,8 +650,9 @@ function ProposalReview({
               <button
                 key={`${item.relative_path}:${index}`}
                 type="button"
+                aria-pressed={index === selectedPatchIndex}
                 onClick={() => onSelectPatch(index)}
-                className={`min-h-8 max-w-full rounded-md border px-2 text-xs ${
+                className={`min-h-9 max-w-full rounded-md border px-2 text-xs outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)] ${
                   index === selectedPatchIndex
                     ? "border-[var(--accent-blue)] bg-blue-500/10 text-[var(--text)]"
                     : "border-[var(--border)] text-[var(--text-secondary)] hover:bg-white/[0.05]"
@@ -465,54 +665,59 @@ function ProposalReview({
         )}
       </div>
       {patch ? (
-        <div className="grid gap-0 lg:grid-cols-2">
-          <div className="border-b border-[var(--border)] p-4 lg:border-b-0 lg:border-r">
+        <div className="grid min-w-0 gap-0 2xl:grid-cols-2">
+          <div className="min-w-0 border-b border-[var(--border)] p-4 2xl:border-b-0 2xl:border-r">
             <div className="mb-2 flex items-center justify-between gap-2">
-              <h3 className="text-xs font-semibold text-[var(--text)]">Editable Result</h3>
-              <span className="text-[10px] text-[var(--text-muted)]">{patch.relative_path}</span>
+              <label htmlFor="skill-proposal-edit" className="text-xs font-semibold text-[var(--text)]">
+                Full File Preview
+              </label>
+              <span className="min-w-0 truncate text-[10px] text-[var(--text-muted)]">{patch.relative_path}</span>
             </div>
-            <textarea
+            <FullFilePreview
+              id="skill-proposal-edit"
               value={editText}
-              onChange={(event) => onEditText(event.target.value)}
-              className="h-[26rem] w-full resize-y rounded-md border border-[var(--border)] bg-black/30 p-3 font-mono text-xs leading-5 text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+              onChange={onEditText}
+              readOnly={!canEdit}
             />
           </div>
-          <div className="p-4">
-            <h3 className="mb-2 text-xs font-semibold text-[var(--text)]">Diff</h3>
-            <pre className="h-[26rem] overflow-auto rounded-md border border-[var(--border)] bg-black/30 p-3 text-xs leading-5 text-[var(--text-secondary)]">
-              {patch.diff_text || "No diff available until the proposal is regenerated."}
-            </pre>
+          <div className="min-w-0 p-4">
+            <div className="mb-2 flex items-center justify-between gap-2">
+              <h3 className="text-xs font-semibold text-[var(--text)]">Change Diff</h3>
+              {hasUnsavedEdit && <span className="text-[10px] text-amber-200">Unsaved edit</span>}
+            </div>
+            <DiffViewer diffText={diffText} />
           </div>
         </div>
       ) : (
         <div className="p-4 text-sm text-[var(--text-muted)]">This proposal has no patch.</div>
       )}
       <div className="flex flex-wrap items-center justify-between gap-3 border-t border-[var(--border)] p-4">
-        <ValidationState proposal={proposal} />
+        <ValidationState proposal={proposal} blocker={applyBlocker} />
         <div className="flex flex-wrap gap-2">
           <button
             type="button"
             onClick={() => onSave(proposal)}
-            disabled={!patch || busy === `edit:${proposal.proposal_id}`}
-            className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] hover:bg-white/[0.05] disabled:opacity-50"
+            disabled={!patch || !canEdit || !hasUnsavedEdit || busy === `edit:${proposal.proposal_id}`}
+            className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] outline-none hover:bg-white/[0.05] disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
           >
-            Save Edit
+            Save proposal edit
           </button>
           <button
             type="button"
             onClick={() => onReject(proposal)}
-            disabled={busy === `reject:${proposal.proposal_id}`}
-            className="min-h-10 rounded-md border border-red-400/30 px-3 text-xs font-medium text-red-200 hover:bg-red-400/10 disabled:opacity-50"
+            disabled={!canReject || busy === `reject:${proposal.proposal_id}`}
+            className="min-h-10 rounded-md border border-red-400/30 px-3 text-xs font-medium text-red-200 outline-none hover:bg-red-400/10 disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-red-300"
           >
             Reject
           </button>
           <button
             type="button"
             onClick={() => onApply(proposal)}
-            disabled={busy === `apply:${proposal.proposal_id}` || proposal.status === "applied"}
-            className="min-h-10 rounded-md bg-emerald-400 px-3 text-xs font-semibold text-slate-950 disabled:opacity-50"
+            disabled={!canApply || busy === `apply:${proposal.proposal_id}`}
+            title={applyBlocker || "Apply this proposal"}
+            className="min-h-10 rounded-md bg-emerald-400 px-3 text-xs font-semibold text-slate-950 outline-none hover:brightness-110 disabled:cursor-not-allowed disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-emerald-200"
           >
-            Apply
+            {hasUnsavedEdit ? "Save edit first" : "Apply update"}
           </button>
         </div>
       </div>
@@ -520,19 +725,268 @@ function ProposalReview({
   );
 }
 
-function ValidationState({ proposal }: { proposal: SkillProposal }) {
+function ConfirmDialog({
+  action,
+  onCancel,
+  onConfirm,
+  busy,
+}: {
+  action: ConfirmAction;
+  onCancel: () => void;
+  onConfirm: () => void;
+  busy: boolean;
+}) {
+  const title =
+    action.kind === "apply" ? "Apply proposal?" : action.kind === "reject" ? "Reject proposal?" : "Enable auto-apply?";
+  const body = confirmBody(action);
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/90 p-4 backdrop-blur-sm" role="presentation">
+      <div
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby="skill-confirm-title"
+        className="w-full max-w-lg rounded-lg border border-[var(--border)] bg-[var(--bg-subtle)] p-4 shadow-2xl"
+      >
+        <h2 id="skill-confirm-title" className="text-base font-semibold text-[var(--text)]">
+          {title}
+        </h2>
+        <div className="mt-3 space-y-2 text-sm text-[var(--text-secondary)]">
+          {body.map((line) => (
+            <p key={line}>{line}</p>
+          ))}
+        </div>
+        <div className="mt-5 flex flex-wrap justify-end gap-2">
+          <button
+            type="button"
+            onClick={onCancel}
+            disabled={busy}
+            className="min-h-10 rounded-md border border-[var(--border)] px-3 text-xs font-medium text-[var(--text)] outline-none hover:bg-white/[0.05] disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={onConfirm}
+            disabled={busy}
+            className="min-h-10 rounded-md bg-[var(--accent-blue)] px-3 text-xs font-semibold text-white outline-none hover:brightness-110 disabled:opacity-50 focus-visible:ring-2 focus-visible:ring-[var(--accent-blue)]"
+          >
+            Confirm
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function confirmBody(action: ConfirmAction) {
+  if (action.kind === "auto_apply") {
+    const policy = action.target.auto_apply_policy;
+    return [
+      `${action.target.name} will auto-apply proposals only when validation and guard checks pass.`,
+      `Policy: max risk ${formatLabel(policy.max_risk)}, ${policy.max_changed_files} files, ${policy.max_added_lines} added lines, ${policy.max_removed_lines ?? 20} removed lines.`,
+    ];
+  }
+  const proposal = action.proposal;
+  const fileCount = proposal.patch_json.patches.length;
+  if (action.kind === "reject") {
+    return [`${proposal.title} will be marked rejected.`, `${fileCount} proposed file change${fileCount === 1 ? "" : "s"} will stay unapplied.`];
+  }
+  return [
+    `${proposal.title} will write ${fileCount} file change${fileCount === 1 ? "" : "s"} to disk.`,
+    `Validation: ${proposal.validation_json?.ok ? "passed" : "not passed"}. Guard: ${proposal.guard_json?.accepted ? "accepted" : "not accepted"}.`,
+  ];
+}
+
+function previewDiff(relativePath: string, before: string, after: string) {
+  const beforeLines = splitPreviewLines(before);
+  const afterLines = splitPreviewLines(after);
+  return [
+    `--- a/${relativePath}`,
+    `+++ b/${relativePath}`,
+    "@@ unsaved edit preview @@",
+    ...beforeLines.map((line) => `-${line}`),
+    ...afterLines.map((line) => `+${line}`),
+  ].join("\n");
+}
+
+function splitPreviewLines(text: string) {
+  const trimmed = text.endsWith("\n") ? text.slice(0, -1) : text;
+  return trimmed ? trimmed.split("\n") : [""];
+}
+
+function FullFilePreview({
+  id,
+  value,
+  onChange,
+  readOnly,
+}: {
+  id: string;
+  value: string;
+  onChange: (value: string) => void;
+  readOnly: boolean;
+}) {
+  const lineNumberRef = useRef<HTMLDivElement>(null);
+  const lineNumbers = useMemo(
+    () => Array.from({ length: Math.max(1, value.split("\n").length) }, (_line, index) => index + 1).join("\n"),
+    [value],
+  );
+  const syncLineScroll = (event: UIEvent<HTMLTextAreaElement>) => {
+    if (lineNumberRef.current) lineNumberRef.current.scrollTop = event.currentTarget.scrollTop;
+  };
+
+  return (
+    <div className="flex h-72 w-full max-w-full overflow-hidden rounded-md border border-[var(--border)] bg-black/30 font-mono text-xs leading-5 md:h-80 xl:h-96">
+      <div
+        ref={lineNumberRef}
+        aria-hidden="true"
+        className="w-14 shrink-0 overflow-hidden border-r border-white/5 bg-black/20"
+      >
+        <pre className="select-none px-2 py-3 text-right text-[var(--text-muted)]">{lineNumbers}</pre>
+      </div>
+      <textarea
+        id={id}
+        value={value}
+        onChange={(event) => onChange(event.target.value)}
+        onScroll={syncLineScroll}
+        readOnly={readOnly}
+        className="h-full min-w-0 flex-1 resize-none border-0 bg-transparent p-3 text-[var(--text)] outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-[var(--accent-blue)]"
+      />
+    </div>
+  );
+}
+
+type DiffRow = {
+  text: string;
+  oldLine: number | null;
+  newLine: number | null;
+  kind: "add" | "remove" | "context" | "hunk" | "meta";
+};
+
+function DiffViewer({ diffText }: { diffText: string }) {
+  return (
+    <div className="h-72 w-full max-w-full overflow-auto rounded-md border border-[var(--border)] bg-black/30 font-mono text-xs leading-5 md:h-80 xl:h-96">
+      <div className="min-w-max py-2">
+        {parseDiffRows(diffText).map((row, index) => (
+          <div
+            key={`${index}:${row.kind}:${row.oldLine ?? ""}:${row.newLine ?? ""}`}
+            className={`grid grid-cols-[3.5rem_3.5rem_minmax(34rem,1fr)] ${diffRowClass(row.kind)}`}
+          >
+            <span className="select-none border-r border-white/5 px-2 text-right text-[var(--text-muted)]">
+              {row.oldLine ?? ""}
+            </span>
+            <span className="select-none border-r border-white/5 px-2 text-right text-[var(--text-muted)]">
+              {row.newLine ?? ""}
+            </span>
+            <code className="whitespace-pre px-3">{row.text || " "}</code>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function parseDiffRows(diffText: string) {
+  const rows: DiffRow[] = [];
+  let oldLine: number | null = null;
+  let newLine: number | null = null;
+  for (const line of splitPreviewLines(diffText)) {
+    const hunk = /^@@ -(\d+)(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk) {
+      oldLine = Number(hunk[1]);
+      newLine = Number(hunk[2]);
+      rows.push({ text: line, oldLine: null, newLine: null, kind: "hunk" });
+      continue;
+    }
+    if (line.startsWith("--- ") || line.startsWith("+++ ")) {
+      rows.push({ text: line, oldLine: null, newLine: null, kind: "meta" });
+      continue;
+    }
+    if (line.startsWith("@@ ")) {
+      oldLine = 1;
+      newLine = 1;
+      rows.push({ text: line, oldLine: null, newLine: null, kind: "hunk" });
+      continue;
+    }
+    if (oldLine === null || newLine === null) {
+      rows.push({ text: line, oldLine: null, newLine: null, kind: "meta" });
+      continue;
+    }
+    if (line.startsWith("+")) {
+      rows.push({ text: line, oldLine: null, newLine, kind: "add" });
+      newLine += 1;
+      continue;
+    }
+    if (line.startsWith("-")) {
+      rows.push({ text: line, oldLine, newLine: null, kind: "remove" });
+      oldLine += 1;
+      continue;
+    }
+    rows.push({ text: line.startsWith(" ") ? line.slice(1) : line, oldLine, newLine, kind: "context" });
+    oldLine += 1;
+    newLine += 1;
+  }
+  return rows;
+}
+
+function diffRowClass(kind: DiffRow["kind"]) {
+  if (kind === "add") return "bg-emerald-400/10 text-emerald-100";
+  if (kind === "remove") return "bg-red-400/10 text-red-100";
+  if (kind === "hunk") return "bg-blue-400/10 text-blue-200";
+  if (kind === "meta") return "text-[var(--text-muted)]";
+  return "text-[var(--text-secondary)]";
+}
+
+function ValidationState({ proposal, blocker }: { proposal: SkillProposal; blocker: string | null }) {
   const ok = proposal.validation_json?.ok;
   const errors = proposal.validation_json?.errors || [];
+  const reasons = proposal.guard_json?.reasons || [];
   return (
-    <div className="text-xs">
-      <span className={ok ? "text-emerald-300" : "text-amber-200"}>
-        {ok ? "Validation passed" : "Needs review"}
-      </span>
-      {errors.length > 0 && <span className="ml-2 text-[var(--text-muted)]">{errors[0]}</span>}
+    <div className="max-w-full text-xs">
+      <div className={blocker ? "text-amber-200" : "text-emerald-300"}>{blocker || "Ready for approval"}</div>
+      {ok === false && errors[0] && <div className="mt-1 text-[var(--text-muted)]">{errors[0]}</div>}
+      {ok !== false && reasons[0] && <div className="mt-1 text-[var(--text-muted)]">{reasons[0]}</div>}
     </div>
   );
 }
 
+function applyBlockerText(proposal: SkillProposal, hasUnsavedEdit: boolean) {
+  if (proposal.status === "applied") return "Already applied";
+  if (proposal.status === "rejected") return "Rejected";
+  if (proposal.status === "superseded") return "Superseded";
+  if (proposal.status !== "pending_review") return `Status is ${formatStatus(proposal.status)}`;
+  if (hasUnsavedEdit) return "Save edits before applying";
+  if (proposal.validation_json?.ok !== true) return "Validation has not passed";
+  if (proposal.guard_json?.accepted !== true) return "Guard has not accepted this proposal";
+  return null;
+}
+
+function formatStatus(status: string) {
+  const labels: Record<string, string> = {
+    approved: "Approved",
+    applied: "Applied",
+    draft: "Draft",
+    failed_validation: "Failed validation",
+    pending_review: "Pending review",
+    rejected: "Rejected",
+    superseded: "Superseded",
+  };
+  return labels[status] || formatLabel(status);
+}
+
+function formatMode(mode: string) {
+  if (mode === "auto_apply") return "Auto-apply";
+  return formatLabel(mode);
+}
+
+function formatLabel(value: string) {
+  const words = String(value || "")
+    .replace(/[_-]+/g, " ")
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ") || "Unknown";
+}
+
 function riskClass(risk: string) {
   if (risk === "high") return "bg-red-400/10 text-red-200";
   if (risk === "medium") return "bg-amber-400/10 text-amber-200";
diff --git a/dashboard/components/LayoutShell.tsx b/dashboard/components/LayoutShell.tsx
index fabe2352..2b0b8599 100644
--- a/dashboard/components/LayoutShell.tsx
+++ b/dashboard/components/LayoutShell.tsx
@@ -21,10 +21,10 @@ export default function LayoutShell({ children }: { children: React.ReactNode })
   }, [sidebarCollapsed, sidebarPreferenceLoaded]);
 
   const contentClassName = pathname === "/context-graph"
-      ? "w-full px-4 py-5 pb-24 sm:px-6 md:p-0"
+      ? "w-full px-4 py-5 pb-36 min-[520px]:pb-24 sm:px-6 md:p-0"
       : pathname === "/memory"
-        ? "mx-auto max-w-7xl px-4 py-5 pb-24 sm:px-6 md:py-8 md:pb-8"
-        : "mx-auto max-w-6xl px-4 py-5 pb-24 sm:px-6 md:py-8 md:pb-8";
+        ? "mx-auto max-w-7xl px-4 py-5 pb-36 min-[520px]:pb-24 sm:px-6 md:py-8 md:pb-8"
+        : "mx-auto max-w-6xl px-4 py-5 pb-36 min-[520px]:pb-24 sm:px-6 md:py-8 md:pb-8";
 
   return (
     <ToastProvider>
diff --git a/dashboard/lib/api.ts b/dashboard/lib/api.ts
index 3add633e..3a52fdea 100644
--- a/dashboard/lib/api.ts
+++ b/dashboard/lib/api.ts
@@ -523,12 +523,7 @@ export const api = {
   },
 
   getRecordFilters: async (): Promise<RecordFiltersResponse> => {
-    const data = await queryRecords({ limit: "500" });
-    return {
-      types: Array.from(new Set(data.records.map((record) => record.record_kind).filter((kind): kind is string => Boolean(kind)))).sort(),
-      roles: Array.from(new Set(data.records.map((record) => record.record_role).filter((role): role is string => Boolean(role)))).sort(),
-      projects: Array.from(new Set(data.records.map((record) => record.project).filter((project): project is string => Boolean(project)))).sort(),
-    };
+    return apiFetch<RecordFiltersResponse>("/api/records/filters");
   },
 
   getRecords: queryRecords,
diff --git a/dashboard/lib/types.ts b/dashboard/lib/types.ts
index 21786188..d9b0999e 100644
--- a/dashboard/lib/types.ts
+++ b/dashboard/lib/types.ts
@@ -174,6 +174,7 @@ export interface SkillAutoApplyPolicy {
   allow_config_files: boolean;
   max_changed_files: number;
   max_added_lines: number;
+  max_removed_lines: number;
   require_validation: boolean;
 }
 
diff --git a/docs/cli/skill.md b/docs/cli/skill.md
index 30075c32..b061a1f4 100644
--- a/docs/cli/skill.md
+++ b/docs/cli/skill.md
@@ -1,8 +1,9 @@
 # lerim skill
 
-Install the bundled Lerim skill into supported agent skill directories.
+Install Lerim's bundled skill, register instruction artifacts, and review
+evidence-backed skill update proposals.
 
-## Example
+## Install
 
 ```bash
 lerim skill install
@@ -11,6 +12,63 @@ lerim skill install
 This copies the repo-shipped Lerim skill files into standard agent skill
 locations so supported agents can query Lerim before they start work.
 
+## Register Targets
+
+Register any skill or instruction artifact Lerim should monitor:
+
+```bash
+lerim skill target add ~/.agents/skills/clean-code --description "Keep simplification guidance current"
+lerim skill target list
+lerim skill target show it_abc123
+```
+
+Supported targets include skill directories, `SKILL.md`, `AGENTS.md`,
+`CLAUDE.md`, `GEMINI.md`, and related instruction files. Proposal paths are
+limited to files scanned as part of the registered target; skill bundles may
+also propose new files under `references/`, `reference/`, or `examples/`.
+Targets inside a registered Lerim project are scoped to that project. Targets
+outside registered projects are global and may learn from registered project
+records.
+
+## Auto-Apply
+
+Targets default to review mode. Auto-apply is opt-in and remains bounded by the
+target policy:
+
+```bash
+lerim skill target auto-apply it_abc123 --enable --risk low
+lerim skill target auto-apply it_abc123 --disable
+```
+
+Automatic application only runs for pending proposals that pass validation,
+guard checks, risk limits, changed-file limits, added-line limits, and
+removed-line limits. Scripts, assets, config files, and frontmatter stay blocked
+unless the target policy explicitly allows them.
+
+## Refresh And Review
+
+Run a scan to compile proposals from scoped context records:
+
+```bash
+lerim skill refresh it_abc123
+lerim skill refresh clean-code --record-limit 120 --json
+```
+
+Review proposals before applying or rejecting them:
+
+```bash
+lerim skill proposal list
+lerim skill proposal list --target-id it_abc123 --status pending_review
+lerim skill proposal show ip_abc123
+lerim skill proposal apply ip_abc123
+lerim skill proposal reject ip_abc123
+```
+
+Applying is allowed only for pending, guard-accepted, validation-passing
+proposals whose file baselines still match the current target files. Terminal
+proposals such as applied or rejected proposals cannot be edited back into
+review.
+
 ## What to do next
 
 Add a short Lerim startup instruction to the repository's agent instruction file,
diff --git a/src/lerim/agents/trace_ingestion/pipeline.py b/src/lerim/agents/trace_ingestion/pipeline.py
index 450ce867..b9cd4876 100644
--- a/src/lerim/agents/trace_ingestion/pipeline.py
+++ b/src/lerim/agents/trace_ingestion/pipeline.py
@@ -664,7 +664,20 @@ def annotate_record_roles(self, state: dict[str, Any]) -> None:
         records = list(payload.get("durable_records") or [])
         if not records:
             return
-        self.require_budget(state)
+        if int(state.get("llm_calls") or 0) >= self.max_model_steps:
+            role_counts: dict[str, int] = {}
+            for record in records:
+                role = str(record.get("record_role") or "general")
+                role_counts[role] = role_counts.get(role, 0) + 1
+            state["observations"].append(
+                observation(
+                    "annotate_record_roles",
+                    True,
+                    f"skipped_for_budget {role_count_summary(role_counts)}",
+                    {"role_counts": role_counts, "skipped_for_budget": True},
+                )
+            )
+            return
         if self.progress:
             print(
                 f"  trace-ingestion role_annotation {int(state['llm_calls']) + 1}/{self.max_model_steps}",
diff --git a/src/lerim/context/__init__.py b/src/lerim/context/__init__.py
index fe69acdf..8890b7b4 100644
--- a/src/lerim/context/__init__.py
+++ b/src/lerim/context/__init__.py
@@ -81,6 +81,7 @@ def __dir__() -> list[str]:
     "ALLOWED_STATUSES",
     "ALLOWED_SCOPE_TYPES",
     "ContextStore",
+    "DEFAULT_RECORD_ROLE",
     "DURABLE_RECORD_KINDS",
     "EMBEDDING_DIMS",
     "EMBEDDING_MODEL_NAME",
diff --git a/src/lerim/context/retrieval.py b/src/lerim/context/retrieval.py
index 03eaf007..7172fcec 100644
--- a/src/lerim/context/retrieval.py
+++ b/src/lerim/context/retrieval.py
@@ -191,7 +191,7 @@ def read_candidates(active_conn: sqlite3.Connection) -> list[sqlite3.Row]:
             ).fetchone()[0]
         )
         candidate_limit = min(max_candidates, max(int(limit), 25))
-        if project_ids or kind_filters or statuses or valid_at or include_archived:
+        if project_ids or kind_filters or role_filters or statuses or valid_at or include_archived:
             candidate_limit = min(max_candidates, max(candidate_limit, int(limit) * 4))
         rows: list[sqlite3.Row] = []
         while candidate_limit > 0:
diff --git a/src/lerim/server/api.py b/src/lerim/server/api.py
index f96cc78f..cbc79b45 100644
--- a/src/lerim/server/api.py
+++ b/src/lerim/server/api.py
@@ -57,12 +57,19 @@
 )
 from lerim.profiles import list_signal_packs
 from lerim.server.runtime import LerimRuntime
-from lerim.skill_stewardship.artifacts import artifact_name, scan_instruction_artifact
-from lerim.skill_stewardship.patching import apply_proposal
-from lerim.skill_stewardship.pipeline import guard_proposal, hydrate_patch_text, run_skill_stewardship_refresh
-from lerim.skill_stewardship.repository import SkillStewardshipRepository
-from lerim.skill_stewardship.schemas import AutoApplyPolicy, SkillProposalDraft
-from lerim.skill_stewardship.validation import validate_proposal
+from lerim.server.skill_api import (
+    api_skill_proposal_apply as api_skill_proposal_apply,
+    api_skill_proposal_reject as api_skill_proposal_reject,
+    api_skill_proposal_show as api_skill_proposal_show,
+    api_skill_proposal_update as api_skill_proposal_update,
+    api_skill_proposals as api_skill_proposals,
+    api_skill_refresh as api_skill_refresh,
+    api_skill_runs as api_skill_runs,
+    api_skill_target_add as api_skill_target_add,
+    api_skill_target_mode as api_skill_target_mode,
+    api_skill_target_show as api_skill_target_show,
+    api_skill_targets as api_skill_targets,
+)
 from lerim.sessions.catalog import (
     count_all_session_state,
     count_fts_indexed,
@@ -308,6 +315,16 @@ def _count_project_records(config: Config, project_path: Path) -> int:
     return int(row["total"]) if row else 0
 
 
+def _registered_project_ids(config: Config, store: ContextStore) -> list[str]:
+    """Return registered project ids and make sure they exist in the store."""
+    project_ids = []
+    for _name, path in _registered_projects(config):
+        identity = resolve_project_identity(path)
+        store.register_project(identity)
+        project_ids.append(identity.project_id)
+    return project_ids
+
+
 def _session_stats_for_repo(
     *,
     sessions_db_path: Path,
@@ -540,163 +557,58 @@ def api_query(
     }
 
 
-def api_skill_target_add(
-    *,
-    path: str,
-    name: str | None = None,
-    description: str | None = None,
-    update_mode: str = "review",
-) -> dict[str, Any]:
-    """Register or refresh one instruction target from a filesystem path."""
+def api_record_filters() -> dict[str, Any]:
+    """Return complete distinct record filter options for the dashboard."""
     config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    base, manifest, files = scan_instruction_artifact(path)
-    target = repository.upsert_target(
-        name=name or artifact_name(path, manifest),
-        path=Path(path).expanduser().resolve(),
-        description=description,
-        manifest=manifest,
-        files=files,
-        update_mode=update_mode,
-    )
-    return {
-        "target": target.model_dump(),
-        "base_path": str(base),
-        "files": [item.model_dump(exclude={"text_preview"}) for item in files],
-        "error": False,
+    store = _context_store(config)
+    project_ids = _registered_project_ids(config, store)
+    if not project_ids:
+        return {"types": [], "roles": [], "projects": [], "error": False}
+    placeholders = ", ".join("?" for _ in project_ids)
+    with store.connect() as conn:
+        kind_rows = conn.execute(
+            f"""
+            SELECT DISTINCT kind AS value
+            FROM records
+            WHERE status = 'active'
+              AND project_id IN ({placeholders})
+              AND COALESCE(TRIM(kind), '') != ''
+            ORDER BY kind ASC
+            """,
+            tuple(project_ids),
+        ).fetchall()
+        role_rows = conn.execute(
+            f"""
+            SELECT DISTINCT COALESCE(record_role, 'general') AS value
+            FROM records
+            WHERE status = 'active'
+              AND project_id IN ({placeholders})
+              AND COALESCE(TRIM(record_role), '') != ''
+            ORDER BY value ASC
+            """,
+            tuple(project_ids),
+        ).fetchall()
+        project_rows = conn.execute(
+            f"""
+            SELECT DISTINCT project_id AS value
+            FROM records
+            WHERE status = 'active'
+              AND project_id IN ({placeholders})
+            ORDER BY value ASC
+            """,
+            tuple(project_ids),
+        ).fetchall()
+    project_names_by_id = {
+        resolve_project_identity(path).project_id: name for name, path in _registered_projects(config)
     }
-
-
-def api_skill_targets() -> dict[str, Any]:
-    """List registered instruction targets with latest scanned files."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    targets = []
-    for target in repository.list_targets():
-        files = repository.target_files(target.target_id)
-        targets.append(
-            {
-                **target.model_dump(),
-                "file_count": len(files),
-                "files": [item.model_dump(exclude={"text_preview"}) for item in files],
-            }
-        )
-    return {"targets": targets, "error": False}
-
-
-def api_skill_target_show(target_id_or_name: str) -> dict[str, Any]:
-    """Return one instruction target, files, and related proposals."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    target = repository.get_target(target_id_or_name)
     return {
-        "target": target.model_dump(),
-        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
-        "proposals": [item.model_dump() for item in repository.list_proposals(target_id=target.target_id)],
+        "types": [str(row["value"]) for row in kind_rows],
+        "roles": [str(row["value"]) for row in role_rows],
+        "projects": sorted(project_names_by_id.get(str(row["value"]), str(row["value"])) for row in project_rows),
         "error": False,
     }
 
 
-def api_skill_target_mode(
-    *,
-    target_id_or_name: str,
-    update_mode: str,
-    auto_apply_policy: dict[str, Any] | None = None,
-) -> dict[str, Any]:
-    """Update target review mode and auto-apply policy."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    existing = repository.get_target(target_id_or_name)
-    policy = existing.auto_apply_policy
-    if auto_apply_policy is not None:
-        policy = AutoApplyPolicy.model_validate({**policy.model_dump(), **auto_apply_policy})
-    target = repository.update_target_mode(target_id_or_name, update_mode, policy)
-    return {"target": target.model_dump(), "error": False}
-
-
-def api_skill_refresh(target_id_or_name: str, *, record_limit: int = 80) -> dict[str, Any]:
-    """Run the LLM-backed skill stewardship proposal pipeline."""
-    result = run_skill_stewardship_refresh(
-        target_id_or_name,
-        record_limit=record_limit,
-        progress=False,
-    )
-    return {**result, "error": False}
-
-
-def api_skill_proposals(
-    *,
-    target_id: str | None = None,
-    status: str | None = None,
-) -> dict[str, Any]:
-    """List skill update proposals."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    proposals = repository.list_proposals(target_id=target_id, status=status)
-    return {"proposals": [proposal.model_dump() for proposal in proposals], "error": False}
-
-
-def api_skill_proposal_show(proposal_id: str) -> dict[str, Any]:
-    """Return one proposal with its target and files."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    proposal = repository.get_proposal(proposal_id)
-    target = repository.get_target(proposal.target_id)
-    return {
-        "proposal": proposal.model_dump(),
-        "target": target.model_dump(),
-        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
-        "error": False,
-    }
-
-
-def api_skill_proposal_apply(proposal_id: str) -> dict[str, Any]:
-    """Apply a proposal after user confirmation."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    proposal = repository.get_proposal(proposal_id)
-    applied = apply_proposal(repository=repository, proposal=proposal, applied_by="user")
-    return {"proposal": applied.model_dump(), "error": False}
-
-
-def api_skill_proposal_reject(proposal_id: str) -> dict[str, Any]:
-    """Reject a proposal from CLI or dashboard review."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    proposal = repository.set_proposal_status(proposal_id, "rejected")
-    return {"proposal": proposal.model_dump(), "error": False}
-
-
-def api_skill_proposal_update(proposal_id: str, patch_json: dict[str, Any]) -> dict[str, Any]:
-    """Replace proposal patch JSON after dashboard editing."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    proposal = repository.get_proposal(proposal_id)
-    target = repository.get_target(proposal.target_id)
-    if target.manifest is None:
-        raise ValueError("target manifest is missing")
-    base = Path(target.path).expanduser().resolve()
-    if base.is_file():
-        base = base.parent
-    draft = hydrate_patch_text(base=base, draft=SkillProposalDraft.model_validate(patch_json))
-    guard = guard_proposal(draft=draft, policy=target.auto_apply_policy)
-    validation = validate_proposal(base_path=base, manifest=target.manifest, proposal=draft)
-    updated = repository.update_proposal_patch(
-        proposal_id=proposal_id,
-        draft=draft,
-        validation=validation,
-        guard=guard,
-    )
-    return {"proposal": updated.model_dump(), "error": False}
-
-
-def api_skill_runs(limit: int = 20) -> dict[str, Any]:
-    """List recent skill stewardship runs."""
-    config = get_config()
-    repository = SkillStewardshipRepository(_context_store(config))
-    return {"runs": repository.recent_runs(limit=limit), "error": False}
-
-
 def api_memory_reset(
     *,
     project: str | None = None,
diff --git a/src/lerim/server/cli.py b/src/lerim/server/cli.py
index 966cc630..72d4640e 100644
--- a/src/lerim/server/cli.py
+++ b/src/lerim/server/cli.py
@@ -40,15 +40,6 @@
 )
 
 from lerim.server.api import (
-    api_skill_proposal_apply,
-    api_skill_proposal_reject,
-    api_skill_proposal_show,
-    api_skill_proposals,
-    api_skill_refresh,
-    api_skill_target_add,
-    api_skill_target_mode,
-    api_skill_target_show,
-    api_skill_targets,
     api_memory_reset,
     api_project_add,
     api_project_list,
@@ -58,6 +49,7 @@
     parse_duration_to_seconds,
     write_init_config,
 )
+from lerim.server.cli_skill import _cmd_skill as _cmd_skill, add_skill_parser
 from lerim.server.docker_runtime import (
     api_down,
     api_up,
@@ -2755,160 +2747,6 @@ def _shutdown(_signum: int, _frame: Any) -> None:
     return 0
 
 
-_SKILL_TARGETS: dict[str, Path] = {
-    "agents": Path.home() / ".agents" / "skills" / "lerim",
-    "claude": Path.home() / ".claude" / "skills" / "lerim",
-}
-"""Skill install targets: ~/.agents/skills (shared by most agents) + ~/.claude/skills (Claude-specific)."""
-
-
-def _cmd_skill(args: argparse.Namespace) -> int:
-    """Dispatch skill install, target, proposal, and refresh commands."""
-    action = getattr(args, "skill_action", None)
-    if action == "install":
-        return _cmd_skill_install()
-    if action == "target":
-        return _cmd_skill_target(args)
-    if action == "proposal":
-        return _cmd_skill_proposal(args)
-    if action == "refresh":
-        return _cmd_skill_refresh(args)
-    _emit("Usage: lerim skill install|target|proposal|refresh")
-    return 2
-
-
-def _cmd_skill_install() -> int:
-    """Install Lerim skill files into coding agent directories."""
-    from lerim.skills import SKILLS_DIR
-
-    skill_files = [SKILLS_DIR / "SKILL.md", SKILLS_DIR / "cli-reference.md"]
-    missing = [f for f in skill_files if not f.exists()]
-    if missing:
-        _emit(f"Skill files not found in package: {missing}", file=sys.stderr)
-        return 1
-
-    installed = []
-    for label, dest in _SKILL_TARGETS.items():
-        dest.mkdir(parents=True, exist_ok=True)
-        for src in skill_files:
-            (dest / src.name).write_text(src.read_text())
-        installed.append(
-            f"~/.{label}/skills/lerim"
-            if label != "agents"
-            else "~/.agents/skills/lerim"
-        )
-
-    _emit(f"Installed lerim skill to: {', '.join(installed)}")
-    _emit("  ~/.agents/skills/lerim  → Cursor, Codex, OpenCode, and others")
-    _emit("  ~/.claude/skills/lerim  → Claude Code")
-    return 0
-
-
-def _cmd_skill_target(args: argparse.Namespace) -> int:
-    """Manage registered instruction targets."""
-    subaction = getattr(args, "target_action", None)
-    try:
-        if subaction == "add":
-            result = api_skill_target_add(
-                path=args.path,
-                name=getattr(args, "name", None),
-                description=getattr(args, "description", None),
-                update_mode=getattr(args, "mode", "review"),
-            )
-            target = result["target"]
-            _emit(f"Registered {target['name']} ({target['target_type']})")
-            _emit(f"- id: {target['target_id']}")
-            _emit(f"- path: {target['path']}")
-            _emit(f"- entry: {target['entry_file']}")
-            return 0
-        if subaction == "list":
-            result = api_skill_targets()
-            if getattr(args, "json", False):
-                _emit(json.dumps(result, indent=2, ensure_ascii=True))
-                return 0
-            for target in result["targets"]:
-                _emit(
-                    f"{target['target_id']}  {target['name']}  "
-                    f"{target['target_type']}  {target['update_mode']}  {target['path']}"
-                )
-            return 0
-        if subaction == "show":
-            result = api_skill_target_show(args.target)
-            _emit(json.dumps(result, indent=2, ensure_ascii=True))
-            return 0
-        if subaction == "auto-apply":
-            policy = {"enabled": bool(args.enable), "max_risk": args.risk}
-            mode = "auto_apply" if args.enable else "review"
-            result = api_skill_target_mode(
-                target_id_or_name=args.target,
-                update_mode=mode,
-                auto_apply_policy=policy,
-            )
-            target = result["target"]
-            _emit(f"Updated {target['name']} mode to {target['update_mode']}")
-            return 0
-    except (FileNotFoundError, KeyError, ValueError) as exc:
-        _emit(str(exc), file=sys.stderr)
-        return 1
-    _emit("Usage: lerim skill target add|list|show|auto-apply")
-    return 2
-
-
-def _cmd_skill_proposal(args: argparse.Namespace) -> int:
-    """Review and apply skill update proposals."""
-    subaction = getattr(args, "proposal_action", None)
-    try:
-        if subaction == "list":
-            result = api_skill_proposals(
-                target_id=getattr(args, "target_id", None),
-                status=getattr(args, "status", None),
-            )
-            if getattr(args, "json", False):
-                _emit(json.dumps(result, indent=2, ensure_ascii=True))
-                return 0
-            for proposal in result["proposals"]:
-                _emit(
-                    f"{proposal['proposal_id']}  {proposal['status']}  "
-                    f"{proposal['risk_level']}  {proposal['title']}"
-                )
-            return 0
-        if subaction == "show":
-            result = api_skill_proposal_show(args.proposal)
-            _emit(json.dumps(result, indent=2, ensure_ascii=True))
-            return 0
-        if subaction == "apply":
-            result = api_skill_proposal_apply(args.proposal)
-            _emit(f"Applied {result['proposal']['proposal_id']}")
-            return 0
-        if subaction == "reject":
-            result = api_skill_proposal_reject(args.proposal)
-            _emit(f"Rejected {result['proposal']['proposal_id']}")
-            return 0
-    except (KeyError, ValueError) as exc:
-        _emit(str(exc), file=sys.stderr)
-        return 1
-    _emit("Usage: lerim skill proposal list|show|apply|reject")
-    return 2
-
-
-def _cmd_skill_refresh(args: argparse.Namespace) -> int:
-    """Run LLM-backed proposal generation for a registered target."""
-    try:
-        result = api_skill_refresh(args.target, record_limit=args.record_limit)
-    except (KeyError, ValueError) as exc:
-        _emit(str(exc), file=sys.stderr)
-        return 1
-    if getattr(args, "json", False):
-        _emit(json.dumps(result, indent=2, ensure_ascii=True))
-        return 0
-    _emit(f"Refresh run {result['run_id']}")
-    _emit(f"- records scanned: {result['records_scanned']}")
-    _emit(f"- signals: {result['signals_created']}")
-    _emit(f"- proposals: {len(result['proposals'])}")
-    _emit(f"- applied: {result['applied']}")
-    return 0
-
-
 def _cmd_auth_dispatch(args: argparse.Namespace) -> int:
     """Dispatch auth subcommands to the appropriate handler."""
     auth_command = getattr(args, "auth_command", None)
@@ -3767,76 +3605,7 @@ def build_parser() -> argparse.ArgumentParser:
     serve.add_argument("--port", type=int, help="Bind port (default: 8765).")
     serve.set_defaults(func=_cmd_serve)
 
-    # ── skill ─────────────────────────────────────────────────────────
-    skill = sub.add_parser(
-        "skill",
-        formatter_class=_F,
-        help="Install Lerim skill files and manage watched skill updates",
-        description="Install Lerim skill files and manage registered instruction artifacts.",
-    )
-    skill_sub = skill.add_subparsers(dest="skill_action")
-    skill_sub.add_parser(
-        "install",
-        formatter_class=_F,
-        help="Copy skill files into agent directories",
-    )
-    skill_target = skill_sub.add_parser(
-        "target",
-        formatter_class=_F,
-        help="Register, inspect, and configure watched instruction artifacts",
-    )
-    target_sub = skill_target.add_subparsers(dest="target_action")
-    target_add = target_sub.add_parser("add", formatter_class=_F, help="Register a skill or instruction path")
-    target_add.add_argument("path", help="Skill directory, SKILL.md, AGENTS.md, or related instruction file.")
-    target_add.add_argument("--name", help="Display name for this watched target.")
-    target_add.add_argument("--description", help="What Lerim should improve in this target.")
-    target_add.add_argument(
-        "--mode",
-        choices=["review", "auto_apply", "paused"],
-        default="review",
-        help="Update mode. Default: review.",
-    )
-    target_list = target_sub.add_parser("list", formatter_class=_F, help="List registered targets")
-    target_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
-    target_show = target_sub.add_parser("show", formatter_class=_F, help="Show one registered target")
-    target_show.add_argument("target", help="Target id or name.")
-    target_auto = target_sub.add_parser(
-        "auto-apply",
-        formatter_class=_F,
-        help="Enable or disable low-risk automatic proposal application",
-    )
-    target_auto.add_argument("target", help="Target id or name.")
-    auto_group = target_auto.add_mutually_exclusive_group(required=True)
-    auto_group.add_argument("--enable", action="store_true", help="Enable auto-apply.")
-    auto_group.add_argument("--disable", dest="enable", action="store_false", help="Disable auto-apply.")
-    target_auto.add_argument("--risk", choices=["low", "medium", "high"], default="low")
-
-    skill_refresh = skill_sub.add_parser(
-        "refresh",
-        formatter_class=_F,
-        help="Run LLM-backed proposal generation for a target",
-    )
-    skill_refresh.add_argument("target", help="Target id or name.")
-    skill_refresh.add_argument("--record-limit", type=int, default=80)
-    skill_refresh.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
-
-    skill_proposal = skill_sub.add_parser(
-        "proposal",
-        formatter_class=_F,
-        help="Review and apply skill update proposals",
-    )
-    proposal_sub = skill_proposal.add_subparsers(dest="proposal_action")
-    proposal_list = proposal_sub.add_parser("list", formatter_class=_F, help="List proposals")
-    proposal_list.add_argument("--target-id", help="Filter by target id.")
-    proposal_list.add_argument("--status", help="Filter by proposal status.")
-    proposal_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
-    proposal_show = proposal_sub.add_parser("show", formatter_class=_F, help="Show one proposal")
-    proposal_show.add_argument("proposal", help="Proposal id.")
-    proposal_apply = proposal_sub.add_parser("apply", formatter_class=_F, help="Apply one proposal")
-    proposal_apply.add_argument("proposal", help="Proposal id.")
-    proposal_reject = proposal_sub.add_parser("reject", formatter_class=_F, help="Reject one proposal")
-    proposal_reject.add_argument("proposal", help="Proposal id.")
-    skill.set_defaults(func=_cmd_skill)
+    add_skill_parser(sub, _F)
 
     # ── auth ──────────────────────────────────────────────────────────
     auth = sub.add_parser(
diff --git a/src/lerim/server/cli_skill.py b/src/lerim/server/cli_skill.py
new file mode 100644
index 00000000..dbeba9c5
--- /dev/null
+++ b/src/lerim/server/cli_skill.py
@@ -0,0 +1,246 @@
+"""CLI command handlers and parser setup for `lerim skill`."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from lerim.server.skill_api import (
+    api_skill_proposal_apply,
+    api_skill_proposal_reject,
+    api_skill_proposal_show,
+    api_skill_proposals,
+    api_skill_refresh,
+    api_skill_target_add,
+    api_skill_target_mode,
+    api_skill_target_show,
+    api_skill_targets,
+)
+
+_SKILL_TARGETS: dict[str, Path] = {
+    "agents": Path.home() / ".agents" / "skills" / "lerim",
+    "claude": Path.home() / ".claude" / "skills" / "lerim",
+}
+"""Skill install targets: ~/.agents/skills (shared by most agents) + ~/.claude/skills (Claude-specific)."""
+
+
+def _emit(message: object = "", *, file: Any | None = None) -> None:
+    """Write one CLI output line to stdout or a provided file-like target."""
+    target = file if file is not None else sys.stdout
+    target.write(f"{message}\n")
+
+
+def _cmd_skill(args: argparse.Namespace) -> int:
+    """Dispatch skill install, target, proposal, and refresh commands."""
+    action = getattr(args, "skill_action", None)
+    if action == "install":
+        return _cmd_skill_install()
+    if action == "target":
+        return _cmd_skill_target(args)
+    if action == "proposal":
+        return _cmd_skill_proposal(args)
+    if action == "refresh":
+        return _cmd_skill_refresh(args)
+    _emit("Usage: lerim skill install|target|proposal|refresh")
+    return 2
+
+
+def _cmd_skill_install() -> int:
+    """Install Lerim skill files into coding agent directories."""
+    from lerim.skills import SKILLS_DIR
+
+    skill_files = [SKILLS_DIR / "SKILL.md", SKILLS_DIR / "cli-reference.md"]
+    missing = [f for f in skill_files if not f.exists()]
+    if missing:
+        _emit(f"Skill files not found in package: {missing}", file=sys.stderr)
+        return 1
+
+    installed = []
+    for label, dest in _SKILL_TARGETS.items():
+        dest.mkdir(parents=True, exist_ok=True)
+        for src in skill_files:
+            (dest / src.name).write_text(src.read_text())
+        installed.append(f"~/.{label}/skills/lerim" if label != "agents" else "~/.agents/skills/lerim")
+
+    _emit(f"Installed lerim skill to: {', '.join(installed)}")
+    _emit("  ~/.agents/skills/lerim  -> Cursor, Codex, OpenCode, and others")
+    _emit("  ~/.claude/skills/lerim  -> Claude Code")
+    return 0
+
+
+def _cmd_skill_target(args: argparse.Namespace) -> int:
+    """Manage registered instruction targets."""
+    subaction = getattr(args, "target_action", None)
+    try:
+        if subaction == "add":
+            result = api_skill_target_add(
+                path=args.path,
+                name=getattr(args, "name", None),
+                description=getattr(args, "description", None),
+                update_mode=getattr(args, "mode", None),
+            )
+            target = result["target"]
+            _emit(f"Registered {target['name']} ({target['target_type']})")
+            _emit(f"- id: {target['target_id']}")
+            _emit(f"- path: {target['path']}")
+            _emit(f"- entry: {target['entry_file']}")
+            return 0
+        if subaction == "list":
+            result = api_skill_targets()
+            if getattr(args, "json", False):
+                _emit(json.dumps(result, indent=2, ensure_ascii=True))
+                return 0
+            for target in result["targets"]:
+                _emit(
+                    f"{target['target_id']}  {target['name']}  "
+                    f"{target['target_type']}  {target['update_mode']}  {target['path']}"
+                )
+            return 0
+        if subaction == "show":
+            result = api_skill_target_show(args.target)
+            _emit(json.dumps(result, indent=2, ensure_ascii=True))
+            return 0
+        if subaction == "auto-apply":
+            policy = {"enabled": bool(args.enable), "max_risk": args.risk}
+            mode = "auto_apply" if args.enable else "review"
+            result = api_skill_target_mode(
+                target_id_or_name=args.target,
+                update_mode=mode,
+                auto_apply_policy=policy,
+            )
+            target = result["target"]
+            _emit(f"Updated {target['name']} mode to {target['update_mode']}")
+            return 0
+    except (FileNotFoundError, KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    _emit("Usage: lerim skill target add|list|show|auto-apply")
+    return 2
+
+
+def _cmd_skill_proposal(args: argparse.Namespace) -> int:
+    """Review and apply skill update proposals."""
+    subaction = getattr(args, "proposal_action", None)
+    try:
+        if subaction == "list":
+            result = api_skill_proposals(
+                target_id=getattr(args, "target_id", None),
+                status=getattr(args, "status", None),
+            )
+            if getattr(args, "json", False):
+                _emit(json.dumps(result, indent=2, ensure_ascii=True))
+                return 0
+            for proposal in result["proposals"]:
+                _emit(f"{proposal['proposal_id']}  {proposal['status']}  {proposal['risk_level']}  {proposal['title']}")
+            return 0
+        if subaction == "show":
+            result = api_skill_proposal_show(args.proposal)
+            _emit(json.dumps(result, indent=2, ensure_ascii=True))
+            return 0
+        if subaction == "apply":
+            result = api_skill_proposal_apply(args.proposal)
+            _emit(f"Applied {result['proposal']['proposal_id']}")
+            return 0
+        if subaction == "reject":
+            result = api_skill_proposal_reject(args.proposal)
+            _emit(f"Rejected {result['proposal']['proposal_id']}")
+            return 0
+    except (KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    _emit("Usage: lerim skill proposal list|show|apply|reject")
+    return 2
+
+
+def _cmd_skill_refresh(args: argparse.Namespace) -> int:
+    """Run LLM-backed proposal generation for a registered target."""
+    try:
+        result = api_skill_refresh(args.target, record_limit=args.record_limit)
+    except (KeyError, ValueError) as exc:
+        _emit(str(exc), file=sys.stderr)
+        return 1
+    if getattr(args, "json", False):
+        _emit(json.dumps(result, indent=2, ensure_ascii=True))
+        return 0
+    _emit(f"Refresh run {result['run_id']}")
+    _emit(f"- records scanned: {result['records_scanned']}")
+    _emit(f"- signals: {result['signals_created']}")
+    _emit(f"- proposals: {len(result['proposals'])}")
+    _emit(f"- applied: {result['applied']}")
+    return 0
+
+
+def add_skill_parser(sub: Any, formatter_class: type[argparse.HelpFormatter]) -> None:
+    """Register the `lerim skill` parser tree."""
+    skill = sub.add_parser(
+        "skill",
+        formatter_class=formatter_class,
+        help="Install Lerim skill files and manage watched skill updates",
+        description="Install Lerim skill files and manage registered instruction artifacts.",
+    )
+    skill_sub = skill.add_subparsers(dest="skill_action")
+    skill_sub.add_parser(
+        "install",
+        formatter_class=formatter_class,
+        help="Copy skill files into agent directories",
+    )
+    skill_target = skill_sub.add_parser(
+        "target",
+        formatter_class=formatter_class,
+        help="Register, inspect, and configure watched instruction artifacts",
+    )
+    target_sub = skill_target.add_subparsers(dest="target_action")
+    target_add = target_sub.add_parser("add", formatter_class=formatter_class, help="Register a skill or instruction path")
+    target_add.add_argument("path", help="Skill directory, SKILL.md, AGENTS.md, or related instruction file.")
+    target_add.add_argument("--name", help="Display name for this watched target.")
+    target_add.add_argument("--description", help="What Lerim should improve in this target.")
+    target_add.add_argument(
+        "--mode",
+        choices=["review", "auto_apply", "paused"],
+        default=None,
+        help="Update mode. New targets default to review; existing targets keep their current mode unless provided.",
+    )
+    target_list = target_sub.add_parser("list", formatter_class=formatter_class, help="List registered targets")
+    target_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+    target_show = target_sub.add_parser("show", formatter_class=formatter_class, help="Show one registered target")
+    target_show.add_argument("target", help="Target id or name.")
+    target_auto = target_sub.add_parser(
+        "auto-apply",
+        formatter_class=formatter_class,
+        help="Enable or disable low-risk automatic proposal application",
+    )
+    target_auto.add_argument("target", help="Target id or name.")
+    auto_group = target_auto.add_mutually_exclusive_group(required=True)
+    auto_group.add_argument("--enable", action="store_true", help="Enable auto-apply.")
+    auto_group.add_argument("--disable", dest="enable", action="store_false", help="Disable auto-apply.")
+    target_auto.add_argument("--risk", choices=["low", "medium", "high"], default="low")
+
+    skill_refresh = skill_sub.add_parser(
+        "refresh",
+        formatter_class=formatter_class,
+        help="Run LLM-backed proposal generation for a target",
+    )
+    skill_refresh.add_argument("target", help="Target id or name.")
+    skill_refresh.add_argument("--record-limit", type=int, default=80)
+    skill_refresh.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+
+    skill_proposal = skill_sub.add_parser(
+        "proposal",
+        formatter_class=formatter_class,
+        help="Review and apply skill update proposals",
+    )
+    proposal_sub = skill_proposal.add_subparsers(dest="proposal_action")
+    proposal_list = proposal_sub.add_parser("list", formatter_class=formatter_class, help="List proposals")
+    proposal_list.add_argument("--target-id", help="Filter by target id.")
+    proposal_list.add_argument("--status", help="Filter by proposal status.")
+    proposal_list.add_argument("--json", action="store_true", default=argparse.SUPPRESS, help="Emit machine-readable JSON.")
+    proposal_show = proposal_sub.add_parser("show", formatter_class=formatter_class, help="Show one proposal")
+    proposal_show.add_argument("proposal", help="Proposal id.")
+    proposal_apply = proposal_sub.add_parser("apply", formatter_class=formatter_class, help="Apply one proposal")
+    proposal_apply.add_argument("proposal", help="Proposal id.")
+    proposal_reject = proposal_sub.add_parser("reject", formatter_class=formatter_class, help="Reject one proposal")
+    proposal_reject.add_argument("proposal", help="Proposal id.")
+    skill.set_defaults(func=_cmd_skill)
diff --git a/src/lerim/server/http_skill_routes.py b/src/lerim/server/http_skill_routes.py
new file mode 100644
index 00000000..c5f7dd78
--- /dev/null
+++ b/src/lerim/server/http_skill_routes.py
@@ -0,0 +1,165 @@
+"""HTTP route handlers for skill stewardship endpoints."""
+
+from __future__ import annotations
+
+from http import HTTPStatus
+from typing import Any, Callable
+from urllib.parse import unquote
+
+from lerim.config.logging import logger
+from lerim.server.skill_api import (
+    api_skill_proposal_apply,
+    api_skill_proposal_reject,
+    api_skill_proposal_show,
+    api_skill_proposal_update,
+    api_skill_proposals,
+    api_skill_refresh,
+    api_skill_runs,
+    api_skill_target_add,
+    api_skill_target_mode,
+    api_skill_target_show,
+    api_skill_targets,
+)
+
+
+def handle_skill_get(handler: Any, path: str, query: dict[str, list[str]]) -> bool:
+    """Serve skill stewardship GET routes; return whether the route matched."""
+    if path == "/api/skills/targets":
+        handler._json(api_skill_targets())
+        return True
+    if path == "/api/skills/proposals":
+        handler._json(
+            api_skill_proposals(
+                target_id=_query_param(query, "target_id") or None,
+                status=_query_param(query, "status") or None,
+            )
+        )
+        return True
+    if path == "/api/skills/runs":
+        handler._json(api_skill_runs(limit=_parse_int(_query_param(query, "limit", "20"), 20, minimum=1, maximum=200)))
+        return True
+    if path.startswith("/api/skills/targets/"):
+        target_id = unquote(path.split("/api/skills/targets/", 1)[1])
+        if not target_id:
+            handler._error(HTTPStatus.BAD_REQUEST, "Missing target id")
+            return True
+        try:
+            handler._json(api_skill_target_show(target_id))
+        except KeyError as exc:
+            handler._error(HTTPStatus.NOT_FOUND, str(exc))
+        return True
+    if path.startswith("/api/skills/proposals/"):
+        proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1])
+        if not proposal_id:
+            handler._error(HTTPStatus.BAD_REQUEST, "Missing proposal id")
+            return True
+        try:
+            handler._json(api_skill_proposal_show(proposal_id))
+        except KeyError as exc:
+            handler._error(HTTPStatus.NOT_FOUND, str(exc))
+        return True
+    return False
+
+
+def handle_skill_post(handler: Any, path: str, read_body: Callable[[], dict[str, Any] | None]) -> bool:
+    """Serve skill stewardship POST routes; return whether the route matched."""
+    if path == "/api/skills/targets":
+        body = read_body()
+        if body is None:
+            return True
+        target_path = str(body.get("path") or "").strip()
+        if not target_path:
+            handler._error(HTTPStatus.BAD_REQUEST, "Missing 'path'")
+            return True
+        requested_mode = body.get("update_mode") if "update_mode" in body else None
+        try:
+            handler._json(
+                api_skill_target_add(
+                    path=target_path,
+                    name=str(body.get("name") or "").strip() or None,
+                    description=str(body.get("description") or "").strip() or None,
+                    update_mode=str(requested_mode).strip() if requested_mode is not None else None,
+                )
+            )
+        except (FileNotFoundError, ValueError) as exc:
+            handler._error(HTTPStatus.BAD_REQUEST, str(exc))
+        return True
+    if path.startswith("/api/skills/targets/") and path.endswith("/refresh"):
+        target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/refresh", 1)[0])
+        body = read_body()
+        if body is None:
+            return True
+        try:
+            handler._json(
+                api_skill_refresh(
+                    target_id,
+                    record_limit=_parse_int(str(body.get("record_limit") or "80"), 80, minimum=1, maximum=500),
+                )
+            )
+        except KeyError as exc:
+            handler._error(HTTPStatus.NOT_FOUND, str(exc))
+        except Exception as exc:
+            logger.exception("skill refresh failed")
+            handler._error(HTTPStatus.INTERNAL_SERVER_ERROR, f"Skill refresh failed: {exc}")
+        return True
+    if path.startswith("/api/skills/targets/") and path.endswith("/mode"):
+        target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/mode", 1)[0])
+        body = read_body()
+        if body is None:
+            return True
+        try:
+            handler._json(
+                api_skill_target_mode(
+                    target_id_or_name=target_id,
+                    update_mode=str(body.get("update_mode") or "review"),
+                    auto_apply_policy=body.get("auto_apply_policy") if isinstance(body.get("auto_apply_policy"), dict) else None,
+                )
+            )
+        except (KeyError, ValueError) as exc:
+            handler._error(HTTPStatus.BAD_REQUEST, str(exc))
+        return True
+    if path.startswith("/api/skills/proposals/") and path.endswith("/apply"):
+        proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/apply", 1)[0])
+        try:
+            handler._json(api_skill_proposal_apply(proposal_id))
+        except (KeyError, ValueError) as exc:
+            handler._error(HTTPStatus.BAD_REQUEST, str(exc))
+        return True
+    if path.startswith("/api/skills/proposals/") and path.endswith("/reject"):
+        proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/reject", 1)[0])
+        try:
+            handler._json(api_skill_proposal_reject(proposal_id))
+        except KeyError as exc:
+            handler._error(HTTPStatus.NOT_FOUND, str(exc))
+        except ValueError as exc:
+            handler._error(HTTPStatus.BAD_REQUEST, str(exc))
+        return True
+    if path.startswith("/api/skills/proposals/") and path.endswith("/edit"):
+        proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/edit", 1)[0])
+        body = read_body()
+        if body is None:
+            return True
+        patch_json = body.get("patch_json")
+        if not isinstance(patch_json, dict):
+            handler._error(HTTPStatus.BAD_REQUEST, "Missing 'patch_json'")
+            return True
+        try:
+            handler._json(api_skill_proposal_update(proposal_id, patch_json))
+        except (KeyError, ValueError) as exc:
+            handler._error(HTTPStatus.BAD_REQUEST, str(exc))
+        return True
+    return False
+
+
+def _query_param(query: dict[str, list[str]], key: str, default: str = "") -> str:
+    """Extract a single query parameter value."""
+    return (query.get(key) or [default])[0]
+
+
+def _parse_int(raw: str | None, default: int, *, minimum: int = 0, maximum: int = 10_000) -> int:
+    """Parse integer query/body parameter and clamp to bounds."""
+    try:
+        value = int(raw or default)
+    except (TypeError, ValueError):
+        value = default
+    return max(minimum, min(maximum, value))
diff --git a/src/lerim/server/httpd.py b/src/lerim/server/httpd.py
index 134d183b..cd4819a6 100644
--- a/src/lerim/server/httpd.py
+++ b/src/lerim/server/httpd.py
@@ -40,26 +40,17 @@
     api_project_add,
     api_project_list,
     api_query,
+    api_record_filters,
     api_project_remove,
     api_queue_jobs,
     api_retry_all_dead_letter,
-    api_skill_proposal_apply,
-    api_skill_proposal_reject,
-    api_skill_proposal_show,
-    api_skill_proposal_update,
-    api_skill_proposals,
-    api_skill_refresh,
-    api_skill_runs,
-    api_skill_target_add,
-    api_skill_target_mode,
-    api_skill_target_show,
-    api_skill_targets,
     api_retry_job,
     api_skip_all_dead_letter,
     api_skip_job,
     api_status,
     api_unscoped,
 )
+from lerim.server.http_skill_routes import handle_skill_get, handle_skill_post
 from lerim.config.settings import (
     Config,
     get_config,
@@ -1129,39 +1120,10 @@ def _handle_api_get(self, path: str, query: dict[str, list[str]]) -> None:
                 return
             self._json(api_unscoped(limit=limit))
             return
-        if path == "/api/skills/targets":
-            self._json(api_skill_targets())
+        if path == "/api/records/filters":
+            self._json(api_record_filters())
             return
-        if path == "/api/skills/proposals":
-            self._json(
-                api_skill_proposals(
-                    target_id=_query_param(query, "target_id") or None,
-                    status=_query_param(query, "status") or None,
-                )
-            )
-            return
-        if path == "/api/skills/runs":
-            self._json(api_skill_runs(limit=_parse_int(_query_param(query, "limit", "20"), 20, minimum=1, maximum=200)))
-            return
-        if path.startswith("/api/skills/targets/"):
-            target_id = unquote(path.split("/api/skills/targets/", 1)[1])
-            if not target_id:
-                self._error(HTTPStatus.BAD_REQUEST, "Missing target id")
-                return
-            try:
-                self._json(api_skill_target_show(target_id))
-            except KeyError as exc:
-                self._error(HTTPStatus.NOT_FOUND, str(exc))
-            return
-        if path.startswith("/api/skills/proposals/"):
-            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1])
-            if not proposal_id:
-                self._error(HTTPStatus.BAD_REQUEST, "Missing proposal id")
-                return
-            try:
-                self._json(api_skill_proposal_show(proposal_id))
-            except KeyError as exc:
-                self._error(HTTPStatus.NOT_FOUND, str(exc))
+        if handle_skill_get(self, path, query):
             return
         no_query_handlers = {
             "/api/health": lambda: self._json(api_health()),
@@ -1348,85 +1310,7 @@ def _run_context_answerer() -> None:
                 return
             self._json(result)
             return
-        if path == "/api/skills/targets":
-            body = read_body()
-            if body is None:
-                return
-            target_path = str(body.get("path") or "").strip()
-            if not target_path:
-                self._error(HTTPStatus.BAD_REQUEST, "Missing 'path'")
-                return
-            try:
-                self._json(
-                    api_skill_target_add(
-                        path=target_path,
-                        name=str(body.get("name") or "").strip() or None,
-                        description=str(body.get("description") or "").strip() or None,
-                        update_mode=str(body.get("update_mode") or "review"),
-                    )
-                )
-            except (FileNotFoundError, ValueError) as exc:
-                self._error(HTTPStatus.BAD_REQUEST, str(exc))
-            return
-        if path.startswith("/api/skills/targets/") and path.endswith("/refresh"):
-            target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/refresh", 1)[0])
-            body = read_body() or {}
-            try:
-                self._json(
-                    api_skill_refresh(
-                        target_id,
-                        record_limit=_parse_int(str(body.get("record_limit") or "80"), 80, minimum=1, maximum=500),
-                    )
-                )
-            except KeyError as exc:
-                self._error(HTTPStatus.NOT_FOUND, str(exc))
-            except Exception as exc:
-                logger.exception("skill refresh failed")
-                self._error(HTTPStatus.INTERNAL_SERVER_ERROR, f"Skill refresh failed: {exc}")
-            return
-        if path.startswith("/api/skills/targets/") and path.endswith("/mode"):
-            target_id = unquote(path.split("/api/skills/targets/", 1)[1].rsplit("/mode", 1)[0])
-            body = read_body()
-            if body is None:
-                return
-            try:
-                self._json(
-                    api_skill_target_mode(
-                        target_id_or_name=target_id,
-                        update_mode=str(body.get("update_mode") or "review"),
-                        auto_apply_policy=body.get("auto_apply_policy") if isinstance(body.get("auto_apply_policy"), dict) else None,
-                    )
-                )
-            except (KeyError, ValueError) as exc:
-                self._error(HTTPStatus.BAD_REQUEST, str(exc))
-            return
-        if path.startswith("/api/skills/proposals/") and path.endswith("/apply"):
-            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/apply", 1)[0])
-            try:
-                self._json(api_skill_proposal_apply(proposal_id))
-            except (KeyError, ValueError) as exc:
-                self._error(HTTPStatus.BAD_REQUEST, str(exc))
-            return
-        if path.startswith("/api/skills/proposals/") and path.endswith("/reject"):
-            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/reject", 1)[0])
-            try:
-                self._json(api_skill_proposal_reject(proposal_id))
-            except KeyError as exc:
-                self._error(HTTPStatus.NOT_FOUND, str(exc))
-            return
-        if path.startswith("/api/skills/proposals/") and path.endswith("/edit"):
-            proposal_id = unquote(path.split("/api/skills/proposals/", 1)[1].rsplit("/edit", 1)[0])
-            body = read_body()
-            if body is None:
-                return
-            patch_json = body.get("patch_json")
-            if not isinstance(patch_json, dict):
-                self._error(HTTPStatus.BAD_REQUEST, "Missing 'patch_json'")
-                return
-            try:
-                self._json(api_skill_proposal_update(proposal_id, patch_json))
-            except (KeyError, ValueError) as exc:
-                self._error(HTTPStatus.BAD_REQUEST, str(exc))
+        if handle_skill_post(self, path, read_body):
             return
         if path == "/api/ingest":
             body = read_body()
diff --git a/src/lerim/server/skill_api.py b/src/lerim/server/skill_api.py
new file mode 100644
index 00000000..e8b27c77
--- /dev/null
+++ b/src/lerim/server/skill_api.py
@@ -0,0 +1,207 @@
+"""Skill stewardship API functions shared by CLI and HTTP routes."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from lerim.config.settings import Config, get_config
+from lerim.context import ContextStore, resolve_project_identity
+from lerim.skill_stewardship.artifacts import artifact_name, scan_instruction_artifact
+from lerim.skill_stewardship.patching import apply_proposal
+from lerim.skill_stewardship.pipeline import guard_proposal, hydrate_patch_text, run_skill_stewardship_refresh
+from lerim.skill_stewardship.repository import SkillStewardshipRepository
+from lerim.skill_stewardship.schemas import AutoApplyPolicy, SkillProposalDraft
+from lerim.skill_stewardship.validation import validate_proposal
+
+
+def _context_store(config: Config) -> ContextStore:
+    """Return the canonical global context store."""
+    store = ContextStore(config.context_db_path)
+    store.initialize()
+    return store
+
+
+def _registered_projects(config: Config) -> list[tuple[str, Path]]:
+    """Return registered projects as resolved (name, path) pairs."""
+    return [(name, Path(path).expanduser().resolve()) for name, path in config.projects.items()]
+
+
+def _project_scope_for_path(config: Config, path: Path) -> tuple[str, str | None]:
+    """Return project scope for paths inside registered projects, otherwise global."""
+    resolved = path.expanduser().resolve()
+    matches = [
+        project_path
+        for _name, project_path in _registered_projects(config)
+        if resolved == project_path or project_path in resolved.parents
+    ]
+    if not matches:
+        return "global", None
+    project_path = max(matches, key=lambda item: len(item.parts))
+    return "project", resolve_project_identity(project_path).project_id
+
+
+def api_skill_target_add(
+    *,
+    path: str,
+    name: str | None = None,
+    description: str | None = None,
+    update_mode: str | None = None,
+) -> dict[str, Any]:
+    """Register or refresh one instruction target from a filesystem path."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    base, manifest, files = scan_instruction_artifact(path)
+    resolved_path = Path(path).expanduser().resolve()
+    scope_type, scope_id = _project_scope_for_path(config, resolved_path)
+    target = repository.upsert_target(
+        name=name or artifact_name(path, manifest),
+        path=resolved_path,
+        description=description,
+        manifest=manifest,
+        files=files,
+        update_mode=update_mode,
+        scope_type=scope_type,
+        scope_id=scope_id,
+    )
+    return {
+        "target": target.model_dump(),
+        "base_path": str(base),
+        "files": [item.model_dump(exclude={"text_preview"}) for item in files],
+        "error": False,
+    }
+
+
+def api_skill_targets() -> dict[str, Any]:
+    """List registered instruction targets with latest scanned files."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    targets = []
+    for target in repository.list_targets():
+        files = repository.target_files(target.target_id)
+        targets.append(
+            {
+                **target.model_dump(),
+                "file_count": len(files),
+                "files": [item.model_dump(exclude={"text_preview"}) for item in files],
+            }
+        )
+    return {"targets": targets, "error": False}
+
+
+def api_skill_target_show(target_id_or_name: str) -> dict[str, Any]:
+    """Return one instruction target, files, and related proposals."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    target = repository.get_target(target_id_or_name)
+    return {
+        "target": target.model_dump(),
+        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
+        "proposals": [item.model_dump() for item in repository.list_proposals(target_id=target.target_id)],
+        "error": False,
+    }
+
+
+def api_skill_target_mode(
+    *,
+    target_id_or_name: str,
+    update_mode: str,
+    auto_apply_policy: dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Update target review mode and auto-apply policy."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    existing = repository.get_target(target_id_or_name)
+    policy = existing.auto_apply_policy
+    if auto_apply_policy is not None:
+        policy = AutoApplyPolicy.model_validate({**policy.model_dump(), **auto_apply_policy})
+    target = repository.update_target_mode(target_id_or_name, update_mode, policy)
+    return {"target": target.model_dump(), "error": False}
+
+
+def api_skill_refresh(target_id_or_name: str, *, record_limit: int = 80) -> dict[str, Any]:
+    """Run the LLM-backed skill stewardship proposal pipeline."""
+    result = run_skill_stewardship_refresh(
+        target_id_or_name,
+        record_limit=record_limit,
+        progress=False,
+    )
+    return {**result, "error": False}
+
+
+def api_skill_proposals(
+    *,
+    target_id: str | None = None,
+    status: str | None = None,
+) -> dict[str, Any]:
+    """List skill update proposals."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposals = repository.list_proposals(target_id=target_id, status=status)
+    return {"proposals": [proposal.model_dump() for proposal in proposals], "error": False}
+
+
+def api_skill_proposal_show(proposal_id: str) -> dict[str, Any]:
+    """Return one proposal with its target and files."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    target = repository.get_target(proposal.target_id)
+    return {
+        "proposal": proposal.model_dump(),
+        "target": target.model_dump(),
+        "files": [item.model_dump() for item in repository.target_files(target.target_id)],
+        "error": False,
+    }
+
+
+def api_skill_proposal_apply(proposal_id: str) -> dict[str, Any]:
+    """Apply a proposal after user confirmation."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    applied = apply_proposal(
+        repository=repository,
+        proposal=proposal,
+        applied_by="user",
+        workspace_root=config.global_data_dir / "workspace",
+    )
+    return {"proposal": applied.model_dump(), "error": False}
+
+
+def api_skill_proposal_reject(proposal_id: str) -> dict[str, Any]:
+    """Reject a proposal from CLI or dashboard review."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.set_proposal_status(proposal_id, "rejected")
+    return {"proposal": proposal.model_dump(), "error": False}
+
+
+def api_skill_proposal_update(proposal_id: str, patch_json: dict[str, Any]) -> dict[str, Any]:
+    """Replace proposal patch JSON after dashboard editing."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    proposal = repository.get_proposal(proposal_id)
+    target = repository.get_target(proposal.target_id)
+    if target.manifest is None:
+        raise ValueError("target manifest is missing")
+    base = Path(target.path).expanduser().resolve()
+    if base.is_file():
+        base = base.parent
+    draft = hydrate_patch_text(base=base, draft=SkillProposalDraft.model_validate(patch_json))
+    guard = guard_proposal(draft=draft, policy=target.auto_apply_policy, manifest=target.manifest)
+    validation = validate_proposal(base_path=base, manifest=target.manifest, proposal=draft)
+    updated = repository.update_proposal_patch(
+        proposal_id=proposal_id,
+        draft=draft,
+        validation=validation,
+        guard=guard,
+    )
+    return {"proposal": updated.model_dump(), "error": False}
+
+
+def api_skill_runs(limit: int = 20) -> dict[str, Any]:
+    """List recent skill stewardship runs."""
+    config = get_config()
+    repository = SkillStewardshipRepository(_context_store(config))
+    return {"runs": repository.recent_runs(limit=limit), "error": False}
diff --git a/src/lerim/skill_stewardship/artifacts.py b/src/lerim/skill_stewardship/artifacts.py
index d998b2a5..90cf9dd9 100644
--- a/src/lerim/skill_stewardship/artifacts.py
+++ b/src/lerim/skill_stewardship/artifacts.py
@@ -25,6 +25,18 @@
     ".cursor",
     ".roo",
 }
+IGNORED_SCAN_DIRS = {
+    ".git",
+    ".hg",
+    ".svn",
+    ".next",
+    ".venv",
+    "__pycache__",
+    "build",
+    "dist",
+    "node_modules",
+    "venv",
+}
 
 
 def scan_instruction_artifact(path: Path | str) -> tuple[Path, ArtifactManifest, list[TargetFile]]:
@@ -76,9 +88,10 @@ def _target_files(*, root: Path, base: Path, entry: Path) -> list[TargetFile]:
     """Collect bounded artifact files for review and proposal generation."""
     candidates = [entry]
     if root.is_dir():
-        for child in sorted(root.rglob("*")):
-            if child.is_file() and _belongs_to_artifact(root, child):
-                candidates.append(child)
+        for child in _artifact_children(root):
+            candidates.append(child)
+            if len(candidates) >= MAX_SCAN_FILES:
+                break
     seen: set[Path] = set()
     files: list[TargetFile] = []
     for candidate in candidates:
@@ -90,9 +103,11 @@ def _target_files(*, root: Path, base: Path, entry: Path) -> list[TargetFile]:
             break
         try:
             stat = resolved.stat()
+            relative_path = resolved.relative_to(base).as_posix()
         except OSError:
             continue
-        relative_path = resolved.relative_to(base).as_posix()
+        except ValueError:
+            continue
         preview = None
         if _is_textish(resolved) and stat.st_size <= MAX_FILE_BYTES:
             preview = resolved.read_text(encoding="utf-8", errors="replace")
@@ -109,6 +124,42 @@ def _target_files(*, root: Path, base: Path, entry: Path) -> list[TargetFile]:
     return files
 
 
+def _artifact_children(root: Path) -> list[Path]:
+    """Return bounded candidate files without walking unrelated repo trees."""
+    children: list[Path] = []
+    for child in sorted(root.iterdir()):
+        if len(children) >= MAX_SCAN_FILES:
+            break
+        if child.is_file() and _belongs_to_artifact(root, child):
+            children.append(child)
+        elif not child.is_symlink() and child.is_dir() and child.name in KNOWN_SUPPORT_DIRS:
+            children.extend(_support_files(root, child, remaining=MAX_SCAN_FILES - len(children)))
+    return children
+
+
+def _support_files(root: Path, support_dir: Path, *, remaining: int) -> list[Path]:
+    """Walk one known support directory with pruning and a hard file cap."""
+    files: list[Path] = []
+    stack = [support_dir]
+    while stack and len(files) < remaining:
+        current = stack.pop()
+        try:
+            entries = sorted(current.iterdir())
+        except OSError:
+            continue
+        for entry in entries:
+            if len(files) >= remaining:
+                break
+            if entry.is_symlink():
+                continue
+            if entry.is_dir():
+                if entry.name not in IGNORED_SCAN_DIRS:
+                    stack.append(entry)
+            elif entry.is_file() and _belongs_to_artifact(root, entry):
+                files.append(entry)
+    return files
+
+
 def _manifest_for(*, root: Path, base: Path, entry: Path, files: list[TargetFile]) -> ArtifactManifest:
     """Build a manifest for the detected instruction artifact type."""
     target_type = _target_type(root=root, entry=entry)
@@ -154,16 +205,22 @@ def _target_type(*, root: Path, entry: Path) -> TargetType:
     if root.name == ".clinerules" or ".clinerules" in entry.parts:
         return "cline_rules"
     if entry.name == "CLAUDE.md":
-        return "opencode_rules"
+        return "claude_context"
     return "generic_markdown_bundle"
 
 
 def _belongs_to_artifact(root: Path, path: Path) -> bool:
     """Return whether a child file should be considered part of an artifact."""
-    rel = path.resolve().relative_to(root.resolve())
+    try:
+        rel = path.resolve().relative_to(root.resolve())
+    except ValueError:
+        return False
     if len(rel.parts) == 1:
         return path.name in ENTRY_NAMES or path.suffix in {".md", ".txt", ".yaml", ".yml", ".json", ".toml"}
-    return rel.parts[0] in KNOWN_SUPPORT_DIRS and path.stat().st_size <= MAX_FILE_BYTES
+    try:
+        return rel.parts[0] in KNOWN_SUPPORT_DIRS and path.stat().st_size <= MAX_FILE_BYTES
+    except OSError:
+        return False
 
 
 def _file_role(*, root: Path, entry: Path, path: Path) -> str:
@@ -217,7 +274,7 @@ def _allowed_surfaces(target_type: TargetType) -> list[str]:
         return ["entry_file_body", "references", "examples"]
     if target_type == "cline_rules":
         return ["markdown_rule_files"]
-    if target_type == "gemini_context":
+    if target_type in {"claude_context", "gemini_context"}:
         return ["context_body", "explicit_imports"]
     return ["markdown_body"]
 
@@ -227,7 +284,7 @@ def _high_risk_surfaces(target_type: TargetType) -> list[str]:
     surfaces = ["scripts", "assets", "config_files", "frontmatter"]
     if target_type == "codex_skill":
         surfaces.append("agents/openai.yaml")
-    if target_type == "claude_skill":
+    if target_type in {"claude_skill", "claude_context"}:
         surfaces.extend(["allowed-tools", "disable-model-invocation", "hooks", "mcp_config"])
     return surfaces
 
diff --git a/src/lerim/skill_stewardship/patching.py b/src/lerim/skill_stewardship/patching.py
index bb2eabe2..dbf23eac 100644
--- a/src/lerim/skill_stewardship/patching.py
+++ b/src/lerim/skill_stewardship/patching.py
@@ -3,10 +3,14 @@
 from __future__ import annotations
 
 import hashlib
+import sqlite3
 from pathlib import Path
 
-from lerim.skill_stewardship.repository import SkillStewardshipRepository, utc_now
-from lerim.skill_stewardship.schemas import SkillProposal, SkillProposalDraft
+from lerim.skill_stewardship.repository import SkillStewardshipRepository, new_id, utc_now
+from lerim.skill_stewardship.schemas import SkillPatch, SkillProposal, SkillProposalDraft
+from lerim.skill_stewardship.validation import validate_proposal
+
+APPLICABLE_STATUSES = {"pending_review", "approved"}
 
 
 def apply_proposal(
@@ -14,33 +18,153 @@ def apply_proposal(
     repository: SkillStewardshipRepository,
     proposal: SkillProposal,
     applied_by: str,
+    workspace_root: Path | None = None,
 ) -> SkillProposal:
     """Apply a persisted proposal after review or auto-apply guard approval."""
     target = repository.get_target(proposal.target_id)
     base = Path(target.path).expanduser().resolve()
     if base.is_file():
         base = base.parent
+    if target.manifest is None:
+        raise ValueError("target manifest is missing")
+    _ensure_proposal_is_applicable(proposal)
     draft = SkillProposalDraft.model_validate(proposal.patch_json)
-    snapshot_root = _snapshot_root(repository.context_store.db_path.parent, proposal.proposal_id)
+    validation = validate_proposal(base_path=base, manifest=target.manifest, proposal=draft)
+    if not validation.ok:
+        raise ValueError(f"proposal validation failed: {'; '.join(validation.errors)}")
+    snapshot_root = _snapshot_root(workspace_root or repository.context_store.db_path.parent / "workspace", proposal.proposal_id)
+    prepared: list[tuple[SkillPatch, Path, str | None]] = []
+    versions: list[dict[str, str | None]] = []
+    wrote_files = False
+    try:
+        repository.initialize()
+        with repository.context_store.connect() as conn:
+            conn.execute("BEGIN IMMEDIATE")
+            _ensure_current_status_applicable(conn, proposal.proposal_id)
+            prepared = _prepare_patches(base=base, draft=draft)
+            for patch, target_file, current_text in prepared:
+                before_hash = _hash_text(current_text) if current_text is not None else None
+                snapshot_path = None
+                if current_text is not None:
+                    snapshot_path = str(_write_snapshot(snapshot_root, patch.relative_path, target_file))
+                target_file.parent.mkdir(parents=True, exist_ok=True)
+                wrote_files = True
+                target_file.write_text(patch.after_text, encoding="utf-8")
+                versions.append(
+                    {
+                        "relative_path": patch.relative_path,
+                        "before_hash": before_hash,
+                        "after_hash": _hash_text(patch.after_text),
+                        "snapshot_path": snapshot_path,
+                    }
+                )
+            _record_applied_versions(
+                conn=conn,
+                target_id=target.target_id,
+                proposal_id=proposal.proposal_id,
+                versions=versions,
+                applied_by=applied_by,
+            )
+    except Exception:
+        if wrote_files:
+            _restore_prepared_files(prepared)
+        raise
+    return repository.get_proposal(proposal.proposal_id)
+
+
+def _ensure_proposal_is_applicable(proposal: SkillProposal) -> None:
+    """Reject proposals that are stale, unsafe, or outside the apply lifecycle."""
+    if proposal.status not in APPLICABLE_STATUSES:
+        raise ValueError(f"proposal status cannot be applied: {proposal.status}")
+    if proposal.validation_json.get("ok") is not True:
+        raise ValueError("proposal validation has not passed")
+    if proposal.guard_json.get("accepted") is not True:
+        raise ValueError("proposal guard has not accepted this update")
+
+
+def _ensure_current_status_applicable(conn: sqlite3.Connection, proposal_id: str) -> None:
+    """Reject stale apply attempts while the database write lock is held."""
+    row = conn.execute(
+        "SELECT status FROM instruction_update_proposals WHERE proposal_id = ?",
+        (proposal_id,),
+    ).fetchone()
+    if row is None:
+        raise KeyError(f"instruction proposal not found: {proposal_id}")
+    status = str(row["status"])
+    if status not in APPLICABLE_STATUSES:
+        raise ValueError(f"proposal status cannot be applied: {status}")
+
+
+def _record_applied_versions(
+    *,
+    conn: sqlite3.Connection,
+    target_id: str,
+    proposal_id: str,
+    versions: list[dict[str, str | None]],
+    applied_by: str,
+) -> None:
+    """Persist version rows and terminal proposal status in the active transaction."""
+    now = utc_now()
+    for version in versions:
+        conn.execute(
+            """
+            INSERT INTO instruction_versions(
+                version_id, target_id, proposal_id, relative_path, before_hash,
+                after_hash, snapshot_path, applied_at, applied_by
+            )
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            """,
+            (
+                new_id("iv"),
+                target_id,
+                proposal_id,
+                version["relative_path"],
+                version["before_hash"],
+                version["after_hash"],
+                version["snapshot_path"],
+                now,
+                applied_by,
+            ),
+        )
+    conn.execute(
+        """
+        UPDATE instruction_update_proposals
+        SET status = 'applied', updated_at = ?
+        WHERE proposal_id = ?
+        """,
+        (now, proposal_id),
+    )
+
+
+def _prepare_patches(base: Path, draft: SkillProposalDraft) -> list[tuple[SkillPatch, Path, str | None]]:
+    """Resolve patches and verify the current files still match proposal baselines."""
+    prepared = []
+    seen_paths: set[str] = set()
     for patch in draft.patches:
+        if patch.relative_path in seen_paths:
+            raise ValueError(f"{patch.relative_path}: duplicate patch path")
+        seen_paths.add(patch.relative_path)
         target_file = _safe_child(base, patch.relative_path)
-        before_hash = _hash_text(target_file.read_text(encoding="utf-8", errors="replace")) if target_file.exists() else None
-        snapshot_path = None
-        if target_file.exists():
-            snapshot_path = str(_write_snapshot(snapshot_root, patch.relative_path, target_file))
+        current_text = target_file.read_text(encoding="utf-8", errors="replace") if target_file.exists() else None
+        if current_text is None and patch.change_type != "create":
+            raise ValueError(f"{patch.relative_path}: missing target file cannot be modified")
+        if current_text is None and (patch.before_text or ""):
+            raise ValueError(f"{patch.relative_path}: target changed since proposal was created")
+        if current_text is not None and patch.before_text is not None and current_text != patch.before_text:
+            raise ValueError(f"{patch.relative_path}: target changed since proposal was created")
+        prepared.append((patch, target_file, current_text))
+    return prepared
+
+
+def _restore_prepared_files(prepared: list[tuple[SkillPatch, Path, str | None]]) -> None:
+    """Restore target files after a failed multi-file apply."""
+    for _patch, target_file, current_text in prepared:
+        if current_text is None:
+            if target_file.exists():
+                target_file.unlink()
+            continue
         target_file.parent.mkdir(parents=True, exist_ok=True)
-        target_file.write_text(patch.after_text, encoding="utf-8")
-        after_hash = _hash_text(patch.after_text)
-        repository.save_applied_version(
-            target_id=target.target_id,
-            proposal_id=proposal.proposal_id,
-            relative_path=patch.relative_path,
-            before_hash=before_hash,
-            after_hash=after_hash,
-            snapshot_path=snapshot_path,
-            applied_by=applied_by,
-        )
-    return repository.set_proposal_status(proposal.proposal_id, "applied")
+        target_file.write_text(current_text, encoding="utf-8")
 
 
 def _snapshot_root(base: Path, proposal_id: str) -> Path:
diff --git a/src/lerim/skill_stewardship/pipeline.py b/src/lerim/skill_stewardship/pipeline.py
index 90bfd8b0..ceb1b864 100644
--- a/src/lerim/skill_stewardship/pipeline.py
+++ b/src/lerim/skill_stewardship/pipeline.py
@@ -11,7 +11,7 @@
 from lerim.agents.model_helpers import call_model_step, prediction_payload
 from lerim.agents.model_runtime import ModelRuntime, build_model_runtime
 from lerim.config.settings import Config, get_config
-from lerim.context import ContextStore
+from lerim.context import ContextStore, resolve_project_identity
 from lerim.skill_stewardship.artifacts import manifest_json, read_target_text, scan_instruction_artifact
 from lerim.skill_stewardship.patching import apply_proposal
 from lerim.skill_stewardship.repository import SkillStewardshipRepository
@@ -21,9 +21,10 @@
     SkillPatch,
     SkillProposal,
     SkillProposalDraft,
+    ArtifactManifest,
 )
 from lerim.skill_stewardship.signatures import CompileSkillUpdateProposal
-from lerim.skill_stewardship.validation import validate_proposal
+from lerim.skill_stewardship.validation import frontmatter_block, path_belongs_to_manifest, validate_proposal
 
 DEFAULT_RECORD_LIMIT = 80
 PREFERRED_RECORD_ROLES = [
@@ -73,11 +74,17 @@ def forward(self, target_id_or_name: str, *, record_limit: int = DEFAULT_RECORD_
                 files=files,
                 update_mode=target.update_mode,
                 auto_apply_policy=target.auto_apply_policy,
+                scope_type=target.scope_type,
+                scope_id=target.scope_id,
+            )
+            records = _candidate_records(
+                self.repository.context_store,
+                limit=record_limit,
+                project_ids=_target_project_ids(self.config, refreshed),
             )
-            records = _candidate_records(self.repository.context_store, limit=record_limit)
             draft = self._compile(target=refreshed, base=base, manifest=manifest, files=files, records=records)
             draft = hydrate_patch_text(base=base, draft=draft)
-            guard = guard_proposal(draft=draft, policy=refreshed.auto_apply_policy)
+            guard = guard_proposal(draft=draft, policy=refreshed.auto_apply_policy, manifest=manifest)
             validation = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
             signals = self.repository.save_signals(run_id=run_id, target_id=refreshed.target_id, draft=draft)
             if draft.patches and guard.accepted:
@@ -96,6 +103,7 @@ def forward(self, target_id_or_name: str, *, record_limit: int = DEFAULT_RECORD_
                         repository=self.repository,
                         proposal=proposal,
                         applied_by="auto_apply",
+                        workspace_root=self.config.global_data_dir / "workspace",
                     )
                     applied += 1
             self.repository.finish_run(
@@ -179,25 +187,43 @@ def run_skill_stewardship_refresh(
     return pipeline(target_id_or_name, record_limit=record_limit)
 
 
-def guard_proposal(*, draft: SkillProposalDraft, policy: AutoApplyPolicy) -> ProposalGuardResult:
+def guard_proposal(
+    *,
+    draft: SkillProposalDraft,
+    policy: AutoApplyPolicy,
+    manifest: ArtifactManifest | None = None,
+) -> ProposalGuardResult:
     """Apply deterministic safety gates to a model-authored proposal."""
     reasons: list[str] = []
     if not draft.patches:
         return ProposalGuardResult(accepted=False, risk_level="low", auto_apply_eligible=False, reasons=["no_patch"])
     risk = _highest_risk([draft.risk_level, *(patch.risk for patch in draft.patches)])
+    added_lines = sum(
+        max(0, len((patch.after_text or "").splitlines()) - len((patch.before_text or "").splitlines()))
+        for patch in draft.patches
+    )
+    removed_lines = sum(
+        max(0, len((patch.before_text or "").splitlines()) - len((patch.after_text or "").splitlines()))
+        for patch in draft.patches
+    )
+    if not _risk_allowed(risk, policy.max_risk):
+        reasons.append(f"risk {risk} exceeds auto-apply max_risk={policy.max_risk}")
+    if len(draft.patches) > policy.max_changed_files:
+        reasons.append(f"changed files exceed auto-apply max_changed_files={policy.max_changed_files}")
+    if added_lines > policy.max_added_lines:
+        reasons.append(f"added lines exceed auto-apply max_added_lines={policy.max_added_lines}")
+    if removed_lines > policy.max_removed_lines:
+        reasons.append(f"removed lines exceed auto-apply max_removed_lines={policy.max_removed_lines}")
     for patch in draft.patches:
-        if patch.risk == "high":
-            reasons.append(f"{patch.relative_path}: high-risk changes require manual review")
         if not patch.evidence_record_ids:
             reasons.append(f"{patch.relative_path}: missing evidence")
-        if patch.relative_path.split("/", 1)[0] in {"scripts", "assets"}:
-            reasons.append(f"{patch.relative_path}: scripts/assets are blocked from auto-apply")
+        reasons.extend(_patch_policy_reasons(patch=patch, policy=policy, manifest=manifest))
     auto_apply = (
         policy.enabled
-        and risk == "low"
+        and _risk_allowed(risk, policy.max_risk)
         and len(draft.patches) <= policy.max_changed_files
-        and sum(max(0, len((patch.after_text or "").splitlines()) - len((patch.before_text or "").splitlines())) for patch in draft.patches)
-        <= policy.max_added_lines
+        and added_lines <= policy.max_added_lines
+        and removed_lines <= policy.max_removed_lines
         and not reasons
     )
     return ProposalGuardResult(
@@ -208,7 +234,36 @@ def guard_proposal(*, draft: SkillProposalDraft, policy: AutoApplyPolicy) -> Pro
     )
 
 
-def _candidate_records(store: ContextStore, *, limit: int) -> list[dict[str, Any]]:
+def _patch_policy_reasons(
+    *,
+    patch: SkillPatch,
+    policy: AutoApplyPolicy,
+    manifest: ArtifactManifest | None,
+) -> list[str]:
+    """Return policy reasons that keep one patch out of automatic application."""
+    reasons: list[str] = []
+    path = Path(patch.relative_path)
+    first = path.parts[0] if path.parts else ""
+    if patch.risk == "high":
+        reasons.append(f"{patch.relative_path}: high-risk changes require manual review")
+    if manifest and not path_belongs_to_manifest(manifest, patch.relative_path, change_type=patch.change_type):
+        reasons.append(f"{patch.relative_path}: outside registered instruction artifact")
+    if manifest and patch.relative_path == manifest.entry_file and not policy.allow_entry_file_body:
+        reasons.append(f"{patch.relative_path}: entry-file body changes are blocked from auto-apply")
+    if frontmatter_block(str(patch.before_text or "")) != frontmatter_block(patch.after_text) and not policy.allow_frontmatter:
+        reasons.append(f"{patch.relative_path}: frontmatter changes are blocked from auto-apply")
+    if patch.change_type == "create" and first in {"references", "reference", "examples"} and not policy.allow_new_reference_files:
+        reasons.append(f"{patch.relative_path}: new reference/example files are blocked from auto-apply")
+    if first == "scripts" and not policy.allow_scripts:
+        reasons.append(f"{patch.relative_path}: scripts are blocked from auto-apply")
+    if first == "assets" and not policy.allow_assets:
+        reasons.append(f"{patch.relative_path}: assets are blocked from auto-apply")
+    if _is_config_path(path) and not policy.allow_config_files:
+        reasons.append(f"{patch.relative_path}: config files are blocked from auto-apply")
+    return reasons
+
+
+def _candidate_records(store: ContextStore, *, limit: int, project_ids: list[str] | None = None) -> list[dict[str, Any]]:
     """Load high-value operational records for proposal generation."""
     store.initialize()
     role_rows: list[dict[str, Any]] = []
@@ -216,7 +271,7 @@ def _candidate_records(store: ContextStore, *, limit: int) -> list[dict[str, Any
         result = store.query(
             entity="records",
             mode="list",
-            project_ids=None,
+            project_ids=project_ids,
             record_role=role,
             status="active",
             order_by="updated_at",
@@ -229,7 +284,7 @@ def _candidate_records(store: ContextStore, *, limit: int) -> list[dict[str, Any
     result = store.query(
         entity="records",
         mode="list",
-        project_ids=None,
+        project_ids=project_ids,
         status="active",
         order_by="updated_at",
         limit=limit - len(role_rows),
@@ -239,6 +294,16 @@ def _candidate_records(store: ContextStore, *, limit: int) -> list[dict[str, Any
     return role_rows + [row for row in result.get("rows") or [] if row.get("record_id") not in seen]
 
 
+def _target_project_ids(config: Config, target: Any) -> list[str] | None:
+    """Return the project ids a target may learn from."""
+    if target.scope_type == "project" and target.scope_id:
+        return [str(target.scope_id)]
+    registered = []
+    for path in config.projects.values():
+        registered.append(resolve_project_identity(Path(path).expanduser().resolve()).project_id)
+    return registered or None
+
+
 def hydrate_patch_text(*, base: Path, draft: SkillProposalDraft) -> SkillProposalDraft:
     """Attach before_text and unified diffs to model patches."""
     patches: list[SkillPatch] = []
@@ -291,6 +356,23 @@ def _highest_risk(values: list[str]) -> str:
     return max(values, key=lambda value: order.get(str(value), 0))
 
 
+def _risk_allowed(risk: str, max_risk: str) -> bool:
+    """Return whether a patch risk is within an auto-apply policy ceiling."""
+    order = {"low": 0, "medium": 1, "high": 2}
+    return order.get(str(risk), 2) <= order.get(str(max_risk), 0)
+
+
+def _is_config_path(path: Path) -> bool:
+    """Return whether a relative target path is a high-risk config surface."""
+    first = path.parts[0] if path.parts else ""
+    return first in {"agents", ".cursor", ".roo", ".clinerules"} or path.suffix in {
+        ".json",
+        ".toml",
+        ".yaml",
+        ".yml",
+    }
+
+
 def _should_auto_apply(update_mode: str, policy: AutoApplyPolicy, proposal: SkillProposal) -> bool:
     """Return whether a persisted proposal should be auto-applied."""
     validation_ok = bool(proposal.validation_json.get("ok"))
diff --git a/src/lerim/skill_stewardship/repository.py b/src/lerim/skill_stewardship/repository.py
index 8faab558..ad3c7269 100644
--- a/src/lerim/skill_stewardship/repository.py
+++ b/src/lerim/skill_stewardship/repository.py
@@ -19,8 +19,13 @@
     SkillProposalDraft,
     TargetFile,
     ValidationResult,
+    normalize_update_mode,
 )
 
+TERMINAL_PROPOSAL_STATUSES = {"applied", "rejected", "superseded"}
+EDITABLE_PROPOSAL_STATUSES = {"pending_review", "failed_validation"}
+APPLICABLE_PROPOSAL_STATUSES = {"pending_review", "approved"}
+
 
 def utc_now() -> str:
     """Return an ISO UTC timestamp."""
@@ -160,20 +165,40 @@ def upsert_target(
         description: str | None,
         manifest: ArtifactManifest,
         files: list[TargetFile],
-        update_mode: str = "review",
+        update_mode: str | None = None,
         auto_apply_policy: AutoApplyPolicy | None = None,
+        scope_type: str | None = None,
+        scope_id: str | None = None,
     ) -> InstructionTarget:
         """Create or update a registered instruction target from a fresh scan."""
         self.initialize()
         now = utc_now()
-        policy = auto_apply_policy or AutoApplyPolicy()
         with self.context_store.connect() as conn:
             existing = conn.execute(
-                "SELECT target_id, created_at FROM instruction_targets WHERE path = ?",
+                """
+                SELECT target_id, created_at, update_mode, auto_apply_policy_json, scope_type, scope_id
+                FROM instruction_targets
+                WHERE path = ?
+                """,
                 (str(path),),
             ).fetchone()
             target_id = str(existing["target_id"]) if existing else new_id("it")
             created_at = str(existing["created_at"]) if existing else now
+            if existing and auto_apply_policy is None:
+                policy = AutoApplyPolicy.model_validate(json.loads(str(existing["auto_apply_policy_json"] or "{}")))
+            else:
+                policy = auto_apply_policy or AutoApplyPolicy()
+            effective_update_mode = (
+                normalize_update_mode(update_mode)
+                if update_mode is not None
+                else normalize_update_mode(str(existing["update_mode"]) if existing else None)
+            )
+            effective_scope_type = str(scope_type or (existing["scope_type"] if existing else "global") or "global")
+            effective_scope_id = scope_id if scope_type else (existing["scope_id"] if existing else None)
+            if effective_scope_type == "project" and not effective_scope_id:
+                raise ValueError("project-scoped instruction targets require scope_id")
+            if effective_scope_type != "project":
+                effective_scope_id = None
             conn.execute(
                 """
                 INSERT INTO instruction_targets(
@@ -181,12 +206,14 @@ def upsert_target(
                     scope_type, scope_id, update_mode, auto_apply_policy_json,
                     manifest_json, status, created_at, updated_at
                 )
-                VALUES (?, ?, ?, ?, ?, ?, 'global', NULL, ?, ?, ?, 'active', ?, ?)
+                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active', ?, ?)
                 ON CONFLICT(path) DO UPDATE SET
                     name=excluded.name,
                     description=excluded.description,
                     target_type=excluded.target_type,
                     entry_file=excluded.entry_file,
+                    scope_type=excluded.scope_type,
+                    scope_id=excluded.scope_id,
                     update_mode=excluded.update_mode,
                     auto_apply_policy_json=excluded.auto_apply_policy_json,
                     manifest_json=excluded.manifest_json,
@@ -200,7 +227,9 @@ def upsert_target(
                     str(path),
                     manifest.target_type,
                     manifest.entry_file,
-                    update_mode,
+                    effective_scope_type,
+                    effective_scope_id,
+                    effective_update_mode,
                     policy.model_dump_json(),
                     manifest.model_dump_json(),
                     created_at,
@@ -253,6 +282,7 @@ def target_files(self, target_id: str) -> list[TargetFile]:
 
     def update_target_mode(self, target_id_or_name: str, update_mode: str, policy: AutoApplyPolicy | None = None) -> InstructionTarget:
         """Update review or auto-apply behavior for a target."""
+        effective_update_mode = normalize_update_mode(update_mode)
         target = self.get_target(target_id_or_name)
         effective_policy = policy or target.auto_apply_policy
         now = utc_now()
@@ -263,7 +293,7 @@ def update_target_mode(self, target_id_or_name: str, update_mode: str, policy: A
                 SET update_mode = ?, auto_apply_policy_json = ?, updated_at = ?
                 WHERE target_id = ?
                 """,
-                (update_mode, effective_policy.model_dump_json(), now, target.target_id),
+                (effective_update_mode, effective_policy.model_dump_json(), now, target.target_id),
             )
         return self.get_target(target.target_id)
 
@@ -436,6 +466,8 @@ def set_proposal_status(self, proposal_id: str, status: str) -> SkillProposal:
         """Move a proposal through the review lifecycle."""
         self.initialize()
         with self.context_store.connect() as conn:
+            current = self._proposal_row(conn, proposal_id)
+            self._ensure_status_transition(current_status=str(current["status"]), next_status=status)
             conn.execute(
                 """
                 UPDATE instruction_update_proposals
@@ -457,15 +489,20 @@ def update_proposal_patch(
         """Replace a proposal patch after user editing and validation."""
         self.initialize()
         with self.context_store.connect() as conn:
+            current = self._proposal_row(conn, proposal_id)
+            if str(current["status"]) not in EDITABLE_PROPOSAL_STATUSES:
+                raise ValueError(f"proposal status cannot be edited: {current['status']}")
             conn.execute(
                 """
                 UPDATE instruction_update_proposals
-                SET patch_json = ?, validation_json = ?, guard_json = ?,
+                SET title = ?, summary = ?, patch_json = ?, validation_json = ?, guard_json = ?,
                     risk_level = ?, auto_apply_eligible = ?, status = 'pending_review',
                     updated_at = ?
                 WHERE proposal_id = ?
                 """,
                 (
+                    draft.title,
+                    draft.summary,
                     draft.model_dump_json(),
                     validation.model_dump_json(),
                     guard.model_dump_json(),
@@ -477,41 +514,6 @@ def update_proposal_patch(
             )
         return self.get_proposal(proposal_id)
 
-    def save_applied_version(
-        self,
-        *,
-        target_id: str,
-        proposal_id: str,
-        relative_path: str,
-        before_hash: str | None,
-        after_hash: str | None,
-        snapshot_path: str | None,
-        applied_by: str,
-    ) -> None:
-        """Record an applied file version."""
-        self.initialize()
-        with self.context_store.connect() as conn:
-            conn.execute(
-                """
-                INSERT INTO instruction_versions(
-                    version_id, target_id, proposal_id, relative_path, before_hash,
-                    after_hash, snapshot_path, applied_at, applied_by
-                )
-                VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
-                """,
-                (
-                    new_id("iv"),
-                    target_id,
-                    proposal_id,
-                    relative_path,
-                    before_hash,
-                    after_hash,
-                    snapshot_path,
-                    utc_now(),
-                    applied_by,
-                ),
-            )
-
     def recent_runs(self, *, limit: int = 20) -> list[dict[str, Any]]:
         """Return recent stewardship runs as dictionaries."""
         self.initialize()
@@ -537,6 +539,18 @@ def _replace_files(
         seen_at: str,
     ) -> None:
         """Refresh target file rows after a scan."""
+        relative_paths = [file_info.relative_path for file_info in files]
+        if relative_paths:
+            placeholders = ", ".join("?" for _ in relative_paths)
+            conn.execute(
+                f"""
+                DELETE FROM instruction_target_files
+                WHERE target_id = ? AND relative_path NOT IN ({placeholders})
+                """,
+                (target_id, *relative_paths),
+            )
+        else:
+            conn.execute("DELETE FROM instruction_target_files WHERE target_id = ?", (target_id,))
         for file_info in files:
             conn.execute(
                 """
@@ -566,6 +580,25 @@ def _replace_files(
                 ),
             )
 
+    def _proposal_row(self, conn: sqlite3.Connection, proposal_id: str) -> sqlite3.Row:
+        """Return one proposal row or raise a stable not-found error."""
+        row = conn.execute(
+            "SELECT * FROM instruction_update_proposals WHERE proposal_id = ?",
+            (proposal_id,),
+        ).fetchone()
+        if row is None:
+            raise KeyError(f"instruction proposal not found: {proposal_id}")
+        return row
+
+    def _ensure_status_transition(self, *, current_status: str, next_status: str) -> None:
+        """Reject lifecycle transitions that would resurrect terminal proposals."""
+        if current_status == next_status:
+            return
+        if current_status in TERMINAL_PROPOSAL_STATUSES:
+            raise ValueError(f"proposal status is terminal: {current_status}")
+        if next_status == "applied" and current_status not in APPLICABLE_PROPOSAL_STATUSES:
+            raise ValueError(f"proposal status cannot be applied: {current_status}")
+
     def _target_from_row(self, row: sqlite3.Row) -> InstructionTarget:
         """Convert one target row into a typed model."""
         policy_raw = json.loads(str(row["auto_apply_policy_json"] or "{}"))
diff --git a/src/lerim/skill_stewardship/schemas.py b/src/lerim/skill_stewardship/schemas.py
index 07d17cea..46eaf1c7 100644
--- a/src/lerim/skill_stewardship/schemas.py
+++ b/src/lerim/skill_stewardship/schemas.py
@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Any, Literal
+from typing import Any, Literal, cast, get_args
 
 from pydantic import BaseModel, Field
 
@@ -10,6 +10,7 @@
 TargetType = Literal[
     "codex_skill",
     "claude_skill",
+    "claude_context",
     "agent_skill",
     "agents_md",
     "gemini_context",
@@ -20,6 +21,7 @@
 ]
 TargetStatus = Literal["active", "paused", "archived"]
 UpdateMode = Literal["review", "auto_apply", "paused"]
+UPDATE_MODES = tuple(str(value) for value in get_args(UpdateMode))
 ProposalStatus = Literal[
     "draft",
     "pending_review",
@@ -57,6 +59,7 @@ class AutoApplyPolicy(BaseModel):
     allow_config_files: bool = False
     max_changed_files: int = 2
     max_added_lines: int = 40
+    max_removed_lines: int = 20
     require_validation: bool = True
 
 
@@ -171,3 +174,11 @@ class SkillProposal(BaseModel):
     auto_apply_eligible: bool
     created_at: str
     updated_at: str
+
+
+def normalize_update_mode(value: str | None) -> UpdateMode:
+    """Validate and normalize one target update mode before persistence."""
+    mode = str(value or "review").strip()
+    if mode not in UPDATE_MODES:
+        raise ValueError(f"invalid_update_mode:{mode}")
+    return cast(UpdateMode, mode)
diff --git a/src/lerim/skill_stewardship/validation.py b/src/lerim/skill_stewardship/validation.py
index e58d09d6..d7627788 100644
--- a/src/lerim/skill_stewardship/validation.py
+++ b/src/lerim/skill_stewardship/validation.py
@@ -19,20 +19,35 @@ def validate_proposal(
     checks: list[str] = []
     errors: list[str] = []
     base = base_path.resolve()
-    changed_files = {patch.relative_path for patch in proposal.patches}
+    changed_files: set[str] = set()
+    instruction_files = set(manifest.instruction_files or [manifest.entry_file])
     if not proposal.patches:
         return ValidationResult(ok=True, checks=["abstained_no_patch"], errors=[])
     checks.append("has_patch")
     for patch in proposal.patches:
+        if patch.relative_path in changed_files:
+            errors.append(f"{patch.relative_path}: duplicate patch path")
+            continue
+        changed_files.add(patch.relative_path)
         _validate_patch_path(base, patch.relative_path, errors)
+        target_file = (base / patch.relative_path).resolve()
+        if not path_belongs_to_manifest(manifest, patch.relative_path, change_type=patch.change_type):
+            errors.append(f"{patch.relative_path}: path is not part of the registered instruction artifact")
+        if target_file.exists() and patch.change_type == "create":
+            errors.append(f"{patch.relative_path}: create patch targets an existing file")
+        if not target_file.exists():
+            if patch.change_type != "create":
+                errors.append(f"{patch.relative_path}: missing file must use create change_type")
+            if not _new_file_allowed(manifest, patch.relative_path):
+                errors.append(f"{patch.relative_path}: new file is not allowed for {manifest.target_type}")
         if not patch.evidence_record_ids:
             errors.append(f"{patch.relative_path}: missing evidence_record_ids")
-        if patch.change_type == "create" and not _new_file_allowed(manifest, patch.relative_path):
-            errors.append(f"{patch.relative_path}: new file is not allowed for {manifest.target_type}")
         if patch.relative_path == manifest.entry_file:
-            if str(patch.before_text or "").startswith("---\n") and not patch.after_text.startswith("---\n"):
+            if frontmatter_block(str(patch.before_text or "")) and not frontmatter_block(patch.after_text):
                 errors.append(f"{manifest.entry_file}: must preserve existing YAML frontmatter")
             _validate_entry_text(manifest, patch.after_text, errors)
+        if patch.relative_path in instruction_files:
+            _validate_instruction_body(patch.relative_path, patch.after_text, errors)
     if len(changed_files) <= 3:
         checks.append("bounded_changed_files")
     else:
@@ -40,12 +55,25 @@ def validate_proposal(
     return ValidationResult(ok=not errors, checks=checks, errors=errors)
 
 
+def frontmatter_block(text: str) -> str | None:
+    """Return the complete YAML frontmatter block from text when present."""
+    if not text.startswith("---\n"):
+        return None
+    end = text.find("\n---", 4)
+    if end < 0:
+        return None
+    return text[: end + 4]
+
+
 def _validate_patch_path(base: Path, relative_path: str, errors: list[str]) -> None:
     """Reject absolute paths and path traversal."""
     path = Path(relative_path)
     if path.is_absolute():
         errors.append(f"{relative_path}: absolute paths are not allowed")
         return
+    if any(part in {"", ".", ".."} for part in path.parts):
+        errors.append(f"{relative_path}: relative path components are not allowed")
+        return
     resolved = (base / path).resolve()
     if base != resolved and base not in resolved.parents:
         errors.append(f"{relative_path}: path escapes target")
@@ -71,13 +99,31 @@ def _validate_entry_text(manifest: ArtifactManifest, text: str, errors: list[str
             errors.append(f"{manifest.entry_file}: missing required frontmatter field {key}")
 
 
+def _validate_instruction_body(relative_path: str, text: str, errors: list[str]) -> None:
+    """Require instruction files to retain human-readable guidance."""
+    body = text
+    frontmatter = frontmatter_block(text)
+    if frontmatter:
+        body = text[len(frontmatter):]
+    if not body.strip():
+        errors.append(f"{relative_path}: instruction body cannot be empty")
+
+
 def _new_file_allowed(manifest: ArtifactManifest, relative_path: str) -> bool:
     """Return whether a target type supports creating this file."""
     first = Path(relative_path).parts[0] if Path(relative_path).parts else ""
     if manifest.target_type in {"codex_skill", "claude_skill", "agent_skill"}:
         return first in {"references", "reference", "examples"}
-    if manifest.target_type == "cline_rules":
-        return relative_path.endswith((".md", ".txt"))
-    if manifest.target_type == "gemini_context":
-        return relative_path.endswith((".md", ".txt"))
-    return relative_path in manifest.instruction_files
+    return False
+
+
+def path_belongs_to_manifest(manifest: ArtifactManifest, relative_path: str, *, change_type: str) -> bool:
+    """Return whether a patch path is inside the scanned artifact surface."""
+    tracked = {
+        manifest.entry_file,
+        *manifest.instruction_files,
+        *manifest.supporting_files,
+    }
+    if relative_path in tracked:
+        return True
+    return change_type == "create" and _new_file_allowed(manifest, relative_path)
diff --git a/src/lerim/skills/cli-reference.md b/src/lerim/skills/cli-reference.md
index 9784a27b..8badf23c 100644
--- a/src/lerim/skills/cli-reference.md
+++ b/src/lerim/skills/cli-reference.md
@@ -669,12 +669,53 @@ lerim auth logout
 
 ### `lerim skill` (host-only)
 
-Install Lerim skill files into supported agent directories.
+Install Lerim's own skill files, register watched instruction artifacts, and
+review evidence-backed skill update proposals.
 
-Installs to two locations:
+`install` copies Lerim's agent skill into two locations:
 - `~/.agents/skills/lerim/` — shared by Cursor, Codex, OpenCode, and others
 - `~/.claude/skills/lerim/` — Claude Code (reads only from its own directory)
 
 ```bash
 lerim skill install
 ```
+
+`target` registers any skill or instruction artifact Lerim should monitor. Pass
+a skill directory, `SKILL.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or related
+instruction file. New targets default to review mode; re-registering an existing
+target refreshes its manifest without resetting mode or auto-apply policy unless
+`--mode` is provided. Targets inside a registered project are scoped to that
+project; targets outside registered projects are global. Proposals can patch
+only files scanned as part of the registered target, with new skill-bundle files
+limited to `references/`, `reference/`, or `examples/`.
+
+```bash
+lerim skill target add ~/.agents/skills/clean-code --description "Keep simplification guidance current"
+lerim skill target list
+lerim skill target show it_abc123
+lerim skill target auto-apply it_abc123 --enable --risk low
+lerim skill target auto-apply it_abc123 --disable
+```
+
+`refresh` runs the LLM-backed stewardship pipeline for one target, scans relevant
+context records, and creates guarded proposals. Project-scoped targets only read
+records from their project. Global targets read records from registered projects.
+
+```bash
+lerim skill refresh it_abc123
+lerim skill refresh clean-code --record-limit 120 --json
+```
+
+`proposal` lists, inspects, applies, or rejects generated updates. Applying is
+allowed only for pending, guard-accepted, validation-passing proposals whose file
+baselines still match the current target files. Auto-apply is opt-in and also
+enforces changed-file, added-line, removed-line, risk, evidence, and surface
+policy limits.
+
+```bash
+lerim skill proposal list
+lerim skill proposal list --target-id it_abc123 --status pending_review
+lerim skill proposal show ip_abc123
+lerim skill proposal apply ip_abc123
+lerim skill proposal reject ip_abc123
+```
diff --git a/tests/README.md b/tests/README.md
index afd344ff..71517ff9 100644
--- a/tests/README.md
+++ b/tests/README.md
@@ -141,6 +141,7 @@ Rules:
 - MCP integration tests cover client config writers, dry-run/backup behavior, exposed MCP tool registration, in-process context search/brief calls, and trace-submit importer routing
 - Context store search tests cover derived-index generation metadata, fast-path retrieval, and stale-index repair without live LLM calls
 - Benchmark doc tests cover README launch links and visual references, duplicate demo media, public benchmark table values, artifact-path wording, and positioning guardrails for non-coding workflows
+- Skill stewardship tests cover artifact scanning, target registration refresh, project-scoped candidate loading, auto-apply guard policy, proposal lifecycle guards, proposal validation, and stale/partial apply safety
 
 ## Testing rules
 
diff --git a/tests/unit/agents/trace_ingestion/test_pipeline.py b/tests/unit/agents/trace_ingestion/test_pipeline.py
index 1ffcb8b7..2b3541aa 100644
--- a/tests/unit/agents/trace_ingestion/test_pipeline.py
+++ b/tests/unit/agents/trace_ingestion/test_pipeline.py
@@ -10,6 +10,7 @@
     apply_coding_retention_decisions,
     coding_eval_polish_to_synthesized,
 )
+from lerim.agents.trace_ingestion.pipeline import TraceIngestionPipeline
 from lerim.agents.trace_ingestion.summaries import (
     _episode_summary,
     _implementation_summary,
@@ -445,6 +446,33 @@ def test_trace_pipeline_filters_candidates_before_synthesis(tmp_path):
     assert "Filter durable signal" in decision["role_payload"]
 
 
+def test_role_annotation_skips_when_model_budget_is_exhausted():
+    """The optional role pass should not fail ingestion when earlier steps use the budget."""
+    pipeline = object.__new__(TraceIngestionPipeline)
+    pipeline.max_model_steps = 1
+    pipeline.progress = False
+    state = {
+        "llm_calls": 1,
+        "observations": [],
+        "synthesized": {
+            "durable_records": [
+                {
+                    "kind": "decision",
+                    "title": "Keep extraction stable",
+                    "body": "Earlier steps used the model budget.",
+                    "status": "active",
+                }
+            ]
+        },
+    }
+
+    pipeline.annotate_record_roles(state)
+
+    assert state["synthesized"]["durable_records"][0]["title"] == "Keep extraction stable"
+    assert state["observations"][-1]["action"] == "annotate_record_roles"
+    assert state["observations"][-1]["args"]["skipped_for_budget"] is True
+
+
 def test_coding_fixture_slot_preserves_source_backed_body(tmp_path):
     """Fixture constraints keep the actual constraint instead of a generic eval rule."""
     trace_path = tmp_path / "trace.jsonl"
diff --git a/tests/unit/context/test_store_search.py b/tests/unit/context/test_store_search.py
index d857828c..2ab9cd16 100644
--- a/tests/unit/context/test_store_search.py
+++ b/tests/unit/context/test_store_search.py
@@ -480,6 +480,57 @@ def embed_document(self, text: str) -> list[float]:
         assert len(hits) == 1
         assert hits[0][0] == target["record_id"]
 
+    def test_semantic_candidates_oversample_before_role_filtering(self, tmp_path, monkeypatch):
+        class _ScopedProvider:
+            model_id = "test-embed-v2"
+            embedding_dims = 4
+
+            def embed_query(self, text: str) -> list[float]:
+                return [1.0, 0.0, 0.0, 0.0] if "needle" in text.lower() else [0.0, 0.0, 0.0, 1.0]
+
+            def embed_document(self, text: str) -> list[float]:
+                lowered = text.lower()
+                if "closer distractor" in lowered:
+                    return [1.0, 0.0, 0.0, 0.0]
+                if "target procedure" in lowered:
+                    return [0.8, 0.2, 0.0, 0.0]
+                return [0.0, 0.0, 0.0, 1.0]
+
+        monkeypatch.setattr("lerim.context.store.get_embedding_provider", lambda: _ScopedProvider())
+        store, pid = _build_store_with_project(tmp_path, monkeypatch)
+        for index in range(30):
+            store.create_record(
+                project_id=pid,
+                session_id="sess_search",
+                kind="fact",
+                title=f"Closer distractor {index}",
+                body="This is the closer distractor for semantic search.",
+                record_role="general",
+            )
+        target = store.create_record(
+            project_id=pid,
+            session_id="sess_search",
+            kind="fact",
+            title="Target procedure",
+            body="This target procedure should survive semantic shortlist filtering.",
+            record_role="procedure",
+        )
+
+        hits = semantic_candidates(
+            store,
+            project_ids=[pid],
+            query="needle query",
+            kind_filters=None,
+            role_filters=["procedure"],
+            statuses=None,
+            valid_at=None,
+            include_archived=False,
+            limit=1,
+        )
+
+        assert len(hits) == 1
+        assert hits[0][0] == target["record_id"]
+
     def test_status_filter_active_only(self, tmp_path, monkeypatch):
         store, pid = _build_store_with_project(tmp_path, monkeypatch)
         store.create_record(
diff --git a/tests/unit/server/test_api.py b/tests/unit/server/test_api.py
index 8af086be..2c45f381 100644
--- a/tests/unit/server/test_api.py
+++ b/tests/unit/server/test_api.py
@@ -27,6 +27,7 @@
 
 import lerim.server.api as api_mod
 import lerim.server.docker_runtime as docker_mod
+import lerim.server.skill_api as skill_api_mod
 import lerim.sessions.catalog as catalog_mod
 from lerim.adapters.registry import KNOWN_PLATFORMS
 from lerim.context import ContextStore, resolve_project_identity
@@ -39,6 +40,7 @@
     api_project_add,
     api_project_list,
     api_project_remove,
+    api_record_filters,
     api_retry_all_dead_letter,
     api_skip_all_dead_letter,
     api_status,
@@ -379,6 +381,106 @@ def query(self, **kwargs):
     assert payload["message"] == "Context query storage is unavailable."
 
 
+def test_api_record_filters_reads_distinct_values_without_limit_sampling(
+    monkeypatch,
+    tmp_path,
+    mock_embeddings,
+) -> None:
+    """Record filters come from distinct DB values instead of a sampled records page."""
+    project_root = tmp_path / "project"
+    project_root.mkdir()
+    cfg = replace(make_config(tmp_path), projects={"project": str(project_root)})
+    identity = resolve_project_identity(project_root)
+    store = ContextStore(cfg.context_db_path)
+    store.initialize()
+    store.register_project(identity)
+    for index in range(505):
+        store.create_record(
+            project_id=identity.project_id,
+            session_id=None,
+            kind="fact" if index < 504 else "constraint",
+            title=f"Record {index}",
+            body="Body.",
+            record_role="general" if index < 504 else "procedure",
+            scope_label="project",
+        )
+    monkeypatch.setattr(api_mod, "get_config", lambda: cfg)
+
+    payload = api_record_filters()
+
+    assert payload["types"] == ["constraint", "fact"]
+    assert payload["roles"] == ["general", "procedure"]
+    assert payload["projects"] == ["project"]
+    assert payload["error"] is False
+
+
+def test_api_record_filters_use_registered_project_scope(
+    monkeypatch,
+    tmp_path,
+    mock_embeddings,
+) -> None:
+    """Filter options exclude stale records from unregistered projects."""
+    registered_root = tmp_path / "registered"
+    stale_root = tmp_path / "stale"
+    registered_root.mkdir()
+    stale_root.mkdir()
+    cfg = replace(make_config(tmp_path), projects={"registered": str(registered_root)})
+    registered_identity = resolve_project_identity(registered_root)
+    stale_identity = resolve_project_identity(stale_root)
+    store = ContextStore(cfg.context_db_path)
+    store.initialize()
+    store.register_project(registered_identity)
+    store.register_project(stale_identity)
+    store.create_record(
+        project_id=registered_identity.project_id,
+        session_id=None,
+        kind="fact",
+        title="Registered",
+        body="Registered body.",
+        record_role="procedure",
+        scope_label="registered",
+    )
+    store.create_record(
+        project_id=stale_identity.project_id,
+        session_id=None,
+        kind="constraint",
+        title="Stale",
+        body="Stale body.",
+        record_role="gotcha",
+        scope_label="stale",
+    )
+    monkeypatch.setattr(api_mod, "get_config", lambda: cfg)
+
+    payload = api_record_filters()
+
+    assert payload["types"] == ["fact"]
+    assert payload["roles"] == ["procedure"]
+    assert payload["projects"] == ["registered"]
+
+
+def test_api_skill_target_add_scopes_registered_project_paths(
+    monkeypatch,
+    tmp_path,
+    mock_embeddings,
+) -> None:
+    """Targets inside a registered project are saved with that project scope."""
+    project_root = tmp_path / "project"
+    project_root.mkdir()
+    skill = project_root / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n",
+        encoding="utf-8",
+    )
+    cfg = replace(make_config(tmp_path), projects={"project": str(project_root)})
+    monkeypatch.setattr(skill_api_mod, "get_config", lambda: cfg)
+
+    payload = skill_api_mod.api_skill_target_add(path=str(skill), name="demo")
+
+    assert payload["target"]["scope_type"] == "project"
+    assert payload["target"]["scope_id"] == resolve_project_identity(project_root).project_id
+
+
 def test_api_ingest_includes_queue_health_warning(monkeypatch, tmp_path) -> None:
     """Ingest API response surfaces degraded queue warning hints."""
     cfg = make_config(tmp_path)
diff --git a/tests/unit/server/test_cli_commands.py b/tests/unit/server/test_cli_commands.py
index 7f49fd6d..53cfe5b1 100644
--- a/tests/unit/server/test_cli_commands.py
+++ b/tests/unit/server/test_cli_commands.py
@@ -22,6 +22,7 @@
 import pytest
 
 from lerim.server import cli
+from lerim.server import cli_skill
 from tests.helpers import make_config
 
 
@@ -2265,7 +2266,7 @@ def test_skill_install_success(
             "agents": tmp_path / ".agents" / "skills" / "lerim",
             "claude": tmp_path / ".claude" / "skills" / "lerim",
         }
-        monkeypatch.setattr(cli, "_SKILL_TARGETS", targets)
+        monkeypatch.setattr(cli_skill, "_SKILL_TARGETS", targets)
 
         args = _ns(command="skill", skill_action="install")
         buf = io.StringIO()
diff --git a/tests/unit/skill_stewardship/test_artifacts.py b/tests/unit/skill_stewardship/test_artifacts.py
index a58a080d..ef47491a 100644
--- a/tests/unit/skill_stewardship/test_artifacts.py
+++ b/tests/unit/skill_stewardship/test_artifacts.py
@@ -4,6 +4,8 @@
 
 from pathlib import Path
 
+import pytest
+
 from lerim.skill_stewardship.artifacts import scan_instruction_artifact
 
 
@@ -38,3 +40,53 @@ def test_scans_plain_agents_file(tmp_path: Path) -> None:
     assert manifest.entry_file == "AGENTS.md"
     assert files[0].relative_path == "AGENTS.md"
 
+
+def test_scans_claude_context_file(tmp_path: Path) -> None:
+    """A standalone CLAUDE.md is classified as Claude context, not OpenCode."""
+    path = tmp_path / "CLAUDE.md"
+    path.write_text("# Claude Instructions\n\nUse the project tests.\n", encoding="utf-8")
+
+    _base, manifest, files = scan_instruction_artifact(path)
+
+    assert manifest.target_type == "claude_context"
+    assert manifest.entry_file == "CLAUDE.md"
+    assert files[0].relative_path == "CLAUDE.md"
+
+
+def test_scan_skips_support_symlink_outside_target(tmp_path: Path) -> None:
+    """Support files symlinked outside the artifact root do not crash scans."""
+    skill = tmp_path / "skill"
+    references = skill / "references"
+    outside = tmp_path / "outside.md"
+    references.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo.\n---\n\nUse small updates.\n",
+        encoding="utf-8",
+    )
+    outside.write_text("Outside target.\n", encoding="utf-8")
+    try:
+        (references / "outside.md").symlink_to(outside)
+    except OSError:
+        pytest.skip("filesystem does not allow symlink creation")
+
+    _base, _manifest, files = scan_instruction_artifact(skill)
+
+    assert {item.relative_path for item in files} == {"SKILL.md"}
+
+
+def test_scan_prunes_large_irrelevant_directories(tmp_path: Path) -> None:
+    """Directory targets do not walk dependency/build trees before applying caps."""
+    skill = tmp_path / "skill"
+    references = skill / "references"
+    ignored = references / "node_modules" / "package"
+    ignored.mkdir(parents=True)
+    (skill / "SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo.\n---\n\nUse small updates.\n",
+        encoding="utf-8",
+    )
+    (references / "guide.md").write_text("Useful guidance.\n", encoding="utf-8")
+    (ignored / "ignored.md").write_text("Should not be scanned.\n", encoding="utf-8")
+
+    _base, _manifest, files = scan_instruction_artifact(skill)
+
+    assert {item.relative_path for item in files} == {"SKILL.md", "references/guide.md"}
diff --git a/tests/unit/skill_stewardship/test_repository_and_pipeline.py b/tests/unit/skill_stewardship/test_repository_and_pipeline.py
index 42a1363c..56be516e 100644
--- a/tests/unit/skill_stewardship/test_repository_and_pipeline.py
+++ b/tests/unit/skill_stewardship/test_repository_and_pipeline.py
@@ -4,9 +4,13 @@
 
 from pathlib import Path
 
-from lerim.context import ContextStore
+import pytest
+
+from lerim.context import ContextStore, ProjectIdentity
+from lerim.skill_stewardship import patching
 from lerim.skill_stewardship.artifacts import scan_instruction_artifact
-from lerim.skill_stewardship.pipeline import guard_proposal, hydrate_patch_text
+from lerim.skill_stewardship.patching import apply_proposal
+from lerim.skill_stewardship.pipeline import _candidate_records, guard_proposal, hydrate_patch_text
 from lerim.skill_stewardship.repository import SkillStewardshipRepository
 from lerim.skill_stewardship.schemas import AutoApplyPolicy, SkillPatch, SkillProposalDraft
 from lerim.skill_stewardship.validation import validate_proposal
@@ -32,6 +36,62 @@ def test_repository_registers_target_and_files(tmp_path: Path) -> None:
     assert repository.target_files(target.target_id)[0].relative_path == "SKILL.md"
 
 
+def test_repository_preserves_mode_and_policy_when_reregistering(tmp_path: Path) -> None:
+    """Target refresh keeps existing mode and policy unless the caller replaces them."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    repository.update_target_mode(
+        target.target_id,
+        "auto_apply",
+        AutoApplyPolicy(enabled=True, max_added_lines=7),
+    )
+
+    refreshed = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+
+    assert refreshed.update_mode == "auto_apply"
+    assert refreshed.auto_apply_policy.enabled is True
+    assert refreshed.auto_apply_policy.max_added_lines == 7
+
+
+def test_repository_rejects_invalid_mode_before_write(tmp_path: Path) -> None:
+    """Invalid update modes fail before poisoning persisted target rows."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    repository.update_target_mode(target.target_id, "auto_apply", AutoApplyPolicy(enabled=True))
+
+    with pytest.raises(ValueError, match="invalid_update_mode"):
+        repository.update_target_mode(target.target_id, "instant")
+
+    assert repository.get_target(target.target_id).update_mode == "auto_apply"
+
+
+def test_repository_refresh_removes_stale_tracked_files(tmp_path: Path) -> None:
+    """A scan refresh deletes file rows that no longer belong to the target."""
+    skill = tmp_path / "skill"
+    references = skill / "references"
+    references.mkdir(parents=True)
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    stale = references / "old.md"
+    stale.write_text("Old guidance.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    stale.unlink()
+    base, manifest, files = scan_instruction_artifact(skill)
+
+    repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+
+    assert {item.relative_path for item in repository.target_files(target.target_id)} == {"SKILL.md"}
+
+
 def test_guard_allows_low_risk_auto_apply_with_evidence() -> None:
     """Low-risk bounded edits can become auto-apply eligible when policy allows it."""
     draft = SkillProposalDraft(
@@ -57,6 +117,67 @@ def test_guard_allows_low_risk_auto_apply_with_evidence() -> None:
     assert result.auto_apply_eligible is True
 
 
+def test_guard_respects_frontmatter_auto_apply_policy(tmp_path: Path) -> None:
+    """Frontmatter edits can be reviewed but do not auto-apply under the default policy."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    original = "---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n"
+    changed = "---\nname: demo\ndescription: Changed.\n---\n\nUse evidence.\n"
+    (skill / "SKILL.md").write_text(original, encoding="utf-8")
+    _base, manifest, _files = scan_instruction_artifact(skill)
+    draft = SkillProposalDraft(
+        title="Adjust metadata",
+        summary="Changes metadata.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported by record.",
+                evidence_record_ids=["rec_1"],
+                before_text=original,
+                after_text=changed,
+                diff_text="",
+            )
+        ],
+    )
+
+    result = guard_proposal(draft=draft, policy=AutoApplyPolicy(enabled=True), manifest=manifest)
+
+    assert result.accepted is True
+    assert result.auto_apply_eligible is False
+    assert any("frontmatter" in reason for reason in result.reasons)
+
+
+def test_guard_blocks_large_removals_from_auto_apply() -> None:
+    """Deletion-heavy patches stay manual even when net added lines are small."""
+    before = "\n".join(f"line {index}" for index in range(30)) + "\n"
+    draft = SkillProposalDraft(
+        title="Shrink guidance",
+        summary="Removes most existing guidance.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="AGENTS.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported by record.",
+                evidence_record_ids=["rec_1"],
+                before_text=before,
+                after_text="keep one line\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = guard_proposal(draft=draft, policy=AutoApplyPolicy(enabled=True, max_removed_lines=5))
+
+    assert result.accepted is True
+    assert result.auto_apply_eligible is False
+    assert any("removed lines" in reason for reason in result.reasons)
+
+
 def test_guard_blocks_missing_evidence() -> None:
     """A patch without record evidence stays out of the review path."""
     draft = SkillProposalDraft(
@@ -112,6 +233,155 @@ def test_validation_rejects_frontmatter_removal(tmp_path: Path) -> None:
     assert any("frontmatter" in error for error in result.errors)
 
 
+def test_validation_rejects_empty_instruction_body(tmp_path: Path) -> None:
+    """Instruction edits cannot reduce the target to an empty body."""
+    path = tmp_path / "AGENTS.md"
+    path.write_text("# Project Instructions\n\nRun tests.\n", encoding="utf-8")
+    base, manifest, _files = scan_instruction_artifact(path)
+    draft = SkillProposalDraft(
+        title="Empty instructions",
+        summary="Accidentally deletes all guidance.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="AGENTS.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                before_text="# Project Instructions\n\nRun tests.\n",
+                after_text="",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+
+    assert result.ok is False
+    assert any("instruction body cannot be empty" in error for error in result.errors)
+
+
+def test_validation_rejects_duplicate_patch_paths(tmp_path: Path) -> None:
+    """One proposal cannot contain competing edits for the same file."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    original = "---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n"
+    (skill / "SKILL.md").write_text(original, encoding="utf-8")
+    base, manifest, _files = scan_instruction_artifact(skill)
+    patch = SkillPatch(
+        relative_path="SKILL.md",
+        change_type="modify",
+        risk="low",
+        rationale="Supported.",
+        evidence_record_ids=["rec_1"],
+        before_text=original,
+        after_text=original + "Keep updates small.\n",
+        diff_text="",
+    )
+    draft = SkillProposalDraft(
+        title="Duplicate",
+        summary="Contains duplicate patches.",
+        risk_level="low",
+        patches=[patch, patch],
+    )
+
+    result = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+
+    assert result.ok is False
+    assert any("duplicate patch path" in error for error in result.errors)
+
+
+def test_validation_rejects_modify_for_missing_file(tmp_path: Path) -> None:
+    """Missing files must be explicit create patches, not silent modify writes."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\n# Demo\n", encoding="utf-8")
+    base, manifest, _files = scan_instruction_artifact(skill)
+    draft = SkillProposalDraft(
+        title="Bad missing edit",
+        summary="Tries to modify a missing file.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="references/new.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                before_text="",
+                after_text="New guidance.\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+
+    assert result.ok is False
+    assert any("missing file must use create" in error for error in result.errors)
+
+
+def test_validation_rejects_existing_file_outside_registered_artifact(tmp_path: Path) -> None:
+    """File targets cannot write unrelated siblings in the containing directory."""
+    path = tmp_path / "AGENTS.md"
+    path.write_text("# Project Instructions\n\nRun tests.\n", encoding="utf-8")
+    sibling = tmp_path / "README.md"
+    sibling.write_text("# Project\n", encoding="utf-8")
+    base, manifest, _files = scan_instruction_artifact(path)
+    draft = SkillProposalDraft(
+        title="Bad sibling edit",
+        summary="Tries to edit an unregistered sibling file.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="README.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                before_text="# Project\n",
+                after_text="# Project\n\nNew instructions.\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = validate_proposal(base_path=base, manifest=manifest, proposal=draft)
+
+    assert result.ok is False
+    assert any("not part of the registered instruction artifact" in error for error in result.errors)
+
+
+def test_guard_keeps_unregistered_paths_out_of_auto_apply(tmp_path: Path) -> None:
+    """The auto-apply guard refuses paths outside the scanned instruction artifact."""
+    path = tmp_path / "AGENTS.md"
+    path.write_text("# Project Instructions\n\nRun tests.\n", encoding="utf-8")
+    _base, manifest, _files = scan_instruction_artifact(path)
+    draft = SkillProposalDraft(
+        title="Bad sibling edit",
+        summary="Tries to edit an unregistered sibling file.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="README.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                after_text="# Project\n\nNew instructions.\n",
+                diff_text="",
+            )
+        ],
+    )
+
+    result = guard_proposal(draft=draft, policy=AutoApplyPolicy(enabled=True), manifest=manifest)
+
+    assert result.accepted is True
+    assert result.auto_apply_eligible is False
+    assert any("outside registered instruction artifact" in reason for reason in result.reasons)
+
+
 def test_hydrate_patch_text_recomputes_before_text_and_diff(tmp_path: Path) -> None:
     """Edited proposals get fresh file content and unified diffs before validation."""
     skill = tmp_path / "skill"
@@ -139,3 +409,278 @@ def test_hydrate_patch_text_recomputes_before_text_and_diff(tmp_path: Path) -> N
     assert hydrated.patches[0].before_text == "Use simple code.\n"
     assert "--- a/SKILL.md" in hydrated.patches[0].diff_text
     assert "+Remove wrappers that only forward." in hydrated.patches[0].diff_text
+
+
+def test_apply_rejects_non_review_proposal(tmp_path: Path) -> None:
+    """Rejected proposals cannot be applied later by CLI or dashboard calls."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="rejected")
+
+    with pytest.raises(ValueError, match="status cannot be applied"):
+        apply_proposal(repository=repository, proposal=proposal, applied_by="test")
+
+
+def test_apply_rejects_failed_validation_payload(tmp_path: Path) -> None:
+    """A pending proposal with failed validation metadata cannot write files."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    draft = SkillProposalDraft(
+        title="Invalid edit",
+        summary="Tries to modify a missing file.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="references/missing.md",
+                change_type="modify",
+                risk="low",
+                rationale="Bad.",
+                evidence_record_ids=["rec_1"],
+                after_text="New guidance.\n",
+                diff_text="",
+            )
+        ],
+    )
+    hydrated = hydrate_patch_text(base=base, draft=draft)
+    proposal = repository.save_proposal(
+        run_id=repository.create_run(target.target_id),
+        target_id=target.target_id,
+        draft=hydrated,
+        guard=guard_proposal(draft=hydrated, policy=AutoApplyPolicy(enabled=True), manifest=manifest),
+        validation=validate_proposal(base_path=base, manifest=manifest, proposal=hydrated),
+        status="pending_review",
+    )
+
+    with pytest.raises(ValueError, match="validation has not passed"):
+        apply_proposal(repository=repository, proposal=proposal, applied_by="test")
+
+
+def test_apply_rejects_stale_patch_baseline(tmp_path: Path) -> None:
+    """Apply fails when the target file changed after proposal generation."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="pending_review")
+    target = repository.get_target(proposal.target_id)
+    Path(target.path, "SKILL.md").write_text(
+        "---\nname: demo\ndescription: Demo.\n---\n\nChanged elsewhere.\n",
+        encoding="utf-8",
+    )
+
+    with pytest.raises(ValueError, match="target changed"):
+        apply_proposal(repository=repository, proposal=proposal, applied_by="test")
+
+
+def test_repository_edit_updates_visible_proposal_metadata(tmp_path: Path) -> None:
+    """Proposal list metadata follows the edited patch payload."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="pending_review")
+    target = repository.get_target(proposal.target_id)
+    draft = SkillProposalDraft.model_validate(
+        {
+            **proposal.patch_json,
+            "title": "Edited title",
+            "summary": "Edited summary.",
+            "risk_level": "medium",
+        }
+    )
+
+    updated = repository.update_proposal_patch(
+        proposal_id=proposal.proposal_id,
+        draft=draft,
+        validation=validate_proposal(base_path=Path(target.path), manifest=target.manifest, proposal=draft),
+        guard=guard_proposal(draft=draft, policy=target.auto_apply_policy, manifest=target.manifest),
+    )
+
+    assert updated.title == "Edited title"
+    assert updated.summary == "Edited summary."
+    assert updated.risk_level == "medium"
+
+
+def test_repository_rejects_edits_to_terminal_proposals(tmp_path: Path) -> None:
+    """Applied/rejected proposals cannot be resurrected by patch edits."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="applied")
+    draft = SkillProposalDraft.model_validate(proposal.patch_json)
+    target = repository.get_target(proposal.target_id)
+
+    with pytest.raises(ValueError, match="cannot be edited"):
+        repository.update_proposal_patch(
+            proposal_id=proposal.proposal_id,
+            draft=draft,
+            validation=validate_proposal(base_path=Path(target.path), manifest=target.manifest, proposal=draft),
+            guard=guard_proposal(draft=draft, policy=target.auto_apply_policy, manifest=target.manifest),
+        )
+
+    assert repository.get_proposal(proposal.proposal_id).status == "applied"
+
+
+def test_repository_rejects_terminal_status_transition(tmp_path: Path) -> None:
+    """Rejected proposals stay terminal."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="rejected")
+
+    with pytest.raises(ValueError, match="terminal"):
+        repository.set_proposal_status(proposal.proposal_id, "pending_review")
+
+    assert repository.get_proposal(proposal.proposal_id).status == "rejected"
+
+
+def test_apply_rolls_back_files_when_metadata_write_fails(monkeypatch, tmp_path: Path) -> None:
+    """A failed multi-file apply restores every file it already touched."""
+    skill = tmp_path / "skill"
+    references = skill / "references"
+    references.mkdir(parents=True)
+    skill_text = "---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n"
+    reference_text = "Old reference.\n"
+    (skill / "SKILL.md").write_text(skill_text, encoding="utf-8")
+    (references / "notes.md").write_text(reference_text, encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    draft = SkillProposalDraft(
+        title="Two edits",
+        summary="Edits two files.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported.",
+                evidence_record_ids=["rec_1"],
+                after_text=skill_text + "Keep updates small.\n",
+                diff_text="",
+            ),
+            SkillPatch(
+                relative_path="references/notes.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported.",
+                evidence_record_ids=["rec_1"],
+                after_text="New reference.\n",
+                diff_text="",
+            ),
+        ],
+    )
+    hydrated = hydrate_patch_text(base=base, draft=draft)
+    proposal = repository.save_proposal(
+        run_id=repository.create_run(target.target_id),
+        target_id=target.target_id,
+        draft=hydrated,
+        guard=guard_proposal(draft=hydrated, policy=AutoApplyPolicy(enabled=True), manifest=manifest),
+        validation=validate_proposal(base_path=base, manifest=manifest, proposal=hydrated),
+        status="pending_review",
+    )
+    monkeypatch.setattr(
+        patching,
+        "_record_applied_versions",
+        lambda **_kwargs: (_ for _ in ()).throw(RuntimeError("db write failed")),
+    )
+
+    with pytest.raises(RuntimeError, match="db write failed"):
+        apply_proposal(repository=repository, proposal=proposal, applied_by="test")
+
+    assert (skill / "SKILL.md").read_text(encoding="utf-8") == skill_text
+    assert (references / "notes.md").read_text(encoding="utf-8") == reference_text
+    assert repository.get_proposal(proposal.proposal_id).status == "pending_review"
+
+
+def test_stale_apply_does_not_restore_already_applied_files(monkeypatch, tmp_path: Path) -> None:
+    """A stale concurrent apply exits before writes, leaving applied disk content alone."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="pending_review")
+    target = repository.get_target(proposal.target_id)
+    draft = SkillProposalDraft.model_validate(proposal.patch_json)
+    applied_text = draft.patches[0].after_text
+    target_file = Path(target.path, "SKILL.md")
+    target_file.write_text(applied_text, encoding="utf-8")
+    repository.set_proposal_status(proposal.proposal_id, "applied")
+    monkeypatch.setattr(
+        patching,
+        "_prepare_patches",
+        lambda **_kwargs: pytest.fail("stale apply should not prepare or restore files"),
+    )
+
+    with pytest.raises(ValueError, match="status cannot be applied"):
+        apply_proposal(repository=repository, proposal=proposal, applied_by="second")
+
+    assert target_file.read_text(encoding="utf-8") == applied_text
+
+
+def test_apply_snapshots_under_workspace_root(tmp_path: Path) -> None:
+    """Snapshots are run artifacts under the canonical workspace tree."""
+    repository, proposal = _saved_valid_proposal(tmp_path, status="pending_review")
+    workspace = tmp_path / "workspace"
+
+    apply_proposal(repository=repository, proposal=proposal, applied_by="test", workspace_root=workspace)
+
+    with repository.context_store.connect() as conn:
+        row = conn.execute("SELECT snapshot_path FROM instruction_versions").fetchone()
+    assert row is not None
+    assert str(row["snapshot_path"]).startswith(str(workspace / "skill-snapshots"))
+
+
+def test_candidate_records_can_be_project_scoped(tmp_path: Path) -> None:
+    """Skill refresh candidates stay inside the target project when scoped."""
+    store = ContextStore(tmp_path / "context.sqlite3")
+    store.initialize()
+    store.register_project(ProjectIdentity(project_id="proj_a", project_slug="a", repo_path=tmp_path / "a"))
+    store.register_project(ProjectIdentity(project_id="proj_b", project_slug="b", repo_path=tmp_path / "b"))
+    store.create_record(
+        project_id="proj_a",
+        session_id=None,
+        kind="fact",
+        title="A procedure",
+        body="A body.",
+        record_role="procedure",
+        scope_type="project",
+        scope_id="proj_a",
+        scope_label="a",
+    )
+    store.create_record(
+        project_id="proj_b",
+        session_id=None,
+        kind="fact",
+        title="B procedure",
+        body="B body.",
+        record_role="procedure",
+        scope_type="project",
+        scope_id="proj_b",
+        scope_label="b",
+    )
+
+    rows = _candidate_records(store, limit=10, project_ids=["proj_a"])
+
+    assert {row["project_id"] for row in rows} == {"proj_a"}
+
+
+def _saved_valid_proposal(tmp_path: Path, *, status: str):
+    """Create a repository and one valid persisted proposal for apply tests."""
+    skill = tmp_path / "skill"
+    skill.mkdir()
+    (skill / "SKILL.md").write_text("---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\n", encoding="utf-8")
+    base, manifest, files = scan_instruction_artifact(skill)
+    repository = SkillStewardshipRepository(ContextStore(tmp_path / "context.sqlite3"))
+    target = repository.upsert_target(name="demo", path=base, description=None, manifest=manifest, files=files)
+    draft = SkillProposalDraft(
+        title="Improve evidence",
+        summary="Adds one evidence reminder.",
+        risk_level="low",
+        patches=[
+            SkillPatch(
+                relative_path="SKILL.md",
+                change_type="modify",
+                risk="low",
+                rationale="Supported by record.",
+                evidence_record_ids=["rec_1"],
+                after_text="---\nname: demo\ndescription: Demo.\n---\n\nUse evidence.\nKeep updates small.\n",
+                diff_text="",
+            )
+        ],
+    )
+    hydrated = hydrate_patch_text(base=base, draft=draft)
+    proposal = repository.save_proposal(
+        run_id=repository.create_run(target.target_id),
+        target_id=target.target_id,
+        draft=hydrated,
+        guard=guard_proposal(draft=hydrated, policy=AutoApplyPolicy(enabled=True), manifest=manifest),
+        validation=validate_proposal(base_path=base, manifest=manifest, proposal=hydrated),
+        status=status,
+    )
+    return repository, proposal

From ce522e05e50eabe6fb928e3b79117699630ffb1e Mon Sep 17 00:00:00 2001
From: Isaac Kargar <kargarisaac@gmail.com>
Date: Sun, 31 May 2026 14:01:59 +0300
Subject: [PATCH 3/3] chore: whitelist skill stewardship contracts

---
 vulture_whitelist.py | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/vulture_whitelist.py b/vulture_whitelist.py
index 8d0aafa8..ab8b1f79 100644
--- a/vulture_whitelist.py
+++ b/vulture_whitelist.py
@@ -46,6 +46,8 @@
 retrieval_json  # noqa
 brief  # noqa
 records_json  # noqa
+target_json  # noqa
+files_json  # noqa
 batch_id  # noqa
 source_record_id  # noqa
 target_record_id  # noqa
@@ -100,6 +102,9 @@
 keep  # noqa
 save_any  # noqa
 session_reason  # noqa
+allowed_update_surfaces  # noqa
+high_risk_surfaces  # noqa
+diff_text  # noqa
 
 # Pydantic validators registered by decorators
 validate_level  # noqa