Docs v1

.github/workflows/docs.yml

@@ -0,0 +1,49 @@
+name: Deploy docs to GitHub Pages
+
+on:
+  push:
+    branches: [main, docs-v1]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+      - name: Install dependencies
+        working-directory: docs
+        run: npm ci
+      - name: Build site
+        working-directory: docs
+        run: npm run build
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

docs/.gitignore

@@ -0,0 +1,15 @@
+# Dependencies
+node_modules/
+
+# Production
+build/
+
+# Generated files
+.docusaurus/
+.cache-loader/
+
+# Misc
+.DS_Store
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/docs/configure/analytics.md

@@ -0,0 +1,42 @@
+---
+title: Analytics
+description: What anonymous usage events Anton sends, what they contain, and how to opt out.
+---
+
+# Analytics
+
+Anton collects anonymous usage events — for example "session started" or
+"first query" — to help the MindsDB team understand how the product is used.
+
+## What is sent
+
+Each event is a single HTTP GET request carrying only:
+
+- the action name (e.g. `anton_started`),
+- a timestamp,
+- an anonymous installation ID.
+
+**No personal data or query content is ever sent** — no prompts, no file
+contents, no hostnames. The installation ID is a one-way SHA-256 hash of the
+machine's network adapter address, truncated to 16 hex characters; the raw
+address never leaves your device. Events are fire-and-forget: they never
+block Anton and failures are silently ignored.
+
+## Opting out
+
+Set the environment variable:
+
+```bash
+export ANTON_ANALYTICS_ENABLED=false
+```
+
+Or add it to your workspace config (`.anton/.env`):
+
+```text
+ANTON_ANALYTICS_ENABLED=false
+```
+
+To turn it off everywhere, put the same line in the global `~/.anton/.env`.
+See [Environment variables](/configure/env-vars) for how the config files are
+loaded, and [Security model](/configure/security) for the full picture of
+what leaves your machine.

docs/docs/configure/env-vars.md

@@ -0,0 +1,82 @@
+---
+title: Environment variables
+description: The authoritative reference for ANTON_* configuration variables and the .env loading chain.
+---
+
+# Environment variables
+
+Every Anton setting can be set as an environment variable with the `ANTON_`
+prefix. Most users never touch these directly — the `anton setup` and
+`anton setup-search` flows write them to the right `.env` file for you — but
+they are all available for scripting and overrides.
+
+## The .env loading chain
+
+Anton reads configuration from three locations:
+
+1. `.env` in the current directory
+2. `.anton/.env` in the workspace (project-local config)
+3. `~/.anton/.env` (global config — LLM keys, search keys)
+
+Variables set in your actual shell environment always take precedence over
+values from any file. Setup flows write LLM and search provider keys to the
+global file so they carry across workspaces, and workspace-specific settings
+to the local one.
+
+## Providers and models
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `ANTON_PLANNING_PROVIDER` | `anthropic` | Provider for the planning model (`anthropic`, `openai`, `openai-compatible`) |
+| `ANTON_PLANNING_MODEL` | `claude-sonnet-4-6` | Model used for planning and conversation |
+| `ANTON_CODING_PROVIDER` | `anthropic` | Provider for the coding model |
+| `ANTON_CODING_MODEL` | `claude-haiku-4-5-20251001` | Model used for code generation in the scratchpad |
+| `ANTON_MAX_TOKENS` | `8192` | Max output tokens per LLM call |
+| `ANTON_ANTHROPIC_API_KEY` | unset | Anthropic API key |
+| `ANTON_OPENAI_API_KEY` | unset | OpenAI (or OpenAI-compatible endpoint) API key |
+| `ANTON_OPENAI_BASE_URL` | unset | Base URL for an OpenAI-compatible endpoint |
+| `ANTON_OPENAI_API_VERSION` | unset | Azure OpenAI `api-version` query parameter |
+| `ANTON_MINDS_ENABLED` | `true` | Allow using a Minds server as LLM provider |
+| `ANTON_MINDS_API_KEY` | unset | Minds API key |
+| `ANTON_MINDS_URL` | Minds cloud URL | Minds server URL |
+| `ANTON_MINDS_MIND_NAME` | unset | Mind name to use on the Minds server |
+| `ANTON_MINDS_SSL_VERIFY` | `true` | Verify SSL certificates when talking to the Minds server |
+
+## Web tools
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `ANTON_WEB_SEARCH_ENABLED` | `true` | Enable the `web_search` tool — see [Web search](/connect/web-search) |
+| `ANTON_WEB_FETCH_ENABLED` | `true` | Enable the `web_fetch` tool — see [Web fetch](/connect/web-fetch) |
+| `ANTON_EXTERNAL_SEARCH_PROVIDER` | unset | External search provider for generic endpoints: `exa` or `brave` |
+| `ANTON_EXA_API_KEY` | unset | Exa.ai API key |
+| `ANTON_BRAVE_API_KEY` | unset | Brave Search API key |
+
+The search provider variables are normally written by `anton setup-search` —
+see [Search providers](/configure/search-providers).
+
+## Memory
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `ANTON_MEMORY_ENABLED` | `true` | Master switch for the memory system |
+| `ANTON_MEMORY_MODE` | `autopilot` | How lessons are saved: `autopilot`, `copilot`, or `off` — see [Memory overview](/teach/memory-overview) |
+| `ANTON_EPISODIC_MEMORY` | `true` | Keep an episode archive of past sessions — see [Episodes and recall](/teach/episodes-and-recall) |
+
+## Behavior
+
+| Variable | Default | What it does |
+| --- | --- | --- |
+| `ANTON_THEME` | `auto` | Terminal color theme |
+| `ANTON_DISABLE_AUTOUPDATES` | `false` | Skip automatic update checks — see [Updating](/start/updating) |
+| `ANTON_ANALYTICS_ENABLED` | `true` | Anonymous usage events — see [Analytics](/configure/analytics) |
+| `ANTON_LANGFUSE_HEADERS` | unset | Set to `1` to attach Langfuse trace headers on any OpenAI-compatible endpoint — see [Trace headers](/configure/trace-headers) |
+| `ANTON_PROACTIVE_DASHBOARDS` | `false` | When `true`, Anton builds HTML dashboards proactively; when `false`, CLI output only |
+| `ANTON_BACKEND` | `local` | Scratchpad backend: `local` or `remote` (remote requires Minds URL and API key) |
+| `ANTON_PUBLISH_URL` | `https://4nton.ai` | Publish service used when sharing artifacts |
+| `ANTON_TERMS_CONSENT` | `false` | Records that you accepted the terms screen (set by the first-run flow) |
+| `ANTON_FIRST_RUN_DONE` | `false` | Records that first-run onboarding completed (set by the setup flow) |
+
+A few additional internal tuning variables exist (tool-round limits, cell
+timeouts); they are intentionally undocumented here as they are not meant for
+everyday configuration.

