docs+api: embedder guide for command_position shell-token replace

[SebTardif]

Source of request

Bline embedder (future edit_file / plan ops for shell and CI files).

Priority

P3 — lower (feature exists in 0.12; packaging for hosts is incomplete).

Scenario

Agents rename tools in scripts: pip install → uv pip install, without turning pipenv into uvenv or matching uv pip. Bline wants to offer:

• edit_file with commandPosition: true, or
• Auto-detect when path is *.sh / Makefile / *.yml CI

ReplaceOptions.command_position already implements this. What’s missing for hosts:

1. Discoverability — embedder docs with “when to set this” examples
2. ContentEdit batch — confirm/document that multi-op ContentEdit::Replace options include command_position end-to-end
3. Incompatible flag errors as typed InvalidInput (already partly there) with a stable message hosts can surface

Why patchloom should document/own packaging

This is a differentiator vs naive replace; if only CLI knows, agent hosts won’t enable it and agents will keep botching package-manager renames.

Acceptance criteria

• Embedder section: shell-token replace with before/after examples
• ContentEdit / plan / MCP field table includes command_position
• Test that library ContentEdit path honors the flag
• Note incompatibilities (regex, whole_line, …)

Bline impact if done

Wire one optional flag on edit_file with confidence; fewer broken Dockerfile/CI renames.

[SebTardif]

Maintainer triage (Bline embedder review)

Verdict: accept as primarily docs/packaging (P3); core behavior already exists.

Verified on main:

• ReplaceOptions.command_position and plan/MCP fields
• ContentEdit::Replace already has a unit test command_position_in_batch_match_count in src/api/content_edits.rs

Remaining: embedder-facing guide (when to enable, before/after shell examples, incompatibilities with regex/whole_line), and a short field table for ContentEdit/plan/MCP so hosts enable the flag with confidence.

Labels: keep documentation + enhancement + ready.