godspeedsystems · sakshiarora386 · Dec 24, 2025 · Dec 24, 2025 · Dec 24, 2025
diff --git a/docs/saarthi/getting-started/installing.mdx b/docs/saarthi/getting-started/installing.mdx
@@ -45,7 +45,7 @@ import SaarthiIcon from '@site/src/components/SaarthiIcon';
 
 **[Modes →](/docs/saarthi/basic-usage/using-modes.md)** 
 
-**[Workflows →](/docs/saarthi/workflows.md)**
+**[Workflows →](/docs/saarthi/workflows/general.md)**
 
 
 ## Troubleshooting

diff --git a/docs/saarthi/index.md b/docs/saarthi/index.md
@@ -36,7 +36,7 @@ import SaarthiIcon from '@site/src/components/SaarthiIcon';
 ## Key Features
 
 ### Multiple Agents
-Saarthi adapts to your needs with specialized [modes](./basic-usage/using-modes) and [workflows](/docs/saarthi/workflows.md):
+Saarthi adapts to your needs with specialized [modes](./basic-usage/using-modes) and [workflows](/docs/saarthi/workflows/general.md):
 
 
     **[💻 Code](./modes/code.md):** For general-purpose coding tasks, now with integrated support for Godspeed’s 4th-gen meta framework for backend development, enabling guard-railed 10x engineering practices—automatically.
@@ -66,7 +66,7 @@ Saarthi adapts to your needs with specialized [modes](./basic-usage/using-modes)
 
 
 ### Smart Tools
-- Saarthi comes with powerful **[workflows](/docs/saarthi/workflows.md)** that can automate your multi-step dev tasks.
+- Saarthi comes with powerful **[workflows](/docs/saarthi/workflows/general.md)** that can automate your multi-step dev tasks.
 - Read and write files in your project
 - Execute commands in your VS Code terminal
 - Control a web browser

diff --git a/docs/saarthi/workflows.md → docs/saarthi/workflows/general.md b/docs/saarthi/workflows.md → docs/saarthi/workflows/general.md
@@ -1,3 +1,8 @@
+---
+sidebar_label: General
+---
+
+
 # Workflows
 
 Workflows in Saarthi are **sequences of actions** defined to automate common development and deployment tasks. They are customizable and bring consistency, guardrails, and speed to your engineering process — from setting up a Godspeed project to deploying on cloud, generating UIs, creating test strategies, or even drafting technical documents.  
@@ -136,49 +141,7 @@ Sets up authentication in your Godspeed microservice using supported auth method
 
 ---
 
-### 7. Figma to UI Generation
-
-**Description:**
-Convert your Figma designs into responsive UI components and pages.
-
-**Pre-requirements:**
-
-* Figma file URL
-* Figma Personal Access Token
-
-**Process:**
-
-1. **Select Workflow** – Choose `Figma to UI Generation` from workflows dropdown.
-2. **Provide Figma Details** – Enter Figma URL + Access Token.
-3. **Extract Components** – Saarthi generates component hierarchy with `gs-nodegen-figma`.
-4. **Generate Scaffolding** – Creates project scaffolding + imports Godspeed UI components.
-5. **Integrate APIs (optional)** – Provide Swagger spec → generates API slices with Redux.
-6. **Run Strategy** – Orchestrator executes milestones → pages & components built step-by-step.
-
----
-
-### 8. Prompt to UI Generation
-
-**Description:**
-Generate UI pages and components directly from a text prompt, if you don't have PRD, TRD, or Figma designs.
-Saarthi automates **strategy creation, component scaffolding, API integration, and responsive UI development** — all inside your workspace.
-
-**Requirements:**
-
-* Prepare your PRD/TRD files simply give a text prompt.
-* Project brief (you’ll be prompted for this if PRD/TRD are missing)
-* If using API integration, have a **Swagger/OpenAPI spec JSON** ready.
-
-**Process:**
-
-1. **Provide Project Brief** – If no PRD/TRD found, Saarthi asks for a short description of the project.
-2. **Scan Components** – Reads `components/gs-ui` and `components-list.txt` to detect available components.
-3. **Finalize Components** – User helps confirm components and their variants.
-4. **Generate Strategy** – Pages and components are mapped into milestones & steps.
-5. **Run Strategy** – Orchestrator executes the plan, building responsive pages with integrated APIs (if provided).
-
-
-### 9. Download and Run Docker Container
+### 7. Download and Run Docker Container
 
 **Description**
 Pulls a Docker image and runs a container with custom configuration.
