docs: add CLAUDE.md for AI-assisted development

[HerrRichter]

Adds a CLAUDE.md at the repo root to orient Claude Code / AI assistants working in this super-repo.

Why: the repo is a build-orchestration meta-repo whose source lives in 9 submodules (uninitialized on a bare checkout). The file captures the non-obvious bits that require reading multiple files to grasp:

• submodules must be init'd first (git submodule update --init --recursive)
• the Docker Bake build DAG and cd build && docker buildx bake commands
• branding/version build variables (PRODUCT_VERSION, COMPANY_NAME, BRANDING_DIR, ...)
• footguns: Nextcloud-only provider, per-submodule Dockerfiles, submodule SHA pinning

No code or build behavior changes — documentation only.

🤖 Generated with Claude Code

[pplupo]

Call it AGENTS.md. It will work with Claude (it looks for AGENTS if it doesn't find CLAUDE) and also Codex, Windsurf, Cursor, Aider, and Copilot. I guess the only one that doesn't read it automatically may be Antigravity, but you can solve this by mentioning it with @AGENTS.md in any prompt in each chat (preferably the first one).

[errant253]

Hi, would this not conflict with #16 since Flathub has a very strict no generative AI/LLM assisted software policy?

[tuxPT]

@errant253 I think the policy is mostly for slop(vibe coded) apps, not well maintained apps.

https://github.com/flathub-infra/documentation/blob/main/docs/02-for-app-authors/02-requirements.md#generative-ai-policy contains the following line:

Exceptions may be granted for mature, well-maintained projects.

However, Euro-Office is very new, so the exception mostly likely would not be granted. So I would suggest to avoid using AI in order to keep the software on flathub or, if it's a must, then the Euro-Office team could create it's own flatpak repo with it's own rules.

P.S: this is not a flathub only issue, various stores are implementing this in order to exclude low quality and poorly maintained apps.

[pplupo]

@tuxPT Euro-Office is a substantial project. Using AI for development assistance does not make the output "slop." If Flathub's policies are too rigid to recognize the difference between well-maintained code and low-effort generation, we may need to look at alternative distribution methods.

I respect the need to filter out irrelevant or low-quality submissions, but a strict ban on AI assistance is counterproductive for the open-source community. Closed-source organizations are rapidly adopting AI to accelerate development, which only widens the gap between well-funded proprietary software and open-source alternatives.

AI tools are the economics that will turn the tide in our favor. They level the playing field, allowing open-source maintainers to match or exceed the output of closed-source teams. Stores and repositories that fail to adapt to this shift will eventually struggle to host the most competitive and innovative software.

[errant253]

It's worth mentioning that Flathub is not the be-all-end-all of Flatpak distribution, numerous orgs host their own Flatpak repositories (such as KDE, ElementaryOS, and GNOME), Euro-Office could very easily host a .flatpakrepo and provide a one-line command for users to add the repository and install.

It may be prudent to get in contact with Flathub first to see if Euro-Office would be granted an exemption, and then decide based on the response.

[pplupo]

This is my CLAUDE.md (AGENTS.md). It may be helpful to add:

# 1. CRITICAL PRE-REQUISITE: Think Before Coding
**This is the foundational directive and supersedes all implementation steps.**
*   **Surface Assumptions:** Never attempt to resolve ambiguity through silent guessing.
*   **Halt and Clarify:** If a requirement, specification, or architectural pattern allows for multiple interpretations, execution must immediately halt. You must explicitly articulate the conflict, map out the potential alternatives, and request formal human clarification before proceeding.

# 2. Execution Boundaries (Three-Tier Authorization)
Adhere strictly to predefined read/write permission boundaries.
*   **Always:** Execute mandatory programmatic checks (e.g., type checks, linters) before committing.
*   **Ask First:** Halt and request human authorization before installing new dependencies, altering CI/CD workflows, or making architectural decisions.
*   **Never:** Do not commit secrets, access production servers, or modify files in generated directories.

# 3. Naming Conventions
*   **Intention-Revealing:** Variables, functions, and classes must explicitly tell the reader why they exist, what they do, and how they are used.
*   **Avoid Disinformation:** Do not leave old names in place when the functionality changes. Update identifiers synchronously with behavior.
*   **Pronounceable and Searchable:** Avoid arbitrary abbreviations (e.g., use `customerRecord`, not `cr`).

# 4. Locality of Behavior (LoB) over DRY
Optimize for context window comprehension by minimizing file traversal.
*   Keep logic, state, and related fixtures as close as possible to where they are initially utilized.
*   Favor spatial proximity over absolute deduplication. 
*   Avoid aggressive application of Don't Repeat Yourself (DRY) principles if it fragments the codebase across multiple abstract layers.

# 5. Surgical Changes and Bounded Refactoring
Every modified line of code must trace directly and exclusively back to the active task.
*   **Zone 0 (Target Mutation):** Implement the requested logic exclusively.
*   **Zone 1 (Enclosing Function):** You may apply local clean-up (e.g., renaming variables, extracting guard clauses) strictly within the single abstract syntax tree (AST) function node you are modifying.
*   **Zone 2 (Enclosing Module):** Drive-by refactoring and the application of the "Boy Scout Rule" outside the target function are explicitly forbidden.
*   **Orphan Cleanup:** Systematically remove existing imports, variables, or helper functions only if they were directly orphaned by your immediate modification. Do not delete pre-existing dead code.

# 6. Anti-Speculation (YAGNI & KISS)
Combat the natural entropy of over-engineering.
*   Implement the absolute minimum volume of code required to resolve the immediate, documented specification.
*   The introduction of speculative abstractions, unnecessary configurability, generic base classes, or future-proofing interfaces is strictly prohibited.
*   If a functional requirement can be satisfied with a simple procedural block instead of an abstracted hierarchy, the simpler solution is objectively superior and must be utilized.

# 7. Architectural Consistency and Concurrency
*   **Absolute Conformity:** Modifications must identically match the existing patterns, nomenclature, and formatting of the target repository, even if an alternative paradigm is more modern.
*   **Single Writer Rule:** In parallelized environments, strict resource locking must be enforced. Do not concurrently hold write access to the same file or shared state.

# 8. Goal-Driven Execution
*   **Testable State:** Translate vague imperatives into deterministic outcomes. Map every task to a verifiable checkpoint (e.g., writing a failing unit test that reproduces a defect) before generating production code.