docs(agents): add architecture overview and CLAUDE.md symlink

[paolomainardi]

User description

What

• Add an Architecture: the big picture section to AGENTS.md covering the four runtime services (traefik, dinghy_layer, join_networks, dns), the dynamic-config data flow, the shared pkg/ roles, and the config surface — the cross-file context that isn't obvious from any single file.
• Make CLAUDE.md a symlink to AGENTS.md so Claude Code and other agentic harnesses read one canonical file. A note at the top of AGENTS.md records that CLAUDE.md is the symlink and only AGENTS.md should be edited.

Why

AGENTS.md already documented commands and style conventions but lacked a high-level architecture map. Onboarding claude produced that map; rather than maintain two parallel files, both harnesses now share the same content via a symlink.

Notes

• No code changes. Docs only.
• Markdown formatted with Prettier.

---

PR Type

Documentation

---

Description

• Add architecture overview section to AGENTS.md

• Document four runtime services, data flow, and shared packages

• Create CLAUDE.md as symlink to AGENTS.md

• Add symlink notice and minor formatting fix in AGENTS.md

---

Diagram Walkthrough

flowchart LR
  A["AGENTS.md"] -- "symlinked by" --> B["CLAUDE.md"]
  A -- "documents" --> C["Architecture Overview"]
  C -- "covers" --> D["traefik service"]
  C -- "covers" --> E["dinghy_layer service"]
  C -- "covers" --> F["join_networks service"]
  C -- "covers" --> G["dns service"]
  E -- "writes dynamic config" --> D
  F -- "connects networks to" --> D

Loading

File Walkthrough

Relevant files

Documentation

AGENTS.md Add architecture overview and symlink notice to AGENTS.md AGENTS.md Add symlink notice at the top indicating CLAUDE.md points to this file Add "Architecture: the big picture" section covering four runtime services Document dynamic-config data flow with ASCII diagram Document shared pkg/ packages and configuration surface Minor formatting fix adding blank line before test requirements list +68/-0    CLAUDE.md Add CLAUDE.md symlink to AGENTS.md                                              CLAUDE.md Create CLAUDE.md as a symlink pointing to AGENTS.md +1/-0

---

[sparkfabrik-ai-bot]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 1 🔵⚪⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Broken Symlink CLAUDE.md contains the literal text AGENTS.md rather than being an actual filesystem symlink. A real symlink would be a special filesystem entry (created with ln -s AGENTS.md CLAUDE.md), not a file with that string as its content. As committed, tools reading CLAUDE.md will see only the text "AGENTS.md" rather than the contents of AGENTS.md. # AGENTS.md

[sparkfabrik-ai-bot]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	File content is not a real symlink The CLAUDE.md file contains only the text "AGENTS.md" rather than being an actual symlink. A symlink would be a filesystem-level construct, not a file containing the target path as text. If the intent is a symlink, it should be created via ln -s AGENTS.md CLAUDE.md and tracked in git with git add CLAUDE.md, not as a regular file with this content. CLAUDE.md [1] -AGENTS.md +# This file should be a symlink, not a regular file. +# Create it with: ln -s AGENTS.md CLAUDE.md +# Then: git add CLAUDE.md Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies that CLAUDE.md contains the text "AGENTS.md" rather than being an actual filesystem symlink. However, the improved_code replaces the file content with comments rather than demonstrating the actual fix (which would be a git-tracked symlink), making it not directly applicable as a code change.	Low