deepshard · temp-deepshard · Jul 16, 2026
diff --git a/sdk/building-apps.mdx b/sdk/building-apps.mdx
@@ -48,7 +48,9 @@ from truffile.app_runtime import (
 )
 ```
 
-The source lives in `truffile/app_runtime/` in the repo and ships with the installed package. Once you `pip install truffile`, the same runtime is importable from app code running on your device.
+The runtime ships in the installed package. Truffile release builds stage it
+from Truffle's runtime source before packaging, so released wheels contain the
+complete app-authoring API used by generated apps.
 
 There are two other entry points that import the same names:
 
@@ -64,15 +66,14 @@ All three forms resolve to the same objects. Pick whichever reads best for you.
 The fastest way to start:
 
 ```bash
-truffile create my-app
+truffile create my-app --type foreground
 ```
 
 ```text
 ✓ Created app scaffold: ./my-app
   Files:
   → truffile.yaml
   → my_app_foreground.py
-  → my_app_background.py
   → icon.png
 
   Next: truffile validate ./my-app
@@ -82,9 +83,11 @@ Flags:
 
 - `truffile create <name>` — set the name, prompt for base path
 - `truffile create <name> --path <dir>` — set name and base path
+- `truffile create <name> --type foreground|background|hybrid` — choose the app shape
 - `truffile create` — fully interactive
 
-The generated `my_app_foreground.py` and `my_app_background.py` are stubs using the real SDK classes. Delete whichever you don't need — the app type is inferred from which `foreground` / `background` sections you keep in `truffile.yaml`.
+The default remains `hybrid`. When you pass `--type`, Truffile writes only the
+matching entrypoints, manifest sections, and copy-file steps.
 
 ---
 

diff --git a/sdk/cli.mdx b/sdk/cli.mdx
@@ -21,15 +21,18 @@ Most workflows can be driven with explicit arguments, which makes them easy to
 test in CI or from another agent:
 
 ```bash
-truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID"
-truffile list devices
+truffile connect truffle-6272 --user-id "$TRUFFLE_USER_ID" --json --non-interactive
+truffile list devices --json
 truffile list apps --json
-truffile load all
-truffile create my-app --path ./apps
-truffile validate ./apps/my-app
-truffile deploy ./apps/my-app --dry-run --json
+truffile load all --json
+truffile create my-app --type foreground --path ./apps --json --non-interactive
+truffile validate ./apps/my-app --json
+truffile deploy ./apps/my-app --dry-run --json --non-interactive
+# after the user approves deployment and replacing an installed copy
 truffile deploy ./apps/my-app --json --non-interactive --replace
-truffile delete my-app
+truffile delete my-app --dry-run --json --non-interactive
+# after the user confirms the exact deletion plan
+truffile delete my-app --yes --json --non-interactive
 truffile chat "Summarize my installed apps" --json --quiet --timeout 60
 truffile infer "Say pong" --json --no-stream --quiet
 truffile infer --list-models --json
@@ -237,7 +240,7 @@ truffile infer
 | `--model <name>` | Pre-select a model |
 | `--system <text>` | Set an initial system prompt |
 | `--no-stream` | Disable streaming (get the full response at once) |
-| `--no-tools` | Disable built-in tools (`web_search`, `web_fetch`) |
+| `--no-default-tools` | Disable built-in tools (`web_search`, `web_fetch`) |
 | `--mcp <url>` | Connect an MCP server at startup (can be repeated) |
 
 ```bash
@@ -393,10 +396,12 @@ truffile create
 truffile create my-app
 
 # in a specific directory
-truffile create my-app --path ./apps
+truffile create my-app --type foreground --path ./apps
 ```
 
-Creates a scaffold with `truffile.yaml`, foreground/background entry points, and a default icon.
+Use `--type foreground`, `--type background`, or `--type hybrid`. The default is
+`hybrid` for compatibility. The scaffold contains only the selected entrypoints,
+matching manifest sections, and a default icon.
 
 ### Validate an app
 
@@ -443,25 +448,24 @@ truffile list devices   # devices you have saved credentials for
 
 ### Delete apps
 
-```bash
-# interactive picker
-truffile delete
-
-# delete all apps
-truffile delete all
+For scripts and agents, identify an app by its stable name, slug, or UUID,
+preview the exact target, ask the user to confirm that plan, and only then pass
+`--yes`:
 
-# delete by index (1-based, as shown in the app list)
-truffile delete 1 2 3
-
-# comma-separated works too
-truffile delete 1,3,5
-
-# pipe selection
-echo "all" | truffile delete
-echo "1 2" | truffile delete
+```bash
+truffile list apps --json
+truffile delete my-app --dry-run --json --non-interactive
+# after the user confirms the exact app shown above
+truffile delete my-app --yes --json --non-interactive
 ```
 
