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).