From eab872d2ed02c655e97f8d27cad3f73c56f9f54f Mon Sep 17 00:00:00 2001
From: "J. Champagne" <jchampagne@maplegoosestudio.ca>
Date: Sat, 14 Mar 2026 14:52:23 -0400
Subject: [PATCH] doc: Remove ideas for full tabular data plans.

---
 docs/DESIGN.md  | 51 +++++++++++++++++++++++++++++++++++++++++--------
 docs/DEVPLAN.md | 25 +++++++++++++++---------
 2 files changed, 59 insertions(+), 17 deletions(-)

diff --git a/docs/DESIGN.md b/docs/DESIGN.md
index dbaf364..e18adee 100644
--- a/docs/DESIGN.md
+++ b/docs/DESIGN.md
@@ -60,9 +60,23 @@ selection. Useful for live preview pipelines.
 
 ### CSV / TSV
 
-`--input-format csv` or `--input-format tsv` parses columnar
-input. First row is headers, which become field names. Maps
-naturally to table/column display mode.
+`--input-format csv` or `--input-format tsv` parses delimited
+input. First row is always headers, which become field names.
+
+Each row becomes a JSON object. Known fields (`label`,
+`sublabel`, `icon`, `group`) are promoted to the top level.
+Everything else goes into a `meta` object. If no column
+matches the label key, the first column is used as `label`.
+
+```sh
+# CSV rows become normal Items, so filtering, hooks, and
+# multi-select all work unchanged.
+echo "name,age,city\nalice,30,toronto" | pikl --input-format csv
+```
+
+When `--input-format csv` or `tsv` is used without
+`--columns`, column config is auto-generated from the CSV
+headers.
 
 ## Event Hooks
 
@@ -441,11 +455,26 @@ pikl --format '{icon} {label} <dim>{sublabel}</dim>'
 ### Table / Column Mode
 
 ```sh
-pikl --columns label,meta.res,meta.size --column-separator ' │ '
+pikl --columns label,meta.res:Resolution,meta.size
 ```
 
-Auto-aligns columns. Sortable per-column with keybinds.
-CSV/TSV input maps naturally here.
+`--columns` takes a comma-separated list of field paths.
+Each column can have a display alias after a colon
+(`meta.res:Resolution`). Auto-aligns columns by computing
+widths from header names and cell values (capped at 60
+chars). Column widths are computed in core and included in
+`ViewState`, so the GUI frontend gets them for free.
+
+The header row renders bold/underlined with `│` separators.
+Item rows pad cells to column widths within the same `List`
+widget, so cursor/selection/visual-mode highlighting stays
+identical to the non-table path.
+
+When `--input-format csv` is used without `--columns`,
+columns are auto-generated from the CSV headers.
+
+**Future:** column sorting keybinds, cell/column selection,
+horizontal scrolling for wide tables.
 
 ### Preview Pane
 
@@ -757,8 +786,14 @@ find-walls --json | pikl \
   --on-cancel 'restore-wallpaper' \
   --on-hover-debounce 100
 
-# Process killer with table view
-ps aux --no-headers | pikl --input-format tsv --columns 1,10,2 --multi
+# CSV table view
+echo "name,age,city\nalice,30,toronto\nbob,25,vancouver" | pikl --input-format csv
+
+# CSV with column subset and aliases
+cat data.csv | pikl --input-format csv --columns "name,meta.age:Age"
+
+# TSV table view
+ps aux --no-headers | pikl --input-format tsv --multi
 
 # Drill-down file browser
 pikl --manifest ~/.config/pikl/filebrowser.toml --session filebrowser
diff --git a/docs/DEVPLAN.md b/docs/DEVPLAN.md
index f4d3550..15ae1a6 100644
--- a/docs/DEVPLAN.md
+++ b/docs/DEVPLAN.md
@@ -191,19 +191,26 @@ changes covers the register use case.
 **Done when:** `seq 1 20 | pikl --multi`, toggle a few items
 with Space, confirm, and all selected items appear on stdout.
 
-## Phase 5: Table Mode & CSV
+## Phase 5: Table Mode & CSV ✓
 
-Columnar data display.
+CSV/TSV input parsing and columnar table rendering.
 
 **Deliverables:**
-- `--columns` flag for table layout
-- Auto-alignment
-- Column sorting keybinds
-- `--input-format csv` and `--input-format tsv`
-- Column-specific filtering
+- `--input-format csv` and `--input-format tsv` for delimited input
+- `--columns` flag for table layout with optional aliases
+- Auto-generated column config from CSV headers
+- Column widths computed in core (GUI gets them for free)
+- Table header row with bold/underline styling
+- CSV rows become normal Items (JSON objects), so filtering,
+  field filters, hooks, multi-select, and output all work unchanged
 
-**Done when:** `ps aux | pikl --input-format tsv --columns 1,10,2`
-renders a clean table.
+**Deferred to future:**
+- Cell/column selection in table mode
+- Column sorting keybinds
+- Horizontal scrolling for wide tables
+
+**Done when:** `echo "name,age\nalice,30\nbob,25" | pikl --input-format csv`
+renders a navigable table with headers.
 
 ## Phase 6: Sessions & IPC