### Initial Setup Codex

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `setup-codex` command performs a full initial setup, including scaffolding the workspace plugin and installing local skills. It can be used with `--dry-run` to preview changes.

```bash
npx @daominhhiep/codex-kit setup-codex
```

```bash
npx @daominhhiep/codex-kit setup-codex --skills planning,clean-code,debugging
```

```bash
npx @daominhhiep/codex-kit setup-codex --dry-run
```

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

### Common Codex Kit CLI Examples

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

A collection of common command-line examples for initializing, installing, listing, and managing components within a Codex Kit project.

```bash
codex-kit init --path ./my-project
```

```bash
codex-kit install --path ./my-project
```

```bash
codex-kit install --target plugin
```

```bash
codex-kit install --target mcp
```

```bash
codex-kit install --target skills
```

```bash
codex-kit list --target skills
```

```bash
codex-kit list --target skills --query frontend
```

```bash
codex-kit list --target skills --scope local
```

```bash
codex-kit install --target skills --scope local
```

```bash
codex-kit install --target skills --scope local --skills clean-code,planning
```

```bash
codex-kit sync --target skills --scope local --skills clean-code,planning
```

```bash
codex-kit remove --target skills --scope local --skills clean-code,planning
```

```bash
codex-kit setup-codex
```

```bash
codex-kit sync-codex
```

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

### Install MCP Server Bundle with Codex Kit

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Add the MCP server bundle, including Context7 and a MySQL example, to Codex configuration. Use `--scope local` to install to user-level config. `sync` command can be used to update config.

```bash
npx @daominhhiep/codex-kit install --target mcp
```

```bash
npx @daominhhiep/codex-kit install --target mcp --scope local
```

```bash
npx @daominhhiep/codex-kit sync --target mcp
```

```bash
npx @daominhhiep/codex-kit sync --target mcp --scope local
```

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

### Initialize and Install Codex Kit

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Use these commands to scaffold a new project with Codex Kit or install the existing scaffold.

```bash
npx @daominhhiep/codex-kit init
```

```bash
npx @daominhhiep/codex-kit install
```

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

### MCP Bundle Example

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Lists the components included in the shipped MCP bundle, including an example for MySQL using a specific package.

```javascript
The shipped MCP bundle currently includes `context7` and a commented `mysql` example using `@benborla29/mcp-server-mysql`.
```

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

### Setup Codex CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Performs the initial full setup for Codex Kit in the current repository. This command is essential for new projects.

```bash
npx @daominhhiep/codex-kit setup-codex
```

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

### Install Managed MCP

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Installs a shipped MCP bundle (e.g., Context7 + MySQL example) to the Codex configuration file. Specify the target directory, scope, Codex home directory, and whether to perform a dry run.

```javascript
import { installManagedMcp } from "@daominhhiep/codex-kit/lib/mcp.js";

// Install to project config
const result = await installManagedMcp({
  targetDir: "./my-project",
  scope: "project",
  codexHome: `${process.env.HOME}/.codex`,
  dryRun: false
});

console.log(`Config path: ${result.configPath}`);
console.log(`Changed: ${result.changed}`);
console.log(`Installed servers: ${result.installedServers.join(", ")}`);
console.log(`Commented examples: ${result.commentedServers.join(", ")}`);
// Output:
// Config path: ./my-project/.codex/config.toml
// Changed: true
// Installed servers: context7
// Commented examples: mysql
```

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

### Install Codex Kit Globally

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Install Codex Kit globally to use its commands from any directory. After global installation, you can initialize a project using the `codex-kit init` command.

```bash
npm install -g @daominhhiep/codex-kit
codex-kit init
```

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

### Install local skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Installs shipped skills to the local Codex installation. Provide an empty array to install all available skills.

```javascript
import { installLocalSkills } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await installLocalSkills({
  skillsRoot: "./templates/project/.agents/skills",
  codexHome: process.env.CODEX_HOME || `${process.env.HOME}/.codex`,
  skills: ["clean-code", "debugging", "planning"],  // Empty for all skills
  force: false,
  dryRun: false
});

console.log(`Installed to: ${result.targetDir}`);
console.log(`Files written: ${result.written.length}`);
console.log(`Files skipped: ${result.skipped.length}`);
// Output:
// Installed to: /home/user/.codex/skills
// Files written: 24
// Files skipped: 0
```

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

### Install Codex Kit Components

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Use the `install` command to add various components to your Codex Kit project. Specify the target to install specific types of components like plugins, MCP, or skills.

```bash
codex-kit install
```

```bash
codex-kit install --target plugin
```

```bash
codex-kit install --target mcp
```

```bash
codex-kit install --target skills
```

```bash
codex-kit install --target skills --scope local
```

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

