### Setup Baton-DX for Development

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Clones the repository and builds the project locally for development purposes. Requires Bun to be installed.

```bash
git clone https://github.com/baton-dx/baton-dx.git
cd baton-dx
bun install
bun run build
bun link --cwd packages/cli
```

--------------------------------

### Perform First-Time Setup and Configuration

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Scans the local environment for AI tools and IDEs, and registers team source repositories for project reuse.

```bash
baton ai-tools scan
baton ides scan
baton source connect github:your-org/dx-configs --name my-team
```

--------------------------------

### Verify Baton-DX Installation

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Checks the installed version of Baton-DX and displays the help menu to confirm the CLI is correctly configured.

```bash
baton --version
baton --help
```

--------------------------------

### Run Baton-DX without Installation

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Executes the Baton-DX initialization command directly using npx or bunx without requiring a global installation.

```bash
npx @baton-dx/cli init
bunx @baton-dx/cli init
```

--------------------------------

### Install Baton CLI

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/02-quickstart.md

Installs the Baton CLI globally on your system using either the Bun package manager or Homebrew. This is the prerequisite step for all other Baton commands.

```bash
bun install -g @baton-dx/cli
# or: brew install baton-dx
```

--------------------------------

### Setup Baton DX Project

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/11-contributing.md

Commands to clone the Baton DX repository, install dependencies using Bun, build all packages, and link the CLI globally for testing.

```bash
git clone https://github.com/baton-dx/baton-dx.git
cd baton-dx
bun install
bun run build
bun link --cwd packages/cli
baton --version
```

--------------------------------

### Connect and Initialize Baton Sources

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/02-quickstart.md

Registers a remote source repository for configuration profiles or initializes the project with a specific AI-assisted profile. These commands establish the connection between your project and the Baton configuration ecosystem.

```bash
baton source connect github:your-org/dx-configs --name my-team
baton init --profile github:baton-dx/baton-dx-source/consumer
```

--------------------------------

### Baton Complete Workflow Example

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Provides a step-by-step example of a complete Baton workflow, from creating a new source repository to defining profiles, adding content, and validating the source. This demonstrates the end-to-end process of setting up and managing configurations with Baton.

```bash
# 1. Create a new source repository
baton source create my-team-configs
cd my-team-configs

# 2. Create profiles
baton profile create frontend
baton profile create backend

# 3. Edit baton.source.yaml to register profiles
cat > baton.source.yaml << 'EOF'
name: my-team-configs
version: 1.0.0
description: Team DX standards
profiles:
  - name: frontend
    path: profiles/frontend
  - name: backend
    path: profiles/backend
EOF

# 4. Add content to profiles (rules, skills, memory, etc.)
mkdir -p profiles/frontend/ai/rules
echo "# Coding Standards" > profiles/frontend/ai/rules/coding-style.md

# 5. Validate the source
baton source validate

```

--------------------------------

### Initialize Baton Project (CLI)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/05-using-profiles.md

Initializes a new Baton project, creating a baton.yaml manifest and guiding the user through selecting sources and profiles. Supports interactive setup or direct option passing.

```bash
baton init

```

```bash
baton init \
  --target claude-code \
  --target cursor \
  --profile github:my-org/dx-configs/frontend

```

--------------------------------

### Install Baton-DX via Package Managers

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Installs the Baton-DX CLI globally using common Node.js package managers. Bun is the recommended package manager.

```bash
bun install -g @baton-dx/cli
npm install -g @baton-dx/cli
pnpm install -g @baton-dx/cli
yarn global add @baton-dx/cli
```

--------------------------------

### Initialize and Sync Baton Project

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/02-quickstart.md

Initializes the project directory with a baton.yaml file and performs the synchronization of configurations. The sync process resolves profiles, merges settings, and generates the necessary files for IDEs and AI tools.

```bash
cd your-project
baton init
baton sync
```

--------------------------------

### Install Baton DX CLI

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Instructions for installing the Baton DX CLI globally using Homebrew, bun, or npm. Includes verification commands.

```bash
# Install via Homebrew (macOS/Linux)
brew tap baton-dx/baton-dx https://github.com/baton-dx/baton-dx
brew install baton-dx

# Install via bun (recommended)
bun install -g @baton-dx/cli

# Install via npm
npm install -g @baton-dx/cli

# Run without installing
npx @baton-dx/cli init
bunx @baton-dx/cli init

# Verify installation
baton --version
baton --help
```

