diff --git a/AGENTS.md b/AGENTS.md index 17a4f9ee..26a7aada 100644 --- a/AGENTS.md +++ b/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 diff --git a/docs/migrations.md b/agents/skills/migrations.md similarity index 98% rename from docs/migrations.md rename to agents/skills/migrations.md index 779e02b7..bb6cf2b8 100644 --- a/docs/migrations.md +++ b/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. diff --git a/default/audio/tunings/dell-xps-2026/tuning.conf b/default/audio/tunings/dell-xps-2026/tuning.conf index e7bb633b..cb821332 100644 --- a/default/audio/tunings/dell-xps-2026/tuning.conf +++ b/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 diff --git a/default/systemd/user/omarchy-speaker-tuning.service b/default/systemd/user/omarchy-speaker-tuning.service index b26ce758..53b37447 100644 --- a/default/systemd/user/omarchy-speaker-tuning.service +++ b/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 diff --git a/docs/AUDIO-TUNING.md b/docs/audio-tuning.md similarity index 100% rename from docs/AUDIO-TUNING.md rename to docs/audio-tuning.md diff --git a/docs/file-layout.md b/docs/file-layout.md index 90b9b200..ce7ec0ec 100644 --- a/docs/file-layout.md +++ b/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 diff --git a/docs/update-process.md b/docs/update-process.md index f994292d..2d89e05d 100644 --- a/docs/update-process.md +++ b/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: