Introduction

One .ai/ folder. All your AI tools. Always in sync. Always in context.

AI coding tools each expect their own config directory — .claude/, .gemini/, .github/, .agents/. dotai creates a single .ai/ directory as your source of truth and symlinks everything to where each tool expects it.

Edit one file. Every tool stays in sync.

The Problem

Without dotai, you juggle separate files for every tool:

CLAUDE.md              # Claude Code reads this
GEMINI.md              # Gemini CLI reads this
.github/copilot-instructions.md  # Copilot reads this
.gemini/rules/         # Antigravity reads this

The Solution

With dotai, all of the above is one file:

.ai/AI.md  →  symlinked to all of the above

One file to write. Four tools that read it. Zero drift.

What's New in v3.1.0

dotai v3.1.0 adds 5 new command groups for managing every aspect of your AI tool configuration from the CLI — MCP servers, skills, rules, slash commands, and config settings. Plus the SDD Toolkit from v3.0.0 for spec-driven development.

Supported Tools

• Gemini CLI — Google's CLI-based AI assistant
• Antigravity — Google's IDE-integrated AI agent
• Claude Code — Anthropic's terminal-native coding assistant
• GitHub Copilot — GitHub's AI pair programmer

Installation

Install dotai globally via npm.

Requirements

• Node.js 18+ — dotai requires Node.js version 18 or higher
• npm — comes bundled with Node.js

Install

$ npm install -g @nbslabs/dotai

Verify

$ dotai --version
3.1.0

Quick Start

Up and running in 30 seconds.

# 1. Install globally
$ npm install -g @nbslabs/dotai

# 2. Initialize in your project
$ cd your-project
$ dotai init

# 3. (Optional) Build persistent knowledge
$ dotai knowledge init

# Done! Edit .ai/ files — all tools stay in sync.

dotai init will:

1. Ask which AI tools you use (or select all with --yes)
2. Create the .ai/ directory with template files
3. Create symlinks so each tool reads from .ai/
4. Auto-detect and import existing CLAUDE.md / GEMINI.md content
5. Update .gitignore to exclude symlinked directories

Project Structure

The .ai/ directory anatomy explained.

The AI.md File

The heart of dotai — write your project context once for every AI tool.

.ai/AI.md is symlinked to CLAUDE.md, GEMINI.md, AGENTS.md, and .github/copilot-instructions.md. Whatever you write here, every tool sees.

Template Sections

The scaffolded AI.md includes these sections (fill them in for your project):

• Before You Start — Instructions for agents to read .ai/knowledge/ first
• Auto-Persist Rule — Mandatory rule for agents to call knowledge_append when they discover something new
• MCP Server Reference — Table of 7 MCP tools available
• Project Overview — What the project does
• Architecture — Directory structure, layers
• Tech Stack — Language, runtime, framework, database, ORM, etc.
• Coding Conventions — Style rules, naming, patterns
• Key Commands — Exact dev/build/test commands
• Important Constraints — Hard rules the AI must never violate
• Common Pitfalls — Gotchas the AI wouldn't know

.dotai.json

The project configuration file — similar to package.json in npm.

Created by dotai init. Tracks which tools are configured, link states, and knowledge settings.

{
  "version": "3.1.0",
  "tools": ["claude", "gemini", "copilot", "antigravity"],
  "aiDir": ".ai",
  "gitignore": true,
  "links": {
    "claude": { "linked": true, "linkedAt": "2026-04-16T..." },
    "gemini": { "linked": true, "linkedAt": "2026-04-16T..." },
    "copilot": { "linked": true, "linkedAt": "2026-04-16T..." },
    "antigravity": { "linked": true, "linkedAt": "2026-04-16T..." }
  },
  "knowledge": {
    "enabled": true,
    "scanDepth": 2,
    "excludePatterns": [],
    "autoUpdateOnCommit": false
  },
  "sdd": {
    "enabled": true,
    "initializedAt": "2026-04-16T..."
  }
}

Settings

Per-tool JSON configuration files in .ai/settings/.

claude.json

Symlinked to .claude/settings.json. Controls Claude Code permissions and MCP servers.

{
  "permissions": {
    "allow": [],
    "deny": []
  },
  "mcpServers": {
    "dotai-knowledge": {
      "command": "npx",
      "args": ["dotai", "knowledge", "serve", "--stdio", "--project", "/path/to/project"]
    }
  }
}

gemini.json

