Docs: install separated from usage, 20+ real examples

README.md

@@ -50,37 +50,125 @@ it is small, private, and answers all 8 command questions in about 17 ms.
 | Size | 27B | 0.75B |
 | A question it was not trained on | answers it | rejects it |
 
-## Try it in one line
+## Ask it a question
+
+Every call has the same three parts: **the text to judge**, **the question id**, and
+**Knack's answer**. `echo` only hands the text to Knack. Nothing in the text is ever run,
+so you can safely ask about dangerous commands.
+
+```
+echo "<text to judge>" | ollama run devshub/knack --ask <question id>
+```
+
+For example, "will `npm run dev` keep running until I stop it?":
+
+```
+$ echo "npm run dev" | ollama run devshub/knack --ask serves
+yes  97%
+```
+
+### Questions about a shell command
+
+Will it keep running until stopped?
+
+```
+$ echo "python -m http.server 8000" | ollama run devshub/knack --ask serves
+yes  98%
+$ echo "pytest -q" | ollama run devshub/knack --ask serves
+no  97%
+```
+
+How dangerous is it?
+
+```
+$ echo "ls -la" | ollama run devshub/knack --ask risk --level safe --level "needs care" --level destructive
+safe  97%  0.0 / 2
+$ echo "npm install" | ollama run devshub/knack --ask risk --level safe --level "needs care" --level destructive
+needs care  96%  1.0 / 2
+$ echo "git push --force origin main" | ollama run devshub/knack --ask risk --level safe --level "needs care" --level destructive
+destructive  96%  1.9 / 2
+```
+
+Will it take minutes?
 
 ```
-echo "npm run dev" | ollama run devshub/knack --ask serves
+$ echo "cargo build --release" | ollama run devshub/knack --ask long_running
+yes  84%
+$ echo "git status" | ollama run devshub/knack --ask long_running
+no  97%
 ```
 
+What kind of command is it?
+
+```
+$ echo "pip install requests" | ollama run devshub/knack --ask activity \
+    --choice testing --choice building --choice installing --choice git --choice inspecting --choice running
+installing  94%
+$ echo "grep -rn TODO src" | ollama run devshub/knack --ask activity \
+    --choice testing --choice building --choice installing --choice git --choice inspecting --choice running
+inspecting  95%
 ```
+
+Does a pass prove the change works? Does it change git? Does it deploy?
+
+```
+$ echo "pytest tests/test_login.py" | ollama run devshub/knack --ask verifies
 yes  97%
+$ echo "npm run build" | ollama run devshub/knack --ask verifies
+no  96%
+$ echo "git commit -am 'fix login'" | ollama run devshub/knack --ask mutates_repo
+yes  96%
+$ echo "git diff" | ollama run devshub/knack --ask mutates_repo
+no  97%
+$ echo "kubectl apply -f k8s/" | ollama run devshub/knack --ask deploys
+yes  95%
+```
+
+### Questions about a message to a coding assistant
+
+What kind of task is this?
+
+```
+$ echo "fix the failing login test" | ollama run devshub/knack --ask task.intent \
+    --choice bug_fix --choice feature --choice refactor --choice api_schema --choice config_deploy \
+    --choice test --choice documentation --choice investigation --choice unknown
+bug_fix  90%
 ```
 
-`serves` asks whether the command keeps running until someone stops it (a dev server, a
-watcher, `tail -f`). Each id has one precise meaning, listed in the tables below. Read them
-before relying on an answer: `long_running`, for example, means "takes minutes", so a build
-counts.
+With the same `--choice` list: "add dark mode to the settings page" gives `feature  93%`,
+"write docs for the payments API" gives `documentation  97%`, and "why does the build take
+so long?" gives `investigation  97%`.
+
+Is it chat or a request for work?
 
-Knack only reads the text and judges it. Nothing is executed, so it is safe to ask about any
-command, including destructive ones.
+```
+$ echo "hi, how are you?" | ollama run devshub/knack --ask turn.chat_or_task --choice chat --choice task
+chat  98%
+$ echo "rename the user module" | ollama run devshub/knack --ask turn.chat_or_task --choice chat --choice task
+task  97%
+```
+
+Which assistant mode fits?
+
+```
+$ echo "what does this repo do?" | ollama run devshub/knack --ask route.mode --choice plan --choice build --choice ask --choice debug
+ask  96%
+$ echo "plan the migration to Postgres" | ollama run devshub/knack --ask route.mode --choice plan --choice build --choice ask --choice debug
+plan  90%
+```
 
-More examples:
+Start or stop a screen recording?
 
 ```
-echo "git push --force" | ollama run devshub/knack --ask risk --level safe --level "needs care" --level destructive
-echo "fix the failing login test" | ollama run devshub/knack --ask turn.new_task
-echo "fix the failing login test" | ollama run devshub/knack --ask task.intent \
-  --choice bug_fix --choice feature --choice refactor --choice api_schema --choice config_deploy \
-  --choice test --choice documentation --choice investigation --choice unknown
+$ echo "record my screen" | ollama run devshub/knack --ask turn.screencast --choice start --choice stop --choice none
+start  89%
 ```
 
-Ask with an id from the tables. Any other question is rejected rather than guessed. A choice
-or score question needs its options in the order shown; if they do not match, the error
-shows the exact flags to use.
+The answer is the option Knack picks and its confidence. Each id has one precise meaning,
+listed in the tables below; read them before relying on an answer. `long_running`, for
+example, means "takes minutes", so a build counts. Questions with options (`--choice`,
+`--level`) need them in the order shown; if they do not match, the error shows the exact
+flags to use. Any question that is not one of the 29 ids is rejected rather than guessed.
 
 ## API
 
@@ -197,7 +285,8 @@ defaults).
   refund requested?", is rejected. Use a general decision model like clef for those.
 - **Other input.** Logs, emails, tickets, documents or images give meaningless answers,
   even to these 29 questions.
-- **Conversation history.** Through Ollama it sees a single message. Inside CodeSync it also
+- **Conversation history.** Through Ollama it sees a single message, so a question like
+  `turn.resume` ("continue where you left off") answers no: there is nothing to resume. Inside CodeSync it also
   gets the session context, which makes the turn questions more reliable.
 - **Text generation.** It returns one pick with a confidence, never sentences.
 
@@ -210,10 +299,11 @@ Measured with the commands above, so you know where to double-check:
 | `tail -f app.log` | `serves` | no, 75% | yes |
 | `npm run build` | `serves` | yes, 79% | no |
 | `docker compose up` | `long_running` | 51% yes | yes |
+| `curl --fail http://localhost:3000/health` | `runtime_check` | no, 92% | yes |
 | `npm test` | `long_running` | 45% yes | unclear, depends on the suite |
 
-These come from the model, not the Ollama packaging (the original PyTorch model gives the
-same numbers), and are the next training targets.
+These come from the model's training, not the Ollama packaging: on every command compared,
+the Ollama build matches the original model to within 0.002. They are the next training targets.
 
 ## Results