Knowledge Base

The Knowledge Base

Everything the skills answer from lives under knowledge/, generated per release tag by the pipelines described in Generation Pipelines. Nothing per-release is committed to this repository – it is fetched and generated on your own machine, on request (see Sources and Licensing for why).

Layout

knowledge/
├── versions.json                                    (local, git-ignored)
├── cross-references.schema.json                     (committed)
├── model-library.schema.json                         (committed)
└── <tag>/                                            (local, git-ignored)
    ├── metamodel/
    │   ├── index.md, index.json, metamodel.json
    │   └── elements/<Name>.md
    ├── spec/{kerml, sysml2}/                          (only if the OMG PDFs were supplied)
    ├── textual-notation/
    │   ├── index.md
    │   ├── grammar-{kerml,sysml,graphical}.md
    │   └── examples/
    ├── model-library/
    │   ├── index.json
    │   └── packages/<slug>.md
    └── cross-references.json

knowledge/versions.json records which releases are installed locally, which one is the current default, and the upstream commit each tag resolved to (traceability only). knowledge/README.md documents this layout in the repository itself and is explicit: do not hand-edit generated files.

Metamodel

knowledge/<tag>/metamodel/elements/<Name>.md – one file per metaclass, enumeration or primitive type: front matter, Generalizations/Specializations, Owned features, an Inherited features table giving the full effective feature set (read it directly – it is not necessary to re-walk the generalization chain by hand), and Constraints (OCL). index.md / index.json resolve a name to an element.

metamodel.json is the same content as a structural graph, with inheritance closures precomputed: classes carry allAncestors/allDescendants, plus owned and inherited attributes, operations and constraints; also enumerations, primitive types and packages. A multiplicity upper bound of -1 means unbounded. This is what makes set-shaped questions ("every concrete subclass of Usage") a single jq query instead of a directory walk – see Getting Started.

Generated by tools/metamodel-gen from the combined KerML/SysML v2 XMI (see Generation Pipelines).

Specification text {#spec}

knowledge/<tag>/spec/{kerml,sysml2}/<clause>.md – verbatim clause text plus front matter (clause, title, document, version, pages, normative), with index.md / index.json. Generated by tools/spec-extract (Python/pdfplumber) from the OMG specification PDFs, which are copyrighted and never committed – so this folder only exists once a release's PDFs have been fetched (hypha fetch, by default) and hypha generate's spec artifact has run. That artifact provisions its own Python: it fetches and caches uv, which resolves or fetches a matching Python itself and runs tools/spec-extract through it, so no maintainer source checkout or pre-installed Python is needed any more (see Generation Pipelines#tools-spec-extract). Without the PDFs (or on a platform uv can't provision), metamodel lookup and validation still work fully; spec citation can still name the governing clause via cross-references.json, just not quote the text itself.

Textual notation

knowledge/<tag>/textual-notation/grammar-{kerml,sysml,graphical}.md – every grammar production grouped by specification clause, naming the metaclass it builds, the clause it is defined in, and the metamodel features it populates – all three stated by the grammar itself, never matched on a name.

knowledge/<tag>/textual-notation/index.md is the release's keyword reference (read from its own BNF) with a link to every example, and examples/ holds one page per model the release ships, each code block a byte-exact copy of a sources/<tag>/textual/ model, with front matter naming its upstream path and the metaclasses it declares.

Model library

knowledge/<tag>/model-library/index.json resolves a qualified name (ISQBase::mass, ScalarValues::Real) to {kind, file, source}, plus package-level counts. knowledge/<tag>/model-library/packages/<slug>.md holds the verbatim declaration source for a standard-library package (ISQ, ScalarValues, SysML.sysml, ...). See knowledge/model-library.schema.json for the exact shape.

Cross-references

knowledge/<tag>/cross-references.json (shape described by the committed knowledge/cross-references.schema.json) links each metamodel element to the specification clause identifier, the grammar production, the metamodel features its syntax populates, and worked examples. Every edge carries its provenance tier (see Skills and Agents) and the method that produced it.

This file never contains clause text – only identifiers and links. That distinction is what let cross-references be committed while spec/ could not, back when a rolling window of releases was committed at all. Nothing per-release is committed to git any more (see Sources and Licensing), so the distinction no longer decides what ships in git, but it still decides what a spec-citation answer may quote versus merely cite.

Generated last (see Generation Pipelines#order), because it reads the index and the generated examples of everything before it.