Documentation Hub

Documentation Hub (문서 허브)

최종 점검: 2026-06-21

이 페이지는 FractalOps 문서의 단일 진입점이자 전체 지도입니다. 사람용 문서는 docs/src/content/docs/ 아래의 Astro/Starlight 사이트로 빌드되며, 클러스터에서 docs.monstore.io 로 서빙됩니다(GitOps로 재현 가능, PR #1803 기준).

코드 옆에 있던(co-located) 에이전트 지침과 스캐폴더 템플릿 시드 파일은 운영자와 에이전트가 흩어진 옛 메모를 줍지 않도록 여기서 분류합니다.

먼저 읽는 순서 (Read Order)

처음 온보딩하는 사람은 이 순서를 권장합니다.

FractalOps Constitution — 제품 법(L0)
FractalOps Canonical Architecture — 제품 정의 서사
Current Stack, Solution, and IA Map — 지금의 스택/IA 라우팅 기준
FractalOps C4 Model — 시스템/컨테이너/컴포넌트 경계
Architecture Overview — 실행/플랫폼 토폴로지
Engineering Handoff — 운영자 인수인계
Requirements Index — 요구사항 SSOT

문서 지도 (Docs Map)

큰 그림으로 섹션이 어떻게 연결되는지 보여줍니다. 화살표는 “여기서 시작해서 저기로 파고든다”는 추천 흐름입니다.

flowchart TB
  index["index<br/>랜딩 · 안내 데스크"]
  hub["documentation-hub<br/>(이 페이지)<br/>전체 지도"]
  manual["manual-ko<br/>운영 매뉴얼 (한글)"]

  subgraph arch["Architecture (제품 법 · 정의 · 토폴로지)"]
    direction LR
    const["constitution<br/>제품 법 (L0)"]
    canon["canonical architecture<br/>제품 정의"]
    stackmap["current-stack-solution-ia<br/>스택 · IA 라우팅"]
    c4["fractalops-c4-model<br/>C4 경계 지도"]
    overview["overview<br/>실행 토폴로지"]
  end

  subgraph ops["Operations (운영 런북)"]
    direction LR
    handoff["engineering-handoff"]
    squadops["agentsquad-operations"]
    cache["docker-cache (Nexus + GHCR)"]
  end

  subgraph req["Requirements (스택별 요구사항)"]
    direction LR
    reqindex["requirements index"]
    stacks["stacks/*<br/>keycloak · pomerium · pve ..."]
  end

  subgraph colo["Colocated (코드 옆 README · 규칙)"]
    direction LR
    infra["platform/k8s/environments<br/>런타임 SSOT"]
    contracts["contracts<br/>계약 패키지"]
  end

  index --> hub
  hub --> manual
  hub --> arch
  hub --> ops
  hub --> req
  hub --> colo
  const --> canon --> stackmap --> c4 --> overview
  reqindex --> stacks
  stackmap -.->|"우선 기준"| reqindex

정본 문서 (Canonical Docs)

제품의 정체 · 법 · 토폴로지를 정의하는 1급 문서입니다.

주제	정본 문서	상태
제품 법 (L0)	FractalOps Constitution	Canonical
제품 정의 서사	Canonical Architecture	Canonical
현재 스택과 IA	Current Stack, Solution, and IA Map	Canonical
C4 시스템 지도	FractalOps C4 Model	Canonical C4
실행/플랫폼 토폴로지	Architecture Overview	Canonical 상세
실행 네이밍 사전	Execution Naming Glossary	정본 용어집
아키텍처 린팅 표준	Tach DDD / Feature Slice Boundary Standard	솔루션 공통 표준
Pydantic 경계 계약	Pydantic Boundary Contracts	계약 경계 표준
코드베이스 승격 티어	Codebase Promotion Tiering	승격 규칙

AgentSquad · AgentSquad · Agent Execution

에이전트가 실제로 일을 수행하는 실행 평면입니다. 제품 흐름의 “일(work)” 과 “반성적 개선” 단계가 여기서 돕니다.

주제	문서	설명 (한 줄)
AgentSquad 전달 언어	AgentSquad Delivery Language	전달용 정본 명사 · controller message · merge lifecycle 어휘
AgentSquad 현재 구현 지도	AgentSquad Current Implementation	단일 워크스페이스 + git worktree + 2-plane 실행의 실제 구현
AgentSquad PARA	AgentSquad PARA	런타임 오버뷰 (PARA 모델)
AgentSquad 런/세션 운영	AgentSquad Operations	런/세션 운영 런북
Agent Execution	Agent Execution	생명주기 · 재시도 · 리플레이 · next action
Agent PR 전달 파이프라인	Agent PR Submission Pipeline	에이전트 → GitHub App PR 전달 경로
cliproxy 런타임 자격증명	cliproxy Runtime Credentials	모델 플레인 자격증명 브리지
런타임 딜리버리 모델 (Bake vs Reconcile)	Runtime Delivery Model	무엇을 BAKE/무엇을 PULL, 핀 주체 SSOT

실행 · 프리뷰 · 빌드 평면

워크스페이스, dev 프리뷰, 빌드/관측이 어떻게 나뉘는지 다룹니다.

주제	문서	설명 (한 줄)
Dev Preview Plane	Dev Preview Plane	bare 프로세스 dev 서버 + 서명 프리뷰 URL + `<slug>.monstore.io` 라우팅
Project Dev Service Plane	Project Development Service Plane	워크스페이스 vs Dokploy 백킹 서비스 경계
Build Plane Observability	Build Plane Observability	CI 이미지 빌드 텔레메트리 · GlitchTip · trace sink
Build & Package Cache	Build & Package Cache Topology	Nexus package/Docker Hub cache + GHCR OCI build cache
Test Execution Policy	Test Execution Policy	PR/main/release 테스트 계층 · affected gate · 캐시/GC 원칙
generate-env 컷오버	generate-env Cutover	topology → env 생성 경로 컷오버

의미(Semantics) · 계보 · 데이터 평면

증명 경로(proof path)와 데이터/계보 평면입니다.

주제	문서	설명 (한 줄)
Harness DataHub 투영	Harness DataHub Projection	런/세션 계보의 DataHub 투영
계보 온톨로지 v1	Lineage Ontology v1	엔티티/aspect 온톨로지
Feature Plane	Feature Plane	Feast 기반 compact 에이전트 피처
Work-Lineage 최적화 루프	Work-Lineage Optimization Loop	리니지 READ/WRITE/MEASURE 자기최적화 폐루프
Semantic Plane & 런타임 하드닝	Semantic Plane and Runtime Hardening	의미 평면 + 런타임 강화
Supabase 중앙 데이터 평면	Supabase Central Data Plane	중앙 postgres 앱-데이터 통합

Portal · Copilot · 전달

사람이 닿는 표면(Portal)과 전달 흐름입니다.

주제	문서	설명 (한 줄)
Portal 전달	Portal Delivery Flow	Astro Cloudflare Worker deploy, cutover guard, public smoke
Portal Copilot 모듈	Portal Copilot Module	Portal 내장 copilot 도킹

운영 (Operations)

배포 · 시크릿 · 노드 위생 · 알림 등 운영 런북입니다.

주제	문서	설명 (한 줄)
엔지니어링 인수인계	Engineering Handoff	운영자 핵심 인수인계
Cloudflared / OpenBao	Cloudflared OpenBao	edge 터널 + 시크릿 전달
Nexus docker 미러 컷오버	Nexus Docker Mirror Cutover	docker-pull 캐시 컷오버 런북
Stack API Debt Audit	Stack API Debt Audit	외부 스택 공식 API drift/삭제 후보 추적
K3s 노드 위생	K3s Node Hygiene	노드 정리/위생 런북
PostgreSQL 스토리지	PostgreSQL Storage	공유 postgres 스토리지 운영
Novu 알림	Novu Notifications	알림 플레인 운영
Tilt 로컬 개발	Tilt	로컬 개발 루프
리서치 Starlight 워크스페이스	Research Astro/Starlight Workspaces	리서치 모드 문서 워크스페이스
운영 매뉴얼 (한글)	Operations Manual KO	한글 운영자 진입점과 정본 문서 링크

요구사항 (Requirements)

스택별 인증/인가/동기화/검증 요구사항입니다. 라우팅 기준은 Requirements Index가 소유하며, 스택 페이지가 옛 스냅샷과 충돌하면 current stack map이 우선입니다.

주제	문서
요구사항 SSOT 색인	Requirements Index
공통 계약	Common Contract
MCP E2E 시나리오	MCP E2E Scenarios
FractalOps Core	FractalOps Core
Portal Control Plane	Portal Control Plane
Pomerium Edge	Pomerium
Keycloak IdP	Keycloak
Penpot	Penpot
OpenBao Secret	OpenBao
Proxmox VE	PVE
Temporal Orchestration	Temporal

코드 옆 문서 (`colocated/`)

예전엔 코드 근처에 있던 README/규칙 파일입니다. 지금은 docs/src/content/docs/colocated/ 아래로 물리적으로 모았고, 제품 아키텍처를 재정의할 수 없습니다(정본 부모 문서를 따릅니다).

위치	역할	정본 부모
Contracts	계약 저장소와 호환성 정책	Constitution / 계약
plugins/README.md	플러그인 패키지 색인	Armory / 런타임 문서
scripts/README.md	스크립트 패키지 색인	Operations 문서

리포지토리 AGENTS.md와 owner-local README는 로컬 실행 지침만 유지하고 이 허브의 아키텍처 결정을 따릅니다.

에이전트 컨텍스트 문서

운영자 문서가 아니라 에이전트 하네스 컨텍스트 파일입니다. 정본 문서에서 드리프트가 발견되면 재생성/갱신해야 합니다.

위치	역할
`.agent-os/context/canonical-summary.md`	압축된 정본 요약
`.agent-os/context/ddd-context-map.md`	DDD 컨텍스트 맵
`.agent-os/context/e2e-manifest.md`	E2E 라우팅
`.agent-os/context/fractal-plan-l0-l3.md`	L0-L3 계획

템플릿 시드 문서

생성된 리포지토리/패키지로 복사되기 때문에 의도적으로 docs/ 밖에 두는 파일입니다. FractalOps 운영자 문서가 아니라 템플릿 페이로드입니다.

위치	역할
`ops/scaffolder/templates/create-package/README.md`	패키지 템플릿 운영자 노트
`ops/scaffolder/templates/create-package/skeleton/README.md`	생성 패키지 README 시드
`ops/scaffolder/templates/create-project/README.md`	프로젝트 템플릿 운영자 노트
`ops/scaffolder/templates/create-project/skeleton/README.md`	생성 프로젝트 README 시드
`ops/scaffolder/templates/create-project/skeleton/docs/index.md`	생성 프로젝트 docs 시드

폐기 레인 (Deprecation Lane)

retired · 생성물 · 로컬 전용 문서 그룹입니다. 특정 작업이 명시적으로 지목하지 않는 한 운영자 read order에서 제외합니다.

위치	처리
`.serena/memories/*`	도구 메모리, 제품 문서 아님
`.pytest_cache/README.md`	pytest 생성 노트
`output/*`	런 산출물 출력, 정본 아님
`docs/src/content/docs/architecture/todo`	여기 승격되기 전까지는 과거 계획용

유지보수 규칙

새 사람용 문서는 docs/ 아래에 두고, 반드시 이 허브에서 링크합니다.
템플릿 시드 README는 스캐폴더가 생성 리포/패키지로 복사할 때만 docs/ 밖에 둡니다.
README.md는 랜딩 페이지로 두고 여기를 가리킵니다.
docs/src/content/docs/index.md는 짧은 안내 페이지로 두고 여기를 가리킵니다.
옛 스택 페이지는 먼저 Current Stack, Solution, and IA Map으로 양보해야 합니다.
여기 링크되지 않은 파일은 분류되기 전까지 로컬 컨텍스트 또는 retired 문서로 취급합니다.

검증 커맨드

# 문서 트리 인벤토리
find . -maxdepth 3 \( -path './.git' -o -path './node_modules' -o -path './.state' \) -prune -o \( -name '*.md' -o -name '*.mdx' \) -print | sort

# 현재 스택 카탈로그
fops stacks list --compact

# 문서 사이트 빌드 게이트 (docs/ 디렉터리에서)
pnpm --dir docs exec astro check