Codemie Infrastructure as Code

Infrastructure as Code solution for managing Codemie AI assistants, datasources, and workflows through declarative YAML configuration.

🎯 What This Solves

$3

1. Access Control Limitations 🔒
In Codemie UI, only resource creators can modify assistants and workflows. Team members cannot contribute improvements even when they have ideas.

2. Limited Execution History Visibility 👁️
Only the creator can see execution history of assistants and workflows - even administrators lack access. This makes debugging and monitoring difficult for the team.

3. No Custom Validation ✅
Changes go live immediately without additional checks. There's no way to enforce team-specific validation rules or quality gates before deployment.

$3

Democratic Access
Anyone can propose changes via pull requests. Changes are reviewed and deployed by a service account with full access to all resources and their execution history.

Custom Validation Pipeline
Add your own validation rules in CI/CD - from simple YAML checks to AI-powered prompt reviews. Nothing deploys until it passes your criteria.

Team Visibility
Service account has access to execution history of all assistants and workflows, enabling team-wide monitoring, debugging, and analytics.

$3

- Code Review Process - Changes reviewed before going live, improving quality
- DRY Configuration - $ref mechanism eliminates duplication (define once, use everywhere)
- Automated Deployment - CI/CD integration removes manual steps and human errors
- Audit Trail - Git history shows who changed what and why
- Environment Consistency - Same configuration can be deployed to dev/staging/prod or can be used by other teams

Overview

This IaC solution enables version-controlled, reproducible deployment of Codemie resources using a GitOps approach. Changes are detected via SHA256 checksums, and resources are managed by their human-readable names.

Installation

``bash
npm install
`

$3

Create a .env file in the project root:

`bash
CODEMIE_API_URL=https://your-instance.codemie.ai/api
CODEMIE_AUTH_URL=https://your-keycloak.auth.com
CODEMIE_REALM=codemie
CODEMIE_CLIENT_ID=your-client-id
CODEMIE_CLIENT_SECRET=your-client-secret
`

⚠️ Security: DO NOT commit .env to Git!

The .env file is already added to .gitignore and should never be committed to the repository.

For local development:
- Each developer creates their own .env file locally with actual credentials
- Copy the template above and replace with your values
- Use your own credentials (do not share them via Git)
- Optional: Create .env.example in your project (template without actual secrets) to help team members

For CI/CD (GitLab):
- Add environment variables in GitLab: Settings → CI/CD → Variables
- Add each variable separately:
- CODEMIE_API_URL
- CODEMIE_AUTH_URL
- CODEMIE_REALM
- CODEMIE_CLIENT_ID
- CODEMIE_CLIENT_SECRET (mark as Masked)

Quick Start

`bash


Full validation with API connectivity check (default, recommended)

npm run validate

Basic validation only (fast, no API connection)

npm run validate:basic

Preview changes

npm run preview

Deploy resources

npm run deploy

Deploy resources and delete orphaned ones

npm run deploy -- --prune

Remove all IaC-managed resources

npm run destroy

Create backup of all resources

npm run backup

Use external config file to override default names and locations for: codemie.yaml, .codemie/state.json, backups

npm run --config codemie/iac.json
`
Note: All commands work identically whether you use monolithic configuration or modular imports - the $import directives are automatically resolved during config loading.

Config file structure:
`json
{
"rootDir": "root/of/working/directory",
"codemieConfig": "path/to/codemie.yaml",
"codemieState": "path/to/state.json",
"backupsDirectory": "path/to/backups"
}
`
It is not mandatory to provide all fields - any missing fields will use default values.

Default Config:
`json
{
"rootDir": ".",
"codemieConfig": "codemie.yaml",
"codemieState": ".codemie/state.json",
"backupsDirectory": "backups"
}
`


Validation types:
- Full validation (npm run validate) checks:
- codemie.yaml syntax is valid
- All referenced files exist
- Required fields are present
- No cyclic dependencies in sub-assistants
- Assistants with sub-assistants cannot be sub-assistants themselves
- Plus API checks:
- Slug conflicts with existing assistants in Codemie (if slugs are provided)
- Ensures your slugs are globally unique before deployment

- Basic validation (npm run validate:basic) skips API checks (faster, no credentials needed)

$3

The tool provides a unified codemie command for all operations:

`bash


Show help and available commands

codemie --help

Deploy resources

codemie deploy
codemie deploy --prune

Other commands

codemie backup
codemie destroy --force
codemie preview
codemie validate --check-api
`

For local development, npm scripts provide convenient shortcuts:
`bash
npm run deploy # → codemie deploy
npm run backup # → codemie backup
npm run destroy # → codemie destroy --force
`

🔄 Migrating Existing Resources to IaC

If you already have assistants, datasources, and workflows created in Codemie UI, use the backup command to migrate them to IaC management:

`bash
npm run backup
`

$3

Automated Export:
- Fetches all resources from your Codemie platform (assistants, datasources, workflows, integrations)
- Generates IaC configuration files in backups/YYYY-MM-DDTHH-MM-SS/ directory:
- codemie.yaml - Main configuration with all resources (MCP servers use integration aliasing)
- state.json - State file with resource IDs and checksums
- system_prompts/*.prompt.md - Assistant system prompts
- workflows/*.yaml - Workflow definitions
- openapi_specs/*.json - OpenAPI tool specifications

Transaction Safety:
- Atomic backup process with rollback on failure
- Resume capability - if backup is interrupted, rerunning continues from last checkpoint
- Temporary directory used during backup (.temp-*) - moved to final location only on success
- Progress tracking with transaction.json checkpoint file

Type-Safe Conversions:
- SDK response types → IaC resource formats with proper field mapping
- Workflow YAML includes assistant ID → name resolution for readability

$3

Step 1: Create Backup
`bash
npm run backup
`

Output:
`
🗄️ Creating backup of all Codemie resources...

🔌 Connecting to Codemie API...
✓ Connected to Codemie API

📁 Temporary backup directory: backups/.temp-2025-01-27

🤖 Fetching assistants...
Found 15 assistant(s)
• TAD BA Helper (ast-123)
• TAD Code Analyst (ast-456)
...
✓ Backed up 15 assistant(s)

📊 Fetching datasources...
Found 8 datasource(s)
✓ Backed up 8 datasource(s)

🔄 Fetching workflows...
Found 3 workflow(s)
✓ Backed up 3 workflow(s)

🔄 Finalizing backup...
✓ Backup finalized at backups/2025-01-27T14-30-45

==================================================
📊 Backup Summary:

🤖 Assistants: 15
📊 Datasources: 8
🔄 Workflows: 3
🔌 Integrations: 5

📁 Location: backups/2025-01-27T14-30-45
`

Step 2: Review Generated Files

`bash
cd backups/2025-01-27T14-30-45
ls -la
`

Files created:
`
codemie.yaml # Main IaC configuration
state.json # Resource state (IDs, checksums)
system_prompts/ # Assistant system prompts
tad-ba-helper.prompt.md
tad-code-analyst.prompt.md
workflows/ # Workflow definitions
code-review-workflow.yaml
openapi_specs/ # OpenAPI tool specs
`

Step 3: Copy to Your IaC Project

`bash


