github.com/pierrecomputer/pierre (link)

# PierreJS Monorepo

## Agent Environment

Set `AGENT=1` at the start of every terminal session so Bun's test runner emits
AI-friendly output:

```bash
export AGENT=1
```

Most local moon tasks (formatters, benchmarks, worktree management) are
configured with `runInCI: 'always'` so they keep working in CI-marked shells
like agent harnesses. Tasks connected to the build graph (dev servers, prod
serves, e2e variants, publish guards) stay CI-skipped — run those with
`moonx <target> --ignore-ci-checks`, e.g.

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate

<!-- BEGIN:nextjs-agent-rules -->

# This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate

@AGENTS.md

@AGENTS.md

@AGENTS.md

---
name: theming
description:
  Use when an app uses @pierre/theming to list, resolve, select, switch,
  persist, or apply themes, including color modes, theme controllers, React
  state, UI colors, and bundled Pierre or Shiki collections.
---

# `@pierre/theming`

Use `@pierre/theming` to manage runtime themes. The package separates theme
metadata, theme resolution, selected state, and UI color mapping.

## Install

```bash
pnpm add @pierre/theming
```

Install optional peer dependencies only for the sele

---
name: theme
description:
  Use when an app needs a Pierre light or dark theme from @pierre/theme for
  Shiki, VS Code, Cursor, or Zed, including soft, vibrant, protanopia,
  deuteranopia, and tritanopia variants.
---

# `@pierre/theme`

Use `@pierre/theme` for Pierre syntax and editor themes. The package supplies
ten immutable Shiki and VS Code theme objects.

## Install

```bash
pnpm add @pierre/theme
```

## Select an API reference

| Need                                    | Reference                

---
name: diffs
description:
  Use when an app uses @pierre/diffs to render or edit code files, diffs,
  patches, merge conflicts, or CodeView review surfaces, including React,
  vanilla JavaScript, SSR, workers, annotations, selection, and custom Shiki
  languages or themes.
---

# `@pierre/diffs`

Use `@pierre/diffs` to render syntax-highlighted files and diffs. Use its
optional editor, SSR, and worker entries for those capabilities.

## Install

```bash
pnpm add @pierre/diffs
```

Install `react` and `re

---
name: tooling-and-dependencies
description:
  Use when running repo scripts, adding or changing dependencies, editing
  package.json files, installing packages, publishing packages, or deciding when
  pnpm package operations versus Bun runtime commands should be invoked.
---

# Tooling and Dependencies

## Toolchain (proto)

- Tool versions (bun, pnpm, node, moon, gh) are pinned in `.prototools` and
  managed by [proto](https://moonrepo.dev/docs/proto); its shims put the pinned
  versions on PATH inside

---
name: trees
description:
  Use when an app uses @pierre/trees to render or control a file tree, including
  React, vanilla JavaScript, SSR, web components, selection, search, rename,
  drag and drop, icons, git status, and themes.
---

# `@pierre/trees`

Use `@pierre/trees` for an interactive file tree. Public state and callbacks use
path strings.

## Install

```bash
pnpm add @pierre/trees
```

Install `react` and `react-dom` when the app uses the React entry.

## Select an API reference

| Entry      

---
name: worktrees-and-dev-servers
description:
  Use when working with the repo's moonx root:wt worktree helper, Pierre-managed
  worktrees, dev-server port offsets, stale server cleanup, Playwright fixtures,
  or Chrome debug instances. Do not use this as a substitute for host-provided
  workspace isolation.
---

# Worktrees and Dev Servers

Pierre includes a repo-specific `git worktree` helper for local/manual
parallelization outside host-managed agent workspaces. Managed Pierre worktrees
live at:

```t

---
name: browser-automation
description:
  Use when opening, inspecting, clicking, filling, snapshotting, or otherwise
  automating web pages for this repo, including local dev servers and
  browser-based verification.
---

# Browser Automation

Use `agent-browser` for web automation in this repo. Run:

```bash
agent-browser --help
```

Core workflow:

```bash
agent-browser open <url>
agent-browser snapshot -i
agent-browser click @e1
agent-browser fill @e2 "text"
```

Re-run `agent-browser snapshot -i` aft

---
name: typescript-monorepo
description:
  Use when adding or changing packages/apps, TypeScript configs, workspace
  dependencies, package references, exports, or monorepo project-reference
  relationships.
---

# TypeScript Monorepo

## TypeScript

Use TypeScript everywhere practical. Compiler settings are intentionally fairly
strict.

- Shared compiler options live in `tsconfig.options.json`.
- Root `tsconfig.json` manages project references across the monorepo.
- Typechecking uses TypeScript 7's nativ

---
name: testing-and-verification
description:
  Use when adding or running tests, checking snapshots, choosing between Bun
  tests and Playwright, running lint/format/typecheck, or deciding the
  verification scope for a change.
---

# Testing and Verification

## Baseline Commands

After code changes, run the required baseline (moon tasks run from anywhere in
the repo, including CI-marked agent shells):

```bash
moon run root:format root:lint
```

Useful check/fix pairs on the root project:

```bash
moon