project-config.md

Project Configuration

mai.toml

Project manifest declaring dependencies.

Structure

[project]
name = "my-project"
version = "1.0.0"
description = "Description"

[dependencies]
# Exact version
my-pack = "1.2.3"

# Semver range
another-pack = "^1.2.3"

# Patch-level
patch-pack = "~1.2.3"

# Range
range-pack = ">=1.0.0, <2.0.0"

Version Operators

Operator	Description	Example
=	Exact	=1.2.3
^	Compatible (minor/patch)	^1.2.3 → >=1.2.3, <2.0.0
~	Patch-level	~1.2.3 → >=1.2.3, <1.3.0
>	Greater than	>1.0.0
>=	Greater or equal	>=1.0.0
<	Less than	<2.0.0
<=	Less or equal	<=2.0.0

---

mai.lock

Auto-generated by mai project sync. Pins exact versions with hashes.

Structure

version = 1

[[packages]]
name = "my-pack"
version = "1.2.3"
source = "https://..."
integrity = "sha256:abc123..."

Fields

Field	Description
version	Format version
name	Package name
version	Exact resolved version
source	Source URL
integrity	SHA-256 hash

---

Workflow

1. Initialize

mai project init

2. Add dependencies

mai install my-pack@^1.0.0

3. Sync

mai project sync

4. Verify

mai project check

---

Best Practices

1. Commit mai.lock — Reproducible builds
2. Use semver ranges — ^ for automatic compatible updates
3. Pin critical deps — Exact versions for stability
4. Regular sync — Keep lock file current
5. Verify in CI — mai project check