# ConnectAI — Project Architecture Context

<!-- ASTRA:AUTO-START -->

## Snapshot
- **Workspace**: `ConnectAI` `v2.2.247` _(absolute path varies by environment; resolved from the active VS Code workspace)_
- **Description**: The personal intelligence layer for Antigravity and VS Code. A private cognitive partner for deep project context, memory, and proactive strategic decision-making.
- **Stack**: TypeScript, Node.js, VS Code Extension, LM Studio SDK, Test runner
- **Stats**: 560 source files, ~83,576 lines across 5 top-level modules.

## Last Refresh
- **Time**: 2026-06-12T14:30:58.311Z
- **Files newly analysed**: 3
- **Files reused from cache**: 557

## Directory Map
```mermaid
mindmap
  root((ConnectAI))
    src/
      features/
      sidebar/
      lib/
      agent/
      intelligence/
      retrieval/
    media/
    tests/
      helpers/
      integration/
      mocks/
    core_py/
    docs/
      records/
      docs/
      plans/
```

## Module Dependencies
> Arrows: which top-level module imports from which.
```mermaid
flowchart LR
    src["src/<br/>317 files"]
    media["media/<br/>6 files"]
    tests["tests/<br/>58 files"]
    core_py["core_py/<br/>6 files"]
    docs["docs/<br/>173 files"]
    tests --> src
```

## Entry Points
> Files to read first when learning the codebase.
- `src/extension.ts`
- `media/sidebar.html` — Astra
- `package.json` — npm package manifest

## Hub Files
> Imported by many other files — touching these has wide blast radius.
- `src/utils.ts` — referenced by **102** files
- `src/config.ts` — referenced by **38** files
- `src/agent.ts` — referenced by **34** files
- `src/core/services.ts` — referenced by **17** files
- `src/features/company/index.ts` — referenced by **14** files · Public API for 1인 기업 모드. Consumers (sidebarProvider, chatHandlers, command handlers) import from this barrel so internal layout can move around without touching every call site.
- `src/features/company/types.ts` — referenced by **14** files · Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
- `src/retrieval/brainIndex.ts` — referenced by **12** files · Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-IDF 점수를 계산했습니다 — 파일 수가 많아지면 그게 병목입니다. 이 모듈은 <brainPath>/.astra/brain-index.json 에
- `src/integrations/telegram/telegramClient.ts` — referenced by **12** files

## Modules

### `src/` — 317 files, ~61,263 lines

**Sub-directories**
- `src/features/` (112) — Generic event-sourced store — append-only .jsonl 파일 1개를 읽고/쓰는 공통 기반. 배경: customers, hire, runway, feedback 4개 store 가 같은
- `src/sidebar/` (35) — Brain profile lifecycle 의 pure helpers — sidebarProvider 의 add/edit/delete 흐름에서 modal UI 와 config 쓰기를 제외한 데이터 변환 만 격리. 현
- `src/lib/` (33) — Astra Mode Architecture Context Builder. 의도: 사용자가 Astra 자체의 mode 디자인 (Guard vs Multi-Agent 가 별도 모드여야 하는지) 을 묻는 메타 질문에 답할
- `src/agent/` (31) — 한·영 깨진 토큰 감지·수리 — 소형 로컬 모델의 토큰 붕괴 보정. 증상: 한국어 단어 중간에 영문 토큰이 섞임 — "덩어리"→"덩ey", "결과적으로"→"결ently". 프롬프트 규칙([출력 위생])으로는 못 막는
- `src/intelligence/` (18) — Confidence Engine — 답변 확신도 0~100 결정론적 산출. Self-Evolving OS 마스터 플랜 Phase 2 / Track 1-1. 신뢰 조건 T4 "확신이 없으면 사람에게 묻는다" 의 측정 
- `src/retrieval/` (18) — Actionability Scoring — 검색 결과를 "현재 작업 상태" 신호로 재가중. 기존 TF-IDF (단어 매칭) + recency (시간) 만으로는 "지금 이 사용자가 하고 있는 작업과 직접 연결 된 문서
- `src/core/` (15) — Astra Path Resolver (경로 해결기) Astra의 모든 데이터 파일(.astra 디렉토리)의 경로를 중앙에서 관리합니다. 확장 프로그램의 설치 경로(extensionUri) 기반으로 .astra 디렉토
- `src/extension/` (13) — 두뇌(Second Brain) 기본 위치 부트스트랩 — 첫 실행 온보딩. 문제: 두뇌 미설정 시 config 가 ~/.g1nation-brain(숨김 점폴더)로 조용히 폴백했다. - 폴더가 실제로 생성되지 않고, 설
- `src/memory/` (9) — Episodic Memory (일화 기억) 과거 대화/회의/결정의 맥락 흐름을 저장합니다. 세션 종료 시 자동으로 에피소드를 요약하여 저장합니다. "왜 이렇게 결정했는지", "어떤 흐름으로 진행했는지" 기록. 저장 
- `src/docs/` (6) — src Chronicle Records
- `src/integrations/` (6) — Per-chat conversation history for the Telegram bot. Why this exists: the previous bot was stateless — every inbound mess
- `src/lmstudio/` (4) — 4 files (.ts)

