From a80e99e500587aec53689019a2f4e20269949410 Mon Sep 17 00:00:00 2001
From: forbes-0023 <joseph.forbes@kindred-systems.com>
Date: Wed, 11 Feb 2026 10:40:09 -0600
Subject: [PATCH] docs: update specs for schema-driven form descriptor API

- frontend-spec.md: rewrite CreateItemPane spec for dynamic form
  rendering from form descriptor, replace CategoryPicker three-column
  spec with multi-stage domain/subcategory picker, replace useCategories
  hook with useFormDescriptor, update form sections to dynamic field
  groups, mark hierarchical categories as implemented, remove
  sourcing_link/standard_cost from item-level DB columns, update types
  and implementation order
- SPECIFICATION.md: rename /api/schemas/{name}/properties endpoint to
  /api/schemas/{name}/form
---
 docs/SPECIFICATION.md |   2 +-
 frontend-spec.md      | 339 +++++++++++++++++++++++-------------------
 2 files changed, 185 insertions(+), 156 deletions(-)

diff --git a/docs/SPECIFICATION.md b/docs/SPECIFICATION.md
index 8f89a93..772b927 100644
--- a/docs/SPECIFICATION.md
+++ b/docs/SPECIFICATION.md
@@ -627,7 +627,7 @@ POST   /api/uploads/presign                                 # Get presigned MinI
 # Schemas (read: viewer, write: editor)
 GET    /api/schemas                                         # List all schemas
 GET    /api/schemas/{name}                                  # Get schema details
-GET    /api/schemas/{name}/properties                       # Get property schema for category
+GET    /api/schemas/{name}/form                             # Get form descriptor (field groups, widgets, category picker)
 POST   /api/schemas/{name}/segments/{segment}/values        # Add enum value [editor]
 PUT    /api/schemas/{name}/segments/{segment}/values/{code} # Update enum value [editor]
 DELETE /api/schemas/{name}/segments/{segment}/values/{code} # Delete enum value [editor]
diff --git a/frontend-spec.md b/frontend-spec.md
index 4e29629..6eb6ab3 100644
--- a/frontend-spec.md
+++ b/frontend-spec.md
@@ -1,6 +1,6 @@
 # Silo Frontend Specification
 
-Current as of 2026-02-08. Documents the React + Vite + TypeScript frontend (migration from Go templates is complete).
+Current as of 2026-02-11. Documents the React + Vite + TypeScript frontend (migration from Go templates is complete).
 
 ## Overview
 
@@ -68,6 +68,7 @@ web/
     │   └── AuthContext.tsx                AuthProvider with login/logout/refresh methods
     ├── hooks/
     │   ├── useAuth.ts                    Context consumer hook
+    │   ├── useFormDescriptor.ts           Fetches form descriptor from /api/schemas/{name}/form (replaces useCategories)
     │   ├── useItems.ts                   Items fetching with search, filters, pagination, debounce
     │   └── useLocalStorage.ts            Typed localStorage persistence hook
     ├── styles/
@@ -271,63 +272,81 @@ Vite dev server runs on port 5173 with proxy config in `vite.config.ts` forwardi
 
 ## New Frontend Tasks
 
-# CreateItemPane Redesign Specification
+# CreateItemPane — Schema-Driven Dynamic Form
 
-**Date**: 2026-02-06
-**Scope**: Replace existing `CreateItemPane.tsx` with a two-column layout, multi-stage category picker, file attachment via MinIO, and full use of screen real estate.
+**Date**: 2026-02-10
+**Scope**: `CreateItemPane.tsx` renders a dynamic form driven entirely by the form descriptor API (`GET /api/schemas/{name}/form`). All field groups, field types, widgets, and category-specific fields are defined in YAML and resolved server-side.
 **Parent**: Items page (`ItemsPage.tsx`) — renders in the detail pane area per existing in-pane CRUD pattern.
 
 ---
 
 ## Layout
 
