# AGENTS.md

Guidance for AI agents and contributors working in this repository.

## Documentation

- Write **all** documentation into the [`/docs`](docs) folder.
- Follow the **OKF / Knowledge-Catalog** pattern:
  <https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md>
  - Every concept document starts with YAML frontmatter — `type` is required;
    `title`, `description`, `tags`, `timestamp` are recommended — followed by Markdown.
  - [`docs/index.md`](docs/index.md) is the catalog (no frontmatter).
    [`docs/log.md`](docs/log.md) is the update log (ISO dates, newest first).
- All documents are written in **English**.
- Canonical docs: [specification](docs/specification.md),
  [architecture](docs/architecture.md), [design patterns](docs/design-patterns.md).

## Development environment

- Use the **Nix** dev shell — do **not** assume globally installed Node/npm.
  - `nix develop` (flakes) or `nix-shell`. With direnv: `direnv allow` (uses `.envrc`).
  - Provides Node 20 + npm + npx. Scaffolding tools (`yo`, `generator-joplin`) are run on
    demand via `npx`, never installed globally.
- Build: `npm run dist` → `publish/io.github.lansidev.shopping-list.jpl`.
- Test: `npm test` (jest + ts-jest).

## Code conventions

- Keep all parsing / routing / sorting / serialization logic in the **pure** modules under
  [`src/shopping/`](src/shopping) (no Joplin API imports) so it stays unit-testable. Cover
  changes with tests in [`__tests__/`](__tests__).
- [`src/index.ts`](src/index.ts) is the plugin main process (Joplin API).
  [`src/webview.ts`](src/webview.ts) is a thin vanilla-TS renderer that only emits intents and
  renders the view model — keep business logic out of it.
- Do not hand-edit `webpack.config.js` or `api/` (provided by `generator-joplin`). Configure the
  build via `plugin.config.json` and `package.json` instead.
- Indent with tabs, to match the existing files and the Joplin template.