@wooojin/forgen 0.4.0 → 0.4.3

package/README.md

@@ -1,10 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wooo-jin/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
+  <img src="https://raw.githubusercontent.com/forgen-team/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
 </p>
 
 <p align="center">
-  <strong>When Claude says "done", forgen makes it prove it.</strong><br/>
-  Turn-level self-verification + personalized rules, at <strong>$0 extra API cost</strong>.
+  <strong>When your agent says "done", forgen makes it prove it.</strong><br/>
+  Turn-level self-verification + personalized rules for <strong>Claude Code</strong> and <strong>Codex CLI</strong>, at <strong>$0 extra API cost</strong>.
 </p>
 
 <p align="center">
@@ -18,6 +18,7 @@
   <a href="#quick-start">Quick Start</a> &middot;
   <a href="#how-it-works">How It Works</a> &middot;
   <a href="#4-axis-personalization">4-Axis</a> &middot;
+  <a href="#the-harness-carries-you">Harness Vision</a> &middot;
   <a href="#commands">Commands</a> &middot;
   <a href="#architecture">Architecture</a> &middot;
   <a href="#safety">Safety</a>
@@ -37,24 +38,28 @@
 You've been burned: Claude says "tests pass, implementation done" — you run it — it doesn't work. forgen closes that gap.
 
 ```
-You:     "Implement the login handler."
-Claude:  ...makes edits...
-Claude:  "구현 완료했습니다."
+You:     "Update the auth middleware."
+Claude:  ...makes edits to src/middleware/auth.ts...
+Claude:  "구현 완료. 신뢰도 95/100."
 
-[forgen:stop-guard/L1-e2e-before-done]
-Docker e2e 증거(~/.forgen/state/e2e-result.json, 1시간 이내)가 없습니다.
-지금 실행 후 재응답하라.
+[forgen:stop-guard/builtin:self-score-inflation]
+자가 점수 상승 선언 1건 (95/100). 측정 도구 호출 0회 — 숫자를 뒷받침할
+실행/확인 증거 없음. 테스트/빌드/curl 실행 결과를 턴에 포함해 재응답.
 
-Claude:  "완료 선언을 취소합니다. 증거 파일이 없습니다. e2e 를 먼저 실행합니다..."
-         ...runs bash tests/e2e/docker/run-test.sh...
-         "63/63 pass. 구현 완료했습니다."
+Claude:  "측정 없이 점수를 매겼습니다. 실 테스트부터 실행합니다..."
+         $ npm test
+         "31 passed / 0 failed. auth middleware 구현 완료."
 
 [forgen] ✓ approved
 ```
 
-**What just happened**: Claude's Stop hook was blocked by a rule you defined (`L1-e2e-before-done`). Claude read the block `reason`, retracted its premature claim, produced evidence, and re-submitted. **Zero extra API calls** — it all happened in the same session turn Claude was going to produce anyway.
+**What just happened**: Claude's Stop hook detected a score claim (`95/100`) without any measurement tool call (`Bash` / `NotebookEdit`) in the turn — one of forgen's **three built-in meta guards** (TEST-1 fact vs agreement, **TEST-2 self-score inflation**, TEST-3 conclusion/verification ratio). Claude read the block `reason`, retracted, ran the real test, and re-submitted. **Zero extra API calls** — it all happened in the same session turn Claude was going to produce anyway.
 
-This is **Mech-B self-check prompt-inject**. It works because Claude Code's Stop hook accepts `decision: "block"` + `reason`, and Claude in the next turn reads that reason as input. We verified it end-to-end on 10 scenarios at $1.74 total cost ([A1 spike report](docs/spike/mech-b-a1-verification-report.md)).
+The same mechanism also fires when Claude writes conclusions faster than evidence ("done. passed. shipped. verified." with no measurement context), or claims facts ("테스트가 통과합니다") without ever having executed them. You can also define **custom rules** (e.g. "require npm test evidence before saying 'done' in this repo") via `forgen compound --rule` — they slot into the same Stop-hook dispatcher.
+
+This is **Mech-B self-check prompt-inject**. It works because Claude Code's Stop hook accepts `decision: "block"` + `reason`, and Claude in the next turn reads that reason as input. Codex CLI gets the same treatment via the symmetric host adapter (v0.4.3, [multi-host core design](docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md)). We verified it end-to-end on 10 scenarios at $1.74 total cost ([A1 spike report](docs/spike/mech-b-a1-verification-report.md)), and v0.4.1 added built-in guards so you get the first block **without writing any rule**.
+
+> **v0.4.3 self-correction story:** the same guards detected their own 16-day false-positive (strict φ 65.66% — 84% from a single Korean-regex bug), and the [`forgen-eval`](packages/forgen-eval/) introspect testbed (alpha) flagged a `TEST-1` wiring gap on top of it. Both fixes shipped in v0.4.3 — forgen finding and fixing forgen. Details in [CHANGELOG](CHANGELOG.md).
 
 🎬 **See it happen** (27 seconds):
 
