docs: add domain glossary and ADRs for the placeholder round-trip

CONTEXT.md captures the ninjection glossary (injection, parent/child
buffer, language header, ninjection block, literal/interpreted
placeholder, rename mapping). docs/adr records the three load-bearing
decisions: split the parent transform from the injected-keyed header
render (0001), Treesitter as the sole structural parser (0002), and the
child validates only its own language (0003). TODO.md tracks remaining
follow-ups.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: pete3n

CONTEXT.md

@@ -0,0 +1,68 @@
+# Ninjection
+
+Ninjection is a Treesitter plugin for Neovim that extends Treesitter's
+introspection into injected languages: it makes injected-language code blocks
+inside a host file (e.g. shell or Lua embedded in Nix) editable as first-class
+buffers — with the injected language's LSP, completion, and formatting — then
+writes the edits back into the host file. Structural understanding of code is
+always Treesitter's job, never hand-rolled string parsing.
+
+## Language
+
+**Injection**:
+A region of a host file written in a different language, marked for Treesitter to
+parse as that language. The unit ninjection extracts, edits, and writes back.
+_Avoid_: snippet, embed, fragment
+
+**Parent buffer**:
+The host-language buffer that contains injections (e.g. the Nix file). Modeled as
+`NJParent`.
+_Avoid_: host buffer, source buffer
+
+**Child buffer**:
+The ephemeral buffer holding a single injection's content in the injected
+language, where editing happens. Modeled as `NJChild`.
+_Avoid_: scratch buffer, edit buffer
+
+**Injected language**:
+The language of an injection's content and of the child buffer (e.g. bash).
+Distinct from the parent buffer language.
+
+**Language header**:
+Ephemeral scaffolding prepended to a child buffer on edit and stripped on
+write-back. Supplies what the injected language's LSP needs but the host
+synthesizes at build time (e.g. a shell shebang), and carries a delimited block
+recording the placeholder substitutions to reverse.
+
+**Ninjection block**:
+The delimited, comment-fenced region inside a language header holding real
+variable declarations (initialized to the injected language's default value,
+e.g. `""` for shell, `nil` for Lua) for the injected placeholders. Satisfies the
+injected language's LSP (no undefined-variable diagnostics) and serves as the
+round-trip ledger of which placeholders to restore — including rename mappings
+for placeholders whose host name is invalid in the injected language. Delimited
+in the injected language's comment syntax; tagged with the parent buffer
+language.
+
+**Rename mapping**:
+A ledger entry recording that an *interpreted* placeholder's host name was
+rewritten to an injected-language-safe identifier for editing (e.g. Nix
+`pkgs.gnugrep` → `pkgs_0x2E_gnugrep`, since the dot is invalid in shell — each
+invalid character is replaced in place by `_0x<HEX>_`).
+Reversed on write-back. Only interpreted placeholders are renamed; literals never
+are.
+
+**Literal placeholder**:
+A host interpolation that denotes literal text rather than evaluation — in Nix,
+`''${var}` produces the literal `${var}`. Ninjection de-escapes it to `${var}`
+for editing and re-escapes on write-back. Literals are never renamed: the token
+is its own injected-language name, so a literal whose name is invalid in the
+injected language is left undeclared, letting that language's LSP surface the
+pre-existing error rather than hiding it.
+_Avoid_: escaped variable
+
+**Interpreted placeholder**:
+A host interpolation the host evaluates — in Nix, `${pkgs.hello}`. Ninjection
+rewrites it to an injected-language-safe identifier (see Rename mapping) for
+editing and restores it on write-back. Substituting the host's *real* evaluated
+value (rather than a default) is a future enhancement.

TODO.md