### Install Project Skill Bundle CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Installs the project skill bundle into the current repository. Ensure you are in the correct repository directory.

```bash
npx @daominhhiep/codex-kit install --target skills
```

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

### Initialize Project Scaffold with Codex Kit

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `init` command to install the full Codex Kit scaffold. Options include specifying a path, installing the workspace plugin, performing a dry run, or forcing an overwrite.

```bash
npx @daominhhiep/codex-kit init
```

```bash
npx @daominhhiep/codex-kit init --path ./my-project
```

```bash
npx @daominhhiep/codex-kit init --install-plugin
```

```bash
npx @daominhhiep/codex-kit init --dry-run
```

```bash
npx @daominhhiep/codex-kit init --force
```

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

### Install MCP Bundle

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Installs the shipped MCP bundle into the project or local Codex config. Use `--scope local` for user-local installation.

```bash
npx @daominhhiep/codex-kit install --target mcp
```

```bash
npx @daominhhiep/codex-kit install --target mcp --scope local
```

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

### Install Shipped Skills Locally

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Installs the shipped skills into the local Codex environment.

```bash
npx @daominhhiep/codex-kit install --target skills --scope local
```

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

### Setup and Sync Codex

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Performs complete Codex setup or syncs the workspace plugin and local skills.

```APIDOC
## Setup and Sync Codex

### Description
The `setup-codex` command performs a complete Codex setup, including scaffolding the workspace plugin and installing shipped skills. The `sync-codex` command updates both after upgrading Codex Kit.

### Commands
- `setup-codex [options]`
- `sync-codex

### Options for `setup-codex`
- **--skills** (string) - Optional - Comma-separated list of specific skills to set up.
- **--dry-run** (boolean) - Optional - Previews the setup process without making changes.

### Examples
```bash
# Full initial setup (plugin + local skills)
npx @daominhhiep/codex-kit setup-codex

# Sync both plugin and local skills after upgrade
npx @daominhhiep/codex-kit sync-codex

# Setup with specific skills only
npx @daominhhiep/codex-kit setup-codex --skills planning,clean-code,debugging

# Preview setup
npx @daominhhiep/codex-kit setup-codex --dry-run
```
```

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

### Install Skills to Local Codex Installation

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Copy shipped skills to the user's local Codex installation (`~/.codex/skills`). Use `--skills` to specify individual skills, `--force` to overwrite, or `sync` to update.

```bash
npx @daominhhiep/codex-kit install --target skills --scope local
```

```bash
npx @daominhhiep/codex-kit install --target skills --scope local --skills clean-code,planning
```

```bash
npx @daominhhiep/codex-kit install --target skills --scope local --skills frontend-design,nextjs-react-expert,tailwind-patterns
```

```bash
npx @daominhhiep/codex-kit install --target skills --scope local --force
```

```bash
npx @daominhhiep/codex-kit sync --target skills --scope local
```

```bash
npx @daominhhiep/codex-kit sync --target skills --scope local --skills debugging,bug-hunt
```

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

### Install Project Skills with Codex Kit

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Install the shipped skill bundle to the project's `.agents/skills/` directory. Use `--dry-run` to preview changes or `sync` to update skills.

```bash
npx @daominhhiep/codex-kit install --target skills
```

```bash
npx @daominhhiep/codex-kit sync --target skills
```

```bash
npx @daominhhiep/codex-kit install --target skills --dry-run
```

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

### List Available Skills CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Use this command to list all available skills. No setup is required.

```bash
npx @daominhhiep/codex-kit list --target skills
```

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

### Install Workspace Plugin

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Installs only the workspace plugin into the current project.

```bash
npx @daominhhiep/codex-kit install --target plugin
```

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

### Natural Language to Install Skill CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Maps the natural language query 'cài skill frontend-design' to the CLI command for installing the 'frontend-design' skill locally.

```bash
npx @daominhhiep/codex-kit install --target skills --scope local --skills frontend-design
```

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

### List Installed Local Skills CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Lists all skills that have been installed locally in your Codex configuration. Use the --scope local flag to filter for local installations.

```bash
npx @daominhhiep/codex-kit list --target skills --scope local
```

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

### Workflow Resolution Example 3

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Illustrates using a workflow from the workspace, prioritizing local files over npm packages. 'review' workflow uses '.agents/workflows/review.md'.

```bash
follow the review workflow in this repo
```

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

### Setup and Sync Codex

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Commands to set up and synchronize Codex configurations and rules within your project.

```bash
codex-kit setup-codex
```

```bash
codex-kit sync-codex
```

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

### Install Codex Kit Workspace Plugin

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Install only the workspace plugin for Codex integration into an existing project. Options include specifying a path, performing a dry run, or installing to a specific directory.

```bash
npx @daominhhiep/codex-kit install --target plugin
```

```bash
npx @daominhhiep/codex-kit install --target plugin --path ./my-project
```

```bash
npx @daominhhiep/codex-kit install --target plugin --dry-run
```

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

### List installed local skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Retrieves information about currently installed shipped skills in the local Codex.

```javascript
import { listInstalledLocalSkills } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await listInstalledLocalSkills({
  skillsRoot: "./templates/project/.agents/skills",
  codexHome: `${process.env.HOME}/.codex`
});

