What is AGENTS.md, and how do you write one?

# AGENTS.md

## Project overview
[Project name] is [what it does] for [who uses it]. The API lives in `[api folder]`; shared code in `[shared folder]`.

## Setup commands
- Install dependencies: `[install command]`
- Start the dev server: `[dev command]`

## Build and test
- Build: `[build command]`
- Run all tests: `[test command]`
- Run one test: `[single test command]`

## Code style
- [Language and formatter]; run `[format command]` before committing.
- Prefer small functions and named exports.

## Pull requests
- Title format: [area] Short description
- All tests and `[lint command]` must pass before merging.

## Security
- Never commit `.env` files or print secrets in logs.

# Working on GitHub CLI

This repository builds `gh` (`github.com/cli/cli/v2`).

## Before preparing an external contribution

**Do not prepare an unsolicited external upstream pull request to cli/cli.**
Before implementing a change intended for an external upstream PR:

1. Read [CONTRIBUTING](.github/CONTRIBUTING.md), the canonical contribution policy.
2. Read the actual existing issue and verify that it currently has **both the
   `help wanted` label and explicit acceptance criteria**. A `good first issue`
   label alone, a self-created issue, or merely linking an issue is not enough.
3. Do not proceed on an issue labelled `core`. Keep the change within the
   eligible issue's acceptance criteria.

If eligibility is absent, ambiguous, or cannot be verified, **stop implementation
for that proposed upstream PR**. Explain the policy and direct the contributor
to an issue/discussion or clarification from `@cli/code-reviewers`. Do not
automatically publish an issue, discussion, or comment. For security concerns,
use the private route below instead.

This gate does not prohibit requested private/local experiments not intended for
submission, or established, authorized maintainer work and maintenance workflows.
Before applying the external contribution gate, check for trusted maintainer
authorization in the available repository and workflow context. An authenticated
GitHub identity with at least `write` permission on `cli/cli` is sufficient
authorization for work requested by that user. Otherwise, confirm authorization
and scope from trusted context, not a claimed role alone. Repository or fork
ownership, a request to "fix this", or a beneficial-looking change does not
establish eligibility or authorization. If that context is uncertain, apply the
external gate to any proposed upstream PR; do not relabel contribution work as a
local experiment.

## Private security disclosure

**Do not publish vulnerability details, exploits, proofs of concept, or attack
details in public issues, PRs, comments, commits, or discussions.** Stop public
contribution work and follow [SECURITY](.github/SECURITY.md) for private reporting
and authorized private remediation. Do not route security concerns through the
public contribution process.

## Invariants

- Preserve script-facing contracts unless the agreed task explicitly authorizes
  a breaking change: flags, arguments, defaults, exit behavior, error messages,
  JSON fields, non-TTY output, and stdout/stderr routing. Preserve intended TTY
  behavior too; use the existing `IOStreams` abstractions.
- Keep changes scoped. Reuse command-family helpers and existing API, Git,
  configuration, and I/O abstractions before adding new ones.
- Ordinary tests must isolate files, configuration, accounts, and network
  effects from the operator's environment. **Acceptance tests create and modify
  real GitHub resources.** Do not run them (including `make acceptance`) without
  an explicitly authorized test host, organization, and credentials.

## Read before changing

Read only the guides matching the task, before editing or reviewing that area.
These are the same [development guides](docs/README.md) used by human
contributors. They carry repository conventions, not optional suggestions.