@@ -193,7 +156,7 @@ Pulls a Docker image and runs a container with custom configuration.
 6. Validates container is running.
 
 
-### 10. Godspeed Coaching
+### 8. Godspeed Coaching
 
 **Description**
 Provides an interactive learning experience for mastering the Godspeed framework.
@@ -207,7 +170,7 @@ Provides an interactive learning experience for mastering the Godspeed framework
 
 ---
 
-### 11. Implement Feature from PRD
+### 9. Implement Feature from PRD
 
 **Description:**
 Implements features step-by-step based on the Product Requirement Document (PRD).
@@ -221,7 +184,7 @@ Implements features step-by-step based on the Product Requirement Document (PRD)
 
 ---
 
-### 12. Create/Update Test Strategy
+### 10. Create/Update Test Strategy
 
 **Description:**
 Creates or updates a comprehensive test strategy including scope, metrics, and environments.
@@ -235,7 +198,7 @@ Creates or updates a comprehensive test strategy including scope, metrics, and e
 
 ---
 
-### 13. Generate Test Cases
+### 11. Generate Test Cases
 
 **Description:**
 Generates detailed test cases (steps, expected results, traceability) from requirements.
@@ -249,7 +212,7 @@ Generates detailed test cases (steps, expected results, traceability) from requi
 
 ---
 
-### 14. Update Test Cases in Strategy
+### 12. Update Test Cases in Strategy
 
 **Description:**
 Maintains test documentation with version control, impact analysis, and traceability.
@@ -263,7 +226,7 @@ Maintains test documentation with version control, impact analysis, and traceabi
 
 ---
 
-### 15. Deploy to Render
+### 13. Deploy to Render
 
 **Description:**
 Deploys applications directly to the Render cloud platform.
@@ -277,7 +240,7 @@ Deploys applications directly to the Render cloud platform.
 
 ---
 
-### 16. Progress Review
+### 14. Progress Review
 
 **Description:**
 Reviews code, tests, and documentation against defined quality metrics.
@@ -291,7 +254,7 @@ Reviews code, tests, and documentation against defined quality metrics.
 
 ---
 
-### 17. Create Docker Image
+### 15. Create Docker Image
 
 **Description:**
 Builds Docker images from Dockerfiles for containerized deployment.
@@ -305,7 +268,7 @@ Builds Docker images from Dockerfiles for containerized deployment.
 
 ---
 
-### 18. Sprint Plan to Git Issues
+### 16. Sprint Plan to Git Issues
 
 **Description:**
 Converts sprint planning items into actionable GitHub issues.
@@ -319,7 +282,7 @@ Converts sprint planning items into actionable GitHub issues.
 
 ---
 
-### 19. Generate High-Level TRD
+### 17. Generate High-Level TRD
 
 **Description:**
 Generates a Technical Requirements Document (TRD) with architecture diagrams.
@@ -333,7 +296,7 @@ Generates a Technical Requirements Document (TRD) with architecture diagrams.
 
 ---
 
-### 20. Generate Coding Guidelines
+### 18. Generate Coding Guidelines
 
 **Description:**
 Creates coding standards with best practices, security, and compliance guidelines.
@@ -347,7 +310,7 @@ Creates coding standards with best practices, security, and compliance guideline
 
 ---
 
-### 21. Learning Roadmap
+### 19. Learning Roadmap
 
 **Description:**
 Builds a personalized learning roadmap with exercises, resources, and progress tracking.
@@ -361,7 +324,7 @@ Builds a personalized learning roadmap with exercises, resources, and progress t
 
 ---
 
-### 22. Assign Exercises
+### 20. Assign Exercises
 
 **Description:**
 Assigns predefined or custom exercises with tracking.
@@ -375,7 +338,7 @@ Assigns predefined or custom exercises with tracking.
 
 ---
 
