Add a concept to the graph

Each node is one YAML file in plugins/runpod/skills/runpod-usage/concepts/ (called concepts/ below). The format, kinds, relation types and writing style are defined in concepts/README.md. Read it before writing; this skill is the procedure, not the format.

Every file is public-facing. Everything in it must be safe to show a customer and backed by a public source. The validator enforces this.

1. Check it doesn't already exist

Search ids, names and aliases before creating anything:

grep -ril "<term>" plugins/runpod/skills/runpod-usage/concepts/
cd ontology/tools && pnpm build:sqlite && pnpm query concept "<term>"   # resolves names and aliases
pnpm query search "<term>"                                     # finds rules that mention it

• If the idea is a fact about an existing concept, add a rule to that file instead of a new node.
• If it is a new field or state of an existing resource, add it to that file's fields or states.
• Create a new file only for a thing a customer or agent names on its own, or for a flow that spans concepts.

2. Pick the kind

Set is_a for a kind-of parent (cpu-pod is_a pod). Set part_of for the whole it belongs to (worker part_of serverless-endpoint). Top-level resources, catalogs, billing roots, tools and limits sit part_of: runpod-platform.

3. Find public sources first

Write only what a public source supports:

If no public source supports a claim, leave it out. Don't cite internal documents, internal ids or private repositories. Don't create billable resources to verify a claim without asking first.

4. Write the file

Copy the shape of a similar file (pod.yaml for a resource, machine.yaml for infrastructure, pod-deployment.yaml for a process) and fill in:

1. id (kebab-case; the file is <id>.yaml), name, kind, summary (one or two customer-facing sentences), product, is_a, part_of, aliases.
2. surfaces: the REST v2 schema and paths, GraphQL names from the public reference, MCP tools, runpodctl commands, console page.
3. fields and states if the concept has them. With a REST v2 schema, every field must exist on that schema or its create/update request.
4. relations, from the closed set in concepts/README.md.
5. rules: one fact per rule, with an id of <concept-id>.<slug>. Write one to three sentences an agent can act on. Point applies_to at the fields, states or actions the rule constrains. Put related rules on other concepts in see: instead of restating them.

For a process, add steps in order. Each step has an id, title, description, the concepts it involves and the rules that govern it. Steps link to rules that already exist on the concepts. Put only the facts that belong to the flow as a whole on the process itself, such as pod-deployment.stock-is-not-your-machine.

Style: plain present tense, code identifiers in backticks, "Runpod" spelled correctly, and no words like "currently" or "not yet". The full list is in concepts/README.md under "Writing style".

Don't use # comments: pnpm format rewrites the file from its data and refuses a file with a comment, since it would drop it. Put the context in a note on the evidence instead.

5. Validate and look at it

cd ontology/tools
pnpm format              # canonical style; CI runs format:check
pnpm validate --strict   # must report 0 errors and 0 warnings
pnpm scan                # internal links, email addresses and keys; must report 0 errors
pnpm test
pnpm build:graph         # open ../build/graph.html

Common validator errors:

In the graph, find the node, check that its links make sense, and read its panel once as a customer would.

6. Link a guide

Every concept must be covered by at least one skill, reference doc or golden path; pnpm check:guides fails otherwise. Follow the write-guide skill (.claude/skills/write-guide/SKILL.md) to extend an existing doc or write a new one, and to check that the docs already covering the concept still agree with its rules.

7. Commit

Commit the concept file, plus any other files you linked from or to, with a Conventional Commits message that says what the node explains, for example docs(concepts): explain why a stopped pod may not restart.