feat(mdl): default columns mirror tracking-number components + customizable

Per the reference doc at zddc.varasys.io/reference.html#tracking-numbers,
a tracking number is composed of: originator, [phase], project,
[area], discipline, type, sequence, [suffix]. The default Master
Deliverables List now surfaces every component as its own column,
plus the standard MDL metadata (title, plannedRevision,
plannedDate, status, owner). Columns appear in the canonical
filename order so the table reads left-to-right like the tracking
number itself.

Optional components ([phase], [area], [suffix]) render in the
table even when blank — keeps the layout consistent across rows.
Projects on a schema that doesn't use them hide the columns by
overriding (see customization).

Form schema (default-mdl.form.yaml):

- One JSON Schema property per tracking-number component, plus
  the deliverable metadata. originator / project / discipline /
  type / sequence are required; phase / area / suffix are
  optional. The schema is intentionally permissive — free-text
  strings on every component, no enums or regex constraints.
  Projects pick their own conventions for originator codes,
  discipline vocabularies, etc.; a default that imposed a
  fixed set would just get in the way.

- Phase 2's editable-cell widget factory derives the right
  per-cell editor from this schema: text inputs for the
  components, the existing select for `status` (which keeps
  its enum), date input for `plannedDate`, textarea for
  `notes`.

Customization (the "way for end users to customize"):

- Drop your own table.yaml and / or form.yaml into the rows
  directory (archive/<party>/mdl/, or any directory hosting a
  table). Operator-supplied files override the embedded defaults
  ATOMICALLY — there's no field-level merge, the operator file
  wins entirely. This matches every other "spec on disk wins"
  convention in zddc-server.

- Hide a column: omit it from the columns: list.
- Rename a column header: change `title:`.
- Add a column: append a {field, title} entry AND add a
  matching property in form.yaml's schema.properties.
- Tighten constraints: use `enum:`, `pattern:`, `minLength:`
  etc. on form.yaml properties.
- Pre-filter rows on load: defaults.filter[<field>].

The whole rows-directory is self-contained — copying mdl/ to a
new project takes the spec, the form, and every row YAML
together.

Documentation:

- AGENTS.md "Tables system" gains a paragraph on the default-MDL
  column set + the customization mechanism + a pointer to the
  embedded source files.

- tables/template.html help panel rewrites the body to cover:
    * What the directory IS (spec + form + row YAMLs together).
    * Editable-cell keyboard shortcuts (the Phase 1-5 sequence
      we just shipped — arrows, Tab, Enter, F2, Delete, Ctrl+D /
      R / C / V / Z, Shift+arrow / Shift+click for ranges).
    * The auto-save model + per-row state swatch colors.
    * The customization model with a worked file-tree example.
  Replaces the obsolete pre-Phase-1 wording that referenced
  `*.table.yaml` parent files and click-to-navigate-row UX.

Tests: no schema test changes — the default YAMLs are loaded
through the same RecognizeTableRequest / RecognizeFormRequest
paths that already cover the fallback. Full Playwright + Go
suites green (44 + 13).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -376,6 +376,8 @@ Read/aggregate counterpart to the form system. Renders a directory of YAML row f
 
 **Default-MDL fallback at `archive/<party>/mdl/`**: when no `table.yaml` (or `form.yaml`) exists on disk in this exact location, the server serves embedded default bytes. The `mdl/` directory itself doesn't even need to exist — the URL renders the default MDL view fully virtually so a fresh archive surfaces the master document list without operator setup. Outside `archive/<party>/mdl/`, presence-based discovery is the rule.
 
+**Default-MDL columns mirror the tracking-number components** documented at `zddc.varasys.io/reference.html#tracking-numbers`: `originator`, `phase`, `project`, `area`, `discipline`, `type`, `sequence`, `suffix` — each one a slot of the deliverable's permanent identifier — plus `title`, `plannedRevision`, `plannedDate`, `status`, `owner`. The form schema accepts free-text on every component (no enums or regex constraints) so projects pick their own conventions. Operators customize by dropping their own `table.yaml` + `form.yaml` into `archive/<party>/mdl/`; both files override the embedded defaults atomically (no merge — operator-supplied wins entirely). Source: `zddc/internal/handler/default-mdl.{table,form}.yaml`.
+
 **Adding a new table**: create a directory `<dir>/` and drop `table.yaml` (and optionally `form.yaml` for row editing) into it. No code change required. Visit `<dir>/table.html`.
 
 ## Implementation-vs-dependency policy

tables/template.html

