chore: add context files

AGENTS.md

@@ -129,3 +129,7 @@ go run . verify --schema internal/configuration/schema.json --file configuration
 ## Maintaining AGENTS.md
 
 This file documents project conventions for agentic coding tools. Update this file to reflect changes when adding new commands, changing build processes, updating dependencies, or modifying code style conventions. Agents operating in this repository should follow the guidelines outlined here.
+
+When planning or reviewing changes, consult the [CODEBASE.md](./CODEBASE.md) to account for known risks and constraints involving consequential or fragile code paths, integrations, and operational workflows. This map contains selective information; the absence of an entry does not imply an area is safe or unconstrained.
+
+For work involving domain terms, their meanings, preferred wording, or concept relationships, read the [TERMINOLOGY.md](./TERMINOLOGY.md) in the repository root first. Use the terminology file as the source of domain vocabulary; it does not describe implementation.

CODEBASE.md

@@ -0,0 +1,17 @@
+# Codebase Map
+
+## Overview
+
+CRD Catalog gathers Kubernetes CustomResourceDefinition schemas from configured sources and produces schema and definition files for downstream validation and tooling.
+
+## Version ordering
+
+- Values-file versions are sorted as semantic versions; prefixes, suffixes, and leading zeroes can produce incorrect ordering.
+
+## Git sources
+
+- Git sources are cloned with the Git CLI because cloning with the Go Git library used excessive memory.
+
+## Local updater check
+
+- `TestCheckLocal` is intended for step-debugging a local check and should be skipped during normal unit tests.

README.md

@@ -4,7 +4,7 @@ This repository aggregates hundreds of popular Kubernetes CRDs (`CustomResourceD
 
 The intended purpose with this repository is aid with validation, language servers and code generation.
 
-The catalog are checked for updates every 8 hours, but the catalog is also tagged with kubernetes versions to make the catalog available as it were when a specific version was released.
+The catalog are checked for updates every 8 hours, but the catalog is also tagged with kubernetes release versions to make the catalog available as it were when a specific version was released.
 
 ## Known use cases
 

TERMINOLOGY.md

@@ -0,0 +1,36 @@
+# CRD Catalog
+
+This domain covers the collection of Kubernetes CRDs and their schemas from external sources for use by validation and development tools.
+
+## Language
+
+**Source**:
+A configured route for obtaining CRDs from an upstream.
+_Avoid_: Provider, feed
+
+**Upstream**:
+The external repository, chart repository, or service from which a source obtains CRDs.
+_Avoid_: Source
+
+**Source version**:
+A release or revision of an upstream from which CRDs are obtained.
+_Avoid_: CRD version
+
+**CRD**:
+A Kubernetes CustomResourceDefinition that establishes a custom resource kind within an API group.
+_Avoid_: CRD definition
+
+**CRD version**:
+An API version declared by a CRD.
+_Avoid_: Source version
+
+**Schema**:
+The validation schema associated with a CRD version; a CRD version may have no schema.
+_Avoid_: CRD
+
+## Relationships
+
+- A **Source** obtains CRDs from an **Upstream** at a **Source version**.
+- A **Source** can provide multiple **CRDs**.
+- A **CRD** declares one or more **CRD versions**.
+- A **Schema** belongs to a **CRD version**, and a **CRD version** may have no **Schema**.

docs/HOW-TO-CONTRIBUTE.md

@@ -3,8 +3,8 @@
 You need to create a pull request with changes to the sources list using the methods (prepared in order of preference) below:
 
 - [Helm charts](#helm-charts)
-- [OCI charts](#oci-charts)
 - [Git](#git)
+- [OCI charts](#oci-charts)
 - [Uris](#uris) - when everything else fails
 
 We prefer using the [Helm charts](#helm-charts) method to avoid issues like needing to specify each release version with CRD changes or version history being unavailable.
@@ -119,9 +119,9 @@ This entry should contain a complete list of unique value specified in the CRDs
 
 ### `crds`
 
-Each release version that contains addition, changes or removal to CRDs must be listed separately in this list.
+Each source version that contains addition, changes or removal to CRDs must be listed separately in this list.
 
 The `baseUri` combined with each entry in `paths` using the template `${baseUri}/${pathEntry}` must be a URI to a manifest file that is publicly available. You can split the uris as you want, for instance to optimize for the longest common `baseUri`.
 
 > [!TIP]
-> Each release version has their own `baseUri` and `paths` entries.
+> Each source version has their own `baseUri` and `paths` entries.