# Root-Level Files in BuilderIO/agent-native: Complete Repository Structure Guide

> Explore root-level files in BuilderIO/agent-native, including package.json, agent-native.json, and wrangler config. Understand the repository structure for efficient development.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-07-01

---

**The BuilderIO/agent-native repository root contains 30+ configuration files, documentation, and directories including [`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json), [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json), multiple `wrangler-*.toml` files, and workspace directories like `scripts/` and `docs/`.**

Understanding the root-level files in BuilderIO/agent-native is essential for navigating this monorepo framework. The repository root serves as the command center for the Agent-Native project, containing configuration manifests, Cloudflare Wrangler deployment files, and workspace definitions that bootstrap the entire system according to the source code structure.

## Complete Inventory of Root-Level Files

The repository root contains a mix of JSON manifests, TOML configuration files, YAML workspace definitions, Markdown documentation, and essential directories. Here is the complete list of files located directly in the repository root.

### Configuration Manifests

- **[`package.json`](https://github.com/BuilderIO/agent-native/blob/main/package.json)** – Defines the monorepo's dependencies, scripts, and metadata
- **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** – Central manifest that tells the CLI which templates, skills, and defaults to use when scaffolding new projects
- **[`app.json`](https://github.com/BuilderIO/agent-native/blob/main/app.json)** – Application configuration for the native mobile build
- **[`eas.json`](https://github.com/BuilderIO/agent-native/blob/main/eas.json)** – Expo Application Services configuration for build and submit profiles
- **[`registry.json`](https://github.com/BuilderIO/agent-native/blob/main/registry.json)** – Package registry configuration for the framework components
- **[`opencode.json`](https://github.com/BuilderIO/agent-native/blob/main/opencode.json)** – OpenCode-specific configuration settings
- **[`.cache_meta.json`](https://github.com/BuilderIO/agent-native/blob/main/.cache_meta.json)** – Metadata cache for build optimization

### Cloudflare Wrangler Configurations

The repository includes multiple TOML files for different Cloudflare Workers deployments:

- **[`wrangler-analytics.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-analytics.toml)**
- **[`wrangler-calendar.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-calendar.toml)**
- **[`wrangler-calorie-tracker.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-calorie-tracker.toml)**
- **[`wrangler-chat.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-chat.toml)**
- **[`wrangler-clips.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-clips.toml)**
- **[`wrangler-content.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-content.toml)**
- **[`wrangler-dispatch.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-dispatch.toml)**
- **[`wrangler-forms.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-forms.toml)**
- **[`wrangler-mail.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-mail.toml)**
- **[`wrangler-slides.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-slides.toml)**
- **[`wrangler-videos.toml`](https://github.com/BuilderIO/agent-native/blob/main/wrangler-videos.toml)**

### Workspace and Package Management

- **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** – Defines the monorepo structure for pnpm, specifying which directories contain workspace packages
- **[`pnpm-lock.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-lock.yaml)** – Lock file ensuring reproducible dependency installs across environments

### Documentation Files