console.log(`Installed: ${result.installed.length} skills`);
console.log(`Missing: ${result.missing.length} skills`);
result.installed.forEach(skill => {
  console.log(`  - ${skill.name}: ${skill.summary}`);
});
// Output:
// Installed: 12 skills
// Missing: 33 skills
//   - clean-code: Pragmatic coding standards and scoped implementation quality.
//   - debugging: Evidence-based debugging before changing code.
```

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

### Install Skill by Name into Local Codex CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Installs a specific skill by its name into your local Codex configuration. Requires the skill name and local scope.

```bash
npx @daominhhiep/codex-kit install --target skills --scope local --skills <name>
```

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

### Programmatic API: installWorkspacePlugin

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Installs only the workspace plugin into a project.

```APIDOC
## installWorkspacePlugin

### Description
Installs only the workspace plugin into a project, adding the plugin manifest and skills to `.agents/plugins/codex-kit/`.

### Function Signature
```javascript
installWorkspacePlugin(options: { targetDir: string, pluginRoot?: string, version?: string, force?: boolean, dryRun?: boolean }): Promise<{ written: number }>
```

### Parameters
- **targetDir** (string) - Required - The directory of the project where the plugin will be installed.
- **pluginRoot** (string) - Optional - The root directory of the workspace plugin.
- **version** (string) - Optional - The version of Codex Kit to use.
- **force** (boolean) - Optional - If true, overwrites existing plugin files. Defaults to false.
- **dryRun** (boolean) - Optional - If true, simulates the operation without writing files. Defaults to false.

### Request Example
```javascript
import { installWorkspacePlugin } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await installWorkspacePlugin({
  targetDir: "./my-project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  force: false,
  dryRun: false
});

console.log(`Plugin files written: ${result.written.length}`);
```

### Response Example
```javascript
// Output:
// Plugin files written: 3
```
```

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

### Workflow Resolution Example 2

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Shows how a direct request for a workflow is resolved to a local file path. 'plan' workflow resolves to '.agents/workflows/plan.md'.

```bash
use the plan workflow from codex kit
```

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

### Install Workspace Plugin with Codex Kit API

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `installWorkspacePlugin` function installs only the workspace plugin into a project, adding its manifest and skills to the `.agents/plugins/codex-kit/` directory. Control the process with `force` and `dryRun` options.

```javascript
import { installWorkspacePlugin } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await installWorkspacePlugin({
  targetDir: "./my-project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  force: false,
  dryRun: false
});

console.log(`Plugin files written: ${result.written.length}`);
// Output:
// Plugin files written: 3
```

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

### List Codex Kit Components

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

List available or installed components. You can filter by target and scope, and even query for specific skills.

```bash
codex-kit list --target skills
```

```bash
codex-kit list --target skills --query frontend
```

```bash
codex-kit list --target skills --scope local
```

```bash
codex-kit list --target plugin
```

```bash
codex-kit list --target mcp
```

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

### Workflow Resolution Example 1

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Demonstrates how a natural language request for a workflow alias is resolved to a local file path. The alias 'ui-ux-promax' maps to '.agents/workflows/ui-ux-pro-max.md'.

```bash
dùng workflow ui-ux-promax của codex kit
```

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

### Search Skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Search for skills by keyword or list installed skills in local Codex.

```APIDOC
## Search Skills by Keyword

### Description
Searches for skills matching a given keyword.

### Command
```bash
npx @daominhhiep/codex-kit list --target skills --query <keyword>
```

### Examples
```bash
npx @daominhhiep/codex-kit list --target skills --query frontend
npx @daominhhiep/codex-kit list --target skills --query debug
npx @daominhhiep/codex-kit list --target skills --query testing
```

## List Installed Skills

### Description
Lists all skills currently installed in the local Codex.

### Command
```bash
npx @daominhhiep/codex-kit list --target skills --scope local
```

## Legacy Search Command

### Description
An older command that still functions for searching skills.

### Command
```bash
npx @daominhhiep/codex-kit search-skills <keyword>
```

