docs: add AGENTS.md and llms.txt for AI agents

Co-authored-by: Cursor <[email protected]>

.cursor/rules/architecture.mdc

@@ -1,17 +0,0 @@
----
-description: Architecture overview for liquidjs internals
-alwaysApply: true
----
-
-## Async/sync duality via generators
-
-All core logic is written once as a `Generator` function (`function *`). Use `yield` where you'd normally `await` a potentially async value.
-
-- `toPromise(generator)` drives it **asynchronously** — awaits yielded promises.
-- `toValueSync(generator)` drives it **synchronously** — passes yielded values through as-is.
-
-Never duplicate logic into separate async and sync methods. A single generator serves both paths.
-
-When wrapping an async+sync function pair (e.g. `contains`/`containsSync`, `exists`/`existsSync`, `readFile`/`readFileSync`), use `toLiquidAsync(asyncFn, syncFn?)` which returns a `LiquidAsync<F>` — one function that picks the sync or async implementation based on a leading `sync: boolean` arg. Then `yield` the result inside a generator to let the driver handle it in both modes.
-
-See `src/util/async.ts`.

.cursor/rules/conventions.mdc

@@ -1,6 +0,0 @@
----
-description: Project conventions for liquidjs
-alwaysApply: true
----
-
-- Keep edits minimal: change only what the task requires, match existing style.

.cursor/rules/testing.mdc

@@ -1,17 +0,0 @@
----
-description: Testing conventions — e2e uses built dist, integration uses src
-globs: test/**/*.ts
-alwaysApply: false
----
-
-# Testing
-
-## End-to-end tests (`test/e2e`)
-
-- **Use the built package**, not TypeScript sources under `src/`.
-- Import the public API from the package root (for example `import { Liquid } from '../..'`), which resolves through `package.json` to **`dist/`** (`main`, `module`, etc.).
-- **Avoid** `import … from '../../src/liquid'` (or other `src/` paths) in `test/e2e/**` so e2e matches what consumers get from npm and you do not depend on an unbuilt tree.
-
-## Integration and unit tests
-
-- Tests under `test/integration/`, `src/**/*.spec.ts`, and similar may import from **`src/`** when the suite is meant to run against the current TypeScript sources (typical for this repo’s Jest setup).

AGENTS.md

