chore(jarca-ledger): finalize approved batch docs, dashboard, and CI smoke updates

docs/runtime-flows.md

@@ -4,8 +4,8 @@
 - Baseline Seed: `.stage-pilot/bootstrap/baseline.yaml`
 - Status: draft
 - Owner: Jarca / project maintainer
-- Last Updated (KST): 2026-06-27 10:17
-- Source Discovery / Batch: bootstrap-baseline
+- Last Updated (KST): 2026-06-30
+- Source Discovery / Batch: bootstrap-baseline, BAT-006
 - Primary Runtime: mixed
 
 ## Project Summary
@@ -23,6 +23,7 @@
 - `jarca-ledger-mcp` :: MCP stdio server for Hermes tool calls.
 - `dashboard/app.py` :: Streamlit local dashboard.
 - `pytest` :: regression test runner.
+- `.github/workflows/ci.yml` :: GitHub Actions CI gate runner for PR/push/manual checks.
 
 ## Shared Components
 - SQLite database at `~/.local/share/jarca/ledger.sqlite3` by default.
@@ -44,6 +45,22 @@
 4. UI calls service functions for reads, updates, imports, categorization, and manual linking.
 5. UI displays success/error status and refreshes visible tables.
 
+## Flow: `Dashboard operations hub overview`
+1. Operator opens the `요약` page.
+2. Dashboard resolves the KST current month and calls `get_monthly_cashflow_report(month)` using `transactions.transaction_date` and `ledger_categories.cashflow_kind` semantics.
+3. Dashboard calls `get_asset_liquidity_report`, which groups active accounts by `accounts.liquidity_bucket` and uses only `accounts.last_balance` for asset/liability values.
+4. Dashboard renders sections in REQ-005 priority order: this-month actual income/expense/net/savings rate, asset liquidity, asset composition, budget/spend, operational warnings.
+5. Missing `last_balance` account rows are excluded from asset totals and surfaced as warnings; transaction sums are not used to estimate non-transaction assets.
+
+## Flow: `CI validation gates`
+1. GitHub Actions starts `.github/workflows/ci.yml` on `pull_request`, `push` to `main`, or `workflow_dispatch`.
+2. `pytest-regression` installs the project with dev/dashboard extras and runs `pytest --ignore=tests/test_dashboard_app.py` so service/parser/regression failures fail the workflow.
+3. `dashboard-app-test` runs `pytest tests/test_dashboard_app.py`; the AppTest test creates a synthetic fixture DB through `scripts/ci_fixture_db.py`, sets `JARCA_LEDGER_DB_PATH`, and asserts core dashboard pages render without Streamlit exceptions.
+4. `dashboard-http-smoke` runs `scripts/ci_dashboard_http_smoke.py`; the wrapper creates a temp fixture DB, starts Streamlit on loopback, polls for HTTP 200, then terminates the process.
+5. `db-safety-smoke` runs `scripts/ci_db_safety_smoke.py`; the wrapper creates temp source/backup/target DB files and invokes `scripts/ledger_restore_smoke.py` without touching the operating DB path.
+6. Any job failure fails the workflow. Stable job names are intended for branch protection configuration outside the repository.
+7. CI logs are status-oriented and synthetic-data-only; they must not contain real account identifiers, raw payloads, statement filenames, balances from the operating DB, or passwords.
+
 ## Flow: `Import preview and import`
 1. Operator chooses or supplies a supported source file: KB Bank PDF, Toss Bank PDF, Toss Securities PDF, SeoulPay XLSX, or CSV.
 2. Preview function parses the file and reports counts, sample rows, duplicate status, and classification preview.
@@ -71,6 +88,25 @@
 5. Restore execution is not an MCP flow. Restore smoke uses `scripts/ledger_restore_smoke.py` or the runbook and requires explicit approval before overwriting an existing target DB.
 6. Verification evidence must not include full transaction dumps, full merchant/counterparty dumps, account identifiers, raw_payload, original financial file contents, or passwords.
 
