docs(core): update documentation suite for v0.19.0 improvements

Author: apiad

README.md

@@ -58,6 +58,7 @@ The `.gemini/commands/` directory defines specialized workflows that automate ev
 
 ### 🔍 Phase 1: Planning & Discovery
 *   **`/research <topic>`**: A deep, 3-phase investigation (Planning -> Data Gathering -> Reporting) that produces exhaustive Markdown reports in the `research/` directory. **Crucial for gathering technical requirements and state-of-the-art context.**
+*   **`/learn <topic>`**: A grounded learning lifecycle (Audit -> Strategic Mapping -> Execution -> Codification) for mastering new technologies and building a permanent, machine-readable knowledge base in `.gemini/skills/`.
 *   **`/plan`**: The **Architectural Bridge**. This interactive workflow translates ideas into actionable execution plans:
     *   **Phase 1 (Clarification):** The agent interviews you to resolve ambiguities before planning.
     *   **Phase 2 (Agentic Analysis):** A specialized `planner` subagent scans the codebase and generates a detailed technical strategy.
@@ -107,12 +108,14 @@ This framework shines when you combine these commands into cohesive workflows:
 
 ## ⚓ The Hook System
 
-The framework uses a robust hook system (`.gemini/hooks/`) that synchronizes the agent with your project state:
+The framework uses a dual-layer hook system to synchronize the agent with your project state:
 
-*   **`session.py`**: Initializes the environment and provides a project summary.
-*   **`journal.py`**: Ensures a journal entry exists for the current date (`journal/YYYY-MM-DD.md`).
-*   **`make.py`**: Automatically runs `make` after critical agent actions to prevent regressions.
-*   **`cron.py`**: Synchronizes `cron.toml` tasks with **systemd user timers**.
+*   **`session.py` / `welcome.py`**: Initialize the environment, provide a project summary, and check for environment readiness.
+*   **`log.py`**: Provides a comprehensive, structured audit trail of every agent turn and tool execution.
+*   **`notify.py`**: Sends a desktop notification and sound when the agent completes its work, minimizing downtime.
+*   **`cron.py`**: Synchronizes repetitive tasks with **systemd user timers**.
+*   **`pre-commit.py` (Git Hook)**: Enforces daily journaling and timestamp-based validation before any code changes are finalized.
+*   **`journal.py` (Script)**: The dedicated utility for correctly formatting and appending new journal entries.
 
 ## 📄 License & Contribution
 

docs/design.md

@@ -8,19 +8,27 @@ The project's "brain" resides in the `.gemini/` directory, which is organized in
 
 ### 1. The Hook System (`.gemini/hooks/`)
 
-Hooks are Python-based scripts that intercept the Gemini CLI turn lifecycle. They are the framework's primary enforcement mechanism.
+The framework uses a dual-layer hook system to enforce standards and automate workflows.
 