-The pane uses a CSS Grid two-column layout instead of the current single-column form:
+Single-column scrollable form with a green header bar. Field groups are rendered dynamically from the form descriptor. Category-specific field groups appear after global groups when a category is selected.
 
 ```
-┌──────────────────────────────────────────────────────┬──────────────┐
-│  Header: "New Item"  [green bar]      Cancel │ Create │              │
-├──────────────────────────────────────────────────────┤              │
-│                                                      │  Auto-       │
-│  ── Identity ──────────────────────────────────────  │  assigned    │
-│  [Part Number *]          [Type *        v]          │  metadata    │
-│  [Description                               ]        │              │
-│  Category * [Domain   │ Group    │ Subtype  ]        │──────────────│
-│             Mechanical│ Structural│ Bracket  │        │              │
-│             Electrical│ Bearings  │ Plate    │        │  Attachments │
-│             ...       │ ...       │ ...      │        │  ┌─ ─ ─ ─ ┐ │
-│  ── Sourcing ──────────────────────────────────────  │  │ Drop   │ │
-│  [Sourcing Type v]    [Standard Cost  $    ]         │  │ zone   │ │
-│  [Unit of Measure v]  [Sourcing Link       ]         │  └─ ─ ─ ─ ┘ │
-│                                                      │  file.FCStd  │
-│  ── Details ───────────────────────────────────────  │  drawing.pdf │
-│  [Long Description                          ]        │              │
-│  [Projects: [tag][tag] type to search...    ]        │──────────────│
-│                                                      │  Thumbnail   │
-│                                                      │  [preview]   │
-└──────────────────────────────────────────────────────┴──────────────┘
+┌──────────────────────────────────────────────────────────────────────┐
+│  Header: "New Item"  [green bar]                    Cancel │ Create │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  Category * [Domain buttons: F C R S E M T A P X]                   │
+│             [Subcategory search + filtered list]                     │
+│                                                                      │
+│  ── Identity ────────────────────────────────────────────────────── │
+│  [Type *   (auto-derived from category)]  [Description           ]  │
+│                                                                      │
+│  ── Sourcing ────────────────────────────────────────────────────── │
+│  [Sourcing Type v]  [Manufacturer]  [MPN]  [Supplier]  [SPN]       │
+│  [Sourcing Link]                                                     │
+│                                                                      │
+│  ── Cost & Lead Time ────────────────────────────────────────────── │
+│  [Standard Cost $]  [Lead Time Days]  [Min Order Qty]               │
+│                                                                      │
+│  ── Status ──────────────────────────────────────────────────────── │
+│  [Lifecycle Status v]  [RoHS Compliant ☐]  [Country of Origin]     │
+│                                                                      │
+│  ── Details ─────────────────────────────────────────────────────── │
+│  [Long Description                                              ]   │
+│  [Projects: [tag][tag] type to search...                       ]    │
+│  [Notes                                                         ]   │
+│                                                                      │
+│  ── Fastener Specifications (category-specific) ─────────────────── │
+│  [Material]  [Finish]  [Thread Size]  [Head Type]  [Drive Type] ... │
+│                                                                      │
+└──────────────────────────────────────────────────────────────────────┘
 ```
 
-Grid definition: `grid-template-columns: 1fr 320px`. The left column scrolls independently if content overflows. The right sidebar is a flex column with sections separated by `--ctp-surface1` borders.
+## Data Source — Form Descriptor API
+
+All form structure is fetched from `GET /api/schemas/kindred-rd/form`, which returns:
+
+- `category_picker`: Multi-stage picker config (domain → subcategory)
+- `item_fields`: Definitions for item-level fields (description, item_type, sourcing_type, etc.)
+- `field_groups`: Ordered groups with resolved field metadata (Identity, Sourcing, Cost, Status, Details)
+- `category_field_groups`: Per-category-prefix groups (e.g., Fastener Specifications for `F` prefix)
+- `field_overrides`: Widget hints (currency, url, select, checkbox)
+
+The YAML schema (`schemas/kindred-rd.yaml`) is the single source of truth. Adding a new field or category in YAML propagates to all clients with no code changes.
 
 ## File Location
 