--------------------------------

### Baton Multi-Profile Layering Example

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/05-using-profiles.md

Shows an example of how multiple profiles are layered in Baton based on weight and order in baton.yaml, illustrating the merge order and conflict resolution principles.

```yaml
profiles:
  - source: github:my-org/dx-configs/base       # weight: 0
  - source: github:my-org/dx-configs/frontend    # weight: 10
  - source: github:my-org/dx-configs/strict      # weight: 100

```

--------------------------------

### Install Baton-DX via Homebrew

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/01-installation.md

Installs the Baton-DX CLI using the Homebrew package manager on macOS or Linux. This is the recommended method for end users.

```bash
brew tap baton-dx/baton-dx https://github.com/baton-dx/baton-dx
brew install baton-dx
```

--------------------------------

### Example AI Agent Definition

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

An example of an AI agent configuration file (`.md`) with YAML frontmatter, defining its name, description, targeted tools, and specific instructions.

```markdown
---
name: reviewer
description: Code review specialist
tools: [claude-code, cursor]
---

You are a code review specialist. Focus on:
- Code quality and readability
- Performance implications
- Security vulnerabilities
- Test coverage
```

--------------------------------

### Initialize Baton Project

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands to initialize Baton DX in a project, including interactive setup, specifying profiles and targets, and non-interactive or force options.

```bash
# Interactive initialization
baton init

# Initialize with a specific profile from a source
baton init --profile github:my-org/dx-configs/frontend

# Initialize targeting specific AI tools
baton init --target claude-code --target cursor --profile github:my-org/dx-configs/frontend

# Non-interactive initialization (accept defaults)
baton init --yes

# Overwrite existing baton.yaml
baton init --force
```

--------------------------------

### Profile Manifest Example (`baton.profile.yaml`)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

A comprehensive example of a `baton.profile.yaml` file, demonstrating the configuration of AI tools, skills, rules, memory, agents, file placements, IDE settings, and variables. This manifest defines the scope and behavior of a 'frontend' profile.

```yaml
name: frontend
version: 1.0.0
description: Frontend development standards
extends:
  - ../base
weight: 10
ai:
  tools: [claude-code, cursor, windsurf]
  skills:
    - name: code-review
      scope: project
    - name: refactor
      scope: project
  rules:
    - name: coding-style
      scope: project
  memory:
    - source: MEMORY.md
      merge: append
  agents:
    - name: reviewer
      scope: project
  mcp:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
      env:
        ROOT_DIR: "${HOME}"
      scope: project
    - name: github
      transport: http
      url: https://api.githubcopilot.com/mcp/
      scope: global
files:
  - source: files/.editorconfig
    target: .editorconfig
    merge: replace
  - source: files/biome.json
    target: biome.json
    merge: deep
ide:
  vscode:
    settings: ide/vscode/settings.json
    extensions: ide/vscode/extensions.json
variables:
  project_type: frontend
  framework: react

```

--------------------------------

### Create a Baton Source Repository (CLI)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

Scaffolds a new Baton source repository with a manifest and example profile. Supports adding descriptions and multiple profiles during creation.

```bash
baton source create my-team-configs
```

```bash
baton source create my-team-configs \
  --description "Team DX standards" \
  --profile frontend \
  --profile backend
```

--------------------------------

### Define VS Code settings and extensions

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/09-ide-platforms-reference.md

Examples of standard VS Code configuration files for editor behavior and extension recommendations. These files are deployed to the project's .vscode directory during synchronization.

```json
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "biomejs.biome",
  "typescript.preferences.importModuleSpecifier": "relative"
}
```

```json
{
  "recommendations": [
    "biomejs.biome",
    "dbaeumer.vscode-eslint"
  ]
}
```

--------------------------------

### Publish Baton Source to npm (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

These bash commands guide the process of packaging and publishing a Baton source to npm. It includes initializing an npm package with a specific scope and then publishing it.

```bash
npm init --scope=@my-org
npm publish
```

--------------------------------

### Initialize and Sync Baton Consumer Profile

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/05-using-profiles.md

Initializes the Baton consumer profile from the official source repository and synchronizes the project configuration. This setup provides AI tools with the necessary context for Baton CLI commands like init, sync, apply, and diff.

```bash
baton init --profile github:baton-dx/baton-dx-source/consumer
baton sync
```

--------------------------------

### Baton Source Manifest (`baton.source.yaml`) Example

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

