# CLAUDE.md

This directory is the executable source of truth for Quant OS. `quant60` is
its first A-share Baseline kernel/package; the project itself also owns data,
research, portfolio, execution, evidence, and platform adapters. Obsidian
contains research and status documentation only.

## Development commands

Run all commands from this directory:

```bash
make test
make bundle
make smoke
make verify
make doctor
make local
```

The zero-install path is `PYTHONPATH=src:. python3 ...`. Do not require a
virtual environment for the deterministic local smoke.

## Platform boundaries

- `dist/joinquant_strategy.py` is the generated single-file JoinQuant upload.
- `dist/qmt_builtin_strategy.py` is the generated QMT built-in backtest file.
- `platforms/qmt_research_runner.py` drives qmttools backtests.
- `adapters/xttrader_live.py` is the guarded external QMT/XtTrader boundary.
- `platforms/qlib_runner.py` is an isolated Qlib research bridge.
- `notebooks/quant_os_colab.ipynb` must remain executable locally and in Colab.

Never make QMT built-in code live-capable. Real broker mutation stays disabled
unless the external XtTrader adapter receives a fresh, account-bound guard.

## Security

- Never commit passwords, tokens, cookies, broker userdata, account exports,
  private keys, or reusable credentials.
- JoinQuant authentication uses an interactive browser session.
- QMT configuration is injected through local environment variables; only
  placeholder names belong in `.env.example`.
- Fake, synthetic, and unit-test evidence must never be described as a real
  platform or broker pass.

## Definition of done

A change is complete only when:

1. unit/integration tests pass;
2. hosted bundles rebuild and pass Python 3.6 syntax checks;
3. the deterministic smoke and manifest verifier pass;
4. docs state the exact evidence class and remaining external gate;
5. no secret or machine-specific absolute path is added to tracked artifacts.