SPARK CHEATSHEET                                          lp CHEATSHEET.txt

THE AI
  spark chat [words]              one more turn, or a chat (/help for verbs)
  spark chat --thread N [words]   go on with an older thread (spark history)
  /resume [N]   /clear   /new     in the chat: an older thread, wipe, fresh
  spark <words>                   a streamed answer     spark last  the last
  spark do <words>                a task, one confirmed command at a time
  ?? words                        follow up on the last answer (same thread)
  ?? how do I change the theme    spark knows itself: it names its own verbs
  spark @FILE words               ask about a file (first 4 kB, last 12 kB)
  spark edit [?] words < FILE     rewrite / complete (--at N) / ask (?) stdin
  spark soul [edit|reset]         who it is: default soul, replace with edit
  spark remember WORDS            a fact it keeps    spark forget N  drops it
  spark memory [on|off|clear]     the facts it recalls on every answer
  spark ember [NAME|auto|none]    a second model for conversations (opt-in)
  spark history [clear]           the threads kept here; clear removes them
  spark                           status: brain, widget, server, soul, last

AT THE PROMPT
  ? words   or   words?   Enter   the command lands in your line, hint above
  Enter again                     runs it (! = read it first; it deletes)
  Esc s                           ask about the line you are on, no ?
  cmd 2>&1 | explain              what went wrong, and the fix
  spark off | spark on            silence / restore every pane at once
  spark <TAB>                     completes the verbs; second word too
                                  (theme and model names included, offline)

THE SERVER
  spark model [NAME|list]         the table (license, tested); choose one
  spark model budget [N]          percent of RAM+GPU auto may use (10-95)
  spark model add URL             add your own (--sha256, --license required)
  spark model verify              sha256 every downloaded file now, exit 1 bad
  spark serve | spark stop        one LAN address, token required; stop
  spark stop --force [--noreload] also the unit's server; and keep it down
  spark brain                     what answers now: a FORGE or a llama-server
  spark stats [--week]            tok/s, latency, cache hits, GPU, baseline
  spark bench [--tune]            llama-bench; --tune finds the best settings
  spark tune show | apply         the winner; apply writes spark.env, restarts
  spark forge [on|off]            the FORGE: the agent's API + page, on the LAN
  spark forge --print-client      what a peer needs: URL + a user minted here
  spark forge --print-url         the login URL; the admin token on a tty
  spark forge token --new         rotate the admin token; a user rotates
                                  their own: spark user token --new
  spark user [list]               the named users, each a sealed store
  spark user add NAME             mint an account; the token shows once
  spark user login [NAME] | logout  act as NAME here; forget the login
  spark user token --new          rotate your token; old logins die

THE PAGE (spark forge --print-url)  keys work when no input has focus
  1..5                            the tabs      r  refresh      ?  help
  /                               focus the input (Esc blurs it)
  Enter | Shift+Enter             send | a new line
  n                               a new thread  j / k  next / prev thread
  Esc                             stop the answer; else blur; else close
  share -> add to home screen     an app on iOS; a browser shortcut on Android

THE MACHINE
  spark setup                     first run: name, user, model, theme, light it
  spark check                     drift report; exit 0 = every promise kept
  spark check --watch 5           redraw every 5 s     --selftest  prove rows
  long output (help, check, lists) pages via $PAGER (less); piped stays plain
  spark shell [on|off]            spark's own shell: tmux, starship, micro ...
                                  on links the rc files (yours -> .bak)
  spark headless [on|off]         the FORGE up from boot, never asleep (brain)
  spark client [URL|off]          answer from another machine's FORGE; none here
  spark quiet                     the three states: start, login, boot
  spark quiet start on|off        no banner, one-line serve/forge + bare spark
  spark quiet login|boot on|off   Linux: motd + kernel line; GRUB's menu
  spark font FACE SIZE | list     console font (Linux) / Terminal.app's font
  spark ver                       logo, version, credits (the login greeting)
  spark update [--dry-run]        the newest tag; main pulls on a dev clone
  ./bootstrap.sh --dry-run        what a rebuild would change (never sudo)
  ./bootstrap.sh                  apply; converged = Nothing to do
  curl -fsSL .../spark/main/get | sh     update: pull, then spark setup again
  ~/.config/spark/site.env  name, user, model, ember, budget, shell, peer, theme
  ~/.config/spark/spark.env       ports, URLs, engine, history, memory, forge

THE SHELL (spark shell on)
  spark bar [on|off]              tmux's status line: bare shows, on|off sets
  spark theme NAME | list | show  one palette: console, tmux, micro; none=off
  tmux (prefix C-b)  c new window   n/p next/prev   | split right  - below
                     h j k l panes  d detach  r reload  [ scroll/copy (vi)
  z DIR (zoxide)   C-r history (fzf)   C-t files (fzf)   rg PATTERN
  fd NAME  eza -la  bat FILE  btop  micro FILE (C-s save, C-q quit)
  micro: Alt-s (Mac: Option-s)  Enter=complete  words=rewrite  ?=ask/review
         setlocal spark.about "a poem"   tell it, when it should not guess

LINUX
  systemctl --user status spark-serve spark-forge spark-check.timer
  journalctl --user -u spark-serve -n 50     (spark-forge likewise)
  ~/.local/state/spark/forge.log             the FORGE's own log (both OSes)
  fd/bat are fdfind/batcat on Debian; the shell layer's rc aliases them

MACOS
  launchctl print gui/$UID/spark.serve         is the agent loaded? (.forge too)
  launchctl kickstart -k gui/$UID/spark.serve  restart it
  spark headless on: both live in system/; restart and stop need sudo launchctl
  Alt is Option (spark's Terminal profile makes it Meta): Option-s, not Cmd-s