From 2d3dd1d76877f3f0b819324cbef968ffa0aba27b Mon Sep 17 00:00:00 2001
From: sehkone <sehkone@cluml.com>
Date: Mon, 19 Jan 2026 13:28:12 +0900
Subject: [PATCH] Update documentation

Closes #135
---
 docs/en/cli.md           | 10 ++++++--
 docs/en/concepts.md      | 46 +++++++++++++++++++++++++-----------
 docs/en/configuration.md | 48 +++++++++++++++++++++++++++++++++++++
 docs/en/index.md         | 46 +++++++++++++++++-------------------
 docs/ko/cli.md           | 10 ++++++--
 docs/ko/concepts.md      | 51 ++++++++++++++++++++++++++--------------
 docs/ko/configuration.md | 48 +++++++++++++++++++++++++++++++++++++
 docs/ko/index.md         | 51 +++++++++++++++++-----------------------
 8 files changed, 222 insertions(+), 88 deletions(-)

diff --git a/docs/en/cli.md b/docs/en/cli.md
index bc84464..d6b3988 100644
--- a/docs/en/cli.md
+++ b/docs/en/cli.md
@@ -128,7 +128,7 @@ bootroot init --auto-generate --eab-auto --responder-url http://localhost:8080
 
 ## bootroot status
 
-Checks infra and OpenBao status.
+Checks infra status (including containers) and OpenBao KV/AppRole status.
 
 ### Inputs
 
@@ -170,6 +170,12 @@ This is the required step when adding a new app. After it completes, you
 must run bootroot-agent and OpenBao Agent as instructed, and then start
 the app so mTLS certificates are used correctly in app-to-app traffic.
 
+If the app runs on a different machine, the bootroot-agent on that host
+must use the same `agent.toml`. The `--cert-path`/`--key-path` values must
+also be set relative to where the app runs. This command only prints
+paths/snippets; you still configure and run the agent on the machine where
+the app runs.
+
 ### Inputs
 
 Input priority is **CLI flags > environment variables > prompts/defaults**.
@@ -181,7 +187,7 @@ Input priority is **CLI flags > environment variables > prompts/defaults**.
 - `--agent-config`: bootroot-agent config path
 - `--cert-path`: certificate output path
 - `--key-path`: private key output path
-- `--instance-id`: app instance_id (required for daemon and docker)
+- `--instance-id`: app instance_id
 - `--container-name`: docker container name (required for docker)
 - `--root-token`: OpenBao root token (environment variable: `OPENBAO_ROOT_TOKEN`)
 - `--notes`: freeform notes (optional)
diff --git a/docs/en/concepts.md b/docs/en/concepts.md
index dd45fbc..c9a3a42 100644
--- a/docs/en/concepts.md
+++ b/docs/en/concepts.md
@@ -17,6 +17,10 @@ SANs are the identities inside the certificate. Common types:
 - **DNS**: `example.internal`
 - **IP**: `192.0.2.10`
 
+In the bootroot CLI ecosystem, DNS SANs use this format (same for daemon and docker):
+
+`<instance_id>.<service_name>.<hostname>.<domain>`
+
 ## mTLS
 
 Mutual TLS requires both client and server to present certificates.
@@ -46,7 +50,9 @@ Key terms in the ACME flow:
 
 ## HTTP-01 Challenge
 
-HTTP-01 is a domain control check. The CA gives the client a **token**, and
+HTTP-01 is a domain control check. Its purpose is to ensure certificates
+are issued only to the **actual domain owner**. The CA gives the client a
+**token**, and
 then makes an HTTP request to verify that the domain owner can serve it.
 
 Flow:
@@ -62,8 +68,10 @@ Flow:
 
 ## EAB (External Account Binding)
 
-EAB allows a CA to restrict registrations. The operator supplies a key ID
-and HMAC key. bootroot-agent can load EAB from config or CLI.
+EAB lets a CA restrict **account registrations** from clients such as
+bootroot-agent. The **client** must submit the `kid`/`hmac` issued by the
+CA **during account registration**, or the CA will reject the request.
+bootroot-agent can load EAB from config or CLI.
 
 - `kid` (key ID): an identifier for the EAB key pair issued by the CA.
 - `hmac`: the shared HMAC key used to bind the external account.
@@ -73,7 +81,8 @@ and HMAC key. bootroot-agent can load EAB from config or CLI.
 ## Secret Manager (OpenBao)
 
 In production, avoid hardcoding secrets in files or environment variables.
-Use a secret manager like OpenBao, which provides Vault-compatible KV v2
+To reduce security risk, use a secret manager like OpenBao, which provides
+Vault-compatible KV v2
 storage (Vault is a widely used secrets manager; KV v2 is its versioned
 key/value secrets engine). For bootroot, store and inject:
 
@@ -96,19 +105,28 @@ logs in with AppRole and renders secrets to files:
 The `bootroot` CLI calls the OpenBao API only for **administrative actions**
 like init/rotate.
 
+#### OpenBao bootstrap and access
+
 OpenBao is initialized with **unseal keys** and a **root token**. Unseal keys
 unlock the storage on startup, while the root token grants full administrative
-access. After bootstrap, the OpenBao Agent authenticates using **AppRole**
-(role_id + secret_id) and receives short-lived tokens. Policies should grant
-only the minimum paths required (read-only for runtime services).
+access.
+
+#### Unseal keys custody
+
 Unseal keys are split using **shares (total)** and **threshold (required)**,
-and you must provide at least the threshold count to unseal.
-OpenBao generates the unseal keys and root token during initialization; an
-operator must capture and store them securely.
-They are needed later to unseal OpenBao after restarts and to perform
-administrative recovery or policy changes.
-AppRole `role_id` and `secret_id` are issued by OpenBao. `role_id` identifies
-the role and is stable, while `secret_id` is a credential that can be rotated.
+and you must provide at least the threshold count to unseal. OpenBao
+generates the unseal keys and root token during initialization; an operator
+must capture and store them securely. They are needed later to unseal
+OpenBao after restarts and to perform administrative recovery or policy
+changes.
+
+#### AppRole credentials
+
+After bootstrap, the OpenBao Agent authenticates using **AppRole**
+(role_id + secret_id) and receives short-lived tokens. Policies should grant
+only the minimum paths required (read-only for runtime services). AppRole
+`role_id` and `secret_id` are issued by OpenBao. `role_id` identifies the
+role and is stable, while `secret_id` is a credential that can be rotated.
 Operators deliver the initial values to services (or OpenBao Agent), and
 rotate `secret_id` as needed.
 
diff --git a/docs/en/configuration.md b/docs/en/configuration.md
index 1d675b2..af88061 100644
--- a/docs/en/configuration.md
+++ b/docs/en/configuration.md
@@ -13,6 +13,9 @@ the **manual configuration** flow.
 ## OpenBao Agent
 
 OpenBao Agent reads secrets from OpenBao and renders them to files.
+`agent.hcl` is the **OpenBao Agent configuration file**. It defines
+template/output paths and AppRole login details. It is not a secret file
+itself; OpenBao Agent uses it to render the actual secret files.
 `bootroot init` generates step-ca/responder agent configs at
 `secrets/openbao/stepca/agent.hcl` and `secrets/openbao/responder/agent.hcl`.
 `bootroot app add` prints the per-app OpenBao Agent config path, which
@@ -21,6 +24,51 @@ defaults to `secrets/openbao/apps/<service>/agent.hcl`.
 OpenBao Agent logs in via AppRole using `role_id`/`secret_id` stored under
 `secrets/apps/<service>/`. Keep the directory `0700` and the files `0600`.
 
+Ownership is split as follows:
+
+- **step-ca/responder**: `bootroot init` generates `agent.hcl` automatically.
+- **per-app agents**: `bootroot app add` prints the path and run guidance;
+  users place `agent.hcl` at that location and run the agent.
+
+Sample `agent.hcl` snippet:
+
+```hcl
+exit_after_auth = false
+pid_file = "/openbao/secrets/openbao/apps/edge-proxy/agent.pid"
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path = "/openbao/secrets/apps/edge-proxy/role_id"
+      secret_id_file_path = "/openbao/secrets/apps/edge-proxy/secret_id"
+    }
+  }
+  sink "file" {
+    config = {
+      path = "/openbao/secrets/openbao/apps/edge-proxy/token"
+    }
+  }
+}
+
+template {
+  source = "/openbao/secrets/openbao/apps/edge-proxy/agent.toml.ctmpl"
+  destination = "/openbao/secrets/apps/edge-proxy/agent.toml"
+}
+```
+
+This snippet is for **manual setup reference**. In the bootroot CLI
+workflow, the simplest path is to use the `agent.hcl` generated by
+`bootroot init`/`bootroot app add`.
+
+What each field means:
+
+- `exit_after_auth`: `true` exits after auth; `false` keeps the agent running.
+- `pid_file`: path to the agent PID file.
+- `auto_auth.method`: AppRole login config that reads `role_id`/`secret_id`.
+- `auto_auth.sink`: file path where the issued token is written.
+- `template`: renders config/secret files from OpenBao KV data.
+
 ## bootroot-agent (agent.toml)
 
 ### Global Settings
diff --git a/docs/en/index.md b/docs/en/index.md
index 75e53cc..a1de855 100644
--- a/docs/en/index.md
+++ b/docs/en/index.md
@@ -7,12 +7,6 @@ complete a full installation and issue certificates successfully. The
 bootroot CLI binary is `bootroot`, and the bootroot-agent binary is
 `bootroot-agent`.
 
-## CLI
-
-CLI usage is documented in the [CLI manual](cli.md). It covers core commands
-like `infra up/init/status`, `app add/verify`, and `rotate`. The rest of this
-manual focuses on the **manual setup** flow.
-
 ## What Bootroot Does
 
 Bootroot is a product-embedded PKI bootstrap layer. A bootstrap prepares the
@@ -20,15 +14,23 @@ initial environment so a system can start securely from day one. CA is short
 for **Certificate Authority**, the service that signs certificates to assert
 identity. ACME (Automated Certificate Management Environment) is the RFC 8555
 protocol used for automated issuance.
+Bootroot's role is to **automatically issue, renew, and rotate certificates**
+so services (daemon apps and docker apps) can communicate over mTLS.
 
 Components:
 
 - **step-ca**: A private ACME-compatible CA (open source)
 - **PostgreSQL**: The database server used by step-ca (open source)
 - **OpenBao**: Secrets manager for bootroot inputs and rotation (open source)
+- **OpenBao Agent**: Agent that renders OpenBao secrets to files (open source)
+- **bootroot CLI**: CLI tool that automates install, init, and operations
 - **bootroot-agent**: A Rust ACME client developed in this project
 - **HTTP-01 responder**: An HTTP-01 daemon developed in this project
 
+CA is short for **Certificate Authority**, the service that signs certificates
+to assert identity. ACME (Automated Certificate Management Environment) is the
+RFC 8555 protocol used for automated issuance.
+
 ## Manual Map
 
 - **CLI**: infra bring-up/initialization/status plus app onboarding,
@@ -41,29 +43,25 @@ Components:
 - **Operations**: Renewal, logs, backup, and security (including OpenBao)
 - **Troubleshooting / FAQ**: Common issues and answers
 
-## Architecture (High Level)
-
-1. bootroot-agent fetches the ACME directory from step-ca
-2. It registers an ACME account (optionally with EAB)
-3. It requests an order for a domain/SAN set
-4. It registers HTTP-01 tokens with the responder
-5. The responder serves HTTP-01 on port 80
-6. It finalizes the order and writes cert/key to disk
-7. It runs hooks and schedules renewals (daemon mode)
-8. OpenBao supplies secrets to bootroot components via rendered files
+CLI usage is documented in the [CLI manual](cli.md) and the
+[CLI examples](cli-examples.md). The CLI manual covers
+core commands like `infra up/init/status`, `app add/verify`, and `rotate`.
+The rest of this manual focuses on the **manual setup** flow.
 
-## Key Files in This Repo
+## Architecture (High Level)
 
-- `agent.toml.example`: Full multi-profile configuration example
-- `agent.toml.compose`: Example used by Docker Compose
-- `secrets/config/ca.json`: step-ca configuration (dev)
-- `openbao-agent/*.hcl`: OpenBao Agent templates (render secrets to files)
-- `scripts/update-ca-db-dsn.sh`: Update `ca.json` DB DSN from env
-- `docs/en/*` and `docs/ko/*`: Manual source
+1. OpenBao supplies secrets to bootroot components via rendered files
+2. bootroot-agent fetches the ACME directory from step-ca
+3. It registers an ACME account (optionally with EAB)
+4. It requests an order for a domain/SAN set
+5. It registers HTTP-01 tokens with the responder
+6. The responder serves HTTP-01 on port 80
+7. It finalizes the order and writes cert/key to disk
+8. It runs hooks and schedules renewals (daemon mode)
 
 ## Safety Notes
 
 - Do not commit production secrets to git.
-- Private keys should be `0600` and secret directories `0700`.
+- Secrets should be `0600` and secret directories `0700`.
 - Store OpenBao tokens/unseal keys in secure storage.
 - Use restricted network access between CA and PostgreSQL.
diff --git a/docs/ko/cli.md b/docs/ko/cli.md
index d057f0f..96ce6d4 100644
--- a/docs/ko/cli.md
+++ b/docs/ko/cli.md
@@ -125,7 +125,7 @@ bootroot init --auto-generate --eab-auto --responder-url http://localhost:8080
 
 ## bootroot status
 
-infra 및 OpenBao 상태를 점검합니다.
+infra 상태(컨테이너 포함)와 OpenBao KV/AppRole 상태를 점검합니다.
 
 ### 입력
 
@@ -168,6 +168,12 @@ bootroot status
 OpenBao Agent를 구동하고, 앱을 실행해 **앱 간 통신에서 발급된
 mTLS 인증서가 올바르게 사용되도록 구성**해야 합니다.
 
+앱이 다른 머신에서 실행된다면, 해당 머신에서 bootroot-agent가 같은
+`agent.toml`을 사용하도록 설정해야 합니다. `--cert-path`/`--key-path`
+도 앱이 실행되는 머신 기준으로 맞춰야 합니다. 이 명령은 경로/스니펫을
+안내할 뿐이며, 실제 설정 파일과 실행은 앱이 동작하는 머신에서
+진행해야 합니다.
+
 ### 입력
 
 입력 우선순위는 **CLI 옵션 > 환경 변수 > 프롬프트/기본값**입니다.
@@ -179,7 +185,7 @@ mTLS 인증서가 올바르게 사용되도록 구성**해야 합니다.
 - `--agent-config`: bootroot-agent 설정 파일 경로
 - `--cert-path`: 인증서 출력 경로
 - `--key-path`: 개인키 출력 경로
-- `--instance-id`: 앱 instance_id (daemon/docker 필수)
+- `--instance-id`: 앱 instance_id
 - `--container-name`: 도커 앱 컨테이너 이름 (docker 필수)
 - `--root-token`: OpenBao root token (환경 변수: `OPENBAO_ROOT_TOKEN`)
 - `--notes`: 메모(선택)
diff --git a/docs/ko/concepts.md b/docs/ko/concepts.md
index a646907..5e2bbab 100644
--- a/docs/ko/concepts.md
+++ b/docs/ko/concepts.md
@@ -15,6 +15,10 @@
 - **DNS**: `example.internal`
 - **IP**: `192.0.2.10`
 
+bootroot CLI 생태계에서는 다음 형식의 DNS SAN을 사용합니다(데몬/도커 동일):
+
+`<instance_id>.<service_name>.<hostname>.<domain>`
+
 ## mTLS
 
 서버와 클라이언트 모두 인증서를 제시하는 TLS 방식입니다.
@@ -48,7 +52,9 @@ ACME 흐름에서 자주 등장하는 개념은 다음과 같습니다.
 
 ## HTTP-01 챌린지
 
-HTTP-01은 **도메인 소유 확인 절차**입니다. CA가 **토큰**을 발급하고,
+HTTP-01은 **도메인 소유 확인 절차**입니다. 목적은 인증서가
+**실제 도메인 소유자**에게만 발급되도록 보장하는 것입니다. CA가
+**토큰**을 발급하고,
 해당 도메인으로 HTTP 요청을 보내 응답을 검증합니다.
 
 흐름:
@@ -64,8 +70,10 @@ HTTP-01은 **도메인 소유 확인 절차**입니다. CA가 **토큰**을 발
 
 ## EAB (External Account Binding)
 
-등록 제한이 필요한 CA에서 사용하는 방식입니다. `kid`와 `hmac`를
-제공해야 계정 등록이 허용됩니다.
+CA가 bootroot-agent와 같은 클라이언트의 계정 생성 요청을 제한하고자
+할 때 사용하는 방식입니다. 이때 **클라이언트**가
+CA로부터 발급받은 `kid`/`hmac`를 **계정 등록 요청 시** 제출해야
+등록이 허용됩니다.
 
 - `kid`(key ID): CA가 발급하는 EAB 키의 식별자입니다.
 - `hmac`: 외부 계정 바인딩에 사용하는 공유 HMAC 키입니다.
@@ -74,8 +82,9 @@ HTTP-01은 **도메인 소유 확인 절차**입니다. CA가 **토큰**을 발
 
 ## 시크릿 매니저(OpenBao)
 
-운영 환경에서는 시크릿을 파일이나 환경변수에 하드코딩하지 않고
-OpenBao 같은 시크릿 매니저에 저장해 주입합니다. OpenBao는
+운영 환경에서는 시크릿을 파일이나 환경변수에 하드코딩하지 않고,
+보안 위험을 줄이기 위해 OpenBao 같은 시크릿 매니저에 저장해
+주입하는 방식을 권장합니다. OpenBao는
 Vault 호환 KV v2 스토리지를 제공하며(Vault는 널리 쓰이는 시크릿 매니저,
 KV v2는 버전 관리되는 키/값 시크릿 엔진), bootroot에서는 다음 값을
 관리합니다.
@@ -99,21 +108,29 @@ AppRole로 로그인해 시크릿을 파일로 렌더링합니다. 주요 흐름
 `bootroot` CLI는 초기화/회전 같은 **관리 작업**에서만 OpenBao API를
 직접 호출합니다.
 
+#### OpenBao 초기화와 접속
+
 OpenBao는 **unseal keys**와 **root token**으로 초기화/접속합니다.
 unseal keys는 기동 시 스토리지를 해제하는 용도이고, root token은
-전체 관리자 권한을 부여합니다. 초기 설정 이후에는 OpenBao Agent가
-**AppRole**(role_id + secret_id)로 로그인해 짧은 TTL 토큰을 받고,
-필요한 경로만 읽도록 최소 권한 정책을 적용합니다.
+전체 관리자 권한을 부여합니다.
+
+#### unseal keys 보관
+
 unseal keys는 초기화 시 **shares(총 개수)**와 **threshold(필요 개수)**로
-분할되며, 언실 시에는 threshold 개수 이상이 필요합니다.
-unseal keys와 root token은 OpenBao 초기화 시 **OpenBao가 자동 생성**하며,
-운영자가 값을 안전하게 보관해야 합니다.
-이 값들은 재기동 시 언실(unseal)과 운영 중 복구/정책 변경 같은
-관리 작업에 필요합니다.
-AppRole의 `role_id`/`secret_id`는 OpenBao가 발급합니다. `role_id`는
-역할 식별자이며 고정값이고, `secret_id`는 로그인에 쓰는 자격증명으로
-재발급/회전이 가능합니다. 초기 값은 운영자가 서비스(OpenBao Agent)에
-전달하고, 이후에는 `secret_id`를 주기적으로 갱신합니다.
+분할되며, 언실 시에는 threshold 개수 이상이 필요합니다. unseal keys와
+root token은 초기화 시 **OpenBao가 자동 생성**하며, 운영자가 값을
+안전하게 보관해야 합니다. 이 값들은 재기동 시 언실(unseal)과 운영 중
+복구/정책 변경 같은 관리 작업에 필요합니다.
+
+#### AppRole 자격증명
+
+초기 설정 이후에는 OpenBao Agent가 **AppRole**(role_id + secret_id)로
+로그인해 짧은 TTL 토큰을 받고, 필요한 경로만 읽도록 최소 권한 정책을
+적용합니다. AppRole의 `role_id`/`secret_id`는 OpenBao가 발급합니다.
+`role_id`는 역할 식별자이며 고정값이고, `secret_id`는 로그인에 쓰는
+자격증명으로 재발급/회전이 가능합니다. 초기 값은 운영자가
+서비스(OpenBao Agent)에 전달하고, 이후에는 `secret_id`를 주기적으로
+갱신합니다.
 
 ### Dev-only 자동 언실(주의)
 
diff --git a/docs/ko/configuration.md b/docs/ko/configuration.md
index 16e9ca8..bdb8edb 100644
--- a/docs/ko/configuration.md
+++ b/docs/ko/configuration.md
@@ -13,6 +13,9 @@ CLI 사용법은 [CLI 문서](cli.md)에 정리되어 있습니다. 이 문서
 ## OpenBao Agent
 
 OpenBao Agent는 OpenBao에서 시크릿을 읽어 파일로 렌더링합니다.
+`agent.hcl`은 **OpenBao Agent 설정 파일**이며, 템플릿/출력 경로와
+AppRole 로그인 정보를 정의합니다. `agent.hcl` 자체가 시크릿 파일은 아니며,
+OpenBao Agent가 이 설정을 사용해 실제 시크릿 파일을 생성합니다.
 `bootroot init`은 step-ca/리스폰더용 `agent.hcl`을
 `secrets/openbao/stepca/agent.hcl`,
 `secrets/openbao/responder/agent.hcl`에 생성합니다.
@@ -23,6 +26,51 @@ OpenBao Agent는 `role_id`/`secret_id` 파일을 사용해 AppRole로 로그인
 해당 파일은 `secrets/apps/<service>/` 아래에 저장됩니다.
 디렉터리는 `0700`, 파일은 `0600` 권한을 유지해야 합니다.
 
+구성 책임은 다음과 같습니다.
+
+- **step-ca/리스폰더**: `bootroot init`이 `agent.hcl`을 자동 생성합니다.
+- **앱별 에이전트**: `bootroot app add`가 경로와 실행 안내를 출력하며,
+  사용자가 해당 경로에 `agent.hcl`을 배치해 실행합니다.
+
+예시 `agent.hcl` 스니펫:
+
+```hcl
+exit_after_auth = false
+pid_file = "/openbao/secrets/openbao/apps/edge-proxy/agent.pid"
+
+auto_auth {
+  method "approle" {
+    mount_path = "auth/approle"
+    config = {
+      role_id_file_path = "/openbao/secrets/apps/edge-proxy/role_id"
+      secret_id_file_path = "/openbao/secrets/apps/edge-proxy/secret_id"
+    }
+  }
+  sink "file" {
+    config = {
+      path = "/openbao/secrets/openbao/apps/edge-proxy/token"
+    }
+  }
+}
+
+template {
+  source = "/openbao/secrets/openbao/apps/edge-proxy/agent.toml.ctmpl"
+  destination = "/openbao/secrets/apps/edge-proxy/agent.toml"
+}
+```
+
+이 스니펫은 **수동 구성 시 참고용**입니다. bootroot CLI 생태계에서는
+`bootroot init`/`bootroot app add`가 생성한 `agent.hcl`을 사용하는 것이
+가장 간편합니다.
+
+구성 설명:
+
+- `exit_after_auth`: `true`면 토큰 발급 후 종료, `false`면 상시 실행합니다.
+- `pid_file`: 에이전트 PID 파일 경로입니다.
+- `auto_auth.method`: AppRole 로그인 설정이며 `role_id`/`secret_id` 파일을 읽습니다.
+- `auto_auth.sink`: 발급된 토큰을 파일로 저장하는 위치입니다.
+- `template`: OpenBao KV 값을 읽어 실제 설정/시크릿 파일을 렌더링합니다.
+
 ## bootroot-agent (agent.toml)
 
 ### 전역 설정
diff --git a/docs/ko/index.md b/docs/ko/index.md
index be8181d..92df1a8 100644
--- a/docs/ko/index.md
+++ b/docs/ko/index.md
@@ -6,28 +6,25 @@ PKI 배경 지식이 없는 사용자도 이 문서만으로 설치와 인증서
 완료할 수 있도록 구성했습니다. bootroot CLI 실행 파일은 `bootroot`,
 bootroot-agent 실행 파일은 `bootroot-agent`입니다.
 
-## CLI
-
-CLI 사용법은 [CLI 문서](cli.md)에 정리되어 있습니다.
-`infra up/init/status`, `app add/verify`, `rotate` 등 주요 명령을 다룹니다.
-이 매뉴얼의 나머지 섹션은 **CLI를 쓰지 않는 수동 절차**를 기준으로
-설명합니다.
-
 ## Bootroot가 하는 일
 
 Bootroot는 제품 내장형 PKI 부트스트랩 계층입니다. 부트스트랩은 시스템이 처음부터
 동작할 수 있도록 **초기 환경을 준비하고 구동을 시작하는 과정**을 의미합니다.