-If you pass indices that are out of range or invalid, the CLI falls back to the interactive picker (when running in a terminal).
+For normal human use, `truffile delete` opens an interactive picker and asks
+for confirmation. Numeric indices and `all` remain available interactively,
+but automated workflows should use a stable name, slug, or UUID because list
+ordering can change.
+
+Non-interactive deletion without a selection or without `--yes` returns a
+structured error and does not mutate the device.
 
 ### List models
 
@@ -499,14 +503,15 @@ Both modes let you talk to models on your Truffle, but they serve different purp
 | `truffile scan` | Scan network for Truffle devices |
 | `truffile connect <device>` | Connect to a device |
 | `truffile disconnect [device\|all]` | Disconnect and clear credentials |
-| `truffile create [name] [--path <dir>]` | Scaffold a new app |
+| `truffile create [name] [--path <dir>] [--type foreground\|background\|hybrid]` | Scaffold a new app |
 | `truffile validate [path]` | Validate app config and sources |
 | `truffile deploy [path]` | Deploy app to connected device |
 | `truffile deploy --dry-run` | Show deploy plan without changes |
 | `truffile deploy --interactive` | Deploy with interactive terminal |
 | `truffile list apps` | List installed apps |
 | `truffile list devices` | List connected devices |
-| `truffile delete [all\|1 2 3]` | Delete apps (interactive, by index, or all) |
+| `truffile delete <name-or-uuid> --dry-run --json --non-interactive` | Preview an exact app deletion plan |
+| `truffile delete <name-or-uuid> --yes --json --non-interactive` | Delete an app after explicit confirmation |
 | `truffile models` | List models on connected device |
 | `truffile chat [--resume]` | Agent chat REPL |
 | `truffile infer [--model M] [--system S]` | Raw inference REPL |