### Example
```bash
npx @daominhhiep/codex-kit search-skills frontend
```
```

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

### Sync local skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Overwrites local Codex skills with the shipped version, equivalent to installing with force enabled.

```javascript
import { syncLocalSkills } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await syncLocalSkills({
  skillsRoot: "./templates/project/.agents/skills",
  codexHome: `${process.env.HOME}/.codex`,
  skills: ["debugging"],  // Sync specific skill
  dryRun: false
});

console.log(`Synced ${result.written.length} files to ${result.targetDir}`);
// Output:
// Synced 8 files to /home/user/.codex/skills
```

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

### Local Skill Management

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

APIs for managing shipped skills within a local Codex installation.

```APIDOC
## installLocalSkills

### Description
Installs shipped skills to the user's local Codex installation. Use the `skills` array to install specific skills by name.

### Method
`installLocalSkills` (function)

### Parameters
#### Request Body
- **skillsRoot** (string) - Required - The root directory for skills.
- **codexHome** (string) - Required - The home directory for Codex.
- **skills** (array of strings) - Optional - An array of skill names to install. If empty, all skills are installed.
- **force** (boolean) - Optional - If true, overwrites existing skills.
- **dryRun** (boolean) - Optional - If true, simulates the installation without making changes.

### Request Example
```javascript
{
  "skillsRoot": "./templates/project/.agents/skills",
  "codexHome": process.env.CODEX_HOME || `${process.env.HOME}/.codex`,
  "skills": ["clean-code", "debugging", "planning"],
  "force": false,
  "dryRun": false
}
```

### Response
#### Success Response (Object)
- **targetDir** (string) - The directory where skills were installed.
- **written** (array of strings) - A list of files that were written.
- **skipped** (array of strings) - A list of files that were skipped.

#### Response Example
```json
{
  "targetDir": "/home/user/.codex/skills",
  "written": ["file1.js", "file2.js"],
  "skipped": []
}
```

## syncLocalSkills

### Description
Overwrites local Codex skills with the shipped version. Functionally equivalent to `installLocalSkills` with `force: true`.

### Method
`syncLocalSkills` (function)

### Parameters
#### Request Body
- **skillsRoot** (string) - Required - The root directory for skills.
- **codexHome** (string) - Required - The home directory for Codex.
- **skills** (array of strings) - Optional - An array of skill names to sync. If empty, all skills are synced.
- **dryRun** (boolean) - Optional - If true, simulates the sync without making changes.

### Request Example
```javascript
{
  "skillsRoot": "./templates/project/.agents/skills",
  "codexHome": `${process.env.HOME}/.codex`,
  "skills": ["debugging"],
  "dryRun": false
}
```

### Response
#### Success Response (Object)
- **targetDir** (string) - The directory where skills were synced.
- **written** (array of strings) - A list of files that were synced.

#### Response Example
```json
{
  "targetDir": "/home/user/.codex/skills",
  "written": ["file1.js"]
}
```

## removeLocalSkills

### Description
Removes specific shipped skills from the local Codex installation.

### Method
`removeLocalSkills` (function)

### Parameters
#### Request Body
- **skillsRoot** (string) - Required - The root directory for skills.
- **codexHome** (string) - Required - The home directory for Codex.
- **skills** (array of strings) - Required - An array of skill names to remove.
- **dryRun** (boolean) - Optional - If true, simulates the removal without making changes.

### Request Example
```javascript
{
  "skillsRoot": "./templates/project/.agents/skills",
  "codexHome": `${process.env.HOME}/.codex`,
  "skills": ["clean-code", "planning"],
  "dryRun": false
}
```

### Response
#### Success Response (Object)
- **removed** (array of strings) - A list of skills that were removed.
- **skipped** (array of strings) - A list of skills that were skipped (e.g., not found).

#### Response Example
```json
{
  "removed": ["clean-code", "planning"],
  "skipped": []
}
```

## listInstalledLocalSkills

### Description
Returns information about which shipped skills are currently installed in local Codex.

### Method
`listInstalledLocalSkills` (function)

### Parameters
#### Request Body
- **skillsRoot** (string) - Required - The root directory for skills.
- **codexHome** (string) - Required - The home directory for Codex.

### Request Example
```javascript
{
  "skillsRoot": "./templates/project/.agents/skills",
  "codexHome": `${process.env.HOME}/.codex`
}
```

### Response
#### Success Response (Object)
- **installed** (array of objects) - A list of installed skills, each with `name` and `summary`.
- **missing** (array of strings) - A list of skill names that are missing.

#### Response Example
```json
{
  "installed": [
    {"name": "clean-code", "summary": "Pragmatic coding standards..."},
    {"name": "debugging", "summary": "Evidence-based debugging..."}
  ],
  "missing": ["skill1", "skill2"]
}
```
```

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

### Get shipped skills catalog

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Retrieves the full catalog of shipped skills and groups them by category.

```javascript
import { getShippedSkills, groupSkillsByCategory } from "@daominhhiep/codex-kit/lib/skills.js";

const skills = await getShippedSkills("./templates/project/.agents/skills");
const grouped = groupSkillsByCategory(skills);

grouped.forEach(group => {
  console.log(`\n${group.category}:`);
  group.skills.forEach(skill => {
    console.log(`  - ${skill.name}: ${skill.summary}`);
  });
});
// Output:
// Planning & Routing:
//   - app-builder: New app scaffolding, stack selection, and project setup.
//   - architecture: Requirements, tradeoffs, ADRs, and system design decisions.
//   - brainstorming: Clarify scope and generate options before implementation.
// Backend & Platform:
//   - clean-code: Pragmatic coding standards and scoped implementation quality.
//   - api-patterns: API design, response shapes, versioning, and protocol choices.
```

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

### List Plugin Status

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use `list --target plugin` to check the status of the workspace plugin. This command helps verify if the plugin is correctly installed and configured.

```bash
npx @daominhhiep/codex-kit list --target plugin
```

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

### Remove Skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Removes specific skills from the local Codex installation.

```APIDOC
## Remove Skills from Local Codex

### Description
Removes specified shipped skills from the local Codex installation. The `--skills` flag is mandatory to prevent accidental removal of all skills.

### Command
```bash
npx @daominhhiep/codex-kit remove --target skills --scope local --skills <skill1>,<skill2>
```

### Parameters
#### Path Parameters
None

#### Query Parameters
- **--skills** (string) - Required - Comma-separated list of skills to remove.
- **--dry-run** (boolean) - Optional - Performs a preview of the removal without making changes.

### Examples
```bash
# Remove specific skills from local Codex
npx @daominhhiep/codex-kit remove --target skills --scope local --skills clean-code,planning

# Preview removal (dry run)
npx @daominhhiep/codex-kit remove --target skills --scope local --skills debugging --dry-run
```
```

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

### Add Shipped MCP Bundle to Repository CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Adds the shipped MCP bundle to the current repository's configuration. This command is used for repository-level setup.

```bash
npx @daominhhiep/codex-kit install --target mcp
```

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

### Define Skill Categories

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

An array defining the categories for shipped skills in the Codex catalog. Each category includes a comment listing example skills.

```javascript
const SKILL_CATEGORIES = [
  "Planning & Routing",      // app-builder, architecture, brainstorming, planning, etc.
  "Backend & Platform",      // clean-code, api-patterns, database-design, nodejs, python, rust
  "Frontend & UI",           // frontend-design, mobile-design, nextjs-react, tailwind, i18n
  "Debugging & Review",      // bug-hunt, debugging, code-review, high-signal-review
  "Testing & Validation",    // lint-and-validate, tdd-workflow, test-hardening, testing-patterns
  "Docs, Delivery & Operations",  // docs-shipper, documentation-templates, deployment
  "Security, Performance & Discoverability",  // vulnerability-scanner, performance-profiling, seo
  "Shell & Environment"      // bash-linux, powershell-windows
];
```

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

### Add Shipped MCP Bundle to Local Config CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Adds the shipped MCP bundle to your local Codex configuration. Use the --scope local flag for local-only installations.

```bash
npx @daominhhiep/codex-kit install --target mcp --scope local
```

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

### Get Managed MCP Status

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Returns the current state of MCP configuration in the project or local Codex config. Requires specifying the target directory, scope, and Codex home directory.

```javascript
import { statusManagedMcp } from "@daominhhiep/codex-kit/lib/mcp.js";

const status = await statusManagedMcp({
  targetDir: "./my-project",
  scope: "project",
  codexHome: `${process.env.HOME}/.codex`
});

console.log(`Config: ${status.configPath}`);
console.log(`Bundle installed: ${status.installed}`);
console.log(`Servers: ${status.servers.join(", ") || "none"}`);
console.log(`Expected: ${status.expectedServers.join(", ")}`);
// Output:
// Config: ./my-project/.codex/config.toml
// Bundle installed: true
// Servers: context7
// Expected: context7
```

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

### Initialize Codex Kit Project

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Use this command to bootstrap a new project with Codex Kit. It sets up the necessary directory structure and configuration files.

```bash
npx @daominhhiep/codex-kit init
```

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

### Programmatic API: initProject

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Initializes a new Codex Kit scaffold in the target directory.

```APIDOC
## initProject

### Description
Initializes a new Codex Kit scaffold in the target directory. Creates routing docs, skills, workflows, agents, and config files with hash tracking in the manifest.

### Function Signature
```javascript
initProject(options: { targetDir: string, templateRoot?: string, pluginRoot?: string, version?: string, installPlugin?: boolean, force?: boolean, dryRun?: boolean }): Promise<{ written: string[], skipped: number, pluginInstalled: boolean }>
```

