Explain settings and Lisp prompt usage in startup tips

Author: luciusmagn

src/application/commands.lisp

@@ -2237,7 +2237,7 @@ are forwarded to TERMINAL-UI-SELECT."
     (:name "/model"
      :argument "[MODEL]"
      :description "pick a registered provider model and reasoning effort"
-     :tip "changes both the model and its reasoning effort."
+     :tip "selects the provider/model used for replies and then its reasoning effort; the choice is saved for future sessions."
      :busy-behavior :apply
      :terminal-behavior :exclusive
      :callable t)
@@ -2279,7 +2279,7 @@ are forwarded to TERMINAL-UI-SELECT."
     (:name "/effort"
      :argument "[LEVEL]"
      :description "pick the reasoning effort"
-     :tip "changes reasoning effort without switching models."
+     :tip "sets the model's reasoning budget without changing models. Higher levels allow more reasoning and can take longer; available levels depend on the model."
      :busy-behavior :apply
      :terminal-behavior :exclusive-without-arguments
      :callable t)
@@ -2301,7 +2301,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-fast-command
     (:name "/fast"
      :description "show or change Codex Fast mode"
-     :tip "uses service_tier=priority at 2x plan usage for future Codex requests."
+     :tip "sets Codex Fast mode: (fast \"on\") requests priority service at 2x plan usage; (fast \"off\") requests normal service."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2313,7 +2313,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-trace-command
     (:name "/trace"
      :description "show visible reasoning summaries"
-     :tip "toggles visible reasoning summaries with on or off."
+     :tip "controls visible reasoning summaries: (trace \"on\") shows them, (trace \"off\") hides them. Use (effort) to change the reasoning budget."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2325,7 +2325,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-turn-timestamps-command
     (:name "/timestamps"
      :description "show local timestamps beside user and assistant turns"
-     :tip "toggles dim local timestamps beside user and assistant turns."
+     :tip "controls local-time labels beside user and assistant turns: (timestamps \"on\") shows them, (timestamps \"off\") hides them."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2337,7 +2337,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-simple-technical-english-command
     (:name "/ste"
      :description "use Simple Technical English for replies"
-     :tip "toggles short, direct Simple Technical English replies."
+     :tip "sets reply style: (ste \"on\") requests short, direct Simple Technical English; (ste \"off\") removes that style instruction."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2349,7 +2349,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-session-titles-command
     (:name "/titles"
      :description "allow provider-generated session-title refreshes"
-     :tip "toggles automatic provider-generated session-title refreshes."
+     :tip "controls session naming: (titles \"on\") allows provider-generated title refreshes; (titles \"off\") uses locally derived titles."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2361,7 +2361,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-cache-misses-command
     (:name "/cache-misses"
      :description "notify when a request re-reads uncached context"
-     :tip "reports prompt-cache misses and their likely cause after each affected request."
+     :tip "controls cache diagnostics: (cache-misses \"on\") reports uncached context and likely causes; (cache-misses \"off\") hides these notices."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2373,7 +2373,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-hurry-up-command
     (:name "/hurry-up"
      :description "show or change hurry-up mode"
-     :tip "enables direct execution and admits at most two child agents."
+     :tip "sets execution style: (hurry-up \"on\") favors direct work and limits delegation to two child agents; (hurry-up \"off\") uses normal delegation limits."
      :busy-behavior :apply
      :terminal-behavior :shared
      :callable t
@@ -2385,7 +2385,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-permissions-command
     (:name "/permissions"
      :description "choose command access for this session"
-     :tip "chooses how shell commands are authorized, including autonomous auto mode."
+     :tip "sets command authorization: ask prompts for approval, auto authorizes autonomously, sandbox confines commands, and full grants session-wide host access."
      :busy-behavior :apply
      :terminal-behavior :exclusive-without-arguments
      :callable t
@@ -2649,7 +2649,7 @@ are forwarded to TERMINAL-UI-SELECT."
 (define-application-command application--builtin-compact-command
     (:name "/compact"
      :description "compact context now; on/off selects tool detail presentation"
-     :tip "compacts context without an argument, waiting until an active turn finishes."
+     :tip "with no argument compacts conversation context. (compact \"on\") collapses tool details; (compact \"off\") shows expanded details."
      :busy-behavior :hold
      :terminal-behavior :shared
      :callable t

src/startup/main.lisp

@@ -130,26 +130,43 @@
          append (application--banner-terminate-row
                  (terminal--clip-spans metadata-row columns)))))
 
-(-> application--startup-command-entry () application-command)
-(defun application--startup-command-entry ()
-  "Return one command entry selected for the startup banner."
-  (let ((commands (application-command-list)))
-    (nth (random (length commands) (make-random-state t))
-         commands)))
+(defparameter *application-startup-tips*
+  '(((:plain "The prompt is a Lisp REPL, you can use it to evaluate arbitrary Common Lisp."))
+    ((:plain "The tools available to the model are callable functions in the prompt, try for instance ")
+     (:code "(search.files :query \"README\")")
+     (:plain " to fuzzy-search workspace file paths with fff."))
+    ((:code "AUTOLITH_WEB_SEARCH")
+     (:plain " selects provider web search: disabled turns it off, cached uses indexed results, and live fetches fresh results where supported."))
+    ((:code "autolith --fullscreen")
+     (:plain " uses a scrollable transcript and bottom-pinned composer. Save the choice for future launches with ")
+     (:code "(preferences-set-fullscreen (application-configuration *active-application*) t)")
+     (:plain "; nil restores the inline default.")))
+  "Startup advice supplementing registered command tips, as styled span specifications.")
 
 (-> application--command-tip-spans
     (application-command)
     terminal-styled-text)
 (defun application--command-tip-spans (entry)
   "Return a startup tip with ENTRY's canonical Lisp call styled as code."
-  (list (terminal-span :plain (format nil "~2%"))
-        (terminal-span :dim "Tip: ")
+  (list (terminal-span ':dim "Tip: ")
         (terminal-span
          :code
          (format nil "(~A)" (application-operation--command-name entry)))
         (terminal-span :plain
                        (format nil " ~A" (application-command-tip entry)))))
 
+(-> application--startup-tip-spans () terminal-styled-text)
+(defun application--startup-tip-spans ()
+  "Choose command or general advice without consuming the saved image's random state."
+  (let* ((commands (application-command-list))
+         (index (random (+ (length commands) (length *application-startup-tips*))
+                        (make-random-state t))))
+    (if (< index (length commands))
+        (application--command-tip-spans (nth index commands))
+        (cons (terminal-span ':dim "Tip: ")
+              (loop for (style text) in (nth (- index (length commands)) *application-startup-tips*)
+                    collect (terminal-span style text))))))
+
 (-> application-banner (application) list)
 (defun application-banner (application)
   "Return APPLICATION's identity, session metadata, security notice, and tip."
@@ -178,8 +195,8 @@
        :notice
        (format nil "~%Autolith executes model-generated code with your user ~
                     privileges.~%Sandboxing is no substitute for human oversight")))
-     (application--command-tip-spans
-      (application--startup-command-entry)))))
+     (list (terminal-span ':plain (format nil "~2%")))
+     (application--startup-tip-spans))))
 
 (-> application--update-notice (application) (option list))
 (defun application--update-notice (application)

src/terminal/boot-screen.lisp

@@ -49,10 +49,22 @@
 
 (-> terminal-ui--welcome-rows (terminal-ui integer) list)
 (defun terminal-ui--welcome-rows (ui height)
-  "Return the empty session's machine console above its pinned composer."
-  (nth-value 0 (terminal-ui--boot-screen-frame
-                ui :phase ':listener-ready
-                :detail "Type a request. Use (login) to connect a provider." :height height)))
+  "Center the machine console and one stable, wrapped tip above the composer."
+  (let* ((columns (max 1 (terminal-columns (terminal-ui-terminal ui))))
+         (width (min 64 (max 1 (- columns 4))))
+         (left (make-string (floor (- columns width) 2) :initial-element #\Space))
+         (tip (or (fullscreen-terminal-ui-welcome-tip ui)
+                  (setf (fullscreen-terminal-ui-welcome-tip ui)
+                        (application--startup-tip-spans))))
+         (tip-rows (terminal-ui-fullscreen--display-rows ui (list tip) width))
+         (panel (mapcar (lambda (row) (terminal--render-spans (terminal-ui-terminal ui) row))
+                        (terminal-ui--boot-screen-panel
+                         ':listener-ready "Type a request. Use (login) to connect a provider." columns)))
+         (rows (append panel (list "")
+                       (mapcar (lambda (row) (concatenate 'string left row)) tip-rows)))
+         (visible (subseq rows 0 (min (length rows) (max 0 height))))
+         (top (max 0 (floor (- height (length visible)) 2))))
+    (append (make-list top :initial-element "") visible)))
 
 (-> terminal-ui-boot-screen
     (terminal-ui (or string symbol) &optional (option string)) null)

src/terminal/fullscreen.lisp

@@ -34,6 +34,8 @@
                 :documentation "Width of the last successfully painted frame.")
    (cursor-visible-p :initform t :accessor fullscreen-terminal-ui-cursor-visible-p
                      :type boolean :documentation "Requested composer cursor visibility.")
+   (welcome-tip :initform nil :accessor fullscreen-terminal-ui-welcome-tip
+                :documentation "Startup advice retained across welcome repaints and resize.")
    (welcome-p :initform nil :accessor terminal-ui-fullscreen-welcome-p :type boolean
               :documentation "Whether the empty session shows the machine console panel."))
   (:documentation "An alternate-screen transcript viewport and bottom-pinned composer."))

tests/application-tests.lisp

@@ -387,9 +387,9 @@
    "quit aliases inherit the command's cancellation policy")
   (let* ((*random-state* (make-random-state nil))
          (captured-state (make-random-state *random-state*))
-         (entry (application--startup-command-entry)))
-    (test-assert (member entry (application-command-list) :test #'eq)
-                 "startup tip selection returns one canonical command")
+         (tip (application--startup-tip-spans)))
+    (test-assert (typep tip 'terminal-styled-text)
+                 "startup selection returns styled command or general advice")
     (test-assert (equalp *random-state* captured-state)
                  "startup tip selection does not consume saved image RNG state"))
   nil)

tests/fullscreen-boot-tests.lisp

@@ -16,9 +16,22 @@
           (test-assert (<= (abs (- first-row (- 23 last-row))) 1) "panel is vertically centered")
           (test-assert (= left (floor (- 80 64) 2)) "panel is horizontally centered")
           (test-assert (> cursor last-row) "provider prompts start below the panel")))
+      (terminal-ui--welcome-rows ui 21)
+      (let ((tip (fullscreen-terminal-ui-welcome-tip ui)))
+        (terminal-ui--welcome-rows ui 21)
+        (test-assert (eq tip (fullscreen-terminal-ui-welcome-tip ui))
+                     "welcome repaints retain the selected advice"))
+      (setf (fullscreen-terminal-ui-welcome-tip ui)
+            (list (terminal-span ':plain
+                                 (apply #'concatenate 'string
+                                        (make-list 20 :initial-element "wrapped advice ")))))
       (dolist (columns '(1 2 12 24 80))
         (dolist (height '(1 2 7 24))
           (terminal-set-dimensions terminal columns :rows height)
+          (let ((welcome (terminal-ui--welcome-rows ui height)))
+            (test-assert (<= (length welcome) height) "welcome advice fits the viewport height")
+            (test-assert (every (lambda (row) (<= (clinedi:ansi-display-width row) columns)) welcome)
+                         "welcome advice reflows within the viewport width"))
           (multiple-value-bind (frame cursor)
               (terminal-ui--boot-screen-frame ui :phase ':login :detail "detail" :height height)
             (test-assert (<= (length frame) height) "panel height is bounded")