From 5cf816da96849d3f9bc651b8a9bca8c096531845 Mon Sep 17 00:00:00 2001
From: Poby <87608318+smg1024@users.noreply.github.com>
Date: Mon, 16 Mar 2026 22:24:17 +0900
Subject: [PATCH] docs: update README and codex skills

---
 .codex/skills/readme/SKILL.md |  4 +-
 README-ko.md                  | 65 +++++++++++++++++-------------
 README.md                     | 74 +++++++++++++++++++++--------------
 3 files changed, 84 insertions(+), 59 deletions(-)

diff --git a/.codex/skills/readme/SKILL.md b/.codex/skills/readme/SKILL.md
index 428aead..9f13039 100644
--- a/.codex/skills/readme/SKILL.md
+++ b/.codex/skills/readme/SKILL.md
@@ -14,7 +14,7 @@ useful, project-specific content.
 ## Workflow
 
 1. Inspect repository facts before writing. Use targeted reads of `flake.nix`,
-   `Justfile`, `home/`, `modules/`, and `secrets/` plus recent git history. Do
+   `Justfile`, `home/`, `hosts/`, and `secrets/` plus recent git history. Do
    not invent commands, tools, or directory names.
 
 2. Select target file and language. Default target is `README.md` in English. If
@@ -40,7 +40,7 @@ useful, project-specific content.
 
 - Title and short description
 - Prerequisites (Nix/macOS assumptions when relevant)
-- Repository layout (`home/`, `modules/`, `secrets/`, root files)
+- Repository layout (`home/`, `hosts/`, `secrets/`, root files)
 - Key commands (`just darwin`, `just darwin-debug`, `just fmt`, update/cleanup
   commands)
 - Configuration and secrets notes (`.sops.yaml`, `secrets/*.yaml`)
diff --git a/README-ko.md b/README-ko.md
index 6d64346..4ad89d4 100644
--- a/README-ko.md
+++ b/README-ko.md
@@ -1,14 +1,14 @@
 # nix-darwin
 
-`nix-darwin`, `home-manager`, `nix-homebrew`, `sops-nix`를 사용해 호스트
-`fenrir`를 선언적으로 관리하는 macOS 설정 저장소입니다.
+`nix-darwin`, `home-manager`, `nix-homebrew`, `sops-nix` 기반의 선언적 macOS
+설정 저장소입니다.
 
 ## 이 저장소가 관리하는 것
 
-- 시스템 레벨 macOS 설정(`modules/`)
-- 사용자 레벨 도구 및 셸/에디터 설정(`home/`)
-- 선언적 Homebrew tap/app/cask
-- SOPS 기반 암호화 시크릿(`secrets/` + `.sops.yaml`)
+- `hosts/`의 시스템 레벨 macOS 설정
+- `home/`의 사용자 레벨 도구/셸/터미널/에디터 설정
+- `hosts/apps.nix`의 선언적 Homebrew tap/app/cask 관리
+- `secrets/` + `.sops.yaml`의 SOPS 암호화 시크릿
 
 ## 사전 요구사항
 
@@ -25,9 +25,13 @@
 
 - `flake.nix`: flake input/output 및 `darwinConfigurations`
 - `Justfile`: 일상 명령(`darwin`, `darwin-debug`, `fmt`, `up`, `gc` 등)
-- `modules/`: 시스템 모듈(`nix-core.nix`, `system.nix`, `apps.nix`,
-  `host-users.nix`)
-- `home/`: Home Manager 모듈(셸, git, nvf, 터미널, 도구)
+- `hosts/`: 시스템 모듈
+  - `default.nix`
+  - `nix-core.nix`
+  - `system.nix`
+  - `apps.nix`
+  - `host-users.nix`
+- `home/`: Home Manager 모듈(`git.nix`, `zsh.nix`, `nvf/`, `aerospace.nix` 등)
 - `secrets/`: 암호화된 시크릿 파일(`poby.yaml`)
 
 ## 자주 쓰는 명령
@@ -36,13 +40,13 @@
 # 사용 가능한 작업 보기
 just
 