### Parameters
- **targetDir** (string) - Required - The directory where the project scaffold will be initialized.
- **templateRoot** (string) - Optional - The root directory of the project template.
- **pluginRoot** (string) - Optional - The root directory of the workspace plugin.
- **version** (string) - Optional - The version of Codex Kit to use.
- **installPlugin** (boolean) - Optional - If true, also installs the workspace plugin. Defaults to false.
- **force** (boolean) - Optional - If true, overwrites existing files. Defaults to false.
- **dryRun** (boolean) - Optional - If true, simulates the operation without writing files. Defaults to false.

### Request Example
```javascript
import { initProject } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await initProject({
  targetDir: "./my-project",
  templateRoot: "./templates/project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  installPlugin: true,  // Also install workspace plugin
  force: false,         // Don't overwrite existing files
  dryRun: false         // Actually write files
});

console.log(`Written: ${result.written.length} files`);
console.log(`Skipped: ${result.skipped.length} existing files`);
console.log(`Plugin installed: ${result.pluginInstalled}`);
```

### Response Example
```javascript
// Output:
// Written: 156 files
// Skipped: 0 existing files
// Plugin installed: true
```
```

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

### Initialize Project with Codex Kit API

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `initProject` function initializes a new Codex Kit scaffold in a specified directory. It creates necessary files and tracks changes in the manifest. Configure options like `installPlugin`, `force`, and `dryRun` as needed.

```javascript
import { initProject } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await initProject({
  targetDir: "./my-project",
  templateRoot: "./templates/project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  installPlugin: true,  // Also install workspace plugin
  force: false,         // Don't overwrite existing files
  dryRun: false         // Actually write files
});

console.log(`Written: ${result.written.length} files`);
console.log(`Skipped: ${result.skipped.length} existing files`);
console.log(`Plugin installed: ${result.pluginInstalled}`);
// Output:
// Written: 156 files
// Skipped: 0 existing files
// Plugin installed: true
```

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

### Remove local skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Removes specific shipped skills from the local Codex installation.

```javascript
import { removeLocalSkills } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await removeLocalSkills({
  skillsRoot: "./templates/project/.agents/skills",
  codexHome: `${process.env.HOME}/.codex`,
  skills: ["clean-code", "planning"],
  dryRun: false
});

console.log(`Removed: ${result.removed.length} skills`);
console.log(`Skipped (not found): ${result.skipped.length}`);
// Output:
// Removed: 2 skills
// Skipped (not found): 0
```

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

### Preview Project Updates

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `--dry-run` flag with the `update` command to see which files would be updated without making any changes.

```bash
npx @daominhhiep/codex-kit update --dry-run
```

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

### Search Skills by Keyword

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `list --target skills --query` command to find skills matching a specific keyword. This is useful for discovering relevant skills for development tasks.

```bash
npx @daominhhiep/codex-kit list --target skills --query frontend
```

```bash
npx @daominhhiep/codex-kit list --target skills --query debug
```

```bash
npx @daominhhiep/codex-kit list --target skills --query testing
```

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

### Update Project with Plugin Sync

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `update --install-plugin` command refreshes scaffold files and ensures the workspace plugin is synchronized.

```bash
npx @daominhhiep/codex-kit update --install-plugin
```

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

### Initialize Codex Kit in Specific Directory

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Initialize Codex Kit within a specific directory, useful for creating projects in a designated location.

```bash
npx @daominhhiep/codex-kit init --path ./my-project
```

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

### Search Skills by Topic CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Use this command to search for skills related to a specific topic. Replace <query> with your search term.

```bash
npx @daominhhiep/codex-kit list --target skills --query <query>
```

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

### Force Update Project Scaffold

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `--force` flag with the `update` command to overwrite any locally modified files with the template versions. Use with caution.

```bash
npx @daominhhiep/codex-kit update --force
```

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

### List Shipped Skills

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Browse or search the shipped skill catalog. Options include searching by query or filtering by local scope.

```bash
npx @daominhhiep/codex-kit list --target skills
```

```bash
npx @daominhhiep/codex-kit list --target skills --query frontend
```

```bash
npx @daominhhiep/codex-kit list --target skills --scope local
```

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

### Remove Specific Skills from Local Codex

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `remove --target skills --scope local --skills` command to delete specific skills from your local Codex installation. Always specify skills to avoid accidental mass deletion.

```bash
npx @daominhhiep/codex-kit remove --target skills --scope local --skills clean-code,planning
```

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

### Check Project Status

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `status` command displays the state of scaffold-managed files, highlighting missing, modified, or outdated files within your project.

```bash
npx @daominhhiep/codex-kit status
```

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

### Check project status

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Returns the state of scaffold-managed files, identifying missing, modified, or outdated files.

```javascript
import { statusProject } from "@daominhhiep/codex-kit/lib/kit.js";

