docs: tell writing agents how backticks and heredocs fail

[serkanalgur]

What

Adds an Escaping section to the three agents that hold shell: allow and author code — nexus-coder, nexus-tester, nexus-architect.

Two failure modes, in order of how much damage they do:

1. Nested backtick in a template literal (loud). A backtick placed directly inside a template literal terminates it early, so `outer `in` parses as a binary expression and outer becomes an undefined identifier. Escape it ( `outer \`in\ ``) or inject it via String.fromCharCode(96).

2. Shell heredocs (silent). A heredoc expands \n and backticks and writes a corrupted file, with an error message that does not name the cause. Use write / edit, which pass content whole.

Why

This started as an investigation into an execute tool bug. It isn't one. I ran six template-literal cases through both Node and the code sandbox, and they agree exactly — the sandbox is correct JS semantics, and the one failing case is invalid JS that Node also rejects. The orchestrator's own guidance already carries the "fails loudly, not silently" framing, so the fix is prevention rather than repair.

The heredoc case is the one worth guarding. It bit twice in a single session — a test file lost its \n escapes and Node died with Invalid or unexpected token on the line after a backtick run. That failure is destructive and misattributed: the reported line is not the broken line.

What is deliberately not done

nexus-orchestrator is unchanged. It grants only subagent in its frontmatter and states at line 44 that it never writes code. An escaping rule there would instruct it about a mistake it is structurally unable to make, at the cost of diluting a 240-line file that is already dense with process rules.

No package.json bump. .github/workflows/release.yml:52-56 sets the version from the release tag via npm version "$VERSION" --no-git-tag-version, so a hand-edit would be overwritten on release.

~/.config/opencode/agents/ not synced. assets/agents/ is canonical (nexusAgentsDir(), index.ts:764). Note that NEXUS_SUBAGENT_FILES (index.ts:769) excludes nexus-orchestrator.md, which is instead written only if absent (index.ts:925-926) — so a local edit to that one file would survive a re-setup while these three would be overwritten.

Verification

bun run lint

Clean — biome over 92 files, tsc --noEmit, and the dashboard inline-script parse check all pass. These are markdown-only changes, so no build or test behaviour is affected.

Reviewer note

Worth a judgement call rather than a rubber stamp: if you think the heredoc rule alone earns its place in three files, the template-literal bullet could be dropped from the architect variant — it is the weakest fit, since the architect returns a direction rather than code.