mai-cli 0.2.0

AI tooling package manager - Manage skills, commands, and MCP connectors for AI agents (Qwen, Claude, etc.)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# AGENTS.md

**mai** — AI tooling package manager. Rust CLI (edition 2024).

## Quick Context

| Purpose | Manage skills/commands/MCPs for AI tools (Qwen, Claude, etc.) |
|---------|---------------------------------------------------------------|
| Entry | `src/main.rs` → `cli::Cli` (clap) |
| Core | `src/core/` — pure domain logic (no I/O) |
| Storage | `src/storage/` — XDG paths, registry, lockfile |
| Config | `~/.config/mai/`, `~/.local/share/mai/`, `.mai/` (local) |

## Module Boundaries

```
cli/       → core + storage + manifest  (orchestrates)
core/      → nothing                     (pure types)
storage/   → core                        (file I/O)
```

## Key Types

```rust
Pack { name, pack_type: PackType, version: Version, tool, metadata, scope: InstallScope }
InstallScope { Global, Local }
Version { major, minor, patch }
MaiConfig { active_tool, tools: HashMap<String, ToolConfig> }
ProjectManifest { project: ProjectInfo, dependencies: Vec<DependencySpec> }
LockFile { version, packs: HashMap<String, Vec<LockedDependency>> }
```

## Installation Scopes

mai supports two installation scopes (like `cargo`):

- **Local** (default): `.mai/` in project root — project-specific packs
- **Global**: XDG dirs (`~/.config/mai/`, `~/.local/share/mai/`, `~/.cache/mai/`) or fallback `~/.mai/`

Resolution order: **Local first**, then Global (local overrides global).

## Commands

| Command | File | Purpose |
|---------|------|---------|
| `mai use` | `cli/use_cmd.rs` | Switch active AI tool |
| `mai install` | `cli/install_cmd.rs` | Install pack (local by default, `-g` for global) |
| `mai list` | `cli/list_cmd.rs` | List packs (`--global`, `--local` filters) |
| `mai project` | `cli/project_cmd.rs` | Init/sync project |
| `mai remove` | `cli/remove_cmd.rs` | Remove pack (`-g` for global) |
| `mai update` | `cli/update_cmd.rs` | Update pack (`-g` for global) |
| `mai completions` | `cli/completions_cmd.rs` | Shell completions |

## Files to Read First

1. `TODO.md` — current phase, next actions
2. `.ai-factory/AI_OPTIMIZATION_PLAN.md` — optimization goals
3. `src/core/pack.rs` — domain types (Pack, InstallScope, PackType)
4. `src/storage/xdg.rs` — path handling (XDG + local .mai/)
5. `src/storage/registry.rs` — pack storage (dual-scope support)

## Conventions

- **Naming**: `snake_case` vars, `PascalCase` types
- **Errors**: `anyhow::Result` app, custom enums domain
- **Comments**: Only "why", not "what"
- **Tests**: One per function, minimal setup
- **Files**: Max 500 lines

## Build & Test

```bash
cargo build
cargo test
cargo clippy -- -D warnings
```

## XDG Paths

| Dir | Path | Fallback |
|-----|------|----------|
| Config | `~/.config/mai/config.toml` | `~/.mai/config/` |
| Data | `~/.local/share/mai/` | `~/.mai/packs/` |
| Cache | `~/.cache/mai/` | `~/.mai/cache/` |

## Local Project Paths

| Dir | Path |
|-----|------|
| Config | `<project>/.mai/config/config.toml` |
| Data | `<project>/.mai/packs/` |
| Cache | `<project>/.mai/cache/` |

## Project Files

| File | Purpose |
|------|---------|
| `mai.toml` | Project manifest (dependencies) |
| `mai.lock` | Pinned versions + hashes |
| `.mai/` | Local project storage (not committed by default) |

## Pack Concept

A **pack** is a set of AI tools/utilities:
- **Skills** — AI agent capabilities
- **Commands** — CLI tools for AI assistants  
- **MCPs** — Model Context Protocol connectors

Packs are **tool-specific** — install separately for each AI tool. Use `mai use <tool>` to switch.