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

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

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

• Insert as a top-level availability key in the page's YAML

frontmatter block — same level as title, description, etc.

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