From 3dbaedc1da353f6e72c654af28b07a1cc50faae6 Mon Sep 17 00:00:00 2001
From: "claude@clouddev1" <claude-clouddev1@oliversturm.ch>
Date: Fri, 8 May 2026 14:51:15 +0000
Subject: [PATCH] help: surface ADR-0017/0018 auto-fill semantics (B1)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ADR-0017 added --force-conversion / --dont-convert as
opt-in flags on `change column`; the help text already
mentioned the flags but didn't explain when they apply.
ADR-0018 generalised serial beyond PK and added auto-fill
on `add column ... (serial|shortid)` for non-empty tables;
none of that was reflected in user-visible help.

This commit:

- Annotates the `add column` line with a continuation note
  that adding serial/shortid to a non-empty table
  auto-fills existing rows.
- Annotates the `change column` line with a continuation
  note that converting to serial/shortid auto-fills null
  cells.
- Appends an "Auto-generated types" section explaining
  serial and shortid: how they auto-fill, that they imply
  UNIQUE outside a PK (serial) or always (shortid), and
  that adding/converting-to either type on a non-empty
  table auto-fills existing/null cells.

The new test
`help_describes_auto_generated_type_behaviour` pins these
phrases so a future help-text edit can't silently drop the
pedagogical lines. The existing
`help_command_lists_supported_commands` and
`help_lists_export_and_import` tests still pass — they
only assert substring presence.

No engine vocabulary leaks (ADR-0002 posture preserved).
536 -> 537 passing, clippy clean.
---
 src/app.rs                              | 10 +++++++++
 tests/iteration4b_lifecycle_commands.rs | 30 +++++++++++++++++++++++++
 2 files changed, 40 insertions(+)

diff --git a/src/app.rs b/src/app.rs
index 733bc6b..68fdc85 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -1210,10 +1210,12 @@ impl App {
             "  create table <T> with pk [<col>:<type>...]",
             "  drop table <T>",
             "  add column [to] [table] <T>: <col> (<type>)",
+            "    (for serial/shortid on a non-empty table: existing rows auto-filled)",
             "  drop column [from] [table] <T>: <col>",
             "  rename column [in] [table] <T>: <old> to <new>",
             "  change column [in] [table] <T>: <col> (<newtype>)",
             "    [--force-conversion | --dont-convert]",
+            "    (to serial/shortid: null cells auto-filled with generated values)",
             "  add 1:n relationship [as <name>] from <P>.<col> to <C>.<col>",
             "    [on delete <action>] [on update <action>] [--create-fk]",
             "  drop relationship <name>",
@@ -1223,6 +1225,14 @@ impl App {
             "  show table <T>",
             "  show data <T>",
             "Types: text, int, real, decimal, bool, date, datetime, blob, serial, shortid",
+            "Auto-generated types (serial, shortid):",
+            "  serial   — integer that auto-fills with the next sequence value",
+            "             (MAX(col)+1) on insert. Outside a primary key it carries",
+            "             a UNIQUE contract.",
+            "  shortid  — short base58 identifier auto-filled at insert time. Always",
+            "             carries a UNIQUE contract.",
+            "  Adding or changing-to either type on a non-empty table auto-fills",
+            "  existing/null cells in the same operation.",
         ] {
             self.note_system(line);
         }
diff --git a/tests/iteration4b_lifecycle_commands.rs b/tests/iteration4b_lifecycle_commands.rs
index b5e7c88..6148cc3 100644
--- a/tests/iteration4b_lifecycle_commands.rs
+++ b/tests/iteration4b_lifecycle_commands.rs
@@ -67,6 +67,36 @@ fn help_command_lists_supported_commands() {
     }
 }
 
+#[test]
+fn help_describes_auto_generated_type_behaviour() {
+    // ADR-0017 / ADR-0018: the in-app help must surface the
+    // auto-fill contract for serial / shortid columns and the
+    // change-column conversion flags. Captured as a regression
+    // check so a future help-text edit doesn't silently drop the
+    // pedagogical lines.
+    let mut app = App::new();
+    type_str(&mut app, "help");
+    submit(&mut app);
+    let body = app
+        .output
+        .iter()
+        .map(|l| l.text.as_str())
+        .collect::<Vec<_>>()
+        .join("\n");
+    for keyword in [
+        "--force-conversion",
+        "--dont-convert",
+        "Auto-generated types",
+        "auto-filled",
+        "UNIQUE",
+    ] {
+        assert!(
+            body.contains(keyword),
+            "help output missing `{keyword}`:\n{body}",
+        );
+    }
+}
+
 #[test]
 fn save_on_temp_opens_path_entry_modal() {
     let mut app = App::new();