opensearch-sugar 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6d1486b22e98b74ba4476a37426aec9731b02b6a7a77205a3efd887b9b4a7a4a
+  data.tar.gz: 0af59b7653390f2a19b6226a8addd7d61b73cad37e0261001a2a8aac8f23c06e
+SHA512:
+  metadata.gz: 7ca00642cf6bf0b9ba3fdfb28d95e22c5a76b2ffa5b50bf4decca0f76a390a40c82556cd6f44ce60f168c09ef14777b06c8de1d6d08504e0e070ae539810449b
+  data.tar.gz: 26c12cdf67f9a1dd2e01006d21b05bb088ededb6a75672e9263734fe9caafa47fec52f1057e1b53c95d8c4f6227a552e62138d6c1302de7ebec6bcef80b03c7c

data/.agents/skills/diataxis/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: diataxis
+description: Create and evaluate documentation using the Diátaxis framework. Use when writing, organizing, or auditing documentation to ensure it serves distinct user needs through four systematic categories (Tutorials, How-to Guides, Reference, Explanation). Ideal for diagnosing documentation problems, separating mixed content, and ensuring each piece serves a single, clear purpose.
+metadata: 
+  version: 1.0.0
+  author: arisng
+---
+
+# Diátaxis Documentation Skill
+
+The **Diátaxis framework** organizes documentation by user need, not by topic. This skill helps you create documentation that works for your audience.
+
+## The Four Categories
+
+Diátaxis distinguishes four documentation needs using a 2×2 matrix:
+
+|              | **Practical**     | **Theoretical** |
+| ------------ | ----------------- | --------------- |
+| **Learning** | **Tutorials**     | **Explanation** |
+| **Working**  | **How-to Guides** | **Reference**   |
+
+### Quick Reference
+
+- **Tutorials** (Learning + Practical): "Teach me by doing"
+- **How-to Guides** (Working + Practical): "Help me accomplish X"
+- **Reference** (Working + Theoretical): "Tell me how things work"
+- **Explanation** (Learning + Theoretical): "Help me understand why"
+
+## Working With Documentation
+
+### 1. Diagnose What You Have
+
+When given documentation, determine which category it belongs to:
+
+- **Is it teaching or working?** (Axis 1)
+- **Is it practical or theoretical?** (Axis 2)
+- **Does it serve a single purpose or is it mixed?**
+
+### 2. Identify Problems
+
+Common documentation problems map to mixing categories:
+
+- **Tutorials polluted with explanation** → Users get lost in "why" when they should focus on "do"
+- **How-to guides that teach** → Assumes no prior knowledge; should link to tutorials instead
+- **Reference missing examples** → Should show, not just describe
+- **Explanation that instructs** → Should link to how-to guides instead
+- **Missing entire categories** → Product has only reference; users can't get started
+
+### 3. Choose the Right Template
+
+When writing documentation, use the appropriate template:
+
+- **Writing a tutorial?** See [tutorial-template.md](references/tutorial-template.md)
+- **Writing a how-to guide?** See [how-to-guide-template.md](references/how-to-guide-template.md)
+- **Writing reference?** See [reference-template.md](references/reference-template.md)
+- **Writing explanation?** See [explanation-template.md](references/explanation-template.md)
+- **Want real-world examples?** See [examples.md](references/examples.md)
+
+### 4. Apply Category-Specific Principles
+
+See [framework.md](references/framework.md) for detailed principles, language patterns, and anti-patterns for each category.
+
+### 5. Structure Output
+
+Create documentation in this structure:
+
+```
+.docs/
+├── tutorials/          # Learning-oriented lessons
+│   └── [topic]/
+├── how-to/             # Task-oriented guides
+│   └── [domain]/
+├── reference/          # Technical descriptions
+│   └── [component]/
+├── explanation/        # Conceptual discussions
+│   └── [subject]/
+└── index.md            # Navigation (generated automatically)
+```
+
+**Naming conventions:**
+- Use `kebab-case` for all files and folders
+- Tutorials: `getting-started-with-x.md`, `your-first-y.md`
+- How-to: `how-to-configure-x.md`, `how-to-deploy-y.md`
+- Reference: `api-reference.md`, `configuration-options.md`
+- Explanation: `about-architecture.md`, `understanding-x.md`
+
+### 6. Generate Index
+
+Use the Python script to automatically generate the `index.md` file:
+
+```bash
+python skills/diataxis/scripts/generate_index.py
+```
+
+This script scans the `.docs/` subfolders, extracts titles from `.md` files, and creates links organized by category. Run it whenever you add or remove documentation files to keep the index up-to-date.
+
+## Common Workflows
+
+### Auditing existing documentation
+
+1. Read through each document
+2. Determine which category it belongs to
+3. Flag content that belongs in other categories
+4. Suggest extractions or links to separate content
+5. Check for "category pollution" (mixing purposes)
+
+### Writing new documentation
+
+1. Identify the user need (learning/working, practical/theoretical)
+2. Choose the appropriate category
+3. Find the right template:
+   - Tutorial: [tutorial-template.md](references/tutorial-template.md)
+   - How-to: [how-to-guide-template.md](references/how-to-guide-template.md)
+   - Reference: [reference-template.md](references/reference-template.md)
+   - Explanation: [explanation-template.md](references/explanation-template.md)
+4. Use category-specific language patterns (in template)
+5. See [examples.md](references/examples.md) for production-grade examples
+6. Save in the correct folder structure
+
+### Refactoring mixed content
+
+1. Read the mixed document
+2. Identify sections that belong in different categories
+3. Create separate files for each category
+4. In each file, link to related content in other categories
+5. Remove the original mixed document
+
+### Generating the documentation index
+
+To keep the documentation index consistent and up-to-date:
+
+1. Ensure all documentation files are placed in the appropriate `.docs/` subfolders (`tutorials/`, `how-to/`, `reference/`, `explanation/`).
+2. Run the generation script: `python skills/diataxis/scripts/generate_index.py`
+3. The script will automatically scan for `.md` files, extract their titles, and update `.docs/index.md` with organized links.
+
+This workflow should be used after adding new documents or restructuring existing ones.
+
+## Key Principle
+
+**Every document should serve exactly one user need.** When content serves multiple needs, separate it into multiple documents and link them together. This is better than trying to serve all needs in one place.
+
+Remember: *The first rule of teaching is simply: don't try to teach.* Let the structure and the doing facilitate learning.

