Update public/index.html

public/index.html

@@ -187,6 +187,130 @@ python3 client.py
     </div>
   </section>
 
+  <!-- TUTORIAL -->
+  <section class="grid-1">
+    <div class="card">
+      <h3>Tutorial: Plan → Review → Execute (client-side)</h3>
+
+      <p class="muted">
+        Axis client asks the server to <b>plan</b>, then lets you <b>review</b> and <b>run locally</b>.
+        The server never executes shell commands; the client does (with danger checks).
+      </p>
+
+      <ol style="margin: 0 0 10px 18px;">
+        <li><b>Launch the client</b> (sets/reads your API key, pings the server):
+          <pre><button class="copy" aria-label="Copy">Copy</button><code>
+python3 client.py --server https://tandevllc-axis.hf.space
+# (or export LLAMA_SERVER and just run `python3 client.py`)
+          </code></pre>
+        </li>
+
+        <li><b>Type what you want</b> in natural language (e.g. “create a Flask hello-world app and run it”).  
+            The client calls <code>/infer</code> and shows a planned JSON with steps.</li>
+
+        <li><b>Review the plan</b> in a Rich table and pick:
+          <ul class="check" style="margin-top:6px">
+            <li><b>[a]</b> Execute all — runs steps locally in order</li>
+            <li><b>[s]</b> Step-by-step — confirm/edit/skip each step</li>
+            <li><b>[e]</b> Edit plan — opens JSON in <code>$EDITOR</code> before running</li>
+            <li><b>[d]</b> Toggle dry-run — preview only (no changes)</li>
+            <li><b>[c]</b> Cancel</li>
+          </ul>
+        </li>
+
+        <li><b>Danger gate</b> for risky shell commands (e.g., <code>rm -rf /</code>, <code>curl | sh</code>, <code>mkfs.*</code>):  
+            you’ll be asked to type <code>proceed</code> to continue. This is client-side safety.</li>
+
+        <li><b>See results</b> for every step with pretty panels (stdout/stderr, bytes written, file previews, etc.).  
+            All transcripts & artifacts are saved under:
+          <pre><button class="copy" aria-label="Copy">Copy</button><code>
+~/.llama3_agent/sessions/<timestamp>/
+          </code></pre>
+        </li>
+      </ol>
+
+      <p class="muted" style="margin-top:8px">
+        <b>Meta commands</b> (type at the client prompt, start with a colon):
+      </p>
+      <pre><button class="copy" aria-label="Copy">Copy</button><code>
+:server                 # show current server
+:server https://...     # change server
+:apikey set             # save/replace API key into ./client/key.json
+:apikey clear           # delete saved key (will prompt next run)
+:history                # list recent sessions
+:open <path>            # open file in a pager
+:clear                  # clear screen
+:help                   # help
+      </code></pre>
+
+      <p class="muted" style="margin-top:8px">
+        <b>Tips</b>: Works great with Llama-3 8B; TinyLlama on HF is fine for lightweight tasks. You can write long-form content,
+        scaffold apps (Flask, etc.), generate files/trees, and manipulate your local filesystem safely.
+      </p>
+    </div>
+
+    <div class="card">
+      <h3>Step Types Reference (what the plan can do)</h3>
+      <p class="muted">Here’s what the client understands and how each step behaves locally.</p>
+
+      <ul class="check">
+        <li><code>shell</code> — run a shell command (OS-aware). Danger-checked before execution.</li>
+        <li><code>read_file</code> — print a file’s content with syntax highlighting.</li>
+        <li><code>write_file</code> / <code>edit_file</code> / <code>append_file</code> — create/modify files (UTF-8).</li>
+        <li><code>rewrite_file</code> — sends current file + instruction to server to rewrite, then saves locally.</li>
+        <li><code>mkdirs</code> — create one or more directories (parents OK).</li>
+        <li><code>generate_file</code> — ask the model to generate content and save it.</li>
+        <li><code>generate_tree</code> — generate multiple files (each via <code>/gen</code>) into a project structure.</li>
+        <li><code>generate_large_file</code> — build a big file from multiple generated chunks.</li>
+        <li><code>python</code> — run a small Python snippet locally and capture stdout.</li>
+        <li><code>respond</code> / <code>respond_llm</code> — show text to you (LLM-assisted for the latter).</li>
+        <li><code>fs</code> — filesystem helpers:
+          <code>list</code>, <code>read</code>, <code>write</code>, <code>append</code>, <code>mkdir</code>,
+          <code>remove</code> (non-recursive), <code>move</code>, <code>copy</code>, <code>exists</code>, <code>glob</code>.
+        </li>
+      </ul>
+
+      <p class="muted" style="margin-top:8px"><b>Examples</b></p>
+
+      <pre><button class="copy" aria-label="Copy">Copy</button><code># Ask: “Make me a Flask hello-world app and run it on port 5001.”
+# Typical planned steps might include:
+{
+  "steps": [
+    {"type":"mkdirs","paths":["app"]},
+    {"type":"write_file","path":"app/app.py","content":"from flask import Flask\napp=Flask(__name__)\n@app.get('/')\ndef hi():\n  return 'hi'\n\nif __name__=='__main__':\n  app.run(port=5001)"},
+    {"type":"shell","cmd":{"unix":"python3 -m pip install flask","windows":"py -m pip install flask"}},
+    {"type":"shell","cmd":{"unix":"python3 app/app.py","windows":"py app/app.py"}}
+  ]
+}
+      </code></pre>
+
+      <pre><button class="copy" aria-label="Copy">Copy</button><code># Ask: “Draft a 700-word article on RAG for cybersecurity and save to docs/rag.md.”
+{
+  "steps": [
+    {"type":"mkdirs","paths":["docs"]},
+    {"type":"generate_file","format":"markdown","instruction":"700-word article on RAG for cybersecurity, well-structured with headings and bullets","length":"long","path":"docs/rag.md"},
+    {"type":"read_file","path":"docs/rag.md"}
+  ]
+}
+      </code></pre>
+
+      <pre><button class="copy" aria-label="Copy">Copy</button><code># Ask: “Scan my project folder and list all Python files; show me if README exists.”
+{
+  "steps": [
+    {"type":"fs","op":"glob","pattern":"**/*.py"},
+    {"type":"fs","op":"exists","path":"README.md"}
+  ]
+}
+      </code></pre>
+
+      <p class="muted" style="margin-top:8px">
+        <b>Notes</b>: <code>remove</code> is non-recursive on purpose; dangerous recursive deletes will trigger the danger gate.
+        Shell commands are executed with <code>subprocess.run(..., shell=True)</code> locally, with captured stdout/stderr and return code panels.
+      </p>
+    </div>
+  </section>
+
+
   <footer>
     <p>Axis · Agent — Client delivery by TanDev. Status: <a href="/status">/status</a></p>
   </footer>