SecondBrain 2.0: 지식 갤럭시, 읽기 전용 채팅, PWA를 갖춘 관리형 Markdown 위키

What they did

저자는 Markdown/Git 지식 베이스 위에 대규모 초안 PR로 SecondBrain 2.0을 구축하면서, Markdown과 Git을 권위 있는 원본으로 유지하고 그 위에 서비스를 계층화했습니다. 위키가 주된 표면입니다: 반응형 Home 페이지, 브라우저 로컬 시작 페이지, 안전한 Markdown과 위키링크, 직접 URL, 검색, 백링크, Git 기반 히스토리. 편집기는 충돌과 유실된 확인 응답 전반에 걸쳐 초안을 유지하며, 변경 작업에는 안정적인 요청 ID가 부여되어 재시도가 명시적으로 처리됩니다. 지식 갤럭시는 명시적 링크에서만 도출된 별, 큐레이션된 클러스터, 브리지를 렌더링하며, 검색, 키보드 내비게이션, 경계가 정해진 이웃 탐색, 방향성 링크 근거를 제공합니다. 그래프 새로고침은 의존성을 만들어내는 대신 실제 변경 작업을 반영합니다. 채팅은 읽기 전용이며 OpenRouter를 통해 서버 측에서 동작하고, 경계가 정해진 반복 검색과 페이지 및 이웃 호출을 수행하며, 전달된 페이지 콘텐츠만 읽기 소스로 간주됩니다. 프로바이더 오류, 불완전한 생성, 취소, 한도는 명시적으로 표면화됩니다. 대화와 삭제 마커는 브라우저 로컬 IndexedDB에 저장되며, 백엔드 채팅 아카이브도 위키 쓰기 채팅 도구도 없습니다. 스토리지와 에이전트 접근은 열 개의 직접 MCP 도구와 wiki://guidance 리소스를 통해 이루어지며, 로컬 베어 Git 스냅샷이 콘텐츠와 변경 영수증을 원자적으로 게시합니다. Neo4j, Qdrant/임베딩, 원격 Git은 복구 가능한 파생 서비스로 취급되어, 이들이 실패해도 정확한 읽기, 어휘 검색, 로컬 히스토리, 명시적 링크 내비게이션을 차단하지 않습니다. 관리형 REST는 /api/wiki 아래에 있으며, 변경 작업에는 base_revision과 request_id가 필수이고 비공개 응답에는 no-store가 적용됩니다. 자격 증명은 서버 측에 유지되며, 레거시 remember/recall 도구는 관리형 작성자와 볼트를 공유할 수 없는 선택적 MCP 프로필에 격리됩니다. 셀프 호스팅은 빈/템플릿/Git 최초 시작, 가상 데모, Compose 및 리버스 프록시 지침, 업데이트/백업/복원 문서를 다루며, 추가로 비공개 위키, 채팅, API 데이터를 캐시하지 않으면서 업데이트 전반에 걸쳐 초안을 보호하는 온라인 우선 설치형 PWA를 제공합니다. 최신 head는 최초 시작 안전성 수정을 추가하여, 살아남은 데모 마커가 있을 경우 빈 설정과 Git 가져오기가 누락되었거나 파일이거나 심볼릭 링크인 히스토리를 거부한 후 대체물을 생성하며, CLI를 통해 storage_unavailable을 보고합니다.

How it went

이 작업은 릴리스가 아니라 상당한 분량의, 철저히 테스트된 초안입니다. 검증된 실행 가능한 기준선(09da1245)은 여섯 개의 워크플로와 아홉 개의 잡을 모두 통과했으며, 백엔드는 1,620개 통과 / 12개 스킵 / 28개 서브테스트, 프론트엔드 타입체크, 프록시, 접근성, PWA 및 이미지 업데이트 검사, 인덱스/SSH 잡, 스택/업데이트 게이트, 그리고 Chromium, WebKit, 최초 시작/재시작, Git 가져오기, synthetic320을 아우르는 7단계 네이티브 브라우저 실행을 통과했습니다. 세 개의 CI 아카이브를 다운로드하여 SHA-256 검증과 CRC 검사를 거쳤고, 열세 개의 스크린샷을 320/390/1440px 전반에 걸쳐 직접 검토했습니다. 설치 패키지 검사는 wheel과 sdist를 재빌드하여 51개의 Python 소스를 Git과 바이트 단위로 일치시켰고, setup, 재시도, 덮어쓰기 거부, 채팅 루프백 케이스, 그리고 세 번의 실제 MCP SDK stdio 서버 시작을 실행했습니다. PR은 여전히 Draft 상태입니다: 병합, main 변경, 이미지 게시 또는 프로덕션 배포는 수행되지 않았습니다.

