vntrevx · vntrevx · Jun 23, 2026 · Jun 23, 2026 · Jun 23, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -23,3 +23,12 @@ jobs:
       - run: uv run ruff check .
       - run: uv run basedpyright
       - run: uv run pytest -q
+      - run: python3 -m json.tool package.json >/dev/null
+      - run: bash -n scripts/install.sh scripts/uninstall.sh scripts/final_smoke.sh
+      - name: Install bootstrap dry-run
+        run: |
+          runtime_dir="$(mktemp -d)"
+          trap 'rm -rf "$runtime_dir"' EXIT
+          bash scripts/install.sh --yes --paper --testnet --dry-run --runtime-dir "$runtime_dir/runtime"
+          bash scripts/uninstall.sh --yes --dry-run --runtime-dir "$runtime_dir/runtime"
+          bash scripts/uninstall.sh --purge --yes --dry-run --runtime-dir "$runtime_dir/runtime"
diff --git a/.gitignore b/.gitignore
@@ -11,13 +11,26 @@
 .ruff_cache/
 .runtime/
 .venv/
+node_modules/
 __pycache__/
 test-results/
+playwright-report/
+browser-traces/
 build/
 dist/
 htmlcov/
 *.egg-info/
 *.py[cod]
-*.sqlite3
+*.sqlite*
+*.db
 *.log
