# Latest Features in ag‑kit: Automated Manifests, Managed CLI, and Modern Documentation

> Discover the latest features in ag-kit including automated manifests, managed CLI, and modern Next.js documentation. Upgrade your workflow today.

- Repository: [Vũ Đỗ/ag-kit](https://github.com/vudovn/ag-kit)
- Tags: getting-started
- Published: 2026-07-29

---

**The latest features in ag‑kit introduce a fully automated managed component registry, an enhanced CLI with filesystem tree synchronization, and a JSON‑driven documentation architecture built on Next.js 16.**

The **ag‑kit** repository (`vudovn/ag-kit`) now functions as a complete Antigravity‑first AI‑agent engineering platform that unifies versioned agent definitions, command‑line tooling, and rich documentation. These latest features emphasize automation, release safety, and developer experience across three tightly integrated deliverables.

## Automated Agent Registry with Dual‑Track Versioning

The `.agents/` directory operates as a **managed component registry** that automatically maintains consistency across your agent definitions, skills, and workflows.

### Automatic Manifest Generation

Any edit to a managed component triggers regeneration of three critical files: [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json), and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md). This ensures that dependency graphs and cryptographic hashes never drift from source content. Trigger this generation manually using:

```bash
npm run generate:agents

```

### Dual‑Track Versioning System

The registry implements **CalVer** for release tracking and **SemVer** for component contracts. The overall toolkit version lives in `.agents/VERSION` (CalVer format), while individual agents and skills declare their own SemVer bumps in front‑matter metadata. This separation allows precise dependency resolution while maintaining clear release milestones.

### Strict Validation Pipeline

Before any commit or release, [`validate_kit.py`](https://github.com/vudovn/ag-kit/blob/main/validate_kit.py) (invoked via `npm run check:agents`) validates the entire toolkit structure. The Antigravity runtime layer—configured through [`hooks.json`](https://github.com/vudovn/ag-kit/blob/main/hooks.json) and the `hooks/` directory—further enforces safety via scripts like `.agents/hooks/validate-tool-call.mjs`, which intercepts and blocks raw disk writes or other dangerous filesystem operations before execution.

## Enhanced CLI with Managed Tree Synchronization

The `@vudovn/ag-kit` npm package requires Node ≥18 and provides sophisticated filesystem tracking through the new **managed tree** architecture.

### Managed Tree Tracking

The core logic in [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) maintains a real‑time shadow of the component filesystem. This tree distinguishes between auto‑generated artifacts (like manifests) and hand‑edited source files, ensuring that regeneration commands only overwrite intended targets. Inspect the tree programmatically:

```javascript
import { getManagedTree } from '@vudovn/ag-kit/lib/managed-tree.js';

const tree = getManagedTree();
console.log(tree);

```

### Release Safety Testing

The [`cli/test/release-safety.test.js`](https://github.com/vudovn/ag-kit/blob/main/cli/test/release-safety.test.js) suite enforces **version consistency** across all three [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json) files and the `.agents/VERSION` file. This prevents the common failure mode where the CLI, web documentation, and agent toolkit report different version numbers.

### Installation and Usage

Install the toolkit into any project and synchronize components:

```bash

# Install into a target project

npx @vudovn/ag-kit add

# Validate toolkit consistency

npm run check:agents

```

## Modern Documentation Architecture

The `web/` directory contains a rebuilt documentation site using Next.js 16, MDX, and Tailwind 4, featuring a complete separation between build tooling and data sources.

### JSON‑Catalog Data Layer

Rather than scanning the `.agents/` folder at build time, the site consumes static JSON catalogs located in `web/src/services/*.json`, such as [`web/src/services/agents.json`](https://github.com/vudovn/ag-kit/blob/main/web/src/services/agents.json). This architecture enables faster builds and establishes clear data contracts between the toolkit definitions and their rendered documentation.

### Webpack Build Pipeline

Due to MDX plugin constraints requiring string‑named plugin references, the project explicitly opts for **Webpack** over Turbopack. This configuration is set in [`web/next.config.ts`](https://github.com/vudovn/ag-kit/blob/main/web/next.config.ts) to ensure reliable MDX processing.

### Running the Documentation Site

Start the documentation server locally:

```bash
cd web
npm ci        # Install site‑specific dependencies

npm run dev   # Starts development server at http://localhost:3000

```

## Summary

- **Automated manifest generation** creates [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json), [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) automatically when you run `npm run generate:agents`.
- **Dual‑track versioning** combines CalVer for releases (stored in `.agents/VERSION`) with SemVer for individual component front‑matter.
- **Managed tree synchronization** via [`cli/lib/managed-tree.js`](https://github.com/vudovn/ag-kit/blob/main/cli/lib/managed-tree.js) prevents drift between source files and generated artifacts.
- **Release‑safety tests** ensure version alignment across all [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json) files before publishing.
- **JSON‑driven documentation** in `web/src/services/` enables faster builds and clearer data separation.

## Frequently Asked Questions

### How do I regenerate the agent manifests after making changes?

Run `npm run generate:agents` from the repository root, or use `npx @vudovn/ag-kit generate:agents` explicitly. This command triggers the managed component registry to rebuild [`manifest.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.json), [`manifest.lock.json`](https://github.com/vudovn/ag-kit/blob/main/manifest.lock.json), and [`DEPENDENCY_GRAPH.md`](https://github.com/vudovn/ag-kit/blob/main/DEPENDENCY_GRAPH.md) based on the current state of the `.agents/` directory.

### What prevents version mismatches between the CLI and the agent toolkit?

The [`cli/test/release-safety.test.js`](https://github.com/vudovn/ag-kit/blob/main/cli/test/release-safety.test.js) suite automatically validates that version numbers in all three [`package.json`](https://github.com/vudovn/ag-kit/blob/main/package.json) files match the CalVer release declared in `.agents/VERSION`. This test runs during the release process and blocks publication if any divergence is detected.

### Why does the documentation site use Webpack instead of Turbopack?

The MDX plugin requires string‑named plugin references that are incompatible with Turbopack's architecture. As configured in [`web/next.config.ts`](https://github.com/vudovn/ag-kit/blob/main/web/next.config.ts), the project explicitly opts for Webpack to ensure reliable MDX processing during the build pipeline.

### How does ag‑kit block dangerous filesystem operations?

The Antigravity runtime loads hooks from the `.agents/hooks/` directory, specifically `validate-tool-call.mjs`, which intercepts tool calls before execution. This hook validates operations against a safety policy that blocks raw disk writes and other potentially destructive filesystem modifications.