Symlinked to .gemini/settings.json. Shared by both Gemini CLI and Antigravity.

{
  "mcpServers": {
    "dotai-knowledge": {
      "command": "npx",
      "args": ["dotai", "knowledge", "serve", "--stdio", "--project", "/path/to/project"]
    }
  }
}

Rules

Coding rules applied to agents via .ai/rules/.

Rules are Markdown files with YAML frontmatter. They are symlinked to .claude/rules/, .gemini/rules/, and .agents/rules/ for Claude, Gemini, and Antigravity respectively.

Frontmatter Fields

Example: security.md

---
description: Security rules for this project
alwaysApply: true
---

# Security Rules

- Never commit secrets, API keys, or credentials
- Use environment variables for sensitive configuration
- Validate all user inputs
- Apply least-privilege principle

Default Rules

dotai scaffolds three rules:

• general.md — General coding conventions (alwaysApply: true)
• security.md — Security best practices (alwaysApply: true)
• testing.md — Testing conventions (alwaysApply: false)

Commands

Custom slash commands in .ai/commands/ and .ai/commands-gemini/.

Claude Code Commands (.md)

Markdown files in .ai/commands/ become slash commands in Claude Code. Each file is symlinked to .claude/commands/.

# .ai/commands/review.md

# /review Command

Review the current code changes and provide:
1. A summary of changes
2. Potential issues or bugs
3. Suggestions for improvement
4. Security concerns if any

Gemini CLI Commands (.toml)

Gemini CLI uses TOML format (not Markdown). These live in .ai/commands-gemini/ and are symlinked to .gemini/commands/.

# .ai/commands-gemini/review.toml

description = "Review code changes and provide feedback"
prompt = """
Review the current code changes and provide:
1. A summary of changes
2. Potential issues or bugs
3. Suggestions for improvement
4. Security concerns if any

{{args}}
"""

The /learn Command

A special command (.ai/commands/learn.md) that teaches agents how to write findings back to the knowledge base using the knowledge_append MCP tool or CLI command.

Built-in Slash Commands

dotai init automatically scaffolds these slash commands for all enabled tools:

The /git-stage-commit Command

Stages all unstaged and modified changes, generates a conventional commit message from the diff, and commits locally without pushing. If the knowledge base exists but is unpopulated, it runs /learn first.

# Usage — just run the slash command in your AI tool
/git-stage-commit

Skills

Reusable instruction packages shared across all AI tools.

Skills live in .ai/skills/ and are symlinked to all four tools:

• .claude/skills/
• .gemini/skills/
• .agents/skills/
• .github/skills/

Each skill is a subdirectory containing a SKILL.md file with instructions.

Workflows

Step-by-step workflow definitions for Antigravity.

Workflows live in .ai/workflows/ and are symlinked to .agents/workflows/. Each workflow is a Markdown file with YAML frontmatter and step definitions.

---
description: Example workflow for common tasks
---

# Example Workflow

1. Describe the first step
2. Describe the second step
3. Describe the final step

Ignore Files

Control which files AI tools should ignore.

.ai/ignore/.aiignore is symlinked to .geminiignore. Use standard gitignore syntax:

node_modules/
dist/
build/
.env
.env.*
*.log

Prompts & Instructions

GitHub Copilot-specific prompt and instruction files.

Prompts

Markdown files in .ai/prompts/ are symlinked to .github/prompts/. Each file has YAML frontmatter with a description.

Instructions

Path-specific instructions in .ai/instructions/ are symlinked to .github/instructions/. Copilot applies them based on the applyTo glob pattern:

---
description: Backend-specific coding instructions
applyTo: "src/backend/**,server/**,api/**"
---

# Backend Instructions

- Follow RESTful conventions
- Use proper error handling
- Log important operations

Claude Code

Anthropic's terminal-native coding assistant. Native dir: .claude/

Gemini CLI

Google's CLI-based AI assistant. Native dir: .gemini/

GitHub Copilot

GitHub's AI pair programmer. Native dir: .github/

Antigravity

Google's IDE-integrated AI agent. Native dir: .gemini/

How Symlinks Work

The full mapping of what you edit and where each tool reads it.

When you run dotai link, symlinks are created using relative paths for portability. Move or clone the repo anywhere and dotai link recreates everything.

Backup & Restore

dotai backs up existing files before replacing them with symlinks.

How Backups Work

When dotai link --force encounters an existing real file at a symlink target, it:

1. Renames the original to *.dotai.bak (e.g. CLAUDE.md.dotai.bak)
2. Creates the symlink in its place

Restoring Originals

dotai unlink automatically restores .dotai.bak backups. Use --no-restore to skip.

Related Flags

Platform Support

Works everywhere — macOS, Linux, and Windows.

Knowledge Base Overview

Persistent agent memory that survives across conversations.

AI agents reset their memory every conversation. dotai builds a persistent knowledge layer at .ai/knowledge/ that gives every agent instant codebase context — and agents auto-persist new discoveries as they work.

Why AI-Driven?

CLI scanners extract exports and file structure, but they miss context — why something is designed a certain way, what not to do, hidden dependencies. AI agents understand semantics and produce dramatically better knowledge.

Step 1: dotai knowledge init — scaffolds directory + /learn command
Step 2: Run /learn to let your AI agent deeply populate it

Initialization

Scaffold the knowledge directory, AI skills, and /learn commands.

# Initialize knowledge base
$ dotai knowledge init

# Re-write skill and command files (preserves knowledge data)
$ dotai knowledge init --force

What Gets Created

• knowledge/ — Directory with skeleton files (INDEX.md, patterns.md, gotchas.md, changelog.md)
• skills/knowledge-scan-skill/SKILL.md — AI skill for deep codebase analysis
• /learn slash command — for each enabled tool (Claude, Gemini, Antigravity, Copilot)

Next Step

After initialization, ask your AI agent to populate the knowledge base:

/learn

The agent will explore the codebase, analyze each module, and persist findings to .ai/knowledge/ using MCP tools.

MCP Server

Expose knowledge as MCP tools for AI agents.

$ dotai knowledge serve --stdio
$ dotai knowledge serve --stdio --project /path/to/project  # for IDE tools

The MCP server runs independently — no dotai init required. It auto-creates the knowledge directory if missing.

Configuration

Add to .ai/settings/claude.json or .ai/settings/gemini.json:

{
  "mcpServers": {
    "dotai-knowledge": {
      "command": "npx",
      "args": ["dotai", "knowledge", "serve", "--stdio",
               "--project", "/path/to/your/project"]
    }
  }
}

Available MCP Tools

Auto-Persist Rule

How agents automatically write discoveries back to the knowledge base.

The AI.md template includes a mandatory auto-persist rule. When an agent reads or modifies code and discovers something non-obvious, it is instructed to immediately call the knowledge_append MCP tool — no user prompting needed.

What Triggers Auto-Persist

• Agent notices a non-obvious constraint or side effect
• Agent discovers a hidden dependency between modules
• Agent fixes a bug and finds the root cause was subtle
• Agent notices a consistent pattern across multiple files
• Agent finds that an approach does NOT work (prevents future mistakes)
• Agent encounters an undocumented API requirement

How Knowledge Accumulates

Session 1:  Agent discovers 10 things → persists 8 → knowledge grows
Session 2:  Agent reads knowledge → starts smart → discovers more → persists
Session 3:  Even richer context from line one

Populating with AI

Prompts to ask your AI agent for deep knowledge population.

Full Knowledge Population

Use knowledge_explore to analyze the entire codebase directory by directory.
For each module, use knowledge_append to persist patterns, gotchas, and insights.
Then use knowledge_populate_ai_md to fill in the AI.md with project overview,
architecture, tech stack, key commands, constraints, and common pitfalls.

Quick Module Deep-Dive

Use knowledge_explore to read src/core/ and analyze the code deeply. Persist
every non-obvious finding using knowledge_append. Focus on things that would
surprise a new developer.

AI.md Population Only

Explore the codebase using knowledge_explore, then call knowledge_populate_ai_md
to fill in the Project Overview, Architecture, Tech Stack, Key Commands,
Important Constraints, and Common Pitfalls sections of AI.md.

dotai init

Scaffold .ai/ directory and create .dotai.json.

$ dotai init [options]

Behavior

• If .dotai.json exists (e.g. after cloning), it auto-restores the project — no prompts
• If CLAUDE.md, GEMINI.md, or .github/copilot-instructions.md exist, their content is merged into .ai/AI.md
• Never overwrites existing files in .ai/

dotai link

Create symlinks for one or all configured tools.

$ dotai link [tools...]

dotai unlink

Remove symlinks, optionally restore backed-up originals.

$ dotai unlink [tools...]

dotai status

