docs(agents): ban variant="default", color="blue", and em dashes

[ussaama]

Agents kept reaching for off-brand Mantine defaults (variant="default",
color="blue") and sprinkling em dashes into UI copy, partly because the
AGENTS.md files themselves modeled em-dash style and never spelled out the
Button rules in code terms.

• Add a Buttons and colors section to AGENTS.md and frontend/AGENTS.md with concrete do/don't snippets: the theme already defaults to color="primary" + variant="filled", so most buttons need no props. Allowed variants: omit, outline, subtle (light only as a last resort). Never variant="default", never color="blue".
• Add a "no em dashes" rule under Brand & UI Copy, applied to both user-facing copy and the agent docs themselves.
• Strip em dashes from AGENTS.md, frontend/AGENTS.md, server/AGENTS.md so the docs stop modeling the style they're meant to forbid.

Summary by CodeRabbit

• Documentation
  • Updated internal development guidelines and best practices across agent operating instructions, frontend patterns, and server-specific maintenance guidance for consistency and clarity.

[coderabbitai]

Walkthrough

Three agent operating instruction documents are updated to standardize punctuation and phrasing, refine Directus workflows, introduce frontend styling constraints, and clarify server-side patterns. Changes are primarily documentation style improvements with targeted content additions for Directus, frontend color rules, and server reconciliation behavior.

Changes

Core Agent Operating Instructions Refinement

Layer / File(s)	Summary
Documentation style normalization across sections echo/AGENTS.md	Maintenance Protocol, Brand & UI Copy, UI Rules, Translations, Architecture, Dramatiq & Async Rules, LLM Model Groups, Transcription, and Project Management sections are updated to remove em-dashes and tighten phrasing while preserving the underlying rules and structure.
Directus workflow and maintenance enhancements echo/AGENTS.md	New Directus migration check instruction added to Maintenance Protocol. Directus Rules workflow gains step 4 for committing snapshot JSON as source of truth. Python DirectusClient and TypeScript SDK guidance refined to emphasize {"data": {...}} unwrapping and search() return shape validation.

Frontend Agent Guidance Enhancements

Layer / File(s)	Summary
Frontend styling and brand color guidance echo/frontend/AGENTS.md	New "Buttons and brand colors" section documents Mantine variant and color constraints with do/don't examples. Cross-cutting pattern wording clarified, and Dynamic theming CSS variable documentation reformatted (--app-background, --app-text, --app-font-family).
Frontend analytics documentation echo/frontend/AGENTS.md	PostHog tracked-event guidance reformatted with parenthetical grep phrasing and updated punctuation while preserving event names.

Server Agent Guidance Refinements

Layer / File(s)	Summary
Server patterns and background task guidelines echo/server/AGENTS.md	Patterns section emphasizes uv run for local entry points, prefers Directus queries over raw SQLAlchemy for API handlers, and clarifies configuration/embeddings/asyncio uvicorn worker usage. Background task design layered catch-up protocol adjusted for clarity.
Verification topic reconciliation echo/server/AGENTS.md	New section documents server startup reconciliation using reconcile_default_verification_topics function and Redis lock (dembrane:verification_topics:reconcile_lock) with TTL, including recovery behavior if lock is held after a crash.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• Dembrane/echo#568: Directus Rules refinements in this PR build on consolidated Directus client guidance and workflow standardization from the prior PR.

Suggested labels

improvement

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the main changes: banning variant="default" and color="blue" in button rules, and removing em dashes from agent documentation.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/agents-brand-rules

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@echo/AGENTS.md`:
- Around line 55-65: The Button/color guidance in echo/AGENTS.md is duplicated
from frontend/AGENTS.md; replace the full rules block under the "Buttons and
colors" heading with a short pointer to frontend/AGENTS.md and a TL;DR note
(e.g., reference that mantine defaults apply and "never use variant='default' or
color='blue'") so the authoritative rules live in frontend/AGENTS.md and this
root doc only links to it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: c4e4ffa8-d528-4f3a-984e-105db2b36bb1

📥 Commits

Reviewing files that changed from the base of the PR and between a288780 and 810a15c.

📒 Files selected for processing (3)

• echo/AGENTS.md
• echo/frontend/AGENTS.md
• echo/server/AGENTS.md

[dembrane-sam-bot]

Reviewed PR #589. Clean and valuable documentation hygiene.

Key updates:

• Style constraints: Added rules banning em dashes (—) in user-facing copy and within agent docs to prevent AI models from copying and propagating them.
• Mantine Buttons & colors: Defined explicit rules in root AGENTS.md and frontend/AGENTS.md to prevent off-brand styling (banning variant="default" and color="blue" in favor of theme-default color="primary" / Royal Blue).
• Em-dash cleanup: Stripped all existing em dashes from AGENTS.md, frontend/AGENTS.md, and server/AGENTS.md so the docs stop modeling the style they forbid.

CI checks are green. Since my operational limits forbid me from approving PRs directly on GitHub (humans approve), I am submitting this as a comment review. Sameer can go ahead and approve/merge.

Confidence: high