Add module doc template and AI writing rules

docs/templates/module-doc-rules.md

@@ -0,0 +1,123 @@
+# Module Documentation — AI Writing Rules
+
+Rules Grace follows when creating or updating any module doc using `module-doc-template.md`.
+
+---
+
+## General Rules
+
+1. Do not delete any existing content unless explicitly instructed. Prefer appending or updating.
+2. Preserve all formatting: Markdown headings, code blocks, bullets, spacing.
+3. Additions must match the existing style and formatting in the file.
+4. Return only the updated section(s) with AI GENERATED markers — not the full file — unless the full file is explicitly requested.
+
+---
+
+## Section-Specific Rules
+
+### Overview
+Describe what the module does, its purpose, and primary use cases.
+
+### Installation
+Add installation steps, version notes, or dependency instructions. Format all commands in code blocks.
+
+### Configuration
+Update or add configuration options with defaults and examples. Mark optional vs required parameters clearly.
+
+### Connections to other services, systems, and modules
+List ALL connections made to other services, systems, and modules. Describe where this module sits in the stack.
+
+### Usage Examples
+Add practical code snippets or commands. Append new examples — never remove old ones.
+
+### Dependencies
+Add required libraries/modules with version constraints. Append only. Always check:
+- Have credentials been added to Infisical?
+- Is there a Web UI that needs to be configured?
+
+### Troubleshooting
+Add solutions to common issues. Preserve existing tips. Include date stamps on new items.
+
+### Change Log
+Append entries in the format:
+```
+YYYY-MM-DD | Added/Updated/Fixed | Summary of changes
+```
+Never remove previous entries.
+
+### References
+Link to official docs, repos, and related internal docs. Flag external docs with:
+```
+AI TODO: Schedule RAG import for future reference.
+```
+
+---
+
+## Examples
+
+### Overview Example
+```
+The {{module_name}} service provides secure handling of sensitive configuration data using
+Infisical for secret management. It abstracts access to API keys, database credentials,
+and environment variables, making deployment and scaling more secure and consistent.
+
+Primary Use Cases:
+- Automated retrieval of secrets at runtime
+- Centralized configuration for microservices
+- Integration with CI/CD pipelines for secure deployments
+```
+
+### Installation Example
+```bash
+pip install {{module_name}}=={{version}}
+
+# Ensure the Infisical CLI is installed and authenticated:
+curl -sL https://app.infisical.com/cli/install.sh | bash
+infisical login --token $INFISICAL_TOKEN
+
+# Verify installation:
+python -c "import {{module_name}}; print({{module_name}}.__version__)"
+
+# Optional: Install additional adapters if using PostgreSQL or Redis:
+pip install {{module_name}}[postgres,redis]
+```
+
+### Configuration Example
+```yaml
+# Required configuration (fetched via Infisical)
+SECRETS_PROJECT: my_project
+SECRETS_ENV: production
+
+# Optional configuration
+ENABLE_LOGGING: false        # Default false
+CACHE_EXPIRY: 3600           # In seconds, default 1 hour
+
+# Advanced options
+RETRY_POLICY: exponential_backoff
+RETRY_ATTEMPTS: 5
+```
+
+### Connections Example
+```
+- PostgreSQL database: Automatically retrieves DB_USER and DB_PASSWORD from Infisical.
+- Redis cache: Optional caching layer, configured via CACHE_URL.
+- CI/CD pipelines: Integrates with GitHub Actions or GitLab CI for secret injection.
+- Microservices: Exposes a gRPC API for internal service communication.
+
+AI TODO: Schedule RAG import for each external system's documentation for future reference.
+```
+
+### Troubleshooting Example
+```
+- Cannot retrieve secrets: Ensure INFISICAL_TOKEN is valid and CLI is logged in.
+- Module fails to import: Verify Python version >= 3.11 and dependencies are installed.
+- Cache not updating: Check CACHE_URL and network connectivity.
+- Retries failing: Verify RETRY_POLICY settings; default is exponential_backoff.
+- Secrets missing in production: Confirm project and environment settings in Infisical.
+```
+
+### Change Log Example
+```
+2026-03-17 | Added   | Initial draft of module documentation with Infisical integration
+2026-03-18 | Updated | Added optional caching layer and retry policy
+```

docs/templates/module-doc-template.md

@@ -0,0 +1,108 @@
+# {{module_name}} Documentation
+<!-- 
+AI USAGE INSTRUCTIONS:
+- Preserve all formatting (headings, bullet points, code blocks).
+- Always append new items instead of deleting existing content unless a removal is explicitly authorized.
+-->
+
+---
+
+## Overview
+{{module_name}} is a module/service that provides the following functionality:
+
+- Purpose: {{brief purpose description}}
+- Primary Use Cases: {{key scenarios}}
+
+---
+
+## Installation
+<!-- AI GENERATED START: Installation -->
+{{installation_steps}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- Only modify the installation instructions here.
+- Include version-specific steps if relevant.
+- Add notes about dependencies.
+- Keep commands formatted in code blocks.
+
+---
+
+## Configuration
+<!-- AI GENERATED START: Configuration -->
+{{configuration_details}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- Only update configuration options.
+- Include default values and examples.
+- Do not remove existing valid options.
+- Highlight optional vs required parameters.
+
+---
+
+## Connections to other services, systems, and modules
+<!-- AI GENERATED START: Dependencies -->
+{{connections_list_and_description}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- List all connection that are made to other services, systems, and modules. Where does this module sit in the stack?
+
+---
+
+## Usage Examples
+<!-- AI GENERATED START: Usage Examples -->
+{{usage_examples}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- Add practical examples, commands, or API snippets.
+- Format code blocks correctly.
+- If updating, append new examples; never rewrite old ones unless flagged.
+
+---
+
+## Dependencies
+<!-- AI GENERATED START: Dependencies -->
+{{dependencies_list}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- List all libraries, modules, or services required.
+- Include version constraints if applicable.
+- Append new dependencies rather than replacing the list.
+- Have credentials been added to Infisical?
+- Is there a Web UI that needs to be configured?
+
+---
+
+## Troubleshooting
+<!-- AI GENERATED START: Troubleshooting -->
+{{troubleshooting_tips}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- Add solutions to common issues encountered during installation, configuration, or usage.
+- Preserve existing tips.
+- Add new tips with date stamps.
+
+---
+
+## Change Log
+<!-- AI GENERATED START: Change Log -->
+{{change_log}}
+<!-- AI GENERATED END -->
+
+AI PROMPT GUIDELINE:
+- Always append a new entry with:
+  - Date (YYYY-MM-DD)
+  - Type (Added / Updated / Fixed)
+  - Summary of changes
+- Do not remove previous entries.
+
+---
+
+## References
+- [Official Module Repo]({{repo_url}})
+- [Related Documentation]({{related_docs_url}})