Grounding

Grounding is establishing what is actually true and current for the surface you are about to change, then acting on that — not on a guess, a memory, or the first grep hit. The hard part is not search; it is picking the authoritative source and reconciling sources that disagree.

Intentional seed. This holds only Grida-specific facts that are not obvious from CLAUDE.md/AGENTS.md. Grow it from real, discovered specifics (concept→file anchors that bite repeatedly, conflicts that actually happened and how they resolved). Do not pad it with generic search advice a competent agent already knows.

Source of truth (scoped to the surface)

Authority is per-surface — the engine model and its TS mirror can each be right for their own surface and still disagree. Name the surface, then trust:

• Canvas render/node model → the Rust engine, now in the engine repo: https://github.com/gridaco/nothing/blob/main/crates/grida/src/node/schema.rs. The TS mirror editor/grida-canvas/ is authoritative for editor behavior and can lag the engine.
• DB schema → supabase/migrations/ (applied, immutable); supabase/schemas/*.sql is a readable projection that can lag — use the database skill.
• Shared AI catalogue and input contracts → repository-root data/ai/facts.json, data/ai/service.json, and data/ai/inputs.json. Edit these authored sources; marked TypeScript literals and crates/grida-ai/data/ assets are generated consumers. Follow ai-models for authoring and regeneration.
• Directory contract → the nearest AGENTS.md/README.md.
• "I remember API X…" → re-read current code; a memory is a claim about a past state, verify before acting.

Disagreement → decide which wins and why (git log -1 recency, what the running entrypoint imports, what tests assert); don't average; surface a material conflict to the user. Never authoritative even when they match: docs/_history/, docs/@designto-code/ (synced — truth is upstream), .ref/. docs/cli/ is the replacement CLI's maintained user guide; only its explicitly retired legacy pages are historical. Follow docs/AGENTS.md for that boundary.

Dead-tree traps

Some directories are git-tracked but dead — a bare rg from repo root returns obsolete hits that look like confirmation: docs/_history/, .ref/. (The legacy editor trees .legacy/ and packages/.legacy/ were retired May 2026 in #759; recover from the snapshot/legacy-with-2023-grida-code-editor-at-202505 branch.) rg already skips gitignored build dirs (node_modules/, .next/, …); don't waste flags there. Scope positively, or exclude the dead trees:

rg PATTERN editor/grida-canvas packages
rg PATTERN -g '!**/docs/_history/**'

Grounding the docs

~360 markdown files; only docs/wg/** and docs/reference/** (plus the user-facing trees in docs/AGENTS.md) are maintained. docs/tags.yml is the controlled vocabulary; tags: frontmatter is the navigation signal. Use the index, don't grep bodies — scripts/docsearch.py reads frontmatter only, self-installs via uv, runs from any cwd:

S=.agents/skills/grounding/scripts/docsearch.py
uv run $S tags                          # vocabulary + usage counts + drift
uv run $S find --tag figma --tag wg     # AND (--any=OR); + --has K --field K=V
uv run $S show wg/feat-fig/glossary/fig.kiwi.md   # one file's frontmatter only

Before trusting a doc over code: draft: true = proposal not built yet (intent ahead); doc_tasks: or stale git log -1 = likely behind.

Related skills

database (DB source-of-truth), research (upstream/peer projects), naming (where new things belong).