+## Flow: `Statement-unavailable manual balance reconciliation`
+1. Operator follows the dcy-002 safety standard first: capture DB status, create or confirm a recent backup, and run preview/reconcile on a validation DB before operating on the production DB.
+2. Operator marks accounts with `statement_status`: `manual_only` for statement-unavailable accounts, `partial_import` for accounts that require manual supplementation, or `import_supported` where normal statement import is sufficient.
+3. Operator records manual evidence transactions with `source='manual'`, positive amount, date, account, and non-sensitive memo/source context.
+4. Operator runs `get_balance_reconciliation_report` from MCP/service or the dashboard account page. If `baseline_at` is `YYYY-MM`, the snapshot time is that month end at 23:59 KST; ad-hoc reconciliation uses the user-supplied snapshot timestamp.
+5. The report compares `baseline_balance`/`last_balance` with the latest `balance_after` if available, otherwise with net signed account transactions. Absolute tolerance is 1,000 KRW; 0.1% of baseline is reference-only.
+6. `OK` rows need no immediate triage. `REVIEW_NEEDED` rows present manual decision candidates: `계좌이동`, `실지출`, `실수입`, `투자이동`, `분석제외`, `확인필요`.
+7. This flow does not run automatic scheduling, notifications, restore, or auto-confirming mutation.
+
+## Flow: `Streamlit browser evidence capture`
+1. Operator runs `scripts/streamlit_browser_evidence.py` from the repository root.
+2. The script creates a synthetic fixture DB under the evidence output directory and refuses to use the default operating DB path.
+3. Streamlit starts with `JARCA_LEDGER_DB_PATH=<fixture.sqlite3>` on a local loopback port.
+4. `/usr/bin/google-chrome-stable` runs in headless mode through Chrome DevTools Protocol and opens target dashboard pages such as `분류 규칙`, `확인필요 큐`, and `Import`.
+5. After page title text is rendered, the script stores PNG screenshots, DOM snapshots, and `manifest.json` in the evidence directory.
+6. UI/dashboard-impacting batches must attach browser screenshot/snapshot evidence. Non-UI batches may treat it as optional, and docs-only batches do not require browser evidence.
+7. If Chrome/browser capture is unavailable, AppTest + HTTP 200 fallback evidence is allowed only as `PASS_WITH_NOTES` with the environment failure and remaining browser-evidence item recorded.
+8. Browser screenshot/DOM evidence is not a required GitHub Actions gate in BAT-006. Run it locally for visual/layout-sensitive dashboard changes, while non-visual backend/CI changes can rely on pytest/AppTest/HTTP/DB safety gates.
+
 ## Flow Constraints
 - Preview before broad import or categorization mutation where supported.
 - Do not include `transfer`, `investment`, `exclude`, or unresolved rows in actual household spending totals unless a report explicitly asks for account movement.
@@ -78,12 +114,16 @@
 - Avoid destructive migrations without a backup/approval plan.
 - Before broad DB mutation, capture DB status evidence and create or confirm a recent backup.
 - Restore execution is script/runbook only and must not be exposed as an MCP tool.
+- Manual balance reconciliation must remain preview/report-first unless a future REQ approves persistent review routing and confirmation mutation.
+- Streamlit browser evidence must use synthetic/validation DBs only and must not screenshot/log real account numbers, balances, source financial filenames, passwords, full merchant/counterparty dumps, or raw payloads.
+- CI gates must use synthetic/temp DBs only. The default operating DB path (`~/.local/share/jarca/ledger.sqlite3`) is forbidden for AppTest, HTTP smoke, and DB safety smoke wrappers.
+- Dashboard asset liquidity calculations must use `accounts.liquidity_bucket` and `accounts.last_balance`; `loan` is excluded from the asset composition denominator and reflected as debt/net-worth only.
 - Sensitive passwords are runtime inputs and must not be committed.
 
 ## Current Gaps / Planned Changes
-- Need final browser-level UX verification for rule delete and cancel/original linking dialogs.
-- Need CI/deployment flow if this project will be maintained beyond local operation.
-- Need a documented operational process for statement-unavailable accounts.
+- Browser-level evidence is available locally through `scripts/streamlit_browser_evidence.py`; it remains outside required CI gates by design.
+- Dedicated reconciliation workbench and persistent review-decision queue are deferred beyond REQ-003.
+- Separate asset snapshot/manual asset tables and automatic market/real-estate valuation are deferred beyond REQ-005.
 
 ## Update Triggers
 - Update this document when a command entry point changes.
@@ -93,3 +133,7 @@
 ## Change Log
 - 2026-06-26 22:24 KST: Created by `bootstrap-baseline` from repository observation.
 - 2026-06-27 10:17 KST: BAT-002/REQ-002 기준으로 운영 backup/status/list/hash 및 restore 제한 flow 추가.
+- 2026-06-29 KST: REQ-003/BAT-003 기준으로 statement-unavailable 수동 잔액대조 flow 추가.
+- 2026-06-29 KST: REQ-004/BAT-004 기준으로 Streamlit browser evidence capture flow 및 UI evidence gate 기준 추가.
+- 2026-06-29 KST: REQ-005/BAT-005 기준으로 dashboard operations hub 및 `liquidity_bucket`/`last_balance` 자산 유동성 flow 추가.
+- 2026-06-30 KST: REQ-006/BAT-006 기준으로 GitHub Actions CI validation gates, synthetic fixture DB boundary, AppTest/HTTP/DB safety smoke flow, local browser evidence boundary 추가.