diff --git a/AGENTS.md b/AGENTS.md
index 21d599b70..8c8f6084c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,37 +1,56 @@
-This file is a stub and is not yet complete.
-
-You should edit, add, and improve it!
-
-# Dependency Management
-
-## Dependency Manager
-
-The project uses **Swift Package Manager (SwiftPM)** for managing dependencies. SwiftPM is Apple's native package manager, and it is integrated with the Xcode ecosystem.
-
-### Overview of SwiftPM Usage
-Each module in the project appears to be its own Swift package, with a `Package.swift` file located in the `Packages` directory. This allows the project to manage its dependencies through these modular packages.
-
-## List of Packages
+# IceCubesApp Development Guide
+
+This document provides notes for contributors and automated agents working in this repository.
+
+## Project Overview
+IceCubesApp is an open-source Mastodon client written entirely in SwiftUI. The repo contains the main `IceCubesApp` Xcode project plus a set of Swift packages under `Packages/` that implement most of the functionality.
+
+## Repository Layout
+- `IceCubesApp` – main application target
+- `IceCubesShareExtension`, `IceCubesActionExtension`, `IceCubesNotifications`, `IceCubesAppIntents`, `IceCubesAppWidgetsExtension` – extra targets and extensions
+- `Packages/` – independent Swift packages listed below
+
+### Packages
+1. **Account** – user profile and account management
+2. **AppAccount** – multi-account support
+3. **Conversations** – direct messages
+4. **DesignSystem** – shared UI components and theming
+5. **Env** – global environment and routing
+6. **Explore** – search and discovery features
+7. **Lists** – Mastodon lists support
+8. **MediaUI** – media handling components
+9. **Models** – data models for Mastodon API
+10. **Network** – networking layer and API client
+11. **Notifications** – push and in-app notifications
+12. **StatusKit** – post editor and status rendering
+13. **Timeline** – timeline views and streaming logic
+
+Each package has its own `Package.swift` file and is built with **Swift Package Manager**.
+
+## Building the Project
+1. Copy `IceCubesApp.xcconfig.template` to `IceCubesApp.xcconfig`.
+2. Fill in the `DEVELOPMENT_TEAM` and `BUNDLE_ID_PREFIX` values.
+3. Open `IceCubesApp.xcodeproj` in Xcode and build.
+
+To build a package on the command line:
+```bash
+swift build
+```
 
-The following Swift packages are located in the `Packages` directory:
+## Testing
+Unit tests live in the `Tests` directory of each package. Run tests with:
+```bash
+cd Packages/<PackageName>
+swift test
+```
+Many packages depend on Apple frameworks such as SwiftUI and will not build on a pure Linux environment.
 
-1. **MediaUI** - UI components related to media.
-2. **DesignSystem** - Design system components used across the app.
-3. **Lists** - Package for list-related components.
-4. **AppAccount** - Package for managing user accounts and authentication.
-5. **Network** - Network-related functionality, such as API calls and data management.
-6. **Models** - Contains data models used throughout the app.
-7. **Explore** - Package for explore features, such as discovery of content.
-8. **Env** - Environmental settings or configurations.
-9. **Conversations** - Package for managing conversations or chat-related features.
-10. **Account** - Handles user accounts and profile features.
-11. **Timeline** - Package for timeline-related functionality, likely for displaying user posts or activities.
-12. **Notifications** - Handles notifications functionality.
-13. **StatusKit** - Contains status-related components, such as user status or activity status.
+## Code Style
+This repository uses [SwiftFormat](https://github.com/nicklockwood/SwiftFormat). The configuration is stored in `.swiftformat` and currently sets a two-space indentation. Format Swift files before committing if possible.
 
-## How to Build the Project
+## Contribution Tips
+- Follow the MVVM pattern used throughout the packages.
+- See `README.md` and `CLAUDE.md` for deeper explanations of features and architecture.
+- CI scripts in `ci_scripts/` reveal environment variables required for automated builds.
 
-If you're working on the project, you may be able to build it on Linux using the following command:
-```bash
-swift build
-```
+Happy coding!