Revise contributing guidelines and intro docs:

butschster · butschster · commit f0c12a0062ef · 2025-09-21T16:22:22.000+04:00
- Simplify wording and improve clarity in contributing steps.
- Update code examples to reflect recent changes (e.g., `ctx` command usage).
- Enhance CTX introduction with context-focused benefits and real-world use cases.
diff --git a/docs/contributing.md b/docs/contributing.md
@@ -1,7 +1,6 @@
-# Contributing to **CTX**
+# Contributing
 
-We're excited to welcome you as a contributor to the **CTX** project! This guide will help you get started
-with contributing to our project.
+We're excited to welcome you as a contributor to our project!
 
 ## How to Contribute
 
@@ -10,17 +9,14 @@ There are many ways to contribute to **CTX**:
 1. **Report Issues**: If you find a bug or have a
    suggestion, [create an issue](https://github.com/context-hub/generator/issues) on our GitHub repository.
 2. **Submit Pull Requests**: Have a fix or a new feature? Submit a pull request!
-3. **Improve Documentation**: Help us make our documentation more clear, comprehensive, and accessible.
+3. **Improve Documentation**: Help us make our [documentation](https://github.com/context-hub/docs) more clear,
+   comprehensive, and accessible.
 4. **Share Your Use Cases**: Let us know how you're using **CTX** in your projects.
 
 We label issues that are suitable for community contribution with the `help wanted` tag. Additionally, we use labels
 such as `good first issue` for newcomer-friendly tasks, and complexity indicators to help you choose tasks that match
 your experience level.
 
-I'd be happy to write a better instruction for the Getting Started section that highlights the use of the context.yaml
-file for context generation. This will help new contributors understand how they can use **CTX** itself to
-explore and work with the codebase.
-
 ## Getting Started with Contributing
 
 Follow this guide to set up your environment and effectively contribute to the **CTX** project. We've designed
@@ -37,31 +33,19 @@ cd context-generator
 composer install
 
 # Make the CLI tool available locally
-chmod +x context-generator
+chmod +x ctx
 
 # Test the command
-./context-generator --help
+./ctx --help
 ```
 
-> **Note:** Use the local `./context-generator` command during development to test your changes. The globally installed
-`ctx` command won't reflect your local modifications.
+> **Note:** Use the local `./ctx` command during development to test your changes. The globally installed`ctx` command
+> won't reflect your local modifications.
 
 ### 2. Understand the Project Structure
 
-Before diving into specific components, familiarize yourself with the project structure:
-
-```
-└── src/
-    ├── ConfigLoader/ - Configuration loading and processing
-    ├── Console/ - CLI commands and interfaces
-    ├── Document/ - Document generation and formatting
-    ├── Fetcher/ - Content fetching mechanisms
-    ├── Lib/ - Utility libraries and helpers
-    ├── Modifier/ - Content modification systems
-    └── Source/ - Different source type implementations
-```
-
-To get a more detailed view of the project structure, use the `tree` source type:
+Before diving into specific components, familiarize yourself with the project structure. To get a detailed view of the
+project structure, use the `tree` source type:
 
 ```yaml
 documents:
@@ -77,27 +61,13 @@ documents:
 Run this configuration to generate a visual representation of the codebase structure:
 
 ```bash
-./context-generator
+./ctx
 ```
 
-This will create a `docs/file-structure.md` file that outlines the project's organization. Just put this file in the
+This will create a `docs/file-structure.md` file that outlines the project's organization. Put this file in the
 Claude project context to help it understand the codebase.
 
-### 3. Explore the Codebase Using **CTX**
-
-The project includes a pre-configured `context.yaml` file to help you explore the codebase:
-
-```bash
-# Generate context files using the provided configuration
-./context-generator
-
-# This will create documentation in the .context/ directory
-```
-
-The generated context files provide a comprehensive overview of the most important parts of the system. Upload documents
-connected to your task to an LLM like Claude to get a better understanding of the codebase.
-
-### 4. Request Specific Context Using YAML
+### 3. Request Specific Context Using YAML
 
 When working on a specific feature or bug fix, create targeted context requests to get exactly the information you need.
 
@@ -122,7 +92,7 @@ documents:
 Generate your custom context:
 
 ```bash
-./context-generator
+./ctx
 ```
 
 This structured approach offers several advantages:
@@ -134,7 +104,7 @@ This structured approach offers several advantages:
 
 Let me enhance the section on collaborating with AI assistants to include this important recommendation:
 
-### 5. Collaborate with AI Assistants
+### 4. Collaborate with AI Assistants
 
 Share the generated context files with AI assistants like Claude to get help with:
 
@@ -176,7 +146,7 @@ Include the problem statement, proposed solution, implementation details, and po
 This gives the AI assistant exactly the context needed to provide meaningful assistance with your specific task, and the
 resulting document becomes a valuable asset throughout your development process.
 
-### 6. Implement Your Changes
+### 5. Implement Your Changes
 
 > **Tip**: When you provide all required context to Claude, it will be able to solve your task efficiently. With proper
 > context, the solution will be fast, precise, and aligned with the project's patterns and standards.
@@ -196,7 +166,7 @@ With a solid understanding of the codebase:
     3. Review and refine the suggested documentation
     4. Include the updated documentation in your pull request
 
-### 7. Document Your Changes
+### 6. Document Your Changes
 
 If you worked with an LLM to implement your changes, ask it to help draft commit messages and pull request descriptions.
 
@@ -213,7 +183,7 @@ documents:
         commit: "unstaged"  # or "staged" if you've already staged your changes
 ```
 
-### 8. Submit Your Pull Request
+### 7. Submit Your Pull Request
 
 - Push your changes to your fork
 - Open a pull request with a clear description
diff --git a/docs/index.md b/docs/index.md
@@ -2,12 +2,16 @@
 
 ![Good morning, LLM](https://github.com/user-attachments/assets/8129f227-dc3f-4671-bc0e-0ecd2f3a1888)
 
-**CTX** is a tool that solves the context management gap when working with LLMs like ChatGPT or Claude. It helps
-developers organize and automatically collect information from their codebase into structured documents that can be
-easily shared with AI assistants.
+During development, your codebase constantly evolves. Files are added, modified, and removed. Each time you need to
+continue working with an LLM, you need to regenerate context to provide updated information about your current codebase
+state.
 
-**The tool doesn't work instead of developer - it's a tool where developers can describe their contexts and use them
-to provide information to LLMs.**
+**CTX** is a context management tool that gives developers full control over what AI sees from their codebase. Instead
+of letting AI tools guess what's relevant, you define exactly what context to provide - making your AI-assisted
+development more predictable, secure, and efficient.
+
+It helps developers organize contexts and automatically collect information from their codebase into structured
+documents that can be easily shared with LLM.
 
 For example, a developer describes what context they need:
 
@@ -56,30 +60,84 @@ into a chat session or provided via the built-in [MCP server](./mcp/index.md).
 
 > Here is a [Quickstart guide](./quick-start.md) to get you started with CTX.
 
-### The Problem CTX Solves
+### Why CTX?
+
+Current AI coding tools automatically scan your entire codebase, which creates several issues:
+
+- **Security risk**: Your sensitive files (env vars, tokens, private code) get uploaded to cloud services
+- **Context dilution**: AI gets overwhelmed with irrelevant code, reducing output quality
+- **No control**: You can't influence what the AI considers when generating responses
+- **Expensive**: Premium tools charge based on how much they scan, not how much you actually need
+
+### The CTX Approach
+
+You know your code better than any AI. CTX puts you in control:
+
+- ✅ Define exactly what context to share - no more, no less
+- ✅ Keep sensitive data local - works with local LLMs or carefully curated cloud contexts
+- ✅ Generate reusable, shareable contexts - commit configurations to your repo
+- ✅ Improve code architecture - designing for AI context windows naturally leads to better modular code
+- ✅ Works with any LLM - Claude, ChatGPT, local models, or future tools
+
+## Real-World Use Cases
+
+### 🚀 Onboarding New Team Member
+
+```yaml
+# Quick project overview for new developers
+documents:
+  - description: "Project Architecture Overview"
+    outputPath: "docs/architecture.md"
+    sources:
+      - type: tree
+        sourcePaths: [ "src" ]
+        maxDepth: 2
+      - type: file
+        description: "Core interfaces and main classes"
+        sourcePaths: [ "src" ]
+        filePattern: "*Interface.php"
+```
+
+### 📝 Feature Development
+
+```yaml
+# Context for developing a new feature
+documents:
+  - description: "User Authentication System"
+    outputPath: "contexts/auth-context.md"
+    sources:
+      - type: file
+        sourcePaths: [ "src/Auth", "src/Models" ]
+        filePattern: "*.php"
+      - type: git_diff
+        description: "Recent auth changes"
+        commit: "last-week"
+```
 
-**Without such a tool, you would need to:**
+### 📚 Documentation Generation
 
-- Manually search for all files that were changed
-- Copy their contents each time
-- Explain the codebase structure repeatedly
-- Spend significant time maintaining context consistency
+```yaml
+# Generate API documentation
+documents:
+  - description: "API Documentation"
+    outputPath: "docs/api.md"
+    sources:
+      - type: file
+        sourcePaths: [ "src/Controllers" ]
+        modifiers: [ "php-signature" ]
+        contains: [ "@Route", "@Api" ]
+```
 
-This repetitive process becomes frustrating and can discourage continued development, as you end up doing the same
-context-gathering work over and over instead of writing code.
+## Join Our Community
 
-Since CTX describes contexts, this process becomes automated.
+Join hundreds of developers using CTX for professional AI-assisted coding:
 
-## Use Cases
+[![Join Discord](https://img.shields.io/discord/1419284404315881633?color=5865F2&label=Join%20Discord&logo=discord&logoColor=white&style=for-the-badge)](https://discord.gg/YmFckwVkQM)
 
-When working with AI-powered development tools context is everything.
+**What you'll find in our Discord:**
 
-- **Code Development**: Maintain up-to-date context for iterative development sessions with AI assistants. When your
-  codebase changes, regenerate context documents to continue working with current code state.
-- **Code Refactoring**: Provide AI with complete context about classes, functions, and their dependencies for
-  refactoring assistance.
-- **Documentation**: Generate documentation by combining source code with explanations, using AI to create guides and
-  references based on actual code.
-- **Team Workflows**: Share context configurations across team members to maintain consistent AI interaction patterns.
-- **MCP Integration**: Connect Claude AI directly to your codebase for real-time, context-aware assistance without
-  manual context sharing.
+- 💡 Share and discover context configurations
+- 🛠️ Get help with setup and advanced usage
+- 🚀 Showcase your AI development workflows
+- 🤝 Connect with like-minded developers
+- 📢 First to know about new releases and features