@@ -73,27 +73,85 @@
         </div>
         <div class="help-panel__body">
             <h3>What is this table?</h3>
-            <p>Each row in this table is one YAML file in the source directory.
+            <p>The directory you opened — say <code>archive/Acme/mdl/</code> —
-            Tables are declared in <code>.zddc</code> via a
+            <em>is</em> the table. <code>table.yaml</code> describes the
-            <code>tables:</code> map. The columns and row schema come from
+            columns; <code>form.yaml</code> describes the row-edit form
-            a <code>*.table.yaml</code> spec file.</p>
+            schema; every other <code>.yaml</code> file in the directory
+            is one row. Copying the directory anywhere takes the whole
+            table (spec + form + every row) with it.</p>
+
+            <h3>Editing cells</h3>
+            <p>Click a cell to select it. Then:</p>
+            <dl>
+                <dt><kbd>↑</kbd> / <kbd>↓</kbd> / <kbd>←</kbd> / <kbd>→</kbd></dt>
+                <dd>Move selection. Hold <kbd>Shift</kbd> to extend a range.</dd>
+                <dt><kbd>Tab</kbd> / <kbd>Shift+Tab</kbd></dt>
+                <dd>Move right / left, wrap to next / previous row.</dd>
+                <dt><kbd>Enter</kbd> / <kbd>F2</kbd> / double-click / typing</dt>
+                <dd>Enter edit mode. Typing replaces the cell value; the
+                others keep it.</dd>
+                <dt><kbd>Enter</kbd> in edit mode</dt>
+                <dd>Commit and move down.</dd>
+                <dt><kbd>Tab</kbd> in edit mode</dt>
+                <dd>Commit and move right.</dd>
+                <dt><kbd>Esc</kbd></dt>
+                <dd>Cancel the edit; restore the prior value.</dd>
+                <dt><kbd>Delete</kbd> / <kbd>Backspace</kbd></dt>
+                <dd>Clear every cell in the current selection.</dd>
+                <dt><kbd>Ctrl+D</kbd> / <kbd>Ctrl+R</kbd></dt>
+                <dd>Fill the top row down / left column right through the
+                selected range.</dd>
+                <dt><kbd>Ctrl+C</kbd> / <kbd>Ctrl+V</kbd></dt>
+                <dd>Copy / paste — interoperates with Excel and Google
+                Sheets via tab-separated values.</dd>
+                <dt><kbd>Ctrl+Z</kbd></dt>
+                <dd>Undo the last edit (one history per session).</dd>
+            </dl>
+            <p>Edits save automatically when you move to a different row.
+            A small left-edge swatch on the row indicates state:
+            <strong>blue</strong> = unsaved, <strong>amber</strong> = the
+            server flagged a validation error, <strong>orange</strong> =
+            someone else changed this row since you loaded it (you'll
+            get a prompt with <em>Use mine</em> / <em>Reload</em>).</p>
 
             <h3>Sorting</h3>
             <p>Click a column header to sort by that column. Click again to
-            toggle direction. Shift-click another header to add a secondary
+            toggle direction. <kbd>Shift</kbd>-click another header to
-            sort key.</p>
+            add a secondary sort key.</p>
 
             <h3>Filtering</h3>
             <p>Type in the box under a column header to filter rows whose
-            value contains your text (case-insensitive). For columns with a
+            value contains your text (case-insensitive). Same filter UI
-            fixed enum, the box becomes a multi-select — leave it empty to
+            for every column.</p>
-            show every value.</p>
 
-            <h3>Editing a row</h3>
+            <h3>Customizing the columns</h3>
-            <p>Click a row to open its YAML in the form editor. Whether the
+            <p>The default Master Deliverables List has columns for every
-            row is editable depends on the cascading <code>.zddc</code>
+            component of a tracking number
-            permissions for the row's path. Rows in <code>Issued</code> or
+            (<code>originator</code>, <code>phase</code>,
-            <code>Received</code> archives are read-only by design (WORM).</p>
+            <code>project</code>, <code>area</code>,
+            <code>discipline</code>, <code>type</code>,
+            <code>sequence</code>, <code>suffix</code>) plus deliverable
+            metadata. To customize, drop your own
+            <code>table.yaml</code> (and matching
+            <code>form.yaml</code>) into this directory:</p>
+            <pre><code>archive/&lt;party&gt;/mdl/
+  table.yaml          ← columns + sort/filter defaults
+  form.yaml           ← per-row schema (JSON Schema)
+  &lt;id&gt;.yaml ...     ← rows</code></pre>
+            <p>Operator-supplied files override the embedded defaults.
+            Hide a column by omitting it from <code>columns:</code>;
+            add a column by appending one (and adding the matching
+            property in <code>form.yaml</code>'s
+            <code>schema.properties</code>). The same pattern works
+            for any directory — <code>&lt;dir&gt;/table.html</code>
+            is automatically a table whenever
+            <code>&lt;dir&gt;/table.yaml</code> exists.</p>
+
+            <h3>Permissions</h3>
+            <p>Whether a row is editable depends on the cascading
+            <code>.zddc</code> permissions for the directory. Rows
+            in <code>Issued</code> or <code>Received</code> archives
+            are read-only by design (WORM).</p>
 
             <h3>Header buttons</h3>
             <dl>

