gencode-ai 0.2.0 → 0.3.0

package/docs/config-system-comparison.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-GenCode implements a multi-level configuration system compatible with Claude Code, while also supporting OpenCode-style flexibility through the `GENCODE_CONFIG_DIRS` environment variable.
+GenCode implements a multi-level configuration system compatible with Claude Code, while also supporting OpenCode-style flexibility through the `GEN_CONFIG` environment variable.
 
 ## Table of Contents
 
@@ -29,19 +29,19 @@ Priority (High → Low):
 │  Scope: Current session only                                        │
 ├─────────────────────────────────────────────────────────────────────┤
 │  Level 4: Local (Personal)                                          │
-│  Location: .gencode/*.local.* + .claude/*.local.*                   │
+│  Location: .gen/*.local.* + .claude/*.local.*                   │
 │  Scope: Current user, current project only (gitignored)             │
 ├─────────────────────────────────────────────────────────────────────┤
 │  Level 3: Project (Shared)                                          │
-│  Location: .gencode/ + .claude/ (MERGED)                            │
+│  Location: .gen/ + .claude/ (MERGED)                            │
 │  Scope: All collaborators (committed to git)                        │
 ├─────────────────────────────────────────────────────────────────────┤
-│  Level 2: Extra Dirs (GENCODE_CONFIG_DIRS)                          │
+│  Level 2: Extra Dirs (GEN_CONFIG)                          │
 │  Location: Colon-separated paths from environment variable          │
 │  Scope: Team/organization shared configs                            │
 ├─────────────────────────────────────────────────────────────────────┤
 │  Level 1: User (Global) - LOWEST PRIORITY                           │
-│  Location: ~/.gencode/ + ~/.claude/ (MERGED)                        │
+│  Location: ~/.gen/ + ~/.claude/ (MERGED)                        │
 │  Scope: Current user, all projects                                  │
 └─────────────────────────────────────────────────────────────────────┘
 ```
@@ -69,7 +69,7 @@ Priority (High → Low):
     ║   同层级内合并 (claude 先加载，gencode 后加载覆盖):                            ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  claude  = load("~/.claude/settings.json")    // 低优先级           │   ║
-    ║   │  gencode = load("~/.gencode/settings.json")   // 高优先级           │   ║
+    ║   │  gencode = load("~/.gen/settings.json")   // 高优先级           │   ║
     ║   │  user    = deepMerge(claude, gencode)         // gencode 覆盖       │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
@@ -80,12 +80,12 @@ Priority (High → Low):
                     └──────────────────┬──────────────────┘
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
-    ║  STEP 2: Load EXTRA Config Dirs (可选，GENCODE_CONFIG_DIRS)                 ║
+    ║  STEP 2: Load EXTRA Config Dirs (可选，GEN_CONFIG)                 ║
     ╠═════════════════════════════════════════════════════════════════════════════╣
     ║                                                                             ║
-    ║   环境变量: GENCODE_CONFIG_DIRS="/team/config:~/shared-rules"               ║
+    ║   环境变量: GEN_CONFIG="/team/config:~/shared-rules"               ║
     ║                                                                             ║
-    ║   For each dir in GENCODE_CONFIG_DIRS.split(':'):                          ║
+    ║   For each dir in GEN_CONFIG.split(':'):                          ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  extra = load("{dir}/settings.json")                                │   ║
     ║   │  settings = deepMerge(settings, extra)                              │   ║
@@ -100,7 +100,7 @@ Priority (High → Low):
     ║   同层级内合并:                                                              ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  claude  = load(".claude/settings.json")      // 低优先级           │   ║
-    ║   │  gencode = load(".gencode/settings.json")     // 高优先级           │   ║
+    ║   │  gencode = load(".gen/settings.json")     // 高优先级           │   ║
     ║   │  project = deepMerge(claude, gencode)         // gencode 覆盖       │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
@@ -118,7 +118,7 @@ Priority (High → Low):
     ║   同层级内合并:                                                              ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  claude  = load(".claude/settings.local.json")  // 低优先级         │   ║
-    ║   │  gencode = load(".gencode/settings.local.json") // 高优先级         │   ║
+    ║   │  gencode = load(".gen/settings.local.json") // 高优先级         │   ║
     ║   │  local   = deepMerge(claude, gencode)           // gencode 覆盖     │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
@@ -181,7 +181,7 @@ Priority (High → Low):
     ║   │      namespace: "claude", enforced: true                            │   ║
     ║   │    })                                                               │   ║
     ║   │    if exists: memories.push({                                       │   ║
-    ║   │      content: load("/Library/.../GenCode/AGENT.md"),                │   ║
+    ║   │      content: load("/Library/.../GenCode/GEN.md"),                │   ║
     ║   │      namespace: "gencode", enforced: true                           │   ║
     ║   │    })                                                               │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
@@ -195,13 +195,13 @@ Priority (High → Low):
     ║   都加载 (先 claude 后 gencode):                                              ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  if exists: memories.push(load("~/.claude/CLAUDE.md"))              │   ║
-    ║   │  if exists: memories.push(load("~/.gencode/AGENT.md"))              │   ║
+    ║   │  if exists: memories.push(load("~/.gen/GEN.md"))              │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
     ║   同样加载 rules:                                                            ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  ~/.claude/rules/*.md  → memories.push(each)                        │   ║
-    ║   │  ~/.gencode/rules/*.md → memories.push(each)                        │   ║
+    ║   │  ~/.gen/rules/*.md → memories.push(each)                        │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
@@ -210,10 +210,10 @@ Priority (High → Low):
     ║  STEP 3: Load EXTRA Config Dirs Memory (可选)                               ║
     ╠═════════════════════════════════════════════════════════════════════════════╣
     ║                                                                             ║
-    ║   For each dir in GENCODE_CONFIG_DIRS:                                      ║
+    ║   For each dir in GEN_CONFIG:                                      ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  if exists: memories.push(load("{dir}/CLAUDE.md"))                  │   ║
-    ║   │  if exists: memories.push(load("{dir}/AGENT.md"))                   │   ║
+    ║   │  if exists: memories.push(load("{dir}/GEN.md"))                   │   ║
     ║   │  for each: memories.push(load("{dir}/rules/*.md"))                  │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
@@ -230,8 +230,8 @@ Priority (High → Low):
     ║   │  else if exists: memories.push(load("./.claude/CLAUDE.md"))         │   ║
     ║   │                                                                     │   ║
     ║   │  # GenCode files (pick first found)                                 │   ║
-    ║   │  if exists: memories.push(load("./AGENT.md"))                       │   ║
-    ║   │  else if exists: memories.push(load("./.gencode/AGENT.md"))         │   ║
+    ║   │  if exists: memories.push(load("./GEN.md"))                       │   ║
+    ║   │  else if exists: memories.push(load("./.gen/GEN.md"))         │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
@@ -243,7 +243,7 @@ Priority (High → Low):
     ║   加载规则目录 (都加载):                                                      ║
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  .claude/rules/*.md  → memories.push(each, namespace: "claude")     │   ║
-    ║   │  .gencode/rules/*.md → memories.push(each, namespace: "gencode")    │   ║
+    ║   │  .gen/rules/*.md → memories.push(each, namespace: "gencode")    │   ║
     ║   │                                                                     │   ║
     ║   │  支持 paths frontmatter 条件加载:                                    │   ║
     ║   │  ---                                                                │   ║
@@ -262,8 +262,8 @@ Priority (High → Low):
     ║   ┌─────────────────────────────────────────────────────────────────────┐   ║
     ║   │  if exists: memories.push(load("./CLAUDE.local.md"))                │   ║
     ║   │  if exists: memories.push(load("./.claude/CLAUDE.local.md"))        │   ║
-    ║   │  if exists: memories.push(load("./AGENT.local.md"))                 │   ║
-    ║   │  if exists: memories.push(load("./.gencode/AGENT.local.md"))        │   ║
+    ║   │  if exists: memories.push(load("./GEN.local.md"))                 │   ║
+    ║   │  if exists: memories.push(load("./.gen/GEN.local.md"))        │   ║
     ║   └─────────────────────────────────────────────────────────────────────┘   ║
     ║                                                                             ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
@@ -365,10 +365,10 @@ src/memory/
 
 | Aspect | GenCode | OpenCode | Claude Code |
 |--------|---------|----------|-------------|
-| **User Config Dir** | `~/.gencode/` + `~/.claude/` (merge) | `~/.config/opencode/` (XDG) | `~/.claude/` |
-| **Project Config Dir** | `.gencode/` + `.claude/` (merge) | `.opencode/` | `.claude/` |
+| **User Config Dir** | `~/.gen/` + `~/.claude/` (merge) | `~/.config/opencode/` (XDG) | `~/.claude/` |
+| **Project Config Dir** | `.gen/` + `.claude/` (merge) | `.opencode/` | `.claude/` |
 | **Config File Format** | JSON | JSON/JSONC/TOML | JSON |
-| **Memory File** | `AGENT.md` / `CLAUDE.md` | N/A (uses instructions) | `CLAUDE.md` |
+| **Memory File** | `GEN.md` / `CLAUDE.md` | N/A (uses instructions) | `CLAUDE.md` |
 | **Rules Dir** | `rules/*.md` | N/A | `rules/*.md` |
 
 ### Loading Semantics
@@ -390,10 +390,10 @@ src/memory/
 │  GenCode (6 levels):                 OpenCode (6 levels):    Claude Code (5):  │
 │  ─────────────────                   ────────────────────    ───────────────   │
 │  1. User                             1. Remote (well-known)  1. User           │
-│     ~/.claude/ + ~/.gencode/         2. Global (~/.config/)  2. Project        │
-│  2. Extra (GENCODE_CONFIG_DIRS)      3. OPENCODE_CONFIG      3. Local          │
+│     ~/.claude/ + ~/.gen/         2. Global (~/.config/)  2. Project        │
+│  2. Extra (GEN_CONFIG)      3. OPENCODE_CONFIG      3. Local          │
 │  3. Project                          4. Project              4. CLI            │
-│     .claude/ + .gencode/             5. .opencode/           5. Managed        │
+│     .claude/ + .gen/             5. .opencode/           5. Managed        │
 │  4. Local                            6. OPENCODE_CONFIG_CONTENT                │
 │     *.local.json                                                               │
 │  5. CLI                                                                        │
@@ -406,12 +406,12 @@ src/memory/
 
 #### 1. Dual Namespace Merge (GenCode Unique)
 
-GenCode loads **both** `.gencode/` and `.claude/` directories at each level and merges them:
+GenCode loads **both** `.gen/` and `.claude/` directories at each level and merges them:
 
 ```typescript
 // At User level:
 claude  = load("~/.claude/settings.json")     // lower priority
-gencode = load("~/.gencode/settings.json")    // higher priority
+gencode = load("~/.gen/settings.json")    // higher priority
 result  = deepMerge(claude, gencode)          // gencode wins on conflicts
 ```
 
@@ -419,10 +419,10 @@ OpenCode and Claude Code only use their own namespace.
 
 #### 2. Extra Config Dirs (GenCode Feature)
 
-GenCode supports `GENCODE_CONFIG_DIRS` for team/organization config:
+GenCode supports `GEN_CONFIG` for team/organization config:
 
 ```bash
-export GENCODE_CONFIG_DIRS="/team/shared-config:~/my-custom-rules"
+export GEN_CONFIG="/team/shared-config:~/my-custom-rules"
 ```
 
 OpenCode has `OPENCODE_CONFIG` for single file and `OPENCODE_CONFIG_CONTENT` for inline JSON.
@@ -430,7 +430,7 @@ OpenCode has `OPENCODE_CONFIG` for single file and `OPENCODE_CONFIG_CONTENT` for
 #### 3. Memory System (GenCode/Claude Code Feature)
 
 GenCode implements a full memory system like Claude Code:
-- `AGENT.md` / `CLAUDE.md` files
+- `GEN.md` / `CLAUDE.md` files
 - `rules/*.md` with path-scoped activation
 - `@import` syntax for file references
 
@@ -512,9 +512,9 @@ console.log(config.getDebugSummary());
 // Output:
 // Configuration Sources (in priority order):
 //   user:claude - ~/.claude/settings.json
-//   user:gencode - ~/.gencode/settings.json
+//   user:gencode - ~/.gen/settings.json
 //   project:claude - .claude/settings.json
-//   project:gencode - .gencode/settings.json
+//   project:gencode - .gen/settings.json
 ```
 
 ### Loading Memory
@@ -533,20 +533,20 @@ console.log(memory.getDebugSummary());
 // Output:
 // Memory Sources (in load order):
 //   user:claude - ~/.claude/CLAUDE.md (1024 bytes)
-//   user:gencode - ~/.gencode/AGENT.md (512 bytes)
+//   user:gencode - ~/.gen/GEN.md (512 bytes)
 //   project:claude - ./CLAUDE.md (2048 bytes)
-//   project:gencode - ./AGENT.md (1024 bytes)
+//   project:gencode - ./GEN.md (1024 bytes)
 ```
 
 ### Using Extra Config Dirs
 
 ```bash
 # Set up team config
-export GENCODE_CONFIG_DIRS="/team/shared-config"
+export GEN_CONFIG="/team/shared-config"
 
 # Create team settings
 echo '{"provider": "anthropic"}' > /team/shared-config/settings.json
-echo '# Team Guidelines' > /team/shared-config/AGENT.md
+echo '# Team Guidelines' > /team/shared-config/GEN.md
 
 # Run GenCode - it will merge team config
 npx gencode
@@ -557,12 +557,12 @@ npx gencode
 GenCode is fully backward compatible with Claude Code:
 
 1. Existing `.claude/` directories work automatically
-2. `CLAUDE.md` files are loaded alongside `AGENT.md`
+2. `CLAUDE.md` files are loaded alongside `GEN.md`
 3. No changes needed for existing Claude Code users
 
 To migrate:
-1. Optionally rename `.claude/` to `.gencode/`
-2. Optionally rename `CLAUDE.md` to `AGENT.md`
+1. Optionally rename `.claude/` to `.gen/`
+2. Optionally rename `CLAUDE.md` to `GEN.md`
 3. Or keep both - GenCode will merge them
 
 ## API Reference
@@ -626,19 +626,19 @@ class MemoryManager {
     ║  LEVEL 1: USER Settings                                                     ║
     ╠═════════════════════════════════════════════════════════════════════════════╣
     ║   claude  = load("~/.claude/settings.json")    // lower priority            ║
-    ║   gencode = load("~/.gencode/settings.json")   // higher priority           ║
+    ║   gencode = load("~/.gen/settings.json")   // higher priority           ║
     ║   user    = deepMerge(claude, gencode)                                      ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
-    ║  LEVEL 2: EXTRA Config Dirs (GENCODE_CONFIG_DIRS)                           ║
+    ║  LEVEL 2: EXTRA Config Dirs (GEN_CONFIG)                           ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
     ║  LEVEL 3: PROJECT Settings                                                  ║
     ╠═════════════════════════════════════════════════════════════════════════════╣
     ║   claude  = load(".claude/settings.json")      // lower priority            ║
-    ║   gencode = load(".gencode/settings.json")     // higher priority           ║
+    ║   gencode = load(".gen/settings.json")     // higher priority           ║
     ║   project = deepMerge(claude, gencode)                                      ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
@@ -671,33 +671,33 @@ class MemoryManager {
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
     ║  1. ENTERPRISE Memory (enforced)                                            ║
     ║     /Library/.../ClaudeCode/CLAUDE.md  →  push                              ║
-    ║     /Library/.../GenCode/AGENT.md      →  push                              ║
+    ║     /Library/.../GenCode/GEN.md      →  push                              ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
     ║  2. USER Memory                                                             ║
     ║     ~/.claude/CLAUDE.md  →  push                                            ║
-    ║     ~/.gencode/AGENT.md  →  push                                            ║
+    ║     ~/.gen/GEN.md  →  push                                            ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
-    ║  3. EXTRA Memory (GENCODE_CONFIG_DIRS)                                      ║
+    ║  3. EXTRA Memory (GEN_CONFIG)                                      ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
     ║  4. PROJECT Memory                                                          ║
     ║     ./CLAUDE.md or .claude/CLAUDE.md  →  push                               ║
-    ║     ./AGENT.md or .gencode/AGENT.md   →  push                               ║
+    ║     ./GEN.md or .gen/GEN.md   →  push                               ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
-    ║  5. RULES (.claude/rules/ + .gencode/rules/)                                ║
+    ║  5. RULES (.claude/rules/ + .gen/rules/)                                ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
     ╔══════════════════════════════════▼══════════════════════════════════════════╗
     ║  6. LOCAL Memory (*.local.md)                                               ║
     ║     ./CLAUDE.local.md  →  push                                              ║
-    ║     ./AGENT.local.md   →  push                                              ║
+    ║     ./GEN.local.md   →  push                                              ║
     ╚══════════════════════════════════╤══════════════════════════════════════════╝
                                        │
                               ┌────────▼────────┐

package/docs/cost-tracking-comparison.md

@@ -391,7 +391,7 @@ interface CostConfig {
 │ │   output: session.tokenUsage.output + 567,                   │    │
 │ │ }                                                              │    │
 │ │                                                               │    │
-│ │ 存储到: ~/.gencode/sessions/{id}.json                         │    │
+│ │ 存储到: ~/.gen/sessions/{id}.json                         │    │
 │ └─────────────────────────────────────────────────────────────┘    │
 └─────────────────────────────────────────────────────────────────────┘
                                 ↓
@@ -495,7 +495,7 @@ interface CostConfig {
 │ │ session.totalCost = (session.totalCost || 0) +               │    │
 │ │                      response.cost.totalCost;                 │    │
 │ │                                                               │    │
-│ │ 存储到: ~/.gencode/sessions/{id}.json                         │    │
+│ │ 存储到: ~/.gen/sessions/{id}.json                         │    │
 │ │   {                                                           │    │
 │ │     "id": "...",                                              │    │
 │ │     "tokenUsage": { "input": 1234, "output": 567 },          │    │

package/docs/memory-system.md

@@ -6,11 +6,11 @@ GenCode implements a hierarchical memory system compatible with Claude Code's CL
 
 | Level | Primary (GenCode) | Fallback (Claude Code) |
 |-------|-------------------|------------------------|
-| User | `~/.gencode/AGENT.md` | `~/.claude/CLAUDE.md` |
-| User Rules | `~/.gencode/rules/*.md` | `~/.claude/rules/*.md` |
-| Project | `./AGENT.md` or `./.gencode/AGENT.md` | `./CLAUDE.md` or `./.claude/CLAUDE.md` |
-| Project Rules | `./.gencode/rules/*.md` | `./.claude/rules/*.md` |
-| Local | `./.gencode/AGENT.local.md` | `./.claude/CLAUDE.local.md` |
+| User | `~/.gen/GEN.md` | `~/.claude/CLAUDE.md` |
+| User Rules | `~/.gen/rules/*.md` | `~/.claude/rules/*.md` |
+| Project | `./GEN.md` or `./.gen/GEN.md` | `./CLAUDE.md` or `./.claude/CLAUDE.md` |
+| Project Rules | `./.gen/rules/*.md` | `./.claude/rules/*.md` |
+| Local | `./.gen/GEN.local.md` | `./.claude/CLAUDE.local.md` |
 
 **Loading Logic**: Primary path is checked first; if not found, fallback path is used.
 
@@ -61,24 +61,24 @@ GenCode implements a hierarchical memory system compatible with Claude Code's CL
                                   ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │ 1. User Level                                                        │
-│    Primary:  ~/.gencode/AGENT.md                                     │
+│    Primary:  ~/.gen/GEN.md                                     │
 │    Fallback: ~/.claude/CLAUDE.md                                     │
-│    Rules:    ~/.gencode/rules/*.md → ~/.claude/rules/*.md            │
+│    Rules:    ~/.gen/rules/*.md → ~/.claude/rules/*.md            │
 └─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │ 2. Project Level                                                     │
-│    Primary:  ./AGENT.md or ./.gencode/AGENT.md                       │
+│    Primary:  ./GEN.md or ./.gen/GEN.md                       │
 │    Fallback: ./CLAUDE.md or ./.claude/CLAUDE.md                      │
-│    Rules:    ./.gencode/rules/*.md → ./.claude/rules/*.md            │
+│    Rules:    ./.gen/rules/*.md → ./.claude/rules/*.md            │
 │              (with paths: frontmatter for scoping)                   │
 └─────────────────────────────────────────────────────────────────────┘
                                   │
                                   ▼
 ┌─────────────────────────────────────────────────────────────────────┐
 │ 3. Local Level (gitignored)                                          │
-│    Primary:  ./.gencode/AGENT.local.md                               │
+│    Primary:  ./.gen/GEN.local.md                               │
 │    Fallback: ./.claude/CLAUDE.local.md                               │
 └─────────────────────────────────────────────────────────────────────┘
                                   │
@@ -102,34 +102,127 @@ GenCode implements a hierarchical memory system compatible with Claude Code's CL
 
 | Feature | Claude Code | GenCode |
 |---------|-------------|---------|
-| Primary filename | CLAUDE.md | AGENT.md |
+| Primary filename | CLAUDE.md | GEN.md |
 | Fallback support | No | Yes (→ CLAUDE.md) |
-| User directory | ~/.claude/ | ~/.gencode/ → ~/.claude/ |
-| Project directory | .claude/ | .gencode/ → .claude/ |
-| Rules directory | .claude/rules/ | .gencode/rules/ → .claude/rules/ |
+| User directory | ~/.claude/ | ~/.gen/ → ~/.claude/ |
+| Project directory | .claude/ | .gen/ → .claude/ |
+| Rules directory | .claude/rules/ | .gen/rules/ → .claude/rules/ |
 | Path scoping | Yes (paths: frontmatter) | Yes (paths: frontmatter) |
 | @import syntax | Yes | Yes (max 5 levels) |
-| Local files | CLAUDE.local.md | AGENT.local.md |
+| Local files | CLAUDE.local.md | GEN.local.md |
 | Directory-specific | Yes (on-demand) | Not in v1 |
 
+## Memory Merge Strategies
+
+GenCode supports multiple strategies for loading memory files when both CLAUDE.md and GEN.md exist at the same level. This allows you to optimize context size and control which files are loaded.
+
+### Available Strategies
+
+| Strategy | Behavior | Use Case |
+|----------|----------|----------|
+| `fallback` (default) | Load GEN.md if exists, else CLAUDE.md | **Recommended**: Reduces context size while maintaining flexibility |
+| `both` | Load both CLAUDE.md and GEN.md | Maximum context, useful when you need both file's content |
+| `gencode-only` | Only load .gen/GEN.md files | Strict GenCode-only mode |
+| `claude-only` | Only load .claude/CLAUDE.md files | Strict Claude Code compatibility mode |
+
+### How Fallback Works
+
+At each level (user, project, local), the system:
+1. Checks for `.gen/GEN.md` (or `./GEN.md` at project root)
+2. If found: Load GEN.md only, skip CLAUDE.md
+3. If not found: Load `.claude/CLAUDE.md` (or `./CLAUDE.md`) as fallback
+
+**Example:**
+```
+~/.claude/CLAUDE.md exists (global instructions)
+~/.gen/GEN.md does NOT exist
+./project1/.gen/GEN.md exists (project-specific)
+./project2/ has no GEN.md
+
+Loading for project1 (fallback mode):
+- User level: ~/.claude/CLAUDE.md (no ~/.gen/GEN.md)
+- Project level: ./project1/.gen/GEN.md (skip ./CLAUDE.md)
+= Result: Global + Project configs, ~50% context reduction
+
+Loading for project2 (fallback mode):
+- User level: ~/.claude/CLAUDE.md (no ~/.gen/GEN.md)
+- Project level: Nothing found
+= Result: Only global config, maximum context reduction
+```
+
+### Configuring the Strategy
+
+#### 1. Environment Variable (Highest Priority)
+
+```bash
+export GEN_MEMORY_STRATEGY=fallback  # or both, gencode-only, claude-only
+gencode "help me with this code"
+```
+
+#### 2. Settings File (User or Project Level)
+
+Add to `~/.gen/settings.json` or `./.gen/settings.json`:
+
+```json
+{
+  "memoryMergeStrategy": "fallback"
+}
+```
+
+#### 3. Default Behavior
+
+If not specified, defaults to `fallback` mode.
+
+### Verbose Mode
+
+See which files were loaded and skipped:
+
+```bash
+# Set verbose in config
+{
+  "verbose": true,
+  "memoryMergeStrategy": "fallback"
+}
+
+# Output shows:
+[Memory] Strategy: fallback
+[Memory] user: ~/.gen/GEN.md (0.1 KB)
+[Memory] project: ./GEN.md (3.2 KB)
+[Memory] Skipped: ~/.claude/CLAUDE.md
+[Memory] Total: 3.3 KB (2 files loaded, 1 skipped)
+```
+
+### Context Size Comparison
+
+Real-world example with both user and project memory:
+
+| Strategy | Files Loaded | Total Size | Savings |
+|----------|--------------|------------|---------|
+| `both` (old default) | CLAUDE.md + GEN.md (both levels) | 8.9 KB | Baseline |
+| `fallback` (new default) | GEN.md (user) + CLAUDE.md (project) | 3.4 KB | **61% reduction** |
+| `gencode-only` | GEN.md only | 0.1 KB | **99% reduction** |
+| `claude-only` | CLAUDE.md only | 8.7 KB | 2% reduction |
+
+**Recommendation**: Use `fallback` mode (default) for best balance between context size and flexibility. Only use `both` if you specifically need content from both files at the same level.
+
 ## Commands
 
 ### /init
 
-Analyzes your codebase and generates an AGENT.md file:
+Analyzes your codebase and generates an GEN.md file:
 
 ```
 > /init
 
 Analyzing codebase...
 Found 3 context file(s): package.json, README.md, tsconfig.json
-Generating AGENT.md...
+Generating GEN.md...
 ```
 
 The command:
 1. Scans for package.json, README.md, Makefile, etc.
 2. Builds a prompt asking the AI to generate project instructions
-3. Creates or updates AGENT.md via the Write tool
+3. Creates or updates GEN.md via the Write tool
 
 ### /memory
 
@@ -139,11 +232,11 @@ Shows all loaded memory files:
 > /memory
 
 Loaded Memory Files:
-  [1] ~/.gencode/AGENT.md (user, 1.2KB)
-  [2] ./AGENT.md (project, 856B)
+  [1] ~/.gen/GEN.md (user, 1.2KB)
+  [2] ./GEN.md (project, 856B)
 
 Loaded Rules:
-  [1] .gencode/rules/api.md (project-rules, 234B)
+  [1] .gen/rules/api.md (project-rules, 234B)
 ```
 
 ### # Quick Add
@@ -152,10 +245,10 @@ Add notes to memory directly:
 
 ```
 # Always use 2-space indentation
-Added to project memory: ./AGENT.md
+Added to project memory: ./GEN.md
 
 ## Prefer async/await over callbacks
-Added to user memory: ~/.gencode/AGENT.md
+Added to user memory: ~/.gen/GEN.md
 ```
 
 - `# note` → adds to project memory
@@ -163,12 +256,12 @@ Added to user memory: ~/.gencode/AGENT.md
 
 ## Rules Directory
 
-Create path-scoped rules in `.gencode/rules/`:
+Create path-scoped rules in `.gen/rules/`:
 
 ```
 your-project/
-├── .gencode/
-│   ├── AGENT.md           # Main project instructions
+├── .gen/
+│   ├── GEN.md           # Main project instructions
 │   └── rules/
 │       ├── code-style.md  # Always loaded
 │       ├── testing.md     # Always loaded
@@ -197,7 +290,7 @@ Rules with `paths:` frontmatter only load when working with matching files.
 Include other files in your memory files:
 
 ```markdown
-# AGENT.md
+# GEN.md
 
 @./docs/architecture.md
 @./docs/conventions.md
@@ -219,13 +312,13 @@ Memory content is injected into the system prompt:
 <claudeMd>
 Codebase and user instructions are shown below...
 
-Contents of ~/.gencode/AGENT.md (user's private global instructions):
+Contents of ~/.gen/GEN.md (user's private global instructions):
 [user memory content]
 
-Contents of ./AGENT.md (project instructions):
+Contents of ./GEN.md (project instructions):
 [project memory content]
 
-Rule from .gencode/rules/api.md (applies to: src/api/**):
+Rule from .gen/rules/api.md (applies to: src/api/**):
 [rule content]
 </claudeMd>
 ```
@@ -233,6 +326,6 @@ Rule from .gencode/rules/api.md (applies to: src/api/**):
 ## Best Practices
 
 1. **Keep memory concise** - Memory files are loaded every session
-2. **Use rules for path-specific guidance** - Avoid cluttering main AGENT.md
+2. **Use rules for path-specific guidance** - Avoid cluttering main GEN.md
 3. **Use local files for personal notes** - .gitignore automatically includes them
 4. **Leverage fallback for Claude Code users** - Existing CLAUDE.md files work automatically

package/docs/permissions.md

@@ -165,7 +165,7 @@ GenCode uses a multi-level configuration system (Claude Code compatible):
 | Project | `.claude/settings.json` | Project settings (tracked in git) |
 | Project local | `.claude/settings.local.json` | Project settings (gitignored) |
 
-**Fallback**: If `.claude/` doesn't exist, GenCode falls back to `.gencode/` directories.
+**Fallback**: If `.claude/` doesn't exist, GenCode falls back to `.gen/` directories.
 
 **Loading order**: User → Project → Project local (later overrides earlier for scalar values, arrays are concatenated)
 
@@ -231,7 +231,7 @@ When a tool requires confirmation, you can choose:
 2. **Yes, and don't ask again** - Add a persistent rule to project settings
 3. **No** - Block this operation
 
-When you select "don't ask again", the rule is saved to `.claude/settings.local.json` (or `.gencode/settings.local.json` if using GenCode directories).
+When you select "don't ask again", the rule is saved to `.claude/settings.local.json` (or `.gen/settings.local.json` if using GenCode directories).
 
 ## Prompt-Based Permissions