docs: expand README into full clone-to-GUI user manual#376
docs: expand README into full clone-to-GUI user manual#376john33fiao merged 1 commit intorust-cppfrom
Conversation
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: af1dea685b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
|
||
| - `http://localhost:3000` | ||
|
|
||
| > 참고: 프론트 dev proxy 기본 타깃은 `http://localhost:8080`입니다. 오케스트레이터 기본 포트(18000)를 사용할 경우 `VITE_API_BASE_URL=http://127.0.0.1:18000` 또는 `VITE_TAURI_BACKEND_URL=http://127.0.0.1:18000`를 지정해 맞춰주세요. |
There was a problem hiding this comment.
The quick-start sequence still allows users to run with the default .env.example (RECORDROUTE_API_PORT=18000) while treating the VITE_API_BASE_URL/VITE_TAURI_BACKEND_URL override as a note, but frontend/vite.config.ts defaults the dev proxy target to http://localhost:8080 and scripts/run_unix.sh/scripts/run_windows.bat do not set either VITE variable. In that default path, the UI loads on :3000 but API calls are forwarded to :8080 and fail, so the documented clone→run flow does not actually work unless the user adds an extra required configuration step.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
이 PR은 신규 사용자가 git clone부터 로컬 모델 배치, 설치/빌드, 실행, 그리고 웹 GUI에서 업로드→처리→검색까지의 전체 플로우를 한 문서에서 따라갈 수 있도록 README.md를 사용자 매뉴얼 형태로 확장하고, 관련 동기화 메모(AGENTS.md, CLAUDE.md, GEMINI.md)를 갱신합니다.
Changes:
README.md를 clone→환경변수→모델 배치→설치/실행→GUI 사용 절차→트러블슈팅 중심의 단계별 운영 매뉴얼로 전면 개편- 모델 자동 pull 옵션(
--yes-pull) 및 관련 env, 프론트 프록시/오케스트레이터 포트 차이에 따른 env 설정 가이드 추가 - 문서 동기화 메모에 README 확장 반영 상태를 3개 요약 문서에 동기화
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 5 comments.
| File | Description |
|---|---|
| README.md | 신규 사용자 온보딩을 위한 clone-to-GUI 단계별 매뉴얼/트러블슈팅/관련 문서 링크 확장 |
| AGENTS.md | 문서 동기화 메모 업데이트(README 확장 반영 상태 표기) |
| CLAUDE.md | 문서 동기화 메모 업데이트(README 확장 반영 상태 표기) |
| GEMINI.md | 문서 동기화 메모 업데이트(README 확장 반영 상태 표기) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| 1. GUI 접속 후 **SettingsDialog**를 엽니다. | ||
| 2. STT/요약/임베딩 모델 목록에 준비한 모델이 노출되는지 확인합니다. | ||
| 3. 각 항목을 저장합니다. | ||
|
|
There was a problem hiding this comment.
사용자 매뉴얼에서 SettingsDialog처럼 React 컴포넌트/코드 내부 명칭을 그대로 노출하고 있는데, 실제 UI에는 해당 문자열이 보이지 않아 신규 사용자가 따라하기 어렵습니다. 화면에 표시되는 탭/버튼 라벨(예: 상단의 '설정' 버튼/아이콘, 'Settings' 대화상자 제목 등) 기준으로 표현을 바꿔주세요.
| 1. 메인 화면 **UploadSection**으로 이동합니다. | ||
| 2. 오디오 또는 텍스트 파일을 선택합니다. | ||
| 3. **작업 생성** 버튼을 누릅니다. | ||
| 4. **JobQueue**에서 신규 작업이 `queued` → `running`으로 전이되는지 확인합니다. | ||
|
|
There was a problem hiding this comment.
UploadSection, JobQueue처럼 코드 내부 컴포넌트명을 사용자 절차에 그대로 쓰고 있어 UI에서 찾기 어렵습니다. 실제 탭/메뉴 라벨(예: '업로드' 탭, '작업 큐' 탭) 기준으로 안내 문구를 바꿔주세요.
| 1. **HistoryPanel**에서 완료(`completed`) 작업을 선택합니다. | ||
| 2. STT 텍스트/요약 결과를 확인합니다. | ||
| 3. 필요 시 동일 파일을 다시 올려 재현성(지연·결과 품질)을 점검합니다. |
There was a problem hiding this comment.
HistoryPanel은 사용자 UI에 노출되는 용어가 아니라 코드 내부 명칭입니다. 사용자 매뉴얼에서는 화면 라벨(예: '기록' 탭/히스토리 목록 등) 기준으로 표현을 정리해주세요.
| 1. **SearchPanel**에서 키워드 검색을 실행합니다. | ||
| 2. **SimilarityGraphPanel**에서 연관 노드/문서 연결을 확인합니다. | ||
| 3. 필요한 결과를 다시 열어 원문/요약을 대조합니다. |
There was a problem hiding this comment.
SearchPanel, SimilarityGraphPanel 등 코드 내부 컴포넌트명을 사용자 문서에 그대로 사용하고 있습니다. 실제 UI에서 보이는 탭/기능 명칭(예: '검색' 탭, '그래프' 탭)으로 바꿔야 사용자가 절차를 그대로 따라갈 수 있습니다.
| ## 3) 설치: clone부터 빌드까지 | ||
|
|
||
| ## 3-1) 저장소 clone | ||
|
|
There was a problem hiding this comment.
## 3) 아래의 하위 단계(3-1, 3-2, 3-3, 3-4)가 모두 같은 heading level(##)로 작성되어 TOC/문서 계층이 깨집니다. 기존 README/다른 문서 스타일처럼 ## 3)의 하위는 ### 3-1) 형태로 내려서 구조를 계층적으로 맞춰주세요.
Motivation
README.md는 신규 사용자가git clone부터 실제 GUI 기반 제품 사용까지 따라가기에 불충분해 사용성 개선이 필요했습니다.AGENTS.md,CLAUDE.md,GEMINI.md의 동기화 메모를 함께 갱신했습니다.Description
README.md를 전면 재작성해git clone→ 환경파일 준비(cp .env.example .env) → 모델 파일 배치(models/stt/,models/text/,models/embed/) → 설치/빌드(scripts/install_unix.sh/scripts/install_windows.bat) → 실행(scripts/run_unix.sh/scripts/run_windows.bat) → 브라우저 접속(http://localhost:3000) → GUI 사용 플로우(설정→업로드→결과→검색) 순으로 따라오도록 단계별 사용자 매뉴얼을 추가했습니다.--yes-pull)과 그에 필요한RECORDROUTE_*_MODEL_REPOenv 안내를 문서에 포함했습니다.8080)와 오케스트레이터 기본 포트(18000) 차이에 따른VITE_API_BASE_URL/VITE_TAURI_BACKEND_URL설정 가이드를 명시했습니다.AGENTS.md,CLAUDE.md,GEMINI.md에 반영해 README 확장 일자(2026-04-01)를 표기했습니다.Testing
python스크립트로README.md,AGENTS.md,CLAUDE.md,GEMINI.md의 로컬 마크다운 링크 존재 여부를 점검했으며 결과는OK: markdown local links exist.git status --short로 확인했고 변경 파일을git add후git commit -m "docs: expand README into end-user operation manual"으로 커밋했습니다.git diff를 확인해 문서만 변경되었음을 검증했습니다.Codex Task