docs: warn users that Cloudflare WAF blocks awareness writes containing inline backticks / code fences

[cmeans-claude-dev]

Summary

Cross-agent handoff from a claude-code (QA/Dev) session on the cmeans/yt-dont-recommend repo on 2026-04-22.

Awareness write calls (update_entry, remember, add_context) fail silently with a Cloudflare block page when the JSON request body contains inline backticks or fenced code blocks and the payload is above ~1–2 KB. Reads are unaffected. Small writes are unaffected. The same content rewritten as plain prose succeeds immediately.

This is not documented anywhere in the MCP server's README or tooling. Users (and agents) hit it blind — the error surface is a raw Cloudflare HTML page with a Ray ID; there is no structured error message pointing at WAF, and awareness itself has no way to surface a helpful message because the request never reaches the server.

Reproduction

Verified on 2026-04-22 from a claude-code instance:

1. update_entry with ~4 KB of markdown content including triple-backtick code fences (e.g. ```yaml blocks) and inline backticks around function names, paths, and CLI flags → blocked (Cloudflare "Sorry, you have been blocked" page, Ray ID in response body).
2. Same entry_id, ~1.7 KB of the same information rewritten as plain prose with no backticks and no code fences → succeeds on first try.
3. Same session, add_context with a 1-line description → succeeds on first try.

Other claude-code instances running on the same host at the same time were writing to awareness without issue (per user confirmation), so this is a per-request content match, not an IP / account / rate-limit problem. The likely trigger is a Cloudflare Managed Ruleset shell-command-injection signature matching backticks adjacent to shell-like tokens — classic false positive on code-in-markdown.

Impact

• Agents composing status notes or project snapshots in markdown will silently fail their writes and may not even realize it (depending on how the caller handles unstructured errors).
• The resilience guidance in the global CLAUDE.md is "retry once and continue" — which here means the write is permanently lost unless the agent diagnoses the WAF and rewrites the payload.
• Users writing entries through other MCP client implementations may see even less useful error surfaces.

Requested action

Update the mcp-awareness README (or a dedicated docs/troubleshooting.md) with a short section along the lines of:

Writing tips — avoid inline backticks and code fences in large payloads.
The awareness service is fronted by Cloudflare, whose managed ruleset can flag JSON request bodies containing backtick-wrapped tokens and triple-backtick code fences as possible shell command injection and block the request before it reaches the server. If a write call fails with a Cloudflare HTML "Sorry, you have been blocked" response instead of a structured error, this is almost certainly the cause.

Workaround: write entry content as plain prose. Describe code-like tokens (function names, CLI flags, file paths, shell snippets, template-expression syntax) in words rather than wrapping them in backticks or fences. Short payloads (under ~1 KB) may slip through with backticks, but larger ones (~4 KB+) reliably trip the rule.

Optional follow-ups worth considering:

• In the MCP server code path, detect when an outgoing response is a Cloudflare HTML block page (not JSON) and translate it into a structured error hint so clients can log something actionable.
• Consider a client-side lint or warning in the MCP tool descriptions (e.g. an extra sentence in the description fields for update_entry / remember / add_context).

Source

• Full diagnosis saved in awareness itself via remember with logical_key=waf-backtick-block (source awareness-mcp, tags awareness / mcp / gotcha). Plus a matching add_context entry tagged feedback / mcp-awareness for live alerting.
• Cross-agent handoff from claude-code session on yt-dont-recommend, branch main at b56f5ff.

Suggested commit type on the docs PR: docs(readme): document Cloudflare WAF content restriction on write payloads.