개인 문서형 Docs와 Provenance 운영 계획

한눈에 보기

이 문서는 공개 포트폴리오와 개인 문서형 docs를 keystone-portfolio 안에서 통합 관리하되, 서버에 노출되는 경로를 공개용과 인증 필요 영역으로 분리하기 위한 운영 계획입니다.

핵심 원칙은 다음과 같습니다.

• 공개 포트폴리오는 문제, 접근, 결과, 증거, 공개 가능한 출처 요약을 보여준다.
• 개인 문서형 docs는 실제 원천 경로, commit, 내부 판단, source map, reference ledger를 보관한다.
• 저장소가 비공개여도 서버가 제공하는 route는 공개될 수 있으므로, private markdown은 public archive, sitemap, 검색 index에 섞지 않는다.
• HTML 산출물은 모두 Astro로 통째 변환하지 않고, 가치와 민감도에 따라 Astro, archive-md, static-html, private-only, discard로 분류한다.

공개 / 개인 경계

계층	목적	공개 범위
Portfolio	외부 독자에게 보여줄 시스템 설명과 사례	공개
Public Archive	공개 가능한 과거 문서와 정제된 reference 요약	공개
Private Docs	source map, provenance ledger, 내부 결정, raw evidence	인증 필요
Internal Source	실제 저장소, 로컬 로그, raw transcript, 민감 경로	비공개/로컬 전용

권장 파일 구조

keystone-portfolio
  src/data/v2Portfolio.ts       공개 포트폴리오 1급 페이지
  src/content/docs/             공개 archive docs
  src/content/private-docs/     인증 뒤에 읽는 개인 문서 collection
  src/content/cases/            추후 case 전용 collection 후보
  docs/internal/                라우팅하지 않는 이관 매트릭스와 작업 초안
  public/hugh/                  공개 가능한 HTML snapshot

현재 보호 방식

Cloudflare Pages 배포에서는 /private/* 요청을 Pages Functions middleware가 먼저 검사한다. 사용자는 /private/login에서 비밀번호를 입력하고, 통과하면 HttpOnly 쿠키로 /private/docs/*에 접근한다.

필수 환경 변수:

Name	설명
PRIVATE_DOCS_PASSWORD	private docs 진입 비밀번호

선택 환경 변수:

Name	설명
PRIVATE_DOCS_SESSION_SECRET	세션 쿠키 HMAC 서명 키. 없으면 비밀번호 값을 서명 키로도 사용

배포 체크리스트

Cloudflare Pages 환경 변수에 PRIVATE_DOCS_PASSWORD를 설정한 뒤 새 배포를 실행한다. 배포 후에는 비로그인 상태에서 /private/docs가 /private/login으로 이동하는지, 로그인 후 private docs가 열리는지, /private/logout 후 다시 잠기는지 확인한다.

검증 명령:

npm run build
npm run validate:public-boundary

이 검증은 private route 생성, middleware 존재, sitemap 제외, 공개 문서의 민감 문자열 노출 여부를 확인한다.

한계

현재 방식은 계정별 인증이 아니라 공유 비밀번호 게이트다. 비밀번호가 유출되면 전체 private docs에 접근할 수 있으므로 필요하면 비밀번호를 교체한다. 외부 협업자별 권한, 접근 기록, 세분화된 정책이 필요해지면 Cloudflare Access로 승격한다.

Provenance 분류

Label	의미	공개 처리
reference-only	읽고 검토만 했고 직접 도입하지 않음	맥락상 필요할 때만 언급
adapted-reference	아이디어나 패턴만 가져와 재구현	공개 출처 표기 권장
modified-adaptation	구조를 크게 바꿔 도입	공개 출처와 변경점 요약 필요
direct-derived	코드나 문서를 직접 가져오거나 거의 파생됨	라이선스와 원문 출처 필수
keystone-native	처음부터 Keystone 기준으로 계획/설계/구현	Keystone-native로 표기
discarded	검토 후 버림	보통 private ledger에만 보관

공개 템플릿

provenance:
  type: adapted-reference
  source_name: Hue reference system
  source_author: Hue author
  source_url: 공개 가능하면 URL
  source_path: 공개 가능하면 파일/문서 경로
  license: 확인된 경우 표기
  adoption: idea-reimplemented
  changes:
    - Keystone Hub layer/profile 구조로 재설계
    - runtime state import 금지
    - doctor/health loop에 통합

내부 템플릿

internal_source:
  original_repo: 실제 repo URL 또는 로컬 clone 경로
  commit: abc1234
  file: path/to/source.md
  reviewed_at: 2026-06-03
  decision: adopt | adapt | reference-only | discard
  implemented_in:
    - layers/...
    - docs/...

HTML에서 Astro로 옮기는 기준

후보 유형	처리 방식	기준
대표 사례	Astro 상세 페이지	외부 독자가 문제, 접근, 결과, 증거를 이해해야 하는 경우
반복 목록/저널	Markdown 또는 JSON 데이터 + Astro route	목록, 필터, 인덱스가 필요한 경우
원본 보존 HTML	Static snapshot	시각적 보존 가치는 있지만 1급 포트폴리오로 재작성할 필요가 낮은 경우
내부 운영 화면	Private docs 후보	경로, profile, machine, runtime 상태, 내부 로그가 포함된 경우
생성물/중복본	Discard	다시 만들 수 있거나 canonical 원본이 따로 있는 경우

이관 수용 기준

1. 모든 후보는 Astro, archive-md, static-html, private-only, discard 중 하나로 분류한다.
2. 공개 페이지에는 provenance label과 공개 가능한 source summary가 있다.
3. 로컬 경로, 토큰, webhook, raw transcript, 민감한 회사/고객 맥락은 공개 산출물에 포함하지 않는다.
4. static HTML은 archive snapshot으로 표시하고, Keystone-native Astro 페이지처럼 보이게 하지 않는다.
5. /archive/docs/* 링크는 src/content/docs에 실제 문서가 있을 때만 유지한다.
6. /private/docs/*는 서버 또는 플랫폼 인증이 준비된 뒤에만 route를 만든다.

현재 권장 방향

먼저 Cases와 Provenance를 포트폴리오의 1급 섹션으로 승격한다. 그다음 공개 가치가 높은 viewer/docs 원천만 Astro 상세 페이지로 재작성하고, 나머지는 공개 아카이브 또는 private ledger로 분리한다.