From ed135670c511fc09c757c5c30e89c6b718a47ac4 Mon Sep 17 00:00:00 2001
From: "caffeine-ci-generic-rw[bot]"
 <caffeine-ci-generic-rw[bot]@users.noreply.github.com>
Date: Mon, 6 Jul 2026 07:49:51 +0000
Subject: [PATCH] docs: seed AGENTS.md

---
 AGENTS.md | 33 +++++++++++++++++++++++++++++++++
 CLAUDE.md |  1 +
 2 files changed, 34 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..82f71ef
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,33 @@
+# AGENTS.md
+
+`motoko` is a Node.js/browser library that compiles and runs Motoko smart contracts by wrapping the Motoko compiler (`moc`).
+
+## Commands
+
+- Build: `npm run build` (removes `lib/`, then compiles TypeScript with `tsc -p .`).
+- Test: `npm test` (Jest via `ts-jest`).
+- Format: `prettier --write <files>` (config in `.prettierrc`; enforced on commit).
+- Size check: `npm run size-limit`.
+- Regenerate compiler artifacts: `npm run generate -- <moc_version> <core_version>` (see below).
+
+Node 22.x and 24.x are the versions exercised in CI. Install deps with `npm ci`.
+
+## Layout (non-obvious)
+
+- `src/` — TypeScript source; compiled output goes to `lib/`.
+- `versions/latest/` — bundled minified `moc` compiler builds.
+- `packages/latest/` — bundled Motoko core package (`core.json`).
+- `contrib/generated/` — generated data (e.g. `errorCodes.json`).
+- `utils/generate.js` — script that produces the bundled compiler, core package, and error codes.
+- `contrib/` — editor/tooling integrations (highlight.js, Monaco, snippets).
+- `index.js` / `interpreter.js` — entry points re-exporting from `lib/`.
+
+## Conventions & gotchas
+
+- Never hand-edit generated content: `lib/` (build output, gitignored), `versions/latest/`, `packages/latest/`, and `contrib/generated/`. Update these only via `npm run generate`.
+- `motoko-src/` is a transient clone created during generation and is gitignored; do not commit it.
+- Prettier settings are enforced: single quotes, semicolons, 4-space tabs, trailing commas. `lib/generated` is excluded from formatting.
+- A Husky `pre-commit` hook runs `npm run precommit` (`lint-staged`), which formats staged JS/TS in `lib/`, `contrib/`, and `utils/`.
+- `.npmrc` sets `min-release-age=7`, delaying adoption of newly published dependency versions.
+- Publishing is automated: pushing a changed `version` in `package.json` to `main` triggers an npm publish, so bump the version deliberately.
+- The `generate` script expects a checkout of the Motoko compiler repo, located via the `MOTOKO_REPO` environment variable (or auto-detects the latest release if version args are omitted).
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..10ddb19
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+See @AGENTS.md