Design-system delivery, the contrast fix, recall scoping, and backup coverage (#93)

.forgejo/workflows/ci.yml

@@ -165,7 +165,18 @@ jobs:
       # ruff is pre-installed in the ci-python image — no install
       # step needed, lint runs in ~2s.
       - name: Lint
-        run: ruff check src/
+        run: ruff check src/ scripts/
+
+      # Design tokens: does the frontend's CSS agree with the stylesheet the
+      # design system generates? Fails only on an unresolvable var() reference —
+      # that count is at zero, so this is a ratchet rather than a backlog. The
+      # literal findings are printed, not gated; hundreds exist and a
+      # permanently-red job is one nobody reads.
+      #
+      # Stdlib only, no install, no network: the source of truth is theme.css,
+      # which is generated from the design system and committed.
+      - name: Design token check
+        run: python3 scripts/check_design_tokens.py --report-literals
 
   test:
     name: Python tests

frontend/src/App.vue

@@ -255,7 +255,7 @@ onUnmounted(() => {
   z-index: 9999;
   padding: 0.4rem 0.75rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: 0 0 4px 4px;
   font-size: 0.875rem;
   text-decoration: none;

frontend/src/assets/editor-shared.css

@@ -56,7 +56,7 @@
 .btn-save {
   padding: 0.45rem 1.1rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -76,7 +76,7 @@
 .btn-delete {
   padding: 0.45rem 1rem;
   background: var(--color-action-destructive);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -187,12 +187,12 @@
 }
 .tag-pill:hover:not(:disabled) {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .tag-pill.applied {
   background: var(--color-success, #2ecc71);
   border-color: var(--color-success, #2ecc71);
-  color: #fff;
+  color: var(--fs-text-on-action);
   cursor: default;
 }
 .tag-check {
@@ -345,7 +345,7 @@
 .btn-generate {
   padding: 0.4rem 0.9rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -478,7 +478,7 @@
 .btn-accept {
   padding: 0.4rem 1rem;
   background: var(--color-success);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -537,7 +537,7 @@
 }
 .modal-btn-danger {
   background: var(--color-danger);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-color: var(--color-danger);
 }
 
@@ -548,7 +548,7 @@
   transform: translateX(-50%);
   padding: 0.3rem 0.75rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/assets/theme.css

@@ -132,9 +132,10 @@
   --fs-table-stripe: color-mix(in srgb, var(--fs-text-primary) 3%, transparent);
 
   /* text */
-  --fs-text-primary: #E8E4D8;  /* also the text colour on filled action buttons */
+  --fs-text-primary: #E8E4D8;  /* body, headings, labels — inverts by mode */
   --fs-text-secondary: #C2BFB4;
   --fs-text-tertiary: #9C9A92;
+  --fs-text-on-action: #E8E4D8;  /* text on a filled colour — NOT mode-dependent */
 
   /* type */
   --fs-size-display: 40px;
@@ -178,6 +179,14 @@
   --fs-text-tertiary: #9A9890;
 }
 
+/* SUPERSEDES — write the token, not the literal.
+ * #fff -> --fs-text-on-action
+ * #ffffff -> --fs-text-on-action
+ * white -> --fs-text-on-action
+ * bold -> --fs-weight-medium
+ * bolder -> --fs-weight-medium
+ */
+
 /* ==========================================================================
    COMPATIBILITY ALIASES — the app's historical names, pointing at the system.
 
@@ -282,7 +291,10 @@
      visual shifts exactly where a fallback had drifted; that shift IS the fix.
      ------------------------------------------------------------------ */
   --color-accent: var(--fs-accent);
-  --color-accent-fg: var(--fs-text-primary);
+  /* Foreground ON the accent, so it follows the accent's mode-independence,
+     not the page text's. Pointing this at --fs-text-primary made it invert to
+     obsidian on light — over a mid-tone accent, well under the AA floor. */
+  --color-accent-fg: var(--fs-text-on-action);
   --color-hover: var(--fs-surface-hover);
   --color-bg-hover: var(--fs-surface-hover);
   --color-bg-tertiary: var(--fs-surface-hover);

frontend/src/components/HistoryPanel.vue

@@ -396,7 +396,7 @@ onMounted(loadVersions);
 .btn-restore {
   padding: 0.45rem 1rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/components/InlineAssistPanel.vue

@@ -192,7 +192,7 @@ const markers: Record<DiffLine["type"], string> = {
 }
 .iap-btn-accept {
   background: var(--color-success, #22c55e);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .iap-btn-accept:hover { opacity: 0.85; }
 

frontend/src/components/NotificationBell.vue

@@ -82,7 +82,7 @@ onUnmounted(() => {
   top: -5px;
   right: -5px;
   background: var(--color-danger, #ef4444);
-  color: #fff;
+  color: var(--fs-text-on-action);
   font-size: 0.6rem;
   font-weight: 700;
   min-width: 16px;

frontend/src/components/PaginationBar.vue

@@ -90,7 +90,7 @@ function goToPage(page: number) {
 }
 .page-btn.active {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-color: var(--color-primary);
 }
 .ellipsis {

frontend/src/components/ShareDialog.vue

@@ -268,7 +268,7 @@ onMounted(async () => {
 .share-tab.active {
   background: var(--color-primary);
   border-color: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 
 .share-target-form {
@@ -339,7 +339,7 @@ onMounted(async () => {
 .btn-add-share {
   padding: 0.45rem 1rem;
   background: var(--gradient-cta);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: 6px;
   font-size: 0.85rem;

frontend/src/components/SystemsSection.vue

@@ -390,7 +390,7 @@ async function confirmDelete() {
 .btn-confirm {
   padding: 0.35rem 0.8rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -405,7 +405,7 @@ async function confirmDelete() {
   padding: 0.35rem 0.8rem;
   background: var(--color-action-secondary);
   border: none;
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: var(--radius-sm);
   cursor: pointer;
   font-size: 0.82rem;
@@ -555,6 +555,6 @@ async function confirmDelete() {
   font-family: inherit;
 }
 .modal-btn:hover { background: var(--color-bg); }
-.modal-btn-danger { background: var(--color-action-destructive); border-color: var(--color-action-destructive); color: #fff; }
+.modal-btn-danger { background: var(--color-action-destructive); border-color: var(--color-action-destructive); color: var(--fs-text-on-action); }
 .modal-btn-danger:hover { background: var(--color-action-destructive-hover); border-color: var(--color-action-destructive-hover); }
 </style>

frontend/src/components/TaskLogSection.vue

@@ -217,7 +217,7 @@ onMounted(loadLogs);
 
 .log-duration-badge {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: 99px;
   padding: 0.1rem 0.5rem;
   font-size: 0.72rem;
@@ -312,7 +312,7 @@ onMounted(loadLogs);
   margin-left: auto;
   padding: 0.3rem 0.75rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/components/ToastNotification.vue

@@ -36,7 +36,7 @@ const toastStore = useToastStore();
   gap: 0.5rem;
   padding: 0.75rem 1rem;
   border-radius: 6px;
-  color: #fff;
+  color: var(--fs-text-on-action);
   font-size: 0.9rem;
   box-shadow: 0 2px 8px var(--color-shadow);
   min-width: 200px;
@@ -54,7 +54,7 @@ const toastStore = useToastStore();
   padding: 0 0.15rem;
 }
 .toast-close:hover {
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .toast--success {
   background: var(--color-toast-success);

frontend/src/components/VersionHistorySection.vue

@@ -241,7 +241,7 @@ function restore() {
   border-radius: var(--radius-sm);
   padding: 0.25rem 0.6rem;
   font-size: 0.78rem;
-  color: #fff;
+  color: var(--fs-text-on-action);
   cursor: pointer;
   font-family: inherit;
 }

frontend/src/components/WorkspaceNoteEditor.vue

@@ -643,7 +643,7 @@ defineExpose({ reload: loadProjectNotes });
   border-radius: 3px;
   transition: background 0.15s, color 0.15s;
 }
-.btn-confirm-delete:hover:not(:disabled) { background: var(--color-action-destructive); color: #fff; }
+.btn-confirm-delete:hover:not(:disabled) { background: var(--color-action-destructive); color: var(--fs-text-on-action); }
 .btn-confirm-delete:disabled { opacity: 0.5; cursor: default; }
 
 .btn-cancel-delete {
@@ -671,7 +671,7 @@ defineExpose({ reload: loadProjectNotes });
 
 .btn-confirm {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: 4px;
   padding: 0.15rem 0.35rem;
@@ -733,7 +733,7 @@ defineExpose({ reload: loadProjectNotes });
 /* Moss action-primary per Hybrid */
 .btn-save {
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: 5px;
   padding: 0.25rem 0.7rem;

frontend/src/components/WorkspaceTaskPanel.vue

@@ -398,7 +398,7 @@ defineExpose({ reload: loadAll });
 
 .btn-add {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: 5px;
   padding: 0.28rem 0.55rem;
@@ -590,7 +590,7 @@ defineExpose({ reload: loadAll });
   margin-left: 0.25rem;
   transition: background 0.15s, color 0.15s;
 }
-.btn-delete-confirm:hover:not(:disabled) { background: var(--color-action-destructive); color: #fff; }
+.btn-delete-confirm:hover:not(:disabled) { background: var(--color-action-destructive); color: var(--fs-text-on-action); }
 .btn-delete-confirm:disabled { opacity: 0.5; cursor: default; }
 
 .btn-delete-cancel {

frontend/src/views/DesignSystemsView.vue

@@ -1273,14 +1273,9 @@ textarea.input {
   border: 1px solid transparent;
 }
 
-/* Background matches the house convention (--color-action-primary, as in
-   ProjectListView and four others). The text colour deliberately does NOT:
-   every existing copy uses `color: #fff`, which is 67 live violations of the
-   rule that pure white is never text (#2275). Parchment is what the rulebook
-   actually specifies. */
 .btn-primary {
   background: var(--color-action-primary);
-  color: #E8E4D8;
+  color: var(--fs-text-on-action);
 }
 
 .btn-primary:not(:disabled):hover {

frontend/src/views/ForgotPasswordView.vue

@@ -141,7 +141,7 @@ async function handleSubmit() {
   width: 100%;
   padding: 0.6rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/KnowledgeView.vue

@@ -574,7 +574,7 @@ onUnmounted(() => {
   border-radius: 10px;
   border: none;
   background: var(--gradient-cta);
-  color: #fff;
+  color: var(--fs-text-on-action);
   cursor: pointer;
   font-size: 0.85rem;
   font-weight: 500;

frontend/src/views/LoginView.vue

@@ -180,7 +180,7 @@ function loginWithOAuth() {
   width: 100%;
   padding: 0.6rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/NoteEditorView.vue

@@ -748,7 +748,7 @@ onUnmounted(() => assist.clearSelection());
   cursor: pointer;
   font-family: inherit;
 }
-.btn-link-all:hover { background: var(--color-primary); color: #fff; }
+.btn-link-all:hover { background: var(--color-primary); color: var(--fs-text-on-action); }
 
 .link-suggest-list {
   display: flex;

frontend/src/views/NoteViewerView.vue

@@ -354,7 +354,7 @@ async function convertToTask() {
   border: none;
   border-radius: var(--radius-sm);
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   text-decoration: none;
   cursor: pointer;
   font-size: 0.875rem;
@@ -363,14 +363,14 @@ async function convertToTask() {
 }
 .btn-edit:hover {
   background: var(--color-action-primary-hover);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 /* Convert + Share: Bronze action-secondary — alternate paths */
 .btn-convert {
   margin-left: auto;
   padding: 0.3rem 0.75rem;
   background: var(--color-action-secondary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -388,7 +388,7 @@ async function convertToTask() {
   background: var(--color-action-secondary);
   border: none;
   border-radius: var(--radius-sm);
-  color: #fff;
+  color: var(--fs-text-on-action);
   cursor: pointer;
   font-size: 0.85rem;
   font-family: inherit;

frontend/src/views/ProjectListView.vue

@@ -287,7 +287,7 @@ function overallPct(project: Project): { total: number; pct: number } {
 .btn-primary {
   padding: 0.45rem 1rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -341,7 +341,7 @@ function overallPct(project: Project): { total: number; pct: number } {
 .empty-title { font-size: 1rem; font-weight: 500; color: var(--color-text-secondary); margin: 0 0 0.35rem; }
 .empty-sub { font-size: 0.85rem; margin: 0 0 1rem; }
 .empty-action { display: inline-block; padding: 0.4rem 1rem; border: 1px solid var(--color-primary); border-radius: var(--radius-sm); color: var(--color-primary); background: none; cursor: pointer; font-size: 0.85rem; transition: background 0.15s, color 0.15s; }
-.empty-action:hover { background: var(--color-primary); color: #fff; }
+.empty-action:hover { background: var(--color-primary); color: var(--fs-text-on-action); }
 
 .skeleton-card {
   height: 140px;
@@ -594,7 +594,7 @@ function overallPct(project: Project): { total: number; pct: number } {
 .modal-btn-primary {
   background: var(--color-primary);
   border-color: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .modal-btn-primary:hover:not(:disabled) {
   opacity: 0.9;

frontend/src/views/ProjectView.vue

@@ -879,7 +879,7 @@ async function confirmDelete() {
   gap: 0.35rem;
   padding: 0.45rem 1rem;
   background: var(--gradient-cta);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   font-size: 0.875rem;
@@ -888,14 +888,14 @@ async function confirmDelete() {
   box-shadow: var(--glow-cta);
   transition: box-shadow 0.15s, opacity 0.15s;
 }
-.btn-workspace:hover { box-shadow: var(--glow-cta-hover); opacity: 0.95; color: #fff; }
+.btn-workspace:hover { box-shadow: var(--glow-cta-hover); opacity: 0.95; color: var(--fs-text-on-action); }
 
 /* Share: Bronze action-secondary — alternate path */
 .btn-share {
   padding: 0.4rem 0.8rem;
   background: var(--color-action-secondary);
   border: none;
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: var(--radius-sm);
   cursor: pointer;
   font-size: 0.85rem;
@@ -917,7 +917,7 @@ async function confirmDelete() {
   font-family: inherit;
   transition: background 0.15s, color 0.15s;
 }
-.btn-danger-outline:hover { background: var(--color-action-destructive); color: #fff; }
+.btn-danger-outline:hover { background: var(--color-action-destructive); color: var(--fs-text-on-action); }
 
 .error-msg { color: var(--color-danger); font-size: 0.9rem; }
 
@@ -1065,7 +1065,7 @@ async function confirmDelete() {
 .btn-save-panel {
   padding: 0.45rem 0.9rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -1151,7 +1151,7 @@ async function confirmDelete() {
 .btn-ms-confirm {
   padding: 0.3rem 0.65rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -1165,7 +1165,7 @@ async function confirmDelete() {
   padding: 0.3rem 0.65rem;
   background: var(--color-action-secondary);
   border: none;
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: var(--radius-sm);
   cursor: pointer;
   font-size: 0.78rem;
@@ -1224,7 +1224,7 @@ async function confirmDelete() {
   cursor: pointer;
   border: 1px solid var(--color-border);
 }
-.ms-plan-actions .btn-primary { background: var(--color-primary); color: #fff; border-color: var(--color-primary); }
+.ms-plan-actions .btn-primary { background: var(--color-primary); color: var(--fs-text-on-action); border-color: var(--color-primary); }
 .ms-plan-actions .btn-primary:disabled { opacity: 0.6; cursor: default; }
 .ms-plan-actions .btn-secondary { background: var(--color-bg-card); color: var(--color-text); }
 
@@ -1393,8 +1393,8 @@ async function confirmDelete() {
   line-height: 1;
 }
 .task-card:hover .task-advance-btn { opacity: 1; }
-.task-advance-btn:hover { background: var(--color-primary); border-color: var(--color-primary); color: #fff; }
-.task-advance-btn--done:hover { background: var(--color-success, #22c55e); border-color: var(--color-success, #22c55e); color: #fff; }
+.task-advance-btn:hover { background: var(--color-primary); border-color: var(--color-primary); color: var(--fs-text-on-action); }
+.task-advance-btn--done:hover { background: var(--color-success, #22c55e); border-color: var(--color-success, #22c55e); color: var(--fs-text-on-action); }
 .task-advance-btn:disabled { opacity: 0.4; cursor: default; }
 
 .priority-dot {
@@ -1475,7 +1475,7 @@ async function confirmDelete() {
   font-family: inherit;
 }
 .modal-btn:hover { background: var(--color-bg); }
-.modal-btn-danger { background: var(--color-action-destructive); border-color: var(--color-action-destructive); color: #fff; }
+.modal-btn-danger { background: var(--color-action-destructive); border-color: var(--color-action-destructive); color: var(--fs-text-on-action); }
 .modal-btn-danger:hover { background: var(--color-action-destructive-hover); border-color: var(--color-action-destructive-hover); }
 
 /* ── Skeleton ────────────────────────────────────────────────── */

frontend/src/views/RegisterInviteView.vue

@@ -251,7 +251,7 @@ async function handleSubmit() {
   width: 100%;
   padding: 0.6rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/RegisterView.vue

@@ -220,7 +220,7 @@ async function handleSubmit() {
   width: 100%;
   padding: 0.6rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/ResetPasswordView.vue

@@ -199,7 +199,7 @@ async function handleSubmit() {
   width: 100%;
   padding: 0.6rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/SettingsView.vue

@@ -2567,7 +2567,7 @@ function formatUserDate(iso: string): string {
 .btn-save {
   padding: 0.4rem 0.9rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -2595,7 +2595,7 @@ function formatUserDate(iso: string): string {
 }
 .btn-danger-outline:hover:not(:disabled) {
   background: var(--color-action-destructive);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .btn-danger-outline:disabled { opacity: 0.5; cursor: default; }
 
@@ -2603,7 +2603,7 @@ function formatUserDate(iso: string): string {
 .btn-danger {
   padding: 0.4rem 0.9rem;
   background: var(--color-action-destructive);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -2620,7 +2620,7 @@ function formatUserDate(iso: string): string {
 .btn-secondary {
   padding: 0.4rem 0.9rem;
   background: var(--color-action-secondary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -2685,7 +2685,7 @@ function formatUserDate(iso: string): string {
 .db-health-table tr.dh-warn td:first-child code { color: var(--color-warning); }
 .btn-warn:hover:not(:disabled) {
   background: var(--color-warning);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 
 .saved-msg {
@@ -3000,7 +3000,7 @@ function formatUserDate(iso: string): string {
 .btn-confirm-delete {
   padding: 0.25rem 0.6rem;
   background: var(--color-action-destructive);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -3033,7 +3033,7 @@ function formatUserDate(iso: string): string {
   transition: background 0.15s;
 }
 .btn-toggle:disabled { opacity: 0.6; cursor: default; }
-.btn-toggle-open { background: var(--color-action-primary); color: #fff; }
+.btn-toggle-open { background: var(--color-action-primary); color: var(--fs-text-on-action); }
 .btn-toggle-open:hover:not(:disabled) { background: var(--color-action-primary-hover); }
 .btn-toggle-close {
   background: var(--color-bg-secondary);
@@ -3151,7 +3151,7 @@ function formatUserDate(iso: string): string {
 .btn-primary {
   padding: 0.4rem 0.9rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -3391,7 +3391,7 @@ function formatUserDate(iso: string): string {
 }
 .unit-btn.active {
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .unit-btn:hover:not(.active) {
   color: var(--color-text);
@@ -3863,7 +3863,7 @@ function formatUserDate(iso: string): string {
 }
 .btn-danger-outline:hover:not(:disabled) {
   background: var(--color-action-destructive);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .btn-danger-outline:disabled { opacity: 0.5; cursor: default; }
 @keyframes va-dot-bounce {

frontend/src/views/SnippetDetailView.vue

@@ -268,7 +268,7 @@ async function confirmDelete() {
   padding: 0.35rem 0.8rem;
   border: none;
   background: var(--color-action-destructive, #6B2118);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border-radius: var(--radius-sm);
   cursor: pointer;
   font-size: 0.85rem;

frontend/src/views/SnippetEditorView.vue

@@ -575,7 +575,7 @@ function cancel() {
 .btn-primary {
   padding: 0.5rem 1.1rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/SnippetListView.vue

@@ -546,7 +546,7 @@ function usageTitle(s: SnippetListItem): string {
 .btn-primary {
   padding: 0.45rem 1rem;
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -679,7 +679,7 @@ function usageTitle(s: SnippetListItem): string {
 }
 .empty-action:hover {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 
 .skeleton-grid,
@@ -1021,7 +1021,7 @@ function usageTitle(s: SnippetListItem): string {
 .modal-btn-primary {
   background: var(--color-action-primary);
   border-color: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .modal-btn-primary:hover:not(:disabled) {
   background: var(--color-action-primary-hover);

frontend/src/views/TaskEditorView.vue

@@ -971,7 +971,7 @@ useEditorGuards(dirty, save);
 .btn-subtask-confirm {
   padding: 0.25rem 0.5rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

frontend/src/views/TaskViewerView.vue

@@ -501,7 +501,7 @@ const subTaskProgress = computed(() => {
   border: none;
   border-radius: var(--radius-sm);
   background: var(--color-action-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   text-decoration: none;
   cursor: pointer;
   font-size: 0.875rem;
@@ -511,14 +511,14 @@ const subTaskProgress = computed(() => {
 .btn-edit:hover,
 .btn-advance:hover {
   background: var(--color-action-primary-hover);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 /* Convert + Share: Bronze action-secondary — alternate paths */
 .btn-convert {
   margin-left: auto;
   padding: 0.3rem 0.75rem;
   background: var(--color-action-secondary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -536,7 +536,7 @@ const subTaskProgress = computed(() => {
   background: var(--color-action-secondary);
   border: none;
   border-radius: var(--radius-sm);
-  color: #fff;
+  color: var(--fs-text-on-action);
   cursor: pointer;
   font-size: 0.85rem;
   font-family: inherit;

frontend/src/views/UserManagementView.vue

@@ -331,7 +331,7 @@ function formatDate(iso: string): string {
 .btn-invite {
   padding: 0.45rem 1rem;
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;
@@ -395,7 +395,7 @@ function formatDate(iso: string): string {
 }
 .btn-toggle-open {
   background: var(--color-primary);
-  color: #fff;
+  color: var(--fs-text-on-action);
 }
 .btn-toggle-open:hover:not(:disabled) {
   opacity: 0.9;
@@ -498,7 +498,7 @@ function formatDate(iso: string): string {
 .btn-confirm-delete {
   padding: 0.25rem 0.6rem;
   background: var(--color-danger);
-  color: #fff;
+  color: var(--fs-text-on-action);
   border: none;
   border-radius: var(--radius-sm);
   cursor: pointer;

plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "scribe",
   "description": "Scribe system-of-record for Claude Code: MCP tools over your notes/tasks/projects/rules, a session-start push channel that surfaces your always-on rules + active-project context, process-skills (writing-plans, systematic-debugging, verification, brainstorming, reusing-code), and your saved Scribe Processes auto-surfaced as skills (/scribe:sync). Replaces superpowers + file-memory with one app-backed plugin.",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "author": { "name": "Bryan Van Deusen" },
   "mcpServers": {
     "scribe": {

plugin/skills/using-scribe/SKILL.md

@@ -64,11 +64,13 @@ Two constraints on *how* that's achieved:
 3. **Update over duplicate.** When recording, prefer updating an existing
    note/rule/task over creating a new one. Search first; revise what's there.
 
-4. **Plans live in Scribe.** For non-trivial work call `start_planning(project_id,
-   title)` FIRST — it creates a milestone whose `body` holds the design; each
-   step is its own task under that milestone (`create_task(milestone_id=...)`),
-   progress goes in work-logs (`add_task_log`). Read it back with `get_milestone`.
-   Do not write plans/specs to local `.md` files.
+4. **When you plan, plan in Scribe.** Work with an *arc* — several steps toward
+   one goal — gets a plan, and a plan is a milestone: `start_planning(project_id,
+   title)` creates one whose `body` holds the design, each step is its own task
+   under it (`create_task(milestone_id=...)`), progress goes in work-logs
+   (`add_task_log`). Work without an arc (a fix, a one-file change, a question)
+   is just a task — don't wrap it in a milestone. Either way, do not write
+   plans/specs to local `.md` files. See the **writing-plans** skill.
 
 5. **Keep state honest.** Set a task `in_progress` when you start it, `done` the
    moment it's complete; log progress as you go.
@@ -102,7 +104,7 @@ shared homes general:
   norms that bind *every* project. Cross-project standards only.
 - **Subscribed rulebook** (`create_rule` + `subscribe_project_to_rulebook`) — a
   reusable, *themed* module of general rules that binds only projects that opt
-  in (e.g. a design system → visual apps). Themed, but still project-agnostic.
+  in (e.g. a review checklist → every service). Themed, but project-agnostic.
 - **Project rule** (`create_project_rule`) — anything specific to one project
   (its files, paths, quirks).
 
@@ -112,6 +114,26 @@ project rule; a standard a category shares → subscribed rulebook; a universal
 norm → always-on rulebook. Never put project-specific detail in a shared
 rulebook — it leaks to every other project that gets it.
 
+**First ask whether it's a rule at all.** A rule is prose you have to remember
+and apply; Scribe's other entities are structure a tool can resolve and check.
+Visual standards belong in a **design system**, not a rulebook — a token can be
+inherited, resolved per mode, rendered to a stylesheet and diffed against code,
+and none of that survives being written as a rule. A repeatable procedure is a
+**process**; reusable code is a **snippet**. Reach for a rule when the thing
+really is a standing instruction about how to work.
+
+## Building UI: the project's design system binds
+
+`enter_project` returns a `design_system` when the project has one, with the
+guidance **chain-merged** — the house style it inherits plus its own departures
+from it. Treat it the way you treat a rule.
+
+Before writing a colour, size, radius, weight or duration by hand, reach for a
+token: `resolve_design_system(id)` for the values, or
+`get_design_system_stylesheet(id)` for the rendered sheet. A literal is a value
+stated outside the system, so it can never follow a palette change — and
+nothing will tell you it drifted.
+
 ## Other Scribe process-skills
 
 This plugin also ships focused process-skills — writing-plans, systematic

plugin/skills/writing-plans/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: writing-plans
-description: Use before starting any non-trivial or multi-step piece of work — produce a clear plan BEFORE diving in. Triggers when the user asks you to plan, design an approach, scope an effort, or tackle work big enough to need ordered steps. The plan lives in a Scribe milestone (via start_planning), not a local file.
+description: Use when a piece of work has an arc — several steps toward one goal, worth tracking as a unit — and you want the approach reviewable before you start. Triggers when the user asks you to plan, design an approach, or scope an effort, or when work is about to sprawl across several steps. Not for single-step work. The plan lives in a Scribe milestone (via start_planning), not a local file.
 ---
 
 # Writing plans
@@ -9,12 +9,30 @@ A plan is **how** you'll execute a chunk of work — the design plus an ordered
 set of steps — written *before* you start, so the approach is reviewable and the
 work stays trackable.
 
-## Start the plan in Scribe, not a file
+## First decide whether this work wants a plan
 
-For non-trivial work, call **`start_planning(project_id, title)` FIRST** —
-before any design or implementation. It creates a **milestone** (the plan
-container) seeded with a design template and returns the milestone id plus the
-project's applicable rules. The plan lives in that milestone:
+A plan lives in a milestone, and **a milestone earns its place when the work has
+an arc**: several steps, one shared goal, a beginning and an end worth tracking
+as a unit. That is the whole test, and it is a judgment about the *shape* of the
+work — not about its size, difficulty, or importance.
+
+Plenty of real work has no arc. A bug fix, a one-file change, a question
+answered, a setting changed. For those, a milestone is a container with one
+thing in it: the ceremony costs more than it records, and it leaves the project
+with milestones that never meant anything. **Use a task instead** — set it
+`in_progress`, record what you find with `add_task_log`, set it `done`. That is
+a complete, honest record of work that didn't need a plan.
+
+Some projects are milestone-shaped and some are a flat task list. Read the
+project you are in rather than imposing a shape on it.
+
+## When it does: start the plan in Scribe, not a file
+
+Call **`start_planning(project_id, title)`** before designing or implementing —
+so the milestone exists to write into, rather than being backfilled from work
+already done. It creates a **milestone** (the plan container) seeded with a
+design template and returns the milestone id plus the project's applicable
+rules. The plan lives in that milestone:
 
 - The **design/intent** goes in the milestone `body` — edit it with
   `update_milestone(milestone_id, body=...)`.

scripts/check_design_tokens.py

@@ -0,0 +1,174 @@
+#!/usr/bin/env python3
+"""Check the frontend's CSS against the tokens its stylesheet declares.
+
+The gap this closes: `services/design_stylesheet.check_code_against_tokens` has
+always been able to answer "does this code use the sheet correctly?", but the
+only thing ever fed to it was recorded SNIPPETS. The app's own components — where
+sixteen unresolvable references were found living quietly (#2319) — were checked
+by nothing at all.
+
+That was structural rather than an oversight. The drift panel runs in the browser
+and cannot read source files, and the server has no repo access. CI is the only
+place holding both the component sources and the ability to run the check, and it
+only became cheap once `theme.css` became a generated artifact — so the source of
+truth is a local file, with no network and no credentials.
+
+INSTANCE-AGNOSTIC ON PURPOSE (rule #115). Nothing here knows what a token should
+be called or which literals are discouraged. Both come from the stylesheet: the
+declarations, and the `SUPERSEDES` block the generator emits. Point it at a
+different install's sheet and it checks that install's rules.
+
+Two severities, and the split is deliberate:
+
+  FAIL   an unresolvable `var()` reference. Currently zero, so this is a ratchet
+         that holds a line already reached rather than a backlog that keeps CI
+         red. It also cannot false-positive: either the name is declared or it
+         is not.
+  REPORT superseded literals and raw colour literals. Hundreds today, so gating
+         on them would mean a permanently failing job that everyone learns to
+         ignore — which is worse than no check.
+"""
+from __future__ import annotations
+
+import argparse
+import pathlib
+import re
+import sys
+
+# A declaration is `--name:`; a reference is `var(--name)` or `var(--name, …)`.
+DECLARATION = re.compile(r"(?<![\w-])(--[A-Za-z0-9_-]+)\s*:")
+REFERENCE = re.compile(r"var\(\s*(--[A-Za-z0-9_-]+)")
+SUPERSEDES_LINE = re.compile(r"^\s*\*\s*(\S+)\s*->\s*(--[A-Za-z0-9_-]+)\s*$")
+HEX_LITERAL = re.compile(r"#[0-9a-fA-F]{3,8}\b")
+STYLE_BLOCK = re.compile(r"<style[^>]*>(.*?)</style>", re.S)
+CSS_COMMENT = re.compile(r"/\*.*?\*/", re.S)
+
+
+def declared_tokens(sheet: str) -> set[str]:
+    """Every custom property the stylesheet declares.
+
+    Anchored on the colon alone. Anchoring on `{` or `;` instead silently drops
+    every declaration that follows a comment — a mistake made once already, which
+    lost `--color-bg` and 2 others without erroring.
+    """
+    return set(DECLARATION.findall(sheet))
+
+
+def superseded_literals(sheet: str) -> dict[str, str]:
+    """`{literal: token}` from the generator's SUPERSEDES block, lowercased."""
+    out: dict[str, str] = {}
+    for line in sheet.splitlines():
+        match = SUPERSEDES_LINE.match(line)
+        if match:
+            out[match.group(1).lower()] = match.group(2)
+    return out
+
+
+def _literal_pattern(literal: str) -> re.Pattern:
+    """Match a literal without matching a longer one containing it.
+
+    `#fff` must not fire inside `#ffffff`: different colours, and a finding on
+    the wrong one sends someone to change correct code.
+    """
+    return re.compile(
+        r"(?<![0-9A-Za-z_#-])" + re.escape(literal) + r"(?![0-9A-Za-z_-])",
+        re.IGNORECASE,
+    )
+
+
+def style_source(path: pathlib.Path) -> str:
+    """The CSS in a file — `<style>` blocks for an SFC, the whole of a .css.
+
+    Comments are stripped, and that is load-bearing rather than tidy. A comment
+    EXPLAINING a rule mentions the very literal the rule forbids: this file's own
+    stylesheet documents why it avoids `#fff`, and the first run of this checker
+    reported that explanation as a violation. A checker that flags the
+    documentation of a rule teaches people to stop documenting rules.
+    """
+    text = path.read_text(encoding="utf-8", errors="replace")
+    css = "\n".join(STYLE_BLOCK.findall(text)) if path.suffix == ".vue" else text
+    return CSS_COMMENT.sub(" ", css)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--sheet", default="frontend/src/assets/theme.css")
+    parser.add_argument("--root", default="frontend/src")
+    parser.add_argument(
+        "--report-literals", action="store_true",
+        help="also list raw colour literals (advisory, never fails)",
+    )
+    args = parser.parse_args()
+
+    sheet_path = pathlib.Path(args.sheet)
+    if not sheet_path.is_file():
+        print(f"error: stylesheet not found: {sheet_path}", file=sys.stderr)
+        return 2
+
+    sheet = sheet_path.read_text()
+    declared = declared_tokens(sheet)
+    supersedes = superseded_literals(sheet)
+    print(f"{sheet_path}: {len(declared)} tokens declared, "
+          f"{len(supersedes)} superseded literals recorded\n")
+
+    root = pathlib.Path(args.root)
+    sources = sorted(
+        [p for p in root.rglob("*.vue")] + [p for p in root.rglob("*.css")]
+    )
+
+    unresolved: list[tuple[pathlib.Path, str]] = []
+    superseded_hits: list[tuple[pathlib.Path, str, str]] = []
+    literal_count = 0
+
+    for path in sources:
+        if path == sheet_path:
+            continue
+        css = style_source(path)
+        if not css.strip():
+            continue
+
+        # A component may legitimately declare a local custom property; a
+        # reference to it is not unresolved.
+        local = set(DECLARATION.findall(css))
+        for name in sorted(set(REFERENCE.findall(css))):
+            if name not in declared and name not in local:
+                unresolved.append((path, name))
+
+        for literal, token in supersedes.items():
+            if _literal_pattern(literal).search(css):
+                superseded_hits.append((path, literal, token))
+
+        literal_count += len(HEX_LITERAL.findall(css))
+
+    if unresolved:
+        print(f"FAIL — {len(unresolved)} unresolvable var() reference(s).")
+        print("  These render as the fallback if given one, or as nothing at all.")
+        print("  Either way nothing errors, which is why they survive.\n")
+        for path, name in unresolved:
+            print(f"    {path}: {name}")
+        print()
+    else:
+        print("OK — every var() reference resolves to a declared token.\n")
+
+    if superseded_hits:
+        print(f"REPORT — {len(superseded_hits)} superseded literal(s). "
+              "The sheet says what to write instead:")
+        seen: set[tuple[str, str]] = set()
+        for path, literal, token in superseded_hits:
+            key = (str(path), literal)
+            if key in seen:
+                continue
+            seen.add(key)
+            print(f"    {path}: {literal} -> {token}")
+        print()
+
+    if args.report_literals:
+        print(f"REPORT — {literal_count} raw colour literal(s) in component CSS.")
+        print("  Advisory: a literal is a value stated outside the system, so it "
+              "cannot follow a palette change.\n")
+
+    return 1 if unresolved else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

src/scribe/mcp/server.py

@@ -33,14 +33,27 @@ What each part is for, and when to reach for it:
 - Plan: a MILESTONE acting as a plan container — HOW you'll execute a chunk of
   work. The design/intent lives in the milestone `body`; each step is its own
   child task (create_task(milestone_id=...)), tracked with status + work-logs —
-  NOT a checkbox buried in the body. Start one with start_planning when
-  beginning non-trivial work, before you dive in; read it back with
-  get_milestone (body + steps). (The old kind=plan task is retired — some
-  historical plan-tasks still exist and remain readable, but don't create new
-  ones.)
+  NOT a checkbox buried in the body. Create one with start_planning when the
+  work has an arc (same test as a milestone, above) and you want the approach
+  reviewable before you start; read it back with get_milestone (body + steps).
+  Work without an arc is a task, not a plan. (The old kind=plan task is retired
+  — some historical plan-tasks still exist and remain readable, but don't
+  create new ones.)
 - Note: durable free-form knowledge — reference material, decisions, logs of
   what happened.
   No lifecycle, not actionable. Reach for one to CAPTURE something worth keeping.
+- Design system: the visual standards a project's UI is built from — design
+  tokens (name + value per mode) plus the prose a token table cannot hold
+  (aesthetic, voice, what is out of scope). Systems INHERIT: a child holds only
+  what it changes and the chain supplies the rest, so a family's house style and
+  one app's departures from it are the same structure at two depths. A project
+  points at one with set_project_design_system, and enter_project then hands it
+  back with the guidance chain-merged. Treat it as binding for UI work: reach
+  for a token (resolve_design_system / get_design_system_stylesheet) before
+  writing a colour, size, radius or duration by hand. Do NOT record a design
+  system as a rulebook — rules are for behaviour, and tokens kept as prose
+  cannot be resolved, inherited, rendered to a stylesheet, or checked against
+  code.
 - System: a per-project, reusable, self-describing subsystem/area. Associate any
   record (note, task, issue) with it via system_ids so research, build-work, and
   fixes for the same area line up, and recurring problem-spots surface. Manage
@@ -143,8 +156,8 @@ right altitude:
     subscribe_project_to_rulebook) — a reusable, THEMED module of general
     rules that binds only the projects which subscribe. Its rules must make
     sense for every project that could subscribe, never one specific project
-    (e.g. a design-system rulebook: design-specific but project-agnostic — no
-    rule names a single app).
+    (e.g. a code-review checklist, or a compliance regime a category of
+    projects shares — no rule names a single app).
   - Project rule (create_project_rule) — anything specific to ONE project.
 Both rulebook tiers are SHARED, so their rules stay general; the difference
 between them is REACH (all projects vs opt-in by theme), not generality. Rule
@@ -152,6 +165,15 @@ of thumb: names a specific project's files/paths/quirks -> project rule; a
 standard a CATEGORY of projects shares -> subscribed rulebook; a universal
 norm -> always-on rulebook. Coordinate with the operator on which home fits.
 
+Before writing a rule, check whether another entity already models the thing.
+A rule is prose an agent must remember and apply; the other entities are
+structure a tool can resolve, render and check. Visual standards are a DESIGN
+SYSTEM, not a rulebook — a token can be inherited, resolved per mode, rendered
+to a stylesheet and diffed against code, and none of that survives being
+written as a rule. A repeatable procedure is a PROCESS. Reusable code is a
+SNIPPET. Reach for a rule when the thing genuinely is a standing instruction
+about how to work, and nothing else can hold it.
+
 One thing NOT to do: don't bridge Scribe into a session by writing to the
 host's native memory. Rules are pull-only, so a fresh session won't reach for
 them unless its always-loaded context says to — but the bridge for that is the
@@ -184,17 +206,13 @@ adopting or creating — never do either silently, and never guess a project int
 existence. Once a project is in scope, the enter_project handshake and the
 host-memory pointer step above both apply.
 
-A plan is a MILESTONE, and Scribe is the canonical home for it. When you begin
-non-trivial work, call start_planning(project_id, title) FIRST — before any
-brainstorming, design, or plan-writing skill runs. start_planning creates the
-milestone, seeds its `body` with the design template, returns the project's
-applicable_rules, and gives you the milestone id you'll write into. Put the
-design/intent in the milestone body via update_milestone(milestone_id, body=...);
-create each step as a child task with create_task(milestone_id=...) and track it
-with status + add_task_log — do NOT list steps as checkboxes in the body. Read
-the plan back with get_milestone (body + steps). If a habit tells you to save a
-plan or spec to a local `.md` file, that's superseded here: the milestone is the
-record, not a local file.
+When work DOES get a plan, Scribe is the plan's canonical home: it is a
+milestone (see the Plan entry above), created with start_planning and written
+into with update_milestone + child tasks. If a habit tells you to save a plan or
+spec to a local `.md` file, that's superseded here — the milestone is the
+record, not a file on disk. Whether a given piece of work wants a plan at all is
+a separate question, answered by the arc test above and by the writing-plans
+skill; these instructions do not mandate one.
 
 Deletes are recoverable: every delete_* tool moves the entity (and its
 descendants) to the trash and returns a deleted_batch_id. Use list_trash() to

src/scribe/mcp/tools/projects.py

@@ -17,6 +17,7 @@ keeps working.
 from __future__ import annotations
 
 from scribe.mcp._context import current_user_id
+from scribe.services import design_systems as design_systems_svc
 from scribe.services import milestones as milestones_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
@@ -53,7 +54,13 @@ async def enter_project(project_id: int) -> dict:
 
     Returns a dict with keys: project, milestone_summary, applicable_rules,
     project_rules, subscribed_rulebooks, applicable_rules_truncated,
-    open_tasks, recent_notes.
+    open_tasks, recent_notes, design_system.
+
+    `design_system` is null unless the project points at one. When present it
+    carries the chain-merged guidance (the house style AND this project's
+    departures from it) plus a summary of the token set — treat it as binding
+    for any UI you write, and pull the values with resolve_design_system or
+    get_design_system_stylesheet before reaching for a literal.
     """
     uid = current_user_id()
     project = await projects_svc.get_project(uid, project_id)
@@ -74,9 +81,17 @@ async def enter_project(project_id: int) -> dict:
         uid, is_task=False, project_id=project_id,
         sort="updated_at", limit=5,
     )
+    # A project need not have one, and most installs won't — null is ordinary
+    # here, not a missing prerequisite.
+    design_system = None
+    if project.design_system_id:
+        design_system = await design_systems_svc.design_context(
+            uid, project.design_system_id,
+        )
 
     return {
         "project": project.to_dict(),
+        "design_system": design_system,
         "milestone_summary": milestone_summary,
         "applicable_rules": applicable["rules"],
         "project_rules": applicable.get("project_rules", []),

src/scribe/mcp/tools/tasks.py

@@ -276,6 +276,12 @@ async def add_task_log(task_id: int, content: str) -> dict:
 async def start_planning(project_id: int, title: str) -> dict:
     """Begin a plan in Scribe (the preferred home for plans — not a local .md file).
 
+    Reach for this when the work has an ARC — several steps toward one goal,
+    worth tracking as a unit. Work without one (a fix, a one-file change, a
+    question answered) is a task, not a plan: create_task, drive its status, and
+    record progress with add_task_log. A milestone holding a single step is
+    ceremony, and it leaves the project with a plan that never meant anything.
+
     Creates a MILESTONE that IS the plan: its `body` is seeded with a design
     template (Goal/Approach/Verification) under the given project, and the call
     returns it together with the project's applicable Rulebook rules and brief

src/scribe/routes/notes.py

@@ -1,8 +1,6 @@
-import asyncio
 import logging
 import re
 
-from scribe.services.embeddings import upsert_note_embedding
 
 from quart import Blueprint, jsonify, request
 
@@ -113,9 +111,6 @@ async def create_note_route():
         )
     except ValueError as e:
         return jsonify({"error": str(e)}), 400
-    text = f"{note.title}\n{note.body}".strip() if note.body else (note.title or "")
-    if text:
-        asyncio.create_task(upsert_note_embedding(note.id, uid, text))
     return jsonify(note.to_dict()), 201
 
 
@@ -221,9 +216,6 @@ async def update_note_route(note_id: int):
         return jsonify({"error": str(e)}), 400
     if note is None:
         return not_found("Note")
-    text = f"{note.title}\n{note.body}".strip() if note.body else (note.title or "")
-    if text:
-        asyncio.create_task(upsert_note_embedding(note.id, owner_uid, text))
     return jsonify(note.to_dict())
 
 
@@ -259,9 +251,6 @@ async def patch_note_route(note_id: int):
         return jsonify({"error": str(e)}), 400
     if note is None:
         return not_found("Note")
-    text = f"{note.title}\n{note.body}".strip() if note.body else (note.title or "")
-    if text:
-        asyncio.create_task(upsert_note_embedding(note.id, owner_uid, text))
     return jsonify(note.to_dict())
 
 

src/scribe/routes/tasks.py

@@ -1,4 +1,3 @@
-import asyncio
 from datetime import date
 
 from quart import Blueprint, jsonify, request
@@ -8,7 +7,6 @@ from scribe.models.note import TaskPriority, TaskStatus
 from scribe.routes.utils import not_found, parse_iso_date, parse_pagination
 from scribe.services.access import can_write_note
 from scribe.services import systems as systems_svc
-from scribe.services.embeddings import upsert_note_embedding
 from scribe.services.notes import (
     create_note,
     get_note_for_user,
@@ -149,9 +147,6 @@ async def create_task_route():
     )
     if data.get("system_ids") is not None:
         await systems_svc.set_record_systems(uid, task.id, data["system_ids"])
-    text = f"{task.title}\n{task.body}".strip() if task.body else (task.title or "")
-    if text:
-        asyncio.create_task(upsert_note_embedding(task.id, uid, text))
     out = task.to_dict()
     out["systems"] = [s.to_dict() for s in await systems_svc.list_record_systems(uid, task.id)]
     return jsonify(out), 201
@@ -255,9 +250,6 @@ async def update_task_route(task_id: int):
         return not_found("Task")
     if data.get("system_ids") is not None:
         await systems_svc.set_record_systems(uid, task_id, data["system_ids"])
-    text = f"{task.title}\n{task.body}".strip() if task.body else (task.title or "")
-    if text:
-        asyncio.create_task(upsert_note_embedding(task.id, task_note.user_id, text))
     out = task.to_dict()
     out["systems"] = [s.to_dict() for s in await systems_svc.list_record_systems(uid, task_id)]
     return jsonify(out)

src/scribe/services/backup.py

@@ -8,7 +8,10 @@ from scribe.models.milestone import Milestone
 from scribe.models.note import Note
 from scribe.models.note_draft import NoteDraft
 from scribe.models.note_version import NoteVersion
+from scribe.models.design_system import DesignSystem, DesignToken
+from scribe.models.note_usage import NoteUsageEvent
 from scribe.models.project import Project
+from scribe.models.repo_binding import RepoBinding
 from scribe.models.rulebook import (
     Rule,
     Rulebook,
@@ -18,6 +21,7 @@ from scribe.models.rulebook import (
     project_topic_suppressions,
 )
 from scribe.models.setting import Setting
+from scribe.models.system import RecordSystem, System
 from scribe.models.task_log import TaskLog
 from scribe.models.user import User
 
@@ -26,17 +30,44 @@ logger = logging.getLogger(__name__)
 # Backup format version. v3 (2026-06) added rulebooks/topics/rules + their
 # project subscription/suppression join tables. v4 (2026-07) dropped events
 # when the calendar surface was retired — old v3 events are skipped on restore.
+# v5 (2026-08) added the six tables that had accumulated outside the backup
+# entirely (#2293), and the coverage guard that stops the seventh.
 # Bump when the serialized schema changes.
-BACKUP_VERSION = 4
+BACKUP_VERSION = 5
+
+# Every table this backup carries, by its REAL name. Paired with _NOT_INCLUDED
+# below, these two lists must together account for the entire schema — which is
+# what tests/test_services_backup.py asserts against Base.metadata.
+#
+# The point is the ABSENCE case. A new table gets a model and a migration, both
+# of which fail loudly if wrong, and then silently never gets a backup section:
+# no error, no warning, and a restore that reports success. Naming the coverage
+# explicitly turns "someone forgot" into a failing test (#2293).
+_BACKED_UP = [
+    "users", "projects", "milestones", "notes", "task_logs", "note_drafts",
+    "note_versions", "settings", "rulebooks", "rulebook_topics", "rules",
+    "project_rulebook_subscriptions", "project_rule_suppressions",
+    "project_topic_suppressions",
+    # v5 (2026-08): the five-year gap this list was written to stop.
+    "systems", "record_systems", "design_systems", "design_tokens",
+    "note_usage_events", "repo_bindings",
+]
 
 # Tables intentionally NOT in the backup, surfaced in the payload so the gap is
 # explicit rather than silent. ACL (groups/shares) is a coherent follow-up;
-# embeddings are derived (regenerated from note bodies); api_keys are sensitive
-# credentials; the rest are transient/operational.
+# note_embeddings are derived (regenerated from note bodies); api_keys are
+# sensitive credentials; retrieval_logs is observational telemetry that nothing
+# reads for correctness and that grows per query; the rest are
+# transient/operational.
+#
+# REAL table names, deliberately. This list used to read "embeddings",
+# "invitations", "password_resets" — none of which are tables — so it looked
+# like coverage while naming nothing the schema could confirm.
 _NOT_INCLUDED = [
     "groups", "group_memberships", "project_shares", "note_shares",
-    "api_keys", "embeddings", "app_logs", "notifications", "invitations",
-    "password_resets", "user_profiles",
+    "api_keys", "note_embeddings", "app_logs", "notifications",
+    "invitation_tokens", "password_reset_tokens", "user_profiles",
+    "retrieval_logs",
 ]
 
 
@@ -60,12 +91,73 @@ def _topic_suppression_rows(rows) -> list[dict]:
     return [{"project_id": r.project_id, "topic_id": r.topic_id} for r in rows]
 
 
+# The v5 sections. Pure row-builders like the join-table helpers above, for the
+# same reason: CI has no database, so a serialiser that is a plain function is
+# one that can actually be tested.
+
+def _system_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": r.id, "user_id": r.user_id, "project_id": r.project_id,
+            "name": r.name, "description": r.description, "color": r.color,
+            "status": r.status, "order_index": r.order_index,
+        }
+        for r in rows
+    ]
+
+
+def _record_system_rows(rows) -> list[dict]:
+    return [{"note_id": r.note_id, "system_id": r.system_id} for r in rows]
+
+
+def _design_system_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": r.id, "owner_user_id": r.owner_user_id, "title": r.title,
+            "description": r.description, "guidance": r.guidance,
+            "parent_id": r.parent_id,
+        }
+        for r in rows
+    ]
+
+
+def _design_token_rows(rows) -> list[dict]:
+    return [
+        {
+            "id": r.id, "design_system_id": r.design_system_id, "name": r.name,
+            "value_by_mode": r.value_by_mode or {},
+            "group_name": r.group_name, "purpose": r.purpose,
+            "rationale": r.rationale, "supersedes": r.supersedes or [],
+            "order_index": r.order_index,
+        }
+        for r in rows
+    ]
+
+
+def _usage_event_rows(rows) -> list[dict]:
+    return [
+        {
+            "user_id": r.user_id, "note_id": r.note_id, "event": r.event,
+            "source": r.source,
+            "created_at": r.created_at.isoformat() if r.created_at else None,
+        }
+        for r in rows
+    ]
+
+
+def _repo_binding_rows(rows) -> list[dict]:
+    return [
+        {"user_id": r.user_id, "project_id": r.project_id, "repo_key": r.repo_key}
+        for r in rows
+    ]
+
+
 # ---------------------------------------------------------------------------
 # Export
 # ---------------------------------------------------------------------------
 
 async def export_full_backup() -> dict:
-    """Export all data as a version-3 JSON backup."""
+    """Export all data as a version-5 JSON backup."""
     async with async_session() as session:
         users = (await session.execute(select(User))).scalars().all()
         projects = (await session.execute(select(Project))).scalars().all()
@@ -77,6 +169,18 @@ async def export_full_backup() -> dict:
             select(NoteVersion).order_by(NoteVersion.note_id, NoteVersion.id)
         )).scalars().all()
         settings = (await session.execute(select(Setting))).scalars().all()
+        systems = (await session.execute(select(System))).scalars().all()
+        record_systems = (await session.execute(select(RecordSystem))).scalars().all()
+        # Parent-first, so a restore can resolve parent_id as it goes rather
+        # than needing a second pass — the self-FK is the only ordering
+        # constraint in this payload.
+        design_systems = (await session.execute(
+            select(DesignSystem).order_by(DesignSystem.parent_id.nullsfirst(),
+                                          DesignSystem.id)
+        )).scalars().all()
+        design_tokens = (await session.execute(select(DesignToken))).scalars().all()
+        usage_events = (await session.execute(select(NoteUsageEvent))).scalars().all()
+        repo_bindings = (await session.execute(select(RepoBinding))).scalars().all()
         rulebooks = (await session.execute(select(Rulebook))).scalars().all()
         topics = (await session.execute(select(RulebookTopic))).scalars().all()
         rules = (await session.execute(select(Rule))).scalars().all()
@@ -244,11 +348,17 @@ async def export_full_backup() -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "systems": _system_rows(systems),
+        "record_systems": _record_system_rows(record_systems),
+        "design_systems": _design_system_rows(design_systems),
+        "design_tokens": _design_token_rows(design_tokens),
+        "note_usage_events": _usage_event_rows(usage_events),
+        "repo_bindings": _repo_binding_rows(repo_bindings),
     }
 
 
 async def export_user_backup(user_id: int) -> dict:
-    """Export a single user's data as a version-3 JSON backup."""
+    """Export a single user's data as a version-5 JSON backup."""
     async with async_session() as session:
         user = await session.get(User, user_id)
         projects = (await session.execute(
@@ -274,6 +384,32 @@ async def export_user_backup(user_id: int) -> dict:
         settings = (await session.execute(
             select(Setting).where(Setting.user_id == user_id)
         )).scalars().all()
+        systems = (await session.execute(
+            select(System).where(System.user_id == user_id)
+        )).scalars().all()
+        system_ids = [sy.id for sy in systems]
+        note_ids = [n.id for n in notes]
+        # Scoped by the user's SYSTEMS, not their notes: a shared note carrying
+        # this user's system tag belongs in their backup, and a note of theirs
+        # tagged with someone else's system does not — that row is the other
+        # user's to keep.
+        record_systems = (await session.execute(
+            select(RecordSystem).where(RecordSystem.system_id.in_(system_ids))
+        )).scalars().all() if system_ids else []
+        design_systems = (await session.execute(
+            select(DesignSystem).where(DesignSystem.owner_user_id == user_id)
+            .order_by(DesignSystem.parent_id.nullsfirst(), DesignSystem.id)
+        )).scalars().all()
+        ds_ids = [d.id for d in design_systems]
+        design_tokens = (await session.execute(
+            select(DesignToken).where(DesignToken.design_system_id.in_(ds_ids))
+        )).scalars().all() if ds_ids else []
+        usage_events = (await session.execute(
+            select(NoteUsageEvent).where(NoteUsageEvent.note_id.in_(note_ids))
+        )).scalars().all() if note_ids else []
+        repo_bindings = (await session.execute(
+            select(RepoBinding).where(RepoBinding.user_id == user_id)
+        )).scalars().all()
         rulebooks = (await session.execute(
             select(Rulebook).where(Rulebook.owner_user_id == user_id)
         )).scalars().all()
@@ -455,6 +591,12 @@ async def export_user_backup(user_id: int) -> dict:
         "rulebook_subscriptions": _subscription_rows(subscriptions),
         "rule_suppressions": _rule_suppression_rows(rule_suppressions),
         "topic_suppressions": _topic_suppression_rows(topic_suppressions),
+        "systems": _system_rows(systems),
+        "record_systems": _record_system_rows(record_systems),
+        "design_systems": _design_system_rows(design_systems),
+        "design_tokens": _design_token_rows(design_tokens),
+        "note_usage_events": _usage_event_rows(usage_events),
+        "repo_bindings": _repo_binding_rows(repo_bindings),
     }
 
 
@@ -556,6 +698,8 @@ async def _restore_v2(data: dict) -> dict:
         "settings": 0, "rulebooks": 0, "rulebook_topics": 0, "rules": 0,
         "rulebook_subscriptions": 0, "rule_suppressions": 0,
         "topic_suppressions": 0,
+        "systems": 0, "record_systems": 0, "design_systems": 0,
+        "design_tokens": 0, "note_usage_events": 0, "repo_bindings": 0,
     }
 
     async with async_session() as session:
@@ -814,6 +958,106 @@ async def _restore_v2(data: dict) -> dict:
             ))
             stats["topic_suppressions"] += 1
 
+        # --- v5 sections. Every one is data.get()-guarded, so a v2/v3/v4
+        # payload restores without them rather than failing on an absent key.
+
+        # 15. Systems
+        system_id_map: dict[int, int] = {}
+        for sy_data in data.get("systems", []):
+            mapped_uid = user_id_map.get(sy_data.get("user_id", 0))
+            mapped_pid = project_id_map.get(sy_data.get("project_id", 0))
+            if mapped_uid is None or mapped_pid is None:
+                continue
+            system = System(
+                user_id=mapped_uid, project_id=mapped_pid,
+                name=sy_data.get("name", ""),
+                description=sy_data.get("description"),
+                color=sy_data.get("color"),
+                status=sy_data.get("status", "active"),
+                order_index=sy_data.get("order_index", 0),
+            )
+            session.add(system)
+            await session.flush()
+            system_id_map[sy_data["id"]] = system.id
+            stats["systems"] += 1
+
+        # 16. Record↔system links
+        for rs in data.get("record_systems", []):
+            mapped_nid = note_id_map.get(rs.get("note_id", 0))
+            mapped_sid = system_id_map.get(rs.get("system_id", 0))
+            if mapped_nid is None or mapped_sid is None:
+                continue
+            session.add(RecordSystem(note_id=mapped_nid, system_id=mapped_sid))
+            stats["record_systems"] += 1
+
+        # 17. Design systems. The export orders these parent-first, so a
+        # parent's new id is always in the map by the time a child needs it —
+        # no second pass, and a child whose parent is missing lands as a root
+        # rather than failing the whole restore.
+        design_system_id_map: dict[int, int] = {}
+        for ds_data in data.get("design_systems", []):
+            mapped_uid = user_id_map.get(ds_data.get("owner_user_id", 0))
+            if mapped_uid is None:
+                continue
+            design = DesignSystem(
+                owner_user_id=mapped_uid,
+                title=ds_data.get("title", ""),
+                description=ds_data.get("description"),
+                guidance=ds_data.get("guidance"),
+                parent_id=design_system_id_map.get(ds_data.get("parent_id") or 0),
+            )
+            session.add(design)
+            await session.flush()
+            design_system_id_map[ds_data["id"]] = design.id
+            stats["design_systems"] += 1
+
+        # 18. Design tokens
+        for t_data in data.get("design_tokens", []):
+            mapped_dsid = design_system_id_map.get(t_data.get("design_system_id", 0))
+            if mapped_dsid is None:
+                continue
+            session.add(DesignToken(
+                design_system_id=mapped_dsid,
+                name=t_data.get("name", ""),
+                value_by_mode=t_data.get("value_by_mode") or {},
+                group_name=t_data.get("group_name"),
+                purpose=t_data.get("purpose"),
+                rationale=t_data.get("rationale"),
+                supersedes=t_data.get("supersedes") or [],
+                order_index=t_data.get("order_index", 0),
+            ))
+            stats["design_tokens"] += 1
+
+        # 19. Usage events. Kept because pull-through is the evidence base for
+        # whether recall works at all, and it is only ever accumulated — a
+        # restore that dropped it would silently reset that measurement to zero
+        # while everything still looked fine.
+        for ev in data.get("note_usage_events", []):
+            mapped_nid = note_id_map.get(ev.get("note_id", 0))
+            if mapped_nid is None:
+                continue
+            session.add(NoteUsageEvent(
+                user_id=user_id_map.get(ev.get("user_id") or 0),
+                note_id=mapped_nid,
+                event=ev.get("event", ""),
+                source=ev.get("source", ""),
+                created_at=_dt(ev.get("created_at")),
+            ))
+            stats["note_usage_events"] += 1
+
+        # 20. Repo bindings — small, but losing them means every bound repo
+        # quietly stops loading its project at session start.
+        for rb_data in data.get("repo_bindings", []):
+            mapped_uid = user_id_map.get(rb_data.get("user_id", 0))
+            mapped_pid = project_id_map.get(rb_data.get("project_id", 0))
+            if mapped_uid is None or mapped_pid is None:
+                continue
+            session.add(RepoBinding(
+                user_id=mapped_uid, project_id=mapped_pid,
+                repo_key=rb_data.get("repo_key", ""),
+            ))
+            stats["repo_bindings"] += 1
+
         await session.commit()
 
     logger.info("Restored v2/v3 backup: %s", stats)

src/scribe/services/design_stylesheet.py

@@ -194,6 +194,27 @@ def render_stylesheet(
         lines.append("}")
         lines.append("")
 
+    # A trailing, machine-readable record of what this system says to write
+    # INSTEAD of a given literal.
+    #
+    # The sheet carries its own supersedes declarations so that any consumer has
+    # them — notably a CI check, which has the component sources but no database.
+    # Hardcoding the mapping in a checker would bake one install's palette into
+    # the tool; reading it from the sheet keeps the checker instance-agnostic and
+    # keeps this file the single source.
+    replacements = [
+        (literal, getattr(token, "name", ""))
+        for token in tokens
+        for literal in (getattr(token, "supersedes", None) or ())
+        if is_valid_token_name(getattr(token, "name", ""))
+    ]
+    if replacements:
+        lines.append("/* SUPERSEDES — write the token, not the literal.")
+        for literal, name in replacements:
+            lines.append(f" * {safe_comment(str(literal))} -> {name}")
+        lines.append(" */")
+        lines.append("")
+
     return "\n".join(lines).rstrip() + "\n"
 
 

src/scribe/services/design_systems.py

@@ -282,6 +282,68 @@ async def resolve_design_system(
     return resolve_tokens(design_system_id, parents, tokens_by_system)
 
 
+async def design_context(user_id: int, design_system_id: int) -> dict | None:
+    """What a session needs to know about a design system, before it writes UI.
+
+    This is the DELIVERY side of a design system, and it exists because storing
+    one does not make a session aware of it. Rules get pushed into every session
+    by the plugin's SessionStart hook; a design system had no such channel, so
+    the standards were reachable only by an agent that already knew to go
+    looking — which is the same silent failure as a token nobody declares.
+
+    Guidance is chain-merged, ANCESTOR-FIRST, and that is the point rather than
+    a convenience. A child system holds only what it CHANGES, so its own
+    guidance describes a departure from a house style it never restates. Hand an
+    agent the leaf alone and it builds against a fragment, with no signal that
+    the rest exists.
+
+    Tokens are summarised, not listed: the count and the group names are enough
+    to know what the system covers, and the full set is one call away. Sending
+    a hundred token values into every session start would crowd out the context
+    it is meant to inform.
+
+    None when the caller may not read the system.
+    """
+    tokens = await resolve_design_system(user_id, design_system_id)
+    if tokens is None:
+        return None
+
+    async with async_session() as session:
+        system = await session.get(DesignSystem, design_system_id)
+        if system is None or system.deleted_at is not None:
+            return None
+        parents = await _parent_map(session, system.owner_user_id)
+        chain = ancestry(design_system_id, parents)
+        rows = (
+            await session.execute(
+                select(DesignSystem).where(DesignSystem.id.in_(chain))
+            )
+        ).scalars().all()
+
+    by_id = {s.id: s for s in rows}
+    return {
+        "id": system.id,
+        "title": system.title,
+        "description": system.description or "",
+        # Outermost ancestor first, so the reader meets the house style before
+        # the app's departures from it.
+        "inherits_from": [
+            by_id[sid].title for sid in reversed(chain[1:]) if sid in by_id
+        ],
+        "guidance": [
+            {
+                "design_system_id": sid,
+                "title": by_id[sid].title,
+                "guidance": (by_id[sid].guidance or "").strip(),
+            }
+            for sid in reversed(chain)
+            if sid in by_id and (by_id[sid].guidance or "").strip()
+        ],
+        "token_count": len(tokens),
+        "token_groups": sorted({t.group_name for t in tokens if t.group_name}),
+    }
+
+
 async def update_token(
     user_id: int, token_id: int, **fields: object
 ) -> DesignToken | None:

src/scribe/services/embeddings.py

@@ -14,7 +14,9 @@ import logging
 import math
 import os
 
-from sqlalchemy import delete, select
+from collections.abc import Sequence
+
+from sqlalchemy import delete, or_, select
 
 from scribe.models import async_session
 from scribe.models.embedding import NoteEmbedding
@@ -114,7 +116,8 @@ async def semantic_search_notes(
     threshold: float = _SIMILARITY_THRESHOLD,
     project_id: int | None = None,
     is_task: bool | None = None,
-    note_type: str | None = None,
+    note_type: str | Sequence[str] | None = None,
+    task_kind: str | Sequence[str] | None = None,
     orphan_only: bool = False,
     scope: str = "own",
 ) -> list[tuple[float, Note]]:
@@ -123,8 +126,15 @@ async def semantic_search_notes(
     Scores are cosine similarities in [-1, 1]; only notes at or above
     *threshold* are returned, sorted highest-first.
 
-    `note_type` narrows to a single record kind (e.g. "snippet"), for callers
-    that want prior art rather than everything embedded.
+    `note_type` narrows to a record kind, or several (e.g. "snippet", or
+    ("snippet", "note")), for callers that want prior art rather than everything
+    embedded.
+
+    `task_kind` restricts TASKS to the given kinds while leaving non-task notes
+    untouched. That asymmetry is the point: "recorded experience" is issues plus
+    dev-logs, and those differ on `is_task`, so neither `note_type` nor `is_task`
+    alone can express it. With `note_type="note", task_kind="issue"` a caller
+    gets fixed problems and durable notes without the open to-do list.
 
     `scope` ("own" | "browse" | "read", see access.notes_visibility_clause)
     decides how far this may see. It exists because this one function serves
@@ -179,11 +189,22 @@ async def semantic_search_notes(
                 stmt = stmt.where(Note.status.isnot(None))
             elif is_task is False:
                 stmt = stmt.where(Note.status.is_(None))
-            # Narrow to one kind of record. Composes with is_task rather than
-            # replacing it — 'snippet' is a non-task note_type, so a caller asking
-            # for prior art gets snippets and not the dev-log that mentions them.
+            # Narrow to one kind of record, or several. Composes with is_task
+            # rather than replacing it — 'snippet' is a non-task note_type, so a
+            # caller asking for prior art gets snippets and not the dev-log that
+            # mentions them.
             if note_type:
-                stmt = stmt.where(Note.note_type == note_type)
+                kinds = [note_type] if isinstance(note_type, str) else list(note_type)
+                stmt = stmt.where(Note.note_type.in_(kinds))
+            # Restrict TASKS to certain kinds while leaving notes alone. A note
+            # has no task_kind that means anything, so a plain `.in_()` would
+            # drop every dev-log — which is exactly the record a caller asking
+            # for prior experience wants most.
+            if task_kind:
+                tkinds = [task_kind] if isinstance(task_kind, str) else list(task_kind)
+                stmt = stmt.where(
+                    or_(Note.status.is_(None), Note.task_kind.in_(tkinds))
+                )
             if exclude_ids:
                 stmt = stmt.where(NoteEmbedding.note_id.notin_(exclude_ids))
             stmt = stmt.where(distance <= max_distance).order_by(distance.asc()).limit(limit)

src/scribe/services/notes.py

@@ -10,6 +10,40 @@ from scribe.models.note import Note, TaskPriority, TaskStatus
 logger = logging.getLogger(__name__)
 
 
+def embed_note(note) -> None:
+    """Refresh a note's embedding, fire-and-forget.
+
+    Lives HERE — at the service, not the route — so every caller gets it by
+    construction. Previously each REST route made this call itself and the MCP
+    tools did not, so a record created through MCP stayed out of semantic search
+    and auto-inject until the next restart's backfill ran (#2056). That is
+    invisible on an instance that redeploys constantly and permanent on one that
+    doesn't, which is the worst shape a bug can have: it only appears where
+    nobody is looking.
+
+    Uses `note.user_id` — the OWNER — rather than the caller. Embeddings belong
+    to the record, and a collaborator editing a shared note must refresh the
+    owner's row rather than mint a second one under their own id.
+
+    Import is lazy so importing this module doesn't pull in the embedding model;
+    exceptions are swallowed because a record that saved must not fail on its
+    index refresh. No running loop (unit tests, scripts) is an ordinary case,
+    not an error.
+    """
+    text = f"{note.title}\n{note.body}".strip() if note.body else (note.title or "")
+    if not text:
+        return
+    try:
+        import asyncio
+
+        from scribe.services.embeddings import upsert_note_embedding
+        asyncio.create_task(upsert_note_embedding(note.id, note.user_id, text))
+    except RuntimeError:
+        pass          # no running loop — a sync caller, not a failure
+    except Exception:  # noqa: BLE001 - never let indexing break a write
+        logger.exception("embedding refresh failed for note %s", note.id)
+
+
 def _normalize_tags(tags: list[str]) -> list[str]:
     """Lowercase, strip, deduplicate, and drop empty tags."""
     seen: set[str] = set()
@@ -115,6 +149,8 @@ async def create_note(
         await session.commit()
         await session.refresh(note)
 
+    embed_note(note)
+
     if project_id is not None:
         await _maybe_reactivate_project(project_id)
 
@@ -329,6 +365,8 @@ async def update_note(user_id: int, note_id: int, **fields: object) -> Note | No
         from scribe.services.note_versions import create_version
         await create_version(user_id, note_id, old_body, old_title, old_tags)
 
+    embed_note(note)
+
     if note.project_id is not None:
         await _maybe_reactivate_project(note.project_id)
 

src/scribe/services/plugin_context.py

@@ -22,6 +22,7 @@ from sqlalchemy import select
 
 from scribe.models import async_session
 from scribe.models.rulebook import RulebookTopic
+from scribe.services import design_systems as design_systems_svc
 from scribe.services import knowledge as knowledge_svc
 from scribe.services import notes as notes_svc
 from scribe.services import projects as projects_svc
@@ -289,6 +290,70 @@ def _record_kind(note) -> str:
     return note.note_type or "note"
 
 
+_REUSE_KINDS = ("snippet", "process")
+
+
+async def _reserve_slot_for_reuse(
+    user_id: int,
+    query: str,
+    kept: list,
+    cfg: dict,
+    *,
+    project_id: int | None,
+    exclude_ids: set[int],
+) -> list:
+    """Guarantee the reuse-shaped kinds one slot, if one clears threshold (#2246).
+
+    Ranking by raw cosine is blind to what KIND of record answers what kind of
+    ask, and the corpus makes that fatal rather than merely imperfect: Scribe's
+    project records are *about software work*, so a task titled "surface snippets
+    before the agent writes code" is a near-perfect lexical match for "write a
+    function…" while being useless as an answer to it. Measured live, a prompt
+    asking for a helper returned three records about BUILDING the retrieval
+    system and zero snippets.
+
+    The bias is structural and gets WORSE as the project record grows — which is
+    the direction Scribe is supposed to grow. Snippets are ~0.5% of the corpus
+    here; no threshold tuning fixes a 200:1 ratio.
+
+    So the reserved hit is deliberately NOT held to the margin band. The band
+    measures distance from the top overall score, and that top score is the very
+    thing snippets lose to. It still has to clear the configured threshold, so a
+    weak snippet cannot buy the slot — silence stays the default.
+    """
+    if any(_record_kind(n) in _REUSE_KINDS for _s, n in kept):
+        return kept                      # reuse already represented; nothing to do
+
+    top_k = cfg["top_k"]
+    reuse = await semantic_search_notes(
+        user_id, query,
+        limit=1,
+        threshold=cfg["threshold"],
+        project_id=project_id,
+        exclude_ids=exclude_ids | {int(n.id) for _s, n in kept},
+        note_type=_REUSE_KINDS,
+        scope="browse",
+    )
+    # Verify the kind rather than trusting the query that asked for it, and
+    # dedup on top of exclude_ids. This slot exists FOR reuse kinds — a slot
+    # silently spent on something else is worse than no slot, because the line
+    # is indistinguishable from one that earned its place on score.
+    kept_ids = {int(n.id) for _s, n in kept}
+    fresh = [
+        (s, n) for s, n in reuse
+        if _record_kind(n) in _REUSE_KINDS and int(n.id) not in kept_ids
+    ][:1]
+    if not fresh:
+        return kept
+
+    # Take the LAST slot, never the first: the strongest overall hit is still the
+    # best answer to the prompt, and displacing it would trade one blindness for
+    # another.
+    if len(kept) >= top_k:
+        return kept[:top_k - 1] + fresh
+    return (kept + fresh)[:top_k]
+
+
 async def build_autoinject_hint(
     user_id: int,
     query: str,
@@ -340,6 +405,10 @@ async def build_autoinject_hint(
     # Margin gate: keep only hits close to the strongest one.
     top_score = hits[0][0]
     kept = [(s, n) for s, n in hits if s >= top_score - _AUTOINJECT_BAND]
+    kept = await _reserve_slot_for_reuse(
+        user_id, q, kept, cfg, project_id=(project_id or None),
+        exclude_ids=set(exclude_ids or []),
+    )
 
     # A collaborator's note can reach this menu via a shared project, and the
     # operator never asked for it — so say whose it is. Unattributed, it reads as
@@ -684,7 +753,20 @@ async def build_write_path_hint(
             threshold=cfg["threshold"],
             project_id=scope_project,
             exclude_ids=seen,
-            note_type="snippet",
+            # Snippets AND recorded experience (#2246). This arm was
+            # snippets-only, which is auto-inject's mistake inverted: an issue
+            # saying "we tried this and it deadlocked", or a dev-log recording
+            # how a problem was solved, is prior art for the code about to be
+            # written — arguably better prior art than a resembling helper,
+            # because it says what NOT to do.
+            #
+            # `task_kind="issue"` keeps the open to-do list out. A task titled
+            # "add debouncing to the search box" resembles the code being
+            # written and answers nothing; an ISSUE is corrective work with a
+            # root cause in it, and a non-task note is durable knowledge. Both
+            # earned their place; a todo did not.
+            note_type=("snippet", "note"),
+            task_kind="issue",
             # Same reasoning as auto-inject: nobody asked for this, so it takes
             # the browse scope and never surfaces a one-to-one direct share.
             scope="browse",
@@ -692,7 +774,10 @@ async def build_write_path_hint(
         record_retrieval(
             user_id=user_id, source="write_path", query=query,
             threshold=cfg["threshold"], limit=remaining,
-            project_id=scope_project, is_task=False, results=hits,
+            # is_task is None, not False: this arm now returns issues too, and
+            # recording it as a notes-only retrieval would misdescribe the
+            # candidate set the threshold is being tuned against.
+            project_id=scope_project, is_task=None, results=hits,
             duration_ms=(time.perf_counter() - t0) * 1000.0,
         )
         if hits:
@@ -700,8 +785,15 @@ async def build_write_path_hint(
             for score, note in hits:
                 if score < top_score - _AUTOINJECT_BAND:
                     continue
+                # Name the kind unless it's a snippet — the menu's default and
+                # the header's default reading. An issue or a dev-log offered
+                # here is a different KIND of claim ("this was already tried")
+                # and an unlabelled line would be read as "here is code to
+                # reuse", which is the opposite of what it says.
+                kind = _record_kind(note)
                 scored.append((
-                    f"similar {score:.2f}",
+                    f"similar {score:.2f}" if kind == "snippet"
+                    else f"similar {score:.2f} · {kind}",
                     {
                         "id": int(note.id), "title": note.title, "user_id": note.user_id,
                         # Carried so the line can disclose a cross-language hit
@@ -732,7 +824,9 @@ async def build_write_path_hint(
 
     lines = [
         f"> Prior art already recorded in Scribe for `{path}` — open one with "
-        "`get_snippet(id)` and reuse it rather than writing a fresh one-off "
+        "`get_snippet(id)` for a snippet, `get_task(id)` for an issue, "
+        "`get_note(id)` otherwise. Reuse a snippet rather than writing a fresh "
+        "one-off; read an issue before repeating what it records "
         "(titles only; shown once per session):",
     ]
     # Say what a language tag MEANS, and only when one is actually on the menu.
@@ -837,6 +931,37 @@ async def build_session_context(
                 f"Goal: {goal[:200]}" if goal else "",
                 f"Open todo tasks: {open_count}",
             ]
+
+            # A design system binds the same way a rule does, and until this
+            # existed it had no push channel — the standards were reachable only
+            # by an agent that already knew to look for them. Summary only: the
+            # token VALUES are a tool call away, and pasting a hundred of them
+            # into every session would crowd out the context they inform.
+            if project.design_system_id:
+                design = await design_systems_svc.design_context(
+                    user_id, project.design_system_id,
+                )
+                if design:
+                    inherits = (
+                        " (inherits " + " › ".join(design["inherits_from"]) + ")"
+                        if design["inherits_from"] else ""
+                    )
+                    groups = ", ".join(design["token_groups"])
+                    lines += [
+                        "",
+                        f"## Design system: {design['title']} "
+                        f"(id {design['id']}){inherits}",
+                        f"{design['token_count']} tokens"
+                        + (f" across {groups}" if groups else "")
+                        + ". This project's UI is built from these, not from "
+                        "literals — reach for a token before writing a colour, "
+                        "size, radius or duration by hand.",
+                        f"Values: `resolve_design_system({design['id']})` · "
+                        f"stylesheet: `get_design_system_stylesheet({design['id']})` "
+                        f"· the prose (aesthetic, voice, where the accent may "
+                        f"appear): `enter_project` returns it, or "
+                        f"`get_design_system({design['id']})`.",
+                    ]
     elif unbound_repo:
         lines += [
             "",

src/scribe/services/snippets.py

@@ -28,7 +28,6 @@ came from.
 """
 from __future__ import annotations
 
-import asyncio
 import hashlib
 import logging
 import re
@@ -52,25 +51,6 @@ SNIPPET_TAG = "snippet"
 UNSET: object = object()
 
 
-def _embed_snippet(note) -> None:
-    """Fire-and-forget embedding refresh for a snippet.
-
-    A snippet's whole value is *immediate* recall — it must join the semantic /
-    auto-inject pool the moment it's recorded, not wait for the startup backfill.
-    Unlike a plain note (embedded at the REST-route boundary only, so its MCP
-    create path defers to restart-backfill), a snippet is recorded primarily via
-    MCP, so we embed here in the service — covering BOTH the MCP tool and the
-    REST route by construction. Mirrors the route pattern: fire-and-forget,
-    text = title + body. Import lazily so the pure serialize/parse helpers can be
-    imported without pulling in the embedding model.
-    """
-    text = f"{note.title}\n{note.body}".strip() if note.body else (note.title or "")
-    if not text:
-        return
-    from scribe.services.embeddings import upsert_note_embedding
-    asyncio.create_task(upsert_note_embedding(note.id, note.user_id, text))
-
-
 # --- serialize: structured fields -> note (title/body/tags) ------------------
 
 def compose_title(name: str, when_to_use: str = "") -> str:
@@ -640,7 +620,6 @@ async def create_snippet(
             language=language, code=code, locations=locations,
         ),
     )
-    _embed_snippet(note)
     return note
 
 
@@ -801,9 +780,6 @@ async def update_snippet(
     # As the OWNER: update_note is owner-scoped, so a shared editor's own id
     # would find nothing. The write was authorised by can_write_note above.
     updated = await notes_svc.update_note(note.user_id, snippet_id, **fields)
-    if updated is not None:
-        # Title/body changed → refresh the embedding so recall reflects the edit.
-        _embed_snippet(updated)
     return updated
 
 
@@ -1025,7 +1001,6 @@ async def merge_snippets(user_id: int, target_id: int, source_ids: list[int]):
         if batch is not None:
             merged_ids.append(s.id)
 
-    _embed_snippet(updated)
     return updated, merged_ids
 
 
@@ -1134,5 +1109,4 @@ async def unmerge_snippet(user_id: int, survivor_id: int, source_id: int):
     )
     if updated is None:
         return None
-    _embed_snippet(updated)
     return updated, restored

tests/test_check_design_tokens.py

@@ -0,0 +1,175 @@
+"""The CI-side token check (#2277).
+
+The checker is stdlib-only and lives in scripts/ so CI can run it without an
+install, so these tests import it by path rather than as a package.
+
+Two properties matter more than the parsing: it must not fire on a COMMENT that
+discusses a rule, and it must not fire on a longer literal that merely contains a
+shorter one. Both would make the report untrustworthy, and an untrustworthy
+report is worse than none — people stop reading it and the check stops working
+while still passing.
+"""
+import importlib.util
+import pathlib
+
+import pytest
+
+_PATH = pathlib.Path(__file__).resolve().parents[1] / "scripts" / "check_design_tokens.py"
+_spec = importlib.util.spec_from_file_location("check_design_tokens", _PATH)
+check = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(check)
+
+
+SHEET = """
+:root {
+  /* surface */
+  --fs-surface-page: #14171A;  /* page bg */
+  --fs-text-primary: #E8E4D8;
+}
+
+/* SUPERSEDES — write the token, not the literal.
+ * #fff -> --fs-text-primary
+ * #ffffff -> --fs-text-primary
+ * bold -> --fs-weight-medium
+ */
+"""
+
+
+# --- reading the sheet ------------------------------------------------------
+
+def test_declarations_after_a_comment_are_not_lost():
+    """Anchored on the colon alone. Anchoring on `{` or `;` silently drops every
+    declaration that follows a comment — a mistake made once already in this
+    codebase, which lost three tokens without erroring."""
+    assert check.declared_tokens(SHEET) == {"--fs-surface-page", "--fs-text-primary"}
+
+
+def test_the_supersedes_block_is_read_from_the_sheet_not_hardcoded():
+    """Rule #115: the checker must know nothing about any install's palette.
+    Everything it enforces comes out of the stylesheet it is pointed at."""
+    assert check.superseded_literals(SHEET) == {
+        "#fff": "--fs-text-primary",
+        "#ffffff": "--fs-text-primary",
+        "bold": "--fs-weight-medium",
+    }
+
+
+def test_a_sheet_with_no_supersedes_block_yields_nothing():
+    assert check.superseded_literals(":root { --a: 1px; }") == {}
+
+
+# --- the literal matcher ----------------------------------------------------
+
+def test_a_short_hex_does_not_match_inside_a_longer_one():
+    """`#fff` firing on `#ffffff` would send someone to change correct code."""
+    assert check._literal_pattern("#fff").search("color: #ffffff;") is None
+    assert check._literal_pattern("#fff").search("color: #fff;") is not None
+
+
+def test_the_match_is_case_insensitive():
+    assert check._literal_pattern("#ffffff").search("color: #FFFFFF;") is not None
+
+
+def test_a_keyword_does_not_match_inside_a_longer_word():
+    """`bold` must not fire on `font-weight: bolder` or a class named
+    `.bold-label` — the boundary is what keeps the report readable."""
+    assert check._literal_pattern("bold").search("font-weight: bolder;") is None
+    assert check._literal_pattern("bold").search(".bold-label { }") is None
+    assert check._literal_pattern("bold").search("font-weight: bold;") is not None
+
+
+# --- reading a component ----------------------------------------------------
+
+def test_only_the_style_block_of_an_sfc_is_read(tmp_path):
+    """A hex in a template attribute or a script string is not a stylesheet
+    violation, and reporting it would bury the ones that are."""
+    sfc = tmp_path / "X.vue"
+    sfc.write_text(
+        '<template><div data-x="#fff">white</div></template>\n'
+        '<script setup>const c = "#fff";</script>\n'
+        '<style scoped>.a { color: var(--fs-text-primary); }</style>\n'
+    )
+    css = check.style_source(sfc)
+    assert "--fs-text-primary" in css
+    assert "#fff" not in css
+
+
+def test_a_comment_explaining_a_rule_is_not_a_violation(tmp_path):
+    """LOAD-BEARING, and it fired on the first real run. A comment documenting
+    why a literal is avoided necessarily contains that literal — this codebase's
+    own stylesheet says so about `#fff`. A checker that flags the documentation
+    of a rule teaches people to stop documenting rules."""
+    sfc = tmp_path / "Y.vue"
+    sfc.write_text(
+        "<style scoped>\n"
+        "/* Deliberately NOT #fff — pure white is never text. */\n"
+        ".a { color: var(--fs-text-primary); }\n"
+        "</style>\n"
+    )
+    css = check.style_source(sfc)
+    assert check._literal_pattern("#fff").search(css) is None
+
+
+def test_a_plain_css_file_is_read_whole(tmp_path):
+    css_file = tmp_path / "shared.css"
+    css_file.write_text(".a { color: #fff; }")
+    assert "#fff" in check.style_source(css_file)
+
+
+# --- the gate ---------------------------------------------------------------
+
+def _run(tmp_path, sheet: str, component: str, monkeypatch, capsys):
+    (tmp_path / "assets").mkdir(parents=True, exist_ok=True)
+    sheet_path = tmp_path / "assets" / "theme.css"
+    sheet_path.write_text(sheet)
+    (tmp_path / "C.vue").write_text(f"<style>{component}</style>")
+    monkeypatch.setattr(
+        "sys.argv",
+        ["check", "--sheet", str(sheet_path), "--root", str(tmp_path)],
+    )
+    code = check.main()
+    return code, capsys.readouterr().out
+
+
+def test_an_unresolvable_reference_fails_the_build(tmp_path, monkeypatch, capsys):
+    """The one hard gate. It is safe to gate on because the count is zero today —
+    a ratchet holding a line already reached, not a backlog that keeps CI red."""
+    code, out = _run(tmp_path, SHEET, ".a { color: var(--nope); }", monkeypatch, capsys)
+    assert code == 1
+    assert "--nope" in out
+
+
+def test_a_resolvable_reference_passes(tmp_path, monkeypatch, capsys):
+    code, out = _run(
+        tmp_path, SHEET, ".a { color: var(--fs-text-primary); }", monkeypatch, capsys
+    )
+    assert code == 0
+    assert "every var() reference resolves" in out
+
+
+def test_a_locally_declared_property_is_not_unresolved(tmp_path, monkeypatch, capsys):
+    """A component may legitimately define its own custom property for local use —
+    a keyframe variable, a per-instance override. Only a reference to a name that
+    exists NOWHERE is broken."""
+    code, _ = _run(
+        tmp_path, SHEET, ".a { --local: 4px; padding: var(--local); }", monkeypatch, capsys
+    )
+    assert code == 0
+
+
+def test_a_superseded_literal_reports_but_does_not_fail(tmp_path, monkeypatch, capsys):
+    """Hundreds exist. Gating would make a permanently-red job, which is a check
+    nobody reads — worse than no check at all."""
+    code, out = _run(tmp_path, SHEET, ".a { color: #fff; }", monkeypatch, capsys)
+    assert code == 0
+    assert "#fff -> --fs-text-primary" in out
+
+
+def test_a_missing_stylesheet_is_an_error_not_a_pass(tmp_path, monkeypatch, capsys):
+    """If the sheet moves, the check must fail loudly rather than silently
+    passing with zero tokens to compare against — which would look identical to
+    a clean run."""
+    monkeypatch.setattr(
+        "sys.argv", ["check", "--sheet", str(tmp_path / "gone.css"), "--root", str(tmp_path)]
+    )
+    assert check.main() == 2

tests/test_mcp_tool_projects.py

@@ -17,12 +17,16 @@ def _bind_user():
     _user_id_ctx.reset(token)
 
 
-def _fake_project(**overrides) -> MagicMock:
+def _fake_project(design_system_id=None, **overrides) -> MagicMock:
     p = MagicMock()
     base = {"id": 1, "title": "P", "description": "", "goal": "",
             "status": "active", "color": None}
     base.update(overrides)
     p.to_dict.return_value = base
+    # Explicit, because a bare MagicMock hands back a truthy auto-attribute —
+    # which would route every project in this file through the design-system
+    # branch and out to a real database.
+    p.design_system_id = design_system_id
     return p
 
 
@@ -176,6 +180,45 @@ async def test_enter_project_composes_full_context():
     assert out["open_tasks"][0]["id"] == 100
     assert out["open_tasks"][0]["status"] == "in_progress"
     assert out["recent_notes"][0]["id"] == 200
+    # No design system on this project -> the key is present and null, not
+    # absent. A caller that has to distinguish "no key" from "no system" will
+    # eventually get it wrong.
+    assert out["design_system"] is None
+
+
+@pytest.mark.asyncio
+async def test_enter_project_hands_back_the_design_system_when_the_project_has_one():
+    """The handshake is where an agent learns what binds it, and a design
+    system binds the same way a rule does. Before this it was reachable only by
+    an agent that already knew to call resolve_design_system — so the standards
+    were present in the store and absent from the work."""
+    p = _fake_project(id=5, design_system_id=9)
+    design = {"id": 9, "title": "App kit", "guidance": [{"title": "House"}],
+              "token_count": 95, "token_groups": ["surface"],
+              "inherits_from": ["House"], "description": ""}
+
+    with patch(
+        "scribe.mcp.tools.projects.projects_svc.get_project",
+        AsyncMock(return_value=p),
+    ), patch(
+        "scribe.mcp.tools.projects.rulebooks_svc.get_applicable_rules",
+        AsyncMock(return_value={"rules": [], "truncated": False,
+                                "subscribed_rulebooks": []}),
+    ), patch(
+        "scribe.mcp.tools.projects.milestones_svc.get_project_milestone_summary",
+        AsyncMock(return_value=[]),
+    ), patch(
+        "scribe.mcp.tools.projects.notes_svc.list_notes",
+        AsyncMock(side_effect=[([], 0), ([], 0)]),
+    ), patch(
+        "scribe.mcp.tools.projects.design_systems_svc.design_context",
+        AsyncMock(return_value=design),
+    ) as ctx:
+        out = await enter_project(project_id=5)
+
+    assert out["design_system"]["token_count"] == 95
+    assert out["design_system"]["inherits_from"] == ["House"]
+    assert ctx.await_args.args == (7, 9)   # caller's id, the project's system
 
 
 @pytest.mark.asyncio

tests/test_note_usage.py

@@ -25,6 +25,9 @@ def _note(nid, title, user_id=1):
     # See the same note in test_write_path_trigger: an auto-created mock on
     # `.data` is truthy and would leak into a rendered menu line (#2244).
     n.data = None
+    # And on `.is_task`, which the kind marker reads FIRST — truthy there makes
+    # every one of these snippets read as a task (#2246).
+    n.is_task, n.task_kind = False, "work"
     return n
 
 

tests/test_services_backup.py

@@ -13,16 +13,54 @@ import pytest
 from scribe.services import backup
 
 
-def test_backup_version_is_v4():
-    assert backup.BACKUP_VERSION == 4
+def test_backup_version_is_v5():
+    assert backup.BACKUP_VERSION == 5
 
 
 def test_not_included_lists_the_known_gaps():
     # The deferred tables must be surfaced explicitly, not silently dropped.
-    for table in ("groups", "project_shares", "note_shares", "api_keys", "embeddings"):
+    for table in ("groups", "project_shares", "note_shares", "api_keys",
+                  "note_embeddings", "retrieval_logs"):
         assert table in backup._NOT_INCLUDED
 
 
+def test_every_table_is_either_backed_up_or_explicitly_excluded():
+    """THE GUARD (#2293), and the only shape of test that catches an ABSENCE.
+
+    A new table gets a model and a migration — both fail loudly if wrong — and
+    then silently never gets a backup section. No error, no warning, and a
+    restore that reports success. That is how `systems`, `record_systems`,
+    `note_usage_events`, `design_systems`, `design_tokens` and `repo_bindings`
+    all went missing, over five migrations, with nothing to notice.
+
+    Extending the export fixes today. THIS fixes the next one: adding a table
+    now fails here until someone either backs it up or states in
+    `_NOT_INCLUDED` that it shouldn't be. Either is fine; silence is not.
+    """
+    from scribe.models import Base
+
+    schema = set(Base.metadata.tables)
+    accounted = set(backup._BACKED_UP) | set(backup._NOT_INCLUDED)
+
+    unaccounted = schema - accounted
+    assert not unaccounted, (
+        f"{len(unaccounted)} table(s) are neither backed up nor explicitly "
+        f"excluded: {sorted(unaccounted)}. Add each to backup._BACKED_UP (and "
+        f"give it an export + restore section) or to backup._NOT_INCLUDED with "
+        f"a reason in the comment above it."
+    )
+
+    # And the reverse: a name in either list that no longer exists is a lie the
+    # guard would otherwise keep telling. This half is what caught "embeddings",
+    # "invitations" and "password_resets" — three entries that named nothing.
+    phantom = accounted - schema
+    assert not phantom, (
+        f"backup lists table(s) that are not in the schema: {sorted(phantom)}. "
+        f"Renamed or dropped — fix the list rather than leaving it to read as "
+        f"coverage."
+    )
+
+
 def test_join_table_row_helpers_are_pure():
     subs = [SimpleNamespace(project_id=1, rulebook_id=2)]
     rsup = [SimpleNamespace(project_id=1, rule_id=9)]
@@ -57,16 +95,18 @@ class _CM:
 
 
 @pytest.mark.asyncio
-async def test_export_full_backup_contains_v3_sections():
+async def test_export_full_backup_contains_every_declared_section():
     with patch("scribe.services.backup.async_session", lambda: _CM()):
         out = await backup.export_full_backup()
 
-    assert out["version"] == 4
+    assert out["version"] == backup.BACKUP_VERSION
     assert out["scope"] == "full"
     assert "api_keys" in out["_not_included"]
-    # The sections v2 silently dropped must now be present (empty here).
+    # The sections v2 silently dropped, plus the six v5 added (empty here).
     for key in ("rulebooks", "rulebook_topics", "rules",
                 "rulebook_subscriptions", "rule_suppressions",
-                "topic_suppressions"):
-        assert key in out, f"missing v3 section: {key}"
+                "topic_suppressions",
+                "systems", "record_systems", "design_systems",
+                "design_tokens", "note_usage_events", "repo_bindings"):
+        assert key in out, f"missing export section: {key}"
         assert out[key] == []

tests/test_services_design_systems.py

@@ -321,3 +321,94 @@ async def test_stylesheet_reports_what_the_sheet_cannot_say_for_itself():
     assert result["duplicates"] == {"#4a5d3f": ["--fs-moss", "--fs-success"]}
     assert "--fs-moss: #4a5d3f;" in result["css"]
     assert "FabledSword" in result["css"]
+
+
+# --- design_context: the delivery side --------------------------------------
+
+def _ctx_token(name: str, group: str | None):
+    from scribe.services.design_cascade import ResolvedToken
+    return ResolvedToken(
+        name=name, contributions={}, group_name=group,
+        purpose=None, rationale=None, supersedes=(), order_index=0,
+    )
+
+
+@pytest.mark.asyncio
+async def test_design_context_merges_guidance_ANCESTOR_FIRST():
+    """LOAD-BEARING. A child system holds only what it CHANGES, so its own
+    guidance describes a departure from a house style it never restates. An
+    agent handed the leaf alone builds against a fragment with no signal that
+    the rest exists — which is exactly the failure retiring the design rulebook
+    would otherwise have caused.
+    """
+    family = MagicMock(id=1, deleted_at=None, owner_user_id=42,
+                       description="the house", guidance="Dark-mode-first.")
+    family.title = "House"
+    app = MagicMock(id=3, deleted_at=None, owner_user_id=42,
+                    description="one app", guidance="Accent on the wordmark.")
+    app.title = "App"
+
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=app)
+    mock_session.execute = AsyncMock(return_value=MagicMock(
+        scalars=MagicMock(return_value=MagicMock(all=lambda: [app, family]))
+    ))
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems._parent_map",
+               AsyncMock(return_value={3: 1, 1: None})), \
+         patch("scribe.services.design_systems.resolve_design_system",
+               AsyncMock(return_value=[
+                   _ctx_token("--a", "surface"), _ctx_token("--b", "type"),
+                   _ctx_token("--c", "surface"), _ctx_token("--d", None),
+               ])):
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import design_context
+        out = await design_context(user_id=42, design_system_id=3)
+
+    assert [g["title"] for g in out["guidance"]] == ["House", "App"]
+    assert out["inherits_from"] == ["House"]
+    assert out["token_count"] == 4
+    # Group names deduped and sorted; an ungrouped token contributes nothing.
+    assert out["token_groups"] == ["surface", "type"]
+
+
+@pytest.mark.asyncio
+async def test_design_context_denied_returns_none():
+    """It rides on resolve_design_system's ACL rather than re-deriving one —
+    a second permission path is a second thing to get wrong."""
+    with patch("scribe.services.design_systems.resolve_design_system",
+               AsyncMock(return_value=None)):
+        from scribe.services.design_systems import design_context
+        assert await design_context(user_id=1, design_system_id=3) is None
+
+
+@pytest.mark.asyncio
+async def test_design_context_omits_systems_with_no_guidance():
+    """A system that overrides one token and says nothing about it should not
+    contribute an empty section — a heading with nothing under it reads as
+    missing content rather than as an absence of content."""
+    family = MagicMock(id=1, deleted_at=None, owner_user_id=42,
+                       description="", guidance="Dark-mode-first.")
+    family.title = "House"
+    app = MagicMock(id=3, deleted_at=None, owner_user_id=42,
+                    description="", guidance="   ")
+    app.title = "App"
+
+    mock_session = _make_mock_session()
+    mock_session.get = AsyncMock(return_value=app)
+    mock_session.execute = AsyncMock(return_value=MagicMock(
+        scalars=MagicMock(return_value=MagicMock(all=lambda: [app, family]))
+    ))
+
+    with patch("scribe.services.design_systems.async_session") as mock_cls, \
+         patch("scribe.services.design_systems._parent_map",
+               AsyncMock(return_value={3: 1, 1: None})), \
+         patch("scribe.services.design_systems.resolve_design_system",
+               AsyncMock(return_value=[])):
+        mock_cls.return_value = mock_session
+        from scribe.services.design_systems import design_context
+        out = await design_context(user_id=42, design_system_id=3)
+
+    assert [g["title"] for g in out["guidance"]] == ["House"]
+    assert out["token_count"] == 0

tests/test_services_notes.py

@@ -0,0 +1,64 @@
+"""services/notes.py — the inline embedding moved here from the routes (#2056).
+
+Why it moved: embedding was triggered at each REST route and nowhere else, so a
+record created through MCP stayed out of semantic search and auto-inject until
+the next restart's backfill. Putting it in the service means every caller — REST,
+MCP, recurrence, snippets — gets it by construction rather than by remembering.
+
+These test the helper directly. The point of the change is that there is now ONE
+place to test.
+"""
+from scribe.services import notes as notes_svc
+
+# --- inline embedding (#2056) -----------------------------------------------
+
+def test_embed_note_uses_the_OWNER_not_the_caller():
+    """LOAD-BEARING for shared records. An embedding belongs to the record; a
+    collaborator editing a shared note must refresh the owner's row rather than
+    mint a second one under their own id. The routes this replaced passed the
+    caller's uid on one path and the owner's on another — exactly the kind of
+    inconsistency that moving it to one place removes."""
+    from unittest.mock import MagicMock, patch
+
+    note = MagicMock(id=5, user_id=42, title="T", body="B")
+    with patch("scribe.services.embeddings.upsert_note_embedding") as upsert, \
+         patch("asyncio.create_task") as create_task:
+        notes_svc.embed_note(note)
+
+    assert create_task.called
+    upsert.assert_called_once()
+    assert upsert.call_args.args[0] == 5
+    assert upsert.call_args.args[1] == 42          # owner, never the caller
+    assert upsert.call_args.args[2] == "T\nB"
+
+
+def test_embed_note_skips_a_record_with_no_text():
+    """An empty embedding is worse than none — it is a row that matches nothing
+    and hides the fact that the record was never indexed."""
+    from unittest.mock import MagicMock, patch
+
+    note = MagicMock(id=5, user_id=42, title="", body="")
+    with patch("asyncio.create_task") as create_task:
+        notes_svc.embed_note(note)
+    assert not create_task.called
+
+
+def test_embed_note_without_a_running_loop_is_not_an_error():
+    """Unit tests and scripts call create_note with no event loop. That must be
+    an ordinary case: a write that succeeded cannot be failed by its index
+    refresh."""
+    from unittest.mock import MagicMock, patch
+
+    note = MagicMock(id=5, user_id=42, title="T", body="B")
+    with patch("asyncio.create_task", side_effect=RuntimeError("no running loop")):
+        notes_svc.embed_note(note)          # must not raise
+
+
+def test_embed_note_swallows_an_indexing_failure():
+    """Same reason, wider net: the embedding model being unavailable must not
+    turn a successful save into a 500."""
+    from unittest.mock import MagicMock, patch
+
+    note = MagicMock(id=5, user_id=42, title="T", body="B")
+    with patch("asyncio.create_task", side_effect=ValueError("model gone")):
+        notes_svc.embed_note(note)          # must not raise

tests/test_services_plugin_context.py

@@ -19,6 +19,9 @@ def _note(nid, title, user_id=1, note_type="note", is_task=False, task_kind="wor
     # auto-MagicMock is truthy, so every line would read as another user's task.
     n.user_id = user_id
     n.note_type, n.is_task, n.task_kind = note_type, is_task, task_kind
+    # The write-path menu reads note.data for a language tag; an auto-mock there
+    # is truthy and renders its repr into the marker.
+    n.data = None
     return n
 
 
@@ -130,7 +133,11 @@ async def test_build_session_context_renders_titles_grouped_by_topic():
 
 @pytest.mark.asyncio
 async def test_build_session_context_includes_project_when_scoped():
-    project = MagicMock(id=2, title="FabledScribe", goal="ship it")
+    # design_system_id explicitly None: a bare MagicMock would hand back a truthy
+    # auto-attribute and send this through the design branch, which is the
+    # opposite of what this test is about.
+    project = MagicMock(id=2, title="FabledScribe", goal="ship it",
+                        design_system_id=None)
     with patch("scribe.services.plugin_context.rulebooks_svc.list_always_on_rules",
                AsyncMock(return_value=[_rule(1, "rule", 1)])), \
          patch("scribe.services.plugin_context._topic_titles",
@@ -145,6 +152,68 @@ async def test_build_session_context_includes_project_when_scoped():
     assert out["project"] == {"id": 2, "title": "FabledScribe"}
     assert "## Active project: FabledScribe (id 2)" in out["context"]
     assert "Open todo tasks: 4" in out["context"]
+    # No design system on the project -> no design block at all. An install with
+    # none is the ordinary case, not a degraded one.
+    assert "## Design system" not in out["context"]
+
+
+@pytest.mark.asyncio
+async def test_build_session_context_pushes_the_projects_design_system():
+    """The gap this closes: a design system had no push channel, so its
+    standards reached a session only if the agent already knew to go looking —
+    the same silent failure as a token nobody declares."""
+    project = MagicMock(id=2, title="App", goal="", design_system_id=9)
+    design = {
+        "id": 9, "title": "App kit", "description": "",
+        "inherits_from": ["House"],
+        "guidance": [], "token_count": 95,
+        "token_groups": ["accent", "surface", "type"],
+    }
+    with patch("scribe.services.plugin_context.rulebooks_svc.list_always_on_rules",
+               AsyncMock(return_value=[_rule(1, "rule", 1)])), \
+         patch("scribe.services.plugin_context._topic_titles",
+               AsyncMock(return_value={1: "git-workflow"})), \
+         patch("scribe.services.plugin_context.projects_svc.get_project",
+               AsyncMock(return_value=project)), \
+         patch("scribe.services.plugin_context.notes_svc.list_notes",
+               AsyncMock(return_value=([], 0))), \
+         patch("scribe.services.plugin_context.design_systems_svc.design_context",
+               AsyncMock(return_value=design)):
+        from scribe.services.plugin_context import build_session_context
+        out = await build_session_context(user_id=7, project_id=2)
+
+    ctx = out["context"]
+    assert "## Design system: App kit (id 9) (inherits House)" in ctx
+    assert "95 tokens across accent, surface, type" in ctx
+    # A pointer to the values, never the values themselves — a hundred token
+    # declarations would crowd out the context they are meant to inform. The
+    # summary carries counts and group NAMES only, which is why design_context
+    # returns those rather than the resolved tokens.
+    assert "resolve_design_system(9)" in ctx
+    assert "get_design_system_stylesheet(9)" in ctx
+
+
+@pytest.mark.asyncio
+async def test_build_session_context_survives_an_unreadable_design_system():
+    """design_context returns None when the caller may not read the system.
+    That must degrade to "no design block", not to a crash that costs the
+    session its rules too."""
+    project = MagicMock(id=2, title="App", goal="", design_system_id=9)
+    with patch("scribe.services.plugin_context.rulebooks_svc.list_always_on_rules",
+               AsyncMock(return_value=[_rule(1, "rule", 1)])), \
+         patch("scribe.services.plugin_context._topic_titles",
+               AsyncMock(return_value={1: "git-workflow"})), \
+         patch("scribe.services.plugin_context.projects_svc.get_project",
+               AsyncMock(return_value=project)), \
+         patch("scribe.services.plugin_context.notes_svc.list_notes",
+               AsyncMock(return_value=([], 0))), \
+         patch("scribe.services.plugin_context.design_systems_svc.design_context",
+               AsyncMock(return_value=None)):
+        from scribe.services.plugin_context import build_session_context
+        out = await build_session_context(user_id=7, project_id=2)
+
+    assert "## Design system" not in out["context"]
+    assert "## Active project: App (id 2)" in out["context"]
 
 
 @pytest.mark.asyncio
@@ -229,3 +298,174 @@ async def test_build_session_context_caps_length():
 
     assert len(out["context"]) <= 9000 + 60  # cap + truncation note
     assert "truncated" in out["context"]
+
+
+# --- the reuse slot (#2246) --------------------------------------------------
+
+_CFG = {"enabled": True, "threshold": 0.55, "top_k": 3}
+
+
+async def _autoinject(main_hits, reuse_hits, cfg=None):
+    """Run build_autoinject_hint with the two semantic queries stubbed in order:
+    the unscoped pool first, then the reserved reuse query."""
+    calls: list[dict] = []
+
+    async def fake_search(*_a, **kw):
+        calls.append(kw)
+        return reuse_hits if kw.get("note_type") else main_hits
+
+    with patch("scribe.services.plugin_context.get_autoinject_config",
+               AsyncMock(return_value=dict(cfg or _CFG))), \
+         patch("scribe.services.plugin_context.semantic_search_notes",
+               AsyncMock(side_effect=fake_search)), \
+         patch("scribe.services.plugin_context.record_retrieval", MagicMock()), \
+         patch("scribe.services.plugin_context.record_surfaced", MagicMock()), \
+         patch("scribe.services.plugin_context.owner_names_for",
+               AsyncMock(return_value={})):
+        from scribe.services.plugin_context import build_autoinject_hint
+        out = await build_autoinject_hint(1, "write a debounce helper")
+    return out, calls
+
+
+@pytest.mark.asyncio
+async def test_a_snippet_takes_the_last_slot_when_none_won_on_score():
+    """The measured failure: a prompt asking for a helper returned three project
+    records ABOUT building the retrieval system, and zero snippets. Scribe's own
+    records are about software work, so they share vocabulary with any coding
+    prompt while answering none of them."""
+    main = [(0.66, _note(1, "Step 3: title-first auto-inject")),
+            (0.65, _note(2, "Task-reminder dedup query crashes", is_task=True)),
+            (0.64, _note(3, "Drafter hardening · write-path trigger", is_task=True))]
+    reuse = [(0.58, _note(9, "debounce — collapse rapid calls", note_type="snippet"))]
+
+    out, calls = await _autoinject(main, reuse)
+
+    assert out["note_ids"] == [1, 2, 9]        # last slot displaced, not the first
+    assert "#9" in out["context"] and "[snippet]" in out["context"]
+    # The reserved query is scoped to the reuse kinds and asks for exactly one.
+    assert calls[1]["note_type"] == ("snippet", "process")
+    assert calls[1]["limit"] == 1
+
+
+@pytest.mark.asyncio
+async def test_the_reserved_query_is_skipped_when_a_snippet_already_won():
+    """No second query, and no slot spent twice, when ranking already did the
+    right thing — the fix must be invisible in the case it isn't needed."""
+    main = [(0.81, _note(9, "debounce helper", note_type="snippet")),
+            (0.80, _note(1, "some task", is_task=True))]
+
+    out, calls = await _autoinject(main, [])
+
+    assert len(calls) == 1                      # reserved query never ran
+    assert out["note_ids"] == [9, 1]
+
+
+@pytest.mark.asyncio
+async def test_a_weak_snippet_does_not_buy_the_slot():
+    """The reserved hit skips the MARGIN band — that band is what snippets lose
+    to — but never the threshold. Silence stays the default; a slot spent on an
+    irrelevant snippet is how a menu teaches people to ignore it."""
+    main = [(0.66, _note(1, "a task", is_task=True))]
+
+    out, calls = await _autoinject(main, [])     # threshold returned nothing
+
+    assert out["note_ids"] == [1]
+    assert len(calls) == 2                       # it asked, and got nothing
+
+
+@pytest.mark.asyncio
+async def test_the_reserved_hit_is_not_held_to_the_margin_band():
+    """0.58 is 0.08 below the top hit. Under the band it would survive; the point
+    is that it must survive even when it wouldn't — a snippet losing to a
+    same-vocabulary project record by a wide margin is the whole bug."""
+    main = [(0.90, _note(1, "a task", is_task=True))]
+    reuse = [(0.58, _note(9, "debounce", note_type="snippet"))]
+
+    out, _calls = await _autoinject(main, reuse)
+
+    assert 9 in out["note_ids"]
+
+
+@pytest.mark.asyncio
+async def test_a_process_counts_as_reuse_too():
+    """A stored process answers 'how do we do X here' the same way a snippet
+    answers 'what do we already have' — both lose to the same project records."""
+    main = [(0.70, _note(1, "a task", is_task=True))]
+    reuse = [(0.60, _note(8, "DRY pass process", note_type="process"))]
+
+    out, _ = await _autoinject(main, reuse)
+    assert 8 in out["note_ids"]
+
+    # …and one already on the menu suppresses the reserved query.
+    out2, calls2 = await _autoinject(
+        [(0.70, _note(8, "DRY pass process", note_type="process"))], [])
+    assert len(calls2) == 1
+
+
+# --- write-path widened beyond snippets (#2246, the mirror half) -------------
+
+@pytest.mark.asyncio
+async def test_write_path_semantic_arm_asks_for_experience_not_just_snippets():
+    """The inverse of auto-inject's mistake. This arm was snippets-only, so an
+    issue saying "we tried this and it deadlocked" could never reach the moment
+    that code was about to be written — arguably the better prior art, because
+    it says what NOT to do."""
+    from scribe.services import plugin_context as pc
+
+    hits = [(0.72, _note(9, "debounce helper", note_type="snippet")),
+            (0.70, _note(7, "Debounce dropped the trailing call", is_task=True,
+                         task_kind="issue"))]
+    search = AsyncMock(return_value=hits)
+    rec = MagicMock()
+    with patch.object(pc, "get_writepath_config",
+                      AsyncMock(return_value={"enabled": True, "threshold": 0.6,
+                                              "top_k": 3})), \
+         patch.object(pc.snippets_svc, "list_snippets",
+                      AsyncMock(return_value=([], 0))), \
+         patch.object(pc, "semantic_search_notes", search), \
+         patch.object(pc, "record_retrieval", rec), \
+         patch.object(pc, "record_surfaced", MagicMock()), \
+         patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
+         patch.object(pc, "concept_query", MagicMock(return_value="debounce a callback")):
+        out = await pc.build_write_path_hint(
+            1, "src/utils/debounce.ts", code="x" * 400,
+        )
+
+    kw = search.await_args.kwargs
+    assert kw["note_type"] == ("snippet", "note")
+    # An open to-do resembling the code answers nothing; an ISSUE carries a root
+    # cause and a NOTE carries durable knowledge. Only the todo is excluded.
+    assert kw["task_kind"] == "issue"
+    # Telemetry must not claim this was a notes-only retrieval any more.
+    assert rec.call_args.kwargs["is_task"] is None
+
+
+@pytest.mark.asyncio
+async def test_write_path_labels_a_non_snippet_hit_with_its_kind():
+    """An unlabelled issue on this menu reads as "here is code to reuse", which
+    is the opposite of what it says. A snippet stays unlabelled — it is the
+    menu's default and the header's default reading."""
+    from scribe.services import plugin_context as pc
+
+    hits = [(0.72, _note(9, "debounce helper", note_type="snippet")),
+            (0.71, _note(7, "Debounce dropped the trailing call", is_task=True,
+                         task_kind="issue"))]
+    with patch.object(pc, "get_writepath_config",
+                      AsyncMock(return_value={"enabled": True, "threshold": 0.6,
+                                              "top_k": 3})), \
+         patch.object(pc.snippets_svc, "list_snippets",
+                      AsyncMock(return_value=([], 0))), \
+         patch.object(pc, "semantic_search_notes", AsyncMock(return_value=hits)), \
+         patch.object(pc, "record_retrieval", MagicMock()), \
+         patch.object(pc, "record_surfaced", MagicMock()), \
+         patch.object(pc, "owner_names_for", AsyncMock(return_value={})), \
+         patch.object(pc, "concept_query", MagicMock(return_value="debounce a callback")):
+        out = await pc.build_write_path_hint(
+            1, "src/utils/debounce.ts", code="x" * 400,
+        )
+
+    ctx = out["context"]
+    assert "· issue]" in ctx                 # the issue says what it is
+    assert '[similar 0.72] "debounce helper"' in ctx   # the snippet does not
+    # The header now names the right opener for each kind.
+    assert "get_task(id)" in ctx and "get_snippet(id)" in ctx

tests/test_shared_write_access.py

@@ -40,8 +40,7 @@ async def test_editor_share_can_update_and_writes_as_the_owner():
     with patch.object(svc, "get_snippet", AsyncMock(return_value=note)), \
          patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)), \
          patch.object(svc.notes_svc, "update_note",
-                      AsyncMock(return_value=updated)) as mock_update, \
-         patch.object(svc, "_embed_snippet", MagicMock()):
+                      AsyncMock(return_value=updated)) as mock_update:
         got = await svc.update_snippet(7, 1, name="formatDuration")
 
     assert got is updated
@@ -107,8 +106,7 @@ async def test_merge_skips_sources_owned_by_someone_else():
     with patch.object(svc, "get_snippet", AsyncMock(side_effect=fake_get)), \
          patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)), \
          patch.object(svc.notes_svc, "update_note", AsyncMock(return_value=target)), \
-         patch("scribe.services.trash.delete", AsyncMock(return_value=object())), \
-         patch.object(svc, "_embed_snippet", MagicMock()):
+         patch("scribe.services.trash.delete", AsyncMock(return_value=object())):
         _note, merged_ids = await svc.merge_snippets(7, 1, [2, 3])
 
     assert merged_ids == [2]

tests/test_snippet_merge_provenance.py

@@ -39,8 +39,7 @@ async def _run_merge(target, sources, source_ids):
          patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)), \
          patch.object(s.notes_svc, "update_note",
                       AsyncMock(return_value=target)) as mock_update, \
-         patch("scribe.services.trash.delete", AsyncMock(return_value=object())), \
-         patch.object(s, "_embed_snippet", MagicMock()):
+         patch("scribe.services.trash.delete", AsyncMock(return_value=object())):
         await s.merge_snippets(7, target.id, source_ids)
     return mock_update.await_args.kwargs
 
@@ -88,8 +87,7 @@ async def test_an_ordinary_edit_carries_provenance_forward():
     with patch.object(s, "get_snippet", AsyncMock(return_value=note)), \
          patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)), \
          patch.object(s.notes_svc, "update_note",
-                      AsyncMock(return_value=note)) as mock_update, \
-         patch.object(s, "_embed_snippet", MagicMock()):
+                      AsyncMock(return_value=note)) as mock_update:
         await s.update_snippet(7, 1, signature="f(ms) -> string")
 
     kwargs = mock_update.await_args.kwargs
@@ -106,8 +104,7 @@ async def test_a_pre_0070_row_keeps_provenance_through_the_body():
     with patch.object(s, "get_snippet", AsyncMock(return_value=note)), \
          patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)), \
          patch.object(s.notes_svc, "update_note",
-                      AsyncMock(return_value=note)) as mock_update, \
-         patch.object(s, "_embed_snippet", MagicMock()):
+                      AsyncMock(return_value=note)) as mock_update:
         await s.update_snippet(7, 1, when_to_use="humanize a ms count")
 
     assert "**Merged from:** #5" in mock_update.await_args.kwargs["body"]

tests/test_snippet_unmerge.py

@@ -44,7 +44,6 @@ async def _run_unmerge(survivor, *, source_alive=None, restore=1):
         patch("scribe.services.trash.restore_entity", AsyncMock(return_value=restore)),
         patch.object(s.notes_svc, "update_note",
                      AsyncMock(return_value=survivor)) as upd,
-        patch.object(s, "_embed_snippet", MagicMock()),
     ):
         await s.unmerge_snippet(7, 1, 2)
     return upd.await_args.kwargs
@@ -127,7 +126,6 @@ async def test_a_purged_source_is_refused_and_the_survivor_is_untouched():
         patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)),
         patch("scribe.services.trash.restore_entity", AsyncMock(return_value=None)),
         patch.object(s.notes_svc, "update_note", AsyncMock()) as upd,
-        patch.object(s, "_embed_snippet", MagicMock()),
     ):
         with pytest.raises(s.UnmergeError, match="purged"):
             await s.unmerge_snippet(7, 1, 2)
@@ -150,7 +148,6 @@ async def test_an_entry_without_attribution_is_refused_not_guessed():
         patch.object(s, "get_snippet", AsyncMock(side_effect=fake_get)),
         patch("scribe.services.access.can_write_note", AsyncMock(return_value=True)),
         patch.object(s.notes_svc, "update_note", AsyncMock()) as upd,
-        patch.object(s, "_embed_snippet", MagicMock()),
     ):
         with pytest.raises(s.UnmergeError, match="provenance"):
             await s.unmerge_snippet(7, 1, 2)

tests/test_write_path_trigger.py

@@ -23,13 +23,17 @@ def _snippet_item(nid, title, user_id=1):
     return {"id": nid, "title": title, "user_id": user_id, "note_type": "snippet"}
 
 
-def _note(nid, title, user_id=1):
+def _note(nid, title, user_id=1, note_type="snippet", is_task=False, task_kind="work"):
     n = MagicMock()
     n.id, n.title, n.user_id = nid, title, user_id
     # Explicitly None, not left to MagicMock's auto-attribute: the semantic arm
     # reads `note.data` for the snippet's language (#2244), and an auto-created
     # mock there is truthy, so it would render its repr into the menu line.
     n.data = None
+    # Same reasoning, second instance: since #2246 this arm returns issues and
+    # dev-logs too, so the line names the kind. An auto-mock `is_task` is truthy,
+    # which would label every snippet here "task".
+    n.note_type, n.is_task, n.task_kind = note_type, is_task, task_kind
     return n
 
 
@@ -183,8 +187,11 @@ async def test_semantic_arm_is_snippet_only_and_browse_scoped():
          patch.object(pc, "record_retrieval", MagicMock()):
         await pc.build_write_path_hint(1, "src/x.py", code=REAL_CODE)
     kwargs = search.await_args.kwargs
-    # Prior art means snippets — not the dev-log that happens to mention one.
-    assert kwargs["note_type"] == "snippet"
+    # Prior art is snippets AND recorded experience (#2246) — an issue saying
+    # "we tried this and it broke" belongs here. What stays out is the open
+    # to-do list, which resembles the code and answers nothing.
+    assert kwargs["note_type"] == ("snippet", "note")
+    assert kwargs["task_kind"] == "issue"
     # Nobody asked for this, so it must not reach a one-to-one direct share.
     assert kwargs["scope"] == "browse"