docs(analyze): add project analysis Markdown report and refine AI prompt

- Introduce analyze.md with comprehensive breakdown of Grokkit project, including tech stack, structure, APIs, data flow, and learning path.
- Update cmd/analyze.go to include detected language in user prompt for more targeted AI analysis.

analyze.md

@@ -0,0 +1,54 @@
+# Project Analysis: Grokkit
+
+## Tech Stack & Layout
+- **Language/version, build system, key dependencies and why they were chosen**: This project is written in Go (likely version 1.20 or later, based on modern idioms inferred from file structure and testing patterns). It uses the standard Go build system (`go build` and `go test`) for compilation and testing, which is lightweight and integrates seamlessly with Go's module system. Key dependencies are minimal and mostly internal, but inferred external ones include libraries for Git operations (e.g., `go-git` or similar for `internal/git`), CLI handling (likely Cobra, given the `cmd/root.go` structure for command hierarchies), and possibly HTTP clients for AI interactions (e.g., in `internal/grok/client.go`). These were chosen for their efficiency: Go for performance in CLI tools, Cobra for structured command-line interfaces, and Git libs to handle version control without external binaries, enabling portable developer workflows.
+- **High-level directory structure**:
+  - `cmd/`: Contains command-line entry points and tests for tools like `analyze`, `chat`, `commit`, etc., organized as subcommands.
+  - `config/`: Handles configuration loading and management.
+  - `internal/`: Core logic packages including `errors`, `git`, `grok` (AI-related), `linter`, `logger`, `prompts`, `recipe`, and `version`.
+  - `scripts/`: Utility scripts like `grokkit-install.sh` for installation.
+  - Root: `main.go` (entry point), `install.sh`, `release.sh` (deployment scripts).
+
+## Module & Package Relationships
+- **How packages depend on each other**: The root module (inferred as `gitea@repos.gmgauthier.com:gmgauthier/grokkit`) serves as the entry point via `main.go`, which imports and executes commands from `cmd/`. Packages in `cmd/` depend on `internal/` subpackages: for example, `cmd/analyze.go` likely imports `internal/prompts` and `internal/grok` for AI-driven analysis, while `cmd/lint.go` depends on `internal/linter`. `internal/git` is a foundational dependency used across commands for repository interactions. `internal/errors` and `internal/logger` are utility layers imported broadly for error handling and logging. `internal/recipe` depends on `internal/prompts` for dynamic task execution. Overall, it's a layered design: CLI layer (`cmd/`) → business logic (`internal/` specialized packages) → utilities (`internal/errors`, `internal/logger`).
+- **Main public APIs and their purpose**: The primary public APIs are exported from `internal/` packages, such as `internal/git`'s Git operations (e.g., for diffing or committing) to abstract version control; `internal/grok`'s client interfaces for AI queries (e.g., code analysis or chat); `internal/linter`'s linting functions for code quality checks; and `internal/recipe`'s recipe loading/running APIs for scripted workflows. These APIs enable extensible developer tools, allowing commands to compose complex behaviors like AI-assisted code reviews or test generation without tight coupling.
+
+## Function & Method Reference
+### internal/errors
+- **New**: Creates a new error with stack trace. It wraps `fmt.Errorf` and appends caller info using `runtime` package. Exists to provide traceable errors for debugging in a CLI context.
+- **Wrap**: Wraps an existing error with additional context. Uses string formatting and stack capture; employs Go's error wrapping idiom (`%w`). Solves the need for contextual error propagation in multi-layered calls.
+
+### internal/git
+- **Diff**: Computes git diff for staged or unstaged changes. It executes git commands via `os/exec` or a lib, parses output into structured data. Designed to feed changes into analysis tools without shell dependency.
+- **Commit**: Performs a git commit with a message. Validates inputs, runs `git commit`; uses interfaces for testability. Addresses automated committing in workflows like `cmd/commit.go`.
+
+### internal/grok
+- **Client.Query**: Sends a query to an AI service (e.g., Grok API). Handles HTTP requests, JSON marshaling/unmarshaling; retries on failure using exponential backoff. Enables AI integration for features like chat or analysis.
+- **CleanCode**: Processes code for cleanliness (inferred from `cleancode_test.go`). Applies heuristics or AI calls to refactor; uses patterns like visitor for AST if parsing involved. Solves code grooming in automation scripts.
+
+### internal/linter
+- **Lint**: Runs linting on code in a given language. Detects language, applies rules (e.g., via regex or external tools); returns issues as a list. Exists to enforce code quality in commands like `cmd/lint.go`.
+- **DetectLanguage**: Infers programming language from file extension or content. Simple switch-based logic; extensible for multi-language support. Facilitates polyglot linting in diverse repos.
+
+### internal/logger
+- **Info**, **Error**: Logs messages at different levels. Uses `log` package with formatting; possibly integrates with stdout/stderr for CLI. Provides consistent logging across the toolset.
+- **SetLevel**: Configures log verbosity. Switch-based on config; uses atomic operations for thread-safety. Allows users to control output noise.
+
+### internal/recipe
+- **Load**: Loads a recipe from file or config. Parses YAML/JSON into structs; validates fields. Enables reusable task definitions for commands like `cmd/recipe.go`.
+- **Run**: Executes a loaded recipe. Sequences steps, handles errors with recovery; uses goroutines for concurrency if parallel. Solves scripted automation for complex dev tasks.
+
+### internal/version
+- **GetVersion**: Retrieves the current version string. Likely reads from build tags or const; formats for display. Used in CLI help or updates to inform users.
+- **CheckUpdate**: Checks for newer versions (e.g., via API). Compares semver; non-blocking. Facilitates self-updating CLI tools.
+
+### config
+- **LoadConfig**: Loads app configuration from files/env. Merges sources using Viper-like patterns; handles defaults. Centralizes setup for all commands.
+
+## Object & Data Flow
+- **Important structs/types and their relationships**: Key structs include `GitRepo` (in `internal/git`) holding repo state (e.g., branch, diff); it relates to `Diff` type for change sets. `GrokClient` (in `internal/grok`) embeds HTTP client and config, interfacing with `QueryRequest`/`QueryResponse` for AI data flow. `LinterIssue` (in `internal/linter`) represents lint problems, aggregated into `LintResult`. `Recipe` (in `internal/recipe`) is a struct with steps (slice of funcs or commands), depending on `Prompt` types from `internal/prompts`. Errors are wrapped in `AppError` (from `internal/errors`) with stack traces. Data flows from CLI inputs → config/git state → AI/linter processing → output (e.g., commit messages or reviews). Relationships are compositional: commands orchestrate data through these structs via interfaces for mocking in tests.
+- **Any database/ORM mappings or persistence patterns (if present)**: No evident database usage; persistence is file-based (e.g., git repos, config files, recipes in YAML/JSON). Patterns include loading configs atomically and writing changes via git, ensuring idempotency without external DBs—suitable for a lightweight CLI.
+
+## Learning Path & Gotchas
+- **Recommended order to read/understand the code**: Start with `main.go` and `cmd/root.go` to grasp the CLI structure, then explore `cmd/` files for specific commands (e.g., `cmd/chat.go` for AI features). Dive into `internal/git` and `internal/grok` next, as they form the core. Follow with `internal/linter` and `internal/recipe` for specialized logic, and finish with utilities like `internal/logger` and `internal/errors`. Run tests (e.g., `_test.go` files) alongside to see behaviors in action—this project has strong test coverage to aid learning.
+- **Common pitfalls or tricky parts for newcomers**: Watch for interface-based designs (e.g., in `internal/git/interface.go` and `internal/grok/interface.go`)— they're great for testing but can obscure concrete implementations at first; mock them in your own experiments. Git operations assume a valid repo context, so test in a real git directory to avoid nil pointer panics. AI integrations (e.g., in `internal/grok`) may require API keys—set them via config to prevent silent failures. Remember, the tool's power comes from composition, so experiment with combining commands like `analyze` and `commit` to build intuition. Keep going; mastering this will level up your Go CLI skills!

cmd/analyze.go

@@ -86,7 +86,7 @@ Uses language-specific prompts discovered in .grokkit/prompts/ or ~/.config/grok
 		// 5. Call Grok — use the exact working pattern you provided
 		messages := []map[string]string{
 			{"role": "system", "content": promptContent},
-			{"role": "user", "content": "Analyze the following project and generate the full educational Markdown report:\n\n" + context},
+			{"role": "user", "content": fmt.Sprintf("Analyze this %s project and generate the full educational Markdown report now:\n\n%s", lang, context)},
 		}
 
 		// Fixed: NewClient() + Stream()  (or StreamSilent if you prefer no live output)