Skip to content

docs: add Cursor Cloud specific development instructions to AGENTS.md #72

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
andykais-claude wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

docs: add Cursor Cloud specific development instructions to AGENTS.md #72

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c2747e6
docs: add Cursor Cloud specific instructions to AGENTS.md
cursoragent May 9, 2026
1744a21
docs: document Deno canary bare specifier regression and web build/de…
cursoragent May 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 31 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -890,3 +890,34 @@ Forager is a well-architected media management system with:
- Migration-based schema evolution

When working on this codebase, prioritize type safety, follow established patterns, write tests, and maintain the clean separation of concerns across layers.

## Cursor Cloud specific instructions

### Environment

- **Deno stable** (not canary) must be used for the web package build. Deno canary has a regression where bare specifiers (e.g. `import 'zimmerframe'` inside `svelte/src/compiler/index.js`) are resolved as relative paths during vite's config evaluation, causing `Unable to load .../svelte/compiler` errors. The root cause: when vite loads vite.config.ts, it evaluates `@sveltejs/kit`'s `import_peer('svelte/compiler')` which loads `node_modules/svelte/src/compiler/index.js`; that file's `import 'zimmerframe'` is then incorrectly resolved as `./zimmerframe` instead of using Node module resolution. `nodeModulesDir: "manual"` + `npm install` does NOT fix this because the issue is in Deno canary's module loader (not the node_modules layout). Use Deno stable 2.7.x.
- **FFmpeg** is pre-installed at `/usr/bin/ffmpeg` and `/usr/bin/ffprobe`.
- **No external services** are needed — the database is embedded SQLite and the web server is built into the CLI.

### Running services

- **GUI server**: `deno task --cwd packages/cli develop --config <config_path> gui` starts the web UI on `127.0.0.1:8000`. Requires a YAML config file (see AGENTS.md main section for schema). A minimal config needs `core.database.folder`, `core.database.filename`, `core.thumbnails.folder`, `core.migrations.automatic: true`, and `web.port`.
- **Dev mode** (with HMR): `deno task develop` first builds the web package then starts the CLI GUI. This is the recommended dev workflow.

### Key commands

| Task | Command |
|------|---------|
| Lint (core) | `deno task --cwd packages/core lint` |
| Test (core) | `deno task --cwd packages/core test` |
| Test (CLI) | `deno task --cwd packages/cli test` (requires web build first) |
| Build (web) | `deno task --cwd packages/web build` or `build:local` |
| Dev (web HMR) | `deno task --cwd packages/web dev` (vite dev on port 5173) |
| Format | `deno fmt` |
| Full dev | `deno task develop` |

### Known test quirks

- Core tests have 4 failures related to FFmpeg version-specific floating-point precision (duration values differ slightly from expected). These are not code bugs.
- CLI tests require the web package to be built first (`deno task --cwd packages/web build`).
- The `--env-file=../../.env` warning from CLI develop tasks is harmless if no `.env` file exists.
Loading