const status = await statusProject({
  targetDir: "./my-project",
  templateRoot: "./templates/project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4"
});

console.log(`Version: ${status.version}`);
console.log(`Managed files: ${status.managedCount}`);
console.log(`Plugin installed: ${status.pluginInstalled}`);
console.log(`Missing: ${status.missing.length}`);
console.log(`Modified: ${status.modified.length}`);
console.log(`Outdated: ${status.outdated.length}`);
// Output:
// Version: 0.1.4
// Managed files: 156
// Plugin installed: true
// Missing: 0
// Modified: 2
// Outdated: 5
```

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

### Natural Language to List Skills Debug CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Maps the natural language query 'liệt kê skills debug' to the corresponding CLI command for listing debug skills.

```bash
npx @daominhhiep/codex-kit list --target skills --query debug
```

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

### Preview Skill Removal

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Use the `--dry-run` flag with the `remove` command to preview which skills would be removed without actually deleting them. This is a safety measure.

```bash
npx @daominhhiep/codex-kit remove --target skills --scope local --skills debugging --dry-run
```

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

### Sync Codex Kit Components

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

Synchronize components with the specified target. This command is useful for ensuring consistency across different parts of your project.

```bash
codex-kit sync --target mcp
```

```bash
codex-kit sync --target plugin
```

```bash
codex-kit sync --target skills
```

```bash
codex-kit sync --target skills --scope local
```

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

### Legacy Search Skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The legacy `search-skills` command can still be used to find skills by keyword. It provides similar functionality to the newer `list` command.

```bash
npx @daominhhiep/codex-kit search-skills frontend
```

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

### Programmatic API: updateProject

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Updates an existing scaffold by refreshing managed files while preserving local modifications.

```APIDOC
## updateProject

### Description
Updates an existing scaffold by refreshing managed files while preserving locally modified files. Requires an existing manifest from a previous `initProject` call.

### Function Signature
```javascript
updateProject(options: { targetDir: string, templateRoot?: string, pluginRoot?: string, version?: string, installPlugin?: boolean, force?: boolean, dryRun?: boolean }): Promise<{ written: string[], skipped: number }>
```

### Parameters
- **targetDir** (string) - Required - The directory of the project to update.
- **templateRoot** (string) - Optional - The root directory of the project template.
- **pluginRoot** (string) - Optional - The root directory of the workspace plugin.
- **version** (string) - Optional - The version of Codex Kit to use.
- **installPlugin** (boolean) - Optional - If true, installs or updates the workspace plugin. Defaults to false.
- **force** (boolean) - Optional - If true, overwrites modified files. Defaults to false.
- **dryRun** (boolean) - Optional - If true, simulates the operation without writing files. Defaults to false.

### Request Example
```javascript
import { updateProject } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await updateProject({
  targetDir: "./my-project",
  templateRoot: "./templates/project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  installPlugin: true,
  force: false,  // Set true to overwrite modified files
  dryRun: false
});

console.log(`Updated: ${result.written.length} files`);
console.log(`Preserved: ${result.skipped.length} locally modified files`);
```

### Response Example
```javascript
// Output:
// Updated: 12 files
// Preserved: 3 locally modified files
```
```

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

### Check Codex Kit Status

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

The `status` command provides an overview of the current state of your Codex Kit project.

```bash
codex-kit status
```

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

### Project Status and Skill Catalog

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

APIs for checking project status and retrieving the catalog of shipped skills.

```APIDOC
## statusProject

### Description
Returns the current state of scaffold-managed files, including missing, modified, and outdated files.

### Method
`statusProject` (function)

### Parameters
#### Request Body
- **targetDir** (string) - Required - The target directory of the project.
- **templateRoot** (string) - Required - The root directory of the project template.
- **pluginRoot** (string) - Required - The root directory of the Codex Kit plugin.
- **version** (string) - Required - The version of the project template.

### Request Example
```javascript
{
  "targetDir": "./my-project",
  "templateRoot": "./templates/project",
  "pluginRoot": "./plugins/codex-kit",
  "version": "0.1.4"
}
```

### Response
#### Success Response (Object)
- **version** (string) - The version of the project.
- **managedCount** (integer) - The total number of managed files.
- **pluginInstalled** (boolean) - Whether the Codex Kit plugin is installed.
- **missing** (array of strings) - A list of missing files.
- **modified** (array of strings) - A list of modified files.
- **outdated** (array of strings) - A list of outdated files.