zddc/internal/handler/default-mdl.form.yaml

@@ -1,32 +1,77 @@
-# Default row schema for a Master Deliverables List entry. Served by
+# Default row schema for a Master Deliverables List entry, served by
-# zddc-server when no operator-supplied mdl.form.yaml exists at
+# zddc-server when no operator-supplied form.yaml exists at
-# archive/<party>/. Operators can override per-party.
+# archive/<party>/mdl/.
+#
+# Properties cover every component of the ZDDC tracking-number model
+# (zddc.varasys.io/reference.html#tracking-numbers) plus the standard
+# MDL metadata (title, planned revision, planned date, status, owner,
+# notes). The schema is intentionally permissive on the components
+# (free-text strings, no regex / enum constraints) — projects choose
+# their own conventions for originator codes, discipline vocabularies,
+# etc., and a default that imposed a fixed set would just get in the
+# way.
+#
+# To customize: drop your own form.yaml into archive/<party>/mdl/
+# (the same directory as table.yaml). Tighten constraints with
+# `enum:`, `pattern:`, `minLength:`, etc. Add fields and they'll
+# appear in the row-edit form; add a matching column to table.yaml
+# to surface the field in the table view too.
 
 title: Deliverable
-description: One planned or in-flight deliverable for this party.
+description: One planned or in-flight deliverable. The first eight fields are components of this row's tracking number; the rest are deliverable metadata.
 
 schema:
   type: object
-  required: [tracking, title]
+  required: [originator, project, discipline, type, sequence, title]
   additionalProperties: false
   properties:
-    tracking:
+    # --- Tracking-number components (matches the reference doc's
+    # field definitions, in order). originator / project / discipline
+    # / type / sequence are the structural minimum; phase / area /
+    # suffix are optional and project-dependent.
+    originator:
       type: string
-      title: Tracking number
+      title: Originator
-      description: ZDDC tracking identifier (e.g. proj-EM-SPC-0001).
+      description: Organizational unit responsible for this deliverable (e.g. ACME).
       minLength: 1
+    phase:
+      type: string
+      title: Phase
+      description: Optional project phase code (e.g. ECI, EPC). Leave blank if your tracking-number schema doesn't use phases.
+    project:
+      type: string
+      title: Project
+      description: Project identifier, or your corporate placeholder (e.g. 000000) for non-project deliverables.
+      minLength: 1
+    area:
+      type: string
+      title: Area
+      description: Optional area / budget code (e.g. B02). Leave blank if unused.
+    discipline:
+      type: string
+      title: Discipline
+      description: Engineering or functional group code (EL, ME, CV, PM, ...).
+      minLength: 1
+    type:
+      type: string
+      title: Document type
+      description: Document category code within the discipline (SPC, DWG, RPT, ...).
+      minLength: 1
+    sequence:
+      type: string
+      title: Sequence
+      description: Zero-padded integer (0001, 0042, 2623). Stored as a string so leading zeros survive YAML.
+      minLength: 1
+    suffix:
+      type: string
+      title: Suffix
+      description: Optional structural-part suffix (-A for Appendix A, -01 for Sheet 1). Use only for parts of the SAME deliverable; separate documents get their own tracking number.
+
+    # --- Deliverable metadata.
     title:
       type: string
       title: Deliverable title
       minLength: 1
-    discipline:
-      type: string
-      title: Discipline
-      description: Engineering discipline code (EM, EL, MC, ST, ...).
-    type:
-      type: string
-      title: Document type
-      description: Code for document class (SPC, DWG, RPT, ...).
     plannedRevision:
       type: string
       title: Planned revision
@@ -46,3 +91,6 @@ schema:
     notes:
       type: string
       title: Notes
+ui:
+  notes:
+    ui:widget: textarea

zddc/internal/handler/default-mdl.table.yaml

@@ -1,40 +1,83 @@
 # Default Master Deliverables List spec, served by zddc-server when no
