@thegitai/cli 1.0.0-preview.3 → 1.0.0-preview.31

package/README.md

@@ -1,8 +1,10 @@
-# TheGitAI
+# TheGitAI — AI coding agent for your terminal
 
-Interactive terminal coding agent. Talk to your repo in plain English — it reads
-your code, makes edits, runs the commands a task needs, and keeps long-running
-processes going while you work, all with your approval.
+TheGitAI is an AI coding agent for your terminal. It reads and searches your repository,
+writes and edits files, runs commands, and builds features with you.
+
+Talk to your repo in plain English. TheGitAI can keep long-running processes
+going while you work, all with your approval.
 
 ## Install
 
@@ -15,9 +17,9 @@ Requires Node.js 24 or newer.
 ## Usage
 
 ```text
-ai                  start an interactive session in the current repo
+ai                  sign in if needed, then start a session in the current repo
 ai "<request>"      start a session with <request> as the first message
-ai login            sign in via your browser (--no-browser for SSH/headless)
+ai login            the same as `ai`; kept for muscle memory
 ai whoami           show the signed-in account
 ai --usage          show account usage and reset times
 ai logout           sign out
@@ -26,6 +28,37 @@ ai --version        print the version and exit
 
 Run `ai --help` for sessions, modes, keys, and chat commands.
 
+Coding sessions require an interactive terminal on stdin and stdout. Piped
+one-shot prompts are not supported. Saved history is local to the repo and can
+always be viewed or resumed from that computer. Continuing it through the
+service requires the TheGitAI account used for that session. Local sessions can
+also be listed while signed out or offline.
+
+Signing in opens your browser. The same screen also prints a URL you can open on
+any other device and a box for an authorization code, so SSH and headless
+machines need no separate command: open the URL wherever you have a browser,
+choose "On another computer" on that page, and paste the code it shows.
+
+CLI login tokens use a rolling 48-hour inactivity timeout. If one expires during
+any server request, the CLI removes the expired credential and signs you in
+again on the next run.
+
+## Structured questions
+
+The agent can pause its current turn to ask up to four related questions in one
+form. Use **↑ / ↓**, the displayed option number, or **Enter** to choose, and
+**← / →** to move between questions. **Something else / add details** is the
+numbered final option; focus it and type, paste, or press **Enter** to add a
+single-line note. On single-select questions it is mutually exclusive with the
+listed choices, and **↑ / ↓** leaves its editor when the note is empty.
+Multi-select questions toggle choices. The last question has an explicit
+**Submit answers** row. **Esc** closes an open note first and otherwise cancels
+the form; **Ctrl+C** cancels the whole turn.
+
+Answers return to the same turn, and completed question/answer records remain
+readable when the session is resumed. Default, Auto-Accept, and Plan modes all
+support the form; Auto-Accept does not choose answers for you.
+
 ## Visible to-do list
 
 For larger multi-step tasks, the agent keeps a compact to-do list on screen so