docs: add AGENTS.md and CLAUDE.md

[Alex-Arsys]

AGENTS.md is the canonical guidance file for AI agents working in this repository — covering architecture constraints, conventions, and rules. CLAUDE.md contains only @AGENTS.md, making Claude Code load this file automatically alongside other AI tools.

Assisted-by: ClaudeCode:claude-sonnet-4-6

[MonaAghili]

It would be good to mention sdkjs agents.md becuase they somehow related to each other
Also as @moodyjmz mentioned it would be good to add /DocumentServer/AGENTS.md for docker

I believe that code style, architecture, the libraries that used in this repository with their current version and some additional information in general about the status of current workflow is missing and needed to be mentioned
Also nothing mentioned about mobile and it's stack

[moodyjmz]

Review authored by Claude (Opus 4.8), posted by @moodyjmz. Findings verified against origin/main source.

Building on @MonaAghili's review — agree with all of it. The bigger issue is that the Module System & Build Architecture section needs a rewrite rather than a patch: it reads like an adaptation of sdkjs/AGENTS.md, but web-apps builds nothing like sdkjs does.

Build model (lines 10–14) is inaccurate

• "Files are plain scripts concatenated in order by Grunt" — the desktop editors are Backbone + AMD modules (define()/require()) bundled by the RequireJS r.js optimiser (grunt-contrib-requirejs). Not plain concatenation.
• "invisible until manually added to build/Gruntfile.js" — wrong file and wrong mechanism. Per-editor build config is build/<editor>.json (e.g. build/documenteditor.json); r.js discovers files through the AMD dependency graph (findNestedDependencies), there's no hand-maintained source array in Gruntfile.js.
• "No ES modules, no tree-shaking" is also false for mobile, which @MonaAghili rightly flags as missing entirely. Mobile is a second pipeline: React 19 + Framework7 8.x → webpack 5 (vendor/framework7-react/build/webpack.config.js), ES modules/JSX, and webpack tree-shakes by default. (pdfeditor is the one editor with no mobile front-end.)

Build commands (line 12)

cd build && npm ci / grunt deploy-<editor> are real tasks, but they're host-side and unscoped. We build inside the eo container via make (the in-container Makefile runs npm ci + grunt itself):

docker compose exec -T eo make web-apps       # full
docker compose exec -T eo make web-apps-dev   # fast rebuild

This is the /DocumentServer/AGENTS.md reference @moodyjmz raised. Note it also contradicts line 17, which already says these run "in the container."

@../AGENTS.md (line 3)

Agree with @MonaAghili that it should change — to be precise, the file does exist in the dev workspace (DocumentServer/AGENTS.md), so it resolves there, but as an @-import it dangles in a standalone clone. Make it a plain markdown link for the Docker setup, and state the build commands locally so a standalone checkout still works.

#51 (line 27)

That's the closed "Update Dockerfile…" issue in this repo. The reference was copied from sdkjs/AGENTS.md, where #51 genuinely is the findings-store issue — issue numbers don't carry across repos. There's no committed findings store on main yet — a knowledge store is only proposed in #108 (.claude/ isn't in the repo). Either way the reference is wrong and out of scope; suggest dropping the line.

---

I've drafted a corrected AGENTS.md covering both pipelines (desktop AMD/r.js + mobile React/webpack), the theme.config.mjs contract, the per-editor window namespaces, and the container/make workflow. Happy to push it to the branch or share it here.

[moodyjmz]

Authored by Claude (Opus 4.8), posted by @moodyjmz. Every factual claim verified against origin/main source.

Edited: removed parked-webpack-migration content that had crept in (the webpack5-* finding reference, a non-existent themeReplacements export, and an uncommitted .claude/findings/ pointer); fixed the sibling-repo path to ../sdkjs/AGENTS.md. The mobile webpack 5 pipeline is real on main and stays.

Proposed corrected AGENTS.md (per my review above) — covers both build pipelines, the config.json theme contract, per-editor window namespaces, and the container/make workflow. Drop-in replacement for the file in this PR:

# web-apps — Euro-Office

Guidance for AI agents working in **web-apps** — the editor UIs and DocsAPI gateway for
Euro-Office Document Server. This is the canonical instruction file; `CLAUDE.md` points here.
For the sibling SDK, see `../sdkjs/AGENTS.md` (sibling repo in the dev workspace).

## What this repo is

The front-end of Euro-Office Document Server: the **desktop** and **mobile** editor UIs plus
`api.js`, the DocsAPI gateway that host integrations embed via `<script>`. Hard fork of
`ONLYOFFICE/web-apps`, rebranded to Euro-Office. Licensed **AGPL-3.0**.

Five desktop editors — **documenteditor**, **spreadsheeteditor**, **presentationeditor**,
**pdfeditor**, **visioeditor** (plus **appforms**, the document-editor forms variant). All
except **pdfeditor** also have a mobile front-end. The client-side document engine itself lives
in the sibling **sdkjs** repo and loads via `<script>`; it is not built here.