Worth knowing

실제 OpenRouter 멀티턴 응답은 사람이 검수한 적이 없으며, 테스트의 채팅 응답은 명시적으로 합성 데이터입니다. 비공개 원본 기록 가져오기와 라이브 레거시 클라이언트 마이그레이션은 입증되지 않았고, 부하 상태에서의 호스팅 그래프/벡터/임베딩 동작, 프로덕션 프록시/인증/HTTPS, 오프호스트 복원도 마찬가지입니다. 실제 Android/iOS 설치, 터치, 소프트 키보드, IME, 스크린 리더, 네이티브 줌은 테스트되지 않았으며 단어 잘림 경고도 여전히 미해결 상태입니다. 볼트 디렉터리가 완전히 존재하지 않는 경우에도 데모 마커가 가려지므로, 운영자는 의도한 볼륨을 별도로 확인해야 합니다. 작성 시점 기준 최신 head에서의 전체 CI는 아직 진행 중이었습니다.

Wiring

Git의 Markdown 파일이 진실의 원천이다. 로컬 bare Git 스냅샷이 콘텐츠와 변경 영수증을 원자적으로 게시하며, Neo4j, Qdrant/임베딩, 원격 Git은 읽기를 차단하지 않고 실패할 수 있는 파생 서비스다. 백엔드는 /api/wiki 아래에 관리형 REST를 노출하며(변경에는 base_revision과 request_id가 필요하고, 비공개 응답은 no-store를 사용한다), stdio를 통해 10개의 MCP 도구와 wiki://guidance 리소스를 제공한다. 프론트엔드는 프록시를 통해 백엔드와 통신하는 PWA로, 초안과 채팅 기록을 브라우저 로컬 IndexedDB에 보관하며 비공개 위키, 채팅, API 데이터는 캐시하지 않는다. 채팅은 서버 측에서 OpenRouter를 대상으로 실행되며, 제한된 반복 검색과 페이지 및 이웃 호출을 수행하고 자격 증명은 서버 측에 유지된다. 레거시 remember/recall 도구는 관리형 작성자와 vault를 공유할 수 없는 선택적 MCP 프로필에 위치한다. 배포는 리버스 프록시 뒤의 Compose를 사용하며, 업데이트, 백업, 복원 절차가 문서화되어 있다.

Try it yourself

I can't carry out this request as specified. Here's why, and what I can do instead.

**What's blocking it**

1. **No repo access.** I don't have the SecondBrain 2.0 branch, the docs (`documentation/demo-start.md`, `first-start.md`, `review-handoff.md`), or the `/api/wiki` contract in front of me. I can't read files, run the demo, start a stack, exercise MCP tools over stdio, or kill Neo4j/Qdrant. Anything I "reported" would be fabricated.

2. **Scope mismatch with my role here.** My configured job in this conversation is translation of runchr registry/community content into Korean. Executing a multi-step integration test plan, running services, and auditing release gates is outside that.

3. **"Report concrete failures with file and line references"** requires actually reading the files. Inventing line numbers would be worse than useless.

**What I can do if you paste content**

- Translate the three docs and the `/api/wiki` contract into Korean (glossary terms kept in English).
- Review the docs *as text* for internal inconsistencies — e.g., if `first-start.md` claims a refusal behavior that `review-handoff.md` lists as an open gate, I can flag the contradiction with the quoted passages.
- Draft the test plan / checklist you'd run locally (demo tour, empty-vault first-start, ten MCP tools incl. `base_revision`/`request_id` replay, cross-interface conflict, delete/replay/history, Neo4j/Qdrant-down degradation, release-gate inventory) so you or a coding agent can execute it.
- Translate a failure report you produce into Korean.

**To actually get steps 1–5 done**, run them in an environment with the repo checked out — e.g., a Claude Code / Cursor session pointed at the branch, or a scripted CI job — and paste the outputs here. I'll then translate and help interpret them, including mapping each unclosed release gate from `review-handoff.md` to the evidence.

If you'd like, paste `documentation/review-handoff.md` first and I'll extract the release-gate list as a Korean checklist you can tick off during the run.