feat(documents): add attachment records and file picker workflow

Add document persistence with typed links, metadata hashing, and a new Documents tab/form that uses a built-in file picker for interactive file selection in the TUI. closes #94

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: cpcloud

docs/content/docs/reference/data-storage.md

@@ -42,6 +42,7 @@ run migrations manually.
 | `maintenance_categories` | Pre-seeded maintenance categories |
 | `appliances`           | Physical equipment |
 | `service_log_entries`  | Service history per maintenance item |
+| `documents`            | File metadata + attachments linked to records |
 | `deletion_records`     | Audit trail for soft deletes/restores |
 
 ### Pre-seeded data

internal/app/forms.go

@@ -114,6 +114,14 @@ type applianceFormData struct {
 	Notes          string
 }
 
+type documentFormData struct {
+	Title      string
+	FilePath   string
+	EntityKind string
+	EntityID   string
+	Notes      string
+}
+
 func (m *Model) startHouseForm() {
 	values := &houseFormData{}
 	if m.hasHouse {
@@ -638,6 +646,114 @@ func (m *Model) parseVendorFormData() (data.Vendor, error) {
 	}, nil
 }
 
+func (m *Model) startDocumentForm() {
+	values := &documentFormData{}
+	m.openDocumentForm(values)
+}
+
+func (m *Model) startEditDocumentForm(id uint) error {
+	doc, err := m.store.GetDocument(id)
+	if err != nil {
+		return fmt.Errorf("load document: %w", err)
+	}
+	values := documentFormValues(doc)
+	m.editID = &id
+	m.openDocumentForm(values)
+	return nil
+}
+
+func (m *Model) openDocumentForm(values *documentFormData) {
+	form := huh.NewForm(
+		huh.NewGroup(
+			huh.NewInput().
+				Title("Title").
+				Placeholder("Final quote PDF").
+				Value(&values.Title).
+				Validate(requiredText("title")),
+			huh.NewFilePicker().
+				Title("Document file").
+				Description("Use picker search to quickly find the file").
+				FileAllowed(true).
+				DirAllowed(false).
+				ShowHidden(false).
+				Value(&values.FilePath).
+				Validate(requiredText("document file")),
+		).Title("File"),
+		huh.NewGroup(
+			huh.NewSelect[string]().
+				Title("Linked record type").
+				Options(documentEntityOptions()...).
+				Value(&values.EntityKind),
+			huh.NewInput().
+				Title("Linked record ID").
+				Placeholder("e.g. 42 (optional for none)").
+				Value(&values.EntityID).
+				Validate(optionalEntityIDForKind(&values.EntityKind)),
+			huh.NewText().Title("Notes").Value(&values.Notes),
+		).Title("Link"),
+	)
+	m.activateForm(formDocument, form, values)
+}
+
+func (m *Model) submitDocumentForm() error {
+	doc, err := m.parseDocumentFormData()
+	if err != nil {
+		return err
+	}
+	if m.editID != nil {
+		doc.ID = *m.editID
+		return m.store.UpdateDocument(doc)
+	}
+	return m.store.CreateDocument(doc)
+}
+
+func (m *Model) parseDocumentFormData() (data.Document, error) {
+	values, ok := m.formData.(*documentFormData)
+	if !ok {
+		return data.Document{}, fmt.Errorf("unexpected document form data")
+	}
+	entityKind := strings.TrimSpace(values.EntityKind)
+	if entityKind == "none" {
+		entityKind = ""
+	}
+
+	var entityID *uint
+	entityIDText := strings.TrimSpace(values.EntityID)
+	if entityKind != "" {
+		if entityIDText == "" {
+			return data.Document{}, fmt.Errorf("linked record id is required")
+		}
+		parsed, err := data.ParseRequiredInt(entityIDText)
+		if err != nil {
+			return data.Document{}, fmt.Errorf("linked record id should be a positive whole number")
+		}
+		id := uint(parsed)
+		entityID = &id
+	}
+
+	return data.Document{
+		Title:      strings.TrimSpace(values.Title),
+		FilePath:   strings.TrimSpace(values.FilePath),
+		EntityKind: entityKind,
+		EntityID:   entityID,
+		Notes:      strings.TrimSpace(values.Notes),
+	}, nil
+}
+
+func documentFormValues(doc data.Document) *documentFormData {
+	entityID := ""
+	if doc.EntityID != nil {
+		entityID = strconv.FormatUint(uint64(*doc.EntityID), 10)
+	}
+	return &documentFormData{
+		Title:      doc.Title,
+		FilePath:   doc.FilePath,
+		EntityKind: displayDocumentKind(doc.EntityKind),
+		EntityID:   entityID,
+		Notes:      doc.Notes,
+	}
+}
+
 func (m *Model) inlineEditVendor(id uint, col int) error {
 	vendor, err := m.store.GetVendor(id)
 	if err != nil {
@@ -1064,6 +1180,37 @@ func vendorOptions(vendors []data.Vendor) []huh.Option[uint] {
 	return withOrdinals(options)
 }
 
+func documentEntityOptions() []huh.Option[string] {
+	kinds := data.DocumentEntityKinds()
+	options := make([]huh.Option[string], 0, len(kinds))
+	for _, kind := range kinds {
+		label := kind
+		if kind == "" {
+			label = "none"
+		}
+		options = append(options, huh.NewOption(label, label))
+	}
+	return withOrdinals(options)
+}
+
+func optionalEntityIDForKind(kind *string) func(string) error {
+	return func(input string) error {
+		value := strings.TrimSpace(input)
+		selectedKind := strings.TrimSpace(*kind)
+		if selectedKind == "none" || selectedKind == "" {
+			if value != "" {
+				return fmt.Errorf("clear linked record id when linked record type is none")
+			}
+			return nil
+		}
+		parsed, err := data.ParseRequiredInt(value)
+		if err != nil || parsed <= 0 {
+			return fmt.Errorf("linked record id should be a positive whole number")
+		}
+		return nil
+	}
+}
+
 func requiredDate(label string) func(string) error {
 	return func(input string) error {
 		if strings.TrimSpace(input) == "" {

internal/app/handlers.go

@@ -742,3 +742,75 @@ func (projectQuoteHandler) Snapshot(store *data.Store, id uint) (undoEntry, bool
 }
 
 func (projectQuoteHandler) SyncFixedValues(_ *Model, _ []columnSpec) {}
+
+// ---------------------------------------------------------------------------
+// documentHandler
+// ---------------------------------------------------------------------------
+
+type documentHandler struct{}
+
+func (documentHandler) FormKind() FormKind { return formDocument }
+
+func (documentHandler) Load(
+	store *data.Store,
+	showDeleted bool,
+) ([]table.Row, []rowMeta, [][]cell, error) {
+	docs, err := store.ListDocuments(showDeleted)
+	if err != nil {
+		return nil, nil, nil, err
+	}
+	rows, meta, cellRows := documentRows(docs)
+	return rows, meta, cellRows, nil
+}
+
+func (documentHandler) Delete(store *data.Store, id uint) error {
+	return store.DeleteDocument(id)
+}
+
+func (documentHandler) Restore(store *data.Store, id uint) error {
+	return store.RestoreDocument(id)
+}
+
+func (documentHandler) StartAddForm(m *Model) error {
+	m.startDocumentForm()
+	return nil
+}
+
+func (documentHandler) StartEditForm(m *Model, id uint) error {
+	return m.startEditDocumentForm(id)
+}
+
+func (documentHandler) InlineEdit(m *Model, id uint, _ int) error {
+	return m.startEditDocumentForm(id)
+}
+
+func (documentHandler) SubmitForm(m *Model) error {
+	return m.submitDocumentForm()
+}
+
+func (documentHandler) Snapshot(store *data.Store, id uint) (undoEntry, bool) {
+	doc, err := store.GetDocument(id)
+	if err != nil {
+		return undoEntry{}, false
+	}
+	return undoEntry{
+		Description: fmt.Sprintf("document %q", doc.Title),
+		FormKind:    formDocument,
+		EntityID:    id,
+		Restore: func() error {
+			return store.UpdateDocument(doc)
+		},
+	}, true
+}
+
+func (documentHandler) SyncFixedValues(_ *Model, specs []columnSpec) {
+	kinds := make([]string, 0, len(data.DocumentEntityKinds()))
+	for _, kind := range data.DocumentEntityKinds() {
+		if kind == "" {
+			kinds = append(kinds, "none")
+			continue
+		}
+		kinds = append(kinds, kind)
+	}
+	setFixedValues(specs, "Type", kinds)
+}

internal/app/tables.go

@@ -54,6 +54,7 @@ func NewTabs(styles Styles) []Tab {
 	maintenanceSpecs := maintenanceColumnSpecs()
 	applianceSpecs := applianceColumnSpecs()
 	vendorSpecs := vendorColumnSpecs()
+	documentSpecs := documentColumnSpecs()
 	return []Tab{
 		{
 			Kind:    tabProjects,
@@ -90,6 +91,13 @@ func NewTabs(styles Styles) []Tab {
 			Specs:   vendorSpecs,
 			Table:   newTable(specsToColumns(vendorSpecs), styles),
 		},
+		{
+			Kind:    tabDocuments,
+			Name:    "Documents",
+			Handler: documentHandler{},
+			Specs:   documentSpecs,
+			Table:   newTable(specsToColumns(documentSpecs), styles),
+		},
 	}
 }
 
@@ -337,6 +345,17 @@ func vendorColumnSpecs() []columnSpec {
 	}
 }
 
+func documentColumnSpecs() []columnSpec {
+	return []columnSpec{
+		{Title: "ID", Min: 4, Max: 6, Align: alignRight, Kind: cellReadonly},
+		{Title: "Title", Min: 14, Max: 24, Flex: true},
+		{Title: "File", Min: 12, Max: 24, Flex: true},
+		{Title: "Type", Min: 10, Max: 14},
+		{Title: "Ref", Min: 8, Max: 16},
+		{Title: "Size", Min: 8, Max: 12, Align: alignRight, Kind: cellReadonly},
+	}
+}
+
 func vendorRows(
 	vendors []data.Vendor,
 	quoteCounts map[uint]int,
@@ -368,6 +387,46 @@ func vendorRows(
 	})
 }
 
+func documentRows(items []data.Document) ([]table.Row, []rowMeta, [][]cell) {
+	return buildRows(items, func(d data.Document) rowSpec {
+		ref := ""
+		if d.EntityID != nil {
+			ref = fmt.Sprintf("%s:%d", d.EntityKind, *d.EntityID)
+		}
+		return rowSpec{
+			ID:      d.ID,
+			Deleted: d.DeletedAt.Valid,
+			Cells: []cell{
+				{Value: fmt.Sprintf("%d", d.ID), Kind: cellReadonly},
+				{Value: d.Title, Kind: cellText},
+				{Value: d.FileName, Kind: cellText},
+				{Value: displayDocumentKind(d.EntityKind), Kind: cellText},
+				{Value: ref, Kind: cellText},
+				{Value: formatSize(d.SizeBytes), Kind: cellReadonly},
+			},
+		}
+	})
+}
+
+func displayDocumentKind(kind string) string {
+	if kind == "" {
+		return "none"
+	}
+	return kind
+}
+
+func formatSize(size int64) string {
+	if size < 1024 {
+		return fmt.Sprintf("%d B", size)
+	}
+	kb := float64(size) / 1024.0
+	if kb < 1024 {
+		return fmt.Sprintf("%.1f KB", kb)
+	}
+	mb := kb / 1024.0
+	return fmt.Sprintf("%.1f MB", mb)
+}
+
 func specsToColumns(specs []columnSpec) []table.Column {
 	cols := make([]table.Column, 0, len(specs))
 	for _, spec := range specs {

internal/app/types.go

@@ -27,6 +27,7 @@ const (
 	formAppliance
 	formServiceLog
 	formVendor
+	formDocument
 )
 
 type TabKind int
@@ -37,6 +38,7 @@ const (
 	tabMaintenance
 	tabAppliances
 	tabVendors
+	tabDocuments
 )
 
 func (k TabKind) String() string {
@@ -51,6 +53,8 @@ func (k TabKind) String() string {
 		return "Appliances"
 	case tabVendors:
 		return "Vendors"
+	case tabDocuments:
+		return "Documents"
 	default:
 		return "Unknown"
 	}