@@ -1,4 +1,15 @@
-# Nix / Shell code implemntation
-## Header template
-## Literal var placeholders for ''${var} to -> ${var} and back
-## Interpereted var placeholders for ${pkgs.var} to ${pkgs_var} and back
+# Nix / Shell injected-language editing
+
+Implemented (branch `feat/placeholder-roundtrip`):
+- [x] Language header: shebang + fenced ninjection block of real declarations
+- [x] Literal var placeholders: `''${var}` <-> `${var}`
+- [x] Interpreted var placeholders: `${pkgs.var}` <-> `${pkgs_0x2Evar}`
+      (in-place `_0x<HEX>` rename, restored via the block's `# <- host` arrows)
+
+Follow-up:
+- [ ] checkhealth: report the injected-language Treesitter grammar requirement
+      for the placeholder round-trip (degrades gracefully today)
+- [ ] Resolve the `cfg.debug`-guarded string restorer in `replace()` — currently
+      inert and accidentally load-bearing (see docs/adr/0001 notes / memory)
+- [ ] Real value interpolation for interpreted placeholders (default `""`/`nil` today)
+- [ ] Generalise beyond a Nix host / bash+sh injected languages

docs/adr/0001-split-placeholder-transform-from-header-render.md

@@ -0,0 +1,33 @@
+# Split placeholder transform (host-keyed) from header render (injected-keyed)
+
+Making injected code editable spans two independent language axes: rewriting
+host interpolations into editable placeholders is governed by the **parent
+buffer language's** rules (e.g. Nix decides that `''${x}` is a literal and
+`${pkgs.y}` is an interpolation), while building the language header — shebang,
+comment delimiter, assignment operator, default value — is governed by the
+**injected (child) language's** rules (bash `#`/`=`/`""` vs Lua `--`/` = `/`nil`).
+
+We model these as two stages rather than one function: a parent-keyed *transform*
+that returns `(body, ledger)`, then an injected-keyed *header renderer* that turns
+the ledger into header text prepended to the child buffer. Restore runs them in
+reverse. We chose this over a single function told both languages because it
+matches the codebase's existing grain (parent-keyed tables like
+`inj_text_modifiers` beside injected-keyed tables like `lsp_map`), keeps each
+unit single-responsibility and independently testable, and makes adding an
+injected language a matter of supplying a header descriptor rather than editing
+the Nix transform.
+
+## Consequences
+
+- The in-buffer ninjection block *is* the ledger, so placeholder data is parsed
+  back out of the child buffer on restore rather than threaded through
+  `text_meta`.
+- Header height is needed only transiently during `edit()` (to offset the child
+  cursor by the prepended header) and is passed into `set_cursor`; it is *not*
+  stored in `text_meta`, and restore locates the header by fence-scan, not a
+  stored count.
+- `text_meta` is therefore not for ninjection's internal bookkeeping. Its purpose
+  is to be an accessible per-language round-trip channel that a user's modifier
+  writes and that user's restorer reads, with core shuttling it opaquely — the
+  extension point for adding language behavior without core changes. It should be
+  typed opaquely (`table<string, any>`), not narrowed to `table<string, boolean>`.

docs/adr/0002-treesitter-is-the-sole-structural-parser.md

@@ -0,0 +1,24 @@
+# Treesitter is the sole mechanism for structural introspection
+
+All structural understanding of code — locating injections, distinguishing a Nix
+interpolation `${…}` from an escaped literal `''${…}`, identifying language
+constructs — is obtained from Treesitter, never from regex or hand-rolled string
+parsing. Ninjection is, in effect, a Treesitter plugin that extends Treesitter's
+introspection into injected languages; re-implementing slices of a language's
+lexer in Lua patterns would be fragile, would silently corrupt users' source,
+and is explicitly out of scope to maintain.
+
+## Consequences
+
+- Stage 1 of the placeholder round-trip (see ADR-0001) takes the injected
+  Treesitter node (or interpolation ranges precomputed from it), not a bare
+  string, so it can rewrite by node range rather than by pattern match.
+- Reverse (write-back) stays in the child buffer: the injected language's TS
+  locates the variable nodes, and re-adding the parent's literal delimiter is a
+  trivial prepend onto the TS-identified slice — no parent-language parsing and
+  no buffer-language switch.
+- The ban is on using string processing to *locate or parse* language structure.
+  Once TS hands us a node range, a simple prepend/substitution on that slice (or
+  matching ninjection's own fixed `>>> ninjection` fence marker) is not language
+  parsing and remains acceptable. What is forbidden is scanning or parsing whole
+  buffers / extracting language elements by hand.

docs/adr/0003-child-validates-only-its-own-language.md

@@ -0,0 +1,30 @@
+# The child buffer validates only its own language
+
+The child buffer is responsible for being valid in the injected language, using
+that language's Treesitter grammar and LSP. It is *not* responsible for
+validating the text it writes back into the parent buffer. If a user edits a
+placeholder into something invalid for the parent language, the parent's own
+Treesitter grammar / LSP reports the error after write-back and the user
+re-edits there.
+
+We chose this boundary rather than having ninjection re-validate the round-tripped
+result against the parent language, because each buffer already has first-class
+tooling for its own language and duplicating parent validation inside the child
+edit flow adds complexity for no gain — the parent buffer surfaces the error
+exactly where the user fixes it.
+
+## Consequences
+
+- Substituting the host's *real* evaluated value into placeholders (real-time
+  interpolation in the child buffer) is out of scope for now; placeholders are
+  declared with the injected language's default value (`""`, `nil`).
+- The round-trip's correctness obligation is limited to reproducing the user's
+  intent (escape vs. bare interpolation), not to guaranteeing the result is valid
+  parent-language code.
+- Literals are never renamed. A literal's editable token *is* its
+  injected-language name, so a literal with an injected-invalid name (`''${cfg.foo}`,
+  which already emitted invalid shell) is de-escaped but left undeclared — the
+  injected LSP surfaces the pre-existing error instead of ninjection hiding it
+  behind a rename. Consequently only interpreted placeholders carry a ledger
+  arrow, and the reverse rule is: arrow → bare `${host}`; otherwise (bare-in-block
+  or absent) → escape `''${name}`.