**Key files**
- `src/utils.ts` (485 lines)
- `src/config.ts` (661 lines)
- `src/agent.ts` (1670 lines)
- `src/features/company/types.ts` (446 lines) — Type definitions for the 1인 기업 (One-Person Company) mode. The mode turns the user into a virtual CEO that dispatches work to a roster of specialist agents. Each turn produces a session directory conta
- `src/core/services.ts` (176 lines)
- `src/sidebarProvider.ts` (3487 lines)
- `src/integrations/telegram/telegramClient.ts` (154 lines)
- `src/agent/actions/types.ts` (41 lines)
- `src/lib/contextManager.ts` (278 lines) — Context Manager (컨텍스트 한계 관리) "context length = 132k" 는 "답변을 132k 토큰까지 생성해도 된다" 가 아닙니다. 시스템 프롬프트 + 대화 기록 + 입력 문서 + 생성될 답변 + 여유분 ≤ context length 이 모듈은 요청을 보내기 전에 입력 토큰을 추정하고, - 동적으로 출력 상한(maxTokens)을 계
- `src/retrieval/brainIndex.ts` (566 lines) — Brain Index — persistent, mtime-keyed tokenized cache of the Second Brain RAG 검색은 매 질의마다 브레인의 모든 .md 파일을 읽고 토크나이즈해서 TF-IDF 점수를 계산했습니다 — 파일 수가 많아지면 그게 병목입니다. 이 모듈은 <brainPath>/.astra/brain-index.json 에
- `src/retrieval/scoring.ts` (541 lines) — Scoring Engine — TF-IDF + Bilingual Tokenizer 단순 includes() 키워드 매칭을 넘어서, TF-IDF 가중치 기반의 문서 스코어링을 제공합니다. 한국어/영어 양국어 토크나이저를 포함합니다.
- `src/features/company/companyConfig.ts` (896 lines) — State + config plumbing for 1인 기업 모드. Two surfaces: - CompanyState (runtime data: enabled flag, company name, which agents are active, per-agent model overrides). Persisted in VS Code's globalState so
- `src/lib/paths.ts` (151 lines)
- `src/skills/agentKnowledgeMap.ts` (374 lines)
- `src/features/datacollect/slashRouter.ts` (201 lines)
- `src/retrieval/types.ts` (66 lines) — Retrieval Types (검색 결과 통합 타입) 모든 검색 소스(Brain, Memory, Project, Episode)의 결과를 통합 인터페이스로 정의합니다.
- `src/intelligence/requirementGraph.ts` (273 lines) — Requirement Graph — 업무 유형별 필수 요소 정의 + 감지 + 커버리지 검사. Self-Evolving Digital Employee OS 마스터 플랜(docs/SELFEVOLVINGOSMASTERPLAN.md) Phase 1 / Track 2-1. 신뢰 조건 T3 "품질이 일관적이다 — 필수 요소 누락 없음" 담당. 동작 2단계: 1. In
- `src/lib/contextBuilders/promptDetection.ts` (107 lines) — 사용자 prompt 의 의도 분류 류 detection helpers. 모두 stateless 정규식 매칭. 옛 코드는 agent.ts 의 private 메서드로 박혀 있었는데, system prompt 빌더 (buildJarvisProjectBriefContext 등) 가 이걸 의존하면서 god-file 안에서 서로 얽힘. 헬퍼만 먼저 떼면 의존 그래프가
- `src/memory/types.ts` (151 lines) — Memory Type Definitions (메모리 타입 정의) Astra의 5-Layer Cognitive Memory System의 모든 타입을 정의합니다. ① Short-Term ② Long-Term ③ Project ④ Procedural ⑤ Episodic
- `src/features/stocks/types.ts` (53 lines) — Stocks 모듈 공유 타입. investresults/targetstocks.json 스키마를 그대로 받아서, ConnectAI 의 <workspace>/.astra/stocks.json 으로 옮긴 뒤 같은 필드명을 유지. 한글 필드명은 사용자의 도메인 데이터라 변경하지 않는다 — 마이그레이션 충돌 회피 + 사용자가 직접 JSON 편집할 때 frictio
- `src/retrieval/lessonHelpers.ts` (325 lines) — Lesson / Experience Memory — pure helpers (no vscode dependency) "Lesson" = a markdown file in the active brain that captures a past mistake/risk and how to avoid repeating it. Identified by a lessons
- `src/intelligence/confidenceEngine.ts` (165 lines) — Confidence Engine — 답변 확신도 0~100 결정론적 산출. Self-Evolving OS 마스터 플랜 Phase 2 / Track 1-1. 신뢰 조건 T4 "확신이 없으면 사람에게 묻는다" 의 측정 기반 — Escalation Engine 의 입력. 설계 원칙 (termValidator 와 동일): LLM 호출 없음. 검색 그라운딩 신호(턴
- `src/intelligence/reflectionStore.ts` (162 lines) — Reflection Store — 업무 turn 회고 기록 + Failure Pattern 집계. Self-Evolving OS 마스터 플랜 Phase 1 / Track 2-4 (Reflection Engine v1) + Phase 3 / Track 3-6 (Failure Pattern DB v1 시드). 신뢰 조건 T5 "같은 실수를 반복하지 않는다" 의
- `src/extension/telegramCommands.ts` (103 lines)
- `src/security.ts` (159 lines)

### `media/` — 6 files, ~7,799 lines

**Key files**
- `media/sidebar.css` (2114 lines) — Stylesheet
- `media/sidebar.js` (3947 lines)
- `media/sidebar.html` (539 lines) — Astra
- `media/settings-panel.html` (440 lines) — Astra Settings
- `media/settings-panel.js` (505 lines)
- `media/settings-panel.css` (254 lines) — Stylesheet

### `tests/` — 58 files, ~8,276 lines
*Depends on*: `src/`

**Sub-directories**
- `tests/helpers/` (1) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스
- `tests/integration/` (1) — MockLLMClient 자체의 sanity test. 이게 통과하면 dispatcher / ceoPlanner / ChunkedWriter 등 IAIService 를 받는 코드가 실제 LLM 없이 단위 / inte
- `tests/mocks/` (1) — 1 files (.js)

**Key files**
- `tests/helpers/mockLLMClient.ts` (112 lines) — MockLLMClient — IAIService 의 Mock 구현체. 의도: 회사 모드 dispatcher / ChunkedWriter / ceoPlanner 등 LLM 을 호출하는 코드 경로를 CI 환경에서도 테스트 가능하게. 실제 Ollama / LM Studio 없이도 응답을 미리 정의하거나 동적으로 생성 가능. 사용 예: const ai = new 
- `tests/agentEngine.test.ts` (413 lines) — AgentEngine Tests — Chunked Writer Architecture 예전 buildup(planner → researcher → reflector → writer → synthesizer)을 단일 ChunkedWriter 의 outline → section[N] → polish 로 교체한 뒤의 회귀 테스트. 다루는 범위: 1. ErrorC
- `tests/lmStudioLifecycle.test.ts` (330 lines) — Unit tests for ModelLifecycleManager. Strategy: inject mock ILMStudioClient and a simple in-memory IActivityTracker. No real LM Studio or SDK is touched — the manager file does not import the SDK dire
- `tests/localPathPreflight.test.ts` (520 lines)
- `tests/telegramBot.test.ts` (363 lines) — Unit tests for TelegramBot + truncateForTelegram. Strategy: - TelegramBot is driven by an injected ITelegramClient stub. We script getUpdates to return queued batches and assert that: - the offset cur
- `tests/criticReflectionEval.test.ts` (200 lines) — Critic Agent / Reflection Store / Task Eval Harness (Self-Evolving OS P1 잔여 + P3) 테스트.
- `tests/lmStudioStreamer.test.ts` (222 lines) — Unit tests for LMStudioStreamer. Strategy: inject a fake ILMStudioClient that returns a fake model handle whose respond() yields a controllable async iterable. No real SDK or WebSocket touched.
- `tests/secondBrainTrace.test.ts` (407 lines)
- `tests/approvalQueue.test.ts` (164 lines) — Unit tests for ApprovalQueue. Strategy: drive enqueue → approve / reject / clear / pre-empt directly, confirm the onChange event fires at the right moments and callbacks fire exactly once.
- `tests/confidenceEngine.test.ts` (175 lines) — Confidence Engine + Escalation Engine (Self-Evolving OS Phase 2) 단위 테스트. 순수 함수만 검증 — vscode 의존 없음.
- `tests/correctionLoop.test.ts` (158 lines) — Correction Loop 단위 테스트 — 순수 로직 (감지·프로필·레슨·큐 등록·영속화). LLM 의존 부분(classifyCorrection)은 엔드포인트 실패 → 휴리스틱 fallback 경로만 검증.
- `tests/knowledgeOps.test.ts` (174 lines) — Knowledge Validation / Belief Revision / Decay / Debt (Self-Evolving OS Phase 4 — 지식 운영) 테스트.
- `tests/meetRegistration.test.ts` (110 lines) — /meet 확신 게이트 — 분류·confirm 파싱·날짜 정규화 테스트. 정책: 확정+기한만 자동, 진행미정/기한미정/조건부는 보류, 반복은 첫 1회, 과거 날짜는 등록하되 완료확인 표기, 기한 해석 불가 확정건은 보류(추측 등록 금지).
- `tests/needEngineQueue.test.ts` (159 lines) — Gap Detector / Need Engine / Knowledge Inventory / Learning Queue (Self-Evolving OS Phase 3 — 성장 루프 코어) 테스트.
- `tests/projectScaffolder.test.ts` (135 lines) — Unit tests for FileSystemProjectScaffolder. Drives against a real temp directory so end-to-end file IO + path-traversal defenses are exercised.
- `tests/requirementGraph.test.ts` (126 lines) — Requirement Graph (Self-Evolving OS Phase 1 / Track 2-1) 단위 테스트. 순수 함수만 검증 — vscode 의존 없음.
- `tests/researchSkill.test.ts` (122 lines) — Research Agent / Skill Score / Success Pattern DB (Self-Evolving OS Phase 6) 테스트.
- `tests/resilience_stress.test.ts` (197 lines) — Resilience & Boundary Stress Test Suite (v2.77.3) 이 테스트는 ConnectAI 엔진이 극한의 환경(인증 실패, 네트워크 차단, 타임아웃 등)에서 얼마나 안정적으로 복구되고, 신뢰성 지표(Resilience Metrics)를 정확히 기록하는지 검증합니다.
- `tests/retrievalEvalEmbedding.test.ts` (106 lines) — 하이브리드(sparse+dense) 검색 측정 — 청크 TF-IDF vs 청크+임베딩 (alpha sweep). 평소 테스트 런에서는 skip (실제 두뇌 + 로컬 임베딩 서버 필요). 수동 실행: ASTRAEVALBRAIN="E:/Wiki/2nd/10Wiki/Topics" \ ASTRAEVALEMBEDMODEL="text-embedding-nomic-em
- `tests/skillInjectionService.test.ts` (172 lines) — Unit tests for FileSystemSkillInjectionService. Strategy: drive the service against a real temp directory so path-traversal defenses and writeFileSync paths are exercised end-to-end. The service accep
- `tests/sleepDigest.test.ts` (101 lines) — Sleep-time 사전 소화 — 순수 로직 테스트 (대상 선정·노후화 판정·노트 형식). LLM 호출(runSleepDigestOnce)은 제외 — 통합 검증은 수동 명령으로.
- `tests/stocksCriteria.test.ts` (129 lines) — criteriaEval — /stocks judge 결정론 평가기 테스트. 픽스처는 옛 LLM 프롬프트에 명시돼 있던 사용자의 실제 분류 예시 3종 (마녀공장/기가비스/엔켐) — 코드 판정이 사용자 패턴과 일치해야 한다.
- `tests/alignmentResearch.test.ts` (208 lines)
- `tests/conflictCheck.test.ts` (65 lines) — Schedule Conflict Check (Self-Evolving OS Track 6-2/6-3) 테스트.
- `tests/dataProcessor.test.ts` (87 lines) — / <reference types="jest" />

### `core_py/` — 6 files, ~409 lines

**Key files**
- `core_py/events.py` (64 lines)
- `core_py/inference.py` (91 lines)
- `core_py/loader.py` (61 lines)
- `core_py/monitoring.py` (56 lines)
- `core_py/optimizer.py` (55 lines)
- `core_py/queue_worker.py` (82 lines)

### `docs/` — 173 files, ~5,829 lines

**Sub-directories**
- `docs/records/` (157) — Astra Project Chronicle Records
- `docs/docs/` (5) — docs Chronicle Records
- `docs/plans/` (2) — Alignment Self-Learning 개선 계획 (v2 — 적대적 리뷰 반영)

**Key files**
- `docs/TELEGRAM_REMOTE_EXECUTION_PLAN.md` (452 lines) — Telegram Remote Execution 기획서
- `docs/records/ConnectAI/timeline.md` (422 lines) — Project Timeline
- `docs/AgentEngine_Architecture.md` (314 lines) — AgentEngine Architecture Document
- `docs/SELF_EVOLVING_OS_MASTER_PLAN.md` (275 lines) — ASTRA Self-Evolving Digital Employee OS — 마스터 개발 계획 v1.1
- `docs/ASTRA_OFFICE_REFACTOR.md` (198 lines) — Astra Office Refactor — Design Doc
- `docs/EXPERIENCE_MEMORY_PLAN.md` (122 lines) — Experience Memory (Mistake / Lesson Loop) — Implementation Plan
- `docs/plans/alignment-self-learning-plan.md` (194 lines) — Alignment Self-Learning 개선 계획 (v2 — 적대적 리뷰 반영)
- `docs/plans/web-fetch-and-mode-parity-plan.md` (102 lines) — 웹 접근 + 모드 동등성 수정 계획 (v2 — 적대적 리뷰 + 재검증 반영)
- `docs/records/ConnectAI/development/2026-05-02_connectai_project_knowledge_overview.md` (121 lines) — Astra Project Knowledge Overview
- `docs/records/ConnectAI/development/2026-05-03_connectai_project_knowledge_overview.md` (121 lines) — Astra Project Knowledge Overview
- `docs/Advanced_Features_Implementation_Guide.md` (40 lines) — Advanced Features Implementation Guide
- `docs/PROJECT_CHRONICLE_GUARD_ROADMAP.md` (43 lines) — Project Chronicle Guard: Search Engine Roadmap
- `docs/UX_UI_Consistency_Guidelines.md` (44 lines) — UX/UI Consistency Guidelines
- `docs/docs/records/docs/README.md` (18 lines) — docs Chronicle Records
- `docs/docs/records/docs/bugs/BUG-0001-viewed-integration-retrieval-test-ts-1-59-integration-retrie.md` (16 lines) — Bug: Viewed integrationretrieval.test.ts:1-59 integrationretrieval.test.ts를 통해 ...
- `docs/docs/records/docs/chronicle.config.json` (11 lines) — JSON configuration
- `docs/docs/records/docs/project-profile.md` (31 lines) — Project Profile
- `docs/docs/records/docs/timeline.md` (7 lines) — Project Timeline
- `docs/records/ConnectAI/README.md` (18 lines) — Astra Project Chronicle Records
- `docs/records/ConnectAI/bugs/BUG-0001-volumes-data-project-antigravity-connectai-프로젝트-코드-리뷰-해줄-수-있.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 프로젝트 코드 리뷰 해줄 수 있어? 개선할 부분이 있는지, 그러고...
- `docs/records/ConnectAI/bugs/BUG-0002-지금-내가-분석-요청하고-너가-답을-줄때-아래-템플릿에-맞춰-답을-써주고-있는데-개선-포인트가-있는지-확인해.md` (16 lines) — Bug: 지금 내가 분석 요청하고 너가 답을 줄때 아래 템플릿에 맞춰 답을 써주고 있는데, 개선 포인트가 있는지 확인해줘. ## 내가 보는 위험 가장 큰...
- `docs/records/ConnectAI/bugs/BUG-0003-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0004-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...
- `docs/records/ConnectAI/bugs/BUG-0005-다시한번-답줘-volumes-data-project-antigravity-connectai-내-질문에-대한-.md` (16 lines) — Bug: 다시한번 답줘. /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는...
- `docs/records/ConnectAI/bugs/BUG-0006-volumes-data-project-antigravity-connectai-내-질문에-대한-답변이-잘-정리.md` (16 lines) — Bug: /Volumes/Data/project/Antigravity/ConnectAI 내 질문에 대한 답변이 잘 정리되서 알려주긴 하는데 focused...

## VS Code Extension Surface
- **Extension ID**: `g1nation.astra`
- **Activation events**: `onStartupFinished`
- **Commands** (39):
  - `g1nation.newChat` — Astra: New Chat
  - `g1nation.eval.retrieval` — Astra: 검색 평가 실행 (recall@k / MRR)
  - `g1nation.eval.tasks` — Astra: 업무 평가 실행 (회의록 골든셋)
  - `g1nation.growth.report` — Astra: 성장 리포트 (Reflection 추이)
  - `g1nation.growth.learningQueue` — Astra: 학습 큐 갱신 (Need Engine)
  - `g1nation.knowledge.decayAudit` — Astra: 지식 노후 점검 (Knowledge Decay)
  - `g1nation.research.runQueue` — Astra: 학습 실행 (Research Agent — 승인된 큐 항목)
  - `g1nation.growthCycle.runNow` — Astra: 주간 성장 사이클 지금 실행 (평가→학습큐→노후점검→승인분 실행)
  - `g1nation.embeddings.backfill` — Astra: 두뇌 임베딩 전체 색인
  - `g1nation.sleepDigest.runNow` — Astra: 지식 사전 소화 지금 실행 (Sleep-time Digest)
  - `g1nation.conflictScan.runNow` — Astra: 지식 충돌 스캔 지금 실행 (신규 문서 ↔ 기존 지식)
  - `g1nation.exportChat` — Astra: Export Chat as Markdown
  - `g1nation.explainSelection` — Astra: Explain Selected Code
  - `g1nation.focusChat` — Astra: Focus Chat Input
  - `g1nation.showBrainNetwork` — Astra: Show Brain Topology
  - `g1nation.approval.focus` — Astra: Focus Approval Panel
  - `g1nation.scaffoldProject` — Astra: Scaffold New Project
  - `g1nation.telegram.setBotToken` — Astra: Set Telegram Bot Token
  - `g1nation.telegram.clearBotToken` — Astra: Clear Telegram Bot Token
  - `g1nation.telegram.testConnection` — Astra: Test Telegram Connection
  - `g1nation.settings.focus` — Astra: Open Settings Panel
  - `g1nation.skills.editKnowledgeMap` — Astra: Edit Agent ↔ Knowledge Map
  - `g1nation.openChat` — Astra: Open Chat (Editor Column)
  - `g1nation.setupDatacollect` — Astra: Setup Datacollect Dependencies (yt-dlp, youtube-transcript-api)
  - `g1nation.lesson.create` — Astra: New Lesson (Experience Memory)
  - `g1nation.lesson.fromConversation` — Astra: New Lesson from Current Conversation
  - `g1nation.lesson.manage` — Astra: Browse / Manage Lessons
  - `g1nation.architecture.refresh` — Astra: Refresh Project Architecture Context
  - `g1nation.architecture.detach` — Astra: Detach Project Architecture Context
  - `g1nation.architecture.attach` — Astra: Attach Project Architecture Context
  - `g1nation.architecture.open` — Astra: Open Project Architecture Doc
  - `g1nation.company.toggle` — Astra: Toggle 1인 기업 Mode
  - `g1nation.company.manage` — Astra: Manage 1인 기업 Agents
  - `g1nation.company.openSessions` — Astra: Open 1인 기업 Sessions Folder
  - `g1nation.company.pixelOffice.open` — Astra: Open Pixel Office (Full Screen)
  - `g1nation.calendar.connect` — Astra: Google Calendar (iCal) 연결 📅
  - `g1nation.calendar.refresh` — Astra: Google Calendar 새로고침 📅
  - `g1nation.calendar.connectOAuth` — Astra: Google Calendar OAuth 연결 (쓰기) 🔐
  - `g1nation.devilAgent.toggle` — Astra: Toggle Devil Agent 🎭
- **Configuration** (149 settings):
  - `g1nation.multiAgentEnabled` *(boolean)* _(default: `false`)_ — Enable Multi-Agent Workflow (Planner -> Researcher -> Writer) for complex tasks.
  - `g1nation.datacollectBridgeTarget` *(string)* _(default: `"local"`)_
  - `g1nation.datacollectBridgeUrl` *(string)* _(default: `"http://127.0.0.1:3002"`)_ — [local 타깃] Wiki/Datacollect MCP Bridge URL. /benchmark, /youtube, /wikify chat slash commands route here. The Bridge must be running (`npm run bridge` in the Datacollect project).
  - `g1nation.datacollectBridgeNasUrl` *(string)* _(default: `""`)_
  - `g1nation.datacollectBridgeNasToken` *(string)* _(default: `""`)_
  - `g1nation.datacollectSavePath` *(string)* _(default: `""`)_
  - `g1nation.datacollectCrawlDepth` *(number)* _(default: `1`)_
  - `g1nation.datacollectMaxPages` *(number)* _(default: `8`)_
  - `g1nation.datacollectSynthesisTemperature` *(number)* _(default: `0.1`)_
  - `g1nation.chatTemperature` *(number)* _(default: `0.3`)_
  - `g1nation.meetUsesTasks` *(boolean)* _(default: `true`)_
  - `g1nation.meetUsesCalendar` *(boolean)* _(default: `false`)_
  - `g1nation.meetVerifyPass` *(boolean)* _(default: `false`)_
  - `g1nation.dailyBriefing.enabled` *(boolean)* _(default: `true`)_
  - `g1nation.dailyBriefing.time` *(string)* _(default: `"09:30"`)_
  - `g1nation.sleepDigest.enabled` *(boolean)* _(default: `true`)_
  - `g1nation.sleepDigest.time` *(string)* _(default: `"03:00"`)_
  - `g1nation.growthCycle.enabled` *(boolean)* _(default: `true`)_
  - `g1nation.growthCycle.day` *(number)* _(default: `0`)_
  - `g1nation.growthCycle.time` *(string)* _(default: `"20:00"`)_
  - `g1nation.growthCycle.autoRunApproved` *(boolean)* _(default: `true`)_
  - `g1nation.teamVoiceGuide` *(string)* _(default: `""`)_
  - `g1nation.memoryEnabled` *(boolean)* _(default: `true`)_ — Enable layered memory injection before each model response.
  - `g1nation.memoryShortTermMessages` *(number)* _(default: `8`)_ — Number of recent conversation messages included as short-term memory.
  - `g1nation.memoryMediumTermSessions` *(number)* _(default: `5`)_ — Number of recent saved chat sessions included as medium-term memory.
  - `g1nation.memoryLongTermFiles` *(number)* _(default: `6`)_ — Number of relevant Second Brain markdown files included as long-term memory.
  - `g1nation.ollamaUrl` *(string)* _(default: `"http://127.0.0.1:11434"`)_ — Base URL for Ollama or LM Studio. Default: http://127.0.0.1:11434
  - `g1nation.defaultModel` *(string)* _(default: `"gemma4:e2b"`)_ — Default model name to use for chat requests.
  - `g1nation.requestTimeout` *(number)* _(default: `300`)_ — Request timeout in seconds. Default: 300
  - `g1nation.contextLength` *(number)* _(default: `32768`)_ — Model context window in tokens (prompt + generation combined). Set this to the value your loaded model is actually running with in LM Studio / Ollama. Astra budgets prompt and output against this so i
  - `g1nation.maxOutputTokens` *(number)* _(default: `4096`)_ — Upper bound on tokens generated per response. The effective limit is reduced automatically when the prompt is large so input + output stays within g1nation.contextLength. Default: 4096
  - `g1nation.contextSafetyMargin` *(number)* _(default: `2048`)_ — Tokens kept free as a safety buffer for token-count estimation error. Default: 2048
  - `g1nation.contextOverflowPolicy` *(string)* _(default: `"stopAtLimit"`)_ — Fallback behavior (LM Studio) if the prompt still exceeds the context window after Astra's own budgeting. 'stopAtLimit' fails clearly so you notice; 'truncateMiddle'/'rollingWindow' drop content silen
  - `g1nation.autoCompactHistory` *(boolean)* _(default: `true`)_ — Automatically drop the oldest conversation messages from the request when the prompt would exceed the context budget (the on-screen chat history is unaffected). Default: true
  - `g1nation.smallModelContextCap` *(number)* _(default: `0`)_ — Optional safety knob, OFF by default (0). Some very small models (≤3B) emit an empty/EOS response when given a prompt near their context window even though it nominally fits. If you observe that with 
  - `g1nation.autoContinueOnOutputLimit` *(boolean)* _(default: `true`)_ — When a reply is cut off because it hit the output-token limit, Astra continues it internally (compressed request — original question + the answer so far, not the whole context again) and shows one mer
  - `g1nation.maxAutoContinuations` *(number)* _(default: `4`)_ — Maximum number of automatic continuation rounds per reply (prevents runaway loops). Raise it (e.g. 5–6) for long-form answers on slow local models; set 0 to disable auto-continuation. Default: 4
  - `g1nation.finalOnlyRetryOnThoughtLeak` *(boolean)* _(default: `true`)_ — If the model emits only hidden reasoning (<think>, <|channel|>thought, "Thinking Process:" …) and no user-visible answer, Astra silently re-asks it for the final answer only. Hidden reasoning is never
  - `g1nation.lmStudio.idleTimeoutMs` *(number)* _(default: `300000`)_ — Auto-eject the loaded LM Studio model after this many milliseconds of inactivity. Set to 0 to disable. Default: 300000 (5 minutes).
  - `g1nation.lmStudio.autoLoadOnSelect` *(boolean)* _(default: `true`)_ — Automatically load LM Studio models into memory when selected from the Astra sidebar.
  - `g1nation.lmStudio.sampling.topP` *(number)* _(default: `0.9`)_ — Nucleus sampling cutoff. Small / quantized models often spew wrong-neighbour tokens (한글 깨짐: 붕괴→붕점) when the tail is wide. Lower (0.8–0.9) tightens; 1.0 disables. Applied to both SDK and REST paths.
  - `g1nation.lmStudio.sampling.topK` *(number)* _(default: `20`)_ — Top-K sampling cutoff. 0 disables. Default 20 — tighter for small models, raise to 40–80 for large models that already sample well.
  - `g1nation.lmStudio.sampling.minP` *(number)* _(default: `0.05`)_ — Min-P floor — discards tokens with probability below this fraction of the top token. Good defence against rare-token glitches. 0 disables.
  - `g1nation.lmStudio.sampling.repeatPenalty` *(number)* _(default: `1.1`)_ — Repeat / frequency penalty to curb stutter (것입니다서입니다…). 1.0 disables. Values 1.05–1.2 are typical.
  - `g1nation.lmStudio.statsInBudget` *(boolean)* _(default: `true`)_ — Show token/s and time-to-first-token from LM Studio prediction stats in the context-budget badge after each turn (SDK path only).
  - `g1nation.lmStudio.draftModel` *(string)* _(default: `""`)_ — [Speculative decoding] LM Studio model key of a small draft model (e.g. 'gemma-2b-it') used to accelerate the main model. Empty disables. 1.5–3x throughput on large models. The draft must be downloade
  - `g1nation.lmStudio.load.flashAttention` *(boolean)* _(default: `true`)_ — [Load option] Enable Flash Attention when loading models. Faster generation + lower memory on compatible hardware, especially helpful for long contexts. Default: true.
  - `g1nation.lmStudio.load.gpuOffloadRatio` *(string)* _(default: `"max"`)_ — [Load option] How much of the model to offload to GPU. 'max' = all (default), 'off' = CPU only, or a number 0–1 (e.g. '0.5' = half). Numeric strings are parsed.
  - `g1nation.lmStudio.load.offloadKVCacheToGpu` *(boolean)* _(default: `true`)_ — [Load option] Keep KV cache on GPU memory. Faster but requires VRAM headroom. Default: true.
  - `g1nation.lmStudio.load.keepModelInMemory` *(boolean)* _(default: `true`)_ — [Load option] Prevent the model from being swapped out of system memory. Improves interactive responsiveness; raises RAM use. Default: true.
  - `g1nation.lmStudio.load.useFp16ForKVCache` *(boolean)* _(default: `false`)_ — [Load option] Store KV cache in FP16 (halves cache memory). Tiny quality impact for most models — try if you run out of VRAM at long contexts. Default: false.
  - `g1nation.lmStudio.load.evalBatchSize` *(number)* _(default: `0`)_ — [Load option] Token batch size during evaluation. 0 = engine default. Higher (512–1024) improves prefill speed on GPU at the cost of memory.
  - `g1nation.localBrainPath` *(string)* _(default: `""`)_ — Folder path for your local Second Brain knowledge base. Leave empty to use the default folder.
  - `g1nation.brainProfiles` *(array)* _(default: `[]`)_ — Multiple brain profiles. Each item supports id, name, localBrainPath, secondBrainRepo, and description.
  - `g1nation.activeBrainId` *(string)* _(default: `""`)_ — Active brain profile id used for the current chat context.
  - `g1nation.secondBrainRepo` *(string)* _(default: `""`)_ — Optional GitHub repository URL used for Second Brain sync.
  - `g1nation.autoPushBrain` *(boolean)* _(default: `false`)_ — Automatically commit and push Second Brain changes after updates.
  - `g1nation.maxContextSize` *(number)* _(default: `32000`)_ — Maximum character count for active file context. Default: 32000
  - `g1nation.maxAutoSteps` *(number)* _(default: `50`)_ — Maximum autonomous steps the agent can take per request. Default: 50
  - `g1nation.dryRun` *(boolean)* _(default: `false`)_ — If enabled, the agent will ask for approval before committing any file changes.
  - _…and 89 more_

## Dependencies
- **Runtime** (2): `@lmstudio/sdk`, `pdf-parse`
- **Dev** (8): `@types/jest`, `@types/node`, `@types/vscode`, `@vercel/ncc`, `esbuild`, `jest`, `ts-jest`, `typescript`

## README Excerpt
> Pulled from the project root README — first ~2 KB.

# Astra (by g1nation)

Astra는 **Antigravity 및 VS Code** 환경에서 작동하는 대표님 전용 **지능형 운영 레이어(Personal Intelligence Layer)**입니다. 단순한 명령 수행을 넘어, 프로젝트의 맥락과 대표님의 의사결정 패턴을 학습하여 최적의 전략적 조언을 제공하는 독립적인 인지 파트너입니다.

## 🌌 Antigravity & VS Code Unified Assistant

Astra는 범용 AI와 달리 특정 플랫폼에 종속되지 않으며, Antigravity 워크스페이스의 깊은 맥락과 VS Code의 강력한 개발 도구를 하나로 연결합니다. 

### 1. 전용 지능형 판단 체계 (Personal Cognition Layer)
v4.0 운영 정책이 코어에 이식되어 데이터의 신뢰도를 대표님의 기준에 맞춰 스스로 평가합니다. 상충되는 정보 발견 시 즉각적인 **[CONFLICT WARNING]**을 통해 객관적인 판단 근거를 제시합니다.

### 2. 고밀도 전략 지식망 (Strategic Knowledge Hub)
대표님의 Second Brain과 Antigravity 내의 모든 지식을 온톨로지 기반으로 구조화합니다. 비즈니스 전략, 기술 아키텍처, 리스크 관리가 하나로 통합된 지식 그래프를 통해 추론의 깊이를 보장합니다.

### 3. 선제적 파트너십 (Proactive Partnership)
작업이 완료된 후, 대표님이 다음에 내려야 할 **전략적 의사결정 포크(Decision Forks)**를 선제적으로 제안합니다. 사용자의 명령을 기다리지 않고, 프로젝트의 흐름을 먼저 읽고 길을 제시합니다.

## 🛠️ 주요 기능 및 권한

Astra는 대표님의 명시적인 승인 하에 로컬 시스템의 강력한 제어 권한을 행사하여 생산성을 극대화합니다.

| 작업 범주 | 설명 |
| :--- | :--- |
| **플랫폼 최적화** | Antigravity 워크스페이스와 VS Code 사이의 유기적인 맥락 전환 및 동기화를 지원합니다. |
| **자율 워크플로우** | 다중 에이전트 협업을 통해 복잡한 비즈니스 요구사항을 즉시 실행 가능한 단계별 계획으로 분해합니다. |
| **지식 자산화** | 흩어진 정보들을 P-Reinforce v3.0 표준에 맞게 위키화하여 영구적인 지식 자산으로 전환합니다. |
| **보안 및 프라이버시** | 100% 로컬 환경에서 작동하여 대표님의 소중한 데이터가 외부로 유출되지 않음을 보장합니다. |

## 🚀 설치 및 시작하기

### 패키지 설치
1. **g1nation**에서 배포된 최신 **v2.65.0** VSIX 파일을 확보합니다.
2. VS Code 명령 팔레트(`Cmd+Shift+P`)에서 **Extensions: Install from VSIX**를 선택하여 설치합니다.
3. Antigravity 환경과 연동하여 나만의 지능형 레이어를 활성화합니다.

---
**Designed for High-Performance Decision Making.**
Copyright (C) **g1nation**. All rights reserved.

_Last auto-scan: 2026-06-12T14:30:58.311Z · signature `314f69`_
<!-- ASTRA:AUTO-END -->

## Purpose

Astra (g1nation) — **로컬 LLM 기반의 개인 지능형 운영 레이어**. VS Code 확장으로 LM Studio / Ollama 와 채팅하면서 *프로젝트 컨텍스트 / 메모리 / 작업 자동화* 를 단일 UI 에서 처리. 100% 로컬 (cloud LLM 은 opt-in 라우팅).

### Top-level 동작 흐름

```
User ↘                                              ↗ webview (chat UI)
       sidebar.html / sidebar.js  ←——  chatHandlers
                        │                    │
                        │                    ├─ slash router (/research /youtube /stocks 등)
                        │                    │
                        ↓                    ↓
              SidebarChatProvider ──→  AgentExecutor (agent.ts, 1,529 lines)
                                              │
                       ┌──────────────────────┴──────────────────────┐
                       ↓                      ↓                      ↓
              handlePrompt phases      executeActions (8 그룹)   LLM I/O (agent/llm)
              (agent/handlePrompt)     (agent/actions)            createStreamingRequest
                                                                  streamChatOnce
                                                                  callNonStreaming
                       │
                       ↓
              [PRIOR TURN CONCLUSION]   ← 대화 연속성 anchor
              + Mode Bridge + Context Blocks + System Prompt + Budget
```

### 핵심 디자인 패턴

**1. God-file 분해 (R50–R59, 2026-05).** `agent.ts` 2731→1529 lines, `extension.ts` 1145→349 lines. 25개 신규 모듈 (`src/agent/**`, `src/extension/**`). 패턴:
- *Pure free functions + deps object* — `this.X` 의존성을 callback dep 으로 명시 (e.g. `callNonStreaming(deps, params)`)
- *Thin wrappers on the class* — AgentExecutor 의 메서드는 deps 묶어서 free function 으로 위임. 외부 caller signature 보존.
- Action handlers (15+ tags) 는 `HandlerContext` 공유 ctx 객체로 통일 — 8개 그룹 (file/run/list/brain/calendar/sheets/tasks).
- handlePrompt 1,100줄 → 7 phase 모듈 (buildTurnContextBlocks / buildModeBridgeContext / build{Agent,Astra}ModeSystemPrompt / computeBudgetedRequest / processFinalAnswer / applyAutoContinuation).

**2. 대화 연속성 (v2.2.150~157).** 작은 로컬 모델 (gemma 4B 등) 이 follow-up 정정/보강 turn 에 echo/parrot 하는 문제 해결:
- `[PRIOR TURN CONCLUSION]` block — 직전 assistant 답변의 첫 문장을 system prompt 에 anchor
- `[CONVERSATION CONTINUITY & REVISION]` rule — echo 금지, 최소 3-5 문장 구조 강제
- *Thin follow-up classifier* (`isThinFollowUp`) — 짧은 follow-up turn 에서 Guard 의 4-section boilerplate (`## 요청 요약` 등) suppress
- *Slash 결과 chatHistory mirror* — slash 명령 결과를 webview *와 함께* agent.chatHistory 에 push (capture wrapper). 다음 turn LLM 이 직전 명령 출력 인식. `getHistory()` 가 filtered copy 반환하는 silent bug fix 포함.

**3. Slash 명령 시스템.** `src/features/datacollect/slashRouter.ts` 의 registry. 등록된 명령: `/research /benchmark /youtube /blog /wikify /meet /stocks`. webview 의 `/` 자동완성 dropdown 으로 노출. 각 명령은 `(arg, view, context) => Promise<boolean>` 시그니처 통일.

**4. Stocks feature (v2.2.152~158).** 새 도메인 — 한국 주식 모니터링/발굴:
- `.astra/stocks.json` 저장소 (workspace root)
- Yahoo Finance 현재가 갱신, `g1nation.stocks.spreadsheetId` 로 Google Sheets 동기화 (calendar OAuth scope 재사용)
- KST 09:00 / 15:00 watcher 자동 트리거 → Telegram 보고서
- **8 키워드 자동 필터** (ROE/성장성/유동성/수익성/영업효율/기술력/안정성/PBR) — `llmJudge.ts` 와 `stockDiscovery.ts` 가 동일 임계값 공유
- `/stocks discover` — Naver 비공식 JSON API (`m.stock.naver.com/api/...`) 로 시가총액 페이지 + 펀더멘털 (ROE/영업이익률/유보율) 크롤 후 8 키워드 필터 → 통과한 종목 → LLM Top 5 매력도 분석 → Telegram 자동 발송
- `/stocks judge <symbol>` — LLM 으로 4-criteria 필터 자동 판정 + JSON 업데이트

**5. 5-Layer Cognitive Memory.** `src/memory/`:
- Short-Term (대화 단기) / Long-Term (Second Brain) / Project (프로젝트 기록) / Procedural (스킬) / Episodic (세션 요약)
- TF-IDF + 한/영 이중 토크나이저 (`src/retrieval/scoring.ts`)
- 옵션: embedding hybrid (`g1nation.embeddingModel` 설정 시 dense+sparse blend)
- Knowledge Mix policy — Second Brain 의존도 (0-100) 사용자 조절 가능

**6. 1인 기업 모드 (Company Mode).** `src/features/company/`:
- 가상 회사 — 사용자 = CEO, 에이전트 = 직원. 명령 분류기 → dispatcher → 직군별 specialist → CEO 검수 → 산출물
- 각 turn 은 session directory 에 `_brief.md / _report.md / 에이전트별 산출물` 영구 기록
- LLM 호출 인터페이스: `IAIService.chat({system, user})` (mock 가능 → `tests/helpers/mockLLMClient.ts`)

**7. Context budget (`src/lib/contextManager.ts`).** 매 turn 마다 system + history + input 의 토큰 예산 계산, output 상한 동적 조절. `smallModelContextCap` 옵션으로 ≤3B 모델의 EOS-first 환각 회피.

**8. Cloud LLM routing (`src/features/providers/`).** `openrouter:` / `anthropic:` / `gemini:` prefix 가 model id 에 있으면 자동 cloud SDK 라우팅. SSE 응답은 OpenAI 호환 형식으로 normalize → 로컬 path 와 동일 consumer.

### 진입 파일 (학습 순서)

1. **`src/extension.ts`** — activation, 모든 wiring (사이드바 / approval / telegram / stocks watcher / slash router)
2. **`src/sidebarProvider.ts`** — webview lifecycle, message dispatch (chatHandlers / settings)
3. **`src/agent.ts`** — AgentExecutor (thin wrappers + chatHistory 상태)
4. **`src/agent/handlePrompt/`** — 한 turn 의 7-phase pipeline
5. **`src/features/stocks/`** — 최근 새 도메인 사례 (slash + watcher + LLM + Telegram 통합)

### 활성 작업 (2026-05)

- *완료*: god-file 분해 R50–R59, Stocks feature 전체 파이프라인, 대화 연속성 fix
- *진행 가능 (paused)*: `/stocks discover` 의 시가총액 범위 자동 유도 (사용자 드롭 요청)
- *남은 큰 영역*: `slashRouter.ts` (1,127 lines), `dispatcher.ts` (1,364 lines), `sidebarProvider.ts` (3,194 lines) — 별도 god-file 분해 대상이나 ROI 검토 필요
