Implementation notes are shown to users as help text — field and dashboard-widget descriptions cite hook files, card numbers, DESIGN.md sections and PRs

src/dashboards/finance.dashboard.ts

@@ -110,7 +110,7 @@ export const FinanceDashboard: Dashboard = {
     {
       id: 'overdue_amount',
       title: 'Overdue Amount',
-      description: 'Scheduled value of instalments the daily job has stamped overdue',
+      description: 'Scheduled value of instalments the daily check has marked overdue',
       type: 'metric',
       dataset: 'payment_metrics',
       values: ['overdue_amount'],

src/dashboards/legal.dashboard.ts

@@ -177,7 +177,7 @@ export const LegalDashboard: Dashboard = {
        */
       id: 'review_ageing',
       title: 'In Review Over 30 Days',
-      description: 'Older than every seeded type SLA (longest is 10 days) — a fixed threshold, not the per-type breach',
+      description: 'A fixed 30-day threshold, not each contract type\'s own review SLA.',
       type: 'metric',
       dataset: 'contract_metrics',
       values: ['contract_count'],
@@ -188,7 +188,7 @@ export const LegalDashboard: Dashboard = {
     {
       id: 'negotiation_stalled',
       title: 'Waiting on Counterparty',
-      description: 'The ball is in their court — the queue F4 chases',
+      description: 'The ball is in their court — the queue to chase',
       type: 'metric',
       dataset: 'contract_metrics',
       values: ['contract_count'],
@@ -230,7 +230,7 @@ export const LegalDashboard: Dashboard = {
        */
       id: 'approval_throughput',
       title: 'Approved This Month',
-      description: 'Contracts reaching approved this month, against the previous period. Not an average duration — see the PR.',
+      description: 'Contracts approved this month, compared with last month. A count, not an average turnaround time.',
       type: 'metric',
       dataset: 'contract_metrics',
       values: ['contract_count'],

src/flows/executed-upload.flow.ts

@@ -128,7 +128,9 @@ const PARTY_BAD = '!has(vars.partyRecord) || vars.partyRecord == null || !has(va
 export const ExecutedUploadFlow: Flow = {
   name: 'executed_upload',
   label: 'Backfill An Executed Contract',
-  description: 'Record a contract that was signed outside this system: create it directly in active with is_backfilled set, and file the executed copy as its final signed version.',
+  // Creates the contract in `active` with `is_backfilled` set and files the
+  // executed copy as a `final_signed` version.
+  description: 'Record a contract that was signed outside this system: create it directly as active, marked as backfilled, and file the executed copy as its final signed version.',
   type: 'autolaunched',
   status: 'active',
   // See the header: the ONE thing elevation buys is the right to insert a

src/flows/legal-review-sla.flow.ts

@@ -52,7 +52,10 @@ import { holdersPrelude, rowBody, sweepFlow } from './_daily-sweep.js';
 export const LegalReviewSlaFlow: Flow = sweepFlow({
   name: 'legal_review_sla',
   label: 'Legal Review Running Long',
-  description: 'Daily: remind the legal owner of a contract that has been in review over 30 days, and copy the head of legal once it passes 60. A fixed threshold, stated in the message — decision #31 ruled 2B, the per-type SLA needs platform date support (objectstack#16737).',
+  // A fixed threshold, stated in the message — decision #31 ruled 2B: the
+  // per-type SLA needs platform date support (objectstack#16737). See the
+  // header above.
+  description: 'Daily: remind the legal owner of a contract that has been in review over 30 days, and copy the head of legal once it passes 60. A fixed threshold, not each contract type\'s own review SLA.',
   prelude: holdersPrelude('clm_legal_head', 'legalHeads'),
   stages: [
     {

src/flows/obligation-due.flow.ts

@@ -59,7 +59,7 @@ const flagOverdue: FlowNode = {
 export const ObligationDueFlow: Flow = sweepFlow({
   name: 'obligation_due',
   label: 'Obligations Due And Overdue',
-  description: 'Daily: remind an obligation owner seven days out and on the due date, and move an unfinished obligation past its due date into overdue (which moves the contract roll-up with it).',
+  description: 'Daily: remind an obligation owner seven days out and on the due date, and move an unfinished obligation past its due date into overdue (which also updates the contract\'s overdue count).',
   stages: [
     {
       id: 'week',

src/flows/renewal-notice.flow.ts

@@ -228,7 +228,8 @@ export const RenewalNoticeFlow: Flow = sweepFlow({
 export const RenewalStartFlow: Flow = {
   name: 'renewal_start',
   label: 'Start Renewal',
-  description: 'Create a renewal draft of this contract, pre-filled from it and linked back through renewed_from.',
+  // "Linked back" = `renewed_from` on the new draft.
+  description: 'Create a renewal draft of this contract, pre-filled from it and linked back to it.',
   type: 'autolaunched',
   status: 'active',
   runAs: 'user',

src/flows/signature-record.flow.ts

@@ -205,7 +205,8 @@ const when = (...clauses: string[]) => expression(clauses.join(' && '));
 export const SignatureRecordFlow: Flow = {
   name: 'signature_record',
   label: 'Signature Completed — Execution Check',
-  description: 'When a signing round completes, compare the formalities done against the ones the contract requires: stamp executed_at and file the final signed version when covered, or tell the legal owner which formality is missing.',
+  // "Record the execution date" = stamp `executed_at`.
+  description: 'When a signing round completes, compare the formalities done against the ones the contract requires: record the execution date and file the final signed version when covered, or tell the legal owner which formality is missing.',
   type: 'record_change',
   status: 'active',
   // See the header: the stamp lands on a readonly, field-secured column, and
@@ -440,7 +441,7 @@ export const SignatureRecordOnCreateFlow: Flow = {
   ...SignatureRecordFlow,
   name: 'signature_record_on_create',
   label: 'Signature Completed — Execution Check (on create)',
-  description: 'Execution-formalities check for a signing round created already completed (insert-time twin of signature_record).',
+  description: 'The same execution check, for a signing round that is recorded as already completed.',
   nodes: SignatureRecordFlow.nodes.map((node) =>
     node.id === 'start'
       ? { ...node, config: { ...node.config, triggerType: 'record-after-create' } }

src/objects/clause.object.ts

@@ -102,7 +102,7 @@ export const Clause = ObjectSchema.create({
       label: 'Deviation Needs Head of Legal',
       group: 'scope',
       defaultValue: false,
-      description: 'An accepted deviation from this clause routes the contract through the head-of-legal rung (F6).',
+      description: 'An accepted deviation from this clause routes the contract through the head-of-legal rung.',
     }),
     is_active: Field.boolean({
       label: 'Active',

src/objects/contract-type.object.ts

@@ -110,7 +110,8 @@ export const ContractType = ObjectSchema.create({
       label: 'Requires Legal Review',
       group: 'workflow',
       defaultValue: true,
-      description: 'When off, a submitted contract of this type goes straight to approval (DESIGN.md §03 状态机).',
+      // The submitted → in_approval edge of the DESIGN.md §03 state machine.
+      description: 'When off, a submitted contract of this type skips legal review and goes straight to approval.',
     }),
     execution_formalities: Field.select({
       label: 'Execution Formalities',
@@ -141,20 +142,26 @@ export const ContractType = ObjectSchema.create({
       min: 0,
       max: 90,
       defaultValue: 5,
-      description: 'Calendar days legal has to finish review before the overdue reminder fires (F3).',
+      // DESIGN.md §06 F3 reads this per type, but the reminder fires at a fixed
+      // 30 days until the platform can compare dates (decision #31, 1C + 2B — see
+      // legal-review-sla.flow.ts), so the help text must not promise a per-type
+      // reminder.
+      description: 'Calendar days legal has to finish reviewing a contract of this type. The overdue reminder does not use this value: it currently fires at a fixed 30 days.',
     }),
 
     template_file: Field.file({
       label: 'Template',
       group: 'template',
       accept: ['application/pdf', '.docx'],
       maxSize: 20 * 1024 * 1024,
-      description: 'The document a first version is drafted from. No rendering engine exists on the platform yet — the launch form hands the template and its placeholder list to the drafter (DESIGN.md §12).',
+      // No rendering engine exists on the platform yet (DESIGN.md §12).
+      description: 'The document a first version is drafted from. The launch form hands the template and its placeholder list to the drafter; it does not fill the template in.',
     }),
     template_placeholders: Field.json({
       label: 'Template Placeholders',
       group: 'template',
-      description: 'Array of { key, label, type, required } — the same shape as DocumentTemplate.placeholders in @objectstack/spec.',
+      // The same shape as DocumentTemplate.placeholders in @objectstack/spec.
+      description: 'A JSON list of the template\'s placeholders, one { key, label, type, required } entry per placeholder.',
     }),
 
     default_term_months: Field.number({

src/objects/contract-version.object.ts

@@ -38,7 +38,7 @@ export const ContractVersion = ObjectSchema.create({
       readonly: true,
       searchable: true,
       maxLength: 80,
-      description: 'Stored mirror "v<version_no> · <kind>", stamped by mirror.hook.ts.',
+      description: 'Filled in automatically from the version number and kind, e.g. "v2 · Clean".',
     }),
     contract: Field.masterDetail('clm_contract', {
       label: 'Contract',
@@ -84,7 +84,8 @@ export const ContractVersion = ObjectSchema.create({
       label: 'Current',
       group: 'version',
       defaultValue: false,
-      description: 'The version negotiation is currently on. The clean-version guard before signing reads this flag.',
+      // The approved → signing guard in contract.hook.ts reads this flag.
+      description: 'The version negotiation is currently on. A contract can go to signing only once its current version is a clean copy.',
     }),
 
     file: Field.file({