feat: add optional help text to field definitions (#34)

Add a helpText property to field definitions that displays an info icon
next to field labels. Clicking the icon opens a popover with guidance
text that supports **bold** and [links](url) via inline markdown.

Surfaces in: person detail, team detail, manager dashboard column
headers, field definition settings, and edit modals.

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: accorvin

docs/DATA-FORMATS.md

@@ -471,6 +471,7 @@ Stores custom field definitions for person-level and team-level fields. Created
       "required": false,
       "visible": true,
       "primaryDisplay": true,
+      "helpText": "The primary area this person is currently focused on.",
       "allowedValues": null,
       "optionsRef": null,
       "deleted": false,
@@ -488,6 +489,7 @@ Stores custom field definitions for person-level and team-level fields. Created
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": null,
       "optionsRef": null,
       "deleted": false,
@@ -507,6 +509,7 @@ Stores custom field definitions for person-level and team-level fields. Created
 - `deleted` supports soft-delete — deleted fields are hidden from the UI but values are preserved.
 - `allowedValues` is an array of strings for `constrained` fields (the set of selectable options), or `null` for other field types. Maximum 100 items, each up to 200 characters. When `optionsRef` is set, `allowedValues` is `null` in storage and resolved at runtime from the referenced field option set.
 - `optionsRef` is an optional string referencing a named field option set (e.g., `"components"`). When set, the field's allowed values are sourced dynamically from `data/team-data/field-options/<optionsRef>.json` instead of from the static `allowedValues` array. The `GET /structure/field-definitions` API response resolves `optionsRef` fields by injecting the option values into `allowedValues` (with a `_resolvedFromOptions: true` flag). Defaults to `null`.
+- `helpText` is an optional string (or `null`) providing guidance displayed to users via an info icon. Supports a minimal inline-markdown subset: `**bold**` and `[text](https://...)` links. Defaults to `null`.
 - At most one person field can have `primaryDisplay: true`.
 
 ## Field Options — `data/team-data/field-options/<name>.json`

fixtures/team-data/field-definitions.json

@@ -8,6 +8,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": true,
+      "helpText": "The primary area this person is currently focused on. This could be a **project name**, a **technical domain**, or a [team objective](https://example.com). Update this when focus shifts significantly.",
       "allowedValues": null,
       "deleted": false,
       "order": 0,
@@ -22,6 +23,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": null,
       "optionsRef": "component",
       "deleted": false,
@@ -37,6 +39,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": ["Python", "Go", "Rust", "JavaScript", "Java", "ML/AI"],
       "deleted": false,
       "order": 2,
@@ -51,6 +54,7 @@
       "required": true,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": ["Backend", "Frontend", "Full Stack", "DevOps", "ML Engineer", "QE"],
       "deleted": false,
       "order": 3,
@@ -67,6 +71,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": null,
       "deleted": false,
       "order": 0,
@@ -81,6 +86,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": ["Active", "Forming", "Sunset"],
       "deleted": false,
       "order": 1,
@@ -95,6 +101,7 @@
       "required": false,
       "visible": true,
       "primaryDisplay": false,
+      "helpText": null,
       "allowedValues": null,
       "optionsRef": "component",
       "deleted": false,

modules/team-tracker/client/components/FieldDefinitionManager.vue

@@ -2,6 +2,7 @@
 import { ref, computed, onMounted, watch } from 'vue'
 import { apiRequest } from '@shared/client/services/api.js'
 import { useFieldDefinitions } from '@shared/client/composables/useFieldDefinitions'
+import FieldHelpText from './FieldHelpText.vue'
 
 const { definitions, loading, demoToast, fetchDefinitions, createField, updateField, deleteField } = useFieldDefinitions()
 
@@ -12,6 +13,7 @@ const newFieldType = ref('free-text')
 const newFieldMultiValue = ref(false)
 const newFieldOptions = ref([])
 const newOptionInput = ref('')
+const newFieldHelpText = ref('')
 const newFieldOptionsSource = ref('inline')
 const newFieldOptionsRef = ref('')
 const availableOptionSets = ref([])
@@ -55,6 +57,7 @@ function openCreateModal() {
   newFieldLabel.value = ''
   newFieldType.value = 'free-text'
   newFieldMultiValue.value = false
+  newFieldHelpText.value = ''
   newFieldOptions.value = []
   newOptionInput.value = ''
   newFieldOptionsSource.value = 'inline'
@@ -93,6 +96,9 @@ async function handleCreate() {
       label: newFieldLabel.value.trim(),
       type: newFieldType.value
     }
+    if (newFieldHelpText.value.trim()) {
+      body.helpText = newFieldHelpText.value.trim()
+    }
     if (newFieldType.value === 'constrained') {
       body.multiValue = newFieldMultiValue.value
       if (newFieldOptionsSource.value === 'shared') {
@@ -109,11 +115,13 @@ async function handleCreate() {
 }
 
 const editType = ref('')
+const editHelpText = ref('')
 
 function startEdit(field) {
   editingFieldId.value = field.id
   editLabel.value = field.label
   editType.value = field.type
+  editHelpText.value = field.helpText || ''
 }
 
 async function saveEdit(fieldId) {
@@ -125,6 +133,10 @@ async function saveEdit(fieldId) {
     if (originalField && editType.value !== originalField.type) {
       updates.type = editType.value
     }
+    const newHelp = editHelpText.value.trim() || null
+    if (newHelp !== (originalField?.helpText || null)) {
+      updates.helpText = newHelp
+    }
     await updateField(activeTab.value, fieldId, updates)
     editingFieldId.value = null
   } catch (e) {
@@ -228,17 +240,29 @@ async function toggleVisibility(field) {
         <tbody class="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
           <tr v-for="field in activeFields" :key="field.id" :class="['hover:bg-gray-50 dark:hover:bg-gray-700/50', editingFieldId === field.id ? 'bg-blue-50 dark:bg-blue-900/20' : '']">
             <td class="px-4 py-3 text-sm whitespace-nowrap">
-              <div v-if="editingFieldId === field.id" class="flex items-center gap-2">
-                <input
-                  v-model="editLabel"
-                  class="block flex-1 rounded border-gray-300 dark:border-gray-600 shadow-sm text-sm bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100"
-                  @keyup.enter="saveEdit(field.id)"
+              <div v-if="editingFieldId === field.id" class="space-y-2">
+                <div class="flex items-center gap-2">
+                  <input
+                    v-model="editLabel"
+                    class="block flex-1 rounded border-gray-300 dark:border-gray-600 shadow-sm text-sm bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100"
+                    @keyup.enter="saveEdit(field.id)"
+                    @keyup.escape="editingFieldId = null"
+                  >
+                  <button class="px-2.5 py-1 text-xs font-medium text-white bg-primary-600 rounded hover:bg-primary-700 transition-colors" @click="saveEdit(field.id)">Save</button>
+                  <button class="px-2.5 py-1 text-xs font-medium text-gray-600 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 rounded hover:bg-gray-200 dark:hover:bg-gray-600 transition-colors" @click="editingFieldId = null">Cancel</button>
+                </div>
+                <textarea
+                  v-model="editHelpText"
+                  rows="2"
+                  class="block w-full rounded border-gray-300 dark:border-gray-600 shadow-sm text-xs bg-white dark:bg-gray-700 text-gray-900 dark:text-gray-100"
+                  placeholder="Help text (optional) — supports **bold** and [links](https://...)"
                   @keyup.escape="editingFieldId = null"
-                >
-                <button class="px-2.5 py-1 text-xs font-medium text-white bg-primary-600 rounded hover:bg-primary-700 transition-colors" @click="saveEdit(field.id)">Save</button>
-                <button class="px-2.5 py-1 text-xs font-medium text-gray-600 dark:text-gray-300 bg-gray-100 dark:bg-gray-700 rounded hover:bg-gray-200 dark:hover:bg-gray-600 transition-colors" @click="editingFieldId = null">Cancel</button>
+                ></textarea>
+              </div>
+              <div v-else>
+                <span class="font-medium text-gray-900 dark:text-gray-100">{{ field.label }}</span>
+                <FieldHelpText :text="field.helpText" size="xs" />
               </div>
-              <span v-else class="font-medium text-gray-900 dark:text-gray-100">{{ field.label }}</span>
             </td>
             <td class="px-4 py-3 text-sm whitespace-nowrap text-gray-600 dark:text-gray-400">
               <template v-if="editingFieldId === field.id">
@@ -310,6 +334,15 @@ async function toggleVisibility(field) {
               <option v-for="t in fieldTypes" :key="t.value" :value="t.value">{{ t.label }}</option>
             </select>
           </div>
+          <div>
+            <label class="block text-sm font-medium text-gray-700 dark:text-gray-300 mb-1">Help Text <span class="text-xs text-gray-400 font-normal">(optional)</span></label>
+            <textarea
+              v-model="newFieldHelpText"
+              rows="2"
+              class="block w-full rounded border-gray-300 shadow-sm text-sm focus:ring-primary-500 focus:border-primary-500"
+              placeholder="Guidance shown to users when filling in this field. Supports **bold** and [links](https://...)."
+            ></textarea>
+          </div>
           <!-- Allowed values for constrained type -->
           <div v-if="newFieldType === 'constrained'" class="space-y-3">
             <div>

modules/team-tracker/client/components/FieldHelpText.vue

@@ -0,0 +1,97 @@
+<script setup>
+import { ref, computed, watch, nextTick, onMounted, onUnmounted } from 'vue'
+
+const props = defineProps({
+  text: { type: String, default: null },
+  size: { type: String, default: 'sm' }
+})
+
+const showPopover = ref(false)
+const triggerEl = ref(null)
+const popoverEl = ref(null)
+const popoverPos = ref({ top: 0, left: 0 })
+
+const sizeClasses = computed(() =>
+  props.size === 'xs' ? 'h-3 w-3' : 'h-3.5 w-3.5'
+)
+
+/**
+ * Render a minimal inline-markdown subset to HTML:
+ *   **bold** -> <strong>
+ *   [text](url) -> <a>
+ * Escapes HTML entities first to prevent XSS.
+ */
+const renderedHtml = computed(() => {
+  if (!props.text) return ''
+  let s = props.text
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+
+  // **bold**
+  s = s.replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+  // [text](url) — only allow http(s) URLs
+  s = s.replace(/\[([^\]]+)\]\((https?:\/\/[^)]+)\)/g, '<a href="$2" target="_blank" rel="noopener noreferrer" class="text-primary-600 dark:text-primary-400 underline">$1</a>')
+  // Newlines to <br>
+  s = s.replace(/\n/g, '<br>')
+  return s
+})
+
+function updatePosition() {
+  if (!triggerEl.value) return
+  const rect = triggerEl.value.getBoundingClientRect()
+  const top = rect.bottom + 6
+  const left = Math.max(8, rect.left - 100)
+  const maxLeft = window.innerWidth - 300
+  popoverPos.value = { top, left: Math.min(left, maxLeft) }
+}
+
+function toggle(e) {
+  e.stopPropagation()
+  showPopover.value = !showPopover.value
+}
+
+watch(showPopover, (val) => {
+  if (val) nextTick(updatePosition)
+})
+
+function onClickOutside(e) {
+  if (
+    showPopover.value &&
+    triggerEl.value && !triggerEl.value.contains(e.target) &&
+    popoverEl.value && !popoverEl.value.contains(e.target)
+  ) {
+    showPopover.value = false
+  }
+}
+
+onMounted(() => document.addEventListener('click', onClickOutside, true))
+onUnmounted(() => document.removeEventListener('click', onClickOutside, true))
+</script>
+
+<template>
+  <span v-if="text" class="relative inline-flex items-center">
+    <button
+      ref="triggerEl"
+      type="button"
+      class="text-gray-400 dark:text-gray-500 hover:text-gray-600 dark:hover:text-gray-300 transition-colors focus:outline-none"
+      :title="showPopover ? '' : 'Click for more info'"
+      @click="toggle"
+    >
+      <svg :class="sizeClasses" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M13 16h-1v-4h-1m1-4h.01M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+      </svg>
+    </button>
+    <Teleport to="body">
+      <div
+        v-if="showPopover"
+        ref="popoverEl"
+        class="fixed z-[100] max-w-xs w-72 p-3 text-sm text-gray-700 dark:text-gray-200 bg-white dark:bg-gray-800 border border-gray-200 dark:border-gray-600 rounded-lg shadow-lg"
+        :style="{ top: popoverPos.top + 'px', left: popoverPos.left + 'px' }"
+      >
+        <div v-html="renderedHtml" class="leading-relaxed [&_strong]:font-semibold"></div>
+      </div>
+    </Teleport>
+  </span>
+</template>

modules/team-tracker/client/components/PersonFieldEditor.vue

@@ -3,6 +3,7 @@ import { ref, computed, watch, inject, onUnmounted } from 'vue'
 import { useFieldDefinitions } from '@shared/client/composables/useFieldDefinitions'
 import PersonAutocomplete from './PersonAutocomplete.vue'
 import ConstrainedAutocomplete from './ConstrainedAutocomplete.vue'
+import FieldHelpText from './FieldHelpText.vue'
 
 const props = defineProps({
   uid: { type: String, required: true },
@@ -152,8 +153,9 @@ function isPersonRefType(field) {
         <div v-for="field in visibleFields" :key="field.id" :class="['group', editingFieldId === field.id ? 'bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-md px-2 py-1.5' : '']">
           <!-- Edit mode -->
           <template v-if="editingFieldId === field.id">
-            <div class="text-xs text-gray-500 dark:text-gray-400 mb-1">
-              {{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span>
+            <div class="text-xs text-gray-500 dark:text-gray-400 mb-1 flex items-center gap-1">
+              <span>{{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span></span>
+              <FieldHelpText :text="field.helpText" size="xs" />
             </div>
             <!-- Constrained field (single or multi-value): autocomplete -->
             <ConstrainedAutocomplete
@@ -196,7 +198,10 @@ function isPersonRefType(field) {
                 <path stroke-linecap="round" stroke-linejoin="round" d="M7 7h.01M7 3h5c.512 0 1.024.195 1.414.586l7 7a2 2 0 010 2.828l-7 7a2 2 0 01-2.828 0l-7-7A1.994 1.994 0 013 12V7a4 4 0 014-4z" />
               </svg>
               <div class="flex-1 min-w-0">
-                <div class="text-[11px] text-gray-400 dark:text-gray-500 leading-tight">{{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span></div>
+                <div class="text-[11px] text-gray-400 dark:text-gray-500 leading-tight flex items-center gap-0.5">
+                  <span>{{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span></span>
+                  <FieldHelpText :text="field.helpText" size="xs" />
+                </div>
                 <!-- Multi-value display -->
                 <div v-if="isMultiValue(field)" class="flex flex-wrap gap-1 mt-0.5">
                   <span

modules/team-tracker/client/components/TeamFieldEditor.vue

@@ -3,6 +3,7 @@ import { ref, computed, watch, onUnmounted } from 'vue'
 import { useTeams } from '@shared/client/composables/useTeams'
 import PersonAutocomplete from './PersonAutocomplete.vue'
 import ConstrainedAutocomplete from './ConstrainedAutocomplete.vue'
+import FieldHelpText from './FieldHelpText.vue'
 
 const props = defineProps({
   teamId: { type: String, required: true },
@@ -170,8 +171,9 @@ function isPersonRefType(field) {
         editingFieldId === field.id ? 'bg-blue-50 dark:bg-blue-900/20 border border-blue-200 dark:border-blue-800 rounded-md px-2 py-1' : ''
       ]"
     >
-      <span :class="inline ? 'text-sm text-gray-400 dark:text-gray-500 shrink-0' : 'text-sm text-gray-600 dark:text-gray-400 w-32 shrink-0'">
-        {{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span>:
+      <span :class="[inline ? 'text-sm text-gray-400 dark:text-gray-500 shrink-0' : 'text-sm text-gray-600 dark:text-gray-400 w-32 shrink-0', 'inline-flex items-center gap-1']">
+        <span>{{ field.label }}<span v-if="field.required" class="text-red-500 ml-0.5">*</span>:</span>
+        <FieldHelpText :text="field.helpText" size="xs" />
       </span>
       <template v-if="editingFieldId === field.id">
         <!-- Constrained field (single or multi-value): autocomplete -->

modules/team-tracker/client/views/ManagerDashboardView.vue

@@ -156,7 +156,7 @@
                   :data-tour="idx === 0 ? 'field-cell' : undefined"
                   class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider"
                   :class="bulkEditing ? 'text-primary-700 dark:text-primary-300 bg-blue-50 dark:bg-blue-900/30' : 'text-gray-500 dark:text-gray-400'"
-                >{{ field.label }}</th>
+                ><span class="inline-flex items-center gap-1">{{ field.label }}<FieldHelpText :text="field.helpText" size="xs" /></span></th>
               </tr>
             </thead>
             <tbody class="bg-white dark:bg-gray-800 divide-y divide-gray-200 dark:divide-gray-700">
@@ -373,7 +373,7 @@
                     :key="field.id"
                     class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider"
                     :class="teamBulkEditing ? 'text-primary-700 dark:text-primary-300 bg-blue-50 dark:bg-blue-900/30' : 'text-gray-500 dark:text-gray-400'"
-                  >{{ field.label }}</th>
+                  ><span class="inline-flex items-center gap-1">{{ field.label }}<FieldHelpText :text="field.helpText" size="xs" /></span></th>
                   <th class="px-4 py-3 text-left text-xs font-medium uppercase tracking-wider" :class="teamBulkEditing ? 'text-primary-700 dark:text-primary-300 bg-blue-50 dark:bg-blue-900/30' : 'text-gray-500 dark:text-gray-400'">Boards</th>
                 </tr>
               </thead>
@@ -513,6 +513,7 @@ import { isFieldEmpty as _isFieldEmpty, buildExceptionSet, hasException as _hasE
 import ConstrainedAutocomplete from '../components/ConstrainedAutocomplete.vue'
 import FieldDisplayCell from '../components/FieldDisplayCell.vue'
 import FieldEditCell from '../components/FieldEditCell.vue'
+import FieldHelpText from '../components/FieldHelpText.vue'
 import TeamBoardsDrawer from '../components/TeamBoardsDrawer.vue'
 import { useManagerTutorial } from '../composables/useManagerTutorial'
 

shared/server/field-store.js

@@ -164,6 +164,7 @@ async function createFieldDefinition(storage, scope, definition, actorEmail) {
       required: definition.required || false,
       visible: definition.visible !== false,
       primaryDisplay: definition.primaryDisplay || false,
+      helpText: definition.helpText || null,
       allowedValues: definition.allowedValues || null,
       optionsRef: definition.optionsRef || null,
       deleted: false,
@@ -218,7 +219,7 @@ async function updateFieldDefinition(storage, scope, fieldId, updates, actorEmai
 
     const changes = {};
     for (const [k, v] of Object.entries(updates)) {
-      if (['label', 'type', 'required', 'visible', 'primaryDisplay', 'allowedValues', 'multiValue', 'optionsRef'].includes(k)) {
+      if (['label', 'type', 'required', 'visible', 'primaryDisplay', 'helpText', 'allowedValues', 'multiValue', 'optionsRef'].includes(k)) {
         changes[k] = { old: field[k], new: v };
         field[k] = v;
       }