@@ -92,6 +97,31 @@ Forgen profiles your work style, learns from your corrections, and renders perso
 
 ---
 
+## The harness carries you
+
+Personalization is the surface. The deeper idea: **every session leaves a trace, and those traces compound into a harness that reasons like you do.** Your corrections, your conventions, your trade-off preferences — extracted from conversation, stored under `~/.forgen/me/`, and replayed back to Claude on every future session.
+
+```
+Conversation  ──►  Extracted: solution / rule / behavior / profile update
+                   ─────────────────────────────────────────────────────
+                                         │
+                                         ▼
+Next session  ◄──  Injected: UserPromptSubmit context + rendered rules
+                   + Stop-hook guards calibrated to *your* standards
+```
+
+After a few weeks this harness stops being "a tool that enforces rules" and starts being **a portable bundle of how you judge work**. One command exports it:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — your philosophy)
+forgen compound import <path>   # replay it on another machine
+```
+
+That's the north star: *a Claude on your laptop that judges like you do, and a tarball you can carry.*
+
+---
+
 ## What happens when you use forgen
 
 ### First run (one time, ~1 minute)
@@ -159,19 +189,59 @@ Updated rules are rendered with your corrections included. Compound knowledge is
 # 1. Install (MUST use -g — forgen is a global CLI)
 npm install -g @wooojin/forgen
 
-# 2. First run — 4-question onboarding (English or Korean)
-forgen
+# 2. Register forgen on your host(s) — Claude Code, Codex, or both
+forgen install both         # 3-choice interactive: claude / codex / both
+# or non-interactive:
+forgen install claude
+forgen install codex
 
-# 3. Every day after that
-forgen
+# 3. First run — 4-question onboarding (English or Korean)
+forgen                       # default: Claude
+forgen --runtime codex       # use Codex
+forgen config default-host codex   # set persistent default
 ```
 
 ### Prerequisites
 
 - **Node.js** >= 20 (>= 22 recommended for SQLite session search)