Defines the metadata for a Baton source repository, including its name, version, description, repository URI, and the profiles it provides.

```yaml
name: my-team-configs
version: 1.0.0
description: Team DX standards
repository: github:my-org/dx-configs
profiles:
  - name: frontend
    path: profiles/frontend
  - name: backend
    path: profiles/backend
```

--------------------------------

### IDE Management

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands for scanning and listing installed IDE platforms.

```APIDOC
## baton ides scan

Detect installed IDE platforms.

### Method
GET

### Endpoint
/baton/ides/scan

### Description
Scans the system for installed IDE platforms.

### Parameters
#### Query Parameters
- **yes** (boolean) - Optional - Non-interactive scan.

### Request Example
```bash
baton ides scan --yes
```

## baton ides list

List configured IDE platforms.

### Method
GET

### Endpoint
/baton/ides/list

### Description
Lists the IDE platforms that are currently configured.

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - Show all supported platforms.
- **json** (boolean) - Optional - Output as JSON.

### Request Example
```bash
baton ides list --all --json
```
```

--------------------------------

### Commit and Share Baton Configuration

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/02-quickstart.md

Commits the generated configuration files to version control so that teammates can synchronize the same project settings. Teammates use the sync command to apply the shared configuration.

```bash
git add baton.yaml baton.lock
git commit -m "feat: add Baton configuration"
# Teammates run:
baton sync
```

--------------------------------

### Initialize Baton Project

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/06-cli-reference.md

Initializes Baton in a project, guiding the user through an interactive wizard to detect AI tools and IDEs, select sources and profiles, and create the `baton.yaml` configuration file. It supports specifying a profile source directly and running in non-interactive mode.

```bash
baton init
baton init --profile github:org/repo/profile-name
baton init --yes
baton init --force
```

--------------------------------

### Markdown File Inclusion Examples (`baton:include`)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

Demonstrates various ways to include external files using the `baton:include` directive in Markdown. It shows different modes like `inline`, `link`, and `reference`, along with optional attributes such as `hint` and `optional`.

```markdown
<!-- baton:include src="PROJECT.md" -->
<!-- baton:include src="docs/api.md" mode="inline" -->
<!-- baton:include src="docs/api.md" mode="link" -->
<!-- baton:include src="docs/api.md" mode="link" hint="API Docs: {{file}}" -->
<!-- baton:include src="docs/api.md" mode="reference" -->
<!-- baton:include src="docs/api.md" mode="reference" hint="Read {{file}} for details" -->
<!-- baton:include src="docs/OPTIONAL.md" optional="true" -->
```

--------------------------------

### YAML Hooks for Sync Lifecycle Commands

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

Shows how to define shell commands to be executed at specific points during the Baton DX sync process using the `hooks` configuration in YAML. It includes examples for `pre-sync` and `post-sync` hooks.

```yaml
hooks:
  pre-sync:
    - echo "Starting sync..."
    - npm run clean
  post-sync:
    - echo "Sync complete!"
    - npm install
```

--------------------------------

### AI Tools Management

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands for scanning and listing installed AI tools.

```APIDOC
## baton ai-tools scan

Detect installed AI tools on the system by checking for CLI binaries and config directories.

### Method
GET

### Endpoint
/baton/ai-tools/scan

### Description
Scans the system for installed AI tools.

### Parameters
#### Query Parameters
- **yes** (boolean) - Optional - Non-interactive scan.

### Request Example
```bash
baton ai-tools scan --yes
```

## baton ai-tools list

List configured AI tools.

### Method
GET

### Endpoint
/baton/ai-tools/list

### Description
Lists the AI tools that are currently configured.

### Parameters
#### Query Parameters
- **all** (boolean) - Optional - Show all 14 supported tools.
- **json** (boolean) - Optional - Output as JSON.

### Request Example
```bash
baton ai-tools list --all --json
```
```

--------------------------------

### Scan and List AI Tools with Baton CLI

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands to detect installed AI tools on the system and list currently configured tools. Supports interactive and non-interactive modes, as well as JSON output for programmatic integration.

```bash
# Scan and interactively save detected tools
baton ai-tools scan

# Non-interactive scan
baton ai-tools scan --yes

# List configured tools
baton ai-tools list

# Show all 14 supported tools
baton ai-tools list --all

# Output as JSON
baton ai-tools list --json
```

--------------------------------

