Added project documentation in wiki and established INTENT.md

wiki/RecommendedRepositoryLayout.md

@@ -0,0 +1,66 @@
+RecommendedRepositoryLayout
+
+*Pragmatic directory layout for dev projects*
+
+## 📁 Recommended Repository Layout
+
+Adopting a consistent repository layout is essential for **collaboration**, **maintainability**, and **scalability**. A well-structured project allows developers to quickly understand the codebase, simplifies automation, and reduces time spent searching for files. This convention separates source code from other assets and organizes project files logically.
+
+---
+
+## 🌳 Core Directory Structure
+
+The following directories represent a standard, universal layout for most projects.
+
+* `**src/**`: Contains the **source code**—the core files of your application.
+* `**dist/**`: Holds the **compiled or minified code** ready for production deployment.
+* `**test/**`: A dedicated directory for all **unit, integration, and end-to-end tests**.
+* `**docs/**`: Stores all project **documentation**, including API guides and user manuals.
+* `**assets/**`: For **static assets** like images, fonts, and stylesheets.
+* `**vendor/**`: For **third-party libraries** not managed by a package manager.
+* `**lib/**`: For shared code and **libraries** created as part of the project.
+* `**bin/**`: Contains **executable scripts** for common tasks like setup, testing, or deployment.
+* `**.gitignore**` **and other dotfiles**: Essential configuration files that manage project-specific settings (e.g., Git ignores).
+
+---
+
+## 🗂️ A Deeper Dive: A Detailed Example
+
+For more complex projects, a **clean architecture** approach offers a robust and scalable structure. This example demonstrates how to organize a project within the `src/` directory to enforce separation of concerns. 
+
+* `**project_name/**`: The main package.
+    * `**domain/**`: Houses the **core business logic** (models, entities) independent of any framework.
+    * `**application/**`: Contains **services and use cases** that orchestrate the domain logic.
+    * `**infrastructure/**`: Manages **external dependencies** like databases, third-party APIs, and logging.
+    * `**interfaces/**`: Holds **user-facing interfaces**.
+        * `**cli/**`: Logic for a command-line interface.
+        * `**api/**`: **(Optional)** Logic for a web API.
+    * `**shared/**`: Reusable utilities and types used across different layers.
+
+---
+
+## ⚙️ Root-Level Files and Directories
+
+The root of your repository should contain files and directories that provide high-level project information and setup instructions.
+
+* `**README.md**`: The primary documentation file for a project overview, installation, and usage.
+* `**LICENSE**`: Specifies the project's intellectual property license.
+* `**pyproject.toml**` **/** `**package.json**`: Defines project dependencies and configuration for package managers.
+* `**Makefile**` **/** `**justfile**`: A file for common development commands.
+* `**docs/**`: **(Recommended)** A top-level directory for all project documentation.
+* `**tests/**`: **(Recommended)** A top-level directory for all test files.
+
+---
+
+## 💡 Guiding Principles
+
+These rules explain the rationale behind this convention.
+
+* **Separation of Concerns**: The layout strictly separates source code (`src/`), documentation (`docs/`), and development tools (`tools/`) to improve clarity and maintainability.
+* **Encapsulation**: Moving logic to specific layers (`domain/`, `application/`) enforces a **clean architecture**, reducing dependencies and making the project easier to test.
+* **Idempotency**: This structure is predictable and repeatable, ensuring that creating a new project with this convention always yields a consistent result.
+* **Extensibility**: The layout is easily extensible. New interfaces or tools can be added without disrupting the core structure.
+
+
+
+xxx