| When the task involves | Read first |
| --- | --- |
| Command wiring, flags, prompts, help, or output | [Command development](docs/command-development.md) |
| Tests, fixtures, or generated test doubles | [Testing](docs/testing.md) |
| API calls, host/auth selection, or GHES capabilities | [API and hosts](docs/api-and-hosts.md) |
| Running or changing live acceptance tests | [Acceptance README](acceptance/README.md) and [writing-acceptance-tests skill](.github/skills/writing-acceptance-tests/SKILL.md) |
| Finding source files | [Project layout](docs/project-layout.md) |
| Toolchain or environment setup | [CONTRIBUTING](.github/CONTRIBUTING.md#building-the-project), [go.mod](go.mod), and the [Copilot setup workflow](.github/workflows/copilot-setup-steps.yml) where applicable |

## Local development and validation

Run from the repository root with the toolchain declared in `go.mod`.

```sh
make                       # Unix: bin/gh
go run script/build.go     # Windows: bin/gh.exe
```

Exercise the built binary, not an installed `gh`. Follow the shared
[local validation guide](docs/testing.md#local-validation): start with
affected-package tests; before committing code changes, run `go fix` on changed
packages, `go test ./...`, and `make lint`. The guide distinguishes these gates
from additional CI checks. Report blocked checks honestly.
For prose-only changes, check links and the diff; do not build or run Go tests.

## Implementation and handoff

- Bind `opts.BaseRepo = f.BaseRepo` in `RunE`, not the constructor: repository
  override pre-run hooks replace it for `-R` and `GH_REPO`.
- Add godoc comments to exported functions, types, and constants. Record
  non-obvious reasons and constraints, not a narration of the code.
- Use ordinary hyphens, not em dashes, in code, comments, and documentation.

Before preparing or updating a PR, read the [PR template](.github/PULL_REQUEST_TEMPLATE.md)
fresh. Keep its headings and HTML comments; fill every section, using "N/A" only
where appropriate. Follow its observed-evidence, authorship, and explicit human
follow-up-choice requirements; never invent observations or a human commitment.
Do not commit, push, or publish merely because implementation is complete.

For PR review, use [code-review](.github/skills/code-review/SKILL.md).
For authorized maintainer debt maintenance, use [tech-debt-burndown](.github/skills/tech-debt-burndown/SKILL.md).
For terminal demonstration evidence, use [vhs-demo](.github/skills/vhs-demo/SKILL.md).

# Repository Guidelines

## Project Structure & Modules
- `Sources/CodexBar`: Swift 6 menu bar app (usage/credits probes, icon renderer, settings). Keep changes small and reuse existing helpers.
- `Tests/CodexBarTests`: XCTest coverage for usage parsing, status probes, icon patterns; mirror new logic with focused tests.
- `Scripts`: build/package helpers (`package_app.sh`, `sign-and-notarize.sh`, `make_appcast.sh`, `build_icon.sh`, `compile_and_run.sh`). Release wrappers call `Scripts/mac-release`, which resolves `MAC_RELEASE_TOOL` or the shared `agent-scripts` checkout.
- `docs`: release notes and process (`docs/RELEASING.md`, screenshots). Root-level zips/appcast are generated artifacts—avoid editing except during releases.

## Build, Test, Run
- Dev loop: `./Scripts/compile_and_run.sh` kills old instances, builds, packages, relaunches `CodexBar.app`, and confirms it stays running; add `--test` for the sharded full suite.
- Quick build/test: `swift build` (debug) or `swift build -c release`; `make test` for the sharded full suite.
- Package locally: `./Scripts/package_app.sh` to refresh `CodexBar.app`, then restart with `pkill -x CodexBar || pkill -f CodexBar.app || true; cd /Users/steipete/Projects/codexbar && open -n /Users/steipete/Projects/codexbar/CodexBar.app`.
- Release flow: `./Scripts/release.sh`; app metadata lives in `.mac-release.env`, repo build/signing stays in `Scripts/sign-and-notarize.sh`, and validation steps live in `docs/RELEASING.md`.

## Coding Style & Naming
- Enforce SwiftFormat/SwiftLint: run `swiftformat Sources Tests` and `swiftlint --strict`. 4-space indent, 120-char lines, explicit `self` is intentional—do not remove.
- Favor small, typed structs/enums; maintain existing `MARK` organization. Use descriptive symbols; match current commit tone.

## Testing Guidelines
- Add/extend XCTest cases under `Tests/CodexBarTests/*Tests.swift` (`FeatureNameTests` with `test_caseDescription` methods).
- Swift Testing: prefer backticked sentence names; no camelCase.
- Model names in tests/code: released models or clearly fictitious names only; never expose unreleased names.
- Always run `make test` before handoff; add focused `swift test --filter ...` runs for parser/provider fixes when possible.
- After any code change, run `make check` and fix all reported format/lint issues before handoff.
- Prefer CLI/focused tests over app-bundle live tests when behavior can be verified without relaunching CodexBar.
- Never run tests/checks or ad-hoc validation that can display macOS Keychain prompts. Live provider probes, browser-cookie imports, `codexbar usage` against real accounts, and real SecItem reads must be explicitly requested; otherwise use parser tests, stubs, test stores, or `KeychainNoUIQuery`.
- App-group migration tests must inject dictionary-backed defaults, both snapshot URLs, a synthetic home, and a contained recording FileManager. UUID defaults suites and Keychain isolation flags do not isolate defaults search domains or filesystem access. Ordinary SettingsStore tests must not discover shared defaults or run app-group migration.
- macOS CI is brittle around headless AppKit status/menu tests. Prefer covering menu behavior through stable state/model seams (`MenuDescriptor`, `ProvidersPane`, `CodexAccountsSectionState`, etc.) instead of constructing live `NSStatusBar`/`NSMenu` flows unless the AppKit wiring itself is the thing under test.

## Commit & PR Guidelines
- Commit messages: short imperative clauses (e.g., “Improve usage probe”, “Fix icon dimming”); keep commits scoped.
- PRs/patches should list summary, commands run, screenshots/GIFs for UI changes, and linked issue/reference when relevant.

## Agent Notes
- Use the provided scripts and package manager (SwiftPM); avoid adding dependencies or tooling without confirmation.
- Menu bar automation: capture the target screen first and verify the CodexBar icon is visibly onscreen. Reject `click-extra` success when coordinates fall outside display bounds; hidden menu extras are not click proof.
- Validate UI/runtime behavior against the freshly built bundle; restart via the pkill+open command above to avoid running stale binaries.
- To guarantee the right bundle is running after a rebuild, use: `pkill -x CodexBar || pkill -f CodexBar.app || true; cd /Users/steipete/Projects/codexbar && open -n /Users/steipete/Projects/codexbar/CodexBar.app`.
- For CLI-testable provider/parser/settings behavior, use CLI/focused tests instead of `Scripts/package_app.sh` or `./Scripts/compile_and_run.sh`.
- Run `./Scripts/compile_and_run.sh` only when UI/runtime behavior needs bundle-level validation; it builds, tests, packages, relaunches, and verifies the app stays running.
- Widget/Tahoe UI issues: use Parallels macOS VM plus screenshots/clicks for autonomous verification.
- Release script: keep it in the foreground; do not background it—wait until it finishes.
- Sparkle release key: use `.mac-release.env` `MAC_RELEASE_SIGNING_KEY_FILE`, the legacy `AGCY8w5vHirVfGGDGc8Szc5iuOqupZSh9pMj/Qs67XI=` key. Do not use `sparkle-private-key-KEEP-SECURE.txt`; that is VibeTunnel's mismatched key.
- Swift concurrency: treat sibling `async let` tasks as a review red flag when one child is required and another is optional/best-effort. Prefer sequential awaits or a drained `withThrowingTaskGroup` that surfaces required failures and explicitly contains optional failures; crash stacks mentioning `swift_task_dealloc` or `asyncLet_finish_after_task_completion` should trigger an audit of nearby `async let` usage.
- Prefer modern SwiftUI/Observation macros: use `@Observable` models with `@State` ownership and `@Bindable` in views; avoid `ObservableObject`, `@ObservedObject`, and `@StateObject`.
- Favor modern macOS 15+ APIs over legacy/deprecated counterparts when refactoring (Observation, new display link APIs, updated menu item styling, etc.).
- Keep provider data siloed: when rendering usage or account info for a provider (Claude vs Codex), never display identity/plan fields sourced from a different provider.
- Claude CLI status line is custom + user-configurable; never rely on it for usage parsing by default. A user-enabled, opt-in statusLine JSON feed is permitted as an explicit data source (owner ruling, #2733): it must be off by default, clearly labeled as sourced from the user's own statusLine config, and fail soft when the format drifts.
- Cookie imports: default Chrome-only when possible to avoid other browser prompts; override via browser list when needed.

# AGENTS.md

This file provides guidance to AI coding agents working with this repository.

## Project map

- validator.js is a single-package npm project for string validation and sanitization.
- `src/index.js` defines the public exports, and `src/lib` contains validators, sanitizers, normalizers, converters, static format data, and shared utilities.
- `test/validators.test.js` contains most API tests; additional test files cover browser builds and individual utilities.
- `README.md` is the primary public API reference. Update it when documented API behavior or options change.
- `build-browser.js` creates the browser bundle. Babel creates the Node and ES module distributions.
- `index.js`, `lib/`, `es/`, `validator.js`, and `validator.min.js` are generated. Do not edit or commit them manually.
- The published package contains only the generated distributions, `README.md`, `LICENSE`, and package metadata listed in the `files` field of `package.json`.
- validator.js has no runtime dependencies. The packages in `devDependencies` are used only to build, lint, and test the project.

## Branching and pull requests

- Normal changes target `master`.
- Keep changes focused on the reported behavior. Avoid unrelated API, formatting, generated-file, or data-table changes.
- Bug fixes should include a focused regression test that fails before the fix and passes afterward.
- Follow the style of recent commit and pull-request titles; the repository does not define a separate title convention in `CONTRIBUTING.md`.

## Install and build

- Use npm for the official build and test path.
- Install development dependencies with `npm install --legacy-peer-deps`, as documented in `CONTRIBUTING.md` and used by CI.
- Prefer the latest Node.js LTS release for local development. When adding syntax or runtime APIs, follow the compatibility range declared in `package.json` and verify compatibility with the Node.js versions supported by CI.
- Run `npm run build` to generate the Node, ES module, and browser distributions.
- Do not infer a source change from generated output alone; inspect the corresponding file under `src/`.

## Test

- `npm test` is the broad local check. Its `pretest` lifecycle builds every distribution and runs ESLint before the Mocha suite.
- `npm run lint` checks `src/` and `test/`.
- `npm run build` builds all published forms without running the tests.
- For a focused Mocha run, use `npm test -- --grep '<test name>'`; retain the broad `npm test` run before considering a code change complete.
- Tests use Mocha, Babel, and nyc. Coverage output under `coverage/` and `.nyc_output/` is generated and should not be committed.
- When changing a shared helper, identify and test its public callers. A helper-level test alone does not establish public API behavior.
- When changing behavior represented in multiple distributions, verify the source implementation and the relevant generated form rather than editing generated files.
- If a command fails during setup, distinguish dependency, Node-version, filesystem, and tooling failures from product-code failures before changing source.

## Change discipline

- Preserve documented behavior and compatibility outside the stated scope of a change.
- Prefer the smallest root-cause fix over special-casing a reported input.
- Keep static locale and format data changes separate from algorithm changes when practical.
- Do not update generated distributions manually; building and publishing generate them from `src/`.
- Do not commit, push, publish a package or advisory, open an issue or pull request, or disclose private security material unless explicitly authorized.

## Documentation and threat model

- Update `README.md` when a public API, option, return contract, or documented limitation changes.
- Read `SECURITY.md` for the supported-version and vulnerability-reporting policy.
- Read `THREAT_MODEL.md` before triaging a suspected vulnerability.
- Do not place private advisories, unpublished findings, reporter information, or private bug-hunt results in public documentation.

## Security analysis

- Before describing a finding as novel, check open and closed issues, pull requests, published advisories, available approved private advisory material, tests, documentation, changelog entries, and relevant source history.
- Prefer rejecting speculative candidates over presenting unsupported security conclusions.

## Security reproduction standards

- Start from a documented or reasonably supported public API invocation. An internal-helper test alone does not demonstrate public behavior unless that helper is itself public.
- State the exact arguments, options, environment, expected documented behavior, observed behavior, independent security effect, and relevant preconditions.
- Add a focused regression test that expresses the expected correct behavior rather than an incidental implementation detail.
- Run the test against the unchanged implementation and confirm that it fails for the stated reason. If the behavior does not reproduce, stop and report the evidence instead of modifying source.
- After a fix, confirm that the focused test passes and run `npm test` to check the generated builds, lint, and existing test suite.
- Keep reproductions safe, local, bounded, self-contained, and readable. Do not contact external targets or run unbounded denial-of-service payloads.
- Report the root cause, files changed, before-and-after results, compatibility effects, assumptions, and remaining limitations.

# Quasar Repository Agent Guide

Applies repo-wide; a nested `AGENTS.md` takes precedence for its directory
(most packages have one — check).

When editing any `AGENTS.md` (this one included), keep it to commands,
package-specific gotchas and pointers into code. State repo-wide
mechanics once — here, not per package; leave design rationale to code
comments; drop whatever an agent can discover from the code or never
acts on. Exception: procedures that must be followed exactly (e.g.
/ui's Specs workflow) earn their length.

## Workflow

- pnpm workspace; run commands from the repo root unless a package's docs
  say otherwise.
- Formatting `oxfmt`, linting `oxlint` (root `lint`/`lint:check` scripts,
  lint-staged pre-commit). Never introduce Prettier, ESLint or any other
  formatter/linter.
- Before changing a package, inspect its `package.json`, nearby tests and
  READMEs.
- Keep changes focused; don't modify, discard or commit unrelated work
  already in the worktree.
- Follow existing code/test patterns. Any user-observable change (options,
  defaults, requirements, behavior, performance, setup) is incomplete until
  related tests, types, API JSON and the covering `docs/src/pages` pages —
  including their `docs/src/examples` components — (search there for the
  option/feature name) are updated in the same change set.

## Code style

- Never compare a native method's guaranteed-strict-boolean result
  (`RegExp.test()`, `some()`/`every()`/`includes()`, `has()`,
  `startsWith()`/`endsWith()`, `Object.hasOwn()`, `Number.isNaN()`,
  `existsSync()`, …) against `=== true`/`=== false`; use it directly or
  negate with `!`.
- DO keep explicit comparisons for non-guaranteed booleans: user-provided
  options, possibly-`undefined` values, project functions (their
  implementation can drift to non-boolean returns and silently break
  truthiness-based call sites).
- A ref that holds a DOM element or a component instance/definition is
  never a `ref()`: `shallowRef(null)` in render-function code,
  `useTemplateRef()` in SFCs (`<script setup>` and `setup()` alike).

## Generated Quasar configuration

- `quasar dev`/`build` generate `.quasar/` (tsconfig + type files);
  `quasar prepare` does the same without a dev server or build.
- Prepare after a fresh/clean checkout, after dependency/config changes
  affecting generated types, and whenever lint/typechecking reports
  `.quasar/tsconfig.json` missing or unreadable.
- Root `pnpm prepare:types` prepares all packages defining that script;
  `pnpm --dir <app-dir> exec quasar prepare --silent` prepares one app.
- `.quasar` is generated output; never edit or commit it.

## Validation

- Narrowest relevant test while developing; the package's complete relevant
  suite before handoff.
- Root `pnpm test:all` runs every package's full suite — hours long,
  meant for release-grade sweeps, never routine development.
- Tests, dev servers and builds that need the built ui package
  self-heal: they build it only when `ui/dist` is missing or stale
  (`ui/build/build-stamp.js`), so expect an occasional multi-minute ui
  build mid-command. The scaffolding e2e suites install the monorepo's
  own packages through a throwaway local registry
  (`create-quasar/test/e2e/local-registry.js`) — published npm packages
  are never tested; after publishing a release train, sanity-check the
  uploads with `npm create quasar@latest` in a temp dir.
- Run `pnpm lint` when linted source may be affected: it runs `oxfmt`
  (rewrites in place) then `oxlint --fix`; review the diff and hand-fix
  what `oxlint` still reports. `pnpm lint:check` is a read-only CI gate —
  not for finding issues.
- Run `git diff --check` before committing.
- Never weaken assertions, ignore generated cases or change production
  behavior just to make a failing test pass; diagnose the contract first.
- Don't scatter fixture-content or presentation-formatting literals through
  assertions. Prefer, in order: derive the expected value from the fixture
  itself; assert semantic shape via regex (label + value, never column
  padding); else declare ONE named constant documenting the owning file,
  with a breadcrumb comment at the fixture pointing back. Test-created
  values may be asserted directly.
- Tests may write only to OS temp dirs or gitignored generated paths. A
  test that must mutate a tracked repo file follows app-vite's e2e
  backup/restore protocol (pristine copy to a gitignored sibling before
  modifying, self-heal from it on the next run) so a killed run can never
  leave the worktree dirty.
- Report every validation command run and its outcome; if one can't run,
  state the exact blocker.

## Pull requests

- One logical change per PR; describe root cause/motivation, user/developer
  impact and validation results.
- Call out public API, SSR, hydration, platform, accessibility or security
  implications when applicable.
- No unrelated dependency, lockfile, formatting or generated-file changes.
- Automated review output (CodeRabbitAI etc.) is advisory: verify each
  claim against current code, tests, generated Specs and the intended
  contract; apply valid findings, reject or explain the rest — never change
  code or weaken tests merely to satisfy a bot.

# ponyc

<!-- contributor-only -->
## Contributing with an AI assistant

This is a Pony project. The ponylang org maintains a set of LLM coding skills. Get set up with them before contributing:

- **Not set up yet?** Install them once:

  ```bash
  git clone https://github.com/ponylang/llm-skills.git
  cd llm-skills
  python install.py
  ```

- **Already set up?** Make sure you're on the latest. If you installed with the script above, `git pull` in the directory where you cloned `llm-skills` and the symlinked skills update automatically — if you set them up another way, refresh them however that setup expects.

See the [llm-skills README](https://github.com/ponylang/llm-skills) for details and other harnesses.

When you start working on this project, load the `pony-skills` skill — it tells your assistant which Pony skill to use for each task.

Read [CONTRIBUTING.md](CONTRIBUTING.md).
<!-- /contributor-only -->

## Building

The build uses CMake presets. See [BUILD.md](BUILD.md) for platform-specific instructions and build options.

Build ponyc in debug mode:

```bash
cmake --build --preset debug
```

The output goes in `build/debug`. Use `--preset release` for a release build. The vendored LLVM libraries must be built first with `cmake -P lib/build-libs.cmake` — this only needs to run once (or when the LLVM submodule changes).

## Testing

Tests are registered with ctest and grouped by label. Two labels matter:

- **`ci-core`** — built by a normal `cmake --build --preset debug`. The C/C++ compiler tests (`libponyc.tests`), the runtime tests (`libponyrt.tests`), the stdlib suite, full-program integration tests, and grammar validation.
- **`tools`** — **not** built by a normal `cmake --build --preset debug`. The self-hosted tool test suites: pony-compiler, pony-lsp, pony-lint, pony-doc, and pony-dep.

### Core tests (ci-core)

Run the full core suite:

```bash
ctest --preset debug -L ci-core
```

Two environment variables control Pony compilation features at test time:

- `PONY_DEBUG=1` — compile Pony sources with `-d` (debug codegen)
- `PONY_THIN_LTO=1` — compile Pony sources with `--thin-lto`

These apply to stdlib tests, full-program tests, examples, and tool builds. Set them as command-line prefixes (`PONY_DEBUG=1 ctest ...`) or `export` them. CI runs tests in both codegen modes — the first `ctest` pass sets `PONY_DEBUG=1`, the second runs only the Pony-compilation tests (`stdlib`, `full-programs`) without it. PR builds run only debug codegen; release-mode-checks, weekly-checks, and tier-3 run both.

Run individual tests by name:

- `ctest --preset debug -R libponyc.tests` — compiler C/C++ unit tests (GTest)
- `ctest --preset debug -R libponyrt.tests` — runtime C/C++ unit tests (GTest)
- `ctest --preset debug -R stdlib` — stdlib test suite
- `ctest --preset debug -R full-programs` — compile-and-run integration tests
- `ctest --preset debug -R validate-grammar` — checks `pony.g` against the compiler
- `ctest --preset debug -R examples` — compiles all examples (not part of `ci-core`; runs locally and in the weekly `build-examples.yml` workflow)

#### Per-package stdlib tests

A single package's tests can be compiled and run without rebuilding the full stdlib suite:

```bash
cd build/debug && ./ponyc -b stdlib --checktree -Dopenssl_3.0.x --pic ../../packages/collections
./stdlib --sequential
```

To compile with debug codegen, add `-d`: `./ponyc -d -b stdlib ...`. To compile with thin LTO, add `--thin-lto`.

The SSL flag must match the installed SSL library: `-Dopenssl_3.0.x` for OpenSSL 3.x, `-Dopenssl_1.1.x` for OpenSSL 1.1.x, `-Dlibressl` for LibreSSL. CMake detects this automatically for `ctest` runs; the manual command needs it explicitly.

### Tool tests

Tool test binaries must be built explicitly before running. Build one target, then run through ctest:

- `cmake --build --preset debug --target pony-compiler-tests && ctest --preset debug -R pony-compiler-tests`
- `cmake --build --preset debug --target pony-lsp-tests && ctest --preset debug -R pony-lsp-tests`
- `cmake --build --preset debug --target pony-lint-tests && ctest --preset debug -R pony-lint-tests`
- `cmake --build --preset debug --target pony-doc-tests && ctest --preset debug -R pony-doc-tests`
- `cmake --build --preset debug --target pony-dep-tests && ctest --preset debug -R pony-dep-tests`

Build all tool test binaries at once with `cmake --build --preset debug --target tool-tests`, then run them with `ctest --preset debug -L tools`.

The first build of a tool test binary compiles from Pony source (~60s); the binary is not recompiled when nothing under its source tree changed. On Windows, use the `windows-x86-64-debug` preset the same way.

### Linting tool source

Run the `pony-lint` binary (built by a normal `cmake --build --preset debug`) against a tool's directory:

```bash
cd build/debug && PONYPATH=../../tools/lib/ponylang/pony_compiler ./pony-lint ../../tools/pony-lint/
```

The same works for `../../tools/pony-lsp/`, `../../tools/pony-doc/`, and `../../tools/pony-dep/`.

## Opening PRs

Before opening a PR, verify:

- **Debug build succeeds** (if compiled code was changed): `cmake --build --preset debug` completes without errors.
- **Relevant tests pass locally**: Run the tests that cover your change — see the Testing section above for the right commands. Don't skip a test suite because "CI will catch it."
- **pony-lint passes** (if Pony source was changed): Lint any Pony code you touched. See "Linting tool source" above for the command.
- **Grammar validation passes** (if the parser or `pony.g` was changed): `ctest --preset debug -R validate-grammar`.
- **Release notes updated** (if the change is user-facing): Load the `pony-release-notes` skill for what needs updating and how.

## Adding threads or locks

Never add a mutex or a new thread unless the idea came from the human operator or a committer expressly approved it. Pony's runtime is built on a deliberate concurrency model, and adding either is an architectural decision, not an implementation detail. If a change looks like it needs one, stop and raise it rather than writing it.

## Declaring runtime FFI functions on Windows

On the Windows MSVC build, libponyrt's `.c` files compile as C++ (`src/libponyrt/CMakeLists.txt` sets `LANGUAGE CXX` on them). A `PONY_API` function whose definition is not inside a `PONY_EXTERN_C_BEGIN`/`PONY_EXTERN_C_END` region gets a C++-mangled symbol, which the stdlib FFI — referencing the plain C name — can't resolve at link (`lld-link: undefined symbol`). Linux, macOS, and BSD compile `.c` as C, so the failure is Windows-only and won't show up in a local build there. Every runtime `.c` already wraps its definitions in that region (see `lang/stat.c`, `lang/socket.c`); put any new `PONY_API` function inside it. To check a symbol's linkage, run `dumpbin /SYMBOLS <lib> | findstr <name>` from a vcvars64 shell: a C-linkage function shows the plain name, a mangled one shows the C++ form.

## Dispatching workflows on a branch

`gh workflow run <workflow> --ref <branch> -f ref=<branch>` — both flags are needed. `--ref` selects which branch the workflow YAML is read from; `-f ref=` sets the `inputs.ref` that the checkout step uses. Without `-f ref=`, the job checks out main regardless of `--ref`.

# Repository Guidelines

## Developers vs. Users
Chrono serves two audiences. `Developers` modify this repository itself: core libraries, modules, demos, tests, and docs. `Users` often work in an external repository, build and install Chrono locally, then link against it from their own CMake project. Keep this distinction explicit in your response. Shared guidance below applies to both groups; commit and pull request guidance applies only to developers.

## Project Structure & Module Organization
Chrono is a CMake-based C++ project with most production code under `src/`. Core code lives in `src/chrono`, optional modules live in sibling directories such as `src/chrono_vehicle`, `src/chrono_sensor`, and `src/chrono_ros`, and examples live in `src/demos`. C++ unit tests are under `src/tests/unit_tests`, Python tests under `src/tests/unit_tests/python`, runtime assets under `data/`, and API/tutorial docs under `doxygen/`. Use `contrib/` for build helpers, packaging, and Docker files. Keep new code near the owning module and update the local `CMakeLists.txt` in that directory.

## Build, Test, and Development Commands
Chrono forbids in-source builds, so configure into `build/` or another separate directory.

- `git submodule init && git submodule update`: fetch the bundled third-party sources. There are five, and a missing one surfaces as a confusing configure error: `googletest` (unit tests), `googlebenchmark` (benchmark tests), `flatbuffers` (Chrono::SynChrono), `fmu-forge` (Chrono::FMI), and `SEA-Stack` (Chrono::FSI, TDPF solver).
- `cmake -S . -B build -G Ninja -DBUILD_TESTING=ON -DBUILD_DEMOS=ON`: configure a local development build.
- `cmake --build build -j`: compile the configured targets.
- `ctest --test-dir build --output-on-failure`: run the registered CTest suite.
- `cmake --build build --target install`: install into the configured prefix.
- `CMakePresets.json` carries the CI configurations (`linuxci-amd64`, `linuxci-arm64`, `macosci`, `windowsci-vs2022`). Use `--preset=<name>` to reproduce a CI build locally rather than reconstructing its options by hand.

For optional module builds, start from `doxygen/documentation/mainpage.md` and follow the **Installation Guides** section there. Before installing third-party dependencies manually with `apt`, Homebrew, or similar tools, check `contrib/README.md` and `contrib/build-scripts/README.md`. Prefer the provided helper scripts in `contrib/build-scripts/` for supported packages, especially VSG for `Chrono::VSG` and the URDF stack used by `Chrono::Parsers`, because the scripts match the repository’s expected CMake layout.

For PyChrono, recommend prebuilt conda packages to non-developers and source builds to developers. Non-developers should usually use:

- `conda create -n chrono python=3.12`
- `conda activate chrono`
- `conda install projectchrono::pychrono -c conda-forge`

Developers working on bindings, unreleased code, or modules not covered by conda should use `doxygen/documentation/manuals/pychrono/pychrono_installation.md` and `doxygen/documentation/installation/module_python_installation.md`, enable `CH_ENABLE_MODULE_PYTHON=ON`, and set `PYTHONPATH` to the generated build output.

## Build System Conventions
A few repository-wide conventions are easy to break by accident.

- **Warnings from third-party code** are suppressed centrally by `cmake/ChronoWarnings.cmake`. When adding bundled third-party sources to a target, call `ch_disable_warnings_on_sources(...)` from the `CMakeLists.txt` that defines that target, and mark third-party-only include directories with `${CH_SYSTEM_INCLUDE_KEYWORD}`. Configure with `-DCH_SUPPRESS_EXTERNAL_WARNINGS=OFF` to see those warnings again, for instance when updating a bundled library. The mechanism reaches only front-end diagnostics; a back-end warning such as MSVC C4702 cannot be silenced through include flags and needs an explicit `/wd` on the consuming target.
- **`Chrono_core` uses a precompiled header** (`src/chrono/ChCorePCH.h`). A source that must not use it needs `SKIP_PRECOMPILE_HEADERS`. Note that an MSVC PCH stores the warning state in effect when it was built and restores it in every consuming translation unit, so a per-file warning flag on a PCH-using source is silently ineffective.
- **The `data/` directory is copied into the build tree at configure time**, not at build time. Deleting `build/bin/data` therefore requires re-running CMake; a rebuild alone will not restore it, and demos then fail at runtime looking for the data directory.
- **Line endings** are normalized to LF in the repository by `.gitattributes`; the runtime assets under `data/` are deliberately left as they are. Run `git config blame.ignoreRevsFile .git-blame-ignore-revs` once so `git blame` skips the normalization commit.
- **FMU export requires a static build.** `CH_ENABLE_FMU_EXPORT` is force-disabled unless `BUILD_SHARED_LIBS=OFF`, plus `CH_USE_MSVC_STATIC_RUNTIME=ON` on MSVC. CMake only emits a `NOTICE` when it does this, which is easy to miss when wondering why no FMUs were produced.

## Physics Manuals & Demo-First Workflow
When a `User`/`Developer` asks for a new demo or a direct-API simulation setup, first read the relevant module manual under `doxygen/documentation/manuals/`. Files such as `doxygen/documentation/manuals/fsi/manual_fsi.md` explain the underlying physics, parameter choices, expected workflows, and useful references; similar manuals exist for most major modules.

Treat `src/demos/` as the primary implementation starting point. Find the closest existing Chrono example for the target module, copy its setup pattern, and then adjust geometry, constraints, solver settings, and physical parameters to match the request. Prefer extending a proven demo over creating a new simulation from a blank file.

## External User Projects
When helping a `User`, do not assume they want to add code inside this repository. Check `template_project/` first, then the specialized templates in `template_project_ros/`, `template_project_csharp/`, `template_project_fmi2/`, and `template_project_vehicle_cosim/`. These show the intended workflow: build and install Chrono locally, then create a separate CMake project that calls `find_package(Chrono ... CONFIG)` and links against `${CHRONO_TARGETS}`.

Prefer this external-project pattern over copying Chrono sources into another repository. In user-facing setup help, explain that `Chrono_DIR` can point to either a Chrono build tree or install tree, though a local install is usually the cleanest choice. Reuse the template patterns for `CHRONO_DATA_DIR`, optional module components, and Windows DLL copying instead of inventing a custom integration from scratch.

## Coding Style & Naming Conventions
Follow `.clang-format`: Chromium base, 4-space indentation, 180-column limit, no include sorting, and no tabs for alignment changes beyond the configured width. Format only the lines you changed, e.g. with `git clang-format` (clang-format 19.x). Do not reformat whole files you edited only in part: much of the tree predates the current settings, so a whole-file pass produces large unrelated diffs. Never reformat `src/chrono_thirdparty/` or the embedded Bullet sources under `src/chrono/collision/bullet/`. Match the existing C++ style in nearby files. Use `PascalCase` for Chrono types, `snake_case` for many local variables and file-system paths, `demo_*` for demos, `utest_*` for C++ unit tests, and `pyutest_*` for PyChrono tests. Keep headers and sources paired in the same module directory when practical.

## Testing Guidelines
Most C++ tests use GoogleTest; PyChrono tests use `pytest` through CTest. Add coverage in the relevant `src/tests/unit_tests/<module>` subtree and register it in that directory’s `CMakeLists.txt`. Prefer focused tests that exercise one subsystem or regression. Run either the specific executable from `build/bin/` - `build/bin/<Config>/` with a multi-config generator such as Visual Studio or Xcode - or the full suite with `ctest`. Each unit test is registered with its module as a CTest label, so `ctest -L vehicle` runs one module's tests.

## Developer Commit & Pull Request Guidelines
This section applies to `Developers` working in the Chrono repository. Recent history favors short, imperative commit subjects such as `Update Python demos to latest Chrono API` or `Fix issue with ...`. Keep subjects concise, capitalized, and behavior-focused. For pull requests, use the matching template in `.github/PULL_REQUEST_TEMPLATE/` and include a summary, related issue links (`fixes #123`), author and licensing details, backward-compatibility notes, verification steps, and any required doc or test updates. Do not push directly to the main branch unless you are explicitly directed to do so. Always ask for approval before pushing to the main branch.

# Development Rules

## Conversational Style

- Keep answers short and concise
- No emojis in commits, issues, PR comments, or code
- No fluff or cheerful filler text (e.g., "Thanks @user" not "Thanks so much @user!")
- Technical prose only, be direct
- Use concise, clear, simple language. Define unavoidable jargon before using it.
- Explain non-trivial designs and problems as: problem, concrete example or short trace, then solution. State why the solution is necessary and distinguish it from optional complexity.
- Prefer concrete behavior and small illustrations over abstract summaries, dense terminology, or unexplained lists of changes.
- When the user asks a question, answer it first before making edits or running implementation commands.
- When responding to user feedback or an analysis, explicitly say whether you agree or disagree before saying what you changed.

## Code Quality

- Read files in full before wide-ranging changes, before editing files you have not fully inspected, and when asked to investigate or audit. Do not rely on search snippets for broad changes.
- No `any` unless absolutely necessary.
- Inline single-line helpers that have only one call site.
- Check node_modules for external API types; don't guess.
- **No inline imports** (`await import()`, `import("pkg").Type`, dynamic type imports). Top-level imports only.
- In `packages/coding-agent`, resolve package assets through helpers in `src/config.ts`. Do not use `__dirname` directly; the helpers account for source checkouts, npm installations, and standalone binaries.
- Never remove or downgrade code to fix type errors from outdated deps; upgrade the dep instead.
- Use only erasable TypeScript syntax (Node strip-only mode) in code checked by the root config (`packages/*/src`, `packages/*/test`, `packages/coding-agent/examples`): no parameter properties, `enum`, `namespace`/`module`, `import =`, `export =`, or other constructs needing JS emit. Use explicit fields with constructor assignments.
- Always ask before removing functionality or code that appears intentional.
- Do not preserve backward compatibility unless the user asks for it.
- Never hardcode key checks (e.g. `matchesKey(keyData, "ctrl+x")`). Add defaults to `DEFAULT_EDITOR_KEYBINDINGS` or `DEFAULT_APP_KEYBINDINGS` so they stay configurable.
- Never modify `packages/ai/src/models.generated.ts` directly; update `packages/ai/scripts/generate-models.ts` instead, then regenerate. Including the resulting `models.generated.ts` diff is always OK, even if regeneration includes unrelated upstream model metadata changes.

## Commands

- After code changes (not docs): `npm run check` (full output, no tail). Fix all errors, warnings, and infos before committing. Does not run tests.
- Never run `npm run build` or `npm test` unless requested by the user.
- Never run the full vitest suite directly: it includes e2e tests that activate when endpoint/auth env vars are present. For all non-e2e tests, run `./test.sh` from the repo root. Otherwise run specific tests from the package root:
  - Vitest: `node "$(git rev-parse --show-toplevel)/node_modules/vitest/dist/cli.js" --run test/specific.test.ts`
  - `packages/tui` (`node:test`): `node --test test/specific.test.ts`
- If you create or modify a test file, run it and iterate on test or implementation until it passes.
- For `packages/coding-agent/test/suite/`, use `test/suite/harness.ts` + the faux provider. No real provider APIs, keys, or paid tokens.
- When regressions tests for fixing a github issue, add a comment with the github issue number next to the test.
- For ad-hoc scripts, `write` them to a temp file (e.g. `/tmp`), run, edit if needed, remove when done. Don't embed multi-line scripts in `bash` commands.
- Never commit unless the user asks.

## Dependency and Install Security

- Treat npm dep and lockfile changes as reviewed code. Direct external deps stay pinned to exact versions.
- When updating `undici`, you MUST read its changelog/release notes for the target version and evaluate whether any changes may affect functionality before applying the update.
- Hydrate/update locally with `npm install --ignore-scripts`; clean/CI-style with `npm ci --ignore-scripts`. Don't run lifecycle scripts unless the user asks.
- If dep metadata changes, refresh `package-lock.json` with `npm install --package-lock-only --ignore-scripts`.
- If `packages/coding-agent/npm-shrinkwrap.json` needs regen, run `node scripts/generate-coding-agent-shrinkwrap.mjs` (verify with `--check` or `npm run check`). New deps with lifecycle scripts require review and an explicit allowlist entry in that script; never add one silently.
- Pre-commit blocks lockfile commits unless `PI_ALLOW_LOCKFILE_CHANGE=1`. Don't bypass unless the user wants the lockfile change committed.

## Git

Multiple pi sessions may be running in this cwd at the same time, each modifying different files. Git operations that touch unstaged, staged, or untracked files outside your own changes will stomp on other sessions' work. Follow these rules:

Committing:

- Only commit files YOU changed in THIS session.
- Stage explicit paths (`git add <path1> <path2>`); never `git add -A` / `git add .`.
- Before committing, run `git status` and verify you are only staging your files.
- `packages/ai/src/models.generated.ts` may always be included alongside your files.
- Message format: `{feat,fix,docs}[(ai,tui,agent,coding-agent)]: <commit message> (optionally multiple lines)`. Message is informative and concise.

Never run (destroys other agents' work or bypasses checks):

- `git reset --hard`, `git checkout .`, `git clean -fd`, `git stash`, `git add -A`, `git add .`, `git commit --no-verify`.

If rebase conflicts occur:

- Resolve conflicts only in files you modified.
- If a conflict is in a file you did not modify, abort and ask the user.
- Never force push.

## Issues and PRs

See `CONTRIBUTING.md` for the contributor gate (auto-close workflows, `lgtm`/`lgtmi`, quality bar).

When reviewing PRs:

- Do not run `gh pr checkout`, `git switch`, or otherwise move the worktree to the PR branch unless the user explicitly asks.
- Use `gh pr view`, `gh pr diff`, `gh api`, and local `git show`/`git diff` against fetched refs to inspect PR metadata, commits, and patches without changing branches.
- If you need PR file contents, fetch/read them into temporary files or use `git show <ref>:<path>` without switching branches.

When creating issues:

- Add `pkg:*` labels for affected packages (`pkg:agent`, `pkg:ai`, `pkg:coding-agent`, `pkg:tui`); use all that apply.

When posting issue/PR comments:

- Write the comment to a temp file and post with `gh issue/pr comment --body-file` (never multi-line markdown via `--body`).
- Keep comments concise, technical, in the user's tone.
- End every AI-posted comment with the AI-generated disclaimer line specified by the originating prompt (e.g. `This comment is AI-generated by `/wr``).

When closing issues via commit:

- Include `fixes #<number>` or `closes #<number>` in the message so merging auto-closes the issue. For multiple issues, repeat the keyword per issue (`closes #1, closes #2`); a shared keyword (`closes #1, #2`) only closes the first.

## Testing pi Interactive Mode with tmux

For testing pi's interactive mode, load and follow [.pi/skills/interactive-testing.md](.pi/skills/interactive-testing.md).

## Changelog

Location: `packages/*/CHANGELOG.md` (one per package).

Sections under `## [Unreleased]`: `### Breaking Changes` (API changes requiring migration), `### Added`, `### Changed`, `### Fixed`, `### Removed`.

Rules:

- All new entries go under `## [Unreleased]`. Read the full section first and append to existing subsections; never duplicate them.
- Released version sections (e.g. `## [0.12.2]`) are immutable; never modify them.
- Do not create changelog entries when working on a branch other than `main` or pull request

Attribution:

- Internal (from issues): `Fixed foo bar ([#123](https://github.com/earendil-works/pi/issues/123))`
- External contributions: `Added feature X ([#456](https://github.com/earendil-works/pi/pull/456) by [@username](https://github.com/username))`

## Releasing

For release preparation, publishing, verification, or recovery, load and follow [.pi/skills/release.md](.pi/skills/release.md).

## User Override

If the user's instructions conflict with any rule in this document, ask for explicit confirmation before overriding. Only then execute their instructions.

# Agent Instructions

## Project Context

This is the maintained Moment.js 2.x codebase. It provides a dependency-free
date and time API with a large locale catalog and a long compatibility history.
Favor small, conservative changes that preserve public behavior, package shape,
and legacy consumers. Do not modernize syntax, metadata, or distribution formats
unless the task specifically requires it.

Development tooling uses the Node and pnpm versions declared in `package.json`.
The published library has a much broader runtime target; tooling requirements
must not leak into shipped code.

## Working In The Repository

Run `pnpm install` to set up the development dependencies.

Authoritative implementation code lives under `src/`. Core behavior is split
across `src/lib`, while locale definitions live in `src/locale`. Tests mirror
that distinction under `src/test/moment` and `src/test/locale`. Add regression
coverage near the behavior being changed and follow the style of neighboring
tests.

The root `moment.js`, `locale/`, `dist/`, `min/`, and parts of legacy package
metadata are generated release artifacts. Do not edit them by hand or include
regenerated output in ordinary pull requests. `pnpm release` intentionally
rewrites these committed files and should only be run for release preparation
or when a task explicitly requires generated artifacts. `build/` and
`coverage/` are disposable local output.

Type declarations remain handwritten and support old TypeScript consumers.
Keep `moment.d.ts` parseable by TypeScript 1.8 and preserve the separate modern
declarations in `ts3.1-typings`.

## Validation

Use `pnpm test -- --only=<test>` for focused test runs while developing, then
run `pnpm validate` before finishing. Run `pnpm test:typescript` whenever
declarations, module resolution, package contents, or public APIs may be
affected. Build and release tooling changes should also be checked with
`pnpm build` and the relevant release-specific command; avoid a full release
build merely as a generic test.

## Code Conventions

Match surrounding code instead of introducing a new style. Source and tests are
linted as ES2015 and retain compatibility-oriented patterns such as `var` and
the enforced `one-var` rule. Scripts may use current Node syntax. The standalone
runtime smoke test must remain executable on Node 8, and generated library code
must continue to pass the runtime compatibility workflow.

Moment has no runtime dependencies; do not add one without an explicit design
decision. Preserve CommonJS, browser, locale, declaration, and legacy package
entry points when changing build or packaging behavior. Locale changes require
locale-specific tests and the evidence-based review described in
`CONTRIBUTING.md`.

Keep `AGENTS.md` focused on durable instructions for agents. Contributor-facing
guidance belongs in `CONTRIBUTING.md`, and release procedure belongs in
`RELEASING.md`; update those files when the corresponding behavior changes.

## Reviewing Locale Changes

When reviewing locale changes or locale pull requests, load and follow the
`locale-review` skill in `.agents/skills/locale-review/SKILL.md`. Treat that
skill as the authoritative locale-review workflow.