docs: enhance installation and setup documentation with detailed project scaffolding and integration steps

Author: apiad

docs/deploy.md

@@ -11,15 +11,19 @@ curl -fsSL https://apiad.github.io/starter/install.sh | bash
 ```
 
 ### 1. New Project (Scaffolding)
+
 Running `install.sh` in an empty directory will:
+
 - Initialize a fresh Git repository.
 - Extract the core `.gemini/` framework and configuration files.
 - Create the standard project structure (`journal/`, `plans/`, `research/`, `drafts/`).
 - Initialize baseline files (`README.md`, `CHANGELOG.md`, `TASKS.md`, `makefile`).
 - Perform an initial "feat" commit.
 
 ### 2. Existing Project (Integration)
+
 If run inside an existing project, the script will:
+
 - **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.
@@ -29,6 +33,7 @@ If run inside an existing project, the script will:
 ## 🛠️ Prerequisites
 
 To ensure full functionality, your environment should have:
+
 - **Git:** Required for state management and change detection hooks.
 - **Node.js:** Necessary for running the `gemini` CLI.
 - **Python 3.10+:** Required for executing the project's automation hooks (`.gemini/hooks/`).
@@ -39,17 +44,21 @@ To ensure full functionality, your environment should have:
 Once the installation is complete, follow these steps to orient yourself:
 
 ### 1. Run Onboarding
+
 Execute the `/onboard` command to get a high-signal overview of the repository's architecture, standards, and current roadmap.
 
 ```bash
 gemini /onboard
 ```
 
 ### 2. Initialize the Roadmap
+
 Check the current `TASKS.md` file and use the `/task` command to define your project's initial goals.
 
 ### 3. Start a New Feature
+
 For your first feature, follow the standard workflow:
+
 - **Research:** `gemini /research [topic]`
 - **Plan:** `gemini /plan` (follow the interactive prompts)
 - **Implement:** Begin coding once the plan is saved in `plans/`.

docs/design.md

@@ -7,29 +7,37 @@ The **Gemini CLI Opinionated Framework** is not just a collection of scripts; it
 The project's "brain" resides in the `.gemini/` directory, which is organized into four primary systems:
 
 ### 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.
+
 - **`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.
 - **`make.py`:** Automatically runs the `makefile` (tests/linting) to prevent regressions.
 - **`cron.py`:** Synchronizes the project's background tasks with systemd user timers.
 - **`utils.py`:** Provides a shared set of utilities for git status analysis and communication with the CLI.
 
 ### 2. 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.
 - **`/task`:** The primary execution engine, managing `TASKS.md` and enforcing the strict TCR (Test-Commit-Revert) loop and feature branch isolation.
 
 ### 🔌 Synergistic Validation
+
 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.
 
 ### 3. 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.
 
 ### 4. State Management
+
 The framework maintains internal state to optimize operations and ensure continuity:
+
 - **`.gemini/last_make_run`**: Stores the timestamp of the last successful validation, allowing the framework to skip redundant tests.
 - **`.gemini/last_journal_update`**: Tracks when the journal was last updated to intelligently enforce the journaling requirement.
 - **`.gemini/settings.json`**: Configures the framework's global behavior and hook execution order.

docs/develop.md

@@ -7,29 +7,37 @@ The **Gemini CLI Opinionated Framework** enforces a high-discipline development
 Every non-trivial change must follow this strict three-phase process:
 
 ### 1. Research & Analysis
+
 Before proposing a change, use the `/research` command to gather context, analyze the current codebase, and identify potential risks.
 
 ### 2. Strategic Planning
+
 A feature is not considered "active" until a persistent Markdown plan has been created in the `plans/` directory. Use the `/plan` command to generate this strategy and synchronize it with `TASKS.md`.
 
 ### 3. Execution & Validation (TCR Protocol)
-The `/task work` command implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
+
+The `/task work on ...` command implements a strict **TCR (Test-Commit-Revert)** protocol to ensure high-velocity, high-quality code.
 
 #### **Phase 1: Pre-flight Verification**
+
 The agent verifies that the working tree is clean, the current branch is `main`, and `make test` passes as a baseline.
 
 #### **Phase 2: Task Isolation**
+
 A dedicated feature branch (e.g., `feature/task-name`) is auto-generated and checked out. All subsequent work for this task occurs here.
 
 #### **Phase 3: The Red-Green-Verify Loop**
+
 For every granular step of the implementation:
+
 1.  **Red:** Write a failing test and verify failure with `make test`.
 2.  **Green:** Implement the minimal code to pass.
 3.  **Verify:** Run `make test`.
     - **Pass:** `git commit` the step.
     - **Fail:** Attempt one quick fix; if it still fails, **revert** to the last green state (`git checkout .`).
 
 #### **Phase 4: Integration**
+
 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.
 
 ## ✅ Testing & Quality Standards
@@ -41,17 +49,21 @@ Once all steps are complete, a final test run is performed. Upon user approval,
 ## 🌲 Git & Source Control
 
 ### 1. Clean Working Tree
+
 The framework requires a clean working tree for critical actions. Commit often to avoid merge conflicts or large, unmanageable diffs.
 
 ### 2. Conventional Commits
