@cleocode/cleo 2026.2.5 → 2026.2.7

package/packages/ct-skills/skills/railway-platform/references/14-railway-metal.md

@@ -0,0 +1,197 @@
+# Railway Metal
+
+Railway's own cloud infrastructure for improved performance and pricing.
+
+## What is Railway Metal?
+
+Railway Metal is Railway's custom infrastructure:
+- **Owned hardware** in datacenters worldwide
+- **NVMe SSD storage** for fast I/O
+- **Better CPUs** with higher performance per core
+- **Improved networking** with anycast edge
+
+## Benefits
+
+| Feature | Improvement |
+|---------|-------------|
+| **Pricing** | Up to 50% less egress, 40% less storage |
+| **Performance** | Faster CPUs, better disk I/O |
+| **Regions** | Available to all plans |
+| **Reliability** | End-to-end hardware control |
+| **Features** | Enables Static IPs, Anycast, HA volumes |
+
+## Migration Timeline
+
+| Date | Milestone |
+|------|-----------|
+| Dec 2024 | Trial/Hobby services on Railway Metal |
+| Jan 2025 | Gradual volume-less migration |
+| Feb 2025 | Pro services on Railway Metal |
+| Mar 2025 | Stateful (volume) services begin |
+| Jul 2025 | Migration complete |
+
+## Checking Your Status
+
+### Is Service on Railway Metal?
+
+```bash
+railway status --json | jq '.service'
+```
+
+Or check Dashboard:
+- Service Settings → Deploy → Regions
+- Look for "Metal (New)" tag
+
+### Regional Availability
+
+| Region | Status |
+|--------|--------|
+| US West (California) | ✅ Active |
+| US East (Virginia) | ✅ Active |
+| Europe West (Amsterdam) | ✅ Active |
+| Southeast Asia (Singapore) | ✅ Active |
+
+## Migration Behavior
+
+### Automatic Migration
+
+Services without volumes are automatically migrated:
+- Brief downtime during migration
+- Ephemeral storage wiped (expected)
+- Rollback available if issues
+
+### With Volumes
+
+Stateful migrations (volumes) began March 2025:
+- Volumes migrated to NVMe SSD
+- Region must match between service and volume
+- No cross-region volume mounts
+
+## Opting In Early
+
+### Manual Migration
+
+```bash
+# Go to Service Settings → Deploy → Regions
+# Select region with "Metal (New)" tag
+```
+
+### Railway CLI
+
+Via environment configuration:
+
+```bash
+source _shared/scripts/railway-api.sh
+
+ENV_ID=$(get_environment_id)
+SERVICE_ID=$(get_service_id)
+
+# Update to Railway Metal region
+railway_api '
+  mutation stageChanges($environmentId: String!, $input: EnvironmentConfig!) {
+    environmentStageChanges(environmentId: $environmentId, input: $input, merge: true) {
+      id
+    }
+  }
+' "{\"environmentId\": \"$ENV_ID\", \"input\": {\"services\": {\"$SERVICE_ID\": {\"deploy\": {\"multiRegionConfig\": {\"us-west1\": {\"numReplicas\": 1}}}}}}}"
+```
+
+## Rollback
+
+### Automatic Rollback
+
+If issues after migration:
+1. Dashboard shows rollback banner
+2. Click "Rollback" to revert
+
+### Manual Rollback
+
+```bash
+# Service Settings → Deploy → Regions
+# Select region without "Metal" tag
+```
+
+## Considerations
+
+### Cross-Region Latency
+
+If database in US West (Oregon) and app in US West (California):
+- Increased latency due to physical distance
+- Keep related services in same region
+- Migrate together when possible
+
+### Metrics Changes
+
+Railway Metal has different metrics sampling:
+- CPU may appear higher (more accurate sampling)
+- RAM may appear lower
+- Not actual usage changes, just better measurement
+
+### Pricing
+
+Automatic discounts applied when 80%+ workloads on Railway Metal:
+- Egress: $0.10/GB → $0.05/GB
+- Disk: $0.25/GB → $0.15/GB
+
+## Troubleshooting
+
+### Increased Latency
+
+**Cause:** Service and database in different regions.
+
+**Fix:**
+```bash
+# Check region of each service
+railway status --json | jq '.service.region'
+
+# Move to same region
+# See migration steps above
+```
+
+### Service Issues After Migration
+
+**Immediate fix:**
+```bash
+# Rollback via dashboard
+# Or redeploy
+railway redeploy -y
+```
+
+**Debug:**
+```bash
+# Check logs
+railway logs --lines 100
+
+# SSH for investigation
+railway ssh
+```
+
+## Future Features
+
+Railway Metal enables:
+- **Static Inbound IPs** - Fixed IP addresses
+- **Anycast Edge Network** - Global edge routing
+- **High-Availability Volumes** - Multi-zone replication
+- **Enhanced Networking** - Direct provider connections
+
+## FAQ
+
+**Q: Is Railway Metal stable?**
+A: Yes, ~40,000 deployments running on it.
+
+**Q: Will my service change?**
+A: No code changes needed. Just infrastructure.
+
+**Q: Can I stay on GCP?**
+A: No, all services migrate to Railway Metal.
+
+**Q: Do I need to do anything?**
+A: No for most users. Migration is automatic.
+
+**Q: Will costs change?**
+A: Should decrease due to better pricing.
+
+## Next Steps
+
+- [09-networking.md](09-networking.md) - Networking features
+- [13-troubleshooting.md](13-troubleshooting.md) - Migration issues