#### Response Example
```json
{
  "version": "0.1.4",
  "managedCount": 156,
  "pluginInstalled": true,
  "missing": [],
  "modified": ["file.txt"],
  "outdated": ["another_file.js"]
}
```

## getShippedSkills

### Description
Returns the complete catalog of shipped skills with metadata, organized by category.

### Method
`getShippedSkills` (function)

### Parameters
#### Query Parameters
- **skillsRoot** (string) - Required - The root directory for skills.

### Request Example
```javascript
// No explicit request body, but requires skillsRoot parameter
// Example usage with groupSkillsByCategory:
import { getShippedSkills, groupSkillsByCategory } from "@daominhhiep/codex-kit/lib/skills.js";

const skills = await getShippedSkills("./templates/project/.agents/skills");
const grouped = groupSkillsByCategory(skills);
```

### Response
#### Success Response (Array of Objects)
- Each object represents a skill category and contains:
  - **category** (string) - The name of the skill category.
  - **skills** (array of objects) - A list of skills within this category, each with `name` and `summary`.

#### Response Example
```json
[
  {
    "category": "Planning & Routing",
    "skills": [
      {"name": "app-builder", "summary": "New app scaffolding..."},
      {"name": "architecture", "summary": "Requirements, tradeoffs..."}
    ]
  },
  {
    "category": "Backend & Platform",
    "skills": [
      {"name": "clean-code", "summary": "Pragmatic coding standards..."}
    ]
  }
]
```
```

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

### Search Shipped Skills

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Searches the shipped skill catalog by name, summary, or category keywords. Requires specifying the skills root directory and the query.

```javascript
import { searchShippedSkills } from "@daominhhiep/codex-kit/lib/skills.js";

const results = await searchShippedSkills({
  skillsRoot: "./templates/project/.agents/skills",
  query: "frontend"
});

results.forEach(skill => {
  console.log(`${skill.name} [${skill.category}]`);
  console.log(`  ${skill.summary}`);
});
// Output:
// frontend-design [Frontend & UI]
//   Web UI design systems, hierarchy, typography, and aesthetics.
// nextjs-react-expert [Frontend & UI]
//   React or Next.js architecture, rendering, and performance.
```

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

### Legacy Codex Kit Aliases

Source: https://github.com/daominhhiep/codex-kit/blob/main/README.md

These are legacy commands that still work for backward compatibility. They perform similar functions to the current commands but use older naming conventions.

```bash
codex-kit install --target project
```

```bash
codex-kit sync --target project
```

```bash
codex-kit list-skills
```

```bash
codex-kit search-skills frontend
```

```bash
codex-kit list-installed-skills
```

```bash
codex-kit install-skills
```

```bash
codex-kit sync-skills
```

```bash
codex-kit remove-skills --skills clean-code,planning
```

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

### Update Project with Codex Kit API

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `updateProject` function refreshes an existing scaffold, preserving locally modified files. It requires a manifest from a prior `initProject` call. Options like `force` and `dryRun` control overwriting behavior.

```javascript
import { updateProject } from "@daominhhiep/codex-kit/lib/kit.js";

const result = await updateProject({
  targetDir: "./my-project",
  templateRoot: "./templates/project",
  pluginRoot: "./plugins/codex-kit",
  version: "0.1.4",
  installPlugin: true,
  force: false,  // Set true to overwrite modified files
  dryRun: false
});

console.log(`Updated: ${result.written.length} files`);
console.log(`Preserved: ${result.skipped.length} locally modified files`);
// Output:
// Updated: 12 files
// Preserved: 3 locally modified files
```

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

### Update Project Scaffold

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

The `update` command refreshes scaffold-managed files from the template. Locally modified files are preserved by default.

```bash
npx @daominhhiep/codex-kit update
```

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

### Sync Codex CLI

Source: https://github.com/daominhhiep/codex-kit/blob/main/plugins/codex-kit/skills/codex-kit/SKILL.md

Updates both the workspace plugin and local skills. This command synchronizes your Codex environment.

```bash
npx @daominhhiep/codex-kit sync-codex
```

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

### Check Project Status

Source: https://context7.com/daominhhiep/codex-kit/llms.txt

Displays the status of scaffold-managed files and checks plugin or MCP status.

```APIDOC
## Check Project Status

### Description
The `status` command shows the state of scaffold-managed files in a project, including missing, modified, and outdated files. Other `list` commands can check workspace plugin or MCP status.

### Commands
- `status`
- `list --target plugin`
- `list --target mcp [--scope local]`

### Examples
```bash
# Check project status
npx @daominhhiep/codex-kit status

# Check workspace plugin status
npx @daominhhiep/codex-kit list --target plugin

# Check MCP status
npx @daominhhiep/codex-kit list --target mcp
npx @daominhhiep/codex-kit list --target mcp --scope local
```
```