> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# nora documents

> 지식 라이브러리의 문서 관리. 나열, 태그, supersede

문서가 지식의 원시 단위. 파일, 페이지, 추출물 같은 것들. (파운더리 파이프라인이나 웹 업로드로) 인제스트되면 Agent가 리트리벌하는 라이브러리에 삶.

`documents` CLI가 라이브러리를 일상적으로 관리하는 표면: 나열, 태그, supersede.

## 명령

| 명령                                                  | 설명                    |
| --------------------------------------------------- | --------------------- |
| `documents list [--tag <tag>]`                      | 문서 나열(폴더 태그로 좁힘 선택).  |
| `documents get <doc-id>`                            | 문서 하나의 전체 메타데이터 출력.   |
| `documents supersede <doc-id> [--restore]`          | Superseded 표시(또는 복원). |
| `documents tag <doc-id> [--add ...] [--remove ...]` | 폴더 태그 추가·제거.          |

## `documents list`

```bash theme={null}
nora documents list
nora documents list --tag billing
```

문서당 한 줄 출력: ID, 제목, 콘텐츠 타입, 크기, 태그, 마지막 업데이트.

스크립트용 출력은 `--json`을 붙임.

## `documents get`

```bash theme={null}
nora documents get doc_abc
```

전체 메타데이터 출력. 제목, 소스 URL, 콘텐츠 해시, 태그, 만든 인제스트 파이프라인, 청크 수, supersede 상태.

## `documents supersede`

```bash theme={null}
nora documents supersede doc_abc
# 나중에 undo:
nora documents supersede doc_abc --restore
```

문서를 superseded로 표시. 모든 리트리벌에서 숨지만 감사용으로는 조회됨. Superseded 청크가 몇 초 안에 쿼리에 안 걸림.

`--restore`가 supersede를 되돌림. 문서가 리트리벌 인덱스에 다시 합류.

삭제보다 supersede를 권함. 되돌릴 수 있고 감사 트레일이 남음. 삭제는 진짜 테이크다운(PII, 법적 제거)에만 맞음. 그마저도 CLI가 아니라 라이브러리 UI를 씀. 삭제는 확인이 필요하니까.

## `documents tag`

```bash theme={null}
# 태그 추가
nora documents tag doc_abc --add customer-facing,billing

# 제거
nora documents tag doc_abc --remove deprecated

# 둘 다 한 번에
nora documents tag doc_abc --add current --remove draft
```

태그가 큰 라이브러리를 잘라 쓰는 주된 방법. 태그 위생은 [태그·정리](/ko/build/knowledge/tag) 참고.

쉼표로 구분한 목록을 받음. `--add`와 `--remove`는 둘 다 선택(다만 적어도 하나는 필요).

## 레시피

### 문서 묶음을 한 폴더에서 다른 폴더로 옮기기

```bash theme={null}
for id in $(nora documents list --tag old-folder --json | jq -r '.[].id'); do
  nora documents tag $id --add new-folder --remove old-folder
done
```

### 특정 날짜보다 오래된 것 모두 supersede

```bash theme={null}
cutoff="2025-01-01"
for id in $(nora documents list --json | jq -r --arg cutoff "$cutoff" '.[] | select(.updated_at < $cutoff) | .id'); do
  nora documents supersede $id
done
```

### 태그 커버리지 감사

```bash theme={null}
nora documents list --json | jq -r '.[] | select((.tags // []) | length == 0) | .id'
```

태그 없는 문서를 출력. 파운더리 강화기로 자동 태깅할 후보.

### 문서 메타데이터를 git에 스냅샷

```bash theme={null}
nora documents list --json > snapshots/documents-$(date +%Y%m%d).json
```

콘텐츠를 안 내보내고 시간에 걸친 라이브러리 변화를 추적하기 좋음.

## CLI가 안 하는 것

* **업로드** 일회성 업로드는 앱을 씀([문서 업로드](/ko/build/knowledge/upload) 참고). 자동 인제스트는 파운더리 파이프라인([`nora pipelines`](/ko/cli/pipelines) 참고).
* **삭제** CLI는 supersede만 됨. 하드 삭제는 앱 UI를 씀(이중 확인 있음).
* **콘텐츠 편집** 문서는 인제스트되면 안 바뀜. 소스를 고쳐 다시 인제스트.

이 제약은 일부러 둔 것. CLI는 시각 리뷰가 필요한 편집이 아니라 스크립트 작업에 맞춰짐.

## 문서 ID가 오는 곳

* **앱** 라이브러리의 문서마다 세부 패널에 ID가 뜸.
* **파운더리 로그** `pipelines logs get`이 실행이 만든 문서 ID를 표시.
* **`documents list`** 스크립트용.