### Initialize and Sync with Creator Profile (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This bash command sequence initializes a new Baton DX source using the 'creator' profile from a specified repository. It then synchronizes the project, providing AI tools with context about profile schemas, merge strategies, transformations, and publishing.

```bash
baton init --profile github:baton-dx/baton-dx-source/creator
baton sync
```

--------------------------------

### Initialize Git Repository and Push to GitHub (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This sequence of bash commands initializes a new Git repository, stages all files, creates an initial commit, adds a remote origin pointing to a GitHub repository, and pushes the code to the main branch. This is a standard workflow for publishing Baton sources via GitHub.

```bash
git init
git add .
git commit -m "feat: initial source release"
git remote add origin git@github.com:my-org/dx-configs.git
git push -u origin main
```

--------------------------------

### Baton DX Conventional Commits

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/11-contributing.md

Examples of commit messages following the Conventional Commits specification for the Baton DX project. Includes examples for features, fixes, refactors, docs, and tests.

```bash
git commit -m "feat(cli): add profile wizard"
git commit -m "fix(core): handle empty manifest"
git commit -m "refactor(ai-tool-paths): simplify registry lookup"
git commit -m "docs: update CLI reference"
git commit -m "test(core): add cursor adapter tests"
```

--------------------------------

### Create New Profile Manifest (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This command creates an empty `baton.profile.yaml` file, which serves as the manifest for a new Baton profile. This file is essential for defining the profile's configuration.

```bash
touch profiles/my-new-profile/baton.profile.yaml
```

--------------------------------

### Development CLI Alias for Baton DX

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/11-contributing.md

Shell alias to run a local build of the Baton DX CLI without overwriting the installed version. This is useful for testing local changes.

```bash
# Add to your ~/.zshrc or ~/.bashrc
baton-dev() {
  node /path/to/baton-dx/packages/cli/dist/index.mjs "$@"
}
```

--------------------------------

### Manage Authentication and Configuration Settings

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Utilities for diagnosing repository authentication and managing global configuration settings. Provides commands to inspect status, list settings, and get/set specific configuration values.

```bash
# Check auth for GitHub
baton auth status

# Check auth for specific hostname
baton auth status --hostname gitlab.example.com

# Show dashboard
baton config

# List all settings
baton config list

# Get a setting value
baton config get default-scope

# Set a setting value
baton config set default-scope global
baton config set symlink-mode true
```

--------------------------------

### Create Baton Source Repository

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Scaffolds a new source repository for Baton DX profiles, with options for description and initial profiles, and non-interactive creation.

```bash
# Create a new source repository
baton source create my-team-configs

# Create with description and initial profiles
baton source create my-team-configs \
  --description "Team DX standards" \
  --profile frontend \
  --profile backend

# Non-interactive creation
baton source create my-team-configs --yes
```

--------------------------------

### Manage Baton Project Interactively

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Launches an interactive wizard for project management, offering options like overview, adding/removing profiles, and removing Baton.

```bash
# Launch interactive management wizard
baton manage

# Options available:
# - Overview: Show project status and resolved tool preferences
# - Add Profile: Add a new profile from a source
# - Remove Profile: Remove an installed profile
# - Remove Baton: Remove Baton from the project
```

--------------------------------

### Configure Baton Settings

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/06-cli-reference.md

Displays the Baton dashboard overview or allows configuration of settings. Users can list all settings, get a specific setting's value, or set a new value for a setting. Key settings include `default-scope` and `symlink-mode`.

```bash
baton config
baton config list
baton config get <key>
baton config set <key> <value>
```

--------------------------------

### Scan and List IDE Platforms with Baton CLI

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands to detect and manage IDE platform configurations. Allows for scanning the local environment and listing supported IDEs with optional JSON formatting.

```bash
# Scan and save IDE platforms
baton ides scan

# Non-interactive scan
baton ides scan --yes

# List configured IDEs
baton ides list

# Show all supported platforms
baton ides list --all

# Output as JSON
baton ides list --json
```

--------------------------------

### Create New Profile Directory Structure (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This command creates the necessary nested directories for a new Baton profile, including subdirectories for AI components (skills, rules, agents, memory, commands) and general profile assets (files, ide).

```bash
mkdir -p profiles/my-new-profile/ai/{skills,rules,agents,memory,commands}
mkdir -p profiles/my-new-profile/{files,ide}
```

--------------------------------

### Sync Project Configurations

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/06-cli-reference.md

