[pull] main from mindsdb:main

CLAUDE.md

@@ -0,0 +1,118 @@
+# Minds Platform
+
+## Submodules
+
+This repo has 4 submodules:
+
+| Path | Repo | Tracking |
+|---|---|---|
+| `frontend` | `mindsdb/cowork` | tag-pinned |
+| `backend/core_api` | `mindsdb/cowork-server` | tag-pinned |
+| `backend/core_agent` | `mindsdb/anton` | tag-pinned |
+| `backend/data-vault` | `mindsdb/data-vault` | `main` branch |
+
+### Clone (fresh)
+
+```bash
+git clone --recurse-submodules https://github.com/mindsdb/minds-platform
+```
+
+### Initialize after cloning without submodules
+
+```bash
+git submodule update --init --recursive
+```
+
+### Pull — sync to what the parent repo pins (default)
+
+```bash
+git submodule update --recursive
+```
+
+### Pull — advance all submodules to latest `main`
+
+Only do this if you intend to develop across all repos. You'll need to commit the updated pointers in the parent repo afterward.
+
+```bash
+git submodule foreach 'git checkout main && git pull origin main'
+```
+
+### Make changes and push inside a submodule
+
+1. Go into the submodule and get on a real branch first (all submodules start in detached HEAD):
+
+```bash
+cd backend/data-vault   # or whichever submodule
+git checkout main       # or: git checkout -b your-feature-branch
+```
+
+2. Make your changes, commit, and push:
+
+```bash
+git add .
+git commit -m "your message"
+git push origin main
+```
+
+3. Back in the parent repo, stage and commit the updated submodule pointer:
+
+```bash
+cd ../..
+git add backend/data-vault
+git commit -m "bump data-vault to latest"
+git push
+```
+
+> The parent repo stores a commit SHA pointer to each submodule, not the code itself. Always push from inside the submodule first, then update the pointer in the parent.
+
+## Running locally (web browser mode)
+
+After initializing submodules, start the full stack with:
+
+```bash
+cd frontend
+npm install
+npm run dev:web
+```
+
+Open `http://localhost:5173/`. The FastAPI backend starts automatically on `http://127.0.0.1:26866`.
+
+### Skip Keycloak auth (required for local dev)
+
+By default the web app redirects to MindsHub SSO on first load. To bypass this locally, create `frontend/src/renderer/.env` (Vite's root is `src/renderer`, not `frontend/`):
+
+```bash
+echo "VITE_SKIP_AUTH=true" > frontend/src/renderer/.env
+```
+
+Then restart `npm run dev:web`. The Keycloak redirect will be skipped and the app loads the onboarding screen directly where you can enter a BYOK API key.
+
+### First-time symlink fix
+
+The `dev:web` script expects the `uv`-installed tool at `~/.local/share/uv/tools/anton/`, but it may be installed as `anton-agent`. If you see "Anton Python interpreter not found", run:
+
+```bash
+ln -s ~/.local/share/uv/tools/anton-agent ~/.local/share/uv/tools/anton
+```
+
+## Flushing local installs (fresh start)
+
+`make flush` wipes every local install **and** all app state, returning the machine to a pre-install condition. Use it to test the from-scratch install flow or to recover from a broken/half-installed environment.
+
+```bash
+make flush          # prompts before deleting
+make flush FORCE=1  # skip the prompt (CI / scripts)
+```
+
+It removes:
+
+| Removed | What it is |
+|---|---|
+| `cowork-server` uv tool (+ legacy `anton-agent`) | the runtime the **Electron app** installs via `uv tool install` |
+| `backend/core_api/.venv`, `backend/core_agent/.venv` | the venvs the **Makefile** dev flow builds via `uv sync` |
+| `~/.anton` | provider keys / `.env` |
+| `~/.cowork` | database, `hermes`, `projects` |
+
+> ⚠️ Destructive — deletes conversations and saved provider keys, no undo. After flushing, the next `make setup` (or app launch) reinstalls everything from scratch.
+
+> It deliberately leaves `uv` itself and uv-managed Python runtimes alone (shared infrastructure, not part of the anton/cowork install).

Makefile

@@ -6,7 +6,7 @@ _NPM_STAMP := $(FRONTEND)/node_modules/.package-lock.json
 _API_STAMP  := $(API)/.venv
 _AGENT_STAMP := $(AGENT)/.venv
 
-.PHONY: setup dev dev-web build dist-mac dist-win docker-build docker-up docker-down
+.PHONY: setup dev dev-web build dist-mac dist-win docker-build docker-up docker-down flush
 
 $(_NPM_STAMP): $(FRONTEND)/package-lock.json
 	npm --prefix $(FRONTEND) ci
@@ -50,3 +50,28 @@ docker-up:
 
 docker-down:
 	docker compose down
+
+# Wipe every local install + all app state, returning the machine to a
+# pre-install state. Covers BOTH runtime models (the Makefile dev venvs
+# AND the Electron app's `uv tool install cowork-server`) plus user data.
+# Removes:
+#   • cowork-server uv tool (and the legacy anton-agent tool)
+#   • submodule venvs: $(API)/.venv, $(AGENT)/.venv
+#   • ~/.anton   — provider keys / .env
+#   • ~/.cowork  — database, hermes, projects
+# The next `make setup` (or app launch) reinstalls from scratch.
+# Set FORCE=1 to skip the confirmation prompt (CI / scripts).
+flush:
+	@echo "This will PERMANENTLY remove:"
+	@echo "  • cowork-server uv tool (+ legacy anton-agent)"
+	@echo "  • $(API)/.venv and $(AGENT)/.venv"
+	@echo "  • ~/.anton   (provider keys / .env)"
+	@echo "  • ~/.cowork  (database, hermes, projects)"
+	@if [ "$(FORCE)" != "1" ]; then \
+		read -p "Proceed? [y/N] " ans; [ "$$ans" = y ] || [ "$$ans" = Y ] || { echo "Aborted."; exit 1; }; \
+	fi
+	-uv tool uninstall cowork-server
+	-uv tool uninstall anton-agent
+	rm -rf $(API)/.venv $(AGENT)/.venv
+	rm -rf $$HOME/.anton $$HOME/.cowork
+	@echo "✓ Flushed. Run 'make setup' (or relaunch the app) for a fresh install."

README.md

@@ -77,6 +77,9 @@ make setup
 | Production build | `make build` |
 | Package for macOS | `make dist-mac` |
 | Package for Windows | `make dist-win` |
+| Wipe all local installs + data (fresh start) | `make flush` |
+
+> **Reset to a clean slate:** `make flush` uninstalls the local runtime (the `cowork-server` uv tool and the `backend/*/.venv`s) **and** deletes app state in `~/.anton` (provider keys) and `~/.cowork` (database, hermes, projects). Use it to test the from-scratch install flow or recover from a broken install. ⚠️ This deletes your conversations and saved keys. It prompts for confirmation; pass `FORCE=1` to skip it. The next `make setup` or app launch reinstalls everything.
 
 ---
 

docs/setup.html

@@ -546,8 +546,18 @@ <h2>All make commands</h2>
           <tr><td><code>make docker-build</code></td><td>Build the api and web Docker images.</td></tr>
           <tr><td><code>make docker-up</code></td><td>Start the Docker stack (<code>docker compose up</code>).</td></tr>
           <tr><td><code>make docker-down</code></td><td>Stop and remove containers.</td></tr>
+          <tr><td><code>make flush</code></td><td>Wipe all local installs + app data for a fresh start (see below).</td></tr>
         </tbody>
       </table>
+
+      <h2>Reset to a clean slate</h2>
+      <p><code>make flush</code> returns the machine to a pre-install state. It uninstalls the local runtime &mdash; the <code>cowork-server</code> uv tool <em>and</em> the <code>backend/core_api/.venv</code> + <code>backend/core_agent/.venv</code> &mdash; and deletes all app state: <code>~/.anton</code> (provider keys / <code>.env</code>) and <code>~/.cowork</code> (database, hermes, projects).</p>
+      <p>Use it to test the from-scratch install flow or to recover from a broken install. It prompts for confirmation before deleting; pass <code>FORCE=1</code> to skip the prompt in scripts/CI. The next <code>make setup</code> (or app launch) reinstalls everything.</p>
+      <div class="note">
+        <strong>Destructive.</strong> This permanently deletes your conversations and saved provider keys. There is no undo.
+      </div>
+      <pre><code>make flush          # prompts before wiping
+make flush FORCE=1  # no prompt (CI / scripts)</code></pre>
     </section>
   </main>
 </div>