diff --git a/docs/README.md b/docs/README.md
index ddad719..961968e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -9,14 +9,15 @@ remote modpack workflows from a single CLI.
 
 - Create and import modpacks
 - Add, remove, update, and inspect projects
-- Resolve dependencies across supported platforms
+- Resolve dependencies across supported platforms with automatic cross-platform
+  project merging
 - Manage pack configuration and per-project overrides
 - Export CurseForge, Modrinth, and serverpack layouts
 
 ### New in Pakker
 
 - Work with forked packs and remote repositories
-- Interactively set and configure and test API credentials
+- Interactively set, configure, and test API credentials
 
 ## Quick Start
 
@@ -24,6 +25,19 @@ remote modpack workflows from a single CLI.
 2. Use `pakker add` or `pakker add-prj` to add projects.
 3. Run `pakker export` when you want distributable output.
 
+## How It Works
+
+Pakker maintains two files in your modpack directory:
+
+- `pakker.json`: pack metadata, paths, overrides, and per-project settings
+- `pakku-lock.json`: resolved project state with platform IDs, file URLs, and
+  dependency links
+
+When you add a project, Pakker queries the supported platforms, merges results
+into a single project record with cross-platform identifiers, resolves
+dependencies recursively, and updates the lockfile. The resolver detects
+circular dependencies and links related projects via `pakku_links`.
+
 ## Acknowledgments
 
 [Pakku]: https://github.com/juraj-hrivnak/Pakku