package/packages/ct-skills/skills.json

@@ -0,0 +1,5 @@
+{
+  "version": "2.0.0",
+  "generated": "2026-02-19T18:35:42Z",
+  "skills": [{"name":"ct-cleo","description":"CLEO task management protocol - core guidance for session, task, and workflow operations. Provides MCP-first workflow, CLI fallback, session protocol, task discovery patterns, RCSD lifecycle overview, and error handling. Load this skill for detailed CLEO protocol guidance.","version":"2.0.0","path":"skills/ct-cleo/SKILL.md","references":["skills/ct-cleo/references/session-protocol.md","skills/ct-cleo/references/rcsd-lifecycle.md","skills/ct-cleo/references/orchestrator-constraints.md","skills/ct-cleo/references/anti-patterns.md"],"core":true,"category":"core","tier":0,"protocol":null,"dependencies":[],"sharedResources":["task-system-integration"],"compatibility":["claude-code","gemini-cli","codex-cli"],"license":"MIT","metadata":{}},{"name":"ct-contribution","description":"Guided workflow for multi-agent consensus contributions. Use when user says \"/contribution\", \"contribution protocol\", \"submit contribution\", \"consensus workflow\", \"multi-agent decision\", \"create contribution\", \"contribution start\", \"contribution submit\", \"detect conflicts\", \"weighted consensus\", \"decision tracking\", \"conflict resolution\".","version":"1.0.0","path":"skills/ct-contribution/SKILL.md","references":[],"core":false,"category":"meta","tier":3,"protocol":"contribution","dependencies":[],"sharedResources":["subagent-protocol-base"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-dev-workflow","description":"Development workflow orchestration for task-driven development with atomic commits, conventional commit messages, and systematic release processes. Enforces task traceability, branch discipline, smart test scope selection, and GitHub Actions integration. Use when committing code, creating releases, managing branches, or following contribution protocols. Triggers on commit operations, release preparation, or workflow compliance needs.","version":"3.0.0","path":"skills/ct-dev-workflow/SKILL.md","references":[],"core":false,"category":"specialist","tier":2,"protocol":"contribution","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-docs-lookup","description":"This skill should be used when the user asks \"how do I configure [library]\", \"write code using [framework]\", \"what are the [library] methods\", \"show me [framework] examples\", or mentions libraries like React, Vue, Next.js, Prisma, Supabase, Express, Tailwind, Drizzle, Svelte. Triggers for library setup, configuration, API references, framework code examples, or version-specific docs (\"React 19\", \"Next.js 15\").","version":"1.0.0","path":"skills/ct-docs-lookup/SKILL.md","references":[],"core":false,"category":"composition","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-docs-review","description":"This skill should be used when the user asks to \"review documentation\", \"check docs style\", \"review this markdown file\", \"check style guide compliance\", \"review PR documentation\", or needs documentation reviewed against the CLEO writing style guide. Supports both local file review and GitHub PR review modes with inline comments.","version":"1.0.0","path":"skills/ct-docs-review/SKILL.md","references":[],"core":false,"category":"composition","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-docs-write","description":"This skill should be used when creating, editing, or reviewing documentation files (markdown, MDX, README, guides). Use when the user asks to \"write docs\", \"create documentation\", \"edit the README\", \"improve doc clarity\", \"make docs more readable\", \"follow the style guide\", or \"write user-facing content\". Applies CLEO's conversational, clear, and user-focused writing style.","version":"1.0.0","path":"skills/ct-docs-write/SKILL.md","references":[],"core":false,"category":"composition","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-documentor","description":"Documentation creation, editing, and review with CLEO style guide compliance. Coordinates specialized skills for lookup, writing, and review. Use when creating or updating documentation files, consolidating scattered documentation, or validating documentation against style standards. Triggers on documentation tasks, doc update requests, or style guide compliance checks.","version":"3.0.0","path":"skills/ct-documentor/SKILL.md","references":[],"core":false,"category":"specialist","tier":3,"protocol":null,"dependencies":["ct-docs-lookup","ct-docs-write","ct-docs-review"],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-epic-architect","description":"Epic planning and task decomposition for breaking down large initiatives into atomic, executable tasks. Provides dependency analysis, wave-based parallel execution planning, hierarchy management, and research linking. Use when creating epics, decomposing initiatives into task trees, planning parallel workflows, or analyzing task dependencies. Triggers on epic creation, task decomposition requests, or planning phase work.","version":"3.0.0","path":"skills/ct-epic-architect/SKILL.md","references":["skills/ct-epic-architect/references/bug-epic-example.md","skills/ct-epic-architect/references/commands.md","skills/ct-epic-architect/references/feature-epic-example.md","skills/ct-epic-architect/references/migration-epic-example.md","skills/ct-epic-architect/references/output-format.md","skills/ct-epic-architect/references/patterns.md","skills/ct-epic-architect/references/refactor-epic-example.md","skills/ct-epic-architect/references/research-epic-example.md","skills/ct-epic-architect/references/shell-escaping.md","skills/ct-epic-architect/references/skill-aware-execution.md"],"core":false,"category":"recommended","tier":1,"protocol":"decomposition","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-gitbook","description":"Comprehensive guide for the modern GitBook platform including Docs Sites publishing, @gitbook/api TypeScript SDK, Git Sync with GitHub App, Change Requests, Site Sections, adaptive content, visitor authentication (Auth0/Okta/Azure AD), LLM-ready docs (llms.txt, MCP server), OpenAPI integration, content blocks, custom domains, SSO/SAML, SEO optimization, and migration from MkDocs/Docusaurus. Use when creating, managing, or automating GitBook documentation sites, configuring Git Sync, working with the GitBook API, setting up authentication, or migrating documentation to GitBook.","version":"1.0.0","path":"skills/ct-gitbook/SKILL.md","references":["skills/ct-gitbook/references/api-sdk.md","skills/ct-gitbook/references/auth-sso.md","skills/ct-gitbook/references/change-requests.md","skills/ct-gitbook/references/content-blocks.md","skills/ct-gitbook/references/docs-sites.md","skills/ct-gitbook/references/git-sync.md","skills/ct-gitbook/references/llm-ready.md","skills/ct-gitbook/references/migration.md"],"core":false,"category":"meta","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-library-implementer-bash","description":"Bash library development with focus on creating well-structured lib/*.sh files following shell best practices. Implements reusable functions, utility modules, and shared helpers with proper documentation, error handling, and dependency management. Use when creating new lib/ modules, implementing shared functions, or adding utility libraries. Triggers on library implementation tasks, bash module creation, or utility function needs.","version":"2.0.0","path":"skills/ct-library-implementer-bash/SKILL.md","references":[],"core":false,"category":"specialist","tier":2,"protocol":"implementation","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-orchestrator","description":"This skill should be used when the user asks to \"orchestrate\", \"orchestrator mode\", \"run as orchestrator\", \"delegate to subagents\", \"coordinate agents\", \"spawn subagents\", \"multi-agent workflow\", \"context-protected workflow\", \"agent farm\", \"HITL orchestration\", or needs to manage complex workflows by delegating work to subagents while protecting the main context window. Enforces ORC-001 through ORC-009 constraints.","version":"3.0.0","path":"skills/ct-orchestrator/SKILL.md","references":["skills/ct-orchestrator/references/autonomous-operation.md","skills/ct-orchestrator/references/lifecycle-gates.md","skills/ct-orchestrator/references/orchestrator-compliance.md","skills/ct-orchestrator/references/orchestrator-handoffs.md","skills/ct-orchestrator/references/orchestrator-patterns.md","skills/ct-orchestrator/references/orchestrator-recovery.md","skills/ct-orchestrator/references/orchestrator-spawning.md","skills/ct-orchestrator/references/orchestrator-tokens.md","skills/ct-orchestrator/references/SUBAGENT-PROTOCOL-BLOCK.md"],"core":true,"category":"core","tier":0,"protocol":"agent-protocol","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-research-agent","description":"Multi-source research and investigation combining web search, documentation lookup via Context7, and codebase analysis. Synthesizes findings into actionable recommendations with proper citation and task traceability. Use when conducting research, investigating best practices, gathering technical information, or analyzing existing implementations. Triggers on research tasks, investigation needs, or information discovery requests.","version":"2.0.0","path":"skills/ct-research-agent/SKILL.md","references":[],"core":false,"category":"recommended","tier":2,"protocol":"research","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-skill-creator","description":"Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.","version":"1.0.0","path":"skills/ct-skill-creator/SKILL.md","references":["skills/ct-skill-creator/references/output-patterns.md","skills/ct-skill-creator/references/workflows.md"],"core":false,"category":"meta","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-skill-lookup","description":"This skill should be used when the user asks to \"find me a skill\", \"search for skills\", \"what skills are available\", \"get skill XYZ\", \"install a skill\", \"extend Claude's capabilities with skills\", or mentions Agent Skills, prompts.chat, SkillsMP, marketplace, external skills, or reusable AI agent components.","version":"1.1.0","path":"skills/ct-skill-lookup/SKILL.md","references":[],"core":false,"category":"meta","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-spec-writer","description":"Technical specification writing using RFC 2119 language for clear, unambiguous requirements. Creates protocol specifications, technical requirements, API specifications, and architecture documents with testable requirements and compliance criteria. Use when writing specifications, defining protocols, documenting requirements, or creating API contracts. Triggers on specification tasks, protocol definition needs, or requirement documentation.","version":"2.0.0","path":"skills/ct-spec-writer/SKILL.md","references":[],"core":false,"category":"recommended","tier":2,"protocol":"specification","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-task-executor","description":"General implementation task execution for completing assigned CLEO tasks by following instructions and producing concrete deliverables. Handles coding, configuration, documentation work with quality verification against acceptance criteria and progress reporting. Use when executing implementation tasks, completing assigned work, or producing task deliverables. Triggers on implementation tasks, general execution needs, or task completion work.","version":"2.0.0","path":"skills/ct-task-executor/SKILL.md","references":[],"core":true,"category":"core","tier":2,"protocol":"implementation","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-test-writer-bats","description":"BATS (Bash Automated Testing System) test creation for comprehensive integration and unit testing. Creates idempotent tests with happy path, error handling, and edge case coverage. Includes fixture creation and JSON output validation. Use when writing tests, creating test suites, adding test coverage, or validating bash implementations. Triggers on test writing tasks, test coverage needs, or BATS test creation.","version":"2.0.0","path":"skills/ct-test-writer-bats/SKILL.md","references":[],"core":false,"category":"specialist","tier":2,"protocol":"testing","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"ct-validator","description":"Compliance validation for verifying systems, documents, or code against requirements, schemas, or standards. Performs schema validation, code compliance checks, document validation, and protocol compliance verification with detailed pass/fail reporting. Use when validating compliance, checking schemas, verifying code standards, or auditing protocol implementations. Triggers on validation tasks, compliance checks, or quality verification needs.","version":"2.0.0","path":"skills/ct-validator/SKILL.md","references":[],"core":false,"category":"recommended","tier":2,"protocol":"validation","dependencies":[],"sharedResources":["subagent-protocol-base","task-system-integration"],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}},{"name":"railway-platform","description":"Deploy and manage applications on Railway platform. Use for creating projects, deploying services (Node.js, Python, Go, Docker, static sites), managing databases (Postgres, Redis, MySQL, MongoDB), configuring domains, environment variables, volumes, cron jobs, and networking. Integrates with GitHub for auto-deploys. Supports monorepos, private networking, and Railway Metal infrastructure.","version":"1.0.0","path":"skills/railway-platform/SKILL.md","references":["skills/railway-platform/references/01-getting-started.md","skills/railway-platform/references/02-projects.md","skills/railway-platform/references/03-services.md","skills/railway-platform/references/04-deployments.md","skills/railway-platform/references/05-databases.md","skills/railway-platform/references/06-environments.md","skills/railway-platform/references/07-domains.md","skills/railway-platform/references/08-volumes.md","skills/railway-platform/references/09-networking.md","skills/railway-platform/references/10-cron.md","skills/railway-platform/references/11-functions.md","skills/railway-platform/references/12-monorepo.md","skills/railway-platform/references/13-troubleshooting.md","skills/railway-platform/references/14-railway-metal.md"],"core":false,"category":"specialist","tier":3,"protocol":null,"dependencies":[],"sharedResources":[],"compatibility":["claude-code","cursor","windsurf","gemini-cli"],"license":"MIT","metadata":{}}]
+}

package/schemas/adr-frontmatter.schema.json

@@ -0,0 +1,72 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "adr-frontmatter",
+  "title": "ADR Frontmatter Schema",
+  "description": "Canonical frontmatter schema for CLEO Architecture Decision Records. All status values must match the architecture_decisions SQLite table enum exactly.",
+  "type": "object",
+  "required": ["Date", "Status"],
+  "properties": {
+    "Date": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "ADR creation date in YYYY-MM-DD format"
+    },
+    "Status": {
+      "type": "string",
+      "enum": ["proposed", "accepted", "superseded", "deprecated"],
+      "description": "Lifecycle status. Must match architecture_decisions DB enum exactly (lowercase only)."
+    },
+    "Accepted": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+      "description": "Date accepted in YYYY-MM-DD format. Required when Status=accepted."
+    },
+    "Supersedes": {
+      "type": "string",
+      "description": "Comma-separated ADR IDs this supersedes (e.g., 'ADR-001, ADR-002'). Required when this supersedes others."
+    },
+    "Superseded By": {
+      "type": "string",
+      "description": "ADR ID that supersedes this one (e.g., 'ADR-017'). Required when Status=superseded."
+    },
+    "Amends": {
+      "type": "string",
+      "description": "ADR ID(s) this partially amends (e.g., 'ADR-006 (§3))'). Partial amendment — scope-limited change to one section."
+    },
+    "Amended By": {
+      "type": "string",
+      "description": "Comma-separated ADR IDs that partially amend this one. Inverse of Amends."
+    },
+    "Related ADRs": {
+      "type": "string",
+      "description": "Comma-separated related ADR IDs (e.g., 'ADR-006, ADR-007')."
+    },
+    "Related Tasks": {
+      "type": "string",
+      "description": "Comma-separated related CLEO task IDs (e.g., 'T4732, T4791'). Unified replacement for: Task, Epic, References, Research, Related Epics."
+    },
+    "Gate": {
+      "type": "string",
+      "enum": ["HITL", "automated"],
+      "description": "Gate type required before implementation. Use instead of prose conditions in Status field."
+    },
+    "Gate Status": {
+      "type": "string",
+      "enum": ["pending", "passed", "waived"],
+      "description": "Current gate status."
+    },
+    "Summary": {
+      "type": "string",
+      "description": "1-3 sentence plain-language description of the decision. Enables cognitive search across ADRs without reading full content."
+    },
+    "Keywords": {
+      "type": "string",
+      "description": "Comma-separated freeform tags (e.g., 'sqlite, storage, migration'). Used for fuzzy search."
+    },
+    "Topics": {
+      "type": "string",
+      "description": "Comma-separated canonical CLEO domain tags from: tasks, session, memory, check, pipeline, orchestrate, tools, admin, nexus, storage, testing, migration, naming, security, performance."
+    }
+  },
+  "additionalProperties": false
+}

package/schemas/archive/agent-configs.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cleo-dev.com/schemas/v1/agent-configs.schema.json",
+  "schemaVersion": "1.0.0",
+  "title": "CLEO Agent Configurations Registry Schema",
+  "description": "Global registry tracking agent configuration files (CLAUDE.md, AGENTS.md, GEMINI.md) at ~/.cleo/agent-configs.json. Monitors CLEO instruction injection versions and setup status across all supported LLM agent CLIs.",
+  "type": "object",
+  "required": ["schemaVersion", "lastUpdated", "configs"],
+  "additionalProperties": false,
+
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "Schema version for this registry file (semver). Initial version: 1.0.0."
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp of last registry modification. Updated when any config entry changes."
+    },
+    "configs": {
+      "type": "object",
+      "description": "Agent configuration files keyed by absolute file path. Each entry tracks injection version and setup status for one agent config file.",
+      "additionalProperties": {
+        "$ref": "#/definitions/agentConfigEntry"
+      }
+    }
+  },
+
+  "definitions": {
+    "agentConfigEntry": {
+      "type": "object",
+      "description": "Single agent configuration file tracking entry. Monitors CLEO instruction injection version and setup state.",
+      "required": ["version", "method", "setupDate", "status"],
+      "additionalProperties": false,
+      "properties": {
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "CLEO version of injected instructions. Extracted from <!-- CLEO:START vX.X.X --> marker."
+        },
+        "method": {
+          "type": "string",
+          "enum": ["@", "inline", "embed"],
+          "description": "Injection method used: @=@ reference to ~/.cleo/docs/, inline=marker-based injection, embed=full content embedded."
+        },
+        "setupDate": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when this config file was first created/configured by CLEO."
+        },
+        "lastChecked": {
+          "type": ["string", "null"],
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of most recent validation check. Null if never validated since setup."
+        },
+        "status": {
+          "type": "string",
+          "enum": ["current", "outdated", "missing", "invalid"],
+          "description": "Config file health status: current=version matches CLI, outdated=old version detected, missing=file not found, invalid=corrupt or unparseable."
+        },
+        "cliVersion": {
+          "type": ["string", "null"],
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "CLEO CLI version when last checked. Used to detect version drift between agent config and installed CLI."
+        },
+        "agentType": {
+          "type": ["string", "null"],
+          "enum": ["claude", "gemini", "codex", "kimi", null],
+          "description": "Agent type inferred from config file name/path. Null if cannot determine."
+        },
+        "notes": {
+          "type": ["string", "null"],
+          "maxLength": 500,
+          "description": "Optional notes about this config (e.g., manual edits detected, custom setup, migration status)."
+        }
+      }
+    }
+  },
+
+  "examples": [
+    {
+      "schemaVersion": "1.0.0",
+      "lastUpdated": "2026-01-05T14:23:45Z",
+      "configs": {
+        "/home/user/.claude/CLAUDE.md": {
+          "version": "0.50.2",
+          "method": "@",
+          "setupDate": "2026-01-01T10:00:00Z",
+          "lastChecked": "2026-01-05T14:23:45Z",
+          "status": "current",
+          "cliVersion": "0.50.2",
+          "agentType": "claude",
+          "notes": null
+        },
+        "/home/user/.claude/AGENTS.md": {
+          "version": "0.50.2",
+          "method": "@",
+          "setupDate": "2026-01-01T10:00:00Z",
+          "lastChecked": "2026-01-05T14:23:45Z",
+          "status": "current",
+          "cliVersion": "0.50.2",
+          "agentType": null,
+          "notes": null
+        },
+        "/home/user/.gemini/GEMINI.md": {
+          "version": "0.50.1",
+          "method": "@",
+          "setupDate": "2026-01-01T10:00:00Z",
+          "lastChecked": "2026-01-05T14:23:45Z",
+          "status": "outdated",
+          "cliVersion": "0.50.2",
+          "agentType": "gemini",
+          "notes": "Needs update to v0.50.2"
+        }
+      }
+    }
+  ]
+}

package/schemas/archive/agent-registry.schema.json

@@ -0,0 +1,132 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://cleo-dev.com/schemas/v1/agent-registry.schema.json",
+  "title": "CLEO Agent Registry Schema",
+  "description": "Unified registry for LLM coding agent configurations, paths, and capabilities",
+  "type": "object",
+  "required": ["schemaVersion", "lastUpdated", "agents"],
+  "properties": {
+    "schemaVersion": {
+      "type": "string",
+      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
+      "description": "Semantic version of this schema"
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date",
+      "description": "Last update date (ISO 8601)"
+    },
+    "agents": {
+      "type": "object",
+      "description": "Map of agent ID to configuration",
+      "additionalProperties": {
+        "$ref": "#/$defs/agentConfig"
+      }
+    },
+    "instructionFileMap": {
+      "type": "object",
+      "description": "Map of instruction file names to list of agents using them",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    },
+    "priorityTiers": {
+      "type": "object",
+      "description": "Agent groupings by priority tier",
+      "properties": {
+        "tier1": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "High priority - primary agents"
+        },
+        "tier2": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Medium priority - secondary agents"
+        },
+        "tier3": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Low priority - emerging agents"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "agentConfig": {
+      "type": "object",
+      "required": ["id", "displayName", "globalDir", "instructionFile", "skillsDir", "priority"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]*$",
+          "description": "Unique agent identifier (lowercase, hyphenated)"
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Human-readable display name"
+        },
+        "vendor": {
+          "type": "string",
+          "description": "Company/organization behind the agent"
+        },
+        "globalDir": {
+          "type": "string",
+          "description": "Global configuration directory path (use $HOME for home dir)"
+        },
+        "projectDir": {
+          "type": "string",
+          "description": "Project-level configuration directory (relative to project root)"
+        },
+        "instructionFile": {
+          "type": "string",
+          "description": "Instruction/configuration markdown file name"
+        },
+        "skillsDir": {
+          "type": "string",
+          "description": "Skills directory path relative to globalDir"
+        },
+        "projectSkillsDir": {
+          "type": "string",
+          "description": "Project-level skills directory (relative to project root)"
+        },
+        "priority": {
+          "type": "string",
+          "enum": ["high", "medium", "low"],
+          "description": "Agent priority tier for CLEO support"
+        },
+        "status": {
+          "type": "string",
+          "enum": ["active", "beta", "deprecated", "planned"],
+          "default": "active",
+          "description": "Support status"
+        },
+        "cliDetection": {
+          "type": "object",
+          "description": "How to detect if agent CLI is installed",
+          "properties": {
+            "method": {
+              "type": "string",
+              "enum": ["directory", "command", "file"],
+              "description": "Detection method"
+            },
+            "check": {
+              "type": "string",
+              "description": "Path, command, or file to check"
+            }
+          }
+        },
+        "agentSkillsCompatible": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether agent is compatible with vercel-labs/add-skill"
+        },
+        "notes": {
+          "type": "string",
+          "description": "Additional notes about this agent"
+        }
+      }
+    }
+  }
+}