Folio
요청과 기존 아티팩트를 읽은 후 HTML을 작성하십시오. 모든 외부 의존성과 퍼블리시 URL은 매니페스트 원장에 속합니다. 아티팩트는 정적 문서입니다 — API를 호출하지 않습니다.
Folio를 사용해야 할 때 — 사용하지 말아야 할 때
Folio는 지속적으로 보관, 열람, 공유할 수 있는 웹 산출물 — 사용자가 저장하거나 다시 열거나 다른 사람에게 전달할 항목을 위한 것입니다.
Folio를 사용하세요:
- 사용자가 문서, 대시보드, 시트, 슬라이드, 페이지를 저장하거나 보내겠다고 요청하는 경우
- 출력이 산출물(눈요기가 아니라 "보고서 만들어 줘", "팀을 위한 대시보드 만들어 줘", "이걸 온라인에 올려 줘", "페이지를 원해…")인 경우
- 사용자가 명시적으로 동사를 호출하는 경우 (
folio publish,folio audit,folio remix,folio describe)
Folio를 사용하지 마세요:
- 사용자가 산출물이 아닌 빠른 확인을 원하는 경우 ("보여 줘", "어떻게 생겼는지 보여 줘", "그냥 확인해 봐", "표시해 줄 수 있어?")
- 이 대화 이후에 다시 열지 않을 출력물인 경우 — 인라인으로 답변하거나 스크래치 파일을 작성하고, 스탬프, 원장, 게이트를 적용하지 마십시오.
- 요청이 코드 스니펫, 설정 파일, 단일 함수인 경우 — 브라우저 아티팩트가 아닙니다.
입구 게이트. 아티팩트 흐름에 들어가기 전에 질문하세요: 사용자가 이 세션 후에 이 파일을 다시 열 것인가? 아니라면 folio는 잘못된 도구입니다 — 그냥 답변하세요. 맞다면 진행하세요.
독립형이 기본입니다. 가장 가벼운 Folio 경로는 하나의 index.html을 가진 단일 폴더입니다 — 사이트 루트나 site.json, 인덱스 페이지가 없습니다. 사이트 루트는 두 번째 아티팩트가 있거나 사용자가 컬렉션을 퍼블리시하도록 요청할 때만 나타납니다. 단일 파일을 위해 사이트 의례를 만들지 마십시오.
용어집
Folio 출력에서는 다음 용어만 사용하십시오.
| 용어 | 의미 |
|---|---|
| artifact | 브라우저에서 실행 가능한 CSS/JS가 포함된 독립형 정적 웹 산출물 (HTML) |
| bundle | single-file (인라인 CSS/JS) 또는 multi-file (한 디렉토리에 연결된 자산) 중 하나 |
| artifact kind | doc, sheet, dashboard, explainer, slides, tool, landing 중 하나 |
| host profile | 사이트가 지속적으로 호스팅되는 위치: local, surge, gh-pages, cf-pages, cf-worker |
| share (tunnel) | 실행 중인 로컬 서버의 임시 공개 URL (기본값: localhost.run, 대안: ngrok). 임시적이며 머신이 호스트를 유지함 — 퍼블리시가 아님 |
| site root | index.html과 artifacts/ 트리를 포함하는 디렉토리, 하나의 도메인으로 퍼블리시됨. 아티팩트는 별도의 서브도메인이 아닌 그 아래의 경로임 |
| site manifest | .folio/site.json — 신뢰할 수 있는 정식 정보 출처. 도메인 + 아티팩트별 레지스트리 (slug, kind, bundle, ledger, provenance, publish state)를 포함함. 스탬프, 인덱스, 감사도 모두 여기서 파생됨 |
| standalone artifact | 사이트 루트가 없는 아티팩트. HTML 스탬프가 유일한 매니페스트임. 두 번째 아티팩트가 나타나면 사이트 항목으로 업그레이드됨 |
| provenance | 리믹스된 아티팩트의 source 필드: { slug, site, url }. 원본은 null. describe, audit, remix에서 읽음 |
| manifest | 항목 HTML, 파일 목록, 외부 종속성, 선택적 퍼블리시 메타데이터 |
| ledger | 매니페스트 원장 — 빌드 전 종속성, 데이터 파일, URL, 증거 수준 |
| gate | 핸드오프 전에 통과해야 하는 이진 검사 |
| evidence level | observed, derived, stated, absent 중 하나 |
이 스킬을 사용하는 방법
- 기본값: 하나의 아티팩트를 생성하거나 업데이트합니다. 아티팩트 흐름을 따릅니다. 단일 아티팩트는 기본적으로 독립형입니다 — 사이트 루트가 필요하지 않습니다.
folio audit <경로|URL>: 읽기 전용 감사. 편집하지 마십시오.references/verbs/audit.md를 읽으십시오.folio describe <경로|URL|slug>: 아티팩트의 매니페스트 항목(종류, 원장, 출처, 퍼블리시 상태)을 읽습니다.references/verbs/describe.md를 읽으십시오.folio share <사이트-루트>: 임시 공개 링크를 터널(기본값 localhost.run — 설치 불필요, 계정 불필요;--ngrok대안)을 통해 로컬에서 실행 중인 사이트로 엽니다. 머신이 호스트를 유지하며, URL은 프로세스가 종료되면 사라집니다. "지금 당장 누군가에게 보여주기" 용도로 사용하십시오. 퍼블리시가 아닙니다.references/verbs/share.md를 읽으십시오.folio publish <사이트-루트>: 사이트 루트(모든 아티팩트)를 선택한 호스트 프로필에 내구성 있는 호스팅으로 배포합니다. 먼저 인덱스를 재생성한 후(scripts/gen-index.js), 배포합니다.references/verbs/publish.md를 읽으십시오.folio remix <경로|URL>: 아티팩트를 포크하고 매니페스트 정직성을 유지하며 소스 계보를 기록하면서 변경합니다.references/verbs/remix.md를 읽으십시오.
한 번 실행 = 사용자가 여러 개를 지정하지 않는 한 하나의 아티팩트입니다. 요청을 충족하는 가장 작은 번들을 선호하십시오. 단일 아티팩트는 독립형입니다. 여러 아티팩트는 하나의 사이트 루트 아래에 있으며 하나의 도메인으로 퍼블리시됩니다. 사이트 루트 모델 및 독립형-사이트 업그레이드에 대한 자세한 내용은 references/site-index.md를 읽으십시오.
양보할 수 없는 규율
- 예쁘기 전에 실행 가능. 아티팩트는 브라우저에서 열리고 핵심 상호작용이 작동해야 하며, 그 후에야 다듬거나 퍼블리시합니다.
- 정적 문서만. 외부 API에 대한
fetch()호출, WebSocket 연결, 라이브 엔드포인트에 대한XMLHttpRequest가 없습니다. 데이터는 인라인으로 포함되거나,fetch('./data/…')를 통해 로컬 파일에서 로드되거나, 빌드 시 생성됩니다. 아티팩트가 수행하는 유일한 네트워크 요청은 원장에 기록된 CDN 스크립트, 스타일, 글꼴에 대한 것입니다. - 매니페스트 정직성. CDN 스크립트, 글꼴, 이미지, 데이터 파일은 원장 행이지 예상치 못한 것이 아닙니다.
- 로컬 우선, 그 다음 공유, 그 다음 퍼블리시. 기본 호스트 프로필은
local입니다. 동적 방식으로 실행하십시오 —node <folio-skill>/scripts/serve.js <사이트-루트>는artifacts/폴더를 보장하고, 원장에서 인덱스/검색 페이지를 재생성하며, 열린 포트를 선택하고 HTTP로 서빙합니다 (file://은 완전히 인라인된 단일 파일에 적합하지만fetch및 모듈 임포트를 깨뜨립니다).references/local-server.md를 참조하십시오. 지금 당장 누군가에게 보여주려면 임시 터널을 여십시오 —node <folio-skill>/scripts/share.js <사이트-루트>(기본값 localhost.run, 설치/계정 불필요); 링크는 임시적이며 머신이 호스트를 유지합니다. 내구성 있는 호스팅은publish입니다 — 사용자가 요청하거나folio publish가 호출된 경우에만 해당됩니다. 공유 또는 퍼블리시 기능을 사전에 광고하지 마십시오. - 정적 파일에 비밀을 저장하지 마십시오. API 키, 토큰, 개인 URL은 커밋되거나 퍼블리시된 HTML/JS에 속하지 않습니다.
- 보기 흉하지 않게. 아티팩트는 시각적 기준을 따릅니다. 빌드 전에
references/visual-baseline.md를 읽으십시오.
골드 결정 트레이스
요청: 이 CSV로 대화형 지연 시간 히스토그램을 만들어 동료에게 전달.
인벤토리:
· 대상: 새 아티팩트 `latency-hist`
· 기존: 없음
· 데이터: 사용자가 `runs.csv` 첨부 (observed, 840행)
· 제약 조건: 로컬 폴더, 퍼블리시 없음
선택: kind=explainer · bundle=multi-file · host=local · audience=동료 핸드오프
원장:
dep | kind | evidence | in artifact as
d3@7 (cdn.jsdelivr) | script | stated, 사용자가 고정하지 않음 | index.html script 태그 + README 메모
runs.csv | data | observed | ./data/runs.csv, fetch('./data/runs.csv')로 로드
파일 계획:
생성: artifacts/latency-hist/index.html, style.css, app.js, data/runs.csv, README.md
삭제 없음.
검증: npx serve artifacts/latency-hist; 차트 렌더링; 콘솔 깨끗함
게이트: opens-locally=예, console-clean=예, ledger-complete=예, no-secrets=예, mock-labeled=해당 없음, visual-baseline=예
핸드오프: 경로, 여는 방법, 원장 요약, 연기됨: 없음
범위 포크
넓은 설계 질문 전에 범위를 결정하십시오.
| 요청 형태 | Bundle | Host | 생략 |
|---|---|---|---|
| 빠른 일회성 데모 | single-file | local | README, 퍼블리시, 다중 페이지 |
| 문서나 보고서 | single-file 또는 multi-file | local | 차트, 무거운 JS |
| 데이터 테이블이나 시트 | single-file 또는 multi-file | local | 서사적 산문, 장식 |
| 메트릭 대시보드 | multi-file | local | 전체 CRUD, 라이브 데이터 피드 |
| 개념 설명 | multi-file | local | 조밀한 원시 데이터 덤프 |
| 슬라이드 덱 | multi-file | local | 스크롤 레이아웃, 위젯 |
| 공유 동료 아티팩트 | multi-file | local | 프레임워크 빌드 단계 |
| 지금 당장 누군가에게 보여주기 | single-file 또는 multi-file | share (터널) | 배포 의례, 내구성 호스트 |
| 내구성 있는 공개 링크 | multi-file | surge 또는 cf-pages | 인증, 서버 로직 |
| 에이전트 핸드오프 미리보기 | single-file 선호 | local | 요청하지 않으면 공유/퍼블리시 안 함 |
애매한 요청: 한 번만 간결하게 물어보십시오. 예: "단일 자체 포함 파일 또는 별도의 CSS/JS가 있는 작은 폴더?" 답변이 없으면 작동하는 가장 작은 번들을 선택하십시오.
아티팩트 흐름
0. 인벤토리
요청과 기존 아티팩트 트리를 읽으십시오. references/evidence.md와 references/artifact-types.md를 읽으십시오.
수집:
- 주제: 아티팩트가 보여주거나 사용자가 할 수 있게 해야 하는 것
- 입력: 파일, JSON, CSV, 복사본, 디자인 제약 조건 (증거 수준 포함)
- 기존 아티팩트: 경로, 항목 HTML, 매니페스트, 마지막 퍼블리시 URL (있는 경우)
- 호스트 프로필: 기본값
local; 퍼블리시가 범위에 있을 때references/host-profiles.md를 읽으십시오 - 컨벤션 소스:
folio.md(있는 경우)
진행 전에 인용을 포함한 간결한 인벤토리를 출력하십시오.
1. 선택
빌드 전에 출력: Picks: kind=<x> · bundle=<y> · host=<z> · audience=<a>.
종류가 불분명할 때 references/artifact-types.md를 읽으십시오. 호스트가 local이 아닐 때 references/host-profiles.md를 읽으십시오.
2. 매니페스트 원장
HTML을 작성하기 전에 원장을 구축하십시오. references/manifest-ledger.md를 읽으십시오.
열:
dep | kind | evidence | in artifact as
종류: script, style, font, image, data, mock, publish-target.
데이터 파일과 모의 데이터는 명시적이어야 합니다. 외부 API 호출은 범위를 벗어납니다 — 규율 #2를 참조하십시오.
3. 파일 계획 및 빌드
편집 전에 파일 계획을 명시하십시오:
생성: artifacts/<slug>/index.html, app.js, data/sample.json
수정: 없음
삭제 없음.
템플릿에서 시작하십시오. references/templates/<kind>.html을 로드하고 적응시키십시오 — {{placeholder}} 콘텐츠와 <!-- Replace: ... --> 마커를 실제 콘텐츠로 교체하십시오. 템플릿은 게이트를 통과하는 Folio 아티팩트 그 자체입니다; 토큰 블록, 라이트/다크 토글, 파비콘, 종류별 구조를 포함합니다. 각 템플릿이 제공하는 항목에 대한 인덱스는 references/templates/를 읽으십시오.
CSS를 작성하기 전에 references/visual-baseline.md를 읽으십시오.
사용자가 특정 스택을 명시하지 않는 한 일반 HTML/CSS/JS로 빌드하십시오. 선호:
- 의미론적 HTML, 하나의 명백한 항목 파일 (
index.html) - 모든 시각적 토큰(색상, 서체, 간격, 둥근 정도, 그림자)에 CSS 사용자 정의 속성
- 색상에 OKLCH 사용;
:root토큰 블록 외부에 인라인 hex/rgb 없음 - 바닐라 JS 또는 단일 명명된 CDN 라이브러리 — 원장에 기록
multi-file: 모든 자산 경로를 상대 경로로 유지; 절대 머신 경로 없음- 이탤릭체 제목 없음; 읽기 좋은 측정값 (
max-width: 60–70ch);html과body에overflow-x: clip
아티팩트가 사용자 입력을 받거나, 타사 콘텐츠를 포함하거나, 공개적으로 퍼블리시될 때 references/security.md를 읽으십시오.
스탬프 (HTML 주석, 항목 파일 상단):
<!-- Folio · slug: latency-hist · kind: explainer · bundle: multi-file · host: local -->
<!-- deps: d3@7 · data: runs.csv · publish: none -->
single-file의 경우 스탬프를 최소로 유지하십시오 (한 줄).
4. 검증
references/verification.md를 읽으십시오. 호스트 프로필에 맞는 검사를 실행하십시오.
최소 매트릭스:
check | command/evidence | result | notes
예: 정적 서버 + 항목 URL 로드, DevTools 콘솔 깨끗함, 주요 상호작용 클릭 통과, 끊어진 링크 검사, file:// vs 서버 참고 (fetch용), 시각적 기준 점검.
5. 게이트
핸드오프 전에 적용하십시오. 아니오가 있으면 수정 루프를 트리거합니다.
| 게이트 | 검사 |
|---|---|
opens-locally | 항목 HTML이 정적 서버(또는 정직한 file:// 주의사항 문서화)를 통해 로드됨; 서버 설정은 references/local-server.md 참조 (scripts/serve.js가 한 명령 경로) |
console-clean | 주요 경로에서 잡히지 않은 오류 없음 |
ledger-complete | 모든 외부 종속성 및 데이터 소스가 원장에 나타남 |
no-secrets | 소스에 키, 토큰, 개인 URL 없음 |
mock-labeled | 실제 데이터가 없을 때 모의/샘플 데이터 레이블 지정 |
static-only | 외부 API에 fetch() 없음, WebSocket 없음, 라이브 엔드포인트에 XHR 없음 |
visual-baseline | 토큰 블록 존재, :root 외부에 인라인 색상 없음, 이탤릭체 제목 없음, 대비 충분 |
publish-ready | 퍼블리시할 때: 호스트 프로필 단계가 문서화되고 검증되었거나 명시적으로 연기됨 |
manifest-derivation | 권고사항. HTML 스탬프(slug, kind, bundle)가 이 아티팩트의 site.json 항목과 일치함. 드리프트를 플래그함; references/verification.md#manifest-derivation-check 참조 |
빌드 후 references/slop-test.md를 읽으십시오. 핸드오프 전에 P0/P1을 수정하십시오.
6. 퍼블리시 (선택 사항)
사용자가 퍼블리시를 요청하거나 folio publish를 호출한 경우에만 해당됩니다. references/verbs/publish.md와 호스트 프로필 상세 파일을 읽으십시오.
퍼블리시 URL을 매니페스트와 핸드오프에 기록하십시오. 퍼블리시 명령 출력의 증거 없이 URL을 주장하지 마십시오.
7. 핸드오프
포함:
- 아티팩트 경로 및 항목 파일
- 로컬에서 여는 방법 (정확한 명령)
- 퍼블리시 URL (퍼블리시된 경우), 증거 포함
- 매니페스트 원장 요약
- 검증 명령 및 결과
- 연기된 항목 (예:
fetch는 서버 필요, 모의 데이터 사용 중)
매니페스트나 퍼블리시 사실을 구현 잡담 아래 묻지 마십시오.
BAD/GOOD 대비
BAD: 대시보드가 보통 API에서 사용자를 로드하기 때문에 fetch('/api/users')를 연결.
GOOD: data/users.json을 포함하고 "샘플 데이터" 레이블을 표시. API 호출 없음.
BAD: Google Analytics, 글꼴, 세 개의 CDN 라이브러리를 나열하지 않고 붙여넣기. GOOD: 각 의존성은 URL과 목적을 가진 원장 행입니다.
BAD: 퍼블리시 명령을 실행하지 않고 "https://demo.example.com에 배포됨". GOOD: 퍼블리시 URL을 명령 출력에서 복사하거나 연기됨으로 표시.
BAD: CSS 전체에 oklch() 값이 흩어져 있고, 세 가지 다른 font-family 선언이 존재.
GOOD: 모든 시각적 값이 :root 토큰 블록에 있고 var()로 참조됨.
컨벤션 아티팩트
folio.md (출력 디렉토리, 기본 호스트, CDN 허용 목록, 명명): 옵트인. references/folio-md.md를 읽으십시오. 존재하면 하우스 기본값이 승리합니다.
선택적 프로젝트별 레이아웃:
…
[번역을 위해 잘렸습니다]