Bootstrap And Onboarding

Current reality

The repo still expects a fairly hands-on Python and Node setup. That is acceptable for contributors, but it is not yet the V1 onboarding experience we want for broader users.

Product goal

The long-term bootstrap flow should feel more like a guided launcher than a README scavenger hunt. At minimum it should:

1. detect platform and prerequisite gaps
2. offer optional dependency installation
3. prepare the Python and Node environments
4. validate provider and model readiness
5. start the relevant local surface
6. explain next steps when anything fails

Planned command surface

The command surface should stay layered instead of mysterious. Focused commands stay available for debugging, while normal operators get a short lifecycle vocabulary:

The existing focused commands such as setup:node, install:python, setup:research-flow, setup:camofox, fetch:camofox, start:camofox, and service-specific CLI commands should remain useful for debugging. The plan is to make them implementation details behind the guided lifecycle rather than the only way to get started.

app:doctor is intentionally the first implemented lifecycle command. It uses the already installed agentic-trader entrypoint instead of invoking uv run, so a diagnosis does not create or repair an environment as a hidden side effect. It reads setup-status, model-service, Camofox-service, WebGUI-service, provider diagnostics, and network-light v1-readiness; generation probes remain explicit through v1-readiness --provider-check or model-service status --probe-generation.

app:up is now the first guided first-run orchestrator. It defaults to dry-run and composes the existing lifecycle commands instead of creating another runtime owner. The safe --all --yes lane runs core setup repair, the runtime-controlled CrewAI Flow sidecar setup, app-owned Web GUI start, and a final app:doctor report. Optional Camofox dependency setup, Camofox browser binary fetch, model-service start, and Camofox-service start require explicit scopes plus matching ownership flags such as --ollama-owner=app-owned or --camofox-owner=app-owned. Host-owned, API/key-only, and skipped choices are persisted in runtime/setup/tool-ownership.json, show up in setup status, dashboard, Web GUI, and TUI readiness, and do not become hidden installs.

app:start and app:stop are also implemented as conservative service slices: they default to dry-run, require selecting --webgui, --model-service, --camofox-service, or --all, and mutate only after --yes. They do not install dependencies, fetch browser binaries, pull Ollama models, start a trading daemon, or open a browser unless --open-browser is explicitly passed. Ownership checks stay inside the existing model-service, camofox-service, and webgui-service commands. Starting model-service or Camofox-service through app:start requires the persisted ownership mode to be app-owned; host-owned or skipped tools remain visible blockers instead of being claimed. If the recorded app-owned Web GUI process cannot be stopped, its state remains for retry rather than being silently reclassified as an external listener.

app:update is implemented as the first scoped update lane. It defaults to dry-run and requires selecting --core, --sidecar, --camofox, --build, --status, or --all plus --yes before it mutates anything. It uses the native owners for each dependency set and does not fetch browser binaries, pull models, start or stop services, delete runtime state, or start the trading daemon.

app:uninstall is implemented as the first conservative cleanup lane. It defaults to dry-run and requires selecting --artifacts, --deps, --service-state, or --all plus --yes before it removes files. It preserves ignored env files, secrets, provider accounts, brokerage configuration, host-owned services, global tools, and trading runtime evidence. Recorded service state files block service-state cleanup until app:stop clears the app-owned process record.

Non-negotiable requirements

• cross-platform support: macOS, Linux, and Windows
• provider-aware behavior instead of forcing Ollama-only setup
• explicit prompts before installing optional model services or models
• resume or repair behavior for partial installs
• visible logs and actionable error messages
• no hidden dependency deletion, large browser/model download, provider account creation, or daemon start

Tool ownership questions

Before installing or starting optional helpers, the guided setup should ask which ownership mode the operator wants:

• host-owned: the app connects to an already managed local tool and never stops it
• app-owned: the app installs or uses a repo-local helper and records owner-only state/logs before it starts or stops anything
• API/key-only: the app uses an ignored environment/keychain value without installing a CLI
• skipped: the feature stays degraded but the core paper-first product can still open

This matters for Ollama, Firecrawl, and Camofox. If host Ollama is absent and the operator does not want a host install, the installer should offer the app-owned model-service path instead of letting the Web GUI open into a confusing "Ollama unreachable" state. Firecrawl should use the internal SDK/API-key path first; authenticated host CLI fallback is allowed only when Firecrawl is recorded as host-owned, while app-owned/API-only/skipped modes keep that fallback disabled and visible. Camofox should remain loopback-only, access-key-gated, and browser-binary fetch should stay a separate opt-in step.

Current ownership state can be inspected or changed without running setup:

agentic-trader tool-ownership status --json
agentic-trader tool-ownership set --ollama-owner host-owned --firecrawl-owner api-key-only --camofox-owner skipped --json

