chore: prepare v1 demo checkpoint

.gitignore

@@ -29,6 +29,8 @@ data/notegen.db-shm
 # DB 备份（e2e/迁移留存），同样含 bcrypt 哈希，严禁入库
 data/*.e2ebak
 data/user_notes/
+backups/*.zip
+.playwright-cli/
 models/
 models_msc_cache/
 wheels/

CHANGELOG.md

@@ -0,0 +1,75 @@
+# Changelog
+
+All notable project changes are tracked here.
+
+## v1.0.0-demo - 2026-06-25
+
+This is the first demo checkpoint for a reproducible local NoteGen release. The goal is not feature expansion; it is a stable version that can be built, smoked, demonstrated, and rolled back.
+
+### Added
+
+- Added `scripts/smoke_local.ps1` for local release smoke checks:
+  - Redis TCP availability.
+  - API `/api/health`.
+  - single worker process check.
+  - public notes API.
+  - optional login and private notes check.
+  - DOCX export endpoint.
+  - production web build.
+- Added local release documentation:
+  - `docs/SMOKE_TEST.md`
+  - `docs/DEPLOY_LOCAL.md`
+- Added v1 demo artifacts under `output/playwright/`:
+  - `v1-home.png`
+  - `v1-login-gate.png`
+  - `v1-workspace.png`
+  - `v1-demo.gif`
+  - `v1-export.docx`
+
+### Changed
+
+- Migrated the core QA entry in `web/components/ChatPanel.tsx` from legacy `--bg` / `--fg` / `--accent` tokens to Warm Fold `--wf-*` tokens.
+- Migrated the `/notes/[id]` workspace shell in `web/components/NoteWorkspace.tsx` to Warm Fold tokens for error state, skeleton state, top controls, right-side tools, and the mobile chapter drawer.
+- Migrated `web/components/CreateNotePanel.tsx`, used by `/notebooks`, from legacy tokens and `apple-button` to Warm Fold tokens.
+- Reworked `web/lib/progress.ts` to read chapter progress through `useSyncExternalStore`, keeping localStorage behavior while clearing the React hooks lint baseline.
+- Removed unused legacy visual components after confirming no runtime references:
+  - `web/components/AskBar.tsx`
+  - `web/components/FluidBG.tsx`
+  - `web/components/ParticleBG.tsx`
+
+### Fixed
+
+- Cleared blocking ESLint errors in:
+  - `web/components/ChatPanel.tsx`
+  - `web/lib/progress.ts`
+- Adjusted local smoke worker detection for Windows virtualenv behavior, where a venv shim and the real Python child process can both contain `run_worker.py` in their command line.
+- Adjusted DOCX smoke verification to use `Invoke-WebRequest -UseBasicParsing`, avoiding a Windows PowerShell null-reference failure on binary responses.
+
+### Verified
+
+Latest verified local commands:
+
+```powershell
+cd web
+npm run lint
+npm run test
+npx tsc --noEmit
+npm run build
+```
+
+Latest local smoke command:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\smoke_local.ps1
+```
+
+Smoke result at checkpoint time:
+
+- Failures: `0`
+- Warnings: login skipped unless `NOTEGEN_SMOKE_EMAIL` and `NOTEGEN_SMOKE_PASSWORD` are provided.
+
+### Known Baseline
+
+- `npm run lint` exits successfully but still reports non-blocking warnings for existing `<img>` usage and one unused ESLint disable directive outside the files touched for this checkpoint.
+- Learning progress is still localStorage-backed, not account-synchronized.
+- Full GPU video generation is intentionally not part of the automated smoke script; the script checks service readiness and lightweight API behavior.

README.md

@@ -116,6 +116,12 @@ cd web; npm run dev                         # 4. Web → http://localhost:3000
 
 输出在 `data/outputs/<video_id>.large-v3.neural.texttile.mm.vl.md`。
 
+## v1 checkpoint docs
+
+- [CHANGELOG.md](CHANGELOG.md) records the `v1.0.0-demo` checkpoint and known baseline.
+- [docs/SMOKE_TEST.md](docs/SMOKE_TEST.md) explains the local smoke path and expected results.
+- [docs/DEPLOY_LOCAL.md](docs/DEPLOY_LOCAL.md) documents the local deployment/startup flow.
+
 ## API 概览
 
 | 分组 | 端点 |

docs/DEPLOY_LOCAL.md

@@ -0,0 +1,199 @@
+# Local Deployment
+
+This document describes how to run NoteGen locally for the v1 demo checkpoint.
+
+## Architecture
+
+The local stack has four moving parts:
+
+```text
+Browser -> Next.js web (:3000)
+        -> FastAPI API (:8000)
+        -> Redis/RQ (:6379)
+        -> one Python worker for qa + default queues
+```
+
+The worker stays on the host machine because it owns the GPU path. Redis can run in Docker. The API and web app can run either directly on the host or through the `full` Docker Compose profile.
+
+## Prerequisites
+
+- Windows 11.
+- NVIDIA GPU for full video pipeline runs.
+- Python 3.10 virtualenv at `.venv`.
+- Node.js 18+ with dependencies installed in `web`.
+- Docker Desktop.
+- `ffmpeg` available on `PATH`.
+- Local model directories under `models/` for full pipeline and QA generation.
+
+Install dependencies:
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+cd web
+npm install
+```
+
+Install the CUDA PyTorch build separately when setting up a new machine:
+
+```powershell
+pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
+```
+
+## Recommended Local Demo Startup
+
+Open separate terminals from the repository root.
+
+Terminal 1: Redis
+
+```powershell
+docker compose up -d redis
+```
+
+Terminal 2: API
+
+```powershell
+.\.venv\Scripts\python.exe server.py
+```
+
+For a clean smoke run without automatic maintenance or backup side effects:
+
+```powershell
+$env:NOTEGEN_AUTO_MAINTENANCE="0"
+$env:NOTEGEN_AUTO_BACKUP="0"
+.\.venv\Scripts\python.exe server.py
+```
+
+Terminal 3: Worker
+
+```powershell
+.\.venv\Scripts\python.exe scripts\run_worker.py
+```
+
+Only run one worker. The v1 GPU model assumes serial execution across QA and generation jobs.
+
+Terminal 4: Web
+
+```powershell
+cd web
+npm run dev
+```
+
+Open:
+
+```text
+http://localhost:3000
+```
+
+## Production Build Check
+
+Before a demo checkpoint, verify the web app builds:
+
+```powershell
+cd web
+npm run lint
+npm run test
+npx tsc --noEmit
+npm run build
+```
+
+## Full Compose Option
+
+Redis, API, and web can be started through Docker Compose:
+
+```powershell
+docker compose --profile full up -d --build
+```
+
+The worker still runs on the host:
+
+```powershell
+.\.venv\Scripts\python.exe scripts\run_worker.py
+```
+
+Use the full Compose path when you want to test container wiring. Use the host path when you want the shortest local iteration loop.
+
+## Environment Variables
+
+Common local variables:
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `NOTEGEN_REDIS_URL` | `redis://127.0.0.1:6379/0` | Redis queue backend. |
+| `NOTEGEN_DB_PATH` | `data/notegen.db` | SQLite database path. |
+| `NOTEGEN_COOKIE_SECURE` | `0` | Set to `1` only behind HTTPS. |
+| `NOTEGEN_VERIFY_BASE` | `http://localhost:3000` | Base URL used in email verification links. |
+| `NOTEGEN_SMTP_HOST` / `NOTEGEN_SMTP_USER` / `NOTEGEN_SMTP_PASS` | unset | SMTP settings for real email verification. |
+| `NOTEGEN_AUTO_MAINTENANCE` | `1` | Set to `0` to stop startup/daily raw cleanup. |
+| `NOTEGEN_AUTO_BACKUP` | `1` | Set to `0` to stop startup/daily backup. |
+| `NOTEGEN_BACKUP_DIR` | `backups/` | Backup output directory. |
+| `NOTEGEN_MIN_FREE_RATIO` | `0.15` | Disk low-water mark. |
+| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | API URL baked into the web build. |
+
+## Health Check
+
+Verify API and Redis:
+
+```powershell
+Invoke-RestMethod http://127.0.0.1:8000/api/health
+```
+
+Expected shape:
+
+```json
+{
+  "ok": true,
+  "redis": true,
+  "queue_depth": 0,
+  "disk": {
+    "low": false
+  }
+}
+```
+
+Run the smoke script after all services are up:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File scripts\smoke_local.ps1
+```
+
+## Shutdown
+
+Stop Docker Redis:
+
+```powershell
+docker compose down
+```
+
+Stop host API, worker, and web processes with `Ctrl+C` in their terminals.
+
+If they were started in the background, find them with:
+
+```powershell
+Get-CimInstance Win32_Process |
+  Where-Object { $_.CommandLine -match 'server\.py|run_worker\.py|next' } |
+  Select-Object ProcessId,CommandLine
+```
+
+Then stop a specific process:
+
+```powershell
+Stop-Process -Id <pid>
+```
+
+## Git Hygiene
+
+Running the local stack can change runtime data:
+
+- Redis writes to `data/redis`.
+- API startup can create backups in `backups/`.
+- maintenance can remove old files under `data/raw` and `data/audio`.
+
+Before committing, check:
+
+```powershell
+git status --short
+```
+
+Do not include runtime data in a v1 code/docs commit unless that is the explicit intent.