## Two build systems

web-apps has **two independent front-end build pipelines**. Get this wrong and nothing else
makes sense.

### Desktop — Backbone + AMD → RequireJS (r.js), via Grunt
- Desktop editor code is **Backbone** built on **AMD modules** (`define()` / `require()`) —
  hundreds of them. It is **not** plain-script concatenation, and it is **not** ES modules.
- Bundled per editor by the **r.js optimiser** (`grunt-contrib-requirejs`). A file becomes part
  of the bundle when it is pulled into the AMD dependency graph (`define([...deps])`) — r.js
  discovers it via `findNestedDependencies`. There is **no** hand-maintained source array in
  `Gruntfile.js`.
- Per-editor build config (entry, paths, output) is **`build/<editor>.json`**
  (e.g. `build/documenteditor.json`), not `Gruntfile.js`.
- Templates are loaded at runtime via the `requirejs-text` (`text!`) loader plugin.
- Symbols live on global `window` namespaces: `Common.*` (shared) plus one per editor —
  `DE` (documenteditor), `SSE` (spreadsheeteditor), `PE` (presentationeditor),
  `PDFE` (pdfeditor), `VE` (visioeditor). `Asc` / `AscCommon` come from sdkjs (loaded via
  `<script>`).

### Mobile — React + Framework7 → webpack 5
- Mobile editors are **React 19 + Framework7 8.x** (with MobX), ES modules / JSX, sources under
  `apps/<editor>/mobile/src/` (documenteditor, spreadsheeteditor, presentationeditor,
  visioeditor — pdfeditor has no mobile front-end).
- Built by **webpack 5** (`vendor/framework7-react/build/webpack.config.js`) with Babel,
  terser, and Workbox. webpack tree-shakes by default.

(The sibling **sdkjs** repo uses Google Closure Compiler — a third, separate model. Don't
conflate it with either of the above.)

### Theme contract (shared by both)
`theme/<name>/meta/config.json` is the single source of truth for brand data — both pipelines
read from it. Desktop: the Grunt `deploy-theme` task loads it into `global.themeMeta`, and
`_themVal()` resolves each value with priority **env var > `config.json` > `''`** (an empty value
hides the element in templates) → LESS variables + JS token replacement. Mobile: webpack imports
`themeGlobalVars` / `themeDefines` from `build/theme.config.mjs` → `DefinePlugin` + `less-loader`
`globalVars`. Don't duplicate brand tokens elsewhere — they all derive from `config.json`.

## Build & run

Builds run **inside the `eo` dev container**, never on the host, and you **never rebuild the
Docker image to test a change** — the repo is bind-mounted. For the full Docker dev-environment
setup (starting the container, healthcheck, Nextcloud connector), see the DocumentServer repo's
[`../AGENTS.md`](../AGENTS.md) — note this link resolves only inside the DocumentServer dev
workspace; a standalone clone of web-apps has no parent file.

The in-container Makefile drives the web-apps build — it runs `npm ci` + grunt itself, so you do
not run those by hand:

```sh
docker compose exec -T eo make web-apps       # full build (installs npm deps; needed first time)
docker compose exec -T eo make web-apps-dev   # fast rebuild — skips npm install / babel / imagemin
```

Pass **`PRODUCT_VERSION`** (e.g. `PRODUCT_VERSION=9.3.0 make web-apps`) or `api.js` reports
`4.3.0` and Euro-Office rejects it. `SKIP_MOBILE=1` skips the mobile webpack build.

Day-to-day loop: edit a source file → `make web-apps-dev` → hard-reload the editor. The service
worker caches aggressively, so test in incognito or hard-reset the SW in devtools (two `app.js`
versions in devtools = a cache conflict).

## Gotchas
- **`translation/merge_and_check.py` rewrites locale JSON** on every `make web-apps` /
  `make web-apps-dev` run. The changes appear in `git status` on the host. Don't commit them
  unless you intentionally changed translation strings.
- **`deploy/` is build output** (gitignored) — anything written there is overwritten on the next
  build.
- **`api.js` resolves subresource paths relative to its own URL** (`apps/api/documents/api.js`).
  Serving it from an unexpected path or with a version prefix silently breaks editor loading —
  the host integration's `<script>` URL must match exactly.

## Rules
- **Never** run the build on the host — use `make` inside the `eo` container.
- **Never** rebuild the Docker image to test a change — the checkout is bind-mounted.
- **Never** edit files under `deploy/` — build output.
- **Never** commit locale JSON rewrites from `merge_and_check.py` unless you changed strings.
- **Never** use `npm install` in `build/` — use `npm ci` to respect the pinned lockfile.
- **Never** edit `vendor/` by hand — it is checked-in, not npm-managed.

## Findings
There is no committed findings store on `main` yet — a portable, cross-tool knowledge store is
proposed in #108. Until it lands, this file is the only in-repo guidance.