Grounding the Agent

Grounding reduces mistakes by giving the agent the right context before it writes code.

Two components: a documentation corpus answers questions on demand, and a negative ruleset sits always-on and enforces constraints.

Why the Negative Half Carries More Weight

Ask a model to center cards and it will often choose display: grid. In a Gameface project, that default is wrong.

A negative rule is stronger than a warning. “Never use CSS Grid, Gameface has no grid layout” gives the model something to reject while generating code.

	Documentation corpus	Negative ruleset
Answers	“How do I do X in Gameface?”	“Is this line allowed at all?”
Delivery	Retrieved on demand, per query	Always in context
Content	Patterns, concepts, examples, trade-offs	A flat list of what the engine refuses
Written from	This guide	Engine feature detection

Both matter: the ruleset blocks bad code, and the corpus supplies the right code.

The Documentation Corpus

The corpus is this guide, rewritten for retrieval. Agents read in chunks, not in order, so each chunk has to stand on its own.

Each chunk carries metadata so retrieval can rank by more than keyword overlap:

[TOPIC: layout] [TYPE: concept] [SEVERITY: critical] [SOURCE: laying-out-the-screen.mdx]
## Flexbox-Only: Gameface Has No CSS Grid

Gameface's layout engine relies exclusively on the Flexbox model, powered by the
Yoga layout engine. CSS Grid is entirely absent, and all `grid-*` properties are
rejected by the parser...

> GAMEFACE CONSTRAINT: `display: grid`, `display: inline-block`, `display: contents`
> and `display: inline-grid` are rejected by the engine. Use `display: flex` exclusively.

SEVERITY: critical is the key field. A search for “flexbox layout” should surface a breaking constraint before stylistic advice.

Corpus Contents

• Directoryprompts/rag

  • 01-engine-bridge.md
  • 02-layout.md
  • 03-scalability.md
  • 04-interactions.md
  • 05-graphics.md
  • 06-fonts-and-text.md
  • 07-performance.md
  • 08-gameface-ui.md
  • 09_1-components-basic.md
  • 09_2-components-complex.md
  • 09_3-components-feedback.md
  • 09_4-components-layout.md
  • 09_5-components-media.md
  • 09_6-components-utility.md
  • 10-live-views.md
  • 11-localization.md
  • 12-custom-effects.md
  • 13-accessibility.md
  • 14-animations.md
  • 15-tooling.md

The six 09_* files cover the Gameface UI component library by category. They help most in daily work because they push the agent toward existing components such as Slider, Navigation, and ScrollView instead of rebuilding them.

Retrieval Routes

With the MCP server connected, there are two access paths. search_gameface_docs returns the relevant chunks for a query, and server instructions should tell the agent to call it before writing markup, CSS, or JavaScript. Each topic file is also exposed at gameface://rag/<file>.md, with gameface://rag/index listing them, when a full topic is more useful than a short answer.

A Confident Agent Will Skip the Search

The tool being available is not enough. A project instruction like “call search_gameface_docs before writing any CSS” materially changes behaviour.

The Negative Ruleset

The ruleset is a single file, prompts/negative-rules/negative-rules-injection.md, exposed by the MCP server as gameface://code-instructions. It comes from feature detection run against the engine , not documentation, so it captures edge cases that rarely get written down.

It starts with a short “supported, use freely” section. The rest is prohibitions:

Section	Example rule
CSS, forbidden property families	Never use CSS Grid, multi-column, container queries, logical properties, scroll-snap, or view transitions
CSS, forbidden functions	Never use oklch, lab, or color-mix; never use clamp, min, or max; never use repeating-linear-gradient
CSS, partial-value restrictions	border-style rejects dashed and dotted, box-shadow rejects inset, border-radius rejects percentages
CSS, selector restrictions	:has(), :checked, :disabled, and :focus-visible parse but never match
HTML, forbidden tags and attributes	<input type="checkbox"> is coerced to type="text", <table> has no table layout, <a href> does not navigate
JavaScript, missing or stubbed APIs	No fetch, no localStorage, no IntersectionObserver, no Workers, no AbortController

Two rules cause most of the stylesheet breakage.

First, var() does not resolve inside shorthands. border: 1px solid var(--c) drops the entire declaration, and the same applies to padding: var(--a) var(--b) and transition: opacity var(--d) var(--e). Longhands work. This matters because agents tend to generate shorthand-heavy, token-driven CSS.

Second, some selectors parse but never match. :checked and :disabled fail silently, so markup that looks correct in source still renders incorrectly.

Treat the Ruleset as a Snapshot of One Engine Version

The file reflects the engine versions that were tested. Several entries are marked “unverified”, including url(), image-set(), and cross-fade(), because they could not be probed safely. Re-check it against the Gameface documentation after an upgrade. If a rule conflicts with observed behaviour, suspect the rule before the code.

Using Both Without the MCP Server

Neither component requires the server. Both are plain Markdown in the repository, and every agent supports some form of always-loaded project instructions:

Client	Location
Claude Code	CLAUDE.md at the project root
GitHub Copilot	.github/copilot-instructions.md
Gemini CLI	GEMINI.md at the project root
Cursor	.cursor/rules/

Paste the negative ruleset in as-is, since it is meant to be injected verbatim, and reference the corpus files by path so the agent can open them directly. You lose on-demand retrieval for the corpus, which matters because it is large. You lose nothing for the ruleset, because it belongs in permanent context.

Store It With the Project Rather Than in Personal Configuration

The ruleset describes the target engine, so new teammates inherit it automatically when they clone the repository.