From e74e56e908dd3affc45cf8d4e1dbb219e1764bb5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alex=20Hern=C3=A1ndez?= Date: Thu, 25 Jun 2026 11:50:31 +0200 Subject: [PATCH] docs: add AGENTS.md and CLAUDE.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 Signed-off-by: Alex Hernández --- AGENTS.md | 23 +++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 24 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..e07d5d3b6 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,23 @@ +# document-server-integration — Euro-Office API Integration Reference + +@../AGENTS.md + +Guidance for Claude Code (and other AI agents) working in **document-server-integration** — reference implementations for host applications. + +## What this repo is +A collection of insecure, didactic implementation examples across 11 programming languages/frameworks demonstrating how an external application communicates with the Euro-Office API. + +## Licensing Guardrails & Core Architecture +- **THE LICENSING RULE:** Unlike the main repository submodules which are under the strict AGPL-3.0 license, this repository is explicitly licensed under **Apache-2.0**. + - **CRITICAL:** Every new file contributed here MUST contain the Apache-2.0 copyright header block. Committing AGPL-3.0 headers here creates severe compliance violations. +- **The `/track` Saving Lifecycle:** The `/track` POST callback endpoint is the absolute core of the architecture. When the Document Server finishes an editing session, it fires data to this endpoint. + - **CRITICAL FAIL MODE:** If the host application returns a slow response, handles the JWT incorrectly, or suffers a timeout, the user edits are silently lost. Study the Node.js `/track` handler in `web/documentserver-example/nodejs/app.js` and the `documentService` helper (`helpers/documentService.js`) as the standard model. +- **JWT Cryptographic Verification:** All communication between the host and Document Server must pass signed JWT tokens. Mismatched keys trigger silent HTTP 403 errors on the callback URL with zero debug logs. + +## Rules +- **Never** introduce production hardening, standard login authentications, or complex access control logic to these files; doing so obscures the minimal integration patterns they exist to teach. +- **Never** introduce a new language example without implementing the absolute minimum baseline flow: Document Open, JWT Generation, and the `/track` Callback. +- **Never** commit code with AGPL-3.0 license headers. + +## Findings & Long-tail +No centralized findings store exists in this repository yet. Document edge cases in code comments or GitHub issues until one is established. \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..43c994c2d --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md