Fetches the latest versions of all sources, merges, transforms, and places configurations into the project. This command always fetches fresh data and does not use cached versions. It supports filtering by category, performing a read-only stale check, and running non-interactively.

```bash
baton sync
baton sync --dry-run
baton sync --verbose
baton sync --category ai
baton sync --check
baton sync --yes
```

--------------------------------

### Reference Local File Source (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML configuration demonstrates how to reference a Baton source located on the local filesystem. This is particularly useful for development and testing purposes.

```yaml
source: file:../dx-configs/frontend
```

--------------------------------

### Register New Profile in Source Manifest (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML snippet demonstrates how to register a newly created profile by adding its name and path to the `profiles` list within the `baton.source.yaml` file. This makes the profile available for use.

```yaml
profiles:
  - name: frontend
    path: profiles/frontend
  - name: backend
    path: profiles/backend
  - name: my-new-profile           # add this
    path: profiles/my-new-profile  # add this
```

--------------------------------

### List Baton Sources

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Lists all registered global sources, displaying their names, URLs, and default status.

```bash
baton source list
```

--------------------------------

### Create Baton Profile

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Creates a new profile within the current source repository. Requires being in a directory with `baton.source.yaml`.

```bash
# Must be run inside a directory containing baton.source.yaml
cd my-source-repo
baton profile create frontend
```

--------------------------------

### Baton Profile Source References

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/05-using-profiles.md

Illustrates different ways to reference profile sources within the baton.yaml file, including different transports (github, npm, file) and optional version pinning.

```yaml
profiles:
  - source: github:my-org/dx-configs/frontend
  - source: npm:@my-org/dx-configs/backend
  - source: file:../local-configs/experimental

```

```yaml
profiles:
  - source: github:my-org/dx-configs@v1.2.0/frontend

```

--------------------------------

### Reference GitLab Source (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

Similar to the GitHub reference, this YAML configuration demonstrates how consumers can reference a Baton source hosted on GitLab, using the `gitlab:` prefix.

```yaml
source: gitlab:my-org/dx-configs/frontend
```

--------------------------------

### AI Rules Placement (Universal vs. Tool-Specific)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

Demonstrates how AI rules are organized within the `ai/rules/` directory. Universal rules apply to all AI tools, while tool-specific rules are placed in subdirectories named after the respective tools.

```tree
ai/rules/
├── coding-style.md            # applied to all tools
├── testing.md                 # applied to all tools
├── cursor/
│   └── react-patterns.md     # only applied to Cursor
└── claude-code/
    └── project-context.md    # only applied to Claude Code

```

--------------------------------

### Reference Git Tagged Source (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML configuration illustrates how consumers can reference a specific version of a Baton source hosted on GitHub by appending the Git tag (e.g., `@v1.2.0`) to the source path.

```yaml
source: github:my-org/dx-configs@v1.2.0/frontend
```

--------------------------------

### Baton File Merge Strategies

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Demonstrates various merge strategies for synchronizing files using Baton. Strategies include 'replace', 'deep', 'append', 'prepend', 'skip', 'prompt', 'directory', and 'import', each defining how source content interacts with target files.

```yaml
files:
  # replace - Target completely replaced with source
  - source: files/.editorconfig
    target: .editorconfig
    merge: replace

  # deep - JSON/YAML objects deep-merged
  - source: files/biome.json
    target: biome.json
    merge: deep

  # append - Source content appended to end
  - source: files/.gitignore
    target: .gitignore
    merge: append

  # prepend - Source content prepended to start
  - source: files/header.md
    target: README.md
    merge: prepend

  # skip - Only write if target doesn't exist
  - source: files/.env.example
    target: .env.example
    merge: skip

  # prompt - Ask user interactively
  - source: files/tsconfig.json
    target: tsconfig.json
    merge: prompt

  # directory - Directory-level merge
  - source: files/templates/
    target: templates/
    merge: directory

  # import - Add @import reference line
  - source: files/theme.css
    target: styles/main.css
    merge: import
```

--------------------------------

### Connect Baton Source Repository

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Registers a source repository globally for reuse across projects, supporting GitHub, GitLab, local file paths, and generic Git URLs.

```bash
# Connect a GitHub source
baton source connect github:my-org/dx-configs --name my-team

# Connect a GitLab source
baton source connect gitlab:my-org/dx-configs --name my-team

# Connect a local source
baton source connect file:///path/to/local/source --name local

# Connect any Git URL
baton source connect git:https://git.internal.co/dx-configs --name internal
```

