diff --git a/.run_status.toml b/.run_status.toml
index 9353dba..8d2f72f 100644
--- a/.run_status.toml
+++ b/.run_status.toml
@@ -1,8 +1,8 @@
[last_run_clean]
run_status = "Success"
-lines_parsed = 211
-coverage = 76.1
+lines_parsed = 242
+coverage = 76.72
[last_run_clean.run_duration]
-secs = 16
-nanos = 510511933
+secs = 18
+nanos = 765260395
diff --git a/README.md b/README.md
index 6eaf608..d8a72dd 100644
--- a/README.md
+++ b/README.md
@@ -35,6 +35,7 @@ signals, not the probability that AI wrote the content.
- [Runnable Rust examples](examples/README.md)
- [Documentation index](docs/README.md)
- [Command-line usage and current capabilities](docs/usage.md)
+- [Helix and Vim formatter/LSP setup](docs/editors.md)
- [Human, concise, and JSON output contracts](docs/output.md)
- [Architecture and public library API](docs/architecture.md)
- [Layered configuration](docs/configuration.md)
diff --git a/badges/coverage.svg b/badges/coverage.svg
index 538dc80..4acc2bf 100644
--- a/badges/coverage.svg
+++ b/badges/coverage.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index b1241c5..5a028a0 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -7,6 +7,8 @@ the details needed to use, embed, and develop John Slop:
analysis, streaming path input, and shared replacement planning.
- [Usage](usage.md) documents accepted inputs, detector output, exit statuses,
and the current formatter/LSP status.
+- [Editor setup](editors.md) provides Helix (`hx`) and Vim configuration for
+ the formatter and LSP adapter contracts, with current scaffold caveats.
- [Output contracts](output.md) specifies human and concise presentation plus
the versioned JSON Lines schema and partial-error records.
- [Architecture](architecture.md) describes module boundaries, shared domain
diff --git a/docs/editors.md b/docs/editors.md
new file mode 100644
index 0000000..6cd9dbf
--- /dev/null
+++ b/docs/editors.md
@@ -0,0 +1,105 @@
+# Editor setup
+
+> **Current status:** these configurations are ready for the adapter contracts,
+> but `john-slop-fmt` and `john-slop-lsp` are still explicit scaffolds. The
+> formatter becomes operational in Milestone 5 and the language server in
+> Milestone 6. Until then, both return an unsupported diagnostic when started
+> without `--help`.
+
+Install all three binaries somewhere on `PATH`, then confirm the editor-facing
+help is available:
+
+```sh
+john-slop-fmt --help
+john-slop-lsp --help
+```
+
+## Helix (`hx` / `helix-term`)
+
+Helix configures formatters and language servers in `languages.toml`. Put this
+in `~/.config/helix/languages.toml` on Linux, or in `.helix/languages.toml` for
+project-local configuration:
+
+```toml
+[language-server.john-slop]
+command = "john-slop-lsp"
+
+[[language]]
+name = "john-slop-text"
+language-id = "plaintext"
+scope = "text.john-slop"
+file-types = ["txt"]
+formatter = { command = "john-slop-fmt" }
+language-servers = ["john-slop"]
+auto-format = false
+```
+
+This complete custom language entry makes the repository's `example.txt`
+fixtures useful without depending on a built-in plain-text grammar. Use
+`:format` to run the formatter. Set `auto-format = true` only if save-time
+replacement is wanted after Milestone 5.
+
+For an existing language, merge John Slop into that language's entry rather
+than replacing its useful defaults. For example, Rust should retain
+`rust-analyzer`:
+
+```toml
+[[language]]
+name = "rust"
+formatter = { command = "john-slop-fmt" }
+language-servers = ["rust-analyzer", "john-slop"]
+```
+
+Run `hx --health rust` (or the selected language name) to confirm both binaries
+are visible. Helix documents that a formatter reads the buffer from stdin and
+writes it to stdout, while an LSP command must be on `PATH`; those are the
+contracts the two John Slop milestones target. See the official
+[Helix language configuration reference](https://docs.helix-editor.com/languages.html).
+
+## Vim
+
+Vim's native `formatprg` option is enough for formatting. Add this to
+`~/.vimrc`:
+
+```vim
+augroup john_slop_format
+ autocmd!
+ autocmd BufRead,BufNewFile *.txt setfiletype text
+ autocmd FileType text,markdown,rust setlocal formatprg=john-slop-fmt
+augroup END
+```
+
+Use `gggqG` to filter the whole buffer through the formatter, or select a range
+and press `gq`. Vim requires `formatprg` programs to read stdin and write stdout;
+see the official [`formatprg` and `gq` help](https://vimhelp.org/options.txt.html#%27formatprg%27).
+
+Classic Vim needs an LSP client plugin. With
+[`prabirshrestha/vim-lsp`](https://github.com/prabirshrestha/vim-lsp), register
+John Slop in `~/.vimrc`:
+
+```vim
+if executable('john-slop-lsp')
+ au User lsp_setup call lsp#register_server({
+ \ 'name': 'john-slop',
+ \ 'cmd': {server_info->['john-slop-lsp']},
+ \ 'allowlist': ['text', 'markdown', 'rust'],
+ \ })
+endif
+```
+
+The plugin's `:LspStatus`, `:LspNextDiagnostic`, and `:LspCodeAction` commands
+will expose server state, diagnostics, and replacement quick fixes once
+Milestone 6 lands. The registration shape and `allowlist` follow the plugin's
+current upstream documentation.
+
+## Try the shared fixtures
+
+Open `examples/fixtures/typography/example.txt` in either editor. Its expected
+formatter result is the adjacent `formatted.txt`; the shared manifest records
+three replacements and one typography rule. The CLI is usable now for a
+baseline:
+
+```sh
+cargo run --bin john-slop -- --output concise \
+ examples/fixtures/typography/example.txt
+```
diff --git a/docs/usage.md b/docs/usage.md
index 9cb8974..04cd2bb 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -89,4 +89,6 @@ Cargo already exposes `john-slop-fmt` and `john-slop-lsp` so packaging and CI
exercise their target names. Both are explicit scaffolds today and return an
unsupported diagnostic. Replacement planning is available through the library;
file-writing formatter behavior and the stdio language server arrive in later
-milestones.
+milestones. Both scaffolds accept `--help` and show concise Helix and Vim setup;
+the complete snippets and validation workflow live in
+[Editor setup](editors.md).
diff --git a/src/bin/editor_help.rs b/src/bin/editor_help.rs
new file mode 100644
index 0000000..33ec0c1
--- /dev/null
+++ b/src/bin/editor_help.rs
@@ -0,0 +1,27 @@
+//! Shared editor-integration help for the formatter and LSP adapters.
+
+pub const EDITOR_SETUP: &str = r#"EDITOR SETUP (fmt: Milestone 5; LSP: Milestone 6):
+ Helix ~/.config/helix/languages.toml:
+ [language-server.john-slop]
+ command = "john-slop-lsp"
+
+ [[language]]
+ name = "john-slop-text"
+ language-id = "plaintext"
+ scope = "text.john-slop"
+ file-types = ["txt"]
+ formatter = { command = "john-slop-fmt" }
+ language-servers = ["john-slop"]
+
+ Vim ~/.vimrc formatter (use gggqG for the whole buffer):
+ autocmd BufRead,BufNewFile *.txt setfiletype text
+ autocmd FileType text,markdown,rust setlocal formatprg=john-slop-fmt
+
+ Vim ~/.vimrc LSP (requires prabirshrestha/vim-lsp):
+ au User lsp_setup call lsp#register_server({
+ \ 'name': 'john-slop',
+ \ 'cmd': {server_info->['john-slop-lsp']},
+ \ 'allowlist': ['text', 'markdown', 'rust'],
+ \ })
+
+See docs/editors.md for installation, existing-language setup, and validation."#;
diff --git a/src/bin/john-slop-fmt.rs b/src/bin/john-slop-fmt.rs
index 031eb3d..c97b751 100644
--- a/src/bin/john-slop-fmt.rs
+++ b/src/bin/john-slop-fmt.rs
@@ -1,8 +1,23 @@
//! Formatter command-line adapter scaffold.
+#[path = "editor_help.rs"]
+mod editor_help;
+
+use clap::Parser;
use miette::{Result, miette};
+/// Replace configured Unicode punctuation with safe ASCII equivalents.
+#[derive(Debug, Parser)]
+#[command(
+ name = "john-slop-fmt",
+ version,
+ about,
+ after_help = editor_help::EDITOR_SETUP
+)]
+struct Cli {}
+
fn main() -> Result<()> {
+ let _cli = Cli::parse();
Err(miette!(
"john-slop-fmt is not implemented yet; replacement planning is available through the library"
))
diff --git a/src/bin/john-slop-lsp.rs b/src/bin/john-slop-lsp.rs
index d92608c..9048a5a 100644
--- a/src/bin/john-slop-lsp.rs
+++ b/src/bin/john-slop-lsp.rs
@@ -1,8 +1,23 @@
//! Language-server adapter scaffold.
+#[path = "editor_help.rs"]
+mod editor_help;
+
+use clap::Parser;
use miette::{Result, miette};
+/// Publish John Slop replacement diagnostics and quick fixes over stdio.
+#[derive(Debug, Parser)]
+#[command(
+ name = "john-slop-lsp",
+ version,
+ about,
+ after_help = editor_help::EDITOR_SETUP
+)]
+struct Cli {}
+
fn main() -> Result<()> {
+ let _cli = Cli::parse();
Err(miette!(
"john-slop-lsp is not implemented yet; LSP support is planned for Milestone 6"
))
diff --git a/tests/adapter_help.rs b/tests/adapter_help.rs
new file mode 100644
index 0000000..7a08948
--- /dev/null
+++ b/tests/adapter_help.rs
@@ -0,0 +1,33 @@
+use std::process::{Command, Output};
+
+fn help(binary: &str) -> Output {
+ Command::new(binary)
+ .arg("--help")
+ .output()
+ .expect("run adapter help")
+}
+
+#[test]
+fn formatter_help_contains_helix_and_vim_setup() {
+ let output = help(env!("CARGO_BIN_EXE_john-slop-fmt"));
+ let stdout = String::from_utf8(output.stdout).expect("UTF-8 formatter help");
+
+ assert!(output.status.success());
+ assert!(output.stderr.is_empty());
+ assert!(stdout.contains("Helix ~/.config/helix/languages.toml"));
+ assert!(stdout.contains("formatter = { command = \"john-slop-fmt\" }"));
+ assert!(stdout.contains("setlocal formatprg=john-slop-fmt"));
+}
+
+#[test]
+fn lsp_help_contains_helix_and_vim_setup() {
+ let output = help(env!("CARGO_BIN_EXE_john-slop-lsp"));
+ let stdout = String::from_utf8(output.stdout).expect("UTF-8 LSP help");
+
+ assert!(output.status.success());
+ assert!(output.stderr.is_empty());
+ assert!(stdout.contains("[language-server.john-slop]"));
+ assert!(stdout.contains("command = \"john-slop-lsp\""));
+ assert!(stdout.contains("lsp#register_server"));
+ assert!(stdout.contains("['john-slop-lsp']"));
+}