Project State

What is already true

Agentic Trader is already more than a prototype. The repo currently contains:

• a staged specialist graph
• shared runtime and review contracts
• DuckDB-backed persistence
• CLI, Rich, Ink, observer API, and Web GUI surfaces
• paper-first execution discipline
• smoke QA and runtime inspection tooling

The docs site should reflect that reality instead of rewriting it into a generic AI-product story.

What is actively hardening

The current hardening track is focused on:

• making runtime, provider, and model health easier to inspect
• improving onboarding and setup quality
• keeping web surfaces thin and contract-aligned
• documenting real boundaries so contributors move faster with less drift

What should not drift

• The Python runtime remains the source of truth.
• webgui/ still shells out to the Python CLI instead of replacing it.
• docs/ is a developer-facing shell, not a second product runtime.
• Paper trading remains the default execution posture.
• Fallback paths must stay explicit and inspectable.

Open product-facing initiatives

Optional app-managed Ollama supervision

The target behavior is to let the application supervise Ollama through the same status and log surfaces already used for runtime diagnostics.

That means:

• explicit start and stop behavior
• visible health checks
• readable request and log evidence
• no fake “healthy” state when the model is stalled

Cross-platform bootstrap

The longer-term onboarding target is a guided setup flow for macOS, Linux, and Windows that can:

• inspect prerequisites
• offer optional dependency installation
• prepare Python and Node environments
• validate providers and model readiness
• launch the correct local surface

Current documentation posture

This docs site is now expected to cover more than a simple quick start. It should explain:

• current system ownership
• the guardrails behind runtime behavior
• how frontend surfaces are allowed to evolve
• what evidence counts as a meaningful QA pass

PR posture for this branch

A docs branch is not ready merely because it renders. It should also:

• describe the real repo state honestly
• be maintainable as the repo grows
• avoid long, overloaded files when splitting improves readability
• keep docs, .ai notes, and implementation assumptions aligned