--------------------------------

### Project Manifest (baton.yaml)

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Defines the project-level configuration file.

```APIDOC
## Project Manifest (baton.yaml)

The project-level configuration file created by `baton init` that declares profiles, AI tool targets, variables, and overrides.

### Structure
```yaml
# baton.yaml - Project manifest
profiles:
  - source: github:my-org/dx-configs/frontend
  - source: github:my-org/dx-configs/backend
    version: 1.0.0  # Optional: pin to specific version

ai:
  targets:  # Limit which AI tools to configure
    - claude-code
    - cursor
    - windsurf

variables:  # Template variables for substitution
  project_name: My App
  team_email: dev@acme.com

overrides:
  files:
    .gitignore:
      merge: skip
    biome.json:
      merge: deep

extras:
  scripts:
    - name: setup
      command: bun install
```
```

--------------------------------

### Reference GitHub Source (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML configuration shows how consumers can reference a Baton source hosted on GitHub. It specifies the repository and a specific profile within that repository.

```yaml
source: github:my-org/dx-configs/frontend
```

--------------------------------

### Tag Git Repository for Versioning (Bash)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This bash command sequence tags the current commit with a version number (prefixed with 'v') and pushes the tag to the remote repository. This allows consumers to pin to specific versions of the source.

```bash
git tag v1.2.0
git push origin v1.2.0
```

--------------------------------

### Configure Prepend Merge Strategy

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/10-merge-strategies.md

The prepend strategy inserts source content at the beginning of the target file, useful for headers or documentation prefixes.

```yaml
files:
  - source: files/header.md
    target: README.md
    merge: prepend
```

--------------------------------

### Reference npm Source (YAML)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML configuration shows how consumers can reference a Baton source published to npm, specifying the npm scope and package name, followed by the profile.

```yaml
source: npm:@my-org/dx-configs/frontend
```

--------------------------------

### Running Baton DX from Source

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/11-contributing.md

Command to run the Baton DX CLI directly from source without needing to build the packages first. Useful for quick testing during development.

```bash
bun run dev -- sync
```

--------------------------------

### Profile Manifest (baton.profile.yaml)

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Defines a profile's contents including AI configurations, file placements, and IDE settings.

```APIDOC
## Profile Manifest (baton.profile.yaml)

Defines a profile's contents including AI configurations, file placements, and IDE settings.

### Structure
```yaml
# baton.profile.yaml - Profile manifest
name: frontend
version: 1.0.0
description: Frontend development standards

extends:
  - ../base  # Inherit from parent profile

weight: 10  # Priority ordering (higher = applied later)

ai:
  tools: [claude-code, cursor, windsurf]

  skills:
    - name: code-review
      scope: project
    - name: refactor
      scope: project

  rules:
    - name: coding-style
      scope: project
    - name: testing
      scope: global

  agents:
    - name: reviewer
      scope: project

  memory:
    - source: MEMORY.md
      merge: append

  commands:
    - name: deploy
      scope: project

  mcp:
    - name: filesystem
      transport: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-filesystem"]
      env:
        ROOT_DIR: "${HOME}"
      scope: project
    - name: github-mcp
      transport: http
      url: https://api.githubcopilot.com/mcp/
      scope: global

files:
  - source: files/.editorconfig
    target: .editorconfig
    merge: replace
  - source: files/biome.json
    target: biome.json
    merge: deep
  - source: files/.gitignore
    target: .gitignore
    merge: append

ide:
  vscode:
    settings: ide/vscode/settings.json
    extensions: ide/vscode/extensions.json

variables:
  project_type: frontend
  framework: react

hooks:
  pre-sync:
    - echo "Starting sync..."
  post-sync:
    - npm install
```
```

--------------------------------

### Configure IDE settings in baton.profile.yaml

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/09-ide-platforms-reference.md

Defines how to map local configuration files to specific IDEs within a Baton profile manifest. The paths provided are relative to the profile directory.

```yaml
ide:
  vscode:
    settings: ide/vscode/settings.json
    extensions: ide/vscode/extensions.json
  jetbrains:
    settings: ide/jetbrains/settings.xml
```

--------------------------------

### Sync Baton Configurations

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Commands for syncing configurations, including dry runs, verbose output, filtering by category, checking for staleness, and non-interactive sync.

