# AXE Labs Docs — 전체 본문 (LLM 단일 ingest 용)

생성: 2026-06-08T16:08:51.801Z
사이트: https://docs.axelabs.ai

각 페이지는 URL prefix + frontmatter + 본문 형식. 페이지 경계는 "<!-- PAGE -->" 마커.

---

<!-- PAGE https://docs.axelabs.ai/ -->

# AXE Labs Platform

> 멀티테넌트 SaaS 플랫폼 — 액스코퍼레이션 주식회사 (`axec`) 가 운영하는 자체 인프라.

URL: https://docs.axelabs.ai/

# AXE Labs Platform

> 👋 **처음 오셨나요?** 본인 역할로 바로 이동하세요 — 이 사이트 외 다른 첨부·메시지 의존 없이 자력 완료 가능합니다.
>
> | 누구이신가요? | 가는 곳 | 소요 |
> |---|---|---|
> | **고객사 IT 담당자** (회사가 AXE Labs 도입 결정 → 자기 회사 macmini 준비 중) | [→ 고객사 IT 가이드](/partner) (4-step) | ~45 분 |
> | **신규 직원** (회사가 이미 AXE Labs 사용 중 → 본인 connector setup) | [→ 신규 직원 온보딩](/onboard) | ~10 분 |
> | **운영자 (액스코퍼레이션 주식회사)** | [→ 운영자 runbook](/ops/runbook/customer-onboarding) | — |

AXE Labs 는 **운영 주체 (액스코퍼레이션 주식회사) 가 다수의 customer 를 동일 패턴으로 호스팅** 할 수 있도록 설계된 멀티테넌트 SaaS 플랫폼입니다. 각 customer (현재 axe, 진행 중 realchoice) 는 자기 macmini 위에서 동일한 stack — frame · blueprint · vault · index — 을 실행하고, 운영 주체의 자동화 계정 (`ai@axellc.com`) 이 단일 CLI 와 SSOT 설정 파일(`customers.yaml`)로 전체를 관리합니다.

## 핵심 서비스

```
┌────────────────────────────────────────────────────────────────┐
│  AXE LABS — multi-tenant platform                              │
├────────────────────────────────────────────────────────────────┤
│                                                                │
│   blueprint    : AI-native workspace (Next.js + Claude SDK)    │
│   frame        : 회계 backend (Postgres + MCP)                 │
│   stream       : S&OP MCP (sales · inventory · settlement)     │
│   magnet       : 마케팅 자동화 MCP (Meta / Naver / Threads)    │
│   vault        : Self-host Vaultwarden + Microsoft SSO         │
│   index        : (예정) 검색·전체 색인 layer                   │
│                                                                │
└────────────────────────────────────────────────────────────────┘
```

각 서비스는 별도 git repo + Docker Compose 단위로 배포되며, customer 격리는 **OS-level (macmini 1대 = customer 1개)** 입니다.

## 문서 구성

| 섹션 | 대상 | 인증 |
|---|---|---|
| [플랫폼 아키텍처](/architecture) | 모든 독자 | 공개 |
| [서비스 카탈로그](/services) | 모든 독자 | 공개 |
| [직원 온보딩](/onboard) | 신규 직원 | 공개 |
| [고객사 IT 가이드](/partner) | 고객사 IT 담당자 | 공개 (민감 정보는 별도 채널) |
| [운영자 (내부)](/ops) | 운영자 (`ai@axellc.com`) | Microsoft Entra ID 로그인 |
| [운영 정책](/operations) | 운영자 + 감사인 | 공개 (정책 자체) |

## Quick Links

- **고객사 IT (도입 결정 후 첫 방문)**: [고객사 IT 가이드 — 4-step 흐름](/partner)
- **고객사 IT (Azure CLI 1줄)**: [Entra ID 앱 등록 §Option A](/partner/registration#option-a--cli-1-줄-권장)
- **신규 직원**: [Frame connector 4-step setup](/onboard/claude-frame-setup)
- **터미널 · Claude Code · Codex · CI**: [AXE CLI (`axe`) 설치 + 로그인 1회](/services/cli) — MCP 커넥터 불요, 토큰 하나로 전 서비스
- **운영자**: [신규 customer onboarding](/ops/runbook/customer-onboarding)
- **아키텍처 결정**: [DECISIONS](/ops/decisions)

## AI / LLM 진입점

- **[`/llms.txt`](https://docs.axelabs.ai/llms.txt)** — [llmstxt.org](https://llmstxt.org/) 스펙 페이지 인덱스. AI agent 가 사이트 구조를 파악하는 표준 entry point.
- **[`/llms-full.txt`](https://docs.axelabs.ai/llms-full.txt)** — 전체 페이지 본문을 1 파일로 concat (현재 ~190 KB). 단일 ingest 로 컨텍스트 전체 로딩.
- **[`/api/search?q=...`](https://docs.axelabs.ai/api/search?q=OAuth)** — JSON full-text search. score 기반 ranking + snippet + markdown_url. LLM 이 페이지 위치 찾을 때.
- **Per-page raw markdown** — 모든 URL 에 `.md` suffix (예: [`/services/frame.md`](https://docs.axelabs.ai/services/frame.md)). frontmatter + canonical URL 주석 포함.
- **[`/sitemap.xml`](https://docs.axelabs.ai/sitemap.xml)** — 전체 URL 목록.
- **[GitHub repo](https://github.com/soohunkang/axelabs-docs)** — mdx 원본 직접 조회.

## 도메인 / URL 컨벤션

```
{customer}.axelabs.ai/             ← blueprint (apex)
{customer}.axelabs.ai/frame/mcp    ← frame MCP endpoint
{customer}.axelabs.ai/vault        ← Vaultwarden
admin.axelabs.ai                   ← 운영자 콘솔 (Microsoft SSO 게이트)
docs.axelabs.ai                    ← 본 문서 (이곳)
```

* `axelabs.ai` — 플랫폼 (이 docs 가 있는 곳)
* `axellc.com` — corporate (이메일·기업 홈페이지, 플랫폼과 분리)

## 운영 메타

| 항목 | 값 |
|---|---|
| 운영 주체 | 액스코퍼레이션 주식회사 (`axec` entity, 자동화 계정 `ai@axellc.com`) |
| 1차 customer | axe (라이브 2025-01) |
| 2차 customer | realchoice (예정 2026-06-01) |
| 회계 기준 | KSME / K-GAAP |
| 시간대 | Asia/Seoul |
| 인증 | Microsoft Entra ID OAuth 2.0 / OIDC |
| 데이터 격리 | OS-level (customer/macmini) + schema-per-entity (DB) |

---

<!-- PAGE https://docs.axelabs.ai/architecture -->

# 플랫폼 아키텍처

> AXE Labs 멀티테넌트 SaaS 플랫폼의 토폴로지, 도메인, 인증, 격리 모델.

URL: https://docs.axelabs.ai/architecture

# 플랫폼 아키텍처

AXE Labs 의 아키텍처는 **소규모 운영자(1인) 가 다수의 customer 를 일관된 패턴으로 호스팅** 할 수 있도록 설계되었습니다. 모든 결정은 [DECISIONS](/ops/decisions) 에 누적 기록되며, 본 페이지는 그 결과의 정적 요약입니다.

> 약어가 익숙하지 않으면 [용어 사전](/glossary) 먼저 참조. 핵심: **MCP** (Model Context Protocol, AI 가 외부 도구·데이터에 접근하는 표준), **OIDC** (OpenID Connect, 신원 확인), **PKCE** (Proof Key for Code Exchange, OAuth 코드 가로채기 방지).

## 6 가지 설계 원칙

1. **격리는 OS-level — customer 1개 = macmini 1대.** 다중 customer 가 한 머신을 공유하지 않습니다. SPOF (macmini 자체 장애) 는 cold storage 백업으로 흡수.
2. **테넌트 ID = 이메일 도메인 → `customers.yaml` 매핑.** 사용자가 `ai@axellc.com` 으로 로그인하면 `axellc.com → axe` customer, `realchoice.co.kr → realchoice` customer 로 자동 라우팅.
3. **Path-based 1-level subdomain.** `{customer}.axelabs.ai/{service}` 형식. 2-level wildcard SSL 무료 미지원 → path-based 로 회피.
4. **Tailscale 메시 + SSH key.** 운영자 ↔ customer macmini 간 push 기반 deploy. 자체 mTLS X.
5. **Microsoft Entra ID + customer 별 own tenant.** 각 customer 의 직원은 자기 회사 tenant 로 인증.
6. **GitHub source-of-truth + push deploy.** customer macmini 가 pull-polling 하지 않음.

## High-Level Topology

```
┌────────────────────────────────────────────────────────────────────────┐
│                                                                        │
│   직원 노트북 (Windows / macOS)                                          │
│   ├─ Claude Code 네이티브 앱 + Microsoft Entra ID 로그인                  │
│   └─ claude.ai 측에 Custom Connector 1회 등록                            │
│            │                                                            │
│            ↓  (Anthropic backend OAuth flow)                            │
│                                                                        │
│   Microsoft Entra ID (customer tenant)                                 │
│   - axe:        122fb574-...  (axellc.com)                              │
│   - realchoice: &lt;TBD&gt;          (realchoice.co.kr)                       │
│                                                                        │
│            ↓  (Bearer access_token, aud = MCP URL)                      │
│                                                                        │
│   Cloudflare DNS / Cloudflare Tunnel (axelabs-tunnel)                  │
│            │                                                            │
│            ↓  (host.docker.internal:3712)                               │
│                                                                        │
│   ┌──── customer macmini (axe-macmini / realchoice-macmini) ────┐       │
│   │                                                              │       │
│   │  axe-frame-proxy (Caddy, port 3712)  ← blue/green selector   │       │
│   │         │                                                    │       │
│   │         ├──→ frame-mcp-blue  :3710   (active)                │       │
│   │         └──→ frame-mcp-green :3711   (passive)               │       │
│   │                  │                                           │       │
│   │                  ↓                                           │       │
│   │           frame-postgres :3700                                │       │
│   │                                                              │       │
│   │  blueprint :3100   axe-vaultwarden :443/vault                │       │
│   │  stream :8780      magnet :8770                              │       │
│   │                                                              │       │
│   └──────────────────────────────────────────────────────────────┘       │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘
```

## 인증 흐름 (간략)

```
1. 직원 → claude.ai Custom Connector → URL https://{customer}.axelabs.ai/frame/mcp
2. claude.ai 백엔드 → frame /mcp (no auth) → 401 + WWW-Authenticate
3. claude.ai → /.well-known/oauth-protected-resource → AS = Microsoft Entra
4. claude.ai → Microsoft authorize 엔드포인트 (PKCE S256 + client_secret)
5. 브라우저 → Microsoft 로그인 → consent → code 발급
6. claude.ai → Microsoft /token → access_token (aud = Application ID URI)
7. claude.ai → frame /mcp with Authorization: Bearer &lt;access_token&gt;
8. frame middleware → Microsoft JWKS RS256 검증 + audience match + entity 매핑
9. frame → MCP session 생성 → tools 호출
```

상세는 [인증 · 권한](/architecture/auth) 참조.

## 다음 단계

- [Topology · 네트워크](/architecture/topology) — Cloudflare Tunnel, Docker network, proxy 패턴 상세
- [도메인 · DNS](/architecture/domains) — Cloudflare zone, 1-level subdomain 결정 근거
- [인증 · 권한](/architecture/auth) — Microsoft Entra ID, JWT, dual-token model
- [데이터 격리 모델](/architecture/data) — schema-per-entity, audit_log, PII 암호화
- [배포 · 무중단](/architecture/deploy) — blue/green frame swap, axe-frame-proxy
- [백업 · DR](/architecture/backup) — restic 3-tier (local / ring P2P / cold SSD)

---

<!-- PAGE https://docs.axelabs.ai/architecture/artifacts -->

# Artifact 모델 · PARA 지식 레이어

> Blueprint 의 typed fact layer. PARA 와 결합해 work/knowledge 를 organize. MCPs/Teams/Mail/OneDrive 의 citation chain.

URL: https://docs.axelabs.ai/architecture/artifacts

# Artifact 모델 · PARA 지식 레이어

> **[2026-06-06 방향 갱신]** PARA 의 상위 설계 철학은 [/architecture/para-os](/architecture/para-os) 로 정리됨 (PARA=조직론, dispatch="집"/link-default, governance 결정로그, 죽은 딜 본질). 본 페이지의 **dispatch `copy-with-provenance` → `link-default` 로 revise** ([D-bp-para-1](/ops/decisions)), Area=workspace-container → 조직론 노드 + R/A 내포. 단 저장·citation·schema discovery 세부는 본 페이지가 유효한 reference.
>
> **[2026-06-06 구현 토폴로지 — [D-bp-rust-1](/ops/decisions)]** Artifact 레이어는 Blueprint 의 **첫 Rust organ** 으로 이관된다 (TS→Rust strangler-fig). 신규 substrate 서비스(Rust+axum)가 `blueprint-postgres` 의 **`substrate` schema** 에서 `artifact`/`artifact_link`/`mcp_schema` 를 소유 — `workspace_id`·`entity_id` 는 opaque 외부 ref(**Artifact-scoped 경계**), Workspace+paraLayer SoR 는 Prisma `public` 잔류. 모델 교정(처음부터 1급): **home/link("집")** = `artifact_link` 가 멤버십 본체 + **`annotation`**(Area별 해석), `parent_artifact_id` → **`derived_from_id`**(진짜 파생만), **2-level `scope`**(personal/shared), **citation 8종**(아래 7종 + `gate.decision` [D-gate-2](/ops/decisions)). 아래 본문의 Prisma SQL·"copy default"·"7 kind" 서술은 **현 TS(M6 Stage-1) 기록**이며 cutover(ADR §6 S3) 전까지 병존 — 권위 = [D-bp-rust-1](/ops/decisions) + ADR `docs/adr/blueprint-rust-migration.md`.

## 한 줄 정의

**Artifact = Blueprint 의 typed fact unit**. source 문서가 아니라 agent 가 직접 read 하는, 사전 추출된 사실 한 조각. per-field schema + per-field citation + confidence + audit trail + paraLayer scope 를 갖춤. Blueprint Postgres 거주 (D-config-16), large content / 원본 파일은 OneDrive · frame · hive · Teams · mail 등 원위치 유지하고 artifact 는 stable ID 로만 참조 — data 중복 0.

## 왜 필요한가

현재 Blueprint 의 knowledge layer 는 [ctx skill](https://docs.axelabs.ai/services/blueprint) 의 markdown PKM 한 단계뿐. agent 가 grep + cat 으로 markdown 본문을 읽어 사실을 추출하는 방식이라 다음이 모두 불가능:

| 격차 | 현재 (markdown only) | 결과 |
|---|---|---|
| Cross-functional query | "portfolio cos 중 Q4 churn > 15%" 를 grep 으로 못 풀음 | Area query 가 LLM 토큰 폭증 |
| Field-level provenance | 사실 한 줄의 출처 추적 불가 (markdown 안에 인용 표기 의무 X) | citation chain 끊김, IC 결정의 audit 불가능 |
| Time-travel | "Project Deal X 가 지난 주 이후 무엇 바뀌었나" 답 불가 | 의사결정의 시점형 archaeology 불가 |
| 결정론적 충돌 해소 | 두 agent 가 같은 markdown 동시 편집 시 last-write-wins | 사실 무결성 보장 X |
| Multi-agent concurrent read-write | markdown lock 없음 | 동시 작업 시 race |

격차의 본질: 인프라는 dev-co level (per-customer macmini isolation · blue/green deploy · OAuth-RP · restic backup · 7-stack 응집) 이지만 knowledge layer 만 single-operator PKM tool 수준에 머문다. AI-native fund 가 자기 의사결정의 SOT 로 쓰려면 typed fact layer 가 필요.

## PARA 와의 관계

PARA (Tiago Forte) 의 Project / Area / Resource / Archive 4 layer 각각에 typed artifact 집합이 거주. PARA layer 가 artifact 의 lifecycle 과 visibility 를 결정.

| Layer | 역할 | 대표 artifact 유형 |
|---|---|---|
| **Project** | 기한 + goal cross-functional 컨테이너 (IC for Deal X, Fund 2 fundraising, 2026 Q3 LP report) | `ICMemoArtifact` · `BoardMeetingNotesArtifact` · `LPCapitalCallArtifact` |
| **Area** | function 별 지속 reference state (CFO · IR · Sourcing · Portfolio). read 빈도 높음, 끊임없는 갱신 | `PortcoBoardKPIArtifact` (Portfolio Monitoring) |
| **Resource** | 재사용 가능한 versioned framework + template | `SectorFrameworkArtifact` |
| **Archive** | 기한 지난 Project + outdated resource. pattern detection corpus | 위 모든 종류의 frozen snapshot |

Project 가 closeout 되면 그 안의 artifact 들이 typed fact 단위로 Area / Resource / Archive 로 field-level dispatch. [M3 PARA Dispatch](/ops/roadmap#m3--blueprint-para-dispatch-d-bp-entity-1-pr-5) 가 현재 workspace-level (file-level) provenance (`sourceWorkspaceId` / `sourceArtifactPath` / `copiedAt`, [D-bp-entity-2](/ops/decisions)) 까지 land — Artifact 는 그 위에서 **field-level** 진화.

### Cross-PARA query 예시

현재 ctx markdown 으로 불가능하지만 artifact layer 위에서 자연:

- "portfolio cos 중 Q4 churn > 15%" — Area query (`PortcoBoardKPIArtifact.confidence ≥ 0.8`)
- "과거 deal 중 현재 Sentry 와 IRR trajectory 비슷한 것" — Archive cross-Project pattern match
- "portco Y 가장 최근 revenue, citation 포함" — Area lookup with citation chain
- "Project Deal X 가 지난 주 이후 무엇 바뀌었나" — time-travel diff
- "LP X 와 마지막 comm 후 변한 portfolio fact" — IR Area × Portfolio Area cross-query

## 데이터 모델

Blueprint Postgres 의 `Artifact` + `Citation` 테이블 (Prisma). schema 는 versioned (`schema_id` FK), content 는 JSONB (schema 별 typed field), citations 는 JSONB array.

```sql
CREATE TABLE artifact (
  id                  uuid PRIMARY KEY,
  schema_id           text NOT NULL REFERENCES artifact_schema(id),  -- MCP discovery schema (e.g., `frame.balance@1.0`, `hive.employee@1.0`) 또는 free-form (`freeform.llm@auto`). MCP authority — Blueprint 는 registry 아니라 discovery/mirror
  workspace_id        uuid NOT NULL REFERENCES workspace(id),
  entity_id           text NOT NULL REFERENCES entity(slug),         -- D-bp-entity-3 NOT NULL
  para_layer          text NOT NULL CHECK (para_layer IN ('PROJECT','AREA','RESOURCE','ARCHIVE')),
  content             jsonb NOT NULL,                                -- schema 별 typed field
  citations           jsonb NOT NULL DEFAULT '[]'::jsonb,            -- per-field citation array
  confidence          numeric(3,2) NOT NULL DEFAULT 1.0,             -- 0.00 ~ 1.00
  audit_trail         jsonb NOT NULL DEFAULT '[]'::jsonb,            -- propose/review/confirm/edit events
  parent_artifact_id  uuid REFERENCES artifact(id),                  -- PARA dispatch fork chain
  created_at          timestamptz NOT NULL DEFAULT now(),
  updated_at          timestamptz NOT NULL DEFAULT now(),
  archived_at         timestamptz                                    -- soft delete (Archive 진입 시 set)
);

CREATE INDEX artifact_workspace_idx ON artifact (workspace_id);
CREATE INDEX artifact_entity_para_idx ON artifact (entity_id, para_layer);
CREATE INDEX artifact_schema_idx ON artifact (schema_id);
CREATE INDEX artifact_parent_idx ON artifact (parent_artifact_id) WHERE parent_artifact_id IS NOT NULL;
```

`audit_trail` 의 한 entry 는 `{ event, actor, ts, diff?, prompt? }` 형식. 변경 history 가 row 안에 누적되며 `updated_at` 만 갱신 — pg_jsonschema validation 으로 무결성 가드 (확장 add-on).

## Citation 형태

Citation 은 외부 source 의 **stable ID** 만 가짐. data 자체는 원위치 (OneDrive driveItem / frame query / hive ID / index DB ref / gate decision cert / Teams chat+msg / mail thread+msg / external URL) — artifact 에 중복 0. 8 kind:

```jsonc
// content 의 field 별 1+ citation
{
  "field": "revenue_q4_2025",
  "citations": [
    // 1) OneDrive Excel cell
    { "kind": "onedrive",
      "drive_item_id": "01ABCD...",
      "version": "v3",
      "sheet": "Q4 Recurring",
      "cell": "B14" },

    // 2) frame typed query (회계 도메인)
    { "kind": "frame.balance",
      "entity": "axec",
      "account": "4001",
      "period": "2025-Q4",
      "queried_at": "2026-05-22T03:14:00Z" },

    // 3) hive employee record (HR 도메인)
    { "kind": "hive.employee",
      "entity": "axev",
      "employee_id": "uuid-...",
      "queried_at": "2026-05-22T03:14:00Z" },

    // 4) Teams chat message
    { "kind": "teams.message",
      "chat_id": "19:...",
      "message_id": "1700000000000" },

    // 5) Mail thread message
    { "kind": "mail.thread",
      "thread_id": "AAMkAD...",
      "message_id": "AAMkAD...." },

    // 6) External web fetch (snapshot 시점 명시)
    { "kind": "external.web",
      "url": "https://...",
      "fetched_at": "2026-05-22T03:14:00Z" },

    // 7) index typed query (투자 도메인 — D-index-6)
    { "kind": "index.financial_output",
      "deal_id": "uuid-iippo",
      "model_id": "uuid-iippo-v7-base",
      "scenario_code": "weighted",
      "output_code": "irr_loss_included",
      "computed_at": "2026-05-06T10:00:00Z" },
    // 기타 index.* sub-kinds: index.deal · index.fund_investment ·
    // index.dd_finding · index.ic_decision · index.portfolio_kpi ·
    // index.financial_model · index.valuation · index.lp_comm 등

    // 8) gate 거버넌스 결정 (gate.decision SoR 의 mirror — D-gate-2)
    { "kind": "gate.decision",
      "decision_id": "uuid-...",
      "cert_id": "modusign-...",        // 모두싸인 서명완료 cert (citation only)
      "decided_at": "2026-06-06T01:00:00Z" }
  ]
}
```

각 kind 에 대응하는 **citation resolver** (`src/lib/artifact/citations/`) 가 stable ID 로 실 데이터를 fetch + cache. Trinity dashboard (Workspace × OneDrive × TeamsChat) 의 진화형 — 기존 GUID 3축 → field 단위 citation chain.

## MCPs 와의 분리

별 트랙. **MCP = domain-specific data system**, **Artifact + PARA = Blueprint 내부 work/knowledge organization meta-layer**.

| Layer | 책임 |
|---|---|
| frame MCP | 회계 도메인 데이터 (journal, balance, period) — schema-per-entity Postgres |
| hive MCP | HR 도메인 데이터 (employee, payroll, leave) — frame mirror |
| magnet / stream / 기타 MCP | 각 도메인 데이터 시스템 |
| **Artifact + PARA (Blueprint)** | **위 MCP 들이 발행하는 사실을 typed fact 로 organize. citation 으로 stable ID 참조** |

Artifact 가 frame 의 `query_balance` 결과를 자기 안에 복사하지 않음. citation `{ kind: "frame.balance", entity, account, period, queried_at }` 만 보유. agent 가 artifact read 시 resolver 가 frame MCP 를 다시 호출하거나 cache 사용. MCP backend 가 sole owner — artifact 는 reference + interpretation 의 home.

### Schema authority 분산

Schema 의 권위는 **MCP service** (frame · hive · magnet · stream · Matrix · …). 각 MCP 가 자기 도메인 schema 를 정의하고 `/schemas` endpoint 로 노출. Blueprint 는 그 schema 들을 **discovery / mirror** — fetch + cache + version. registry 아님. 새 MCP 추가 시 자기 schema 를 가지고 들어오므로 Blueprint 측 변경 0.

MCP 가 정한 규칙이 없는 영역 (IC memo / Board meeting / Trip / LP comm / Sector framework 등 free-form) 은 **LLM 자율** — extract 시점에 ad-hoc typed structure 결정하거나 free-form content + citation/confidence wrap 으로 보존. AXE 가 미리 schema 다 정의할 필요 없음.

| 영역 | Schema authority | 예 schema_id |
|---|---|---|
| 회계 (journal, balance, period, account) | **frame MCP** | `frame.balance@1.0` · `frame.journal@1.0` |
| HR (employee, payroll, leave, compensation) | **hive MCP** | `hive.employee@1.0` · `hive.payslip@1.0` |
| 투자 (deal, fund_investment, financial_model, dd_finding, ic_decision, portfolio_kpi, valuation, lp_comm) | **index MCP** | `index.deal@1.0` · `index.fund_investment@1.0` · `index.financial_output@1.0` ([14 schemas](/services/index/schema-catalog)) |
| 마케팅 (campaign, channel, lead) | **magnet MCP** | `magnet.campaign@1.0` |
| S&OP (forecast, plan) | **stream MCP** | `stream.forecast@1.0` |
| 모니터링 (health, alert) | **Matrix MCP** | `matrix.health@1.0` |
| 관계망 (person, interaction, relationship) | **cortex MCP** | `cortex.person@1.0` · `cortex.interaction@1.0` |
| Board meeting / Trip / Sector framework (도메인 외 free-form) | **LLM 자율** | `freeform.llm@auto` 또는 skill-defined (`ic.memo@1.0`) |

`/schemas` endpoint contract (각 MCP 가 표준화):

```jsonc
GET /schemas
{
  "service": "frame",
  "version": "1.2.0",
  "schemas": [
    { "id": "frame.balance@1.0", "fields": { ... }, "description": "..." },
    { "id": "frame.journal@1.0", "fields": { ... }, "description": "..." }
  ]
}
```

Blueprint 의 `src/lib/artifact/schemas/` 가 각 MCP 의 `/schemas` 를 주기적으로 fetch → `artifact_schema` 테이블 upsert. 변경 감지 시 새 version row 추가 (기존 row 미변경 — 기존 artifact 의 citation chain 보존).

## ctx skill 의 진화

**대체 아님, 진화.** 기존 `ctx` (agent session delta → markdown append + parent KB propagation) 는 artifact store 의 **curation interface** 로 재정의.

```
source (OneDrive doc / frame query / Teams chat / mail thread / web fetch)
    ↓
ingest (skill: ingest, 별도 skill 신설 가능)
    ↓
typed extraction (schema-aware LLM extract, e.g., ICMemoArtifact §재무)
    ↓
proposed fact (audit_trail entry: { event: "propose", actor: "agent", ... })
    ↓
ctx review (user confirm / edit / reject — UX 가 markdown diff + citation hover)
    ↓
confirmed fact + audit (audit_trail entry: { event: "confirm", actor: "user", ... })
    ↓
agent reads via Query API (grep 안 함 — typed query + citation chain)
```

Markdown 은 보조 — review UX 의 diff 표면 + archive 보존 + emergency cat (DB 장애 시). primary read path 는 Query API.

### Markdown → artifact 점진 migration (AI-assisted)

기존 markdown PKM (`ctx/MEMORY.md` 의 누적 entry, project_*.md, feedback_*.md 등) 은 **목표는 전면 artifact 화**. 단 mass migration 안 함 — **항목 단위 AI-assisted ctx review** 로 점진:

```
기존 markdown 파일 1개 (예: ctx/MEMORY.md 의 한 entry)
    ↓
LLM 이 read → typed extract 시도 (MCP discovery schema 매칭 또는 LLM 자율 free-form)
    ↓
proposed artifact (audit_trail: { event: "migration_propose",
                                  actor: "agent",
                                  source_markdown: "ctx/MEMORY.md#L42-58",
                                  ts: "..." })
    ↓
ctx review (사용자 confirm / edit / reject — UX 가 source markdown 발췌 + extracted typed fact 나란히)
    ↓
confirmed artifact + 기존 markdown entry 에 `<!-- migrated: <artifact_id> -->` archive 마킹
    ↓
markdown 파일 전체 entry 가 모두 migrate 되면 그 파일 자체 deprecation
    ↓
신규 fact 는 처음부터 artifact 로 — markdown append 안 함
```

핵심 원칙:
- **점진** — 1주에 1 파일 또는 1 batch (10 entry) 수준. 인간 정비 cadence 안에서
- **AI-assisted** — LLM 이 자동 extract, 사람은 confirm 만 (인간 개입 최소화)
- **archive 마킹** — migrated entry 가 어떤 artifact 로 변환됐는지 trace 보존 (`<!-- migrated: <artifact_id> -->`). 이후 audit / 재migration 가능
- **신규 fact = artifact 처음부터** — 마이그레이션 완료 전이라도 새 사실은 artifact 로 직접 들어옴 (markdown append 옵션 안 줌)

## Workspace lifecycle

PARA 4 layer 는 Workspace 의 `paraLayer` 컬럼 (PROJECT / AREA / RESOURCE / ARCHIVE) 으로 표현. 각 Workspace 는 정확히 1 paraLayer 보유. lifecycle 의 핵심: **Dispatch ≠ Close** — 두 활동 분리.

### 4 paraLayer transition

```
                  create(paraLayer=PROJECT|AREA|RESOURCE)
                                  │
                                  ▼
              ┌──────── PROJECT (working) ─────────┐
              │                                     │
              │  dispatch (anytime — copy/link)     │
              │  artifact/file 을 다른 Workspace 로  │
              │  reclassify (any-to-any)            │
              │                                     │
              └────── close (paraLayer 변경 1회) ────┘
                                  │
                ┌─────────────────┼─────────────────┐
                ▼                 ▼                 ▼
              AREA            RESOURCE          ARCHIVE
              (현재형)         (재사용)          (시점형)
                │                 │                 │
                │   reclassify bidirectional 가능    │
                │   (ARCHIVE resurrect 포함)        │
                └─────────────────┴─────────────────┘
```

규칙:
- **create** — paraLayer 선택 (PROJECT 가 default, AREA/RESOURCE 도 직접 가능)
- **dispatch (anytime)** — Project 진행 중에도 file/artifact 를 다른 Workspace 로 흘려보냄. 3 mode: **link**(기본, 집 배정) / **copy_curate**(재사용본 저작→Resource) / **move**(소모성→Archive) — 아래 §Dispatch 3 mode
- **close (한 번)** — `workspace.paraLayer` 를 한 번 변경. PROJECT → ARCHIVE (보통) 또는 PROJECT → AREA/RESOURCE (reclassify). audit trail 에 close event 기록
- **reclassify (bidirectional)** — ARCHIVE → AREA 도 가능 (resurrect). 단 audit_trail 보존 — 누가 언제 왜 resurrect 했는지

### Dispatch 3 mode — link(기본) / copy-curate / move ([D-bp-para-1](/ops/decisions))

> dispatch = "집(home)" 배정 ([para-os §6](/architecture/para-os)). **link 가 기본** (artifact 몸통 1 + 집 N). 구 "copy-default"(`copy-with-provenance`)는 폐기 — copy 는 *재사용본 저작* 예외만.

| Mode | 의미 | 사용 사례 |
|---|---|---|
| **link** (기본) | `artifact_link` 에 (artifact_id, workspace_id, link_type, **annotation**, linked_at, linked_by) row 추가. artifact 본문 1 row, 여러 Workspace 가 share. `annotation` = Area별 해석 레이어 | 같은 PortcoBoardKPI 를 Portfolio Area + IC Project + LP Project 가 동시 참조 (각 Area 다른 annotation) |
| **copy-curate** | method/지식을 *새 Resource artifact 로 저작* (사실 복제 아님). lineage 는 `derived_from_id`(진짜 파생만, 구 `parent_artifact_id`) | 죽은 딜 경쟁분석 → 섹터 Resource 큐레이션, 펀드 결성 템플릿 1호→2호 |
| **move** | 소모성 working corpus → Archive → 폐기 (workspace 레벨 + OneDrive trinity-sync) | LoI 초안 v1~v5, dataroom 원본, 회의 스크래치 |

`artifact_link` 테이블:

```sql
CREATE TABLE artifact_link (
  artifact_id   uuid NOT NULL REFERENCES artifact(id) ON DELETE CASCADE,
  workspace_id  uuid NOT NULL REFERENCES workspace(id) ON DELETE CASCADE,
  link_type     text NOT NULL CHECK (link_type IN ('reference', 'sub_project', 'cross_link')),
  linked_at     timestamptz NOT NULL DEFAULT now(),
  linked_by     text NOT NULL,                       -- user.id or agent.id
  PRIMARY KEY (artifact_id, workspace_id)
);

CREATE INDEX artifact_link_workspace_idx ON artifact_link (workspace_id);
```

dispatch API (substrate, ADR §6 S1):
- `dispatch_artifact(artifact_id, to_workspace_id, mode="link"|"copy_curate"|"move", annotation?)` → **link**(기본) = `artifact_link` row INSERT(+annotation), **copy_curate** = 새 Resource artifact + `derived_from_id`, **move** = workspace 레벨 + OneDrive 이동
- `unlink_artifact(artifact_id, workspace_id)` → link 해제 (`artifact_link` row DELETE). copy_curate 산출은 별 artifact 라 unlink 대상 아님

### Area cardinality + AXEV 현재 seed

**Area 1개 / function**: 중복 function 의 Area 가 둘 생기지 않도록 UI/LLM 가드. 새 Area 만들기 시도 시 기존 Area 와 function overlap 검출 → "기존 `<Area name>` 와 merge 권고" 모달. operator 가 override 시도 시 audit 기록.

AXEV 현재 Area seed (2026-05-23):

| Area | Function | 비고 |
|---|---|---|
| **Finance** | 회계 / 재무 / cash flow / 예산 | frame MCP 의 data 가 주 |
| **BOD** | 이사회 / 결의 / 거버넌스 | resolution + meeting note |
| **Legal** | 계약 / 컴플라이언스 / 등기 | 법무 사항 |
| **License** | AC (Advisory Committee) 라이센스 관리 | AC 관련 |

Resource = 0 (아직 없음). naturally emerge — 첫 Project close 시점 또는 첫 framework consolidate 시점에 생성.

### UX 흐름 4 페이지 분리

UI 측면에서 paraLayer 별 entry point 를 분리 (cross-PARA query 는 별 surface):

| URL | 역할 | 표시 |
|---|---|---|
| `/axe/projects` | 진행 중 Project 리스트 + close button | PROJECT only |
| `/axe/areas` | function 별 living knowledge 그리드 + last-updated heatmap | AREA only |
| `/axe/resources` | reusable template/framework | RESOURCE only |
| `/axe/archive` | 시점형 의사결정 archaeology + search | ARCHIVE only |

각 page 에 "+New Workspace" 시 paraLayer 가 그 page 에 fix (PROJECT page = 새 PROJECT, AREA page = 새 AREA …). 4 page 위에 cross-PARA query 는 Knowledge Overview dashboard 에서 진입.

Workspace create 시 paraLayer 선택 UI (mock):

```
┌─ New Workspace ──────────────────────────────┐
│ Name:      [_______________________________] │
│ Entity:    [axev ▾]                          │
│ paraLayer: ( ) Project  ( ) Area             │
│            ( ) Resource ( ) Archive          │
│                                              │
│ ▶ Target close date (optional, PROJECT only) │
│   [____________]                             │
│                                              │
│              [Cancel]      [Create]          │
└──────────────────────────────────────────────┘
```

### OneDrive 폴더 mirror

trinity-sync 가 Workspace 의 paraLayer 변경을 OneDrive 폴더 이동으로 mirror. **2 시점** 에 file move 발생:

| 시점 | 동작 | 예 |
|---|---|---|
| **dispatch (file 별)** | artifact 에 attached 된 file 1개를 다른 Workspace 로 dispatch 시, 그 file 만 destination Workspace 의 OneDrive 폴더로 부분 이동 (copy mode = OneDrive copy, link mode = OneDrive shortcut/symlink) | IC artifact 의 spreadsheet 1개를 Portfolio Area 로 link |
| **close (workspace 전체)** | Workspace.paraLayer 변경 시 그 Workspace 의 OneDrive 폴더 전체가 destination paraLayer 의 root 로 이동 | `/Ventures/1. Project/Deal X/` → `/Ventures/4. Archive/Deal X/` |

trinity-sync 가 OneDrive driveItem 이동 trigger + Blueprint Workspace.drivePath 업데이트. paraLayer 변경 자동 propagation.

## Knowledge Overview dashboard

회사 지식체계 P → A/R → A 흐름을 한눈에 조망하는 별도 page (`/axe/knowledge`). 4 paraLayer page 위에 cross-PARA view.

### 3-pane layout

```
┌─────────────────────────────────────────────────────────────┐
│  Knowledge Overview (axev)                                  │
├──────────────────┬──────────────────┬───────────────────────┤
│ Layer counts +   │ Sankey: PARA     │ Cross-PARA query 입력 │
│ state            │ flow (지난 30일)  │                       │
│                  │                  │ "portfolio cos 중      │
│ PROJECT:    12   │   PROJECT        │  Q4 churn > 15%"      │
│  - active:   8   │   ↓ dispatch      │                       │
│  - closing:  2   │  copy: 23        │ [Query] [Save]        │
│  - stale:    2   │  link: 15        │                       │
│                  │   ↓                │ 결과: 3 artifact      │
│ AREA:        4   │   AREA   RESOURCE │  - portco Y (0.18)   │
│  - Finance       │   ↓               │  - portco Z (0.17)   │
│  - BOD           │   ↓ reclassify    │  - portco W (0.16)   │
│  - Legal         │  3 (manual)       │  [view citation]      │
│  - License       │                  │                       │
│                  │   ARCHIVE:        │                       │
│ RESOURCE:    0   │   close: 5       │                       │
│ ARCHIVE:    27   │   resurrect: 1   │                       │
└──────────────────┴──────────────────┴───────────────────────┘
```

### Area health alert

각 Area 의 last-updated timestamp 기반:

- **stale** (30일 무변경) — Area 카드에 yellow ⚠ banner
- **inactive** (90일 무변경) — Area 카드에 red ⏸ banner + "이 Area 가 living 인지 재평가" 알림

운영자 review queue 에 자동 추가.

### 추가 view (drill-down)

| View | 표시 |
|---|---|
| **PARA flow over time** | 월 별 P→A/R/A dispatch count 추세 (lifecycle 활성도) |
| **Artifact graph** | citation chain 의 graph 시각화 (artifact ↔ citation source) — 의존성 spot |
| **Provenance trace** | 1 artifact 선택 → 그 artifact 의 모든 dispatch / link / migration history (audit_trail timeline) |

### 의도

Knowledge Overview 의 자체 가치 — **회사의 fact health 가 한눈에**. PARA OS 가 단지 "파일 정리" 가 아니라 살아있는 지식체계라는 것을 운영자/직원이 daily 로 확인할 surface. inactive Area, dispatch 끊긴 흐름, citation chain 깨진 artifact 가 시각적으로 detect 됨.

## MCP tool 분리 (paraLayer 별)

UI 4 page 분리와 같은 원칙으로 MCP tool 도 paraLayer 별 분리. **LLM intent clarity** — tool name 자체에 paraLayer 의도 드러남.

### Workspace level tools

| Tool | 역할 |
|---|---|
| `list_projects(entity?, state?)` | PROJECT only, state = active / closing / stale |
| `list_areas(entity?)` | AREA only, last_updated 정렬 default |
| `list_resources(entity?)` | RESOURCE only |
| `search_archive(entity?, query, since?, until?)` | ARCHIVE only, time-travel + full-text |
| `create_workspace(paraLayer, name, entity, target_close_date?)` | 신규 (4 paraLayer 어디든) |
| `close_workspace(id, dispatch_plan?)` | paraLayer 변경 1회 + 동시 dispatch 가능 |
| `reclassify_workspace(id, new_paraLayer)` | bidirectional reclassify (ARCHIVE resurrect 포함) |

### Artifact level tools

| Tool | 역할 |
|---|---|
| `get_artifact(id)` | 단일 artifact + citations + audit_trail |
| `list_artifacts(workspaceId, schema_id?, paraLayer?)` | filter by workspace / schema / paraLayer |
| `propose_artifact(workspaceId, schema_id, content, citations, confidence?)` | agent propose (audit_trail event: "propose") |
| `dispatch_artifact(artifact_id, to_workspace_id, mode="copy" \| "link")` | copy or link |
| `unlink_artifact(artifact_id, workspace_id)` | link 해제 (copy 는 별 artifact 가 됐기 때문 미적용) |

### Knowledge query

| Tool | 역할 |
|---|---|
| `query_knowledge(query, paraLayers?, entity?, since?)` | KnowQL-lite — cross-PARA / time-travel / confidence filter. agent 가 grep 안 함 |

이유: `list_workspaces(paraLayer=PROJECT)` 같은 generic tool 보다 `list_projects` 가 LLM 의 intent 명확. plan 단계 토큰 절감 + 잘못된 paraLayer 호출 가능성 차단.

## LLM 호출 + Access 정책

artifact 의 두 가지 access pattern 결정:

### Layer 1: LLM 호출 = Max plan OAuth 우선

Artifact extraction / proposing / review 의 LLM 호출은 **Claude Code OAuth token (Anthropic Max plan) 우선**. Anthropic API direct (per-token billing) 은 fallback / 대량 batch 용.

| Surface | 호출 방식 |
|---|---|
| Teams bot | Claude Code OAuth (Max plan session) |
| 로컬 Claude Code CLI | OAuth (operator session) |
| 웹 UI (review queue, ctx review) | OAuth (Max plan, 사용자 본인 session) |
| 대량 batch (한 번에 1000+ artifact extraction) | Anthropic API direct fallback |
| vision-heavy ingest (pdf/pptx 대량) | Anthropic API direct ([기존 패턴 `vision_ingest.py`](/services/blueprint)) |

**비용 측면** — per-token incremental cost 0 (Max plan 안 무제한). 대량 batch / vision-heavy 만 per-token billing 노출.

**기존 패턴 정합** — `vision_ingest.py` 의 API direct 호출은 대량 vision 처리 한정. 같은 원칙을 artifact extraction 으로 확장.

### Layer 2: Access = MCP tool 위주, REST 최소화

Artifact access 의 primary layer 는 **Blueprint MCP tool** (위의 `query_knowledge` / `get_artifact` / `dispatch_artifact` 등). 별도 REST endpoint proliferation 회피.

| Surface | Access |
|---|---|
| Claude Code (CLI / Teams bot / 웹 agent) | Blueprint MCP tool |
| 외부 agent (third-party MCP client) | Blueprint MCP tool (OAuth-RP) |
| 웹 UI (Blueprint Next.js) | 최소 REST endpoint (curation UX 용) |
| Cross-service backend (frame ↔ Blueprint event consumer) | Postgres direct (격리 X — 같은 instance) |

이유: MCP tool surface 한 곳으로 통합 = audit 한 곳, OAuth-RP 한 번 (D-bp-mcp-1), 권한 모델 한 번 (D-bp-entity-17 EntityRole). REST endpoint 가 늘면 권한 모델 중복 + audit silo + version drift.

## 저장 결정 + 대안 비교

**Primary storage = Blueprint Postgres 16** (D-config-16 cutover 완료). 신규 인프라 0. per-customer macmini isolation (D1) 안에서 Blueprint Postgres 동거.

Monolith first — 별도 `KnowledgeStore` service 분리 안 함. Blueprint 가 이미 PARA OS home, surface 분리는 추출 필요 시 나중.

| 대안 | 거절 사유 |
|---|---|
| **Graph DB (Neo4j)** | citation chain 이 graph 형태이긴 하나 query workload 가 hash-lookup + filter 위주. Postgres JSONB GIN index 로 충분. 신규 dependency 추가만 부담 |
| **Vector DB (Qdrant) primary** | 의미 검색은 필요 시 pgvector extension 으로. primary 로 두면 trans actional consistency / FK constraint / audit trail 다 잃음 |
| **ClickHouse** | analytical query OLAP 강점은 있으나 artifact 는 row count < 100k 수준의 transactional/curation workload. column-store 이점 X |
| **MongoDB** | JSONB 의 동등 기능 + sharding 미필요 + frame/hive 와 Postgres 일관성. 별 DB 추가 부담 |
| **SQLite (file-per-workspace)** | concurrent read-write 모델 (multi-agent) 미적합. Postgres advisory lock 으로 자연 |

## 확장 (필요 시 add-on)

기본 Postgres 위에 Phase 별 add-on 가능. 모두 신규 인프라 없이 extension install 수준.

| 확장 | 활성화 조건 |
|---|---|
| `pgvector` | semantic search (artifact content / citation text embedding) 필요 시. Stage 2 의 cross-PARA query 가 정확도 부족하면 도입 |
| `pg_jsonschema` | content + audit_trail JSONB validation 강제 시. schema_id 별로 JSON Schema 등록 → INSERT/UPDATE 시 reject |
| `temporal_tables` (또는 `timestamptz` column + soft archive) | time-travel query 정확도 필요 시. Stage 1 까지는 `updated_at` + `archived_at` 으로 충분 |

## 단계 (활성화 조건 충족 시 — 활성화 자체는 다음 결정)

[M3 PARA Dispatch](/ops/roadmap#m3--blueprint-para-dispatch-d-bp-entity-1-pr-5) land + [M1 multi-tenant](/ops/roadmap#m1--stage-0--1-외부-출시) 종료 가 자연스러운 entry. 단 평행 진행 가능 — 외부 surface 영향 0.

| Stage | 산출 | 기간 |
|---|---|---|
| **0. PoC** | filesystem-only 첫 schema (`ICMemoArtifact §재무`) — DB 변화 0. ctx 의 markdown diff UX 위에 typed extraction proof | ~3일 |
| **1. DB 진입** | `Artifact` + `Citation` Prisma migration, KnowQL-lite HTTP endpoint, Blueprint UI 탭 1개 | ~3-4주 |
| **2. Full integration** | 5종 schema (IC / Board / LP / Sector / KPI) active, PARA dispatch field-level engine, ctx 진화 (curation mode) | ~3-4주 |

## Open implementation decisions

본 페이지의 design 위에 implementation 단계에서 결정할 항목들. 각 항목마다 framework (방향성) 만 명시, 구체 결정은 deferred. **Implementation 단계에서 각 항목 결정 시 D-bp-artifact-N 추가 등재**.

| # | 항목 | Framework (방향성) |
|---|---|---|
| **B1** | Agent ↔ artifact API contract | Agent (Claude / Teams bot) 의 artifact propose 권한은 implementation 시 [D-bp-entity-17](/ops/decisions) EntityRole 위에 layer 추가 검토. propose 는 ctx review queue 경유 default — 직접 confirmed 진입은 별 권한 grant 필요 |
| **B2** | Schema evolution 호환성 | Schema versioning: MCP source schema 변경 = MCP 의 도메인 정책 따름 (frame/hive 각자 backward compat 책임). free-form artifact 는 `schema_id` 마다 append-only 보존 (`freeform.llm@auto-2026-05` 같은 timestamped variant). forced migration 도구는 implementation 시 결정 |
| **B3** | Concurrent write 정책 | optimistic lock (`updated_at` version check) + audit_trail conflict event. detail TBD — 첫 multi-agent concurrent write 발견 시 결정 |
| **B4** | Time-travel 정확도 | Stage 1 = `updated_at` filter (근사). Stage 2 = audit_trail event replay. snapshot table 신설 여부는 정확도 정당화 시점에 결정 (e.g., IRR 결정론 검증이 시점 정확도 요구할 때) |
| **B5** | Failure modes (degradation) | graceful degradation 원칙: (a) LLM extraction 실패 → markdown fallback (raw content + warning); (b) Citation resolver 실패 → cached value + warning chip; (c) Dispatch partial fail → savepoint rollback (all-or-nothing). detail TBD |
| **C1** | Cross-customer aggregation | per-customer macmini isolation ([D1](/ops/decisions)) 의도된 격리 유지. meta-layer aggregation (예: AXE 가 운영하는 N customer 의 PARA flow 집계) 미설계. 외부 GP 명시 요구 시 재검토 |
| **C2** | axec PARA 구조 | axec / axev / sys entity 각각 자체 PARA tree. axec Area 정의는 axec workflow 진행 시 자연 emerge (현재 axec workflow 비중 낮음 — axev 가 primary) |
| **C3** | Resource 외부 import | 외부 framework (e.g., Atomico VC playbook, McKinsey portfolio template) 의 RESOURCE 등재는 implementation 시 IP / license 정책 합의 후 결정. v1 = AXE 내부 사용만 |
| **C4** | Multi-language artifact | v1 = 한국어 우선 (모든 schema 정의 + UI 한국어). content 안 영문 field 가 자연 등장 시 (예: 외국인 employee record, 영문 LP comm) schema 별 multi-lang 결정 |

각 항목은 implementation PR 시점에 D-bp-artifact-N 으로 등재 + 본 표 update. framework 만으로 시작 가능 (구체 결정 deferred 가 작업 정체 trigger 아님).

## 관련 결정

- [D-bp-artifact-1~7](/ops/decisions) (본 페이지 등재 동반, 2026-05-23)
- [D-bp-entity-1](/ops/decisions) (Blueprint entity 개념 + PARA 4 layer schema)
- [D-bp-entity-2](/ops/decisions) (PARA dispatch workspace-level provenance — 본 페이지가 field-level 진화)
- [D-bp-entity-17](/ops/decisions) (EntityRole — propose/review 권한 layer 의 base)
- [D-config-16](/ops/decisions) (Blueprint Postgres — artifact 거주지)

## 관련 페이지

- [/services/blueprint](/services/blueprint) — Blueprint 서비스 페이지의 artifact 섹션
- [/ops/roadmap M3, M6](/ops/roadmap) — PARA dispatch + artifact layer
- [/architecture/data](/architecture/data) — 데이터 격리 모델 (entityId scope)
- [/ops/backlog](/ops/backlog) — M6 태그 항목들

---

<!-- PAGE https://docs.axelabs.ai/architecture/auth -->

# 인증 · 권한

> Microsoft Entra ID OAuth 2.0, frame JWT, dual-token model.

URL: https://docs.axelabs.ai/architecture/auth

# 인증 · 권한

## 3 가지 인증 경로

| 경로 | 사용 주체 | 토큰 | 검증 |
|---|---|---|---|
| **A. Microsoft Entra ID OAuth** | 직원 (Claude Code / claude.ai) | access_token (RS256, Microsoft 서명) | frame middleware: JWKS RS256 + aud match |
| **B. frame HS256 JWT** | 운영자 / 서비스 토큰 (cron job 등) | HS256 (FRAME_JWT_SECRET 으로 서명) | frame middleware: `audience=client_id` |
| **C. dual-token** | Blueprint agent + per-user 위임 | (agent_jwt, user_jwt) | intersection of permissions |

`iss` claim 으로 자동 dispatch — `https://login.microsoftonline.com/...` 시작이면 A, 아니면 B.

> **경로 D — Blueprint 플랫폼 토큰 (D-axe-idp-1, Phase 1+2 LIVE 2026-06-04)**: **Blueprint = 플랫폼 OIDC Provider** 가 4번째 신뢰 발행자로 합류 — 로그인 1회로 전 서비스. Blueprint 가 Entra 를 federate(기존 NextAuth 세션 재사용) + RS256 플랫폼 토큰 발행(`/oauth/*` + `/.well-known/{openid-configuration,jwks.json}` on `blueprint.axellc.com`). 각 서비스는 `iss=blueprint` 분기에서 Blueprint JWKS 로 RS256 검증(`aud=https://axe.axelabs.ai`), email→entity 는 기존 `customers.yaml` 그대로. **frame·hive·cortex·index·matrix + Blueprint 자체 MCP — 6개 서비스 전부 Blueprint 토큰 신뢰** (Python: `auth_blueprint.py` + `is_blueprint_iss` dispatch / Rust: `peek_iss`→`verify_rs256` vs Blueprint JWKS). 영속 설정(compose/`.env.local` 의 `BLUEPRINT_ISSUER` 기본값)·e2e 검증(`axe login` → `axe <svc> tools` GREEN). 비파괴 롤백 = 서비스 `BLUEPRINT_*` env 제거(unset=종전 Microsoft 경로). 설계·현행 SSOT: [/architecture/platform-identity](/architecture/platform-identity).

## 경로 A — Microsoft Entra ID (직원)

각 customer 의 Microsoft Entra ID tenant 에 **5 개의 app** 이 등록되어 있어야 합니다 (axe customer 2026-05-21 현재):

| App 이름 | 용도 | 토큰 종류 | 비고 |
|---|---|---|---|
| Frame MCP | 회계 backend 접근 | access_token (aud=client_id, v2) | public client + PKCE (`b7ead15d-...` Hive 패턴) |
| Hive MCP | HR backend 접근 | access_token (aud=client_id, v2) | public client + PKCE, `client_id=b7ead15d-2fea-4864-a5a8-b4b07d1629d4` |
| Blueprint MCP | platform MCP at apex | access_token (aud=URI, v1) | public client + PKCE, `/api/mcp` apex |
| Vaultwarden | password vault SSO | OIDC id_token | confidential, secret 보관 |
| Blueprint Web | web UI 로그인 | OIDC id_token | NextAuth |

자동 등록: `az ad app create` + `az rest --method PATCH /applications/APP_ID` (identifierUris + requestedAccessTokenVersion=2 + oauth2PermissionScopes.value="mcp.access"). 운영자 손작업 = `axe.axelabs.ai` 도메인 검증 1회만.

### Frame MCP app 설정 (현재 axe live)

```yaml
client_id:           137fc0ef-eb9f-4903-acbc-1a748add349c
application_id_uri:  https://axe.axelabs.ai/frame/mcp    # 도메인 검증 필요
tenant_id:           122fb574-7efa-476a-95b6-bee81bce2cce
platform:            Web
redirect_uris:
  - https://claude.ai/api/mcp/auth_callback
  - https://claude.com/api/mcp/auth_callback
scopes:
  - openid
  - profile
  - email
  - https://axe.axelabs.ai/frame/mcp/mcp.access
allow_public_client_flows: true   # PKCE 활성 (manifest `isFallbackPublicClient: true`)
# client_secret 발급 여부:
#   - 직접-Microsoft path (현재 live):     발급 X (PKCE-only, claude.ai 가 secret 안 보냄)
#   - OAuth proxy path (D-ops-15 dormant): 발급 + frame .env 에 보관
# access_token_version (manifest `requestedAccessTokenVersion`):
#   - null/1 → access_token aud = Application ID URI (https://...)
#   - 2      → access_token aud = client_id GUID
# frame middleware 는 양쪽 모두 수용 (audiences=[client_id, app_id_uri]).
```

### Azure App ID URI

Microsoft v2 endpoint 의 **resource indicator** 와 **scope URI prefix** 가 정확히 일치해야 Microsoft 가 token 발급. 발견된 함정:

- **AADSTS9010010**: scope=`api://137fc0ef-.../mcp.access` + resource=`https://axe.axelabs.ai/frame/mcp` → mismatch.
- 해결: domain verify (`axe.axelabs.ai` 에 TXT `MS=ms...` 등록) → Application ID URI 를 `https://axe.axelabs.ai/frame/mcp` (URL 형식) 로 변경 → scope 도 같은 prefix.

## frame OAuth-RP middleware

frame 서버의 `auth_oidc.py` 가 다음을 수행:

1. `Authorization: Bearer &lt;access_token&gt;` 헤더 추출
2. `iss` claim peek (서명 검증 전 unverified decode) → Microsoft 시작이면 A 경로
3. Microsoft JWKS fetch (1h TTL, kid miss 시 강제 갱신)
4. RS256 서명 검증
5. **audience 검증**: token `aud` 가 `{client_id GUID, Application ID URI}` 중 하나와 일치 (v1/v2 호환)
6. issuer 검증: `https://login.microsoftonline.com/{tenant_id}/v2.0`
7. `email` / `preferred_username` / `upn` 중 첫 비어 있지 않은 값 → email
8. `customers.yaml > user_entity_map[email]` → entity 권한 dict 매핑
9. `TokenClaims` 생성 → ContextVar 주입 → tool 호출에 사용

### RFC 9728 protected-resource metadata path

claude.ai Connector 와 다른 MCP client 가 OAuth challenge 시작 시 fetch 하는 metadata endpoint 는 **두 path** 에서 동일한 응답:

| Path | 용도 |
|---|---|
| `/frame/.well-known/oauth-protected-resource` | server-level (RFC 8615 base URL convention) |
| `/frame/mcp/.well-known/oauth-protected-resource` | resource-level (RFC 9728 — application_id_uri 의 sub-path). claude.ai Connector / Anthropic MCP client 가 이 path 를 fetch |

양쪽 모두 `_PUBLIC_PATHS` 로 unauthenticated 면제 + `inner.router` 에 같은 handler 마운트. 401 응답의 `WWW-Authenticate: Bearer realm="frame", resource_metadata="..."` 가 가리키는 URL 도 양쪽 모두 valid (D-ops-23, 2026-05-22 — 이전엔 resource-level path 401 → claude.ai Reconnect silently 실패).

### Schema discovery — auth-required

`/frame/schemas` (그리고 hive 의 `/hive/schemas`) 는 RFC 9728 metadata 와 달리 **auth-required** — `_PUBLIC_PATHS` 미포함. JWTAuthMiddleware 가 일반 MCP 호출과 동일 검증 적용. Blueprint artifact + PARA 지식 레이어 ([D-bp-artifact-1](/ops/decisions)) 가 fetch 시 자기 MCP 토큰 재사용. 자세한 endpoint contract = [services/frame § Schema discovery](/services/frame#schema-discovery--get-frameschemas).

## 권한 모델 — Scope

```
read  < write < close < admin
```

- `read` — query_balance, list_journals
- `write` — post_journal, flag_uncertainty
- `close` — soft_close period, hard_close (운영자)
- `reopen` — 폐쇄된 period 재오픈 (드물게)
- `admin` — chart of accounts 변경, policy 마이그레이션

권한은 **entity 별로** 부여 (예: `{"axec": ["read", "write"], "axev": ["read"]}`).

## dual-token (CFO + accountant 패턴)

CFO 에이전트가 회계사 A 를 대신해 활동할 때:

```
Authorization: Bearer &lt;CFO agent JWT&gt;         ← 광범위한 권한
X-User-Token:   &lt;accountant A JWT&gt;            ← axec 만, read+write
```

frame 의 `dual_authorize(agent, user, entity, scope)` 가 두 토큰의 권한 교집합으로 게이팅:

```python
effective_scopes = agent.permissions["axec"] ∩ user.permissions["axec"]
```

최소 권한 원칙 강제. agent 가 admin 이어도 user 가 read-only 면 read 만 가능.

## 운영자 자체 토큰

운영자 (`ai@axellc.com`) 가 CLI 에서 직접 호출 시:

```bash
docker exec frame-mcp-blue python -m frame.cli mcp-token \
    --sub ai@axellc.com \
    --customer axe \
    --entity axec:read,write,close \
    --entity axev:read,write,close \
    --ttl 2592000      # 30 days
```

→ HS256 frame JWT 발급. 경로 B 로 검증.

운영자 토큰은 **Vaultwarden 의 `axe-frame-jwt` collection** 에 보관 (entity 별 vault).

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| Application ID URI 와 scope prefix 불일치 | AADSTS9010010 | 두 값 같은 URL prefix |
| Allow public client flows: No + secret 없음 | AADSTS7000218 | Yes 토글 OR secret 입력 |
| accessTokenAcceptedVersion=2 + aud check on URL | mcp_client_invalid | **v2 강제 + middleware multi-issuer 양쪽 모두**: (1) Azure app 등록 시 `requestedAccessTokenVersion=2` 강제 (bootstrap.sh manifest PATCH 시점), (2) middleware 가 v1+v2 issuer 양쪽 수용 (defense in depth — v1 token 이 어떤 사유로 들어와도 graceful 처리). 단독 (1) = bootstrap PATCH 누락 시 사고. 단독 (2) = client 측 v1 token 발급 자유 잔존. |
| App ID URI 삭제 (cleanup 잘못) | AADSTS500011 resource principal not found | 복원 후 propagation 5-10분 대기 |
| 잘못된 client_id 입력 (vaultwarden vs frame_mcp) | AADSTS700016 application not found | customers.yaml 확인 |
| `az ad app create` 후 sign-in 시도 → 즉시 실패 | Entra trace ID + "Authorization with the MCP server failed". `az ad app create` 는 **application object 만 생성, Service Principal 자동 생성 X** | `az ad sp create --id <appId>` 별도 호출 |
| SP 있는데 sign-in 시 같은 메시지 | Service Principal 존재해도 `requiredResourceAccess` 비어 있고 admin consent 안 받음 | manifest 에 `mcp.access` (self) + Graph `User.Read` (e1fe6dd8-ba31-4d61-89e7-88639da4683d) `requiredResourceAccess` 추가 후 admin consent grant |
| `az ad app permission admin-consent` → 403 Forbidden | 명령 실행 user 가 tenant admin role 없음 ("This operation can only be performed by an administrator") | (a) Portal UI: App registrations → 해당 app → API permissions → "Grant admin consent for {`{tenant}`}" 버튼, (b) admin user 로 `az login` 후 명령 재실행 |
| `az ad app credential reset --append` parsing 시 stderr 섞임 | JSON 출력에 progress 메시지 혼합 → `python3 -c "json.load"` 실패 | `--query 'password' -o tsv` 로 단일 필드 추출 |
| Vaultwarden SSO with Microsoft Entra ID → "Your provider does not send email verification status" | Entra ID id_token 에 `email_verified` claim 없음, Timshel fork 가 거부 | `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"` 추가 (D-ops-24, 2026-05-22) |
| Blueprint OAuth scope 추가 (`SCOPES` in `src/lib/graph.ts`) ship 후 admin consent grant 누락 | (1) 모든 user 의 GraphToken refresh 침묵 실패 — UI 상 "Connected" 표시 유지하나 실 호출 시 401/403, (2) 새 user OAuth flow 차단 `AADSTS65001 Consent_VersionMismatch`, (3) `acquireTokenByClientCredential` 캐시된 옛 토큰 (insufficient-scope) 계속 반환 | (1) ship 직후 `az ad app permission admin-consent --id <client_id>` 실행, (2) `docker restart blueprint-app-green` (또는 -blue) — MSAL in-memory 캐시 폐기, (3) 자동화 후보: `axe ship blueprint` post-deploy hook + Blueprint daily token health check ([B-blueprint-scope-change-admin-consent-runbook](/ops/backlog) 참조). 절차 상세 = 아래 [OAuth scope 추가 시 운영자 절차](#oauth-scope-추가-시-운영자-절차) |
| Frame/Hive MCP middleware 의 `_MICROSOFT_ISS_PREFIX` 가 v2 issuer prefix (`https://login.microsoftonline.com/`) 만 매치 (trap #33, Truvia 2026-05-25 보고) | Microsoft v1 access_token (iss=`https://sts.windows.net/<tenant>/`) 보내면 middleware 가 Microsoft 경로 미인식 → HS256 fallback path 진입 → `algorithms=["RS256"]` allowlist 가 RS256 token 을 잘못된 path 에서 reject → `The specified alg value is not allowed` | (1) Azure app 등록 시 `requestedAccessTokenVersion=2` 강제 (bootstrap.sh + 등록 후 manifest 검증 — Truvia 우회 = 3 MCP app 모두 manifest PATCH), (2) middleware 가 v1+v2 issuer 양쪽 수용 (Blueprint MCP 의 `config.py:76,81` + `auth_oidc.py:153` 패턴 mirror). 위치: `/Users/axe/frame/src/frame/mcp/http_server.py:141` + `/Users/axe/hive/src/hive/mcp/http_server.py:67`. 영구 fix = [B-trap-33-frame-hive-multi-issuer](/ops/backlog) (code portion 잔존, docs portion ✅ 2026-05-28) |

상세 troubleshooting: [/onboard/troubleshooting](/onboard/troubleshooting).

## OAuth scope 추가 시 운영자 절차

Blueprint Next.js app (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`) 의 `SCOPES` array (`src/lib/graph.ts`) 변경 ship 시 다음 순서를 그대로 따를 것. 누락 시 위 함정 표 마지막 row 의 3 가지 증상 발현 (2026-05-26 D-bp-mcp-calendar-1 ship 후 발현 사례 있음).

```bash
# 1. SCOPES array 변경 commit + ship
cd /Users/axe/blueprint && axe ship

# 2. admin consent grant (운영자 = Global Admin 만 가능, soohun.kang)
az login --allow-no-subscriptions
az ad app permission admin-consent --id <client_id>
# (client_id = Blueprint Next.js app, 예: 2b222356-1c36-48e0-96a3-2c5e0ecbf937)

# 3. blueprint-app 재시작 (MSAL in-memory 캐시 폐기)
ssh axe-macmini "cd /Users/axe/blueprint && docker compose restart blueprint-app-blue blueprint-app-green"

# 4. 검증 (token health)
# - /api/admin/graph-tokens (또는 /settings) 에서 각 user 의 expiresAt 갱신 확인
# - 본인 계정으로 Graph API 호출 1회 (e.g. /api/admin/broadcast-dm test)

# 5. user 측 reconnect 안내 (Teams DM)
# - admin consent 후에도 옛 refresh token 의 grant 가 새 scope 안 가짐
# - 각 user 가 /api/graph/auth 재방문 → 새 scope 포함 consent → 새 refresh token 발급
```

본 절차 가운데 step 3 (MSAL in-memory cache 폐기) 의 근본 원인은 [/ops/known-gaps#msal-acquiretokenbyclientcredential-토큰-캐시](/ops/known-gaps) 참조. Blueprint 의 Azure App 2 개 (Next.js app `2b222356-...` vs MCP custom connector `482598f7-540c-462c-9dfd-b957651eb804`) 구분도 같은 페이지에 있음 — 본 SCOPES 변경 및 admin consent 는 **Next.js app 측에만** 적용.

## app-only Application permission (send-as)

위 [OAuth scope 추가 시 운영자 절차](#oauth-scope-추가-시-운영자-절차) 는 **delegated** scope (`SCOPES` in `src/lib/graph.ts`, caller 본인 토큰) 변경용이다. 그와 별개로, **admin send-as** 기능 (caller `role=admin` 이 타 사용자 리소스에 write) 은 app-only token (`getAppOnlyClient()` = `acquireTokenByClientCredential`) 을 쓰며, **Application permission** + tenant admin consent 를 요구한다. delegated 와 달리 사용자별 re-consent 가 아니라 테넌트 1회 admin consent 다.

대상 App = **Blueprint Next.js app (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`)** — MCP connector app (`482598f7-...`) 이 아니다 (함정 [/ops/known-gaps#blueprint-azure-app-id-혼동](/ops/known-gaps#blueprint-azure-app-id-혼동)).

| 기능 | Application permission | delegated 대응 (이미 SCOPES) | 결정 |
|---|---|---|---|
| calendar send-as (`create_event` 등 `as_user_email`) | `Calendars.ReadWrite` | `Calendars.ReadWrite` | D-bp-mcp-calendar-2 |
| `send_mail` send-as (`as_user_email`) | `Mail.Send` | `Mail.Send` (→ self 발송은 추가 consent 불필요) | D-bp-mcp-mail-1 |

```bash
# 1. permission 추가: Azure Portal → App registrations → Blueprint (Next.js)
#    → API permissions → Add → Microsoft Graph → Application permissions
#    → Mail.Send (well-known roleId b633e1c5-b582-4048-a93e-9f11b44c7e96)
# 2. tenant admin consent (Global Admin 계정 — AXE 테넌트는 soohun.kang 만)
az ad app permission admin-consent --id 2b222356-1c36-48e0-96a3-2c5e0ecbf937
# 3. MSAL client-credential in-memory 캐시 폐기 (옛 insufficient-scope 토큰 재사용 방지)
docker restart blueprint-app-blue   # 또는 -green
```

consent 누락 시 send-as 호출은 Graph 403 → 코드가 `mail_send_not_consented` (mail) / `app_only_token_unavailable` (calendar) 로 surface. self (delegated) 경로는 본 permission 없이도 동작하므로 **send-as 만** 영향.

---

<!-- PAGE https://docs.axelabs.ai/architecture/axe-ui -->

# @axe/ui 디자인 시스템

> AXE Labs 디자인 토큰 + 컴포넌트 라이브러리를 sync 스크립트 방식으로 소비. light/dark 토글, 5분 셋업, dogfood = axelabs.ai.

URL: https://docs.axelabs.ai/architecture/axe-ui

# @axe/ui 디자인 시스템

AXE Labs 의 단일 디자인 시스템 (`@axe/ui`). 색·간격·타이포·폰트 토큰 + 컴포넌트 클래스를 모든 React 소비자 (Blueprint · frame admin · hive admin · docs.axelabs.ai · axelabs.ai 회사 홈) 가 공유. npm registry 없이 **git+ssh 또는 sync 스크립트** 로 전파 ([D-axe-ui-1](/ops/decisions)).

> **본 페이지는 새 프로젝트에 적용하는 절차서**. 운영 중 변경 흐름은 [/ops/backlog](/ops/backlog) + [/ops/updates](/ops/updates).

## SSOT 경로

`/Users/axe/axelabs/` (github: `soohunkang/axelabs`) — 디자인 시스템 본가:

```
src/lib/
├── tokens/          colors · spacing · typography · fonts · index
└── styles/          reset · components
```

Canonical sync 스크립트: `/Users/axe/axelabs-docs/scripts/sync-axe-ui.mjs` — 그대로 복사 가능.

## 적용 절차 (Next.js 기준 5분)

### 1. sync 스크립트 복사

```bash
cp /Users/axe/axelabs-docs/scripts/sync-axe-ui.mjs PROJECT/scripts/
```

스크립트 안의 `axeLabsRoot` 가 `join(repoRoot, "..", "axelabs")` 로 잡혀 있음. 새 프로젝트가 `axelabs/` 와 같은 부모 디렉토리 (`/Users/axe/`) 에 있으면 그대로 OK. 다르면 그 한 줄만 수정.

### 2. `package.json` 의 `scripts` 에 4 줄 추가

```json
"sync-axe-ui":  "node scripts/sync-axe-ui.mjs",
"check-axe-ui": "node scripts/sync-axe-ui.mjs && git --no-pager diff --stat -- app/_axe-ui/ ':!app/_axe-ui/VERSION' && git checkout -- app/_axe-ui/",
"predev":       "node scripts/sync-axe-ui.mjs",
"prebuild":     "node scripts/sync-axe-ui.mjs"
```

### 3. 최초 sync 실행

```bash
npm run sync-axe-ui
# → app/_axe-ui/{tokens,styles,VERSION} 생성됨
```

### 4. `app/globals.css` 첫 부분에 import

Nextra/theme CSS **뒤에** 와야 override 됨:

```css
@import "./_axe-ui/tokens/colors.css";
@import "./_axe-ui/tokens/spacing.css";
@import "./_axe-ui/tokens/typography.css";
@import "./_axe-ui/tokens/fonts.css";
```

### 5. (선택) 컴포넌트 클래스도 사용

```css
@import "./_axe-ui/styles/reset.css";
@import "./_axe-ui/styles/components.css";
```

### 6. `app/_axe-ui/` 전체를 git commit

Docker/CI 빌드 안에서는 `axelabs/` 경로가 없음 — committed 산출물로 동작 (스크립트가 graceful skip).

## 테마 토글 — class · attribute 둘 다 지원

axelabs HEAD `ff6eb27` (2026-05-22) 이후 두 전략 모두 자동 매핑.

### A) class 전략 — next-themes 기본값

HTML 의 root element 에 `class="light"` 또는 `class="dark"`. Nextra docs 같이 next-themes 쓰면 추가 설정 불필요.

### B) attribute 전략 — root element 의 `data-theme` 속성

직접 토글 시:

```ts
useEffect(() => {
  document.documentElement.setAttribute("data-theme", mode);
}, [mode]);
```

둘 중 어느 쪽이든 토큰 정확히 매핑. OS `prefers-color-scheme` 도 명시적 light 선택을 덮어쓰지 않음.

## 검증

| 모드 | body bg | accent |
|---|---|---|
| light | `#f5f1e8` (cream) | `#821f3b` (claret) |
| dark | `#1a0610` (noir) | `#e3ff66` (neon) |

토글 시 즉시 반영. OS=dark + 사용자 "light" 선택해도 dark 로 안 어긋남.

## 최신 버전 체크 — 개발 중 SSOT 변경 감지

```bash
# 현재 sync 상태
cat app/_axe-ui/VERSION
# @axe/ui 0.1.0
# synced-at: 2026-05-22T...
# source: /Users/axe/axelabs
# source-sha: ff6eb27        ← axelabs HEAD
# source-lib-sha: ff6eb27    ← src/lib 마지막 변경 SHA
# source-lib-date: 2026-05-22 10:41:53 +0900

# 받을 변경 있나 (dry-run, 파일 안 건드림)
npm run check-axe-ui
# 빈 출력           = 최신
# "N files changed" = 받을 변경 있음

# axelabs 측에서 놓친 commit 목록
git -C /Users/axe/axelabs log SOURCE-LIB-SHA..HEAD -- src/lib/

# 실제로 받기
npm run sync-axe-ui && git add app/_axe-ui/ && git diff --staged
# 검토 후 commit: "sync(ui): @axe/ui bump to SHA"
# axe ship SERVICE
```

**자동**: `npm run dev` / `npm run build` 시 `predev`/`prebuild` hook 이 매번 sync 돌림. diff 가 생기면 그때 commit + ship 결정.

## 적용된 소비자

| 프로젝트 | 전략 | 비고 |
|---|---|---|
| `/Users/axe/axelabs-docs` | class | Nextra docs (본 페이지 포함) |
| `/Users/axe/axelabs/app/ui` | attribute | axelabs 메인 (디자인 시스템 자기 dogfood) |
| Blueprint | _예정_ | [B-axe-ui-blueprint-migrate](/ops/backlog) |
| frame admin / hive admin | _예정_ | 외부 customer rollout 전 |

## 관련 결정

- [D-axe-ui-1](/ops/decisions) — `@axe/ui` 단일 배포 채널 = git+ssh + axelabs.ai dogfood (Verdaccio / GitHub Packages / npm publish 모두 미사용 — 소비자 ≤3개 시점에서 부담만)
- [B-axelabs-ai-live](/ops/backlog) — axelabs.ai 도메인 라이브 배포 (production tag 핀 가능 시점 prereq)
- [B-axe-ui-v0.1-tag](/ops/backlog) — `v0.1.0` git tag (외부 소비자 stable 버전 시작점)

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| sync 스크립트가 axelabs 경로 못 찾음 (Docker/CI) | sync graceful skip, committed `app/_axe-ui/` 사용 | 본 디렉토리 항상 commit + Dockerfile 의 `COPY . .` 에 포함 |
| Nextra theme CSS 가 토큰 override | 색 안 적용 | `@import` 순서 — `globals.css` 의 첫 부분 |
| Fontshare `@import` 의 `f[]=` drop (Blueprint 사례) | font 로드 실패 | `<link>` 방식 + Clash Display 패턴 일치 |
| OS `prefers-color-scheme` 이 사용자 선택 override | 토글 후 OS 따라 깜빡 | axelabs `ff6eb27` 이후 자동 회피 (사용자 명시 우선) |

---

<!-- PAGE https://docs.axelabs.ai/architecture/backup -->

# 백업 · DR

> restic 3-tier (local · ring P2P · cold SSD), restore drill.

URL: https://docs.axelabs.ai/architecture/backup

# 백업 · DR

## 3-tier 전략

```
Tier A — 로컬 (실시간 보호)
   restic repo /Users/axe/.axe/backups/local/
   매일 03:00 KST, com.axe.backup.local

Tier B — P2P ring (cross-customer 양방향)
   axe-macmini ↔ realchoice-macmini  (SSH key, Tailscale)
   매일 03:30 KST, com.axe.ring.push

Tier C — Cold SSD (offline 보호)
   외장 SSD rotation /Volumes/axe-cold-{1,2,3}
   mount 시 자동 sync
```

## Tier A — 로컬 (live)

| 항목 | 값 |
|---|---|
| Repo path | `/Users/axe/.axe/backups/local/` |
| Restic version | 0.18.1+ |
| Password | macOS Keychain (`axe.backup.restic.local`) |
| 백업 대상 | frame-postgres dump + **blueprint-postgres dump** (D-config-17 cutover 후, 2026-05-15~) + **hive-postgres dump** (D-hive-backup, 2026-05-21~ — Phase 1 조직/휴가 + Phase 3 payroll v2 실데이터) + **mysrt-postgres dump** (B-mysrt-backup-decision, 2026-06-06~ — users/jobs/push_subscriptions; SRT는 train/예약의 SoT일 뿐 계정·잡설정 SoT 아님) + **index-postgres dump** (D-index-51, 2026-06-06~ — `evidence_blob` = 죽은 딜 OneDrive/Blueprint 원본 삭제 후 **유일 사본**, 312MB bytea → ~633MB `pg_dumpall`, restic content-dedup 으로 ~274MB stored) + `.local/files/` (platform data) |
| 빈도 | 매일 03:00 KST (`com.axe.backup.local` launchd) |
| 현재 크기 | ~429 MiB raw-data (2026-06-06 — index-postgres 흡수 후, restic dedup 적용) |
| Excludes | `/Users/axe/.axe/bin/restic-excludes` |

### 명령어

```bash
# 수동 백업
axe backup --local

# 백업 상태 확인
restic -r /Users/axe/.axe/backups/local snapshots \
  --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local)

# 복원 (dry-run)
axe restore --customer axe --from local --as-of 2026-05-20 --dry-run
```

## Tier B — P2P ring

axe ↔ realchoice 양방향 백업 (각자 다른 macmini 의 백업을 보관).

```
axe-macmini → realchoice-macmini 의 /Users/realchoice/peer-backups/axe/
realchoice-macmini → axe-macmini 의 /Users/axe/.axe/backups/peer/realchoice/
```

| 항목 | 값 |
|---|---|
| 전송 | restic `sftp:` backend (SSH key) |
| auth | SSH key (~/.ssh/id_ed25519, 비밀번호 없음) |
| 빈도 | 매일 03:30 KST (`com.axe.ring.push` launchd) |
| 검증 | bidirectional_ssh 2026-05-15 검증 완료 |

`customers.yaml` 에 ring backup 메타 등록:

```yaml
realchoice:
  ring_backup:
    ssh_user: "realchoice"
    ssh_fqdn: "realchoice-macmini.tail090015.ts.net"
    ssh_ip: "100.114.161.51"
    receive_dir_at_peer: "/Users/realchoice/peer-backups/axe/"
    receive_dir_at_self: "/Users/axe/.axe/backups/peer/realchoice/"
    restic_version: "0.18.1"
    disk_available_gib: 43
    bidirectional_ssh: true
```

### 함정

- **Tailscale alone 으로는 충분하지 않음** — SSH key 가 별도 필요. Tailscale 인증 없어도 작동.
- **Cross-customer 백업 = 데이터 노출 risk** — 양측 운영자 모두 합의 + restic 암호화로 컨텐츠 보호.

## Tier C — Cold SSD (offline)

외장 SSD 를 분기별로 rotation. mount 가 감지되면 자동 sync.

| 항목 | 값 |
|---|---|
| Mount path | `/Volumes/axe-cold-{1,2,3}` (rotation) |
| Restic repo | `/Volumes/axe-cold-N/restic-repo/` (N = 1, 2, 3 — rotation index) |
| Password | 종이 메모 (vault 안에 넣지 말 것 — closed-loop 방지) |
| Rotation | 분기별 (Q1 = SSD #1, Q2 = SSD #2, ...) |
| Drill | 분기마다 자동 restore drill (`com.axe.restore-drill`, Jan/Apr/Jul/Oct 15 03:00 KST) |

### 왜 종이?

cold storage 의 password 를 self-host vault 에 넣으면 vault 가 사라졌을 때 cold storage 도 못 풉니다 (closed loop). 종이 + 운영자 머리 = 이중화.

## 복원 절차

### 시나리오 1 — frame DB 손상 (오타 / migration 사고)

```bash
# 1. 어제 03:00 KST 백업 복원
axe restore --customer axe --tier local --as-of 2026-05-20T03:00 --target frame-postgres

# 2. frame 재시작
docker compose restart frame-mcp-blue frame-mcp-green

# 3. 정합성 검사
docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axec
```

### 시나리오 1b — blueprint DB 손상

```bash
# 1. 어제 03:00 KST 백업 복원
axe restore --customer axe --tier local --as-of 2026-05-20T03:00 --target blueprint-postgres

# 2. blueprint app + mcp 재시작 (PR #337 이후 blue/green pair)
docker compose -f /Users/axe/blueprint/docker/docker-compose.yml restart app-green blueprint-mcp-blue blueprint-mcp-green

# 3. 정합성 검사 (Prisma client round-trip)
docker exec blueprint-app-green node -e "const {PrismaClient}=require('@prisma/client'); new PrismaClient().workspace.count().then(n=>console.log('workspaces:',n))"
```

### 시나리오 1c — hive DB 손상

```bash
# 1. 어제 03:00 KST 백업 복원
axe restore --customer axe --tier local --as-of 2026-05-20T03:00 --target hive-postgres

# 2. hive 재시작 (Phase 1 조직/휴가 + Phase 3 payroll v2)
docker compose -f /Users/axe/hive/docker-compose.yml restart hive-postgres hive-mcp-blue hive-mcp-green

# 3. 정합성 검사 (axec/axev 테넌트별 employee count round-trip)
docker exec hive-postgres psql -U hive -d hive -c \
  "SELECT 'axec' AS tenant, COUNT(*) FROM axec.employees
   UNION ALL SELECT 'axev', COUNT(*) FROM axev.employees;"
```

### 시나리오 2 — macmini 자체 손실 (도난, 화재)

```bash
# 1. 새 macmini 셋업 (Tailscale 설치, axe CLI install)
# 2. ring peer 에서 받기
axe restore --customer axe --tier ring --from realchoice --as-of 2026-05-20

# 3. 또는 cold SSD 마운트 + restore
axe restore --customer axe --tier cold --as-of 2026-05-20
```

### 시나리오 3 — 사일런트 corruption

`frame integrity-check --entity axec` 가 detect 하면:

```bash
# 가장 가까운 valid snapshot 으로 부분 복원
axe restore --customer axe --tier local --table journal_line --as-of &lt;last-valid&gt;
```

## Restore drill (자동)

분기마다 자동으로:

1. 임시 staging container 에 어제 backup 복원
2. `frame integrity-check` 통과 여부 확인
3. 결과를 운영자 Slack 으로 보고

drill 자체가 실패하면 cold SSD rotation 시도 또는 ring peer 복원.

## 함정 모음

| 함정 | 결과 | 회피 |
|---|---|---|
| Vault 에 cold storage password 저장 | closed loop, vault 손실 시 cold 도 못 풂 | 종이 메모 |
| restic password 분실 | 백업 영구 손실 | Keychain + 종이 이중화 |
| backup excludes 누락 (`.local/files`) | 핵심 데이터 백업 안 됨 | restic-excludes 명시 |
| `docker exec frame-postgres pg_dump` 만으로 신뢰 | container 죽으면 dump 못 함 | volume 자체 백업 병행 |
| ring backup 단방향 | 한쪽 손실 시 복구 불가 | bidirectional_ssh 검증 필수 |
| index-postgres 백업 누락 | `evidence_blob` = 죽은 딜 OneDrive/Blueprint 원본 삭제 후 **유일 사본** → 영구 소실 | `axe-backup` index 블록 (D-index-51) + `index export-evidence` round-trip drill |

---

<!-- PAGE https://docs.axelabs.ai/architecture/data -->

# 데이터 격리 모델

> schema-per-entity, customer 격리, audit_log, PII 암호화.

URL: https://docs.axelabs.ai/architecture/data

# 데이터 격리 모델

AXE Labs 는 **3-tier 데이터 격리**를 사용합니다:

| Tier | 격리 단위 | 구현 |
|---|---|---|
| 1. OS-level | customer | macmini 1대 = customer 1개 |
| 2. Database schema | entity (회사) | PostgreSQL schema-per-entity |
| 3. Row-level (일부) | tenant_id | RLS (magnet 등에서) |

## Tier 1 — OS-level (customer)

각 customer 는 자기 macmini 위에서 frame · blueprint 등 동일 스택을 실행합니다. customer 간 cross-talk 없음.

| customer | macmini | DB | schema 셋 |
|---|---|---|---|
| axe | `axe-macmini` | frame-postgres | shared + axec + axev + axtest |
| realchoice | `realchoice-macmini` (예정) | (별도) | shared + realchoice |

backup 도 macmini 별로 분리되며, customer 간 ring backup 은 **운영자 명시 승인 + 양방향 SSH 합의** 후에만.

## Tier 2 — Schema-per-entity (frame)

frame 의 PostgreSQL 안에는:

```
frame DB
├── shared (cross-entity)
│   ├── entity                ← 등록된 entity 메타 (axec, axev, realchoice)
│   ├── format_profile        ← 파일 포맷 캐시 (vendor + column_signature)
│   ├── account_template      ← 표준 계정과목 (KSME)
│   ├── idempotency_record    ← 멱등 키
│   └── oauth_authorization_codes  ← OAuth proxy (D-ops-15, 현재 dormant)
│
├── axec (개별 entity schema)
│   ├── account, journal, journal_line
│   ├── raw_transaction, bank_account, source_file
│   ├── fiscal_period, open_item
│   ├── evidence, audit_log
│   └── ... (전체 16 개 migration)
│
├── axev (axec 와 동일 구조)
│   └── ...
│
└── axtest (테스트 전용)
    └── ...
```

**Cross-entity 쿼리 불가**: 각 MCP tool 호출이 `SET search_path TO {entity_id}, shared` 로 격리. 사용자가 `axec` 권한만 가지면 `axev` schema 접근 불가.

### Migration 패턴

Alembic 의 dual-env:

| 디렉토리 | 적용 시점 | 대상 |
|---|---|---|
| `alembic/versions/` | `frame migrate` 시 1회 | `shared` schema |
| `alembic/entity_versions/` | `frame register-entity` 시 + 매 migrate | 각 entity schema (axec, axev, ...) |

`frame migrate` 실행 시:
1. `upgrade_shared()` → shared schema 마이그
2. 등록된 모든 entity 에 대해 `upgrade_entity(entity_id)` → entity schema 마이그

## Tier 3 — Row-level (선택적)

`magnet` 같이 multi-tenant 단일 schema 에서 RLS 사용:

```sql
-- magnet sql/050_multi_tenant_baseline.sql
ALTER TABLE campaign_metrics_daily ENABLE ROW LEVEL SECURITY;
CREATE POLICY tenant_isolation ON campaign_metrics_daily
  USING (tenant_id = current_setting('app.tenant_id')::bigint);
```

DB 연결 단계에서 `SET app.tenant_id = &lt;id&gt;` 주입. 사용자가 잘못된 tenant_id 로는 read/write 불가.

frame 은 schema-per-entity 가 더 강한 격리 (cross-schema 권한 자체 분리), magnet 은 RLS 가 멀티 brand 통합 운영에 더 적합 → 서비스 별 적절한 격리 모델 선택.

## audit_log — 모든 쓰기 추적

각 entity schema 에 `audit_log` 테이블이 있으며, **모든 쓰기 (insert/update/delete)** 가 자동 기록됩니다.

```sql
-- entity-side audit_log 의 컬럼
audit_log (
  id              bigserial,
  table_name      text,
  op              text,        -- INSERT | UPDATE | DELETE
  old_data        jsonb,
  new_data        jsonb,
  actor           text,        -- frame.actor session var
  entity_context  text,        -- 'axec'
  ts              timestamptz default now()
)
```

`frame.actor` 는 entity_session context manager 에서 설정되며, MCP tool 호출의 `TokenClaims.sub` 가 자동으로 들어갑니다.

### Append-only 강제

`raw_transaction`, `journal_line` 같은 핵심 테이블에는 DELETE/UPDATE 권한이 DB 사용자 단에서 REVOKE 되어 있습니다. 잘못된 분개는 `reverse_journal` 로 역분 (새 journal 생성), 절대 수정/삭제 안 함.

## PII 암호화 (pgcrypto)

개인정보 (security_holder, audit log 의 일부 raw_data) 는 `pgcrypto.pgp_sym_encrypt` 로 entity 별 별도 passphrase 로 암호화됩니다.

```yaml
# docker-compose.yml env
FRAME_PII_PASSPHRASE_AXEC: ${FRAME_PII_PASSPHRASE_AXEC:-}
FRAME_PII_PASSPHRASE_AXEV: ${FRAME_PII_PASSPHRASE_AXEV:-}
FRAME_PII_PASSPHRASE_REALCHOICE: ${FRAME_PII_PASSPHRASE_REALCHOICE:-}
FRAME_PII_SALT_DIR: /root/.frame
```

각 entity 의 passphrase 는 운영자 Keychain (`security add-generic-password`) 에 저장되고 컨테이너 launch wrapper 가 env 로 주입. **passphrase 분실 = PII 영구 손실** (이는 의도된 설계 — 운영자가 DB dump 만으로는 PII 복원 불가).

## Evidence blob 저장 (content-addressed file store, D-frame-2)

큰 파일 (evidence PDF·통장 xls·세금계산서 등) 은 Postgres bytea 가 아니라 **content-addressed file store** `.local/files/<hash[:2]>/<hash>/<filename>` 에 저장. DB 의 `evidence`/`source_file` row 는 `content_hash` (SHA-256) + **portable** `storage_url` (relative `<hash[:2]>/<hash>/<filename>`) 만 보유.

- **컨테이너 마운트**: host `.local/files` ↔ 컨테이너 `/app/.local/files` bind mount (`FRAME_FILE_STORAGE_PATH`). read 시 `frame.ingest.pipeline.resolve_storage_path()` 가 portable url 을 live store 기준 absolute 로 매핑 → host·컨테이너 어디서 실행해도 같은 blob 해석.
- **금지**: `local://<host 절대경로>` (외부 OneDrive/Downloads 포인터 — 컨테이너 read 불가 + rename/move 시 깨짐), CWD 의존 absolute 경로 (host `/Users/...` vs 컨테이너 `/app/...` 불일치). 모든 ingest write-path (`pipeline`/`card`/`fund`/`hometax`/`entity_meta`/`resolution`/`ops.evidence`) 가 `_store_file_locally` 로 통일.
- **무결성 probe**: `GET /frame/health/storage` 가 모든 entity schema 의 evidence storage_url 을 resolve 해 blob 존재 확인 — bind-mount 회귀로 blob 이 사라지면 (2026-05-14 incident) 503 + missing-list. blob 은 절대 삭제 안 함 (append-only 정신).

## 정합성 검사

`frame integrity-check --entity axec` 가 4가지 검사를 수행:

1. **balance** — `SUM(debit) == SUM(credit)` per journal
2. **journal** — 모든 journal_line 이 valid account 참조
3. **account** — chart-of-accounts 와 journal_line 의 일관성
4. **fiscal_period** — period 의 starting/ending balance 정합

cron 으로 매일 자동 실행 + Slack alert.

---

<!-- PAGE https://docs.axelabs.ai/architecture/deploy -->

# 배포 · 무중단

> blue/green frame swap, axe-frame-proxy, axe CLI deploy.

URL: https://docs.axelabs.ai/architecture/deploy

# 배포 · 무중단

## Blue/green 패턴 (frame)

frame 은 **두 개의 컨테이너가 항상 동시 실행**됩니다 — blue (3710) + green (3711). 한쪽이 active, 다른 한쪽이 passive.

```
              ┌──── frame-mcp-blue   :3710  ◀ alias `frame-mcp` (active)
              │
axe-frame-proxy ─── (Caddy upstream)
   :3712      │
              └──── frame-mcp-green  :3711       (passive, 새 코드 받는 곳)
```

배포 시퀀스:

```
1. green container 에 새 코드 build + start
2. green 헬스체크 통과 대기 (poll /health/ready)
3. docker network alias `frame-mcp` 를 green 으로 이동
4. axe-frame-proxy 가 upstream 자동 reload (Caddy graceful)
5. blue 의 in-flight 요청 완료 대기 (60s grace)
6. blue stop → 다음 배포 시점에 새 코드로 build
```

다운타임: **0 초**. 한 시점에 < 1s 의 latency spike 는 수용.

## axe CLI deploy

운영자 머신에서:

```bash
# dry-run (변경사항 미리 표시)
axe deploy frame axe

# 적용
axe deploy frame axe --apply
```

`axe deploy frame {customer}` 가 위 6 step 을 자동 실행. 진행 상황은 stderr 에 step 별 로그.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `docker compose up --build` (다운타임) | 30-60s 다운타임 | `axe deploy` 사용 |
| `docker compose restart` (코드 미변경 시) | 다운타임 + env 재로딩 X | 코드 변경 → `axe deploy` |
| cloudflared 의 SIGHUP | process 죽음 | host-side proxy 뒤로 분리 |
| blue/green 컨테이너 이름을 cloudflared 에 직접 명시 | swap 불가 | docker network alias 사용 |
| `--no-build` 잊고 deploy | 새 코드 적용 안 됨 | `axe deploy` 가 자동 처리 |

## docker-compose 구조

`/Users/axe/frame/docker-compose.yml`:

```yaml
services:
  postgres:
    image: postgres:16-alpine
    container_name: frame-postgres
    ports: ["3700:5432"]

  frame-mcp-blue: &frame-mcp-blue
    build: . (Dockerfile)
    container_name: frame-mcp-blue
    ports: ["3710:3710"]
    environment:
      FRAME_DEPLOY_COLOR: blue
      FRAME_MCP_PORT: 3710
      AZURE_FRAME_MCP_CLIENT_SECRET: ${AZURE_FRAME_MCP_CLIENT_SECRET:-}
      # ... 기타 env
    networks:
      default:
        aliases: [frame-mcp]    # initial: blue active
      artemis_default:
        aliases: [frame-mcp]

  frame-mcp-green:
    <<: *frame-mcp-blue          # YAML anchor 로 동일 설정 상속
    container_name: frame-mcp-green
    ports: ["3711:3710"]
    environment:
      FRAME_DEPLOY_COLOR: green
      # ... 동일하지만 color=green
    networks:
      default: {}                # green 은 alias 없음 (passive)
      artemis_default: {}
```

## 무엇이 다운타임 0 을 가능케 하는가

1. **컨테이너 1대 만 build 중** — 다른 1대가 traffic 흡수
2. **docker network alias** 가 instant DNS 갱신 (DNS TTL 없음, in-memory)
3. **axe-frame-proxy 의 Caddy** 가 upstream 변경에 graceful (SIGHUP)
4. **cloudflared 가 build 와 무관** — 평소 라우팅 유지

## 다른 서비스 — blueprint

blueprint 은 단일 컨테이너 (현재). Next.js dev/build 시간이 짧고 (수십 초), 사용자 traffic 이 frame 만큼 critical 하지 않아 단순 deploy 사용:

```bash
cd /Users/axe/blueprint && pnpm build && pnpm start
# (launchd 또는 docker compose restart)
```

다운타임 발생 시 사용자가 보는 것은 "Connecting..." 메시지 수 초. 회계 작업과 같은 in-flight transaction 없음.

향후 blueprint 도 blue/green 으로 전환 예정 (D-config-13 패턴 확장).

---

<!-- PAGE https://docs.axelabs.ai/architecture/domains -->

# 도메인 · DNS

> Cloudflare zone, 1-level subdomain 결정, customer 도메인 매핑.

URL: https://docs.axelabs.ai/architecture/domains

# 도메인 · DNS

## 두 개의 zone

| Zone | 용도 | 상태 |
|---|---|---|
| `axelabs.ai` | **플랫폼** (이 docs, 모든 customer 서비스) | 2026-05-14 등록 |
| `axellc.com` | **corporate** (회사 이메일, 기업 홈페이지) | 기존 |

플랫폼 트래픽은 `axelabs.ai` 만 거치고, `axellc.com` 은 corporate 용도로 분리됩니다.

## URL 컨벤션

```
{customer}.axelabs.ai            ← apex, blueprint
{customer}.axelabs.ai/frame      ← frame MCP
{customer}.axelabs.ai/frame/mcp  ← MCP endpoint (canonical resource URI)
{customer}.axelabs.ai/vault      ← Vaultwarden
{customer}.axelabs.ai/index      ← (예정)

admin.axelabs.ai                 ← 운영자 콘솔 (Microsoft SSO)
docs.axelabs.ai                  ← 본 docs
```

## 왜 1-level subdomain + path?

선택지 비교:

| 옵션 | SSL | URL 모양 | 운영 부담 |
|---|---|---|---|
| 1-level + path | ✓ 무료 (Cloudflare Universal SSL) | `axe.axelabs.ai/frame` | cloudflared path-aware 라우팅 |
| 2-level subdomain | ❌ 유료 ($10/cert/월) | `frame.axe.axelabs.ai` | 일관 wildcard 필요 |
| Service-only domain | △ | `frame.axelabs.ai` | customer 격리 불가 |

→ 1-level + path 채택. cloudflared ingress 의 `path` 매칭으로 service 분기.

## 함정 — Universal SSL wildcard 의 1-level 한계 (D-ops-39)

무료 Universal SSL 의 wildcard cert (`*.axelabs.ai`) 는 **1단 서브도메인만 cover**. 2단 (e.g. `ssh.axe.axelabs.ai`, `<x>.axe.axelabs.ai`) 은 cert SAN 미일치 → edge 가 default cert 로 fallback → 클라이언트에서 `tls: handshake failure` / `SEC_E_ILLEGAL_MESSAGE` / `sslv3 alert handshake failure`.

**규칙**: HTTPS 노출되는 모든 hostname 은 `{name}.axelabs.ai` 의 **1단** 이어야 함. service 또는 sub-context 가 필요하면:

- ✅ **flat hostname** — `ssh-axe.axelabs.ai`, `docs-axe.axelabs.ai`
- ✅ **path under apex** — `axe.axelabs.ai/frame`
- ❌ **2단 subdomain** — `ssh.axe.axelabs.ai`, `frame.axe.axelabs.ai`

**증상이 보이면**: 클라이언트의 `cloudflared --version` 이 최신이고 시간 동기화도 정상인데 handshake failure 가 모든 클라이언트에서 일관되면 서버측 cert 문제. zone DNS records 에서 hostname dot count 확인. 함정 사례 → [/ops/known-gaps#cloudflare-universal-ssl-1-level](/ops/known-gaps#cloudflare-universal-ssl-1-level).

**유료 회피 옵션 평가**: Advanced Certificate Manager ($10/cert/월) 또는 zone delegation (`axe.axelabs.ai` 별도 zone) 모두 미채택. 무료 plan + flat-hostname 으로 충분.

## 현재 customer 별 할당

| customer | apex 도메인 | corporate 도메인 (이메일) |
|---|---|---|
| axe | `axe.axelabs.ai` | `axellc.com` |
| realchoice | `realchoice.axelabs.ai` | `realchoice.co.kr` |

## DNS records

axelabs.ai zone (Cloudflare):

```
CNAME  axe              <tunnel-id>.cfargotunnel.com   ; orange-cloud ON (axelabs tunnel)
CNAME  realchoice       <tunnel-id>.cfargotunnel.com   ; orange-cloud ON (realchoice tunnel)
CNAME  admin            <tunnel-id>.cfargotunnel.com   ; orange-cloud ON
CNAME  docs             <tunnel-id>.cfargotunnel.com   ; orange-cloud ON
CNAME  ssh-axe          <tunnel-id>.cfargotunnel.com   ; orange-cloud ON (operator SSH)
CNAME  www              axelabs.ai
TXT    axe              "MS=ms10433167"                ; Microsoft Entra domain verify
```

> `ssh-axe.axelabs.ai` 는 운영자/엔지니어가 macmini 에 SSH 진입하기 위한 Cloudflare Access 보호 endpoint. 클라이언트는 `cloudflared access ssh --hostname ssh-axe.axelabs.ai ...` 또는 `ssh user@ssh-axe.axelabs.ai` (ProxyCommand 설정 시).
> 이전 hostname `ssh.axe.axelabs.ai` 는 [위 함정](#함정--universal-ssl-wildcard-의-1-level-한계-d-ops-39) 으로 폐기 (D-ops-39, 2026-05-26). DNS record 와 `*.axe.axelabs.ai` 와일드카드 는 backlog 에서 일괄 정리.

Microsoft 도메인 검증 TXT 는 Application ID URI 에 `https://axe.axelabs.ai/frame/mcp` 같은 형식을 등록하기 위해 필요. 자세히는 [인증 · 권한](/architecture/auth#azure-app-id-uri).

## Customer 추가 시

1. `customers.yaml` 에 새 entry (예: `realchoice`)
2. Cloudflare zone 에 `A {customer}` record 추가 (proxy ON)
3. cloudflared config 에 ingress 규칙 추가
4. cloudflared 재시작 (1회만, ingress 안정 후 추가 변경 없음)

상세 절차는 [신규 customer onboarding](/ops/runbook/customer-onboarding).

---

<!-- PAGE https://docs.axelabs.ai/architecture/governance -->

# 결정 거버넌스 — gate (결재 + e-sign + 법무)

> gate 서비스의 결정→실행 거버넌스 아키텍처. record≠process, 서명 1-primitive, actuation ledger, Blueprint mirror, 그리고 narrowed Phase-1(gate-native 직접-build 암호 e-sign[CAdES-T]·내부검색·AXE-internal) vs Phase-2(외부 본인확인기관·flywheel·공개 SaaS·결제·멀티테넌트) 경계.

URL: https://docs.axelabs.ai/architecture/governance

# 결정 거버넌스 — gate

gate 는 한국형 **내부 전자결재 + e-sign + HTML 문서 + 법무검색**을 하나의 **AI-driven 결정→실행 파이프라인**으로 묶는 신규 **Rust + Postgres** 서비스다. [para-os §7](/architecture/para-os)(결정로그 ≠ 결재워크플로)의 물질화 — 성숙한 거버넌스 Area 가 독립 서비스로 졸업한 형태.

> 본 페이지 = gate **거버넌스 아키텍처 설계** (착수 직전 설계 + e-sign 엔진 빌트, 2026-06-07). 결정 SSOT = [D-gate-1](/ops/decisions)(scope·Phase) · [D-gate-2](/ops/decisions)(record SoR) · [D-gate-3](/ops/decisions)(actuation·e-sign 경계, e-sign 부분 D-gate-5 가 supersede) · [D-gate-4](/ops/decisions)(법무) · **[D-gate-5](/ops/decisions)(e-sign 직접구현 = 암호등급 자체 서명엔진, 빌트+검증 — D-gate-3 integrator 입장 supersede)**. 마스터플랜·착수 큐 = [B-bp-decision-pipeline-esign](/ops/backlog) (service=gate, roadmap M9). 설계 전모·리서치 결론은 gate machine 메모리 2파일.

## 1. Phase 경계 — narrowed Phase-1 (경로 A)

7라운드 설계 후 7-agent red-team 이 **풀설계**(결재 + 직접 e-sign + 법무 RAG flywheel + 공개 SaaS + 결제 + 멀티테넌트 = 1인이 동시에 짓는 6~7 규제제품)에 **NO-GO**(11 P0 / 16 P1 / 8 누락) 판정했다. 결정적 사실 — **11 P0 가 전부 "야심 5종"에 거주**한다. 따라서 narrowed Phase-1 은 대부분의 P0 를 *해소가 아니라 defer 로* 회피한다 ([D-gate-1](/ops/decisions)).

> **단, e-sign 은 예외 (2026-06-07 [D-gate-5](/ops/decisions))**: 운영자가 *"모두싸인의 기능을 직접, 암호등급으로 구현"* 지시 → e-sign 은 defer 가 아니라 **직접-build 로 빌트**됐다 (§6). red-team 이 직접-build 를 막았던 P0(HSM·HTML→PDF 결정성·custody)는 이제 **해소-또는-명시**: 결정성 = canonical decision bytes 로 *지금*(typst PDF render 는 later), HSM = trait abstraction *ready*(dev = software key), custody = `esign_seal` append-only + RFC3161 TSA. **진짜 잔여 Phase-2 = 외부 서명자 본인확인기관**(정보통신망법 §23-3, 자가구축 불가) — 그 외 직접 e-sign P0 는 닫혔다.

| 영역 | **Phase-1 (확정·착수 가능)** | **Phase-2+ (각자 게이트, defer)** |
|---|---|---|
| 결정로그 | gate `decision` SoR (record≠process) | — |
| 결재워크플로 | 기안→DOA→승인/반려/보류→시행 상태기계 | — |
| 문서 | HTML spine → PDF 렌더 | — |
| e-sign | **gate-native 직접-build 암호 서명엔진** (CAdES-T server-seal + RFC3161 + esign_seal evidence + verify_seal; 모두싸인 = optional alt provider) — [D-gate-5](/ops/decisions) | 외부 서명자 **본인확인기관** 통합(정보통신망법 §23-3) · *하드닝*: HSM·PAdES 서명-PDF·prod-key |
| 실행 | actuation ledger (멱등 + reconcile) | saga 보상 (e-sign+결제+분개) |
| 가로 거버넌스 | Blueprint `gate.decision` citation mirror | visibility-gated mirror 테이블 |
| 배포 대상 | **AXE-internal only** (realchoice/Truvia table-stakes) | 공개 SaaS (+tenant_id RLS·self-IdP) |
| 법무 | **pgvector-KR 내부검색만** (결재 자동주입 X) | Pinecone+Cohere+Gemini flywheel (+PIPA 자문) |
| 결제 | 없음 | 포트원/토스/Paddle (+전자금융/전자상거래) |
| 테넌시 | 없음 (owner_id RLS) | cross-tenant 축적 (+PIPA 가명정보) |

빌드게이트(코드보다 먼저) = [B-gate-bonin-id-contract](/ops/backlog)(본인확인기관 계약, 수주~수개월) · [B-gate-legal-counsel](/ops/backlog)(변호사법 §109 + PIPA 의견서) · [B-gate-phase2-gates](/ops/backlog).

## 2. record ≠ process — SoR = gate, Blueprint = mirror

- **결정 로그 (record)** — 무엇이·누가·언제·무슨 권한으로·뭘 근거로 결정됐나. append-only, 불변(수정 아닌 **supersede**). **SoR = gate `decision` 테이블** (서비스가 SoR 소유, [D-gate-2](/ops/decisions)).
- **결재 워크플로 (process)** — 기안 → 결재선(DOA) → 승인/반려/보류 → 시행. 그 위 policy-driven·agent-assisted 레이어. 워크플로 완료 → 결정로그 한 줄 방출.

**왜 gate 가 SoR 인가**: round-1 은 결정로그를 *Blueprint core primitive(가로)* 로 뒀으나 = AXE-internal 전제. standalone 외부제품 요구가 refine — record 의 집을 gate 로 옮겼다. 근거(grounded): [/architecture/artifacts](/architecture/artifacts) "MCP backend = sole owner, data 중복 0" · [/architecture/data](/architecture/data) "cross-service = 직접 DB read 금지, 명시적 신호채널(pg_notify/outbox)만" · [D-cortex-9](/ops/decisions) = service-owns-SoR + Blueprint visibility-gated mirror 가 이미 빌트(template 기성). Blueprint = `gate.decision` citation mirror(optional consumer 1종, 외부고객 = OFF, gate 단독 완결).

## 3. 핵심 테이블 (Blueprint-agnostic)

| 테이블 | 역할 |
|---|---|
| `document` | **HTML 작성 스파인**(풍성한 포맷) + 변수(AI/템플릿 fill) + rendered_pdf_ref(서명용) + version + kind(기안/계약/통지). 내부결재 + e-sign = 같은 document 의 두 phase. |
| `workflow` | 내부결재 상태기계: draft→상신→in_review(결재선 step)→승인/반려/보류→시행→done. |
| `approval_step` | 결재선 (kind: 승인/전결/협조/합의/대결 · state: pending/approved/rejected/held/skipped). **반려·철회·서명거절 역흐름 = 1급 시민**(red-team 누락 #8). |
| `doa_policy` | 전결규정 (entity · decision_type · amount_min/max → line jsonb). |
| `signature` | 내부+외부 서명 통합 primitive (provider ∈ `{internal, gate, modusign}` · signers · envelope_id · cert_ref · status). §4. |
| `esign_seal` | **암호 봉인 evidence** (append-only, 전자문서법 §5 custodian) — decision_id · sealed_bytes_hash · **CMS/CAdES-T DER**(detached 서명 + RFC3161 토큰) · signer_cert_ref · tsa_url · sealed_at. 시행 시 `esign.gate` actuator 가 1행 append, `verify_seal` 가 읽음. §4·§6. |
| `actuation` | 실행 ledger (actuator_kind · payload · idempotency_key · state · result_ref · reconciled_at). §5. |
| `event` | append-only audit. |
| `decision` | gate SoR terminal record (authority · actor · decided_at · basis citations · supersedes). canonical bytes = `esign_seal` 봉인 대상. |

## 4. 서명 = 한 primitive

내부 sign-off = 외부 e-sign = 같은 primitive `signature`. 누가·법적무게만 다르다. `provider ∈ {internal, gate, modusign}`:

- **`internal`** — 결재선 step 의 인증된 결재 승인 (UI sign-off). gate identity = 실지명의.
- **`gate`** (Phase-1, [D-gate-5](/ops/decisions)) — **gate-native 암호 봉인**. 시행 시 승인된 결정의 canonical bytes 를 단일 서버 서명 identity 로 **CAdES-T server-seal** → `esign_seal` 에 evidence 저장. 봉인 1건 = `signature(provider=gate)` + `esign_seal` 1행. §6.
- **`modusign`** (optional alt provider) — 외부 카운터파티 라운드트립이 필요할 때의 대체 경로 (`esign.send`/EsignStub). Phase-1 의 *대안*이지 기본 아님.

내부 결재 승인도, gate 서버 봉인도, 외부 모두싸인 e-sign 도 "행위자가 결정을 시점에 (법적으로) 확정"하는 한 종류의 행위 — [para-os §84](/architecture/para-os) 와 정합.

## 5. actuation ledger + reconcile (분산 일관성)

승인된 결정 → **actuator 호출** (`frame.post_journal` / `index.register_deal` 등; Area 서비스 = 결정 파이프라인의 actuator). 결정→실행은 분산 트랜잭션이므로:

- `actuation.idempotency_key = uuidv5(workflow + seq + actuator + payload_hash)` — gate 측 재시도 멱등.
- **reconcile 워커** (frame-worker 패턴, pg_notify) — inflight→done/failed 정합.
- ⚠️ **gate idempotency_key 는 *외부* 이중실행을 못 막는다** (red-team P0 #5) — `esign.gate` 봉인은 gate 내부 actuator라 `esign_seal`(decision_id 유일) append 가 멱등이지만, *외부* provider 경로(모두싸인 alt) 는 **provider-side idempotency 토큰** 필요. saga 보상(e-sign+결제+분개)은 결제 도입 Phase-2.

## 6. e-sign 경계 — Phase-1 = gate-native 직접-build 암호 서명엔진

> **2026-06-07 pivot ([D-gate-5](/ops/decisions), [D-gate-3](/ops/decisions) e-sign 경계 supersede)**: [D-gate-3](/ops/decisions) 은 e-sign 을 모두싸인 integrator 로 두고 직접-build 를 Phase-2 로 defer 했으나, 운영자가 *"모두싸인의 기능을 직접, 암호등급으로 구현"* 지시 → **Phase-1 이 직접-build 엔진**이다. 빌트+검증 완료 (이 세션).

**Phase-1 = BUILD (직접 구현, 작동·검증됨)** — gate 가 자체 암호 서명엔진을 갖는다 ([para-os §84](/architecture/para-os) 와 정합: gate = 결정 파이프라인의 actuator, 봉인은 `esign.gate` actuator):

- **① CMS/PKCS#7 CAdES-BES detached 서명** (RSA-2048 + SHA-256). `DocumentSigner` trait(**HSM-ready** abstraction) + `SoftwareSigner`(self-signed X.509). 적대적 리뷰(위조 도달경로 없음) + **openssl 양방향 interop**, 7 tests.
- **② RFC3161 신뢰 타임스탬프 → CAdES-T** (hand-rolled ASN.1, 단일 clean dep line). default = DigiCert RSA TSA; 한국 prod = **Koscom/CrossCert** config-swap. 9 tests + live round-trip.
- **⑤ 워크플로 배선**: **시행(execute)** 시 `esign.gate` actuator 가 승인된 결정을 **server-seal** — canonical decision bytes → CAdES-T → append-only **`esign_seal`** evidence 테이블 저장 (**전자문서법 §5 custodian**). 신규 **`verify_seal` MCP tool** = 서명 + 무결성 + 타임스탬프 검증. e2e: 결재→seal→verify valid · 저장 CMS openssl cross-verify 통과 · DB tamper→integrity fail.

**법적 근거 — 전자서명법 (2020, 공인 폐지)**: 사서명(private/internal e-sign)은 **실지명의 + 서명의사**면 유효, 운영 라이선스 불요. gate 매핑 = **실지명의 = 인증된 gate identity**(내부 서명자) · **서명의사 = 결재 승인 행위**. → 내부/사내 e-sign 은 본 엔진으로 **합법 완결**.

**모두싸인 = optional alternative provider** (기본 아님): 외부 카운터파티 라운드트립이 필요할 때 `signature.provider=modusign` 경로 (`esign.send`/EsignStub) 가 여전히 존재. gate-native 봉인이 Phase-1 기본, 모두싸인은 *대안*.

**잔여 하드닝 / Phase-2**:
- **외부 서명자 본인확인 = 진짜 Phase-2** — 방통위 지정 **본인확인기관** 통합([B-gate-bonin-id-contract](/ops/backlog), 정보통신망법 §23-3 자가구축 불가). 내부 서명자는 gate auth = 실지명의라 불요; 외부 신원 강증명만 게이트.
- **HSM** (cryptoki/PKCS#11) — `DocumentSigner` trait 가 이미 **abstraction-ready**, dev 는 software key. prod = HSM-backed `DocumentSigner` 구현 + **서명키 DR/escrow**(분실 = 전 과거서명 검증불가).
- **PAdES 서명-PDF 컨테이너** (③④) — typst **deterministic render** + pyHanko PAdES. 현재 봉인 대상 = decision canonical bytes(결정적); 사람이 읽는 sealed-PDF 는 later.
- **production 키관리** — dev 는 ephemeral key. prod = 영속 서버 서명 identity + 회전·백업.

**MUST NOT (Phase 무관, 불변)**: 자체 CA · per-user cert · 자체 TSA · "공인/인증" 주장. gate 는 **단일 서버 서명 identity** 로 봉인한다 (per-user cert 발급 없음) — 이것이 **ModuSign-recipe 모델**(provider 가 서버 서명으로 봉인, 사용자별 인증서 없이). 자체 TSA 도 안 만든다 — 외부 RFC3161 TSA(DigiCert/Koscom/CrossCert)에 위임.

**환경 변수** (signing identity + TSA): `GATE_ESIGN_KEY_PEM` / `GATE_ESIGN_CERT_PEM` (서버 서명 키·인증서 PEM, 또는 `GATE_ESIGN_KEY_DIR` 로 디렉터리 지정) · `GATE_TSA_URL` (RFC3161 TSA 엔드포인트, default DigiCert / 한국 prod Koscom·CrossCert). prod 의 `GATE_ESIGN_KEY_PEM` = **비밀** → `customers.yaml services.gate.secrets[]` 에 등재(blueprint OIDC 서명키 `blueprint/axe/oidc-signing-key` 패턴, [/architecture/secrets](/architecture/secrets)).

## 7. 법무 모듈 가드레일

gate 법무모듈 = **검색·요약·번역·템플릿(로폼: user-blank, 기계적)만** ([D-gate-4](/ops/decisions)).

**하드룰 — 변호사법 §109(형사)·§34(5)**: 법률상담/사안별 자문/대리/결과예측-as-advice **금지**. **공개 "AI 법률상담" 금지**(AI대륙아주 7개월 폐쇄·징계 선례). 변호사 노출 시 정액광고만(로톡 모델 — 알선료/성공보수/광고수익배분 금지). 모든 출력 "**법률 정보, 자문 아님**" disclaimer. cite = **retrieval-verified**(존재 + 시행일/선고일 temporal 강제). **결재 자동주입 차단** — AI 기안이 법령/판례를 auto-approve 경로에 주입하지 않음(red-team P0 #2).

**Phase-1 data**: 국가법령정보 OPEN API(open.law.go.kr, 이용제한없음·무료) + data.go.kr 판례(상용 OK) + HF `korean_law_open_data_precedents`(openrail). 대법원/헌재 + 법령 grade(하급심 = 엘박스/케이스노트 상용 walled 라 제외). SoR = gate Postgres, index = **pgvector-KR**(Pinecone 아님). `lbox_open`/`kcl` = CC BY-NC = 유료제품 금지.

**Phase-2 gate**: Pinecone + Cohere rerank + Gemini embed flywheel(LLM비용 사용자부과·DB 복리) + cross-tenant 축적 = **PIPA 처리근거·가명정보·국외이전(§28-8) 자문**([B-gate-legal-counsel](/ops/backlog)) 선결. B2B/internal-use 유지 = 최저위험.

## 8. 규제 경계 요약

| 법령 | 무엇을 강제하나 | Phase |
|---|---|---|
| 전자서명법 (2020, 공인폐지) | 사서명도 실지명의 + 서명의사면 유효 — 직접구현 합법, 운영 라이선스 불요. gate: 실지명의 = gate auth · 서명의사 = 결재 승인 | **Phase-1** (직접 e-sign 빌트, [D-gate-5](/ops/decisions)) |
| 전자문서법 §5 | 서명문서 + 메타 무결성 보관 (gate = evidence custodian via `esign_seal` append-only + RFC3161 TSA) | **Phase-1** (gate-native 봉인) |
| 정보통신망법 §23-3 | 본인확인 자가구축 불가 → 방통위 지정 본인확인기관 통합 필수 | Phase-2 (**외부 서명자 신원** 한정; 내부 서명자는 gate auth = 실지명의라 불요) |
| 변호사법 §109/§34 | 법률사무 무면허 금지 — 검색·정보 한정, 자문/대리/auto-주입 금지 | **Phase-1** (법무 활성 시) |
| 개인정보보호법 (PIPA) | cross-tenant 축적·국외이전·CI/DI = 처리근거·가명정보·DPIA | Phase-2 (flywheel/SaaS 전제) |
| 전자상거래법 (2025 개정) | 정기결제 명시동의·셀프해지·사전고지·다크패턴 금지 | Phase-2 (결제 전제) |

대법원 2017도13263(해시 무결성 → 서명시점 해시 + custody chain) · 민사소송법 §358(실제 서명행위 → 진정성립)이 증거능력 타깃. 제외문서 = 유언·부동산등기·공정증서·일부보증(민법 §428-2).

## 9. Phase-2 게이트 (deferred)

각 야심은 자기 P0/규제 게이트를 동반한다 ([B-gate-phase2-gates](/ops/backlog)):

1. **e-sign — 엔진은 Phase-1 빌트 ([D-gate-5](/ops/decisions)), 잔여만 Phase-2/하드닝**: (Phase-2) 외부 서명자 **본인확인기관** 통합(정보통신망법 §23-3) · (하드닝) HSM/KMS `DocumentSigner`(trait ready) + 서명키 DR/escrow · PAdES 서명-PDF(typst deterministic render + pyHanko) · production 키관리. *닫힌 항목*: 자체 PKI 서버서명·CAdES-T·RFC3161 타임스탬프·custody(`esign_seal`)·canonical-bytes 결정성·para-os §84 재결정 = §6 참조.
2. **Pinecone 법무 flywheel** — PIPA 자문 · 비식별/가명정보 · namespace 테넌트격리 · PII 임베딩 전 제거 코드강제.
3. **공개 SaaS** — tenant_id RLS substrate(owner_id RLS 재설계, red-team P0 #8) · self-IdP tenant바인딩/iss/aud/per-tenant 시크릿/MFA(P0 #9) · rate-limit·abuse · 서브도메인 격리.
4. **결제** — 전자금융/전자상거래법(동의·셀프해지·사전고지·다크패턴) · LLM 미터링 과금 · Paddle MoR 영세율. (Stripe = 한국법인 불가.)
5. **cross-tenant 축적** — PIPA 근거 확정 후.

## 10. 착수 순서

docs-first(본 페이지 + D-gate-1~5) → `cp -R cortex gate` scaffold(auth 3-branch ladder[HS256 / Blueprint OIDC / Entra] · `gate_app` NOSUPERUSER + `gate.actor` GUC RLS · append-only audit · blue/green caddy 상속, index 도메인 미상속) → 포트 41xx 배선(pg4100 / blue4110 / green4111 / proxy4112) → 7테이블 migration(6 + `esign_seal`) → 상태기계 → **`esign.gate` actuator**(gate-native CAdES-T server-seal + `esign_seal` + `verify_seal`, [D-gate-5](/ops/decisions) — 빌트) + 모두싸인 alt-provider actuator(Actuator trait + EsignStub → 모두싸인 sandbox, optional) → `customers.yaml services.gate.secrets[]`(+ `GATE_ESIGN_KEY_PEM` 서명키) · cloudflared · pre-push guard.

## 관련

- [/architecture/para-os](/architecture/para-os) §7 — 결정로그 ≠ 결재워크플로 (본 페이지의 상위 철학)
- [/architecture/artifacts](/architecture/artifacts) — Artifact · Citation 저장/스키마 (Blueprint mirror 토대)
- [/architecture/data](/architecture/data) — 데이터 격리 · cross-service 신호채널 규율
- [D-gate-1](/ops/decisions) · [D-gate-2](/ops/decisions) · [D-gate-3](/ops/decisions) · [D-gate-4](/ops/decisions) · [D-gate-5](/ops/decisions)(e-sign 직접구현) — 본 페이지의 결정 등재
- [B-bp-decision-pipeline-esign](/ops/backlog) — 마스터플랜 + 착수 큐 (service=gate, M9)

---

<!-- PAGE https://docs.axelabs.ai/architecture/mcp-server-checklist -->

# MCP 서버 개발 체크리스트

> frame / hive / blueprint 누적 lesson — 양파껍질 5층 + Azure manifest 9 항목 + 운영 21 항목 (skill-integration 5 포함).

URL: https://docs.axelabs.ai/architecture/mcp-server-checklist

# MCP 서버 개발 체크리스트

claude.ai Custom Connector + Claude Code 가 받는 표준 MCP 서버를 추가할 때, **frame · hive 가 검증한 byte-by-byte 패턴을 1:1 으로 복사**해야 한다. 비슷하게 만들면 5층 양파껍질이 차례로 폭로된다 (Blueprint 2026-05-21 실제 사고).

> **핵심 원칙**: 새 MCP 서버는 `cp -R /Users/axe/frame/src/frame /tmp/...` 부터 시작하라. "유사하게" 가 아니라 "diff 가 없을 때까지". 단 4 단어 (`audience=[client_id, app_id_uri]`) 빠뜨려도 OAuth 통과 후 401 무한루프.

---

## 0. 가기 전 — 결정 (D-bp-mcp-1, 2026-05-21)

| 결정 | 이유 |
|---|---|
| **Python + FastMCP + Starlette + uvicorn** 으로 통일 | claude.ai 의 Streamable HTTP 가 frame 의 wire-level response 만 수용. Node port 시도 (visible response 동일) 도 silent reject. |
| DB 는 **기존 Prisma/Drizzle/SQLAlchemy schema 를 raw SQL 로 read-only access** | 별도 schema 필요 없음. SQLAlchemy `text("SELECT ... FROM \"User\" WHERE ...")` 패턴. |
| **OAuth Resource Server (RP)** 직접 — 자체 AS 구축 금지 | D-ops-15 dead-end: claude.ai 는 외부 AS 의 PKCE 우회 못함. 무조건 Microsoft Entra ID 직결. |
| **standalone 컨테이너** — main service 컨테이너에 mount X | claude.ai connector probe 가 Next.js 의 `vary: rsc, ...` auto-header 거부. 최소 header 의 standalone Python 필요. |

---

## 1. Azure Entra ID app registration — 9 항목

`az ad app create` 한 줄로 끝나지 않는다. 각 항목 확인.

```bash
# 1. app + sp 동시 생성
az ad app create --display-name "Blueprint MCP" --sign-in-audience AzureADMyOrg
az ad sp create --id APP_ID   # ← 명시적 SP 생성, 자동 생성 안 됨

# 2. identifierUris (= App ID URI)
az ad app update --id APP_ID --identifier-uris "https://axe.axelabs.ai/blueprint/mcp"

# 3. accessTokenAcceptedVersion = 2 (v2 endpoint 가 표준)
az rest --method PATCH --uri "https://graph.microsoft.com/v1.0/applications/OBJECT_ID" \
  --body '{"api":{"requestedAccessTokenVersion":2}}'

# 4. oauth2PermissionScopes (delegated permission)
az rest --method PATCH ... --body '{
  "api": {"oauth2PermissionScopes":[{
    "id":"RANDOM_UUID",
    "value":"mcp.access",
    "type":"User",
    "isEnabled":true,
    "adminConsentDisplayName":"Access Blueprint MCP",
    "userConsentDisplayName":"Access Blueprint MCP"
  }]}
}'

# 5. redirectUris (claude.ai 의 양쪽 도메인)
az rest --method PATCH ... --body '{"web":{"redirectUris":[
  "https://claude.ai/api/mcp/auth_callback",
  "https://claude.com/api/mcp/auth_callback"
]}}'

# 6. requiredResourceAccess (Microsoft Graph User.Read — id_token 의 email claim 발급)
az rest --method PATCH ... --body '{"requiredResourceAccess":[{
  "resourceAppId":"00000003-0000-0000-c000-000000000000",
  "resourceAccess":[{"id":"e1fe6dd8-ba31-4d61-89e7-88639da4683d","type":"Scope"}]
}]}'

# 7. implicitGrantSettings.enableIdTokenIssuance = true
az rest --method PATCH ... --body '{"web":{"implicitGrantSettings":{"enableIdTokenIssuance":true}}}'

# 8. client_secret 생성 + vault push (stderr 분리 필수)
az ad app credential reset --id APP_ID --years 2 --query password -o tsv 2>/dev/null \
  | axe secret push CUSTOMER/SERVICE/mcp-client-secret -

# 9. tenant admin consent (필요 시 Azure Portal 에서 1 클릭)
#    User.Read + mcp.access 둘 다 grant
```

**함정 — `az` stderr 가 password 와 합쳐져 vault corrupt (Blueprint 270자 사건 2026-05-21)**: 반드시 `2>/dev/null` 로 stderr 분리.

**검증**:

```bash
az ad app show --id APP_ID --query "{accessTokenAcceptedVersion:api.requestedAccessTokenVersion, identifierUris:identifierUris, signInAudience:signInAudience}" -o json
```

frame · hive · blueprint 비교 시 차이 0 이어야 한다. 차이 있으면 fix.

**별개 — app-only write 기능의 Graph Application permission**: 위 9 항목은 **MCP connector app** (token 검증 + id_token email claim 용 `User.Read`) 한정이다. Blueprint 의 admin send-as write 기능은 app-only token (`getAppOnlyClient()`, client-credentials)을 쓰므로 **Blueprint Next.js app (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`)** 에 Application permission 을 부여해야 한다 — connector app (`482598f7-...`) 이 아니다 (함정 [/ops/known-gaps#blueprint-azure-app-id-혼동](/ops/known-gaps#blueprint-azure-app-id-혼동)):

| 기능 | Application permission | 결정 |
|---|---|---|
| calendar send-as (`as_user_email`) | `Calendars.ReadWrite` | D-bp-mcp-calendar-2 |
| `send_mail` send-as (`as_user_email`) | `Mail.Send` | D-bp-mcp-mail-1 |

부여 후 `az ad app permission admin-consent --id 2b222356-1c36-48e0-96a3-2c5e0ecbf937` (Global Admin) → `docker restart blueprint-app-blue` (또는 -green; MSAL client-credential in-memory 캐시 폐기). 상세 = [/architecture/auth § app-only Application permission (send-as)](../architecture/auth). 비-admin caller 의 send-as 시도는 코드가 403 `send_as_forbidden` 로 차단하므로 self (delegated) 경로는 이 permission 없이도 동작.

---

## 2. cloudflared ingress — 1 줄 (path-based)

`/Users/axe/.axe/tunnels/axelabs/config.yml` 의 `ingress:` 에 prepend:

```yaml
- hostname: axe.axelabs.ai
  path: ^/SERVICE/mcp(/.*)?$
  service: http://host.docker.internal:PROXY_PORT

- hostname: axe.axelabs.ai
  path: ^/SERVICE/\.well-known/oauth-protected-resource(/.*)?$
  service: http://host.docker.internal:PROXY_PORT
```

**함정**: cloudflared 는 **path prefix 를 strip 하지 않는다**. 컨테이너가 `/SERVICE/mcp` 를 그대로 받음. 따라서 Starlette 라우트도 `/SERVICE/mcp` 에 mount.

---

## 3. Caddy reverse proxy (axe-SERVICE-mcp-proxy)

frame-proxy / hive-proxy 미러. cloudflared 가 graceful reload 미지원이라 사이에 끼움 (blue/green swap 시 sub-second).

`/Users/axe/.axe/SERVICE-mcp-proxy/Caddyfile`:

```
:80 {
    reverse_proxy SERVICE-mcp:3000 {
        lb_try_duration 5s
        lb_try_interval 250ms
        header_up Host {http.request.host}
    }
    encode gzip
    log { output stdout; format console; level INFO }
}
```

**함정**: nested `handle_path` syntax 쓰지 마. 단순 `reverse_proxy` 만 (Blueprint Caddyfile syntax error 2026-05-21).

---

## 4. Python 코드 — frame `auth_oidc.py` + `mcp/http_server.py` 1:1 미러

### 4.1 `auth_oidc.py` — JWKS + 토큰 검증 (∼180 줄)

**필수 4 가지 (Blueprint 양파껍질 1·3 사건)**:

```python
# ① httpx.Timeout — 4-arg 또는 default 명시. partial kwargs 는 0.28 부터 ValueError.
_JWKS_HTTP_TIMEOUT = httpx.Timeout(connect=2.0, read=3.0, write=2.0, pool=5.0)
#                                                          ^^^^^^^^^^^^^^^^^^^^ 빠뜨리면 500

# ② audience = [client_id GUID, application_id_uri]
#    v2 endpoint 의 access_token aud = client_id GUID (NOT App ID URI).
#    PyJWT 가 list 의 any 매칭. 둘 다 줘야 v1/v2 양립.
expected_audiences: list[str] = [get_client_id(), get_app_id_uri()]
payload = pyjwt.decode(
    token, public_key,
    algorithms=["RS256"],
    audience=expected_audiences,       # ← list, 단일 string 금지
    issuer=[get_microsoft_issuer(), get_microsoft_issuer_v1()],
    options={"require": ["exp","iat","iss","aud","sub"]},
    leeway=60,
)

# ③ JWKS cache + fail cooldown + kid-miss force refetch
#    Microsoft 의 key rotation 대응. frame/auth_oidc.py:47-78 그대로.

# ④ email claim fallback 순서
email = (payload.get("email")
         or payload.get("preferred_username")
         or payload.get("upn") or "").strip().lower()
```

### 4.2 `mcp/http_server.py` — Starlette + FastMCP wiring (∼270 줄)

**필수 5 가지**:

```python
# ① lifespan forward — Starlette Mount 는 child lifespan 미전파
def build_app() -> Starlette:
    mcp_app = mcp.streamable_http_app()
    @asynccontextmanager
    async def _lifespan(app: Starlette):
        async with mcp_app.router.lifespan_context(app):  # ← 안 부르면
            try:
                yield                                       #   "Task group not initialized"
            finally:
                await db_shutdown()

# ② 401 reason 노출 (body + log)
def _unauthorized(request, request_id, reason):
    log.warning("401 %s reason=%s", request.url.path, reason)
    body = {"error": {
        "code": _map_code(reason),    # MISSING_TOKEN / INVALID_TOKEN / USER_NOT_PROVISIONED / UNAUTHORIZED
        "message": reason,             # ← 고정 string 금지. reason 그대로.
        "context": {"request_id": request_id, "reason": reason},
        ...
    }}
    # WWW-Authenticate resource_metadata = APP_ID_URI 에서 /mcp suffix strip + /.well-known/...

# ③ FastMCP DNS-rebinding guard 우회 — main() 안에서 build_app() 전에:
allowed_hosts = os.environ.get("SERVICE_MCP_ALLOWED_HOSTS")
if allowed_hosts:
    mcp.settings.transport_security.allowed_hosts = [h.strip() for h in allowed_hosts.split(",") if h.strip()]
# 안 하면 axe.axelabs.ai 가 421 Misdirected Request

# ④ Route mount: cloudflared 가 path 그대로 보내므로 `/SERVICE/` mount + 화이트리스트
routes = [
    Route("/health", health),
    Route("/SERVICE/health", health),
    Route("/SERVICE/.well-known/oauth-protected-resource", oauth_protected_resource),
    Mount("/SERVICE", app=mcp_app),
]

# ⑤ JWTAuthMiddleware 의 public-path 화이트리스트도 `/SERVICE/` prefix 포함
if path in ("/health", "/SERVICE/health", "/SERVICE/.well-known/oauth-protected-resource", ...):
    return await call_next(request)
```

---

## 5. docker-compose.yml — 5 항목

```yaml
mcp:
  build: { context: .., dockerfile: mcp/Dockerfile }
  container_name: SERVICE-mcp
  env_file: ../.env
  environment:
    - SERVICE_MCP_PORT=3000
    - SERVICE_MCP_APP_ID_URI=${SERVICE_MCP_APP_ID_URI:-https://axe.axelabs.ai/SERVICE/mcp}
    - AZURE_AD_TENANT_ID=${AZURE_AD_TENANT_ID:-122fb574-...}
    # ① allowed_hosts (axe.axelabs.ai + 컨테이너 DNS + localhost)
    - SERVICE_MCP_ALLOWED_HOSTS=SERVICE-mcp:*,localhost:*,127.0.0.1:*,host.docker.internal:*,axe.axelabs.ai
    - SERVICE_MCP_ALLOWED_ORIGINS=https://axe.axelabs.ai,https://claude.ai,https://claude.com
  networks:
    default:
      aliases:
        - SERVICE-mcp
    # ② artemis network 도 참여 (axelabs-tunnel 같은 네트워크여야 cloudflared 가 닿음)
    artemis:
  # ③ Python 이미지면 curl healthcheck (Node 잔재 `node -e fetch(...)` 금지)
  healthcheck:
    test: ["CMD", "curl", "-fsS", "http://127.0.0.1:3000/health"]
    interval: 30s
    timeout: 5s
    retries: 3
    start_period: 10s
  depends_on:
    postgres:
      condition: service_healthy
```

**함정 (Blueprint 양파껍질 5 사건)**: healthcheck 가 Node 잔재면 컨테이너 영원히 `unhealthy`. Python 이미지면 curl 만.

---

## 6. customers.yaml entry — D-ops-17 매니페스트

```yaml
azure_apps:
  CUSTOMER:
    SERVICE_mcp:                # D-SERVICE-mcp-1
      client_id: "GUID"
      application_id_uri: "https://axe.axelabs.ai/SERVICE/mcp"
      scopes:
        - "https://axe.axelabs.ai/SERVICE/mcp/mcp.access"
      # client_secret 는 vault 에서 pull (env 명시)
      client_secret_env: "AZURE_SERVICE_MCP_CLIENT_SECRET"

services:
  SERVICE:
    env_file: "/Users/axe/SERVICE/.env"
    secrets:
      - { env: AZURE_SERVICE_MCP_CLIENT_SECRET, vault: "SERVICE/CUSTOMER/mcp-client-secret", rotation_external: azure }
      # 기타 비밀들 ...
```

`axe secret push PATH -` 로 push, `axe secret pull SERVICE` 로 deploy-time pull.

---

## 7. 등록 절차 — 사용자 화면 (claude.ai)

1. Settings → Connectors → **+ Add custom connector**
2. URL: `https://axe.axelabs.ai/SERVICE/mcp`
3. Client ID + Client Secret 입력 (vault 에서 `axe secret get SERVICE/CUSTOMER/mcp-client-secret -n`)
4. Microsoft 로그인 (axellc.com 계정) → 동의 → claude.ai 복귀
5. **성공 신호**: connector 상세에 tool 목록이 노출됨 (whoami, list_..., 등)

**실패 시 사용자 화면 메시지 → 진짜 원인 매핑** (Blueprint 5 fix 회고):

| claude.ai 메시지 | 실제 원인 | 진단 path |
|---|---|---|
| "the integration may not be available right now due to a temporary error" | server 가 500 응답 (verifier 자체 ValueError 등) | `docker logs SERVICE-mcp` traceback |
| "the integration rejected the credentials, so the connection was reverted" | server 가 401 응답 | log.warning `reason=...` 확인 (`§ 4.2 ②` fix 필수) |
| "Audience doesn't match" (응답 body) | `audience=` 가 list 아님 (`§ 4.1 ②`) | aud claim 확인 — v2 면 client_id GUID |
| "Task group is not initialized" (응답 body 또는 컨테이너 로그) | lifespan forward 누락 (`§ 4.2 ①`) | boot log 에 "StreamableHTTP session manager started" 있어야 함 |
| "Invalid Host header" + 421 | allowed_hosts 미설정 (`§ 4.2 ③`) | `BLUEPRINT_MCP_ALLOWED_HOSTS` env 확인 |

---

## 8. 운영 — 21 가지 체크포인트

배포 후 다음을 모두 확인. 어느 하나 실패 시 production 으로 안 보냄.

- **#1–#16 = 전송·인증·부팅 레이어** (frame · hive · blueprint 가 검증한 wire/OAuth/DB 항목).
- **#17–#21 = skill-integration 레이어** ([index](../services/index) 가 도입). MCP 서버가 *판단 도구* (propose_deal_closure 류 write tool + ic / pmc skill 호출) 를 노출하면, 도구가 idempotent 한지 · citation 이 roundtrip 하는지 · skill 끼리 충돌 시 audit 에 남는지 · 의존 down 시 graceful 한지 · schema 가 진화해도 옛 artifact 가 읽히는지를 추가로 검증한다. write tool 없는 read-only MCP (matrix 류) 는 #17–#21 면제.

| # | 검증 | 명령 | 정답 |
|---|---|---|---|
| 1 | 컨테이너 healthy | `docker ps \| grep SERVICE-mcp` | `Up X (healthy)` |
| 2 | health endpoint | `curl https://axe.axelabs.ai/SERVICE/health` | 200 OK |
| 3 | OAuth metadata | `curl https://axe.axelabs.ai/SERVICE/.well-known/oauth-protected-resource` | 200 + 정확한 issuer/scopes |
| 4 | Bearer 없음 → 401 | `curl -X POST https://axe.axelabs.ai/SERVICE/mcp` | 401 + `WWW-Authenticate: Bearer ... resource_metadata="..."` |
| 5 | fake Bearer → 401 with reason | `curl -X POST ... -H "Authorization: Bearer xxx"` | 401 + body.error.context.reason 노출 |
| 6 | boot log: session manager | `docker logs SERVICE-mcp` | `StreamableHTTP session manager started` |
| 7 | JWKS fetch 성공 | (첫 인증 호출 후) `docker logs` | `GET .../discovery/v2.0/keys "HTTP/1.1 200 OK"` |
| 8 | 컨테이너 DNS alias | `docker exec axelabs-tunnel ping -c1 SERVICE-mcp` | 응답 |
| 9 | Caddy → backend | `docker logs axe-SERVICE-mcp-proxy` | `upstream "SERVICE-mcp:3000"` |
| 10 | cloudflared ingress | `cloudflared tunnel info axelabs` | hostname 포함 |
| 11 | Azure app manifest | `az ad app show --id APP_ID` | accessTokenAcceptedVersion=2, identifierUris=URL 형식 |
| 12 | SP 존재 | `az ad sp list --filter "appId eq 'APP_ID'"` | non-empty |
| 13 | vault secret 유효 | `axe secret get PATH -n \| wc -c` | 40~50 자 (270 자면 stderr 섞임) |
| 14 | claude.ai 직접 등록 | 위 § 7 의 1~5 단계 | tool 목록 노출 |
| 15 | **DATABASE_URL 유효** (D-bp-mcp-3) | `docker exec SERVICE-mcp printenv DATABASE_URL` | `postgresql://...` 또는 `postgresql+asyncpg://...` (SQLite `file:./...` 면 = .env 잔재 → 제거) |
| 16 | **startup probe 통과** (D-bp-mcp-3) | `docker logs SERVICE-mcp \| grep "startup probe"` | `startup probe: DB reachable, schema accessible` (없으면 lifespan fail = DB 미접속). ⚠️ `/health/ready` endpoint 만 가진 service (frame · hive 2026-05-22 상태) 는 broken DB 로 부팅 가능 — first request 가 와야 fail → blue/green swap promote 위험. **lifespan 안에서 SELECT 1 1 블록 호출** 패턴 강제. `blueprint/mcp/src/blueprint_mcp/mcp/http_server.py:238-260` 1:1 미러. |
| 17 | **skill write tool idempotency** (D-index-13) | 동일 input 으로 write tool 2회 호출 (예: `propose_deal_closure(deal_id=X, idempotency_key=K)` 두 번) | 1회차 = 적용 + `(artifact_id, was_inserted=true)`, 2회차 = **`409` / `IdempotencyConflict`** (또는 `was_inserted=false` idempotent skip) — **두 번째 호출이 중복 ledger row 를 만들면 FAIL**. index 는 `idempotency_record` 테이블 (hive 패턴 mirror, 24h TTL) 로 atomic propose 의 race 차단 — `index/migrations/20260528000001_shared_schema.up.sql` + `error.rs::IndexError::IdempotencyConflict` (→ `StatusCode::CONFLICT`). agent 가 retry/재호출해도 안전해야 함 (네트워크 timeout 후 재시도 = 흔함). |
| 18 | **citation resolver roundtrip** (durable ≠ fragile) | propose 한 artifact 의 citation 을 다시 resolve → 원본 anchor 와 대조 | resolve 한 값이 원본과 **상대오차 ±0.001% 이내** (재무 수치는 bit-exact 권장). `durable` citation (anchor = sha256 / drive_item_id / frame journal_id 같은 stable ref) 은 100% 재현, `fragile` citation (텍스트 anchor·페이지 추정) 은 별도 카운트되어 노출되어야 함 — `index/src/html.rs` 의 `citation_durable_total` / `citation_fragile_total`. fragile 비율이 0 이 아니면 status board 에 표시 (숨기면 FAIL). |
| 19 | **cross-skill conflict → audit_trail** (silent resolve 금지) | 두 skill (예: ic 재무모델 vs frame 실적분개) 이 같은 metric 에 다른 값을 propose → conflict 감지 | 충돌이 **자동으로 한쪽을 골라 덮어쓰지 않고**, `artifact_event` append-only 감사 로그 (op=propose) + reconcile 레이어에 `{min, max, relative_gap, [{value, source_file, location}]}` 로 노출되어야 함. index 는 상대갭 **10% 초과** 시 metric group 을 conflict 로 flag (`artifact.rs` conflict guard) — "conflict 는 metric 레벨에서 표면화, 절대 silent 해결 안 함". 판단 도구가 충돌을 조용히 삼키면 FAIL. |
| 20 | **graceful degradation** (의존 down 시 markdown-only / warn) | 의존 서비스 1개 강제 정지 후 도구 호출 (예: skill 의 humanize sub-agent OR frame MCP upstream 차단) | 전체 pipeline 이 **panic / 502 로 죽지 않고** degrade — index ic skill 은 humanize 2회 실패 시 `degrade-to-warn` (결과 폐기 → `pre_humanize.attempt1` backup 으로 PDF 렌더 + 워터마크, 진행은 막지 않음, `skills/ic/SKILL.md`). blue/green Caddy 는 한 컬러 down 시 다음 요청을 살아있는 컬러로 자동 라우팅 (graceful reload). 의존 부재가 hard-fail 을 일으키면 FAIL. |
| 21 | **schema evolution 하위호환** (옛 artifact 읽힘) | `schema_version` 을 올린 새 코드로 **이전 버전 artifact** 를 read/list | 옛 row 가 그대로 역직렬화되어야 함 — index artifact 는 `schema_version integer NOT NULL DEFAULT 1` (`migrations/20260526210000_initial_artifact_schema.up.sql`) + back-compat shim (`artifact.rs`: 기존 caller 는 default provenance `skill="manual"`) + seed 가 "schema 가 실데이터와 backward-compatible" 임을 증명 (`seed.rs`). migration 후 옛 artifact 가 깨지면 FAIL. **acceptance gate**: index 는 `cargo test` (seed roundtrip + 23 live seed 역직렬화) 를 배포 게이트로 사용 — read tool 변경 시 이 gate 통과 필수. |

> **#17–#21 운영 모니터 (배포 후 24h)**: idempotency 위반 (중복 ledger) · fragile citation 급증 · 미해결 conflict · degrade-to-warn 발동 빈도 · schema 역직렬화 실패는 **status board 지표**다 (index `/index` status page 의 `artifact_event` append-only count + `citation_durable/fragile` + `conflict` 카운트). 첫 24h 동안 fragile 비율 · conflict 건수 · degrade 발동을 관찰하고, 비정상 spike 면 promote 보류. read-only MCP (matrix) 는 write tool 이 없어 #17·#19 비해당, #18·#20·#21 도 노출 도구 한정으로 N/A 처리 가능.

---

## 9. 디버깅 — 첫 번째 행동

증상이 무엇이든 **이것부터**:

```bash
docker logs SERVICE-mcp --since 5m 2>&1 | grep -iE "401|reason|warning|error|exception|task group|invalid" | head -30
```

그 다음 proxy:

```bash
docker logs axe-SERVICE-mcp-proxy --since 5m 2>&1 | grep -E '"status": [45]' | tail -20
```

응답 body 가 진단 정보 들어있는지 확인:

```bash
curl -X POST https://axe.axelabs.ai/SERVICE/mcp \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZXN0IjoxfQ.invalid" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | jq .error
```

`.error.message` 와 `.error.context.reason` 이 모두 노출되어야 정상 (`§ 4.2 ②` 통과).

---

## 10. 양파껍질 회고 (Blueprint MCP, 2026-05-21)

5 단계 모두 frame 코드에 byte-by-byte 미러했더라면 0 단계.

| 차단 | 메시지 | 원인 | Fix |
|---|---|---|---|
| 1 | "integration may not be available" (500) | `httpx.Timeout(connect, read)` 2-arg | 4-arg form |
| 2 | (모든 401 이 같은 메시지) | `_unauthorized` body 가 reason 무시 | reason → body + log |
| 3 | "rejected the credentials" (401) | `audience=app_id_uri` 단일 | `audience=[client_id, app_id_uri]` |
| 4 | (auth 통과 후 첫 호출) `Task group not initialized` | Starlette Mount 가 FastMCP lifespan 미전파 | `lifespan=inner.router.lifespan_context` wrap |
| 5 | 421 `Invalid Host header: axe.axelabs.ai` | DNS rebinding guard | `mcp.settings.transport_security.allowed_hosts` env |
| 6 | "Authorization with the MCP server failed" (claude.ai UI, 종일 broken, D-bp-mcp-3 2026-05-22) | D-config-17 Postgres cutover 가 `.env` 의 `DATABASE_URL="file:./data/blueprint.db"` SQLite legacy line 안 지움 → mcp 가 받음 → SQLAlchemy `ArgumentError` deep in ASGI → 모든 Bearer 요청 silent 500 → claude.ai 는 일반적 OAuth fail 로 표시 → 운영자가 secret 만 의심 | (a) `.env` 의 stale `DATABASE_URL` line 제거 (compose default `${DATABASE_URL:-postgresql://...}` 적용), (b) `config.get_database_url()` fail-fast on non-postgres URL, (c) Starlette lifespan 에 `SELECT 1` startup probe → DB 미접속 시 healthcheck fail → blue/green swap 거부 |

**총 6 PR (#331~#335, #346)**, 약 2 시간. 같은 시간에 frame 1:1 copy + Postgres cutover env audit 했다면 30 분.

**Lesson 항구화**:
1. 새 MCP 서버 = `cp -R frame/src/frame /tmp/NEW` 부터.
2. 첫 PR 부터 `_unauthorized` reason 노출 — 진단 도구가 우선.
3. 등록 시도 시 claude.ai 의 generic 메시지 ↔ 컨테이너 로그 매핑 표 (`§ 7`) 참조.
4. **DB 종속 service 는 startup probe 필수** — lifespan 에서 `SELECT 1` 호출, 실패 시 raise → healthcheck fail → blue/green swap 거부. silent runtime 500 보다 명시적 부팅 실패가 훨씬 안전.
5. **env_file 잔재 검사** — 매 service launch 전 `docker exec SERVICE printenv DATABASE_URL` 가 정확한 형식인지 § 8 #15~16 으로 확인.

---

## 참고

- frame 구현: `/Users/axe/frame/src/frame/{auth_oidc.py, mcp/http_server.py}`
- hive 구현: `/Users/axe/hive/src/hive/{auth_oidc.py, mcp/http_server.py}`
- blueprint 구현: `/Users/axe/blueprint/mcp/src/blueprint_mcp/{auth_oidc.py, mcp/http_server.py}` (2026-05-21 standalone)
- index 구현 (skill-integration 레이어 #17–#21): `/Users/axe/index/src/{artifact.rs, error.rs, html.rs, seed.rs}` + `migrations/20260528000001_shared_schema.up.sql` (idempotency_record) — [/services/index](../services/index)
- 인증 흐름: [/architecture/auth](../architecture/auth)
- 비밀 매니페스트: [/architecture/secrets](../architecture/secrets) (D-ops-17)
- 결정 기록: [/ops/decisions](../ops/decisions)

---

<!-- PAGE https://docs.axelabs.ai/architecture/para-os -->

# PARA OS — 일하는 방식과 지식의 구조

> Blueprint 의 PARA 는 파일 정리법이 아니라 조직론. Area(영속 기능) × Project(임시 TFT) matrix org 를 substrate 로, 지식이 claim·judgment·document 로 흐른다. dispatch="집"(link) 모델, governance 결정로그+결재워크플로, 죽은 딜 본질.

URL: https://docs.axelabs.ai/architecture/para-os

# PARA OS — 일하는 방식과 지식의 구조

Blueprint 의 PARA 는 파일 정리법이 아니라 **조직론**이다. Area(영속 기능) × Project(임시 TFT) 의 matrix org 를 substrate 로 삼고, 그 위에 지식이 흐른다. 도메인 서비스(frame/hive/index)는 성숙한 Area 가 물질화한 것, Blueprint 는 모든 Area 의 기본 substrate + 가로 결정로그.

> 본 페이지 = 설계 **철학·원칙** (방향). 저장·citation·schema 구현 세부는 [/architecture/artifacts](/architecture/artifacts), 결정 이력은 [D-bp-para-1](/ops/decisions). 일부 항목은 **열린 질문** (§10) — 확정 시 decisions 등재. SoT 메모 = `project_para_ai_os_philosophy.md` (Blueprint global memory).

## 1. PARA = 조직론

| Layer | 조직론적 정체 | 시간성 | 예 |
|---|---|---|---|
| **Project** | cross-functional TFT (동적 조직) — 목표 향해 모였다 끝나면 흩어짐 | 임시 | 딜, 펀드 결성, 유상증자, 분쟁 조정 |
| **Area** | 영속 기능 (정적 조직) — 통상의 부서 | 영속 | Finance · HR · Investment · Legal · IR · BOD |
| **Resource** | 일하는 방법·틀 — Project·Area 수행의 지식 기반 | 재사용 | DD 체크리스트, IC 템플릿, 섹터 프레임, 회사소개서 |
| **Archive** | 식은 이력 — 적극 탐색 불요 | 냉동 → 폐기 | 죽은 딜, 종료 프로젝트 |

Project 와 Area 는 matrix org 의 두 축이다 — **정적 기능 × 동적 태스크포스**. Project 가 전사에 던져지면 참여자가 emerge 하므로 "살아있는 팀"이자 "컨테이너"다 (둘 다).

## 2. 기하학 — Area 가 척추, R/A 는 Area 안

PARA 는 4 개 평등한 형제가 아니다. **Area 가 척추**이고, Resource 와 Archive 는 *각 Area 안에* 매달린다. Project 만 Area 들을 가로지른다.

```text
Area (영속 기능) ── 척추
  ├─ Live state   서비스화(frame/hive/index)  |  미졸업(Blueprint artifact)
  ├─ Resource     그 기능의 방법·틀  (hot)
  └─ Archive      그 기능의 식은 이력  (cold)
Project (TFT) ── Area 들을 가로지르는 동적 레이어
```

## 3. MCP = 물질화된 Area + 졸업 경로

도메인 서비스는 추상 서비스가 아니라 **Area 를 AI-native 로 물질화한 것**이다. frame = Finance Area, hive = HR Area, index = Investment Area. "폴더+artifact 만으로 Area 관점이 부족 → 개별 서비스화 + DB 적재로 UX 극대화" 가 그 동기.

- **기본 = Blueprint artifact** (인큐베이터). 새 테넌트·새 Area 는 전부 여기서 시작.
- **졸업 = 전용 MCP 서비스**. 트리거 = 저장이 아니라 **도메인 로직/operation + AI 상호작용** (frame=복식부기·마감, hive=급여계산, index=IRR). 단순 저장이면 Blueprint 로 충분.

## 4. Blueprint = 모든 Area 의 기본 substrate

| 층위 | 미졸업 / 무서비스 Area | 졸업 Area (frame/hive/index/gate) |
|---|---|---|
| Live state | Blueprint artifact | 서비스가 소유 |
| Resource | Blueprint | **서비스가 자기 도메인 Resource 소유** (index = DD 체크리스트·섹터 프레임·IC 템플릿) |
| Archive | Blueprint (cold) | **서비스가 자기 도메인 Archive 소유** (index = 죽은 딜) |
| 결정 로그 | gate SoR · Blueprint citation mirror (가로) | gate SoR · Blueprint citation mirror (가로) |

→ **Blueprint = 도메인 서비스가 *안 덮는* 것의 substrate**: (a) 미졸업·전용 서비스 없는 Area 의 live + R/A, (b) **cross-service 종합물**(보드팩·cross-domain 메모 — 각 서비스로 citation), (c) PARA fabric(workspace/dispatch/home·link) + **gate.decision mirror**(가로). 졸업한 서비스(index 등)는 자기 도메인 지식(**죽은 딜·섹터 프레임 포함**)을 *가져간다* — moat(죽은 딜 복리) = index, Blueprint = 토대 + 연결 조직.

## 5. 저장 substrate — 저장소(SoR) vs 검색 index 구분

벡터 DB·임베딩·rerank 은 **저장소가 아니라 검색 index**다. 진실 바이트가 아니라 원본 가리키는 임베딩만 둔다. 그래서 "OneDrive 냐 Pinecone 이냐" 는 양자택일이 아니라 "OneDrive(SoR) + 벡터 index".

| 대상 | 저장 (SoR) | 검색 |
|---|---|---|
| typed Area live (예: frame 잔액) | 서비스 DB | typed 쿼리 (벡터 불요) |
| Resource (hot) | 파일 / artifact | **벡터 index** (의미검색) |
| Archive (cold) | 싼 cold 보관 | 거의 안 함 — 폐기 전 *추출 지식만* 영구·queryable |

## 6. Dispatch = "집(home)" 모델

> **move 냐 copy 냐 link 냐 — 이 고민은 폴더가 강요한 가짜 3지선다다.** 폴더는 파일을 물리적으로 한 곳에만 둔다. 그래서 "투자계약서가 딜 소속이냐 Legal 소속이냐" 에 좋은 답이 없다.

전환: **artifact 는 몸통이 하나, 집은 여럿(link).** dispatch = 바이트 이동이 아니라 *집 배정*이다.

| 산출 종류 | 동작 | 예 (실제 워크스페이스) |
|---|---|---|
| 소유·소모성 | **move → Archive → 폐기** | LoI 초안 v1~v5, dataroom 원본, 회의 스크래치 |
| Area 영구 귀속 | **link / 정착** (canonical 은 Area, Project 는 참조) | 인감·고유번호증·통장(펀드 entity), 투자계약서(Legal), 서명 NDA, 최종 LoI, IRR claim(index) |
| 재사용 지식 | **copy-curate → Resource** (복제 아닌 재사용본 저작) | 섹터 경쟁분석, 펀드 결성 템플릿(1호→2호), 리턴모델 방법론 |

즉 **link 가 기본**(다중 집), move 는 소모성 working 파일만, copy 는 재사용본을 *새로 저작*할 때만. 이는 [D-bp-entity-2](/ops/decisions) 의 copy-with-provenance default 를 **link-default 로 revise** 한 것. cross-functional 분배는 별도 동작이 아니다 — Project 가 가로질러서 산출이 *원래부터* 여러 Area 소속이다.

## 7. Governance — 결정로그(record) vs 결재워크플로(process)

지식뿐 아니라 **결정**도 1급이다. 둘을 가른다:

- **결정 로그 (record)** — 무엇이·누가·언제·무슨 권한으로·뭘 근거로 결정됐나. append-only, 불변(수정 아닌 **supersede**), 모든 Area 가 cite. **record SoR = gate `decision` 테이블**(서비스가 SoR 소유) · **Blueprint = `gate.decision` citation mirror(가로 거버넌스)** — [D-gate-2](/ops/decisions) 로 refine(원래 "Blueprint core primitive" → service-owns-SoR + visibility-gated mirror, standalone 가능). frame 의 `register_resolution` / `query_effective_resolutions` / `link_journal_to_resolution` 이 회계 범위 결정로그 — 이를 가로로 일반화.
- **결재 워크플로 (process)** — 기안 → 결재선(DOA) → 승인/반려 → 시행 = 한국형 전자결재. 그 위 policy-driven·agent-assisted 레이어. 워크플로 완료 → 결정로그 한 줄 방출.

**서명은 한 종류**다: 내부 sign-off = 외부 e-sign = "행위자가 결정을 시점에 (법적으로) 확정". 서명은 결정 파이프라인의 **actuator** 로 실행되고, 봉인 결과를 결정에 link 한다. **Area 서비스 = 결정 파이프라인의 actuator** — 승인된 결정 → `frame.post_journal`/`index.register_deal` 호출, 결과를 결정에 link(앞으로) + 도메인 변경이 승인 결정을 cite(뒤로). 통합 구현 = [backlog B-bp-decision-pipeline-esign](/ops/backlog).
>
> **(2026-06-07 갱신 · [D-gate-5](/ops/decisions), [D-gate-3](/ops/decisions) e-sign 입장 supersede)**: 직접 서명엔진 build 는 *defer 되지 않고 당겨져 **구현**됐다* (암호등급). gate Phase-1 = **gate-native `esign.gate` actuator** — 시행 시 승인된 결정의 canonical bytes 를 **CAdES-BES → RFC3161 → CAdES-T** 로 server-seal(단일 서버 서명 identity, RSA-2048+SHA-256), append-only `esign_seal` evidence(전자문서법 §5 custodian) 저장 + `verify_seal` 검증. 법적 근거 = 전자서명법 2020 사서명(실지명의 = gate auth · 서명의사 = 결재 승인). 모두싸인 = optional alt provider 로 강등. **잔여**: 외부 서명자 본인확인기관(정보통신망법 §23-3) = 진짜 Phase-2; HSM(trait ready)·PAdES-PDF·prod-key = 하드닝. red-team 이 직접-build 를 막았던 P0(HSM·HTML→PDF 결정성·custody)는 해소-또는-명시(canonical bytes 결정성 now / HSM abstraction ready / custody = esign_seal + TSA). 상세 = [/architecture/governance](/architecture/governance) §6.

> 한국 시장에서 전자결재 + e-sign 은 **table-stakes** — 테넌트가 당연히 기대한다. internal 편의가 아니라 product requirement.

## 8. 본질 — 죽은 딜을 저장한다

live deal 관리는 누구나 한다 (moat 아님). **VC 지식의 압도적 대부분은 죽은 딜에 있다** — 시장맵·경쟁분석·섹터 thesis·valuation, 그리고 무엇보다 **judgment("왜 패스했나")**. 통상 이게 Archive 에 묻혀 증발한다. AI-native fund 가 **죽은 딜 지식을 재사용 Resource + queryable judgment corpus 로 harvest** 하면 복리로 쌓인다 ("이 섹터 딜 N 건 봤고 패턴은 이렇다").

그래서 Archive 모델이 정밀해진다: **raw 파일은 싸게 폐기, 추출 지식(judgment + 큐레이션된 섹터 Resource)은 영구·queryable.** 폐기 전 harvest 가 §6 dispatch 의 copy-curate 가 존재하는 *이유*다. 이것이 Investment Area 서비스(index)가 invested 딜뿐 아니라 **passed/dead 딜을 1급으로 저장**해야 하는 근거.

## 9. 관통 원칙

- **종류별로 가른다** — 한 상자에 여러 종류를 욱여넣으면 탁해진다. copy/link, Archive/Area, dispatch 가 다 그 증상이었다. 조직론 축(Area/Project/Resource/Archive) + 인식론 축(claim/judgment/document)으로 분해하면 녹는다.
- **claim · judgment · document** — claim(관측: source-cited, live, 갱신) · judgment(판단: author, 불변·supersede) · document(산출: 둘의 구성).
- **link 가 기본, 단일 출처** — copy 는 재사용본 저작에만.
- **결정은 불변 로그** — process(결재)가 record(결정로그)를 낳는다.
- **신규 코드 = Rust** (2026-06-06 사용자 지침).

## 10. 열린 질문 — 처리 현황

| # | 질문 | 상태 (2026-06-06) |
|---|---|---|
| 1 | 2-level scope (personal efforts + shared Areas) | **확정: personal + shared** ([D-bp-rust-1](/ops/decisions) — artifact `scope` 컬럼) |
| 2 | Governance servicization — Blueprint core 결정로그 vs 독립 서비스 | **확정: 독립 `gate` 서비스 + Blueprint citation mirror** ([D-gate-1](/ops/decisions)·[D-gate-2](/ops/decisions), §7) |
| 3 | Project staffing ("던지면 emerge") 메커니즘 | **후속 defer** ([D-bp-rust-1](/ops/decisions) — Project=컨테이너 + WorkspaceMember, emerge UX 는 후속) |
| 4 | Rust 적용 범위 | **확정: Blueprint 백엔드 점진 Rust 전환(strangler-fig), substrate=첫 organ, 프론트는 TS 유지** ([D-bp-rust-1](/ops/decisions)) |

**구현 토폴로지** (§4 substrate 가 *어떻게* 사느냐): PARA substrate 는 Blueprint 의 **첫 Rust organ** 으로, `blueprint-postgres` 의 `substrate` schema 를 소유하는 sidecar(axum)다 — frame/hive 식 독립 product-service 가 아니라 `axe ship blueprint` 한 경로 안의 내부 organ ([D-bp-artifact-4](/ops/decisions) "monolith first·신규 인프라 0" 을 *언어만 Rust* 로 refine). 상세 = [D-bp-rust-1](/ops/decisions) + ADR `docs/adr/blueprint-rust-migration.md`.

## 관련

- [/architecture/artifacts](/architecture/artifacts) — Artifact · Citation 저장/스키마 구현 세부 (본 페이지의 field-level 토대)
- [/architecture/governance](/architecture/governance) — gate 결정 거버넌스(결재 + e-sign + 법무) 상세 + Phase-1/2 경계 ([D-gate-1](/ops/decisions))
- [D-bp-para-1](/ops/decisions) — 본 페이지의 결정 등재 ([D-bp-entity-2](/ops/decisions) copy→link revise)
- [backlog B-bp-decision-pipeline-esign](/ops/backlog) — 결재 + e-sign 통합 서비스화

---

<!-- PAGE https://docs.axelabs.ai/architecture/platform-identity -->

# 플랫폼 신원 (Blueprint = OIDC Provider)

> Blueprint 가 Entra 를 federate 하고 플랫폼 토큰을 발행 — 로그인 1회로 전 서비스. (D-axe-idp-1 — Phase 1+2 LIVE)

URL: https://docs.axelabs.ai/architecture/platform-identity

# 플랫폼 신원 — Blueprint = OIDC Provider

> **상태**: **Phase 1+2 LIVE** (2026-06-04). Blueprint OP(discovery·jwks·authorize·token) + RS256 서명키(vault `blueprint/axe/oidc-signing-key`) + `axe login` loopback-PKCE + **frame·hive·cortex·index·matrix + Blueprint 자체 MCP — 6개 서비스 전부 Blueprint 토큰 신뢰** (영속 설정, e2e 검증). `axe login` → `axe <svc> tools` GREEN. 본 페이지는 [D-axe-idp-1](/ops/decisions) 설계 SSOT 이자 현행 구현 기준.
> ⚠️ **발행자 자신이 마지막 resource server였다** (2026-06-04 fix): Blueprint MCP 는 토큰을 *발행*하면서도 *검증*은 Microsoft Entra 경로만 알아, 자기 플랫폼 토큰을 `unknown_kid` 로 401 했다 (kid = Blueprint OIDC 서명키, Microsoft JWKS 에 부재). frame 의 `auth_blueprint.py` + iss-dispatch 를 미러해 Blueprint MCP 도 자기 issuer 의 resource server 로 배선 (`BLUEPRINT_ISSUER=https://blueprint.axellc.com`). 교훈: OP 를 세울 때 **그 OP 의 자체 MCP 도 resource-server 목록에 포함**해야 한다.
> 비파괴 cutover 유지 (`BLUEPRINT_ISSUER` 미설정 시 서비스는 종전 Microsoft 경로). **인가 중앙화**(entity grant 토큰 삽입)는 여전히 Phase 3 — 현재는 인증만 Blueprint, 인가는 각 서비스 customers.yaml.

## 본질

오늘 외부/멀티에이전트 접근의 마찰은 **서비스마다 따로 인증**한다는 데서 온다. 직원·에이전트가
frame·hive·index·cortex·matrix 를 쓰려면 서비스별 MCP OAuth 를 각각 통과하고, frame·cortex 는
각자 [OAuth-RP 프록시](/architecture/auth) (D-ops-14/15) 를 따로 운영한다. 신원은 **N 곳에 흩어져** 있다.

**목표 한 줄**: 사람은 **한 번** SSO 로그인하고, 그 결과로 받은 **하나의 플랫폼 토큰**으로 **모든 서비스**를 쓴다.
거버넌스(누가·어떤 스코프·취소·감사)는 **Blueprint 한 곳**에 모인다.

그 한 곳이 **Blueprint** 인 이유:
- Blueprint 는 **이미 Entra 를 federate** 한다 (NextAuth Azure AD provider, [`src/lib/auth.ts`](/architecture/auth)). 신규 IdP 를 세우는 게 아니라 **기존 세션 위에 토큰 발행만 얹는다**.
- Blueprint 는 **이미 per-user 권한의 권위자**다 — `entityScopes` · `EntityRole` · `getEntityRolesForUser` 를 들고 있고, frame/hive 가 `/api/internal/entity-roles` 로 **이미 그걸 물어본다**. 토큰 거버넌스의 자연스러운 자리.
- Blueprint 는 **control plane** (구동 시스템). 서비스가 신뢰할 단일 발행자로 토폴로지상 맞다.

## 현재 상태 — 검증된 인증 표면 (2026-06-03 실측)

각 서비스가 incoming 토큰을 검증하는 방식. "Blueprint 신뢰" 추가 시 바꿀 지점과 난이도를 함께 표기.

| 서비스 | 스택 | validator (file) | iss-dispatch seam | HS256 경로 | "Blueprint 신뢰" 난이도 |
|---|---|---|---|---|---|
| **frame** | Python FastMCP | `src/frame/mcp/http_server.py:438` | ✅ `_is_microsoft_iss` → else HS256 | ✅ `FRAME_JWT_SECRET` | **낮음** — `elif _is_blueprint_iss` 한 가지 추가 |
| **hive** | Python FastMCP (frame fork) | `src/hive/mcp/http_server.py:250` | ✅ `_is_microsoft_iss` → else HS256 | ✅ `HIVE_JWT_SECRET` | **낮음** — frame 과 1:1 동일 패턴 |
| **cortex** | Rust axum | `src/auth.rs:214` | △ HS256 short-circuit → RS256 (MS hardcoded) | ✅ `CORTEX_JWT_SECRET` (배선됨) | **중간** — issuer 파라미터화 |
| **index** | Rust axum | `src/auth.rs:214` | ✗ RS256(MS) hardcoded, fallback 없음 | △ `INDEX_JWT_SECRET` 정의만·**미배선** | **중간** — issuer 파라미터화 + HS256 배선 |
| **matrix** | Rust axum (custom) | `src/auth.rs:17` | ✗ HS256 단일, iss 미검증 | ✅ `MATRIX_JWT_SECRET` 만 | **높음** — async refactor + RS256 + JWKS |
| **blueprint (자체 MCP)** | Python FastMCP | `mcp/src/blueprint_mcp/mcp/http_server.py` | ✅ iss-dispatch 추가됨 (2026-06-04) — Blueprint vs Microsoft | ✗ HS256 경로 없음 (Microsoft + Blueprint 만) | **낮음 (완료)** — frame `auth_blueprint.py` 미러. *발행자 본인이라 누락됐던 행* |

**핵심 발견**:
- frame·hive 는 이미 **iss 로 verifier 를 고르는 dispatch seam** 이 있다 — Blueprint 분기는 한 줄. Phase 1 첫 타깃 = **frame** (seam + `auth_oidc.py` JWKS 머신 재사용 + 이미 CLI GREEN 검증됨).
- Blueprint 측 OP 머신(`SignJWT`/JWKS endpoint/authorize/token)은 **전무** (greenfield). 단 `jose` 는 이미 dependency 이고 검증측 `createRemoteJWKSet` 패턴이 `src/lib/mcp-microsoft-rp.ts` 에 존재.
- customers.yaml 의 tenant 는 **고객사별로 다름** (realchoice = 별도 Entra tenant). → **OIDC-OP 는 per-deployment**: 각 고객 Blueprint = 자기 Entra 를 federate 하는 자기 issuer. AXE 자체 issuer = `https://blueprint.axellc.com`.

## 목표 아키텍처

```
        ┌─────────────────────── 사람 SSO 1회 ───────────────────────┐
        │                                                            ▼
  axe login (CLI)                                         ┌──────────────────────┐
  loopback PKCE                                           │  Microsoft Entra ID  │
        │                                                 │  (customer tenant)   │
        │ 1. open browser /oauth/authorize                └──────────┬───────────┘
        ▼                                                            │ NextAuth (기존)
  ┌───────────────────────── Blueprint = OIDC Provider ─────────────┴──┐
  │  GET  /.well-known/openid-configuration   (discovery)              │
  │  GET  /.well-known/jwks.json              (공개키 — 서비스가 fetch)  │
  │  GET  /oauth/authorize   getServerSession 재사용 → code (PKCE)      │
  │  POST /oauth/token       code+verifier → 플랫폼 JWT(RS256)+refresh  │
  │  POST /oauth/register    DCR (loopback + claude.ai allowlist)      │
  │  POST /oauth/revoke      refresh 취소                               │
  │  거버넌스: scope · EntityRole · 발행 audit · per-user/tenant         │
  └───────────────────────────────┬───────────────────────────────────┘
        2. 플랫폼 토큰 (keychain)   │  iss=blueprint, aud=platform, RS256
        ▼                          ▼  (서비스는 Blueprint JWKS 로 검증)
  ┌──────────┐  Bearer  ┌────────┬────────┬────────┬────────┬────────┐
  │  axe CLI │ ───────► │ frame  │  hive  │ index  │ cortex │ matrix │
  └──────────┘  하나의   └────────┴────────┴────────┴────────┴────────┘
                토큰으로 전 서비스       iss=blueprint 분기 → Blueprint JWKS RS256 검증
```

**원칙**:
1. **Entra federation 은 재사용** — `/oauth/authorize` 가 `getServerSession(authOptions)` 로 기존 NextAuth 세션을 확인. 세션 있으면(=이미 Entra SSO 됨) code 발행, 없으면 `/login` 으로 bounce 후 복귀. Blueprint 가 Entra 와 직접 서버-투-서버 code 교환을 다시 짤 필요 없음 (frame `oauth.py` 의 `/oauth/callback` 단계가 Blueprint 에선 불필요 — 이게 frame 대비 단순화).
2. **하나의 토큰, 전 서비스** — `aud` = 플랫폼 audience 단일값. 서비스별 audience juggling 없음. 서비스 권한은 **scope** 가 가른다.
3. **서비스는 서명만 신뢰** — 각 서비스는 `iss=blueprint` 분기에서 Blueprint JWKS 로 RS256 검증. Phase 1 에선 **인증**만 Blueprint 로 (email vouch); **인가**(email→entity) 는 각 서비스 customers.yaml 그대로 → 비파괴. (entity grant 를 토큰에 심는 **인가 중앙화**는 Phase 3.)

## OIDC-OP 엔드포인트 (Blueprint Next.js 에 신설)

모두 `https://blueprint.axellc.com` (= `BLUEPRINT_OIDC_ISSUER`, 기본 `NEXTAUTH_URL`) origin 에 App Router route handler 로 추가. 전부 **공개**(인증 면제) — 단 authorize 는 세션을 요구.

| 엔드포인트 | 메서드 | 신규 파일 (제안) | 역할 |
|---|---|---|---|
| `/.well-known/openid-configuration` | GET | `src/app/.well-known/openid-configuration/route.ts` | RFC 8414 metadata (issuer, endpoints, jwks_uri, S256, RS256) |
| `/.well-known/jwks.json` | GET | `src/app/.well-known/jwks.json/route.ts` | 공개키 (서비스·CLI 가 RS256 검증) |
| `/oauth/authorize` | GET | `src/app/oauth/authorize/route.ts` | 세션 확인(getServerSession) → 단발 code 발행 (PKCE S256 필수) |
| `/oauth/token` | POST | `src/app/oauth/token/route.ts` | `authorization_code` + `refresh_token` grant → 플랫폼 JWT |
| `/oauth/register` | POST | `src/app/oauth/register/route.ts` | RFC 7591 DCR (loopback + claude.ai redirect allowlist) |
| `/oauth/revoke` | POST | `src/app/oauth/revoke/route.ts` | refresh token 취소 (governance) |
| `/oauth/device_authorization` | POST | (Phase 3) | RFC 8628 device-code (headless) |

frame [`oauth.py`](/services/frame) 가 **검증된 레퍼런스**다 (PKCE 단발 code·atomic 단일소비·S256 constant-time·DCR allowlist 전부 구현). Blueprint OP 는 그것을 그대로 따르되 **차이점 3 가지**:
1. HS256 대신 **RS256 서명** + JWKS 공개 (서비스가 secret 공유 없이 검증).
2. Microsoft 서버-투-서버 교환 단계 **제거** → 기존 **NextAuth 세션** 재사용.
3. **refresh token** 추가 (CLI UX "로그인 1회 후 한동안 유지" + 취소 지점).

## 플랫폼 JWT (access token) shape

RS256, `kid` 헤더. 클레임:

```jsonc
{
  "iss": "https://blueprint.axellc.com",   // BLUEPRINT_OIDC_ISSUER (per-deployment)
  "sub": "<Entra oid>",                     // User.entraOid — 안정적 cross-app 식별자
  "email": "ai@axellc.com",                 // 소문자 정규화
  "aud": "https://axe.axelabs.ai",          // 플랫폼 audience (단일; 전 서비스 공통)
  "scope": "openid profile email frame hive index cortex matrix",
  "azp": "axe-cli",                         // 토큰을 받은 client_id (감사)
  "jti": "<uuid>",                          // 감사 + (선택) 취소 denylist
  "iat": 1730000000,
  "exp": 1730003600,                        // 1h
  "ent": { "axec": ["read","write"], "axev": ["read"] }  // Phase 3 (선택) — 현재는 서비스가 무시
}
```

- **access token**: 짧음 (1h). 만료 시 refresh 로 무중단 갱신.
- **refresh token**: opaque 랜덤 (JWT 아님), 서버측 저장(Prisma), **회전**(rotating — 사용 시 새 발급+구 폐기), 30d. → 취소·도난탐지 지점.
- **scope**: Phase 1 = 서비스 단위 grant (존재 = 그 서비스 접근). frame 의 entity별 read/write 인가는 customers.yaml email→entity 가 그대로 담당. (`frame:read` 같은 fine scope + `ent` 클레임 인가중앙화 = Phase 3.)
- **aud 단일값의 트레이드오프**: 한 토큰이 전 서비스 → 토큰 유출 시 blast radius 가 플랫폼 전체. 완화 = 짧은 exp(1h) + scope + refresh 취소 + loopback-only public client + PKCE 필수. (per-service aud 격리보다 편의를 택한 D-axe-idp-1 의 의도적 선택.)

## 서비스별 신뢰 이전 (trust migration)

각 서비스는 **feature flag** 로 Blueprint 신뢰를 켠다 — `BLUEPRINT_ISSUER` + `BLUEPRINT_JWKS_URL` (+ `BLUEPRINT_AUDIENCE`) **unset = 현행 동작 그대로** (비파괴·롤백 = env 제거).

### frame · hive (Python — 낮음, Phase 1·2)

`http_server.py` 의 dispatch 에 분기 한 줄 + verifier 모듈 신설:

```python
# http_server.py — 기존 if _is_microsoft_iss(iss): ... else: (HS256) 사이에 삽입
elif _is_blueprint_iss(iss):                       # iss == BLUEPRINT_ISSUER
    payload = await verify_blueprint_token(         # 신규 auth_blueprint.py
        agent_token, jwks_url=BLUEPRINT_JWKS_URL,
        issuer=BLUEPRINT_ISSUER, audience=BLUEPRINT_AUDIENCE,
    )
    email = extract_email(payload)
    agent_claims = resolve_subject_to_claims(payload, email, customer_id=cid)  # 기존 재사용
```

`verify_blueprint_token` = `auth_oidc.py` 의 JWKS fetch/cache(`createRemoteJWKSet` 대응, 1h TTL·kid-miss 강제갱신)를 그대로 미러, issuer/aud/exp 검증 후 payload 반환. email→entity 는 **기존 `resolve_subject_to_claims` 무수정 재사용** → 인가 모델 불변.

### cortex · index (Rust — 중간, Phase 2)

`auth.rs:verify_token` 의 단일 MS issuer hardcode 를 issuer-dispatch 로 리팩터:

```rust
let iss = peek_iss(token)?;                        // unverified payload iss
match trusted_issuer(&iss, &state.settings) {
    Issuer::Microsoft => verify_rs256(token, ms_jwks, ms_iss, ms_aud).await,
    Issuer::Blueprint => verify_rs256(token, bp_jwks, bp_iss, bp_aud).await,  // 신규
    Issuer::Self_     => verify_hs256(token, secret),   // cortex 기존 / index 는 여기서 배선
    _ => Err(Unknown),
}
```

`verify_rs256(token, jwks, iss, aud)` 헬퍼로 추출하면 MS·Blueprint 가 같은 코드 재사용. index 는 이참에 `INDEX_JWT_SECRET` HS256 도 배선(cortex `oauth_as.rs` 패턴 복사).

### matrix (Rust custom — 높음, Phase 2 후)

HS256 단일·동기 미들웨어 → ① async 화 ② iss peek ③ Blueprint RS256 분기 ④ JWKS fetch(reqwest 이미 보유) ⑤ `Claims` 에 `iss`/`aud` 필드 추가. ~80–120 LOC. seam 없음 → 마지막.

| 서비스 | flag env | 작업량 | Phase |
|---|---|---|---|
| frame | `BLUEPRINT_ISSUER`,`BLUEPRINT_JWKS_URL`,`BLUEPRINT_AUDIENCE` | ~80 LOC + tests | **1** (모델 증명) |
| hive | 동일 | ~60 LOC (frame 복사) | 2 |
| cortex | `BLUEPRINT_*` (settings) | refactor + ~80 LOC | 2 |
| index | `BLUEPRINT_*` + `INDEX_JWT_SECRET` 배선 | refactor + ~100 LOC | 2 |
| matrix | `MATRIX_BLUEPRINT_*` | async refactor ~120 LOC | 2 |
| blueprint (자체 MCP) | `BLUEPRINT_ISSUER`,`BLUEPRINT_AUDIENCE` (JWKS 파생) | ~150 LOC + 10 tests (frame 미러) | **완료 (2026-06-04)** |

> 위 표가 frame·hive·cortex·index·matrix 만 세고 **Blueprint 자체 MCP 를 빠뜨린 것**이 2026-06-04 의 401 버그 근원이었다 — issuer 가 곧 resource server 라는 사실이 자명해 보여 목록에서 누락됐다. 새 OP 를 세울 땐 *그 OP 의 MCP 도* 이 표의 한 행이다.

## `axe login` — loopback PKCE (CLI)

[AXE CLI](/services) 에 `axe login` (인자 없음) 추가. stdlib 만 (`http.server`·`webbrowser`·`hashlib`·`secrets`·`urllib`):

```
1. CLI: 랜덤 loopback 서버 기동 http://127.0.0.1:<port>/callback
2. CLI: POST /oauth/register {redirect_uris:[loopback]}  → client_id  (또는 정적 axe-cli)
3. CLI: code_verifier 생성, challenge=S256, state 생성 → 브라우저 open
        /oauth/authorize?response_type=code&client_id=…&redirect_uri=loopback
                        &code_challenge=…&code_challenge_method=S256&scope=…&state=…
4. 브라우저: (NextAuth 세션 없으면) Entra SSO 1회 → Blueprint 가 loopback 으로 302 ?code=…&state=…
5. CLI(loopback): code 수신, state 검증 → POST /oauth/token
        grant_type=authorization_code&code=…&code_verifier=…&redirect_uri=loopback
6. CLI: {access_token, refresh_token, expires_in} → keychain 저장. 브라우저엔 "닫아도 됨".
```

- **헤드리스(Codex/CI)**: `axe login --token <T>` / `AXE_TOKEN` env 공존 (gh 모델) — 변경 없음. 또는 Phase 3 **device-code**.
- **검증은 사람 브라우저 로그인 필요** → 단독 e2e 불가, 운영자 SSO 1회로 마무리.
- 토큰 자동 refresh: access 만료 시 CLI 가 저장된 refresh 로 `/oauth/token` (`grant_type=refresh_token`) 조용히 갱신.

## 거버넌스 (Blueprint 중앙)

- **scope**: `openid profile email` + 서비스 grant. 발급 시 Blueprint 가 user 의 `entityScopes`/`EntityRole` 로 허용 scope 를 결정 (consent UI 는 first-party CLI 라 Phase 1 생략 가능, 외부 third-party client 도입 시 추가).
- **revoke**: refresh token 서버측 저장 → `/oauth/revoke` 또는 admin UI 에서 폐기. access 는 짧아(1h) revoke latency = exp. 더 강한 즉시취소 필요 시 `jti` denylist (introspection 없이).
- **audit**: 모든 발행(누가·언제·client·scope·jti)을 append-only 로그. Blueprint 의 기존 로깅/DB 재사용.
- **per-tenant**: issuer 가 per-deployment 이므로 고객사 토큰은 그 고객 Blueprint 가 발행·관리 (sovereignty 정합).

## 키 관리

- RS256 keypair. private key = **vault** (`blueprint/axe/oidc-signing-key`, PKCS8 PEM 또는 JWK) → `BLUEPRINT_OIDC_PRIVATE_KEY` 로 주입. 공개키만 `/.well-known/jwks.json` 에 `kid` 와 함께.
- **회전**: JWKS 에 2 키(old+new) 동시 게시 → 신규 서명은 new `kid`, 검증은 둘 다 수용 → old 만료 후 제거. 서비스 JWKS 캐시 TTL(1h) 고려.
- `jose` (`generateKeyPair`/`importPKCS8`/`SignJWT`/`exportJWK`) 사용 — 이미 dependency.

## 데이터 모델 (Prisma 신설)

```prisma
model OAuthAuthCode {       // authorize→token 단발 code (frame oauth_authorization_codes 대응)
  code         String   @id
  clientId     String
  userId       String
  codeChallenge String
  redirectUri  String
  scope        String
  expiresAt    DateTime
  consumedAt   DateTime?
}
model OAuthRefreshToken {   // refresh + revoke + 회전
  id         String   @id @default(cuid())
  tokenHash  String   @unique     // 평문 저장 안 함
  userId     String
  clientId   String
  scope      String
  expiresAt  DateTime
  revokedAt  DateTime?
  rotatedTo  String?            // 회전 추적 (도난 재사용 탐지)
  createdAt  DateTime @default(now())
}
model OAuthClient {         // 클라이언트 레지스트리 (axe-cli 정적 seed + DCR)
  clientId     String   @id
  name         String
  redirectUris String              // JSON 배열
  type         String   @default("public")  // PKCE-only
  createdAt    DateTime @default(now())
}
```

## 비파괴 cutover (신·구 병행)

보안 핵심 → **점진·가역**. 어느 단계도 기존 claude.ai MS-OAuth 흐름과 frame/cortex 프록시를 **깨지 않는다**.

1. **Blueprint OP 추가** = 전부 신규 route. 기존 동작 0 변경.
2. **서비스별 Blueprint 신뢰 추가** = iss 분기 1개 ADD. MS·HS256 경로 불변. flag(`BLUEPRINT_ISSUER`) unset 이면 무시 = 현행. → **서비스 단위로 독립 ship·롤백**.
3. **per-service 프록시 폐기는 나중** — frame/cortex 의 claude.ai DCR 프록시(D-ops-14/15)는 Blueprint OP 가 충분히 증명될 때까지 **공존**. claude.ai 커넥터 흐름 내내 유지. 통합(claude.ai 를 Blueprint OP 로 이전 + 프록시 제거)은 Phase 2 말~3.

롤백 = 해당 서비스 `BLUEPRINT_*` env 제거 후 recreate. 토큰 발행 중단 = Blueprint route 비활성.

## Phase 계획

- **Phase 1 (모델 증명) ✅ 2026-06-04**: Blueprint OP(discovery·jwks·authorize·token·register·revoke) + RS256 키(vault) + Prisma 모델 + `axe-cli` 정적 client + `axe login` loopback PKCE + **frame** Blueprint 신뢰. → 운영자 브라우저 SSO 1회로 `axe login` → `axe frame tools` GREEN 증명 완료.
- **Phase 2 ✅ 2026-06-04**: hive·cortex·index·matrix trust 이전 — 5개 서비스 전부 LIVE + 영속(`BLUEPRINT_ISSUER` compose/.env.local 기본값) + e2e(`axe <svc> tools`). claude.ai → Blueprint OP 이전 + frame/cortex 프록시 폐기는 미평가(잔여).
- **Phase 3**: 인가 중앙화(`ent` 클레임 + fine scope, 서비스가 customers.yaml 대신 토큰 grant 사용) + 감사 UI + headless device-code(RFC 8628, `B-axe-cli-device-code` — 미구현) + 키 회전 자동화.

## 미해결 / 결정 필요

- **issuer 도메인**: 현재 `blueprint.axellc.com` (NEXTAUTH_URL). axelabs.ai 도메인 이전 시 issuer 변경 = 발행된 토큰·서비스 신뢰설정 일괄 영향 → 이전 **전에** 확정하거나 `auth.axelabs.ai` 안정 alias 고정.
- **claude.ai 통합 시점**: claude.ai 커넥터를 Blueprint OP 뒤로 옮기면 per-service 프록시 폐기 가능. 단 claude.ai DCR redirect allowlist·Mcp-Session-Id 흐름 재검증 필요 (B-axe-cli 의 public 멀티스텝 403 함정과 연동).
- **인가 중앙화 범위**: entity grant 를 토큰에 심는 순간 customers.yaml 의 email→entity 가 Blueprint 로 이동 → 큰 마이그레이션. Phase 1 은 인증만, 인가는 그대로 두는 게 안전.

## 관련

- 결정: [D-axe-idp-1](/ops/decisions) (본 설계) · [D-axe-cli-1](/ops/decisions) (CLI·토큰모델) · [D-ops-14/15](/ops/decisions) (per-service 프록시 — 통합 대상)
- 현행 인증: [/architecture/auth](/architecture/auth) (3 경로 — Blueprint = 4번째 trusted issuer 로 합류)
- 레퍼런스 구현: frame `src/frame/mcp/oauth.py` (검증된 OAuth 2.1 AS + PKCE + DCR)
- 백로그: [B-axe-idp-1](/ops/backlog)

---

<!-- PAGE https://docs.axelabs.ai/architecture/playbooks -->

# Playbook 패턴 (AI session 던지기 표준 형식)

> docs.axelabs.ai 의 행위 단위 페이지 (셋업/배포/공지/복구) 가 사람과 AI 양쪽의 단일 entry point 가 되도록 하는 맨 위 prompt block + 본문 구조 표준. 새 playbook 작성 시 본 SSOT 따른다.

URL: https://docs.axelabs.ai/architecture/playbooks

# Playbook 패턴

docs.axelabs.ai 의 일부 페이지는 단순 reference 가 아니라 **행위 단위** (셋업 / 배포 / 공지 / 복구) 다. 이런 페이지는 사람이 직접 read 해서 따라가는 것 외에, **사용자가 자기 AI session 에 URL + 짧은 prompt 를 던져 step-by-step interactive 로 진행**시키는 방식이 표준이다 ([D-docs-playbook](../ops/decisions)).

> 본 페이지 = 새 playbook 작성 시 따를 형식의 SSOT. 형식 drift 가 곧 페이지마다 사용자 mental model 재학습 비용 = 패턴 가치 훼손이라 박제한다.

## 무엇이 playbook 이고 무엇이 아닌가

| 페이지 성격 | playbook? | 이유 |
|---|---|---|
| **셋업** (SSH 진입, vault setup, MCP connector 추가) | ✅ | 사용자가 단계 따라가야 끝남 |
| **배포** (release-flow, customer onboarding D-day) | ✅ | 운영자 손에서 N 명령 순차 실행 |
| **운영자 공지** (Teams DM broadcast, mail broadcast) | ✅ | 한 번에 N 사람 대상으로 행위 |
| **복구** (vault recovery, postgres restore) | ✅ | 사고 시 명령 순서 + 검증 매 step |
| **decision / 결정 기록** (D-ops-*) | ❌ | 사실 기록. 행위 트리거 아님 |
| **아키텍처/모델** (domains, data, artifacts) | ❌ | reference. 사용자가 행위로 변환 안 함 |
| **backlog / known-gaps / updates** | ❌ | 메타 운영 — 페이지가 entry point 지만 행위 단위 X |

판단 기준: "본 페이지를 끝까지 따라가면 사용자 환경 또는 외부 시스템 상태가 변하는가?" → 변하면 playbook.

## 표준 형식

### Frontmatter

```yaml
---
title: <행위 명사구 또는 짧은 페이지명>
description: <한 줄 — 행위 + 외부 dependency + 완료 기준. 본 페이지 fetch 한 AI 가 prereq 판단할 수 있게 명시>
playbook: true
---
```

`playbook: true` 는 machine-readable marker — 후속 build-time catalog 자동 생성 / search filter / 외부 agent 가 "행위 단위 페이지만" 골라낼 때 anchor. 본 SSOT 의 "현 playbook 목록" 표가 수동 인덱스, frontmatter 가 자동 인덱스의 단일 진실.

### Sidebar marker

해당 페이지의 `_meta.js` entry title 앞에 `⚡ ` prefix 추가 — Nextra sidebar 에서 사람이 페이지 열기 전 "이 페이지는 AI 던지기 가능한 행위 단위" 식별:

```js
// content/onboard/_meta.js (예)
export default {
  index: '신규 직원 가이드',                       // 안내, marker 없음
  'ssh-access': '⚡ SSH 로컬 작업',                // playbook
  'vault-setup': '⚡ Vault setup (KDF + 4 client)', // playbook
  troubleshooting: '문제 해결',                    // reference, marker 없음
}
```

### 본문 구조 (필수 순서)

```mdx
# <행위 명사구>

(선택) 1-2 문장 페이지 정체성 — 무엇을 하는 페이지인지, legacy 페이지가 있다면 cross-link.

## AI 요청 프롬프트

​```
<표준 prompt block — 다음 절 참고>
​```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- <권한 / 자격>
- <환경 / 머신 / 네트워크>
- <사전 자료 (email, key, manifest 등)>

## Step 1: <첫 단계>
## Step 2: ...

(또는 단계가 크면 `## Phase 1 (...)` / `## Phase 2 (...)` 패턴)

## 함정 정리

| # | 함정 | 우회 |
|---|---|---|
| 1 | <증상> | <대응> |

## 완료 후 (선택)

- <done criteria>
- <후속 회신 / Ship Log / 운영자 통보>
```

### 표준 prompt block 템플릿

코드 블록 안의 내용:

```
https://docs.axelabs.ai/<path> 따라 <행위 한 줄 요약> 해줘.

진행:
1. <환경/머신 진단 — OS, 기존 설치 여부, 권한>
2. <페이지 Prereq 확인 + 조건 분기 (해당 시 skip)>
3. 페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음
4. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
5. <완료 후 done criteria — 운영자 회신 / Ship Log / 검증 산출물>
```

**고정 element** (모든 playbook 동일):

- 첫 줄 = 페이지 URL + "따라" + 행위 + "해줘"
- step 3 = "페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음" (낱말 그대로)
- step 4 = "함정 발생 시 페이지 '함정 정리' 표 따라 우회" (낱말 그대로)

**가변 element**:

- step 1-2 = 행위에 따른 사전 진단 (운영자 broadcast 는 "Blueprint LIVE 확인" / SSH 셋업은 "OS 진단" 등)
- step 5 = 완료 기준 (Teams 회신 / Ship Log / 운영자 통보 등)

### 표준 꼬리 (prompt block 다음 2줄)

```
본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.
```

**낱말 그대로** 복붙. AI session 후보 4 개 순서 고정 (Claude Code · Cursor · ChatGPT 데스크탑 · Claude.app · 기타).

## 현 playbook 목록

표 = [`scripts/generate-playbook-catalog.mjs`](https://github.com/axelabs-ai/axelabs-docs/blob/main/scripts/generate-playbook-catalog.mjs) 가 frontmatter `playbook: true` 페이지 인덱싱해서 marker 사이 자동 채움. `package.json` 의 `prebuild` 가 자동 hook — `npm run build` 마다 갱신. ad-hoc 호출은 `npm run catalog`. **script idempotent** (변경 없을 때 file 안 만짐) 라 매 build 마다 working tree dirty 0. **본 표 직접 편집 X** — 새 playbook 추가 = 페이지 frontmatter 만, build (또는 catalog) 한 번 → 표 + JSON 갱신 → 결과 commit.

machine catalog = [public/playbooks.json](/playbooks.json) (count + URL + title + action + audience, deterministic, no timestamp).

{/* playbook-catalog:start */}
| Playbook | 행위 | 대상 |
|---|---|---|
| [AXE MCP connectors (claude.ai + Claude Code 자동 sync)](/onboard/claude-connectors) | claude.ai 의 Custom Connector 등록에 Bitwarden 브라우저 확장 + AXE Vault `MCP Connectors` collection 활용 | 직원 / customer 직원 |
| [Microsoft 365 connector](/onboard/m365-connector) | OneDrive · Outlook · Teams 통합 (Anthropic 제공) | 직원 / customer 직원 |
| [SSH 로컬 작업 (Claude Code / Cursor / 기타 AI session)](/onboard/ssh-access) | AXE macmini 에 SSH 진입해 로컬 작업하는 표준 절차 | 직원 / customer 직원 |
| [Vault setup — KDF rotation + 4 client + Bitwarden Authenticator](/onboard/vault-setup) | AXE Vaultwarden 의 SSO→MP unlock 정상화 (KDF rotation, 옛 user 만) + 데스크톱/Chrome/Mobile 3 client + Bitwarden Authenticator 표준 setup | 직원 / customer 직원 |
| [Cloudflared 재기동](/ops/runbook/cloudflared) | cloudflared 가 죽었거나 config 변경 시 5초 다운타임 절차 | 운영자 |
| [신규 Customer Onboarding](/ops/runbook/customer-onboarding) | 운영자 측 자동화 + 수동 touchpoints | 운영자 |
| [Frame DB 복구](/ops/runbook/db-recovery) | frame-postgres 손상/migration 사고/silent corruption 대응 | 운영자 |
| [Blue/Green Deploy](/ops/runbook/deploy) | frame 무중단 배포 절차 | 운영자 |
| [직원 퇴사](/ops/runbook/employee-offboarding) | 퇴사한 직원의 모든 access 차단 절차 | 운영자 |
| [신규 직원 등록](/ops/runbook/employee-onboarding) | customer admin 으로부터 신규 직원 추가 요청 받았을 때 운영자 절차 | 운영자 |
| [macmini 손실](/ops/runbook/macmini-loss) | customer macmini 도난/화재/완전 손실 시 1-day 복구 | 운영자 |
| [운영자 broadcast — Teams DM 으로 임직원 1:N 공지](/ops/runbook/operator-broadcast) | Blueprint `/api/admin/broadcast-dm` REST 로 bot identity (ai@axellc.com) → AXE 임직원 1:N Teams DM | 운영자 |
| [Release flow (axe ship)](/ops/runbook/release-flow) | 코드 변경 → 운영 반영까지의 release-gate | 운영자 |
| [Secret Rotation](/ops/runbook/secret-rotation) | 모든 비밀 회전의 단일 명령 — axe secret rotate | 운영자 |
| [Vaultwarden 복구](/ops/runbook/vault-recovery) | self-host vault 복구, OIDC 깨짐 대응, sso_nonce 수동 패치 | 운영자 |
{/* playbook-catalog:end */}

신규 playbook 추가 흐름 = (1) 페이지 frontmatter `playbook: true` + 본문 표준 형식 + sidebar `⚡ ` prefix → (2) `npm run build` (또는 `npm run catalog`) 한 번 실행 → 본 표 + JSON 자동 갱신 → (3) git commit 묶음.

## 함정 / drift 회피

| 함정 | 우회 |
|---|---|
| AI session 후보 나열 순서를 자기 임의로 바꿈 (예: Claude.app 을 첫 자리) | 본 SSOT 의 4 후보 순서 (Claude Code · Cursor · ChatGPT 데스크탑 · Claude.app) 낱말 그대로 |
| 꼬리 2줄을 1줄로 압축 (vault-setup·operator-broadcast 의 초기 drift) | 2줄 분리 유지 — 읽기 부담 ↓ + AI 가 첫줄 (후보 식별) 과 둘째줄 (행위 지시) 별도 cue 로 파싱 |
| `## AI 요청 프롬프트` 헤딩 변형 (옛 `🤖 AI 에 던질 prompt (...)` 잔존 / 다른 단어로 paraphrase) | 낱말 그대로. 사람 + AI 둘 다 visual anchor 로 사용 — 일치 안 하면 "이 페이지 playbook 인가?" 재판단 비용 |
| prompt block 안 첫 줄에 URL 안 적고 페이지 안에서 "위 페이지" 식 indirect 참조 | URL 명시 — AI 가 본 prompt 만 보고 페이지 fetch 가능해야 self-contained |
| step 3-4 의 표준 문구를 paraphrase ("각 step 따라가 줘" / "함정 표 보고" 등) | 낱말 그대로 — AI 가 페이지의 `## 함정 정리` 표를 anchor 로 매핑하는 cue |
| 페이지 본문에 prompt 안 step 과 실제 `## Step N` heading 의 번호 불일치 | prompt step 5 = 페이지의 마지막 행위, prompt 안 step N = 페이지 Step N 으로 1:1 매핑 권장 |

## 새 playbook 추가 체크리스트

신규 페이지가 위 "무엇이 playbook 인가" 판단으로 playbook 이면:

1. Frontmatter title + description + **`playbook: true`** 작성 (description 한 줄에 행위 + dependency + 완료 기준)
2. `## AI 요청 프롬프트` 헤딩 + code block + 표준 꼬리 2줄 복붙 — code block 안만 행위에 맞게 가변
3. `## Prereq` / `## Step N` 또는 `## Phase N` / `## 함정 정리` / `## 완료 후` 순서 — 누락 시 본 SSOT 표 한 줄로 reject
4. 본 페이지 (`architecture/playbooks`) 의 "현 playbook 목록" 표 = **script 자동 생성, 수동 편집 X** — `scripts/generate-playbook-catalog.mjs` 가 frontmatter `playbook: true` 페이지 인덱싱해서 marker 사이 표 + `public/playbooks.json` 갱신. `prebuild` 자동 hook 또는 `npm run catalog` (ad-hoc) → 결과 commit. script idempotent 라 build 마다 dirty 0
5. 해당 폴더의 `_meta.js` entry title 앞에 `⚡ ` prefix 추가 (sidebar marker)
6. 페이지가 운영자 행위면 `content/ops/runbook/`, 직원/customer 행위면 `content/onboard/` — 위치 혼동 시 sidebar 카테고리 가시성 ↓ + catalog audience 매핑 잘못

## 관련 결정

- 본 SSOT — [D-docs-playbook](../ops/decisions)
- backlog ritual — [/ops/backlog](/ops/backlog) (다른 entry point. playbook 페이지는 backlog 와 별 channel — playbook = 행위 트리거, backlog = 행위 큐)

---

<!-- PAGE https://docs.axelabs.ai/architecture/secrets -->

# 비밀 관리 — vault → 서비스 흐름

> 모든 서비스 비밀의 SoT 는 Vaultwarden. customers.yaml 매니페스트가 매핑 SSOT. axe ship 가 배포 직전 vault → env_file 동기화 강제.

URL: https://docs.axelabs.ai/architecture/secrets

# 비밀 관리 (D-ops-17)

> AXE 플랫폼의 모든 서비스 비밀 (DB password, OAuth client_secret, JWT signing key, 외부 API token) 은 **Vaultwarden 이 canonical store**. 서비스 컨테이너는 vault 를 직접 모르고, **`axe ship` 가 배포 직전 vault → env_file 로 동기화** 한 뒤 docker compose 가 env_file 을 읽음.

## 핵심 결정

| # | 결정 | 이유 |
|---|---|---|
| D-ops-9 | Vaultwarden = canonical secret store | 기존 결정 — Tier-1 vault |
| D-ops-17 | Deploy-time pull (runtime X) | runtime vault 호출은 blast radius + bootstrap 문제. deploy-time 만 의존성 발생, 서비스 코드는 vault 모름 |

## 데이터 흐름

```
┌──────────────┐                      ┌─────────────────────────────────────────┐
│ Vaultwarden  │ ← canonical SoT      │ /Users/axe/.axe/customers.yaml          │
│ (axe.axelabs │                      │   services.<svc>.secrets[]:             │
│  .ai/vault)  │                      │     - env: FRAME_DB_PASSWORD            │
└──────┬───────┘                      │       vault: "frame/axe/db-password"    │
       │                              │     - env: AZURE_FRAME_MCP_CLIENT_SECRET│
       │ bw CLI                       │       vault: "frame/axe/oauth-..."      │
       │ (BW_SESSION                  │       rotation_external: azure          │
       │  from Keychain)              └─────────────────────┬───────────────────┘
       │                                                    │ (manifest read)
       ▼                                                    ▼
┌──────────────────────────────────────────────────────────────────┐
│ axe ship <service>  (release-gate)                               │
│   step 1: docs-check                                             │
│   step 2: branch + clean                                         │
│   step 3: commits to push                                        │
│   step 4: confirm                                                │
│   step 5: git push                                               │
│   step 6: deploy                                                 │
│     ├─ pre-deploy [a]: axe secret check <service>   ← abort 시 stop│
│     ├─ pre-deploy [b]: axe secret pull <service>    ← env_file write│
│     └─ docker compose up -d ...     (env_file = pulled content) │
└──────────────────────────────────────────────────────────────────┘
       │
       ▼
┌────────────────────────────────────────┐
│ /Users/axe/<repo>/.env(.local)        │ ← AUTO-GENERATED, mode 600,
│   FRAME_DB_PASSWORD="..."             │   git-ignored
│   AZURE_FRAME_MCP_CLIENT_SECRET="..." │
│   ...                                  │
└────────────────────────────────────────┘
       │
       ▼
   docker container env (frame-mcp-blue, etc.)
```

## 매니페스트 스키마

`customers.yaml` 의 `customers.CUSTOMER.services.SERVICE.secrets[]`:

```yaml
services:
  frame:
    env_file: "/Users/axe/frame/.env.local"   # axe secret pull 의 write target
    secrets:
      - env: FRAME_DB_PASSWORD               # 환경변수 이름 (docker-compose 가 보는)
        vault: "frame/axe/db-password"       # Bitwarden item name (axe secret get 가 보는)
      - env: AZURE_FRAME_MCP_CLIENT_SECRET
        vault: "frame/axe/oauth-client-secret"
        rotation_external: azure              # 회전 시 Azure portal 갱신 필요
      # ...
```

| 필드 | 필수 | 의미 |
|---|---|---|
| `env_file` | ✓ | `axe secret pull` 가 작성할 절대 경로. docker-compose.yml 의 `env_file:` 지시자와 일치 |
| `secrets[].env` | ✓ | 환경변수 이름 (서비스 코드가 `os.getenv("...")` 로 보는 이름) |
| `secrets[].vault` | ✓ | Vaultwarden item 이름. 컨벤션: `SERVICE/CUSTOMER/SHORT` (예: `frame/axe/db_password`) |
| `secrets[].rotation_external` | ✗ | 외부 시스템 식별자 (`azure`/`github`/`meta`/`anthropic`/`naver`/`slack`). 설정 시 `axe secret rotate` 가 portal URL 안내 |
| `bootstrap_only` | ✗ | `true` 면 service 자체가 vault 인 경우 (vault 가 자기 자신 못 읽음 — chicken-and-egg). check/pull skip |

## CLI 명령

| 명령 | 동작 |
|---|---|
| `axe secret check SERVICE` | 매니페스트 vs vault 보유 비교 → 누락 출력. 누락 시 exit 1 |
| `axe secret pull SERVICE` | 매니페스트 순회 → bw 로 fetch → `env_file` atomic write (mode 600) |
| `axe secret push ENV_NAME --service SVC --value VALUE` | 매니페스트로 vault 경로 lookup → 신규 생성 or password 필드 갱신. 대형/PEM/파일-소스 비밀은 `--value-stdin` 으로 stdin 주입 (값이 argv/ps 에 안 뜸): `grep ^KEY= .env \| cut -d= -f2- \| axe secret push KEY --service SVC --value-stdin` |
| `axe secret send ENV_NAME --service SVC [--to RECIP]` | 매니페스트 lookup → vault GET → `bw send` 로 1회용 링크 생성 → URL stdout. 기본 `-d 1 -a 1 --hidden`. 사람에게 전달 전용 |
| `axe secret rotate ENV_NAME --service SVC` | 새 값 (외부 provider 입력 or 자동 생성) → vault PUT → pull → ship 트리거 |
| `axe secret get VAULT_NAME` | 단건 조회 (저레벨, 기존 명령) |
| `axe secret list` | vault 전체 item 표 (값 출력 X) |
| `axe secret status` | bw session 상태 확인 |

`--customer` 기본값 `axe`. realchoice 합류 시 명시.

## 매니페스트 — 현재 상태 (axe customer)

| service | env_file | 비밀 개수 |
|---|---|---|
| frame | `/Users/axe/frame/.env.local` | 9 (DB password, JWT, OAuth client_secret, PII passphrase × 2, Claude OAuth, 롯데카드 포털 ID/PW — host-only 스크래퍼 [D-frame-lottecard-scraper](/ops/decisions)) |
| hive | `/Users/axe/hive/.env.local` | 5 (DB password, JWT, PII passphrase × 2, OAuth client_secret) — frame 동일. confidential client (PKCE + secret, accessTokenVersion=2, isFallbackPublicClient=true) |
| blueprint | `/Users/axe/blueprint/.env` | 14 (DB, agent secret, Anthropic admin, OAuth, NextAuth, GH token, cron, frame token, **OIDC 서명키 `blueprint/axe/oidc-signing-key` — D-axe-idp-1 RS256 base64 PKCS8**, ...) |
| stream | `/Users/axe/stream/.env` | 2 (DB, Truvia master key) |
| magnet | `/Users/axe/magnet/.env` | 10 (DB, HMAC, Meta × 3, Naver × 3, Slack, Threads × 2) |
| matrix | `/Users/axe/matrix/.env.local` | 3 (DB password, JWT secret, console API token) — [D-matrix-1](/ops/decisions) |
| vault | `/Users/axe/.axe/vault/.env` | 1 (Vaultwarden 자기 자신 OAuth client_secret) — `bootstrap_only: true` |

합계 **42 개 비밀** 매니페스트 등재. (현재 vault 안 실제 item 수와 매니페스트 양은 별개 — `axe secret check SVC` 로 갭 확인.)

> **gate (착수 예정, 아직 미배포 — 위 표 미포함)**: gate 가 배포되면 `services.gate.secrets[]` 에 **e-sign 서버 서명키** `GATE_ESIGN_KEY_PEM`(vault `gate/axe/esign-signing-key`, RSA-2048 PKCS8 PEM — blueprint OIDC 서명키 패턴과 동형) + 짝 인증서 `GATE_ESIGN_CERT_PEM`(공개 X.509, 비밀 아님이라 env/파일이면 충분) 등재 필요 ([D-gate-5](/ops/decisions) gate-native CAdES-T 서명엔진, [/architecture/governance](/architecture/governance) §6). 키 디렉터리 지정 변형 = `GATE_ESIGN_KEY_DIR`. `GATE_TSA_URL`(RFC3161 TSA, default DigiCert / 한국 prod Koscom·CrossCert) = 비밀 아님(공개 엔드포인트). ⚠️ 서명키 분실 = 전 과거 봉인 검증불가 → **DR/escrow** 필수(하드닝, [/architecture/governance](/architecture/governance) §9). dev = ephemeral key (vault 불요).

## 신규 customer 매니페스트 추가 (realchoice 등)

> **현재 상태 (2026-05-23)**: `customers.yaml` 의 `services:` 섹션은 **`axe` customer 만 등재**. realchoice 는 customer 메타블록 (legal_name, tailscale_host, sso.apps 등) 만 있고 secrets 매니페스트 부재. 즉 `axe secret push --customer realchoice` 가 manifest lookup 실패. 이 갭이 D-day "1-shot onboard" 의 가장 큰 막힘 → [B-onboard-customers-add](/ops/backlog) + [B-onboard-azure-pack](/ops/backlog).

신규 customer 합류 시 `customers.yaml` 의 `services:` 섹션에 customer 별 슬롯을 미리 등재해야 `axe secret push` 가 동작합니다. realchoice 템플릿:

```yaml
services:
  frame:
    realchoice:
      env_file: "/Users/realchoice/frame/.env.local"
      secrets:
        - env: FRAME_DB_PASSWORD
          vault: "frame/realchoice/db-password"
        - env: FRAME_JWT_SECRET
          vault: "frame/realchoice/jwt-secret"
        - env: AZURE_FRAME_MCP_CLIENT_SECRET
          vault: "frame/realchoice/oauth-client-secret"
          rotation_external: azure
        - env: FRAME_PII_PASSPHRASE_REALCHOICE
          vault: "frame/realchoice/pii-passphrase-realchoice"
        - env: CLAUDE_CODE_OAUTH_TOKEN
          vault: "frame/realchoice/claude-oauth"
  blueprint:
    realchoice:
      env_file: "/Users/realchoice/blueprint/.env"
      secrets:
        - env: AZURE_AD_CLIENT_SECRET
          vault: "blueprint/realchoice/azure-client-secret"
          rotation_external: azure
        - env: NEXTAUTH_SECRET
          vault: "blueprint/realchoice/nextauth-secret"
        # ... (axe customer 의 12 개 패턴 동일 복제)
  vaultwarden:
    realchoice:
      env_file: "/Users/realchoice/.axe/vault/.env"
      bootstrap_only: true
      secrets:
        - env: AZURE_VAULTWARDEN_CLIENT_SECRET
          vault: "vaultwarden/realchoice/oauth-client-secret"
          rotation_external: azure
  hive:
    realchoice:
      env_file: "/Users/realchoice/hive/.env.local"
      secrets:
        - env: HIVE_DB_PASSWORD
          vault: "hive/realchoice/db-password"
        # ... axe 동일 패턴
```

> **`axe customers add {customer}` 명령** ([B-onboard-customers-add](/ops/backlog)) 가 이 템플릿을 자동 생성하도록 만들면 운영자 손작업 단계 2 제거 가능. customer IT 회신 (8 개 값) JSON 한 덩어리를 받아 `axe customer ingest {customer} azure-pack.json` 한 줄에 (a) customers.yaml 슬롯 작성 + (b) 3 개 client_secret 을 vault 로 push 까지 묶는 게 [B-onboard-azure-pack](/ops/backlog) 의 본질.

## 회전 (rotation) 흐름

```
axe secret rotate AZURE_FRAME_MCP_CLIENT_SECRET --service frame

[1/4] external rotation required (provider: azure)
      portal: https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/...
      action: rotate secret in the provider, then paste the NEW value below.
              the OLD value will remain valid until step 4 (rotation overlap window).
      new value: ********

[2/4] writing new value to vault item 'frame/axe/oauth-client-secret'
      ✓ updated existing vault item

[3/4] axe secret pull frame
      ✓ frame: pulled 7 secrets → /Users/axe/frame/.env.local (mode 600)

[4/4] deploy with new secret
      run `axe ship frame` now? (yes/no): yes
      → frame blue/green swap with new secret

Note: in the azure portal, REVOKE the OLD secret value now that the new
      one is verified working in production. Both are valid until you delete the old.
```

회전 순서가 중요:

1. **외부 provider 먼저** — Azure 가 새 값 발급 → 운영자가 복사
2. **vault PUT** — Bitwarden 에 새 값 저장 (이전 값 덮어쓰기)
3. **env_file refresh** — `axe secret pull`
4. **service redeploy** — `axe ship` (blue/green = 무중단)
5. **OLD secret revoke** — Azure portal 에서 이전 값 삭제 (overlap window 닫기)

## Pull 동작 — merge-mode (D-ops-18 의 결과)

`axe secret pull SERVICE` 는 env_file 을 **머지** 합니다:

- 매니페스트의 키 → vault 값으로 **in-place update**
- 매니페스트 외 키 / 주석 / 빈 줄 → **그대로 보존**
- 매니페스트엔 있는데 파일엔 없는 키 → 파일 끝에 append

→ 비밀 외 config (예: `AZURE_AD_CLIENT_ID`, `NEXTAUTH_URL`, `DATABASE_URL` 등 운영자가 hand-maintain 하는 항목) 가 pull 호출로 사라지지 않음. **초기 구현은 전체 덮어쓰기였고 2026-05-21 첫 blueprint pull 에서 9개 config 가 wipe 되는 사고 발생 → 코드 패치 + D-ops-18 등재**.

출력 예:
```
✓ blueprint: merged 13 secrets into /Users/axe/blueprint/.env (13 updated, 0 added, non-managed lines preserved)
```

## Rotation — az CLI 기반 (D-ops-19)

Azure 의 `client_secret` 회전은 6 단계 az cli 자동화. Portal UI 0 회 (단, app 의 **Owner** 가 운영자로 박혀 있어야 함):

```bash
APP_ID=<app's appId>  # e.g. Frame MCP: 137fc0ef-...
OLD_KEY_ID=$(az ad app credential list --id $APP_ID --query "[?starts_with(hint,'<old hint>')].keyId | [0]" -o tsv)

# 1. Azure 새 secret 추가 (--append, OLD 유지 = overlap window)
NEW=$(az ad app credential reset --id $APP_ID \
  --display-name "rotated <date>" --years 2 --append \
  --query password -o tsv)

# 2. vault PUT
axe secret push <ENV_NAME> --service <svc> --value "$NEW"

# 3. pull (merge — config 보존)
axe secret pull <svc>

# 4. 무중단 swap
axe deploy <svc> axe --apply   # frame / hive
# 또는
axe blueprint upgrade axe --apply  # blueprint

# 5. 검증 — 컨테이너 env 의 새 secret prefix 가 OLD 와 다른지
docker exec <active-container> env | grep <ENV_NAME>

# 6. 운영 안정 확인 후 OLD revoke
az ad app credential delete --id $APP_ID --key-id $OLD_KEY_ID
```

**App Owner 전제조건**: portal-등록 app 은 default 로 owner 없음 → az cli 권한 X. 신규 az cli 등록 app 은 호출자가 owner 자동 박힘. 기존 portal-등록 app 들은 portal Owners 탭에서 운영자 (`ai@axellc.com`) 명시 추가 필요. 본 플랫폼 현황:

| App | appId | Owner |
|---|---|---|
| frame_mcp | `137fc0ef-...` | ai@axellc.com (2026-05-21 추가) |
| hive_mcp | `b7ead15d-...` | ai@axellc.com (등록 시 자동) |
| blueprint_mcp | `482598f7-...` | ai@axellc.com (등록 시 자동) |
| Blueprint Graph (better-auth) | `2b222356-...` | ai@axellc.com (2026-05-21 추가) |
| vaultwarden | `9d0dc49b-...` | ai@axellc.com (2026-05-21 추가) |

## 사람에게 전달 — Bitwarden Send

`axe secret get` 의 결과는 vault → 디스크/컨테이너 경로용. **사람 (신규 직원, customer admin) 에게 보낼 때는 평문 절대 금지** — Teams DM, 이메일, 위키 모두 영구 보존되는 채널. Vaultwarden 의 1회용 링크 (Bitwarden Send) 로 전달한다.

### `axe secret send` (권장)

```bash
axe secret send <ENV_NAME> --service <svc> [--to <recipient>]
```

매니페스트 lookup (`customers.yaml services.<svc>.secrets[].env → .vault`) → bw GET → bw send 파이프. stdout 에 Send URL 만 (상태 메시지는 stderr) — `axe secret send ... | pbcopy` 로 클립보드 직행. 기본값:

| 플래그 | 의미 | 기본값 |
|---|---|---|
| `-d N` / `--days N` | N일 후 자동 삭제 | `1` |
| `-a N` / `--access N` | 최대 N회 열람 후 무효 | `1` |
| `--to <라벨>` | Send name 에 `(라벨)` 추가 (운영자 추적용, 실 ACL 아님) | 없음 |
| `--password <p>` | 추가 비밀번호 잠금 | 없음 — 외부 customer 대상 시 권장 |
| `--customer <c>` | customer 식별 (기본 `axe`) | `axe` |

stdin 으로 값 주입 → argv 에 secret 노출 0 (ps, shell history 안 박힘).

```bash
# 예: 한진우에게 Blueprint MCP secret 전달
axe secret send AZURE_BLUEPRINT_MCP_CLIENT_SECRET --service blueprint --to jinwoo
# ✓ Send created: blueprint AZURE_BLUEPRINT_MCP_CLIENT_SECRET (jinwoo)
#   expires in 1d / max 1 access(es)
# https://vault.axelabs.ai/#/send/abc123.../def456...
```

### 다인 × 다 secret 배치

`-a 1` 이면 한 사람이 열면 끝나므로 **(수신자, secret) 1쌍당 링크 1개**:

```bash
for who in taehun jinwoo soohun; do
  for env in AZURE_BLUEPRINT_MCP_CLIENT_SECRET AZURE_HIVE_MCP_CLIENT_SECRET; do
    svc=$(echo $env | awk -F_ '{print tolower($2)}')
    echo "=== $who / $env ==="
    axe secret send $env --service $svc --to $who
  done
done
```

위 6 링크가 stdout 에, 각 헤더는 stderr 로 분리 출력. 운영자 본인 (soohun) 도 동일하게 새 Custom Connector 등록 흐름이 필요하면 포함.

### 자동 발사 — `/api/admin/broadcast-dm`

`axe secret send` 출력 URL 을 운영자가 Teams 에 손으로 paste 하지 말고 **Blueprint bot (ai@axellc.com) 이 1:1 DM 으로 직접 발사**. 엔드포인트 [`POST /api/admin/broadcast-dm`](https://blueprint.axellc.com/api/admin/broadcast-dm) 이 each email → AAD lookup → `POST /chats` (oneOnOne, Graph idempotent) → `POST /chats/\{id\}/messages` 수행.

```bash
# 1. URL 발급 (이미 `/tmp/sends.txt` 로 캐시했다고 가정)
# 2. 수신자별 메시지 합성 + DM 발사 (예: 강태훈 한 명)
CRON=$(grep -E "^CRON_SECRET=" /Users/axe/blueprint/.env | cut -d= -f2-)
URL_BP=$(grep "^taehun|blueprint|" /tmp/sends.txt | cut -d'|' -f3)
URL_HV=$(grep "^taehun|hive|" /tmp/sends.txt | cut -d'|' -f3)

TEXT="태훈님, Blueprint + Hive Custom Connector 등록 부탁드립니다 ...
Blueprint Secret: $URL_BP
Hive Secret:     $URL_HV"

curl -s -X POST http://localhost:3100/api/admin/broadcast-dm \
  -H "Authorization: Bearer $CRON" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg e taehun.kang@axellc.com --arg t "$TEXT" \
        '{emails:[$e], text:$t, contentType:"text"}')"
# → {"summary":{"total":1,"sent":1,...}, "results":[{...,"chatId":"19:...","messageId":"..."}]}
```

**같은 텍스트를 N명에게 broadcast**: `emails:[a,b,c]` 한 호출. 다른 텍스트면 N 호출 (위 패턴 반복).

| 필드 | 의미 |
|---|---|
| **Endpoint** | `POST /api/admin/broadcast-dm` (Blueprint, host `:3100` 또는 `blueprint.axellc.com`) |
| **Auth** | `Authorization: Bearer $CRON_SECRET` (Blueprint `.env`). NextAuth 세션 불필요 |
| **Body** | `\{ emails: string[], text: string, contentType?: "text" \| "html" \}` 기본 `"text"` (HTML escape 안전) |
| **AAD lookup** | `User.aadObjectId` (NextAuth 첫 sign-in 시 자동 채워짐). 없으면 `skipped` |
| **Idempotent** | Graph `POST /chats` 가 같은 (bot, target) 쌍이면 같은 chat id 반환 → 재호출해도 새 채팅방 안 생김 |
| **Self-DM 차단** | target AAD = bot AAD 면 `skipped` (bot=ai@axellc.com 본인은 호출 불가) |

상세 코드: `/Users/axe/blueprint/src/app/api/admin/broadcast-dm/route.ts`.

#### 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 수신자가 메시지 보면 **sender = AI (ai@axellc.com)** 이라 사람-요청 같지 않음 | "왜 AI 가 connector 등록 시킴" 혼동 | 메시지 본문 첫 줄에 운영자명 명시 ("수훈 대표 요청으로 ...") |
| `User.aadObjectId` 비어 있는 신규 직원 → `skipped` | DM 미발사, 운영자 로그 확인 안 하면 모름 | NextAuth Blueprint 첫 sign-in 1회 선행. 또는 응답 JSON 의 `summary.skipped > 0` 가드 |
| `CRON_SECRET` env 미설정 | 503 응답 | Blueprint `.env` 의 `CRON_SECRET` 확인. Phase 2 deploy 에서 자동 생성됨 |

### 웹 UI 대안

`https://vault.axelabs.ai` 로그인 → 좌측 **Send** → **+ New Send** → Type: Text, Text: secret 붙여넣기, Deletion: 1 day, Maximum Access Count: 1, Hide text by default ✓ → Save → **Copy link**. CLI 가 막혔거나 매니페스트 외 임시 비밀에만 사용.

### 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `bw send` 를 raw 로 호출하면서 `axe secret get` 에 `-n` 누락 | trailing `\n` 이 base64/URL 인코딩 시 secret 변형 → OAuth 거부 | `axe secret send` 사용 (내부에서 stdin 으로 처리) |
| Send URL 자체를 다시 위키/메일에 영구 보존 | 1회 사용 후 URL 무효지만 메타데이터 (라벨) 노출 | URL 은 1회용 채널 (DM, SMS) 만 사용 |
| `-d` 너무 길게 (예: `-d 30`) | 수신자가 잊고 안 받으면 secret 이 30일간 노출면 유지 | `-d 1` 기본, 수신 확인 후 `bw send delete <id>` |
| 수신자가 받기 전에 운영자 본인이 열어버림 | `-a 1` 소진 → 수신자 재발급 필요 | URL 검증 X — 발급 후 바로 송부, 수신자 동의 확인 후 만 |
| Send 만든 직후 `bw sync` 안 한 두 번째 macmini 에서 안 보임 | revoke 가 한쪽에만 적용 | 운영자는 한 기기에서만 Send 관리, 또는 매 작업 후 `bw sync` |
| vault locked 상태 (timeout) | `axe secret send` 가 시작 시 status 검사 → "vault is locked" 명시 + unlock 명령 안내 | `axe vault unlock` → Keychain 갱신. **TTY 없는 에이전트/cron 컨텍스트면 osascript 다이얼로그 자동 팝업** (운영자가 master password 입력) — 더 이상 "운영자가 터미널에서 직접" punting 불필요 (2026-06-04 root-cause fix). `--gui` 강제 / `--tty` 레거시 프롬프트 |
| bw locked 상태에서 raw `bw get password X` 직접 호출 | interactive prompt 시도 → `ERR_USE_AFTER_CLOSE` crash + **exit 0 + 빈 stdout** (misleading) | `axe secret send`/`get` 만 사용 — pre-check 가 status 가드 |
| **bw 2025.7.0 (D-ops-28 다운그레이드 line) 의 `bw send` 가 옵션 (`-d` / `-a` / `-n` / `--hidden`) 함께 주면 stdin pipe 거부** — `echo X \| bw send -d 1 -a 1 -n "..."` → `error: missing required argument 'data'`. `--help` 의 `echo "text" \| bw send` 예시는 **옵션 0 인 호출에만** 동작 | raw `bw send` 사용한 1세대 `axe secret send` 가 exit 1 로 죽음 (2026-05-23 발견, 1세대 라이브 첫 호출 시) | 2세대 구현 = `bw send create` 서브커맨드 + base64-encoded JSON template 을 stdin 으로 (`\{type:0, name, deletionDate, maxAccessCount, text:\{text, hidden\}, password\}`) — encoded blob 도 stdin 이라 argv 노출 0. `accessUrl` 필드 parse 해서 반환 |

## 운영자 → vault 비밀 입력 패턴 (osascript hidden-dialog)

운영자가 **외부에서 발급받은 비밀 (PAT, API key, OAuth client_secret, SaaS token)** 을 vault 에 한 번에 영구 저장해야 할 때의 표준 패턴. [D-ops-40](/ops/decisions) axe.3 release (2026-05-26) GHCR PAT 보관 시 정착.

> **같은 osascript 다이얼로그 기법이 vault *unlock* 에도 적용됨** (2026-06-04): `axe vault unlock` 은 TTY 가 없으면 (Claude Code / cron / CI) 자동으로 hidden-text 다이얼로그를 띄워 master password 를 받아 `bw unlock --passwordenv` 로 unlock → BW_SESSION 을 Keychain 에 저장. 덕분에 **어느 에이전트 세션이든 한 명령으로 vault unlock 을 트리거**할 수 있고 운영자는 팝업에만 답하면 됨 (master password 는 argv/ps/history 어디에도 안 남음). 근인: 기존 `bw unlock --raw` 는 프롬프트에 TTY 가 필요해 non-TTY 호출자가 unlock 불가 → 매번 운영자에게 punting 했음.
>
> **파일/대형/PEM 비밀**(예: 플랫폼 OIDC RS256 서명키)은 다이얼로그(single-line) 대상이 아니므로 `... | axe secret push <ENV> --service <svc> --value-stdin` 으로 stdin 주입 (값이 argv/ps 에 안 뜸).

### 원칙

| 원칙 | 구현 |
|---|---|
| 비밀 값 = AI context 미진입 | bash subprocess 안에서만 env var, AI 가 받는 output 은 `✓ saved/✗ failed` 만 |
| shell history 미기록 | `osascript display dialog` (zsh history 우회) |
| 화면 / 스크롤백 미노출 | `hidden answer` 옵션 |
| clipboard 미사용 | dialog → 직접 env var (clipboard hop 없음) |
| TTY 불필요 | macOS Apple Events 로 GUI dialog — `forkpty: Device not configured` 환경에서도 동작 |
| 저장처 단일 SoT | AXE Vaultwarden organization collection (keychain 금지 — [D-ops-ops-17](/ops/decisions) + [B-frame-keychain-to-vault](/ops/backlog)) |
| 메모리 즉시 정리 | bash subprocess 종료 시 env var 소멸 + 명시 `unset` |
| idempotent | 같은 name 으로 재실행 시 UPDATE (overwrite), 없으면 CREATE |

### 한 블록 (복붙 → argument-pack 만 수정)

```bash
# === argument-pack: 이 부분만 task 별로 갱신 ===
ITEM_NAME='<bw-item-name>'              # 예: ghcr-axelabs-ai-pull-pat
COLLECTION_ID='<organization-collection-uuid>'  # bw list collections --organizationid <ORG> | jq 로 확인
ORG_ID='<organization-uuid>'            # 예: 0c5d8bbd-ad85-42b4-8b8a-2849031981b1 (AXE)
LOGIN_USERNAME='<username-or-empty>'    # 예: axe-labs-ai
LOGIN_URI='<service-url-or-empty>'      # 예: https://ghcr.io
DIALOG_PROMPT='<운영자에게 보여줄 한 줄 설명>'
DIALOG_TITLE='<dialog 타이틀 — AXE Vault 일관성>'
NOTES_HINT='<짧은 용도 + rotation 주기>'
# ============================================

SECRET=$(osascript \
  -e "display dialog \"${DIALOG_PROMPT}\" default answer \"\" with hidden answer with title \"${DIALOG_TITLE}\" buttons {\"Cancel\",\"OK\"} default button \"OK\"" \
  -e 'text returned of result' 2>&1)
RC=$?
if [ $RC -ne 0 ] || [ -z "$SECRET" ]; then echo "DIALOG_CANCELLED_OR_EMPTY rc=$RC"; exit 1; fi

export BW_SESSION="$(security find-generic-password -s 'axe.vault.session' -w 2>/dev/null)"
if [ -z "$BW_SESSION" ]; then echo "NO_SESSION_IN_KEYCHAIN"; exit 1; fi

STATUS=$(bw status --session "$BW_SESSION" --raw 2>&1 | jq -r '.status' 2>/dev/null)
if [ "$STATUS" != "unlocked" ]; then echo "SESSION_NOT_UNLOCKED (run: bw unlock --raw)"; exit 1; fi

bw sync --session "$BW_SESSION" >/dev/null 2>&1

EXISTING=$(bw list items --organizationid "$ORG_ID" --session "$BW_SESSION" 2>/dev/null \
  | jq -r --arg n "$ITEM_NAME" '.[] | select(.name==$n) | .id' | head -1)

if [ -n "$EXISTING" ]; then
  bw get item "$EXISTING" --session "$BW_SESSION" 2>/dev/null | jq \
    --arg secret "$SECRET" --arg today "$(date +%Y-%m-%d)" --arg hint "$NOTES_HINT" \
    '.notes="\($hint) Updated: \($today)." | .login.password=$secret' \
    | bw encode | bw edit item "$EXISTING" --session "$BW_SESSION" >/dev/null \
    && echo "✓ UPDATED $ITEM_NAME ($EXISTING)"
else
  bw get template item | jq \
    --arg name "$ITEM_NAME" --arg org "$ORG_ID" --arg col "$COLLECTION_ID" \
    --arg secret "$SECRET" --arg today "$(date +%Y-%m-%d)" --arg hint "$NOTES_HINT" \
    --arg user "$LOGIN_USERNAME" --arg uri "$LOGIN_URI" \
    '.name=$name | .notes="\($hint) Issued: \($today)." | .organizationId=$org | .collectionIds=[$col]
     | .login.username=$user | .login.password=$secret
     | (if $uri == "" then . else .login.uris=[{"uri":$uri}] end)' \
    | bw encode | bw create item --session "$BW_SESSION" 2>/dev/null | jq -r '.id' \
    | xargs -I{} echo "✓ CREATED $ITEM_NAME ({})"
fi

unset SECRET
```

### 호출 시 운영자 액션 (5 단계)

1. 비밀 발급처 (예: https://github.com/settings/tokens) 에서 비밀 생성 + 화면에 표시된 값 복사
2. 위 블록 실행 (운영자 본인 터미널 OR Claude Code 의 Bash tool 둘 다 가능)
3. macOS native dialog 팝업 → hidden-text 필드에 비밀 붙여넣기 → OK
4. 결과 = `✓ CREATED <name> (<bw-item-id>)` 또는 `✓ UPDATED <name> (<bw-item-id>)`
5. `pbcopy < /dev/null` 로 clipboard 클리어

이후 자동화는 `bw get password <name> --session "$BW_SESSION"` 한 줄로 꺼내씀.

### AI agent 호출

Claude Code 세션은 `vault-secret-capture` skill 로 같은 패턴 자동 적용 (description 매칭 기반 자동 발견). 운영자가 "vault 에 PAT 저장해줘" 만 해도 위 블록을 argument-pack 채워서 실행 — 비밀 값은 dialog 통해서만 받음 (AI context 미통과).

### 실 적용 예 — D-ops-40 GHCR PAT

```text
ITEM_NAME      = ghcr-axelabs-ai-pull-pat
COLLECTION_ID  = 1d794d29-f127-4602-b8cb-5ce8a731cf7f  (Platform — Service Secrets)
ORG_ID         = 0c5d8bbd-ad85-42b4-8b8a-2849031981b1  (AXE)
LOGIN_USERNAME = axe-labs-ai
LOGIN_URI      = https://ghcr.io
NOTES_HINT     = GHCR push/pull. axe-macmini + customer macmini docker login. Rotate 90d.
```

이후 사용: `bw get password ghcr-axelabs-ai-pull-pat | docker login ghcr.io -u axe-labs-ai --password-stdin`

### 함정 (이 패턴 한정)

| 함정 | 결과 | 회피 |
|---|---|---|
| collection name 의 em-dash (`Platform — Service Secrets`) 잘못 hyphen 으로 lookup | name 검색 실패 | ID 직접 사용 (`COLLECTION_ID=...uuid...`) |
| `axe.vault.session` Keychain entry 부재 | NO_SESSION_IN_KEYCHAIN | `bw unlock --raw \| security add-generic-password -s 'axe.vault.session' -a "$(whoami)" -w "$(cat)" -U` |
| 줄바꿈 포함 secret (PEM, RSA private key) | dialog 가 single-line | 다른 패턴 필요 (file path → vault attachment, 별 skill) |
| dialog OK 가 아닌 `Cancel` / 빈 입력 | DIALOG_CANCELLED_OR_EMPTY | 정상 처리, exit 1 로 정지 (재실행 가능) |
| customer-side 비밀을 AXE vault 에 저장 | sovereignty 위반 | customer 측이 자기 vault 에 자기가 저장 (같은 패턴 customer macmini 에서 실행) |

### 향후 확장

- `axe secret prompt-store <name> --collection X --uri ... --username ...` CLI subcommand 로 한 줄 명령화 (backlog: B-axe-secret-prompt-store-cli)
- 다중 secret 동시 입력 (예: client_id + client_secret 쌍) — 현재는 별 호출 2회
- 줄바꿈 포함 secret — file path 받아서 vault attachment 으로 저장하는 별 skill

## SSH 환경에서 vault 비밀 주입 (keychain-free raw-bw)

> 위 osascript hidden-dialog 패턴은 **GUI 세션**(콘솔/원격 데스크톱)을 전제로 한다. 그러나 이 머신 = AXE 의 Mac mini 이고 **Claude Code 세션은 SSH(loopback) 위에서** 돈다 — 운영자는 Windows 에서 `ssh axe@100.127.210.30` (Tailscale) 로 접속한다. macOS 는 **SSH 세션이 GUI login keychain 에 쓰는 것을 거부**한다 ("User interaction is not allowed"). 그래서 SSH 컨텍스트에서 vault 에 비밀을 *넣을* 때는 **keychain 을 전혀 안 쓰는 raw-bw 경로**를 쓴다. ([D-ops-44](/ops/decisions), `/Users/axe/CLAUDE.md` 강제 규칙.)

### 금지 (SSH 에서 전부 실패)

| 금지 | 이유 (SSH 에서 깨지는 메커니즘) |
|---|---|
| 운영자에게 `axe vault unlock` 시키기 | unlock 의 keychain-cache 단계가 SSH 세션에서 crash |
| `axe secret push` / `pull` / `check` 로 비밀 PUT | 내부 `_vault_env` 가 keychain 세션만 읽음 (`security find-generic-password -s axe.vault.session -a ai@axellc.com`) → SSH 에선 "vault session not found" |
| osascript `display dialog` | GUI 다이얼로그 = 원격/Windows 운영자에게 안 보임. 운영자-타이핑 비밀은 `read -rs` 로 받을 것 |

### 정답 = keychain-free raw-bw (운영자가 자기 셸에서 직접)

운영자가 **자기 인터랙티브 셸** (Windows `ssh axe@100.127.210.30` 또는 Mac 터미널) 에서 직접 실행한다. 에이전트는 스크립트를 **ASCII-only · 주석 없음 · `bw unlock` 을 단독 한 줄**로 공급한다 — 한 블록으로 붙여넣으면 unlock 프롬프트가 바로 다음 줄을 비밀번호로 삼켜버리기 때문이다.

1. **private CA 지정** (필수):

```bash
export NODE_EXTRA_CA_CERTS=/Users/axe/.axe/vault/certs/rootCA.pem
```

2. **unlock — 반드시 자기 단독 줄에서** (master-pw 프롬프트):

```bash
export BW_SESSION="$(bw unlock --raw)"
```

TTY-flaky 환경 폴백 (프롬프트가 안 뜨거나 깨질 때):

```bash
read -rs PW; export BW_SESSION="$(BW_PASSWORD="$PW" bw unlock --passwordenv BW_PASSWORD --raw)"; unset PW
```

3. **Login item 생성/갱신** (raw `bw create` / `bw edit`), 그다음 `bw sync` → `unset BW_SESSION`. 항목 매핑:

| bw 필드 | 값 |
|---|---|
| **name** | `customers.yaml` 의 `services.<svc>.secrets[].vault` 경로 (예 `gate/axe/jwt-secret`) |
| **username** | env var 이름 (예 `GATE_JWT_SECRET`) |
| **password** | 스크립트 안에서 생성/읽은 값 — `$(openssl rand -hex 32)` / `$(cat key.pem)` / 상수. **echo·shell history·argv·agent-context 어디에도 안 남김** |

### Windows 운영자 접속

운영자(Windows)는 Tailscale 로 `ssh axe@100.127.210.30` 한 뒤 위 3 단계를 **자기 SSH 셸 안에서** 실행한다. BW_SESSION 은 그 셸에만 존재한다.

### 검증 caveat — 에이전트는 검증 불가

BW_SESSION 이 운영자 셸 안에만 살아 있으므로 에이전트(Claude)는 결과를 직접 확인할 수 없다. **운영자의 `created`/`updated` + `synced` 출력이 곧 확인**이다. `axe secret check` 호출 금지 (keychain 필요 → SSH 에서 실패).

### keychain 세션이 필요한 곳 = deploy/ship 시점 한정

비밀을 *넣는* 작업은 위 raw-bw 로 keychain 없이 끝난다. 단 **`axe ship` / `axe secret pull` 은 배포 시점에 keychain 세션을 읽는다**. SSH 에서 GUI 없이 그 세션을 채우는 법 (headless unlock):

```bash
read -rs KCPW; security unlock-keychain -p "$KCPW" ~/Library/Keychains/login.keychain-db; unset KCPW
```

그다음 `axe vault unlock` → `axe ship`. 이 단계는 **배포/ship 할 때만** 필요하고, 비밀 주입 자체에는 불요하다.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 서비스 코드에서 vault REST 직접 호출 | vault 다운 = 전 서비스 startup fail | **금지**. 매니페스트 등록 후 deploy-time pull 만 |
| `git push origin main` 직접 호출 (axe ship 우회) | docs drift + secret 미동기화 | release-worthy push 는 `axe ship` 만 (D-ops-16) |
| `.env(.local)` git commit | secret 노출 | `.gitignore` 에 `.env*` (각 repo 확인 필요) |
| vault item name 오타 | check 가 missing 으로 표시 | 매니페스트 yaml lint + vault item 정확 복사 |
| bw session 만료 (Keychain) | `axe secret get/check/pull` 무응답 | `bw unlock --raw` 재실행 + Keychain 업데이트 |
| 매니페스트에는 있는데 vault item 누락 | check 실패 → ship abort | Vaultwarden web UI 에서 Login item 생성 (name = vault path, password 필드 = 값) |
| `bootstrap_only` 인 vault 자체 secret | pull 실패 (rightly) | `/Users/axe/.axe/vault/.env` 수동 유지 + 종이 메모 fallback |
| 운영자 1명 → service account 부재 | 모든 bw 호출이 운영자 개인 token | `axe-cli@axellc.com` service account 분리 (Phase 6) |
| **compose `environment:` 블록의 default-empty substitution (`$VAR` 변수 치환 형식) 이 env_file 값을 shadow** | 컨테이너에 secret 빈 값 도달 (frame 2026-05-21 dogfood 시 발견) | compose `environment:` 블록에 **비밀 vars 중복 금지** — env_file 만 사용 (D-ops-18) |
| **compose 파일이 subdir 에 있고 Docker auto-load `.env` 가 project_dir 의 `.env` 만 찾음** | `$VAR` 변수 substitution 실패 → 컨테이너 미작동 (blueprint `/docker/` subdir 시 발견) | `ln -sf ../.env SUBDIR/.env` symlink (D-ops-18) |
| **portal-등록 app 에 owner 없음 → az cli 회전 권한 X** | `Insufficient privileges` | portal Owners 탭에서 운영자 명시 추가 (D-ops-19) |
| **az 의 `credential reset` (no `--append`) 가 기존 secrets 전체 삭제** | overlap window 없이 즉시 cutover → in-flight 인증 실패 | 항상 `--append` (D-ops-19) |
| 매니페스트 env_file 이 compose 가 실제 읽는 파일과 불일치 (frame `.env` vs `.env.local`) | pull 가 .env.local 에 써도 compose 가 .env 에서 substitution → 새 값 안 닿음 | compose 의 모든 비밀 var 가 env_file 단일 경로에서 읽혀야 함. environment block 에서 비밀 substitution 제거 (D-ops-18) |
| **bw CLI `2026.4+` 또는 Bitwarden Chrome extension `>= 2026.4`** + Vaultwarden Timshel fork SSO user | `TypeError: toWrappedAccountCryptographicState` / "Master password unlock data was not found" crash | bw `2025.7.0` pin (`npm install -g @bitwarden/cli@2025.7.0`). 서버 측 axe.2 patch ([D-ops-37](/ops/decisions)) 가 영구 fix — patch 적용된 image (`axe.3` release) 사용 시 bw 2026.x 도 호환되지만 운영 표준은 2025.7.0 통일 |
| **bw `data.json` cache stale (server patch deploy 후)** — axe.2 / axe.3 등 server patch deploy 후 local cache 가 옛 schema 의 wrapped key 보유 → bw 가 decrypt 시도 시 MAC mismatch. patch deploy 가 client-side 무효화 신호 안 보냄 = 운영자 본인이 logout/login 1 회 필수 | 매 `bw unlock` 또는 `bw get ...` 시 `[Encrypt service] MAC comparison failed` → bw 명령 전체 실패 | (1) `bw logout` (2) `bw config server https://axe.axelabs.ai/vault` (3) `bw login` interactive (4) `bw unlock` 재시도. frequency 추적: 2026-05-22, 2026-05-26 — server patch deploy 후 매번 1회. 상세 = [`/ops/runbook/vault-recovery#bw-cli-data-json-cache-stale-recovery`](/ops/runbook/vault-recovery#bw-cli-data-json-cache-stale-recovery) |

## Bootstrap (현재 상태)

### bw CLI 표준 버전 — `2025.7.0` ([D-ops-28](/ops/decisions))

`axe secret *` + `bw-bootstrap.sh` + customer-side wrapper 가 **모두 bw CLI `2025.7.0`** 가정. 신규 머신 / customer macmini 설치:

```bash
npm install -g @bitwarden/cli@2025.7.0
bw --version    # 2025.7.0 확인
```

**다운그레이드 사유**: bw `2026.4+` 와 Bitwarden Chrome extension `>= 2026.4` 가 Vaultwarden Timshel fork 의 SSO user 와 호환 깨짐 — `TypeError: toWrappedAccountCryptographicState` / "Master password unlock data was not found" crash. 서버 측 axe.2 patch ([D-ops-37](/ops/decisions)) 가 영구 fix 라 본 patch 이미지 사용 시 bw 2026.x 도 호환되지만, **운영 표준은 2025.7.0 로 통일** (회귀 차단 + customer macmini 일관성).

axe CLI 의 `_svc_step_customer_vault_check` 가 version mismatch 발견 시 warning. `bw-bootstrap.sh` 가 install hint + warning gate.

### 초기 채우기

`axe secret push/pull/rotate` 코드는 동작 — `bw` CLI 가 설치돼 있고 `BW_SESSION` 이 Keychain 에 있으면 즉시 사용 가능. 다만 **vault 안에 실제 item 들이 아직 만들어지지 않음**. 초기 채우기:

```bash
# vault 잠금 풀기 (필요 시)
bw unlock --raw    # 출력값 복사
security add-generic-password -s axe.vault.session -a ai@axellc.com -w "<token>" -U

# 누락 확인
axe secret check frame

# 각 누락 item 에 대해, 현재 디스크의 값을 vault 로 push
axe secret push FRAME_DB_PASSWORD --service frame
# (interactive: value 입력)
# 또는 --value '<v>' 로 한 줄에

# 모두 채운 후 재확인
axe secret check frame    # exit 0 = ✓

# 이후로는 axe ship 가 자동으로 check + pull
```

## MCP Connectors catalog (D-vault-mcp-catalog, 2026-05-26)

운영자/직원/customer 가 `claude.ai/customize/connectors` (또는 다른 MCP host) 에 axelabs 자체 MCP 를 custom connector 로 등록할 때, 4 조각 (이름, MCP URL, client_id, client_secret) 을 매번 4 곳에서 찾는 비효율 해소. Vaultwarden 의 **`MCP Connectors` org collection** 이 catalog view — Bitwarden 브라우저 확장이 URI 매칭으로 자동 suggest.

### 구조 (데이터 중복 0)

```
SoT (변경 금지)                          View (자동 생성)
─────────────────                       ─────────────────────────────────
customers.yaml          ─┐
  .sso.apps.frame_mcp    │
    .client_id           ├──→ axe mcp publish ──→ Vaultwarden
    .application_id_uri  │    (idempotent upsert)  "MCP Connectors" collection
    .client_secret_env   │                            ├─ "Frame MCP (axe)"
                         │                            │    URIs: claude.ai/.com/customize/connectors
Vaultwarden             ─┤                            │           + https://axe.axelabs.ai/frame/mcp
  frame/axe/             │                            │    username: 137fc0ef-... (client_id)
   oauth-client-secret  ─┘                            │    password: <client_secret 40 chars>
                                                      │    field "MCP URL": application_id_uri
                                                      │    field "Tenant ID" / "Scopes" / "Vault secret path"
                                                      ├─ "Hive MCP (axe)"
                                                      └─ "Blueprint MCP (axe)"
```

### CLI

```bash
axe mcp list              # 미리보기 — vault 미접근
axe mcp publish           # 실 publish — 매니페스트 순회 + vault fetch + upsert
axe mcp publish --dry-run # plan only
axe mcp publish --allow-missing  # public client (secret 없는 항목) 도 publish
```

매 호출 idempotent — item 이름 (`{Svc} MCP ({cust})`) 으로 lookup 하여 존재 시 edit, 없으면 create.

### 사용자 흐름 (target audience)

1. `https://claude.ai/customize/connectors` 접속 + "Custom Connector" → "Add"
2. Bitwarden 브라우저 확장 아이콘 클릭 — URI 매칭으로 3 개 MCP 항목 자동 suggest
3. 원하는 항목 클릭 → username (= client_id) / password (= client_secret) 자동 입력
4. Name + MCP URL 은 custom field 옆 "copy" 한 번씩 → 폼에 붙여넣기
5. Save → connector 등록 완료

### 자동 갱신 hook

`axe secret rotate <ENV> --service <svc>` 가 MCP `client_secret` 회전 시 `axe mcp publish` 자동 호출 → catalog 의 password 즉시 갱신. 사용자가 옛 secret 으로 등록하다 OAuth 거부 받는 함정 차단.

### 신규 MCP 추가 절차 (표준)

1. Entra app 등록 (또는 az CLI) — application_id_uri = `https://axe.axelabs.ai/{svc}/mcp` + redirect_uris (claude.ai/.com 양쪽) + mcp.access scope
2. `customers.yaml customers.axe.sso.apps.<svc>_mcp` 4-key 추가: `client_id`, `application_id_uri`, `scopes[]`, `client_secret_env`
3. `customers.yaml customers.axe.services.<svc>.secrets[]` 에 `{env: AZURE_<SVC>_MCP_CLIENT_SECRET, vault: "<svc>/axe/oauth-client-secret", rotation_external: azure}` 추가
4. `axe secret push AZURE_<SVC>_MCP_CLIENT_SECRET --service <svc>` (interactive)
5. `axe mcp publish` → catalog 에 새 item 자동 등재

### 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `customers.yaml` 의 `client_secret_env` line 누락 (예: 5/21 hive 등재 후에도 frame_mcp 의 본 line 이 "proxy-only" 주석 형태로 stale, 5/26 정정) | catalog 의 frame_mcp 가 (public) 으로 잘못 publish — claude.ai 등록 시 secret 칸 비어 OAuth 거부 | `axe mcp list` 출력의 "vault item" 칸이 `(public)` 인 항목 점검. claude.ai 가 secret 요구하는 MCP 면 customers.yaml 의 `client_secret_env` line 확인 |
| MCP URL (custom field) 의 Bitwarden 확장 자동입력 불가 | claude.ai 폼의 "Server URL" 필드는 표준 username/password 가 아니라 자동입력 안 됨 — 사용자가 "copy" → "paste" 한 번 필요 | 표준 한계. 4 곳 찾는 것보다 4 클릭 이 빠름 |
| customer (realchoice 등) 의 MCP secret 을 operator vault 에 publish | sovereignty 위반 ([B-customer-sovereignty-architecture](/ops/backlog) Q3) | `axe mcp publish` 는 `--customer` 명시 + 명시되지 않으면 axe 만 publish. customer 측 운영자가 customer macmini 에서 customer 자체 vault 에 publish |
| Vaultwarden org timeout 으로 catalog 가 stale 보일 가능성 | Bitwarden 확장에 새 item 안 보임 | 클라이언트 측 `bw sync` 또는 web UI 새로고침. catalog 변경 빈도 낮아 일상 운영엔 영향 없음 |

## 관련

- [`/ops/runbook/secret-rotation`](/ops/runbook/secret-rotation) — 회전 실전 절차
- [`/ops/runbook/release-flow`](/ops/runbook/release-flow) — `axe ship` 전체 흐름
- [`/ops/decisions`](/ops/decisions) — D-ops-9 (vault SoT), D-ops-17 (deploy-time pull), D-vault-mcp-catalog (본 catalog)
- [`/services/index`](/services) — Vaultwarden 운영 정보

---

<!-- PAGE https://docs.axelabs.ai/architecture/topology -->

# Topology · 네트워크

> Cloudflare Tunnel, Docker network, host-side proxy 패턴.

URL: https://docs.axelabs.ai/architecture/topology

# Topology · 네트워크

## 외부 경계 — Cloudflare

모든 외부 트래픽은 Cloudflare 의 anycast 망을 통해 도달합니다.

| 구간 | 도메인 / 호스트 | 처리 |
|---|---|---|
| DNS | `axelabs.ai` zone (Cloudflare) | A/CNAME → Cloudflare proxy IPs |
| 전송 보안 | Cloudflare → cloudflared (HTTPS) | mTLS connector |
| 터널 | `axelabs-tunnel` (Docker, ID `d8efecdd-2c3f-42de-9925-501433e21394`) | tunnel ingress |
| origin | `host.docker.internal:{port}` | per-service routing |

cloudflared config 위치: `/Users/axe/.axe/tunnels/axelabs/config.yml`

### Tunnel ingress 규칙

```yaml
tunnel: d8efecdd-2c3f-42de-9925-501433e21394
ingress:
  - hostname: axe.axelabs.ai
    path: ^/frame(/.*)?$
    service: http://host.docker.internal:3712     # axe-frame-proxy
  - hostname: axe.axelabs.ai
    path: ^/vault(/.*)?$
    service: https://host.docker.internal:8222   # axe-vault-caddy
  - hostname: admin.axelabs.ai
    service: http://axe-caddy:80                  # operator console
  - hostname: axe.axelabs.ai
    service: http://host.docker.internal:3100     # blueprint apex
  - service: http_status:404                       # default deny
```

## ⚠️ 함정 — cloudflared SIGHUP 미지원

```ansi
[1m[31mcloudflared 는 SIGHUP graceful reload 를 지원하지 않습니다.[0m
```

**검증된 사실 (2026-05-15)**: `docker kill -s HUP axelabs-tunnel` 실행 시 프로세스가 종료됩니다. config 변경 = 컨테이너 재시작 = **5초 다운타임**.

**대응**: 변경 잦은 부분 (frame upstream, blue/green swap) 을 cloudflared config 에서 분리하고 **host-side proxy 뒤로 이전**.

→ 결과: cloudflared 는 `host.docker.internal:3712` 한 줄만 알고, blue/green swap 은 그 proxy 내부에서 처리. cloudflared 재시작 없음.

## Host-side proxy 패턴 (axe-frame-proxy)

**axe-frame-proxy** = Caddy reverse-proxy 컨테이너. host port `3712` 노출. 단일 책임: `/frame/*` 트래픽을 docker network 위의 `frame-mcp` alias (blue 또는 green 중 active 쪽) 로 라우팅. blue/green swap = alias 이동 + Caddy graceful reload (SIGHUP 지원, cloudflared 와 달리). frame 컨테이너의 build/recreate 와 무관하게 cloudflared 안정.


```
cloudflared (axelabs-tunnel)
        │
        ↓  HTTP /frame/* → host.docker.internal:3712
        │
        ↓
┌──── axe-frame-proxy (Caddy) ────┐
│                                 │
│  /frame/* → upstream (선택)      │
│              │                  │
│              ↓                  │
│   frame-mcp-blue :3710          │  ← network alias `frame-mcp`
│   frame-mcp-green :3711         │     (blue/green swap = alias move)
│                                 │
└─────────────────────────────────┘
```

**핵심**: cloudflared 는 `axe-frame-proxy` 만 알고, blue/green 의 실제 컨테이너 이름·포트는 모릅니다. swap 은 docker network alias 이동으로 처리 (`axe deploy frame axe --apply`).

## Docker 네트워크 — `artemis_default`

axelabs 플랫폼의 모든 컨테이너 (axelabs-tunnel, axe-frame-proxy, frame-mcp-blue/green, blueprint-app 등) 는 `artemis_default` 외부 docker 네트워크 위에서 통신합니다.

```bash
# 검증
docker network inspect artemis_default | grep '"Name"'
```

frame docker-compose.yml 에서:

```yaml
networks:
  artemis_default:
    external: true   # 별도 docker 명령으로 생성된 망에 합류
```

## 포트 할당 (CLAUDE.md SSOT)

| 범위 | 프로젝트 |
|---|---|
| 31xx | Blueprint |
| 32xx | Cortex |
| 33xx | Artemis |
| 34xx | Distributa |
| 35xx | Kolon Discussion |
| 36xx | mysrt |
| 37xx | frame |

전체 포트 테이블은 [/Users/axe/CLAUDE.md](https://github.com/soohunkang/blueprint/blob/main/CLAUDE.md) 가 SSOT. 새 서비스 추가 시 반드시 비어 있는 범위 확인.

## ⚠️ 함정 모음

| 함정 | 결과 | 회피 |
|---|---|---|
| cloudflared SIGHUP 직접 호출 | process 종료, 다운타임 | host-side proxy 뒤로 |
| frame 컨테이너 이름을 cloudflared 에 직접 명시 | blue/green swap 불가 | network alias 사용 |
| path strip 기대 (cloudflared) | 라우터가 prefix 못 찾음 | 각 서비스에 `/frame` prefix mount |
| 2-level subdomain (`frame.axe.axelabs.ai`) | Cloudflare Universal SSL 무료 미커버 | 1-level + path |
| `axellc.com` 으로 platform traffic | corporate ↔ platform 경계 혼탁 | 평행 운영, 신규는 `axelabs.ai` only |
| `artemis_default` external network 사전 부재 (신규 customer macmini) | `axe deploy` 시 `network artemis_default declared as external, but could not be found` → compose up fail | onboard step 에 `docker network create artemis_default` pre-step (또는 `axe deploy` 자체에 `_svc_step_network` 빌트인 — 2026-05-25 이후 적용 ✅, trap #17 of B-onboard-d-day-traps-2026-05-25) |

상세 결정 근거는 [DECISIONS](/ops/decisions) §3 D-config-13 참조.

---

<!-- PAGE https://docs.axelabs.ai/architecture/vault-policies -->

# Vault 세션/정책 모델 (3 layer)

> AXE Vaultwarden 의 session lifecycle + 권한 정책 + per-user unlock 패턴. 운영자가 통제 가능한 layer 와 user 자율 layer 의 구분. 새 직원/customer 의 표준 setup.

URL: https://docs.axelabs.ai/architecture/vault-policies

# Vault 세션/정책 모델 (3 layer)

AXE Vaultwarden (Timshel fork 기반, [D-ops-37](/ops/decisions) + [D-ops-40](/ops/decisions)) 의 session/unlock 정책은 **3 layer 누적**으로 결정. 각 layer 가 누가 통제하는지 + 변경 비용이 다름.

| Layer | 통제 누가 | 영향 범위 | 변경 비용 |
|---|---|---|---|
| **1. Server env** (Vaultwarden config) | 운영자 (compose env_file) | 모든 user, 모든 client | container restart 1회 |
| **2. Org Policies** (Bitwarden 호환 정책) | Org Owner (web UI 또는 API) | 해당 org member 전원, 모든 client | 즉시 (next login 적용) |
| **3. Per-client preferences** (localStorage) | 각 user 본인 (각 device/client 마다) | 본인의 그 client 만 | 본인 30초 |

3 layer 가 **누적 적용** — 각 layer 가 더 paranoia 방향으로 강제하고, 마지막 user 자율 layer 가 ceiling 안에서 편의 조정.

## Layer 1 — Server env

Vaultwarden config 의 env var. `/Users/axe/.axe/vault/docker-compose.yml` 의 `environment:` 블록.

### 핵심: `SSO_AUTH_ONLY_NOT_SESSION`

| 값 | 효과 |
|---|---|
| `false` (default) | SSO 의 refresh token 따라감 — Entra ID 의 token 만료 시점에 자동 logout → re-SSO+MP 강제. user 입력 빈도 ↑ |
| **`true` (AXE 현재 설정, 2026-05-26)** | SSO 가 인증만, session lifecycle 은 Vaultwarden 자체 **30일 idle refresh token** 사용. user 가 30일 안 idle 안 하면 무한 갱신 |

**적용 효과** (AXE 4 user):
- SSO+MP 재입력 = 약 월 1회 (idle 30일 + browser 재시작 시)
- Touch ID/PIN unlock 은 daily

**trade-off**:
- Entra 측 user 비활성/제명이 server session 에 ≤30일 lag
- offboarding 시 운영자가 수동으로 vault 측에서도 user 비활성 (UI: AXE org → Manage → Members → user → Remove + admin panel 에서 user disable) — AXE 4명 규모 충분 처리 가능
- customer 규모 ↑ 시 재평가 (별 결정)

### 다른 관련 env

| env | 효과 |
|---|---|
| `SSO_ONLY=false` | MP 단독 fallback 유지 ([D-ops-26](/ops/decisions) + [D-ops-27](/ops/decisions)) |
| `SIGNUPS_ALLOWED=true` | JIT user provisioning (SSO 신규 user 자동 생성) |
| `SSO_SCOPES="openid profile offline_access User.Read"` | offline_access = refresh token 발급 |
| `ORGANIZATION_INVITE_AUTO_ACCEPT=true` | invite Accept 단계 자동 통과 |

**Vaultwarden 미지원 (의도)**:
- ❌ Maximum Vault Timeout — Bitwarden commercial license, AGPLv3 비호환 ([source comment](https://github.com/Timshel/vaultwarden/blob/main/src/db/models/org_policy.rs): `// MaximumVaultTimeout = 9, // Not supported (Not AGPLv3 Licensed)`)
- ❌ Disable Personal Vault Export — 동일 license 사유
- ❌ Activate Autofill, Automatic App LogIn — Vaultwarden 미구현

→ vault timeout 의 **server-side 강제는 영구 영역 외**. `SSO_AUTH_ONLY_NOT_SESSION=true` 가 가용 영역 안 best 대체.

## Layer 2 — Org Policies (Bitwarden 호환)

Org Owner 가 `/api/organizations/<orgId>/policies/<type>` ([Bitwarden 정책 docs](https://bitwarden.com/help/policies/)) 또는 web UI 로 설정. Vaultwarden 의 [supported set](https://github.com/Timshel/vaultwarden/blob/main/src/db/models/org_policy.rs#L26) 안에서.

### 현재 AXE org 적용 (2026-05-26, [D-ops-40](/ops/decisions) Progress)

| type | 정책 | 값 | 효과 |
|---|---|---|---|
| 1 | MasterPassword | min 12자, complexity 1 | MP **변경 시점** 검증. 기존 MP 영향 0 (paranoia 옵션) |
| 2 | PasswordGenerator | length 20, upper+lower+number+special | item 신규 생성 시 강한 default |
| 3 | SingleOrg | enabled | member 가 다른 org 가입 차단 → 데이터 누설 방지 |
| 5 | PersonalOwnership | enabled | 신규 item 은 org collection 필수 ([D-ops-32](/ops/decisions) 본질 정합) |

**의도적 미설정** (D-ops-38 + D-ops-26+27):

| type | 정책 | 왜 안 켜나 |
|---|---|---|
| 0 | TwoFactorAuthentication | Entra SSO 가 이미 MFA 역할 ([D-ops-38](/ops/decisions)) — vault 자체 2FA 중복 |
| 8 | ResetPassword | 운영자 직권 reset 보존 (default), 강제 policy 불필요 |
| 14 | RemoveUnlockWithPin | PIN unlock = 일상 편의 핵심, 차단하면 user 경험 악화 |

### Vaultwarden 미지원 (Bitwarden Cloud 에서는 가능):

| type | 정책 | 사유 |
|---|---|---|
| 4 | RequireSso | Vaultwarden 미구현 (의도 — MP 단독 fallback 보존 정책과 정합) |
| 9 | MaximumVaultTimeout | AGPL 비호환 |
| 10 | DisablePersonalVaultExport | AGPL 비호환 |

### API 호출 패턴

```bash
# AXE org policy 조회
export BW_SESSION="$(security find-generic-password -s 'axe.vault.session' -w)"
AI_USER=0ef2361b-5a69-4c23-973d-e978a4d55512  # ai@
ORG=0c5d8bbd-ad85-42b4-8b8a-2849031981b1     # AXE
TOKEN=$(jq -r ".\"user_${AI_USER}_token_accessToken\"" \
  "$HOME/Library/Application Support/Bitwarden CLI/data.json")

curl -sf -H "Authorization: Bearer $TOKEN" \
  "https://axe.axelabs.ai/vault/api/organizations/$ORG/policies" \
  | jq '.data | map({type, enabled})'

# 정책 변경 (예: MasterPassword 정책 수정)
curl -sf -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  "https://axe.axelabs.ai/vault/api/organizations/$ORG/policies/1" \
  -d '{"type":1,"enabled":true,"data":{"minComplexity":2,"minLength":14,"requireUpper":false,"requireLower":false,"requireNumbers":false,"requireSpecial":false,"enforceOnLogin":false}}'
```

token 만료 시 (~1h) `bw sync` 로 refresh.

## Layer 3 — Per-client preferences

vault timeout / PIN / Touch ID / theme = **각 device 의 client localStorage**. server 가 못 건드림 (Bitwarden 디자인 — privacy by design, prefs 가 user device 안). 정책 부재 시 각 client 의 첫 사용에서 user 가 선택.

### AXE 표준 setup (KDF rotation 완료 후 권장)

**4 user 모두 + 모든 새 직원** 다음 3 client 설정:

#### A. Web vault (보조용, https://axe.axelabs.ai/vault)

| field | 권장 |
|---|---|
| Vault timeout | `On browser refresh` (web vault 의 최장 옵션 — `Never` 노출 안 됨) |
| Vault timeout action | `Lock` (Logout 절대 X — SSO 재진입 비용) |

설정 위치: 우상단 본인 이름 → Account settings → Preferences

#### B. Chrome extension (일상 brower-bound)

| field | 권장 |
|---|---|
| Server URL (self-hosted) | `https://axe.axelabs.ai/vault` |
| Vault timeout | **`Never`** (extension 은 `Never` 노출됨) |
| Vault timeout action | `Lock` |
| Unlock with PIN code | ✅ + PIN 4~12자 (e.g. `axe-2026` word) |
| Lock with master password on browser restart | ✅ (paranoia 균형) |

#### C. Native macOS app (daily driver — 가장 편함)

| field | 권장 |
|---|---|
| Server URL (self-hosted) | `https://axe.axelabs.ai/vault` |
| Vault timeout | `Never` |
| Vault timeout action | `Lock` |
| Unlock with Touch ID | ✅ (macOS Secure Enclave) |
| Lock with master password on browser restart | ✅ |

**실 효과** (3 layer 누적):
- daily unlock = Touch ID (수 초)
- 주 1-2회 = PIN (Chrome ext)
- 월 1회 (idle 30일 또는 paranoia 재시작) = MP

## Vault scope — 무엇을 보호하는가 (trust boundary)

Vault 는 **secret 의 저장 + retrieval + access control** 만 담당하는 저장소. vault item 을 delete/revoke 했다고 해서 그 secret 이 의미하는 **외부 service 의 권한·계정·2FA 가 자동으로 무효화되지 않음**. 두 영역을 혼동하면 offboarding/사고 대응 시 access 잔존 위험.

### 경계 도식

```
┌─ Vault scope (이 페이지 + Vaultwarden 이 통제) ──────────┐
│   • secret 값의 저장 / 암호화 (Argon2id + KDF)            │
│   • org collection 기반 access control (Layer 2)        │
│   • SSO + MP unlock lifecycle (Layer 1, 3)              │
│   • item delete/revoke → 그 저장 위치 에서 차단           │
└──────────────────────────────────────────────────────────┘
            ↓ vault item 은 외부 service 의 "거울" 일 뿐
┌─ 외부 service scope (vault 가 못 건드림) ─────────────────┐
│   • 해당 service 측 계정 자체 (Microsoft / Google / ...) │
│   • TOTP secret 의 generation (해당 service 가 발급)     │
│   • OAuth client_secret / refresh token invalidation    │
│   • GitHub PAT, API key 의 server 측 revoke             │
│   • customer 측 데이터 자체 (KB / 홈택스 export 등)       │
└──────────────────────────────────────────────────────────┘
```

→ **회수 범위 = vault item delete + 외부 service 측 절차**. 둘 다 해야 완전.

### 회수 대상별 분리표

| 회수 대상 | vault 가 처리 | 외부 service 측 절차 필요 |
|---|---|---|
| service password 저장값 | ✅ item delete/revoke | 해당 service 의 password reset (admin 또는 본인) |
| TOTP secret (2FA) | ✅ item delete | 해당 service 의 2FA reset → TOTP secret regenerate |
| OAuth client_secret | ✅ item delete | Azure / Google / GitHub 측에서 client_secret 재발급 + 옛값 폐기 |
| GitHub PAT | ✅ item delete | GitHub Settings → Personal access tokens → Revoke (server 측 token row 무효화) |
| API key (Anthropic / OpenAI / etc) | ✅ item delete | 해당 provider 의 console 에서 key revoke |
| KB / 홈택스 / 회계법인 portal admin 계정 | ❌ vault scope 외 (계정 자체는 vault 가 보관 안 함) | 해당 portal admin 의 계정 비활성/삭제 |
| Microsoft 365 / Entra ID 계정 | ❌ vault scope 외 | customer IT 가 Entra ID 에서 user 비활성 |
| customer 측 데이터 (Excel, PDF 등 export 본) | ❌ vault scope 외 | customer 자체 DLP / device wipe / 법적 요구 |

### 함의

- **offboarding 시**: [/ops/runbook/employee-offboarding](/ops/runbook/employee-offboarding) 의 "외부 service 권한 회수" 표를 vault item 제거와 **반드시 병행**.
- **secret rotation 시**: vault item 값을 새로 채우는 것 만으로는 옛값이 외부 service 측에서 살아있음 — [/ops/runbook/secret-rotation](/ops/runbook/secret-rotation) 의 외부 service rotation step 동반.
- **사고 대응 시**: vault item delete = "이 운영자 머신/AXE org 안에서 더 못 꺼냄". 그 secret 이 leak 된 정황이면 외부 service 측 revoke 가 본질.

## 3 layer 누적 그림

```
┌──────────────────────────────────────────────────────────┐
│ Layer 3: Per-client preferences (user 자율)              │
│   • web `On browser refresh` Lock                       │
│   • extension `Never` + PIN                             │
│   • native `Never` + Touch ID                           │
│   ↓ 위 layer 의 ceiling 안에서 user 편의 조정             │
├──────────────────────────────────────────────────────────┤
│ Layer 2: Org Policies (Owner 통제, member 전원 적용)      │
│   • MasterPassword min 12, complexity 1                 │
│   • PasswordGenerator length 20                         │
│   • SingleOrg                                            │
│   • PersonalOwnership                                    │
│   ↓ 모든 member 자동                                      │
├──────────────────────────────────────────────────────────┤
│ Layer 1: Server env (운영자 통제, 전 instance)            │
│   • SSO_AUTH_ONLY_NOT_SESSION=true → 30일 session       │
│   • SSO_ONLY=false → MP fallback                        │
│   • SIGNUPS_ALLOWED=true → JIT                          │
│   ↓ 인스턴스 기본값                                       │
└──────────────────────────────────────────────────────────┘
```

## 새 직원 onboarding 의무 step

1. **KDF rotation** (1회) — [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) runbook
   - 옛 PBKDF2 → Argon2id 로 vault re-encrypt
   - SSO→MP wrapped variant 정합 ([D-ops-40](/ops/decisions))
2. **Layer 3 setup** (1회 per device) — 위 Web/Extension/Native 표 그대로
3. 끝 — 이후 일상은 Touch ID/PIN 만

운영자가 1번 안내 1회 + 2번 표 공유 1회 = onboarding 끝. layer 1+2 는 server 가 자동.

## Customer (Truvia 등) — sovereignty

| Layer | customer 자율도 |
|---|---|
| Layer 1 (server env) | **customer 자체 통제** — customer 의 macmini compose, customer 자율. AXE 가 권장만 (이 페이지 참조 안내) |
| Layer 2 (org policies) | **customer org Owner 가 설정** — AXE 가 정책 enforce 불가. 권장 (위 4 정책 동일) |
| Layer 3 (per-client) | customer 직원 본인 — 동일 setup 권장 |

→ customer 운영자에게 본 페이지 link 만 전달, 권장 follow. [/services/vault](#) 의 customer onboarding 단계에 vault setup 포함 (TODO).

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| Maximum Vault Timeout 정책 시도 (Bitwarden 패턴) | HTTP 400 "Invalid or unsupported policy type" | Vaultwarden 미지원 (AGPL). 대신 `SSO_AUTH_ONLY_NOT_SESSION=true` 사용 |
| `SSO_ONLY=true` + Entra ID 장애 | 운영자 vault 진입 불가 (lockout) | `SSO_ONLY=false` 유지 ([D-ops-26](/ops/decisions) + [D-ops-27](/ops/decisions)) — MP fallback 보존 |
| RemoveUnlockWithPin 정책 enable | PIN unlock 불가 → 일상 MP 입력 강제 | 본 정책 enable 금지 (paranoia 와 편의 균형) |
| 옛 KDF (PBKDF2) user 가 SSO→MP unlock 실패 | client 가 wrapped MP 변환 불가 | user 별 KDF rotation 의무 (onboarding step 1) |
| Org policy 변경이 즉시 client 에 반영 안 되는 듯 | client 가 sync 시점에 fetch | bw sync 또는 client 강제 sync (일반적 ≤1분 안 자동) |
| 운영자가 Layer 3 강제 시도 (Chrome managed policy 등) | macmini 별 enrollment 필요 — overhead 큼 | AXE 4명 규모 = docs 안내 + 신뢰. 10+ 직원 시점에 재평가 ([B-vault-chrome-mdm-policy-distribution](#)) |
| Entra user 비활성 후 ≤30일 server session 잔존 | offboard 직후 vault 접근 가능 | offboard 시 운영자가 vault admin panel 에서 user disable 같이 실행 (manual checklist) |

## 관련

- [D-ops-37](/ops/decisions) — AXE-local Vaultwarden fork build
- [D-ops-40](/ops/decisions) — axe.3 release plan + Progress (본 정책 결정)
- [D-ops-38](/ops/decisions) — 외부 service 2FA = vault TOTP, 내부 2FA skip
- [D-ops-26](/ops/decisions) + [D-ops-27](/ops/decisions) — SSO_ONLY=false + MP fallback
- [/architecture/auth](/architecture/auth) — Entra ID + OAuth-RP middleware
- [/architecture/secrets](/architecture/secrets) — 서비스 secret 관리 (vault item)
- [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) — KDF rotation runbook
- [B-vault-collection-migration-v1](/ops/backlog) — personal vault → org collection 정리

---

<!-- PAGE https://docs.axelabs.ai/glossary -->

# 용어 사전 (Glossary)

> AXE Labs docs 에서 반복 등장하는 약어와 용어 정의.

URL: https://docs.axelabs.ai/glossary

# 용어 사전

AXE Labs docs 전반에서 반복 등장하는 약어·용어 정의. 처음 보는 약어 있을 때 여기를 참조.

## 인증·OAuth

| 용어 | 정의 |
|---|---|
| **MCP** | Model Context Protocol. Anthropic 표준으로 AI 가 외부 도구·데이터에 접근하는 방식. HTTP 또는 stdio transport. |
| **FastMCP** | Python 기반 MCP server 구현 라이브러리. `@mcp.tool()` 데코레이터로 도구 등록. |
| **SSE** | Server-Sent Events. HTTP 위에서 server → client 단방향 streaming. MCP HTTP transport 의 한 방식. |
| **OAuth 2.0** | 인증·인가 표준 (RFC 6749). "사용자 비밀번호 공유 없이 권한 위임" 의 방식. |
| **OIDC** | OpenID Connect. OAuth 2.0 위에 사용자 신원 확인 추가 (id_token 발급). |
| **RP** | Relying Party. OIDC 에서 신원을 의존하는 측 (= 우리 frame, blueprint). Identity Provider (Microsoft) 는 IdP. |
| **PKCE** | Proof Key for Code Exchange (RFC 7636). 모바일/SPA 같은 public client 의 인증 코드 가로채기 방지. `code_challenge` + `code_verifier` 쌍. |
| **JWT** | JSON Web Token. claim 들을 JSON 으로 담은 signed token. `header.payload.signature` 형식. |
| **JWKS** | JSON Web Key Set. JWT 서명 검증용 공개 키 목록. Microsoft 가 `https://login.microsoftonline.com/{tenant}/discovery/v2.0/keys` 로 제공. |
| **RS256** | RSA-SHA256 비대칭 서명. JWT 서명 알고리즘. asymmetric — 공개키로 검증, 비밀키로 서명. |
| **HS256** | HMAC-SHA256 대칭 서명. 동일 비밀키로 서명+검증. frame 의 자체 발급 JWT 가 사용. |
| **AS** | Authorization Server. OAuth 에서 토큰을 발급하는 서버. Microsoft Entra ID 가 우리의 AS. |
| **App ID URI** | Microsoft Entra ID 에서 app 의 식별 URI. `api://137fc0ef-...` 또는 `https://axe.axelabs.ai/frame/mcp`. access_token 의 `aud` (audience) claim 으로 들어감. |
| **AADSTS** | Azure Active Directory STS error code prefix. 6자리 숫자 (예: AADSTS9010010). 모든 Microsoft 인증 실패의 진단 코드. |

## 데이터·DB

| 용어 | 정의 |
|---|---|
| **SSOT** | Single Source of Truth. 한 정보의 정본이 한 파일에만 있도록 하는 원칙. `customers.yaml` 이 멀티테넌트 SSOT. |
| **RLS** | Row-Level Security (PostgreSQL). 한 테이블 안에서 row 단위 권한 분리. `SET app.tenant_id = X` 같은 session 변수로 자동 필터링. |
| **Schema-per-entity** | 한 PostgreSQL DB 안에 entity 별로 별도 schema 둠. frame 의 `axec`, `axev` 가 그 예. cross-schema 조회 불가 = 격리. |
| **PII** | Personally Identifiable Information. 주민번호·계좌·주소 등. frame 은 `pgcrypto.pgp_sym_encrypt` 로 entity 별 passphrase 로 암호화. |
| **Bitemporal** | 두 시간 축 (`valid_from/to` + `recorded_at`) 으로 "어떤 시점에 무엇이 사실이었는가" + "그 사실을 언제 알았는가" 모두 기록. hive 의 `employment_records` 가 그 예. |
| **ltree** | PostgreSQL 의 hierarchical tree 자료형 + 인덱스. hive 의 조직도 트리에 사용. `org.axec.finance.team1` 같은 path. |
| **Append-only** | 한 번 쓴 row 는 UPDATE/DELETE 불가, 새 row 만 가능. frame 의 `journal_line`, `raw_transaction` 이 그 예. |

## 인프라

| 용어 | 정의 |
|---|---|
| **Cloudflare Tunnel** | 외부에 포트를 노출하지 않고 Cloudflare 측에서 origin 으로 outbound TCP 만으로 트래픽 받는 방식. `axelabs-tunnel` 컨테이너가 그 역할. |
| **cloudflared** | Cloudflare Tunnel 의 connector binary. `docker.io/cloudflare/cloudflared`. |
| **Caddy** | Go 기반 reverse proxy + HTTPS auto-cert. `axe-frame-proxy` (port 3712) 가 frame blue/green selector 로 사용. |
| **launchd** | macOS 서비스 매니저 (Linux 의 systemd 격). `com.axe.backup.local` 같은 plist 등록. |
| **Tailscale** | Mesh VPN. AXE 운영자 ↔ customer macmini 간 push deploy 의 transport. SSH key 와 별도 layer. |
| **restic** | Open-source encrypted incremental backup tool. 3-tier backup (local + ring + cold SSD) 모두 같은 도구. |
| **Keychain** | macOS 의 secret store. `security add-generic-password -a axe-cli -s axe.backup.restic.local -w ...` 로 등록. |

## AXE 고유 용어

| 용어 | 정의 |
|---|---|
| **customer** | AXE 의 고객 회사 (axe, realchoice). 각자 macmini 1대 보유. |
| **entity** | 한 customer 안의 법인 단위 (axec, axev, realchoice). DB schema 격리 단위. |
| **operator** | 운영 주체 = 액스코퍼레이션 주식회사 (`axec` entity). 자동화 계정 `ai@axellc.com` 이 단일 CLI 진입점. |
| **D-ops-N / D-config-N / D-hive-N** | 누적 의사결정 번호. 영문 N 은 시간순 번호. 예: D-ops-15 = OAuth proxy 시도 (dormant). |
| **blue/green** | 두 버전이 동시 가동 + alias 이동으로 무중단 deploy. frame 만 적용 (port 3710/3711). |
| **axe-frame-proxy** | Caddy 컨테이너 (port 3712). 외부에서 들어온 `/frame` 트래픽을 blue 또는 green 중 active 쪽으로 라우팅. |

## 관련 페이지

- [아키텍처 결정](/ops/decisions) — D-ops / D-config / D-hive 전체 목록
- [인프라 인벤토리](/ops/inventory) — 포트 · 컨테이너 · launchd
- [인증 · 권한](/architecture/auth) — Microsoft Entra ID OAuth 흐름 상세

---

<!-- PAGE https://docs.axelabs.ai/onboard -->

# 신규 직원 온보딩

> 회사 이메일로 AXE Labs 플랫폼에 접속하는 4 단계.

URL: https://docs.axelabs.ai/onboard

# 신규 직원 온보딩

AXE Labs 플랫폼에 접속하기 위해 필요한 것은 **회사 이메일 + Claude 구독** 입니다.

## 사전 조건 (운영자가 미리 처리)

운영자 (`ai@axellc.com`) 가 다음을 완료한 상태여야 합니다:

- [ ] 회사 Microsoft Entra ID 계정 발급
- [ ] `customers.yaml` 의 `user_entity_map` 또는 `default_entities_by_domain` 에 본인 매핑
- [ ] (선택) 본인이 작업할 entity 권한 부여 (예: `axec:read,write`)

신규 직원의 운영자 측 단계는 [신규 employee 등록 runbook](/ops/runbook/customer-onboarding) 참조.

## 4-step 설정

1. **Claude 구독**: 회사 이메일 (`@axellc.com`) 로 [claude.ai](https://claude.ai) 가입 (개인 결제 또는 회사 결제)
2. **[Frame connector 설정](/onboard/claude-frame-setup)**: claude.ai 에 회사 회계 시스템 연결 (5분, 1회)
3. **(선택) [M365 connector](/onboard/m365-connector)**: OneDrive·Outlook·Teams 통합
4. **Claude Code 네이티브 앱**: 같은 claude.ai 계정으로 로그인 → connector 자동 동기화

> **터미널·Claude Code·Codex·cron 에서 쓰려면** (claude.ai 커넥터 대신): [AXE CLI](/services/cli) 의 **"에이전트에 붙여넣기"** 블록을 본인 에이전트에 한 번 복붙하면 로그인 1회로 전 서비스 사용. 커넥터는 claude.ai 웹 챗용, CLI 는 셸 가진 모든 곳용.

## 사용 방법

설정 끝나면 채팅에서 자연어로 호출:

```
axec 의 5월 미결 항목 보여줘

→ Frame:list_open_items 자동 호출, entity_id=axec
```

```
axec 와 axev 의 이번 분기 잔액 비교해줘

→ Frame:query_balance 두 번 호출, 결과 비교
```

```
axec 에 5월 28일 매출 1000만원 계상해줘 — Revenue 1000, Cash 1000

→ Frame:post_journal 자동 호출 (write 권한 필요)
```

Entity 명시 (`axec`, `axev`, `realchoice`) 가 정확. 미명시 시 Claude 가 되묻습니다.

## 권한 모델

각자 부여된 권한 내에서만 작업 가능:

| 권한 | 가능한 작업 |
|---|---|
| `read` | 잔액 조회, 분개장, 미결 조회 |
| `write` | 분개 등록, 미결 생성/해결 |
| `close` | 회계 기간 마감 |
| `admin` | 계정과목 변경 (운영자만) |

권한 부족 시 Claude 가 "이 작업은 write 권한이 필요하나 현재 read 만 부여되어 있습니다" 식으로 알려줍니다.

## 다음

- [Frame connector 4-step 설정](/onboard/claude-frame-setup)
- [문제 해결](/onboard/troubleshooting)

---

<!-- PAGE https://docs.axelabs.ai/onboard/claude-connectors -->

# AXE MCP connectors (claude.ai + Claude Code 자동 sync)

> claude.ai 의 Custom Connector 등록에 Bitwarden 브라우저 확장 + AXE Vault `MCP Connectors` collection 활용. 4 필드 (Name / URL / Client ID / Client Secret) 를 4 곳에서 찾던 옛 방식 폐기 — 확장 한 번 열면 catalog 자동 suggest. Claude Code 로컬 앱은 같은 claude.ai 계정 로그인 시 자동 sync.

URL: https://docs.axelabs.ai/onboard/claude-connectors

# AXE MCP connectors

axelabs 가 운영하는 MCP server (Frame · Hive · Blueprint 등) 를 본인 Claude 에 등록하는 표준 절차. 4 필드 (이름 / URL / Client ID / Client Secret) 를 4 곳에서 찾던 옛 방식 ([/onboard/claude-frame-setup](/onboard/claude-frame-setup) — legacy, MCP 마다 반복) 폐기. Bitwarden 브라우저 확장이 vault `MCP Connectors` collection 에서 URI 매칭으로 자동 suggest ([D-vault-mcp-catalog](/ops/decisions)).

> **커넥터는 claude.ai 웹 챗 통합용.** 터미널·Claude Code·Codex·Cursor·cron 처럼 셸이 있는 곳에선 커넥터를 서비스마다 등록할 필요 없이 [AXE CLI](/services/cli) 한 줄 복붙 — 로그인 1회로 전 서비스. 그 페이지의 **"에이전트에 붙여넣기"** 블록을 본인 에이전트에 그대로 붙이면 끝.

## AI 요청 프롬프트

```
https://docs.axelabs.ai/onboard/claude-connectors 따라 내 머신에 AXE MCP connector 추가해줘.

진행:
1. 내 OS + 브라우저 확인 (Chrome/Firefox/Safari/Edge)
2. Bitwarden 브라우저 확장 설치 + 본인 vault server URL 등재 + unlock 상태 진단
3. 본인 claude.ai 회사 이메일 로그인 확인
4. 페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음
5. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
6. Claude Code 로컬 앱 (macOS/Windows) 자동 sync 검증
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- AXE 임직원 (`@axellc.com`) 또는 customer 직원 (`@<customer-domain>`) email
- 본인 AXE Vaultwarden 계정 (운영자 / customer IT 가 Entra SSO 가입 완료) + `MCP Connectors` collection access 권한
- 본인 claude.ai 계정 — **회사 이메일** 로그인 (개인 gmail 등 불가)
- 머신: macOS / Windows / Linux + 모던 브라우저

## Step 1: Bitwarden 브라우저 확장 install + vault server 등재

(이미 설치 + 로그인 돼 있으면 skip → Step 2)

### Chrome / Edge / Brave

[Chrome Web Store — Bitwarden Password Manager](https://chrome.google.com/webstore/detail/bitwarden-password-manage/nngceckbapebfimnlniiiahkandclblb) 에서 추가.

### Firefox

[Mozilla Add-ons — Bitwarden Password Manager](https://addons.mozilla.org/firefox/addon/bitwarden-password-manager/).

### Safari

App Store → "Bitwarden Password Manager" 설치 + Safari 환경설정 → 확장 프로그램 → Bitwarden 체크.

### Self-hosted server 등재 (필수)

확장 아이콘 클릭 → 로그인 화면 좌하단 **Settings** (gear) → **Self-hosted environment** → **Server URL** 에:

| Customer | Server URL |
|---|---|
| axe (`@axellc.com` 직원) | `https://axe.axelabs.ai/vault` |
| realchoice (`@realchoice.co.kr`) | `https://realchoice.axelabs.ai/vault` |
| (다른 customer) | 운영자 / customer IT 가 안내 |

Save → 확장 화면 복귀 → **Log in** → 회사 이메일 + 마스터 비밀번호 → unlock.

검증: 확장 popup 안에 본인 vault items 가 보이면 OK. **MCP Connectors** collection 클릭 시 N 개 (axe = 3 개: `Frame MCP (axe)` / `Hive MCP (axe)` / `Blueprint MCP (axe)`) 보이면 ready.

> realchoice 외 customer 는 customer 측 vault 의 `MCP Connectors` collection 이 아직 미구축 가능 (Q3 sovereignty 마일스톤). 비어있으면 customer IT 에게 catalog 구축 요청 — 임시 우회는 옛 [/onboard/claude-frame-setup](/onboard/claude-frame-setup) hand-find 절차.

## Step 2: claude.ai 의 Custom Connector 추가 화면 열기

[claude.ai](https://claude.ai) → 우측 상단 프로필 → **Settings** → **Connectors** → **Custom connectors** → **+ Add Custom Connector** 클릭.

폼이 열림 — 4 필드:

- **Name** (텍스트)
- **Remote MCP server URL** (URL)
- **Advanced** ▼ 펼치기 →
  - **OAuth Client ID** (텍스트)
  - **OAuth Client Secret** (password)

> 이 폼이 열린 상태로 다음 Step. 닫지 말 것.

## Step 3: Bitwarden 확장에서 catalog item 의 4 필드 가져오기

브라우저 주소창이 `https://claude.ai/customize/connectors` (또는 `https://claude.com/customize/connectors`) 인 상태에서 **Bitwarden 확장 아이콘 클릭**. URI 매칭으로 `MCP Connectors` collection 의 항목들이 popup 상단 **"Items for this site"** 섹션에 자동 suggest:

- `Frame MCP (axe)`
- `Hive MCP (axe)`
- `Blueprint MCP (axe)`

등록할 MCP 클릭 → 상세 화면. 각 필드의 **copy 버튼** ⎘ 으로 claude.ai 폼에 paste:

| Bitwarden 항목 필드 | claude.ai 폼 필드 | 메모 |
|---|---|---|
| **Name** (= item 제목, 예: `Frame MCP (axe)`) | Name | 본인 화면 라벨 — 짧게 줄여도 OK (예: `Frame`) |
| **Username** (= OAuth client_id GUID) | OAuth Client ID | Bitwarden 자동입력 가능성 있음 — 작동 안 하면 copy + paste |
| **Password** (= OAuth client_secret, 마스킹됨) | OAuth Client Secret | popup 의 👁 아이콘으로 잠시 확인 가능. 자동입력 가능성 있음 — 작동 안 하면 copy + paste |
| **Custom field "MCP URL"** | Remote MCP server URL | 표준 form field 아님 → 항상 copy + paste |

> 💡 Client ID 와 Client Secret 의 차이: Client ID 는 공개 식별자 (메일 평문 전달 OK), Client Secret 은 비밀번호 (절대 노출 X). vault 가 두 값 모두 단일 SoT 로 관리 → 본인 손에 메모/종이 보관 0.

> Bitwarden 의 자동입력 동작 여부는 claude.ai 폼의 필드 attribute (`autocomplete`, `type="password"` 등) 에 따라 다름. 자동입력 실패해도 popup 의 copy 버튼 4 클릭 으로 4 필드 채움 — 옛 방식 (4 곳 hand-find) 대비 결정적 단축.

## Step 4: Connect → Microsoft 로그인 → 첫 사용 시 동의

폼 4 필드 채운 후 **Connect** 버튼 → 브라우저가 Microsoft 로그인으로 redirect:

1. 회사 이메일 입력 (`firstname.lastname@axellc.com` 또는 customer 도메인)
2. 비밀번호 / Authenticator
3. **(첫 사용 시) 동의 화면** — `Access <MCP-name> MCP` 권한 요청 → **Accept** 클릭
4. 자동으로 claude.ai 복귀
5. Connector 상태 = **"Connected"** (녹색 점) → 성공

> 두 번째 이후 등록 (같은 customer 의 다른 MCP) 은 같은 Microsoft 계정이라 동의 화면 skip — 바로 Connected.

## Step 5: 동작 확인

claude.ai 새 채팅에서 자연어 호출:

| MCP | 자연어 예시 | Claude 가 호출하는 tool |
|---|---|---|
| Frame | `axec 의 5월 미결 항목 5 개 보여줘` | `Frame:list_open_items` |
| Frame | `axec 4월 시산표` | `Frame:query_trial_balance` |
| Hive | `이번 주 휴가 신청 보여줘` | `Hive:leave_get_request` |
| Hive | `내 급여 명세 5월` | `Hive:payroll_get_my_payslip` |
| Blueprint | `오늘 일정 추가: 14:00 회의실 A` | `Blueprint:create_event` |
| Blueprint | `Teams 메시지 본문 fetch <link>` | `Blueprint:get_teams_message` |

Claude 가 tool 호출 + 결과 자연어 정리 → 성공.

같은 절차로 나머지 MCP 도 Step 2~4 반복. catalog 가 3 개 다 보유 — **3 개 모두 등록 권장** (한 번 등록 후 영구 사용).

## Step 6: Claude Code 로컬 앱 자동 sync

같은 claude.ai 계정으로 **Claude Code 네이티브 앱** (macOS / Windows) 에 로그인하면 위에서 등록한 connector 들이 **자동 동기화** — 별도 설정 X.

검증:

1. Claude Code 앱 열기
2. `/status` → "Anthropic Account" 줄에 본인 회사 이메일 표시
3. `/mcp` → 위에서 등록한 connector 들이 목록에 보임 (`Frame` / `Hive` / `Blueprint` 등, claude.ai connector 표식 함께)
4. 채팅에서 자연어로 호출 가능

> Cursor / Cline / Witsy 같은 다른 MCP host 는 각자 별도 설정 — 본 페이지 범위 밖. 표준 `mcpServers` JSON 패턴은 동일하므로 catalog 의 4 필드 값 그대로 활용 가능 (각 host 의 config 형식만 차이).

## 함정 정리

| # | 증상 | 원인 | 우회 |
|---|---|---|---|
| 1 | Bitwarden 확장 popup 에 `MCP Connectors` collection 보이지 않음 | vault sync 안 됨 / unlock 만료 / 다른 customer vault server 에 로그인 | 확장 → Settings → **Sync vault** 클릭 / 확장 lock → unlock 재실행 / Step 1 의 server URL 본인 customer 와 일치 확인 |
| 2 | claude.ai 페이지에서 확장 클릭 시 매칭 항목 0 — 다른 사이트의 일반 item 만 보임 | catalog item 의 URI 가 등록되지 않음 (catalog 갱신 누락) | 운영자 (`ai@axellc.com`) 에게 보고 — `axe mcp publish` 재실행 필요. 임시 우회 = `MCP Connectors` collection 을 확장 안에서 직접 열어 item 수동 copy |
| 3 | Bitwarden 자동입력이 OAuth Client ID/Secret 칸에 작동 안 함 | claude.ai 폼의 필드 attribute 가 표준 `username`/`password` 아님 | popup 의 각 필드 옆 **copy 버튼** 사용 + 폼에 paste (4 클릭) — 정상 우회 |
| 4 | "Remote MCP server URL" 칸이 자동입력 안 됨 | URL 은 custom field (`MCP URL`) 라 표준 form field 아님 | item popup → Custom fields 섹션 → MCP URL 옆 copy 버튼 → 폼에 paste — 항상 manual (claude.ai 폼 구조상 영구) |
| 5 | Connect 클릭 후 Microsoft → `AADSTS50011: redirect_uri mismatch` | 본인 customer 외 다른 customer 의 URL 입력 (예: realchoice 직원이 axe URL) | Step 1 의 customer 별 server URL 표 + Step 3 의 item 본인 customer 의 것 확인 |
| 6 | Connect 후 Microsoft → `AADSTS500011: resource not found` | MCP app 의 `application_id_uri` 가 본인 회사 Entra tenant 에 등록 안 됨 (다른 customer 의 vault item 일 수 있음) | 본인 customer 의 vault 사용 확인 / 운영자 / customer IT 에 보고 |
| 7 | 동의 화면이 안 뜨고 바로 Connected | 이미 처음 한 번 동의함 — 재동의는 Settings → Connectors → Disconnect → re-Connect 시점에만 발생 | 정상. 권한 변경 필요 시 Disconnect 후 재연결 |
| 8 | Connected 표시 후에도 채팅에서 tool 호출 안 됨 | claude.ai 가 tool 목록 fetch 중 또는 connector 비활성 | 1~2 분 대기 후 새 채팅 / Settings → Connectors → 본 connector toggle off → on |
| 9 | Bitwarden 확장에 master password 입력 후에도 `MCP Connectors` 안 보임 | 본인이 해당 collection 의 멤버 아님 (organization 권한 미부여) | 운영자 (`ai@axellc.com`) 에게 본인 email 으로 collection access 요청. axe 측 = ai / soohun / taehun / jinwoo 4명 기본 access |
| 10 | Claude Code 네이티브 앱에 `/mcp` 가 비어있음 (Step 6) | claude.ai 와 다른 Anthropic 계정으로 로그인됨 / sync 지연 | `/login` → claude.ai 와 같은 회사 이메일 / Claude Code 앱 재시작 → 1~2 분 대기 |

## 매 작업 시 사전 작업

| 빈도 | 작업 | 자동화 |
|---|---|---|
| 1회 (초기 setup) | Step 1~4 (extension + vault + claude.ai 등록) | — |
| Vault timeout 마다 | Bitwarden 확장 unlock (master password) | ✅ Bitwarden 의 vault timeout 설정 (확장 → Settings → Vault timeout) |
| Secret rotation 발생 시 | (없음 — 운영자가 `axe secret rotate` 실행 시 catalog 자동 재발행, Bitwarden sync 후 확장에서 새 secret 자동) | ✅ [D-vault-mcp-catalog](/ops/decisions) step 4.5 hook |
| 매 claude.ai 사용 | (없음) | — |

## 참조

- [D-vault-mcp-catalog](/ops/decisions) — 본 catalog 모델 (Vaultwarden org collection + `axe mcp publish` CLI + `axe secret rotate` 자동 hook)
- [/architecture/secrets#mcp-connectors-catalog-d-vault-mcp-catalog-2026-05-26](/architecture/secrets) — catalog 구조 도식 + 신규 MCP 추가 3-step 표준 절차
- [/onboard/claude-frame-setup](/onboard/claude-frame-setup) — Frame 단독 connector 옛 절차 (4 필드 hand-find, legacy — 본 페이지로 대체 권장)
- [/onboard/vault-setup](/onboard/vault-setup) — Vault setup 표준 (KDF + 4 client 셋업)
- [/onboard/m365-connector](/onboard/m365-connector) — Microsoft 365 connector (별 MCP 가 아님, 보조 reading)
- [B-customer-sovereignty-architecture](/ops/backlog) — customer 측 vault catalog 분리 (Q3 milestone)
- [/ops/known-gaps](/ops/known-gaps) "매니페스트 / vault 측 미해결" — bw cache stale 함정 (운영자 측, end-user 무관)

---

<!-- PAGE https://docs.axelabs.ai/onboard/claude-frame-setup -->

# Frame connector 설정

> claude.ai 에 회사 회계 시스템 (Frame) 연결하는 5분 절차.

URL: https://docs.axelabs.ai/onboard/claude-frame-setup

# Frame connector 설정 (claude.ai)

> **🔁 신규 권장 절차** = [/onboard/claude-connectors](/onboard/claude-connectors) (Bitwarden 확장 + AXE Vault `MCP Connectors` collection 으로 Frame 포함 모든 MCP 한 번에 자동 suggest). 본 페이지는 단일 connector 의 hand-find 절차 (legacy, 2026-05-26 이전) 보존용.

회사 회계 시스템 (Frame) 에 claude.ai 에서 자연어로 접근하기 위한 1회 설정.

## 본인 단계 (5분)

### 1. claude.ai 에 회사 이메일로 로그인

[claude.ai](https://claude.ai) → 회사 이메일 (`@axellc.com` 또는 본인 회사 도메인) 로 로그인.

> 개인 이메일 (gmail 등) 로 가입한 계정은 회사 데이터 접근 불가. 회사 이메일 사용 필수.

### 2. Custom Connector 추가

claude.ai 우측 상단 프로필 → **Settings** → **Connectors** → **Custom connectors** → **+ Add Custom Connector** 클릭.

### 3. 입력값 4 개

| 필드 | 값 | 비밀성 |
|---|---|---|
| **Name** | `Frame` | 공개 (자기 화면 라벨) |
| **Remote MCP server URL** | `https://axe.axelabs.ai/frame/mcp` (또는 회사 URL) | 공개 |
| **Advanced** 펼치기 ↓ | | |
| **OAuth Client ID** | 운영자가 준 GUID (예: `137fc0ef-...`) | **공개** (ID 일 뿐 — 메일에 평문 OK) |
| **OAuth Client Secret** | 운영자가 준 secret 값 | **비밀** (Bitwarden Send 1회용 링크로만 전달됨, 입력 후 잊으세요) |

> 💡 Client ID 와 Client Secret 의 차이: Client ID 는 "회사 출입증 번호 = 누구라도 봐도 됨", Client Secret 은 "비밀번호 = 절대 노출 X". 둘 다 함께 있어야 인증 가능.

> URL 은 본인 회사 (customer) 에 따라 다릅니다. 운영자가 안내한 URL 사용:
> - axe customer (axellc.com 직원): `https://axe.axelabs.ai/frame/mcp`
> - realchoice customer (realchoice.co.kr 직원): 운영자가 onboard 완료 후 통지 (배포 시점에 활성)
>
> 다른 customer 의 URL 입력 시 Microsoft 가 redirect_uri mismatch (AADSTS50011) 로 거부합니다.

> Client ID 는 평문으로 (Teams/메일 OK), Client Secret 은 Vaultwarden 의 Bitwarden Send 1회용 링크로 전달됩니다. 링크는 1회 열람 후 자동 무효 — 받자마자 connector 화면에 붙여 넣고 닫으세요. (운영자 측 절차: [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send))

### 4. Connect → Microsoft 로그인

`Connect` 버튼 클릭 → 브라우저가 Microsoft 로그인 페이지로 이동:

1. 회사 이메일 입력 (`firstname.lastname@axellc.com` 등)
2. 비밀번호 입력 (또는 Authenticator 앱)
3. **첫 사용 시 동의 화면** — `Access Frame MCP` 권한 요청 → **Accept** 클릭
4. 자동으로 claude.ai 로 복귀
5. Connector 상태가 **"Connected"** (녹색) 로 표시되면 성공

### 5. 동작 확인

claude.ai 새 채팅에서:

```
axec 의 5월 미결 항목 5개 보여줘
```

Claude 가 `Frame:list_open_items` 호출하고 결과를 자연어로 정리해서 보여주면 끝.

## Claude Code 네이티브 앱 자동 동기화

같은 claude.ai 계정으로 Claude Code 네이티브 앱 (macOS / Windows) 에 로그인하면 **자동으로 connector 가 동기화** 됩니다 — 별도 설정 불필요.

확인:
1. Claude Code 앱 열기
2. `/status` 입력 → "Anthropic Account" 줄에 본인 이메일 표시
3. `/mcp` 입력 → `Frame` connector 가 목록에 보임 (claude.ai connector 표식 함께)
4. 채팅에서 `axec 의 미결 5개` 등 자연어로 호출

## 일반 흐름

설정 완료 후 자주 쓰는 패턴:

| 자연어 | Frame tool |
|---|---|
| "axec 의 5월 매출은?" | query_balance, list_journals |
| "axec 의 미결 항목 보여줘" | list_open_items |
| "axec 와 axev 의 이번 분기 잔액 비교" | query_balance × 2 |
| "axec 에 매출 1000만원 계상" | post_journal (write 권한 필요) |
| "axec 의 4월 시산표" | query_trial_balance |
| "axec 의 5월 분개장" | list_journals |
| "은행 입출금 파일 업로드: 파일첨부" | ingest_file_blob (write) |

## 보안 권장

- **Client Secret 을 다른 채널에 보관하지 마세요** — claude.ai 의 Advanced 칸에만 입력. 한 번 입력하면 다시 볼 일 없습니다.
- **공용 PC 에서 claude.ai 로그인 후 로그아웃 잊지 마세요** — connector 가 활성 상태로 노출됨.
- **회사 이메일이 의심스럽게 사용된 흔적이 있으면** 즉시 `ai@axellc.com` (운영자) 에게 신고.

## 문제 발생 시

[/onboard/troubleshooting](/onboard/troubleshooting) 참조 또는 운영자에게 다음 정보 전달:

1. 어느 단계에서 막혔는지
2. 오류 메시지 전문 (특히 `AADSTS` 코드)
3. 브라우저 주소창의 전체 URL

## 다음

- [Microsoft 365 connector](/onboard/m365-connector) — OneDrive·Outlook·Teams 통합 (선택)
- [문제 해결 모음](/onboard/troubleshooting)

---

<!-- PAGE https://docs.axelabs.ai/onboard/m365-connector -->

# Microsoft 365 connector

> OneDrive · Outlook · Teams 통합 (Anthropic 제공).

URL: https://docs.axelabs.ai/onboard/m365-connector

# Microsoft 365 connector

## AI 요청 프롬프트

```
https://docs.axelabs.ai/onboard/m365-connector 따라 본인 claude.ai 에 Microsoft 365 connector 추가해줘.

진행:
1. 본인 claude.ai 회사 이메일 (`@axellc.com` 또는 customer 도메인) 로그인 확인
2. 페이지 "Frame connector 와 무관" 표 따라 별도 인증 컨텍스트 인식 (M365 토큰 ≠ Frame 토큰, Anthropic 운영)
3. 페이지의 설정 5 step (claude.ai/customize/connectors → Microsoft 365 찾기 → Connect → Microsoft 로그인 → 권한 5종 동의) 매 step 결과 받고 다음
4. 함정 — 회사 IT 가 외부 OAuth app consent 차단 시 admin consent 요청 (요청 권한 5종 = User.Read · Mail.Read · Files.Read.All · Sites.Read.All · ChannelMessage.Read.All)
5. "Connected" 상태 확인 + 페이지 "사용" 예시 1개 (지난주 메일 검색 등) 으로 토큰 동작 검증
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

Anthropic 이 제공하는 공식 connector. 회사 이메일·OneDrive·Teams 메시지·SharePoint 파일에 Claude 가 read-only 로 접근.

## Frame connector 와 무관

M365 connector 는 Anthropic 이 운영합니다. Frame connector 와 **별도 인증** 합니다. 두 connector 의 토큰은 서로 공유되지 않습니다.

| connector | 운영자 | 데이터 |
|---|---|---|
| Frame | AXE Labs (본인 회사 macmini) | 회계 |
| M365 | Anthropic | OneDrive · Outlook · Teams · SharePoint |

## 설정 (2분)

1. [claude.ai/customize/connectors](https://claude.ai/customize/connectors) → **Microsoft 365** connector 찾기 (Anthropic 공식 목록)
2. **Connect** 클릭
3. Microsoft 로그인 (회사 이메일)
4. 권한 동의:
   - User.Read
   - Mail.Read
   - Files.Read.All
   - Sites.Read.All
   - ChannelMessage.Read.All (Teams)
5. 자동 복귀, "Connected" 상태

## 사용

```
지난주 ai@axellc.com 한테 온 메일 중 'invoice' 키워드 있는 것 요약

→ Microsoft 365:search_emails 호출
```

```
Finance OneDrive 폴더 의 2026-05 파일 목록

→ Microsoft 365:list_files 호출
```

```
Teams '회계' 채널 의 최근 5일 메시지 보여줘

→ Microsoft 365:list_channel_messages 호출
```

## Frame 과 조합 활용

```
OneDrive Finance/2026-05 폴더의 carddata.xlsx 를 frame axec 에 ingest 해줘

→ 1. Microsoft 365:download_file (read)
→ 2. Frame:ingest_file_blob (write to axec)
```

이렇게 두 connector 가 협업.

## 보안

- M365 connector 는 **read-only** — Claude 가 OneDrive 의 파일을 수정/삭제할 수 없음. (read 만)
- 토큰은 Anthropic 백엔드에 암호화 저장. 직원이 직접 볼 수 없음.
- 직원이 access 권한 가진 파일만 Claude 가 봄 — 권한 자체는 회사 Microsoft 365 의 권한 그대로.

## 관련

- [Anthropic 공식 문서](https://support.claude.com/en/articles/12542951-enable-and-use-the-microsoft-365-connector)
- [M365 보안 가이드](https://support.claude.com/en/articles/12684923-microsoft-365-connector-security-guide)

---

<!-- PAGE https://docs.axelabs.ai/onboard/ssh-access -->

# SSH 로컬 작업 (Claude Code / Cursor / 기타 AI session)

> AXE macmini 에 SSH 진입해 로컬 작업하는 표준 절차. 사람이 read 하거나, AI session 에 본 페이지 URL 을 던지면 step-by-step interactive 진행.

URL: https://docs.axelabs.ai/onboard/ssh-access

# SSH 로컬 작업

## AI 요청 프롬프트

```
https://docs.axelabs.ai/onboard/ssh-access 따라 내 머신을 SSH 셋업해줘.

진행:
1. 내 머신 OS 진단 (Windows/macOS/Linux)
2. 기존 환경 확인 (cloudflared 설치, ~/.ssh/id_ed25519 존재, ~/.ssh/config 등)
3. 페이지의 각 Step 명령 실행 + 검증, 매 step 결과 받고 다음
4. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
5. Step 3 server-side 등록 = 운영자 ai (ai@axellc.com) 에 Teams DM 으로 내 public key + email 전달, 회신 받고 다음 진행
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- AXE 임직원 (`@axellc.com`) 또는 customer 직원 (해당 customer 도메인) email
- Microsoft Entra SSO 가능 — 본인 회사 IT 가 Entra 직원 등록 완료
- 머신: Windows 10/11 또는 macOS 또는 Linux

## Step 1: cloudflared 설치

### Windows

```powershell
winget install --id Cloudflare.cloudflared
```

설치 후 **새 PowerShell 창** 열어서 검증:

```powershell
cloudflared --version
```

함정: 같은 PowerShell 창 안에서 검증 시 `cloudflared : The term 'cloudflared' is not recognized` — PATH 환경변수가 같은 shell session 에 갱신 안 됨. **새 창** 필수.

### macOS

```bash
brew install cloudflare/cloudflare/cloudflared
```

### Linux

[Cloudflare 공식 install guide](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/).

## Step 2: ed25519 keypair 생성

본인 머신에 SSH key 가 없으면 생성:

```
ssh-keygen -t ed25519 -C "<your-email>@axellc.com"
```

기본 경로 (Enter 로 수락):

- Windows: `C:\Users\<You>\.ssh\id_ed25519`
- macOS / Linux: `~/.ssh/id_ed25519`

passphrase 입력 권장 (key 유출 시 안전장치).

검증 (public key 출력):

```
cat ~/.ssh/id_ed25519.pub
```

출력 예:

```
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIIzszmDFVQCu3ViuGwWV2NatlLhYozWalisAtw6xgQWh you@axellc.com
```

## Step 3: server-side 등록 (운영자 ai 처리)

본인 public key 한 줄을 운영자 ai (`ai@axellc.com`) 에게 전달. 방법 2가지:

**A. Teams DM 으로 전달** — 본인 1:1 채팅에 paste. 운영자 ai 가 메시지 받으면 자동 처리.

**B. AI session 자동 forward** — 본인 Claude Code session 이 본 페이지 따라 진행 중이면 자동으로 운영자 ai 에 메시지 발송 (Blueprint MCP `get_teams_message` 패턴 — [B-bp-mcp-teams-admin-consent](/ops/backlog) 완료 후).

운영자 ai 가 수행하는 작업 (참고):

```bash
# (a) public key append to axe user's authorized_keys (codebase 작업용)
#     ⚠️ axe 는 공용 계정 — install 은 destination replace 라 기존 직원 키 전부 삭제됨.
#     반드시 tee -a 로 append. 권한·소유자는 기존 file 의 것이 유지됨 (file 이 이미 600/axe:staff).
echo "<your-pubkey-one-line>" | sudo /usr/bin/tee -a /Users/axe/.ssh/authorized_keys >/dev/null

# (b) SACL 추가 (PAM pam_sacl.so 통과)
sudo /usr/sbin/dseditgroup -o edit -a <your-shortname> -t user com.apple.access_ssh

# (c) (선택) 본인 home directory 도 SSH 진입 허용 — 본인 personal 작업 시 (첫 등록 시만 install OK)
sudo /usr/bin/install -d -m 700 -o <your-shortname> -g dev /Users/<your-shortname>/.ssh
sudo /usr/bin/install -m 600 -o <your-shortname> -g dev <tmp-key-file> /Users/<your-shortname>/.ssh/authorized_keys
# 두 번째 키 추가 시에는 (a) 처럼 tee -a 로 append.
```

전부 NOPASSWD whitelist 안 (`tee /Users/*` / `install` / `chown` / `dseditgroup`) — 운영자 password 입력 불요.

운영자 ai 회신 받으면 다음 step.

## Step 4: ~/.ssh/config 작성

### Windows (PowerShell)

```powershell
@'
Host axe-macmini
  HostName ssh-axe.axelabs.ai
  User axe
  ProxyCommand "C:\Program Files (x86)\cloudflared\cloudflared.exe" access ssh --hostname %h
  IdentityFile ~/.ssh/id_ed25519
'@ | Out-File -Encoding ascii -FilePath $env:USERPROFILE\.ssh\config
```

### macOS / Linux

```bash
cat <<'EOF' >> ~/.ssh/config

Host axe-macmini
  HostName ssh-axe.axelabs.ai
  User axe
  ProxyCommand cloudflared access ssh --hostname %h
  IdentityFile ~/.ssh/id_ed25519
EOF
```

설명:

- `HostName ssh-axe.axelabs.ai` — Cloudflare Tunnel 의 public hostname. 옛 `ssh.axe.axelabs.ai` 폐기됨 ([D-ops-39](/ops/decisions)).
- `User axe` — OS account = `axe` (AXE platform codebase 공통 위치 `/Users/axe/` 진입). audit 식별은 Cloudflare Access SSO log + ssh key fingerprint + git author 3중.
- `ProxyCommand cloudflared access ssh --hostname %h` — Cloudflare Access SSH 게이트 통과. Windows 는 절대 경로 + 따옴표.

## Step 5: Cloudflare Access 인증 (24h 1회)

```
cloudflared access login https://ssh-axe.axelabs.ai
```

브라우저 자동 열림 → Microsoft 로그인 (본인 email) → 완료. JWT 토큰 발급 (24h 유효, `session_duration: "24h"` per Access app 설정).

## Step 6: 첫 ssh 시도

```
ssh -o StrictHostKeyChecking=accept-new axe-macmini
```

`accept-new` = 첫 시도 시 host fingerprint 자동 등록 (사람 prompt 없이). `axe@AXEs-Mac-mini ~ %` prompt 떨어지면 성공.

함정: 단순 `ssh axe-macmini` 시도 시 `Host key verification failed` — host key prompt 가 non-interactive shell 에서 답을 못 받음. 반드시 `accept-new` 옵션.

## Step 7: AI session 등록 (Claude Code / Cursor / 등)

### Claude Code (Windows) — ProxyCommand 미지원 함정

Claude Code Windows native app 의 SSH backend 는 OpenSSH `ProxyCommand` 를 호출 안 함 → 동일 `~/.ssh/config` 인데 PowerShell 의 `ssh axe-macmini` 는 통과, Claude Code 는 timeout/handshake fail.

**우회 = cloudflared TCP forward** (PC 부팅 후 1회):

```powershell
Start-Process -FilePath "C:\Program Files (x86)\cloudflared\cloudflared.exe" -ArgumentList 'access tcp --hostname ssh-axe.axelabs.ai --url localhost:2222'
```

background 창이 자동으로 뜸 — 그대로 둠 (작업 종료 시까지).

첫 등록 시 known_hosts 추가:

```
ssh -o StrictHostKeyChecking=accept-new -p 2222 axe@localhost
```

Claude Code SSH 연결 다이얼로그:

- 이름: `axe-macmini`
- SSH 호스트: `axe@localhost`
- SSH 포트: `2222`
- Identity File: `~/.ssh/id_ed25519`

저장 → New Session → axe-macmini 선택 → `/Users/axe/` 하위 폴더 (axelabs, axelabs-docs, frame, hive, blueprint, .axe 등) 보임.

### Claude Code (macOS) — ProxyCommand 정상

macOS native ssh backend 라 ProxyCommand 작동. Step 4 의 `~/.ssh/config` 그대로 + Claude Code 다이얼로그에 host = `axe@axe-macmini`. TCP forward 불필요.

### TCP forward 자동화 (Windows, user-context Scheduled Task + VBS wrapper)

cloudflared TCP forward 를 PowerShell 창에서 띄우면 창 종료 시 같이 죽음 (함정 #9).
NSSM 등으로 SYSTEM 서비스화하면 JWT 토큰 격리로 origin 인증 무한 루프 (함정 #10).
PowerShell `-WindowStyle Hidden` 는 초기 깜빡임이 있음 (함정 #13).
Task 의 `-RestartCount` 는 FAILURE 에만 발동 — cloudflared 정상 종료 시 silent 중단 (함정 #14).

해결 = **user-context Scheduled Task + VBScript 무한 루프 wrapper**:

- `wscript.exe` 호스팅 → 깜빡임 0
- VBS 내부 루프 → 어떤 종료 코드든 5초 뒤 재기동
- Hidden + AtLogOn + 본인 계정 → 본인 끌 UI 0

**Setup (관리자 PowerShell 한 번에)**:

```powershell
New-Item -ItemType Directory -Path 'C:\ProgramData\cloudflared-ssh-axe' -Force | Out-Null

# VBScript wrapper — 0-flash + 무한 재시작
@'
Set sh = CreateObject("WScript.Shell")
Do
    sh.Run """C:\Program Files (x86)\cloudflared\cloudflared.exe"" access tcp --hostname ssh-axe.axelabs.ai --url localhost:2222", 0, True
    WScript.Sleep 5000
Loop
'@ | Out-File -FilePath 'C:\ProgramData\cloudflared-ssh-axe\tcp-forward.vbs' -Encoding ascii

# Task 등록
$action    = New-ScheduledTaskAction -Execute 'wscript.exe' `
    -Argument '"C:\ProgramData\cloudflared-ssh-axe\tcp-forward.vbs"'
$trigger   = New-ScheduledTaskTrigger -AtLogOn -User "$env:USERDOMAIN\$env:USERNAME"
$principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" -LogonType Interactive
$settings  = New-ScheduledTaskSettingsSet -StartWhenAvailable `
    -DontStopIfGoingOnBatteries -AllowStartIfOnBatteries `
    -ExecutionTimeLimit ([TimeSpan]::Zero) -Hidden

Register-ScheduledTask -TaskName 'cloudflared-ssh-axe-tcp' `
    -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force

Start-ScheduledTask -TaskName 'cloudflared-ssh-axe-tcp'
```

**검증**:

```powershell
Start-Sleep -Seconds 5
Get-NetTCPConnection -LocalPort 2222 -State Listen
Get-Process cloudflared, wscript -ErrorAction SilentlyContinue | Select-Object Name, Id, StartTime

# 가시적 창 0 확인
Get-Process cloudflared, wscript -ErrorAction SilentlyContinue |
    Where-Object { $_.MainWindowHandle -ne 0 } |
    Select-Object Name, Id, MainWindowTitle
```

마지막 쿼리가 빈 결과 = 진짜 hidden. 포트 2222 LISTENING + 프로세스 살아있으면 성공.

**작동 특성**:

- PowerShell 창 종료: cloudflared 살아있음 (task scheduler 자식 프로세스 트리)
- cloudflared 정상/비정상 종료: VBS 루프가 5초 뒤 재실행 (`-RestartCount` 의존성 0)
- 로그오프: cloudflared/wscript 죽음 → 재로그인 시 AtLogOn 자동 부활
- PC 재부팅: 로그온 후 자동 시작
- 본인 계정 컨텍스트로 실행 → `~/.cloudflared/` 토큰 캐시 공유 (renewal task 와 동일)
- 가시적 창 0개 — 작업 관리자 "세부 정보" 또는 작업 스케줄러 GUI 까지 가야 보임

## Token 자동 갱신 (Windows)

기존 문서: 24h 마다 사람이 `cloudflared access login` 수동 실행. 이를 자동화하는 self-rescheduling Scheduled Task.

**설계 원칙**:

- **폴링 없음** — 토큰의 실제 `exp` claim 을 파싱해서 그 시점에만 fire (24h 주기 task fire 2~3회)
- **만료 5분 전 미리 갱신** → 다운타임 0
- **Self-rescheduling** — task 가 자기 trigger 를 재예약 (외부 cron 불필요)
- **사람 클릭 0회 (조건부)** — Microsoft "로그인 상태 유지" 켜져 있으면 갱신 시 브라우저 깜빡 → SSO 자동 통과

**중요 — `-RunLevel Highest` 필수** (함정 #11): task 가 자기 자신의 `Set-ScheduledTask` 호출해야 해서 elevated 필요. Interactive 만으로는 `Access is denied`.

### Setup (관리자 PowerShell 한 번에)

```powershell
$dir = 'C:\ProgramData\cloudflared-ssh-axe'
New-Item -ItemType Directory -Path $dir -Force | Out-Null

@'
#Requires -Version 5.1
$ErrorActionPreference = 'Stop'

$Config = @{
    Cloudflared             = 'C:\Program Files (x86)\cloudflared\cloudflared.exe'
    AppUrl                  = 'https://ssh-axe.axelabs.ai'
    LogPath                 = 'C:\ProgramData\cloudflared-ssh-axe\renewal.log'
    TaskName                = 'cloudflared-token-renewal'
    RenewWindowMinutes      = 5
    PostLoginRecheckMinutes = 5
    FallbackRetryMinutes    = 60
}

function Write-Log {
    param([string]$Message)
    "$([DateTime]::Now.ToString('s'))  $Message" | Out-File $Config.LogPath -Append -Encoding utf8
    if ((Get-Item $Config.LogPath).Length -gt 1MB) {
        Get-Content $Config.LogPath -Tail 200 | Set-Content $Config.LogPath -Encoding utf8
    }
}

function Get-JwtExpiry {
    param([string]$Jwt)
    $payload = $Jwt.Trim().Split('.')[1].Replace('-','+').Replace('_','/')
    $payload += '=' * ((4 - ($payload.Length % 4)) % 4)
    $json = [Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($payload)) | ConvertFrom-Json
    [DateTimeOffset]::FromUnixTimeSeconds($json.exp).LocalDateTime
}

function Get-CurrentToken {
    try {
        $t = & $Config.Cloudflared access token "--app=$($Config.AppUrl)" 2>$null
        if ($LASTEXITCODE -eq 0 -and $t -and $t -notmatch 'Unable to find token|please login') {
            return $t.Trim()
        }
    } catch {}
    return $null
}

function Set-NextRun {
    param([DateTime]$When)
    $triggers = @(
        (New-ScheduledTaskTrigger -Once -At $When),
        (New-ScheduledTaskTrigger -AtLogOn)
    )
    Set-ScheduledTask -TaskName $Config.TaskName -Trigger $triggers | Out-Null
    Write-Log "next run: $($When.ToString('s'))"
}

function Invoke-Login {
    Start-Process $Config.Cloudflared -ArgumentList @('access','login',$Config.AppUrl) -WindowStyle Hidden
    Write-Log 'triggered: cloudflared access login'
}

try {
    $token = Get-CurrentToken
    if ($null -eq $token) {
        Invoke-Login
        Set-NextRun (Get-Date).AddMinutes($Config.PostLoginRecheckMinutes)
        return
    }

    $exp      = Get-JwtExpiry $token
    $minsLeft = [int]($exp - (Get-Date)).TotalMinutes
    Write-Log "token exp=$($exp.ToString('s')) (${minsLeft}min)"

    if ($minsLeft -lt $Config.RenewWindowMinutes) {
        Invoke-Login
        Set-NextRun (Get-Date).AddMinutes($Config.PostLoginRecheckMinutes)
    } else {
        Set-NextRun $exp.AddMinutes(-$Config.RenewWindowMinutes)
    }
}
catch {
    Write-Log "ERROR: $($_.Exception.Message)"
    try { Set-NextRun (Get-Date).AddMinutes($Config.FallbackRetryMinutes) } catch {}
    exit 1
}
'@ | Out-File -FilePath "$dir\renew-token.ps1" -Encoding utf8

$action    = New-ScheduledTaskAction -Execute 'powershell.exe' `
    -Argument '-NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File "C:\ProgramData\cloudflared-ssh-axe\renew-token.ps1"'
$trigger   = New-ScheduledTaskTrigger -Once -At (Get-Date).AddMinutes(1)
$principal = New-ScheduledTaskPrincipal -UserId "$env:USERDOMAIN\$env:USERNAME" `
    -LogonType Interactive -RunLevel Highest   # ← Highest 필수 (함정 #11)
$settings  = New-ScheduledTaskSettingsSet -StartWhenAvailable `
    -DontStopIfGoingOnBatteries -AllowStartIfOnBatteries

Register-ScheduledTask -TaskName 'cloudflared-token-renewal' `
    -Action $action -Trigger $trigger -Principal $principal -Settings $settings -Force
```

### 검증

```powershell
Start-ScheduledTask -TaskName 'cloudflared-token-renewal'
Start-Sleep -Seconds 3
Get-Content C:\ProgramData\cloudflared-ssh-axe\renewal.log -Tail 5
```

`token exp=... (NNNmin)` + `next run: ...` 두 줄 보이면 정상.
`ERROR: Access is denied` 가 보이면 `-RunLevel Highest` 누락 (함정 #11).

### (선택) 갱신 시 사람 클릭 0회

기본 브라우저에서 `https://account.microsoft.com` 로그인 시 **"로그인 상태를 유지하시겠습니까?" → 예**. 그러면 renewal task 가 `cloudflared access login` 트리거해도 Microsoft 가 자동 redirect → 사람 손 안 가는 상태.

조직 Entra 정책이 sticky session 차단하면 갱신 시점에 한 번씩 클릭은 필요 (정책 문제, client 우회 불가).

## (부록) NSSM/Windows 서비스화 시도가 실패하는 이유

직관적으로 cloudflared 를 Windows 서비스화하고 싶을 수 있음 — PowerShell 창 의존성 제거 + 로그오프 후에도 살아있음. 그러나 두 시나리오 모두 실패:

**A. SYSTEM 으로 실행 → 토큰 격리**

`cloudflared access login` 으로 받은 JWT 는 `%USERPROFILE%\.cloudflared\<app-id>-token.json` 에 저장. SYSTEM 서비스는 `C:\Windows\System32\config\systemprofile\.cloudflared\` 를 봄.

증상 (stderr.log):

```
failed to acquire app token lock: timed out waiting for lock file
  C:\Windows\System32\config\systemprofile\.cloudflared\...-token.lock
```

SYSTEM 서비스는 토큰 없으니 자체 login 시도 → SYSTEM 은 desktop session 없어서 브라우저 못 띄움 → 무한 "Waiting for login..." 루프.

**B. 사용자 계정으로 실행 → 패스워드 저장 문제**

`nssm set <svc> ObjectName .\<user> <password>` 또는 services.msc 의 Log On 탭에서 사용자 계정 + 패스워드 입력 필요. 평문 명령행 노출 + Microsoft 계정/Windows Hello 사용자는 패스워드 입력 자체 번거로움 + 계정 패스워드 변경 시 서비스 정지 (운영 부담).

**결론**

SSH 가 사람의 active session 에서만 의미 있음 (SSH 시도 = 본인 로그인 상태). 따라서 user-context Scheduled Task (AtLogOn + VBS wrapper) 가 NSSM 보다 깔끔:

- 패스워드 저장 0
- 토큰 캐시 자동 공유
- 본인 계정 컨텍스트 일관
- 본인 끌 UI 0 (가시적 창 0)
- VBS 무한 루프로 정상/비정상 종료 모두 자동 재기동

## 함정 정리

| # | 증상 | 원인 | 우회 |
|---|---|---|---|
| 1 | `cloudflared not recognized` (Windows) | PATH 미반영 | 새 shell 창 |
| 2 | `tls: handshake failure` (Windows: `SEC_E_ILLEGAL_MESSAGE`, macOS: `sslv3 alert handshake failure`) | hostname 2단 (e.g. `ssh.axe.axelabs.ai`) — Universal SSL 1-level | 평탄 hostname (`ssh-axe.axelabs.ai`), [D-ops-39](/ops/decisions) |
| 3 | pubkey 통과 후 `Connection closed by UNKNOWN port` | SACL `com.apple.access_ssh` 미가입 → PAM `pam_sacl.so` account 거부 | Step 3 (운영자 ai 가 `dseditgroup` 추가) |
| 4 | `Host key verification failed` (prompt 답 못 함) | non-interactive ssh | `-o StrictHostKeyChecking=accept-new` |
| 5 | Claude Code SSH timeout / handshake fail (PowerShell 직접 ssh 는 통과) | Claude Code 의 SSH backend 가 `ProxyCommand` 미지원 | TCP forward (Step 7) |
| 6 | `ssh: connect to host localhost port 2222: Connection refused` | cloudflared TCP forward background 안 띄움 | `Start-Process ... access tcp ...` (Step 7) |
| 7 | Claude Code 폴더 선택 시 axelabs / frame / hive 안 보임 | SSH user = 본인 shortname (본인 home 만 보임). AXE platform codebase 는 `/Users/axe/` | SSH user = `axe` (Step 4 의 config), git author = 본인 email (audit) |
| 8 | 24h 후 `cloudflared access ssh` 에러 / Microsoft 로그인 페이지 prompt | JWT 토큰 exp | `cloudflared access login https://ssh-axe.axelabs.ai` 재실행 (또는 § "Token 자동 갱신") |
| 9 | cloudflared TCP forward 가 PowerShell 창 종료 시 같이 죽음 | `Start-Process` 자식이 부모 종료에 종속 | user-context Scheduled Task + VBS wrapper (§ TCP forward 자동화) |
| 10 | NSSM 등으로 cloudflared 서비스화 후 stderr 에 `failed to acquire app token lock: ...\Windows\System32\config\systemprofile\.cloudflared\...` 무한 루프 | SYSTEM 프로필 토큰 캐시 비어있음. JWT 는 user-scoped 라 SYSTEM 컨텍스트와 격리 | 서비스화 금지. user-context Scheduled Task (§ TCP forward 자동화) |
| 11 | Token renewal task 가 `ERROR: Access is denied` 로 자기 trigger 수정 실패 | `Set-ScheduledTask` 는 elevated 권한 필요 | Principal 에 `-RunLevel Highest` |
| 12 | 24h 마다 SSO 재인증을 사람이 매일 수동 실행해야 함 | docs 기본 흐름이 수동 | Self-rescheduling renewal task (§ Token 자동 갱신) |
| 13 | `powershell.exe -WindowStyle Hidden` 으로 task action 구성 시 매 fire 마다 콘솔 창 깜빡임 | Windows 가 hidden flag 적용하기 전 수십 ms 노출 | TCP forward 같은 daemon 류는 `wscript.exe` + VBS wrapper 사용 (§ TCP forward 자동화) |
| 14 | Task `-RestartCount` 설정해도 cloudflared 정상 종료 (exit 0) 후 재시작 안 됨 → 며칠 후 silently SSH 끊김 | `-RestartCount` 는 FAILURE (non-zero exit) 에만 발동 | VBS wrapper 안에 무한 재시작 루프 (§ TCP forward 자동화) |

## Audit Trail (D-ops-29)

OS user = `axe` 공통이지만 식별 3중:

| Layer | 식별자 |
|---|---|
| Cloudflare Access SSO log | email (Cloudflare 대시보드 — Zero Trust → Logs → Access) |
| sshd auth log | ed25519 fingerprint (`/var/log/system.log`) |
| git commit author | `user.email` per session |

본인 session 의 git config 분리 (axe 의 global `~/.gitconfig` 가 ai@ 으로 되어있을 수 있음):

```bash
# repo 별
cd /Users/axe/<repo>
git config user.email "<your-email>@axellc.com"

# 또는 본인 session 환경변수
export GIT_AUTHOR_EMAIL="<your-email>@axellc.com"
export GIT_COMMITTER_EMAIL="<your-email>@axellc.com"
```

## 매 작업 시 사전 작업

| 빈도 | 작업 | 자동화 |
|---|---|---|
| PC 로그온 시 | cloudflared TCP forward 시작 | ✅ Scheduled task `cloudflared-ssh-axe-tcp` (AtLogOn + VBS 무한 루프) |
| Token 만료 ~5분 전 | `cloudflared access login` | ✅ Scheduled task `cloudflared-token-renewal` (self-rescheduling, RunLevel Highest) |
| 매 SSH 시도 | (없음) | — |
| (선택) Microsoft "로그인 상태 유지" | 갱신 시 사람 클릭 제거 | ⚠️ 본인 브라우저 설정 + Entra 정책에 의존 |

## 참조

- [D-ops-41](/ops/decisions) — SSH client-side automation (NSSM 폐기, user-context Scheduled Task + VBS wrapper, self-rescheduling renewal)
- [D-ops-39](/ops/decisions) — Universal SSL 1-level + flat-hostname 컨벤션
- [D-ops-29](/ops/decisions) — Dual identity (ai@ automation vs soohun.kang human work)
- [B-bp-mcp-teams-admin-consent](/ops/backlog) — Blueprint MCP Teams tools admin consent (미완)
- [/ops/known-gaps](/ops/known-gaps) — Cloudflare Universal SSL 1-level 함정 + 14 trap 분석

_Last updated: 2026-05-27 (Soohun Kang — Windows TCP-forward 자동화 + 24h SSO 자동 갱신 셋업 검증 + 함정 #9~#14 추가)_

---

<!-- PAGE https://docs.axelabs.ai/onboard/troubleshooting -->

# 문제 해결

> Frame connector 설정 시 자주 발생하는 오류와 대응.

URL: https://docs.axelabs.ai/onboard/troubleshooting

# 문제 해결

## "Couldn't reach the MCP server"

claude.ai 가 frame 서버에 도달 못 함. 원인 후보:

1. **URL 오타** — `https://axe.axelabs.ai/frame/mcp` (마지막에 `/mcp` 포함)
2. **회사 customer 와 다른 URL** — `axe` 직원은 `axe.axelabs.ai`, `realchoice` 직원은 `realchoice.axelabs.ai`
3. **claude.ai 캐시** — connector 완전 삭제 후 시크릿 창에서 재등록 시도

curl 로 외부 reachability 확인:
```bash
curl -sS https://axe.axelabs.ai/frame/health
# → {"status":"ok","service":"frame-mcp"}
```

200 OK 안 나오면 운영자에게 알리세요.

## "Authorization with the MCP server failed"

Microsoft 인증 또는 그 다음 단계에서 실패. URL 바의 `error_code=` 와 `entra_aadsts_code=` 가 결정적 단서.

### Reconnect 후에도 401 — frame middleware 의 RFC 9728 metadata path

**증상**: Connector 가 "Connection has expired. You can reconnect to re-authenticate" 표시 → Reconnect 클릭 → Microsoft 로그인 성공 (Entra Trace ID 있음, AADSTS error code 없음) → 다시 같은 메시지 반복.

**원인**: frame middleware 의 `/frame/mcp/.well-known/oauth-protected-resource` (resource-level RFC 9728 metadata) path 가 unauthenticated allowlist 누락 시 401 반환. claude.ai Connector 가 OAuth challenge metadata 못 받아 reconnect flow 진행 불가.

**해소**: **D-ops-23 (2026-05-22)** — `src/frame/mcp/http_server.py` 의 `_PUBLIC_PATHS` + `inner.router` 양쪽에 resource-level path 추가. 본 시점 이후 reconnect 정상.

**검증 명령**:
```bash
curl -sS -o /dev/null -w "%{http_code}\n" \
    https://<customer>.axelabs.ai/frame/mcp/.well-known/oauth-protected-resource
# 200 expected (D-ops-23 이전엔 401)
```

### `/frame/schemas` 또는 `/hive/schemas` 401 — auth-required (정상)

**증상**: `curl https://axe.axelabs.ai/frame/schemas` 가 401 반환. WWW-Authenticate: Bearer header 동반.

**원인**: 의도된 동작. `/schemas` 는 RFC 9728 metadata 와 달리 **`_PUBLIC_PATHS` 미포함** — Blueprint artifact 지식 레이어 ([D-bp-artifact-1](/ops/decisions)) 의 schema discovery 가 MCP 토큰 인증 필요. 토큰 없이 호출 시 일반 MCP 호출과 동일 401.

**해소**: MCP 토큰 (`FRAME_MCP_TOKEN` 또는 OAuth bearer) 부여 후 재시도. Blueprint 가 자동 호출 시는 [`B-bp-artifact-schema-discovery`](/ops/backlog) 가 frame token 재사용.

```bash
curl -H "Authorization: Bearer $FRAME_MCP_TOKEN" \
    https://axe.axelabs.ai/frame/schemas
# 200 + { version, service, schemas } envelope expected
```

### AADSTS700016 — Application not found

```
Application with identifier '<...>' was not found in the directory '...'
```

- Client ID 입력 오타 (vaultwarden 의 GUID 와 Frame MCP 의 GUID 혼동 등)
- 운영자가 새 customer 의 Azure 등록을 아직 안 한 상태

→ 운영자에게 정확한 Client ID 확인 요청.

### AADSTS9010010 — resource/scope mismatch

```
The resource parameter provided in the request doesn't match with the requested scopes
```

운영자 측 Azure 설정 문제. Application ID URI 와 scope URI prefix 가 다를 때 발생. → 운영자 측에서 처리, 직원 작업 X.

### AADSTS7000218 — missing client_secret

```
The request body must contain the following parameter: 'client_assertion' or 'client_secret'
```

- claude.ai 의 Advanced 에 **OAuth Client Secret 미입력**
- 또는 Azure 측 "Allow public client flows" 가 No 상태인데 secret 없음

→ Advanced 칸에 운영자가 준 secret 입력. secret 분실했으면 운영자에게 재요청.

### Bitwarden Send URL — "This Send has been deleted" / "Send not found"

운영자가 Teams DM 으로 보낸 1회용 URL 을 클릭했는데 위 메시지 나옴.

- **1회 클릭 이미 소진** — `-a 1` 설정이라 누군가 (운영자 본인 검증 포함) 이미 1회 열었으면 즉시 무효
- **1일 만료 (`-d 1`)** 경과 — 운영자가 발사한 시각 + 24h 지남
- **운영자가 수동 삭제** (`bw send delete`)

→ 운영자에게 재발급 요청: 본인 이메일 + 어느 서비스 (Blueprint / Hive / Frame) 인지 명시. 운영자 1 명령 (`axe secret send <ENV> --service <svc> --to <local-part>`) + broadcast-dm 으로 새 URL 즉시 송부. 절차: [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send).

### AADSTS65001 — user/admin consent 없음

```
The user or administrator has not consented to use the application
```

- 첫 로그인 시 동의 화면에서 **Accept** 안 누름
- 또는 admin consent 가 필요한 scope 이지만 미부여

→ 다시 connect 시도, 동의 화면 나오면 Accept 클릭. 안 나오면 운영자 호출.

### AADSTS50011 — redirect URI mismatch

```
The reply URL specified in the request does not match the reply URLs configured
```

운영자 측 Azure 설정 문제 (redirect_uri 누락). → 운영자 작업.

## "mcp_client_invalid"

Anthropic 이 Microsoft 에서 받은 토큰을 frame 에 못 보냄. URL 바의 `entra_aadsts_code=` 확인.

URL 형식: `claude.ai/customize/connectors?...&error_code=mcp_client_invalid&entra_aadsts_code=<코드>&entra_trace_id=&lt;id&gt;`

`entra_aadsts_code` 가 있으면 위 AADSTS 섹션 참조. 없으면 운영자에게 전체 URL 전달.

## "SSO 화면 자체가 안 뜸"

- claude.ai connector 가 stale state — 완전 삭제 후 **브라우저 hard refresh (Cmd+Shift+R)** → 재등록
- 또는 시크릿/incognito 창에서 재시도

## Vault (axe.axelabs.ai/vault) — "Log in with SSO" / Identifier 입력 안 보임

Vaultwarden 기본 로그인 페이지는 **이메일 입력이 먼저** 노출됩니다. SSO Identifier 화면으로 바로 가려면:

- 직접 URL: `https://axe.axelabs.ai/vault/#/sso` → "Organization SSO Identifier" 입력 칸 노출 → `AXE` 입력 → "Log In"
- 또는 이메일 입력 화면 하단의 **"Enterprise single sign-on"** 링크 클릭

## Vault — "Your provider does not send email verification status"

전체 오류:
```
Your provider does not send email verification status.
You will need to change the server configuration
(check `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION`) to log in.
```

**원인**: Microsoft Entra ID 의 OIDC id_token 에는 `email_verified` claim 이 포함되지 않음. Vaultwarden Timshel fork 의 기본 동작은 검증 실패 → 로그인 거부.

**해소**: **D-ops-24 (2026-05-22)** — `/Users/axe/.axe/vault/docker-compose.yml` 의 `axe-vaultwarden.environment` 에 `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"` 추가 후 `docker compose up -d --force-recreate axe-vaultwarden`. tenant 내부 사용자만 SSO 흐름에 진입하므로 추가 검증 면제 안전.

직원은 본 해소 이후 위 "Identifier 입력 안 보임" 안내대로 재시도.

## "Connected 떴는데 도구 호출이 실패함"

채팅에서 `Frame:list_open_items` 호출 시 "권한 없음" 또는 "Entity not authorized":

- 본인 이메일이 `customers.yaml` 의 `user_entity_map` 에 매핑 안 됨
- 또는 잘못된 entity 명 사용 (`axec` vs `axes`)

→ 운영자에게 entity 매핑 확인 요청.

## "권한 부족" — 분개 등록 실패

```
이 작업은 write 권한이 필요하나 현재 read 만 부여되어 있습니다
```

본인의 role 이 `read` 만 부여된 상태. 운영자에게 권한 상승 요청.

## "토큰 만료" — 며칠 후 갑자기 안 됨

Microsoft access_token 은 기본 60-90분, refresh_token 은 90일. claude.ai 가 자동 갱신하지만, 90일 무사용 시 만료.

→ claude.ai 의 connector 페이지에서 **Re-authorize** 클릭. Microsoft 로그인 1회 → 재활성.

## `axe login` 은 됐는데 `axe <service> …` 가 401 — Blueprint 플랫폼 토큰 (D-axe-idp-1)

[AXE CLI](/services) 의 `axe login`(브라우저 Entra SSO)은 성공해 토큰을 받았는데 `axe frame tools` 등이 401 이면:

- **서비스가 Blueprint 를 아직 신뢰 안 함** — 해당 서비스에 `BLUEPRINT_ISSUER=https://blueprint.axellc.com` 가 설정돼야 `iss=blueprint` 토큰을 수용. unset 이면 그 토큰은 HS256 경로로 빠져 거부됨(의도된 비파괴 기본값). 운영자: 서비스 env(frame 은 `.env.local`)에 추가 후 `docker compose up -d --force-recreate`.
- **`aud` 불일치** — 플랫폼 토큰 `aud` = `https://axe.axelabs.ai`(`BLUEPRINT_AUDIENCE` 기본). 서비스의 `BLUEPRINT_AUDIENCE` 와 같아야 함.
- **email 미매핑** — 토큰은 유효하나 `customers.yaml` `user_entity_map`/`default_entities_by_domain` 에 해당 email 없음 → `USER_NOT_MAPPED`. customers.yaml 에 추가.
- **Blueprint JWKS 도달 불가** — 서비스가 `https://blueprint.axellc.com/.well-known/jwks.json` 를 못 받으면 `OIDC_UNAVAILABLE`(503). 네트워크/터널 확인.

운영자 배포 함정: blueprint DB 는 `prisma migrate deploy` 가 안 먹음(`_prisma_migrations` 부재) → 새 모델은 `prisma db push`(또는 raw SQL). `BLUEPRINT_OIDC_PRIVATE_KEY` 는 env_file 따옴표/개행 문제 회피 위해 **base64 단일라인**.

## 그 외 — 운영자에게 전달할 정보

문제 해결 안 될 때 운영자 (`ai@axellc.com`) 에게 다음 전부 전달:

1. **어떤 작업 도중** 문제 발생했는지 (connector 추가 / tool 호출 / 다른 것)
2. **정확한 오류 메시지** (스크린샷)
3. **URL 바 전체** (특히 `error_code=`, `entra_aadsts_code=`, `entra_trace_id=` 부분)
4. **claude.ai connector 페이지 상태** (Connected / Disconnected / Authorization failed)
5. **(가능하면) Browser DevTools Network 탭** 에서 `login.microsoftonline.com` 으로 가는 요청의 Request URL

---

<!-- PAGE https://docs.axelabs.ai/onboard/vault-setup -->

# Vault setup — KDF rotation + 4 client + Bitwarden Authenticator

> AXE Vaultwarden 의 SSO→MP unlock 정상화 (KDF rotation, 옛 user 만) + 데스크톱/Chrome/Mobile 3 client + Bitwarden Authenticator 표준 setup. 한 번 (~30분) 후 일상 = Touch ID / PIN. 새 직원 onboarding 의무 step.

URL: https://docs.axelabs.ai/onboard/vault-setup

# Vault setup

## AI 요청 프롬프트

```
https://docs.axelabs.ai/onboard/vault-setup 따라 내 vault 본인 setup 진행해줘.

진행:
1. 내 머신 OS + 기존 환경 진단 (macOS Touch ID 유무, Chrome 설치, mobile 종류)
2. 페이지의 Prereq 확인 — 내가 KDF rotation 대상인지 (axe.2 적용 전 가입 user 만), 아니면 Phase 1 skip
3. 페이지의 각 Phase 명령 + 검증 매 step 결과 받고 다음
4. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
5. 모든 Phase 완료 후 운영자 ai 에게 Teams 회신 "vault setup 완료"
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- AXE 임직원 (`@axellc.com`) — Entra ID SSO 등록 완료
- 본인 macmini / 노트북 (macOS Touch ID 또는 Windows Hello 권장) + iPhone 또는 Android
- 본인 vault master password 기억 (변경 시 current MP 확인 + 새 MP 입력 필수)
- Microsoft Authenticator 가 phone 에 이미 설치되어 Entra MFA 등록 완료 상태

**Phase 별 강제도 (skip 가능성 판단)**:

| Phase | 강제도 | skip 시 영향 |
|---|---|---|
| 1. KDF rotation | 옛 user 만 필수 | 옛 user 가 skip 하면 SSO→MP unlock 깨짐 (Phase 1 본문 참조) |
| 2. Desktop 앱 | 필수 | 데스크톱 일상 unlock 불가 |
| 3. Chrome extension | 필수 | 웹 자동 채우기 + 검색 + 단축키 입력 불가 |
| 4. Mobile | **권장** | mobile 자동 채우기 / 외출 시 vault 조회 불가. 데스크톱-only 워크플로면 skip 가능 |
| 5. Bitwarden Authenticator | **선택** | Google Authenticator 등 기존 TOTP 앱 계속 사용 OK (Phase 5 본문 참조). 새 2FA 등록만 vault TOTP 필드 권장 |

**Phase 1 (KDF rotation) 대상 = "옛" user**:

- ✅ 본인이 **axe.2 release (2026-05-26) 이전 가입자** 이면 KDF rotation 필요 (`client_kdf_type=0`, PBKDF2)
- ❌ axe.2 release 이후 신규 가입자 (realchoice 측 등) 는 새 schema 로 가입돼 KDF rotation 불필요 → **Phase 1 skip**
- 헷갈리면 일단 Phase 1 시도 — 옛 schema 면 효과, 새 schema 면 no-op (안전)

## Phase 1: KDF rotation (옛 user 만, ~5분)

vault 의 SSO→MP unlock 정상화 ([D-ops-40](/ops/decisions)). 옛 KDF (PBKDF2) 로 wrap 된 user.akey 를 새 schema 로 재wrap.

1. https://axe.axelabs.ai/vault — **새 incognito (Chrome 시크릿) 창** 에서 접속
2. 본인 email (`firstname.lastname@axellc.com`) → Continue
3. ★ **SSO 누르지 말고** Master password 단독 로그인 (본인 현재 MP)
4. 우상단 본인 이름 → Account settings → 좌측 사이드바 Security → 상단 **Master password** 탭
5. 입력:
   - **Current master password**: 본인 현재 MP
   - **New master password**: 같은 값으로 OK (또는 더 강한 12자 이상 새 값)
   - **Confirm new master password**: new 와 동일
   - ☑ **Also rotate my account's encryption key** — **반드시 체크**
6. **Change master password** 클릭 → 수십 초 대기 (client-side 가 모든 vault item 재암호)
7. 자동 logout

**검증** (같은 incognito 창에서):

8. https://axe.axelabs.ai/vault → 본인 email → Continue
9. 이번엔 **Enterprise single sign-on** 클릭
10. Microsoft 로그인 + MFA → vault redirect → **MP 입력** → unlock 정상이면 ✅

axe.2 까지는 10번 단계에서 "Cannot read properties of null (reading toWrappedAccountCryptographicState)" 에러로 막혔음. KDF rotation 후 정상.

## Phase 2: Bitwarden 데스크톱 앱 (~5분)

본인 OS 에 맞는 sub-section 따라가기.

### Phase 2a — macOS

1. https://bitwarden.com/download/ → **macOS Desktop (Universal)** 다운로드 → `/Applications` 설치
2. 첫 실행 → 좌측 아래 **gear (Settings)** → **Self-hosted environment**
3. **Server URL**: `https://axe.axelabs.ai/vault` → **Save**
4. **Log in with SSO** (Enterprise single sign-on) → Entra ID + MFA → MP 입력 → Unlock
5. 메뉴 → **Settings** (⌘+,) → **Preferences**:
   - **Vault timeout**: **Never**
   - **Vault timeout action**: **Lock**
   - **Unlock with Touch ID**: ☑ (Touch Bar 또는 Magic Keyboard Touch ID)
   - **Lock with master password on browser restart**: ☑
6. **Save**

→ 이후 일상 unlock = Touch ID (1-2 초). MP 입력 = 앱 완전 재시작 + paranoia 옵션 시만.

### Phase 2b — Windows

설치 경로 2 가지 — **Microsoft Store** vs **`.exe` installer**. 결과물 + 동작 같음, 자동 업데이트 채널만 다름.

| 설치 방법 | 다운로드 | 자동 업데이트 | 추천 |
|---|---|---|---|
| Microsoft Store | Store 검색 "Bitwarden" | Store 가 자동 (Windows Update 함께) | 일반 사용자 |
| `.exe` installer | https://bitwarden.com/download/ → **Windows Installer (64-bit)** | 앱 내장 updater (수동 확인 OK) | 회사 정책상 Store 제한 PC |

설치 후:

1. 첫 실행 → 좌측 아래 **gear (Settings)** → **Self-hosted environment**
2. **Server URL**: `https://axe.axelabs.ai/vault` → **Save**
3. **Log in with SSO** → Entra ID + MFA → MP 입력 → Unlock
4. 메뉴 → **Settings** → **Preferences**:
   - **Vault timeout**: **Never**
   - **Vault timeout action**: **Lock**
   - **Unlock with Windows Hello**: ☑ (Windows Hello 사전 설정 PC 만 — 아래 분기 참조)
   - **Lock with master password on browser restart**: ☑
5. **Save**

**Windows Hello 미설정 PC 의 fallback** = PIN unlock:

- 설정에서 **Unlock with Windows Hello** 옵션이 회색 비활성 = OS 단에서 Hello 미등록 (PIN / 얼굴 / 지문 어느 것도 없음)
- 두 선택지:
  - (a) Windows Settings → Accounts → Sign-in options → **Windows Hello PIN** 등록 → Bitwarden 재시작 → Hello unlock 활성화
  - (b) Hello 등록 거부 시 → **Unlock with PIN code** ☑ + PIN 6자리 이상 (Chrome ext 와 동일 방식, Phase 3 참조)
- 권장 = (a). Hello = OS biometric / PIN 통합 채널이라 Bitwarden + 회사 다른 앱 동일 채널 사용 가능

→ 이후 일상 unlock = Windows Hello (또는 PIN). MP 입력 = 앱 완전 재시작 + paranoia 옵션 시만.

## Phase 3: Chrome extension (~3분)

1. Chrome 에서 다운로드:
   ```
   https://chromewebstore.google.com/detail/bitwarden-free-password-m/nngceckbapebfimnlniiiahkandclblb
   ```
2. extension 아이콘 클릭 → **⚙ Settings** → **Self-hosted environment**
3. **Server URL**: `https://axe.axelabs.ai/vault` → **Save**
4. **Log in with SSO** → 첫 MP unlock
5. **⚙ Settings** → **Account security**:
   - **Vault timeout**: **Never**
   - **Vault timeout action**: **Lock**
   - **Unlock with PIN code**: ☑ + PIN 6자리 이상 (숫자보다 word 권장, 예: `axe-2026`)
   - **Lock with master password on browser restart**: ☑

→ 이후 unlock = PIN. Chrome 완전 재시작 시 MP 1회 (paranoia 옵션이면).

## Phase 4: Mobile (iOS / Android, ~5분, 권장)

> **권장 (필수 아님)**. 데스크톱-only 워크플로 (외근 / 외출 중 vault 조회 불필요) 사용자는 skip 가능. skip 시 영향 = mobile 자동 채우기 / 외출 vault 조회 불가. 대부분 직원은 SMS / KB / 홈택스 등 mobile 2FA 도착 시 vault TOTP 조회가 필요해 설치 권장.

1. App Store / Play Store → **"Bitwarden"** 검색 → **노란 방패 아이콘** (Password Manager — Authenticator 와 다른 앱)
2. 설치 → 첫 실행 → **Settings** → **Self-hosted environment**:
   - **Server URL**: `https://axe.axelabs.ai/vault` → **Save**
3. **Log in with SSO** → Entra MFA → MP 입력 → Unlock
4. **Settings** → **Account security**:
   - **Unlock with Face ID** / **Touch ID**: ☑
   - **Vault timeout**: **1 month**
   - **Vault timeout action**: **Lock**

→ Safari/Chrome 모바일 자동 채우기, 앱 안 자동 채우기 다 됨.

## Phase 5: Bitwarden Authenticator (TOTP, ~3분, 선택)

외부 service (KB / 홈택스 / GitHub / 등) 의 2FA 코드를 vault 와 분리 저장 ([D-ops-38](/ops/decisions) 보조).

> **선택 (필수 아님)**. 기존 Google Authenticator / Microsoft Authenticator 앱에 등록된 TOTP 는 **그대로 유지 OK** — 새 2FA 등록 시점부터 본 표준 (vault item TOTP 필드) 적용을 권장하는 것. **기존 item 일괄 수정 SOP 아님**.

### "vault item TOTP 필드 저장" 의 의미

| 시나리오 | 행동 |
|---|---|
| 이미 Google/MS Authenticator 에 있는 기존 TOTP | **건드릴 필요 없음**. phone authenticator 그대로 사용 |
| 새 서비스 2FA 등록 (오늘 이후) | 새 표준 = vault item 의 Authenticator key (TOTP) 필드에 secret 저장 |
| 기존 TOTP 를 vault 로 이전 (선택) | 본인 시간 날 때만. phone authenticator 의 backup code 또는 service 의 "2FA reset" 흐름 거쳐 재발급 → vault 저장 |

### vault item TOTP 필드 UI 동작 (Bitwarden 공통)

데스크톱 / Chrome ext / mobile 어디서나 동일:

| 상태 | 동작 |
|---|---|
| **View 모드** (item 클릭만) | TOTP secret 있는 item 만 "Verification code (TOTP)" / "인증 코드 (TOTP)" 섹션 노출. 없으면 섹션 자체 안 보임 |
| **편집 모드** (item Edit) | Authenticator key 입력 필드 노출 (View 모드엔 안 보임) — secret 추가 / 변경 / 삭제 |
| 상단 **"인증 코드 복사"** 버튼 | 해당 item 에 TOTP secret **있을 때만 동작**. 빈 item 에서 누르면 무반응 (오류 메시지 없음) — 정상 |

→ "복사 버튼 무반응" 이면 = 본인 item 에 secret 없음 = 편집 모드 진입 후 secret 입력 (또는 phone authenticator 에 그대로 두기).

### Mobile (권장)

1. App Store / Play Store → **"Bitwarden Authenticator"** 검색
   - ★ Phase 4 의 Password Manager 와 **별도 앱** — 회색 방패 + 시계 아이콘
2. 설치 → 첫 실행 → **Bitwarden 계정** (axe.axelabs.ai/vault SSO 동일) 로그인 → **sync 활성화**
3. 끝 — Password Manager 의 TOTP 필드와 양방향 동기화

> 기존 Google / MS Authenticator 와 **병행** OK. 신규 TOTP 만 Bitwarden 쪽에 등록해도 됨.

### Desktop

Bitwarden Authenticator 는 mobile-only (2026-05 기준 macOS / Windows 공식 앱 없음).

**대안 = Phase 2 의 Bitwarden Password Manager 데스크톱 앱이 TOTP 내장**:
- vault item 의 **Authenticator key (TOTP)** 필드에 secret 저장 → 데스크톱에서 6-digit 자동 회전 (30초)
- D-ops-38 표준: **새** 외부 service 2FA 등록 시 phone Authenticator 앱 대신 vault item TOTP 필드 사용 → mobile + desktop 양쪽 동일 코드

## 검증 + 완료 신호

| # | 검증 항목 | 통과 기준 |
|---|---|---|
| 1 | (Phase 1 대상자) SSO → MP unlock | https://axe.axelabs.ai/vault SSO 흐름 → MP 입력 → vault 열림 |
| 2 | Phase 2 데스크톱 unlock | Touch ID 1회 → vault 열림 |
| 3 | Phase 3 Chrome ext unlock | PIN 입력 → vault items 검색 가능 |
| 4 | Phase 4 Mobile unlock | Face ID / Touch ID → vault 열림 |
| 5 | Phase 5 Mobile Bitwarden Authenticator | Bitwarden 계정 sync 성공 (vault item TOTP 필드와 같은 코드 회전) |
| 6 | vault item 접근 (워크플로 분기 아래 참조) | 본인 워크플로 기준 항목 통과 |

### 자동 채우기 검증 — 워크플로 분기

vault item 접근 방식은 사용자별로 다름. 본인 워크플로에 맞는 검증만 통과하면 OK.

| 워크플로 | 검증 방법 | 통과 기준 |
|---|---|---|
| **웹 폼 위주** (KB / 홈택스 / SaaS 로그인 페이지 잦음) | Safari/Chrome 의 login form 에서 Bitwarden suggestion 자동 노출 | suggestion drop-down 클릭 → ID/PW 자동 입력 |
| **SSO 위주** (대부분 회사 서비스 = Entra SSO 한 번 + remote-host credential 위주) | 데스크톱 앱에서 vault 검색 → 필드 우클릭 / 단축키 복사 | 검색 → item 클릭 → 필드 단축키 (⌘C / Ctrl+C) 또는 컨텍스트 메뉴 복사 |
| **터미널 / SSH 위주** | Chrome ext 단축키 자동 입력 (Ctrl+Shift+L on focused input) 또는 SSH agent 연동 | focused field 에 자동 입력 ID/PW 전송 |

> SSO 위주 사용자 (대다수 AXE 개발자 / taehun 같은 패턴) 는 웹 자동 채우기 거의 안 씀 = 자동 채우기 검증 skip OK. 검색 + 필드 복사가 정상 작동하면 통과.

전부 통과하면 운영자 ai (`ai@axellc.com`) 에게 Teams 1:1 채팅으로 "vault setup 완료" 회신.

## 함정 정리

| # | 증상 | 원인 | 우회 |
|---|---|---|---|
| 1 | Phase 1 step 5 의 "Change master password" 후 vault 깨짐 | Step 6 의 client-side 재암호 wait 중 새로고침 / 창 닫기 | 수십 초 절대 건드리지 X. 끊겼으면 운영자 ai 에게 즉시 신고 (백업 복원 가능, [/ops/runbook/vault-recovery](/ops/runbook/vault-recovery)) |
| 2 | Phase 1 KDF rotation 후에도 SSO→MP 깨짐 | (a) 옛 schema 가 아니라 다른 원인, 또는 (b) Phase 1 의 "rotate encryption key" 체크 빠짐 | 운영자 ai 에게 docker logs capture 시도 신고 — 옛 schema 가설 외 후속 진단 |
| 3 | Phase 2-4 의 Web vault timeout 에 `Never` 옵션 없음 | 보안 정책상 web vault 가 `Never` 미노출 (Bitwarden 의도) | Web vault 는 `On browser refresh` 가 최장. Native + Extension 은 `Never` OK |
| 4 | Phase 3 Chrome ext 가 SSO 로그인 안 됨 | Self-hosted environment 의 Server URL 미설정 / 오타 | `https://axe.axelabs.ai/vault` (https + /vault 까지) 정확 입력 |
| 5 | Phase 4 mobile 에서 vault 로그인 매번 MP 요구 | Vault timeout = `Immediately` 또는 짧음 + biometric unlock 미활성 | Settings → Account security → Vault timeout `1 month` + Face/Touch ID ☑ |
| 6 | Phase 5 Bitwarden Authenticator 가 데스크톱 안 보임 | Bitwarden Authenticator = mobile-only (2026-05 기준) | 데스크톱 = Phase 2 의 Password Manager 데스크톱 앱 TOTP 기능 사용 |
| 7 | Phase 5 모바일 Authenticator sync 안 됨 | Bitwarden 계정 로그인 빠짐 (Authenticator 첫 실행 시 "Use without account" 선택했음) | 앱 Settings → Account → Log in → axe.axelabs.ai/vault SSO 계정 |
| 8 | Phase 5 Authenticator app 에서 vault item TOTP 안 보임 | sync 활성화는 됐지만 Password Manager 측 item 에 TOTP 필드 미설정 | Password Manager 에서 해당 item 편집 → Authenticator key 필드에 외부 service 의 TOTP secret 입력 → 양쪽 동기화 |
| 9 | Phase 1 의 SSO 단계에서 Entra ID 가 MFA 요구하는데 Microsoft Authenticator 미설치 | MFA enrollment 미완 | https://mysignins.microsoft.com/security-info → Add sign-in method → Microsoft Authenticator → 모바일 설치 + 등록 |
| 10 | "Phase 1 대상자인지 모르겠음" | 본인이 옛 user 인지 신규 user 인지 불확실 | 일단 Phase 1 시도 — 옛 schema 면 효과, 새 schema 면 no-op (Master password change 가 그냥 동일 값으로 갱신, 안전). 시간 = 5분 |
| 11 | Phase 2b Windows 의 "Unlock with Windows Hello" 옵션이 회색 비활성 | OS 단에서 Hello 미등록 (PIN / 얼굴 / 지문 어느 것도 없음) | Windows Settings → Accounts → Sign-in options 에서 Hello PIN 등록 → Bitwarden 재시작. 또는 PIN unlock fallback (Phase 2b 본문) |
| 12 | Phase 5 의 "vault item 의 인증 코드 복사" 버튼 눌러도 무반응 | 해당 item 의 Authenticator key (TOTP) 필드가 비어 있음 (정상 동작 — 오류 메시지 없음) | item 편집 모드 진입 → Authenticator key 필드에 secret 입력 (또는 phone authenticator 그대로 유지) |
| 13 | Phase 5 "기존 Google Authenticator TOTP 를 vault 로 옮겨야 하나" 헷갈림 | "vault item TOTP 필드 저장" 의미 = 신규 SOP, 기존 일괄 마이그레이션 X | 기존 TOTP 는 그대로 유지 OK. 새 2FA 등록 시점부터 vault TOTP 필드 사용 |
| 14 | Phase 검증 6번 (자동 채우기) 안 됨 | SSO 위주 사용자라 웹 폼 자동 채우기 거의 안 씀 | 본인 워크플로 분기 (검증 섹션 표) 따라 SSO 위주 / 터미널 위주 검증으로 대체. 자동 채우기 검증 skip OK |

## Phase 별 시간

| Phase | 시간 | 비고 |
|---|---|---|
| 1. KDF rotation | 5분 | 옛 user 만 |
| 2. Desktop (macOS / Windows) | 5분 | 모두 (필수) |
| 3. Chrome extension | 3분 | 모두 (필수) |
| 4. Mobile | 5분 | 권장 (skip 가능) |
| 5. Bitwarden Authenticator | 3분 | 선택 (Google/MS Authenticator 병행 OK) |
| 검증 + 회신 | 5분 | 모두 |
| **합계** | **~25-30분** | 옛 user / 5 phase 다 |

## 표준 setup vs valid 변형

본 페이지의 **표준 setup** 외 valid 변형도 인정. 본인 워크플로에 맞으면 변형 사용 OK — 운영자 ai 에게 "valid 변형 X 사용 중" 명시만.

| 구성 | 표준 (권장) | valid 변형 |
|---|---|---|
| Stack | 3-stack (Desktop + Chrome ext + Mobile) + Bitwarden Authenticator | 2-stack (Desktop + Chrome ext) — Mobile / Bitwarden Authenticator 생략 |
| TOTP 앱 | Bitwarden Authenticator (mobile) + vault item TOTP 필드 (desktop) | Google Authenticator / Microsoft Authenticator 계속 사용 + 새 2FA 만 vault 등록 |
| 자동 채우기 | 웹 폼 + Chrome ext suggestion 적극 활용 | SSO + remote-host credential 위주 = 검색 + 필드 복사 + 단축키 입력 |
| 적합 사용자 | 직접 SaaS 로그인 잦은 운영 / 기획 / 영업 등 | 개발자 (SSO + ssh / remote-host 위주) — taehun 같은 패턴 |

> 둘 다 D-ops-37 + D-ops-38 + D-ops-40 정합 — secret 이 vault SoT 에 있고 user master password 가 단일 unlock factor 면 valid.

## 일상 운영 (setup 완료 후)

- **daily unlock** = Touch ID (macOS) / Windows Hello (Windows) / Face ID (mobile) / PIN (Chrome ext) — 1-2 초
- **MP 입력 빈도** = 데스크톱 / mobile 완전 재시작 시 + paranoia 옵션 켰을 때만 (월 1-2회)
- **vault item 추가** = 데스크톱 앱이 가장 편함 (form 더 큼 + TOTP 필드 명시)
- **service 2FA 코드 조회** = Bitwarden Authenticator (모바일) 또는 Password Manager 의 TOTP 필드 (데스크톱). Google/MS Authenticator 병행 사용자는 기존 앱 그대로
- **자동 채우기 안 뜨면** = Chrome ext 의 Self-hosted environment 확인 + extension 권한 (해당 사이트에서 contents 접근 허용). SSO 위주 사용자는 자동 채우기 미사용이 정상 — 검색 + 단축키 복사로 대체

## 참조

- [D-ops-40](/ops/decisions) — vault axe.3 release plan + Progress (본 setup 의 배경)
- [/architecture/vault-policies](/architecture/vault-policies) — 3 layer 정책 모델 (server env + Org Policies + per-client preferences). Phase 2-5 의 "Vault timeout / Unlock with X" 권장값의 근거
- [D-ops-38](/ops/decisions) — 외부 service 2FA = vault TOTP 필드 (Phase 5 본질)
- [D-ops-37](/ops/decisions) — axelabs-ai/vault Timshel fork build
- [D-ops-26](/ops/decisions) + [D-ops-27](/ops/decisions) — SSO_ONLY=false + MP fallback 보존
- [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) — KDF rotation 진행 status (4명 완료 후 ✅)
- [/ops/runbook/vault-recovery](/ops/runbook/vault-recovery) — vault 복구 (Phase 1 step 6 중단 등 비상 시)
- [/ops/runbook/operator-broadcast](/ops/runbook/operator-broadcast) — 본 setup 안내 broadcast 채널 (운영자가 신규 직원에게 본 페이지 URL 발송)

---

<!-- PAGE https://docs.axelabs.ai/ops -->

# 운영자 대시보드

> 운영자 (`ai@axellc.com`) 전용 — 일상·주간·월간 점검 항목.

URL: https://docs.axelabs.ai/ops

# 운영자 대시보드

> 본 섹션은 **운영자 (`ai@axellc.com`)** 전용. Microsoft Entra ID 로그인 게이트 (예정). 정보가 customer 별 운영 디테일 포함.

## 매일 (자동, 점검만)

| 항목 | 자동화 | 점검 방법 |
|---|---|---|
| 03:00 KST local backup | `com.axe.backup.local` | `restic snapshots` 직접 |
| 03:30 KST ring push (axe → realchoice) | `com.axe.ring.push` | `axe ring status` |
| 매시 frame integrity check | `com.frame.integrity-check` | `ssh axe-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axec"` |
| 매시 cron jobs (stream/magnet) | supercronic | 각 service 로그 |

매일 운영자가 받는 Slack 보고 (또는 메일):
- 어제 backup 성공/실패
- frame integrity 결과 (모든 entity 정상이면 1줄 OK)
- stream/magnet alert 합계

## 매주

- 직원 활동 audit (frame `audit_log` × 모든 entity)
- secret 만료 임박 항목 (30일 이내)
- Cloudflare tunnel uptime
- macmini 디스크 사용량 (모든 customer)

## 매월

- 직원 권한 review (`customers.yaml > user_entity_map`)
- backup 크기 변화
- Vaultwarden organization 멤버 변동
- 회계 사무소 export 송부

## 분기

- Restore drill (`com.axe.restore-drill`, Jan/Apr/Jul/Oct 15)
- DECISIONS 회고 (변경 필요?)
- 비용 review (Cloudflare, Microsoft, Anthropic)
- Cold SSD rotation

## 주요 도구

| CLI | 용도 |
|---|---|
| `axe customers list/add/show` | customer 목록 |
| `axe health &lt;target&gt;` | 인프라 health probe (positional, `target` 기본값 `all`) |
| `axe deploy &lt;service&gt; &lt;customer&gt; --apply` | blue/green deploy |
| `axe ring push/sync/status/init` | ring backup (Phase 5) |
| `axe cold init/sync/status` | cold SSD backup |
| `axe console rebuild/data/restart/sso/token` | admin.axelabs.ai 콘솔 갱신 |
| `axe secret get/list/status` | Vault 직접 호출 (단건) |
| `axe secret check/pull/push/rotate &lt;svc&gt;` | 매니페스트 기반 일괄 ([architecture/secrets](/architecture/secrets), D-ops-17) |
| `axe phase` | 현재 rollout phase |
| `axe onboard &lt;customer&gt; --apply` | 신규 customer bootstrap (18-step) |
| `axe restore --customer X --from Y --as-of Z` | restic 복원 — **Phase 5 stub**, 현재 restic 직접 호출 사용 ([known-gaps](/ops/known-gaps)) |
| `axe docs-check [--since &lt;ref&gt;]` | 코드 ↔ axelabs-docs drift 감지 ([release flow](/ops/runbook/release-flow)) |
| `axe ship [&lt;service&gt;]` | release-gate: docs-check + push + deploy. **`git push origin main` 대신 사용** ([release flow](/ops/runbook/release-flow)) |

자동 일일 backup = `com.axe.backup.local` launchd (매일 03:00 KST). 수동 시도는 `restic backup` 직접.

## 외부 콘솔

| 콘솔 | 용도 |
|---|---|
| `https://admin.axelabs.ai` | 운영자 web 콘솔 (Microsoft SSO) |
| `https://axe.axelabs.ai/vault` | Vaultwarden (master password) |
| Azure portal | Entra ID app 관리 |
| Cloudflare dashboard | DNS, tunnel, Universal SSL |

## 핵심 파일

| 파일 | 역할 |
|---|---|
| `/Users/axe/.axe/customers.yaml` | SSOT — customer registry |
| `/Users/axe/.axe/bin/axe` | CLI |
| `/Users/axe/CLAUDE.md` | 포트 할당, launchd 서비스 목록 |
| `/Users/axe/multi-tenant-platform-plan.md` | 마스터 플랜 + D 결정 |
| `/Users/axe/frame/DECISIONS.md` | D-ops-1~15 |
| `/Users/axe/.axe/state.yaml` | 현재 rollout phase, 다음 세션 컨텍스트 |
| `/Users/axe/.axe/tunnels/axelabs/config.yml` | cloudflared ingress |
| `/Users/axe/.axe/vault/docker-compose.yml` | Vaultwarden |

## 다음 세션 시작 시

1. `cat /Users/axe/.axe/state.yaml` — 현재 phase 확인
2. `cat /Users/axe/.axe/NEXT_SESSION.md` — 마지막 세션의 다음 작업
3. 운영자 콘솔 ( `https://admin.axelabs.ai` ) 의 dashboard 확인
4. 미해결 알람 (어제 backup 실패 등) 처리

## 비상

| 사건 | 즉시 대응 |
|---|---|
| frame DB 손상 | [Runbook · DB 복구](/ops/runbook/db-recovery) |
| cloudflared 죽음 | `docker start axelabs-tunnel` |
| Vaultwarden 죽음 | [Runbook · Vaultwarden recovery](/ops/runbook/vault-recovery) |
| customer macmini 도난/화재 | [Runbook · macmini 손실](/ops/runbook/macmini-loss) |
| secret 노출 의심 | [Runbook · secret rotation](/ops/runbook/secret-rotation) |

## 다음

- [Runbooks](/ops/runbook) — 표준 절차들
- [DECISIONS](/ops/decisions) — 아키텍처 결정 누적
- [인프라 인벤토리](/ops/inventory) — 서비스/포트/파일 전체 목록

---

<!-- PAGE https://docs.axelabs.ai/ops/backlog -->

# 백로그 (실행 큐)

> 다음 세션의 entry point. 신규/Ready/in-progress/done lifecycle 로 무엇부터 할지가 5초 안에 보임.

URL: https://docs.axelabs.ai/ops/backlog

# 백로그 (실행 큐)

> **다음 세션이 들어오면 이 페이지부터 본다.** [known-gaps](/ops/known-gaps) 는 "함정과 미해결 사실", 본 페이지는 "다음 실행 항목". [roadmap](/ops/roadmap) 은 마일스톤 큰 그림 — 각 백로그 항목은 마일스톤 ID (M1~M5) 로 묶임. 이미 ship 된 ✅ 항목은 [updates](/ops/updates) 의 Ship Log 로 promote (Phase 2 자동 = `B-axe-ship-update-hook`).
>
> **시간축 4 페이지** ([D-docs-updates-1](/ops/decisions)): **본 페이지** (현재) · [roadmap](/ops/roadmap) (미래) · [updates](/ops/updates) (과거) · [known-gaps](/ops/known-gaps) (사실).
>
> **Lifecycle**: 🆕 신규 (분류 안 됨) → 📋 ready (다음 세션이 집어가도 됨) → 🔧 in-progress (작업 중) → ✅ done (1주 후 archive 또는 삭제) → ⏸️ blocked (외부 차단)
>
> **운영 ritual**:
> 1. **세션 시작**: 본 페이지 + [known-gaps](/ops/known-gaps) 같이 확인. 작업 주제의 항목 있으면 🔧 로 옮기고 owner 자기 이름으로
> 2. **세션 종료**: 끝낸 항목 ✅ + 새 발견 🆕. ✅ 항목은 다음 정비 시 archive 표로 이동
> 3. **항상**: 항목 = 한 줄 행동. 1주 안 끝날 항목은 마일스톤 (M-) 으로 승격하거나 쪼개기

## 🔧 In-progress (작업 중)

| ID | 항목 | 마일스톤 | owner | 시작일 | 비고 |
|---|---|---|---|---|---|
| **B-search-deploy** | docs.axelabs.ai UI 검색 (Pagefind) 라이브 배포 — 코드 머지 끝, `axe ship docs` 후 검색박스 동작 검증 | — | 운영자 | 2026-05-22 | [D-docs-search-1](/ops/decisions), 본 항목 ✅ 후 [known-gaps](/ops/known-gaps) 의 "docs 사이트 UI 검색" 섹션 제거 |
| **B-axe-idp-1** 🔧 | **Blueprint = 플랫폼 OIDC Provider** — 로그인 1회로 전 서비스 ([D-axe-idp-1](/ops/decisions), 설계 SSOT [/architecture/platform-identity](/architecture/platform-identity)). **Phase 1 (모델 증명, 진행 중)**: Blueprint OIDC-OP(`.well-known/openid-configuration`·`jwks.json`·`/oauth/authorize`(getServerSession 재사용)·`/token`·`/register`·`/revoke`) + RS256 키(vault) + Prisma 모델(AuthCode·RefreshToken·Client) + `axe login` loopback PKCE + **frame 만** Blueprint 신뢰(`_is_blueprint_iss` 분기 + `auth_blueprint.py`). **Phase 2**: hive·cortex·index·matrix trust 이전 + frame/cortex 프록시([D-ops-14/15](/ops/decisions)) 통합·폐기. **Phase 3**: 인가 중앙화(`ent` 클레임 + fine scope) + 감사 UI + headless device-code + 키 회전. **비파괴 cutover**: 서비스별 flag `BLUEPRINT_ISSUER`/`BLUEPRINT_JWKS_URL` unset = 현행 그대로(롤백 = env 제거). | — | Claude Code (ai@axellc.com) | 2026-06-03 | 보안 핵심 → 설계 우선. **최종 검증 = 운영자 브라우저 SSO 1회 필요**(단독 e2e 불가). B-axe-cli-P0 후속. |

## 📋 Ready (다음 세션이 집어갈 수 있음)

> 📋 항목은 의존성이 해소돼서 **지금 시작해도 되는 것들**. 마일스톤 ID 가 묶음을 보여줍니다.

| ID | 항목 | 마일스톤 | 추정 | 의존성 / 비고 |
|---|---|---|---|---|
| **B-bp-mcp-teams-admin-consent** | Blueprint Next.js app (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`) 에 Microsoft Graph **`Chat.Read.All` + `ChatMessage.Read.All`** Application permission 추가 + tenant admin consent grant. 검증: `get_teams_message(url=...)` → 200 (현재 AADSTS65001 `invalid_grant` 502). 운영자 1회 작업. D-bp-mcp-teams-1/2/3 가 LIVE 됐으나 본 grant 부재로 tool 모두 사실상 unusable. `B-bp-mcp-calendar-2 admin consent` 와 동일 패턴 (known-gaps "Blueprint Azure App ID 혼동" 참조). 후속: `docker restart blueprint-app-green` 으로 MSAL `.default` 토큰 캐시 무효화 (D-bp-mcp-calendar-2 함정 #3). | M1 | 0.2d | 2026-05-26 본 세션 발견 (soohun.kang 1:34 메시지로 smoke test → 두 chat 모두 AADSTS65001). 운영자(Global Admin = soohun.kang) 만 가능 — `ai@axellc.com` 은 일반 사용자라 admin consent 권한 X (known-gaps D-bp-mcp-calendar-2 §"Global Admin = soohun.kang 단독"). |
| **B-cortex-xlsx-import-run** 🆕 | Cortex live 후 잔여 — `Network_CRM.xlsx` 660 행 enrichment 1회 마이그. 전제: operator 가 connect_google + sync_google_now 완료 (Google Contacts → person artifact). 절차: xlsx 를 macmini 로 복사 → `cortex import-xlsx --path <xlsx> --owner <whoami email>` (dry-run) → 매칭 통계 + private 카운트 확인 → 필요시 `--private-cols HPE,메모,소개` 조정 → `--apply`. owner_id 는 claude.ai 로그인한 Entra email (whoami 로 확인). 멱등 (subject+key 중복 skip). 완료 후 `~/Network/` → `~/Network.legacy/` archive + Network Manager Desktop OAuth client 폐기 | M1 | 0.3d | 2026-05-28 — cortex production live 후. CLI 전용 (로컬 파일이라 MCP tool 불가). **민감 컬럼 → `visibility=private` 태깅 구현 완료** (`--private-cols`, default HPE, commit `2ff4cf4`, [D-cortex-9](/ops/decisions)) — 잔여 = 파일 복사 + Google sync + 실 dry-run/apply (운영자 prerequisite) |
| **B-cortex-visibility-phase2-mirror-contract** 🆕 | [D-cortex-9](/ops/decisions) Phase 2 (M6 착수 시) — Blueprint mirror job 이 `visibility='shared'` 만 가져가도록 계약 enforce + field-level privacy (payload `private` 하위객체 mirror 제외 + 선택적 `CORTEX_PII_PASSPHRASE` pgp 암호화) + private artifact 의 audit event redact. 선행 = M6 Blueprint artifact mirror ([D-bp-artifact-1](/ops/decisions)) | M6 | 2d | 2026-05-28 요청 3.2+3.4. M6 (2026 Q4) 종속 |
| **B-cortex-visibility-phase3-e2e** 🆕 | [D-cortex-9](/ops/decisions) Phase 3 (opt-in) — client-held key sealed payload, 서버 복호화 불가. search_person(`payload::text ILIKE`)·Google push 포기 trade-off → 가장 민감한 메모만 "sealed" 모드 | M6 | 3d | 2026-05-28 요청 3.5 (보너스). 우선순위 최하 |
| **B-cortex-mcp-catalog-publish** 🆕 | `axe mcp publish` 로 cortex_mcp 를 Vaultwarden MCP Connectors collection 에 등재 ([D-vault-mcp-catalog](/ops/decisions)). customers.yaml `sso.apps.cortex_mcp` 이미 4-key (client_id + application_id_uri + scopes + client_secret_env) 있음 → publish idempotent. 그러면 다음 사용자가 claude.ai connector 등록 시 Bitwarden 확장이 URI 매칭으로 cortex 4-piece auto-suggest | M1 | 0.1d | 2026-05-28. frame/hive/blueprint 와 동일 |
| **B-cortex-google-oauth-verify** 🆕 | Cortex Google OAuth 앱 정식 검증(verification) 제출 → 동의 화면 "확인되지 않은 앱" 경고 제거. 앱 = External+production, 스코프 `auth/contacts` (**sensitive**), client `135512942819-l18ra7gkf1ac93ai8t4hf2h4jl6mi0a2.apps.googleusercontent.com` (project no. 135512942819). 현재 unverified → 동의 시 경고("고급 → 이동" 우회 중) + unverified 100-user 상한. 외부 개인 Gmail(kangthge@gmail.com 등) 온보딩 신뢰 문제로 검증 필요. **제출물**: 브랜딩(앱명·로고·지원이메일) + 앱 도메인(홈페이지·개인정보처리방침·서비스약관 URL) + 승인된 도메인 Search Console 소유권 verify(axelabs.ai) + 민감 스코프 정당화 사유 + OAuth 동의 흐름 데모 영상 → Google Auth Platform(`console.cloud.google.com/auth/*`) 제출. **금전비용 0** — contacts 는 sensitive(not restricted)라 CASA 제3자 보안평가 불필요(restricted였으면 수천 $/yr). 대안 기각: Internal user type = Workspace 한정이라 개인 Gmail 제외 부적합. 참고: production 전환으로 Testing 의 refresh_token 7일 만료는 이미 회피(sync 안정성 확보, 검증과 별개). | M1 | 0.5d (+Google 검토 수일~수주) | 2026-05-29 발견. 관문 = 개인정보처리방침/약관 페이지(axelabs.ai 정적 호스팅) — [B-legal-pages](/ops/backlog) 연계 |
| **B-axe-secret-pull-noquote** 🆕 | `axe secret pull` 이 env_file 작성 시 값에 따옴표를 붙이는데, docker compose `env_file:` directive 는 따옴표를 literal 로 처리 (compose `.env` variable substitution 과 다름) → 컨테이너 안 secret 에 따옴표 포함 → DB auth / API key mismatch. cortex 가 첫 피해 (postgres auth 실패, 수동 sed 로 우회). fix: `axe secret pull` 이 quote 안 붙이게 (또는 env_file 소비처가 strip). frame/hive 는 Python config 가 우연히 strip 해서 안 터졌을 뿐 | M1 | 0.3d | 2026-05-28 cortex 발견. [known-gaps Cortex #2](/ops/known-gaps) |
| **B-axe-tunnel-add-ingress** 🆕 | `axe tunnel add-ingress <hostname> <path> <service>` CLI 신설. `axe` 에 이미 `_cf_request` helper + CF API token (vault `Cloudflare API - axelabs`) 있음 → Cloudflare Dashboard remote-managed 터널의 ingress 를 GET→insert→PUT. cortex 등재 시 4-step curl 수동 (fetch config + jq insert + PUT) — 1 명령으로 축소. catch-all 보다 앞 + axe.axelabs.ai 의 no-path rule 보다 앞에 삽입 | M1 | 0.3d | 2026-05-28 cortex 발견. [known-gaps Cortex #7](/ops/known-gaps) |
| **B-artemis-tunnel-orphan** 🆕 | `artemis-tunnel` (cloudflared, Up, 2026-05-09 생성) 가 `project=artemis` compose 라벨만 달고 현 `docker-compose.yml` 엔 정의 없음 — [D-ops-20](/ops/decisions)(터널 axelabs 스택 이전)의 잔재. 증상: artemis 에 `docker compose` 명령 시 orphan 경고 + `down/up --remove-orphans` 시 **살아있는 터널 삭제** 함정. 조치: 용도 확인(서빙 라우트 식별) → 불필요시 `docker rm -f artemis-tunnel`, 필요시 axelabs 스택 compose 로 라벨 이전. 2026-06-03 artemis launchd 스크립트(filings/collectors/reporters) `docker run`→`docker compose run` 전환으로 경고 노출 빈도↑. | M1 | 0.2d | 2026-06-03 발견. 현재 동작 무영향(안전). [D-ops-20](/ops/decisions) 잔재 |
| **B-bp-entity-table-create** 🆕 | Blueprint Prisma `Entity` model 신설 ([D-bp-entity-canonical](/ops/decisions) Phase 1). schema = `Entity` 의 컬럼 (id text PK = axec/axev/axep/truvia, canonicalName 한글, customerId axe/realchoice, role 운영법인/GP/기타, isActive, createdAt) + EntityRole FK refactor (현재 EntityRole.entityId text → Entity.id FK). **데이터 seed**: (a) customers.yaml.entities iterate → Entity row 1 per id, (b) customers.yaml.entity_meta.(id).legal_name → canonicalName, (c) frame.shared.entity.legal_name 과 cross-check (D-bp-entity-canonical migration 의 frame i18n 정정 후 sync). REST endpoint `/api/admin/entities` (GET list + GET by id) — axe CLI 와 docs/inventory.mdx 가 fetch 가능. backward compat = customers.yaml.entities 는 SoT 유지 (deployment prerequisite, 부팅 self-contained) | M2 | 1d | [D-bp-entity-canonical](/ops/decisions). 선행 = `B-org-fanout-1` (organizationId FK pattern 일관) |
| **B-customers-yaml-entity-meta-derive** 🆕 | `customers.yaml.entity_meta` (2026-05-27 본 세션 신설) 를 Blueprint Entity 의 derived view 로 전환 ([D-bp-entity-canonical](/ops/decisions) Phase 2). **3 sub-step**: (a) axe CLI 의 `cmd_customers_list` 가 Blueprint REST `/api/admin/entities?customerId=(id)` fetch → entity_meta 표시 (yaml 의 entity_meta block 은 보존하되 "derived from Blueprint Entity, do not edit manually" comment 추가), (b) matrix collector 에 `entity_meta_drift_check` 추가 — customers.yaml 의 entity_meta vs Blueprint Entity table cross-check, mismatch detect 시 alert, (c) `axe deploy` 부팅 시 entity_meta 가 stale 이면 warning (단 부팅은 계속). transitional 기간 = Phase 1 완료 후 1 주 검증 + Phase 2 진입 | M2 | 0.5d | [D-bp-entity-canonical](/ops/decisions). 선행 = B-bp-entity-table-create |
| **B-axelabs-matrix-customers-yaml-direct** 🆕 | `axelabs.ai/matrix` UI 의 customer 정보 drift 영구 fix. **현재**: `/Users/axe/axelabs/app/api/matrix/customers/route.ts` 가 `http://axe-console-app:8228/api/customers` proxy. console-app = 폐기 대상 ([B-matrix-admin-retire](/ops/backlog)), docker ps 미가동, build 시점 prerender stale 본 노출. 2026-05-27 본 세션이 customers.yaml SoT (axec/axev/axep 한글명 + truvia rename + entity_meta 신설) 변경했으나 production UI 는 옛 본 (axe="에이엑스이 LLC" / axev 누락 / realchoice="리얼초이스 주식회사" / entities=["realchoice"]). **fix**: (a) route.ts 를 `fs.readFile('/axe-data/customers.yaml')` + js-yaml parse 로 변경 (console proxy 제거), (b) axelabs container `docker-compose.yml` 에 `/Users/axe/.axe:/axe-data:ro` mount + js-yaml deps 추가, (c) Next.js `revalidate: 0` 유지 + page 의 customers metric card 가 server-fetch (현재 client fetch → SSR 으로 변환 권장), (d) /api/matrix/services / launchd / containers / backups / console / state 6 route 도 동일 패턴 검토 (모두 console proxy). [D-bp-entity-canonical](/ops/decisions) "customers.yaml = deployment SoT" 정합 + [B-matrix-admin-retire](/ops/backlog) prerequisite (console-app 폐기 가능). 작업자 = axelabs container owner | 2026-05-27 | M1, 1d (route 6개 마이그레이션 + compose mount + rebuild + ship) |
| **B-org-fanout-1** | Blueprint `Workspace/UsageLog/Agent` 에 `organizationId` FK 추가 (`prisma/schema.prisma:688` "별도 PR" 주석 해소) — D-bp-org-fanout 신규 결정 등재 동반 | M1 | 0.5d | cross-tenant 쿼리 누락 = 전 고객 노출 차단 |
| **B-azure-multi-tenant** | `src/lib/auth.ts:101` 의 `AZURE_AD_TENANT_ID` 단일 env → per-org `Organization.azureTenantId` + multi-tenant Azure AD provider 분기 | M1 | 1d | B-org-fanout-1 선행 |
| **B-legal-pages** | TOS / Privacy / DPA / PIPA 4 페이지 신설 + Blueprint 노출 | M1 | 1d | 법무팀 review 1회 필요 |
| **B-edge-rate-limit** | Blueprint API edge rate-limit (per-org, IP 보조). Cloudflare WAF 또는 next/middleware | M1 | 0.5d | — |
| **B-sentry-wire** | Blueprint + frame + hive 에 Sentry SDK + DSN secret + sourcemap upload | M1 | 0.5d | vault 에 SENTRY_DSN 등재 prereq |
| **B-matrix-docker-deploy** | matrix Docker compose full deployment — launchd 또는 systemd 자동 시작 등록 | M1 | 0.5d | [D-matrix-1](/ops/decisions) |
| **B-matrix-blueprint-mcp** | Blueprint 에이전트에 matrix MCP connector 등록 | M1 | 0.5d | [D-matrix-1](/ops/decisions) |
| **B-matrix-admin-retire** | `admin.axelabs.ai` → `axelabs.ai/matrix` 리다이렉트 + `axe-console-app` 컨테이너 폐기. Caddy ingress 변경 + DNS CNAME 제거 | M1 | 0.5d | matrix 가 console 데이터 전량 흡수 완료 (2026-05-23). 인증(Entra ID OAuth) 미구현 — 상태 보드 공개 또는 별도 auth gate 결정 필요 |
| **B-matrix-wan-monitor** 🔧 | matrix collector WAN/인터넷 가용성 모니터링 (`wan-gateway`/`wan-internet`/`wan-dns` + ISP 귀책 판별) — [D-matrix-2](/ops/decisions). **상태**: 코드 구현 완료 (matrix branch `feat/wan-monitor`, `cargo check` 통과) + docs draft 완료. **잔여 = 운영자 검토 → docs `axe ship` (D-matrix-2 origin/main 반영) → matrix `axe ship` (blue/green rebuild, NET_RAW+iputils-ping+env 3종) → `/matrix/api/status` 에서 wan-* 등장 + 강제 차단 테스트**. 시작점 = 댁내 wifi 민원용 wifi.log 분석 (`~/wifi-complaint/`) | M1 | 0.2d (ship만) | 2026-06-03, ship 대기 |
| **B-matrix-wan-report-tool** 🆕 | matrix `get_wan_report` MCP tool (D-matrix-2 v2) — `check_results` 에서 `wan-internet`/`wan-gateway` 전환을 읽어 **장애 구간 (start/end/지속) + 업타임% + 귀책** 을 ISP 민원 제출용 타임라인으로 출력. wifi.log 일회 분석 (2026-06-03 `~/wifi-complaint/`) 의 상시 자동화 버전 | M1 | 0.5d | [D-matrix-2](/ops/decisions) v2, B-matrix-wan-monitor 선행 |
| **B-netheal-install** ✅ | 인터넷 자가치유 데몬 — [D-matrix-4](/ops/decisions). **완료 (2026-06-04)**: pty 고갈로 sudo 불가 → `osascript ... with administrator privileges` 우회 설치, `com.axe.netheal` LaunchDaemon 가동 중 (PID 16331, `netheal started` 로그, 오발동 0), inventory.mdx 등재. **잔여(선택)** = 콘솔에서 실 WiFi-바운스 치유 1회 검증 (원격 ~15s 끊김) | M1 | ✅ | 2026-06-04 |
| **B-frame-runtime-invariant-test** | DB CHECK runtime test (entity_kind 위반·ownership all-or-none·bounds·link_kind 등 invalid INSERT 차단 검증) + sum invariant (active row sum(numerator)==denominator) | M2 | 0.5d | [D-ops-22](/ops/decisions) 후속. tests/test_shared_fund_domain.py 의 metadata test 외 runtime layer |
| **B-bp-workspace-entity-nm** | Blueprint `WorkspaceEntity` join migration — D-bp-entity-1 plan 의 `Workspace.entityId` scalar → N:M 수정 | M2, M3 | 1d | D-bp-entity-1 plan 수정 등재 |
| **B-bp-para-dispatch-spike** | Path B Spike — DB 변경 없이 단일 workspace 로 PARA dispatch 흐름 검증 (3~5일) | M3 | 4d | 본 구현 (Path A) 전 권장 |
| **B-hive-payroll-cell-compare** | 첨부 급여대장 셀별 정확 일치 검증 (axec/axev 4월·5월 데이터) | M4 | 1d | payroll v2 ✓ 검증 마지막 단계 |
| **B-hive-dkim-prod** | hive 메일 발송용 DKIM/DMARC DNS prod 확정 (Cloudflare API token 자동화 검증) | M4 | 0.5d | [D-hive-23](/ops/decisions) |
| **B-backup-restore-drill** | frame-postgres / blueprint-postgres / hive-postgres restore drill 첫 실시 + 회고 + 정기 cron. **부분진척 2026-06-03**: `axe drill`(D-config-14 restic canary) 메커니즘 강화 — snapshot freshness 검사(`--max-age-days`·`--strict`, silent backup-stop 탐지) + robust canary(non-empty+YAML parse, customers.yaml live-drift false-FAIL 해소; axe-cli `fc0f29f`). **잔여 = 본 항목 핵심**: frame/blueprint/hive **postgres 실제 restore drill + 회고** (restic 스냅샷은 DB Docker 볼륨 미포함이라 별도 pg_dump 기반 drill 필요) | M5 | 1d | [D-hive-backup](/ops/decisions), [D-config-14](/ops/decisions) |
| **B-mysrt-backup-decision** | mysrt-postgres 의 SRT 외부 SOT 여부 사용자 확인 → Tier A 합산 또는 보류 결정 등재 | M5 | 0.5d | — |
| **B-frame-observability** | frame `observability.py` 의 Prometheus percentile 계산 — 현재 TODO 상태 | M1 | 0.5d | `/Users/axe/frame/src/frame/observability.py` TODO 코멘트 |
| **B-frame-lpm-classify** | LLM classify pipeline (`raw_transaction → journal_line` 자동 분류) — 현재 `analyze_file_format` 만 존재. **ETA 3-단계 (2026-05-25 RE^4 회신)**: (a) **D+90 (2026-09-01) minimum viable** — LLM proposal + 운영자 confirm + commit, 정확도 60~80% (axe 백테스트), (b) **D+120 (2026-10-01) rule-based pre-classifier 결합**, 정확도 80%+, (c) **2026-12-01 stable** — axec/axev 1년 backtest + 회귀 green. Truvia D+30 사이클은 수작업 분개 (`/services/frame#신규-customer-1-차-사이클-runbook`) 로 보완 | **M2 (top)** | 누적 4-6 주 | `/Users/axe/frame/DECISIONS.md` M2 Phase C, 트루비아 RE^4 |
| **B-frame-fund-cross-journal** | 펀드 cross-entity mirror 분개 도구 (GP commitment / 운용보수 / 성과보수) | M2 | 2d | `/Users/axe/frame/DECISIONS.md` D-frame-N4. B-frame-cross-journal-link 선행 |
| **B-frame-vat-schema** | journal_line 의 VAT (부가세) 컬럼 계산 로직 — 현재 컬럼만 예약, 로직 0 | M2 | 1d | `/Users/axe/frame/DECISIONS.md` "VAT handling... but no logic yet" |
| **B-hive-phase2-spike** | hive Phase 2 (성과평가 OKR/KPI, AI 목표 추천) 기능 명세 SPIKE 문서 작성 | — | 3d | `/Users/axe/hive/DECISIONS.md` Phase 2 scope. 본격 구현 전 명세 |
| **B-hive-dispatch-channel** | hive 이벤트 채널 5개 추가 (`employee.hired/terminated`, `payroll.finalized`, `compensation.granted`, `blueprint.agent.*`) | — | 1d | `/Users/axe/hive/DECISIONS.md` KNOWN_INCOMING_EVENT_TYPES Phase 2 |
| **B-hive-compensation-validate** | hive compensation Phase 3 검증 — 현재 Phase 1 schema 만, Phase 3 tools 검증 조건 정의 | M4 | 1d | `/Users/axe/hive/DECISIONS.md` Phase 1=schema / Phase 3=tools |
| **B-bp-artifact-propose-api** | Blueprint `POST /api/artifact/propose` REST endpoint 신설 — **cross-service automation 용 generic surface**. axelabs platform 내부 worker / 외부 서비스 / 사용자 정의 automation 이 artifact propose 가능. body = ProposeInput JSON. Bearer `ARTIFACT_PROPOSE_TOKEN` AppSetting auth (service-account, NextAuth session 미요구). admin UI 의 NextAuth-gated `/api/admin/mcp-schemas/refresh` 와 별 surface. response = StoredArtifact JSON | M6 | 2d | [D-bp-artifact-1](/ops/decisions). 통합 자체의 도메인 결정은 각 호출자 측 별도 |
| **B-mysrt-srt-risk-review** | SRT 약관 위반 risk 재검토 (자동 예매 기능, 계정 정지 risk) + 운영 정책 재정의 | — | 0.5d | `/Users/axe/mysrt/README.md` "약관 위반... 계정 정지" |
| **B-ops-stack-consolidation** | docker-compose 7-stack 통합 운영 시작 (`~/.axe/axelabs/docker-compose.yml` 신설 + 12→7 마이그레이션) | M1 | 1d | [D-ops-20](/ops/decisions) |
| **B-bp-artifact-arch-doc** | Blueprint artifact + PARA 아키텍처 결정 문서 본격 작성 — D-bp-artifact-1~7 등재 후 implementation 결정 문서 (`Artifact` 테이블 정확한 컬럼 / Citation 6-kind resolver contract / PARA dispatch field-level engine / MCP tool 시그니처 / ctx 진화 path) | M6 | 2d | [D-bp-artifact-1](/ops/decisions) ~ [D-bp-artifact-7](/ops/decisions). 코드 0줄, ADR landing |
| **B-bp-artifact-citation-resolver** | Citation kind 별 resolver (onedrive / frame.* / hive.* / teams.message / mail.thread / external.web) — typed contract + 통합 read API | M6 | 3d | B-bp-artifact-prisma 선행 |
| **B-bp-artifact-dispatch-engine** | PARA dispatch field-level engine — Project artifact 종료 시 Area/Resource/Archive routing rule + 자동 분배 (LLM 제안 + 사용자 confirm). copy + link 2 mode 지원. M3 의 workspace-level dispatch (B-bp-para-provenance-fields) 의 field-level 진화 | M6 | 5d | M3 PARA Dispatch land 선행 권장 + B-bp-artifact-link-table |
| **B-bp-artifact-query-api** | Cross-PARA / cross-artifact / time-travel query — **MCP tool 위주** (`query_knowledge`, `get_artifact`, `list_artifacts` 등 [D-bp-artifact-7](/ops/decisions) Layer 2 정합). 웹 UI 만 최소 REST endpoint (curation UX). agent SDK 가 grep 대신 typed query | M6 | 3d | B-bp-artifact-citation-resolver 선행 |
| **B-bp-mcp-paraLayer-tools** | `list_projects` / `list_areas` / `list_resources` / `search_archive` 등 paraLayer 별 MCP tool 분리 — LLM intent clarity (tool name 자체에 paraLayer 의도 드러남). + `create_workspace(paraLayer, ...)` / `close_workspace(id, dispatch_plan?)` / `reclassify_workspace(id, new_paraLayer)` workspace lifecycle tool | M6 | 2d | [D-bp-artifact-6](/ops/decisions). B-bp-artifact-query-api 와 같이 진행 가능 |
| **B-bp-workspace-lifecycle-ui** | 4 paraLayer 별 UI 페이지 신설 — `/axe/projects` (기존) + `/axe/areas` / `/axe/resources` / `/axe/archive` (신설). 각 page 의 "+New Workspace" 가 paraLayer 그 page 에 고정. + "Close Project" / "Reclassify" / dispatch plan 모달. ARAClient 의 3-tab 폐기 (분리로 대체) | M6 | 5d | [D-bp-artifact-6](/ops/decisions). B-bp-artifact-prisma 선행 (paraLayer 컬럼 활성) |
| **B-bp-ctx-skill-evolve** | ctx skill 진화 — markdown PKM → artifact curation interface. flows: agent propose → ctx review → confirmed fact + audit. markdown 은 보조 (review UX, archive). 기존 ctx sync/review/status 3 mode 호환 유지 + artifact 모드 추가. **+ markdown → artifact 점진 migration mode** (LLM extract 시도 → ctx review queue 등재 → 사용자 confirm/edit/reject → confirmed artifact + 원본 entry `<!-- migrated: <id> -->` 마킹) | M6 | 5d | B-bp-artifact-query-api 선행. [D-bp-artifact-5](/ops/decisions) |
| **B-bp-ctx-migration-mode** | ctx review 의 markdown → artifact propose flow (점진 마이그레이션 UX) — review queue 에 migration_propose event 표시 + source markdown 발췌와 extracted typed fact 나란히 + confirm 시 markdown entry 에 archive 마킹 자동 삽입. B-bp-ctx-skill-evolve 안 포함될 수 있으나 UX 작업량 명시 분리 | M6 | 3d | B-bp-ctx-skill-evolve 와 같이 진행 |
| **B-bp-markdown-archive-marker** | migrated 마킹 표준 (`<!-- migrated: <artifact_id> -->`) — 어떤 markdown entry 가 어떤 artifact 로 변환됐는지 trace. ctx review confirm 시 자동 삽입 + grep tool (`ctx migrated-trace <markdown_path>`) | M6 | 1d | B-bp-ctx-migration-mode |
| **B-bp-knowledge-overview** | Knowledge Overview dashboard (`/axe/knowledge`) — 3-pane layout (4 layer count + state / Sankey flow 지난 30일 / Cross-PARA query 입력) + Area health alert (stale 30일, inactive 90일) + drill-down view (PARA flow over time / artifact graph / provenance trace) | M6 | 5d | B-bp-artifact-query-api + B-bp-mcp-paraLayer-tools 선행 |
| **B-bp-artifact-ic-pilot** | IC pipeline 첫 vertical pilot — 1 deal (Sentry 권고) 의 §재무 가 raw markdown 대신 `ICMemoArtifact` 의 typed fact read. before/after 토큰 측정 + IRR 결정론성 검증. M6 활성화 검증 datapoint | M6 | 5d | B-bp-ctx-skill-evolve 후. Stage 0 PoC 의 production 변환 |
| **B-index-blueprint-citation-kind** | Blueprint `src/lib/artifact/citations/index.ts` resolver 신설 — `index.*` kind 14 sub-type 의 stable ID → MCP call mapping. `index.financial_output` → `query_irr` / `index.deal` → `get_deal` 등 | M7 | 1d | [D-index-6](/ops/decisions) Phase 1 |
| **B-index-ic-skill-push-mode** | ic skill SKILL.md 에 신규 Rule 25 (`--push-to-index` mode) 추가 + 산출물 5종 (financial_model xlsx + scenario_deltas yaml + exit_matrix yaml + memo md + recap yaml) → index propose 자동화 script. ctx review queue 경유 | M7 | 2d | [D-index-8](/ops/decisions) Phase 1, B-index-phase0-mcp-tools 선행 |
| **B-index-frame-event-mirror** | pg_notify `index_events` channel (capital_call / valuation_recorded / exit_distributed) + frame 측 `frame-worker` LISTEN 추가 + cross_journal_link 분개 mirror. frame M2 의 commitment_ledger 정합 | M7 | 2d | [D-index-9](/ops/decisions) Phase 2, M2 의존 |
| **B-index-axev-fund2-frame-register** | frame 에 `axe_ia_002` (액스 투자조합 2호) 등록 — Iippo 2호 split 의 fund entity 가 frame 에 부재 (현재 axe_ia_001 만). `frame register-entity --id axe_ia_002 --kind kvf` + fund_meta JSONB 채움 | M7 | 0.2d | M2 frame 펀드 회계 + index Phase 0 prereq |
| **B-ic-push-mode-impl** | ic skill `--push-to-index` 5th mode 구현 ([D-index-11](/ops/decisions)) — SKILL.md Rule 25 + Step 5.5 (40-60 lines) + gate_memo.sh post-V_COUNT atomic propose dispatch (80-120 lines, idempotency_key 계산 + `propose_deal_closure` curl + polling) + orchestration-initial.md (50-80 lines) + build_3fs.py / calc_irr.py / postmortem_stub.py minor edits. 총 ~280-350 lines. **backward compat 100%** (flag 미사용 시 기존 동작). `ic/index_push_state/v(N).json` local checkpoint 도입 | M7 | 2d | [D-index-11](/ops/decisions), B-index-phase0-mcp-tools 선행 |
| **B-portfolio-mgmt-deprecation** | `portfolio-management` skill 3-phase deprecation ([D-index-12](/ops/decisions)) — Phase 0 (즉시) SKILL.md 에 deprecation notice + Blueprint suggest UI 에 marker / Phase 1 (M7 Phase 1 launch 후) KPI 표 → `pmc/references/kpi-catalog.md` copy + cross-link / Phase 2 (3개월 후) SKILL.md disable (Blueprint search 에서 미노출) / Phase 3 (6개월 후) archive (`.deprecated/` 이동). 점진 패턴 [D-bp-artifact-5](/ops/decisions) 정합 | M7 | 0.5d per phase | [D-index-12](/ops/decisions) |
| **B-investor-relations-deprecation** | `investor-relations` skill 3-phase deprecation ([D-index-12](/ops/decisions)) — portfolio-mgmt 와 동형. LP 보고 구조 + 펀드 성과 지표 → `pmc/references/ir-lifecycle.md` migration. Phase 0/1/2/3 timing 동일 | M7 | 0.5d per phase | [D-index-12](/ops/decisions) |
| **B-index-error-model-enum** | `src/index/error_model.rs` Rust enum SoT ([D-index-14](/ops/decisions)) — 12+ case (IdempotencyConflict / ValidationWarning / SchemaNotFound / CitationResolveFailed / FinancialModelLocked / DslSyntaxError / UnknownEnum / DealNotFound / FundEntityNotFound / ServiceUnavailable / RateLimitExceeded / InsufficientScope) + `impl From IndexError to McpErrorResponse` deterministic mapping. ic/pmc skill 측 `lib/index_client.py` (또는 동형) 의 code 별 분기 handler. unit test 가 모든 case 의 wire-level response 검증. silent fallback 절대 금지 | M7 | 1d | [D-index-14](/ops/decisions), B-index-skeleton-mirror 선행 |
| **B-index-integration-fixtures** | `/Users/axe/index/tests/fixtures/ic_integration_phase0.json` + `pmc_integration_phase1.json` + `cross_skill_regression.json` ([D-index-14](/ops/decisions), D-index-15 정합) — Iippo (1:N fund) + Sentry (option round) + Canopy (multi-round) 3 deal regression. ic_integration_phase0 assertion: `propose_deal_closure` 성공 + `compute_outputs(base)` IRR ±0.5pp vs ic `v(N).xlsx` cell J42 + citation roundtrip resolve. cross_skill_regression: 5 skill (ic/dd/vc-deal-sourcing/portfolio-management/investor-relations) 동시 propose → audit_trail 충돌 없음 + 마지막 silent overwrite 검출. PR merge gate (`axe test index --fixtures`) | M7 | 1.5d | B-index-phase0-mcp-tools + B-ic-push-mode-impl 후 |
| **B-index-mcp-checklist-extension** | [/architecture/mcp-server-checklist](/architecture/mcp-server-checklist) § 8 운영 14 체크포인트 → **21** 항목으로 확장 — skill 통합 5 항목 (#17 skill idempotency 2× call 409 검증 / #18 citation resolver roundtrip ±0.001 percent / #19 cross-skill conflict 시 audit_trail 또는 last-write-wins + warning modal / #20 graceful degradation: index 죽이고 ic 호출 시 markdown-only fallback / #21 schema evolution: 새 field 추가 시 old skill 호환). `axe test index --accept-gate` 명령 + 24h production monitor (error rate under 0.1 percent, citation cache hit over 95 percent) | M7 | 1d | B-index-error-model-enum + B-index-integration-fixtures 선행 |
| **B-index-vision-boundary-rule** | xlsx vision 보조 vs PDF vision 분리 룰 ([D-index-15](/ops/decisions) worst-case #2 차단) — index 의 `ingest_financial_model_xlsx` 는 xlsx sheet/row label 만 vision (LLM 보조 inference), numeric cell value 는 mechanical (Rust calamine) 파싱 강제, PDF (IR pack 등) 는 vision 불가 → ingest skill 의 markdown clone 만. dataroom IR PDF 의 "5,941원" 가 "5,941엔" 오인식 → DB authoritative cell 가 되는 worst-case 영구 차단. 본 룰 `/services/index/financial-model.mdx` 추가 + ingest tool 의 input validation (PDF blob 거부) | M7 | 0.3d | [D-index-15](/ops/decisions), B-index-phase0-mcp-tools 선행 |
| **B-index-proceeds-bridge-retrofit** 🆕 | [D-index-22](/ops/decisions) 후속 — Iippo·Canopy 의 `legacy_ev` → `ev_bridge` per-leaf 전환. 두 deal 은 EV-based 이나 per-leaf 에 exit_ev_krw/exit_net_debt_krw/exit_stake_pct 미itemize (validate Check 7 = legacy_ev WARN 2건). **작업**: (a) Canopy — `exit_assumptions` 의 net debt 300억(EqV 498억) 를 per-leaf 로 분해, 40+ leaf 각각 exit_ev + stake 도출 → axe_proceeds ±2% reconcile, (b) Iippo — asset-light net debt 0, 30+ leaf 에 exit_ev(=proceeds/stake) + stake; **동시에 entry-F/D-flat dilution 교정** (중간 라운드 희석 미반영 → exit_stake 를 round-별 희석 반영값으로 — proceeds 수 pp 과대 낙관 해소), (c) proceeds_basis=ev_bridge 변경 + re-ingest + IRR ±1pp regression. Sentry(equity_value)·pre-IPO 3(mom) 는 bridge N/A 라 대상 아님. | M7 | 1d | 2026-05-29 [D-index-22](/ops/decisions). **검토 후 보류** (2026-05-29 "정확도 심화" 세션): (a) Canopy 는 per-leaf 순부채가 **원자료에 없어** itemize 하려면 시나리오별 부채를 근거 없이 가정해야 함 ([D-index-22](/ops/decisions) "없는 부채 날조 안 함" 원칙상 불가) — 모델-level net debt 300억은 이미 명시·정확, proceeds/IRR 도 검증됨 (즉 현 데이터는 정확, itemize 만 미수행); (b) Iippo net_debt=0 이라 itemize 가 tautological (exit_ev=proceeds/stake 환원); (c) **dilution 교정은 [D-index-24](/ops/decisions) 와 충돌** (Iippo/Sentry 는 executed → 모델 사후 재작성 금지). 숫자 불변 + WARN→PASS 표현 rigor 만이라 효과 대비 위험 큼 → legacy_ev WARN 유지가 정직. 실 DD per-leaf 부채 데이터 확보 시 재개 |
| **B-index-skill-overlap-sunset** | [D-index-17](/ops/decisions) overlap 기간 종료 후 Blueprint mirror 측 `.claude/skills/{ic,ingest}` 제거. 3 sunset 기준 모두 충족 시: (a) 다음 3 deal IC 가 `index/skills/ic/` 기반 정상 작동, (b) Blueprint Claude Agent SDK 의 index/skills/ mount/sync 자동화 확립, (c) ic skill `--push-to-index` mode 일반화 ([B-ic-push-mode-impl](/ops/backlog)). 작업 = Blueprint repo `.claude/skills/ic` + `.claude/skills/ingest` 디렉토리 삭제 + Claude Agent SDK 가 index/skills/ 또는 MCP 로 fetch 하도록 변경. drift 0 검증 (sha256). 충족 안 되면 overlap 지속 | M7 | 0.5d | 3 기준 충족 후 |
| **B-index-skill-versioning-schema** | [D-index-17](/ops/decisions) Phase 2 — `shared.skill_resource` table + `index.skill_resource@1.0` schema. name + version + skill_md + scripts (JSONB) + references_md (JSONB) + domain + locked_at + superseded_by. Per-deal trace: `index.ic_decision.skill_version_used` field 추가 → "이 IC 메모는 ic skill v8.3 으로 작성" 영구 audit. Cross-deal "ic v8.3 vs v8.0 평균 IRR" 분석 가능 | M7 | 1d | [D-index-17](/ops/decisions) |
| **B-index-dd-vc-sourcing-ownership** | [D-index-17](/ops/decisions) Phase 1 후속 — `due-diligence` + `vc-deal-sourcing` skill 의 index 산하 이전 검토. 두 skill 모두 투자 도메인이지만 ic + ingest 보다 결합도 낮음. 별도 결정 필요 (D-index-? 신규) | M7 | 0.3d (검토) + 1h (이전) | [D-index-17](/ops/decisions) overlap 안착 후 |
| **B-index-ingest-structured-extraction** 🔧 ⭐ | **✅ L1 SHIPPED (2026-05-30, [D-index-41](/ops/decisions), blueprint PR #379 merged → `~/.claude/skills/ingest` v2)** — convert_xlsx v2 (`{stem}_xlsx.cells.json` + key_outputs 자동탐지 + Model Summary/Key Outputs md) + convert_pdf v2 (`figures.json`). Apposter 20-sheet model → 31 key outputs(Exit IRR 57.2%/MoM 8.60x/EV 270억) 자동 surfacing(이전 truncated 주석 매몰), test 40/40, 의존성 0. **+ ✅ L2-core artifact화 SHIPPED ([D-index-42](/ops/decisions), index `4ca5868`, blue/green live)** — ingest sidecars → proposed artifacts (`artifact`+`citation`+`artifact_event` op=propose, RLS index_app+GUC, idempotent). artifact store 0→35 (dormant 던 store 첫 가동). **+ ✅ lifecycle SHIPPED ([D-index-43](/ops/decisions), `3eece93`+`118568a`, blue/green live)**: Query API(`query_artifacts`/`get_artifact`) + ctx review(`confirm_artifact`/`reject_artifact`) + L3-lite `reconcile_artifacts`(metric spread flag) + L2 `draft_seed_from_artifacts`(보수적 scaffold — 날조금지 구조강제, draft non-ingestable). 6 신규 MCP tool, 27 test. **+ ✅ metric_kind 세분 ([D-index-44](/ops/decisions), blueprint PR #380 — valuation/multiple/moic 분리+curation) + lifecycle 회귀 스위트(8 test, audit 영속성 발견) SHIPPED**. **잔여 (축소, 📋): ctx review UI(Blueprint markdown-diff) · Query API → /ic·seed-building primary read path 통합 · 전 deal artifact화(현 Apposter 1) · L4 versioned diff**. **⭐ 중요 — ingest 고도화: 단순 md transcription → source-type-aware structured extraction** (사용자 2026-05-30 "IR·Excel 이 md 로 소화 안 되는 케이스 많음"). ingest 는 파이프라인 정문이라 여기 손실은 ic·index 에서 복구 불가 (GIGO). 현 md photocopy = L0. **L1 (즉시·저위험)**: source-type routing — xlsx→구조화(HTML table 또는 cell+merge JSON), IR deck(PDF/PPT)→페이지 이미지+vision, 일반 prose→md 유지. 사용자 체감 손실(Excel 표 구조·deck 차트)의 80% 해결. **L2 (핵심 레버리지)**: transcription→typed extraction — ingest 가 베끼는 대신 index typed 스키마를 채움 ([D-index-31](/ops/decisions) intake 5필드 series·round_size·committed·entry_date·pre/post + exit 가정 + cap table → seed·financial_model 초안 생성). 지금 사람이 dataroom 읽고 손으로 쓰는 seed yaml 을 ingest 가 초안 잡고 사람은 검토·confirm — 정문 자동화. **L3 (품질 배수)**: cross-source reconciliation — deck vs xlsx vs cap table 수치 불일치 flag (silently 택1 금지) + confidence 태그 (mechanical=high · vision-inferred=review). **L4**: versioned/idempotent 재ingest diff (v2 IR vs v1 변경점). **불변식**: ① 숫자는 항상 mechanical(calamine) → vision 은 정성·cross-check 만 ([D-index-15](/ops/decisions) vision-boundary 정합·확장), ② 원본은 항상 evidence blob 보존 (fidelity SoT, 클론은 파생·교체가능), ③ 추출 fact 마다 citation(page/cell) 자동 부착. **선행**: 구현 전 D-index 결정으로 설계 ratify (extraction-not-transcription + source-type-aware 명문화). 관련 [B-index-vision-boundary-rule](/ops/backlog). | M7 | L1 1d / L2 3-5d / L3 2d | 2026-05-30 사용자 "중요". [D-index-15](/ops/decisions)+[D-index-31](/ops/decisions) 위에서 진행, D-index 결정 선행 |

## 🆕 신규 (분류 안 됨)

> 발견했지만 아직 마일스톤·우선순위·owner 미정. 다음 정비 시 📋 로 옮기거나 [known-gaps](/ops/known-gaps) 로 강등.

| ID | 항목 | 발견일 | 비고 |
|---|---|---|---|
| **B-index-judgment-in-seeds** ✅ ⭐ | **완료 2026-06-03 ([D-index-46](/ops/decisions), index `8ec2c10`)** — seed.yaml 이 judgment 단일 SoT: per-seed `judgment:`(assumptions+calibrations) + `seeds/_corpus.yaml` + seed-ingest `--emit-judgment`(natural-name anchor→corpus id 해소, idempotent). 23 seed 마이그레이션 후 `backfill.rs`+`corpus.rs`(2824 LoC) 삭제. GATE: 재ingest +0 new · committed wipe→재현 byte-identical(42 dup citation pruned) · append-only intact · 51 test · validate-seeds Δ0. 신규 deal 자동 artifact화 — hardcode transcription 0. | 2026-06-03 ✅ | [D-index-46](/ops/decisions) |
| **B-index-epic2-confidence-load-bearing** 🆕 | [D-index-45](/ops/decisions) Epic 2 — confidence 를 장식→load-bearing. 입력 assumption 신뢰도를 출력(E[CF]·E[MoM])으로 전파: 미확정/저신뢰 가정 위 딜은 저신뢰 플래그. provenance 위 confidence rollup. epistemic 차별점 심화. | 2026-06-03 | M7, 2-3d |
| **B-index-epic3-self-calibrating-loop** 🆕 ⭐ | [D-index-45](/ops/decisions) Epic 3 (북극성) — prediction→outcome→recalibration. IC 시점 calibrated E[CF]/P(loss) 를 불변 `prediction` artifact 로 freeze → 실제 outcome(exit·후속·writeoff) 포착 → deal-class 별 예측-실제 bias 노출(체계적 낙관/비관) → 다음 IC 자동 보정. base-rate corpus(현 35 comp+5 base_rate) 누적. Palantir 가 안 주는 복리 자산. **outcome-capture 는 B-index-postmortem-loop 가 공급.** | 2026-06-03 | M8, prediction freeze 선행 |
| **B-index-pmc-operational** 🆕 ⭐ | [roadmap M7 Phase 3](/ops/roadmap) — pmc(Post-Money Care) 운영 파이프라인. 현재 pmc 는 skill skeleton([D-index-12](/ops/decisions)) + P3 에서 blueprint mirror 됐으나 **index persistence 미구현**. 8-agent 분기 cycle(KPI/risk/NAV/postmortem) → `index.portfolio_kpi`·`risk_alert`·`valuation_snapshot`·`postmortem` typed fact + pmc `--push-to-index`. IC결의~Exit(5년+) 포트폴리오 케어 phase. | 2026-06-04 | M7 Phase 3 |
| **B-index-postmortem-loop** 🆕 ⭐ | [roadmap M7 Phase 3](/ops/roadmap) — post-mortem 루프: ic `postmortem_stub` → reminder cadence → pmc fill → `index.postmortem`(IC 예측 vs 실제 회고). **Epic 3 의 outcome-capture leg** — prediction(freeze)과 짝이 되어 self-calibrating 루프를 닫음. ic postmortem_stub/reminder(투자 phase) + pmc fill/render/push(care phase) 2-track([D-index-12](/ops/decisions)). | 2026-06-04 | M7/M8, Epic 3 짝 |
| **B-index-evidence-durability** ✅ v1 ⭐ | **v1 완료 2026-06-04 (index `b273979`, deployed)** — citation `sha256` content-anchor(범용·무의존) + Blueprint-id 필드 readiness(`workspace_id`/`driveItemId`/`marker`/`rel_path`). `CitationAnchor`+`is_durable`(durable = sha256 OR drive_item_id OR workspace_id+rel_path) · ingest sidecar sha256 emit + **propose-time fallback hashing**(skill 무변경에도 durable) · `verify_citations(deal?)` MCP tool · 현황 페이지 "citation durability %" 라인. additive(기존 357 artifact/545 citation byte-identical) · 80 test · validate-seeds Δ0 · 공개 페이지 누출 0. 폴더 이동·삭제 분석 + 운영자 "workspace unique id" 제안에서 도출. | 2026-06-04 ✅ | [D-index-45](/ops/decisions)/47 |
| **B-index-evidence-durability-v2** 🆕 | [roadmap M7 Phase 3](/ops/roadmap) — v1 deferred 잔여(cross-repo): ① 기존 545 path-only citation **backfill**(resolvable source hash→ref 에 sha256 merge, 또는 deal 별 재ingest) ② **Blueprint resolve API**(stable id→현 위치, sync 갱신) ③ `driveItemId`/`workspace_id` 채우기(Blueprint `Workspace` 쿼리) ④ ic/ingest skill blueprint mirror(런타임이 sidecar sha256 emit). v1 schema/predicate 가 이미 수용. | 2026-06-04 | M7 Phase 3, cross-repo |
| **B-index-skill-p1-stamp** ✅ | **완료 2026-06-03 ([D-index-47](/ops/decisions), index `11aca12`, deployed)** — `artifact_event`(op=propose).payload_after 에 `_provenance`(skill·skill_version·bundle_sha256·schema_envelope_version·frozen_enums_hash·actor·surface) 스탬프 + propose 시 schema-drift hard gate(불일치→`SCHEMA_CONTRACT_DRIFT`, insert 전 fail-closed). frozen_enums_hash=`3b58b4b0…`(전용 SoT fn, pinned tripwire test) + /index/schemas 가 publish(ic-push discover+pin). 66 test(+17) · additive(기존 357 untouched, append-only 라 retro-stamp 불가) · validate-seeds Δ0. live: 드리프트 probe→SCHEMA_CONTRACT_DRIFT(무오염). | 2026-06-03 ✅ | [D-index-47](/ops/decisions) |
| **B-index-skill-p2-ci-mirror** ✅ ⭐ | **완료 2026-06-03 ([D-index-47](/ops/decisions), index `6edf0ff`)** — ⭐ **"런타임 fix" 는 이미 달성**(P0 + 기존 sync): ic/ingest 가 index SoT↔blueprint origin/main↔런타임 전부 byte-identical(attest: ic `cb9b9ec`/ingest `7d09bcd` IN-SYNC). 그래서 P2 = content push 아닌 **메커니즘**: `index-skill-sync.py`→`--attest`(deterministic dir-sha256 drift sentinel, advisory) 재범위(깨진 byte-delivery 제거) + `index-skill-mirror.sh`(미래 미러, sanctioned PR flow, pmc fail-closed 거부) 빌드. **blueprint 무쓰기·무push·무PR**, pmc 보류(P3). | 2026-06-03 ✅ | [D-index-47](/ops/decisions) |
| **B-index-skill-sync-wrapper-retire** ✅ | **resolved 2026-06-03 — neutralized by P0** — `blueprint/scripts/sync-index-skills.sh` 는 (a) origin/main 에 없음(untracked local-only) (b) 호출하던 launchd `ai.axe.index-skill-sync.plist` 가 P0 에서 폐기 → **invoker 0 = 무해**. 물리 파일은 blueprint working-tree 의 untracked 파일(병렬 세션 활성 편집 중 — re-point 가능성) → index scope 밖, blueprint tree owner 가 rm/re-point. index-side action 불필요. | 2026-06-03 ✅ | [D-index-47](/ops/decisions) |
| **B-index-skill-p3-contamination-purge** ✅ ⭐ | **완료 2026-06-03 ([D-index-47](/ops/decisions), blueprint PR #381 gate + #382 pmc, both squash-merged origin/main)** — 8 투자 skill(ic·ingest·due-diligence·vc-deal-sourcing·investor-relations·portfolio-management·legal-compliance + pmc)에 `owner:index` 태그 + boot(`start.sh`)/webhook(`route.ts`) 양 경로 gate(customer `services.index` 판정 → 비-index `rm -rf`+skip purge, index keep). **axe 3중 안전**(services.index + `:-axe` 기본 + fail-safe keep + 운영자 skills-sync.sh ungated → simul KEEP 16/16) · realchoice/Truvia PURGE 7/KEEP 9 · `customers.ts customerHasService` + test 21/21 · tsc 0. pmc(index-only)도 base 로 mirror(gated→axe 만). **운영자 잔여**: Truvia `BLUEPRINT_CUSTOMER_ID` 확인 + 컨테이너 재기동(boot gate 가 purge) + R7 DB residue(assigned skill row). rollback=revert(axe 무영향). | 2026-06-03 ✅ | [D-index-47](/ops/decisions) |
| **B-index-skill-owner-frontmatter** 🆕 | [D-index-47](/ops/decisions) follow-up — ic/ingest/pmc SKILL.md frontmatter 에 `owner: index` 추가(현재 `INDEX_OWNED.txt` manifest 가 de-facto SoT, frontmatter 미기재). drift-guard 가 frontmatter 키로 동작 시 필요. blueprint mirror PR 동반. | 2026-06-03 | 소, P2 동반 |
| **B-index-ic-screen-mode** 🆕 | [D-index-36](/ops/decisions) 후속 — `/ic` skill 에 lightweight **screen-mode** 통합. 현재 Screening 게이트는 수동(Claude best-effort: 외부 리서치 5종 + research-calibrated 재무모델 + engine IRR(E[CF]) + premortem 가정라벨). 이를 `/ic --screen`(또는 stage 자동감지)로 정규화: 19-agent full 대신 축약 파이프라인(market/competition/comps base-rate research + financial model + premortem-critic + screen-memo synthesist), **dataroom 불요**(teaser/1-pager 입력), 산출 = ic/memo screen + research + finance + index 적재(stage='Screening'). DD 전환 gate(조건) 명시. 첫 수동 사례 = 에듀온([D-index-36](/ops/decisions)). | 2026-05-30 | M7, 1.5d. ic skill 4-mode(INITIAL·REVISION·APPEND·FINALIZE)에 SCREEN 추가 |
| **B-hive-compensation-adjustment-impl** ✅ | hive `compensation_events.adjustment` 정식 MCP 도구 구현 — D-hive-17 후행 leg 완성. **2026-06-01 완료 ([D-hive-29](/ops/decisions))**: `compensation_event_adjustment_create(employee_id, period_label, line_kind, delta_krw, reason, evidence_url?)` admin scope. 페이슬립 line append + 합계 보정 + `compensation_events.adjustment` audit row + `hive.payroll.event` (subtype=adjustment) 발행. `compute_period` UPSERT-with-gates 의 case C/D/E (발송됨/지급됨/역분개됨) skip 케이스의 정공법 정정 경로. `delta_krw` 부호 = `line_items.amount_krw` 부호 (공제 460원 증가 = -460). 발송된 페이슬립 정정 시 직원 메일 ≠ DB → 운영자 재발송 책임 (운영 절차). | 2026-05-30 → 2026-06-01 ✅ | [D-hive-17](/ops/decisions) + [D-hive-29](/ops/decisions) |
| **B-frame-payroll-event-consumer-adjustment** 🆕 | frame consumer-worker 측 `hive.payroll.event` LISTEN + subtype='adjustment' dispatch → 인건비 정정 분개 자동. [D-frame-1](/ops/decisions) pending_payroll 패턴 정합 (이중 분개 위험 0). [D-hive-29](/ops/decisions) 동반 — hive 측 event 발행 ✅ but consumer 측 미구현. 본 leg 없으면 frame 분개 ≠ hive 페이슬립 차액 누적. | 2026-06-01 | M3, 1.5d. [D-hive-29](/ops/decisions) |
| **B-hive-adjustment-auto-redispatch** 🆕 | `apply_adjustment` 직후 `send_payslip_email` 자동 호출 (`auto_redispatch=True` default) + 메일 본문 템플릿에 정정사유·차액·새 net 표시 (정정명세서 전용 템플릿 `payslip_adjusted.j2`). 운영자가 "정정 → 재발송" 두 step 잊지 않게. 직원 메일 (옛 net) ≠ DB (새 net) 정합 갭 해소. | 2026-06-01 | M3, 1d. [D-hive-29](/ops/decisions) |
| **B-hive-adjustment-operator-alert** 🆕 | `apply_adjustment` 직후 Blueprint Teams DM 운영자 알림 (`payslip 정정 ps#<id> 직원 <name> <delta>원 — 재발송 자동 ✅ / 운영자 확인 필요 ⚠️`) — `auto_redispatch` 실패 / 차액 송금 필요 시 강조. | 2026-06-01 | M3, 0.5d. [D-hive-29](/ops/decisions) + B-hive-adjustment-auto-redispatch 후속 |
| **B-hive-payroll-base-policy-decision** 🆕 | hive `compute_period` 의 4대보험 base **일할 케이스 정책 결정** — 현재 [D-hive-29 룰 K](/ops/decisions) 로 base = `reported_income_*_krw` (보수월액), 값은 R(과세표준)과 같게 set 정책. **정액 케이스**: 보수월액 = R → 결과 일치. **일할 케이스** (신규 입사·중도 퇴사): R(일할 적용된 변동값) vs 보수월액(고정값) → 결과 다를 수 있음. 예: 강태훈 axev 2/19 입사 → 2월 prorate. compute_payroll_v2 가 `taxable_total` 에는 prorate 적용 (= R 변동) 하는데 base = reported_income 사용 시 보수월액 고정값으로 NPS/NHIS 계산 → 일할 적용 안 됨. **요구**: 일할 케이스 시뮬 + 회계법인 cross-check (NPS/NHIS 공단 정합 = 일할 시 보수월액도 비례 조정? 또는 고정?) → 룰 K 보강 결정 (예: 일할 비율을 보수월액에도 곱 적용 vs 보수월액은 항상 고정). | 2026-06-05 | M3, owner: 강수훈 dev. 우선도 🟡 중간 (현재 정액 결과 정합이라 시급 X). [D-hive-29](/ops/decisions) 룰 K 후속 일할 정책 |
| **B-index-ingest-pipeline-candidates** 🆕 | 2026-05-30 데이터룸 스캔 발견 — index 미적재 deal 중 **IC 완료 후 적재 대상**: **Prj_Render** (dataroom + ic 스캐폴드 有, IC 메모 미완 → 메모 완료 시 적재), **Prj_Whale=위시켓** (보유 포폴 — 세무조정·주식이관·주총·등기 admin docs 만, 원 IC 재무모델 확보 시 적재). 비대상: 델리후레쉬(RFP 제휴건), Pipeline 잔여(Curi AI·엘리시움 등 — 미screen). **적재 완료** (7-deal): Interstellar(10th, PASS)·에듀온(11th, Screening PASS [D-index-36](/ops/decisions))·EGA(12th, IC)·수성별(13th, Passed)·Nanora(14th, full IC, [D-index-37](/ops/decisions))·**디벨로퍼그룹(15th, buyout-class)·유비랩(16th, Screening)** ([D-index-38](/ops/decisions), 2026-05-30). 나머지 Pipeline 은 screen 또는 IC 시 D-index-36/21/24/26 프로토콜 적용. **Prj_Render = 리얼초이스/트루비아** = 2026-05-30 best-effort SCREEN 완료 → 적재 (23rd, [D-index-40](/ops/decisions), par-entry cheap-option). ⭐ **별도 Archive batch** (`1_Project (Archive)`): Medistaff·Open Research·JS E&L·Catalyst·데이톤·Apposter 6건 = [D-index-39](/ops/decisions) 적재 (17~22th, 전부 미투자/correctly-avoided). **⛔ 데이터룸 소진 (DB 23)** — 잔여 = Prj_Whale=위시켓(executed 포폴이나 원 IC/재무모델 부재, **자료 확보 시 적재**) · Purple AI/TR Corp/엘리시움(DHP 빈 폴더, 자료 입수 시 screen) · 이노씨앤에스/Curi AI/가람봇/딥트리/블루밍(thin lead). 비-딜: Prj_Artemis(AXE 자체 제품)·델리후레쉬(RFP). | 2026-05-30 | M7, deal당 ~1d (screen) / DD 시 full /ic |
| **B-blueprint-broadcast-mail** 🆕 | Blueprint `/api/admin/broadcast-dm` (Teams DM) 와 동급의 **실 SMTP/Graph email broadcast REST 추가** — `/api/admin/broadcast-mail`. 본 use case = 운영자가 임직원 1:N 공지 시 Teams DM 외에 이메일도 발송 필요한 경우 (외부 회계법인 cc / 감사 audit trail 보존 / 비-Teams 사용자 대비). `sendEmail()` 함수 (`src/lib/graph.ts:412`) + Mail.Send permission 이미 보유 — REST wrapper 만 추가하면 됨. Auth 동일 `CRON_SECRET`. 운영 정합 = [/ops/runbook/operator-broadcast](/ops/runbook/operator-broadcast) 의 함정 표 그대로 적용. 사용 빈도 추정 = 분기 1-2회 (vault 공지 / 신규 customer launch / 시스템 변경). 본 작업 ROI = 작음 (Teams DM 으로 대부분 충분), 다만 audit trail / 외부 cc 가 본질 필요한 deal 결정 발생 시 즉시 우선순위 ↑. **2026-05-29 update**: MCP `send_mail` ([D-bp-mcp-mail-1](/ops/decisions)) 가 agent/connector 의 단발(1:N 임의 수신자 포함) 발송 + `MailSendLog` audit + 외부 cc 를 이미 커버 — 본 항목은 이제 **운영자용 REST bulk broadcast** (CRON_SECRET auth, 비-MCP 트리거) 한정으로 축소, ROI 더 작아짐. | 2026-05-26 | M5, 0.3d |
| **B-axe-secret-prompt-store-cli** 🆕 | `axe secret prompt-store <name> --collection X --uri ... --username ...` CLI subcommand 신설 — [vault-secret-capture](https://github.com/axelabs-ai/blueprint/blob/main/.claude/skills/vault-secret-capture/SKILL.md) skill 의 osascript hidden-dialog + vault item 저장 패턴을 한 줄 명령으로. 사용 빈도 (PAT 발급 / API key 등록 / OAuth client_secret 회전 등) 증가하면 진행. 본 작업 ROI = 중간 (skill 로도 충분, CLI 화 = 운영자 본인 typing 짧아짐). | 2026-05-26 | M3, 0.3d |
| **B-dev-platform-dns-placeholder-cli** | `axe customers dns-placeholder <id>` — Cloudflare DNS API 로 `<id>.axelabs.ai` 의 CNAME stub 추가 (tunnel target). vault token (`Cloudflare API - axelabs`) 가 zone DNS Edit 보유 — 즉시 가능 | 2026-05-23 | 1시간 추정 |
| **B-dev-platform-customer-deploy** | `axe customer deploy <id>` — D-dev-platform-2 후속, customer macmini side. SSH (Tailscale/Cloudflare Tunnel) 로 customer 머신 진입 → Docker stack (frame/hive/blueprint blue/green + postgres + caddy) 배포 + cloudflared tunnel 등록 + customers.yaml 동기화. realchoice 첫 실 운영 | 2026-05-23 | b5 — 2-3시간 추정. M1-M2 |
| **B-dev-platform-user-add-cli** | `axe user add <email> --customer <id>` — Phase 1 강태훈 setup (macOS user + SSH key + Vaultwarden item + GitHub collaborator + Cloudflare Access policy) 의 자동화. 본 PR 의 강태훈/Soohun 수동 절차 1 명령으로 | 2026-05-23 | Phase 1 의 반복 가능 형태 |
| **B-axe-pat-rotation-cron** | GitHub PAT (axe-labs-ai, 90일 TTL) + Cloudflare token + 기타 vault secret 의 만료 D-7 launchd alert (D-bp-alert-1 패턴) + `axe secret rotate <path>` end-to-end 회전 명령. D-dev-platform-4 의 운영 prereq | 2026-05-23 | 0.5d |
| **B-dev-platform-host-rebuild-doc** | axe-macmini 전체 host 재구성 시 본 세션의 multi-user setup 재현 자동화 — sudoers + dev group + macOS users + sshd_config drop-in + Cloudflare tunnel + Vault. ad-hoc script 가 아니라 도구화 (e.g. `axe host bootstrap`) | 2026-05-23 | 1d |
| **B-axe-host-inventory-cli** | `axe host inventory` — 본 머신 13 layer ([ops/host-setup](/ops/host-setup)) 의 현재 값 자동 수집 + docs 의 표 와 drift detect → markdown report. 신규 머신 진단 + 본 머신 정기 audit (launchd cron) | 2026-05-23 | 1d. D-host-setup-1 후속 |
| **B-axe-host-bootstrap-cli** | `axe host bootstrap` — 신규 macmini 의 layer 1-13 자동 setup. inventory CLI 의 reverse — 본 머신 현 값을 reference 삼아 신규 머신 동일 상태로. layer 0/6/12 (Hardware/Entra/OneDrive) 는 manual prompt, 나머지 자동. Tailscale invite + Cloudflare tunnel UUID 발급 + sudoers + SSH + Docker stack + launchd + git config 모두 1 명령 | 2026-05-23 | 3-5d. realchoice 본격 onboarding 의 핵심 prereq |
| **B-axe-pty-max-launchd** | `kern.tty.ptmx_max=511` 한도 → 2047 로 늘림 + launchd plist 로 boot 시 자동 적용 (sudoers `/usr/sbin/sysctl` 추가 필요). Claude Desktop PTY leak 같은 함정 영구 차단 | 2026-05-23 | 0.3d. ops/host-setup 의 알려진 함정 |
| **B-claude-desktop-pty-leak-track** | Claude Desktop app (`/Applications/Claude.app/Contents/MacOS/Claude`) 의 PTY leak. **재발 확정 — 2026-05-26 D-bp-mcp-calendar-2 ship 중 `forkpty: Device not configured` (ENXIO) 로 새 터미널 차단** (43일 가동 누적, 511 한도 도달). `lsof /dev/ptmx` 결과 = Claude.app PID 가 fd 43,44,46,88,89,92,94,98,99,102+ 점유. userspace zsh 좀비 (82개 누적, Claude Code subprocess) 정리해도 해소 안 됨 = Claude.app 본체 leak 확정. macOS `kern.tty.ptmx_max` 가 511 초과 거부 → sysctl raise 무효 → Claude.app 종료/재시작이 유일한 fix. **Anthropic 측 issue 제기 (5/26 재발로 1주 모니터 기간 단축, B-claudeapp-fd-leak-anthropic-report 로 split)** | 2026-05-23, 2026-05-26 재발 | 모니터 → 리포트 |
| **B-blueprint-user-add-entra-oid** | Blueprint `User` 테이블에 `entraOid` 컬럼 추가 (NextAuth Azure AD callback 에서 `account.providerAccountId` 또는 `profile.oid` 저장). 현재 `User.id` = Prisma cuid 라 Graph `/users/{key}` 호출 시 UPN/email 만 사용 가능. 미래 Graph endpoint 중 oid 만 받는 것 (event subscription, change notification 등) 대응. D-bp-mcp-calendar-2 의 send-as 함정 발견 직접 결과 ([/ops/known-gaps#blueprint-user.id-≠-microsoft-entra-oid](/ops/known-gaps)) | 2026-05-26 | 0.3d (schema migration + auth callback 갱신 + 백필 1회) |
| **B-msal-cache-flush-on-consent** | Azure App admin consent 직후 MSAL `acquireTokenByClientCredential` 의 in-memory 토큰 캐시가 옛 (insufficient-scope) 토큰 계속 반환하는 함정. 현재 우회 = blueprint-app 컨테이너 수동 재시작 (전체 MSAL instance 폐기). 영구 fix 후보: (a) `getMsalApp()` 의 캐시 invalidation hash 에 "last admin consent timestamp" 같은 외부 signal 포함 — Azure CLI 의 admin-consent 명령 후 운영자가 `axe blueprint touch-msal-cache` 한 줄 실행, (b) `acquireTokenByClientCredential({ skipCache: true })` 를 매 호출 사용 (성능 영향 검토), (c) MSAL 의 `clearCache()` API 호출하는 admin endpoint 신설. (a) 가 가장 간단. ([/ops/known-gaps#msal-acquiretokenbyclientcredential-토큰-캐시](/ops/known-gaps)) | 2026-05-26 | 0.5d |
| **B-frame-cross-check-workflow** | 외부 회계법인 cross-check workflow — frame 의 monthly trial_balance / income_statement export + 회계법인 회신 매칭 + adjustment 분개 자동 생성. hive payroll L2 패턴 mirror. Truvia 측 외부 회계법인 협의 결과 회신 시 본격 등재 (사내 협의 진행 중) | 2026-05-25 | M2, 1d (회신 후) |
| **B-customer-deploy-generalization-phase3-3rd-customer** | B-customer-deploy-generalization Phase 3 잔여 — 3rd customer dry-run (realchoice 이후 다음 신규 customer 의 self-deploy 검증). Phase 1 + Phase 2 (realchoice D-day) ✅ 2026-05-25/26. 3rd customer 사례 발생 시 axe CLI flow 재현성 확인 + 추가 함정 발견 시 R6+ phase 등재 | 2026-05-25 | M2, 0.5d (3rd customer onboard 시) |
| **B-cf-token-rotation-2026-05-25** | Cloudflare API token (`Cloudflare API - axelabs`) 의 실제 값이 본 세션 transcript (axe secret get 출력) 에서 평문 노출. 토큰 가치 = 도메인 zone DNS Edit 권한 = 운영자 측 인프라 통제. 회전 권장: Cloudflare dashboard → API token → revoke + 신규 발급 → `axe secret push CLOUDFLARE_API_TOKEN ...` | 2026-05-25 | M1, 0.3d |
| **B-realchoice-d-plus-checklist** | realchoice 측 후속 회신 (RE^2 §7): vault 데이터 마이그레이션 plan (D+7), 마케팅 에이전트 10 → Blueprint Agent row 매핑표 (D+7), nemotron-personas 라이선스/origin (D+14), 2026 4Q 회계 병행 인력 분배 (D+30). 각 회신 시점에 docs / customers.yaml / Blueprint Agent row 반영 | 2026-05-23 | M1-M2, 각 0.5d (회신 후) |
| **B-magnet-tenant-env-injection** | `axe ship magnet --customer <id>` 가 `customers.yaml.service_tenant_map.magnet` 에서 `MAGNET_TENANT_SLUG`/`MAGNET_TENANT_ID` 자동 주입. 현재는 service operator 가 .env.local 수동 편집. D-magnet-tenant-map-1 후속 | 2026-05-23 | M1, 0.5d |
| **B-nemotron-catalog-promote** | Truvia 측 D+14 라이선스 회신 후, cross-customer OK 면 `/services/nemotron-personas` placeholder 본격 보강 + Blueprint MCP registry 등재. cross-customer X 면 `customers.realchoice.private_services[]` 신설 + 라이선스 박스 명시 | 2026-06-15 | M1, 0.5d |
| **B-operator-bus-factor** | 운영자 SPOF (인력 1 명만 운영 가능) 해소. 2 인 이상 운영 가능 + cold SSD paper memo 분리 ownership + 분기 drill. 트루비아 측 보고서 (RE^2 §Q8) 가 drill 동참 의사 명시 — 분기 drill 일정 사전 통보 약속 | 2026-05-23 | M5, 2d |
| **B-container-name-customer-prefix** | `frame/docker-compose.yml:197 (axe-frame-proxy)`, `hive/docker-compose.yml:124 (axe-hive-proxy)`, `vault/docker-compose.yml:29/66 (axe-vaultwarden, axe-vault-caddy)` 의 container_name 이 `axe-` prefix 박혀 있음 — customer-per-macmini 격리로 충돌 없으나 realchoice macmini 에 `axe-frame-proxy` 가 떠서 misleading. `${CUSTOMER_PREFIX}-` 변수화 또는 customer-agnostic 으로 정규화. 트루비아 측 첫 보고서 직접 지적 (2026-05-23). 운영 영향 0, docs/도식 명확성 中 | 2026-05-23 | M1, 0.5d |
| **B-axe-labs-ai-2fa** | axe-labs-ai GitHub 계정 2FA 강제 활성 — Settings → Password and authentication → Two-factor authentication. PAT 분실/유출 시 추가 보호 layer. ai@ 자동화 영향 0 (PAT 는 2FA 우회) | 2026-05-23 | 0.1d. 운영자 5분 |
| **B-hive-send-202605** | axev 2026-05 실 메일 발송 (`payroll_send_all_payslips dry_run=false`) — **2026-05-28 hive MCP 검증 결과 partial**: 강태훈 ✅ sent (send_log id=6, channel=graph_api, status=sent, 2026-05-25T15:11:51), 한진우 ❌ pending (RRN 등록 선행 [B-hive-hanjinwoo-rrn]). DKIM/DMARC live 검증된 상태. 한진우 RRN 입력 후 본인분 send 실행 시 본 항목 ✅ 가능 | 2026-05-22 | period_id=4 |
| **B-hive-mark-paid-202605** | axev 2026-05 KB 일괄송금 + `payroll_mark_paid`. hive event 발행 → frame-worker pending_payroll INSERT 예약 | 2026-05-22 | D-frame-1 흐름 |
| **B-frame-ingest-kb-202605** | KB 거래내역 download → frame.ingest_kb_* → `match_pending_sweep` 자동 매칭 분개 생성. matching principle 검증 cycle 1번째. **2026-05-28 frame MCP 검증**: axec raw_transaction 일부 존재하나 전부 `journaled=false` (+ 0원 카드 가승인/취소 noise) — 실 KB 거래내역 download + matching cycle 미수행 = pending | 2026-05-22 | D-frame-1 |
| **B-hive-202604-recon** | axev 2026-04 cycle 산출 + mark_paid (강수훈 정산 24,660 환급 분개 발행) | 2026-05-22 | 정산-only payslip 분기 코드 ready |
| **B-hive-hanjinwoo-rrn** | 한진우 주민번호 별도 보안 채널 수령 + `complete_onboarding(national_id)`. 4대보험 신고 전 필수 | 2026-05-22 | D-hive-18 |
| **B-frame-axev-resolution-ktx** | 강태훈 임원 보수 axev 이사회 결의서 등록 (`frame.axev.internal_resolution`) + award.resolution_id backfill | 2026-05-22 | 감사 추적 |
| **B-hive-simplified-tax-import** | 국세청 2026 간이세액표 정확 import. 현재 placeholder 근사식 + 강태훈/한진우 ground truth row 만 정확 | 2026-05-22 | D-hive-21. 다른 직원 임금 시점에 발견 risk |
| **B-hive-reported-income-axev** | axev 보수월액 신고치 확정. 현재 4,186,222 (연금) / 4,022,567 (건강) 추정 → 실 4대보험 신고서 cross-check | 2026-05-22 | D-hive-21 |
| **B-hive-golden-ci** | tests/payroll/golden_axec_2026_04.json 자동 CI 가동 (현재 수동 검증만). 산식 회귀 방지 | 2026-05-22 | D-hive-21 |
| **B-hive-phase4-wage-tax** | 원천세 자동 신고 자료 + 4대보험 EDI + 퇴직금 + 연말정산 + 연장/야간/휴일 + 연차수당 | 2026-05-22 | Phase 4 scope |
| **B-axelabs-ai-live** | `axelabs.ai` 도메인 라이브 배포 — Cloudflare Tunnel DNS (apex + www) + cloudflared ingress + `docker compose up -d --build`. `/Users/axe/axelabs/` 의 Next.js standalone 컨테이너 (host:3900). 회사 홈 + `/ui` 쇼케이스 동시 노출 | 2026-05-22 | docs.axelabs.ai 와 동일 패턴. `/Users/axe/axelabs/DEPLOY.md` 참고 |
| **B-axe-ui-blueprint-migrate** | Blueprint 가 `@axe/ui` 채택 — `pnpm add git+ssh://...axelabs#v0.1.0` + `transpilePackages: ["@axe/ui"]` + globals.css 의 토큰 import 로 교체 + Fontshare `<link>` 정리. 기존 globals.css 와 `@axe/ui` 토큰의 시각 차이 회귀 점검 | 2026-05-22 | B-axelabs-ai-live 선행 권장 (production tag 가 있어야 핀 가능). 첫 외부 소비자 검증 |
| **B-axe-ui-v0.1-tag** | axelabs 레포에 `v0.1.0` git tag — 외부 소비자들이 핀할 stable 버전 시작점. tag 직전 build/typecheck 통과 + axelabs.ai 라이브 확인 | 2026-05-22 | B-axelabs-ai-live 후 |
| **B-axe-ship-update-hook** ✅ | **DONE 2026-06-03** (axe-cli `aa43d4a`): `cmd_ship` post-deploy hook — updates.mdx Ship Log 자동 stub(멱등, backtick-hash) + `--no-update-hook`. 전체 guarded(ship 안 깸), 배포 성공 후만. **단 backlog 자동 promote 는 surfacing-only**(🔧 항목 제안 출력) — markdown 행 자동이동은 fragile 해 제외, true 자동화는 [B-axe-backlog-promote-cli](#-신규-분류-안-됨) 선행. [D-docs-updates-1](/ops/decisions) Phase 2 | 2026-05-22 | done: Ship Log 자동화 |
| **B-axe-cli-git-track** ✅ | **DONE 2026-06-03**: `~/.axe/bin` 제자리 git-init(코드-only, 비밀은 ~/.axe 루트라 범위 밖) + 비공개 remote `github.com/axelabs-ai/axe-cli`(genesis `ad91ea0`, .bak·pycache gitignore). 이후 일반 git flow. (결정: 별도 repo 화 — `~/.axe` 통째 git-init 은 tokens.json·vault/.env 밀집으로 기각.) | 2026-05-23 | done: axe-cli repo |
| **B-axe-backlog-promote-cli** 🆕 | `axe backlog promote <id>` — backlog.mdx 의 🔧/📋 항목을 ✅ Done 섹션으로 안전 이동(행 파싱 → 재배치 → 완료일·결정링크 삽입). 현재 [B-axe-ship-update-hook](#-신규-분류-안-됨) 의 promote 는 surfacing-only(후보 출력) — markdown 행 자동이동이 fragile 해서다. 이 명령이 생기면 ship hook 이 호출해 **true 자동 promote** 가능. + 본 세션이 ✅ 항목을 in-place 마킹만 하고 물리적 Done 이동은 deferred 한 것도 이 명령으로 일괄 처리 | 2026-06-03 | M3, 0.3d. B-axe-ship-update-hook 후속 |
| **B-matrix-backlog-system** 🆕 ⭐ | matrix 를 backlog/roadmap/ship-log **구조화 SSOT** 로 ([D-matrix-3](/ops/decisions), ADR `matrix/docs/adr/backlog-roadmap-system.md`). markdown 의 멀티라이터 충돌·fragile 행이동·수동 카운트 해소. **Phase 1 구현완료(미배포)**: matrix-postgres 3테이블(backlog_item/roadmap_milestone/ship_event, slug PK) + MCP 8도구(`backlog_list/create/update/transition`·`roadmap_*`·`shiplog_*`) + import 파서(206 backlog+16 ship+7 roadmap dry-run 검증), `cargo check` ✓. **잔여**: Phase 1 배포(feat/wan-monitor 와 분리 브랜치 권장)+import apply, Phase 2 의례 cutover(전 서비스 CLAUDE.md→matrix MCP, ship-hook→`shiplog_append`, B-axe-backlog-promote-cli 흡수), Phase 3 보드뷰(axelabs app)+REST+host-side gen-docs | 2026-06-03 | M3 epic, Phase 1 done. [D-matrix-3](/ops/decisions) |
| **B-axe-ui-consumer-mysrt** | mysrt 가 @axe/ui 토큰만 도입 (FastAPI+Jinja+vanilla JS, React 없음). Toss Pink 브랜드 유지 결정 → `[data-brand="mysrt"]` scope override 패턴. 토큰 이름만 통일 | 2026-05-23 | 브랜드 정책 결정 필요. 후순위 |
| **B-axe-ui-consumer-distributa** | Distributa (현재 빈 Vercel scaffold) 가 product surface 정의 후 sync-axe-ui 도입. 신규 화면 짓기 시작할 때 적용 | 2026-05-23 | product 정의 선행 |
| **B-docs-box-verify-cron** | `npm run verify:box` 의 cron 등록 (매 30분 또는 시간) — Cloudflare/외부 변화 catch. 운영자 launchd job. 실패 시 alert (e.g., known-gaps 자동 등재 또는 Slack/Teams webhook) | 2026-05-23 | Phase 20-21 의 보강. axe ship 통합으로 deploy 시점은 차단 — cron 은 *외부 요인* catch |
| **B-axe-ui-radix-bump** | @axe/ui v0.3.2 의 미해결 QA P1 11 + P2 6 fix (a11y/types/skip-link/contrast 등) → v0.3.3 patch. Phase 16 audit 보고서 참고 | 2026-05-23 | non-blocking, 다음 cycle |
| **B-docs-cf-purge-cli** | `axe cf purge <url>` CLI 신설 — Cloudflare API token 을 vault 에 등재 후 운영자가 dashboard 우회. 본 chapter 의 Cloudflare 옛 404 4시간 잔존 fix 시 운영자 dashboard 작업 강제됐던 점 해소 | 2026-05-22 | wrangler scope (`cache_purge`) 없음 확인 |
| **B-axe-secret-send-dm** | `axe secret send <ENV> --service <svc> --to <email> --dm` flag 추가 — Bitwarden Send URL 발급 + Blueprint `/api/admin/broadcast-dm` 호출까지 1 명령에 묶음. 현재 운영자가 (1) `axe secret send ...` 6 회 + (2) `curl /api/admin/broadcast-dm` 3 회 + (3) 메시지 본문 bash 합성 필요. `--dm` 가 to-email 매핑 (`taehun → taehun.kang@axellc.com`) + 메시지 템플릿 (`--template connector-onboarding`) + CRON 자동 추출까지. SSOT: [/architecture/secrets § 자동 발사](/architecture/secrets#자동-발사--apiadminbroadcast-dm) | 2026-05-23 | 본 세션에서 발견 (axe-secret-send 라이브 첫 사용). 현재 docs 의 employee-onboarding §5.2 가 the bash boilerplate. `--template` 카탈로그도 같이 등재 |
| **B-vault-org-create-automation** 🆕 | Vaultwarden organization 자체 생성 명령 부재 (client-side encryption 으로 web UI 만 가능). customer onboarding 시 운영자가 web UI 30초 수동. 영구 fix = (a) Vaultwarden API + admin token 으로 직접 호출 또는 (b) Playwright headless 자동화. Truvia 5/26 D-ops-32 = realchoice org `eac93965-...` 수동 생성 + 4 collection. 영향: 신규 customer 마다 30초 + 사람 손 의무 | 2026-05-26 | M2, 0.5d |
| **B-vault-org-cli-automation** 🆕 | bw CLI 의 organization invite/confirm 명령 부재. Truvia 5/26 우회: Vaultwarden API + data.json 의 `user_<uuid>_token_accessToken` JWT 추출 (2025.7.0 schema). customer 측 onboarding 자동화에 필수. 영구 fix = (a) custom bw helper script (axe `axe vault org-invite <email>` 신설) 또는 (b) upstream bw CLI PR. Vaultwarden REST API 사용 (`POST /api/organizations/{id}/users/invite`) | 2026-05-26 | M2, 1d |
| **B-port-conflict-preflight** 🆕 | onboard step 3 (SSH probe) 직후 step 10 (docker preflight) 이전에 **포트 충돌 사전 점검** 추가 — `ssh <host> "docker ps --format '{{.Names}}\t{{.Ports}}'"` 매트릭스 추출 → AXE platform 표준 포트 (3700/3710-3712, 3800/3810-3812, 3100-3151) 와 cross-reference. 충돌 발견 시 차단 게이트 + 운영자 알림. realchoice 14 컨테이너 사례 (trap #6). 영구 fix = `_onboard_step_port_audit` 신설 + B-realchoice-port-collision-audit 통합 | 2026-05-26 | M1, 0.3d |
| **B-frame-keychain-to-vault** 🆕 | frame docker-compose 의 `FRAME_STORAGE_HOST_DIR=/Users/axe/frame/.local` hardcoded default 영구 fix. R1 (HOME 변환) 부분 fix 적용 (wrapper 의 .env.local 에 `FRAME_STORAGE_HOST_DIR=${HOME}/frame/.local` 명시), 하지만 service repo 의 docker-compose.yml SOT 도 `${HOME}/frame/.local` default 로 변경 필요 (frame 측 PR). 동일 검토 = blueprint·hive·matrix compose 도 axe 절대경로 hardcode 잔존 여부 grep | 2026-05-26 | M1, 0.5d (frame PR) |
| **B-bw-cache-stale-autoheal** 🆕 | bw CLI 의 local data.json cached `cryptoSymmetricKey` 가 server-side patch deploy (axe.2 / axe.3 등) 후 stale 상태로 저장되어 매 unlock `[Encrypt service] MAC comparison failed` → recurring (5/22 + 5/26 두 차례 manual recovery). `bw unlock` 은 cache 무효화 X. **영구 fix 3 갈래** (자동화 작업, docs portion 은 2026-05-28 ✅): (a) `axe vault` 에 `cmd_vault_reset` 신설 — data dir 옆으로 이동 + bw config server + bw login one-shot. 운영자 1 명령. (b) `_bw_get_password` 헬퍼가 MAC fail 패턴 감지 시 자동 reset + retry 1회. 자동 self-heal. (c) `axe ship vault` 의 post-deploy hook 이 patch shape 변경 감지 시 운영자에게 "운영자 자신 macmini 의 bw 재로그인 권장" osascript 알림. 함정: ai@'s personal vault 만 ~37 items 라 fresh login → sync 시 약 30초. 본 backlog 의 (a) 가 핵심 — (b), (c) 는 부가 가드. docs 측 표준 recovery 절차 = [/ops/runbook/vault-recovery#bw-cli-data-json-cache-stale-recovery](/ops/runbook/vault-recovery) (2026-05-28 ✅). | 2026-05-26 | M1, 0.5d (자동화 잔여) |
| **B-trap-33-frame-hive-multi-issuer** 🆕 | trap #33 영구 fix — docs portion (c) ✅ 2026-05-28 ([/architecture/auth](/architecture/auth) line 147 정정 + 함정 표 row 추가). **잔여 code fix 2 갈래**: (a) **frame + hive code 에 v1 issuer 추가** — Blueprint MCP 의 `config.py:76,81` + `auth_oidc.py:153` `issuer=[v2, v1]` 패턴 mirror. `get_microsoft_issuer_v1()` helper 추가 (return `f"https://sts.windows.net/<tenant_id>/"`). 위치: `/Users/axe/frame/src/frame/mcp/http_server.py:141` + `/Users/axe/hive/src/hive/mcp/http_server.py:67`. (b) **bootstrap.sh 가 등록 시 v2 강제 + 검증** — Truvia D-day 시 3 app 모두 v1 였다 = PATCH 누락 또는 실패. bootstrap.sh 의 PATCH step 정합성 검증 + 등록 후 manifest version 검증 step 추가. | 2026-05-25 | M1, 0.7d (frame PR + hive PR + bootstrap.sh) |
| **B-customer-sovereignty-architecture** 🆕 | **Q3 milestone**. Truvia 측 architectural concern (5/25): operator vault SoT (D-ops-17) → customer-측 vault/secret SoT 으로 재 architecting. 본질 = operator 가 모든 customer secret 의 SoT 라고 주장 = customer data sovereignty 침해. **올바른 architecture**: Code SoT=Github / Image SoT=registry / Service secret + Business data + Service config SoT = customer 본인 macmini. **operator 책임 2개만** = (a) software supply (code/image push to registry) (b) 외부 노출 (DNS/tunnel ingress catch-all). axe deploy 의 vault fetch + customers.yaml 의 secret manifest 모두 제거. customer 자율 secret (openssl rand + .env + customer 자체 vault). 5/25 D-day 의 self-deploy 패턴 (Truvia 가 본인 .env + compose 자체) 가 본 architectural change 의 첫 실제 적용. customers.yaml = customer 식별 (legal_name, public_domain, tailscale_host) + onboard step (cloudflared tunnel/DNS) 만 유지. | 2026-05-25 | M2/M3 Q3, 5d |
| **B-customer-deploy-generalization-r6-volume-precreate** 🆕 | trap #19 + #23 영구 fix. docker-compose 의 external volume — (a) blueprint 6개 (app-data/workspace/claude-data/postgres-data + mcp-proxy data/config) 신규 customer 측 사전 부재 → compose up fail (trap #19), (b) hive 2개 (`hive-proxy_axe-hive-proxy-{data,config}`) 의 historical compose project prefix 정합성 문제 (trap #23) — 둘 다 본 R6 phase 에서 함께 해소. 영구 fix 2 옵션: (a) compose 의 `external:true` 제거 → compose 가 자체 volume 자동 생성 (권장 — compose self-contained, customer self-deploy 친화). (b) axe deploy pre-step 으로 `docker volume create` 자동 호출. R6 (customer-deploy-generalization 차기 phase) 으로 묶음. | 2026-05-25 | M1, 0.5d |
| **B-docs-ssot-extension-2026-05-26-newpages** 🆕 | B-docs-ssot-extension-2026-05-26 의 잔여 — 신규 페이지 2 (A1/A2) 만. A1 `/partner/macmini-existing` 신설 (기존 운영 macmini → customer 전환), A2 `/services/vaultwarden` 또는 `/architecture/vault-integration` 신설 (Timshel image + compose/Caddyfile/env 패턴 + axe.2 patch 정체 + [D-ops-37](/ops/decisions) fork build). 정정 7건 (B1-B7) 은 2026-05-28 본 세션 ✅ 완료. **A1/A2 는 5/27 D-day 후 Truvia 측 첨언 사전 받아 시작 권장** | 2026-05-26 | M2, 0.5d |
| **B-vault-collection-migration-v1** 🆕 | [D-ops-32](/ops/decisions) 의 6 collection 신설 완료 (2026-05-26) 후속 — item migration + 옛 collection cleanup. **3 단계**: (1) **운영자 personal vault → Platform — Service Secrets 이전** = `axe secret list` 의 ~37 service secrets (frame/hive/blueprint/matrix `/axe/*` + Cloudflare API + shared/* + infra/realchoice/*) 가 현재 ai@ personal vault only ⇒ bus factor 위험. organization Platform — Service Secrets 로 옮기면 soohun 도 access. `bw share` (deprecated → `bw move`) 또는 web UI. (2) **Default 의 3 items 분류**: `github PAT: ai@axellc.com` → Platform — Infrastructure (또는 rotation 후 폐기 — [B-cf-token-rotation-2026-05-25] 패턴), `axe-macmini local: {soohun,taehun}.kang` 은 각자 personal vault 가 본질 — organization 에서 제거 권장. (3) **옛 4 collection 의 item 이동 + collection 삭제**: frame-jwt-axec 의 `taehun-kang-axec-2026-05-17` + frame-jwt-operators 의 `ai-operator-2026-05-16` 검토 (D-ops-14 frame JWT 잔재) — Platform — Service Secrets 으로 옮기거나 unused 면 삭제. 빈 collection (frame-jwt-axev) 즉시 삭제 가능. Default + frame-jwt-* item-empty 화 후 collection 삭제. **위험**: axe CLI 가 name 기반이라 이동 자체는 안전, 다만 (a) item 이름 변경 금지 (`axe secret get <name>` 깨짐), (b) item 삭제는 영구 — 검토 후 진행. **`bw move <id> <orgId> <encodedCollectionIds>`** 가 personal→organization item 이전 명령. organization 내 collection 변경은 item 의 `collectionIds` 갱신 (bw edit) 으로. | 2026-05-26 | M1, 1d (운영자 검토 시간 큼) |
| **B-blueprint-settings-graph-reconnect-button** 🆕 | Blueprint `/settings` (또는 `/axe/settings` Integrations) 의 GraphToken status panel + **Reconnect 버튼** 부재 — 운영자가 token expiry / refresh 실패 진단·회복 self-service 불가. 본 세션 (2026-05-26) 함정: ai@ token 이 1.5h 전 expired + AADSTS65001 (Calendars.ReadWrite scope admin-consent 누락) 으로 refresh 침묵 실패. UI 는 "Connected as ai@axellc.com" 만 표시 — token 실제 상태 0. 운영자가 직접 `/api/graph/auth` URL 알아 방문 + admin consent 별도 trigger 모두 운영자 black-box 지식 의존. **요구 UI** (3 요소): (1) **현 상태 panel** — Connected/Disconnected/Expired/RefreshFailed status badge + `expiresAt` 카운트다운 + 마지막 refresh 시각 + 현재 grant 된 scope 목록. (2) **Reconnect 버튼** — 클릭 시 `/api/graph/auth` 로 redirect (`prompt=consent` 강제 query 추가). 옛 token row 는 fallback 으로 보존. (3) **Admin consent 검증 + 안내** — Microsoft 화면에서 "Need admin approval" 차단 시 운영자 본인 (Global Admin) 으로 sign-in 안내 또는 별 admin consent URL 직접 제공 (`https://login.microsoftonline.com/{tenant}/adminconsent?client_id={app}`). 본 세션에서 발견 (강수훈 직접 보고: "settings 에서 기본적으로 reconnect 버튼이 필요해보입니다. 흐름이 이상하지 않습니까"). | 2026-05-26 | M1, 0.5d |
| **B-blueprint-scope-change-admin-consent-runbook** 🆕 | Blueprint app 의 OAuth scope 추가 ship 시 함정 — docs portion ✅ 완료 (2026-05-28, [/architecture/auth#oauth-scope-추가-시-운영자-절차](/architecture/auth) 함정 표 row + 운영자 절차 섹션). **잔여 자동화 2 prong**: (1) **`axe ship blueprint` post-deploy hook** — `SCOPES` array 변경 감지 시 `az ad app permission admin-consent --id <client_id>` 자동 호출 (또는 prompt). (3) **Blueprint 자동 token health check** — daily cron 또는 startup probe 가 모든 GraphToken refresh 시도 + AADSTS65001 발견 시 운영자 알림 (OperatorAlert + Teams DM). | 2026-05-26 | M1, 0.5d (자동화 잔여) |

## ⏸️ Blocked (외부 차단)

| ID | 항목 | 차단 사유 | 차단 해소 조건 |
|---|---|---|---|
| _(현재 없음)_ | | | |

## ✅ Done (최근 7일, archive 대기)

| ID | 항목 | 완료일 | 결정/문서 링크 |
|---|---|---|---|
| **B-vault-axe.2-sso-mp-incomplete** ✅ | **axe.2 SSO→MP unlock 부분 fix 완전 종결 — 4명 KDF rotation 전부 완료** ([D-ops-40](/ops/decisions) Progress xiii). 옛 user 의 `user.akey` 가 PBKDF2 600k schema 로 wrap 된 게 SSO→MP unlock 실패 원인. **본질 발견 = KDF type dropdown 변경 불필요** — Master password change + ☑ "Also rotate my account's encryption key" 체크박스 만으로 akey 재wrap 충분 (ai@ 가 Phase A 로 검증, 나머지 3명 동일 패턴). 4명 (ai 5/27 → soohun → taehun 5/29 → **jinwoo 6/4**) 전부 SSO→MP unlock 정상 확인. DB: ai 는 Argon2id (Phase B 까지), soohun/taehun/jinwoo 는 PBKDF2 유지 (akey 재wrap 만 — kdf_type 안 바뀌어도 fix 동작). jinwoo last_login 5/23→6/4 점프 = 완료 신호 + 운영자 구두 확인. realchoice 측 영향 없음 (axe.2 후 신규 가입 = 새 schema). 운영자 안내 = Teams broadcast 2회 ([operator-broadcast](/ops/runbook/operator-broadcast)) + [/onboard/vault-setup](/onboard/vault-setup) playbook. **D-ops-40 전체 작업 종결** (build pipeline + axe.3 patches + deploy + 검증 3건 + 정책 layer + 4명 rotation). | 2026-06-04 | [D-ops-40](/ops/decisions) Progress xiii |
| **B-axe-cli-P0** ✅ | AXE CLI P0 골격 GREEN — stdlib 단일파일 `~/axe-cli/axe` (`login`/`logout`/`whoami` + macOS Keychain + `AXE_TOKEN` env fallback + MCP streamable-HTTP 클라이언트 + `--local` Host-header 자동첨부). frame HS256 부트스트랩 토큰(`frame mcp-token`)으로 `axe frame tools` → **54 tools GREEN 검증**. "커넥터 0 · 토큰 1회" 증명. repo git-tracked ([B-axe-cli-git-track](/ops/backlog)). 인터랙티브 인증 후속 = [B-axe-idp-1](/ops/backlog) (Blueprint OIDC loopback PKCE). | 2026-06-03 | [D-axe-cli-1](/ops/decisions) |
| **B-index-epic1-judgment-layer** ✅ ⭐ | **artifact-first judgment layer (Epic 1) — 증거층↔판단층 결합**. 휴면 artifact store(39 fact)→relational 23 deal 결합: 모든 투자판단 fact 를 일급 typed+cited+audited artifact 로 승격 (kind assumption·calibration·comp·base_rate, **migration 0** generic store 재사용, 링크=일급 citation index_field+artifact_ref relation, side-bridge table 아님). **23/23 deal → 357 fact**, 0 orphan judgment value, additive-only 3중 증명(event propose/confirm·relational updated_at 미전진·validate-seeds Δ0), 48/48 test, sqlx clean. 2-wave supervised — adversarial gate 가 wave1 61% 미완 적발 → 직접 +4 → wave2 5딜 author + 6 rival module→1 `backfill.rs` 통합. index `1c707e1`. | 2026-06-03 | [D-index-45](/ops/decisions) |
| **B-index M7 build cohort** (skeleton·azure-app·docker-compose·shared/artifact/financial migration·dsl-parser·topo-evaluator·mcp-checklist·schemas-endpoint·phase0-mcp-tools·3deal-seed·3deal-irr-validation·driver-period-refactor — 14) | index 서비스 live: **23 deals**·26 fund_investment·16 typed schema·artifact store(RLS)·MCP tools·DSL+topo evaluator. (phase0 4-tool 은 `propose_deal_closure` 로 통합 [D-index-13]; shared schema 는 public = Phase-0 설계.) validate-seeds A1 PASS Δ0. | 2026-05-31 | [D-index-2](/ops/decisions)~18 (triage 검증) |
| **B-pmc-postmortem-2track** | pmc skill 2-track 분리 구현 (ic: postmortem_stub/reminder · pmc: fill_interactive/render + cadence ref). ⚠ launchd reminder install 은 operator 잔여. | 2026-05-31 | [D-index-12](/ops/decisions) |
| **B-index-sqlx-cache-guard** | `.githooks/pre-commit` + `scripts/check-sqlx-cache.sh` (`cargo sqlx prepare --check`), `core.hooksPath=.githooks` 활성화 (2026-05-31). | 2026-05-31 | [D-index-32](/ops/decisions)~33 |
| **B-cortex-visibility-phase1-sync-filter** ✅ | [D-cortex-9](/ops/decisions) Phase 1 — Google contactGroup(라벨) whitelist/blacklist sync 유입 필터 (`Personal`/`HPE` 라벨 연락처 유입 차단). `passes_label_filter` + `list_contact_group_names`(id→name 맵 1회 로드) + 맵 로드 실패 시 owner cycle fail-safe skip. 민감정보 미유입의 가장 강한 보장 | 2026-05-31 | env `CORTEX_SYNC_GROUP_BLACKLIST`(기본 `Personal,HPE`)/`CORTEX_SYNC_GROUP_WHITELIST` + `sync_google_now` 의 `skipped_by_label` stat. 코드 = cortex working tree (미commit), docs 반영 ([services/cortex](/services/cortex#visibility--private-partition-d-cortex-9)). `axe ship cortex` 시 commit/deploy |
| **B-frame-hive-backup-cron** ✅ | axe-backup 스크립트에 hive-postgres pg_dumpall 블록 실 추가 (D-hive-backup 결정 후 미실행) (stale-done: 감사+반증검증 통과) | 2026-05-30 | wf 감사 wf_f1573f47 (misc (B-) |
| **B-hive-template-axev** ✅ | axev payslip_email template clone + customize + activate (D-hive-25 customize 강제) (stale-done: 감사+반증검증 통과) | 2026-05-30 | wf 감사 wf_f1573f47 (hive) |
| **B-bp-para-provenance-fields** ✅ | Blueprint Workspace에 sourceWorkspaceId/sourceArtifactPath/copiedAt 3필드 — PARA dispatch copy-with-provenance (stale-done: 감사+반증검증 통과) | 2026-05-30 | wf 감사 wf_f1573f47 (blueprin) |
| **B-axe-ui-consumer-cortex** ✅ | Cortex 가 @axe/ui 도입 — design token 채택 (Tailwind v3→v4 마이그 + sync-axe-ui + ★3→★4) (stale-done: 감사+반증검증 통과) | 2026-05-30 | wf 감사 wf_f1573f47 (cortex) |
| **B-frame-fund-ksme-seed** ✅ | `shared.account_template` 에 `fund_ksme` standard 48행 이미 seed | 2026-05-30 | stale-done 감사 (DB 확인) |
| **B-frame-mcp-register-entity-tool** ✅ | MCP `register_entity`+`list_sub_entities` 이미 `@mcp.tool()` (server.py:1470,1505) | 2026-05-30 | stale-done 감사 (코드) |
| **B-frame-fund-commitment-ledger** ✅ | `commitment_ledger`+`lp_master` 전 entity 스키마에 이미 존재 (schema 신설; population 별도) | 2026-05-30 | stale-done 감사 (DB) |
| **B-frame-mcp-http-wrap** ✅ | `http_server.py` 1012줄 HTTP MCP 가동 중 (frame DECISIONS.md:170 'M1 only stdio' stale 정정 권장) | 2026-05-30 | stale-done 감사 (코드) |
| **B-bp-onboard-claude-code** ✅ | `/onboard/claude-code` 페이지 5 컴포넌트 이미 구현 (Phase B) | 2026-05-30 | stale-done 감사 (코드) |
| **B-axe-secret-totp-cli** ✅ | `axe secret get <name> --field totp` 지원됨 (CLI --field choices 'totp'; 전용 subcommand 만 미신설) | 2026-05-30 | stale-done 감사 (CLI) |
| **B-frame-entity-legal-name-i18n** ✅ | frame DB shared.entity legal_name 정정 — **전제 정정**: 사업자등록증 기준 법인명이 영문 (`axec`="AXE Corporation", `axev`="AXE Ventures") 이라 기존 "영문→한글" 전제 + customers.yaml SoT 의 한글값("액스코퍼레이션 주식회사" 등)이 오기였음. frame-postgres 2행 UPDATE (+ per-entity audit_log) + customers.yaml(entity_meta·axe.legal_name) 정정. **잔여**: hive shared.entity 가 동일 한글 stale → 운영자 확인 후 동일 정정 예정 (payroll 시스템) | 2026-05-30 | frame-postgres + customers.yaml |
| **B-index-entry-date-backfill** ✅ | 9 deal 전부 entry_date 기입 (executed=paid_date / planned·passed=가안), `entry_basis=assumed` 0건 ([D-index-28](/ops/decisions) 후속) | 2026-05-29 | index commit `f650bec`+`e5ac7a6` |
| **B-index-deprecate-sump-irr** ✅ | Σp·IRR 폐기 → IRR(E[CF]) 단일 canonical (사용자 승인). `weighted_irr_*` 제거 + `#[deprecated]` + 9 baseline·html·xlsx 전환 | 2026-05-29 | [D-index-32](/ops/decisions), index commit `3b2f543` |
| **B-index-docs-irr-ecf-restate** ✅ | docs IRR 을 canonical E[CF] 기준 재기재 — 8-deal 랭킹 확정 (tail flip Sendy 11.7 > Novachips 9.2) + per-deal 구→신 표 + seed 주석 | 2026-05-29 | [D-index-34](/ops/decisions), index commit `537c04e` |
| **B-index-instrument-adjusted-irr** ✅ | won't-do — instrument 효과가 exit_matrix leaf recovery 에 이미 반영 (flat discount table 은 이중계상). discount table 미구현 + Novachips `irr_instrument_adjusted` 폐기 + seed.rs 가드 | 2026-05-29 | [D-index-33](/ops/decisions), index commit `74e1eb4` |
| **B-blueprint-mcp-send-mail** ✅ | Blueprint MCP 범용 이메일 발송 tool `send_mail` ([D-bp-mcp-mail-1](/ops/decisions)). `create_event` 형제 — 신규 route `POST /api/internal/mail` (caller delegated `Mail.Send` self 발송 / admin app-only send-as) + Python tool `mail.py` + append-only `MailSendLog` audit (migration `20260529120000_add_mail_send_log`). params: to/subject/body(html\|text)/cc/bcc/attachments(base64)/save_to_sent_items/as_user_email/dry_run. 에러: `send_as_forbidden`/`recipient_invalid`/`mail_send_not_consented`/`graph_error`. typecheck 0 errors. **⚠️ Azure 선행조건 (운영자 1회)**: send-as 경로는 Next.js app (`2b222356-...`) 에 Application `Mail.Send` + admin consent 필요 — self 발송은 delegated `Mail.Send` 이미 보유라 불필요. 절차 = [/architecture/auth § app-only Application permission](/architecture/auth). docs (blueprint/auth/mcp-server-checklist/decisions) 동시 갱신. | 2026-05-29 | branch `feat/bp-mcp-send-mail`, [services/blueprint](/services/blueprint) |
| **B-index-infinity-3step** ✅ | Prj_Infinity(INEX) 축적 — 3-step surface→재수행→비교 ([D-index-23](/ops/decisions)). 사용자 "기존 데이터 적재 테스트 → 신규 IC 재수행 → 두개 비교로 전 건들과 같게". **Step1**: v8 FINAL(irr_locked) surface 적재 → index 13.8%/1.70x 정확 재현 (ev_bridge·net debt 0 보통주·exit-diluted 0.0724% — surface 모범). **Step2 재수행**: 외부 research — 실명계좌 base-rate near-zero(2021 특금법 후 원화마켓 신규 0건, P&lt;10%) / 코빗 ceiling 1,000-1,400억 / Gopax·Binance license-shell M&A 선례 / 보통주 distress recovery 0~20%. 모달 exit 를 won-market rerating 아닌 SI shell M&A breakeven 으로 reframe + 보통주 wipeout leg(18% @ 0.12x). **Step3 비교**: calibrated −8.3%/0.82x. **~22pp gap + sign-flip**. 핵심 = 성숙·정직한 v8(hurdle 미달 공개)도 핵심 base-rate 를 mgmt optimism 에 anchor + 보통주 wipeout 누락 → 역전. proceeds 메커니즘 불변(analytical gap only). **canonical 결정** ([D-index-24](/ops/decisions)): executed/Closed deal 이므로 IC-approved 13.8% 가 canonical (decision-time 기록 보존), −8.3% 는 `infinity_recalibrated.yaml` retrospective overlay. 8-deal canonical: Infinity 13.8 (Hancom~Novachips 사이). validate-model 0 errors. IC memo v9 = OneDrive. | 2026-05-29 | index commit `c0dcd9a` + canonical swap |
| **B-index-proceeds-bridge-hardening** ✅ | proceeds 산정 강화 — EV→EqV(net debt) bridge + exit-dilution 명시·강제 ([D-index-22](/ops/decisions)). 사용자 audit "모두 EV=EqV+Net Debt + 투자 후 dilution 고려됐나 체크" 의 답. **발견**: 7-deal proceeds 비일관 — net-debt bridge 는 Canopy 만 명시(EV 797−netdebt 300=EqV 498), Sendy(v2)·Iippo 는 stake×EV 직접, pre-IPO 3+Sentry 는 equity multiple(N/A); dilution 은 Iippo·Sentry entry F/D flat. **결정** = [D-index-20](/ops/decisions) IRR determinism 을 proceeds 로 확장: `proceeds_basis` enum (ev_bridge|equity_value|mom|legacy_ev) + ev_bridge non-writedown leaf 는 stake×(EV−net debt) 가 axe_proceeds 와 ±2% 일치해야 — seed load **hard-reject** + validate Check 7 Error 2중 강제 (negative test 거부 확인: 10%×2,225억 ≠ 날조 300억). migration 0005. **Sendy v3**: ev_bridge, net debt 0 (asset-light + 자금니즈 equity 충족 + 차입 증거 0 → 보수적, **날조 안 함**) → proceeds·IRR 불변 6.47% 이나 EV≠EqV 누락 class 영구 차단. 7-deal: Sendy ev_bridge PASS / Sentry equity_value / 3 pre-IPO mom / Iippo·Canopy legacy_ev WARN — 0 errors. 잔여 = [B-index-proceeds-bridge-retrofit](/ops/backlog). | 2026-05-29 | index commit `ca714b7` |
| **B-index-sendy-current-practice-rewrite** ✅ | 센디(Sendy) IC v2 재작성 — 현 practice 재calibration ([D-index-21](/ops/decisions)). 사용자 redirect "그냥 적재 말고 ic memo 를 현 practice 수준으로 새로 써라 (당시 방법론 열위)". [D-index-19](/ops/decisions) (surface→calibrated) 의 종착 = **memo 방법론 자체 재작성**. **3-tier IRR**: v1 md 31%/22.8%(fabricated) → v1 Excel 92.4%(math-correct, 낙관 input) → **v2 현 practice 6.5% ⭐ canonical**. **v1 5결함 교정**: IRR override(D-index-20 차단) / wipeout leg 부재(Downside +31.6% gain → 손실 시나리오 없음) → genuine 18% wipeout(부릉 1/6 recovery) / sendyX 66x 미검증 → base-rate haircut(-93%) / Exit 5x flat → segment-weighted(freight 1~1.5x + SaaS 4~5x, WiseTech-E2open 3.5x) / instrument 분석 부재. 외부 anchor: Convoy $3.8B→0 + 부릉 1/6 distress → wipeout 15~25%, 한국 Series C→IPO 예외(TMAP 교훈). 결과 4-scenario E[IRR] 6.5% / E[MoM] 1.51x / Sharpe-like -0.06. 7-deal 랭킹 Sendy 6.5 최하위로 정정. 산출물: OneDrive `ic/memo/v2_axe_current_practice_260529.md` + seed v2(version:2). validate-model 7/7 PASS. | 2026-05-29 | index commit `b77a236` |
| **B-index-sendy-passed-deal** ✅ | 센디(Sendy) 축적 — IRR override 오류 flagship + 첫 declined deal ([D-index-20](/ops/decisions)). 출처 `1_Project/Pipeline/Sendy/`. **index 존재 이유 결정적 증거**: exit_matrix/v1.yaml 의 `corrected: 35%` manual override (계산값 95.7% 를 근거없이 변경) — index 는 IRR 을 proceeds 에서 deterministic 계산 → override 물리적 불가, EV-derived seed → 자동 교정 (Base 95.7/Downside 31.6/Upside 146.6/weighted 92.43, Excel 일치). **deal.stage 'Passed' 추가** (migration 0004) — declined deal first-class tracking. 7-deal portfolio Closed 3 / IC 3 / Passed 1. PASS 사유 구조+타이밍 (quality 아님). honesty: screening-grade model (sendyX 66x 미검증). validate-model 7/7 PASS. | 2026-05-29 | index commit `9263179` |
| **B-index-3-preipo-deals** ✅ | 3 pre-IPO deal (스타넥스/한컴인스페이스/노바칩스) calibrated 검토 본 축적 ([D-index-19](/ops/decisions)). 출처 `_comparative_20260528_preIPO/` 13-agent 비교 IC 메모. surface IRR(19.6/58.5/-1.5) → calibrated(36.4/22.4/7.45) 재calibration 본을 index 에 typed fact 로 저장 (xlsx surface cell 아님). pre-IPO scenario-tree 모델 (scenario=단일 outcome), `parse_timing_years` 소수 연도 확장 + timing CHECK 완화 migration. 6-deal portfolio 랭킹 검증 + validate-model 6/6 PASS. **신규 backlog 발견**: [B-index-instrument-adjusted-irr](/ops/backlog) (보통주 vs RCPS 8-15pp discount systematic 적용). | 2026-05-29 | index commit `e130a69` |
| **B-cortex-production-live** ✅ | Cortex (Rust + axum + sqlx, 첫 비-Python MCP 서비스) 를 claude.ai connector 까지 production live. 폐기 (file-based recall → `.legacy.20260526/`) → Rust 재출발 (19 task) → 5 secret vault push → Entra app (az cli) + Google OAuth Web client (Cloud Console, 신규 프로젝트 cortex-497605) → Cloudflare ingress (Dashboard remote-managed, CF API PUT) → docker compose (postgres+blue+green+proxy) + 2 migration → claude.ai connector (client_id+secret) → Microsoft OAuth → **12 tools 노출 + whoami + connect_google 검증**. 시행착오 7 함정 ([known-gaps Cortex](/ops/known-gaps)) 전부 해소: DB password URL 파싱 (PgConnectOptions) / env_file 따옴표 / RFC 9728 resource-level path / RFC 8414 path-insertion (→ Microsoft-direct) / claude.ai client credential / ASCII-only property key (`메모`→`memo`) / Cloudflare remote-managed tunnel. **B-cortex-mcp-crash-loop (2026-05-27 등재) 해소** — 원인은 env_file 따옴표 + DB password URL + stale Docker image 복합. | 2026-05-28 | [D-cortex-1..8](/ops/decisions), [services/cortex](/services/cortex), cortex commits `c65b934..dfa9330` |
| **B-cortex-dockerfile-healthcheck** ✅ | blue/green 컨테이너 영구 `unhealthy` 해소. 원인: healthcheck CMD 가 `python -c urllib...` 인데 Rust/Debian-slim 이미지엔 python·curl·wget 전무 (`/usr/local/bin/cortex` 바이너리만). 트래픽 무해 (Caddy alias routing 이 health-gate 안 함) 했으나 blue/green swap 의 healthy gate 잠복 위험. **fix = binary self-probe**: `cortex healthcheck` 서브커맨드 (GET `127.0.0.1:$CORTEX_MCP_PORT/healthz`, 2xx exit 0) + compose test `["CMD","/usr/local/bin/cortex","healthcheck"]` (green 은 `<<: *cortex-mcp-blue` 머지 상속). Settings::load 전 short-circuit → DB 자격증명 독립 (false unhealthy 방지). **index 의 python→curl 과 다른 선택** — 패키지 추가 없이 기존 바이너리 재사용 (minimal-base 정합). 검증: rebuild 후 blue+green `(healthy)` + 외부 200/401 유지. index 도 동일 패턴 정렬 권장 (curl 의존 제거, 우선순위 낮음). | 2026-05-28 | cortex commit `b8d3aa0` |
| **B-cortex-private-partition-phase0** ✅ | [D-cortex-9](/ops/decisions) Phase 0 — artifact `visibility` tier (shared\|private) 도입. soohun.kang 2026-05-28 "Private Partition" 요청. migration 0003 (`artifact.visibility` DEFAULT shared + CHECK + index, 기존 3,250행 shared) + register_person `visibility`(private→Google push skip)·classify_person·update_person(re-tag) 에 `visibility`+`skip_audit_payload` + list_persons `visibility`/`exclude_classification_key`/`_value` 필터 (QueryBuilder) + get_person visibility 노출. 신규 schema key 전부 ASCII. 검증: build + migration + blue/green healthy + 필터 5-assertion rolled-back SQL 테스트 (zero residue) + 외부 200/401. **잔여(auth)**: claude.ai tools/list 12 + register_person(private) 실 round-trip 스모크. | 2026-05-28 | [D-cortex-9](/ops/decisions), [services/cortex](/services/cortex#visibility--private-partition-d-cortex-9), cortex commit `f8cad8c` |
| **B-blueprint-agent-sdk-integration** ✅ | [D-index-17](/ops/decisions) Phase 2 — Blueprint Agent SDK 가 index MCP 의 skill 을 fetch 해 local cache sync. `scripts/sync-index-skills.sh` (index-skill-sync.py wrapper) + `launchd/ai.axe.index-skill-sync.plist` (10분 주기, RunAtLoad=true). drift 감지 시 `/tmp/blueprint-skills-drift.log` 에 기록. cache target = `.claude/skills-cache/{ic,ingest,pmc}/`. **검증**: 1차 sync 3 skill / 61 file added (ic + ingest + 신규 pmc 자동 발견), 2차 sync 61 unchanged (cache hit). 운영자가 `launchctl load` 시 자동 동작. D-index-17 overlap 정책: 현재 SoT = `.claude/skills/{ic,ingest}`, skills-cache = 검증 사본 (drift 감지). sunset 후 cache 가 SoT. | 2026-05-28 | blueprint commit `579a0fa1` |
| **B-pmc-skill-skeleton** ✅ | [D-index-12](/ops/decisions) — Post-Money Care skill 신규 scaffold (Background Agent worktree 에서 진행). 30 files / 1,906 LoC: SKILL.md (213 line) + 8 agents (data-fetcher / kpi-extractor / risk-alerter / valuation-updater / exit-signal-analyzer / board-pack-drafter / lp-comm-drafter / index-payload-composer, avg ~93 line) + 5 references (kpi-catalog [portfolio-management copy] / ir-lifecycle [investor-relations copy] / postmortem-cadence symlink to ic SoT / risk-kind-frozen [5 enum 박제] / trigger-tiers [SCHEDULED/EVENT/MANUAL]) + 4 Python stubs (render_postmortem / postmortem_fill_interactive / quarterly_close / event_trigger) + 11 sub-dir `.gitkeep` (runtime output 구조 박제). Phase 0 = scaffold only, Phase 1 = 첫 quarterly cycle 실행. **검증**: index MCP list_skills 가 자동 발견 (ic + ingest + **pmc**), Blueprint sync hook 도 자동 fetch. | 2026-05-28 | index commit `2a74ef0` |
| **B-index-3fs-bs-cf-completion** ✅ | [D-index-18](/ops/decisions) Gap 2 마무리 — Phase 0 working capital + simplified debt/ppe model 로 BS 12 line + CF 7 line 모두 derive. compute_3fs 가 IS-only → full 3FS. **BS**: ar=rev×dso_days/365, inv=cogs×inv_days/365, ap=cogs×dpo_days/365, ppe_net=cum_capex, equity=init+Σni, cash=plug (defaults 60/30/45 days, equity_init 1억). **CF** (indirect): ni+dep−Δwc−capex−debt_rp. xlsx 4→6 sheets, HTML 7→9 sections. **검증** Iippo Y1: total_assets = L+E = 14.4M+209.5M = 223.9M ✅ balanced. 4 (deal×scenario) compute_3fs persist 성공 (217+217+155+155 rows). 4 standalone HTML 모두 9 sections, 브라우저 즉시 view. Phase 1 = depreciation schedule + debt amortization + intangibles + deferred tax. | 2026-05-28 | commit `8997e28` |
| **B-index-xlsx-roundtrip** ✅ | LP 가 수정해서 돌려보낸 xlsx 의 변경 검증 + DB 반영. **16번째 MCP tool** `import_xlsx(file_path, deal_code, scenario, apply=false)`. calamine 0.26 crate (read), Assumptions sheet parse. Input drivers 만 비교 (derived는 formula 재계산이라 round-trip 비교 대상 아님). **effective_db_value** semantic: period > 0 에 값 없으면 period 0 fallback (xlsx carry-forward visualization 과 동형). diff kinds: added/changed/removed/unchanged. apply=true 시 financial_driver_value UPSERT, removed 는 보존 (round-trip safety). **검증**: 무수정 round-trip 49 unchanged ✅ byte-equivalent, 1 cell 수정 (0.02→0.05) → 정확히 1 changed 감지 ✅, apply=true → DB UPSERT 1 row ✅. LP 양방향 흐름 완성. | 2026-05-28 | commit `6aa2680` |
| **B-blueprint-skill-mcp-client** ✅ | [D-index-17](/ops/decisions) Phase 2 — Blueprint Claude Agent SDK 의 filesystem `.claude/skills/` 직접 의존 제거 reference impl. `bin/index-skill-sync.py` (~297 line, Python stdlib only, no deps) — index MCP 의 `list_skills()` + `get_skill_resource()` 호출 → local cache sync. **Dual transport**: HTTP (production, Entra ID bearer) + CLI fallback (local-dev). **sha256 cache invalidation** — server sha256 vs local file sha256 비교, drift 감지 시 자동 update. **Conditional recursive traversal** — `has_{references,scripts,tests,agents}` 플래그 기반 sub-dir 만 fetch (scripts/_oneoff/ 같은 nested 도 처리). `--diff` mode (dry-run) + `--skill` 단일 필터. **검증**: 1차 sync 43 files added (ic 39 + ingest 4) + 모든 sha256 verified + 2차 sync 43 unchanged + drift simulation (`echo >> SKILL.md`) → 'updated' 감지 + restore 1 updated. `.manifest.json` 으로 audit trail. **다음**: Blueprint Agent SDK 의 skill loader 에 본 cache dir 인식 + cron 등록 → [D-index-17](/ops/decisions) sunset 기준 (b) 충족. | 2026-05-28 | commit `8b6f05d` |
| **B-index-lp-html** ✅ | 사용자 결정 PDF 말고 native HTML 로 LP dashboard. 신규 `src/html.rs` (~360 line) + **15번째 MCP tool** `export_lp_html(deal_code, scenario, out_dir?)` — 단일 self-contained HTML5 (inline CSS, 외부 fetch 0). 7 sections: Reproducibility / IRR Summary metric cards / Fund Investments / Income Statement (with derivation rules) / Exit Matrix (joint_probability) / Assumptions / Audit Trail. Korean font stack (Apple SD Gothic Neo / Pretendard / Noto Sans KR), `@media print` 으로 LP 브라우저 PDF 출력 가능, semantic HTML5 (a11y), color-coded (양수 green / 음수 red), sticky table headers. **export_lp_bundle v2**: index.html + xlsx + README.md (cover.md 폐기, index.html zip 첫 entry — LP 가 Finder 에서 가장 먼저 봄). 검증: Iippo base HTML 20,250 bytes, byte-deterministic (2회 sha 동일 `70096195...`), 3 deal × 2 scenario 성공, regression 유지. **LP 흐름 update**: bundle.zip 첨부 → 풀어서 index.html 더블클릭 → 브라우저 dashboard + xlsx cell audit. | 2026-05-28 | commit `eb66fab` |
| **B-index-lp-bundle** ✅ | Gap 3 마무리 layer — LP 가 1 첨부로 받는 zip + byte-deterministic. **14번째 MCP tool** `export_lp_bundle(deal_code, scenario, out_dir?)` → `{deal}-{scenario}-{sha[:8]}-bundle.zip` (xlsx + cover.md + README.md). `src/xlsx.rs` 확장 (~150 line): build_cover_markdown (IRR table + Fund table + reproducibility lock + Phase 0 한계 박제), build_readme_markdown (LP 안내문), build_bundle_zip (1980-01-01 epoch deterministic). **Determinism fix 3종** ([D-index-4](/ops/decisions) lock 강화): (a) xlsx DocProperties.set_creation_datetime(epoch) + set_author "AXE Labs index", (b) cover.md `Generated: <timestamp>` 제거 → inputs_hash[:16] 로 대체, (c) zip last_modified_time(epoch). 검증: 2회 export → xlsx sha + bundle sha 모두 동일 (byte-equivalent). Iippo base bundle 13,302 bytes. 운영 흐름: 전 xlsx 첨부 → 후 zip 1개 (cover + README + xlsx). | 2026-05-28 | commit `d33e8de` |
| **B-index-lp-deliverable-export** ✅ | Gap 3 — LP 전달용 xlsx export 완성 ([D-index-18](/ops/decisions) chain 종결). `rust_xlsxwriter 0.95` Rust 네이티브 crate. 신규 src/xlsx.rs (~280 line) + **13번째 MCP tool** `export_lp_model(deal_code, scenario, out_dir?)`. 4-sheet 결정론적 xlsx: (1) **Assumptions** driver_value 매트릭스 + cover (inputs_hash 포함), (2) **Income Statement** 12 line × 7 period + footer derivation rules, (3) **Exit Matrix** leaf-level (joint_probability 는 Excel formula `=E*B`, audit trail), (4) **IRR Summary** per-fund + weighted metrics + reproducibility footer. 검증: Iippo base 11,894 bytes "Microsoft Excel 2007+", **byte-equivalent reproducibility** (같은 DB → 같은 sha256), 3 deal × 4 scenario 전부 export 성공. **운영 흐름**: `export_lp_model Iippo base` → `/tmp/index-lp/Iippo-base-{sha[:8]}.xlsx` → 운영자가 LP 에 첨부 → LP가 Excel 에서 cell formula audit + 1년 후 재현 가능. Phase 1 잔여 = xlsx round-trip (calamine read → DB diff sha256 verify, [B-index-xlsx-roundtrip](/ops/backlog)) + BS/CF 완성 ([B-index-3fs-bs-cf-completion](/ops/backlog)) + PDF cover bundle. | 2026-05-28 | commit `425a758` |
| **B-index-3fs-typed-schema** ✅ | Gap 2 — driver_value 위 typed Income Statement / Balance Sheet / Cash Flow line items 도입. migration 20260528000002 `financial_statement_line` 테이블 (model×scenario×statement×line_code×period UNIQUE). **신규 12번째 MCP tool** `compute_3fs(deal_code, scenario, persist=false)` — driver_value lookup (period-0 fallback + base inheritance) → IS 12 line 재구성 (cogs = revenue×(1-gross_margin), opex_total = Σopex, ebit fallback, tax_expense = max(0, pretax × tax_rate), net_income). 검증 Iippo base: 12 line × 7 period = **84 cells persisted**, net_income Y1=1.10억 → Y7=17.15억 (정확히 pretax × 0.78). **Frozen enum 신설** ([D-index-15](/ops/decisions)): statement 3 (income_statement / balance_sheet / cash_flow) + is_line_code 12. BS 12 line + CF 7 line 은 placeholder (Phase 1 = working capital + debt schedule 추가 driver 도입 후 완성). /index/schemas 15 → 16 (`index.financial_statement_line@1.0` active). 회귀: validate-model 27/27 + IRR 3 deal ±1pp 유지. 다음 = Gap 3 LP xlsx export. | 2026-05-28 | commit `9ac0c68` |
| **B-index-compute-full-model** ✅ | Gap 1 closure — DSL evaluator DB 통합 (사용자 질문 "Excel model → DB화 best practice" 의 첫 gap). DSL evaluator 는 이미 구현돼 있었으나 financial_driver 와 financial_driver_value table 과 연결 안 됨. **신규 11번째 MCP tool**: `compute_full_model(deal_code, scenario, persist?)` — DB load → scenario inheritance (base 폴백) → base_revenue_period0 → revenue[-1] sentinel → `dsl::evaluator::evaluate(horizon)` → derived 결과 매트릭스 + inputs_hash + (persist=true 시 financial_driver_value UPSERT). **evaluator 개선 2건**: (a) topo_order self-edge skip (revenue[y-1] lag, A7 check_driver_dag 와 동일 정책), (b) lookup_value input period 0 fallback (Excel "constant input row" 패턴, derived 는 strict). 검증: Iippo base 8 period × 2 derived = 16 cells persist → validate-model scenario_coverage **46% → 77%** 자동 상승, IRR ±1pp 회귀 유지. Iippo mgmt 시나리오 inheritance: base 13 + mgmt 11 override = 14 effective inputs, hash 분리 (base 와 다른 inputs_hash). **발견된 Y-suffix anti-pattern → [D-index-18](/ops/decisions) 신규**: `revenue_growth_y1..y7` + 단일 formula 결합 시 period 7 에서 revenue 1.2 quadrillion 원 비현실 compounding. Refactor 잔여 = [B-index-driver-period-indexed-refactor](/ops/backlog). | 2026-05-28 | commit `9df7f71` |
| **B-index-skill-mcp-discovery** ✅ | [D-index-17](/ops/decisions) Phase 2 entry point — index MCP 가 ic + ingest skill 의 canonical SoT (filesystem) 위에 discovery layer 추가. 2 신규 tool 도입 (MCP 총 10): (9) `list_skills()` — `/Users/axe/index/skills/` 의 모든 skill 의 SKILL.md frontmatter (`name` / `description` / `allowed-tools` / `required_model`) + sha256 + sub-dir 존재 (references / scripts / tests / agents); (10) `get_skill_resource(skill, path?)` — path 미지정 시 SKILL.md, file = content + sha256, directory = entries[] listing. **Security 4중 차단**: (a) `..` path traversal, (b) skill name 영문/숫자/_/- 만 허용, (c) canonicalize 후 starts_with 재검증 (symlink escape), (d) invalid → NOT_FOUND + context. /index/schemas 도 `index.skill_resource@1.0` 추가 → 14 → 15 schemas (9 active + 6 stub). 다음 = [B-blueprint-skill-mcp-client](/ops/backlog) (Blueprint Agent SDK 가 본 두 tool 로 skill discovery, filesystem 의존 제거) → [D-index-17](/ops/decisions) sunset 기준 (b) 충족. | 2026-05-28 | commit `bf09547` |
| **B-index-mcp-surface-2x** ✅ | Phase 0 마무리 — MCP `tools/list` 4 → 8 tool 확장 + `/index/schemas` envelope 활성화 ([D-index-7](/ops/decisions)). 신규 tool: `list_deals(stage?, sector?)` portfolio overview, `get_deal(deal_code)` full snapshot (target_company + fund_investments[] + financial_model + scenarios[]), `cross_deal_benchmark(driver, scenario)` D-index-10 A5 의 MCP 노출, `get_exit_matrix(deal_code, scenario?)` leaf-level detail (joint_probability + dead_leaf + concentration). `/index/schemas` 가 빈 list → 14 schema 본문 (8 active DB-backed: target_company / deal / fund_investment / financial_model / financial_driver / financial_scenario / exit_matrix_leaf / financial_output + 6 stub Phase 1: dd_finding / ic_decision / portfolio_kpi / risk_alert / valuation / lp_comm) + metadata.frozen_enums 4종 ([D-index-15](/ops/decisions) immutable) + dsl_operators 12 + decision_references 9. 신규 CLI `index dump-schemas` (auth bypass JSON dump). 회귀 검증 PASS: validate-model 27/27 + IRR ±1pp IC baseline 유지 (Iippo 36.52% / Sentry 40.26% / Canopy 26.39%). 다음 consumer = ic skill `--push-to-index` ([D-index-13](/ops/decisions) atomic batch) + Blueprint citation resolver (`index.financial_output` kind). | 2026-05-28 | commit `2dfc484` |
| **B-index-customers-yaml** ✅ | [D-index-10](/ops/decisions) production prereq — `customers.yaml axe.services.index` block 신설 (5 secret manifest: INDEX_DB_PASSWORD / INDEX_JWT_SECRET / AZURE_INDEX_MCP_CLIENT_SECRET escape_dollar / INDEX_PII_PASSPHRASE_AXEC Phase 1 backlog / ANTHROPIC_API_KEY shared). `service_paths.index` "placeholder 503" → 정상 path. `axe ship` CLI 에 `index` 등재 (`SHIP_SERVICES["index"] = {repo, deploy: manual_hint}` + `SHIP_DIRNAME_MAP`). Dockerfile cortex→index 정정 + sqlx offline `.sqlx/` 28 query cache → DB 없이 Docker 빌드 가능. docker-compose healthcheck python→curl. 검증: 4 컨테이너 healthy + `/healthz` 200 + `/index/mcp` 401 + WWW-Authenticate (RFC 9728) + RFC 9728 envelope. **Manual 잔존** (Soohun Global Admin): az ad app + admin consent + axe secret push + cloudflared route + GitHub remote + 첫 `axe ship index`. 상세 runbook = [/services/index#production-배포-axe-ship-index](/services/index). | 2026-05-28 | commit `38dcac8` |
| **B-index-A8-mcp-tools-integration** ✅ | [D-index-10](/ops/decisions) A8 — MCP `tools/list` + `tools/call` 4 tool 통합 (`src/mcp.rs` 137 → 566 line). **4 tools**: (1) `propose_deal_closure(seed)` atomic batch INSERT (D-index-13 정합 — 4 sub-tool 흡수, UUIDv5(deal_code) idempotency_key retry-safe), (2) `validate_financial_model(deal_code)` (A7 6 sanity check), (3) `compute_outputs(deal_code, scenario?)` (exit_matrix aggregation), (4) `query_irr(deal_code)` (per-fund display + summary weighted IRR). Methodology = irr::weighted_* 함수 재사용으로 validate.rs in-memory 결과와 byte-identical. 검증: Iippo 36.52% / Sentry 40.26% / Canopy 26.39% — 3 deal 모두 IC baseline ±1pp PASS. 3-layer error model (D-index-14) 적용: L1 HTTP (auth middleware) + L2 MCP body (JsonRpcError + error_code + context) + L3 skill. CLI smoke test 도입: `index mcp-call TOOL --args JSON` (auth bypass, dev 반복 회귀). **D-index-10 acceptance 8/8 PASS** (A6 xlsx round-trip 만 별 backlog 잔여). | 2026-05-28 | [D-index-10](/ops/decisions), `src/mcp.rs` |
| **B-index-A7-validate-financial-model** ✅ | [D-index-10](/ops/decisions) A7 — `index validate-model` CLI 6개 sanity check 도입 (`src/validate_model.rs` 608 라인). (1) driver_dag.cycle (topo sort, `revenue[y-1]` self-lag skip), (2) scenario_coverage (exit-matrix-only 모델 인식 — Sentry/Canopy 0% = PASS), (3) exit_matrix.sanity (dead_leaf + concentration > 50%), (4) leaf_probability_sum (Σ = 1.0 ± 0.02), (5) leaf_probability_sanity (V1 outdated upside never×writedown > 5% 자동 검출), (6) fund_investment.invariants (status=paid → invested_krw + paid_date 필수). 3 deal 모두 9/9 check PASS. 발견·수정: Canopy Initial BW paid_date NULL → 2025-06-01 보강. D-index-10 6/8 acceptance test 완료 (A1+A2+A3+A4+A5+A7). 잔여 = A6 (xlsx round-trip) + A8 (MCP tool integration). | 2026-05-28 | [D-index-10](/ops/decisions), `src/validate_model.rs` |
| **B-customer-deploy-generalization** ✅ | 5 요건 R1-R5 빌트인 완료 (Phase 1 5/26 + Phase 2 D-day 5/25). plan SSOT: `/Users/axe/customer-deploy-generalization-plan.md`. R1 `${HOME}` 변환 ✅, R2 vault SoT (`bw get password`) ✅, R3 `$` → `$$` escape (`escape_dollar` flag) ✅, R4 `image_override` 슬롯 ✅, R5 container_name customer-prefix (별 backlog [B-container-name-customer-prefix](#-신규-분류-안-됨) 으로 split). `_deploy_service_customer` 13-step + wrapper 3종 (`start-{frame,blueprint,hive}.sh`) + `bw-bootstrap.sh`. realchoice D-day 5/5 endpoint LIVE 검증. Phase 3 (3rd customer dry-run) 은 [B-customer-deploy-generalization-phase3-3rd-customer](#-신규-분류-안-됨) split. | 2026-05-26 | [/Users/axe/customer-deploy-generalization-plan.md](docstring) |
| **B-realchoice-port-collision-audit** ✅ | 트루비아 기존 14 컨테이너 (stream-mcp:8780, magnet-mcp:8770, ~/vault:8222, stream-realchoice 외) ↔ axec stack 포트 충돌 사전 점검. **D-day 5/25 5/5 endpoint LIVE 으로 implicit pass** (trap #6 포트 점유 함정은 onboard 중 발견 후 해소, known-gaps "realchoice D-day 6 함정" 에 포트 충돌 미언급 = 실제 충돌 없음). 영구화 = [B-port-conflict-preflight](#-신규-분류-안-됨) 의 onboard step preflight CLI. | 2026-05-25 | trap #6 + Ship Log 5/25 |
| **B-realchoice-vault-instance-decision** ✅ | 트루비아 기존 `~/vault` (Vaultwarden Timshel fork, port 8222) ↔ axec deploy 시 신설 `axe-vaultwarden` 인스턴스 선택. **결정**: 옵션 (a) **기존 vault 유지 + OIDC SSO 추가** (data migration 부담 0). 5/25 (PM) Ship Log "Vault OIDC SSO 통합 ✅ (Q3 (a) 채택, `~/vault` = `soohunkang/vault` repo, SSO 로그인 → 잠금 해제 정상)" — D-day 실 운영 검증 완료. description 의 "(b) 잠정" 은 5/24 시점 RE^2 §Q3 가정 → 5/25 (a) 확정으로 정정. | 2026-05-25 | Ship Log 5/25 PM |
| **B-anthropic-connector-input-attrs** ✅ | claude.ai Custom Connector modal 의 4 input 식별자 부재 함정 — Anthropic 측 업스트림 보고 draft 작성. `/ops/reports/anthropic-connector-input-attrs-2026-05` (173 라인, 9 섹션 self-contained: Summary / Env+Repro / Root cause + DOM analysis / Requested fix `name`/`aria-label`/`autocomplete` / Impact 표 / AXE Labs 우회 (B-axe-mcp-catalog-en-aliases 참조) / Attachments / Channels (support@anthropic.com + GitHub claude-code issue) / Status). 운영자 검토 후 제출. 수락 시 한국어 UI 4/4 자동입력 + 모든 i18n locale 동시 해소. | 2026-05-28 | [/ops/reports/anthropic-connector-input-attrs-2026-05](/ops/reports/anthropic-connector-input-attrs-2026-05) |
| **B-vault-axe.2-patches-upstream-pr** ✅ | Timshel/vaultwarden upstream PR draft 작성. `/ops/reports/timshel-vaultwarden-upstream-pr-2026-05` (165 라인, 9 섹션 self-contained: Summary / Motivation (symptom + trigger + affected) / Changes (patch 0001 prelogin alias + 0002 connect/token AccountKeys+MasterPasswordUnlock) / Testing (manual verification + real-world validation) / Compatibility (backward+forward+no migration) / Code reference (axelabs-ai/vault commit hash TBD) / Related (axe.3 patches 별 PR) / Status / Channels). 두 patch 모두 dani-garcia/vaultwarden mainline backport 성격 → 수락 가능성 높음. 수락 시 AXE fork diff 자연 소실 → [B-vault-axe.2-sso-mp-incomplete](#-신규-분류-안-됨) archive. | 2026-05-28 | [/ops/reports/timshel-vaultwarden-upstream-pr-2026-05](/ops/reports/timshel-vaultwarden-upstream-pr-2026-05) |
| **B-trap-33-frame-hive-multi-issuer-docs** ✅ | trap #33 의 (c) docs portion — [/architecture/auth](/architecture/auth) line 147 정정 + 함정 표 row 추가. "v1 token (aud=URI) OR middleware 양쪽 수용" 권장 → **"v2 강제 + middleware multi-issuer 양쪽 모두"** (defense in depth). 함정 row = Frame/Hive `_MICROSOFT_ISS_PREFIX` v2-only matcher 가 v1 token 을 HS256 fallback path 로 보내 RS256 reject 시키는 정확한 메커니즘 + fix 위치 (`http_server.py:141`/`:67`). code fix (a, b) 잔존 = [B-trap-33-frame-hive-multi-issuer](#-신규-분류-안-됨). | 2026-05-28 | [/architecture/auth](/architecture/auth) |
| **B-vault-d-day-traps-2026-05-25** ✅ | realchoice vault SSO 통합 시 발견 **8 함정** 인벤토리 entry. 모든 함정 catalog 완료 + 80%+ resolved (#10 `$` escape ✅ / #11 sso_nonce verifier ✅ / #12 axe.2 patch ✅ / #13 bw appdata 격리 ✅ / #14 → [B-vault-org-cli-automation](#-신규-분류-안-됨) split). 잔여 #8 (vault-caddy path mount), #9 (wget → curl), #15 (Caddyfile `/vault/` trailing slash) 는 production 운영 검증 (axe.axelabs.ai/vault 정상) — vault-caddy 측 minor patch 또는 documented behavior 로 본 inventory entry 는 종결. | 2026-05-28 | trap #8-#15 인벤토리 |
| **B-onboard-d-day-traps-2026-05-25** ✅ | realchoice D-day 첫 onboard 실행 중 발견 **15 함정** 인벤토리 entry. #1-#10 D-day 초기 함정 ✅ (Tailscale alias / SSH PATH / keychain partition / 포트 점유 [B-port-conflict-preflight](#-신규-분류-안-됨) split / hardcoded path R1 ✅ / docker ps 사전 검사 ✅ / frame-proxy archived ✅ / cloudflared 127.0.0.1 ✅). #11/#12 PAT workaround. #16 → [B-vault-org-create-automation](#-신규-분류-안-됨). #17 `_svc_step_network` ✅. #18 → [B-axelabs-bootstrap-blueprint-mcp-app](#-✅-done) ✅. #19 → [B-customer-deploy-generalization-r6-volume-precreate](#-신규-분류-안-됨). #20 → [B-customers-yaml-mkdir-trap](#-✅-done) ✅. 모든 sub-trap 이 ✅ 또는 split 완료 — 본 inventory entry 종결. | 2026-05-28 | trap #1-#20 인벤토리 |
| **B-ops-reports-sidebar** ✅ | `/Users/axe/axelabs-docs/content/ops/_meta.js` 에 `reports` entry 추가 (troubleshooting 다음, known-gaps 앞). Round 1 의 ops/reports/ 폴더 신설 + Round 2 의 2 추가 mdx 가 sidebar 에 노출. | 2026-05-28 | `content/ops/_meta.js` |
| **B-vault-setup-playbook-v2** ✅ | taehun.kang 의 첫 실제 vault setup 피드백 5건 (2026-05-27 Teams) 을 [/onboard/vault-setup](/onboard/vault-setup) playbook 에 inline 반영. (1) Phase 2 macOS/Windows sub-section 분리 (Windows Hello + Microsoft Store vs `.exe` + PIN fallback), (2) Phase 4/5 강제 vs 선택 구분 + skip 영향, (3) Phase 5 TOTP 의미 "기존 item 손댈 필요 없음, 새 2FA 부터 적용" 명시, (4) TOTP UI 동작 3종 (view/edit/empty) 표, (5) "자동 채우기 정상" 검증을 SSO 위주 vs 웹 폼 위주 워크플로 분기, (6) 표준 vs valid 변형 섹션 신설. +84 라인 (200→284). | 2026-05-28 | [/onboard/vault-setup](/onboard/vault-setup) |
| **B-vault-revoke-scope-doc** ✅ | taehun 피드백 #6 (2026-05-27) — vault trust boundary 명확화. [/architecture/vault-policies](/architecture/vault-policies) 에 `## Vault scope — 무엇을 보호하는가 (trust boundary)` 신설 (8-row 분리표) + [/ops/runbook/employee-offboarding](/ops/runbook/employee-offboarding) 에 step 8 "외부 service 권한 회수 (vault scope 외)" 표 6 row + 함정 표 row. 메시지 = vault = secret 보관 ≠ 외부 service 권한 제어 (KB / 홈택스 / GitHub PAT / Cloudflare Access 회수는 별 절차). | 2026-05-28 | [/architecture/vault-policies](/architecture/vault-policies) |
| **B-bw-cache-recovery-procedure-docs** ✅ | bw CLI data.json cache stale 함정의 표준 recovery 절차 docs 등재 (`/architecture/secrets` 함정 표 row + `/ops/runbook/vault-recovery` 새 ## 섹션 ~48 라인). 증상/원인/빈도 (5/22 + 5/26)/회복 절차 4 step bash/자동화 후보 3 prong/함정 4-row 표. 자동화 잔여는 [B-bw-cache-stale-autoheal](#-신규-분류-안-됨) (별 backlog). | 2026-05-28 | [/ops/runbook/vault-recovery](/ops/runbook/vault-recovery) |
| **B-blueprint-scope-change-runbook-docs** ✅ | Blueprint OAuth scope 추가 함정의 docs 등재. [/architecture/auth](/architecture/auth) 의 함정 표에 row 1개 (refresh token 침묵 사망 + AADSTS65001 + MSAL 캐시) + `## OAuth scope 추가 시 운영자 절차` 새 섹션 (5-step bash: ship → admin-consent → docker restart → 검증 → user reconnect 안내). +27 라인. 자동화 prong 2개 (post-deploy hook + token health check) 는 [B-blueprint-scope-change-admin-consent-runbook](#-신규-분류-안-됨) 잔존. | 2026-05-28 | [/architecture/auth](/architecture/auth) |
| **B-claudeapp-fd-leak-anthropic-report** ✅ | Claude.app PTY/fd leak 의 Anthropic 측 공식 리포트 draft 작성. `/Users/axe/axelabs-docs/content/ops/reports/claudeapp-fd-leak-2026-05.mdx` (113 라인, 10 섹션 + frontmatter) — Summary / Environment / Symptom (failure mode + reproduction + diagnosis) / Workarounds / Suspected root cause / Impact / Requested fix / Attachments / Channels / Status. `ops/reports/` 폴더 + `_meta.js` 신설. 운영자 검토 후 support@anthropic.com 또는 GitHub claude-code repo issue 로 제출. | 2026-05-28 | [/ops/reports/claudeapp-fd-leak-2026-05](/ops/reports/claudeapp-fd-leak-2026-05) |
| **B-docs-ssot-extension-2026-05-26-corrections** ✅ | Truvia 2026-05-26 피드백 정정 7건 (B1-B7) docs 반영. **B1** [/ops/runbook/vault-recovery](/ops/runbook/vault-recovery) bw cache section + **B2** [/architecture/secrets](/architecture/secrets) `$` escape 함정 row + **B3** [/architecture/auth](/architecture/auth) (별 B-blueprint-scope-change 와 연계) + **B4** [/architecture/topology](/architecture/topology) `artemis_default` external network 함정 row + **B5** [/services/frame](/services/frame) `${HOME}` 함정 + `/Users/axe/` hardcode 금지 callout + **B6** [/partner/registration](/partner/registration) `--allow-no-subscriptions` 검증 step + **B7** [/partner/deploy](/partner/deploy) 함정 표 18-step 형태 재구성 (11 신규 row). 잔여 = 신규 페이지 A1/A2 ([B-docs-ssot-extension-2026-05-26-newpages](#-신규-분류-안-됨)). | 2026-05-28 | 다중 페이지 |
| **B-docs-playbook-frontmatter-marker** ✅ | playbook 페이지 frontmatter `playbook: true` 스킴 + `_meta.js` entry title 에 `⚡ ` prefix. 15 페이지 일괄 적용 (onboard 4 + ops/runbook 11). SSOT = [/architecture/playbooks](/architecture/playbooks). | 2026-05-26 | [/architecture/playbooks](/architecture/playbooks) |
| **B-docs-playbook-catalog-build-time** ✅ | `scripts/generate-playbook-catalog.mjs` 도입 — frontmatter `playbook: true` 페이지 인덱싱 + SSOT [/architecture/playbooks](/architecture/playbooks) 의 marker 사이 표 자동 교체 + `public/playbooks.json` deterministic export. | 2026-05-26 | [/architecture/playbooks](/architecture/playbooks) |
| **B-realchoice-d7-checklist** ✅ | Truvia 5/25 D-7 회신 처리 완료 (RE^4). (1) payslip Hive Phase 3 deferral, (2) 외부 회계법인 사내 협의 → [B-frame-cross-check-workflow](#-ready-다음-세션이-집어갈-수-있음) 분리, (3) macmini 이진우 자택, IP 동일, Tailscale 입고 후 회신 → [B-realchoice-tailscale-onboard](#) 분리. | 2026-05-25 | RE^4 |
| **B-realchoice-tailscale-onboard** ✅ | 피벗 (5/25 RE^6) — macmini 발주 skip, 기존 운영 macmini → `realchoice-macmini`. Tailscale ACTIVE direct + SSH + Docker + 절전 OFF 모두 기존 상태. 외부 IP 변경 X. D-day = 본일 (5/25). | 2026-05-25 | RE^6 |
| **B-axe-mcp-catalog-en-aliases** ✅ | `axe mcp publish` 의 `_mcp_item_payload` 3 차례 iteration + 운영자 retest 결과 — autofill 2/4 (Client ID + Secret) 유지 + Name/URL 은 copy-paste convenience field 등재. **확정 finding**: `Remote MCP server URL` field 추가 = regression (1/4), `Server URL` 단독 (EN label) = 안전. 6 Custom Field 표준 (Name + Server URL + MCP URL + Tenant ID + Scopes + Vault secret path). 매칭 천장 4/4 는 Anthropic markup 변경 ([B-anthropic-connector-input-attrs](#-신규-분류-안-됨)) 필수. **금지** = `Remote MCP server URL` 절대 추가 X. | 2026-05-27 | axe CLI docstring |
| **B-docs-cache-control-static** ✅ | docs.axelabs.ai 의 자주 갱신되는 정적 자산 (`/llms.txt`, `/llms-full.txt`, `/changes.json`) 에 `s-maxage=60` cache-control 명시. `next.config.mjs` 의 `headers()` source 3개 추가 — 기존 `/_pagefind/*` (commit 9c13bcc) 와 동일 패턴. ship 직후 Cloudflare 캐시 잔존 함정 차단. | 2026-05-26 | commit 9c13bcc + 본 PR |
| **B-trap-24-blueprint-mcp-admin-consent** ✅ | trap #24 영구 fix (docs 측). `/partner/registration` 의 Option A 사전 확인 표에 admin consent grant 권한 4 가지 role (Global Admin / Privileged Role Admin / Cloud App Admin / Application Admin) 명시 + 함정 표에 admin consent 실패 시 manual grant 절차 (portal UI / admin consent URL) 명시 + Option B 함정 모음에 admin consent 함정 row 추가. bootstrap.sh 측 Blueprint MCP app 등록 fix 는 [B-axelabs-bootstrap-blueprint-mcp-app](#-ready-다음-세션이-집어갈-수-있음) 별 task. | 2026-05-26 | trap #24 |
| **B-customers-yaml-mkdir-trap** ✅ | trap #20 영구 fix. **Root cause 확인** = axe CLI / bootstrap.sh / wrapper scripts / partner docs 어디에도 `mkdir -p .../customers.yaml` 같은 잘못된 명령 부재 (grep 검증 완료). Truvia 측 manual 실수 가능성 高 (customer 측에는 customers.yaml 부재가 정상 — operator SOT). **Defensive fix** = axe CLI `_load_yaml` + `_load_customers_yaml_rt` 에 `path.is_dir()` sanity check 추가 — file 예상한 path 가 dir 일 때 `IsADirectoryError` stack trace 대신 명확한 회복 안내 (`rm -rf <path> + recreate as file`). axe CLI 는 git untracked ([B-axe-cli-git-track](#-ready-다음-세션이-집어갈-수-있음)) 라 단일 머신 적용. | 2026-05-26 | trap #20 |
| **B-axelabs-bootstrap-blueprint-mcp-app** ✅ | trap #18 영구 fix. `axelabs-bootstrap.sh` 에 App #4 Blueprint MCP 등록 step 추가 (Frame MCP 패턴 1:1 mirror — application_id_uri `/blueprint/mcp` + mcp.access scope + claude.ai redirect + optional claims + v1 token + self-ref permission). JSON pack 의 `apps` 에 `blueprint_mcp` 필드 추가. `axe customers ingest` 가 optional 로 흡수 (옛 3-app pack 도 backward compat). `/partner/registration` docs = "3 개" → "4 개" + Option B App #4 섹션 신설 (Frame MCP 와 동일 절차 + 경로 차이 표). 새 SHA-256 = `ae6f771e85f7ec49d75bc082e1e0d42b106ba095e03d9adad430e590c2c4aefb`. 양쪽 (`public/` + `.axe/bootstrap/`) 동기화. | 2026-05-26 | trap #18 |
| **B-trap-23-hive-volume-compose-prefix** ✅ | trap #23 영구 fix — **R6 (B-customer-deploy-generalization-r6-volume-precreate) 통합 결정**. hive docker-compose.yml 의 external volume name (`hive-proxy_*` historical prefix) 정합성 문제는 R6 의 blueprint volume 6개 fix 와 함께 차기 phase 에서 한꺼번에 해소 (compose `external:true` 제거 → self-contained volume 권장). 별 task 종결, R6 row 비고에 trap #23 명시 추가. | 2026-05-26 | trap #23 → R6 |
| **B-vault-mcp-catalog** 🆕✅ | MCP Connectors catalog view ([D-vault-mcp-catalog](/ops/decisions)) — Vaultwarden `MCP Connectors` org collection (`1a62e754-6e47-43e0-a99a-cf71c37b8638`, 4 org 멤버 모두 access) + `axe mcp publish/list` CLI subcommand (axe CLI `cmd_mcp_publish`/`cmd_mcp_list`) + `axe secret rotate` 의 step 4.5 자동 hook (env name 패턴 `AZURE_*_MCP_CLIENT_SECRET` 감지 시 catalog 재발행) + customers.yaml frame_mcp 의 stale `client_secret_env` 주석 정정. 3 MCP seed (frame/hive/blueprint) publish 완료. `customers.yaml` SoT + Vaultwarden item SoT 변경 0 (catalog 은 derived view only). 함정 1 발견 + 정정 (frame_mcp client_secret_env stale, 5/26 정정). docs = [/architecture/secrets#mcp-connectors-catalog](/architecture/secrets) + [/ops/decisions D-vault-mcp-catalog](/ops/decisions) + known-gaps "vault측 미해결" 표의 bw cache stale 항목 cross-link. | 2026-05-26 | [D-vault-mcp-catalog](/ops/decisions) |
| **B-bw-cache-recovery-procedure** 🆕✅ | bw 2025.7.0 의 local data.json cached `cryptoSymmetricKey` stale 증상 (5/22, 5/26 두 차례) root cause 확정 + recovery procedure 표준화. **Root cause** = server-side patch deploy (axe.2, axe.3 등) 후 bw `sync` 가 cache 를 inconsistent 상태로 저장. `bw unlock` 은 캐시 무효화 X. **확정 절차** = `mv "~/Library/Application Support/Bitwarden CLI" .broken.$(date +%s) && bw config server https://axe.axelabs.ai/vault && bw login ai@axellc.com` (positional password 또는 osascript dialog). 약 1분. **추가 발견**: bw 2025.7.0 의 `bw unlock --passwordenv` 가 silent failure (rc=0 + empty output) — positional password `bw unlock "$PW" --raw` 만 작동. 본 PR 의 본격 영구 fix 는 [B-bw-cache-stale-autoheal](#) (axe wrapper layer) 로 분리. | 2026-05-26 | known-gaps "vault측 미해결" 표 + [B-bw-cache-stale-autoheal](#) |
| **B-vault-fork-build-pipeline** | [D-ops-40](/ops/decisions) 의 build pipeline 실 구현 + axe.3 release. `axelabs-ai/vault` repo public 전환, `build/build.sh` + `.github/workflows/build.yml` + `build/patches/0001..0004.patch` (axe.2 + axe.3 4 patch) commit + main push (commit `799015b`). GHA buildx multi-arch (linux/amd64+arm64) → GHCR push (PAT vault-stored, item `ghcr-axelabs-ai-pull-pat` in Platform — Service Secrets). main-`<sha7>` rolling tag + imagetools alias `1.34.1-6-axe.3` (manifest list digest `sha256:a26208a0794acbc9a2807379ffba33c7478dbe8d41daed24893f7916a55aeada`). axe-macmini compose 의 image 라인 = `ghcr.io/axelabs-ai/vault@sha256:...` 로 재핀 ([D-ops-11](/ops/decisions) immutable manifest-digest 정책 정합 복원). | 2026-05-26 | [D-ops-40](/ops/decisions) + axelabs-ai/vault commit `799015b` |
| **B-vault-org-perm-3-quirks** | [D-ops-40](/ops/decisions) patch 0003 + 0004 axe.3 release deploy + 3건 in-production 검증 통과. **patch 0003** = `src/api/core/organizations.rs` 의 3 site (line 522, 600, 685 — post_organization_collections + post_bulk_access_collections + post_organization_collection_update) 에서 `if member.access_all { continue; }` skip 제거 → Owner 도 명시 `users_collections` row 생성. **patch 0004** = `src/db/models/cipher.rs::to_json` (line 374 근방, User-sync branch) 에 `permissions: {response:null, delete:<bool>, restore:<bool>}` 추가 (`<bool>` = collection manage OR org Owner/Admin). 함정 2 (cipher edit collectionIds silent partial-revert) 는 vaultwarden bug 아닌 mainline design 으로 확인 — 운영 룰 영구 ([B-vault-org-cli-automation](#) 의 본 함정 확장). **검증 3건 in-production** (2026-05-26 13:19 KST): (1) `bw create org-collection ... users=[{id:ai@,manage:true}]` → SQLite users_collections 에 `ai@axellc.com\|0\|0\|1` row 명시 insert ✅, (2) raw GET `/api/sync` → org cipher 의 `permissions: {delete:true,restore:true,response:null}` 정확 emit ✅, (3) `bw delete item` rc=0 ✅. 영구 fix 완성, 운영 임시 룰 (SQL 수동 INSERT, admin endpoint 직접 호출) 자연 폐기. | 2026-05-26 | [D-ops-40](/ops/decisions) Progress |
| **B-matrix-git-init** ✅ | `/Users/axe/matrix` git init + first commit. 본 점검 세션 시작 시 working tree 가 init 상태였으나 commit 0 (`no commits yet`). `.gitignore` 보강 (`.env`, `.env.local`, `.claude/`, `.DS_Store`, `*.log` 추가 — 기존 `/target` 만) 후 13 파일 staged + commit `f73492d` "initial: matrix MCP monitoring service v0.1.0" + commit `48a301b` (collector port fix). ultrareview / 롤백 / origin push 가능 상태 회복. | 2026-05-26 | [D-matrix-1](/ops/decisions) |
| **B-matrix-rebuild-stale** ✅ | matrix blue/green 컨테이너 rebuild — `cargo check` 결과 `src/api.rs:26` 의 `matrix_info` 함수 미정의 (E0425) 로 working tree 자체가 컴파일 불가였음 (11:35 빌드 후 11:39 미완성 수정 흔적). `matrix_info` honest minimal stub (service info JSON: name/version/endpoints 4개) 추가 + collector port fix 와 한 번에 무중단 rebuild (green→blue 순서, 두 컨테이너 healthy 검증). 새 image digest, external `axe.axelabs.ai/matrix` 도 새 landing 반환. | 2026-05-26 | commit `48a301b` |
| **B-matrix-collector-port-fix** ✅ | `src/collector.rs:180` 의 blueprint-http URL `:3110` → `:3100/api/health` 정정. 호스트 `lsof` + 컨테이너 안 `docker exec curl` 양쪽 검증 — :3110 미 listening, :3100/api/health 가 정답 (Blueprint Next.js dev, `/Users/axe/blueprint/src/app/api/health/route.ts` 존재). cortex-fe/cortex-be 는 그대로 — cortex backend :3210 실제 down, cortex frontend :3200 root path 빈 응답으로 **valid alert**. rebuild 후 첫 cycle: failures = `["cortex-fe-http", "cortex-be-http"]` (blueprint 사라짐 ✓). 누적된 blueprint-http unacked alert 1 row 도 ack 처리 (`acked_by='collector-port-fix-2026-05-26'`). | 2026-05-26 | commit `48a301b` |
| **B-matrix-mcp-auth-enforce** ✅ | matrix `/matrix/mcp` 에 JWT auth middleware 부착. router 분리 — `mcp_router = Router::new().route("/matrix/mcp", post(mcp::handle_mcp)).route_layer(middleware::from_fn(auth::auth_middleware))` + main router 에 merge. REST + health 는 anonymous 유지 (의도된 공개 status board). **부착 전 안전 검증** = production access log 0 (matrix-mcp-blue/green/proxy 모두 /matrix/mcp 호출 흔적 0) + Blueprint repo 에 matrix MCP client 코드 0 + customers.yaml 에 `MATRIX_JWT_SECRET` vault 등재 (`matrix/axe/jwt-secret`) = JWT 의도 분명. 검증: no-auth POST → 401 "missing bearer token", REST → 200. `cargo check` 의 `auth_middleware never used` warning 사라짐. | 2026-05-26 | commit `96cf758` |
| **B-matrix-cortex-collector-skip** ✅ | matrix collector 의 cortex-fe-http / cortex-be-http 두 endpoint 제거 — **cortex 는 개발 중** (운영자 확인 2026-05-26), launchd 미부트 + `:3210` 미 listening + `:3200` 빈 응답으로 valid alert 가 운영 noise 화. `src/collector.rs:181` 에 재가동 시 재활성화 조건 주석 명시. rebuild 후 collector cycle = `check passed` (failures 0). 누적 unacked alert 2 row (cortex-fe + cortex-be) 도 ack 처리. | 2026-05-26 | commit `96cf758` |
| **B-frame-fund-ingest-verify** | 강태훈 대표 fund 자료 ingest 시도 결과 audit — D-ops-30/PR #38 fix 적용 후 `axe_ia_001` (kip, fund_ksme) 정상 empty fund 로 회복 (48 accounts + accounting_policy bootstrap + alembic 0019 head). 회계 데이터 0 = 사용 시작 준비 완료. 7 entities → 5 로 좀비 정리 (`axe_ia_001_diag` + `bug_check_kip_20260524` DROP, `axep` 보존) | 2026-05-26 | [D-frame-fund-ksme-policy-check](/ops/decisions) + [D-frame-register-entity-atomic](/ops/decisions) |
| **B-frame-register-entity-atomic** | `register_entity` atomicity + mismatch detect (강태훈 bug report root cause #2/#3 잔여분 영구 fix). (a) existing row 의 standard/kind/schema_name mismatch 시 ValueError (silent override 금지), (b) `upgrade_entity` 실패 시 compensating `DROP SCHEMA CASCADE` + `DELETE shared.entity` 로 좀비 회수. 6 신규 pytest (mismatch standard/kind/all-diffs · idempotent identical · zombie cleanup · pre-existing 보호) + 16 기존 PASS 무회귀 | 2026-05-26 | [D-frame-register-entity-atomic](/ops/decisions). `src/frame/db/migrations.py:88` + `tests/test_register_entity_atomicity.py` 신설 |

## 🗄️ Archive (1주+ 경과 · Ship Log + decisions 영구 보존)

> Done 에서 1주 경과한 ship 완료 항목. 상세 narrative = [updates Ship Log](/ops/updates), 결정 = [decisions](/ops/decisions). 본 표는 ID → 결정 trace 만 유지 (compact).

| ID | 한 줄 | 완료일 | 결정 |
|---|---|---|---|
| B-bp-artifact-prisma + B-bp-artifact-link-table | Artifact + ArtifactLink Prisma migration + `src/lib/artifact/store/` | 2026-05-23 | [D-bp-artifact-1](/ops/decisions) |
| B-bp-artifact-schema-discovery | Blueprint `McpSchema` 모델 + fetcher/registry + admin API 2 | 2026-05-23 | [D-bp-artifact-1](/ops/decisions) |
| B-frame-mcp-schema-endpoint | frame `/frame/schemas` 13 schemas | 2026-05-23 | [D-bp-artifact-1](/ops/decisions) |
| B-hive-mcp-schema-endpoint | hive `/hive/schemas` 15 schemas | 2026-05-23 | [D-bp-artifact-1](/ops/decisions) |
| B-onboard-azure-pack | `axe customers ingest` CLI 신설 (schema 검증 + yaml fill + vault push) | 2026-05-23 | [D-ops-34](/ops/decisions) |
| B-onboard-bootstrap-publish | `axelabs-bootstrap.sh` raw 노출 + partner docs self-contained | 2026-05-23 | [D-onboard-bootstrap-publish](/ops/decisions) |
| B-health-monitor-launchd | `com.axe.health-check` → matrix service 대체 | 2026-05-23 | [D-matrix-1](/ops/decisions) |
| B-docs-search-impl | docs.axelabs.ai Pagefind UI 검색 코드 머지 | 2026-05-22 | [D-docs-search-1](/ops/decisions) |
| B-frame-shared-extend | `shared.entity` entity_kind+fund_meta+closed_at ADD (0008_shared) | 2026-05-22 | [D-ops-22](/ops/decisions) |
| B-frame-entity-relationship | `entity_relationship` ownership numerator/denominator + kind ENUM | 2026-05-22 | [D-ops-22](/ops/decisions) |
| B-frame-cross-journal-link | `shared.cross_journal_link` 신설 (mirror 분개 pair) | 2026-05-22 | [D-ops-22](/ops/decisions) |
| B-frame-register-entity-cli | `register_entity` Python API + CLI `--kind`/`--fund-meta` | 2026-05-22 | [D-ops-22](/ops/decisions) |
| B-frame-fund-deploy | frame-mcp rebuild + `0008_shared` migration + 0 regression | 2026-05-22 | [D-ops-22](/ops/decisions) |
| B-frame-rfc9728-fix | RFC 9728 resource-level path 401 → Connector Reconnect fix | 2026-05-22 | [D-ops-23](/ops/decisions) |
| B-vault-sso-email-verif | `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION` Entra email_verified fix | 2026-05-22 | [D-ops-24](/ops/decisions) |

## 신규 항목 등재 — 한 줄 가이드

```markdown
| **B-<area>-<slug>** | <행동 한 줄> | M? | <추정 d> | <의존성/비고 + decisions/docs 링크> |
```

규칙:
- ID = `B-AREA-SLUG` (B = Backlog, area = `org` · `frame` · `hive` · `bp` · `docs` · `infra` · `legal` · `backup` 등)
- 한 줄 행동 — 1주 안 끝날 항목은 쪼개거나 마일스톤으로 승격
- 마일스톤 ID 명시 (M1~M5) — 없으면 `—`
- 관련 decisions / docs 항상 링크
- 작업 시작 = 🔧 로 옮기고 owner + 시작일 추가
- 완료 = ✅ 로 옮기고 완료일 + 결정 링크. 1주 후 archive

## 본 페이지의 의도

다른 세션이 들어와도 **"무엇부터 할 지" 가 5초 안에 보이게**. [known-gaps](/ops/known-gaps) 는 "왜 그렇게 됐는지·뭐가 함정인지" 의 분석적 정보, 본 페이지는 "다음 행동" 의 실행 큐. 마일스톤 큰 그림은 [roadmap](/ops/roadmap).

---

<!-- PAGE https://docs.axelabs.ai/ops/decisions -->

# 아키텍처 결정 (DECISIONS)

> D1~D-ops-19 누적 결정 기록 + 함정 모음.

URL: https://docs.axelabs.ai/ops/decisions

# 아키텍처 결정 누적 기록

다음 두 SSOT 파일에 결정이 누적되어 있고, 본 페이지는 그 요약입니다. 변경 발생 시 그쪽 파일이 우선이고 본 페이지는 후행 정리:

- [/Users/axe/multi-tenant-platform-plan.md](https://github.com/soohunkang/blueprint/blob/main/multi-tenant-platform-plan.md) — 마스터 플랫폼 plan + D 결정 + 함정
- [/Users/axe/frame/DECISIONS.md](https://github.com/soohunkang/frame/blob/main/DECISIONS.md) — frame 측 D-ops-1 ~ 15

## D — 플랫폼 결정

| ID | 결정 | 채택일 |
|---|---|---|
| D1 | **격리 = customer 1개 / macmini 1대** (OS-level, SPOF 수용) | 2026-05 |
| D2 | **테넌트 ID = 이메일 도메인** (customers.yaml SSOT) | 2026-05 |
| D3 | **path-based 1-level subdomain** (`{customer}.axelabs.ai/{service}`) | 2026-05 |
| D4 | **Tailscale 메시 + SSH key** (자체 mTLS 안 만듦) | 2026-05 |
| D5 | **HTTP MCP + 부트스트랩 JWT** (OAuth 1차 deferral) | 2026-05 |
| D6 | **push-based CI/CD** (pull polling 안 함) | 2026-05 |
| D7 | **P2P ring restic backup** (mesh 안 만듦) | 2026-05 |
| D8 | **3-tier secret** (vault + keychain + env) | 2026-05 |
| D9 | **schema-per-entity** (고객 내 법인 격리, RLS 대신) | 2026-04 |
| D10 | **index / vault 동일 패턴** (Phase 6 deferral) | 2026-05 |
| D-config-13 | **다운타임 0 frame deploy** (blue/green + host proxy, cloudflared 미관) | 2026-05-15 |
| D-config-14 | **DR cold storage** (external SSD rotation, 종이 password) | 2026-05-15 |
| D-config-15 | **blueprint multi-customer** (env override per macmini) | 2026-05 |
| D-config-16 | **blueprint = Postgres** (SQLite deprecate 예정) | 2026-05 |
| D-config-17 | **Postgres cutover 무중단** (운영자 명시 승인) | 2026-05 |

## D-ops — frame 운영 결정

| ID | 결정 | 채택일 |
|---|---|---|
| D-gate-5 | **e-sign 직접구현 = 암호등급 자체 서명엔진 ([D-gate-3](/ops/decisions) 모두싸인 integrator 입장 supersede)** (2026-06-07 — 빌드+검증 완료, 운영자 pivot) — [D-gate-3](/ops/decisions) 은 e-sign 코어를 **모두싸인이 흡수**(integrator)하고 직접-build 서명엔진을 Phase-2 로 defer 했으나, 운영자가 *"모두싸인의 기능을 직접, 암호등급으로 구현"* 지시 → gate Phase-1 = **gate-native 직접-build 암호 서명엔진**(작동 self-hosted, 이 세션 빌드+검증). **무엇이 빌트됐나**: ① **CMS/PKCS#7 CAdES-BES** detached 서명(RSA-2048+SHA-256), `DocumentSigner` trait(**HSM-ready**) + `SoftwareSigner`(self-signed X.509) — 적대적 리뷰(위조 도달경로 없음) + openssl 양방향 호환, 7 tests. ② **RFC3161 신뢰 타임스탬프 → CAdES-T**(hand-rolled ASN.1, 단일 clean dep; default DigiCert RSA TSA, 한국 prod = Koscom/CrossCert config-swap), 9 tests + live round-trip. ⑤ **워크플로 배선**: 시행(execute) 시 `esign.gate` actuator 가 승인된 결정을 **server-seal**(canonical decision bytes → CAdES-T), append-only **`esign_seal`** evidence 테이블(전자문서법 §5 custodian) 저장. 신규 **`verify_seal`** MCP tool(서명+무결성+타임스탬프 검증). e2e: 결재→seal→verify valid, 저장 CMS openssl cross-verify 통과, DB tamper→integrity fail. **법적 근거(전자서명법 2020, 공인폐지)**: 사서명(private/internal e-sign)은 **실지명의 + 서명의사**면 유효 — gate 의 경우 **실지명의 = 인증된 gate identity**(내부 서명자), **서명의사 = 결재 승인 행위** → 운영 라이선스 불요·합법. **유지된 경계(여전히 Phase-2/하드닝)**: 외부 서명자 **본인확인 = 방통위 지정 본인확인기관** 통합(정보통신망법 §23-3, 자가구축 불가) = **진짜 Phase-2** · HSM(cryptoki/PKCS#11, abstraction ready) · PAdES 서명-PDF 컨테이너(③④ typst deterministic render + pyHanko) · production 키관리(dev = ephemeral key) = **하드닝**. **red-team P0 해소-또는-명시**: 직접-build 를 막았던 P0(HSM·HTML→PDF 결정성·custody)가 — 결정성은 **canonical bytes 로 now**(typst PDF 는 later), HSM 은 **abstraction ready**(trait), custody 는 **esign_seal + RFC3161 TSA** 로 해소-또는-명시. **MUST NOT(불변)**: 자체 CA·per-user cert·자체 TSA·"공인/인증" 주장 — gate 는 **단일 서버 서명 identity**(ModuSign-recipe 모델: per-user cert 없이 서버가 봉인). **스택**: RustCrypto `cms`/`der`/`rsa` + RFC3161 + DigiCert TSA. 갱신: [/architecture/governance](/architecture/governance) §6 재작성 + [para-os §84](/architecture/para-os) footnote + [D-gate-1](/ops/decisions) Phase-1 e-sign 행. 정합: [D-gate-1](/ops/decisions)(scope) · supersede [D-gate-3](/ops/decisions)(e-sign 경계). | 2026-06-07 |
| D-gate-1 | **gate = 한국형 결재+e-sign+법무 거버넌스 제품 — narrowed Phase-1 확정(경로 A), 야심 5종 Phase-2 defer** (2026-06-06 결정 → 코드 착수 직전; 마스터플랜 [B-bp-decision-pipeline-esign](/ops/backlog), 상세 [/architecture/governance](/architecture/governance)) — gate = 신규 **Rust+Postgres** 서비스(포트 41xx: pg4100/blue4110/green4111/proxy4112, origin `axe.axelabs.ai/gate`), 한국형 **내부 전자결재 + e-sign + HTML 문서 + 법무검색**을 AI-driven 결정→실행 파이프라인으로. **동기**: 7라운드 설계 후 7-agent red-team 이 풀설계(결재+직접 e-sign+법무 RAG flywheel+공개 SaaS+결제+멀티테넌트 = 1인이 동시에 짓는 6~7 규제제품)에 **NO-GO**(11 P0 / 16 P1 / 8 누락) 판정 — 11 P0 가 **전부 야심 5종에 거주**. → **경로 A(narrowed Phase-1)** 채택: 11 P0 를 *해소가 아니라 defer 로* 회피. **Phase-1(확정·착수 가능)**: ①결정로그(record≠process, [D-gate-2](/ops/decisions)) ②결재워크플로 상태기계(기안→DOA→승인/반려/보류→시행) ③document = HTML spine→PDF 렌더 ④**서명 signature** — *2026-06-07 [D-gate-5](/ops/decisions) 로 갱신*: 모두싸인 통합(provider=modusign, [D-gate-3](/ops/decisions))에서 **gate-native 직접-build 암호 서명엔진(CAdES-T server-seal + esign_seal + verify_seal)** 으로 전환, 모두싸인 = optional alternative provider 로 강등 ⑤actuation ledger(멱등+reconcile) ⑥Blueprint `gate.decision` citation mirror. **AXE-internal only**, **pgvector-KR**(Pinecone 아님), 법무=**내부검색만**(결재 자동주입 X, [D-gate-4](/ops/decisions)). 결제·멀티테넌트 **없음**. **Phase-2+(각자 규제/substrate 게이트, defer)**: 외부 서명자 **본인확인기관** 통합(정보통신망법 §23-3, [B-gate-bonin-id-contract](/ops/backlog)) — *직접 e-sign 엔진 자체는 [D-gate-5](/ops/decisions) 로 Phase-1 빌트; 잔여 하드닝 = HSM·PAdES-PDF·prod-key* · Pinecone 법무 flywheel(+PIPA) · 공개 SaaS(+tenant_id RLS substrate·self-IdP) · 결제(포트원/토스/Paddle, +전자금융/전자상거래) · cross-tenant 축적(+PIPA 가명정보). 빌드게이트 = [B-gate-legal-counsel](/ops/backlog) + [B-gate-phase2-gates](/ops/backlog). **착수 순서**: docs-first(D-gate-1~5 + governance.mdx) → `cp -R cortex gate` scaffold(auth 3-branch ladder·RLS·blue/green 상속) → 7테이블 migration(+`esign_seal`) → 상태기계 → **`esign.gate` actuator**(gate-native CAdES-T server-seal + verify_seal, [D-gate-5](/ops/decisions) 빌트) + 모두싸인 alt-provider stub(optional). 기준 = [para-os §7](/architecture/para-os) refine, [D-bp-para-1](/ops/decisions) governance clause 확장. | 2026-06-06 |
| D-gate-2 | **결정 record SoR = gate `decision` 테이블, Blueprint = `gate.decision` citation mirror — D-bp-para-1 governance clause refine** (2026-06-06) — [D-bp-para-1](/ops/decisions)/[para-os §7](/architecture/para-os) 은 결정로그를 *"Blueprint core primitive(가로)"* 로 뒀으나 = AXE-internal 전제. **standalone 외부제품 요구 + 3축 survey(SoR경계·auth·멀티테넌트)** 가 refine: **record SoR = gate** `decision` 테이블(완료 workflow + 서명 HTML문서 + cert·authority·actor·decided_at·basis citations·supersedes, append-only). **Blueprint = mirror**: citation kind `gate.decision`(artifact·Area 가 cite) + 후일 visibility-gated mirror 테이블 — optional consumer 1종, 외부고객 = OFF(gate 단독 완결). **근거(grounded)**: [/architecture/artifacts](/architecture/artifacts) "MCP backend = sole owner, data 중복 0" · [/architecture/data](/architecture/data) cross-service = 직접 DB read 금지·명시적 신호채널(pg_notify/outbox)만 · **[D-cortex-9](/ops/decisions) = service-owns-SoR + Blueprint visibility-gated mirror 이미 빌트**(template 기성) · [para-os §7](/architecture/para-os) e-sign cert 를 citation 으로 = pre-authorize. → round-1 의 "record→Blueprint core" 가 오히려 platform 패턴(service-owns-SoR) 이탈, standalone 요구가 아키텍처가 가리키던 곳을 드러냄. 상세 = [/architecture/governance](/architecture/governance). | 2026-06-06 |
| D-gate-3 | **actuation ledger(결정→실행 멱등 일관성) + e-sign = 모두싸인 integrator(gate = 전자문서법 §5 evidence custodian); 직접-build 서명엔진 = Phase-2 gate** (2026-06-06) — ⚠️ **e-sign 부분은 [D-gate-5](/ops/decisions)(2026-06-07) 가 supersede** — 직접-build 암호 서명엔진이 Phase-1 으로 당겨져 빌트됨(아래 e-sign 경계는 역사 기록). actuation ledger 부분은 유효. 승인된 결정 → actuator 호출(`frame.post_journal`/`index.register_deal` 등, [para-os §7](/architecture/para-os) "Area 서비스 = actuator"). **actuation 테이블** = 실행 ledger(actuator_kind·payload·**idempotency_key=uuidv5(workflow+seq+actuator+payload_hash)**·state pending/inflight/done/failed·result_ref·reconciled_at) + **reconcile 워커**(frame-worker 패턴, pg_notify). **e-sign 경계(Phase-1 = INTEGRATE, [para-os §84](/architecture/para-os) 와 정합)**: signature.provider=`modusign` — 본인확인·타임스탬프·증거능력 코어를 모두싸인이 흡수, gate 는 **전자문서법 §5 evidence custodian**(서명문서+메타[작성자·수신자·송수신/서명 일시] 무결성 보관 + consent 기록, immutable audit store). cert ID 만 citation 참조(복제0). **⚠️ 직접-build 서명엔진(자체 PKI 서버서명·PAdES/XAdES·HTML→PDF 결정성[sealed-bytes=원본]·해시봉인·공개검증포털·감사추적인증서·HSM/KMS·서명키 DR/escrow·대법원 2017도13263 custody·본인확인기관 직통합) = Phase-2 gate**(red-team P0 #3/#7/#10) — 정당화였던 KISA §8 인정조차 "MVP 불요". **MUST NOT(Phase 무관)**: 자체 CA·per-user cert·자체 TSA·"공인/인증" 주장. **멱등 보강**: 모두싸인 actuator 도 provider-side idempotency 토큰 필요(gate idempotency_key 가 외부 이중실행 못막음, red-team P0 #5); saga 보상(e-sign+결제+분개) = 결제 도입 Phase-2. 상세 = [/architecture/governance](/architecture/governance). | 2026-06-06 |
| D-gate-4 | **법무 모듈 가드레일 = 변호사법 §109/§34 검색·정보 한정(자문 금지); Phase-1 = pgvector-KR 내부검색만, flywheel = Phase-2** (2026-06-06) — gate 법무모듈 = **검색·요약·번역·템플릿(로폼: user-blank, 기계적)만**. **하드룰 변호사법 §109(형사)·§34(5)**: 법률상담/사안별 자문/대리/결과예측-as-advice **금지**, **공개 "AI 법률상담" 금지**(AI대륙아주 7개월 폐쇄·징계 선례), 변호사 노출 시 정액광고만(로톡 모델, 알선료/성공보수/광고수익배분 금지). 모든 출력 "**법률 정보, 자문 아님**" disclaimer + cite = **retrieval-verified**(존재 + 시행일/선고일 temporal 강제). **결재 자동주입 차단**(AI 기안이 법령/판례를 auto-approve 경로에 주입 X — red-team P0 #2). **Phase-1 data**: 국가법령정보 OPEN API(open.law.go.kr, 이용제한없음·무료) + data.go.kr 판례(상용 OK) + HF `korean_law_open_data_precedents`(openrail), 대법원/헌재+법령 grade(하급심=상용 walled 제외). SoR = gate Postgres, index = **pgvector-KR**(Pinecone 아님). **Phase-2 gate**: Pinecone+Cohere rerank+Gemini embed flywheel(LLM비용 사용자부과·DB 복리) + cross-tenant 축적 = **PIPA 처리근거·가명정보·국외이전 자문**([B-gate-legal-counsel](/ops/backlog)) 선결 — `lbox_open`/`kcl`=CC BY-NC=유료제품 금지. B2B/internal-use 유지 = 최저위험. 상세 = [/architecture/governance](/architecture/governance). | 2026-06-06 |
| D-ops-44 | **Vault 비밀 주입 = SSH 환경 raw-bw keychain-free (`axe vault unlock` 금지)** (2026-06-09, `/Users/axe/CLAUDE.md` 강제 규칙으로 박제) — 이 머신 = AXE Mac mini, Claude Code 세션은 **SSH(loopback) 위에서** 돌고 운영자는 Windows 에서 `ssh axe@100.127.210.30` (Tailscale) 로 접속. macOS 는 **SSH 세션이 GUI login keychain 에 쓰는 것을 차단**("User interaction is not allowed") → vault 비밀을 *넣는* 경로의 keychain 의존이 전부 막힘. **금지(SSH 에서 전부 실패)**: (1) 운영자에게 `axe vault unlock` 시키기 — keychain-cache 단계가 SSH 에서 crash. (2) `axe secret push/pull/check` 로 비밀 PUT — `_vault_env` 가 keychain 세션만 읽음(`security find-generic-password -s axe.vault.session -a ai@axellc.com`) → SSH 에서 "vault session not found". (3) osascript `display dialog` — GUI 다이얼로그라 원격/Windows 운영자에게 안 보임(운영자-타이핑 비밀은 `read -rs`). **정답 = keychain-free raw-bw**, 운영자가 자기 인터랙티브 셸(Windows `ssh axe@…` 또는 Mac 터미널)에서 직접 실행. 에이전트는 **ASCII-only·주석 없음·`bw unlock` 을 단독 한 줄**로 공급(한 블록 붙여넣기는 unlock 프롬프트가 다음 줄을 비밀번호로 삼켜버림). 단계: ① `export NODE_EXTRA_CA_CERTS=/Users/axe/.axe/vault/certs/rootCA.pem`(Vaultwarden private CA — 필수) ② **단독 줄** `export BW_SESSION="$(bw unlock --raw)"`(master-pw 프롬프트; TTY-flaky 폴백 `read -rs PW; export BW_SESSION="$(BW_PASSWORD="$PW" bw unlock --passwordenv BW_PASSWORD --raw)"; unset PW`) ③ raw `bw create`/`bw edit` 로 Login item — **name** = `customers.yaml` 의 `services.<svc>.secrets[].vault` 경로(예 `gate/axe/jwt-secret`), **username** = env var 이름, **password** = 스크립트 안에서 생성/읽은 값(`$(openssl rand -hex 32)`/`$(cat key.pem)`/상수 — echo·history·argv·agent-context 어디에도 안 남김) → `bw sync` → `unset BW_SESSION`. **검증**: 에이전트는 검증 불가(세션이 운영자 셸에만 존재) → 운영자의 `created/updated` + `synced` 출력이 곧 확인, `axe secret check` 호출 금지(keychain 필요). **keychain 세션이 필요한 곳 = deploy/ship 시점 한정**(`axe ship`/`secret pull` 이 그때 keychain 읽음): SSH 에서 `read -rs KCPW; security unlock-keychain -p "$KCPW" ~/Library/Keychains/login.keychain-db; unset KCPW`(headless unlock, GUI 없음) → `axe vault unlock` → `axe ship`. 비밀을 *넣는* 작업엔 불요. 정합: [D-ops-17](/ops/decisions)(vault SoT) · [D-ops-40](/ops/decisions)(osascript hidden-dialog — GUI 세션 전제라 SSH 에선 본 raw-bw 가 대체). | 2026-06-09 |
| D-ops-43 | **운영자 원격 데스크톱 = RustDesk(Direct IP) over Cloudflare Access — Google Remote Desktop 대체, Tailscale 비의존** (2026-06-05 결정 → Phase 1 구축 중) — GRD(Google relay 경유 + Google 의존) 를 자체 트러스트 경계로 대체. **전송**: RustDesk 를 Direct IP 모드(자체 relay/ID 서버 미사용)로 axe-macmini 에서 구동 + `axelabs-tunnel`(d8efecdd) 에 TCP ingress (`rdp-axe.axelabs.ai → tcp://host.docker.internal:<port>`) 추가 → **`ssh-axe` ([D-ops-39](/ops/decisions)) 와 동일 Cloudflare Access 패턴**. 데스크톱 = `cloudflared access tcp --hostname rdp-axe.axelabs.ai --url localhost:<port>` 후 RustDesk 클라이언트 127.0.0.1 직결; 모바일 = Cloudflare WARP 등록 (`cloudflared access` CLI 가 폰에 부재). **인증 (2-phase)**: Phase 1 = **Microsoft Entra 직결 IdP** (즉시 가동, Blueprint 코드변경 0; 복구 채널이라 플랫폼 비의존이 오히려 견고 — 순환 의존 회피). Phase 2 fast-follow = **Blueprint OIDC 主 + Entra break-glass 副** ([B-blueprint-oidc-third-party-rp](/ops/backlog)) — 현 Blueprint OIDC (`src/lib/platform-oidc.ts`) 가 public·PKCE-only·exact-match 콜백 화이트리스트라 제3자 confidential RP (Cloudflare Access) 를 못 받음 → 콜백 허용 + client_secret 처리 + id_token/userinfo 완결성 확장 필요 ([D-axe-idp-1](/ops/decisions) Phase 2 영역). **Tailscale 배제 근거**: 인터랙티브 운영자 접속의 트러스트·전송은 Cloudflare Access 단일화 (ssh-axe 동형). Tailscale ([D4](/ops/decisions)) 은 backend (배포 push + 백업 ring) 전용 — RustDesk+Tailscale 안 함. **비용 $0** (Cloudflare Zero Trust Free ≤50 user; Spectrum 유료 경로 미사용). **macOS 26 Tahoe 함정**: RustDesk 에 화면 녹화 + 손쉬운 사용 권한 1회 수동 부여 필수 (SIP 보호, CLI 불가) + 주기적 재확인 nag. **거부된 대안**: (a) RustDesk+Tailscale — Tailscale 비의존 방향 역행. (b) RustDesk public relay / 자체 hbbs·hbbr — privacy + 추가 인프라. (c) Cloudflare Spectrum — 유료. (d) Blueprint 主 from start — 플랫폼 OIDC 코어(5 서비스 의존) 선확장 부담 → working RD 지연. (e) macOS 화면 공유(VNC) — Apple 코덱 성능 열위 (RustDesk 코덱 우선, 권한 마찰 수용). 본문: [/architecture/topology](/architecture/topology) + [/ops/inventory](/ops/inventory). **정정 (2026-06-05 동일 결정 진화): `{customer}.axelabs.ai/vnc` 경로 요구 → RustDesk(raw TCP) 폐기, 브라우저 VNC(Apache Guacamole) 전환.** path 라우팅 = HTTP 전용이라 TCP 불가 (ssh-axe flat 과 동일 D-ops-39 제약); Cloudflare 네이티브 browser-render VNC 도 hostname-bound (path 미지원, 2026-06 docs 확인) → 진짜 HTTP 앱 **Guacamole** 를 `/frame` 처럼 path 로. origin = macOS Screen Sharing(:5900) ← guacd ← guacamole webapp ← tunnel `http://host.docker.internal:<port>` ← Access(path-scoped, Entra). 이득 = 브라우저 클라이언트리스(모바일 ✓ — WARP 갭 해소) + 커스터머별 표준 path 템플릿. 트레이드오프 = RustDesk 코덱 → Apple VNC 코덱(관리/제어 충분). 초기 RustDesk-flat(`rdp-axe`, Access app `0653d6ef`) 자원 철거(2026-06-05). Phase 2 Blueprint SSO 는 Guacamole(HTTP)가 `Cf-Access-Authenticated-User-Email` 헤더 passthrough 로 RustDesk 보다 용이. **★ 최종 결론 (2026-06-05, 실측 후): GRD(Google Remote Desktop) 존치, 자가호스팅 대체 보류.** noVNC `/vnc` 를 e2e 구축·검증했으나 **Apple 레거시 VNC 코덱이라 체감 사용 불가** (Retina 프레임버퍼 + RFB + CF 다단 홉). RustDesk = 코덱 우수하나 네이티브 앱(브라우저/path 불가). **GRD 우위 = WebRTC/VP8 비디오 코덱을 *브라우저 안에서* + 네트워킹 셋업 0 + 모바일 — 이 조합을 자가호스팅으로 매칭하는 솔루션이 현재 없음** (Guacamole/noVNC/Cloudflare browser-render 전부 `:5900` 에 RFB 라 코덱 천장 동일; Mac 은 RDP 미지원이라 Guacamole RDP 경로도 불가). `/vnc` 실험 자원(noVNC 스택 `/Users/axe/axelabs/vnc/` + Access app `eae049e7` + ingress path rule + vault VNC pw) 철거 대상. **de-Google 미래 경로** = (a) RustDesk web client 성숙 시 self-host (코덱+브라우저 양립), (b) WebRTC 기반 자체 클라이언트(tether). 그 전까지 운영자 원격 데스크톱 = **GRD** (project_devenv "GRD 유지" 와 정합 — 본 결정이 실측으로 재확인). **수용한 trade-off**: GRD = 폐쇄소스(Google 독점 Chrome Remote Desktop — 호스트 코드 일부만 Chromium `src/remoting/` 공개, 릴레이·시그널링·디렉터리는 Google 비공개·self-host 불가) + 트래픽 Google relay 경유 = sovereignty 비용을 de-Google 솔루션 부재 시점까지 **의식적으로 수용**. | 2026-06-05 |
| D-ops-42 | **배포 SSOT 아키텍처 — `origin/main` SHA = 배포 진실원천** (worktree 작업격리 + build-from-SHA + deploy lock + 스테이지 상태기계 + migration-validation 게이트) (2026-06-04, DESIGN LOCKED · additive rollout) — **원칙**: `origin/main 의 commit SHA = 배포의 SSOT`. working tree·로컬 main·실행 중 컨테이너는 전부 그 SHA 의 파생·일회용 투영. docs·backlog 가 이미 matrix-postgres SSOT 규율([D-matrix-3](/ops/decisions))을 따르듯, 같은 규율을 **배포**로 확장. **동기 (실측 incident)**: N개 동시 Claude Code 세션이 repo 당 1 working tree + 1 `main` 공유 → (a) 다른 세션이 먼저 push 하면 `main` diverge → non-fast-forward push 거부, (b) 서로 다른 feature 의 uncommitted WIP 가 한 tree 에 누적 → 누구도 자기 slice 만 clean commit 불가, (c) `axe deploy` 가 dirty working tree 에서 이미지 빌드 → uncommitted 코드 prod 누출 + push 전 배포 가능. 2026-06-04: 이미 배포된 blueprint fix (commit `b4067504`) 가 main diverge + 타 세션 WIP 로 수 시간 push 불가 → 운영자 수동 reconcile (stash→rebase→push). 추가 발견: 운영자 `axe` CLI (364KB) 자체가 **버전 미관리·in-place 편집** = 같은 병의 가장 깊은 사례. **컴포넌트 A–F**: (A) **작업 격리** `axe work <svc> <slug>` = 세션별 git worktree (`~/.worktrees/<svc>/<slug>`) off origin/main, 정규 repo 는 fast-forward 전용 "main mirror" 강등(손편집 금지) → 공유 tree 경합·WIP 혼재·stash 더미 **발생 불가능**. (B) **SHA 에서만 빌드** = deploy 가 working tree 아닌 pushed SHA 의 clean checkout(`git worktree --detach`/archive)에서 빌드, 이미지 태그 `<svc>:<sha>`, push 안 된 SHA 배포 거부 → deploy-before-push + dirty-tree 누출 **구조적 불가능**. (C) **Deploy lock** = 서비스당 배포 직렬화 (matrix-postgres `pg_advisory_lock` 우선, 파일락 fallback) → 두 세션 동시 blue/green flip 불가. (D) **Provenance + drift** = 컨테이너 `org.axe.git_sha` 라벨, `axe health`/`axe host` 가 color 별 실행 SHA + origin/main 대비 drift 표시 → "라이브가 git 과 일치하나" 항상 답. (E) **잘못된 경로 제거** = `axe deploy` 가 tree 입력 폐기, `git push origin main` 직접 = pre-push 훅 + GitHub branch protection 으로 **기계적 차단**(현 honor-system 대체), `axe ship` 만 main 전진. (F) **통합 ship** = `axe ship`(worktree 에서): fetch → origin/main rebase → SHA build+test → push(main ff) → 그 SHA deploy(lock 하) → mirror ff → shiplog. 오늘 손 reconcile 전부가 한 명령. **스테이지 상태기계**: `built → canary(passive color, 트래픽 0) → [migration-validation 게이트] → live(active flip) → previous(직전 active = 즉시 롤백 타깃)` — blue/green 이 이미 canary/live/previous 3스테이지 제공. **migration-validation (안전 척추)**: 스키마 마이그레이션 포함 릴리스는 flip 전 prod DB 의 ephemeral clone 에 마이그레이션 적용·검증 (`axe drill`/backup 스냅샷 재사용). blue/green 이 **DB 공유** → 깨지는 스키마 변경은 카나리 *불가능* (green 용 마이그레이션이 blue 즉시 오염). 이 게이트가 blue/green 이 못 막는 유일한 위험 차단. 대상: blueprint 대기 migration 2개 (add_user_entra_oid, add_entity_legal_name), hive alembic. **rollout (additive)**: 전부 기존 동작과 공존 → `--dry-run` + passive-color 카나리(flip X) 검증 → cutover(기본값 flip + 가드 활성, escape hatch 포함) 게이트 → 되돌림 가능, 진행 중 WIP 보존. **채택 안 함**: 별도 staging *환경* (staging.axelabs.ai + 독립 DB/터널) — 단일 Mac mini 에서 새 실패유형 0 + 비용·parity 부담만, canary + migration-validation 이 실위험 커버. 작업추적 새 "스테이지" 축 — roadmap/backlog/updates 가 이미 작업 파이프라인. 본문: [/ops/runbook/deploy-ssot](/ops/runbook/deploy-ssot). 정합: [D-ops-16](/ops/decisions) (release-gate `axe ship`) · [D-matrix-3](/ops/decisions) (matrix SSOT) · [Blue/green deploy](/ops/runbook/deploy). | 2026-06-04 |
| D-axe-idp-1 | **Blueprint = 플랫폼 인가서버 (OIDC Provider) — 로그인 1회로 전 서비스** (2026-06-03 결정 → **Phase 1+2 LIVE 2026-06-04**; 현행 구현 SSOT [/architecture/platform-identity](/architecture/platform-identity)) — D-axe-cli-1 의 외부 인증을 "신규 Entra 앱" 대신 **Blueprint 중앙 관장**으로 (본질적 선택). Blueprint 가 Entra 를 상위 federate(인간 SSO 1회) + **자체 플랫폼 토큰 발행**(서명 JWT + JWKS + authorize/token/register + OIDC `.well-known`) → **모든 서비스가 Blueprint 신뢰**(iss=blueprint + JWKS 검증). 한 토큰이 전 서비스 동작 (서비스별 audience juggling 불필요). frame/cortex 의 per-service OAuth-RP 프록시(D-ops-14/15)를 Blueprint 하나로 **통합**(net-new 아닌 consolidation). 거버넌스(per-user/tenant scope·revoke·audit) Blueprint 중앙. **D-axe-cli-1 토큰모델 정정**: 인터랙티브=Blueprint 발행 토큰(Entra-direct/HS256 아님), HS256 부트스트랩은 헤드리스/cron 잔존. **보안 핵심 → 설계문서 + 신·구 병행 비파괴 cutover**. Phase: ①Blueprint OIDC-OP + `axe login`(loopback PKCE→Blueprint) + frame 가 Blueprint 신뢰(모델 증명) ②index/hive/cortex/matrix trust 이전 + proxy 폐기 ③거버넌스/감사 + headless device-code. **상태: Phase 1+2 LIVE (2026-06-04)** — Blueprint OIDC-OP(discovery·jwks·authorize·token·register·revoke) + RS256 키(vault) + `axe login` loopback-PKCE + frame·hive·cortex·index·matrix + Blueprint 자체 MCP **6개 서비스 전부 Blueprint 토큰 신뢰**(영속·e2e 검증). claude.ai→Blueprint OP 이전 + per-service 프록시 폐기, Phase 3(인가 중앙화·감사 UI·device-code·키 회전 자동화)만 잔여. | 2026-06-03 |
| D-axe-cli-1 | **외부/멀티에이전트 접근 = 고객 CLI (gh 모델) + 토큰 로그인, MCP 커넥터 대체** (2026-06-03 결정 → **LIVE**: 고객 CLI 배포·`axe login`·전 서비스 호출 가동; 사용자 매뉴얼 [/services/cli](/services/cli)) — 외부 인원이 서비스별 MCP 커넥터를 개별 등록하던 방식의 "느리고 불편" 본질 = ① 1인당 N개 커넥터 등록·인증 마찰 ② 커넥터당 도구 스키마 **100개+** (frame ~54 + HR ~40 + blueprint ~20 실측) 가 매 턴 컨텍스트 적재 → 모델 턴 지연·오선택. 해소 = **단일 CLI** (`~/axe-cli`). 근거: 셸 조합성(pipe/loop/batch 1회 실행, 모델 왕복 0 — MCP 도구는 고립 호출) + **에이전트 무관** (Claude Code·**Codex**·Cursor·Gemini CLI·cron·CI; CLI = syscall/ABI 층, vendor lock-in 0). **CLI-only** (웹 Cowork 용 Skill 폐기 — 외부 인원 Claude Code 표준화). **토큰** = `axe login --token` → OS Keychain → `Authorization: Bearer` (헤드리스/Codex 가능, 브라우저 OAuth 회피). 토큰 실체 = **HS256 부트스트랩 JWT** — frame `frame.<customer>.jwt_secret` 의 **이미-LIVE** 패턴 표준화; index 는 `INDEX_JWT_SECRET` 설정만 있고 **미배선**(Entra RS256 만 검증) → 배선 필요, hive/blueprint/cortex/matrix 도 PAT 경로 추가(P2). **배포 = Blueprint 설치 시 in-place 번들** (Blueprint=구동 시스템; `axe onboard` 가 테넌트 PAT 발급→Keychain = zero-touch 인증 + control-plane 자기설정) + standalone(curl/pip) 보조. **스코프 분리**: 운영자 `axe`(vault/deploy/secret/customers) ≠ 고객 CLI(업무 명령·토큰 스코프). 기존 `axe mcp` connector-catalog 는 외부용 대체. **현행 정정**: 토큰 모델은 [D-axe-idp-1](/ops/decisions) 로 갱신됨 — 인터랙티브 = Blueprint 발행 RS256 플랫폼 토큰(`axe login` SSO), HS256 부트스트랩은 헤드리스/cron 잔존. 배포 = `https://<tenant>.axelabs.ai/cli`(+`/cli.ps1`) served + `axe self-update`(매 실행 conditional GET). 잔여 backlog: headless device-code(`B-axe-cli-device-code`). | 2026-06-03 |
| D-ops-1 | folder-as-context — `.mcp.json` per folder | 2026-05-08 |
| D-ops-2 | JWT 평문 디스크 금지 — Keychain + launchctl env | 2026-05-08 |
| D-ops-3 | `sub` = identity, `permissions` = entitlement (분리) | 2026-05-08 |
| D-ops-4 | tool surface 분리 — operator/employee tools | 2026-05-09 |
| D-ops-5 | v1 permission matrix — read/write/close/admin | 2026-05-09 |
| D-ops-6 | end-to-end MCP test 자동화 | 2026-05-10 |
| D-ops-7 | `.mcp.json` is the spec location, NOT `.claude/settings.json` ⚠️ | 2026-05-11 |
| D-ops-8 | vault-per-entity canonical distribution | 2026-05-13 |
| D-ops-9 | Vaultwarden 가 canonical secret store | 2026-05-14 |
| D-ops-10 | Phase 1 SSO via Vaultwarden OIDC (Timshel) | 2026-05-14 |
| D-ops-11 | Timshel digest pin (mainline 무한 미지원 회피) | 2026-05-15 |
| D-ops-12 | sso_nonce manual SQL fix | 2026-05-15 |
| D-ops-13 | external_id mapping (Microsoft oid ↔ Vaultwarden user) | 2026-05-15 |
| D-ops-14 | frame OAuth-RP (Microsoft Entra ID direct) + Blueprint /onboard | 2026-05-17 |
| D-ops-15 | OAuth proxy 시도 (dormant — Anthropic Connector 한계로 미사용) | 2026-05-21 |
| D-ops-15.5 | axe.axelabs.ai 도메인 검증 + Application ID URI 형식 URL | 2026-05-21 |
| D-ops-16 | docs drift 강제는 release-gate (`axe ship`), pre-commit hook 채택 X | 2026-05-21 |
| D-ops-17 | secret = vault SoT + deploy-time pull (`customers.yaml` 매니페스트), runtime vault 호출 X | 2026-05-21 |
| D-ops-18 | compose env_file 단일 출처 (environment block 의 secret 중복 금지 + 하위 dir compose 의 `.env` symlink) + `axe secret pull` merge-mode (config 보존) | 2026-05-21 |
| D-ops-19 | Azure secret rotation = az cli + `--append` (overlap window) + app owner 운영자 명시 prereq | 2026-05-21 |
| D-ops-20 | **7-stack 응집** — service 별 1 stack 으로 통합 (proxy/console/docs/tunnel 분산 → frame·hive·blueprint·artemis·mysrt·vault·axelabs). cross-cutting infra (caddy/tunnels/docs/console) = `axelabs` stack. Portainer 12 stack → 7 stack. 본질·퀄리티·안전 우선. | 2026-05-22 |
| D-ops-21 | **`frame register-entity` 자동 chart seed** — entity 등록 시 표준 chart (KSME/KGAAP/KIFRS) 자동 apply. 이전엔 별도 `apply-chart` 누락 시 모든 분개가 `account_code not found` 로 실패하던 운영 함정 해소. | 2026-05-22 |
| D-ops-22 | **frame 펀드 도메인 지원** — `shared.entity` 에 `entity_kind` (corporate/kip/kvf) + `fund_meta` JSONB + `closed_at` 컬럼 ADD. `shared.entity_relationship` 확장 (`ownership_numerator/denominator/unit` — % 폐기, `kind` ENUM 에 `gp_managed_fund`/`lp_invested_fund` 추가). `shared.cross_journal_link` 신설 (AXEV↔fund mirror 분개 pair 무결성). `register-entity` CLI 에 `--kind`/`--fund-meta` flag. AXEV 창업기획자 산하 KIP/KVF 다수 결성 수용. 회계 원칙: AXEV↔fund = K-IFRS 1110 통제 미달 → 운용 관계 (parent-child 아님). `frame_meta` schema 신설 폐기 (기존 `shared` 확장이 자연 + 명명 충돌 회피). alembic `0008_shared` migration + frame-mcp blue/green rebuild. | 2026-05-22 |
| D-ops-23 | **frame RFC 9728 resource-level metadata path fix** — `/frame/mcp/.well-known/oauth-protected-resource` (application_id_uri 의 sub-path, RFC 9728 정확 path) 가 frame middleware 의 unauthenticated allowlist 누락으로 401 반환. claude.ai Connector / Anthropic MCP client 가 본 path fetch 시도 → OAuth challenge metadata 못 받음 → Reconnect silently 실패. `9b43845 feat(mcp): OAuth-RP dispatch + RFC 9728 endpoint` 시점부터 latent, D-ops-22 deploy (frame-mcp blue/green rebuild) 가 stored token invalidate 하면서 발현. fix: `http_server.py` 의 `_PUBLIC_PATHS` + `inner.router` 에 resource-level path 추가 (handler reuse `_oauth_protected_resource`). 양쪽 path (server-level `/frame/.well-known/...` + resource-level `/frame/mcp/.well-known/...`) 모두 200. commit `4f5dfcc`. | 2026-05-22 |
| D-ops-24 | **Vaultwarden SSO + Microsoft Entra ID — `email_verified` 면제** — Entra ID id_token 에 `email_verified` claim 부재 → Timshel fork 가 "Your provider does not send email verification status. ... `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION`" 오류로 거부. 첫 employee SSO 시도 (`taehun.kang@axellc.com`, 2026-05-22) 에서 발현. fix: `/Users/axe/.axe/vault/docker-compose.yml` 의 `axe-vaultwarden.environment` 에 `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"` 추가. SSO_AUTHORITY 가 single-tenant URL (`122fb574-...`) 이므로 외부 tenant 사용자 진입 불가 → 추가 검증 면제 안전. + Vaultwarden UI 함정 (이메일-first 기본 화면이 SSO Identifier 입력 칸 가림) 은 `/vault/#/sso` 직링크 안내 (troubleshooting.mdx). | 2026-05-22 |
| D-ops-25 | **MCP service 의 startup probe 강제** (D-bp-mcp-3 cross-cutting 일반화) — 모든 DB 종속 MCP service 의 Starlette lifespan 안에서 첫 traffic 받기 전 `SELECT 1` probe 실행. broken DB / malformed URL 시 lifespan fail → uvicorn 시작 실패 → healthcheck never green → `axe deploy SERVICE-mcp` blue/green swap 자동 거부 (broken container 가 active promote 못 됨). `/health/ready` endpoint 가 있어도 그건 request-time 검증이라 부팅 직후 broken DB 가 active 가능. **현재 상태**: blueprint-mcp ✅ 적용 ([PR #353](https://github.com/soohunkang/blueprint/pull/353)). **frame-mcp ✅ 적용 (2026-05-22, commit `3c7ca6a`)** — `src/frame/mcp/http_server.py` 의 outer Starlette lifespan 을 `@asynccontextmanager` wrapper 로 변경 (sync `Engine.begin()` + `SELECT 1` + log + `async with inner.router.lifespan_context(...)` bridge). startup log `"startup probe: DB reachable, schema accessible (D-ops-25)"` verified. hive-mcp **미적용** — frame pattern 1:1 미러 (5-10 분, `hive/src/hive/mcp/http_server.py`). mcp-server-checklist § 8 #16 으로 항구화. | 2026-05-22 |
| D-ops-26 | **Vaultwarden JIT user provisioning 활성** — D-ops-24 후속 incident. SSO 인증 통과 후 신규 user (`jinwoo.han@axellc.com`, 2026-05-22 10:01) 가 `/#/set-password-jit?identifier=AXE` 페이지에서 "An error has occurred. Failed to retrieve the invitation" 차단. vaultwarden log `Failed to retrieve the invitation` from `vaultwarden::api::core::accounts`. 원인: `SIGNUPS_ALLOWED=false` 가 JIT user 생성 차단 → invitation fallback 도 (`INVITATIONS_ALLOWED=false`) 없음 → 양쪽 모두 닫혀서 신규 employee 영구 차단. fix: `SIGNUPS_ALLOWED: "true"` 단독. `INVITATIONS_ALLOWED=false` 유지 (manual invitation flow 사용 안 함, JIT 로 통일). **D-ops-27 (operator 결정) 와 함께 읽을 것** — `SSO_ONLY` 는 false 유지 (emergency MP fallback 보존). | 2026-05-22 |
| D-ops-28 | **bw CLI 다운그레이드 2025.7.0 + 업스트림 vault migration 백로그** — 한진우/강태훈 AXE org 멤버 초대 자동화 시 brew 의 bw CLI 2026.4.1 이 `TypeError: Cannot read properties of null (reading 'toWrappedAccountCryptographicState')` 로 login 단계 crash. [bitwarden/clients #19413](https://github.com/bitwarden/clients/issues/19413) 와 동일 — CLI 2026.x 가 server ≥ 2026.x API 응답 필드 요구하는데 Timshel fork 의 최신 stable 은 `1.34.1-6` (upstream Vaultwarden 1.34.1, 2025-07-15 빌드). Timshel ghcr 에 1.34 이상 image 없음 (1.36.0 git tag 만 존재). fix: `brew uninstall bitwarden-cli && npm install -g @bitwarden/cli@2025.7.0` (Timshel 1.34.1-6 동시기). `/Users/axe/.axe/vault/invite-members.sh` 가 멤버 invite + auto-accept + confirm 한 번에 처리. **상위 결정 변경**: D-ops-11 의 "Timshel digest pin" 사유 (mainline Vaultwarden SSO 미지원) 가 2026-05 upstream 1.36.0 의 native SSO 도입으로 해소 → backlog `B-vault-upstream-migration` 등재 (dani-garcia/vaultwarden:1.36.0 으로 이전, schema migration + SSO 환경변수 매핑 + 데이터 보존 검증). 이전 완료 후 bw CLI 최신 line 복귀 가능. | 2026-05-22 |
| D-ops-27 | **Vaultwarden `SSO_ONLY=false` 유지 + `ORGANIZATION_INVITE_AUTO_ACCEPT=true`** (operator setup 마무리, 2026-05-22). (a) **SSO_ONLY=false**: D-ops-26 초안의 `SSO_ONLY=true` 폐기. Microsoft Entra 장애 / SSO 설정 오류 시 operator 가 master password 로 emergency 진입 가능해야 함 (`axe ship docs` 와 동일 원칙 — single-vendor lock-out 회피). trade-off: 외부에서 `axe.axelabs.ai/vault` 직접 password 가입 가능 (org collection 접근 X). mitigations: SSO_AUTHORITY single-tenant 가 외부 tenant SSO 진입 차단 + org member invite operator-only. **TODO** (backlog): 비정상 user row INSERT 감지 cron (`B-vault-anomaly-cron`). (b) **ORGANIZATION_INVITE_AUTO_ACCEPT=true**: org member 초대 시 사용자 측 "Accept invitation" 클릭 단계 자동 통과. operator 의 "Confirm" (org key 를 user public key 로 암호화 전달) 만 남음. 안전: invite 자체는 operator-only 이고 user pool 은 SSO 통과한 tenant user 만 가능. | 2026-05-22 |
| D-ops-29 | **Dual-identity for 강수훈 — `ai@axellc.com` (automation, AAD `7f110c52-...`) + `soohun.kang@axellc.com` (human Owner, AAD `e35e6778-...`)** — founding operator 가 두 identity 보유. 분리 원칙: (a) **`ai`** = 자동화 / bot / cron / agent identity. Graph token 발행, 직원 proactive DM, frame/hive agent run. 사람 손작업 X. (b) **`soohun.kang`** = 본인의 사람 작업 identity. Teams 응답, vault item 등재, blueprint admin UI. Vault AXE org 에서 둘 다 Owner + access_all=1 (DB UPDATE `users_organizations.atype=0, access_all=1` 적용 2026-05-22). Blueprint User.role 둘 다 admin. **이유**: bot 메시지가 human sender 로 표시되거나 vice versa 시 incident response 추적 혼란 (D-ops-23 의 mcp_client_invalid 디버깅 사례 참조). audit trail 명확화 + 신원 misuse 회피 + sender identity propagation 본질 원칙. | 2026-05-22 |
| D-ops-30 | **Bot proactive DM endpoint — `/api/admin/broadcast-dm`** (blueprint) — operator (ai@axellc.com identity) 가 직원 N명에게 동일 메시지 일괄 1:1 Teams DM. Auth: `Bearer <CRON_SECRET>`. Body: emails 배열 + text + contentType (text|html). 각 email 마다 (1) User.aadObjectId lookup → (2) Graph POST /chats oneOnOne (bot + user, idempotent — same pair 반환) → (3) POST /chats/CHAT_ID/messages. Pattern: `cron-failure-alert.ts:postAlertToAdmin` 재사용 (single → fan-out). 사용 사례: vault onboarding 안내, 플랫폼 공지, 운영자 broadcast. agent-context reply 는 `graph_chat_message_post` (Blueprint MCP) 그대로 사용. | 2026-05-22 |
| D-frame-lottecard-scraper | **롯데카드 거래내역 자체 스크래퍼 + 멀티카드 적재** (2026-05-29) — CODEF 등 외부 집계 API 미사용, 자격증명으로 롯데 법인 포털 직접 로그인하는 헤드풀 Playwright 스크래퍼 (`frame scrape <source>` 제네릭 + 롯데카드 첫 커넥터, host-only). 법인관리자 ID/PW (웹 보안키패드) → 승인내역 **개인정보 미포함(=이메일/인증 생략)** 신청 → 비동기 생성 → CP2 .xls 다운로드 → ingest. 법인전체 export 가 법인의 모든 카드를 담으므로 `ingest_lotte_card` 를 **행별 계정 resolve** 로 수정 (마스킹 `5105-****-****-*042` ↔ 기존 실번호 계정 `5105-5400-0199-9042` 와 와일드카드 매칭하여 링크, 실번호 보존; 신규 카드는 새 계정). 비밀 = `frame/axe/lotte-portal-{username,password}` (vault, host-only — MCP 컨테이너 제외). 스케줄은 DB-driven ([D-frame-scrape-schedule](/ops/decisions)). 함정: axec id=3 의 기존 701행이 혼합 카드 (과거 첫-행-버그) — 별도 정합성 정리 대상. | 2026-05-29 |
| D-frame-scrape-schedule | **스크래퍼 주기 = DB(MCP 조정) + launchd 단순 tick** (2026-05-29) — 주기를 plist 하드코딩하지 않고 `shared.scrape_schedule`(KST cron) 에 두고 MCP `set_scrape_schedule`(raw cron 또는 daily/weekly/monthly 프리셋) 로 조정. MCP 컨테이너는 호스트 launchd 를 못 건드리므로 launchd 는 `com.frame.scrape-tick`(08–21시 매시 :15) 단순 tick → `frame scrape-due` 가 croniter 로 due 판정해 해당 source 만 실행 + last_run/next_due 갱신. cron 은 KST (anchor=last_run else created_at → 갓 만든 weekly 는 첫 진짜 fire 에 실행, 첫 틱 즉발 X). croniter+Playwright=host-only(`schedule.py`), cron 컴파일=pure(`cron.py`, 컨테이너 공용). 마이그레이션 `0009_shared`. 신규 MCP 도구 3개 → frame-mcp rebuild 필요. **SLA(다운타임 catch-up)**: 놓친 실행은 복구 후 1회 따라잡기 + look-back 을 now−last_run(상한 365일)까지 확장해 그 기간 backfill (row_hash dedup, 손실 0), `RunAtLoad` 부팅/wake catch-up, MCP `overdue` 가시화. seed: lottecard/axec weekly Mon 08:10. | 2026-05-29 |
| D-ops-33 | **`axe vault bootstrap {customer}` CLI 신설** — D-ops-24/26/27 4-key 적용을 코드로 항구화. customer-onboarding.mdx 의 D+1 수동 단계를 1 명령으로 축소. 동작: SSH (or local for axe) 로 `/Users/{ssh_user}/.axe/vault/docker-compose.yml` 읽음 → 4 key 진단 (idempotent) → 누락만 patch (anchor: `SSO_SIGNUPS_MATCH_EMAIL`) → force-recreate `axe-vaultwarden`. Default = dry-run, `--apply` 로 실 패치. **검증**: `axe vault bootstrap axe` (이미 적용 — "bootstrap 불필요" 정확 detect) + `axe vault bootstrap realchoice` (file 부재 시 깔끔한 에러). 후속 ([B-onboard-cli-vault-bootstrap](/ops/backlog)): Vault Organization 자동 생성 + 첫 admin invite (현재 web UI 수동). | 2026-05-22 |
| D-ops-31 | **axep entity 신설 (액스파트너스 유한책임회사)** — axe customer 의 3번째 entity 추가 완료 (2026-05-22). frame `register-entity --id axep --kind corporate --accounting-standard ksme` (chart auto-seed 54/59 accounts, D-ops-21) + hive `register-entity --id axep` (frame mirror). `customers.yaml`: entities 배열 `["axec","axev","axep"]` + frame/hive PII passphrase secret 매니페스트 2개 (`frame/axe/pii-passphrase-axep`, `hive/axe/pii-passphrase-axep`) 추가. user_entity_map: ai/cfo/soohun 만 `["axev","axec","axep"]` (axep 참여), taehun/jinwoo 은 axep 제외 유지. **Deploy 완료**: PII passphrase 2개 vault push (`axe secret push`) + frame blue/green swap (active=green:3711, blue:3710 next passive) + hive sequential force-recreate (green → 6s → blue). axec/axev 영향 0 (PII passphrase entity별 분리 + lazy-load). 자동화: `/Users/axe/.axe/vault/deploy-axep.sh`. **부수 발견 함정**: `axe secret push` 가 `BW_SESSION` env var 무시 + macOS Keychain (`axe.vault.session` / `ai@axellc.com`) 만 읽음 → 자동화 시 `security add-generic-password -U` 로 keychain 갱신 단계 필수. | 2026-05-22 |
| D-ops-34 | **Onboard 1-input 모델 — Phase A (vault unlock = 세션 prerequisite) + Phase B (umbrella 명령 1 줄)** — 신규 customer (realchoice 등) 배포 시 운영자 D-day 입력 = **axe 명령 1 줄**. 가정: vault 가 미리 unlock 돼 있어야 함 (`bw unlock --raw` → Keychain `axe.vault.session` cache, 8시간). 이후 모든 `axe secret`/`axe onboard`/`axe deploy` 가 keychain BW_SESSION 자동 사용 — D-day 추가 prompt 0. **Phase B umbrella** = `axe deploy customer {customer} --from-pack pack.json --apply` ([B-onboard-umbrella](/ops/backlog)) — 내부에서 ingest + onboard (cloudflared+frame) + deploy blueprint + deploy hive 순차. **거부**: cron 기반 `bw unlock` keep-alive (vault 상시 unlocked = 머신 침해 시 전체 노출 = blast radius 큼). 권장 모델 = "출근 시 비번 1 회 입력 → 하루 1 입력" 보안/편의 최적점. customer IT 측 mirror = `az login` 1 회 + `axelabs-bootstrap.sh` 1 줄 (docs.axelabs.ai 만으로 자력 — [D-onboard-bootstrap-publish](/ops/decisions), [/partner/registration §Option A](/partner/registration#option-a--cli-1-줄-권장)). | 2026-05-23 |
| D-ops-32 | **Vault collection 구조 v1 — 6 collection** (D-ops-9/27/29 종합 설계) — 기존 4 collection (Default empty, frame-jwt-axec/axev D-ops-14 잔재 each 1 item, frame-jwt-operators empty) → 6 collection: (1) **Platform — Service Secrets** (37 customers.yaml secrets, ai+soohun only) (2) **Platform — Infrastructure** (Cloudflare API, vault ADMIN_TOKEN raw, GitHub org admin, DNS, cert; ai+soohun only) (3) **AXEC** (4명 RW — KB/홈택스/Azure axec/세무사 access) (4) **AXEV** (4명 RW — KB/KSD/금감원/GP-LP portal/investee data room) (5) **AXEP** (ai+soohun only — GP 단독 출자/운영) (6) **Shared Tools** (4명 RW — Notion/Slack/공통 SaaS/도메인 admin/메일 alias). 기존 frame-jwt-axec + frame-jwt-axev 의 2 item → Platform — Service Secrets 로 이동. 기존 Default + frame-jwt-operators 삭제. 구체 마이그레이션은 운영자 web UI 권장 (SQL/bw 직접 manipulation 은 Vaultwarden cache 충돌 위험). 외부 인력 (회계사/LP) 합류 시점에 entity-level read-only 분리 검토. **Progress (2026-05-26)**: 6 collection 전부 신설 ✅. AXEC (`5b13e7e4...`) + AXEV (`6eb223cb...`) + AXEP (`89de0ab9...`) + Platform — Service Secrets (`1d794d29...`) + Platform — Infrastructure (`50f2705f...`) + Shared Tools (`68197247...`). 권한 부여: AXEC/AXEV/Shared Tools 4명 RW (ai+soohun manage=true / taehun+jinwoo manage=false), AXEP + Platform 둘은 ai+soohun only. `bw create org-collection` 자동화 검증 — D-ops-32 가 명시한 "운영자 web UI 권장" 은 완전 우회 가능. **영향 평가**: axe CLI `_vault_get` 가 name 기반 (`bw get password <name>`), service deploy 가 `.env` 에 inject — collection 추가/이동/삭제로 MCP connector 깨지지 않음 (running connector 영향 0, 다음 deploy 시 lookup 도 무관). **AXE org role 확인**: ai@ + soohun.kang 모두 type=0 (Owner), taehun + jinwoo type=2 (User). **남은 작업 (별건)**: (a) 운영자 ai@ 의 personal vault 의 service secrets (axe secret list 의 ~37 path) 를 Platform — Service Secrets 로 이전 — 현재 ai@ only, bus factor 위험. (b) Default 의 3 items (`axe-macmini local: soohun.kang`, `axe-macmini local: taehun.kang`, `github PAT: ai@axellc.com`) 검토 — github PAT 은 Platform — Infrastructure, 나머지 2 은 personal vault 가 적절. (c) frame-jwt-axec/axev/operators 의 2 item (`taehun-kang-axec-2026-05-17`, `ai-operator-2026-05-16`) 검토 후 적절한 신설 collection 으로 이동. (d) 옛 4 collection (Default + frame-jwt-*) 삭제. → 신규 backlog [B-vault-collection-migration-v1](/ops/backlog). **2026-05-26 권한 정정 fix 적용 완료**: `bw create org-collection` 의 users 배열 처리 server-side 함정 (Owner skip + manage=0 강제 — 자세한 root cause = [B-vault-org-perm-3-quirks](/ops/backlog)) 으로 6 collection 모두 ai+soohun 권한 누락 또는 partial 이었음. SQLite 직접 `users_collections` 일괄 INSERT/UPDATE + ai+soohun-only collection 의 taehun/jinwoo entry DELETE 로 본 결정의 권한 모델 (4명 RW vs ai+soohun only) 그대로 정합 복원. cipher delete/move 는 `*/admin` HTTP endpoint 직접 호출이 정공법 (bw CLI 의 cipher.permissions.delete client-check 우회). | 2026-05-22 |
| D-nemotron-1 | **`/services/nemotron-personas` 카탈로그 등재 (placeholder)** — 트루비아 측 기존 자산 (Docker SSE :8771, NVIDIA Nemotron-Personas 데이터셋 1M+ 페르소나 풀) 이 docs 미등재였던 갭 해소. 보고서 Q5 confirm 후속 (2026-05-23 RE^2). 본격 본문은 D+14 (2026-06-15) 트루비아 측 라이선스/origin 회신 후. 라이선스 cross-customer OK 면 공식 카탈로그 + Blueprint MCP registry, X 면 realchoice 전용 (`customers.realchoice.private_services[]` 신설 검토). 현 시점 docs 노출은 가시성 + 운영자 SPOF 회피 목적. | 2026-05-23 |
| D-magnet-tenant-map-1 | **`customers.yaml > customers.{customer}.service_tenant_map` 신설** — magnet 의 service-internal RLS `tenant_id` (integer) 와 AXE customer ID (string) 의 매핑 SSOT. `MAGNET_TENANT_ID=1` (realchoice) 유지, 향후 axe 가 magnet 사용 시 `tenant_id=2` 부여로 충돌 회피. 트루비아 측 보고서 Q6 confirm 후속 (2026-05-23 RE^2). `/services/magnet#tenant-id-mapping` 본문. 향후 stream / 기타 service-internal id 도 동일 패턴 확장. axe ship 이 manifest 에서 자동 주입은 `B-magnet-tenant-env-injection` 후속. | 2026-05-23 |
| D-onboard-bootstrap-publish | **`axelabs-bootstrap.sh` 를 docs.axelabs.ai 의 raw 로 노출** — 신규 customer IT 가 docs link 만 받고 자력 완료 가능한 상태 (별도 안전채널 메시지 + `realchoice_entra_id_setup_v4.md` 의존 폐기). `/Users/axe/.axe/bootstrap/axelabs-bootstrap.sh` → `/Users/axe/axelabs-docs/public/axelabs-bootstrap.sh` 복사 (17749 bytes, SHA-256 `7d2d607136e5387c6c9368bf8529d4ec0e219f8eb7bab45b57590a00838210cc`). partner/registration §Option A 가 docs 안에 다운로드+검증+실행+회신을 모두 포함하도록 재작성. 함께 신설: partner/macmini-prep.mdx (Tailscale 가입 + SSH key 회신 + 절전 OFF + Docker 6 단계) + partner/domain-prep §A (axelabs.ai zone = 운영자 책임, 귀사 IT 1 분 한 줄 전달) §B (귀사 corporate domain TXT 가이드) + partner/handoff JSON pack 양식 (`axelabs-bootstrap/v1` schema) + partner/index 의 4-step 흐름. customers.yaml realchoice.sso.apps 에 blueprint 슬롯 사전 추가 (bootstrap.sh 의 apps.blueprint 출력 흡수 대비). 운영자 측 1-shot umbrella ([D-ops-34](/ops/decisions)) 는 여전히 backlog — 운영자 D-day 명령 수 5→1 줄이는 작업은 별도 추진. customer-facing 의 docs-only 자력 완료는 본 결정으로 달성. | 2026-05-23 |
| D-ops-41 | **SSH client-side automation: NSSM/서비스 폐기, user-context Scheduled Task + VBS wrapper 채택** — `/onboard/ssh-access` 실전 셋업 (Soohun Kang Windows 11, 2026-05-27) 도중 6 함정 발견 후속. (1) cloudflared TCP forward 와 token renewal 모두 **user-context Scheduled Task** 로 통일. TCP forward 는 **VBScript wrapper 호스팅** 으로 0-flash hidden + 무한 재시작 보장 (`wscript.exe` + `Do ... sh.Run ..., 0, True; WScript.Sleep 5000; Loop`). Token renewal 은 **self-rescheduling PS1** — JWT `exp` claim 파싱 후 `exp - 5min` 에 한 번만 fire (24h 주기 task fire 2~3회), `Set-ScheduledTask` 가 자기 trigger 재예약. (2) **거부된 대안**: (a) NSSM/SYSTEM 서비스화 — JWT 토큰 user-scoped (`%USERPROFILE%\.cloudflared\`) vs SYSTEM 의 `%SystemRoot%\System32\config\systemprofile\.cloudflared\` 격리 → 무한 `failed to acquire app token lock` 루프 + SYSTEM 의 desktop session 부재로 자체 login 도 무한 "Waiting for login..." (함정 #10). (b) NSSM 사용자 계정 실행 — 패스워드 평문 저장 + Microsoft 계정/Windows Hello 사용자 UX 저하 + 계정 패스워드 변경 시 서비스 정지. (c) Cloudflare Service Token — [D-ops-29](/ops/decisions) dual identity audit 와 충돌 (SSO email log 없어짐). (d) Access app `session_duration` 30d 연장 — 갱신 빈도만 줄어들 뿐 자동화는 별개. (3) **PowerShell `-WindowStyle Hidden` 폐기** (daemon 류) — Windows 가 hidden flag 적용 전 수십 ms 콘솔 노출 → 매 task fire 마다 깜빡임 잔상 (함정 #13). `wscript.exe` 호스팅이 0-flash. (4) **Task `-RestartCount` 의존성 0** — FAILURE (non-zero exit) 에만 발동이라 cloudflared 정상 종료 (exit 0) 시 silent 중단 → 며칠 후 SSH 끊김 (함정 #14). VBS wrapper 안의 `Do ... Loop` 가 어떤 종료 코드든 5초 뒤 재기동. (5) **Renewal task `-RunLevel Highest` 필수** (함정 #11) — `Set-ScheduledTask` 는 elevated 권한 필요, Interactive 만으로 `Access is denied`. (6) **SSH use case 의 active logon session 전제** — "logon 전에도 살아있음" 이 필요 없음 → user-context Scheduled Task 가 NSSM 보다 깔끔 (패스워드 저장 0 / 토큰 캐시 자동 공유 / 본인 끌 UI 0 / 가시적 창 0). **결과 = 사람 클릭 0회 조건부** — Microsoft "로그인 상태를 유지" sticky session 켜져 있으면 renewal 시 SSO 자동 통과. Entra conditional access 가 sticky 차단하면 갱신 시점 1회 클릭 필요 (정책 영역, client 우회 불가). **검증 환경**: Windows 11 + cloudflared 2026.5.1 + OpenSSH for Windows 9.5p2 / LibreSSL 3.8.2. **참조**: [/onboard/ssh-access § TCP forward 자동화](/onboard/ssh-access#tcp-forward-자동화-windows-user-context-scheduled-task--vbs-wrapper) / [§ Token 자동 갱신](/onboard/ssh-access#token-자동-갱신-windows) / [§ 함정 #9~#14](/onboard/ssh-access#함정-정리). | 2026-05-27 |
| D-ops-40 | **axe.3 vault release plan — 2 patch (Owner skip + cipher.permissions) + KDF rotation procedure + `axelabs-ai/vault` GHA pipeline 구축** — [D-ops-37](/ops/decisions) axe.2 deploy 후 발견된 [B-vault-org-perm-3-quirks](/ops/backlog) (3 함정) + [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) 의 모든 근본 진단 (2026-05-26 timshel/vaultwarden source clone read-only 진단). **Patch A — 함정 1 (Owner skip on collection user save)**: `src/api/core/organizations.rs` 의 **2곳 동일 fix** — `post_organization_collections` (line 522-524) + `post_organization_collection_update` (line 685-687) 에서 `if member.access_all { continue; }` 3 라인 제거. 결과 = Owner role 도 `CollectionUser::save` 명시 entry 생성 → 권한 체크 정합 + cipher.permissions.delete 계산 정상. **Patch B — 함정 3 (cipher.permissions field missing)**: `src/db/models/cipher.rs::to_json` 함수 line ~239 부근 `"edit"` / `"viewPassword"` 옆에 `"permissions": {"response": null, "delete": <bool>, "restore": <bool>}` 추가. `<bool>` 계산 = `Membership::find_by_user_and_org(user_uuid, org_uuid).await` 결과의 `atype <= Admin` OR `cipher.user_uuid == Some(user_uuid)` OR (`get_access_restrictions().manage == true`). Bitwarden mainline schema backport. **Patch C — 함정 2 (cipher edit collectionIds silent partial-revert)**: **patch 안 함** — vaultwarden bug 아닌 mainline design (collectionIds 변경은 `POST /ciphers/{id}/collections` 별도 endpoint). 운영 룰: bw CLI 의 `bw edit item` 으로 collectionIds 변경 불가, 대신 `bw move` 또는 `/admin` endpoint 직접 호출 ([B-vault-org-perm-3-quirks](/ops/backlog) 의 운영 임시 룰 영구). **Patch D — SSO→MP wrapped MP**: **patch 안 함** — axe.2 의 response shape backport 가 이미 충분. 기존 user (axe 측 4명) 의 user.akey 가 옛 KDF/wrapping schema 로 생성된 게 원인 (realchoice 측 신규 가입 user 는 axe.2 적용 후라 새 schema, 정상). **Fix = KDF rotation runbook** (운영자 셀프, patch 영역 외): 각 user 가 MP 단독 로그인 → Settings → Account → Security → Master password change (same value OK) + KDF type PBKDF2 → Argon2id → save → vault items re-encrypt → logout → SSO→MP 정상. axe 측 4명 (ai/soohun/taehun/jinwoo) 차례로. realchoice 측 영향 없음. **Build pipeline (axelabs-ai/vault repo, 현재 빈 상태)**: `build/build.sh` (clone timshel `1.34.1-6` tag + `patches/*.patch` 일괄 git apply + `docker buildx --platform linux/amd64,linux/arm64 --push ghcr.io/axelabs-ai/vault:<tag>`) + `.github/workflows/build.yml` (push.branches=main 자동 빌드 `main-<sha7>` rolling tag + `workflow_dispatch` input tag 로 release 빌드 `1.34.1-6-axe.3`) + `build/patches/0001..0004.patch` (axe.2 의 prelogin/password + AccountKeys + axe.3 의 organizations Owner-skip + cipher permissions). **Deploy 흐름**: (1) `axelabs-ai/vault` repo 의 build/ + workflows/ + patches/ commit. (2) workflow_dispatch → GHCR push. (3) `axe-macmini`: `docker compose pull vaultwarden && docker compose up -d` (compose.yml image 라인 = `ghcr.io/axelabs-ai/vault@sha256:<new-digest>` 로 핀, [D-ops-37](/ops/decisions) 의 axe.2 ImageID 주석 → axe.3 digest 로 갱신, 이전 digest rollback 주석 보존). (4) `realchoice-macmini`: 동일 pull + up (customer self-deploy, [D-ops-customer-sovereignty](/ops/backlog) 원칙). (5) axe + realchoice 양쪽 검증 = collection 생성 (Owner entry 명시 확인) + cipher delete (bw CLI 정상 동작 확인) + SSO→MP (KDF rotation 후 검증). **현금 비용 0** (GHCR + GHA runner 무료 한도 안, image 460MB, build ~15분/회). **운영자 시간 5~9h** (patch 작성 1h + build pipeline 1~2h + 빌드/검증 1h + KDF rotation 4명 30분 + Truvia 안내 30분). **AGPL 라이선스 고려**: Vaultwarden = AGPL-3.0. fork 의 patch 배포 시 source 공개 의무 — `axelabs-ai/vault` GHCR push public 가능 + source 공개 같이. private 유지 원하면 patch 만 사적 운영 (배포 안 함, GHCR private + 본인 macmini 만 pull). 본 결정 = **public 모드** (source 공개 = patch 공개, GHCR public, 라이선스 정합 + 무료 GitHub plan 한도 무관). **Progress (2026-05-26 KST, ~3.5h 실 진행)**: (i) `axelabs-ai/vault` repo PUBLIC 전환 ✅ (조직 정책상 GHCR package 는 PRIVATE 유지). (ii) realchoice-macmini 의 기존 build pipeline (build/build.sh + Dockerfile + README + workflow + 2 axe.2 patches) 그대로 vendor + axe.3 patch 2개 추가 ✅: **patch 0003** `src/api/core/organizations.rs` line 522 + 600 + 685 의 `if member.access_all { continue; }` 3 라인 제거 (plan 의 "2곳" 외 line 600 `post_bulk_access_collections` 추가 발견 — 동일 root cause, 3곳 모두 patch). **patch 0004** `src/db/models/cipher.rs::to_json` line 374 (실 line, plan 의 ~239 와 다름) 의 `edit/viewPassword` 옆에 `permissions: {response,delete,restore}` 추가 + line 161 의 `_` → `manage` 로 바꿔 `get_access_restrictions` 결과 reuse (DB round-trip 절약). `can_delete` = collection manage flag OR org Owner/Admin (`atype <= 1`) — `Membership::find_by_user_and_org` 한 번 호출. (iii) 로컬 docker buildx (arm64, --load) 검증 ✅ — 5분 (M-series + cache), Rust 컴파일 정합 확인 (image `axelabs-ai/vault:axe.3-localtest` ImageID `sha256:e1ac1617...`). (iv) commit `799015b` push to axelabs-ai/vault main → GHA `build-vault-image` 자동 트리거 → 13분 multi-arch build → ghcr.io/axelabs-ai/vault:main-799015b push ✅. workflow_dispatch 는 axe-labs-ai PAT 의 actions scope 부족으로 403 — 대신 `docker buildx imagetools create` 로 `1.34.1-6-axe.3` alias 발행 (rebuild 없이, 3초). **manifest list digest** `sha256:a26208a0794acbc9a2807379ffba33c7478dbe8d41daed24893f7916a55aeada` (arm64 `sha256:d97a6ed...`, amd64 `sha256:402eeac...`). (v) GHCR auth: PAT (read+write:packages+workflow) 발급 → **AXE vault `Platform — Service Secrets / ghcr-axelabs-ai-pull-pat`** 저장 ([D-ops-ops-17](/ops/decisions) SoT 원칙 — keychain 안 씀). docker login 패턴: `bw get password ghcr-axelabs-ai-pull-pat \| docker login ghcr.io -u axe-labs-ai --password-stdin`. (vi) axe-macmini deploy: data tgz + sqlite 백업 (`data-pre-axe.3-20260526-131744.tgz`, `db-pre-axe.3-20260526-131744.sqlite3`) → `docker compose pull && up -d` → 60s healthy. compose image 라인 = `ghcr.io/axelabs-ai/vault@sha256:a26208a...`. (vii) **검증 3건 in-production** (13:19 KST): **VERIFY 1** = `bw create org-collection` (test 용) → SQLite `users_collections` 에 `ai@axellc.com\|0\|0\|1` row 명시 insert ✅ (axe.2 = zero rows). **VERIFY 2** = raw `GET /api/sync` → org cipher 의 `permissions: {delete:true,restore:true,response:null}` 정확 emit ✅ (bw CLI 2025.7.0 출력은 `null` — 옛 client 가 unknown field 파싱 못해 표시 안 됨, 새 client ≥2026.4 는 정상 읽음). **VERIFY 3** = `bw delete item` (test cipher) rc=0 ✅ (cleanup 후). (viii) external `https://axe.axelabs.ai/vault/alive` HTTP 200 (0.28s). (ix) [B-vault-fork-build-pipeline](/ops/backlog) ✅, [B-vault-org-perm-3-quirks](/ops/backlog) ✅. (x) **잔여 = KDF rotation 4명 (ai/soohun/taehun/jinwoo)** — 운영자 본인 MP 입력 필수라 자동화 불가, [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) runbook 참조. realchoice 안내 별도 (customer-sovereignty — 직접 pull, vault 에서 PAT 받아감). **(xi) ai@ KDF rotation 검증 완료** (Master password change + rotate encryption key 만으로 SSO→MP unlock 정상 — KDF 변경 없이 akey 재wrap 만으로 충분 확인). **(xii) post-deploy 정책 layer 박제** ([/architecture/vault-policies](/architecture/vault-policies) 신설): **(a)** server env `SSO_AUTH_ONLY_NOT_SESSION=true` 적용 — SSO 가 인증만, session lifecycle = Vaultwarden 자체 30일 idle refresh token. trade-off = Entra 비활성/제명 ≤30일 lag (AXE 4명 규모 OK), benefit = SSO+MP 재입력 월 ~1회. **(b)** Org Policies 4종 API 적용 (Owner ai@ token 으로 PUT) — MasterPassword(min 12, complexity 1), PasswordGenerator(len 20), SingleOrg, PersonalOwnership. **(c)** MaximumVaultTimeout 시도 HTTP 400 — Timshel source 의 `// MaximumVaultTimeout = 9, // Not supported (Not AGPLv3 Licensed)` 확인. Bitwarden commercial license 라 Vaultwarden 영구 미지원, `SSO_AUTH_ONLY_NOT_SESSION` 이 가용 영역 안 best 대체. 3 layer 모델 (server env + Org Policies + per-client preferences) 통합 박제. **(xiii) 4명 KDF rotation 전부 완료 → D-ops-40 전체 종결** (2026-06-04): ai (5/27) → soohun → taehun (5/29) → jinwoo (6/4) 순서. **본질 발견 = KDF type dropdown 변경 불필요** — Master password change + ☑ "Also rotate my account's encryption key" 체크박스 만으로 `user.akey` 재wrap 충분 (plan 의 "KDF PBKDF2 → Argon2id" 보다 간소). DB: ai 는 Argon2id (Phase B 까지 진행), soohun/taehun/jinwoo 는 PBKDF2 유지 — **kdf_type 안 바뀌어도 akey 재wrap 만으로 SSO→MP fix 동작 확인**. 4명 모두 SSO→MP unlock 정상. jinwoo last_login 5/23→6/4 점프 = 완료 신호 + 운영자 구두 확인. 운영 도구 부산물: [/onboard/vault-setup](/onboard/vault-setup) playbook (taehun 피드백 6건 반영) + [/ops/runbook/operator-broadcast](/ops/runbook/operator-broadcast) (Teams DM 1:N) + [/architecture/vault-policies](/architecture/vault-policies). [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) ✅. **D-ops-40 전 작업 (build pipeline + axe.3 patches + GHCR + deploy + 검증 3건 + 정책 layer + 4명 rotation) 종결.** | 2026-05-26 |
| D-ops-39 | **무료 Universal SSL 의 1-level wildcard 한계 = flat-hostname 컨벤션 강제 (ACM 유료 회피)** — Cloudflare 무료 plan 의 `*.axelabs.ai` Universal SSL cert 는 1단 서브도메인만 cover. 2단 (`ssh.axe.axelabs.ai`) 은 SAN 미일치 → edge default cert fallback → 클라이언트 `tls: handshake failure` (Windows: `SEC_E_ILLEGAL_MESSAGE 0x80090326`, macOS: `sslv3 alert handshake failure`). 강태훈 Windows 의 `cloudflared access login https://ssh.axe.axelabs.ai` (2026-05-25) 에서 발현, MAX agent 진단 (axelabs.ai chat) → 운영자 forward → 본 결정. **Fix**: 신규 1단 hostname `ssh-axe.axelabs.ai` (DNS CNAME → 동일 tunnel `d8efecdd`, ingress 규칙 clone, Access app `b903d8cd` self_hosted_domains 추가). 검증: `curl -v https://ssh-axe.axelabs.ai` → `*.axelabs.ai` cert SAN 매치 + Access 302 OK. 옛 `ssh.axe.axelabs.ai` 와 vestigial `*.axe.axelabs.ai` 와일드카드 (이번 한계 violation) 는 [B-ssh-axe-flat-hostname-sunset](/ops/backlog) 로 grace period 후 일괄 삭제. **거부된 대안**: (a) Cloudflare Advanced Certificate Manager $10/cert/월 — 1개 hostname 위해 유료 전환 부당. (b) `axe.axelabs.ai` 별도 zone 등록 — NS delegation/zone 이원화 overhead 과잉. (c) 강태훈 Tailscale 우회 — 일반 직원 권한 범위 외 + 권한 확장 정책 필요. (d) 클라이언트 cert 검증 우회 — 보안 위반 + 다음 직원도 같은 함정 재현. **컨벤션**: HTTPS 노출되는 모든 hostname 은 `{name}.axelabs.ai` 1단 (`ssh-axe`, `docs-axe` 등 flat). sub-context 필요하면 path (`axe.axelabs.ai/frame`). 본 룰 [/architecture/domains#함정--universal-ssl-wildcard-의-1-level-한계-d-ops-39](/architecture/domains#함정--universal-ssl-wildcard-의-1-level-한계-d-ops-39). | 2026-05-26 |
| D-ops-38 | **외부 service 2FA 는 vault item TOTP 필드, AXE 내부 vault 계정 자체 2FA skip (Entra SSO 가 MFA 역할)** — AXE 가 사용하는 외부 services (KB/홈택스/AWS/GitHub/카드사/세무사 SaaS/etc.) 의 2FA 코드 는 Vaultwarden item 의 `login.totp` 필드 (Vaultwarden 무료 지원, Bitwarden premium 의 self-host 등가) 에 저장 → vault unlock 시점에 client (web/ext/native) 가 자동 6-digit 생성. **AXE 내부 vault 자체 user 2FA 는 활성 안 함** — Microsoft Entra SSO 가 이미 MFA 역할 (Entra ID 의 conditional access + Authenticator app 정책). Vault 의 SSO→MP unlock 흐름이 동작하면 (현 [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) 해소 후) 그 자체가 multi-layer. **AI agent 자동화 활용**: Claude Code / axe CLI / 기타 운영 자동화가 외부 service 로그인 시 TOTP 필요한 경우 `bw get totp <item-name>` 또는 향후 `axe secret totp <name>` ([B-axe-secret-totp-cli](/ops/backlog)) 으로 vault 에서 자동 조달 — 운영자 phone 의존 제거 + bus factor 0. **운영 룰**: 외부 service 2FA 등록 시점에 (a) phone Authenticator 앱은 사용 안 함, (b) QR/secret/`otpauth://` URI 를 vault item 의 TOTP 필드에 직접 저장, (c) phone 분실/교체 시 손실 없음. **trade-off**: vault 가 단일 trust boundary — 뚫리면 외부 service 2FA 도 같이 뚫림. 따라서 vault 의 SSO/MP/(향후) 2FA layer 가 더 중요해짐. AXE 내부 vault 계정 자체 2FA skip 결정은 **Entra SSO 가 살아있을 때** 만 유효 — SSO 가 깨진 현재 상태 ([B-vault-axe.2-sso-mp-incomplete](/ops/backlog)) 에서는 MP single-factor 단계라 임시 위험 가시. SSO 흐름 복원 시점에 자동 mitigation. | 2026-05-26 |
| D-ops-37 | **AXE-local Vaultwarden fork build — `ghcr.io/axelabs-ai/vault@sha256:a26208a0794acbc9a2807379ffba33c7478dbe8d41daed24893f7916a55aeada` (axe.3, 2026-05-26)** — Bitwarden client >= 2026.4 (Chrome extension + bw CLI) 와 Timshel 1.34.1-6 fork 사이 두 protocol 불일치 영구 fix. (1) Bitwarden client 가 `/accounts/prelogin/password` 로 split — Timshel 은 legacy `/accounts/prelogin` 만 노출 → 404 → 로그인 시작 불가. (2) `/identity/connect/token` 응답에 새 wrapped-variant 필드 (`AccountKeys` / `MasterPasswordUnlock`) 부재 → "toWrappedAccountCryptographicState" throw → unlock 실패. 패치 2개 모두 dani-garcia/vaultwarden mainline 에서 backport. realchoice tenant 가 2026-05-25 자체 build & deploy → axe-macmini 는 본 일 (2026-05-26) realchoice-macmini local image 를 docker save/load 로 import → `axe-vaultwarden` recreate (ImageID `sha256:11536845...`, arm64). prelogin/password endpoint 200 OK 회귀 검증 완료 (이전 404). **2026-05-26 추가 (axe.3 ramp, [D-ops-40](/ops/decisions))**: axelabs-ai/vault GHA pipeline 정식 구축 + axe.3 patch 2개 추가 (organizations Owner-skip + cipher.permissions) → image 라인 = `ghcr.io/axelabs-ai/vault@sha256:a26208a...` (manifest list, multi-arch). [D-ops-11](/ops/decisions) immutable digest 핀 정합 복원. **rollback (axe.2)**: 로컬 tag `axelabs-ai/vault:1.34.1-6-axe.2`, ImageID `sha256:11536845...`. **rollback (pre-axe.2)**: `ghcr.io/timshel/vaultwarden@sha256:a5d5ed0366abd84cc7443a79e52ffe4774671648dca5e1a5412fd91b77d4f692`. **follow-up**: (a) ~~`axelabs-ai/vault` 에 build/patches/ + GHA workflow 실 셋업~~ ✅ ([B-vault-fork-build-pipeline](/ops/backlog) Done). (b) 패치 2개 Timshel upstream PR 제출 ([B-vault-axe.2-patches-upstream-pr](/ops/backlog)). [B-vault-d-day-traps-2026-05-25 #12](/ops/backlog) 의 client-side bw 2025.7.0 pin workaround 와 별도 — 본 결정은 server-side 영구 fix. **vault-next 18-24개월 roadmap 의 bridge** (별도). | 2026-05-26 |
| D-ops-35 | **`axe deploy hive {customer}` subcommand 신설** — frame blue/green 패턴 1:1 mirror. `cmd_deploy_hive` + `_hive_active_color` + `_hive_port` 헬퍼 + `HIVE_*` 상수 (compose, proxy=`axe-hive-proxy`, networks=`["hive_default","artemis_default"]`, alias=`hive-mcp`, drain=5s). 8-step: build passive → up -d → /health/ready 200 wait → add alias (양쪽 network) → caddy reload → edge verify (200/401 둘 다 정상 — JWTAuthMiddleware) → drain 5s → 옛 active alias 제거. argparse choices 에 `hive` 추가, dispatcher 분기. **검증**: `axe deploy hive axe --apply` 실 swap (blue:3810 → green:3811 active, edge `axe.axelabs.ai/hive/health: 200`, 무중단). hive 가 `axe ship hive` 의 manual_hint 만 남아있던 격차 해소. realchoice 6/1 deploy 가 진정 1-shot 가능 — `axe deploy customer realchoice --from-pack ...` umbrella ([D-ops-34](/ops/decisions)) 의 hive 단계도 자동. customer-onboarding.mdx 의 step 4 manual ssh 폐기. | 2026-05-23 |
| D-ksme-1 | **KSME seed 판관비 10개 보강** — 5210 급여 / 5211 임원급여 / 5212 잡급 / 5213 퇴직급여 / 5214 복리후생비_4대보험 / 5215 통신비 / 5216 광고선전비 / 5217 도서인쇄비 / 5218 교육훈련비 / 5219 감가상각비. 한국 법인 필수인 급여 계정 자체가 없던 본질적 결손. | 2026-05-22 |
| D-frame-3 | **`cash_flow_statement` 신규 계정 fallback 분류 (type + code prefix) — 명시적 dict 우선, 미매핑 계정만 규칙 적용** — CF 분류가 hardcoded dict (`INVESTING_ACCOUNTS`/`FINANCING_ACCOUNTS`/`OPERATING_*`) 라 신규 계정(1302 투자조합출자금·1303 매도가능증권·2104 주임종단기차입금)이 `unclassified_accounts` 로 남아 `reconciliation_diff≠0` → `verified=false`. Fix (`ops/statements.py`): 미분류 계정에 한해 fallback rule — **1300번대 자산(prefix `13`, type=asset) → 투자활동** (1301/1302/1303 + 향후 1300번대 신계정 자동 포함), **차입금성 부채(`BORROWING_LIABILITIES`={2104,2105}, type=liability) → 재무활동**. ⚠️ 2101 미지급금/2102 미지급세금/2103 부가세예수금/2106 가수금 은 `OPERATING_LIABILITIES` 라 영업활동 유지 — 21xx prefix 로 싸잡지 않고 차입금 코드만 explicit set (미지급금 재무 누출 차단). 명시적 dict 멤버는 기존 로직대로 처리 (기존 분류·테스트 불변, 회귀 0). reconciliation 계산을 fallback 분류 後로 이동. 라이브 axec 2026-01~05 CF: diff −195M → **0, verified=true** (1302 −225M·1303 −200M 투자, 2104 +230M 재무). | 2026-06-04 |
| D-frame-2 | **evidence/source_file blob 은 항상 `.local/files` content-addressed 복사 + `storage_url` 은 portable (relative `<hash[:2]>/<hash>/<filename>`)** — `local://<host 경로>` 참조 금지 (컨테이너가 host 경로 read 불가 + source 파일 rename/move 시 깨짐), CWD 의존 absolute 경로도 금지 (host `/Users/.../​.local/files/...` vs 컨테이너 `/app/.local/files/...` 불일치). 근인: `ingest/entity_meta.py`·`ingest/resolution.py` 가 blob 을 복사 안 하고 `local://{pdf_path.resolve()}` 만 저장 → 외부 OneDrive/Downloads 포인터라 컨테이너에서 blob 부재; `_store_file_locally`·`ops/evidence.py`·`hometax.py` 는 복사는 했지만 `str(dest.resolve())` 라 CWD 의존. Fix: `_store_file_locally` 가 portable url 반환 + 신규 `resolve_storage_path()` 가 read 시 `settings.file_storage_path` 기준 absolute 로 매핑 (portable/`/app`/`/Users`/`local://` 4형식 tolerant — legacy row 무중단). 모든 write-site (entity_meta/resolution/hometax/ops.evidence) 가 `_store_file_locally` 경유. read-site = `http_server.py` storage-integrity probe 가 `resolve_storage_path` 사용. Alembic entity migration `0020_normalize_evidence_storage_url` 가 blob 이 `.local/files` 에 실존하는 기존 row (axec 158 + axev 19 = 177) 를 portable 로 정규화 (blob 부재 row 는 절대 미변경·notice; blob 절대 삭제 안 함). | 2026-06-04 |
| D-frame-1 | **pending_payroll: 분개 trigger = 실 거래 (matching principle)** — D-hive-26 의 즉시 분개 디자인 폐기. hive event → `pending_payroll` INSERT (예약). KB raw_tx → `match_pending_payroll` (date±3 + amount exact + name fuzzy) → 분개 자동 생성 + link. status: pending→matched/stale/cancelled. 회계 표준 (matching principle: 거래 발생 시점에 분개) 부합. 이중 분개 위험 0. | 2026-05-22 |
| D-matrix-1 | **Matrix: Rust + native MCP (no Python SDK)** — 첫 Rust 서비스. MCP Streamable HTTP 직접 구현 (JSON-RPC 2.0 + axum). 모니터링 서비스 저메모리·단일 바이너리 적합. D-bp-mcp-1 (Python FastMCP) 과 별개 precedent | 2026-05-23 |
| D-matrix-2 | **Matrix: WAN/인터넷 가용성 모니터링 + ISP 귀책 판별** — collector 에 `check_wan` (wan-gateway / wan-internet / wan-dns 프로브) 추가. gateway↑ + internet↓ ⇒ ISP/WAN fault 자동 태깅. 스키마 변경 0 (기존 `check_results` JSONB 재사용). 컨테이너 NET_RAW + iputils-ping, default interval 60→30 | 2026-06-03 |
| D-matrix-4 | **netheal — 호스트 인터넷 자가치유 데몬** (matrix 보완) — 인터넷 지속 끊김 시 DNS플러시→DHCP갱신→WiFi바운스 사다리 자동 실행. ISP 장애(gateway↑·외부↓)면 백오프(WiFi 안 건드림). root LaunchDaemon (컨테이너 밖, 호스트 en1 제어). 자동 재부팅 기본 OFF. `~/axe-netheal/` | 2026-06-04 |
| D-matrix-3 | **Matrix: backlog/roadmap/ship-log 구조화 SSOT** — backlog·roadmap·updates(ship log) 의 SSOT 를 hand-edited markdown → matrix-postgres(slug PK `B-foo`/`M1` 보존) 로 이전. matrix MCP 8 도구(`backlog_list/create/update/transition`·`roadmap_list/upsert`·`shiplog_append/list`)로 전 서비스 에이전트가 **멀티라이터-안전** read/write. docs 의 3 페이지는 **host-side 생성**(`axe ship docs` 가 matrix fetch→.mdx, matrix-git-push 모델 기각). known-gaps·decisions 는 narrative 라 markdown 유지. 동기 = git-markdown 멀티라이터 충돌(2026-06-03 세션 실측: known-gaps swept-commit·backlog 동시 +3). [ADR](https://github.com/axelabs-ai)=`matrix/docs/adr/backlog-roadmap-system.md`. **Phase 1(스키마 3테이블+MCP 8도구+import 파서) 구현·`cargo check`·import dry-run(206 backlog+16 ship+7 roadmap) 검증 완료, 미배포** | 2026-06-03 |
| D-hive-1 | Hive HR backend 신설 — frame 패턴 mirror (schema-per-entity, OAuth-RP) | 2026-05-21 |
| D-hive-21 | Payroll v2 — 한국 도메인 본질 7가지 (간이세액표 lookup · 비과세 분리 · 보수월액별 · 부양가족 · 정산 · 일할 · 보험별 라운딩). v1 단순 누진세 폐기. 첨부 급여대장 셀별 정확 일치. | 2026-05-21 |
| D-hive-22 | 급여명세서 메일 발송 인프라 (PDF + 평문 본문) + 법정 8항목 (근로기준법 §48 ②) | 2026-05-21 |
| D-hive-23 | M365 SMTP AUTH 의 deprecation 회피 → Graph API SendMail + client_credentials + DKIM/DMARC DNS (Cloudflare API token 자동화) | 2026-05-21 |
| D-hive-24 | 메시지 템플릿 관리 — shared default + entity override + Jinja2 SandboxedEnvironment + StrictUndefined + partial unique index | 2026-05-21 |
| D-hive-25 | Customize 강제 (`require_entity_override=True` — shared fallback 차단) + 발송·송금 audit log (`payslip_dispatch_log` + `payslip_send_log` with body_sha256) | 2026-05-21 |
| D-hive-26 | **Cross-service event consumer = `CONSUMER-worker` 별도 컨테이너** (consumer-grouped, multi-channel LISTEN). frame-worker 1개가 hive_events 받음 + 미래 magnet/stream 채널은 dispatch table 추가만 (컨테이너 추가 X). N×N 폭증 회피 (N+M, M≤N). in-process async task (P2) 검토 후 책임분리·격리·blue/green swap 무관·crash 격리 우선으로 sidecar (P1) 선택. | 2026-05-22 |
| D-hive-27 | **`employees.payroll_start_date` 단일 컬럼 분리** — `hire_date` 가 (i) 계약 발효일 (ii) 보수 개시일 (iii) 4대보험 가입일 3 의미 동시에 짊어지던 모순 해소. `payroll_start_date` Date nullable, NULL → hire_date fallback (정직원 90% 는 NULL → 자동). 임원계약 §2 (계약 시작) ≠ §6/§12 (보수·4대보험 시작) 케이스 대응. frame.executive_officer.appointed_date (= hive.hire_date) 정합 보존. 4대보험 가입일은 당분간 보수 개시일과 동일로 가정 — 다른 경우 발생 시 `social_insurance_enroll_date` 추가 검토. cycle.py 일할 base + employee_create/update MCP 옵셔널 입력 지원. alembic entity 0009. | 2026-05-29 |
| D-hive-28 | **`compute_period` 시그니처에서 `employee_ids` 제거** — D-hive-20 원작자가 정정 경로를 분리 (full re-run = `compute_period`, 사후 정정 = `compensation_events.adjustment`, D-hive-17) 했음에도 후행 adjustment leg 미구현 + `employee_ids` 파라미터의 동작 ("period 전체 wipe + 일부만 INSERT") 이 운영자에게 "부분 정정" 직관을 줘 다른 직원 payslip 손실 위험. 단순 결함 아닌 의도된 분기 + 미완성 + 의미 모호의 누적. 시그니처 모호 파라미터 제거가 원작자 의도 정합. 골든 테스트 + MCP wrapper 사용처 0건이라 호환성 영향 없음. 후속: `compensation_events.adjustment` 정식 MCP 도구 구현은 별도 backlog. | 2026-05-30 |
| D-hive-30 | **`compensation_plan_list` + `compensation_award_create` MCP 도구 신설 (M 트랙, D-hive-17 후행 leg)** — alembic 0004 의 plan/award/event 3-table schema 만 정의되고 등록 도구 미구현이라 운영자가 직접 SQL 박아야 했음. 본 결정에서: `compensation_plan_list(entity, plan_kind?)` (read) — plan_code 조회용. `compensation_award_create(entity, employee_no, plan_code, annual_amount_krw, effective_from, effective_until?, award_code?)` (admin) — employee/plan 존재 + active overlap 검증 후 INSERT (overlap 시 `COMPENSATION_AWARD_CONFLICT` raise, 옛 award `effective_until` 먼저 set 안내). `payroll_compute_period` 가 active salary award 없으면 skip — 본 도구가 페이슬립 산정의 선행. 사용 절차: plan_list → award_create → compute_period 재호출 → case A INSERT 자동 산정. 후속 (별도 backlog): award_update / award_close / plan_create / event_* 등. | 2026-06-05 |
| D-hive-29 | **`compute_period` UPSERT-with-gates (ABCDE) + `compensation_events.adjustment` 정공법 도구** — DELETE+INSERT 가 (i) `payslip_send_log` FK NO ACTION 과 충돌해 발송된 페이슬립 재산정 차단, (ii) ID 변경으로 외부 참조 dangling, (iii) audit history 가 두 ID 로 쪼개짐. UPDATE 는 PG WAL/MVCC 동등 또는 우위. 직원별 case A(없음→INSERT) / B(pending+send_log=0→UPDATE) / C(pending+발송됨→skip) / D(paid→skip) / E(reversed→skip) MECE 룰. UPDATE 는 산정 fields 덮어쓰기 / 운영 fields + 운영 메타 보존. 동반 구현 = `compensation_event_adjustment_create` MCP 도구 (admin scope) — payslips uq 제약으로 갈래 1 line append + 합계 보정 채택, `compensation_events.adjustment` row 가 audit 본질. `delta_krw` 부호 = `line_items.amount_krw` 부호. 발송된 페이슬립 정정 시 직원 메일 ≠ DB → 운영자 재발송 책임. D-hive-28 의 "DELETE+INSERT" 표현을 본 결정이 갱신, employee_ids 제거 자체는 유지. **보강 (룰 H, 동일 날짜)**: adjustment 도구는 case C 만 허용 — A→`PAYSLIP_NOT_FOUND` / B→`PAYSLIP_NOT_DISPATCHED` (compute_period 안내) / D→`PAYSLIP_ALREADY_PAID` (운영자 수동·다음달 소급 자동화 의도적 미구현) / E→`PAYSLIP_REVERSED` raise. 자동화 leg (frame 정정 분개 consumer / 정정명세서 자동 재발송 / 운영자 Teams 알림) 별도 backlog. **보강 (룰 I, 2026-06-05)**: NPS 4.5% → **4.75%** (2026 한국 국민연금 보험료율 9%→9.5% 인상, 1998년 이후 첫 조정). 사용자 원본 산식 `MIN(base, IF(base<370K,16650,IF(base>5.9M,265500,ROUNDDOWN(ROUNDDOWN(base,-3)*4.75%,-1))))` 그대로 적용 — base 천원 절사 + 양끝 정액 cap (16,650 / 265,500) + 외부 MIN wrapper. **룰 K (2026-06-05 최종)** — **근로소득세/주민세 base = R(과세표준) / 4대보험(NPS·NHIS·LTC·EI) base = 신고보수월액(`reported_income_*_krw`, NULL fallback R)**. 보수월액 컬럼 값은 R 과 같게 set 정책 (운영자 책임, 회계·공단 신고 정합). 정액 케이스는 R 기준과 결과 동일, 일할 케이스 (신규 입사·중도 퇴사) 에서 R(일할 변동) vs 보수월액(고정) 차이 가능 — 별도 backlog `B-hive-payroll-base-policy-decision` 정책 결정. axec.AXEC-002/003 reported_income 4,186,222/4,022,567 → 3,966,667 정합 UPDATE (axev 는 이미 정합). 골든 axec 4월 net 강태훈=3,607,277 / 한진우=3,571,577 — 사용자 expected 정확 일치. **MCP 노출 leg 정정**: D-hive-21 payroll v2 컬럼 8개 (reported_income_pension/health·dependents·children·vehicle·is_executive·meal/vehicle_allowance) 를 `employee_get` select / `employee_update` allowed 에 일괄 추가 — 운영자가 신고보수월액 조회·갱신 가능. 골든 강태훈/한진우 axec 4월 pension 188,370→198,830, net 3,605,007→3,594,547 (강태훈) / 3,569,307→3,558,847 (한진우). 5월 ps#7 강태훈 (case C) = adjustment 정공법 정정 필요, ps#8 한진우 (case B) = 다음 compute_period 호출 시 UPDATE 자동. | 2026-06-01 / 2026-06-05 |
| D-bp-mcp-calendar-2 | **Admin send-as 캘린더 쓰기** — `create_event` 등 6개 write tool 에 `as_user_email` optional 파라미터 추가 (find_free_time 제외 — 이미 attendeeEmails 로 다중 사용자 조회). 호출자 `role=admin` 이면 target user 의 캘린더에 직접 write 가능, event organizer = target user 표시. 구현: 신규 `getAppOnlyClient()` (graph.ts) = `msalApp.acquireTokenByClientCredential({ scopes: [".default"] })` 로 app-only token 발급 → `/users/{targetUpn}/events` Graph endpoint (UPN/email key — Blueprint `User.id` = Prisma cuid 이지 Entra oid 아님). Azure App **Application permission** `Calendars.ReadWrite` 필요 + tenant admin consent 1회. **권한은 Blueprint Next.js Azure App (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`) 에 부여** — MCP custom connector 의 별도 App (`482598f7-...`) 가 아님 (함정 [/ops/known-gaps#blueprint-azure-app-id-혼동](/ops/known-gaps#blueprint-azure-app-id-혼동)). 명령: `az ad app permission admin-consent --id 2b222356-1c36-48e0-96a3-2c5e0ecbf937` (Global Admin 계정 필요 — AXE 테넌트는 soohun.kang 만). consent 후 blueprint-app 컨테이너 1회 재시작 (MSAL `acquireTokenByClientCredential` 내부 토큰 캐시 비우기). 비-admin caller 의 `as_user_email` 사용 시 403 `send_as_forbidden`. D-bp-mcp-calendar-1 의 delegated 경로는 그대로 (caller 본인 캘린더 = 기본 동작). 동기 = 관리자 (`ai@axellc.com`) 가 직원 계정 (`soohun.kang@axellc.com`) 의 캘린더에 직접 일정 등록하는 사용자 시나리오. | 2026-05-26 |
| D-bp-mcp-mail-1 | **범용 이메일 발송 tool `send_mail`** — Blueprint MCP 의 첫 일반 outbound mail surface (기존 outbound 은 `create_event` .ics 초대뿐). caller 본인 mailbox 에서 임의 수신자(외부 도메인 포함)로 메일 발송. 구현: 신규 dispatcher route `POST /api/internal/mail` (calendar route 형제) → caller delegated token (`getClientForUser`; `Mail.Send` delegated 는 **이미** `src/lib/graph.ts` SCOPES 에 존재 → self 발송은 re-consent 불필요) → Graph `POST /me/sendMail`. params: `to`/`subject`/`body`(html\|text)/`cc`/`bcc`/`attachments`(Graph fileAttachment base64)/`save_to_sent_items`/`dry_run`. **Admin send-as** (`as_user_email`, calendar-2 와 동일 게이트): caller `role=admin` 이면 app-only token (`getAppOnlyClient`) + `/users/{targetUpn}/sendMail` 로 타 사용자 mailbox 발송. Azure App **Application permission** `Mail.Send` + admin consent 필요 — **Blueprint Next.js app (`2b222356-1c36-48e0-96a3-2c5e0ecbf937`) 측**, MCP connector app (`482598f7-...`) 아님 (함정 [/ops/known-gaps#blueprint-azure-app-id-혼동](/ops/known-gaps#blueprint-azure-app-id-혼동)). 비-admin 의 `as_user_email` → 403 `send_as_forbidden`. **Audit (injection-safety 정책 필수)**: 모든 발송 (`sent`/`dry_run`/`failed`) 이 append-only `MailSendLog` 1 row (caller · sentAs · to/cc/bcc count · subject · status · httpStatus · messageId) — Hive `payslip_send_log` + magnet decisions-ledger 패턴 정합. Graph `sendMail` 은 202 no-body → `message_id` null (Hive D-hive-23 동일; Sent 폴더 사본이 durable record). `dry_run=true` = 메시지 조립·검증·preview 만 반환, Graph 미호출. 동기 = 운영자 봇 (`ai@axellc.com`, role=admin) 이 외부 고객/임원에게 요약 메일 발송 필요. | 2026-05-29 |
| D-bp-mcp-1 | Blueprint MCP standalone (Python+FastMCP, frame/hive 1:1 미러) + 5층 양파껍질 회고 → 체크리스트 항구화 | 2026-05-21 |
| D-bp-mcp-2 | Blueprint MCP **blue/green pair** (frame `frame-mcp-blue/green` 패턴 미러, alias swap + Caddy reload, cloudflared 무중단) — single replica 가 build 시 5-10s 다운 유발하던 drift 해소 | 2026-05-21 |
| D-bp-mcp-teams-1 | **`get_teams_message` MCP tool** — Blueprint MCP 가 `teams.microsoft.com/l/message/...` deep link 를 본문·발신자·타임스탬프로 resolve. 구현 = Python MCP → docker `default` 망 → Blueprint Next.js `POST /api/internal/teams/fetch-message` (Bearer `BLUEPRINT_INTERNAL_API_KEY` 공유 비밀, `/api/internal/entity-roles` 패턴 미러) → 기존 `getChatMessage()` (bot identity `ai@axellc.com`, app perm `ChatMessage.Read.All`) 재사용. 동기 = Claude (web/desktop) connector 사용자가 Teams 링크 던졌을 때 "fetch 불가" 응답이 나오던 capability gap — connector 자체는 enable 됐으나 tool 이 없어서 호출 불가. **Scope**: contextType=chat (1:1·그룹) 만. channel-context URL 은 501 (`/teams/{teamId}/channels/{channelId}/messages/{messageId}` Graph 경로 + groupId 파싱 follow-up). bot 미멤버 chat 은 403 그대로 surface. | 2026-05-26 |
| D-bp-mcp-calendar-1 | **Blueprint MCP 의 첫 write surface = M365 caller 캘린더 CRUD** (7 tools: create/update/delete/get/list event, add_attendees, find_free_time). 사용자 요청 = Outlook calendar 자동 일정 등록 + 외부 도메인 (gmail/naver 등) attendee 초대. 구현: 단일 dispatcher route `POST /api/internal/calendar` (op selector — 7 ops in one file, calendar 가 1 logical CRUD domain). caller email → User.id → `getClientForUser(userId)` delegated Graph (`Calendars.ReadWrite`). 외부 attendee 도메인 = Graph 가 SMTP invite 자동 발송, 별도 provider 통합 불필요 (Google Calendar API 와 무관). NextAuth + graph.ts SCOPES 양쪽에 `Calendars.ReadWrite` 추가 — 기존 사용자 1회 re-consent (또는 admin tenant-wide consent). **D-bp-mcp-1 의 read-only 원칙과 무관**: D-bp-mcp-1 은 Blueprint 자체 도메인 (issue/session/workspace) 에 한정 — calendar 는 별개 도메인 (Microsoft Graph). 후속 [D-bp-mcp-calendar-2](#) 에서 admin send-as 추가. | 2026-05-26 |
| D-bp-mcp-teams-3 | **`reference` 첨부 파일 본문 fetch** — D-bp-mcp-teams-2 의 v2 가 `attachments[i].contentUrl` 을 surface 했지만 OneDrive/SharePoint 파일의 **실제 본문**은 별도 Graph 호출이 필요해서 호출자가 링크만 받고 끝남. 사용자 첫 메시지에 `.md` 첨부가 있어 즉시 노출된 gap. v3 = 신규 tool `get_teams_attachment_file(content_url)` + 신규 endpoint `POST /api/internal/teams/fetch-attachment-file`. `downloadReferenceFile()` (graph-client.ts:1507) 의 in-memory 버전 = `encodeShareUrl` (private helper 미러: `u!` + base64url, no padding) + `/shares/{enc}/driveItem/content` ARRAYBUFFER fetch. 응답 = 확장자 기반 3 분기: text-like (md/txt/csv/json/yaml/yml/log/xml/html/ts/py/sh/sql/conf/toml/diff 등) → UTF-8 decode 후 `kind: "text"`; image (png/jpg/gif/webp/svg) → base64 + `kind: "image"`; 나머지 → base64 + `kind: "binary"`. 50 MB 기본 / 100 MB hard cap (호출 시 `maxBytes` override 가능). 동기 = file vision 으로 가는 게 아니라 텍스트 파일이 압도적이므로 text → string 직답이 가장 큰 가치. 이미지 자료는 `get_teams_hosted_content` (inline message images) 가 별도 경로. | 2026-05-26 |
| D-bp-mcp-teams-2 | **첨부 + 인용 + 인라인이미지 지원 확장** — D-bp-mcp-teams-1 의 v1 응답이 `attachments[]` 를 drop 해 사용자 첫 smoke test 메시지에 첨부가 있어도 호출자가 알 수 없던 gap. v2 응답에 (a) `attachments[]` (`reference` OneDrive 파일 + `contentUrl` / `messageReference` Teams 인용 / Adaptive Card `content` JSON), (b) `quotes[]` (`messageReference` 자동 1-level resolve — `attachments.ts:resolveMessageReferences()` 패턴 미러, quote-of-quote 는 opaque), (c) `inlineImageIds[]` (`extractInlineImageRefs(bodyHtml)`) 추가. 신규 tool `get_teams_hosted_content(chat_id, message_id, hosted_content_id)` = Graph `/chats/{c}/messages/{m}/hostedContents/{h}/$value` ARRAYBUFFER fetch → 매직바이트 sniff (PNG/JPEG/GIF/WebP) → FastMCP `Image()` 반환 → Claude vision 직접 활용. 10 MB 상한. 신규 internal endpoint `POST /api/internal/teams/fetch-hosted-content`. | 2026-05-26 |
| D-bp-entity-1 | Blueprint 에 **entity 개념 도입** (axec/axev) — Workspace 에 `entityId` FK + `paraLayer` enum (PROJECT/AREA/RESOURCE/ARCHIVE). PARA 4 layer 모두 entity scope. hive 의 schema-per-entity 와 달리 row-level FK (Blueprint 의 cross-entity workflow 와 부합). [PR #339](https://github.com/soohunkang/blueprint/pull/339) + hotfix [PR #341](https://github.com/soohunkang/blueprint/pull/341) 적용 완료. | 2026-05-21 |
| D-bp-entity-2 | **PARA dispatch flow sub-consensus** — Project 종결 → Area/Resource 이관은 copy-with-provenance (`sourceWorkspaceId` / `sourceArtifactPath` / `copiedAt`). Archive = 시점형 archaeology, Area/Resource = 현재형 living knowledge (검색 분리). 자동 분배 = LLM 제안 + 사용자 확인. schema 부분은 D-bp-entity-1 PR 에 통합, UI 는 PR 5 예정 (Path B Spike 선행 권고). | 2026-05-21 |
| D-bp-para-1 | **PARA 범용 재구조화 — 조직론 모델 + dispatch "집(link)" + governance 분리 + 죽은 딜 본질** ([D-bp-entity-2](#d-bp-entity-2--para-dispatch-flow-sub-consensus) copy→link **revise**) — PARA=조직론(Area=영속기능/MCP=물질화 · Project=TFT · R/A는 Area 안). dispatch="집" 모델: artifact 몸통1·집N(**link 기본**), move=소모성→Archive→폐기, copy-curate=재사용본 저작→Resource (copy-with-provenance default 폐기). Blueprint=모든 Area 기본 substrate + 가로 결정로그, 서비스=졸업한 live 엔진. governance=결정로그(record, append-only) + 결재워크플로(process, layer), e-sign 통합=[B-bp-decision-pipeline-esign](/ops/backlog). **본질=죽은 딜 저장·harvest**. 신규코드=Rust. 상세=[/architecture/para-os](/architecture/para-os). | 2026-06-06 |
| D-bp-rust-1 | **Blueprint 점진 Rust 전환 (strangler-fig) — substrate = 첫 organ** ([D-bp-para-1](/ops/decisions) 열린질문 a/c/d 확정) — 백엔드를 도메인별 Rust(axum) organ 으로 점진 추출, Next.js=얇아지는 frontend-of-record (**프론트는 당분간 TS**, UI 전면 재작성은 별개·먼 결정). 첫 organ = **PARA substrate**(artifact/dispatch/knowledge-query). 경계=**Artifact-scoped**: substrate 가 artifact/artifact_link(+annotation)/mcp_schema 소유, `workspace_id`·`entity_id`=opaque 외부 ref(FK·중복 0), **Workspace+paraLayer SoR=Prisma 잔류**. 공존=**Postgres schema-split**(Prisma `public` / sqlx `substrate`, 한 blueprint-postgres, 교차쓰기 0) → [D-bp-artifact-4](/ops/decisions) "monolith first·신규 인프라 0" **refine(모순 아님): 인프라 동일·언어만 Rust·프로세스 분리**. 배포=blueprint compose sidecar `blueprint-substrate` (cloudflared/공개 MCP/blue-green/ops 온보딩 **없음**, `axe ship blueprint` 한 경로). Next→Rust 인증=기존 `BLUEPRINT_INTERNAL_API_KEY` Bearer. 모델=[D-bp-para-1](/ops/decisions) home/link("집") 1급 + **2-level scope(personal/shared) 확정**(a) + citation 8종([D-index-6](/ops/decisions) `index.*` · [D-gate-2](/ops/decisions) `gate.decision` 포함). Project staffing=후속 defer(c). 상세=ADR `docs/adr/blueprint-rust-migration.md` + [/architecture/para-os](/architecture/para-os). | 2026-06-06 |
| D-bp-entity-3 | **General bucket 본질 제거 + sys entity 도입** — `Workspace.entityId` nullable → **NOT NULL FK** (모든 workspace 가 정확히 1 entity 보유). ad-hoc / 시스템 row 는 seeded `sys` entity (kind=`system`, end-user dropdown 미노출). 사용자 결정 2026-05-22 ("General entity 는 필요하지 않습니다"). [PR #344](https://github.com/soohunkang/blueprint/pull/344) + hotfix [PR #345](https://github.com/soohunkang/blueprint/pull/345) (workspace.create 3곳 entityId 필수 — `_resolveEntityIdForCreate` helper: opts.entitySlug / drivePath guess / user.entityScopes[0]). 적용 후: axec 1 / axev 15 / sys 2 / null 0. | 2026-05-22 |
| D-bp-entity-4 | **TopNav 전역 EntitySelector + hive name sync** — 페이지별 entity dropdown 폐기 → TopNav 우측 단일 selector (URL `?entity=` primary + localStorage `axe:lastEntity` fallback). session.user.entityScopes 노출. ProjectsClient + ARAClient 가 URL query 읽기로 fetch 구성. Blueprint Entity.name 을 hive `shared.entity.legal_name` 한국어 정식 명칭 (액스코퍼레이션 주식회사 / 액스벤처스 주식회사) 으로 sync — 두 시스템 entity universe SOT 정합. [PR #346](https://github.com/soohunkang/blueprint/pull/346) + [PR #347](https://github.com/soohunkang/blueprint/pull/347) (Next.js 16 useSearchParams Suspense — /axe layout dynamic) + [PR #348](https://github.com/soohunkang/blueprint/pull/348) + [PR #349](https://github.com/soohunkang/blueprint/pull/349). | 2026-05-22 |
| D-bp-entity-5 | **Entity metadata 확장 + /api/entities + TopNav fetch** — Entity 에 `bizNo` / `fiscalYearStartMonth` / `countryCode` 추가 (hive shared.entity mirror, axec=366-86-03798 / axev=643-86-01377). `/api/entities` GET 엔드포인트 (서버 측 entityScopes 권한 검증). TopNav `ENTITY_LABELS` hardcode 제거 → /api/entities fetch — 새 entity 등록 시 client 재배포 0. seed drift detect 가 모든 mirror field 비교 (PR #350 의 early-out fix). [PR #350](https://github.com/soohunkang/blueprint/pull/350) + [PR #351](https://github.com/soohunkang/blueprint/pull/351). | 2026-05-22 |
| D-bp-entity-6 | **Team entity scope + Member.entityId rename** — `Member.entityId` (polymorphic User/Agent FK disambiguator) → `underlyingId`. D-bp-entity-1 의 `Workspace.entityId` (accounting entity) 와 naming 충돌 영구 해소. team-service 응답에 `entityScopes: string[] \| null` 추가 (human = User.entityScopes / agent = null). TeamClient + OrgChartView 가 chip 표시 (axec/axev = lime / sys = muted) + URL `?entity=` filter (human 만 적용, agent 는 system actor pass-through). [PR #352](https://github.com/soohunkang/blueprint/pull/352). | 2026-05-22 |
| D-bp-entity-7 | **User.defaultEntity — 사용자별 명시적 default entity** — 이전: TopNav 첫 로드 "all" / createWorkspace fallback "scopes[0]" 가 customers.yaml 순서 의존 (axec). 사용자별 default 명시 불가. 본 PR: `User.defaultEntity String?` 컬럼 + hydrateEntityScopesForUser 자동 set (null + non-empty scopes → scopes[0]; scope 외 default → scopes[0] fallback). session.user.defaultEntity 노출. TopNav fallback chain: URL → localStorage → defaultEntity → "all". createWorkspace fallback: opts → drivePath → defaultEntity → scopes[0] → throw. `/api/user/default-entity` PATCH 엔드포인트 (server-side gate). [PR #354](https://github.com/soohunkang/blueprint/pull/354). 운영 후속: Settings UI dropdown (endpoint 의 사용자 surface, 별도 PR). | 2026-05-22 |
| D-bp-entity-8 | **entityScopes YAML 순서 보존 + scopes[0] fallback** — D-bp-entity-7 의 후속 함정: hydrate 가 entityScopes 를 alphabetic sort 후 저장 → customers.yaml `["axev","axec"]` operator 의도 SOT 가 DB `["axec","axev"]` 로 reset → scopes[0] = "axec" → axev default 불가능. fix: hydrate 가 raw `resolved` 순서로 저장 (sort 는 set-equality 비교만). TopNav fallback chain 에 `userScopes[0]` 추가 — URL → localStorage → defaultEntity → scopes[0] → "all". session.defaultEntity null (build cache miss 등) 이어도 yaml 순서 가 운영 default. customers.yaml 의 user_entity_map list 순서가 진정한 SOT. 사용자 결정 "모두 default 는 axev" 만족. [PR #355](https://github.com/soohunkang/blueprint/pull/355). | 2026-05-22 |
| D-bp-entity-9 | **owned account switching (TopNav AccountSwitcher)** — Soohun 이 `soohun.kang@axellc.com` + `ai@axellc.com` + `cfo@axellc.com` 모두 운영. owner 가 owned AI agent identity 로 view-only switch. 본 PR: `User.ownedBy String?` self-FK (NULL 시 본인 계정, set 시 owner.id 참조). `POST /api/auth/switch-account { targetUserId }` 가 `target.ownedBy === caller.userId` 검증 후 httpOnly cookie `axe:active-user-id` set. `DELETE` 는 cookie clear (revert). session callback 이 cookie 발견 시 매 read 마다 ownership 재검증 → session.user.* 모두 target 로 override (email/name/role/entityScopes/defaultEntity). JWT 자체는 untouched — authenticated identity 의 audit trail 보존, view 만 변경. TopNav AccountSwitcher dropdown (owned ≥1 시만 노출, isImpersonating=true 시 lime border + tooltip). mid-session ownership revoke 시 자동 revert (defense-in-depth). admin role 도 bypass 불가 — owned-only. [PR #356](https://github.com/soohunkang/blueprint/pull/356) + hotfix [PR #357](https://github.com/soohunkang/blueprint/pull/357) (Suspense import). 적용 후 DB: ai@/cfo@ ownedBy = soohun.kang.id. | 2026-05-22 |
| D-bp-entity-10 | **AccountSwitcher 항상 노출 + Add account** — 이전: owned ≥1 (`accounts.length > 1`) 조건으로 single-identity 사용자에게 dropdown 가려짐 → 다른 계정 추가 진입로 부재. 본 PR: gate 를 `!activeUserId` 로만 (signed-in 모두 노출). dropdown 안에 `+ 다른 계정으로 로그인` 옵션 추가 → 선택 시 `signIn("azure-ad", ..., { prompt: "select_account" })` 호출, Microsoft 계정 picker 강제. PR #358 첫 시도는 `return null on accounts.length === 0` 함정 (initial state 가 빈 배열 → null mount → useEffect setAccounts 무효) → hotfix [PR #359](https://github.com/soohunkang/blueprint/pull/359) 가 condition 을 `!activeUserId` 로 좁힘. [PR #358](https://github.com/soohunkang/blueprint/pull/358) + #359. | 2026-05-22 |
| D-bp-entity-11 | **"전체 entity" 폐기 — 항상 specific scope** — 이전: TopNav 와 ProjectsClient/ARAClient/TeamClient 가 `entity === "all"` 분기로 전체 entity 합산 뷰 제공. 사용자 보고: "전체 entity 선택하는 것 잘 동작하지 않습니다" + 회계/거버넌스 측면에서도 cross-entity 합산은 의미 부재 (axec 와 axev 는 별 법인). 본 PR: ALL 상수 제거 + URL `entity` 가 userScopes 안 이 아니면 자동 specific 으로 rewrite (fallback: localStorage → defaultEntity → scopes[0]). 클라이언트 fetch 도 `entity` 항상 set. [PR #360](https://github.com/soohunkang/blueprint/pull/360) + follow-up [PR #361](https://github.com/soohunkang/blueprint/pull/361) (3 client 의 "all" 분기 제거 — ProjectsClient/ARAClient/TeamClient). | 2026-05-22 |
| D-bp-entity-12 | **user name = AccountSwitcher trigger (M365/Gmail 패턴)** — 이전: 사용자 이름은 정적 `<span>`, AccountSwitcher 는 별도 `<select>` — 사용자 보고 "nav 에서 id 클릭하면 다른 어카운트로 바뀌는거 구현 왜 안되어있습니까?". 본 PR: 두 element 통합 — 사용자 이름이 자체 dropdown trigger (button) 이고, 클릭 시 popover 메뉴 펼침 (owned accounts list + `+ 다른 계정으로 로그인`). click-outside / Escape close + active item lime / aria-haspopup="menu" + aria-checked. data-testid `nav-user-name` 유지 (E2E backward compat). isImpersonating=true 시 button border + label lime. `<select>` native 동작 (browser-provided dismiss / option 색) 잃지만 M365·Gmail UX 일관성 + click target = label 본질 우선. | 2026-05-22 |
| D-bp-entity-13 | **EntitySelector → button + popover (UI 일관성)** — 사용자 요청: "entity dropdown 도 id dropdown 처럼 보여지면 좋겠습니다". TopNav 의 두 dropdown (EntitySelector + AccountSwitcher) 중 EntitySelector 만 native `<select>` 로 남아있어 시각 불일치 + dark-mode option 색이 OS 마다 차이. 본 PR: 동일 button + popover 패턴 미러 (chevron rotate 120ms, click-outside / Escape close, aria-haspopup="menu", aria-checked). 각 행에 slug chip (axec/axev/sys) 표시 — 사용자가 legal name 만 보다가 slug 도 확인 가능. data-testid `nav-entity-selector` 유지 + `nav-entity-menu`/`nav-entity-item-{slug}` 추가. 부수: `userScopes` useMemo 로 wrap → react-hooks/exhaustive-deps 경고 0. | 2026-05-22 |
| D-bp-entity-14 | **`/axe/usage` entity scope (회계 분리)** — UsageLog → metadata.sessionId → Session.workspaceId → Workspace.entityId 경로로 axec/axev 비용 분리. K-IFRS/K-GAAP 회계 원칙 (거래는 발생 entity 기준 — economic locus = workspace). UsageLog 자체에 entityId column 추가 없이 derived join 으로 Phase 1 구현 — 228 row 규모에서는 query 부담 무시 가능, 5k+ scale 시 Phase 2 로 column + backfill. workspace 미존재 usage (ad-hoc Teams 1:1 / system) 는 `sys` entity 분류 → TopNav 에서 sys 선택 가능한 user (root) 에게만 노출. response 에 `entity` + `byEntity` aggregation 추가 (UI 가 각 entity 별 합계 표시 가능). `byUser/byChat/byWorkspace/byModel/byAuthMode/byDay` + recent 모두 entity filter 적용. UsageClient 가 URL `?entity=` 읽기 — TopNav EntitySelector 와 자동 연동. server-side `entityScopes.includes` 검증 (defense-in-depth). | 2026-05-22 |
| D-bp-entity-15 | **switch-account ownership = authenticated id (impersonated sibling switch fix)** — 사용자 보고: "id dropdown 에서 다른 id 들이 클릭 안되는 이슈". 근본 원인: `switch-account/route.ts` 의 `callerId = session.user.id` 가 effective (impersonated) id 였음. 시나리오: soohun 로 로그인 → ai@ 로 impersonate → cookie effective=ai@.id, JWT authenticated=soohun.id → ai@ 화면에서 cfo@ 클릭 시 `caller=ai@.id`, `target.ownedBy=soohun.id ≠ ai@.id` → 403. UI 의 try/catch 가 silent fail 하여 사용자에게 "클릭 안 됨" 으로만 보임. 본 PR: ownership 검증 + self-switch 모두 `authenticatedUserId` 기준. JWT 가 실제 switching authority 의 SOT (cookie 는 view override 만). 부수: UI `selectAccount` 의 silent fail 폐기 — non-ok response + network error 모두 `console.error` + `window.alert` 로 노출. 정책 명시: impersonated session 이라도 같은 authenticated owner 의 owned set 안에서는 자유롭게 sibling switch 가능 (ai@↔cfo@). 권한 상승은 여전히 차단 — owned identity 가 authenticated 가 아닌 target 으로 switch 불가. | 2026-05-22 |
| D-bp-entity-16 | **admin role 자동 sys entity 포함** — D-bp-entity-14 follow-up. `/axe/usage?entity=sys` 가 403 반환되던 함정. 근본: `hydrateEntityScopesForUser` 의 admin fallback 이 customers.yaml 미설정 시에만 작동 (`resolved.length === 0`). customers.yaml 에 명시된 user (axec/axev) 가 admin 이어도 sys 가 entityScopes 에 없음. 본 PR: admin role 이면 explicit list 뒤에 `sys` 자동 append. 정책: ad-hoc Teams 1:1 / system 사용량 회계 attribution 은 운영자만 확인 (회계 보고서 작성용). 일반 user 는 그대로 403 (자기 ad-hoc 보고 싶으면 admin 승격 필요). customers.yaml 손대지 않고 role 기반 자동화 — operator-editing-yaml-every-time 함정 회피. | 2026-05-22 |
| D-bp-entity-17 | **EntityRole 모델 — entity-scoped 3-tier 권한 (admin/owner/member)** — 트리거: axev 대표 강태훈 (`taehun.kang@axellc.com`) 이 axev HR/payroll 운영을 위해 admin scope 필요한데, 기존 `User.role=admin` 격상은 tenant-wide → axec 까지 영향하는 over-scope. 본 PR: `EntityRole { userId, entitySlug, role }` 모델 도입. role hierarchy `admin > owner > member`. tenant admin (Soohun, ai@) 은 모든 entity 에 implicit admin (admin fallback 정신 계승). hydration = sign-in 시 entityScopes 기반 member row 자동 생성 + slug 제거 시 revoke; UI grant 가 owner/admin overlay. Admin UI (`/axe/admin/users`) 에 entity 별 dropdown 추가 (tenant admin gate). 내부 API `GET /api/internal/entity-roles?email=...` (HMAC bearer) — hive/frame OIDC RP 가 PR 2/3 에서 호출해 자동 MCP scope grant 의 SOT. `entityScopes` JSON 은 dual-read (가시성 SOT) — 추후 별도 D 에서 폐기 평가. | 2026-05-22 |
| D-frame-fund-ksme-policy-check | **frame entity_versions/0003 의 `ck_policy_standard` 가 `fund_ksme` 미허용으로 fund entity 등록 좀비** — 트리거: 강태훈 대표 (2026-05-22 11:42) "frame 에서 `axe_ia_001` (액스 투자조합 1호, kind=kip) entity 오류없이 등록 및 활용할 수 있도록 조치" 요청. 근본: D-ops-30 (Migration #2) 가 fund kind 시 `shared.entity.accounting_standard='fund_ksme'` set 하는데, 0003 의 per-entity `accounting_policy.standard` CHECK 가 `('ksme','kgaap','kifrs')` 만 허용 → bootstrap INSERT 가 `COALESCE(accounting_standard,'ksme')` 로 `fund_ksme` 그대로 넣다가 CheckViolation → upgrade_entity 중단 → `axe_ia_001` schema 빈 채 (alembic_version 행도 없음, 0 tables) zombie. **Fix 2-prong**: (a) 0003 코드 패치 — CheckConstraint 정의 자체에 `fund_ksme` 추가 (신규 entity 가 처음부터 통과), (b) 0019 신규 migration (0018 fund_commitment_ledger 다음에 선형화) — `DROP CONSTRAINT IF EXISTS` + `IF EXISTS` 가드 + `ALTER ADD CONSTRAINT` 로 기존 entity (axec/axev/axep/axtest/axe_ia_001_diag) CHECK in-place 확장 + zombie schema 도 fresh 0001→head 로 진행 통과. 배포 후 강태훈 측 register_entity 재호출 → schema head + chart auto-apply 성공 경로 회복. | 2026-05-22 |
| D-frame-register-entity-atomic | **`register_entity` atomicity + mismatch detect — 강태훈 bug report 의 root cause #2/#3 잔여분** ([D-frame-fund-ksme-policy-check](/ops/decisions) 후속). bug report 의 (1) CHECK 제약은 PR #38 로 fix 됐지만 (2) explicit `accounting_standard='ksme'` 명시해도 stored 가 `fund_ksme` 이면 silent override + (3) `shared.entity` INSERT 와 `upgrade_entity` 가 별개 `begin()` 블록 → migrate 실패 시 좀비 row 잔존 — 두 잠재 함정이 미수정. 본 결정: `src/frame/db/migrations.py:register_entity` 를 2-prong 강화 — (a) **mismatch detect**: existing row 의 `accounting_standard`/`entity_kind`/`schema_name` 가 요청 인자와 다르면 ValueError (silent skip 금지, "use different entity_id or update via admin path"), (b) **compensating action**: `upgrade_entity` 실패 시 `inserted_now` 인 경우 `DROP SCHEMA CASCADE` + `DELETE shared.entity` 로 회수 (기존 row 는 보존). 6 신규 pytest (mismatch standard/kind/all-diffs · idempotent identical · zombie cleanup · pre-existing 보호) + 16 기존 PASS 무회귀. 본 audit 결과: bug fix 적용 후 `axe_ia_001` 은 valid empty fund 로 회복 (48 accounts seeded + accounting_policy fund_ksme bootstrapped + alembic 0019 head). 좀비 cleanup = `axe_ia_001_diag` (강태훈 진단용) + `bug_check_kip_20260524` (강태훈 fix 검증용) DROP. **axep** (액스파트너스 유한책임회사, 의도 불명, 데이터 0) 는 보존. | 2026-05-26 |
| D-hive-blueprint-entity-roles | **hive OIDC 가 Blueprint EntityRole 조회해 `admin` scope 자동 부여 (D-bp-entity-17 PR 2)** — 트리거: D-bp-entity-17 후속 + 강태훈 axev owner 격상 후 hive connector 의 admin 자동 활성. 이전: `auth_oidc.py` 가 OIDC 인증 시 무조건 `[read, write, approve]` 만 부여 (admin 은 운영자 HS256 manual). 본 PR: sign-in 마다 Blueprint 내부 API `GET /api/internal/entity-roles?email=...` (HMAC bearer `BLUEPRINT_INTERNAL_API_KEY`) 호출 → role `admin`/`owner` 면 그 entity 의 scope 에 `admin` 추가. **fail-open** (Blueprint 장애 시 default scope 유지 — lockout 회피), **5분 cache** (admin grant 가 Cowork 재인증 cadence 내 반영, Blueprint API 부담 최소화), `_log.info("admin scope granted on ...")` 로 audit. customers.yaml `services.hive.secrets[]` 에 `BLUEPRINT_INTERNAL_API_KEY` 추가 (Vaultwarden collection 동일). | 2026-05-22 |
| D-frame-blueprint-entity-roles | **frame OIDC 가 Blueprint EntityRole 조회해 `admin` scope 자동 부여 (D-bp-entity-17 PR 3)** — D-hive-blueprint-entity-roles 의 frame 측 1:1 미러. 동일 함수 시그니처/캐시 정책/fail-open. frame OIDC default `[read, write, close]` + role admin/owner 시 `admin` 추가 (`reopen` 은 여전히 HS256 only). customers.yaml `services.frame.secrets[]` 에 `BLUEPRINT_INTERNAL_API_KEY` 추가. | 2026-05-22 |
| D-dev-platform-1 | **Phase 1 contributor platform — axe-macmini multi-user dev access (B 안)** — 비전: macmini 10대 × customer 직원 1-2명/customer 가 시스템 개선 활동. 본 PR Phase 1 = 강태훈 + Soohun 양쪽 dev 진입 인프라. (1) macOS multi-user 정책 = first.last shortname (`soohun.kang`/`taehun.kang`), `dev` group + setgid + git `core.sharedRepository=group` 으로 `/Users/axe/{blueprint,frame,hive,axelabs-docs}` 공유. (2) sudoers `/etc/sudoers.d/ai-axe` 좁은 NOPASSWD (dseditgroup/sysadminctl/createhomedir/launchctl/sshd/install/tee `/Users/*`+`/etc/ssh/sshd_config*`/mv `/etc/ssh/sshd_config*`/chown). (3) SSH 강화 — `/etc/ssh/sshd_config.d/200-axe-hardening.conf` 에 PasswordAuth disable / PubkeyOnly / Root disable / ChallengeResponse disable (AllowUsers 는 자동화 user 명단 확정 후 별 round). (4) Cloudflare tunnel ingress + DNS `ssh.axe.axelabs.ai` (proxied, host SSH 22 로 forward) — public 외부 노출 없음, tunnel only. (5) 4 repo (blueprint/frame/hive — axelabs-ai org 으로 transfer 완료, axelabs-docs local-only) 에 CODEOWNERS skeleton (`* @soohunkang`) + PR template. macOS local password 는 Vaultwarden AXE org Default collection 의 `axe-macmini local: <user>` item 으로 등재 — Teams 채팅에 평문 송부 X. 본 PR 미완: Cloudflare Zero Trust App (Account-scope CF token 발급 후 별 round), branch protection (GitHub Team plan 또는 public 전환 결정 필요). | 2026-05-23 |
| D-dev-platform-2 | **`axe customers add <id>` CLI — Phase 2 customer onboarding 자동화 entry point** — Phase 1 의 강태훈 reference implementation 다음 step. AXE central side metadata 등재 (customers.yaml block 추가). Idempotent (이미 존재 시 거절), dry-run, validation (`id` `^[a-z][a-z0-9-]{1,30}$`, entity slug `^[a-z][a-z0-9_]{1,20}$` — underscore OK / hyphen X, frame/hive schema name compatibility), `--legal-name`/`--primary-domain`/`--tailscale-host`/`--public-domain`/`--entities`/`--yes`. 후속 (별 commands, 별 PRs): `axe customers vault-bootstrap <id>` (Vaultwarden collection), `axe customers github-team <id>` (GitHub team + collaborator slot), `axe customers dns-placeholder <id>` (Cloudflare CNAME stub), `axe customer deploy <id>` (customer macmini Docker stack). 첫 use case = realchoice (이미 customers.yaml 등재 — 다음 deploy 단계). | 2026-05-23 |
| D-dev-platform-3 | **`axe customers vault-bootstrap` + `github-team` CLI 추가 — D-dev-platform-2 follow-up** — `vault-bootstrap <id>`: AXE Vaultwarden org 에 3 collection 생성 (`<id>-macmini-local-accounts` / `frame-jwt-<id>-operators` / `<id>-deploy-secrets`). BW_SESSION 요구, idempotent. `github-team <id>`: `axelabs-ai/<id>-developers` team + 3 core repo (blueprint/frame/hive) push permission. member 추가는 `axe user add` (별 PR). 둘 다 dry-run + confirm prompt. realchoice 가 첫 use case (CLI dry-run 검증 완료). | 2026-05-23 |
| D-dev-platform-4 | **ai@axellc.com 통합 GitHub identity (`axe-labs-ai`) — git/gh 단일화** — 본 머신 git config (global) = `AXE Labs AI <ai@axellc.com>`, gh CLI active account = `axe-labs-ai` (PAT vault item `github PAT: ai@axellc.com`, Default collection). 모든 자동화 commit + push 가 단일 identity. 사용자 직원 (soohun.kang/taehun.kang macOS user) 은 자기 ~/.gitconfig 별도 (각자 본인 email/name). 기존 soohunkang gh account 도 keyring 잔존 — break-glass `gh auth switch -u soohunkang` 가능. **org 권한**: `axe-labs-ai` 가 axelabs-ai org **Owner** (team 생성 / collaborator add 자동화 가능). **PAT 발급 정책** (fine-grained): Resource owner = **axelabs-ai org** (본인 X — 본인 발급은 org repo 접근 X); All repositories; Permissions = Repository (Contents R+W / PR R+W / Workflows R+W / Administration R+W / Metadata R) + Organization (Members R+W / Administration R+W). PAT TTL 90일 (만료 2026-08-21), rotation backlog (`B-axe-pat-rotation-cron`). 2FA 권장 (`B-axe-labs-ai-2fa`). | 2026-05-23 |
| D-dev-platform-5 | **Cloudflare Zero Trust App + Free GitHub plan 결정 — D-dev-platform-1 미완 부분 마감** — Zero Trust: `ssh.axe.axelabs.ai` self-hosted App (`b903d8cd-...`) + Email domain policy (allow `*@axellc.com`, `e10f3198-...`). vault token `Cloudflare API - axelabs` (`fae8ff16-...`) 가 Account-scope Access Apps Edit 이미 보유 — 새 token 발급 불요 (notes 만 부정확했음). GitHub branch protection: Free plan 유지. 비용 0, invite-only collaborator + CODEOWNERS + PR template 으로 비전 충족 (강제 X — social norm + axe ship release-gate 가 main 직접 push blast radius 0). 향후 contributor 5+ 또는 외부 진입 시 Team plan / public 재평가. | 2026-05-23 |
| D-dev-platform-6 | **`axe vault unlock/lock/status` — Keychain-backed bw session, ai@ stdin tty 영구 회피** — 이전: BW_SESSION 자주 만료 + 운영자가 매번 `bw unlock --raw` 출력 채팅 회신 + transcript 노출 + ai@ subprocess 의 stdin tty 문제로 bw CLI 호출 fail. 본 PR: `axe vault unlock` 가 운영자 1회 interactive unlock 후 session token 을 macOS Keychain (`security add-generic-password -s axe.vault.session -a ai@axellc.com -w ... -U`) 에 push. _vault_env() 가 모든 ai@ subprocess 의 bw 호출 시 자동 fetch + `--session` flag 우회 패턴으로 stdin tty 문제 영구 회피. Keychain item 은 user 별 isolation (axe user 의 BW_SESSION 은 soohun.kang/taehun.kang user 접근 불가, macOS native ACL). `bw serve` 폐기 사유: UNIX socket / token auth 미지원 → TCP 8087 port 가 same-machine 다른 user 노출 risk. `cmd_customers_vault_bootstrap` 의 BW_SESSION env require 도 `_vault_env()` 자동 fetch 로 교체. | 2026-05-23 |
| D-host-setup-1 | **신설 `/ops/host-setup` page — macmini 13 layer SSOT** — 비전: 10 customer macmini 운영 + 신규 macmini 1 page reference 로 reproducible. 본 머신 (axe-macmini) 의 모든 layer (Hardware / macOS tunables / users + dev group / sudoers / SSH / Tailscale + Cloudflare / Entra / Vault / Docker stack / launchd / CLI / Git / OneDrive / Backup) 와 그 현재 값을 1 page 에 정리. 본 세션의 D-dev-platform-1~6 + 이전 세션의 D-ops/D-config/D-hive/D-frame 결정 다 cross-ref. 본 page 는 read-only reference + drift detect SOT — 변경 시 = 운영 실패 / 함정 발견 trigger. 자동화 CLI (`axe host bootstrap` / `axe host inventory`) backlog. | 2026-05-23 |
| D-hive-backup | **hive-postgres Tier A 백업 합산** — `axe-backup` 의 blueprint-postgres 블록 직후 `hive-postgres pg_dumpall` 블록 추가 (running check + size sanity + restic tag). Phase 1 (조직/휴가) + Phase 3 (payroll v2 axec/axev 실데이터) 운영 중인데 Tier A 0 이던 비대칭 해소. backup.mdx 시나리오 1c (hive DB 손상 복원) 신설. mysrt-postgres 는 SRT 외부 SOT 가능성 잔존 → 별도 결정 보류. | 2026-05-21 |
| D-docs-search-1 | **Nextra 4 UI 검색 = Pagefind 정적 인덱스** — 빌드 후 `pagefind --site .next/server/app --output-path public/_pagefind` 별도 실행. Nextra 4 가 v3 와 달리 검색 UI (`Search` 컴포넌트) 와 인덱스 생성을 분리해 두어 `next build` 만으로는 검색박스가 "Failed to load search index." 가 됨 (초기 scaffold 부터 줄곧 누락). `/api/search` JSON 엔드포인트는 LLM 용 자체 구현이라 무관 — UI 용 = Pagefind, LLM 용 = `/api/search`. | 2026-05-22 |
| D-bp-alert-1 | **L2 silent-drop alert = AXE infra only** (DB row + macOS launchd osascript). 외부 SaaS (Slack/Teams webhook) 모두 배제 — AXE 는 Teams 가 main comm 이고 Slack 미사용, 또한 Teams webhook 도 같은 Graph 종속이라 본 incident class 차단 불가. Channel 1 = `OperatorAlert` Prisma row + `/axe/admin/system` red banner (운영자가 dashboard 자주 보는 곳). Channel 2 = `[OPERATOR-ALERT]` console marker → host launchd `com.axe.operator-alert-notify` daemon 이 docker logs tail + osascript notification (Graph/Postgres 모두 무관, 운영자 mac 앞에 있을 때 즉시 push). 두 채널 독립 — DB 죽어도 marker 살아있고 vice versa. **본질·퀄리티·결과·안전** 4-axis 동시 만족. PR #340 의 Slack webhook design 폐기 후 본 결정. | 2026-05-22 |
| D-docs-roadmap-1 | **`/ops/roadmap` + `/ops/backlog` 분리, `/ops/known-gaps` 책임 좁힘** — 다른 세션이 들어왔을 때 무엇부터 할지가 5초 안에 보이도록 실행 큐 (backlog) 와 큰 그림 (roadmap) 을 별도 페이지로 분리. known-gaps 는 분석적 사실 기록만 유지 (entry point 아님). backlog lifecycle = 신규 / ready / in-progress / done. CLAUDE.md ritual 의 "known-gaps 단일 SoT" 를 "backlog = entry point + known-gaps = 함정/사실" 로 재정의. | 2026-05-22 |
| D-docs-updates-1 | **`/ops/updates` 신설로 4-페이지 시간축 분리** — `backlog` (현재) + `roadmap` (미래) + `updates` (과거) + `known-gaps` (사실). updates 는 3 섹션: (1) Ship Log = 매 ship 한 줄 (Phase 1 수동, Phase 2 자동 hook), (2) Highlights = 사람 큐레이션 narrative (직원·외부 IT), (3) API feed = `/api/changes` JSON (LLM agent fetch). build 시점 `scripts/generate-changes-json.mjs` 가 git log → `public/changes.json` export — runtime container 에 git 바이너리 없는 (.dockerignore 가 `.git` 제외) 함정 회피. CLAUDE.md ritual 도 4-페이지로 확장. | 2026-05-22 |
| D-docs-playbook | **playbook 표준 형식 박제 (`## AI 요청 프롬프트` + step block + 표준 꼬리 2줄)** — 행위 단위 페이지 (셋업/배포/공지/복구) 가 사람과 AI 양쪽의 단일 entry point. commit 18e99d8 (ssh-access 의 "맨 위 복붙 prompt block" 도입) 이 5/26 4 페이지 (ssh-access · vault-setup · claude-connectors · operator-broadcast) 로 정착 → 본 결정으로 [/architecture/playbooks](/architecture/playbooks) 박제 + 4 페이지 minor drift fix. 후속 라운드에 11 페이지 추가 playbook 화 (총 15) + frontmatter `playbook: true` + sidebar `⚡ ` prefix + `scripts/generate-playbook-catalog.mjs` (SSOT 표 자동 + `public/playbooks.json` deterministic export, prebuild 자동 hook + `npm run catalog` ad-hoc) 모두 본 결정의 확장. **2026-05-27 갱신**: 헤딩 `🤖 AI 에 던질 prompt (복사해서 본인 AI session 에 paste)` → `AI 요청 프롬프트` (이모지/괄호 제거, 한국어 명사구 통일). 15 페이지 + 본 SSOT 일괄 정합. 형식 drift = 사용자 mental model 재학습 비용 = 패턴 가치 훼손. | 2026-05-26 |
| D-docs-mdx-traps | **mdx 함정 3종 박제 + `scripts/verify-mdx-compile.mjs` prebuild 자동 audit** — playbook catalog 작업 라운드들에서 노출된 3 함정: (1) `## Heading {#explicit-anchor}` MDX 3 acorn parse fail (기존 함정, 운영자 commit `941196f`), (2) GFM 표 cell 의 backtick code 안 `\|` 가 column separator 로 잘못 인식 → `{` mid-cell unclosed → acorn fail (known-gaps line 386 의 `{reason: "a"\|"b"\|"c"}` 패턴 노출 — webpack cache 가 보통 가려두지만 catalog script 의 SSOT 갱신이 page-map invalidate → fresh re-parse 시 노출), (3) plain text 안 `<PascalCase>` 가 close tag 없는 JSX 컴포넌트로 인식 → build fail (decisions.mdx line 315 의 `Extension<AuthContext>` 노출). 모두 [/ops/known-gaps](/ops/known-gaps) mdx 함정 섹션에 등재 + `project_axelabs_docs_mdx_traps` memory 갱신. 미래 재발 예방 = `scripts/verify-mdx-compile.mjs` (mdx-js + remark-gfm + remark-frontmatter compile 시도, fail file 별 정확한 line/col 출력) 가 prebuild hook 자동 + `npm run verify:mdx` ad-hoc alias. `next build` 의 webpack 모듈 단위 알림보다 정확한 anchor 제공. | 2026-05-27 |
| D-bp-mcp-3 | **Blueprint MCP Postgres cutover 잔재 + startup probe** — D-config-17 (Postgres cutover, 5/15) 가 blueprint-app 만 다루고 `.env` 의 `DATABASE_URL="file:./data/blueprint.db"` SQLite legacy line 그대로 둠. blueprint-mcp 는 그 .env 받아 SQLAlchemy `ArgumentError: Could not parse SQLAlchemy URL` deep in ASGI handler → 모든 OAuth-bearing 요청 500 → Claude.ai UI 가 "Authorization with the MCP server failed" 로 표시 → 운영자가 secret/Azure config 만 의심 (실은 무관). MCP launch (5/21) 부터 종일 broken, container 8h+ healthy 였지만 200 응답 0건. **4-axis fix**: (1) **본질** — `.env` 의 stale `DATABASE_URL` line 제거 → compose default `${DATABASE_URL:-postgresql://blueprint:${BLUEPRINT_DB_PASSWORD}@postgres:5432/blueprint}` 자동 적용. (2) **퀄리티** — `config.get_database_url()` 가 `postgresql+asyncpg://`/`postgresql://`/`postgres://` 외 URL fail-fast (silent parse 대신 명확한 RuntimeError + remediation 안내). (3) **결과** — Claude.ai bearer → MCP 200, tools 실제 동작. (4) **안전** — Starlette lifespan 에 `SELECT 1` startup probe — DB 미접속/URL malformed 시 lifespan fail → healthcheck fail → `axe blueprint upgrade` blue/green swap 거부 (broken container active 못 됨). 양파껍질 6번째 layer = "Postgres cutover env_file 잔재 + SQLAlchemy silent parse fail" → mcp-server-checklist 에 항구화. | 2026-05-22 |
| D-bp-ui-5 | **Blueprint globals.css alias bridge 제거** — D-bp-ui-4 (PR #368) 가 모든 사용처를 새 토큰으로 마이그한 뒤 alias LHS 가 dead code. 본 PR 제거: `@layer base :root` 의 legacy var 9개 정의 (`--navy/--navy-light/--navy-mid/--white/--gray/--gray-light/--dark-border/--green/--red`) + `@layer utilities` 의 legacy class 5개 (`.bg-navy/.bg-navy-mid/.text-gray-ax/.text-gray-light-ax/.border-dark`). 보존: `--accent-glow` (41 tsx 사용, mode-invariant fixed RGB) + `.font-display/.text-accent` (새 토큰 직접 참조). 1 file, +7/-37. production deployed: `--accent-glow:#e3ff6626` 검증, legacy var 정의 0 hits. PR #370 — @axe/ui adoption 5-PR 시리즈 마무리. | 2026-05-22 |
| D-bp-ui-4 | **Blueprint legacy var() → @axe/ui 토큰명 일괄 마이그레이션** — 50+ tsx 의 `var(--navy)/--white/--gray/--gray-light/--dark-border/--green/--red/--navy-light/--navy-mid` 를 sed in-place 로 새 토큰 (`--bg-base/--text-primary/--text-muted/--text-tertiary/--border-subtle/--success/--danger/--gray-2/--gray-3`) 로 1:1 rename. 57 files, +1645/-1645 (mechanical, semantic change 0). globals.css 의 alias bridge LHS 는 보존 — deprecation 단계, 다음 PR (D-bp-ui-5) 에서 제거. Tailwind utility class 이름 (`.bg-navy`/`.text-gray-ax`/등) 그대로 (사용처 무수정), globals.css 의 정의가 새 토큰 직접 가리키게 자동 갱신. sed 순서 유의 — `-light`/`-mid` 가 base 보다 먼저. PR #368. | 2026-05-22 |
| D-bp-ui-3 | **Blueprint light/dark mode 토글 (cookie-backed SSR)** — D-bp-ui-1 토큰 인프라 위 첫 user-visible 기능. `next/headers` 의 `cookies()` (async) 를 RootLayout 에서 read → `<html data-theme={theme}>` 결정. cookie 없으면 dark 기본. `ThemeToggle` client 컴포넌트가 토글 시 (1) `document.cookie = 'theme=...; max-age=31536000; SameSite=Lax'` 1년 persistence, (2) `documentElement.setAttribute` 즉시 교체, (3) state 갱신. 다음 SSR 도 같은 cookie 읽으므로 FOUC/hydration mismatch 없음. next-themes 의존성 미추가 — 65-line custom. `/axe/settings` General 섹션의 placeholder GeneralRow Theme="Dark" 를 active 토글로 교체. `TopNav` 의 hard-coded `rgba(26,6,16,0.92)` → `color-mix(in srgb, var(--bg-base) 92%, transparent)` (modern color-mix Chrome 111+/Safari 16.4+/Firefox 113+). PR #367. | 2026-05-22 |
| D-bp-ui-2 | **Blueprint Space Grotesk inline → @axe/ui font 토큰** — D-bp-ui-1 후속 cleanup. 8 tsx 의 14 inline fontFamily refs 를 토큰화. SVG `<text fontFamily="'Space Grotesk', sans-serif">` × 8 (agents/org × 4, team/OrgChartView × 4) → `var(--font-sans)`. React inline style `fontFamily: "'Space Grotesk', monospace"` × 6 (system prompt textarea — fallback `monospace` 가 의도 신호) → `var(--font-mono)` (Sarasa Fixed K). layout.tsx 의 Space Grotesk `<link>` 제거 (의존성 0). 시각 변화: SVG = Pretendard 로 전환, textarea = Sarasa Fixed K mono 로 전환 (한글 박스 정렬 회복). PR #366. | 2026-05-22 |
| D-bp-ui-1 | **Blueprint `@axe/ui` 채택 + Tailwind 4 패치 2종** — Blueprint 가 `/Users/axe/axelabs/src/lib/` SSOT 를 `src/app/_axe-ui/` 로 sync. Blueprint 전용 패치: (a) dest path `src/app/_axe-ui/` (canonical `app/_axe-ui/` 와 다른 src/ source root), (b) `fonts.css` 의 `@import url(pretendard/d2coding)` strip — Tailwind 4 + Turbopack 이 토큰 파일을 globals.css 로 inline 한 뒤 위 @import 들이 다른 rule 뒤로 밀려 **CSS spec 위반으로 브라우저 silent drop** (Pretendard 미로드). 회피: sync 단계 strip + `layout.tsx <link rel="stylesheet">` (Clash Display 와 같은 패턴 확장). 35+ tsx 의 기존 `var(--navy)/var(--white)/var(--gray-ax)/--dark-border` 는 globals.css 에서 `var(--bg-base)/var(--text-primary)/var(--text-muted)/var(--border-subtle)` 로 alias — 비파괴 자동 전환. `<html data-theme="dark">` 기본, CSP `style-src`+`font-src` 에 `cdn.jsdelivr.net` 추가. `predev`/`prebuild`/`check-axe-ui` npm hook 으로 SSOT drift 감지. | 2026-05-22 |
| D-axe-ui-1 | **`@axe/ui` 단일 배포 채널 = git+ssh + axelabs.ai dogfood** — 디자인 시스템 (`/Users/axe/axelabs/`) 이 npm registry 없이 git+ssh 임포트 (`pnpm add 'git+ssh://...axelabs#tag'`) 만으로 모든 React 소비자 (Blueprint · frame admin · hive admin · docs.axelabs.ai MDX) 에 전파. axelabs.ai 회사 홈이 자기 자신을 dogfood — `axelabs.ai/ui` 라이브 쇼케이스가 깨지면 즉시 인지. Verdaccio / GitHub Packages / npm publish 모두 미사용 — 소비자 ≤3개 시점에서 부담만. v1.0 시점 재검토. Clash Display `<link>` 패턴은 Blueprint 와 일치 (Fontshare CSS @import 의 `f[]=` drop 함정 회피). | 2026-05-22 |
| D-bp-artifact-1 | **Blueprint artifact + PARA 지식 레이어 도입 — Blueprint 내부 meta-layer, MCPs 와 별 트랙** — Blueprint 의 typed fact unit (`Artifact`) 를 1st-class 도입. source 문서가 아니라 agent 가 직접 read 하는, 사전 추출된 사실 한 조각: per-field schema (versioned, `schema_id` FK) + per-field citation + confidence + audit_trail + paraLayer scope. MCPs (frame · hive · magnet · stream …) 는 domain-specific data system 으로 그대로 — Artifact 는 그 위에서 사실을 organize 하는 Blueprint 내부 meta-layer (별 트랙). **Schema authority = MCP service** — frame/hive/magnet/stream 등 각자 자기 도메인 schema 정의 + `/schemas` endpoint 로 노출, Blueprint 는 schema **registry 아니라 discovery / mirror** (fetch + cache + version). free-form 영역 (IC memo / Board / LP comm / Sector framework 등 MCP 권위 없는 영역) 은 **LLM 자율** (extract 시점 ad-hoc typed structure 또는 `freeform.llm@auto` content + citation wrap). 별도 system naming 거절 — "Blueprint 의 artifact + PARA structure" 라고만 부름. 5종 artifact 유형 예시 (`ICMemoArtifact` PROJECT · `BoardMeetingNotesArtifact` PROJECT→ARCHIVE · `LPCapitalCallArtifact` PROJECT · `SectorFrameworkArtifact` RESOURCE · `PortcoBoardKPIArtifact` AREA) — 이는 schema 미리 정의 아니라 LLM 자율 또는 IC/ic skill 의 own structure (frame.balance / hive.employee 같은 MCP authority 예시는 [/architecture/artifacts § Schema authority 분산](/architecture/artifacts#schema-authority-분산)). [D-bp-entity-1](/ops/decisions) 의 PARA 4 layer schema + [D-bp-entity-2](/ops/decisions) 의 workspace-level provenance 위에 **field-level** 로 진화. 상세 = [/architecture/artifacts](/architecture/artifacts). | 2026-05-23 |
| D-bp-artifact-2 | **Artifact 저장 = blueprint-postgres + JSONB content + JSONB citations** — Primary storage 는 Blueprint Postgres 16 ([D-config-16](/ops/decisions) cutover 완료) 의 신규 `Artifact` 테이블. 신규 인프라 0. 컬럼: `id` / `schema_id` (versioned schema FK) / `workspace_id` / `entity_id` (NOT NULL, [D-bp-entity-3](/ops/decisions) 정합) / `para_layer` (PROJECT/AREA/RESOURCE/ARCHIVE) / `content` (JSONB, schema 별 typed field) / `citations` (JSONB array) / `confidence` (numeric) / `audit_trail` (JSONB, propose/review/confirm/edit event 누적) / `parent_artifact_id` (PARA dispatch fork chain) / `created_at` / `updated_at` / `archived_at` (soft archive). Index: workspace / (entity, paraLayer) / schema / parent. content + audit_trail 무결성은 pg_jsonschema extension (확장 add-on) 으로 가드. 상세 schema = [/architecture/artifacts § 데이터 모델](/architecture/artifacts#데이터-모델). | 2026-05-23 |
| D-bp-artifact-3 | **Citation = 외부 source 의 stable ID** — Artifact 의 citation 은 **stable ID 만 보유, data 중복 0**. 6 kind: (1) `onedrive` (`drive_item_id` + `version` + `sheet`/`page`/`cell`), (2) `frame.*` (`entity` + `account`/`period` + `queried_at` — 회계 도메인 typed query snapshot), (3) `hive.*` (`entity` + `employee_id` + `queried_at` — HR 도메인), (4) `teams.message` (`chat_id` + `message_id`), (5) `mail.thread` (`thread_id` + `message_id`), (6) `external.web` (`url` + `fetched_at` snapshot 시점). large content / 원본 파일은 모두 원위치 유지 — OneDrive driveItem, frame DB resolution/journal IDs, hive DB employee IDs, Teams chat+msg, mail thread+msg, external API. artifact 가 frame `query_balance` 결과를 복사하지 않고 citation 으로만 가리킴 → resolver (`src/lib/artifact/citations/`) 가 fetch + cache. Trinity dashboard (Workspace × OneDrive × TeamsChat GUID 3축) 의 field-level 진화. | 2026-05-23 |
| D-bp-artifact-4 | **monolith first — 별도 KnowledgeStore service 분리 안 함** — Blueprint 가 이미 PARA OS home 이고 per-customer macmini isolation ([D1](/ops/decisions)) 안에서 Blueprint Postgres 동거가 자연. 추출 필요 시 나중. 대안 거절: **Graph DB (Neo4j)** — citation chain 이 graph 형태이긴 하나 query workload 가 hash-lookup + filter 위주, Postgres JSONB GIN 으로 충분 / **Vector DB (Qdrant) primary** — primary 로 두면 transactional consistency · FK · audit trail 다 잃음, semantic search 필요 시 pgvector extension / **ClickHouse** — analytical OLAP 강점은 있으나 artifact row count < 100k 수준의 transactional workload, column-store 이점 X / **MongoDB** — JSONB 동등 + sharding 미필요 + frame/hive Postgres 일관성, 별 DB 추가 부담 / **SQLite per-workspace** — multi-agent concurrent read-write 미적합. 확장 add-on (필요 시): `pgvector` (semantic search) · `pg_jsonschema` (JSONB validation) · `temporal_tables` 또는 `timestamptz` column (time-travel). 상세 비교 = [/architecture/artifacts § 저장 결정 + 대안 비교](/architecture/artifacts#저장-결정--대안-비교). | 2026-05-23 |
| D-bp-artifact-5 | **ctx skill 진화 — markdown PKM → artifact curation interface + markdown 점진 migration** — 기존 `ctx` (agent session delta → markdown append + parent KB propagation) 를 artifact store 의 curation interface 로 재정의. 대체 아님 — 진화. 흐름 4 단계: source → ingest → typed extraction (schema-aware LLM extract) → proposed fact (`audit_trail: { event: "propose", actor: "agent", ... }`) → ctx review (user confirm / edit / reject, UX 가 markdown diff + citation hover) → confirmed fact + audit (`audit_trail: { event: "confirm", actor: "user", ... }`) → agent reads via Query API (grep 안 함 — typed query + citation chain). markdown 은 보조 — review UX 의 diff 표면 + Archive 보존 + emergency cat (DB 장애 시). primary read path 는 Query API. 기존 `ctx sync` / `ctx review` / `ctx status` 3 mode 호환 유지 + artifact 모드 추가. **기존 markdown KB 는 점진 migration (항목별 AI-assisted ctx review)** — mass migration 안 함, 1 entry → LLM extract → proposed artifact → ctx review (사용자 confirm/edit/reject) → confirmed artifact + 원본 markdown entry `<!-- migrated: <artifact_id> -->` archive 마킹. 신규 fact 는 처음부터 artifact (markdown append 안 함). 5 단계 migration 흐름 상세 = [/architecture/artifacts § Markdown → artifact 점진 migration](/architecture/artifacts#markdown--artifact-점진-migration-ai-assisted). | 2026-05-23 |
| D-bp-artifact-6 | **Workspace lifecycle + Dispatch ≠ Close 분리** — Workspace.paraLayer 가 PROJECT / AREA / RESOURCE / ARCHIVE 4 layer transition 관리. (a) **Dispatch (anytime activity)** — Project 진행 중에도 artifact/file 을 다른 Workspace 로 흘려보냄. 2 mode: **copy** (새 artifact row, `parent_artifact_id` chain, source frozen) vs **link** (`artifact_link` 테이블 — multi-parent reference, 원본 1 row 만 유지). (b) **Close (한 번)** — `workspace.paraLayer` 한 번 변경 (PROJECT → ARCHIVE 보통, 또는 reclassify 다른 layer 로). (c) **Reclassify bidirectional 모두 허용** (ARCHIVE → AREA resurrect 포함, audit_trail 보존). (d) **Area cardinality = function 당 1개** — 중복 function Area 만들기 시 UI/LLM 가 "기존 Area 와 merge 권고". (e) AXEV 현재 Area 4 (**Finance / BOD / Legal / License (AC 관련)**), Resource = 0 (naturally emerge). (f) **OneDrive 폴더 mirror** — trinity-sync 가 2 시점 처리: dispatch 별 file 부분 이동 + close 시 workspace 전체 이동. (g) `artifact_link` 테이블 신설 (PK `(artifact_id, workspace_id)`, `link_type` ∈ `{'reference','sub_project','cross_link'}`, linked_at + linked_by). 상세 = [/architecture/artifacts § Workspace lifecycle](/architecture/artifacts#workspace-lifecycle). | 2026-05-23 |
| D-bp-artifact-7 | **LLM 호출 = Max plan OAuth 우선, Access = MCP tool 위주 (REST 최소화)** — 2 layer 정책. **Layer 1 (LLM 호출)**: artifact extraction / propose / review 의 LLM 호출은 **Claude Code OAuth token (Anthropic Max plan)** 우선. 비용 측면 per-token incremental 0 (Max plan 무제한 활용). Anthropic API direct (per-token billing) 은 **fallback / 대량 batch** 만 — 한 번에 1000+ extraction, vision-heavy ingest (pdf/pptx 대량 — 기존 `vision_ingest.py` 패턴 확장). Surface = Teams bot · 로컬 Claude Code CLI · 웹 (Max session) 모두 same OAuth. **Layer 2 (Access)**: artifact access 의 primary layer = **Blueprint MCP tool** (`query_knowledge` / `get_artifact` / `dispatch_artifact` 등). 별도 REST endpoint proliferation 회피 — 웹 UI 만 최소 REST (curation UX 용). 외부 agent 도 Blueprint MCP via OAuth-RP ([D-bp-mcp-1](/ops/decisions)). 권한 모델 single source ([D-bp-entity-17](/ops/decisions) EntityRole). 상세 = [/architecture/artifacts § LLM 호출 + Access 정책](/architecture/artifacts#llm-호출--access-정책). | 2026-05-23 |
| D-index-1 | **index 서비스 inception — AXE Labs 7번째 vertical, 투자 도메인 MCP backend** — 펀드 운용 lifecycle (소싱 → 실사 → IC → 포트폴리오 → 엑싯 → LP IR) 의 typed fact SoT. frame (회계) / hive (HR) 와 같은 layer. Blueprint 의 `ic` / `due-diligence` / `vc-deal-sourcing` / `portfolio-management` / `investor-relations` 5 skill 의 dataroom-bound run-time 산출물 (memo markdown / xlsx / yaml) 을 persistent typed artifact + cross-deal / cross-fund / time-travel query 가능한 형태로 승격. 상세 = [/services/index](/services/index). 5 skill 자체는 작성/조사 workflow 로 유지 — index 는 사실의 보존소. | 2026-05-27 |
| D-index-2 | **Rust + axum + sqlx + Day 1 artifact-first ([D-cortex-7](/ops/decisions) precedent)** — cortex 의 5-table reference 1:1 미러: artifact / citation / artifact_event / mcp_schema + owner_id RLS + `index_app` NOSUPERUSER role + `SET LOCAL index.actor` GUC. 사유 (D-cortex-7 4 사유 그대로): (a) artifact 의 discriminated union 과 Rust algebraic type 자연, (b) sqlx compile-time SQL check 가 schema/RLS query 안전성 보강, (c) MCP HTTP 서버 long-running 단일 process 의 panic-free 적합, (d) 단일 binary. Anthropic SDK 부재 → reqwest direct (`/messages` endpoint). MCP checklist 의 "Python+FastMCP 통일" 은 frame/hive/blueprint mcp 의 양파껍질 회고 기반인데 cortex/matrix 가 이미 break 한 precedent. 시작 = `cp -R /Users/axe/cortex /Users/axe/index` byte-by-byte. | 2026-05-27 |
| D-index-3 | **schema-per-entity Postgres 16 + 40xx 포트 범위** — frame/hive 패턴 1:1 미러. Shared schema (deal · target_company · fund_investment · sector_framework · lp_master · cross_journal_link · mcp_schema_version) + per-entity schema (financial_model · financial_driver · financial_scenario · financial_driver_value · financial_output · exit_matrix · dd_finding · ic_decision · portfolio_kpi_snapshot · risk_alert · valuation_snapshot · exit_signal · lp_communication · postmortem · audit_log). 펀드 entity (axe_ia_001 / axe_ia_002 / ...) 가 frame 의 `shared.entity` 와 정합 — frame 이 register 한 펀드를 index 가 그대로 사용. 포트: 4000 postgres / 4010 mcp blue / 4011 green / 4012 axe-index-proxy Caddy. cloudflared ingress `^/index(/.*)?$` → `host.docker.internal:4012`. 39xx (matrix) 다음 40xx 자연 할당. | 2026-05-27 |
| D-index-4 | **financial_model 6-table SoT + DSL formula + topo evaluator + xlsx round-trip** — 본 결정의 핵심. ic skill 의 `ic/finance/{3fs_*,scenario_deltas,exit_matrix,irr_analysis,irr_cell_ref,prob_tree,assumptions}` 산출물을 DB 1st-class entity 로 승격. 6 테이블: (1) `financial_model` (deal 별 1+, time_axis + horizon + locked_at + source_xlsx_sha256 + OneDrive citation), (2) `financial_driver` (code · kind=input/derived · formula DSL · dependencies[] · units · category), (3) `financial_scenario` (Upside/Base/Mgmt/Downside · probability · driver_changes narrative · parent_scenario_id fork chain — ic skill 의 PR-J 4-scenario 정합), (4) `financial_driver_value` (model × driver_code × scenario × period_index → value · is_override · PK 4-tuple), (5) `financial_output` (irr/moic/npv/exit_val/runway × scenario × period → value + inputs_hash sha256 reproducibility), (6) `exit_matrix_leaf` (scenario × timing × path × probability × proceeds_krw × axe_proceeds_krw + dead_leaf/concentration flag — ic skill `check_exit_matrix.py` 결과 캐시). DSL = Rust `pest` parser + 10 operators (`+ - * / min max if sum avg lag(driver,n) growth`) — xlsx formula 100% 가 아닌 IC memo cite 80~90% 만. Topo evaluator (`petgraph` topological sort) — driver DAG cycle detect + period 별 순차 평가. `compute_outputs(model_id, scenario_id)` 호출 시 driver_value snapshot sha256 → output row 의 `inputs_hash` 저장 → driver_value 변경 시 재산출 trigger. Round-trip: `ingest_financial_model_xlsx(deal_id, blob)` LLM-assisted (Anthropic Sonnet 으로 sheet/cell pattern → driver tree extract) + `export_xlsx(model_id, scenarios[])` 재생성. ic skill 의 4 sanity check (`xlsx_integrity` / `check_arithmetic` / `check_exit_matrix` / `citation_trace`) 가 `validate_financial_model` MCP tool 의 DB CHECK + trigger 로 흡수. 상세 = [/services/index/financial-model](/services/index/financial-model). | 2026-05-27 |
| D-index-5 | **fund_investment(deal × fund × round) — 3차원 N:M** — 본 결정의 두 번째 핵심. **deal 은 회사 단위 thesis, fund_investment 는 cash flow + IRR carrier**. 한 deal 이 (a) 여러 펀드에서 동시 투자 (Iippo: 액스 투자조합 1호 99,998,912 + 2호 100,000,000 = 199,998,912원, RCPS), (b) 다른 시점 follow-on round (Canopy: 1호 BW 5억 + v5 신주 follow 1억), (c) 다른 instrument (RCPS / BW / SAFE / 신주 / 보통주) 로 들어갈 수 있음. `fund_investment` row = (deal_id, fund_entity_id, round_label, instrument, committed_krw, invested_krw, share_count, price_per_share, entry_date, paid_date, pre_money_krw, post_money_krw, ownership_pct_post, ownership_pct_fd, status [committed/paid/locked_in/written_off/exited], conditions[] JSONB [Iippo 2호 의 6 PCC 같은 trigger]). **financial_model 은 deal 레벨** (회사 projection 은 fund 무관 동일) — `financial_output.axe_proceeds` 산출 → `fund_investment` 의 ratio 로 split → 펀드별 IRR = `irr(committed_at_paid_date, axe_proceeds × fund.ratio_in_round)` 독립 산출. 사용자가 강조한 "Sentry 1호/2호 IRR 각각 관리" 의 본질이 `fund_investment` row 분리로 자연 해결. 실 데이터 검증: Iippo 가 1:N (1 deal × 2 fund) 의 cleanest 케이스. 상세 = [/services/index/financial-model § fund_investment](/services/index/financial-model#fund_investment). | 2026-05-27 |
| D-index-6 | **Blueprint citation kind 7번째 `index.*` 추가 + Workspace ↔ deal N:1** — Blueprint artifact 의 citation kind ([D-bp-artifact-3](/ops/decisions) 의 6 kind: onedrive · frame.* · hive.* · teams.message · mail.thread · external.web) 에 **7번째: `index.*`** (deal · fund_investment · dd_finding · ic_decision · portfolio_kpi · financial_model · financial_output · valuation · lp_comm · risk_alert · exit_signal · postmortem · sector_framework · target_company). 예: IC memo 한 줄 "base case IRR 23.4%" 의 citation = `{ kind: "index.financial_output", model_id, scenario_id: "base", output_code: "irr", computed_at }`. xlsx cell ref 가 아닌 **DB cell ref** 가 primary citation unit. **Workspace ↔ deal = N:1** — Blueprint workspace 는 sector deep-dive / pipeline / fund container, deal 은 그 안의 artifact subject. ic skill 의 현재 "workspace.name = deal name" 가정 폐기 — deal-name-as-tag 로 진화. ic skill 폴더 규약 `ic/memo/v{N}.md` → `ic/deal/<deal_id>/memo/v{N}.md` 로 재구성 (workspace 단위 → deal 단위 artifact 그룹). 한 deal 의 IC convergence 후 별도 workspace spin-off 가 자연스러우면 link mode dispatch ([D-bp-artifact-6](/ops/decisions)) 로 cover. | 2026-05-27 |
| D-index-7 | **`/index/schemas` 권위 + 14 schema set 노출** — frame `/frame/schemas` 13 schemas + hive `/hive/schemas` 15 schemas 패턴 1:1 미러. SoT = `src/index/mcp/schemas.rs` (Rust 측, cortex 의 schemas.rs 미러). 첫 노출 14 schemas: `index.deal@1.0` · `index.target_company@1.0` · `index.fund_investment@1.0` · `index.dd_finding@1.0` · `index.ic_decision@1.0` · `index.portfolio_kpi@1.0` · `index.risk_alert@1.0` · `index.valuation@1.0` · `index.lp_comm@1.0` · `index.postmortem@1.0` · `index.sector_framework@1.0` · `index.financial_model@1.0` · `index.financial_output@1.0` · `index.exit_matrix_leaf@1.0`. Blueprint 의 [B-bp-artifact-schema-discovery](/ops/backlog) fetcher 에 `index` entry 1 줄 추가만으로 자동 mirror. 인증 required (JWTAuthMiddleware, frame 동일), versioning `@{version}` suffix, envelope `{ version, service, schemas }`. 상세 schema spec = [/services/index/schema-catalog](/services/index/schema-catalog). | 2026-05-27 |
| D-index-8 | **5 skill → service 진화 + `--push-to-index` mode** — `ic` / `due-diligence` / `vc-deal-sourcing` / `portfolio-management` / `investor-relations` 5 skill 의 진화 경로. **skill = workflow (LLM-heavy authoring), index = persistence (typed fact)**. (1) `vc-deal-sourcing` pipeline 표 → `index.deal` + `deal_stage_history` (영구 + cross-fund pipeline view), (2) `due-diligence` 체크리스트 → `index.dd_finding` + citation chain (finding 한 줄마다 출처 trace), (3) `ic` skill 의 18-section memo + 19-agent orchestration → run-time orchestration **유지** (LLM heavy 본질), 산출물은 `index.ic_decision` typed fact 로 push. memo PDF 본문 = OneDrive citation, scenario / IRR / postmortem cadence = typed field, (4) `portfolio-management` KPI 표 → `index.portfolio_kpi` time series (QoQ chart, cross-portfolio benchmark), (5) `investor-relations` LP 보고 → `index.lp_comm` audit + LP 별 last-contact view + AXE 펀드 성과 지표 자동 산출 (frame `lp_master` 결합). 새 mode = `/ic --push-to-index` — IC convergence (`/ic --finalize` 와 평행) 후 산출물의 typed fact 부분 (deal / ic_decision / financial_model / dd_finding / risk_alert / exit_matrix_leaf) 만 index 로 propose. ctx review queue 경유 후 confirmed → audit trail 시작. 기존 markdown / xlsx / yaml 산출물은 OneDrive 그대로 보존 (citation source). 상세 = [/services/index/skill-evolution](/services/index/skill-evolution). | 2026-05-27 |
| D-index-9 | **frame cross_journal_link mirror (펀드 회계 자동)** — index 의 `fund_investment` event (commit / paid / valuation change / exit) 가 frame 의 `commitment_ledger` (D-ops-22 펀드 회계 확장 — `[B-frame-fund-commitment-ledger](/ops/backlog)`) 와 자동 mirror 분개. 채널 = pg_notify (`index_events` 채널 from index-postgres → frame-postgres `LISTEN`, hive payroll → frame 패턴 1:1 미러). 이벤트: (a) `fund_investment.paid` → frame 의 capital call 분개 + commitment_ledger 차감, (b) `valuation_snapshot.recorded` → frame 의 평가손익 분개 (분기), (c) `fund_investment.exited` → frame 의 distribution 분개 + LP 비례 carry 산출. cross_journal_link 테이블 ([D-ops-22](/ops/decisions)) 가 양쪽 journal pair 무결성 보장. 이는 frame M2 (펀드 회계 확장) 의 자연스러운 client — index 가 frame 의 펀드 회계 trigger SoT. 단, M2 미완 시 index 는 stand-alone 가동 (event_outbox 보류 + 운영자 수동 review). | 2026-05-27 |
| D-index-10 | **3 deal validation fixture (Iippo / Sentry / Canopy) — Phase 0 acceptance bar** — Phase 0 의 schema correctness 검증 fixture. 3 deal 모두 ic skill 의 완전한 산출물 보유 (memo v4~v8 / scenario_deltas yaml / exit_matrix yaml / 3fs xlsx / irr_analysis xlsx / assumptions md). **Iippo** (킵코퍼레이션, AXE 199,998,912원 = 1호 99,998,912 + 2호 100,000,000, 1:N pure case) + **Sentry** (센티넬딥액티브, 1호 단독 5억 + 후속 5억 pro-rata option, 1:1 + future option case) + **Canopy** (사이클로이드, 1호 BW 5억 + v5 신주 follow 1억, multi-round 1:1×2 case) 가 fund_investment 의 3차원 N:M 을 모두 cover. Phase 0 acceptance bar: (a) 3 deal 모두 seed yaml → index DB ingest 성공, (b) ic skill 의 기존 `irr_analysis xlsx` 산출 IRR 과 index `compute_outputs(model_id, scenario_id)` 결과가 ±1pp 일치, (c) Iippo 1호 / 2호 IRR 각각 산출 가능 (별도 row), (d) Blueprint artifact 의 ICMemo citation = `{ kind: "index.financial_output", ... }` 로 정확 resolve. seed yaml SoT = `/Users/axe/index/seeds/{iippo,sentry,canopy}.yaml` (본 결정 PR 의 산출물). | 2026-05-27 |
| D-index-11 | **ic skill `--push-to-index` = 5th mode (FINALIZE 평행 track), atomic propose** — ic skill 의 기존 4 mode (INITIAL / REVISION / APPEND / FINALIZE) 에 5번째 mode 가 sequential 추가 아닌 **parallel track**. FINALIZE 는 `ic/final/` lock + PDF deliverable (OneDrive deliverable lifecycle), `--push-to-index` 는 typed fact persistence (DB lifecycle) — 둘이 같은 commit 에 묶이면 partial failure 시 rollback 모호. **Step 5.5** 신규 삽입 (gate_memo.sh PASS → humanize Stage 4 → pdf_quality 다음, postmortem_stub.py 자동 호출 이전): `--push-to-index` 플래그 detect → atomic `propose_deal_closure(deal_id, version, idempotency_key, payload)` 단일 batch MCP call → index 측 1 transaction 으로 모두 INSERT or all-rollback. **개별 propose tool 금지** (financial_model 따로, ic_decision 따로 → 중간 실패 시 inconsistent state). 산출물: ic/index_push_state/v(N).json (model_id, status, timestamp, errors 배열 포함) local checkpoint — retry-safe. 변경 범위 = SKILL.md (40-60 lines, Rule 25 + Step 5.5) + gate_memo.sh (80-120 lines post-V_COUNT) + orchestration-initial.md (50-80 lines) + build_3fs.py + calc_irr.py + postmortem_stub.py (~30-50 lines). 총 ~280-350 lines, **backward compat 100%** (flag 미사용 시 기존 동작). REVISION mode 와의 상호작용 = v(N+1) push 시 v(N) model 자동 supersede (last-write-wins, audit_trail 가 prior 보존). | 2026-05-27 |
| D-index-12 | **pmc (Post-Money Care) skill 신규 + portfolio-management / investor-relations 통합 3-phase deprecation** — IC 결의 ~ Exit/WD (5년+) 수명의 포트폴리오 케어 단계 통합 도구. 기존 2 prompt-only skill (`portfolio-management` 60 lines + `investor-relations`) 가 **개념은 정확하지만 실행 불가** (KPI 정의표만, 추출/저장/푸시 워크플로 없음) — pmc 가 둘을 흡수해 실행 가능 도구화. ic skill 의 19-agent 보다 lighter (8 sub-agent: data-fetcher / kpi-extractor / risk-alerter / valuation-updater / exit-signal-analyzer / board-pack-drafter / lp-comm-drafter / index-payload-composer). Trigger 3-tier: SCHEDULED (분기 첫 영업일 09:00 KST launchd) + EVENT (red alert 자동 fire — runway 6M 미만 / 핵심 인력 이탈 / burn_spike 30 percent 초과 / growth_slowdown / customer_concentration) + MANUAL (`/pmc --postmortem-fill` 또는 `--board-pack` 또는 `--push-to-index`). 폴더 = deal 폴더 안 `pmc/` 하위에 board_packs · kpi (snapshots + time_series) · risk/alerts · valuation/quarterly_nav · exit_signals · lp_comms · postmortem · index_push · cross_deal · manifests 10 sub-dir. **Postmortem 2-track 분리**: ic skill 의 `postmortem_stub.py` + `postmortem_reminder.py` 는 **유지** (gate_memo.sh PASS 시점 stub 생성 + launchd daily reminder = investment phase 책임), pmc 는 **fill + render + push** (`scripts/render_postmortem.py` 이관 + index.postmortem propose = portfolio care phase 책임). `references/postmortem-cadence.md` 는 양쪽 symlink (single SoT). **3-phase 마이그레이션** ([D-bp-artifact-5](/ops/decisions) 점진 패턴): Phase 0 (즉시) — pmc SKILL.md skeleton 등록 + portfolio-management/investor-relations 에 deprecation notice / Phase 1 (M7 Phase 1 launch 후) — 첫 quarterly cycle 실행 + KPI catalog → `pmc/references/kpi-catalog.md` copy + IR lifecycle → `pmc/references/ir-lifecycle.md` copy / Phase 2 (3개월 후) — 기존 skill SKILL.md soft-deprecate (Blueprint suggest 에서 pmc 로 redirect) / Phase 3 — 완전 archive. **5 risk_alert.kind enum 영구 freeze** (DB CHECK constraint): `runway_under_6m` / `key_personnel` / `growth_slowdown` / `burn_spike` / `customer_concentration` — portfolio-management SKILL.md 표 1:1 mirror, 새 kind 추가는 schema version bump 필요. | 2026-05-27 |
| D-index-13 | **Atomic `propose_deal_closure` MCP tool + idempotency key UUIDv5** — ic skill 의 `--push-to-index` 가 financial_model / ic_decision / fund_investments / dd_findings / exit_matrix_leaves / risk_alerts 를 개별 propose call (6+ round-trip) 시 partial failure risk: 첫 4개 commit 됐는데 5번째에서 schema validation fail → DB inconsistent state. 대신 **단일 batch MCP tool** `propose_deal_closure(deal_id, version, idempotency_key, payload)` 가 index 측에서 1 DB transaction 으로 묶음. 모두 INSERT or ROLLBACK (PostgreSQL serializable isolation). **Idempotency key** = `UUIDv5(namespace=deal_id, name="<version>::<content_sha256>::<actor_email>")` — ic skill gate_memo.sh 가 매 호출 동일 input 으로 동일 key 생성, DB UNIQUE constraint (`idempotency_record` 테이블, 24h TTL — hive `idempotency_record` 패턴 미러) 가 2nd call 을 409 + `context.prior_actor` 반환. **silent re-insert 절대 금지** — 두 ic session 이 동시 fire 시 race detect 됨. retry-safe: same input → same key → cached response. 본 tool 이 D-index-11 의 atomic Step 5.5 의 server-side counterpart. Phase 0 의 핵심 MCP tool (Phase 1 후속이 아닌). 비유: hive 의 `payslip_send_log` 의 `body_sha256` immutable 패턴 + frame 의 `idempotency_record` cross-entity dedup + post_journal 5계층 검증 의 atomic 정신 결합. | 2026-05-27 |
| D-index-14 | **3-layer error model + `IndexError` Rust enum SoT** — skill → index 모든 통신 에러는 일관 3-layer 표현. **L1 HTTP**: 401 Unauthorized + `WWW-Authenticate: Bearer resource_metadata="..."` (RFC 9728 정합, frame/hive 패턴). **L2 MCP body**: JSON envelope with `error.code` (영구 freeze enum, 예: `FINANCIAL_MODEL_CONFLICT`) + `error.message` + `error.context` (case 별 typed payload: prior_actor / prior_ts / idempotency_key 등) — silent fail 금지. **L3 skill handler**: ic skill 의 `lib/index_client.py` (또는 pmc 의 동형) 가 code 별 deterministic 분기 — `IDEMPOTENCY_CONFLICT` → 기존 표시 + retry 차단 / `VALIDATION_WARNING` → ctx review 사용자 confirm 요청 / `SCHEMA_NOT_FOUND` → upgrade hint / `SERVICE_UNAVAILABLE` → 로컬 drafts 보존 + retry 안내 / `CITATION_RESOLVE_FAILED` → cached value + warning chip. SoT = `src/index/error_model.rs` Rust enum (12+ case, deterministic mapping to McpErrorResponse) — silent fallback 금지. skill code 측 매칭 spec 은 본 enum 의 변경 시 deterministic 갱신 (test fixture 가 매 PR 검증). 양파껍질 ([D-bp-mcp-1](/ops/decisions)) layer 2 ("진단 불가, 모든 401 같은 메시지") 의 영구 차단. | 2026-05-27 |
| D-index-51 | **index-postgres 백업 (evidence_blob = 죽은 딜 SOLE 사본 보호) + teardown 역연산·감사 1급화 — frame reciprocal audit 마감** — [D-index-50](/ops/decisions) teardown 으로 10 딜(Sendy·apposter·dayton·DeveloperGroup·Eduon·JsEnl·Medistaff·Novachips·OpenResearch·Catalyst)의 OneDrive 원본 + 2 Blueprint workspace 삭제 → `evidence_blob`(328 blob/312MB)가 그 ~350 파일의 **유일 사본**. frame 이 index 의 Archive 설계를 reciprocal audit (A RLS gate · B dedup race · C size cap · D backup · E cross-deal refcount) → **2 FAIL 발견·마감**. **D (P0 — backup gap)**: index-postgres 가 `axe-backup` scope 에 부재 = SOLE 사본인데 백업 0 → 단일 실패점에서 영구 소실 가능. 수정 = `axe-backup` 에 index-postgres `pg_dumpall` 블록 추가 (매일 03:00 launchd · 312MB bytea → ~633MB hex dump → restic content-dedup 으로 ~274MB stored, snapshot `21735e04` 즉시 검증). **C (size cap)**: `register_evidence_blob` 에 512MiB 상한 가드 — bytea 1GiB hard-limit 아래에서 LOUD fail (초과 미디어는 inline 금지·citation 참조). **E (refcount + CAS 불변)**: cross-deal dedup blob 은 `deal_evidence→evidence_blob` FK(NO ACTION)가 참조 중 blob 삭제를 물리 차단 + teardown 이 index 행 미삭제로 안전. ⚠ 단 evidence_blob 의 [D-index-50](/ops/decisions) 마이그는 SELECT/INSERT only 를 명시 의도(주석 "UPDATE/DELETE grant 없음")했으나, 스키마 전역 `ALTER DEFAULT PRIVILEGES … GRANT … ON TABLES TO index_app`(20260526210000 artifact 스키마)가 *이후 생성된 모든 테이블*에 UPDATE/DELETE 를 자동 과다부여 → evidence_blob·teardown_event 도 열려 있었음(코드 INSERT-only 라 live 위반 0, by-construction 보장 아님; frame-audit E 의 "DELETE grant 부재" 기술은 당시 부정확) → **migration `20260606000004`(evidence_blob)·`20260606000005`(teardown_event) 로 UPDATE/DELETE 회수**, evidence_blob = append-only(INSERT/SELECT only) — content 불변 + index_app blob 삭제 불가가 by-construction. ★향후 orphan GC 는 별도 권한 role + refcount-guarded (`DELETE blob WHERE NOT EXISTS (SELECT 1 FROM deal_evidence …)`) 필수, per-deal 즉시삭제 금지. **reversibility (역연산 1급화)**: ① `export-evidence` CLI (evidence_blob → 파일 복원 + 디스크 재-hash 로 sha256 round-trip 검증, Sendy 28/28 0-mismatch) = teardown 이 되돌릴 수 있음을 증명. ② `teardown_event` audit 테이블 (deal·file_count·total_bytes·onedrive_path·blueprint_workspace_id·**sha_manifest** recovery map `[{path,sha256,kind,size}]`, RLS owner_only) = "무엇을 언제 어디서 떼어냈고 무엇으로 되돌리나" 의 단일 기록. **axe CLI 1급화**: `axe index teardown/restore/list-archive` — cross-service orchestrator (폴더해소 = Blueprint `Workspace.drivePath` 권위 → host index `ingest-evidence` archive → sha byte-for-byte verify → capture-first OneDrive rmtree + Blueprint workspace 삭제 → `teardown_event` insert). **경계** = axe CLI(orchestration·삭제·감사) · index binary(archive·restore·무결성). [D-index-50](/ops/decisions) `bin/deal_teardown.py` 스톱갭을 흡수. 108 test. | 2026-06-06 |
| D-index-50 | **Archive — 죽은 딜 evidence-blob 저장 + post-mortem schedule (Sendy 첫 완전 teardown)** — 2026-06-06 사용자 "Sendy 딜 저장·Resource화 후 종결 — OneDrive 폴더+Blueprint workspace 제거, 모든 파일 index 저장(frame evidence 참고), post-mortem 시점+할일". [D-index-49](/ops/decisions) dead-deal-harvest 의 §8 dispatch 실현: raw 파일=폐기가능·추출지식=영구, **폐기 전 흡수**. **gap**: index 가 citation(OneDrive 경로 포인터)만 보유 — 폴더 삭제 시 orphan. **구현 (2 subsystem, frame evidence 패턴 mirror·bytea 백엔드)**: ① `evidence_blob`(sha256 PK · content **bytea**=파일 bytes 자체 · content-addressed dedup, CAS RLS 없음) + `deal_evidence`(owner RLS 링크 · kind 7종 · original_filename · source_path provenance). bytea 선택 이유 = blue/green ephemeral 컨테이너 + 단일 DB 백업이 파일까지 커버(filesystem volume 불요·frame 과 차이). `get_evidence_blob` 은 deal_evidence(RLS) JOIN 접근통제. ② `postmortem_schedule`(deal · kind postmortem/revisit/follow_up · due_at · trigger_condition · action_items · status 상태머신) — PASS 결정의 disconfirming evidence 를 후일 actual 대비 검증. tool 6(register/list/get_evidence + schedule/list/update_postmortem, 29→35) + CLI `ingest-evidence`. **Sendy teardown**: 28 파일(6.6MB) 전부 흡수(dataroom 2 PDF+4 extract · finance 7 · ic_memo v2 · kb 6 · decision_log 8) + financial_model citation durable anchor(memo sha256) + post-mortem revisit(Q4 2026: sendyX 20+ customer·₩100M ARR / Series C ≤250억 / BEP). **검증(subagent, 삭제 전 게이트)**: 28/28 sha256 byte-for-byte(file↔store set-diff·in-DB content==hash·4.8MB PDF round-trip) · 의사결정 blob+typed fact 이중 보존(PASS사유·v1→v2 재calib·95.7%→35% IRR override 버그+버그파일 verbatim·post-mortem) · OneDrive 의존 0(self-contained) → SAFE TO DELETE. 108 test. ⭐ 부수: frame 에 bytea-vs-filesystem durability 통찰 전달(storage_url 가 백업·컨테이너 재빌드 survive 하나 점검). | 2026-06-06 |
| D-index-49 | **죽은 딜 harvest — why-passed/lost JUDGMENT 1급화 (`deal_judgment` artifact kind, dead-deal-harvest Pillar A)** — 2026-06-06 사용자 "죽은 딜 저장이 본질" (Blueprint PARA 철학 §11). live deal 관리는 moat 아님 — VC 지식의 압도적 대부분은 죽은 딜(시장맵·경쟁분석·섹터 thesis·valuation + 무엇보다 judgment "왜 패스했나")에 있고 보통 Archive 에 묻혀 증발 → 복리 corpus 로 harvest. **gap (recon)**: index 는 이미 passed/dead 를 *상태*로 1급 저장(deal.stage Passed/Writedown · 357 artifact)하나 judgment 층이 전부 finance-centric(왜 *숫자*가 그런가 — assumption/calibration). thesis-level **처분 JUDGMENT**("왜 passed/lost/died" + durable lesson, 예 Apposter "good company ≠ good deal"·"field DD kills thesis", Interstellar "high IRR ≠ Go")은 seed 주석·`fund_investment.conditions` 문자열에만 = typed·queryable 아님. **인식론 분리 (§0)**: claim(source-cited·live·갱신 = extracted_metric) vs **judgment(author·불변·supersede)** — `deal_judgment` 가 후자의 1급화. **구현 (D-index-45/46 기계장치 순수 확장, SQL migration 0 — store generic·kind/relation CHECK 없음)**: ① 새 artifact kind `deal_judgment`(payload deal_code/verdict/thesis/rationale[]/lesson/sector/tags[]/decided_by/at), FROZEN verdict `passed/lost/dead/invested/missed`, content-identity `deal_code·verdict`, para_layer=area. ② 새 FROZEN artifact_ref relation `supersedes`(judgment 불변 — 재판단=새 artifact 가 prior supersede). ③ seed `judgment:` block 에 `verdict:` 확장 (seed=SoT) → `seed-ingest --emit-judgment` 가 emit (`index_field(deal,"deal:disposition")` citation + 선택 corpus backing anchored_to, confirm-on-create, content-identity idempotent). ④ schema `index.deal_judgment` (/index/schemas active 14→15) + `verdict` frozen-enums 발행 → frozen_enums_hash 재-pin ([D-index-47](/ops/decisions) drift tripwire 정상 발화). ⑤ read tool `query_dispositions`(verdict/sector/tag 횡단)·`get_deal_judgment`(단일 deal) — 27→29 tool. ⑥ 23 canonical seed 전체 verdict backfill (헤더/conditions 에서 TRANSCRIBE, 4 병렬 agent + orchestrator QC, 날조 X) → **16 passed + 6 invested + 1 lost**. **검증 (additive-only 3중 증명)**: store 357→**380**(+23 deal_judgment), 재ingest 시 assumption/calibration/comp/base_rate 전부 +0(319 idempotent-skip), artifact_event op = propose 23 + confirm 23 only(edit/dispatch/archive 0), relational `deal.updated_at` 미전진(2026-05-30 고정), validate-seeds Δ=+0.00. 103 test, sqlx --check clean, blue/green 배포. **결과**: "왜 우리는 스마트링/교육/supplement 딜을 패스했나, durable lesson 은" 이 typed cross-deal 질의 + backing comp evidence 해소 가능 (Apposter→"Hardware wearable EV/Rev band" anchored_to). **B·C 설계 ratify (후속 backlog)**: B = sector harvest = artifact-first `sector` Resource (SoT `seeds/_sectors.yaml`, para_layer=resource, comp/base_rate/deal_judgment citation) + 휴면 빈 `sector_framework` 테이블 폐기 → [B-index-sector-harvest](/ops/backlog); C = cross-deal pattern (`query_sector`·`find_similar_deals` + **벡터 semantic** = hot sector Resource 색인, §5 "벡터=Resource 위 index, 가치 클 때만") → [B-index-cross-deal-pattern-query](/ops/backlog)·[B-index-sector-vector-index](/ops/backlog). **5축**: 본질(죽은 딜 judgment = 진짜 moat 의 1급화)·안전(additive·frozen-drift gate·fail-closed verdict·append-only)·결과(380 fact queryable judgment corpus)·혁신(claim/judgment 인식론 분리 + supersede 불변)·퀄리티(103 test·frozen verdict·transcribe-not-invent). | 2026-06-06 |
| D-index-48 | **브라우저 SSO 현황 페이지 — Blueprint OIDC 로그인 시 세션-게이트 firm-read 상세 열람** — 2026-06-04 사용자 "웹페이지에서 blueprint 기반 sso login 되면 상세 투자정보 조회 가능하도록". 현 `/index` 는 public aggregate(민감정보 0, leak-tripwire). **추가**: Blueprint OIDC **Authorization Code + PKCE(S256)** 웹 플로우 — `/index/login`(PKCE+state 서명쿠키→`/oauth/authorize` 리다이렉트, Entra 세션 재사용 = 진짜 SSO) · `/index/callback`(`/oauth/token` 교환→`auth::verify_blueprint_rs256` 재검증→email→세션쿠키) · `/index/logout`. 세션 있으면 `/index` 가 **firm-read 상세**(deal별 IRR(E[CF])·E[MoM]·P(loss) + 펀드 1·2·3호 성과 + calibration), 없으면 기존 aggregate + 로그인 버튼. **보안**: 세션·tx 쿠키 = HMAC(`INDEX_JWT_SECRET` 재사용, httpOnly+Secure+SameSite=Lax, 단명 exp) · state CSRF 가드 · 콜백 토큰은 RS256+iss+aud 재검증 · 무세션 경로 leak-tripwire 보존(공개 페이지 불변). **권한**: 세분화(IC allowlist)는 추후 — 우선 **AXE 인증 전체 firm-read**(superuser pool 전역 SELECT + 세션 게이트가 보호, RLS actor 불요). **Blueprint 의존(위임)**: `isAllowedRedirectUri`(platform-oidc.ts)가 현재 loopback+claude.ai 만 허용 → `https://axe.axelabs.ai/index/callback` 거부 → web redirect policy + `axe-index-web` static client 추가는 **병렬 IdP 세션([D-axe-idp-1](/ops/decisions))에 위임**(머지 전 web 로그인 비활성, index 코드 ready, env `BLUEPRINT_INDEX_CLIENT_ID`). index-only 구축. **✅ 2026-06-04 LIVE**: #383 merged(`19f30042`) + blueprint blue/green 배포(green active, edge 200) + index env flip(`INDEX_PUBLIC_BASE_URL`=https://axe.axelabs.ai + `INDEX_WEB_LOGIN_READY`=true) + recreate. authorize→Entra 수락 e2e 통과(운영자 첫 SSO 1회 잔여). 배포 시 3rd 세션 미커밋 WIP 는 stash 격리·복원(무손상, prod 미배포). | 2026-06-04 |
| D-index-47 | **skill ownership/distribution 아키텍처 ratify + P0 reconcile (index=SoT 거짓 해소)** — 2026-06-03 사용자 "위생 본질 전략 순" 의 *전략* leg (opus 서브에이전트). 직전 멀티에이전트 플랜 ratify: **index=truth(SoT bytes·semver·schema-contract·audit) · Blueprint=road(universal git→webhook→rsync 분배, 신규 transport 0) · surface=run(Agent SDK 로컬 디스크 읽기)**. **P0 "STOP THE LIE" 완료**(index commit `3b39a03`): `index=SoT` 가 `ingest` 에 거짓이었음(Blueprint base mirror 가 v2 구조추출로 AHEAD) → blueprint→index port 로 index 현행 superset 화(SKILL.md 285→348 · ingest.py 1443→2035 · test 신규, `diff -qr` 동일). ic byte-identical · pmc index-only 확인 · `INDEX_OWNED.txt` manifest + 죽은 launchd 폐기. **검증된 정정**: (a) 폐기 launchd 의 target script 는 실재(오늘 수정)·방향 안전(index MCP→blueprint skills-cache drift 검증, 파괴적 아님) — P2 binary(`index/bin/index-skill-sync.py`) 미존재로 비기능 → 폐기. (b) **⚠ 런타임은 아직 blueprint origin/main 서빙**: LIVE `com.axe.blueprint-skills-sync` launchd 가 blueprint→`~/.claude/skills` rsync — index=SoT 는 disk/git 에선 참이나 **런타임 반영은 P2(index→blueprint mirror+push) 필요**. (c) `owner:index` frontmatter 미기재(manifest 가 de-facto SoT) → follow-up. **잔여**: P1 stamp(provenance+schema-drift gate, index-side 安) · **P2 CI mirror(런타임 fix — blueprint write+push, production 영향)** · **P3 contamination purge(ic/dd/vc-sourcing/ir/pmgmt/legal 을 universal base 에서 제거 — 전 customer 컨테이너 영향, 高위험)**. P2/P3 = explicit go + blueprint PR 필요. | 2026-06-03 |
| D-index-46 | **seed = SoT for judgment facts — hardcoded backfill 폐기 (B-index-judgment-in-seeds ✅)** — 2026-06-03 사용자 "위생 본질 전략 순" 의 *본질* leg. index commit `8ec2c10`. [D-index-45](/ops/decisions) 가 318 judgment artifact 를 1회성 hardcode migration(`backfill.rs` 2221 LoC + `corpus.rs` 603 LoC)으로 넣은 것 = seed prose 의 중복 = transcription 부채. 제거: **seed.yaml 이 judgment 의 단일 SoT**. ① seed schema: per-seed `judgment:`(assumptions[]+calibrations[]) + 공유 `seeds/_corpus.yaml`(comps+base_rates), serde + fail-closed validate(identity-unique·FROZEN scrub_kind/relation·anchor XOR·band/prob). ② seed-ingest emit leg(`--emit-judgment`): relational ingest 후 judgment artifact 를 propose_judgment_fact 로 emit, comp/base-rate anchor 를 **natural name → corpus artifact_id** 해소, idempotent·confirm-on-create. ③ 23 seed + _corpus 마이그레이션(backfill.rs/corpus.rs 에서 verbatim) 후 두 모듈 **삭제**. **HARD GATE PASS**: (1) 전 23 seed 재ingest = **+0 new**(content-identity 일치). (2) fresh-reproduction — committed wipe(318→0, relational 무손상) + seed-ingest 단독 +318 재현, byte-identical, 유일 delta = **42 stale dup citation pruned**(corpus.rs 중복 = 제거 대상 부채; 587→545). (3) backfill 모듈 삭제, seed-ingest 유일 경로. (4) additive-safe(event propose/confirm only·append-only trigger intact·validate-seeds 23 Δ=+0.00). 정확 구성: **357 = 218 assumption + 58 calibration + 35 comp + 7 base_rate + 39 기존**. 51 test(6 invariant 를 backfill.rs→seed.rs 이전, 23 seed YAML=SoT 위에서 assert). **신규 deal 은 seed-ingest 로 자동 artifact화** — hardcode transcription 0. **5축**: 본질(seed=진짜 SoT)·안전(2중 증명+append-only intact)·결과(2824 LoC 삭제+자동화)·혁신(natural-name anchor 해소)·퀄리티(51 test+fail-closed validate). | 2026-06-03 |
| D-index-45 | **artifact-first judgment layer — 증거층↔판단층 결합 (Epic 1, 2-wave supervised)** — 2026-06-03 사용자 "Epic 1 같이 검토하고 들어갑시다. 실제 구현은 서브에이전트로" + "본질에 집중, quick fix 금지". index commit `1c707e1`. **휴면이던 artifact store(39 fact — Apposter 추출치뿐)를 relational compute substrate(23 deal)와 결합** — 모든 투자판단 fact 를 store 의 일급 typed+cited+audited artifact 로 승격. **설계 (검증으로 확정)**: ① side-bridge stringly-typed 테이블(quick-fix) 거부 ② relational 전면 재작성(안전 위반) 거부 → propose API 가 kind 에 generic 이고 `artifact.kind`·`citation.kind` 에 CHECK 없음 확인 → **migration 0**. 4 신규 kind: `assumption`(보정 가정)·`calibration`(surface↔calibrated delta)·`comp`(외부 비교)·`base_rate`(경험적 기저율), schema SoT `mcp::judgment_schema_defs` → `/index/schemas`(active 10→14)+`mcp_schema` upsert. FROZEN enum: `scrub_kind` 7(fat_tail_comp_scrub·genuine_wipeout·par_entry·dilution·over_pessimism_floor·ramp_haircut·multiple_anchor) + artifact_ref `relation` 4(calibrated_from·scrubbed_from·anchored_to·contradicts). **링크 = 일급 citation(side-table 아님)**: `index_field` ref `{deal,field}` → relational field_ref(예 `scenario:base:exit_multiple`·`output:irr_expected_cashflow`) + `artifact_ref` ref `{artifact_id,relation}`. `propose_judgment_fact` 가 `propose_extracted_fact` INSERT shape 재사용(multi-citation·content-idempotency·confirm-on-create·fail-closed guard). 2 read tool: `get_judgment_provenance(deal,field_ref)`·`list_calibrations(deal)`. **결과**: 23/23 deal → **357 fact**(assumption 218 + calibration 58 + comp 35 + base_rate 7 + 기존 39), 0 orphan judgment value. 모든 scenario 확률·exit multiple·recovery·ramp 가 backing assumption 보유 + AUDIT-TRAIL surface→calibrated delta 마다 calibration artifact 가 scrubbed_from comp 인용(예 Apposter MoM 8.60x→1.48x scrubbed_from Oura 10x PSR via fat_tail_comp_scrub). **안전(additive-only 3중 증명)**: artifact_event op = propose/confirm 만(edit/dispatch/archive/restore 0) · relational updated_at 가 seed-ingest(05-30) 이후 미전진 · validate-seeds Δ=+0.00. 48/48 test(backfill self-contract 포함) · sqlx --check clean. **과정**: wave1 = machinery + 14/23 — **adversarial gate 가 61% 미완 적발**(per_deal 일부 aspirational, 병렬 agent crate 충돌) → 운영자 직접 미실행 subcommand 실행 +4 → wave2 = 미작성 5딜(Medistaff·Nanora·Novachips·OpenResearch·Superman) author + **6 rival backfill module → 1 `backfill.rs` + `corpus.rs` 통합**. **5축**: 본질(artifact-first 실재화 = 판단 기억)·결과(357 fact queryable)·안전(additive 3중+gate)·혁신(scrub→comp 역추적 provenance·우리 epistemic 차별점)·퀄리티(48 test·frozen enum·0 dangling ref). **잔여(방향)**: judgment data 를 structured seed field 로 이전 → ingest 가 artifact 파생(현 1회성 transcription) [B-index-judgment-in-seeds] · Epic 2 confidence load-bearing · Epic 3 self-calibrating prediction→outcome loop. | 2026-06-03 |
| D-index-44 | **ingest 데이터품질 + lifecycle 안전 — metric_kind 세분 + 회귀 스위트 (5축 평가 후 병렬 2 unit)** — 2026-05-30 사용자 "지금 가능한 작업 서브에이전트 진행. 본질·퀄리티·결과·안전·혁신". [D-index-43](/ops/decisions) 잔여를 5축 평가 → 최고가치 2개 병렬(non-conflicting repo). **(X) metric_kind 세분** (blueprint PR #380 merged `931284b9` → `~/.claude/skills/ingest` webhook sync): reconcile 가 스스로 노출한 근본결함 — coarse `valuation` 이 절대 EV(270억) + EV/EBITDA 배수(9x) + 음수 helper(−74) 혼재 — 를 source 에서 fix. order-priority 분류기(`moic`→`multiple`→`valuation`) + per-kind curation: `valuation`(절대 EV/EqV/proceeds, currency fmt)·`multiple`(EV/EBITDA·EV/Rev·P/E·PSR·PBR·배수)·`moic` 독립. curation: multiple 은 양수 0~100x band·valuation 은 양수 절대값만 → 음수 EV/EBITDA helper drop. test 52/52, irr·moic·cagr **0 regression**(XIRR function-path 무영향). **(Y) lifecycle 회귀 스위트** (index `c8b3746`): 8 test — idempotency·1:1:1·status 파생·confirm/reject·append-only(grant+trigger 이중)·RLS 격리·reconcile·**seed-draft non-ingestability**(serde reject 로 증명). tx-rollback isolation + graceful skip, 35 pass, 0 residue, offline-safe. ⭐ **발견(버그 아님)**: append-only trigger 가 `ON DELETE CASCADE` 도 차단 → event 보유 artifact 는 normal session 삭제 불가 = **audit 영속성 보장**(operational invariant). **통합 결과**: 정제 classifier 재ingest → store refresh → artifact store split 반영: **valuation 12 + multiple 4**(이전 conflated 10) + irr 8·cagr 7·moic 4 + figure 4 = 39 facts. extractor 결함이 정량 데이터로 노출(reconcile)되고 source 에서 닫힘 — **self-correcting 루프**. **5축**: 본질(근본 데이터품질)·결과(split 가시)·안전(회귀 lock+audit 영속)·혁신(unit-aware 분류기+self-correcting reconcile)·퀄리티(52+35 test). | 2026-05-30 |
| D-index-43 | **artifact-first lifecycle 완성 — Query API + ctx review + reconcile + seed-draft scaffold ([D-index-42](/ops/decisions) 잔여 4 완결)** — 2026-05-30 사용자 "서브에이전트로 종결 후 보고". D-index-42(propose)가 남긴 4개를 2 unit 순차 구현(supervised subagents) + blue/green 배포. index commit `3eece93`(lifecycle)+`118568a`(seed-draft). **(1) Query API read path** — `query_artifacts`(para_anchor/kind/metric_kind/status 필터)·`get_artifact`(payload+citations+event history). status = 최신 `artifact_event.op` 파생(propose→proposed/confirm→confirmed/reject→rejected; edit·dispatch 는 직전 유지) — agent 가 grep 대신 typed query. **(2) ctx review** — `confirm_artifact`(op=confirm; edit_payload 시 payload UPDATE+before/after 감사)·`reject_artifact`(op=reject+reason, row 보존). proposed→confirmed/rejected. **(3) L3-lite reconcile** — `reconcile_artifacts`: metric_kind 별 value spread flag, 불일치 `{value, source, location, status}` 전량 surface (silently 택1 금지). Apposter irr spread 86%(Exit IRR 0.572 vs Min IRR 0.08) + 5 group 전부 flag. **(4) L2 본령 seed-draft** — `draft_seed_from_artifacts`: deal artifacts → **보수적 seed.yaml SCAFFOLD**(`index draft-seed` CLI + MCP). ⭐ **날조 금지를 구조로 강제**: surface metrics(57.2% 등)→AUDIT TRAIL 주석+citation only / scenario probability·calibrated scenario·wipeout·baseline·intake = 전부 `~ TODO` / valuation 후보 다수(270억 vs 349억)→자동선택 거부 / draft 는 의도적 non-ingestable(validate-seeds 가 `~` placeholder 에서 fail) — judgment gate 가 문서 아닌 타입시스템으로 강제. coverage(Apposter): auto_filled 0 / needs_human 18 / surface_metrics 29 — 사람은 skeleton·number-hunt 절약, calibration([D-index-24](/ops/decisions)/26/21) 판단은 보존. **전 tx RLS 정식경로**(set_current_user), build clean online+offline(sqlx guard), 27 test pass, 6 신규 MCP tool live(blue/green, ext healthz 200). → **artifact-first 전 lifecycle 가동**: propose→query→review→reconcile→draft. **잔여(축소)**: ctx review UI(Blueprint markdown-diff 표면, 현재 CLI/MCP only) · Query API 를 /ic·seed-building 의 primary read path 통합 · extractor metric_kind 세분(valuation 이 EV+EV/EBITDA 혼재 — reconcile 가 노출한 finding) · 전 deal artifact화(현재 Apposter 1건) · L4 versioned diff. | 2026-05-30 |
| D-index-42 | **ingest 고도화 L2(부분) — extraction → proposed artifacts (artifact화, artifact store 첫 가동)** — 2026-05-30 사용자 "ingest 때 artifact화 한다던 것 구현됐나?". [D-index-41](/ops/decisions) L1(extraction→JSON sidecar) 후속 — sidecar 의 fact 를 **index artifact store 에 proposed artifact 로 적재** ([D-bp-artifact-5](/ops/decisions) 흐름 "source→ingest→typed extraction→**proposed fact(audit_trail propose)+citation**" 의 전반부 실현). **발견된 gap**: index 의 artifact/citation/artifact_event store ([D-index-2](/ops/decisions) cortex mirror, Day-1 schema) 가 **0행 — 한 번도 안 쓰임**. 23-deal 은 relational deal-domain 테이블에만 존재, artifact-first 층은 dormant 였음 (정직히 미구현). **구현** (index commit `4ca5868`, blue/green 재배포 live): **`propose-from-ingest <dataroom>` CLI + `propose_artifacts_from_ingest` MCP tool** — `*_xlsx.cells.json` key_outputs + `*_pdf.figures.json` figures → 각 fact = `artifact`(kind=extracted_metric|extracted_figure, payload value+formula+metric_kind+location, confidence, para_layer=resource) + `citation`(xlsx_cell|pdf_figure, ref=cell/page 증거) + `artifact_event`(op=propose, actor=system:ingest). **RLS 정식 경로** (index_app NOSUPERUSER + index.actor GUC — `db::set_current_user` 첫 실사용자, superuser bypass 아님). **idempotent** ((owner,kind,source_file,location), 재실행 0 new). **⭐ before/after (Apposter)**: artifact store **0 → 35** (31 metric + 4 figure, 1:1:1 artifact:citation:event). Exit IRR 57.2% 가 이제 typed queryable artifact (`metric_kind=irr`, citation `Return!Y62`, propose event) — D-index-41 에서 surface 된 fact 가 이제 **store 적재·인용가능**. append-only+RLS live 검증 (타 actor 0행, event UPDATE/DELETE 거부). **잔여**: ctx review(confirm/reject) + Query API read path + L2 본령(seed/financial_model 초안 자동생성) + L3 cross-source reconciliation. | 2026-05-30 |
| D-index-41 | **ingest 고도화 L1 — extraction-not-transcription + source-type-aware structured extraction (재무모델·IR 정문 손실 해소)** — 2026-05-30 사용자 "ingest 역량 끝까지 고도화, 서브에이전트로, before/after 만". [B-index-ingest-structured-extraction](/ops/backlog) 의 **L1 ship** (설계 ratify 동반). **문제**: ingest 가 dataroom xlsx/pdf 를 md 로 photocopy 하던 게 lossy — xlsx 는 값만 표로, 수식은 40개 truncate 후 `<!-- formulas: +182 more -->` 주석에 매몰 → return model 의 IRR/MoM 기계추출 불가 (23-deal 적재 시 수작업 발굴해야 했던 근본 원인). 정문 손실은 ic·index 에서 복구 불가 (GIGO). **L1 구현** (blueprint PR #379 merged → `~/.claude/skills/ingest` v2, launchd webhook sync): **convert_xlsx v2** — `{stem}_xlsx.cells.json` sidecar (시트별 full grid: value+formula+number_format+label, named_ranges, **key_outputs[]**) + **key_outputs 자동탐지** (XIRR/IRR/MIRR/NPV/XNPV 함수 + IRR/MoM/NPV/CAGR/valuation/EV/배수/수익률/밸류 라벨 정규식; numeric-value + rate-타당성 게이트로 false-positive 차단) + md `## Model Summary` / `## Key Outputs (detected)` / per-sheet formula↔value 표(truncated 주석 대체) / `## Named Ranges`. **convert_pdf v2** — `{stem}_pdf.figures.json` (라벨 인접 재무 figure sweep, precision-first) + `## Detected Figures`. **불변식 준수**: 숫자는 mechanical(openpyxl/pdfplumber) only ([D-index-15](/ops/decisions) vision-boundary), 추출 fact 마다 citation(sheet!cell / page) 자동. **⭐ before/after (Apposter 20-sheet return model)**: BEFORE = Exit IRR `=XIRR(L85:Q85,L79:Q79)` 가 `+182 more` truncated 주석에 매몰, 기계추출 불가. AFTER = **31 key outputs 자동 surfacing** — Exit IRR **57.2%/50.4%**(Case B 49.6%/43.3%) · Exit MoM **8.60x/7.12x** · Entry EV **270억** · Exit **9x** EV/EBITDA, 전부 값+수식+라벨로 파일 상단. (직전 23-deal 의 Apposter agent 가 수작업 발굴한 수치가 이제 mechanical 추출.) test 40/40 PASS · 기존 포맷(docx/pptx/csv/image/zip) 무변경 · 신규 의존성 0 · datetime→ISO 직렬화 버그 fix 포함. orchestrator QC: agent draft 의 broad-recall false-positive(date cell·mislabel CAGR 25M) 를 numeric+rate 게이트로 34→31 정정(true output 전량 보존). **잔여 (L2-L4, 후속)**: L2 cells.json→index typed intake/financial_model **seed-draft 자동생성**, L3 cross-source reconciliation(deck vs xlsx vs cap table 불일치 flag), L4 versioned re-ingest diff. | 2026-05-30 |
| D-index-40 | **Render/리얼초이스(23rd) 적재 + par-entry cheap-option = E[CF] 극단 사례 ([D-index-25](/ops/decisions) poster child) — 데이터룸 소진** — 2026-05-30 사용자 "더 추가할 프로젝트?". 전체 데이터룸 스캔 → 적재가능 신규 = Render 1건. **Render = 리얼초이스/트루비아**(데일리퓨어크레아틴, 크레아틴 건기식 D2C). dataroom 有·IC 미완 → best-effort SCREEN, status='passed'(미투자 — ⚠ 리얼초이스/트루비아는 AXE **플랫폼 고객**(realchoice vault·Truvia frame 회계)이나 **고객 ≠ 투자집행**; 주금납입·조합결성 증거 없음). ⭐ **핵심 — par-entry cheap-option 이 E[CF] 를 오해소지로 끌어올림**: AXE 진입 = 5,000만 @ 100원 = **액면=순자산(93원) = par/book value**(트루비아 **벤처기업 확인 enabler** 목적 개인투자조합 신주, 정상 priced VC 라운드 아님). par 진입이라 **어떤 성공도 거대 multiple** → upside 28.0x(P 0.12). 결과 **E[CF] 35.13%**(랭킹 4위 수준)이나 **E[MoM] 4.53x·P(loss) 68%·median=손실(0.40x)**. ⭐ **fantasy([D-index-26](/ops/decisions))와 구분**: exit multiple 은 0.8-1.4x commodity 정합 scrub 완료(Oura/EGA식 인플레 아님) — 높은 E[CF] 는 **par 진입의 구조적 산물**이지 multiple 환상이 아님. 고로 Render 는 [D-index-25](/ops/decisions)("E[CF]=fat-tail winner 가 끄는 mean → E[MoM]+P(loss) 동반 필수")의 **poster child**: **E[CF] 단독 랭킹은 par-entry 딜에서 오해 유발** — Render 35% 는 top deal 이 아니라 **68% 손실확률 par 진입 cheap call option**. SCREEN=PASS(commodity supplement·moat 약함·median 손실·보통주 무보호). 단 5,000만 = 트루비아 벤처확인 enabler + 고객관계 cheap option 으로 재무 IC 와 **분리 의사결정** 가능. EGA(RCPS·매출16억·올리브영)·Nanora($9M cap)보다 early·고위험. deal_id `eb83b883`. **데이터룸 소진** (DB 23): 잔여 = Whale=위시켓(executed 포폴이나 원 IC/모델 부재, 자료 확보 시) · Purple AI/TR Corp/엘리시움(DHP 빈 폴더) · Prj_Artemis(AXE 자체 제품) · 델리후레쉬(RFP) · 이노씨앤에스/Curi AI/가람봇/딥트리/블루밍(thin lead) = 전부 비-딜/자료대기. **23-deal canonical E[CF] 랭킹** (⚠ par-entry 주의): Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > **Render 35.13(⚠par cheap-option, P loss 68%·median 손실)** > Canopy 31.8 > Interstellar 30.5 > Hancom 23.9 > EGA 23.3 > (Superman 20.8 별도) > Catalyst 16.99 > 데이톤 16.57 > Infinity 16.5 > Eduon 15.0 > 디벨로퍼그룹 14.76 > 수성별 14.0 > Sendy 11.7 > Nanora 10.1 > Novachips 9.2 > Apposter 8.34 > 유비랩 4.06 > Medistaff −0.59 > JS E&L −1.97 > Open Research −25.85. index commit `de47a2c`. | 2026-05-30 |
| D-index-39 | **Archive batch 6-deal 적재 (17~22th) — 전부 correctly-avoided(PASSED) — DB 22** — 2026-05-30 사용자 "1_Project (Archive) 6건 모두 best effort 검토". 6 병행 agent + orchestrator 양방향 QC. **전부 archived=미투자** → [D-index-24](/ops/decisions) calibrated canonical(surface 헤더 audit-trail). **딜별**: **Medistaff**(의료진 플랫폼, screen) E[CF] **−0.59%** — founder 형사 jeopardy(블랙리스트 방조·증거인멸 검찰송치) + 두나무 lead 선점. **Open Research/oo.ai** E[CF] **−25.85%**(P loss 90%) — ⭐ **"deal structure ≠ company quality"**: 회사는 Series A 2,000억 라운드 중이었으나 본 거래는 창업자 김일두(전 카카오브레인) **개인 distressed 담보 secondary bridge**(도박·사채 변제용) → 직후 도박/무단 지분매각/서비스중단/팀 9-of-9 이탈 표면화. 계약서 당사자 공란=미체결. **JS E&L**(2차전지 부품, transcribe) E[CF] **−1.97%** — EV 캐즘, 자본잠식 임박·누적결손 56.85억, surface exit PER 16x(2차전지 고배수)→NPC 2x·AJ 8x scrub. **Catalyst/클래스카드**(교육 PE buyout, transcribe) E[CF] **16.99%** — ⭐ index **2nd buyout + 첫 PEF/GP-structured**(AXE=GP, 삼일 PwC 옥션 입찰, committed=consortium equity 170억 ≠ AXE direct; GP commit ~5억+carry). surface Gross 30.86% → 10x flat exit를 교육 comp 5-9x로 scrub + 60% LTV wipeout. **"높은 IRR≠Go"**: first-time GP 가 600억 consortium 0 commit + 학령인구 + leverage. 미체결(SPA 없음, Mgmt/Exit 폴더 공란, archived before SPA). **데이톤/DATON**(DC AI Ops, screen) E[CF] **16.57%** — 흑자전환 100억 매출·DC tailwind·레퍼런스(에코프로BM/현대제철) 진성이나 terms-void(valuation/instrument 전부 assumed) + AINATION 합병 미확인. **Apposter/b.ring**(스마트링, transcribe) E[CF] **8.34%** — ⭐ **"field DD kills thesis"**: 현장실사(Bic Camera 방문 + McKinsey JP)가 moat 사망 확인(commodity 광동 OEM, sleep accuracy 열위, disposable test-buy) → **Case Drop**. surface Oura 10x PSR(2029 4,000억 exit) fantasy → Movano/Fitbit 2-3x scrub + 15yr 累損 wipeout. Nanora(10%) 대비 강한 traction·강한 kill. ⭐ **batch 교훈**: (1) **negative-E[CF] 기록 = PASS 결정의 정량 검증** — index 가 correctly-avoided 딜을 음수 what-if 로 보존(Open Research −25.85% / JS E&L −1.97% / Medistaff −0.59%), 회피 판단 근거화. (2) **양방향 QC 가 agent 에 전파** — 6 agent 가 instrument floor·fat-tail scrub·genuine wipeout 를 briefing 만으로 자체 적용([D-index-37](/ops/decisions)/[38](/ops/decisions)). (3) deal-class 다양화: buyout/PEF·founder-distressed-secondary·field-DD. **22-deal canonical E[CF] 랭킹**: Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Interstellar 30.5 > Hancom 23.9 > EGA 23.3 > (Superman 20.8 별도) > Catalyst 16.99 > 데이톤 16.57 > Infinity 16.5 > Eduon 15.0(s) > 디벨로퍼그룹 14.76(buyout) > 수성별 14.0 > Sendy 11.7 > Nanora 10.1 > Novachips 9.2 > Apposter 8.34 > 유비랩 4.06(s) > Medistaff −0.59 > JS E&L −1.97 > Open Research −25.85. index commit `7d6ccca`. | 2026-05-30 |
| D-index-38 | **디벨로퍼그룹(15th, index 최초 buyout-class)·유비랩(16th, deep-tech screen) 2-deal batch — buyout FCF-floor + 양방향 QC** — 2026-05-30 사용자 "디벨로퍼그룹·유비랩 검토". 입력 richness 양극: 디벨로퍼그룹 = 완성 full IC(v5, 5개정) / 유비랩 = IR+Q&A only(screen). **(1) 디벨로퍼그룹 스터디카페 사업부 100% 영업양도** = index **최초 buyout-class**(PE형 캐시카우 M&A, AXE 12억/EBITDA 3.87x, 무차입, 100% 보유, 보통주/secondary). full IC surface 공식 확률가중 E[CF] **34.09%** 이나 **메모 스스로 Devils-reweighted 16.5% 명시**(17.6pp 갭) — Exit 5.0x(근거 'L', 비교사례 없음) + EBITDA 310M(이승호 대표 보수 미계상→실 230-260M + 수도권유지보수 83→23M -61.7% 급감 미규명) + Upside 10.53x "카카오/네이버 9,251M" fat-tail 의존. [D-index-24](/ops/decisions) 미집행→calibrated canonical + [D-index-26](/ops/decisions) fat-tail scrub(Exit 4.0x·조정EBITDA·kakao 폐기) + [D-index-21](/ops/decisions) genuine wipeout → **E[CF] 14.76% / E[MoM] 2.02x / P(loss) 15%** (메모 Devils 근방). ⭐ **buyout 신 insight**: cashflow buyout 의 FCF 배당이 실질 하방 floor(downside 도 ~1.1x, 원금손실 거의 없음) → **P(loss)가 VC 딜보다 구조적으로 낮음** (손실은 운영붕괴 wipeout 경로뿐). VC equity 와 다른 첫 자산군 — 단 SME 성숙기라 upside cap(IPO 5년내 불가). deal_id `b88e2dcb`. **(2) 유비랩**(그래핀/그라파이트 4단 적층 방열 시트, OLED foldable + AI 반도체 TIM) SCREEN: 병행 agent + orchestrator QC. **elite founder**(유봉현 — 삼성D R&D 33년·세계최초 82인치 UHD·美특허 120+·NeoGraf 美 VP) + **진성 traction**(삼성D 업체코드+1/2/3차 샘플매출+애플 샘플전달)이나 **component multiple cap**(회사가 Q&A 에서 지목한 직접경쟁사 신화인터텍 EV/Rev **0.2x**·PBR 0.51x) + pre-rev hockey-stick(92억@3y=2,500x, NeoGraf 글로벌1위도 $16M) + Samsung 단일고객 concentration → **"좋은 회사 ≠ 좋은 딜"** (Interstellar "높은 IRR≠Go"·Novachips "polish≠quality" 가족). ⭐ **양방향 QC ([D-index-37](/ops/decisions) 보완)**: D-index-37 교훈은 "낙관 메모 blind transcribe 금지"(아래로 scrub). 유비랩은 **반대 방향** — agent 가 base 를 as-converted(0.76x)로 계산해 E[CF] 2.9%/P(loss) **80%** 산출했으나, 본인이 가정한 RCPS 1x 우선권을 base(EV 143억 ≫ 20억 우선권)엔 미적용한 **내부 불일치 artifact**(downside 엔 적용). 우선권 floor 일관 적용(base 1.0x) → **E[CF] 4.06% / P(loss) 43%** (peer 정합: EGA 40%·에듀온 45%·Nanora 50%). **QC = 올바른 수치에 착지(단지 낮은 수치가 아님)** — fat-tail 도 instrument-floor artifact 도 모두 교정. deal_id `c98ba89e`, stage='Screening'. **16-deal canonical E[CF] 랭킹**: Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Interstellar 30.5 > Hancom 23.9 > EGA 23.3 > Infinity 16.5 > Eduon 15.0(screen) > **디벨로퍼그룹 14.76(buyout)** > 수성별 14.0 > Sendy 11.7 > Nanora 10.1 > Novachips 9.2 > **유비랩 4.06(screen)** (+ Superman 20.8 별도). index commit `c0bf6d5`. | 2026-05-30 |
| D-index-37 | **EGA·수성별·Nanora 3-deal batch 적재 (12~14th) — transcribed 메모 rigor 가변 → QC+calibration 필수** — 2026-05-30 사용자 "EGA·Nanora·수성별 모두 진행" + "Nanora full ic". 3 병행 background agent(deal당 1) + orchestrator QC. **핵심 교훈 — full-IC 메모를 blind transcribe 하면 안 됨**: 메모 rigor 가 deal 마다 극과 극. **EGA**(디파이넘버, NMN 뉴트리코스메틱) 메모는 surface-optimistic → agent 가 그대로 옮긴 E[CF] **127%**(매출 16억→550억 3년 34x + EV/Rev 7× + 18x MoM@2y)는 [D-index-26](/ops/decisions) fat-tail 환상(Iippo 74% 재현). EGA 는 status='passed'(미투자·조건부)라 [D-index-24](/ops/decisions)상 surface 아닌 calibrated 가 canonical → **scrub**(revenue ramp 보수화 16→300/120억 + EV/Rev 5×/3.5×/2.5× K-beauty M&A anchor + **genuine wipeout 추가**: IR에 창업자 이름·이력 부재 + 매출 16억 미검증 red flag) → **calibrated E[CF] 23.3%** (E[MoM] 2.33x, P(loss) 40%). surface 는 헤더 audit trail 보존. 반면 **수성별**(국군복지단 DOOH 광고, 우선협상대상자) 메모는 이미 보수적 — Σp −23.8% → IRR(E[CF]) **+14.0%**(sign-flip, Interstellar 패턴). 단 **deal 조건 전부 dataroom 부재**(10억/30억/25% 가정) + 팀공백 + CAPEX gap 5:1 = info-void Conditional Pass (instrument TBD, series 기타). **Nanora**(US precision-wellness, TCM→구독 supplement+smart ring+AI, SAFE @ $9M post cap, pre-launch) 는 사용자 지시로 **SCREEN→FULL IC 승격**(rich dataroom): 18-section + multi-scenario + adversarial(proponent/premortem-critic 분리). research-calibrated E[CF] **10.05%**(E[MoM] 1.76x, P(loss) 50%) — 회사 plan을 **Care/of($225M→Bayer→2024 폐업) category-graveyard** + Oura 11x→supplement 1.5-2.5x rev + Pre-Seed→A 85% fail base-rate 로 하향. 판정 **Conditional**(미투자, 결정변수 = post-launch 90-day cohort retention, T+9M revisit). **QC 결론**: agent batch 는 효율적이나 transcribe 산출은 반드시 orchestrator 가 fat-tail/wipeout/base-rate QC (EGA 127%를 적재 전 차단). **14-deal canonical E[CF] 랭킹**: Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Interstellar 30.5 > Hancom 23.9 > **EGA 23.3** > Infinity 16.5 > Eduon 15.0(screen) > **수성별 14.0** > Sendy 11.7 > **Nanora 10.1** > Novachips 9.2 (+ Superman 3-step 별도). index commit `fc56004`+`7b4a50d`. | 2026-05-30 |
| D-index-36 | **SCREENING 단계 정규화 — best-effort pre-DD 게이트 (research+모델 필수, full /ic 자원 gate)** — 2026-05-30 사용자 "screen 단계 추가 + 적합 IC memo + 최소 리서치 전부 + 재무모델 + best effort + 정규 프로세스화 + 적재". 1-pager(seed teaser)만 있는 inbound 에 19-agent `/ic`(수 시간·dataroom 전제)를 바로 돌리는 건 GIGO·낭비 → **Screening 게이트** 신설. **deal lifecycle**: sourcing → ⟨**Screening**⟩ → DD(full `/ic`) → IC 결의(Go/Conditional/Pass) → Portfolio → Exit. (deal.stage enum 에 'Screening' 이미 존재 — migration 불요.) **Screening 이 답하는 질문** = "이 건에 **DD 자원 투입 가치**가 있나?" (Go/No-Go 투자결정 아님). **프로토콜 (타협 금지)**: (a) **최소 외부 리서치 필수** — 시장·수요 / sector franchise-or-stage base-rate / exit comp(공개 multiple) / 경쟁·moat / founder 검증, (b) **재무모델은 회사 plan 이 아닌 base-rate calibrated**, (c) IRR 은 index engine IRR(E[CF]) (D-index-25/32) 로 검증, (d) premortem + 가정 라벨 A1..An (H/M/L). **산출물**: 딜폴더 `ic/{research,finance,memo}/` + index 적재 (stage='Screening', screen-pass 면 status='passed', what-if IRR 보존 [D-index-30](/ops/decisions)). **첫 사례 = 에듀온(EDUON)** — 초등 영어 Writing 프랜차이즈 Seed 보통주 5억@Pre 20억. ⭐ **교훈 — best-effort screen 이 ad-hoc 낙관을 base-rate 로 보정**: 회사 IRR 58% / Claude ad-hoc E[CF] 26.5%(upside 10x) → **research-calibrated E[CF] 15.0%** (E[MoM] 2.0x, P(loss) 45%). 두 회사 낙관(가맹 "3년 1,000" vs 3030영어 21년→1,400 / exit "매출100억→300억=3x rev" vs 크레버스 0.59x·웅진 0.20x rev)이 base-rate·comp 에 동시에 깨지며 upside 10x→6x cap. **Screen 판정 = PASS(DD 미진행)** — E[CF] 15%≪30% hurdle + SME 프랜차이즈(upside cap) + 보통주 무보호 + AI(Wizon) commodity. founder·product 우량하나 현 조건 DD 정당화 불가 → 재screen 조건(RCPS+Pre 10-12억+가맹 traction+vesting) + T+6M(론칭 후) 재screen. **정직 원칙**: 입력이 1-pager 면 "full cycle 의 정직한 형태 = Screen 에서 멈춤". 향후 `/ic` 에 lightweight screen-mode 통합 = [B-index-ic-screen-mode](/ops/backlog). index 11th deal (첫 Screening), deal_id `2bb5d585`. | 2026-05-30 |
| D-index-35 | **Interstellar (인티그레이션) 적재 — 10th deal, PASS (governance-driven, not IRR)** — 2026-05-30 사용자 "추가 적재 프로젝트?" → 데이터룸(OneDrive `1_Project/`) 스캔 결과 IC 분석 완료·미적재 = **Prj_Interstellar 1건** (Render=IC 미완 / Whale[위시켓]=보유 admin docs / 델리후레쉬=RFP 제휴건 / Pipeline=스크리닝 단계 — 모두 미대상). **인티그레이션**: 한의·치과 5-카테고리 플랫폼 (한의사 가입률 83% 사실상 단독 1위, FY24A 매출 454억 +74%). **Series D RCPS**, AXE follow 검토 20억 (신주 16.4+구주 3.6, pre 1,085억, AXE 1.6% O/S) — **PASS** (알토스+네이버 lead 160억 종결). [D-index-24](/ops/decisions): PASS→calibrated canonical (Sendy 동급, `status='passed'`, what-if IRR 보존). **canonical E[CF] IRR 30.5% / E[MoM] 3.23x / P(loss) 36.0%** (IC v1 surface Σp 계열 25.3%/2.71x). ⭐ **핵심 — PASS 사유가 IRR 아님**: E[CF] 30.5% 는 매력적(아래 9-deal 중 5위)이나 PASS 는 거버넌스(R6 자기거래 — 정희범 대표 명의 메디스트림 한의원+원외탕전 매출 인식 → IPO 심사 reject ≥30%) + AXE 1.6% minority(이사회 미진입) + 알토스/네이버 lead 후 marginal value 부재 = 순수 비-IRR. **"높은 IRR ≠ Go"** 명시 사례 (Novachips "polish ≠ quality" 와 짝). **현 canonical 9-deal 랭킹** ([D-index-34](/ops/decisions) 8-deal supersede): Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > **Interstellar 30.5** > Hancom 23.9 > Infinity 16.5 > Sendy 11.7 > Novachips 9.2. 부수: `seed.rs` SERIES_OK 에 Series D/E 추가 (누락 — 향후 Series D+ intake hard-reject 방지). validate-seeds 12 Pass / 23 test / DB 10 deal. index commit `7269286`. | 2026-05-30 |
| D-index-34 | **canonical 8-deal E[CF] 랭킹 확정 — Σp/surface 시절 랭킹 supersede** — 2026-05-29 [D-index-32](/ops/decisions)/[33](/ops/decisions) 후속, [B-index-docs-irr-ecf-restate](/ops/backlog) 수행. D-index-19/21/23/24 의 인라인 랭킹은 Σp·IRR(폐기) 또는 surface 기준 → engine `validate-seeds` 로 9 deal IRR(E[CF]) 재산출하여 canonical 확정. **canonical E[CF] 랭킹**: Sentry 43.5 ≈ Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Hancom 23.9 > Infinity 16.5 > **Sendy 11.7 > Novachips 9.2**. **구 Σp 랭킹 대비 변화**: (a) **tail flip** — Sendy(구 6.5 최하위) 가 Novachips(구 7.8) 위로 (E[CF] 11.7 vs 9.2); (b) Sentry–Iippo 격차 4pp→0.2pp (거의 동률); (c) 전반적으로 E[CF] 가 Σp 보다 높음 (fat-tail upside 가 mean 견인). **per-deal 구(Σp/surface)→신(E[CF])**: Sentry 40.3→43.5 / Iippo 36.5→43.3 / Starnex 36.4→38.1 / Canopy 26.4→31.8 / Hancom 22.4→23.9 / Infinity 13.8→16.5 / Novachips 7.8→9.2 / Sendy 6.5→11.7. overlay: Infinity recalibrated -8.3→-4.3 / Superman fresh 10.5→20.8 ([D-index-33](/ops/decisions) 에서 seed 전환 완료). **Infinity 특례 (executed deal — [D-index-24](/ops/decisions)↔[32](/ops/decisions) 조정)**: v8 **모델(leaves) 불변** 유지(집행건 decision-time 보존) + 집계만 E[CF] 통일 → canonical metric = **E[CF] 16.5%** (baseline 0.1646), IC headline **13.8%** 는 provenance (집계법 차이, 모델 자체 불변). 즉 D-index-24 의 "사후 재작성 금지" = 모델/가정 보존이지 집계법 고정이 아님. **seed 주석도 정합** (index commit `537c04e`: starnex/hancom/sendy/infinity 주석 E[CF] 재기재, value 불변). **역사적 결정문(D-index-19/21/23/24)**은 revision 최소화 — 인라인 숫자는 당시 기록 보존, 본 결정이 현 canonical 랭킹 SoT. | 2026-05-29 |
| D-index-33 | **irr_instrument_adjusted 폐기 — instrument 효과는 leaf waterfall 로만 표현 (flat discount 이중계상)** — 2026-05-29 사용자 "수익성 정확도 심화" 방향 선택 후 조사 결과. **발견**: exit_matrix leaf recovery 가 instrument 구조를 포트폴리오 전역에서 이미 반영 — RCPS deal 은 preference floor (Sentry 0.05~0.14 / Starnex 회생 1.10x "RCPS floor"), 보통주 deal 은 후순위 wipeout (Hancom 0.30 / Sendy 0.15 / Novachips 0.20 / Infinity 0.12, leaf 설명에 "보통주 후순위" 명시). 따라서 **IRR(E[CF]) 가 이미 instrument-aware**. Novachips 1건에만 있던 `irr_instrument_adjusted` (E[CF] +9.2% 에서 -12pp 추가 → -4.55%) 는 leaf 의 보통주 wipeout(0.2x)을 **이중계상** (검산: E[MoM] 1.34x → E[CF] +9.2%, wipeout 6M@5y 이미 포함). [D-index-19](/ops/decisions) 의 instrument-adjusted-IRR 제안([B-index-instrument-adjusted-irr](/ops/backlog)) supersede — discount table 미구현. **변경**: (a) novachips `irr_instrument_adjusted` baseline 제거 + 헤더 재프레이밍; (b) `seed.rs::validate` DEPRECATED_OUTPUT_CODES load-time hard reject — `irr_instrument_adjusted` (D-index-33) + `irr_loss_included` / `irr_success_only` (Σp, [D-index-32](/ops/decisions) 완결, 음성 테스트 OK); (c) overlay seed 잔존 Σp output_code 정합 — infinity_recalibrated / superman_fresh 의 `irr_loss_included` → `irr_expected_cashflow` (engine E[CF]: **Infinity -4.3%** [구 Σp -8.3%] / **Superman fresh 20.8%** [구 Σp 10.5%] — fat-tail 일수록 Σp↔E[CF] 격차 큼). **잔여 (정직 기록)**: docs 8-deal 랭킹 등 IRR 다수가 pre-E[CF] (Σp/surface) → [B-index-docs-irr-ecf-restate](/ops/backlog). Σp·IRR 과 동형 (잘못된 별도 집계 폐기). 11 seed validate + 23 test + 음성 테스트 Pass. index commit `74e1eb4`. | 2026-05-29 |
| D-index-32 | **Σp·IRR 폐기 — IRR(E[CF]) 단일 canonical 집계** — 2026-05-29 사용자 승인 "p IRR 폐기하고 남은 것 모두 진행" ([D-index-25](/ops/decisions) 의 "폐기 보류" 해제). **배경**: Σp·IRR (per-scenario IRR 의 확률가중 평균) 은 "수익률을 평균" 하는 잘못된 집계 — fat-tail deal 에서 rate-averaging 이 mean 을 왜곡. IRR(E[CF]) (확률을 cash flow 에 먼저 적용 후 IRR) 만 canonical 로 유지. **변경**: (a) `query_irr` summary 에서 `weighted_irr_loss_included` / `weighted_irr_success_only` 제거 → `irr_expected_cashflow` + `expected_moic` + `prob_loss` + `success_probability` + `methodology` 만 노출; (b) `src/irr.rs::weighted_irr` / `weighted_irr_success_only` 에 `#[deprecated]` + `#[allow(dead_code)]` (호출부 0, 산식은 audit 위해 보존); (c) **E[MoM] (weighted_moic) 는 폐기 아님** — MoIC 는 linear 집계라 확률가중 평균이 정합 (rate 가 아닌 multiple); (d) `validate.rs` ValidateReport + 9 seed `financial_outputs_baseline` 의 output_code 를 `irr_expected_cashflow` 로 전환 (E[CF] 값); (e) html/xlsx cover 의 IrrSummary 표시 = E[CF] / E[MoM] / P(loss). 23 unit test + validate 3 PASS. index commit `3b2f543`. | 2026-05-29 |
| D-index-31b | **share_type 신주(primary)/구주(secondary) 구분 + post-money invariant** — 2026-05-29 사용자 "round size 와 entry 가 신주 구주 나눠진 경우도 수용 가능한가 → 신·구주 혼합 등 다양한 상황 많다". **모델**: `fund_investment.share_type ∈ {primary\|secondary}` — **primary**(신주) 는 회사로 자금 유입 → post-money 증가에 반영, **secondary**(구주) 는 기존 주주 지분 매입 → post 불변 (회사 미유입). 혼합 라운드는 `round_primary_krw` (라운드 중 신주분) 별도 기재. **invariant** (`SeedFile::validate` Check 1b + `validate.rs`): `post_money ≈ pre_money + 신주(round_primary)` ±2% — 위반 시 hard reject. **검증 효과**: Infinity pre 499.5억 / post 500억 이 DSC 라운드 100억 신주와 불일치 (500 ≠ 499.5 + 100) → invariant 가 포착 → pre 400억 으로 정정 (post 500 = pre 400 + 신주 100). Hancom / Novachips 는 구주 매입분 포함 → `share_type=secondary`. migration 0005 = share_type + round_primary_krw. index commit `98b88c2`. | 2026-05-29 |
| D-index-31 | **투자성 분석 최소 intake 게이트 (5 필수 필드) + EV/EqV 혼동 차단 + _TEMPLATE** — 2026-05-29 사용자 "투자성 분석 시 최소 필요한 정보는 받아서 시작 — entry date / valuation (EV 인지 EqV 인지 혼동 없게) / 전체 라운드 / 투자 규모 / Series". **5 필수 필드** (`SeedFile::validate` Check 1b): `series` + `round_size_krw` (라운드 전체) + `committed_krw` (우리 투자) + `entry_date` + `pre_money_krw`. **enforcement 2-tier** (사용자 "Warn 기존 호환 + 신규만 hard"): `intake_enforced=true` (신규/template) → 누락 시 hard reject; `=false` (기존 9건) → warn 만. **EV/EqV 규칙** (혼동 영구 차단): entry valuation (pre/post) 은 **항상 EqV** (지분율 분모) — EV 입력 금지; exit 만 `proceeds_basis` 로 EV→EqV bridge ([D-index-22](/ops/decisions)). **신주/구주**: round 을 primary/secondary 로 분해 ([D-index-31b](/ops/decisions)). 산출물 = `seeds/_TEMPLATE.yaml` (intake form + EV/EqV 가이드 주석 + 신주/구주 혼합 예시). migration 0004 = series + round_size_krw. 기존 9건 backfill (series + round_size_krw + share_type). index commit `c4c12f4` + `9e86a07`. | 2026-05-29 |
| D-index-30 | **status='passed' (검토 미투자) — what-if IRR 보존 + fund/project baseline 제외 + 5/29 배치 정정** — 2026-05-29 사용자 "pass 도 당연히 IRR 로 데이터 관리. fund·project 수익성에서는 제외". **status='passed'** = 검토했으나 미집행 — per-position what-if IRR 은 **계산·보존** (의사결정 학습용) 하되 `committed_total` / fund pooling / project baseline 에서 **제외**. **all-passed fallback**: 한 deal 의 position 이 전부 passed 면 (실투자 0) baseline 계산 시 passed 를 포함 (빈 집계 방지). 구현 = `incl()` closure (`status != "option" && (!has_real \|\| status != "passed")`) 를 mcp.rs query_irr + validate.rs 에 공통 적용. **5/29 사용자 배치 정정 동반**: (a) Sentry Pre-A = 투자조합 1호; (b) Iippo 1호=1호·2호=2호; (c) Starnex 검토 20억 / entry 8월말; (d) **Canopy BW 는 별도 deal 아닌 Canopy 안의 passed position** (BW entry 2026-02-28, 4.2% warrant — per-position 모델로 BW IRR 28.0% &lt; RCPS 31.8% 정합, 이전 별도 deal CanopyBW 삭제); (e) Hancom 검토 5억 / 납입 7월말 / passed; (f) Sendy 검토 10억 / Pre-C / passed; (g) Novachips entry 2026-06-10 / passed. **proceeds 비례 재척도** (사용자 "IRR 보존") — 규모 변경 시 leaf proceeds × (new/old) 로 IRR 불변 유지 (Starnex 38.1% / Hancom 23.9% / Sendy 11.7%). migration 0003 = passed status. index commit `f650bec`. | 2026-05-29 |
| D-index-29 | **status='option' (pro-rata 권리 미행사) — baseline·fund·per-position IRR 전면 제외** — 2026-05-29 사용자 "Series A Option 은 무슨 표현?" 후속 재분류. **status='option'** = 향후 행사 가능한 pro-rata 권리 (아직 집행도 검토결정도 아님) — `committed_total` / baseline / recovery / fund pooling 에서 **전면 제외**, per-position IRR = null (행사 전이라 cashflow 미존재). passed ([D-index-30](/ops/decisions)) 와의 차이: passed 는 검토 완료·what-if IRR 보존, option 은 권리만 보유·IRR 미산출. 대표 케이스 = **Sentry 후속 5억 pro-rata option** (1호 단독 5억 집행 + 후속은 권리만) → status='option' 으로 재분류 (이전 committed 로 잘못 집계되던 것 제거). fund_investment.status enum 최종 = option / passed / committed / paid / locked_in / written_off / partial_exited / exited. migration 0002 = option status. index commit `9523638`. | 2026-05-29 |
| D-index-28 | **미집행 position entry timing — planned date + never-silent flag + fund pooling 클램프 버그 수정** — 2026-05-29 사용자 지적 "2호 납입 시점이 한 달 다른데 IRR 이 완전 동일한 게 말이 되나". **진단**: 계산식은 정확 (격리 테스트 IippoTT — 2호 +1개월 44.24% / +4개월 47.40%, MoIC 5.685x 불변; exit=회사 단일 청산 calendar 고정이라 늦은 entry=짧은 hold=높은 IRR). 동일값 원인 = **2호 paid_date=null → 코드가 offset 0 으로 silent fallback → 1호와 hold 동일**. **수정 3종**: (a) `seeds/iippo.yaml` 2호 `entry_date=2026-06-15`(가안/planned, 사용자 결정), `paid_date=null` 유지(미집행) → 코드 `paid_date.or(entry_date)` fallback → 2호 IRR **44.24%** (1호 43.27%, +0.97pp). (b) **never-silent flag** — `entry_basis ∈ {paid\|planned\|assumed}` + note (paid_date 없으면 "⚠ 미집행 … 보수적 하한" 명시; query_irr per_fund + fund_performance per_position). (c) **fund_ecf_irr 풀링 버그** — `deal_ref_offset` 의 `.max(0.0)` 제거: fund position 이 deal lead 보다 늦게 진입(deal_ref &lt; fund_epoch)하면 음수 offset 이 정상인데 클램프가 hold 항등식(exit_t − paid_offset = leaf.timing − deal_paid_offset)을 깨 단일 position 펀드 IRR(43.27%)이 standalone(44.24%)과 불일치 → 수정 후 일치. **부수**: flag 가 Hancom/Novachips/Sendy/Starnex/Superman entry date 누락(`assumed`) 노출 (이전 silent) → [B-index-entry-date-backfill](/ops/backlog). index commit `85c8481`. | 2026-05-29 |
| D-index-27 | **per-position / per-fund IRR (투자조합 1·2·3호 수익성) + 추가투자 = 별도 position + Iippo 2호 = AXE Private Fund II** — 2026-05-29 사용자 4 지시 "추가 투자가 별도 건으로 관리 / 1·2·3호 펀드 수익성 / Iippo 2호 별도 적재·분석" 의 답. **per-position IRR**: `fund_investment` row 별 독립 IRR — proceeds split = non-writedown `leaf.proceeds × (own_fd/ref_own)`, writedown `recovery × own_committed`; timing = `leaf.timing − deal_paid_offset` (position 납입이 deal lead 보다 늦으면 hold 단축). `src/irr.rs::position_ecf_irr / position_moic`. **per-fund IRR**: `fund_performance(fund_entity_id)` MCP tool — 펀드의 모든 deal 횡단 position pool → 단일 calendar E[CF] IRR (`fund_ecf_irr`). fund_entity_id = **axe_ia_001**(1호 블라인드) / **axe_ia_002**(2호) / **axe_ia_003**(3호). **Iippo 2호 정정**: 가공했던 "Series A follow-on" 제거 → 실제 = **AXE Private Fund II (개인투자조합)** 통한 Pre-A 동일 라운드 1억 RCPS 공동투자 (GP 액스벤처스/강태훈, LP=Iippo측 유치 개인 + AXE 100M, MOSS 미등록·6 PCC·Conditional GO 미집행). 별도 IC Memo = OneDrive `Prj_Iippo/ic/memo/Iippo_2호_FundII_IC_memo_v1.md` (vehicle 심의, deal thesis = IC v8). index commit `7e313b5`. | 2026-05-29 |
| D-index-26 | **fat-tail optimistic leg comp-scrub → canonical (overlay 아님) — Iippo/Sentry/Canopy 74% 환상 제거** — 2026-05-29 사용자 "투자성 재검토 필요한 건 없나 → 2번 수행 (upside-leg 재검토)" + "기대현금흐름 IRR 아까 수정 안 됐나" 의 답. [D-index-25](/ops/decisions) IRR(E[CF]) 도입 후 fat-tail multi-leg deal 의 mean 이 mgmt/upside fantasy leg 에 과민 → 외부 comp 로 cap. **scrub (comp anchor)**: (a) **Iippo** mgmt EV 1~2.5조 → 1,000~2,500억 (강남언니 752억→6,000억 ≈ 8x ceiling); IRR(E[CF]) **74% → 43.3%**, E[MoM] 14.9x → 5.68x. (b) **Sentry** upside axe 236억(=47x) → 73억 (마스턴 27조 AUM ≈ 3,000~5,000억 equity), mgmt 84.5억 → 58.65억; **43.6%**, success-only 59.9%/16.8x → 45.5%/8.43x. (c) **Canopy** fleet EV/EBITDA 12x → 6x (Bird $2.5bn→$145M de-rating), non-writedown proceeds ×0.5; **31.8%**. **핵심**: scrub 을 **canonical seed 에 직접 적용** (이전엔 overlay-only → query 가 un-scrub 74% 노출 → 사용자 지적). 각 seed `financial_outputs_baseline` 주석에 **IC 원본(pre-scrub) 보존** (Iippo IC v8 37.0%/14.9x, Sentry IC pass 41%/13.2x, Canopy 27%) — audit trail. [D-index-24](/ops/decisions)(executed=IC canonical) 와 양립: leaf scrub 은 live E[CF] 계산 입력, 원본은 추적 가능. index commit `8c5e60e`. | 2026-05-29 |
| D-index-25 | **기대현금흐름 IRR (IRR of E[CF]) = canonical 수익성 지표; Σp·IRR 은 병기 (폐기 보류)** — 2026-05-29 사용자 질의 "확률 고려한 cashflow IRR 의 정확한 표현은?" + "cashflow IRR 이 확률 내포면 그게 더 정합" 의 답. **두 집계 구분**: (a) **Σp·IRR** (per-scenario IRR 의 확률가중 평균) = "수익률의 평균" — 잘못된 집계 (rate 를 평균), legacy; (b) **기대현금흐름 IRR = IRR(E[CF])** = 확률을 cash flow 에 먼저 적용 → 그 기대 CF stream 의 IRR — **canonical**. toy: 50% 10x + 50% 0.1x → Σp·IRR 10.8% vs IRR(E[CF]) 38.5% vs E[MoM] 5.05x. IRR(E[CF]) 는 fat tail 이 carry 하는 **평균값** → 반드시 **E[MoM] + P(loss MoM&lt;1) / median 과 묶어** 제시 (단독이면 우상향 왜곡). 구현 `src/irr.rs::expected_cashflow_irr(committed, leaves)` = leaf timing 별 group → E[CF] → compute_irr; `prob_loss`. query_irr summary = `irr_expected_cashflow`(canonical) + `expected_moic` + `prob_loss` + legacy `weighted_irr_*` 병기. **Σp·IRR 폐기는 사용자 승인 후** (현재 보류 — "우선 추후 폐기") → [B-index-deprecate-sump-irr](/ops/backlog). index commit `2d2066f`. | 2026-05-29 |
| D-index-24 | **executed deal = IC-approved 기준 canonical (decision-time 기록 보존); 현 practice 재calibration = retrospective overlay** — 2026-05-29 사용자 지시 "우선 13.8% 로 IC 승인 후 집행한 건이므로 13.8% 를 적재하라". [D-index-23](/ops/decisions) Infinity 3-step 비교(surface 13.8% → reviewed −8.3%) 후속 — **어느 값이 canonical 인가**의 결정. **원칙**: `deal.stage` 가 **Closed/집행됨**이면 canonical DB 기록 = **IC 가 실제 승인·의사결정한 기준** (Infinity 13.8%, v8 FINAL irr_locked) — 집행된 deal 의 IRR 은 **사후 재작성하지 않는다** (회수 시 actual 대조 baseline + 의사결정 history 무결성 보존). 현 practice 재calibration(−8.3%) 은 `seeds/infinity_recalibrated.yaml` + v9 memo 에 **retrospective overlay** 로 보존 (post-mortem·learning lens, DB 미적재 — 동일 deal_code 충돌). **executed-vs-passed 규칙**: **Sendy(Passed)** = 집행 결정 부재 → calibrated(6.5%)가 canonical (보존할 의사결정 없음, [D-index-21](/ops/decisions)); **Infinity(Closed)** = IC-approved(13.8%)가 canonical, recalibration 은 overlay. 즉 index canonical 선택 = **(passed → 현 practice 재작성 canonical) vs (executed → decision-time 기록 canonical + 별도 overlay)**. **8-deal canonical 랭킹** (⚠ pre-E[CF] Σp 기준 — 현 canonical 랭킹은 [D-index-34](/ops/decisions) E[CF]): Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > **Infinity 13.8** > Novachips 7.8 > Sendy 6.5 (overlay 적용 시 Infinity −8.3 최하위). seed: `infinity.yaml`(canonical 13.8% v8) + `infinity_recalibrated.yaml`(overlay −8.3% v9). index commit (canonical swap) 후속. | 2026-05-29 |
| D-index-23 | **3-step 검증 프로토콜 (surface 적재 → 현 practice 재수행 → 비교) — Prj_Infinity(INEX) 13.8% → −8.3% sign-flip** — 2026-05-29 사용자 지시 "기존 데이터 적재 테스트 → 신규 IC 재수행 → 두개 비교로 전 건들과 같게". [D-index-19](/ops/decisions)(surface↔calibrated gap)·[D-index-21](/ops/decisions)(현 practice 재작성) 를 **명시적 3-step 으로 정식화** — surface 를 별도 seed 로 적재(audit snapshot)하여 gap 을 DB 에서 정량화. **대상 INEX** (가상자산 거래소/VASP, 보통주 bridge 0.4997억 / POST 500억 / Closed). **Step 1 (surface)**: v8 FINAL(irr_locked) 그대로 (= 현 canonical `infinity.yaml`) → index 가 **13.8% / MoM 1.70x / success 76.5%** 정확 재현. **Step 2 (현 practice 재수행 + 외부 research)**: 4 anchor — (a) **실명계좌 base-rate near-zero** (2021 특금법 후 원화마켓 신규 진입 0건, 5사 closed club, FIU 옥죔, P&lt;10%) → surface success 76.5% 는 mgmt optimism anchor, (b) 코빗 won-market ceiling **1,000-1,400억**(Mirae MOU 25.12) → INEX coin-only 는 그 below, (c) **Gopax/Binance license-shell M&A 선례** (실패 coin-only entity 도 SI 매수, 2.7yr 규제 slog + discount) → 모달 exit = won-market rerating 이 아닌 **SI shell M&A breakeven**, (d) **보통주 distress recovery 0~20%** (RCPS 우선권 후순위) → genuine wipeout leg. **Step 3 (비교)**: calibrated `infinity_recalibrated.yaml`(overlay) = **−8.3% / MoM 0.82x** (upside 0.10 / base 0.42 breakeven / downside 0.30 / **wipeout 0.18 @ 0.12x**). **~22pp gap + sign-flip.** **핵심 시사점**: **성숙·정직한 IC memo 도 핵심 base-rate 를 mgmt optimism 에 anchor 하면 결론 역전** — v8 은 Event-Driven all-or-nothing 명시 + **종합 IRR 13.8% < hurdle 20% 공개** + 3 reviewer + irr_locked 로 매우 성숙했으나, success 확률을 실명계좌 optimism(실제 base-rate &lt;10%)에 anchor + 보통주 wipeout leg 누락 → reviewed E[IRR] sign-flip. **"return 이 hurdle 미달임을 공개"하는 것과 "probability 가 base-rate anchored"인 것은 별개** — index value = base-rate-anchored 확률 + genuine wipeout 강제 (surface honesty 와 독립). **proceeds 메커니즘은 v8 이 이미 정확** (ev_bridge·net debt 0 보통주·exit-diluted 0.0724% — [D-index-22](/ops/decisions) 모범) → 재계산 0, gap 은 순수 analytical. **8-deal 랭킹** (⚠ pre-E[CF] Σp 기준 — 현 canonical [D-index-34](/ops/decisions)): **canonical = IC-approved 13.8%** (executed deal — [D-index-24](/ops/decisions)): Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > **Infinity 13.8** > Novachips 7.8 > Sendy 6.5; recalibration overlay(−8.3%) 적용 시 Infinity 최하위. 단 INEX 는 조합 6.6%(0.5억) Event-Driven 소액 optionality bet 라 invested 자체는 방어 가능 (license scarcity + SI LOI floor). 산출물: OneDrive `Prj_Infinity/ic/memo/v9_axe_current_practice_260529.md` + seed `infinity.yaml`(canonical 13.8% v8) + `infinity_recalibrated.yaml`(overlay −8.3% v9). index commit `c0dcd9a` + canonical swap. | 2026-05-29 |
| D-index-22 | **proceeds 산정 강화 — EV→EqV(net debt) bridge + exit-dilution 명시·강제 (manual scalar 불가)** — 2026-05-29 사용자 audit "모두 EV = EqV + Net Debt 개념과 투자 후 dilution 을 적절히 고려해 계산됐는지 체크" 의 답. **발견 — 7-deal proceeds 도출이 비일관**: (a) net-debt bridge = **Canopy 만 명시** (EV 797억 − net debt 300억 = EqV 498억; KB캐피탈 fleet 차입이라 가장 필요한 deal 을 옳게 처리), Sendy(v2)·Iippo 는 `stake × EV` 직접 (EqV bridge 누락), pre-IPO 3 + Sentry 는 시총/PER equity multiple (bridge 구조적 N/A — 정상); (b) dilution = pre-IPO 3 + Sendy 는 exit-date 희석 stake 명시, **Iippo·Sentry 는 entry F/D flat** (중간 라운드 희석 미반영 → proceeds 수 pp 과대 낙관). **결정 ([D-index-20](/ops/decisions) 의 "IRR deterministic·override 불가" 를 proceeds 로 확장)**: proceeds 도 manual scalar 가 아닌 명시 도출. `financial_model.proceeds_basis` enum 4종 — **ev_bridge** = `exit_stake × (exit_ev − exit_net_debt)` / **equity_value** = 시총·PER (equity multiple, net-debt N/A) / **mom** = `committed × MoM` (pre-IPO check 기반) / **legacy_ev** = EV-based pre-hardening (per-leaf bridge 미itemize, retrofit 대기). **강제 2중**: ev_bridge non-writedown leaf 는 `stake×(EV−net debt)` 가 axe_proceeds 와 ±2% 일치해야 — (1) seed load-time **hard reject** (`SeedFile::validate`) + (2) `validate_financial_model` **Check 7 `exit_proceeds.bridge` Error**. negative test 로 거부 확인 (stake 10% × EV 2,225억 = 222.5억 ≠ 날조 300억 → "proceeds 불일치 >2%" reject). migration 0005 = proceeds_basis + exit_ev_krw/exit_net_debt_krw/exit_stake_pct 컬럼. **Sendy 정정 (v3)**: proceeds_basis=ev_bridge, **net debt = 0** (asset-light 플랫폼 트럭 미보유 + 자금니즈를 debt 아닌 equity[Series C]로 충족 + dataroom 차입 증거 0 → 보수적; **없는 부채 날조 안 함**), exit_stake 10% = entry 12.5% 의 20% 희석. → **proceeds·IRR 불변 (E[IRR] 6.47%)** 이나 EV≠EqV 누락 class 를 구조적으로 영구 차단. "정정 = 구조적 (bridge 명시 + 엔진 강제), 숫자 불변" 이 evidence 상 정직한 결과. **7-deal 결과**: Sendy ev_bridge PASS(3 leaf reconciled) / Sentry equity_value PASS / Starnex·Hancom·Novachips mom PASS / Iippo·Canopy legacy_ev WARN — **0 errors**. **잔여 gap (정직 기록 → [known-gaps](/ops/known-gaps))**: (1) Iippo·Canopy per-leaf EV→EqV bridge 미itemize → [B-index-proceeds-bridge-retrofit](/ops/backlog), (2) Iippo·Sentry exit-dilution = entry F/D flat (중간 라운드 희석 미반영; RCPS anti-dilution/pro-rata 부분 상쇄 — Closed deal 이라 사후 실익 낮으나 IRR-정직성 차원). index commit `ca714b7`. | 2026-05-29 |
| D-index-21 | **historical deal 축적 = 현 practice 재작성 (raw 축적 아님) — 3-tier IRR + v1 5-flaw 교정** — 2026-05-29 사용자 redirect "그냥 적재하지 말고 ic memo 를 거의 현재 우리 practice 수준으로 새로 써본다 생각하고 임하라 (당시 작성 방법론은 현재보다 열위일 가능성 높음, 추가 조사 가능)" 의 답. [D-index-19](/ops/decisions) 가 "xlsx surface cell → calibrated" 였다면 본 결정은 그 논리적 종착 — **전체 memo 방법론 자체를 현 5-tenet practice 로 재작성**. **3-tier IRR story** (index 의 reviewed-truth 가치 실증): (a) v1 md 기재 = Expected 31% / Devils 22.8% (per-scenario 62/35/-8, Excel 과 모순된 **fabricated override** — D-index-20 가 architectural 차단), (b) v1 Excel 실제 = Base 95.7% / weighted 92.4% (**math-correct 이나 낙관 input** — D-index-20 이 자동 산출), (c) **v2 현 practice 재calibration = E[IRR] +6.5% ⭐ canonical** (외부 comps anchor + genuine wipeout leg). **v1 의 5 결함 교정**: (1) IRR override 95.7→35 fabrication (D-index-20), (2) **wipeout leg 부재** — v1 의 Downside 가 +31.6% gain 이라 손실 시나리오 자체 없음 → genuine 18% wipeout leg 추가 (보통주 floor 0 / 부릉 1/6 precedent recovery 0.15x), (3) **sendyX 66x 미검증** (beta 25.12 고객 5곳 월 375만원 → 2026E 25억 = 1년 66배 bottom-up 무근거) → base-rate haircut (mgmt 919억 대비 -93% deep-discount, B2B SaaS PMF base rate 정합), (4) **Exit 5x flat → segment-weighted** (freight matching 1.0~1.5x + TMS SaaS 4~5x; WiseTech-E2open 3.5x M&A anchor), (5) instrument 분석 부재. **외부 anchor** (background research): freight matching EV/Rev 0.3~2x, TMS SaaS 3.5~5x, Convoy $3.8B→0 + Mesh Korea(부릉) ₩5,500억→₩800억(1/6 distress) → wipeout base rate 15~25%, 한국 Series C→IPO 예외적 (TMAP 미들마일 IPO covenant 미달 교훈 → Bull IPO P 0.12 로 down). **결과**: 4-scenario bull(0.12, 4.45x, IRR +64.5%) / base(0.40, 1.83x, +16.3%) / bear(0.30, 0.72x, -7.0%) / wipeout(0.18, 0.15x, -31.5%) → **E[IRR] 6.5% / E[MoM] 1.51x / σ 27.5% / Sharpe-like -0.06 / Semi-σ 17.7%**. PASS 재확인 — v1 사유(구조+타이밍)에 더해 fundamentals 도 30% hurdle -23.5pp 미달로 정합 (당시 quality 평가는 긍정이었으나 현 practice 로는 marginal). **portfolio 영향**: 7-deal 랭킹 Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > Novachips 7.8 > **Sendy 6.5 (최하위)** — v1 의 92% 매력은 대부분 2 낙관 input + 누락 risk leg 의 산물이었음을 정량 노출. **일반 원칙 (index 축적 protocol 확장)**: (1) deal 의 IC 방법론이 현 practice 이전이면 conclusion 축적 아닌 memo 재작성, (2) 외부 comps/precedent 로 multiple·probability anchor, (3) genuine downside/wipeout leg 필수 (낙관 일변 금지), (4) unvalidated bottom-up 가정은 base-rate haircut, (5) v1 conclusion 은 audit citation (financial_outputs_baseline) 으로만 보존. 산출물: OneDrive `1_Project/Pipeline/Sendy/ic/memo/v2_axe_current_practice_260529.md` (5-tenet · 4-scenario · deterministic IRR · premortem · v1→v2 교정표) + seed v2 = `/Users/axe/index/seeds/sendy.yaml` (financial_model version:2). | 2026-05-29 |
| D-index-20 | **manual IRR override 불가 (deterministic compute SoT) + declined-deal (Passed stage) tracking** — 2026-05-29 센디(Sendy) 축적 시 발견된 flagship 사례, **index 존재 이유의 결정적 증거**. 센디 `ic/finance/exit_matrix/v1.yaml` line 76: `irr_approx_pct: 95 # (375/50)^(1/3)-1 ≈ corrected: 35%` — 계산값 95.7% 를 근거 없이 "35%" 로 손수 override. 이 오류가 md 전반 전파 (Base 35% / Downside -8% / Expected 31% / Devils 22.8%), 그 중 **Downside -8% 는 구조적 불가** (수취 114억 > 투자 50억 → IRR 반드시 양수). 문서 자체가 "수정 필요 상태 (현재 미수정)" 명시했으나 미교정 잔존. **index 정책**: IRR 은 `exit_matrix_leaf` 의 proceeds + timing 에서 `single_flow_irr` deterministic 계산 — financial_output 에 IRR 직접 쓰는 path 없음 (manual override 물리적 불가). 센디 seed (v1) 를 EV-derived proceeds (Exit EV × stake 10%) 로 작성 → index 가 Base 95.7% / Downside 31.6% / Upside 146.6% / weighted 92.43% 자동 산출 = Excel 실제값 정확히 일치 (md override 자동 교정). md 의 erroneous 값은 financial_outputs_baseline citation 으로만 보존 (audit). **단 이 92.43% 는 math-correct 이나 v1 의 낙관 input (sendyX 66x + Exit 5x flat + wipeout leg 부재) 산물 — 초기 축적값일 뿐 canonical 아님**; 사용자 redirect 로 현 practice 재작성 → seed v2 = E[IRR] 6.5% 로 supersede ([D-index-21](/ops/decisions)). 즉 본 결정은 "computed override 차단" (architecture), D-index-21 은 "낙관 input 자체를 현 practice 로 재calibration" (analysis) — 2-layer. **부수 결정 — `deal.stage` 에 'Passed' 추가** (migration 0004): index 가 GO/Closed deal 만이 아니라 **PASS 결정 (IC 검토 후 미투자) 도 first-class institutional memory** 로 보존. 센디 PASS (2026-02-15) 사유 = 구조 (10억서 AXE CB 외 equity 참여 제한) + 타이밍 — **quality/IRR 아님** (물류 round-trip 최적화 긍정 평가, "할 수 있었으면 좋았을 deal"). 7-deal portfolio = Closed 3 (Iippo/Sentry/Canopy) / IC 3 (Starnex/Hancom/Novachips) / Passed 1 (Sendy). **시사점**: (1) [D-index-19](/ops/decisions) 가 "surface vs reviewed gap" 였다면 본 결정은 "**computed vs manually-overridden gap**" — index 가 후자를 물리적 차단, (2) screening-grade model honesty — 92% 는 math-correct 이나 Exit EV 낙관 (sendyX 2026E 25억 = beta 5곳 월375만원 대비 66x 미검증); inputs_hash 가 가정 재현성 보존하되 가정 타당성 판단은 별도 (validate sanity 확장 여지), (3) declined deal 이 "왜 안 했는가 + 그 시점 IRR" 보존 → 센디 Q4 post-mortem (sendyX 상용화/BEP) 시 actual 대비 검증 가능. seed = `/Users/axe/index/seeds/sendy.yaml`. | 2026-05-29 |
| D-index-19 | **reviewed truth 축적 — index 는 calibrated 검토 본 저장, xlsx surface cell 아님** — 2026-05-28 사용자 요청 "3건 (스타넥스/노바칩스/한컴인스페이스) 찾아서 축적하되 그대로가 아닌 검토 + 시사점" 의 답. 3 pre-IPO deal 을 `_comparative_20260528_preIPO/` (13-agent 비교 IC 메모) 의 **common-protocol calibrated** 본으로 index 축적. **핵심 발견 — surface IRR ≠ reviewed IRR (최대 36pp gap)**: 스타넥스 surface(IC v3) 19.6% → calibrated 36.4% (+17pp), 한컴 surface 58.5%(P 거래소 85%) → calibrated 22.4% (-36pp, KOSDAQ 재청구 base rate 40~55% anchored 65% 로 down-cal), 노바칩스 surface -1.5% → calibrated 7.45% (+9pp). **만약 xlsx surface cell 을 그대로 축적했으면 한컴이 1위로 오기록** (실제 calibrated 랭킹 스타넥스 > 한컴 > 노바칩스) → index 의 본질 = typed reviewed truth 보존 (D-index-1 실증, raw cell dump 아님). **5 시사점**: (1) surface vs calibrated gap → index 가 검토 본 저장하는 가치 정량 실증, (2) **instrument structure 가 IRR-material (8~15pp)** — 노바칩스 보통주 구주 instrument-adjusted -4.55% vs surface 7.45% = 12pp; 현 schema `instrument` enum 은 있으나 `irr_instrument_adjusted` 자동계산 없음 → [B-index-instrument-adjusted-irr](/ops/backlog) gap, (3) probability calibration provenance (base rate anchor) 가 `scenario.description` 에 박제 → "왜 65%?" 추적 가능, (4) **동일 exit_matrix_leaf schema 가 Pre-A multi-leaf (Iippo/Sentry/Canopy) + pre-IPO single-leaf (각 scenario=단일 outcome) 양쪽 수용** — schema 유연성 검증; timing 이 bucket(3y/5y/7y) → 소수(2.5y/4.5y) 확장 필요 (parse_timing_years + CHECK 완화 migration 20260528000003), (5) **변곡점: IC 산출물 완성도 ≠ deal quality** — 노바칩스 (5 estimator × 8 scenario, 가장 정교) = 최약체 (IRR 7.8% 최하위 + Sharpe -0.02), index cross-deal benchmark 가 "polish bias" 객관 노출. **검증**: 6-deal portfolio IRR 랭킹 Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > Novachips 7.8, pre-IPO 내부 랭킹 AXE 비교메모 결론과 일치, validate-model 6/6 PASS. seed = `/Users/axe/index/seeds/{starnex,hancom_inspace,novachips}.yaml`. | 2026-05-28 |
| D-index-18 | **DSL formula = "single driver + period-indexed values" 패턴 강제 (Y-suffix multi-driver 금지)** — 2026-05-28 사용자 질문 "Excel model → DB화 best practice" 의 답. 본 service 의 모든 financial_model 은 driver 를 시간축 분할 (`revenue_growth_y1`, `revenue_growth_y2`, ... `revenue_growth_y7` 처럼 7개 개별 driver) 하지 않고, **단일 driver (`revenue_growth`) + period 0..N 별 값** 으로 표현. **이유**: (a) DSL 의 `lag` 연산자 (`revenue[y-1]`) + `current_period` 자동 lookup 이 자연스럽게 작동 — formula `revenue[y-1] * (1 + revenue_growth)` 이 period 0 에는 growth[0], period 1 에는 growth[1] 을 자동 읽음. (b) Y-suffix anti-pattern 의 함정 박제 — compute_full_model (commit `9df7f71`) 의 Iippo base output: 모든 period 에 `revenue_growth_y1=6.5` 만 reuse → 7년차에 revenue 1.2 quadrillion 원 비현실적 compounding, seed comment "Y2+ override 별 row" 의도였으나 DSL 이 단일 formula 만 지원 → 모델 거짓 양성. (c) **Excel 의 "input row" 패턴과 동형** — Excel 에서도 growth rate 는 1 row × N column (period 별), 별도 7 row 가 아님. **현재 seed 정정 필요**: Iippo 의 `revenue_growth_y1~y7` 7 개 driver → 단일 `revenue_growth` driver + period 0..6 별 driver_value rows. Sentry/Canopy 는 exit-matrix-only 라 영향 없음. `revenue` formula 도 단순화 (`revenue[y-1] * (1 + revenue_growth)` 로 충분). 본 결정으로 도입되는 backlog: [B-index-driver-period-indexed-refactor](/ops/backlog) (Iippo seed 정정 + re-ingest + compute_full_model 재검증 + IRR ±1pp 회귀). **best practice 결정 4종** ([D-index-15](/ops/decisions) frozen enum 의 modeling 차원 확장): (1) driver code = snake_case 명사, 시간축 suffix 금지, (2) period-varying value 는 driver_value rows (period_index 컬럼), (3) formula 는 단일 표현 — period-별 분기 금지 (해당 시 lag/multi-period 패턴 사용), (4) base_revenue_period0 같은 sentinel 은 financial_model row 의 명시적 컬럼. **LP-deliverable 관점**: 동일 model 을 1년 후 재계산해도 deterministic — driver_value 의 period 별 값이 audit trail 의 단일 SoT. Excel 의 `=A2*(1+$B$3)` 같은 cell-reference anti-pattern 영구 차단. | 2026-05-28 |
| D-index-17 | **ic + ingest skill ownership Blueprint → index 이전 (overlap 기간 양쪽 보유)** — 2026-05-28 사용자 결정. 도메인 alignment: `ic` skill (19-agent IC memo orchestration) 은 투자 도메인 → index 가 자연 owner. `ingest` skill (dataroom pdf/pptx/xlsx → md clone) 은 ic 의 직접 의존이라 함께 이전. **이전 방식 = overlap (copy)**, symlink 아님 — 안정화 기간 동안 양쪽 모두 byte-identical 보유, **index/skills/ = canonical SoT**, `/Users/axe/blueprint/.claude/skills/` = mirror (deploy 호환성). Phase 1 후속 대상: `due-diligence`, `vc-deal-sourcing` 도 도메인 정합 (별도 결정). `portfolio-management` + `investor-relations` 는 [D-index-12](/ops/decisions) 에서 이미 pmc skill 흡수 결정. `ctx` / `humanizer` / `report-writing` / `vault-secret-capture` / `office-admin` / `code-review` 등 일반 skill 은 Blueprint 잔존. **안정화 sunset 기준 3가지** (모두 충족 시 Blueprint mirror 제거 — 별도 결정): (a) 다음 3 deal 의 IC 실행이 `index/skills/ic/` 기반 정상 작동, (b) Blueprint Claude Agent SDK 가 index/skills/ mount/sync 자동화 확립, (c) `ic --push-to-index` mode 일반화 ([B-ic-push-mode-impl](/ops/backlog)). 본 결정 + sunset 작업 = `B-index-skill-overlap-sunset`. **Phase 2 진화 path** (별 backlog): `B-index-skill-mcp-discovery` (index MCP 에 `list_skills` + `get_skill_resource` tool) + `B-blueprint-skill-mcp-client` (Claude Agent SDK 가 MCP 로 skill 발견, filesystem 의존 제거) + `B-index-skill-versioning-schema` (`index.skill_resource@1.0` schema + audit_event — per-deal "이 IC 의 메모는 ic skill v8.3 으로 작성" trace). Overlap 기간 sync 책임 = index 편집 후 Blueprint mirror 로 sha256 검증 cp. Blueprint hook (`skill-sot-guard.sh`) 가 main 직접 편집 차단 → drift 방지 자동화. 상세 = [/services/index/skill-ownership](/services/index/skill-ownership). | 2026-05-28 |
| D-index-16 | **IRR methodology 단일화 — per-leaf weighted 만 사용, anchor methodology deprecate** — 2026-05-28 사용자 결정. 본 service 의 모든 deal IRR 산출은 **per-leaf weighted methodology** (each leaf: `(proceeds/committed)^(1/timing) - 1` 산출 후 joint_probability 가중 합산) 로 통일. 별 anchor methodology (V5 final 의 F/D Pre anchor + Series A 희석 chain + success_probability 단일 flow) 폐기. 이유: (a) **데이터 정합으로 충분** — V1 yaml outdated → V5 final 의 3 보강 layer (광고 element 본문화 + 서울시 4자 합의 + KB 캐피탈 capex debt backbone) 반영 시 per-leaf 가 자연스럽게 27% 매칭. Canopy V1 → V5 정합 3-step (writedown recovery_rate 도입 + scenario probability rebalance + never writedown 비합리성 정정) 으로 -17.41% → 26.39% 달성, IC pass 27% baseline Δ=0.01 PASS. (b) **단일 methodology 운영 단순성** — deal 마다 다른 methodology 선택 logic 불필요. financial_model schema 에 `irr_methodology` enum 추가 불필요. (c) **3 deal per-leaf ALL ±1pp**: Iippo 37% (computed 36.52%) / Sentry 41% (40.26%) / Canopy 27% (26.39%) — 일관성 검증 완료. 본 결정으로 폐기되는 backlog: `B-index-canopy-anchor-irr-algo` (anchor IRR 별 algorithm) + `B-index-canopy-v5-anchor-methodology` (anchor 재구현). 본 결정으로 발견된 신규 발견 = V1 yaml 의 outdated assumption (upside scenario 10% never writedown, base 20% never writedown 같은 구조적 결함) 을 ic skill `--push-to-index` 시 자동 surface 가능 — within-scenario writedown probability 합리성 check 가 financial_model validate trigger 로 추가 ([B-index-leaf-probability-sanity](/ops/backlog) 신규). `src/irr.rs` 의 `anchor_irr` + `canopy_anchor_grid` 는 `#[deprecated]` 표시 후 Phase 1 에서 삭제. | 2026-05-28 |
| D-index-15 | **Schema authority immutable — DSL grammar + enum 은 service code 에만, skill 쪽 override 불가** — index 의 `financial_driver.formula` DSL grammar (10 operator: + - * / min max if sum avg lag growth) + `risk_alert.kind` enum 5종 + `instrument` enum 5종 (RCPS/BW/SAFE/신주/보통주) + `fund_investment.status` enum 6종 + `exit_matrix_leaf.path` enum 6종 (ma/ma_strategic/ipo/secondary/writedown/partial) 모두 **service code 에 hardcoded**, `customers.yaml` / 환경 변수 / runtime config 으로 override 불가. ic skill 의 `scenario_deltas.yaml` 이 DSL syntax error 또는 unknown enum 값 emit 시 `ingest_financial_model_xlsx` 가 `error.code = "formula_syntax_error"` 또는 `"unknown_enum"` + suggestion 본문 반환 → ctx review queue 에 highlighted error + 정정 예시 표시 → 사용자 수정 후 confirm. **skill schema drift → service crash** 시나리오 영구 차단 (worst-case risk #1). 새 enum value 추가는 (a) `src/index/schemas.rs` SoT 수정 + (b) `/index/schemas` envelope `@1.0` → `@2.0` version bump + (c) Blueprint `artifact_schema` 자동 mirror + (d) ic/pmc skill 의 yaml validator 갱신 — coordination PR 강제 (silent 추가 금지). frame 의 KSME `accounting_standard` enum 영구 freeze 패턴 ([D-frame-fund-ksme-policy-check](/ops/decisions)) 의 index domain 확장. | 2026-05-27 |
| D-bp-entity-canonical | **Entity canonical SoT 의 계층화 — Blueprint 가 entity 의 canonical name + customer 소속 + role SoT, 도메인 메타는 도메인 service SoT, customers.yaml 은 deployment 식별 SoT** — 운영자 질문 ("id, entity 정보는 blueprint 가 SoT 가 되어야 할 것 같습니다") 을 architectural 결정으로 정착. 현재 entity 정보 4 곳 분산 (customers.yaml.entities + customers.yaml.entity_meta + frame.shared.entity + Blueprint EntityRole + Blueprint User.entityScopes) — drift 위험 + bus factor. **계층화된 SoT**: (a) `customers.yaml.entities` = customer→entity 식별 (deployment prerequisite, 부팅 self-contained, 변경 X), (b) **Blueprint `Entity` 테이블 신설** = entity 의 canonical name (한글) + customerId + role (corporate/GP/etc) + isActive — 사용자-facing + 인증 게이트 + UI selector 의 자연스러운 위치, (c) `frame.shared.entity` = 회계 도메인 메타 (accounting_standard / fund_meta / biz_no / entity_kind) 유지, (d) Blueprint `EntityRole` + `User.entityScopes` = 권한 (기존 SoT 유지). 본 2026-05-27 세션의 `customers.yaml.entity_meta` 신설은 **transitional** — Blueprint Entity 테이블 신설 후 derived view 또는 cross-check drift 검증으로 전환 ([B-customers-yaml-entity-meta-derive](/ops/backlog)). **단계화 3-phase**: Phase 0 (본 결정 등재 + backlog 2 항목 등재) / Phase 1 ([B-bp-entity-table-create](/ops/backlog), Prisma Entity model + customers.yaml + frame.shared.entity union seed) / Phase 2 (customers.yaml.entity_meta 를 axe CLI 의 derived view + matrix collector 에 drift 검증 추가). frame/hive 의 `legal_name` 영문 → 한글 정정 ([B-frame-entity-legal-name-i18n](/ops/backlog)) 도 Blueprint Entity SoT sync 의 일환. | 2026-05-27 |
| D-ui-1 | **통합 layout chrome `.axe-app-shell` 도입 + `ui.axelabs.ai` 디자인 시스템 사이트 신설** (Phase 15) — cortex 운영자의 "docs.axelabs.ai 와 묘하게 다르다" 지적 (2026-05-29) 을 출발점으로, 토큰만 SSOT 화하던 기존 상태를 chrome 자체 SSOT 로 확장. **3 결정**: (a) **variant 옵션** — 단일 `.axe-app-shell` 이 `data-shell="docs|dashboard|landing"` 3 형태 분기 (sidebar+content+toc / sidebar+content / single-col), `--app-shell-{sidebar-w,toc-w,gutter,topbar-h}` 4 변수 노출. (b) **CSS-only primitives + thin React wrapper** — Rust(cortex maud)/Python(jinja) 모두 동일 markup 으로 가져갈 수 있게 styling 100% CSS 클래스 + data attribute. React `&lt;AppShell&gt;` 는 슬롯 합성 + semantic role 만. (c) **Nextra theme override** — docs.axelabs.ai 폐기 비용 큼, navbar/sidebar 슬롯에 axe 컴포넌트만 끼움 (C2 가성비 모델). **도메인 = `ui.axelabs.ai`** (1-level subdomain) — 짧음, `@axe/ui` 패키지 이름 일치, `docs.axelabs.ai` 와 페어. **배포 모델 = axelabs.ai Next.js multi-domain rewrite** (a) — host header 분기 (`Host: ui.axelabs.ai → /design/*`), 별도 컨테이너 X, build 산출물 공유. axelabs.ai/design 직접 접근도 살아있음 (dev/preview/canary). Phase 1 완료 (2026-05-29): `src/lib/styles/layout.css` 의 `.axe-app-shell*` primitives (200+ lines) + `src/lib/components/app-shell/{AppShell.tsx, Toc.tsx}` + `app/design/{page.tsx, shell/page.tsx}` 데모 + `.claude/launch.json` `axe-ui-design-preview` (:3902, :3900 은 docker production 점유) + `next.config.mjs` rewrites. 3 variant + dark mode 모두 브라우저 검증. **순차 적용 (운영자 확정 후)**: (1) ui.axelabs.ai 인프라 (DNS + tunnel ingress + customers.yaml) (2) cortex `scripts/sync-axe-ui.sh` 갱신 + maud `page()` AppShell markup (3) docs.axelabs.ai Nextra theme override (4) axelabs.ai 메인 `/app/page.tsx` → `variant="landing"` (5) frame · hive · matrix 신규 적용. **본문**: [/services/ui](/services/ui). | 2026-05-29 |
| D-ui-2 | **layout primitives (Stack/Cluster/Grid/Container) + ThemeToggle 를 @axe/ui SSOT 로 흡수** (Phase 16) — [D-ui-1](/ops/decisions) chrome SSOT 의 micro 레이아웃 짝. 출발점: matrix 페이지가 `col(gap)`/`grid()` inline 헬퍼로 flex/grid 를 재발명 + design 페이지가 ThemeProvider 우회해 `document.documentElement` 를 직접 토글하던 버그. **흡수 5종**: Stack (세로 flex+gap) · Cluster (가로 flex+wrap — toolbar/액션 줄) · Grid (`auto`+`min` auto-fill 으로 cortex `.cortex-metric-grid` 대체) · Container (max-width 중앙) · ThemeToggle (light/system/dark, `useTheme` 위 thin UI — DOM/storage 반영을 Provider 에 위임, 외부 아이콘 dep 0). chrome 과 동일하게 styling 100% CSS 클래스 (`.axe-stack`/`.axe-cluster`/`.axe-grid`/`.axe-container`/`.axe-theme-toggle` + `--axe-grid-min`) → cortex maud/jinja 등 비-React 소비자 동일 markup. gap = spacing scale 1:1 (매직 px 금지). **채택·브라우저 검증 2026-05-29**: `app/page.tsx` (axelabs.ai 홈 — Hero/Section/Footer 컴포지트 + Stack/Cluster/Grid, D-ui-1 step 4 동시 이행) + `app/matrix` (MatrixNav ThemeToggle + page 전체) + `app/design` (ui.axelabs.ai). cortex/docs/blueprint 순차 적용 대기. 본문: [/services/ui § Layout primitives](/services/ui). | 2026-05-29 |
| D-ui-3 | **디자인 시스템 도메인 `ui.axelabs.ai` → `design.axelabs.ai` rename (완전 교체·구 도메인 폐기) + 문서 HTML 템플릿 (IC Memo · LP letter, 가로/세로) 도입** — 운영자 Phase 2 결정 (2026-05-29). **(1) 도메인**: `design.axelabs.ai` 가 의미를 더 명확히 전달 (디자인 시스템 + 문서 템플릿 showcase). `ui.axelabs.ai` 는 ingress 제거로 catch-all 404 (완전 교체, 병행 X). 패키지 이름은 `@axe/ui` 유지 (도메인 ≠ 패키지) → docs 경로도 `/services/ui` 유지. **(2) 분기 메커니즘 정정**: host 분기는 `next.config.mjs` `rewrites()` 가 아니라 **`proxy.ts`** (Next.js 16 convention) — 정적 prerender 된 `/` 에 `next.config` rewrites 가 안 걸리는 함정 우회 (proxy 는 항상 runtime). `Host: design.axelabs.ai` → root 를 `/design` rewrite, sub-path 는 root 로 308, `axelabs.ai/design/*` 는 404. **(3) 인프라 (vault CF 토큰으로 처리)**: `design.axelabs.ai` proxied CNAME → `d8efecdd….cfargotunnel.com` 을 axelabs.ai zone 에 CF API (`Cloudflare API - axelabs` 토큰) 로 생성. tunnel ingress 는 **remote-managed** ([known-gaps Cortex 7함정 #7](/ops/known-gaps)) 라 `config.yml` 편집 무효 → `PUT /accounts/<acct>/cfd_tunnel/<uuid>/configurations` 로 `ui`→`design` 1-rule swap (v21→v22, 나머지 15 rule 보존). 함정 2개: ① `cloudflared tunnel route dns` 는 cert-scoped (axellc.com) 라 `design.axelabs.ai.axellc.com` 오생성 → CF API 로 삭제, axelabs.ai zone DNS 는 반드시 API 토큰 사용. ② 신규 1-level host 직후 로컬 resolver AAAA-only → IPv6 무라우팅 머신 curl HTTP 000 (production 무관, `curl -4`/`--resolve` 로 검증). 검증: design 200 (양 edge·@axe/ui 페이지) · sub-path 308 · ui 404 · axelabs.ai/www/docs 무영향. **(4) 문서 템플릿**: AXE 발신 문서 (IC Memo · LP letter 등) 를 `.axe-doc` CSS-class HTML 로 — 가로(landscape)·세로(portrait) **모두** modifier 로 지원 (문서 성격별 고정 X), A4 `@page` + `@media print` (브라우저 인쇄→PDF), 기존 `md-to-pdf` 렌더 파이프라인과 통합 (병렬 렌더러 신설 X). design.axelabs.ai showcase 에 orientation 토글 + 인쇄 버튼. **구현 완료 (2026-05-29)**: `src/lib/styles/document.css` (`.axe-doc*` + named `@page` 스코프) + `src/lib/templates/documents/ic-memo.html.jinja`·`lp-letter.html.jinja` (jinja2 가로·세로 4 combo 렌더 검증) + `app/design` 쇼케이스 섹션 (문서·orientation·zoom 토글 + 인쇄). 렌더는 기존 md-to-pdf skill (pandoc + chromium `--print-to-pdf`) + ic skill `check_pdf_quality.py` 게이트 재사용 (병렬 렌더러 X — body 슬롯에 markdown→HTML 주입). **본문**: [/services/ui](/services/ui). | 2026-05-29 |

### D-bp-mcp-1 — Blueprint MCP standalone (양파껍질 lesson)

Blueprint 자신의 read-only MCP 서버 launch (`axe.axelabs.ai/blueprint/mcp`, 9 tools). 의도: frame 의 `auth_oidc.py` + `mcp/http_server.py` 를 byte-by-byte 미러. 실제: "비슷하게" 작성 → claude.ai 등록 시 **5 단계 순차 차단** (PR #331~#335, 약 1.5 h 소비):

| # | 차단 | 메시지 (claude.ai) | 원인 |
|---|---|---|---|
| 1 | server 500 | "integration may not be available right now" | `httpx.Timeout(connect, read)` 2-arg → httpx 0.28 ValueError |
| 2 | 진단 불가 | (모든 401 이 같은 메시지) | `_unauthorized` body 가 reason 무시 |
| 3 | 토큰 검증 401 | "rejected the credentials, so the connection was reverted" | `audience=app_id_uri` 단일 (v2 토큰 aud = client_id GUID 임) |
| 4 | 인증 후 첫 호출 RuntimeError | "Task group not initialized" | Starlette Mount 가 FastMCP child lifespan 미전파 |
| 5 | 421 Misdirected | "Invalid Host header: axe.axelabs.ai" | FastMCP DNS-rebinding guard, allowed_hosts env 미설정 |

**결정**: 새 MCP 서버는 [/architecture/mcp-server-checklist](../architecture/mcp-server-checklist) 의 9·5·5·14 체크포인트 (azure manifest 9 · python 코드 5 · compose 5 · 운영 14) 를 1:1 통과 후 production. 시작은 `cp -R frame/src/frame /tmp/NEW_SERVICE` 부터, 그 다음 service-specific edits.

### D-bp-mcp-2 — Blueprint MCP blue/green pair

D-bp-mcp-1 launch 직후 진단으로 발견: Blueprint MCP 는 frame/hive 의 docker compose 패턴 (`&frame-mcp-blue` anchor + green sibling) 을 **미러하지 않은 단일 replica** 였음. `docker compose up -d --build mcp` 시 build + recreate 5-10s 다운 발생 — D-config-13 의 "다운타임 0 frame deploy" 원칙에 어긋남.

**결정**: `docker/docker-compose.yml` 의 `mcp:` 블록을 `mcp-blue: &blueprint-mcp-blue` + `mcp-green` 으로 분리. blue 가 docker network alias `blueprint-mcp` 보유 (active), green 은 alias 없이 가동 (passive). swap = `docker network connect/disconnect --alias` + `caddy reload`, sub-second. cloudflared 비건드림 (D-config-13 §3 frame 패턴과 동일).

host port: `blueprint-mcp-blue:3152`, `blueprint-mcp-green:3153` (디버그용, 외부 path 는 여전히 `:3151` Caddy proxy).

### D-bp-entity-1 — Blueprint entity 개념 도입 (PARA × entity)

진단 (2026-05-21 5분야 멀티 에이전트): Blueprint 의 `Organization` 모델이 single-row stub (`prisma/schema.prisma:689`), `Workspace/UsageLog/Agent` 에 organization FK 부재 (line 688 "별도 PR" 주석). 동시 `customers.yaml` 의 `axe.entities: ["axec","axev"]` (frame/hive 와 정합) 은 이미 회계/HR 차원에서 격리 운영 중. Blueprint 의 PARA 폴더 컨벤션 (`/Ventures · /Corporation · /General` × `1. Project · 2. Area · 3. Resource · 4. Archive`) 도 entity 차원의 격리를 함의.

**결정**:

| 항목 | 방향 |
|---|---|
| entity 정의 | `axec` (AXE Corporation), `axev` (AXE Ventures) — frame/hive 와 정합. `General` 은 cross-entity bucket 으로 추후 (axec/axev 외) entityId 부재 row 가 대응 |
| 모델 | `Workspace.entityId` FK (nullable for migration) + `Workspace.paraLayer ParaLayer?` enum `{PROJECT, AREA, RESOURCE, ARCHIVE}` — 4 PARA layer 모두 동일 row-level entity scope |
| 격리 강도 | hive 의 schema-per-entity 와 달리 **row-level FK + auth gate** (D-hive-1 의 SQL boundary 격리 미적용). Blueprint 의 cross-entity workflow (Teams bot · IC pipeline · Trinity) 와 부합 |
| Area/Resource/Archive | 별도 first-class 모델 안 만들고 Workspace 의 paraLayer variant. 고유 속성 발견 시 후속 PR 분리 |
| 적용 시점 | **Stage 1 외부 customer rollout 전**. `customers.yaml` 의 `axe.entities` 가 이미 production 이므로 single-customer 내 multi-entity 만으로도 시급 |

**Implementation** ([PR #339](https://github.com/soohunkang/blueprint/pull/339), 2026-05-22, 단일 PR 4 commit):

1. Prisma migration: `Entity` 모델 + `ParaLayer` enum + `Workspace.entityId/paraLayer` + D-bp-entity-2 provenance 3필드 + `User.entityScopes`. Idempotent SQL + axec/axev seed. Postgres baseline 부재 → `scripts/apply-entity-para-migration.ts` 운영자 1회 적용 후 매 boot `seed-entities.ts` 가 idempotent upsert.
2. drivePath 기반 backfill (`scripts/backfill-workspace-entity-para.ts`): `/Ventures/...` → entityId=axev, `/Corporation/...` → entityId=axec, `paraLayer` = `1_Project`/`2_Area`/`3_Resource`/`4_Archive` segment match. dry-run + apply 분리.
3. `src/lib/entity-scopes.ts` (resolve/hydrate/get/require + entityScopeWhereFilter) + `src/lib/auth.ts` signIn hydration + `src/lib/workspace.ts` listWorkspaces opt 확장 + `/api/workspaces/*` 게이트.
4. UI: `/axe/projects` entity dropdown + 항상 `paraLayer=PROJECT` fetch / `/axe/ara` stub → ARAClient 3-tab + fork badge.

**사용자 결정 (2026-05-22)**: Workspace ↔ Entity = scalar 1:N (OneDrive `/Ventures/` `/Corporation/` 폴더 분리가 SOT, cross-entity 는 `User.entityScopes` 로 처리). frame fund 회계 N:M 권고는 reject.

**Production hotfix** ([PR #341](https://github.com/soohunkang/blueprint/pull/341), 2026-05-22): verification 중 발견한 3 drift — (a) `docker-compose.yml` app-green block 에 customers.yaml mount + `CUSTOMERS_YAML_PATH` env 누락 (blue 만 있던 mount 가 cutover 시 옮겨지지 않아 entityScopes hydration 항상 admin-fallback), (b) `scripts/apply-entity-para-migration.ts` 의 header comment 안 `$$` 가 splitter inDollar flag 오염 → P2010, (c) backfill regex `[.\s]` 에 underscore 추가 (`1_Project` 매치).

**Production 결과**: Entity 2 row (axec/axev seed) · Workspace 18 row 중 16 backfill 적용 (PROJECT × axec: 1 / PROJECT × axev: 14 / PROJECT × null: 2 / AREA × axev: 1 [HR]) · 5 user entityScopes hydrate · Chrome MCP /axe/projects + /axe/ara 검증 PASS.

### D-bp-entity-2 — PARA dispatch flow sub-consensus

D-bp-entity-1 머지 후 Project 종결 → Area/Resource 이관 (dispatch) 흐름. 본 결정은 dispatch UI ([PR #339](https://github.com/soohunkang/blueprint/pull/339) 의 schema 까지만 포함, UI 는 PR 5 예정) 의 4 합의:

| # | 합의 |
|---|---|
| 1 | **Copy-with-provenance (Fork)** — Project row → Area/Resource row 는 dispatch 시점의 snapshot copy. 원본 archived workspace 에 freeze. `sourceWorkspaceId` / `sourceArtifactPath` / `copiedAt` 3 필드 (D-bp-entity-1 schema 에 통합) |
| 2 | **검색 분리** — Archive = "그때 어떻게 생각했는지" (시점형, 의사결정 archaeology). Area/Resource = "지금 이렇게 생각한다" (현재형, living knowledge). Search surface 가 PARA-aware |
| 3 | **끊임없는 정비 workflow** — Dispatch 는 일회성 migration tool 이 아님. 복사본은 각 Area/Resource 의 목적에 맞게 지속 편집되는 living document. PARA 철학 (Tiago Forte) 핵심 |
| 4 | **자동 분배 ≡ LLM 제안 + 사용자 확인** — NEVER fire-and-forget. Suggestion-based, non-destructive |

**미해결** (dispatch UI PR 직전 결정): (a) Dispatch unit (file vs semantic chunk), (b) Area instance 정의 권한 (org-admin vs free), (c) 정비 트리거 우선순위 (manual / periodic / LLM-detected staleness). **권고 경로**: Path B Spike (DB 변경 없이 단일 workspace 로 흐름 검증 3-5일) → Path A 본구현 (Area/Resource UI + dispatch modal + archive search separation).

**관련 진단**: `/Users/axe/.claude/projects/-Users-axe-blueprint/memory/feedback_multi_agent_diagnosis_2026_05_21.md`

### D-bp-para-1 — PARA 범용 재구조화 (조직론 + 집(link) 모델 + governance + 죽은 딜 본질)

[D-bp-entity-1](#)/[D-bp-entity-2](#d-bp-entity-2--para-dispatch-flow-sub-consensus) 의 AXE-shaped 초기 설계(copy-with-provenance · Area=workspace)를 **범용 AI OS 관점으로 재구조화** (2026-06-06 설계 세션). 상세·철학 = [/architecture/para-os](/architecture/para-os). 미구현 dispatch/UX zone 한정 — 저장층(Artifact/ArtifactLink/McpSchema, [PR #339](https://github.com/soohunkang/blueprint/pull/339)) schema 는 유효.

**확정 결정**:

1. **PARA = 조직론** — Area=영속 기능(정적 조직, MCP=물질화), Project=cross-functional TFT(동적 조직). Resource·Archive 는 *각 Area 안*, Project 만 가로지름.
2. **dispatch = "집(home)" 모델** — move/copy/link 3지선다는 폴더-thinking 증상. artifact 몸통 1 + 집 N(link). **link=기본**(다중 Area 참조), **move**=소모성 working→Archive→폐기, **copy-curate**=재사용본 저작→Resource. → D-bp-entity-2 의 **copy-with-provenance default 를 link-default 로 revise** (copy 는 method→Resource 큐레이션 예외만).
3. **Blueprint = 도메인 서비스가 *안 덮는* 것의 substrate** (미졸업·무서비스 Area live + 그 R/A + cross-service 종합물 + 가로 결정로그 mirror). 졸업 서비스(frame/hive/index/gate)는 **자기 도메인 지식(죽은 딜·섹터 프레임 등 R/A 포함)을 가져감** — moat(죽은 딜 복리) = index. Area 졸업 트리거 = 도메인 로직/AI 상호작용(저장 아님). _[정정 2026-06-06: 원안 "모든 R/A → Blueprint" 를 졸업 기준으로 좁힘 (사용자 확정), 상세 [para-os §4](/architecture/para-os)]_
4. **substrate 3분** — typed Area=쿼리 / Resource=SoR+벡터 index(hot) / Archive=cold·폐기가능(추출 지식만 영구·queryable). 벡터=저장소 아닌 index.
5. **Governance 분리** — 결정로그(record: Blueprint core, append-only, supersede, 모든 Area cite) vs 결재워크플로(process: 전자결재, policy-driven·agent-assisted layer). 서명 한 종류(내부=외부 e-sign). Area 서비스=결정 actuator. 통합 구현=[B-bp-decision-pipeline-esign](/ops/backlog).
6. **본질 = 죽은 딜 저장·harvest** — VC 지식의 대부분이 dead deal(judgment "왜 패스" + 섹터지식)에. Archive raw=폐기 가능하되 추출 지식=영구. index 가 passed/dead 딜을 1급 저장해야 하는 근거.

**열린 질문** (확정 시 후속 D 등재): (a) 2-level scope(personal+shared), (b) governance servicization(Blueprint core vs 독립 서비스 — 부족함 진단 저장/로직/AI 로 가름), (c) Project staffing, (d) Rust 적용 범위(기존 Python 서비스 확장 언어).

**제약**: 신규 코드 = Rust (사용자 지침). SoT 메모 = `project_para_ai_os_philosophy.md` (Blueprint global memory).

### D-bp-rust-1 — Blueprint 점진 Rust 전환 (strangler-fig) · substrate = 첫 organ

[D-bp-para-1](/ops/decisions) 의 **열린 질문 (a)/(c)/(d) 를 확정**하고, "신규 코드 = Rust" 지침을 Blueprint 토폴로지에 정착 (2026-06-06 세션). 사용자 발화: "점차 blueprint 도 rust 로 전환할 계획입니다 … 점진적 대체로 하려고 합니다."

**전략 — strangler-fig (점진 대체)**:

1. **프론트엔드(React/Next.js UI) = 당분간 TS 유지.** "Blueprint→Rust" = *백엔드* 전환이지 UI 재작성이 아님. WASM 프론트(Leptos/Dioxus) 전면 재작성은 별개·먼 결정 (현재 scope 아님). → 열린질문 (d) 확정: **Rust 범위 = 신규 백엔드 organ, 프론트 제외**.
2. **백엔드(API routes + `src/lib/*` 로직) = 도메인별 Rust(axum) organ 으로 점진 추출.** Next.js 는 점점 얇은 frontend-of-record 로 후퇴, Rust 를 내부 HTTP 호출.
3. **데이터 공존 = Postgres schema-split 소유권** ("두 ORM 한 DB" 를 안전하게): Prisma=`public`(Workspace/Entity/User/Session/Issue…), Rust/sqlx=`substrate`(artifact/artifact_link/mcp_schema). 한 blueprint-postgres 인스턴스, **교차쓰기 금지** (substrate 는 Workspace 미접근, Prisma 는 artifact 미접근 → 마이그레이션 도구 충돌 0). `public` 이 시간에 따라 줄어드는 게 strangler.

→ [D-bp-artifact-4](/ops/decisions) **refine (모순 아님)**: "monolith first / 별도 KnowledgeStore service 분리 안 함 / 신규 인프라 0" 의 *인프라* 정신은 보존 (동일 blueprint-postgres · 동일 compose · 동일 `axe ship blueprint`). 바뀐 것은 *언어* 뿐 — knowledge substrate 를 Rust 프로세스로 구현 (언어 마이그레이션 목적의 프로세스 분리). frame/hive/gate 식 **독립 product-service 가 아님** (cloudflared·공개 MCP·blue/green pair·customers.yaml service·pre-push guard 등재 전부 없음).

**첫 organ = PARA substrate**:

- **경계 = Artifact-scoped** (사용자 확정): substrate 가 `artifact` / `artifact_link`(+`annotation`) / `mcp_schema` 소유. `workspace_id` · `entity_id` 는 OneDrive citation 처럼 **opaque 외부 ref**(FK 없음, 데이터 중복 0). **Workspace + paraLayer SoR = Blueprint/Prisma 잔류**. Workspace lifecycle 변경(reclassify/close) → 내부 신호(pg_notify 또는 webhook)로 substrate 의 cached paraLayer 동기화 ([D-bp-artifact-6](/ops/decisions) "Re-sync on paraLayer change" 의 cross-process 판).
- **모델은 처음부터 옳게**: [D-bp-para-1](/ops/decisions) home/link("집") 1급 — `artifact_link (artifact_id, workspace_id)` = home 멤버십 본체 + **`annotation`**(Area 별 해석 레이어), dispatch mode `link`(기본)/`copy_curate`(method→Resource)/`move`(working→Archive), `parent_artifact_id` → `derived_from_id`(진짜 파생 lineage 만). **2-level scope(personal/shared)** = artifact `scope` 컬럼 → 열린질문 (a) 확정. citation = [D-bp-artifact-3](/ops/decisions) 6종 + [D-index-6](/ops/decisions) `index.*` + [D-gate-2](/ops/decisions) `gate.decision` = **8종** 처음부터.
- **배포 = blueprint compose 내 sidecar** `blueprint-substrate` (Rust+axum, 내부 포트). 위치 = `blueprint/substrate/` (레포 내부 Cargo — polyglot 레포 = 점진 전환의 정상태). `axe ship blueprint` 한 경로 안에서 빌드.
- **Next→Rust 인증** = 기존 `BLUEPRINT_INTERNAL_API_KEY` Bearer (`/api/internal/*` 패턴) + caller identity·entity scope 헤더. 동일 compose 망 내부 호출 신뢰.
- **첫 organ 이 재사용 패턴 확립** (schema-split · 내부 auth 브릿지 · typed TS client · compose-service) → 이후 organ 들이 복제.

**열린 질문 처리** ([D-bp-para-1](/ops/decisions)):
- (a) 2-level scope → **확정: personal + shared** (artifact `scope` 컬럼, 기본 personal → 승급 shared).
- (b) governance servicization → 별 트랙 `gate` 서비스가 흡수 ([D-gate-1](/ops/decisions)/[D-gate-2](/ops/decisions)). substrate 와 무관.
- (c) Project staffing("던지면 emerge") → **후속 defer** (이번 substrate scope 아님; Project=컨테이너 + 기존 WorkspaceMember).
- (d) Rust 범위 → **확정: 신규 백엔드 organ = Rust, 프론트 = TS 유지, 점진 대체**.

**시퀀싱 (중요)**: 첫 scaffold 는 기존 M6 Stage-1 TS Artifact 테이블(Prisma `public`)을 **건드리지 않고 병행 신설**. cutover(Prisma Artifact 제거 + `/api/artifact/propose` → substrate client repoint)는 Rust 경로 동작 검증 *후* 별 stage — 기존 propose route 안 깨짐.

**정직한 비용**: polyglot 레포 + 두 마이그레이션 도구(schema-split 로 관리), Workspace↔artifact 교차 트랜잭션 상실(Artifact-scoped 라 수용 — workspace 생성 후 artifact propose 분리). 상세 ADR = `docs/adr/blueprint-rust-migration.md`. SoT 메모 = `project_para_ai_os_philosophy.md`.

### D-bp-ui-1 — Blueprint `@axe/ui` 채택 + Tailwind 4 패치

D-axe-ui-1 (SSOT 단일 배포 채널 결정) 의 Blueprint 측 implementation. 첫 SSOT 소비자 중 Tailwind 4 + Turbopack 스택을 가진 곳 — Nextra (axelabs-docs) 와 다른 CSS 파이프라인 거동 때문에 sync 단계 패치 필요.

**채택 범위 (2026-05-22)**:

| 항목 | 결정 |
|---|---|
| SSOT 경로 | `/Users/axe/axelabs/src/lib/{tokens,styles}/` (D-axe-ui-1 과 동일) |
| Blueprint dest | `src/app/_axe-ui/` (canonical `app/_axe-ui/` 와 다름 — src/ source root) |
| sync 스크립트 | `scripts/sync-axe-ui.mjs` — canonical `/Users/axe/axelabs-docs/scripts/sync-axe-ui.mjs` 패턴 + Blueprint 패치 |
| 자동화 | `predev` / `prebuild` npm hook + `check-axe-ui` dry-run |
| VERSION 필드 | `source-sha` / `source-lib-sha` / `source-lib-date` (`execSync git rev-parse + log -1`) |
| DOM 토글 마커 | `<html data-theme="dark">` 기본. `class="light|dark"` 도 SSOT 가 지원 (next-themes 호환) |
| CSP 추가 | `style-src` + `font-src` 에 `cdn.jsdelivr.net` (Pretendard + D2Coding CDN) |

**Blueprint 전용 패치 1 — fonts.css `@import url()` strip**:

axelabs SSOT 의 `src/lib/tokens/fonts.css` 는 Pretendard + D2Coding 을 `@import url("https://cdn.jsdelivr.net/...")` 로 로드. 이는 Nextra (axelabs-docs) 에서 정상 동작. 그러나 Blueprint 의 **Tailwind 4 + Turbopack 파이프라인** 은 `globals.css` 가 import 한 4 토큰 파일 (`colors.css` · `spacing.css` · `typography.css` · `fonts.css`) 을 globals.css 본문 안으로 **inline** 한 뒤 컴파일. 결과 CSS 의 구조:

```
[colors.css :root 블록] ...
[spacing.css :root 블록] ...
[typography.css body { ... } html { ... }] ...
[fonts.css 의 @import url(pretendard) ← 다른 rule 뒤로 밀림!]
[fonts.css @font-face { Sarasa } :root { --font-* }]
```

CSS spec: `@import` 은 `@charset` / `@layer` 만 선행 가능. 다른 rule 뒤의 `@import` 는 **브라우저가 silent drop**. 결과: Pretendard 미로드, body 폰트가 system sans-serif 로 fallback (검증 안 했으면 모르고 지나갈 수 있음). 빌드 단계에서 `@import rules must precede all rules aside from @charset and @layer statements` 경고 발생.

**회피**: SSOT 미변경. sync 스크립트가 `fonts.css` 복사 시 `content.replace(/^@import url\([^)]*\);\s*\n/gm, "")` 로 `@import url(...)` 두 줄만 strip. Pretendard + D2Coding 은 `src/app/layout.tsx` 의 `<link rel="stylesheet">` 로 로드 — 이는 SSOT 자체가 Clash Display 에 대해 fonts.css 주석에서 명시한 회피 패턴 ("Fontshare URL 의 f[]= 대괄호가 Next.js CSS @import 파이프라인에서 떨궈지는 이슈 회피") 의 확장. 후속 axelabs SSOT 의 모든 `@import url()` 도 동일 strip 적용 (sync 스크립트의 정적 규칙).

**Blueprint 전용 패치 2 — Legacy var alias bridge**:

35+ tsx 가 기존 토큰 (`var(--navy)` `var(--white)` `var(--gray-ax)` `var(--gray-light-ax)` `var(--dark-border)` `var(--accent-glow)` `var(--green)` `var(--red)` `var(--navy-light)` `var(--navy-mid)`) 직접 사용. 비파괴 채택을 위해 `src/app/globals.css` 의 `@layer base :root { }` 에서 alias:

```css
--navy: var(--bg-base);            /* dark: #1a0610 (legacy 동일) */
--navy-light: var(--gray-2);
--navy-mid: var(--gray-3);
--white: var(--text-primary);      /* dark: #f2e8ee (≈ legacy #f0f2f5) */
--gray: var(--text-muted);
--gray-light: var(--text-tertiary);
--dark-border: var(--border-subtle);
--accent-glow: rgb(227 255 102 / 0.15);
--green: var(--success);
--red: var(--danger);
```

`--accent` 는 legacy 값 (`#E3FF66`) 을 제거 — colors.css 가 모드별로 자동 주입 (`var(--brand-claret)` light / `var(--brand-neon)` dark). dark 모드에서 `--accent = #e3ff66` 는 legacy hex (`#E3FF66`) 와 byte-equivalent. 즉 `data-theme="dark"` 기본인 한 모든 컴포넌트 무수정 작동, light 토글 시 일관성 있게 claret 톤으로 전환.

**검증 (deployed @ 2026-05-22 PR 머지 시)**:
- `curl https://blueprint.axellc.com/_next/static/chunks/0bd4439~8glcs.css | grep -oE '\[data-theme="dark"\],\.dark'` — lightningcss optimizer 가 selector list 보존
- `--gray-1: #1a0610` (dark block), `--brand-neon: #e3ff66`, `--navy: var(--bg-base)` 확인
- Pretendard CDN 200, `/api/health` localhost + edge 200
- `next build` 컴파일 ~8s, `@import rules must precede` 경고 0

**후속 (별도 PR)**:
- 8+ tsx 의 inline `fontFamily: "'Space Grotesk', ..."` → `var(--font-sans)` 토큰화 (SVG 텍스트). 완료되면 Space Grotesk `<link>` 제거 가능.
- 35+ tsx 의 `var(--navy)/var(--white)/var(--gray-ax)` 직접 사용 → 새 토큰명 (`var(--bg-base)/var(--text-primary)/var(--text-muted)`) 점진 마이그레이션. alias bridge 는 그 동안 보존.
- Light mode 토글 UI (인프라는 준비 — `data-theme` attribute, persistence 만 별도).

**관련 진단**: `/Users/axe/.claude/projects/-Users-axe-blueprint/memory/architecture_blueprint_axe_ui_adoption.md`

### D-matrix-1 — Matrix: Rust + native MCP (no Python SDK)

AXE Labs 첫 Rust 서비스. MCP Streamable HTTP 를 JSON-RPC 2.0 + axum 으로 직접 구현 (Python FastMCP 미사용). 모니터링 서비스 특성상 저메모리 (~15 MB), 단일 바이너리, tokio 기반 concurrent health check 가 핵심 이점.

| 항목 | 결정 |
|---|---|
| 언어 | Rust 1.95 — 기존 Python 3.12+ (frame/hive/blueprint) 과 별 트랙 |
| MCP 구현 | JSON-RPC 2.0 + SSE over axum (native). MCP 프로토콜 레이어가 충분히 단순 (JSON-RPC + SSE) 하여 직접 구현 |
| DB | PostgreSQL 16 (sqlx) — 기존 서비스와 동일 DB 엔진 |
| Docker API | bollard crate — 컨테이너 상태 실시간 수집 |
| 배포 패턴 | blue/green (frame/hive 와 동일 — port 3910/3911 + proxy 3912) |

**기존 결정과의 관계**: D-bp-mcp-1 (Python + FastMCP 기반 MCP 서버 표준) 은 기존 Python 서비스에 그대로 유효. 본 결정은 infrastructure tooling 의 새 precedent — Rust 의 장점 (메모리, 바이너리 크기, 동시성) 이 Python SDK lock-in 보다 우선하는 경우에 한정.

**Rust 마이그레이션 적합성 평가** (2026-05-21): 기존 8개 프로젝트 (frame, blueprint, magnet, stream, artemis, cortex, mysrt, tether) 의 Rust 전환은 모두 No 판정 (mcp Python SDK + anthropic SDK + 한글 PDF 파싱 lock-in). 새 컴포넌트에서 시작하는 것이 미래 후보 — matrix 가 그 첫 사례. **2026-05-26**: cortex 가 두번째 Rust 서비스 — 기존 file-based recall 폐기 후 artifact-first 재출발 (D-cortex 참조).

### D-matrix-2 — Matrix: WAN/인터넷 가용성 모니터링 + ISP 귀책 판별 (2026-06-03)

운영자의 댁내 Wi-Fi/인터넷 장애를 통신사에 민원 제출하려 macmini 시스템 로그 (`/var/log/wifi.log` 11일치 + 통합로그) 를 분석한 데서 출발. 단말 로그는 "이 기기가 해당 시각 인터넷 도달 실패" 는 증명하나 **ISP vs 댁내 (공유기/Wi-Fi) 귀책을 단독 확정 못 함** (6/3 장애는 DNS 실패 + IPv4 경로 99회 상실 = upstream 정합이나 동시에 Wi-Fi 펌웨어 트랩 1회 → 100% 단정 불가). matrix 가 상시 가동 인프라 모니터링 MCP 이므로 "인터넷 회선 가용성" 을 종합 모니터링 항목으로 흡수 — 향후 장애를 분 단위로 자동 기록 + 귀책 자동 판별.

| 항목 | 결정 |
|---|---|
| 구현 위치 | `collector.rs::check_wan()` — `run_check` 의 5 번째 점검. collector 가 제네릭 (`ServiceCheck{name,type,status,detail}`) 이라 **프로브 1 개 추가 = 저장·alert·history·uptime·status board 자동 적용, 스키마 변경 0** |
| 3 프로브 | `wan-gateway` (공유기 ICMP — LAN 링크) · `wan-internet` (공인 anycast ICMP, RTT + 손실%) · `wan-dns` (호스트네임 해석 시간, `tokio::net::lookup_host`). `tokio::join!` 동시 실행 |
| 귀책 판별 | gateway↑ + internet↓ ⇒ **ISP/WAN fault** (warning 발생) · gateway↓ + internet↓ ⇒ 댁내 링크/Wi-Fi. wifi.log 분석이 못 한 구분을 상시 자동화 |
| 컨테이너 ICMP | `cap_add: NET_RAW` + 런타임 이미지 `iputils-ping` (권한상승 없는 unprivileged ping). Docker Desktop NAT 통과 + 공유기 (192.168.55.1) / 외부 (1.1.1.1) 도달 사전검증 (2026-06-03, 손실 0%) |
| 신규 env | `MATRIX_LAN_GATEWAY` (default 192.168.55.1 — 노드별·DHCP 주의) · `MATRIX_WAN_TARGET` (1.1.1.1) · `MATRIX_DNS_HOST` (google.com). 비밀 아님 → vault 등재 불요. `MATRIX_CHECK_INTERVAL` default 60→30 (끊김 해상도) |
| 범위 (v1) | 프로브 + 귀책 alert. 기존 `get_service_history` / `get_uptime_report` 가 `wan-*` 이름에 즉시 작동. **v2 후보** = `get_wan_report` MCP tool (장애 구간 start/end/지속 + 업타임 + 귀책 = ISP 제출용 타임라인). [B-matrix-wan-report-tool](/ops/backlog) |
| 검증 | host `cargo check` 통과 (cargo 1.95). 런타임 검증은 `axe ship` 후 `/matrix/api/status` 에서 `wan-*` 등장 확인 |

**기존 결정 정합**: D-matrix-1 (collector 제네릭 설계) 위에 프로브 추가만으로 성립 — 새 테이블/도구 불요가 핵심. multi-tenant — `wan-*` 는 노드별 자기 회선 모니터라 customer sovereignty 와 자연 정합.

### D-matrix-4 — netheal: 호스트 인터넷 자가치유 데몬 (2026-06-04)

D-matrix-2 가 WAN 끊김을 *감지·귀책* 하면, netheal 은 *치유* — 6/3 운영자가 손으로 한 WiFi off/on 6회 → 재부팅을 자동화. matrix 는 Docker (Linux VM) 안이라 macOS `en1` 을 제어할 수 없어 치유는 호스트로 분리.

| 항목 | 결정 |
|---|---|
| 위치 제약 | 치유는 **호스트 root LaunchDaemon** (`com.axe.netheal`) — matrix=감지/가시화, netheal=치유. Docker 비의존 → 네트워크/컨테이너 동반 장애에도 작동 |
| 치유 사다리 | DNS 플러시 (dscacheutil + mDNSResponder HUP) → DHCP 갱신 (ipconfig set DHCP) → WiFi 바운스 (networksetup setairportpower off/on). 약→강 |
| ISP 인지 백오프 | gateway↑ + 외부↓ = ISP/회선 장애 → WiFi 바운스 futile → DNS/DHCP 1회 후 HOLD. gateway↓ = 로컬 → 풀 사다리 |
| 안전장치 | 디바운스 (~60s 지속돼야 작동) · 쿨다운 90s · 시간당 12회 서킷브레이커 · **자동 재부팅 기본 OFF** (`NETHEAL_ALLOW_REBOOT`, 박스가 frame/hive/matrix 구동) · 전 동작 타임스탬프 로깅 (`/var/log/axe-netheal.log`, 증거 겸용) |
| 구현 | 순수 bash (의존성 0, 감사 용이, `/bin/bash` 3.2 호환). `~/axe-netheal/{axe-netheal.sh, com.axe.netheal.plist, README.md}`. `bash -n` + 스모크 (started + 오발동 0) 검증 |
| 잔여 | 운영자 sudo 설치 (/usr/local/sbin + /Library/LaunchDaemons) + `launchctl bootstrap` → inventory.mdx launchd 표 등재. [B-netheal-install](/ops/backlog) |

**기존 결정 정합**: D-matrix-2 의 gateway-vs-internet 귀책 로직을 그대로 재사용 (감지→치유). multi-tenant — 노드별 자기 회선 치유라 customer sovereignty 와 직교.

### D-cortex — Cortex (AI-native relationship CRM, 2026-05-26)

7 개 결정의 묶음. 강수훈 개인이 Windows + OneDrive 의 단일 `Network_CRM.xlsx` 로 운영해온 1인용 투자 네트워크 CRM 을 platform 안으로 끌어들임 — frame 이 회계 자산을, hive 가 HR 자산을 platform 안으로 끌어들인 것과 동일 패턴. 도구는 개인용이었지만 데이터 (HPE 딜 / AXEV 파이프라인 / LP·SI·FI·Portfolio·Talent 관계) 는 회사가 의존하는 자산이라 한 사람의 OneDrive 에 잠겨있는 게 본질적 위험.

기존 `/Users/axe/cortex` (2026-03 시작한 file-based "VC 심사역 AI 기억 시스템" — 186 markdown topic tree + 16 entity profile + 3,394 keyword DB + 45,903 connection edge) 은 도메인이 유사했지만 모델 (파일 기반 / 단일 사용자 / 자체 router LLM) 이 새 설계와 완전히 다름 → `.legacy.20260526/` 으로 rename 보존 (623 MB, 추후 enrichment migration 참조용).

| ID | 결정 | 핵심 |
|---|---|---|
| **D-cortex-1** | **M6 artifact 모델 Day 1 채택** | Blueprint 의 typed-fact artifact + citation + append-only event log + PARA dispatch 가 Q4 2026 target 에서 Day 1 표준으로 escalation. Cortex 가 platform 의 첫 artifact-first reference impl. 다른 vertical service 도 향후 동일 패턴. frame 의 domain-strict 테이블 (entity/journal/raw_transaction) 은 회계 KSME 제약 때문에 그대로 유지 — `/schemas` endpoint 가 artifact mirror. |
| **D-cortex-2** | **per-user private (owner_id + Postgres RLS)** | 모든 도메인 테이블 (artifact, citation, artifact_event, google_oauth_token) 에 `owner_id` 필드 + `FORCE ROW LEVEL SECURITY` + `cortex_app` NOSUPERUSER 역할 + `SET LOCAL ROLE cortex_app; SET LOCAL cortex.actor = <email>` 패턴. POSTGRES_USER `cortex` 가 docker postgres init 단계에서 SUPERUSER 로 만들어져 RLS 우회 가능하므로 application connection 은 항상 cortex_app 으로 role downgrade. GUC 이름 = `cortex.actor` (`current_user` 가 Postgres 예약어). |
| **D-cortex-3** | **Google Contacts canonical, 단방향 pull default + enrichment 보존 계약** | 흐름: 명함 → Remember → Google Contacts → Cortex (10분 cron). Google 이 base field (이름·전화·이메일·소속·직급) owning. Cortex 는 enrichment (분류 HPE/AXEV/구분1/구분2 / 메모 / interaction / 관계 / deal link / cohort / former_org/title 등) 만 owning. 신규 인물 진입은 항상 Remember/Google 경로. 양방향 sync 안 함. **Sync 보존 계약** (2026-05-29 PM4 hardening — 동일 일자 PM 의 데이터 손실 버그 발견 + 수정): Google → Cortex overlay 는 `GOOGLE_CANONICAL_KEYS` 화이트리스트 (display_name · given_name · family_name · org · title · department · emails · phones · memberships · biographies · userDefined) 만, 그것도 *meaningful* (non-null + non-empty 문자열/배열/객체) 값일 때만. Cortex enrichment 키는 sync 가 절대 안 건드림. **버그 원인**: `upsert_from_person` 의 `UPDATE artifact SET payload=$1` 가 전체 payload 덮어쓰기 → register_person 으로 등록된 person 의 enrichment (display_name 포함) 가 10분 후 sync 실행 시 빈 Google payload 로 destroy 됐음. **증거**: 김승우 (코오롱인더스트리 전무) + 정성화 (한섬비즈온 대표) 신규 등록 직후 audit 가 propose (operator) → 4분 후 edit (system:google-sync, display_name=null + 모든 enrichment 사라짐) 기록. **복구**: append-only audit log 보존 덕분에 propose payload + 후속 operator edit 으로 restore (op='restore' event, actor='system:enrichment-recovery-D-cortex-3'). **동반 fix**: register_person 의 createContact 가 `display_name` 만 보내는데 People API 의 `Name.displayName` 은 server-computed 라 무시됨 → `unstructured_name` 필드 같이 보내도록 `NameCreate` 확장 (mcp.rs + web/views.rs push_one). 향후 신규 등록은 Google 측에 정상 displayName 저장. **검증**: 복구 + 강제 sync → enrichment 보존, sync 는 `memberships=["myContacts"]` (Google meaningful) 만 overlay. **단방향 원칙의 예외 (식별 키 정정 한정)**: PM4c 에 발견 — `unstructured_name fix` 가 ship 되더라도 fix 이전에 생성된 134 Google contact 들의 displayName 은 빈 상태 그대로. 이걸 Google 측에 재push 하는 도구 = `update_contact` MCP tool + `cortex backfill-google-names` CLI ([D-cortex-google-names-backfill](/ops/decisions)). 둘 다 **식별 키 (display_name/given/family, 그리고 phone/email/org/title 등 GOOGLE_CANONICAL_KEYS 의 일부)** 만 push, enrichment 키 (memo/cohort/HPE/AXEV/former_org/former_title) 는 **절대 push 안 함**. updateContact 는 createContact 의 보완재 (역방향 sync 가 아닌 식별 정정), 단방향 pull default 와 양립. **이번에 함정 추가 발견 — Docker layer cache**: 코드 fix push 후 `docker compose build` 만 했을 때 src content 변경에도 캐시된 빌더 레이어가 재사용되어 old binary 가 컨테이너로 들어가는 케이스 발생. `--no-cache` 강제 빌드 + 새 binary 동작 (enrichment 보존) 직접 검증 후 134 backfill 실행. **PM7 재발 — blue/green 동일 binary invariant + 회귀 테스트 추가** (2026-05-29 PM7): 같은 날 저녁 동일 증상 재현. 김승우/정성화 (한섬·스위티) 3명의 memo/cohort/former_org/former_title 이 다시 system:google-sync 의 edit event 로 wipe. **진짜 root cause**: 소스는 이미 PM4 의 overlay-preserving 코드였으나, `docker compose build --no-cache` 가 `cortex-mcp-blue` 한 서비스에만 적용됐고 `cortex-mcp-green` 은 stale 캐시된 옛 이미지 그대로. blue/green 둘 다 `run_loop` 를 동시에 돌기 때문 (leader election 부재) sync 한 번 돌 때마다 race — 새 코드의 보존 INSERT 직후 옛 코드가 같은 초에 destructive UPDATE 로 덮음. **검증법**: `docker exec cortex-mcp-blue sha256sum /usr/local/bin/cortex` 와 `docker exec cortex-mcp-green sha256sum /usr/local/bin/cortex` 가 정확히 같아야 함 (image-level hash 는 빌드 timestamp 비결정성으로 달라도 OK — 안의 binary 만 같으면 안전). **복구**: 운영자 status='paused' → 두 서비스 모두 `--no-cache` 재빌드 + `up -d --force-recreate` → 183 person `restore-from-audit --apply` → sync 재개. **회귀 차단**: `src/google/sync.rs` 에 `#[cfg(test)] mod tests` 5개 unit test 추가 — (1) overlay 가 enrichment 보존 + (2) Google canonical 이 모두 null 일 때 enrichment 보존 (edge case) + (3) wholesale replace 차단 + (4) 멱등 + (5) is_meaningful 가드. `cargo test --bin cortex google::sync::tests` 5/5 통과. 향후 ship hook 에 묶을 것. **운영 invariant 명문화** (CLAUDE.md 의 운영 함정 섹션): sync.rs 같은 critical path 수정 시 blue/green **둘 다** 명시적 `--no-cache` 후 binary sha256 일치 검증 필수. | 2026-05-26 + 2026-05-29 PM4 (sync 보존 + updateContact 확장) + 2026-05-29 PM7 (blue/green race + 회귀 테스트) |
| **D-cortex-4** | **opportunistic push to Google (신규 등록 시에만)** | `register_person` MCP tool 호출 시, 사용자가 Google 에 없는 사람을 입력하면 `people:createContact` 으로 Google 에도 등록 (resource_name 받아 artifact citation 으로 사용). Update push X — Cortex enrichment 필드 (분류·메모·관계·interaction) 는 Google 으로 안 흘러감. Cortex-only person 은 존재하지 않음 (모든 artifact 가 google_contact citation 보유 가능). |
| **D-cortex-5** | **Day 1 multi-user (per-user Google OAuth Web client)** | 각 사용자가 자기 개인 Google 계정 (Remember 흐름의 upstream) 을 Cortex 에 authorize. refresh_token 은 Postgres `google_oauth_token` 에 `pgp_sym_encrypt(token, CORTEX_PII_PASSPHRASE_AXEC)` 로 저장. per-user sync 가 격리 — 한 사용자 sync 실패가 다른 사용자 안 막음. Initial 사용자는 강수훈 (axellc.com) 이지만 architecture 가 multi-user 지원. State JWT (HS256 with CORTEX_JWT_SECRET) 가 OAuth callback 인증 (DB hit 없이 stateless owner_id 추출). |
| **D-cortex-6** | **MCP-only 1차 (Next.js 프론트 없음)** | claude.ai connector + Claude Code 가 primary client surface. **12 tools** (whoami / list_persons / search_person / get_person / register_person / log_interaction / list_interactions / connect_google / disconnect_google / sync_google_now / classify_person / update_person) + RFC 9728 OAuth metadata (server-level + **resource-level** `/cortex/mcp/.well-known/oauth-protected-resource` 둘 다 — D-ops-23 frame 학습) + Google OAuth callback HTML. UI 가 필요해지면 Blueprint 안에 Cortex 페이지 추가 (M6 통합 이후). 별도 Next.js 안 짓기. **→ D-cortex-6.1 로 부분 번복 (2026-05-29).** |
| **D-cortex-6.1** | **read-only 웹 UI 는 cortex binary 안에서 (axum + maud)** | 운영자 "axe.axelabs.ai/cortex 웹에서 볼 수 있게" 요청 (2026-05-29). D-cortex-6 의 "UI 는 Blueprint" 부분만 번복 — Blueprint 분리 X 이유: (a) D-cortex-7 의 단일 binary 운영 ergonomics 유지, (b) 같은 PgPool / RLS / `set_current_user` 헬퍼 재사용, (c) Microsoft federation 코드 (oauth_as.rs 의 server-to-server token exchange + JWKS verify) 가 그대로 cookie 세션용으로 재사용 가능, (d) Blueprint 가 M6 mirror 까지 cortex 데이터를 모름 → cross-service HTTP 호출 회피. **구성**: `src/web/{session,auth,views,mod}.rs`. 세션 = HS256 JWT cookie `cortex_session` (`tok="web"` discriminator, 8h sliding refresh, HttpOnly+Secure+SameSite=Lax, Path=/cortex). 로그인 = Entra ID federation (`/cortex/login/start` → Microsoft → `/cortex/login/callback`, 별도 redirect URI 등록 — Entra app 의 web.redirectUris 에 `https://axe.axelabs.ai/cortex/login/callback` 추가). 페이지: `/cortex/home` 대시보드 (kind 별 count + Google 연결 상태 + 최근 audit event) · `/cortex/{people,orgs,deals,interactions,relationships}` 리스트 (visibility 필터 + 페이지네이션) · `/cortex/a/:id` detail (payload pretty + citations + 최근 20 events) · `/cortex/google/reconnect` (기존 `build_authorize_url` 재호출 wrapper). **read-only**: write 는 여전히 MCP. 향후 write 추가 시 CSRF 토큰 필요 (현재 GET 만이라 미적용). **세션 격리**: MCP `auth::middleware` (Bearer) 와 web `require_session` (Cookie) 은 별도 axum layer 로 적용 — `/cortex/mcp` 가 cookie 우연히 받아도 Bearer 헤더 없으면 401, web 라우터가 Bearer 받아도 cookie 검증 분리. `tok="web"` 미스매치 시 둘 다 거절. | 2026-05-29 |
| **D-cortex-google-push-batch** | **xlsx 적재 후 Google push 큐 운영 — batch + skip + visibility 격리** | xlsx `--create-missing` 이후 Cortex-only person 215~ 명을 Google 에 동기화하려면 행 단위 클릭 비현실적. D-cortex-4 (opportunistic) 안에서 batch 정의 = **사용자 명시 클릭 (체크박스 multi-select + "Push selected (N)" 버튼) 으로 N 건 enqueue, worker 가 1 req/sec 페이스로 Google quota (90/min/user) 안에서 순차 처리**. **데이터모델 — JobRegistry** (`src/web/google_push.rs`): `Arc<Mutex<{jobs: HashMap<JobId,JobStatus>, owner_running: HashMap<owner,JobId>}>>` (in-memory, 프로세스 재시작 시 손실 허용 — `push_one` 의 google_contact citation 중복 거절로 재시도 idempotent). **owner 동시 1 job 락** — 2nd start 가 같은 owner 면 진행 중 job 의 status page 로 `?already_running=1` 와 함께 redirect (에러 페이지 X, 운영자가 진행 중인 batch 가 어디 있는지 즉시 봄). **진행률**: status page = progress bar + 결과 table + 클라이언트 `setInterval(1500ms)` 로 JSON polling — 워커가 끝나면 stop. **owner 격리**: status snapshot 핸들러는 `owner == auth.email` 강제 (다른 사용자 batch 못 봄). **데이터모델 — skip 마킹**: 연락처미상 placeholder 영구 제외 = `kind='attribute', payload={subject_artifact_id, key='do_not_sync_google', value='true'}` 별도 artifact (`classify_person` 패턴 일관, person payload mutation 회피, append-only audit 자동). `list_google_pending` SQL 이 NOT EXISTS 두 종 (citation google_contact + skip attribute) 강제. **D-cortex-9 안전 fix 동반**: 같은 SQL 에 `AND a.visibility='shared'` 추가 — private person 절대 push 후보 안 됨 (배포 전 누락이었음 → 같이 패치). **MAX_BATCH_SIZE = 500** sanity cap. **라우트**: `POST /cortex/google/push/start` (form ids[]) · `GET /cortex/google/push/status/<job_id>` HTML · `GET /cortex/google/push/json/<job_id>` JSON · `POST /cortex/a/<id>/skip-google-push` 마킹 신규/idempotent. **검증** (fake UUIDs 2 개 + concurrency + completion + 락 재획득 모두 OK, Google API 호출 0 회 — NotFound 가 token refresh 이전 단락). skip 후 pending 215→214, DB 에 attribute 1 row 확인. | 2026-05-29 |
| **D-cortex-design-axe-ui** | **cortex 웹 UI 도 axelabs design tokens 그대로 채택 — docs.axelabs.ai 와 같은 시각언어** | D-cortex-6.1 의 inline CSS (`STYLE` const ~200 line) 폐기 → axelabs SSOT (`/Users/axe/axelabs/src/lib/{tokens,styles}/`) 를 가져다 씀. **Sync 메커니즘** — `scripts/sync-axe-ui.sh` (docs.axelabs.ai 의 `scripts/sync-axe-ui.mjs` 패턴 미러). 호스트 빌드 시 axelabs 소스를 읽어 `static/axe-ui/bundle.css` (83 KB) 와 `static/axe-ui/fonts/SarasaFixedK-Regular.woff2` (533 KB) 갱신. **Bundle 구성** = tokens 4 종 (colors / spacing / typography / fonts) + styles 6 종 (reset / components base / form / data-display / dashboard / feedback). components.css 의 `@import` 중 cortex 가 안 쓰는 그룹 (overlays, agent, menus, mobile, layout, indicators, chat-ext, data-views, composites) 은 sync 시 strip. fonts.css 의 `/fonts/SarasaFixedK-Regular.woff2` 절대경로는 cortex 가 자기 static 으로 서빙하도록 `/cortex/static/fonts/...` 로 rewrite. **Binary stamp** — `include_str!`/`include_bytes!` 로 cortex binary 안에 박아 Docker stage 가 axelabs 디렉토리를 못 봐도 빌드 가능 (Dockerfile 도 `COPY static ./static` 한 줄 추가). 라우트 = `GET /cortex/static/axe-ui.css` + `GET /cortex/static/fonts/SarasaFixedK-Regular.woff2` (public, 세션 불요, Cache-Control 1일/30일). **HTML 적용** — `<html data-theme="light">` 로 라이트 모드 anchor + `<link rel="stylesheet" href="/cortex/static/axe-ui.css">`. 컴포넌트 클래스 매핑: `.topbar` → `.axe-topnav`, `.brand` → `.axe-logo`, `.card` → `.axe-card`, `.btn` → `.axe-btn .axe-btn--{primary,secondary,ghost}`, `.metric` → `.axe-metric-card`, `<table>` → `.axe-data-table > __scroll > __table > __th/__td`, `.empty` → `.axe-empty-state`, callout box → `.axe-callout--{info,danger}`, checkbox → `.axe-checkbox`. **Cortex-only 개념** (visibility tag, payload pre, kv list, filter bar, simple pager, flash, login wrap) 은 `.cortex-` prefix 로 분리 inline. **검증**: axe-ui.css 200 (85100 bytes, text/css) · font 200 (533932 bytes, font/woff2) · /cortex/home 200 + data-theme="light" + link stylesheet + .axe-topnav/.axe-metric-card/.cortex-metric-grid 모두 렌더 · /cortex/google/pending 200 + .axe-data-table/.axe-checkbox/.axe-btn--primary 렌더 · 엣지 https://axe.axelabs.ai/cortex/static/axe-ui.css 200. | 2026-05-29 |
| **D-cortex-backfill-orgs** | **person.payload.org inline string → organization artifact + employed_by relationship 일괄 승급 (CLI 2단계)** | 운영자 관찰 (2026-05-29): /cortex/orgs 페이지가 비어있음. person 3,597 개 모두에 회사가 payload.org 안에 inline string 으로만 있고 distinct 약 1,536 개. **자동 normalization 의 함정** — "노루" vs "노루홀딩스" vs "(주)노루홀딩스" 같은 변형을 LLM/trigram 만으로 합치면 잘못 합치는 사고. 따라서 **2단계 워크플로**: Phase 1 = `cortex backfill-orgs --owner <email>` (`src/backfill.rs`) → pg_trgm 활성화 + distinct org 추출 + similarity ≥ 0.6 클러스터 제안 YAML stdout (canonical_name + aliases + 빈도). 운영자 파일 저장 → 편집 (잘못 클러스터된 항목 분리, 합칠 항목 합치고, placeholder/미상은 `skip: true` 추가). Phase 2 = `--mapping <yaml>` 로 dry-run 통계, Phase 3 = `--apply` 실제 INSERT. **Idempotent** — (owner_id, payload->>'name') 으로 org 중복 안 만듦, (edge_kind='employed_by', from_artifact_id, to_artifact_id) 로 relationship 중복 안 만듦, 재실행 무해. **artifact 형식** — `kind='organization', payload={name, aliases:[...], backfill_source:'backfill_orgs_v1'}, visibility='shared'`; `kind='relationship', payload={from_artifact_id, to_artifact_id, edge_kind:'employed_by', source_org_string:<원본>, backfill_source:'backfill_orgs_v1'}, visibility='shared'`. **D-cortex-6.1 read-only 원칙 유지** — 등록 mutation 은 MCP-only 이고 backfill 은 CLI 일회성 도구 (운영자 명시적 의도 분명, 웹 form 추가 안 함). 회사명·employed_by 사실은 민감 아님 → shared 고정. **검증**: 1,536 distinct strings · 1,446 suggested clusters · YAML 5,000+ 줄 stdout 정상 · 소규모 2-org mapping 으로 Phase 2 dry-run + Phase 3 apply + 재apply (existing=2 idempotent) 모두 통과 · /cortex/orgs 페이지 가 빈 axe-empty-state 에서 데이터 있는 axe-data-table 로 전환됨 확인. | 2026-05-29 |
| **D-cortex-google-names-backfill** | **`cortex backfill-google-names` 일회성 CLI — Google contact 측 빈 displayName 정정 (134건)** | unstructured_name fix ship (commit 1326123, cutoff 2026-05-29T06:48:07Z) 이전에 register_person → createContact 로 Google 에 push 된 contact 들의 Google-side displayName 이 NULL 상태. People API 의 Name.displayName 은 server-computed — 옛 코드가 보낸 클라이언트 displayName 무시되고 given/family 도 null 이라 빈 displayName 으로 저장됨. **Candidate filter**: kind=google_contact, ref.source=register_person, artifact.visibility=shared, last_pushed_at 이 cutoff 이전 (또는 NULL + citation.created_at 이 cutoff 이전), citation.ref 의 unstructured_name_backfill 이 v1 아님 (idempotency gate). **per-person flow**: Cortex payload 의 display_name/given_name/family_name 추출 → People API updateContact PATCH (unstructuredName 동봉) → 응답 etag 추출 → RLS tx 안에서 citation.ref 갱신 (last_pushed_at + unstructured_name_backfill v1 마킹 + etag + backfill_source) + INSERT artifact_event 'dispatch' (actor=system:backfill-google-names). **Rate limit**: 1 req/sec (Google quota 90/min/user 안전 여유). **Error 분기**: 4xx etag mismatch 면 fresh getContact 후 1회 retry · 5xx 면 exponential backoff 1s/3s/9s 3회 · 429 면 60s 대기 후 1회 · 그 외 4xx 면 log + skip. **D-cortex-3 정합**: 식별 키만 push, enrichment 키는 절대 push 안 함. **D-cortex-4**: 운영자 명시 --apply 실행만. **D-cortex-9**: visibility=shared 만 candidate, private 자동 제외. **검증**: dry-run candidate=134 (Bucket A=2 김승우/정성화, Bucket B=132). canary 5/5 → full 129/129 success (총 134, 약 2.5분, 1 req/sec). 사후 candidate=0, dispatch event 134개, 김승우/정성화 citation 마킹 v1. 전제 — restore-from-audit 가 Cortex 측 display_name 을 먼저 채워둬야 함. | 2026-05-29 |
| **D-cortex-restore-from-audit** | **append-only audit 기반 enrichment 복원 CLI — `cortex restore-from-audit --owner &lt;email&gt; [--artifact-id &lt;uuid&gt; \| --scan] [--apply]`** | D-cortex-3 sync overwrite 같은 destructive event 후 audit log 기반 enrichment 복원. **알고리즘 — per-key 최신 meaningful 값 picking**: 단일 operator payload_after 만 보면 (예: 김승우 14:41 operator edit 가 이미 깨진 state 위에 former_org 만 추가 + display_name=null) 복원 실패. 키별로 ASC 훑어 마지막 meaningful (non-null + non-empty) 값을 채택. **소스 필터**: `op IN ('propose','edit')` (dispatch/archive/restore op 는 enrichment intent 아님) + actor NOT IN system actors. xlsx-migration 은 enrichment source 로 인정 (operator 가 다른 채널로 못 만진 경우 backup). **대상 키**: Cortex enrichment 키 (비-`GOOGLE_CANONICAL_KEYS`) 만 복원 + display_name 은 canonical 이지만 sync bug 손실 패턴 흔해서 예외 처리. **idempotent**: 이미 복원된 (current payload 가 meaningful) 케이스는 skip 보고. **검증**: D-cortex-3 hotfix 직후 일회성 Python script (177 복구) + 동일 알고리즘 CLI v2 가 14건 추가 발견·복구 (single-payload 정책 미스). 미래 비슷한 사고에 재사용. | 2026-05-29 |
| **D-cortex-mcp-write-tools** | **MCP write tool 표면 완성 — register_organization/deal/relationship + update_contact + archive_artifact + list_organizations/get_organization/list_deals/get_deal/list_relationships (10종 추가, 총 22 tool, register_deal 재설계 — name + contact_person_ids 자동 deal_contact relationship + visibility default private + source_attribute_id, archive_artifact 에 reason/restore alias 추가)** | 운영자 관찰 (2026-05-29 PM3): claude.ai 가 organization/deal/relationship 을 일상 등록할 수 있는 채널이 부재. 그리고 PM4 에 발견된 D-cortex-3 destructive overwrite 버그 fix 과정에서 Cortex → Google 으로 식별 필드 push 도구 (update_contact) 필요성 드러남. 현재 organization 채움 경로는 `cortex backfill-orgs` CLI 하나뿐. 일상 운영 (예: claude.ai 안에서 "이번 미팅에서 A 회사 알게 됐다 → register_organization") 흐름이 시작되도록 register_person 패턴을 4 kind 으로 확장. **register_organization** = (owner, payload->>'name') idempotent (같은 이름이면 existing id 반환, payload 갱신 X), visibility default 'shared', payload 가 additionalProperties: true. **register_deal** = NOT idempotent (같은 title 의 deal 가 round 별로 나옴), target_org_id 가 있으면 owner-scope + kind='organization' 검증, payload 자유. **register_relationship** = (owner, edge_kind, from_artifact_id, to_artifact_id) idempotent, from/to 양쪽 owner-scope 존재 검증, self-loop 차단 (from==to → InvalidArg). **archive_artifact** = `payload.archived=true` + `payload.archived_at=ts` UPDATE + append-only event `op='archive'`. **혁신** — 별도 archive_person/archive_organization/... 안 만들고 한 일반 도구로 통일. `archive=false` 로 restore (역방향, op='restore'). 멱등 — 같은 상태로 호출하면 no_op. visibility tier 와 직교 (안 건드림). **DELETE 차단 우회의 핵심**: artifact_event append-only trigger 가 DELETE/UPDATE 차단 → artifact 자체는 DELETE 가능하지만 CASCADE 로 events 같이 손실. archive flag 로 lifecycle 표현하면 audit 보존 + list/count/push 자동 제외. **List 쿼리 일괄 갱신**: web (fetch_kind_counts/recent_events/artifacts_by_kind/pending_push), MCP (list_persons/search_person via push_person_filters), backfill (distinct_orgs/person_rows) 모두 `NOT COALESCE((payload->>'archived')::boolean, false)` default 필터. get_person(id) 등 ID 직접 접근은 archived 도 반환 (복원 흐름 + audit 보존). **검증** (11/11 통과): (1) register_organization 신규 (2) 재호출 idempotent 같은 id+existing (3) register_relationship 신규 (4) 재호출 idempotent (5) register_deal 신규 (6) 동일 title 재호출 새 id (7) target_org_id 가 person uuid → kind mismatch error (8) archive 4개 (org/2 deal/rel) (9) 재 archive no_op (10) archive=false restore (11) 이전 세션 SMOKE_TEST_ORG_DELETE_ME_BACKFILL 정리. UI 검증: /cortex/orgs 가 archived 항목 안 보임, home dashboard 카운트 archived 제외 정합. | 2026-05-29 |
| **D-cortex-7** | **Rust + axum + sqlx (D-matrix-1 후속 precedent)** | 기존 8개 프로젝트는 Python/TypeScript 인데 Cortex 만 Rust 인 이유: (a) artifact 의 typed discriminated union 과 Rust 의 algebraic type 자연스러움, (b) sqlx 의 compile-time SQL check 가 schema/RLS query 안전성 보강, (c) MCP HTTP 서버 = long-running 단일 process 이므로 Rust 의 panic-free + 낮은 메모리 ergonomics 적합, (d) 단일 binary 배포. Day 1 부터 Rust. matrix (D-matrix-1) 가 첫 Rust precedent, cortex 가 두번째. |
| **D-cortex-8** | **claude.ai connector OAuth = Microsoft 직접 federation (self-hosted AS proxy 아님)** | RFC 9728 의 `authorization_servers` 를 **Microsoft** (`login.microsoftonline.com/<tenant>/v2.0`) 로 둠 → claude.ai 가 Microsoft 의 OIDC metadata fetch → Microsoft `/authorize`·`/token` 사용. cortex 는 RS256 access_token (aud = Application ID URI `https://axe.axelabs.ai/cortex/mcp`) 만 검증 (auth.rs RS256 path). frame 의 "직접-Microsoft 현재 live" path 와 동일. claude.ai connector 의 Advanced field 에 client_id (`60d04ea8-...`) + client_secret 입력 필수 (confidential client). **탐색 후 폐기**: cortex 자체 AS proxy (`/cortex/oauth/{authorize,callback,token,register}` + RFC 8414 metadata + `oauth_authorization_codes` 테이블 + auth.rs HS256 path, src/oauth_as.rs ~620 line) 를 구현했으나 불필요로 판명 → frame oauth.py 와 동일하게 **dormant 보존** (claude.ai client 개선 시 재활성 가능). 사유: `authorization_servers` 를 cortex (path 있는 issuer `https://axe.axelabs.ai/cortex`) 로 두면 RFC 8414 §3.1 의 path-insertion (metadata 위치 = `https://axe.axelabs.ai/.well-known/oauth-authorization-server/cortex`) 때문에 claude.ai 가 cortex sub-path 의 RFC 8414 metadata 를 못 찾음 → origin 의 `/authorize` fallback → blueprint 404. |
| **D-cortex-person-tier** | **person 을 tier (pool\|network) 로 2분 — 자동 sync 연락처(pool) vs 운영자 인맥(network), auto-promote 자동화** | 운영자 관찰 (2026-05-29 PM9): Google Contacts 3,601 person 중 대부분이 일회성/업무 raw 연락처라 "내 인맥" 뷰를 오염. **개념**: pool = Google sync 가 자동으로 가져온 raw 연락처 (의미 부여 X, 손실 없이 보존), network = 운영자가 의도적으로 추가/관리하는 인맥. backfill (tier_backfill_v1): network 625 / pool 2,976. **기본값**: (a) Google sync 신규 person = pool (sync.rs INSERT 시 자동; 기존 person 의 tier 는 enrichment 키 → overlay 가 GOOGLE_CANONICAL_KEYS 화이트리스트 밖이라 절대 안 건드림). (b) register_person (운영자 명시) = network default (claude.ai 에서 의도적 등록 = 이미 인맥); tier='pool' 명시 허용 (행사 명함 일괄 후 추후 분류). (c) import-xlsx (Network_CRM.xlsx = 운영자 큐레이션 인맥) = network — create-missing 신규는 생성 시 tier='network', matched (Google-synced pool) person 도 xlsx 등장 = 인맥이라 system:xlsx-migration 이 network 로 승급 (멱등). **auto-promote (pool→network, 멱등)**: classify_person(attribute 부착) / register_relationship(person endpoint, edge_kind 무관) / log_interaction(participant) 중 어느 액션이든 발생하면 대상 person 자동 승급 — payload.tier='network' + tier_source='auto_promoted_from_&lt;action&gt;' + tier_promoted_at, audit op='edit' actor='system:auto-promote'. 한 helper (auto_promote_to_network) 가 3 handler 의 tx 안에서 호출. **network→pool 강등 없음** — 한 번 인맥은 영원히 인맥. 유일한 역방향 = 운영자 명시 demote_to_pool(person_id, reason) MCP tool (archive_artifact 패턴 미러, payload.tier='pool' + tier_demoted_at + tier_demote_reason, audit actor=operator, 멱등). **노출**: list_persons MCP tool 기본 tier='network' (claude.ai 1차 뷰 = 인맥), web /cortex/people 기본 tier='network' + ?tier=pool\|all 확장 필터 바, home 대시보드 People 카드 = 내 인맥(network) 값 + 풀/전체 sublabel. **D-cortex-3 정합**: tier 는 enrichment 키 → sync 가 절대 안 건드림. 회귀 차단: sync.rs 의 overlay_never_touches_tier_enrichment_key unit test (6 tests). **MCP tool 수**: 22 → 23 (demote_to_pool). | 2026-05-29 PM9 |
| **D-cortex-org-stats** | **home 대시보드 전사(cross-user) 집계 — D-cortex-2 per-user 격리를 처음 의도적으로 여는 표면 (익명 합계 한정)** | 운영자 요청 (2026-05-29 PM10): "대시보드에 조직 전체 통계도". 범위 확정 — **전사 집계(cross-user)** + **전 직원 visible** + **전사 합계만 (직원 익명, per-employee breakdown 없음)**. **구현**: `fetch_org_wide_counts(state)` 가 `set_current_user` 를 호출하지 않아 cortex superuser 연결(rolbypassrls)로 RLS(owner_only) 를 우회 → 모든 owner 의 artifact 를 kind 별 COUNT + distinct owner(사용자) 수만 집계 (sync.rs 의 cross-row 패턴과 동일; per-user 경로는 여전히 SET LOCAL ROLE cortex_app + cortex.actor 로 격리). **격리 보존 핵심**: 개별 레코드도 owner 별 분해도 반환 안 함 — 오직 익명 총합 숫자만 RLS 섬 밖으로 나감 (D-cortex-2 의 "타인 레코드 비가시" 유지, 집계 숫자만 공유). archived 제외. home 에 "조직 전체 (전사 집계 · 사용자 N명)" 섹션 + 익명 안내 callout + `org_metric` (non-link — 전사 합계는 per-user 리스트로 안 매핑되므로 클릭 misleading 방지). **검증**: 집계 person 3600 / relationship 3071 / org 1500 / deal 17 / interaction 1 / users 1. (smoke 잔여 archive 후 정확.) **확장 시 주의**: 직원별 breakdown(attribution, created_by/owner_id 기반)을 추가하려면 개인 인맥 규모가 직원 간 노출 → 별도 운영자 결정 필요. created_by(artifact) + actor(artifact_event append-only) 는 이미 누가 등록·수정했는지 전부 기록 중이라 attribution 데이터는 준비됨. | 2026-05-29 PM10 |
| **D-cortex-customer** | **person/organization 고객 태깅 — 다대다 (1 subject ↔ 여러 case) 수동 태깅** | 운영자 결정 (2026-05-29 PM11): "고객인지 아닌지·어떤 건 고객인지 별도 DB화 — 불편해도 우선 수동, 단 1명이 여러 건(프로젝트 a/b/c)으로 고객 가능". **모델**: 고객 = subject 에 붙은 ≥1개의 `customer_case` attribute (kind='attribute', key='customer_case', value=case 라벨). 한 subject 가 여러 case 로 고객이면 case 마다 별도 attribute → 다대다. 별도 kind/table 안 만들고 attribute 전용 key 재사용 ("별도 DB화" 를 dedicated key 로 충족, 기존 archived/visibility/audit 인프라 그대로). **MCP tool 2종**: tag_customer(subject_id, case, note?, visibility=shared) — (subject, case) 멱등, person 이면 tier network 자동 승급 (고객=인맥); untag_customer(subject_id, case) — 해당 case attribute archive (멱등, tier 강등 X, 다른 case 유지). visibility default shared (전사 고객 카운트 근거). **대시보드**: "고객 N명 / N개 회사" = customer_case 있는 distinct person / organization. MCP tool 수 23 → 25. **확장 여지**: case 를 자유 텍스트 대신 deal/project artifact 로 승급하면 자동 파생 가능 (현재는 수동 우선). **2026-05-29 후속 — customer→account 리네임 + type 차원**: 운영자 "customer 는 일차원적" → 개념을 **account (거래 계정)** 로 리네임 (tag_customer→tag_account, untag_customer→untag_account, key customer_case→account_case, 대시보드 라벨 'Account'). 동시에 **type 차원** 추가 (account_case payload 의 optional `type`, free-form 권장 vocab investor/client/advisor/partner/lp/vendor/portfolio/acquirer/other) — **1 account 가 case 별로 여러 type 가능** (예: investor + client). tag_account 에 type 파라미터 (같은 case 재태깅 시 type 만 UPDATE, 중복 X). 마이그레이션: 기존 58행 account_case 로 리네임 (audit actor='system:account-rename'), 활성 57 AXEC 행 type='investor'. 대시보드 sublabel 에 type별 distinct subject (상위 3). | 2026-05-29 PM11 + 2026-05-29 (account 리네임 + type) |
| **D-cortex-dashboard-redesign** | **home 을 사람 중심 2-row (전사 / 나의) 로 재편 — relationship·kind 카드 제거** | 운영자 피드백 (2026-05-29 PM11): "relationship 은 사람에게 크게 중요한 정보 아닌 것 같다". 기존 home = kind 카드 그리드(people/orgs/deals/interactions/relationships) → 그래프 내부 엣지(relationship) 카운트는 사용자에게 noise. **새 레이아웃 순서**: 구글 연동 → 구글 Push 대기 → 전사 row → 안심 주석 → 나의 row. **각 row 4 지표**: 전체 인원 N명 · 네트워크 N명/N개 회사 · 고객 N명/N개 회사 · 1개월 내 활동 N건/총 N건. 회사 = network person 들이 employed_by 로 연결된 distinct organization. **안심 주석** (전사 row 아래): "네트워크가 아닌 인원은 정보가 조직 내 공유되지 않습니다. 안심하세요." (전사 '총' 은 pool 포함하지만 익명 합계라 개별 pool 인원 정보는 비공유 — 운영자 결정 'pool 포함 총'). **구현**: NetworkStats 한 구조 + NETWORK_STATS_SQL 한 쿼리를 per-user(set_current_user RLS) 와 전사(superuser bypass) 양쪽 재사용. stat_row/stat_cell (non-link — 집계는 per-user 리스트로 안 매핑). 30일 윈도우 created_at 기준 (occurred_at cast 실패 회피). **검증** (나의 row): 총 3600 / 네트워크 624 / 네트워크회사 413 / 고객 0(태그전) / 활동 1·총 1. | 2026-05-29 PM11 |
| **D-cortex-leader-election** | **blue/green run_loop 중 한 쪽만 sync 실행 — `pg_try_advisory_xact_lock` 으로 race 본질 차단 (D-cortex-3 PM7 follow-up)** | D-cortex-3 PM7 가 blue/green binary 불일치 race 였는데 fix 가 "둘 다 --no-cache 재빌드 + binary sha 일치 검증" 운영 invariant 였음. 본질적 root cause = **blue/green 둘 다 run_loop 를 돈다는 것 자체**. binary 동일성은 race 가 일어나도 같은 결정을 내리는 우회. **본질 = race 자체 차단** → leader election. **구현**: `src/google/sync.rs::run_cycle` 시작 시 `state.pool.begin().await` 로 transaction 열고 `pg_try_advisory_xact_lock(SYNC_LEADER_LOCK_KEY)` (i64 const = 2026052907 = PM7 incident 날짜) 시도. 성공 시 leader → `run_cycle_inner` 실행 → `tx.commit()` 시 advisory_xact_lock auto-release. 실패 시 INFO 로그 (`sync cycle: leader lock held by other instance, skipping`) 후 즉시 return. **Transaction-scoped lock 선택 이유**: session lock 은 sqlx pool 의 connection 재사용으로 release 대상 backend 가 모호. xact lock 은 COMMIT/ROLLBACK/disconnect 모두에서 auto-release → leader 인스턴스가 panic·crash·OOM 으로 죽어도 PG backend session 종료 시 lock 즉시 해제, 다음 cycle 에 다른 인스턴스가 leader. 무인 페일오버, lock 영구 stuck 위험 없음. **부수효과**: Google API quota 절반 (이전 2× 호출 → 1×), DB 부하 절반. **Race 차단 일반화**: PM7 같은 binary 불일치 뿐 아니라 코드 수정 race / 동시 sync 가 같은 person 을 두 번 처리하는 모든 race 가 leader 한 명 보장으로 자동 차단. **Ship hook 자동화 (Dockerfile 통합)**: `cargo build --release && cargo test --release --bin cortex google::sync::tests` 가 Dockerfile RUN 한 단계 — test 실패 시 image 생성 자체 불가 → 옛 destructive 코드가 production 으로 흘러갈 수 없음. 매 `docker compose build` 자동 검증. **운영 함정 갱신** (CLAUDE.md): blue/green 동일 binary 가 강제→권장 으로 격하 (leader election 도입 후엔 binary 가 달라도 한 쪽만 실행). 새 함정 = "skip 로그가 한 쪽에서 항상 안 보이면 그 쪽이 leader 가 못 됨 (DB pool 문제)". **검증**: (1) psql 두 세션 동시 시도 → 한 쪽만 `t`, 다른 쪽 `f` 받음 (mutual exclusion). 첫 세션 commit 후 두번째 시도 → `t` (auto-release). (2) Docker rebuild --no-cache both + recreate → 같은 binary sha 확인 + 첫 sync cycle 후 blue/green 중 한 쪽만 "owner sync ok", 다른 쪽 "leader lock held, skipping". (3) `cargo test` 5/5 통과 (회귀 차단). | 2026-05-29 PM8 |
| **D-cortex-9** | **artifact visibility tier (`shared`\|`private`) — owner 의 RLS 섬 밖으로 무엇이 나가는가를 통제하는 propagation gate** | soohun.kang 2026-05-28 "Private Partition" 요청. **핵심 재구성**: 현재 모든 artifact 는 이미 RLS (`owner_only`: `owner_id=current_setting('cortex.actor')`, 앱 role `NOSUPERUSER NOBYPASSRLS`) 로 owner 본인에게만 보임 — *타인·관리자·감사자가 볼 수 있는 경로 자체가 없음*. 따라서 `private` 플래그는 본인 vs 타인 격리가 아니라 **데이터가 owner RLS 섬을 벗어나는 미래 표면을 막는 게이트**. 그 표면 = **Blueprint M6 artifact mirror** ([D-bp-artifact-1](/ops/decisions), [/architecture/artifacts](/architecture/artifacts)): Blueprint `Artifact` 테이블은 `workspace_id`+`entity_id` scope 이고 `owner_id`·`visibility` 컬럼이 없어, mirror 시 owner 격리가 풀림. M6 이 아직 📐 설계 (2026 Q4) 라 **mirror 가 생기기 전 지금이 visibility 를 박을 적기**. **계약**: 모든 outward propagation (Blueprint mirror / org export / dashboard) 은 `WHERE visibility='shared'` 강제, `private` 은 절대 RLS 섬을 안 떠남. owner 본인 세션은 shared+private 모두 봄. **기본값 정책**: `shared` (Google 동기화 base 연락처는 이미 Google 에 존재하는 저민감 canonical) — 단 민감 분류(HPE 등)·xlsx import 의 sensitive 컬럼·명시 flag 는 `private`. 신규 sensitive 데이터(HPE 138건)가 아직 미유입(`B-cortex-xlsx-import-run`)이라 backfill 불필요. **단계**: Phase 0 (지금) = `artifact.visibility` 컬럼 + `list_persons(visibility=, exclude_classification_key/value)` 필터 + write tool `visibility`/`skip_audit_payload` 파라미터 (§6 스톱갭). Phase 1 = Google contactGroup sync 화이트/블랙리스트 (유입 차단). Phase 2 (M6 착수 시) = Blueprint mirror 계약 + field-level privacy (payload `private` 하위객체 + 기존 `CORTEX_PII_PASSPHRASE` pgp 재사용) + private artifact 의 audit redact. Phase 3 (opt-in) = client-key sealed E2E (search·Google push 포기 trade-off). **visibility 결정 UX**: 기본 shared, write tool 4종 description 의 SENSITIVITY RULE 로 커넥터 LLM 이 민감 가능 내용에 한해 저장 전 'private/shared?' 확인 (MCP 는 요청-응답이라 직접 못 물음 → LLM-guidance). **공유 인물 + 비공개 메모** = person `shared` + 별도 `classify_person(visibility=private)` attribute (별개 artifact). `log_interaction` 도 visibility 보유 (private 미팅 → participant relationship 도 상속). | 2026-05-28 |
| **D-cortex-google-drift** | **Google sync 가 인맥(network)의 소속/직급을 다른 meaningful 값으로 덮을 때 drift 알림 기록 — overlay 와 독립한 additive notification 레이어** | Google sync 는 D-cortex-3 에 따라 canonical 필드를 자동 overlay (Google = canonical). 하지만 org/title 이 "한 의미있는 값 → 다른 의미있는 값" 으로 바뀌면 = 이직/승진 신호 → 운영자가 대시보드에서 검토하도록 drift 레코드 생성. **overlay 자체는 안 건드림** — drift 는 순수 additive. **판정 (overlay 와 별개)**: `is_meaningful_change(old,new)` = 공백 정규화 후 둘 다 non-empty 이고 서로 다름. null→value(채움)·value→null(지움)·whitespace-only 차이는 drift 아님. tier='network' 만 (pool = raw Google dump 의 잡음 변화 무시). org·title 두 필드 검사. **레코드**: `kind='attribute'`, key='google_drift', payload `{subject_artifact_id, field:'org'\|'title', old, new, detected_at, source_etag, acknowledged:false}`, visibility='shared', created_by='system:google-sync' + artifact_event op='propose'. **멱등**: 같은 (subject, field, new) 의 활성(archived=false, acknowledged=false) drift 가 있으면 skip. 모두 sync tx 안 (이미 RLS-scoped). **웹**: home 에 "🔔 변화 감지 (Google)" 카드 (미확인 N>0 시) → `/cortex/google/drift` 목록 (이름 link · 변화 "소속/직급: old → new" · 감지일 · [확인]) → `POST /cortex/a/:id/ack-drift` (payload.acknowledged=true + acknowledged_at + op='confirm' event, RLS-scoped). D-cortex-6.1 read-only 예외 (push/skip 처럼 운영자 lifecycle 액션). **백필 안 함**: 기존 audit 의 org/title 변경은 운영자 cleanup 이라 진짜 커리어 변화 아님 — going-forward 만. **회귀 차단**: sync.rs `#[cfg(test)] mod tests` 에 9 drift test 추가 (총 15) — Dockerfile `cargo test ... google::sync::tests` gate 가 강제. | 2026-05-29 |

**부수 효과**:
- `/Users/axe/cortex` 폴더 폐기 (`cortex.legacy.20260526/`), `cortex.axellc.com` 도메인 라우트 삭제 (cloudflared `~/.cloudflared/config.yml` 정리, mysrt.axellc.com 만 보존)
- 32xx 포트 재할당: 3200 postgres / 3210 mcp-blue / 3211 mcp-green / 3212 proxy (frame 3700/3710/3711/3712 패턴)
- `customers.yaml`: `sso.apps.cortex_mcp` (appId=`60d04ea8-5d7b-453e-a4c0-af421b4689f5`, az cli 등록 2026-05-26) + `services.cortex` (5 secrets: DB_PASSWORD, PII_PASSPHRASE_AXEC, JWT_SECRET, AZURE_CORTEX_MCP_CLIENT_SECRET, GOOGLE_OAUTH_CLIENT_SECRET)
- Entra app: frame_mcp / hive_mcp / blueprint_mcp 와 동형 (signInAudience=AzureADMyOrg, requestedAccessTokenVersion=2, identifierUris=`https://axe.axelabs.ai/cortex/mcp`, scope `mcp.access`, webRedirectUris=claude.ai+claude.com `/api/mcp/auth_callback`)
- Postgres 5 테이블 (artifact / citation / artifact_event / mcp_schema / google_oauth_token), GIN+btree+partial index, append-only trigger, 4 RLS policy (owner_only USING+WITH CHECK)
- 10 MCP tools — auth middleware (Entra ID JWKS 1h TTL cache + RS256 + audience-issuer-exp 검증) 통과 후 `Extension<AuthContext>` 로 owner_id 사용
- Google OAuth Web flow + People API client + per-user sync loop (600s 간격, `system:google-sync` actor 로 artifact_event 기록)

**운영자 작업 — 2026-05-28 production live 완료**:
1. ✅ 5 secret vault push (`cortex/axe/{db-password, pii-passphrase-axec, jwt-secret, oauth-client-secret, google-oauth-client-secret}`) — 모두 stdin pipe (jq -Rsc) 로 shell history·context 미경유
2. ✅ Google OAuth Web client — 신규 GCP 프로젝트 `Cortex` (id `cortex-497605`, 옛 `Gemini`/Network Manager 폐기 예정). People API enable + consent screen External/Testing + client (`135512942819-...apps.googleusercontent.com`)
3. ✅ Cloudflare ingress — `axelabs` 터널은 Cloudflare **Dashboard remote-managed** (로컬 config.yml 무시 — `Updated to new configuration version=N` 이 증거). `axe` 의 기존 CF API token (vault `Cloudflare API - axelabs`) 으로 `PUT /accounts/.../cfd_tunnel/.../configurations` 하여 `axe.axelabs.ai` path=`cortex(/.*)?` → `host.docker.internal:3212` 추가
4. ✅ `docker compose up -d --build` (postgres 3200 + mcp-blue 3210 + mcp-green 3211 + proxy 3212). `cortex migrate` (2 migration: artifact schema + oauth_authorization_codes)
5. ✅ claude.ai connector 등록 (URL + client_id + client_secret) → Microsoft OAuth → 12 tools 노출 + whoami 검증
6. ✅ connect_google → 브라우저 consent (kangsoohun@gmail.com, Test users 등록 필요) → "✓ Google 연결 완료"
7. 🔧 (잔여) `cortex import-xlsx` 660 행 enrichment 1회 마이그 + `axe mcp publish` catalog 등재 — [B-cortex-xlsx-import-run](/ops/backlog), [B-cortex-mcp-catalog-publish](/ops/backlog)

**시행착오 (전부 [known-gaps](/ops/known-gaps) 등재)**: DB password 의 base64 `/` 가 URL port 파싱 깨뜨림 (PgConnectOptions builder 로 회피) · docker compose env_file 가 따옴표 literal (axe secret pull quote 가 postgres auth 깨뜨림) · resource-level RFC 9728 path 누락 · RFC 8414 path-insertion · MCP tool property key 한글 (`메모`) 이 tools/list 전체 거부 · Cloudflare remote-managed tunnel · Docker image 가 옛 코드라 cargo build 만으론 부족 (`--build` 필수).

상세: [services/cortex](/services/cortex), [/Users/axe/cortex/docs/operator-setup.md](https://github.com/soohunkang/cortex/blob/main/docs/operator-setup.md), [/Users/axe/cortex/CLAUDE.md](https://github.com/soohunkang/cortex/blob/main/CLAUDE.md).

### D-vault-mcp-catalog — MCP Connectors catalog view (Vaultwarden org collection)

axelabs 자체 운영 MCP (frame, hive, blueprint, ...) 의 OAuth 등록 정보 4 조각 (이름, MCP URL, client_id, client_secret) 을 사용자가 `claude.ai/customize/connectors` 등 MCP host 에 등록할 때마다 4 곳에서 찾는 비효율 해소. **catalog view** = Vaultwarden 의 `MCP Connectors` organization collection (org-wide read access). 사용자는 Bitwarden 브라우저 확장만 열면 URI 매칭으로 자동 suggest.

| 항목 | 결정 |
|---|---|
| **SoT 불변** | `/Users/axe/.axe/customers.yaml customers.<cust>.sso.apps.*_mcp` (client_id, application_id_uri, scopes) + Vaultwarden item `<svc>/<cust>/oauth-client-secret` (또는 `blueprint/<cust>/mcp-client-secret`) for secret. **데이터 중복 0** |
| **catalog 위치** | AXE Vaultwarden org `0c5d8bbd-ad85-42b4-8b8a-2849031981b1` 의 `MCP Connectors` collection ID `1a62e754-6e47-43e0-a99a-cf71c37b8638`. 4명 org 멤버 모두 access (ai@/soohun@ = manage, taehun@/jinwoo@ = read-only) |
| **item shape** | Login item per `*_mcp` app. title = `"{Svc} MCP ({cust})"`, username = client_id, password = client_secret, custom fields = MCP URL / Tenant ID / Scopes / Vault path, URIs = `claude.ai/customize/connectors` + `claude.com/customize/connectors` + MCP endpoint (모두 "Starts with" match → 브라우저 확장 자동 suggest) |
| **publisher** | `axe mcp publish [--customer axe]` — `/Users/axe/.axe/bin/axe` 의 `cmd_mcp_publish`. 매니페스트 순회 + vault fetch + bw create/edit upsert. idempotent. `axe mcp list` 는 read-only 미리보기 (vault 미접근) |
| **hook** | `axe secret rotate <ENV> --service <svc>` 가 MCP `client_secret` 회전 시 `axe mcp publish` 자동 호출 → catalog 의 password 도 즉시 갱신. 사용자가 옛 secret 으로 claude.ai 에 등록하다 OAuth 거부 받는 함정 사전 차단 |
| **신규 MCP 추가 시** | (1) Entra app 등록 + customers.yaml 의 `sso.apps.<svc>_mcp` 4-key (client_id, application_id_uri, scopes, client_secret_env) 추가 + services manifest 의 secret entry 등재 → (2) `axe secret push` → (3) `axe mcp publish`. 3 단계 표준 |
| **realchoice (sovereignty 격리)** | customer 측 vault 에 customer 자체 `MCP Connectors` collection. operator 의 catalog 에 customer secret 비포함. [B-customer-sovereignty-architecture](/ops/backlog) Q3 milestone |

**함정 (도입 직후 발견)**: `customers.yaml customers.axe.sso.apps.frame_mcp.client_secret_env` 가 5/21 hive_mcp 등재 후에도 D-ops-15.5 의 "proxy path only" 주석 형태로 stale 처리되어 있었음 (실제 vault item 존재 + claude.ai 가 confidential client 요구). 본 D 도입 시 정정 — frame_mcp 도 secret 포함하여 catalog publish. 같은 함정 = 미래 새 MCP 추가 시 `client_secret_env` 누락 시 catalog item 이 (public) 으로 잘못 publish 됨. `axe mcp list` 출력의 "vault item" 칸이 `(public)` 이면 점검 신호.

### D-ops-42 — 배포 SSOT 아키텍처 (origin/main SHA = 배포 진실원천)

다중 동시 Claude Code 세션이 repo 당 1 working tree + 1 `main` 을 공유하던 구조가 만든 배포 엉킴을 근본 해소. **원칙 한 줄**: `origin/main 의 commit SHA = 배포의 SSOT`. working tree·로컬 main·실행 중 컨테이너는 전부 그 SHA 의 파생·일회용 투영. AXE 가 docs·backlog(matrix-postgres, [D-matrix-3](/ops/decisions))에 이미 적용 중인 SSOT 규율을 **배포**로 확장한 것. 전체 본문 = [/ops/runbook/deploy-ssot](/ops/runbook/deploy-ssot).

**동기 (실측 incident, 2026-06-04)**: 공유 tree + 공유 `main` 이 세 가지 고장을 동시에 발생:

| 고장 | 메커니즘 |
|---|---|
| push 거부 | 타 세션이 먼저 push → 로컬 `main` 이 origin 과 diverge → non-fast-forward → push blocked |
| WIP 혼재 | 서로 다른 feature 의 uncommitted 변경이 한 tree 에 누적 → 누구도 자기 slice 만 clean commit 불가 |
| dirty 누출 | `axe deploy` 가 dirty working tree 에서 이미지 빌드 → uncommitted 코드 prod 누출 + push 전 배포 가능 |

구체 사례: 이미 배포까지 끝난 blueprint fix (commit `b4067504`) 가 main diverge + 타 세션 WIP 로 수 시간 push 불가 → 운영자가 수동 reconcile (stash→rebase→push). 추가 발견 = 운영자 `axe` CLI (364KB) 자체가 **버전 미관리 + in-place 편집** = 같은 병의 가장 깊은 사례 (CLI 가 배포 도구인데 자기 자신은 SHA 추적 밖).

**컴포넌트 — 각자 제거하는 고장**:

| 컴포넌트 | 동작 | 제거하는 고장 |
|---|---|---|
| **A. 작업 격리** | `axe work <svc> <slug>` = 세션별 git worktree (`~/.worktrees/<svc>/<slug>`) off origin/main. 정규 repo 는 fast-forward 전용 "main mirror" 강등 (손편집 금지) | 공유 tree 경합 · WIP 혼재 · stash 더미 = **발생 불가능** |
| **B. SHA 에서만 빌드** | deploy 가 working tree 가 아니라 pushed SHA 의 clean checkout (`git worktree --detach`/archive) 에서 빌드. 이미지 태그 `<svc>:<sha>`. push 안 된 SHA 배포 거부 | deploy-before-push + dirty-tree 누출 = **구조적 불가능** |
| **C. Deploy lock** | 서비스당 배포 직렬화 (matrix-postgres `pg_advisory_lock` 우선, 파일락 fallback) | 두 세션이 같은 서비스 blue/green 동시 flip 불가 |
| **D. Provenance + drift** | 컨테이너 `org.axe.git_sha` 라벨. `axe health`/`axe host` 가 color 별 실행 SHA + origin/main 대비 drift 표시 | "지금 라이브가 git 과 일치하나" 에 항상 답 (silent drift 소멸) |
| **E. 잘못된 경로 제거** | `axe deploy` 가 tree 입력 폐기. `git push origin main` 직접 = pre-push 훅 + GitHub branch protection 으로 기계적 차단. `axe ship` 만 main 전진 | honor-system 의존 (현재 = 사회적 규약뿐) 제거 |
| **F. 통합 ship** | `axe ship` (worktree 에서): fetch → origin/main rebase → SHA build+test → push (main ff) → 그 SHA deploy (lock 하) → mirror ff → shiplog | 오늘 운영자가 손으로 한 reconcile 전 단계가 한 명령 |

**스테이지 상태기계** (blue/green 이 이미 3스테이지 제공):

```
built → canary(passive color, 트래픽 0) → [migration-validation 게이트] → live(active flip) → previous(직전 active = 즉시 롤백)
```

**migration-validation (안전 척추)**: 스키마 마이그레이션 포함 릴리스는 flip 전에 prod DB 의 ephemeral clone 에 마이그레이션을 적용·검증 (`axe drill`/backup 스냅샷 기계 재사용). 본질적 이유 = blue 와 green 이 **DB 를 공유**하므로 깨지는 스키마 변경은 blue/green 으로 카나리가 *불가능* (green 용 마이그레이션이 blue 도 즉시 오염). 이 게이트가 blue/green 이 못 막는 유일한 위험을 덮음. 대상 = blueprint 대기 migration 2개 (`add_user_entra_oid`, `add_entity_legal_name`), hive alembic.

**rollout (additive → canary → cutover)**: 전부 기존 동작과 공존 (additive) → `--dry-run` + passive-color 카나리 (flip 안 함) 검증 → cutover (기본값 flip + 가드 활성화, escape hatch 포함) 는 게이트됨 → 되돌림 가능. 진행 중 WIP 보존.

**채택 안 함**:

- **별도 staging 환경** (staging.axelabs.ai + 독립 DB/터널) — 단일 Mac mini 호스트에서 새 실패유형은 안 잡으면서 비용·parity 만 증가. canary + migration-validation 이 실위험을 이미 커버.
- **작업추적에 새 "스테이지" 축** — roadmap/backlog/updates 가 이미 작업 스테이지 파이프라인 ([D-matrix-3](/ops/decisions)). 배포 스테이지와 작업 스테이지를 혼동하지 않음.

**정합**: [D-ops-16](/ops/decisions) (docs drift = release-gate `axe ship`) 의 release-gate 를 배포 진실원천까지 확장 · [D-matrix-3](/ops/decisions) (matrix-postgres SSOT) 의 SSOT 규율을 배포로 확장 · [Blue/green deploy](/ops/runbook/deploy) 의 alias swap 메커니즘 재사용.

### D-ops-44 — Vault 비밀 주입 = SSH 환경 raw-bw keychain-free (`axe vault unlock` 금지)

이 머신은 AXE 의 Mac mini 이고 **Claude Code 세션은 SSH(loopback) 위에서** 돈다. 운영자는 Windows 에서 `ssh axe@100.127.210.30` (Tailscale) 로 들어온다. macOS 는 **SSH 세션이 GUI login keychain 에 쓰는 것을 거부**한다 ("User interaction is not allowed"). 그 결과 vault 비밀을 *넣는* 통상 경로 (keychain 세션 의존) 가 SSH 컨텍스트에서 전부 막힌다. 본 결정 = SSH 환경에서 비밀을 vault 에 넣는 **정답 경로를 keychain-free raw-bw 로 고정**하고, 이를 `/Users/axe/CLAUDE.md` 에 강제 규칙으로 박제한 것. 운영자-facing how-to = [/architecture/secrets#ssh-환경에서-vault-비밀-주입-keychain-free-raw-bw](/architecture/secrets).

**금지 (SSH 에서 전부 실패)**:

| 금지 | 이유 (SSH 에서 깨지는 메커니즘) |
|---|---|
| 운영자에게 `axe vault unlock` 시키기 | unlock 의 keychain-cache 단계가 SSH 세션에서 crash |
| `axe secret push/pull/check` 로 비밀 PUT | 내부 `_vault_env` 가 keychain 세션만 읽음 (`security find-generic-password -s axe.vault.session -a ai@axellc.com`) → SSH 에선 "vault session not found" |
| osascript `display dialog` | GUI 다이얼로그 = 원격/Windows 운영자에게 안 보임. 운영자-타이핑 비밀은 `read -rs` 로 받음 |

**정답 = keychain-free raw-bw** (운영자가 자기 인터랙티브 셸 — Windows `ssh axe@100.127.210.30` 또는 Mac 터미널 — 에서 직접 실행). 에이전트는 스크립트를 **ASCII-only · 주석 없음 · `bw unlock` 을 단독 한 줄**로 공급한다 (한 블록으로 붙여넣으면 unlock 프롬프트가 바로 다음 줄을 비밀번호로 삼켜버림). 단계:

1. `export NODE_EXTRA_CA_CERTS=/Users/axe/.axe/vault/certs/rootCA.pem` — Vaultwarden private CA, 필수.
2. **자기 단독 줄에서** `export BW_SESSION="$(bw unlock --raw)"` — master-pw 프롬프트. TTY-flaky 폴백: `read -rs PW; export BW_SESSION="$(BW_PASSWORD="$PW" bw unlock --passwordenv BW_PASSWORD --raw)"; unset PW`.
3. raw `bw create` / `bw edit` 로 Login item 생성·갱신 — **name** = `customers.yaml` 의 `services.<svc>.secrets[].vault` 경로 (예 `gate/axe/jwt-secret`), **username** = env var 이름, **password** = 스크립트 안에서 생성/읽은 값 (`$(openssl rand -hex 32)` / `$(cat key.pem)` / 상수 — echo·history·argv·agent-context 어디에도 안 남김) → `bw sync` → `unset BW_SESSION`.

**검증 (에이전트는 검증 불가)**: BW_SESSION 이 운영자 셸 안에만 살아 있으므로 에이전트는 결과를 직접 확인할 수 없다. 운영자의 `created/updated` + `synced` 출력이 곧 확인이다. `axe secret check` 호출 금지 (keychain 필요).

**keychain 세션이 필요한 곳 = deploy/ship 시점 한정**: `axe ship`/`axe secret pull` 은 그때 keychain 세션을 읽는다. SSH 에서 GUI 없이 그 세션을 채우는 법 = `read -rs KCPW; security unlock-keychain -p "$KCPW" ~/Library/Keychains/login.keychain-db; unset KCPW` (headless unlock) → `axe vault unlock` → `axe ship`. **비밀을 *넣는* 작업은 이 단계가 불요** — raw-bw 가 keychain 없이 vault 에 직접 쓴다.

**정합**: [D-ops-17](/ops/decisions) (vault = canonical SoT, manifest 매핑) · [D-ops-40](/ops/decisions) (osascript hidden-dialog 패턴 — GUI 세션 전제라 SSH 컨텍스트에선 본 raw-bw 가 대체). 더 깊은 잔여 격차 (=`_vault_env` 가 keychain 만 읽고 env-session 폴백이 없는 것) 는 [/ops/known-gaps](/ops/known-gaps) 에 분석 기록.

## ⚠️ 함정 — 회피 필수

| # | 함정 | 결과 | 회피 |
|---|---|---|---|
| 1 | pull-polling 배포 | 1시간+ lag | push (D6) |
| 2 | 자체 mTLS | 운영 부담 | Tailscale + restic 암호화 |
| 3 | schema-per-customer (한 macmini 다중 customer) | 격리 약 | macmini 1대/customer |
| 4 | OAuth 1차 시도 | 도메인 검증 등 함정 layer | Phase 3 deferral 까지 |
| 5 | 2-level subdomain SSL | 유료 ($10/cert/월) | 1-level + path |
| 6 | service-only domain (`frame.axelabs.ai`) | customer 격리 불가 | `{customer}.axelabs.ai/{service}` |
| 7 | `.local` 도메인 | mDNS 충돌 | platform/corporate 분리 |
| 8 | `axellc.com` 으로 platform 트래픽 | corporate ↔ platform 혼탁 | `axelabs.ai` 만 |
| 9 | cloudflared path strip 가정 | 라우터에서 prefix 못 찾음 | 서비스에 prefix mount |
| 10 | cloudflared SIGHUP 직접 호출 | process 죽음 | `docker restart` |
| 11 | frame container 직접 cloudflared 바인딩 | swap 불가 | host-side proxy 경유 |
| 12 | 다운타임 deploy | 사용자 5xx | blue/green |
| 13 | `.claude/settings.json` 의 mcpServers | silent 무시 | `.mcp.json` (D-ops-7) |
| 14 | Microsoft Application ID URI 와 scope prefix 불일치 | AADSTS9010010 | 둘 다 같은 URL prefix |
| 15 | Allow public client flows: No + secret 없음 | AADSTS7000218 | Yes 또는 secret |
| 16 | accessTokenAcceptedVersion=2 + Anthropic 의 aud check | mcp_client_invalid | null/1 (v1 token, aud=URI) |
| 17 | App ID URI 삭제 cleanup | AADSTS500011 | 복원 후 propagation 대기 |
| 18 | compose `environment:` 의 `$VAR` default-empty 치환 (docker-compose `dollar-brace VAR colon dash brace` 형식) 가 `env_file` 값을 shadow | 컨테이너 secret 빈 값 | `environment:` 에서 비밀 var 제거 (D-ops-18) |
| 19 | compose subdir (`REPO/docker/` 형태) 의 Docker auto-load `.env` 부재 | `$VAR` substitution (docker-compose 변수) 실패, 컨테이너 미부팅 | `ln -sf ../.env docker/.env` symlink (D-ops-18) |
| 20 | `axe secret pull` 옛 버전이 .env 전체 덮어씀 | 비밀 외 config 라인 wipe (2026-05-21 blueprint 사고) | 코드 fix 완료 (merge-mode). pull 출력에 "non-managed lines preserved" 확인 |
| 21 | portal-등록 Azure app 에 owner 미지정 | `az ad app credential reset` 권한 거부 | 운영자를 portal 의 Owners 탭에 명시 추가 (D-ops-19) |
| 22 | `az ad app credential reset` (no `--append`) | 기존 secrets 전부 삭제 → overlap window 없음 | 항상 `--append` (D-ops-19) |
| 23 | 새 fact 도입 시 schema 를 AXE 가 직접 정의 시도 | AXE 가 schema authority 부담 → 작업 정체 + drift | **MCP 가 schema 권위** (frame/hive 등 — 자기 도메인 `/schemas` endpoint). 자기 도메인 MCP 없으면 LLM 자율 free-form. Blueprint 는 discovery / mirror only ([D-bp-artifact-1](/ops/decisions)) |
| 24 | artifact extraction 을 Anthropic API direct call 로 구현 | per-token 비용 + per-user attribution 손실 + Max plan 무제한 활용 못 함 | Claude Code OAuth (Max plan) 통해 호출 — Teams bot / 로컬 CLI / 웹 모두 same surface. API direct 는 대량 batch / vision-heavy 만 ([D-bp-artifact-7](/ops/decisions)) |

## 결정 변경 절차

새 결정 또는 기존 결정 변경 시:

1. **multi-tenant-platform-plan.md** 또는 **frame/DECISIONS.md** 에 추가 (해당하는 곳)
2. 본 페이지의 표 갱신
3. 영향 받는 다른 docs 페이지 수정
4. customer admin / 직원에게 통지 (영향 받는 경우)

## 회고 주기

분기마다 (Jan/Apr/Jul/Oct 15) DECISIONS 회고:

- 채택한 결정 중 후회 있는 것
- 함정에 빠진 사례
- 새로 발견된 함정
- D-ops 회수번호 (deprecate 결정)

## 참고

- `/Users/axe/multi-tenant-platform-plan.md` — 마스터 plan + D-config-N
- `/Users/axe/frame/DECISIONS.md` — frame D-ops-1~15
- `/Users/axe/hive/DECISIONS.md` — hive D-hive-1~25
- `/Users/axe/blueprint/docs/project-blueprint.md` — blueprint 마스터 (5 분과)
- `/Users/axe/CLAUDE.md` — 포트 · launchd 인벤토리

---

<!-- PAGE https://docs.axelabs.ai/ops/host-setup -->

# macmini host setup

> axelabs.ai customer macmini 전체 setup. 13 layer step-by-step + 본 머신 (axe-macmini) 현재 inventory + 함정.

URL: https://docs.axelabs.ai/ops/host-setup

# macmini host setup

> **본 페이지의 위치**: 비전 = "macmini 10대 × customer 직원 1-2명/customer 시스템 개선" ([D-dev-platform-1](/ops/decisions)). 각 customer 머신 셋업의 SSOT. 신규 customer onboard 시 본 페이지 위에서 자동화 CLI ([B-axe-host-bootstrap-cli](/ops/backlog)) 가 진행할 task의 인간이 읽을 reference.
>
> **운영자 ritual**: 본 페이지 변경 시 = 운영 실패 / 함정 발견 / 신규 layer 추가의 trigger. 모든 macmini 변경의 SSOT.

13 layer + 본 머신 (axe-macmini) 의 현재 값을 짝지어 정리.

## Layer 0 — Hardware

- Mac mini (Apple silicon 권장 — M1/M2/M3/M4). 외장 SSD 1개 (backup tier B).
- 본 머신 = AXEs-Mac-mini (Soohun 운영).

## Layer 1 — macOS + system tunables

| 항목 | 값 (본 머신) | 신규 setup |
|---|---|---|
| macOS version | 26.3.1 (Build 25D771280a) | 26.0+ 권장 |
| Remote Login | `on` (sshd active port 22) | `sudo systemsetup -setremotelogin on` |
| `kern.tty.ptmx_max` | 511 (default) | leak 함정 — Claude Desktop app 의 PTY leak 으로 한도 도달 가능. `sudo sysctl -w kern.tty.ptmx_max=2047` + launchd plist 영구화 ([B-axe-pty-max-launchd](/ops/backlog)) |
| `launchctl limit maxfiles` | `256 / unlimited` | 낮음 — heavy MCP/Docker 운영 시 부족할 수 있음 |
| `launchctl limit maxproc` | `5333 / 8000` | 충분 |
| FileVault | (확인 필요) | 권장 ON (외장 SSD backup 도 암호화) |
| Time Machine | (선택) | restic 백업이 primary, TM 은 보조 |

## Layer 2 — macOS users + dev group ([D-dev-platform-1](/ops/decisions))

본 머신:
- `axe` (UID 501) — ai@ 봇 전용 (자동화/cron/MCP container 운영자)
- `soohun.kang` (UID 502) — 운영자 본인 dev 계정
- `taehun.kang` (UID 503) — axev 대표 dev 계정
- group `dev` (GID 501) — 위 3명 모두 가입

신규 setup:
```bash
sudo bash <<'OPSCRIPT'
set -e
dseditgroup -o create -r "AXE Developers" -n . dev 2>/dev/null || true
dseditgroup -o edit -a axe -t user dev
OPSCRIPT
# user 추가 (각 사람마다)
sudo sysadminctl -addUser <shortname> -fullName "<Full Name>" -password <random> -shell /bin/zsh -home /Users/<shortname> -GID 501
sudo createhomedir -c -u <shortname>
sudo dseditgroup -o edit -a <shortname> -t user dev
sudo install -d -o <shortname> -g dev -m 700 /Users/<shortname>/.ssh
sudo install -m 600 -o <shortname> -g dev /dev/null /Users/<shortname>/.ssh/authorized_keys
# password 는 Vaultwarden item 'axe-macmini local: <shortname>' 에 등재
```

repo 공유 — `/Users/axe/{blueprint,frame,hive,axelabs-docs}` = group `dev` + setgid + git `core.sharedRepository=group`:
```bash
for d in blueprint frame hive axelabs-docs; do
  sudo chgrp -R dev "/Users/axe/$d"
  sudo find "/Users/axe/$d" -type d -exec chmod g+rwsX {} +
  git -C "/Users/axe/$d" config core.sharedRepository group
done
```

## Layer 3 — sudoers (`/etc/sudoers.d/ai-axe`, D-dev-platform-1)

ai@ subprocess 가 NOPASSWD 로 실행 가능한 좁은 명령 set:

```
Cmnd_Alias AI_USER = /usr/sbin/dseditgroup, /usr/sbin/sysadminctl, /usr/bin/dscl ., /usr/sbin/createhomedir
Cmnd_Alias AI_SSH = /bin/launchctl kickstart -k system/com.openssh.sshd, /usr/sbin/sshd -t
Cmnd_Alias AI_FS = /usr/bin/install, /usr/sbin/chown, /usr/bin/tee /Users/*, /usr/bin/tee /etc/ssh/sshd_config*, /bin/mv /etc/ssh/sshd_config*
axe ALL=(ALL) NOPASSWD: AI_USER, AI_SSH, AI_FS
```

설치: `sudo install -m 440 /dev/stdin /etc/sudoers.d/ai-axe <<<'<content>'` + `sudo visudo -cf /etc/sudoers.d/ai-axe`.

**금지**: `tee` 의 wildcard 가 `/Users/*` 또는 `/etc/ssh/sshd_config*` 로 제한 — `tee` 자체 무제한 NOPASSWD = root takeover.

## Layer 4 — SSH 강화 ([D-dev-platform-1](/ops/decisions))

`/etc/ssh/sshd_config.d/200-axe-hardening.conf`:
```
PasswordAuthentication no
ChallengeResponseAuthentication no
KbdInteractiveAuthentication no
PubkeyAuthentication yes
PermitRootLogin no
```

검증: `sudo sshd -t` → reload: `sudo launchctl kickstart -k system/com.openssh.sshd`.

**Layer 1 보호** = Cloudflare Tunnel + Zero Trust (Microsoft Entra SSO 게이트). host SSH 는 layer 2 = key-only.

## Layer 5 — Tailscale + Cloudflare Tunnel

| 항목 | 본 머신 |
|---|---|
| Tailscale IP | 100.127.210.30 (host: axe-macmini) |
| Cloudflare tunnel UUID | `d8efecdd-2c3f-42de-9925-501433e21394` (container `axelabs-tunnel`) |
| 외부 hostname (axe.axelabs.ai) | `/blueprint/mcp` `/frame` `/hive` `/vault` `/index` (catch-all → blueprint-app) |
| 추가 hostname | `ssh.axe.axelabs.ai` (host SSH, Zero Trust App) [D-dev-platform-5] |
| Cloudflare Zero Trust App | `b903d8cd-...` (Self-hosted, Email policy `*@axellc.com`) |
| Zone | `axelabs.ai` (zone id `850053fec240de9d83f165cd3e6f10a5`) |
| Account | `6e6bbb05187c8bfea52d63fa1a06460b` |

신규 customer 머신:
- Tailscale install + tailnet 합류 (Microsoft Entra SSO)
- 새 cloudflared tunnel UUID 발급 (Cloudflare 대시보드)
- DNS CNAME `<customer>.axelabs.ai` → tunnel hostname
- Zero Trust App `ssh.<customer>.axelabs.ai` (선택 — 외부 dev access 시)

## Layer 6 — Microsoft Entra ID

| 앱 | 용도 |
|---|---|
| Frame MCP | 회계 backend 접근 (PKCE public client) |
| Hive MCP | HR backend 접근 (PKCE public client) |
| Blueprint MCP | platform MCP at apex (PKCE public client) |
| Vaultwarden | password vault SSO (OIDC confidential, secret 보관) |
| Blueprint Web | web UI NextAuth (OIDC) |

axe tenant ID = `122fb574-7efa-476a-95b6-bee81bce2cce` (axellc.com).

신규 customer = 자기 tenant 별도. 본 머신의 5 앱 패턴 미러. 자동 등록: [ops/runbook/customer-onboarding](/ops/runbook/customer-onboarding).

## Layer 7 — Vaultwarden ([D-ops-11](/ops/decisions) Timshel fork, [D-ops-24/26/27/29](/ops/decisions) SSO)

- 컨테이너: `axe-vaultwarden` (host `axe.axelabs.ai/vault`)
- bw CLI: 2025.7.0 (Timshel fork schema 호환 — [D-ops-28](/ops/decisions))
- SSO: Microsoft Entra (SSO_AUTHORITY single-tenant)
- 환경 vars: `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION=true`, `SIGNUPS_ALLOWED=true`, `SSO_ONLY=false`, `ORGANIZATION_INVITE_AUTO_ACCEPT=true`
- org: AXE (`0c5d8bbd-ad85-42b4-8b8a-2849031981b1`)
- collections: Default · frame-jwt-axec · frame-jwt-axev · frame-jwt-operators

신규 customer = vault 인스턴스 별 (또는 same vault 다른 org). `axe customers vault-bootstrap <id>` ([D-dev-platform-3](/ops/decisions)) 가 3 collection 자동.

**Vault session 관리** ([D-dev-platform-6](/ops/decisions)): `axe vault unlock` 운영자 1회 → macOS Keychain (`axe.vault.session` / `ai@axellc.com`) 에 BW_SESSION push. ai@ subprocess 가 `_vault_env()` 로 자동 fetch. BW_SESSION 채팅 회신 패턴 폐기.

## Layer 8 — Docker stacks

| Container | 용도 |
|---|---|
| axe-tunnel · axelabs-tunnel · artemis-tunnel | Cloudflare cloudflared (외부 ingress) |
| axe-caddy · axe-blueprint-mcp-proxy · axe-frame-proxy · axe-hive-proxy · axe-vault-caddy | reverse proxy (Caddy 2) |
| axe-vaultwarden | Vaultwarden (password vault) |
| blueprint-app · blueprint-postgres · blueprint-mcp-blue · blueprint-mcp-green | Blueprint platform |
| frame-mcp-blue · frame-mcp-green · frame-postgres · frame-worker | frame 회계 |
| hive-mcp-blue · hive-mcp-green · hive-postgres | hive HR |
| axelabs-docs | docs.axelabs.ai (Nextra) |
| axelabs · axe-console-app | platform UIs |
| artemis-api · artemis-web · artemis-db · artemis-collector_* | artemis (filings/news) |
| mysrt-app · mysrt-nginx · mysrt-postgres | mysrt SRT 자동 예매 |

Docker networks: `artemis_default` · `blueprint_default` · `frame_default` · `hive_default` · `mysrt_default` · `vault_default` · `console_default`.

신규 customer = 동일 stack 일부 (frame + hive + blueprint + vault + cloudflared 가 핵심). `axe customer deploy <id>` ([B-dev-platform-customer-deploy](/ops/backlog)) 자동화 예정.

## Layer 9 — launchd jobs

본 머신 활성:
- `com.cortex.frontend` / `com.cortex.backend` / `com.cortex.cloudflared` (Cortex)
- `com.artemis.filings` / `collectors` / `index` / `index_intraday` / `reporters` / `logrotate` / `backup`
- `com.mysrt.app` (간접 — mysrt container)
- `com.axe.blueprint-usage-digest` (Teams 일일 사용량 09:00 KST)
- `com.axe.blueprint-skills-sync` (git webhook → ~/.claude/skills/)
- `com.axe.blueprint-rebuild-watcher` (rebuild trigger file polling)
- `com.axe.health-check` (매분 7 도메인 + bind-mount probe)
- `com.axe.secret-check` (09:00 KST vault drift)
- `com.axe.operator-alert-notify` (docker logs tail → osascript notification)
- `com.axe.backup.local` (외장 SSD restic)
- `com.axe.restore-drill` (분기별 restore 검증)
- `com.axe.ring.push` (frame data ring push)
- `com.axe.console.refresh` (axe-console-app refresh)

신규 customer = 본 머신 set 의 subset (customer 별 deploy script 가 깔아줌).

## Layer 10 — CLI tools

| 도구 | 설치 | 비고 |
|---|---|---|
| Homebrew | `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"` | macOS 표준 |
| `axe` CLI | `/Users/axe/.axe/bin/axe` (local Python single file, git 미관리) | 별도 git repo 화 backlog |
| `bw` CLI | `brew install bitwarden-cli@2025.7.0` ([D-ops-28](/ops/decisions) 다운그레이드) | Timshel fork 호환 |
| `cloudflared` | `brew install cloudflared` | Tunnel + Access SSH |
| `gh` CLI | `brew install gh` + `gh auth login --with-token` | `axe-labs-ai` PAT (Vault) — [D-dev-platform-4](/ops/decisions) |
| `docker` | Docker Desktop for Mac | file sharing + memory 8GB+ |
| `python3` | macOS 기본 (또는 `brew install python@3.14`) | axe CLI venv 자동 |
| `pnpm` / `node` | `brew install pnpm` (node 자동) | Blueprint dev |

git config (global):
```bash
git config --global user.email ai@axellc.com
git config --global user.name "AXE Labs AI"
```

## Layer 11 — Git repos + GitHub

본 머신:
- `/Users/axe/blueprint, frame, hive, axelabs-docs` (4 core)
- `/Users/axe/artemis, cortex, axelabs, mysrt, kolon-discussion, distributa, magnet, stream` (별 service)
- `/Users/axe/.axe/` — local-only (git 미관리)

GitHub org = `axelabs-ai` (Free plan, [D-dev-platform-5](/ops/decisions)). 4 core repo 에 CODEOWNERS skeleton + PR template ([B-dev-platform-cf-zerotrust](/ops/backlog) 완료).

신규 customer = 자기 GitHub user 발급 + `axelabs-ai/<customer>-developers` team 가입 (`axe customers github-team <id>` — [D-dev-platform-3](/ops/decisions)).

## Layer 12 — OneDrive sync

운영자 Microsoft OneDrive client 설치 (Soohun 개인 + 공유). symlink 로 `~/OneDrive` → workspace 자료. Blueprint Workspace.drivePath = OneDrive 폴더 GUID.

신규 customer = 본인 OneDrive 또는 SharePoint site. Blueprint 의 trinity 모델 (Workspace × OneDrive × TeamsChat).

## Layer 13 — Backup ([D-config-14](/ops/decisions) DR cold storage)

- `axe-backup` launchd (daily) — restic snapshot
- Tier A: `blueprint-postgres` + `hive-postgres` + `customers.yaml` + Vaultwarden data dir
- Tier B: 외장 SSD rotation (사용자 manual swap)
- restore drill 분기별 (`com.axe.restore-drill`)

신규 customer = 자기 외장 SSD + 본 머신 patterns 미러.

## 신규 macmini setup 순서 (요약)

1. Layer 0-1 (Hardware + macOS) — 운영자 manual
2. Layer 2 (users + dev group) — `axe user add` ([B-dev-platform-user-add-cli](/ops/backlog)) 자동화 예정
3. Layer 3-4 (sudoers + SSH) — `axe host bootstrap` ([B-axe-host-bootstrap-cli](/ops/backlog)) 자동화 예정
4. Layer 5 (Tailscale + Cloudflare) — Tailscale CLI + `axe customers dns-placeholder <id>` ([B-dev-platform-dns-placeholder-cli](/ops/backlog))
5. Layer 6 (Entra ID) — 운영자 Azure CLI + 도메인 verify (수동)
6. Layer 7 (Vault) — `axe customers vault-bootstrap <id>` + `axe vault bootstrap`
7. Layer 8 (Docker) — `axe customer deploy <id>` ([B-dev-platform-customer-deploy](/ops/backlog)) 자동화 예정
8. Layer 9 (launchd) — `axe customer deploy` 가 install
9. Layer 10 (CLI) — `axe customer deploy` 가 brew install
10. Layer 11 (Git) — `axe customers github-team <id>` + 직원 별 collaborator
11. Layer 12 (OneDrive) — 운영자 수동
12. Layer 13 (Backup) — `axe customer deploy` 가 launchd 등재

## 함정 + 알려진 미해결

| 함정 | 결과 | 회피 / 결정 |
|---|---|---|
| `kern.tty.ptmx_max=511` 한도 + Claude Desktop PTY leak | `forkpty: Device not configured` → 새 terminal 못 열림 | Claude Desktop 재시작 또는 sysctl 늘림 + launchd plist 영구화 ([B-axe-pty-max-launchd](/ops/backlog)) |
| `launchctl limit maxfiles=256` | heavy MCP/Docker 시 fd 부족 | per-process 명령 또는 launchd plist 늘림 |
| sudoers wildcard 부정확 — `tee` 전체 NOPASSWD | root takeover | `tee` 경로 한정 (`/Users/*`, `/etc/ssh/sshd_config*`) |
| Cloudflare API token 의 scope 가 notes 와 실제 다름 | API 호출 불필요 fail | `curl /user/tokens/verify` 로 실 권한 검증 |
| Bitwarden CLI 2025.8.0+ 가 Timshel fork schema reject | bw 명령 모두 fail | 2025.7.0 pin ([D-ops-28](/ops/decisions)) |
| BW_SESSION 만료 + ai@ subprocess stdin tty 없음 | bw CLI 호출 fail | Keychain-backed session ([D-dev-platform-6](/ops/decisions)) |
| Docker bind-mount file source 손상 | container "not a directory" 거부 | file → dir 변환 + restic restore |
| Fine-grained PAT 의 Resource owner = 본인 (org 아님) | org repo 접근 시 "Could not resolve to a Repository" (404), org membership 와 무관 | 발급 시 Resource owner dropdown = **org** 선택 ([D-dev-platform-4](/ops/decisions)) |
| GitHub UI 에서 PAT regenerate → keyring stale | `gh auth status` ✓ 인데 모든 API 401 (gh CLI 가 옛 token cached) | `gh auth logout -h github.com -u <user>` + `gh auth login --with-token` 새 PAT 으로 재로그인 |
| bw CLI subprocess 호출 시 BW_SESSION env 누락 | bw 가 master password prompt → subprocess stdin pipe → hang 또는 JSON parse fail | python `subprocess.run(..., env={**os.environ, "BW_SESSION": ..., "NODE_EXTRA_CA_CERTS": ...})` 명시 전달 ([D-dev-platform-6](/ops/decisions)) |

## 관련 페이지

- [/ops/inventory](/ops/inventory) — 본 머신 자산 list (paths, ports)
- [/ops/runbook/customer-onboarding](/ops/runbook/customer-onboarding) — 신규 customer 절차
- [/architecture/auth](/architecture/auth) — Microsoft Entra + frame/hive/blueprint OAuth
- [/architecture/secrets](/architecture/secrets) — vault 정책
- [/architecture/backup](/architecture/backup) — restic + 외장 SSD
- [/ops/decisions](/ops/decisions) — 모든 D-... 결정
- [/ops/backlog](/ops/backlog) — `B-axe-host-bootstrap-cli` + `B-axe-pty-max-launchd` 등 후속

---

<!-- PAGE https://docs.axelabs.ai/ops/inventory -->

# 인프라 인벤토리

> 모든 서비스 / 포트 / 파일 / launchd / 컨테이너 전체 목록.

URL: https://docs.axelabs.ai/ops/inventory

# 인프라 인벤토리

## 포트 할당

[/Users/axe/CLAUDE.md](https://github.com/soohunkang/blueprint/blob/main/CLAUDE.md) 가 SSOT. 본 표는 후행 정리.

| 범위 | 프로젝트 |
|---|---|
| 31xx | Blueprint |
| 32xx | Cortex |
| 33xx | Artemis |
| 34xx | Distributa |
| 35xx | Kolon Discussion |
| 36xx | mysrt |
| 37xx | frame |
| 38xx | hive |
| 39xx | axelabs (회사 홈 + @axe/ui) + matrix (인프라 모니터링 MCP) |
| 31xx ~ | docs (3140 = axelabs-docs) |

### 전체 포트 테이블

| 서비스 | 포트 | 컨테이너 / 프로세스 | 관리 |
|---|---|---|---|
| Blueprint Next.js dev | 3100 | node | 수동 |
| Blueprint WebSocket | 3101 | node | 수동 |
| Blueprint Docker nginx | 3180 / 3143 | Docker | docker compose |
| Cortex Postgres 16 | 3200 | Docker `cortex-postgres` | docker compose |
| Cortex MCP blue | 3210 | Docker `cortex-mcp-blue` (alias `cortex-mcp` active) | docker compose |
| Cortex MCP green | 3211 | Docker `cortex-mcp-green` (passive) | docker compose (task 15) |
| Cortex proxy (Caddy blue/green selector) | 3212 | Docker `axe-cortex-proxy` | docker compose (task 15) |
| Cortex cloudflared (legacy, mysrt only) | 20241 | cloudflared | launchd `com.cortex.cloudflared` — D-cortex-7 후 cortex 라우트 제거, mysrt.axellc.com 만 서비스 |
| Artemis Qdrant | 6333 | Docker | docker compose |
| Artemis Caddy | 3380 / 3343 | Docker | docker compose |
| Distributa Next.js | 3400 | node | 수동 |
| Kolon Discussion | 3500 | node | 수동 |
| mysrt FastAPI | 3600 | uvicorn | launchd `com.mysrt.app` |
| frame Postgres 16 | 3700 | Docker `frame-postgres` | docker compose |
| frame MCP blue | 3710 | Docker `frame-mcp-blue` | docker compose |
| frame MCP green | 3711 | Docker `frame-mcp-green` | docker compose |
| frame proxy (Caddy blue/green selector) | 3712 | Docker `${CUSTOMER_PREFIX:-axe}-frame-proxy` (기본 `axe-frame-proxy`, 멀티커스터머 prefix 변수화) | docker compose |
| Blueprint Postgres 16 | 3120 | Docker `blueprint-postgres` | docker compose |
| Blueprint MCP blue | 3152 → 3000 | Docker `blueprint-mcp-blue` (alias `blueprint-mcp` active) | docker compose |
| Blueprint MCP green | 3153 → 3000 | Docker `blueprint-mcp-green` (passive) | docker compose |
| Blueprint MCP proxy (Caddy) | 3151 | Docker `axe-blueprint-mcp-proxy` | docker compose |

> blueprint-mcp blue/green 은 Microsoft Entra 토큰 + **Blueprint 플랫폼 토큰**(`axe login`, D-axe-idp-1) 둘 다 수용 — `environment:` 의 `BLUEPRINT_ISSUER=https://blueprint.axellc.com`(+ `BLUEPRINT_AUDIENCE`) 가 자체 OP 의 resource-server 신뢰를 켠다 (2026-06-04, [known-gaps](/ops/known-gaps#oidc-발행자가-자기-토큰을-401-issuer--resource-server)). 미설정 시 Entra 경로만.

| hive Postgres 16 | 3800 | Docker `hive-postgres` | docker compose |
| hive MCP blue | 3810 | Docker `hive-mcp-blue` | docker compose |
| hive MCP green | 3811 | Docker `hive-mcp-green` | docker compose |
| hive proxy (Caddy blue/green selector) | 3812 | Docker `axe-hive-proxy` | docker compose |
| axelabs-docs (이 문서) | 3140 | node | 수동 / launchd 검토 |
| axelabs (회사 홈 + @axe/ui 쇼케이스) | 3900 | Docker `axelabs` (Next.js standalone) | docker compose |
| matrix Postgres 16 | 3901 | Docker `matrix-postgres` | docker compose |
| matrix MCP blue | 3910 | Docker `matrix-mcp-blue` (alias `matrix-mcp` active) | docker compose |
| matrix MCP green | 3911 | Docker `matrix-mcp-green` (passive) | docker compose |
| matrix proxy (Caddy blue/green selector) | 3912 | Docker `axe-matrix-proxy` (127.0.0.1 bind) | docker compose |
| stream MCP (realchoice) | 8780 | Docker `stream-mcp` | docker compose |
| magnet MCP (realchoice) | 8770 | Docker `magnet-mcp` | docker compose |

## launchd 서비스 (자동 시작)

| 라벨 | 용도 | 빈도 |
|---|---|---|
| `com.cortex.cloudflared` | mysrt.axellc.com tunnel (legacy 명) — 추후 axe-tunnel Docker 로 이전 후 폐기 | always |
| `com.artemis.filings` | 공시 수집 | 매일 18:00 |
| `com.artemis.collectors` | WatchPath 트리거 | event |
| `com.mysrt.app` | mysrt (:3600) | always |
| `com.frame.token-rotation` | frame JWT 갱신 | 매 8h |
| `com.frame.integrity-check` | nightly 무결성 감사 | 매일 |
| `com.axe.backup.local` | local restic backup | 매일 03:00 KST |
| `com.axe.ring.push` | ring backup push | 매일 03:30 KST |
| `com.axe.restore-drill` | 분기별 restore drill | Jan/Apr/Jul/Oct 15 03:00 |
| `com.axe.console.rebuild` | 운영자 콘솔 rebuild | 매시 |
| `com.axe.health-check` | 인프라 health probe | 매분 |
| `com.axe.secret-check` | secret 만료 알림 | 매일 09:00 |
| `com.axe.operator-alert-notify` | Blueprint silent-drop L2 — `[OPERATOR-ALERT]` 마커 tail → macOS notification (D-bp-alert-1, 2026-05-22) | always (KeepAlive) |
| `com.axe.netheal` | 인터넷 자가치유 — WAN 끊김 시 DNS플러시→DHCP갱신→WiFi바운스 + ISP 인지 백오프 (D-matrix-4). `/usr/local/sbin/axe-netheal.sh`, 로그 `/var/log/axe-netheal.log` | always (KeepAlive) |

전체 list:

```bash
launchctl list | grep -E 'cortex|artemis|mysrt|frame|axe' | head -30
```

## Docker 컨테이너 (axe-macmini 기준)

```
axelabs-tunnel              cloudflared (axelabs.ai 트래픽)
axe-frame-proxy             Caddy (blue/green selector :3712)
frame-mcp-blue              FastMCP (:3710)
frame-mcp-green             FastMCP (:3711, passive)
frame-postgres              PostgreSQL 16 (:3700)
axe-hive-proxy              Caddy (blue/green selector :3812)
hive-mcp-blue               FastMCP (:3810)
hive-mcp-green              FastMCP (:3811, passive)
hive-postgres               PostgreSQL 16 (:3800)
axe-blueprint-mcp-proxy     Caddy (:3151, upstream alias `blueprint-mcp`)
blueprint-mcp-blue          FastMCP (:3000 internal, host :3152, alias `blueprint-mcp` active)
blueprint-mcp-green         FastMCP (:3000 internal, host :3153, passive)
blueprint-postgres          PostgreSQL 16 (:3120, Prisma schema)
axe-matrix-proxy            Caddy (:3912 → upstream alias `matrix-mcp`, 127.0.0.1 bind only)
matrix-mcp-blue             Rust/axum (:3910, alias `matrix-mcp` active, MCP + REST + collector)
matrix-mcp-green            Rust/axum (:3911, passive)
matrix-postgres             PostgreSQL 16 (:3901, ICU ko-KR)
axe-vaultwarden             Vaultwarden Timshel
axe-vault-caddy             Caddy (vault TLS termination :8222)
axe-caddy                   Caddy (admin.axelabs.ai)
artemis-*                   Artemis stack (별도 운영)
blueprint-app               Blueprint (axe customer 의 Next.js)
```

확인:
```bash
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
```

## 핵심 파일

| 파일 | 역할 |
|---|---|
| `/Users/axe/.axe/customers.yaml` | 멀티테넌트 SSOT |
| `/Users/axe/.axe/bin/axe` | 운영자 CLI |
| `/Users/axe/CLAUDE.md` | 포트 / 도메인 / launchd 모음 |
| `/Users/axe/multi-tenant-platform-plan.md` | 플랫폼 마스터 plan |
| `/Users/axe/frame/DECISIONS.md` | D-ops 결정 기록 |
| `/Users/axe/.axe/state.yaml` | 현재 rollout phase |
| `/Users/axe/.axe/NEXT_SESSION.md` | 다음 세션 컨텍스트 |
| `/Users/axe/.axe/tunnels/axelabs/config.yml` | cloudflared ingress |
| `/Users/axe/.axe/vault/docker-compose.yml` | Vaultwarden |
| `/Users/axe/.axe/vault/.env` | Vaultwarden secrets |
| `/Users/axe/frame/.env.local` | frame env_file (vault-pulled, D-ops-17/18). docker-compose env_file 단일 출처 — `environment:` 블록은 literal config 만 |
| `/Users/axe/hive/.env.local` | hive env_file (vault-pulled). 동일 패턴 (D-ops-18) |
| `/Users/axe/blueprint/.env` | Blueprint env (vault-pulled). compose project_dir=`docker/` 라서 `docker/.env → ../.env` symlink 필요 (`bin/setup-env-symlink.sh`) |
| `/Users/axe/.axe/backups/local/` | restic Tier A repo |
| `/Users/axe/.axe/messages/` | 외부 송부 메시지 (realchoice 등) |

## Docker 네트워크

| 네트워크 | 용도 | 멤버 (예시) |
|---|---|---|
| `frame_default` | frame 컨테이너 격리 | postgres, frame-mcp-blue/green |
| `artemis_default` | 플랫폼 공유 | axelabs-tunnel, axe-caddy, blueprint-app, frame-mcp-blue/green (alias) |

확인:
```bash
docker network ls
docker network inspect artemis_default
```

## DNS Records (Cloudflare zone `axelabs.ai`)

| Type | Name | Content | Proxy |
|---|---|---|---|
| CNAME (Tunnel) | axe | `AXELABS-UUID.cfargotunnel.com` | ON |
| CNAME (Tunnel) | *.axe | `AXELABS-UUID.cfargotunnel.com` | ON (wildcard) |
| CNAME (Tunnel) | admin | `AXELABS-UUID.cfargotunnel.com` | ON |
| CNAME (Tunnel) | docs | `AXELABS-UUID.cfargotunnel.com` | ON |
| CNAME | www | axelabs.ai | ON |
| TXT | axe | `MS=ms10433167` (Microsoft 도메인 검증) | DNS only |

`AXELABS-UUID` = `d8efecdd-2c3f-42de-9925-501433e21394`. Cloudflare UI 가 `.cfargotunnel.com` suffix 를 인식해서 Type 컬럼에 `Tunnel` 로 표시.

## Microsoft Entra ID Apps (axe customer 기준)

| App | Client ID | 용도 |
|---|---|---|
| Frame MCP | 137fc0ef-eb9f-4903-acbc-1a748add349c | 회계 OAuth |
| Hive MCP | b7ead15d-2fea-4864-a5a8-b4b07d1629d4 | HR OAuth |
| Blueprint MCP | 482598f7-540c-462c-9dfd-b957651eb804 | Blueprint platform OAuth (D-bp-mcp-1) |
| axe-vaultwarden | 9d0dc49b-a251-45e1-9f10-74704af3c033 | Vault SSO |
| Blueprint Web | (별도) | Web UI 로그인 |

Application ID URI:
- Frame MCP: `https://axe.axelabs.ai/frame/mcp`
- Hive MCP: `https://axe.axelabs.ai/hive/mcp`
- Blueprint MCP: `https://axe.axelabs.ai/blueprint/mcp`
- Vaultwarden: (Microsoft 기본 `api://...`)

## Cloudflare Tunnel

| Tunnel | ID | 실행 |
|---|---|---|
| `axelabs` | `d8efecdd-2c3f-42de-9925-501433e21394` | Docker `axelabs-tunnel` (axelabs.ai 전체) |
| `cortex` | `35b42a0a-8ef8-467d-be90-2f46b3e0dbd0` | launchd `com.cortex.cloudflared` (cortex.axellc.com, mysrt.axellc.com) |
| `axe` | `846f512c-7a35-45f0-8cea-d41157318856` | 별도 운영 |
| (customer 측) | (별도) | (each customer macmini) |

확인 (host):
```bash
cloudflared tunnel list
```

## Vaultwarden Organizations

| Organization | 용도 |
|---|---|
| `axe` | 액스코퍼레이션 주식회사 platform (axec entity 가 운영 주체) |
| `realchoice` (예정) | realchoice customer |

Collections (per organization):
- `frame-jwt-&lt;entity&gt;` — 운영자 발급 토큰 보관 (현재 dormant, OAuth 사용 후)
- `frame-secrets` — client_id, client_secret 보관
- `infra-secrets` — backup password 등

## Backup repositories

| Tier | 위치 | Password |
|---|---|---|
| A (local) | `/Users/axe/.axe/backups/local/` | Keychain `axe.backup.restic.local` |
| B (ring) | `realchoice:/Users/realchoice/peer-backups/axe/` | Keychain |
| C (cold) | `/Volumes/axe-cold-{1,2,3}/restic-repo/` | 종이 메모 |

백업 대상 dump (`axe-backup`, 매일 03:00): frame · blueprint · hive · mysrt · **index** (`evidence_blob` = 죽은 딜 OneDrive/Blueprint 원본 삭제 후 SOLE 사본, [D-index-51](/ops/decisions)) + `.local/files/`. 상세 = [backup](/architecture/backup).

## 현재 customer 상태

SSOT = `/Users/axe/.axe/customers.yaml`. 본 표는 후행 정리. 빠른 확인: `axe customers list`.

### Customer 메타

| id | name | public_domain | entities | onboarded | 상태 |
|---|---|---|---|---|---|
| **axe** | AXE | `axe.axelabs.ai` | `axec` (액스코퍼레이션 주식회사) · `axev` (액스벤처스 주식회사) · `axep` (액스파트너스 유한책임회사, GP) · `axe_ia_001` (액스 투자조합 1호, KIP, GP=axev) | 2025-01-01 | **live** — 9 service in-house 가동, AXE 가 operator-of-record |
| **realchoice** | Realchoice | `realchoice.axelabs.ai` | `truvia` (트루비아 주식회사). customer 측 frame schema_name = `realchoice` (legacy_id, sovereignty 유지) | 2026-05-25 | **live (self-deploy)** — 5/5 endpoint LIVE, customer 측 자체 운영 (D-customer-sovereignty), AXE 측은 software supply + cloudflared catch-all 만 |

> `axe.entities` 의 한글 legal_name SoT = `customers.yaml` 의 `axe.entity_meta.(entity).legal_name` (2026-05-27 신설, `(entity)` = `axec` / `axev` / `axep` / `axe_ia_001`). frame DB 의 영문 `legal_name` (AX Capital LLC / AX Ventures LLC) 정정은 별 backlog `B-frame-entity-legal-name-i18n`. `axe_ia_001` 의 `entity_kind='kip'` (개인투자조합) 은 frame `shared.entity` CHECK constraint `['corporate','kip','kvf']` 의 fund tier.

### Customer × Service 매트릭스 (axe customer 가동 현황)

axe customer 의 서비스만 in-house. realchoice 는 customer self-deploy 라 AXE 측 가동 0. 각 service 의 가동 버전 + Docker container 상태 + path.

| Service | 버전 | 컨테이너 | path | 상태 |
|---|---|---|---|---|
| Blueprint | 0.1.0 | `blueprint-app` + `blueprint-mcp-blue/green` + `blueprint-postgres` + `axe-blueprint-mcp-proxy` | `/` (apex) + `/blueprint/mcp` | LIVE (5 컨테이너 healthy) |
| Frame | 0.1.0 | `frame-mcp-blue/green` + `frame-postgres` + `frame-worker` + `axe-frame-proxy` | `/frame` + `/frame/mcp` | LIVE (5 컨테이너 healthy) |
| Hive | 0.1.0 | `hive-mcp-blue/green` + `hive-postgres` + `axe-hive-proxy` | `/hive` + `/hive/mcp` | LIVE (4 컨테이너 healthy) |
| Matrix | 0.1.0 | `matrix-mcp-blue/green` + `matrix-postgres` + `axe-matrix-proxy` | `/matrix` + `/matrix/mcp` | LIVE (4 컨테이너 healthy, JWT enforced — [D-matrix-1](/ops/decisions)) |
| Cortex | 0.1.0 | `cortex-mcp-blue/green` + `cortex-postgres` + `axe-cortex-proxy` | `/cortex` + `/cortex/mcp` | ⚠ **degraded** — postgres healthy but mcp-blue/green Restarting (crash loop, task 15 진행 중 — [D-cortex-1..7](/ops/decisions)) |
| Vault | Timshel (axelabs-ai/vault axe.3) | `axe-vaultwarden` + `axe-vault-caddy` | `/vault` | LIVE (2 컨테이너 healthy) |
| Blurgram | (Rust) | `blurgram-api` + `blurgram-postgres` + `blurgram-redis` + `blurgram-tunnel` | `blurgram.com` (별 domain, AXE 운영) | LIVE (4 컨테이너 healthy — [D-ops-41](/ops/decisions)) |
| Stream | (Python) | — | — (customer realchoice 측에서 사용 예정, axe 측 가동 없음) | manifest only |
| Magnet | (Python) | — | — (customer realchoice 측에서 사용 예정, axe 측 가동 없음) | manifest only |

추가 컨테이너: `axelabs` (회사 홈 :3900) + `axelabs-docs` (이 문서 :3140) + `axelabs-tunnel` (cloudflared) — service 가 아닌 platform infrastructure.

### Customer × Service 매트릭스 (realchoice customer)

realchoice 는 **customer self-deploy** ([D-customer-sovereignty](/ops/known-gaps)) 모델 — AXE 측 컨테이너 0. AXE 책임 = (a) software supply (code/image), (b) 외부 노출 (DNS + cloudflared catch-all).

| Service | 상태 |
|---|---|
| Blueprint | customer self-deploy — `realchoice-macmini` 의 blueprint-app + mcp blue/green + postgres |
| Frame | customer self-deploy — frame-mcp-blue + frame-postgres + axe-frame-proxy (customer 측) |
| Hive | customer self-deploy — hive-postgres + hive-mcp-blue/green + axe-hive-proxy (customer 측) |
| Vault | customer self-deploy — vault-app (Timshel) + vault-caddy + vault-mcp + vault-cron |
| Ingress | customer self-deploy — axe-realchoice-ingress (host Caddy :8090) |
| Matrix / Cortex / Blurgram / Stream / Magnet | 미사용 (또는 customer 측 결정) |

빠른 검증: `curl https://realchoice.axelabs.ai/` → 200 (customer 측 정상 serve).

## 향후 추가 예정

| 항목 | Phase |
|---|---|
| index 서비스 | Phase 6 |
| 신규 customer onboarding (자동화 완성) | Phase 2 |
| OAuth proxy 재활성 (Anthropic Connector 개선 시) | D-ops-15 후속 |
| docs.axelabs.ai 배포 | 본 문서 작업 직후 |

---

<!-- PAGE https://docs.axelabs.ai/ops/known-gaps -->

# 알려진 gap

> docs 와 실제 구현 사이 의도된 / 미구현된 격차 목록.

URL: https://docs.axelabs.ai/ops/known-gaps

# 알려진 gap (정직 페이지)

문서는 "운영자가 1인 멀티테넌트 플랫폼을 잡고 갈 수 있도록 하는 사실 의 SSOT" 가 목표. 그러나 일부 항목은 미구현 / 단순화 / 향후 작업. 본 페이지는 그 격차를 명시.

> **시간축 4-페이지 분리** (2026-05-22, [D-docs-updates-1](/ops/decisions)):
> - [/ops/backlog](/ops/backlog) = **현재** — 실행 큐 (`🆕→📋→🔧→✅→⏸️`). 다른 세션의 entry point
> - [/ops/roadmap](/ops/roadmap) = **미래** — M1~M5 마일스톤 큰 그림
> - [/ops/updates](/ops/updates) = **과거** — Ship Log + Highlights + [/api/changes](/api/changes) JSON feed
> - **본 페이지** = (사실) — "왜 이렇게 됐는지 · 무엇이 함정인지" 의 분석적 사실 기록. entry point 아님
>
> 새 함정·미구현을 발견하면: **실행 가능한 항목** = backlog 🆕 / **사실·맥락 기록** = 본 페이지 / **ship 됨** = updates.

## deploy-SSOT guard = host-local 강제, 서버측 백스톱 없음 (2026-06-05)

[D-ops-42](/ops/decisions) 의 pre-push guard (컴포넌트 E) 는 **이 Mac mini 의 로컬 git 훅**이다. `axe guard install` 로 frame·hive·blueprint·stream·magnet·index + axe-cli(`~/.axe/bin`) 에 설치 — `git push origin main` 직접을 기계적으로 거부하고 `axe ship`(내부적으로 `AXE_SHIP=1` set, `axe` line ~7606) 만 통과. **강제의 경계가 있다**:

| 우회 벡터 | 사실 | 완화 |
|---|---|---|
| 다른 머신/CI 에서 같은 origin 으로 push | 로컬 훅이 없어 차단 안 됨 | 모든 개발 세션이 이 Mac mini 에서 돎 → 실 위협은 로컬 훅이 커버 |
| `git push --no-verify` | git 내재 동작 — 클라이언트에서 pre-push skip, 클라이언트측 차단 불가 | 운영자 단일·악의 아님 전제로 수용 |
| GitHub branch protection (서버측 정답) | **현 plan 불가** — private repo 의 branch protection 은 Pro/Team 필요 (`gh api repos/axelabs-ai/<svc>/branches/main/protection` → 403 "Upgrade to GitHub Pro") | plan upgrade 시 require-PR / restrict-push 로 권위 백스톱 추가 |

**범위**: guard 는 **axe-ship 거버넌스 대상 한정** (위 6 서비스 + CLI). artemis/blurgram/vault/axelabs 등은 자체 배포 경로라 의도적으로 guard 밖 (universal 아님).

**설치 함정 — tracked `core.hooksPath`**: index 는 `core.hooksPath=.githooks` (추적 디렉터리, sqlx `pre-commit` 보유). guard install 이 거기에 `pre-push` 를 쓰면 **untracked 로 노출** → 세션이 `git add -A` 하면 운영자-로컬 강제 훅이 공유 repo 에 커밋되어 clone/CI 의 정상 push 까지 잘못 차단한다. 2026-06-05 `~/index/.git/info/exclude` 로 차단 (비전파·tree 무변·훅 실행엔 무영향). 나머지 6 repo 는 `.git/hooks`(git 미추적)라 무관. CLI 일반화 = [B-axe-guard-hookspath-exclude](/ops/backlog).

## SSH 세션은 GUI login keychain 에 못 쓴다 — vault 비밀 주입의 keychain 함정 (2026-06-09)

이 Mac mini 의 Claude Code 세션은 **SSH(loopback) 위에서** 돌고 운영자는 Windows 에서 `ssh axe@100.127.210.30` (Tailscale) 로 접속한다. macOS 는 **SSH 세션이 GUI login keychain 에 쓰는 것을 거부**한다 ("User interaction is not allowed"). 그래서 vault 에 비밀을 *넣는* keychain 의존 경로 — `axe vault unlock` (keychain-cache crash), `axe secret push/pull/check` (`_vault_env` 가 `security find-generic-password -s axe.vault.session` 으로 keychain 세션만 읽음 → "vault session not found") — 이 전부 SSH 에서 실패한다. **현 워크어라운드** = keychain-free raw-bw (운영자가 자기 셸에서 `NODE_EXTRA_CA_CERTS` + 단독 줄 `bw unlock --raw` + raw `bw create/edit`, [D-ops-44](/ops/decisions) / [/architecture/secrets](/architecture/secrets#ssh-환경에서-vault-비밀-주입-keychain-free-raw-bw)). **더 깊은 격차** = `_vault_env` 가 **keychain 세션만** 읽고 env-session(`BW_SESSION`/stdin) 폴백이 없다는 것 — 그래서 SSH 컨텍스트가 `axe secret *` 의 1급 경로가 못 되고 매번 raw-bw 로 우회해야 한다. 이 함정을 없애는 fix 후보 = `axe secret put --stdin-session` 또는 `_vault_env` 의 env-session 폴백 (있으면 SSH 에서도 `axe secret push` 가 그대로 동작). 비밀 주입과 달리 **배포(`axe ship`/`secret pull`) 는 keychain 세션이 필요** — SSH 에선 `security unlock-keychain` headless unlock 후 `axe vault unlock` 으로 채운다. (전조: 이 keychain partition 격리 자체는 [realchoice D-day 함정 #5](#realchoice-d-day-첫-실행--6-함정-2026-05-25-발견) 에서 customer 측으로 먼저 관측됨 — 본 항목은 운영자 macmini 의 SSH 세션 + 비밀 *주입* 축.)

## OIDC 발행자가 자기 토큰을 401 (issuer ≠ resource server)

2026-06-04. D-axe-idp-1 후속. **Blueprint 가 플랫폼 토큰을 *발행*하면서 자기 MCP 는 그 토큰을 *거부*** 했다. `axe login` 토큰은 frame·hive·index·cortex·matrix 에선 동작하나 `https://axe.axelabs.ai/blueprint/mcp` 에선 **401 (`unknown_kid`)**.

**근본 원인**: trust-migration 작업이 frame·hive·cortex·index·matrix **5개**만 대상으로 잡고 **Blueprint 자체 MCP 를 빠뜨렸다** — "issuer 가 곧 resource server" 가 자명해 보여 목록에서 누락. Blueprint MCP (`blueprint_mcp/auth_oidc.py`) 는 Microsoft Entra access_token 만 검증 (`verify_microsoft_access_token`) → 플랫폼 토큰의 `kid` (= Blueprint OIDC 서명키) 가 Microsoft JWKS 에 없어 `unknown_kid` → 401.

**진단 단서** (같은 토큰을 두 서비스에 던져 비교):
- `blueprint/mcp` → `401 {"code":"UNAUTHORIZED","message":"unknown_kid: <kid>"}` (Microsoft JWKS 에서 못 찾음)
- `frame/mcp` → `401 {"code":"TOKEN_EXPIRED"}` (= **iss 분기·서명검증을 통과**하고 exp 만 걸림 → frame 경로는 정상)
- `unknown_kid` vs `token_expired` 의 차이가 "이 서비스는 Blueprint issuer 분기가 아예 없다" 를 가리킨다.

**Fix**: frame `auth_blueprint.py` + `http_server.py` iss-dispatch 를 Blueprint MCP 에 미러 (`mcp/src/blueprint_mcp/auth_blueprint.py` 신규 + `BLUEPRINT_ISSUER=https://blueprint.axellc.com` compose env). forged-iss/bad-sig → 401 검증 (unverified iss-peek 가 auth 우회 안 함). 설계: [/architecture/platform-identity](/architecture/platform-identity).

**교훈**: **OP 를 세울 때 그 OP 자신의 MCP 도 resource-server 목록의 한 행이다.** 발행자라는 사실이 자동 신뢰를 주지 않는다 — 토큰 검증은 issuer 든 아니든 동일하게 명시 배선해야 한다.

**잔여 (별개)**: `axe-cli` 의 blueprint **local** 엔드포인트 경로가 틀림 — `:3151/mcp` → 404 (proxy 는 `/blueprint/mcp` 서빙). public 은 정상. backlog `B-axe-cli-blueprint-local-path`.

## Cloudflare Universal SSL 1-level

2026-05-26, D-ops-39. 무료 plan 의 `*.axelabs.ai` Universal SSL cert 가 **1단 서브도메인만 cover** 하는 함정. zone 안에 2단 hostname (e.g. `ssh.axe.axelabs.ai`) 을 만들면 edge 가 SAN 미일치 → default cert fallback → 클라이언트 TLS handshake 실패.

| 환경 | 증상 |
|---|---|
| Windows (Schannel) | `SEC_E_ILLEGAL_MESSAGE (0x80090326)` — `cloudflared access login` 시 `failed to get app info: remote error: tls: handshake failure` |
| macOS (LibreSSL/curl) | `sslv3 alert handshake failure` |
| 브라우저 (Chrome/Edge) | `ERR_SSL_VERSION_OR_CIPHER_MISMATCH` |

진단 분기점: **`cloudflared --version` 최신 + 시스템 시간 OK + 브라우저/curl/cloudflared 3개 클라이언트 모두 동일 실패** = 서버측 cert 단정 (90%+ confidence). 동일 zone 안에서 1단 host (e.g. `axe.axelabs.ai`) 는 정상 동작하는 것도 단서.

**컨벤션 (D-ops-39)**: HTTPS 노출되는 모든 hostname = `{name}.axelabs.ai` 의 1단. flat-hostname (예: `ssh-axe`) 또는 path under apex (`axe.axelabs.ai/frame`). 룰 본문 [/architecture/domains#함정--universal-ssl-wildcard-의-1-level-한계-d-ops-39](/architecture/domains#함정--universal-ssl-wildcard-의-1-level-한계-d-ops-39).

**구체 사례 — `ssh.axe.axelabs.ai` (강태훈 Windows, 2026-05-25)**:
- 강태훈이 `cloudflared access login https://ssh.axe.axelabs.ai` 시도 → 위 Windows 증상.
- axelabs.ai chat 의 MAX agent 가 클라이언트 4단계 (cloudflared version / 시스템 시간 / TLS inspection / hostname 정확성) 진단 후 서버측 단정.
- 2026-05-26 운영자가 `ssh-axe.axelabs.ai` 신규 등록 (DNS CNAME → 동일 tunnel `d8efecdd`, ingress 규칙 clone, Access app `b903d8cd` self_hosted_domains 추가). 검증: `curl -v https://ssh-axe.axelabs.ai/` → 302 to `axellc.cloudflareaccess.com`.

**옛 hostname 완전 삭제 (2026-05-26 같은 날 후속)**: 강태훈이 신규 hostname 으로 1차 재시도했으나 Microsoft SSO 통과 후 callback 이 옛 `ssh.axe.axelabs.ai` 로 떨어져 동일 cert 오류 재발. 추가 진단:
- Access app 의 primary `domain` 필드가 여전히 `ssh.axe.axelabs.ai` 였음 → post-auth callback / App Launcher 흐름이 primary 를 우선시. 1차 fix: `domain` 을 `ssh-axe.axelabs.ai` 로 PUT swap.
- 2차 fix (확정): 옛 hostname 흔적 3 layer 모두 제거 — (a) DNS CNAME `ssh.axe.axelabs.ai` + `*.axe.axelabs.ai` 와일드카드 삭제, (b) axelabs tunnel (`d8efecdd`) ingress 규칙 제거, (c) Access app `self_hosted_domains` / `destinations` 에서 제거. 검증: `dig ssh.axe.axelabs.ai` → NXDOMAIN. 클라이언트 측 cache (브라우저 쿠키 + `%USERPROFILE%\.cloudflared\` token) 정리 후 `cloudflared access login https://ssh-axe.axelabs.ai` 재시도 안내.

**거부된 대안** ($10/cert/월 ACM, zone delegation, Tailscale 우회, 클라이언트 cert bypass): D-ops-39 본문 참조.

## Microsoft 자사 앱 간 consent preauthorization 정책 — az CLI Mail.Send 영구 차단 (2026-05-26)

> 운영자가 az CLI 로 `/me/sendMail` 호출하려고 시도 → `403 ErrorAccessDenied`. 명시적 scope (`--scope https://graph.microsoft.com/Mail.Send`) 요청 시 `AADSTS65002: Consent between first party application '04b07795-8ddb-461a-bbee-02f9e1bf7b46' and first party resource '00000003-0000-0000-c000-000000000000' must be configured via preauthorization`.

az CLI 의 client app id `04b07795` (Microsoft Azure CLI 자체) 가 Microsoft Graph (`00000003`) 의 Mail.Send scope 받으려면 Microsoft 가 preauthorization 등록해야 함. 자사 앱 간에도 cross-app consent 안 됨. **개별 tenant 의 admin consent 로 우회 불가**.

**영향**: az CLI 경유 mail/chat send 영구 불가. 우회 = (a) [`/api/admin/broadcast-dm`](/ops/runbook/operator-broadcast) (Blueprint REST, 본 use case 의 정공법), (b) Outlook 수동, (c) custom Azure app 신설 (Mail.Send delegated/application + admin consent + client_id/secret vault 저장, 30분+ setup — 사용 빈도 높을 시 [B-axe-mail-send-cli](/ops/backlog) 진행).

**왜 운영자가 함정에 들어갔나**: Blueprint 가 `sendEmail()` 함수 + Mail.Send permission 둘 다 보유 — 자연스레 "외부 connector 에서도 호출 가능" 가정. 실제는 graph_* tool 32+ 중 send 계열은 `blueprint-graph` 내부 MCP 에만 등록, 외부 7cb41f76 connector 는 read-only 격리 (의도). 외부에서 send 가 필요하면 admin REST (`broadcast-dm` 등) 별도 경로.

## D-bp-mcp-calendar-2 send-as 도입 시 8개 함정 (2026-05-26)

> Soohun 의 "ai 계정으로 다른 사용자 캘린더 쓸 수 있냐" 질문 → 1시간 안에 7개 별개 차단점 통과. 각각 다음 calendar/admin write feature 도입 시 동일 패턴.

### Blueprint Azure App ID 혼동

Blueprint 가 **별개의 Azure App 2개** 보유:
- `2b222356-1c36-48e0-96a3-2c5e0ecbf937` = **Blueprint Next.js app** (NextAuth Azure AD provider, `getMsalApp()` → `getAppOnlyClient()` 가 사용). DB AppSetting `azure_ad_client_id`.
- `482598f7-540c-462c-9dfd-b957651eb804` = **Blueprint MCP custom connector** (Claude → MCP OAuth용). CLAUDE.md 의 "Client ID" 항목.

내부 API route 가 app-only token 발급할 때 audience = Next.js app (`2b222356`). Application permission + admin consent **모두 `2b222356`** 에 적용해야 함. MCP app `482598f7` 에 consent 하면 무관 → 403 ErrorAccessDenied 계속 반환. 본 세션 1회 잘못 적용 → MSAL token 디코드해서 `aud` 확인하고서야 발견.

### Blueprint User.id ≠ Microsoft Entra oid

Blueprint `User.id` = Prisma 가 생성한 cuid (e.g. `e1c51fa2-0102-43ed-...`). NextAuth Azure AD callback 에서 Entra `oid` 를 별도 컬럼에 저장하지 않음 → `/users/{User.id}/events` 호출 시 Graph 가 `ErrorInvalidUser 404`. **Graph `/users/{key}` 는 oid 또는 UPN/email 받음** — UPN 사용으로 우회. Route 가 `target.email` 을 path 에 인코딩하도록 fix. 향후 D-bp-mcp-calendar-3 이상에서 직접 oid 필요한 endpoint 도입 시 `User` 에 `oid` 컬럼 추가 검토.

### MSAL `acquireTokenByClientCredential` 토큰 캐시

`@azure/msal-node` 의 ConfidentialClientApplication 은 client-credentials flow 토큰을 in-memory 캐시 (default TTL ~1시간). admin consent 직후에도 캐시된 옛 토큰 (consent 이전 발급, `roles` claim 누락) 이 계속 반환됨 → Graph 403 지속. **container 재시작 또는 `skipCache: true` 옵션으로 강제 refresh**. MSAL `.default` scope 가 "현재 consent 된 모든 perm" 의미라 cache 무효화 트리거 없음 (admin consent 가 MSAL instance 에 signal 안 보냄). 본 세션은 `docker restart blueprint-app-green` 으로 우회.

### Global Admin = soohun.kang 단독 (ai@axellc.com 은 admin 아님)

운영자 가정: "`ai@axellc.com` 으로 az 로그인 되어 있고 관리자 권한이므로 tenant 작업 가능". 실제: AXE 테넌트의 **Microsoft Entra Global Administrator role** = `soohun.kang@axellc.com` 단독. `ai@axellc.com` 은 일반 사용자. `Authorization_RequestDenied` 에러 시 `userObjectId` 필드 디코드 (Entra oid lookup) 로 실제 호출 identity 확인.

**참고**: Blueprint 자체 admin role (`User.role === "admin"`) 과 Azure AD Global Admin 은 별개. ai@axellc.com 은 Blueprint admin (Blueprint MCP send-as 호출 가능), 그러나 Azure AD admin 작업 (Application permission grant 등) 불가.

### `az login` 무구독 테넌트

M365-only 테넌트는 Azure 구독 0개. `az login --tenant <id>` 만으로는 active context 가 직전 계정에 머무름 (No subscriptions 메시지 후 무시). **`--allow-no-subscriptions` flag 필수**. 확인: `az account show` 로 active upn 검증.

### Claude.app `/dev/ptmx` fd leak

Claude 데스크탑 앱이 새 채팅/대화 열 때마다 `/dev/ptmx` open, close 안 함. 누적되면 `kern.tty.ptmx_max=511` (macOS 하드 한도) 도달 → `forkpty: Device not configured` (ENXIO) → 신규 터미널·subprocess PTY 할당 불가. **userspace 측 zsh 좀비 (Claude Code subprocess 누적 82 → 정리해도 무효)** 가 아니라 Claude.app 본체 fd leak. `lsof /dev/ptmx` 로 holder 확인 가능.

해결: Claude.app 종료 후 재실행 (fd 자동 release). sudo 로 `kern.tty.ptmx_max` raise = "Invalid argument" (macOS 가 511 이상 거부). Anthropic 리포트 대상 (`B-claudeapp-fd-leak-report` backlog).

**2026-06-04 재발 확인** (`lsof /dev/ptmx`: Claude.app PID 1개가 510/511 점유, 여유 0). 이때 신규 PTY 차단뿐 아니라 **`sudo` 자체가 막힌다** — sudoers `Defaults use_pty` 탓에 `sudo: unable to allocate pty: Device not configured`. **세션을 안 끊고 root 작업하는 우회법** = `osascript -e 'do shell script "…" with administrator privileges'` (AuthorizationServices GUI 인증 → pty 불요, sudo 미경유). netheal 데몬(D-matrix-4) 설치를 이 방법으로 완료. 단 GUI 세션 필요 (GRD/콘솔 OK, 순수 SSH 불가). 항구적 회수는 여전히 Claude.app 재시작.

### FastMCP tool 의 `Image | dict` union 반환 어노테이션

FastMCP tool registration 이 return type annotation 을 pydantic 으로 schema generate. `mcp.server.fastmcp.utilities.types.Image` 가 union (`Image | dict`) 안에 있으면 `PydanticSchemaGenerationError: Unable to generate pydantic-core schema for <class 'Image'>` → MCP 서버 startup 실패 → blue/green health check 60s timeout → swap 자동 거부. **return annotation 생략 또는 `Any`** 로 우회. 본 세션 `get_teams_hosted_content` 가 1회 발현 후 commit `3c7ae254` 로 fix.

### Pre-existing axelabs-docs `{#anchor}` MDX 3 acorn parse fail

별개 함정 (calendar 와 무관) 이지만 본 세션 docs ship 차단했음. `## Heading {#explicit-anchor}` 문법이 Nextra (MDX 3) 의 acorn 파서를 깨뜨림 → `Could not parse expression with acorn` → `npm run build` 실패 → `axe ship docs` 의 docker rebuild 차단. **MDX 3 에서 `{#...}` 명시 anchor 미지원**: 헤딩 텍스트를 슬러그와 일치시키도록 변경 (github-slugger 자동 ID) 하고 inbound 링크 그대로 유지. 운영자 별도 commit 으로 동시 fix 됨 (race condition 으로 commit `941196f`).

## realchoice D-day 첫 실행 — 6 함정 (2026-05-25 발견)

> Truvia 측 RE^6 의 D-day 즉시 시작 피벗 후 운영자가 `axe onboard realchoice --apply` 실행. **step 1-13 ✅ + step 14 차단**. 본 섹션은 분석적 기록 (실행 항목은 [B-onboard-d-day-traps-2026-05-25](/ops/backlog)).

| # | 함정 | 본질 | 영구 fix 후보 |
|---|---|---|---|
| 1 | Tailscale short host alias (`realchoice-macmini`) macOS resolver 미해석 → ssh fail | macOS resolver 는 magicDNS short alias 자동 처리 X. `~/.ssh/config` 의 Host alias + HostName FQDN 매핑 필수. axe CLI 가 short alias 로 ssh 호출 | partner/macmini-prep 함정 표 + `axe onboard` 가 자동으로 `~/.ssh/config` 추가 또는 ssh 명령에 `-o "Host alias=FQDN"` 사용 |
| 2 | SSH non-login shell PATH 에 `/usr/local/bin` 누락 → `docker not found` | macOS 의 zsh non-login 은 `~/.zshrc` 안 봄. `~/.zshenv` 만 봄. Docker Desktop 의 symlink (`/usr/local/bin/docker`) 가 default PATH 밖. Truvia 측 `~/.zshenv` 에 `export PATH=/usr/local/bin:/opt/homebrew/bin:$PATH` 추가 필요 | partner/macmini-prep 의 §5 Docker 섹션에 `~/.zshenv` 명시 (즉시 갱신 필요) |
| 3 | TXT + CNAME 같은 name 공존 시 `axe onboard` step 5 의 `_cf_dns_find(zone, name)` 가 type filter 없어 거절 | CloudFlare API 는 type filter 미적용 시 모든 record 반환. axe CLI 코드가 "exists" 로 단정 → conflict 처리. RFC 측면 TXT+CNAME 공존 OK | axe CLI `_cf_dns_find(zone, name, record_type)` 시그니처 변경 + onboard step 5 가 `record_type="CNAME"` 명시 |
| 4 | Login keychain locked + SSH non-interactive → `security add-generic-password` exit 36 (errSecAuthFailed) | macOS GUI session 의 keychain unlock 이 SSH non-interactive session 의 securityd partition 으로 propagate 안 됨 | 함정 5 가 본질적 fix (vault SOT 이전) |
| 5 | **macOS keychain partition 격리 — SSH non-interactive 의 securityd 가 GUI session 과 별도 partition** | Truvia 측 GUI 로그인 + timeout 10h 연장 했지만 SSH non-interactive session 영향 0. 즉 `axe onboard` 의 step 12 (secret generation) 가 SSH 으로 호출하면 fundamental 차단. **본 D-day 의 핵심 함정**. 즉시 우회 = Truvia 가 본인 SSH session 에서 직접 명령 실행 (operator → customer 권한 위임 패턴) | (a) `start-frame.sh` 를 customer launchd job 으로 등록 → console session 의 keychain access. (b) **secret SOT 를 keychain 에서 vault 로 이전** (D-ops-17 manifest pattern 확장). bw CLI 는 SSH session 에서도 작동 |
| 6 | **`start-frame.sh` wrapper 가 SSH non-interactive 에서 `security find -w` (value fetch) 시도 → ACL 차단 → FATAL: FRAME_JWT_SECRET empty** | 함정 5 의 구체적 발현. wrapper 가 keychain value 꺼내야 frame postgres + frame-mcp-blue 부팅 가능. SSH 으로 호출 시 차단. axe CLI line 2588 의 step 12 fix (`-w` 제거, metadata-only) 는 step 12 통과시키나 step 14 wrapper 의 fetch 는 동일 차단 | 함정 5 와 동일 영구 fix |

**즉시 우회 (본 세션 적용)**:
- 함정 1: `~/.ssh/config` 신설 (Host alias + HostName FQDN)
- 함정 2: Truvia 측 `~/.zshenv` PATH 추가
- 함정 3: Microsoft verify 완료 후 TXT 제거 + axe CLI 재실행
- 함정 4-5: Truvia 가 본인 SSH session 에서 `security add-generic-password` 직접 실행
- 함정 6: ⏳ Truvia 회신 대기 (옵션 A = 본인 SSH session 에서 `start-frame.sh up -d` 직접 / 옵션 B = `security set-generic-password-partition-list` ACL 변경)

**영구 fix 적용 (2026-05-26, B-customer-deploy-generalization Phase 1 완료)**:
- 함정 4·5·6 → **vault SoT 이전**. axe CLI 의 `_deploy_service_customer` + 새 wrapper 3종 (`start-{frame,blueprint,hive}.sh`) 이 customer 측 `bw get password` 으로 secret fetch. SSH non-interactive 의 keychain partition ACL 회피 (bw 는 파일 기반 `~/.bw-session` 으로 BW_SESSION 획득 → securityd 무관). customer 측 1회 부트스트랩 = `brew install bitwarden-cli` + `bw-bootstrap.sh https://<vault-url> <email>` (interactive). 본 변경 후 함정 4·5·6 = **다음 customer 에서 재발 0**.
- 함정 10 (env_file `$` literal) → `escape_dollar: true` flag 자동 처리. INGEST_MANIFEST_TEMPLATE 의 OAuth secrets 에 빌트인.
- 함정 7 (docker-compose default path hardcode) → `image_override` 슬롯으로 customers.yaml 에서 override 가능 (R4). compose 본체 변수화는 service repo 측 별도 PR.
- 함정 8 (axe onboard step 14 non-idempotent) → 이미 axe CLI line 2720+ 에 `docker ps` 사전 검사 + skip if running 패치 적용 (5/25). 신규 `_deploy_service_customer` 도 동일 패턴 적용 필요 (TODO).

**미해소**:
- 함정 1·2·3 = docs 측 갱신 필요 (partner/macmini-prep 의 함정 표 + axe CLI `_cf_dns_find` 시그니처 변경).
- 함정 9 (frame-proxy stale archive) → `/Users/axe/.axe/frame-proxy/` 5/24 복원 ✅. axe CLI 가 정상 경로 참조.

## 1-shot onboard 갭 — realchoice (2026-05-23 분석)

> **목표**: D-day 에 운영자가 **vault master password 1 회** 입력만으로 신규 customer (realchoice 등) 전체 배포 완료. 현재 6 개 수동 touchpoint 가 남음. [/ops/runbook/customer-onboarding#d-day-tldr--운영자-수동-touchpoints](/ops/runbook/customer-onboarding) 가 SSOT.

> ⚠️ **갱신 (2026-06-06)**: realchoice 는 2026-05-25 **sovereignty self-deploy 로 LIVE 완료** (`customers.yaml` 에서 `services:` 의도 제거). 본 섹션의 realchoice 예시는 *역사적* — 잔여 갭은 `services:` 매니페스트를 선언하는 **신규** customer 에만 적용되고, realchoice 자체엔 `axe deploy {svc} realchoice` 가 미적용된다 (→ [/ops/runbook/customer-onboarding](/ops/runbook/customer-onboarding) sovereignty caveat).

| # | 갭 | 현재 상태 | 닫는 작업 |
|---|---|---|---|
| 1 | `axe customers add {customer}` = stub (line 560-561) | customers.yaml 의 customer 메타블록 + services 슬롯 모두 운영자 수동 편집 | [B-onboard-customers-add](/ops/backlog) |
| 2 | customer IT 회신 8 개 값 → vault 로 운영자 수동 push × 3 + customers.yaml 수동 paste × 4 (tenant_id + 3 client_id) | 안전채널 받은 값 운영자 손에서 vault 로 이동 | [B-onboard-azure-pack](/ops/backlog) — `axe customer ingest {customer} pack.json` 으로 (a) yaml fill + (b) vault push 묶음 |
| 3 | `services:` 섹션이 axe customer 만 등재 (realchoice services 슬롯 부재) | `axe secret push --customer realchoice` 가 manifest lookup 실패 | [B-onboard-customers-add](/ops/backlog) 결과물의 일부 |
| 4 | ~~`axe deploy hive {customer}` subcommand 부재~~ ✅ **해소 (2026-06-06)** | `axe deploy` choices = frame / blueprint / blueprint-mcp / **hive / matrix** (`cmd_deploy_hive` customer-path live, `.axe/bin/axe`) | [B-onboard-hive-deploy](/ops/backlog) |
| 5 | `cmd_deploy_blueprint` docstring 자기 명시: "SSO (Azure AD) 미설정 — Phase 3 추가 작업 필요" | Blueprint 컨테이너는 부트되지만 첫 SSO 로그인 시 secret 부재로 실패. 운영자가 별도로 customer Keychain 또는 vault → .env 채워야 함 | [B-onboard-bp-sso](/ops/backlog) |
| 6 | Cloudflare API token vault 등재 = first-onboard chicken-and-egg | 첫 onboard 직전 1 회 `axe secret push` 필요 (현재 docs 부재) | [B-onboard-cf-token-doc](/ops/backlog) — secrets.mdx 의 bootstrap 섹션에 명시 1 줄 |

**해소 후 D-day 흐름** (목표):
```
# 0. vault unlock — master password 1 회
export BW_SESSION="$(bw unlock --raw)" && security add-generic-password ...

# 1. customer IT 회신 한 줄 ingest (yaml fill + vault push 묶음)
axe customer ingest realchoice ~/Downloads/realchoice-azure-pack.json

# 2. 모든 stack 묶음 배포 (frame + blueprint + hive + vault)
axe deploy all realchoice --apply
```

**현재 drift 발견** (본 sweep, 2026-05-23):
- ~~customer-onboarding.mdx 의 D-7 step 3-5 가 `/Users/axe/.axe/tunnels/axelabs/config.yml` 편집 + `docker restart axelabs-tunnel` 요구~~ → **정정 완료**. 실제 `axe onboard` 는 customer 별 독립 tunnel 을 customer macmini 에 생성 (`_render_cloudflared_config` `/Users/{ssh_user}/.cloudflared/config.yml`). 중앙 tunnel 편집 의무 사라짐.
- ~~`axelabs-bootstrap.sh` + `realchoice_entra_id_setup_v3.md` 가 별도 안전채널 메시지로 전달되는 의존~~ → **정정 완료 ([B-onboard-bootstrap-publish](/ops/backlog#-done-최근-7일-archive-대기), 2026-05-23)**. 스크립트가 `https://docs.axelabs.ai/axelabs-bootstrap.sh` 의 raw 로 노출. partner/registration §Option A + macmini-prep + domain-prep §A/§B + handoff JSON pack 양식 + index 4-step 흐름으로 docs.axelabs.ai 만으로 customer IT 자력 완료 가능. **customer-facing 차단은 0**. 잔여 6 갭 (위 표) 은 모두 **운영자 측 자동화 (umbrella + ingest + hive deploy + bp sso + cf token)** — 운영자의 D-day 명령 수를 5→1 로 줄이는 것이 우선순위. customer 측에는 영향 없음.

## CLI 측 미구현 (axe CLI Phase 5 stub)

| 약속된 CLI | 실제 상태 | 우회 |
|---|---|---|
| `axe restore --customer X --tier local\|ring\|cold --target X --table X --apply` | argparse stub (`--tier`, `--target`, `--table`, `--apply` flag 없음) | restic 직접 호출 (각 runbook 의 갱신된 예시 참조) |
| `axe backup --status` / `axe backup --local --tag X` | `axe backup` subcommand 없음 — `/Users/axe/.axe/bin/axe-backup` shell script 가 매일 03:00 자동 | `restic snapshots` 직접 |
| `axe onboard --skip-azure` | `--skip-azure` flag 없음 (`--skip-frame` 만 있음) | onboard 가 Azure 측 변경 안 함 — flag 없어도 무방 |
| `axe health &lt;target&gt; --customer X` | `--customer` flag 없음 (positional 만) | `axe health frame` 처럼 사용 |
| `axe secret status --customer X` | `--customer` flag 없음 | 운영자 콘솔 dashboard 에서 확인 |
| `axe ship` (release-gate) | ✅ 구현됨 (D-ops-16) | — |
| `axe secret check/pull/push/rotate` (manifest 기반) | ✅ 구현됨 (D-ops-17). pull merge-mode (D-ops-18) | — |
| `axe deploy blueprint-mcp` (blue/green swap) | ✅ 구현됨 (D-bp-mcp-2, 2026-05-21) — frame `cmd_deploy(frame)` 1:1 미러 | — |
| `axe ship blueprint` 안에서 mcp swap 자동 호출 | ✅ 구현됨 (D-bp-mcp-2 후속, 2026-05-21) — cmd_blueprint_upgrade 직후 cmd_deploy_blueprint_mcp wire-up | — |

→ Phase 5 (D) 작업 항목으로 CLI 완성 예정. 그때까지 runbook 의 명령어는 "현재 형식" 으로 사용.

## 매니페스트 / vault 측 미해결

| 항목 | 현재 상태 | 후속 |
|---|---|---|
| 매니페스트 non-secret config 흡수 결정 (Option A: 매니페스트 확장 / B: merge-mode 만 / C: customers.yaml 통합) | merge-mode pull (D-ops-18) 로 즉시 위험 X. blueprint .env 의 AZURE_AD_CLIENT_ID 등 9개는 hand-maintain | 운영 안정 후 정책 결정 |
| `axe-cli@axellc.com` Vaultwarden service account | 미생성. 현재 모든 bw 호출이 운영자 개인 token | D-ops-17 Phase 6 |
| `cmd_blueprint_upgrade` Keychain → vault 통합 | 현재 Keychain inject (line 698) + env_file 동시 사용. 두 출처 sync 책임 운영자 | vault 단일 출처로 통합 |
| `CLAUDE_CODE_OAUTH_TOKEN` 회전 | 2026-05-21 transcript 노출. 사용자 보류 (후순위) | Anthropic console 새 토큰 발급 → `axe secret rotate` |
| hive `HIVE_MAILER_*` 매니페스트 미등재 | `.env.local` 에 hand-maintain 중 (D-hive-23) | customers.yaml hive.secrets[] 에 추가 |
| hive postgres `HIVE_DB_PASSWORD` substitution (compose 변수) | volume reset 시점 default `hive_dev` 로 fall back 위험. 현재 data dir 에 vault 값 이미 init | postgres 에도 env_file 도입 또는 `.env` 명시 |
| **bw CLI `[Encrypt service] MAC comparison failed. ... Failed to decrypt user key with stretched master key`** — 재발성 (5/22 `.broken.1779431724` + 5/26 `.broken.1779783301`). KDF 원인 **아님** (ai@axellc.com 이미 Argon2id). | **Root cause 확정** (5/26 검증): bw CLI 의 local data.json 의 cached `cryptoSymmetricKey` (wrapped user key) 가 server-side patch deploy 후 bw `sync` 시점에 stale 상태로 저장됨. `bw unlock` 은 이 캐시를 invalidate 안 함 → 매 unlock 마다 stale wrapped user key 로 decrypt 시도 → MAC fail. axe Vaultwarden 의 빈번한 fork patch deploy (axe.2, axe.3, ...) 가 트리거. | **즉시 복구 (확정)**: `mv "~/Library/Application Support/Bitwarden CLI" "~/Library/Application Support/Bitwarden CLI.broken.$(date +%s)" && bw config server https://axe.axelabs.ai/vault && bw login ai@axellc.com` (fresh login). 약 1분. → [B-bw-cache-stale-autoheal](/ops/backlog) 영구 fix |

## launchd 측 미구현

| 약속된 launchd | 실제 상태 |
|---|---|
| `com.axe.secret-check` (매일 09:00) | 미구현. Vault item 의 만료 메타 + 운영자 콘솔 dashboard 에서 수동 확인 |
| `com.axe.health-check` (매분) | 미구현. `com.axe.console.refresh` (매시) 가 운영자 콘솔에 health 표시. 매분 알림은 향후 추가 |
| `axe-health-monitor` 바이너리 | 미구현 |

대안: 운영자 콘솔 (`https://admin.axelabs.ai`) 이 매시 rebuild 되며 health 표시. 즉시 알림이 필요하면 `osascript` 또는 Slack webhook 으로 임시 wrapper 작성 가능.

## Docs 측 내부 불일치 (정리 진행 중)

| 항목 | 현재 상태 | 정리 계획 |
|---|---|---|
| `partner/registration.mdx` 신모델 (Web platform + secret + App ID URI + mcp.access) | 작성됨 | axe customer 는 이미 신모델로 마이그됨. realchoice 도 6월 onboard 전 신모델로 적용 |
| `realchoice_entra_id_setup_v3.md` | ✅ 작성 완료 (2026-05-21) | 발송 (5/29 마감) |
| `axe_frame_mcp_setup.md` (구모델 기록) | historical | 본인 실작업 기록 — 사실 정확성 위해 보존 |
| `frame/docs/ops/onboarding-operator.md §0` (구모델 Azure 등록) | obsolete | registration.mdx 로 통합 → 향후 cross-link |
| `customers.yaml.axe.sso.apps.blueprint_mcp` | ✅ 추가됨 (D-bp-mcp-1) | — |
| frame ahead commits 의 docs drift (auth_oidc.py, cli.py, alembic, Dockerfile 등) | operator hive integration 세션 작업분 | operator 의 axe ship frame 사이클에 함께 |

## 정확한 tool count

| 서비스 | docs 표기 | 실제 (코드 기준) | 비고 |
|---|---|---|---|
| frame | ~44 (수정됨) | 44 (`grep -c '@mcp.tool' src/frame/mcp/server.py`) | OK |
| stream | 28 (수정됨) | 28 (admin=7, sales=5, inventory=4, settlement=3, health=3, bridge=2, signals=3, meta=1) | OK |
| magnet | 39+ headline | 51+ 표 합산, 자기 진단 1 포함 시 ~62 데코레이터 | 표 합산이 실제와 다름 — magnet 측 통합 daemon 의 자체 보고가 39 |

magnet 의 39 vs 51+ 차이는 magnet 측 `mcp/server.py` 의 importlib 흡수 시 일부 중복/내부 도구 제외. magnet team 정리 후 docs 갱신.

## hive 골든테스트 ↔ 라이브 데이터 결합 (2026-06-04)

`tests/payroll/test_golden_axec_2026_04.py` 가 라이브 `axec` DB 의 직원 종료상태에 의존 (자체 시드 없이 `compute_period` 실행). 골든 픽스처 (`golden_axec_2026_04.json`) 가 강수훈 (AXEC-001) 을 `terminated 2026-04-01` 로 인코딩 → CI 통과를 위해 **실 직원행을 수동 (out-of-band, audit_log empty-actor) UPDATE** 하게 만든 것이 강수훈 axec 종료의 근본원인 (2026-06-04 agent 조사·DB 검증). 같은 압력으로 `axev/AXEV-003` 강수훈도 수동 종료됐으나 그는 **AXEV 파트너 직급** — 정합화는 backlog [B-hive-axev-003-terminated](/ops/backlog). 구조적 해소 (테스트를 트랜잭션 내 자체 시드 또는 전용 test entity 로 분리) 는 backlog [B-hive-seed-integrity](/ops/backlog). 가드: "terminated 인데 active membership/open employment_record" 면 fail 하는 invariant 테스트.

## gh pr create ↔ repo redirect 함정 (origin=`soohunkang/*` → `axelabs-ai/*`) (2026-06-04)

로컬 git remote `origin` 이 `soohunkang/<repo>` (구 이름) 인데 GitHub 가 `axelabs-ai/<repo>` 로 **redirect** (repo transfer — fork 아님: `gh repo view soohunkang/hive` → `isFork:false, parent:null, nameWithOwner:axelabs-ai/hive`). 이 상태에서:

- ❌ `gh pr create … --head soohunkang:<branch>` (fork 스타일 head) → 존재하지 않는 fork owner 해석 시도 → GraphQL `Something went wrong` 500 (무한 반복). plain `gh pr create` 도 redirect/fork-resolution GraphQL 에서 간헐 500.
- ✅ **REST + plain same-repo head**: `gh api --method POST repos/axelabs-ai/<repo>/pulls -f head="<branch>" -f base="main" -f title=… -f body=…`. 머지도 `gh api --method PUT …/pulls/<n>/merge -f merge_method=squash`.
- `git push origin` 은 redirect 통과(axelabs-ai 에 정상 반영). **진단 순서**: GitHub status green + `gh api rate_limit` 정상이면 장애 아님 → head 형식/redirect 의심하고 REST 로 우회. 모든 세션이 동일 origin 사용 → 공통 함정 (2026-06-04 hive PR #5 에서 ~6회 헛시도 후 규명).

## 운영 자동화 미완성

| 항목 | 현재 |
|---|---|
| 분기 restore drill (`com.axe.restore-drill`) | launchd 등록 + plist 존재. 첫 실제 drill 시기 (Jul 15) 까지 검증 |
| Cold SSD rotation | tooling ready, **SSD 자체 미구매** (operator 작업) |
| Realchoice ring backup | 양방향 SSH 검증 완료 (2026-05-15). realchoice onboard (6/1) 후 첫 sync 시작 |
| **mysrt-postgres backup 정책 미명시** | `mysrt-postgres` 컨테이너 운영 중, axe-backup 범위 밖. mysrt 가 SRT 폴링 (외부 SOT 가 source-of-truth 가능성) 이라 의도적 제외일 수도 / 누락일 수도. `architecture/backup.mdx` 에 "백업 대상에서 의도적 제외" 명시 또는 추가 결정. 검출 2026-05-21. |

## Blueprint 측 미완 (2026-05-21 세션 발견)

| 항목 | 현재 상태 | 후속 |
|---|---|---|
| **Blueprint MCP `get_session` + `list_messages` tool** | 9 read-only tool 중 Message 본문 외부 비공개 → agent transcript blind. 5분야 진단 (2026-05-21) 의 최대 빈 곳 | Stage 1 전 추가. PrismaClient member-scoped pattern |
| **`cmd_deploy_blueprint_mcp` edge probe URL 부정확** | `200 expected` 인데 cloudflared 가 `/blueprint/mcp/health` path 보존 + JWTAuthMiddleware 가 `Bearer` 인증 요구 → 실제 응답 401 (정상 도달). `axe deploy blueprint-mcp` 가 매 swap 에서 "⚠ edge not 200" 경고 출력 | URL 을 `/blueprint/mcp` (auth-required endpoint) 로 + expected `401` + `WWW-Authenticate: Bearer` 헤더 검증 |
| **`axe blueprint upgrade` active color resolve 오작동** | `_blueprint_active_color()` 가 stopped 컨테이너 metadata 를 alias 보유로 인식 → 실제 active 인 컨테이너 rebuild 시도 위험 (2026-05-21 회피: docker compose 직접 호출) | `docker inspect` 결과에 `State.Running == true` 필터 추가 |
| **Trinity scheduled reconcile 부재** | `src/lib/trinity-sync.ts:1-15` 가 사용자 클릭 trigger / `resolveLocalPath` self-heal 만. 6/16 row drift 가 사용자 trigger 까지 잔존 | cron 또는 launchd 일일 reconcile |
| **`/axe/personas` UI 부재** | API `src/app/api/personas/route.ts:11-19` 만, page 없음 | persona 자기 큐레이션 UI |
| **`/api/health` 단순 200** | 14줄, DB/Postgres/Graph upstream probe 없음 | upstream probe + Cloudflare health-gate 신뢰 회복 |
| **IC DATA-FIX mode** | SKILL.md:140-173 4-mode (INITIAL/APPEND/REVISION/FINALIZE) 만. 숫자 정정 시 강제 v-bump | DATA-FIX mode 추가 |
| **PARA dispatch UI** (Project 종결 시 Area/Resource 로 artifact 이관) | schema 부분 완료 ([PR #339](https://github.com/soohunkang/blueprint/pull/339) 의 `sourceWorkspaceId` / `sourceArtifactPath` / `copiedAt` 3 필드). [D-bp-entity-2](./decisions#d-bp-entity-2--para-dispatch-flow-sub-consensus) 정식 등재. UI 만 잔여 (PR 5 예정). 미결 3종: 분배 단위 (파일 vs 의미) / Area 인스턴스 정의 권한 (org-admin vs free) / 정비 트리거 우선순위 | Path B Spike (DB 변경 없이 단일 workspace 로 LLM 분배 정확도 검증 3-5일) → Path A 본구현 (Area/Resource UI + dispatch modal + archive search separation) |
| **Settings UI default entity dropdown** | `/api/user/default-entity` PATCH endpoint ([D-bp-entity-7](./decisions#d-bp-entity-7--userdefaultentity--사용자별-명시적-default-entity)) 있으나 UI 부재. 사용자가 직접 변경 못 함 — 운영자 SQL 또는 customers.yaml 순서 의존 | `/axe/settings/SettingsClient.tsx` 에 dropdown 한 줄 (~30 min) |
| **axe entity register 통합 명령** | hive `register-entity` + Blueprint `seed-entities.ts` 갱신 두 명령 분리. 부분 등록 함정 (한 시스템만 등록되고 다른 시스템 안 됨) 가능 | axe CLI `entity register <slug> --name ... --biz-no ...` subcommand. hive subprocess + Blueprint Entity row INSERT atomic |
| **blueprint-mcp + hive-mcp `/health` anon expose** | JWTAuthMiddleware 가 모든 path (/health 포함) Bearer 요구. frame-mcp 는 /health anon. axe CLI edge probe 가 401 expected 로 현재 workaround. frame 패턴 mirror 가 본질 fix | FastMCP middleware exclusion list 에 `/health` 추가 (blueprint-mcp + hive-mcp 각각). axe CLI expected 401 → 200 정정. mcp-server-checklist 에 항구화 |
| **Teams attachment unsupported contentType → LLM false-negative** | `src/lib/teams/attachments.ts:138` 의 unsupported-loop 가 `[unsupported contentType: X]` stub 만 LLM 에 넘김. LLM 은 stub 만 보고 "X 못 봤다" 그럴듯한 답 confabulate (실제 API 한계와 구분 불가). `messageReference` 1 종은 [PR #372](https://github.com/soohunkang/blueprint/pull/372) 에서 fix. `card` / `file` / 기타 contentType 미점검 | [B-bp-teams-attachment-contenttype-audit](/ops/backlog). production 관측 contentType enumerate + handler 추가 또는 placeholder 명확화. [feedback_bot_capability_gap_self_diagnosis](memory) |
| **Knowledge Layer 격차 — typed fact 부재** | ctx skill 이 markdown PKM 만 제공. Per-field citation / cross-functional query (frame typed × portfolio markdown join) / time-travel / 결정론적 충돌 해소 모두 불가능. 인프라는 dev-co level (per-customer isolation / blue-green / restic backup) 인데 knowledge layer 만 single-operator PKM tool 수준 | [M6 Blueprint artifact + PARA 지식 레이어](/ops/roadmap#m6--blueprint-artifact--para-지식-레이어) 가 본 격차 직접 대응. [D-bp-artifact-1~5](/ops/decisions) (2026-05-23 등재). [아키텍처 페이지](/architecture/artifacts) |

## Multi-tenant 외부 출시 차단 (Stage 0 → 1)

5분야 진단 (2026-05-21) 결과:

| 항목 | 현재 | 후속 |
|---|---|---|
| **Org tenancy FK fanout** | `Workspace/UsageLog/Agent` 에 organizationId FK 부재 (`prisma/schema.prisma:688` "별도 PR" 주석). single cross-tenant 쿼리 누락 = 전 고객 노출 | D-bp-org-fanout 신규 결정 + migration. D-bp-entity-1 의 entityId FK 와 별개 (entity = 회계 단위, org = customer 단위) |
| **Azure AD tenant env-lock** | `src/lib/auth.ts:101` `AZURE_AD_TENANT_ID` 단일 env → 외부 IdP 분기 0 | per-org `Organization.azureTenantId` + `auth.ts` multi-tenant Azure AD provider |
| **법무 페이지 / rate-limit / Sentry / `axe-health-monitor`** | TOS / Privacy / DPA / PIPA 페이지 0건. edge rate-limit 부재. monitor 미구현 (위 launchd 측 미구현 참조) | Stage 1 closed beta 진입 prereq |
| **Backup tier-A** | ✅ blueprint-postgres dump 포함 (2026-05-21 backup.mdx 갱신) | restore drill 1회 (Jul 15) |

## MCP 공통 함정 (D-bp-mcp-3 cross-cutting, 2026-05-22)

[D-bp-mcp-3](./decisions#d-bp-mcp-3) 본질이 frame · hive 에도 부분 적용. 양파껍질 6 layer 의 한 갈래:

| 서비스 | SQLite legacy 잔재 risk | startup probe (lifespan) | 비고 |
|---|---|---|---|
| **blueprint-mcp** | ✅ 해소 (D-bp-mcp-3 2026-05-22) | ✅ 적용됨 | `.env` line 제거 + config fail-fast + lifespan `SELECT 1` |
| **frame-mcp** | N/A (URL self-construct, env string 안 씀) | ❌ **미적용** — `/health/ready` 는 request-time only (`frame/src/frame/mcp/http_server.py:594`) | broken DB 로 부팅 가능, swap promote 위험. **lifespan probe 1 블록 추가 권장** (blueprint pattern mirror) |
| **hive-mcp** | N/A (frame 패턴 동일) | ❌ **미적용** — `hive/src/hive/mcp/http_server.py:364` | 동상 |

**복붙 메시지** (운영자가 frame/hive owner 에게 전달): [/architecture/mcp-server-checklist#16 startup probe pass](../architecture/mcp-server-checklist#8-운영--14-가지-체크포인트) 참조. 5-10 분 작업.

## claude.ai 멀티-커넥터: 1 커넥터의 나쁜 key 가 전체 tools/list 400 (2026-05-28)

claude.ai 는 활성화된 **모든 커넥터의 tool 을 하나의 `tools` 배열로 합쳐** API 에 보냄. 따라서 **어느 한 커넥터** tool 의 inputSchema property key 가 `^[a-zA-Z0-9_.-]{1,64}$` 를 위반하면 → `400 tools.N.custom.input_schema.properties` 로 **요청 전체 거부** → 그 대화의 *모든* 커넥터(결백한 것 포함)가 같이 막힘. `tools.N` 의 N 은 결합 배열 인덱스라 커넥터 on/off 시 바뀜 → 범인 특정이 어려움 (Cortex 함정 #6 의 cross-connector 확장판).

- **2026-05-28 발견**: cortex register_person 이 `tools.15`/`tools.10` 으로 막힘. cortex(12)·frame(51)·hive(39) 라이브 tools/list + Claude-in-Chrome 22 스키마 직접 검증 → 전부 clean. 범인 = **claude.ai 의 `GitHub 연동`(Anthropic 제공 통합)** — 우리가 소스 못 고침. 사용자가 그 커넥터만 비활성화 → 즉시 해소.
- **진단법 (사용자에게 커넥터 토글 반복 요청 금지)**: 각 서비스의 `mcp-token` CLI(frame/hive) 또는 HS256 수동 mint(cortex)로 로컬 `tools/list`(blue 컨테이너 직접) 받아 모든 property key 를 정규식 검증. Anthropic 커넥터(GitHub 등)는 소스 접근 불가 → 소거법으로 좁힌 뒤 사용자가 해당 커넥터 비활성화 + 앱 내 피드백 신고.
- **예방**: 우리 서비스는 trap #6(ASCII-only key) 준수. CI/`axe mcp publish` 에 "served tools/list 의 모든 property key 정규식 lint" 추가 권장 (backlog 가치).

## 신규 ship 된 MCP tool 이 이미 연결된 Claude 세션·서브에이전트에 안 보임 — tools/list 재동기 지연 (2026-05-29)

> Blueprint MCP `send_mail` ([D-bp-mcp-mail-1](./decisions#d-bp-mcp-mail-1)) ship + self-send Graph 202 검증 직후, 운영자의 active Claude Code 세션에서 호출 → `No such tool available`. 같은 세션에서 spawn 한 서브에이전트도 동일 (ToolSearch 4회 모두 미발견).

MCP 클라이언트(Claude Code / claude.ai)는 **연결 handshake 시점의 `tools/list` 를 캐시**한다. 서버에 tool 을 새로 배포해도 **이미 연결된 세션은 재동기 전까지 못 본다**. 서브에이전트(Agent tool)는 **부모 세션의 MCP 연결을 공유**하므로 스폰으로도 해소 안 됨 (stale registry 상속).

- **결정적 해결 = 새 세션**: `spawn_task` 칩 / 세션 재시작 / 커넥터 reconnect(`/mcp`). fresh handshake → fresh `tools/list`.
- **자가 해소되기도 함**: 본 건은 일정 시간 후 클라이언트가 재-list 하여 같은 세션에 `send_mail` 이 deferred tool 로 떠 호출 성공(재시작 없이). "전파 지연"이지 영구 차단 아님 — 타이밍은 비결정적.
- **오진 주의**: "tool 미발견 = 배포 실패" 단정 금지. 서버 측 검증(self-send 202 / 컨테이너 직접 `tools/list`)이 통과하면 배포는 정상, 클라이언트 캐시 문제다.
- **운영 수칙**: MCP tool ship 후 같은 세션 즉시 호출 실패는 정상. 급하면 새 세션(칩/재시작), 아니면 잠시 후 재시도.

## Cortex production live — 7 함정 (2026-05-28, 신규 Rust MCP 서비스 첫 배포)

cortex (Rust + axum + sqlx, 첫 비-Python MCP 서비스) 를 claude.ai connector 까지 live 시키며 밟은 함정. **index ([D-index-2](./decisions)) 가 cortex 1:1 미러라 그대로 상속** — 등재 순서대로 회피할 것.

| # | 함정 | 증상 | 회피 |
|---|---|---|---|
| 1 | **DB password 의 base64 `/`·`+`·`=` 가 connection URL 파싱 깨뜨림** | `error with configuration: invalid port number` — `postgres://user:pa/ss@host:port` 에서 `/` 뒤가 port 자리로 오인 | sqlx `PgConnectOptions::new().host().port().username().password()` 빌더 사용 (URL string 조립 금지). cortex `src/db.rs::connect_options` |
| 2 | **docker compose `env_file:` 가 따옴표를 literal 로 처리** | `axe secret pull` 이 `KEY="val"` 로 쓰면 컨테이너 안 env = `"val"` (따옴표 포함) → postgres auth 실패 / secret mismatch. compose `.env` (variable substitution) 은 따옴표 strip 하므로 postgres init 은 unquoted, mcp 컨테이너만 quoted → 불일치 | env_file 값은 unquote. 임시: `sed -i '' -E 's/^([A-Z_]+)="(.+)"$/\1=\2/'`. 영구: [B-axe-secret-pull-noquote](./backlog) (axe secret pull 이 quote 안 붙이게) |
| 3 | **RFC 9728 resource-level metadata path 누락** | claude.ai 가 `<application_id_uri>/.well-known/oauth-protected-resource` (= `/cortex/mcp/.well-known/...`) fetch 시도 → 404 (server-level `/cortex/.well-known/...` 만 있으면 부족) → discovery 실패 → origin `/authorize` fallback | server-level + resource-level **둘 다** 라우트. [D-ops-23](./decisions) frame 학습 — cortex 가 미반영했다 재발 |
| 4 | **RFC 8414 path-insertion — authorization_servers 를 자기 (path 있는 issuer) 로 두면 안 됨** | `authorization_servers: ["https://axe.axelabs.ai/cortex"]` → claude.ai 가 RFC 8414 §3.1 따라 `https://axe.axelabs.ai/.well-known/oauth-authorization-server/cortex` (host 와 path 사이 삽입) 에서 metadata 찾음 → 우리가 serve 하는 `/cortex/.well-known/...` (path append) 와 불일치 → 404 → origin `/authorize` fallback → blueprint 404 | `authorization_servers` 를 **Microsoft** 직접 (`login.microsoftonline.com/<tenant>/v2.0`) 로. claude.ai 가 Microsoft OIDC metadata fetch → Microsoft endpoint 사용. self-hosted AS proxy 불필요 ([D-cortex-8](./decisions), frame "직접-Microsoft" path) |
| 5 | **claude.ai connector 는 client_id + client_secret 입력 필수** | URL 만 입력 시 confidential client credential 없어 OAuth 미완 | Advanced field 에 client_id (Entra appId) + client_secret 입력. frame/hive/blueprint 와 동일 ([D-vault-mcp-catalog](./decisions), `axe mcp publish` 로 Bitwarden 확장 auto-suggest) |
| 6 | **MCP tool inputSchema property key 는 ASCII only** | 한글 key (`"메모"`) → Anthropic API `400 tools.N.custom.input_schema.properties: Property keys should match pattern '^[a-zA-Z0-9_.-]{1,64}$'` → **해당 connector 의 tools/list 전체 거부** (1개 나쁜 key 가 12 tools 모두 막음). claude.ai 에서 silent fail | property key 는 ASCII (`memo`). 한글 값은 `additionalProperties: true` 로 런타임 전달 가능 (key 만 제약). cortex commit `dfa9330` |
| 7 | **Cloudflare 터널이 Dashboard remote-managed** | 로컬 `~/.axe/tunnels/axelabs/config.yml` 편집 + 컨테이너 재시동해도 ingress 안 바뀜 (`cloudflared` log 의 `Updated to new configuration version=N` 이 remote 적재 증거). `axe-tunnel` 와 `axelabs-tunnel` 이 다른 컨테이너 (전자 = axellc.com zone, 후자 = axelabs.ai zone) — 잘못된 것 재시동하기 쉬움 | Cloudflare Dashboard 또는 API (`PUT /accounts/<acct>/cfd_tunnel/<uuid>/configurations`, token = vault `Cloudflare API - axelabs`) 로 ingress 변경. `axe` 의 `_cf_request` helper 가 이미 있음 → [B-axe-tunnel-add-ingress](./backlog) CLI 화 권장 |

**부수**: (a) Docker image 는 `cargo build` (호스트) 와 별개 — 코드 변경 후 `docker compose up -d --build` 필수 (안 그러면 옛 binary). (b) `shred` 는 macOS 미존재 (Linux 전용) — `rm -P` 또는 APFS+SSD 에선 `rm` 으로 충분. (c) **Google OAuth consent 2026-05-29 Testing → production 전환** (client `135512942819-l18ra7gkf1ac93ai8t4hf2h4jl6mi0a2.apps.googleusercontent.com`, project no. 135512942819). Testing 시절 함정(Test users 목록의 Gmail 만 허용·100명 한도·미등록=`403 access_denied`, **+ refresh_token 7일 만료**로 sync 주기적 단절 위험)은 production 전환으로 해소. **잔존 함정**: 스코프 `auth/contacts` 는 Google *sensitive* 인데 앱이 unverified → 동의 화면에 "확인되지 않은 앱" 경고 + unverified 사용자 100명 상한. 사용자는 **고급 → "&lt;앱&gt;(으)로 이동(안전하지 않음)"** 으로 통과(동작엔 지장 없음). 경고 제거 = Google 정식 검증 → [B-cortex-google-oauth-verify](./backlog) (**금전비용 0** — `contacts` 는 sensitive 라 CASA 제3자 보안평가 불필요; restricted 였으면 수천 $/yr). Internal user type 은 Workspace 조직원 한정이라 개인 Gmail 연동엔 부적합.

**Cortex — `attended` relationship 방향 불일치 (2026-05-29 PM12, 미해결)**: interaction↔person 의 `attended` 엣지가 두 생성 경로에서 반대 방향. `log_interaction` MCP = `from=interaction → to=person`, xlsx_hpe/backfill = `from=person → to=interaction`. 따라서 "interaction 의 참석자" 를 한 방향만 가정해 쿼리하면 절반 누락. **현재 대응**: web `fetch_attended_participants` 가 `$iid IN (from,to)` 후 반대쪽 endpoint=person 으로 **양방향 흡수** (display 레벨 해소, 36 interaction 전부 resolve). **미해결**: 데이터 정규화(36건 방향 통일) migration 미실시 — 새 코드가 "interaction 의 attended" 를 짤 때 반드시 양방향. 우회 invariant 는 cortex `CLAUDE.md` 운영 함정에도 기록.

## index 측 — proceeds 산정 정밀도 (2026-05-29, D-index-22 audit)

EV→EqV(net debt) bridge + 투자 후 dilution 이 7-deal 에 비일관 적용된 사실 (사용자 audit 발견). [D-index-22](./decisions) 가 schema/validate 로 강제 (`proceeds_basis` enum + Check 7 `stake×(EV−net debt)` ±2% reconcile, broken bridge hard-reject) 하고 Sendy 는 `ev_bridge` 로 정정 (net debt 0, IRR 불변 6.47%). 잔여 분석적 사실:

| 항목 | 현재 상태 | 후속 |
|---|---|---|
| **Iippo·Canopy legacy_ev** | EV-based 이나 per-leaf 에 exit_ev/net_debt/stake 미itemize → validate Check 7 = legacy_ev WARN 2건. Canopy 는 net debt 300억 을 model-level `exit_assumptions` 에 명시(EqV 498억)했으나 per-leaf 분해 안 됨; Iippo 는 asset-light net debt~0 | [B-index-proceeds-bridge-retrofit](./backlog) — per-leaf ev_bridge 전환 (40+/30+ leaf) |
| **Iippo·Sentry entry-F/D-flat dilution** | exit proceeds 가 entry fully-diluted stake (Iippo 2.065% / Sentry ~4.46%) 를 exit 까지 flat 적용 — Pre-A→exit(5~7y) 사이 Series A/B 신주 희석 미반영 → proceeds·IRR 수 pp 과대 낙관. RCPS anti-dilution/pro-rata 부분 상쇄 | Closed deal 이라 사후 정정 실익 낮음 — retrofit 시 exit_stake 를 round-별 희석 반영값으로. pre-IPO 3 + Sendy 는 이미 exit-date 희석 stake 명시라 해당 없음 |
| **net debt = screening 가정 (BS 부재)** | Sendy net debt 0 은 dataroom 에 BS 없어 asset-light + 자금니즈 equity 충족 근거의 보수적 screening 가정 | DD 단계 실 BS 확보 시 `exit_net_debt_krw` 한 줄 수정 → proceeds·IRR 자동 재산출 (deterministic) |

## frame 측 미완 (회계 도메인 확장)

| 항목 | 현재 상태 | 후속 |
|---|---|---|
| **AXEV 창업기획자 펀드 회계** | **Migration #1 + #3 일부 완료** (2026-05-22, D-ops-22). `shared.entity` 에 `entity_kind`/`fund_meta`/`closed_at` ADD + `shared.entity_relationship` 확장 (numerator/denominator/unit + `gp_managed_fund`/`lp_invested_fund`) + `shared.cross_journal_link` 신설 + `register-entity` CLI `--kind`/`--fund-meta` flag + alembic `0008_shared` 적용 + frame-mcp blue/green rebuild + tests/test_shared_fund_domain.py 16 PASS. **axec/axev/axtest** 자동 entity_kind='corporate'. 강태훈 대표 2026-05-23 자료 ingest 예정 (Evidence + entity meta + 통장내역 raw_transaction). 잔여: 펀드 전용 계정과목 (출자금·미출자약정·평가손익·분배금) + capital call / waterfall + AXEV↔조합 cross-entity mirror 분개 (GP commitment·운용보수·성과보수) 모두 미구현 | **Architecture (2026-05-21 채택 + 2026-05-22 drift 정정 + 2026-05-22 Migration #1 적용)**: <br/>• **기존 `shared` 확장 ✅완료** (frame_meta schema 신설 폐기 — 코드 탐색 결과 기존 객체와 명명 충돌 + cross-entity 메타 layer 가 이미 shared 에 존재): ① `shared.entity` 에 `entity_kind` (corporate/kip/kvf) + `fund_meta` JSONB + `closed_at` 컬럼 ADD ✅. ② `shared.entity_relationship` (PR #26) 에 `ownership_numerator/denominator/unit` 컬럼 ADD (% 폐기, 반올림 오차 회피) + kind ENUM 확장 (`gp_managed_fund`/`lp_invested_fund` 추가) ✅. 의미 매핑: entity_a=holder, entity_b=target. ③ `shared.cross_journal_link` 신설 (mirror 분개 pair, schema 격리 환경 무결성) ✅.<br/>• fund schema 내부 (미구현): `commitment_ledger` (LP 약정/call/미출자 off-BS) + `lp_master` (조합원 + optional `external_entity_id`) + (optional) `fund_waterfall_state`.<br/>• fund 계정 seed (미구현): 기존 `shared.account_template` 에 새 standard `'fund_ksme'` 추가 + 펀드 계정 row.<br/>• Blueprint = workspace↔entity **scalar 1:N** (`Workspace.entityId` 단일). 사용자 결정 (2026-05-22, [PR #339](https://github.com/soohunkang/blueprint/pull/339)): OneDrive `/Ventures/` `/Corporation/` 폴더 분리가 SOT, fund 회계의 cross-entity 는 `User.entityScopes` 로 처리. N:M `WorkspaceEntity` join 권고는 reject (over-engineering).<br/>• 권한 enforcement = Blueprint middleware (gatekeeper). frame 은 entity_id 동등 처리. 기존 `entity_session` search_path 패턴 (entity_id == schema_name) 유지.<br/>• 회계 원칙: AXEV↔fund = parent-child 아닌 운용 관계 (K-IFRS 1110 통제 미달). relation_kind 가 회계 처리 갈래 (지분법/공정가치/운용보수) 결정.<br/>**Migration 순서**: (1) ✅완료 shared 확장 + cross_journal_link 신설 (alembic `0008_shared`) [D-ops-22], (2) fund_ksme standard + seed [D-frame-N2], (3) ✅일부완료 (CLI `--kind`/`--fund-meta`) — 잔여: MCP `register_entity` tool (CLI 의존 제거) + `list_sub_entities` tool [D-frame-N3], (4) Blueprint WorkspaceEntity migration [D-bp-entity-1 수정], (5) 결성 조합 schema bootstrap + shared.entity row [조합 detail 대기], (6) fund schema 의 commitment_ledger/lp_master + 과거 결산 적재, (7) cross_journal_link 활용한 mirror 분개 tool [D-frame-N4] |

## frame shared.entity 의도 불명 row (`axep`)

2026-05-26 audit 발견. `shared.entity` 의 `axep` (legal_name "액스파트너스 유한책임회사", entity_kind=corporate, accounting_standard=ksme, 2026-05-22 08:56 등록) 의 등록 의도가 확인되지 않음. `audit_log` 은 `account` 한 table 의 chart seed 만 (운영 데이터 0). actor null, biz_no 없음, git 검색 결과 코드에도 언급 0.

후속: 강수훈 의도 확인 → (a) 실제 액스파트너스 유한책임회사 설립 의도면 보존 + biz_no/fund_meta 보강, (b) 단순 placeholder/test 면 DROP SCHEMA axep CASCADE + DELETE shared.entity. 본 row 는 [D-frame-register-entity-atomic](/ops/decisions) 2026-05-26 cleanup 사이클에서 보존 결정 (low-risk to leave, 강수훈 confirm 대기).

## 디자인 시스템 배포 (`@axe/ui` · axelabs.ai)

| 항목 | 현재 상태 | 후속 |
|---|---|---|
| **`@axe/ui` 패키지 발행 채널** | git+ssh 직접 임포트 (`pnpm add 'git+ssh://...axelabs#tag'`). dist 빌드 없이 raw TS export — 소비자는 `transpilePackages: ["@axe/ui"]` 명시 필요. npm registry / Verdaccio / GitHub Packages 모두 미사용 | v0.1 stable 후 GitHub Packages 검토. 현재 React 소비자 ≤3개라 git+ssh 로 충분 |
| **`axelabs.ai` 도메인 라이브** | ✅ LIVE — apex + www + docs + design 모두 tunnel 경유 200 (2026-05-29 검증). 컨테이너 `axelabs` (127.0.0.1:3900), `axelabs-docs` (3140). | (완료) |
| **`design.axelabs.ai` 디자인 시스템 도메인 (D-ui-3) LIVE** | ✅ 2026-05-29 — `ui.axelabs.ai` → `design.axelabs.ai` 완전 교체. DNS proxied CNAME (axelabs.ai zone, CF API) + tunnel remote config v21→v22 (ui→design 1-rule swap) + axelabs rebuild (proxy.ts host 분기). 검증: design 200(@axe/ui 페이지)·sub-path 308·ui 404·axelabs.ai/www/docs 무영향 | **함정 4**: ① tunnel ingress = remote-managed (config.yml 무효 — 본 페이지 "Cortex production live 7함정" #7) → `PUT /accounts/<acct>/cfd_tunnel/<uuid>/configurations` (token=vault `Cloudflare API - axelabs`). ② axelabs.ai zone DNS 는 반드시 **CF API 토큰** — `cloudflared tunnel route dns` 는 cert-scoped(axellc.com) 라 `<host>.axellc.com` 오생성 (이번에 `design.axelabs.ai.axellc.com` 생겨 삭제함). ③ host 분기 = `proxy.ts` (next.config rewrites 아님 — 정적 prerender `/` 우회). ④ 신규 1-level host 직후 로컬 resolver AAAA-only → IPv6 무라우팅 머신 `curl` HTTP 000 (production 무관, `curl -4`/`--resolve` 검증) |
| **Clash Display @import drop 함정** | Fontshare URL 의 `f[]=` 대괄호가 Next.js CSS @import 빌더에서 떨궈진다 (현 16.2.6 확인). 해결: `<link rel="stylesheet">` 를 layout 의 `<head>` 에 직접 추가. Pretendard·D2Coding `@import` 는 정상 | 다른 서비스 마이그레이션 시 같은 함정 안 빠지게 README + `/ui#consume` 에 명시. 향후 Next.js 픽스 시 재검토 |
| **nextra 테이블 셀 코드스팬 안 escape 안 된 파이프 → build 깨짐** | 2026-05-29 발견 (decisions.mdx D-cortex-google-drift). 마크다운 테이블 셀의 inline code 안에 escape 안 된 파이프 문자(예: JSON-ish payload 의 union 타입 표기)가 있으면 GFM 이 그 파이프를 셀 구분자로 먼저 분리 → 백틱 스팬이 깨지고 그 안 중괄호가 미닫힌 JSX expression 으로 노출 → nextra 가 "Unexpected end of file in expression" 로 **전체 build 실패**. `axe ship docs` 의 docker build 단계에서야 늦게 잡힘. **해결**: 셀 안 파이프는 항상 백슬래시 escape, 중괄호·꺾쇠도 코드스팬 의존 말고 escape (꺾쇠는 HTML entity). **예방**: ship 전 로컬 `npx next build` 로 컴파일 확인 (docker 왕복보다 빠름). | 여러 세션이 같은 mdx 편집 시 file 단위 git add 가 병행 세션 WIP 까지 휩쓸 수 있음 (이번 cortex D-cortex-google-drift 가 index 커밋에 혼입) → ship 전 staged diff 확인. docs ritual 에 "ship 전 npx next build" 추가 검토 |
| **`Button asChild` 미지원** | 현재 `Button` 컴포넌트는 raw `<button>` 만 — anchor 가 필요하면 `<a className="axe-btn axe-btn--primary">` 패턴 직접 사용. axelabs.ai 메인 페이지가 이 패턴으로 작성됨 | v0.2 에서 Radix Slot 패턴 도입 검토 |
| **dist 빌드 부재** | `package.json` exports 가 `./src/lib/index.ts` (raw TS) 를 가리킴. tsup/unbuild dist 빌드 없음 — 소비자 측 트랜스파일러에 의존 | Next.js / Vite 둘 다 transpilePackages 로 가능. dist 도입은 외부 OSS 공개 시점에 |
| **standalone build 의 `output: "standalone"` 의존** | Dockerfile 의 `.next/standalone` copy 가 `next.config.mjs` 의 standalone output 설정에 의존. 누락 시 빌드 fail | next.config 주석으로 표시. config 변경 시 Dockerfile 같이 확인 |
| **문서 템플릿 `@page` 전역 누수** (D-ui-3 Phase 2) | `.axe-doc` 인쇄용 A4 `@page` 를 전역 bare `@page` (size A4) 로 선언하면 design 사이트 **전 페이지** 인쇄가 A4 로 강제됨 (`@page` 는 문서 전역 스코프). 해결: named `@page axe-doc-portrait`/`axe-doc-landscape` + `.axe-doc` 의 `page:` 속성으로 스코프 — `document.css` 적용 완료 | 다른 인쇄 surface 추가 시 동일 패턴. jinja 템플릿 로컬 렌더·검증엔 jinja2 필요 (system `python3` 미포함 → `python3 -m venv` 후 `pip install jinja2`) |

## docs `verify:box` 오탐 — orphan `next dev` 의 IPv6 `:3140` port-shadow (2026-05-29)

`axe ship docs` 의 post-deploy `verify:box` (playwright `page.goto(localhost:3140, networkidle)`) 가 `TimeoutError: page.goto: Timeout 30000ms exceeded` 로 실패 → "❌ POST-DEPLOY VERIFY FAILED — production 박스 정렬 깨짐 (exit 3)" 출력. **그러나 배포는 성공했고 production 은 정상** — 전형적 오탐. ship 자체를 의심해 롤백/재빌드 하면 멀쩡한 배포를 헛돌린다.

근본 원인: host 에 떠 있던 **orphan `next dev --port 3140`** (parent=launchd, 4h+ 방치된 로컬 docs dev 잔여) 가 IPv6 `*:3140` 을 점유. `localhost` 가 `::1` 을 먼저 resolve 하는 macOS 특성상 host 의 모든 `localhost:3140` 접근 (playwright + curl) 이 죽은 dev 서버로 빨려감. production docker container 는 IPv4 `127.0.0.1:3140` 으로만 노출되고, 외부 `docs.axelabs.ai` 도 tunnel 이 `host.docker.internal` (IPv4) 로 origin 을 잡으므로 — **둘 다 멀쩡한데 host loopback 경유 검증만 깨진다**.

| 검증 경로 | 결과 |
|---|---|
| `curl localhost:3140` (host, `::1` 우선) | hang / timeout (orphan dev) |
| `curl -4 127.0.0.1:3140` | 200 / ~10ms (production container) |
| docker `inspect` in-container healthcheck | `FailingStreak: 0` (정상) |
| 외부 `https://docs.axelabs.ai` | 신규 본문 정상 서빙 |

진단 분기점: `lsof -nP -iTCP:3140 -sTCP:LISTEN` → listener 가 **두 개** (IPv6 `node` vs IPv4 `com.docker`). IPv6 쪽 PID 의 parent 가 launchd 이고 그 PID 가 production 트래픽 0 이면 orphan 확정. `verify:box` 만 깨지고 `curl -4` + in-container healthcheck + 외부 도메인이 모두 통과하면 = 배포 OK · 검증 경로 오염.

조치: orphan 을 `kill -TERM <pid>` (graceful, SIGKILL 불필요 — production PGID 와 무관). 이후 `localhost:3140` 이 IPv4 로 fallback → `verify:box` 재실행 PASS. 예방: 로컬 docs dev 는 끝나면 반드시 종료할 것. `:3140` 은 production container 점유 포트이므로 로컬 dev 는 **다른 포트** 권장 (`npx next dev --port 3142` 등).

## Blueprint Postgres — `prisma migrate deploy` 가 P3005 로 신규 마이그레이션 자동 적용 안 함 (2026-05-30)

`blueprint-postgres` 는 D-config-17 cutover 때 `db push` 로 부트스트랩돼서 `_prisma_migrations` 베이스라인 테이블이 **없다**. 그래서 컨테이너 기동 시 `start.sh` 의 `prisma migrate deploy` 가 **P3005 ("The database schema is not empty")** 로 거부하고 `[start] prisma migrate deploy failed (non-fatal)` 만 찍고 넘어간다. 결과: **`prisma/migrations/` 에 새 마이그레이션 파일을 추가해도 배포 시 자동 적용되지 않는다** (테이블이 생성되지 않음).

증상: route·코드는 떠 있는데 신규 테이블이 없어 `prisma.<model>.create()` 가 런타임에 실패. 감사 로그처럼 try/catch 로 감싼 경로면 **조용히** 실패할 수 있다 (D-bp-mcp-mail-1 의 `MailSendLog` 가 정확히 이 케이스 — route 정상 배포됐으나 테이블 부재로 audit write 가 silent fail 직전).

해결 (스키마 변경 시마다 1회):

```bash
# additive 변경(새 테이블 등)이면 해당 마이그레이션 SQL 만 직접 적용 — 가장 안전, 기존 테이블 무영향
docker exec -i blueprint-postgres psql -U blueprint -d blueprint -v ON_ERROR_STOP=1 \
  < prisma/migrations/<ts>_<name>/migration.sql
# 적용 확인
docker exec blueprint-postgres psql -U blueprint -d blueprint -tc "SELECT to_regclass('public.\"<Table>\"');"
```

2026-05-30 기준 같은 함정에 걸린 마이그레이션: `20260529120000_add_mail_send_log` (수동 적용 완료), `20260531000000_add_user_entra_oid` (다른 세션 작업 — `User.entraOid` 컬럼, 수동 적용 필요할 수 있음), `20260603100452_add_entity_legal_name` (C1 — `Entity.legalName` 영문 법인명 + axec/axev 백필, **미적용** — 배포 시 위 psql 직접적용 패턴 사용; additive·기존 테이블 무영향).

근본 fix 후보 (backlog): 기존 마이그레이션 전부를 `prisma migrate resolve --applied <name>` 로 베이스라인 등록 → 이후 `migrate deploy` 정상화. 또는 deploy hook 에 db-push fallback 추가.

## 문서 작업 다음 단계

- [ ] CLI Phase 5 완성 후 runbook 의 restic 명령을 `axe restore` 로 단순화
- [ ] `com.axe.secret-check` / `com.axe.health-check` launchd 구현 후 cloudflared.mdx 갱신
- [ ] partner/registration.mdx 와 frame/docs/ops/onboarding-operator.md §0 일관성 점검
- [ ] customers.yaml 에 blueprint app 슬롯 추가 (현재 frame_mcp 와 vaultwarden 만)
- [ ] Blueprint MEMORY.md 33.5KB → 24.4KB pruning (`~/.claude/projects/-Users-axe-blueprint/memory/MEMORY.md` index 항목 길이 정리, `/ctx review` 별도 세션)

## axelabs 5 표준 (2026-05-26, Truvia 측 요구로 명시화)

운영자 측 분석 (B-customer-deploy-generalization Phase 1 + Truvia D-day 후속 회신 기반) 의 axelabs platform 표준. 각 항목은 decisions.mdx 의 D-config-N 또는 D-ops-N 으로 별도 격상 검토.

| # | 표준 | 본질 | 시행 |
|---|---|---|---|
| 1 | **macmini 운영 패턴 = 기존 자산 ≡ 신규 발주 (동등 지원)** | customer 가 가동 중 macmini 에 platform 도입 시 발주·재설치 의무 없음. 14 컨테이너 기존 가동 + Tailscale 합류 + SSH key 기등록 케이스 (realchoice) 1급 지원. | `/partner/macmini-existing` (신설 예정 — B-docs-ssot-extension), `B-port-conflict-preflight` 가 충돌 게이트 |
| 2 | **Vault repo (`soohunkang/vault.git`) 표준 image = `timshel/vaultwarden:latest`** | Vaultwarden Timshel fork 가 axelabs platform 표준. customer 측이 다른 vault image (e.g. official vaultwarden/server) 사용 시 SSO/sso_nonce/healthcheck/path mount 패턴 모두 다름. Truvia 측 5/26 D-ops-32 검증 = Timshel + collection 구조 정렬. | `/services/vaultwarden` (신설 예정), `image_override` slot 으로 customer-별 version pin 허용 |
| 3 | **bw CLI 표준 version = `2025.7.0`** (D-ops-28 line) | bw 2026.4.x 가 Timshel SSO user 호환성 차단 ("Master password unlock data was not found", trap #12). 2025.7.0 = 최후 호환 release. | `bw-bootstrap.sh` 가 install hint + warning gate. `_svc_step_customer_vault_check` 가 version mismatch warning. backlog `B-bw-cli-version-pinning`. |
| 4 | **Customer-측 self-deploy 일반화 = R1-R5 빌트인** (B-customer-deploy-generalization Phase 1) | (R1) `${HOME}` 변환 — hardcoded `/Users/axe/` 금지. (R2) vault SoT — bw CLI 기반, keychain 의존 폐기. (R3) env_file `$` → `$$` escape — `escape_dollar` flag 자동. (R4) `image_override` slot — customer-별 service repo image pin. (R5) `${CUSTOMER_PREFIX}-` container name 정규화 (Phase 2). | axe CLI `_deploy_service_customer` + wrapper 3종 + customers.yaml schema. |
| 5 | **customers.yaml schema = secret manifest + service_tenant_map + image_override + escape_dollar slots** | customer 메타 + `sso.apps[].client_id` + `services.<svc>.<env_file, secrets[], image_override>` + `service_tenant_map` (D-magnet-tenant-map-1) + `ring_backup` + `entity_meta`. ruamel.yaml round-trip 으로 comment 보존. `axe customers ingest` 가 자동 fill. | `/Users/axe/.axe/customers.yaml` (SSOT), `INGEST_MANIFEST_TEMPLATE` (axe CLI), schema doc = `/architecture/customers` (신설 검토). |

## 세션 의례 (다음 세션 / 다른 세션 모두)

**모든 axelabs.ai 작업 세션은 본 페이지를 의례로 사용**:

1. **세션 시작 시 — READ**: 작업 주제와 관련된 known-gap 이 있는지 본 페이지 확인. 이미 등재된 gap 을 모르고 작업하면 다른 사람의 작업과 중복되거나 충돌 가능.

2. **세션 중 — DISCOVER**: 작업 중 새 gap / 미구현 / 약속 vs 실제 불일치 발견 시 즉시 본 페이지에 한 줄 추가 (해당 섹션에 표 row 추가). 메모리에 들고만 있지 말 것.

3. **세션 종료 시 — WRITE**: 본 세션이 해소한 gap 은 즉시 제거. 새로 발견한 gap 은 등재. 다음 세션의 다른 사람이 본 페이지만 보고도 현재 상태 파악할 수 있어야 함.

4. **페이지가 비어가는 것이 목표**. 단 의도된 deferral (예: "Phase 5 에서 통합") 은 등재 후 phase 표기.

운영자 또는 협업 세션에 본 ritual 이 적용되도록 root `CLAUDE.md` + per-repo `CLAUDE.md` 에 명시.

## 본 페이지의 의도

다음 세션의 본인 (또는 협업자) 이 문서를 보고 작업할 때, **약속된 것** 과 **실제 작동하는 것** 의 격차를 명확히 알도록 함. 격차 자체가 함정이 되지 않게 정리.

---

<!-- PAGE https://docs.axelabs.ai/ops/reports -->

# 리포트 (upstream 제출 draft)

> AXE Labs 운영 중 발견한 함정·feature request 의 upstream 보고 draft. 운영자가 검토 후 support / GitHub issue / PR 로 제출.

URL: https://docs.axelabs.ai/ops/reports

## 1. 본 섹션의 목적

AXE Labs 가 운영 중 발견한 함정 또는 feature request 중:

- **AXE 자체 fix 가 부분 fix 인 경우** (예: client-side workaround)
- **upstream 측 영구 fix 가 본질** (예: 라이브러리 자체 패치 필요)
- **다른 사용자도 영향 받을 함정** (i18n, accessibility, edge case)

해당하는 사안의 **self-contained 보고 draft** 를 본 섹션에 보관. 운영자가 검토 후 다음 채널 중 적절한 곳으로 제출:

- Vendor email support
- GitHub issue / discussion
- GitHub pull request
- 표준 단체 (RFC 등) — 해당 시

## 2. 현재 보유 reports

| ID (filename) | 제목 | 대상 | 상태 | 작성일 |
|---|---|---|---|---|
| [`claudeapp-fd-leak-2026-05`](/ops/reports/claudeapp-fd-leak-2026-05) | Claude Desktop PTY/fd leak | Anthropic | Draft — 운영자 검토 대기 | 2026-05-28 |
| [`anthropic-connector-input-attrs-2026-05`](/ops/reports/anthropic-connector-input-attrs-2026-05) | claude.ai Custom Connector input identifiers | Anthropic | Draft — 운영자 검토 대기 | 2026-05-28 |
| [`timshel-vaultwarden-upstream-pr-2026-05`](/ops/reports/timshel-vaultwarden-upstream-pr-2026-05) | Timshel/vaultwarden mainline backport (bw 2026.4+ compatibility) | Timshel/vaultwarden GitHub | Draft — 운영자 검토 대기 | 2026-05-28 |

## 3. 신규 보고 작성 가이드

새 함정·feature request 의 upstream 보고 draft 작성 시:

### 파일 명명

`<descriptive-slug>-YYYY-MM.mdx` (예: `claudeapp-fd-leak-2026-05.mdx`)

- slug = upstream system + 함정 type
- YYYY-MM = 발견 또는 작성 시점

### 권장 섹션 구조 (10 섹션, self-contained)

1. **Summary** — 1-2 문장 요약
2. **Environment** — OS, app version, hardware, uptime 등 repro 환경
3. **Symptom** — failure mode + reproduction steps + diagnostic commands
4. **Workarounds** — 현재 사용 가능한 우회 + AXE 측 자체 fix (있다면)
5. **Suspected root cause** — 분석 + 증거
6. **Impact** — 영향 범위 (user 수, scenario 등)
7. **Requested fix** — upstream 측에 요청하는 변경 (가능하면 code 또는 spec 단위)
8. **Attachments** — diagnostic logs, screenshots, code refs (path)
9. **Channels** — 어디 제출할지 (email, GitHub repo URL, etc.)
10. **Status** — draft → submitted → response → resolved

### MDX 주의사항

- code 는 fenced block 안
- placeholder `<tenant>` `<name>` 등은 backtick 안 또는 `&lt;...&gt;` escape
- frontmatter title 은 사람 읽기 쉬운 한 문장

### _meta.js 등재

파일 생성 후 `/Users/axe/axelabs-docs/content/ops/reports/_meta.js` 에 entry 추가:

```javascript
"new-report-slug-YYYY-MM": "사람 읽기 쉬운 제목"
```

## 4. backlog 연계

본 섹션의 모든 report 는 backlog 의 대응 항목과 cross-link 권장:

- backlog entry → report link (entry 본문에 `→ /ops/reports/<slug>` 명시)
- report frontmatter → backlog link (optional, history 추적용)

수락/회신 시 status 업데이트:

- 본 페이지 표의 "상태" 열 갱신
- backlog 의 ✅ Done 으로 이동 시점 = upstream 측 수락 또는 운영자가 close 결정

---

<!-- PAGE https://docs.axelabs.ai/ops/reports/anthropic-connector-input-attrs-2026-05 -->

# claude.ai Custom Connector input identifiers — feature request draft (2026-05)

> Custom Connector modal 의 4 input 에 안정 식별자 (name / aria-label / autocomplete) 부여 요청. 한국어 UI 에서 Bitwarden 등 password manager 자동 입력 불가 문제 해소 + 모든 i18n locale 동시 개선.

URL: https://docs.axelabs.ai/ops/reports/anthropic-connector-input-attrs-2026-05

# claude.ai Custom Connector input identifiers — feature request draft (2026-05)

> **상태**: Draft. 운영자 검토 후 `support@anthropic.com` 또는 [claude-code GitHub issues](https://github.com/anthropics/claude-code/issues) 에 그대로 전송 가능한 self-contained 리포트.
>
> **Backlog**: [B-anthropic-connector-input-attrs](/ops/backlog)
>
> **관련 분석**: [claude.ai Custom Connector autofill 한국어 한계](/ops/known-gaps)

---

## 1. Summary

claude.ai Custom Connector modal 의 4 input field (Name, Remote MCP server URL, OAuth Client ID, OAuth Client Secret) 가 안정 식별자 (`name` / `aria-label` / `autocomplete`) 를 갖고 있지 않다. Bitwarden 등 password manager 가 한국어 placeholder 만으로 매칭을 시도할 경우 정규화 규칙 (`/[^a-zA-Z0-9]+/g` — alphanumeric only) 이 한글을 모두 제거해 placeholder 가 빈 문자열이 되고, 결과적으로 자동 입력이 불가능하다. 4 input 에 `name="..."` 또는 `aria-label="..."` 를 추가하면 한국어 UI 에서 즉시 4/4 자동입력이 가능해지고, 다른 모든 i18n locale 도 동시에 해소된다.

## 2. Environment & Repro

- **URL**: `claude.ai/customize/connectors` → "Add custom connector"
- **Locale**: ko (한국어). 다른 locale (ja, zh, ...) 도 동일 영향 가능성 (추가 분석 필요).
- **Browser**: Chrome, Edge, 기타 Chromium 계열 모두 동일.
- **Password manager**: Bitwarden Chrome extension (2025.7.x, 2026.4.x 모두 검증). 1Password 등 다른 PM 도 동일 패턴 추정.

### Reproduction

1. `claude.ai/customize/connectors` 진입 (브라우저 locale = 한국어 상태).
2. "Add custom connector" 버튼 클릭 → modal 등장.
3. Bitwarden 확장에서 vault item 자동 채우기 시도.
4. 결과: 4 input 중 0/4 또는 2/4 만 채워짐. Client ID/Secret 은 EN substring 매칭으로 부분 성공 가능하나, Name + Remote MCP server URL 은 한국어 placeholder 만 노출되어 매칭 실패.
5. 사용자가 Name + URL 을 수동 입력 또는 Bitwarden popup 의 ⎘ copy-paste 로 채워야 함.

## 3. Root cause (DOM analysis)

Custom Connector modal 4 input 의 HTML (2026-05-27 inspect 결과, Claude in Chrome MCP 사용):

```html
<input
  type="text"
  id="base-ui-_r_dn_"
  placeholder="이름"
  class="..."
/>
<input
  type="text"
  id="base-ui-_r_dq_"
  placeholder="Remote MCP server URL"
  class="..."
/>
<input
  type="text"
  id="base-ui-_r_dr_"
  placeholder="OAuth Client ID"
  class="..."
/>
<input
  type="password"
  id="base-ui-_r_ds_"
  placeholder="OAuth Client Secret"
  class="..."
/>
```

문제점:

- `id` = Base UI 라이브러리의 무작위 패턴 (예: `base-ui-_r_dn_`) — 렌더마다 변경 가능. 안정 식별자가 아님.
- `name` / `aria-label` / `autocomplete` = **모두 없음**.
- 결과적으로 password manager 가 매칭할 안정 식별자가 0 — placeholder 만 시도 가능.

Bitwarden 매칭 logic (실측):

```javascript
// Bitwarden 의 form field 매칭 후보 정규화
const normalize = (s) => (s || '').toLowerCase().replace(/[^a-zA-Z0-9]+/g, '');
```

- 한국어 placeholder `"이름"` → 정규화 결과 = `""` (빈 문자열) → 매칭 후보 사라짐.
- 영문 placeholder `"OAuth Client ID"` → 정규화 결과 = `"oauthclientid"` → keyword 매칭 가능.

즉 한글 placeholder 만 가진 2 input (Name, 그리고 URL 도 일부 PM 에서 url scheme 매칭 실패) 은 구조적으로 자동입력 불가.

## 4. Requested fix

각 input 에 안정 식별자를 1개 이상 추가 (권장 = 3개 모두):

```html
<input
  type="text"
  name="connector-name"
  aria-label="Connector name"
  autocomplete="off"
  placeholder="이름"
  ...
/>
<input
  type="text"
  name="server-url"
  aria-label="Remote MCP server URL"
  autocomplete="url"
  placeholder="Remote MCP server URL"
  ...
/>
<input
  type="text"
  name="oauth-client-id"
  aria-label="OAuth Client ID"
  autocomplete="off"
  placeholder="OAuth Client ID"
  ...
/>
<input
  type="password"
  name="oauth-client-secret"
  aria-label="OAuth Client Secret"
  autocomplete="off"
  placeholder="OAuth Client Secret"
  ...
/>
```

이유:

- `name` = HTML 표준 form field identifier. Password manager 의 1순위 매칭 단서.
- `aria-label` = 시각 장애인 접근성 (screen reader) + 영문 식별자 — password manager 의 보조 단서.
- `autocomplete="off"` (또는 secret 의 경우 `"new-password"`) = browser 의 자체 저장 prompt 차단 (선택적).

추가 권장: 부모 `<form>` 에도 `name="add-custom-connector"` 같은 form-level 식별자를 부여 — Bitwarden 의 form context 매칭 보조.

## 5. Impact

| 사용자 | 현재 | 권장 fix 후 |
|---|---|---|
| 한국어 UI + Bitwarden | 2/4 자동입력 (EN substring 만), 2/4 수동 | 4/4 자동입력 |
| 한국어 UI + 다른 PM | 동일 (정규화 규칙 동일) | 4/4 자동입력 |
| 영문 UI | 2/4 자동입력 (placeholder EN substring) | 4/4 자동입력 |
| 다른 locale (일본어, 중국어 등) | 0/4 또는 2/4 (locale 별 placeholder 정규화에 의존) | 4/4 자동입력 |

a11y 부수 효과: `aria-label` 추가로 screen reader 사용자의 form field 식별이 개선됨.

## 6. AXE Labs 자체 우회 (참고)

운영자 (AXE Labs 임직원) 가 한국어 UI 에서 자체 catalog 를 통해 우회:

- Vaultwarden `MCP Connectors` org collection 의 6 Custom Field 등재: `Name`, `Server URL`, `MCP URL`, `Tenant ID`, `Scopes`, `Vault secret path`.
- autofill 2/4 (Client ID + Secret, EN label substring 매칭) 가능.
- 나머지 2/4 (Name + URL) = Bitwarden popup 의 ⎘ copy → paste 수동.

본 우회는 운영 가능하나 connector 등록 1 건당 운영자 click 약 6 회 발생. 본 upstream fix 는 한국어 UI 에서도 4/4 자동입력, 다른 locale 도 동시에 해소.

## 7. Attachments / references

- Custom Connector modal HTML inspect 결과 (2026-05-27, Claude in Chrome MCP).
- Bitwarden 매칭 정규화 규칙 (`/[^a-zA-Z0-9]+/g`) — Bitwarden browser extension source 참조 가능.
- AXE Labs 자체 catalog 우회 패턴 (`B-axe-mcp-catalog-en-aliases` 결과물).
- 관련 known-gaps: [claude.ai Custom Connector autofill 한국어 한계](/ops/known-gaps).

## 8. Submission channels

- **Email**: `support@anthropic.com` (subject 예시: `Feature request: Custom Connector input identifiers for i18n password manager support`)
- **GitHub**: https://github.com/anthropics/claude-code/issues — issue title 예시: `Custom Connector modal: add name/aria-label to 4 input fields for i18n password manager support`

## 9. Status

| Field | Value |
|---|---|
| Report state | Draft |
| Submission date | TBD (운영자 결정) |
| Anthropic acknowledgement | TBD |
| Anthropic fix release | TBD |

운영자가 검토 후 위 채널 중 하나로 제출. 회신 수령 시 본 페이지 §9 표를 갱신하고 [/ops/known-gaps](/ops/known-gaps) 의 해당 항목에 진행 상황 한 줄 추가.

---

<!-- PAGE https://docs.axelabs.ai/ops/reports/claudeapp-fd-leak-2026-05 -->

# Claude Desktop PTY/fd leak — bug report draft (2026-05)

> macOS Claude.app 의 /dev/ptmx fd 누적 leak 으로 1-2 주 가동 후 forkpty ENXIO 차단. Anthropic support 또는 claude-code GitHub issue 제출용 draft.

URL: https://docs.axelabs.ai/ops/reports/claudeapp-fd-leak-2026-05

# Claude Desktop PTY/fd leak — bug report draft (2026-05)

> **상태**: Draft. 운영자 검토 후 `support@anthropic.com` 또는 [claude-code GitHub issues](https://github.com/anthropics/claude-code/issues) 에 그대로 전송 가능한 self-contained 리포트.
>
> **Backlog**: [B-claudeapp-fd-leak-anthropic-report](/ops/backlog) · **Tracking**: [B-claude-desktop-pty-leak-track](/ops/backlog) · **Mitigation**: [B-axe-pty-max-launchd](/ops/backlog)
>
> **관련 분석**: [Claude.app /dev/ptmx fd leak (known-gaps)](/ops/known-gaps)

---

## 1. Summary

Claude Desktop on macOS leaks file descriptors to `/dev/ptmx`, accumulating fd usage over weeks of normal operation until the system-wide `kern.tty.ptmx_max` limit is reached. After that, new terminal/PTY spawns fail with `forkpty: Device not configured` (ENXIO), affecting all macOS users on the host (not just Claude.app itself). The only known fix is to quit and restart Claude Desktop, which reclaims all leaked fds.

## 2. Environment

- **OS**: macOS (Darwin 25.3.0 at time of reproduction)
- **App**: Claude Desktop — `/Applications/Claude.app/Contents/MacOS/Claude`
- **Hardware**: Apple Silicon mac mini
- **Uptime at failure**: 43+ days continuous operation (observed 2026-05-26)
- **PTY limit**: `kern.tty.ptmx_max` = 511 (macOS default; sysctl raise to 2047 is rejected by kernel)

## 3. Symptom

### 3.1 Failure mode

- New terminal spawns (Terminal.app, iTerm2, Claude Code subprocess `forkpty()`) are denied with ENXIO.
- Error string: `forkpty: Device not configured`
- **Scope**: system-wide — not limited to Claude.app. All users on the host lose the ability to allocate new PTYs until the leak is cleared.

### 3.2 Reproduction

1. Use Claude Desktop normally on a macOS host (open many chats, close them, leave the app running).
2. After 1–2 weeks of continuous uptime, monitor PTY fd consumption:
   ```bash
   sudo lsof /dev/ptmx | grep -i Claude | wc -l
   ```
   Count grows steadily over time.
3. When the total `lsof /dev/ptmx` count reaches `kern.tty.ptmx_max` (default 511), `forkpty: Device not configured` starts to fire on every new PTY allocation attempt.

### 3.3 Diagnosis commands

```bash
# Per-process PTY fd occupancy (sorted)
sudo lsof /dev/ptmx | awk '{print $1}' | sort | uniq -c | sort -rn

# Kernel PTY ceiling
sysctl kern.tty.ptmx_max

# Detailed fd list for Claude.app PID
ps aux | grep -i Claude
sudo lsof -p <claude-pid> | grep /dev/ptmx | wc -l
```

### 3.4 Observed data (2026-05-26, operator host)

- Claude.app PID held fds 43, 44, 46, 88, 89, 92, 94, 98, 99, 102+ against `/dev/ptmx`.
- Reaping userspace zsh zombies (82 accumulated, all Claude Code subprocesses) did **not** release the ptmx fds — confirming the leak is in Claude.app proper, not in spawned shells.

## 4. Workarounds (current)

| Action | Effect | Notes |
|---|---|---|
| Quit + relaunch Claude Desktop | Immediate: all leaked fds reclaimed | Only known reliable fix |
| `sudo sysctl -w kern.tty.ptmx_max=2047` | Ineffective | Kernel rejects values above 511 on current macOS |
| launchd plist for boot-time sysctl ([B-axe-pty-max-launchd](/ops/backlog)) | Pending validation | Likely also rejected by kernel; tracked as long-term mitigation |

## 5. Suspected root cause

- Claude.app spawns PTY-backed subprocesses (IPC helpers, terminal-like surfaces) without releasing the master fd when the subprocess exits or the chat is closed.
- Reaping orphaned userspace `zsh` zombies (Claude Code subprocesses) does not free the `/dev/ptmx` fds — strongly suggests the leak is in the Claude.app process holding the master end open after the slave has gone away.
- Pattern is consistent with missing `close()` on the master fd in a subprocess lifecycle path.

## 6. Impact

- **Affected users**: macOS users running Claude Desktop with long uptime (1–2 weeks+) and any non-trivial chat volume.
- **Blast radius**: system-wide PTY denial — all terminal applications on the host are blocked from spawning new sessions, not just Claude.app.
- **Detectability**: silent until the limit is hit; the failure surfaces in unrelated apps (Terminal.app, iTerm2) and is hard to attribute to Claude.app without running `lsof /dev/ptmx`.

## 7. Requested fix

1. Audit Claude.app's PTY subprocess lifecycle — ensure master fds are `close()`d when the slave end exits or the owning chat/IPC channel is torn down.
2. Guarantee close-on-exit semantics for all spawned PTYs.
3. Add a self-check in the production build: if Claude.app's own `/dev/ptmx` fd count exceeds a threshold (e.g. 100), emit a telemetry event so this regression is caught automatically in future releases.

## 8. Attachments / references

- Operator known-gaps entry: [Claude.app /dev/ptmx fd leak](/ops/known-gaps)
- Related operator backlog items:
  - `B-claude-desktop-pty-leak-track` — tracking the recurrence
  - `B-axe-pty-max-launchd` — host-side mitigation attempt
  - `B-claudeapp-fd-leak-anthropic-report` — this report

## 9. Submission channels

- **Email**: `support@anthropic.com`
- **GitHub**: https://github.com/anthropics/claude-code/issues — cross-post recommended since the symptom also surfaces from Claude Code's subprocess `forkpty()` paths.

## 10. Status

| Field | Value |
|---|---|
| Report state | Draft |
| Submission date | TBD (운영자 결정) |
| Anthropic acknowledgement | TBD |
| Anthropic fix release | TBD |

운영자가 검토 후 위 채널 중 하나로 제출. 회신 수령 시 본 페이지 §10 표를 갱신하고 [/ops/known-gaps](/ops/known-gaps) 의 해당 항목에 진행 상황 한 줄 추가.

---

<!-- PAGE https://docs.axelabs.ai/ops/reports/timshel-vaultwarden-upstream-pr-2026-05 -->

# Timshel/vaultwarden upstream PR draft — bw 2026.4+ client compatibility (2026-05)

> AXE Labs 가 Timshel fork 의 axe.2 release 에 적용한 2 patch 의 upstream 제출 draft. /accounts/prelogin/password alias + /identity/connect/token AccountKeys/MasterPasswordUnlock backport. 둘 다 dani-garcia/vaultwarden mainline backport 성격.

URL: https://docs.axelabs.ai/ops/reports/timshel-vaultwarden-upstream-pr-2026-05

# Timshel/vaultwarden upstream PR draft — bw 2026.4+ client compatibility (2026-05)

> **상태**: Draft. 운영자 검토 후 [Timshel/vaultwarden](https://github.com/Timshel/vaultwarden) 에 그대로 PR 본문으로 paste 가능한 self-contained 제출문.
>
> **Backlog**: [B-vault-axe.2-patches-upstream-pr](/ops/backlog) · **관련 분석**: [/ops/known-gaps](/ops/known-gaps) 의 Timshel fork drift 항목.
>
> **Scope**: 본 PR 은 axe.2 의 2 patch 만 다룸. axe.3 의 organizations Owner-skip 제거 + cipher.permissions backport 는 별 PR 권장 (§7 참조).

---

## 1. Summary

Timshel/vaultwarden fork 가 dani-garcia/vaultwarden mainline 대비 2개 endpoint 가 outdated → bw CLI 2026.4+ / Bitwarden Chrome extension >= 2026.4 와 호환 깨짐. 본 PR 가 2 minimal patch 로 mainline 동등 shape 회복.

## 2. Motivation

### 2.1 Symptom

- bw CLI `2025.7.0` 까지는 호환 정상.
- bw CLI `2026.4.x` + Bitwarden Chrome ext `2026.4+` 에서 SSO user unlock 시도 시 다음 에러:
  - `Master password unlock data was not found`
  - `Cannot read properties of null (reading 'toWrappedAccountCryptographicState')`

### 2.2 Trigger

새 Bitwarden client (2026.4.x) 가 unlock flow 에서 server 측 응답 shape 의존성 강화 (mainline vaultwarden 의 새 spec). Timshel 은 옛 spec 유지 → 새 client 가 expect 하는 field 부재로 unlock 차단.

### 2.3 Affected

- Timshel fork 사용자 + 2026.4.x bw client 조합.
- SSO 인증 후 master password unlock 흐름.

### 2.4 Workaround (현재 운영)

- 클라이언트 측: `npm install -g @bitwarden/cli@2025.7.0` 으로 pin (임시).
- 서버 측 (영구): 본 PR 의 2 patch 적용 — AXE Labs 는 axe.2 release 로 production 운영 중.

## 3. Changes

### 3.1 Patch 0001 — `/accounts/prelogin/password` alias

**File**: `src/api/identity.rs` (또는 동등 router).

**Change** (개념):

```rust
// 기존
.route("/accounts/prelogin", post(prelogin))

// 추가
.route("/accounts/prelogin/password", post(prelogin))  // mainline alias
```

또는 동일 handler 가 두 path 모두 처리하도록 등록.

**Rationale**: dani-garcia/vaultwarden mainline 의 `/accounts/prelogin/password` endpoint 와 동일 response shape. bw 2026.4 client 가 본 path 호출 → 200 OK + shape (kdf, kdfIterations 등) 받아 unlock 진행.

### 3.2 Patch 0002 — `/identity/connect/token` AccountKeys/MasterPasswordUnlock

**File**: `src/api/identity.rs` (또는 connect_token handler).

**Change** (개념):

```rust
struct TokenResponse {
    // ... 기존 field
    AccountKeys: AccountKeysData,         // 신규
    MasterPasswordUnlock: MpUnlockData,   // 신규
}

struct AccountKeysData {
    publicKey: String,
    encryptedPrivateKey: String,
    // ... mainline 동등
}

struct MpUnlockData {
    kdf: KdfType,
    kdfIterations: i32,
    kdfMemory: Option<i32>,
    kdfParallelism: Option<i32>,
    salt: String,
    masterKeyWrappedUserKey: String,
    emailKdfIterations: Option<i32>,
    // ... mainline 동등
}
```

**Rationale**: mainline vaultwarden 의 `/identity/connect/token` response 와 동일 field set. 2026.4+ client 가 본 field 로 unlock flow 진행.

## 4. Testing

### 4.1 Manual verification (AXE Labs production, 2026-05-26)

Server 측 (axe.2 image deploy 후):

```bash
curl -X POST https://axe.axelabs.ai/vault/api/accounts/prelogin/password \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com"}'
# Expected: 200 OK + {kdf, kdfIterations, ...}
```

Client 측 (bw CLI 2026.4+):

```bash
bw config server https://axe.axelabs.ai/vault
bw login --sso
# Expected: SSO + MP flow 통과, unlock 성공
```

### 4.2 Real-world validation

- AXE Labs production 운영 (2026-05-26 부터): axe.2 image deploy 후 bw CLI 2026.4.x + Chrome ext 2026.4.x 모두 정상 unlock 검증.
- Real users: 4 명 (운영자 + 3 임직원) — 회귀 0 보고.

## 5. Compatibility

- **Backward compat**: 기존 `/accounts/prelogin` 그대로 유지 → 옛 client (2025.x 이하) 영향 0.
- **Forward compat**: mainline vaultwarden 의 shape 와 동등 → 미래 client update 와도 정합.
- **Database migration**: 없음 — 모두 response shape 변경만.

## 6. Code reference

AXE Labs 의 fork repo: https://github.com/axelabs-ai/vault

- axe.2 release commit: TBD (운영자가 commit hash 채울 것)
- `patches/0001_prelogin_password_alias.patch`
- `patches/0002_connect_token_account_keys_mp_unlock.patch`

Mainline reference:

- dani-garcia/vaultwarden 의 동등 코드 위치 (PR 제출 시 commit/file 링크 첨부 권장).

## 7. Related (별 PR 권장)

axe.3 release 의 추가 2 patch — 본 PR scope 외:

- **Patch 0003**: organizations Owner-skip 3 site removal — `post_organization_collections` + `post_bulk_access_collections` + `post_organization_collection_update` 의 `if member.access_all { continue; }` 제거 → Owner 도 명시 users_collections row 생성.
- **Patch 0004**: `cipher.rs::to_json` User-sync branch 에 `permissions: {response: null, delete: <bool-escape>, restore: <bool-escape>}` 추가.

위 2 patch 는 organization permission model 의 mainline 정합 — 별 PR 로 분리 제출 권장 (review surface 분리 + 본 PR 의 compatibility-only 성격 유지).

## 8. Status

| Field | Value |
|---|---|
| Report state | Draft |
| 작성 일자 | 2026-05-28 |
| 제출 일자 | TBD (운영자 결정) |
| Timshel upstream 회신 | TBD |
| 수락 시 효과 | AXE fork 의 axe.2 diff 자연 소실 (`B-vault-axe.2-sso-mp-incomplete` archive) |

## 9. Submission channels

- **Repo**: https://github.com/Timshel/vaultwarden
- **PR title**: `Backport prelogin/password alias + connect/token AccountKeys/MasterPasswordUnlock from dani-garcia mainline (bw 2026.4+ compatibility)`
- **Label 권장**: `compatibility`, `mainline-backport`

운영자가 검토 후 위 채널로 PR 제출. 회신 수령 시 본 페이지 §8 표를 갱신하고 [/ops/backlog](/ops/backlog) 의 `B-vault-axe.2-patches-upstream-pr` 를 ✅ 로 이동.

---

<!-- PAGE https://docs.axelabs.ai/ops/roadmap -->

# 로드맵 (마일스톤)

> AXE Labs 플랫폼의 분기/마일스톤 수준 큰 그림. 단기 실행 항목은 backlog 참조.

URL: https://docs.axelabs.ai/ops/roadmap

# 로드맵 (마일스톤)

> 이 페이지는 **어디로 가는가** 의 큰 그림입니다. 다음 세션이 들어와서 "지금 무엇부터" 가 궁금하다면 [backlog](/ops/backlog) 가 entry point — 본 페이지는 그 백로그 항목들이 묶이는 상위 목표를 보여줍니다. 이미 ship 된 변경은 [updates](/ops/updates) 의 Ship Log + Highlights.
>
> **시간축 4 페이지** ([D-docs-updates-1](/ops/decisions)): [backlog](/ops/backlog) (현재) · **본 페이지** (미래) · [updates](/ops/updates) (과거) · [known-gaps](/ops/known-gaps) (사실).
>
> **상태**: 📐 설계 · 🔧 개발 · 🎯 검증 · ✅ 완료 · ⏸️ 보류
>
> **신규 마일스톤 등재 절차**: 본 표에 한 줄 추가 → 관련 [decisions.mdx](/ops/decisions) D-마일스톤-N 등재 → 실행 항목은 [backlog](/ops/backlog) 에 마일스톤 ID 로 묶기.

## 마일스톤 표

| ID | 마일스톤 | 목표 | 상태 | Target |
|---|---|---|---|---|
| **M1** | [Stage 0 → 1 외부 출시](#m1--stage-0--1-외부-출시) | Multi-tenant closed beta 진입 — 격리·법무·관측·복원 전부 충족 | 🔧 개발 | 2026 Q3 |
| **M2** | [frame 회계 도메인 확장](#m2--frame-회계-도메인-확장-axev-펀드-회계) | AXEV 펀드 (KIP/KVF) 회계 — 조합 회계·LP capital call·cross-entity mirror 분개 | 📐 설계 | 2026 Q3 |
| **M3** | [Blueprint PARA dispatch](#m3--blueprint-para-dispatch-d-bp-entity-1-pr-5) | Project 종결 → Area/Resource 로 copy-with-provenance 분배 + LLM 제안 + dispatch UI | 📐 설계 | 2026 Q3 |
| **M4** | [hive payroll v2 prod cutover](#m4--hive-payroll-v2-prod-cutover) | 한국 도메인 본질 7가지 (간이세액표·비과세·정산·일할 등) 검증 완료 후 실 사용 | 🎯 검증 | 2026 Q2 |
| **M5** | [Backup/DR 강화](#m5--backupdr-강화) | hive-postgres Tier A 합산 (✅) + restore drill 정기화 + mysrt 처리 결정 | 🔧 개발 | 2026 Q3 |
| **M6** | [Blueprint artifact + PARA 지식 레이어](#m6--blueprint-artifact--para-지식-레이어) | typed fact layer in Blueprint Postgres — citation-backed, PARA dispatch field-level 진화 | 📐 설계 | 2026 Q4 |
| **M7** | [index 투자 도메인 backend](#m7--index-투자-도메인-backend) | 펀드 lifecycle (소싱·DD·IC·포트폴리오·엑싯·IR) typed fact SoT. financial_model 6-table + fund_investment N:M + 5 skill 진화 | 📐 설계 | 2026 Q4 |

---

## M1 — Stage 0 → 1 외부 출시

**목표**: 현재 단일 customer (axec/axev) 운영 → 외부 customer 1~3개의 closed beta 진입. 5분야 점검 (2026-05-21) 의 모든 차단 사항 해소.

**근거 결정**: D-org-fanout (신규 예정), D-ops-15.5 (도메인 검증), D-ops-17~19 (secret 운영), D-config-15 (multi-customer 분기)

**의존성**:
- [backlog](/ops/backlog) 의 M1 태그 항목들 — tenancy FK 마이그레이션 · Azure AD 분기 · 법무 4페이지 · edge rate-limit · Sentry · `axe-health-monitor` · restore drill
- 첫 외부 customer 확정 (영업) — 본 로드맵 외 의사결정

**완료 정의**: 5분야 점검 표 모든 항목 ✅, 첫 외부 customer 운영 1주 + 회고 1회.

상세 현황: [known-gaps#multi-tenant](/ops/known-gaps) Multi-tenant 섹션.

## M2 — frame 회계 도메인 확장 (AXEV 펀드 회계)

**목표**: frame 이 corporate (axec/axev) 외에 **펀드 (KIP/KVF) 회계** 처리. AXEV 가 GP 인 일부 결성 조합 (수·타입 detail 대기) 의 정확한 출자금·미출자약정·운용보수·성과보수·평가손익·분배금 처리.

**근거 결정**: D-frame-N1~N4 (예정, decisions.mdx 의 frame 측 미완 표 참조).

**아키텍처 요지** (2026-05-22 drift 정정):
- 기존 `shared` schema 확장 (`frame_meta` 신설 X — 명명 충돌 + cross-entity 메타가 이미 shared 에 존재)
- `shared.entity` 에 `entity_kind` (corporate/kip/kvf) + `fund_meta` JSONB + `closed_at`
- `shared.entity_relationship` 확장 (% → numerator/denominator/unit, kind ENUM 에 `gp_managed_fund`/`lp_invested_fund`)
- `shared.cross_journal_link` 신설 (schema 격리 환경 mirror 분개 무결성)
- fund schema 내부: `commitment_ledger` + `lp_master` + (optional) `fund_waterfall_state`
- Blueprint workspace↔entity = **N:M** (`WorkspaceEntity` join) — D-bp-entity-1 plan 수정 필요

**의존성**:
- [backlog](/ops/backlog) 의 M2 태그 항목들 — migration 7단계
- 결성 조합 detail (사용자 입력) — 1~4 단계는 detail 없이 가능

**완료 정의**: 결성 조합 1개 schema bootstrap + 과거 결산 적재 + AXEV↔조합 mirror 분개 1회 검증.

상세: [known-gaps#frame-측-미완](/ops/known-gaps) frame 섹션의 7단계 migration 순서.

## M3 — Blueprint PARA dispatch (D-bp-entity-1 PR 5)

**목표**: Blueprint Project 종결 시 Area/Resource 로 artifact 이관 — copy-with-provenance + 검색 분리 + 정비 워크플로 + LLM 제안.

**근거 결정**: [D-bp-entity-1](/ops/decisions) (entity 개념 도입) + 본 세션 합의 4개 (PARA dispatch flow, 2026-05-21).

**합의 4개**:
1. **copy-with-provenance** — `sourceWorkspaceId` / `sourceArtifactPath` / `copiedAt` 3 필드 신설. 원본 frozen + 사본 fork
2. **검색 분리** — Archive = "그때 어떻게 생각했는지", Area/Resource = "지금 이렇게 생각한다"
3. **끊임없는 정비** — 일회성 도구 X, living document
4. **LLM 제안 + 사용자 confirm** — 완전 자동 X

**미결 3종** (PR 5 직전 결정):
- 분배 단위 (파일 vs 의미)
- Area 인스턴스 정의 권한 (org-admin vs free)
- 정비 트리거 우선순위 (수동 / 주기 / LLM 제안)

**의존성**:
- D-bp-entity-1 PR 1 의 provenance 3 필드 (Workspace 스키마 변경) 선행
- M2 의 Blueprint WorkspaceEntity N:M 마이그레이션 (entity 결정과 무관하지 않음 — 분배 단위 결정 시 entity 경계 고려)

**검토 권장 경로**: Path B Spike (DB 변경 없이 단일 workspace 로 흐름 검증 3-5일) → Path A 본 구현.

## M4 — hive payroll v2 prod cutover

**목표**: 한국 도메인 본질 7가지 (간이세액표 lookup · 비과세 분리 · 보수월액별 · 부양가족 · 정산 · 일할 · 보험별 라운딩) 의 첨부 급여대장 셀별 정확 일치 검증 후 axec/axev 실 운영 cutover.

**근거 결정**: [D-hive-21](/ops/decisions) ~ [D-hive-26](/ops/decisions) (payroll v2 + 발송 인프라 + 템플릿 + audit + event consumer).

**현 상태**: 기능 구현 끝, Phase 3 (payroll v2 실데이터) 운영 중. backup Tier A 합산 완료 (D-hive-backup).

**의존성**:
- [backlog](/ops/backlog) 의 M4 태그 항목 — 첨부 급여대장 cell-by-cell 비교, DKIM/DMARC DNS prod 확정, audit log 무결성 검증
- M5 의 restore drill (페이롤 데이터 백업 검증)

**완료 정의**: 2분기 (4월·5월) 전직원 급여 v2 로 산출 + 메일 발송 + 정산 일치.

## M5 — Backup/DR 강화

**목표**: 모든 platform postgres + critical state 의 Tier A 백업 (`axe-backup` 통합) + 정기 restore drill + DR cold storage rotation.

**근거 결정**: [D-config-14](/ops/decisions) (DR cold storage), [D-hive-backup](/ops/decisions) (hive Tier A 합산).

**현 상태**:
- ✅ frame-postgres / blueprint-postgres / hive-postgres Tier A 합산 끝
- 🔧 mysrt-postgres — SRT 외부 SOT 가능성 잔존 → 별도 결정 보류
- 🔧 restore drill — 1회 실시 후 정기화 미정

**의존성**: [backlog](/ops/backlog) 의 M5 태그 항목들 — restore drill 첫 실시 · mysrt 결정 · cold storage rotation 정기 cron.

**완료 정의**: 모든 postgres restore drill 1회 + 정기 drill cron + mysrt 처리 결정 등재.

## M6 — Blueprint artifact + PARA 지식 레이어

**목표**: Blueprint 의 markdown PKM (ctx) 위에 typed fact layer (`Artifact`). Per-field schema + citation + confidence + PARA scope. Cross-functional query / 결정론적 citation / time-travel / multi-agent concurrent read-write 가능.

**Status escalation (2026-05-26)**: M6 가 Cortex 의 Day 1 표준으로 escalation. Cortex ([D-cortex-1](/ops/decisions)) 가 platform 의 첫 artifact-first reference impl — Q4 2026 Blueprint stage 2 (full integration) 보다 6 개월 앞서 실 사용. Cortex 의 artifact / citation / artifact_event / mcp_schema 5 테이블 + RLS + append-only trigger 가 reference 구현. Blueprint 측 PARA dispatch UI 도입 시 Cortex 의 owner-scoped artifact 도 mirror 대상.

**근거 결정**: [D-bp-artifact-1~5](/ops/decisions) (본 마일스톤 등재 동반), [D-cortex-1](/ops/decisions) (Day 1 채택, Cortex reference impl), [D-bp-entity-1](/ops/decisions) (PARA + entity 골격), [D-bp-entity-2](/ops/decisions) (workspace-level provenance — 본 마일스톤이 field-level 로 진화), [D-config-16](/ops/decisions) (Blueprint Postgres).

**아키텍처**: [/architecture/artifacts](/architecture/artifacts) 참조 — `Artifact` 테이블 (JSONB content + citations) + 6-kind citation resolver + PARA dispatch engine + Query API + ctx 진화.

**3 Stage 구조** (활성화 조건 충족 시):

| Stage | 산출 | 기간 |
|---|---|---|
| 0. PoC | filesystem-only 첫 schema (예: IC §재무 또는 `PortcoBoardKPIArtifact` — domain MCP 가 없는 영역에서 LLM 자율 extract) — DB 변화 0 | ~3일 |
| 1. DB 진입 | `Artifact` + `Citation` + `artifact_link` Prisma migration, MCP schema discovery 인프라 (frame/hive `/schemas` endpoint + Blueprint fetch/cache/version), 4 paraLayer UI 페이지 신설 (`/axe/{projects,areas,resources,archive}`) | ~3-4주 |
| 2. Full integration | Dispatch field-level engine (copy + link 2 mode), Knowledge Overview dashboard, MCP tool paraLayer 분리 (`list_projects` / `list_areas` / etc.), ctx 진화 (curation mode + markdown 점진 migration flow) | ~3-4주 |

**의존성**:
- [M3](#m3--blueprint-para-dispatch-d-bp-entity-1-pr-5) PARA Dispatch (workspace-level provenance UI) — 본 마일스톤이 그 field-level 진화
- [M1](#m1--stage-0--1-외부-출시) multi-tenant rollout — 평행 가능 (외부 surface 영향 0), 다만 critical path 충돌 회피 위해 M1 main 진행 시 M6 secondary
- [backlog](/ops/backlog) 의 M6 태그 항목들

**완료 정의**: `Artifact` + `Citation` + `artifact_link` 테이블 production 적용 + MCP schema discovery active (frame/hive `/schemas` 등재) + 1개 deal 의 IC 가 raw markdown → artifact 경로로 실 사용 + ctx review 모드 가 typed fact 처리 + cross-PARA query 1개 use case 검증 + **AXEV 의 Area 4 (Finance / BOD / Legal / License) seed 완료 + 첫 Project close 가 적어도 1 Area 로 dispatch 검증**.

**Strategic 의미**: AI-native fund global best-in-class infra ambition 의 knowledge tier 도달. 현재 dev-co level infra (per-customer isolation / blue-green / OAuth-RP / restic backup) 위에 PKM tool 수준 knowledge layer 가 있던 격차 해소.

## M7 — index 투자 도메인 backend

**목표**: AXE Labs 7번째 vertical 서비스 — 펀드 운용 lifecycle (소싱 → 실사 → IC → 포트폴리오 → 엑싯 → LP IR) 의 typed fact SoT. frame (회계) / hive (HR) 와 같은 layer. Blueprint 의 5 skill (`ic` · `due-diligence` · `vc-deal-sourcing` · `portfolio-management` · `investor-relations`) 의 dataroom-bound run-time 산출물 (memo markdown / xlsx / yaml) 을 persistent typed artifact + cross-deal / cross-fund / time-travel query 가능한 형태로 승격.

**핵심 차별성** (frame/hive 와 다른 본질):
- **financial_model 6-table SoT** — xlsx 가 일급 entity 가 아니라 (driver / scenario / driver_value / output / exit_matrix_leaf) 의 typed model. DSL formula + topo evaluator 가 xlsx replay. ic skill 의 4 sanity check 가 DB CHECK 로 흡수
- **fund_investment(deal × fund × round) 3차원 N:M** — 한 deal 이 여러 펀드에서 동시 + 다른 시점 follow-on + 다른 instrument 로 들어갈 수 있음. 펀드별 IRR 독립 산출
- **Day 1 artifact-first** ([D-cortex-7](/ops/decisions) precedent 미러) — Rust + axum + sqlx + Postgres 16 RLS

**근거 결정**: [D-index-1~10](/ops/decisions) (본 마일스톤 등재 동반, 2026-05-27). 핵심 결정은 D-index-4 (financial_model 6-table) + D-index-5 (fund_investment N:M).

**아키텍처**: [/services/index](/services/index) 참조 — 서비스 main + 4 sub-page (financial-model / schema-catalog / skill-evolution).

**3 Phase 구조**:

| Phase | 산출 | 기간 |
|---|---|---|
| **0. Skeleton + 3 deal fixture** | `cp -R cortex index` byte-by-byte → Azure app + customers.yaml + docker-compose (postgres 4000 + mcp 4010/4011 + Caddy 4012) + cloudflared `^/index(/.*)?$` + MCP checklist 14 항목 + Phase 0 schema set (target_company · deal · fund_investment · financial_model 6-table + cortex artifact 4 테이블) + DSL parser + topo evaluator + 4 tools (`register_target_company` · `create_deal` · `propose_financial_model` · `compute_outputs`) + `/index/schemas` (14 schemas) + **Iippo/Sentry/Canopy seed yaml ingest → IRR 산출 ic skill 결과와 ±1pp 일치 검증** | ~6일 |
| **1. DD + IC + KPI 코어** | dd_finding / ic_decision / portfolio_kpi schema + ~15 tools + ic skill `--push-to-index` mode + Blueprint workspace ↔ deal N:1 매핑 + Blueprint MCP schema discovery 에 `index` 등재 + Blueprint UI 의 deal-level artifact citation resolver | ~2-3주 |
| **2. Cross-fund + LP + frame mirror + Exit + IR** | lp_comm / valuation / exit_signal / postmortem + frame cross_journal_link mirror (pg_notify `index_events` → frame LISTEN, capital call / distribution 자동 분개) + Blueprint cross-PARA query_knowledge (deal × kpi × time) + portfolio dashboard in Blueprint + IR 자동 보고 (hive payslip pattern) | ~3-4주 |
| **3. 판단기억 + portfolio-care + self-calibration** (2026-06, post-v1) | (Phase 0–2 의 financial_model·IC·typed-fact 위 — 이번 사이클에 **artifact-first 판단층 live**: [D-index-45](/ops/decisions) judgment layer · 46 seed=SoT · 47 skill ownership P0–P3.) 다음: **pmc 운영 파이프라인**(8-agent 분기 KPI/risk/NAV — post-money care → `index.portfolio_kpi`·`risk_alert`·`valuation_snapshot` typed fact) · **post-mortem 루프**(ic `postmortem_stub` → pmc fill → `index.postmortem`; IC 예측 vs 실제) · **Epic 3 self-calibrating**(prediction freeze → outcome 포착 → deal-class bias → 다음 IC 자동보정 — post-mortem 이 outcome 공급) · **Epic 2 confidence load-bearing** · **evidence durability**(citation path→`drive_item_id`/`sha256`; OneDrive 소스 이동·삭제에도 provenance 생존 — 현재 107 path·0 sha256 = 끊김 위험) | ~3-5주 |

**의존성**:
- [M2](#m2--frame-회계-도메인-확장-axev-펀드-회계) frame 펀드 회계 확장 — Phase 2 의 cross_journal_link mirror 가 frame 측 commitment_ledger 필요. M2 미완 시 Phase 0/1 stand-alone 가동 가능 (event_outbox 보류)
- [M6](#m6--blueprint-artifact--para-지식-레이어) Blueprint artifact + PARA — Phase 1 의 schema discovery 가 Blueprint M6 Stage 1 (DB 진입) 정합. 평행 가능
- [backlog](/ops/backlog) 의 M7 태그 항목들

**완료 정의**:
- (a) Phase 0: 3 deal (Iippo / Sentry / Canopy) seed yaml ingest 성공 + ic skill 의 `irr_analysis xlsx` 결과와 index `compute_outputs(model_id, scenario_id)` 결과 ±1pp 일치 + Iippo 1호 / 2호 IRR 각각 독립 산출 가능
- (b) Phase 1: 새 deal 1건이 ic skill 끝 → `--push-to-index` 로 typed fact propose → ctx review confirm → Blueprint artifact citation 으로 resolve
- (c) Phase 2: AXEV 펀드 1호 의 quarterly NAV report 가 100% index typed fact 위에서 산출 (markdown 자동 render — LP 보고 audit trail 보존)

**Strategic 의미**: AXE 의 본업 (펀드 운용) 이 finally 1st-class platform service 화. frame/hive 가 운영 backbone, index 가 본업 SoT. ic skill 의 markdown/xlsx 산출이 휘발성 artifact 에서 cross-deal / time-travel query 가능한 typed fact 로 진화 — IC 결정의 audit trail 영구 + LP 의 모든 숫자가 DB cell trace.

---

## 마일스톤 라이프사이클

| 단계 | 표시 | 다음 단계 조건 |
|---|---|---|
| **📐 설계** | 아키텍처/결정 미확정 | decisions.mdx 에 D-마일스톤-N 등재 |
| **🔧 개발** | backlog 항목 진행 중 | 모든 backlog M-태그 항목 ✅ |
| **🎯 검증** | 기능 끝, 운영 검증 | 운영 회고 + 완료 정의 충족 |
| **✅ 완료** | 운영 안착 | (1~2 분기 후 archive) |
| **⏸️ 보류** | 의존성/외부 차단 | 차단 해소 시 재개 |

## 변경 이력

| 일자 | 변경 |
|---|---|
| 2026-05-22 | 페이지 신설 + M1~M5 초기 등재 ([D-docs-roadmap-1](/ops/decisions)) |
| 2026-05-27 | M7 (index 투자 도메인 backend) 신설 ([D-index-1~10](/ops/decisions)) — 3 Phase + Iippo/Sentry/Canopy fixture |

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/cloudflared -->

# Cloudflared 재기동

> cloudflared 가 죽었거나 config 변경 시 5초 다운타임 절차.

URL: https://docs.axelabs.ai/ops/runbook/cloudflared

# Cloudflared 재기동

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/cloudflared 따라 axelabs-tunnel 재기동 진행해줘.

진행:
1. 현재 상태 진단 — `docker ps -a | grep axelabs-tunnel` + 외부 endpoint health (`curl -sI https://axe.axelabs.ai/frame/health`)
2. 페이지 시나리오 1 (죽음 감지) / 시나리오 2 (ingress config 변경) 중 분기 식별
3. 페이지의 각 명령 실행 + 검증, 매 step 결과 받고 다음. **절대 SIGHUP 금지** (cloudflared graceful reload 미지원) — docker restart 만 사용, 5초 다운타임 발생 사용자 사전 확인
4. 함정 — 본 runbook 은 axe-macmini 중앙 tunnel 만 다룸, customer 별 tunnel (`axelabs-{customer}`) 은 `axe onboard --apply` step 7 이 customer macmini 의 config 자동 push
5. 외부 endpoint 200 검증 + (선택) /ops/updates Ship Log
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

`axelabs-tunnel` (cloudflared) 가 죽거나 ingress config 변경이 필요할 때.

> **Tunnel layer 구분** (2026-05-23 정정): AXE 플랫폼은 **2 종류 cloudflared tunnel** 운용. 본 runbook 은 axe-macmini 의 **중앙 tunnel** (`axelabs-tunnel` 컨테이너 — `axe.axelabs.ai` / `docs.axelabs.ai` / `admin.axelabs.ai` 등 운영자 자기 서비스) 만 다룸. **customer 별 tunnel** (`axelabs-realchoice` 등 — `{customer}.axelabs.ai` 서빙) 은 `axe onboard` 가 customer macmini 의 launchd `com.axelabs.{customer}.cloudflared` 로 부팅하며 본 runbook 적용 안 됨. customer tunnel ingress 추가 시 `axe onboard --apply` 가 step 7 에서 자동 push.

## 절대 SIGHUP 금지

```
❌ docker kill -s HUP axelabs-tunnel
```

**검증된 사실 (2026-05-15)**: cloudflared 는 SIGHUP graceful reload **미지원**. SIGHUP 받으면 프로세스 종료.

→ docker restart 만 사용. 5초 다운타임 발생.

## 시나리오 1 — 죽음 감지

`com.axe.health-check` 또는 운영자 콘솔에서 cloudflared 죽음 감지:

```bash
# 상태 확인
docker ps -a | grep axelabs-tunnel
# Exited (1) 또는 Dead 표시

# 재시작
docker start axelabs-tunnel

# 5초 대기 후 검증
sleep 5
curl -sI https://axe.axelabs.ai/frame/health
# 200 OK
```

## 시나리오 2 — Ingress config 변경

신규 customer 추가 또는 path 추가 시:

```bash
# 1. config 편집
vim /Users/axe/.axe/tunnels/axelabs/config.yml

# 2. 검증
docker run --rm -v /Users/axe/.axe/tunnels/axelabs:/etc/cloudflared cloudflare/cloudflared:latest \
    tunnel --config /etc/cloudflared/config.yml ingress validate
# OK 면

# 3. 재시작 (다운타임 ~5s)
docker restart axelabs-tunnel

# 4. 새 ingress 동작 확인
sleep 5
curl -sI https://&lt;new-host&gt;/&lt;path&gt;
```

## 시나리오 3 — credentials 만료 / 회전

cloudflared 의 tunnel credentials (`d8efecdd-2c3f-42de-9925-501433e21394.json`) 는 일반적으로 만료 없음. 단, 의심 노출 시:

```bash
# 1. Cloudflare dashboard → Zero Trust → Networks → Tunnels → axelabs-tunnel → Configure → Rotate token

# 2. 새 credentials 파일 받아서 macmini 에 push
scp credentials.json axe-macmini:/Users/axe/.axe/tunnels/axelabs/

# 3. 재시작
docker restart axelabs-tunnel
```

## Ingress 변경 시 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| docker kill -s HUP | process 종료 | `docker restart` |
| frame upstream 을 cloudflared 에 직접 (host:port) | blue/green swap 불가 | axe-frame-proxy 경유 |
| path strip 기대 | 라우터에서 prefix 못 찾음 | 서비스에 `/frame` mount |
| catch-all (404) 라인 제거 | unhandled 호스트 가 임의 origin 으로 | 마지막 `service: http_status:404` 유지 |

## 다운타임 분산 운영

cloudflared 재시작 = **5초** 다운타임 (모든 customer 의 모든 서비스). 따라서:

- 가능한 한 **새벽 시간 (03:00 KST)** 에 수행
- 사전 알림 (customer admin 들에게 24h 전)
- 한 번에 여러 변경 묶어서 (재시작 1회 분량)

## 자동화 모니터링 (TBD)

현재는 운영자 콘솔 (`https://admin.axelabs.ai`, `com.axe.console.refresh` 매시 rebuild) 에서 health probe 결과 확인. 매분 단위 자동 알림 (`com.axe.health-check` launchd + `axe-health-monitor` script) 는 **향후 작업 항목**.

대안 (즉시 구현 가능):

```bash
# /Users/axe/.axe/bin/check-cloudflared.sh (TODO: 실제 launchd 등록)
if ! curl -sf https://axe.axelabs.ai/frame/health > /dev/null; then
    osascript -e 'display notification "cloudflared 또는 frame 죽음" with title "AXE Labs"'
fi
```

## 다른 cloudflared 인스턴스

축전된 다른 tunnel 들:

| Tunnel | 컨테이너 | ingress |
|---|---|---|
| axelabs-tunnel | `axelabs-tunnel` (Docker) | 플랫폼 (`*.axelabs.ai`) |
| cortex-tunnel | `com.cortex.cloudflared` (launchd) | cortex.axellc.com + mysrt.axellc.com |
| (기타 customer 측) | (각 customer macmini) | 각 customer 의 자체 |

각각 독립 운영. cortex-tunnel 죽음 ≠ axelabs-tunnel 죽음.

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/customer-onboarding -->

# 신규 Customer Onboarding

> 운영자 측 자동화 + 수동 touchpoints. D-day = vault 비번 + axe 2~3 줄.

URL: https://docs.axelabs.ai/ops/runbook/customer-onboarding

# 신규 Customer Onboarding

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/customer-onboarding 따라 신규 customer ([customer id]) D-day onboard 진행해줘.

진행:
1. D-day prerequisite 확인 — vault session unlock (bw + Keychain `axe.vault.session`, 8h cache) + customer IT 회신 `axelabs-bootstrap-{customer}.json` pack 수령 + customer macmini Tailscale ACTIVE direct
2. 페이지 Phase B 표 따라 5 step 중 현재 자동화 상태 분기 — `axe customers ingest` → `axe onboard --apply` → `axe deploy blueprint --apply` → `axe deploy hive --apply` (umbrella 미구현 시 순차)
3. 각 axe 명령은 dry-run (`--apply` 생략) 먼저 실행 + 변경 계획 사용자 확인 후 `--apply`. 매 step 결과 받고 다음. SSH 진입 / cloudflared ingress / vault collection 권한 점검 포함
4. 함정 발생 시 [/ops/known-gaps](/ops/known-gaps) 의 "D-day traps" 섹션 표 따라 우회 (Tailscale short alias / SSH non-login PATH / TXT+CNAME 공존 / keychain partition / bw cache stale / vault DOMAIN path / docker volume external 부재 / customers.yaml directory 잘못 생성 등 15+ 함정)
5. 5 step 완료 후 customer 측 health 검증 (frame/blueprint/hive 외부 endpoint 200) + Ship Log 한 줄 + customer IT 회신 ("배포 완료, 접속 안내")
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

신규 customer (예: realchoice) 의 macmini 에 AXE Labs 스택 전체를 배포하는 절차.

## D-day TLDR — vault 먼저 풀어두면 1 명령

> **목표** ([B-onboard-1shot](/ops/backlog)): D-day 운영자 입력 = **axe 명령 1 줄**.
> vault 의 `bw unlock` 은 **session prerequisite** (8 시간 cache) — D-day touchpoint 아님.

### Phase A — 세션 prerequisite (한 번, 이후 8 시간 자동)

| 작업 | 명령 |
|---|---|
| vault session unlock + Keychain cache | `bw unlock --raw \| security add-generic-password -s axe.vault.session -a ai@axellc.com -w "$(cat)" -U` |

이후 모든 `axe secret`/`axe onboard`/`axe deploy` 명령은 Keychain 의 BW_SESSION 자동 사용. 비번 재입력 없음.

### Phase B — Deploy touchpoint (umbrella 후 1 명령, 현재 5 명령)

| # | 운영자가 손대는 부분 | 자동화 | backlog |
|---|---|---|---|
| 0 | customer IT 에게 docs link 4 개 송부 (D-7) | ✅ 자력 — bootstrap.sh 가 docs.axelabs.ai 의 raw 로 노출 (2026-05-23 해소) | [B-onboard-bootstrap-publish](/ops/backlog) ✅ |
| 1 | `customers.yaml` 의 `{customer}` 블록 + services 슬롯 작성 | `axe customers add` = stub | [B-onboard-customers-add](/ops/backlog) |
| 2 | customer IT pack.json → vault + customers.yaml 흡수 | ✅ `axe customers ingest {id} {pack}` (2026-05-23 구현) — dry-run/`--apply` + ruamel round-trip (comment 보존) + idempotent | [B-onboard-azure-pack](/ops/backlog) ✅ |
| 3 | `axe onboard {customer} --apply` (cloudflared + frame, 18-step) | ✅ 자동 | — |
| 4 | `axe deploy blueprint {customer} --apply` (Blueprint, 11-step) | ✅ 자동 (SSO 미설정 부팅) | [B-onboard-bp-sso](/ops/backlog) |
| 5 | Hive stack 수동 (ssh + docker compose) | `axe deploy hive` 부재 | [B-onboard-hive-deploy](/ops/backlog) |

→ 위 5 개를 묶는 **umbrella 명령** [B-onboard-umbrella](/ops/backlog) 가 구현되면:

```bash
# 세션 prerequisite (8 시간 1 회)
bw unlock --raw | security add-generic-password -s axe.vault.session -a ai@axellc.com -w "$(cat)" -U

# D-day — 줄 1 개
axe deploy customer {customer} --from-pack ~/Downloads/axelabs-bootstrap-{customer}.json --apply
```

운영자 D-day 입력 = **0 회** (vault 살아있으면) 또는 **1 회** (vault 만료 시 unlock 한 번).

> 진정한 0 입력 D-day = (a) cron 이 `bw unlock` keep-alive 유지 + (b) umbrella 구현 + (c) pack.json 사전 수신. (c) 는 customer IT 측이 axelabs-bootstrap.sh 실행해서 안전채널로 보내주는 시점 의존 — 즉 운영자는 IT 회신만 기다리면 됨.

## D-day 실제 명령 (2026-05-26 시점, B-customer-deploy-generalization Phase 1 ✅)

```bash
# 0. 운영자 vault unlock (master password 1 회)
export BW_SESSION="$(bw unlock --raw)"
security add-generic-password -s axe.vault.session -a ai@axellc.com -w "$BW_SESSION" -U

# 1. customer IT 회신 받은 axelabs-bootstrap-{customer}.json 흡수 (one-shot)
#    sso.tenant_id + sso.apps.{}.client_id fill + services manifest 슬롯 추가
#    + vault push × 3 (3 client_secret) 묶음
axe customers ingest {customer} ~/Downloads/axelabs-bootstrap-{customer}.json --apply
#    (dry-run 으로 먼저 확인하려면 --apply 빼고 실행 → 변경 계획만 출력)

# 2. Cloudflare tunnel + DNS + cloudflared launchd 부트스트랩 (1-9 step)
axe onboard {customer} --apply --skip-frame
#    --skip-frame: frame stack 은 별도 `axe deploy frame` 로. 이전 18-step 묶음 패턴 폐기.

# 3. customer 측 bw vault session bootstrap (interactive 1회 — customer IT 가 실행)
#    operator 가 SSH 으로 helper 를 push 한 후 customer IT 에게 실행 요청:
scp /Users/axe/.axe/bw-bootstrap.sh {customer}-macmini:~/bw-bootstrap.sh
ssh -t {customer}-macmini "brew install bitwarden-cli && \
    ~/bw-bootstrap.sh https://<vault-url> <login-email>"
#    → ~/.bw-session (mode 600) 생성. wrapper 가 SSH non-interactive 호출 가능해짐.

# 4. service 3종 customer-측 deploy (각각 13-step, ~5-15 분 each)
axe deploy frame {customer} --apply
axe deploy blueprint {customer} --apply
axe deploy hive {customer} --apply
```

> ⚠️ **위 `{customer}` 는 `services:` 매니페스트를 선언한 *신규* customer 자리** — sovereignty/self-deploy 로 졸업한 고객(realchoice/Truvia)은 **대상 아님**. 그 고객은 자기 macmini 에서 secret·compose·Caddy 를 **자체 배포**하고, `customers.yaml` 에 `services:` 매니페스트가 *의도적으로* 없어 `axe deploy {svc} {customer}` 가 `services … not declared` 로 `sys.exit` 한다. 운영자 역할 = **software supply (code/image) + 외부 노출 (DNS·cloudflared catch-all)** 뿐. 근거: [/ops/decisions](/ops/decisions) (D-ops-40 / B-customer-sovereignty-architecture).

각 `axe deploy {service} {customer}` 가 동일한 13-step 흐름 수행:
preflight → clone → vault_check → secrets_bootstrap (auto-gen if missing) → env_local → wrapper push → network → (blueprint 만) frame_mcp_token → compose up → (frame 만) proxy push → health → (frame+hive) register_entities → ingress swap.

**`axe onboard --skip-frame` 권장 이유**: 이전 18-step 통합 흐름은 frame stack 까지 묶였으나, 이제 customer-측 deploy 가 일반화되어 `axe deploy frame {customer}` 로 분리 호출이 idempotent + 재시도 안전. onboard 는 cloudflared layer 만 담당.

## D-14 ~ D-7 (사전 협의)

| 작업 | 책임 |
|---|---|
| 1. 가격·SLA 협의 | 운영자 |
| 2. customer ID 정함 (`x`, `newco` 등) | 운영자 |
| 3. customer 측 IT 담당자 식별 | customer |
| 4. macmini 구매 (M2/M3, 16GB+, 512GB+) | customer |
| 5. Tailscale 가입 + key 교환 | 양측 |
| 6. customer 측 Microsoft 365 tenant 확인 | customer |
| 7. customer 측 도메인 검증 준비 (TXT record 추가 권한) | customer IT |
| 8. axelabs.ai zone 의 `{customer}` A record 추가 | 운영자 (Cloudflare) |

## D-7 (Azure 사전 등록 — customer IT 자력)

운영자가 customer IT 에게 보내는 것 = **링크 4 개** (별도 첨부 / 스크립트 메시지 X — 2026-05-23 `B-onboard-bootstrap-publish` 해소):

```
https://docs.axelabs.ai/partner             ← 4 단계 흐름 (entry)
https://docs.axelabs.ai/partner/macmini-prep  ← macmini 사전 준비 (Tailscale, SSH, 절전)
https://docs.axelabs.ai/partner/registration  ← Option A CLI 1 줄 (axelabs-bootstrap.sh)
https://docs.axelabs.ai/partner/handoff       ← JSON pack 회신 양식
```

customer IT 가 30 분 (Option A) ~ 45 분 (Option B) 작업 → `axelabs-bootstrap-{customer}.json` 회신 (또는 텍스트 8 개 값).

JSON pack 스키마: `axelabs-bootstrap/v1` — `tenant_id` + `apps.blueprint/vaultwarden/frame_mcp` 각각의 `client_id` + `client_secret` + (frame_mcp 만) `application_id_uri` + `scope` + `redirect_uris`. 운영자가 받으면 [B-onboard-azure-pack](/ops/backlog) 의 `axe customer ingest` 가 1 줄로 흡수 (구현 후) — 현재는 수동 paste + `axe secret push` × 3.

운영자가 받으면:
1. **client_secret 3개 → vault 로 push** (Keychain 직접 push 는 폐기 — 비밀의 SoT = Vaultwarden, [D-ops-17](/ops/decisions#d-ops-17--secret-deploy-time-pull)):
   ```bash
   axe secret push AZURE_{CUSTOMER}_BLUEPRINT_CLIENT_SECRET   --service blueprint   --customer {customer}
   axe secret push AZURE_{CUSTOMER}_VAULTWARDEN_CLIENT_SECRET --service vaultwarden --customer {customer}
   axe secret push AZURE_{CUSTOMER}_FRAME_MCP_CLIENT_SECRET   --service frame       --customer {customer}
   ```
   (각 명령은 `Value for ...:` 프롬프트 → 안전채널로 받은 값 붙여넣기. 매니페스트에 customer service 슬롯이 사전 등재돼 있어야 함 — [B-onboard-azure-pack](/ops/backlog).)
2. `customers.yaml` 에 entry 추가:
   ```yaml
   {customer}:
     legal_name: "<...>"
     primary_domain: "<...>"
     public_domain: "{customer}.axelabs.ai"
     entities: ["<...>"]
     tailscale_host: "{customer}-macmini"
     sso:
       provider: "microsoft_entra_id"
       tenant_id: "<...>"
       apps:
         blueprint:
           client_id: "<...>"
           client_secret_env: "AZURE_{CUSTOMER}_BLUEPRINT_CLIENT_SECRET"
           redirect_uri: "https://{customer}.axelabs.ai/api/auth/callback/azure-ad"
         vaultwarden:
           client_id: "<...>"
           client_secret_env: "AZURE_{CUSTOMER}_VAULTWARDEN_CLIENT_SECRET"
           redirect_uri: "https://{customer}.axelabs.ai/vault/identity/connect/oidc-signin"
         frame_mcp:
           client_id: "<...>"
           client_secret_env: "AZURE_{CUSTOMER}_FRAME_MCP_CLIENT_SECRET"
           application_id_uri: "https://{customer}.axelabs.ai/frame/mcp"
           redirect_uris:
             - "https://claude.ai/api/mcp/auth_callback"
             - "https://claude.com/api/mcp/auth_callback"
           scopes:
             - "openid"
             - "profile"
             - "email"
             - "https://{customer}.axelabs.ai/frame/mcp/mcp.access"
     user_entity_map: {}
     default_entities_by_domain:
       "&lt;primary_domain&gt;": ["&lt;entity&gt;"]
     onboarded: "&lt;date&gt;"
   ```
3. ~~cloudflared 중앙 tunnel ingress 편집~~ — **불필요** ([2026-05-23 drift 정정](/ops/known-gaps)). `axe onboard` 가 **customer 별 독립 tunnel** 을 customer macmini 에 생성/launchd 등록함 (`_render_cloudflared_config` in `/Users/axe/.axe/bin/axe`). 중앙 `/Users/axe/.axe/tunnels/axelabs/config.yml` 편집 의 D-7 의무는 사라짐. axe macmini 측 cloudflared 는 docs.axelabs.ai / admin.axelabs.ai 등 운영자 자기 서비스 전용.
4. ~~cloudflared 재시작~~ — 위와 동일. customer 측 tunnel 은 `axe onboard` step 8 의 launchd 가 자동 boot.
5. Cloudflare zone 의 axelabs.ai 에서 `{customer}` A record 추가 — **불필요**. `axe onboard` step 5 가 Cloudflare API 로 자동 CNAME 생성 (`<tunnel-uuid>.cfargotunnel.com`).

## D-day (~1 시간, 자동)

운영자 머신에서 — 상단 [D-day TLDR](#d-day-tldr--운영자-수동-touchpoints) 참조. 핵심 흐름:

```bash
# Dry-run 으로 확인 (변경 0)
axe onboard {customer}

# 실제 적용 (cloudflared + frame)
axe onboard {customer} --apply

# Blueprint (별도 명령 — 통합은 B-onboard-1shot)
axe deploy blueprint {customer} --apply
```

`axe onboard` 가 18-step 을 순차 실행 (Tailscale SSH 로 customer macmini 에 push):

| Step | 작업 (실제 axe CLI 코드 기준) |
|---|---|
| 1 | Tailscale up / customer macmini reachable 확인 |
| 2 | customer meta 검증 (customers.yaml entry, Tailscale FQDN) |
| 3 | SSH probe (key 인증) |
| 4 | cloudflared 터널 생성 (기존 있으면 reuse) |
| 5 | Cloudflare DNS A record 생성 |
| 6 | cloudflared credentials.json push → macmini |
| 7 | cloudflared config.yml push (ingress 규칙 포함) |
| 8 | cloudflared launchd plist 등록 + boot |
| 9 | cloudflared health check (curl /cdn-cgi/trace) |
| 10 | frame git clone + Dockerfile preflight |
| 11 | frame git submodule + asset 동기화 |
| 12 | macmini Keychain 에 secret push (vault, frame, blueprint, restic) |
| 13 | macmini .env.local 생성 (env_file 용) |
| 14 | docker compose up (postgres + frame-mcp-blue + frame-mcp-green + proxy) |
| 15 | frame-mcp /health/ready poll (max 60s) |
| 16 | `frame register-entity` × 각 entity + `frame migrate` |
| 17 | axe-frame-proxy alias = blue 로 설정 |
| 18 | cloudflared ingress alias swap (axe-frame-proxy 가 frame upstream) |

진행 중 어느 step 에서 실패하면 자동 rollback (기존 상태 유지). 운영자 화면에 명확한 오류 + 다음 단계 제시.

## D+1 (검증 + Vault 부트스트랩)

운영자 (`ai@axellc.com`) 측에서:

```bash
# 외부 health
axe health {customer}

# customer macmini ssh
ssh {customer}-macmini "docker ps"

# Blueprint admin 부여
ssh {customer}-macmini "docker exec blueprint-app pnpm prisma db execute --stdin" <<EOF
UPDATE User SET role = 'admin' WHERE email = '&lt;ADMIN_EMAIL&gt;';
EOF

# 첫 frame entity 등록 (chart auto-seed 적용, D-ops-21)
ssh {customer}-macmini "docker exec frame-mcp-blue python -m frame.cli register-entity --id &lt;entity_id&gt; --legal-name '<법인명>' --kind corporate --accounting-standard ksme"

# 첫 hive entity 등록 (frame mirror)
ssh {customer}-macmini "docker exec hive-mcp-blue python -m hive.cli register-entity --id &lt;entity_id&gt; --legal-name '<법인명>'"

# PII passphrase 2개 vault push + frame/hive deploy (axe customer 의 deploy-axep.sh 패턴)
# 일반화된 deploy-new-entity.sh 가 자동 처리 (D-ops-31 후속 일반화):
#   bash /Users/axe/.axe/vault/deploy-new-entity.sh &lt;customer&gt; &lt;entity_id&gt; "&lt;법인명&gt;"
```

### Vault 부트스트랩 — `axe vault bootstrap {customer}` ([D-ops-33](/ops/decisions))

운영자 mac 에서 1 명령:

```bash
# Dry-run (default) — 현재 4 key 적용 상태 진단
axe vault bootstrap {customer}

# 실 패치 + axe-vaultwarden force-recreate
axe vault bootstrap {customer} --apply
```

명령 자동 흐름:
1. SSH 로 customer macmini 의 `/Users/{ssh_user}/.axe/vault/docker-compose.yml` 읽음 (axe customer 는 local exec)
2. 4 key (D-ops-24/26/27) 적용 상태 진단 — 이미 OK 면 skip
3. 누락 key 만 patch (in-place, anchor = `SSO_SIGNUPS_MATCH_EMAIL` 다음 줄)
4. `docker compose up -d --force-recreate axe-vaultwarden`
5. Idempotent — 재실행 안전

적용되는 4 key:
```yaml
SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"   # D-ops-24
SIGNUPS_ALLOWED:                       "true"  # D-ops-26
SSO_ONLY:                              "false" # D-ops-27 — emergency MP fallback 보존
ORGANIZATION_INVITE_AUTO_ACCEPT:       "true"  # D-ops-27 — 직원 Accept 자동
```

(`INVITATIONS_ALLOWED=false` 는 기존 docker-compose 의 default — JIT 통일.)

이 명령 빠지면 첫 employee 가 "Failed to retrieve the invitation" / "Your provider does not send email verification status" 등 차단 ([D-ops-24](/ops/decisions), [D-ops-26](/ops/decisions), [D-ops-27](/ops/decisions) 참조).

## D+2 (직원 onboarding + Vault 첫 멤버 invite)

### 직원 SSO 안내

운영자 → customer admin 으로 [신규 직원 온보딩 URL](/onboard) 전달.

customer admin 이 자기 직원들에게 안내. 각자 [Frame connector 4-step setup](/onboard/claude-frame-setup) 따라 설정.

Vault 접속 안내 ([troubleshooting](/onboard/troubleshooting) 의 Vault 섹션 참조):
- 직링크: `https://{customer}.axelabs.ai/vault/#/sso`
- Identifier: 그 customer 의 org 이름 (예: AXE, REALCHOICE)

### Vault Organization + 직원 invite

customer admin (또는 운영자 SSH proxy) 가:

1. Web vault → Admin Console → org 생성 (`{CUSTOMER}` 대문자 권장, 예: AXE / REALCHOICE)
2. **dual-identity 권장 패턴** ([D-ops-29](/ops/decisions)):
   - `ai@{customer-domain}` = 자동화 / bot identity (Graph token 발행, proactive DM, agent run)
   - 실제 admin 직원 별도 계정 = 사람 작업 identity
   - 둘 다 vault Owner + access_all=1
3. 직원 invite — `/Users/axe/.axe/vault/invite-members.sh` 패턴 (customer 별 변수만 교체)
4. **Collection 구조 v1** ([D-ops-32](/ops/decisions)):
   - entity 1개 customer (예: realchoice): 4-collection 단순 구조
     - `Platform — Service Secrets` (operator only)
     - `Platform — Infrastructure` (operator only)
     - `{Customer Entity}` (전직원 RW)
     - `Shared Tools` (전직원 RW)
   - entity 다수 customer (예: axe 의 axec/axev/axep): 6-collection (entity별 분리)

## D+7 (안정화 점검)

- frame `audit_log` 활성? (실제 분개 1건 이상 발생?)
- backup 정상? (`restic -r /Users/axe/.axe/backups/local snapshots --password-file ...`)
- 직원 첫 시도 시 누락 없음?

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| customers.yaml entry 빠뜨림 | onboard 18-step 실패 | step 2 가 자동 검증 |
| ~~Cloudflare A record 없음~~ | (해소 — `axe onboard` step 5 가 자동 생성) | — |
| customer macmini sleep mode | onboard SSH 실패 | D-7 까지 절전 안 함 설정 |
| Tailscale key 교환 안 됨 | step 1 실패 | D-7 까지 양방향 ping 검증 |
| **customers.yaml `services:` 섹션에 customer 슬롯 없음** | `axe secret push` 가 매니페스트 lookup 실패 (`{env_name} not in manifest`) | `services.{svc}.{customer}.secrets[]` 슬롯 사전 등재. 현재 `axe` 만 등재됨 — realchoice 는 신규 작업 ([B-onboard-azure-pack](/ops/backlog)) |
| **Cloudflare API token vault 미등재** | `axe onboard` step 4 의 `_cf_token()` 실패 | 첫 onboard 전 1 회 `axe secret push` 로 등재 ([B-onboard-cf-token-doc](/ops/backlog)) |
| **Blueprint 가 SSO 미설정으로 부팅** | `axe deploy blueprint` 후 첫 로그인 실패 | 현재 `cmd_deploy_blueprint` docstring 명시 한계. customer Keychain 에 Azure secret 별도 push 필요 ([B-onboard-bp-sso](/ops/backlog)) |
| **Hive stack 자동 배포 명령 부재** | `axe deploy hive` 가 없어서 매번 ssh + docker compose 수동 | [B-onboard-hive-deploy](/ops/backlog) |
| Vault `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION` 미설정 | 첫 employee SSO "Your provider does not send email verification status" 차단 | D+1 의 Vault 부트스트랩 4-block ([D-ops-24](/ops/decisions)) |
| Vault `SIGNUPS_ALLOWED=false` + `INVITATIONS_ALLOWED=false` | 첫 employee JIT 가입 "Failed to retrieve the invitation" 차단 | D+1 의 4-block ([D-ops-26](/ops/decisions)) |
| Vault `SSO_ONLY=true` 설정 | Entra 장애 시 운영자 lockout (master password 진입 불가) | `SSO_ONLY: "false"` 유지 ([D-ops-27](/ops/decisions)) |
| Vault UI 이메일-first 화면이 SSO Identifier 가림 | 직원이 가입 절차 못 찾음 | `/vault/#/sso` 직링크 안내 ([troubleshooting](/onboard/troubleshooting)) |
| frame/hive entity 추가 시 PII passphrase 빠뜨림 | 그 entity 의 PII 작업 시점에 RuntimeError | `deploy-new-entity.sh` 가 PII passphrase 2개 vault push + ship 자동화 ([D-ops-31](/ops/decisions)) |
| customer Vaultwarden 의 bw CLI 자동화 시 BW_SESSION 직접 export 만 함 | `axe secret push` 실패 (keychain 만 읽음) | `security add-generic-password -s axe.vault.session -a ai@... -w "$BW_SESSION" -U` 단계 통합 ([D-ops-31](/ops/decisions) 부수 발견) |
| Vaultwarden Timshel 1.34.1-6 + bw CLI 2026.x | `TypeError: ... toWrappedAccountCryptographicState` crash | bw CLI 2025.7.0 pin (`npm install -g @bitwarden/cli@2025.7.0`). 항구 해소: [B-vault-upstream-migration](/ops/backlog) — dani-garcia/vaultwarden:1.36.0 native SSO ([D-ops-28](/ops/decisions)) |

## 다음 customer

- [신규 직원 등록](/ops/runbook/employee-onboarding)
- [Secret rotation](/ops/runbook/secret-rotation)

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/db-recovery -->

# Frame DB 복구

> frame-postgres 손상/migration 사고/silent corruption 대응.

URL: https://docs.axelabs.ai/ops/runbook/db-recovery

# Frame DB 복구

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/db-recovery 따라 frame DB 복구 진행해줘.

진행:
1. 현재 사고 진단 — 사용자 보고 증상으로 페이지 "시나리오 분류" 표의 5 시나리오 중 분기 식별 (migration / 사용자 실수 / macmini 손실 / silent corruption / postgres crash)
2. 즉시 대응 — frame container stop (사용자 추가 쓰기 차단) + restic 최신 snapshot 확인
3. 시나리오별 복구 절차 실행, 매 step 결과 받고 다음. destructive (drop database / restore from backup) 직전 사용자 확인
4. 함정 발생 시 페이지 본문 따라 우회 (Phase 5 stub `axe restore` 부재 → restic 직접 / silent corruption 의 부분 복원 범위 / migration rollback)
5. 정합성 검사 통과 (`integrity-check`) + frame 재기동 + (선택) /ops/known-gaps 사고 원인 한 줄
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

frame 의 PostgreSQL 데이터가 손상되었을 때 복구 절차.

## 시나리오 분류

| 사건 | 즉시 대응 | 복구 경로 |
|---|---|---|
| Migration 사고 (alembic 적용 후 정합성 깨짐) | 모든 frame container stop | local backup (Tier A) |
| 사용자 실수 (잘못된 분개 대량 등록) | 해당 entity 만 freeze | `reverse_journal` × 다수 OR 백업 |
| macmini 전체 손실 (도난·화재) | 새 macmini 셋업 | ring (Tier B) 또는 cold SSD (Tier C) |
| Silent corruption (검증 실패) | 정합성 검사 결과 분석 | 부분 복원 |
| Postgres 자체 crash | `docker restart frame-postgres` | 거의 자동 복구 |

## 시나리오 1 — Migration 사고

새 migration 적용 후 정합성 검사 실패:

```bash
ssh axe-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axec"
# → FAIL: balance mismatch in journal X
```

### 즉시

```bash
# 1. 모든 frame container stop (사용자 추가 쓰기 차단)
ssh axe-macmini "cd /Users/axe/frame && docker compose stop frame-mcp-blue frame-mcp-green"

# 2. Backup 최근 snapshot 확인
ssh axe-macmini "
  restic -r /Users/axe/.axe/backups/local snapshots \
    --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local)
"
# 어제 03:00 KST snapshot 찾기
```

### 복구

```bash
# 3. 어제 backup 으로 frame-postgres 복원
# `axe restore` 는 Phase 5 stub 상태 → 현재는 restic 직접 호출:
ssh axe-macmini "
  restic -r /Users/axe/.axe/backups/local \
    --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local -a axe-cli) \
    restore &lt;snapshot_id&gt; --target /tmp/restore --include 'frame-postgres/*'
"
# 그 후 docker exec frame-postgres pg_restore 또는 dump replay
# 정식 `axe restore` 자동화는 Phase 5 (D) 작업 항목

# 4. frame container restart (이전 코드 버전으로!)
ssh axe-macmini "cd /Users/axe/frame && git checkout &lt;previous-good-commit&gt;"
ssh axe-macmini "
  cd /Users/axe/frame &&
  set -a && source .env.local && set +a &&
  docker compose build frame-mcp-blue &&
  docker compose up -d --force-recreate frame-mcp-blue frame-mcp-green
"

# 5. 정합성 재확인
ssh axe-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axec"
# → OK
```

### 손실 분석

복원 후 손실 = 백업 시점 (어제 03:00) ~ container stop 시점 사이의 모든 쓰기.

```bash
# 손실된 audit_log 추출 (다른 백업 또는 in-memory)
ssh axe-macmini "docker exec frame-postgres psql -U frame -d frame -c \"
  SELECT * FROM axec.audit_log
  WHERE ts > '2026-05-20 03:00:00+09:00'
  ORDER BY ts;
\""
```

사용자에게 통지 + 수동 재입력 또는 잘못 적용된 migration 의 의도된 효과 분석.

## 시나리오 2 — 사용자 실수

회계사가 실수로 잘못된 분개 50건 등록:

### 우선 — `reverse_journal` 시도

```python
# Claude Code 에서
Frame:list_journals entity_id=axec, start_date=2026-05-20, status=posted

# 잘못된 journal_id 목록 확인 후
for jid in [...]:
    Frame:reverse_journal entity_id=axec, journal_id=jid, memo="실수 역분"
```

`reverse_journal` 은 새 journal 생성 (append-only). audit_log 에 모두 기록.

### 대량 (50건+) — 백업 복원

50건 넘으면 reverse 절차도 부담. 백업 복원이 더 깔끔:

```bash
# 1. 사용자의 다른 활동 멈추기 (claude.ai connector 비활성 요청)

# 2. 가장 가까운 valid backup 복원 — table-level restore 자동화 TBD
# 현재는 dump 전체 복원 후 손상 table 만 selective merge
# (정식 도구화 = Phase 5 D 항목)
```

table-level 복원이 가능한지 확인 필요 — restic 자체는 file-level 만 → pg_dump 의 selective restore 필요. 향후 도구화 검토.

## 시나리오 3 — macmini 전체 손실

가장 심각. 새 macmini 에 처음부터 셋업.

### 절차

```bash
# 1. 새 macmini 준비
# - macOS 클린 install
# - Tailscale 가입 + 운영자 key 등록
# - Docker Desktop install
# - axe CLI install: bash &lt;(curl -sSL https://docs.axelabs.ai/install/axe-cli.sh)

# 2. customers.yaml 의 entry 그대로 사용
# (운영자 머신에서 push)

# 3. 가장 신선한 백업 복원 (restic 직접 호출)
# ring peer (realchoice macmini) 측에서 pull:
ssh axe-macmini "
  restic -r sftp:realchoice@realchoice-macmini.tail090015.ts.net:/Users/realchoice/peer-backups/axe \
    --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local -a axe-cli) \
    restore latest --target /tmp/restore
"

# 또는 cold SSD 마운트 후
ssh axe-macmini "
  restic -r /Volumes/axe-cold-1/restic-repo \
    --password-file &lt;(종이메모) \
    restore latest --target /tmp/restore
"

# 4. frame onboard (axe CLI 의 `--skip-azure` 플래그 는 향후 추가 예정;
#    현재는 onboard 가 Azure 측 변경 자체를 하지 않으므로 일반 onboard 그대로)
axe onboard axe --apply

# 5. Microsoft 측 — redirect_uri 변경 불필요 (axe.axelabs.ai 도메인 그대로)

# 6. 검증
axe health axe
ssh axe-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axec"
ssh axe-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity axev"

# 7. 직원 통지
"frame 시스템 복구 완료. claude.ai 의 connector 는 그대로 작동합니다."
```

## 시나리오 4 — Silent Corruption

매일 자동 `integrity-check` 가 잡아냄. 발견 즉시:

1. 어느 entity, 어느 검사가 실패했는지 확인
2. 가장 가까운 valid snapshot 찾기 (전날 또는 그 이전)
3. table-level 또는 entity-level 복원
4. 사용자에게 통지 (해당 기간 데이터 재입력 필요할 수도)

## Restore Drill (분기별)

매 분기 (Jan/Apr/Jul/Oct 15) 자동 drill 이 실행:

1. 임시 staging 컨테이너 (`frame-mcp-drill`) 에 어제 backup 복원
2. `integrity-check` 4개 모두 통과 여부
3. 결과 → 운영자 Slack

drill 실패 = backup 자체 문제 (압축 손상, password 오류 등). 즉시 원인 분석.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 손상 발견 후 frame 미정지 → 추가 쓰기 누적 | 손실 확대 | 즉시 `docker compose stop` |
| ring peer 의 backup 도 손상되었을 가능성 | 양쪽 손상 | cold SSD 도 보유 |
| 복원 후 정합성 검사 안 함 | 잠재 손상 미발견 | `integrity-check` 필수 |
| pg_dump 의 schema-per-entity 옵션 누락 | 복원 시 entity schema 사라짐 | restic 의 raw file 복원 (PGDATA volume) |

## ⚠️ 현재 도구 상태

`axe restore --customer ... --tier ... --target ... --table ... --apply` 식의 통합 CLI 는 **Phase 5 (D) 작업 항목** — 현재 stub 상태. 본 runbook 의 실제 복구는 위에서처럼 **restic 직접 호출**.

자동화 완성 후 본 runbook 의 명령어 갱신 예정 — 그때까지 운영자는 restic CLI 직접 + docker exec 조합 사용.

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/deploy -->

# Blue/Green Deploy

> frame 무중단 배포 절차.

URL: https://docs.axelabs.ai/ops/runbook/deploy

# Blue/Green Deploy (frame)

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/deploy 따라 frame [customer] Blue/Green 배포해줘.

진행:
1. 현재 active color 확인 (`docker exec axe-frame-proxy` + network alias) + git log origin/main..HEAD 변경 미리보기
2. 자동 경로 (`axe deploy frame {customer} --apply`) 가능 판단, 안 되면 수동 9 step 분기
3. 페이지의 각 step 실행 + 매 step 결과 받고 다음. 특히 alias swap 직전 사용자 확인 (passive health 60s 통과 검증 후) + 기존 active stop 전 60s grace 대기
4. 함정 발생 시 페이지 본문 따라 우회 (health check 60s timeout / in-flight grace 미준수 / mcp-proxy upstream 미반영)
5. 새 active 첫 요청 검증 (`curl https://axe.axelabs.ai/frame/health` 200) + (선택) /ops/updates Ship Log
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

다운타임 0 으로 frame 새 코드 적용.

## 자동 (권장)

```bash
# Dry-run 으로 변경사항 미리 확인
axe deploy frame axe

# 실제 적용
axe deploy frame axe --apply
```

`axe deploy frame {customer}` 가 자동으로 처리:

| Step | 작업 |
|---|---|
| 1 | git pull origin main |
| 2 | passive container 의 새 코드로 build (예: green 이 passive 면 green build) |
| 3 | passive container start |
| 4 | 헬스체크 통과 대기 (poll `/health/ready`, max 60s) |
| 5 | docker network alias `frame-mcp` 이동 (active → passive) |
| 6 | 새 active 의 첫 요청 정상 처리 검증 |
| 7 | 기존 active (현재 passive) 의 in-flight 요청 60s grace |
| 8 | 기존 active stop |
| 9 | 운영자에게 deploy 완료 알림 |

총 5-7 분 (build 시간 포함). 사용자 측 다운타임: 0.

## 수동 (응급, axe CLI 사용 불가 시)

### 1. 현재 active color 확인

```bash
docker exec axe-frame-proxy cat /etc/caddy/Caddyfile     # mount 위치 (frame-proxy/docker-compose.yml 의 :ro) | grep upstream
# 또는
docker network inspect frame_default | grep -A 2 'frame-mcp"'
# Aliases 에 `frame-mcp` 표시된 컨테이너가 active
```

active = blue 가정.

### 2. green 에 새 코드 build

```bash
cd /Users/axe/frame
git pull origin main

set -a && source .env.local && set +a
docker compose build frame-mcp-green
docker compose up -d --force-recreate frame-mcp-green
```

### 3. green health check

```bash
sleep 10
curl -s http://localhost:3711/health/ready
# → {"status":"ok"}
```

### 4. alias 이동 (blue → green)

```bash
# blue 에서 alias 제거
docker network disconnect frame_default frame-mcp-blue
docker network connect frame_default frame-mcp-blue   # alias 없이 다시

# green 에 alias 부여
docker network disconnect frame_default frame-mcp-green
docker network connect --alias frame-mcp frame_default frame-mcp-green
```

> 위 절차는 axe-frame-proxy 의 upstream resolution 이 즉시 갱신. Caddy 가 alias 기반이라 DNS 캐시 없음.

### 5. axe-frame-proxy 갱신 확인

```bash
docker exec axe-frame-proxy cat /etc/caddy/Caddyfile     # mount 위치 (frame-proxy/docker-compose.yml 의 :ro) | grep frame-mcp
# upstream 이 frame-mcp:3710 그대로 (alias 가 green 으로 이동)
```

### 6. blue 의 in-flight 요청 완료 대기 + stop

```bash
sleep 60   # in-flight grace
docker stop frame-mcp-blue
# 다음 deploy 시 새 코드로 build 됨 (현재 passive)
```

## 검증

```bash
# 외부 호출 확인
curl -s https://axe.axelabs.ai/frame/health
# → 200 OK + service: frame-mcp

# 새 코드 버전 확인
docker exec frame-mcp-green python -c "import frame; print(frame.__version__)"
```

## Rollback (5초)

문제 발견 시 alias 만 되돌리면 끝:

```bash
docker network disconnect frame_default frame-mcp-green
docker network connect frame_default frame-mcp-green
docker network connect --alias frame-mcp frame_default frame-mcp-blue
```

blue 가 다시 active. 새 코드는 green 컨테이너에 그대로 (다음 시도 시 fix 후 재배포).

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `docker compose up --build` 단일 컨테이너로 (블루든 그린이든) | 30-60s 다운타임 | blue+green 동시 운영 필수 |
| `--force-recreate` 없이 env 변경 적용 | 새 env 안 읽음 | 항상 `--force-recreate` |
| customer macmini 에 docker daemon 죽음 | proxy 도 죽음 | `launchctl kickstart` 로 docker 재시작 |
| build 실패 (Dockerfile 오류) | passive 컨테이너 stop | git revert + 재시도, blue 는 영향 없음 |

## 다른 서비스

- **blueprint** — 단일 컨테이너, 짧은 다운타임 수용 (`docker compose up -d --force-recreate blueprint`)
- **vault** (Vaultwarden) — 단일 컨테이너, 다운타임 시 사용자 vault 로그인 불가 (rare op, 야간 작업)
- **stream / magnet** — 각 customer 측 자체 운영

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/deploy-ssot -->

# 배포 SSOT 아키텍처

> origin/main 의 commit SHA = 배포의 진실원천. worktree 작업격리 + build-from-SHA + deploy lock + 스테이지 상태기계 + migration-validation 게이트로 다중 세션 배포 엉킴을 구조적으로 제거.

URL: https://docs.axelabs.ai/ops/runbook/deploy-ssot

# 배포 SSOT 아키텍처 — `origin/main` SHA = 배포 진실원천

> **원칙 (한 줄)**: `origin/main 의 commit SHA = 배포의 SSOT.` working tree·로컬 main·실행 중 컨테이너는 전부 그 SHA 의 파생·일회용 투영이다.

AXE 가 docs·backlog(matrix-postgres, [D-matrix-3](/ops/decisions))에 이미 적용 중인 SSOT 규율을 **배포**로 확장한 것. 결정 근거 = [D-ops-42](/ops/decisions).

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/deploy-ssot 따라 배포 SSOT 아키텍처를 rollout 해줘.

진행:
1. 현재 상태 진단 (어느 컴포넌트 A–F 가 이미 있고 어느 게 없는지 + axe CLI 버전관리 여부 + 지금 라이브 SHA vs origin/main drift)
2. additive 원칙 확인 — 각 컴포넌트는 기존 동작과 공존하게 추가 (기존 axe deploy/ship 경로 안 깨고)
3. 각 컴포넌트 추가마다 --dry-run + passive-color 카나리 (flip 안 함) 로 검증, flip 은 게이트 (사용자 확인)
4. migration 포함 릴리스면 ephemeral DB clone 검증 게이트 통과 후에만 flip
5. cutover (기본값 flip + pre-push 훅/branch protection 가드 활성화) 는 escape hatch 포함 + 사용자 확인 후
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## 동기 — 공유 tree + 공유 main 의 세 고장

다중 동시 Claude Code 세션이 repo 당 (frame / blueprint / hive / index / cortex / matrix) **1 working tree + 1 `main`** 을 공유한다. 여기서 세 고장이 동시에 난다:

| 고장 | 메커니즘 |
|---|---|
| push 거부 | 타 세션이 먼저 push → 로컬 `main` 이 origin 과 diverge → non-fast-forward → push blocked |
| WIP 혼재 | 서로 다른 feature 의 uncommitted 변경이 한 tree 에 누적 → 누구도 자기 slice 만 clean commit 불가 |
| dirty 누출 | `axe deploy` 가 dirty working tree 에서 이미지 빌드 → uncommitted 코드 prod 누출 + push 전 배포 가능 |

**실측 (2026-06-04)**: 이미 배포까지 끝난 blueprint fix (commit `b4067504`) 가 main diverge + 타 세션 WIP 로 수 시간 push 불가 → 운영자가 손으로 reconcile (stash → rebase → push). 같은 병의 가장 깊은 사례 = 운영자 `axe` CLI (364KB) 자체가 **버전 미관리 + in-place 편집** — 배포 도구인데 자기 자신은 SHA 추적 밖.

## 스테이지 파이프라인

blue/green 이 이미 canary/live/previous 3스테이지를 제공한다. 거기에 migration-validation 게이트 하나만 끼운다:

```
   ┌─────────┐      ┌────────────────────┐      ┌──────────────────────┐      ┌────────────┐      ┌──────────────────────┐
   │  built  │ ───► │ canary             │ ───► │ [migration-validation │ ───► │ live       │ ───► │ previous             │
   │ <svc>:  │      │ passive color      │      │  게이트]              │      │ active     │      │ 직전 active          │
   │ <sha>   │      │ 트래픽 0           │      │ ephemeral DB clone 에  │      │ flip       │      │ = 즉시 롤백 타깃     │
   └─────────┘      │ health 검증        │      │ migration 적용·검증    │      │ (alias swap)│      └──────────────────────┘
        ▲           └────────────────────┘      └──────────────────────┘      └────────────┘                 │
        │                                                  │ fail                                              │ rollback
        │ build-from-SHA (clean checkout)                  ▼                                                   ▼
   pushed SHA only                                    flip 거부                                          alias 되돌림 (5초)
```

- **built** — pushed SHA 의 clean checkout 에서 이미지 빌드, 태그 `<svc>:<sha>`. push 안 된 SHA 는 여기 진입 거부.
- **canary** — passive color 에 배포, 트래픽 0. health 검증만 (active 영향 0).
- **migration-validation 게이트** — 스키마 변경 포함 시에만. prod DB 의 ephemeral clone 에 migration 적용·검증. fail = flip 거부.
- **live** — active color flip (alias swap). 사용자 다운타임 0.
- **previous** — 직전 active = 즉시 롤백 타깃 (alias 되돌림 5초, [Blue/green deploy](/ops/runbook/deploy) § Rollback).

## 컴포넌트 A–F — 각자 제거하는 고장

각 컴포넌트는 *특정 고장 하나*를 구조적으로 없앤다.

### A. 작업 격리 — `axe work <svc> <slug>`

세션마다 origin/main 에서 분기한 git worktree (`~/.worktrees/<svc>/<slug>`). 정규 repo 는 **fast-forward 전용 "main mirror"** 로 강등 (손편집 금지 — mirror 는 origin 의 읽기 투영일 뿐).

**제거하는 고장**: 공유 tree 경합 · WIP 혼재 · stash 더미 = **발생 불가능**. 각 세션이 자기 tree 에서 자기 slice 만 commit.

### B. SHA 에서만 빌드

deploy 가 working tree 가 아니라 **pushed SHA 의 clean checkout** (`git worktree --detach <sha>` 또는 `git archive`) 에서 이미지를 빌드한다. 이미지 태그 = `<svc>:<sha>`. push 안 된 SHA 는 배포 거부.

**제거하는 고장**: deploy-before-push + dirty-tree 누출 = **구조적 불가능**. 빌드 입력이 origin 에 도달한 SHA 로 한정되므로 uncommitted 코드가 prod 에 갈 경로 자체가 없음.

### C. Deploy lock

서비스당 배포 직렬화. matrix-postgres `pg_advisory_lock` 우선 (이미 matrix DB 가 SSOT), 파일락 fallback (matrix down 시).

**제거하는 고장**: 두 세션이 같은 서비스 blue/green 을 동시에 flip → alias 경합 / 어느 color 가 active 인지 불명 = 불가능.

### D. Provenance + drift

컨테이너에 `org.axe.git_sha` 라벨 부여. `axe health` / `axe host` 가 color 별 실행 SHA + origin/main 대비 drift 를 표시.

**제거하는 고장**: "지금 라이브가 git 과 일치하나" 가 silent 하게 불명이던 상태. 항상 답이 나옴 (drift 가시화).

### E. 잘못된 경로 제거

`axe deploy` 가 더 이상 tree 입력을 받지 않는다 (B 가 SHA 입력으로 대체). `git push origin main` 직접 = **pre-push 훅 + GitHub branch protection** 으로 기계적 차단. `axe ship` 만 main 을 전진시킨다.

**제거하는 고장**: 현재는 "main 직접 push 금지" 가 honor-system (사회적 규약뿐, [D-ops-16](/ops/decisions)). 훅 + branch protection 으로 기계적 강제 전환.

### F. 통합 ship 흐름 — `axe ship`

worktree 에서 한 명령으로:

```
fetch → origin/main 에 rebase → SHA 에서 build + test → push (main fast-forward)
      → 그 SHA 를 deploy (C 의 lock 하에) → main mirror fast-forward → shiplog 기록
```

**제거하는 고장**: 오늘 운영자가 손으로 한 reconcile (fetch / stash / rebase / push / deploy / 정리) 전 단계가 한 명령으로 압축. `b4067504` 같은 incident 가 명령 한 줄로 끝남.

## 안전한 rollout — additive → canary → cutover

전부 비파괴. 진행 중 WIP 보존.

1. **additive** — A–F 각 컴포넌트는 기존 동작과 **공존**하게 추가. 기존 `axe deploy` / `axe ship` 경로를 깨지 않음.
2. **canary 검증** — 각 컴포넌트를 `--dry-run` + passive-color 카나리 (flip 안 함) 로 검증. active 트래픽 영향 0.
3. **migration 게이트** — 스키마 변경 포함 릴리스는 ephemeral DB clone 검증 통과 후에만 flip.
4. **cutover** — 기본값 flip 전환 + 가드 활성화 (pre-push 훅 / branch protection). escape hatch 포함 (응급 시 우회 경로). 게이트됨 (운영자 확인).
5. **되돌림** — 문제 시 previous color alias 되돌림 (5초) + 가드 비활성화로 이전 운영 모델 복귀.

## 왜 별도 staging 환경을 안 쓰나

별도 staging *환경* (staging.axelabs.ai + 독립 DB + 독립 터널) 은 **채택 안 함**.

- AXE 는 단일 Mac mini 호스트. staging 환경을 띄워도 prod 와 같은 호스트 → 새 실패유형을 **안 잡음** (호스트·네트워크·DB 엔진 동일).
- 비용 (컨테이너 2배 + DB 2배) 과 parity 유지 부담 (staging 이 prod 와 drift 하면 검증 가치 0) 만 증가.
- 실제로 막아야 할 위험 = (a) 깨진 코드가 트래픽 받기, (b) 깨지는 스키마 변경. (a) 는 **passive-color 카나리** (트래픽 0 에서 health 검증) 가, (b) 는 **migration-validation 게이트** 가 이미 커버.

canary + migration-validation 이 staging 의 실효를 단일 호스트 비용 0 추가로 달성한다.

## 왜 migration-validation 이 본질인가

blue/green 의 **유일한 사각**이 스키마 마이그레이션이다.

- blue 와 green 은 **DB 를 공유**한다 (코드만 2벌, 데이터는 1벌).
- 따라서 green 용 마이그레이션을 적용하면 **blue 도 즉시 그 스키마를 본다**. 깨지는 변경 (컬럼 drop / 타입 변경 / NOT NULL 추가) 은 green flip 전에 이미 blue 를 오염시킨다.
- 즉 스키마 변경은 blue/green 으로 **카나리가 원천적으로 불가능** — passive color 검증이 active 를 보호하지 못함.

migration-validation 게이트가 이 사각을 덮는다: flip 전에 **prod DB 의 ephemeral clone** (`axe drill` / backup 스냅샷 기계 재사용) 에 마이그레이션을 적용·검증. clone 에서 깨지면 flip 거부 → 공유 DB 는 손대지 않음. 대상 예 = blueprint 대기 migration 2개 (`add_user_entra_oid`, `add_entity_legal_name`), hive alembic.

## 관련

- [D-ops-42](/ops/decisions) — 본 아키텍처 결정 근거 (컴포넌트 A–F 상세 + 실측 incident)
- [Release flow (`axe ship`)](/ops/runbook/release-flow) — F 의 ship 흐름이 확장하는 기존 release-gate ([D-ops-16](/ops/decisions))
- [Blue/green deploy](/ops/runbook/deploy) — 스테이지 파이프라인의 alias swap + 5초 rollback 메커니즘
- [D-matrix-3](/ops/decisions) — matrix-postgres SSOT (C 의 advisory lock + backlog/roadmap/updates 작업 스테이지)

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/employee-offboarding -->

# 직원 퇴사

> 퇴사한 직원의 모든 access 차단 절차.

URL: https://docs.axelabs.ai/ops/runbook/employee-offboarding

# 직원 퇴사 (운영자 측)

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/employee-offboarding 따라 퇴사 직원 access 차단해줘.

진행:
1. 퇴사 정보 확인 (email + 퇴사일 + 즉시 차단 여부)
2. 페이지 step 1 — customer IT 측 Microsoft 365 사용자 비활성 (Entra ID OAuth 차단, 토큰 60-90분 내 자동 만료)
3. 페이지 step 2 — `customers.yaml` 의 `user_entity_map` 에서 해당 email 제거 또는 주석, 사용자 확인 후 적용
4. 페이지 step 3 — customer macmini 측 frame 재기동, 매 step 결과 받고 다음. 함정 — 토큰 캐시 60-90분 미만료 / customers.yaml comment 처리 vs 삭제
5. 페이지 step 4 (선택) — 직원이 client_secret 알고 있던 정황 시 [secret-rotation](/ops/runbook/secret-rotation) playbook 으로 분기
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

customer admin 으로부터 퇴사 알림:

```
퇴사: kim.minsoo@axellc.com
퇴사일: 2026-06-30
요청: access 즉시 차단
```

## 즉시 (퇴사일 ≤24h 전)

### 1. customer 측 Microsoft 365 사용자 비활성

customer IT 가 처리. 이거 하나만 해도 Microsoft Entra ID OAuth 가 차단 — 즉, frame 도 자동 차단.

직원 본인의 access_token 이 캐시되어 있더라도 60-90분 내 만료.

### 2. customers.yaml 에서 entity 매핑 제거

```yaml
axe:
  user_entity_map:
    "ai@axellc.com": ["axec", "axev"]
    "cfo@axellc.com": ["axec", "axev"]
    # "kim.minsoo@axellc.com": ["axec"]    # ← 제거 (또는 주석 처리)
```

### 3. frame 재기동

```bash
ssh axe-macmini "
  cd /Users/axe/frame &&
  set -a && source .env.local && set +a &&
  docker compose restart frame-mcp-blue frame-mcp-green
"
```

이후 그 직원의 토큰이 frame 에 도달해도 `EntityNotAuthorizedError` 로 거부.

### 4. claude.ai 측 secret 회전 (선택)

만약 그 직원이 회사 client_secret 값을 알고 있던 상황 (Vaultwarden 등) → 의심 시 회전:

→ [Secret rotation](/ops/runbook/secret-rotation) 절차 (응급).

악의 없는 정상 퇴사면 회전 안 해도 무방 (직원의 Microsoft 계정이 비활성화되어 secret 으로도 OAuth 시작 못 함).

## 24h 후

### 5. Audit (직원 마지막 활동 기록)

```bash
ssh axe-macmini "docker exec frame-postgres psql -U frame -d frame -c \"
  SELECT actor, op, table_name, ts
  FROM axec.audit_log
  WHERE actor = 'kim.minsoo@axellc.com'
  ORDER BY ts DESC
  LIMIT 30;
\""
```

- 마지막 활동 timestamp 확인 (정상 종료 vs 의심 패턴)
- 이상 활동 있으면 customer admin 에게 통지

### 6. 보관

audit_log 는 자동으로 영구 보관 (append-only). 별도 export 불필요. 향후 감사 필요 시 actor 로 조회.

## 1 주일 후

### 7. (선택) Vaultwarden organization 에서 제거

만약 Vaultwarden 멤버였으면 organization 에서 제거:

```bash
# Vaultwarden admin UI
# Organizations → axe → Members → kim.minsoo@axellc.com → Remove
```

또는 `bw` CLI 로:
```bash
bw config server https://axe.axelabs.ai/vault
bw login
# (subcommand 로 organization member remove)
```

> **주의 — vault 의 trust boundary**: vault item delete 는 **그 secret 의 저장 위치에서만** 차단. 외부 service (Microsoft / GitHub / KB / 홈택스 등) 의 계정·2FA·OAuth client_secret 은 별 절차 필요. 상세: [/architecture/vault-policies#vault-scope--무엇을-보호하는가-trust-boundary](/architecture/vault-policies). 다음 step 8 표를 vault remove 와 **반드시 병행**.

### 8. 외부 service 권한 회수 (vault scope 외)

vault item 을 지웠다고 그 secret 이 가리키는 외부 service 측 access 가 자동 차단되지 않음. service 마다 별도 admin 절차 필요. 회수 누락 시 그 service 의 access 잔존 + 데이터 export risk.

| 외부 service | 회수 작업 | 책임자 |
|---|---|---|
| Microsoft 365 / Entra ID | 계정 비활성 (= step 1 그대로) | customer IT admin |
| GitHub `axelabs-ai` org | org member 제거 + 본인 PAT 의 server 측 revoke 요청 | 운영자 |
| KB / 홈택스 / 회계법인 portal | 해당 portal admin 의 계정 비활성/삭제 + TOTP secret regenerate (잔존 device 차단) | customer admin |
| Cloudflare Access | user 를 Access policy 에서 remove | 운영자 |
| Anthropic / OpenAI / 기타 API key | 해당 console 에서 API key revoke (vault item 삭제와 별개) | 운영자 |
| OAuth client_secret (직원이 알던 정황) | Azure / Google 측 client_secret 재발급 → 옛값 폐기 | 운영자 (→ [secret-rotation](/ops/runbook/secret-rotation)) |

→ 각 row 를 vault item 삭제와 **쌍으로 처리**. 둘 다 끝나야 회수 완료.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| Microsoft 비활성만 하고 customers.yaml 안 건드림 | 그 직원의 토큰이 만료 후 OAuth 재시도하면 frame 가 entity 매핑 발견 후 통과 가능성 | 둘 다 처리 |
| frame 재기동 잊음 | YAML 변경 안 반영 | 매번 restart |
| 마지막 activity audit 안 함 | 의심 활동 놓침 | 24h 후 확인 |
| vault 만 처리하고 외부 service 안 건드림 | 그 service 측 access 잔존 (KB/홈택스/GitHub/Anthropic 등) + 데이터 export risk | step 8 표 row 별 외부 service 회수 동반 — vault item delete 는 "저장소 차단" 일 뿐. trust boundary = [/architecture/vault-policies#vault-scope--무엇을-보호하는가-trust-boundary](/architecture/vault-policies) |

## 응급 — 의심 활동 발견 시

만약 audit_log 에서 의심 활동 (대량 export, write 폭주 등) 발견:

1. customer admin 에게 즉시 통지
2. 그 직원의 모든 활동 추출 (audit_log 전체)
3. 영향 받은 entity 의 daily integrity check 결과 재확인
4. 필요 시 백업으로 복원 검토
5. customer 요청 시 외부 감사인에게 audit_log 인도

audit_log 는 모든 write 의 old_data + new_data 를 JSONB 로 기록 → 정확한 변경 내용 복원 가능.

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/employee-onboarding -->

# 신규 직원 등록

> customer admin 으로부터 신규 직원 추가 요청 받았을 때 운영자 절차.

URL: https://docs.axelabs.ai/ops/runbook/employee-onboarding

# 신규 직원 등록 (운영자 측)

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/employee-onboarding 따라 신규 직원 등록해줘.

진행:
1. customer admin 요청 정보 확인 (email + 업무 + 필요 entity 권한)
2. 페이지 step 1 — `customers.yaml` 의 `user_entity_map` 에 한 줄 추가 (`"<email>": [<entity>...]`), 매 변경 사용자 확인
3. 페이지 step 2 — customer macmini 측 frame 재기동 (`docker compose restart frame-mcp-blue frame-mcp-green`, ~5초)
4. 함정 — entity 명 typo / scope 별도 분리 미구현 (default `read/write/close` 부여) / customer macmini SSH 진입 실패
5. 페이지 step 3 검증 (`axe health frame`) + 직원에게 onboarding 안내 송부 ([/onboard/ssh-access](/onboard/ssh-access) + [/onboard/vault-setup](/onboard/vault-setup) + [/onboard/claude-connectors](/onboard/claude-connectors) playbook 3종)
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

customer admin 으로부터:

```
신규 직원: kim.minsoo@axellc.com
업무: 회계 (axec)
필요 권한: axec read+write
```

같은 요청 받았을 때.

## 1. customers.yaml 수정

```yaml
axe:
  user_entity_map:
    "ai@axellc.com": ["axec", "axev"]
    "cfo@axellc.com": ["axec", "axev"]
    "kim.minsoo@axellc.com": ["axec"]    # ← 추가
```

→ entity 만 매핑. scope 는 기본값 (`read`, `write`, `close`) 모두 부여 — 권한 별도 분리는 별도 작업 (D-ops-?, 향후).

## 2. frame 재기동 (customers.yaml reload)

```bash
ssh axe-macmini "
  cd /Users/axe/frame &&
  set -a && source .env.local && set +a &&
  docker compose restart frame-mcp-blue frame-mcp-green
"
```

소요 ~5초.

## 3. 검증 (옵션)

직원에게 onboarding 안내 보내기 전, 본인이 그 직원 가짜로 시도:

```bash
# Microsoft id_token (테스트용) 발급은 어려우므로, frame integrity 만 확인
axe health frame   # positional target only; multi-customer 환경에선 ssh customer-macmini 측 health 확인
```

`customers.yaml` 의 user_entity_map 변경 → frame 재기동 → 즉시 적용. 별도 검증 불필요.

## 4. 직원 안내 메일

```
제목: [AXE Labs] {회사명} Frame access 설정 안내

안녕하세요 김민수님,

회사 계정으로 회계 시스템 (Frame) 접근 권한이 부여되었습니다.

설정 방법 (5분):
1. claude.ai 에 회사 이메일 (kim.minsoo@axellc.com) 로 로그인
2. https://docs.axelabs.ai/onboard/claude-frame-setup 따라 진행
3. Client ID + Secret 는 별도 안전 채널 (Bitwarden Send) 로 전송 예정

권한:
  - entity axec (에이엑스이 코퍼레이션)
  - 권한: 조회 + 분개 등록 (read + write)

문제 발생 시:
  - 1차: 회사 IT 담당자
  - 2차: ai@axellc.com (운영자)

감사합니다.
```

## 5. Client Secret 전달 — `axe secret send` + Teams DM 자동 발사

Client ID 는 평문으로 같이 보내도 무방 (GUID 일 뿐). Client Secret 은 **반드시 Bitwarden Send 1회용 링크** — `axe secret send` 가 매니페스트 lookup + 1회용 링크 생성을 한 번에. 옵션 의미는 [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send).

### 5.1 URL 발급 (3개 secret)

```bash
EMP=kim.minsoo   # local-part (라벨용)
EMAIL=kim.minsoo@axellc.com
> /tmp/onboard-$EMP.txt
for env in AZURE_BLUEPRINT_MCP_CLIENT_SECRET \
           AZURE_HIVE_MCP_CLIENT_SECRET \
           AZURE_FRAME_MCP_CLIENT_SECRET; do
  svc=$(echo $env | awk -F_ '{print tolower($2)}')
  url=$(axe secret send $env --service $svc --to $EMP 2>/dev/null)
  echo "$svc|$url" >> /tmp/onboard-$EMP.txt
done
```

### 5.2 Teams DM 자동 발사 ([broadcast-dm](/architecture/secrets#자동-발사--apiadminbroadcast-dm))

```bash
CRON=$(grep -E "^CRON_SECRET=" /Users/axe/blueprint/.env | cut -d= -f2-)
BP=$(grep "^blueprint|" /tmp/onboard-$EMP.txt | cut -d'|' -f2)
HV=$(grep "^hive|"      /tmp/onboard-$EMP.txt | cut -d'|' -f2)
FR=$(grep "^frame|"     /tmp/onboard-$EMP.txt | cut -d'|' -f2)

TEXT="$EMP 님, 회사 시스템 (Blueprint / Hive / Frame) Custom Connector 등록 부탁드립니다.
가이드: https://docs.axelabs.ai/onboard/claude-frame-setup

claude.ai → Settings → Connectors → + Add Custom Connector × 3

Blueprint
  URL: https://axe.axelabs.ai/blueprint/mcp
  Client ID: 482598f7-540c-462c-9dfd-b957651eb804
  Secret: $BP

Hive
  URL: https://axe.axelabs.ai/hive/mcp
  Client ID: b7ead15d-2fea-4864-a5a8-b4b07d1629d4
  Secret: $HV

Frame
  URL: https://axe.axelabs.ai/frame/mcp
  Client ID: 137fc0ef-eb9f-4903-acbc-1a748add349c
  Secret: $FR

Microsoft 회사 계정 ($EMAIL) 로그인 → Connected. 막히면 ai@axellc.com."

curl -s -X POST http://localhost:3100/api/admin/broadcast-dm \
  -H "Authorization: Bearer $CRON" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg e "$EMAIL" --arg t "$TEXT" \
        '{emails:[$e], text:$t, contentType:"text"}')"
# → {"summary":{"sent":1,...}}
```

신규 직원이 Teams 에서 ai@axellc.com 으로부터 1:1 DM 수신 → 3 Send URL 클릭 → claude.ai Custom Connector Secret 칸 paste → `-a 1` 자동 무효. 운영자 손 = unlock 1번 + 위 2-block 실행만.

## 6. Bitwarden Vault 멤버 추가 (선택)

향후 frame-JWT 직접 발급 경로로 회귀할 경우 대비:

1. Vaultwarden organization → frame-jwt-axec collection → 멤버 추가: `kim.minsoo@axellc.com`
2. 권한: read-only (item 조회만)

현재 직접-Microsoft OAuth 경로에선 불필요. 향후 변경 가능성 대비.

## 7. 직원이 첫 호출 후 검증

직원 등록 후 며칠 내 본인이 frame audit_log 확인:

```bash
ssh axe-macmini "docker exec frame-postgres psql -U frame -d frame -c \"
  SELECT actor, op, table_name, ts
  FROM axec.audit_log
  WHERE actor = 'kim.minsoo@axellc.com'
  ORDER BY ts DESC
  LIMIT 5;
\""
```

활동 1건 이상 = 정상 작동 확인.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `user_entity_map` 에 추가만 하고 컨테이너 재기동 X | 권한 적용 안 됨 | 항상 `docker compose restart` |
| email 대소문자 불일치 | lookup 실패 | customers.yaml 는 lower-case 통일 (frame 코드가 자동 normalize) |
| entity 이름 오타 (`axec` vs `axes`) | EntityNotAuthorizedError | YAML 저장 전 확인 |
| 권한 부여 후 직원에게 알림 안 함 | 직원이 onboarding 절차 모름 | 메일 발송 절차 자동화 검토 |

## 향후 개선

- [ ] `axe employee add --customer axe --email <...> --entity axec` CLI 명령 추가
- [ ] customer admin 이 self-service 로 직원 추가하는 Blueprint UI
- [ ] 권한 부여 audit (누가 누구에게 언제 부여)

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/macmini-loss -->

# macmini 손실

> customer macmini 도난/화재/완전 손실 시 1-day 복구.

URL: https://docs.axelabs.ai/ops/runbook/macmini-loss

# macmini 손실 (재해 복구)

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/macmini-loss 따라 customer macmini 손실 1-day 복구 진행해줘.

진행:
1. 사건 확인 — customer admin 통보 (도난/화재/disk 파손) + 손실 시점 파악
2. 즉시 access 차단 — customer IT 측 Microsoft Entra ID app 비활성 또는 secret 회전 (모든 직원 connector 401)
3. backup 상태 확인 (Ring peer / Cold SSD 가장 신선 snapshot) → 손실 시점 ~ 마지막 backup 간 데이터 손실 범위 추정 + 사용자 확인
4. 새 macmini 확보 + 단기 복구 (T+1h~1d) 페이지 절차, 매 step 결과 받고 다음. customer IT 와 양방향 통보 + 진행 상황 공유
5. 복구 완료 후 health 검증 + 정합성 검사 + customer 회신 + 사고 회고 /ops/known-gaps 기록 (재발 방지)
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

가장 심각한 시나리오. customer macmini 가 도난/화재/disk 완전 파손으로 사용 불가.

## 즉시 (T+0 ~ T+1h)

### 1. 사건 확인

customer admin 으로부터 통보:
- "사무실 화재로 macmini 손상"
- "이전 후 부팅 안 됨"
- "도난 신고"

### 2. 사용자 access 차단

악의적 사용 방지 — Microsoft Entra ID 측에서 app 비활성 (또는 secret 회전):

```bash
# customer IT 에게 즉시 요청:
"Azure portal → Microsoft Entra ID → App registrations → 'Frame MCP' → Authentication → 
 'Allow public client flows' 끄거나, Certificates & secrets 에서 secret 삭제"
```

→ 모든 직원의 connector 가 401 받기 시작.

### 3. 현재 backup 상태 확인

```bash
# Ring peer 측에서 가장 신선한 backup 확인
ssh realchoice-macmini "
  restic -r /Users/realchoice/peer-backups/axe/restic-repo snapshots \
    --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local)
"
# 가장 최근 snapshot 시점 확인 → 손실 시간 추정

# Cold SSD 도 확인
# (운영자가 SSD 꽂아서 확인)
```

손실 시점 = (사건 직전 시점) ~ (마지막 backup 시점) 사이.

## 단기 복구 (T+1h ~ T+1d)

### 4. 새 macmini 확보

- customer 가 새 macmini 구매 (M2/M3, 16GB+, 512GB+)
- 도착 즉시 운영자 측 배송 또는 customer IT 가 셋업

### 5. macOS 기본 셋업

customer IT 또는 운영자가 원격 지원:

```bash
# 1. macOS 사용자 생성 (예: axe)
# 2. Tailscale install + 운영자 key 등록
# 3. SSH 접속 검증

# 4. Docker Desktop install
# 5. axe CLI install
curl -sSL https://docs.axelabs.ai/install/axe-cli.sh | bash
```

### 6. backup 복원

```bash
# 운영자 머신에서
axe restore --customer &lt;customer&gt; --tier ring --from &lt;peer&gt; --as-of &lt;latest&gt;

# 또는 cold SSD
axe restore --customer &lt;customer&gt; --tier cold --as-of &lt;latest&gt;
```

복원 대상:
- `frame-postgres` 데이터 (Docker volume)
- `.local/files/` (platform data, source files)
- `~/.frame/` (PII salt)
- 컨테이너 image 들 (재 build)

### 7. customers.yaml + cloudflared 그대로

운영자 머신의 `customers.yaml` 변경 불필요 — customer 의 도메인 (`{customer}.axelabs.ai`) 그대로 사용.

cloudflared ingress 도 그대로 — origin 이 host.docker.internal:port 이고 customer macmini IP 변경 무관 (Tailscale FQDN 사용 안 함).

### 8. onboard 재실행

```bash
axe onboard &lt;customer&gt; --apply
# Azure 측 설정은 손대지 않음 (onboard 가 Azure CRUD 안 함, 그대로 재실행 idempotent).
# 부분 재실행 필요하면 `--skip-frame` (frame 만 건너뛰기) 사용 가능.
```

Azure Entra ID app 들은 그대로 (도메인 동일, redirect_uri 동일). frame / blueprint / vault 만 macmini 측 fresh setup.

### 9. 정합성 검사

```bash
ssh &lt;customer&gt;-macmini "docker exec frame-mcp-blue python -m frame.cli integrity-check --entity &lt;each_entity&gt;"
```

모두 통과 → 복구 완료.

### 10. customer IT 측 Microsoft Entra ID 재활성

`Allow public client flows` 다시 Yes 또는 새 secret 발급 (3 절에서 차단했던 것 되돌리기).

새 secret 발급 시:
1. customer IT → 새 secret VALUE
2. 운영자 → macmini Keychain 에 push
3. 컨테이너 재기동
4. 직원들에게 새 secret 안내 (claude.ai connector 측 swap 필요)

## 손실 분석

복원 후 손실 분석:

```bash
# 마지막 backup ~ 사건 사이의 audit_log
ssh &lt;customer&gt;-macmini "docker exec frame-postgres psql -U frame -d frame -c \"
  SELECT actor, op, table_name, ts
  FROM &lt;entity&gt;.audit_log
  WHERE ts > '&lt;last_backup_ts&gt;'
  ORDER BY ts;
\""
```

이 audit_log 자체도 backup 시점 이후 손실. 운영자가:

1. customer 에게 손실 시점 통지 + 그 사이 작업한 내역 재입력 요청
2. 매뉴얼 분개 재입력 (회계사가 자기 메모 보고)
3. 외부 증거 (은행 statement 등) 재수집

## 보안 검토 (사건 직후)

도난/화재가 아니라 침해 의심이면:
- Microsoft Entra ID audit log 검토 (의심 IP, 의심 시간대)
- frame audit_log 검토 (의심 actor)
- ring peer 의 backup 도 봐서 사건 직전 정상 활동 확인
- 의심 시 사건 정식 보고 + 외부 감사

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| backup 만 신뢰, Microsoft 측 access 안 차단 | 도난자가 계속 access | 즉시 customer IT 호출 |
| backup 신선도 명확 확인 안 함 | 손실 시간 misestimate | 매번 `restic snapshots` 의 `Time` 컬럼 명시 |
| 복원 후 정합성 검사 안 함 | 잠재 손상 미발견 | `integrity-check` 필수 |
| 자세한 손실 시점 추정 안 함 | customer 가 누락된 작업 모름 | 마지막 backup ts 명확히 통지 |

## 분기 Drill 의 의미

분기 자동 restore drill 은 정확히 이 시나리오 대비. drill 통과 = 복구 절차가 실제로 작동함을 검증.

drill 실패 = 즉시 backup 절차 점검. 실패 누적 = 인프라 전반 재검토.

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/operator-broadcast -->

# 운영자 broadcast — Teams DM 으로 임직원 1:N 공지

> Blueprint `/api/admin/broadcast-dm` REST 로 bot identity (ai@axellc.com) → AXE 임직원 1:N Teams DM. M365 Mail.Send 가 아닌 Teams 채널 — AXE 내부 broadcast 표준. vault 안내 / 운영 공지 / 시스템 변경 통보 등 use case.

URL: https://docs.axelabs.ai/ops/runbook/operator-broadcast

# 운영자 broadcast (Teams DM)

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/operator-broadcast 따라
임직원 [수신자 email list] 에게 다음 공지 broadcast 해줘:

[공지 본문 paste]

진행:
1. 본 페이지의 Prereq 확인 (Blueprint LIVE + CRON_SECRET 접근 가능)
2. Step 1..4 순서대로 — 매 step 결과 받고 다음
3. 함정 발생 시 페이지 "함정 정리" 표 따라 우회
4. Step 4 결과 (3 messageId) 받으면 종료 + Ship Log 한 줄 (선택)
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

## Prereq

- 운영자 자격 (AXE org Owner — 본 broadcast 가 정당 operational 공지인지 본인 판단)
- axe-macmini 에서 실행 (Blueprint LIVE 가 `http://blueprint.local:3100` 으로 접근 가능)
- `/Users/axe/blueprint/.env` 의 `CRON_SECRET` 환경변수 존재 (Blueprint deploy 시 자동 set)
- 수신자 email list (`@axellc.com` 도메인 — 운영자 자체 broadcast 가 cross-tenant 안 함)
- 본문 = plain text 또는 escaped html (default text — 권장)

## Step 1: 사전 확인 (Blueprint LIVE + CRON_SECRET + bot identity)

```bash
# (a) Blueprint health
curl -sf -o /dev/null -w 'blueprint http=%{http_code}\n' http://blueprint.local:3100/api/health

# (b) CRON_SECRET 길이 (값 출력 X)
SECRET=$(grep '^CRON_SECRET=' /Users/axe/blueprint/.env | cut -d= -f2- | tr -d '"' | tr -d "'")
echo "secret_len=${#SECRET}"

# (c) bot identity = ai@ 인지 self-DM 거부 응답으로 검증 (실제 메시지 발송 X)
curl -sf -X POST http://blueprint.local:3100/api/admin/broadcast-dm \
  -H "Authorization: Bearer $SECRET" \
  -H 'Content-Type: application/json' \
  -d '{"emails":["ai@axellc.com"],"text":"self-test","contentType":"text"}' \
  | jq '.results[0]'
# 기대: {email:"ai@axellc.com", status:"skipped", reason:"target AAD id matches bot — refusing self-DM"}
# → reason 안에 "matches bot" 보이면 bot = ai@ 정상
```

3개 다 통과해야 진행. 실패 시 함정 표 참조.

## Step 2: 본문 + payload JSON 작성

본문 = plain text (default contentType). 줄바꿈 `\n`, 특수문자 escape 불필요 (text mode 라 client 가 그대로 렌더). bullet 은 `-` 또는 `•` 등 plain.

```bash
# 본문을 한 변수에 — heredoc 이 가독성 ↑
BODY=$(cat <<'EOF'
[제목 1줄]

[본문 내용]
- bullet 1
- bullet 2

링크: https://...
EOF
)

# payload JSON 작성 (jq 가 \n + 특수문자 자동 escape)
EMAILS_JSON='["soohun.kang@axellc.com","taehun.kang@axellc.com","jinwoo.han@axellc.com"]'
jq -n --argjson emails "$EMAILS_JSON" --arg text "$BODY" \
  '{emails:$emails, contentType:"text", text:$text}' > /tmp/bcast.json

# 확인 (수신자 + 본문 길이만 — 본문 풀 출력 안 함)
jq '{emails, text_len: (.text | length)}' /tmp/bcast.json
```

## Step 3: POST 호출

```bash
SECRET=$(grep '^CRON_SECRET=' /Users/axe/blueprint/.env | cut -d= -f2- | tr -d '"' | tr -d "'")
curl -s -X POST http://blueprint.local:3100/api/admin/broadcast-dm \
  -H "Authorization: Bearer $SECRET" \
  -H 'Content-Type: application/json' \
  -d @/tmp/bcast.json \
  -w '\nHTTP_%{http_code}\n'
```

기대 응답:

```json
{
  "summary": {"total":3, "sent":3, "skipped":0, "error":0},
  "results": [
    {"email":"soohun.kang@axellc.com", "status":"sent", "chatId":"19:...@unq.gbl.spaces", "messageId":"1779..."},
    {"email":"taehun.kang@axellc.com", "status":"sent", "chatId":"19:...", "messageId":"1779..."},
    {"email":"jinwoo.han@axellc.com",  "status":"sent", "chatId":"19:...", "messageId":"1779..."}
  ]
}
```

`sent=3` + HTTP 200 = 정상. cleanup:

```bash
rm -f /tmp/bcast.json
```

## Step 4: 결과 검증 + Ship Log (선택)

각 수신자가 Teams 앱 (phone + desktop) 에서 ai@axellc.com 로부터 1:1 DM push 알림 받았는지 본인이 확인 (수신자 회신 또는 운영자 본인 Teams 의 sent items 확인).

운영 회고용 Ship Log 한 줄 (broadcast 가 의미 있는 일이면 — vault 공지 / 신규 customer launch 등):

```markdown
| YYYY-MM-DD HH:MM | broadcast (axe org) | (operator action) | **broadcast title** — 3 임직원 (soohun/taehun/jinwoo) Teams DM 발송. broadcast-dm REST + bot ai@. 본문 핵심: [한 줄 요약]. messageId: 1779..., 1779..., 1779... |
```

추가하면 `/Users/axe/axelabs-docs/content/ops/updates.mdx` Ship Log 표 최상단에 한 줄. `axe ship docs` 로 배포.

## 함정 정리

| # | 증상 | 원인 | 우회 |
|---|---|---|---|
| 1 | 외부 7cb41f76 MCP 의 노출 tool list 에 `send_mail` / `send_email` / `graph_send_email` 없음 | 의도된 분리 — Blueprint 의 32+ graph_* tool 중 send 계열은 `blueprint-graph` 내부 MCP 에만 등록, 외부 connector 는 read-only 격리 | 본 페이지의 broadcast-dm REST 사용 (admin 채널 별도) |
| 2 | `az rest --uri /me/sendMail` → `403 Forbidden ErrorAccessDenied` | az CLI 의 first-party app (04b07795) 이 Mail.Send scope 받을 권한 없음 (Microsoft 자사 앱 간 consent preauthorization 정책) | az CLI 경유 mail send 영구 불가 — broadcast-dm 또는 Outlook 수동 |
| 3 | `az account get-access-token --scope https://graph.microsoft.com/Mail.Send` → AADSTS65002 | (#2 와 동일 root cause) | (#2 와 동일) |
| 4 | `/api/admin/broadcast-dm` → `{status:"skipped", reason:"target AAD id matches bot — refusing self-DM"}` | bot identity = ai@axellc.com — 본인에게 DM 시도 거부 | 수신자 list 에서 ai@ 제거. 또는 self-test 용도 (Step 1 의 (c)) 일부러 의도적 |
| 5 | `{status:"skipped", reason:"no AAD object id for user"}` | 수신자가 Blueprint 에 한 번도 로그인한 적 없음 — NextAuth callback 의 `User.aadObjectId` populate 안 됨 | 수신자가 https://blueprint.axelabs.ai 1회 SSO 로그인 → 자동 fill → 재시도 |
| 6 | `401 Unauthorized` | `CRON_SECRET` 헤더 잘못 / .env 에 미설정 / Bearer prefix 빠짐 | `Authorization: Bearer $SECRET` 정확. .env 의 CRON_SECRET 값 직접 변수에 |
| 7 | `Connection refused http://blueprint.local:3100` | Blueprint 미실행 (PC 부팅 직후 / launchd 미가동) | `ps aux \| grep blueprint` 확인, 필요 시 `launchctl kickstart -k gui/$(id -u)/com.axe.blueprint` |
| 8 | 본문 줄바꿈 깨짐 (Teams 한 줄로 표시) | `contentType: "html"` 인데 plain text 넣음 — `<br>` 없으니 collapse | `contentType: "text"` 명시 (default 권장) |
| 9 | 본문 안 `*` 강조 등이 안 보임 | Teams 는 markdown 미해석 (text contentType) | bullet 은 `-` plain, 강조는 대문자 or `===` 줄 구분 |
| 10 | customer 직원 (`@truvia.co.kr` 등) 에게 보내려고 시도 → skip | broadcast-dm 의 bot = AXE tenant 의 ai@, cross-tenant chat 생성 불가 | customer 측은 본인 운영자 (Truvia 의 broadcast 채널) 자체 보냄 — sovereignty 원칙 |

## 관련 use case (참고)

- **vault 운영 공지** — KDF rotation / setup 안내 (D-ops-40, 2026-05-26 첫 실 사용)
- **신규 customer launch 안내** — 새 service 가 LIVE 됐을 때
- **시스템 변경 통보** — Blueprint major upgrade, frame schema migration 등
- **D-day 직전 사전 안내** — onboard step 차단 가능성 등 사전 경고

NOT for: 일반 잡담 (channel 사용), 1:1 코칭 (Teams 직접 chat), customer 측 공지 (customer 자체 채널).

## 매 작업 시 사전 작업

| 빈도 | 작업 | 자동화 |
|---|---|---|
| 매 broadcast | Step 1 사전 확인 (Blueprint LIVE + bot identity 검증) | ❌ (사람 판단) |
| `CRON_SECRET` 회전 시 | Blueprint .env + axe-macmini launchd 재시작 | [B-blueprint-secret-rotation](/ops/backlog) 참조 |

## 참조

- [D-ops-40](/ops/decisions) — vault axe.3 release (본 broadcast 의 첫 use case, 2026-05-26)
- [/architecture/vault-policies](/architecture/vault-policies) — vault 3 layer 정책 모델 (broadcast 본문 안 참조 patterns)
- [/services/blueprint](/services/blueprint) — Blueprint 서비스 개요
- `src/app/api/admin/broadcast-dm/route.ts` — REST 구현
- `src/lib/teams/graph-client.ts` — bot Graph client (`getSharedClient()` 가 ai@ 정합)
- [B-blueprint-broadcast-mail](/ops/backlog) — 실 SMTP email 발송 route 추가 (M5, 사용 빈도 보고 진행)
- [/ops/known-gaps](/ops/known-gaps) — Microsoft 첫 당사자 app consent policy (az CLI Mail.Send 영구 차단)

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/release-flow -->

# Release flow (axe ship)

> 코드 변경 → 운영 반영까지의 release-gate. `git push origin main` 대신 `axe ship` 한 명령으로 docs-check + push + deploy 를 묶음.

URL: https://docs.axelabs.ai/ops/runbook/release-flow

# Release flow — `axe ship`

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/release-flow 따라 본 repo 변경 release 해줘.

진행:
1. 현재 repo + branch + 변경 상태 진단 (git status + git log origin/main..HEAD + 동반 docs 갱신 commit 존재 여부)
2. 페이지 "Service 매핑" 표 확인 — 본 repo 의 deploy hook 자동/수동 분기
3. 페이지의 각 Step (docs-check → branch clean → push preview → confirm → push → deploy hook) 매 step 결과 받고 다음. 특히 Step 4 confirm 직전 사용자 확인
4. 함정 발생 시 페이지 "함정" 표 따라 우회 (docs commit 누락 / cross-repo drift / feature branch)
5. 배포 완료 후 production 검증 + (선택) updates.mdx Ship Log 한 줄 추가
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

> **Problem**: 코드 변경 후 docs (`axelabs-docs/content/*.mdx`) 갱신을 깜빡하면 production 사이트가 거짓말을 함. 매 commit 마다 hook 으로 강제하면 WIP commit 이 막혀서 `--no-verify` 우회 습관이 생김 → hook 사실상 무력화.
>
> **Solution**: release 시점에만 강제. `git push origin main` 의 자리에 `axe ship` 를 둬서, **production 으로 나가는 모든 push 가 docs-drift 검증을 통과해야** 함. WIP / feature branch push 는 raw git 으로 그대로 사용.

## 한 줄 요약

```bash
# 이전 습관
git push origin main && ssh axe-macmini "cd /Users/axe/<service> && docker compose ..."

# 새 습관
axe ship          # 현재 repo 자동 감지 → docs-check → push → deploy
axe ship frame    # 명시
axe ship docs     # docs SSOT 자체 배포
```

## 무엇을 하는가

| Step | 동작 | 실패 시 |
|---|---|---|
| 1 | `axe docs-check --since origin/main` (현재 repo) | abort — 누락 mdx 페이지 출력 후 종료 |
| 2 | branch == `main` && working tree clean | abort |
| 3 | `git log origin/main..HEAD` 출력 (push 될 commit 미리보기) | nothing-to-push → abort |
| 3b | `axelabs-docs` 에 unpushed commit 있나? 있으면 경고 | (계속 진행, 단순 hint) |
| 4 | `yes/no` confirm 프롬프트 | abort |
| 5 | `git push origin main` | git push 자체 실패면 abort |
| 6 | service 별 deploy hook (아래 표) | (배포 실패는 알림, push 는 이미 완료) |

## Service 매핑

| `axe ship SERVICE` | repo | deploy hook |
|---|---|---|
| `frame` | `/Users/axe/frame` | `cmd_deploy` (blue/green swap, plan §3 D-config-13) |
| `blueprint` | `/Users/axe/blueprint` | `cmd_blueprint_upgrade` (sequential blue/green) |
| `docs` | `/Users/axe/axelabs-docs` | `docker compose up -d --build` (단일 컨테이너, ~30-60s 다운) |
| `hive` | `/Users/axe/hive` | (자동화 X) manual hint 출력 |
| `stream` | `/Users/axe/stream` | (자동화 X) manual hint 출력 |
| `magnet` | `/Users/axe/magnet` | (자동화 X) manual hint 출력 |

`hive/stream/magnet` 의 blue/green CLI 가 `axe deploy` 에 들어오면 매핑 갱신.

## 옵션

```
axe ship [service]
  --dry-run     # 실행 안 함, 어떤 step 이 무엇을 할지만 출력
  --no-deploy   # docs-check + push 까지만, 배포 hook skip (배포는 나중에 수동)
```

**escape hatch 없음**. `--skip-docs-check` 같은 플래그는 의도적으로 만들지 않음. drift 가 있다면:

1. `axelabs-docs/content/PAGE.mdx` 수정
2. `cd /Users/axe/axelabs-docs && git add -A && git commit -m 'docs: ...'`
3. `axe ship docs` (production 반영)
4. 원 repo 로 돌아와 `axe ship SERVICE` 재실행

## docs SSOT 의 특수성

`axe ship docs` 는 docs-check 를 **skip** 함 (자기가 SSOT 인데 자기 자신과 drift 비교는 무의미). 대신:

- branch + working tree clean 검사는 동일
- push 후 `docker compose up -d --build` 로 즉시 production 반영
- 배포 시간 ~30-60s, 단일 컨테이너 (blue/green X)

## 운영 순서

코드 변경이 docs 영향이 있는 경우 (대부분):

```bash
# 1. 코드 작업 (frame 예시)
cd /Users/axe/frame
# ... 작업 ...
git add -A && git commit -m "feat(frame): add foo MCP tool"

# 2. docs 갱신
cd /Users/axe/axelabs-docs
vim content/services/frame.mdx   # MCP Tools 표에 foo 추가
git add -A && git commit -m "docs(frame): document foo MCP tool"

# 3. docs 먼저 배포 (frame ship 의 docs-check 가 통과되도록 origin/main 에 docs commit 도달)
cd /Users/axe/axelabs-docs
axe ship                          # docs 자동 감지, push + rebuild

# 4. frame 배포
cd /Users/axe/frame
axe ship                          # frame 자동 감지, docs-check 통과, push + blue/green swap
```

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `axe ship` 대신 `git push origin main` 직접 | docs-check 미실행 → drift 누적 | release-worthy push 는 반드시 `axe ship` |
| feature branch 에서 `axe ship` | "current branch is X, expected main" abort | merge to main 먼저 |
| docs commit 안 한 채 `axe ship frame` | docs-check fail, push 거부 | docs 먼저 commit + ship |
| `axe ship docs` 전에 `axe ship frame` | docs commit 은 frame repo origin/main 에서 보임 → check 통과, but production 사이트는 옛 mdx | docs 먼저 ship (cross-repo 경고가 출력됨) |
| 다른 사람의 mdx 변경이 origin/main 에 있음 | docs-check 통과 (이미 mdx 있음) | 정상 — 다른 push 가 이미 docs 채움 |

## 왜 pre-commit hook 이 아닌가

자세한 의사결정 근거: [`D-ops-N` (release-gate-not-precommit)](/ops/decisions). 요약:

- pre-commit hook 은 WIP commit 마다 발화 → 노이즈 → `--no-verify` 습관화 → hook 사실상 죽음
- release-gate (`axe ship`) 는 운영자가 의도해서 호출하는 단 한 곳에 검증을 집중 → 우회 유혹 적음
- 솔로 운영자 + Claude Code 주 개발자 환경에서 ROI 가 가장 높은 지점

## 관련

- [`axe docs-check`](/ops) — drift 감지기 (ship 의 step 1 내부에서 호출)
- [DECISIONS](/ops/decisions) — release-gate 결정 근거
- [Blue/green deploy](/ops/runbook/deploy) — frame/blueprint 배포의 내부 동작

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/secret-rotation -->

# Secret Rotation

> 모든 비밀 회전의 단일 명령 — axe secret rotate. Vault SoT + external provider (Azure/Meta/Naver/...) 동기화 + 무중단 재배포 자동화.

URL: https://docs.axelabs.ai/ops/runbook/secret-rotation

# Secret Rotation

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/secret-rotation 따라 [secret name] 회전 진행해줘.

진행:
1. 회전 대상 secret + provider 식별 (Azure / Meta / Naver / GitHub / Anthropic / 기타)
2. Azure 면 az cli 6 단계 분기, 그 외면 `axe secret rotate <ENV_NAME>` interactive 분기
3. 페이지의 각 step 명령 실행 + 검증, 매 step 결과 받고 다음. 특히 OLD secret revoke 직전 사용자 확인 (NEW secret 무중단 swap + production 검증 통과 후)
4. 함정 발생 시 페이지 본문 따라 우회 (App Owner 부재 / external portal 수동 / `unset NEW` shell history 정리 / merge-mode pull 누락)
5. 회전 완료 + production health 검증 + (선택) /ops/updates Ship Log 한 줄
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

> **D-ops-17 + D-ops-19 (2026-05-21)** 이후 표준: Azure 의 client_secret 은 **az cli 6 단계** 로 portal UI 0회. 다른 provider (Meta/Naver/GitHub/Anthropic) 는 `axe secret rotate` 의 interactive 경로 + 외부 portal 수동.

## Azure 회전 — az cli 6 단계 (권장)

```bash
APP_ID=137fc0ef-eb9f-4903-acbc-1a748add349c   # frame_mcp (예시)
OLD_KEY_ID=$(az ad app credential list --id $APP_ID \
  --query "[?starts_with(hint,'<old prefix>')].keyId | [0]" -o tsv)

# 1. Azure 새 secret 추가 — --append 가 OLD 유지 = overlap window
NEW=$(az ad app credential reset --id $APP_ID \
  --display-name "auto-rotated 2026-MM-DD" --years 2 --append \
  --query password -o tsv)

# 2. vault PUT
axe secret push AZURE_FRAME_MCP_CLIENT_SECRET --service frame --value "$NEW"

# 3. pull (merge-mode — config 보존)
axe secret pull frame

# 4. 무중단 swap
axe deploy frame axe --apply          # frame / hive
axe blueprint upgrade axe --apply     # blueprint

# 5. 검증
docker exec $(active container) env | grep AZURE_FRAME_MCP_CLIENT_SECRET
/usr/bin/curl -sI https://axe.axelabs.ai/frame/health   # 200

# 6. OLD revoke (검증 후)
az ad app credential delete --id $APP_ID --key-id $OLD_KEY_ID

unset NEW                              # shell history 에서 제거
```

### 전제조건 — App Owner 확인

`az ad app credential reset` 은 app 의 owner 만 가능. portal-등록 app 은 default 로 owner 없음:

```bash
az ad app owner list --id $APP_ID --query "[].userPrincipalName" -o tsv
# 비어 있으면 → portal 에서 owner 추가 후 재시도:
#   open "https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/ApplicationMenuBlade/~/Owners/appId/$APP_ID"
```

본 플랫폼의 모든 AXE app 은 `ai@axellc.com` owner 박혀 있음 (2026-05-21 audit). 신규 az cli 등록 app 은 호출자가 owner 자동 박힘.

## 다른 provider 회전 — `axe secret rotate` interactive

Anthropic / GitHub / Meta / Naver / Slack 등 az 안 통하는 provider:

```bash
axe secret rotate <ENV_NAME> --service <svc>
```

진행:
1. 매니페스트의 `rotation_external` 확인 → provider portal URL 출력
2. 운영자가 portal 에서 새 값 발급 → 복사 → 프롬프트에 붙여넣기 (`getpass`, 화면 안 보임)
3. vault PUT
4. `axe secret pull SVC` (merge-mode)
5. `axe ship SVC` 트리거 (working tree dirty 면 abort — `axe deploy ... --apply` 로 수동 보완)
6. 운영자가 provider 에서 OLD 수동 revoke

상세 데이터 흐름: [/architecture/secrets](/architecture/secrets).

## 회전 주기 — 정기 점검

Microsoft Entra ID app 의 client_secret 회전 주기 = 24개월 (Frame MCP), 180일 (Blueprint, Vaultwarden).

만료 30일 전 자동 알림. 미루지 말 것 — 만료 = OAuth 전체 마비.

## 사전 알림

**현재 상태**: `com.axe.secret-check` launchd 자동 알림 + `axe secret status --customer X` CLI 는 **향후 추가 예정** (TODO). 현재는 수동 확인:

```bash
# 운영자 콘솔 (admin.axelabs.ai) 에 secret 만료일 표시 — `axe console rebuild` 가 매시 갱신
# 또는 Vault 에 보관된 메타에서 직접 확인:
bw get item "Frame MCP — claude.ai connector secret"  # 만료일 필드 확인
```

출력 예:
```
axe customer:
  blueprint:    expires 2026-08-15 (89 days)
  vaultwarden:  expires 2026-09-01 (106 days)
  frame_mcp:    expires 2028-05-19 (730 days)
```

90일 이내면 운영자 콘솔 dashboard 에 빨간 배너.

## 회전 절차 (180일 secret, ~30분)

예: customer `axe` 의 `frame_mcp` secret 회전 (24개월 만료).

### 1. 새 secret 발급 (customer IT 측)

customer IT 에게 메일:

```
제목: [AXE Labs] Frame MCP client_secret 갱신 요청 (만료 30일 전)

안녕하세요,

귀사 Microsoft Entra ID 의 'Frame MCP' app 의 client_secret 이 
30일 후 만료됩니다 (2028-05-19).

다음 절차로 새 secret 발급 + 안전 채널로 전달 부탁드립니다:

1. Azure portal → Microsoft Entra ID → App registrations → 'Frame MCP'
2. Certificates & secrets → + New client secret
3. Description: frame-mcp-axe-2028-05
4. Expires: 24 months
5. Add → VALUE 즉시 복사
6. Bitwarden Send (view-once, `-a 1 -d 1`) 또는 안전 채널로 운영자에게 전달 — 절차: [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send)

운영자 측 swap 완료 후 기존 secret 은 안전하게 폐기됩니다.

감사합니다.
액스코퍼레이션 주식회사 (운영 주체, ai@axellc.com)
```

### 2. 새 secret 받으면

```bash
# Keychain push (replace 기존)
security add-generic-password -a axe -s "axe.axe.frame.client_secret" -w '&lt;new_value&gt;' -U

# Verify
security find-generic-password -s "axe.axe.frame.client_secret" -w
# → &lt;new_value&gt; 출력되면 OK
```

### 3. 컨테이너 재기동 (env reload)

```bash
cd /Users/axe/frame
set -a && source .env.local && set +a
docker compose up -d --force-recreate frame-mcp-blue frame-mcp-green
sleep 5

# Verify env 적용
docker exec frame-mcp-blue env | grep AZURE_FRAME_MCP_CLIENT_SECRET | head -c 30
# → 새 값의 prefix 보이면 OK
```

> ⚠️ **다운타임 ~3초** — `--force-recreate` 가 blue+green 동시 재기동. 향후 blue→green→blue 순차 재기동으로 0초 만들 예정 (D-ops-16 후보).

### 4. claude.ai connector 측 영향

`frame_mcp` secret 의 경우 **직원 측 영향 있음**:
- claude.ai 의 Custom Connector 에 입력한 secret 도 갱신 필요
- 운영자 → 직원들에게 새 secret 전달 (안전 채널)
- 직원 각자 claude.ai 의 connector 편집 → Advanced 의 OAuth Client Secret 교체 → Save

> ⚠️ 이게 secret 회전의 가장 큰 운영 부담. 직원이 많을수록 painful. 향후 OAuth proxy 패턴 (D-ops-15) 으로 secret 분배 제거 검토.

### 5. 기존 secret 폐기 (24시간 후)

새 secret 활성 확인 + 직원 전원 swap 완료 후:

```
# customer IT 에게:
"기존 client_secret (<처음 4글자만 hint, 예: XX.X~ 처럼 식별 가능한 prefix>)
 Azure portal 에서 삭제 부탁드립니다.
 새 secret 으로 swap 완료 + 24시간 검증 완료했습니다."
```

> ⚠️ **secret VALUE 평문을 docs/메일/채팅 어디에도 적지 마세요**. 식별 hint 는 Azure portal 의 secret 표에서 보이는 hint prefix (보통 처음 3-4자 + "...") 만 사용. 운영자 본인이 회전 시점에는 Keychain `find-generic-password` 로 prefix 확인.

customer IT 측에서 Azure portal → Certificates & secrets → 기존 secret 옆 휴지통 클릭.

### 6. 검증

```bash
# customers.yaml 메타 업데이트 (선택)
# sso.apps.frame_mcp.client_secret_env 의 만료일 주석 갱신

# Audit (TODO: `axe secret status` 추가 후)
# 현재는 Vault item 의 만료 메타 갱신 + 운영자 콘솔 dashboard 확인
```

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 만료일 잊고 24시간 후 마비 | OAuth 전체 다운 | 매일 자동 알림 + 30일 전 작업 |
| 새 secret swap 전 기존 삭제 | OAuth 즉시 다운 | 24시간 grace period |
| Keychain replace 안 하고 새로 add | duplicate, 어떤 게 active 인지 모름 | `-U` 플래그로 update |
| 컨테이너 restart 만 (--force-recreate X) | env file 재로드 안 됨 | `up -d --force-recreate` |
| 직원에게 secret 일괄 push 잊음 | 직원들 connector 실패 | swap 전에 communication |

## 응급: secret 노출 의심

평문이 어딘가 노출된 의심이 있을 경우 (메일 전송 사고, 노트북 분실 등):

1. customer IT 에게 즉시 새 secret 발급 요청 (정상 절차 X, 비상)
2. 받자마자 Keychain push + 컨테이너 재기동
3. 기존 secret 즉시 삭제 (24시간 grace X)
4. audit_log 검사 — 의심 시간대에 비정상 access 있는지
5. 직원 전원에게 알림 + claude.ai connector 즉시 update 요청

상세: [Runbook · Secret 노출 대응](/ops/runbook/secret-incident) (예정).

---

<!-- PAGE https://docs.axelabs.ai/ops/runbook/vault-recovery -->

# Vaultwarden 복구

> self-host vault 복구, OIDC 깨짐 대응, sso_nonce 수동 패치.

URL: https://docs.axelabs.ai/ops/runbook/vault-recovery

# Vaultwarden 복구

## AI 요청 프롬프트

```
https://docs.axelabs.ai/ops/runbook/vault-recovery 따라 axe-vaultwarden 복구 진행해줘.

진행:
1. 현재 증상 진단 — docker ps + curl /identity/.well-known/openid-configuration + 사용자 보고로 시나리오 1~6 중 어느 분기인지 식별
2. 시나리오 식별 후 추가 분기 확인 (PostgreSQL vs SQLite backend / Timshel fork vs mainline / customer 측 axe.axelabs.ai vs realchoice 측)
3. 페이지의 각 명령 실행 + 검증, 매 step 결과 받고 다음. backup 또는 force-recreate 등 destructive 명령 직전 사용자 확인
4. 함정 발생 시 페이지 "함정" 표 따라 우회 (column 명 verifier vs code_verifier / digest pin / 시나리오 6 = 영구 손실 — 복구 불가)
5. 복구 완료 검증 (SSO 로그인 + vault item 조회 + admin endpoint) + 사고 원인 /ops/known-gaps 한 줄 (재발 방지)
```

본인 AI session = Claude Code / Cursor / ChatGPT 데스크탑 / Claude.app / 기타.

페이지 본문 = 사람이 직접 read 도 가능, AI 도 참고. AI 가 본 페이지 fetch 후 위 진행 순서대로 사용자와 step-by-step interactive 풀어나감.

`axe-vaultwarden` 서비스가 죽거나 OIDC 가 깨졌을 때.

## 시나리오 1 — 컨테이너 죽음

```bash
docker ps -a | grep vault
# axe-vaultwarden Exited (1)

# 단순 재시작
cd /Users/axe/.axe/vault
docker compose up -d --force-recreate
sleep 5
curl -sk https://localhost:8222/identity/.well-known/openid-configuration | head -5
```

설정 정상이면 정상 가동.

## 시나리오 2 — OIDC 깨짐 (sso_nonce 누락)

D-ops-12 에서 다룬 알려진 이슈. Timshel fork 가 sso_nonce 테이블을 알아서 생성 안 함. **2026-05-25 정정** (Truvia realchoice 검증) — Timshel fork 의 실제 column 명 = `verifier` (NOT `code_verifier`). PostgreSQL / SQLite backend 분기 명령 별도.

증상:
```
ERROR: relation "sso_nonce" does not exist   (PostgreSQL)
또는
sqlite> .schema sso_nonce → empty                (SQLite)
```

### PostgreSQL backend (axec axe-vaultwarden 패턴)

```bash
docker exec axe-vaultwarden-postgres psql -U vaultwarden -d vaultwarden -c "
CREATE TABLE IF NOT EXISTS sso_nonce (
    state TEXT PRIMARY KEY,
    nonce TEXT NOT NULL,
    verifier TEXT NOT NULL,
    redirect_uri TEXT NOT NULL,
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
"

docker compose restart axe-vaultwarden
```

### SQLite backend (`soohunkang/vault` repo + Vaultwarden 공식 image, 예: realchoice 의 ~/vault)

```bash
# vault-app 컨테이너 안의 sqlite3 (또는 host 측에서 docker exec)
docker exec vault-app sqlite3 /data/db.sqlite3 <<'EOF'
CREATE TABLE IF NOT EXISTS sso_nonce (
    state TEXT PRIMARY KEY,
    nonce TEXT NOT NULL,
    verifier TEXT NOT NULL,
    redirect_uri TEXT NOT NULL,
    created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
);
EOF

# 만약 위 schema 작성 후 column 명 mismatch 로 fail 보이면 (이전에 잘못된 column 이름으로 만든 경우):
docker exec vault-app sqlite3 /data/db.sqlite3 "ALTER TABLE sso_nonce RENAME COLUMN code_verifier TO verifier;"

docker compose restart vault-app
```

(db.sqlite3 경로는 `DATA_FOLDER` env 또는 `/data` volume mount 기준. compose.yaml 확인 후 적용.)

## 시나리오 3 — Microsoft SSO 갑자기 안 됨

원인 후보:
- Vaultwarden app 의 client_secret 만료
- redirect_uri 등록 잘못됨
- AZURE_TENANT_ID 또는 AZURE_VAULTWARDEN_APP_ID 잘못 설정

확인:
```bash
# .env 검증
cat /Users/axe/.axe/vault/.env | grep -E 'AZURE_(TENANT_ID|VAULTWARDEN)'

# 컨테이너 env 검증
docker exec axe-vaultwarden env | grep -E 'SSO_(AUTHORITY|CLIENT)'
```

해결:
1. customer IT 측 Azure 에서 새 client_secret 발급
2. `.env` 의 `AZURE_VAULTWARDEN_CLIENT_SECRET=` 새 값으로
3. `docker compose up -d --force-recreate`

## 시나리오 4 — 컨테이너 손상 / 데이터 손실

```bash
# 1. backup 확인
restic -r /Users/axe/.axe/backups/local snapshots \
    --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local -a axe-cli) \
    --tag vault

# 2. 가장 신선한 vault snapshot 복원
# `axe restore` 는 Phase 5 stub — 현재는 restic 직접 + docker volume restore:
restic -r /Users/axe/.axe/backups/local \
  --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local -a axe-cli) \
  restore &lt;snapshot_id&gt; --target /tmp/vault-restore --include '/Users/axe/.axe/vault/*'
# 그 후 docker volume 또는 .yml volume mount 위치에 복사

# 3. 컨테이너 재시작
cd /Users/axe/.axe/vault
docker compose up -d --force-recreate

# 4. Microsoft SSO 시도
open https://axe.axelabs.ai/vault
```

## 시나리오 5 — Timshel fork 업데이트

Timshel fork 의 새 release 가 나왔을 때.

⚠️ **신중하게**. Timshel 은 mainline Vaultwarden 보다 작은 PR queue → 가끔 breaking change.

```bash
# 1. 현재 digest pin 확인
grep ghcr.io /Users/axe/.axe/vault/docker-compose.yml

# 2. 새 digest 확인 (Timshel 의 GitHub Releases)
# https://github.com/Timshel/vaultwarden/releases

# 3. 비프로덕션 환경에서 테스트 (있다면)

# 4. backup 전체 (vault + DB)
# 수동 backup (현재 `axe backup` subcommand 없음 → restic 직접):
restic -r /Users/axe/.axe/backups/local \
  --password-file &lt;(security find-generic-password -w -s axe.backup.restic.local -a axe-cli) \
  backup /Users/axe/.axe/vault --tag vault-pre-upgrade

# 5. .yml 의 image: line 갱신
vim /Users/axe/.axe/vault/docker-compose.yml
# image: ghcr.io/timshel/vaultwarden@sha256:&lt;new&gt;

# 6. 재시작
docker compose up -d --force-recreate

# 7. 검증
# - admin 로그인
# - Microsoft SSO 로그인
# - 기존 collection 의 item 조회
# - 새 item 생성/조회

# 8. 실패 시 rollback
docker compose down
# .yml 의 image: 옛 digest 로 되돌림
docker compose up -d
```

## bw CLI data.json cache stale recovery (운영자 측)

서버 측 복구가 아닌 **운영자 본인 머신의 bw CLI** 회복 절차. server-side vault patch deploy 후 local `data.json` cache 가 stale 상태로 잔존하면서 발생.

**증상**:
```
[Encrypt service] MAC comparison failed
```
`bw unlock` 또는 `bw get <name>` 시 위 에러 → bw 명령 전체 실패.

**언제 발생**: server-side vault patch deploy 후 (axe.2 → axe.3 등). bw CLI 의 local `data.json` 에 `cryptoSymmetricKey` cache 가 옛 schema 의 wrapped key 보유 → 새 server 가 내려준 패치 후 shape 와 mismatch → decrypt 시 MAC mismatch. `bw unlock` 자체는 cache 무효화 안 함.

**빈도**: server patch 마다 1회 — 2026-05-22, 2026-05-26 두 차례 재발 확정. patch shape 변경 시 매번.

**표준 회복 절차** (운영자 본인 머신, 약 30초):

```bash
bw logout
bw config server https://axe.axelabs.ai/vault
bw login   # email + MP + Entra MFA (interactive)
bw unlock  # MP — session token stdout
export BW_SESSION="...token..."
bw get password <known-secret>  # 검증
```

이후 Keychain 의 `axe.vault.session` entry 갱신:

```bash
bw unlock --raw | security add-generic-password -s 'axe.vault.session' -a "$(whoami)" -w "$(cat)" -U
```

**자동화 후보** (영구 fix, [B-bw-cache-stale-autoheal](/ops/backlog)):

- `axe vault reset` 신설 — 위 4단계를 한 명령으로
- `_bw_get_password` 헬퍼가 `MAC comparison failed` 패턴 감지 시 자동 reset + retry
- `axe ship vault` post-deploy hook 이 patch shape 변경 시 osascript 알림 — 운영자 본인에게 "logout/login 필요" pre-warn

**함정**:

| 함정 | 결과 | 회피 |
|---|---|---|
| ai@ personal vault 가 약 37 items → fresh login 시 sync 약 30초 대기 | `bw login` 직후 `bw get` 호출 시 일부 item 미반영 | login 직후 `bw sync` 명시 + 약 30초 대기 |
| `bw login` 시 `BW_CLIENTID` / `BW_CLIENTSECRET` env 잔존 시 API key 모드로 진입 | SSO 흐름과 다른 인증 경로 — 일반 사용 OK 단 본 회복 절차는 interactive 가 가장 안전 | 회복 시 `unset BW_CLIENTID BW_CLIENTSECRET` 후 `bw login` |
| `~/.config/Bitwarden CLI/` (또는 `$BITWARDENCLI_APPDATA_DIR`) 의 `data.json` 직접 삭제 시도 | clean state 안 됨 + session token 잔존 | `bw logout` 권장 (data.json + session 모두 정리) |
| Keychain 의 `axe.vault.session` 옛 token 잔존 | `axe secret *` 호출이 옛 invalid session 으로 NO_SESSION_IN_KEYCHAIN | login 후 위 `security add-generic-password ... -U` 로 갱신 필수 |

## 시나리오 6 — 운영자 master password 분실

⚠️ **이건 영구 손실**. Vaultwarden 의 master password 는 vault 의 encryption key. 모르면 모든 item 복호화 불가.

회피:
1. master password 는 종이 메모 + 신뢰할 수 있는 가족 (또는 다른 안전한 곳)
2. 매월 1회 master password 로 로그인 시도 (잊지 않게)
3. Bitwarden export 정기 + 그 export 파일 자체도 vault 의 master password 로 암호화

분실 시 — vault 폐기, 모든 item 재발급. 회사 운영 1주일 이상 마비 가능. 그래서 종이 백업 필수.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| Timshel digest pin 안 함 (`:latest`) | 무작위 업데이트 | 항상 `@sha256:&lt;digest&gt;` |
| backup 안 함 | sso_nonce 깨졌을 때 복구 불가 | 매일 자동 backup |
| .env 평문 commit | secret 노출 | .gitignore + Keychain |
| master password 단일 보관 | 분실 시 영구 손실 | 종이 + 가족 이중화 |
| 분기 drill 안 함 | restore 절차 실제 검증 안 됨 | `com.axe.restore-drill` 자동화 |

---

<!-- PAGE https://docs.axelabs.ai/ops/troubleshooting -->

# 운영자 문제 해결

> 직원이 보고하는 문제 분류 + 운영자 측 진단 단계.

URL: https://docs.axelabs.ai/ops/troubleshooting

# 운영자 문제 해결

직원이 "frame 안 됩니다" 라고 호출 왔을 때 진단 순서.

## Step 1 — 외부 health

```bash
curl -sI https://axe.axelabs.ai/frame/health
# 200 OK 인지 확인
```

200 OK 안 나오면:
- → cloudflared 죽음? `docker ps | grep axelabs-tunnel`
- → frame 자체 죽음? `docker ps | grep frame-mcp`
- → Cloudflare 측 장애? Cloudflare status page 확인

## Step 2 — protected-resource 메타데이터

```bash
curl -sS https://axe.axelabs.ai/frame/.well-known/oauth-protected-resource | python3 -m json.tool
```

기대 응답:
```json
{
  "resource": "https://axe.axelabs.ai/frame/mcp",
  "authorization_servers": [
    "https://login.microsoftonline.com/122fb574-7efa-476a-95b6-bee81bce2cce/v2.0"
  ],
  "scopes_supported": [...],
  "bearer_methods_supported": ["header"]
}
```

`resource` 가 다르면 → customers.yaml 의 public_domain 확인.
`authorization_servers` 의 tenant_id 가 customers.yaml 와 다르면 → 환경변수 갱신.

## Step 3 — frame 로그

```bash
docker logs --since 10m frame-mcp-blue 2>&1 | grep -v 'health\|/ready' | tail -30
```

패턴:
- `POST /frame/mcp 401 Unauthorized` 만 보임 → Bearer 안 들어옴, claude.ai 측 또는 Microsoft 측 문제
- `POST /frame/mcp 200 OK` + tool 호출 → 정상
- `INVALID_TOKEN` / `OIDC_UNAVAILABLE` / `EntityNotAuthorizedError` → 각각 다른 진단

## Step 4 — 직원 측 정보 수집

직원에게 요청:

1. claude.ai/customize/connectors 페이지의 Frame connector 상태 (Connected / Disconnected / Authorization failed)
2. 오류 메시지 전문 (스크린샷)
3. 브라우저 주소창의 전체 URL (특히 `error_code=`, `entra_aadsts_code=`, `entra_trace_id=`)
4. 본인 회사 이메일

## Step 5 — Microsoft sign-in log

Azure portal → Microsoft Entra ID → Monitoring → Sign-in logs:
- 직원의 trace_id 또는 시간 + 이메일로 필터
- Sign-in error code (AADSTS XXX) 확인
- Failure reason

## Step 6 — 분류

| 증상 | 원인 후보 | 해결 |
|---|---|---|
| AADSTS700016 | client_id 오타 또는 misconfig | customers.yaml 확인 |
| AADSTS9010010 | resource ≠ scope prefix | Application ID URI ↔ scope 일치 확인 |
| AADSTS7000218 | secret 없음 + public client flow off | secret 발급 + claude.ai 입력 |
| AADSTS65001 | consent 안 함 | 직원이 consent 화면에서 Accept |
| mcp_client_invalid | aud 검증 실패 (v2 토큰) | manifest accessTokenAcceptedVersion = null |
| Couldn't reach MCP server | URL 오타 또는 frame 죽음 | Step 1 |
| EntityNotAuthorizedError | customers.yaml 매핑 누락 | user_entity_map 에 추가 + frame 재기동 |
| 권한 부족 | 직원의 scope 부족 | 권한 상승 결정 + customers.yaml |

## 자주 발생하는 운영자 측 실수

| 실수 | 증상 | 대응 |
|---|---|---|
| customers.yaml 수정 후 frame restart 안 함 | YAML 변경 안 반영 | `docker compose restart frame-mcp-blue frame-mcp-green` |
| 환경변수 변경 후 `--force-recreate` 안 함 | env 안 읽음 | `docker compose up -d --force-recreate` |
| Application ID URI cleanup (삭제) | AADSTS500011 | 복원 후 propagation 대기 |
| Bitwarden secret 평문 평이메일 전송 | 노출 | secret rotation |
| Cloudflare DNS A record 누락 | DNS 미해석 | record 추가 + propagation 대기 |
| 운영자 콘솔 stale | dashboard 옛 정보 | `axe console rebuild` |

## 진단 cheat sheet

```bash
# 인프라 health
axe health &lt;customer&gt;

# Cloudflare tunnel
docker ps | grep tunnel
docker logs --tail 50 axelabs-tunnel

# Frame
docker ps | grep frame
docker logs --since 5m frame-mcp-blue | grep -v health
docker exec frame-mcp-blue python -m frame.cli integrity-check --entity <e>

# customers.yaml
cat /Users/axe/.axe/customers.yaml | grep -A 5 user_entity_map

# Microsoft Entra
# (Azure portal 또는 Microsoft Graph CLI)
```

## Escalation

위로도 안 풀릴 때:

1. 운영자 본인 → 진단 + Slack `#alerts` 노트
2. customer admin 에게 통지 (영향 범위 안내)
3. 직원에게 임시 우회 (workaround 가능하면 제공)
4. 본격 디버깅 시간 잡기 (보통 1시간 내 해결, 안 풀리면 휴식 후 fresh 접근)

## 학습 — 이슈 사후 기록

해결 후 [DECISIONS](/ops/decisions) 또는 함정 모음에 추가:
- 새로운 함정 발견했으면 표에 add
- 기존 함정 변형이면 기존 항목 update
- 향후 동일 사건 재발 시 참조 가능

---

<!-- PAGE https://docs.axelabs.ai/ops/updates -->

# 업데이트 (Updates)

> docs.axelabs.ai + 플랫폼의 ship 별 changelog + Highlights + API feed. 시간축 = 과거 (이미 한 일).

URL: https://docs.axelabs.ai/ops/updates

# 업데이트 (Updates)

> **시간축 4-페이지 분리** ([D-docs-updates-1](/ops/decisions), 2026-05-22):
>
> | 페이지 | 시간 | 용도 |
> |---|---|---|
> | [roadmap](/ops/roadmap) | **미래** | 분기 마일스톤 (M1~M5) |
> | [backlog](/ops/backlog) | **현재** | 1주 안 행동 큐 |
> | **본 페이지** | **과거** | ship 별 changelog + 큐레이션 highlights |
> | [known-gaps](/ops/known-gaps) | (사실) | 함정·미해결 |

본 페이지는 **3 섹션**:

1. **Ship Log** — 매 `axe ship SERVICE` 마다 한 줄 자동 기록 (Phase 2: [`B-axe-ship-update-hook`](/ops/backlog)). Phase 1 (현재) = 수동 append. 정직 채널, 운영 회고용.
2. **Highlights** — 사람 큐레이션. 의미 있는 변경만 narrative (직원·외부 IT 용).
3. **API feed** — [`/api/changes`](/api/changes) JSON endpoint. LLM agent 가 "지난 N일 변경" fetch.

---

## Ship Log

> 매 ship 의 한 줄. `2026-MM-DD HH:MM — SERVICE ship — COMMIT-SUBJECT` (commit hash + service stack).
>
> Phase 1 (수동 append) — 운영자가 `axe ship SERVICE` 후 한 줄 추가.
> Phase 2 (완전 자동) — backlog 의 [`B-axe-ship-update-hook`](/ops/backlog) 항목.

| 일시 (KST) | Service | Commit | 한 줄 |
|---|---|---|---|
| 2026-06-05 | vault (axe org) | (운영자 action + docs) | **vault axe.3 — 4명 KDF rotation 전부 완료 → D-ops-40 전체 종결** ([D-ops-40](/ops/decisions) Progress xiii). ai (5/27) → soohun → taehun (5/29) → jinwoo (6/4) 순서로 SSO→MP unlock 정상화. **본질 발견 = KDF dropdown 변경 불필요** — Master password change + ☑ "Also rotate my account's encryption key" 만으로 user.akey 재wrap 충분 (kdf_type 안 바뀌어도 fix 동작, ai 만 Argon2id 까지). jinwoo last_login 5/23→6/4 점프 = 완료 신호. taehun 실사용 피드백 6건 → [/onboard/vault-setup](/onboard/vault-setup) playbook 반영 (Windows section + Phase 강제도 + TOTP UI 동작 + SSO 사용자 검증 분기 + valid 변형) + [B-vault-revoke-scope-doc](/ops/backlog) (vault trust boundary). [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) ✅. **D-ops-40 전 작업 (build pipeline + 4 patches + GHCR + deploy + 검증 3건 + 정책 layer + 4명 rotation) 종결** — self-host vault 의 Bitwarden client compat + organization 권한 + SSO→MP 영구 fix 완성. |
| 2026-06-04 | docs | `22b1334` | docs(frame): D-frame-2 evidence blob-storage + D-frame-3 CF classification rule _(auto-logged by `axe ship` — curate/expand, then Highlights)_ |
| 2026-06-04 | docs | `ed65f9b` | docs(ops): netheal install complete + Claude.app pty-leak osascript workaround _(auto-logged by `axe ship` — curate/expand, then Highlights)_ |
| 2026-06-04 | hive | `48f38a1` | feat(auth): trust Blueprint platform tokens (D-axe-idp-1 Phase 2) _(auto-logged by `axe ship` — curate/expand, then Highlights)_ |
| 2026-06-03 | frame | `f1b124d` | feat(auth): trust Blueprint platform tokens (D-axe-idp-1 Phase 1) _(auto-logged by `axe ship` — curate/expand, then Highlights)_ |
| 2026-06-04 | index | `b273979` | **evidence-durability v1 — citation sha256 anchor (B-index-evidence-durability)** — 운영자 "workspace unique id" 제안 + 폴더 이동/삭제 분석에서 도출. citation 을 fragile path → stable anchor: `sha256` content-anchor(범용·무의존) + Blueprint-id(`workspace_id`/`driveItemId`/`marker`) 필드 readiness. `CitationAnchor`+`is_durable` · ingest sidecar sha256 + **propose-time fallback hashing**(skill 무변경에도 durable) · `verify_citations` MCP tool · 현황 페이지 durable% 라인. **additive**(기존 357 artifact/545 citation byte-identical) · 80 test · validate-seeds Δ0 · 공개 페이지 누출 0. blue/green deployed. deferred(v2): 545 backfill · Blueprint resolve API · driveItemId 채우기. |
| 2026-06-03 | blueprint | `57ff2ac7` | feat(auth): Blueprint as platform OIDC Provider (D-axe-idp-1 Phase 1) _(auto-logged by `axe ship` — curate/expand, then Highlights)_ |
| 2026-06-03 | blueprint | `#381`+`#382` | **전략 P3 — investment skill vertical-gate (contamination purge, D-index-47)** — 사용자 merge 승인. 8 투자 skill(ic·ingest·due-diligence·vc-deal-sourcing·investor-relations·portfolio-management·legal-compliance + pmc)에 `owner:index` 태그 + blueprint boot(`start.sh`)/webhook(`route.ts`) 양 경로 gate(customer `services.index` → 비-index `rm -rf`+skip purge, index keep). **axe 3중 안전**(services.index + `:-axe` 기본 + fail-safe keep + 운영자 ungated → simul KEEP 16/16) · realchoice/Truvia PURGE 7/KEEP 9 · `customers.ts customerHasService` + test 21/21 · tsc 0. pmc(index-only)도 base 로 mirror(gated→axe 만). PR #381(gate)+#382(pmc) squash-merged origin/main. 운영자 잔여: Truvia env 확인+재기동 purge + R7 DB residue. rollback=revert(axe 무영향). |
| 2026-06-03 | index | `6edf0ff` | **전략 P2 — index→blueprint attest sentinel + mirror mechanism (D-index-47)** — 사용자 "P2 진행". ⭐ 조사 결과 "런타임 fix" 는 **이미 달성**(P0+기존 sync): ic/ingest 가 index SoT↔blueprint origin/main↔런타임 byte-identical(attest IN-SYNC). 그래서 P2 = 위험한 content push 아닌 **메커니즘**: `index-skill-sync.py`→`--attest`(deterministic dir-sha256 drift sentinel) 재범위 + `index-skill-mirror.sh`(미래 미러, sanctioned PR flow, pmc fail-closed) 빌드. **blueprint 무쓰기·무push·무PR**, pmc 보류(P3 contamination gate 전). note-3 worry 해소 — 런타임이 stale 이 아니라 index 가 stale 이었음. |
| 2026-06-03 | index | `11aca12` | **전략 P1 — provenance stamp + schema-drift gate (D-index-47)** — 사용자 "P1만 진행"(P2/P3 명시-go 보존). 모든 propose 경로의 `artifact_event(op=propose).payload_after` 에 `_provenance` 스탬프(frozen_enums_hash 포함) + schema-drift hard gate(불일치→`SCHEMA_CONTRACT_DRIFT`, insert 전 fail-closed). frozen_enums_hash = 전용 SoT fn(D-index-15 enum + SCRUB_KINDS + ARTIFACT_REF_RELATIONS) pinned tripwire + /index/schemas 가 publish(외부 ic-push discover+pin). additive(기존 357 artifact/event byte-identical, append-only 라 retro-stamp 없음) · 66 test(+17) · sqlx clean · validate-seeds Δ0. blue/green redeploy + live 드리프트 probe 검증(무오염). |
| 2026-06-03 | index | `8ec2c10` | **seed = SoT for judgment facts — hardcoded backfill 폐기 (D-index-46, B-index-judgment-in-seeds ✅)** — 사용자 "위생 본질 전략 순" 의 본질 leg. [D-index-45](/ops/decisions) 의 1회성 hardcode backfill(`backfill.rs`+`corpus.rs` 2824 LoC)을 제거 → seed.yaml 이 judgment 단일 SoT. per-seed `judgment:`(assumptions+calibrations) + `seeds/_corpus.yaml` + seed-ingest `--emit-judgment`(natural-name anchor→corpus id 해소, idempotent·confirm-on-create). 23 seed 마이그레이션 후 두 모듈 삭제. **HARD GATE**: 전 23 seed 재ingest +0 new · committed wipe(318→0, relational 무손상)→seed-ingest 단독 +318 byte-identical 재현(42 stale dup citation pruned) · append-only trigger intact · validate-seeds 23 Δ=+0.00 · 51 test. **신규 deal 자동 artifact화** — hardcode transcription 0. |
| 2026-06-03 | index | `1c707e1` | **artifact-first judgment layer — 증거층↔판단층 결합 (D-index-45, Epic 1, 2-wave supervised)** — 사용자 "Epic 1 같이 검토하고, 실제 구현은 서브에이전트로 · 본질에 집중 quick-fix 금지". 휴면 artifact store(39 fact)→relational 23 deal 결합: 모든 투자판단 fact 를 일급 typed+cited+audited artifact 로 승격. migration 0(generic store 재사용), 4 kind(assumption·calibration·comp·base_rate), 링크=일급 citation(index_field+artifact_ref relation, side-bridge table 아님). **23/23 deal → 357 fact**, 0 orphan judgment value. additive-only 3중 증명(event propose/confirm 만·relational updated_at 미전진·validate-seeds Δ=+0.00), 48/48 test, sqlx --check clean. ⭐ adversarial gate 가 wave1 61% 미완 적발 → wave2 5딜 author + 6 rival backfill module → 1 `backfill.rs` 통합. 방향: structured-seed 파생[B-index-judgment-in-seeds]·Epic 2 confidence load-bearing·Epic 3 self-calibrating loop. |
| 2026-06-03 | docs | `3eade41`+`19ffd2c` | **backlog C1–C5 인터랙티브 정비 + axe-cli ship-hook/drill ✅ 반영** — 운영자와 C1(entity legal영문+display한글, frame/hive/blueprint 마이그레이션 준비·미적용)·C2(axe-cli git-track → 비공개 `axelabs-ai/axe-cli`)·C3(`axe drill` freshness+robust-canary · `axe ship` post-deploy Ship Log hook)·C4(설계 DRAFT 5건 보존)·C5(미커밋 코드 전부 보존) 순차 해결. ⭐ **premise 정정**: B-backup-restore-drill = drill 메커니즘 강화일 뿐 postgres 실제 restore drill 은 미완(open 유지). 동반 게시: D-hive-29 payroll UPSERT/adjustment docs · @axe/ui resync. ⭐ 본 row = ship-update-hook 첫 실가동 산출(자동 stub → curate). |
| 2026-05-30 | index+blueprint | `931284b9`+`c8b3746` | **ingest 데이터품질 metric_kind 세분 + lifecycle 회귀 스위트 (D-index-44, 5축 평가 2 unit 병렬)** — 사용자 "지금 가능한 작업, 본질·퀄리티·결과·안전·혁신". **(X)** blueprint PR #380: convert_xlsx metric_kind 세분 — coarse valuation(절대 EV+EV/EBITDA 배수+음수 혼재, reconcile 가 노출한 결함) → `valuation`/`multiple`/`moic` 분리 + curation(음수/absurd helper drop). 52/52 test, irr·moic·cagr 0 regression(XIRR function-path 무영향). webhook sync live. **(Y)** index `c8b3746`: artifact lifecycle 회귀 8 test (idempotency·status 파생·confirm/reject·append-only(grant+trigger 이중)·RLS 격리·reconcile·seed-draft non-ingestability serde-reject), 35 pass 0 residue, offline-safe. ⭐ 발견: append-only trigger 가 ON DELETE CASCADE 차단 → event 보유 artifact 삭제불가 = audit 영속성. **통합**: 정제 classifier 재ingest → store refresh → valuation 12 + multiple 4 split 반영(39 facts). self-correcting 루프(reconcile 가 노출 → source fix). |
| 2026-05-30 | index | `3eece93`+`118568a` (deploy) | **artifact-first lifecycle 완성 — Query API+ctx review+reconcile+seed-draft (D-index-43)** — 사용자 "서브에이전트로 종결 후 보고". D-index-42(propose) 잔여 4개를 2 supervised subagent 순차 구현 + 1 blue/green. **(1) Query API**: `query_artifacts`/`get_artifact` (status=최신 event.op 파생). **(2) ctx review**: `confirm_artifact`/`reject_artifact` (op=confirm/reject, append-only 감사). **(3) reconcile**: `reconcile_artifacts` — metric_kind 별 value spread flag(불일치 전량 surface, silently 택1 금지; Apposter irr 86% flag). **(4) L2 본령 seed-draft**: `draft_seed_from_artifacts` — deal artifacts → 보수적 seed.yaml SCAFFOLD(`index draft-seed`). ⭐ 날조금지 구조강제: surface→audit주석 only, calibration·intake·baseline 전부 `~ TODO`, valuation 후보다수 자동선택 거부, draft non-ingestable(validate-seeds fail). coverage auto_filled 0/needs_human 18/surface 29. RLS 정식경로, build online+offline clean, 27 test, 6 MCP tool live(ext healthz 200). artifact-first 전 lifecycle 가동(propose→query→review→reconcile→draft). 잔여: ctx review UI(Blueprint)·Query API /ic 통합·extractor metric_kind 세분·전 deal artifact화. | — 사용자 "ingest 때 artifact화 한다던 것 구현됐나?" (정직 확인). **gap 발견**: index artifact/citation/artifact_event store([D-index-2](/ops/decisions) cortex mirror)가 Day-1 이후 **0행 미사용** — 23-deal 은 relational 테이블에만, artifact-first 층 dormant. **구현**(subagent + orchestrator QC): `propose-from-ingest` CLI + `propose_artifacts_from_ingest` MCP tool — D-index-41 sidecars(`cells.json`/`figures.json`) → 각 key_output/figure = `artifact`(extracted_metric|extracted_figure) + `citation`(cell/page 증거) + `artifact_event`(op=propose). RLS 정식경로(index_app+index.actor GUC, `db::set_current_user` 첫 실사용자), idempotent. **before/after (Apposter)**: store **0 → 35** (31 metric+4 figure, 1:1:1 artifact:citation:event). Exit IRR 57.2% = typed artifact(`metric_kind=irr`)+citation `Return!Y62`+propose event. append-only+RLS live 검증. build clean(online+offline, sqlx guard), blue/green 재배포 — `propose_artifacts_from_ingest` MCP tool live(both healthy, ext healthz 200). [D-bp-artifact-5](/ops/decisions) "proposed fact" 전반부 실현. 잔여: ctx review + Query API + L2본령(seed-draft) + L3 reconciliation. |
| 2026-05-30 | blueprint | `PR #379` | **ingest 고도화 L1 — 재무모델·IR structured extraction (D-index-41)** — 사용자 "ingest 역량 끝까지 고도화, 서브에이전트로". impl agent(worktree, skill-sot-guard 준수) + orchestrator QC. ingest 가 dataroom xlsx/pdf 를 md photocopy 하던 lossy 문제(수식 40개 truncate → `<!-- formulas: +182 more -->` 매몰, 기계추출 불가) 해소. **convert_xlsx v2**: `{stem}_xlsx.cells.json` (full grid value+formula+number_format+label, named_ranges, **key_outputs[]** XIRR/IRR/NPV/MoM/CAGR/valuation 자동탐지) + md Model Summary/Key Outputs/formula↔value 표. **convert_pdf v2**: `figures.json` 라벨인접 재무 figure sweep. 숫자=mechanical only([D-index-15](/ops/decisions)), citation(cell/page) 자동. **before/after (Apposter 20-sheet model)**: Exit IRR `=XIRR(…)` 가 truncated 주석 매몰 → **31 key outputs 자동 surfacing** (Exit IRR 57.2%/50.4%·MoM 8.60x·Entry EV 270억·9x exit, 값+수식+라벨). test 40/40 PASS·기존 포맷 무변경·의존성 0·datetime fix. QC: broad-recall false-positive(date·mislabel CAGR 25M) numeric+rate 게이트로 34→31 정정(true output 보존). PR #379 merged→main(`3a9966bd`)→launchd webhook sync→`~/.claude/skills/ingest` v2 live. [B-index-ingest-structured-extraction](/ops/backlog) L1 ✅(L2 typed seed-draft / L3 reconciliation / L4 versioned-diff 잔여). |
| 2026-05-30 | index | `de47a2c` | **Render/리얼초이스(23rd) 적재 + par-entry cheap-option = E[CF] 극단 (D-index-40) — 데이터룸 소진, DB 23** — 사용자 "더 추가할 프로젝트?". 데이터룸 전체 스캔 → 적재가능 신규 = Render 1건. **Render = 리얼초이스/트루비아**(데일리퓨어크레아틴, 크레아틴 건기식). best-effort SCREEN, status=passed (미투자 — AXE 플랫폼 고객이나 고객≠투자집행). ⭐ **par-entry**(5,000만@100원=액면=순자산, 트루비아 벤처확인 enabler 신주) → 어떤 성공도 거대 multiple → **E[CF] 35.13%**(랭킹 4위 수준)이나 **E[MoM] 4.53x·P(loss) 68%·median 손실**. exit multiple 은 0.8-1.4x commodity scrub 완료([D-index-26](/ops/decisions) fantasy 아님) — 높은 E[CF]=par 진입 구조적 산물. ⭐ **[D-index-25](/ops/decisions) poster child**: E[CF] 단독 랭킹은 par-entry 딜에서 오해 — Render 35% = top deal 아닌 **68% 손실확률 cheap call option**. SCREEN=PASS, 단 5,000만=트루비아 벤처확인 enabler+고객관계 cheap option 으로 재무 IC 와 분리. deal_id eb83b883. **데이터룸 소진**: 잔여 Whale=위시켓(자료 확보 시)·DHP 3(빈 폴더)·Artemis(AXE 자체 제품)·델리후레쉬(RFP)·thin lead 5 = 비-딜/자료대기. **23-deal 랭킹**: Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > **Render 35.13(⚠par cheap-option)** > Canopy 31.8 > Interstellar 30.5 > … > Open Research −25.85. validate-seeds Δ0 Pass. |
| 2026-05-30 | index | `7d6ccca` | **Archive batch 6-deal 적재 (17~22th, D-index-39) — 전부 correctly-avoided — DB 22** — 사용자 "1_Project (Archive) 6건 모두 best effort 검토". 6 병행 agent + orchestrator 양방향 QC. 전부 archived=미투자 → [D-index-24](/ops/decisions) calibrated canonical. **Medistaff**(의료진, screen) **−0.59%** (founder 형사 jeopardy+두나무 lead) · **Open Research/oo.ai** **−25.85%**(P loss 90%) — ⭐ "deal structure ≠ company quality"(회사 2,000억 라운드 중이나 창업자 개인 distressed 담보 secondary bridge, 도박/사채/팀 9-of-9 이탈) · **JS E&L**(2차전지 부품) **−1.97%**(EV 캐즘·자본잠식 임박, PER 16x→2-8x scrub) · **Catalyst/클래스카드**(교육 PE buyout) **16.99%** — index 2nd buyout + 첫 PEF/GP구조(AXE=GP, committed=consortium 170억, 10x flat exit→5-9x scrub+60% LTV wipeout, first-time-GP 0 commit, "높은 IRR≠Go") · **데이톤/DATON**(DC AI Ops, screen) **16.57%**(흑자 100억 매출·DC tailwind 진성이나 terms-void) · **Apposter/b.ring**(스마트링) **8.34%** — ⭐ "field DD kills thesis"(현장실사 Bic Camera 방문→commodity 입증→Case Drop, Oura 10x PSR→2-3x scrub). ⭐ 교훈: (1) negative-E[CF] 기록 = PASS 결정의 정량 검증, (2) 양방향 QC(instrument floor·fat-tail scrub·wipeout)가 agent 에 briefing 만으로 전파. **22-deal 랭킹**: …EGA 23.3 > (Superman 20.8) > Catalyst 16.99 > 데이톤 16.57 > Infinity 16.5 > Eduon 15.0 > 디벨로퍼그룹 14.76 > 수성별 14.0 > Sendy 11.7 > Nanora 10.1 > Novachips 9.2 > Apposter 8.34 > 유비랩 4.06 > Medistaff −0.59 > JS E&L −1.97 > Open Research −25.85. validate-seeds Δ0 6/6 Pass. |
| 2026-05-30 | index | `c0bf6d5` | **디벨로퍼그룹(15th)+유비랩(16th) 적재 — buyout-class + 양방향 QC (D-index-38) — DB 16** — 사용자 "디벨로퍼그룹·유비랩 검토". 입력 richness 양극. **디벨로퍼그룹 스터디카페 사업부 100% 영업양도** = index **최초 buyout-class**(PE형 캐시카우 M&A, AXE 12억/EBITDA 3.87x, 무차입, 보통주/secondary). full IC v5 surface 공식 34.09% → **메모 자신의 Devils-reweighted 16.5% anchor**([D-index-24](/ops/decisions) 미집행→calibrated + [D-index-26](/ops/decisions) Exit 5.0x→4.0x·조정EBITDA·kakao 9,251M fantasy scrub + [D-index-21](/ops/decisions) genuine wipeout) → **E[CF] 14.76% / E[MoM] 2.02x / P(loss) 15%**. ⭐ buyout 신 insight: cashflow buyout 의 FCF 배당이 실질 하방 floor → downside ~1.1x(원금손실 거의 없음), **P(loss) VC 대비 구조적 저**. deal_id b88e2dcb. **유비랩**(그래핀/그라파이트 방열 시트 deep-tech, OLED foldable+AI 반도체 TIM) SCREEN(병행 agent + orchestrator QC): elite founder(유봉현 삼성D 33년·NeoGraf 美VP)+삼성D/애플 샘플 진성 traction 이나 component multiple cap(직접경쟁사 신화인터텍 EV/Rev 0.2x)+pre-rev hockey-stick(92억@3y 2,500x)+Samsung 단일고객 → **"좋은 회사 ≠ 좋은 딜"**(Interstellar/Novachips 가족). ⭐ **양방향 QC** (D-index-37 보완): agent 가 base 를 as-converted(0.76x)로 계산해 E[CF] 2.9%/P(loss) **80%** 산출 → 본인 가정 RCPS 1x 우선권을 base(EV 143억≫20억)에 미적용한 **내부 불일치 artifact** 교정(우선권 floor 일관적용 base 1.0x) → **E[CF] 4.06% / P(loss) 43%**(peer 정합). QC=올바른 수치 착지(낮은 수치 아님) — fat-tail 도 instrument-floor artifact 도 교정. deal_id c98ba89e, stage=Screening. **16-deal 랭킹**: Sentry 43.5 > … > Eduon 15.0(screen) > **디벨로퍼그룹 14.76(buyout)** > 수성별 14.0 > Sendy 11.7 > Nanora 10.1 > Novachips 9.2 > **유비랩 4.06(최하, screen)** (+ Superman 20.8 별도). validate-seeds Δ0 둘 다 Pass. |
| 2026-05-30 | blueprint | `247b41f8` | **send_mail MCP 도구 — 범용 outbound email (D-bp-mcp-mail-1)** — `create_event` 형제. caller 본인 mailbox 발송(delegated `Mail.Send` 이미 SCOPES → self re-consent 불요) + admin send-as(`as_user_email`, app-only `Mail.Send`+consent 선행). 신규 route `POST /api/internal/mail` + Python tool `mail.py` + append-only `MailSendLog` audit(`sent`/`dry_run`/`failed`) + migration `20260529120000_add_mail_send_log`. params to/subject/body(html\|text)/cc/bcc/attachments(base64)/save_to_sent_items/dry_run. 에러 `send_as_forbidden`/`recipient_invalid`/`mail_send_not_consented`/`graph_error`. Graph `sendMail` 202 no-body → `message_id` null. ⭐ **동시 세션 격리 배포**: 내 커밋만 origin/main 위로 cherry-pick(247b41f8), 다른 세션의 unpushed `579a0fa1`(index-skill-sync) + 미커밋 WIP 는 `wip/index-skill-sync-579a0fa1` + stash 로 보존하고 배포 제외. |
| 2026-05-30 | index | `fc56004`+`7b4a50d` | **EGA·수성별·Nanora 3-deal batch 적재 (12~14th deal, D-index-37) — DB 14** — 사용자 "EGA·Nanora·수성별 모두 진행" + "Nanora full ic". 3 병행 background agent(deal당 1) + orchestrator QC. ⭐ **핵심 교훈 — full-IC 메모를 blind transcribe 하면 안 됨** (메모 rigor 가 deal 마다 극과 극): **EGA**(디파이넘버, NMN 뉴트리코스메틱) 메모는 surface-optimistic → agent 가 그대로 옮긴 E[CF] **127%**(매출 16억→550억 34x + EV/Rev 7× + 18x MoM@2y, wipeout 無)는 [D-index-26](/ops/decisions) fat-tail 환상(Iippo 74% 재현). status='passed'(미투자)라 [D-index-24](/ops/decisions)상 calibrated 가 canonical → **scrub**(ramp 16→300/120억 + EV/Rev 5×/3.5× K-beauty M&A anchor + **genuine wipeout 0.2x**: 창업자 이력 부재·매출 16억 미검증 red flag) → **calibrated E[CF] 23.3%** (E[MoM] 2.33x, P(loss) 40%); surface 는 헤더 audit trail 보존. 반면 **수성별**(국군복지단 DOOH 광고, 우선협상대상자) 메모는 이미 보수적 — Σp −23.8% → E[CF] **+14.0%**(sign-flip, Interstellar 패턴). 단 **deal 조건 전부 dataroom 부재**(10억/30억/25% 가정) + 팀공백 + CAPEX gap = info-void Conditional(stage Passed, instrument TBD). **Nanora**(US precision-wellness, TCM→구독 supplement+smart ring+AI, SAFE @ $9M post cap, pre-launch)는 사용자 지시로 **SCREEN→FULL IC 승격**: 18-section + multi-scenario + adversarial(proponent/premortem-critic 분리). E[CF] **10.05%**(E[MoM] 1.76x, P(loss) 50%) — Care/of($225M→Bayer→2024 폐업) category-graveyard + Pre-Seed→A 85% fail base-rate 로 회사 plan 하향, 판정 **Conditional**(결정변수 = post-launch 90-day cohort retention, T+9M revisit). **QC 결론**: agent batch 는 효율적이나 transcribe 산출은 반드시 orchestrator 가 fat-tail/wipeout/base-rate QC (EGA 127%를 적재 전 차단). **14-deal canonical E[CF] 랭킹**: Sentry 43.5 > Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Interstellar 30.5 > Hancom 23.9 > **EGA 23.3** > Infinity 16.5 > Eduon 15.0(screen) > **수성별 14.0** > Sendy 11.7 > **Nanora 10.1** > Novachips 9.2. 엔진 재확인: `validate-seeds seeds/*.yaml` 전 seed status Pass — **EGA E[CF] 23.30% · 수성별 14.02% · Nanora 10.05%** (docs 값 정합), baseline Δ0 regression 은 committed-baseline 3-deal(Iippo/Sentry/Canopy)에만 적용·나머지는 live-computed. |
| 2026-05-30 | index | `eduon seed` | **SCREENING 단계 정규화 (D-index-36) + 에듀온 11th deal (첫 Screening)** — 사용자 "screen 단계 추가 + 정규 프로세스화 + 적재". 1-pager inbound 에 19-agent `/ic` 바로 돌리는 GIGO 방지용 **Screening 게이트** 신설 (deal.stage 'Screening' enum 기존재 — migration 불요). 프로토콜: 외부 리서치 5종 + base-rate calibrated 재무모델 + engine IRR(E[CF]) + premortem 필수, dataroom 불요, "DD 자원 투입 가치" 판단(Go/No-Go 아님). **첫 사례 에듀온**(초등 영어 Writing 프랜차이즈 Seed 보통주 5억@Pre 20억): WebSearch 5 + franchise rollout 재무모델 → **E[CF] 15.0% / E[MoM] 2.0x / P(loss) 45%**. ⭐ 교훈: 회사 IRR 58% / Claude ad-hoc 26.5%(upside 10x) → **calibrated 15%** — 가맹 "3년 1,000"(3030영어 21년→1,400) + exit "3x rev/300억"(크레버스 0.59x·웅진 0.20x) 두 낙관이 base-rate·comp 에 깨짐 → upside 6x cap. **Screen=PASS(DD 미진행)** + 재screen 조건(RCPS+Pre 10-12억+가맹 traction). 산출물 `ic/{research,finance,memo}/` + index 적재(deal_id 2bb5d585). 향후 ic skill screen-mode = [B-index-ic-screen-mode](/ops/backlog). DB 11 deal. |
| 2026-05-30 | index | `7269286` | **Interstellar (인티그레이션) 적재 — 10th deal (D-index-35)** — 사용자 "추가 적재 프로젝트?" → 데이터룸 스캔, IC 분석 완료·미적재 = Interstellar 1건 (Render IC 미완 / Whale admin docs / 델리후레쉬 RFP / Pipeline 스크리닝 — 미대상). 인티그레이션(한의·치과 5-카테고리, 한의사 가입률 83%) Series D RCPS, AXE follow 검토 20억 **PASS** (알토스+네이버 lead 종결). D-index-24 PASS→calibrated canonical (status='passed'). **E[CF] IRR 30.5% / E[MoM] 3.23x / P(loss) 36.0%** (IC surface Σp 25.3%). ⭐ PASS 사유=거버넌스(R6 자기거래 IPO reject≥30%)+1.6% minority, **IRR 아님** — 9-deal 중 5위(Canopy 31.8 > Interstellar 30.5 > Hancom 23.9)인데도 PASS = "높은 IRR ≠ Go". 부수: seed.rs SERIES_OK 에 Series D/E 추가(누락 보완). validate-seeds 12 Pass / 23 test / DB 10 deal. (live MCP 는 DB 데이터 즉시 반영 — SERIES_OK 는 ingest-only 라 재배포 불요.) |
| 2026-05-29 (eve8) | index | `537c04e` (deploy) | **live index MCP blue/green 재배포 — D-index-25~34 코드 라이브** — 그간 commit/검증만 됐던 index 코드(option/passed status·intake 게이트·Σp 폐기·instrument·E[CF] canonical)가 live MCP 에 미반영(blue/green 컨테이너가 35h+ 구 바이너리 서빙 = 새 데이터에 구 코드 = option/passed 오집계)이던 것 배포. `axe ship index` = `manual_hint`(자동화 미구현, [B-index-azure-app](/ops/backlog) 후 frame_blue_green 승격 예정)라 **수동 compose 재배포**: `docker compose build` (SQLX_OFFLINE + `.sqlx` 최신) → green 재생성·healthy·new-binary 검증(sentry option 수락 + E[CF] 43.5% + 폐기코드 가드) → blue 재생성(alias 유지, Caddy `lb_try_duration 5s` 가 restart blip 흡수)·healthy → 검증. **DB 데이터는 이미 current** (option 1·passed 4 status + intake 필드 11/12, baseline 은 live 계산이라 financial_output 0행 = 정상) → 재적재 불요, 코드만 stale 이었음. 검증: 내부 healthz + 외부 `https://axe.axelabs.ai/index/healthz` 200, 4 컨테이너 healthy, 두 이미지 fresh(14:48). |
| 2026-05-29 (eve7) | index | `537c04e` | **canonical E[CF] 랭킹 확정 (D-index-34) + seed 주석·description E[CF] 재기재** — "정확도 심화" 마무리. **(1) D-index-34**: D-index-19/21/23/24 의 인라인 랭킹이 Σp/surface 기준이던 것 → engine `validate-seeds` 로 9 deal E[CF] 재산출, canonical 랭킹 확정: Sentry 43.5 ≈ Iippo 43.3 > Starnex 38.1 > Canopy 31.8 > Hancom 23.9 > Infinity 16.5 > **Sendy 11.7 > Novachips 9.2** — 구 Σp 대비 **tail flip** (Sendy↑Novachips) + Sentry-Iippo 거의 동률. Infinity executed 특례: v8 모델 불변(D-index-24) + 집계만 E[CF] 16.5%(D-index-32), IC headline 13.8% provenance. D-index-23/24 인라인에 "⚠ pre-E[CF] → D-index-34" 마커. **(2) seed 주석 정합** (index `537c04e`): starnex 36.4→38.1·hancom 22.4→23.9·sendy 6.5→11.7·infinity 13.8→16.5 주석 E[CF] 재기재 (value 불변). **(3) description 정정** (index `21e533d`, 병행 에이전트): 재척도 후 stale "3억 ×"(starnex→20억)·"× 10% = 222.5억"(sendy→2%/44.5억). **(4) #82 driver refactor 이미 완료 확인** (Iippo/Canopy 단일 revenue_growth). proceeds-bridge-retrofit(#81)은 날조위험+D-index-24 충돌로 보류. 11 seed validate Pass, E[CF] 전부 불변. |
| 2026-05-29 (eve6) | index | `74e1eb4` | **irr_instrument_adjusted 폐기 (D-index-33) + Σp output_code 가드** — 사용자 "수익성 정확도 심화" 선택 후 조사. **발견**: exit_matrix leaf recovery 가 instrument 구조를 이미 전역 반영 (RCPS preference floor: Sentry 0.05~0.14·Starnex 회생 1.10x / 보통주 후순위 wipeout: Hancom 0.30·Sendy 0.15·Novachips 0.20·Infinity 0.12) → IRR(E[CF])가 이미 instrument-aware. Novachips 1건의 `irr_instrument_adjusted`(-4.55% = E[CF] +9.2% −12pp)는 leaf wipeout(0.2x) **이중계상** (Σp·IRR 동형 함정). **조치**: (a) novachips baseline 제거 + 헤더 재프레이밍, (b) `seed.rs` DEPRECATED_OUTPUT_CODES load-time hard reject — `irr_instrument_adjusted`(D-index-33) + `irr_loss_included`/`irr_success_only`(Σp, D-index-32 완결), (c) overlay 잔존 Σp 정합 — infinity_recalibrated/superman_fresh 의 `irr_loss_included` → `irr_expected_cashflow` (engine E[CF]: Infinity -4.3% [구 Σp -8.3%] / Superman fresh 20.8% [구 Σp 10.5%]). [B-index-instrument-adjusted-irr](/ops/backlog) won't-do close, [B-index-docs-irr-ecf-restate](/ops/backlog) 신규(docs IRR 다수 pre-E[CF]). 11 seed validate + 23 test + 음성 테스트 Pass. |
| 2026-05-29 (eve5) | index | `3b2f543` | **투자성 intake 게이트 + option/passed status + Σp·IRR 폐기** ([D-index-29](/ops/decisions)/[30](/ops/decisions)/[31](/ops/decisions)/[31b](/ops/decisions)/[32](/ops/decisions)). 사용자 thread: "Series A Option 표현? / pass 도 IRR 관리하되 fund·project 제외 / 최소 intake (entry·valuation EV vs EqV·라운드·규모·Series) / 신주 구주 혼합 / p IRR 폐기 + 남은 것 모두". **D-index-29** `status='option'` (pro-rata 권리 미행사) — committed_total·baseline·fund·per-position IRR 전면 제외, IRR=null (Sentry 후속 5억 option 재분류, commit `9523638`). **D-index-30** `status='passed'` (검토 미투자) — what-if IRR 보존하되 fund/project baseline 제외 + all-passed fallback (`incl()` closure 공통화); 5/29 배치 정정 동반 (Canopy BW = Canopy 내 passed position 4.2% warrant, per-position BW IRR 28.0% &lt; RCPS 31.8% 정합 → 별도 deal CanopyBW 삭제; Sentry 1호·Iippo 1·2호·Starnex 20억/8월말·Hancom 5억/7월말·Sendy 10억 Pre-C·Novachips 6/10; proceeds 비례 재척도로 IRR 보존 Starnex 38.1%/Hancom 23.9%/Sendy 11.7%, commit `f650bec`). **D-index-31** 투자성 분석 최소 intake 게이트 5 필수 필드(series·round_size_krw·committed_krw·entry_date·pre_money_krw) + EV/EqV 영구 차단(entry=항상 EqV·exit=proceeds_basis) + `_TEMPLATE.yaml` (intake_enforced 2-tier: 신규 hard·기존 warn); 9건 backfill (commit `c4c12f4`+`9e86a07`). **D-index-31b** `share_type` 신주(primary→post 반영)/구주(secondary→post 불변) + 혼합 `round_primary_krw` + post≈pre+신주 ±2% invariant (Infinity pre 499.5→400억 정정으로 검증; Hancom·Novachips secondary, commit `98b88c2`). **D-index-32** Σp·IRR(rate 평균, 오집계) 폐기 → IRR(E[CF]) 단일 canonical: query_irr/html/xlsx 에서 `weighted_irr_*` 제거 + `irr.rs` 함수 `#[deprecated]` + 9 baseline·validate output_code 전환; E[MoM]은 linear 집계라 유지 (23 unit test + validate 3 PASS, commit `3b2f543`). 부수: superman_fresh entry_date 보강 → 실 seed `entry_basis=assumed` 0건, [B-index-entry-date-backfill](/ops/backlog) + [B-index-deprecate-sump-irr](/ops/backlog) ✅. |
| 2026-05-29 (eve4) | index | `85c8481` | **IRR 방법론 stack — 기대현금흐름 IRR canonical + per-fund 수익성 + fat-tail scrub + 미집행 timing** ([D-index-25](/ops/decisions)/[26](/ops/decisions)/[27](/ops/decisions)/[28](/ops/decisions)). 사용자 thread: "확률 IRR 폐기 보류 + 추가투자 별도 + 1·2·3호 펀드 수익성 + Iippo 2호 분석 + cashflow IRR 정확한 표현 + 2호 IRR 동일 의문". **D-index-25** 기대현금흐름 IRR = IRR(E[CF]) (확률을 CF 에 먼저 적용 → IRR) 를 canonical 로, Σp·IRR(rate 평균, 오집계)은 병기(폐기 보류) — 반드시 E[MoM]+P(loss MoM&lt;1) 동반 (`irr.rs::expected_cashflow_irr`, commit `2d2066f`). **D-index-27** per-position(`position_ecf_irr`, ratio-split + deal_paid_offset) + per-fund(`fund_performance`, axe_ia_001/002/003 횡단 pool) IRR; Iippo 2호 = 가공 follow-on 제거 → 실제 **AXE Private Fund II 개인투자조합** Pre-A 공동투자 1억 RCPS, 별도 IC Memo (commit `7e313b5`). **D-index-26** fat-tail leg comp-scrub 를 **canonical 에 직접 적용**(이전 overlay-only 라 74% 환상 잔존): Iippo mgmt 1~2.5조→1,000~2,500억(강남언니 8x ceiling) E[CF] 74%→43.3%, Sentry upside 47x→14.7x(마스턴 AUM), Canopy 12x→6x EBITDA(Bird) — IC 원본 주석 보존 (commit `8c5e60e`). **D-index-28** 2호 IRR 이 1호와 동일했던 건 paid_date=null→offset 0 silent fallback (계산식은 정확; 격리 테스트 +1개월 44.24%/+4개월 47.40%, exit=calendar 고정이라 늦은 entry=짧은 hold=높은 IRR); 수정 = 2호 entry 2026-06-15 가안(planned)·paid null 유지 + `entry_basis {paid/planned/assumed}` never-silent flag + `fund_ecf_irr` 의 `.max(0.0)` 클램프 버그(deal_ref&lt;fund_epoch 음수 offset 정상) 제거 → 단일 position 펀드 IRR 가 standalone 과 일치 (commit `85c8481`). 부수: flag 가 Hancom·Novachips·Sendy·Starnex·Superman entry date 누락(`assumed`) 노출 → [B-index-entry-date-backfill](/ops/backlog) 진행. validate-seeds 9-deal Pass, DB 9 deal 정합. |
| 2026-05-29 (PM12) | cortex | (interactions 참석자 표시 + 대시보드 폴리시) | **interactions 참석자 표시 + 대시보드 포맷 폴리시** (운영자 피드백 연속). **(1) 참석자**: /cortex/interactions 에 참석자 정보가 없다는 지적 — 데이터는 `attended` relationship 으로 이미 연결돼 있었으나 화면 미표시(display gap). list 2번째 컬럼을 "참석자 / 일시", detail 에 "참석자 (N)" 섹션 추가 (person 링크). **방향 불일치 흡수**: log_interaction 은 from=interaction→to=person, xlsx_hpe 백필은 from=person→to=interaction 으로 만들어 양방향 모두 resolve (`fetch_attended_participants`, `$iid IN (from,to)` 후 반대쪽 endpoint=person). 36 interaction 전부 참석자 연결 확인. 데이터 정규화 migration 은 미실시 (display 흡수, [known-gaps](/ops/known-gaps) 기록). **(2) 대시보드**: stat 카드 값에 단위(명/건) + 천단위 콤마(fmt_n); "전체 인원"→"전체" + total_orgs("N개 회사") sub 추가. **(3) 404**: 운영자가 본 /cortex/interactions 404 는 직전 blue/green --force-recreate 재시작 윈도우(수초)의 일시적 현상 — 라우트 정상, 재현 안 됨. blue/green --no-cache rebuild (binary 4465506b). |
| 2026-05-29 (PM11) | cortex | (D-cortex-customer + dashboard 사람중심 재편) | **고객 태깅(다대다) + home 대시보드 사람중심 2-row 재편** ([D-cortex-customer](/ops/decisions), [D-cortex-dashboard-redesign](/ops/decisions)). **(1) 고객**: 운영자 "1명이 여러 건(프로젝트 a/b/c)으로 고객 가능, 우선 수동 태깅". 고객 = subject 에 붙은 ≥1 customer_case attribute (다대다). tag_customer(subject_id, case, note?) — (subject,case) 멱등, person 은 network 자동 승급; untag_customer — 해당 case archive (tier 강등 X). MCP 23→25 tools. **(2) 대시보드 재편**: 운영자 "relationship 은 사람에게 안 중요". kind 카드 그리드 제거 → 사람중심 2-row: 구글연동 → Push대기 → 전사 row → 안심주석 → 나의 row. 각 row = 전체 인원 · 네트워크 N명/N개 회사 · 고객 N명/N개 회사 · 1개월 활동 N건/총 N건. NetworkStats 한 구조+쿼리를 per-user(RLS)·전사(superuser) 재사용. 안심 주석 "네트워크 아닌 인원은 조직 내 비공유". 검증 나의 row: 총 3600/네트워크 624/회사 413/고객 0/활동 1·1. blue/green --no-cache rebuild. |
| 2026-05-29 (PM10) | cortex | (D-cortex-org-stats + import-xlsx=network 정정) | **전사(cross-user) 집계 대시보드 + import-xlsx tier=network 정정** ([D-cortex-org-stats](/ops/decisions), [D-cortex-person-tier](/ops/decisions)). **(1) 전사 집계**: 운영자 "대시보드에 조직 전체 통계도". 범위 = 전사 cross-user + 전 직원 visible + 합계만(직원 익명). `fetch_org_wide_counts` 가 set_current_user 미호출 → cortex superuser 연결(bypassrls)로 모든 owner artifact 를 kind별 COUNT + distinct owner 수만 집계 (개별 레코드·owner 분해 X — D-cortex-2 격리 유지, 익명 숫자만 공유). home "조직 전체" 섹션 + 익명 callout + non-link org_metric. 집계 person 3600/relationship 3071/org 1500/deal 17/interaction 1/users 1. **(2) import-xlsx=network 정정**: 운영자 지적 — Network_CRM.xlsx 는 큐레이션 인맥이라 import 가 만지는 person 은 pool 아니라 network. create_person_from_xlsx_row payload tier='network', matched(Google pool) person 도 system:xlsx-migration 이 promote (멱등). ImportStats.tier_promoted. **(3) 등록자 추적 확인**: created_by(artifact) + actor(artifact_event append-only) 가 shared 포함 누가 등록·수정했는지 전부 기록 (현재 per-user 라 actor 는 `본인 또는 system:*` 뿐; cross-employee attribution 은 D-cortex-9 Phase 2). blue/green --no-cache rebuild. |
| 2026-05-29 (PM9) | cortex | (D-cortex-person-tier — pool/network 운영 자동화) | **person tier (pool\|network) 도입 — 자동 sync 연락처 vs 운영자 인맥 분리 + auto-promote** ([D-cortex-person-tier](/ops/decisions)). 운영자 관찰: Google Contacts 3,601 중 대부분이 raw 연락처라 "내 인맥" 뷰 오염. backfill = network 625 / pool 2,976. **기본값**: Google sync 신규 person = pool (sync.rs INSERT; 기존 tier 는 enrichment 키라 overlay 가 안 건드림), register_person = network (운영자 명시 등록 = 인맥; tier='pool' 명시 허용). **auto-promote (pool→network, 멱등)**: classify_person / register_relationship(person endpoint) / log_interaction(participant) 어느 액션이든 대상 person 자동 승급 (tier_source='auto_promoted_from_&lt;action&gt;', audit actor='system:auto-promote'). 한 helper 가 3 handler 의 tx 안에서 호출. **network→pool 강등 없음** — 유일 역방향 = 명시 demote_to_pool(person_id, reason) MCP tool. **노출**: list_persons + web /cortex/people 기본 tier='network', ?tier=pool\|all 확장; home People 카드 = 내 인맥 값 + 풀/전체 sublabel. **D-cortex-3 정합**: tier=enrichment 키 → sync 보존. 회귀: overlay_never_touches_tier_enrichment_key (sync.rs 6 tests). MCP 22→23 tools. blue/green --no-cache rebuild (PM8 leader election + Dockerfile cargo test gate 동반). |
| 2026-05-29 (PM8) | cortex | (D-cortex-leader-election + Dockerfile ship hook) | **D-cortex-3 PM7 의 본질 해결 — leader election (pg_try_advisory_xact_lock) 도입 + Dockerfile 안 cargo test 자동 회귀 차단** ([D-cortex-leader-election](/ops/decisions)). PM7 의 fix 는 "둘 다 --no-cache 재빌드 + binary sha 일치 검증" 운영 invariant 였는데 본질 = blue/green 둘 다 run_loop 를 돈다는 것 자체. binary 동일성은 race 가 일어나도 같은 결정을 내리는 우회 — race 자체 차단이 본질. 5축 평가 (본질 5 · 결과 5 · 혁신 5 · 퀄리티 4 · 안전 4 = 23) 로 가장 강한 옵션 선택. **구현**: `src/google/sync.rs::run_cycle` 시작 시 transaction 열고 `pg_try_advisory_xact_lock(2026052907)` 시도. 성공 시 leader → 본문 실행 → commit (lock auto-release). 실패 시 INFO 로그 후 skip. **Transaction-scoped lock** = COMMIT/ROLLBACK/disconnect 시 auto-release → leader panic·crash 해도 무인 페일오버. **부수효과**: Google API quota 절반 (2× → 1×), DB 부하 절반. **Ship hook (직교 추가, 점수 18)**: Dockerfile RUN 안 `cargo build --release && cargo test --release --bin cortex google::sync::tests` 한 줄 — test 실패 시 image 생성 자체 불가 → 옛 destructive 코드가 production 으로 흘러갈 수 없음. **검증**: (1) psql 두 세션 동시 `pg_try_advisory_xact_lock(2026052907)` → 첫 세션 t, 두번째 f. 첫 세션 commit 후 두번째 t (auto-release). (2) Docker --no-cache 양쪽 rebuild + recreate → 같은 binary sha `0658a1c7...`. cargo test 5/5 통과 (자동 회귀 차단). (3) 첫 sync cycle 후 blue/green 중 한 쪽만 "owner sync ok" + 다른 쪽 "leader lock held, skipping" 관찰 예정. **CLAUDE.md 운영 함정 갱신**: blue/green 동일 binary 가 강제→권장 으로 격하 (leader election 이 본질 차단). 새 함정 = skip 로그가 한 쪽에서 항상 안 보이면 그 쪽이 leader 가 못 됨. |
| 2026-05-29 (PM7) | cortex | (D-cortex-3 PM7 — blue/green 동일 binary invariant + 회귀 테스트) | **D-cortex-3 enrichment wipe 재발 → blue/green Docker layer cache race 발견 + fix + 회귀 테스트 5개 추가** ([D-cortex-3 갱신](/ops/decisions)). PM4·PM6 의 overlay-preserving 코드가 이미 ship 됐는데 동일 증상 재발 — 김승우 (코오롱·한섬·스위티) 3명의 memo/cohort/former_org/former_title 이 또 system:google-sync 의 edit event 로 wipe. **진짜 root cause**: PM6 의 `docker compose build --no-cache` 가 `cortex-mcp-blue` 한 서비스에만 적용되고 `cortex-mcp-green` 은 stale 캐시 이미지 그대로 유지. blue/green 둘 다 run_loop 를 동시에 돌기 때문 (leader election 부재) sync 한 번 돌 때마다 race — 새 코드가 enrichment 보존해도 옛 코드가 같은 초에 destructive UPDATE 로 덮음. 운영자가 본 .236 preserve 와 .337 wipe 가 같은 초에 짝지어 일어난 흔적 = 두 컨테이너의 race 결과. **즉시 안전**: `UPDATE google_oauth_token SET status='paused'` → sync 정지. **fix**: 두 서비스 모두 명시적 `docker compose build --no-cache cortex-mcp-{blue,green}` + `up -d --force-recreate cortex-mcp-{blue,green}` → 안의 `/usr/local/bin/cortex` sha256 일치 검증 (50faa90d...). **복구**: `cortex restore-from-audit --owner soohun.kang@axellc.com --scan --apply` → 183 person enrichment 복원. sync 재개 (status='active') 후 강제 sync_google_now 3,385 → 3 victim 그대로 + missing_memo/cohort/former_org/former_title/HPE 전 owner 합쳐 0. **회귀 차단**: `src/google/sync.rs` 에 `#[cfg(test)] mod tests` 5개 unit test — (1) overlay 가 enrichment 보존 + (2) Google canonical 전부 null 일 때도 enrichment 보존 (edge case) + (3) wholesale replace 차단 + (4) 멱등 + (5) is_meaningful 가드. `cargo test --bin cortex google::sync::tests` 5/5 통과. **운영 invariant 명문화** (CLAUDE.md 운영 함정 섹션): sync.rs 같은 critical path 수정 시 blue·green 둘 다 명시적 `--no-cache` + `docker exec <blue/green> sha256sum /usr/local/bin/cortex` 일치 검증 필수. image-level hash 는 빌드 timestamp 비결정성으로 달라도 OK, binary 자체만 같으면 안전. |
| 2026-05-29 (PM6) | cortex | (Google contact displayName backfill 134/134) | **`cortex backfill-google-names` CLI 일회성 실행 — 134/134 success** ([D-cortex-google-names-backfill](/ops/decisions) + [D-cortex-3 갱신](/ops/decisions)). 옛 register_person 으로 push 된 Google contact 134건의 빈 displayName 정정 (unstructured_name fix 이전 createContact 호출분). per-person flow 는 People API updateContact 호출 + citation.ref 갱신 + dispatch event. rate 1 req/sec, idempotency gate (citation.ref 의 unstructured_name_backfill 마킹 v1). dry-run candidate=134 (Bucket A=2 김승우/정성화 + Bucket B=132). canary 5/5 → full 129/129 (총 134, 약 2.5분). 사후 candidate=0, dispatch event 134, 김승우/정성화 citation 마킹 v1. **선행** restore-from-audit 가 Cortex 측 display_name 을 채워둠. **함정 발견** — Docker layer cache 로 코드 fix 후에도 old binary 가 동작 (docker compose build 만 했을 때 캐시 재사용). docker compose build --no-cache 강제 빌드 + 새 binary 동작 직접 검증 (memo/former_org 보존) 후 134 backfill 실행. **D-cortex-3 본문 갱신**: 단방향 createContact 원칙 안에서 식별 키 정정 한정의 updateContact 도 허용 (enrichment 키는 절대 push 안 함). |
| 2026-05-29 (PM5) | cortex | (MCP tools 17 → 22 + register_deal 재설계) | **Cortex MCP write tools 확장 — 17 → 22 tools, register_deal 재설계 + 5 read tools** ([D-cortex-mcp-write-tools](/ops/decisions)). 운영자 follow-up — claude.ai 안에서 일상 운영 (deal stage 전환, org 조회, person ↔ deal 연결 등) 가능하게. **재설계**: `register_deal` = `title` → `name` 표기 통일 (16/19 기존 deal 이 이미 'name' 쓰는 backfill 패턴 + 3개 'title' archived 됨), stage 자유 string (권장 enum origination/screening/dd/ic/active/closed/killed description 만 — 실제 분포 active/closed/exploring/review 호환), **visibility default 'private'** (deals 민감), `contact_person_ids[]` → 각각 `deal_contact` relationship 자동 (idempotent, deal visibility 상속), `target_org_id` 있으면 `targets` relationship 자동, `source_attribute_id` (HPE → deal 추출 provenance). `register_organization` = case-insensitive idempotency (`lower(payload->>'name')` 매칭 — 'Aruda'/'ARUDA'/'aruda' 모두 동일 id) + `aliases` 명시 필드. `archive_artifact` = `reason` 필드 (payload.archived_reason) + `restore=true` alias (archive=false 와 동등). **신규 5 read tools**: `list_organizations` (name+aliases ILIKE search), `get_organization`, `list_deals` (stage/target_org_id 필터), `get_deal` (recent 20 events 포함), `list_relationships` (person_id 가 from 또는 to + edge_kind 필터). 모두 archived 자동 제외 (get_* 단건만 archived 도 노출). **검증** (7/7 smoke): tools/list=22 / ARUDA case-insensitive 3 variant 동일 id / register_deal default private / contact_person_ids+target_org_id → 자동 2 relationship (deal_contact + targets) / archive_artifact reason+restore alias / register_relationship 멱등 / list_* read OK / archived org list 에서 안 보이고 get 으로는 보임. blue/green Docker recreate. |
| 2026-05-29 (PM4b) | cortex | (D-cortex-3 enrichment 보존 fix + 데이터 복구) | **D-cortex-3 sync overwrite 버그 발견 + 즉시 패치 + 데이터 복구** ([D-cortex-3](/ops/decisions)). 운영자 ("방금 2명 신규 저장했는데 잘 적재된건가") 가 확인 요청 → audit log 점검 결과 김승우 (코오롱인더스트리 전무) + 정성화 (한섬비즈온 대표) 두 person 의 display_name + memo + cohort + former_org/title 이 **모두 sync 백그라운드에 의해 destroy** 됨. **Root cause**: `src/google/sync.rs::upsert_from_person` 의 `UPDATE artifact SET payload = $1` (Google payload 전체 덮기). register_person → Google createContact → 4분 후 sync 실행 → Google 의 빈 응답 (createContact 가 displayName 못 저장한 buggy 상태) 으로 Cortex enrichment 까지 통째로 날아감. **즉시 패치 3종**: (1) `sync.rs` 에 `GOOGLE_CANONICAL_KEYS` 화이트리스트 (display_name·given/family_name·org·title·department·emails·phones·memberships·biographies·userDefined) + `overlay_google_into_cortex(existing, google)` 가 meaningful (non-null + non-empty) 값만 selective overlay → enrichment 키는 자동 보존. (2) `google/people.rs::NameCreate` 에 `unstructured_name` 필드 추가 — People API 의 `Name.displayName` 은 server-computed 이므로 클라이언트가 보내도 무시, `unstructuredName` 으로 보내야 Google 측 displayName 정상 생성. (3) `mcp.rs::try_google_create_contact` + `web/views.rs::push_one` 의 NameCreate 인스턴스화에 unstructured_name=display_name 추가. **데이터 복구**: append-only audit log 보존 덕분에 두 person 의 propose (operator) + operator edit 의 enrichment 합성 → SQL UPDATE artifact + INSERT artifact_event op='restore' (actor='system:enrichment-recovery-D-cortex-3'). 정성화: display_name·org·title·memo·cohort 복원. 김승우: + former_org/title 복원. **검증**: 강제 sync_google_now (3,385 contacts) 후 두 person enrichment 그대로 + sync 가 만든 새 edit 의 payload_after 가 `memberships=["myContacts"]` 만 추가 (Google meaningful 값) — display_name·memo·cohort 보존 확인. blue+green Docker recreate. **D-cortex-3 본문 갱신** — Sync 보존 계약 명문화. **회피 가능했던 운영 함정** (참고): 이번 버그는 register_person → createContact name bug + sync 의 destructive overwrite 두 결함이 결합해서 만들어짐. createContact 만 고쳐도 destructive overwrite 는 잠재 위협으로 남았을 것. overlay 화이트리스트 도입이 더 본질적인 안전망. |
| 2026-05-29 (PM4) | docs | (ssh-access trap fix) | **ssh-access runbook 함정 fix — `install` 은 replace, append 는 `tee -a`** ([/onboard/ssh-access](/onboard/ssh-access)). 운영자 ai 가 taehun.kang SSH key 등록 (직원 onboarding) 중 발견 — Step 3 (a) `sudo /usr/bin/install -m 600 -o axe -g staff <tmp> /Users/axe/.ssh/authorized_keys` 주석은 "append" 인데 명령은 destination replace (cp 와 동일). 운영자가 무심코 따라하면 공용 `axe` 계정의 기존 직원 키 (이번 경우 ring-backup + soohun.kang) 전부 삭제 → 다른 직원 SSH 잠김. **fix**: (a) 를 `echo "<pubkey>" \| sudo /usr/bin/tee -a /Users/axe/.ssh/authorized_keys >/dev/null` 로 교체 (NOPASSWD whitelist `/usr/bin/tee /Users/*` 활용 확인). ⚠️ 코멘트 + (c) personal home 도 "첫 등록 시만 install OK, 두 번째부터 tee -a" 명시. 본 건 (taehun.kang) 은 Edit in-place append 로 진행 → 기존 2 키 보존. SACL `com.apple.access_ssh` 는 이미 등록되어 있어서 dseditgroup 불요. |
| 2026-05-29 (PM3) | cortex | (MCP write tools + archive) | **Cortex MCP write tool 표면 완성 — 16 tools** ([D-cortex-mcp-write-tools](/ops/decisions)). 운영자 "본질 퀄리티 결과 안전 혁신" 으로 진행 위임. 5축 평가 후 본질 gap (claude.ai 가 organization/deal/relationship 등록할 채널 없음) + lifecycle gap (DELETE 가 append-only audit trigger 로 차단) 동시 해결. **신규 4 tool** = `register_organization` ((owner, name) idempotent, visibility default shared) · `register_deal` (NOT idempotent — 같은 title 의 round 가능, target_org_id 가 있으면 owner-scope + kind='organization' 검증) · `register_relationship` ((owner, edge_kind, from, to) idempotent, from/to 양쪽 owner-scope 존재 검증, self-loop 차단) · `archive_artifact` (toggle archive=true|false → payload.archived 갱신 + op='archive'/'restore' event). **혁신** — 별도 archive_person/archive_deal 안 만들고 한 일반 도구 + restore. DELETE 차단 우회의 핵심: payload.archived flag 로 lifecycle 표현하면 audit 보존 + list/count/push 자동 제외. **List 쿼리 일괄 갱신** — web(fetch_kind_counts/recent_events/artifacts_by_kind/pending_push) + MCP(list_persons/search_person via push_person_filters) + backfill(distinct_orgs/person_rows) 모두 `NOT COALESCE((payload->>'archived')::boolean, false)` default 필터. ID 직접 접근 (get_person 등) 은 archived 도 반환. **검증** (11/11): register_organization 신규 + idempotent / register_relationship 신규 + idempotent / register_deal 신규 + 동일 title 새 id / target_org_id=person uuid → kind mismatch error / archive 4 artifact / 재 archive no_op / restore / 이전 세션 SMOKE_TEST_ORG_DELETE_ME_BACKFILL MCP archive 로 정리. UI: /cortex/orgs 가 archived 항목 안 보임, home dashboard 카운트 archived 제외 정합. blue/green Docker recreate 후 edge https://axe.axelabs.ai/cortex/home 200. **남은 우선순위** (다음 세션): backfill-introductions CLI (xlsx '소개' attribute → introducer relationship) · HPE attribute → deal 자동 추출 · 운영자 #1 full backfill-orgs (1,536 org YAML 편집, 수동) · edit-before-push / partial-failure (Google push 마무리 UX). |
| 2026-05-29 (eve3) | index | `c0dcd9a` | **Prj_Infinity(INEX) 축적 — 3-step surface→재수행→비교 (13.8% → −8.3% sign-flip)** ([D-index-23](/ops/decisions)). 사용자 "기존 적재 테스트 → 신규 IC 재수행 → 두개 비교". [D-index-19](/ops/decisions)/[21](/ops/decisions) 을 명시적 3-step 으로 정식화. **대상**: INEX 가상자산 거래소/VASP (보통주 0.5억 bridge, Closed). **Step1 surface**: v8 FINAL(irr_locked) 적재 → index 13.8%/MoM 1.70x 정확 재현. **Step2 재수행**: 외부 research — 실명계좌 base-rate near-zero(2021 특금법 후 원화마켓 신규 0건, P&lt;10%) / 코빗 ceiling 1,000-1,400억(Mirae MOU) / Gopax·Binance license-shell M&A 선례 / 보통주 distress recovery 0~20%. → 모달 exit 를 won-market rerating 아닌 SI shell M&A breakeven 으로 reframe + 보통주 wipeout leg(18% @ 0.12x) 추가. **Step3 비교**: calibrated −8.3%/MoM 0.82x. **~22pp gap + sign-flip**. **핵심**: 성숙·정직한 v8(hurdle 미달 공개·3 reviewer·irr_locked)도 핵심 base-rate(실명계좌)를 mgmt optimism 에 anchor + 보통주 wipeout 누락 → 결론 역전. proceeds 메커니즘은 v8 이 이미 정확(ev_bridge·net debt 0·exit-diluted) → 재계산 0, gap 순수 analytical. **canonical = IC-approved 13.8%** (executed/Closed deal → decision-time 기록 보존; −8.3% 는 retrospective overlay = `infinity_recalibrated.yaml`, [D-index-24](/ops/decisions)). 8-deal canonical 랭킹: Hancom 23.2 > **Infinity 13.8** > Novachips 7.8 > Sendy 6.5. validate-model 0 errors. IC memo v9 = OneDrive. |
| 2026-05-29 (PM2) | cortex | (axe-ui + backfill-orgs) | **Cortex 웹 UI 가 docs.axelabs.ai 와 같은 토큰을 입음 + /cortex/orgs 가 비어있던 문제 풀림** ([D-cortex-design-axe-ui](/ops/decisions) + [D-cortex-backfill-orgs](/ops/decisions)). **Design** — D-cortex-6.1 의 inline CSS (~200 line) 폐기 → `scripts/sync-axe-ui.sh` 가 axelabs SSOT (`/Users/axe/axelabs/src/lib/`) 에서 tokens 4종 + styles 6종 (reset/components base/form/data-display/dashboard/feedback) + Sarasa Fixed K woff2 (533 KB) 를 `static/axe-ui/bundle.css` (83 KB) 로 묶음. components.css 의 `@import` 중 cortex 가 안 쓰는 9 그룹은 strip. fonts.css 의 `/fonts/` 절대경로는 `/cortex/static/fonts/` 로 rewrite. `include_str!`/`include_bytes!` 로 binary stamp + Dockerfile 에 `COPY static ./static` 추가. 라우트 = `GET /cortex/static/axe-ui.css` + `/fonts/SarasaFixedK-Regular.woff2` (public, Cache-Control 1일/30일). HTML 은 `<html data-theme="light">` + `<link rel="stylesheet" href="/cortex/static/axe-ui.css">`. 클래스 매핑 = `.topbar`→`.axe-topnav`, `.brand`→`.axe-logo`, `.card`→`.axe-card`, `.btn`→`.axe-btn--{primary,secondary,ghost}`, `.metric`→`.axe-metric-card`, `<table>`→`.axe-data-table > __scroll > __table > __th/__td`, `.empty`→`.axe-empty-state`, callout box→`.axe-callout--{info,danger}`. cortex-only 개념 (visibility tag, payload pre, kv, flash, filter bar) 은 `.cortex-` prefix 로 분리 inline. **Backfill** — `cortex backfill-orgs` CLI 2단계: Phase 1 (`--owner <email>`) → pg_trgm 활성화 + distinct payload.org 추출 (1,536개) + similarity ≥ 0.6 클러스터 (1,446개) 제안 YAML stdout. 운영자가 파일 저장 → canonical_name/aliases/skip 편집. Phase 2 (`--mapping <yaml>`) dry-run, Phase 3 (`--apply`) 실제 INSERT. Idempotent — (owner, name) 으로 org 중복, (from, to, edge_kind) 로 relationship 중복 안 만듦. artifact `visibility='shared'`, `payload.backfill_source='backfill_orgs_v1'`. D-cortex-6.1 read-only 원칙 유지 — CLI 도구만, 웹 form X. **검증**: axe-ui.css 200 + 엣지 https://axe.axelabs.ai/cortex/static/axe-ui.css 200 · /cortex/home + /cortex/google/pending 모두 axe-* 클래스 + Sarasa 폰트로 렌더 · backfill Phase 1 YAML 1,536 distinct → 1,446 clusters 정상 출력 · 소규모 2-org mapping 으로 dry-run + apply (orgs created=2, rels created=2) + 재apply (existing=2, idempotent) 모두 통과 · /cortex/orgs 가 빈 axe-empty-state 에서 데이터 있는 axe-data-table 로 전환됨 확인 · /cortex/relationships 도 employed_by 2개 표시. **잔여**: 1,536개 org 의 full backfill 은 운영자가 YAML 편집 후 실행 (이번엔 smoke 만), 메모리에 도큐먼트. **남은 우선순위**: #2 backfill-introductions (xlsx '소개' 컬럼 → introducer relationship) · #3 register_organization/_deal/_relationship MCP tool · #4 HPE → deal 자동 추출. |
| 2026-05-29 (eve2) | index | `ca714b7` | **proceeds 산정 강화 — EV→EqV(net debt) bridge + exit-dilution 강제** ([D-index-22](/ops/decisions)). 사용자 audit "모두 EV = EqV + Net Debt + 투자 후 dilution 고려됐나 체크". **발견**: 7-deal proceeds 비일관 — net-debt bridge 는 Canopy 만 명시(EV 797−netdebt 300=EqV 498), Sendy(v2)·Iippo 는 stake×EV 직접(EqV 누락), pre-IPO 3+Sentry 는 equity multiple(N/A); dilution 은 pre-IPO 3+Sendy exit-date 희석 명시 vs Iippo·Sentry entry F/D flat. **결정** ([D-index-20](/ops/decisions) IRR determinism 을 proceeds 로 확장): `proceeds_basis` enum (ev_bridge|equity_value|mom|legacy_ev) + ev_bridge non-writedown leaf 는 `stake×(EV−net debt)` 가 axe_proceeds 와 ±2% 일치해야 — seed load **hard reject** + validate Check 7 Error 2중 강제. negative test 거부 확인 (10%×2,225억=222.5억 ≠ 날조 300억). migration 0005 (proceeds_basis + exit_ev/net_debt/stake 컬럼). **Sendy 정정 v3**: ev_bridge, net debt=0 (asset-light + 자금니즈 equity 충족 + 차입 증거 0 → 보수적, **없는 부채 날조 안 함**), stake 12.5%→10%. **proceeds·IRR 불변 6.47%** 이나 EV≠EqV 누락 class 영구 차단 — "정정=구조적, 숫자 불변" 이 정직한 결과. **7-deal**: Sendy ev_bridge PASS / Sentry equity_value / 3 pre-IPO mom / Iippo·Canopy legacy_ev WARN — 0 errors. 잔여: [B-index-proceeds-bridge-retrofit](/ops/backlog) (Iippo·Canopy per-leaf bridge) + Iippo·Sentry entry-F/D-flat dilution ([known-gaps](/ops/known-gaps)). |
| 2026-05-29 (eve) | index | `b77a236` | **센디(Sendy) IC v2 재작성 — 현 practice 재calibration (92% → 6.5%)** ([D-index-21](/ops/decisions)). 사용자 redirect "그냥 적재 말고 ic memo 를 현 practice 수준으로 새로 써라 (당시 방법론 열위)". [D-index-19](/ops/decisions) (surface→calibrated) 의 종착 = **memo 방법론 자체 재작성**. **3-tier IRR**: (a) v1 md 31%/22.8% (fabricated override), (b) v1 Excel 92.4% (math-correct, 낙관 input), (c) **v2 현 practice 6.5% ⭐ canonical**. **v1 5결함 교정**: IRR override(D-index-20 차단) / **wipeout leg 부재** (Downside 가 +31.6% gain → 손실 시나리오 자체 없음) → genuine 18% wipeout (부릉 1/6 recovery 0.15x) / **sendyX 66x 미검증** (beta 5곳 월375만→2026E 25억) → base-rate haircut(-93%) / **Exit 5x flat → segment-weighted** (freight 1.0~1.5x + TMS SaaS 4~5x, WiseTech-E2open 3.5x anchor) / instrument 분석 부재. **외부 anchor**: Convoy $3.8B→0 + 부릉 ₩5,500억→800억(1/6) → wipeout 15~25%, 한국 Series C→IPO 예외(TMAP 교훈). **결과**: 4-scenario bull(0.12,4.45x)/base(0.40,1.83x)/bear(0.30,0.72x)/wipeout(0.18,0.15x) → E[IRR] 6.5% / E[MoM] 1.51x / Sharpe-like -0.06. PASS 재확인 (v1 구조+타이밍 + fundamentals 30% hurdle -23.5pp 미달). **7-deal 랭킹**: Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > Novachips 7.8 > **Sendy 6.5 (최하위로 정정)** — 92% 매력 대부분이 2 낙관 input + 누락 risk leg 산물이었음. 산출물: OneDrive `ic/memo/v2_axe_current_practice_260529.md` (5-tenet·premortem·v1→v2 교정표) + seed v2 (version:2). validate-model 7/7 PASS. |
| 2026-05-29 (PM) | index | `9263179` | **센디(Sendy) 축적 — IRR override 오류 flagship + 첫 declined deal** ([D-index-20](/ops/decisions)). 사용자 "sendy 건도 비슷하게". 출처 = `1_Project/Pipeline/Sendy/`. **index 존재 이유의 결정적 증거**: `exit_matrix/v1.yaml` line 76 `irr_approx_pct: 95 # ... ≈ corrected: 35%` — 계산값 95.7% 를 근거없이 "35%" 로 손수 override (md 전반 Base 35/Downside -8/Expected 31/Devils 22.8 오류 chain; Downside -8% 는 수취 114억 > 투자 50억 → 구조적 불가). index 는 IRR 을 exit proceeds 에서 deterministic 계산 → override 물리적 불가. EV-derived seed → index 자동 교정: Base 95.7% / Downside 31.6% / Upside 146.6% / weighted 92.43% (Excel 실제값 일치). **부수 — deal.stage 'Passed' 추가** (migration 0004): GO/Closed 만이 아닌 PASS 결정 institutional memory 보존. 센디 PASS (2026-02-15) = 구조(10억서 CB 외 equity 제한)+타이밍, quality 아님. **7-deal portfolio**: Closed 3 / IC 3 / Passed 1 (full lifecycle). honesty: 92% 는 math-correct 이나 screening-grade model (sendyX 66x 미검증), PASS 는 IRR 무관 결정. validate-model 7/7 PASS. |
| 2026-05-29 (PM) | cortex | (batch push UI) | **Cortex Google push 큐 — batch + skip + visibility 격리** ([D-cortex-google-push-batch](/ops/decisions)). 운영자 "216 명 하나씩 클릭 비현실적" → batch UI 추가. **신규 모듈** `src/web/google_push.rs` (~400 LoC) — `JobRegistry` (`Arc<Mutex<{jobs, owner_running}>>`) in-memory, owner 동시 1 job 락, 1 req/sec 페이스 (Google quota 90/min/user 안전), MAX_BATCH_SIZE=500, 프로세스 재시작 시 손실 허용 (push idempotent — citation 중복 거절). **3 작업 일괄 ship**: (#3, **D-cortex-9 안전 fix**) `fetch_pending_push` SQL 에 `AND a.visibility='shared'` 추가 — private person 절대 push 후보 안 됨. count 216→215 검증. (#2, skip permanently) `kind='attribute', payload.key='do_not_sync_google'` 별도 artifact 마킹 (classify_person 패턴 일관, payload mutation 회피). `POST /cortex/a/:id/skip-google-push` 라우트 + 행별 `<button form="skipform-:id">` (HTML5 외부-form 참조로 nested form 금지 회피). 신규/idempotent 모두 OK, count 215→214 검증. (#1, batch push) `POST /cortex/google/push/start` (body: Bytes 직접 form-urlencoded 파싱 — axum default Form 이 same-key Vec 안 됨) · `GET /cortex/google/push/status/:job_id` HTML (progress bar + 결과 table + `setInterval(1500ms)` JSON 폴링, 완료 시 stop) · `GET /cortex/google/push/json/:job_id` JSON snapshot (owner mismatch 403). 워커 = `push_one_public` 재사용 → `registry.record` per item → 1s sleep → `registry.finish` (락 해제). **UI 재구성**: pending 페이지 = `<form id="batchpush">` 안에 행별 체크박스 + "전체 선택 토글" / "연락처 있는 행만 선택" (placeholder 자동 제외 hint) / "선택 해제" 보조 버튼 + sticky 액션바 "Push selected (N)". **검증** (fake UUIDs 2 개, Google API 호출 0 회 — NotFound 가 token refresh 이전 단락): empty form 303+err flash · 2 ids → 303 status page · immediate JSON state=running 1/2 · 2nd start during running → same job_id `?already_running=1` · 완료 후 락 해제 → new job_id OK · HTML status 200 (9118B) · edge https://axe.axelabs.ai/cortex/google/pending 200 + blue/green 재기동. **남은 작업** (다음 세션): #4 edit-before-push 인라인 수정, #5 partial-failure 분류 column. |
| 2026-05-29 | cortex | (web UI) | **🚀 cortex 웹 UI LIVE — `https://axe.axelabs.ai/cortex` SSO** ([D-cortex-6.1](/ops/decisions)). 운영자 "axe.axelabs.ai/cortex 웹에서 볼 수 있게" 요청 → cortex binary 안에 read-only 운영자 포털 추가 (axum + maud + 인라인 CSS, 별도 SPA/Next.js 없음). **구성** — `src/web/{session,auth,views,mod}.rs` 신규: (a) **세션** = HS256 JWT cookie `cortex_session` (`tok="web"` discriminator, 8h sliding refresh, HttpOnly+Secure+SameSite=Lax, Path=/cortex), CORTEX_JWT_SECRET 재사용; (b) **로그인** = `/cortex/login/start` → Microsoft Entra ID federation (state cookie CSRF gate, server-to-server token exchange, JWKS id_token verify — oauth_as.rs federation 코드 미러); (c) **페이지** — `/cortex/home` 대시보드 (kind 별 count metric + Google 연결 상태 카드 + 최근 8 audit event) · `/cortex/{people,orgs,deals,interactions,relationships}` 리스트 (visibility 필터 all/shared/private + page 50 페이지네이션 + primary/secondary label kind 별) · `/cortex/a/:id` detail (payload pretty + citations + 최근 20 events) · `/cortex/google/reconnect` (기존 `build_authorize_url` wrapper); (d) **격리** — MCP `auth::middleware` (Bearer) 와 web `require_session` (Cookie) 은 별도 axum layer (cross-token-type leak 차단). **Entra app 갱신** — web.redirectUris 에 `https://axe.axelabs.ai/cortex/login/callback` 추가 (기존 3 URI 유지). **검증**: `/cortex` 303→login · `/cortex/login` 200 (5247B) · `/cortex/login/start` 302→Microsoft + state cookie · 보호 라우터 7개 모두 미인증 시 303→login · 유효 세션 쿠키로 home/people/orgs/deals/interactions/relationships/detail 모두 200 + sliding refresh cookie 부착 · 위조 JWT (`tok="mcp"`) 거절 · wrong-secret JWT 거절 · `POST /cortex/logout` 302+clear cookie · MCP `/cortex/mcp` Bearer 흐름 + RFC 9728/8414 metadata 회귀 정상. Write 는 여전히 MCP. D-cortex-6 의 "UI 는 Blueprint" 부분만 번복 (D-cortex-7 single-binary ergonomics + 같은 DB pool + Microsoft federation 코드 재사용 + cross-service 호출 회피 이유). |
| 2026-05-29 | index | `e130a69` | **3 pre-IPO deal 축적 (스타넥스/한컴인스페이스/노바칩스) — calibrated 검토 본** ([D-index-19](/ops/decisions)). 사용자 "찾아서 축적하되 그대로가 아닌 검토 + 시사점". 출처 = OneDrive `_comparative_20260528_preIPO/` (13-agent 비교 IC 메모 + 5축 평가 + quant IRR). **핵심 — surface IRR ≠ calibrated IRR (최대 36pp gap)**: 스타넥스 19.6%→36.4%, 한컴 58.5%→22.4% (KOSDAQ 재청구 base rate down-cal), 노바칩스 -1.5%→7.45%. xlsx surface cell 그대로 축적했으면 한컴 1위 오기록 → index = reviewed truth 저장 실증. 3 seed = pre-IPO scenario-tree (각 scenario Bull/Base/Bear/Wipeout = 단일 exit outcome, P+MoM+holding). code: `parse_timing_years` 소수 연도 (2.5y/4.5y) + seed.rs validate 위임 + migration 20260528000003 (timing CHECK rigid enum → regex). **검증**: validate-model 3 신규 0 error, query_irr calibrated ±1pp (36.36/23.16/7.80), 6-deal portfolio 랭킹 Sentry 40.3 > Iippo 36.5 > Starnex 36.4 > Canopy 26.4 > Hancom 23.2 > Novachips 7.8 (pre-IPO 내부 랭킹 AXE 메모 일치). **5 시사점**: surface↔calibrated gap / instrument 8-15pp IRR-material (schema gap) / probability base-rate provenance / 동일 schema 가 Pre-A multi-leaf + pre-IPO single-leaf 수용 / **변곡점 IC 완성도 ≠ deal quality** (노바칩스 가장 정교=최약체). |
| 2026-05-28 (PM20) | index | (az + axe mcp) | **index_mcp catalog 등록 — claude.ai connector 4-field one-stop**. 사용자 발견: `axe mcp list` 에 index 누락. 원인: `customers.yaml axe.services.sso.apps` 에 `index_mcp` block 없음 (services.index secrets manifest 만 있고 sso.apps 의 OAuth app 정의 누락). 처리: (1) `sso.apps.index_mcp` block 추가 (client_id 47fe856f… + application_id_uri + redirect_uris claude.ai/claude.com + scopes [openid/profile/email/`mcp.access`] + client_secret_env), cortex_mcp 와 동형. (2) **Entra app gap 2개 정정** — `mcp.access` exposed API scope 가 없어서 (`api: []`) claude.ai 가 resource-scoped token 못 받을 상태였음 → Graph API PATCH `oauth2PermissionScopes` 추가 + `requestedAccessTokenVersion=2` (v2 token aud=client_id, frame/hive/cortex 정합). (3) `axe mcp publish` → vault `MCP Connectors` collection 에 **"Index MCP (axe)"** item created (URL + client_id + secret len=40 + scopes 4-field). 이제 `axe mcp list` 5 app (frame/hive/blueprint/cortex/**index**). 운영자가 claude.ai connector 등록 시 vault 한 곳에서 4 field 복사. **테스트 ready 검증**: cortex (live) 와 Entra app 구조 1:1 동일 (identifierUri + mcp.access scope + v2 token + redirect URIs). |
| 2026-05-28 (PM19) | index | (CF API + launchd) | **🚀 index production LIVE — `https://axe.axelabs.ai/index/mcp`**. 사용자 "끝까지 마무리" — 운영자 manual 영역까지 자동화. (1) **Cloudflare route 자동화** — 그간 "Soohun Global Admin 전용" 으로 분류했던 `/index` tunnel ingress 를 **zone-scoped CF API token** (`Cloudflare API - axelabs` vault item, ai@axellc.com 접근 가능) 으로 self-service 갱신. account id 는 zone 의 `account.id` 에서 derive (token 은 account-list 권한 없지만 zone-read 로 우회). `cfd_tunnel/{id}/configurations` GET (v19) → ingress[4] `/index` 의 `http_status:503` → `http://host.docker.internal:4012` 수정 → PUT (v20). **검증**: `/index/healthz` → 200 `{"service":"index","status":"ok"}`, `/index/.well-known/oauth-protected-resource` → RFC 9728 envelope (real tenant 122fb574…), `/index/mcp` (no auth) → 401. **함정 정정**: cloudflared dashboard-managed config 는 local `config.yml` edit 무효 (PM5 에서 발견) 였으나 — **CF API PUT 으로 dashboard config 직접 갱신 가능** = 운영자 dashboard 클릭 불필요. cortex/matrix/frame 도 동일 패턴 적용 가능 (known-gaps "Cloudflare tunnel Dashboard remote-managed" 가치 갱신). (2) **launchd 등록** — `ai.axe.index-skill-sync.plist` install + load (PID 8377 exit 0), 10분 주기 skill sync 작동 시작 (3 skill / 61 file). **잔여 prereq 1개** (UX only, hard-block 아님): Azure admin consent — Soohun 이 claude.ai 첫 OAuth 시 개인 동의로도 가능 (org-wide 사전 동의는 per-user prompt 회피용). **D-index-10 8/8 + Phase 1 전부 + production endpoint LIVE**. |
| 2026-05-28 (PM18) | index + blueprint | `6aa2680` + `8997e28` + `579a0fa1` + `2a74ef0` | **사용자 "모두 진행" — 4 backlog 일괄 완료**. (1) **B-index-xlsx-roundtrip** ✅ `import_xlsx` 16번째 MCP tool — calamine 0.26 read, Assumptions sheet parse, input drivers 만 비교 (derived는 formula 재계산), effective_db_value (period 0 fallback) semantic, diff (added/changed/removed/unchanged), apply=true → DB UPSERT. **검증**: 무수정 round-trip 49 unchanged, 1 cell 수정 → 정확히 1 changed 감지. (2) **B-index-3fs-bs-cf-completion** ✅ Phase 0 working capital model — BS 12 line (ar=rev×dso/365, inv=cogs×inv_days/365, ap=cogs×dpo/365, ppe_net=cum_capex, debt = max(0, init−cum_repayment), equity = init + Σni, cash = plug) + CF 7 line (indirect method: ni+dep−Δwc−capex−debt_rp). LpWorkbookInput 에 bs_lines + cf_lines 필드 추가, xlsx 4→6 sheets, HTML 7→9 sections. **검증** Iippo Y1: total_assets = L + E = 14.4M + 209.5M = 223.9M ✅ balanced. 4 (deal×scenario) compute_3fs persist 성공 (217 rows × 2 + 155 rows × 2). (3) **B-pmc-skill-skeleton** ✅ Background Agent 가 D-index-12 의 pmc (Post-Money Care) skill scaffold (30 files, 1,906 LoC) — SKILL.md 213 line + 8 agents (~93 line each) + 5 references (kpi-catalog/ir-lifecycle/postmortem-cadence symlink/risk-kind-frozen/trigger-tiers) + 4 Python stub + 11 sub-dir .gitkeep. (4) **B-blueprint-agent-sdk-integration** ✅ Blueprint hook — `scripts/sync-index-skills.sh` (index-skill-sync.py wrapper) + `launchd/ai.axe.index-skill-sync.plist` (10분 주기). 검증: 1차 sync 3 skill / 61 file added (ic+ingest+신규 pmc 자동 발견), 2차 sync 61 unchanged. **누적 16 MCP tools + 16 schemas + pmc skill 추가 + Blueprint sync hook 작동**. 회귀: validate-model 27/27 + IRR 3 deal ±1pp 유지. |
| 2026-05-28 (PM17) | index | `8b6f05d` | **MCP client — `bin/index-skill-sync.py` (B-blueprint-skill-mcp-client Phase 2)**. [D-index-17](/ops/decisions) Phase 2 — Blueprint Claude Agent SDK 의 filesystem `.claude/skills/` 직접 의존 제거 reference impl. Python stdlib only (no deps) ~297 line. **Dual transport**: HTTP (production Entra ID bearer) + CLI fallback (local-dev `target/debug/index mcp-call`). 동작: index MCP 의 `list_skills()` + `get_skill_resource()` 호출 → `/var/cache/blueprint-skills/{skill_name}/...` 로 sync. **sha256 cache invalidation** — server sha256 vs local file sha256 비교. **Conditional recursive traversal** — `has_{references,scripts,tests,agents}` 플래그 기반 fetch (scripts/_oneoff/ nested 도 처리). `--diff` mode (dry-run) + `--skill` 단일 필터 + `.manifest.json` (audit trail). **검증**: 1차 sync 43 files added (ic 39 + ingest 4) + 모든 sha256 verified + 2차 sync 43 unchanged (cache hit) + drift simulation (`echo >> SKILL.md`) → 'updated' 감지 + restore 1 updated. **운영 흐름** (Blueprint 측 도입 후): Agent SDK startup → `subprocess.run(["index-skill-sync"])` → cache dir 을 `.claude/skills/` mount point 로 인식 → 10분 cron 으로 server 변경 자동 fetch. 추가: 3 deal HTML render 일괄 생성 (Iippo base/mgmt/upside/downside + Sentry base + Canopy base, 6 file 모두 macOS open 으로 브라우저 즉시 view 검증). 다음 = Blueprint Agent SDK 측 loader 통합 + cron 등재 → [D-index-17](/ops/decisions) sunset 기준 (b) 충족. |
| 2026-05-28 (PM16) | index | `eb66fab` | **Native HTML LP dashboard (`export_lp_html`, 15번째 MCP tool)** — 사용자 결정 PDF 말고 native HTML 로 LP 에 deliver. md-to-pdf intermediate 없이 Rust 에서 직접 inline-CSS self-contained HTML 생성. 신규 `src/html.rs` (~360 line) — `build_lp_html()` 가 7 section HTML5: 🔒 Reproducibility (inputs_hash + xlsx sha256) / 📊 IRR Summary (primary metric card) / 💼 Fund Investments (status + baseline tag) / 📈 Income Statement (12 line × N period + derivation rules block) / 🎯 Exit Matrix (joint_probability column) / ⚙️ Assumptions (driver_value matrix) / 🔍 Audit Trail. 설계: self-contained (외부 fetch 0), Korean-friendly font stack (Apple SD Gothic Neo / Pretendard / Noto Sans KR), `@media print` 으로 LP 가 브라우저에서 PDF 출력, semantic HTML5 (a11y), color-coded (양수 green / 음수 red / NULL gray), sticky table headers. **bundle v2** = `index.html` + `xlsx` + `README.md` (cover.md 폐기, index.html 가 zip 첫 entry → LP 가 가장 먼저 봄). 검증: Iippo base HTML 20,250 bytes, 2회 export sha 동일 (`70096195...` byte-deterministic), 3 deal × 2 scenario 전부 성공, validate-model 27/27 + IRR 3 deal ±1pp 유지. **LP 흐름 update**: bundle.zip 첨부 → LP 가 풀어서 index.html 더블클릭 → 브라우저 dashboard + xlsx 로 cell audit. 다음 Phase 1 = xlsx round-trip + BS/CF + 선택적 interactive chart.js. |
| 2026-05-28 (PM15) | index | `d33e8de` | **`export_lp_bundle` MCP tool (14번째) — LP 가 1 첨부로 받는 zip + byte-deterministic**. Gap 3 마무리 layer. `export_lp_bundle(deal_code, scenario, out_dir?)` → `{deal}-{scenario}-{sha[:8]}-bundle.zip` (xlsx + cover.md + README.md). `src/xlsx.rs` 확장 (~150 line): `build_cover_markdown` (IRR table + Fund table + reproducibility lock + Phase 0 한계 박제), `build_readme_markdown` (LP 안내문: Excel 사용법 + 변경 요청 경로), `build_bundle_zip` (zip 1980-01-01 epoch deterministic). **Determinism fix 3종** (D-index-4 lock 강화): (a) xlsx `DocProperties.set_creation_datetime(epoch)` + set_author "AXE Labs index", (b) cover.md `Generated: <timestamp>` 제거 → inputs_hash[:16] 로 대체, (c) zip `last_modified_time(epoch)`. **검증**: 2회 export (2초 간격) → xlsx sha 동일 (`ac80f052...`) + bundle sha 동일 (`c940ce5b...`). Iippo base bundle 13,302 bytes (xlsx 11,892 + cover 1,997 + README 1,040). 3 deal × 2 scenario 전부 성공. validate-model 27/27 + IRR ±1pp 유지. 운영 흐름: 전 `export_lp_model` xlsx 첨부 (LP 별도 안내 필요) → 후 `export_lp_bundle` zip 1개 (cover + README + xlsx). Phase 1 = xlsx round-trip + BS/CF + PDF render. |
| 2026-05-28 (PM14) | cortex | `4c7dda0` | **visibility 결정 UX — 민감하면 LLM 이 먼저 묻기 + log_interaction visibility** ([D-cortex-9](/ops/decisions)). 사용자 요청 "private/shared 가 민감할 수 있으면 질문하도록". write tool 4종(register/classify/update_person + log_interaction) description 에 **SENSITIVITY RULE** 추가 — `visibility` 미지정 + 민감 가능 내용(딜 코멘트·협상 의견·사적 메모·비공개 미팅)이면 커넥터 LLM 이 저장 전 'private/shared?' 확인, 일반 공개 정보는 묻지 않고 shared. (MCP 는 요청-응답이라 직접 못 물음 → LLM-guidance 패턴. 기본값 shared 유지.) `log_interaction` 에 visibility + skip_audit_payload 신규 — "비공개 미팅" 답변을 실제 반영, participant relationship artifact 도 interaction 의 visibility 상속. **공유 인물 + 비공개 메모** 패턴 문서화 (person shared + 별도 classify_person private attribute). 검증: build 9.0s, tools/list 12 tool 0 bad key (description 한글=값이라 무관), log_interaction props 노출, interaction+relationship private 쓰기 rolled-back SQL 확인. **앞선 GitHub 연동 tools.15 사건**: cortex/frame/hive 라이브 + Claude-in-Chrome 22 tool 스키마 직접 검증해 전부 clean 확인 → 범인은 claude.ai 의 GitHub 연동(Anthropic 통합) — 커넥터 1개의 non-conforming key 가 전체 tools/list 400 (claude.ai 한계, [known-gaps] 가치). |
| 2026-05-28 (PM13) | index | `425a758` | **Gap 3 — LP-deliverable xlsx export (`export_lp_model` MCP tool, 13번째)**. D-index-18 chain 의 종결 — 사용자 stated 목적 "LP 요청 시 model 주는 것" 의 직접적 구현. `rust_xlsxwriter 0.95` Rust 네이티브 crate 사용 (calamine read counterpart는 Phase 1 round-trip backlog). 신규 `src/xlsx.rs` (~280 line): LpWorkbookInput → 4-sheet 결정론적 xlsx — (1) **Assumptions** driver_value 매트릭스 + cover (deal/scenario/horizon/inputs_hash), (2) **Income Statement** 12 line × 7 period + footer 의 derivation rule 문서화 (audit trail), (3) **Exit Matrix** leaf-level (joint_probability = Excel formula `=E*B`), (4) **IRR Summary** per-fund + weighted metrics + reproducibility footer. **export_lp_model(deal_code, scenario, out_dir?)** → `/tmp/index-lp/{deal}-{scenario}-{sha[:8]}.xlsx` 생성 + sha256 + size_bytes + inputs_hash + sheet_summary 반환. 검증: Iippo base 11,894 bytes, `file` 명령으로 "Microsoft Excel 2007+" 인식, unzip 으로 4 sheet 확인, **byte-equivalent reproducibility** (같은 DB → 같은 sha256), 3 deal × 4 scenario 전부 export 성공. **운영 흐름** (LP 전달): `export_lp_model Iippo base` → /tmp/index-lp/*.xlsx → 운영자가 LP 에 첨부 → LP가 Excel 에서 cell formula audit 가능 → cover sheet 의 inputs_hash 가 1년 후 재현 lock. validate-model 27/27 회귀 유지. Phase 1 잔여 = xlsx round-trip (calamine read → DB diff verify) + BS/CF sheet 완성 + PDF cover bundle. |
| 2026-05-28 (PM12) | index | `9ac0c68` | **Gap 2 — 3FS typed schema + `compute_3fs` MCP tool (12번째)**. LP-deliverable chain 의 다음 layer — driver_value 위 typed Income Statement / Balance Sheet / Cash Flow line items. migration 20260528000002 `financial_statement_line` 신설 (model_id × scenario_id × statement × line_code × period_index UNIQUE). frozen enum: **statement 3종** (income_statement / balance_sheet / cash_flow) + **is_line_code 12종** (revenue / cogs / gross_profit / `opex_{sm,rnd,ga,total}` / ebit / interest_expense / pretax_income / tax_expense / net_income). BS 12 line + CF 7 line 은 Phase 1 backlog (working capital + debt schedule 추가 driver 필요) — placeholder return. `compute_3fs(deal_code, scenario, persist=false)` MCP tool: driver_value lookup (period-0 fallback + base inheritance) → IS line 재구성 (cogs = revenue×(1-gross_margin), opex_total, ebit fallback, tax_expense = max(0, pretax × tax_rate), net_income). **검증** Iippo base: 12 line × 7 period = **84 cells persisted**. Y1 revenue=7.80억 → ni=1.10억, Y5 revenue=75.15억 → ni=10.55억, Y7 revenue=122.12억 → ni=17.15억 (net_income = pretax × 0.78 정확). /index/schemas 15 → 16 (`index.financial_statement_line@1.0` active). 회귀: validate-model 27/27 + IRR 3 deal ±1pp 유지. 다음 = [B-index-lp-deliverable-export](/ops/backlog) (Gap 3) — `rust_xlsxwriter` 로 financial_statement_line → Excel sheet 구조 deterministic export. |
| 2026-05-28 (PM11) | cortex | `2ff4cf4` | **xlsx import private-tagging — `--private-cols`** ([D-cortex-9](/ops/decisions) Phase 0 후속, [B-cortex-xlsx-import-run](/ops/backlog)). `Network_CRM.xlsx` enrichment migration 의 민감 컬럼을 `visibility=private` attribute 로 적재. `cortex import-xlsx --private-cols HPE,메모,소개` (default `HPE` = 민감 딜 코멘트). import.rs: 키별 visibility 결정(`private_cols.contains`→private\|shared) + insert_attribute visibility 컬럼 + 알 수 없는 private-col 경고(ENRICHMENT_KEYS 검증) + dry-run summary 에 private 카운트·컬럼·조정 안내. **혁신 축**: 컬럼 private 여부 hardcode 대신 configurable 플래그 + dry-run 가시화. 검증: build 9.1s + CLI `--help` 플래그 노출. **잔여**: 실 dry-run/apply 은 xlsx 파일 macmini 복사 + Google sync 선행 (운영자). |
| 2026-05-28 (PM10) | index | `9df7f71` | **`compute_full_model` MCP tool — DSL evaluator DB 통합 (Gap 1 closure)** + [D-index-18](/ops/decisions) 결정 박음 (single-driver + period-indexed). 사용자 질문 "Excel model → DB화 + 수식 + 계산 + 검증 best practice" 의 첫 gap closure: DSL evaluator 는 이미 구현돼 있었으나 DB 와 연결 안 됨 → 본 commit 이 마지막 1마일. 신규 11번째 MCP tool: `compute_full_model(deal_code, scenario, persist?)` — DB load → scenario inheritance (base 폴백) → base_revenue_period0 → revenue[-1] sentinel → `dsl::evaluator::evaluate(horizon)` → derived 결과 매트릭스 + inputs_hash + (persist 시 financial_driver_value UPSERT). evaluator 개선 2건: (1) topo_order self-edge skip (revenue[y-1] lag, A7 와 동일 정책), (2) lookup_value input period 0 fallback (Excel "constant input row"). **검증**: Iippo base 8 period × 2 derived = 16 cells persist → validate-model scenario_coverage **46% → 77%**, IRR ±1pp 회귀 유지. Iippo mgmt 시나리오 inheritance: base 13 + mgmt 11 override = 14 effective inputs, hash 분리. **발견된 modeling 안티패턴 → D-index-18 결정**: Y-suffix multi-driver (`revenue_growth_y1..y7`) + 단일 formula 결합 시 period 7 에서 revenue 1.2 quadrillion 원 비현실 compounding. Fix path = 단일 driver `revenue_growth` + period 0..6 별 값 (Excel "input row" 동형). Iippo seed refactor 잔여 = [B-index-driver-period-indexed-refactor](/ops/backlog). |
| 2026-05-28 (PM9) | cortex | `f8cad8c` | **artifact visibility tier — private partition Phase 0** ([D-cortex-9](/ops/decisions) · [B-cortex-private-partition-phase0](/ops/backlog) ✅). soohun.kang "Private Partition" 요청. **핵심 재구성**: 현재 모든 artifact 는 이미 RLS 로 owner-only (타인·관리자 볼 경로 없음) → `visibility` 는 owner RLS 섬 밖(**Blueprint M6 mirror**, [D-bp-artifact-1](/ops/decisions))으로 무엇이 나가는가를 막는 propagation gate. M6 이 아직 📐 설계(Q4)라 mirror 생기기 전 지금 박음. migration 0003 `artifact.visibility` (shared\|private, DEFAULT shared, 기존 3,250행 shared) + register_person `visibility`(**private→Google push skip**)·classify_person·update_person(re-tag)에 `visibility`+`skip_audit_payload` + list_persons `visibility`/`exclude_classification_key`/`_value` 필터(QueryBuilder, share-safe export §6) + get_person 노출. 기본값 정책 = base=shared / 민감분류·HPE import=private (backfill 불필요 — 민감 데이터 미유입). 신규 schema key 전부 ASCII (함정 #6). 검증: host build 8.8s + migration(3250 shared/0 private) + blue+green healthy + 필터 5-assertion **rolled-back** SQL(zero residue) + 외부 200/401. **잔여(auth)**: claude.ai tools/list 12 + register_person(private) 실 round-trip 스모크. Phase 1(Google 라벨 sync 필터)·2(M6 mirror 계약+field-level)·3(E2E) backlog 등재. |
| 2026-05-28 (PM8) | cortex | `b8d3aa0` | **blue/green healthcheck 수정 — Rust 이미지 self-probe** ([B-cortex-dockerfile-healthcheck](/ops/backlog) ✅). production-live 후 두 MCP 컨테이너가 영구 `unhealthy` 로 떠 있던 것 (트래픽 무해 — Caddy alias routing 이 health-gate 안 함, 그러나 blue/green swap 의 healthy gate 잠복 위험) 해소. 원인 = healthcheck `python -c urllib...` 인데 Rust/Debian-slim 이미지엔 python·curl·wget 없음 (`/usr/local/bin/cortex` 바이너리만). fix = `cortex healthcheck` 서브커맨드 (GET `127.0.0.1:$CORTEX_MCP_PORT/healthz`, 2xx→exit 0, `Settings::load` 전 short-circuit 으로 DB 자격증명 독립) + compose test `["CMD","/usr/local/bin/cortex","healthcheck"]` (green 은 `<<: *cortex-mcp-blue` anchor 머지 상속). **index(cortex 1:1 미러)의 python→curl 과 다른 선택** = 패키지 추가 없이 바이너리 재사용 (minimal-base 정합, index 정렬 권장). 검증: host build 8.6s + 서브커맨드 positive(3210)=0/negative(39999)=1 + rebuild 후 blue+green `(healthy)` + 외부 `/cortex/{healthz,mcp}` 200/401 유지. |
| 2026-05-28 (PM7) | index | `bf09547` | **Phase 2 entry — skill MCP discovery (`list_skills` + `get_skill_resource`)** ([D-index-17](/ops/decisions) Phase 2 path 진입). MCP 총 10 tools (8 → 10). (9) `list_skills()` 가 `/Users/axe/index/skills/` 의 모든 skill (현재 ic + ingest) 의 SKILL.md frontmatter (`name` / `description` / `allowed-tools` / `required_model` 등) + sha256 + sub-dir 존재 여부 (`references` / `scripts` / `tests` / `agents`) 반환. (10) `get_skill_resource(skill, path?)` 가 path 미지정 시 SKILL.md, 지정 시 skill dir 기준 relative resource fetch — file = `content` + sha256 + size, directory = `entries[]` listing. **Security**: (a) `..` path traversal 차단 (`PATH_TRAVERSAL` error), (b) skill 이름 영문/숫자/_/- 만 허용, (c) canonicalize 후 skill_dir starts_with 재검증 (symlink escape 차단), (d) invalid → `NOT_FOUND` + context. /index/schemas 도 15번째 schema (`index.skill_resource@1.0`) 추가 → total 15 (9 active + 6 stub). 다음 consumer = [B-blueprint-skill-mcp-client](/ops/backlog) (Blueprint Agent SDK 가 본 두 tool 로 skill discovery, filesystem mount 의존 제거) → [D-index-17](/ops/decisions) sunset 기준 (b) 충족 path. |
| 2026-05-28 (PM6) | index | `2dfc484` | **MCP surface 4→8 tools + /index/schemas 14 envelope 활성화** — Phase 0 다음 layer 진입. 신규 4 tool: (5) `list_deals(stage?, sector?)` portfolio overview, (6) `get_deal(deal_code)` full snapshot (target_company + funds[] + financial_model + scenarios[]), (7) `cross_deal_benchmark(driver, scenario)` A5 MCP 노출, (8) `get_exit_matrix(deal_code, scenario?)` leaf-level detail (joint_probability + dead_leaf + concentration). `/index/schemas` 가 빈 list → 14 schema 본문 ([D-index-7](/ops/decisions)): 8 active (target_company / deal / fund_investment / financial_model / financial_driver / financial_scenario / exit_matrix_leaf / financial_output) + 6 stub (dd_finding / ic_decision / portfolio_kpi / risk_alert / valuation / lp_comm — Phase 1 backlog 표시). `metadata.frozen_enums` ([D-index-15](/ops/decisions) immutable freeze): instrument 5 / status 6 / path 6 / risk_kind 5. dsl_operators 12개 freeze + 9 D-index-N decision_references. 신규 CLI `index dump-schemas` (auth bypass envelope JSON). 회귀 검증: validate-model 27/27 + 3 deal IRR ±1pp IC baseline 유지. 다음 consumer = ic skill `--push-to-index` ([D-index-13](/ops/decisions) atomic batch) + Blueprint citation resolver (`index.financial_output` kind). |
| 2026-05-28 (PM5) | index | (az CLI) | **`axe ship index` Azure prereq 5/7 자동화 완료 — Entra app + SP + permissions + vault 5 secret + .env.local merge**. `ai@axellc.com` 권한으로 az CLI 경유: (1) `az ad app create "Index MCP"` → `appId=47fe856f-75e8-457b-a10e-fce1559939f5`, (2) `az ad app credential reset --years 2` → secret 발급 (escape_dollar N/A — `$` 미포함, 다행), (3) `az ad sp create` (delegated grant prereq), (4) `az ad app permission add` (Microsoft Graph User.Read scope), (5) `axe secret push index` ×5 (db-password / jwt-secret / oauth-client-secret / pii-passphrase-axec / 기 등재 anthropic-api-key shared) → `axe secret check index` ✓ 5/5, (5.5) `axe secret pull index` → `/Users/axe/index/.env.local` atomic merge 완료. 로컬 docker compose restart 후 `/index/.well-known/oauth-protected-resource` 가 real tenant id 반영 (`https://login.microsoftonline.com/122fb574-7efa-476a-95b6-bee81bce2cce/v2.0`). **Manual 잔존 2건** (Soohun Global Admin 전용 — `ai@axellc.com` 권한 부족 확인 완료): (a) tenant admin consent — `az ad app permission admin-consent` 시도 → `401 Forbidden Authorization_RequestDenied`, (b) cloudflared route — **cortex 와 동일 함정 재확인** (named tunnel 의 dashboard-managed remote config 가 local file 을 override). local `config.yml` 의 `/index` 항목을 4012 로 갱신해도 cloudflared 가 dashboard 의 `http_status:503` 을 load. Cloudflare Zero Trust dashboard 의 tunnel `axelabs` Public Hostnames 에서 /index path service 를 dashboard 갱신 필요 (matrix/cortex/frame/hive/blueprint 와 동일). 검증 후 `curl https://axe.axelabs.ai/index/healthz` → `{"service":"index","status":"ok"}` 예상. |
| 2026-05-28 (PM4) | cortex | `dfa9330` | **Cortex production live — claude.ai connector + 12 MCP tools 확인** (첫 비-Python = Rust + axum + sqlx MCP 서비스, artifact-first Day 1). `https://axe.axelabs.ai/cortex/mcp` 가 Entra ID Bearer 로 12 tool (whoami / list·search·get·register_person / classify·update_person / log·list_interactions / connect·disconnect·sync_google_now) 노출. **5 테이블** (artifact / citation / artifact_event append-only / mcp_schema / google_oauth_token) + RLS FORCE + `cortex_app` NOSUPERUSER role 로 per-user 격리 ([D-cortex-2](/ops/decisions)). Google OAuth Web flow (per-user refresh_token pgp_sym_encrypt) + People API pull/opportunistic-push ([D-cortex-3·4](/ops/decisions)). claude.ai 연동까지 **7 함정** 돌파 ([known-gaps](/ops/known-gaps) Cortex 섹션): DB pass base64 URL 파싱 / env_file 따옴표 literal / RFC 9728 resource-level path / RFC 8414 path-insertion (authorization_servers→Microsoft 직접, [D-cortex-8](/ops/decisions) AS proxy dormant) / connector client_secret 입력 / **MCP tool property key ASCII-only** (`메모`→`memo`, 한글 key 1개가 tools/list 전체 400) / Cloudflare tunnel Dashboard remote-managed. 잔여 = [B-cortex-xlsx-import-run](/ops/backlog) (660행 enrichment) + [B-cortex-mcp-catalog-publish](/ops/backlog) (`axe mcp publish`). |
| 2026-05-28 (PM3) | index | `38dcac8` | **`axe ship index` production prereq 완료** — `axe ship` CLI 에 `index` 등재 (`SHIP_SERVICES` + `SHIP_DIRNAME_MAP`), `customers.yaml axe.services.index` block 신설 (5 secret manifest: db-password / jwt-secret / oauth-client-secret / pii-passphrase-axec / anthropic-api-key shared), Dockerfile cortex→index 정정 + `SQLX_OFFLINE=true` + `.sqlx/` 28 query cache checked-in (DB 없이 Docker 빌드 가능), docker-compose healthcheck python→curl 정정, `.env.local.example` index-specific 재작성. **검증**: docker compose up → 4 컨테이너 healthy (postgres :4000 + mcp-blue :4010 + mcp-green :4011 + axe-index-proxy :4012), `/healthz` 200, `/index/mcp` 401 + WWW-Authenticate (RFC 9728), `/.well-known/oauth-protected-resource` envelope 정상. **Manual 잔존** (Soohun Global Admin 전용): (1) az ad app `"AXE Index MCP"` 등록 + credential reset, (2) tenant admin consent, (3) `axe secret push index` (5 vault item), (4) cloudflared route `axe.axelabs.ai/index/*` → `host.docker.internal:4012`, (5) GitHub repo + remote add, (6) `axe ship index` 첫 deploy. 상세 runbook = [/services/index](/services/index#production-배포-axe-ship-index). |
| 2026-05-28 (PM2) | index | `4ef1581` | **[D-index-10](/ops/decisions) A8 PASS — MCP `tools/list` + `tools/call` 4 tool 통합 ⇒ D-index-10 acceptance 8/8 ALL PASS**. `src/mcp.rs` skeleton 137 → 566 line (fully functional dispatcher). 4 tool: (1) `propose_deal_closure(seed)` D-index-13 atomic batch (4 sub-tool 흡수, UUIDv5 idempotency_key retry-safe), (2) `validate_financial_model(deal_code)` (A7 6 check), (3) `compute_outputs(deal_code, scenario?)` (exit_matrix aggregation per scenario), (4) `query_irr(deal_code)` (per-fund display + summary weighted IRR). 검증: 3 deal 모두 IC baseline ±1pp PASS (Iippo 36.52% / Sentry 40.26% / Canopy 26.39%). irr::weighted_* 함수 재사용으로 validate.rs in-memory 와 byte-identical 결과 보장. 3-layer error model (D-index-14): L1 HTTP (auth middleware) + L2 MCP body (JsonRpcError + error_code + context) + L3 skill. dev 회귀용 `index mcp-call TOOL --args JSON` CLI 도입 (auth bypass). **D-index-10 8/8** = A1 (DB ingest) + A2 (IRR ±1pp) + A3 (1호/2호 독립) + A4 (per-fund baseline) + A5 (cross-deal benchmark) + A6 (⏸️ xlsx 별 backlog) + A7 (validate_financial_model 27/27) + A8 (MCP 4 tools). 다음 = axe ship index 또는 Phase 2 skill MCP discovery. |
| 2026-05-28 (PM) | index | `00dc6c5` | **[D-index-10](/ops/decisions) A7 PASS — validate_financial_model 3/3 deals (Iippo + Sentry + Canopy) 0 warnings 0 errors**. `index validate-model` CLI 6개 sanity check 도입 (driver_dag.cycle / scenario_coverage / exit_matrix.sanity / leaf_probability_sum / leaf_probability_sanity / fund_investment.invariants) — `src/validate_model.rs` 608 라인. 핵심 발견·수정: (1) `revenue[y-1]` self-lag 가 같은-period DAG cycle 로 오인 → cycle detection 에서 self-edge skip (lag = 시간축 recurrence, not 같은-period cycle). (2) Sentry/Canopy 는 exit-matrix-only 모델 (driver 는 informational, proceeds 는 leaf 직접) → scenario_coverage 0% 를 PASS 로 인식, exit_matrix_leaves count 함께 보고. (3) Canopy Initial BW status='paid' 인데 paid_date NULL → 2025-06-01 보강. 결과 9 check × 3 deal = 27/27 PASS. **D-index-10 6/8 acceptance** (A1+A2+A3+A4+A5+A7). 잔여 = A6 (xlsx round-trip) + A8 (MCP tool integration). 다음 = `B-index-A6-xlsx-roundtrip` + Phase 2 (B-index-skill-versioning-schema / B-index-skill-mcp-discovery / B-blueprint-skill-mcp-client). |
| 2026-05-28 (Round 6) | docs | (TBD) | **🧹 Ready 중복 5건 제거 (concurrent index 세션 promote 누락분)**. 구조 점검 중 발견 — 5 항목이 Ready + Done 양쪽 동시 등재 (index/pmc 세션이 ✅ Done 으로 옮기며 Ready 사본 제거 누락): B-pmc-skill-skeleton, B-index-customers-yaml, B-index-lp-deliverable-export, B-index-skill-mcp-discovery, B-blueprint-skill-mcp-client. Done 본이 ✅+commit/LoC 증거로 authoritative → stale Ready 사본 5개 제거 (그들의 promotion 완성). 잔여 중복 0 검증. Ready 88 → 83 (실제 -5 active, phantom-todo 해소). 표 구조 점검 = 중간 빈줄 0 ✓. ground truth: in-progress 1 / ready 83 / 신규 60 / Done 54 / Archive 15. |
| 2026-05-28 (Round 5) | docs | `b04f0e4` | **🗄️ Done 섹션 lifecycle 정비 + 집계 방법 정정**. (1) Done 에 1주+ 경과 (2026-05-22/23) ship 완료 항목 15개 → 신규 `## 🗄️ Archive` compact 표로 이동 (lifecycle "이미 ship 된 ✅ 항목 promote" 준수). 각 항목 narrative 는 Ship Log + decisions.mdx 에 영구 보존 확인 후 verbose row 제거, Archive 는 ID→decision trace 만 (compact). Done staging 비대 해소. (2) **집계 정정**: 세션 내내 사용한 full-file `awk` 가 섹션 경계 배정 버그로 Ready/Done undercount (awk: ready 75 / 실제 명시 line 경계 python+sed+awk-range 3중 검증 = **ready 88**, 세션 중 불변). 🆕 신규만 일치 → **신뢰 지표 = 신규(분류 큐) 75 → 60 (-15)**. 기존 라운드의 "활성 151→136" 절대값은 불변 Ready 를 13 undercount 한 artifact 로 정정. 현재 ground truth: in-progress 1 / ready 88 / 신규 60 / Done 54 / Archive 15. |
| 2026-05-28 (Round 4) | docs | `acd26b7` | **🤖 Round 4 — deep audit (60 신규) with MCP verification, backlog 136→136 (0 reduction)**. 1 agent (Explore) 가 잔여 60 신규 항목 audit → 3 항목 silent-done 추천 (B-hive-send-202605, B-hive-mark-paid-202605, B-hive-202604-recon). **운영자 가치 = MCP 검증 결과 audit 결론 모두 inaccurate**: hive MCP `payroll_list_send_log` + `payroll_list_dispatch_log` 직접 query → (a) B-hive-send-202605: 강태훈 ✅ sent (5/25 graph_api) + 한진우 ❌ pending (RRN 선행) = **partial**, (b) B-hive-mark-paid-202605: paid_finalized 0 records = **NOT done**, (c) B-hive-202604-recon: dispatch_log 0 records = **NOT done**. 본 finding 의 교훈 = agent audit 은 description-circular 위험, prod MCP 검증 필수. 변경 = B-hive-send-202605 description 정확화 (강태훈 sent + 한진우 pending) 1줄. 활성 backlog 136 그대로. 누적 (Round 1+2+3+4) 151→136 (-15). |
| 2026-05-28 (Round 3) | docs | `5c7b262` | **🤖 Round 3 — reports landing + silent-done audit, backlog 138→136 (-2)**. (1) `/ops/reports/` 폴더에 `index.mdx` 신설 (77 라인, 4 섹션: 목적/보유/가이드/backlog 연계 + 3 report 표) + reports/_meta.js anthropic entry 추가. (2) Audit-driven silent-done 이동 — D-day 5/25 Ship Log narrative 근거: `B-customer-deploy-generalization` ✅ (R1-R5 완료, Phase 3 3rd-customer 만 split), `B-realchoice-port-collision-audit` ✅ (5/5 endpoint LIVE = implicit pass), `B-realchoice-vault-instance-decision` ✅ ((a) 채택 확정, description 정정 후 이동). 신규 62 → 60, Done 48 → 51. 누적 (Round 1+2+3) 151 → 136 (-15). |
| 2026-05-28 (Round 2) | docs | `1b45ab9` | **🤖 Round 2 — 4-agent 병렬 upstream draft + D-day traps consolidation, backlog 142→138 (-4)**. (1) `B-anthropic-connector-input-attrs` ✅ `/ops/reports/anthropic-connector-input-attrs-2026-05` 173 라인 (claude.ai Custom Connector modal 4 input 식별자 부재 → Anthropic 측 보고 draft). (2) `B-vault-axe.2-patches-upstream-pr` ✅ `/ops/reports/timshel-vaultwarden-upstream-pr-2026-05` 165 라인 (axe.2 2 patch upstream PR description draft, mainline backport 성격). (3) `B-trap-33-frame-hive-multi-issuer-docs` ✅ `/architecture/auth` line 147 정정 + 함정 row 추가 (v2 강제 + multi-issuer defense in depth). (4) `B-ops-reports-sidebar` ✅ `content/ops/_meta.js` reports entry 등재. 추가 consolidation: `B-vault-d-day-traps-2026-05-25` + `B-onboard-d-day-traps-2026-05-25` 두 trap inventory entry ✅ done 으로 이동 (모든 sub-trap ✅ 또는 split 완료). 신규 66 → 62, Done 42 → 48. 빌드 검증: 65 페이지 indexed (+2 신규). 누적 (Round 1 + 2) 활성 backlog 151 → 138 (-13). |
| 2026-05-28 | docs | `5e0f2a1` + `065cf63` | **🤖 6-agent 병렬 docs cleanup — backlog 151→142 (-9 active items)**. 멀티 에이전트 wave 1 (6 agents parallel) 로 docs SSOT 갱신: (1) `B-vault-setup-playbook-v2` ✅ [/onboard/vault-setup](/onboard/vault-setup) +84 라인 (taehun 5건 피드백 inline: Windows Hello + Phase 강제/선택 + TOTP UI + 자동 채우기 분기 + 표준/변형). (2) `B-vault-revoke-scope-doc` ✅ [/architecture/vault-policies](/architecture/vault-policies) `## Vault scope` 신설 (8-row 분리표) + [/ops/runbook/employee-offboarding](/ops/runbook/employee-offboarding) 외부 service 회수 step. (3) `B-bw-cache-recovery-procedure-docs` ✅ [/architecture/secrets](/architecture/secrets) 함정 표 row + [/ops/runbook/vault-recovery](/ops/runbook/vault-recovery) 새 ## 섹션. (4) `B-blueprint-scope-change-runbook-docs` ✅ [/architecture/auth](/architecture/auth) 함정 row + `## OAuth scope 추가 시 운영자 절차` 신설. (5) `B-claudeapp-fd-leak-anthropic-report` ✅ `/ops/reports/claudeapp-fd-leak-2026-05` 113 라인 self-contained draft (Anthropic support 제출용). (6) `B-docs-ssot-extension-2026-05-26-corrections` ✅ B4-B7 정정 (topology artemis_default + services/frame `${HOME}` + partner/registration `--allow-no-subscriptions` + partner/deploy 18-step 함정 표). 추가 backlog cleanup: 신규 75 → 66 (✅ 항목 7건 Done 으로 이동, 1건 description 갱신, 1건 자동화 prong 만 잔존으로 축소). 11 파일, +300 라인, -28 라인. |
| 2026-05-27 | docs | `6228f1d` | **[D-ops-41](/ops/decisions) — SSH client-side automation (Windows) 영구 fix** — Soohun Kang 실전 셋업 (Windows 11 + cloudflared 2026.5.1 + OpenSSH for Windows 9.5p2) 도중 발견한 6 함정 (#9~#14) 영구 해소. `/onboard/ssh-access` Step 7 의 `Scheduled task 자동화` 블록 폐기 → **user-context Scheduled Task + VBScript wrapper** (`cloudflared-ssh-axe-tcp`, AtLogOn + VBS 무한 루프, `wscript.exe` 0-flash hidden, 정상/비정상 종료 모두 5초 뒤 재기동) 로 전환. 신규 § "Token 자동 갱신 (Windows)" 추가 — **self-rescheduling PS1 task** (`cloudflared-token-renewal`, JWT `exp` claim 파싱 → `exp - 5min` 에 1회 fire, `-RunLevel Highest` 필수). 24h 마다 사람이 매일 수동 `cloudflared access login` 실행하던 ❌ → ✅ 자동. NSSM/SYSTEM 서비스화 폐기 사유 박제 (부록 — JWT user-scoped vs SYSTEM `%SystemRoot%\System32\config\systemprofile\` 격리 → 무한 token lock 루프). 함정 정리 표 8행 → 14행 확장. "매 작업 시 사전 작업" 표 갱신 (PC 로그온 + token 만료 5분전 모두 자동 + 선택 sticky session). **검증**: `Get-Process cloudflared, wscript` 둘 다 살아있고 `MainWindowHandle = 0` (가시적 창 0) / `Get-NetTCPConnection -LocalPort 2222 -State Listen` LISTENING / `ssh -p 2222 axe@localhost` `axe@AXEs-Mac-mini ~ %` prompt 정상 / PowerShell 창 모두 종료 후 신규 창 동일 검증 PASS (TCP forward 생존 확인) / renewal task `renewal.log` 에 `token exp=... / next run: ...` 두 줄 정상. |
| 2026-05-26 22:40 | docs | `bb61969` | **blurgram carve out — docs.axelabs.ai 에서 blurgram 흔적 0** (운영자 결정 "blurgram 은 자체 docs 로 별도 관리"). `content/ops/{backlog,known-gaps,decisions,inventory}.mdx` + `content/onboard/ssh-access.mdx` 5 파일, 33 deletions only. 이동 destination = blurgram repo 의 신규 `docs/AXE_HOSTING.md` (D-axe-36 MVP host pattern + D-axe-41 AXE 운영 편입 + D-axe-42 자체 AI 비활성 + 운영 inventory) + `docs/dogfooding/2026-05-26-cycle-relaxed-peach-squid.md` (외부 LLM citizen 첫 cycle 16 row 관찰표 보존) + `docs/status/03-backlog.md` 의 R/U 2 항목 추가 (`B-blurgram-dogfooding-feedback` + `B-blurgram-activity-log-sink`) + calendar alarm 2 row (8/25 + 11/25 sunset) D-axe-41 substitute 로 무효화 표시. 내용 누락 0. 검증: `grep -rn blurgram content/` → 0, live `curl https://docs.axelabs.ai/ops/known-gaps.md \| grep -c blurgram` → 0. memory 측 (`project_mvp_hosted_tunnels.md` + `project_blurgram_agent.md` + `MEMORY.md` index) cross-ref 도 정합 갱신 (operator 회상 보조로만 보존, SoT = blurgram repo). |
| 2026-05-26 22:00 | docs + axe-cli | `5726912` + `c03768a` | **backlog 갯수 정리 — 11 task 중 8 처리** (5 live + 1 axe CLI defensive + 2 draft). **1차 batch (`5726912`)**: B-bw-cli-version-pinning (`/architecture/secrets` Bootstrap 섹션 신설 + 함정 표 row + `/partner/macmini-prep` §6 신설 + 함정 row, bw 2025.7.0 표준 정합), B-docs-cache-control-static (`next.config.mjs` headers 에 `/llms.txt`+`/llms-full.txt`+`/changes.json` `s-maxage=60` 추가, Cloudflare 옛 응답 잔존 차단), B-trap-24-blueprint-mcp-admin-consent (`/partner/registration` Option A 사전 확인 표에 admin consent grant 권한 4 role 명시 + 함정 표에 manual grant 절차 + Option B 함정 모음 row 추가). **2차 batch (`c03768a`)**: B-axelabs-bootstrap-blueprint-mcp-app (trap #18 영구 fix — `public/axelabs-bootstrap.sh` App #4 Blueprint MCP 등록 step 추가 Frame MCP 패턴 1:1 mirror + JSON pack `blueprint_mcp` 필드 + `axe customers ingest` optional 흡수 backward compat + `/partner/registration` "3 개" → "4 개" + Option B App #4 섹션 신설 + SHA-256 갱신 `ae6f771e...`), B-customers-yaml-mkdir-trap (trap #20 — root cause grep 검증 결과 phantom 확정 + axe CLI `_load_yaml`+`_load_customers_yaml_rt` `path.is_dir()` defensive sanity check), B-trap-23-hive-volume-compose-prefix (R6 통합 결정, R6 row 비고에 hive volume 명시 추가). 라이브 검증: `https://docs.axelabs.ai/llms.txt` cache-control `s-maxage=60` ✓ + bootstrap.sh SHA = local 일치 ✓ + npm run verify:box PASS ✓. **남은 3 운영자 본인**: B-axe-labs-ai-2fa, B-cf-token-rotation, B-bp-mcp-teams-admin-consent. **draft 2 사용자 trigger**: B-vault-axe.2-patches-upstream-pr (`/Users/axe/vault/UPSTREAM_PR_DRAFT.md`), B-claudeapp-fd-leak-anthropic-report (`/Users/axe/.axe/ANTHROPIC_FD_LEAK_REPORT_DRAFT.md`). |
| 2026-05-26 17:35 | docs | `df85ba0` + `3dde8eb` + `ef8138e` | **MCP Connectors catalog LIVE — Vaultwarden `MCP Connectors` org collection (`1a62e754-...`) + `axe mcp publish/list` CLI + `axe secret rotate` step 4.5 auto-hook** ([D-vault-mcp-catalog](/ops/decisions)). 운영자/직원 (4명 access) 가 `claude.ai/customize/connectors` 등록 시 4 조각 (이름·URL·client_id·client_secret) 을 Bitwarden 확장 한 클릭에 자동 suggest. SoT 변경 0 (catalog = customers.yaml + vault 의 derived view). 3 MCP seed (frame/hive/blueprint) 완료. 본 세션 부수 발견: (a) **bw 2025.7.0 cache stale root cause 확정** = server-side patch deploy 후 cached `cryptoSymmetricKey` MAC fail, fix = `bw logout && bw login` 1분 절차 ([known-gaps](/ops/known-gaps) "매니페스트 / vault 측 미해결" 표). 오진 2회 (L2 REST API 마이그레이션 / KDF rotation) 후 정정 — backlog matching 만으로는 부족, premise 검증 필수 ([memory](#) feedback_session_start_ritual). (b) **bw `--passwordenv` silent failure** = positional `bw unlock "$PW" --raw` 만 작동. (c) **Keychain account 일관성** = `-a ai@axellc.com` 표준 (secrets.mdx:495), `$(whoami)` 사용 시 별 entry 생성 + find 가 옛 token 반환. (d) **customers.yaml frame_mcp 정정** = "proxy-only" stale 주석 해제, claude.ai 가 confidential client 요구하므로 secret 포함 publish. **backlog ✅**: [B-vault-mcp-catalog](/ops/backlog) + [B-bw-cache-recovery-procedure](/ops/backlog) 신규. axe CLI: `cmd_mcp_publish` + `cmd_mcp_list` + argparse + rotate hook (~190 LOC). |
| 2026-05-26 14:24 | frame | soohunkang/frame `3f9a707` | **D-frame-register-entity-atomic LIVE — 강태훈 bug report 의 root cause #2/#3 영구 fix + DB 좀비 정리 + axev→axe_ia_001 GP 관계 등록** ([D-frame-register-entity-atomic](/ops/decisions)). 강태훈 2026-05-22 Teams 메시지 (chat `19:5fda...@thread.v2/1779450170089`, sender taehun.kang@axellc.com) 의 KIP 등록 버그리포트 audit + fix + 회신 cycle. (1) ck_policy_standard mismatch 는 PR #38 (`3d8181d`) + 0019 in-place ALTER 로 이미 fix, 7 schemas 모두 적용 완료. (2) **잔여 위험 2건 코드 fix** (`src/frame/db/migrations.py:88 register_entity`) = (a) existing row 의 standard/kind/schema_name mismatch 시 ValueError (silent override 금지), (b) `upgrade_entity` 실패 시 compensating `DROP SCHEMA CASCADE` + `DELETE shared.entity` (좀비 회수, 기존 row 보호). 6 신규 pytest (`tests/test_register_entity_atomicity.py` mismatch standard/kind/all-diffs · idempotent identical · zombie cleanup · pre-existing 보호) + 16 기존 PASS 무회귀. (3) **DB 좀비 정리** = `axe_ia_001_diag` + `bug_check_kip_20260524` (actor=taehun.kang) DROP SCHEMA CASCADE + DELETE shared.entity (단일 트랜잭션, cross-ref 0 확인). 7 entities → 5 (axec/axev/axtest/axep/axe_ia_001). (4) **axe_ia_001 정상 회복** = 48 fund_ksme accounts + accounting_policy bootstrap + alembic 0019 head + fund_meta (GP=axev, 755M 약정, 21명 LP, 2026-04-22 등록 866-80-03471). 회계 데이터 0 = 사용 시작 준비. (5) **`shared.entity_relationship` row #112** = (axev → axe_ia_001, gp_managed_fund, effective_from=2026-04-22, ownership NULL — AXEV GP 자기 commit 분리 미명시). **axep** (액스파트너스 유한책임회사, 의도 불명, 데이터 0) 는 보존 ([known-gaps](/ops/known-gaps) 등재). **deploy 검증**: `axe ship frame` 통과 (docs-check no drift / 1 commit push / blue→green flip / `axe.axelabs.ai/frame/health` 200 / active=green:3711). 강태훈 회신 draft 완성, 강수훈이 Teams 로 forward 예정. **backlog ✅**: [B-frame-fund-ingest-verify](/ops/backlog) + [B-frame-register-entity-atomic](/ops/backlog). |
| 2026-05-26 16:17 | vault (axe org) | (compose env + API policies + docs) | **vault axe.3 post-deploy 정책 layer 박제 — server env `SSO_AUTH_ONLY_NOT_SESSION=true` + Org Policies 4종 + 신규 docs 페이지** ([D-ops-40](/ops/decisions) Progress xi-xii). ai@ KDF rotation 검증 완료 (Master password change + rotate encryption key 만으로 SSO→MP 정상). server env 1종: `SSO_AUTH_ONLY_NOT_SESSION=true` → SSO 인증만, session = Vaultwarden 자체 30일 idle refresh (60s 다운타임, 모든 SSO user 자동 적용). Org Policies 4종 (Owner API): MasterPassword(min 12, complexity 1) + PasswordGenerator(len 20) + SingleOrg + PersonalOwnership. MaximumVaultTimeout 시도 HTTP 400 — Timshel source 의 `// Not AGPLv3 Licensed` 확인 (Bitwarden commercial license, Vaultwarden 영구 미지원, `SSO_AUTH_ONLY_NOT_SESSION` 이 가용 best 대체). 신규 docs [/architecture/vault-policies](/architecture/vault-policies) 박제 (3 layer 모델: server env + Org Policies + per-client preferences, 새 직원 onboarding 표준 setup, customer sovereignty 안내). **잔여**: soohun/taehun/jinwoo KDF rotation (각 본인 5분, ai@ flow 그대로). [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) ✅ 이동은 3명 완료 후. |
| 2026-05-26 13:19 | vault (axe org) | axelabs-ai/vault `799015b` | **vault axe.3 LIVE — `ghcr.io/axelabs-ai/vault@sha256:a26208a0...` 으로 manifest-digest 재핀** ([D-ops-40](/ops/decisions) Progress). 3.5h 실 진행: realchoice 측 build pipeline (build.sh + Dockerfile + GHA workflow + 2 axe.2 patches) vendor + axe.3 patch 2개 (organizations Owner-skip 3 site + cipher.permissions backport — line 600 `post_bulk_access_collections` 추가 발견 → 3곳 모두 fix). 로컬 docker arm64 build 검증 5분 → main push → GHA 13분 multi-arch (amd64+arm64) GHCR push → imagetools alias `1.34.1-6-axe.3`. axe-macmini deploy: data + sqlite 백업 → pull + up → 60s healthy. **검증 3건 in-production**: VERIFY 1 `bw create org-collection` → SQLite users_collections 에 Owner ai@ row 명시 insert ✅, VERIFY 2 raw GET `/api/sync` → cipher.permissions `{delete:true,restore:true}` server emit ✅ (bw 2025.7.0 출력은 null — 옛 client 가 unknown field 미파싱), VERIFY 3 `bw delete item` rc=0 ✅. external alive HTTP 200 (0.28s). **GHCR auth**: PAT 발급 → AXE vault `Platform — Service Secrets / ghcr-axelabs-ai-pull-pat` 저장 ([D-ops-ops-17](/ops/decisions) SoT, keychain 회피). **잔여**: 4명 KDF rotation (PBKDF2 → Argon2id, [B-vault-axe.2-sso-mp-incomplete](/ops/backlog) runbook) + Truvia 안내 (customer self pull). **backlog ✅**: [B-vault-fork-build-pipeline](/ops/backlog) + [B-vault-org-perm-3-quirks](/ops/backlog). [D-ops-37](/ops/decisions) image 라인 axe.3 digest 로 갱신, rollback 주석 (axe.2 ImageID + timshel digest) 보존. |
| 2026-05-26 (심야) | vault (axe org) | (운영 데이터 + docs) | **vault organization 권한 모델 정착 + OpenAI item 통합 + 3 권한 함정 root-cause 진단** ([D-ops-32](/ops/decisions) Progress + [D-ops-38](/ops/decisions) 첫 실 적용 + [B-vault-org-perm-3-quirks](/ops/backlog) 신규). **collection 작업**: D-ops-32 의 6 collection 전부 `bw create org-collection` 으로 신설 (AXEC/AXEV/AXEP/Platform Service Secrets/Platform Infrastructure/Shared Tools). **권한 fix**: server-side `users` 배열 매핑 함정 (Owner skip + manage=0 강제) 으로 6 collection 모두 ai+soohun 권한 누락 → vaultwarden stop → SQLite 직접 `users_collections` INSERT/UPDATE/DELETE (transaction) → start. **OpenAI item 통합**: soohun 이 personal vault → AXE org share 한 두 item (`chatgpt.com` + `platform.openai.com`, 같은 ai@ 계정) 을 1 item multi-URI (Base domain match) 로 통합. cipher delete/move 가 bw CLI 의 client-side `permissions.delete: false` reject 로 막힘 → `*/admin` HTTP endpoint 직접 호출 (access_token = bw data.json 추출) 로 우회 → 영구 삭제 + Platform — Infrastructure 단독 collection. 최종 = 1 item, 권한 정합, MCP connector 영향 0. data/ 추가 백업 (`db-pre-permissions-fix-20260526-111834.sqlite3`). |
| 2026-05-26 (저녁) | vault (axe tenant) | (compose 단독) | **vault axe.2 패치 — axe-vaultwarden 1.34.1-6-axe.2 deploy** ([D-ops-37](/ops/decisions)). Bitwarden client >= 2026.4 (Chrome ext + bw CLI) 와 Timshel 1.34.1-6 사이 2 protocol 불일치 영구 fix. 이미지 출처: realchoice-macmini local build (axelabs-ai/vault 의 GHCR push 미구축) → docker save/load streaming (LAN 7s) → axe-macmini import (arm64, ImageID `sha256:11536845...`). compose image 라인 교체 + commentary 갱신 (Timshel digest 이전 값 rollback 주석 보존). `/vault/identity/accounts/prelogin/password` 200 OK 회귀 검증 ✅ (이전 404). **운영자 수동 검증 결과**: (a) MP 단독 web 로그인 ✅, (b) SSO 성공 → MP 단계 ❌ (web + Chrome ext + native app 3 client 모두 동일 → server-side 원인 확정. realchoice-macmini 동일 image 는 정상이라 회귀 아님, 기존 user wrapped MP schema 미마이그레이션 가설). 후속 = [B-vault-axe.2-sso-mp-incomplete](/ops/backlog). data/ 2.5MB 사전 백업 (`backups/data-pre-axe.2-20260526-093846.tgz`). **backlog**: `B-vault-d-day-traps-2026-05-25 #12` server-side 영구 fix 등재, 신규 `B-vault-fork-build-pipeline` + `B-vault-axe.2-patches-upstream-pr` |
| 2026-05-25 (오전) | infra+docs | (다수) | **🎯 realchoice (Truvia 주식회사) D-day-resume 완료 — 5/5 endpoint LIVE + customer sovereignty 첫 실제 적용**. 5/25 09:00 KST 일정 앞당김 (Truvia 요청 "지금 즉시"). **운영자 책임 3건**: (1) cloudflared catch-all 교체 09:28 (5 rule → 1 rule, trap #10 fix `127.0.0.1:8090`). (2) hive repo PAT 임시 push (axelabs-ai/hive private clone, ~/.netrc 즉시 제거). (3) customers.yaml realchoice 블록 sovereignty 정리 (`legal_name=Truvia 주식회사`, 5 sso.apps client_id 만 유지, services secret manifest 일체 제거 — customer 측 자체 SoT). **Truvia 자체 (sovereignty 본질)**: blueprint MCP + hive MCP Entra app 자체 등록 + secret 자체 (openssl rand) + .env + compose up + axe-realchoice-ingress Caddy 신설 (host port 8090) + 5 service self-deploy. **5 endpoint health**: `/` 200 / `/frame/health` 200 / `/vault/alive` 200 / `/blueprint/mcp/health` 401 (OAuth) / `/hive/health` 200. **신규 trap 5건** (#18 bootstrap.sh Blueprint MCP app 미등록 / #19 docker volume external 사전 부재 / #20 customers.yaml directory 잘못 생성 / #23 hive volume compose project prefix / #24 admin consent Global Admin 부재). **신규 backlog 5건** (B-customer-sovereignty-architecture Q3 + 4 trap 영구 fix). axe CLI 변경: `_render_cloudflared_config` catch-all + `_svc_step_ingress_swap` no-op + `--yes` flag + `_svc_step_customer_vault_check` bw 2025.7.0 + APPDATA_DIR 격리 |
| 2026-05-26 (PM) | docs+axe-cli | (다수) | **Truvia 5/26 회신 반영 — D-day blocking + backlog 확장** (B-customer-deploy-generalization Phase 1 후속). Truvia 측 D-ops-32 완료 보고 (realchoice vault organization `eac93965-...` + ai@ invite + collection 4종) + 4 신규 함정 (#12-#15) + docs SSOT 갱신 권장 (7 페이지 + 17 함정 통합 + 5 표준). **5/27 D-day blocking 처리**: bw-bootstrap.sh 갱신 (bw 2025.7.0 pin + BITWARDENCLI_APPDATA_DIR 격리), wrapper 3종 (`start-{frame,blueprint,hive}.sh`) 가 ~/.bw-appdata-dir source, axe CLI `_svc_step_customer_vault_check` 가 bw version assertion + appdata 격리 검증, `_svc_step_secrets_bootstrap` 가 cross-vault sync 도 appdata 격리 전파. **backlog 등재**: `B-vault-d-day-traps-2026-05-25` 의 #12-#15 본문 추가 (8 함정 누적), `B-onboard-d-day-traps-2026-05-25` 의 #6/#16/#17 본문 추가 (12 함정 누적). 신규 backlog 6종 (`B-vault-org-create-automation`, `B-vault-org-cli-automation`, `B-port-conflict-preflight`, `B-frame-keychain-to-vault`, `B-bw-cli-version-pinning`, `B-docs-ssot-extension-2026-05-26`). known-gaps 에 **axelabs 5 표준** 신설 섹션 (macmini 패턴 등가 / Timshel image / bw 2025.7.0 / customer-deploy R1-R5 / customers.yaml schema). **회귀 0** — axe-side deploy + customer dry-run 모두 통과 |
| 2026-05-26 (AM) | axe-cli+infra | (axe CLI 미관리) | **B-customer-deploy-generalization Phase 1 완료** — `_deploy_service_customer(service, customer_id, ...)` 신설 (axe CLI line ~3265, 13-step service-agnostic). SERVICE_DEPLOY_CONFIG 참조하여 frame/blueprint/hive customer-측 deploy 통일. 5 요건 빌트인: R1 `${HOME}` 변환 (remote_dir_template), R2 vault SoT (customer macmini 측 `bw get password` — keychain 의존 폐기), R3 `$` → `$$` escape (`escape_dollar` flag), R4 `image_override` 슬롯 (customers.yaml). wrapper 3종 정비 (`start-{frame,blueprint,hive}.sh` 모두 `~/.bw-session` + `.secrets.list` 기반). customer 측 1회 부트스트랩 helper `bw-bootstrap.sh` 신설. `cmd_deploy_blueprint` body 가 dispatcher delegate, hive/frame customer 분기 활성. realchoice customers.yaml 의 3개 OAuth secrets 에 `escape_dollar: true` 적용. **회귀 0** (axe-side frame/blueprint-mcp/hive deploy dry-run 모두 통과). known-gaps trap 4·5·6 영구 fix 표지. **Pending Phase 2** = Truvia 5/27 D-day-resume 시 `axe deploy {frame,blueprint,hive} realchoice --apply` 일괄 |
| 2026-05-25 (PM) | docs+axe-cli+infra | `70f0599` → `8c82595` (5 commit) | **realchoice D-day frame+vault layer LIVE + customer-deploy 일반화 착수** — onboard 18-step ✅ 완료 (`realchoice.axelabs.ai/frame/health` HTTP 200) + Vault OIDC SSO 통합 ✅ (Q3 (a) 채택, `~/vault` = `soohunkang/vault` repo, SSO 로그인 → 잠금 해제 정상). D-day 함정 누적 10 (onboard) + 4 (vault) = 14, 모두 backlog 등재 (`B-onboard-d-day-traps-2026-05-25` + `B-vault-d-day-traps-2026-05-25`). vault-recovery runbook 의 sso_nonce schema PostgreSQL/SQLite 분기 + `verifier` column 명 정정. Truvia C 채택 후 **`B-customer-deploy-generalization` 진입** (M1, ETA 2026-05-27, 5 요건 R1-R5 빌트인). axe CLI `SERVICE_DEPLOY_CONFIG` skeleton (frame/blueprint/hive 메타) + cmd_deploy stub. plan SSOT: `/Users/axe/customer-deploy-generalization-plan.md`. 다음 세션 entry = `/Users/axe/.axe/NEXT_SESSION.md` §0-bis Phase 1.2~3 |
| 2026-05-25 06:50 | docs+axe-cli+infra | (다수) | **realchoice D-day execution 진입 (in-progress)** — RE^6 (D-day 즉시 시작 피벗) + RE^7 (운영자 사전 점검) + TXT 등재 (`MS=ms12037986`) + JSON pack 수신 + `axe customers ingest realchoice --apply` ✅ (vault 3 secret + customers.yaml fill) + `axe onboard realchoice --apply` step 1-13 ✅. axe CLI line 2588 step 12 fix (`security find -w` → metadata-only) 적용. 발견 6 함정 (`B-onboard-d-day-traps-2026-05-25`): Tailscale alias resolver / SSH non-login PATH / TXT+CNAME 공존 / keychain partition 격리 / start-frame.sh wrapper fetch. **step 14 차단** — Truvia 회신 대기 (옵션 A = 직접 실행 / 옵션 B = keychain ACL partition-list 변경). 핵심 entry = `/Users/axe/.axe/NEXT_SESSION.md` §0-bis |
| 2026-05-25 10:00 | docs | (다수) | **Truvia D-7 RE^4 회신 처리** — payslip Phase 3 deferral / 외부 회계법인 별도 회신 (`B-frame-cross-check-workflow` 신규) / macmini 이진우 자택 IP 동일 (`B-realchoice-tailscale-onboard` 신규) + `B-frame-lpm-classify` ETA 3 단계 명시 (D+90 minimum viable / D+120 rule-pre-classifier / 2026-12-01 stable) + `/services/frame` 에 **신규 customer 1 차 사이클 runbook** 신설 (D-day ~ D+30 의 chart auto-seed → ingest → trial balance → payroll 매칭 → 수작업 분개 → 회고 순서). Truvia D+30 사이클 effort 산정 명확화 (200~500 건 분개, 1 인 2~5 일/월) |
| 2026-05-23 21:00 | axe-cli+docs | (axe CLI 미관리) | **`axe customers ingest <id> <pack.json>` CLI 신설 (B-onboard-azure-pack ✅)** — axelabs-bootstrap/v1 schema 검증 + customers.yaml fill (ruamel round-trip, comment 보존) + services 매니페스트 4 슬롯 + vault push × 3 묶음. dry-run 기본. realchoice 가상 pack 으로 모든 plan 출력 검증 + 3 에러 path (bad schema / customer mismatch / unknown block) 검증. customer-onboarding.mdx 의 D-day 명령 흐름이 secret push × 3 → ingest 1 명령으로 축소. 트루비아 RE^2 §8 즉시 착수 요청 완료. axe CLI 변경 (`/Users/axe/.axe/bin/axe` cmd_customers_ingest + INGEST_MANIFEST_TEMPLATE + REQUIRED_PKGS += ruamel.yaml>=0.18) 은 git 미관리 — axe-backup 자동 보존 |
| 2026-05-23 20:30 | docs | (다수) | **realchoice 측 RE^2 합의 반영 + 운영자 측 5/25 D-7 약속 docs 등재** — `D-magnet-tenant-map-1` (customers.yaml service_tenant_map 신설, magnet RLS tenant_id ↔ AXE customer ID 매핑 SSOT) + `D-nemotron-1` (`/services/nemotron-personas` placeholder, D+14 라이선스 회신 대기) + `B-frame-lpm-classify` priority 상향 (RE^2 Q7: 2026 4Q 병행 운영 수작업 분개 risk) + backlog 5 신규 항목 (`B-realchoice-d7-checklist`, `B-realchoice-d-plus-checklist`, `B-magnet-tenant-env-injection`, `B-nemotron-catalog-promote`, `B-operator-bus-factor`). 7 D 결정 confirm + 8 Q confirm + cfo@realchoice.co.kr 신설 합의. D-7 (5/25) 트루비아 측 회신 대기 3 항목 (Hive 발송 도메인 / 호수회계법인 cross-check / macmini IP) |
| 2026-05-23 19:30 | docs | [`d0590e7`](https://github.com/) | **운영 주체 표기 = 액스코퍼레이션 주식회사 + 컨테이너 이름 컨벤션 명시** — narrative 9 페이지 (index/glossary/partner/* /ops/inventory/secret-rotation) 의 "강수훈" 인명 + "AXE LLC" → "액스코퍼레이션 주식회사 (axec entity)". customers.yaml axe.legal_name 정정. `/partner/deploy` 에 도입 후 macmini 컨테이너 구성 도식 + 3 패턴 (customer-prefix / customer-agnostic / historical axe- prefix) 신설. `B-container-name-customer-prefix` 등재 — Truvia RE 측 도식 의문 직접 답변 |
| 2026-05-23 19:00 | docs | [`d91e0bf`](https://github.com/) | **landing role-router callout** — docs.axelabs.ai URL 단독 송부 시 customer IT/직원/운영자 3-path 즉시 분기 가능. hero 다음 표 추가 + Quick Links 의 customer 항목을 partner entry 로 교체. 4-link 묶음 송부 의존 폐기 |
| 2026-05-23 18:30 | docs | [`0861d73`](https://github.com/) [`101fa0d`](https://github.com/) | **D-onboard-bootstrap-publish** — `axelabs-bootstrap.sh` (17749B, SHA-256 `7d2d607...`) 를 `https://docs.axelabs.ai/axelabs-bootstrap.sh` raw 노출. partner/registration §Option A self-contained + partner/macmini-prep 신설 + partner/domain-prep §A/§B + partner/handoff JSON pack. customer IT 가 docs link 만으로 자력 완료 가능 — 별도 안전채널 메시지 (`realchoice_entra_id_setup_v4.md`) 의존 폐기 |
| 2026-05-23 18:00 | docs+axe-cli+infra | (다수) | **Phase 1/2 contributor platform 세션** — D-bp-entity-17 (EntityRole + hive/frame OIDC 연동) 3 PR merge/ship + D-frame-fund-ksme-policy-check (axe_ia_001 좀비 fix) + D-dev-platform-1~6 (multi-user dev access · axe customers add/github-team/vault-bootstrap CLI · axe-labs-ai GitHub identity · Cloudflare Zero Trust App · axe vault unlock Keychain-backed bw session) + D-host-setup-1 (`/ops/host-setup` 13 layer SSOT 신설). 강태훈 Teams 회신 4건. 함정 +5건 (PTY exhaustion · Fine-grained PAT Resource owner · gh CLI keyring stale · bw subprocess BW_SESSION env 누락 · Vault session idle timeout). backlog +10 항목 (axe host inventory/bootstrap CLI · pat rotation cron · 2FA · pty-max launchd · customer deploy · user add 등). 강태훈 SSH pubkey + GitHub username 회신 대기 |
| 2026-05-23 11:30 | docs | [`a0c06f9`](https://github.com/) | **박스 정렬 함정 4번째 영구 차단** — Sarasa Bold @font-face 제거 (Cloudflare 503 영구캐시 fix) + `verify-box-alignment.mjs` (Playwright origin 측정) + `axe ship docs` 자동 통합 + sync-axe-ui 가 woff2 url 에 `?v=<SHA>` 부착 (브라우저 폰트 캐시 무효화). 4 layer 누적 차단. [known-gaps](/ops/known-gaps) 분석 등재 |
| 2026-05-23 11:00 | axelabs+blueprint+artemis+docs | [`a4d8b7e`](https://github.com/) | **@axe/ui v0.3.2 + 3 소비자 배포** — 43+ 컴포넌트 (DataTable/Pagination/Chart/AlertDialog/Accordion/DropdownMenu/EmptyState/ErrorBoundary/StatusBanner/Tree/Timeline/MasterDetail/ResponsiveTabs/MessageWithSources/TypingIndicator/Code/Section/Hero/Footer/Splitter/usePolling/useEventSource/useScrollSpy) + Perf P0/P1 (sideEffects · overrides · optimizePackageImports · Fontshare 비차단) + QA P0 7 + P1 11 fix. Blueprint dogfood — native `confirm()` → `AlertDialog` (SkillsClient.tsx, +53/-3). 모두 production 안정 |
| 2026-05-23 10:00 | infra | [`bfc50ce`](https://github.com/) | **D-ops-35** — `axe deploy hive {customer}` subcommand 신설 (frame blue/green 패턴 1:1 mirror, 8-step). axe `--apply` 실 검증: blue:3810 → green:3811 active 무중단, edge health 200. hive 가 `axe ship hive` 의 manual_hint 만 남아있던 격차 해소. realchoice 6/1 deploy 의 step 4 manual ssh 폐기. axe CLI 변경 (`/Users/axe/.axe/bin/axe`) 은 git 미관리 — axe-backup snapshot 으로 보존 |
| 2026-05-23 09:10 | docs | [`74616be`](https://github.com/) | Ship Log + Highlights — 5/22~23 Vault end-to-end (D-ops-24~33) narrative 등재 (다른 세션 docs ritual) |
| 2026-05-23 08:57 | docs+infra | [`3e75e83`](https://github.com/) | `axe secret send` CLI 신설 — 매니페스트 lookup → bw GET → bw send 파이프. stdin 주입 (argv 노출 0) + locked-vault pre-check. 옵션 `--to`/`--days`/`--access`/`--password`/`--customer`. 운영자 → customer IT 안전 secret 전달 채널 (anonymous one-time URL) |
| 2026-05-23 09:00 | docs+infra | [`7988028`](https://github.com/) | **D-ops-33** — `axe vault bootstrap {customer} [--apply]` subcommand 신설. D-ops-24/26/27 4-key env 패치를 코드로 항구화 (수동 4-block → 1 command). Idempotent + dry-run default. axe 검증 ("bootstrap 불필요" detect) + realchoice dry-run (file 부재 깔끔 에러). runbook customer-onboarding.mdx D+1 섹션 1-command 화. `B-onboard-cli-vault-bootstrap` env 패치 부분 ✅ |
| 2026-05-23 08:42 | docs | [`4c12081`](https://github.com/) | runbook customer-onboarding.mdx: D-ops-24~32 lessons codified — D+1 Vault 부트스트랩 4-block 섹션 + 함정 표 6건 추가. `deploy-new-entity.sh` 일반화 (customer-agnostic) + `B-realchoice-deploy-prep` backlog |
| 2026-05-22 22:30 | infra | _pending_ | **D-ops-31 deploy 완료** — axep PII passphrase 2개 vault push + frame blue/green swap (active=green:3711) + hive sequential force-recreate. edge frame/hive health 200, axec/axev 영향 0. 자동화 스크립트 `/Users/axe/.axe/vault/deploy-axep.sh`. 부수 함정 등재: `axe secret push` 가 BW_SESSION env 무시, macOS Keychain (`axe.vault.session`) 만 읽음 |
| 2026-05-22 21:55 | docs | f1f87bc | **Teams bot integration spec 신설** ([blueprint.mdx](/services/blueprint)) — `## Teams bot integration` section: agent identity (ai@/cfo@) · inbound 처리 흐름 · 첨부 처리 contentType 표 (reference / inline image / messageReference / unhandled) · reply 안전 정책 (sanitizer / silent-drop / in-place edit). [Blueprint PR #372](https://github.com/soohunkang/blueprint/pull/372) (`messageReference` 첨부 본문 fetch fix — 봇 false-negative 제거) 의 docs-first anchor. backlog 2건 (`B-bp-teams-context-msgref` + `B-bp-teams-attachment-contenttype-audit`) + known-gaps Blueprint 섹션 등재 동반 |
| 2026-05-22 17:50 | docs+infra | _pending_ | D-ops-31 + D-ops-32 — axep entity 신설 (액스파트너스 유한책임회사, frame+hive register-entity 적용) + customers.yaml entities 배열·PII secret·user_entity_map 갱신 + Vault collection v1 구조 6-collection 설계 (Platform-Service/Platform-Infra/AXEC/AXEV/AXEP/Shared). 후속: PII passphrase 2개 push + frame/hive ship + collection web UI 마이그레이션 |
| 2026-05-22 16:40 | docs | _pending_ | D-ops-29 + D-ops-30 — dual-identity (`ai@` automation / `soohun.kang@` human Owner, 둘 다 vault Owner access_all=1) + Blueprint `/api/admin/broadcast-dm` endpoint 추가 (operator broadcast 1:1 DM, fan-out from cron-failure-alert pattern) |
| 2026-05-22 16:00 | docs | _pending_ | D-ops-28 — bw CLI 2025.7.0 다운그레이드 (Timshel 1.34.1-6 ↔ CLI 2026.x `toWrappedAccountCryptographicState` crash 우회) + 한진우/강태훈/강수훈 AXE org member 4명 invite + confirm 완료 (자동화 `invite-members.sh`) + 업스트림 vault 1.36.0 native SSO 마이그레이션 backlog |
| 2026-05-22 15:00 | blueprint | _pending_ | D-bp-entity-16 — admin role 자동 sys entity 포함. hydrate 가 customers.yaml 의 explicit list 뒤에 sys append (admin 전용 가시성, 일반 user 403 유지) |
| 2026-05-22 14:30 | blueprint | _pending_ | D-bp-entity-14 — /axe/usage entity scope. UsageLog → Session → Workspace.entityId 경로로 axec/axev 비용 분리. workspace 미존재 = sys |
| 2026-05-22 14:00 | blueprint | _pending_ | D-bp-entity-15 — switch-account ownership 검증을 authenticatedUserId 기준으로. impersonated session 의 sibling switch 403 silent fail 버그 해소. selectAccount 에러 노출 |
| 2026-05-22 13:30 | blueprint | _pending_ | D-bp-entity-13 — EntitySelector 도 button + popover (AccountSwitcher 패턴 미러). UI 일관성 + slug chip 표시 |
| 2026-05-22 13:00 | blueprint | _pending_ | D-bp-entity-12 — TopNav 사용자 이름이 AccountSwitcher trigger (M365/Gmail 패턴). 별도 `<select>` 폐기, button + popover, click-outside + Escape close |
| 2026-05-22 12:40 | blueprint | _pending_ | D-bp-entity-11 — "전체 entity" 폐기 (PR #360 + #361). 항상 specific scope 강제, fallback chain URL → localStorage → defaultEntity → scopes[0] |
| 2026-05-22 12:30 | blueprint | _pending_ | D-bp-entity-10 — AccountSwitcher 항상 노출 + `+ 다른 계정으로 로그인` (PR #358 + #359 hotfix) |
| 2026-05-22 11:30 | docs | _pending_ | D-ops-27 — Vaultwarden operator setup 마무리: `SSO_ONLY=false` 유지 (emergency MP fallback) + `ORGANIZATION_INVITE_AUTO_ACCEPT=true` (멤버 초대 흐름 단순화) + backup verify (snapshot `9c2eb955` 에 vault data 포함) |
| 2026-05-22 10:10 | docs | _pending_ | D-ops-26 — Vaultwarden JIT user provisioning 활성 (`SIGNUPS_ALLOWED=true`). 신규 employee 의 "Failed to retrieve the invitation" 차단 해소 |
| 2026-05-22 09:25 | docs | _pending_ | D-ops-24 — Vaultwarden SSO + Entra ID `email_verified` 면제 (`SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION`) + `/vault/#/sso` 직링크 안내 |
| 2026-05-22 12:50 | docs | [`21d815a`](https://github.com/) | build 산출물 sync (axe-ui VERSION + llms.txt) — ship working tree check 통과용 |
| 2026-05-22 12:48 | docs | [`ac4f52e`](https://github.com/) | architecture/axe-ui 페이지 신설 — @axe/ui 적용 5분 절차 + light/dark 토글 + 함정 표 |
| 2026-05-22 12:30 | docs | [`21042ac`](https://github.com/) | B-search-deploy ✅ + 본 chapter ship 7건 Ship Log 등재 |
| 2026-05-22 11:55 | docs | [`ce4dc18`](https://github.com/) | troubleshooting AADSTS7000215 — frame MCP Advanced 칸 비워야 (D-ops-15.5) |
| 2026-05-22 10:11 | docs | [`f520d3a`](https://github.com/) | D-ops-26 — Vaultwarden JIT user provisioning 활성 |
| 2026-05-22 08:48 | docs | [`4d7aed8`](https://github.com/) | alpine builder 에 `apk add git` (changes.json 빈 응답 진짜 fix) |
| 2026-05-22 08:46 | docs | [`b441a97`](https://github.com/) | .git 을 builder stage 에 포함 (changes.json 빈 응답 1차 fix) |
| 2026-05-22 08:42 | docs | [`564aa61`](https://github.com/) | auth/troubleshooting 보강 + docker-compose.yml repo 화 |
| 2026-05-22 08:40 | docs | [`c8f8544`](https://github.com/) | .claude/ ignore (claude code per-project local config) |
| 2026-05-22 08:37 | docs | [`eed16f3`](https://github.com/) | /ops/updates 신설 + /api/changes JSON feed (시간축 4-페이지 분리 완성) |
| 2026-05-22 08:21 | docs | [`49dc3ad`](https://github.com/) | D-bp-entity-3 — General bucket 제거 + sys entity 도입 |
| 2026-05-22 08:10 | docs | [`9c13bcc`](https://github.com/) | Pagefind 자산 cache-control 60s (s-maxage) — 옛 응답 캐시 잔존 회피 |
| 2026-05-22 01:49 | docs | [`3de1434`](https://github.com/) | Pagefind 검색 + roadmap/backlog 신설 + mdx ?metadata 함정 17 위치 정리 |
| 2026-05-22 01:35 | docs | [`7984aa7`](https://github.com/) | D-bp-alert-1 — operator alert AXE-native (Slack 폐기) |
| 2026-05-22 01:16 | docs | [`437cd5e`](https://github.com/) | D-ops-22 — frame 펀드 도메인 지원 (KIP/KVF, shared schema 확장) |

---

## Highlights

> 큐레이션. 의미 있는 변경만, narrative. 직원·외부 IT 가 "지난 한 달 무엇이 새로 생겼나" 5분 안에 파악.
>
> 등재 절차: 운영자가 1-2 주에 한 번, Ship Log 와 backlog ✅ 항목을 검토하고 narrative 한 단락 작성.

### 2026-05-22 ~ 23 — Vault end-to-end 셋업 + axep entity 신설 + customer 일반화

axe customer 의 Vaultwarden 을 6명 (operator 4 + 2 dual-identity) 사용 가능 상태로 본격 셋업. 첫 employee SSO 시도부터 5 시리얼 함정 해결 → 결정 9 건 ([D-ops-24](/ops/decisions) ~ [D-ops-33](/ops/decisions)):

- **D-ops-24** Entra ID id_token 의 `email_verified` claim 부재 → Timshel fork 거부 → `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION=true`
- **D-ops-26** `SIGNUPS_ALLOWED=false` 가 JIT user 생성 차단 → "Failed to retrieve the invitation" → `SIGNUPS_ALLOWED=true`
- **D-ops-27** `SSO_ONLY=false` 유지 (Entra 장애 emergency MP fallback) + `ORGANIZATION_INVITE_AUTO_ACCEPT=true` (직원 Accept 자동)
- **D-ops-28** bw CLI 2026.4.1 ↔ Timshel 1.34.1-6 호환 미스매치 (`toWrappedAccountCryptographicState` crash) → CLI 2025.7.0 다운그레이드. 항구 해소는 `B-vault-upstream-migration` (dani-garcia/vaultwarden:1.36.0 native SSO)
- **D-ops-29** dual-identity 패턴 (`ai@` automation / `soohun.kang@` human Owner) — bot/human sender 혼동 회피
- **D-ops-30** Blueprint `/api/admin/broadcast-dm` endpoint — operator broadcast 1:1 Teams DM (vault onboarding 안내 3명 발송 검증)
- **D-ops-31** axep entity 신설 (액스파트너스 유한책임회사) — frame+hive register-entity + customers.yaml + PII passphrase 2개 + frame blue/green + hive sequential. axec/axev 무중단 검증
- **D-ops-32** Vault collection 구조 v1 종합 설계 (6-collection: Platform-Service/Platform-Infra/AXEC/AXEV/AXEP/Shared, entity 1개 customer 는 4-collection 변형)
- **D-ops-33** `axe vault bootstrap {customer} --apply` CLI 신설 — D-ops-24/26/27 4-key 적용 자동화. realchoice 6/1 deploy 가 axe 의 5/14~22 시리얼 함정 자동 회피

부수 발견 함정 2건: (a) `axe secret push` 가 `BW_SESSION` env 무시하고 macOS Keychain (`axe.vault.session`) 만 읽음 — 자동화 스크립트가 keychain 갱신 통합, (b) MDX acorn 파서가 backtick 안 `${VAR}` 와 `<placeholder>` 도 JSX 로 파싱 — D-ops-30 decision row 작성 시 2회 build fail.

산출 스크립트: `/Users/axe/.axe/vault/invite-members.sh` (org member invite 자동), `/Users/axe/.axe/vault/deploy-axep.sh` (PII push + ship), `/Users/axe/.axe/vault/deploy-new-entity.sh` (customer-agnostic 일반화), `axe vault bootstrap` (subcommand).

### 2026-05-22 — docs.axelabs.ai 검색 + 운영 ritual 4-페이지 분리

`docs.axelabs.ai` 의 우상단 검색박스가 처음부터 동작 안 했음 (Nextra v4 의 검색이 Pagefind 정적 인덱스 기반인데 빌드 스크립트에 단계 누락). 본일 fix + 라이브 배포 — 4 함정 시리얼 해결: ① Pagefind build 단계 누락 / ② Nextra dev `?metadata` 의 acorn 파싱이 backtick 안 `<placeholder>` 와 `${VAR}` 까지 잡는 함정 (17 위치 plain text ASCII 로 정리) / ③ `git commit 누락 → 옛 image ship` (commit-before-ship ritual) / ④ Cloudflare `max-age=14400` 옛 404 응답 4시간 캐시 (`s-maxage=60` 명시로 미래 회피). 검색 라이브 동작 검증: `cf-cache-status: HIT`, 45 KB.

동시에 운영 흐름의 entry point 가 [`known-gaps`](/ops/known-gaps) 단일 페이지에 누적되어 다른 세션이 "무엇부터" 가 안 보이던 문제 해소 — 시간축 4-페이지 분리:

- [`backlog`](/ops/backlog) (현재) — 실행 큐 lifecycle 🆕→📋→🔧→✅
- [`roadmap`](/ops/roadmap) (미래) — M1~M5 마일스톤 큰 그림
- **본 페이지** (과거) — Ship Log + Highlights + API feed
- [`known-gaps`](/ops/known-gaps) (사실) — 함정·미해결

또한 본일 후반 `/api/changes` JSON endpoint 신설 — `scripts/generate-changes-json.mjs` 가 build 시점 git log → `public/changes.json` export. `cache-control: s-maxage=60` 으로 ship 마다 60초 안에 fresh. LLM agent 가 `curl https://docs.axelabs.ai/api/changes?since=YYYY-MM-DD` 로 변경 fetch 가능. 본 endpoint 도입 중 두 추가 함정 발견: ⑤ `node:22-alpine` 의 `git` 바이너리 미포함 (apk add 필요) / ⑥ 같은 macmini 의 compose project 분리 시 container 이름 충돌 (`docker rm -f` cleanup 필요).

관련 결정: [D-docs-search-1](/ops/decisions), [D-docs-roadmap-1](/ops/decisions), [D-docs-updates-1](/ops/decisions).

### 2026-05-21 ~ 22 — frame 펀드 도메인 + Blueprint entity·PARA dispatch + hive payroll v2

- **frame 펀드 회계** ([D-ops-22](/ops/decisions)): `shared.entity` 에 `entity_kind` (corporate/kip/kvf) + `fund_meta` JSONB. AXEV 산하 KIP/KVF 조합 회계 처리 가능. K-IFRS 1110 통제 미달 (운용 관계 — parent-child 아님) 명시
- **Blueprint entity 도입** ([D-bp-entity-1](/ops/decisions), [PR #339](https://github.com/) + [#341](https://github.com/)): Workspace 에 `entityId` FK + `paraLayer` enum
- **PARA dispatch sub-consensus** ([D-bp-entity-2](/ops/decisions)): copy-with-provenance (sourceWorkspaceId/sourceArtifactPath/copiedAt). UI 는 PR 5 예정
- **sys entity 도입** ([D-bp-entity-3](/ops/decisions), [PR #344](https://github.com/) + [#345](https://github.com/)): `Workspace.entityId` nullable → NOT NULL. ad-hoc / 시스템 row 는 `sys` entity. General bucket 본질 제거
- **hive payroll v2** ([D-hive-21](/ops/decisions) ~ [D-hive-26](/ops/decisions) + [D-frame-1](/ops/decisions)): 한국 도메인 본질 7가지 (간이세액표 / 비과세 / 보수월액별 / 부양가족 / 정산 / 일할 / 보험별 라운딩). 분개 trigger = 실 거래 (matching principle) — D-frame-1 의 pending_payroll + match_pending_sweep 흐름
- **D-bp-alert-1**: Blueprint silent-drop L2 operator alert. AXE-native (Slack 폐기, `[OPERATOR-ALERT]` 마커 tail → macOS notification)

---

## API feed

LLM agent / 외부 시스템이 시간순 변경 사항을 JSON 으로 받는 endpoint:

```
GET /api/changes
GET /api/changes?since=2026-05-01
GET /api/changes?limit=20
GET /api/changes?since=2026-05-01&limit=50
```

응답 (예시):

```json
{
  "site": "https://docs.axelabs.ai",
  "since": "2026-05-01",
  "total": 5,
  "changes": [
    {
      "commit": "49dc3adb",
      "date": "2026-05-22T08:21:48+09:00",
      "subject": "docs(decisions): D-bp-entity-3 — General 제거 + sys entity (#344+#345)",
      "url": "https://docs.axelabs.ai/ops/decisions"
    }
  ]
}
```

`since` 는 ISO 8601 또는 YYYY-MM-DD. `limit` default 30, max 100.

본 endpoint 는 git log 기반 — `git log --format=...` 을 build 시점이 아닌 **request 시점** 에 실행. 캐싱 없음 (변경마다 즉시 반영).

LLM 사용 예: 다른 agent 가 자기 컨텍스트 갱신할 때 `curl https://docs.axelabs.ai/api/changes?since=$(date -v-7d +%Y-%m-%d)` 로 지난 7일 변경 fetch.

---

## 운영 ritual

### Phase 1 (현재) — 수동

매 `axe ship SERVICE` 후:

1. 본 페이지의 **Ship Log** 표에 한 줄 추가
   - 형식: `| 2026-MM-DD HH:MM | SERVICE | [SHORT-HASH](url) | COMMIT-SUBJECT |`
2. backlog 의 ✅ done 항목 검토 → 의미 있는 것은 본 페이지 **Highlights** 에 narrative 한 단락
3. 1-2 주에 한 번 — Ship Log 의 의미 있는 항목 묶어서 Highlights 갱신

### Phase 2 (계획) — 완전 자동

`axe ship` 의 post-deploy hook 이:
1. 본 페이지의 Ship Log 표 첫 행에 commit 정보 자동 append
2. backlog 의 `🔧 in-progress` 중 ship 한 service 의 related 항목을 ✅ done 으로 자동 이동
3. ✅ done 1주 후 본 페이지 Ship Log 로 자동 archive

구현 = [`B-axe-ship-update-hook`](/ops/backlog) (Phase 2).

## 본 페이지의 의도

[backlog](/ops/backlog) 와 [roadmap](/ops/roadmap) 은 "다음/미래" 의 시점. 본 페이지는 **이미 한 일** 의 정직 기록. 의도는 3 가지:

- **회고** — "지난 5번 ship 중 어디서 문제 났나" 운영자가 5초 안에
- **공유** — 직원·외부 IT 가 "최근 변경" Highlights 로 narrative 따라가기
- **자동 연동** — LLM agent 가 `/api/changes` 로 정기 polling

---

<!-- PAGE https://docs.axelabs.ai/partner -->

# 고객사 IT 가이드

> macmini 사전 준비 + Entra ID 앱 등록 + JSON pack 회신 — docs 만 보고 자력 완료.

URL: https://docs.axelabs.ai/partner

# 고객사 IT 가이드

본 가이드는 액스코퍼레이션 주식회사 (운영 주체, 자동화 계정 `ai@axellc.com`) 가 귀사의 macmini 에 frame · blueprint · vault stack 을 배포할 때, **귀사 IT 담당자가 자기 측에서 처리해야 하는 작업** 을 정리합니다.

> 🎯 **본 docs 만으로 자력 완료 가능**. 별도 첨부 / 별도 메시지 / 별도 스크립트 의존 없습니다. 도메인 + macmini 가 있고 docs.axelabs.ai 링크 받으셨으면, 아래 흐름 4 단계가 끝나면 D-day 운영자 push deploy 만 남습니다.

## 전체 작업 흐름 (Option A 권장 — 총 ~45분)

| # | 단계 | 소요 | docs |
|---|---|---|---|
| 1 | macmini 6 단계 사전 준비 (Tailscale + SSH + 절전 OFF + Docker) | 30분 | [macmini 사전 준비](/partner/macmini-prep) |
| 2 | `axelabs-bootstrap.sh` 다운로드 + `az login` + 1 줄 실행 → 3 app 자동 등록 + JSON pack 생성 | 5분 | [Entra ID 앱 등록 §Option A](/partner/registration#option-a--cli-1-줄-권장) |
| 3 | DNS 검증 (TXT 추가 — 대부분 운영자 측에서 자동) | 5분 | [DNS / 도메인 준비](/partner/domain-prep) |
| 4 | JSON pack 을 운영자에게 안전 채널 전달 | 5분 | [운영자에게 넘길 값](/partner/handoff) |

> Option A 가 어려운 환경 (Azure CLI 차단 등) 이면 portal 수작업 Option B (~40분 추가) — [registration §Option B](/partner/registration#option-b--portal-수작업-fallback-40분).

이후 D-day 는 운영자 측 [배포 협의](/partner/deploy) 참조.

## 사전 확인 사항

귀사의 Microsoft 365 tenant 정보 + 권한:

| 항목 | 확인 방법 |
|---|---|
| Tenant ID (GUID) | Azure portal → Microsoft Entra ID → Overview → Tenant ID |
| Global Admin 또는 App Admin 권한 보유자 | 인사·IT 담당자 (Option A 실행 시 본인) |
| 회사 메일 도메인 | 예: `realchoice.co.kr` (= primary verified domain) |
| 서비스 노출 domain | 예: `realchoice.axelabs.ai` (= 운영자 측 axelabs.ai 의 서브도메인) |
| `az` CLI 사용 가능 환경 | `az --version` 으로 확인 — Option A 권장 조건 |

## 보안 채널

`client_secret` 값은 평문 채팅 / 이메일 / Teams 첨부 **금지**. 권장:

- 1Password Send / Bitwarden Send (view-once)
- 회사 SSO 보호된 보안 메신저
- 직접 대면 / 전화 음성

운영자가 Keychain push 완료 후 안전 채널 메시지 삭제 (view-once 사용 권장).

## AXE 측 책임

- macmini 의 frame / blueprint / vault stack 배포 + 운영
- 백업 (3-tier: local + ring + cold SSD)
- 회계 데이터 무결성 검사 (매일 자동)
- 직원 onboarding 가이드 제공
- 사고 시 24시간 내 회신 + 복구

## 귀사 책임

- Microsoft Entra ID app 등록 + client_secret 발급
- 직원의 회사 메일 계정 발급 + Microsoft 365 권한 부여
- 직원 onboarding 후 사용 지원 (1차 helpdesk)
- 신규 직원 입사 시 운영자에게 entity 매핑 요청
- 퇴사 시 운영자에게 권한 회수 요청

## 다음 단계

[Microsoft Entra ID app 등록 가이드 →](/partner/registration)

---

<!-- PAGE https://docs.axelabs.ai/partner/deploy -->

# 배포 협의

> macmini 배포 일정 · 사전 요구사항 · D-day 작업.

URL: https://docs.axelabs.ai/partner/deploy

# 배포 협의

귀사 macmini 에 AXE Labs 스택을 배포하는 일정과 사전 요구사항.

## 사전 요구사항 (D-7)

| # | 항목 | 책임 |
|---|---|---|
| 1 | macmini 1대 (M2/M3, 16GB+ RAM, 512GB+ SSD) | 귀사 (구매) |
| 2 | 항상 켜진 상태 + 인터넷 안정 (유선 권장) | 귀사 |
| 3 | Tailscale 가입 + macmini 가 tailnet 에 합류 | 귀사 IT |
| 4 | 운영자의 Tailscale SSH key 허용 | 귀사 IT |
| 5 | Microsoft 365 tenant + 3개 app 등록 | 귀사 IT |
| 6 | `{customer}.axelabs.ai` 도메인 검증 | 귀사 IT + 액스코퍼레이션 주식회사 (DNS) |
| 7 | client_secret VALUE 안전 채널 전달 | 귀사 IT |

위 7 개 완료 = D-day 작업 진행 가능.

## D-day 작업 (운영자 측, 4시간)

운영자가 `axe onboard {customer} --apply` 실행. 18-step 자동화:

| Step | 작업 | 다운타임 |
|---|---|---|
| 1 | Tailscale status check | 0s |
| 2 | customer registry 확인 | 0s |
| 3 | SSH probe (macmini reachable?) | 0s |
| 4 | Cloudflare tunnel credential push | 0s |
| 5-9 | cloudflared launchd 설정 | 0s |
| 10 | frame docker preflight + git pull | ~30s |
| 11-16 | frame docker-compose bootstrap | ~5min (이미지 빌드) |
| 17 | health check | 0s |
| 18 | 운영자 알림 | — |

총 ~4시간 (이미지 빌드 + 첫 데이터 sync 포함).

## D+1 (검증)

- 운영자가 직접 첫 로그인 검증
- 귀사 admin 사용자 (`ADMIN_EMAIL`) 에게 권한 부여
- 검증 메일 발송

## D+2 ~ (운영)

- 귀사 직원 onboarding 시작
- 각자 [신규 직원 온보딩](/onboard) 따라 setup
- 1차 helpdesk = 귀사 IT (URL/secret 확인 등), 2차 = 운영자 (서버 측)

## 도입 후 귀사 macmini 의 실 컨테이너 구성

`axe onboard {customer} --apply` + `axe deploy blueprint/hive {customer}` 가 끝난 뒤 귀사 macmini 에 떠 있는 컨테이너 목록 (`docker ps` 결과 — `realchoice` 예시):

```
realchoice-macmini  (M2+, 16GB+, Tailscale 메시, 절전 OFF)
├ axelabs-realchoice-tunnel       (cloudflared, customer 별 독립 tunnel — origin 한 줄만)
├ frame-postgres :3700
├ frame-mcp-blue :3710 / frame-mcp-green :3711   (blue/green, 무중단 swap)
├ axe-frame-proxy :3712            (Caddy blue/green selector)         ⚠️ axe- prefix
├ frame-worker                      (cron + match_pending_sweep)
├ hive-postgres :3800
├ hive-mcp-blue :3810 / hive-mcp-green :3811     (blue/green)
├ axe-hive-proxy :3812             (Caddy blue/green selector)         ⚠️ axe- prefix
├ blueprint-postgres
├ blueprint-app :3100 + WebSocket :3101          (blue, dev/build 시 수십초 다운)
├ blueprint-app-green                              (passive, B-bp-bluegreen 후 활성)
├ blueprint-mcp-blue :3152 / blueprint-mcp-green :3153  (read-only MCP, blue/green)
├ stream-mcp :8780                                (귀사 기존 자산, manifest 정렬)
├ magnet-mcp :8770                                (귀사 기존 자산, manifest 정렬)
├ axe-vaultwarden                  (Vaultwarden core)                  ⚠️ axe- prefix
└ axe-vault-caddy :8222            (Vaultwarden front + OIDC)          ⚠️ axe- prefix
```

### 컨테이너 이름 컨벤션 — 정확히 무엇이 customer-aware 인가

| 패턴 | 예시 | customer 식별 |
|---|---|---|
| **customer-prefix 적용 (`axelabs-{customer}-...`)** | `axelabs-realchoice-tunnel` | ✅ — `axe onboard` (`_render_cloudflared_config`, `axe` CLI line 2829) 가 customer ID 박음. axe customer 는 `axelabs-axe-tunnel` 이 아니라 `axelabs-tunnel` (historical) |
| **customer-agnostic (`{service}-...`)** | `frame-postgres`, `hive-mcp-blue`, `blueprint-app`, `blueprint-mcp-green` | ✅ — customer-per-macmini 격리로 같은 host 에 다른 customer 가 없어 충돌 위험 0. macmini hostname (`realchoice-macmini`) 으로 식별 |
| **⚠️ historical `axe-` prefix 잔존** | `axe-frame-proxy`, `axe-hive-proxy`, `axe-vaultwarden`, `axe-vault-caddy` | ❌ — `frame/docker-compose.yml:197`, `hive/docker-compose.yml:124`, `vault/docker-compose.yml:29/66` 의 `container_name` 이 `axe-` 박혀 있음. **realchoice macmini 에서도 컨테이너 이름은 `axe-...`**. customer-per-macmini 격리상 충돌은 없지만 misleading. backlog 등재: [B-container-name-customer-prefix](/ops/backlog) |

⚠️ **즉 받은 도식의 `axe-frame-proxy` / `axe-vault-caddy` 가 "왜 axe-?"** 의문은 정확함 — 실제로 그 이름 그대로 떠 있는 게 맞음 (historical artifact). `axelabs-tunnel` 만 customer-prefix 누락 (이건 axe customer 전용 이름이라 realchoice 측은 `axelabs-realchoice-tunnel`).

향후 일반화는 [B-container-name-customer-prefix](/ops/backlog) — compose 의 `container_name` 을 `${CUSTOMER_PREFIX}-` 변수화. 실 운영 영향 없어 우선순위 中.

## 함정

### 사전 요구사항 단계 (D-7 ~ D-1)

| 함정 | 결과 | 회피 |
|---|---|---|
| Tailscale 미설치 | 운영자 push deploy 불가 | D-7 까지 설치 + key 등록 |
| macmini sleep 모드 | 새벽 backup 실패 | "절전 안 함" 설정 |
| 도메인 검증 누락 | Application ID URI 등록 거부 | 검증 후 app 등록 |
| client_secret 분실 | 재발급 + 운영자 측 swap | 회신 즉시 안전 보관 |

### D-day 18-step 자동화 단계 (2026-05-25 트루비아 측 발견 — B-vault-d-day-traps-2026-05-25 + B-onboard-d-day-traps-2026-05-25)

| 함정 | step | 증상 | 회피 |
|---|---|---|---|
| Private GitHub repo clone 인증 prompt | clone (step 10/11) | `axelabs-ai/frame` · `axelabs-ai/hive` clone 시 PAT prompt → SSH 자동 deploy hang | 운영자 임시 PAT 등록 후 customer 측 team add (D-dev-platform-2) |
| docker network `artemis_default` 사전 부재 | network create (pre step 11) | `external: true` declared network not found → compose up fail | `docker network create artemis_default` (`axe deploy` 의 `_svc_step_network` 빌트인 ✅, 2026-05-25 이후 자동) |
| Blueprint MCP app (4번째 Entra app) 등록 누락 | bootstrap.sh 또는 registry | App #4 미등록 → MCP OAuth 시 redirect 실패 | `bootstrap.sh` App #4 추가 (B-axelabs-bootstrap-blueprint-mcp-app 후속) |
| external volume 6개 (blueprint 측) 사전 부재 | docker compose up | `external: true` declared volume not found | compose 의 `external` 제거 또는 pre-step `docker volume create` (R6 후속) |
| `~/.axe/customers.yaml` 이 directory 로 잘못 사전 생성 | onboard step | file write fail | onboard step 의 `mkdir parent only` 정정 |
| ADMIN_TOKEN argon2 hash `$` interpolation | vault env_file (step 11) | compose v2 yaml expansion 으로 `$` segment 가 빈 값 — vault admin lockout | `$` → `$$` escape (`axe secret pull` 의 `escape_dollar` flag 빌트인 ✅) |
| Timshel vault image `wget` 없음 | compose healthcheck | `wget: command not found` → unhealthy 무한 루프 | healthcheck → `curl` 변경 |
| sso_nonce column 이름 (`code_verifier` → `verifier`) | vault recovery SQL | column not found | runbook 정정 ✅ (PostgreSQL/SQLite backend 분기) |
| bw CLI 2026.4+ Timshel SSO 호환성 | partner setup (bw login) | "Master password unlock data was not found" | bw 2025.7.0 pin: `npm install -g @bitwarden/cli@2025.7.0` (또는 axe.2 patch 적용 vault image) |
| bw data dir keychain restore | bw login | `rm -rf "~/.config/Bitwarden CLI/"` 후에도 옛 session 잔존 (macOS Keychain) | `BITWARDENCLI_APPDATA_DIR=$HOME/.bw-axe-customer` 로 fresh isolated dir |
| Caddyfile `/vault` no trailing slash | vault access (step 17 health check) | SPA HTML relative path 가 root 옆 resolve → asset 503 | `/vault` → `/vault/` permanent redirect (Caddy path-only destination trailing slash strip 함정) |

## Vault OIDC SSO 통합 — 기존 Vaultwarden 운영 중인 customer 용

귀사가 이미 [`soohunkang/vault`](https://github.com/soohunkang/vault) repo (운영자 측 vault platform) 또는 자체 fork 의 Vaultwarden 인스턴스를 운영 중이고 그것을 그대로 유지하기로 결정한 경우 (= RE^2 의 Q3 (a) 채택), `axec stack 의 별도 axe-vaultwarden 신설을 skip` 하고 기존 vault 에 OIDC SSO 만 추가합니다. 본 절은 그 통합 절차.

### 책임 분담

| 작업 | 누가 |
|---|---|
| `~/vault` repo / compose.yaml / env_file 의 OIDC env 추가 + force-recreate | **귀사 IT** (vault 운영 책임) |
| client_secret view-once URL 발사 | **운영자** (`axe secret send`) |
| cloudflared ingress 의 `/vault` path 를 503 placeholder → vault-caddy 호스트 포트로 변경 | **운영자** (axelabs.ai zone tunnel 운영 책임) |
| Vault Organization 생성 + 첫 admin invite | **귀사 admin** (web UI) |

### 절차 (양측 협업, ~30 분)

**1. 운영자 — client_secret view-once URL 발사**

```bash
axe secret send AZURE_{CUSTOMER_UP}_VAULTWARDEN_CLIENT_SECRET --service vault --customer {customer} --days 1 --access 1
```

귀사가 URL 받으면 1 회만 열어서 secret 값 캡처 후 즉시 안전 보관.

**2. 귀사 IT — `~/vault/` 의 env_file (또는 compose.yaml `environment:` 영역) 에 다음 12 key 추가/변경**

먼저 현 vault 의 secrets 보관 위치 확인:

```bash
cd ~/vault
grep -E 'env_file|environment:' compose.yaml | head -5
```

`env_file: ./vault.env` (또는 비슷한 경로) 가 보이면 그 파일 편집. compose.yaml `environment:` 블록 inline 도 가능.

추가/변경할 12 key (기존 SIGNUPS_ALLOWED 가 false 면 true 로 변경):

```bash
# === DOMAIN — axec stack 가 사용할 외부 URL (cloudflared ingress) ===
DOMAIN: "https://{customer}.axelabs.ai/vault"   # 기존 Tailscale FQDN 이면 변경

# === OIDC RP — Microsoft Entra ID ===
SSO_ENABLED: "true"
SSO_ONLY: "false"
SSO_AUTHORITY: "https://login.microsoftonline.com/{TENANT_ID}/v2.0"
SSO_CLIENT_ID: "{vaultwarden_client_id}"
SSO_CLIENT_SECRET: "{받은 secret 값}"
SSO_SCOPES: "openid profile email offline_access"
SSO_DEBUG_TOKENS: "false"

# === 4-block: 첫 employee 가입 차단 회피 (D-ops-24/26/27) ===
SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "true"
SSO_SIGNUPS_MATCH_EMAIL: "true"
SIGNUPS_ALLOWED: "true"                       # 기존 false 면 변경 필수
ORGANIZATION_INVITE_AUTO_ACCEPT: "true"
```

placeholder 4:
- `{TENANT_ID}` = `axelabs-bootstrap-{customer}.json` 의 `tenant_id`
- `{vaultwarden_client_id}` = 동일 JSON 의 `apps.vaultwarden.client_id`
- `{받은 secret 값}` = step 1 view-once URL
- `{customer}` / `{CUSTOMER_UP}` = customer id / 대문자

**3. 귀사 IT — force-recreate**

```bash
cd ~/vault
docker compose up -d --force-recreate vault-app   # 또는 vaultwarden / 본인 컨테이너명
```

**4. 운영자 — cloudflared ingress 의 `/vault` path 를 vault-caddy 로 라우팅**

운영자가 customer macmini 의 `~/.cloudflared/config.yml` 의 `/vault` block 을 503 placeholder → vault-caddy 의 host port (트루비아 vault-caddy 는 보통 `:8222`, HTTPS 는 `:8443`) 로 변경 후 cloudflared 재시작. 본 step 은 customer 측 추가 작업 없음.

**5. 검증 — SSO 직링크**

```
https://{customer}.axelabs.ai/vault/#/sso
```

웹 UI 에 SSO Identifier 입력 화면이 나오면 OK. Identifier = 운영자 측이 customer 별 명명 (예: `REALCHOICE` 대문자 권장 — Bitwarden Send 본문에 명시).

### 첫 employee 시점 — Vault Organization + invite (D-ops-32)

귀사 admin 이 SSO 로 첫 로그인 후 web vault 의 Admin Console:

1. **Organization 생성** — 이름 = `{CUSTOMER_UP}` 대문자 (예: `REALCHOICE`)
2. **Collection 4 개 신설** (D-ops-32 v1):
   - `Platform — Service Secrets` (operator only)
   - `Platform — Infrastructure` (operator only)
   - `{Customer Entity}` (전직원 RW)
   - `Shared Tools` (전직원 RW)
3. **직원 invite** — 기존 운영자 측 `invite-members.sh` 패턴 또는 web UI 직접
4. **dual-identity 권장** (D-ops-29) — admin 직원 별도 `ai@{customer-domain}` (automation) + 실제 사람 계정 2 identity 둘 다 Owner

### 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| `SSO_ONLY: "true"` 설정 | Entra 장애 시 운영자 lockout (master password 진입 불가) | `false` 유지 (D-ops-27) |
| `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION: "false"` (Timshel default) | 첫 employee SSO "Your provider does not send email verification status" 차단 | `true` 명시 (D-ops-24) |
| `SIGNUPS_ALLOWED: "false"` | 첫 employee JIT signup "Failed to retrieve the invitation" 차단 | `true` (D-ops-26) |
| Vault UI 이메일-first 화면이 SSO Identifier 가림 | 직원이 가입 절차 못 찾음 | `/vault/#/sso` 직링크 안내 |
| client_secret 평문 메일 전송 | 영구 보관 노출 | view-once URL (axe secret send) |
| Vaultwarden Timshel 1.34.1-6 + bw CLI 2026.x | `TypeError: toWrappedAccountCryptographicState` crash | bw CLI 2025.7.0 pin (`npm install -g @bitwarden/cli@2025.7.0`) |

상세 결정 근거: [auth.mdx](/architecture/auth) · [D-ops-24](/ops/decisions#d-ops-24) · [D-ops-26](/ops/decisions#d-ops-26) · [D-ops-27](/ops/decisions#d-ops-27) · [D-ops-29](/ops/decisions#d-ops-29) · [D-ops-32](/ops/decisions#d-ops-32).

## 정기 점검

| 주기 | 작업 |
|---|---|
| 매일 | 자동 backup + integrity check (운영자 측) |
| 매주 | 운영자 → 귀사 IT health report |
| 매월 | secret 만료 30일 전 알림 (운영자 → 귀사) |
| 분기 | Restore drill (운영자 측 자동) |
| 연 1회 | 보안 감사 협의 |

## 종료/이전 시

귀사가 AXE Labs 서비스 종료 결정 시:

1. 데이터 export (frame DB dump + Vaultwarden export + Blueprint Workspaces)
2. cold storage SSD 1개 사본 귀사에 인도
3. macmini 의 AXE Labs 컨테이너 제거
4. Microsoft Entra ID 의 3개 app 비활성화 (귀사 측)
5. axelabs.ai zone 의 `{customer}` record 제거 (운영자 측)
6. customers.yaml 의 entry 제거 (운영자 측)

데이터 보관 정책: export 후 자체 보관. AXE Labs 측 백업은 종료 +90일 후 폐기.

---

<!-- PAGE https://docs.axelabs.ai/partner/domain-prep -->

# DNS / 도메인 준비

> Microsoft Entra ID 에서 https:// 형식 Application ID URI 사용을 위한 도메인 검증.

URL: https://docs.axelabs.ai/partner/domain-prep

# DNS / 도메인 준비

Frame MCP app 의 Application ID URI 를 `https://{customer}.axelabs.ai/frame/mcp` 형식으로 등록하려면, **귀사 tenant 에 해당 도메인을 검증** 해야 합니다.

## 왜 검증이 필요한가

Microsoft Entra ID 의 보안 정책:

- **`api://...` 형식**: 검증 불필요 (임의 문자열 허용)
- **`https://...` 형식**: 도메인 검증 필수 (도메인 소유 증명)

`https://` 형식이 필요한 이유:
- Anthropic Claude 가 `resource` 파라미터로 MCP server URL (`https://...`) 을 그대로 사용
- Microsoft 가 `resource` 와 `scope` 의 URI prefix 일치 검사 (AADSTS9010010)
- → Application ID URI 도 `https://` 로 통일해야 prefix 일치

## Zone 책임 모델 (먼저 확인)

| 도메인 | Zone 소유자 | 누가 TXT 추가 |
|---|---|---|
| `{customer}.axelabs.ai` (서비스 노출용, 예: `realchoice.axelabs.ai`) | **액스코퍼레이션 주식회사 (운영 주체)** | **운영자가 추가** — 귀사 IT 는 안내 메시지만 전달 |
| 귀사 corporate domain (예: `realchoice.co.kr`) | **귀사 IT** (Cloudflare / Route53 / 가비아 등) | **귀사 IT 직접** (Microsoft 365 verified domain 등록 시) |

본 페이지는 **두 경로 다** 다룹니다. 둘 중 어느 쪽이 필요한지 운영자와 확인 후 진행.

> ⚠️ Microsoft Entra ID 의 Application ID URI 검증에는 `{customer}.axelabs.ai` 만 충분 (Frame MCP app 의 `https://{customer}.axelabs.ai/frame/mcp`). 코퍼레이트 도메인은 SSO 사용자 식별 (이메일 verified) 용도이며, M365 tenant 가 이미 가지고 있을 확률이 높음 — 기 검증 상태면 본 페이지 §B 는 skip.

---

## A. `{customer}.axelabs.ai` 검증 — 운영자 처리, 귀사 IT 1 분

이 도메인 zone (`axelabs.ai`) 은 운영 주체 (액스코퍼레이션 주식회사) 가 Cloudflare 에서 관리합니다. 귀사 IT 는 다음만 하면 됩니다.

### A-1. Azure 에서 도메인 추가

Azure portal → **Microsoft Entra ID** → **Custom domain names** → **+ Add custom domain**

1. 입력: `{customer}.axelabs.ai` (예: `realchoice.axelabs.ai`)
2. **Add**
3. Microsoft 가 화면에 TXT record 표시:
   ```
   Type:  TXT
   Name:  @
   Value: MS=ms<숫자>   (예: MS=ms10433167)
   TTL:   3600
   ```

### A-2. 운영자에게 한 줄 전달

평문 메일 / Teams 채팅 등 어떤 채널이라도 가능 (TXT 값은 비밀 아님):

```
운영자께,
axelabs.ai zone 의 realchoice 서브도메인에 다음 TXT 추가 부탁드립니다 (M365 tenant 검증용):
  Type:  TXT
  Name:  realchoice         ← @ 아님, customer ID
  Value: MS=ms10433167      ← Azure 가 표시한 값
운영자가 추가 후 알려주시면 Verify 클릭하겠습니다. — {customer} IT
```

운영자가 Cloudflare API (`POST /zones/{ZONE_ID}/dns_records`) 로 추가 (~30초). 운영자가 "추가됨" 회신.

### A-3. propagation 확인 (귀사 IT)

운영자 회신 후:

```bash
dig +short TXT {customer}.axelabs.ai @1.1.1.1
# 예상: "MS=ms10433167"
```

1~5 분 소요. 비어 있으면 좀 더 대기.

### A-4. Azure 에서 Verify

Azure portal 의 Custom domain names 페이지 → 추가한 도메인 → **Verify** 클릭. ✓ "Verified" 표시되면 완료.

---

## B. 귀사 corporate domain 을 M365 verified domain 으로 추가 (선택)

귀사 M365 tenant 가 `{customer}.onmicrosoft.com` 만 가지고 있고 회사 도메인 (예: `realchoice.co.kr`) 이 아직 verified 가 아닌 경우 — 직원 이메일 (`first.last@realchoice.co.kr`) 로 SSO 로그인하기 위해 필요.

이 작업은 **귀사 zone (귀사 DNS provider) 에서 귀사 IT 가 직접** 추가합니다.

### B-1. Azure 에서 도메인 추가

Azure portal → **Microsoft Entra ID** → **Custom domain names** → **+ Add custom domain**

1. 입력: `realchoice.co.kr`
2. **Add** → Microsoft 가 TXT record 표시:
   ```
   Type:  TXT
   Name:  @
   Value: MS=ms<숫자>
   ```

### B-2. 귀사 DNS provider 에 TXT 추가

귀사가 Cloudflare 를 쓴다고 가정 (다른 provider 도 동일 개념):

| 필드 | 값 |
|---|---|
| Type | TXT |
| Name | `@` (zone root — Cloudflare 는 zone 이름 자동 채움) |
| Content | `MS=ms<숫자>` |
| TTL | Auto |
| Proxy status | DNS only |

Route53 / 가비아 / 후이즈 등 다른 provider 도 root TXT 로 동일.

### B-3. propagation + Verify

```bash
dig +short TXT realchoice.co.kr @1.1.1.1
```

OK 면 Azure 측 **Verify** 클릭.

## 검증 후 Application ID URI 등록

이제 Frame MCP app 의 Expose an API 탭에서:

```
Application ID URI: https://{customer}.axelabs.ai/frame/mcp
```

Azure 가 검증된 도메인으로 인식하여 허용. [Frame MCP 등록 §3-3](/partner/registration#3-3-expose-an-api) 계속.

## DNS record 종합 (참고)

운영자 측 (axelabs.ai zone) 에 자동 등록되는 record 들 (`axe onboard` 의 step 4~5 가 Cloudflare API 호출):

| Type | Name | Content | 용도 |
|---|---|---|---|
| CNAME | `{customer}` | `<tunnel-uuid>.cfargotunnel.com` | 트래픽 라우팅 (cloudflared tunnel) |
| TXT | `{customer}` | `MS=ms<숫자>` | Microsoft 도메인 검증 (§A) |

귀사 corporate domain (예: `realchoice.co.kr`) 은 별도 zone — §B 에서 처리 (또는 이미 verified 상태일 가능성).

## 함정

§A (`{customer}.axelabs.ai` — 운영자 측):

| 함정 | 결과 | 회피 |
|---|---|---|
| customer 가 운영자에게 안 알리고 zone 직접 만지려 함 | 권한 없어 실패 | §A-2 — 운영자에게 한 줄 전달 |
| propagation 대기 안 함 (즉시 verify) | Microsoft 가 TXT 못 찾음 | 1~5 분 대기 후 verify |

§B (귀사 corporate domain — 귀사 측):

| 함정 | 결과 | 회피 |
|---|---|---|
| Cloudflare Proxy status orange-cloud | TXT lookup 차단 | DNS only (회색 구름) |
| `@` 외에 다른 Name (`mail`, `www` 등) | zone root 가 아니라 서브에 붙음 | `@` 사용 |
| 가비아 / 후이즈에서 TXT @ 입력 시 호스트명 빈칸 처리 | record 가 등록되지 않음 | provider 별 매뉴얼 확인 (대개 빈칸 = root) |
| M365 tenant 가 이미 같은 도메인 verified — 중복 추가 | "domain already exists" 오류 | tenant 의 Custom domain names 에서 기 등록 여부 사전 확인 |

다음: [운영자에게 넘길 값](/partner/handoff) →

---

<!-- PAGE https://docs.axelabs.ai/partner/handoff -->

# 운영자에게 넘길 값

> JSON pack (Option A 출력물) 또는 8 개 값 (Option B 수작업) 회신 + 안전 채널.

URL: https://docs.axelabs.ai/partner/handoff

# 운영자에게 넘길 값

[Microsoft Entra ID 앱 등록](/partner/registration) + [DNS 준비](/partner/domain-prep) 완료 후, **귀사 IT 가 채택한 옵션에 따라** 운영자 (`ai@axellc.com`) 에게 전달합니다.

| 옵션 | 회신 형식 | 채널 |
|---|---|---|
| **Option A (CLI 1줄, 권장)** | `axelabs-bootstrap-{customer}.json` 파일 1 개 | 1Password Send / Bitwarden Send (view-once) |
| **Option B (portal 수작업)** | 아래 [텍스트 템플릿](#option-b--텍스트-템플릿) 8 개 값 | 동일 안전 채널 (한 메시지에 통합) |

운영자가 ingest 완료 후 알림 보내드리면, 안전 채널 메시지를 즉시 삭제해 주세요.

## ⚠️ 구 docs 폐기 안내

이전 버전 (`realchoice_entra_id_setup_v2.md` 등) 은 **Mobile/desktop platform + `http://localhost` + secret 없음** 모델 기반이었습니다. 본 가이드 (registration.mdx 신모델) 가 정본 — **Web platform + 도메인 검증된 App ID URI + `mcp.access` scope + client_secret 발급**.

구 docs 가 검색에 잡히면 무시하시고 본 페이지 + [registration](/partner/registration) + [domain-prep](/partner/domain-prep) 만 따라주세요.

---

## Option A — JSON pack 회신 (권장)

[registration §Option A](/partner/registration#option-a--cli-1-줄-권장) 의 `axelabs-bootstrap.sh` 가 만든 파일:

```
axelabs-bootstrap-<customer_id>.json
```

이 파일을 **수정하지 말고 그대로** 첨부 (1Password Send / Bitwarden Send 의 file attachment). 안에 8 개 값 + scope/redirect_uri/application_id_uri 모두 포함되어 운영자가 `axe customer ingest <customer> <file>` 으로 1 줄에 vault push + customers.yaml 갱신.

스키마 (`axelabs-bootstrap/v1`) 예시:

```json
{
  "schema": "axelabs-bootstrap/v1",
  "customer": "realchoice",
  "public_domain": "realchoice.axelabs.ai",
  "tenant_id": "00000000-0000-0000-0000-000000000000",
  "generated_by": "it.admin@realchoice.co.kr",
  "apps": {
    "blueprint":   { "client_id": "...", "client_secret": "..." },
    "vaultwarden": { "client_id": "...", "client_secret": "..." },
    "frame_mcp": {
      "client_id": "...",
      "client_secret": "...",
      "application_id_uri": "https://realchoice.axelabs.ai/frame/mcp",
      "scope": "mcp.access",
      "redirect_uris": [
        "https://claude.ai/api/mcp/auth_callback",
        "https://claude.com/api/mcp/auth_callback"
      ]
    }
  }
}
```

추가로 한 줄 회신 (메일 본문 — secret 없음):

```
Option A 로 axelabs-bootstrap-realchoice.json 생성 완료.
첨부는 [Bitwarden Send link, view-once 1 회 + 24h 만료] 입니다.
ADMIN_EMAIL:  admin@realchoice.co.kr
SENDER_EMAIL: it.admin@realchoice.co.kr
— 리얼초이스 IT
```

`ADMIN_EMAIL` (첫 Blueprint admin) 과 `SENDER_EMAIL` (회신자) 은 JSON pack 에 없는 메타 — 메일 본문에 추가.

---

## Option B — 텍스트 템플릿 (수작업 시)

```
TENANT_ID:                  <Directory (tenant) ID>

BLUEPRINT_CLIENT_ID:        <App #1 Application (client) ID>
BLUEPRINT_CLIENT_SECRET:    <App #1 Client secret VALUE>

VAULTWARDEN_CLIENT_ID:      <App #2 Application (client) ID>
VAULTWARDEN_CLIENT_SECRET:  <App #2 Client secret VALUE>

FRAME_MCP_CLIENT_ID:        <App #3 Application (client) ID>
FRAME_MCP_CLIENT_SECRET:    <App #3 Client secret VALUE>

ADMIN_EMAIL:                <첫 Blueprint admin 으로 지정할 사용자 메일>
SENDER_EMAIL:               <회신 보낸 분 메일 (확인 회신용)>
```

## 안전 채널 권장 (필수)

`*_CLIENT_SECRET` 평문은 다음 경로 **금지**:

- ❌ 일반 이메일 (백업·archiving 영구 보관)
- ❌ Slack/Teams 채팅 (스레드 영구)
- ❌ 첨부 파일 (메일 서버 캐시)

권장:

- ✅ **1Password Send** (view-once 옵션 활성화)
- ✅ **Bitwarden Send** (만료 + view-once)
- ✅ 회사 SSO 보호된 보안 메신저
- ✅ 직접 대면 / 음성 통화

운영자가 Keychain push 완료 통지를 보낸 직후, 안전 채널 메시지를 삭제하시기 바랍니다.

## CLIENT_ID 는 평문 무방

`*_CLIENT_ID` 는 GUID 식별자로 비밀이 아닙니다. 이메일 평문 전송 가능. SECRET 만 안전 채널.

## 운영자 측 처리

운영자가 회신 받은 후 ([customer-onboarding D-day TLDR](/ops/runbook/customer-onboarding#d-day-tldr--운영자-수동-touchpoints) 참조):

| 작업 | 명령 (2026-05-23 시점) | 시점 |
|---|---|---|
| 1. customers.yaml 에 client_id + tenant_id 채워넣기 + services 슬롯 등재 | 현재 수동 ([B-onboard-customers-add](/ops/backlog) 자동화 예정) | 회신 즉시 |
| 2. 3 개 client_secret → Vaultwarden push | `axe secret push AZURE_..._CLIENT_SECRET --service {svc} --customer {customer}` × 3 | 회신 즉시 |
| 3. Cloudflare tunnel + frame stack 부트 | `axe onboard {customer} --apply` | 회신 당일 |
| 4. Blueprint stack 부트 | `axe deploy blueprint {customer} --apply` | 회신 당일 |
| 5. 첫 로그인 검증 + admin 권한 부여 | Blueprint 첫 SSO 로그인 후 `UPDATE User SET role='admin' WHERE email='...'` | 1일 내 |
| 6. 직원 onboarding 가이드 전달 | [신규 직원 onboarding](/onboard) URL | 1일 내 |

## 기존 Vaultwarden 운영 중인 경우

귀사가 이미 Vaultwarden / Timshel fork 를 운영 중이고 그것을 유지하기로 결정 시 — axec stack 의 신규 `axe-vaultwarden` 신설을 skip 하고 기존 vault 에 OIDC SSO 만 추가합니다. 절차는 [배포 협의 §Vault OIDC SSO 통합](/partner/deploy#vault-oidc-sso-통합--기존-vaultwarden-운영-중인-customer-용) 참조 (11 key env + 4-block + view-once secret 전달).

## 만료·회전 정책

| Secret | 기본 만료 | 회전 시점 |
|---|---|---|
| Blueprint | 180일 | 만료 30일 전 |
| Vaultwarden | 180일 | 만료 30일 전 |
| Frame MCP | 24개월 | 만료 60일 전 |

만료 30일 전 운영자가 귀사 IT 에게 새 secret 요청 → 받아서 swap. 직원 측은 영향 없음 (claude.ai 측 캐시 자동 갱신).

## 신규 직원 추가 시

배포 후 신규 직원 (entity 권한) 추가:

1. 귀사 측 Microsoft 365 에서 회사 메일 발급 + tenant 활성 사용자 등록
2. 운영자에게 알림:
   ```
   신규 직원: firstname.lastname@{customer}.com
   업무: 회계
   필요 권한: axec read+write
   ```
3. 운영자가 `customers.yaml > user_entity_map` 에 추가 + 컨테이너 재기동

추가 후 직원은 [신규 직원 온보딩](/onboard) 따라 본인 setup.

## 퇴사 시

1. 귀사 측 Microsoft 365 에서 사용자 비활성 (그것만으로도 모든 access 차단됨 — Entra ID 측 검증 통과 못 함)
2. 운영자에게 알림 → `user_entity_map` 에서 제거 + 마지막 활동 audit log 보관

---

<!-- PAGE https://docs.axelabs.ai/partner/macmini-existing -->

# 기존 운영 macmini → customer 전환

> 이미 운영 중인 operator-grade macmini (axe stack live) 를 customer-served host 로 전환 — customers.yaml entry + vault collection + tunnel route + container 식별만 바뀐다.

URL: https://docs.axelabs.ai/partner/macmini-existing

# 기존 운영 macmini → customer 전환

표준 onboarding ([/partner](/partner) → [/partner/macmini-prep](/partner/macmini-prep)) 은 **신품 macmini** 를 전제로 한다 (D-7 절전 OFF + Tailscale 합류 + Docker 설치부터). 본 페이지는 다른 출발점 — **운영자가 이미 띄워 운영 중인 macmini** (예: `axe` stack 이 live 인 operator-grade 박스, 또는 사전 셋업을 끝낸 staging 박스) 에 **새 customer 신원을 얹어 customer-served host 로 전환**하는 경우를 다룬다.

> 🎯 핵심: 하드웨어·OS·Docker·Tailscale 은 **이미 준비됐다**. 따라서 표준 흐름의 인프라 prep (macmini-prep 6단계) 은 건너뛰고, **논리 식별 4가지만 바뀐다** — ① `customers.yaml` entry, ② vault organization/collection, ③ cloudflared tunnel route, ④ container 식별 (실제 rename 은 아직 없음 — 아래 참조). 그 위에 customer-scoped service stack 을 `axe deploy` 로 올린다.

## 언제 이 경로인가

| 상황 | 이 페이지 적용 |
|---|---|
| 운영자가 자기 `axe` stack 돌리던 박스를 customer 에게 인계 (이관) | ✅ |
| 사전에 운영자가 prep 끝낸 staging macmini 를 customer 용으로 승격 | ✅ |
| 운영자 박스에 customer 의 추가 service (stream/magnet 류) 만 co-tenant | ✅ (부분 — § 부분 전환) |
| 완전 신품 macmini, customer IT 가 직접 prep | ❌ → [표준 onboarding](/partner) |
| customer 가 자기 Vaultwarden 을 이미 운영 중 (vault 유지) | ❌ → [/partner/deploy § Vault OIDC SSO 통합](/partner/deploy#vault-oidc-sso-통합--기존-vaultwarden-운영-중인-customer-용) |

> ⚠️ AXE 의 격리 모델은 **customer-per-macmini** 다 ([/architecture/secrets § 컨테이너 이름 컨벤션](/architecture/secrets)). 같은 host 에 서로 다른 customer 둘을 영구 co-tenant 하는 것은 표준이 아니다 — 컨테이너 이름이 아직 customer-prefix 가 아니라 (`frame-postgres` 등 고정명) 두 customer 의 frame stack 이 같은 박스에서 포트·이름 충돌한다. 따라서 "전환" 의 정상 종착지는 **그 박스가 한 customer 의 host 가 되는 것** (operator `axe` 신원에서 customer 신원으로 소유 이전), 단일 host 에 영구 다중 customer 가 아니다.

## 무엇이 바뀌는가 (4가지)

### ① customers.yaml entry

운영자 macmini 는 `axe` customer 로 동작한다 — axe CLI 의 `is_local = (customer_id == "axe")` 분기가 이 박스를 **local exec** (SSH 없이 직접) 로 다룬다. customer 로 전환하면 그 박스는 더 이상 `axe` local-exec 호스트가 아니라 **별도 customer entry** 가 되고, axe CLI 가 Tailscale SSH 로 접근한다.

1. customers.yaml 에 customer 블록 추가 (stub 은 `axe customers add {cid}`):

```yaml
{customer}:
  legal_name: "<법인명>"
  primary_domain: "<회사 도메인>"
  public_domain: "{customer}.axelabs.ai"
  entities: ["<entity_id>"]
  tailscale_host: "{customer}-macmini"   # 이미 가입돼 있으면 현 hostname
  ssh_user: "<현 macOS 사용자명>"          # 기존 박스의 실제 user (axe 가 아니면 명시)
  sso:
    provider: "microsoft_entra_id"
    tenant_id: "<...>"
    apps: { blueprint: {...}, vaultwarden: {...}, frame_mcp: {...} }
  services:
    frame:      { env_file: "/Users/<user>/frame/.env.local", secrets: [...] }
    blueprint:  { env_file: "/Users/<user>/blueprint/.env",   secrets: [...] }
    hive:       { env_file: "/Users/<user>/hive/.env.local",  secrets: [...] }
    vaultwarden:{ env_file: "/Users/<user>/.axe/vault/.env", bootstrap_only: true }
  onboarded: "<date>"
```

전체 entry 스키마 (sso.apps + 각 service secrets[]) 는 [/ops/runbook/customer-onboarding § D-7](/ops/runbook/customer-onboarding) 와 동일하다. customer IT 가 Entra app 3개를 새로 등록 (`axelabs-bootstrap.sh`) 해서 JSON pack 을 회신하면 `axe customers ingest {cid} <pack>.json --apply` 가 sso 블록 + client_secret 3개 vault push 를 한 번에 흡수한다 ([/partner/registration](/partner/registration), [/partner/handoff](/partner/handoff)).

> **핵심 차이**: 기존 운영 박스는 `axe` 신원으로 컨테이너가 이미 돌고 데이터가 들어있을 수 있다. customer 로 전환하면 그 데이터의 소유·접근 경계가 customer org 로 옮겨간다. 운영 중 frame/hive 회계·HR 데이터가 `axe` 법인 것이면 customer 박스로 넘기기 전에 **반드시 분리/정리** (customer 의 host 에 운영자 법인 데이터가 남지 않도록). 이건 코드가 자동으로 못 한다 — 운영자 판단.

### ② vault organization / collection

운영자 vault (`/Users/axe/.axe/vault/`) 의 AXE org (`0c5d8bbd-...`) 는 **운영자 자신의** 비밀을 담는다. customer 박스는 자기 Vaultwarden 인스턴스 + 자기 org 를 가져야 한다 (customer sovereignty). 전환 시:

- 그 박스의 `axe-vaultwarden` 이 **customer 의 org** 를 호스트하도록 한다 — 운영자 org 데이터를 customer 박스에 남기지 않는다.
- customer org 생성 + collection 구조 v1 ([D-ops-32](/ops/decisions)):
  - entity 1개 customer: 4-collection (`Platform — Service Secrets` / `Platform — Infrastructure` (operator only) · `{Customer Entity}` / `Shared Tools` (전직원 RW))
- dual-identity 계정 ([D-ops-29](/ops/decisions)): `ai@{customer-domain}` (bot) + 사람 admin, 둘 다 Owner + access_all.
- vault env 4-key 패치 (JIT 가입 차단 회피) — `axe vault bootstrap {customer} --apply` 가 SSH 로 customer macmini 의 `docker-compose.yml` 에 in-place 적용 + force-recreate ([D-ops-24/26/27](/ops/decisions), [D-ops-33](/ops/decisions)).

서비스 비밀 흐름 자체는 동일 — `customers.yaml services.<svc>.secrets[]` → `axe secret push` → customer vault org → `axe secret pull <svc> --customer {cid}` → env_file. 단 vault item 네이밍의 customer 세그먼트가 `axe` → `{customer}` 로 바뀐다 (`frame/axe/db-password` → `frame/{customer}/db-password`). 상세 = [/services/vaultwarden](/services/vaultwarden) + [/architecture/secrets](/architecture/secrets).

### ③ cloudflared tunnel route

운영자 박스의 tunnel 은 `axelabs-tunnel` (historical 명, customer infix 없음 — `axe` 전용) 이고 docs.axelabs.ai / admin.axelabs.ai 등 **운영자 자기 서비스** 를 서빙한다 ([axe CLI `TUNNEL_NAME_FMT = "axelabs-{customer}"`](/architecture/secrets), `axe` 는 예외적으로 infix 생략).

customer 로 전환하면 그 박스는 **자기 customer tunnel** 을 가진다:

- `axe onboard {customer} --apply` 가 customer macmini 에 **독립 tunnel** (`axelabs-{customer}-tunnel`) 을 생성 + launchd 등록 + boot 한다 (`_render_cloudflared_config`). 중앙 tunnel 편집은 불필요 — [2026-05-23 drift 정정](/ops/known-gaps).
- ingress route 는 `{customer}.axelabs.ai` 의 path 들 (`/`, `/vault`, `/frame/mcp`, `/blueprint`, `/hive/mcp`) 을 host 내부 포트로 매핑.
- Cloudflare DNS 의 `{customer}` CNAME (`<tunnel-uuid>.cfargotunnel.com`) 은 `axe onboard` step 5 가 API 로 자동 생성.

> 즉 운영자 박스가 `axelabs-tunnel` 로 운영자 도메인을 서빙하던 것에서, customer 박스는 `axelabs-{customer}-tunnel` 로 `{customer}.axelabs.ai` 를 서빙한다. 한 박스를 인계하는 전환이면 운영자 tunnel/launchd 를 그 박스에서 **제거**하고 customer tunnel 만 남긴다.

### ④ container 식별 — 실제 rename 은 아직 없음

여기가 가장 오해하기 쉬운 부분이다. **컨테이너 이름은 customer 와 무관하게 고정**이다:

| 패턴 | 예시 | customer 식별 방식 |
|---|---|---|
| customer-agnostic (service-prefixed) | `frame-postgres`, `frame-mcp-blue`, `hive-mcp-blue`, `blueprint-app` | host (macmini hostname) 로 식별. customer-per-macmini 격리라 같은 host 에 다른 customer 없음 → 충돌 0 |
| historical `axe-` prefix 잔존 | `axe-frame-proxy`, `axe-hive-proxy`, `axe-vaultwarden`, `axe-vault-caddy` | compose 의 `container_name` 이 `axe-` 박혀 있음 — **customer 박스에서도 이름은 `axe-...`** (misleading 하지만 동작엔 무해) |
| customer-prefix 적용 | `axelabs-{customer}-tunnel` (cloudflared) | ✅ 유일하게 customer ID 가 들어가는 것 = tunnel |

즉 전환해도 frame/hive/blueprint 컨테이너 이름은 안 바뀐다 (`frame-postgres` 그대로). **변수화는 backlog** ([B-container-name-customer-prefix](/ops/backlog), compose `container_name` 을 `${CUSTOMER_PREFIX}-` 로 — 실 운영 영향 없어 우선순위 中). 그래서 "container prefix 변경" 이라기보다 **container 의 소유 host 가 바뀌는 것** 으로 이해해야 한다.

## 전환 절차

전제: vault session 살아있음 (`bw unlock` 8h cache, [Phase A](/ops/runbook/customer-onboarding#phase-a--세션-prerequisite-한-번-이후-8-시간-자동)) + customer Entra pack 회신 받음 + 그 박스 Tailscale reachable.

```bash
# 0. (인계 전환이면) 박스에서 운영자 axe 신원 정리:
#    - 운영자 법인 데이터 (frame/hive) 분리 — 코드 자동화 없음, 운영자 판단
#    - 운영자 axelabs-tunnel launchd 제거 (customer tunnel 로 대체될 것)
#    - 운영자 org 데이터가 그 박스 vault 에 남지 않도록 정리

# 1. customers.yaml entry 흡수 (Entra pack → sso 블록 + client_secret 3개 vault push)
axe customers ingest {customer} ~/Downloads/axelabs-bootstrap-{customer}.json --apply
#    (먼저 --apply 빼고 dry-run 으로 변경 계획 확인)

# 2. cloudflared customer tunnel + DNS + launchd (그 박스에 독립 tunnel 생성)
axe onboard {customer} --apply --skip-frame

# 3. customer 측 bw vault session bootstrap (customer IT interactive 1회)
scp /Users/axe/.axe/bw-bootstrap.sh {customer}-macmini:~/bw-bootstrap.sh
ssh -t {customer}-macmini "brew install bitwarden-cli && ~/bw-bootstrap.sh https://<vault-url> <login-email>"

# 4. customer-scoped service stack 배포 (각 13-step, idempotent)
axe deploy frame {customer} --apply
axe deploy blueprint {customer} --apply
axe deploy hive {customer} --apply

# 5. vault env 4-key 패치 + force-recreate (JIT 가입 차단 회피)
axe vault bootstrap {customer} --apply
```

각 `axe deploy {svc} {customer}` 는 13-step (preflight → clone → vault_check → secrets_bootstrap → env_local → wrapper push → network → (blueprint) frame_mcp_token → compose up → (frame) proxy push → health → (frame+hive) register_entities → ingress swap) 을 SSH 로 그 박스에서 수행한다. 표준 onboarding 의 D-day 와 동일한 명령 — 차이는 **macmini-prep 6단계를 건너뛴다** (인프라 이미 준비됨) 는 것뿐.

전환 후 검증 + D+1/D+2/D+7 후속 (admin 부여 · entity 등록 · 직원 SSO 안내 · 안정화 점검) 은 [/ops/runbook/customer-onboarding](/ops/runbook/customer-onboarding) 의 해당 시점 절차를 그대로 따른다.

## 부분 전환 — 운영자 박스에 customer service 만 co-tenant

(엄밀 격리 모델 외 예외) customer 의 기존 자산 service (예: realchoice 의 `stream` :8780 / `magnet` :8770) 가 운영자 manifest 에만 정렬돼 도는 형태가 있다 — 이 경우 컨테이너는 customer 의 것이되 customers.yaml manifest 만 운영자 SoT 에 등재된다 ([서비스 카탈로그](/services) 의 stream/magnet `live (realchoice)` 표기). 이건 "박스 전환" 이 아니라 **manifest 정렬** 이므로 위 ①만 (customers.yaml services 슬롯 추가) 적용하고 ②③④ 는 customer 측 기존 인프라를 그대로 둔다. 포트 충돌만 사전 확인 (`portcheck` / `portdup`).

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 운영자 법인 데이터가 customer 박스에 잔존 | customer 가 운영자 회계/HR 데이터 접근 가능 (sovereignty 위반) | step 0 에서 frame/hive 데이터 분리 — 코드 자동화 없음, 운영자 책임 |
| 운영자 `axelabs-tunnel` launchd 가 그 박스에 남음 | customer tunnel 과 ingress 경합 / 운영자 도메인이 customer 박스로 샘 | step 0 에서 운영자 tunnel launchd 제거 |
| `ssh_user` 가 `axe` 가 아닌데 미명시 | axe CLI 가 `is_local` 분기 오판 또는 SSH user 틀림 | customers.yaml entry 에 실제 macOS 사용자명 명시 |
| 같은 host 에 두 customer 영구 co-tenant 시도 | `frame-postgres` 등 컨테이너 이름·포트 충돌 | customer-per-macmini 유지 — co-tenant 는 부분 전환 (manifest 정렬) 한정 |
| 컨테이너 이름이 `axe-...` 라 customer 박스인데 운영자 것으로 오인 | 운영 혼동 (실 동작 무해) | host (macmini hostname) 로 식별. rename 은 [B-container-name-customer-prefix](/ops/backlog) 대기 |
| `docker compose restart` 로 env 변경 반영 시도 | env reload 안 됨 | `docker compose up -d --force-recreate <container>` |

## 참고

- 표준 (신품 macmini) onboarding: [/partner](/partner) → [/partner/macmini-prep](/partner/macmini-prep) → [/partner/registration](/partner/registration) → [/partner/handoff](/partner/handoff) → [/partner/deploy](/partner/deploy)
- 운영자 측 D-day 절차 (동일 명령): [/ops/runbook/customer-onboarding](/ops/runbook/customer-onboarding)
- vault 서비스 정의 + org 모델: [/services/vaultwarden](/services/vaultwarden)
- 비밀 흐름 + 컨테이너 이름 컨벤션: [/architecture/secrets](/architecture/secrets)
- 기존 vault 유지 customer: [/partner/deploy § Vault OIDC SSO 통합](/partner/deploy)

---

<!-- PAGE https://docs.axelabs.ai/partner/macmini-prep -->

# macmini 사전 준비

> 배포 D-7 까지 귀사 IT 가 macmini 측에서 완료할 6 단계 (Tailscale 합류 + SSH key 회신 + 절전 disable).

URL: https://docs.axelabs.ai/partner/macmini-prep

# macmini 사전 준비

신규 배포 D-day 의 최소 1 주일 전 (D-7) 까지 **귀사 IT 담당자** 가 macmini 측에서 완료해야 하는 6 단계. 모두 합쳐 ~30 분.

이 단계가 끝나야 운영자가 `axe onboard {customer} --apply` 로 push deploy 가능합니다.

## 사전 확인

| 항목 | 권장 |
|---|---|
| 하드웨어 | Apple Silicon (M2 / M3 / M4), 16GB+ RAM, 512GB+ SSD |
| macOS | Sonoma 14.x 또는 Sequoia 15.x |
| 네트워크 | 유선 이더넷 권장 (Wi-Fi 가능하나 backup 시 불안정) |
| 전원 | 항시 켜진 상태로 운영 (UPS 권장) |
| 위치 | 회사 IT 룸 (또는 동등) — 직원 데스크 X |

## 1. macOS 초기 설정 (5분)

1. macmini 부팅 → 마법사 진행 (회사 Apple ID 권장, 개인 계정 X)
2. 컴퓨터 이름 = `{customer}-macmini` (예: `realchoice-macmini`) — 시스템 설정 → 일반 → 정보 → 이름
3. 사용자명 = `{customer}` (예: `realchoice`) — 운영자가 SSH 시 사용. 다른 이름 가능하나 운영자에게 회신 필요
4. 회사 메일로 활성화 (개인 메일 X)
5. macOS 최신 업데이트 적용 → 자동 업데이트 **OFF** (배포 후 사전 협의 없이 update 시 다운타임 위험)

## 2. 절전 / 자동 잠금 OFF (3분)

시스템 설정 → 잠금 화면:

| 항목 | 값 |
|---|---|
| 비활성 시간 후 디스플레이 끄기 | **사용 안 함** |
| 비활성 시간 후 잠금 시작 | **사용 안 함** |
| 자동으로 로그아웃 | **사용 안 함** |

시스템 설정 → 에너지:

| 항목 | 값 |
|---|---|
| 디스플레이가 꺼져 있을 때 컴퓨터 자동 잠자기 방지 | **켬** |
| 전원이 차단되었다가 들어오면 자동 시동 | **켬** |
| 네트워크 접근 시 깨우기 | **켬** |

> ⚠️ macmini 가 sleep 에 들어가면 운영자 측 새벽 backup 이 실패합니다. 위 설정 누락 = 함정 1 위.

## 3. Tailscale 가입 + macmini 합류 (10분)

Tailscale 은 운영자가 macmini 에 push deploy 하기 위한 mesh VPN. 공개 IP / 포트 오픈 불필요.

### 3-1. Tailscale 계정 생성

[https://tailscale.com/start](https://tailscale.com/start) → 회사 메일 (`it@{customer}.com` 등) 로 가입. SSO 가능 (Google / Microsoft).

요금: 운영자 측 tailnet 에 합류하므로 귀사 측 별도 결제 X (운영자 부담).

### 3-2. macmini 에 Tailscale 설치

```bash
# Tailscale macOS app (App Store 또는 직접)
brew install --cask tailscale
# 또는 https://tailscale.com/download/macos 에서 .pkg 다운로드
```

설치 후 메뉴바 Tailscale 아이콘 → **Log in** → 위 가입한 계정으로 로그인.

### 3-3. 운영자 tailnet 합류

귀사 계정만으로는 운영자가 접근 못 함. 다음 둘 중 하나:

**A. tailnet share (권장)** — 운영자가 보낸 share link 수락
- 운영자 (`ai@axellc.com`) 에게 macmini 의 Tailscale email 알림
- 운영자가 share invite 발송 → 메일 수락 → 운영자 tailnet 에서 `{customer}-macmini` 가 보임

**B. 별도 tailnet + ACL** — Tailscale Business plan 필요 시
- 운영자에게 사전 협의

### 3-4. Tailscale IP 회신

```bash
tailscale ip -4
# 예: 100.114.161.51
```

이 IP 를 운영자에게 회신 (안전 채널 불필요 — Tailscale IP 는 ACL 로 보호).

## 4. SSH 활성화 + 운영자 key 등록 (5분)

### 4-1. SSH 활성화

시스템 설정 → 일반 → 공유 → **원격 로그인 (SSH)** = **켬**, 접근 = "모든 사용자" 또는 `{customer}` 사용자

### 4-2. 운영자 public key 받기

운영자가 자신의 public key (예: `ssh-ed25519 AAAAC3... ai@axellc.com`) 를 평문 메일로 전송합니다 (public key 는 비밀 X). 한 줄.

### 4-3. authorized_keys 등록

```bash
mkdir -p ~/.ssh
chmod 700 ~/.ssh
echo 'ssh-ed25519 AAAA...받은 운영자 키 한 줄 그대로... ai@axellc.com' >> ~/.ssh/authorized_keys
chmod 600 ~/.ssh/authorized_keys
```

### 4-4. SSH 테스트 (운영자가 실행)

운영자 측에서 `ssh {customer}@{customer}-macmini.tail<...>.ts.net 'whoami'` 가 `{customer}` 를 출력하면 성공. 귀사 측은 회신만 기다리면 됨.

> 💡 SSH 키쌍은 ed25519 권장 (RSA 보다 짧고 안전). 비밀번호 인증은 사용하지 않습니다 — key only.

## 5. Docker Desktop 설치 (5분)

운영자 측 push 후 macmini 에서 docker compose 가 실행됩니다.

```bash
brew install --cask docker
```

또는 [https://www.docker.com/products/docker-desktop/](https://www.docker.com/products/docker-desktop/) 에서 Apple Silicon .dmg.

설치 후:
1. Docker Desktop 실행 → 마법사 (기본 설정 OK)
2. Resources → Memory 8GB+ 할당 (16GB RAM 기준; frame + blueprint + hive + vault 4 stack)
3. Settings → General → **"Start Docker Desktop when you sign in to your computer"** = ON

`docker ps` 가 빈 결과를 출력하면 정상.

## 6. Bitwarden CLI 설치 (3분)

운영자 측 `axe deploy ...` 자동화가 customer-side wrapper 를 통해 bw CLI 로 secret 을 조달합니다.

```bash
# Node.js 가 없으면 먼저 설치
brew install node

# bw CLI 표준 버전 = 2025.7.0 (반드시 이 버전)
npm install -g @bitwarden/cli@2025.7.0
bw --version    # 2025.7.0 확인
```

★ **`2025.7.0` 버전 pin 필수** — 최신 (`2026.4+`) 은 Vaultwarden Timshel SSO user 와 호환 깨짐 (`TypeError: toWrappedAccountCryptographicState`). 운영 표준은 2025.7.0 통일 ([D-ops-28](/ops/decisions), [상세](/architecture/secrets#bw-cli-표준-버전--202570-d-ops-28)).

설치 후 별도 로그인 불필요 — D-day 의 `bw-bootstrap.sh` 가 interactive 로 server URL + 계정 setup.

## 7. 기본 점검 회신

다음 한 줄을 운영자에게 회신:

```
{customer}-macmini 준비 완료
- macOS: 15.x.x
- Tailscale IP: 100.114.161.51
- SSH 사용자: {customer}
- Docker: 4.34.0 (running)
- bw CLI: 2025.7.0
- 절전: 비활성화됨
```

회신 즉시 운영자가 SSH probe 로 검증 → D-day 작업 가능 상태로 전환.

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 절전 / 자동 잠금 비활성화 누락 | 새벽 backup / 모니터링 실패 | §2 모든 항목 OFF |
| 자동 macOS 업데이트 ON | 사전 협의 없이 reboot → 다운타임 | §1 OFF |
| 컴퓨터 이름이 `{customer}-macmini` 아님 | 운영자 측 customers.yaml 의 `tailscale_host` 불일치 | §1 step 2 |
| Tailscale 가입은 했으나 share invite 미수락 | 운영자가 macmini 못 봄 | §3-3 |
| SSH 활성화는 했으나 authorized_keys 등록 누락 | key auth 실패 | §4-3 |
| `authorized_keys` 의 권한이 644 | sshd 가 무시 (StrictModes) | `chmod 600` |
| Docker Desktop 미실행 (설치만 함) | `docker ps` 명령 실패 | 메뉴바에 docker 고래 아이콘 보이는지 확인 |
| bw CLI `2026.4+` 설치 | D-day `bw-bootstrap.sh` 가 `TypeError: toWrappedAccountCryptographicState` 로 crash | `npm install -g @bitwarden/cli@2025.7.0` 재설치 (§6) — 운영 표준 |
| 회사 방화벽이 Tailscale UDP 차단 | mesh 연결 안 됨 | Tailscale 41641/udp outbound 허용 — [공식 문서](https://tailscale.com/kb/1082/firewall-ports/) |

## 다음 단계

macmini 준비가 끝나면:
- [Microsoft Entra ID 앱 등록 (Option A — CLI 1 줄)](/partner/registration#option-a--cli-1-줄-권장)
- [DNS / 도메인 준비](/partner/domain-prep)
- [운영자에게 넘길 값](/partner/handoff)
- [배포 협의](/partner/deploy)

---

<!-- PAGE https://docs.axelabs.ai/partner/registration -->

# Microsoft Entra ID 앱 등록

> Blueprint · Vaultwarden · Frame MCP · Blueprint MCP 4개 app 등록 — CLI 1줄 (5분) 또는 portal (~50분).

URL: https://docs.axelabs.ai/partner/registration

# Microsoft Entra ID 앱 등록

귀사 Microsoft Entra ID tenant 에 **4 개의 app** 을 등록합니다.

> 🚀 **권장: Option A — CLI 1 줄 (~5분)**
> `https://docs.axelabs.ai/axelabs-bootstrap.sh` 다운로드 → `az login` → 1 줄 실행 → JSON pack 회신. 본 페이지의 [Option A](#option-a--cli-1-줄-권장) 섹션 자체에 모든 절차가 들어있습니다 (별도 메시지/파일 의존 없음).
>
> Option B (portal 수작업, ~40분) 은 `az` CLI 가 환경상 안 될 때 fallback 입니다.

---

## Option A — CLI 1 줄 (권장)

### 1. 사전 확인 (5분)

| 항목 | 확인 방법 |
|---|---|
| `az` CLI 설치 (≥ 2.50) | `az --version`; 없으면 `brew install azure-cli` (macOS) / [공식 설치 가이드](https://learn.microsoft.com/cli/azure/install-azure-cli) |
| `jq` 설치 | `jq --version`; 없으면 `brew install jq` |
| **Admin consent grant 권한** (다음 중 하나) | `az ad signed-in-user show` 후 본인 역할 확인. ★ admin consent 가 자동으로 잡혀야 직원/agent 가 claude.ai Custom Connector 등록 시 consent prompt 안 나옴 |
| ・ Global Administrator (권장 — 모든 권한) | Entra ID → Roles and administrators → "Global Administrator" |
| ・ Privileged Role Administrator | 같은 곳에서 확인 |
| ・ Cloud Application Administrator | 같은 곳에서 확인 |
| ・ Application Administrator | 같은 곳에서 확인 |
| `{customer}.axelabs.ai` 가 Entra tenant 의 verified domain 인지 | 운영자 측이 사전 등록함 — 미등록 시 §[도메인 검증 흐름](#도메인-검증-흐름) 참조 |

### 2. 스크립트 다운로드 + 무결성 검증

```bash
# 다운로드
curl -fsSL https://docs.axelabs.ai/axelabs-bootstrap.sh -o axelabs-bootstrap.sh
chmod +x axelabs-bootstrap.sh

# SHA-256 검증 (값이 일치해야 신뢰)
shasum -a 256 axelabs-bootstrap.sh
# 예상: ae6f771e85f7ec49d75bc082e1e0d42b106ba095e03d9adad430e590c2c4aefb  axelabs-bootstrap.sh
```

> ⚠️ 체크섬이 다르면 즉시 운영자 (`ai@axellc.com`) 에게 연락. 위 값은 본 docs 페이지 (https://docs.axelabs.ai/partner/registration) 와 함께 갱신됩니다.

### 3. Azure 로그인

```bash
# 귀사 tenant 로 로그인 (브라우저 팝업)
az login --allow-no-subscriptions --tenant <YOUR_TENANT_ID_OR_DOMAIN>

# 예 (도메인)
az login --allow-no-subscriptions --tenant realchoice.onmicrosoft.com

# 또는 tenant ID (GUID)
az login --allow-no-subscriptions --tenant 381cc823-2bb2-43a7-9a27-68ea3afacdff
```

> ⚠️ **`--allow-no-subscriptions` 가 필수**. Microsoft 365 만 사용하고 Azure subscription (구독 결제) 이 없는 tenant 에서 일반 `az login` 은 "No subscriptions found for ..." 에러로 종료됩니다. bootstrap.sh 는 Microsoft Graph (app registration) 만 호출하므로 subscription 불필요 — 본 flag 로 우회.

**검증** (subscription 없이도 ok):

```bash
az account show
# 기대 출력: subscription 필드 없이도 tenantId / homeTenantId / user.name 표시되면 OK
# (subscription 보유 tenant 라면 isDefault: true 인 subscription 1개 표시도 정상)
```

`az account show` 가 `Please run 'az login' to setup account.` 를 반환하면 step 3 재시도. 정상 출력이면 step 4 진행.

### 4. 부트스트랩 실행 — 1 줄

```bash
./axelabs-bootstrap.sh <customer_id> <public_domain>

# 예 (realchoice)
./axelabs-bootstrap.sh realchoice realchoice.axelabs.ai
```

`<customer_id>` 는 운영자가 사전 제공 (예: `realchoice`). `<public_domain>` 도 운영자 제공 (`{customer}.axelabs.ai`).

스크립트가 자동 처리:
1. `az` 와 `jq` 가용성 확인
2. 4 개 app 등록 (이미 존재하면 reuse — idempotent, destructive 작업 없음)
3. 각 app 의 client_secret 발급 (`--append` 로 기존 secret 보존, overlap window)
4. Frame MCP + Blueprint MCP 의 Application ID URI + `mcp.access` scope + manifest 설정
5. Delegated permission + admin consent (실행자 = Global Admin 이어야 자동)
6. Tenant ID 자동 캡처
7. 결과를 `axelabs-bootstrap-<customer_id>.json` 으로 출력 (mode 600)

### 5. 출력 파일 회신

스크립트 실행 후 생성된 파일:

```
axelabs-bootstrap-<customer_id>.json   # 예: axelabs-bootstrap-realchoice.json
```

JSON 스키마 (`axelabs-bootstrap/v1`):

```json
{
  "schema": "axelabs-bootstrap/v1",
  "customer": "realchoice",
  "public_domain": "realchoice.axelabs.ai",
  "tenant_id": "<GUID>",
  "generated_by": "<your-az-login-email>",
  "apps": {
    "blueprint":   { "client_id": "...", "client_secret": "..." },
    "vaultwarden": { "client_id": "...", "client_secret": "..." },
    "frame_mcp":   {
      "client_id": "...",
      "client_secret": "...",
      "application_id_uri": "https://realchoice.axelabs.ai/frame/mcp",
      "scope": "mcp.access",
      "redirect_uris": ["https://claude.ai/api/mcp/auth_callback", "https://claude.com/api/mcp/auth_callback"]
    },
    "blueprint_mcp": {
      "client_id": "...",
      "client_secret": "...",
      "application_id_uri": "https://realchoice.axelabs.ai/blueprint/mcp",
      "scope": "mcp.access",
      "redirect_uris": ["https://claude.ai/api/mcp/auth_callback", "https://claude.com/api/mcp/auth_callback"]
    }
  }
}
```

운영자에게 [안전 채널로 전달](/partner/handoff) (1Password Send / Bitwarden Send view-once). 평문 메일·채팅 금지.

### 6. 운영자 처리 확인

운영자가 `axe customer ingest realchoice axelabs-bootstrap-realchoice.json` 으로 흡수 → vault 에 secret push + customers.yaml 자동 갱신 → 다음 단계 [배포 협의](/partner/deploy) 진행.

### 도메인 검증 흐름

`{customer}.axelabs.ai` 는 `axelabs.ai` zone (운영 주체 = 액스코퍼레이션 주식회사 관리) 의 서브도메인. 따라서 **TXT 검증은 운영자가 axelabs.ai zone 에 추가**합니다 — 귀사 IT 에서는 다음 두 경로 중 하나:

- 운영자가 사전 등록한 경우: 스크립트가 `--skip-domain-verify` 기본값으로 가정. 그대로 실행.
- 사전 등록 안 된 경우: `./axelabs-bootstrap.sh ... --request-domain-verify` 실행 → stdout 에 TXT 값 표시 → 운영자에게 한 줄 전달 → 운영자가 Cloudflare API 로 추가 후 → 스크립트 재실행.

자세한 도메인 모델은 [DNS 준비](/partner/domain-prep) 참조.

### 함정 (Option A)

| 함정 | 결과 | 회피 |
|---|---|---|
| `az login` 안 함 | "Please run 'az login'" | step 3 |
| **Azure subscription 없는 tenant 에서 `az login` 만 실행** | "No subscriptions found for ...". tenant level access 만 필요한 작업인데도 종료 | **`az login --allow-no-subscriptions --tenant <id>`** 로 실행. M365 만 쓰는 tenant 의 표준 함정 (2026-05-25 트루비아 측 첫 발견) |
| 실행자가 Global Admin / Application Administrator / Cloud App Admin / Privileged Role Admin 모두 아님 | admin consent grant 실패 (warning) → claude.ai Custom Connector 등록 시 일반 직원이 consent prompt 직면 (개인 grant 못 함 → 차단) | (a) 회사 IT 의 위 role 보유자가 재실행, (b) 또는 portal UI 에서 admin consent grant: **Entra ID → App registrations → `Frame MCP` (또는 `Blueprint MCP`) → API permissions → "Grant admin consent for `{tenant}`"** 클릭, (c) 또는 admin consent URL 직접 방문: `https://login.microsoftonline.com/{tenant_id}/adminconsent?client_id={client_id}` |
| `<public_domain>` 검증 안 됨 | Frame MCP Application ID URI 등록 실패 | §[도메인 검증 흐름](#도메인-검증-흐름) |
| 같은 customer_id 로 재실행 | secret 만 추가 발급 (기존 보존) — 정상 동작 | — |
| Apple Silicon 의 `jq` 누락 | "jq: command not found" | `brew install jq` |

---

## Option B — Portal 수작업 (fallback, ~40분)

`az` CLI 사용 불가한 환경 (admin 정책상 차단 등) 일 때만.

귀사 Microsoft Entra ID tenant 에 **4 개의 app** 을 등록합니다. 각각 다른 용도:

| # | App 이름 | 용도 | Platform | Secret |
|---|---|---|---|---|
| 1 | `Blueprint` | Web UI 로그인 | Web | 발급 |
| 2 | `Vaultwarden` | 회사 password vault SSO | Web | 발급 |
| 3 | `Frame MCP` | 회계 시스템 OAuth (claude.ai connector) | Web | 발급 |
| 4 | `Blueprint MCP` | Blueprint MCP OAuth (claude.ai connector) | Web | 발급 |

## 사전 준비

- Azure portal 접속 권한 (Global Admin 또는 Application Administrator)
- 회사 도메인 검증 완료 ([DNS 준비](/partner/domain-prep) 우선 진행)
- 서비스 노출 domain 확인 (AXE 측이 제공, 예: `realchoice.axelabs.ai`)

---

## App #1 — Blueprint (Web UI 로그인)

### 등록

1. Azure portal → **Microsoft Entra ID** → **App registrations** → **+ New registration**
2. **Name**: `Blueprint`
3. **Supported account types**: `Accounts in this organizational directory only (Single tenant)`
4. **Redirect URI**:
   - Platform: **Web**
   - URI: `https://{customer}.axelabs.ai/api/auth/callback/azure-ad`
   - 예: `https://realchoice.axelabs.ai/api/auth/callback/azure-ad`
5. **Register**

### Client Secret 발급

1. 좌측 **Certificates & secrets** → **+ New client secret**
2. Description: `blueprint-{customer}-2026-06`
3. Expires: **180 days** (또는 회사 정책)
4. **Add** → **VALUE** 컬럼 즉시 복사 (이후 안 보임)

### API Permissions

좌측 **API permissions** → **+ Add a permission** → **Microsoft Graph** → **Delegated**:

- `User.Read`
- `Mail.Read`
- `Mail.Send`
- `Chat.ReadWrite`
- `ChatMessage.Send`

**Add permissions** → 권한 있으시면 **Grant admin consent for `{tenant}`**.

### 수집할 값

```
Blueprint_CLIENT_ID    : <Overview 페이지의 Application (client) ID>
Blueprint_CLIENT_SECRET: <위에서 복사한 VALUE>
```

---

## App #2 — Vaultwarden (password vault SSO)

### 등록

1. **+ New registration**
2. **Name**: `Vaultwarden`
3. **Supported account types**: `Single tenant`
4. **Redirect URI**:
   - Platform: **Web**
   - URI: `https://{customer}.axelabs.ai/vault/identity/connect/oidc-signin`
5. **Register**

### Client Secret

App #1 과 동일 절차로 secret 발급, VALUE 캡처.

### API Permissions

**Microsoft Graph → Delegated**:

- `openid`
- `profile`
- `offline_access`
- `User.Read`

**Grant admin consent**.

### 수집할 값

```
Vaultwarden_CLIENT_ID    : <...>
Vaultwarden_CLIENT_SECRET: <...>
```

---

## App #3 — Frame MCP (회계 시스템) ⚠️ 가장 복잡

이 app 만 **App ID URI + custom scope** 가 추가로 필요합니다. 4 단계.

### 3-1. 등록

1. **+ New registration**
2. **Name**: `Frame MCP`
3. **Supported account types**: `Single tenant`
4. **Redirect URI**: 일단 비워두고 **Register**

### 3-2. Authentication (Web platform)

좌측 **Authentication** → **+ Add a platform** → **Web**:

- Redirect URIs (둘 다 추가):
  - `https://claude.ai/api/mcp/auth_callback`
  - `https://claude.com/api/mcp/auth_callback`

같은 페이지 하단 **Advanced settings**:
- **Allow public client flows**: **Yes** (PKCE 가능)

**Save**.

### 3-3. Expose an API

⚠️ **사전 조건**: [DNS / 도메인 준비](/partner/domain-prep) 가 완료되어 `{customer}.axelabs.ai` 가 검증된 사용자 도메인이어야 합니다.

좌측 **Expose an API**:

1. **Application ID URI** → **Add** (또는 Edit) → 입력:
   ```
   https://{customer}.axelabs.ai/frame/mcp
   ```
   예: `https://realchoice.axelabs.ai/frame/mcp`
2. **Save**

3. **Add a scope**:
   - Scope name: `mcp.access`
   - Who can consent: `Admins and users`
   - Admin consent display name: `Access Frame MCP as the signed-in user`
   - Admin consent description: `Allow the application to access Frame MCP on behalf of the signed-in user.`
   - User consent display name: `Access Frame MCP`
   - User consent description: `Allow this app to access Frame MCP for you.`
   - State: **Enabled**
4. **Add scope**

전체 scope URI: `https://{customer}.axelabs.ai/frame/mcp/mcp.access`

### 3-4. API Permissions (자기 자신 참조)

좌측 **API permissions** → **+ Add a permission** → **My APIs** 탭 → **Frame MCP** → **Delegated** → `mcp.access` 체크 → **Add permissions**.

상단 **Grant admin consent for `{tenant}`** 클릭.

### 3-5. Token Configuration

좌측 **Token configuration** → **+ Add optional claim** → **ID** → `email`, `upn` 체크 → **Add**.

(id_token 이 verified email 없는 사용자도 처리할 수 있도록.)

### 3-6. Manifest (선택 확인)

좌측 **Manifest** → JSON 안에서 `"requestedAccessTokenVersion"` 값 확인:
- **`null`** (기본) → v1 토큰 (aud = Application ID URI) — Anthropic Claude 호환에 권장
- `2` → v2 토큰 (aud = client_id GUID)

기본값 `null` 그대로 두기를 권장 (claude.ai 의 audience 검증 호환).

### 3-7. Client Secret 발급

좌측 **Certificates & secrets** → **+ New client secret**:
- Description: `frame-mcp-{customer}-2026-06`
- Expires: **24 months**
- **Add** → VALUE 즉시 복사

### 수집할 값

```
Frame_MCP_CLIENT_ID    : <Overview 페이지의 Application (client) ID>
Frame_MCP_CLIENT_SECRET: <위에서 복사한 VALUE>
```

---

## App #4 — Blueprint MCP (Blueprint MCP OAuth)

**App #3 Frame MCP 와 동일 절차** — 호스트 경로만 `/frame/mcp` → `/blueprint/mcp` 로 교체:

| Step | Frame MCP 값 | Blueprint MCP 값 |
|---|---|---|
| Name | `Frame MCP` | `Blueprint MCP` |
| Application ID URI (3-3) | `https://{customer}.axelabs.ai/frame/mcp` | `https://{customer}.axelabs.ai/blueprint/mcp` |
| Scope URI | `https://{customer}.axelabs.ai/frame/mcp/mcp.access` | `https://{customer}.axelabs.ai/blueprint/mcp/mcp.access` |
| Client secret description | `frame-mcp-{customer}-2026-06` | `blueprint-mcp-{customer}-2026-06` |

나머지 (Authentication Web platform / Redirect URIs / Add public client flows Yes / Expose an API mcp.access scope / API Permissions self-reference + admin consent / Token Configuration optional claims / Manifest accessTokenAcceptedVersion=null) **모두 App #3 과 동일**.

### 수집할 값

```
Blueprint_MCP_CLIENT_ID    : <Overview 페이지의 Application (client) ID>
Blueprint_MCP_CLIENT_SECRET: <위에서 복사한 VALUE>
```

---

## 4. Tenant ID 수집 (1 회)

4개 app 공통. 아무 app 의 Overview 페이지에서 **Directory (tenant) ID** 복사.

또는 Azure portal → Microsoft Entra ID → Overview → Tenant ID.

```
TENANT_ID: &lt;GUID&gt;
```

---

## 5. 회신 형식

[운영자에게 넘길 값](/partner/handoff) 페이지의 회신 템플릿에 채워서 보내주세요.

## 함정 모음

| 함정 | 결과 | 회피 |
|---|---|---|
| Application ID URI 에 검증 안 된 도메인 사용 | 등록 거부 | [DNS 준비](/partner/domain-prep) 먼저 |
| Web platform 누락 (Mobile/desktop 만) | redirect_uri 등록 실패 | Web platform 명시 |
| Allow public client flows = No + secret 없음 | OAuth 실패 (AADSTS7000218) | Yes 또는 secret 발급 |
| `mcp.access` scope 안 만들고 API permissions 만 추가 | scope 호출 시 실패 | Expose an API 단계 먼저 |
| Application ID URI 와 scope URI 불일치 | AADSTS9010010 | 둘 다 같은 URL prefix |
| Manifest 의 accessTokenAcceptedVersion=2 (Anthropic 비호환) | mcp_client_invalid | null 또는 1 |
| **Admin consent 미 grant** (App #1 Blueprint / App #3 Frame MCP / 향후 Blueprint MCP) | 일반 직원이 첫 로그인 또는 claude.ai Custom Connector 등록 시 AADSTS65001 (`invalid_grant`) 차단. 본인 단독 grant 불가 | App 별 **API permissions → Grant admin consent for `{tenant}`** 버튼 클릭. 본인이 권한 부족 시 회사 IT 의 Global Admin / App Admin / Cloud App Admin / Privileged Role Admin 중 1인에게 의뢰. CLI 대안: `az ad app permission admin-consent --id <client_id>` (같은 role 필요) |

다음: [DNS / 도메인 준비](/partner/domain-prep) →

---

<!-- PAGE https://docs.axelabs.ai/services -->

# 서비스 카탈로그

> AXE Labs 플랫폼의 8 vertical 서비스 (Blueprint workspace + 7 MCP backend) + 인프라 의존.

URL: https://docs.axelabs.ai/services

# 서비스 카탈로그

| 서비스 | 역할 | 기술 | 포트 | 상태 |
|---|---|---|---|---|
| [Blueprint](/services/blueprint) | AI-native workspace, agent 협업 | Next.js 16 + Prisma + Claude SDK | 3100/3101 | live (axe) |
| [Cortex](/services/cortex) | AI-native relationship CRM (artifact-first, Google Contacts canonical) | **Rust** + axum + sqlx + Postgres 16 | 3200/3210/3212 | Day 1 (axe, 2026-05-26) |
| [Frame](/services/frame) | 회계 backend (KSME) | Python + FastMCP + Postgres 16 | 3700/3710/3712 | live (axe) |
| [Hive](/services/hive) | HR backend (조직·휴가·성과·보상) | Python + FastMCP + Postgres 16 | 3800/3810/3812 | live (axe) |
| [Matrix](/services/matrix) | 인프라 모니터링 MCP (Docker/Postgres health) | **Rust** + axum + sqlx + bollard | 3901/3910/3912 | live (axe) |
| [UI](/services/ui) | 디자인 시스템 SSOT — 토큰 · 40+ 컴포넌트 · `.axe-app-shell` chrome (Phase 15) | Next.js 16 + React 19 (multi-domain rewrite) | 3900 (공유) | 데모 (axe, 2026-05-29) |
| [Index](/services/index) | 투자 도메인 MCP (소싱·DD·IC·포트폴리오·엑싯·IR) — financial_model 6-table + fund_investment N:M + artifact-first 판단층 | **Rust** + axum + sqlx + Postgres 16 + RLS | 4000/4010/4012 | live (axe) · [현황](https://axe.axelabs.ai/index) |
| [Stream](/services/stream) | S&OP MCP (sales/inventory/settlement) | Python + FastMCP + Postgres | 8780 | live (realchoice) |
| [Magnet](/services/magnet) | 마케팅 자동화 MCP (Meta/Naver/Threads) | Python + FastMCP + Postgres + RLS | 8770 | live (realchoice) |

## 보조 인프라

| 컴포넌트 | 역할 | 위치 |
|---|---|---|
| Vaultwarden | password vault + OIDC | `/Users/axe/.axe/vault/` (Timshel fork) |
| axelabs-tunnel | Cloudflare Tunnel | `/Users/axe/.axe/tunnels/axelabs/` |
| axe-frame-proxy | blue/green selector (Caddy) | `/Users/axe/.axe/frame-proxy/` |
| axe-caddy | admin.axelabs.ai 콘솔 | `/Users/axe/.axe/console/` |
| frame-postgres | DB | Docker (`frame-postgres`, port 3700) |
| customers.yaml | SSOT | `/Users/axe/.axe/customers.yaml` |
| axe CLI | 운영 명령 | `/Users/axe/.axe/bin/axe` |

## 의존성 그래프

```
                    ┌──────────────────┐
                    │  customers.yaml  │  ← SSOT (operator-edited)
                    └──────────────────┘
                              │
              ┌────────┬──────┴──────┬─────────┐
              │        │             │         │
          blueprint  frame  hive    vault     │
              │        │     │       │        │
              ├─────┐  ├─────┘       │        │
              │     └──┼──── stream  │        │
              │        │      ↕      │        │
              │        └──── magnet ─┤        │
              │                              │
              └──── Microsoft Entra ID ──────┘
                     (per-customer tenant)
```

- **blueprint** ↔ **frame**: HTTP MCP (`http://frame-mcp:3710/mcp`) — 회계 데이터
- **blueprint** ↔ **hive**: HTTP MCP (`http://hive-mcp:3810/hive/mcp`) — HR 데이터
- **blueprint** ↔ **cortex**: 향후 (M6 통합) artifact mirror — 관계망 데이터 ([D-cortex-1](/ops/decisions))
- **cortex** → Google Contacts: per-user OAuth + People API (pull canonical, [D-cortex-3](/ops/decisions))
- **hive** → **frame**: pg_notify (`hive.payroll.finalized` → 인건비 자동 분개)
- **stream** ↔ **magnet**: 신호 채널 (purchase_signal, inventory_alert, ad_spend_mirror)
- **vault** ← all services: 운영자가 직접 secret 조회 (CLI), 또는 OIDC 로 직원 로그인

## 운영 책임 분할

각 서비스는 **단일 owner** 모델:

- frame — 회계 데이터 (운영자 책임)
- hive — HR 데이터 (운영자 책임)
- cortex — 관계망 데이터 (per-user private, [D-cortex-2](/ops/decisions))
- stream — sales/inventory/settlement (realchoice 운영자)
- magnet — 마케팅 (realchoice 운영자)
- blueprint — 협업 layer (운영자 책임)
- matrix — infra 모니터링 (운영자 책임)

cross-service 데이터 이동은 **명시적 신호 채널** 만 (pg_notify, JSONL outbox). 직접 DB read 금지.

---

<!-- PAGE https://docs.axelabs.ai/services/blueprint -->

# Blueprint

> AI-native workspace, Claude Agent SDK, MCP 클라이언트, 멀티테넌트 web UI.

URL: https://docs.axelabs.ai/services/blueprint

# Blueprint

**한 줄 소개**: 인간 운영자와 AI 에이전트가 함께 일하는 통합 워크스페이스. Next.js + Claude Agent SDK 로 13종 에이전트 실행, frame · stream · magnet MCP 서버를 도구로 호출.

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | TypeScript |
| 프레임워크 | Next.js 16 (App Router) + React 19 |
| 스타일 | Tailwind CSS 4 + `@axe/ui` 디자인 토큰 (`/Users/axe/axelabs/src/lib/`, sync 됨 → `src/app/_axe-ui/`) |
| DB | PostgreSQL 16 (Prisma 6.19) — D-config-17 cutover 2026-05-15. SQLite 는 historical (cutover 이전 `prisma/data/blueprint.db`) |
| 인증 | NextAuth 4 + Microsoft Entra ID (Azure AD) |
| 에이전트 | `@anthropic-ai/claude-agent-sdk` 0.2.92 |
| 실시간 | Socket.IO 4.8 (port 3101 WebSocket) |
| 터미널 | node-pty 1.1 (PTY) |
| MCP 클라이언트 | `@anthropic-ai/sdk` 0.82 (HTTP/SSE transport) |

## 포트

| 포트 | 용도 |
|---|---|
| 3100 | Next.js dev / production HTTP |
| 3101 | Socket.IO WebSocket |
| 3180 | Caddy 외부 노출 (HTTPS) |

## 디렉토리 구조

```
/Users/axe/blueprint/
├── src/
│   ├── app/                    Next.js App Router
│   │   ├── layout.tsx
│   │   ├── page.tsx           landing
│   │   ├── onboard/           가입 흐름
│   │   ├── axe/               대시보드 (admin, agents, issues, projects, skills, team, trinity)
│   │   └── api/               93+ route.ts
│   │       ├── auth/[...nextauth]
│   │       ├── agents/
│   │       ├── sessions/
│   │       ├── workspaces/
│   │       ├── graph/         Microsoft Graph API proxy
│   │       └── teams-graph-*  Teams 통합
│   ├── lib/
│   │   ├── auth.ts            NextAuth + Azure AD
│   │   ├── anthropic-client.ts
│   │   ├── customers.ts       customers.yaml reader (mtime cache)
│   │   ├── mcp/
│   │   │   └── frame.ts       frame HTTP MCP 등록, ~21개 tool wrapping
│   │   ├── agents/
│   │   │   └── execution-service.ts
│   │   └── teams/
│   ├── server/
│   │   └── websocket.ts       Socket.IO + PTY (port 3101)
│   └── prisma/
│       └── schema.prisma      Member / User / Agent / Session / Issue
├── docker/
│   └── docker-compose.yml
└── docs/
    ├── project-blueprint.md   47KB master doc (5 분과)
    └── project-blueprint/
        ├── division1-org.md
        ├── division2-tech.md
        ├── division3-ops.md
        ├── division4-claude-code.md
        └── division5-risk-governance.md
```

## 데이터 모델 (요약)

```
Entity (axec / axev / sys — D-bp-entity-3 NOT NULL)
  ├─ slug              UNIQUE (axec | axev | sys | …)
  ├─ name              한국어 정식 명칭 (hive shared.entity.legal_name mirror, D-bp-entity-4)
  ├─ kind              "corporate" | "system" | "fund" | …
  ├─ bizNo             사업자등록번호 (D-bp-entity-5, hive mirror)
  ├─ fiscalYearStartMonth  1-12 (KR default 1)
  ├─ countryCode       ISO 3166-1 alpha-2 (KR default)
  └─ workspaces[]      1:N

Member (인간/에이전트 통합)
  ├─ User    (email, aadObjectId, role: admin|member,
  │          entityScopes: JSON ["axev","axec"] — D-bp-entity-8 raw 순서,
  │          defaultEntity: 사용자별 명시적 default — D-bp-entity-7,
  │          ownedBy: 본인 owner FK (AI agent ↔ human, D-bp-entity-9))
  │     └─ EntityRole[]  per-(user, entity) 권한 grant (D-bp-entity-17,
  │                      role: admin|owner|member, grantedById audit)
  └─ Agent   (agentId by SDK, memberId)

Workspace (PARA row — Project/Area/Resource/Archive)
  ├─ entityId          → Entity (NOT NULL — D-bp-entity-3, General bucket 폐기)
  ├─ paraLayer         ParaLayer enum {PROJECT, AREA, RESOURCE, ARCHIVE}
  ├─ sourceWorkspaceId / sourceArtifactPath / copiedAt  (D-bp-entity-2 fork provenance)
  └─ Session (mode: chat|terminal|hybrid|agent)
       ├─ Messages
       └─ TerminalSessions

Issue
  ├─ assignee:Member
  └─ reporter:Member

AppSetting (key-value, frame_mcp_token 회전 저장)

OperatorAlert (D-bp-alert-1, L2 silent-drop 영구 기록)
  ├─ source            처리 진입점 (e.g. processChatBundle)
  ├─ chatId / messageId
  ├─ primaryError / ackError
  ├─ createdAt
  └─ acknowledgedAt / acknowledgedBy   (NULL = unresolved)

MailSendLog (D-bp-mcp-mail-1, 2026-05-29 — send_mail append-only audit; migration 20260529120000_add_mail_send_log)
  ├─ callerEmail        인증된 caller (MCP token email claim)
  ├─ sentAs             실제 발신 mailbox (caller, 또는 send-as target)
  ├─ subject
  ├─ toCount / ccCount / bccCount / attachmentCount   (주소 자체는 미저장)
  ├─ status             "sent" | "dry_run" | "failed"
  ├─ messageId          Graph sendMail 202 no-body → null
  ├─ httpStatus / error
  └─ createdAt          index: createdAt / (callerEmail, createdAt)

McpSchema (D-bp-artifact-1, 2026-05-23 — schema discovery cache)
  ├─ service           ← 'frame' | 'hive' | 'magnet' | 'stream' | …
  ├─ schemaId          ← 'frame.balance@1.0' (@version suffix 포함)
  ├─ envelopeVersion   ← MCP /schemas envelope.version
  ├─ body              ← JSONB { description, produced_by, key_fields, … }
  ├─ fetchedAt         ← @updatedAt — 매 fetch 마다 갱신
  ├─ firstSeenAt       ← 첫 발견 시점
  └─ @@unique([service, schemaId])  새 version = 새 row, body 변경 = drift warn

OAuth* (D-axe-idp-1, 2026-06-03 — Blueprint = 플랫폼 OIDC Provider; src/lib/platform-oidc.ts)
  ├─ OAuthAuthCode      단발 authorization code (PKCE S256, 10분 TTL, atomic 소비)
  ├─ OAuthRefreshToken  회전 refresh token (sha256 hash 만 저장, revokedAt/rotatedTo)
  └─ OAuthClient        RFC 7591 DCR 동적 클라이언트 (loopback/downstream) — axe-cli 는 정적

Artifact (D-bp-artifact-1, 2026-05-23 — typed fact unit)
  ├─ id                ← cuid PK
  ├─ schemaId          ← 'frame.balance@1.0' or 'freeform.llm@auto' — McpSchema lookup
  ├─ workspaceId       ← Workspace FK (CASCADE delete)
  ├─ entityId          ← cached from Workspace.entityId
  ├─ paraLayer         ← cached from Workspace.paraLayer
  ├─ content           ← JSONB — typed payload per schemaId
  ├─ citations         ← JSONB array — 6-kind discriminated union
  │                       (onedrive / frame.* / hive.* / teams.message /
  │                        mail.thread / external.web)
  ├─ confidence        ← Decimal(3,2) 0.00 ~ 1.00 (default 1.0)
  ├─ auditTrail        ← JSONB array — append-only event log
  │                       (propose / confirm / reject / edit / dispatch /
  │                        archive / restore)
  ├─ parentArtifactId  ← self-FK — sub-Project chain + dispatch fork
  ├─ createdAt / updatedAt / archivedAt
  └─ index: workspaceId / (entityId, paraLayer) / schemaId /
            parentArtifactId / archivedAt

ArtifactLink (D-bp-artifact-6, 2026-05-23 — multi-parent reference)
  ├─ artifactId        ← Artifact FK (CASCADE delete)
  ├─ workspaceId       ← Workspace FK (CASCADE delete)
  ├─ linkType          ← 'reference' | 'sub_project' | 'cross_link'
  ├─ linkedAt          ← @default(now())
  ├─ linkedById        ← User FK (SetNull on user delete — preserve audit)
  └─ PK (artifactId, workspaceId)  같은 artifact 동일 workspace 중복 link 차단
```

### entity scope flow

`User.entityScopes` 는 sign-in 콜백 (`auth.ts` → `hydrateEntityScopesForUser`) 가 [customers.yaml](https://github.com/soohunkang/blueprint/blob/main/src/lib/entity-scopes.ts) `user_entity_map` + `default_entities_by_domain` 에서 hydrate. admin 이 customers.yaml 미명시 시 DB 의 모든 Entity slug fallback (lock-out 방지). 각 `/api/workspaces/*` 라우트가 `requireWorkspaceEntityAccess` 로 entity gate 검증 (D-bp-entity-3: nullable early-out 제거, 모든 workspace 명시적 entity).

`User.defaultEntity` (D-bp-entity-7): hydration 시 null + non-empty scopes → scopes[0] 자동 set. scope 외 default → scopes[0] fallback. TopNav 의 fallback chain (D-bp-entity-8) = URL `?entity=` → localStorage `axe:lastEntity` → `defaultEntity` → `entityScopes[0]` → "all". createWorkspace fallback = opts.entitySlug → drivePath segment → defaultEntity → entityScopes[0] → throw. 사용자 변경 endpoint = `PATCH /api/user/default-entity { slug }` (server-side `entityScopes.includes(slug)` 검증). D-bp-entity-8 정정: hydrate 가 raw `customers.yaml` 순서 보존 (이전 alphabetic sort 폐기) — yaml list 순서가 진정한 default SOT.

### EntityRole (D-bp-entity-17, 2026-05-22)

entityScopes 가 entity 가시성만 표현하는 한계 해결. `EntityRole { userId, entitySlug, role: admin|owner|member }` 가 entity 별 3-tier 권한 SSOT. hierarchy `admin > owner > member` 를 `src/lib/entity-roles.ts` 의 `hasEntityRole(userId, slug, min)` / `requireEntityRole(...)` 로 평가. tenant-wide `User.role='admin'` (Soohun/ai@) 은 모든 entity 에 implicit admin (row 없어도 bypass — admin fallback 정신 계승).

Hydration 정책: signIn 콜백이 `hydrateEntityRolesForUser` 호출 — entityScopes 에 새로 들어온 slug 마다 `member` 행 자동 생성, scope 에서 제거된 slug 의 행은 revoke. owner/admin overlay 는 오직 `/axe/admin/users` 에서 tenant admin 이 grant (PATCH `/api/users/[id]/entity-roles { entitySlug, role: admin|owner|member|none }`).

MCP scope 매핑 (내부 API `GET /api/internal/entity-roles?email=...`, HMAC bearer `BLUEPRINT_INTERNAL_API_KEY`): admin/owner → hive `[read,write,approve,admin]` · frame `[read,write,close,admin]`; member → `admin` 제외 동일 set; row 없음 → 빈 set (entity 비노출). hive/frame OIDC RP 측 연동은 PR 2/3 에서 별도 결정.

### owned account switching (D-bp-entity-9, 2026-05-22)

`User.ownedBy` — owner (human) → owned (AI agent identity, e.g. ai@/cfo@) 관계. 운영자 1 인이 본인 + agent 여러 identity 운영하는 패턴. switch flow:

1. owner 가 TopNav 의 **사용자 이름 (button)** 을 클릭 → popover 메뉴 펼침 (D-bp-entity-12)
2. owned account 선택 시 `POST /api/auth/switch-account { targetUserId }` → server-side `target.ownedBy === caller.userId` 검증
3. httpOnly cookie `axe:active-user-id` set + reload
4. session callback (`src/lib/auth.ts`): 매 read 마다 cookie 발견 시 ownership 재검증 → `session.user.*` (id/email/name/role/entityScopes/defaultEntity) 모두 target 로 override. JWT 의 authenticated identity 는 untouched (audit trail 보존)
5. revert = 메뉴 에서 self 선택 → 동일 endpoint (no-op, dropdown 즉시 close)

`/api/auth/owned-accounts` GET = dropdown options 채움 (caller + ownedUsers). `isImpersonating=true` 시 trigger button lime border + label color + tooltip. mid-session ownership revoke 시 자동 revert (매 session read 재검증). admin role 도 bypass 불가 — owned-only.

**D-bp-entity-12 (TopNav UX)**: 사용자 이름 자체가 dropdown trigger (M365/Gmail 패턴). 별도 `<select>` 폐기. 메뉴 안에 `+ 다른 계정으로 로그인` 옵션 → `signIn("azure-ad", ..., { prompt: "select_account" })` 으로 Microsoft 계정 picker 호출. click-outside / Escape close + chevron rotate 120ms. data-testid `nav-user-name` 유지 (E2E backward compat).

### Artifact + PARA 지식 레이어 (📐 설계, M6)

Blueprint 가 PARA OS 로 동작하기 위한 typed fact layer. ctx skill 의 markdown PKM 진화형. 상세 = [아키텍처 페이지](/architecture/artifacts).

요지:
- **Artifact** = per-field typed fact (Postgres + JSONB). `schema_id` / `content` / `citations` / `confidence` / `paraLayer` / `entityId` / `audit_trail` / `parent_artifact_id`
- **Citation** = OneDrive `driveItemId+version` / frame query (entity+account+period+queried_at) / hive `employee_id` / Teams `chatId+msgId` / mail `threadId+msgId` / external `URL+fetched_at`. data 중복 0
- **PARA dispatch** = Project artifact 종료 시 Area/Resource/Archive 로 field-level routing. [M3 dispatch](/ops/roadmap#m3--blueprint-para-dispatch-d-bp-entity-1-pr-5) (workspace-level) 의 진화
- **ctx 진화** = curation interface (markdown 은 보조). 흐름: agent propose → ctx review → confirmed fact + audit

근거: [D-bp-artifact-1~5](/ops/decisions). 마일스톤 [M6](/ops/roadmap#m6--blueprint-artifact--para-지식-레이어).

### Schema discovery — frame/hive `/schemas` mirror (2026-05-23, B-bp-artifact-schema-discovery)

M6 의 첫 implementation slice. Blueprint 가 각 MCP 서비스의 `GET /{service}/schemas` envelope 을 fetch + cache + version. SoT 는 MCP 측 (`src/{frame,hive}/mcp/schemas.py`); Blueprint 는 discovery / mirror 만.

- **Prisma 모델**: `McpSchema { service, schemaId, envelopeVersion, body, fetchedAt, firstSeenAt }`. `@@unique([service, schemaId])`. body 변경 시 `fetchedAt` 갱신 + drift warning. 신규 schema_id (예: `frame.balance@2.0`) = 새 row
- **모듈**: `src/lib/artifact/schemas/` (services / fetcher / registry / types). MCP_SERVICES 에 frame + hive 등재 (확장 시 entry 추가만)
- **Admin API**:
  - `GET  /api/admin/mcp-schemas` — 전체 list + count_by_service + registered_services
  - `POST /api/admin/mcp-schemas/refresh` — fetch trigger (per_service `added/changed/unchanged/total` 반환)
- **CLI**: `npx tsx scripts/fetch-mcp-schemas.ts [--service frame]` (docker exec / launchd cron 모두 사용 가능)
- **Token**: 기존 `frame_mcp_token` AppSetting 재사용. hive 는 `hive_mcp_token` AppSetting 또는 `HIVE_MCP_TOKEN` env (현재 미배치, fetcher 가 auth_failed 로 cleanly skip)
- **에러 모델**: status ∈ `ok` / `auth_failed` / `network_error` / `parse_error` — drift 진단 surface 깨끗

다음 step: artifact 본체 Prisma migration ([`B-bp-artifact-prisma`](/ops/backlog)) + citation resolver ([`B-bp-artifact-citation-resolver`](/ops/backlog)).

### hive ↔ Blueprint entity universe SOT

| Source | role |
|---|---|
| `~/.axe/customers.yaml` `entities` | slug list (이 instance 에 활성화된 entity) |
| `hive.shared.entity` | **legal_name / biz_no / fiscal_year_start_month / country_code SOT** (`hive register-entity` CLI) |
| Blueprint `Entity` (이 페이지의 표) | hive metadata mirror + `kind` 분류. seed-entities.ts 가 매 boot upsert. `sys` 는 Blueprint 전용 (hive 미보유 — ad-hoc Teams 1:1 host) |

`/api/entities` GET = 클라이언트 entity 카탈로그 (`entityScopes` 권한 검증, TopNav fetch). hive 새 entity 등록 → Blueprint `seed-entities.ts` 갱신 → 매 boot upsert → 다음 page load 시 클라이언트 자동 인식 (재배포 0).

## Blueprint MCP 서버 (D-bp-mcp-1, 2026-05-21)

Blueprint **자신**의 read-only MCP 서버. Claude 웹 / 데스크탑 / Code 가 Custom Connector 로 등록 가능.

| 항목 | 값 |
|---|---|
| URL | `https://axe.axelabs.ai/blueprint/mcp` |
| Client ID | `482598f7-540c-462c-9dfd-b957651eb804` |
| Application ID URI | `https://axe.axelabs.ai/blueprint/mcp` |
| Scope | `https://axe.axelabs.ai/blueprint/mcp/mcp.access` |
| Tenant | `122fb574-7efa-476a-95b6-bee81bce2cce` (axellc.com) |
| Stack | Python 3.12 + FastMCP + Starlette + uvicorn (frame/hive 패턴 미러) |

### 22 tools (13 read + 7 calendar + 1 mail write + 1 teams write)

| Tool | 분류 | 설명 |
|---|---|---|
| `whoami` | read | 호출 사용자 (Caller) 정보 |
| `list_workspaces` | read | 본인 멤버십 워크스페이스 |
| `get_workspace` | read | 워크스페이스 상세 |
| `list_sessions` | read | 본인 세션 목록 |
| `list_issues` | read | 이슈 목록 (필터 가능) |
| `get_issue` | read | 이슈 상세 |
| `list_agents` | read | 등록된 에이전트 |
| `list_skills` | read | 등록된 스킬 |
| `search_people` | read | 멤버 검색 (이름/이메일) |
| `get_teams_message` | read | Teams `teams.microsoft.com/l/message/...` deep link → 본문·발신자·타임스탬프 + 첨부·인용·인라인이미지 ID (D-bp-mcp-teams-1, D-bp-mcp-teams-2) |
| `get_teams_hosted_content` | read | Teams 인라인 이미지 (hostedContents) → MCP image content block (Claude vision 직접 활용) (D-bp-mcp-teams-2) |
| `get_teams_attachment_file` | read | Teams `reference` 첨부 (OneDrive/SharePoint 공유 파일) `contentUrl` → text 또는 base64. 50 MB 기본 / 100 MB hard cap (D-bp-mcp-teams-3) |
| `send_teams_message` | **write** | Teams 채팅에 **AXE 봇(ai@axellc.com) 신원**으로 발송. chat_id/text/content_type/prefix/dry_run. **admin 전용** (봇 신원 발신 = broadcast-class). 봇이 멤버인 chat 만 (Graph invariant). 발신 시 humanizer + audit footer 자동. 경로 = `/api/teams/post` (CRON_SECRET) → `sendChatReply` (D-bp-mcp-teams-send-1) |
| `list_teams_chats` | read | 최근 Teams chat 목록 (`TeamsInboundMessage` 로그) — `send_teams_message` 용 chat_id 탐색. query(preview·sender ILIKE)/limit. chat당 최근 sender·preview·receivedAt. admin 전용 (D-bp-mcp-teams-send-1) |
| `create_event` | **write** | 호출자 본인 M365 캘린더에 이벤트 생성. subject/start/end/location/body/recurrence/attendees (외부 도메인 OK) (D-bp-mcp-calendar-1) |
| `update_event` | **write** | 기존 이벤트 부분 수정 (eventId + 변경 필드) |
| `delete_event` | **write** | 이벤트 삭제 + attendees 에게 cancellation 자동 발송 |
| `get_event` | read | 단일 이벤트 fetch by id |
| `list_events` | read | 시간 윈도우 내 이벤트 목록 (UTC 정렬) |
| `add_attendees` | **write** | 기존 attendees 보존 + 신규 추가 (case-insensitive dedup), Graph 가 초대 자동 발송 |
| `find_free_time` | read | 다수 attendee 의 free/busy view (Graph `/me/calendar/getSchedule`) |
| `send_mail` | **write** | caller 본인 mailbox 에서 임의 수신자(외부 도메인 OK)로 이메일 발송. to/subject/body(html\|text)/cc/bcc/attachments(base64)/save_to_sent_items/dry_run + admin `as_user_email` send-as (D-bp-mcp-mail-1) |

> **Write tools (calendar) — 기본 동작**: caller 본인 M365 캘린더에 적용. `getClientForUser(callerUserId)` 로 caller 의 delegated token (`Calendars.ReadWrite`) 사용. 외부 도메인 attendee (gmail/naver/personal) = Graph 가 SMTP 초대 메일 처리, 별도 provider 통합 불필요.
>
> **Admin send-as (D-bp-mcp-calendar-2)**: `create_event`/`update_event`/`delete_event`/`get_event`/`list_events`/`add_attendees` 6개 tool 에 `as_user_email` optional 파라미터. caller 의 Blueprint `role === "admin"` 인 경우만 작동 — target user 의 캘린더에 write, event organizer = target user 로 표시. 구현 = app-only Graph token (`getAppOnlyClient()` via client credentials) + `/users/{targetUserId}/events` endpoint. Azure App **Application permission** `Calendars.ReadWrite` + tenant admin consent 필요. 비-admin caller 가 `as_user_email` 사용 시 403 `send_as_forbidden`.
>
> **사용자 첫 호출 전 1회 re-consent 필요**: `Calendars.ReadWrite` scope 가 2026-05-26 추가됨. 기존 사용자가 cached token 으로 calendar tool 호출 시 graph_token_unavailable / 403 응답 → Blueprint web 에 sign out + sign in 으로 incremental consent. admin 이 tenant-wide consent 시 skip.
>
> Read-only Blueprint domain tools (whoami, list_*, get_*, search_people) 은 D-bp-mcp-1 의 "MCP 는 조회 surface, Blueprint web UI 가 issue/session 작성 SoT" 원칙 유지. Calendar 는 별개 도메인 (Microsoft Graph) 이므로 write 채택 — D-bp-mcp-1 의 SoT 와 무관.
>
> **Mail (`send_mail`, D-bp-mcp-mail-1)**: 기본 동작 = caller 본인 mailbox 발송 (`getClientForUser` delegated token; `Mail.Send` delegated 는 이미 `graph.ts` SCOPES 에 존재 → calendar 와 달리 **re-consent 불필요**). Graph `POST /me/sendMail`, body = `{ message: { subject, body, toRecipients, ccRecipients?, bccRecipients?, attachments? }, saveToSentItems }`. 외부 도메인 수신자 = Graph 가 SMTP 처리. **Admin send-as**: `as_user_email` 지정 시 caller 의 Blueprint `role === "admin"` 인 경우만 작동 — app-only token (`getAppOnlyClient()`) + `/users/{targetUpn}/sendMail`, From = target user. Azure App **Application permission** `Mail.Send` + tenant admin consent 필요 (Blueprint Next.js app `2b222356-...`, MCP connector app `482598f7-...` 아님). 비-admin caller 가 `as_user_email` 사용 시 403 `send_as_forbidden`. `dry_run=true` = 메시지 조립·검증·preview 만 반환 (미발송). Graph `sendMail` 은 202 no-body → `message_id` null (Sent 폴더 사본이 durable record). **모든 발송 (`sent`/`dry_run`/`failed`) = append-only `MailSendLog` 1 row** (caller · sentAs · to/cc/bcc count · subject · status · httpStatus) — injection-safety 정책 audit. 에러 코드: `send_as_forbidden` / `recipient_invalid` / `mail_send_not_consented` (Azure 권한 미동의 명시) / `graph_error{status, detail}`.
>
> **Teams tools**: `get_teams_message` 응답 schema: `{ id, chatId, sender, senderId, timestamp, lastEditedDateTime, messageType, bodyText, bodyHtml, bodyContentType, mentions[], attachments[], inlineImageIds[], quotes[] }`. `attachments` = OneDrive 파일 reference (`contentUrl`) / Adaptive Card 등. `quotes` = `messageReference` 자동 resolve (1-level only — quote-of-quote opaque). `inlineImageIds` = body HTML 에서 추출한 hostedContent ID 배열 — 각각 `get_teams_hosted_content(chatId, messageId, hostedContentId)` 로 fetch. `attachments[i].contentUrl` (contentType=reference) 은 `get_teams_attachment_file(contentUrl)` 로 본문까지 fetch.

> **Teams write (`send_teams_message` · `list_teams_chats`, D-bp-mcp-teams-send-1, 2026-06-04)**: Teams 발신을 1급 MCP 도구로 승격 (이전엔 운영자가 내부 API 역설계 + 수작업 DB 조회로만 가능). `send_teams_message` 는 **봇(ai@) 신원**으로 발송하므로 calendar/mail send-as 와 동일하게 **admin-gated** (`is_admin(callerUserId)` DB 재확인). 봇은 자기가 멤버인 chat 에만 post 가능 (Graph invariant). `list_teams_chats` 는 `TeamsInboundMessage` 로그에서 chat_id 를 찾아준다. **구현 = MCP-only** — 새 app route 대신 기존 `/api/teams/post` (CRON_SECRET, `env_file ../.env` 로 MCP 컨테이너에 이미 주입됨) 재사용 → blueprint **app 무배포** (P3005 마이그레이션 drift + main WIP 회피). **후속**: 일관성 위해 `/api/internal/teams/send` (`BLUEPRINT_INTERNAL_API_KEY`) + `TeamsSendLog` audit 로 이전 (app 청정 배포 가능해질 때 — backlog `B-bp-mcp-teams-send-internal-route`).
>
> 세 tool 모두 Blueprint Next.js 의 `POST /api/internal/teams/{fetch-message,fetch-hosted-content,fetch-attachment-file}` 를 docker 네트워크로 호출 (Bearer `BLUEPRINT_INTERNAL_API_KEY` 공유 비밀). Graph 호출은 bot identity (`ai@axellc.com`, app perm `ChatMessage.Read.All` + Sites/Files Read). bot 이 해당 chat 멤버여야 200. 미멤버 chat / share = 403. Channel 컨텍스트 URL 은 501 (follow-up). hostedContent 10 MB 초과 시 413. attachment file 50 MB 기본 (호출 시 `maxBytes` override 가능, 100 MB hard cap).

### 데이터 흐름

```
cloudflared (axe.axelabs.ai/blueprint/mcp)
  → axe-blueprint-mcp-proxy (Caddy, host:3151)
  → blueprint-mcp:3000 (docker network alias)
    → blueprint-mcp-blue:3000 (active) OR blueprint-mcp-green:3000 (passive)
      = Python+FastMCP+Starlette
    → JWTAuthMiddleware
      - Authorization: Bearer <token>
      - iss-dispatch (unverified peek → full RS256 verify):
          · iss == BLUEPRINT_ISSUER  → verify_blueprint_token  (auth_blueprint.py)
              플랫폼 토큰 (D-axe-idp-1, `axe login`). Blueprint JWKS,
              aud=https://axe.axelabs.ai. ← 자기 OP 의 resource server
          · else                     → verify_microsoft_access_token (auth_oidc.py)
              Microsoft Entra access_token (claude.ai Custom Connector).
              JWKS RS256 + multi-aud (client_id GUID OR app_id_uri)
      - email claim → "User" 테이블 lookup (Prisma schema raw SQL) — 양 경로 공통
    → Caller ContextVar 주입
    → FastMCP streamable_http_app → tool handler
```

### 운영

- 컨테이너: `blueprint-mcp-blue` (host port 3152, compose service `mcp-blue`, alias `blueprint-mcp` active) + `blueprint-mcp-green` (host port 3153, compose service `mcp-green`, passive). frame `frame-mcp-blue/green` 패턴 1:1 미러.
- Proxy: `axe-blueprint-mcp-proxy` (host port 3151) → docker alias `blueprint-mcp` → active color.
- DB 직결: `blueprint-postgres` 의 `User`/`Workspace`/`Session`/`Issue`/`Agent`/`Skill` 테이블 read-only
- 헬스체크: `curl http://127.0.0.1:3152/health` (blue) · `curl http://127.0.0.1:3153/health` (green) · `curl http://127.0.0.1:3151/health` (Caddy → 현재 active)
- Swap (zero-downtime): `docker network disconnect blueprint_default blueprint-mcp-blue && docker network connect --alias blueprint-mcp blueprint_default blueprint-mcp-green && docker exec axe-blueprint-mcp-proxy caddy reload --config /etc/caddy/Caddyfile`. cloudflared 비건드림.

### Custom Connector 등록 절차

운영자: `axe secret send AZURE_BLUEPRINT_MCP_CLIENT_SECRET --service blueprint --to <local-part>` → URL 발급 → [`/api/admin/broadcast-dm`](#admin-teams-api--apiadminbroadcast-dm) 으로 수신자 Teams DM 자동 발사. 전체 흐름은 [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send), 수신자 화면 절차 + 함정은 [/architecture/mcp-server-checklist § 7](../architecture/mcp-server-checklist) + [/onboard/claude-frame-setup](/onboard/claude-frame-setup) (동일 절차, MCP URL 만 다름).

### 개발 history

frame/hive 와 패턴 동일하지만 byte-by-byte 미러 실패로 **5층 양파껍질 사고** (PR #331 ~ #335 누적). 회고는 [/architecture/mcp-server-checklist § 10](../architecture/mcp-server-checklist#10-양파껍질-회고-blueprint-mcp-2026-05-21).

## Teams bot integration

Microsoft Teams 1:1 / group chat 에서 `@AXE AI` (또는 `@CFO`) 멘션 시 봇이 Claude Code 세션을 띄워 응답하는 surface. Web UI 의 chat panel 은 2026-04-25 폐기됨 ([architecture-chat-panel-removed](memory)) — Teams 가 사용자-facing primary, Web UI 는 admin/observe 전용.

### Agent identity

| Agent | UPN | 용도 |
|---|---|---|
| **ai** | `ai@axellc.com` | 일반 워크스페이스 dispatcher. 모든 chat 에 기본 멤버. `getBotGraphClient()` 가 가리키는 레거시 single-bot identity. |
| **cfo** | `cfo@axellc.com` | 회계 도메인 (frame MCP 보유). axe CFO 1:1 chat 의 전용 멤버. |

각 agent 는 Microsoft Graph user 계정 1 개 + Blueprint `Agent` row 1 개. `getClientForUser(agentUserId)` 가 agent 의 delegated token 으로 Graph 인증 — agent 가 chat 의 member 일 때만 인증 성공 (multi-bot 1:1 chat 의 자연 invariant). `getBotGraphClient()` 는 ai@ 의 shared client 로 레거시 경로 (ai@ 가 chat 멤버일 때만 작동).

### Inbound 처리 흐름

1. Microsoft Graph change-notification → `/api/teams/webhook` → `TeamsInboundMessage` 인큐
2. processor: `messageType === "message"` filter (systemEvent / typing 제외) → 봇 mention 검증 → trigger agent 해결 (mentioned identity)
3. agent ↔ chat 매핑 검증 (`resolveChatMemberAgentUserId`) → workspace ACL → 첨부 처리 → claude-invoker
4. reply: `sendChatReply` 또는 정정 시 `editChatMessage` (PATCH in-place edit)
5. resolve: `TeamsInboundMessage.resolvedAt` + `resolution` 마킹

### 첨부 처리 (`src/lib/teams/attachments.ts`)

`processTriggerAttachments` 가 trigger message 의 `attachments[]` 를 contentType 별 분기:

| `contentType` | 처리 | 결과 위치 |
|---|---|---|
| `reference` (OneDrive/SharePoint 파일) | `downloadReferenceFile` agent token 으로 download. sha256 dedup → 워크스페이스 기존 파일 일치 시 inbox 복사본 제거 후 기존 path 가리킴 | `_teams_inbox/<YYYY-MM-DD>/<filename>` |
| inline image (`<img src="hostedContents/.../$value">`) | `downloadHostedContent` + content-type sniff → 확장자 추론 | `_teams_inbox/<date>/image_<msgIdShort>_<idx>.<ext>` |
| `messageReference` (Teams quote/reply) | `getChatMessage(chatId, refMsgId, agentId)` 로 quoted body fetch → HTML → plain text → placeholder 상단에 `[인용 메시지]` block 으로 inline | LLM prompt only (disk 저장 X). fetch 실패 시 `attachment.content.messagePreview` 200자 fallback |
| 기타 (card / file 등) | `[unsupported contentType: X]` placeholder (LLM 이 "못 봤다" 답신 위험 — 향후 audit 대상, [known-gaps](/ops/known-gaps)) | — |

multi-bot chat 의 SharePoint URL 은 chat 참여자에게만 read 권한이 grant 되므로 — agent token propagation 이 필수. 레거시 `getBotGraphClient` 만 쓰면 비참여 chat 에서 403/404 발생 ([feedback_multi_bot_attachment_download_gap](memory) 2026-05-13 fix).

### Reply 안전 정책

- **`sanitizeBotReply`**: markdown + HTML defense-in-depth. system-reminder ban, table → 바이너리 only, dangling cross-reference strip 등 4 종 룰 ([architecture_bot_reply_pipeline](memory) PR #157 + PR #165).
- **silent-drop defense-in-depth**: 사용자 @mention 에 무응답 금지 — 5 종 silent-drop class 별 layer 차단 ([feedback_silent_drop_defense_in_depth](memory) PR #261/#263/#266).
- **In-place edit**: 잘못된 reply 정정 시 softDelete + repost X → `editChatMessage` PATCH. 수정됨 표시 1개만 ([feedback_in_place_edit_over_repost](memory)).
- **System prompt** vs **sanitizer**: 시스템 프롬프트 텍스트 룰이 반복 위반될 경우 sanitizer 에 deterministic regex enforcer 추가 (layer 2 fail-safe).

### 알려진 제약 / 후속

- **Context window messageReference**: trigger message 만 quote 처리. `TeamsContextMessage` (rolling context) 의 quote 는 미해석 — [B-bp-teams-context-msgref](/ops/backlog) 후속.
- **Unhandled contentType audit**: card / file / 기타 — [known-gaps](/ops/known-gaps).
- **`get_session` + `list_messages` MCP tool 부재**: agent transcript 외부 비공개 — Stage 1 전 추가 예정.

### Admin Teams API — `/api/admin/broadcast-dm`

운영자 broadcast / 직원 onboarding 흐름에서 bot identity (ai@axellc.com) 가 1:1 Teams DM 직접 발사. 봇이 @mention 받지 않는 **proactive outreach** 경로.

| 필드 | 값 |
|---|---|
| **POST** | `/api/admin/broadcast-dm` (`:3100` 내부, `blueprint.axellc.com` 외부) |
| **Auth** | `Authorization: Bearer $CRON_SECRET` (NextAuth 세션 불필요 — admin-only) |
| **Body** | `\{ emails: string[], text: string, contentType?: "text" \| "html" \}` |
| **흐름** | each email → `User.aadObjectId` lookup → `POST /chats` (oneOnOne, Graph idempotent — 같은 pair 면 같은 chat id) → `POST /chats/\{id\}/messages` |
| **응답** | `\{ summary: \{total, sent, skipped, error\}, results: [\{email, status, chatId?, messageId?, reason?\}] \}` |

소스: `src/app/api/admin/broadcast-dm/route.ts`. 패턴 derivation: `src/lib/agents/cron-failure-alert.ts:postAlertToAdmin`. 운영자 onboarding 패턴은 [/architecture/secrets § 자동 발사](/architecture/secrets#자동-발사--apiadminbroadcast-dm) 참조.

**Agent context** reply (사용자 @mention 후 봇 응답) 은 본 엔드포인트 X — `mcp__blueprint-graph__graph_chat_message_post` MCP tool 사용.

## MCP 클라이언트 (frame backend 호출용)

`src/lib/mcp/frame.ts`:

```typescript
const frameServerUrl = process.env.FRAME_MCP_URL || 'http://frame-mcp:3710/mcp'
const token = await getAppSetting('frame_mcp_token') ?? process.env.FRAME_MCP_TOKEN
// HTTP MCP Streamable transport with Bearer
```

`frame-mcp` 는 docker network `artemis_default` 의 alias (frame-mcp-blue 또는 green 으로 swap).

토큰 해결 순서:
1. AppSetting `frame_mcp_token` (DB 저장, cron job 으로 회전)
2. env `FRAME_MCP_TOKEN` (백업)

## customers.yaml 사용

`src/lib/customers.ts`:

```typescript
export function getCustomerByPublicDomain(host: string): Customer | undefined {
  // host: "axe.axelabs.ai" → axe customer
}

export function userBelongsToCustomer(email: string, customerId: string): boolean {
  // email "ai@axellc.com" → axellc.com → axe
}
```

마운트: 호스트 `/Users/axe/.axe/customers.yaml` → 컨테이너 `/etc/axe/customers.yaml:ro`. mtime 변경 시 자동 재로드.

## docker-compose

```yaml
services:
  app:
    build: . (Dockerfile)
    container_name: blueprint-app
    ports:
      - "3100:3000"   # HTTP
      - "3101:3001"   # WebSocket
      - "3102:7681"   # ttyd (선택)
    volumes:
      - app-data:/app/data
      - claude-data:/home/nextjs/.claude         # skill sync
      - /Users/axe/.axe/customers.yaml:/etc/axe/customers.yaml:ro
    env_file: ../.env
    networks: [artemis_default]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/api/health"]
```

## 환경 변수 (핵심)

```bash
# Auth
NEXTAUTH_URL=https://axe.axelabs.ai
NEXTAUTH_SECRET=                     # ≥32자
AZURE_AD_CLIENT_ID=                  # Microsoft Entra 'Blueprint' app
AZURE_AD_CLIENT_SECRET=
AZURE_AD_TENANT_ID=                  # customers.yaml 의 axe.sso.tenant_id

# Blueprint MCP — 플랫폼 토큰 (D-axe-idp-1) resource-server 신뢰.
# Blueprint MCP 가 자기 OP 가 발행한 `axe login` 토큰을 받게 한다 (미설정 시
# Microsoft Entra 경로만 → 자기 플랫폼 토큰을 unknown_kid 로 401, 2026-06-04 fix).
# JWKS 는 issuer 에서 파생({issuer}/.well-known/jwks.json). 주권 테넌트는 자기 URL 로.
BLUEPRINT_ISSUER=https://blueprint.axellc.com   # = OP issuer (NEXTAUTH_URL)
BLUEPRINT_AUDIENCE=https://axe.axelabs.ai       # 플랫폼 단일 audience

# Database — D-config-17 cutover 후 (2026-05-15~) Postgres.
# ⚠️ D-bp-mcp-3 (2026-05-22): `.env` 에 DATABASE_URL 명시 X 권고 — compose 의
# `${DATABASE_URL:-postgresql://...}` default 가 모든 service (app + mcp blue/green)
# 에 일관 적용. .env 에 SQLite legacy `file:./...` 잔존 시 blueprint-mcp 가
# SQLAlchemy parse fail 로 모든 OAuth 요청 silent 500 (8h 종일 broken incident).
# mcp/config.py 가 postgresql:// → postgresql+asyncpg:// 자동 변환.
DATABASE_URL=postgresql://blueprint:${BLUEPRINT_DB_PASSWORD}@postgres:5432/blueprint
BLUEPRINT_DB_USER=blueprint              # docker-compose default
BLUEPRINT_DB_PASSWORD=                   # vault-pulled (D-ops-17)
BLUEPRINT_DB_NAME=blueprint

# Multi-tenant
CUSTOMERS_YAML_PATH=/etc/axe/customers.yaml

# MCP
FRAME_MCP_URL=http://frame-mcp:3710/mcp
FRAME_MCP_TOKEN=                     # AppSetting fallback

# Claude
CLAUDE_CODE_OAUTH_TOKEN=             # 또는 ANTHROPIC_API_KEY
```

## Admin vs Settings 경계

```
/axe/admin/*    ← 조직 수준 (멤버 관리, 권한 부여, 감사 로그)
/axe/settings   ← 개인 수준 (개인 토큰, 알림 환경설정)
```

Admin 라우트는 `User.role = 'admin'` 만 접근.

## 디자인 시스템 (@axe/ui, D-bp-ui-1, 2026-05-22)

`/Users/axe/axelabs/src/lib/{tokens,styles}/` SSOT 의 디자인 토큰 + 컴포넌트 스타일을 Blueprint 의 `src/app/_axe-ui/` 로 sync. axelabs 메인 앱 · docs.axelabs.ai 와 동일한 토큰 (claret/cream/neon/noir 12-step) 사용.

| 동작 | 명령 |
|---|---|
| SSOT 가져오기 | `npm run sync-axe-ui` (axelabs HEAD + src/lib/ 마지막 변경 SHA 를 VERSION 에 기록) |
| 변경 감지 (dry-run) | `npm run check-axe-ui` — sync 후 stat 보여주고 revert |
| 자동 sync | `predev` / `prebuild` hook 이 매 `npm run dev`/`build` 마다 실행. Docker 빌드 안에서는 axelabs 경로 부재 → graceful skip (committed 산출물 사용). |

### Blueprint 전용 패치 2종 (`scripts/sync-axe-ui.mjs`)

1. **목적지 경로** — canonical (axelabs-docs) 는 `app/_axe-ui/`. Blueprint 는 `src/` source root 라 `src/app/_axe-ui/`.
2. **`fonts.css` 의 `@import url(...)` strip** — Tailwind 4 + Turbopack 이 토큰 파일들을 globals.css 로 inline 한 뒤 fonts.css 의 `@import url(pretendard/d2coding)` 이 다른 rule 뒤로 밀려 CSS spec 위반으로 **브라우저가 silent drop**. sync 단계에서 strip → Pretendard/D2Coding 은 `layout.tsx` 의 `<link rel="stylesheet">` 로 로드 (SSOT 가 Clash Display 에 대해 이미 인정한 회피 패턴의 확장).

### Legacy var alias bridge (`src/app/globals.css`)

35+ tsx 가 `var(--navy)` · `var(--white)` · `var(--gray-ax)` · `var(--dark-border)` 등 기존 토큰을 직접 사용. 비파괴 채택을 위해 globals.css 에서 alias:

```css
--navy: var(--bg-base);          /* light: #f5f1e8 / dark: #1a0610 */
--white: var(--text-primary);    /* light: #1f1a13 / dark: #f2e8ee */
--gray: var(--text-muted);
--dark-border: var(--border-subtle);
/* ...등 */
```

`data-theme="dark"` 토글 시 기존 tsx 무수정으로 자동 전환. 향후 별도 PR 로 inline ref 를 새 토큰명 (`var(--bg-base)` 등) 으로 점진 마이그레이션.

### 테마 토글

`<html lang="en" data-theme="dark">` 기본. 라이트 모드 전환은 `document.documentElement.setAttribute("data-theme", "light")` — 토글 UI 는 별도 후속. SSOT colors.css 가 `[data-theme="…"]` + `.light/.dark` 양쪽 지원 (next-themes 호환 — `[architecture/decisions D-axe-ui-1](/ops/decisions)` 참조).

## 외부 의존성

| 시스템 | 통합 지점 |
|---|---|
| Microsoft Entra ID | NextAuth provider + Graph API |
| Microsoft Graph | Mail, Chat, Files, Teams 권한 |
| frame MCP | HTTP MCP (회계 도구) |
| Claude API | Anthropic SDK (에이전트 실행) |
| Cloudflare Tunnel | external 노출 |
| jsDelivr CDN | Pretendard + D2Coding 폰트 (CSP `style-src` + `font-src` 허용) |
| Fontshare CDN | Clash Display 폰트 (디스플레이 헤딩 옵션) |

## 운영 노트

- **세션 maxAge**: 365일 (NextAuth)
- **Cookie**: `__Secure-next-auth.session-token` (prod)
- **Skill sync**: `claude-data:/home/nextjs/.claude` 볼륨, git-based SOT
- **PTY**: max buffer 2000 lines per session
- **CORS**: WebSocket origin allowlist (`src/server/websocket.ts` L180-183)

## 관련 문서

- [Frame service](/services/frame) — 회계 MCP backend
- [Microsoft Entra ID app registration](/partner/registration/entra-app)
- [/Users/axe/blueprint/docs/project-blueprint.md](https://github.com/soohunkang/blueprint/blob/main/docs/project-blueprint.md) — 마스터 문서 (47KB)

---

<!-- PAGE https://docs.axelabs.ai/services/cli -->

# AXE CLI (axe)

> 토큰 인증으로 모든 AXE 서비스를 쓰는 단일 CLI. MCP 커넥터 불요. 로그인 1회 → 전 서비스.

URL: https://docs.axelabs.ai/services/cli

# AXE CLI (`axe`)

**셸을 가진 에이전트·사람·cron·CI 어디서나** AXE 플랫폼 서비스를 쓰는 단일 명령줄 도구.
MCP 커넥터를 서비스마다 따로 등록할 필요 없이, **로그인 1회로 받은 토큰 하나**로 frame·hive·index·cortex·matrix·blueprint 를 모두 호출한다.

- **에이전트 무관**: Claude Code · Codex · Cursor · Gemini CLI · 사람 터미널 · cron · CI — 셸만 있으면 동작.
- **토큰 인증**: 브라우저 SSO 1회 또는 헤드리스 토큰. 권한은 토큰 스코프가 결정(중앙 관장).
- **플랫폼 SSO** ([D-axe-idp-1](/ops/decisions)): `axe login` → Microsoft SSO 1회 → **Blueprint 가 발행한 플랫폼 토큰** → 전 서비스. 신원·스코프·취소는 [Blueprint](/architecture/platform-identity) 한 곳에서 관장.

> 근거/설계: [D-axe-cli-1](/ops/decisions) (CLI = 외부 표준 접근) · [/architecture/platform-identity](/architecture/platform-identity) (Blueprint = OIDC Provider).

## 에이전트에 붙여넣기 (copy-paste)

당신의 AI 에이전트(Claude Code `CLAUDE.md` · Codex `AGENTS.md` · Cursor rules · 또는 그냥 채팅창)에 **아래 블록을 그대로 복붙**하면, 그 에이전트는 즉시 AXE 전 서비스를 쓸 수 있다. (사람은 바로 아래 **빠른 시작** 블록 참고.)

```text
너는 AXE 플랫폼 CLI `axe` 를 쓸 수 있다 — 셸 명령 하나로 모든 AXE 서비스를 호출한다 (MCP 커넥터 불요).
위치: `axe` (PATH) 또는 `~/axe-cli/axe`.
없으면 설치: macOS/Linux = `curl -fsSL https://axe.axelabs.ai/cli -o ~/axe-cli/axe && chmod +x ~/axe-cli/axe` (PATH 에 추가) · Windows(PowerShell) = `irm https://axe.axelabs.ai/cli.ps1 | iex`.

인증은 1회만: `axe login` (브라우저 SSO). 브라우저 없는 환경이면 `AXE_TOKEN` env 로 토큰 주입.
확인: `axe whoami` → iss=blueprint.axellc.com, email, scope, exp 가 보이면 OK.

서비스 사용법 — 항상 (1) 도구 조회 후 (2) 호출:
  axe <service> tools                          # 그 서비스의 도구 목록 (이름 + 설명)
  axe <service> call <tool> --args '<json>'    # 도구 1개 실행 (JSON 인자)

  axe teams chats [검색어] [--limit N]           # (편의 v0.1.4) Teams 채팅 목록 — chat_id 탐색
  axe teams send <chat_id> --text "..."        # (편의 v0.1.4) Teams 채팅에 AXE 봇으로 발송 (admin)
                                               #   --dry-run 미리보기 · --text - (stdin) · --html
  # ↑ blueprint MCP send_teams_message/list_teams_chats 의 1급 래퍼 (verbose call 대체).
  #   v0.1.4 = axe.axelabs.ai/cli 서빙 LIVE (2026-06-06, docker-cp bridge; image bake = 다음 클린 리빌드 대기 = B-axe-cli-edge-bake). 전 사용자 auto-update 0.1.2 -> 0.1.4.

서비스:
  frame     = 회계/ERP (분개·재무제표·마감)
  hive      = HR/급여 (직원·휴가·명세서)
  index     = 투자 (딜·펀드·IRR·재무모델)
  cortex    = CRM/인맥 그래프
  matrix    = 인프라 모니터링
  blueprint = 플랫폼 (신원·캘린더·Teams·메일)

규칙:
- 도구 이름과 인자 스키마는 *기억하지 말고* 매번 `axe <service> tools` 결과에서 가져와라.
- 순수 셸이라 조합이 그대로 된다: `axe frame tools | grep balance`, for-loop, `| jq` 파이프.
- 기본 엔드포인트는 https://axe.axelabs.ai. 운영 호스트 안에서 돌면 `--local` 로 저지연.
- 호출이 401/403 이면 먼저 `axe refresh`, 그래도 안 되면 `axe login` 을 다시 안내해라.
- 너는 만능 권한이 아니다 — 가능한 동작은 토큰 scope 가 정한다 (`axe whoami` 의 scope).
```

### 빠른 시작 (사람)

복붙 한 덩어리로 설치 확인 → 로그인 → 첫 호출:

```bash
axe --help                       # 또는 ~/axe-cli/axe --help
axe login                        # 브라우저 SSO 1회 (→ Keychain)
axe whoami                       # 토큰 확인
axe frame tools | head           # 첫 호출 (frame 도구 목록)
```

## 설치 / 위치

CLI 는 **각 테넌트가 자기 도메인에서** 서빙한다 (per-tenant — 그 테넌트의 엔드포인트가 baked):

| 자원 | URL (AXE) | 용도 |
|---|---|---|
| CLI 본체 | `https://axe.axelabs.ai/cli` | 다운로드 + `axe self-update` 소스 |
| Windows 설치기 | `https://axe.axelabs.ai/cli.ps1` | PowerShell 1-라인 설치 |

다른 테넌트는 `https://<tenant>.axelabs.ai/cli` · `/cli.ps1` (예: `realchoice.axelabs.ai/cli`).

### macOS / Linux

운영 머신엔 이미 `~/axe-cli/axe` (stdlib Python 단일 파일, 의존성 0). 직접 받으려면:

```bash
mkdir -p ~/axe-cli && curl -fsSL https://axe.axelabs.ai/cli -o ~/axe-cli/axe && chmod +x ~/axe-cli/axe
alias axe="~/axe-cli/axe"            # 셸 rc 에 추가
axe --version
```

### Windows (PowerShell)

한 줄이면 다운로드 + `axe` 명령 등록 + PATH 까지 자동 (macOS `alias` 와 대등):

```powershell
irm https://axe.axelabs.ai/cli.ps1 | iex
```

설치 후 **새 PowerShell** 창에서 `axe --version`. 내부 동작: `%USERPROFILE%\axe-cli\axe` 다운로드 → `axe.cmd` shim 생성 → 사용자 PATH 등록. **Python 3 필요** (`py -3` 또는 `python` 자동 감지 — 없으면 [python.org](https://www.python.org/downloads/) 또는 MS Store 설치 후 재실행).

- **로그인**: `axe login` 브라우저 SSO 는 Windows 에서도 동작(기본 브라우저 + `127.0.0.1` loopback). 브라우저가 안 열리면 출력된 URL 을 수동으로 열거나, 헤드리스는 `axe login --token "<TOKEN>"` / `$env:AXE_TOKEN="<TOKEN>"`.
- **토큰 저장처**: Keychain 이 없으므로 `%USERPROFILE%\.axe-cli\token` (현재 사용자 ACL 로 제한 — CLI 가 `icacls` 로 상속 차단). 우선순위는 동일: `AXE_TOKEN` env > 파일.
- `irm | iex` 가 실행 정책에 막히면(`Set-ExecutionPolicy` 불가 환경) 맨 아래 **부록: Windows 수동 설치** 의 단계별 스니펫을 쓴다.

**AI 에이전트에게 시키기** — 직접 안 치고 싶으면 Claude Code · Codex · Cursor · 채팅창에 아래를 복붙:

```text
내 Windows PowerShell 에 AXE 플랫폼 CLI 를 설치하고 동작까지 확인해줘.
참고: https://docs.axelabs.ai/services/cli (Windows 섹션).

1. PowerShell 에서:  irm https://axe.axelabs.ai/cli.ps1 | iex
   - "실행이 사용되지 않도록 설정" 오류면 먼저:  Set-ExecutionPolicy -Scope Process Bypass -Force
   - "Python 3 not found" 면 python.org 또는 MS Store 에서 Python 3 설치 후 재실행
2. 새 PowerShell 창을 열고  axe --version  으로 PATH 등록 확인
3. 로그인:  axe login   (브라우저 SSO. 안 열리면 출력된 URL 수동 오픈, 또는  $env:AXE_TOKEN = "<토큰>" )
4. 검증:  axe whoami   그다음   axe frame tools
각 단계 결과를 확인하고, 막히면 멈춰서 무엇이 어떻게 틀렸는지 알려줘. 토큰 값은 절대 출력하지 마.
```

## 로그인

### 1) 브라우저 SSO (기본 — 사람/대화형)

```bash
axe login
```
브라우저가 열리고 **Microsoft 로그인 1회** → 자동으로 토큰을 받아 **macOS Keychain** 에 저장한다. (내부: loopback PKCE → Blueprint `/oauth/authorize` → Entra → 토큰 교환.) 끝나면:

```bash
axe whoami
# {
#   "iss": "https://blueprint.axellc.com",   ← Blueprint 발행
#   "email": "you@axellc.com",
#   "scope": "openid profile email frame hive index cortex matrix blueprint",
#   "aud": "https://axe.axelabs.ai", "exp": ...
# }
```

### 2) 헤드리스 토큰 (Codex / CI / cron / 브라우저 없는 환경)

브라우저를 못 여는 환경은 토큰을 직접 준다 (`gh auth login --with-token` 모델):

```bash
axe login --token "<TOKEN>"      # 키체인 저장
axe login --token -              # stdin 으로 (echo 회피)
export AXE_TOKEN="<TOKEN>"        # env 가 키체인보다 우선 (CI/샌드박스)
```

토큰 해석 우선순위: **`AXE_TOKEN` env > macOS Keychain > `~/.axe-cli/token`** (0600). `AXE_TOKEN` env override 가 헤드리스(CI·Codex·샌드박스)의 표준 경로 — 키체인 없이 동작하고 셸 세션에만 살아 디스크에 남지 않는다.

> **device-code grant (RFC 8628) 은 계획 단계** (`B-axe-cli-device-code`, [D-axe-idp-1](/architecture/platform-identity) Phase 3). 브라우저는 못 열지만 다른 기기로 코드 입력은 가능한 환경(예: 원격 SSH 셸)을 위한 흐름 — **아직 미구현**. 그때까지 헤드리스는 위의 `AXE_TOKEN` env / `axe login --token -` (stdin) 을 쓴다.

### 토큰 갱신 / 로그아웃

```bash
axe refresh        # 저장된 refresh 토큰으로 access 토큰 무중단 갱신
axe logout         # 저장 토큰 제거 (서버측 취소는 Blueprint 에서)
```

## 서비스 호출

```bash
axe <service> tools                          # 도구 목록
axe <service> call <tool> --args '<json>'    # 도구 실행
```

서비스: **`frame`** (회계) · **`hive`** (HR) · **`index`** (투자) · **`cortex`** (CRM) · **`matrix`** (인프라) · **`blueprint`** (플랫폼).

예시:

```bash
axe frame tools                                          # frame 54 도구
axe frame call query_balance --args '{"entity":"axec","account":"1101"}'
axe hive call employee_search --args '{"query":"강"}'
```

### 엔드포인트 선택

| 플래그 | 대상 | 용도 |
|---|---|---|
| (기본) | public `https://axe.axelabs.ai/<svc>/mcp` | 외부/원격 |
| `--local` | `127.0.0.1` (호스트 내) | 운영 머신 로컬 (저지연) |
| `--endpoint <URL>` | 임의 | 디버그 |

`axe login --local` 로 기본 모드를 로컬로 고정 가능. local 호출은 DNS-rebinding 가드 통과를 위해 public Host 헤더를 자동 첨부한다.

## 토큰에 뭐가 들었나

Blueprint 발행 플랫폼 토큰(RS256)은 `iss=https://blueprint.axellc.com`, `email`(→ 각 서비스가 entity 권한으로 매핑), `aud=https://axe.axelabs.ai`(전 서비스 공통), `scope`(서비스 grant), `exp`(1h, refresh 로 갱신). 각 서비스는 Blueprint JWKS(`/.well-known/jwks.json`)로 서명을 검증한다. `axe whoami` 로 언제든 확인.

## 에이전트에서 쓰기 (조합성)

CLI 는 syscall 층이라 셸 조합이 그대로 통한다 — 모델 왕복 없이 pipe·loop·jq:

```bash
# frame 모든 도구 이름만
axe frame tools | awk '{print $1}'
# 여러 entity 잔액을 한 번에
for e in axec axev; do axe frame call query_balance --args "{\"entity\":\"$e\",\"account\":\"1101\"}"; done
```

Codex·CI 에선 `AXE_TOKEN` env + 아웃바운드 HTTPS 허용만 있으면 동작 (브라우저 불요).

## 거버넌스

권한은 **토큰 스코프**가 결정하고, 발행·스코프·취소·감사는 [Blueprint](/architecture/platform-identity) 중앙에서 관리한다. 토큰 유출 시: 짧은 exp(1h) + refresh 취소 + 스코프로 blast radius 제한. 운영자 `axe`(vault/deploy)와 고객 CLI(업무 명령)는 **스코프 분리** — 만능 바이너리를 고객에 주지 않는다.

## 문제 해결

`axe login` 은 됐는데 서비스 호출이 401/403 이면 → [/onboard/troubleshooting](/onboard/troubleshooting) 의 "Blueprint 플랫폼 토큰" 섹션 (서비스가 `BLUEPRINT_ISSUER` 미설정 / aud 불일치 / email 미매핑 등). public 호출이 403 이면 CLI 가 구버전일 수 있음 — User-Agent 헤더가 있어야 Cloudflare 봇 차단을 통과한다(`axe-cli` 0880417+).

**Windows 특이사항**

- **`irm | iex` 가 막힘** (`스크립트 실행이 사용되지 않도록 설정`): 현재 세션만 허용 후 재실행 — `Set-ExecutionPolicy -Scope Process Bypass -Force; irm https://axe.axelabs.ai/cli.ps1 | iex`. 또는 아래 수동 설치.
- **`axe` 명령 인식 안 됨**: PATH 는 **새 터미널**부터 적용된다 — 새 PowerShell 창에서 재시도.
- **`python` 을 못 찾음**: `py -3` 또는 `python` 이 PATH 에 있어야 한다. (MS Store Python 은 `py` 런처가 없을 수 있어 설치기가 `python` 으로 폴백한다.)
- **self-update 거동**: Windows 는 `.cmd` shim → python 구조라, 자동 업데이트 후 `os.execv` 대신 새 프로세스로 재실행한다(`axe-cli` 0.1.1+). 토큰 파일은 `icacls` 로 현재 사용자에 한정.
- **`axe login` 이 `✓` 출력에서 크래시처럼 보임** (`UnicodeEncodeError`, cp949/cp932 콘솔): 토큰은 배너 출력 *전에* 저장되므로 **인증은 이미 성공**한 상태였다 — `axe whoami` 로 확인. **0.1.2+ 에서 해결**(CLI 가 stdout/stderr 를 UTF-8 로 reconfigure + `cli.ps1` shim 이 `set PYTHONUTF8=1`). 구버전이면 `axe self-update` 한 번. 헤드리스/CI 는 애초에 브라우저 SSO 대신 `$env:AXE_TOKEN` 권장.

## 부록: Windows 수동 설치

`irm | iex` 대신 단계별로 (실행 정책 제약 환경):

```powershell
$dir = "$env:USERPROFILE\axe-cli"
New-Item -ItemType Directory -Force $dir | Out-Null
Invoke-WebRequest https://axe.axelabs.ai/cli -OutFile "$dir\axe" -UseBasicParsing -Headers @{'User-Agent'='axe-cli/setup'}
@"
@echo off
set PYTHONUTF8=1
python "%USERPROFILE%\axe-cli\axe" %*
"@ | Set-Content "$dir\axe.cmd" -Encoding ASCII
$p = [Environment]::GetEnvironmentVariable('Path','User')
if (($p -split ';') -notcontains $dir) { [Environment]::SetEnvironmentVariable('Path', "$p;$dir", 'User') }
# 새 PowerShell 창에서:
#   axe --version
#   axe login                          # 브라우저 SSO
#   $env:AXE_TOKEN="<TOKEN>"; axe whoami; axe frame tools   # 또는 헤드리스
```

shim 의 `python` 은 본인 환경에 맞게 `py -3` 로 바꿔도 된다.

---

<!-- PAGE https://docs.axelabs.ai/services/cortex -->

# Cortex

> AI-native relationship CRM — artifact-first, per-user private, Google Contacts canonical. Rust + axum + sqlx.

URL: https://docs.axelabs.ai/services/cortex

# Cortex

**한 줄 소개**: 강수훈 개인이 Windows OneDrive 의 `Network_CRM.xlsx` 로 운영해온 1인용 투자 네트워크 CRM 을 platform 안으로 끌어들임. artifact-first ([D-cortex-1](/ops/decisions)), per-user private RLS ([D-cortex-2](/ops/decisions)), Google Contacts 단방향 pull canonical ([D-cortex-3](/ops/decisions)), Day 1 multi-user ([D-cortex-5](/ops/decisions)), MCP + read-only 웹 UI ([D-cortex-6](/ops/decisions) → [D-cortex-6.1](/ops/decisions)), Rust ([D-cortex-7](/ops/decisions)). 2026-05-26 출발 · 2026-05-29 웹 UI 추가.

기존 `/Users/axe/cortex` (file-based "VC 심사역 AI 기억 시스템", 2026-03 시작) 은 도메인이 유사했지만 모델이 새 설계와 완전히 달라 `.legacy.20260526/` 으로 폐기 보존.

## 사용하기 — 설치 후 무엇을·어디서·어떻게 (직원용)

> **여기부터 읽으세요.** Cortex 에는 "로그인해서 클릭하는" 별도 앱 화면이 없습니다. 평소 쓰는 **AI 에이전트(Claude Code · Codex · Cursor · claude.ai 채팅)에게 한국어로 시키면**, 그 에이전트가 `axe` CLI 로 Cortex 를 대신 호출합니다. 데이터를 눈으로 둘러보기만 할 때는 **읽기 전용 웹 포털**이 따로 있습니다. 아래 ②~③(스택·포트·인증 등)은 운영자/개발용이므로 직원은 건너뛰어도 됩니다.

### 접근 방법 3가지 — 뭘 고를까

| 방법 | "front end" 가 뭐냐 | MS 관리자 권한 |
|---|---|---|
| **① axe CLI (권장)** | **너의 AI 에이전트** (Claude Code·Codex·Cursor·claude.ai) — 또는 그냥 터미널 | 불필요 ✅ |
| ② 읽기 전용 웹 포털 | 브라우저 — [`axe.axelabs.ai/cortex`](https://axe.axelabs.ai/cortex) | 불필요 ✅ |
| ③ claude.ai MCP 커넥터 | claude.ai 커넥터 설정 화면 | **MS 관리자 consent 필요** ⚠️ |

> **관리자 계정이 아니면 ①을 쓰세요.** claude.ai 에서 Custom Connector 추가가 `Authorization with the MCP server failed … Entra Trace ID …` 로 막히는 건 정상입니다 — ③의 커넥터 흐름은 MS 테넌트 관리자의 사전 consent 가 있어야 동작하기 때문입니다([인증](#인증)). **커넥터는 안 해도 됩니다.** `axe` CLI 는 본인 Microsoft 로그인만으로 Cortex 를 쓰게 해주므로 ①로 우회하면 끝입니다.

### ① axe CLI — 3단계

**1. 설치 + 로그인 (한 번만)** — 상세/문제해결은 [AXE CLI](/services/cli):

```bash
mkdir -p ~/axe-cli && curl -fsSL https://axe.axelabs.ai/cli -o ~/axe-cli/axe && chmod +x ~/axe-cli/axe
alias axe="~/axe-cli/axe"            # 셸 rc 에도 추가
axe login                            # 브라우저로 Microsoft 로그인 1회
axe whoami                           # 출력 scope 에 cortex 가 보이면 준비 끝
```

**2. "front end" = 너의 AI 에이전트.** Claude Code · Codex · Cursor · claude.ai 채팅 중 아무거나 열고, 아래 블록을 그대로 붙여넣으면 그 에이전트가 Cortex 를 쓸 수 있게 됩니다:

```text
너는 AXE 의 `axe` CLI 로 Cortex(투자 인맥 CRM)를 쓸 수 있다 — MCP 커넥터 불요.
항상 (1) 도구를 먼저 조회하고  axe cortex tools
     (2) 그 스키마대로 호출한다  axe cortex call <tool> --args '<json>'
주요 도구:
  search_person   이름·회사·메모 등 아무 필드나 substring 으로 인물 검색
  get_person      한 인물의 상세 + citation + 최근 이력
  register_person 신규 인물 등록 (Google 연동 시 내 연락처에도 생성)
  log_interaction 미팅·통화·이벤트 기록 (참석자별 관계도 자동 생성)
  classify_person 인물에 분류 태그 부착 (예: 담당=나, 구분=LP)
  connect_google  내 Google 연락처를 Cortex 로 동기화 시작
규칙:
- 도구 이름·인자는 외우지 말고 매번 `axe cortex tools` 결과에서 가져와라.
- 딜 코멘트·협상 의견·사적 메모처럼 민감하면 visibility=private 로 저장할지 나에게 먼저 물어봐라(기본 shared).
- 호출이 401/403 이면 먼저 `axe refresh`, 그래도 안 되면 `axe login` 재실행을 안내해라.
```

붙여넣은 뒤에는 그냥 한국어로 시키면 됩니다 — 예: *"홍길동 연락처 찾아줘"*, *"방금 ABC캐피탈 김상무랑 한 미팅 기록해줘"*, *"내 구글 연락처 Cortex 에 연동해줘"*.

**3. (선택) 터미널에서 직접** — 에이전트 없이 손으로 칠 때:

```bash
axe cortex tools                                          # 12개 도구 목록
axe cortex call search_person   --args '{"q":"홍길동"}'
axe cortex call register_person --args '{"name":"김상무","org":"ABC캐피탈","memo":"2026 Q2 소개"}'
axe cortex call connect_google  --args '{}'               # → 반환된 authorize_url 을 브라우저로 열기
```

### ② 읽기 전용 웹 포털 — 눈으로 둘러보기

추가·수정 없이 **보기만** 할 거면 브라우저로:

- [`https://axe.axelabs.ai/cortex`](https://axe.axelabs.ai/cortex) → Microsoft 로그인 → 대시보드 / 인물 / 조직 / 딜 / 상호작용 / 관계 그래프
- 본인 데이터만 보입니다(owner-scoped). **읽기 전용**이라 등록·수정은 ①(CLI/에이전트)로 합니다.

### Google 연락처 연동 (1회)

Cortex 는 본인 Google 연락처를 canonical source 로 **단방향 pull** 합니다:

1. 에이전트에 *"내 구글 연락처 연동해줘"* (또는 `axe cortex call connect_google --args '{}'`)
2. 반환된 `authorize_url` 을 브라우저로 열어 Google consent
3. "✓ 연결 완료" 후 다음 sync cycle(또는 `sync_google_now`)부터 자동 유입. 민감 라벨(`Personal`/`HPE`)이 붙은 연락처는 자동 제외됩니다(아래 visibility / private partition 정책 참조).

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Rust 1.95+ ([D-cortex-7](/ops/decisions)) |
| HTTP | axum 0.7 + tower-http + tokio |
| DB | PostgreSQL 16 (sqlx 0.8, rustls, runtime-tokio) |
| Migration | `sqlx migrate run` (alembic 대신, raw .sql) |
| 인증 | jsonwebtoken (Entra ID RS256 JWKS, HS256 state) + reqwest (rustls-tls) |
| Google API | raw reqwest (oauth2 crate 미사용 — rustls 일관성) |
| Logging | tracing + tracing-subscriber (env-filter, json) |
| CLI | clap 4 (subcommand: migrate / mcp-http / show-settings) |
| 단일 binary | 6.7 MB stripped (multi-stage Dockerfile) |

## 포트 (32xx)

| 포트 | 컨테이너 | 용도 |
|---|---|---|
| 3200 | cortex-postgres | PostgreSQL 16 |
| 3210 | cortex-mcp-blue | MCP HTTP/SSE (active) |
| 3211 | cortex-mcp-green | MCP HTTP/SSE (passive, blue/green) |
| 3212 | axe-cortex-proxy | Caddy selector (blue/green swap) — task 15 |

Cloudflared origin: `axe.axelabs.ai/cortex/* → host.docker.internal:3212` (axe-tunnel Docker, task 16).

## 접속

| Endpoint | 인증 | 용도 |
|---|---|---|
| `https://axe.axelabs.ai/cortex/healthz` | 없음 | health probe |
| `…/cortex/mcp/.well-known/oauth-protected-resource` | 없음 | RFC 9728 metadata — **claude.ai 가 실제 조회하는 resource-level 경로** (apex `/.well-known/…` + `/cortex/.well-known/…` 도 동일 응답 제공) |
| `https://axe.axelabs.ai/cortex/mcp` | Entra ID Bearer | MCP JSON-RPC 2.0 endpoint |
| `https://axe.axelabs.ai/cortex/schemas` | Entra ID Bearer | typed fact schema registry (mcp_schema 테이블) |
| `https://axe.axelabs.ai/cortex/oauth/google/callback` | state JWT 자체검증 | Google OAuth Web flow callback |
| `https://axe.axelabs.ai/cortex` | 없음 | 웹 UI 랜딩 ([D-cortex-6.1](/ops/decisions)) — 미인증 시 `/cortex/login` 으로 303 |
| `https://axe.axelabs.ai/cortex/login` · `/login/start` · `/login/callback` | 없음 (Entra federation) | 웹 SSO 흐름. `/login/callback` 은 Entra Redirect URI 에 등록 필수 |
| `https://axe.axelabs.ai/cortex/home` · `/people` · `/orgs` · `/deals` · `/interactions` · `/relationships` · `/a/:id` | `cortex_session` 쿠키 (HS256, `tok="web"`, 8h sliding) | read-only 운영자 포털 (dashboard / 리스트 / detail) |
| `POST /cortex/logout` | (idempotent) | 세션 쿠키 즉시 만료 |

## 데이터 모델 (artifact-first)

5 테이블, RLS FORCE + cortex_app NOSUPERUSER role + append-only trigger.

```
artifact         -- typed fact (kind = person | organization | deal | interaction | relationship | note | attribute)
  └─ payload jsonb   ← 약속: known fields + 임의 미정의 필드 (additionalProperties: true)
  └─ owner_id        ← RLS 격리 키
  └─ visibility      ← shared | private (D-cortex-9) — outward propagation gate. default shared
  └─ schema_version  ← mcp_schema 와 매칭

citation         -- evidence (kind = google_contact | remember_card | teams_msg | mail_thread | frame_query | external_url)
  └─ artifact_id FK + ref jsonb (kind 마다 다른 shape)

artifact_event   -- append-only audit
  └─ op (propose | confirm | reject | edit | dispatch | archive | restore)
  └─ actor (user email 또는 system:google-sync)
  └─ payload_before / payload_after (diff 기록)
  └─ UPDATE/DELETE 는 trigger 가 raise

mcp_schema       -- (kind, version) → JSON schema. payload 검증 advisory 가능 (현재 미강제)

google_oauth_token  -- per-user, owner_id primary key
  └─ refresh_token bytea ← pgp_sym_encrypt(CORTEX_PII_PASSPHRASE_AXEC)
  └─ status (active | revoked | expired)
```

**Relationship 은 artifact 의 한 kind** (kind='relationship', payload = `{from_artifact_id, to_artifact_id, edge_kind, context}`). edge_kind 예: `introduced_by` / `works_at` / `attended_meeting` / `lp_invested_fund` / `referenced_in_deal` / `co_attended`. 그래프 쿼리는 1차에 JSONB GIN index, 부족 시 materialized artifact_link 추가.

**임의 정보 적재 유연성**: artifact.kind, citation.kind 가 free-form string (DB 측 enum 강제 X). payload 가 JSONB 라 어떤 구조도 round-trip. 사전 정의 안 된 `kind='unicorn'`, citation `kind='voice_memo'`, 미정의 payload 필드 `aircraft_collection_hobby` 모두 무손실 저장. 검증 layer 는 (1) MCP tool inputSchema (additionalProperties: true), (2) mcp_schema 등록 advisory, (3) 운영 hygiene 쿼리 (`SELECT DISTINCT kind FROM artifact GROUP BY 1`). 안전은 RLS + append-only audit + citation provenance 로.

## visibility / private partition ([D-cortex-9](/ops/decisions))

**핵심**: 현재 모든 artifact 는 이미 RLS (`owner_only`) 로 owner 본인에게만 보임 — 타인·관리자·감사자가 볼 경로 자체가 없음. 따라서 `visibility` 는 본인 vs 타인 격리가 아니라, 데이터가 **owner 의 RLS 섬을 벗어나는 미래 표면을 막는 propagation gate**. 그 표면 = **Blueprint M6 artifact mirror** ([D-bp-artifact-1](/ops/decisions), [/architecture/artifacts](/architecture/artifacts)) — Blueprint `Artifact` 테이블은 `workspace_id`+`entity_id` scope 이라 `owner_id`·`visibility` 가 없어 mirror 시 owner 격리가 풀림. M6 이 아직 📐 설계 (2026 Q4) 라 mirror 가 생기기 전 지금 박아둠.

| tier | owner 본인 세션 | 바깥 (mirror/export/dashboard) | Google push |
|---|---|---|---|
| `shared` (기본) | 보임 | **보임** (`WHERE visibility='shared'`) | register_person 시 createContact |
| `private` | 보임 | **절대 안 나감** | **skip** |

- **기본값 `shared`**: Google 동기화 base 연락처는 이미 Google 에 존재하는 저민감 canonical. 민감 분류(HPE 등)·xlsx import sensitive 컬럼·명시 flag 만 `private`. 신규 민감 데이터(HPE 138건)가 아직 미유입(`B-cortex-xlsx-import-run`)이라 backfill 불필요.
- **계약 (Phase 2, M6 착수 시)**: 모든 outward propagation 은 `visibility='shared'` 만. `private` artifact 의 audit event 는 redact. payload 내 field-level privacy (`payload.private.*` 하위객체 + `CORTEX_PII_PASSPHRASE` pgp) 는 같은 단계.
- **§6 스톱갭 (Phase 0)**: `list_persons(exclude_classification_key=, exclude_classification_value=)` 로 `구분=개인` 같은 분류 태그 항목을 export 에서 제외. `skip_audit_payload=true` 로 민감 등록·수정의 before/after snapshot 생략 (메타만).
- **sync 유입 필터 (Phase 1)**: visibility 가 *이미 유입된* artifact 의 전파 게이트라면, 이쪽은 **유입 자체를 막는 더 앞단 게이트** — 민감 라벨 연락처를 Cortex 에 안 들이는 가장 강한 보장. Google People sync 가 contactGroup(라벨) 이름 기준으로 거른다: `CORTEX_SYNC_GROUP_BLACKLIST`(기본 `Personal,HPE`) 라벨이 붙은 연락처는 애초에 들어오지 않음. `CORTEX_SYNC_GROUP_WHITELIST` 설정 시 그 라벨 보유 연락처만 통과(gate)하고 blacklist 가 더 강한 veto. 동작: sync 시작 시 contactGroups id→name 맵 1회 로드(필터 비활성이면 호출 생략) → 연락처별 `contactGroupMembership` 를 case-insensitive 매칭. 맵 로드 실패 시 해당 owner cycle 을 fail-safe 로 통째 skip(민감 라벨 누유 방지, 다음 cycle 재시도, 한 owner 실패는 다른 owner 무영향). 제외 수는 `sync_google_now` 의 `skipped_by_label` 로 보고. **이미 유입된 항목은 소급 삭제 안 함** — 그건 Phase 0 export 제외 / 별도 정리 영역. ([B-cortex-visibility-phase1-sync-filter](/ops/backlog))
- **visibility 결정 UX (누가 private 을 정하나)**: 기본값 `shared`. 행위자 3분 — 사용자(자연어) → 커넥터 LLM(인자 결정, 질문 가능) → Cortex MCP(실행, 질문 불가). write tool 4종(register/classify/update_person + log_interaction) description 에 **SENSITIVITY RULE** 을 심어, `visibility` 미지정 + 민감 가능 내용(딜 코멘트·협상 의견·사적 메모·비공개 미팅)이면 커넥터 LLM 이 저장 전 *"private/shared?"* 를 **먼저 확인**. 일반 공개 정보(이름·소속·전화)는 묻지 않고 shared. (MCP 는 요청-응답이라 직접 못 물음 → LLM-guidance 패턴.) `register_person`/`log_interaction` 은 `visibility=private` 시 Google push·외부 전파 생략.
- **필드 단위 — 공유 인물 + 비공개 메모**: person 은 `register_person(visibility=shared)`, 민감 메모는 **별도** `classify_person(..., visibility=private)` attribute 로 (둘이 별개 artifact 라 각자 visibility). 한 payload 안의 특정 필드만 private 은 Phase 2.
- **Phase 3 (opt-in)**: client-key sealed E2E — 서버 복호화 불가, search·Google push 포기 trade-off.

## MCP Tools (12)

`POST /cortex/mcp` JSON-RPC 2.0. Bearer auth 필수. **모든 tool inputSchema property key 는 ASCII** (`^[a-zA-Z0-9_.-]{1,64}$`) — Korean key 한 개라도 들어가면 Anthropic API 가 tools/list 전체를 400 으로 거부 ([known-gaps](/ops/known-gaps) Cortex 함정 #6). 값(value) 은 Korean 자유.

| Tool | 동작 | 비고 |
|---|---|---|
| `whoami` | 인증된 사용자의 email + sub claim 반환 | 헬스 체크 |
| `list_persons` | kind='person' artifact 페이지네이션 (owner-scoped) | limit 1-200, offset, `visibility` (shared\|private\|all, 기본 all), `exclude_classification_key`/`_value` (share-safe export §6) |
| `search_person` | payload::text ILIKE substring (임의 필드 매칭) | 미정의 필드도 검색 가능 |
| `get_person` | artifact + citations + 최근 20 event 묶음 | UUID |
| `register_person` | 신규 person artifact 생성 — payload 가 args 전체 (additionalProperties 그대로) + 'propose' audit event. Google 연동 사용자는 People API `createContact` 까지 수행 후 `google_contact` citation 추가 ([D-cortex-4](/ops/decisions) opportunistic push) | payload key `memo` (ASCII) — Korean key 금지. `visibility`(기본 shared) — **private 면 Google push skip**. `skip_audit_payload` |
| `log_interaction` | interaction artifact + participants 마다 relationship artifact (edge_kind='attended', interaction 의 visibility 상속) | 미팅·통화·이벤트. `visibility`(비공개 미팅) + `skip_audit_payload` |
| `list_interactions` | interaction 페이지 + person_id 필터 (payload->'participants' @> jsonb_array) | |
| `classify_person` | person 에 typed 분류 attribute 부착 — kind='attribute' artifact (subject_artifact_id + key + value). (subject, key) idempotent | key free-form (`HPE`/`AXEV`/`구분1`/`담당`/`Top100` 등). `visibility`(민감 분류는 private) + `skip_audit_payload` |
| `update_person` | person payload JSONB shallow-merge patch + before/after audit event | **Google push 안 함** ([D-cortex-3](/ops/decisions) 단방향). 신규는 register_person, 분류는 classify_person. `visibility` re-tag(shared↔private) + `skip_audit_payload` (snapshot 생략) |
| `connect_google` | Google OAuth Web flow 시작 — authorize_url 반환 (10분 TTL state JWT) | 사용자가 브라우저 → consent → callback |
| `disconnect_google` | refresh_token revoke (DB status='revoked' + Google revoke best-effort) | idempotent |
| `sync_google_now` | 다음 cycle 안 기다리고 즉시 1회 Google → Cortex sync | inserted/updated/pages/`skipped_by_label` 카운트 반환 (`skipped_by_label` = 라벨 필터로 유입 제외된 연락처 수, [D-cortex-9](/ops/decisions) Phase 1) |

### Schema discovery — `GET /cortex/schemas`

Blueprint artifact + PARA layer ([D-bp-artifact-1](/ops/decisions)) 미러를 위해 frame 패턴 차용. 현재 빈 응답 — mcp_schema 테이블에 typed fact schema 등록 시 노출 (`person`, `organization`, `deal`, `interaction`, `relationship`, `note` schema 향후 등록).

## 인증

### Entra ID (RS256, OAuth-RP)

- App: "Cortex MCP", appId=`60d04ea8-5d7b-453e-a4c0-af421b4689f5` (등록 2026-05-26 via az CLI)
- 형식: frame_mcp / hive_mcp / blueprint_mcp 와 동형 (signInAudience=AzureADMyOrg, requestedAccessTokenVersion=2, identifierUris=`https://axe.axelabs.ai/cortex/mcp`, scope `mcp.access`, webRedirectUris=claude.ai+claude.com `/api/mcp/auth_callback`)
- 검증: JWKS 1h TTL cache (RwLock fast→slow path), RS256, audience (MCP URI + client_id 둘 다 허용), issuer (`login.microsoftonline.com/{tenant}/v2.0`), exp/iat 자동
- 401 응답: RFC 9728 § 5.1 WWW-Authenticate 4-tuple (realm + error + error_description + resource_metadata URI)
- email 추출 fallback: `email` → `preferred_username` → `upn`

### claude.ai connector 등록 흐름 (Microsoft-direct federation)

frame 의 "직접-Microsoft" 패턴과 동형 ([D-cortex-8](/ops/decisions)). claude.ai 또는 Claude Code 에서 Cortex 를 custom connector 로 추가할 때:

1. **Connector URL**: `https://axe.axelabs.ai/cortex/mcp`
2. claude.ai 가 `https://axe.axelabs.ai/cortex/mcp` → 401 → `WWW-Authenticate` 의 `resource_metadata` 따라 **resource-level** RFC 9728 metadata 조회. Cortex 는 3 경로 모두 제공: `/.well-known/oauth-protected-resource`, `/cortex/.well-known/oauth-protected-resource`, **`/cortex/mcp/.well-known/oauth-protected-resource`** (claude.ai 가 실제로 찌르는 경로 — 빠지면 discovery 실패 → origin `/authorize` fallback → blueprint apex 404, [known-gaps](/ops/known-gaps) Cortex 함정 #3).
3. metadata 의 `authorization_servers[0]` = **Microsoft** (`https://login.microsoftonline.com/{tenant}/v2.0`), `scopes_supported` 에 `https://axe.axelabs.ai/cortex/mcp/mcp.access` 포함. → claude.ai 는 Microsoft 의 RFC 8414 metadata 를 직접 읽고 Microsoft 로 authorize.
4. claude.ai 가 **client_id + client_secret 직접 입력**을 요구 (confidential client). 입력값:
   - client_id = `60d04ea8-5d7b-453e-a4c0-af421b4689f5`
   - client_secret = vault `cortex/axe/oauth-client-secret`
5. Microsoft consent → claude.ai 가 RS256 access token 수령 (aud = MCP App ID URI 또는 client_id) → 이후 `/cortex/mcp` 호출에 Bearer 첨부.

> **AS proxy 는 dormant** ([D-cortex-8](/ops/decisions)): `src/oauth_as.rs` 에 full RFC 8414 + /authorize→Microsoft + /token PKCE + /register DCR 프록시를 구현했으나, frame 의 Microsoft-direct 가 live 라 **현재 미사용**. `authorization_servers` 를 cortex 자신으로 돌리고 싶을 때(예: claude.ai 가 client_secret 입력을 못 받는 클라이언트 지원) 활성화. `verify_cortex_jwt()` 만 auth.rs 가 HS256 운영자 path 용으로 사용 중.

### Google OAuth 2 (Web flow, per-user)

- Cortex → Google People API on behalf of user
- App: "Cortex" Web client (Cloud Console, GCP project Gemini) — 등록 task 8
- Authorized redirect URI: `https://axe.axelabs.ai/cortex/oauth/google/callback`
- Consent screen: External + testing mode (100 사용자 한도, AXE Labs 인원 충분)
- Scope: `https://www.googleapis.com/auth/contacts` (read + write — read 는 sync, write 는 register_person → createContact)
- refresh_token 저장: `google_oauth_token.refresh_token bytea` = `pgp_sym_encrypt(token, CORTEX_PII_PASSPHRASE_AXEC)`. 분실 = 사용자별 재인증 필요 (DB 행만 영향, 다른 데이터 무영향).
- State JWT (HS256 with CORTEX_JWT_SECRET, 10분 TTL): callback 인증 (DB 없이 stateless owner_id 추출)

## 환경 변수 (.env.local)

| 변수 | Source | 용도 |
|---|---|---|
| `CORTEX_DB_HOST/PORT/NAME/USER/PASSWORD` | vault `cortex/axe/db-password` | Postgres 연결 |
| `AZURE_AD_TENANT_ID` | hardcoded `122fb574-7efa-476a-95b6-bee81bce2cce` | Entra ID tenant |
| `AZURE_CORTEX_MCP_CLIENT_ID` | 등록 후 `60d04ea8-...` | MCP audience claim 매칭 |
| `AZURE_CORTEX_MCP_CLIENT_SECRET` | vault `cortex/axe/oauth-client-secret` | OAuth confidential client (claude.ai 요구) |
| `AZURE_CORTEX_MCP_AUDIENCE` | `https://axe.axelabs.ai/cortex/mcp` | JWT aud 검증 |
| `GOOGLE_OAUTH_CLIENT_ID` | Cloud Console 등록 후 | Google OAuth Web flow |
| `GOOGLE_OAUTH_CLIENT_SECRET` | vault `cortex/axe/google-oauth-client-secret` | 동상 |
| `GOOGLE_OAUTH_REDIRECT_URI` | `https://axe.axelabs.ai/cortex/oauth/google/callback` | callback 등록 매칭 |
| `CORTEX_PII_PASSPHRASE_AXEC` | vault `cortex/axe/pii-passphrase-axec` | pgp_sym_encrypt key (refresh_token 암호화) |
| `CORTEX_JWT_SECRET` | vault `cortex/axe/jwt-secret` | HS256 — OAuth state 서명 + 운영자 path B |
| `CORTEX_MCP_HOST/PORT` | `0.0.0.0:3210` | MCP server bind |
| `CORTEX_DEPLOY_COLOR` | `blue` 또는 `green` | blue/green swap |
| `CORTEX_PUBLIC_BASE_URL` | `https://axe.axelabs.ai` | WWW-Authenticate resource_metadata URI base |
| `CORTEX_SYNC_INTERVAL_SECONDS` | `600` (10분) | per-user sync loop interval |
| `CORTEX_GOOGLE_RATE_LIMIT_PER_MIN` | `90` | Google People API 한도 |
| `CORTEX_SYNC_GROUP_BLACKLIST` | `Personal,HPE` (기본) | **sync 유입 라벨 차단** — 이 contactGroup(라벨) 이름이 붙은 Google 연락처는 sync 가 Cortex 에 들이지 않음 ([D-cortex-9](/ops/decisions) Phase 1). 라벨 이름 case-insensitive 매칭. 명시적 빈 값 (`CORTEX_SYNC_GROUP_BLACKLIST=`) 으로 필터 비활성화 |
| `CORTEX_SYNC_GROUP_WHITELIST` | (빈 값) | 비어있지 않으면 이 라벨 중 하나라도 붙은 연락처만 유입 (gate). blacklist 가 whitelist 보다 강한 veto. 둘 다 비면 필터 off (contactGroups API 호출 자체 생략) |

[D-ops-17](/ops/decisions): secret 은 vault SoT, `axe ship cortex` 가 deploy-time 에 vault → `.env.local` pull. 코드는 runtime 에 vault 호출 X.

## 운영

```bash
# 로컬 개발 (postgres 만 docker, MCP server 는 cargo run 으로 hot iterate)
cd /Users/axe/cortex
docker compose up -d postgres
sqlx migrate run
cargo run --release -- mcp-http

# 또는 배포 형태 (full docker)
docker compose up -d --build

# 배포 (axe ship — release-gate + blue/green swap)
axe ship cortex --customer axe

# DB 직접 점검
docker exec -it cortex-postgres psql -U cortex -d cortex
SELECT count(*), kind FROM artifact GROUP BY kind;

# Schema 디스커버리
curl -H "Authorization: Bearer $TOKEN" https://axe.axelabs.ai/cortex/schemas

# 사용자 Google 연동 (Claude.ai 안에서 MCP tool 호출)
# 1. claude.ai/customize/connectors 에 Cortex 등록 (MCP Connectors catalog 참조)
# 2. MCP tool: connect_google() → authorize_url 받음 → 브라우저로 열기
# 3. Google consent → callback → "✓ Google 연결 완료" 페이지
# 4. 다음 sync cycle (또는 sync_google_now) 부터 Google Contacts pull
```

## 폐기된 것

- `/Users/axe/cortex.legacy.20260526/` (623 MB) — file-based recall 시스템. data/ 의 markdown topic tree (186) + entity profile (16) + keyword DB + connection graph 는 추후 enrichment migration 시 참고용.
- `cortex.axellc.com` 도메인 (cloudflared `~/.cloudflared/config.yml` 에서 ingress 제거됨). `com.cortex.cloudflared` launchd 는 `mysrt.axellc.com` 만 서비스 중 — 추후 mysrt 를 axe-tunnel Docker 로 이전 후 launchd 자체 폐기 ([B-mysrt-tunnel-consolidate](/ops/backlog)).
- `~/Network/network_crm.py` 양방향 sync 스크립트 + `Network_CRM.xlsx` (660 rows) + Google OAuth Desktop client "Network Manager" — task 17 (xlsx enrichment migration) 완료 후 `~/Network.legacy/` 로 archive.

## 관련 서비스

- **Frame** — deal artifact 가 frame entity ID 를 referenced field 로 보유 (`payload.frame_deal_ref`). 향후 frame 의 deal 도메인 ↔ cortex 의 deal artifact 간 양방향 link.
- **Blueprint** — M6 (Q4 2026 target → Day 1 Cortex 로 escalation) artifact + PARA UI mirror. Blueprint 가 Cortex artifact 를 owner-scoped 로 mirror 후 PARA dispatch + IC 메모 citation 에 활용.
- **Hive** — 직원도 사람 ([D-cortex-3](/ops/decisions)). 외부 contact → 직원 transition path 는 추후 결정 ([B-cortex-hive-link](/ops/backlog)).

## SoT

- **본 페이지** = operator SoT (signed AXE LLC)
- [`/Users/axe/cortex/CLAUDE.md`](https://github.com/soohunkang/cortex/blob/main/CLAUDE.md) — local 운영 노트
- [`/Users/axe/cortex/docs/operator-setup.md`](https://github.com/soohunkang/cortex/blob/main/docs/operator-setup.md) — operator 직접 작업 절차 (Entra credential reset, vault push, Google Cloud Console GUI)
- [`/Users/axe/.axe/customers.yaml`](https://github.com/soohunkang/blueprint/blob/main/multi-tenant-platform-plan.md) `services.cortex` 매니페스트 + `sso.apps.cortex_mcp` 등록
- alembic 0001 의 SQL 본문 = `migrations/20260526210000_initial_artifact_schema.{up,down}.sql` (sqlx-cli 포맷)

---

<!-- PAGE https://docs.axelabs.ai/services/frame -->

# Frame

> 회계 backend, K-GAAP/KSME 회계 원칙, MCP 14 tools, schema-per-entity.

URL: https://docs.axelabs.ai/services/frame

# Frame

**한 줄 소개**: KSME 회계 기준 준수 금융관리 SaaS. Postgres schema-per-entity 격리 + ACID double-entry + append-only audit log. Blueprint 에이전트가 MCP ~44개 도구로 접근 (조회 14 + 작업 30+).

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Python 3.12+ |
| 프레임워크 | FastMCP (stdio + HTTP/SSE) |
| DB | PostgreSQL 16 |
| ORM | SQLAlchemy 2.0 Core (declarative 아님) + psycopg v3 |
| Migration | Alembic dual-env (shared + entity) |
| 인증 | PyJWT (HS256 frame JWT + RS256 Microsoft JWKS) |
| LLM | Anthropic Claude (file format 분석, 분류) |
| HTTP server | Starlette + uvicorn |

## 포트

| 포트 | 용도 |
|---|---|
| 3700 | PostgreSQL 16 (frame-postgres) |
| 3710 | MCP HTTP blue (active) |
| 3711 | MCP HTTP green (passive) |
| 3712 | axe-frame-proxy (Caddy, blue/green selector) |

## 4 가지 surface

1. **MCP** (HTTP/SSE) — Claude Agent SDK 가 도구로 호출
2. **CLI** (`frame ...`) — 운영자 명령 (migrate, register-entity, mcp-token, ...)
3. **DB 직접 접근** — psql 으로 정합성 검사, 운영자만
4. **Export** — 회계 사무소용 CSV/JSON

## MCP Tools (~54개)

`src/frame/mcp/server.py` 의 `@mcp.tool()` 데코레이터 기준. 핵심 도구:

| Tool | Scope 요구 | 설명 |
|---|---|---|
| `query_balance` | read | 계정 잔액 조회 |
| `query_trial_balance` | read | 시산표 |
| `list_journals` | read | 분개장 |
| `get_journal` | read | 단일 분개 상세 |
| `list_raw_transactions` | read | 입출금 표 |
| `search_evidence` | read | 증거 전문 검색 |
| `list_open_items` | read | 미결 항목 |
| `list_periods` | read | 회계 기간 조회 |
| `post_journal` | write | 분개 등록 (5계층 검증) |
| `reverse_journal` | write | 분개 역분 |
| `flag_uncertainty` | write | 미결 생성 |
| `resolve_open_item` | write | 미결 해결 |
| `ingest_file_blob` | write | 파일 추출 |
| `reconcile_and_propose` | write | 대사 제안 |
| `closing_preview` | close | 마감 미리보기 |
| `closing_commit` | close | 마감 확정 |
| `register_resolution`, `list_resolutions`, `link_journal_to_resolution` | write | 결의서 관리 |
| `compose_kb_mmf_q_journals`, `compose_kbsc_q_journals` | write | 분기 마감 자동 분개 |
| `register_evidence_blob`, `promote_source_file` | write | 증거·파일 관리 |
| `transition_period` | close | 기간 상태 전이 |
| `register_entity`, `list_sub_entities` | admin | entity 등록 + 자회사/펀드 등 sub-entity 조회 (D-ops-30 Phase 2) |
| `list_scrape_schedules`, `get_scrape_schedule` | read | 포털 스크래퍼 주기 조회 ([D-frame-scrape-schedule](/ops/decisions)) |
| `set_scrape_schedule` | write | 스크래퍼 주기 설정 (raw cron 또는 daily/weekly/monthly 프리셋, KST) |
| 기타: B/S·I/S statements, fixed asset, export, snapshot 등 | 각각 | 정합성·내보내기 |

전체 정확한 카운트는 `grep -c '@mcp.tool' /Users/axe/frame/src/frame/mcp/server.py` 로 확인 (현재 54).

### Schema discovery — `GET /frame/schemas`

Blueprint 의 artifact + PARA 지식 레이어 ([D-bp-artifact-1](/ops/decisions)) 가 fact 의 typed schema 권위를 MCP 에 위임. frame 은 자기가 생산하는 fact kind 를 `/schemas` 엔드포인트로 노출 — Blueprint 가 fetch + cache + version ([B-bp-artifact-schema-discovery](/ops/backlog)).

```bash
curl -H "Authorization: Bearer $FRAME_MCP_TOKEN" \
  https://axe.axelabs.ai/frame/schemas
```

응답 envelope (안정 형식):

```json
{
  "version": "1.0",
  "service": "frame",
  "schemas": {
    "frame.balance@1.0": {
      "description": "단일 계정의 시점 잔액 (debit/credit 합계 + 순 balance).",
      "produced_by": ["query_balance"],
      "key_fields": ["entity_id", "account_code", "as_of_date", "debit", "credit", "balance", "policy_id"]
    },
    "frame.journal@1.0": { ... },
    "frame.income_statement@1.0": { ... }
  }
}
```

13 schemas 현재 노출 (balance / trial_balance / journal / journal_list / raw_transaction / open_item / resolution / fixed_asset_book_value / income_statement / balance_sheet / cash_flow_statement / equity_changes_statement / general_ledger). 추가 schema 는 `src/frame/mcp/schemas.py` (SOT) 에 등재.

**`cash_flow_statement` 활동 분류** (간접법, `src/frame/ops/statements.py`): 명시적 dict (`OPERATING_ASSETS`/`OPERATING_LIABILITIES`/`INVESTING_ACCOUNTS`/`FINANCING_ACCOUNTS`) 우선, **dict 에 없는 신규 계정만** type+prefix fallback (D-frame-3): `asset` 且 code prefix `13` → **투자활동** (1300번대 투자자산 전체, 신계정 자동 포함); `liability` 且 차입금 코드(`BORROWING_LIABILITIES`={2104,2105}) → **재무활동**. ⚠️ 2101 미지급금/2102 미지급세금 등 영업성 부채는 영업활동 유지 (차입금 코드만 명시 — 미지급금 재무 누출 차단). 분류 완전 시 `reconciliation_diff=0`·`verified=true`, 누락 계정은 `unclassified_accounts` 로 노출.

- 인증: required (JWTAuthMiddleware 적용 — `_PUBLIC_PATHS` 에 미포함). MCP 클라이언트의 동일 토큰 재사용
- versioning: schema_id 의 `@{version}` suffix (예: `frame.balance@1.0` → `@2.0` incompatible 시), 환경 envelope `version` 은 응답 모양 변경 시에만 bump
- 소스 권위: `src/frame/mcp/schemas.py` 가 SOT — 외부 schema registry 없음

## 데이터 모델

### Shared schema

| 테이블 | 역할 |
|---|---|
| `entity` | 등록된 entity 메타 (corp + fund 평등 평면). 컬럼: `id` PK · `legal_name` (영문 사업자등록 SoT) · **`display_name`** (한글 표시명, NULL→legal_name 폴백, 0010_shared) · `biz_no` · `schema_name` · `accounting_standard` · `fiscal_year_start_month` · **`entity_kind`** (corporate/kip/kvf, D-ops-22) · **`fund_meta`** JSONB (펀드 결성·약정·LP 등, D-ops-22) · **`closed_at`** (청산일, D-ops-22) |
| `entity_relationship` | entity 간 관계 (PR #26 + D-ops-22). `entity_a` (holder) / `entity_b` (target) / `kind` 8 종 (parent_subsidiary · sister_company · common_controlling_party · common_director · related_party · joint_venture · **gp_managed_fund** · **lp_invested_fund**) / **`ownership_numerator`/`denominator`/`unit`** (amount_krw/shares/units — % 는 반올림 오차로 폐기) / `effective_from·until` / `evidence_ids[]` |
| `cross_journal_link` (D-ops-22) | cross-entity mirror 분개 pair. `link_kind` (gp_commitment / mgmt_fee / carried_interest / capital_call / distribution / other) + (`left_entity_id`, `left_journal_id`) ↔ (`right_entity_id`, `right_journal_id`). UNIQUE 양쪽. schema 격리 환경 무결성 |
| `format_profile` | 파일 포맷 캐시 (vendor + column_signature) |
| `format_profile_clarification` | clarify Q&A 누적 |
| `account_template` | 표준 계정과목 (KSME/KGAAP/KIFRS) |
| `idempotency_record` | 멱등성 키 (cross-entity write dedup) |
| `oauth_authorization_codes` | OAuth proxy 잔재 (현재 dormant) |
| `scrape_schedule` (D-frame-scrape-schedule) | 포털 스크래퍼 주기. `source_key` · `entity_id` · `enabled` · **`cron`** (KST) · `window_days` · `last_run_at`/`last_status`/`next_due_at`. MCP `set_scrape_schedule` 로 조정, 호스트 `frame scrape-due` 가 실행 |

### Per-entity schema (axec, axev, ...)

| 테이블 | 역할 |
|---|---|
| `account` | 계정 (chart-of-accounts) |
| `journal` | 분개 헤더 |
| `journal_line` | 분개 라인 (debit/credit) |
| `raw_transaction` | 원천 거래 (은행 입출금 등) |
| `bank_account` | 계좌 메타 |
| `source_file` | 업로드된 파일 (content_hash, portable `storage_url`) |
| `fiscal_period` | 회계 기간 (open/soft_closed/hard_closed) |
| `open_item` | 미결 (severity, resolution_note) |
| `evidence` | 증거 (kind, content_hash, portable `storage_url`) |
| `audit_log` | 쓰기 추적 (모든 INSERT/UPDATE/DELETE) |
| `entity_meta` | 사업자등록번호, 법인명 |
| `fixed_asset` | 고정자산 |
| `security_holder` | 주주 (PII 암호화) |
| `commitment_ledger` | 펀드 약정·납입 ledger (kip/kvf 전용 — D-ops-30 Phase 3) |
| `lp_master` | LP master (external_entity_id FK → shared.entity, D-ops-30 Phase 3) |

**accounting_policy.standard CHECK** (D-frame-fund-ksme-policy-check, 2026-05-22): 0003 의 CHECK 가 fund kind 의 `fund_ksme` 미허용하여 KIP/KVF entity 등록 시 zombie schema (0 tables). 0003 코드 패치 + 0018 migration 으로 `('ksme','kgaap','kifrs','fund_ksme')` 확장. fund_ksme chart_template (D-ops-30 Migration #2) 가 fund entity bootstrap 시 자동 적용.

**evidence / source_file blob 저장** (D-frame-2, 2026-06-04): 모든 evidence·source_file blob 은 content-addressed 로 `.local/files/<hash[:2]>/<hash>/<filename>` 에 복사 (Postgres 에 bytea 없음 — 큰 파일은 file store). `storage_url` 은 **portable** = relative `<hash[:2]>/<hash>/<filename>`, read 시 `frame.ingest.pipeline.resolve_storage_path()` 가 `FRAME_FILE_STORAGE_PATH` (`.local/files`, 컨테이너 `/app/.local/files`) 기준 absolute 로 매핑. **`local://<host 경로>` 또는 CWD 의존 absolute 경로 금지** — 컨테이너가 host 경로 read 불가 + 원본 rename/move 시 깨짐 (host `/Users/.../.local/files` ↔ 컨테이너 `/app/.local/files` 불일치). resolver 는 legacy 형식 (portable / `/app/...` / `/Users/...` / `local://<abs>`) 을 모두 tolerant. migration `0020_normalize_evidence_storage_url` 가 기존 row 를 portable 로 정규화 (blob 실존 시만, 부재 row 미변경). 무결성 probe: `GET /frame/health/storage`.

## 디렉토리 구조

```
src/frame/
├── auth.py                  TokenClaims, encode/decode_token
├── auth_oidc.py             Microsoft id_token 검증
├── config.py                customers.yaml 로더 + accessor
├── cli.py                   37+ click commands
├── errors.py                FrameError 계층
├── observability.py         @instrument, Prometheus
│
├── db/
│   ├── engine.py            async pool, context manager
│   ├── shared.py            shared 테이블 정의
│   ├── entity.py            entity 메타 factory (35개 테이블)
│   └── migrations.py        upgrade_all(), register_entity()
│
├── ingest/                  파일 → raw_transaction
│   ├── reader.py            xls/xlsx/csv parser
│   ├── llm.py               Claude format 분석
│   ├── profile.py           format_profile 캐시
│   ├── hometax.py           홈택스 vendor
│   ├── kb_fund.py           KB 펀드
│   └── card.py              카드사
│
├── accounting/              M2+ 회계 계층
│   ├── chart.py             chart-of-accounts
│   ├── journal.py           분개 모델
│   ├── classify.py          raw → journal_line
│   ├── balance.py           trial_balance, B/S
│   └── reconcile.py         대사
│
├── ops/                     MCP tool 로직
│   ├── queries.py
│   ├── write.py             post_journal (5계층 검증)
│   ├── period.py            list_periods, transition_period
│   ├── workflow.py          reconcile_and_propose, closing_*
│   ├── open_item.py
│   ├── quarterly_close.py
│   └── snapshot.py
│
├── mcp/                     MCP 서버
│   ├── server.py            FastMCP instance, 44 tools 등록
│   ├── http_server.py       Starlette, OAuth middleware
│   ├── prompts.py           4 prompts (reconcile_walkthrough 등)
│   ├── oauth.py             OAuth proxy (D-ops-15, dormant)
│   └── tools/               각 tool 구현 (13 .py)
│
├── security/
│   └── pii.py               pgcrypto pgp_sym_encrypt
│
alembic/
├── versions/                shared (0001~0007)
└── entity_versions/         per-entity (0001~0016)

docs/ops/                    운영 정책 6 파일
├── naming-conventions.md
├── access-control.md
├── jwt-issuance.md
├── mcp-client-config.md
├── onboarding-operator.md
└── onboarding-employee.md
```

## CLI 명령어

```bash
# DB
frame migrate                          # shared + 모든 entity
frame register-entity --id axec --legal-name "에이엑스이 코퍼레이션"
# fund (D-ops-22, 2026-05-22) — KIP / KVF 등록
frame register-entity --id axev_kvf_001 \
    --legal-name "AXE 시드 1호 벤처투자조합" \
    --kind kvf \
    --fund-meta '{"founded_at":"2024-03-15","commitment_total_krw":5000000000,"term_years":7}'
frame list-entities

# 기간
frame open-period --entity axec --year 2026
frame close-period --entity axec --period-id 7 --status soft_closed
frame list-periods --entity axec

# 추출
frame seed-profile &lt;spec.json&gt;
frame ingest --entity axec --file &lt;path&gt;
frame list-issues --entity axec

# 스크래핑 (외부 포털 → ingest, host-only / launchd)
frame scrape lottecard                 # 롯데 법인카드 승인내역(개인정보 미포함) → axec 적재
frame scrape lottecard --entity axtest --since 2026-04-01 --until 2026-04-30
#   헤드풀 Playwright (EIWAF 가 headless 차단). 법인전체 = 법인의 모든 카드.
#   자격증명: FRAME_LOTTE_PORTAL_USERNAME / _PASSWORD (vault → .env.local).
frame scrape-due [--dry-run]           # launchd tick: shared.scrape_schedule 중 due 인 것만 실행
#   주기는 DB(MCP set_scrape_schedule)로 조정. com.frame.scrape-tick 이 08–21시 매시 호출.

# 회계
frame post-journal --entity axec --spec-path &lt;json&gt;
frame classify --entity axec
frame trial-balance --entity axec --as-of 2026-05-31
frame integrity-check --entity axec

# 토큰 발급
frame mcp-token --sub ai@axellc.com --customer axe \
    --entity axec:read,write,close \
    --entity axev:read,write,close \
    --ttl 2592000

# 서버
frame mcp-serve                        # stdio
frame mcp-health &lt;token&gt;
```

## OAuth-RP 흐름

```
Claude Code/claude.ai → POST /frame/mcp (no auth)
frame                 → 401 + WWW-Authenticate: Bearer resource_metadata="..."
client                → GET /.well-known/oauth-protected-resource
frame                 → {resource: "https://axe.axelabs.ai/frame/mcp", authorization_servers: [Microsoft]}
client                → Microsoft OAuth flow (PKCE)
Microsoft             → access_token (aud = Application ID URI)
client                → POST /frame/mcp Authorization: Bearer &lt;access_token&gt;
frame middleware      → JWKS RS256 verify + aud + iss + email extract → entity 매핑
frame                 → MCP session 생성 → tool 호출 가능
```

상세: [인증 · 권한](/architecture/auth).

### Custom Connector 등록 (신규 사용자)

운영자: `axe secret send AZURE_FRAME_MCP_CLIENT_SECRET --service frame --to <local-part>` → URL 발급 → `/api/admin/broadcast-dm` 자동 Teams DM. 전체 흐름은 [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send). 수신자 화면 절차는 [/onboard/claude-frame-setup](/onboard/claude-frame-setup) (5분 가이드).

## 환경 변수

> **D-ops-18 (2026-05-21)**: 비밀 vars (`FRAME_DB_PASSWORD`, `FRAME_JWT_SECRET`, `FRAME_SECRET_KEY`, `AZURE_FRAME_MCP_CLIENT_SECRET`, `FRAME_PII_PASSPHRASE_*`, `CLAUDE_CODE_OAUTH_TOKEN`) 는 모두 env_file `.env.local` 에서 직접 dump. `docker-compose.yml` 의 `environment:` 블록에 default-empty 변수 치환 (`$VAR` 형식) 으로 중복 정의 금지 — Compose precedence 가 env_file 의 vault 값을 shadow 했던 trap. 환경변수 = vault SoT 단일 출처 (`axe secret pull frame` 이 vault → `.env.local` atomic write).

```bash
# DB
FRAME_DB_HOST=postgres
FRAME_DB_PORT=5432
FRAME_DB_USER=frame
FRAME_DB_PASSWORD=
FRAME_DB_NAME=frame

# JWT
FRAME_JWT_SECRET=                       # ≥32 bytes
AZURE_FRAME_MCP_CLIENT_SECRET=          # OAuth confidential client

# PII
FRAME_PII_PASSPHRASE_AXEC=
FRAME_PII_PASSPHRASE_AXEV=
FRAME_PII_PASSPHRASE_REALCHOICE=
FRAME_PII_SALT_DIR=/root/.frame

# MCP HTTP
FRAME_MCP_HOST=0.0.0.0
FRAME_MCP_PORT=3710
FRAME_MCP_LOG_LEVEL=INFO
FRAME_MCP_ALLOWED_HOSTS=frame-mcp:*,localhost:*,...
FRAME_MCP_ALLOWED_ORIGINS=https://axe.axelabs.ai,...

# Multi-tenant
FRAME_CUSTOMERS_YAML=/etc/axe/customers.yaml
FRAME_CUSTOMER_ID=axe
FRAME_DEPLOY_COLOR=blue

# Blueprint platform identity (D-axe-idp-1) — 전부 빈 기본값 = 비활성(non-breaking).
# BLUEPRINT_ISSUER set 시 Blueprint 발급 platform 토큰을 신뢰. 상세: architecture/platform-identity.
BLUEPRINT_ISSUER=                       # 미설정=무시(현재 동작). set 시 활성
BLUEPRINT_JWKS_URL=                     # 미설정 시 issuer 에서 유도
BLUEPRINT_AUDIENCE=https://axe.axelabs.ai

# 롯데카드 스크래퍼 (host-only — MCP 컨테이너엔 없음, launchd 만 사용)
FRAME_LOTTE_PORTAL_USERNAME=            # 법인관리자 로그인 ID
FRAME_LOTTE_PORTAL_PASSWORD=            # vault frame/axe/lotte-portal-password

# Storage (host bind mount)
FRAME_STORAGE_HOST_DIR=${HOME}/frame/.local   # default — host 의 home 기준. /Users/axe/... hardcode 금지
```

> ⚠️ **`/Users/axe/` 절대경로 hardcode 금지**: `FRAME_STORAGE_HOST_DIR` (그리고 docker-compose 의 volume mount default) 는 반드시 `${HOME}/...` 패턴을 사용. customer macmini 의 운영 user 가 `/Users/<other>/` 인 경우 hardcode 된 `/Users/axe/...` 는 path 부재 → volume bind fail 또는 frame storage 무효 (2026-05-25 트루비아 측 발견 — R1 fix wrapper `.env.local` 에 `${HOME}` 명시, B-frame-keychain-to-vault 후속 fix 후 compose default 도 `${HOME}` 으로 자동 일반화).

## 운영 노트

- **Blue/green deploy** 지원 (port 3710/3711 동시 실행, alias swap)
- **Append-only**: raw_transaction, journal_line 의 DELETE/UPDATE 권한이 REVOKE
- **PII**: pgp_sym_encrypt + entity 별 passphrase (분실 = 영구 손실, 의도)
- **정합성**: `frame integrity-check` 5가지 검사 (journal_balance, audit_completeness, period_consistency, source_link_coverage, **evidence_storage_presence** — 증빙 bytes 가 디스크에 실존하는지 orphan 탐지). nightly `com.frame.integrity-check`, error/blocker → open_item 자동 등록.
- **LLM 비용 추적**: `llm_call` 테이블에 모든 호출 기록
- **포털 스크래퍼 스케줄·SLA** ([D-frame-scrape-schedule](/ops/decisions)): 주기는 `shared.scrape_schedule` 의 KST cron (MCP `set_scrape_schedule` 로 조정), 호스트 `com.frame.scrape-tick` 이 08–21시 매시 due 만 실행. **SLA catch-up** — 다운타임 중 놓친 실행은 복구 후 첫 in-window 틱에서 1회 실행하며, look-back 을 `now−last_run`(상한 365일)까지 넓혀 그 기간 전체를 backfill (row_hash 중복제거, 데이터 손실 0). 부팅/wake 시 `RunAtLoad` 로 즉시 catch-up, `get_scrape_schedule` 의 `overdue` 로 가시화.

## 신규 customer 1 차 사이클 runbook (D-day ~ D+30)

신규 customer (예: realchoice) 가 6/1 D-day 이후 첫 한 달 동안 frame 내부에 회계 데이터를 적재하고 1 차 사이클을 닫는 권장 순서. `B-frame-lpm-classify` (자동 분류) 가 완성 (ETA D+90, 아래) 되기 전 시점이라 분개 일부는 수작업 분개로 보완합니다.

| 시점 | 작업 | 명령 / 도구 |
|---|---|---|
| **D-day (6/1)** | frame stack 부팅 (운영자 측) | `axe customers ingest <id> ... --apply` + `axe onboard <id> --apply` |
| **D+1** | **chart of accounts auto-seed** — entity 등록 시점에 44-account KSME 자동 복사 (D-ops-21) | `frame register-entity --id <id> --legal-name "..." --kind corporate --accounting-standard ksme` |
| **D+2 ~ D+7** | **원천 데이터 ingest** — KB/거래은행 거래내역 CSV 업로드. LLM 이 포맷 자동 인식 → `raw_transaction` 적재 | `ingest_file_blob` MCP tool (또는 `frame ingest <file>` CLI) → `analyze_file_format` 자동 호출 |
| **D+8 ~ D+14** | **trial balance / 결산 잔액 등록** — D2 결정의 "결산 시점 trial balance" 적재. 외부 회계법인 검수본 기준 | `register_resolution` + `post_journal` (개시 분개) |
| **D+15 ~ D+21** | **payroll 매칭** — Hive Phase 1 활성 후 pending_payroll INSERT → frame `match_pending_sweep` 자동 매칭 → 잔여 수동 매칭 | `list_pending_payroll` / `match_pending_to_raw_tx` / `match_pending_sweep` |
| **D+22 ~ D+28** | **수작업 분개 보완** — `analyze_file_format` 가 인식한 raw_transaction 중 자동 매칭 못 한 것은 운영자 또는 customer 측 회계 담당자가 `post_journal` 로 수작업 분개. LLM proposal 보조는 가능하나 commit 은 사람 confirm | `post_journal` + `query_trial_balance` 으로 매일 진척 확인 |
| **D+30** | 1 차 사이클 회고 — 자동 매칭률 / 수작업 분개 시간 / 실패 패턴 측정 → `B-frame-lpm-classify` (M2 top) 의 prompt 학습 데이터로 활용 | `query_trial_balance` / `income_statement` / `balance_sheet` |

### `B-frame-lpm-classify` ETA (자동 분류 pipeline)

| ETA | 도달 수준 | 회신 시점 |
|---|---|---|
| **D+90 (2026-09-01 목표)** | minimum viable — LLM 이 raw_transaction 보고 journal_line proposal 생성, 운영자/회계 담당자 confirm 후 commit. 정확도 60~80% (axe 백테스트 기준) | 2026-08 중 베타 → 9 월 production |
| **D+120 (2026-10-01)** | rule-based pre-classifier 결합 — 반복 거래는 정규식 룰, 1 회 거래는 LLM. 정확도 80%+ | 2026-10 |
| **2026-12-01** | 2027-01-01 cutover 직전 stable — axec/axev 1 년치 backtest 완료 + 회귀 test green | cutover 2 주 전 |

D+30 ~ D+90 동안의 Truvia 측 분개 부담은 **위 표의 D+8~D+28 의 수작업 + 매칭 보조** 로 흡수. 1 차 사이클 = 한 달 raw_transaction + payroll + 결산 잔액 = 추정 200~500 건 분개. 자동 매칭 0% 가정 시 회계 담당자 1 인 × 2~5 일/월 effort.

### Frame 내부 운영의 SSOT

- 본 페이지 = 운영자 측 SSOT (signed by 액스코퍼레이션 주식회사)
- `/Users/axe/frame/DECISIONS.md` = frame 내부 결정 누적
- `/services/hive` 의 payroll 흐름 = frame `pending_payroll` 의 입력 채널
- 외부 회계법인 cross-check workflow = `B-frame-cross-check-workflow` (별도 backlog, Truvia 측 외부 회계법인 회신 시 등재)

## 관련 문서

- [Blueprint service](/services/blueprint) — MCP 클라이언트
- [Frame OAuth 설정 (Azure)](/partner/registration/entra-app)
- [신규 직원 connector setup](/onboard/claude-frame-setup)
- [/Users/axe/frame/DECISIONS.md](https://github.com/soohunkang/frame/blob/main/DECISIONS.md) — D-ops-1~15
- [/Users/axe/frame/docs/ops/](https://github.com/soohunkang/frame/tree/main/docs/ops) — 운영 정책 6 파일

---

<!-- PAGE https://docs.axelabs.ai/services/hive -->

# Hive

> HR backend — 조직 · 휴가 · 성과 · 보상. Postgres schema-per-entity + bitemporal employment_records + ltree 조직 트리 + JSONB 커스텀 필드 + append-only audit. Mirrors frame architecture.

URL: https://docs.axelabs.ai/services/hive

# Hive

**한 줄 소개**: 통합 HR MCP 서버. PostgreSQL schema-per-entity 격리, bitemporal employment_records, ltree 조직 트리, JSONB 커스텀 필드, append-only audit log. Blueprint 에이전트와 직원/매니저가 MCP 도구로 접근.

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Python 3.12+ |
| 프레임워크 | FastMCP (stdio + HTTP/SSE) |
| DB | PostgreSQL 16 (with `ltree`, `pgcrypto`) |
| ORM | SQLAlchemy 2.0 Core + psycopg v3 |
| Migration | Alembic dual-env (shared + entity) |
| 인증 | PyJWT (HS256 hive JWT + RS256 Microsoft JWKS) |
| LLM | Anthropic Claude (OKR 추천, 평가 초안, 이직 리스크) |
| HTTP server | Starlette + uvicorn |

## 포트

| 포트 | 용도 |
|---|---|
| 3800 | PostgreSQL 16 (hive-postgres) |
| 3810 | MCP HTTP blue (active) |
| 3811 | MCP HTTP green (passive) |
| 3812 | axe-hive-proxy (Caddy, blue/green selector) |

## URL 컨벤션

```
{customer}.axelabs.ai/hive               ← HTTP root (path-based mount)
{customer}.axelabs.ai/hive/mcp           ← MCP endpoint (canonical resource URI)
{customer}.axelabs.ai/hive/health/ready  ← readiness
{customer}.axelabs.ai/hive/.well-known/oauth-protected-resource
```

axe.axelabs.ai/hive/mcp 가 현재 axe customer 의 endpoint. realchoice 는 onboarding 시 활성.

## 5 가지 도메인

| 영역 | 상태 | Phase |
|---|---|---|
| 조직 관리 (org tree, employees, positions, employment_records) | live | 1 |
| 휴가 관리 (근로기준법 §60 연차 자동) | live | 1 |
| KPI / OKR | 미구현 | 2 |
| 성과 평가 (360도, AI 보조) | 미구현 | 2 |
| 급여 · 인센티브 (스톡옵션 포함) | 미구현 | 3 |

## MCP Tools (Phase 1, 19개)

**조회**
- `employee_get` — 단일 직원 (id / email / employee_no)
- `employee_search` — 이름·이메일·번호 부분일치 + status/org 필터
- `org_get_chart` — ltree 서브트리 (or 전체) + as_of_date 시점 query
- `org_get_team` — 조직 + 멤버 (line memberships, include_sub_orgs 옵션)
- `position_list` — 직무/직급 목록
- `leave_get_balance` — 직원 휴가 잔여 (근로기준법 자동 적용)
- `leave_get_calendar` — 팀 휴가 캘린더 (overlap 감지)
- `leave_get_request` — 단일 요청 detail
- `leave_policy_list` — 휴가 정책 목록
- `leave_usage_report` — 기간별 사용 집계

**변경**
- `leave_request` — 휴가 신청 (충돌 + 잔여 자동 검증)
- `leave_approve` — 승인/반려 (다단계 결재 지원)
- `leave_cancel` — 취소 (start_date 전)
- `leave_policy_create` — 정책 등록

**관리자**
- `employee_create` — 신규 입사 + 초기 발령 (optional). `payroll_start_date` 옵셔널 — None 이면 `hire_date` fallback (D-hive-27).
- `employee_update` — patch (self vs HR 필드 분리). `payroll_start_date` HR 필드.
- `compensation_plan_list(plan_kind?)` — entity 의 active compensation_plan 목록 조회 (read scope, D-hive-30 M 트랙). `compensation_award_create` 호출 전 `plan_code` 확보용.
- `compensation_award_create(employee_no, plan_code, annual_amount_krw, effective_from, effective_until?, award_code?)` — 직원에게 compensation_award 부여 (D-hive-17 후행 leg, D-hive-30). employee/plan 존재 + active overlap 검증. overlap 시 `COMPENSATION_AWARD_CONFLICT` raise. `payroll_compute_period` 가 active salary award 없으면 skip → 본 도구가 페이슬립 산정의 선행.
- `org_create` — 조직 신설 (ltree path 자동)
- `org_move_employee` — 인사 발령 (membership + bitemporal record)
- `position_create` — 직무/직급 신설

### Schema discovery — `GET /hive/schemas`

Blueprint 의 artifact + PARA 지식 레이어 ([D-bp-artifact-1](/ops/decisions)) 가 fact 의 typed schema 권위를 MCP 에 위임. hive 는 frame 패턴 ([Frame Schema discovery](/services/frame#schema-discovery--get-frameschemas)) 1:1 mirror — 자기가 생산하는 HR/payroll fact kind 를 `/schemas` 엔드포인트로 노출.

```bash
curl -H "Authorization: Bearer $HIVE_MCP_TOKEN" \
  https://axe.axelabs.ai/hive/schemas
```

15 schemas 현재 노출 (employee / employee_onboarding / org_chart / position / leave_balance / leave_calendar / leave_request / leave_policy / leave_usage_report / payroll_period / payslip / payroll_remittance / payroll_send_log / payroll_dispatch_log / notify_template). 추가 schema 는 `src/hive/mcp/schemas.py` (SOT) 에 등재.

- 인증: required (frame 동일)
- versioning: schema_id 의 `@{version}` suffix
- 소스 권위: `src/hive/mcp/schemas.py` — 외부 schema registry 없음
- envelope 형식: frame 과 동일 (`{ version, service, schemas }`) — Blueprint 의 [B-bp-artifact-schema-discovery](/ops/backlog) 가 multi-MCP 통합 fetch

## 데이터 모델

### Shared schema

| 테이블 | 역할 |
|---|---|
| `entity` | 등록 entity 메타 (axec, axev, realchoice) |
| `custom_field_definitions` | 회사별 커스텀 필드 정의 (D-hive-6) |
| `idempotency_record` | 멱등 키 (24h TTL) |
| `event_outbox` | pg_notify 이벤트 outbox (D-hive-7) |

### Per-entity schema

| 테이블 | 역할 |
|---|---|
| `organizations` | 조직 (ltree path, GIST index) |
| `positions` | 직무·직급·직책 매트릭스 |
| `employees` | 임직원 마스터 (national_id/home_address/bank_account_no = PII 암호화). `hire_date` = 위임/근로계약 발효일 (frame.executive_officer.appointed_date 정합), `payroll_start_date` = 보수 개시일 (NULL → hire_date fallback, D-hive-27). |
| `organization_memberships` | 매트릭스 다중 소속 (line/dotted/project) |
| `employment_records` | bitemporal 발령 이력 (valid_from/to + recorded/superseded_at) |
| `leave_policies` | 휴가 정책 (basis + rules JSONB) |
| `leave_requests` | 신청 (approval_chain JSONB, 다단계 결재) |
| `leave_balances` | 잔여 캐시 (granted/used/pending/remaining) |
| `custom_field_violations` | custom field 검증 실패 audit |
| `audit_log` | 쓰기 추적 (trigger 자동) |
| `llm_call` | Anthropic API 호출 audit |

## 권한 모델 — Scope

```
read < write < approve < admin
```

- `read` — get/list/search
- `write` — leave.request (본인), employee.update (자기 일부)
- `approve` — leave.approve, employee.update(hr_fields=True), 성과 review.submit
- `admin` — employee.create, org 변경, policy 변경, payroll.run

권한은 **entity 별로** 부여 (예: `{"axec": ["read","write","approve"], "axev": ["read"]}`).

OIDC 인증 (Microsoft Entra) 기본 = `["read", "write", "approve"]`. **`admin`** 은 Blueprint `EntityRole` (`/api/internal/entity-roles`) 가 해당 (email, entity) 에 대해 `role='admin'` 또는 `'owner'` 반환할 때 **자동 부여** (D-bp-entity-17, 2026-05-22). `auth_oidc.py` 가 sign-in 마다 Blueprint 내부 API 조회 (HMAC bearer `BLUEPRINT_INTERNAL_API_KEY`, 5분 cache, fail-open — Blueprint 장애 시 default scope 유지하여 lockout 회피). HS256 service token 으로 admin 직접 발급은 break-glass / dev 용도로만.

## 한국 근로기준법 §60 연차

연차 leave_policy 생성 시 `rules=None` 이면 statutory 적용:

```yaml
rules:
  first_year_monthly: { grant_per_month: 1, max_first_year: 11 }
  after_first_year:    { base: 15, bonus_every_n_years: 2, max: 25 }
  expiry:              { kind: "1_year_from_grant" }
  carry_over:          { allowed: false, payout_on_expiry: true }
```

회사별 변형은 동일 schema 에 JSONB override 만 변경 (코드 변경 X).

## OAuth-RP 흐름

frame 과 동일. customers.yaml `sso.apps.hive_mcp` 에서 client_id / application_id_uri 읽어 Microsoft Entra ID id_token RS256 검증.

```
Claude Code → POST /hive/mcp (no auth)
hive        → 401 + WWW-Authenticate: Bearer resource_metadata="..."
client      → GET /hive/.well-known/oauth-protected-resource
hive        → {resource: "https://axe.axelabs.ai/hive/mcp", authorization_servers: [Microsoft]}
client      → Microsoft OAuth flow (PKCE)
Microsoft   → access_token (aud = Application ID URI)
client      → POST /hive/mcp Authorization: Bearer <access_token>
hive        → JWKS RS256 verify + aud + iss + email extract → entity 매핑
hive        → MCP session 생성 → tool 호출
```

### Custom Connector 등록 (신규 사용자)

운영자: `axe secret send AZURE_HIVE_MCP_CLIENT_SECRET --service hive --to <local-part>` → URL 발급 → `/api/admin/broadcast-dm` 자동 Teams DM. 전체 흐름은 [/architecture/secrets § 사람에게 전달](/architecture/secrets#사람에게-전달--bitwarden-send). 수신자 화면 절차는 [/onboard/claude-frame-setup](/onboard/claude-frame-setup) (5분 가이드, MCP URL 만 `https://axe.axelabs.ai/hive/mcp` 로 치환).

## CLI

```bash
# DB
hive migrate                        # shared + 모든 entity
hive register-entity --id axec --legal-name "에이엑스이 코퍼레이션"
hive list-entities

# 토큰 발급
hive mcp-token --sub ai@axellc.com --customer axe \
    --entity axec:read,write,approve,admin \
    --entity axev:read,write,approve \
    --ttl 2592000

# 정책 시드
hive seed-policies --entity axec    # 연차/병가/경조사 자동 등록

# 서버
hive mcp-serve                      # stdio
hive mcp-serve-http                 # HTTP (uvicorn :3810)
hive mcp-health --port 3810
```

## 운영 노트

- **Blue/green deploy** 지원 (3810/3811 동시 실행, docker network alias swap via axe-hive-proxy)
- **Append-only**: audit_log trigger 가 모든 mutable table 의 변경 자동 기록
- **PII**: pgp_sym_encrypt + entity 별 passphrase (`HIVE_PII_PASSPHRASE_<ENTITY>`)
- **이벤트**: pg_notify(`hive_events`, ...) — frame 이 LISTEN 하여 payroll.finalized → 인건비 분개
- **환경변수 = env_file 단일 출처 (D-ops-18, 2026-05-21)**: `docker-compose.yml` 의 `environment:` 블록은 literal config 만 (host/port/log_level 등). 비밀 vars (`HIVE_DB_PASSWORD`, `HIVE_JWT_SECRET`, `AZURE_HIVE_MCP_CLIENT_SECRET`, `HIVE_PII_PASSPHRASE_*`, `HIVE_MAILER_*`, `AZURE_TENANT_ID`) 는 모두 env_file `.env.local` 에서 직접 dump → `axe secret pull hive` 가 vault 의 manifest 값으로 .env.local atomic write

## Actor model — `actor_kind` 통합 (D-hive-14)

`employees.actor_kind` 컬럼으로 human / AI agent / service account / external contractor 를 단일 테이블에 통합. HR 자동화 모듈은 `WHERE actor_kind = 'human'` 으로 도메인 적용 분기.

| actor_kind | 적용 |
|---|---|
| `human` | 휴가, 4대보험, 근기법 §60, salary/equity, PII 컬럼 |
| `ai_agent` | api_budget / compute_subscription, 성과 평가 (uptime 등), OKR, audit 통합 |
| `service_account` | 자동화 system 행위자 (audit only) |
| `contractor_external` | 외부 계약직 (commission/project-fee, PII 없음) |

audit_log / org chart / access control 은 모든 actor_kind 공통.

## 인원명단 SOT (D-hive-15)

**Hive = 인원명단 superset SOT**. 100명 회사가 되면 Blueprint/Frame 사용자는 부분집합 (소수 정예). 다중 entity 표현 (`person × entity × employment_kind` 3차원) 은 Hive 만 가능.

```
Microsoft Entra ID  ──(AAD anchor)──▶  Hive  ──(hive.employee.* events)──▶  Blueprint
   (identity SOT)                  (employment SOT)              (platform-access SOT)
```

- Hire 결정 → `hive.employee.hired` → Blueprint LISTEN → User row create + AAD link
- Term 결정 → `hive.employee.terminated` → Blueprint LISTEN → soft-delete + AAD disable
- 역방향 없음 (Blueprint User 가 만들어졌다고 Hive employee 자동 등록 X — silent leak 방지)

## AI agent dual-origin (D-hive-16)

AI agent 의 lifecycle 은 인간과 비대칭. **Blueprint Agent 배포가 시작점**, Hive 가 고용관계 매핑 확정.

```
Blueprint (Agent 배포) → blueprint.agent.created
  → Hive 운영자 prompt (어느 entity 비용 부담?)
  → hive employee-create --actor-kind ai_agent --blueprint-agent-id <id> --entity <axec|axev>
  → hive.employee.hired (actor_kind=ai_agent) → Blueprint LISTEN → user_entity_map + cost_center 확정
```

**SOT 책임 분리**:
- AI agent employment 관계 (entity, cost_center, position) — **Hive**
- AI agent runtime config (model, prompt, tools, secrets) — **Blueprint**
- Cross-link: `employees.attributes.blueprint_agent_id` (soft FK)

모델 업그레이드 (4.6 → 4.7) = 같은 employee_id 유지 + `employment_records.record_kind = 'position_change'` 로 bitemporal 기록.

## 보상 — 5-table 유연 모델 (D-hive-17)

7차원 다양성 (종류·시점·산정·통화·세무·성과연동·거버넌스) 을 컴포지션 가능한 5개 테이블로:

```
compensation_plans      회사 정책 (BASE_SALARY_2026, ESOP_2025, AI_COMPUTE_2026)
       │ 1:N
       ▼
compensation_awards     개인 약정 (한진우 salary 6.5M, ai@ api_budget $500/mo)
       │ 1:N
       ▼
compensation_events     실제 이벤트 (월별 지급, vesting tick, exercise, api charge)
       │ frame_journal_id back-write (pg_notify hive.payroll.event → frame 자동 분개)

payroll_periods         월별/주별 사이클
payslips                employee × period 명세서 (line_items JSONB)
```

**plan_kind (15+1)**: salary / bonus / commission / allowance / overtime / equity / severance / benefit / reimbursement / profit_sharing / retention / relocation / **api_budget / compute_subscription** / other

**amount_rule_kind**: fixed / formula (`expr` 평가) / tiered (구간별 비율) / pool (이익 풀 분배) / discretionary

**유연성 핵심**:
- Plan ↔ Award 분리 (정책 변경 시 plan 만, award 는 frozen snapshot)
- JSONB rules (모든 산정 방식 schema 변경 없이 확장)
- `vesting_schedule` JSONB (4-year cliff / monthly / milestone / acceleration 모두)
- `performance_link` (Phase 2 OKR/KPI 와 lazy coupling)
- `frame_journal_id` (cross-service trigger via pg_notify)
- `calculation_inputs` JSONB (재현 가능성)
- `requires_resolution` + `resolution_id` (임원 보상 frame.internal_resolution 강제 link)

Phase 1 = schema 만 (5 테이블 비어 있음). Phase 3 = MCP tools (`compensation.award.create`, `payroll.run_period` 등) + frame LISTEN handler.

## frame 와의 차이점

| 항목 | frame | hive |
|---|---|---|
| 도메인 | 회계 (KSME) | HR (조직/휴가/성과/보상) |
| 격리 단위 | schema-per-entity (axec, axev) | schema-per-entity (axec, axev) — 동일 |
| 시간 모델 | fiscal_period + audit | bitemporal employment_records + audit |
| Scope | read/write/close/reopen/admin | read/write/approve/admin |
| Append-only | journal_line, raw_transaction (trigger) | audit_log, llm_call (trigger). leave_requests 는 state flow |
| Custom fields | account_template (KSME standard) | custom_field_definitions (JSONB 자유 확장) |
| Actor 모델 | (single, operator/user) | actor_kind 4종 통합 (human/ai_agent/service_account/contractor_external) |
| 인원 SOT | (없음 — frame 은 executive_officer 만) | **인원명단 superset SOT** |
| 보상 모델 | journal_line 분개만 | compensation_plans/awards/events + payslips (Phase 3) |

## Frame 연동 — Canonical ownership (D-hive-13)

한 사실은 단 하나의 서비스가 canonical owner. Hive 는 운영 독립성을 위해 frame 의 entity 메타 일부만 캐시.

| 사실 | Canonical | Hive 보유 |
|---|---|---|
| 법인명·사업자번호·회계연도 | Frame | `shared.entity` (canonical column) |
| 대표자·사업장 주소·업종·영문명 | Frame | `shared.entity.attributes.frame.*` JSONB (cache) |
| 법인등기상 임원·주주 | Frame | **미보유**. 직원 겹칠 시 `employees.attributes.frame_links` 명시적 link |
| 자본구조 (자본금·주식수) | Frame | **참조 안 함** (HR 도메인 외) |
| 직원·조직·휴가·평가·급여 | **Hive** | (Frame 이 인건비 분개 시 Hive MCP 호출) |

**Bootstrap**:
```bash
hive register-entity --id axec --legal-name "액스코퍼레이션 주식회사"
hive sync-entity-meta --entity axec --from-frame   # 대표자/주소/업종 cache
```

**재동기 시점**: 등기 변경, 대표 교체 등 frame 측 변동 시 운영자가 위 명령 1회 실행. `shared.entity.frame_synced_at` = 마지막 watermark. 자동화 (frame → hive 역방향 pg_notify) 는 Phase 2 검토.

**금지**: MCP tool path 에서 frame Postgres 직접 read (D-hive-12). Frame 의 officer roster 를 직원으로 자동 import (다른 도메인).

## 외부 노출 (2026-05-21 라이브)

```
claude.ai → Cloudflare edge (axe.axelabs.ai)
         → axelabs-tunnel (d8efecdd-... cloudflared container)
            └─ ingress: path ^/hive(/.*)?$ → host.docker.internal:3812
         → axe-hive-proxy (Caddy on :3812)
            └─ reverse_proxy hive-mcp:3810 (docker network alias)
         → hive-mcp-blue (active) / hive-mcp-green (passive)
         → hive-postgres :3800
```

**자동화**:
- `/Users/axe/.axe/hive-proxy/` — compose dir (frame-proxy 패턴 mirror). `docker compose up -d` 1회 부팅 후 영구.
- `/Users/axe/.axe/tunnels/axelabs/config.yml` — `^/hive(/.*)?$` 규칙 1줄 추가됨. cloudflared restart 1회 (~5초 다운타임).
- DNS 추가 불필요 — `axe.axelabs.ai` 가 이미 apex (path-based routing D3).
- Blue/green swap = `axe deploy hive` 가 hive-mcp docker alias 이동 + `caddy reload` 실행. cloudflared 무관 (다운타임 0).

**검증된 외부 endpoints**:
- `https://axe.axelabs.ai/hive/health` → 200
- `https://axe.axelabs.ai/hive/health/ready` → DB ping 200
- `https://axe.axelabs.ai/hive/.well-known/oauth-protected-resource` → RFC 9728 metadata
- `https://axe.axelabs.ai/hive/mcp` → 401 + WWW-Authenticate (PKCE challenge)
- `https://axe.axelabs.ai/hive/metrics` → Prometheus exposition

## Self-service onboarding (D-hive-18)

PII (주민번호·주소·계좌·전화) 는 **직원 본인이 incremental 입력**. 개인정보보호법 정보주체 본인 입력 원칙 + 운영자 부담 분산.

**3개 MCP tools**:

| Tool | 기능 |
|---|---|
| `employee_onboarding_status` | 본인의 부족 PII 필드 list. `next_step` 안내. ai_agent 는 `status="n/a"` |
| `employee_complete_onboarding` | partial PII 입력. 형식 검증 + PIIString Fernet 자동 + `onboarding_log` audit |
| `employee_verify_document` | 통장 사본 / 신분증 PDF·이미지 → Anthropic vision → declared_fields 비교 → 일치 시 자동 저장. **예금주/소유자명 = employees.name 일치 critical 검증 (다른 사람 문서 차단)** |

**필수 필드 매트릭스** (`actor_kind × employment_type`):

| 조합 | 필수 |
|---|---|
| human × full_time / part_time | national_id, home_address, bank_account_no, phone |
| human × advisor / contractor / intern | national_id, bank_account_no |
| human × other (겸직 무급) | phone (본업 entity 가 canonical) |
| ai_agent / service_account | 모두 N/A |

`shared.entity.attributes.onboarding_requirements` 로 entity 별 override.

**Self 인증**: `token.sub == employees.email` 시 self 허용, 다른 사람 → admin scope 필수.

**문서 폐기 정책**: blob 메모리 즉시 폐기, audit_log 에 `content_sha256` + actor + extracted (마스킹) 만 잔존. PDF 영구 저장 X.

## 계좌번호 cross-service 정책 (D-hive-19)

직원 계좌번호 전체는 **Hive only canonical**. Frame 미보유.

| 위치 | 상태 |
|---|---|
| `employees.bank_account_no` DB | Fernet ciphertext (`enc::v1::...`) |
| `payroll.export_remittance` 실행 중 메모리 | 평문 < 1초 |
| MCP response in transit | TLS 안 base64 |
| 운영자 머신 다운로드 XLSX | 평문 — 24h 폐기 권고 |
| audit_log | `content_sha256` 만 |
| Frame container | **미보유** |

**Cross-service event** (`hive.payroll.finalized`) 페이로드 표준:

```json
{
  "employees_paid": [
    {
      "employee_id": 2,
      "employee_name": "한진우",
      "net_amount_krw": 3500000,
      "bank_last4": "9012",       /* 매칭 hint, 전체 X */
      "bank_name": "국민은행"
    }
  ]
}
```

Frame 가 회사 통장 raw_transaction 의 출금 row 와 last4 + 금액 + 일자 매칭 → 자동 인건비 분개.

## Payroll (D-hive-17/19/20) — Phase 3 live

5 도구 + 한국 세율 lifecycle + Frame 자동 분개:

| Tool | Scope | 기능 |
|---|---|---|
| `payroll_compute_period(period_label="2026-06")` | admin | **Full re-run, UPSERT-with-gates (D-hive-29)** — 전 active 직원 대상. 직원별 case ABCDE: A 없음→INSERT, B pending+send_log=0→UPDATE (산정 fields 덮어쓰기·운영 메타 보존), C pending+발송됨→skip, D paid→skip, E reversed→skip. summary 에 `action`/`skipped_reason` 포함. 임원=고용·산재 미적용. AI agent skipped. 사후 정정 (skip 케이스) 은 `compensation_event_adjustment_create` |
| `compensation_event_adjustment_create(employee_id, period_label, line_kind, delta_krw, reason)` | admin | **페이슬립 사후 정정 (D-hive-17/29 + 룰 H)** — **case C (pending + 발송됨) 만 허용**. case A→`PAYSLIP_NOT_FOUND` / B→`PAYSLIP_NOT_DISPATCHED` (compute_period 안내) / D→`PAYSLIP_ALREADY_PAID` (운영자 수동) / E→`PAYSLIP_REVERSED` raise. 정정 시: payslip line append + 합계 보정 + `compensation_events` audit row + `hive.payroll.event` (subtype=adjustment) 발행. `delta_krw` 부호 = line.amount_krw 부호 (공제 460원 증가 = -460). 직원 메일 ≠ DB → 운영자 재발송 책임 |
| `payroll_get_my_payslip(period_label)` | read (self) | 본인 명세서 (line_items 표시) |
| `payroll_get_payslip(period_label, employee_id)` | admin | 다른 직원 조회 |
| `payroll_export_remittance(period_id)` | admin | 일괄 송금 XLSX (KB 폼). 평문 계좌 24h 폐기 권고 |
| `payroll_mark_paid(period_id, payment_reference)` | admin | status=paid + hive.payroll.finalized event 발행 |

### 한국 세율 lifecycle (D-hive-20)

`shared.tax_rate_schedule` — effective_from/until + JSONB rates + source_url. 매년 1월 운영자:

```bash
hive.tax.update_rates(
  category="income_tax",
  effective_from="2027-01-01",
  rates={"brackets": [...]},
  source_url="https://www.nts.go.kr/...",
)
```

→ 기존 active row effective_until 자동 마감 + 신규 INSERT. payroll 호출 시 period_end 기준 시점별 lookup → 과거 재계산 정합성.

**산식 정확성 3-layer**:
- L1 — `tests/payroll/golden_kr_YEAR.json` (국세청 간이세액표 fixture, 자동 CI)
- L2 — 호수회계법인 정기 cross-check → 차이 시 `adjustment` event (append-only)
- L3 — 직원 self payslip 본인 검수 → dispute → 재계산

### Frame LISTEN handler (Tier 3)

frame 측 daemon `frame listen-hive-payroll`:
- hive-postgres `LISTEN hive_events` (host.docker.internal:3800)
- `hive.payroll.finalized` 받으면 자동 분개 `Dr 5101 / Cr 1101` per employee
- idempotency = SHA256(period + employee + payment_reference)
- backfill on startup (event_outbox unconsumed)
- ack via `consumed_by` JSONB

### 산정 예시 (axev 2026-05, payroll v2 — 셀별 정확 일치 검증 완료)

| 직원 | 직급 | 지급합계 | 과세표준 | 공제합계 | 실수령 |
|---|---|---|---|---|---|
| 강태훈 | 대표 (임원) | 4,166,667 | 3,966,667 | 559,390 | **3,607,277** |
| 한진우 | 수석 | 4,166,667 | 3,966,667 | 595,090 | **3,571,577** |
| 강수훈 | 파트너 (4/1 퇴사) | — | — | — | **24,660** (건보 환급) |

산식 (D-hive-21): 식대 200K 비과세 → 과세 3,966,667 / 4대보험 보수월액 별도 신고치 (연금 4,186,222, 건보 4,022,567) / 소득세 = 국세청 2026 간이세액표 lookup / 임원 고용·산재 0.

## Payroll v2 — 한국 도메인 본질 (D-hive-21)

기존 v1 의 단순 누진세 계산은 한국 표준 아님. v2 는 7가지 본질 반영:

1. **비과세 분리** — 식대 / 차량보조금 월 200K 한도
2. **간이세액표 lookup** — `shared.simplified_income_tax_table` (월 과세 × 부양가족수 → 세액). 누진세 직접 계산 X
3. **부양가족·자녀세액공제** — `employees.dependents_count` + `children_count_under_20`
4. **4대보험 보수월액 분리** — `reported_income_pension_krw` / `reported_income_health_krw` (각자 신고소득)
5. **정산** — `health_reconciliation_krw` / `yearend_reconciliation_krw` (음수=환급, 양수=추가). `payroll_periods.attributes.pending_reconciliations` 사전 등록
6. **퇴사자 처리** — `termination_date` 일할 또는 정산-only payslip
7. **라운딩** — 국민·건강·장기 = 10원 단위 절상, 고용·소득세 = 원 단위 반올림

검증: `tests/payroll/golden_axec_2026_04.json` — 첨부 급여대장과 모든 셀 정확 일치.

## 급여명세서 메일 발송 (D-hive-22/23) — Phase 3.6

### 채널: Microsoft Graph SendMail

M365 SMTP AUTH 의 deprecation (사용자별 app password 필요) 회피. Azure AD App + `Mail.Send` Application permission + client_credentials → access token → `POST /v1.0/users/{from}/sendMail`. DKIM 자동 서명.

| 환경변수 | 용도 |
|---|---|
| `AZURE_TENANT_ID` | M365 tenant GUID |
| `HIVE_MAILER_CLIENT_ID` | `hive-payroll-mailer` AppId |
| `HIVE_MAILER_CLIENT_SECRET` | client secret (vault) |
| `HIVE_MAILER_FROM` | 발송 mailbox (예: `ai@axellc.com`) |
| `HIVE_MAILER_FROM_NAME` | display name |

### DKIM / DMARC DNS (D-hive-23)

axellc.com Cloudflare zone 에 추가:

```
selector1._domainkey.axellc.com  CNAME  selector1-axellc-com._domainkey.<tenant>.n-v1.dkim.mail.microsoft
selector2._domainkey.axellc.com  CNAME  selector2-axellc-com._domainkey.<tenant>.n-v1.dkim.mail.microsoft
_dmarc.axellc.com                TXT    "v=DMARC1; p=none; rua=mailto:ai@axellc.com; aspf=s; adkim=s"
```

⚠ Microsoft 가 2024년부터 DKIM 도메인을 `.onmicrosoft.com` 에서 `.n-v1.dkim.mail.microsoft` 로 변경. 정확한 값은 M365 Defender DKIM 화면에서 확인.

## 메시지 템플릿 관리 (D-hive-24)

```
shared.message_templates       ◀── AXE 공통 default (fallback 또는 clone source)
 └ {entity}.message_templates  ◀── per-entity customize (override)
```

- Jinja2 `SandboxedEnvironment` + `StrictUndefined` (변수 누락 = render error 로 즉시 발견)
- 변수 선언 (`variables` JSONB) — 운영자가 사용 가능 변수 한눈에 확인
- partial unique index — 동일 (code, language) 의 active 2개 동시 불가
- effective_from/until lifecycle — 산식 패턴과 동일 (시점별 적용)

### Custom template 강제 (D-hive-25)

`send_payslip_email` lookup 이 `require_entity_override=True` — shared default fallback **차단**. entity 측 active template 없으면 `TemplateNotCustomizedError`. 운영자가 한 번은 customize 거쳐야 발송 가능.

**해결 흐름** (1회):
```
notify_template_clone_from_shared(entity_id="axev", code="payslip_email")
notify_template_update(entity_id, scope="entity", template_id, body_template="...")
notify_template_preview(entity_id, template_id, scope="entity", sample_payslip_id)
notify_template_activate(entity_id, scope="entity", template_id)
```

## 발송·송금 audit log (D-hive-25)

| Table | Row 발생 시점 | 핵심 컬럼 |
|---|---|---|
| `{entity}.payslip_dispatch_log` | `export_remittance` 호출 → `mark_paid` 시 동일 row update | `period_id` / `dispatch_kind` ('remittance_export' or 'paid_finalized') / `employees_snapshot` (bank_last4 only — D-hive-19) / `total_amount_krw` / `file_sha256` / `payment_reference` / `finalized_at` |
| `{entity}.payslip_send_log` | `send_payslip_email` 1회 = 1 row (sent/dry_run/failed 모두) | `payslip_id` / `to_email` / `subject` / **`body_sha256`** / `template_id` + `template_source` / `channel` ('graph_api'/'smtp'/'dry_run') / `status` / `error_code` / `error_message` |

`body_sha256` = render 결과 본문 해시. 동일 메일 재발송 검증·변경 감지·분쟁 시 회신 증거.

## MCP Tools 추가 (Phase 3.6)

| 도구 | 권한 | 용도 |
|---|---|---|
| `notify_template_list(entity_id, scope='both', code?, include_drafts?)` | read | 템플릿 목록 (entity / shared / both) |
| `notify_template_get_active(entity_id, code, language='ko')` | read | 현재 active 1건 (룩업 우선순위 적용) |
| `notify_template_clone_from_shared(entity_id, code, language?, effective_from?)` | admin | shared active → entity draft 복사 |
| `notify_template_create(entity_id, scope, code, subject_template, body_template, ...)` | admin | 신규 draft |
| `notify_template_update(entity_id, scope, template_id, subject_template?, body_template?)` | admin | draft 수정 (active 는 immutable) |
| `notify_template_preview(entity_id, template_id+scope OR code, sample_payslip_id?)` | read | render preview |
| `notify_template_activate(entity_id, scope, template_id)` | admin | draft → active (기존 자동 마감) |
| `payroll_send_payslip(entity_id, payslip_id, dry_run?, attach_pdf?)` | admin | 단일 발송 (Graph API) |
| `payroll_send_all_payslips(entity_id, period_id, dry_run?, only_employees?, attach_pdf?)` | admin | 일괄 발송 |
| `payroll_list_send_log(entity_id, period_id?, employee_id?, status?, limit?)` | read | 메일 발송 audit |
| `payroll_list_dispatch_log(entity_id, period_id?, dispatch_kind?, limit?)` | read | 송금 의사 snapshot 조회 |
| `payroll_preview_payslip_pdf(entity_id, payslip_id)` | admin | PDF base64 미리보기 |

## 관련 문서

- [Blueprint service](/services/blueprint) — MCP 클라이언트
- [Frame service](/services/frame) — 미러 패턴의 reference impl
- [/Users/axe/hive/DECISIONS.md](https://github.com/soohunkang/hive/blob/main/DECISIONS.md) — D-hive-1~25

---

<!-- PAGE https://docs.axelabs.ai/services/index -->

# Index

> AXE 투자판단 backend — relational compute substrate + artifact-first judgment layer + owner:index skills. financial_model 6-table SoT + 5 judgment kinds + 35 MCP tools (+ Archive evidence-blob). LIVE (axe.axelabs.ai/index).

URL: https://docs.axelabs.ai/services/index

# Index

**한 줄 소개**: 펀드 운용 lifecycle (소싱 → 실사 → IC → 포트폴리오 → 엑싯 → LP IR) 의 **투자판단 backend**. frame (회계) · hive (HR) 와 같은 vertical layer 이되, "사실의 보존소" 를 넘어 **판단(가정·calibration·comp·base_rate)을 typed fact 로 적재**하고 그 판단이 지배하는 relational compute 를 deterministic 하게 재실행한다. Rust + axum + sqlx ([D-cortex-7](/ops/decisions) precedent).

> **상태**: LIVE. MCP `https://axe.axelabs.ai/index/mcp` · schema discovery `/index/schemas` · 공개 집계 현황 [https://axe.axelabs.ai/index](https://axe.axelabs.ai/index). 23 deal · 380 artifact · 15 typed-fact schema · 35 MCP 도구 (live 집계 = 현황 페이지). **브라우저 SSO firm-read 상세 뷰 LIVE** ([D-index-48](/ops/decisions)) — [axe.axelabs.ai/index](https://axe.axelabs.ai/index) 로그인 → Entra → 딜별 IRR·calibration 상세.

## 3-layer 모델

index 는 한 덩어리가 아니라 세 layer 가 쌓인 구조다:

| Layer | 무엇 | 예 |
|---|---|---|
| **L1 · relational compute substrate** | deal 의 숫자가 사는 관계형 SoT. financial_model 6-table + fund_investment N:M + DSL formula + topo evaluator. cell 재계산 deterministic | `compute_outputs` · `query_irr` · `compute_full_model` |
| **L2 · artifact-first judgment layer** | relational 값을 *지배하는 판단* 을 typed artifact 로 적재. 가정·calibration·comp·base_rate + citation(근거) + append-only event(감사) | `get_judgment_provenance` · `list_calibrations` · `confirm_artifact` |
| **L3 · skills + schema contract** | 투자 도메인 skill (owner:index) 의 SoT + `frozen_enums_hash` 로 고정된 typed-fact 계약 | `list_skills` · `/index/schemas` |

아키텍처 한 줄 ([현황 페이지](https://axe.axelabs.ai/index) 의 "아키텍처" 섹션과 동일): **index owns TRUTH** (사실 레이어) · **Blueprint owns ROAD** (운영·UI, index 사실 소비) · **surface owns RUN** (claude.ai connector / Claude Code — 인증 후 MCP 호출).

## artifact-first judgment layer ([D-index-45](/ops/decisions))

index 의 본질적 차별성. relational compute 만 있으면 "IRR 이 23.4%" 는 알지만 **"왜 그 값인가"** 는 휘발한다. judgment layer 가 그 판단을 일급 fact 로 보존한다.

- **5 judgment kind**: `index.assumption` (한 relational field 를 지배하는 입력) · `index.calibration` (SURFACE→CALIBRATED scrub) · `index.comp` (비교 밴드) · `index.base_rate` (확률 기준율) · `index.deal_judgment` (**thesis-level 처분 판단** — 왜 passed/lost/died + durable lesson, [D-index-49](/ops/decisions) dead-deal harvest; claim 과 달리 author·불변·supersede). field 모양 = [schema-catalog § judgment](/services/index/schema-catalog#b-judgment-layer-4--artifact-first-d-index-45).
- **링크는 일급 citation 이지 컬럼이 아님**: citation kind `index_field` (ref `{deal,field}`) 가 relational field 로, `artifact_ref` (ref `{artifact_id,relation}`, relation ∈ `calibrated_from`/`scrubbed_from`/`anchored_to`/`contradicts`/`supersedes`) 가 fact↔fact 로 연결.
- **lifecycle** propose→confirm, RLS owner_only, append-only `artifact_event`.
- **seed = SoT** ([D-index-46](/ops/decisions)): judgment 는 `seed.yaml` 의 `judgment:` block + `seeds/_corpus.yaml` 에서 `seed-ingest --emit-judgment` 로 파생. hardcoded backfill 폐기.
- **scrub 의 정직**: surface(표면) 값을 research-calibrated 값으로 조정할 때 조용히 하나 고르지 않고 calibration artifact 로 충돌을 드러낸다 ([D-index-24](/ops/decisions)/[26](/ops/decisions)).

현재 380 artifact / 23 deal (assumption 218 · calibration 58 · comp 35 · base_rate 7 · **deal_judgment 23** + extracted_metric/figure — live). deal_judgment = 16 passed · 6 invested · 1 lost ([D-index-49](/ops/decisions) — 죽은 딜의 "왜 패스했나" judgment corpus).

## MCP 도구 카탈로그 (35)

> **Archive (L-Archive · [D-index-50](/ops/decisions) · [D-index-51](/ops/decisions))** — 죽은 딜 teardown: OneDrive/Blueprint raw 파일을 index 가 흡수 (파일 bytes 를 Postgres bytea content-addressed 저장 → 단일 DB 백업·OneDrive 독립). MCP tools: `register_evidence_blob`(512MiB 상한) · `list_deal_evidence` · `get_evidence_blob` · `schedule_postmortem` · `list_postmortems` · `update_postmortem`. CLI/audit surface 는 아래 표 — `ingest-evidence`(archive) ↔ `export-evidence`(restore 역연산) + `teardown_event`(recovery map) + `axe index teardown` orchestrator ([D-index-51](/ops/decisions)).

### Archive — teardown CLI / audit (L-Archive)

| CLI / audit | 기능 |
|---|---|
| `index ingest-evidence --deal <c> --kind <k> <files…>` | 파일 → `evidence_blob` (archive, content-addressed sha256 dedup, 512MiB 상한) |
| `index export-evidence --deal <c> --out <dir>` | `evidence_blob` → 파일 복원 (**restore = 역연산**; 디스크 재-hash sha256 round-trip 검증, 마지막 줄 JSON `mismatches==[]` 게이트) |
| `teardown_event` (table) | teardown 감사 행 + `sha_manifest` recovery map `[{path,sha256,kind,size}]`, RLS owner_only |
| `axe index teardown / restore / list-archive` | cross-service orchestrator — 폴더해소(Blueprint `Workspace.drivePath`)·OneDrive+workspace 삭제·`teardown_event` 감사 ([D-index-51](/ops/decisions)) |

served tool 은 `src/mcp.rs` 의 `tool_schemas()` 가 SoT (현황 페이지의 "MCP 도구 카탈로그" 와 동일). 인증된 `/index/mcp` 에서만 호출 가능. 그룹별:

### deal / IRR query (L1)

| Tool | 기능 |
|---|---|
| `list_deals` | deal 요약 list (stage/sector 필터) |
| `get_deal` | deal full snapshot (target_company + fund_investments + scenarios + leaf/driver count) |
| `query_irr` | deal IRR + per-position 독립 IRR. **IRR(E[CF]) canonical** |
| `fund_performance` | 투자조합(1호/2호/3호) 펀드별 수익성 — 횡단 pool → fund IRR(E[CF]) + E[MoM] |
| `compute_outputs` | exit_matrix aggregation per scenario (Σ leaf.prob × proceeds) + dead_leaf |
| `get_exit_matrix` | leaf-level breakdown (scenario × timing × path × prob × proceeds) |
| `cross_deal_benchmark` | driver 별 cross-deal 비교 |
| `validate_financial_model` | 6 sanity check (DAG cycle · scenario coverage · leaf prob · invariants) |
| `compute_full_model` | DSL evaluator 가 derived formula 를 period 순차 evaluate (cell-equiv) |
| `compute_3fs` | IS/BS/CF typed line items 재구성 (IS focus) |

### artifact / judgment (L2)

| Tool | 기능 |
|---|---|
| `query_artifacts` | owner artifact list (para_anchor/kind/metric_kind/status 필터, 파생 status) |
| `get_artifact` | 단일 artifact full view (payload + citation + event 이력 + 파생 status) |
| `confirm_artifact` | proposed fact confirm (append-only event, edit_payload 시 payload UPDATE) |
| `reject_artifact` | proposed fact reject (row 유지, status→rejected) |
| `reconcile_artifacts` | cross-source 충돌 surface (metric별 group, relative_gap > 10% flag) |
| `get_judgment_provenance` | 한 relational field 를 지배하는 assumption/calibration + 해소된 evidence |
| `list_calibrations` | deal 의 모든 calibration (scrub_kind + surface→calibrated + 링크) |
| `query_dispositions` | **dead-deal harvest** — verdict/sector/tag 횡단 `deal_judgment` ("왜 passed/lost 했나" + durable lesson, [D-index-49](/ops/decisions)) |
| `get_deal_judgment` | 단일 deal 의 처분 JUDGMENT (verdict + thesis + rationale + lesson + backing comp + supersede 체인) |
| `verify_citations` | evidence-durability audit (durable vs fragile 집계) |

### ingest / propose (L2 적재)

| Tool | 기능 |
|---|---|
| `propose_artifacts_from_ingest` | dataroom ingest sidecar → artifact store 에 proposed fact 적재 (+`_provenance` stamp + drift gate) |
| `propose_deal_closure` | atomic batch — target_company + deal + fund_investment[] + financial_model 을 1 transaction INSERT |
| `import_xlsx` | LP 가 수정한 xlsx Assumptions sheet → DB driver_value diff/apply |
| `draft_seed_from_artifacts` | deal artifact → seed.yaml SCAFFOLD auto-draft (정문 자동화, calibration 자동생성 안 함) |

### export (LP deliverable)

| Tool | 기능 |
|---|---|
| `export_lp_html` | self-contained HTML dashboard (IRR + IS + Exit Matrix + Assumptions) |
| `export_lp_model` | 4-sheet xlsx (Assumptions · IS · Exit Matrix · IRR Summary), deterministic |
| `export_lp_bundle` | xlsx + index.html + README.md 를 단일 zip |

### skill (L3)

| Tool | 기능 |
|---|---|
| `list_skills` | index 산하 skill 카탈로그 (frontmatter + sub-dir) |
| `get_skill_resource` | skill resource fetch (content + sha256) |

## evidence-durability

citation 은 source 파일이 이동·개명·삭제돼도 살아남아야 한다. evidence-durability v1 에서 모든 citation 은 **sha256 content-anchor** (cited 파일 bytes 의 hash) 를 PRIMARY 앵커로 carry + 추가 앵커 (`drive_item_id` · `workspace_id`+`rel_path` · `marker` readiness).

- **DURABLE** := ref 에 non-null `sha256` OR `drive_item_id` OR (`workspace_id` AND `rel_path`). 아니면 FRAGILE (path-only).
- `verify_citations` 도구가 owner citation 을 durable/fragile 로 집계 (per-deal 분해 + fragile kind 목록).
- [현황 페이지](https://axe.axelabs.ai/index) 가 durable% 를 공개 (현재 sha256 backfill 진행 전 — citation durability 0%, anchor 적재 path 가동).

상세 citation kind = [schema-catalog § citation](/services/index/schema-catalog#citation-kinds-evidence).

## 기술 스택

frame/hive 패턴 미러하되 **Rust + axum + sqlx ([D-cortex-7](/ops/decisions) precedent, [D-index-2](/ops/decisions))**:

| 항목 | 값 |
|---|---|
| 언어 | Rust |
| 프레임워크 | axum + tower-http |
| DB | PostgreSQL 16 + sqlx (compile-time SQL check) |
| Migration | sqlx migrate (timestamped SQL) |
| MCP transport | axum + Streamable HTTP (cortex 패턴) |
| 인증 | jsonwebtoken + reqwest JWKS — 다중 issuer peek: **Microsoft Entra ID** (RS256, claude.ai/Claude Code) + **Blueprint 플랫폼 토큰** (RS256/JWKS, `axe` CLI·브라우저 SSO, [D-axe-idp-1](/ops/decisions)) + 선택 HS256 self-token. email = RLS actor |
| RLS | `index_app` NOSUPERUSER role + per-request `SET LOCAL index.actor` GUC (owner_only) |
| Formula DSL | 10-operator parser + topological evaluator |
| Container | distroless 단일 binary |

이유: (a) artifact 의 discriminated union 과 Rust algebraic type 자연, (b) sqlx compile-time SQL check 가 schema/RLS query 안전성 보강, (c) long-running 단일 process panic-free.

## 포트 (범위: 40xx)

| 포트 | 컨테이너 | 용도 |
|---|---|---|
| 4000 | `index-postgres` | PostgreSQL 16 |
| 4010 | `index-mcp-blue` | MCP HTTP (active) |
| 4011 | `index-mcp-green` | MCP HTTP (passive) |
| 4012 | `axe-index-proxy` | Caddy blue/green selector |

39xx (matrix) 다음 40xx 자연 할당. cloudflared ingress `^/index(/.*)?$` → `host.docker.internal:4012`. (32xx 는 Cortex.)

## URL 컨벤션

```
axe.axelabs.ai/index                ← 공개 집계 현황 (HTML) · 세션 있으면 firm-read 상세 (D-index-48)
axe.axelabs.ai/index/login          ← 브라우저 SSO 시작 (Blueprint OIDC Auth-Code + PKCE S256)
axe.axelabs.ai/index/callback       ← OAuth redirect (code→token→세션 쿠키)
axe.axelabs.ai/index/logout         ← 세션 쿠키 제거
axe.axelabs.ai/index/mcp            ← MCP endpoint (인증 필요, per-deal 상세)
axe.axelabs.ai/index/schemas        ← schema discovery (인증)
axe.axelabs.ai/index/healthz        ← readiness
axe.axelabs.ai/index/.well-known/oauth-protected-resource
```

> `GET /index` 는 **두 얼굴** ([D-index-48](/ops/decisions)): 세션 없으면 **공개 집계** (deal.stage count · artifact.kind count · schema 이름·버전 · 도구 list 만 — 개별 deal·회사·재무값 **불포함**, RLS per-owner private, [D-index-2](/ops/decisions)); 유효 Blueprint-SSO 세션이면 **firm-read 상세** (deal별 entry 시점·예상 exit(entry+E[holding])·**상태**(Project/Resource/Archive lifecycle, D-index-50) + IRR(E[CF])·E[MoM]·P(loss) + 펀드 1·2·3호 성과 + calibration — MCP `query_irr`/`fund_performance` 와 byte-identical). 무세션 leak-tripwire 는 회귀 테스트로 강제. 쿠키 서명은 `INDEX_JWT_SECRET` 재사용(httpOnly+Secure+SameSite=Lax). 브라우저 SSO 는 **✅ LIVE** (2026-06-04 — Blueprint `axe-index-web` web policy 배포 + env `INDEX_WEB_LOGIN_READY=true`): `axe.axelabs.ai/index` 로그인 버튼 → Blueprint OIDC(Auth-Code+PKCE) → Entra → 상세. per-deal 상세는 그 외엔 인증된 `/index/mcp` 로.

## owner:index skills ([D-index-47](/ops/decisions))

투자 도메인 skill (ic · ingest · pmc + due-diligence · vc-deal-sourcing · investor-relations · portfolio-management · legal-compliance) 은 `owner: index` 로 vertical-gated. **index customer (axe) 만 투자 skill 수신**, 비-index customer 는 universal 9개만. 분배 = universal-base mirror + `--attest` drift sentinel + Blueprint boot/webhook 양 경로 gate. 상세 (P0–P3 LIVE) = [skill-ownership](/services/index/skill-ownership).

## OAuth-RP 흐름

frame/hive 와 동일. customers.yaml `sso.apps.index_mcp` 에서 client_id / application_id_uri 읽어 Microsoft Entra ID id_token RS256 검증.

```
surface → POST /index/mcp (no auth)
index   → 401 + WWW-Authenticate: Bearer resource_metadata="..."
client  → GET /index/.well-known/oauth-protected-resource
index   → { resource, authorization_servers: [Microsoft] }
client  → Microsoft OAuth (PKCE) → access_token (aud = Application ID URI)
client  → POST /index/mcp Authorization: Bearer <token>
index   → JWKS RS256 verify + aud + iss + email → owner 매핑 → MCP session
```

Blueprint platform token 도 trust (D-axe-idp-1 Phase 2). 상세: [/architecture/auth](/architecture/auth).

## Production 배포 (axe ship index)

[D-index-10](/ops/decisions) Phase 0 acceptance 8/8 PASS → production LIVE. `axe ship index` (docs-check → push → blue/green deploy). Entra ID app `47fe856f-75e8-457b-a10e-fce1559939f5`, vault 5 secret manifest, cloudflared `/index` ingress (CF API self-service). 검증:

```bash
docker compose up -d                                # 4 컨테이너 healthy
curl http://localhost:4010/healthz                  # blue 직접
curl http://localhost:4012/healthz                  # proxy 경유
curl -X POST http://localhost:4012/index/mcp        # 401 + WWW-Authenticate
docker exec index-mcp-blue /usr/local/bin/index dump-schemas | jq '.metadata'  # frozen_enums_hash
```

CLI 회귀 (auth 미경유 직접 dispatch):

```bash
docker exec index-mcp-blue /usr/local/bin/index mcp-call query_irr --args '{"deal_code":"Iippo"}'
docker exec index-mcp-blue /usr/local/bin/index mcp-call compute_outputs --args '{"deal_code":"Iippo"}'
```

## 운영 노트

- **Blue/green deploy** (4010/4011 동시 실행, network alias swap via axe-index-proxy)
- **Append-only**: 모든 typed fact 에 `artifact_event` audit + financial_model `locked_at` 후 immutable
- **RLS owner_only**: per-request `SET LOCAL index.actor` GUC, FORCE RLS — 다른 owner 의 artifact 미열람
- **provenance + drift gate** ([D-index-47](/ops/decisions) P1): propose event 에 `_provenance` stamp + `SCHEMA_CONTRACT_DRIFT` gate
- **백업**: restic Tier A — index-postgres `pg_dumpall` 매일 03:00 ([D-index-51](/ops/decisions): `evidence_blob` = 죽은 딜 SOLE 사본, 백업이 유일 보호) + [D-config-14](/ops/decisions)
- **환경변수 = env_file 단일 출처** ([D-ops-18](/ops/decisions)), `axe secret pull index` 가 vault → `.env.local`

## 관련 문서

- [/services/index/financial-model](/services/index/financial-model) — L1 relational: 6-table SoT + DSL + topo evaluator + xlsx round-trip + 3 deal worked example
- [/services/index/schema-catalog](/services/index/schema-catalog) — 14 active typed-fact schema (10 base + 4 judgment) + frozen_enums_hash + citation kinds
- [/services/index/skill-ownership](/services/index/skill-ownership) — owner:index skill 의 P0–P3 구현 (D-index-47)
- [/services/index/skill-evolution](/services/index/skill-evolution) — 5 skill → service 진화 (design-era, 일부 superseded)
- [/services/index/skill-integration](/services/index/skill-integration) — skill 통합 아키텍처 (design-era, 일부 superseded)
- [현황 페이지](https://axe.axelabs.ai/index) — live 집계 (deal/artifact/schema/도구)
- [/ops/decisions D-index-45/46/47](/ops/decisions) — judgment layer · seed=SoT · provenance+skill ownership
- [/services/cortex](/services/cortex) — Rust + axum + sqlx 미러 reference

---

<!-- PAGE https://docs.axelabs.ai/services/index/financial-model -->

# 재무 모델 (xlsx → DB)

> index 의 핵심 차별성 — financial_model 6-table SoT + fund_investment N:M + DSL formula + topo evaluator + xlsx round-trip. Iippo / Sentry / Canopy 실 데이터로 schema 검증.

URL: https://docs.axelabs.ai/services/index/financial-model

# 재무 모델 — xlsx 를 DB 의 일급 entity 로

## 한 줄 정의

ic skill 의 `ic/finance/{3fs_*,scenario_deltas,exit_matrix,irr_analysis}` 산출물을 **6-table typed model** 로 승격. xlsx 가 source 가 아니라 **DB 가 source, xlsx 는 ingest 입력 + export 출력**. DSL formula + topo evaluator 가 cell 재계산 deterministic. fund_investment 가 cash flow + IRR carrier — 한 deal 의 여러 fund × 여러 round 별 IRR 독립 산출.

> 본 페이지는 index 의 **L1 (relational compute substrate)** 이다. 이 relational 값을 *지배하는 판단* (가정·calibration·comp·base_rate) 은 그 위 **L2 — artifact-first judgment layer** ([D-index-45](/ops/decisions)) 가 typed fact 로 보존하며, citation `index_field` (ref `{deal,field}`) 로 여기 relational field 에 링크된다. "왜 이 driver/exit_multiple/probability 가 이 값인가" 추적 = `get_judgment_provenance`. 3-layer 전체 = [/services/index § 3-layer 모델](/services/index#3-layer-모델).

## 왜 필요한가

ic skill 의 현재 흐름:

```
회사 IR pack
  ↓ vision_ingest
dataroom/*.{pdf,pptx,xlsx}
  ↓ /ic 19-agent orchestration (3-5시간)
ic/finance/3fs_base/v7.xlsx     ← scenario 4종 × 3FS 모델 (8 sheet)
ic/finance/scenario_deltas/v7.yaml ← 4 scenario × ~15 driver
ic/finance/exit_matrix/v7.yaml  ← scenario × timing × path leaf 트리
ic/finance/irr_analysis/v7.xlsx ← 확률가중 IRR 산출
ic/memo/v8.md                   ← IRR 23.4% 라는 한 줄 cite
  ↓ PDF render + Teams reply
산출물 휘발 — 다음 deal 도 grep 으로 재추출
```

5 격차:

| 격차 | 현재 (xlsx + yaml + markdown) | 결과 |
|---|---|---|
| Cross-deal driver benchmark | portfolio 의 churn / gross_margin / IRR 시계열 grep 으로 못 풀음 | "axec/axev 포폴 평균 gross margin?" 답 토큰 폭증 |
| Citation chain | IC memo "IRR 23.4%" 가 xlsx 어느 cell, 어느 driver 에서 왔는지 trace 불가 | LP audit 시 "한 숫자라도 잡히면" IRR 신뢰 무너짐 (ic skill `citation_trace.py` 본질) |
| Time-travel | Q2 IC 시점의 IRR vs 현재 IRR diff 안 됨 | 의사결정 archaeology 불가 |
| 펀드별 IRR 분리 | 1호 + 2호 동시 투자 시 각각 IRR 산출 수작업 | Iippo / Sentry 같은 multi-fund deal 의 정합성 안 잡힘 |
| Sanity check 휘발 | ic skill 의 4 check 가 매번 재실행. 누적 audit 없음 | 모순 반복 (Superman v4 "11,250백만원 (1,200억 × 18.75%)" 4-number 모순 같은 사고) |

→ DB 가 source 면 위 5 격차 모두 SQL aggregate / FK / trigger 로 자연 해결.

## 6-table SoT

```
financial_model (deal 별 1+, version)
  │
  ├─ financial_driver (driver tree DAG — code, kind, formula DSL, dependencies[])
  │     ↑ topological sort 로 평가 순서 결정
  │
  ├─ financial_scenario (Upside/Base/Mgmt/Downside, probability, driver_changes)
  │     ↑ ic skill 의 PR-J 4-scenario 정합
  │
  ├─ financial_driver_value (model × driver × scenario × period_index → value)
  │     ↑ scenario 가 baseline 위에 override 만 — driver_changes 의 DB 형태
  │
  ├─ financial_output (model × scenario × output_code × period?)
  │     ↑ irr / moic / npv / exit_val / runway / revenue_year_5 ...
  │     ↑ inputs_hash 가 driver_value snapshot sha256 — reproducibility lock
  │
  └─ exit_matrix_leaf (scenario × timing × path)
        ↑ ic skill exit_matrix yaml 의 3-level tree 의 DB 형태
        ↑ probability × proceeds_krw + dead_leaf/concentration flag (check_exit_matrix.py 결과 캐시)
```

### Schema (SQL skeleton)

```sql
-- per-entity schema (axe_ia_001 / axe_ia_002 / ...)

CREATE TABLE financial_model (
  id                    uuid PRIMARY KEY,
  deal_id               uuid NOT NULL REFERENCES shared.deal(id),
  version               int  NOT NULL,
  name                  text NOT NULL,                    -- e.g., "Iippo IC v8 base model"
  time_axis_kind        text NOT NULL CHECK (time_axis_kind IN ('year','quarter','month')),
  start_period          date NOT NULL,                    -- e.g., 2025-01-01 (Y0)
  horizon_periods       int  NOT NULL,                    -- e.g., 7 (Y0~Y7)
  currency              text NOT NULL DEFAULT 'KRW',
  unit_scale            numeric NOT NULL DEFAULT 1,       -- 1 / 1000 / 1000000 (천원/백만원)
  base_revenue_period0  numeric,                          -- e.g., 120,000,000 (Iippo Y0 매출)
  created_by            text NOT NULL,
  created_at            timestamptz NOT NULL DEFAULT now(),
  locked_at             timestamptz,                      -- 후 immutable
  source_xlsx_sha256    text,
  source_xlsx_citation  jsonb,                            -- {kind:"onedrive", drive_item_id, version, sheet}
  source_yaml_citations jsonb DEFAULT '[]'::jsonb,        -- scenario_deltas/exit_matrix yaml refs
  UNIQUE (deal_id, version)
);

CREATE TABLE financial_driver (
  id              uuid PRIMARY KEY,
  model_id        uuid NOT NULL REFERENCES financial_model(id) ON DELETE CASCADE,
  code            text NOT NULL,                          -- e.g., "revenue_growth_y1"
  kind            text NOT NULL CHECK (kind IN ('input','derived','output')),
  formula         text,                                   -- DSL — null if input
  dependencies    text[] NOT NULL DEFAULT '{}',           -- 다른 driver code list
  units           text NOT NULL,                          -- '%', 'KRW', 'count', 'months', 'multiple'
  category        text NOT NULL,                          -- 'revenue', 'cost', 'opex', 'capex', 'financing', 'wc'
  description     text,
  display_order   int,
  UNIQUE (model_id, code)
);

CREATE TABLE financial_scenario (
  id                     uuid PRIMARY KEY,
  model_id               uuid NOT NULL REFERENCES financial_model(id) ON DELETE CASCADE,
  code                   text NOT NULL,                   -- 'base', 'upside', 'mgmt', 'downside', 'custom_*'
  name                   text NOT NULL,                   -- 'AXE Base'
  kind                   text NOT NULL CHECK (kind IN ('base','upside','mgmt','downside','custom')),
  probability            numeric(5,4) NOT NULL,           -- 0.0000 ~ 1.0000 (per-scenario, 합 = 1)
  description            text,
  driver_changes         jsonb NOT NULL DEFAULT '{}'::jsonb, -- narrative {story, rationale[], key_assumption_overrides}
  parent_scenario_id     uuid REFERENCES financial_scenario(id), -- fork chain
  locked_at              timestamptz,
  UNIQUE (model_id, code)
);

CREATE TABLE financial_driver_value (
  model_id           uuid NOT NULL,
  driver_code        text NOT NULL,
  scenario_id        uuid NOT NULL REFERENCES financial_scenario(id) ON DELETE CASCADE,
  period_index       int  NOT NULL,                       -- 0 ~ horizon_periods
  value              numeric,
  is_override        bool NOT NULL DEFAULT false,         -- true = scenario override on baseline
  PRIMARY KEY (model_id, driver_code, scenario_id, period_index),
  FOREIGN KEY (model_id, driver_code) REFERENCES financial_driver(model_id, code)
);

CREATE TABLE financial_output (
  id              uuid PRIMARY KEY,
  model_id        uuid NOT NULL REFERENCES financial_model(id) ON DELETE CASCADE,
  scenario_id     uuid NOT NULL REFERENCES financial_scenario(id) ON DELETE CASCADE,
  output_code     text NOT NULL,                          -- 'irr', 'moic', 'npv', 'exit_valuation', 'axe_proceeds_total'
  period_index    int,                                    -- null = terminal output, int = time series
  value           numeric,
  computed_at     timestamptz NOT NULL DEFAULT now(),
  inputs_hash     text NOT NULL,                          -- sha256(driver_value snapshot) — reproducibility
  UNIQUE (model_id, scenario_id, output_code, period_index)
);

CREATE TABLE exit_matrix_leaf (
  id                  uuid PRIMARY KEY,
  scenario_id         uuid NOT NULL REFERENCES financial_scenario(id) ON DELETE CASCADE,
  timing              text NOT NULL,                      -- '3y', '5y', '7y', 'never'
  path                text NOT NULL,                      -- 'ma', 'ipo', 'secondary', 'writedown', 'ma_strategic', 'partial'
  probability         numeric(5,4) NOT NULL,              -- 0.0000~1.0000 (per timing, 합 = 1)
  description         text,
  proceeds_krw        numeric,                            -- 회사 전체 exit proceeds (EqV or EV)
  axe_proceeds_krw    numeric,                            -- AXE 회수 (proceeds × ownership_pct_fd × dilution)
  recovery_rate       numeric(5,4),                       -- writedown 시 5-15% 잔존 (D-PR 22 wd-assumption)
  dead_leaf           bool NOT NULL DEFAULT false,        -- check_exit_matrix.py 결과
  concentration       bool NOT NULL DEFAULT false,        -- 단일 leaf P > 10% (concentration warning)
  UNIQUE (scenario_id, timing, path)
);
```

상세 RLS · trigger · index 는 [Phase 0 migration SQL](/services/index/schema-catalog#migration-sql) 참조.

## fund_investment

본 서비스의 두 번째 핵심 abstraction ([D-index-5](/ops/decisions)).

**deal 은 회사 단위 thesis. fund_investment 는 cash flow + IRR carrier.**

### 왜 3차원 N:M?

실 데이터:
- **Iippo**: 1 deal × **2 fund** (1호 99,998,912 + 2호 100,000,000, 같은 round Pre-A)
- **Sentry**: 1 deal × 1 fund × **multi-round option** (1호 5억 + 후속 5억 pro-rata option future)
- **Canopy**: 1 deal × 1 fund × **다른 시점 multi-round** (1호 BW 5억 initial + 1호 신주 follow 1억 v5)

세 deal 모두 N:M 의 다른 축. 단일 (deal, fund) FK pair 로는 부족.

### Schema

```sql
CREATE TABLE shared.fund_investment (
  id                       uuid PRIMARY KEY,
  deal_id                  uuid NOT NULL REFERENCES shared.deal(id),
  fund_entity_id           text NOT NULL REFERENCES shared.entity(id),  -- e.g., 'axe_ia_001'
  round_label              text NOT NULL,                                -- '초기', 'follow-on v5', 'pro-rata option'
  instrument               text NOT NULL,                                -- 'RCPS', 'BW', 'SAFE', '신주', '보통주'
  committed_krw            numeric NOT NULL,                             -- 약정 금액
  invested_krw             numeric,                                      -- 실 납입 (paid 후 set)
  share_count              numeric,                                      -- 주식 수
  price_per_share          numeric,                                      -- 주당 가격
  entry_date               date,                                         -- 결의/계약일
  paid_date                date,                                         -- 납입일 (status=paid 후 set)
  pre_money_krw            numeric,                                      -- 진입 시점
  post_money_krw           numeric,
  ownership_pct_post       numeric(7,6),                                 -- 0.000000 ~ 1.000000
  ownership_pct_fd         numeric(7,6),                                 -- F/D 희석 후
  status                   text NOT NULL CHECK (status IN
                              ('committed','paid','locked_in','written_off','partial_exited','exited')),
  conditions               jsonb DEFAULT '[]'::jsonb,                    -- PCC trigger 같은 조건
  conditions_met_at        timestamptz,                                  -- 조건부 → 무조건 전환 시점
  evidence_citations       jsonb DEFAULT '[]'::jsonb,                    -- 계약서 OneDrive ref 등
  created_at               timestamptz NOT NULL DEFAULT now(),
  updated_at               timestamptz NOT NULL DEFAULT now(),
  UNIQUE (deal_id, fund_entity_id, round_label)
);

CREATE INDEX fund_investment_deal_idx ON shared.fund_investment (deal_id);
CREATE INDEX fund_investment_fund_idx ON shared.fund_investment (fund_entity_id);
CREATE INDEX fund_investment_status_idx ON shared.fund_investment (status) WHERE status IN ('committed','paid','locked_in');
```

### Per-fund IRR 계산

```sql
-- financial_output 의 axe_proceeds_total 산출 → fund_investment.ratio 로 split
-- Iippo 케이스:
--   financial_output (scenario=base, output_code=axe_proceeds_total) = 9.4억 (Y5 회수)
--   fund_investment Iippo×axe_ia_001 ratio = 99,998,912 / 199,998,912 = 0.500003
--   fund_investment Iippo×axe_ia_002 ratio = 100,000,000 / 199,998,912 = 0.499997
--   ↓
--   1호 회수 = 9.4억 × 0.500003 ≈ 4.70억
--   1호 IRR = irr(cash_flow = [-99,998,912 @ 2026-05-15, +4.70억 @ 2030-06-30])
--   2호 회수 = 9.4억 × 0.499997 ≈ 4.70억
--   2호 IRR = irr(cash_flow = [-100,000,000 @ 2026-09-?? (PCC 6 후), +4.70억 @ 2030-06-30])
--
-- 같은 회사 같은 회수 비율이지만 paid_date 가 다르면 IRR 다름 (2호 납입 지연 → IRR 약간 ↓)
```

view `fund_investment_irr`:

```sql
CREATE VIEW shared.fund_investment_irr AS
SELECT
  fi.id              AS fund_investment_id,
  fi.deal_id,
  fi.fund_entity_id,
  fi.round_label,
  fi.committed_krw,
  fi.invested_krw,
  fi.paid_date,
  fs.scenario_id,
  fs.code            AS scenario_code,
  fs.probability     AS scenario_probability,
  fo.value           AS total_axe_proceeds_krw,
  -- fund_investment 비례 split
  fi.committed_krw / SUM(fi.committed_krw) OVER (PARTITION BY fi.deal_id) AS ratio,
  fo.value * (fi.committed_krw / SUM(fi.committed_krw) OVER (PARTITION BY fi.deal_id))
                     AS fund_share_proceeds_krw,
  -- IRR 계산은 Rust 측 compute_outputs 가 채워서 별 row 로 저장 (output_code='irr_per_fund')
FROM shared.fund_investment fi
JOIN financial_scenario fs ON fs.model_id IN (
  SELECT id FROM financial_model WHERE deal_id = fi.deal_id ORDER BY version DESC LIMIT 1
)
JOIN financial_output fo ON fo.scenario_id = fs.id AND fo.output_code = 'axe_proceeds_total';
```

이 view 위에 확률가중 IRR 합산도 SQL aggregate 한 줄.

## DSL Formula

### 왜 한정 DSL?

xlsx formula 를 그대로 못 옮김 — cell ref (`B14`) 를 driver ref (`revenue_y2`) 로 매핑 필요. 또한 Excel 의 ~500 함수 중 IC memo cite 하는 건 10개 미만. 한정 DSL 이 (a) parser 단순, (b) audit 가능, (c) 보안 (eval 안 함).

### 문법 (10 operators)

```
expr        = term (('+' | '-') term)*
term        = factor (('*' | '/') factor)*
factor      = number | driver_ref | func_call | '(' expr ')'
driver_ref  = identifier '[' period ']'  | identifier
period      = 'y0' | 'y1' | ... | 'y<n>' | 'current'
func_call   = func_name '(' args ')'
func_name   = 'min' | 'max' | 'if' | 'sum' | 'avg' | 'lag' | 'growth' | 'cum'
```

예제:

```
# 매출 = 직전 매출 × (1 + 성장률)
revenue[y1] = revenue[y0] * (1 + revenue_growth_y1)
revenue[y2] = revenue[y1] * (1 + revenue_growth_y2)
# ...
revenue[y_n] = lag(revenue, 1) * (1 + lag(revenue_growth, 0))

# 매출원가 = 매출 × (1 - 매출총이익률)
cogs = revenue * (1 - gross_margin_terminal)

# 영업이익 = 매출 - 매출원가 - 판관비
ebit = revenue - cogs - opex_sm - opex_rnd - opex_ga
opex_sm = revenue * opex_sm_per_revenue
opex_rnd = revenue * opex_rnd_per_revenue
opex_ga = revenue * opex_ga_per_revenue

# 운전자본
ar = revenue * ar_days / 365
inventory = cogs * inventory_days / 365
ap = cogs * ap_days / 365

# 세후 영업이익 + CAPEX
nopat = ebit * (1 - tax_rate)
capex = revenue * capex_per_revenue

# 자유현금흐름 + 잔여가치 + IRR
fcf = nopat + depreciation - capex - delta_wc
terminal_value = ebit[exit_year] * exit_multiple
exit_valuation = if(path == 'ipo', terminal_value, terminal_value * 0.85)  # M&A discount
axe_proceeds = exit_valuation * ownership_pct_fd
```

### Topological evaluator

Rust `petgraph::algo::toposort`:

1. DAG 구성: `(driver_code) -[depends_on]-> (driver_code)` edge
2. cycle detect — `toposort` 가 cycle 감지 시 fail-fast (운영자에게 명시적 오류)
3. period 별 evaluation:
   - p=0: input driver value 읽기 (driver_value 테이블)
   - p=1..horizon: derived driver 를 toposort 순서로 평가
   - `lag(driver, n)` 는 p-n 의 cached value 조회
4. scenario 별 4 단계 반복 (base / upside / mgmt / downside)
5. 결과 → `financial_output` row insert (output_code = irr / moic / npv / exit_valuation / etc)
6. `inputs_hash` = sha256(serialized driver_value snapshot) — 같은 input 으로 다시 돌리면 같은 hash + 같은 output

### Reproducibility lock

```
compute_outputs(model_id=X, scenario_id=Y) 호출
  ↓ driver_value snapshot 읽기 → sha256
  ↓ financial_output 의 (model, scenario, output_code) 마다 inputs_hash 비교
  ↓ 같으면 skip (이미 계산됨), 다르면 재산출 + inputs_hash update
```

→ ic skill 의 `tests/fixtures/{DEAL}.json` (lockfile baseline) 패턴 완성. PR 머지 전 fixture diff 자동 검출.

## xlsx round-trip

### ingest (xlsx → DB)

`ingest_financial_model_xlsx(deal_id, xlsx_blob, hint?)` MCP tool. LLM 보조 driver tree extract:

```
1. xlsx 의 sheet 목록 + cell range 파싱 (Rust `calamine`)
2. LLM prompt (Anthropic Sonnet, 1 call ~ 60s):
   "Sheet 'Base' 의 row 'Revenue', 'COGS', 'Gross Profit', ...
    의 cell B14:H14 가 무엇의 어떤 시계열을 표현하는지 추정.
    Schema = financial_driver row 예시 [...]."
3. LLM 응답 → 제안 financial_driver rows + dependencies
4. ctx review queue 에 propose (사용자 confirm/edit/reject)
5. confirmed → financial_driver + financial_driver_value 적재
6. exit_matrix yaml 은 직접 파싱 (LLM 불필요) — schema 정형
7. scenario_deltas yaml 도 직접 (driver value override 만)
8. xlsx 의 IRR cell 과 DB compute_outputs 결과 비교 → ±1pp diff 시 warn
```

vision-heavy 시점만 API direct ([D-bp-artifact-7](/ops/decisions) layer 1 정합). 일상 propose 는 Claude Code OAuth (Max plan).

### export (DB → xlsx)

`export_xlsx(model_id, scenarios[])`. driver tree → xlsx sheet 재생성:

```
1. 시나리오마다 한 sheet (Base / Upside / Mgmt / Downside)
2. row = driver (display_order 순), column = period (y0..y_n)
3. cell value = financial_driver_value.value (input) 또는 evaluator 산출 (derived)
4. derived cell 은 xlsx formula 도 출력 ('=B14*(1+B$3)') — 사용자가 xlsx 안에서 trace 가능
5. exit_matrix → 별 sheet (scenario × timing × path 표)
6. financial_output (IRR / MOIC / NPV) → Output sheet
```

ic skill 의 기존 `ic/finance/3fs_base/v8.xlsx` 와 cell-by-cell 비교 가능 — Phase 0 acceptance test.

## Sanity check 흡수

ic skill 의 4 check 가 index 의 DB CHECK + trigger + `validate_financial_model` tool 로 이전:

| ic skill check | index 측 대응 |
|---|---|
| `xlsx_integrity.py` (5 assertion: BS/CF formula coverage, IS Y-o-Y, Retained Earnings flow, Driver range sanity, cross-scenario shape) | trigger `validate_driver_tree` — DAG cycle / orphan driver / dependency 누락 검출. cross-scenario shape = scenario × driver_code coverage matrix 검사 |
| `check_arithmetic.py` (paragraph self-claim 산수 검증) | memo artifact propose 시 numeric claim 추출 → financial_output cell 비교. `validate_memo_arithmetic(memo_artifact_id, model_id)` tool |
| `check_exit_matrix.py` (dead leaf / concentration / downside semantic / WD recovery 0%) | trigger `exit_matrix_sanity` — INSERT/UPDATE 시 자동 검사. dead_leaf / concentration flag 자동 set |
| `citation_trace.py` (memo 의 단위 동반 숫자 trace) | artifact citation 의 `kind: "index.financial_output"` 가 강제. trace 안 되는 숫자 = orphan citation warning |

ic skill 의 4 Python script 가 index Phase 1 후 deprecate — DB-side enforcement 가 더 결정론적.

## 3 deal worked example (실 데이터 기반)

### Iippo (킵코퍼레이션, iipuda)

기초 데이터: `/Users/axe/Library/CloudStorage/OneDrive-AXE/AXE - Ventures/1_Project/Prj_Iippo/ic/finance/*` (memo v8, scenario_deltas v7, exit_matrix v7).

**target_company** + **deal**:

```yaml
target_company:
  legal_name: "주식회사 킵코퍼레이션"
  brand_name: "iipuda"
  biz_no: "TBD (dataroom 06.정관_등본)"
  sector: "Medical Tourism Platform"
  founding_date: "TBD"

deal:
  deal_code: "Iippo"
  target_company: Iippo
  primary_entity_id: "axe_ia_001"        # 1호가 리드 (블라인드 펀드)
  stage: "Closed"                         # 2026-05-06 IC v8 통과
  owner_email: "ai@axellc.com"
```

**fund_investment** — Iippo 의 1:N split (D-index-5 의 핵심 검증 케이스):

```yaml
fund_investments:
  - fund_entity_id: "axe_ia_001"
    round_label: "Pre-A RCPS 1호 v9.0"
    instrument: "RCPS"
    committed_krw: 99998912                    # 16,832주 × 5,941원
    share_count: 16832
    price_per_share: 5941
    entry_date: "2026-04-30"                    # v9.0 sign-off APPROVED
    paid_date: "2026-05-15"
    pre_money_krw: 6000000000                   # 60억
    post_money_krw: 6200000000                  # 62억
    ownership_pct_post: 0.016130                # 1호 단독 1.613% (1호 + 2호 = 3.226%)
    ownership_pct_fd: 0.010325                  # F/D 1.0325% (희석 0.64x 후)
    status: "paid"
    conditions: []                              # 무조건 GO
    evidence_citations:
      - kind: onedrive
        path: "dataroom/07.리드투자_서류준비/RCPS_v9.0/"

  - fund_entity_id: "axe_ia_002"
    round_label: "Pre-A RCPS 2호 v6 (Conditional)"
    instrument: "RCPS"
    committed_krw: 100000000                    # 잠정 1.5-2.0억 미확정 (강태훈 IC #2)
    share_count: null                            # 협상 진행 중
    price_per_share: 5941                        # 같은 round 같은 단가
    entry_date: null                             # 협상 미완
    paid_date: null                              # 6 PCC 후
    pre_money_krw: 6000000000
    post_money_krw: 6200000000
    ownership_pct_post: 0.016129                # 1.613%
    ownership_pct_fd: 0.010325
    status: "committed"
    conditions:                                 # 6 PCC trigger
      - "PCC #3 — KPI 정합성 + AXEV 소개 병원 status"
      - "PCC #4 — 앤틀러 RCPS amend + Michael Lin SAFE amend"
      - "PCC #5 — 이사회 관찰권 + Pro-rata 명시"
      - "PCC #6 — Q4 anti-dilution 법무 검토"
      - "운영 신호 — 샤오홍슈 캠페인 + Q1-Q2 2026 경영성과"
      - "품질 KPI — iipuda Guide 인증 dashboard 가동"
    evidence_citations:
      - kind: onedrive
        path: "ic/memo/v8.md#1.1.5"
```

**financial_model** (v7 base 기준):

```yaml
financial_model:
  deal_code: "Iippo"
  version: 7
  name: "Iippo IC v7 base model"
  time_axis_kind: "year"
  start_period: "2025-01-01"                    # Y0 = 2025 가결산
  horizon_periods: 7                            # Y0 ~ Y7 (2025~2032)
  currency: "KRW"
  unit_scale: 1
  base_revenue_period0: 120000000               # 1.20억 = 2025 가결산
  source_xlsx_citation:
    kind: onedrive
    path: "Prj_Iippo/ic/finance/3fs_base/v7.xlsx"
```

**financial_scenario** (4종):

```yaml
financial_scenarios:
  - code: base
    name: "AXE Base"
    kind: base
    probability: 0.50
    description: "AXE 보수화 — 회사 IR 8개월 200병원 시뮬레이션을 시장 ramp 평균 (월 +5병원) 으로 할인"
    driver_changes:
      story: "병원 ramp 월 +5, Y3 매출 34.6억, 2030 EBITDA 38억 × EV/EBITDA 12x = 456억 EV"
      key_assumption_overrides:
        hospital_ramp: "월 +5병원 (vs Mgmt 월 +25)"
        china_share: "60% 유지, 다변화 Y3 부터"
        exit_multiple: "EV/EBITDA 12x"

  - code: mgmt
    name: "Mgmt Case"
    kind: mgmt
    probability: 0.10
    description: "회사 IR 가정 그대로 lift"
    driver_changes:
      story: "Y1 200병원/14.75억, Y5 275억, 회사 주장 2030 EV 2조"

  - code: upside
    name: "Upside"
    kind: upside
    probability: 0.30                            # base 보다 약간 낮음
    driver_changes:
      story: "닥터스클럽 leverage 폭발 + 일본/대만 가속 + M&A premium 18x"

  - code: downside
    name: "Downside"
    kind: downside
    probability: 0.10
    driver_changes:
      story: "Y3 매출 stall + 중국 의존 충격"
```

**financial_driver** (15 driver — scenario_deltas yaml 정합):

```yaml
financial_drivers:
  - code: revenue_growth_y1
    kind: input
    units: multiple
    category: revenue
    description: "Y1 매출 성장 multiplier (revenue[y1] / revenue[y0])"
  - code: revenue_growth_y2
    kind: input
    units: multiple
    category: revenue
  - code: revenue_growth_y3
    kind: input
    # ... y4, y5, y6, y7
  - code: gross_margin_terminal
    kind: input
    units: percent
    category: cost
  - code: opex_sm_per_revenue
    kind: input
    units: percent
    category: opex
  - code: opex_rnd_per_revenue
    kind: input
  - code: opex_ga_per_revenue
    kind: input
  - code: ar_days
    kind: input
    units: count
    category: wc
  - code: inventory_days
    kind: input
  - code: ap_days
    kind: input
  - code: capex_per_revenue
    kind: input
    units: percent
    category: capex
  - code: depreciation_years
    kind: input
    units: count
  - code: tax_rate
    kind: input
    units: percent

  # Derived
  - code: revenue
    kind: derived
    formula: "lag(revenue, 1) * (1 + revenue_growth_y[period])"
    dependencies: ["revenue", "revenue_growth_y1", ..., "revenue_growth_y7"]
    units: KRW
    category: revenue
  - code: ebit
    kind: derived
    formula: "revenue * gross_margin_terminal - revenue * (opex_sm_per_revenue + opex_rnd_per_revenue + opex_ga_per_revenue)"
    dependencies: ["revenue", "gross_margin_terminal", "opex_sm_per_revenue", "opex_rnd_per_revenue", "opex_ga_per_revenue"]
    units: KRW
    category: revenue
  # ... 추가 derived (fcf / nopat / exit_valuation / axe_proceeds)
```

**financial_driver_value** (base scenario 일부):

```yaml
financial_driver_values:
  # base scenario
  - { scenario: base, driver: revenue_growth_y1, period: 1, value: 6.5 }      # Y1 = 7.8억 (Y0 × 6.5)
  - { scenario: base, driver: revenue_growth_y2, period: 2, value: 2.4 }      # Y2 = 18.7억
  - { scenario: base, driver: revenue_growth_y3, period: 3, value: 1.85 }     # Y3 = 34.6억
  - { scenario: base, driver: revenue_growth_y4, period: 4, value: 1.55 }
  - { scenario: base, driver: revenue_growth_y5, period: 5, value: 1.40 }     # Y5 = 75억
  - { scenario: base, driver: revenue_growth_y6, period: 6, value: 1.30 }
  - { scenario: base, driver: revenue_growth_y7, period: 7, value: 1.25 }
  - { scenario: base, driver: gross_margin_terminal, period: 5, value: 0.85 }
  - { scenario: base, driver: opex_sm_per_revenue, period: 5, value: 0.35 }
  - { scenario: base, driver: opex_rnd_per_revenue, period: 5, value: 0.12 }
  - { scenario: base, driver: opex_ga_per_revenue, period: 5, value: 0.20 }
  - { scenario: base, driver: ar_days, period: 5, value: 30 }
  - { scenario: base, driver: inventory_days, period: 5, value: 0 }
  - { scenario: base, driver: ap_days, period: 5, value: 30 }
  - { scenario: base, driver: capex_per_revenue, period: 5, value: 0.02 }
  - { scenario: base, driver: depreciation_years, period: 5, value: 5 }
  - { scenario: base, driver: tax_rate, period: 5, value: 0.22 }
  # ... upside / mgmt / downside override (scenario_deltas yaml 의 다른 값)
```

**exit_matrix_leaf** (Iippo base 5y 일부):

```yaml
exit_matrix_leaves:
  # base × 5y × ma
  - { scenario: base, timing: '5y', path: ma, probability: 0.55, axe_proceeds_krw: 1235000000 }
  # base × 5y × ipo
  - { scenario: base, timing: '5y', path: ipo, probability: 0.20, axe_proceeds_krw: 1000000000 }
  # base × 5y × secondary
  - { scenario: base, timing: '5y', path: secondary, probability: 0.20, axe_proceeds_krw: 600000000 }
  # base × 5y × writedown
  - { scenario: base, timing: '5y', path: writedown, probability: 0.05, recovery_rate: 0.10 }
  # ... 3y / 7y / mgmt / upside / downside 동형
```

**financial_output** (compute_outputs 산출):

```yaml
financial_outputs:
  - { scenario: base, output_code: axe_proceeds_total, value: 940000000 }     # Y5 base 회수 9.4억
  - { scenario: base, output_code: irr, value: 0.470 }                          # 47.0%
  - { scenario: base, output_code: moic, value: 4.70 }                          # 회수/투자 ≈ 4.7x

  # 확률가중 (4 scenario × probability)
  - { scenario: weighted, output_code: irr_success_only, value: 0.539 }         # 성공 IRR 53.9% (memo §1.1)
  - { scenario: weighted, output_code: irr_loss_included, value: 0.370 }        # 손실 포함 IRR 37.0%
  - { scenario: weighted, output_code: moic_loss_included, value: 14.9 }        # MoM 14.9x
```

**Per-fund IRR** (fund_investment 별):

```yaml
# financial_output 의 axe_proceeds_total = 9.4억 (base)
# 1호 ratio = 99,998,912 / 199,998,912 = 0.500003
# 2호 ratio = 100,000,000 / 199,998,912 = 0.499997
fund_investment_irrs:
  - { fund: axe_ia_001, scenario: base,
      paid_date: "2026-05-15", proceeds_at: "2030-06-30",
      cash_flow: [-99998912, +470004700],
      irr: 0.4732, moic: 4.70 }
  - { fund: axe_ia_002, scenario: base,
      paid_date: "2026-08-15",                                  # PCC 6 후 3 개월 가정
      proceeds_at: "2030-06-30",
      cash_flow: [-100000000, +469995300],
      irr: 0.4801, moic: 4.70 }                                  # 같은 회수, paid 3 개월 지연 → IRR 약간 ↑ (보유 기간 짧음)
```

### Sentry (센티넬딥액티브)

기초 데이터: `/Users/axe/Library/CloudStorage/OneDrive-AXE/AXE - Ventures/1_Project/Prj_Sentry/ic/{memo/v4.md, finance/*}`.

```yaml
target_company:
  legal_name: "주식회사 센티넬딥액티브"
  biz_no: "708-86-02988"
  sector: "AI Asset Management"
  founding_date: "2023"

deal:
  deal_code: "Sentry"
  primary_entity_id: "axe_ia_001"
  stage: "Closed"                        # 2026-05-14 v4 만장 찬성

fund_investments:
  - fund_entity_id: "axe_ia_001"
    round_label: "Pre-A Bridge RCPS"
    instrument: "RCPS"
    committed_krw: 500068750              # 4,495주 × 111,250원
    share_count: 4495
    price_per_share: 111250
    entry_date: "2026-05-06"              # 현대차 5-6 날인
    paid_date: "2026-05-08"
    pre_money_krw: 9290000000             # 92.9억
    post_money_krw: 9790000000            # 97.9억
    ownership_pct_post: 0.0473            # 4.73%
    ownership_pct_fd: 0.0446              # 4.46% F/D
    status: "paid"

  - fund_entity_id: "axe_ia_001"
    round_label: "Series A Pro-rata Option"
    instrument: "TBD"                     # 후속 라운드 시 결정
    committed_krw: 500000000              # 추가 5억 option
    status: "committed"                   # 옵션 — 6 개월 KPI 충족 시 행사
    conditions:
      - "Series A 라운드 진입 확정"
      - "후속 6개월 KPI 충족"

# financial_model (Sentry v3 기준 — 본 docs 의 worked example 은 abbreviate)
financial_model:
  version: 3
  source_xlsx_citation:
    path: "Prj_Sentry/ic/finance/3fs_base/v3.xlsx"
  scenarios:
    - { code: upside, probability: 0.19, axe_proceeds: 23600000000 }   # 236억 (5y M&A_strategic or IPO)
    - { code: base, probability: 0.49 }
    - { code: mgmt, probability: 0.05 }
    - { code: downside, probability: 0.27 }
  outputs:
    irr_success_only: 0.599                # 59.9% (memo §1.1)
    irr_loss_included: 0.414               # 41.4%
    moic_success_only: 16.8
    moic_loss_included: 13.2
```

Sentry 는 **1 deal × 1 fund × 2 round** (initial + future option) — fund_investment 2 row.

### Canopy (사이클로이드, bardream)

기초 데이터: `Prj_Canopy/ic/{memo/v5_final.md, finance/*}`.

```yaml
target_company:
  legal_name: "주식회사 사이클로이드"
  brand_name: "bardream"
  sector: "Electric Mobility Subscription"

deal:
  deal_code: "Canopy"
  primary_entity_id: "axe_ia_001"
  stage: "Closed"                        # v5 final 2026-05-15

fund_investments:
  - fund_entity_id: "axe_ia_001"
    round_label: "Initial BW (Pre-A)"
    instrument: "BW"                     # Bond with Warrants
    committed_krw: 500000000             # 5억
    entry_date: "TBD"
    paid_date: "TBD"
    pre_money_krw: 6500000000            # v4 기준 (v5 협상 anchor 80억 F/D 81.28억)
    status: "paid"

  - fund_entity_id: "axe_ia_001"
    round_label: "v5 신주 follow-on"
    instrument: "신주"
    committed_krw: 100000000             # 1억 follow (Soohun framing)
    entry_date: "2026-05-15"             # v5 final
    paid_date: "TBD"
    pre_money_krw: 8000000000            # O/S Pre 80억 (Post 100억, F/D Pre 81.28억)
    post_money_krw: 10000000000
    status: "committed"
    conditions:
      - "AXEC 자금 별도 plug (§10 CP-5)"
      - "컨소시엄 분담 시도 (부산창경 등)"

# financial_model (Canopy v1)
financial_model:
  version: 1
  source_xlsx_citation:
    path: "Prj_Canopy/ic/finance/3fs_base/v1.xlsx"
  scenarios:
    - { code: upside, probability: 0.25 }
    - { code: base, probability: 0.45 }
    - { code: downside, probability: 0.30 }
  exit_assumptions:
    fleet_year_5: 5500                   # V3 base 5,500대
    market_share: 0.30                   # 30% (서울시 PM 25만대 expansion)
    ebitda_year_5_krw: 6641000000        # 66.41억 (57.5 + 광고 element 8.91)
    exit_multiple_ev_ebitda: 12
    exit_ev_krw: 79700000000             # 797억
    exit_net_debt_krw: 30000000000       # 300억
    exit_eqv_fd_krw: 49800000000         # 498.28억
  outputs:
    # D-index-16 (2026-05-28): per-leaf methodology 통일. V5_final 정합 데이터로
    # per-leaf 가 27% 매칭 검증 완료 (Canopy 26.39%, baseline 27%, Δ=0.01).
    # 아래 anchor 산출은 deprecated — V1 → V5_final 정합 후 자동 일치.
    irr_loss_included_per_leaf: 0.27     # ⭐ IC PASS (per-leaf, D-index-16)
    hurdle_irr: 0.15
    irr_excess: 0.119                    # +11.9pp 여유
```

Canopy 는 **1 deal × 1 fund × 2 round** (다른 시점 + 다른 instrument BW → 신주).

## 3 deal cross-check 표

| 항목 | Iippo | Sentry | Canopy |
|---|---|---|---|
| Multi-fund | **2 fund** (1호+2호) ⭐ | 1 fund | 1 fund |
| Multi-round | 1 round | 2 round (initial + future option) | **2 round (initial + follow-on)** ⭐ |
| Instrument 변화 | RCPS only | RCPS → TBD (옵션) | BW → 신주 ⭐ |
| Total committed | 199,998,912원 | 500,068,750원 (+ 5억 option) | 500,000,000원 (+ 1억 follow) |
| Scenarios | 4 (base/mgmt/upside/downside) | 4 | 3 (upside/base/downside) |
| Probability base | 0.50 | 0.49 | 0.45 |
| Success IRR (per-leaf) | 53.9% | 59.9% | 44.1% (V5 정합 후) |
| IC pass IRR (loss-included, per-leaf) | **37%** ⭐ | **41%** ⭐ | **27%** ⭐ |
| Hold years | 4.17y | 5.4y | 4.67y |
| Exit multiple | EV/EBITDA 12x | PER 15x (upside) / 8x (base) | EV/EBITDA 12x |
| Key memo | v8 (2026-05-06) | v4 (2026-05-14) | v5_final (2026-05-15) |

세 deal 이 fund_investment 의 3 차원 N:M 을 모두 cover — Phase 0 acceptance fixture ([D-index-10](/ops/decisions)).

## MCP tools (financial 관련)

> **⚠ design-era 이름** — 아래 표는 D-index-4/5 설계 시 가안한 tool 명세다. served tool 의 현행 SoT 는 [/services/index § MCP 도구 카탈로그](/services/index#mcp-도구-카탈로그-27) (27개). 매핑: `ingest_financial_model_xlsx`→`import_xlsx`/`propose_artifacts_from_ingest`, `compare_drivers_across_deals`→`cross_deal_benchmark`, `export_xlsx`→`export_lp_model`/`export_lp_bundle`, `get_financial_model`→`get_deal`. IRR 은 `weighting` 인자 없이 **IRR(E[CF]) 가 유일 canonical** ([D-index-25](/ops/decisions)/[32](/ops/decisions) — `success_only`/`loss_included` weighting 폐기). `compute_full_model` (DSL evaluator) + `compute_3fs` (IS/BS/CF) 가 추가됨.

| Tool | Scope | 기능 |
|---|---|---|
| `ingest_financial_model_xlsx(deal_id, xlsx_blob, hint?)` | write | LLM 보조 driver tree extract → propose financial_model + drivers + values |
| `propose_financial_model(deal_id, drivers, scenarios, values, exit_matrix)` | write | DB 직접 (xlsx 없이) |
| `update_driver(model_id, code, formula?, dependencies?, units?)` | write | unlocked 만 |
| `update_driver_value(model_id, driver_code, scenario_id, period_index, value)` | write | unlocked 만 |
| `create_scenario(model_id, code, name, kind, probability, driver_changes, overrides{})` | write | parent_scenario fork chain |
| `compute_outputs(model_id, scenario_id?)` | write | topo evaluator 실행 → output row 적재. inputs_hash 비교 |
| `get_financial_model(model_id, include_drivers?, include_values?)` | read | model + components |
| `list_scenarios(model_id)` | read | scenario 4종 + probability |
| `query_driver_series(deal_id, driver_code, periods[], scenarios[])` | read | cross-deal driver benchmark — 본 서비스 핵심 query |
| `query_irr(deal_id, fund_investment_id?, weighting='success_only'|'loss_included')` | read | 확률가중 IRR 한 줄 답 |
| `compare_drivers_across_deals(driver_code, deal_ids[], scenarios[])` | read | cross-portfolio benchmark |
| `lock_financial_model(model_id)` | approve | immutable 전환 + locked_at set |
| `export_xlsx(model_id, scenario_ids[])` | read | round-trip 재생성 |
| `validate_financial_model(model_id)` | read | ic skill 의 4 check 통합 결과 |

## Phase 0 Acceptance Bar

[D-index-10](/ops/decisions) 의 검증 fixture:

| Test | 조건 |
|---|---|
| **A1** | 3 deal seed yaml → index DB ingest 성공 (target_company + deal + fund_investment + financial_model + financial_driver + financial_scenario + financial_driver_value + exit_matrix_leaf 모두 적재) |
| **A2** | `compute_outputs(iippo_model_id, base_scenario_id)` 결과의 `axe_proceeds_total` 가 ic skill 의 `irr_analysis/v7.xlsx` cell J42 와 ±1% 일치 |
| **A3** | `query_irr(iippo_deal_id, fund_investment_id=axe_ia_001, weighting='success_only')` = 53.9% ±0.5pp |
| **A4** | `query_irr(iippo_deal_id, fund_investment_id=axe_ia_002, weighting='success_only')` 가 1호 IRR 과 다름 (paid_date 지연 반영) |
| **A5** | `compare_drivers_across_deals('gross_margin_terminal', [iippo, sentry, canopy], ['base'])` 가 3 row 반환 |
| **A6** | `export_xlsx(iippo_model_id, [base_scenario_id])` 결과 xlsx 가 원본 `3fs_base/v7.xlsx` 와 ±0 driver cell diff |
| **A7** | `validate_financial_model(iippo_model_id)` 4 check 모두 PASS (또는 ic skill 의 기존 warning 과 100% 일치) |
| **A8** | Blueprint artifact 의 IC memo citation = `{ kind: "index.financial_output", model_id, scenario_id: "base", output_code: "irr" }` resolve 시 0.470 반환 |

8 test 통과 시 Phase 0 완료.

## 관련 페이지

- [/services/index](/services/index) — 서비스 main
- [/services/index/schema-catalog](/services/index/schema-catalog) — 14 schema 상세 spec
- [/services/index/skill-evolution](/services/index/skill-evolution) — `--push-to-index` flow + ic skill 진화
- [/services/index/skill-integration](/services/index/skill-integration) — 3 skill 통합 아키텍처 + atomic propose + idempotency + 3-layer error model
- [/ops/decisions D-index-4](/ops/decisions) — financial_model 6-table 결정
- [/ops/decisions D-index-5](/ops/decisions) — fund_investment N:M 결정
- [/ops/decisions D-index-10](/ops/decisions) — 3 deal Phase 0 fixture
- [/ops/roadmap M7](/ops/roadmap#m7--index-투자-도메인-backend) — 3 Phase 구조

---

<!-- PAGE https://docs.axelabs.ai/services/index/schema-catalog -->

# Schema 카탈로그

> GET /index/schemas 가 노출하는 typed-fact 계약. 15 active (10 relational base + 5 judgment) + 6 phase-1 stub. frozen_enums_hash 로 contract 고정 (SCHEMA_CONTRACT_DRIFT gate). Blueprint artifact citation 의 index.* kind authority.

URL: https://docs.axelabs.ai/services/index/schema-catalog

# Schema 카탈로그

## 한 줄 정의

index 가 자기 도메인에서 생산하는 typed-fact kind 의 SoT. `GET /index/schemas` endpoint 가 단일 envelope 으로 노출 — 이것이 schema 의 유일한 출처 (외부 schema registry 없음, MCP 가 권위). 같은 envelope 이 `mcp_schema` 테이블에도 mirror 되며 (`index register-schemas`), live 집계는 [현황 페이지](https://axe.axelabs.ai/index) 의 "스키마 계약" 섹션에서 확인.

코드 SoT = `src/mcp.rs` (Rust) 의 `schemas_envelope_base()` 리터럴 (relational base) + `judgment_schema_defs()` (judgment). 두 곳이 served `/index/schemas` 와 `mcp_schema` 레지스트리의 single source.

## 현재 카운트 (2026-06, live)

| 구분 | 수 | 비고 |
|---|---|---|
| **active** | **15** | 10 relational base + 5 judgment (D-index-45/49). `mcp_schema` 에 등록됨 |
| **phase-1 stub** | 6 | `status: phase1_backlog`, `version: 0.1-stub` — body 없는 roadmap placeholder. 레지스트리 미등록 |
| **total (envelope)** | 20 | served `/index/schemas` 의 `schemas[]` 길이 |

stub 이 `active` 로 graduate (real body + `N.0` version 획득) 하면 `register-schemas` 가 코드 변경 없이 자동 등록.

## Envelope 형식

```bash
curl -H "Authorization: Bearer $INDEX_MCP_TOKEN" \
  https://axe.axelabs.ai/index/schemas
```

응답 (요약):

```jsonc
{
  "version": "1.0",
  "service": "index",
  "schemas": [
    {
      "name": "index.deal",
      "version": "1.0",
      "status": "active",
      "description": "...",
      "fields": { "deal_code": { "type": "string", "required": true }, "...": "..." }
    }
    // ... 14 active + 6 stub
  ],
  "metadata": {
    "active_count": 14,
    "total_count": 20,
    "frozen_enums": { "instrument": [...], "path": [...], "scrub_kind": [...], "...": "..." },
    "frozen_enums_hash": "3b58b4b0...11f57f"
  }
}
```

- 인증: required (Bearer, Entra ID RS256)
- versioning: 각 body 의 `version` 필드. 표시는 string ("1.0"), `mcp_schema.version` PK 는 integer major ("1.0" → 1)
- envelope `version`: 응답 모양 변경 시에만 bump

## 14 active schemas

### A. Relational base (10) — financial_model 6-table + deal pipeline

deal 의 relational compute substrate. `propose_deal_closure` 가 atomic 으로 적재, `get_deal` / `get_exit_matrix` / `compute_outputs` / `query_irr` 가 읽음. 상세 = [financial-model](/services/index/financial-model).

#### 1. `index.target_company` (v1.0)

| field | type | notes |
|---|---|---|
| `legal_name` | string · required | 한글 정식 상호 |
| `brand_name` | string | 영문/한글 브랜드명 |
| `biz_no` | string | 사업자등록번호 `^\d{3}-\d{2}-\d{5}$` |
| `sector` | string | sector_framework code 참조 |
| `founding_date` | date | |
| `founders` | array | |
| `website` | uri | |

생성/읽기: `propose_deal_closure` · `get_deal`.

#### 2. `index.deal` (v1.0)

deal_code 가 stable identifier — UUIDv5 idempotency key 의 namespace.

| field | type | notes |
|---|---|---|
| `deal_code` | string · required | stable UI ID (예: Iippo / Sentry / Canopy) |
| `target_company_id` | uuid · required | |
| `stage` | enum | Pre-A · Series A · Series B · Series C · Bridge · Exit |

#### 3. `index.fund_investment` (v1.0)

deal × fund_entity × round 의 3-axis N:M ([D-index-5](/ops/decisions)). 1호 + 2호 동시 투자 시 각각 IRR 독립 산출. 상세 = [financial-model § fund_investment](/services/index/financial-model#fund_investment).

| field | type | notes |
|---|---|---|
| `deal_id` | uuid · required | |
| `fund_entity_id` | string · required | axe_ia_001 / axe_ia_002 등 |
| `round_label` | string · required | |
| `instrument` | enum · **frozen** | RCPS · BW · SAFE · 신주 · 보통주 ([D-index-15](/ops/decisions)) |
| `committed_krw` | number · required | |
| `invested_krw` | number · nullable | |
| `paid_date` | date · nullable | |
| `status` | enum · **frozen** | committed · paid · locked_in · written_off · partial_exited · exited |

#### 4. `index.financial_model` (v1.0)

6-table SoT 의 root (per-deal). `version` + `locked_at` + `source_xlsx_sha256` 가 immutable provenance.

| field | type | notes |
|---|---|---|
| `deal_id` | uuid · required | |
| `version` | integer · required | v(N) per ic skill |
| `time_axis_kind` | enum | annual · quarterly · monthly |
| `start_period` | date · required | |
| `horizon_periods` | integer · required | |
| `currency` | string | default KRW |
| `source_xlsx_sha256` | string · nullable | round-trip integrity |

#### 5. `index.financial_driver` (v1.0)

driver = formula DSL atom. DSL grammar = 10 operator (`+ - * / min max if sum avg lag growth`) — [D-index-15](/ops/decisions) immutable. 문법 = [financial-model § DSL](/services/index/financial-model#dsl-formula).

| field | type | notes |
|---|---|---|
| `code` | string · required | snake_case (예: gross_margin_terminal) |
| `kind` | enum · **frozen** | input · derived · output |
| `formula` | string · nullable | DSL — derived 만 required |
| `dependencies` | array | self-lag (`revenue[y-1]`) 는 cycle 미간주 |
| `units` | string | KRW · percent · multiple |
| `category` | string | revenue · cost · opex · capex · financing |

#### 6. `index.financial_scenario` (v1.0)

scenario = (base · mgmt · upside · downside) × probability. Σ probability = 1.0 ±0.02.

| field | type | notes |
|---|---|---|
| `code` | string · required | base · mgmt · upside · downside · custom |
| `kind` | enum | base · mgmt · upside · downside · stress |
| `probability` | number · required | 0~1, Σ = 1.0 |
| `name` · `description` | string | |

#### 7. `index.exit_matrix_leaf` (v1.0)

scenario × timing × path 의 joint probability leaf. 읽기 = `get_exit_matrix`.

| field | type | notes |
|---|---|---|
| `scenario_id` | uuid · required | |
| `timing` | string · required | 3y · 5y · 7y · never |
| `path` | enum · **frozen** | ma · ma_strategic · ipo · secondary · writedown · partial |
| `probability` | number · required | within-scenario, Σ = 1.0 |
| `axe_proceeds_krw` | number · nullable | fund_share proceeds |
| `recovery_rate` | number · nullable | writedown fallback |

#### 8. `index.financial_output` (v1.0)

`compute_outputs` / `query_irr` 의 결과. **Blueprint IC memo 가 가장 자주 cite** ("IRR" 의 출처).

| field | type | notes |
|---|---|---|
| `deal_code` | string · required | |
| `model_id` | uuid · required | |
| `irr_expected_cashflow` | number | **IRR(E[CF]) — 유일 canonical IRR** ([D-index-25](/ops/decisions)/[32](/ops/decisions); Σp·IRR 폐기) |
| `expected_moic` | number | E[MoM] |
| `prob_loss` | number | `P(MoM<1)` |
| `success_probability` | number | |
| `methodology` | string | default "IRR(E[CF]) canonical" |

#### 9. `index.financial_statement_line` (v1.0)

`compute_3fs` 의 IS/BS/CF typed line items (gross_profit / opex_total / ebit / pretax_income / tax_expense / net_income). Phase 0 = IS focus, BS/CF placeholder.

#### 10. `index.skill_resource` (v1.0)

`list_skills` / `get_skill_resource` 가 노출하는 skill resource fact (skill identifier + 파일 path + sha256). owner:index skill 의 read-path schema ([D-index-47](/ops/decisions) — skill ownership 의 byte 식별). MCP byte-delivery 가 아니라 식별/감사용 (실 분배는 mirror, [skill-ownership](/services/index/skill-ownership)).

---

### B. Judgment layer (4) — artifact-first ([D-index-45](/ops/decisions))

relational 값을 **지배하는 판단**을 typed fact 로 적재. SoT = `seed.yaml` 의 `judgment:` block + `seeds/_corpus.yaml` → `seed-ingest --emit-judgment` 로 파생 ([D-index-46](/ops/decisions) — hardcoded backfill 폐기). lifecycle propose→confirm, RLS owner_only, append-only `artifact_event`. 읽기 = `get_judgment_provenance` · `list_calibrations`. 현재 357 artifact / 23 deal (live 집계 = [현황](https://axe.axelabs.ai/index)).

> **링크는 일급 citation 이지 컬럼이 아님.** judgment artifact 는 두 종류의 citation 으로 연결된다:
> - `index_field` — relational field 로의 링크. ref = `{deal,field}` (예: `scenario:base:exit_multiple`)
> - `artifact_ref` — fact↔fact 링크. ref = `{artifact_id,relation}`, relation ∈ `calibrated_from` · `scrubbed_from` · `anchored_to` · `contradicts` (**frozen**)

#### 11. `index.assumption` (v1)

한 relational `field_ref` 를 지배하는 입력/파라미터 판단.

| field | type | notes |
|---|---|---|
| `field_ref` | string · required | relational target (예: `scenario:base:exit_multiple` · `output:irr_expected_cashflow` · `leaf:downside:axe_proceeds` · `scenario:downside:probability`) |
| `scope` | string · required | base · downside · weighted · deal-wide |
| `value` | number\|string · required | |
| `units` | string | multiple · percent · KRW · ratio |
| `rationale` | string · required | 왜 이 값인가 |
| `decision_ref` | string | D-index-N 참조 (optional) |

#### 12. `index.calibration` (v1)

SURFACE→CALIBRATED scrub ([D-index-24](/ops/decisions)/[26](/ops/decisions) 핵심). surface_value (deck/사업계획) 를 calibrated_value (research-calibrated) 로 조정한 판단.

| field | type | notes |
|---|---|---|
| `metric` | string · required | 조정 대상 (예: exit_multiple · revenue_ramp · downside_recovery) |
| `surface_value` | number\|string · required | 조정 전 표면값 (deck claim) |
| `calibrated_value` | number\|string · required | 채택값 |
| `scrub_kind` | enum · **frozen** | 7종 (아래 frozen-enum 표) |
| `scrub_reason` | string · required | |
| `decision_ref` | string · required | calibration 은 결정 추적 필수 |

artifact_ref `scrubbed_from`/`anchored_to` 로 comp/base_rate 에 링크, index_field 로 대상 relational field 에 링크.

#### 13. `index.comp` (v1)

Comparable — 한 지표의 비교가능 밴드. calibration 이 `artifact_ref(anchored_to)` 로 참조해 `multiple_anchor`/`fat_tail_comp_scrub` 을 정당화.

| field | type | notes |
|---|---|---|
| `name` | string · required | 예: commodity supplement exit multiple |
| `metric` | string · required | 예: ev_rev_multiple · psr · gross_margin |
| `value_low` | number · required | |
| `value_high` | number · required | |
| `sector` | string | |
| `source` | string · required | research 문서 / 시장 데이터 |

#### 14. `index.base_rate` (v1)

Base rate — 시나리오/wipeout 확률 산정 기준율 (예: 식품 5년 생존율 0.34). calibration / `scenario:*:probability` assumption 이 `artifact_ref(anchored_to)` 로 참조.

| field | type | notes |
|---|---|---|
| `name` | string · required | 예: food startup 5y survival |
| `value` | number · required | 0~1 비율 |
| `scope` | string · required | 예: genuine_wipeout · downside |
| `source` | string · required | |

#### 15. `index.deal_judgment` (v1)

**Dead-deal harvest** ([D-index-49](/ops/decisions)) — 한 deal 의 thesis-level **처분 JUDGMENT** ("왜 passed/lost/died" + durable lesson). claim(source-cited·live·갱신)과 달리 **author·불변·supersede** (재판단 = 새 artifact 가 prior 를 `artifact_ref(supersedes)`). `index_field{deal,"deal:disposition"}` 로 relational deal 에, `artifact_ref(anchored_to)` 로 backing comp/base_rate 에 링크. 읽기 = `query_dispositions`(verdict/sector/tag 횡단) · `get_deal_judgment`. seed `judgment.verdict:` block = SoT → `seed-ingest --emit-judgment` 파생.

| field | type | notes |
|---|---|---|
| `deal_code` | string · required | = para_anchor |
| `verdict` | enum · required · **frozen** | passed · lost · dead · invested · missed |
| `thesis` | string · required | one-line thesis-level 판단 (예: good company ≠ good deal) |
| `rationale` | array | 구체 사유 bullet |
| `lesson` | string · required | durable·재사용 lesson (예: field DD kills thesis) |
| `sector` | string · required | cross-deal rollup 용 (Pillar B sector Resource harvest 대상) |
| `tags` | array | open 패턴 vocabulary (예: good-company-not-good-deal · high-irr-not-go) |
| `decided_by` / `decided_at` | string | author stamp (누가 / 언제) |

## frozen-enum 계약 + `frozen_enums_hash` ([D-index-47](/ops/decisions) P1)

enum 값은 service code 에만 존재 — skill/producer 측에서 override 불가. 전체 frozen-enum set 의 deterministic sha256 = `frozen_enums_hash`, envelope `metadata` 에 publish. 현재 live:

```
frozen_enums_hash = 7895afeb4a135f38fb96e4dde239fc3981c790076ae7f7f638dc37d363132daa
```

envelope `metadata.frozen_enums` 의 키 (live):

| 키 | 값 |
|---|---|
| `instrument` | RCPS · BW · SAFE · 신주 · 보통주 |
| `path` (exit) | ma · ma_strategic · ipo · secondary · writedown · partial |
| `status` (fund_investment) | committed · paid · locked_in · written_off · partial_exited · exited |
| `statement` | (financial_statement_line statement code) |
| `is_line_code` | (income-statement line code) |
| `risk_kind` | (risk_alert stub kind) |
| `scrub_kind` | fat_tail_comp_scrub · genuine_wipeout · par_entry · dilution · over_pessimism_floor · ramp_haircut · multiple_anchor |
| `artifact_ref_relation` | calibrated_from · scrubbed_from · anchored_to · contradicts · supersedes |
| `verdict` (deal_judgment) | passed · lost · dead · invested · missed ([D-index-49](/ops/decisions)) |

### SCHEMA_CONTRACT_DRIFT gate

외부 propose caller (예: ic-push 경유 `propose_artifacts_from_ingest`) 는 마지막으로 본 `frozen_enums_hash` 를 `expected_frozen_enums_hash` 로 pin 할 수 있다. index live hash 와 불일치하면 propose 가 거부된다:

```jsonc
{ "error_code": "SCHEMA_CONTRACT_DRIFT", "message": "...(stale skill/contract — refresh against /index/schemas)" }
```

생략 시 게이트 비활성. propose 가 성공하면 `artifact_event.payload_after._provenance` 에 `skill` · `bundle_sha256` · `frozen_enums_hash` · `actor` · `surface` 가 stamp 된다 (P1 provenance). 상세 = [skill-ownership § P1](/services/index/skill-ownership).

## 6 phase-1 stubs (`status: phase1_backlog`)

body (`fields`) 없는 roadmap placeholder. `mcp_schema` 미등록 — graduate 시 자동 등록.

| stub | 예정 owner | 비고 |
|---|---|---|
| `index.dd_finding` | due-diligence skill | M7 후 |
| `index.ic_decision` | ic skill (`--push`) | atomic propose_deal_closure 흡수 vs 별도 propose 검토 |
| `index.portfolio_kpi` | pmc skill | quarterly_close 시 propose |
| `index.risk_alert` | pmc skill | red/yellow 조기 경보 |
| `index.valuation` | pmc skill | NAV / unrealized / realized |
| `index.lp_comm` | pmc skill | LP 보고 audit |

→ 이 6 stub 은 schema-catalog 의 미래 영역. 현행은 위 14 active 가 권위.

## Citation kinds (evidence)

artifact 의 evidence 는 typed citation. judgment-layer 의 일급 링크 (`index_field` · `artifact_ref`) 외에, extracted-fact 의 source 앵커:

| citation kind | ref 모양 | 의미 |
|---|---|---|
| `index_field` | `{deal,field}` | relational field 로의 judgment 링크 |
| `artifact_ref` | `{artifact_id,relation}` | fact↔fact 링크 (relation frozen 4종) |
| `xlsx_cell` | `{source_file,sheet,cell, sha256?}` | xlsx key_output 앵커 |
| `pdf_figure` | `{source_file,page, sha256?}` | pdf figure 앵커 |

### Evidence durability (sha256 content-anchor)

`xlsx_cell` / `pdf_figure` 의 ref 는 sha256 (cited 파일 bytes 의 hash) 를 PRIMARY 앵커로 carry — 파일이 이동·개명·삭제돼도 살아남는다. 추가 앵커: `drive_item_id` (OneDrive move-survivor) · `workspace_id` + `rel_path` · `marker`.

DURABLE := ref 에 non-null `sha256` OR `drive_item_id` OR (`workspace_id` AND `rel_path`). 아니면 FRAGILE (path-only). `verify_citations` 도구가 owner 의 citation 을 durable/fragile 로 집계 (현황 페이지에 durable% 노출). 상세 = evidence-durability v1, [/services/index § evidence-durability](/services/index#evidence-durability).

## Blueprint citation kind `index.*`

Blueprint artifact citation 의 `index.*` kind ([D-bp-artifact-3](/ops/decisions) 6 kind 에 7번째). IC memo 의 IRR 한 줄이 index 의 typed field 를 가리킴:

```jsonc
{
  "field": "irr_expected_cashflow",
  "citations": [{
    "kind": "index.financial_output",
    "deal_code": "Iippo",
    "model_id": "uuid-iippo-v8",
    "scenario_code": "weighted",
    "output_code": "irr_expected_cashflow"
  }]
}
```

Blueprint resolver 가 stable ID 로 실 value 를 fetch (`query_irr` MCP 호출) + cache. 상세 = [/architecture/artifacts § Citation 형태](/architecture/artifacts#citation-형태).

## Migration SQL

```
/Users/axe/index/migrations/
├── ..._shared_schema.sql       — entity / target_company / deal / fund_investment / sector_framework
├── ..._artifact_core.sql       — artifact / citation / artifact_event / mcp_schema (cortex 1:1 mirror)
├── ..._per_entity_template.sql — financial_model 6-table
├── ..._rls.sql                 — index_app role + FORCE RLS (owner_only)
├── ..._triggers.sql            — artifact_event audit + validate_driver_tree + exit_matrix_sanity
└── ..._judgment.sql            — judgment artifact kinds (D-index-45)
```

상세 = `/Users/axe/index/migrations/`.

## 관련 페이지

- [/services/index](/services/index) — 서비스 main (3-layer 모델 + MCP 도구 카탈로그)
- [/services/index/financial-model](/services/index/financial-model) — 6-table SoT 상세
- [현황 페이지](https://axe.axelabs.ai/index) — live 집계 (schema 수 · artifact · frozen_enums_hash)
- [/architecture/artifacts](/architecture/artifacts) — citation kind 7번째 등재
- [/ops/decisions D-index-45](/ops/decisions) — artifact-first judgment layer
- [/ops/decisions D-index-46](/ops/decisions) — seed=SoT (judgment 파생)
- [/ops/decisions D-index-47](/ops/decisions) — provenance + drift gate + skill ownership

---

<!-- PAGE https://docs.axelabs.ai/services/index/skill-evolution -->

# 5 skill 진화 경로

> ic / due-diligence / vc-deal-sourcing / portfolio-management / investor-relations 5 skill 의 service 진화 경로 + --push-to-index flow + 호환 보존.

URL: https://docs.axelabs.ai/services/index/skill-evolution

# 5 skill → index service 진화 경로

> **⚠ 부분 SUPERSEDED (2026-06, [D-index-45](/ops/decisions)/[46](/ops/decisions)/[47](/ops/decisions)).** 본 페이지는 design-era (D-index-1~10 시기) 의 진화 계획이다. **핵심 원칙 (skill = workflow, index = persistence) 은 유효**하나, 아래 구체 mechanism 중 다음은 실구현에서 달라졌다:
>
> - **per-tool propose 이름** (`record_fund_investment` · `propose_dd_finding` · `record_ic_decision` · `record_kpi_snapshot` 등) → 실제는 **atomic [`propose_deal_closure`](/services/index/schema-catalog)** (deal+fund+model 1-tx) + **`propose_artifacts_from_ingest`** (dataroom sidecar → artifact, `_provenance` stamp + drift gate). dd_finding/ic_decision/portfolio_kpi/risk_alert/valuation 은 아직 **phase-1 stub** (미적재) — [schema-catalog § stubs](/services/index/schema-catalog#6-phase-1-stubs-status-phase1_backlog).
> - **skill ownership** (ic/ingest/pmc 이전) → [D-index-47](/ops/decisions) 가 universal-base mirror + `--attest` + vertical-gate 로 **실구현·배포**. [skill-ownership](/services/index/skill-ownership) 참조.
> - **신규 본질**: relational 진화에 더해 **artifact-first judgment layer** ([D-index-45](/ops/decisions)) — 가정·calibration·comp·base_rate 를 typed fact 로 적재 (당시 계획에 없던 layer). [/services/index § judgment](/services/index#artifact-first-judgment-layer-d-index-45).
>
> 아래는 의도·맥락 기록으로 보존. 현행 사실은 위 링크.

## 핵심 원칙

**skill = workflow (LLM-heavy authoring), index = persistence (typed fact).**

skill 자체는 사라지지 않음 — IC memo 19-agent orchestration / DD 체크리스트 prompt / 포트폴리오 KPI 가이드 같은 LLM 작업 본질은 그대로. 진화하는 것은 **산출물의 보존 방식** 뿐:

```
이전 흐름:
  /ic 실행 → dataroom/ + ic/finance/ + ic/memo/ → PDF/Teams reply
    → 다음 deal 도 markdown grep + LLM 재추출 (휘발)

진화 후:
  /ic 실행 → dataroom/ + ic/finance/ + ic/memo/ → PDF/Teams reply
    + /ic --push-to-index → typed fact 부분만 index 로 propose
      → ctx review confirm → index DB 적재 (audit trail 시작)
        → 다음 deal 의 cross-deal benchmark / time-travel query / fund 별 IRR 자연
```

기존 산출물 (markdown / xlsx / yaml) 은 OneDrive 그대로 보존 — citation source 로 영구.

## 5 skill 매핑

### 1. `vc-deal-sourcing` → `index.deal` + `deal_stage_history`

| skill 현재 | service 진화 |
|---|---|
| pipeline 표 markdown 으로 관리 (Identified / Contacted / Screening / DD / IC / Closed) | `deal_stage_history` 테이블 (bitemporal — stage 진입 시점 + 빠진 시점 audit) |
| 타겟 기준 markdown (Must-Have / Nice-to-Have) | `sector_framework` artifact (RESOURCE — vc-deal-sourcing skill `references/` 정합) |
| 스코어링 5 dimension | `index.deal.attributes.scoring` JSONB (확장 가능) |
| Source channel 분류 | `index.deal.source_channel` enum |

진화 후 가능:
- "지난 6개월 referral 채널 deal 의 IC 통과율?" SQL 한 줄
- "특정 sector 의 deal pipeline 전체 + 현재 stage" cross-fund dashboard

skill 자체 변화: vc-deal-sourcing skill 의 `references/` 가 sector_framework artifact 로 점진 migration ([D-bp-artifact-5](/ops/decisions) markdown → artifact 패턴 정합).

### 2. `due-diligence` → `index.dd_finding` + citation chain

| skill 현재 | service 진화 |
|---|---|
| DD 체크리스트 markdown (재무/시장/기술/팀/법무) | `index.dd_finding` row 단위 — kind enum + severity + citation chain |
| 분석 프레임워크 (SWOT/Porter's 5/Unit Economics/Cohort) | sector_framework artifact 의 reusable RESOURCE |
| finding markdown 본문 (출처 표기 의무 X) | citation 6-kind 강제 (onedrive / index.* / external.web / ...) |

진화 후 가능:
- "지난 12개월 모든 deal 의 'team risk' severity=blocker finding" cross-deal query
- "동일 sector 의 historical DD finding pattern" archive search
- finding 한 줄마다 OneDrive PDF page citation trace 100%

skill 자체 변화: DD 체크리스트 prompt 가 `propose_dd_finding` MCP tool call 로 매핑. 사용자가 confirm 하면 typed fact 적재.

### 3. `ic` skill 18-section memo → `index.ic_decision` + `--push-to-index` mode

가장 큰 진화. ic skill 의 19-agent orchestration 은 그대로 (LLM heavy 본질 유지), **산출물의 typed fact 부분만 propose**. 구체적 mode 정의 = [D-index-11](/ops/decisions) (5th mode FINALIZE 평행 track) + [D-index-13](/ops/decisions) (atomic `propose_deal_closure` + idempotency key). 서버 측 contract = [/services/index/skill-integration § 2](/services/index/skill-integration#2-ic-skill-통합--5th-mode---push-to-index).

#### 현재 ic skill 산출

```
Prj_<DEAL>/
├── dataroom/                       (회사 자료 — READ-ONLY)
├── ic/
│   ├── research/                   (15 sub-folder)
│   ├── proponent/v{N}.md
│   ├── premortem/v{N}.md
│   ├── premortem_critic/v{N}.md
│   ├── devils/v{N}.md
│   ├── qa/v{N}.md
│   ├── finance/
│   │   ├── 3fs_{base,upside,mgmt,downside}/v{N}.xlsx
│   │   ├── scenario_deltas/v{N}.yaml
│   │   ├── exit_matrix/v{N}.yaml
│   │   ├── irr_analysis/v{N}.xlsx
│   │   └── irr_cell_ref/v{N}.xlsx
│   ├── memo/v{N}.md                (18-section)
│   ├── deliverables/v{N}.pdf
│   └── _recap/                     (postmortem stub)
└── ctx/MEMORY.md                   (session knowledge)
```

#### `--push-to-index` 모드 (신규)

ic skill 의 신규 mode (`/ic --finalize` 과 평행):

```
/ic --push-to-index
  ↓
1. `ic/finance/*.xlsx` + `ic/finance/*.yaml` → financial_model + driver/scenario/output 추출
   - `ingest_financial_model_xlsx(deal_id, ic/finance/3fs_base/v{N}.xlsx)` × 4 scenario
   - scenario_deltas.yaml 직접 파싱 → driver_value override
   - exit_matrix.yaml 직접 파싱 → exit_matrix_leaf row
2. ic/memo/v{N}.md 의 §1.4 투자 논거, §14 risk 표, §15 postmortem cadence → dd_finding / risk_alert / postmortem stub propose
3. ic/memo/v{N}.md 자체 → Blueprint artifact (memo body OneDrive citation 유지) + ic_decision row
4. ic/finance/exit_matrix/v{N}.yaml 의 meta (axe_investment, ownership_pct_fd) → fund_investment row
   (강수훈 회신/IC pack 기반 — 1호+2호 split 확인 후 row 2개)
5. 모든 propose 가 ctx review queue 경유 → 사용자 confirm/edit/reject
6. confirmed → typed fact 적재 + audit_event 'confirm' 기록
```

이 후 다음 deal 의 IC 작성 시:
- `compare_drivers_across_deals('gross_margin_terminal', portfolio_deals, ['base'])` — 시장 표준 자동 benchmark
- `query_irr(deal_id={유사 deal})` — historical IRR pattern 참조
- ic skill 의 §11 "포트폴리오 정합성" 자동 채우기

#### sanity check 흡수

ic skill 의 4 Python script (`xlsx_integrity.py` / `check_arithmetic.py` / `check_exit_matrix.py` / `citation_trace.py`) 가 index 의 `validate_financial_model` MCP tool + DB trigger 로 흡수 → Phase 1 후 deprecate.

#### 호환 보존

ic skill 자체는 (a) workspace 가 index DB 부재인 환경에서도 작동 (markdown only mode), (b) `--push-to-index` mode 는 opt-in. Phase 0 launch 후 점진 도입.

상세 = [/services/index/financial-model § ic-skill-진화](/services/index/financial-model).

### 4. `portfolio-management` → `index.portfolio_kpi` time series + `risk_alert`

| skill 현재 | service 진화 |
|---|---|
| 핵심 KPI 표 markdown (SaaS / 커머스) | `index.portfolio_kpi` row 단위 — kind enum + asof_date time series |
| 리스크 지표 (조기 경보) | `index.risk_alert` (severity red/yellow + kind enum) |
| 엑싯 시그널 체크리스트 (IPO / M&A / Secondary) | `index.exit_signal` (Phase 2) |
| 분기 board pack 정리 | `record_kpi_snapshot(deal_id, kind, value, asof_date, source_citation)` MCP tool — board pack PDF OneDrive page cite |

진화 후 가능:
- portfolio time series 자동 dashboard (Blueprint UI Phase 1+)
- "지난 12개월 portfolio 평균 churn vs sector benchmark" 한 줄 query
- runway < 6개월 deal 자동 red alert (분기 KPI 입력 시 trigger)

skill 자체 변화: portfolio-management skill 의 KPI 표가 `record_kpi_snapshot` MCP tool prompt 로 진화. 분기 BOD pack ingest 시 LLM 이 KPI 자동 추출 → ctx review.

### 5. `investor-relations` → `index.lp_comm` audit + 펀드 성과 자동

| skill 현재 | service 진화 |
|---|---|
| LP 보고 구조 markdown | `index.lp_comm` (kind / subject / sent_at / body_sha256) — hive `payslip_send_log` 패턴 |
| 펀드 성과 지표 | `index.valuation` + frame `commitment_ledger` 결합 자동 산출 |
| IR 커뮤니케이션 가이드 | sector_framework artifact (RESOURCE) |

진화 후 가능:
- "LP X 와 마지막 comm 후 변한 portfolio fact" — cross IR × Portfolio query
- 분기 NAV report 자동 (frame 의 commitment_ledger × index 의 valuation_snapshot)
- LP audit 시 모든 숫자가 DB cell trace + citation chain

skill 자체 변화: investor-relations skill 의 보고 템플릿이 `index.lp_comm` propose 와 결합 — 발송 시점에 body_sha256 자동 기록.

## ic skill 의 detailed changes

`/Users/axe/blueprint/.claude/skills/ic/SKILL.md` 의 변경 (Phase 1 PR):

### 폴더 규약 변경 ([D-index-6](/ops/decisions))

- 현재: workspace.name = deal name (Prj_Iippo / Prj_Sentry / Prj_Canopy)
- 진화: workspace 는 sector / pipeline / fund container, deal 은 deal_code tag

deal 폴더 → workspace 안의 sub-folder 로 재구성:

```
workspace_name/                      ← sector / pipeline 단위
├── deal/
│   ├── Iippo/
│   │   ├── dataroom/                ← OneDrive
│   │   ├── ic/
│   │   │   ├── finance/
│   │   │   ├── memo/v{N}.md
│   │   │   └── ...
│   │   └── ctx/                     ← deal-level
│   ├── Sentry/
│   │   └── ...
│   └── Canopy/
│       └── ...
└── ctx/MEMORY.md                    ← workspace-level (sector knowledge)
```

이미 진행 중인 deal 의 마이그레이션은 dispatch link mode ([D-bp-artifact-6](/ops/decisions)) 로 cover — 기존 workspace.name=Prj_Iippo 가 새 workspace 안의 deal/Iippo/ 로 link.

### Rule 추가

ic skill SKILL.md 에 신규 rule:

> **25. Push to index (opt-in)**: `/ic --push-to-index` 모드 활성 시, gate_memo.sh PASS 후 자동으로 (a) `ingest_financial_model_xlsx` × 4 scenario xlsx, (b) `record_fund_investment` (memo §1.3 의 fund split parse), (c) `record_ic_decision` (§17 partner verbatim 의 voting record extract), (d) `propose_dd_finding` (§14 risk 표 row 단위), (e) `record_kpi_snapshot` (§1.6 IRR + §13 financial)  를 index propose. ctx review queue 등재 후 사용자 confirm 까지 ic skill 자체는 markdown / xlsx 산출물 영구 보존 (citation source).

## propose flow 통합

5 skill 의 진화는 모두 같은 패턴:

```
skill workflow 실행 (LLM heavy)
  ↓ 산출물: markdown + xlsx + yaml (OneDrive 영구)
--push-to-index 모드 (opt-in)
  ↓ typed fact 추출 (구조화된 부분만)
ctx review queue 등재
  ↓ 사용자 confirm / edit / reject
index DB 적재 + artifact_event 'confirm'
  ↓
cross-deal query / time-travel / fund 별 IRR / portfolio benchmark 가능
```

ctx skill ([D-bp-artifact-5](/ops/decisions)) 가 모든 propose 의 curation interface — 일관된 review UX.

## 기존 markdown KB 의 점진 migration

각 deal 의 `ctx/MEMORY.md` + `project_*.md` 도 점진적으로 index typed fact 로 migration:

```
ctx/project_iippo_status.md
  ↓ LLM extract — "현재 stage / committed / risk / next milestone" 추출
proposed index.deal + index.risk_alert + index.dd_finding rows
  ↓ ctx review confirm
  ↓
ctx/project_iippo_status.md 의 해당 entry 에 archive 마커 ([D-bp-artifact-5](/ops/decisions) `migrated:` 패턴) 삽입
```

[D-bp-artifact-5](/ops/decisions) 의 점진 migration 패턴과 정합. 신규 fact 는 처음부터 index typed (markdown append 안 함).

## 관련 페이지

- [/services/index](/services/index) — 서비스 main
- [/services/index/financial-model](/services/index/financial-model) — 6-table SoT + ic skill 의 xlsx 진화
- [/services/index/schema-catalog](/services/index/schema-catalog) — 14 schema spec
- [/ops/decisions D-index-6](/ops/decisions) — Workspace ↔ deal N:1 + ic skill 폴더 진화
- [/ops/decisions D-index-8](/ops/decisions) — 5 skill 진화 + `--push-to-index` mode
- [/architecture/artifacts § Markdown → artifact 점진 migration](/architecture/artifacts#markdown--artifact-점진-migration-ai-assisted) — 일반 패턴

---

<!-- PAGE https://docs.axelabs.ai/services/index/skill-integration -->

# Skill 통합 아키텍처

> ingest / ic / pmc 3 skill 의 index 통합 설계 — 5-axis (본질·결과·퀄리티·안전·혁신) 정합. atomic propose + idempotency + 3-layer error model + cross-deal aggregate.

URL: https://docs.axelabs.ai/services/index/skill-integration

# Skill 통합 아키텍처

> **⚠ 부분 SUPERSEDED (2026-06, [D-index-45](/ops/decisions)/[46](/ops/decisions)/[47](/ops/decisions)).** design-era (D-index-11~15) 의 통합 설계다. **유효한 것**: atomic `propose_deal_closure` 1-transaction 원칙 (§2, 실구현됨) · 3-layer error model (§4) · schema authority immutable (§5, 실제는 `frozen_enums_hash` + `SCHEMA_CONTRACT_DRIFT` gate 로 강화 — [schema-catalog § frozen-enum](/services/index/schema-catalog#frozen-enum-계약--frozen_enums_hash-d-index-47-p1)). **달라진 것**:
>
> - **ingest → artifact 적재**는 design-era `ingest_financial_model_xlsx` 가 아니라 **`propose_artifacts_from_ingest`** (dataroom sidecar glob → typed artifact + citation + `_provenance` stamp). artifact-first judgment layer ([D-index-45](/ops/decisions)) 가 당시엔 없던 본질.
> - **pmc 8-agent / cross-deal SQL (§3, §6)** 은 `portfolio_kpi` · `risk_alert` · `valuation` 테이블을 가정하나 이들은 아직 **phase-1 stub** (미적재) — [schema-catalog § stubs](/services/index/schema-catalog#6-phase-1-stubs-status-phase1_backlog).
> - **skill ownership** 의 실 분배 경로 = [D-index-47](/ops/decisions) universal-base mirror + vertical-gate ([skill-ownership](/services/index/skill-ownership)). MCP byte-delivery skill discovery 는 infeasible 판명.
>
> 아래는 server-side 설계 의도 기록으로 보존. 현행 도구 카탈로그 = [/services/index § MCP 도구 카탈로그](/services/index#mcp-도구-카탈로그-27).

ingest · ic · pmc 3 skill 이 index MCP 서비스와 어떻게 통합되는가의 본격 설계. 본 페이지는 [/ops/decisions D-index-11~15](/ops/decisions) 의 implementation 가이드 + [/services/index/skill-evolution](/services/index/skill-evolution) 의 진화 path 의 server-side counterpart.

## 5-axis 정합

| Axis | 핵심 명시 |
|---|---|
| **본질** | skill = workflow (LLM-heavy authoring), index = persistence (typed fact SoT). 둘의 boundary 가 명시적이고 protected |
| **결과** | 3 deal (Iippo / Sentry / Canopy) 의 Phase 0 acceptance 8 test 모두 PASS — IRR ±1pp 일치, 펀드별 IRR 독립 산출, citation roundtrip |
| **퀄리티** | atomic `propose_deal_closure` 1 transaction, idempotency_key UUIDv5, 3-layer 에러 모델, schema authority immutable |
| **안전** | graceful degradation (index 죽어도 markdown 산출 유지), partial failure 차단 (all-or-rollback), Korean OCR worst-case 차단 (xlsx vision 만 label, PDF 거부) |
| **혁신** | cross-deal aggregate (fund NAV / portfolio risk heatmap / sector KPI benchmark) — ic/dd/vc 가 못 하는 영역. time-travel query 자연 |

## 3 skill 통합 매트릭스

| skill | 변경 정도 | 핵심 결정 | 산출물 |
|---|---|---|---|
| **ingest** | **변경 0** | 이중 path. dataroom markdown clone 만 (discovery phase). index 는 자체 `ingest_financial_model_xlsx` MCP tool 보유 — post-convergence, typed schema 강제. `vision_ingest.py` orthogonal | (그대로) |
| **ic** | **5th mode 추가, ~280-350 lines** | `--push-to-index` = FINALIZE 평행 track (sequential 아님). Step 5.5 (gate_memo.sh PASS 후, postmortem_stub 이전). atomic `propose_deal_closure` 단일 batch | SKILL.md Rule 25 + Step 5.5 + gate_memo.sh dispatch + 보조 scripts |
| **pmc** | **신규 greenfield + 2 skill 흡수** | portfolio-management + investor-relations 3-phase deprecate. 8 sub-agent (ic 19 < pmc 8). Trigger 3-tier (scheduled + event + manual). postmortem 2-track | SKILL.md + 8 sub-agent + references/ + scripts/ + pmc/ folder convention |

---

## 1. ingest skill 통합 — 이중 path

### 원칙

ingest skill 은 **수정하지 않음**. 이유:

- **본질 분리**: ingest = "dataroom 의 모든 확장자를 agent-readable markdown 으로" (discovery, all-files, vision-optional). index ingest = "재무 모델 xlsx 를 typed driver tree 로" (post-convergence, single-type, schema-strict).
- **재발 risk 차단**: ingest 가 typed schema 책임 가지면 deal 별로 다른 xlsx 모양에 대응하느라 generic ingest 기능이 distort.
- **vision_ingest.py orthogonal**: ingest skill 의 vision 은 dataroom 의 정성 정보 (IR PDF / 회사 자료 PPTX) 의 vision. index 의 ingest 는 xlsx sheet 의 label inference 만 vision (수치는 mechanical).

### Boundary

```
회사 IR pack 받음
  ↓
dataroom/{IR_v1.pdf, 회사소개.pptx, 3FS_model.xlsx, ...}
  ↓ /ingest (변경 없음)
  ↓
dataroom/{IR_v1_pdf.md, 회사소개_pptx.md, 3FS_model_xlsx.md, ...}  ← markdown clone (모두)
  ↓
/ic 실행 (Research squad 가 markdown clone 만 읽음)
  ↓
ic/finance/3fs_base/v{N}.xlsx 산출 (회사 모델 위 AXE 가정 overlay)
  ↓ /ic --push-to-index (선택, 5th mode)
  ↓
index.ingest_financial_model_xlsx(deal_id, ic/finance/3fs_base/v{N}.xlsx blob)
  ↓ Anthropic Sonnet (label inference) + calamine (cell value)
  ↓
financial_model + financial_driver + financial_driver_value DB 적재
```

### 정합 룰 ([D-index-15](/ops/decisions) [B-index-vision-boundary-rule](/ops/backlog))

| Input | Vision 허용 | Mechanical 강제 |
|---|---|---|
| dataroom 의 PDF (IR pack 등) | ✅ ingest skill (markdown clone 만) | (markdown 만 산출) |
| dataroom 의 PPTX | ✅ ingest skill (markdown clone 만) | (markdown 만 산출) |
| ic/finance/*.xlsx | sheet/row **label inference 만** | **numeric cell value 는 calamine** 강제 |
| ic/finance/*.xlsx 의 PDF embed | ❌ vision X | (지원 안 함) |
| dataroom PDF 직접 index 적재 | ❌ 차단 — `ingest_financial_model_xlsx` 가 PDF blob 거부 | — |

→ "5,941원 → 5,941엔" Korean OCR 오인식이 DB authoritative cell 이 되는 worst-case 영구 차단.

---

## 2. ic skill 통합 — 5th mode (`--push-to-index`)

### 4 mode → 5 mode

```
기존:                              진화 후 (D-index-11):
  /ic                                /ic
  ├─ INITIAL    (v1 full run)        ├─ INITIAL    (v1 full run)
  ├─ REVISION   (v{N}→v{N+1})        ├─ REVISION   (v{N}→v{N+1})
  ├─ APPEND     (§17 entry)          ├─ APPEND     (§17 entry)
  └─ FINALIZE   (ic/final/ lock)     ├─ FINALIZE   (ic/final/ lock)
                                     └─ --push-to-index  ← 신규, FINALIZE 평행 track
```

**왜 FINALIZE 와 평행 (sequential 아님)?**

- FINALIZE = OneDrive deliverable lifecycle (`ic/final/v{N}.{md,pdf}` lock)
- `--push-to-index` = DB lifecycle (typed fact persistence)
- 두 lifecycle 이 같은 commit 에 묶이면 partial failure 시 rollback 모호 (PDF 만 lock 되고 DB 미반영 / DB 만 적재되고 PDF 미생성)
- 평행 track = 한 쪽 실패가 다른 쪽 blocking 안 함. 양쪽 모두 retry-safe

### Step 5.5 위치

```
Step 0   : dataroom md clone + ctx sync (PR-O 4-mode dispatch 의 Mode 0)
Step 1-4 : 19-agent orchestration (proponent / premortem_critic / devils / qa / ...)
Step 5   : gate_memo.sh chain (citation_trace / xlsx_integrity / check_arithmetic / check_exit_matrix)
           ↓ PASS
           humanize Stage 4 (humanize-corrector sub-agent)
           ↓
           pdf_quality gate (check_pdf_quality.py)
           ↓
Step 5.5 : ← 신규. --push-to-index 플래그 detect 시 발동
           ├─ idempotency_key = UUIDv5(deal_id, f"{version}::{content_sha256}::{actor_email}")
           ├─ payload 수집 (financial_model xlsx blob + ic_decision + fund_investments[] +
           │   dd_findings[] + exit_matrix_leaves[] + risk_alerts[])
           ├─ POST /index/mcp propose_deal_closure (단일 atomic call, [D-index-13](/ops/decisions))
           ├─ 응답: { model_id, decision_id, ... } 또는 { error.code: "IDEMPOTENCY_CONFLICT", context: ... }
           └─ ic/index_push_state/v{N}.json local checkpoint
Step 6   : postmortem_stub.py 자동 호출 (ic skill 잔존 책임)
Step 7   : FINALIZE 가능 (별도 invocation, ic/final/ lock + render)
```

### Atomic `propose_deal_closure` ([D-index-13](/ops/decisions))

**개별 propose tool 6+ round-trip 금지** — partial failure 시 inconsistent state:

```jsonc
// ❌ 잘못된 패턴
POST /propose_financial_model    → 200 (commit)
POST /propose_ic_decision         → 200 (commit)
POST /propose_fund_investment[0]  → 200 (commit)
POST /propose_fund_investment[1]  → 500 ← FAIL — rollback 불가 (3 commit 됐음)
POST /propose_dd_finding[]        → never reached
```

```jsonc
// ✅ atomic 패턴
POST /propose_deal_closure {
  "deal_id": "iippo",
  "version": 8,
  "idempotency_key": "uuid-v5-...",
  "financial_model": { xlsx_blob, meta },
  "ic_decision": { memo_pdf_url, irr_7metric, voting },
  "fund_investments": [
    { fund: "axe_ia_001", round: "Pre-A RCPS 1호", committed: 99998912, ... },
    { fund: "axe_ia_002", round: "Pre-A RCPS 2호", committed: 100000000, ... }
  ],
  "dd_findings": [...],
  "exit_matrix_leaves": [...],
  "risk_alerts": [...]
}
  ↓ index 측 1 PostgreSQL transaction (SERIALIZABLE isolation)
  ↓ 모두 INSERT or ROLLBACK
  → 200 { model_id, decision_id, fund_investment_ids: [...], ... }
    또는 409 { error.code: "IDEMPOTENCY_CONFLICT", context.prior_actor, prior_ts }
```

### Idempotency ([D-index-13](/ops/decisions))

```python
# ic skill gate_memo.sh 가 매 호출 동일 input 으로 동일 key 생성
idempotency_key = uuid5(
    namespace=deal_id,
    name=f"{version}::{sha256(memo_v{N}.md + finance_xlsx_hashes)}::{actor_email}"
)
```

- `idempotency_record` 테이블 (hive 패턴 1:1 미러) — PK = idempotency_key, TTL = 24h
- 2번째 동일 key call → 409 + 1차 응답 cached body 반환 (silent re-insert 안 됨)
- 다른 input → 다른 key → 정상 처리

### gate_memo.sh 4 Python check 의 phased migration

[D-index-11](/ops/decisions) 의 결정. **즉시 deprecate 아닌 phased**:

| Script | 현재 (ic skill) | M7 Phase 1 | M7 Phase 2 |
|---|---|---|---|
| `citation_trace.py` | local WARN | local (memo prose audit, 유지) | local (영구 유지 — index 영역 외) |
| `check_arithmetic.py` | local WARN | local (memo prose audit, 유지) | local (영구 유지) |
| `xlsx_integrity.py` | local WARN | **이중 gate** — local 가벼운 pre-flight + index `validate_financial_model` DB trigger | DB trigger 만 (local script archive) |
| `check_exit_matrix.py` | local WARN | **이중 gate** — local + index trigger 가 결과 캐시 (dead_leaf / concentration flag) | DB trigger 만 |

**backward compat 100%** — `--push-to-index` 미사용 시 기존 4 script 그대로 동작.

### REVISION mode 와의 상호작용

```
v7 작성 + --push-to-index → financial_model v7 row DB
  ↓
v7 → v8 REVISION (사용자 피드백 반영)
  ↓
v8 --push-to-index → financial_model v8 row DB (UNIQUE (deal_id, version) 새 row)
  ↓
audit_trail 에 v7 supersede 이벤트 + v8 propose 이벤트 모두 보존
  ↓
last-write-wins (v8 이 "current"), 단 v7 도 time-travel query 가능
```

---

## 3. pmc skill 통합 — greenfield + 2 skill 흡수

상세 = [skill-evolution § pmc](/services/index/skill-evolution#pmc-skill) — 본 페이지는 server-side touchpoint.

### Trigger 3-tier

```
1. SCHEDULED (launchd daily 09:00 KST, 매월 첫 영업일 fire)
   /pmc --quarterly --deal-code <CODE> --push-to-index
   ↓
   - 지난 분기 KPI 스냅샷 (board pack ingest 또는 index prior 조회)
   - board_pack draft (markdown + PDF render)
   - LP quarterly letter draft
   - index.portfolio_kpi + index.valuation propose

2. EVENT (red alert 자동 fire)
   pmc/scripts/risk_monitor.py (launchd 5분 polling)
   ↓ runway < 6M / 핵심 인력 이탈 / burn_spike > 30% 등 감지
   ↓
   /pmc --alert --deal-code <CODE> --kind <runway_under_6m|key_personnel|...>
   ↓ index.risk_alert propose (severity=red, raised_at=now)
   ↓ Teams bot notification (operator + deal partner)

3. MANUAL
   /pmc --postmortem-fill --deal-code <CODE> --timepoint <t_3m|t_6m|t_12m|t_24m|exit>
   /pmc --board-pack --deal-code <CODE> --quarter <YYYY-Q[1-4]>
   /pmc --lp-letter --fund <axe_ia_001> --quarter <YYYY-Q[1-4]>
```

### Postmortem 2-track ([D-index-12](/ops/decisions))

```
ic skill (investment phase — 책임 유지):
  postmortem_stub.py (gate_memo.sh PASS 시 stub 생성, idempotent)
  postmortem_reminder.py (launchd daily 09:00 KST, target_date ±7일 미완 macOS notification)
  references/postmortem-cadence.md (spec SoT)

pmc skill (portfolio care phase — 신규):
  scripts/postmortem_fill_interactive.py (yaml interactive fill, 5 시점)
  scripts/render_postmortem.py (ic 에서 이관)
  --push-to-index → index.postmortem propose
  references/postmortem-cadence.md (ic 의 file 을 symlink — single SoT)
```

같은 yaml file (`ic/_recap/{DEAL}_postmortem.yaml`) 을 양쪽이 다른 동작으로 다룸:
- ic = stub 생성 + reminder
- pmc = fill (yaml 채움) + render (1-pager) + push (index DB)

### 8 sub-agent (ic 19 < pmc 8 — lighter)

| Sub-agent | 역할 | LLM model |
|---|---|---|
| 1. data-fetcher | dataroom board pack PDF / 회사 KPI 자료 / index prior 조회 | Sonnet |
| 2. kpi-extractor | raw data → normalized snapshot (MRR/ARR/churn/runway/...) | Sonnet |
| 3. risk-alerter | portfolio-management 5 신호 vs 실측 비교 → red/yellow flag | Sonnet |
| 4. valuation-updater | last-round / mark-to-market / DCF 중 선택 + NAV 계산 | Opus |
| 5. exit-signal-analyzer | IPO / M&A / Secondary 체크리스트 진행도 평가 | Sonnet |
| 6. board-pack-drafter | KPI + risk + valuation → markdown board deck | Opus |
| 7. lp-comm-drafter | board pack → LP quarterly letter | Opus |
| 8. index-payload-composer | 위 산출물 → propose_*_snapshot JSON payloads | Sonnet |

### 3-phase deprecation ([D-index-12](/ops/decisions))

```
Phase 0 (즉시, M7 시작 시):
  portfolio-management SKILL.md 에 deprecation notice
  investor-relations SKILL.md 에 deprecation notice
  pmc SKILL.md skeleton 등록 (frontmatter + references/ placeholder)

Phase 1 (M7 Phase 1 launch + 첫 quarterly cycle 실행 후):
  portfolio-management KPI 표 → pmc/references/kpi-catalog.md copy + cross-link
  investor-relations LP 보고 구조 → pmc/references/ir-lifecycle.md copy

Phase 2 (3개월 후):
  portfolio-management / investor-relations SKILL.md disable
  Blueprint search/suggest 에서 pmc 로 redirect
  legacy 사용처 grep → pmc 로 갱신

Phase 3 (6개월 후):
  완전 archive (.deprecated/ 이동)
  pmc 가 context 에 fully absorbed
```

---

## 4. 3-layer error model ([D-index-14](/ops/decisions))

skill → index 모든 통신 에러는 일관 3-layer 표현 — 양파껍질 ([D-bp-mcp-1](/ops/decisions)) 의 "진단 불가, 모든 401 같은 메시지" 영구 차단.

### L1 — HTTP (RFC 9728)

```http
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://axe.axelabs.ai/index/mcp",
                  error="invalid_token",
                  error_description="Token aud claim missing index app_id_uri"
Content-Type: application/json
```

### L2 — MCP body (structured)

```jsonc
{
  "error": {
    "code": "FINANCIAL_MODEL_CONFLICT",
    "message": "financial_model (deal=iippo, version=7) already proposed",
    "context": {
      "prior_actor": "ai@axellc.com",
      "prior_ts": "2026-05-06T10:00:00Z",
      "idempotency_key": "uuid-v5-...",
      "existing_model_id": "uuid-mdl-..."
    }
  }
}
```

### L3 — skill handler

```python
# ic skill 의 lib/index_client.py (또는 pmc 의 동형)
def propose_deal_closure(deal_id, version, payload):
    resp = mcp_call("propose_deal_closure", {...})
    match resp.error.code:
        case "IDEMPOTENCY_CONFLICT":
            # 기존 propose 표시 + retry 차단
            print(f"⚠ Already proposed by {resp.context.prior_actor}")
            print(f"  Open ctx review queue: ...")
            return existing_response_from_cache
        case "VALIDATION_WARNING":
            # ctx review 사용자 confirm 요청
            return prompt_user_confirm(resp.context.detail)
        case "SCHEMA_NOT_FOUND":
            print(f"⚠ index schema {resp.context.schema_id} not found")
            print(f"  Run: axe deploy index --register-schemas")
            return None
        case "SERVICE_UNAVAILABLE":
            # 로컬 drafts 보존 + retry 안내
            save_to_local_drafts(payload)
            return None
        case "CITATION_RESOLVE_FAILED":
            # cached value + warning chip
            return resp.context.cached_value_with_warning
```

### `IndexError` Rust enum SoT

```rust
// src/index/error_model.rs
pub enum IndexError {
    IdempotencyConflict { prior_actor: String, prior_ts: String, idempotency_key: Uuid },
    ValidationWarning { check: String, detail: String },
    SchemaNotFound { schema_id: String },
    CitationResolveFailed { citation_kind: String, reason: String },
    FinancialModelLocked { model_id: Uuid, locked_at: DateTime<Utc> },
    DslSyntaxError { formula: String, position: usize, suggestion: String },
    UnknownEnum { field: String, value: String, allowed: Vec<String> },
    DealNotFound { deal_id: String },
    FundEntityNotFound { fund_entity_id: String },
    ServiceUnavailable { reason: String },
    RateLimitExceeded { limit: u32, window: String },
    InsufficientScope { required: String, granted: Vec<String> },
}

impl From<IndexError> for McpErrorResponse {
    fn from(e: IndexError) -> Self {
        // deterministic (code, message, context) mapping
    }
}
```

**unit test 가 모든 case 의 wire-level response 검증** — silent fallback 절대 금지.

---

## 5. Schema authority immutable ([D-index-15](/ops/decisions))

DSL grammar + enum 은 service code 에만, skill 측 override 불가:

| 항목 | 위치 | 변경 절차 |
|---|---|---|
| DSL grammar (10 operator) | `src/index/dsl/grammar.pest` | service code SoT |
| `risk_alert.kind` enum 5종 | `src/index/schemas.rs` | service code SoT |
| `instrument` enum 5종 | `src/index/schemas.rs` | service code SoT |
| `fund_investment.status` enum 6종 | `src/index/schemas.rs` | service code SoT |
| `exit_matrix_leaf.path` enum 6종 | `src/index/schemas.rs` | service code SoT |

**ic skill 의 `scenario_deltas.yaml` 이 DSL syntax error 또는 unknown enum 값 emit 시**:

```jsonc
// ic skill 호출
POST /ingest_financial_model_xlsx { deal_id: "iippo", xlsx_blob: "..." }
  ↓ index 측 validation
  ↓
{
  "error": {
    "code": "DSL_SYNTAX_ERROR",
    "message": "Formula parse failed at position 23",
    "context": {
      "formula": "revenue[y0] * (1 + 0.85)",  // wrong — should reference driver
      "position": 23,
      "suggestion": "revenue[y0] * (1 + revenue_growth_y1)",
      "doc": "https://docs.axelabs.ai/services/index/financial-model#dsl-formula"
    }
  }
}
  ↓
ic skill → ctx review queue 에 highlighted error + 정정 예시 표시 → 사용자 수정 후 confirm
```

**enum value 추가는 coordination PR 강제**:

1. `src/index/schemas.rs` SoT 수정 + 새 case 추가
2. `/index/schemas` envelope `@1.0` → `@2.0` version bump
3. Blueprint `artifact_schema` 자동 mirror (다음 fetch cycle)
4. ic / pmc skill 의 yaml validator 갱신
5. 모두 같은 PR 또는 ordered PR chain

silent 추가 금지 — frame KSME `accounting_standard` enum 영구 freeze 패턴 ([D-frame-fund-ksme-policy-check](/ops/decisions)) 의 index domain 확장.

---

## 6. Cross-deal aggregate — pmc 만의 본질 (혁신 axis)

ic / dd / vc 가 deal-by-deal 시점. pmc 는 **fund × portfolio × sector × time** 4축 aggregate. **LP 보고의 backbone**.

### Fund-level quarterly NAV

```sql
SELECT
  fi.fund_entity_id,
  DATE_TRUNC('quarter', v.asof_date) AS quarter,
  SUM(v.nav_krw) AS total_nav,
  SUM(v.unrealized_krw) AS total_unrealized,
  SUM(v.realized_krw) AS total_realized,
  COUNT(DISTINCT v.deal_id) AS portfolio_size
FROM index.valuation v
JOIN index.fund_investment fi ON v.fund_investment_id = fi.id
WHERE fi.fund_entity_id = 'axe_ia_001'
  AND v.asof_date >= '2025-01-01'
GROUP BY fi.fund_entity_id, DATE_TRUNC('quarter', v.asof_date)
ORDER BY quarter DESC;
```

### Portfolio risk heatmap

```sql
SELECT
  d.deal_code,
  tc.brand_name,
  COUNT(*) FILTER (WHERE ra.severity = 'red') AS red_count,
  COUNT(*) FILTER (WHERE ra.severity = 'yellow') AS yellow_count,
  STRING_AGG(DISTINCT ra.kind, ', ') AS active_alerts
FROM index.deal d
JOIN index.target_company tc ON d.target_company_id = tc.id
LEFT JOIN index.fund_investment fi ON d.id = fi.deal_id
LEFT JOIN index.risk_alert ra ON d.id = ra.deal_id AND ra.resolved_at IS NULL
WHERE fi.fund_entity_id = 'axe_ia_001'
GROUP BY d.id, tc.brand_name
ORDER BY red_count DESC, yellow_count DESC;
```

### Sector KPI benchmark

```sql
SELECT
  tc.sector,
  DATE_TRUNC('quarter', k.asof_date) AS quarter,
  AVG(k.value) FILTER (WHERE k.kind = 'burn_multiple') AS avg_burn_multiple,
  AVG(k.value) FILTER (WHERE k.kind = 'runway_months') AS avg_runway,
  AVG(k.value) FILTER (WHERE k.kind = 'churn_monthly') AS avg_churn,
  COUNT(DISTINCT k.deal_id) AS sample_size
FROM index.portfolio_kpi k
JOIN index.deal d ON k.deal_id = d.id
JOIN index.target_company tc ON d.target_company_id = tc.id
WHERE k.asof_date >= '2025-01-01'
GROUP BY tc.sector, DATE_TRUNC('quarter', k.asof_date)
ORDER BY tc.sector, quarter DESC;
```

→ `pmc/cross_deal/{fund_quarterly_nav_report.md, portfolio_risk_heatmap.xlsx, sector_kpi_benchmark.md, fund_irr_projection.md}` 자동 생성.

→ LP 보고서의 정량 backbone — 매 분기 산출 시간 days → minutes.

---

## 7. 3 worst-case integration risks + 차단

### Risk 1 — Schema drift (퀄리티 axis)

**시나리오**: ic 의 `scenario_deltas/v7.yaml` 의 `revenue_growth_y1: 1.85` (multiplier) 를 index 가 `0.85` (percentage) 로 해석 → IRR 산출 wrong → LP audit fail.

**차단**:
- DSL grammar 가 **service code hardcoded** ([D-index-15](/ops/decisions))
- ingest tool 이 syntax error 시 `DSL_SYNTAX_ERROR` + explicit suggestion + doc link
- Phase 0 acceptance A2 (`compute_outputs ±1pp 일치`) 가 매 PR 검증
- `B-index-integration-fixtures` 가 Iippo/Sentry/Canopy 3 deal regression

### Risk 2 — Korean OCR worst-case (안전 axis)

**시나리오**: dataroom IR PDF 의 "5,941원" → "5,941엔" (yen, 1000x off) 오인식 → 영구 DB 적재 → IRR -2pp.

**차단**:
- `ingest_financial_model_xlsx` 의 input validation: PDF blob 거부 (`B-index-vision-boundary-rule`)
- xlsx 만 vision 보조 — sheet/row label inference 만, numeric value 는 calamine 강제
- Phase 0 acceptance A2 ±1pp tolerance 가 catch
- ic skill 잔존 `citation_trace.py` 가 memo prose 숫자 trace 강제 (PDF 출처 명시)

### Risk 3 — pmc ↔ ic 동시 propose race (안전 axis)

**시나리오**: PCC #6 trigger fire + 동시에 pmc 가 Q4 KPI propose → 같은 `(deal_id, kind, asof_date)` 두 row → audit_trail 충돌.

**차단**:
- `record_kpi_snapshot` MCP tool 의 UPSERT (UNIQUE (deal_id, kind, asof_date))
- `updated_at > now - 6h` 시 warn modal (사용자 의도 확인)
- pmc skill rule: `portfolio_kpi_snapshot.updated_at > (now - 6h)` 시 propose 보류
- audit_trail 에 양쪽 모두 기록 + `is_override=true` flag

---

## 8. 양파껍질 재발 차단 — 21 항목 운영 체크포인트

[mcp-server-checklist § 8](/architecture/mcp-server-checklist) 의 운영 14 → **21** 항목으로 확장 ([B-index-mcp-checklist-extension](/ops/backlog)):

| # | 검증 | 명령 | 정답 |
|---|---|---|---|
| 17 | skill idempotency | 2× call same `propose_deal_closure(idempotency_key=X)` | 2nd call 409 + `context.prior_actor`. silent re-insert 0 |
| 18 | citation resolver roundtrip | ic memo citation `{kind:"index.financial_output", ...}` → resolve → DB query value | floating-point epsilon (0.001 percent) 이내 일치 |
| 19 | cross-skill conflict detect | pmc + ic 동시 `record_kpi_snapshot(같은 deal, kind, asof_date, 다른 value)` | audit_trail 양쪽 기록 + last-write-wins + warning modal |
| 20 | graceful degradation | `docker stop index-mcp` 후 `ic --push-to-index` | MCP timeout (3s) 후 markdown-only fallback + warning banner. memo 정상 render |
| 21 | schema evolution | index 에 `financial_output.tax_adjusted_irr` 새 field 추가. 기존 ic skill 호출 | Blueprint `/schemas` mirror 자동 갱신. 기존 artifact citation resolve 정상. ic skill 다음 run 시 새 field 옵션 사용 |

`axe test index --accept-gate` 통합 명령 + 24h production monitor (error rate under 0.1 percent, citation cache hit over 95 percent).

---

## 9. 변경 분량 추정

| 영역 | Phase 0 | Phase 1 | Phase 2 |
|---|---|---|---|
| **ic skill 변경** | — | ~280-350 lines (SKILL.md Rule 25 + Step 5.5 + gate_memo.sh dispatch + scripts) | — |
| **pmc skill 신규** | SKILL.md skeleton (~150 lines) | 8 sub-agent + references/ (~500 lines) + scripts/ (~300 lines) | render templates + cross-deal SQL |
| **portfolio-management deprecation** | notice 추가 (~10 lines) | KPI 표 → kpi-catalog.md copy | SKILL.md disable |
| **investor-relations deprecation** | notice 추가 (~10 lines) | LP 구조 → ir-lifecycle.md copy | SKILL.md disable |
| **index Rust 코드** | error_model.rs + integration fixtures (~1500 lines) | propose_deal_closure + idempotency_record (~800 lines) | cross-deal SQL views + pmc tools (~600 lines) |
| **Blueprint client** | `lib/index_client.py` skill 측 wrapper (~200 lines) | citation resolver (`citations/index.ts`) (~300 lines) | UI integration |
| **docs** | 본 페이지 + skill-evolution.mdx update | financial-model.mdx + schema-catalog.mdx update | pmc-specific section 추가 |

총 추정: Phase 0 ~ 2,000 lines, Phase 1 ~ 2,500 lines, Phase 2 ~ 1,500 lines. 6 weeks Phase 0+1, 12 weeks total (M7 완료).

---

## 관련 페이지

- [/services/index](/services/index) — 서비스 main
- [/services/index/financial-model](/services/index/financial-model) — 6-table SoT + 3 deal worked example
- [/services/index/schema-catalog](/services/index/schema-catalog) — 14 schemas spec
- [/services/index/skill-evolution](/services/index/skill-evolution) — 5 skill → service 진화 (본 페이지의 자매)
- [/ops/decisions D-index-11~15](/ops/decisions) — 5 신규 결정
- [/ops/backlog](/ops/backlog) — 본 페이지의 M7 implementation 항목 (`B-ic-push-mode-impl` 외 9 항목)
- [/architecture/mcp-server-checklist](/architecture/mcp-server-checklist) — 21 운영 체크포인트 (B-index-mcp-checklist-extension 후)
- [/architecture/artifacts](/architecture/artifacts) — Blueprint artifact + citation kind `index.*` (D-index-6 mirror)

---

<!-- PAGE https://docs.axelabs.ai/services/index/skill-ownership -->

# Skill Ownership

> index 산하 skill 의 canonical SoT + overlap 정책 + Phase 1 MCP discovery 진화 path. D-index-17 정합.

URL: https://docs.axelabs.ai/services/index/skill-ownership

# Skill Ownership — index 산하 투자 도메인 skill

[D-index-17](/ops/decisions) 결정 정합. `ic` + `ingest` 의 ownership 을 Blueprint 에서 index 로 이전. Overlap 기간 양쪽 보유, index canonical.

## ⭐ 현재 구현 — D-index-47 (P0–P3, 2026-06-03 LIVE)

[D-index-17](/ops/decisions) 의 ownership *의도*를 [D-index-47](/ops/decisions) 가 **실구현·배포**했다. 아키텍처 = **index owns TRUTH** (SoT bytes·semver·schema-contract·append-only audit) · **Blueprint owns ROAD** (universal git→webhook→rsync 분배, 신규 transport 0) · **surface owns RUN** (Agent SDK 로컬 디스크 read).

- **P0 reconcile** (index `3b39a03`) — `index/skills/ingest` 가 Blueprint base 보다 뒤처져 있던("index=SoT" 가 `ingest` 에 대해 거짓) 역드리프트를 port 로 해소 → index 가 현행 SoT (`diff -qr` 동일). `ic` byte-identical · `pmc` index-only · `INDEX_OWNED.txt` manifest · 죽은 launchd 폐기.
- **P1 stamp + drift gate** (index `11aca12`, deployed) — propose event(`artifact_event.payload_after`)에 `_provenance`(skill·bundle_sha256·`frozen_enums_hash`·actor·surface) 스탬프 + propose 시 schema-drift hard gate(불일치 → `SCHEMA_CONTRACT_DRIFT`). `/index/schemas` envelope 가 `frozen_enums_hash` publish(외부 caller 가 contract discover+pin).
- **P2 attest + mirror mechanism** (index `6edf0ff`) — `index-skill-sync.py --attest`(deterministic dir-sha256 drift sentinel, advisory) + `index-skill-mirror.sh`(index→blueprint sanctioned PR-flow mirror = 아래 수동 cp -R 절차 대체). ⚠ 아래 "Phase 2 MCP-discovery" 의 MCP byte-delivery 는 **infeasible 판명**(`SKILLS_ROOT` host 경로·컨테이너 부재) → attest-only 로 재범위.
- **P3 vertical-gate** (blueprint PR #381 gate + #382 pmc, merged origin/main) — 8 투자 skill(ic·ingest·due-diligence·vc-deal-sourcing·investor-relations·portfolio-management·legal-compliance + pmc)에 `owner: index` frontmatter + blueprint boot(`start.sh`)/webhook(`route.ts`) 양 경로 gate(customer `services.index` 유무 → 비-index `rm -rf`+skip purge, index keep). **index customer(axe)만 투자 skill 수신**, 비-index(Truvia)는 universal 9개만. axe 3중 안전(services.index + `:-axe` 기본 + fail-safe keep + 운영자 sync ungated).

> **Sunset 재정의**: Blueprint mirror 는 "제거 대상"이 아니라 **분배 ROAD 로 정식 채택**(index→blueprint mirror + vertical-gate). 아래 design-era 절차/Phase-2 plan 은 이 구현으로 **superseded** — 실제 경로 = universal-base mirror + `--attest` sentinel + `owner:index` gate.

## 본질 — 왜 index 가 owner?

| Skill | 도메인 | index 가 owner 인 이유 |
|---|---|---|
| **ic** | 19-agent IC memo orchestration | 투자 도메인. 산출 = `index.ic_decision` + `index.financial_model` typed fact |
| **ingest** | dataroom pdf/pptx/xlsx → md clone | ic 의 직접 의존. 함께 가는 게 의존성 단순 |
| **pmc** (신규) | 분기 KPI / risk / NAV / postmortem | [D-index-12](/ops/decisions) — portfolio-management + investor-relations 흡수 |

향후 검토 (Phase 1 후속):
- `due-diligence` — DD 체크리스트 (투자 도메인)
- `vc-deal-sourcing` — pipeline 관리 (투자 도메인)

Blueprint 잔존:
- `ctx` / `humanizer` / `report-writing` / `vault-secret-capture` / `office-admin` / `code-review` / `browser-automation` / `md-to-pdf` / `blueprint-platform` — 일반 skill

## Overlap 정책 (2026-05-28 시점)

```
/Users/axe/index/skills/                     ← CANONICAL SoT ⭐
  ├── ic/
  │   ├── SKILL.md (45 KB, 25 rules)
  │   ├── scripts/  (gate_memo.sh + 26 Python scripts)
  │   ├── references/
  │   └── tests/fixtures/
  ├── ingest/
  │   ├── SKILL.md
  │   └── scripts/  (ingest.py + vision_ingest.py + sync.sh)
  └── README.md   (overlap 정책 + sync 책임)

/Users/axe/blueprint/.claude/skills/         ← MIRROR (overlap 기간)
  ├── ic/      (byte-identical)
  └── ingest/  (byte-identical)
```

**Sync 책임**:
1. **편집은 canonical 측** (`/Users/axe/index/skills/`) 에서만
2. Blueprint mirror 는 index 변경 후 byte-identical cp + sha256 검증
3. Blueprint hook (`skill-sot-guard.sh`) 가 main 직접 편집 차단 → drift 자동 방지

## Sync 절차 (overlap 기간 안내)

```bash
# 1. canonical 편집 + commit (index repo)
cd /Users/axe/index/skills/<name>
vim SKILL.md
cd /Users/axe/index && git add skills/<name> && git commit -m "feat(skill/<name>): ..."

# 2. Blueprint mirror sync
# Blueprint feature branch worktree 만들기 (hook 가 main 차단)
cd /Users/axe/blueprint
git fetch origin main
git worktree add .claude/worktrees/skill-sync-<date> -b claude/skill-sync-<date> origin/main

# 3. cp + sha256 검증
cd .claude/worktrees/skill-sync-<date>
cp -R /Users/axe/index/skills/<name>/* .claude/skills/<name>/
diff -qr /Users/axe/index/skills/<name> .claude/skills/<name>  # empty = identical
git add .claude/skills/<name>
git commit -m "sync(skill/<name>): mirror from index (D-index-17)"

# 4. PR + merge
```

Phase 2 진화 후 본 manual sync 절차는 자동화 (MCP discovery + 자동 fetch).

## Sunset 기준 (Phase 2 후 Blueprint mirror 제거)

다음 3 가지 모두 충족 시:

| 기준 | 검증 방법 |
|---|---|
| (a) 다음 3 deal 의 IC 실행이 `index/skills/ic/` 기반 정상 작동 | gate_memo.sh PASS + memo PDF 정상 + ctx review queue 정상 |
| (b) Blueprint Claude Agent SDK 가 index/skills/ mount/sync 자동화 확립 | docker-compose volume mount 또는 launchd cron sync |
| (c) `ic --push-to-index` mode 일반화 | [B-ic-push-mode-impl](/ops/backlog) PASS + 3 deal `propose_deal_closure` 성공 |

→ 충족 시 [B-index-skill-overlap-sunset](/ops/backlog) 으로 Blueprint mirror 완전 제거.

## Phase 2 진화 — MCP-based skill discovery  ⚠ SUPERSEDED (D-index-47)

> **⚠ 이 plan 은 [D-index-47](/ops/decisions) P2 에서 superseded.** MCP byte-delivery(`get_skill_resource` 로 SKILL.md/scripts fetch)는 **infeasible 판명**: `SKILLS_ROOT` 가 하드코딩 host 경로라 컨테이너에 부재 → 프로덕션에서 `SKILLS_ROOT_READ_FAILED`. 실제 채택 경로 = **universal-base git→webhook→rsync 분배(ROAD) + `index-skill-mirror.sh`(SoT push) + `--attest`(drift sentinel) + `owner:index` vertical-gate**. 아래는 역사적 기록.

본 결정 (D-index-17) 의 후속 진화 path (superseded). 별도 backlog 등재:

### `B-index-skill-mcp-discovery`

index MCP 에 신규 tool:

| Tool | 역할 |
|---|---|
| `list_skills(domain?)` | 전체 skill 카탈로그 (name + version + locked_at) |
| `get_skill_resource(name, version?)` | SKILL.md + scripts/* + references/* fetch (versioned) |
| `propose_skill_update(name, version, content_diff)` | atomic INSERT (git PR 대신 DB versioning) |

`/index/schemas` envelope 에 `index.skill_resource@1.0` 추가 — Blueprint `artifact_schema` 자동 mirror.

### `B-blueprint-skill-mcp-client`

Blueprint Claude Agent SDK 변경:
- session 시작 시 `list_skills()` 호출 → in-memory cache
- skill 사용 시 `get_skill_resource(name)` 동기 fetch
- filesystem `.claude/skills/` 의존 점진 제거

### `B-index-skill-versioning-schema`

```sql
CREATE TABLE shared.skill_resource (
  id              uuid PRIMARY KEY,
  name            text NOT NULL,       -- 'ic', 'ingest', 'pmc'
  version         int NOT NULL,        -- semver-like
  skill_md        text NOT NULL,       -- SKILL.md 본문
  scripts         jsonb NOT NULL,      -- { filename: content } map
  references_md   jsonb NOT NULL,      -- { filename: content }
  domain          text,                -- 'investment', 'platform', 'general'
  created_by      varchar(254),
  locked_at       timestamptz,         -- locked = immutable
  superseded_by   uuid,                -- next version FK
  UNIQUE (name, version)
);
```

Per-deal trace: `index.ic_decision.skill_version_used` field 추가 → "이 IC 메모는 ic skill v8.3 으로 작성" 영구 audit.

### 혁신적 capability — Cross-deal skill effectiveness analytics

```sql
-- "ic skill v8.3 사용한 deal 평균 IRR vs v8.0 사용한 deal"
SELECT
  ic.skill_version_used,
  AVG(fo.value) AS avg_loss_included_irr,
  COUNT(*) AS deal_count
FROM index.ic_decision ic
JOIN index.financial_output fo
  ON fo.model_id IN (SELECT id FROM index.financial_model WHERE deal_id = ic.deal_id)
  AND fo.output_code = 'irr_loss_included'
  AND fo.scenario_id IN (SELECT id FROM index.financial_scenario WHERE code = 'weighted')
WHERE ic.skill_version_used LIKE 'ic@%'
GROUP BY ic.skill_version_used;
```

→ ic skill 진화의 정량적 효과 측정 가능. 다른 vertical 서비스 (frame/hive) 가 못 하는 영역.

## 도메인 ownership 매트릭스 (전체)

| Skill | 현재 위치 | Phase 1 owner | 비고 |
|---|---|---|---|
| `ic` | **index** ⭐ | index (D-index-17) | 도메인 정확 일치 |
| `ingest` | **index** ⭐ | index (D-index-17) | ic 의 직접 의존 |
| `due-diligence` | Blueprint | index 검토 | Phase 1 후속 결정 |
| `vc-deal-sourcing` | Blueprint | index 검토 | Phase 1 후속 결정 |
| `portfolio-management` | Blueprint (deprecate 중) | pmc 흡수 | [D-index-12](/ops/decisions) |
| `investor-relations` | Blueprint (deprecate 중) | pmc 흡수 | [D-index-12](/ops/decisions) |
| `pmc` (신규) | (미생성) | index | Phase 1 [B-pmc-skill-skeleton](/ops/backlog) |
| `ctx` | Blueprint | Blueprint | cross-deal 공통 |
| `humanizer` | Blueprint | Blueprint | 일반 prose |
| `report-writing` | Blueprint | Blueprint | 일반 |
| `vault-secret-capture` | Blueprint | Blueprint | 보안 (운영자) |
| `office-admin` | Blueprint | Blueprint or hive | 잔존 |
| `legal-compliance` | Blueprint | Blueprint | 잔존 |
| `code-review` | Blueprint | Blueprint | 개발 |
| `blueprint-platform` | Blueprint | Blueprint | self-reference |
| `browser-automation` | Blueprint | Blueprint | 일반 |
| `md-to-pdf` | Blueprint | Blueprint | 일반 변환 |

## 5-axis 정합

| Axis | D-index-17 결정 결과 |
|---|---|
| **본질** | 도메인 alignment — ic skill 의 산출이 `index.ic_decision`/`index.financial_model` typed fact 라면 ic skill 본체도 index 산하가 자연 |
| **결과** | Phase 1 즉시 (1.5h) — 2 skill (ic + ingest) ownership 이전 완료. Phase 2 (3-5d) — MCP discovery 자동화 |
| **퀄리티** | Overlap (cp) 방식, symlink 아님 — Blueprint deploy / docker volume 과 충돌 없음. byte-identical sha256 검증 의무 |
| **안전** | Blueprint hook (`skill-sot-guard.sh`) 가 main 직접 편집 차단 = drift 자동 방지. Sunset 3 기준 명확 |
| **혁신** | Phase 2 의 versioning + per-deal skill_version_used → "skill 진화의 정량 효과" cross-deal analytics — frame/hive/cortex 가 못 하는 영역 |

## 관련 페이지

- [/services/index](/services/index) — 서비스 main
- [/services/index/skill-evolution](/services/index/skill-evolution) — 5 skill → service 진화 path
- [/services/index/skill-integration](/services/index/skill-integration) — 통합 architecture
- [/ops/decisions D-index-12](/ops/decisions) — pmc skill 흡수
- [/ops/decisions D-index-17](/ops/decisions) — 본 결정
- [/ops/backlog M7](/ops/backlog) — overlap sunset + MCP discovery 후속

---

<!-- PAGE https://docs.axelabs.ai/services/magnet -->

# Magnet

> 마케팅 자동화 MCP — Meta Ads, Naver, Threads. 39개 도구, decisions ledger, brand SoT.

URL: https://docs.axelabs.ai/services/magnet

# Magnet

**한 줄 소개**: 마케팅 팀장의 직무를 통째로 갖는 에이전트. 광고 예산·크리에이티브·소셜 응대·위기 대응을 자동화. 39개 MCP 도구, hash-chained decisions ledger, brand voice 중앙화.

## 정체성

> magnet (당기다) ↔ stream (흐르다)  
> 마케팅이 수요를 *당기면* 운영이 공급을 *흐르게* 한다.

domain 분업: magnet 은 자기 도메인의 외부 채널(광고·소셜) + 의사결정만 소유. 판매·SCM 은 stream MCP 가 owner.

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Python 3.12+ |
| 프레임워크 | mcp[cli] ≥1.27 (FastMCP) |
| DB | PostgreSQL 16 (multi-tenant + RLS) |
| Scheduler | supercronic (Asia/Seoul TZ) |
| 의존성 | pyyaml ≥6, psycopg[binary] ≥3.2, openpyxl ≥3.1 |

## 포트

| 포트 | 용도 |
|---|---|
| 8770 | MCP HTTP/SSE (`magnet-mcp`) |
| 5432 | PostgreSQL (`magnet-postgres` 컨테이너, 127.0.0.1 loopback 만) |

## 39 MCP Tools (6 prefix)

| Prefix | 모듈 | 도구 수 | 주요 |
|---|---|---|---|
| `meta_ads_*` | meta-ads | 5 | get_campaigns, propose/execute_budget_change |
| `meta_capi_*` | meta-ads | 2 | send_event, send_purchase |
| `social_*` | social | 19 | `post_to_fb/ig/threads`, reply_to, like, get_insights |
| `naver_search_ad_*` | naver-ads | 3 | get_campaigns, propose_keyword_bid (skeleton) |
| `marketing_*` | performance + content | 9 | get_ad_spend, daily_brief, weekly_brief, compose_post_prompt |
| `decisions_*` | decisions | 3 | get_decisions, verify_chain_integrity, get_lifecycle |
| `stream_bridge_*` | stream-bridge | 4 | send_purchase_from_stream, handle_inventory_alert |
| `marketing_compose_*` | marketing-compose | 2 | compose_post_prompt, validate_copy |
| `threads_browser_*` | threads-browser-host | 4 | init, like, action, status (호스트 stdio MCP) |

## 디렉토리 구조

```
/Users/axe/magnet/
├── mcp/
│   ├── server.py            ★ 통합 daemon — importlib 로 6 모듈 흡수
│   ├── meta-ads/            Meta Ads + CAPI
│   ├── social/              FB + IG + Threads
│   ├── naver-ads/           네이버 검색광고 (skeleton)
│   ├── performance/         ROAS · CAC · spend 조회
│   ├── content/             콘텐츠 발주 (truvia-marketing-agents 연동)
│   ├── decisions/           decisions ledger 조회·시각화
│   ├── stream-bridge/       stream 신호 receiver (2026-05-11)
│   ├── marketing-compose/   카피·답글 생성 (brand SoT 주입)
│   └── threads-browser-host/ Threads 브라우저 자동화 (별도 stdio MCP)
│
├── scripts/
│   ├── automation/          6+ 자동화 (LaunchAgent 흡수)
│   ├── marketing/           MCP 도구 구현 + CLI
│   ├── db/                  DB 연결 + sync
│   ├── admin/               운영자 CLI
│   ├── decisions/           decisions 분석
│   └── entity/              멀티 엔터티 레지스트리
│
├── brand/                   ★ 마케팅 identity SoT
│   ├── personas/operator.yaml    화자 정체성
│   └── voice/                    채널별 톤
│       ├── _global.yaml          전 채널 (광고법·금기)
│       ├── threads.yaml
│       ├── instagram.yaml
│       └── fb.yaml
│
├── data/
│   ├── decisions/realchoice.jsonl   ★ hash-chained ledger (append-only)
│   ├── reports/YYYY-MM-DD.md
│   ├── pending-monitor-actions/
│   └── pending-user-actions.md
│
├── sql/                     스키마 1,300 LOC (10 파일)
│   ├── 000_schema.sql       campaign_metrics_daily, posts, threads_post_snapshots
│   ├── 050_multi_tenant_baseline.sql   ★ RLS + tenant_id
│   ├── 060_threads_clone.sql           Threads snapshot (사고 회복)
│   ├── 100_views.sql
│   └── 200_personas.sql     (nemotron-personas 로 migrate 예정)
│
├── docs/                    핸드오프 + 결정 + 가이드
│   └── incidents/
│       └── 2026-05-14-threads-self-delete.md   사고 리뷰
│
├── crontab                  ★ 10 자동화
├── docker-compose.yml       3 service (magnet-mcp + magnet-cron + magnet-postgres)
├── CLAUDE.md                ★ 자동 로드 컨텍스트
└── SECURITY.md
```

## 데이터 모델 (multi-tenant + RLS)

| 테이블 | 역할 |
|---|---|
| `campaign_metrics_daily` | 광고 성과 (spend, impr, conv, roas, cac) |
| `posts_fb` / `posts_ig` / `posts_threads` | 소셜 게시물 + insights |
| `threads_post_snapshots` | Threads snapshot (사고 회복 자산) |
| `decisions` | 의사결정 audit ledger |
| `campaign_budgets_proposed` | 예산 변경 안 (HMAC 서명, TTL) |
| `copy_ab_tests` | A/B 테스트 메타 |

**RLS**: `POSTGRES_USER=magnet_app` (non-superuser, BYPASSRLS=false), connection stage 에서 `SET app.tenant_id = &lt;id&gt;` 주입. 기본값 `tenant_id=1` (realchoice).

## Crontab (10 task)

| 주기 | 작업 |
|---|---|
| 매시 정각 | `sync_meta_live.py --since 0` + `refresh_daily_kpi.py` |
| 매시 정각 | `sync_threads_live.py` |
| 매시 10분 | `learning_reset_monitor.py` — 광고 학습 reset 회복 |
| 30분 주기 | `ingest_decisions.py realchoice` |
| 매일 01:00 | `naver_searchad_sync.py` |
| 매일 03:00 | `sync_meta_live.py --since 2` — 어제/그제 재폴링 |
| 매일 09:00 | `ad_xray_daily.py` — DataLab + keyword sync |
| 15분 주기 | `scheduled_carousel_publish.py` — 운영자 시간 트리거 |
| 매시 30분 | `sync_threads_full.py` — 게시물 snapshot |
| 20분 주기 | `scheduled_reply_publish.py` — 답글 자동 게시 |
| 매일 00:05 | `logrotate.sh` |
| 09:00 외 | `daily_monitor.py`, `faq_responder.py`, `roas_safety_net.py`, `refund_spike_safeguard.py`, `negative_feedback_alert.py`, `threads_token_refresh.py` |

## Decisions Ledger (hash-chained)

`data/decisions/realchoice.jsonl` 에 모든 의사결정 append-only 저장:

```json
{
  "ts": "2026-05-20T15:00:00+09:00",
  "actor": "magnet-agent",
  "type": "ad_paused",
  "context": {"campaign_id": "23845...", "reason": "ROAS < 1.5"},
  "prev_hash": "sha256:abc..."   // 이전 line 의 SHA-256
}
```

`decisions_verify_chain_integrity()` 도구로 체인 무결성 검증.

## Brand SoT (operator + voice)

모든 카피·답글은 다음 2단계 강제:

1. `marketing_compose_post_prompt({...})` — brand SoT 자동 주입
2. `marketing_validate_copy(text)` — 광고법·금기 키워드·해시태그 정책 검증

`brand/personas/operator.yaml`:
```yaml
identity: "F&B 10년차 두 친구, 매장 비하인드"
disclose: false
hide:
  - real_name
  - exact_store_name
```

`brand/voice/threads.yaml`:
```yaml
tone: "친구 톤, 농담 OK"
no_hashtag: true            # Threads 는 해시태그 X
forbidden:
  - "최고", "1위", "유일"    # 광고법
length_max: 500
```

## Threads 사고 (2026-05-14, 영구 기록)

Threads 브라우저 자동화의 selector 결함으로 본 게시물 3개 + 모든 반응 영구 손실.

| 항목 | 값 |
|---|---|
| Root cause | `threads_browser.py` selector 가 답글 menu 에서 parent thread menu 잡음 |
| Impact | 운영자 carousel 본 게시물 3개 + 모든 반응 |
| Recovery | `data/pending-monitor-actions/2026-05-15-carousel-relaunch.md` (Graph API 재게시) |
| Guard | `MAGNET_THREADS_DANGER_ENABLED=1` 환경변수 없으면 delete/unrepost raise |

이후 모든 destructive Threads op (delete, unrepost) **manual only**, snapshot 매시간 백업으로 회복 자산 확보.

## 자가발전 에이전트

- 매시간 in-session loop + 매일 04:00 KST deep round
- 산물: `data/reports/YYYY-MM-DD.md`, `config/thresholds.yaml` (자율 조정)
- Token cap: 100K/round
- `[NEEDS_REVIEW]` 섹션으로 본 세션·사용자 결정 위임

## 외부 의존성

| 시스템 | 통합 |
|---|---|
| Meta Ads + CAPI | Marketing API v19+ |
| Naver SearchAd | API (HMAC-SHA256) |
| Threads / IG / FB | Graph API + 브라우저 자동화 (호스트 macOS Playwright) |
| stream MCP | 신호 수신 (purchase, inventory_alert) |
| nemotron-personas | 페르소나 조회 (별도 MCP) |
| truvia-marketing-agents | 콘텐츠 발주 인터페이스 |

## Tenant ID Mapping (D-magnet-tenant-map-1)

magnet 의 `MAGNET_TENANT_ID` 는 **service-internal RLS tenant_id** 이며, AXE Labs platform 의 customer ID (`customers.yaml` key) 와 **별개 namespace** 입니다. 본 섹션은 두 ID 의 mapping rule 을 명시합니다.

### 두 ID 의 분리

| 식별자 | 출처 | 예시 | 변경 책임 |
|---|---|---|---|
| **AXE customer ID** | `customers.yaml` 의 top-level key | `axe`, `realchoice` | 운영자 (액스코퍼레이션) |
| **`MAGNET_TENANT_SLUG`** | magnet `.env.local` 의 customer-name string | `realchoice` | service operator |
| **`MAGNET_TENANT_ID`** | magnet DB 의 RLS row identifier (`magnet.tenant.id`, integer) | `1` (realchoice) | DB migration |

같은 customer 가 두 ID 모두 가질 수 있으나 **string ↔ integer 매핑** 이 별도 lookup 필요.

### SSOT — `customers.yaml` 의 `service_tenant_map` (D-magnet-tenant-map-1, 2026-05-23)

신설 필드. 각 customer 블록 안에서 customer 가 사용하는 각 service 의 internal tenant id 를 명시:

```yaml
customers:
  realchoice:
    ...
    service_tenant_map:        # NEW field (D-magnet-tenant-map-1)
      magnet:
        tenant_slug: "realchoice"
        tenant_id: 1
      stream:
        tenant_id: 1           # truvia_ssot (port 5433) 의 tenant row
  axe:
    ...
    service_tenant_map:
      # axe customer 가 magnet 사용 시 tenant_id=2 부여 (충돌 회피)
      magnet:
        tenant_slug: "axe"
        tenant_id: 2
```

### 신규 customer 가 magnet 사용 시 — 충돌 회피 절차

1. 운영자가 `customers.yaml` 의 신규 customer 블록에 `service_tenant_map.magnet` 등재 — `tenant_id` 는 **현재 최대값 + 1**
2. magnet DB migration 또는 admin tool 로 `magnet.tenant` 에 row INSERT (id=신규)
3. customer macmini 의 magnet `.env.local` 에 `MAGNET_TENANT_SLUG`/`MAGNET_TENANT_ID` 등재 (axe ship 이 customers.yaml manifest 에서 자동 주입 — `B-magnet-tenant-env-injection` 향후 작업)
4. RLS 검증: `SET app.tenant_id=<신규>` 후 cross-tenant read 가 빈 결과 보장 (테스트)

### realchoice 측 코드 자산 호환성

`~/magnet` 의 코드 자산은 변경 없음 — RLS 구조 + `tenant_id=1` (realchoice) 유지. 본 신설 mapping 은 **운영자 측 manifest 가시성** 만 추가 (DB schema 영향 0).

### 향후 axe 가 magnet 사용 시

axe customer 가 magnet 도입을 결정하면:
- `customers.yaml > customers.axe.service_tenant_map.magnet.tenant_id = 2` 등재
- magnet DB 에 `INSERT INTO magnet.tenant (id, slug) VALUES (2, 'axe')`
- 양 customer 의 magnet 데이터는 RLS 로 격리, 충돌 0

## 환경 변수 (140+ 라인 `.env.example`)

```bash
# DB
POSTGRES_DB=magnet
POSTGRES_USER=magnet_app
POSTGRES_PASSWORD=
POSTGRES_HOST=

# Multi-tenant — service-internal namespace (Tenant ID Mapping 섹션 참조)
MAGNET_TENANT_SLUG=realchoice
MAGNET_TENANT_ID=1

# Meta Ads
META_ADS_ACCESS_TOKEN=
META_AD_ACCOUNT_ID=
MAGNET_PROPOSAL_HMAC_KEY=
META_PIXEL_ID=

# Naver
NAVER_AD_CUSTOMER_ID=
NAVER_AD_API_KEY=
NAVER_AD_SECRET_KEY=
MAGNET_NAVER_AD_LIVE=1

# Transport
MAGNET_TRANSPORT=sse
MAGNET_HTTP_HOST=127.0.0.1
MAGNET_HTTP_PORT=8770

# Decisions
MAGNET_DECISIONS_LOG_PATH=/data/decisions/realchoice.jsonl

# Threads guard
MAGNET_THREADS_DANGER_ENABLED=     # 미설정이 안전 (delete/unrepost raise)
```

## 관련 문서

- [Stream service](/services/stream) — sales/SCM 신호 발신자
- [/Users/axe/magnet/docs/](https://github.com/soohunkang/magnet/tree/main/docs) — 핸드오프 + incidents
- [/Users/axe/magnet/CLAUDE.md](https://github.com/soohunkang/magnet/blob/main/CLAUDE.md) — 자동 로드 컨텍스트

---

<!-- PAGE https://docs.axelabs.ai/services/matrix -->

# Matrix

> AXE Labs 인프라 모니터링 MCP. Rust + native MCP (no Python SDK). Docker 컨테이너 + HTTP endpoint + Cloudflare tunnel 의 health 를 1분 주기로 수집하여 상태 보드 + alert + Blueprint 에이전트 도구로 노출.

URL: https://docs.axelabs.ai/services/matrix

# Matrix

**한 줄 소개**: AXE Labs 내부 인프라 (Docker 컨테이너 · HTTP 엔드포인트 · Cloudflare tunnel · 디스크) 의 health 를 1 분 주기로 수집하여 (a) `axe.axelabs.ai/matrix` 상태 보드, (b) `acked_at IS NULL` alert 큐, (c) Blueprint 에이전트가 MCP 5 도구로 조회 — 의 3 가지 surface 로 노출하는 **첫 Rust 서비스** ([D-matrix-1](/ops/decisions)).

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Rust 2024 edition (toolchain `rust:1.95-slim`) |
| HTTP framework | axum 0.8 + tower-http (CORS) |
| Async runtime | tokio 1 (full) |
| DB | PostgreSQL 16 (alpine, ICU `ko-KR`) + sqlx 0.8 (`runtime-tokio` + `tls-rustls`) |
| Docker API | bollard 0.18 (container health 조회) |
| HTTP client | reqwest 0.12 (rustls, 5s timeout) — endpoint probe |
| 인증 | jsonwebtoken 9 (HS256 JWT, `MATRIX_JWT_SECRET`) — **현재 router 미부착, [known-gaps](/ops/known-gaps#matrix-mcp-auth-not-enforced) 참조** |
| 스케줄링 | tokio-cron-scheduler 0.13 + tokio sleep loop |
| 로깅 | tracing + tracing-subscriber (`env-filter` + json formatter) |
| Migration | 코드 인-라인 (db.rs `migrate()`, `CREATE TABLE IF NOT EXISTS`) |

소스: `/Users/axe/matrix/src/` (~600 LOC, 6 modules: api · auth · collector · config · db · mcp)

## 포트

| 포트 | 용도 |
|---|---|
| 3901 | PostgreSQL 16 (`matrix-postgres`) |
| 3910 | MCP HTTP blue (`matrix-mcp-blue`, alias `matrix-mcp` active) |
| 3911 | MCP HTTP green (`matrix-mcp-green`, passive) |
| 3912 | `axe-matrix-proxy` (Caddy blue/green selector, 127.0.0.1 bind only) |

cloudflared origin → 외부 `https://axe.axelabs.ai/matrix` + `https://axelabs.ai/matrix` (둘 다 같은 path 라우팅). `matrix.axelabs.ai` 서브도메인은 **미등록** — DNS resolve 실패. 정식 경로는 `axe.axelabs.ai/matrix`.

## 3 가지 surface

1. **MCP** (`POST /matrix/mcp`) — JSON-RPC 2.0 over HTTP, 5 tools. Blueprint / Claude 에이전트가 도구로 호출
2. **REST** (`GET /matrix`, `/matrix/api/status`, `/matrix/api/alerts`) — 상태 보드 (인증 없음, 의도된 공개)
3. **Health probe** (`GET /health`, `/health/ready`) — Docker healthcheck + 외부 모니터링

> `/matrix/mcp` 는 코드상 `auth.rs::auth_middleware` 정의되어 있으나 `api.rs::router()` 에 부착되지 않음. 현재 anonymous 호출 가능. [B-matrix-mcp-auth-enforce](/ops/backlog) 참조.

## MCP Tools (5 개)

`src/mcp.rs:91-150` 의 `handle_tools_list()` 기준. `protocolVersion: 2025-03-26`, `serverInfo.name: "matrix"`, `serverInfo.version: env!("CARGO_PKG_VERSION")` (현재 `0.1.0`).

| Tool | 입력 | 설명 |
|---|---|---|
| `get_status` | — | 가장 최근 collector cycle 의 전체 health 보고 (in-memory `last_check`). 한 번도 안 돈 직후엔 `"no check results yet"` |
| `get_service_history` | `service` (string, required), `hours` (int, default 24) | 특정 서비스의 시계열 — `check_results.report` JSONB 에서 해당 `name` 의 status/detail 추출 (최근 100 rows) |
| `list_alerts` | `include_acked` (bool, default false) | unacked alert 50 개 (or 전체 50). UUID + service + severity + message + created_at + acked_at/by |
| `acknowledge_alert` | `alert_id` (UUID, required), `acked_by` (string, default `"operator"`) | `UPDATE alerts SET acked_at = now(), acked_by = $1 WHERE id = $2 AND acked_at IS NULL` — 이미 ack 된 항목은 no-op |
| `get_uptime_report` | `days` (int, default 7) | 기간 내 모든 cycle 의 per-service pass/total 카운트 + uptime% (소수점 2 자리) |

## REST endpoints

| 메서드 | 경로 | 인증 | 설명 |
|---|---|---|---|
| GET | `/health` | — | `{"status":"ok","service":"matrix"}` (DB 미점검) |
| GET | `/health/ready` | — | `{"status":"ok","db":"connected"}` 또는 `503 + {"db":"<err>"}`. Docker healthcheck 가 사용 |
| GET | `/matrix` | — | landing (상태 보드, 미구현 placeholder 가능성) |
| GET | `/matrix/api/status` | — | 최근 cycle 의 JSON 전체 — `get_status` MCP 와 동일 데이터 |
| GET | `/matrix/api/alerts` | — | unacked 20 개 alert |
| POST | `/matrix/mcp` | — (의도는 JWT) | MCP JSON-RPC. `initialize` / `tools/list` / `tools/call` 처리 |

## 데이터 모델

`src/db.rs:14-39` 의 인-라인 migration (`CREATE TABLE IF NOT EXISTS`). 3 테이블 + 2 인덱스.

| 테이블 | 컬럼 | 역할 |
|---|---|---|
| `check_results` | `id` UUID PK · `ts` TIMESTAMPTZ · `duration_ms` INT · `overall` TEXT (`pass`/`fail`) · `report` JSONB | collector cycle 의 전체 보고서 (모든 service check 결과 array 포함) |
| `services` | `name` PK · `svc_type` · `config` JSONB · `created_at` | (현재 미사용 — 향후 동적 등록용) |
| `alerts` | `id` UUID PK · `service` · `severity` (default `error`) · `message` · `created_at` · `acked_at` · `acked_by` | failure 1 회 발생 시 INSERT, 동일 서비스의 unacked alert 이 있으면 no-op (중복 방지) |

인덱스: `idx_check_results_ts` (DESC), `idx_alerts_unacked` (partial WHERE `acked_at IS NULL`).

## Collector — 무엇을 보는가

`src/collector.rs::run_loop()` — `MATRIX_CHECK_INTERVAL` 초마다 (default 30, [D-matrix-2](/ops/decisions) 에서 60→30), `run_check()` 가 5 종류 점검 병합:

| 종류 | 함수 | 대상 | 판정 |
|---|---|---|---|
| Docker container | `check_docker` | bollard 로 `all=false` (실행 중) 컨테이너 list. `status` 문자열에 `healthy` / `unhealthy` 포함 검사. `matrix-` 접두는 자가 모니터링 회피로 skip | unhealthy = fail, healthy or running = pass |
| HTTP endpoint | `check_http` | 2 개 — `blueprint-http` (host:3100/api/health) + `frame-mcp-http` (host:3710/health, alive-only). cortex-fe/cortex-be 는 개발 중이라 제거 (commit `96cf758`, 재가동 시 재활성) | 상태코드 일치 = pass; frame 만 응답 있으면 pass |
| Cloudflare tunnel | `check_tunnels` | 3 개 — `tunnel-artemis`, `tunnel-blueprint`, `tunnel-mysrt` (`*.axellc.com`) | 200/301/302 = pass, 그 외 = warn, unreachable = fail |
| Disk | `check_disk` | `df -h /` 의 root 디스크 사용률 | ≥90% = warn |
| **WAN/인터넷** | `check_wan` | 3 프로브 동시(`tokio::join!`) — `wan-gateway` (공유기 ICMP), `wan-internet` (`MATRIX_WAN_TARGET` ICMP, RTT+손실%), `wan-dns` (`MATRIX_DNS_HOST` 해석 시간). [D-matrix-2](/ops/decisions) | unreachable = fail. **귀책 판별**: gateway ↑ + internet ↓ ⇒ ISP/WAN fault (warning 발생), gateway ↓ + internet ↓ ⇒ 댁내 링크/WiFi |

호스트 도달은 모두 `host.docker.internal` 경유. failure 시 `create_alert()` 가 동일 서비스의 unacked alert 가 없을 때만 INSERT (중복 방지). cycle 결과는 항상 `check_results` 에 INSERT.

> **WAN 프로브 (D-matrix-2)**: `wan-*` 결과는 기존 `check_results` JSONB 에 그대로 들어가 별도 스키마 변경 없이 `get_service_history` / `get_uptime_report` / 상태 보드 / alert 에 자동 노출. ICMP 는 컨테이너에 `cap_add: NET_RAW` + 런타임 이미지의 `iputils-ping` 으로 권한상승 없이 가능 (Docker Desktop NAT 통과 + 공유기/외부 도달 검증 2026-06-03). 게이트웨이 IP 는 노드별로 다르므로 `MATRIX_LAN_GATEWAY` env 로 주입.

> **함정 (2026-05-26 발견 → 같은 날 fix)**: `blueprint-http` URL 이 `:3110` (미 listening) 으로 25 분+ 연속 FAILED 누적. 정정: `:3100/api/health` (Blueprint Next.js dev). 동일 세션에서 `cortex-fe`/`cortex-be` 도 검증 — cortex backend (`:3210`) 는 **실제 down**, cortex frontend (`:3200`) 는 listening 하지만 root path 빈 응답 → 두 항목은 valid alert (cortex 측 점검 별도 필요). [B-matrix-collector-port-fix](/ops/backlog) ✅

## 환경 변수

`src/config.rs::Config::from_env()` 기준. `.env.local` (env_file) 으로 vault → 컨테이너 dump (D-ops-18 패턴).

```bash
MATRIX_PORT=3910                                            # default 3910
MATRIX_DATABASE_URL=postgres://matrix:<pw>@postgres:5432/matrix
MATRIX_DB_PASSWORD=                                          # compose 가 ${MATRIX_DB_PASSWORD:?required}
MATRIX_JWT_SECRET=                                          # default "dev-secret-change-me" — production 미설정 시 위험
MATRIX_CHECK_INTERVAL=30                                    # 초 (D-matrix-2: 60→30, 끊김 해상도 향상)
MATRIX_CUSTOMER_ID=axe                                       # multi-tenant 마커
MATRIX_DEPLOY_COLOR=blue|green                              # blue/green 식별
MATRIX_LAN_GATEWAY=192.168.55.1                            # wan-gateway 프로브 대상 (공유기 IP, 노드별 상이)
MATRIX_WAN_TARGET=1.1.1.1                                   # wan-internet 프로브 대상 (공인 anycast)
MATRIX_DNS_HOST=google.com                                  # wan-dns 해석 테스트 호스트
```

> `MATRIX_LAN_GATEWAY` / `MATRIX_WAN_TARGET` / `MATRIX_DNS_HOST` 는 비밀이 아니라 노드별 설정값 — secrets 표/vault 등재 불필요 (default 존재). 단 `MATRIX_LAN_GATEWAY` 는 DHCP 로 바뀔 수 있어 노드 셋업 시 확인 ([D-matrix-2](/ops/decisions)).

[/architecture/secrets](/architecture/secrets) 의 service secrets 표 등재 (matrix `.env.local` = DB password + JWT secret + console API token 3 종).

## Blue/green 운영

- `matrix-mcp-blue` 와 `matrix-mcp-green` 가 동일 image (compose 의 `build: .`) 로 동시 실행. blue 만 `matrix-mcp` network alias 보유 → `axe-matrix-proxy` (Caddyfile 의 `reverse_proxy matrix-mcp:3910`) 가 항상 blue 로 forward.
- swap = compose 의 alias 를 green 으로 옮긴 후 `docker compose up -d --no-deps matrix-mcp-green` → 검증 → blue 도 업데이트. frame · hive 와 동일 패턴.
- **현재 상태** (2026-05-26): 두 컨테이너 동일 코드 (build 동시), 둘 다 healthy, 3 일 가동.

## 운영 노트 · 알려진 함정

- ~~**Git 미커밋**~~ ✅ — `f73492d` (initial) + `48a301b` (fix) 두 commit 으로 history 회복 (2026-05-26).
- ~~**Stale build (2026-05-23)**~~ ✅ — `matrix_info` 함수 미정의 (E0425) 였던 게 root cause. 같은 날 stub 추가 + 무중단 rebuild.
- ~~**JWT 미적용**~~ ✅ — `/matrix/mcp` 에 `middleware::from_fn(auth_middleware)` 부착 (commit `96cf758`). REST + health 는 anonymous 유지 (의도된 공개 status board). 검증: no-auth POST → 401 "missing bearer token", REST → 200. production 호출 client 0 (access log 0 + Blueprint repo 미참조) 확인 후 안전 부착.
- **자가 모니터링 회피**: collector 가 `matrix-` 접두 컨테이너를 skip. matrix-postgres 도 skip 됨 — 의도된 단순화, 그러나 DB 가 죽으면 `/health/ready` 자체가 503 떨어지므로 외부 healthcheck 로 보완.
- **39xx 범위 공유**: `axelabs` 회사 홈 (3900) 과 matrix (3901/3910/3911/3912) 가 같은 범위에서 공존. CLAUDE.md / [/ops/inventory#포트-할당](/ops/inventory#포트-할당) 에 명시.
- ~~**부수 발견 — cortex 측 valid alert**~~ ✅ resolved by removal — cortex 가 개발 중이라 collector endpoint list 에서 cortex-fe / cortex-be 제거 (commit `96cf758`, src/collector.rs:181). 재가동 시 다시 활성화. 누적 unacked alert 2 row (`acked_by='cortex-removed-from-collector-2026-05-26'`) ack 처리.

## 관련 문서

- [D-matrix-1](/ops/decisions) — Rust + native MCP 채택 결정
- [/ops/backlog](/ops/backlog) — `B-matrix-*` 시리즈 (deploy, blueprint connector, console retire, rebuild, git init, auth enforce, collector port fix)
- [/architecture/secrets](/architecture/secrets) — matrix `.env.local` 3 secrets
- [/architecture/artifacts](/architecture/artifacts) — `matrix.health@1.0` schema 노출
- [/services/blueprint](/services/blueprint) — matrix MCP 의 client

---

<!-- PAGE https://docs.axelabs.ai/services/nemotron-personas -->

# Nemotron Personas

> 1M+ 합성 페르소나 풀 MCP — 마케팅 / UX / 사용자 모델링 입력. realchoice 측 기존 자산 (D-nemotron-1, placeholder).

URL: https://docs.axelabs.ai/services/nemotron-personas

# Nemotron Personas

**한 줄 소개**: NVIDIA Nemotron-Personas 데이터셋 기반 페르소나 풀 MCP. magnet / Blueprint agent / UX research 입력으로 활용. 본 페이지는 D-nemotron-1 신설 후 placeholder — 라이선스 / 자료 origin 확정 후 본격 보강 예정.

> ⚠️ **Placeholder (2026-05-23)**: 트루비아 측 보고서 (2026-05-23 RE^2) 의 Q5 confirm 후속. 라이선스 / 자료 origin / cross-customer 사용 가능 범위 회신 받는 즉시 (D+14, 2026-06-15) 본문 본격 작성. 본 페이지 현재 노출은 카탈로그 가시성 확보 + 향후 채울 항목 명시 목적.

## 정체성

> magnet 이 *외부 채널* 을 다루면, nemotron-personas 는 *외부 사람* 의 합성 모델을 제공한다.

대규모 합성 페르소나 (1M+, 직업·연령·취향·구매 행동) 를 MCP 로 노출해서 agent 가 "이 페르소나가 보면 어떻게 반응?" 같은 시뮬레이션을 query 가능하게.

## 기술 스택 (현재 파악)

| 항목 | 값 (잠정) |
|---|---|
| 컨테이너 | Docker SSE :8771 |
| 운영 위치 | realchoice macmini (트루비아 측 기존 자산) |
| 소스 | NVIDIA Nemotron-Personas 데이터셋 |
| 라이선스 | **확인 필요** (D+14 회신 대기) |

## MCP Tools (현재 파악)

```
personas_get               단일 페르소나 조회 (id)
personas_list_datasets     사용 가능 dataset 목록
personas_list_segments     segment / cohort 목록
personas_register_segment  custom segment 등록
personas_search            조건 검색 (filter + limit)
```

세부 tool signature + sample 응답은 D+14 후속 보강.

## 통합 지점

| Consumer | 용도 |
|---|---|
| magnet | 광고 카피 / 크리에이티브 검증 — "이 페르소나가 보면 click 할 가능성" |
| Blueprint agent SDK | UX research 시뮬레이션 / 가상 사용자 인터뷰 |
| 향후 cross-customer | axe customer 가 SaaS 도입 시 동일 풀 공유 가능 여부 (라이선스 의존) |

## 라이선스 / cross-customer 사용 — **확인 필요 (D+14)**

다음 항목 트루비아 측에서 D+14 까지 회신 약속:

1. NVIDIA Nemotron-Personas 데이터셋 라이선스 범위 (commercial / non-commercial / specific use case)
2. 트루비아 외 customer (axe 등) 가 동일 데이터 사용 가능 여부
3. 데이터셋 갱신 주기 / origin 변경 시 sync 방법
4. AXE Labs platform 카탈로그 등재가 라이선스 위배 가능성

회신 후:
- 라이선스 cross-customer OK → 카탈로그 공식 등재 + Blueprint MCP registry 추가
- cross-customer X → realchoice 전용 service 로 markaa (`customers.realchoice.private_services[]`)

## 환경 변수

(D+14 회신 후 본격 등재)

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| 라이선스 미확인 상태에서 cross-customer 사용 | NVIDIA 라이선스 위배 risk | D+14 라이선스 회신 대기 |
| docs 미등재 + 운영자 모르는 사이 production 의존 | sudden incident 시 운영자 대응 불가 | 본 placeholder 등재로 가시성 확보 |

## 다음

- [트루비아 측 D+14 회신](https://docs.axelabs.ai/ops/known-gaps) — 라이선스 / origin 확정 후 본 페이지 본격 보강
- [B-nemotron-catalog-promote](https://docs.axelabs.ai/ops/backlog) — 본격 카탈로그 등재 작업 (라이선스 OK 시)

---

<!-- PAGE https://docs.axelabs.ai/services/stream -->

# Stream

> S&OP 통합 MCP — sales, inventory, settlement. 22개 도구, Postgres 16 SSOT.

URL: https://docs.axelabs.ai/services/stream

# Stream

**한 줄 소개**: Sales · Operations · Settlement 통합 MCP. 매출·재고·정산·환불의 전체 흐름을 책임짐. realchoice (truvia) 운영의 SSOT. 28개 MCP 도구.

## 정체성

> "주문이 들어와 재고가 나가고 매출이 정산되고 환불이 처리되는 모든 *흐름* 을 책임지는 MCP."

3 가지 의미:
1. **stream of data** — 매출·재고·정산·물류·발주 데이터의 흐름
2. **cash flow stream** — 들어오는 매출 → 나가는 발주·정산·환불
3. **magnet(당기다) ↔ stream(흐르다)** — 마케팅이 수요를 당기면 운영이 공급을 흐르게 함

## 기술 스택

| 항목 | 값 |
|---|---|
| 언어 | Python 3.12 |
| 프레임워크 | FastMCP (stdio + SSE) 1.27.1 |
| DB | PostgreSQL 16 (`truvia_ssot`, host port 5433) |
| DB driver | psycopg v3.2+ |
| Scheduler | supercronic v0.2.29 (Docker 내) |
| Slack | slack-bolt 1.28, slack-sdk 3.41 (Socket Mode) |
| Crypto | cryptography 48.0 (pgp_sym_encrypt vault) |
| API 클라이언트 | google-api-python-client, anthropic |

## 포트

| 포트 | 용도 |
|---|---|
| 8780 | MCP HTTP/SSE (`stream-mcp`) |
| 5433 → 5432 | PostgreSQL (`truvia-ssot-db`, internal alias `db`) |

## Docker Compose (3 service)

```yaml
services:
  stream-mcp:
    image: stream:latest
    ports: ["127.0.0.1:8780:8780"]
    command: python -m stream_mcp.server
    # FastMCP SSE 서버 (22개 도구)

  stream-data-ops:
    image: stream:latest
    command: python data_ops/supervisor.py
    # Slack Bolt Socket Mode 슈퍼바이저 (outbound only)

  stream-cron:
    image: stream:latest
    command: supercronic -overlapping /app/crontab
    # 6 cron task

networks:
  ssot:
    external: true                   # truvia-ssot_default 와 공유
```

3 service 모두 동일 image 공유 → 배포 단순화.

## 28 MCP Tools (prefix `stream_*`)

| Domain | Tools |
|---|---|
| **sales** (5) | `get_orders`, `get_revenue`, `top_products`, `refund_summary`, `forecast` |
| **inventory** (4) | `current`, `history`, `low_alerts`, `purchase_order_suggest` |
| **settlement** (3) | `lag`, `match`, `pending` |
| **health** (3) | `freshness`, `alerts`, `db_status` |
| **bridge** (2) | `ads_get_spend`, `ads_get_roas` (magnet adapter) |
| **signals** (3) | `emit_purchase_signal`, `emit_inventory_alert`, `signals_recent` |
| **admin** (7) | `list_tenants`, `tenant_get/create/update`, `api_key_create/rotate`, `unified_inventory` |
| **meta (1)** | `stream_unified_inventory` (자기진단) |

## 데이터 수집 (6 collectors)

매시 정각 (`hourly_collect.py`):

| 채널 | 모듈 | API |
|---|---|---|
| 쿠팡 | `data_ops/collectors/coupang.py` | OPEN API (발주서, 매출, 반품) |
| 네이버 커머스 | `data_ops/collectors/naver_commerce.py` | 주문 sync API |
| 네이버 검색광고 | `data_ops/collectors/naver_searchad.py` | (현재 미작동, magnet 으로 이전 예정) |
| Meta Ads | `data_ops/collectors/meta_ads.py` | Marketing API (캠페인, 일일 insights) |
| Magnet | `data_ops/collectors/magnet.py` | magnet 폴더 JSONL ingest |

## 데이터 모델 (핵심)

| 테이블 | 역할 |
|---|---|
| `orders` | 1주문 = 1행 (채널 native ID, 결제/배송/정산 시점) |
| `order_items` | 1주문 N라인 (SKU, 옵션, 수량, 금액) |
| `order_events` | 라이프사이클 상태 변경 로그 |
| `products` | 채널 노출 카탈로그 |
| `product_options` | 상품 옵션 |
| `inventory_supplies` | 내부 부자재 |
| `settlements` | 정산 raw data |
| `settle_cases` | 정산 정형화 |
| `settle_commissions` | 정산 수수료 |
| `vat_cases` | 부가세 |
| `raw_channel_payloads` | API 원본 영구 보존 (180일 retention) |
| `ad_spend_daily` | 광고비 일일 (magnet owner, stream read mirror) |
| `secrets` | Vault (pgp_sym_encrypt + audit_log) |

### Materialized Views

- `v_order_lifecycle` — 1주문 6단계 (paid → recognized → settled) + lag
- `v_revenue_by_stage_monthly` — 월별 (결제·인식·정산 3 시점 비교)
- `v_settlement_lag_stats` — 정산 지연 분석
- `v_business_flow_monthly` — 종합 월간
- `v_data_freshness` — 채널별 데이터 최신성

## Magnet 신호 교환

3 채널 양방향:

| 신호 | 발신자 | 수신자 | 채널 |
|---|---|---|---|
| `purchase_signal` | stream `emit_purchase_signal` | Meta CAPI | `data/signals/&lt;channel&gt;-YYYY-MM.jsonl` + Meta API |
| `inventory_alert` | stream `emit_inventory_alert` | magnet (광고 일시정지) | JSONL + pg_notify |
| `ad_spend_mirror` | magnet `ad_spend_daily` | stream read mirror | DB direct (magnet_client.py) |

## Crontab (6 task)

| 주기 | 작업 |
|---|---|
| 매시 정각 | `hourly_collect.py` — 6개 collector |
| 매 5분 | `watchdog.sh` — Slack 봇 BrokenPipe 감지 |
| 매 30분 | `health_check.sh` — freshness 점검 |
| 매일 09:10 | `magnet_alerts.py` — daily summary + ROAS alert |
| 매일 00:05 | `logrotate.sh` |
| 매주 일요일 04:30 | `retention.py --days 180 --vacuum` |

## 환경 변수

```bash
# DB
STREAM_DB_HOST=db
STREAM_DB_PORT=5432
STREAM_DB_NAME=truvia_ssot
STREAM_DB_USER=agent11
STREAM_DB_PASSWORD=

# Secrets vault
TRUVIA_SECRETS_MASTER_KEY=                # pgp_sym_encrypt master

# MCP
STREAM_TRANSPORT=sse
STREAM_HTTP_HOST=0.0.0.0
STREAM_HTTP_PORT=8780

# Slack
DATA_OPS_SLACK_BOT_TOKEN=
DATA_OPS_CHANNEL=#data-ops

# Magnet adapter
MAGNET_REPO_ROOT=/Users/realchoice/magnet

# Signals
STREAM_SIGNALS_DIR=/Users/realchoice/stream/data/signals
```

env file 위치: `~/.config/truvia/stream.env` (host 저장, chat transcript 영역 외, .gitignore 외부).

## 외부 의존성

| 시스템 | 통합 |
|---|---|
| PostgreSQL 16 truvia_ssot | data SoT (read/write) |
| Slack workspace | Bolt Socket Mode + #data-ops alert |
| 쿠팡 OPEN API | 발주서, 매출, 반품·교환 |
| 네이버 커머스 API | 주문 sync |
| Meta Ads Manager | 캠페인, insights |
| Meta CAPI | purchase event emit |
| Google Sheets API | 자동 export |
| magnet MCP | ad_spend mirror, signal receiver |

## 운영 노트

- **GitHub repo**: `soohunkang/stream` (private)
- **이전 4 MCP → 통합** (2026-05-11 stream + magnet)
- **LaunchAgent 8종 archived** — Docker Compose 라운드 7 수렴
- **Multi-tenant scaffold** 준비 (`_set_tenant_context()`, schema-multi-tenant.sql)

## 관련 문서

- [Magnet service](/services/magnet) — 마케팅 자동화, 신호 발신자
- [/Users/axe/stream/docs/](https://github.com/soohunkang/stream/tree/main/docs) — 16개 운영 문서

---

<!-- PAGE https://docs.axelabs.ai/services/ui -->

# UI (디자인 시스템)

> axelabs 플랫폼이 공유하는 토큰·컴포넌트·layout chrome SSOT. design.axelabs.ai 에서 라이브 데모.

URL: https://docs.axelabs.ai/services/ui

# UI

**한 줄 소개**: axelabs 플랫폼 (메인 사이트 · docs · cortex · frame · hive · matrix · blueprint) 이 공통으로 쓰는 **디자인 시스템 SSOT** — 토큰 (color/spacing/typography) + 40+ React 컴포넌트 + `.axe-app-shell` 통합 layout chrome ([D-ui-1](/ops/decisions)). 외부 데모 = [design.axelabs.ai](https://design.axelabs.ai) (구 `ui.axelabs.ai` → [D-ui-3](/ops/decisions) 에서 rename·폐기).

## 도메인

| URL | 용도 |
|---|---|
| https://design.axelabs.ai | 디자인 시스템 라이브 사이트 (variant 토글 + 본문 + 데모 모두 한 페이지에 통합) |
| `localhost:3902/design` | 운영자 로컬 dev preview (port 3902 — :3900 은 docker production 점유) |

`design.axelabs.ai` 의 sub-path 는 root 로 308 redirect (단일 페이지 통합 — 운영자 결정 2026-05-29).
메인 `axelabs.ai/design/*` 는 404 차단 (디자인 시스템 surface 는 `design.axelabs.ai` 단일 host).
구 `ui.axelabs.ai` 는 [D-ui-3](/ops/decisions) 에서 완전 폐기 — tunnel ingress 제거로 catch-all 404.

## 기술 스택

| 항목 | 값 |
|---|---|
| 패키지 이름 | `@axe/ui` |
| 위치 (SSOT) | `/Users/axe/axelabs/src/lib/` |
| 프레임워크 | Next.js 16 (App Router) + React 19 |
| 호스팅 | axelabs.ai 와 동일 Next.js 컨테이너 (multi-domain rewrite, [D-ui-1](/ops/decisions)) |
| 토큰 | CSS 변수 — `tokens/{colors,typography,spacing,fonts}.css` |
| 컴포넌트 | 40+ React (.tsx) + 14 CSS 그룹 (`styles/*.css`) |
| Layout chrome | `.axe-app-shell` + variant (`data-shell="docs|dashboard|landing"`) — Phase 15 |
| 다크모드 | `data-theme="dark"` + `.dark/.light` 동시 set (next-themes 호환) |
| 폰트 | Pretendard (본문) + Sarasa Fixed K (mono) + Clash Display (옵션 display) |

## 배포 모델 (D-ui-1 · 도메인 D-ui-3)

design.axelabs.ai 는 **별도 컨테이너가 아닙니다**. axelabs.ai (회사 홈) 와 같은 Next.js standalone 컨테이너가 host header 를 보고 분기:

- `Host: axelabs.ai` 또는 `www.axelabs.ai` → 메인 사이트
- `Host: design.axelabs.ai` → root 를 `/design` 으로 rewrite (`proxy.ts`, host 분기 — [D-ui-3](/ops/decisions))

분기 메커니즘은 `next.config.mjs` 의 `rewrites()` 가 아니라 **`proxy.ts`** (Next.js 16 convention, 구 middleware.ts) 다 — 정적 prerender 된 `/` 에는 `next.config` rewrites 가 안 걸리는 함정 때문 (proxy 는 항상 runtime).

`axelabs.ai/design` 으로 직접 접근도 살아있음 — dev/preview + canary 용도.

이유: 디자인 시스템 코드가 본 레포에 살고, build 산출물 공유가 자연스러움. 단일 docker compose 운영 단순.

> **tunnel ingress 변경은 로컬 `config.yml` 이 아님** — `axelabs-tunnel` 은 Cloudflare remote-managed (source=cloudflare, version-tracked). ingress 추가/변경/삭제는 `PUT /accounts/<acct>/cfd_tunnel/<uuid>/configurations` (token = vault `Cloudflare API - axelabs`). 상세 = [known-gaps Cortex 7함정 #7](/ops/known-gaps).

## Chrome variants

| Variant | 형태 | 사용처 |
|---|---|---|
| `docs` | TopNav + Sidebar + Content (80ch) + TOC + Footer | docs.axelabs.ai, 가이드 페이지 |
| `dashboard` | TopNav + Sidebar + Content (1280px) + Footer | cortex / frame admin / blueprint workspace |
| `landing` | TopNav + Content (full width) + Footer | axelabs.ai 메인, 마케팅 페이지 |

CSS 변수 (variant 별 width):

| 변수 | 기본값 |
|---|---|
| `--app-shell-sidebar-w` | 240px |
| `--app-shell-toc-w` | 220px |
| `--app-shell-gutter` | `var(--space-6)` (32px) |
| `--app-shell-topbar-h` | 56px |

## Layout primitives + ThemeToggle (Phase 16)

Chrome 가 페이지 macro 골격이라면, **primitives 는 그 안의 micro 레이아웃** — `display:flex`/`grid` + gap 을 매번 inline style 로 재발명하던 것을 SSOT 클래스로 흡수 ([D-ui-2](/ops/decisions)). Chrome 과 동일하게 styling 은 100% CSS 클래스 → React 아닌 소비자 (cortex maud, jinja) 도 같은 markup 재사용.

| 컴포넌트 | CSS 클래스 | 역할 | 주요 prop |
|---|---|---|---|
| `Stack` | `.axe-stack` | 세로 flex + gap | `gap` 0–10 (기본 4) · `align` · `as` |
| `Cluster` | `.axe-cluster` | 가로 flex + wrap + gap (toolbar/액션 줄) | `gap` 0–10 (기본 3) · `align`(기본 center) · `justify` · `nowrap` · `as` |
| `Grid` | `.axe-grid` | 반응형 grid | `cols` 1–6 (기본 3) · `gap` 0–6 (기본 4) · `auto`+`min` · `responsive` |
| `Container` | `.axe-container` | max-width 중앙 + gutter | `size` sm/md/lg/xl/full (기본 lg) · `as` |
| `ThemeToggle` | `.axe-theme-toggle` | light/system/dark 전환 | `mode` segment\|cycle (기본 segment) · `size` |

- **gap 은 spacing scale 와 1:1** — `gap={4}` → `var(--space-4)`. 매직 px 금지.
- **`Grid auto`** — `min` (기본 15rem) 이하로 안 줄게 `auto-fill` wrap. cortex 의 `.cortex-metric-grid` 재발명 대체.
- **`ThemeToggle`** 은 `useTheme` 위 thin UI — DOM/storage 반영을 `ThemeProvider` 에 위임 (이전 design 페이지가 Provider 우회해 `document.documentElement` 를 직접 만지던 버그 제거). 아이콘은 inline SVG (외부 dep 0).

CSS-only 소비자는 동일 클래스를 직접 쓴다:

```html
<div class="axe-stack axe-stack--gap-4">
  <div class="axe-cluster axe-cluster--gap-2 axe-cluster--justify-between">…</div>
  <div class="axe-grid axe-grid--auto axe-grid--gap-3" style="--axe-grid-min: 220px">…</div>
</div>
```

채택 (2026-05-29 브라우저 검증): `app/page.tsx` (axelabs.ai 홈 — Hero/Section/Footer 컴포지트 + Stack/Cluster/Grid) · `app/matrix` (MatrixNav ThemeToggle + page 전체 레이아웃) · `app/design` (design.axelabs.ai 본 페이지). cortex/docs/blueprint 는 순차 적용 대기.

## 문서 템플릿 (Phase 17)

Chrome·primitives 가 **화면** 레이아웃이라면, 문서 템플릿은 **인쇄물** — AXE 가 외부로 발신하는 문서 (IC Memo · LP 서한 등) 를 `.axe-doc` CSS-class HTML 로 통일 ([D-ui-3](/ops/decisions)). 화면 컴포넌트와 동일하게 styling 100% CSS 클래스 → React 쇼케이스와 jinja2 렌더가 **같은 markup** 을 공유.

| 템플릿 | 위치 | 용도 |
|---|---|---|
| IC Memo | `src/lib/templates/documents/ic-memo.html.jinja` | 투자심의 메모 — 권고 callout + deal/returns KPI + 번호 섹션 + 리스크/표결 표 + 서명 |
| LP 서한 | `src/lib/templates/documents/lp-letter.html.jinja` | 출자자 서한 — 분기(quarterly)/수시(adhoc) 분기 + NAV KPI + 서명 |
| 스타일 SSOT | `src/lib/styles/document.css` | `.axe-doc*` 전 클래스 (`components.css` 가 @import → globals 경유 전역 로드) |

**가로·세로 모두 지원** (문서 성격별 고정 X — 운영자 결정): `.axe-doc--portrait` (A4 210×297mm) / `.axe-doc--landscape` (297×210mm). landscape 본문엔 `.axe-doc__cols` (2단) 적용 가능.

| 측면 | 방식 |
|---|---|
| 단위 | `pt` (화면·인쇄 일관) |
| 페이지 | named `@page axe-doc-portrait` / `axe-doc-landscape` + `.axe-doc` 의 `page:` 속성으로 선택 — **전역 bare `@page` 금지** (사이트 전 페이지에 A4 누수) |
| 테마 | `.axe-doc` 가 자체 `--doc-*` 팔레트 정의 → light/dark 무관 동일 (흰 종이·따뜻한 잉크) |
| 인쇄 | `@media print` 가 stage·toolbar 숨김 + box-shadow 제거 + `print-color-adjust:exact` |

### 렌더 파이프라인 (기존 md-to-pdf 재사용)

병렬 렌더러 신설 X — 기존 마크다운→PDF 파이프라인에 끼움:

1. **본문 (markdown → HTML)** — pandoc 가 narrative 를 HTML 로 (md-to-pdf skill). 결과를 jinja 컨텍스트의 `memo.body_html` / `letter.body_html` 슬롯에 `safe` 필터로 주입.
2. **wrapper (jinja → HTML)** — `.axe-doc` chrome (masthead·meta·KPI·callout·표·서명) 으로 본문을 감쌈. CSS 는 `axe_css` (inline, production 권장) 또는 `css_href` (dev `<link>`).
3. **HTML → PDF** — `chromium --headless --print-to-pdf` (md-to-pdf skill `render.sh` 와 **동일 엔진**). orientation 클래스가 named `@page` 를 선택.
4. **품질 게이트** — ic skill `check_pdf_quality.py` 로 검증.

### 쇼케이스

[design.axelabs.ai](https://design.axelabs.ai) `§ 문서 템플릿` 에 라이브 데모 — IC Memo ↔ LP 서한 · 세로 ↔ 가로 · zoom 토글 + "인쇄·PDF" 버튼 (현재 문서 노드만 새 창에 복제해 `window.print()` → AppShell chrome 없는 깨끗한 PDF). 컨텍스트 스키마는 각 `.jinja` 파일 상단 주석 참조.

## Multi-stack

React 가 아닌 stack (cortex 의 Rust+maud 등) 도 동일 markup 으로 동일 chrome:

```html
<div class="axe-app-shell" data-shell="dashboard">
  <div class="axe-app-shell__topbar">
    <nav class="axe-topnav">…</nav>
  </div>
  <div class="axe-app-shell__main">
    <aside class="axe-app-shell__sidebar"><nav class="axe-sidebar">…</nav></aside>
    <main  class="axe-app-shell__content">…</main>
  </div>
  <div class="axe-app-shell__footer">
    <footer class="axe-footer">…</footer>
  </div>
</div>
```

cortex 의 `scripts/sync-axe-ui.sh` 가 `layout.css` 를 bundle 에 포함시키도록 갱신하면 즉시 채택 가능. 가이드 = `/Users/axe/cortex/CLAUDE.md` (D-cortex-design-axe-ui).

## 소비자 (현재 + 예정)

| 서비스 | 현재 chrome | 목표 variant | 상태 |
|---|---|---|---|
| axelabs.ai (메인) | TopNav + Hero/Section/Footer + Stack/Cluster/Grid | `landing` | 채택 (2026-05-29 dogfood) |
| docs.axelabs.ai | Nextra theme | `docs` (slot override) | 대기 (C2 — Nextra navbar/sidebar 슬롯에 axe 컴포넌트 끼움) |
| cortex | TopNav-only (maud) | `dashboard` | 다음 (`scripts/sync-axe-ui.sh` + `page()` 갱신) |
| frame · hive · matrix | — | `dashboard` | 대기 (신규 admin UI 시작 시) |
| Blueprint | 자체 | `dashboard` | 대기 (기존 chrome 분리 후) |

## 환경 변수

본 서비스는 별도 환경 변수 없음. axelabs.ai 와 동일 컨테이너 + 정적 자원.

## 함정

- **`:3900` dev 띄우기** — docker production container 가 점유 중. 로컬 dev 는 `npx next dev --port 3902` ([reference](/onboard/troubleshooting)) 또는 `.claude/launch.json` 의 `axe-ui-design-preview` 항목 사용.
- **host header rewrite 검증** — `axelabs.ai/design` (404 차단) 와 `design.axelabs.ai` (200, /design 서빙) 가 같게 동작하면 host 분기 실패. cloudflared 의 `httpHostHeader` override 없이 default (preserve) 사용 가정. 컨테이너 직접 검증: `curl -H 'Host: design.axelabs.ai' http://127.0.0.1:3900/` → 200, `curl -H 'Host: axelabs.ai' http://127.0.0.1:3900/design` → 404.
- **신규 1-level 호스트는 IPv6-only 로 잠깐 보일 수 있음** — 새 `design.axelabs.ai` 직후 로컬 resolver 가 AAAA(Cloudflare IPv6 edge)만 반환 → IPv6 무라우팅 머신에서 `curl` 이 `No route to host` (HTTP 000). production 문제 아님. `curl -4` 또는 `--resolve design.axelabs.ai:443:104.21.66.67` 로 IPv4 edge 검증.

---

<!-- PAGE https://docs.axelabs.ai/services/vaultwarden -->

# Vaultwarden (AXE vault)

> AXE 플랫폼의 Tier-1 비밀 저장소 — Timshel fork (axe.2/axe.3 patch) + Microsoft Entra SSO + Caddy sub-path. customers.yaml secrets[] → vault → axe secret pull.

URL: https://docs.axelabs.ai/services/vaultwarden

# Vaultwarden (AXE vault)

AXE 플랫폼의 **모든 서비스 비밀의 canonical store** ([D-ops-9](/ops/decisions)). frame · hive · blueprint · stream · magnet 의 DB password · OAuth client_secret · JWT signing key · 외부 API token 이 전부 여기에 산다. 서비스 컨테이너는 vault 를 직접 모르고, `axe ship` / `axe secret pull` 이 **배포 직전** vault → `env_file` 로 동기화한 뒤 docker compose 가 그 파일을 읽는다 ([D-ops-17](/ops/decisions), runtime vault 호출 없음).

동시에 Microsoft Entra ID **OIDC RP** 로서 직원이 SSO 로 로그인하는 password manager 이기도 하다 — 즉 **운영자용 secret CLI 백엔드** + **직원용 password vault** 두 역할을 한 인스턴스가 겸한다.

> 본 페이지는 서비스 *정의* (image · compose · env · org 모델 · 비밀 흐름). 직원 setup 절차는 [/onboard/vault-setup](/onboard/vault-setup), 운영자 비밀 매니페스트 흐름은 [/architecture/secrets](/architecture/secrets), 기존 vault 보유 customer 통합은 [/partner/deploy § Vault OIDC SSO 통합](/partner/deploy#vault-oidc-sso-통합--기존-vaultwarden-운영-중인-customer-용) 를 참조.

## 한눈에

| 항목 | 값 |
|---|---|
| 역할 | Tier-1 secret store + 직원 password vault (OIDC RP) |
| image | `ghcr.io/axelabs-ai/vault` — Timshel fork + axe.2/axe.3 patch (아래 § 이미지) |
| 노출 | `127.0.0.1:8222` (HTTPS, Caddy) — 외부는 cloudflared 가 `https://axe.axelabs.ai/vault` 로 |
| 컨테이너 | `axe-vaultwarden` (core) + `axe-vault-caddy` (front, :443) |
| 위치 | `/Users/axe/.axe/vault/` (operator macmini) |
| SSO | Microsoft Entra ID (Azure AD), single-tenant `@axellc.com` |
| 비밀 SoT | 자기 자신 — `bootstrap_only: true` (vault 가 자기 OAuth secret 못 읽음, chicken-and-egg) |
| 결정 | [D-ops-9](/ops/decisions) · [D-ops-10](/ops/decisions) · [D-ops-17](/ops/decisions) · [D-ops-37](/ops/decisions) · [D-ops-40](/ops/decisions) |

## 이미지 — Timshel fork + axe.2 / axe.3 patch

upstream Vaultwarden (dani-garcia) 가 아니라 **Timshel fork** (native SSO 지원) 을 base 로, AXE 가 자체 patch 를 얹어 `ghcr.io/axelabs-ai/vault` 로 빌드한다 ([D-ops-37](/ops/decisions) — fork build, [D-ops-40](/ops/decisions) — axe.3 release).

- **base**: Timshel `1.34.1-6` (commit `80439605`, 2025-07-15)
- **axe.2 patch** (Bitwarden client ≥ 2026.4 unlock 호환, dani-garcia mainline 에서 backport):
  1. `/accounts/prelogin/password` alias 추가 — 신 client 가 prelogin 을 password-only sub-endpoint 로 분리하는데 Timshel 은 legacy `/accounts/prelogin` 만 노출 → 404 → 로그인 실패
  2. `/identity/connect/token` 에 `AccountKeys` / `MasterPasswordUnlock` wrapped-variant 필드 backport — 없으면 unlock 시 `Cannot read properties of null (reading toWrappedAccountCryptographicState)`
- **axe.3 patch** (org permission quirk, 자체 진단):
  3. `src/api/core/organizations.rs` 3곳의 `if member.access_all { continue; }` skip 제거 — Owner 는 `access_all=true` 라 explicit `users_collections` row 가 안 생겨 downstream permission 체크 (cipher delete) 가 깨졌음
  4. `Cipher::to_json` 에 `cipher.permissions {response, delete, restore}` 필드 backport — client ≥ 2026.4 가 delete/restore 를 이 필드로 gate. `can_delete` = collection manage flag OR org Owner/Admin

> **axe.2 = KDF cutoff**. axe.2 release (2026-05-26) **이전** 가입 user 는 옛 schema (`client_kdf_type=0`, PBKDF2) 라 SSO→MP unlock 이 `toWrappedAccountCryptographicState` 에러로 막혀 **KDF rotation (PBKDF2 → Argon2id)** 이 필요하다 ([D-ops-40](/ops/decisions) runbook, axe-side 4명 ai/soohun/taehun/jinwoo). axe.2 **이후** 신규 가입 user (realchoice 측 등) 는 새 schema 로 가입돼 rotation 불필요. 상세 = [/onboard/vault-setup § KDF rotation](/onboard/vault-setup).

### pin / rollback

| | tag / digest |
|---|---|
| **현재 (manifest list, multi-arch)** | `ghcr.io/axelabs-ai/vault:1.34.1-6-axe.3` @ `sha256:a26208a0...55aeada` |
| compose 의 실제 pin | digest 직접 (`image: ghcr.io/axelabs-ai/vault@sha256:a26208a0...`) — tag 가 아닌 digest 고정 |
| arm64 (axe-macmini 유효) | `sha256:d97a6ed6...d4016` |
| amd64 | `sha256:402eeac9...58572a` |
| rollback (axe.2) | local tag `axelabs-ai/vault:1.34.1-6-axe.2`, ImageID `sha256:11536845...858af9` |

- **source build**: `axelabs-ai/vault` repo 의 `build/build.sh` + `.github/workflows/build.yml` (GHA, buildx multi-arch linux/amd64 + linux/arm64), commit `799015b`.
- **GHCR auth**: `ghcr.io/axelabs-ai/vault` 는 **private**. pull PAT 는 vault 의 `Platform — Service Secrets / ghcr-axelabs-ai-pull-pat` 에 보관 (값은 vault 안). docker login:
  ```bash
  bw get password ghcr-axelabs-ai-pull-pat | docker login ghcr.io -u axe-labs-ai --password-stdin
  ```
- **upstream PR (저우선)**: axe.3 patch 3+4 를 Timshel 에 제출 — accept 되면 자체 diff 소멸.

## compose / 포트

`/Users/axe/.axe/vault/docker-compose.yml` — 2 컨테이너:

| 컨테이너 | image | 노출 | 역할 |
|---|---|---|---|
| `axe-vaultwarden` | `ghcr.io/axelabs-ai/vault@sha256:...` | `expose: 80` (host 직노출 X) | Vaultwarden core (API + SSO RP) |
| `axe-vault-caddy` | `caddy:2-alpine` | `127.0.0.1:8222 → 443` | TLS 종단 + `/vault` sub-path redirect |

- core 는 host 포트를 안 받는다 — `expose: "80"` 만 (컨테이너 네트워크 내부). Caddy 가 유일한 진입점.
- Caddy 는 **127.0.0.1 에만 바인딩** (`127.0.0.1:8222:443`) — Tailnet/공개 노출 X. bw CLI (운영자 mac) 가 mkcert 로컬 인증서로 신뢰, 외부 직원은 cloudflared 터널 origin 으로만 닿는다.
- volume: core 는 `./data:/data` (sqlite + attachments), Caddy 는 named volume 2개.

### Caddy — sub-path 호스팅 함정

`/Users/axe/.axe/vault/Caddyfile` 는 `:443` 에서 **모든 hostname** 을 받는다 (localhost = bw CLI mkcert cert, `axe.axelabs.ai` = cloudflared origin, Host 보존). Vaultwarden 은 `DOMAIN` env 가 canonical URL 을 가리키는 한 Host mismatch 를 무시한다.

핵심은 **trailing-slash redirect**:

```caddyfile
@vault_no_slash { path /vault }
redir @vault_no_slash /vault/ permanent
reverse_proxy axe-vaultwarden:80
```

Vaultwarden SPA 의 HTML 은 **상대 asset 경로** (`images/...`, `app/main.js`) 를 쓴다. 사용자가 trailing slash 없는 `/vault` 로 들어오면 브라우저가 `vault` 를 파일로 보고 root 로 올라가 `/app/main.js` 를 요청 → cloudflared 가 default ingress (blueprint:3100) 로 보내 모든 static asset 이 502. `/vault/` 강제 301 로 base directory 를 `/vault/` 로 고정해야 한다. (customer 측 onboarding 함정 표에도 동일 항목 — [/architecture/secrets](/architecture/secrets).)

## 환경 변수

`axe-vaultwarden.environment` (값 일부는 `./.env`, mode 600, gitignored 에서 치환):

| env | 값 | 이유 / 결정 |
|---|---|---|
| `DOMAIN` | `https://axe.axelabs.ai/vault` | 외부 canonical URL ([D-ops-10](/ops/decisions)) |
| `SIGNUPS_ALLOWED` | `"true"` | SSO 통과 신규 user JIT provisioning ([D-ops-26](/ops/decisions)) |
| `SSO_ONLY` | `"false"` | master password emergency fallback 보존 — Entra 장애 시 운영자 lockout 방지 ([D-ops-27](/ops/decisions)) |
| `INVITATIONS_ALLOWED` | `"false"` | manual invitation 미사용 (JIT 통일) |
| `ORGANIZATION_INVITE_AUTO_ACCEPT` | `"true"` | 사용자측 "Accept invitation" 자동 — operator 의 "Confirm" (org key 암호화 전달) 은 여전히 필수 ([D-ops-27](/ops/decisions)) |
| `SHOW_PASSWORD_HINT` | `"false"` | — |
| `LOG_LEVEL` | `"info"` | SSO flow 이벤트 캡처용 (warn → info bump) |
| `SSO_ENABLED` | `"true"` | Microsoft Entra ID RP ([D-ops-10](/ops/decisions)) |
| `SSO_AUTHORITY` | `https://login.microsoftonline.com/${AZURE_TENANT_ID}/v2.0` | single-tenant → 외부 user SSO 통과 불가 |
| `SSO_CLIENT_ID` | `${AZURE_VAULTWARDEN_APP_ID}` | Entra app (Vaultwarden 전용 등록) |
| `SSO_CLIENT_SECRET` | `${AZURE_VAULTWARDEN_CLIENT_SECRET}` | **값은 vault 안** (아래 § 자기 자신 비밀) |
| `SSO_SCOPES` | `openid profile offline_access User.Read` | — |
| `SSO_SIGNUPS_MATCH_EMAIL` | `"true"` | 기존 user 와 email 매칭 |
| `SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION` | `"true"` | Entra id_token 에 `email_verified` claim 부재 — tenant 내부 검증 신원이라 허용. 없으면 첫 SSO 가 "Your provider does not send email verification status" 차단 ([D-ops-24](/ops/decisions)) |
| `SSO_AUTH_ONLY_NOT_SESSION` | `"true"` | SSO 는 인증만, session lifecycle 은 Vaultwarden 자체 (30일 idle). false 면 Entra refresh token 따라가 MP 입력 잦음. trade-off: Entra 측 비활성/제명이 server session 에 ≤30일 lag — AXE 4명 규모는 수동 즉시 offboarding 으로 OK ([D-ops-40](/ops/decisions)) |

> `${AZURE_TENANT_ID}` / `${AZURE_VAULTWARDEN_APP_ID}` / `${AZURE_VAULTWARDEN_CLIENT_SECRET}` 는 `/Users/axe/.axe/vault/.env` (mode 600) 에서 치환된다. customer macmini 의 같은 4-key 패치 (`SSO_ALLOW_UNKNOWN_EMAIL_VERIFICATION` / `SIGNUPS_ALLOWED` / `SSO_ONLY=false` / `ORGANIZATION_INVITE_AUTO_ACCEPT`) 는 `axe vault bootstrap {customer}` 가 in-place 적용 ([D-ops-33](/ops/decisions), [customer-onboarding D+1](/ops/runbook/customer-onboarding)).

## Organization 모델

비밀과 직원 password 는 **단일 AXE organization** 안에 산다 (org UUID `0c5d8bbd-ad85-42b4-8b8a-2849031981b1`, axe CLI `_AXE_VAULT_ORG_ID`, MCP catalog org 와 동일 UUID).

### dual-identity 계정 ([D-ops-29](/ops/decisions))

org 운영은 customer 당 두 종류 계정으로 나뉜다:

| identity | 용도 | 권한 |
|---|---|---|
| `ai@{customer-domain}` (axe 측 `ai@axellc.com`) | 자동화 / bot — Graph token 발행, proactive DM, agent run, **axe CLI 가 BW_SESSION 으로 쓰는 계정** | Owner + `access_all=1` |
| 실제 admin 직원 (예: soohun.kang) | 사람 작업 identity | Owner + `access_all=1` |

axe CLI 는 `ai@` 계정의 `BW_SESSION` (macOS Keychain `service=axe.vault.session`, `account=ai@axellc.com`) 으로 `bw` subprocess 를 돌린다. master password 는 **출근 시 1회** `bw unlock` 후 Keychain 에 cache (8h) — 이후 모든 `axe secret`/`axe vault` 명령이 재입력 없이 동작.

> ⚠️ "axe.2 / axe.3" 는 **org 계정 종류가 아니라 image patch release** 다 (위 § 이미지). org 계정 모델은 위 dual-identity (`ai@` bot + 사람 admin) 가 정답.

### Collection 구조 v1 ([D-ops-32](/ops/decisions))

| customer 형태 | collection |
|---|---|
| entity 1개 (예: realchoice) | 4-collection: `Platform — Service Secrets` (operator only) · `Platform — Infrastructure` (operator only) · `{Customer Entity}` (전직원 RW) · `Shared Tools` (전직원 RW) |
| entity 다수 (예: axe 의 axec/axev/axep) | 6-collection (entity별 분리) |

별도로 MCP connector 카탈로그용 `MCP Connectors` collection (`1a62e754-6e47-43e0-a99a-cf71c37b8638`) 이 있다 — `axe mcp publish` 가 connector 메타를 여기에 쓰고, 직원이 claude.ai 에 connector 추가 시 이 collection 에서 값을 본다 ([/onboard/claude-connectors](/onboard/claude-connectors), D-vault-mcp-catalog).

org REST 자동화는 axe CLI 가 bw-derived API token 으로 직접 호출한다 — `axe vault org-invite` (`POST /api/organizations/{org_id}/users/invite`), `axe secret prompt-store` (org collection 에 hidden-text item 생성, 값이 shell history/clipboard 에 안 남음).

## 비밀 흐름 — customers.yaml secrets[] → vault → axe secret pull

핵심 invariant: **서비스 코드는 vault 를 모른다.** `customers.yaml` 의 `services.<svc>.secrets[]` 매니페스트가 env-var ↔ vault-item 매핑의 SSOT 이고, `axe secret` 명령들이 그 사이를 잇는다.

```
customers.yaml                         Vaultwarden (org)              service env_file
services.<svc>.secrets[]               ai@ 계정, bw CLI               <svc>/.env (mode 600)
  - env: FRAME_DB_PASSWORD    ──push──▶  item "frame/axe/db-password"  ──pull──▶ FRAME_DB_PASSWORD=...
    vault: frame/axe/db-password         (password 필드)                          (docker compose env_file)
```

| 명령 | 동작 |
|---|---|
| `axe secret push <ENV> --service <svc> [--customer C]` | 매니페스트로 vault 경로 lookup → 신규 item 생성 or password 필드 갱신. 대형/PEM 비밀은 `--value-stdin` (값이 argv/ps 에 안 뜸) |
| `axe secret pull <svc> [--customer C]` | 매니페스트의 각 `secrets[]` 를 `bw get` → `env_file` 에 **merge** (manifest 키만 덮어쓰고 나머지 config·comment·hand-edit 라인은 보존). 따옴표 없이 raw single-line 으로 write (env_file 은 literal-quote) |
| `axe secret check <svc>` | 매니페스트 vs vault 보유 비교 → 누락 출력. `axe ship` 가 배포 gate 로 사용 |
| `axe secret send <ENV> --service <svc> [--to R]` | vault GET → `bw send` 1회용 링크 (기본 `-d 1 -a 1 --hidden`) → URL stdout. 사람 전달 전용 (직원에게 client_secret 줄 때) |
| `axe secret rotate <ENV> --service <svc>` | 새 값 (외부 provider 입력 or 자동 생성) → vault PUT → pull → ship 트리거 |
| `axe secret get <ENV> [-n]` / `axe secret list` | 단건 조회 / 전체 item 표 (list 는 값 출력 X) |

vault item 네이밍 컨벤션: `<service>/<customer>/<short>` (예: `frame/axe/db-password`, `blueprint/realchoice/azure-client-secret`). 상세 + 전체 매니페스트 (현재 42개 비밀 등재) = [/architecture/secrets](/architecture/secrets).

### 자기 자신 비밀 — bootstrap_only

vault 의 자기 OAuth client_secret (`AZURE_VAULTWARDEN_CLIENT_SECRET`) 은 **vault 자신이 자기를 못 읽는다** (vault 가 부팅돼야 secret 을 줄 수 있는데, 부팅에 그 secret 이 필요한 chicken-and-egg). 그래서 `customers.yaml` 에서 vaultwarden service 는 `bootstrap_only: true` — `axe secret check`/`pull` 이 skip 하고, `/Users/axe/.axe/vault/.env` 가 직접 그 값을 들고 있다 (vault 매니페스트엔 "manually maintained — vault is the SoT but can't read itself" 주석).

> 즉 vaultwarden 의 SSO secret 1개만 매니페스트상 self-referential 예외이고, 나머지 모든 서비스 비밀은 정상 push/pull 경로를 탄다.

## 백업

vault 의 `./data` (sqlite + attachments) 는 AXE 3-tier backup (local + ring + cold SSD, restic) 에 포함된다. 복구 절차는 vault master password 로 `axe-vaultwarden` 잠금 해제 후 data 복원 — 상세 = [/architecture/backup](/architecture/backup).

## 함정

| 함정 | 결과 | 회피 |
|---|---|---|
| Caddyfile `/vault` no trailing slash | SPA 상대 asset 이 root 옆 resolve → asset 502/503 | `/vault` → `/vault/` permanent redirect (Caddyfile 기본 적용) |
| Timshel image `wget`/`curl` 가정 오류 | compose healthcheck 실패 → unhealthy 무한 루프 | image 에 실제 존재하는 바이너리로 healthcheck (Timshel 은 `wget` 없음 → `curl`) |
| bw CLI 2026.4+ ↔ Timshel SSO 호환 | unlock 시 `TypeError: ... toWrappedAccountCryptographicState` | bw CLI **2025.7.0 pin** (`npm install -g @bitwarden/cli@2025.7.0`, [D-ops-28](/ops/decisions)) 또는 axe.2+ patch image |
| axe.2 이전 가입자 KDF | SSO→MP unlock 동일 에러 | KDF rotation PBKDF2 → Argon2id ([D-ops-40](/ops/decisions), [vault-setup](/onboard/vault-setup)) |
| `SSO_ONLY=true` 설정 | Entra 장애 시 운영자 lockout (MP 진입 불가) | `SSO_ONLY: "false"` 유지 ([D-ops-27](/ops/decisions)) |
| `SIGNUPS_ALLOWED=false` + `INVITATIONS_ALLOWED=false` | 첫 employee JIT 가입 "Failed to retrieve the invitation" | `SIGNUPS_ALLOWED: "true"` ([D-ops-26](/ops/decisions)) |
| `docker compose restart` 만 함 | env 변경 미반영 (restart 는 env reload 안 함) | `docker compose up -d --force-recreate axe-vaultwarden` |
| `ghcr.io/axelabs-ai/vault` private pull 실패 | image pull `denied` | `ghcr-axelabs-ai-pull-pat` 로 `docker login ghcr.io` 선행 |

## 참고

- 운영자 비밀 매니페스트 + axe secret 명령: [/architecture/secrets](/architecture/secrets) ([D-ops-17](/ops/decisions))
- 직원 vault setup (SSO/KDF/3-client): [/onboard/vault-setup](/onboard/vault-setup)
- 기존 vault 보유 customer 통합: [/partner/deploy § Vault OIDC SSO 통합](/partner/deploy)
- customer 측 vault bootstrap: [/ops/runbook/customer-onboarding § D+1](/ops/runbook/customer-onboarding)
- 결정: [D-ops-9](/ops/decisions) · [D-ops-10](/ops/decisions) · [D-ops-17](/ops/decisions) · [D-ops-24](/ops/decisions) · [D-ops-26](/ops/decisions) · [D-ops-27](/ops/decisions) · [D-ops-28](/ops/decisions) · [D-ops-32](/ops/decisions) · [D-ops-33](/ops/decisions) · [D-ops-37](/ops/decisions) · [D-ops-40](/ops/decisions)
- 소스: `/Users/axe/.axe/vault/{docker-compose.yml, Caddyfile, .env}` · build: `axelabs-ai/vault` repo

---