[codex] Improve local music self-analytics dashboard

.env.example

@@ -5,6 +5,7 @@ STREAMIFY_DUCKDB_PATH=data/streamify.duckdb
 STREAMIFY_REPORT_PATH=data/streamify_summary.md
 STREAMIFY_SNAPSHOT_PATH=data/streamify_snapshot.json
 STREAMIFY_RECOMMENDATIONS_DIR=data/recommendations
+STREAMIFY_ENRICHMENT_DIR=data/enrichment
 STREAMIFY_DBT_PROFILES_DIR=dbt
 STREAMIFY_DASHBOARD_PORT=8501
 DBT_THREADS=1

Makefile

@@ -6,7 +6,7 @@ VENV_STREAMLIT := $(VENV)/bin/streamlit
 ENV_RUN := $(VENV_PYTHON) scripts/run_with_dotenv.py
 DBT_PROFILES_DIR ?= dbt
 
-.PHONY: help setup token-help status ingest ingest-sample preflight dbt-deps dbt-build dashboard dashboard-smoke doctor report snapshot recommendations readiness readiness-real real-gate-smoke product-answers-smoke pages-site acceptance-local acceptance-real compose-smoke-local test up-local compose-check clean-local
+.PHONY: help setup token-help status ingest ingest-sample preflight dbt-deps dbt-build dashboard dashboard-smoke doctor report snapshot recommendations readiness readiness-real real-gate-smoke product-answers-smoke pages-site acceptance-local acceptance-real compose-smoke-local compose-smoke-real test up-local compose-check clean-local
 
 help:
 	@printf '%s\n' 'Streamify local Yandex Music self-analytics'
@@ -25,6 +25,7 @@ help:
 	@printf '%s\n' 'Docker Compose local profile:'
 	@printf '%s\n' '  make up-local'
 	@printf '%s\n' '  make compose-smoke-local'
+	@printf '%s\n' '  make compose-smoke-real    # requires YANDEX_MUSIC_TOKEN'
 	@printf '%s\n' ''
 	@printf '%s\n' 'Useful checks and exports:'
 	@printf '%s\n' '  make raw-contract     Validate raw JSONL/manifest contracts'
@@ -42,18 +43,7 @@ setup:
 	$(MAKE) dbt-deps
 
 token-help:
-	@printf '%s\n' 'Streamify needs a ready Yandex Music OAuth token in .env:'
-	@printf '%s\n' '  YANDEX_MUSIC_TOKEN=...'
-	@printf '%s\n' ''
-	@printf '%s\n' 'The installed yandex-music client only accepts a token; it does not obtain one.'
-	@printf '%s\n' 'Use an external Yandex Music OAuth token helper, then paste the token into .env.'
-	@printf '%s\n' ''
-	@printf '%s\n' 'Known community helper:'
-	@printf '%s\n' '  https://github.com/MarshalX/yandex-music-token'
-	@printf '%s\n' ''
-	@printf '%s\n' 'After saving .env, run:'
-	@printf '%s\n' '  make preflight'
-	@printf '%s\n' '  make acceptance-real'
+	$(ENV_RUN) -- $(VENV_PYTHON) scripts/yamusic_token_help.py
 
 status:
 	$(ENV_RUN) -- $(VENV_PYTHON) -m yamusic_ingest --status
@@ -119,6 +109,9 @@ acceptance-real: preflight ingest raw-contract dbt-build doctor report readiness
 compose-smoke-local:
 	$(ENV_RUN) -- $(VENV_PYTHON) scripts/smoke_compose_local.py
 
+compose-smoke-real:
+	$(ENV_RUN) -- $(VENV_PYTHON) scripts/smoke_compose_local.py --use-env-token
+
 test:
 	$(VENV_PYTHON) scripts/validate_dbt_quality.py
 	$(VENV_PYTHON) scripts/validate_yamusic_local.py

README.md

@@ -45,7 +45,7 @@ make dashboard
 Local defaults:
 
 - command guide: `make help`
-- token guide: `make token-help`
+- token guide: `make token-help`, which checks `.env`, installed `yandex-music` capabilities, and next steps without printing token values.
 - raw metadata: `data/raw/yamusic/*.jsonl`
 - local warehouse: `data/streamify.duckdb`
 - local configuration: `.env` is loaded by the Python CLI/scripts and by `scripts/run_with_dotenv.py` for Makefile commands, so token and path overrides work without Make parsing token values.
@@ -66,6 +66,7 @@ Local defaults:
 - safety guard: `scripts/check_no_local_sensitive_artifacts.py` keeps root `.env`, Yandex raw data, DuckDB files and local audio out of git.
 - raw schema contract: `make raw-contract`
 - Docker Compose smoke: `make compose-smoke-local`
+- real-account Docker Compose smoke: `make compose-smoke-real`, after `YANDEX_MUSIC_TOKEN` is set.
 - one-command container path: `make up-local`, which loads `.env` through `scripts/run_with_dotenv.py` and runs Docker Compose with the `local` profile. It uses real Yandex Music metadata when `YANDEX_MUSIC_TOKEN` is present in `.env`, otherwise it writes deterministic sample metadata.
 - local reset: `make clean-local` removes generated raw metadata, DuckDB databases, summary/snapshot/recommendations reports, dbt target/logs/packages, and smoke-test artifacts while preserving `.env` and source files.