docs: update comprehensive documentation suite

Author: apiad

docs/deploy.md

@@ -20,17 +20,21 @@ Running `install.sh` in an empty directory will:
 - Initialize baseline files (`README.md`, `CHANGELOG.md`, `TASKS.md`, `makefile`).
 - Perform an initial "feat" commit.
 
-### 2. Existing Project (Integration)
+### 2. Existing Project (Integration & Updates)
 
-If run inside an existing project, the script will:
+If run inside an existing project, the script performs a **Surgical Update**:
 
-- **Validate:** Ensure you have a clean Git working tree.
-- **Analyze:** Identify which framework files are missing or need updating.
-- **Confirm:** Present a summary of all proposed changes and wait for your approval.
-- **Integrate:** Add the `.gemini/` directory and core Markdown files without deleting your existing content.
-- **Commit:** Create a descriptive "feat" or "chore" commit with the changes.
+- **Validate:** Ensure a clean Git working tree to prevent data loss.
+- **Surgical Sync:** Updates core framework components (`hooks/`, `commands/`, `agents/`, `scripts/`) individually.
+- **Protection:** Explicitly preserves user configurations in **Protected Files**:
+    - `.gemini/settings.json`
+    - `.gemini/style-guide.md`
+- **Intelligent GEMINI.md Merge:** Preserves your custom content in the `## Project Notes` section of `GEMINI.md` while updating the core mandates above it.
+- **Confirm:** Presents a detailed summary of which files will be **created**, **updated**, or **protected** and waits for your approval.
+- **Integrate:** Adds missing directory structures (`journal/`, `plans/`, etc.) if they don't exist.
+- **Commit:** Automatically creates a descriptive `chore` commit marking the update.
 
-## 🛠️ Prerequisites
+## 🛠️ Prerequisites & Setup
 
 To ensure full functionality, your environment should have:
 
@@ -39,6 +43,16 @@ To ensure full functionality, your environment should have:
 - **Python 3.10+:** Required for executing the project's automation hooks (`.gemini/hooks/`).
 - **Make:** Used for project validation and health checks.
 
+### Installing Git Hooks
+
+After installation, you **must** link the framework's hooks to your git repository:
+
+```bash
+make install-hooks
+```
+
+This target creates a symbolic link from `.gemini/hooks/pre-commit.py` to `.git/hooks/pre-commit`, enabling the automated journal and validation checks.
+
 ## 🚢 Getting Started
 
 Once the installation is complete, follow these steps to orient yourself:

docs/design.md

@@ -10,27 +10,38 @@ The project's "brain" resides in the `.gemini/` directory, which is organized in
 
 Hooks are Python-based scripts that intercept the Gemini CLI turn lifecycle. They are the framework's primary enforcement mechanism.
 
-- **`session.py`:** Initializes the session and provides a project summary to the agent.
-- **`journal.py`:** Enforces the mandatory daily journaling requirement for all significant changes.
+- **`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.
-- **`cron.py`:** Synchronizes the project's background tasks with systemd user timers.
+- **`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.
 
-### 2. The Command System (`.gemini/commands/`)
+### 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.
+
+### 3. The Command System (`.gemini/commands/`)
 
 Commands define structured, multi-phase workflows that automate the development lifecycle. Each command is a TOML file containing specific instructions and context for the agent.
 
 - **`/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 for root-cause analysis.
-- **`/docs`:** Analyzes the codebase and project state to update the documentation suite.
+- **`/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.
 
-### 🔌 Synergistic Validation
+### 🔍 Deep Dive: Timestamp-Based Validation
+
+The `pre-commit.py` hook implements a sophisticated cross-file validation strategy:
 
-The `/task` command works in tandem with the `make.py` hook to ensure a "no-regression" policy. While `/task` enforces testing during the Red-Green-Verify cycle, the `make.py` hook provides a final, infrastructure-level check after every turn. If any turn (manual or automated) results in broken code, the framework immediately detects it, ensuring that the repository's "last known state" is always stable.
+1.  **Change Detection:** Uses `git status --porcelain` to identify all modified files, excluding internal framework files (`.gemini/`) and the journal itself.
+2.  **MTime Analysis:** Calculates the maximum modification time (`max(mtime)`) among all meaningful changes.
+3.  **Audit Trail Check:** Parses the **last entry** in the current day's journal file (`journal/YYYY-MM-DD.md`) and extracts its ISO timestamp.
+4.  **Temporal Consistency:** If the journal entry timestamp is **older** than the latest file change, the commit is blocked. This forces the agent (or user) to document the work *after* it is done but *before* it is finalized.
 
-### 3. Specialized Agents (`.gemini/agents/`)
+### 4. Specialized Agents (`.gemini/agents/`)
 
 Instead of a single "do-it-all" AI, the framework delegates tasks to specialized sub-agents with restricted toolsets and focused personas (e.g., `planner`, `debugger`, `editor`, `reporter`). This ensures higher reliability and more consistent results.
 

