docs: document context minification feature and principles

Author: apiad

docs/design.md

@@ -17,6 +17,7 @@ These scripts are registered in `.gemini/settings.json` and intercept the turn-b
 - **`log.py`:** Provides a comprehensive audit trail of every interaction, logging structured markers for `BeforeAgent`, `AfterModel`, and `AfterTool` events.
 - **`notify.py`:** Sends a desktop notification and plays a system sound once the agent completes its turn, ensuring the user is alerted when the agent is waiting for input.
 - **`cron.py`:** Synchronizes the `cron.toml` task definitions with **systemd user timers** for background execution.
+- **`minifier.py`:** A `BeforeModel` hook that performs **Context Minification**. It identifies redundant `<instruction>` blocks from previous turns and replaces them with a lightweight placeholder, preserving only the most recent instruction to maximize token efficiency and prevent context saturation during long sessions.
 
 #### **B. Git Hooks**
 These are linked to the repository's `.git/hooks/` directory and manage the finality of changes.

docs/develop.md

@@ -72,7 +72,9 @@ Failure to do this will block your commit or turn execution.
 
 ## ✅ Testing & Quality Standards
 
-- **Agent-Driven Validation:** This project maintains a **minimalist, transient testing philosophy**. Instead of a static suite of thousands of unit tests, it relies on high-discipline agent execution and **Grounded Experimentation** to verify behavior in real-time.
+- **Automated Context Minification:** To ensure maximum token efficiency and prevent context saturation during long sessions, the framework automatically identifies and replaces redundant `<instruction>` blocks from previous turns with a placeholder. Only the *latest* instruction is passed to the model in its full form, ensuring the agent stays focused on the current task while maintaining structural operational context.
+- **Agent-Driven Validation:** This project maintains a **minimalist, transient testing philosophy**.
+ Instead of a static suite of thousands of unit tests, it relies on high-discipline agent execution and **Grounded Experimentation** to verify behavior in real-time.
 - **On-the-Fly Verification:** During the mandatory TCR (Test-Commit-Revert) loop, the agent is required to write specific, temporary test cases (e.g., `test_feature_x.py`) that verify the granular step being implemented.
 - **Source of Truth:** The `makefile` is the central definition of project health. Even if it initially points to an empty `test` target, it serves as the hook point for the agent's automated validation.
 - **The TCR Mandate:** The primary mechanism for ensuring "Green-only" development is the mandatory **Test-Commit-Revert** loop. If a change fails its temporary verification, it is instantly reverted, ensuring the `main` branch remains a "known-good" state.

docs/index.md

@@ -47,6 +47,7 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 - **Deep Discovery:** Use `/research` for multi-phase domain investigations.
 - **Knowledge Mastering:** Use `/learn` to explore and codify new libraries or topics into permanent project skills.
 - **Semantic Tier Routing (The Tier Protocol):** Optimizes for intelligence, cost, and speed by mapping specialized agents (`planner`, `debugger`, `learner`, `reviewer`) to high-reasoning models.
+- **Automated Context Optimization:** Proactively minifies historical instructions to maintain high token efficiency during long, complex sessions.
 - **Architectural Planning:** Use `/plan` to generate persistent, actionable strategies.
 - **Forensic Debugging:** Use `/debug` for root-cause analysis without immediate (and potentially incorrect) fixes.
 - **Automated Documentation:** Use `/document` to keep the documentation synchronized with the evolving codebase.

docs/user-guide.md

@@ -15,6 +15,7 @@ This framework solves this problem by enforcing three core principles:
 1.  **The important things should be made explicit:** We keep track of everything important in Markdown files. Ideas are committed to `plans/`, research is summarized in `research/`, and all changes are logged in the `journal/`. This physical "long-term memory" prevents the agent from forgetting context.
 2.  **Resist the urge to guess:** We favor explicit commands over implicit actions. If you want the model to make a plan, you use the `/plan` command, which invokes a carefully crafted workflow rather than relying on the agent's default behavior.
 3.  **Delegate, delegate, delegate:** We use specialized sub-agents (`planner`, `researcher`, `writer`, `reviewer`, `coder`). These agents run complex, multi-step tasks in private contexts, preventing their internal reasoning (e.g., browsing 20 web pages) from polluting the main session's context window.
+4.  **Automated Context Optimization:** The framework proactively manages its own "attention span" via the **Context Minifier**. As your session grows, it surgically replaces redundant `<instruction>` blocks from previous turns with a lightweight placeholder, preserving only the most recent command to ensure the model remains efficient and responsive without losing the thread of the project's history.
 
 ---
 

journal/2026-03-24.md

@@ -10,3 +10,4 @@
 [2026-03-24T14:51:22] - Implement Context Minifier system to prune redundant instructions
 [2026-03-24T14:53:39] - Release v0.22.0: context minifier, procedural tasks, and multi-model routing
 [2026-03-24T15:20:45] - refine document command workflow for targeted inspection
+[2026-03-24T15:21:52] - document context minification feature and principles