Update documentation

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)

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.
 

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

docs/en/index.md

@@ -7,28 +7,30 @@ 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
 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.

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`: 메모(선택)

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 자동 언실(주의)