-- **Claude Code** installed and authenticated (`npm i -g @anthropic-ai/claude-code`)
+- **At least one host** installed and authenticated:
+  - **Claude Code** — `npm i -g @anthropic-ai/claude-code`
+  - **Codex CLI** — install per [Codex docs](https://github.com/openai/codex)
+  - Or both — `forgen install both` registers symmetric hooks/MCP for each
+
+> **Vendor dependency:** Forgen wraps Claude Code and Codex CLI symmetrically (Claude is the behavior reference; Codex extends with equivalence). Upstream API/CLI changes may affect behavior. Tested with Claude Code 1.0.x / 2.1.x and Codex 0.x.
 
-> **Vendor dependency:** Forgen wraps Claude Code. Anthropic API or Claude Code changes may affect behavior. Tested with Claude Code 1.0.x.
+### Isolated / CI / Docker usage
+
+Forgen's home directory is `~/.forgen` by default, but can be overridden per-process:
+
+```bash
+# Fresh isolated home — does NOT touch your real ~/.forgen
+FORGEN_HOME=/tmp/forgen-clean forgen init       # provisions 15-solution starter pack
+FORGEN_HOME=/tmp/forgen-clean forgen stats      # shows stats from the isolated home
+FORGEN_HOME=/tmp/forgen-clean claude -p "..."   # hooks inherit the env → isolated logs
+```
+
+Claude Code hook processes inherit the parent env, so any `claude` command
+prefixed with `FORGEN_HOME=...` routes all state (rules, solutions, behavior,
+enforcement logs) into that directory. Useful for:
+
+- CI pipelines validating forgen against a pinned seed set
+- Reproducing buyer-first-day experience without polluting your real home
+- Running multiple personas on one machine
+
+**Docker / remote servers (OAuth limitation):** Claude Code stores its OAuth
+session in the **OS keychain** (macOS Keychain / libsecret / Windows Credential
+Manager). Mounting `~/.claude.json` alone is **not enough** in a fresh Linux
+container because the keychain-bound refresh is missing. For container use, set
+`ANTHROPIC_API_KEY` in the container env instead. Host-native usage (macOS,
+Linux workstations) works with the normal `claude login` flow — no API key
+needed.
+
+### Migrations
+
+`forgen migrate implicit-feedback` backfills the `category` field on pre-v0.4.1
+entries in `~/.forgen/state/implicit-feedback.jsonl`. Idempotent — safe to re-run.
 
 ---
 
@@ -283,7 +353,11 @@ Claude has your accumulated patterns in context while drafting the response.
 
 Precision gates (v0.3.2+): matches below relevance 0.3 or with only a single
 common-word tag overlap are filtered before injection so Claude's context
-doesn't get polluted by low-signal hits.
+doesn't get polluted by low-signal hits. **Cold-start boost (v0.4.1+)**: when
+your outcome history has < 5 champion/active solutions (first days after
+install), the injection threshold is relaxed to 0.2 so starter-pack solutions
+can actually surface; once your own patterns accumulate the threshold returns
+to the standard 0.3.
 
 ### 10 built-in skills
 
@@ -314,7 +388,7 @@ Curated, compound-native skills. Each integrates with your accumulated knowledge
 | `architecture-decision` | "adr" | Weighted trade-off matrix, ADR lifecycle, reversibility classification |
 | `docker` | "docker", "컨테이너" | Multi-stage builds, security hardening, 10 failure modes
 
-### 12 built-in agents
+### 13 built-in agents
 
 Sub-agents with physically separated tool access, `Failure_Modes_To_Avoid` sections, and Good/Bad examples. Invoked via `Agent(subagent_type: "ch-<name>")`. The `ch-` prefix avoids collisions with OMC / built-in Claude Code agents.
 
@@ -333,6 +407,7 @@ Sub-agents with physically separated tool access, `Failure_Modes_To_Avoid` secti
 | Agent | Model | Role |
 |-------|:-----:|------|
 | `ch-planner` | Opus | Strategic planning — decomposes tasks, identifies risks, creates actionable plans |
+| `ch-solution-evolver` | Opus | Propose 3 novel compound-solution candidates from a weakness report (Phase 4 evolution loop) |
 
 **Write-enabled (implementation / verification):**
 
@@ -491,7 +566,9 @@ forgen forge --export           # Export profile
 ### Inspection
 
 ```bash
-forgen stats                    # One-screen trust-layer dashboard (rules, corrections, blocks 7d)
+forgen stats                    # Trust-layer dashboard (rules, corrections, blocks 7d, assist today, philosophy)
+forgen recall [--limit N] [--show]
+                                # Recent compound recalls surfaced to Claude (with body preview)
 forgen last-block               # Most recent block event with rule detail
 forgen inspect profile          # 4-axis profile with packs and facets
 forgen inspect rules            # Active and suppressed rules
@@ -530,7 +607,9 @@ forgen skill list               # List promoted skills
 ### System
 
 ```bash
-forgen init                     # Initialize project
+forgen init                     # Initialize project (+ 15 starter-pack solutions)
+forgen migrate [implicit-feedback|all]
+                                # One-shot schema migrations (idempotent)
 forgen doctor                   # System diagnostics (10 categories + harness maturity)
 forgen doctor --prune-state     # Daily hygiene: state GC + T4 rule decay (90d idle → retire)
 forgen dashboard                # Knowledge overview (6 sections)
@@ -690,7 +769,27 @@ Safety rules are **hard constraints** -- they cannot be overridden by pack selec
 
 Forgen detects other Claude Code plugins (oh-my-claudecode, superpowers, claude-mem) at install time and automatically reduces its context injection by 50% ("yielding principle"). Core safety and compound hooks always remain active. Conflicting skills are skipped when another plugin already provides them.
 
-See [Coexistence Guide](docs/guides/with-omc.md) for details.
+### Better with claude-mem (recommended pairing)
+
+forgen and [claude-mem](https://github.com/thedotmack/claude-mem) solve **complementary** halves of the trust gap:
+
+| | forgen | claude-mem |
+|---|---|---|
+| **Job** | Enforcement — block unverified claims | Recall — inject relevant past sessions |
+| **Trigger** | Stop / PreToolUse hooks | UserPromptSubmit hook |
+| **Cost** | $0 (in-turn block/reason) | $0 (vector recall, local) |
+
+Install both as separate Claude Code plugins (Plugin model — forgen does not bundle claude-mem; AGPL-3.0 stays at arm's length). When both are present forgen's auto-detect yields context budget so claude-mem's recall has room to land, and the orchestration contract — order, failure isolation, Stop-hook ownership — is documented in [ADR-004](docs/adr/ADR-004-claude-mem-hook-orchestration.md). The pairing is one of the 5 arms tracked by [forgen-eval](packages/forgen-eval/) (see [claude-mem spike](docs/spike/2026-04-28-claude-mem-spike.md)).
+
+```
+You:        "fix the auth flow"
+claude-mem: ↓ recalls past auth-flow session, injects 3 relevant chunks
+forgen:     ↓ matches your "no mock as proof" rule, primes Stop guard
+Claude:     edits → declares done → forgen Stop hook blocks (no test ran)
+            → re-runs test → approved
+```
+
+See [Coexistence Guide](docs/guides/with-omc.md) for the full plugin-detection matrix.
 
 ---
 
@@ -700,6 +799,9 @@ See [Coexistence Guide](docs/guides/with-omc.md) for details.
 |----------|-------------|
 | [Hooks Reference](docs/reference/hooks-reference.md) | 19 hooks across 3 tiers — events, timeouts, behavior |
 | [Coexistence Guide](docs/guides/with-omc.md) | Using forgen alongside oh-my-claudecode |
+| [forgen-eval testbed](packages/forgen-eval/) | Alpha self-measurement package — multi-host parity, 7-axis metrics, drift detection (private workspace, v0.4.3+) |
+| [Multi-host core design](docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md) | Codex/Claude symmetric host adapter spec |
+| [ADR-005 forgen-eval architecture](docs/adr/ADR-005-forgen-eval-module-architecture.md) | Self-measurement testbed module design |
 | [CHANGELOG](CHANGELOG.md) | Version history and release notes |
 
 ---

package/README.zh.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/wooo-jin/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
+  <img src="https://raw.githubusercontent.com/forgen-team/forgen/main/assets/banner.png" alt="Forgen" width="100%"/>
 </p>
 
 <p align="center">
@@ -18,6 +18,7 @@
   <a href="#快速开始">快速开始</a> &middot;
   <a href="#工作原理">工作原理</a> &middot;
   <a href="#4轴个性化">4轴</a> &middot;
+  <a href="#这个-harness-装载的是你">愿景</a> &middot;
   <a href="#命令">命令</a> &middot;
   <a href="#架构">架构</a> &middot;
   <a href="#安全">安全</a>
@@ -92,6 +93,31 @@ forgen 实现了这一切。它对你的工作风格进行画像、从你的纠
 
 ---
 
+## 这个 harness 装载的是你
+
+个性化只是表面。更深层的想法:**每次会话都留下痕迹,这些痕迹累积起来成为一个像你一样判断的 harness。** 你的修正、你的规范、你的权衡偏好 — 从对话中提取,存储在 `~/.forgen/me/` 下,并在每次后续会话中回放给 Claude。
+
+```
+对话          ──►  提取: solution / rule / behavior / profile 更新
+                    ────────────────────────────────────────────
+                                       │
+                                       ▼
+下一次会话    ◄──  注入: UserPromptSubmit 上下文 + 渲染的规则
+                    + 校准到你标准的 Stop-hook 守卫
+```
+
+几周之后,这个 harness 不再是"强制执行规则的工具",而是 **承载你如何判断工作的可携带包裹**。一条命令导出:
+
+```bash
+forgen compound export    # → forgen-knowledge-YYYY-MM-DD.tar.gz
+                          #   (rules + solutions + behavior — 你的哲学)
+forgen compound import <path>   # 在另一台机器上重放
+```
+
+这就是北极星:*你的笔记本上,一个像你一样判断的 Claude,还有你能随身携带的 tarball。*
+
+---
+
 ## 使用 forgen 会发生什么
 
 ### 首次运行（仅一次，约1分钟）
@@ -156,22 +182,30 @@ Claude 调用 `correction-record` MCP 工具。纠正作为结构化证据存储
 ## 快速开始
 
 ```bash
-# 1. 安装
+# 1. 安装 (必须 -g — forgen 是全局 CLI)
 npm install -g @wooojin/forgen
 
-# 2. 首次运行 — 4题引导问卷（英语/韩语选择）
-forgen
+# 2. 注册主机 — Claude Code / Codex / 两者
+forgen install both          # 三选交互: claude / codex / both
+# 或非交互:
+forgen install claude
+forgen install codex
 
-# 3. 此后每天
-forgen
+# 3. 首次运行 — 4题引导问卷 (英语/韩语选择)
+forgen                        # 默认: Claude
+forgen --runtime codex        # 使用 Codex
+forgen config default-host codex   # 设置持久默认主机
 ```
 
 ### 前提条件
 
-- **Node.js** >= 20（SQLite 会话搜索推荐 >= 22）
-- **Claude Code** 已安装并认证（`npm i -g @anthropic-ai/claude-code`）
+- **Node.js** >= 20 (SQLite 会话搜索推荐 >= 22)
+- **至少安装一个主机** 并认证:
+  - **Claude Code** — `npm i -g @anthropic-ai/claude-code`
+  - **Codex CLI** — 参考 [Codex docs](https://github.com/openai/codex)
+  - 也可同时使用 — `forgen install both` 对两者对称注册 hook/MCP
 
-> **厂商依赖:** forgen 封装了 Claude Code。Anthropic API 或 Claude Code 的变更可能影响其行为。已在 Claude Code 1.0.x 版本下测试。
+> **厂商依赖:** forgen 对称包装 Claude Code 与 Codex CLI (Claude 为行为基准, Codex 以等价性扩展)。上游 API/CLI 变更可能影响行为。已在 Claude Code 1.0.x / 2.1.x、Codex 0.x 下测试。
 
 ---
 

package/assets/README.md

@@ -0,0 +1,86 @@
+# assets/ — 자산 분리 매핑 (§7.2)
+
+> 출처: `docs/superpowers/specs/2026-04-27-forgen-multi-host-core-design.md` §7.2  
+> 상태: 1차 매핑 문서 박제 (실 이동 미완료)  
+> 작성일: 2026-04-27
+
+---
+
+## 목표 디렉토리 구조
+
+```
+assets/
+  claude/     Claude 전용 자산 (manifest, agents, commands, hooks 등록 manifest)
+  codex/      Codex 전용 자산 (hooks.json 머지 템플릿, config 스니펫 등)
+  shared/     호스트 무관 공통 자산 (hook 스크립트 본체, 이미지 등)
+```
+
+현재 `assets/` 루트에 있는 이미지/SVG/데모 파일은 **공통 자산**으로, 향후 `assets/shared/`로 이동합니다.
+
+---
+
+## 자산 매핑 표
+
+| 현재 위치 | 목표 위치 | 이동 단계 | 비고 |
+|---|---|---|---|
+| `agents/*.md` | `assets/claude/agents/` | **2차 PR** | Claude Code 전용 서브에이전트 정의. Codex는 `AGENTS.md` 모델이므로 codex/ 동치 미정 |
+| `commands/*.md` | `assets/claude/commands/` | **2차 PR** | Claude Code slash-command 원본. skills/ 생성의 소스 역할 |
+| `skills/{name}/SKILL.md` | `assets/claude/skills/` | **2차 PR** | copy-assets.js 가 commands/ 를 변환하여 생성. Claude Code plugin 표준 |
+| `hooks/hooks.json` | `assets/claude/hooks/hooks.json` + `assets/codex/hooks.json` | **2차 PR** | hooks.json schema 가 Claude/Codex 동일 (§18.4 확인). Codex 등록 시 절대경로 pre-expand 필요 (§18.5) |
+| `hooks/hook-registry.json` | `assets/shared/hook-registry.json` | **2차 PR** | 호스트 무관 메타데이터. 양쪽 어댑터가 동일 registry 참조 |
+| `assets/banner.png` | `assets/shared/banner.png` | **2차 PR** | 호스트 무관 이미지 자산 |
+| `assets/banner.svg` | `assets/shared/banner.svg` | **2차 PR** | 동상 |
+| `assets/architecture.svg` | `assets/shared/architecture.svg` | **2차 PR** | 동상 |
+| `assets/icon.png` | `assets/shared/icon.png` | **2차 PR** | 동상 |
+| `assets/demo-preview.svg` | `assets/shared/demo-preview.svg` | **2차 PR** | 동상 |
+| `assets/demo/*` | `assets/shared/demo/` | **2차 PR** | 동상 |
+| `dist/hooks/*.js` (빌드 산출물) | 이동 없음 — InstallPlan에서 절대경로 inject | **해당 없음** | hook 스크립트 본체는 host 무관 node 스크립트. Claude/Codex 양쪽이 동일 경로를 가리킴 (§14.2) |
+
+### Claude 전용 자산 (`assets/claude/`)
+
+- Claude Code plugin manifest (`plugin.json`)
+- `agents/*.md` — Claude Code 서브에이전트 정의
+- `commands/*.md` — slash-command 원본
+- `skills/` — Claude Code plugin 표준 (commands 에서 자동 생성)
+- `hooks/hooks.json` — `${CLAUDE_PLUGIN_ROOT}` 환경변수 참조 버전 (Claude 전용)
+
+### Codex 전용 자산 (`assets/codex/`)
+
+- `hooks.json` — 절대경로 pre-expand 버전. `~/.codex/hooks.json` 에 머지할 템플릿
+- `config-snippet.toml` — `~/.codex/config.toml` 의 `[mcp_servers]` 등록 스니펫
+- (Phase 2) Codex `AGENTS.md` 템플릿 — `skills/commands/agents` 의 Codex 등치 (미확정)
+
+### 공통 자산 (`assets/shared/`)
+
+- `hook-registry.json` — 호스트 무관 hook 메타데이터 레지스트리
+- `dist/hooks/*.js` — 런타임에 절대경로로 inject (실제 파일 이동 없음)
+- 이미지/SVG/데모 파일 일체
+
+---
+
+## 마이그레이션 단계
+
+### 1차 PR (현재 — 이동 없음)
+- [x] 이 README 박제 — 매핑 의도 문서화
+- [x] `agents/`, `commands/`, `skills/`, `hooks/` 에 이동 예정 주석 추가
+- [ ] `scripts/copy-assets.js` 에 TODO 주석 추가 (다음 작업)
+
+### 2차 PR (실 이동)
+- `agents/`, `commands/`, `skills/` → `assets/claude/`
+- `hooks/hooks.json` → `assets/claude/hooks/hooks.json` (Claude 버전)
+- `hooks/hook-registry.json` → `assets/shared/hook-registry.json`
+- 이미지/SVG/데모 → `assets/shared/`
+- Codex hooks 템플릿 → `assets/codex/hooks.json`
+
+### 3차 PR (어댑터 연동)
+- `scripts/copy-assets.js` 의 소스 경로를 새 구조로 갱신
+- Claude InstallPlan: `assets/claude/` → `~/.claude/plugins/cache/...`
+- Codex InstallPlan: `assets/codex/hooks.json` → 절대경로 pre-expand → `~/.codex/hooks.json` 머지
+
+---
+
+## 호환성 메모
+
+- **hooks.json schema 동일성 (§18.4)**: forgen의 현재 `hooks/hooks.json` 형식이 Codex `~/.codex/hooks.json` schema와 완전 동일. 단, `${CLAUDE_PLUGIN_ROOT}` 환경변수는 Codex에서 자동 주입되지 않으므로 절대경로 pre-expand 필수 (§18.5).
+- **agents/commands/skills Codex 동치 미정**: Codex의 prompt 자산 모델은 `AGENTS.md` / `requirements.toml` 중심으로 forgen `skills/commands/agents` 의 직접 대응 표면이 없음. Phase 2 InstallPlan에서 결정.
+- **실 패키지 분리는 3단계 이후**: 현재는 단일 패키지 유지. 구조만 분리 가능한 상태로 준비 (§7.3).

package/assets/architecture.svg

@@ -0,0 +1,100 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 420" fill="none">
+  <defs>
+    <linearGradient id="bg2" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0f0f23" />
+      <stop offset="100%" style="stop-color:#1a1a3e" />
+    </linearGradient>
+  </defs>
+
+  <rect width="720" height="420" rx="12" fill="url(#bg2)"/>
+
+  <!-- Title -->
+  <text x="360" y="35" text-anchor="middle" font-family="'SF Mono', monospace" font-size="14" fill="#ffffff" opacity="0.6" letter-spacing="4">3-LAYER ARCHITECTURE</text>
+
+  <!-- Layer 0: Philosophy -->
+  <rect x="40" y="55" width="640" height="95" rx="8" fill="#f59e0b" fill-opacity="0.08" stroke="#f59e0b" stroke-opacity="0.4" stroke-width="1.5"/>
+  <text x="60" y="80" font-family="'SF Mono', monospace" font-size="13" font-weight="700" fill="#fbbf24">Layer 0 &#x2014; Philosophy (WHY)</text>
+  <text x="60" y="100" font-family="'Inter', sans-serif" font-size="12" fill="#fde68a" opacity="0.8">philosophy.yaml &#x2192; Declare your principles</text>
+
+  <g transform="translate(60, 110)">
+    <rect width="145" height="28" rx="4" fill="#f59e0b" fill-opacity="0.12"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#fbbf24">understand-before-act</text>
+  </g>
+  <g transform="translate(215, 110)">
+    <rect width="145" height="28" rx="4" fill="#f59e0b" fill-opacity="0.12"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#fbbf24">decompose-to-control</text>
+  </g>
+  <g transform="translate(370, 110)">
+    <rect width="148" height="28" rx="4" fill="#f59e0b" fill-opacity="0.12"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#fbbf24">capitalize-on-failure</text>
+  </g>
+  <g transform="translate(528, 110)">
+    <rect width="142" height="28" rx="4" fill="#f59e0b" fill-opacity="0.12"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#fbbf24">focus-resources</text>
+  </g>
+
+  <!-- Arrow -->
+  <line x1="360" y1="155" x2="360" y2="170" stroke="#ffffff" stroke-width="1" opacity="0.3"/>
+  <polygon points="355,168 360,178 365,168" fill="#ffffff" opacity="0.3"/>
+
+  <!-- Layer 1: Workflow Engine -->
+  <rect x="40" y="180" width="640" height="105" rx="8" fill="#6366f1" fill-opacity="0.08" stroke="#6366f1" stroke-opacity="0.4" stroke-width="1.5"/>
+  <text x="60" y="205" font-family="'SF Mono', monospace" font-size="13" font-weight="700" fill="#a78bfa">Layer 1 &#x2014; Workflow Engine (HOW)</text>
+  <text x="60" y="225" font-family="'Inter', sans-serif" font-size="12" fill="#c4b5fd" opacity="0.8">Auto-generated from principles: modes, routing, hooks, monitoring</text>
+
+  <g transform="translate(60, 238)">
+    <rect width="90" height="28" rx="4" fill="#6366f1" fill-opacity="0.15"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#a78bfa">9 Modes</text>
+  </g>
+  <g transform="translate(160, 238)">
+    <rect width="100" height="28" rx="4" fill="#6366f1" fill-opacity="0.15"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#a78bfa">3-Tier Route</text>
+  </g>
+  <g transform="translate(270, 238)">
+    <rect width="100" height="28" rx="4" fill="#6366f1" fill-opacity="0.15"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#a78bfa">14 Hooks</text>
+  </g>
+  <g transform="translate(380, 238)">
+    <rect width="100" height="28" rx="4" fill="#6366f1" fill-opacity="0.15"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#a78bfa">Monitoring</text>
+  </g>
+  <g transform="translate(490, 238)">
+    <rect width="120" height="28" rx="4" fill="#6366f1" fill-opacity="0.15"/>
+    <text x="10" y="18" font-family="monospace" font-size="10" fill="#a78bfa">Compound Loop</text>
+  </g>
+
+  <!-- Arrow -->
+  <line x1="360" y1="290" x2="360" y2="305" stroke="#ffffff" stroke-width="1" opacity="0.3"/>
+  <polygon points="355,303 360,313 365,303" fill="#ffffff" opacity="0.3"/>
+
+  <!-- Layer 2: Pack -->
+  <rect x="40" y="315" width="640" height="90" rx="8" fill="#10b981" fill-opacity="0.08" stroke="#10b981" stroke-opacity="0.4" stroke-width="1.5"/>
+  <text x="60" y="340" font-family="'SF Mono', monospace" font-size="13" font-weight="700" fill="#34d399">Layer 2 &#x2014; Pack (KNOW + SHARE)</text>
+  <text x="60" y="360" font-family="'Inter', sans-serif" font-size="12" fill="#6ee7b7" opacity="0.8">Domain knowledge &amp; sharing across scopes</text>
+
+  <g transform="translate(60, 370)">
+    <rect width="80" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="14" y="17" font-family="monospace" font-size="11" fill="#34d399">Me</text>
+  </g>
+  <g transform="translate(150, 370)">
+    <rect width="80" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="14" y="17" font-family="monospace" font-size="11" fill="#34d399">Team</text>
+  </g>
+  <g transform="translate(240, 370)">
+    <rect width="80" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="14" y="17" font-family="monospace" font-size="11" fill="#34d399">Project</text>
+  </g>
+
+  <g transform="translate(380, 370)">
+    <rect width="80" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="10" y="17" font-family="monospace" font-size="10" fill="#34d399">Solutions</text>
+  </g>
+  <g transform="translate(470, 370)">
+    <rect width="70" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="10" y="17" font-family="monospace" font-size="10" fill="#34d399">Rules</text>
+  </g>
+  <g transform="translate(550, 370)">
+    <rect width="80" height="26" rx="4" fill="#10b981" fill-opacity="0.12"/>
+    <text x="10" y="17" font-family="monospace" font-size="10" fill="#34d399">Manuals</text>
+  </g>
+</svg>

package/assets/banner.svg

@@ -0,0 +1,53 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" fill="none">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0f0f23;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#1a1a3e;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#f97316" />
+      <stop offset="50%" style="stop-color:#ef4444" />
+      <stop offset="100%" style="stop-color:#f59e0b" />
+    </linearGradient>
+    <linearGradient id="glow" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#f97316;stop-opacity:0.3" />
+      <stop offset="100%" style="stop-color:#f97316;stop-opacity:0" />
+    </linearGradient>
+  </defs>
+
+  <rect width="800" height="200" rx="12" fill="url(#bg)"/>
+
+  <!-- Decorative line -->
+  <line x1="60" y1="160" x2="740" y2="160" stroke="url(#accent)" stroke-width="1" opacity="0.4"/>
+
+  <!-- Subtle grid -->
+  <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+    <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#ffffff" stroke-width="0.3" opacity="0.05"/>
+  </pattern>
+  <rect width="800" height="200" fill="url(#grid)"/>
+
+  <!-- Symbol: Anvil + Flame -->
+  <g transform="translate(80, 50)">
+    <!-- Flame -->
+    <path d="M45,5 Q55,25 48,40 Q60,30 55,15 Q65,35 50,50 Q42,50 35,45 Q25,35 30,15 Q35,30 42,40 Q35,25 45,5Z" fill="url(#accent)" opacity="0.8"/>
+    <!-- Anvil -->
+    <path d="M20,60 L70,60 L75,70 Q45,75 15,70 Z" fill="#ffffff" opacity="0.9"/>
+    <rect x="30" y="52" width="30" height="10" rx="2" fill="#ffffff" opacity="0.7"/>
+  </g>
+
+  <!-- Title -->
+  <text x="200" y="95" font-family="'SF Mono', 'Fira Code', 'JetBrains Mono', monospace" font-size="52" font-weight="700" fill="#ffffff" letter-spacing="8">FORGEN</text>
+
+  <!-- Subtitle -->
+  <text x="200" y="125" font-family="'Inter', 'Helvetica Neue', sans-serif" font-size="15" fill="#f59e0b" letter-spacing="3" opacity="0.9">CODE, FORGED FOR YOU</text>
+
+  <!-- Tag -->
+  <rect x="200" y="138" width="160" height="22" rx="4" fill="#f97316" opacity="0.15"/>
+  <text x="210" y="153" font-family="'SF Mono', monospace" font-size="11" fill="#f59e0b" opacity="0.8">Personalize.</text>
+
+  <rect x="370" y="138" width="140" height="22" rx="4" fill="#f97316" opacity="0.15"/>
+  <text x="380" y="153" font-family="'SF Mono', monospace" font-size="11" fill="#f59e0b" opacity="0.8">Forge workflow.</text>
+
+  <rect x="520" y="138" width="150" height="22" rx="4" fill="#f97316" opacity="0.15"/>
+  <text x="530" y="153" font-family="'SF Mono', monospace" font-size="11" fill="#f59e0b" opacity="0.8">Compound growth.</text>
+</svg>

package/assets/demo/01-install.tape

@@ -0,0 +1,54 @@
+# forgen — Install & First Run Demo
+# Shows: npm install → forgen doctor → starter pack loaded
+
+Output assets/demo/01-install.gif
+
+Set Shell "zsh"
+Set FontFamily "JetBrains Mono"
+Set FontSize 16
+Set Width 1200
+Set Height 600
+Set Padding 20
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 40ms
+Set WindowBar Colorful
+Set BorderRadius 10
+Set Margin 20
+Set MarginFill "#1e1e2e"
+
+# Setup (hidden)
+Hide
+Type "cd /tmp && mkdir forgen-demo && cd forgen-demo && git init -q && npm init -y -q 2>/dev/null && clear"
+Enter
+Sleep 1s
+Show
+
+# Step 1: Install
+Type "npm i -g forgen"
+Sleep 500ms
+Enter
+Sleep 5s
+
+# Step 2: Doctor check
+Type "forgen doctor"
+Sleep 500ms
+Enter
+Sleep 3s
+
+# Step 3: Show starter pack
+Type "ls ~/.compound/me/solutions/ | head -5"
+Sleep 500ms
+Enter
+Sleep 2s
+
+# Step 4: Show available skills
+Type "ls ~/.claude/commands/forgen/ | head -10"
+Sleep 500ms
+Enter
+Sleep 3s
+
+# Done
+Type "# Ready! 15 starter solutions + 19 skills loaded"
+Sleep 500ms
+Enter
+Sleep 3s