A technology registry, referenced by id

Context

Technologies appear in three places: the profile’s highlighted core stack, each project, and each experience entry. Written as free text, the same technology becomes postgres, PostgreSQL and Postgres across three files, and the planned MCP get_stack tool has nothing reliable to aggregate.

Decision

content/stack.yaml is a registry of technologies with stable kebab-case ids. Everything else references those ids.

- id: postgres
  label: PostgreSQL
  category: data
  level: expert
  since: 2017

Astro loads it with the file() loader as a collection, so project and experience schemas can use reference('stack') — a dangling id fails astro check with the offending file and field named. FileSystemContentStore performs the same validation on the .NET side at startup.

get_stack is therefore a join, not a fourth list: the registry, plus usage counts derived from the references, plus a core-stack flag derived from the profile. There is no place to record that a technology is “used in three projects” — that number is computed or it does not exist.

The registry is fully language-neutral. Every label is a proper noun, and category names are UI strings that belong in the UI dictionary, so stack.yaml has no translation overlay (see ADR 0005).

Consequences

• Adding a technology is a two-line edit in one file; using it is an id.
• Typos are caught at build time in both toolchains, with the file and field.
• stack.yaml is YAML rather than Markdown because it is pure data. A Markdown file per technology would be an empty envelope around frontmatter.
• The registry is the one content file with no body, so it is parsed by a dedicated method rather than the generic frontmatter path.

Alternatives rejected

Free-text technology names per project. Simplest to write, impossible to aggregate, and guarantees inconsistent spellings.

Deriving the registry from the union of project references. Removes a file but loses proficiency level, adoption year, and canonical labels, and gives typos nowhere to fail.