add-availability-badge

Add the availability field to a page's frontmatter so it renders the right applicability badge (engine, surface, access/plan). Source of truth: Notion: How to use and add applicability badges and src/components/availability/availabilityPresets.js (paths below are relative to website/, the repo root for this project). The spec is inlined below — re-fetching the Notion doc on every run wastes tokens on a stable, code-backed spec. If something here looks wrong, check src/components/availability/availabilityPresets.js first — it's the actual render logic — before trusting the Notion doc or this file.

Workflow

1. Get the input, either form:
   • A preset name directly ("use platform_login") — validate it exists in the preset table below, insert as-is.
   • A plain-language description ("this is an Enterprise+ platform feature", "CLI-only, no platform") — resolve it to a preset if one fits, otherwise build a custom object from the field reference. Ask a clarifying question ONLY when genuinely ambiguous — for example, if the feature skips a plan tier (needs plans array, not minPlan), or you can't tell if login is required outside the platform surface.
2. Only add to pages that don't already have availability. This skill inserts; it doesn't audit or fix existing badges. If asked to fix an existing one, say so and stop — that's out of scope.
3. Insert as a top-level availability key in the page's YAML frontmatter block — same level as title, description, etc.
4. State what it renders as (badge text) so the user can sanity-check without opening a browser — see rendering rules below.

Step 1: try a preset first

Presets bundle surface/access/engine into one name. Confirmed current list from availabilityPresets.js:

Preset	Resolves to	Renders as
all_users	access: free (no surface/engine)	(no badge — applies to everyone)
platform_login	surface: platform, access: login_required	"dbt platform" (login segment suppressed on platform)
local_free	surface: local, access: free	"Local development"
local_all	surface: local_development	"Local development"
everywhere_usage	access: usage_based	"Usage-based" (+ "Login required" if not platform)

---
title: Managing environments
availability: platform_login
---

Preset vs. location name: a bare location value (local, local_development, platform) used alone as availability: local is valid too — it sets surface only, nothing else. Don't use bare platform alone, though — it renders identically to platform_login but doesn't document the login requirement for future editors. Always use the platform_login preset instead of typing platform by itself.

Step 2: custom config, if no preset fits

---
availability:
  surface: platform        # local | local_development | platform | omit = every surface
  access: paid_plan        # free | login_required | usage_based | paid_plan | omit = every access level
  minPlan: enterprise      # only with access: paid_plan. starter | enterprise | enterprise_plus
  # plans: [starter, enterprise_plus]  # alternative to minPlan — use ONE, never both
  engine: v2                # v1 | v2 | omit (or "all") = both engines
---

Only include fields the page actually needs — every field is independently optional.

Field reference

Field	Values	Notes
surface	local, local_development, platform	Omit = every surface. local = CLI-only, no platform equivalent. local_development = local tool that also works with platform-connected projects.
access	free, login_required, usage_based, paid_plan	Omit = every access level. free only renders a badge segment when paired with surface: platform (elsewhere free is assumed, no badge). login_required is hidden on surface: platform (login is already implied).
minPlan	starter, enterprise, enterprise_plus	Only with access: paid_plan. Expands upward — minPlan: starter renders "Starter, Enterprise, Enterprise+". Pick the lowest tier that has the feature.
plans	array, e.g. [starter, enterprise_plus]	Alternative to minPlan, for the rare case that skips a tier in the ladder. Use one or the other, never both.
engine	v1, v2	Omit or all = both. v1 = dbt Core 1.x. v2 = dbt Fusion engine 2.0+.

Rendering rules (so you can predict the output without a browser)

• Badge segment order is always engine → surface → access, e.g. "Available in v2 | dbt platform | Enterprise, Enterprise+" — regardless of the order fields appear in the YAML. \| denotes a rendered separator in the badge text, not <VersionBlock> or <Tabs> — don't insert literal <VersionBlock>/<Tabs> for this.
• paid_plan always spells out every tier minPlan expands to (e.g. "Enterprise, Enterprise+"), never just the highest or lowest one.
• Tooltip field labels: engine → "Version", surface → "Where", access → "Access".

Examples

CLI-only, dbt Core 1.x only:

availability:
  surface: local
  engine: v1

Renders: "Available in v1 | Local development"

Applies to literally everyone:

availability: all_users

Renders: nothing — intentional, a badge here would be noise.

Enterprise+ platform feature:

availability:
  surface: platform
  access: paid_plan
  minPlan: enterprise

Renders: "dbt platform | Enterprise, Enterprise+"

Billed on usage, not plan-gated:

availability:
  surface: platform
  access: usage_based

Renders: "dbt platform | Usage-based"

Skips a tier (Starter and Enterprise+, not plain Enterprise):

availability:
  surface: platform
  access: paid_plan
  plans: [starter, enterprise_plus]

Renders: "dbt platform | Starter, Enterprise+"

Fusion-only, also works on platform-connected projects:

availability:
  surface: local_development
  engine: v2

Renders: "Available in v2 | Local development"

Gotchas

• Never set both minPlan and plans — pick one.
• Never write availability: platform bare — use the platform_login preset so the login requirement is documented for future editors, even though both render identically.
• A preset name can never collide with a location name (local, local_development, platform) — the renderer tells them apart by checking if the value matches a known surface first. If you invent a new preset name later, don't name it after a surface value.
• Out of scope for this skill: fixing/auditing availability blocks that already exist on a page. Flag it to the user and stop instead of editing.
• The .vscode/docs.code-snippets autocomplete snippet mentioned in the Notion doc (from PR #9677) wasn't found in this checkout as of this writing — don't assume it's present; check before telling a user to rely on it.