-`web/src/components/items/CreateItemPane.tsx` (replaces existing file)
+`web/src/components/items/CreateItemPane.tsx`
 
-New supporting files:
+Supporting files:
 
 | File | Purpose |
 |------|---------|
-| `web/src/components/items/CategoryPicker.tsx` | Multi-stage category selector |
+| `web/src/components/items/CategoryPicker.tsx` | Multi-stage domain/subcategory selector |
 | `web/src/components/items/FileDropZone.tsx` | Drag-and-drop file upload with MinIO presigned URLs |
 | `web/src/components/items/TagInput.tsx` | Multi-select tag input for projects |
-| `web/src/hooks/useCategories.ts` | Fetches category tree from schema data |
+| `web/src/hooks/useFormDescriptor.ts` | Fetches and caches form descriptor from `/api/schemas/{name}/form` |
 | `web/src/hooks/useFileUpload.ts` | Manages presigned URL upload flow |
 
 ## Component Breakdown
 
 ### CreateItemPane
 
-Top-level orchestrator. Manages form state, submission, and layout.
+Top-level orchestrator. Renders dynamic form from the form descriptor.
 
 **Props** (unchanged interface):
 
@@ -341,68 +360,64 @@ interface CreateItemPaneProps {
 **State**:
 
 ```typescript
-const [form, setForm] = useState<CreateItemForm>({
-  part_number: '',
-  item_type: 'part',
-  description: '',
-  category_path: [],        // e.g. ['Mechanical', 'Structural', 'Bracket']
-  sourcing_type: 'manufactured',
-  standard_cost: '',
-  unit_of_measure: 'ea',
-  sourcing_link: '',
-  long_description: '',
-  project_ids: [],
-});
-const [attachments, setAttachments] = useState<PendingAttachment[]>([]);
-const [thumbnail, setThumbnail] = useState<PendingAttachment | null>(null);
+const { descriptor, categories, loading } = useFormDescriptor();
+const [category, setCategory] = useState('');           // selected category code, e.g. "F01"
+const [fields, setFields] = useState<Record<string, string>>({});  // all field values keyed by name
 const [error, setError] = useState<string | null>(null);
 const [submitting, setSubmitting] = useState(false);
 ```
 
+A single `fields` record holds all form values (both item-level and property fields). The `ITEM_LEVEL_FIELDS` set (`description`, `item_type`, `sourcing_type`, `long_description`) determines which fields go into the top-level request vs. the `properties` map on submission.
+
+**Auto-derivation**: When a category is selected, `item_type` is automatically set based on the `derived_from_category` mapping in the form descriptor (e.g., category prefix `A` → `assembly`, `T` → `tooling`, default → `part`).
+
+**Dynamic rendering**: A `renderField()` function maps each field's `widget` type to the appropriate input:
+
+| Widget | Rendered As |
+|--------|-------------|
+| `text` | `<input type="text">` |
+| `number` | `<input type="number">` |
+| `textarea` | `<textarea>` |
+| `select` | `<select>` with `<option>` elements from `field.options` |
+| `checkbox` | `<input type="checkbox">` |
+| `currency` | `<input type="number">` with currency prefix (e.g., "$") |
+| `url` | `<input type="url">` |
+| `tag_input` | `TagInput` component with search endpoint |
+
 **Submission flow**:
 
-1. Validate required fields (part_number, item_type, category_path length === 3).
-2. `POST /api/items` with form data → returns created `Item` with UUID.
-3. For each attachment in `attachments[]`, call the file association endpoint: `POST /api/items/{id}/files` with the MinIO object key returned from upload.
-4. If thumbnail exists, `PUT /api/items/{id}/thumbnail` with the object key.
-5. Call `onCreated(item)`.
+1. Validate required fields (category must be selected).
+2. Split `fields` into item-level fields and properties using `ITEM_LEVEL_FIELDS`.
+3. `POST /api/items` with `{ part_number: '', item_type, description, sourcing_type, long_description, category, properties: {...} }`.
+4. Call `onCreated(item)`.
 
-If step 2 fails, show error banner. If file association fails, show warning but still navigate (item was created, files can be re-attached).
-
-**Header bar**: Green (`--ctp-green` background, `--ctp-crust` text) per existing create-pane convention. "New Item" title on left, Cancel (ghost button) and Create Item (primary button, `--ctp-green` bg) on right.
+**Header bar**: Green (`--ctp-green` background, `--ctp-crust` text). "New Item" title on left, Cancel and Create Item buttons on right.
 
 ### CategoryPicker
 
-Three-column scrollable list for hierarchical category selection.
+Multi-stage category selector driven by the form descriptor's `category_picker.stages` config.
 
 **Props**:
 
 ```typescript
 interface CategoryPickerProps {
-  value: string[];                    // current selection path, e.g. ['Mechanical', 'Structural']
-  onChange: (path: string[]) => void;
-  categories: CategoryNode[];         // top-level nodes
-}
-
-interface CategoryNode {
-  name: string;
-  children?: CategoryNode[];
+  value: string;                              // selected category code, e.g. "F01"
+  onChange: (code: string) => void;
+  categories: Record<string, string>;         // flat code → description map
+  stages?: CategoryPickerStage[];             // from form descriptor
 }
 ```
 
-**Rendering**: Three side-by-side `<div>` columns inside a container with `border: 1px solid var(--ctp-surface1)` and `border-radius: 0.4rem`. Each column has:
+**Rendering**: Two-stage selection:
 
-- A sticky header row (10px uppercase, `--ctp-overlay0` text, `--ctp-mantle` background) labeling the tier. Labels come from the schema definition if available, otherwise "Level 1", "Level 2", "Level 3".
-- A scrollable list of options. Each option is a `<div>` row, 28px height, `0.85rem` font. Hover: `--ctp-surface0` background. Selected: translucent mauve background (`rgba(203, 166, 247, 0.12)`), `--ctp-mauve` text, weight 600.
-- If a node has children, show a `›` chevron on the right side of the row.
+1. **Domain row**: Horizontal row of buttons, one per domain from `stages[0].values` (F=Fasteners, C=Fluid Fittings, etc.). Selected domain has mauve highlight.
+2. **Subcategory list**: Filtered list of categories matching the selected domain prefix. Includes a search input for filtering. Each row shows code and description.
 
-Column 1 always shows all top-level nodes. Column 2 shows children of the selected Column 1 node. Column 3 shows children of the selected Column 2 node. If nothing is selected in a column, the next column shows an empty state with muted text: "Select a [tier name]".
+If no `stages` prop is provided, falls back to a flat searchable list of all categories.
 
-Below the picker, render a breadcrumb trail: `Mechanical › Structural › Bracket` in `--ctp-mauve` with `›` separators in `--ctp-overlay0`. Only show segments that are selected.
+Below the picker, the selected category is shown as a breadcrumb: `Fasteners › F01 — Hex Cap Screw` in `--ctp-mauve`.
 
-**Data source**: Categories are derived from schemas. The `useCategories` hook calls `GET /api/schemas` and transforms the response into a `CategoryNode[]` tree. The exact mapping depends on how schemas define category hierarchies — if schemas don't currently support hierarchical categories, this requires a backend addition (see Backend Changes section).
-
-**Max height**: 180px per column with `overflow-y: auto`.
+**Data source**: Categories come from `useFormDescriptor()` which derives them from the `category_picker` stages and `values_by_domain` in the form descriptor response.
 
 ### FileDropZone
 
@@ -478,17 +493,17 @@ The dropdown is an absolutely-positioned `<div>` below the input container, `--c
 
 **For projects**: `searchFn` calls `GET /api/projects?q={query}` and maps to `{ id: project.id, label: project.code + ' — ' + project.name }`.
 
-### useCategories Hook
+### useFormDescriptor Hook
 
 ```typescript
-function useCategories(): {
-  categories: CategoryNode[];
+function useFormDescriptor(schemaName = "kindred-rd"): {
+  descriptor: FormDescriptor | null;
+  categories: Record<string, string>;   // flat code → description map derived from descriptor
   loading: boolean;
-  error: string | null;
 }
 ```
 
-Fetches `GET /api/schemas` on mount and transforms into a category tree. Caches in a module-level variable so repeated renders don't refetch. If the API doesn't currently support hierarchical categories, this returns a flat list as a single-tier picker until the backend is extended.
+Fetches `GET /api/schemas/{name}/form` on mount. Caches the result in a module-level variable so repeated renders/mounts don't refetch. Derives a flat `categories` map from the `category_picker` stages and `values_by_domain` in the response. Replaces the old `useCategories` hook (deleted).
 
 ### useFileUpload Hook
 
@@ -542,30 +557,32 @@ const styles = {
 
 ## Form Sections
 
-The form is visually divided by section headers. Each header is a flex row containing a label (11px uppercase, `--ctp-overlay0`) and a `flex: 1` horizontal line (`1px solid --ctp-surface0`). Sections span `grid-column: 1 / -1`.
+Form sections are rendered dynamically from the `field_groups` array in the form descriptor. Each section header is a flex row containing a label (11px uppercase, `--ctp-overlay0`) and a `flex: 1` horizontal line (`1px solid --ctp-surface0`).
 
-| Section | Fields |
-|---------|--------|
-| Identity | Part Number*, Type*, Description, Category* |
-| Sourcing | Sourcing Type, Standard Cost, Unit of Measure, Sourcing Link |
-| Details | Long Description, Projects |
+**Global field groups** (from `ui.field_groups` in YAML):
 
-## Sidebar Sections
+| Group Key | Label | Fields |
+|-----------|-------|--------|
+| identity | Identity | item_type, description |
+| sourcing | Sourcing | sourcing_type, manufacturer, manufacturer_pn, supplier, supplier_pn, sourcing_link |
+| cost | Cost & Lead Time | standard_cost, lead_time_days, minimum_order_qty |
+| status | Status | lifecycle_status, rohs_compliant, country_of_origin |
+| details | Details | long_description, projects, notes |
 
-The right sidebar is divided into three sections with `borderBottom: 1px solid var(--ctp-surface0)`:
+**Category-specific field groups** (from `ui.category_field_groups` in YAML, shown when a category is selected):
 
-**Auto-assigned metadata**: Read-only key-value rows showing:
-- UUID: "On create" in `--ctp-teal` italic
-- Revision: "A" (hardcoded initial)
-- Created By: current user's display name from `useAuth()`
+| Prefix | Group | Example Fields |
+|--------|-------|----------------|
+| F | Fastener Specifications | material, finish, thread_size, head_type, drive_type, ... |
+| C | Fitting Specifications | material, connection_type, size_1, pressure_rating, ... |
+| R | Motion Specifications | bearing_type, bore_diameter, load_rating, ... |
+| ... | ... | (one group per category prefix, defined in YAML) |
 
-**Attachments**: `FileDropZone` component. Takes `flex: 1` to fill available space.
-
-**Thumbnail**: A 4:3 aspect ratio placeholder box (`--ctp-crust` bg, `--ctp-surface0` border) with centered text "Generated from CAD file or upload manually". Clicking opens file picker filtered to images. If a thumbnail is uploaded, show it as an `<img>` with `object-fit: cover`.
+Note: `sourcing_link` and `standard_cost` are revision properties (stored in the `properties` JSONB), not item-level DB columns. They were migrated from item-level fields in PR #1 (migration 013).
 
 ## Backend Changes
 
-Items 1-3 and 5 below are implemented (migration `011_item_files.sql`, `internal/api/file_handlers.go`). Item 4 (hierarchical categories) remains open.
+Items 1-5 below are implemented. Item 4 (hierarchical categories) is resolved by the form descriptor's multi-stage category picker.
 
 ### 1. Presigned Upload URL -- IMPLEMENTED
 
@@ -597,33 +614,14 @@ Response: 204
 
 Stores the thumbnail at `items/{item_id}/thumbnail.png` in MinIO. Updates `item.thumbnail_key` column.
 
-### 4. Hierarchical Categories -- NOT IMPLEMENTED
+### 4. Hierarchical Categories -- IMPLEMENTED (via Form Descriptor)
 
-If schemas don't currently support a hierarchical category tree, one of these approaches:
+Resolved by the schema-driven form descriptor (`GET /api/schemas/{name}/form`). The YAML schema's `ui.category_picker` section defines multi-stage selection:
 
-**Option A — Schema-driven**: Add a `category_tree` JSON column to the `schemas` table that defines the hierarchy. The `GET /api/schemas` response already returns schemas; the frontend transforms this into the picker tree.
+- **Stage 1 (domain)**: Groups categories by first character of category code (F=Fasteners, C=Fluid Fittings, etc.). Values defined in `ui.category_picker.stages[0].values`.
+- **Stage 2 (subcategory)**: Auto-derived by the Go backend's `ValuesByDomain()` method, which groups the category enum values by their first character.
 
-**Option B — Dedicated table**:
-
-```sql
-CREATE TABLE categories (
-  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  name TEXT NOT NULL,
-  parent_id UUID REFERENCES categories(id),
-  sort_order INT NOT NULL DEFAULT 0,
-  UNIQUE(parent_id, name)
-);
-```
-
-With endpoints:
-```
-GET  /api/categories            → flat list with parent_id, frontend builds tree
-POST /api/categories            → { name, parent_id? }
-PUT  /api/categories/{id}       → { name, sort_order }
-DELETE /api/categories/{id}     → cascade check
-```
-
-**Recommendation**: Option B is more flexible and keeps categories as a first-class entity. The three-tier picker doesn't need to be limited to exactly three levels — it can render as many columns as the deepest category path, but three is the practical default (Domain → Group → Subtype).
+No separate `categories` table is needed — the existing schema enum values are the single source of truth. Adding a new category code to the YAML propagates to the picker automatically.
 
 ### 5. Database Schema Addition -- IMPLEMENTED
 
@@ -641,46 +639,89 @@ CREATE TABLE item_files (
 CREATE INDEX idx_item_files_item ON item_files(item_id);
 
 ALTER TABLE items ADD COLUMN thumbnail_key TEXT;
-ALTER TABLE items ADD COLUMN category_id UUID REFERENCES categories(id);
 ALTER TABLE items ADD COLUMN sourcing_type TEXT NOT NULL DEFAULT 'manufactured';
-ALTER TABLE items ADD COLUMN sourcing_link TEXT;
-ALTER TABLE items ADD COLUMN standard_cost NUMERIC(12,2);
 ALTER TABLE items ADD COLUMN unit_of_measure TEXT NOT NULL DEFAULT 'ea';
 ALTER TABLE items ADD COLUMN long_description TEXT;
 ```
 
 ## Implementation Order
 
-1. **TagInput component** — reusable, no backend changes needed, uses existing projects API.
-2. **CategoryPicker component** — start with flat/mock data, wire to real API after backend adds categories.
-3. **FileDropZone + useFileUpload** — requires presigned URL backend endpoint first.
-4. **CreateItemPane rewrite** — compose the above into the two-column layout.
-5. **Backend: categories table + endpoints** — unblocks real category data.
-6. **Backend: presigned uploads + item_files** — unblocks file attachments.
-7. **Backend: items table migration** — adds new columns (sourcing_type, standard_cost, etc.).
+1. **[DONE] Deduplicate sourcing_link/standard_cost** — Migrated from item-level DB columns to revision properties (migration 013). Removed from Go structs, API types, frontend types.
+2. **[DONE] Form descriptor API** — Added `ui` section to YAML, Go structs + validation, `GET /api/schemas/{name}/form` endpoint.
+3. **[DONE] useFormDescriptor hook** — Replaces `useCategories`, fetches and caches form descriptor.
+4. **[DONE] CategoryPicker rewrite** — Multi-stage domain/subcategory picker driven by form descriptor.
+5. **[DONE] CreateItemPane rewrite** — Dynamic form rendering from field groups, widget-based field rendering.
+6. **TagInput component** — reusable, no backend changes needed, uses existing projects API.
+7. **FileDropZone + useFileUpload** — requires presigned URL backend endpoint (already implemented).
 
-Steps 1-2 can start immediately. Steps 5-7 can run in parallel once specified. Step 4 ties it all together.
+## Types Added
 
-## Types to Add
-
-Add to `web/src/api/types.ts`:
+The following types were added to `web/src/api/types.ts` for the form descriptor system:
 
 ```typescript
-// Categories
-interface Category {
-  id: string;
+// Form descriptor types (from GET /api/schemas/{name}/form)
+interface FormFieldDescriptor {
   name: string;
-  parent_id: string | null;
-  sort_order: number;
+  type: string;
+  widget: string;
+  label: string;
+  required?: boolean;
+  default?: string;
+  unit?: string;
+  description?: string;
+  options?: string[];
+  currency?: string;
+  derived_from_category?: Record<string, string>;
+  search_endpoint?: string;
 }
 
-interface CategoryNode {
-  name: string;
-  id: string;
-  children?: CategoryNode[];
+interface FormFieldGroup {
+  key: string;
+  label: string;
+  order: number;
+  fields: FormFieldDescriptor[];
 }
 
-// File uploads
+interface CategoryPickerStage {
+  name: string;
+  label: string;
+  values?: Record<string, string>;
+  values_by_domain?: Record<string, Record<string, string>>;
+}
+
+interface CategoryPickerDescriptor {
+  style: string;
+  stages: CategoryPickerStage[];
+}
+
+interface ItemFieldDef {
+  type: string;
+  widget: string;
+  label: string;
+  required?: boolean;
+  default?: string;
+  options?: string[];
+  derived_from_category?: Record<string, string>;
+  search_endpoint?: string;
+}
+
+interface FieldOverride {
+  widget?: string;
+  currency?: string;
+  options?: string[];
+}
+
+interface FormDescriptor {
+  schema_name: string;
+  format: string;
+  category_picker: CategoryPickerDescriptor;
+  item_fields: Record<string, ItemFieldDef>;
+  field_groups: FormFieldGroup[];
+  category_field_groups: Record<string, FormFieldGroup[]>;
+  field_overrides: Record<string, FieldOverride>;
+}
+
+// File uploads (unchanged)
 interface PresignRequest {
   filename: string;
   content_type: string;
@@ -703,20 +744,6 @@ interface ItemFile {
   created_at: string;
 }
 
-// Extended create request
-interface CreateItemRequest {
-  part_number: string;
-  item_type: 'part' | 'assembly' | 'document';
-  description?: string;
-  category_id?: string;
-  sourcing_type?: 'manufactured' | 'purchased' | 'phantom';
-  standard_cost?: number;
-  unit_of_measure?: string;
-  sourcing_link?: string;
-  long_description?: string;
-  project_ids?: string[];
-}
-
 // Pending upload (frontend only, not an API type)
 interface PendingAttachment {
   file: File;
@@ -726,3 +753,5 @@ interface PendingAttachment {
   error?: string;
 }
 ```
+
+Note: `sourcing_link` and `standard_cost` have been removed from the `Item`, `CreateItemRequest`, and `UpdateItemRequest` interfaces — they are now stored as revision properties and rendered dynamically from the form descriptor.