chore: import upstream snapshot with attribution

documentation/dev/templates/TEMPLATE.reference.md

@@ -0,0 +1,222 @@
+---
+title: "Reference Documentation Template"
+description: "This template defines the standard structure and conventions for REFERENCE documents within the Sirius project, ensuring comprehensive technical specifications and API documentation."
+template: "TEMPLATE.template"
+version: "1.0.0"
+last_updated: "2025-01-03"
+author: "AI Assistant"
+tags: ["template", "reference", "technical", "specifications", "api"]
+categories: ["project-management", "development"]
+difficulty: "intermediate"
+prerequisites: ["ABOUT.documentation.md"]
+related_docs:
+  - "ABOUT.documentation.md"
+  - "TEMPLATE.documentation-standard.md"
+dependencies: []
+llm_context: "high"
+search_keywords:
+  [
+    "reference template",
+    "technical specs",
+    "api documentation",
+    "specifications",
+  ]
+---
+
+# [System/Component] Reference
+
+## Purpose
+
+This document provides comprehensive technical reference information for [specific system/component/API] within the Sirius project. REFERENCE documents serve as authoritative sources for technical specifications, API endpoints, configuration options, and implementation details.
+
+## When to Use
+
+- **API Development**: When implementing or consuming APIs
+- **Integration Work**: When connecting systems or components
+- **Configuration**: When setting up or modifying system parameters
+- **Debugging**: When troubleshooting technical issues
+- **Code Review**: When reviewing implementation against specifications
+
+## How to Use
+
+### Quick Reference
+
+1. **Find the relevant section** for your specific need
+2. **Check the prerequisites** and requirements
+3. **Follow the examples** for implementation patterns
+4. **Reference the specifications** for exact details
+5. **Use the troubleshooting section** for common issues
+
+### Common Patterns
+
+```bash
+# [Common pattern 1]
+[example implementation]
+
+# [Common pattern 2]
+[example implementation]
+```
+
+## What It Is
+
+### Technical Overview
+
+[Detailed technical explanation of the system/component/API]
+
+### Architecture
+
+[Technical architecture with diagrams and component relationships]
+
+### Data Models
+
+#### [Model 1]
+
+```json
+{
+  "field1": "type",
+  "field2": "type",
+  "field3": {
+    "nested_field": "type"
+  }
+}
+```
+
+#### [Model 2]
+
+```yaml
+field1: type
+field2: type
+field3:
+  nested_field: type
+```
+
+### API Endpoints
+
+#### [Endpoint 1]
+
+- **Method**: `GET|POST|PUT|DELETE`
+- **Path**: `/api/v1/endpoint`
+- **Description**: [What this endpoint does]
+- **Parameters**:
+  - `param1` (required): [Description]
+  - `param2` (optional): [Description]
+- **Response**: [Response format and status codes]
+- **Example**:
+
+```bash
+curl -X GET "http://localhost:9001/api/v1/endpoint?param1=value"
+```
+
+#### [Endpoint 2]
+
+- **Method**: `GET|POST|PUT|DELETE`
+- **Path**: `/api/v1/endpoint2`
+- **Description**: [What this endpoint does]
+- **Request Body**: [Request format]
+- **Response**: [Response format and status codes]
+- **Example**:
+
+```bash
+curl -X POST "http://localhost:9001/api/v1/endpoint2" \
+  -H "Content-Type: application/json" \
+  -d '{"field1": "value", "field2": "value"}'
+```
+
+### Configuration Options
+
+| Option    | Type    | Default   | Description   | Required |
+| --------- | ------- | --------- | ------------- | -------- |
+| `option1` | string  | "default" | [Description] | Yes      |
+| `option2` | integer | 0         | [Description] | No       |
+| `option3` | boolean | false     | [Description] | No       |
+
+### Environment Variables
+
+| Variable   | Description   | Example  | Required |
+| ---------- | ------------- | -------- | -------- |
+| `ENV_VAR1` | [Description] | `value1` | Yes      |
+| `ENV_VAR2` | [Description] | `value2` | No       |
+
+### File Formats
+
+#### [Format 1]
+
+```yaml
+# YAML format example
+key1: value1
+key2:
+  nested_key: nested_value
+  list_item:
+    - item1
+    - item2
+```
+
+#### [Format 2]
+
+```json
+{
+  "key1": "value1",
+  "key2": {
+    "nested_key": "nested_value",
+    "list_item": ["item1", "item2"]
+  }
+}
+```
+
+### Error Codes
+
+| Code   | HTTP Status | Description         | Resolution   |
+| ------ | ----------- | ------------------- | ------------ |
+| `E001` | 400         | [Error description] | [How to fix] |
+| `E002` | 401         | [Error description] | [How to fix] |
+| `E003` | 500         | [Error description] | [How to fix] |
+
+## Troubleshooting
+
+### FAQ
+
+**Q: [Common technical question 1]**
+A: [Technical answer with specific details]
+
+**Q: [Common technical question 2]**
+A: [Technical answer with specific details]
+
+**Q: [Common technical question 3]**
+A: [Technical answer with specific details]
+
+### Command Reference
+
+| Command      | Purpose        | Example     | Notes              |
+| ------------ | -------------- | ----------- | ------------------ |
+| `[command1]` | [What it does] | `[example]` | [Additional notes] |
+| `[command2]` | [What it does] | `[example]` | [Additional notes] |
+| `[command3]` | [What it does] | `[example]` | [Additional notes] |
+
+### Common Issues
+
+| Issue     | Symptoms          | Root Cause       | Solution           |
+| --------- | ----------------- | ---------------- | ------------------ |
+| [Issue 1] | [How to identify] | [Why it happens] | [Step-by-step fix] |
+| [Issue 2] | [How to identify] | [Why it happens] | [Step-by-step fix] |
+| [Issue 3] | [How to identify] | [Why it happens] | [Step-by-step fix] |
+
+### Debugging Steps
+
+1. **Check [specific thing]**: [How to check and what to look for]
+2. **Verify [specific thing]**: [How to verify and expected results]
+3. **Test [specific thing]**: [How to test and success criteria]
+4. **Review [specific thing]**: [What to review and common patterns]
+
+## Lessons Learned
+
+### [Date] - [What was learned]
+
+[Description of technical lesson learned and how it improved the system]
+
+### [Date] - [What was learned]
+
+[Description of technical lesson learned and how it improved the system]
+
+---
+
+_This document follows the Sirius Documentation Standard. For questions about documentation structure, see [ABOUT.documentation.md](../ABOUT.documentation.md)._