From 361fea7408087063ddbd45ce25440619bd12c265 Mon Sep 17 00:00:00 2001
From: Randall Hand <randall.hand@gmail.com>
Date: Sun, 5 Jul 2026 10:13:48 -0400
Subject: [PATCH] feat(nodes): add per-node free-text notes field (#3921)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an optional free-text `notes` annotation per node, scoped per source
like other per-node local metadata (favorites/ignored/hide-from-map). This
mirrors the official Meshtastic mobile clients' local "notes" field, but
persists server-side so it survives across devices/browsers. It is purely
MeshMonitor-local state — never synced to or from the mesh.

Backend:
- Migration 112 adds nullable `nodes.notes` (TEXT / VARCHAR(2000)) across
  SQLite/PostgreSQL/MySQL, idempotent; existing rows keep NULL.
- Schema (3 backends), DbNode / NodeData / DeviceInfo types, dbNodeMapper.
- NodesRepository.setNodeNotes (Drizzle, all backends, source-scoped) and
  DatabaseService.setNodeNotesAsync (repo-backed, no raw SQL).
- upsertNode preserves notes across packet-driven updates and, like `mobile`,
  intentionally omits notes from the conflict DO-UPDATE so a packet never
  clobbers a user-authored note.
- POST /api/nodes/:nodeId/notes route (requirePermission nodes/write, source
  from body, string + 2000-char + hex-nodeId validation).

Frontend:
- Editable notes textarea in NodeDetailsBlock (node detail view in Messages),
  gated on nodes/write permission; read-only display otherwise. Draft tracks
  a local baseline so Save settles immediately before the node poll catches up.
- apiService.setNodeNotes client method + styling.

Tests:
- Repository per-source isolation + notes-preservation tests.
- Route validation-contract tests (set/clear/type/length/sourceId/nodeId).
- Migration registry count/last-name bump to 112.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AphLfgUJWaFNAgU5UXdJ4n
---
 CLAUDE.md                                     |  2 +-
 src/components/MessagesTab.tsx                | 14 ++-
 src/components/NodeDetailsBlock.css           | 62 ++++++++++++
 src/components/NodeDetailsBlock.tsx           | 80 +++++++++++++++-
 src/db/migrations.test.ts                     | 12 +--
 src/db/migrations.ts                          | 17 ++++
 src/db/repositories/nodes.test.ts             | 64 +++++++++++++
 src/db/repositories/nodes.ts                  | 23 +++++
 src/db/schema/nodes.ts                        | 12 +++
 src/db/types.ts                               |  2 +
 .../migrations/112_add_notes_to_nodes.ts      | 69 ++++++++++++++
 src/server/server.test.ts                     | 95 +++++++++++++++++++
 src/server/server.ts                          | 72 ++++++++++++++
 src/server/utils/dbNodeMapper.ts              |  3 +
 src/services/api.ts                           | 21 ++++
 src/services/database.ts                      | 31 ++++++
 src/types/device.ts                           |  1 +
 17 files changed, 571 insertions(+), 9 deletions(-)
 create mode 100644 src/server/migrations/112_add_notes_to_nodes.ts

diff --git a/CLAUDE.md b/CLAUDE.md
index fb290c329..50aa0dfd5 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -98,7 +98,7 @@ For per-source permission tests, mock `getUserPermissionSetAsync(userId, sourceI
 ### Migration Registry
 Migrations use a centralized registry in `src/db/migrations.ts`. Each migration has functions for all three backends.
 
-**Current migration count:** 110 (latest: `110_add_meshcore_position_history`).
+**Current migration count:** 112 (latest: `112_add_notes_to_nodes`).
 
 For the full "adding a migration" recipe see [Migration recipe](#migration-recipe) below.
 
diff --git a/src/components/MessagesTab.tsx b/src/components/MessagesTab.tsx
index bff3dfba5..af8fea251 100644
--- a/src/components/MessagesTab.tsx
+++ b/src/components/MessagesTab.tsx
@@ -2158,7 +2158,19 @@ const MessagesTab: React.FC<MessagesTabProps> = ({
               )}
             </div>
 
-            {selectedNode && <NodeDetailsBlock node={selectedNode} timeFormat={timeFormat} dateFormat={dateFormat} />}
+            {selectedNode && (
+              <NodeDetailsBlock
+                node={selectedNode}
+                timeFormat={timeFormat}
+                dateFormat={dateFormat}
+                canEditNotes={hasPermission('nodes', 'write')}
+                onSaveNotes={async (notes) => {
+                  if (!selectedNode.user?.id) throw new Error('Node has no ID');
+                  await apiService.setNodeNotes(selectedNode.user.id, notes, sourceId);
+                  showToast(t('node_details.notes_saved', 'Notes saved'), 'success');
+                }}
+              />
+            )}
 
             {/* Security Details Section */}
             {selectedNode &&
diff --git a/src/components/NodeDetailsBlock.css b/src/components/NodeDetailsBlock.css
index 7cedd1db4..924315cad 100644
--- a/src/components/NodeDetailsBlock.css
+++ b/src/components/NodeDetailsBlock.css
@@ -131,6 +131,68 @@
   grid-column: span 2;
 }
 
+/* Notes (#3921) — editable free-text per-node annotation */
+.node-detail-notes-input {
+  width: 100%;
+  box-sizing: border-box;
+  margin-top: 4px;
+  padding: 8px 10px;
+  background-color: var(--ctp-base);
+  color: var(--ctp-text);
+  border: 1px solid var(--ctp-surface1);
+  border-radius: var(--radius-sm);
+  font-family: inherit;
+  font-size: 0.95rem;
+  line-height: 1.4;
+  resize: vertical;
+}
+
+.node-detail-notes-input:focus {
+  outline: none;
+  border-color: var(--ctp-blue);
+}
+
+.node-detail-notes-input:disabled {
+  opacity: 0.6;
+}
+
+.node-detail-notes-readonly {
+  font-size: 0.95rem;
+  font-weight: 400;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.node-detail-notes-error {
+  display: block;
+  color: var(--ctp-red);
+  font-size: 0.85rem;
+  margin-top: 4px;
+}
+
+.node-detail-notes-actions {
+  display: flex;
+  justify-content: flex-end;
+  margin-top: 8px;
+}
+
+.node-detail-notes-save {
+  background-color: var(--ctp-blue);
+  color: var(--ctp-base);
+  border: none;
+  border-radius: var(--radius-sm);
+  padding: 6px 14px;
+  font-size: 0.9rem;
+  font-weight: 600;
+  cursor: pointer;
+  transition: opacity 0.2s ease;
+}
+
+.node-detail-notes-save:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
 /* Public key styling */
 .node-detail-public-key {
   font-family: var(--font-mono);
diff --git a/src/components/NodeDetailsBlock.tsx b/src/components/NodeDetailsBlock.tsx
index f1172972e..bd0b3134b 100644
--- a/src/components/NodeDetailsBlock.tsx
+++ b/src/components/NodeDetailsBlock.tsx
@@ -15,9 +15,19 @@ interface NodeDetailsBlockProps {
   node: DeviceInfo | null;
   timeFormat?: TimeFormat;
   dateFormat?: DateFormat;
+  /**
+   * When true (and `onSaveNotes` is provided), the free-text notes field (#3921)
+   * is rendered as an editable textarea. Otherwise any existing note is shown
+   * read-only.
+   */
+  canEditNotes?: boolean;
+  /** Persist the edited note. Resolves on success, rejects on failure. */
+  onSaveNotes?: (notes: string) => Promise<void>;
 }
 
-const NodeDetailsBlock: React.FC<NodeDetailsBlockProps> = ({ node, timeFormat = '24', dateFormat = 'MM/DD/YYYY' }) => {
+const MAX_NODE_NOTES_LENGTH = 2000;
+
+const NodeDetailsBlock: React.FC<NodeDetailsBlockProps> = ({ node, timeFormat = '24', dateFormat = 'MM/DD/YYYY', canEditNotes = false, onSaveNotes }) => {
   const { t } = useTranslation();
   const { channels } = useChannels();
   const { currentNodeId } = useDeviceConfig();
@@ -29,14 +39,50 @@ const NodeDetailsBlock: React.FC<NodeDetailsBlockProps> = ({ node, timeFormat =
     return stored === 'true';
   });
 
+  // #3921: editable free-text notes. Draft is kept in local state and only
+  // persisted on Save; it re-syncs whenever the selected node (or its stored
+  // note) changes.
+  const nodeNum = node?.nodeNum;
+  const storedNotes = node?.notes ?? '';
+  const [notesDraft, setNotesDraft] = useState<string>(storedNotes);
+  // Baseline the draft is compared against for the "dirty" check. It tracks the
+  // last-persisted value locally so the Save button settles immediately after a
+  // successful save, even before the polled `nodes` prop catches up.
+  const [notesBaseline, setNotesBaseline] = useState<string>(storedNotes);
+  const [notesSaving, setNotesSaving] = useState(false);
+  const [notesError, setNotesError] = useState<string | null>(null);
+
   useEffect(() => {
     localStorage.setItem('nodeDetailsCollapsed', isCollapsed.toString());
   }, [isCollapsed]);
 
+  // Re-sync draft/baseline whenever the selected node or its stored note changes.
+  useEffect(() => {
+    setNotesDraft(storedNotes);
+    setNotesBaseline(storedNotes);
+    setNotesError(null);
+  }, [nodeNum, storedNotes]);
+
   if (!node) {
     return null;
   }
 
+  const notesDirty = notesDraft !== notesBaseline;
+
+  const handleSaveNotes = async () => {
+    if (!onSaveNotes || notesSaving || !notesDirty) return;
+    setNotesSaving(true);
+    setNotesError(null);
+    try {
+      await onSaveNotes(notesDraft);
+      setNotesBaseline(notesDraft);
+    } catch (err) {
+      setNotesError(err instanceof Error ? err.message : t('node_details.notes_error', 'Failed to save notes'));
+    } finally {
+      setNotesSaving(false);
+    }
+  };
+
   /**
    * Get battery level indicator class based on percentage
    */
@@ -439,6 +485,38 @@ const NodeDetailsBlock: React.FC<NodeDetailsBlockProps> = ({ node, timeFormat =
               </div>
             </div>
           )}
+
+          {/* Notes (#3921) — editable when permitted, otherwise read-only */}
+          {(canEditNotes && onSaveNotes) ? (
+            <div className="node-detail-card node-detail-card-2col node-detail-notes">
+              <div className="node-detail-label">{t('node_details.notes', 'Notes')}</div>
+              <textarea
+                className="node-detail-notes-input"
+                value={notesDraft}
+                maxLength={MAX_NODE_NOTES_LENGTH}
+                rows={3}
+                placeholder={t('node_details.notes_placeholder', 'Add a private note about this node…')}
+                onChange={e => setNotesDraft(e.target.value)}
+                disabled={notesSaving}
+              />
+              {notesError && <span className="node-detail-notes-error">{notesError}</span>}
+              <div className="node-detail-notes-actions">
+                <button
+                  type="button"
+                  className="node-detail-notes-save"
+                  onClick={handleSaveNotes}
+                  disabled={notesSaving || !notesDirty}
+                >
+                  {notesSaving ? t('common.saving', 'Saving…') : t('common.save', 'Save')}
+                </button>
+              </div>
+            </div>
+          ) : storedNotes ? (
+            <div className="node-detail-card node-detail-card-2col node-detail-notes">
+              <div className="node-detail-label">{t('node_details.notes', 'Notes')}</div>
+              <div className="node-detail-value node-detail-notes-readonly">{storedNotes}</div>
+            </div>
+          ) : null}
         </div>
       )}
     </div>
diff --git a/src/db/migrations.test.ts b/src/db/migrations.test.ts
index b8960adf6..3b8b0c81c 100644
--- a/src/db/migrations.test.ts
+++ b/src/db/migrations.test.ts
@@ -2,8 +2,8 @@ import { describe, it, expect } from 'vitest';
 import { registry } from './migrations.js';
 
 describe('migrations registry', () => {
-  it('has all 111 migrations registered', () => {
-    expect(registry.count()).toBe(111);
+  it('has all 112 migrations registered', () => {
+    expect(registry.count()).toBe(112);
   });
 
   // Bumping these counts: when adding a new migration, increment to <N>+1 and
@@ -15,14 +15,14 @@ describe('migrations registry', () => {
     expect(all[0].name).toContain('v37_baseline');
   });
 
-  it('last migration is meshcore_node_position_source', () => {
+  it('last migration is add_notes_to_nodes', () => {
     const all = registry.getAll();
     const last = all[all.length - 1];
-    expect(last.number).toBe(111);
-    expect(last.name).toContain('meshcore_node_position_source');
+    expect(last.number).toBe(112);
+    expect(last.name).toContain('add_notes_to_nodes');
   });
 
-  it('migrations are sequentially numbered from 1 to 111', () => {
+  it('migrations are sequentially numbered from 1 to 112', () => {
     const all = registry.getAll();
     for (let i = 0; i < all.length; i++) {
       expect(all[i].number).toBe(i + 1);
diff --git a/src/db/migrations.ts b/src/db/migrations.ts
index 16da57e2b..eacd1d62f 100644
--- a/src/db/migrations.ts
+++ b/src/db/migrations.ts
@@ -126,6 +126,7 @@ import { migration as meshcoreSavedRegionsMigration, runMigration108Postgres as
 import { migration as clampFutureTracerouteMigration, runMigration109Postgres as runClampFutureTraceroutePostgres, runMigration109Mysql as runClampFutureTracerouteMysql } from '../server/migrations/109_clamp_future_traceroute_timestamps.js';
 import { migration as meshcorePositionHistoryMigration, runMigration110Postgres as runMeshcorePositionHistoryPostgres, runMigration110Mysql as runMeshcorePositionHistoryMysql } from '../server/migrations/110_add_meshcore_position_history.js';
 import { migration as meshcoreNodePositionSourceMigration, runMigration111Postgres as runMeshcoreNodePositionSourcePostgres, runMigration111Mysql as runMeshcoreNodePositionSourceMysql } from '../server/migrations/111_meshcore_node_position_source.js';
+import { migration as nodeNotesMigration, runMigration112Postgres as runNodeNotesPostgres, runMigration112Mysql as runNodeNotesMysql } from '../server/migrations/112_add_notes_to_nodes.js';
 
 // ============================================================================
 // Registry
@@ -1765,3 +1766,19 @@ registry.register({
   postgres: (client) => runMeshcoreNodePositionSourcePostgres(client),
   mysql: (pool) => runMeshcoreNodePositionSourceMysql(pool),
 });
+
+// ---------------------------------------------------------------------------
+// Migration 112: free-text `notes` on `nodes` (#3921)
+// Per-node MeshMonitor-local annotation editable from the node detail view,
+// mirroring the official mobile clients' local notes field. Never synced to
+// the mesh. Nullable; existing rows keep NULL.
+// ---------------------------------------------------------------------------
+
+registry.register({
+  number: 112,
+  name: 'add_notes_to_nodes',
+  settingsKey: 'migration_112_add_notes_to_nodes',
+  sqlite: (db) => nodeNotesMigration.up(db),
+  postgres: (client) => runNodeNotesPostgres(client),
+  mysql: (pool) => runNodeNotesMysql(pool),
+});
diff --git a/src/db/repositories/nodes.test.ts b/src/db/repositories/nodes.test.ts
index 3dfb56a4e..533f00367 100644
--- a/src/db/repositories/nodes.test.ts
+++ b/src/db/repositories/nodes.test.ts
@@ -78,6 +78,7 @@ const POSTGRES_CREATE = `
     "altitudeOverride" REAL,
     "positionOverrideIsPrivate" BOOLEAN DEFAULT FALSE,
     "hideFromMap" BOOLEAN DEFAULT FALSE,
+    "notes" TEXT,
     "isUnmessagable" BOOLEAN DEFAULT FALSE,
     "isLicensed" BOOLEAN DEFAULT FALSE,
     "hasRemoteAdmin" BOOLEAN DEFAULT FALSE,
@@ -149,6 +150,7 @@ const MYSQL_CREATE = `
     altitudeOverride DOUBLE,
     positionOverrideIsPrivate BOOLEAN DEFAULT FALSE,
     hideFromMap BOOLEAN DEFAULT FALSE,
+    notes VARCHAR(2000),
     isUnmessagable BOOLEAN DEFAULT FALSE,
     isLicensed BOOLEAN DEFAULT FALSE,
     hasRemoteAdmin BOOLEAN DEFAULT FALSE,
@@ -746,6 +748,68 @@ function runNodesTests(getBackend: () => TestBackend) {
     expect(Boolean(inB!.hideFromMap)).toBe(false);
   });
 
+  // --- notes (#3921) ---
+
+  it('setNodeNotes - sets and clears the free-text note', async () => {
+    const backend = getBackend();
+    if (!backend.available) {
+      console.log(`⚠ Skipped: ${backend.skipReason}`);
+      return;
+    }
+
+    await repo.upsertNode(makeNode(820), 'default');
+
+    await repo.setNodeNotes(820, 'Solar repeater on the hill', 'default');
+    let node = await repo.getNode(820) as any;
+    expect(node!.notes).toBe('Solar repeater on the hill');
+
+    // Empty string clears the note
+    await repo.setNodeNotes(820, '', 'default');
+    node = await repo.getNode(820) as any;
+    expect(node!.notes).toBe('');
+  });
+
+  it('setNodeNotes - is per-source isolated (#3921)', async () => {
+    const backend = getBackend();
+    if (!backend.available) {
+      console.log(`⚠ Skipped: ${backend.skipReason}`);
+      return;
+    }
+
+    await repo.upsertNode(makeNode(821), 'source-a');
+    await repo.upsertNode(makeNode(821), 'source-b');
+
+    await repo.setNodeNotes(821, 'note for A', 'source-a');
+
+    const inA = await repo.getNode(821, 'source-a') as any;
+    const inB = await repo.getNode(821, 'source-b') as any;
+    expect(inA!.notes).toBe('note for A');
+    // Source B must be untouched (null / no note)
+    expect(inB!.notes ?? null).toBeNull();
+  });
+
+  it('upsertNode - preserves notes across packet-driven updates (#3921)', async () => {
+    const backend = getBackend();
+    if (!backend.available) {
+      console.log(`⚠ Skipped: ${backend.skipReason}`);
+      return;
+    }
+
+    await repo.upsertNode(makeNode(822), 'default');
+    await repo.setNodeNotes(822, 'keep me', 'default');
+
+    // A later mesh packet updates position but carries no notes field —
+    // the user's note must survive the packet-driven upsert.
+    await repo.upsertNode({
+      ...makeNode(822),
+      latitude: 1.0,
+      longitude: 2.0,
+    }, 'default');
+
+    const node = await repo.getNode(822) as any;
+    expect(node!.notes).toBe('keep me');
+  });
+
   // --- setNodeIgnored ---
 
   it('setNodeIgnored - toggles ignored status', async () => {
diff --git a/src/db/repositories/nodes.ts b/src/db/repositories/nodes.ts
index 9d431913d..bf5c9f98c 100644
--- a/src/db/repositories/nodes.ts
+++ b/src/db/repositories/nodes.ts
@@ -412,6 +412,8 @@ export class NodesRepository extends BaseRepository {
           positionOverrideIsPrivate: nodeData.positionOverrideIsPrivate ?? existingNode.positionOverrideIsPrivate,
           // #3549: preserve the user's "Hide from Map" toggle across packet-driven updates
           hideFromMap: nodeData.hideFromMap ?? existingNode.hideFromMap,
+          // #3921: preserve the user's free-text notes across packet-driven updates
+          notes: nodeData.notes ?? existingNode.notes,
           // #3684: User capability flags from NodeInfo (preserve prior value if not present)
           isUnmessagable: nodeData.isUnmessagable ?? existingNode.isUnmessagable,
           isLicensed: nodeData.isLicensed ?? existingNode.isLicensed,
@@ -464,6 +466,7 @@ export class NodesRepository extends BaseRepository {
         altitudeOverride: nodeData.altitudeOverride ?? null,
         positionOverrideIsPrivate: nodeData.positionOverrideIsPrivate ?? false,
         hideFromMap: nodeData.hideFromMap ?? false,
+        notes: nodeData.notes ?? null,
         isUnmessagable: nodeData.isUnmessagable ?? false,
         isLicensed: nodeData.isLicensed ?? false,
         createdAt: now,
@@ -525,6 +528,9 @@ export class NodesRepository extends BaseRepository {
         altitudeOverride: nodeData.altitudeOverride ?? null,
         positionOverrideIsPrivate: nodeData.positionOverrideIsPrivate ?? false,
         hideFromMap: nodeData.hideFromMap ?? false,
+        // Note: notes is intentionally NOT included here (#3921) — like mobile,
+        // it's a user-authored value that must never be clobbered on a
+        // packet-driven upsert conflict. It is only written by setNodeNotes.
         isUnmessagable: nodeData.isUnmessagable ?? false,
         isLicensed: nodeData.isLicensed ?? false,
         updatedAt: now,
@@ -903,6 +909,23 @@ export class NodesRepository extends BaseRepository {
     await this.syncCacheNode(nodeNum, sourceId);
   }
 
+  /**
+   * Set the free-text per-node notes field (issue #3921), scoped to sourceId.
+   * MeshMonitor-local annotation — never synced to the mesh. An empty string
+   * clears the note.
+   */
+  async setNodeNotes(nodeNum: number, notes: string, sourceId: string): Promise<void> {
+    const now = this.now();
+    const { nodes } = this.tables;
+
+    await this.db
+      .update(nodes)
+      .set({ notes, updatedAt: now })
+      .where(and(eq(nodes.nodeNum, nodeNum), eq(nodes.sourceId, sourceId)));
+
+    await this.syncCacheNode(nodeNum, sourceId);
+  }
+
   /**
    * Update node mobility status
    */
diff --git a/src/db/schema/nodes.ts b/src/db/schema/nodes.ts
index bd4521d00..064144852 100644
--- a/src/db/schema/nodes.ts
+++ b/src/db/schema/nodes.ts
@@ -80,6 +80,10 @@ export const nodesSqlite = sqliteTable('nodes', {
   hasRemoteAdmin: integer('hasRemoteAdmin', { mode: 'boolean' }).default(false),
   lastRemoteAdminCheck: integer('lastRemoteAdminCheck'),
   remoteAdminMetadata: text('remoteAdminMetadata'),
+  // Free-text per-node notes — MeshMonitor-local annotation (#3921). Never
+  // synced to the mesh; purely a server-side label like the mobile clients'
+  // local "notes" field.
+  notes: text('notes'),
   // Time sync
   lastTimeSync: integer('lastTimeSync'),
   // Timestamps
@@ -163,6 +167,10 @@ export const nodesPostgres = pgTable('nodes', {
   hasRemoteAdmin: pgBoolean('hasRemoteAdmin').default(false),
   lastRemoteAdminCheck: pgBigint('lastRemoteAdminCheck', { mode: 'number' }),
   remoteAdminMetadata: pgText('remoteAdminMetadata'),
+  // Free-text per-node notes — MeshMonitor-local annotation (#3921). Never
+  // synced to the mesh; purely a server-side label like the mobile clients'
+  // local "notes" field.
+  notes: pgText('notes'),
   // Time sync
   lastTimeSync: pgBigint('lastTimeSync', { mode: 'number' }),
   // Timestamps
@@ -245,6 +253,10 @@ export const nodesMysql = mysqlTable('nodes', {
   hasRemoteAdmin: myBoolean('hasRemoteAdmin').default(false),
   lastRemoteAdminCheck: myBigint('lastRemoteAdminCheck', { mode: 'number' }),
   remoteAdminMetadata: myVarchar('remoteAdminMetadata', { length: 4096 }),
+  // Free-text per-node notes — MeshMonitor-local annotation (#3921). Never
+  // synced to the mesh; purely a server-side label like the mobile clients'
+  // local "notes" field.
+  notes: myVarchar('notes', { length: 2000 }),
   // Time sync
   lastTimeSync: myBigint('lastTimeSync', { mode: 'number' }),
   // Timestamps
diff --git a/src/db/types.ts b/src/db/types.ts
index 3579258e5..985d4f62a 100644
--- a/src/db/types.ts
+++ b/src/db/types.ts
@@ -83,6 +83,8 @@ export interface DbNode {
   positionOverrideIsPrivate?: boolean | null;
   // Map visibility — #3549: suppress this node's marker on maps only
   hideFromMap?: boolean | null;
+  // Free-text per-node notes — #3921: MeshMonitor-local annotation, never synced
+  notes?: string | null;
   // User capability flags from the node's User protobuf — #3684
   isUnmessagable?: boolean | null;
   isLicensed?: boolean | null;
diff --git a/src/server/migrations/112_add_notes_to_nodes.ts b/src/server/migrations/112_add_notes_to_nodes.ts
new file mode 100644
index 000000000..c9599ac53
--- /dev/null
+++ b/src/server/migrations/112_add_notes_to_nodes.ts
@@ -0,0 +1,69 @@
+/**
+ * Migration 112: Add `notes` to `nodes`.
+ *
+ * Free-text per-node "notes" annotation (issue #3921) — a MeshMonitor-local
+ * label editable from the node detail view, mirroring the official Meshtastic
+ * mobile clients' local notes field. Purely server-side state: there is no
+ * protobuf/admin message involved, so it is never synced to or from the mesh.
+ *
+ * Nullable with no default, so existing rows keep NULL (no note) and behave
+ * exactly as before. Idempotent across SQLite / PostgreSQL / MySQL.
+ */
+import type { Database } from 'better-sqlite3';
+import { logger } from '../../utils/logger.js';
+
+const LABEL = 'Migration 112';
+const TABLE = 'nodes';
+const COLUMN = 'notes';
+
+// ============ SQLite ============
+
+export const migration = {
+  up: (db: Database): void => {
+    logger.info(`${LABEL} (SQLite): adding ${TABLE}.${COLUMN}...`);
+    try {
+      // eslint-disable-next-line no-restricted-syntax -- migrations require raw DDL
+      db.exec(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} TEXT`);
+    } catch (e: any) {
+      if (e.message?.includes('duplicate column')) {
+        logger.debug(`${LABEL} (SQLite): ${TABLE}.${COLUMN} already present, skipping`);
+      } else {
+        throw e;
+      }
+    }
+  },
+
+  down: (_db: Database): void => {
+    logger.debug(`${LABEL} down: not implemented (column drops are destructive)`);
+  },
+};
+
+// ============ PostgreSQL ============
+
+export async function runMigration112Postgres(client: any): Promise<void> {
+  logger.info(`${LABEL} (PostgreSQL): adding ${TABLE}.${COLUMN}...`);
+  await client.query(
+    `ALTER TABLE ${TABLE} ADD COLUMN IF NOT EXISTS "${COLUMN}" TEXT`,
+  );
+}
+
+// ============ MySQL ============
+
+export async function runMigration112Mysql(pool: any): Promise<void> {
+  logger.info(`${LABEL} (MySQL): adding ${TABLE}.${COLUMN}...`);
+  const conn = await pool.getConnection();
+  try {
+    const [rows] = await conn.query(
+      `SELECT COLUMN_NAME FROM information_schema.COLUMNS
+       WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = ? AND COLUMN_NAME = ?`,
+      [TABLE, COLUMN],
+    );
+    if (Array.isArray(rows) && rows.length === 0) {
+      await conn.query(`ALTER TABLE ${TABLE} ADD COLUMN ${COLUMN} VARCHAR(2000)`);
+    } else {
+      logger.debug(`${LABEL} (MySQL): ${TABLE}.${COLUMN} already present, skipping`);
+    }
+  } finally {
+    conn.release();
+  }
+}
diff --git a/src/server/server.test.ts b/src/server/server.test.ts
index 1ea575c34..ae2a3d2b0 100644
--- a/src/server/server.test.ts
+++ b/src/server/server.test.ts
@@ -107,6 +107,7 @@ const databaseMock = {
   setNodeFavorite: vi.fn((_nodeNum: number, _isFavorite: boolean, _sourceId: string, _favoriteLocked?: boolean) => undefined),
   setNodeFavoriteLocked: vi.fn((_nodeNum: number, _favoriteLocked: boolean, _sourceId: string) => undefined),
   setNodeHideFromMapAsync: vi.fn(async (_nodeNum: number, _hidden: boolean, _sourceId: string) => undefined),
+  setNodeNotesAsync: vi.fn(async (_nodeNum: number, _notes: string, _sourceId: string) => undefined),
   purgeAllNodes: vi.fn(),
   purgeAllTelemetry: vi.fn(),
   purgeAllMessages: vi.fn(),
@@ -265,6 +266,42 @@ describe('Server API Endpoints', () => {
       }
     });
 