docs/docs/configure/search-providers.md

@@ -0,0 +1,66 @@
+---
+title: Search providers
+description: Set up Exa.ai or Brave Search with anton setup-search for generic OpenAI-compatible endpoints.
+---
+
+# Search providers
+
+`anton setup-search` configures an external search provider so the
+`web_search` tool works on LLM endpoints that don't ship native search.
+
+## When you need it
+
+Only when your LLM provider is a **generic OpenAI-compatible endpoint**
+(Together, Groq, Ollama, vLLM, OpenRouter, and similar). Anthropic, OpenAI,
+and Minds (mdb.ai) all execute web search natively on your existing LLM key —
+no extra setup, and `setup-search` is unnecessary. See
+[Web search](/connect/web-search) for the full provider matrix.
+
+When `anton setup` finishes configuring a custom OpenAI-compatible endpoint,
+it offers this step automatically. You can run it again at any time:
+
+```bash
+anton setup-search
+```
+
+## Choosing a provider
+
+| Provider | Character | Get a key at |
+| --- | --- | --- |
+| Exa.ai | AI-native semantic search | dashboard.exa.ai/api-keys |
+| Brave Search | privacy-focused web search | api.search.brave.com/app/keys |
+
+The setup screen shows which provider (if any) is currently configured, with
+a masked tail of the active key so you can recognize it without exposing it.
+
+## Key validation
+
+Anton validates the key before saving it: it makes a small probe call to the
+provider's search API and checks the response. If authentication fails or the
+service errors, you can:
+
+- **retry** — re-enter the key for the same provider (fix a typo without
+  re-picking from the menu),
+- **switch** — go back to the picker and try the other provider,
+- **skip** — disable `web_search` for now.
+
+## Switching providers
+
+Re-run `anton setup-search` and pick the other provider. The previously
+stored key for the old provider is left in place; only the active provider
+selection changes.
+
+## Skipping
+
+Choosing **Skip** disables `web_search` — the tool stays unavailable until
+you run `anton setup-search` again. If a working provider is already
+configured, Anton asks for confirmation before clearing it, so a stray
+keystroke can't wipe a working setup.
+
+## Where the key lives
+
+The provider choice and key are persisted to the **global** `~/.anton/.env`
+(as `ANTON_EXTERNAL_SEARCH_PROVIDER` plus `ANTON_EXA_API_KEY` or
+`ANTON_BRAVE_API_KEY`), so they survive across sessions and workspaces —
+the same scope as your LLM keys. See
+[Environment variables](/configure/env-vars).