diff --git a/sdk/inference.mdx b/sdk/inference.mdx
@@ -11,10 +11,27 @@ For the interactive CLI experience (`truffile infer`), see the [CLI guide](/sdk/
 
 ---
 
+## Find the device host
+
+Your computer must be able to reach the Truffle on the same network. Run:
+
+```bash
+truffile scan --json --non-interactive
+```
+
+Use an address returned in `devices[].addresses`, or use the device name as an
+mDNS host such as `truffle-1234.local`.
+
+```bash
+export TRUFFLE_HOST=truffle-1234.local
+```
+
+---
+
 ## List Models
 
 ```bash
-curl -sS http://<device-host>/if2/v1/models | python -m json.tool
+curl -sS "http://$TRUFFLE_HOST/if2/v1/models" | python -m json.tool
 ```
 
 Or via the CLI:
@@ -28,7 +45,7 @@ truffile models
 ## Chat Completions
 
 ```bash
-curl -sS http://<device-host>/if2/v1/chat/completions \
+curl -sS "http://$TRUFFLE_HOST/if2/v1/chat/completions" \
   -H "Content-Type: application/json" \
   -d '{
     "model": "<model-id-or-uuid>",
@@ -38,6 +55,38 @@ curl -sS http://<device-host>/if2/v1/chat/completions \
   }'
 ```
 
+### Python client
+
+`httpx` is installed with Truffile. This example lists the available models,
+uses the first returned model ID, and sends one non-streaming request:
+
+```python
+import os
+
+import httpx
+
+base_url = f"http://{os.environ['TRUFFLE_HOST']}/if2/v1"
+
+models_response = httpx.get(f"{base_url}/models", timeout=15)
+models_response.raise_for_status()
+models = models_response.json()["data"]
+if not models:
+    raise RuntimeError("No inference models are available on this Truffle")
+
+model = models[0].get("id") or models[0]["uuid"]
+response = httpx.post(
+    f"{base_url}/chat/completions",
+    json={
+        "model": model,
+        "messages": [{"role": "user", "content": "Reply with pong."}],
+        "stream": False,
+    },
+    timeout=120,
+)
+response.raise_for_status()
+print(response.json()["choices"][0]["message"]["content"])
+```
+
 ### Request body
 
 | Field | Type | Description |

diff --git a/sdk/installation.mdx b/sdk/installation.mdx
@@ -6,8 +6,8 @@ description: "Install the Truffile SDK to chat with and deploy apps to your Truf
 ## Prerequisites
 
 - Python 3.12 or higher
-- A Truffle¹ device
-- The [Symphony desktop client](/client/overview), with your device already onboarded
+- A Truffle¹ device when you are ready to connect, chat, run inference, or deploy
+- The [Symphony desktop client](/client/overview), with your device onboarded before connecting
 
 ## Agent setup prompt
 
@@ -20,11 +20,10 @@ Use explicit CLI commands and explain what you are doing as you go.
 
 Requirements:
 - Make sure Python 3.12 or newer is available. Prefer `python3.12` when present; otherwise use the newest `python3`/`python` that is >=3.12.
-- Prefer `uv` if it is installed. If `uv` is not installed, use the standard library `venv` module.
-- Create a local virtual environment named `.venv`.
-- Activate/use that virtual environment for all Python and pip commands.
-- Install Truffile with `pip install truffile`; if it is already installed, make sure it is upgraded to the latest version.
-- Verify the install with `truffile --help`.
+- If `uv` is installed, create `.venv` with `uv venv --python 3.12 .venv` and install with `uv pip install --python .venv/bin/python --upgrade truffile`.
+- Otherwise create `.venv` with the standard library and install with `.venv/bin/python -m pip install --upgrade pip truffile`.
+- Use `.venv/bin/python` and `.venv/bin/truffile` for all Python and Truffile commands.
+- Verify the install with `.venv/bin/truffile --help`.
 - Run `truffile load all` so the bundled skills and example apps are copied into this workspace under `./truffile/skills` and `./truffile/examples`.
 - Do not require a Truffle device to finish setup. If no device is connected yet, tell me that I first need to onboard my Truffle through the Symphony desktop client at https://docs.truffle.net/client/overview, then get my User ID from Symphony > Settings, then run `truffile scan` and `truffile connect <device-name> --user-id <user-id>`. During `truffile connect`, I must approve the new session on my Truffle device.
 
@@ -63,7 +62,7 @@ The prompt works because Truffile is CLI-first: every core workflow has explicit
 
     Verify:
     ```bash
-    python3 --version
+    python3.12 --version
     ```
   </Tab>
   <Tab title="Windows">
@@ -86,63 +85,70 @@ The prompt works because Truffile is CLI-first: every core workflow has explicit
 
     Verify:
     ```bash
-    python3 --version
+    python3.12 --version
     ```
   </Tab>
 </Tabs>
 
-## Set up a virtual environment
+## Create the virtual environment and install Truffile
+
+Use uv when it is available. Both paths below call the environment directly, so
+they do not depend on shell activation.
 
 <Tabs>
-  <Tab title="venv">
+  <Tab title="uv">
+    macOS / Linux:
+
     ```bash
-    python3 -m venv .venv
+    uv venv --python 3.12 .venv
+    uv pip install --python .venv/bin/python --upgrade truffile
     ```
 
-    <Tabs>
-      <Tab title="macOS / Linux">
-        ```bash
-        source .venv/bin/activate
-        ```
-      </Tab>
-      <Tab title="Windows">
-        ```powershell
-        .venv\Scripts\Activate.ps1
-        ```
-      </Tab>
-    </Tabs>
+    Windows PowerShell:
+
+    ```powershell
+    uv venv --python 3.12 .venv
+    uv pip install --python .venv\Scripts\python.exe --upgrade truffile
+    ```
   </Tab>
-  <Tab title="uv">
-    If you prefer [uv](https://github.com/astral-sh/uv) for faster package management:
+  <Tab title="venv">
+    macOS / Linux:
 
     ```bash
-    # install uv if you don't have it
-    curl -LsSf https://astral.sh/uv/install.sh | sh
-
-    # create and activate a venv
-    uv venv
-    source .venv/bin/activate   # macOS / Linux
-    # or
-    .venv\Scripts\Activate.ps1  # Windows
+    python3.12 -m venv .venv
+    .venv/bin/python -m pip install --upgrade pip truffile
+    ```
+
+    Windows PowerShell:
+
+    ```powershell
+    py -3.12 -m venv .venv
+    .venv\Scripts\python.exe -m pip install --upgrade pip truffile
     ```
   </Tab>
 </Tabs>
 
-## Install Truffile
+## Verify the installation
 
-With your environment activated:
+macOS / Linux:
 
 ```bash
-pip install truffile
+.venv/bin/truffile --version
+.venv/bin/truffile help
+.venv/bin/truffile load all --json
+.venv/bin/truffile doctor --json
 ```
 
-Verify the installation:
+Windows PowerShell:
 
-```bash
-truffile help
+```powershell
+.venv\Scripts\truffile.exe --version
+.venv\Scripts\truffile.exe help
+.venv\Scripts\truffile.exe load all --json
+.venv\Scripts\truffile.exe doctor --json
 ```
 
-You should see the Truffile welcome panel listing every command (`scan`, `connect`, `deploy`, `chat`, `infer`, and the rest). If you see the panel, you're ready to go.
+`truffile doctor --json` may report `device_required` after a successful local installation. That means the CLI is ready, but a Truffle has not been paired in this environment yet.
 
 <Note>
 Before connecting from Truffile, onboard your device through the Symphony desktop client. Download Symphony from [the client overview](/client/overview), complete device onboarding, then copy your User ID from **Symphony → Settings**. `truffile connect` will ask for that User ID and then you must approve the new session on your Truffle device.