# 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
```