diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 055dbc0..f5997ca 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -16,6 +16,22 @@ repos:
     hooks:
       - id: gitleaks
 
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.48.0
+    hooks:
+      - id: typos
+        exclude: "users/shared/programs/zsh/p10k.zsh"
+
+  - repo: https://github.com/hukkin/mdformat
+    rev: 1.0.0
+    hooks:
+      - id: mdformat
+        args:
+          - --number
+        additional_dependencies:
+          - "mdformat-gfm==1.0.0"
+          - "mdformat-frontmatter==2.1.2"
+
   - repo: https://github.com/scop/pre-commit-shfmt
     rev: v3.13.1-1
     hooks:
diff --git a/README.md b/README.md
index adbc3ae..c0b3802 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # dotfiles
 
-Personal configuration for macOS systems, managed using [Nix Flakes](https://nixos.wiki/wiki/Flakes), [nix-darwin](https://github.com/LnL7/nix-darwin), and [home-manager](https://github.com/nix-community/home-manager).
+Personal configuration for macOS systems, managed using [Nix flakes](https://nix.dev/concepts/flakes.html), [nix-darwin](https://github.com/nix-darwin/nix-darwin), and [home-manager](https://github.com/nix-community/home-manager).
 
 ## Overview
 
@@ -9,25 +9,42 @@ Declarative and reproducible environment across machines:
 - System-level configurations via `nix-darwin`
 - User-specific configurations via `home-manager`
 - Homebrew integration via `nix-homebrew`
+- Cursor and Claude Code configurations from shared definitions
+
+Agent rules, skills, and MCP servers are defined once in `users/shared/programs/agents`. Nix renders them into the per-client format each tool expects, so Cursor and Claude Code stay in sync.
+
+## Layout
+
+| Path            | Contents                                        |
+| --------------- | ----------------------------------------------- |
+| `flake.nix`     | Inputs and `darwinConfigurations` for each host |
+| `modules/`      | System-level configuration and the package set  |
+| `systems/`      | Per-host configuration, keyed by hostname       |
+| `users/shared/` | Program configuration shared across users       |
+| `users/<name>/` | Per-user overrides                              |
 
 ## Setup
 
 1. Install Nix using the [Determinate Systems installer](https://install.determinate.systems/):
-    ```shell
-    just nix-install
-    ```
+
+   ```shell
+   just nix-install
+   ```
 
 2. Clone the repository:
-    ```shell
-    git clone https://github.com/khaykingleb/dotfiles.git ~/.config/dotfiles
-    cd ~/.config/dotfiles
-    ```
+
+   ```shell
+   git clone https://github.com/khaykingleb/dotfiles.git ~/.config/dotfiles
+   cd ~/.config/dotfiles
+   ```
 
 3. Apply the configuration for your machine:
-    ```shell
-    just nix-apply <hostname>
-    ```
-    where `<hostname>` is one of the systems defined in `flake.nix` (e.g. `macbook-pro-m4`).
+
+   ```shell
+   just nix-apply <hostname>
+   ```
+
+   where `<hostname>` is one of the systems defined in `flake.nix` (e.g. `macbook-pro-m4`).
 
 ## Usage