-.omo/evidence/
+*.har
+*.trace
+*.webm
+support-bundle*.zip
+support-bundle*.tar
+support-bundle*.tar.gz
+support-bundle*.tgz
+data/
+logs/
+.omo/
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,104 @@
+# PROJECT KNOWLEDGE BASE
+
+**Generated:** 2026-06-13T01:24:33+09:00
+**Commit:** a0a0630
+**Branch:** main
+
+## OVERVIEW
+
+NFI Engine is an original Python 3.12 crypto trading engine for paper/testnet
+operation, deterministic simulation, backtesting, and NFI-shaped strategy
+compatibility research. Freqtrade and NostalgiaForInfinity are behavior
+references only; do not copy code, UI, wording, or distinctive design.
+
+## STRUCTURE
+
+```text
+nfi_engine/
+|-- src/nfi_engine/      # engine package: CLI, API, domain, trading services
+|-- tests/               # unit, integration, e2e, and canonical fixtures
+|-- docs/                # operator, safety, Docker, UI, compatibility rules
+|-- examples/            # spot/futures paper configs
+|-- scripts/             # install, uninstall, smoke, benchmark, evidence tools
+|-- .omo/                # plans, evidence, workflow ledger; generated-heavy
+|-- Dockerfile
+|-- compose.yaml
+`-- pyproject.toml
+```
+
+## WHERE TO LOOK
+
+| Task | Location | Notes |
+| --- | --- | --- |
+| First run | `README.md`, `docs/docker.md`, `scripts/install.sh` | Docker-first local paper/testnet path. |
+| CLI entry | `src/nfi_engine/cli.py`, `src/nfi_engine/cli_*.py` | Root Typer app fans out by command group. |
+| Runtime config | `src/nfi_engine/config/` | Pydantic settings plus custom loader/env overrides. |
+| API app | `src/nfi_engine/api/app.py`, `api/routes.py` | FastAPI factory and route wiring. |
+| Operator UI | `src/nfi_engine/ui/`, `docs/ui.md` | Local HTML/CSS/JS console, no CDN. |
+| Trading model | `src/nfi_engine/domain/`, `risk/`, `safety/` | Typed market/order/risk boundaries. |
+| Backtests | `src/nfi_engine/backtest/`, `validation/` | Deterministic outputs and reproducibility metadata. |
+| Paper runtime | `src/nfi_engine/paper/`, `exchange/` | Tick-driven loop, simulator/testnet boundary. |
+| Storage | `src/nfi_engine/persistence/`, `maintenance/` | SQLite repositories, migrations, backups. |
+| Tests | `tests/unit`, `tests/integration`, `tests/e2e` | Layered tests with strict pytest config. |
+| Evidence | `.omo/evidence/` | Manual QA, smoke, benchmark, and plan evidence. |
+
+## CODE MAP
+
+| Symbol | Type | Location | Role |
+| --- | --- | --- | --- |
+| `main` | function | `src/nfi_engine/cli.py` | CLI console-script entry. |
+| `create_app` | function | `src/nfi_engine/api/app.py` | Builds the FastAPI app and UI/API wiring. |
+| `RuntimeSettings` | class | `src/nfi_engine/config/models.py` | Root Pydantic runtime model. |
+| `create_order_intent` | function | `src/nfi_engine/domain/orders.py` | Typed order-intent construction. |
+| `run_backtest` | function | `src/nfi_engine/backtest/runner.py` | Deterministic backtest loop. |
+| `run_paper` | function | `src/nfi_engine/paper/runner.py` | Paper-run event loop. |
+| `render_home_page` | function | `src/nfi_engine/ui/pages.py` | First operator surface renderer. |
+| `PersistenceDatabase` | class | `src/nfi_engine/persistence/session.py` | Async SQLAlchemy database wrapper. |
+
+## CONVENTIONS
+
+- Use `uv`; the quality gate is `uv run ruff format --check .`,
+  `uv run ruff check .`, `uv run basedpyright`, `uv run pytest -q`.
+- Python is 3.12, `basedpyright` is strict, `ruff` selects `ALL`, and warnings are pytest errors.
+- Keep config parsing at the edge. Pass typed Pydantic/domain values into services, not raw YAML dictionaries.
+- Use Polars or local typed structures for new engine data. Do not introduce pandas outside compatibility adapters.
+- User-visible, safety, runtime, UI, Docker, or performance work needs manual evidence under `.omo/evidence/`.
+- Keep public wording precise: feature benchmark/inspiration is acceptable; clone, parity, and profit claims are not.
+- When the user writes Korean, answer concisely in Korean unless code or repo text needs English.
+
+## ANTI-PATTERNS
+
+- Do not copy Freqtrade, FreqUI, NostalgiaForInfinity source, docs prose, layout, colors, or strategy internals.
+- Do not add real-money execution, live shortcuts, public-profit claims, or live-order bypasses in milestone work.
+- Do not expose the operator API publicly by default. Preserve loopback binding
+  unless a hardened deployment task exists.
+- Do not commit secrets, runtime `.env`, API tokens, exchange keys, SQLite
+  runtime data, logs, caches, or `.omo/evidence` artifacts.
+- Do not let UI code reach directly into storage rows, raw config dictionaries, or safety internals.
+- Do not bypass auth, CSRF, read-only mode, sandbox checks, plugin allowlists,
+  circuit breakers, reconciliation, or dry-run previews.
+- Do not create large files casually; the project plan treats 250 pure LOC as a split pressure point.
+
+## COMMANDS
+
+```bash
+uv sync
+uv run nfi-engine --help
+uv run nfi-engine config validate --config examples/futures-paper.yaml
+uv run nfi-engine preflight check --profile local-paper --config examples/spot-paper.yaml
+uv run nfi-engine serve --config examples/futures-paper.yaml --host 127.0.0.1 --port 18080
+bash scripts/install.sh --yes --paper --testnet
+bash scripts/uninstall.sh --yes
+bash scripts/final_smoke.sh
+python3 scripts/verify_plan_evidence.py .omo/plans/nfi-engine.md .omo/evidence
+```
+
+## NOTES
+
+- No in-repo `AGENTS.md` existed before this init pass.
+- The worktree often contains active `.omo` plans/evidence and user edits. Do
+  not clean, revert, or normalize unrelated files.
+- `compose.yaml` may contain `0.0.0.0` inside container allowlists; host
+  publishing must remain loopback unless intentionally hardened.
+- Treat `.omo/plans/nfi-engine.md` as the durable original plan; older drafts or
+  generated evidence are not source-of-truth docs.
diff --git a/DESIGN.md b/DESIGN.md
@@ -0,0 +1,50 @@
+# NFI Engine UI Design System
+
+## Product Surface
+
+NFI Engine is a local operator console for paper/testnet trading research. It is
+not a public marketing site. The first screen must stay operational, dense, and
+quiet enough for repeated checks.
+
+## Layout
+
+- Main content is constrained to `1160px` with `24px` desktop padding and `16px`
+  mobile padding.
+- Home uses a compact status strip and a two-column dashboard grid that
+  collapses to one column below `780px`.
+- Sections are bordered operational panels with `6px` radius; avoid nested
+  cards and decorative wrappers.
+
+## Color
+
+- Background: `#f5f7f6`
+- Panel: `#ffffff`
+- Text: `#17201d`
+- Muted text: `#5b6863`
+- Border: `#ccd6d1`
+- Accent: `#0f766e`
+- Danger: `#b42318`
+- Warning: `#9a6700`
+
+## Typography
+
+Use the existing system font stack from `src/nfi_engine/ui/assets.py`.
+Headings are compact: `24px` for the page title and `15px` for panel headings.
+Letter spacing stays `0`.
+
+## Controls
+
+Buttons, inputs, and selects use `5px` radius, local CSS only, and stable
+minimum heights. Disabled controls are visual hints only; server-side guards
+remain authoritative.
+
+## Localization
+
+Visible operator text must use typed i18n keys for English, Korean, and Greek.
+Machine codes, contract ids, API field names, strategy tags, and evidence paths
+stay untranslated.
+
+## Safety Copy
+
+UI text may say paper/testnet-ready or gated when the checks support it. It must
+not claim live readiness, strategy parity, profit, or superiority.