- **[`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md)** – Primary entry point explaining the framework's purpose and quickstart guide
- **[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** – Defines the "always-on" rules, architecture contracts, and high-level workflow guidelines for contributors
- **[`DEVELOPMENT.md`](https://github.com/BuilderIO/agent-native/blob/main/DEVELOPMENT.md)** – Setup instructions, development workflows, and contribution guidelines

### Tooling and Linting Configuration

- **[`.oxlintrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxlintrc.json)** – OX Linter configuration for code quality enforcement
- **[`.oxfmtrc.json`](https://github.com/BuilderIO/agent-native/blob/main/.oxfmtrc.json)** – OX Formatter configuration for code style consistency
- **`.prettierignore`** – Specifies files and directories for Prettier to ignore
- **`.gitignore`** – Git ignore patterns for the repository
- **`.nvmrc`** – Specifies the Node.js version required for the project

### Root-Level Directories

Five key directories live at the repository root:

- **`scripts/`** – Contains helper scripts for CI, development tooling, and repository maintenance
- **`docs/`** – Documentation source files and guides
- **`.github/`** – GitHub Actions workflows, issue templates, and repository configuration
- **`.changeset/`** – Changeset configuration for versioning and changelog generation
- **`.agents/`** – Agent-specific configuration and rule definitions

## Key Files for Daily Development

While the repository contains over 30 root-level items, several files serve as the primary interaction points for developers working with the BuilderIO/agent-native codebase.

### agent-native.json

The **[`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json)** file acts as the central manifest for the framework. Located at the repository root, this file tells the Agent-Native CLI which templates, skills, and default configurations to apply when scaffolding new projects. According to the source code structure, this file is essential for the framework's code generation capabilities.

### pnpm-workspace.yaml

The **[`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml)** file defines the monorepo boundaries for pnpm. As implemented in BuilderIO/agent-native, this YAML file typically specifies workspace packages using glob patterns like `packages/*`, enabling the package manager to link dependencies across the monorepo efficiently.

### AGENTS.md

Unlike typical documentation, **[`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md)** serves as an architectural contract. This root-level Markdown file defines the "always-on" rules and high-level workflow guidelines that govern how contributors interact with the codebase. It functions as the constitution for the project's development practices.

## Working with Root Files Programmatically

When building tooling or automation scripts for the BuilderIO/agent-native repository, you often need to interact with these root-level files programmatically.

### Listing Root Files with Node.js

To enumerate all files in the repository root while excluding directories (useful for build scripts or validation tools):

```typescript
import { readdir } from 'node:fs/promises';
import { join } from 'node:path';

async function listRootFiles() {
  const rootPath = join(import.meta.dirname, '..'); // assumes script lives in a sub-folder
  const entries = await readdir(rootPath, { withFileTypes: true });
  const files = entries
    .filter(e => e.isFile())      // only files (ignore directories)
    .map(e => e.name);
  console.log('Root-level files:');
  console.log(files.join('\n'));
}

listRootFiles().catch(console.error);

```

This script filters out directories like `scripts/` and `docs/`, returning only the configuration files and documentation at the repository root.

### Loading Workspace Configuration

To programmatically read the monorepo structure defined in [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml):

```typescript
import { readFile } from 'node:fs/promises';
import yaml from 'js-yaml';
import { join } from 'node:path';

async function loadWorkspaceConfig() {
  const path = join(process.cwd(), 'pnpm-workspace.yaml');
  const raw = await readFile(path, 'utf8');
  const config = yaml.load(raw);
  console.log('Workspace packages:', config.packages);
}

loadWorkspaceConfig();

```

This pattern is essential for custom build tools that need to understand which packages belong to the Agent-Native workspace.

## Summary

The root-level files in BuilderIO/agent-native provide the foundation for this monorepo framework:

- **30+ configuration files** reside in the repository root, including JSON manifests, TOML deployment configs, and YAML workspace definitions
- **Multiple Wrangler configurations** (`wrangler-*.toml`) support different Cloudflare Workers deployments for analytics, chat, calendar, and other services
- **Key interaction points** include [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) for CLI scaffolding, [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) for monorepo management, and [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) for development guidelines
- **Five root directories** (`scripts/`, `docs/`, `.github/`, `.changeset/`, `.agents/`) contain nested tooling, documentation, and configuration

## Frequently Asked Questions

### What is the purpose of agent-native.json in the root directory?

The [`agent-native.json`](https://github.com/BuilderIO/agent-native/blob/main/agent-native.json) file serves as the central manifest that configures the Agent-Native CLI. It specifies which templates, skills, and default settings to use when scaffolding new projects within the framework. Located at the repository root, this file is essential for the code generation capabilities and project initialization workflows.

### Why are there multiple wrangler-*.toml files in the repository root?

Each `wrangler-*.toml` file configures a specific Cloudflare Workers deployment for different services in the Agent-Native ecosystem. The repository includes separate TOML files for analytics, calendar, chat, clips, content, dispatch, forms, mail, slides, and videos—allowing each microservice to have independent deployment configurations, environment variables, and routing rules.

### How does pnpm-workspace.yaml define the monorepo structure?

The [`pnpm-workspace.yaml`](https://github.com/BuilderIO/agent-native/blob/main/pnpm-workspace.yaml) file uses glob patterns (typically `packages/*`) to tell the pnpm package manager which directories contain workspace packages. This enables the monorepo to link dependencies between internal packages, share node_modules efficiently, and run scripts across the workspace from the repository root.

### What information does AGENTS.md contain compared to README.md?

While [`README.md`](https://github.com/BuilderIO/agent-native/blob/main/README.md) provides the general project overview and quickstart instructions for users, [`AGENTS.md`](https://github.com/BuilderIO/agent-native/blob/main/AGENTS.md) defines the architectural contract and "always-on" rules for contributors. It specifies the high-level workflow guidelines, development conventions, and governance rules that maintain consistency across the BuilderIO/agent-native codebase.