Show the current state of every symlink.

$ dotai status

dotai add

Add a new tool to an already-initialized project.

$ dotai add <tool>

dotai remove

Remove a tool and clean up its symlinks.

$ dotai remove <tool>

dotai list

List all supported tools and their link status.

$ dotai list

dotai sync

Re-evaluate and repair all symlinks.

$ dotai sync

Sync verifies every link, fixes broken/missing ones, and removes stale links for tools no longer configured.

dotai doctor

Run diagnostics and auto-fix all problems.

$ dotai doctor
$ dotai doctor --fix

Checks Performed

• Missing .ai/ directory
• Missing source files (required links)
• Broken symlinks
• Symlinks pointing to wrong target
• Real files blocking symlink targets
• Missing symlinks
• Stale tool references in config
• Missing .gitignore entries

dotai upgrade

Update .ai/ scaffold files to the latest dotai templates.

$ dotai upgrade
$ dotai upgrade --dry-run
$ dotai upgrade --force

How It Works

When you upgrade dotai, your existing .ai/ files keep stale template content because dotai init never overwrites existing files. dotai upgrade detects what changed, removes obsolete files, and helps you migrate.

File Categories

Review Workflow

For user-modified files, the latest template is saved to .ai/_upgrade/ so you can diff and merge manually:

$ diff .ai/AI.md .ai/_upgrade/AI.md
# Merge any new sections you want, then delete _upgrade/
$ rm -rf .ai/_upgrade/

dotai knowledge

Manage persistent codebase knowledge base — 4 subcommands.

dotai sdd

Manage the Spec-Driven Development toolkit — 4 subcommands.

Init Flags

$ dotai sdd init              # scaffold (skips existing)
$ dotai sdd init --force      # re-write skills and commands
$ dotai sdd init --dry-run    # preview without writing

New Feature

$ dotai sdd new user-auth     # creates .ai/sdd/user-auth/

dotai mcp

Manage MCP server configurations across all enabled tool settings files. (v3.1.0)

Add Options

Examples

$ dotai mcp add my-server -c npx -a "my-pkg,serve,--stdio"
$ dotai mcp add db -c npx -a "db-mcp" -e "DB_URL=postgres://localhost"
$ dotai mcp list
$ dotai mcp remove my-server

dotai skill

Manage reusable skill packages in .ai/skills/. (v3.1.0)

Examples

$ dotai skill add code-review -d "Code review checklist"
$ dotai skill list
$ dotai skill remove code-review -y

dotai rule

Manage coding rule files in .ai/rules/. (v3.1.0)

Examples

$ dotai rule add api-conventions --always
$ dotai rule add testing-guidelines
$ dotai rule list

dotai cmd

Manage custom slash commands across all tool formats simultaneously. (v3.1.0)

Format Mapping

Examples

$ dotai cmd add deploy         # creates files for all enabled tools
$ dotai cmd list               # merged view across formats
$ dotai cmd remove deploy

dotai config

View and modify .dotai.json settings directly. (v3.1.0)

Examples

$ dotai config show
$ dotai config get tools
$ dotai config set aiDir .ai

Spec-Driven Development (SDD)

A structured, 8-phase workflow where AI agents implement features from human-reviewed specifications.

Why SDD?

AI coding agents are powerful but unpredictable. Without guardrails, they can:

• Hallucinate features that nobody asked for
• Make architectural decisions without human input
• Introduce subtle bugs when given vague instructions
• Lose context across sessions, re-inventing what was already decided

SDD solves this by decomposing every feature into spec documents that are reviewed by humans before AI implements them. The AI never writes code without an approved plan, and every piece of output traces back to a specification.

How it Fits into dotai

SDD is built on top of the existing dotai infrastructure:

• Skills — 8 reusable instruction sets in .ai/skills/ that teach agents each phase
• Commands — 28 native command files (Claude .md, Gemini .toml, Copilot .prompt.md, Antigravity .md)
• Templates — .ai/sdd/_template-feature/ for consistent feature directory creation
• Knowledge — Phase 8 integrates with the existing knowledge base

The 8-Phase Workflow

Each phase has a dedicated AI skill, a native command, and clear inputs/outputs.

Phase Details

Phase 1: Initiate — 👤 Human

You write idea.md describing what you want to build. The idea should capture the what and why, not the how. Run dotai sdd new <name> to create the feature directory.

Phase 2: Specify — 🤖 Agent