```bash
# Sync all configurations
baton sync

# Preview changes without writing files
baton sync --dry-run

# Show detailed per-file report
baton sync --verbose

# Filter by category (ai, files, or ide)
baton sync --category ai

# Check if configurations are stale (useful for CI)
baton sync --check && echo "In sync" || echo "Run baton sync to update"

# Non-interactive sync
baton sync --yes
```

--------------------------------

### Generate Vitest Test Suite Template for TypeScript

Source: https://github.com/baton-dx/baton-dx/blob/main/test-fixtures/skills/test-gen/SKILL.md

A standardized template for creating unit tests in TypeScript using the Vitest framework. It demonstrates how to structure describe blocks, standard test cases, edge case handling, and error verification.

```typescript
import { describe, it, expect } from 'vitest';
import { functionToTest } from './module';

describe('functionToTest', () => {
  it('should handle valid input', () => {
    const result = functionToTest('valid');
    expect(result).toBe('expected');
  });

  it('should handle edge case: empty input', () => {
    const result = functionToTest('');
    expect(result).toBe('default');
  });

  it('should throw error for invalid input', () => {
    expect(() => functionToTest(null)).toThrow();
  });
});
```

--------------------------------

### Baton Source Directory Layout Convention

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

Illustrates a conventional directory structure for a Baton source repository, emphasizing the placement of the manifest and profile directories.

```tree
my-team-configs/
├── baton.source.yaml
├── profiles/
│   ├── frontend/
│   │   ├── baton.profile.yaml
│   │   ├── ai/
│   │   │   ├── skills/
│   │   │   │   └── code-review/
│   │   │   │       └── SKILL.md
│   │   │   ├── rules/
│   │   │   │   ├── coding-style.md
│   │   │   │   └── testing.md
│   │   │   ├── agents/
│   │   │   │   └── reviewer.md
│   │   │   ├── memory/
│   │   │   │   └── MEMORY.md
│   │   │   └── commands/
│   │   │       └── deploy.md
│   │   ├── files/
│   │   │   ├── .editorconfig
│   │   │   └── biome.json
│   │   └── ide/
│   │       └── vscode/
│   │           ├── settings.json
│   │           └── extensions.json
│   └── backend/
│       ├── baton.profile.yaml
│       ├── ai/
│       │   ├── skills/
│       │   ├── rules/
│       │   ├── agents/
│       │   ├── memory/
│       │   └── commands/
│       ├── files/
│       └── ide/
└── README.md
```

--------------------------------

### Baton Source YAML Configuration

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/03-creating-sources.md

This YAML snippet defines the basic configuration for a Baton DX source, including its name, version, and a list of available profiles. Profiles specify paths to their respective configurations.

```yaml
name: baton-dx-source
version: 0.1.0
profiles:
  - name: base
    path: profiles/base
  - name: maintainer
    path: profiles/maintainer
  - name: creator
    path: profiles/creator
  - name: consumer
    path: profiles/consumer
```

--------------------------------

### List Baton Profiles

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Lists available profiles in the current source repository or project.

```bash
baton profile list
```

--------------------------------

### Add Profile to Existing Baton Project (CLI)

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/05-using-profiles.md

Demonstrates how to add a new profile to an existing Baton project using the CLI command `baton add`. This updates the baton.yaml and syncs the configurations.

```bash
baton add github:my-org/dx-configs/backend

```

--------------------------------

### Configure IDE Settings and Extensions

Source: https://github.com/baton-dx/baton-dx/blob/main/docs/04-creating-profiles.md

Defines editor-specific configuration paths for IDEs like VS Code. This allows for centralized management of settings and extension lists across projects.

```yaml
ide:
  vscode:
    settings: ide/vscode/settings.json
    extensions: ide/vscode/extensions.json
```

--------------------------------

### Source Manifest (baton.source.yaml)

Source: https://context7.com/baton-dx/baton-dx/llms.txt

Defines a source repository at its root, declaring profiles it provides.

```APIDOC
## Source Manifest (baton.source.yaml)

Defines a source repository at its root, declaring profiles it provides.

### Structure
```yaml
# baton.source.yaml - Source manifest
name: my-team-configs
version: 1.0.0
description: Team DX standards
repository: github:my-org/dx-configs

profiles:
  - name: base
    path: profiles/base
  - name: frontend
    path: profiles/frontend
    description: Frontend development
  - name: backend
    path: profiles/backend
    description: Backend API development

metadata:
  author: ACME Corp
  license: MIT
```
```