chore: add agents and contributing md files

Author: aallam

AGENTS.md

@@ -0,0 +1,55 @@
+# AGENTS.md
+
+## Project Overview
+
+- `execbox` is a Node.js 22+ npm workspace that publishes the `@execbox/*` package family.
+- Core source lives under `packages/*/src`, tests live under `packages/*/__tests__`, runnable examples live under `examples/`, and the public docs site lives under `docs/`.
+- The workspace currently contains `@execbox/core`, `@execbox/protocol`, `@execbox/quickjs`, `@execbox/remote`, `@execbox/process`, `@execbox/worker`, and `@execbox/isolated-vm`.
+- Keep changes aligned with existing package boundaries. Prefer changing the owning package instead of introducing cross-package shortcuts.
+
+## Setup Commands
+
+- Install dependencies: `npm ci`
+- Lint: `npm run lint`
+- Type-check: `npm run typecheck`
+- Test default workspace lanes: `npm test`
+- Build published packages: `npm run build`
+- Build docs site: `npm run docs:build`
+- Run security-focused suites: `npm run test:security`
+- Run isolated-vm tests only when needed: `npm run test:isolated-vm`
+- Run the full isolated-vm verification lane: `npm run verify:isolated-vm`
+
+## Codebase Conventions
+
+- Do not edit generated `dist/` output under `packages/*/dist`; build artifacts are produced from source.
+- Preserve the existing ESM + TypeScript workspace structure and root script orchestration.
+- When you change exported APIs in `packages/*/src`, keep JSDoc in sync. ESLint requires JSDoc coverage for exported package symbols.
+- Prefer inline type imports where possible; the ESLint config enforces `@typescript-eslint/consistent-type-imports`.
+- Update examples or docs when you change public package behavior, developer workflow, or recommended runtime choices.
+
+## Testing Instructions
+
+- For most code changes, run `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`.
+- If you change docs site content, navigation, or VitePress config, also run `npm run docs:build`.
+- If you touch execution boundaries, timeout handling, abort propagation, schema validation, or log/memory controls, also run `npm run test:security`.
+- If you touch `@execbox/isolated-vm` or codepaths guarded by `VITEST_INCLUDE_ISOLATED_VM`, run `npm run test:isolated-vm` or `npm run verify:isolated-vm`.
+
+## Security Notes
+
+- The provider and tool surface is the real capability boundary. Treat additions to provider exposure as security-relevant changes.
+- Preserve JSON-only boundaries, schema validation, bounded logs, timeout handling, memory controls, and abort propagation semantics.
+- Do not describe in-process runtimes as a hard security boundary for hostile or multi-tenant code. The current project security model is documented in `docs/security.md`.
+
+## Release Notes
+
+- Use Conventional Commits for git commit messages, for example `docs: add agent and contributor guides` or `fix(worker): handle timeout classification`.
+- Published package releases are managed with Changesets and GitHub Actions.
+- Add a `.changeset/*.md` entry when a change affects published package behavior, public APIs, or release notes for one or more `@execbox/*` packages.
+- Skip a changeset for docs-only, examples-only, CI-only, or internal maintenance changes that do not affect published package behavior.
+
+## Useful References
+
+- Start with `README.md` for the package map.
+- Use `docs/getting-started.md` for install and example expectations.
+- Use `docs/security.md` and `docs/architecture/README.md` before changing execution boundaries or runtime claims.
+- For the human-oriented contribution workflow, see `CONTRIBUTING.md`.

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.md

@@ -0,0 +1,46 @@
+# Contributing
+
+Thanks for contributing to `execbox`.
+
+This guide is for both humans and coding agents. Agent-specific operating instructions live in `AGENTS.md`.
+
+## Development Setup
+
+- Use Node.js 22 or newer. CI runs on Node 22 and Node 24.
+- Install dependencies with `npm ci`.
+- The repo is an npm workspace. Packages live under `packages/`, runnable examples live under `examples/`, and the public docs site lives under `docs/`.
+
+## Working In This Repo
+
+- Make changes in the package that owns the behavior you are updating.
+- Keep exported API documentation current when you change exported symbols in `packages/*/src`; the ESLint config requires JSDoc for exported package APIs.
+- Update tests with behavior changes.
+- Update examples and docs when public behavior, recommended setup, or runtime tradeoffs change.
+
+## Verification
+
+- General code changes: `npm run format:check`, `npm run lint`, `npm run typecheck`, `npm test`, and `npm run build`
+- Docs site changes: `npm run docs:build`
+- Security or execution-boundary changes: `npm run test:security`
+- `@execbox/isolated-vm` changes: `npm run test:isolated-vm` or `npm run verify:isolated-vm`
+
+Choose the smallest verification set that covers your change, and include the commands you ran in your PR or handoff notes when the context would help reviewers.
+
+## Changesets
+
+- Add a `.changeset/*.md` file for user-facing changes to published `@execbox/*` packages.
+- Skip changesets for docs-only, examples-only, CI-only, or internal refactors that do not change published package behavior.
+- Keep the changeset summary focused on the externally visible change.
+
+## Commits
+
+- Use Conventional Commits for git commit messages.
+- Pick the smallest truthful type for the primary change, such as `docs`, `fix`, `feat`, `refactor`, `test`, or `ci`.
+- Keep the subject concise and imperative, for example `docs: document contributor workflow`.
+
+## Pull Requests
+
+- Keep each PR focused on one change or closely related set of changes.
+- Mention which packages, examples, or docs areas are affected.
+- Call out any docs, example, test, or changeset updates that are part of the change.
+- If you change runtime boundaries, security-sensitive behavior, or public API expectations, say so explicitly in the PR description.

README.md

@@ -31,5 +31,5 @@ Runnable examples live in [`examples/`](./examples/) and are indexed in [`exampl
 ## Docs
 
 - [Public Docs](https://execbox.aallam.com)
+- [Getting Started Guide](./docs/getting-started.md)
 - [Execbox Architecture Overview](./docs/architecture/README.md)
-- [QuickJS Pooling Baseline](./docs/performance/quickjs-pooling-baseline.md)