When a decision is already recorded, make bootstrap should report it and move on instead of prompting again. Reselect ownership explicitly with agentic-trader tool-ownership set ... before rerunning bootstrap.

V1 defaults to the internal-first model path: app-owned Ollama, qwen3:8b, and the existing model-service status/log surfaces. Host fallback is available when the operator records host ownership, but app lifecycle commands must not start or stop host-owned tools. Operators who want another model adapter can skip Ollama and select an OpenAI-compatible endpoint explicitly:

AGENTIC_TRADER_LLM_PROVIDER=openai-compatible
AGENTIC_TRADER_BASE_URL=http://127.0.0.1:8080/v1
AGENTIC_TRADER_MODEL_NAME=your-model
AGENTIC_TRADER_OPENAI_COMPATIBLE_API_KEY=optional-secret

Ollama-specific direction

When Ollama is on PATH, a portable local launch can look like this. macOS Homebrew, Linux, and Windows installs may use different binary paths.

OLLAMA_FLASH_ATTENTION="1" OLLAMA_KV_CACHE_TYPE="q8_0" ollama serve

The desired future state is not “teach the user to memorize that command”. The desired future state is:

• the app can start or stop Ollama intentionally
• the app can show health and recent logs
• the operator can tell the difference between idle, busy, and broken

The guided setup should distinguish four states: host Ollama reachable, app-owned Ollama ready, Ollama intentionally skipped because another provider is configured, and model backend missing or broken. app:start may start an already configured app-owned model service when the active provider is ollama, but it must not silently install a binary, pull a model, hijack a host listener, or override an explicit OpenAI-compatible adapter.

Camofox and pnpm direction

tools/camofox-browser is optional tool infrastructure, not a broker/runtime authority. Its setup should move away from npm-owned helper commands and use the repo's pnpm policy:

pnpm --dir tools/camofox-browser install --ignore-workspace --ignore-scripts
pnpm --dir tools/camofox-browser --ignore-workspace run fetch:browser
pnpm --dir tools/camofox-browser --ignore-workspace run test

The first command installs local helper dependencies without browser downloads. The second command downloads or updates the Camoufox browser binary and must remain explicit because it can be large and platform-specific. The wrapper and service commands should start the helper only with a loopback host and CAMOFOX_ACCESS_KEY or a mirrored CAMOFOX_API_KEY.

Update and uninstall direction

app:update updates each dependency owner through its native tool, then can rebuild and re-run setup status:

• root Node workspace: pnpm recursive/workspace update flow
• Camofox helper: pnpm --dir tools/camofox-browser ...
• root Python: uv workspace lock upgrade plus locked sync
• CrewAI Flow sidecar: workspace member locked sync through root uv
• docs/WebGUI/TUI: normal workspace build and typecheck gates
• post-update status: app:doctor

app:uninstall removes only selected app-owned/generated scopes: artifacts, dependency directories, the repo-local pnpm store, and app-owned helper service-state/log directories. It should not delete API keys, brokerage/provider accounts, user-owned host services, global tools, ignored env files, or trading evidence such as DuckDB. If a service state file still exists, the operator should run pnpm run app:stop -- --all --yes first.

Edge cases worth designing for

• the user wants another provider and should be allowed to skip Ollama
• the package manager or shell toolchain is missing
• the PATH differs from the maintainer machine
• a partial installation exists and needs repair
• the Web GUI launches but the runtime fails readiness checks
• a model is present but the wrong adapter or base URL is configured
• Camofox dependencies are present but the browser binary is missing
• a stale app-owned PID exists while a host-owned listener is also running
• an IDE or worktree resolves agentic-trader from a stale checkout

What a good bootstrap UX says out loud

A good bootstrap flow should be explicit about:

• what it is going to install
• what it skipped
• what is optional versus required
• which files it changed
• why a step is deferred and the next command or ownership action to run
• which local URL or UI it launched

Suggested acceptance checklist

• A new machine can reach doctor without manual guesswork.
• Optional model setup can be skipped without breaking the rest of the install.
• The user sees a clear failure when model or provider readiness is missing.
• The launcher can point the user to logs instead of hiding them.
• The generated environment stays consistent with the repo’s current runtime contracts.
• Camofox, Firecrawl, and Ollama ownership decisions are persisted and visible in setup status, dashboard, Web GUI, and TUI readiness.
• Re-running bootstrap does not overwrite persisted ownership decisions or repeat the same ownership prompts.
• Optional global CrewAI CLI failures stay as short setup notes, not multi-line setup-status version tracebacks.
• app:up can recover from a partial install and ends at an opened Web GUI or a precise blocker report.