diff --git a/AGENTS.md b/AGENTS.md
index 08ba23f..2054920 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -201,6 +201,7 @@ Was caused by settings loading at wrong time; fixed by using `LspAttach` autocmd
 - After any config or plugin change, immediately update `MIGRATION_PLAN.md` (check off items, add notes, or adjust next steps).
 - After any change or decision, also update `LOG.md:1` (decisions log and design docs).
 - **After adding/removing/editing any keymaps**, immediately update `README.md` with the change (add new entries, remove deleted mappings, or update descriptions).
+- **After changing formatter/linter configuration, standards, or tool resolution**, immediately update the "Configuration" section in `README.md` (update tool lists, override instructions, or behavior descriptions).
 - At the start of each phase, confirm scope and priorities for that phase.
 - Execute phases via subphases (`N.x`), where each bullet under a phase is its own implement-and-test step (e.g., Phase 3.1, 3.2, 3.3, 3.4).
 - Record decisions and rationale in `LOG.md:1` as they're made.
diff --git a/README.md b/README.md
index 45d1cf5..82dd858 100644
--- a/README.md
+++ b/README.md
@@ -304,3 +304,98 @@ Buffer-local keymaps available when inside a git repository:
 | Mode | Key | Description |
 | --- | --- | --- |
 | insert | `<M-e>` | Fast wrap the previous text with a pair |
+
+## Configuration
+
+### Formatting & Linting
+
+This config uses **none-ls** for formatting and **nvim-lint** for diagnostics. Both prefer project-local tools over global installations.
+
+#### Executable Resolution Order
+
+When looking for formatters/linters, the config searches in this priority:
+
+1. **Project-local** (e.g., `node_modules/.bin/`, `vendor/bin/`)
+2. **Mason-managed** (`~/.local/share/nvim/mason/bin/`)
+3. **System PATH** (globally installed tools)
+
+See `find_executable()` helper in `lua/plugins/none-ls.lua` and `lua/plugins/nvim-lint.lua`.
+
+#### Configured Tools
+
+**Formatters** (`lua/plugins/none-ls.lua`):
+- **JavaScript/TypeScript/CSS/JSON/HTML/Markdown**: `prettier`
+- **PHP**: `phpcbf` (WordPress standard by default)
+- **Lua**: `stylua`
+- **Python**: handled by `ruff` LSP (not none-ls)
+
+**Linters** (`lua/plugins/nvim-lint.lua`):
+- **JavaScript/TypeScript**: `eslint_d`
+- **PHP**: `phpcs` (WordPress standard by default)
+- **Markdown**: `markdownlint` (disabled by default; use `:MarkdownLintEnable`)
+- **Python**: handled by `ruff` LSP (not nvim-lint)
+
+#### Project-Specific Overrides
+
+Both formatters and linters respect project-level configuration files:
+
+**PHP** (phpcbf + phpcs):
+- Create `phpcs.xml` or `phpcs.xml.dist` in your project root
+- When present, this file controls the coding standard (e.g., PSR-12, WordPress, custom)
+- When absent, defaults to `--standard=WordPress`
+
+Example `phpcs.xml`:
+```xml
+<?xml version="1.0"?>
+<ruleset name="Custom">
+  <description>Project-specific PHP rules</description>
+  <rule ref="PSR12"/>
+  <!-- or: <rule ref="WordPress-Core"/> -->
+  
+  <!-- Customize rules -->
+  <rule ref="Generic.Files.LineLength">
+    <properties>
+      <property name="lineLimit" value="120"/>
+    </properties>
+  </rule>
+</ruleset>
+```
+
+**JavaScript/TypeScript** (prettier + eslint):
+- Project config files: `.prettierrc`, `.eslintrc.json`, `eslint.config.js`, etc.
+- Global fallback: `~/.eslintrc.json` (when no project config exists)
+
+**Lua** (stylua):
+- Project config: `stylua.toml` or `.stylua.toml`
+- Falls back to stylua defaults if not present
+
+**Markdown** (markdownlint):
+- Project config: `.markdownlint.json`, `.markdownlintrc`
+
+#### Changing Standards Per-Project
+
+To switch a PHP project from WordPress to PSR-12:
+
+1. Create `phpcs.xml` in project root:
+   ```xml
+   <?xml version="1.0"?>
+   <ruleset name="PSR-12">
+     <rule ref="PSR12"/>
+   </ruleset>
+   ```
+
+2. Restart Neovim (or reload config: `:source $MYVIMRC`)
+
+Both `phpcs` and `phpcbf` will now use PSR-12 rules in that project.
+
+#### Format-on-Save
+
+- **Enabled by default** for all supported filetypes
+- **Toggle**: `<leader>lt` (see keymaps below)
+- **Manual format**: `<leader>lf` (buffer or visual selection)
+
+#### Linting Behavior
+
+- **Automatic**: Runs on `BufEnter`, `BufWritePost`, `InsertLeave`
+- **Per-filetype**: Configured in `lint.linters_by_ft` table
+- **Markdown**: Opt-in only (`:MarkdownLintEnable` / `:MarkdownLintDisable`)
\ No newline at end of file