docs/architecture.md

@@ -82,6 +82,39 @@ progression is driven by Story-kind actions.
 
 The full design lives in `docs/superpowers/specs/2026-06-11-m1-pr3-shell-ui-design.md`.
 
+### Automation
+
+Automation is universal across action kinds once an action has at least its
+configured number of successful completions (`automation.unlockAfterManualCompletions`,
+default `1`). The engine stores those counts in
+`GameState.manualCompletionCounts` and stores configured automation in
+`GameState.automationQueue`.
+
+`src/engine/automation.ts` owns unlock checks, queue mutation, and the runner.
+The runner preserves precedence: manual active/queued actions first,
+automation second, loop-idle actions last. `tickGame` can start automation when
+the manual queue exhausts, including during offline catch-up; loop actions still
+start only from the live runtime path.
+
+`src/engine/recipe.ts` serializes automation queues as shareable text using
+content action ids. The v1 multiline format is:
+
+```text
+idlegame-recipe/v1
+# name: Camp loop
+gather_supplies
+rest
+```
+
+The single-line alias is:
+
+```text
+idlegame-recipe/v1:gather_supplies,rest
+```
+
+Import rejects unknown action ids and actions that are not automation-unlocked
+for the current save.
+
 ## Verification
 
 Run the full local gate before pushing: