# Agent Instructions for ACF Markdown Manual

This folder contains the Markdown source documentation for the ACF Plugin for FileMaker.

## How to Use These Docs

- Start with `index.md`. It lists every manual page by category, title, excerpt, and URL.
- For web access, use `https://horneks.no/manuals/ACFmd/index.md` and follow the linked documents.
- For offline access, unzip `ACF-Markdown-Manual.zip`, read this `AGENTS.md`, then read `index.md`.
- Treat the manual pages as the source of truth for ACF syntax, built-in functions, FileMaker plugin calls, JSON/XML handling, filesystem functions, ZIP/FTP/SFTP functions, Excel functions, image functions, dialogs, and examples.

## Working With ACF Files

- ACF source files normally use the `.acf` extension.
- Preserve package names, public function names, `FunctionID` declarations, and call signatures unless the user explicitly asks for a breaking change.
- Prefer small, local edits. Do not broadly rewrite working ACF packages just to modernize style.
- ACF arrays are commonly 1-based in examples. Check nearby code before changing loop bounds.
- Many ACF functions must be used in assignments, for example `res = copy_file(...)` or `res = delete_file(...)`.
- Use bound SQL variables such as `:id` and `:excerpt` instead of manual string quoting when values may contain quotes, newlines, or punctuation.
- When writing to ZIP paths, use relative archive paths such as `zip + "docs/file.md"`; avoid leading `/` because Windows ZIP tools may unpack those poorly.
- In Markdown intended for local ZIP use, prefer relative links like `docs/page.md`, not `file://` URLs.

## Compiler

- If `ACFcompiler` is installed, compile with:

```sh
/usr/local/bin/ACFcompiler -i path/to/package.acf -o /private/tmp/package.dsComp -f TM -d 0
```

- Keep compiler output outside the repository unless the user asks for a build artifact.
- If compiling fails, report the exact line and message and make the smallest correction needed.

## Repository Safety

- For warning cleanup or modernization, fix one warning class or concern at a time.
- Preserve platform-specific behavior unless the user explicitly asks for a reviewed cross-platform refactor.