-# 호스트용 빌드 및 스위치
+# 현재 머신 hostname 기준으로 빌드 및 스위치
 just darwin $(hostname)
 
-# 전체 trace와 함께 빌드 및 스위치
+# trace/verbose 로그와 함께 빌드 및 스위치
 just darwin-debug $(hostname)
 
-# Nix 파일 포맷팅(예: 저장소 전체)
+# Nix 파일 포맷팅(저장소 루트 기준)
 just fmt .
 
 # flake input 전체 업데이트
@@ -51,30 +55,37 @@ just up
 # 특정 input 하나만 업데이트
 just upp nixpkgs-darwin
 
-# 시스템 프로필 히스토리 확인
-just history
+# 스위치 없이 빌드 검증(예시 호스트: fenrir)
+nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'
 
-# 오래된 generation 정리 / 가비지 컬렉션
+# 시스템 프로필 히스토리 확인 / 오래된 generation 정리
+just history
 just clean
 just gc
 ```
 
+## 설정 노트
+
+- `flake.nix`는 현재 `hostname` 기반으로 하나의 `darwinConfigurations` 항목을
+  만들고, 시스템 모듈은 `./hosts`에서 import 합니다.
+- `home/default.nix`에서 사용자 모듈(셸, git, nvf, aerospace, sops, ssh)을
+  조합합니다.
+- Aerospace 멀티 모니터 워크스페이스 할당은 `home/aerospace.nix`에 있습니다.
+- 자주 업데이트되는 앱은 Homebrew 중심으로 `hosts/apps.nix`에서 관리합니다.
+
 ## 시크릿
 
-- 시크릿은 `secrets/*.yaml`에 암호화되어 저장됩니다.
-- `.sops.yaml`이 age 기반 암호화 규칙을 강제합니다.
-- Home Manager는 `secrets/poby.yaml`에서 아래 항목을 읽어 사용합니다:
+- 시크릿은 `secrets/*.yaml`에 암호화해서 보관합니다.
+- `.sops.yaml`이 `secrets/.*\.yaml`에 대한 암호화 규칙을 강제합니다.
+- Home Manager는 `home/sops.nix`를 통해 `secrets/poby.yaml`에서 아래 항목을
+  읽습니다.
   - `github_ssh_key`
   - `github_cli_token`
 
-## 커스터마이징 노트
-
-- `flake.nix`의 `hostname`, `username`, `useremail`을 환경에 맞게 수정하세요.
-- 새 시스템 동작은 `modules/*.nix`에 추가하세요.
-- 사용자 도구는 `home/*.nix`에 추가하고 `home/default.nix`에서 import 하세요.
-
 ## 트러블슈팅
 
-- 자세한 평가/빌드 출력이 필요하면 `just darwin-debug <hostname>`을 사용하세요.
-- 빌드는 성공했는데 동작이 반영되지 않으면 switch를 다시 실행하고 활성
-  host/config 값을 확인하세요.
+- 자세한 평가/빌드 로그가 필요하면 `just darwin-debug <hostname>`을 사용하세요.
+- 특정 호스트 평가가 실패하면 해당 호스트가 `darwinConfigurations`에 정의됐는지
+  확인하세요.
+- 빌드 성공 후에도 설정 반영이 이상하면 switch를 다시 실행하고 활성
+  hostname/config를 확인하세요.
diff --git a/README.md b/README.md
index c380130..6d6e1f4 100644
--- a/README.md
+++ b/README.md
@@ -2,20 +2,20 @@
 
 [한국어](README-ko.md)
 
-Declarative macOS setup for host `fenrir` using `nix-darwin`, `home-manager`,
-`nix-homebrew`, and `sops-nix`.
+Declarative macOS setup with `nix-darwin`, `home-manager`, `nix-homebrew`, and
+`sops-nix`.
 
 ## What This Repo Manages
 
-- System-level macOS configuration (`modules/`)
-- User-level tooling and shell/editor setup (`home/`)
-- Declarative Homebrew taps/apps/casks
+- System-level macOS configuration in `hosts/`
+- User-level tooling, shell, terminal, and editor config in `home/`
+- Declarative Homebrew taps/apps/casks in `hosts/apps.nix`
 - Encrypted secrets via SOPS (`secrets/` + `.sops.yaml`)
 
 ## Prerequisites
 
 - macOS on Apple Silicon (`aarch64-darwin`)
-- Nix with flakes (`nix-command` + `flakes`)
+- Nix with flakes enabled (`nix-command` + `flakes`)
 - `just` (command runner)
 - SOPS age key at:
 
@@ -26,10 +26,15 @@ Declarative macOS setup for host `fenrir` using `nix-darwin`, `home-manager`,
 ## Repository Layout
 
 - `flake.nix`: flake inputs/outputs and `darwinConfigurations`
-- `Justfile`: daily commands (`darwin`, `darwin-debug`, `fmt`, `up`, `gc`, etc.)
-- `modules/`: system modules (`nix-core.nix`, `system.nix`, `apps.nix`,
-  `host-users.nix`)
-- `home/`: Home Manager modules (shell, git, nvf, terminal, tools)
+- `Justfile`: day-to-day commands (`darwin`, `darwin-debug`, `fmt`, `up`, `gc`)
+- `hosts/`: system modules
+  - `default.nix`
+  - `nix-core.nix`
+  - `system.nix`
+  - `apps.nix`
+  - `host-users.nix`
+- `home/`: Home Manager modules (`git.nix`, `zsh.nix`, `nvf/`, `aerospace.nix`,
+  etc.)
 - `secrets/`: encrypted secret files (`poby.yaml`)
 
 ## Common Commands
@@ -38,46 +43,55 @@ Declarative macOS setup for host `fenrir` using `nix-darwin`, `home-manager`,
 # List available tasks
 just
 
-# Build and switch for a host
+# Build and switch for current machine hostname
 just darwin $(hostname)
 
-# Build and switch with full trace
+# Build and switch with trace/verbose logs
 just darwin-debug $(hostname)
 
-# Format Nix files (example: whole repo)
+# Format Nix files (from repository root)
 just fmt .
 
 # Update all flake inputs
 just up
 
-# Update one input
+# Update one flake input
 just upp nixpkgs-darwin
 
-# Inspect system profile history
-just history
+# Validate build without switching (example host: fenrir)
+nix build .#darwinConfigurations.fenrir.system --extra-experimental-features 'nix-command flakes'
 
-# Clean old generations / garbage collect
+# Inspect profile history / cleanup old generations
+just history
 just clean
 just gc
 ```
 
+## Configuration Notes
+
+- `flake.nix` currently defines one `darwinConfigurations` entry from
+  `hostname`, and imports system modules through `./hosts`.
+- `home/default.nix` composes user modules (shell, git, nvf, aerospace, sops,
+  ssh).
+- Aerospace multi-monitor workspace assignment lives in `home/aerospace.nix`.
+- Homebrew-first app management (for frequently updated apps) is in
+  `hosts/apps.nix`.
+
 ## Secrets
 
-- Secrets are encrypted in `secrets/*.yaml`.
-- `.sops.yaml` enforces age-based encryption rules.
-- Home Manager reads secrets from `secrets/poby.yaml` and exposes:
+- Keep secrets encrypted in `secrets/*.yaml`.
+- `.sops.yaml` enforces encryption rules for `secrets/.*\.yaml`.
+- Home Manager reads from `secrets/poby.yaml` via `home/sops.nix`:
   - `github_ssh_key`
   - `github_cli_token`
 
-## Customization Notes
-
-- Update `hostname`, `username`, and `useremail` in `flake.nix` for your
-  machine.
-- Add new system behavior in `modules/*.nix`.
-- Add user tooling in `home/*.nix` and import it from `home/default.nix`.
-
 ## Troubleshooting
 
-- Use `just darwin-debug <hostname>` for verbose evaluation/build output.
-- If a build succeeds but behavior is stale, re-run switch and verify active
-  host/config values.
+- Use `just darwin-debug <hostname>` for detailed evaluation/build output.
+- If evaluation fails for a host, verify it exists under `darwinConfigurations`.
+- If settings look stale after a successful build, run switch again and verify
+  active hostname/config values.
+
+## Milestone
+
+- [ ] `multi-host implementation`