doc: updated hai usage docs (#151)

Author: magesh-presidio

assets/img/hai-rules.png

@@ -76,10 +76,7 @@ Vertex AI supports eight regions. Select a region that meets your latency, compl
     -   Search for **HAI** and install the extension
 
 <Frame>
-	<img
-		src="https://storage.googleapis.com/cline_public_images/docs/assets/cline-extension-arrow.png"
-		alt="HAI extension in VS Code"
-	/>
+	<img src="../../assets/img/hai-vscode-download.png" alt="HAI extension in VS Code" />
 </Frame>
 
 #### 3.2 Configure HAI Settings

assets/img/hai-vscode-download.png

@@ -0,0 +1,247 @@
+---
+title: "Expert Instruction Meta-Guide"
+description: "A meta-guide to help contributors write high-quality, role-based expert instruction files for building LLM personas or system instructions."
+---
+
+> ✅ **Purpose**  
+> This document is a meta-guide to help contributors craft high-quality, role-based expert instruction files. These serve as ground truth for building LLM personas, system instructions, or engineering knowledge bases.
+>
+> If you're not sure what an expert is or why we need one, please take a moment to read this document: [Experts](../../experts.mdx)
+
+> 📌 **Guiding Philosophy**  
+> An expert guidelines document isn't just a cheat sheet—it's a codified persona of excellence. It should:
+>
+> -   Establish authority in the domain.
+> -   Provide principles and practice—not just instructions.
+> -   Be structured, consistent, and extensible.
+> -   Serve both humans and LLMs—making it chunkable, parseable, and RAG-ready.
+
+---
+
+### 🧩 1. Structure of an Expert File
+
+Here's a canonical format:
+
+```markdown
+## You are HAI, a specialized expert in [DOMAIN] with deep knowledge of [TOOLING/SUBDOMAINS].
+
+## [DOMAIN]-Specific Guidelines
+
+### 1. [Thematic Group Title]
+
+Content, code blocks, rationale, and rules here.
+
+### 2. [Next Area of Concern]
+
+Repeat with clarity.
+...
+
+### X. [CI/CD | Security | Best Practices]
+
+Close with extensibility and enforcement sections.
+```
+
+✅ **Keep it consistent across personas:**
+
+-   Always start with a role declaration
+-   Always follow with a domain-specific guidelines heading
+-   Break content into clearly scoped thematic sections
+-   Use markdown + code fences to support syntax highlighting
+-   Highlight both "How" and "Why"
+
+---
+
+## 🏗️ 2. Before You Begin
+
+**Ask These Questions:**
+
+| Question                                        | Purpose                                   |
+| ----------------------------------------------- | ----------------------------------------- |
+| What persona am I writing as?                   | DevOps expert, React guru, etc.           |
+| Who is the target reader?                       | Beginner? Intermediate? Contributor? LLM? |
+| What are the core pillars of this domain?       | Structure, testing, versioning, etc.      |
+| What tools or frameworks dominate this space?   | e.g., Next.js, Terraform, Playwright      |
+| What is considered bad practice in this domain? | Helps define the edges of expertise       |
+| How can I include reusable code patterns?       | Makes doc practical and referenceable     |
+
+---
+
+## 🧠 3. What Makes It Expert-Level
+
+| Trait                | Description                                                 |
+| -------------------- | ----------------------------------------------------------- |
+| Opinionated          | Don’t be afraid to prescribe best practices. Experts guide. |
+| Battle-Tested Advice | Include guidance reflecting real-world scenarios.           |
+| Code-First           | Add idiomatic examples with syntax and patterns.            |
+| Explains Trade-offs  | Prefer “X over Y because…” vs simply “use X”.               |
+| Modular              | Sections should be pluggable, referenceable, and swappable. |
+| LLM-Friendly         | Structured, token-efficient, chunkable.                     |
+
+---
+
+## ✍️ 4. Writing Checklist
+
+Use this as a repeatable checklist:
+
+✅ **Role Setup**
+
+-   Name the expert clearly.
+-   Define the domain explicitly.
+-   Mention specializations.
+
+✅ **Core Sections (pick and tailor)**
+
+-   Project Structure
+-   Setup & Initialization
+-   Configuration Management
+-   CI/CD Integration
+-   Security Guidelines
+-   Testing Methodologies
+-   Environment Handling (Dev/Staging/Prod)
+-   Versioning & Upgrade Strategies
+-   Deployment or Scaling Patterns
+-   Common Pitfalls / Anti-Patterns
+-   Performance Best Practices
+-   Observability & Logging
+
+✅ **Content Style**
+
+-   Context or explanation for every code block.
+-   Instructions with action verbs.
+-   Consistent terminology.
+-   Links to RFCs, standards, or docs.
+
+---
+
+## ⚙️ 5. Format Guidelines
+
+| Element        | Usage                                              |
+| -------------- | -------------------------------------------------- |
+| ##             | Top-level role or section headers                  |
+| ###            | Subsections by theme                               |
+| ```language    | Always use language tags (e.g., lua, go, ts, bash) |
+| ✅ / ⚠️ / ❌   | Use emojis sparingly for clarity                   |
+| Tables         | For comparisons, options, trade-offs               |
+| Bullet Lists   | When ordering is irrelevant                        |
+| Numbered Lists | When process/order matters                         |
+
+---
+
+## 🧬 6. Reusability for LLMs & Knowledge Graphs
+
+To make the docs ready for automation:
+
+-   Ensure each section is self-contained
+-   Use consistent headings for chunking
+-   Minimize overly verbose narrative — clarity wins
+-   Prefer `term: definition` format for glossary-type items
+-   Group example-first where possible
+
+---
+
+## 🧪 7. Example Meta Templates
+
+Example role primers:
+
+```markdown
+## You are HAI, a DevOps Reliability Expert specializing in Kubernetes-based microservice deployments at scale on AWS and GCP.
+
+## DevOps-Specific Guidelines
+
+### 1. Cluster Configuration
+
+...
+
+### 2. Autoscaling & Cost Controls
+
+...
+```
+
+```markdown
+## You are HAI, an LLM Product Engineer focused on Retrieval-Augmented Generation pipelines using LangChain, Weaviate, and OpenAI APIs.
+
+## LLM Engineering Guidelines
+
+### 1. Chunking & Indexing Strategies
+
+...
+
+### 2. Prompt Engineering Principles
+
+...
+```
+
+---
+
+## 🧭 8. Final Tips
+
+-   Start with a skeleton using the checklist above
+-   Avoid repeating generalities — focus on sharp, unique knowledge
+-   Think of each section as a “tile” of expertise — someone should be able to take just one tile and apply it
+-   Think in terms of portable intelligence, not just documentation
+
+Now that you know how to write an expert, why not contribute? Please refer to the below guide to contribute to HAI.
+
+---
+
+## 🤝 How to Contribute Experts to the GitHub Repository
+
+**1. Clone the Repository**
+
+Start by cloning the repository to your local machine:
+
+```bash
+git clone https://github.com/presidio-oss/cline-based-code-generator
+```
+
+**2. Navigate to the Experts Directory**
+
+Once you've cloned the repository, navigate to the src/experts directory:
+
+```bash
+cd src/experts
+```
+
+**3. Create Your Own Expert Folder**
+
+Each expert should have its own dedicated folder. The folder name should match the name of the expert. For example, if you're contributing a Golang expert, create a folder called golang.
+
+Inside this folder, create two files:
+
+-   prompt.md: The content file that will contain the instructions or prompt for the expert.
+
+-   icon.svg: The SVG icon that represents the expert. Make sure to keep the icon file small and optimized for use in the UI.
+
+Example folder structure:
+
+```plaintext
+src/experts/
+ ├── golang/
+ │    ├── prompt.md
+ │    └── icon.svg
+ └── ...
+```
+
+**4. Create an Issue**
+
+Before submitting your contribution, create an issue to track the addition of the new expert. The issue format should be as follows:
+
+-   Format: `[Expert]: Expert Name`
+-   Example: `[Expert]: Golang`
+
+Make sure to tag the issue with the Expert label for easy identification.
+
+**5. Raise a Pull Request**
+
+After you've made your changes, raise a pull request (PR) to merge your contributions into the main repository.
+
+When creating the pull request, please follow these standards:
+
+-   Pull Request Title Format: `[Experts]: Expert Name expert`
+-   Example: `[Experts]: Golang expert`
+-   Link the Pull Request with the Issue: Make sure to link the pull request to the issue you created earlier. This helps in tracking the progress of the contribution and ensures the expert is properly documented and tracked.
+
+**6. Review and Merge**  
+Once your PR is raised, we will review your contribution. If everything is in order, it will be merged into the repository. If there are any issues, we will provide feedback to help you get your contribution ready for merging.
+
+**Thank You!**

docs/custom-model-configs/gcp-vertex-ai.mdx

@@ -0,0 +1,95 @@
+---
+title: "Experts"
+description: "Learn how Experts help tailor the HAI Code Generator with domain-specific context for smarter, more accurate code generation."
+---
+
+### 🤔 1. What are Experts?
+
+Experts are like smart guides for the code generator—they help it focus on specific tech stacks or domain-specific knowledge the LLM may not know on its own.
+
+### 💡 2. Why do you need an Expert?
+
+Imagine this: you’ve got custom UI components or internal libraries with secret documentation.
+
+The LLM? It’s smart, but it doesn’t know your internal playbook.
+
+Experts bring that knowledge into the loop, so your code gen becomes context-aware and more accurate.
+
+### 🛠️ 3. Built-in Experts
+
+We’ve bundled in 4 ready-to-go experts:
+
+-   ✅ .NET
+-   ✅ Terraform
+-   ✅ Node.js
+-   ✅ Go
+
+Each comes with predefined best practices & usage guidelines.
+
+> 📚 **Note:** These are currently read-only.
+
+### ✍️ 4. Can I create my own Expert?
+
+Yes, you can! 🙌
+
+Here’s how it works:
+
+-   📝 Define your own custom guidelines
+-   🔗 Add up to 3 document links as references
+-   📥 We scrape those URLs and convert the content to markdown
+-   🧠 LLM uses both the guidelines + docs for code generation
+
+> ✅ **Result?** A highly tailored, smart assistant.
+
+### ⚙️ 5. How does it work under the hood?
+
+When you select an Expert, the system sends:
+
+-   The guidelines
+-   The scraped doc content
+
+...to the LLM, giving it the context it needs to generate better code.
+
+### 🚧 6. Current Limitations
+
+-   📄 Only 3 documents can be uploaded right now
+-   🌐 Large URLs may not be fully processed
+
+### 🔍 7. Are we solving this?
+
+Yes! We're actively exploring:
+
+-   Smarter ways to index and chunk content
+-   Reducing noise while keeping the useful stuff
+
+### 🧪 8. How we handle doc content?
+
+We tested two approaches:
+
+#### 📄 Raw Scraped Content
+
+**Pros:**
+
+-   Full fidelity
+
+**Cons:**
+
+-   Too much info = LLM overwhelm
+-   Higher chance of hitting token limits
+
+#### ✂️ Summarized via LLM (Current Approach)
+
+**Pros:**
+
+-   Clean, focused content
+-   Smaller token usage
+
+**Cons:**
+
+-   Might skip minor details
+
+> ⚖️ **Trade-off:** Better performance with most important info kept intact.
+
+### 📄 9. Expert Guidelines
+
+Looking to define your own expert? Check out the [Experts Guidelines](../../experts-guidelines.mdx) file.

docs/exploring-clines-tools/checkpoints.mdx renamed to docs/exploring-hai-tools/checkpoints.mdx

@@ -0,0 +1,34 @@
+---
+title: "File Identification"
+description: "Intelligently identify and retrieve relevant files using task-based discovery, contextual comments, and vector-powered indexing."
+---
+
+### 🔍 File Identification
+
+Elevate your workflow with **intelligent file discovery and retrieval**, designed to help you quickly locate, understand, and act on the right files — even in large codebases.
+
+<div align="center">
+	<img src="assets/gifs/find-files.gif" alt="File Identification" />
+	<p>
+		<i>File Identification</i>
+	</p>
+</div>
+
+---
+
+#### 🧠 Task-Based File Discovery
+
+Redefine how you manage code assets through **Task-Based File Discovery**, which combines intelligent analysis with context-aware tools:
+
+-   **🗒️ Contextual Code Comments**
+
+    -   Automatically generate insightful, contextual comments for every identified file.
+    -   Comments are stored in a dedicated folder, keeping your code clean while maintaining full traceability.
+
+-   **📚 Faiss DB Indexing**
+    -   Built on the powerful **Faiss** vector search engine for lightning-fast and accurate file retrieval.
+    -   Scales effortlessly across large repositories, making file identification reliable even in complex projects.
+
+Together, these tools create a **smart and contextual system** for navigating your codebase — transforming file identification from a bottleneck into a breeze.
+
+🔎 With HAI, finding the right file is no longer a challenge — it's a feature.