The agent reads idea.md and generates requirements.md with functional requirements, non-functional requirements, constraints, and acceptance criteria. You review and approve before continuing.

Phase 3: Decompose — 🤖 Agent

The agent reads requirements.md and decomposes it into atomic task files: tasks/01_name.task.md, tasks/02_name.task.md, etc. Each task should be implementable in a single AI session. You review and approve the task split.

Phase 4: Plan — 🤖 Agent

For each task, the agent generates an implementation plan (plans/*.plan.md) and evaluation criteria (evaluation/*.evaluation.md). Plans contain specific files to create/modify, functions, dependencies. You review and approve.

Phase 5: Implement — 🤖 Agent

The agent implements according to the approved plan. It reads the plan, writes code, runs tests. This is fully automated — the agent follows the plan exactly.

Phase 6: Evaluate — 🤖 Agent

The agent evaluates its own implementation against the acceptance criteria from Phase 4. It writes a *.result.md file with PASS or FAIL verdict. If FAIL, the agent automatically retries implementation (Phase 5) using the diagnosis.

Phase 7: Review — 🤖🔍 Agent + 👤 Human

The agent performs a holistic code review across all implemented tasks and writes code-review.md. You read the review and decide whether to accept, request changes, or iterate.

Phase 8: Context-sync — 🤖 Agent

The agent updates .ai/knowledge/ with patterns, gotchas, and architecture decisions discovered during implementation. This ensures future sessions start with richer context.

SDD CLI Commands

Initialize, create features, and monitor progress.

Initialize SDD

$ dotai sdd init              # scaffold (skip existing files)
$ dotai sdd init --force      # re-write all skills and commands
$ dotai sdd init --dry-run    # preview without writing

This creates:

• 8 skill files in .ai/skills/ — one per SDD phase
• SDD README at .ai/sdd/README.md
• Feature template at .ai/sdd/_template-feature/
• 28 cross-tool commands in 4 formats (see below)
• SDD block appended to .ai/AI.md

Create a Feature

$ dotai sdd new user-authentication

Creates a new directory at .ai/sdd/user-authentication/ from the template.

List Features

$ dotai sdd list

Shows all features with auto-detected phase, task count, and evaluation status.

Feature Status

$ dotai sdd status user-authentication

Displays a detailed phase-by-phase checklist for a feature.

Cross-Tool Commands

SDD generates native commands for every supported AI tool.

Each SDD phase has a command that works natively in all 4 tools. No manual setup needed — dotai sdd init generates everything.

Running Phase Commands

The argument to every phase command is the feature name — not an individual task or plan file:

# Claude / Gemini CLI:
/sdd-implement user-authentication

# If you omit the name, the agent lists features and asks:
/sdd-implement

How each phase processes work:

Implement and Evaluate are sequential by design. The agent works on one task at a time so you can inspect progress between tasks. Run the command again to advance to the next task. If evaluation fails, the agent retries the same task automatically before moving on.

.ai/
├── commands/          ← Claude Code (.md)
│   ├── sdd-specify.md
│   ├── sdd-decompose.md
│   └── ...
├── commands-gemini/   ← Gemini CLI (.toml)
│   ├── sdd-specify.toml
│   └── ...
├── prompts/           ← GitHub Copilot (.prompt.md)
│   ├── sdd-specify.prompt.md
│   └── ...
└── workflows/         ← Antigravity (.md)
    ├── sdd-specify.md
    └── ...

Feature Directory Structure

Each feature lives in its own directory under .ai/sdd/.

.ai/sdd/
├── README.md              ← SDD workflow guide
├── _template-feature/     ← Template for new features
├── my-feature/
│   ├── idea.md                ← Phase 1: you write this
│   ├── requirements.md        ← Phase 2: agent generates
│   ├── tasks/
│   │   ├── 01_setup.task.md   ← Phase 3: agent decomposes
│   │   └── 02_api.task.md
│   ├── plans/
│   │   ├── 01_setup.plan.md   ← Phase 4: agent plans
│   │   └── 02_api.plan.md
│   ├── evaluation/
│   │   ├── 01_setup.evaluation.md  ← Phase 4: acceptance criteria
│   │   ├── 01_setup.result.md      ← Phase 6: pass/fail verdict
│   │   └── ...
│   └── code-review.md         ← Phase 7: holistic review
└── another-feature/
    └── ...

Skills Reference

8 reusable instruction sets that teach AI agents each workflow phase.

Key Skill Features

• Feature Discovery: Every skill includes a "Feature Resolution" clause. If the user doesn't specify a feature name, the agent scans .ai/sdd/ to find the active feature.
• Retry Clause: The implementation skill (Phase 5) includes logic to re-read the failed evaluation and retry automatically.
• Result Persistence: Evaluation results are saved to .result.md files so verdicts persist across sessions.

Using dotai with Existing Projects

Your project already has CLAUDE.md, GEMINI.md, commands, skills — here's how to migrate.

Context Files Are Auto-Imported

When you run dotai init, it automatically detects existing CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md files and merges their content into .ai/AI.md under an "Imported Instructions" section — nothing is lost.

Existing Commands, Skills, Settings

dotai skips real files at symlink targets by default to avoid data loss. To migrate them:

1. Run dotai init — creates .ai/ and imports context files
2. Copy your existing commands and skills into .ai/:

   $ cp -r .claude/commands/* .ai/commands/
   $ cp -r .claude/skills/* .ai/skills/

3. Force re-link with backup: dotai link --force --backup
4. Verify: dotai status

Team Setup

How teammates use dotai after cloning your repo.

When a teammate clones a dotai-managed repo, they just run:

$ npm install -g @nbslabs/dotai  # if not already installed
$ dotai init  # reads .dotai.json, scaffolds missing files, links everything

dotai init detects the existing .dotai.json and automatically sets up the project — no prompts, no tool selection. Just like npm install reads package.json.

Git Integration

What to commit and what to ignore.

dotai automatically adds symlinked directories to .gitignore during init.

nvm Troubleshooting

Fix MCP server issues when Node.js is installed via nvm.

IDE-spawned tools (Antigravity) can't find npx because they don't load .bashrc. Use the full path in your settings JSON:

{
  "mcpServers": {
    "dotai-knowledge": {
      "command": "/home/YOUR_USER/.nvm/versions/node/vXX.XX.X/bin/npx",
      "args": ["dotai", "knowledge", "serve", "--stdio",
               "--project", "/path/to/your/project"],
      "env": {
        "PATH": "/home/YOUR_USER/.nvm/versions/node/vXX.XX.X/bin:/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Find your path with: which npx

Upgrading

Migration steps from previous versions.

From any version to v3.1.0+

v3.1.0 adds stale file cleanup to dotai upgrade and introduces new built-in slash commands.

$ npm install -g @nbslabs/dotai   # upgrade dotai globally
$ cd your-project
$ dotai upgrade --dry-run          # preview what would change
$ dotai upgrade                    # apply safe updates + stale cleanup

This will:

1. Create new template files (e.g., git-stage-commit.md, git-stage-commit.toml)
2. Auto-update DOTAI.md (reference documentation — safe to overwrite)
3. Remove stale files from previous versions that are no longer in the scaffold
4. Save latest templates to .ai/_upgrade/ for user-modified files (e.g., AI.md)
5. Track scaffoldVersion in .dotai.json for future upgrades

Optional: Enable Knowledge Base

$ dotai knowledge init              # scaffold knowledge + /learn command

Optional: Enable SDD Toolkit

$ dotai sdd init                  # opt-in to Spec-Driven Development

From any version to v3.0.0+

v3.0.0 introduced dotai upgrade — a dedicated command that detects stale scaffold files and helps you migrate.

$ npm install -g @nbslabs/dotai   # upgrade dotai globally
$ cd your-project
$ dotai upgrade --dry-run          # preview what would change
$ dotai upgrade                    # apply safe updates

From v2.0.x to v2.1.0

$ npm install -g @nbslabs/dotai   # upgrade
$ cd your-project
$ dotai upgrade                    # preferred (v3.0.0+)
# or: dotai init                  # re-scaffolds missing dirs + re-links

This will:

1. Scaffold .ai/commands-gemini/ with .toml templates (without overwriting existing files)
2. Create new symlinks: AGENTS.md, .gemini/skills/, .github/skills/
3. Stale commands → .gemini/commands symlink can be removed via dotai doctor --fix

From v1.x to v2.x

v2 added the knowledge base system. No breaking changes — existing configs work without modification. The knowledge block in .dotai.json is optional.

$ npm install -g @nbslabs/dotai
$ cd your-project
$ dotai upgrade            # preferred (v3.0.0+)
$ dotai knowledge init  # optional: set up persistent knowledge