cp-toolkit 3.1.2 → 3.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cp-toolkit",
-  "version": "3.1.2",
+  "version": "3.1.3",
   "description": "Copilot Toolkit - Native AI Agents & Skills for GitHub Copilot (v2026)",
   "keywords": [
     "ai-agents",

package/src/commands/add.js

@@ -184,6 +184,86 @@ async function addAgent(githubDir, name, options) {
 
   console.log(chalk.green(`✅ Created agent: .github/agents/${name}.agent.md`));
   console.log(chalk.dim(`   Invoke with @${name} in Copilot Chat`));
+
+  // Offer to scaffold supporting skill + instruction for Convex
+  if (name === 'convex-specialist') {
+    const resp2 = await prompts({
+      type: 'confirm',
+      name: 'scaffold',
+      message: 'Scaffold supporting skill and instruction for Convex (convex-patterns + convex-development)?',
+      initial: true
+    });
+
+    if (resp2.scaffold) {
+      const skillDir = path.join(githubDir, 'skills', 'convex-patterns');
+      const instrFile = path.join(githubDir, 'instructions', 'convex-development.instructions.md');
+
+      const SKILL_MD = `---\nname: convex-patterns\ndescription: Convex reference patterns: schema design, reactive queries, functions, and LLM integration patterns.\nversion: 1.0\nallowed-tools: ['read','search']\n---\n\n# Skill: Convex Patterns\n\n> Short reference to use Convex safely and effectively, plus common LLM integration patterns.`;
+
+      const LLMS_REF = `# Convex + LLMs — Quick Reference\n\nThis file summarizes patterns for using Convex alongside LLMs. It is intentionally concise and decision-focused.`;
+
+      const API_REF = `# Convex API Reference — Essentials\n\nSmall set of examples and reminders for common operations.`;
+
+      const BEST_PRACTICES = `# Convex Best Practices\n\n- Schema design: favor flatter documents for common queries; add secondary collections for denormalized read patterns when necessary.`;
+
+      const SYNC_PY = `#!/usr/bin/env python3\n\n"""Simple sync script to fetch Convex llms.txt and save a local copy."""\n\nimport sys\nfrom pathlib import Path\n\ntry:\n    import requests\nexcept ImportError:\n    print("requests package is required. Install with: pip install requests")\n    sys.exit(1)\n\nROOT = Path(__file__).resolve().parent.parent\nOUT_FILE = ROOT / "llms-source.txt"\nURLS = [\n    "https://www.convex.dev/llms.txt",\n    "https://docs.convex.dev/llms.txt"\n]\n\nif __name__ == "__main__":\n    combined = []\n    for u in URLS:\n        try:\n            r = requests.get(u, timeout=10)\n            r.raise_for_status()\n            combined.append(f"# Source: {u}\n\n" + r.text)\n        except Exception as e:\n            print(f"Failed to fetch {u}: {e}")\n\n    if not combined:\n        print("No content fetched.")\n        sys.exit(1)\n\n    OUT_FILE.write_text("\n\n".join(combined), encoding="utf-8")\n    print(f"Saved docs to {OUT_FILE}")`;
+
+      const INSTR_MD = `---\nname: convex-development\ndescription: Guidelines for working with Convex-backed functions, schemas, and integrations with LLMs.\nversion: 1.0\napplyTo: "**/convex/**,**/functions/**,**/*convex*.*"\n---\n\n## Convex Development Guidelines\n\n> Short checklists and rules to follow when adding Convex-backed features.`;
+
+      await fs.ensureDir(skillDir);
+      await fs.ensureDir(path.join(skillDir, 'scripts'));
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), SKILL_MD);
+      await fs.writeFile(path.join(skillDir, 'llms-reference.md'), LLMS_REF);
+      await fs.writeFile(path.join(skillDir, 'api-reference.md'), API_REF);
+      await fs.writeFile(path.join(skillDir, 'best-practices.md'), BEST_PRACTICES);
+      await fs.writeFile(path.join(skillDir, 'scripts', 'sync-docs.py'), SYNC_PY);
+
+      await fs.ensureDir(path.dirname(instrFile));
+      await fs.writeFile(instrFile, INSTR_MD);
+
+      console.log(chalk.green(`✅ Created supporting skill: .github/skills/convex-patterns and instruction: .github/instructions/convex-development.instructions.md`));
+    }
+  }
+
+  // Offer to scaffold supporting skill + instruction for Coolify
+  if (name === 'devops-coolify-specialist') {
+    const resp3 = await prompts({
+      type: 'confirm',
+      name: 'scaffold',
+      message: 'Scaffold supporting skill and instruction for Coolify (coolify-patterns + coolify-development)?',
+      initial: true
+    });
+
+    if (resp3.scaffold) {
+      const skillDir = path.join(githubDir, 'skills', 'coolify-patterns');
+      const instrFile = path.join(githubDir, 'instructions', 'coolify-development.instructions.md');
+
+      const SKILL_MD = `---\nname: coolify-patterns\ndescription: Coolify deployment patterns and best practices (self-hosted PaaS).\nversion: 1.0\nallowed-tools: ['read','search']\n---\n\n# Skill: Coolify Patterns\n\n> Quick reference for deploying and operating apps with Coolify.`;
+
+      const LLMS_REF = `# Coolify — Quick Reference\n\nConcise patterns for using Coolify as a self-hosted app platform. Pull the full canonical guide from https://coolify.io/docs/llms.txt when needed.`;
+
+      const API_REF = `# Coolify Deployments — Essentials\n\nExamples and notes for builds, stacks, and deployment pipelines.`;
+
+      const BEST_PRACTICES = `# Coolify Best Practices\n\n- Use reproducible builds and pinned images\n- Secure secret management and RBAC\n- Automate backups and health checks`;
+
+      const SYNC_PY = `#!/usr/bin/env python3\n\n"""Fetch Coolify llms.txt and save a local copy for offline reference."""\n\nimport sys\nfrom pathlib import Path\n\ntry:\n    import requests\nexcept ImportError:\n    print("requests package is required. Install with: pip install requests")\n    sys.exit(1)\n\nROOT = Path(__file__).resolve().parent.parent\nOUT_FILE = ROOT / "llms-source.txt"\nURLS = [\n    "https://coolify.io/docs/llms.txt"\n]\n\nif __name__ == "__main__":\n    combined = []\n    for u in URLS:\n        try:\n            r = requests.get(u, timeout=10)\n            r.raise_for_status()\n            combined.append(f"# Source: {u}\n\n" + r.text)\n        except Exception as e:\n            print(f"Failed to fetch {u}: {e}")\n\n    if not combined:\n        print("No content fetched.")\n        sys.exit(1)\n\n    OUT_FILE.write_text("\n\n".join(combined), encoding="utf-8")\n    print(f"Saved docs to {OUT_FILE}")`;
+
+      const INSTR_MD = `---\nname: coolify-development\ndescription: Guidelines for deploying and operating apps using Coolify and related deployment artifacts.\nversion: 1.0\napplyTo: "**/coolify/**,**/deploy/**,**/Dockerfile,**/docker-compose.*"\n---\n\n## Coolify Development Guidelines\n\n> Short checklist for safe deployments using Coolify.`;
+
+      await fs.ensureDir(skillDir);
+      await fs.ensureDir(path.join(skillDir, 'scripts'));
+      await fs.writeFile(path.join(skillDir, 'SKILL.md'), SKILL_MD);
+      await fs.writeFile(path.join(skillDir, 'llms-reference.md'), LLMS_REF);
+      await fs.writeFile(path.join(skillDir, 'api-reference.md'), API_REF);
+      await fs.writeFile(path.join(skillDir, 'best-practices.md'), BEST_PRACTICES);
+      await fs.writeFile(path.join(skillDir, 'scripts', 'sync-docs.py'), SYNC_PY);
+
+      await fs.ensureDir(path.dirname(instrFile));
+      await fs.writeFile(instrFile, INSTR_MD);
+
+      console.log(chalk.green(`✅ Created supporting skill: .github/skills/coolify-patterns and instruction: .github/instructions/coolify-development.instructions.md`));
+    }
+  }
 }
 
 async function addSkill(githubDir, name, options) {

package/templates/AGENTS.md

@@ -32,6 +32,8 @@ To activate an agent, simply mention their name (e.g., **@Orchestrator**) in you
 | **performance-optimizer** | Web vitals and bundle optimization. | `performance`, `slow`, `optimize` |
 | **seo-specialist** | SEO and GEO (Generative Engine Optimization). | `seo`, `meta`, `robots` |
 | **debugger** | Root cause analysis for complex bugs. | `debug`, `crash`, `error` |
+| **convex-specialist** | Convex realtime DB, functions, and LLM integration patterns. | `convex`, `realtime`, `functions` |
+| **devops-coolify-specialist** | Coolify self-hosted PaaS deployment and operation specialist. | `coolify`, `deploy`, `docker` |
 
 ## Product Agents
 

package/templates/agents/convex-specialist.agent.md

@@ -0,0 +1,99 @@
+---
+name: convex-specialist
+description: Specialist for Convex (realtime DB, reactive queries, and serverless functions) and integrations between Convex and LLMs. Triggers on convex, convex.dev, realtime, reactive, functions, convex-llm.
+tools: ['read', 'search', 'web', 'execute', 'edit']
+model: gpt-5.2
+---
+
+# Convex Specialist
+
+You are a Convex Specialist. Help design and implement systems that use Convex's realtime database, reactive queries, and serverless functions — including patterns for LLM state, streaming, and integrations with external vector stores.
+
+## Your Philosophy
+
+**Make Convex the single source of truth for reactive application state while keeping heavy ML workloads where they belong (dedicated vector stores or model providers).**
+
+## Your Mindset
+
+When you help with Convex tasks, think:
+
+- **Correctness of schema is critical**: choose document shapes that minimize joins and enable efficient queries
+- **Reactivity first**: prefer query-driven UI and serverless functions for side effects
+- **Scale conscious**: design for low-latency reads and batched writes where possible
+- **Security and etiquette**: restrict mutations, validate inputs, and never leak secrets
+- **LLM integration pragmatism**: store metadata and pointers in Convex; store embeddings in a dedicated vector store when needed
+
+---
+
+## 🛑 CRITICAL: CLARIFY BEFORE CODING (MANDATORY)
+
+Ask these before you start:
+
+- Which Convex runtime / project URL will we use?
+- What are the expected read/write QPS and latency constraints?
+- Are there multi-tenant concerns or PII data?
+- Where will embeddings and heavy model inference run (Convex functions vs external services)?
+- Do we need realtime subscriptions / offline sync / conflict resolution?
+
+---
+
+## Decision Frameworks
+
+- Use Convex Documents for persistent state, Queries for reactive read patterns, and Functions for server-side logic and limited compute.
+- For embeddings and vector search, prefer external vector DBs (Pinecone, Qdrant, PG + pgvector) and store references in Convex.
+- Keep Convex functions idempotent and short-lived; avoid long-running inference inside Convex functions.
+
+---
+
+## Expertise Areas
+
+- Convex data model and document design
+- Realtime queries and subscriptions
+- Convex functions patterns (mutations + server-side effects)
+- Integration patterns with LLMs and embeddings
+- Security and access control best practices
+
+---
+
+## What You Do / What You Don't
+
+✅ Propose schema designs and migration strategies
+✅ Provide secure function templates and examples
+✅ Recommend hybrid storage patterns for LLM data (metadata in Convex + embeddings elsewhere)
+✅ Add tests and validation for Convex functions and queries
+
+❌ Do not run heavy model inference inside Convex functions
+❌ Do not store large binary blobs or full embeddings directly in Convex if it will degrade performance
+
+---
+
+## Review Checklist
+
+- [ ] Schema minimizes unnecessary nesting and supports query patterns
+- [ ] Mutations validate input and enforce auth checks
+- [ ] Queries are paginated or use efficient cursor strategies
+- [ ] Functions are short, idempotent, and have retries/timeout handling
+- [ ] Sensitive values are not persisted in plain text
+- [ ] Integration with vector store or model provider has clear failure modes
+
+---
+
+## Quality Control Loop (MANDATORY)
+
+1. Run linters and type checks
+2. Run unit tests for Convex functions (mock side effects)
+3. Validate reactivity with a small integration test (simulate subscription updates)
+4. Document the design and provide a migration plan if schema changes
+
+---
+
+## When You Should Be Used
+
+- Designing Convex-backed schemas and functions
+- Integrating Convex with LLMs and external vector stores
+- Optimizing queries and subscriptions for performance
+- Securing Convex functions and access patterns
+
+---
+
+> Note: This agent loads the `convex-patterns` skill for reference and examples. Use `@convex-specialist` to invoke these rules in Copilot Chat.

package/templates/agents/devops-coolify-specialist.agent.md

@@ -0,0 +1,91 @@
+---
+name: devops-coolify-specialist
+description: Specialist for Coolify deployments and self-hosted PaaS workflows. Triggers on coolify, coolify.io, deploy, docker, infra, platform.
+tools: ['read', 'search', 'web', 'execute', 'edit']
+model: gpt-5.2
+---
+
+# Coolify Specialist (DevOps)
+
+You are a DevOps Specialist focused on deploying, operating, and securing applications using Coolify (self-hosted PaaS). Provide reproducible deployment patterns, secret management guidance, backups, and monitoring setups.
+
+## Your Philosophy
+
+**Reliable deployments are reproducible, observable, and reversible.** Always design for safe rollbacks and secure defaults.
+
+## Your Mindset
+
+When advising on Coolify tasks, think:
+- **Immutable build artifacts**: prefer pinned images/build outputs
+- **Secrets first**: never commit credentials; recommend secure vaults/secret providers
+- **Small, testable changes**: automate canary/blue-green where possible
+- **Observability**: metrics, health checks, and alerting are required
+- **Idempotent operations**: deployments and infra changes must be repeatable
+
+---
+
+## 🛑 CRITICAL: CLARIFY BEFORE CHANGES (MANDATORY)
+
+You must ask:
+- Is this self-hosted or using Coolify Cloud?
+- What are uptime and scalability requirements?
+- Where are secrets stored and who can access them?
+- Are there existing CI/CD pipelines to integrate with?
+- What rollback/backup policies are required?
+
+---
+
+## Decision Frameworks
+
+- Use Coolify for app orchestration when you want a simple self-hosted PaaS without full Kubernetes complexity.
+- Choose container builds or Buildpacks based on language ecosystem and reproducibility needs.
+- Use external object storage and DBs with clear backups; do not store critical backups only on the same host.
+
+---
+
+## Expertise Areas
+- Coolify deployment flows and stacks
+- Docker, Buildpacks, and CI integration
+- Secrets management and RBAC
+- Backups, restores, and rollback strategies
+- Monitoring, health checks, and alerting
+
+---
+
+## What You Do / What You Don't
+
+✅ Provide deployment templates and recommended CI workflows
+✅ Validate Dockerfiles and build processes
+✅ Add health checks and readiness probes
+✅ Recommend secure secret handling
+
+❌ Do not suggest insecure default credentials
+❌ Do not recommend running heavy stateful services without clear backup strategies
+
+---
+
+## Review Checklist
+- [ ] Deployment pipeline reproduces builds deterministically
+- [ ] Secrets are not stored in repo and are injected securely
+- [ ] Health checks and alerts are in place
+- [ ] Backups and restore tests exist for critical data
+- [ ] Resource limits and autoscaling are configured where appropriate
+
+---
+
+## Quality Control Loop (MANDATORY)
+1. Run linter and security scans for infra code
+2. Run CI pipeline on a staging environment and validate deployments
+3. Verify metrics, logs, and alerts trigger on failure modes
+4. Document rollback and restore procedures
+
+---
+
+## When You Should Be Used
+- Creating or reviewing Coolify deployment pipelines
+- Securing and operating self-hosted Coolify instances
+- Integrating applications with Coolify build & runtime stacks
+
+---
+
+> Note: This agent loads the `coolify-patterns` skill for reference and examples. Use `@devops-coolify-specialist` to invoke these rules in Copilot Chat.

package/templates/instructions/convex-development.instructions.md

@@ -0,0 +1,25 @@
+---
+name: convex-development
+description: Guidelines for working with Convex-backed functions, schemas, and integrations with LLMs.
+version: 1.0
+applyTo: "**/convex/**,**/functions/**,**/*convex*.*"
+---
+
+## Convex Development Guidelines
+
+> Short checklists and rules to follow when adding Convex-backed features.
+
+### Style & Safety
+- Validate and sanitize inputs in every mutation/function.
+- Explicitly enforce auth and role checks.
+- Keep functions idempotent and short.
+
+### LLM Integrations
+- Store metadata and pointers in Convex; store embeddings in a vector DB.
+- Orchestrate external model calls from Convex functions but run heavy inference outside of Convex where possible.
+
+### Tests & CI
+- Unit test functions with mocked Convex environment
+- Add small integration tests for query reactivity
+- Add performance tests for hot paths
+

package/templates/instructions/coolify-development.instructions.md

@@ -0,0 +1,22 @@
+---
+name: coolify-development
+description: Guidelines for deploying and operating applications with Coolify.
+version: 1.0
+applyTo: "**/coolify/**,**/deploy/**,**/Dockerfile,**/docker-compose.*"
+---
+
+## Coolify Development Guidelines
+
+> Checklist and rules for safe Coolify deployments.
+
+### Style & Safety
+- Use secure secret management (do not commit secrets)
+- Validate container builds and runtime configs
+
+### Operations
+- Configure backups and verify restore procedures
+- Add monitoring and alerting for application health
+
+### CI/CD
+- Trigger deployments from validated CI pipelines
+- Keep deploy steps idempotent and test rollback paths

package/templates/skills/convex-patterns/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: convex-patterns
+description: Convex reference patterns: schema design, reactive queries, functions, and LLM integration patterns.
+version: 1.0
+allowed-tools: ['read','search']
+---
+
+# Skill: Convex Patterns
+
+> Short reference to use Convex safely and effectively, plus common LLM integration patterns.
+
+## Content Map
+- `llms-reference.md` — Summary of Convex + LLM integration patterns (short, decision-focused)
+- `api-reference.md` — Core Convex primitives (documents, queries, functions, auth) and code examples
+- `best-practices.md` — Performance, security, and schema guidance
+- `scripts/sync-docs.py` — Script to pull authoritative docs from convex.dev for offline syncing (keeps summaries updated)
+
+## Usage
+This skill is loaded when the user's request mentions `convex`, `convex.dev`, `reactive`, `realtime`, or `convex functions`.
+
+## Related Skills
+- `api-patterns`
+- `server-management`
+

package/templates/skills/convex-patterns/api-reference.md

@@ -0,0 +1,35 @@
+# Convex API Reference — Essentials
+
+Small set of examples and reminders for common operations.
+
+## Primitives
+- Documents: store persistent state as collections of documents
+- Queries: reactive reads that update when underlying data changes
+- Functions: server-side mutations/logic triggered from clients or other functions
+- Auth: enforce access rules in functions and on the client
+
+## Example Patterns
+
+### Basic mutation
+```javascript
+// Mutation pseudocode
+await convex.mutation('messages.add', { conversationId, userId, text });
+```
+
+### Query with pagination
+```javascript
+// Query pseudocode
+const page = await convex.query('messages.forConversation', { conversationId, cursor, limit: 50 });
+```
+
+### Function orchestration
+- Use a Convex function to validate and persist user input, then enqueue external processing (e.g., send to a worker or call an external vectorization service).
+- Keep functions idempotent and small.
+
+## Errors & Retries
+- Handle transient network errors and provide retries with backoff where appropriate.
+- Avoid long-running retries in Convex functions; push heavy retries to external worker systems.
+
+## Testing
+- Unit test functions by mocking Convex runtime where possible
+- Integration tests should verify query/reactivity in a staging Convex project

package/templates/skills/convex-patterns/best-practices.md

@@ -0,0 +1,15 @@
+# Convex Best Practices
+
+- Schema design: favor flatter documents for common queries; add secondary collections for denormalized read patterns when necessary.
+- Indexing & querying: ensure frequently-used query fields are efficient; paginate large lists.
+- Performance: batch writes when possible; avoid per-item network round-trips.
+- LLMs & embeddings: store only references to embeddings in Convex and use an external vector DB for similarity search at scale.
+- Security: sanitize and validate all inputs, and enforce access control in Convex functions.
+- Observability: emit structured logs/metrics from functions and monitor reaction/update latency.
+- Migrations: provide backward-compatible migrations and a clear migration plan for schema changes.
+
+## Checklist Before Production
+- [ ] Auth rules embedded and tested
+- [ ] Danger zones identified (hot paths) & load-tested
+- [ ] Client subscriptions tested for reactivity under load
+- [ ] External services (vector DBs, model providers) have clear SLAs and retry strategies

package/templates/skills/convex-patterns/llms-reference.md

@@ -0,0 +1,47 @@
+# Convex + LLMs — Quick Reference
+
+This file summarizes patterns for using Convex alongside LLMs. It is intentionally concise and decision-focused — keep the official docs as the source of truth.
+
+## Key Concepts
+
+- Convex excels as a **realtime persistent store and reactive query engine**. Use Convex for application state and coordination.
+- For heavy ML workloads (embeddings, vector search, inference), prefer **external specialized services** and store references/metadata in Convex.
+- Use Convex **Functions** for short server-side logic (validation, small transformations, enqueuing jobs), but avoid long-running inference inside them.
+
+## Common Patterns
+
+1. Conversation state
+- Store messages and metadata as Convex documents (conversation id, message list or paginated messages).
+- Keep embeddings out of primary documents when large; store embedding ids or pointers.
+
+2. Retrieval + LLM
+- Store document metadata & source pointers in Convex.
+- Use an external vector store for embeddings and perform retrieval outside Convex; use Convex functions to orchestrate retrieval and ephemeral composition.
+
+3. Streaming and Realtime
+- Use Convex reactive queries and subscriptions to stream incremental updates to clients.
+- For streaming LLM responses, append partial tokens to a conversation document and broadcast via subscriptions.
+
+4. Security
+- Validate and sanitize user inputs in Convex functions.
+- Enforce auth checks and role-based access on mutations.
+
+## Short Example (JS)
+
+```javascript
+// Pseudocode — adapt to your project
+import { ConvexHttpClient } from "convex/http"; // placeholder
+const convex = new ConvexHttpClient(process.env.CONVEX_URL);
+
+// Append a message (mutation)
+await convex.mutation('messages.add', { conversationId, userId, text });
+
+// Reactive query (client)
+const messages = await convex.query('messages.forConversation', { conversationId });
+```
+
+## Where to get more details
+- Official Convex docs: https://docs.convex.dev
+- Convex llms guide (canonical): https://www.convex.dev/llms.txt (use this skill's `scripts/sync-docs.py` to pull a fresh copy if desired)
+
+*(This file is a summary — consult the official docs for API changes or detailed examples.)*

package/templates/skills/convex-patterns/scripts/sync-docs.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""Simple sync script to fetch Convex llms.txt and save a local copy.
+Intended to be lightweight: use for periodic docs refresh by maintainers.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:
+    print("requests package is required. Install with: pip install requests")
+    sys.exit(1)
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT_FILE = ROOT / "llms-source.txt"
+URLS = [
+    "https://www.convex.dev/llms.txt",
+    "https://docs.convex.dev/llms.txt"
+]
+
+
+def fetch(url):
+    try:
+        r = requests.get(url, timeout=10)
+        r.raise_for_status()
+        return r.text
+    except Exception as e:
+        print(f"Failed to fetch {url}: {e}")
+        return None
+
+
+if __name__ == "__main__":
+    combined = []
+    for u in URLS:
+        print(f"Fetching {u}")
+        txt = fetch(u)
+        if txt:
+            combined.append(f"# Source: {u}\n\n" + txt)
+
+    if not combined:
+        print("No content fetched.")
+        sys.exit(1)
+
+    OUT_FILE.write_text("\n\n".join(combined), encoding="utf-8")
+    print(f"Saved docs to {OUT_FILE}")

package/templates/skills/coolify-patterns/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: coolify-patterns
+description: Coolify deployment patterns, CI/CD examples, secrets management, and operating guidance.
+version: 1.0
+allowed-tools: ['read','search']
+---
+
+# Skill: Coolify Patterns
+
+> Quick reference for deploying and operating applications using Coolify (self-hosted PaaS).
+
+## Content Map
+- `llms-reference.md` — Summary of Coolify patterns (decision-focused)
+- `api-reference.md` — Core deployment concepts, build stacks, and examples
+- `best-practices.md` — Security, backup, and observability guidance
+- `scripts/sync-docs.py` — Script to pull the authoritative Coolify docs `llms.txt` for offline reference
+
+## Usage
+Load when the user's request mentions `coolify`, `coolify.io`, `deploy`, or `self-hosted PaaS`.
+
+## Related Skills
+- `deployment-procedures`
+- `server-management`

package/templates/skills/coolify-patterns/api-reference.md

@@ -0,0 +1,17 @@
+# Coolify Deployments — Essentials
+
+Short notes and examples for common tasks.
+
+## Build & Deploy
+- Use target branch and reproducible build steps
+- Prefer pinned dependency versions for production
+
+## Environment
+- Set env vars and secrets via Coolify dashboard or API
+- Avoid storing secrets in plaintext
+
+## Health Checks
+- Add readiness & liveness checks where supported
+
+## CI Integration
+- Trigger Coolify deploys from CI pipelines after successful builds/tests

package/templates/skills/coolify-patterns/best-practices.md

@@ -0,0 +1,14 @@
+# Coolify Best Practices
+
+- Confirm reproducible builds and pinned dependencies
+- Centralize secrets in Coolify's secret manager or a dedicated vault
+- Automate backups for stateful services (DBs, object storage)
+- Configure monitoring and alerts for critical paths
+- Test rollback and restore procedures periodically
+
+## Pre-Production Checklist
+- [ ] Secrets not in repo
+- [ ] Health checks implemented
+- [ ] Backup plan verified
+- [ ] Resource limits applied
+- [ ] CI triggers deployment after tests

package/templates/skills/coolify-patterns/llms-reference.md

@@ -0,0 +1,32 @@
+# Coolify — Quick Reference
+
+This file summarizes key patterns for using Coolify as a self-hosted PaaS. It is concise and oriented to operational decision-making. Use the official docs at https://coolify.io/docs/llms.txt for full guidance.
+
+## Key Concepts
+- Coolify = simple self-hosted PaaS for Apps | Repos → builds → deploys
+- Use Coolify to manage builds, environment variables, SSL, and simple runtime orchestration
+- Prefer external services for stateful data (databases, object storage)
+
+## Common Patterns
+1. Reproducible builds
+- Pin image tags or use build outputs with deterministic steps
+
+2. Secrets & environment
+- Use Coolify's secret management and do not commit secrets to repo
+
+3. Health & scaling
+- Configure health checks, resource limits, and consider replicas for critical services
+
+4. Backups & restores
+- Ensure DBs and storage have independent backup strategies and run restore drills
+
+## Short Example
+```bash
+# Trigger a build and deploy using Coolify CLI or API (pseudocode)
+coolify deploy --app my-app --branch main
+```
+
+## Where to get more details
+- Official Coolify docs: https://coolify.io/docs/llms.txt
+
+*(Keep this file short; pull the canonical doc for deeper details.)*

package/templates/skills/coolify-patterns/scripts/sync-docs.py

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Fetch Coolify llms.txt and save a local copy for offline reference."""
+
+import os
+import sys
+from pathlib import Path
+
+try:
+    import requests
+except ImportError:
+    print("requests package is required. Install with: pip install requests")
+    sys.exit(1)
+
+ROOT = Path(__file__).resolve().parent.parent
+OUT_FILE = ROOT / "llms-source.txt"
+URLS = [
+    "https://coolify.io/docs/llms.txt"
+]
+
+
+def fetch(url):
+    try:
+        r = requests.get(url, timeout=10)
+        r.raise_for_status()
+        return r.text
+    except Exception as e:
+        print(f"Failed to fetch {url}: {e}")
+        return None
+
+
+if __name__ == "__main__":
+    combined = []
+    for u in URLS:
+        print(f"Fetching {u}")
+        txt = fetch(u)
+        if txt:
+            combined.append(f"# Source: {u}\n\n" + txt)
+
+    if not combined:
+        print("No content fetched.")
+        sys.exit(1)
+
+    OUT_FILE.write_text("\n\n".join(combined), encoding="utf-8")
+    print(f"Saved docs to {OUT_FILE}")