@@ -31,7 +31,7 @@ import type { Dashboard } from '@objectstack/spec/ui';
 export const PipelineDashboard: Dashboard = {
   name: 'pipeline_dashboard',
   label: 'Pipeline Dashboard',
-  description: 'Aggregate view of the sales pipeline with period-over-period comparisons.',
+  description: 'The sales pipeline at a glance, compared with earlier periods.',
   columns: 12,
   widgets: [
     // --- Row 1: KPI tiles -------------------------------------------------
@@ -45,7 +45,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'total_pipeline',
       type: 'metric',
       title: 'Total Pipeline',
-      description: 'Sum of opportunity amounts across open stages.',
+      description: 'Total value of all open opportunities.',
       filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
       dataset: 'opportunity_metrics',
       values: ['total_amount'],
@@ -55,7 +55,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'won_this_quarter',
       type: 'metric',
       title: 'Won This Quarter',
-      description: 'Revenue closed-won in the current quarter, compared to the previous quarter.',
+      description: 'Value of deals won this quarter, compared with last quarter.',
       filter: {
         stage: 'closed_won',
         close_date: {
@@ -72,7 +72,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'avg_deal_size_yoy',
       type: 'metric',
       title: 'Avg Deal Size (YoY)',
-      description: 'Average won-deal value this year vs the same window last year.',
+      description: 'Average value of deals won this year, compared with the same period last year.',
       filter: {
         stage: 'closed_won',
         close_date: {
@@ -91,7 +91,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'pipeline_trend_90d',
       type: 'line',
       title: 'Pipeline Trend (12 months)',
-      description: 'Opportunity count bucketed by close-month for the last year, with a sliding overlay of the prior year for compareTo.',
+      description: 'Opportunities by expected close month over the last 12 months, compared with the year before.',
       filter: {
         close_date: { $gte: '{1_years_ago}', $lte: '{today}' },
       },
@@ -107,7 +107,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'opportunities_by_stage',
       type: 'bar',
       title: 'Opportunities by Stage',
-      description: 'Count grouped by stage with previous-quarter overlay (compareTo).',
+      description: 'Opportunities expected to close this quarter, by stage, compared with last quarter.',
       filter: {
         close_date: {
           $gte: '{current_quarter_start}',
@@ -126,7 +126,7 @@ export const PipelineDashboard: Dashboard = {
       id: 'pipeline_by_industry',
       type: 'pie',
       title: 'Open Pipeline by Stage',
-      description: 'Open-pipeline revenue split by pipeline stage. Pie/donut/funnel ignore `compareTo`.',
+      description: 'Value of open opportunities, split by stage.',
       filter: { stage: { $nin: ['closed_won', 'closed_lost'] } },
       dataset: 'opportunity_metrics',
       dimensions: ['stage'],
 
@@ -59,28 +59,28 @@ const opportunities = defineSeed(Opportunity, {
 const leads = defineSeed(Lead, {
   mode: 'upsert',
   externalId: 'email',
+  // No `assigned_to` on these rows. It is a user field, and no user exists
+  // when the seed runs: people come from sign-up, and the dev admin is
+  // created after the seed. A rep picks up a lead from the record page.
   records: [
     // New / uncontacted
     {
       name: 'Marie Curie', email: 'marie@radium.example', company: 'Radium Labs',
       title: 'Director of Research', phone: '+1-555-0101',
       status: 'new', source: 'web', lead_score: 0,
-      assigned_to: 'ada@acme.example',
       account: 'Acme Corp',
     },
     // In qualification — high-value referral lead
     {
       name: 'Alan Turing', email: 'alan@bletchley.example', company: 'Bletchley Systems',
       title: 'VP Engineering', phone: '+44-20-555-0202',
       status: 'qualifying', source: 'referral', lead_score: 75,
-      assigned_to: 'linus@globex.example',
     },
     // Qualified — ready for conversion
     {
       name: 'Rosalind Franklin', email: 'ros@helix.example', company: 'Helix Analytics',
       title: 'CTO', phone: '+1-555-0303',
       status: 'qualified', source: 'event', lead_score: 85,
-      assigned_to: 'grace@initech.example',
       account: 'Initech',
     },
     // Disqualified — poor fit
@@ -95,7 +95,6 @@ const leads = defineSeed(Lead, {
       name: 'Nikola Tesla', email: 'nikola@wardenclyffe.example', company: 'Wardenclyffe Corp',
       title: 'Chief Inventor', phone: '+1-555-0505',
       status: 'converted', source: 'partner', lead_score: 90,
-      assigned_to: 'ada@acme.example',
       converted_opportunity: 'Acme — Q3 Platform Renewal',
     },
   ],
@@ -106,7 +105,7 @@ const activities = defineSeed(Activity, {
   externalId: 'subject',
   records: [
     {
-      subject: 'Discovery Call — Bletchley Systems',
+      subject: 'Discovery Call — Acme Platform Renewal',
       type: 'call', status: 'completed',
       due_date: cel`daysAgo(3)`,
       contact: 'ada@acme.example',
 
@@ -13,6 +13,8 @@ export const Account = ObjectSchema.create({
   pluralLabel: 'Accounts',
   icon: 'building',
   description: 'A company that the org sells to or supports.',
+  // What the record page shows at a glance, under the title.
+  highlightFields: ['industry', 'annual_revenue', 'website'],
 
   fields: {
     name: Field.text({
 
@@ -14,6 +14,9 @@ export const Activity = ObjectSchema.create({
   pluralLabel: 'Activities',
   icon: 'calendar-check',
   description: 'A logged interaction (call, email, meeting, or task) related to a CRM record.',
+  // What the record page shows at a glance, under the title. The stage is
+  // not here: the record page already draws it as the stage path.
+  highlightFields: ['type', 'due_date', 'contact', 'account'],
 
   fields: {
     subject: Field.text({
 
@@ -14,6 +14,13 @@ export const Contact = ObjectSchema.create({
   pluralLabel: 'Contacts',
   icon: 'user',
   description: 'A person associated with an account.',
+  // The record's title is the person's full name. Without this pointer the
+  // title is derived from the first name-ish field, which reads "Ada" on the
+  // record page, in lookups and in pickers. A text formula is a display title:
+  // search reaches the person through `last_name` and `email` instead.
+  nameField: 'full_name',
+  // What the record page shows at a glance, under the title.
+  highlightFields: ['account', 'email'],
 
   fields: {
     first_name: Field.text({
@@ -28,6 +35,8 @@ export const Contact = ObjectSchema.create({
     }),
     full_name: Field.formula({
       label: 'Full Name',
+      // `text`, so the formula can back the record title (`nameField` above).
+      returnType: 'text',
       expression: cel`(record.first_name == null ? '' : record.first_name + ' ') + record.last_name`,
     }),
     email: Field.email({
 
@@ -14,6 +14,9 @@ export const Lead = ObjectSchema.create({
   pluralLabel: 'Leads',
   icon: 'funnel',
   description: 'An inbound prospect not yet qualified as an opportunity.',
+  // What the record page shows at a glance, under the title. The stage is
+  // not here: the record page already draws it as the stage path.
+  highlightFields: ['company', 'source', 'lead_score', 'assigned_to'],
 
   fields: {
     name: Field.text({
@@ -73,9 +76,10 @@ export const Lead = ObjectSchema.create({
       max: 100,
       defaultValue: 0,
     }),
-    assigned_to: Field.text({
+    // The sales rep who works the lead: a person, so the list and the record
+    // page show a name, never a raw email address.
+    assigned_to: Field.user({
       label: 'Assigned To',
-      maxLength: 200,
     }),
     account: Field.lookup('crm_account', {
       label: 'Account',
@@ -89,6 +93,8 @@ export const Lead = ObjectSchema.create({
     /** CEL formula: is this lead in a terminal converted/disqualified state? */
     is_closed: Field.formula({
       label: 'Is Closed',
+      // `boolean`, so the record page draws a yes/no face, not the raw word.
+      returnType: 'boolean',
       expression: cel`record.status == "converted" || record.status == "disqualified"`,
     }),
   },
 
@@ -14,6 +14,9 @@ export const Opportunity = ObjectSchema.create({
   pluralLabel: 'Opportunities',
   icon: 'trending-up',
   description: 'A potential sale tied to an account.',
+  // What the record page shows at a glance, under the title. The stage is
+  // not here: the record page already draws it as the stage path.
+  highlightFields: ['account', 'amount', 'close_date', 'probability'],
 
   fields: {
     name: Field.text({