Option A: Replace entire configuration

cp backups/2025-01-27T14-30-45/* ./
mv backups/2025-01-27T14-30-45/system_prompts/* system_prompts/
mv backups/2025-01-27T14-30-45/workflows/* workflows/
mv backups/2025-01-27T14-30-45/openapi_specs/* openapi_specs/

Option B: Merge specific resources into existing config

Manually copy needed sections from backups/2025-01-27T14-30-45/codemie.yaml

`

Step 4: Validate & Deploy

`bash
npm run validate # Check configuration
npm run preview # Preview (should show "No changes")
npm run deploy # Deploy (updates state file with current checksums)
`

$3

Backup Interrupted?
- Just run npm run backup again - it will resume from last checkpoint
- Transaction file (transaction.json) tracks progress
- Temporary directory (.temp-*) will be cleaned up automatically

Backup Failed Completely?
- Check .temp-* directory exists - if yes, partial backup was attempted
- Error message will indicate which resource failed
- Temporary directory will be automatically cleaned up (rollback)
- Fix the issue and rerun backup

Code Datasource Missing Repository Link?
- Some code datasources may show warning: ⚠️ Code datasource missing repository link
- SDK sometimes doesn't return code.link field
- Manually add link: https://github.com/... in codemie.yaml datasource section

Workflow Assistant IDs Not Resolved?
- If workflow YAML contains assistant_id: ast-xxx instead of assistant name
- This happens when assistant doesn't exist in backup (e.g., deleted or from another project)
- Manually replace with correct assistant name or ID in workflow YAML file

Resume From Specific Point?
- Transaction file tracks what's completed: transaction.json
- Contains: completed: ['ast-1', 'ast-2'] and failed: [{id: 'ast-3', error: '...'}]
- To force fresh backup: delete backups/YYYY-MM-DDTHH-MM-SS/transaction.json before rerunning

📝 Prompt Compilation System

The repository includes an automated prompt compilation system for managing complex prompts with reusable components and configuration.

$3

Use template-based compilation for:
- Prompts with shared components (includes)
- Multiple configuration variants
- Team collaboration on modular components
- Complex prompts that benefit from DRY principles

Use direct editing for:
- Simple, self-contained prompts
- Quick changes or updates
- Prompts that don't need shared components

$3

`bash


Compile specific agent

npm run compile -- --prompt tad-ba-helper

Compile all prompts

npm run compile:all

Check if compiled files are up-to-date

npm run compile:check

Verbose output

npm run compile:all -- --verbose
`

> Note: Compilation functionality is available only as internal npm scripts. The compile command is not exposed in the published codemie-iac package, which focuses exclusively on infrastructure management (deploy, validate, preview, destroy, backup).

$3

`
prompt_source/ # Source templates
├── shared/ # Shared includes
│ ├── jira-processing.include.md
│ └── confluence-processing.include.md
└── {agent-name}/ # Agent directory
├── {agent}.prompt.md # Template with placeholders
├── {agent}.config.yaml # Configuration values
└── {agent}.requirements.md # Requirements doc

system_prompts/ # Ready-to-deploy prompts
├── README.md # Documentation
└── *.prompt.md # Final prompts (some auto-compiled)
`

$3

The compilation system handles three types of placeholders:

1. Config Placeholders - {config.key}
- Resolved during compilation from .config.yaml
- Example: {team_ids.prescreening} → 91267

2. Runtime Variables - {{system}}
- Preserved for Codemie platform (resolved at runtime)
- Example: {{current_user}}, {{date}}

3. Documentation Examples -
- Part of prompt text, never resolved
- Example: ,

$3

Source: prompt_source/my-agent/my-agent.prompt.md
`markdown
---
prompt_name: My Agent
prompt_version: 1.0.0
---

Instructions

{include:jira-processing}

Use team ID: {team_ids.my_team}
Current user: {{current_user}}
`

Config: prompt_source/my-agent/my-agent.config.yaml
`yaml
prompt_version: 1.0.0

team_ids:
my_team: "12345"
`

Compiled: system_prompts/my-agent/my-agent.prompt.md
`markdown
---
prompt_name: My Agent
prompt_version: 1.0.0
---

Instructions

[Full content of jira-processing.include.md inserted here]

Use team ID: 12345
Current user: {{current_user}}
`

$3

Compilation is fully automated in the deployment pipeline:

1. Compile Stage - Runs before validation
2. Validation - Checks for unresolved placeholders
3. Deployment - Deploys compiled prompts
4. Auto-Commit - CI commits compiled files back to repository

Workflow:
- Edit source files in prompt_source/
- Push to repository
- CI automatically compiles and deploys
- Compiled files updated in system_prompts/

$3

The compilation system uses a plugin-based architecture for easy extension:

- ProcessorPlugin - Custom content transformations
- ValidatorPlugin - Custom validation rules
- Type-safe - Full TypeScript support
- Well-documented - See ARCHITECTURE.md for details

For complete documentation:
- Source Templates: prompt_source/README.md
- System Prompts: system_prompts/README.md
- Architecture: ARCHITECTURE.md
- Development Guide: CONTRIBUTING.md

Configuration Structure

All resources are defined in codemie.yaml:

`yaml
version: 1

project:
name: ta-desk
description: Your project description

environment:
codemie_api_url: ${CODEMIE_API_URL}
# ... other env vars

imported:
integrations: # Platform integrations (referenced via $ref)
assistants: # Existing assistants (for workflows)
datasources: # Existing datasources

resources:
datasources: # Datasources to create/manage
assistants: # Assistants to create/manage
workflows: # Workflows to create/manage
`

For detailed examples of each resource type, see:
- examples/datasource-examples.yaml - All datasource types with field descriptions
- examples/assistant-examples.yaml - Assistant patterns and configurations
- examples/toolkit-examples.yaml - All toolkit configurations
- examples/workflow-examples.yaml - Workflow patterns and structures

📁 Configuration Organization

$3

For large projects, you can split configuration into multiple files using the $import directive. The ConfigLoader automatically resolves imports and supports three organization styles:

#### Style 1: Monolithic

Keep everything in one file - perfect for small projects:

`yaml


codemie.yaml

version: 1
project:
name: my-project

resources:
datasources:
- name: repo-1
type: code
link: https://github.com/org/repo-1
- name: repo-2
type: code
link: https://github.com/org/repo-2

assistants:
- name: Assistant 1
prompt: ./system_prompts/assistant-1.prompt.md
model: gpt-4o
`

#### Style 2: Grouped Resources

Group related resources in array files:

`yaml


codemie.yaml


resources:
datasources:
- $import: configs/datasources/all-repos.yaml
- $import: configs/datasources/knowledge-bases.yaml

assistants:
- $import: configs/assistants/ba-team.yaml
- $import: configs/assistants/dev-team.yaml
`

`yaml


configs/datasources/all-repos.yaml

- name: repo-1
type: code
link: https://github.com/org/repo-1

- name: repo-2
type: code
link: https://github.com/org/repo-2

- name: repo-3
type: code
link: https://github.com/org/repo-3
`

`yaml


configs/assistants/ba-team.yaml

- name: BA Reviewer
prompt: ./system_prompts/ba-reviewer.prompt.md
model: claude-3-7

- name: BA Helper
prompt: ./system_prompts/ba-helper.prompt.md
model: gpt-4.1
sub_assistants:
- BA Reviewer
`

#### Style 3: Individual Files

Each resource in a separate file for maximum modularity:

`yaml


codemie.yaml


resources:
datasources:
- $import: configs/datasources/repo-1.yaml
- $import: configs/datasources/repo-2.yaml
- $import: configs/datasources/jira-kb.yaml

assistants:
- $import: configs/assistants/ba-reviewer.yaml
- $import: configs/assistants/ba-helper.yaml
- $import: configs/assistants/code-reviewer.yaml
`

`yaml


configs/datasources/repo-1.yaml


name: repo-1
type: code
description: Repository 1
link: https://github.com/org/repo-1
branch: main
`

`yaml


configs/assistants/ba-reviewer.yaml


name: BA Reviewer
description: Reviews BA artifacts
prompt: ./system_prompts/ba-reviewer.prompt.md
model: claude-3-7
shared: true
toolkits:
- toolkit: Project Management
tools:
- $ref: tool_definitions.jira_tool
`

#### Style 4: Hybrid

Mix all approaches based on your needs:

`yaml


codemie.yaml


resources:
datasources:
# Inline for quick tests
- name: test-repo
type: code
link: https://github.com/org/test

# Array import for simple repos
- $import: configs/datasources/simple-repos.yaml

# Individual files for critical resources
- $import: configs/datasources/production-jira.yaml
- $import: configs/datasources/production-confluence.yaml

assistants:
# Team groups
- $import: configs/assistants/ba-team.yaml
- $import: configs/assistants/dev-team.yaml

# VIP assistants separately
- $import: configs/assistants/ceo-assistant.yaml
`

$3

Object Imports:
`yaml


Import entire sections

tool_definitions:
$import: configs/shared/tool-definitions.yaml

datasource_defaults:
$import: configs/shared/datasource-defaults.yaml
`

Circular Import Protection:
- Automatically detects circular dependencies (file-a → file-b → file-a)
- Throws clear error with import chain: Circular import detected: [file-a.yaml, file-b.yaml, file-a.yaml]
- Allows same file in different branches (tree structure, not linear chain)

Nested Imports:
`yaml


configs/datasources/all-repos.yaml


- $import: base-repos.yaml # Import from same directory
- name: additional-repo
type: code
link: https://github.com/org/additional
`

Cross-Project Reuse:
`yaml


Project A

resources:
assistants:
- $import: ../shared-assistants/code-reviewer.yaml
- $import: configs/assistants/project-a-specific.yaml

Project B

resources:
assistants:
- $import: ../shared-assistants/code-reviewer.yaml
- $import: configs/assistants/project-b-specific.yaml
`

$3

`
project-root/
├── codemie.yaml # Main config (imports only)
├── configs/
│ ├── project.yaml # Project metadata
│ ├── environment.yaml # Environment variables
│ ├── imported.yaml # Imported resources
│ ├── shared/
│ │ ├── tool-definitions.yaml
│ │ └── datasource-defaults.yaml
│ ├── datasources/
│ │ ├── repos/
│ │ │ ├── frontend-repos.yaml
│ │ │ └── backend-repos.yaml
│ │ └── knowledge-bases/
│ │ ├── jira-production.yaml
│ │ └── confluence-production.yaml
│ ├── assistants/
│ │ ├── ba-team/
│ │ │ ├── ba-reviewer.yaml
│ │ │ └── ba-helper.yaml
│ │ └── dev-team/
│ │ ├── code-reviewer.yaml
│ │ └── codebase-digger.yaml
│ └── workflows/
│ ├── test-automation.yaml
│ └── release-notes.yaml
├── system_prompts/
│ └── *.prompt.md
└── workflows/
└── *.yaml
`

📁 File Structure

`
assistant-resources/
├── codemie.yaml # Main IaC configuration
├── .codemie/
│ └── state.json # Deployment state (committed to Git)
├── system_prompts/
│ └── *.prompt.md # Prompt content files
├── workflows/
│ └── *.yaml # Workflow definitions
├── examples/ # Configuration examples (reference)
│ ├── datasource-examples.yaml
│ ├── assistant-examples.yaml
│ ├── toolkit-examples.yaml
│ └── workflow-examples.yaml
└── src/ # IaC implementation
`

Key Features

$3

Organize your configuration across multiple files for better maintainability and team collaboration. The $import directive automatically resolves imports during config loading:

`yaml


Main config - clean and organized


resources:
datasources:
- $import: configs/datasources/repo-1.yaml # Single resource
- $import: configs/datasources/all-repos.yaml # Array of resources

assistants:
- $import: configs/assistants/ba-team.yaml
`

Supports inline resources, individual files, array files, and any combination. See Configuration Organization for details.

$3

Resources are identified by their name field. Renaming a resource in codemie.yaml results in deleting the old resource and creating a new one.

Why names instead of IDs?
1. Platform generates UUIDs - You don't know the ID until after creation, making it impossible to write config before deployment
2. Git-friendly - Human-readable names enable meaningful diffs in pull requests: "Added Customer Support Bot" vs "Added resource a3f2b8c9-..."
3. Team collaboration - Names are self-documenting; team members understand what changed without looking up UUIDs
4. Config portability - Same config can be deployed to different environments without ID conflicts

Why delete+create on rename?
- Without UUIDs in config, there's no way to track that "Old Name" became "New Name"
- Alternative would require manual migration steps, defeating IaC purpose
- State file (state.json) maps names→UUIDs for updates, but rename breaks this mapping

About slugs:
- slug is optional for all assistants
- Platform auto-generates slug from name if not provided
- Recommendation: Don't specify slug unless you have specific requirements
- Sub-assistants use names (not slugs)
- Workflows reference assistants by name

$3

Changes to prompts and configuration are detected via SHA256 checksums, ensuring only modified resources are updated.

Why checksums instead of timestamps or full comparison?
1. Idempotency - Same config produces same checksums, enabling safe re-runs without unintended changes
2. Efficiency - Avoid costly API calls to fetch resources for comparison when nothing changed
3. Precision - Separate checksums for prompt content and resource config allow granular change detection
4. Git integration - Checksums stored in state.json provide audit trail of what was actually deployed

How it works:
- Prompt checksum: SHA256 of prompt file content
- Config checksum: SHA256 of resource configuration (excluding prompt path, including all other fields)
- On deployment: Compare stored checksums with current checksums
- Only update if either checksum differs

$3

Resources removed from codemie.yaml are NOT automatically deleted by default. To remove them, you must explicitly use the --prune flag.

How orphaned resources are detected:
1. Load state.json - contains all resources created by IaC with their names and UUIDs
2. Load codemie.yaml - contains desired state (what should exist)
3. Compare: For each resource in state.json, check if it exists in codemie.yaml
4. If resource is in state but NOT in config → mark as orphaned
5. If --prune is used: Delete orphaned resources from platform using their UUID
6. Remove from state.json

Safety mechanisms:
- Opt-in cleanup - npm run deploy never deletes resources unless you pass --prune.
- Only IaC-created resources - Resources NOT in state.json are never deleted (manually created resources are safe)
- Per-resource-type - Checks assistants, datasources, workflows separately
- Logged deletion - Each deletion is logged with resource name and UUID for audit

Why automatic cleanup?
- GitOps principle - Config is source of truth; platform state should match config
- No manual cleanup - Prevents orphaned resources accumulating over time
- Safe refactoring - Rename/restructure resources without leaving behind old versions

$3

Workflows reference assistants by assistant_name, which are resolved to platform UUIDs during deployment from state.json or imported.assistants.

Why name-based references in workflows?
1. Readability - assistant_name: "Code Reviewer" vs assistant_id: "a3f2b8c9-..."
2. Maintainability - Update assistant name in one place (codemie.yaml), workflows auto-resolve
3. Versionability - Git diffs show meaningful changes: "Changed to Data Analyzer" vs changed UUID
4. Cross-environment - Same workflow YAML works in dev/prod with different assistant UUIDs

Resolution order:
1. Check state.json - IaC-created assistants (have name→UUID mapping)
2. Check imported.assistants - Pre-existing platform assistants referenced by config
3. If not found → deployment fails with clear error message

This happens during npm run deploy, before sending workflow YAML to API.

$3

Avoid duplication by referencing integrations:

`yaml
imported:
integrations:
- alias: jira_connection
id: 9ab1ad26-07f1-4d1a-9b0b-33d33a9d2cde
credential_type: Jira

resources:
# For datasources: use .id suffix to get UUID string
datasources:
- name: my-jira-kb
type: knowledge_base_jira
setting_id: $ref:imported.integrations.jira_connection.id # → "9ab1ad26..."
jql: project = MY

# For toolkits: reference full object (no .id suffix)
assistants:
- name: My Assistant
toolkits:
- toolkit: Project Management
tools:
- name: generic_jira_tool
settings:
$ref: imported.integrations.jira_connection # → full object
`

Why $ref instead of repeating integration IDs?
1. Single source of truth - Integration ID defined once, used everywhere
2. Easier updates - Change integration ID in one place, applies to all references
3. Reduced errors - Copy-paste mistakes eliminated
4. Semantic clarity - $ref:imported.integrations.jira_connection.id explains what it references

How $ref works:
- For datasources: Path MUST end with .id to get the UUID string
- $ref:imported.integrations.name.id → resolves to UUID string
- For toolkits: Path references the full object (no .id suffix)
- $ref:imported.integrations.name → resolves to full integration object
- During config load, ConfigLoader resolves all $ref references
- Validation ensures referenced path exists before deployment

State Management

The .codemie/state.json file tracks IaC-created resources:

`json
{
"version": "1",
"project": "ta-desk",
"lastSync": "2025-01-15T10:30:00Z",
"resources": {
"assistants": {
"My Assistant": {
"id": "uuid-here",
"promptChecksum": "sha256-hash",
"configChecksum": "sha256-hash"
}
},
"datasources": { ... },
"workflows": { ... }
}
}
`

Why commit state.json to Git?
1. CI/CD requirement - Pipeline needs to know what's deployed to calculate changes
2. Team visibility - Everyone sees current production state
3. Audit trail - Git history shows who deployed what and when
4. No external backend - Simpler than S3/Consul/etc.; Git is the backend

Why no state locking?
- GitLab CI/CD resource_group: production ensures sequential execution
- Only one pipeline runs at a time → no concurrent modifications → no race conditions
- State conflicts impossible with proper CI/CD setup

📝 Configuration Guide

$3

When you want to reference resources that already exist on the Codemie platform (created manually or by another team), you need to import them into your IaC configuration.

#### Why Import Resources?

For Integrations:
- Integrations are created in Codemie UI
- IaC only references them - doesn't create or manage them
- Required for datasources and toolkits to authenticate

For Datasources:
- Reuse datasources created by other teams
- Avoid duplicate indexing of the same data
- Share knowledge bases across multiple assistants

For Assistants:
- Reference existing assistants in workflows
- Use assistants as sub-assistants without managing them
- Collaborate across teams without duplicating resources

#### How to Import Resources

Step 1: Find the resource in Codemie UI

For Integrations:
1. Go to Codemie UI → Integrations
2. Find your integration (e.g., "Git Server Connection")
3. Copy the UUID from the URL or integration details
4. Note the integration type (Git, Jira, Confluence, etc.)

For Datasources:
1. Go to Codemie UI → Data Sources
2. Find your datasource
3. Copy the UUID from the URL (e.g., 8994c477-fc97-4fc0-a1e6-b73be514f684)
4. Note the datasource name and type

For Assistants:
1. Go to Codemie UI → Assistants
2. Find your assistant
3. Copy the UUID from the URL (e.g., 79db7d36-eb89-468d-a99f-44fd4bf92b01)
4. Note the exact assistant name

Step 2: Add to imported section in codemie.yaml

`yaml
imported:
# Integrations (created in Codemie UI, referenced by datasources/toolkits)
integrations:
- alias: git_server_connection
id: f1e53ba4-5ab1-4c05-ad8f-c3625ba5a155 # From Codemie UI
credential_type: Git

- alias: jira_connection
id: 9ab1ad26-07f1-4d1a-9b0b-33d33a9d2cde
credential_type: Jira

- alias: confluence_connection
id: d0f8c5aa-afbb-45a6-9fa3-a2a39ac7e0cb
credential_type: Confluence

# Datasources (existing datasources to reuse)
datasources:
- id: 8994c477-fc97-4fc0-a1e6-b73be514f684 # From Codemie UI
name: Confluence-6May2025 # Exact name from platform
type: knowledge_base_confluence

- id: b31ac927-37ec-4038-bdcc-98fab5d76ec1
name: Jira-Production-KB
type: knowledge_base_jira

# Assistants (existing assistants to reference in workflows/sub-assistants)
assistants:
- id: 79db7d36-eb89-468d-a99f-44fd4bf92b01 # From Codemie UI
name: TA Desk Front-End Code Reviewer # Exact name from platform

- id: 96e2d32a-1fe3-483c-b444-4afec9134928
name: Checklist Generator Assistant
`

Step 3: Use imported resources in your configuration

`yaml
resources:
datasources:
# Use imported integration
- name: my-repo
type: code
link: https://git.example.com/repo
branch: master
setting_id: $ref:imported.integrations.git_server_connection.id # Reference

assistants:
# Use imported datasource
- name: My Assistant
prompt: ./system_prompts/assistant.prompt.md
model: gpt-4o
context:
- context_type: knowledge_base
name: Confluence-6May2025 # References imported datasource

# Use imported integration in toolkit
toolkits:
- toolkit: Project Management
tools:
- name: generic_jira_tool
label: Generic Jira
settings_config: false
settings:
$ref: imported.integrations.jira_connection # Reference

# Use imported assistant as sub-assistant
sub_assistants:
- TA Desk Front-End Code Reviewer # References imported assistant

workflows:
- name: My Workflow
definition: ./workflows/workflow.yaml
mode: Sequential
`

Important Notes:

- Integration IDs: Find in Codemie UI → Integrations (usually in URL or settings)
- Datasource IDs: Find in Codemie UI → Data Sources → Select datasource → Check URL
- Assistant IDs: Find in Codemie UI → Assistants → Select assistant → Check URL
- Exact names: Must match platform names exactly (case-sensitive)
- Type validation: IaC validates that types match platform resources
- Access permissions: Service account must have access to imported resources

Why use imported instead of creating via IaC?

| Resource Type | When to Import | When to Create via IaC |
|---------------|----------------|------------------------|
| Integrations | Always (created in UI only) | Not yet supported |
| Datasources | Shared across teams, large/expensive to index | Team-specific datasources |
| Assistants | Managed by other teams, stable production assistants | Your team's assistants |

$3

You can link assistants together using sub_assistants (name-based):

`yaml
resources:
assistants:
# Sub-assistant (must be defined first)
- name: Sub Assistant Helper
prompt: ./system_prompts/sub.prompt.md
description: "Helper assistant"
model: gpt-4o

# Main assistant with nested sub-assistant
- name: Main Assistant
prompt: ./system_prompts/main.prompt.md
description: "Main assistant with helper"
model: gpt-4o
sub_assistants:
- "Sub Assistant Helper" # Reference by NAME
`

How it works:
- Define sub-assistants before the main assistant in the YAML
- Use sub_assistants to reference them by name (name-based approach)
- During deployment, names are automatically resolved to IDs from state.json
- Sub-assistants must exist (be deployed first) for resolution to work

⚠️ Important restrictions:
- No cyclic dependencies: A → B → C → A is not allowed
- No nested sub-assistants: If an assistant has sub_assistants, it cannot be used as a sub-assistant by another assistant
- Example of invalid configuration:
`yaml
# ❌ Invalid: Middle has sub-assistants AND is used as sub-assistant
assistants:
- name: Helper
model: gpt-4o

- name: Middle
model: gpt-4o
sub_assistants: ["Helper"] # Middle has sub-assistants

- name: Main
model: gpt-4o
sub_assistants: ["Middle"] # ❌ Middle cannot be sub-assistant!
`

📋 Deployment Order:

IaC automatically handles deployment order to resolve dependencies:

1. Datasources first - All datasources are created before assistants
2. Sub-assistants before main - Assistants are deployed in definition order
3. Assistants before workflows - Workflows are deployed last

💡 Best Practice: Define resources in the order they're referenced (datasources → sub-assistants → main assistants → workflows) for clarity.

$3

Toolkits provide additional capabilities to assistants, such as Git operations, Project Management (Jira/Confluence), and OpenAPI integration.

> 🔧 For detailed examples, see examples/toolkit-examples.yaml with all available toolkits and their configurations.

Available Toolkits:
1. Git - Git operations (PR changes, diffs)
2. Project Management - Jira and Confluence integration
3. OpenAPI - OpenAPI specification tools

Available MCP Integrations:
1. Figma MCP - Figma design tool integration
2. Atlassian MCP - Alternative Jira/Confluence integration (more advanced than toolkit)
3. Custom MCP - Any MCP-compatible server

#### Integration Aliases & Tool Definitions

To avoid repeating integration and tool settings across multiple assistants, you can define them once and reference using aliases:

Two-Level System:

`yaml


Level 1: Define integrations (created in Codemie UI)

imported:
integrations:
- alias: jira_main
id: "9ab1ad26-07f1-4d1a-9b0b-33d33a9d2cde"
credential_type: Jira

- alias: confluence_main
id: "d0f8c5aa-afbb-45a6-9fa3-a2a39ac7e0cb"
credential_type: Confluence

Level 2: Define tools (referencing integrations)

tool_definitions:
jira_tool:
name: generic_jira_tool
label: Generic Jira
settings_config: false
settings:
$ref: imported.integrations.jira_main # References integration

confluence_tool:
name: generic_confluence_tool
label: Generic Confluence
settings_config: false
settings:
$ref: imported.integrations.confluence_main

Level 3: Use tools in assistants

resources:
assistants:
- name: BA Assistant
model: gpt-4o
toolkits:
- toolkit: Project Management
tools:
- $ref: tool_definitions.jira_tool
- $ref: tool_definitions.confluence_tool
`

Usage Options:

`yaml


Option 1: Use tool definitions (RECOMMENDED - cleanest & most explicit)

tools:
- $ref: tool_definitions.jira_tool
- $ref: tool_definitions.confluence_tool

Option 2: Reference integration directly (middle ground)

tools:
- name: generic_jira_tool
settings:
$ref: imported.integrations.jira_main

Option 3: Inline everything (not recommended, verbose)

tools:
- name: generic_jira_tool
settings:
id: "9ab1ad26-07f1-4d1a-9b0b-33d33a9d2cde"
credential_type: Jira
# ... many more fields
`

Benefits:
- ✅ DRY Principle: Define once, use everywhere
- ✅ Easy Updates: Change integration/tool in one place
- ✅ Ultra Clean Config: From 15+ lines to 1 line per tool
- ✅ Type Safety: Integration/tool not found? Error at load time
- ✅ Reusability: Share tools across multiple assistants

Note: Integrations are created and managed in Codemie UI. The IaC config only references them by ID.

Basic Toolkit Structure:
`yaml
resources:
assistants:
- name: My Assistant
model: gpt-4o
toolkits:
- toolkit: Git # Toolkit name
label: ""
settings_config: true
is_external: false
tools:
- name: get_pr_changes
label: "Get PR Changes"
settings_config: false
`

MCP (Model Context Protocol) Servers:

In addition to toolkits, assistants can use MCP servers for external integrations. MCP servers use the same integration aliasing pattern as toolkits:

`yaml
imported:
integrations:
- alias: playwright_mcp
id: "4fdd1ece-700e-43e2-8750-31bb482c61f1"
credential_type: MCP

resources:
assistants:
- name: Browser Automation Assistant
prompt: ./system_prompts/browser-automation.prompt.md
description: "Assistant with browser automation via Playwright MCP"
model: gpt-4o
mcp_servers:
- name: Playwright MCP Server
description: "Playwright browser automation"
enabled: true
config:
url: https://your-mcp-server.example.com/playwright/
headers:
X-Api-Key: $API_KEY
settings:
$ref: imported.integrations.playwright_mcp
`

MCP Integration Aliasing:
- MCP integrations are defined once in imported.integrations
- MCP servers reference them via settings: { $ref: imported.integrations.alias }
- Same DRY pattern as toolkits - define once, use everywhere

> 🔧 For detailed MCP examples, see the MCP section in examples/toolkit-examples.yaml

$3

Workflows orchestrate multiple assistants to handle complex, multi-step tasks.

#### Workflow Configuration in codemie.yaml

`yaml
resources:
workflows:
- name: My Workflow # No ID needed (name-based management)
description: Workflow description
definition: ./workflows/my-workflow.yaml # Path to workflow definition file
mode: Sequential # Sequential or Autonomous
shared: true # Share with project members
`

Required fields:
- name - Unique workflow name (used as identifier)
- description - Workflow description
- definition - Path to workflow definition file
- mode - Execution mode: Sequential or Autonomous
- shared - Whether to share with project (typically true)

#### Workflow YAML Structure

Create a workflow definition file (e.g., workflows/my-workflow.yaml):

`yaml
assistants:
# Reference assistants by NAME (name-based approach)
- id: analyzer # Local ID for this workflow
assistant_name: Data Analysis Assistant # References assistant from codemie.yaml

- id: reviewer # Local ID
assistant_name: Code Reviewer # Another assistant reference

# Inline assistant (defined directly in workflow)
- id: parser
model: gpt-4o-mini
name: Data Parser
system_prompt: |
You are a data parser. Extract structured data from text.

states:
- id: first_step
assistant_id: analyzer # Uses local ID from assistants section
task: |
Analyze the following input: {{ user_input }}
output_schema: |
{
"analysis": "string",
"confidence": "number",
"recommendations": "array"
}
next:
state_id: second_step

- id: second_step
assistant_id: reviewer
task: |
Review the analysis: {{ analysis }}
Provide feedback on: {{ recommendations }}
output_schema: |
{
"feedback": "string",
"approved": "boolean"
}
next:
state_id: end
`

How assistant resolution works:
1. External assistants (with assistant_name):
- IaC looks up in state.json (for IaC-managed assistants)
- Falls back to imported.assistants (for platform-managed assistants)
- Resolves name → UUID during deployment
- Workflow YAML stays unchanged (portable!)

2. Inline assistants (with model and system_prompt):
- Defined directly in workflow
- No resolution needed
- Good for simple, workflow-specific assistants

Change detection:
- Workflow YAML checksum (workflowYamlChecksum) - Detects changes to workflow logic
- Metadata checksum (configChecksum) - Detects changes to name, description, mode

> 📚 For detailed workflow patterns, see examples/workflow-examples.yaml
> 📖 For best practices, see Workflow Configuration Documentation

$3

You can link datasources to assistants using the context field:

`yaml
resources:
datasources:
- name: my-repo
type: code
description: "My repository"
link: https://git.example.com/repo
branch: master
setting_id: $ref:imported.integrations.git_connection.id

assistants:
- name: My Assistant
prompt: ./system_prompts/assistant.prompt.md
description: "Assistant with datasources"
model: gpt-4o
context:
- context_type: code
name: my-repo # Reference datasource by name
`

How it works:
- Use context array to reference datasources by their name field
- Specify context_type matching datasource type (code, knowledge_base, etc.)
- During deployment, datasource names are resolved to platform IDs
- Datasources must be defined in config (resources or imported) for resolution to work

Example with imported datasources:

`yaml
imported:
datasources:
- id: b31ac927-37ec-4038-bdcc-98fab5d76ec1
name: Existing Jira KB
type: knowledge_base_jira

resources:
datasources:
- name: my-code-repo
type: code
description: "My repository"
link: https://git.example.com/repo
branch: master
setting_id: $ref:imported.integrations.git_connection.id

assistants:
- name: My Assistant
prompt: ./system_prompts/assistant.prompt.md
model: gpt-4o
context:
- context_type: code
name: my-code-repo # From resources (IaC-managed)
- context_type: knowledge_base
name: Existing Jira KB # From imported (platform-managed)
`

💡 Use imported datasources when:
- Datasource is shared across multiple teams
- You don't want to manage datasource lifecycle via IaC
- Datasource already exists and is maintained elsewhere

$3

To avoid repetition, define reusable datasource configurations in datasource_defaults and reference them using $ref:

`yaml
datasource_defaults:
code:
type: code
index_type: code
embeddings_model: ada-002
shared_with_project: true
branch: master
force_reindex: false

production_code:
type: code
index_type: summary
embeddings_model: text-embedding-3-large
shared_with_project: true
branch: main
force_reindex: false

jira:
type: knowledge_base_jira
embeddings_model: ada-002
shared_with_project: true
force_reindex: false

resources:
datasources:
# Explicit $ref - inherits ALL fields from code
- $ref: datasource_defaults.code
name: my-repo
description: My Git repository
link: https://git.example.com/repo
setting_id: $ref:imported.integrations.git_conn.id
# type, index_type, embeddings_model, branch, etc. from $ref!

# Override specific fields
- $ref: datasource_defaults.code
name: special-repo
description: Special repository
link: https://git.example.com/repo2
setting_id: $ref:imported.integrations.git_conn.id
branch: develop # ← Overrides "master" from defaults
embeddings_model: text-embedding-3-large # ← Override

# Different defaults template
- $ref: datasource_defaults.production_code
name: prod-repo
description: Production repository
link: https://git.example.com/prod
setting_id: $ref:imported.integrations.git_conn.id
# Uses production_code settings (summary index, large embeddings)

# Jira datasource
- $ref: datasource_defaults.jira
name: my-jira
description: Jira knowledge base
setting_id: $ref:imported.integrations.jira_conn.id
jql: project = MY
`

How $ref defaults work:
- Explicit reference: $ref: datasource_defaults.name at the start of datasource
- Merge strategy: { ...defaults, ...datasource } - datasource fields override defaults
- Multiple templates: Create different default sets for different use cases
- Minimal config: Only specify fields unique to each datasource (name, link, description)

Why $ref instead of type-based defaults?
1. Explicit - Clear where values come from
2. Flexible - Multiple default sets for same type (e.g., code vs production_code)
3. Reusable - Same $ref mechanism as integrations and tools
4. DRY - Avoid repeating same fields across 30+ datasources

Required fields (for CODE datasources):
- name - Unique datasource name
- type - Datasource type (determines which defaults to use)
- description - Description (typically repository info)
- link - Git repository URL
- branch - Git branch to index

Common fields (typically in defaults):
- index_type - Indexing type: code, summary, or chunk-summary
- embeddings_model - Model for embeddings (e.g., ada-002)
- summarization_model - LLM model for summarization (e.g., gpt-4o)
- shared_with_project - Share with project (default: true)
- setting_id - Integration reference (use $ref:imported.integrations.name.id)
- force_reindex - Force full reindex on deploy (default: false)

Force Reindex:
Set force_reindex: true to trigger a full reindex of the datasource on the next deployment, even if no configuration changes were detected. This is useful for:
- Updating the index with new commits from the repository
- Recovering from failed indexing
- Applying new embeddings model settings

After deployment, set it back to false to avoid unnecessary reindexing.

Note: Datasource creation starts background indexing. Check Codemie UI for indexing status.

> 📚 For detailed datasource examples, see examples/datasource-examples.yaml with all available fields, descriptions, and common patterns.

$3

Multiple assistants can share the same prompt file:

`yaml
assistants:
- name: Production Bot
prompt: system_prompts/shared.prompt.md
model: gpt-4o

- name: Development Bot (Copy)
prompt: system_prompts/shared.prompt.md # Same file
model: gpt-4o-mini
`

Use cases:
- ✅ Creating test/staging copies of production assistants
- ✅ A/B testing with different models but same prompt
- ✅ Team-specific variants with shared core logic
- ✅ Backup/rollback scenarios

🔄 Common Workflows

$3

1. Create prompt file:
`bash
touch system_prompts/my-new-assistant.prompt.md
`

2. Add to codemie.yaml:
`yaml
resources:
assistants:
- name: My New Assistant # Used as identifier (NO ID!)
prompt: ./system_prompts/my-new-assistant.prompt.md
description: "Description here"
model: gpt-4o
temperature: 0.7
shared: true
toolkits: []
context: []
`

3. Deploy:
`bash
npm run validate # Check slug conflicts (if slug provided)
npm run preview # Preview changes
npm run deploy # Create assistant
`

✨ After deploy:
- codemie.yaml remains unchanged (no ID added)
- .codemie/state.json is updated with name→ID mapping

$3

1. Edit the prompt file or settings in codemie.yaml
2. Run preview to see changes:
`bash
npm run preview
`
3. Deploy:
`bash
npm run deploy
`

$3

1. Create workflow YAML file:
`bash
touch workflows/my-workflow.yaml
`

2. Define workflow in workflows/my-workflow.yaml:
`yaml
assistants:
# Reference assistants by NAME (from codemie.yaml)
- id: step1
assistant_name: My Assistant
- id: step2
assistant_name: Another Assistant

states:
- id: first_step
assistant_id: step1
task: "Analyze: {{ user_input }}"
output_schema: '{ "result": "string" }'
next:
state_id: second_step
- id: second_step
assistant_id: step2
task: "Process: {{ result }}"
output_schema: '{ "final": "string" }'
next:
state_id: end
`

3. Add to codemie.yaml:
`yaml
resources:
workflows:
- name: My Workflow # No ID yet
description: "Workflow description"
definition: ./workflows/my-workflow.yaml
mode: Sequential
shared: true
`

4. Deploy:
`bash
npm run preview # Preview changes
npm run deploy # Create workflow
`

✨ After deploy:
- codemie.yaml remains unchanged (no ID added)
- .codemie/state.json is updated with name→ID mapping

Scenarios

This section covers 18 real-world scenarios you'll encounter when managing resources with IaC.

$3

| Scenario | What It Covers | Risk Level | Auto-Recovery |
|----------|---------------|------------|---------------|
| 1. Create New Assistant | Initial resource creation | ✅ Safe | N/A |
| 2. Update Assistant Prompt | Modify prompt content | ✅ Safe | N/A |
| 3. Update Assistant Config | Modify settings/toolkits | ✅ Safe | N/A |
| 4. Rename Assistant | Delete old + create new | ⚠️ Breaking | ❌ No |
| 5. Delete Assistant | Automatic cleanup | ⚠️ Destructive | ❌ No |
| 6. Sub-Assistants | Dependency management | ✅ Safe | N/A |
| 7. Workflow References | Name-based resolution | ✅ Safe | N/A |
| 8. Imported Assistant | External references | ✅ Safe | N/A |
| 9. Datasource Reference | Context linking | ✅ Safe | N/A |
| 10. Integration Reuse | $ref mechanism | ✅ Safe | N/A |
| 11. Manual Change | Drift detection | ⚠️ Overwrites | ✅ Auto-reverts |
| 12. State Deleted | Recovery options | 🔴 Critical | ❌ Manual fix |
| 13. Parallel Workflow | CI/CD protection | ✅ Safe | N/A |
| 14. Field Transformation | SDK compatibility | ✅ Safe | N/A |
| 15. Missing Prompt | Validation error | ✅ Safe | ❌ Manual fix |
| 16. Circular Dependency | Validation error | ✅ Safe | ❌ Manual fix |
| 17. Nested Sub-Assistants | Platform limitation | ✅ Safe | ❌ Manual fix |
| 18. Missing Env Var | Configuration error | ⚠️ Deploy fails | ❌ Manual fix |

$3

Config (codemie.yaml):
`yaml
resources:
assistants:
- name: Code Reviewer
prompt: system_prompts/code-reviewer.prompt.md
model: gpt-4o
description: Reviews code for best practices
`

What happens:
1. npm run validate - Checks prompt file exists
2. npm run preview - Shows "Create: 1 assistant"
3. npm run deploy:
- Creates assistant via SDK
- Gets UUID back from platform
- Calculates checksums for prompt and config
- Saves to state.json: "Code Reviewer": { id: "uuid", promptChecksum: "...", configChecksum: "..." }

$3

Change: Modify system_prompts/code-reviewer.prompt.md

What happens:
1. npm run preview - Detects prompt checksum changed
2. npm run deploy:
- Recalculates prompt checksum
- Compares with stored checksum → different
- Calls assistants.update(uuid, { ...config, system_prompt: newContent })
- Updates promptChecksum in state.json

$3

Change: Add toolkit to assistant in codemie.yaml

What happens:
1. npm run preview - Detects config checksum changed
2. npm run deploy:
- Recalculates config checksum (based on all fields except prompt path)
- Compares with stored checksum → different
- Calls assistants.update(uuid, newConfig)
- Updates configChecksum in state.json

$3

Change: name: Code Reviewer → name: Senior Code Reviewer

What happens:
1. npm run preview - Shows "Delete: Code Reviewer, Create: Senior Code Reviewer"
2. npm run deploy:
- Looks up "Senior Code Reviewer" in state.json → not found → treats as new resource
- Creates "Senior Code Reviewer" with new UUID
- Detects "Code Reviewer" is in state but not in config → orphaned
- If --prune is NOT set:
- Reports orphan but does NOT delete "Code Reviewer"
- State now has both (but "Code Reviewer" is still tracked as orphan)
- If --prune IS set:
- Deletes "Code Reviewer" from platform
- State now has only "Senior Code Reviewer"

Note: All references to old name break (e.g., in workflows). Update references before renaming.

$3

Change: Remove assistant from codemie.yaml

What happens:
1. npm run preview - Shows "Delete: 1 assistant"
2. npm run deploy:
- Detects assistant in state.json but not in config
- If --prune IS set:
- Deletes from platform using stored UUID
- Removes from state.json
- If --prune is NOT set:
- Warns about orphaned resource
- Assistant remains on platform and in state.json

$3

Config:
`yaml
resources:
assistants:
- name: Data Validator
prompt: system_prompts/validator.prompt.md
model: gpt-4o-mini

- name: Data Processor
prompt: system_prompts/processor.prompt.md
model: gpt-4o
sub_assistants:
- Data Validator # Name reference, not UUID
`

What happens:
1. npm run validate - Checks "Data Validator" exists in config
2. npm run deploy:
- Deploys assistants in order (Data Validator first, then Data Processor)
- When deploying Data Processor:
- Looks up "Data Validator" in state.json → gets UUID
- Adds UUID to assistant_ids array for API call
- Both assistants now in state.json

Dependency order: IaC automatically processes assistants in dependency order (sub-assistants before parents).

$3

Workflow YAML (workflows/my-workflow.yaml):
`yaml
assistants:
- id: reviewer
assistant_name: Code Reviewer # Name, not UUID

states:
- id: review
assistant_id: reviewer
task: Review the code
is_final: true
`

Config (codemie.yaml):
`yaml
resources:
workflows:
- name: Code Review Workflow
definition: workflows/my-workflow.yaml
mode: Sequential
`

What happens:
1. npm run deploy:
- Loads workflow YAML
- Finds assistant_name: Code Reviewer
- Looks up in state.json → gets UUID
- Replaces with assistant_id: uuid
- Sends modified YAML to API
- Stores workflow in state.json

$3

Config:
`yaml
imported:
assistants:
- id: external-assistant-uuid
name: External Tool

resources:
workflows:
- name: My Workflow
definition: workflows/workflow.yaml
`

Workflow YAML:
`yaml
assistants:
- id: step1
assistant_name: External Tool # References imported assistant
`

What happens:
1. npm run deploy:
- Looks up "External Tool" in state.json → not found
- Looks up in imported.assistants → found with UUID
- Uses that UUID for workflow
- Deploys workflow successfully

$3

Config:
`yaml
resources:
datasources:
- name: my-repo
type: code
link: https://git.example.com/repo
setting_id: $ref:imported.integrations.git_connection.id

assistants:
- name: Code Assistant
prompt: system_prompts/assistant.prompt.md
model: gpt-4o
context:
- context_type: code
name: my-repo # Datasource name reference
`

What happens:
1. npm run deploy:
- Deploys datasource first (dependency order)
- Deploys assistant with context pointing to datasource name
- Platform resolves datasource name to UUID internally

$3

Config:
`yaml
imported:
integrations:
- alias: jira_conn
id: jira-uuid
credential_type: Jira

resources:
datasources:
- name: jira-data
type: knowledge_base_jira
jql: project = MY
setting_id: $ref:imported.integrations.jira_conn # Reference 1

assistants:
- name: Jira Bot
toolkits:
- toolkit: jira
settings: $ref:imported.integrations.jira_conn # Reference 2
`

What happens:
- During config load, both $ref are resolved to same integration object
- Changes to jira_conn automatically apply to all references
- No ID duplication in config

$3

Situation: Someone manually edits assistant on platform (e.g., changes temperature)

What happens:
1. npm run preview - Compares config checksums with state
- Prompt unchanged → prompt checksum matches
- Config unchanged → config checksum matches
- Shows "Unchanged: 0, Update: 0"
2. Manual change NOT detected (by design)
3. Next npm run deploy with ANY config change:
- IaC pushes config version
- Manual change overwritten

Why? Config is source of truth. IaC doesn't detect drift, only manages config→platform flow.

$3

What happens:
1. npm run preview - Cannot find resources in state → treats all as new
- Shows "Create: 10 assistants" (even though they exist)
2. npm run deploy - Attempts to create all resources
- Platform rejects duplicates (if names conflict)
- Or creates new resources with same names (depending on platform)

Recovery:
1. Restore state.json from Git history: git checkout HEAD~1 -- .codemie/state.json
2. Or manually reconstruct state by fetching UUIDs from platform and building state.json

$3

Setup:
`yaml
deploy:
resource_group: production # KEY: Ensures sequential execution
`

What happens:
1. Developer A merges PR → triggers pipeline A
2. Developer B merges PR 10 seconds later → triggers pipeline B
3. GitLab sees resource_group: production:
- Pipeline B waits for pipeline A to complete
- No concurrent access to state.json
- No race conditions

$3

Config (what you write):
`yaml
datasources:
- name: my-repo
type: code
link: https://git.example.com/repo # Config uses 'link'
setting_id: $ref:... # Config uses 'setting_id'
`

What IaC does internally:
- Reads link and setting_id from config
- API call unchanged (uses same fields)
- Backward compatibility: Also accepts repository_url → auto-converts to link

Why? Config field names match SDK/API expectations for consistency.

$3

Config:
`yaml
assistants:
- name: My Bot
prompt: system_prompts/missing.prompt.md # File doesn't exist
`

What happens:
1. npm run validate - Checks file existence → fails
`
Error: Prompt file not found: system_prompts/missing.prompt.md (referenced by assistant: My Bot)
`
2. Deployment blocked until file created

$3

Config:
`yaml
assistants:
- name: Assistant A
sub_assistants: [Assistant B]
- name: Assistant B
sub_assistants: [Assistant A] # Circular!
`

What happens:
1. npm run validate - DFS cycle detection → fails
`
Error: Cyclic dependency detected: Assistant A → Assistant B → Assistant A
`
2. Deployment blocked until cycle removed

$3

Config:
`yaml
assistants:
- name: Helper
sub_assistants: [Specialist] # Helper has sub-assistant
- name: Main
sub_assistants: [Helper] # Main uses Helper (which has sub-assistant)
`

What happens:
1. npm run validate - Detects nested sub-assistants → fails
`
Error: Assistant "Helper" has sub-assistants but is itself used as a sub-assistant by: Main.
Nested sub-assistants are not allowed.
`
2. Flatten hierarchy: Main should directly reference both Helper and Specialist

$3

Config:
`yaml
environment:
codemie_api_url: ${CODEMIE_API_URL}
`

What happens if CODEMIE_API_URL not set:
1. npm run validate - Env var substitution → empty string
2. Connection fails with unclear error
3. Best practice: Check required env vars at script start

🗄️ Backup & Restore

$3

The backup tool creates a complete snapshot of ALL resources in your Codemie instance:

`bash
npm run backup
`

What gets backed up:
- ✅ All Assistants - Including prompts, toolkits, context, MCP servers, sub-assistants
- ✅ All Datasources - CODE, Confluence, Jira, Google Docs with full configuration
- ✅ All Workflows - YAML definitions, mode, and metadata
- ✅ All Integrations - Project integrations (IDs and configuration)
- ✅ Complete State - Full state.json with checksums for all resources

Transaction Safety:
- Atomic backup process with rollback on failure
- Resume capability - if backup is interrupted, rerunning continues from last checkpoint
- Temporary directory used during backup (.temp-*) - moved to final location only on success
- Progress tracking with transaction.json checkpoint file

Output structure:
`
backups/
└── 2025-10-22T14-30-45/ # Timestamp-based directory
├── backup.json # Complete backup with all data
├── state.json # State file (ready for IaC)
├── codemie.yaml # Reconstructed IaC config
├── system_prompts/ # Individual prompt files
│ ├── assistant-1.prompt.md
│ └── assistant-2.prompt.md
├── workflows/ # Individual workflow files
│ ├── workflow-1.yaml
│ └── workflow-2.yaml
└── openapi_specs/ # OpenAPI specifications (if any)
├── sumo-logic-api.yaml
├── gitlab-api.yaml
└── coda-api.yaml
`

$3

1. backup.json - Complete resource data
- Full details of all assistants, datasources, workflows, and integrations
- Used for selective restore or manual recovery

2. state.json - IaC state file
- Resource name → UUID mappings
- Checksums for change detection
- Ready to use with npm run deploy

3. codemie.yaml - Reconstructed IaC configuration
- Converts backup into IaC format
- References individual prompt/workflow files
- Includes all integrations in imported section
- MCP servers use integration aliasing (settings: { $ref: imported.integrations.alias })

4. system_prompts/ - Individual prompt files
- Each assistant's prompt as separate .prompt.md file

5. workflows/ - Individual workflow definitions
- Each workflow as separate .yaml` file

6. openapi_specs/ - OpenAPI specifications (if any)
- Extracted from integrations and