docs/docs/configure/security.md

@@ -0,0 +1,75 @@
+---
+title: Security model
+description: How the credential vault, scratchpad isolation, and local-first design keep your secrets and data under your control.
+---
+
+# Security model
+
+Anton runs on your machine. Your code, files, and queries stay local unless
+you explicitly ask Anton to send them somewhere. This page explains the
+mechanisms behind that.
+
+## The credential vault
+
+Connection credentials are stored in a local vault at `~/.anton/data_vault/`
+— one JSON file per connection, with the directory restricted to your user
+account and each file readable only by you.
+
+The key property: **secrets are never placed in LLM prompts.**
+
+- At run time, credentials are injected as `DS_*` environment variables into
+  the scratchpad process (for example `DS_PASSWORD`, or namespaced forms like
+  `DS_POSTGRES_MYDB__PASSWORD` when several connections are loaded).
+- The model writes code that reads `os.environ['DS_PASSWORD']` — it sees the
+  variable *name*, never the value.
+- Scratchpad output is scrubbed before it reaches the model: values of
+  registered secret variables are redacted, so a stray `print` can't leak a
+  password into the conversation.
+
+See [Connecting things: overview](/connect/overview) for how credentials get
+into the vault in the first place.
+
+## Scratchpad isolation
+
+All code Anton writes runs in scratchpads — not in your shell. With the local
+backend, each scratchpad is a persistent subprocess running inside its own
+dedicated Python virtual environment (created per scratchpad under the
+workspace's `.anton/scratchpad-venvs/`, or `~/.anton/scratchpad-venvs/` when
+no workspace applies). Packages Anton installs for one task don't pollute
+your system Python or other scratchpads, and a scratchpad can be reset to a
+clean state at any time.
+
+## What leaves your machine
+
+Three things, and only three:
+
+1. **Prompts to your LLM provider.** Whatever you type, plus the context
+   Anton assembles, goes to the provider you configured (Anthropic, OpenAI,
+   Minds, or your own endpoint) and is governed by that provider's terms.
+2. **Anonymous analytics.** Event names and timestamps only — no query
+   content, no personal data. Opt out any time: see
+   [Analytics](/configure/analytics).
+3. **Whatever you ask Anton to send.** Emails, API calls, published
+   dashboards — actions you request.
+
+In the other direction, remember that **fetched web content is untrusted
+input**: a page Anton reads can contain text designed to manipulate the
+model. See [Web fetch](/connect/web-fetch).
+
+## Windows firewall
+
+On Windows, the scratchpad's Python needs outbound network access. The
+installer offers to add a firewall rule; if you skipped it, run this in an
+elevated PowerShell:
+
+```powershell
+netsh advfirewall firewall add rule name="Anton Scratchpad" dir=out action=allow program="$env:USERPROFILE\.anton\scratchpad-venv\Scripts\python.exe"
+```
+
+## Your responsibility
+
+Anton acts on your behalf — sending emails, modifying data, calling APIs. As
+the first-run terms screen puts it: you're responsible for what Anton does on
+your behalf, so review proposed actions before authorizing them. This matters
+most for [custom integrations](/connect/custom-integrations), where Anton
+writes its own integration code.

docs/docs/configure/trace-headers.md

@@ -0,0 +1,37 @@
+---
+title: Trace headers
+description: Attach Langfuse trace headers to LLM requests on OpenAI-compatible endpoints.
+---
+
+# Trace headers
+
+When the planning provider is OpenAI-compatible, Anton can attach trace
+headers to its LLM requests so a router or observability proxy can attribute
+traces to sessions:
+
+- `Langfuse-Session-Id`
+- `Langfuse-Tags`
+- `Langfuse-Metadata`
+
+This is useful when your requests pass through a gateway that records traces
+— for example a self-hosted Langfuse proxy sitting in front of Ollama or
+vLLM.
+
+## Enabling
+
+To emit the headers against any OpenAI-compatible endpoint, set:
+
+```bash
+export ANTON_LANGFUSE_HEADERS=1
+```
+
+Or add it to your workspace config (`.anton/.env`):
+
+```text
+ANTON_LANGFUSE_HEADERS=1
+```
+
+The headers only carry session attribution metadata — they don't change what
+prompts are sent or where. See
+[Environment variables](/configure/env-vars) for the config file loading
+order.