data/.agents/skills/diataxis/references/examples.md

@@ -0,0 +1,420 @@
+# Real-World Diataxis Examples
+
+Complete, production-grade examples for each documentation type.
+
+## Table of Contents
+1. [Example 1: Tutorial](#example-1-tutorial)
+2. [Example 2: How-to Guide](#example-2-how-to-guide)
+3. [Example 3: Reference](#example-3-reference)
+4. [Example 4: Explanation](#example-4-explanation)
+
+---
+
+## Example 1: Tutorial
+
+**Source**: Getting started with a Python web framework
+
+```markdown
+# Your First Django App
+
+Create a simple blogging application with posts and comments.
+
+## What you'll build
+
+A working blog where you can create, read, and delete posts. By the end, 
+you'll understand Django's MVT (Model-View-Template) architecture.
+
+## Before you start
+
+- Python 3.8+ installed
+- pip installed
+- Basic familiarity with command line
+- A code editor (VS Code, Sublime, etc.)
+
+## Step 1: Create a project directory
+
+```bash
+mkdir my_blog
+cd my_blog
+```
+
+Notice that you're now inside the directory. Your prompt should show `my_blog` 
+in the path.
+
+## Step 2: Create a virtual environment
+
+```bash
+python -m venv venv
+source venv/bin/activate  # On Windows: venv\Scripts\activate
+```
+
+The prompt should now start with `(venv)`. This means the virtual 
+environment is active.
+
+## Step 3: Install Django
+
+```bash
+pip install django
+```
+
+Wait a moment for installation. You should see "Successfully installed Django" 
+in your terminal.
+
+## Step 4: Create a Django project
+
+```bash
+django-admin startproject blog_config .
+django-admin startapp blog
+```
+
+You should see new folders: `blog_config/` and a `blog/` folder.
+
+## Step 5: Run the development server
+
+```bash
+python manage.py runserver
+```
+
+The output will show:
+
+```
+Starting development server at http://127.0.0.1:8000/
+```
+
+Open your browser and visit `http://127.0.0.1:8000/`. You should see 
+Django's welcome page.
+
+## Step 6: Create a simple model
+
+Edit `blog/models.py`:
+
+```python
+from django.db import models
+
+class Post(models.Model):
+    title = models.CharField(max_length=200)
+    content = models.TextField()
+    created_at = models.DateTimeField(auto_now_add=True)
+    
+    def __str__(self):
+        return self.title
+```
+
+Notice that we've defined what a Post is: it has a title, content, and 
+creation timestamp.
+
+## What you've built
+
+You've created a Django project with a Post model. You now understand how 
+Django organizes projects, applications, and data models. Your development 
+server is running, and you can extend it by creating views and templates.
+
+## Next steps
+
+- **Customize it**: [How to add comment functionality](...)
+- **Understand it**: [About Django's MVT architecture](...)
+- **Explore**: [Django models reference](...)
+```
+
+---
+
+## Example 2: How-to Guide
+
+**Source**: Deploying a database migration
+
+```markdown
+# How to migrate a PostgreSQL database with zero downtime
+
+This guide shows you how to move your database to a new server while 
+keeping your application running.
+
+## When to use this guide
+
+Use this when you need to move PostgreSQL to new infrastructure 
+(new server, new provider, new region) while serving live traffic.
+
+## Before you start
+
+- PostgreSQL 9.5+ on both source and destination
+- A standby server or read replica capability
+- SSH access to both servers
+- About 30-60 minutes of work
+
+## Context
+
+Zero-downtime migration works by setting up replication from your old 
+database to the new one, letting it catch up, then switching your 
+application to use the new server. The entire switch takes seconds.
+
+## Steps
+
+### 1. Set up replication from source to destination
+
+```bash
+psql -h source-server -U postgres -c "SELECT pg_start_backup('migration', true);"
+```
+
+This creates a consistent backup point that the destination can follow.
+
+### 2. Backup the source database
+
+```bash
+pg_basebackup -h source-server -D /var/lib/postgresql/backup -P -v
+```
+
+This creates a full backup of your source database. On a large database, 
+this may take several minutes.
+
+### 3. Start replication on destination
+
+```bash
+psql -h dest-server -c "ALTER SYSTEM SET primary_conninfo = 'host=source-server ...'"
+pg_ctl -D /path/to/data restart
+```
+
+Wait 5-10 seconds for replication to establish. Check status with `pg_stat_replication` 
+on the source.
+
+### 4. Monitor replication lag
+
+```bash
+psql -h source-server -U postgres -c "SELECT slot_name, restart_lsn, confirmed_flush_lsn FROM pg_replication_slots;"
+```
+
+Replication lag is normal. Wait until it reaches zero before switching.
+
+### 5. Switch application to use destination
+
+Update your connection string to point to the new server. This typically takes 
+2-5 seconds per application instance.
+
+```bash
+# Update config and restart app
+systemctl restart myapp
+```
+
+### 6. Verify everything works
+
+```bash
+psql -h dest-server -c "SELECT count(*) FROM [your_table];"
+```
+
+Compare the row count to your source. They should match.
+
+## Troubleshooting
+
+**Problem: Replication lag is too high**
+Solution: The source is getting too much write traffic during migration. 
+Reduce application load or increase network bandwidth. Lag is normal; wait 
+until it syncs before switching.
+
+**Problem: Application fails after switching**
+Solution: Check your new connection string. A common issue is firewall 
+blocking the new destination. Test connectivity: `pg_isready -h dest-server`
+
+**Problem: Replication doesn't start**
+Solution: Ensure the destination server is empty or a clean backup. Also 
+verify network connectivity: `ping dest-server` and check firewall rules 
+for port 5432.
+
+## Variations
+
+If you're using Amazon RDS, use AWS Database Migration Service instead. 
+It handles replication automatically.
+
+If you're on MySQL, the process is similar but use `mysqldump` and 
+`mysqlbinlog` for replication.
+
+## Related guides
+
+- [How to set up read replicas](...)
+- [How to monitor replication lag](...)
+- [How to handle network failures during migration](...)
+
+## See also
+
+- [About PostgreSQL replication architecture](...)
+- [Troubleshooting PostgreSQL connection issues](...)
+```
+
+---
+
+## Example 3: Reference
+
+**Source**: API endpoint reference
+
+```markdown
+# POST /api/articles Reference
+
+Create a new article.
+
+## Request
+
+**Endpoint**: `POST /api/articles`
+
+**Authentication**: Required. Bearer token in Authorization header.
+
+**Headers**
+| Header | Value |
+|--------|-------|
+| Authorization | `Bearer {jwt_token}` |
+| Content-Type | `application/json` |
+
+**Body**
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| title | string | Yes | Article title, 1-200 characters |
+| content | string | Yes | Article body, 1-50000 characters |
+| published | boolean | No | Default: false. If true, article is immediately visible |
+| tags | array | No | Up to 10 tags. Each 1-50 characters |
+
+## Response
+
+**Status**: 201 Created
+
+**Body**
+```json
+{
+  "id": "art_abc123",
+  "title": "My Article",
+  "content": "...",
+  "published": false,
+  "tags": ["tech", "tutorial"],
+  "created_at": "2025-12-19T10:30:00Z",
+  "updated_at": "2025-12-19T10:30:00Z"
+}
+```
+
+## Example
+
+```bash
+curl -X POST https://api.example.com/api/articles \
+  -H "Authorization: Bearer eyJhbGc..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "Getting Started with API",
+    "content": "This is my first article...",
+    "tags": ["api", "guide"]
+  }'
+```
+
+## Errors
+
+| Status | Code | Meaning |
+|--------|------|---------|
+| 400 | invalid_input | Title or content missing, or exceeds limits |
+| 401 | unauthorized | Token missing or invalid |
+| 403 | forbidden | User lacks permission to create articles |
+| 409 | duplicate | Title already exists (if title uniqueness enforced) |
+
+## Notes
+
+- Articles are created in draft status by default. Publish them separately.
+- Titles must be unique across your account.
+- Content supports Markdown formatting.
+- Maximum request size: 1MB
+```
+
+---
+
+## Example 4: Explanation
+
+**Source**: Understanding API rate limiting
+
+```markdown
+# About API rate limiting
+
+Rate limiting is the practice of restricting how many requests a client 
+can make to an API in a given time window.
+
+## Background
+
+Early APIs had no limits, which led to problems: a single misbehaving 
+client could overwhelm the server, hurting all users. As APIs became 
+critical infrastructure, rate limiting became essential—as important 
+as circuit breakers in electrical systems.
+
+Different services implement rate limiting differently. Some (like AWS) 
+tie it to your plan. Others (like Twitter) tie it to your authentication. 
+This reflects different business models and reliability needs.
+
+## The core concept
+
+Rate limiting works by associating requests with an identity (API key, 
+user, IP address) and counting them. When a request would exceed the 
+limit, it's rejected with a 429 status.
+
+From the user's perspective, rate limits represent a contract: "You can 
+make this many requests per minute. Plan accordingly."
+
+## Token bucket vs. sliding window
+
+Rate limiting algorithms fall into two main categories.
+
+**Token bucket** (used by most modern APIs) works like a bucket that 
+refills at a constant rate. Every request costs one token. When the bucket 
+is empty, requests are denied. This approach allows bursts: if you didn't 
+use your tokens, you can use more now.
+
+Example: Stripe allows 100 requests per second, but with token bucket 
+algorithm, you could make 500 requests in 5 seconds if you hadn't made 
+any requests before.
+
+**Sliding window** counts requests in a rolling time window. Strictly 
+enforces the limit over any N-second window. This prevents bursts, which 
+is useful for protecting against denial-of-service attacks.
+
+Google Cloud uses sliding window. You get a hard cap: no more than 1000 
+requests per minute, period.
+
+## Why your API cares about limits
+
+Protecting infrastructure is one reason, but not the only reason:
+
+- **Fairness**: Ensures one large customer doesn't monopolize resources
+- **Predictability**: Users can build reliable systems if they know the limit
+- **Cost management**: For usage-based pricing, limits enforce billing tiers
+- **Security**: Limits prevent brute-force attacks (credential stuffing, DDoS)
+
+## Comparison to authentication
+
+Rate limiting is often confused with authentication, but they're distinct:
+
+- **Authentication** answers: "Who are you?" (Validated by token)
+- **Rate limiting** answers: "How much can you do?" (Enforced by counter)
+
+You can be authenticated (pass token) but rate-limited (hit the ceiling). 
+This is actually a good design: it lets legitimate users be identified 
+while still protecting the service.
+
+## Different perspectives
+
+Some argue rate limits should be generous because they build trust: "If 
+you trust me, let me make 10,000 requests per minute." This is good for 
+developer experience during development.
+
+Others argue limits should be strict because one bad client can hurt 
+everyone: "Everyone gets 100 requests per minute, no exceptions." This 
+protects the service.
+
+Most production APIs do both: generous limits for authenticated users 
+(based on their plan) and very strict limits for unauthenticated requests.
+
+## Further reading
+
+- **Learn it**: [Tutorial: Handling rate limit responses](...)
+- **Use it**: [How to design rate limits for your API](...)
+- **Details**: [Rate limits reference documentation](...)
+```
+
+---
+
+## Using These Examples
+
+Each example above is **production-ready code** you can:
+- Copy and adapt for your own documentation
+- Use as a reference when writing similar documentation
+- Share with your team as a style guide
+- Test to ensure it actually works
+
+The examples follow the principles and language patterns from their respective template files.

data/.agents/skills/diataxis/references/explanation-template.md

@@ -0,0 +1,96 @@
+# Explanation Template
+
+**Purpose**: Deepen understanding by providing context, history, and perspective. User reads when reflecting.
+
+**Key Characteristics**:
+- Provides context, background, and history
+- Makes connections to other concepts
+- Discusses "why", not "how"
+- Admits perspectives and alternatives
+- Bounded to a single topic
+
+## Structure
+
+```markdown
+# About [Subject]
+
+[One sentence introducing what this is about]
+
+## Background
+
+[Historical context: why this matters, when it was introduced, or how it evolved]
+
+Example: "Caching has been essential to web performance since the early 
+days of the internet, when bandwidth was scarce. While bandwidth is 
+cheaper now, caching remains critical because latency directly affects 
+user experience."
+
+## The core concept
+
+[What is this fundamentally, without being instructional]
+
+## [Aspect 1: Design consideration]
+
+[Discuss why this was chosen, tradeoffs, alternatives]
+
+Example: "We chose Event-Sourcing because it provides a complete audit 
+trail. The tradeoff is that queries are more complex; traditional 
+databases offer simpler queries but lose the ability to see historical state."
+
+## [Aspect 2: Another consideration]
+
+[Same approach: discuss why, tradeoffs, alternatives]
+
+## Comparison to [related concept]
+
+[How this relates to similar ideas]
+
+Example: "Unlike traditional caching, which discards old data, Event 
+Sourcing preserves the entire history. This is similar to a version 
+control system like Git, where every change is recorded."
+
+## Different perspectives
+
+Some teams prefer [Approach A] because [reason]. This works well when 
+[condition], but can be problematic when [condition].
+
+Others prefer [Approach B] because [reason]. This is better suited for 
+[situation], though it requires [tradeoff].
+
+## Further reading
+
+- **Learn it**: [Link to Tutorial]
+- **Use it**: [Link to How-to Guide]
+- **Details**: [Link to Reference]
+```
+
+## Language Patterns
+
+Use these patterns consistently throughout your explanation:
+
+| Pattern | Example |
+|---------|---------|
+| **The reason for X is because historically, Y** | "The reason we use semver is because it emerged from the open-source community's need for predictable versioning." |
+| **W is better than Z, because** | "Immutability is better than shared state because it eliminates entire categories of race conditions." |
+| **X in system Y is analogous to W in system Z** | "A microservice in our architecture is analogous to a module in traditional monoliths—isolated, focused, and independently deployable." |
+| **Some prefer W because Z. This is good when** | "Some teams prefer GraphQL because it reduces over-fetching. This is beneficial when you have diverse client needs." |
+
+## Key Principles to Remember
+
+✓ **Make connections** — Relate to other concepts and contexts
+
+✓ **Provide context** — Design decisions, history, constraints, tradeoffs
+
+✓ **Talk about the subject** — Titles should work with "About…" prefix
+
+✓ **Admit perspective** — Acknowledge limitations and alternatives
+
+✓ **Weigh alternatives** — Show why one approach is chosen over others
+
+✓ **Bound the discussion** — Don't absorb instructions or reference
+
+✓ **Answer "why" questions** — Not "how" or "what"
+
+## Example
+
+See [examples.md](examples.md#example-4-explanation) for a complete working example: "About API rate limiting"