-# operator-supplied mdl.table.yaml exists at archive/<party>/. Operators
+# operator-supplied table.yaml exists at archive/<party>/mdl/.
-# can override per-party by writing their own file at
+#
-# archive/<party>/mdl.table.yaml plus a tables: { mdl: ./mdl.table.yaml }
+# Columns mirror the tracking-number component model documented at
-# entry in the party's .zddc.
+# zddc.varasys.io/reference.html#tracking-numbers — every column from
+# `originator` through `suffix` is one slot of a deliverable's
+# permanent identifier. Optional components ([phase], [area], [suffix])
+# render in the table even when blank so the layout stays consistent
+# across rows; users on schemas that don't use them can hide the
+# columns by overriding this spec (see customization note below).
+#
+# Beyond the tracking-number fields, the table tracks the deliverable's
+# title, planned revision and date, current status, owner, and notes —
+# the standard MDL columns operators expect for planning and status
+# tracking.
+#
+# To customize: drop your own table.yaml + form.yaml into the same
+# directory (archive/<party>/mdl/). The whole directory IS the table —
+# spec, row-edit form, and rows are siblings. Override examples:
+#   - Hide a column: omit it from the columns: list here.
+#   - Rename a column header: change `title:`.
+#   - Add a custom column: append a {field, title} entry AND add a
+#     matching property in form.yaml's schema.properties so the row
+#     form lets users fill it in.
+#   - Tighten column widths: set `width:` (CSS length, e.g. "8em").
+#   - Pre-filter rows on load: defaults.filter[<field>] = "<text>".
+#
+# The whole directory is self-contained — copying mdl/ to a new
+# project takes the spec, the form, and every row YAML with it.
 
 title: Master Deliverables List
-description: Planned and actual deliverables for this party.
+description: Planned and actual deliverables for this party. Columns mirror the tracking-number components plus standard MDL metadata.
-
-rowSchema: ./mdl.form.yaml
-rows: ./mdl
 
 columns:
-  - field: tracking
+  # --- Tracking-number components (in the order they appear in the
-    title: Tracking
+  # canonical filename: originator-[phase-]project-[area-]discipline-
-    width: 11em
+  # type-sequence[-suffix]). Optional components are kept narrow so
-    sort: asc
+  # they don't clutter the layout when unused.
-  - field: title
+  - field: originator
-    title: Deliverable
+    title: Originator
+    width: 8em
+  - field: phase
+    title: Phase
+    width: 5em
+  - field: project
+    title: Project
+    width: 8em
+  - field: area
+    title: Area
+    width: 5em
   - field: discipline
     title: Disc.
     width: 5em
   - field: type
     title: Type
     width: 6em
+  - field: sequence
+    title: Seq.
+    width: 5em
+  - field: suffix
+    title: Suffix
+    width: 5em
+
+  # --- Deliverable metadata.
+  - field: title
+    title: Deliverable
   - field: plannedRevision
     title: Rev.
     width: 5em
   - field: plannedDate
     title: Planned
     format: date
+    width: 8em
   - field: status
     title: Status
     width: 6em
     enum: [DFT, IFR, IFA, IFC, AFC, AB]
   - field: owner
     title: Owner
+    width: 12em
 
 defaults:
   sort:

zddc/internal/handler/tables.html