docs/adr/0004-single-neovim-toolchain-source-for-ci.md

@@ -0,0 +1,51 @@
+# CI shares the local Neovim toolchain from a single source
+
+The e2e test environment is defined once, in `slop-env/` (the Neovim overlay in
+`slop-env/nix/` and the runtime config in `slop-env/nvim/`), and consumed through
+the root `flake.nix`. CI builds its test image from that same source rather than
+from a parallel copy. Concretely, the root flake exposes a headless
+`devShells.test` — the same `nvim-dev` derivation, packpath, and
+`~/.config/nvim-dev → slop-env/nvim` symlink the local devShell uses, minus the
+jail/claude/sandbox machinery — and `ci/Dockerfile` builds from it. The former
+duplicate, `ci/nix/kickstart-nix.nvim/`, is deleted.
+
+We adopted this after the test harness diverged between environments: CI ran a
+copy pinned to nixpkgs `nixos-25.05` (Neovim 0.11.2) while local development ran
+`slop-env/` on `nixos-26.05` (Neovim 0.12.2), and the two config copies had
+already drifted (old `require('lspconfig').setup` vs. `vim.lsp.config`/`enable`,
+`nixfmt` vs. `nixfmt-rfc-style`). The whole harness depends on one fragile chain
+— Plenary spawns each spec in a child Neovim that loads `~/.config/nvim-dev/init.lua`,
+and that `init.lua` is what wires `NVIM_PACKPATH` onto the packpath, sets the
+indent options that make `lua_ls` emit spaces not tabs, and configures the LSPs
+(see [the test-harness notes](../../tests/run.sh)). Two copies of that chain means
+two ways for it to silently rot. One source means the version local developers
+run is the version CI gates on.
+
+A flake may only import paths inside its own root, so a sub-flake under `ci/nix/`
+cannot import `../../../slop-env`. Routing CI through the root flake (which already
+does `import ./slop-env/nix/neovim-overlay.nix`) is therefore the mechanism that
+makes a single source possible, not merely the tidier option.
+
+## Consequences
+
+- The e2e Docker path is the only CI surface that consolidates here. The
+  binary-download workflows (`typecheck`, `typecheck-debug`, `gendocs`, `style`,
+  `lint`) fetch upstream release artifacts and are not Nix-based; they pin their
+  Neovim / lua-language-server / StyLua versions independently and must be bumped
+  to match `slop-env` separately to keep the environments aligned. Version parity
+  across those is a manual obligation, not something the flake enforces.
+- `e2e-test.yml` is unchanged: `docker run … nvim-dev --headless -c
+  "PlenaryBustedDirectory <dir>" -c qa`, with no `minimal_init`. A `minimal_init`
+  would replace `init.lua` and break the bootstrap chain above, so the harness
+  must always run the spec child through the real dev config.
+- Test fixtures are opened by **relative** path (`tests/ft/…`), never the Docker
+  WORKDIR absolute (`/ninjection/…`); the working directory is the project root in
+  both environments.
+- The root flake gains a CI-facing output (`devShells.test`). Its inputs include
+  `jail-nix` / `llm-agents` / `nix-slop-dev`; building `test` must not force those
+  (they stay lazy). If a build does pull them, the fallback is to make `slop-env/`
+  its own flake so a lean CI consumer can import it without the agent inputs.
+- Bumping the shared source bumps everything at once — Neovim, treesitter
+  grammars, `lua_ls`, plugins — so a single nixpkgs bump can change formatting and
+  type-check output together. That is the intended trade: one knob, one
+  verification pass, no per-environment surprises.