Contributing
The rule: nothing from memory
Section titled “The rule: nothing from memory”Every value in the catalog has a source that was opened when the value was written, or a note from someone who ran the thing. A value with neither is labeled estimate.
This applies to people and to coding agents alike. If you are an agent: do not fill in a version, an image name, a license, a setting or a number from what you remember, even when you are sure. Open the page, copy the value, record the URL.
Evidence labels
Section titled “Evidence labels”| Label | Meaning | Required fields |
|---|---|---|
field |
Verified in a real deployment by a named person | verified_by, and notes with hardware and context |
docs |
Taken from official project or vendor documentation, or, where the documentation is silent, from the project’s source code at the release tag; a statement taken from source code says so | at least one URL in sources |
estimate |
Reasoned, or taken from community sources | notes stating the basis |
Every item in sources is a full http:// or https:// URL. Lint checks this for every docs entry, GPU row and rule, and reports C4 when a source is not such a URL.
An entry carries one label for the whole entry. Use docs only when the version, the license, the artifacts under [airgap] and every statement under [choose] each trace to a URL in sources. If one of them does not, the entry is estimate and notes names the unsourced fields.
Adding or updating a component
Section titled “Adding or updating a component”-
Copy the template below to
skills/airgap-architect/catalog/components/. The file name is the component ID plus.toml. An ID is lower-case words of letters and digits joined by single hyphens (the pattern[a-z0-9]+(-[a-z0-9]+)*, for exampledistribution-registry); lint reportsC1for any other ID andC2when the ID and the file name differ. -
Fill it from the project’s official sources. Record every URL you used in
evidence.sources.Field Where the value comes from versionThe latest stable release on the project’s release page. That is the highest stable version, which is not always the release GitHub marks as latest: a project that patches an older line can publish that patch after a newer release. An exact version, never latest. When other entries list this component inrequiresand their documentation names the versions they support, pin the newest release that all of them support, and say why inairgap.notes.licenseThe SPDX identifier of the repository’s license file. If the project has paid editions, say in choose.caveatswhich features need them.airgap.imagesOne row per image the official installation documentation names for a hardware class, with the tag of that exact version. Leave digestempty unless the publisher documents it.hardwarelists the classes the image is for, drawn fromnvidia,amd,intelandcpu; leave it out when the image is for any hardware. The transfer manifest lists only the rows that match the hardware in the blueprint. Do not list aliases of the same image (the same digest under another tag) or images that are only needed to build.airgap.packagesBinaries, archives or packages the official offline or air-gap installation needs, named exactly as the release names them; the transfer manifest lists each one as something to carry. Name the files for linux/amd64 (x86_64) hosts and give the files for other architectures in airgap.notes. When the entry lists container images, list here only what the image route needs; other install routes (wheels, OS packages, tarballs) go intoairgap.notes.airgap.runtime_downloadsWhat the software fetches while it runs: models, plugins, update checks. airgap.telemetryEach telemetry, analytics or update-check feature the documentation describes, with the documented setting that turns it off. If the documentation says nothing, leave the list empty and say so in airgap.notes.airgap.license_servertruewhen any license check needs network access.requiresOther catalog components the documentation says it needs, for example a database. Component IDs only, each the ID of an existing file in catalog/components/; lint reportsC3otherwise. If that entry is not written yet, leave the ID out and add it in the change that adds that entry.tiersThe floors at which the component is still adequate. A component fit for T3 also lists T1 and T2. chooseShort statements, each traceable to a source. alternativesholds component IDs, not product names, under the same rule asrequires: each must be the ID of an existing file incatalog/components/, or lint reportsC3. Leave out an alternative whose entry is not written yet and add it in the change that adds that entry.deeper_skillsPer-tool skills that exist today. Open the repository and confirm the skill folder is there. -
Set
last_verifiedto today. -
Choose the evidence label by the rule above.
-
Run the checks (see “Running the checks”).
-
In the pull request, list what you verified and what you could not.
Template
Section titled “Template”schema_version = 1id = "<component id>"name = "<display name>"layer = "<llm-serving | llm-gateway | ui | identity | observability | orchestration | state | registry>"summary = "<one sentence>"tiers = ["T1", "T2", "T3"]requires = [] # component IDs of existing entries onlyversion = "<exact version>"license = "<SPDX identifier>"last_verified = 2026-01-01
[evidence]level = "docs"sources = ["<URL>"]verified_by = ""notes = ""
[airgap]images = [{ ref = "<registry/repository:tag>", digest = "" }]packages = []runtime_downloads = []telemetry = [{ what = "<what is sent>", disable = "<documented setting>" }]license_server = falsenotes = ""
[choose]when = ["<condition>"]avoid_when = ["<condition>"]alternatives = [] # component IDs of existing entries only, not product namescaveats = []
[[deeper_skills]]repo = "<owner/repository>"skill = "<skill name>"Lint rejects an entry that still contains a value in angle brackets.
Verifying an entry in the field
Section titled “Verifying an entry in the field”When you have run a component in a real air-gapped deployment:
- Set
evidence.level = "field". - Put your GitHub handle in
verified_by. - In
notes, state the version you ran, the hardware, and what you confirmed: that it installs offline, that the telemetry setting works, that nothing tries to reach the internet. - Set
last_verifiedto the date of the deployment.
Keep the URLs in sources.
GPU rows
Section titled “GPU rows”skills/airgap-architect/catalog/gpus.toml has one [[gpu]] row per model. Start a new row from the commented row template at the top of that file (lines 4 to 13), which lists every field. Memory and power come from the vendor’s specification page; record the URL in sources. Leave tdp_w out when the vendor does not publish it. vendor is required and is one of nvidia, amd or intel; the transfer manifest uses it to choose the image variant when the user gives a model but no vendor.
No two rows may share a name: lint reports C1 when a model or alias of one row matches a model or alias of another once case and punctuation are ignored. Give each variant its own name, for example A100 40GB and A100 80GB, and leave out a bare A100 that would fit both.
Thresholds and defaults
Section titled “Thresholds and defaults”skills/airgap-architect/catalog/rules.toml holds the tier thresholds, the escalators, the sizing defaults and the defaults for “unknown” answers. Most are estimates. To replace one, change value, set evidence to field or docs, and fill verified_by or sources. Tests pin the starting values, so update the affected tests in the same pull request and say why the number changed.
Decision tables
Section titled “Decision tables”The tables in skills/airgap-architect/references/layers/ carry one evidence label per row. A row becomes docs only when official documentation supports the whole step from its condition to its choice (a threshold the design spec picked is never documented, so such a row stays estimate); put the URL in the Basis column.
The README demo
Section titled “The README demo”assets/demo/terminal-light.svg and terminal-dark.svg are generated from the real output of the four scripts on design/demo/department-blueprint.json; do not edit them. The README shows only terminal-dark.svg. Every image in the README either brings its own background or is transparent and reads on both GitHub page colours, because the browser picks a <picture> source by the computer’s colour scheme while GitHub draws the page in the GitHub theme. tests/test_readme.py checks this, and assets/brand/BRAND.md explains it. The “How it works” diagram, assets/brand/how-it-works.svg, is the transparent kind: change design/brand/tools/build_how_it_works.py and rerun it, never the SVG. The light variant is for pages that set their own background. Rebuild with python3 design/demo/build_demo.py from the repository root. The build fails while a catalog entry used by that blueprint is stale (lint reports W1): refresh the catalog first.
Running the checks
Section titled “Running the checks”Python 3.11 or newer, no packages to install.
python3 -m unittest discover -s tests -t . -vpython3 skills/airgap-architect/scripts/lint.py --catalog-onlyBoth must pass. Warnings (codes that start with W) do not fail the build.
The documentation site
Section titled “The documentation site”The site in docs-site/ shows every catalog entry, the GPU table, the interview questions, the scripts, the lint codes, this guide and a worked example. Those pages are generated from the files they describe, so after you change a catalog entry, a GPU row, the design spec, references/interview.md, the demo blueprint, the README’s Install section or this file, run:
python3 docs-site/scripts/generate_reference.pyand commit the pages it writes. The tests fail when a page is out of date. To preview the site you need Node.js 24: cd docs-site && npm ci && npm run dev.