@@ -939,7 +939,7 @@ body.help-open .app-header {
             </svg>
             <div class="header-title-group">
                 <span class="app-header__title" id="table-title">ZDDC Table</span>
-                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.17-alpha · 2026-05-09 15:38:03 · 8e703dc-dirty</span></span>
+                <span class="build-timestamp"><span style="color:red;font-weight:bold">v0.0.17-alpha · 2026-05-09 16:07:14 · d3cd662-dirty</span></span>
             </div>
         </div>
         <div class="header-right">
@@ -990,27 +990,85 @@ body.help-open .app-header {
         </div>
         <div class="help-panel__body">
             <h3>What is this table?</h3>
-            <p>Each row in this table is one YAML file in the source directory.
+            <p>The directory you opened — say <code>archive/Acme/mdl/</code> —
-            Tables are declared in <code>.zddc</code> via a
+            <em>is</em> the table. <code>table.yaml</code> describes the
-            <code>tables:</code> map. The columns and row schema come from
+            columns; <code>form.yaml</code> describes the row-edit form
-            a <code>*.table.yaml</code> spec file.</p>
+            schema; every other <code>.yaml</code> file in the directory
+            is one row. Copying the directory anywhere takes the whole
+            table (spec + form + every row) with it.</p>
+
+            <h3>Editing cells</h3>
+            <p>Click a cell to select it. Then:</p>
+            <dl>
+                <dt><kbd>↑</kbd> / <kbd>↓</kbd> / <kbd>←</kbd> / <kbd>→</kbd></dt>
+                <dd>Move selection. Hold <kbd>Shift</kbd> to extend a range.</dd>
+                <dt><kbd>Tab</kbd> / <kbd>Shift+Tab</kbd></dt>
+                <dd>Move right / left, wrap to next / previous row.</dd>
+                <dt><kbd>Enter</kbd> / <kbd>F2</kbd> / double-click / typing</dt>
+                <dd>Enter edit mode. Typing replaces the cell value; the
+                others keep it.</dd>
+                <dt><kbd>Enter</kbd> in edit mode</dt>
+                <dd>Commit and move down.</dd>
+                <dt><kbd>Tab</kbd> in edit mode</dt>
+                <dd>Commit and move right.</dd>
+                <dt><kbd>Esc</kbd></dt>
+                <dd>Cancel the edit; restore the prior value.</dd>
+                <dt><kbd>Delete</kbd> / <kbd>Backspace</kbd></dt>
+                <dd>Clear every cell in the current selection.</dd>
+                <dt><kbd>Ctrl+D</kbd> / <kbd>Ctrl+R</kbd></dt>
+                <dd>Fill the top row down / left column right through the
+                selected range.</dd>
+                <dt><kbd>Ctrl+C</kbd> / <kbd>Ctrl+V</kbd></dt>
+                <dd>Copy / paste — interoperates with Excel and Google
+                Sheets via tab-separated values.</dd>
+                <dt><kbd>Ctrl+Z</kbd></dt>
+                <dd>Undo the last edit (one history per session).</dd>
+            </dl>
+            <p>Edits save automatically when you move to a different row.
+            A small left-edge swatch on the row indicates state:
+            <strong>blue</strong> = unsaved, <strong>amber</strong> = the
+            server flagged a validation error, <strong>orange</strong> =
+            someone else changed this row since you loaded it (you'll
+            get a prompt with <em>Use mine</em> / <em>Reload</em>).</p>
 
             <h3>Sorting</h3>
             <p>Click a column header to sort by that column. Click again to
-            toggle direction. Shift-click another header to add a secondary
+            toggle direction. <kbd>Shift</kbd>-click another header to
-            sort key.</p>
+            add a secondary sort key.</p>
 
             <h3>Filtering</h3>
             <p>Type in the box under a column header to filter rows whose
-            value contains your text (case-insensitive). For columns with a
+            value contains your text (case-insensitive). Same filter UI
-            fixed enum, the box becomes a multi-select — leave it empty to
+            for every column.</p>
-            show every value.</p>
 
-            <h3>Editing a row</h3>
+            <h3>Customizing the columns</h3>
-            <p>Click a row to open its YAML in the form editor. Whether the
+            <p>The default Master Deliverables List has columns for every
-            row is editable depends on the cascading <code>.zddc</code>
+            component of a tracking number
-            permissions for the row's path. Rows in <code>Issued</code> or
+            (<code>originator</code>, <code>phase</code>,
-            <code>Received</code> archives are read-only by design (WORM).</p>
+            <code>project</code>, <code>area</code>,
+            <code>discipline</code>, <code>type</code>,
+            <code>sequence</code>, <code>suffix</code>) plus deliverable
+            metadata. To customize, drop your own
+            <code>table.yaml</code> (and matching
+            <code>form.yaml</code>) into this directory:</p>
+            <pre><code>archive/&lt;party&gt;/mdl/
+  table.yaml          ← columns + sort/filter defaults
+  form.yaml           ← per-row schema (JSON Schema)
+  &lt;id&gt;.yaml ...     ← rows</code></pre>
+            <p>Operator-supplied files override the embedded defaults.
+            Hide a column by omitting it from <code>columns:</code>;
+            add a column by appending one (and adding the matching
+            property in <code>form.yaml</code>'s
+            <code>schema.properties</code>). The same pattern works
+            for any directory — <code>&lt;dir&gt;/table.html</code>
+            is automatically a table whenever
+            <code>&lt;dir&gt;/table.yaml</code> exists.</p>
+
+            <h3>Permissions</h3>
+            <p>Whether a row is editable depends on the cascading
+            <code>.zddc</code> permissions for the directory. Rows
+            in <code>Issued</code> or <code>Received</code> archives
+            are read-only by design (WORM).</p>
 
             <h3>Header buttons</h3>
             <dl>