docs/develop.md

@@ -4,7 +4,7 @@ The **Gemini CLI Opinionated Framework** enforces a high-discipline development
 
 ## 🔄 The Mandatory Workflow Lifecycle
 
-Every non-trivial change must follow this strict three-phase process:
+Every non-trivial change must follow this strict four-phase process:
 
 ### 1. Research & Analysis
 
@@ -40,6 +40,16 @@ For every granular step of the implementation:
 
 Once all steps are complete, a final test run is performed. Upon user approval, the branch is merged back to `main` and the roadmap in `TASKS.md` is updated.
 
+### 4. Audit & Documentation (NEW)
+
+Before merging or committing any final change, the work **must** be documented in the daily journal. This is enforced by a **timestamp-based git hook**. Use the following tool to satisfy the requirement:
+
+```bash
+python3 .gemini/scripts/journal.py 'one-line description of the work'
+```
+
+Failure to do this will block your commit or turn execution.
+
 ## ✅ Testing & Quality Standards
 
 - **Source of Truth:** The `makefile` is the central definition of project health.
@@ -56,10 +66,10 @@ The framework requires a clean working tree for critical actions. Commit often t
 
 All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) standard:
 
-- **`feat:`**: A new feature for the user.
+- **`feat:`**: A new feature for the user (e.g., `feat(hooks): add notify-send alert`).
 - **`fix:`**: A bug fix for the user.
 - **`docs:`**: Documentation-only changes.
-- **`chore:`**: Maintenance, dependencies, or internal tooling updates.
+- **`chore:`**: Maintenance, dependencies, or internal tooling updates (e.g., `chore(release): version 0.17.1`).
 - **`refactor:`**: Code changes that neither fix a bug nor add a feature.
 
 ### 3. Commit Scoping

docs/index.md

@@ -12,7 +12,11 @@ The framework is built on the belief that AI is most effective when it is constr
 
 The agent is mandated to challenge ideas before implementing them. It identifies technical flaws, security risks, or redundant logic, acting as a "peer reviewer" in real-time.
 
-### 2. Strategy-First (Research -> Plan -> Execute)
+### 2. Journal-First Discipline (NEW)
+
+All significant work must be preceded or accompanied by a structured journal entry. The framework enforces this via a **timestamp-based pre-commit hook**, ensuring that the project's history is an accurate, human-and-AI-readable audit trail of intent and execution.
+
+### 3. Strategy-First (Research -> Plan -> Execute)
 
 Every non-trivial change follows a strict, non-negotiable lifecycle. The agent first researches the domain, proposes a detailed implementation plan, obtains user approval, and only then begins writing code. This is enforced by the **TCR (Test-Commit-Revert)** protocol, ensuring a "Green-only" development path.
 

docs/user-guide.md

@@ -99,12 +99,36 @@ The approved plan is linked to a task. You trigger the execution:
 
 After all steps pass, the agent presents the final work. Upon your approval, it merges back to `main` and cleans up the feature branch.
 
-### **Step 5: Document & Release with `/docs` & `/release`**
+### Step 5: Document & Release with `/docs` & `/release`
 
 Finally, use `/docs` to update the technical documentation and `/release` to publish the new version.
 
+## ✍️ Maintaining your Journal
+
+The framework's most powerful feature is its automated audit trail. This is enforced by a **timestamp-based pre-commit hook** that ensures your code never gets ahead of your documentation.
+
+### The Rule of Temporal Consistency
+
+Every code change must be documented in `journal/YYYY-MM-DD.md`. If you modify a file at 10:00 AM, you must have a journal entry with a timestamp of 10:00 AM or later before you can commit.
+
+### Using the Journal Tool
+
+To simplify this, the framework includes a dedicated script. Always use it instead of manual editing:
+
+```bash
+python3 .gemini/scripts/journal.py "Brief description of your work"
+```
+
+This tool automatically:
+1.  Detects the current date and finds/creates the correct journal file.
+2.  Generates a precise ISO timestamp.
+3.  Appends the entry in the standard `[timestamp] - description` format.
+
+By following this discipline, you ensure that the AI agent always has an up-to-date "long-term memory" to draw from in future sessions.
+
 ## ⚙️ Background Tasks & Maintenance
 
+
 The real magic of AI-assisted development is what happens when you're not looking or when dealing with technical debt.
 
 ### `/cron`

journal/2026-03-20.md

@@ -10,3 +10,4 @@
 [2026-03-20T08:43:37] - chore(release): version 0.17.0
 [2026-03-20T08:45:12] - refactor(docs): simplify journal entry logic in install.sh
 [2026-03-20T08:46:18] - chore(release): version 0.17.1
+[2026-03-20T09:54:08] - docs: update comprehensive documentation suite (index, deploy, design, develop, user-guide) with latest framework improvements