A new SurrealDB verification skill, a lede-length fix, and an agent-skills migration prep

Why Care?

Three unrelated threads landed in the same batch. The common thread across two of them: when a doc-writing rule’s wording drifts from what’s actually being enforced, fix the wording everywhere it’s stated, not just where it was noticed. The lede-length rule was already being followed in practice but written down as “one sentence” in some places and unstated in others — now it says the same thing (subtitle-length, ~3 lines max, overflow goes to ## Why Care?) everywhere it’s documented.

What’s New?

New skill — surrealdb-canonical-layer/

A verification skill for any project running a SurrealDB-backed canonical layer (persons/organizations/affiliations plus a schemaless observations log, multi-tenant via client_access). First live consumer is augment-it, whose schema is documented as the worked example; written generally enough that dididecks-ai or memopop-ai can adopt the same pattern later without re-deriving it.

Same shape as [[search-lossless-corpus]]: an MCP server (surrealmcp, the official SurrealDB server) gives raw query access, the skill carries the schema knowledge and the verification discipline on top. The discipline worth calling out: client tagging is its own explicit check, never inferred from a query that already filters by client — a row created without the tag would be invisible to that filter and invisible to the client’s own UI, but still sitting in the shared multi-tenant table. The skill also documents that client_access isn’t the same shape on every table in augment-it’s schema (string[] on most tables, a singular client: string on observations — a real inconsistency, not a typo).

Also documents the actual wiring decision made while setting this up: surrealmcp is a Rust binary with only two distribution paths (build from source, or the surrealdb/surrealmcp:latest Docker image) — no npm/PyPI package. Went with Docker rather than a submodule + build step, and rather than the “submodule in an mcps/ folder, symlinked” shape that was proposed first — MCP servers are discovered exclusively through .mcp.json, never by scanning a folder, so vendoring the source would have been overhead with no functional effect.

Update — changelog-conventions/SKILL.md + references/frontmatter-spec.md — lede length discipline

The lede field’s own guidance had drifted: “one sentence, no more” in one place, an unbounded “subtitle that grabs attention” in another. Both now say the same thing — subtitle-length, one to a few sentences, never more than ~3 rendered lines — and both point at the escape valve: when a lede wants to carry the full story, that’s the ## Why Care? section’s job, not the frontmatter’s.

Update — context-vigilance/SKILL.md + two references — same discipline, every doc-type

The same rule, applied past changelogs to every context-v/ doc-type (spec, prompt, blueprint, exploration, reminder, issue). context-vigilance/SKILL.md gained a new “Lede length discipline” section with a ✅/❌ example pair; references/developing-a-spec.md and references/frontmatter-spec.md got matching updates to their lede guidance so a spec author sees the same rule whichever doc they open first.

Update — sync-skills-symlinks.sh — agent-skills migration prep

The script now scans two source layouts anywhere in the tree — context-v/skills/<name>/SKILL.md (legacy) and context-v/agent-skills/<name>/SKILL.md (the layout being migrated to) — with agent-skills taking precedence on a name collision, and an existing symlink that still points at a legacy skills/ copy gets repointed automatically. No skill directories have actually moved yet — this is the script prepped ahead of the migration, not the migration itself. surrealdb-canonical-layer (this batch’s new skill) landed at the legacy context-v/skills/ location, matching every other skill in the tree today; it’ll move if/when the agent-skills/ migration actually executes.

Files Changed

context-v/skills/
├── surrealdb-canonical-layer/SKILL.md      (new skill)
├── sync-skills-symlinks.sh                 (agent-skills/ migration prep — scan + repoint, no dirs moved)
├── changelog-conventions/
│   ├── SKILL.md                            (lede length discipline)
│   └── references/frontmatter-spec.md      (lede length discipline)
└── context-vigilance/
    ├── SKILL.md                            (new "Lede length discipline" section)
    └── references/
        ├── developing-a-spec.md            (lede guidance updated to match)
        └── frontmatter-spec.md             (lede guidance updated to match)

What’s Next

• The agent-skills/ migration itself — moving actual skill directories, not just the script that will recognize them once moved.
• Provision a scoped read-only SurrealDB Cloud role for the surrealdb MCP connection — currently full read-write plus Cloud instance management, flagged in the new skill as more blast radius than a verification tool needs, not yet resolved.

Reference

• [[search-lossless-corpus]] — the Chroma precedent the new skill’s shape (MCP for access, skill for discipline) is copied from.
• augment-it/context-v/plans/SurrealDB-MCP-Plus-Skill-for-Canonical-Layer-Verification.md — the plan this skill was built from, including tonight’s diagnostic findings on the live FreedomFest 2026 data.