+
 All commit messages must follow the [Conventional Commits](https://www.conventionalcommits.org/) standard:
+
 - **`feat:`**: A new feature for the user.
 - **`fix:`**: A bug fix for the user.
 - **`docs:`**: Documentation-only changes.
 - **`chore:`**: Maintenance, dependencies, or internal tooling updates.
 - **`refactor:`**: Code changes that neither fix a bug nor add a feature.
 
 ### 3. Commit Scoping
+
 When possible, provide a scope to the commit message (e.g., `feat(onboard): add documentation discovery`).
 
 ## ✍️ Documentation Style

docs/index.md

@@ -9,15 +9,19 @@ This project is more than just a template; it is a structured environment that e
 The framework is built on the belief that AI is most effective when it is constrained by rigorous engineering standards and empowered by deep project context. We operate on three fundamental pillars:
 
 ### 1. Critical Cognitive Partnership
+
 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)
+
 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.
 
 ### 3. Validation-as-Truth
+
 The `makefile` is the ultimate source of truth for project health. Automated hooks ensure that every agent action is followed by a validation run (linting, testing, formatting) to prevent regressions.
 
 ### 4. Task Isolation (Feature Branching)
+
 All development work is strictly performed on dedicated, auto-generated feature branches. This keeps the `main` branch protected and always in a deployable state, while providing a clean, granular history for every task.
 
 ## 🚀 Quick Start

docs/user-guide.md

@@ -8,7 +8,7 @@ The framework is not just a set of scripts; it is a principled system designed t
 
 ## 🧠 Principles of Effective AI-Assisted Work
 
-The most pressing limitation of modern LLMs is context saturation. When you work on a single project for a long time, the model can lose track of important details, leading to hallucinations or drift. 
+The most pressing limitation of modern LLMs is context saturation. When you work on a single project for a long time, the model can lose track of important details, leading to hallucinations or drift.
 
 This framework solves this problem by enforcing three core principles:
 
@@ -23,12 +23,16 @@ This framework solves this problem by enforcing three core principles:
 The most critical phase of any project occurs before you write a single line of code. This framework moves away from impulsive execution toward a deliberate, architected approach.
 
 ### `/research`
+
 Your primary tool for gathering external knowledge.
+
 - **How it works:** When triggered, the `researcher` subagent scours the web for technical documentation, APIs, or case studies. It synthesizes this data into granular summaries saved in the `research/` directory.
 - **When to use:** Use this when you need to understand a new library, a technical specification, or gather data for an article.
 
 ### `/plan`
+
 Your tool for internal strategy and architectural design.
+
 - **How it works:** The `planner` subagent conducts a thorough analysis of your codebase and journal. After clarifying the goal with you interactively, it produces a comprehensive Markdown plan in the `plans/` directory.
 - **Crucial Rule:** The `/plan` command *never* executes the code. It maps the territory and provides a step-by-step execution roadmap for you to approve first.
 
@@ -39,35 +43,50 @@ Your tool for internal strategy and architectural design.
 Once you have a solid strategy in `plans/`, you can move into execution. These commands eliminate the friction of context-switching between your IDE and terminal.
 
 ### `/issues`
+
 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.
 
+
 ### `/task`
+
 Your roadmap manager.
+
 - **How it works:** Manages a living `TASKS.md` document. Use it to `create` new tasks, `work` on existing ones, or `report` on the project's current status.
 
 ### `/commit`
+
 Brings order to your version history.
+
 - **How it works:** Instead of monolithic "WIP" commits, this command analyzes your `git diff` and logically groups modifications into cohesive units. It proposes a series of atomic, Conventional Commits (e.g., separating a feature update from a documentation tweak) for your approval.
 
 ### `/release`
+
 Automates the deployment process.
+
 - **How it works:** Verifies workspace integrity (clean git tree, passing tests via `make`), analyzes commit history to propose the next version bump, drafts a `CHANGELOG.md` entry, and publishes the final tag to GitHub.
 
 ## 🔄 A Full Feature Development Walkthrough
 
 A complete, principled development cycle follows the **Research -> Plan -> Execute** lifecycle.
 
 ### **Step 1: Research with `/research`**
+
 You are integrating a new authentication library. You start by researching the technical requirements.
+
 - The `researcher` subagent gathers documentation and synthesizes it into `research/auth-library-deep-dive.md`.
 
 ### **Step 2: Strategy with `/plan`**
+
 Once you understand the requirements, you trigger the `/plan` command.
+
 - The `planner` subagent analyzes the codebase and generates `plans/implement-auth.md`, mapping out the specific architectural changes and testing strategy.
 
 ### **Step 3: Execute with `/task work`**
+
 The approved plan is linked to a task. You trigger the execution:
+
 - **Pre-flight:** The agent verifies the tree is clean on `main`.
 - **Isolation:** A `feature/auth-integration` branch is created.
 - **Loop (Red-Green-Verify):**
@@ -77,21 +96,27 @@ The approved plan is linked to a task. You trigger the execution:
     4.  The loop repeats for every granular step.
 
 ### **Step 4: Review & Integrate**
+
 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`**
+
 Finally, use `/docs` to update the technical documentation and `/release` to publish the new version.
 
 ## ⚙️ 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`
+
 Your background automation layer.
+
 - **How it works:** Uses the `cron.toml` file to define scheduled tasks via systemd user timers. You can schedule natural language prompts (e.g., "Scour the web for new developments in X") to run overnight, ensuring your knowledge base is fresh by morning.
 
 ### `/maintenance`
+
 Your defense against context rot.
+
 - **How it works:** Performs a comprehensive audit of the codebase to identify technical debt, outdated implementations, or deviations between code and documentation. It presents a detailed refactoring plan for your approval before making any changes, ensuring the repository remains a clean environment for the AI to operate within.
 
 ---