-- **`welcome.py`:** Initializes the session and provides a project summary to the agent. It also checks for the presence of the pre-commit hook and alerts the user if missing.
-- **`pre-commit.py`:** Enforces the mandatory daily journaling and **timestamp-based validation** before any code changes are finalized.
-- **`make.py`:** Automatically runs the `makefile` (tests/linting) to prevent regressions.
-- **`notify.py`:** Sends a desktop notification after each agent turn is successfully completed and validated.
-- **`utils.py`:** Provides a shared set of utilities for git status analysis and communication with the CLI.
+#### **A. Gemini CLI Lifecycle Hooks**
+These scripts are registered in `.gemini/settings.json` and intercept the turn-by-turn lifecycle of the agent.
+
+- **`session.py` / `welcome.py`:** Initialize the session, provide a project summary, and check for environment readiness (e.g., verifying if Git hooks are installed).
+- **`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.
+
+#### **B. Git Hooks**
+These are linked to the repository's `.git/hooks/` directory and manage the finality of changes.
+
+- **`pre-commit.py`:** The primary enforcement mechanism. It performs **timestamp-based validation**, ensuring that a journal entry exists for the current date and that its timestamp is newer than any modified files. It also serves as the trigger for project-wide health checks.
+- **`utils.py`:** A shared Python library providing common functions for git analysis, hook decisions, and communication with the Gemini CLI.
 
 ### 2. The Script Utility System (`.gemini/scripts/`)
 
 Helper scripts that standardize framework operations across different environments.
 
-- **`journal.py`:** A dedicated script to correctly format and append new journal entries (`[timestamp ISO] - description`). This ensures consistency and prevents AI hallucinations of dates or formats.
+- **`journal.py`:** A dedicated script to correctly format and append new journal entries (`[timestamp ISO] - description`). This is the **only recommended way** to update the journal, as it ensures temporal consistency for the `pre-commit.py` hook.
 
 ### 3. The Command System (`.gemini/commands/`)
 
@@ -29,6 +37,7 @@ Commands define structured, multi-phase workflows that automate the development
 - **`/plan`:** An interactive workflow that transitions between clarification, analysis, and strategy generation.
 - **`/research`:** A deep-dive exploration that produces exhaustive reports in the `research/` directory.
 - **`/debug`:** Activates a **forensic investigation mode** using a scientific, hypothesis-driven workflow.
+- **`/learn`:** A grounded learning lifecycle for mastering new technologies and codifying them into project skills.
 - **`/document`:** Analyzes the codebase and project state to update the documentation suite.
 - **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the **strict TCR (Test-Commit-Revert) loop** and feature branch isolation.
 
@@ -68,7 +77,8 @@ Instead of a single "do-it-all" AI, the framework delegates tasks to specialized
 
 - **`planner`:** Responsible for high-level architectural design and roadmap generation.
 - **`debugger`:** A forensic investigation specialist using a scientific, hypothesis-driven workflow.
-- **`learner`:** A "Grounded Learning Specialist" who master new technologies by writing, executing, and documenting code experiments.
+- **`learner`:** A "Grounded Learning Specialist" who masters new technologies by writing, executing, and documenting code experiments.
+- **`researcher`:** Optimized for deep information gathering and multi-source synthesis.
 - **`reporter` / `editor`:** Content generation and refinement specialists.
 
 ### 5. The Skill System (`.gemini/skills/`)
@@ -78,7 +88,7 @@ The framework's permanent knowledge base. Each skill is a directory containing:
 - **`reference-*.md`:** Granular documentation for specific learning objectives.
 - **`assets/`:** Idiomatic, verified code examples and experiment scripts.
 
-### 4. State Management
+### 6. State Management
 
 The framework maintains internal state to optimize operations and ensure continuity:
 

docs/develop.md

@@ -56,15 +56,19 @@ Failure to do this will block your commit or turn execution.
 
 ## ✅ Testing & Quality Standards
 
-- **Agent-Driven Validation:** This project does **not** maintain a traditional suite of unit or integration tests (e.g., in a `tests/` directory). Instead, it relies on high-discipline agent execution and **Grounded Experimentation** to verify behavior.
-- **Source of Truth:** The `makefile` is the central definition of project health.
-- **TCR Protocol:** The primary mechanism for ensuring "Green-only" development is the mandatory **Test-Commit-Revert** loop during task execution.
+- **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.
 
 ## 🧠 Codifying Knowledge with Skills
 
-The `/learn` command is the primary tool for expanding the project's knowledge base. All generated skills must adhere to the following structure:
+The `/learn` command is the primary tool for expanding the project's long-term memory. When mastering a new technology, follow this workflow:
 
-### 1. Mandatory Frontmatter (`SKILL.md`)
+### 1. Grounded Learning Lifecycle
+The agent follows a 4-phase process: **Audit** (environment check), **Strategic Mapping** (learning objectives), **Execution** (real-world experimentation), and **Codification**.
+
+### 2. Mandatory Frontmatter (`SKILL.md`)
 
 The root `SKILL.md` file **must** include a YAML block at the top. This allows the framework to autonomously recognize and activate the skill in future sessions.
 
@@ -75,9 +79,9 @@ description: <concise-summary-for-autonomous-activation>
 ---
 ```
 
-### 2. Asset Management
+### 3. Asset Management
 
-Move all successful experiment scripts and idiomatic examples to the `assets/` subdirectory within the skill folder.
+All successful experiment scripts and idiomatic examples generated during the `/learn` phase should be moved to the `assets/` subdirectory within the skill folder. These serve as verified reference points for future agent turns.
 
 ## 🌲 Git & Source Control
 

docs/user-guide.md

@@ -60,6 +60,17 @@ Your gateway to GitHub.
 - **How it works:** Interfaces with the GitHub CLI to analyze open issues and recommend what to tackle next based on strategic impact.
 
 
+### `/learn`
+
+Your tool for mastering new technologies and codifying them into project skills.
+
+- **How it works:** Implements a "Grounded Learning" philosophy through a 4-phase lifecycle:
+    1.  **Environment Audit:** Automatically detects if the library is already installed or has local integration points.
+    2.  **Strategic Mapping:** Researches the topic and defines 3-5 granular Learning Objectives (the "Learning Map"). **Requires user approval via `ask_user`.**
+    3.  **Grounded Execution:** The specialized `learner` sub-agent performs real-world experiments (writing and running scripts) to verify "gotchas," performance, and idiomatic patterns.
+    4.  **Skill Codification:** Consolidates all findings into a permanent project skill in `.gemini/skills/<name>/`, including a mandatory `SKILL.md` file and reference documents.
+- **Why it works:** It transforms ephemeral research into a permanent, machine-readable knowledge base that future agents can autonomously activate.
+
 ### `/task`
 
 Your roadmap manager.

journal/2026-03-20.md

@@ -23,3 +23,4 @@
 [2026-03-20T12:56:15] - Migrated tests to pytest, then cleaned up tests and makefile to finalize /learn command
 [2026-03-20T13:01:58] - Updated comprehensive documentation suite to include the new /learn command, grounded learning philosophy, and skill codification system
 [2026-03-20T13:04:06] - Release version 0.19.0
+[2026-03-20T13:22:29] - docs(core): update documentation suite for v0.19.0 improvements