-### 23. Feedback-Driven Learning Path
+### 21. Feedback-Driven Learning Path
 
 **Description:**
 Refines the learning experience using feedback, adjusting pace and content.

diff --git a/docs/saarthi/workflows/ui-generation.md b/docs/saarthi/workflows/ui-generation.md
@@ -0,0 +1,155 @@
+---
+sidebar_label: UI Generation
+---
+
+# 🎨 UI Generation Workflows
+
+## Figma to UI Generation
+
+**Description:**  
+Convert Figma designs into responsive UI components and pages using a schema-first approach. 
+This workflow prioritizes structure and fidelity by generating schemas before code.
+
+**Prerequisites:**
+- Figma file URL
+- Figma Personal Access Token
+- Optional: Swagger/OpenAPI spec JSON for API integration
+
+**Process:**
+1. **Input Collection** – User provides Figma URL, Token, and file type (App or Page).
+2. **Schema Generation** – Saarthi uses `gs-nodegen-figma` tool to generate component schemas locally.
+3. **Scaffolding** – Generates the project structure (or uses existing) via `gs-ui-init` tool.
+4. **API Setup (Optional)** – If a Swagger spec is provided, generates API slices using `gs-codegen-openapi`tool and sets up the Redux store/provider.
+5. **Component Implementation** – Iteratively reads schemas and Figma images to build responsive, atomic components and transfers necessary assets.
+6. **Assembly & Routing** – Combines components into full web pages and configures application routing.
+7. **Validation & Handoff** – Runs the development server and asks the user to confirm if the output meets requirements or if changes are needed before final delivery.
+
+### 🔑 How to Get a Figma API Key
+
+1. Go to **Figma → Settings → Security**.
+2. Under **Personal Access Tokens**, click **Generate new token**.
+3. Copy the generated token and store it securely.
+4. Use this token when prompted by Saarthi or the CLI.
+
+### 💡 Tips for Best Results
+* **Organize Frames:** Keep components logically grouped and avoid deeply nested auto-layouts.
+* **Clear Naming:** Use descriptive layer names in Figma to help with component identification.
+* **Large Designs:** To generate large Figma files in one go, move to a paid Figma plan. On free or limited plans, prefer generating smaller pages or sections incrementally.
+
+## ⚠️ Troubleshooting
+
+<details>
+<summary><strong>Windows CLI Argument Parsing</strong></summary>
+
+When using the CLI on Windows (PowerShell), wrap option values for gs-tools in both single and double quotes to correctly escape special characters.
+
+**Example:** `--url '"https://example.com/file?id=123"'`
+</details>
+
+<details>
+<summary><strong>429 – Rate Limit Exceeded</strong></summary>
+
+This indicates that your Figma API key has hit rate limits.
+
+**Note:** Many Figma APIs used by this tool are **Tier-1 APIs** and are subject to the limits described in the [Figma rate-limit documentation](https://developers.figma.com/docs/rest-api/rate-limits/#rate-limits-tier-table).  
+If you are on a limited or free plan, you may encounter frequent connection errors.
+
+**Recommended actions:**
+- Retry after some time.
+- Use smaller design or page-level URLs.
+- Move to a paid Figma plan for large or frequent exports.
+</details>
+
+<details>
+<summary><strong>403 – Forbidden</strong></summary>
+
+This means the token does not have access to the Figma file.
+
+**Check the following:**
+- Verify that the Figma account used to generate the token has access to the design.
+- If you are on a paid plan, ensure the design is added to the correct paid team/workspace.
+</details>
+
+<details>
+<summary><strong>500 Error or Timeout</strong></summary>
+
+This can occur due to:
+- Large or complex Figma designs
+- API rate limits on free or limited plans
+- Figma servers not responding in time
+
+**Recommended actions:**
+- Try generating smaller pages or sections instead of the full file.
+- Retry later.
+- Move to a paid Figma plan to reduce timeouts and API throttling.
+</details>
+
+---
+
+## Prompt to UI Generation
+
+**Description:**
+
+Generate UI pages and components directly from text prompts or PRDs.
+This workflow emphasizes predictability and reuse by leveraging the `gs-ui-kit` tool.
+
+**Prerequisites:**
+- A text prompt or PRD/TRD
+- Project brief
+- Optional: Swagger/OpenAPI spec JSON for API integration
+
+**Process:**
+1. **Scaffolding** – Sets up the UI project workspace via `gs-ui-init` tool.
+2. **Requirement Gathering** – Captures project goals or parses the provided PRD.
+3. **API Setup (Optional)** – Generates API slices via `gs-codegen-openapi` tool and wraps the app in a Redux provider.
+4. **Strategy & Component Selection** – Analyzes requirements to create a `ui-details.md` plan, selecting necessary components and variants from `gs-ui-kit` tool.
+5. **Build & Assemble** – Iteratively builds components (adapting from the kit or generating new ones) and assembles them into pages.
+6. **Validation & Handoff** – Starts the development server, verifies navigation, and asks the user to confirm if the application is ready or requires refinement.
+
+
+### 💡 Tips for Best Results
+* **Be Explicit:** Clearly state the page purpose (e.g., "dashboard", "auth page") and specific behaviors.
+* **Structure over Aesthetics:** Focus the prompt on layout and functionality first; refine styles later.
+* **API Planning:** Identify which components need which endpoints early in the prompt.
+
+---
+
+## Image to UI Generation
+
+**Description:**  
+
+Generate UI pages and components directly from design images. 
+This workflow balances creative freedom with guardrails using atomic design principles.
+
+**Prerequisites:**
+- One or more UI design images
+- Page-level metadata (color palette, fonts, theme)
+- Optional: Swagger/OpenAPI spec JSON
+
+**Process:**
+1. **Image Upload** – User provides design images for pages or sections.
+2. **Scoping** – Define whether the image maps to a full page or a specific component.
+3. **Scaffolding** – Sets up the UI project workspace.
+4. **Metadata Capture** – User provides context (colors, fonts, themes).
+5. **Generation** – Creates atomic components based on image analysis.
+6. **Assembly** – Wires components into pages and connects optional APIs.
+7. **Validation & Handoff** – Runs the application and asks the user to validate the visual fidelity and functionality before finishing.
+
+### 💡 Tips for Best Results
+ * **Use high-resolution images** – Clear contrast and crisp details lead to better code generation
+ * **Provide actual asset files upfront** – Share logos, icons, illustrations, and image assets directly instead of relying on generated placeholders. This ensures visual accuracy and maintains brand consistency
+ * **Define design tokens clearly** – Specify your color palette, typography, and spacing scale before generation
+ * **Document theme details** – Be explicit about light/dark mode, shadows, borders, and other style properties
+ * **Share design system guidelines** – If you have existing design standards, provide them to maintain consistency across generated components
+
+ ---
+
+## Choosing the Right Workflow
+
+| Workflow       | Start With        | Best For                          |
+|---------------|-------------------|----------------------------------|
+| Figma → UI    | Figma designs     | Production-ready applications    |
+| Prompt → UI   | Text / PRD        | Structured app bootstrapping     |
+| Image → UI    | Design images     | Creative or non-standard designs |
+
+---
diff --git a/docs/welcome.md b/docs/welcome.md
@@ -7,7 +7,7 @@ sidebar_label: Welcome
 
 Godspeed is the first agentic SDLC platform that helps you build production-grade software 10x faster. Powered by a 4th-gen framework- [Param](/docs/microservices-framework/introduction/overview.md), AI agents, and built-in guardrails, it brings consistency to modern development. Even entry-level engineers and LLMs can ship clean, scalable code with ease.
 
-Meet [Saarthi](/docs/saarthi/index.md), your multi-agent team inside VS Code. It automates every step of the Software Development Lifecycle - from idea to release, through intelligent [Modes](../basic-usage/using-modes) and [Workflows](/docs/saarthi/workflows.md)
+Meet [Saarthi](/docs/saarthi/index.md), your multi-agent team inside VS Code. It automates every step of the Software Development Lifecycle - from idea to release, through intelligent [Modes](../basic-usage/using-modes) and [Workflows](/docs/saarthi/workflows/general.md)
 
 Plan with PRDs, design with TRDs, generate tasks, implement features, review code, and deploy - all without leaving your IDE.