Sort documentation by genre and document the layout

Task procedure lives in agents/skills/ (migrations.md moves there),
system-shape reference in docs/ (AUDIO-TUNING.md renamed to match),
end-user documentation in manual/. AGENTS.md now states the split.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

AGENTS.md

@@ -9,7 +9,15 @@ matching guide before starting:
 - [`agents/skills/icon-font.md`](agents/skills/icon-font.md) - adding branded glyphs to `default/fonts/omarchy/omarchy.ttf`
 - [`agents/skills/acceptance-tests.md`](agents/skills/acceptance-tests.md) - writing or running graphical acceptance tests under `test/acceptance.d/`
 - [`agents/skills/visual-verification.md`](agents/skills/visual-verification.md) - verifying any change with a visual effect in the running UI
-- [`docs/migrations.md`](docs/migrations.md) - creating or changing migrations under `migrations/`
+- [`agents/skills/migrations.md`](agents/skills/migrations.md) - creating or changing migrations under `migrations/`
+
+# Documentation Layout
+
+Three documentation trees, split by genre and audience:
+
+- `agents/skills/` - task procedure ("do this when doing X"), for anyone working on the codebase
+- `docs/` - reference on how the system is shaped (file layout, update pipeline, theming, shell architecture), for anyone working on the codebase; skills link here for depth
+- `manual/` - end-user documentation for using Omarchy, published; never codebase internals
 
 # Style
 

agents/skills/migrations.md

@@ -1,5 +1,7 @@
 # Omarchy migrations
 
+Read this before creating or changing migrations under `migrations/`.
+
 Omarchy migrations are one-time repair scripts for existing installs. They are
 used when a package update needs to change state that pacman cannot safely own by
 itself.

default/audio/tunings/dell-xps-2026/tuning.conf

@@ -32,7 +32,7 @@ validated_on="2026-07-24"
 validated_hardware="XPS 14 DA14260 (0DB9)"
 
 ## Measured against that reference under a dense pink-weighted multitone of 104
-## bin-aligned tones. See docs/AUDIO-TUNING.md for how to reproduce these.
+## bin-aligned tones. See docs/audio-tuning.md for how to reproduce these.
 magnitude_rms_db="1.24"
 bass_group_delay_swing_ms="13.2"
 limiter_headroom_db="1.6"   ## worst-case peak on a hot master vs -1 dBFS

default/systemd/user/omarchy-speaker-tuning.service

@@ -1,6 +1,6 @@
 [Unit]
 Description=Omarchy speaker tuning filter-chain
-Documentation=https://github.com/basecamp/omarchy/blob/master/docs/AUDIO-TUNING.md
+Documentation=https://github.com/basecamp/omarchy/blob/master/docs/audio-tuning.md
 # WirePlumber does the linking, so starting before it is up risks the output being
 # linked before the speaker device has been discovered.
 After=pipewire.service wireplumber.service

docs/file-layout.md

@@ -201,7 +201,7 @@ the root-side work.
 
 ## Migrations (`omarchy-migrate`)
 
-See [`migrations.md`](migrations.md) for the full migration model, authoring
+See [`migrations.md`](../agents/skills/migrations.md) for the full migration model, authoring
 guidelines, and troubleshooting notes.
 
 Omarchy migrations live in `migrations/*.sh` and run per-user through

docs/update-process.md

@@ -30,7 +30,7 @@ The design goal is:
 
 ## Migration layout
 
-See [`migrations.md`](migrations.md) for the full migration model, authoring
+See [`migrations.md`](../agents/skills/migrations.md) for the full migration model, authoring
 guidelines, and troubleshooting notes.
 
 Migrations live in: