docs: explain config and bitlesson systems

Author: zenus

README.md

@@ -55,6 +55,26 @@ Requires [codex CLI](https://github.com/openai/codex) for review. See the full [
    humanize monitor rlcr
    ```
 
+## Config System
+
+Humanize now uses a shared config hierarchy instead of scattering defaults across scripts.
+
+Priority is:
+1. `config/default_config.json`
+2. `~/.config/humanize/config.json`
+3. `.humanize/config.json`
+4. CLI flags for commands that expose overrides
+
+This keeps RLCR, PR loop, and `ask-codex` aligned on the same Codex defaults, while still letting each project pin its own behavior. The current config surface covers shared review settings such as `codex_model` and `codex_effort`, plus workflow toggles like `bitlesson_model`, `agent_teams`, and plan-generation preferences.
+
+## BitLesson System
+
+Humanize also includes a BitLesson system, which is the repository's Bitter Lesson-style knowledge capture workflow.
+
+Each project keeps a local knowledge base at `.humanize/bitlesson.md`. The RLCR setup initializes that file from a strict template when it is missing. During each round, the loop reads the knowledge base, runs a selector for every task or sub-task, and requires the round summary to include a `## BitLesson Delta` section describing whether a reusable lesson was added, updated, or intentionally left unchanged.
+
+The goal is to turn repeated failure-and-fix cycles into explicit project memory instead of rediscovering the same operational lessons every round.
+
 ## Monitor Dashboard
 
 <p align="center">

docs/usage.md

@@ -140,6 +140,17 @@ Humanize uses a 4-layer config hierarchy (lowest to highest priority):
 3. **Project config**: `.humanize/config.json`
 4. **CLI flags**: Command-line arguments (where available)
 
+Current built-in keys:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `codex_model` | `gpt-5.4` | Shared default model for Codex-backed review and analysis |
+| `codex_effort` | `high` | Shared default reasoning effort (`xhigh`, `high`, `medium`, `low`) |
+| `bitlesson_model` | `haiku` | Model used by the BitLesson selector agent |
+| `agent_teams` | `false` | Project-level default for agent teams workflow |
+| `chinese_plan` | `false` | Project preference for Chinese plan generation |
+| `gen_plan_mode` | `discussion` | Default plan-generation mode |
+
 ### Codex Model Configuration
 
 All Codex-using features (RLCR loop, PR loop, ask-codex) share the same model configuration:
@@ -154,7 +165,8 @@ To override, add to `.humanize/config.json`:
 ```json
 {
   "codex_model": "gpt-5.2",
-  "codex_effort": "xhigh"
+  "codex_effort": "xhigh",
+  "bitlesson_model": "sonnet"
 }
 ```
 
@@ -168,6 +180,43 @@ Codex model is resolved with this precedence:
 `loop_reviewer_model` or `loop_reviewer_effort`, they are silently ignored.
 Use `codex_model` and `codex_effort` instead.
 
+### BitLesson Configuration
+
+BitLesson is the repository's Bitter Lesson-style knowledge capture system for RLCR rounds.
+
+The selector reads `bitlesson_model` from the merged config. Provider routing is automatic:
+
+- `gpt-*`, `o1-*`, `o3-*` route to Codex
+- `claude-*`, `haiku`, `sonnet`, `opus` route to Claude
+
+If the configured provider binary is missing, the selector falls back to the default Codex model so the loop can still proceed.
+
+## BitLesson Workflow
+
+Each project keeps its BitLesson knowledge base at `.humanize/bitlesson.md`.
+
+When `start-rlcr-loop` begins:
+
+1. The file is initialized from `templates/bitlesson.md` if it does not already exist
+2. Each task or sub-task runs through `scripts/bitlesson-select.sh`
+3. The selected lesson IDs are applied during implementation, or `NONE` is recorded when nothing matches
+4. The stop gate validates a required `## BitLesson Delta` section in every round summary
+
+Required summary shape:
+
+```markdown
+## BitLesson Delta
+- Action: none|add|update
+- Lesson ID(s): <IDs or NONE>
+- Notes: <what changed and why>
+```
+
+Validation rules are strict:
+
+- `Action: none` must use `Lesson ID(s): NONE` or leave the field empty
+- `Action: add` and `Action: update` must reference concrete `BL-YYYYMMDD-short-name` IDs that exist in `.humanize/bitlesson.md`
+- `--require-bitlesson-entry-for-none` can be used to block empty knowledge bases from repeatedly reporting `none`
+
 ## Monitoring
 
 Set up the monitoring helper for real-time progress tracking: