From b5a6d58b0868864c2181f358bc9e0ee07c592585 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 10:12:39 +0000 Subject: [PATCH 1/6] Document onboarding notifications toggle and menu-extra memory section - Add the 'Allow notifications' toggle to the onboarding options list (PicoServer onboarding Customize page). - Describe the menu extra's Memory section: the Apps/MLX/Free bar and legend, the memory Pressure indicator, and the GB/% legend toggle (PicoServer #37). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Mvyyqz4fzYoDdkYE8qLgNi --- .../getting-started/install-and-run-pico-ai-server.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md index f2c30dd..c850586 100644 --- a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md +++ b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md @@ -11,7 +11,7 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX 1. Launch Pico AI Server. 2. Complete the first-run flow. - The onboarding flow can set `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. + The onboarding flow can set `Allow notifications`, `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. 3. Open the WebUI at `http://127.0.0.1:11434/`. The onboarding flow normally opens this address for you after setup. 4. If you want LAN access, leave `Allow local network connections` on. @@ -20,6 +20,7 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX With that setting off, Pico AI Server binds to `127.0.0.1`. 6. Use the menu extra when you need quick control. When the server is running, it shows the status, a `Start` or `Stop` button, and an IP-based server address with a copy button. + The `Memory` section breaks down memory use across `Apps`, `MLX`, and `Free` with a bar and legend, and shows a memory `Pressure` indicator. Use the `GB`/`%` button in the `Memory` header to switch the legend between gigabytes and percentages. ## Verify it worked From 410fb4dc5c680df506b7df7346d212479d76d5a3 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 21 Jul 2026 10:14:43 +0000 Subject: [PATCH 2/6] Refine phrasing per automated review - 'can set' -> 'lets you configure' (onboarding toggles are user choices) - 'memory use' -> 'memory usage'; 'switch' -> 'toggle' for the GB/% control Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01Mvyyqz4fzYoDdkYE8qLgNi --- .../getting-started/install-and-run-pico-ai-server.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md index c850586..d48401a 100644 --- a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md +++ b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md @@ -11,7 +11,7 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX 1. Launch Pico AI Server. 2. Complete the first-run flow. - The onboarding flow can set `Allow notifications`, `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. + The onboarding flow lets you configure `Allow notifications`, `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. 3. Open the WebUI at `http://127.0.0.1:11434/`. The onboarding flow normally opens this address for you after setup. 4. If you want LAN access, leave `Allow local network connections` on. @@ -20,7 +20,7 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX With that setting off, Pico AI Server binds to `127.0.0.1`. 6. Use the menu extra when you need quick control. When the server is running, it shows the status, a `Start` or `Stop` button, and an IP-based server address with a copy button. - The `Memory` section breaks down memory use across `Apps`, `MLX`, and `Free` with a bar and legend, and shows a memory `Pressure` indicator. Use the `GB`/`%` button in the `Memory` header to switch the legend between gigabytes and percentages. + The `Memory` section breaks down memory usage across `Apps`, `MLX`, and `Free` with a bar and legend, and shows a memory `Pressure` indicator. Use the `GB`/`%` button in the `Memory` header to toggle the legend between gigabytes and percentages. ## Verify it worked From d7a6b835604db729ba2422b836930ac94f51b52b Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 10:15:17 +0000 Subject: [PATCH 3/6] Update onboarding docs for redesigned four-page setup wizard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PicoServer's first-run flow was rebuilt (PRs #35, #36, #38, #42) into a four-page wizard — Welcome, Model, Access, Ready — and the old Customize page (notifications, open-at-login, prevent-sleep toggles) was removed. - Fix the now-stale onboarding line in Install and Run: the first-run flow no longer configures notifications, open-at-login, or prevent-sleep. - Add a First-Run Setup walkthrough page covering all four wizard pages, including RAM-based model tier selection (Fast / Balanced / Reasoning) and the This-Mac-only vs local-network access choice with Bonjour. - Document Open at Login and Prevent automatic sleep in Configure Settings, where they now live after moving out of onboarding. - Wire the new page into the sidebar and renumber Getting Started siblings. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01D8KgyxEFCWzt6ebEC7SKng --- .../getting-started/configure-settings.md | 6 +- .../getting-started/connect-a-client.md | 2 +- .../getting-started/first-run-setup.md | 61 +++++++++++++++++++ .../install-and-run-pico-ai-server.md | 6 +- sidebars.ts | 1 + 5 files changed, 70 insertions(+), 6 deletions(-) create mode 100644 docs/user-guide/getting-started/first-run-setup.md diff --git a/docs/user-guide/getting-started/configure-settings.md b/docs/user-guide/getting-started/configure-settings.md index 5ca88d7..a8f470e 100644 --- a/docs/user-guide/getting-started/configure-settings.md +++ b/docs/user-guide/getting-started/configure-settings.md @@ -1,6 +1,6 @@ --- title: Configure Settings -sidebar_position: 2 +sidebar_position: 3 --- Use this page to set the storage location, network behavior, and browser-chat defaults. Keep the changes small, apply them, and prove the server still responds before you move on. @@ -22,7 +22,9 @@ Before you start, open the native Pico AI Server app and keep a terminal ready s - `Port` - `Allow Cross-Origin Resource Sharing (CORS)` - `Enable Bonjour broadcasting` -6. Click `Apply Changes` after network or port changes. +6. In `Server Mode`, set `Open at Login` and `Prevent automatic sleep while Pico is running` if you want. + These two options are configured here rather than during first-run setup. `Open at Login` starts Pico when you log in; `Prevent automatic sleep while Pico is running` keeps the Mac awake so the server stays reachable. +7. Click `Apply Changes` after network or port changes. The app saves the configuration and restarts the server. ## Verify it worked diff --git a/docs/user-guide/getting-started/connect-a-client.md b/docs/user-guide/getting-started/connect-a-client.md index b33b944..a243307 100644 --- a/docs/user-guide/getting-started/connect-a-client.md +++ b/docs/user-guide/getting-started/connect-a-client.md @@ -1,6 +1,6 @@ --- title: Connect a Client -sidebar_position: 3 +sidebar_position: 4 --- Use this page when another app needs to talk to Pico AI Server. The job is to copy the right server address, choose the correct compatibility layer, and prove the client can list models before you try chat. diff --git a/docs/user-guide/getting-started/first-run-setup.md b/docs/user-guide/getting-started/first-run-setup.md new file mode 100644 index 0000000..dfec307 --- /dev/null +++ b/docs/user-guide/getting-started/first-run-setup.md @@ -0,0 +1,61 @@ +--- +title: First-Run Setup +sidebar_position: 2 +--- + +The first time you launch Pico AI Server, a setup wizard walks you through four pages — **Welcome**, **Model**, **Access**, and **Ready**. By the end you have a model downloading (or ready), you have chosen who can reach the server, and the server is running. This page explains each page so you know what every choice does. + +You can change every choice later in the app's Settings window, so pick sensible defaults now and move on. + +## Walk through the wizard + +1. Launch Pico AI Server. +2. On the **Welcome** page, review the summary and continue. + This page introduces Pico AI Server and links to the privacy policy and terms. +3. On the **Model** page ("Choose your first model"), pick a model, then continue. + - Pico shows a short list of options — such as **Fast**, **Balanced**, and **Reasoning** — sized for your Mac's memory. + - One option is preselected and marked **Recommended** for this Mac; the page subtitle names it (for example, "Balanced is recommended for this Mac. You can add or switch models later."). + - Each row shows the model name and its total download size. + - The continue button reflects your choice: **Download _tier_ · _size_** for a model that is not on disk yet, or **Use _tier_** for one you already have. + - You can continue without choosing. If no model is available yet, Pico asks you to confirm, and you can download one later in Settings. +4. On the **Access** page ("Choose who can connect"), pick one option, then continue. + - **This Mac only** — the most private choice. Only apps on this Mac can connect. Pico binds to `127.0.0.1`. + - **Devices on my local network** — any device on your network can use Pico. Pico binds to `0.0.0.0`. + - When you choose local-network access, a **Make Pico discoverable automatically** toggle appears. Turn it on to advertise the server over Bonjour so Pico clients and other Pico servers can find it without typing an address. +5. On the **Ready** page, review the live server details, then select **Open Chat**. + - The page shows the real server state: a status dot, the model, the access scope you chose, and the server address. + - Select the copy button next to **Address** to copy the server address. + - **Open Chat** finishes setup, applies your choices, and opens the browser chat. If a model download is still in progress, Pico opens a page that tracks the download instead. + +After you finish, Pico stays in the menu bar. Use its icon to open chat, view memory, or change settings. + +## Verify it worked + +When the Ready page reports the server is running, confirm the API answers: + +```bash +curl http://127.0.0.1:11434/v1/models +``` + +If you get a JSON response, the server is up. If you chose **Devices on my local network**, also ask the server for the address to share with other devices: + +```bash +curl http://127.0.0.1:11434/ip +``` + +## Troubleshooting + +- **Symptom:** The Model page lists fewer options than you expected. + **Cause:** The available tiers depend on your Mac's memory; an 8 GB Mac is offered only the smallest tier. + **Fix:** Choose an available tier now, then add larger models later from the `Models` tab in Settings. +- **Symptom:** A download fails during or after setup. + **Cause:** A network interruption or an unreachable model repository. + **Fix:** Pico shows a **Download Failed** alert. Dismiss it and start the download again from the `Models` tab in Settings. +- **Symptom:** The Ready page shows the server address, but another device cannot connect. + **Cause:** You chose **This Mac only**, so the server is not exposed on the LAN. + **Fix:** Reopen setup or open Settings and switch to **Devices on my local network**, then test again. See [LAN Sharing Basics](../networking/lan-sharing-basics.md). + +## Next steps + +- [Configure Settings](./configure-settings.md) +- [Connect a Client](./connect-a-client.md) diff --git a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md index d48401a..8d3b440 100644 --- a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md +++ b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md @@ -10,10 +10,10 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX ## Start the server 1. Launch Pico AI Server. -2. Complete the first-run flow. - The onboarding flow lets you configure `Allow notifications`, `Allow local network connections`, `Broadcast Bonjour`, `Open at login`, and `Prevent sleep`. +2. Complete the first-run setup. + The setup wizard has four pages — Welcome, Model, Access, and Ready. It downloads a first model, chooses who can connect, and starts the server for you. For a step-by-step walkthrough, see [First-Run Setup](./first-run-setup.md). 3. Open the WebUI at `http://127.0.0.1:11434/`. - The onboarding flow normally opens this address for you after setup. + The setup wizard normally opens this address for you when you finish. 4. If you want LAN access, leave `Allow local network connections` on. With that setting on, Pico AI Server binds to `0.0.0.0`. 5. If you want local-only access, turn `Allow local network connections` off in the native app settings. diff --git a/sidebars.ts b/sidebars.ts index cc1d666..03ee979 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -12,6 +12,7 @@ const sidebars: SidebarsConfig = { label: 'Getting Started', items: [ 'user-guide/getting-started/install-and-run-pico-ai-server', + 'user-guide/getting-started/first-run-setup', 'user-guide/getting-started/configure-settings', 'user-guide/getting-started/connect-a-client', ], From 912707c94202464457580ca99ae7d9028aaed6cf Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 10:24:41 +0000 Subject: [PATCH 4/6] Qualify first-run model download claims (Codex review) - Install and Run: the wizard downloads the model you pick, and picking one is optional (you can skip and add later), not an unconditional "downloads a first model". - First-Run Setup: distinguish selectable options from ones shown as "Coming soon" or gated by a RAM requirement; the model name, size, and Download/Use button apply only to selectable options. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01D8KgyxEFCWzt6ebEC7SKng --- docs/user-guide/getting-started/first-run-setup.md | 6 +++--- .../getting-started/install-and-run-pico-ai-server.md | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/user-guide/getting-started/first-run-setup.md b/docs/user-guide/getting-started/first-run-setup.md index dfec307..2118fc6 100644 --- a/docs/user-guide/getting-started/first-run-setup.md +++ b/docs/user-guide/getting-started/first-run-setup.md @@ -14,9 +14,9 @@ You can change every choice later in the app's Settings window, so pick sensible This page introduces Pico AI Server and links to the privacy policy and terms. 3. On the **Model** page ("Choose your first model"), pick a model, then continue. - Pico shows a short list of options — such as **Fast**, **Balanced**, and **Reasoning** — sized for your Mac's memory. - - One option is preselected and marked **Recommended** for this Mac; the page subtitle names it (for example, "Balanced is recommended for this Mac. You can add or switch models later."). - - Each row shows the model name and its total download size. - - The continue button reflects your choice: **Download _tier_ · _size_** for a model that is not on disk yet, or **Use _tier_** for one you already have. + - One selectable option is preselected and marked **Recommended** for this Mac; the page subtitle names it (for example, "Balanced is recommended for this Mac. You can add or switch models later."). + - Each selectable option shows its model name and total download size. An option that isn't available yet is labeled **Coming soon**, and one that needs more memory than your Mac has shows its RAM requirement instead — neither can be selected. + - For a selectable option, the continue button reflects your choice: **Download _tier_ · _size_** for a model that is not on disk yet, or **Use _tier_** for one you already have. - You can continue without choosing. If no model is available yet, Pico asks you to confirm, and you can download one later in Settings. 4. On the **Access** page ("Choose who can connect"), pick one option, then continue. - **This Mac only** — the most private choice. Only apps on this Mac can connect. Pico binds to `127.0.0.1`. diff --git a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md index 8d3b440..10764d4 100644 --- a/docs/user-guide/getting-started/install-and-run-pico-ai-server.md +++ b/docs/user-guide/getting-started/install-and-run-pico-ai-server.md @@ -11,7 +11,7 @@ Pico AI Server is a macOS app for Apple Silicon Macs — it runs models with MLX 1. Launch Pico AI Server. 2. Complete the first-run setup. - The setup wizard has four pages — Welcome, Model, Access, and Ready. It downloads a first model, chooses who can connect, and starts the server for you. For a step-by-step walkthrough, see [First-Run Setup](./first-run-setup.md). + The setup wizard has four pages — Welcome, Model, Access, and Ready. It downloads the model you pick (you can skip and add one later), lets you choose who can connect, and starts the server for you. For a step-by-step walkthrough, see [First-Run Setup](./first-run-setup.md). 3. Open the WebUI at `http://127.0.0.1:11434/`. The setup wizard normally opens this address for you when you finish. 4. If you want LAN access, leave `Allow local network connections` on. From 14fd0408ec54387ecfbcf8450a12d3660b199878 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 10:32:03 +0000 Subject: [PATCH 5/6] Make first-run intro's model outcome conditional (Codex review) The First-Run Setup intro still promised "a model downloading (or ready)" unconditionally, which contradicts the documented skip path. Reworded so the model outcome is conditional on picking one. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01D8KgyxEFCWzt6ebEC7SKng --- docs/user-guide/getting-started/first-run-setup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/user-guide/getting-started/first-run-setup.md b/docs/user-guide/getting-started/first-run-setup.md index 2118fc6..e7fd24a 100644 --- a/docs/user-guide/getting-started/first-run-setup.md +++ b/docs/user-guide/getting-started/first-run-setup.md @@ -3,7 +3,7 @@ title: First-Run Setup sidebar_position: 2 --- -The first time you launch Pico AI Server, a setup wizard walks you through four pages — **Welcome**, **Model**, **Access**, and **Ready**. By the end you have a model downloading (or ready), you have chosen who can reach the server, and the server is running. This page explains each page so you know what every choice does. +The first time you launch Pico AI Server, a setup wizard walks you through four pages — **Welcome**, **Model**, **Access**, and **Ready**. By the end you have chosen who can reach the server and the server is running; if you picked a model, it is downloading or already ready (you can also skip that step and add a model later). This page explains each page so you know what every choice does. You can change every choice later in the app's Settings window, so pick sensible defaults now and move on. From cdf33407388adf9e763596a40bc951a148cc1a3d Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 22 Jul 2026 10:33:00 +0000 Subject: [PATCH 6/6] Qualify remaining model-outcome phrasing in First-Run Setup Head off the same no-model-path contradiction elsewhere on the page: - Model step: note that picking a model is optional ("or skip it"). - Ready step: the Model detail row only appears when a model was chosen, so qualify it ("the model you chose (when you picked one)"). Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01D8KgyxEFCWzt6ebEC7SKng --- docs/user-guide/getting-started/first-run-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/user-guide/getting-started/first-run-setup.md b/docs/user-guide/getting-started/first-run-setup.md index e7fd24a..6ce04ba 100644 --- a/docs/user-guide/getting-started/first-run-setup.md +++ b/docs/user-guide/getting-started/first-run-setup.md @@ -12,7 +12,7 @@ You can change every choice later in the app's Settings window, so pick sensible 1. Launch Pico AI Server. 2. On the **Welcome** page, review the summary and continue. This page introduces Pico AI Server and links to the privacy policy and terms. -3. On the **Model** page ("Choose your first model"), pick a model, then continue. +3. On the **Model** page ("Choose your first model"), pick a model (or skip it), then continue. - Pico shows a short list of options — such as **Fast**, **Balanced**, and **Reasoning** — sized for your Mac's memory. - One selectable option is preselected and marked **Recommended** for this Mac; the page subtitle names it (for example, "Balanced is recommended for this Mac. You can add or switch models later."). - Each selectable option shows its model name and total download size. An option that isn't available yet is labeled **Coming soon**, and one that needs more memory than your Mac has shows its RAM requirement instead — neither can be selected. @@ -23,7 +23,7 @@ You can change every choice later in the app's Settings window, so pick sensible - **Devices on my local network** — any device on your network can use Pico. Pico binds to `0.0.0.0`. - When you choose local-network access, a **Make Pico discoverable automatically** toggle appears. Turn it on to advertise the server over Bonjour so Pico clients and other Pico servers can find it without typing an address. 5. On the **Ready** page, review the live server details, then select **Open Chat**. - - The page shows the real server state: a status dot, the model, the access scope you chose, and the server address. + - The page shows the real server state: a status dot, the model you chose (when you picked one), the access scope you chose, and the server address. - Select the copy button next to **Address** to copy the server address. - **Open Chat** finishes setup, applies your choices, and opens the browser chat. If a model download is still in progress, Pico opens a page that tracks the download instead.