-CA는 **Certificate Authority**의 약어로, 인증서를 서명해 신원을 보증하는
-기관(또는 서비스)을 뜻합니다. ACME(Automated Certificate Management
-Environment)는 RFC 8555에서 정의된 표준 프로토콜입니다. 구성 요소는
-다음과 같습니다.
+Bootroot의 역할은 서비스(데몬 앱/도커 앱)가 **mTLS 통신을 수행할 수 있도록
+인증서를 자동 발급/갱신/회전**하는 것입니다. 구성 요소는 다음과 같습니다.
 
 - **step-ca**: ACME 호환 사설 CA (오픈 소스)
 - **PostgreSQL**: step-ca가 사용하는 DB 서버 (오픈 소스)
 - **OpenBao**: bootroot 시크릿을 관리/주입하는 시크릿 매니저 (오픈 소스)
+- **OpenBao Agent**: OpenBao 시크릿을 파일로 렌더링하는 에이전트 (오픈 소스)
+- **bootroot CLI**: 전체 설치/초기화/운영을 자동화하는 CLI 도구
 - **bootroot-agent**: 이 프로젝트에서 직접 개발한 Rust ACME 클라이언트
 - **HTTP-01 리스폰더**: 이 프로젝트에서 직접 개발한 HTTP-01 전용 데몬
 
+CA는 **Certificate Authority**의 약어로, 인증서를 서명해 신원을 보증하는
+기관(또는 서비스)을 뜻합니다. ACME(Automated Certificate Management
+Environment)는 RFC 8555에서 정의된 표준 프로토콜입니다.
+
 ## 매뉴얼 구성
 
 - **CLI**: infra 기동/초기화/상태 점검뿐 아니라 앱 온보딩, 발급 검증,
@@ -39,29 +36,25 @@ Environment)는 RFC 8555에서 정의된 표준 프로토콜입니다. 구성 
 - **운영**: 갱신, 로그, 백업, 보안(OpenBao 포함)
 - **문제 해결 / FAQ**: 자주 발생하는 오류와 답변
 
-## 아키텍처(요약)
-
-1. bootroot-agent가 step-ca의 ACME 디렉터리를 읽음
-2. ACME 계정을 등록(EAB 선택)
-3. 인증서 발급 주문 생성
-4. HTTP-01 토큰을 리스폰더에 등록
-5. 리스폰더가 포트 80에서 HTTP-01 응답
-6. 인증서 발급 및 파일 저장
-7. 훅 실행 및 주기적 갱신(데몬 모드)
-8. OpenBao가 렌더링한 파일로 시크릿을 주입
+CLI 사용법은 [CLI 문서](cli.md)와 [CLI 예제](cli-examples.md)에 정리되어 있습니다. CLI 문서에서는
+`infra up/init/status`, `app add/verify`, `rotate` 등 주요 명령을 다룹니다.
+이 매뉴얼의 나머지 섹션은 **CLI를 쓰지 않는 수동 절차**를 기준으로
+설명합니다.
 
-## 주요 파일
+## 아키텍처(요약)
 
-- `agent.toml.example`: 전체 설정 템플릿
-- `agent.toml.compose`: Docker Compose용 설정
-- `secrets/config/ca.json`: step-ca 설정(개발용)
-- `openbao-agent/*.hcl`: OpenBao Agent 템플릿(시크릿 파일 렌더링)
-- `scripts/update-ca-db-dsn.sh`: DB DSN 갱신 스크립트
-- `docs/en/*`, `docs/ko/*`: 매뉴얼 소스
+1. OpenBao가 렌더링한 파일로 시크릿을 주입
+2. bootroot-agent가 step-ca의 ACME 디렉터리를 읽음
+3. ACME 계정을 등록(EAB 선택)
+4. 인증서 발급 주문 생성
+5. HTTP-01 토큰을 리스폰더에 등록
+6. 리스폰더가 포트 80에서 HTTP-01 응답
+7. 인증서 발급 및 파일 저장
+8. 훅 실행 및 주기적 갱신(데몬 모드)
 
 ## 안전 수칙
 
 - 운영 시크릿은 git에 커밋하지 마세요.
-- 개인키는 `0600`, 시크릿 디렉터리는 `0700` 권한을 권장합니다.
+- 시크릿은 `0600`, 시크릿 디렉터리는 `0700` 권한을 권장합니다.
 - OpenBao 토큰/unseal 키는 별도 안전 저장소에 보관하세요.
 - CA와 DB 간 네트워크 접근을 제한하세요.