@@ -0,0 +1,94 @@
+# LiquidJS
+
+Shopify / GitHub Pages compatible Liquid template engine. TypeScript in `src/`, bundles in `dist/`. Docs site in `docs/` (Hexo, `navy` theme).
+
+## Layout
+
+| Path | Contents |
+| --- | --- |
+| `src/parser`, `src/render`, `src/tags`, `src/filters` | Template parse and render |
+| `src/context`, `src/template`, `src/tokens` | Scope, templates, token stream |
+| `src/util/async.ts` | `toPromise`, `toValueSync`, `toLiquidAsync` |
+| `test/` | Jest |
+| `docs/source/` | Doc markdown; sidebar in `docs/source/_data/sidebar.yml` |
+| `docs/themes/navy/` | Layout, CSS, JS |
+| `.local/` | Scratch, repro, PoC (gitignored) |
+
+## Commands
+
+```
+npm run build          # after src/ changes, before npm test
+npm test
+npm run lint
+npm run check          # build + build:docs + test + lint + perf:diff (manual)
+npm run build:docs
+cd docs && npm start   # http://localhost:4000
+npm run perf:diff
+```
+
+PR CI (`pull_request`): build, lint, test, coverage, performance. Docs build runs on push to `master` only.
+
+PR titles: conventional format (`feat:`, `fix:`, `docs:`, …) — checked by CI. Releases on `master` use semantic-release from merged commits.
+
+Backward-compatible API changes expected unless doing an intentional major break.
+
+## Architecture
+
+All core logic is one `function *` per feature. Use `yield` where you'd normally `await` a potentially async value.
+
+- `toPromise(generator)` — async driver; awaits yielded promises
+- `toValueSync(generator)` — sync driver; passes yielded values through as-is
+
+Never duplicate logic into separate async and sync methods. One generator serves both paths.
+
+When wrapping an async+sync pair (e.g. `contains`/`containsSync`, `readFile`/`readFileSync`), use `toLiquidAsync(asyncFn, syncFn?)` — returns a `LiquidAsync<F>` that picks sync or async via a leading `sync: boolean` arg. `yield` the result inside a generator. See `src/util/async.ts`.
+
+## Style
+
+Make minimal changes only. Avoid sweeping edits. Always check after you made changes.
+
+- Change only what the task requires. No drive-by refactors, test harnesses, or extra files unless asked.
+- Match existing patterns in the file you edit.
+- Repro, PoC, and scratch files go in `.local/` — not tracked `poc/` folders or one-off scripts under `docs/`.
+
+### Comments
+
+- Do not add narrative comments. Code should be clear from structure and naming; if it needs explanation, refactor instead.
+- Comments follow existing repo usage only: non-obvious invariants, `@deprecated`, JSDoc on public API where TypeDoc needs it. Not for explaining changes to the author, migration history, or restating what the code already says.
+- Comments document the code; they do not fix unclear code.
+
+### Tests
+
+- Assert observable behavior, not internal implementation details.
+- Avoid duplicate coverage; keep test diffs minimal.
+- **E2E** (`test/e2e/`): import from the package root (resolves to `dist/` via `package.json`). Do not import from `src/` — e2e must match what npm consumers get.
+- **Integration/unit** (`test/integration/`, etc.): may import from `src/` against current TypeScript sources.
+
+### Docs site
+
+- Reuse existing asset paths under `docs/source/` and `docs/themes/navy/` — no new asset directories unless asked.
+- Front matter `title:` is plain text (no backticks).
+- `docs/source/llms.txt` — deployed to https://liquidjs.com/llms.txt for web agents (llms.txt spec).
+- After theme/markdown changes: build or serve locally, check in a browser (light and dark), not only curl or editor preview.
+
+### README
+
+- Research original sources before reordering contributors, logos, or lists.
+
+## Verify
+
+- Do not commit, push, amend, or open a PR unless asked.
+- After changes: verify yourself via CLI or UI (tests, `cd docs && npm start`, browser) before reporting done. Do not tell the user to check instead.
+- Before push on sweeping changes: run `npm run check`.
+- Confirm facts from `.github/workflows`, `package.json`, and library docs — not stale human docs or assumptions.
+- When replacing or integrating a library: read its docs and understand what the previous setup did before changing behavior.
+
+### Security fixes
+
+- Reproduce on current `master` first. Smallest fix that addresses the reported issue.
+- If Shopify/Ruby Liquid behaves the same, document unsafe usage in filter/docs instead of changing behavior.
+
+## Docs
+
+- Published: https://liquidjs.com
+- Repo agent instructions: this file (`AGENTS.md`)

docs/source/llms.txt

@@ -0,0 +1,28 @@
+# LiquidJS
+
+> A simple, expressive and safe Shopify / Github Pages compatible template engine in pure JavaScript.
+
+## Tutorials
+
+- [Introduction to Liquid](https://liquidjs.com/tutorials/intro-to-liquid.html)
+- [Setup](https://liquidjs.com/tutorials/setup.html)
+- [Options](https://liquidjs.com/tutorials/options.html)
+- [Render files](https://liquidjs.com/tutorials/render-file.html)
+- [Partials and layouts](https://liquidjs.com/tutorials/partials-and-layouts.html)
+- [Express.js](https://liquidjs.com/tutorials/use-in-expressjs.html)
+- [Register filters and tags](https://liquidjs.com/tutorials/register-filters-tags.html)
+- [Plugins](https://liquidjs.com/tutorials/plugins.html)
+- [Sync and async](https://liquidjs.com/tutorials/sync-and-async.html)
+- [Operators](https://liquidjs.com/tutorials/operators.html)
+- [Truthy and falsy](https://liquidjs.com/tutorials/truthy-and-falsy.html)
+- [Security model](https://liquidjs.com/tutorials/security-model.html)
+- [Differences from Shopify Liquid](https://liquidjs.com/tutorials/differences.html)
+- [Migrate to v9](https://liquidjs.com/tutorials/migrate-to-9.html)
+- [Changelog](https://liquidjs.com/tutorials/changelog.html)
+
+## Reference
+
+- [Tags](https://liquidjs.com/tags/overview.html)
+- [Filters](https://liquidjs.com/filters/overview.html)
+- [API (TypeDoc)](https://liquidjs.com/api/)
+- [Playground](https://liquidjs.com/playground.html)