+    // Mirrors apiRouter.post('/nodes/:nodeId/notes') validation contract (#3921)
+    const MAX_NODE_NOTES_LENGTH = 2000;
+    app.post('/api/nodes/:nodeId/notes', async (req, res) => {
+      try {
+        const { nodeId } = req.params;
+        const { notes, sourceId } = req.body;
+
+        if (typeof notes !== 'string') {
+          res.status(400).json({ error: 'notes must be a string' });
+          return;
+        }
+
+        if (notes.length > MAX_NODE_NOTES_LENGTH) {
+          res.status(400).json({ error: 'notes is too long' });
+          return;
+        }
+
+        if (typeof sourceId !== 'string' || sourceId.length === 0) {
+          res.status(400).json({ error: 'sourceId is required' });
+          return;
+        }
+
+        const nodeNumStr = nodeId.replace('!', '');
+        if (!/^[0-9a-fA-F]{8}$/.test(nodeNumStr)) {
+          res.status(400).json({ error: 'Invalid nodeId format' });
+          return;
+        }
+        const nodeNum = parseInt(nodeNumStr, 16);
+
+        await databaseMock.setNodeNotesAsync(nodeNum, notes, sourceId);
+        res.json({ success: true, nodeNum, notes });
+      } catch (error) {
+        res.status(500).json({ error: 'Failed to set node notes' });
+      }
+    });
+
     // Message endpoints
     app.get('/api/messages', (req, res) => {
       try {
@@ -662,6 +699,64 @@ describe('Server API Endpoints', () => {
 
       expect(response.body.error).toBe('Invalid nodeId format');
     });
+
+    it('POST /api/nodes/:nodeId/notes should set the note (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/!00000001/notes')
+        .send({ notes: 'Solar repeater on the hill', sourceId: 'default' })
+        .expect(200);
+
+      expect(response.body.success).toBe(true);
+      expect(response.body.nodeNum).toBe(1);
+      expect(response.body.notes).toBe('Solar repeater on the hill');
+      expect(databaseMock.setNodeNotesAsync).toHaveBeenCalledWith(1, 'Solar repeater on the hill', 'default');
+    });
+
+    it('POST /api/nodes/:nodeId/notes should accept an empty string to clear the note (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/!00000001/notes')
+        .send({ notes: '', sourceId: 'default' })
+        .expect(200);
+
+      expect(response.body.success).toBe(true);
+      expect(databaseMock.setNodeNotesAsync).toHaveBeenCalledWith(1, '', 'default');
+    });
+
+    it('POST /api/nodes/:nodeId/notes should reject non-string notes (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/!00000001/notes')
+        .send({ notes: 42, sourceId: 'default' })
+        .expect(400);
+
+      expect(response.body.error).toBe('notes must be a string');
+    });
+
+    it('POST /api/nodes/:nodeId/notes should reject notes over the length limit (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/!00000001/notes')
+        .send({ notes: 'x'.repeat(2001), sourceId: 'default' })
+        .expect(400);
+
+      expect(response.body.error).toBe('notes is too long');
+    });
+
+    it('POST /api/nodes/:nodeId/notes should reject missing sourceId (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/!00000001/notes')
+        .send({ notes: 'hello' })
+        .expect(400);
+
+      expect(response.body.error).toBe('sourceId is required');
+    });
+
+    it('POST /api/nodes/:nodeId/notes should reject invalid nodeId format (#3921)', async () => {
+      const response = await request(app)
+        .post('/api/nodes/invalid/notes')
+        .send({ notes: 'hello', sourceId: 'default' })
+        .expect(400);
+
+      expect(response.body.error).toBe('Invalid nodeId format');
+    });
   });
 
   describe('Message Endpoints', () => {
diff --git a/src/server/server.ts b/src/server/server.ts
index fe1ced5b0..f73f522d8 100644
--- a/src/server/server.ts
+++ b/src/server/server.ts
@@ -2110,6 +2110,78 @@ apiRouter.post('/nodes/:nodeId/hide-from-map', requirePermission('nodes', 'write
   }
 });
 
+// Set the free-text per-node notes annotation (issue #3921). MeshMonitor-local
+// only — never synced to the mesh. An empty string clears the note.
+const MAX_NODE_NOTES_LENGTH = 2000;
+apiRouter.post('/nodes/:nodeId/notes', requirePermission('nodes', 'write', { sourceIdFrom: 'body' }), async (req, res) => {
+  try {
+    const { nodeId } = req.params;
+    const { notes, sourceId: notesSourceId } = req.body;
+
+    if (typeof notes !== 'string') {
+      const errorResponse: ApiErrorResponse = {
+        error: 'notes must be a string',
+        code: 'INVALID_PARAMETER_TYPE',
+        details: 'Expected string value for notes parameter',
+      };
+      res.status(400).json(errorResponse);
+      return;
+    }
+
+    if (notes.length > MAX_NODE_NOTES_LENGTH) {
+      const errorResponse: ApiErrorResponse = {
+        error: 'notes is too long',
+        code: 'INVALID_PARAMETER',
+        details: `notes must be at most ${MAX_NODE_NOTES_LENGTH} characters`,
+      };
+      res.status(400).json(errorResponse);
+      return;
+    }
+
+    if (typeof notesSourceId !== 'string' || notesSourceId.length === 0) {
+      const errorResponse: ApiErrorResponse = {
+        error: 'sourceId is required',
+        code: 'MISSING_SOURCE_ID',
+        details: 'Request body must include a sourceId string',
+      };
+      res.status(400).json(errorResponse);
+      return;
+    }
+
+    // Convert nodeId (hex string like !a1b2c3d4) to nodeNum (integer)
+    const nodeNumStr = nodeId.replace('!', '');
+
+    // Validate hex string format (must be exactly 8 hex characters)
+    if (!/^[0-9a-fA-F]{8}$/.test(nodeNumStr)) {
+      const errorResponse: ApiErrorResponse = {
+        error: 'Invalid nodeId format',
+        code: 'INVALID_NODE_ID',
+        details: 'nodeId must be in format !XXXXXXXX (8 hex characters)',
+      };
+      res.status(400).json(errorResponse);
+      return;
+    }
+
+    const nodeNum = parseInt(nodeNumStr, 16);
+
+    await databaseService.setNodeNotesAsync(nodeNum, notes, notesSourceId);
+
+    res.json({
+      success: true,
+      nodeNum,
+      notes,
+    });
+  } catch (error) {
+    logger.error('Error setting node notes:', error);
+    const errorResponse: ApiErrorResponse = {
+      error: 'Failed to set node notes',
+      code: 'INTERNAL_ERROR',
+      details: error instanceof Error ? error.message : 'Unknown error occurred',
+    };
+    res.status(500).json(errorResponse);
+  }
+});
+
 // Delete neighbor info for a node
 apiRouter.delete('/nodes/:nodeId/neighbors', requirePermission('nodes', 'write'), async (req, res) => {
   try {
diff --git a/src/server/utils/dbNodeMapper.ts b/src/server/utils/dbNodeMapper.ts
index 243c3e309..ec7dce273 100644
--- a/src/server/utils/dbNodeMapper.ts
+++ b/src/server/utils/dbNodeMapper.ts
@@ -109,6 +109,9 @@ export function mapDbNodeToDeviceInfo(node: any, uptimeSeconds?: number): Device
   if (node.hideFromMap !== null && node.hideFromMap !== undefined) {
     deviceInfo.hideFromMap = Boolean(node.hideFromMap);
   }
+  if (node.notes !== null && node.notes !== undefined) {
+    deviceInfo.notes = node.notes;
+  }
   if (node.hasRemoteAdmin !== null && node.hasRemoteAdmin !== undefined) {
     deviceInfo.hasRemoteAdmin = Boolean(node.hasRemoteAdmin);
     logger.debug(`🔍 Node ${node.nodeNum} hasRemoteAdmin: ${node.hasRemoteAdmin}`);
diff --git a/src/services/api.ts b/src/services/api.ts
index d3dae6517..da70d0f65 100644
--- a/src/services/api.ts
+++ b/src/services/api.ts
@@ -1131,6 +1131,27 @@ class ApiService {
     return response.json();
   }
 
+  /**
+   * Set the free-text per-node notes annotation (#3921). MeshMonitor-local
+   * only — never synced to the mesh. An empty string clears the note.
+   */
+  async setNodeNotes(nodeId: string, notes: string, sourceId?: string | null) {
+    await this.ensureBaseUrl();
+    const response = await fetch(`${this.baseUrl}/api/nodes/${encodeURIComponent(nodeId)}/notes`, {
+      method: 'POST',
+      headers: this.getHeadersWithCsrf(),
+      credentials: 'include',
+      body: JSON.stringify({ notes, ...(sourceId ? { sourceId } : {}) }),
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new Error(error.error || 'Failed to set node notes');
+    }
+
+    return response.json();
+  }
+
   async requestConfig(configType: number, sourceId?: string | null) {
     await this.ensureBaseUrl();
     const response = await fetch(`${this.baseUrl}/api/config/request`, {
diff --git a/src/services/database.ts b/src/services/database.ts
index 8bfdff95f..5c7169715 100644
--- a/src/services/database.ts
+++ b/src/services/database.ts
@@ -105,6 +105,7 @@ export interface DbNode {
   altitudeOverride?: number; // Override altitude
   positionOverrideIsPrivate?: boolean; // Override privacy (false = public, true = private)
   hideFromMap?: boolean; // #3549: suppress this node's marker on maps only
+  notes?: string; // #3921: free-text per-node MeshMonitor-local annotation
   isUnmessagable?: boolean; // #3684: User.is_unmessagable — node won't receive DMs
   isLicensed?: boolean; // #3684: User.is_licensed — amateur-radio licensed operator
   // Remote admin discovery (Migration 055)
@@ -380,6 +381,7 @@ class DatabaseService {
       altitudeOverride: node.altitudeOverride ?? undefined,
       positionOverrideIsPrivate: node.positionOverrideIsPrivate ?? undefined,
       hideFromMap: node.hideFromMap ?? undefined,
+      notes: node.notes ?? undefined,
       hasRemoteAdmin: node.hasRemoteAdmin ?? undefined,
       lastRemoteAdminCheck: node.lastRemoteAdminCheck ?? undefined,
       remoteAdminMetadata: node.remoteAdminMetadata ?? undefined,
@@ -1010,6 +1012,7 @@ class DatabaseService {
             altitudeOverride: node.altitudeOverride ?? undefined,
             positionOverrideIsPrivate: node.positionOverrideIsPrivate ?? undefined,
             hideFromMap: node.hideFromMap ?? undefined,
+            notes: node.notes ?? undefined,
             hasRemoteAdmin: node.hasRemoteAdmin ?? undefined,
             lastRemoteAdminCheck: node.lastRemoteAdminCheck ?? undefined,
             remoteAdminMetadata: node.remoteAdminMetadata ?? undefined,
@@ -1291,6 +1294,7 @@ class DatabaseService {
         altitudeOverride REAL,
         positionOverrideIsPrivate INTEGER DEFAULT 0,
         hideFromMap INTEGER DEFAULT 0,
+        notes TEXT,
         hasRemoteAdmin INTEGER DEFAULT 0,
         lastRemoteAdminCheck INTEGER,
         remoteAdminMetadata TEXT,
@@ -2273,6 +2277,8 @@ class DatabaseService {
           positionOverrideIsPrivate: nodeData.positionOverrideIsPrivate ?? existingNode?.positionOverrideIsPrivate,
           // Map visibility (#3549) - preserve existing toggle across packet upserts
           hideFromMap: nodeData.hideFromMap ?? existingNode?.hideFromMap,
+          // Free-text notes (#3921) - preserve user annotation across packet upserts
+          notes: nodeData.notes ?? existingNode?.notes,
           // Remote admin discovery - preserve existing values
           hasRemoteAdmin: existingNode?.hasRemoteAdmin,
           lastRemoteAdminCheck: existingNode?.lastRemoteAdminCheck,
@@ -7596,6 +7602,31 @@ class DatabaseService {
     logger.debug(`🗺️ Node ${nodeNum}@${sourceId} hideFromMap ${hidden ? 'enabled' : 'disabled'}`);
   }
 
+  /**
+   * Set the free-text per-node notes field (issue #3921). MeshMonitor-local
+   * annotation — never synced to the mesh. An empty string clears the note.
+   * Uses the Drizzle-based repository setter for every backend (no raw SQL).
+   */
+  async setNodeNotesAsync(nodeNum: number, notes: string, sourceId: string): Promise<void> {
+    const now = Date.now();
+
+    if (!this.nodesRepo) {
+      throw new Error('Nodes repository is not initialized');
+    }
+
+    // Persist via the repository (Drizzle — works for SQLite/PostgreSQL/MySQL).
+    await this.nodesRepo.setNodeNotes(nodeNum, notes, sourceId);
+
+    // Keep the in-memory cache consistent for sync readers.
+    const cached = this.nodesCache.get(this.cacheKey(nodeNum, sourceId));
+    if (cached) {
+      cached.notes = notes;
+      cached.updatedAt = now;
+    }
+
+    logger.debug(`📝 Node ${nodeNum}@${sourceId} notes updated (${notes.length} chars)`);
+  }
+
   // Authentication and Authorization
   private ensureAdminUser(): void {
     // Run asynchronously without blocking initialization
diff --git a/src/types/device.ts b/src/types/device.ts
index 4cc8ca2fe..63ac997e0 100644
--- a/src/types/device.ts
+++ b/src/types/device.ts
@@ -42,6 +42,7 @@ export interface DeviceInfo {
   favoriteLocked?: boolean;
   isIgnored?: boolean;
   hideFromMap?: boolean; // #3549: suppress this node's marker on maps only
+  notes?: string; // #3921: free-text per-node MeshMonitor-local annotation
   isUnmessagable?: boolean; // #3684: User.is_unmessagable — node won't receive DMs
   isLicensed?: boolean; // #3684: User.is_licensed — amateur-radio licensed operator
   keyIsLowEntropy?: boolean;