Skip to content
v3.0.0Apache-2.0

Hypha is the AI agent of the Mycelium ecosystem: a connecting filament between engineers and the SysML v2 specification. Provides skills and an MCP server for KerML/SysML v2 metamodel lookup, standard model library lookup, Systems Modeling API lookup, normative spec citation, and SysML v2 textual-notation validation.

Changelog

All notable changes to mycelium-hypha are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Changed

  • The solution is mycelium-hypha.slnx (fixes #280): the XML solution format replaces the classic mycelium-hypha.sln, and hypha now recognises a source checkout by the .slnx file. A clone made before this change is no longer taken for a source checkout by a newer hypha until it is updated.

[3.0.0] - 2026-11-15

This release starts hypha tools 2.0.0 (tools-v2.0.0), the first with serve. Checked before it: Claude Code and VS Code with Copilot on Windows, and the launcher's first start, an install and a query on Windows, Linux and macOS. The clients that could not be checked yet are listed in #259.

Added

  • A First start workflow checks a published tools release on every platform (refs #201): started by hand with a tools version, it makes the launcher's first start against that release on Windows x64, Linux x64 and arm64 and macOS on Apple silicon and Intel, as a client does: the download, the checksum, the handover to hypha serve, then hypha_release_status, an install and a query. On macOS and Linux it starts the extensionless bin/hypha-launch, so the POSIX script is checked too.
  • The VS Code extension builds for Windows on Arm, and is tested on every platform it builds for (refs #163, refs #165): win32-arm64 is a package target; CI packages and smoke-tests the extension on Windows on Arm and on macOS (Apple silicon and Intel), each against VS Code stable and 1.101.0; and the Publish VS Code extension workflow can publish to Open VSX, through its Trusted Publishing, as well as to the Marketplace. None of these targets is published yet.
  • Configuration for other MCP clients (refs #199): docs/other-clients.md gives the server configuration and the skills folder for JetBrains Junie, Devin Desktop (formerly Windsurf), Zed and Cline, all starting the plugin's launcher from a clone of its release tag. Roo Code, which was discontinued, is left out.
  • A bundle for Claude Desktop (refs #199): a plugin release now carries hypha-<version>.mcpb, an MCP Bundle that Claude Desktop installs. One bundle serves Windows, macOS and Linux: it holds the plugin's launchers and dispatch script, so it downloads hypha on its first start, as the plugin does. The Claude Desktop bundle workflow packs it when a plugin tag is pushed and attaches it when the release is published. Not yet tried in Claude Desktop.
  • Linux on Arm (refs #200): the release publishes a self-contained hypha for linux-arm64, the launcher is built for it, and bin/hypha-launch starts it on an aarch64 Linux, the platform the VS Code extension already shipped for.
  • Manifests for Agent Plugins clients and Gemini CLI (refs #199): a root plugin.json and mcp.json in the Agent Plugins 1.0 format (GitHub Copilot, Cursor, Codex, Kiro) and a gemini-extension.json, each starting the same bin/hypha-launch and sharing skills/ with the Claude plugin. Not yet checked in those clients.
  • One source for every manifest (refs #199): manifest.source.json holds the package's name, description, server command and its two versions, the package version and the hypha version the launcher downloads. Every manifest is rendered from it, and the tests fail when one drifts.
  • API versions through the MCP release tools (refs #228): hypha_install_release, hypha_use_release and hypha_remove_release take axis: "api" to install, switch or remove a Systems Modeling API version, under the same release-operation lock as a release; an install without a tag installs the newest API version offered, and a version asked to be the default becomes it only once its knowledge is generated (the first one installed is the default from the start, as for a release). An API version installed before any release brings the UML primitives its PIM needs, which only a release install provided before. The server still has 17 tools. The version-management skill installs API versions through them, where it gave plugin users hypha api commands to run before.
  • The worked examples through the MCP server and the CLI (refs #228): hypha_lookup and hypha lookup take examples as a kind, by an example's page name or its model's name (a name several examples share lists their pages), hypha_search finds examples by name or upstream path, and hypha://<tag>/examples/<page name> reads one whole. The sysml-validation skill reads the examples that hypha_syntax cross-reference names, where it could only name them before. The textual-notation generator writes textual-notation/examples/index.json for this (with knowledge/examples.schema.json). A release generated before, including one the migration copies into HYPHA_HOME, reports its textual notation as not generated (hypha_release_status, hypha list), and reading an example names the command that generates it; installing the release again (hypha_install_release) adds the index.
  • The REST schema properties of the Systems Modeling API (refs #228): hypha_api with question: "schema", and hypha query api schema --name <schema>, answer a schema of the REST/HTTP API as its OpenAPI document states it: each property's name, type, whether it is required or nullable and what an identifier refers to, and a union's variants. The api-lookup skill answers them, where it said before that it could not.
  • hypha_check_releases, the upstream check in the MCP server (refs #197): compares the installed releases and Systems Modeling API versions with those offered upstream, and names a newer one when there is, so a newer release still reaches the user once the SessionStart hook is gone. It is read-only and open-world, the one read tool that asks GitHub. hypha check now runs through the same IReleaseCheck, with its JSON unchanged.
  • hypha-launch, the MCP server's launcher (refs #198): the one command every client package starts, bin/hypha-launch, which the Claude plugin now registers as its hypha MCP server. It finds the package from its own location, downloads and verifies the hypha that bin/hypha-launch.json names into HYPHA_HOME/bin/ once, and runs hypha serve on the same standard input and output; HYPHA_BIN names a hypha to start instead. When there is none to start, it serves a minimal MCP server whose one tool, hypha_status, says why and how to fix it. A first start answers the client at once, downloads meanwhile and then hands the session over to hypha serve, so the client neither waits for the download nor reconnects; each download is renamed into place once verified, so two clients starting at once cannot clash. On Windows the extensionless path finds bin/hypha-launch.exe; on macOS and Linux it is a script that execs the platform's binary. The download of the CLI moved from the SessionStart hook into the launcher.
  • A one-time move of existing installs into HYPHA_HOME (refs #196): the first time hypha reads an empty HYPHA_HOME, it copies every release and API version the Claude plugin and the VS Code extension installed in their own folders, with their sources, so nothing is fetched or generated again. It copies rather than moves, holds the release-operation lock (and each client folder's own, so a release a client is installing is never copied half built), renames each copied folder into place and writes the manifests last, and records with .migrated-from-clients that it ran. hypha serve copies beside answering; hypha migrate [--from <folder>] copies on request.
  • The hypha MCP server: hypha serve (refs #196), with the official ModelContextProtocol C# SDK over standard input and output, in a new Hypha.Mcp library. Twelve read-only tools answer from the knowledge base: hypha_release_status, hypha_metaclass, hypha_feature, hypha_typed_by, hypha_package, hypha_syntax, hypha_spec, hypha_search, hypha_resolve, hypha_lookup, hypha_diff and hypha_api. Each groups related questions behind a question argument whose values are the hypha query verb names, and returns the same JSON, grounding included. A question that cannot be answered is a tool error naming the fix. The server's instructions explain the grounding tiers and which tool answers what, for clients that load no skills. Standard output carries only the protocol; the log goes to standard error.
  • Specification search, resources and prompts in the MCP server (refs #196):
    • hypha_search_spec, and hypha query search-specification, find the KerML and SysML clauses whose text says a word or phrase, ignoring case and line breaks, the clauses that say it most first, each with its address and an excerpt (IKnowledgeQuery.SearchSpecification).
    • Every hypha://{tag}/{kind}/{name} address is a resource whose contents are the page as Markdown. Every address in a JSON answer now carries its uri, the text a client opens.
    • Five prompts: overview, explain_metaclass, cite_specification, validate_notation and api_lookup, each naming the tools to use and starting from what is installed.
  • Release tools in the MCP server (refs #196): hypha_install_release (fetch and generate, the newest offered release when no tag is given), hypha_use_release and hypha_remove_release, run in the server's own process. An install sends MCP progress notifications, one per file fetched and per artifact generated, in order, and answers with what each artifact did. The release becomes the default only once its knowledge is generated with no generator refusing, so a failed or cancelled install leaves the previous default answering. Each tool takes the release-operation lock, waiting up to ten minutes for another client's change, through a new IReleaseOperations in Hypha.Knowledge; the switch of the default moved into IReleaseSelector, which hypha use now runs through too.
  • A query API in Hypha.Knowledge (refs #194), namespace Hypha.Knowledge.Query: the structural questions the skills and the metamodel-navigator agent answer today with jq, answered in C# from the same generated JSON, so the CLI and the coming MCP server share one implementation.
    • IKnowledgeQuery, for a language release: the installed releases and API versions, with which artifacts each has generated, subclasses (concrete or not), metaclasses with a feature typed by a type, a metaclass's full feature set with where each inherited feature comes from, redefinitions, an index entry, an element's cross-references, which elements' syntax fills in a feature, and a model-library declaration. For validating and citing, also: a metaclass's ancestors, whether one metaclass specializes another and through which supertypes, the OCL constraints and the operations that apply to a metaclass (its own and inherited, each naming where it is declared), an enumeration's literals, subsettings, the elements a grammar production builds, and the elements a specification clause treats (optionally with its subclauses).
    • Specification text: Clause returns a KerML, SysML or API clause with its verbatim text, grounded as NORMATIVE. The text needs the OMG PDFs, so when it was never generated the result is not an error but Unavailable, saying which commands generate it.
    • Search looks a text up across the metaclasses, the standard-library declarations and the clauses (by number or title), ranked as the lookup resolves names: exact, ignoring case, trailing part of a qualified name, then contains. A clause title counts as a name, so the clauses titled Feature rank with the metaclass Feature.
    • HyphaAddress names a generated page as hypha://{tag}/{kind}/{name} (kinds metamodel, model-library, kerml, sysml2), and Resolve turns an address into its page through the release's indexes, never a path given by the caller.
    • Structural queries (fixes #209), modelled on what uml4net's extensions and reports ask of a metamodel, all reading facts the generator wrote:
      • Containers: the composite features through which an element can be owned, typed by it or by one of its ancestors ("where can a PartUsage be nested?"). FeaturesAccepting: every feature that can hold a value of a type. Both list a feature once, where it is declared; with a className, only that metaclass's effective features, so a feature it redefines is left out.
      • Neighbours: the metaclasses its own features are typed by, and the features of other metaclasses typed by it.
      • Package: a package by qualified name or name (Metadata is two packages), with its metaclasses, its nested packages and every metaclass below it.
      • EffectiveFeatures: owned features and the inherited ones no feature of the metaclass redefines. Opposite: the other end of a feature's association, and the feature that redefines it in the metaclass, when one does.
      • FeatureConstraints: the constraints that name a feature among what they constrain; none does in the releases so far, since their constraints name their metaclass.
      • Contributors: the features that subset or redefine a feature, directly or through another contributor, each saying which, such as the 82 that contribute to Namespace::ownedMember (EnumerationDefinition::enumeratedValue by redefining Definition::variant).
    • Diff (fixes #206): what changed in the metamodel between two installed releases, for every element or for one, by its name in either release. Metaclasses, enumerations and primitive types added, removed, renamed or moved; per metaclass isAbstract, visibility and extends; and the attributes, operations, parameters, constraints and literals they own, added, removed, renamed or changed field by field. An element or member is matched on its XMI id, so a rename is one change, not a removal and an addition; when the ids differ it is matched on its name. Upstream regenerated every id between 2025-04 and 2025-06, so across that gap a rename reads as a removal plus an addition. A rewritten documentation text is one documentation change, without the texts. Inherited members are not compared. Each change is a fact; whether it breaks a model is left to the caller. Two documents of different schema versions are refused. For the elements found in both releases it also compares cross-references.json edge by edge: the clauses, grammar productions, features the syntax populates and worked examples, each added, removed or changed in its provenance, method or productions, with a renamed element compared under both names. That part is null when either release has not generated its cross-references or the two have different schema versions; the metamodel diff is still returned. The comparisons are IMetamodelDiffer and ICrossReferenceDiffer, which AddHyphaKnowledge registers and KnowledgeQuery takes in its constructor.
    • Keyword (fixes #205): what a keyword or operator such as ref, individual or :>> does, read from keywords.json. One use per grammar that lists it (optionally only one grammar), with its kind, the productions that write it and the metaclasses whose syntax includes it, each written directly or through a helper, grounded as DERIVED. In SysML, the expression keywords and operators (and, istype, true, +) come from the KerML expressions SysML calls, and SyntaxFrom says so; a KerML declaration keyword such as classifier is not SysML syntax, so asking SysML about it finds nothing.
    • hypha query (refs #195): one verb per question of IKnowledgeQuery and IApiQuery (hypha query subclasses --of Usage, hypha query keyword --word ':>>', hypha query api type --name Commit), each with --tag/-t (a release, or for api an API version) and --json. With --json it prints the whole result: the answer, its grounding (tier, release, source file) and, when an optional artifact was never generated, why. The results are written through QueryJsonContext, a source-generated contract in camel case that the MCP server will reuse. hypha list now reads the release inventory through the query API, and hypha lookup reads the metamodel and model-library indexes through the query API's typed contracts and document cache, so both read an index once while it is unchanged and both refuse one the generators could not have written (hypha lookup --json output is unchanged).
    • IApiQuery, for a Systems Modeling API version: a PIM class, the cross-references of a type or a service operation, and a clause of the API specification.
    • Every result carries its grounding: the tier (NORMATIVE, MODEL or DERIVED), the release and the generated file it was read from, relative to the folder holding knowledge/. A name the release does not have is a normal result, not an exception.
    • Each document is read once, through its source-generated contract, and read again when its file changes, so a release regenerated by another process is not answered from stale memory. The cache (IDocumentCache) and the specification text reader (ISpecificationReader) are injected; AddHyphaKnowledge registers one of each, shared by both queries. Every read failure is a KnowledgeLookupException: a missing, unreadable (being rewritten), empty or malformed file, and one of the wrong shape, which the query contracts refuse instead of reading with members left null.
    • The release lookup, the query API and the API query choose a version and word their messages in one place, so the verbs those messages name are written once.
    • KnowledgeQueryJqTests checks every answer against the documented jq query on the committed golden metamodel and small fixtures; CI runs them with HYPHA_REQUIRE_JQ, so they cannot be skipped there.
    • MetamodelJsonContext now carries the camel-case naming policy of the file format, so metamodel.json and index.json read back through its default instance. IKnowledgeLayout.MetamodelGraph names metamodel.json, and ModelLibraryFile.ReadIfPresent reads the model-library index. SpecificationIndex is the shape of the index.json that tools/spec-extract writes, so the specification text is read through a contract as well.
  • The VS Code extension is on the Visual Studio Marketplace (refs #155), as a preview pre-release under the mycelium-cmbse publisher: version 0.1.0 for Linux x64 and arm64.
    • The Publish VS Code extension workflow (.github/workflows/publish-vscode.yml), started by hand, packages each target and publishes it through Marketplace Trusted Publishing (vsce publish --oidc), so no Marketplace token is stored. A run waits for approval in the vscode-marketplace environment, and refuses to publish unless tools/ matches the tools-v<cli-version> tag the bundled CLI is labelled with.
    • The extension has an icon, the Preview flag and a changelog of its own; package.mjs takes --pre-release, and linux-arm64 is a package target. @vscode/vsce is 4.1.0, the first version with --oidc.
  • The VS Code extension for Windows x64 (fixes #157), validated end to end on Windows 11 and published with extension version 0.1.1 beside Linux x64 and arm64. CI now packages and smoke-tests the Windows VSIX too, against VS Code stable and against 1.100.0.
  • A release-operation lock in Hypha.Knowledge (fixes #166), compatible with the VS Code extension's: the same .release-operation.lock file in the repository root, the same {"pid", "token"} content and the same recovery rules, so an operation that changes releases on its own (such as the coming MCP install) and an extension install never run at the same time. The CLI's own verbs do not take it, because the extension runs them while it holds the lock.
  • Safe concurrent writers (refs #195), for several MCP servers, the CLI and the VS Code extension working on one knowledge base at once.
    • HyphaKnowledgeOptions.ReleaseLockWait makes IReleaseOperationLock.AcquireAsync wait for a held lock instead of refusing it at once, including one held by another operation of the same process. The default, zero, keeps refusing at once, as the extension does; the lock protocol is unchanged. Between tries a waiter only reads the lock, and runs the protocol again once the lock is free or its owner is gone, so it does not keep the recovery file in place while it waits.
    • A lock or recovery file removed by the other side in the instant after creating it failed is now reported as a held lock, not as a raw IOException.
    • Both versions.json manifests and every generated knowledge file are written through ReaderSafeFile: to a temporary file beside it, then renamed over it, so a reader in another process sees the old file or the new one, never half of one.
  • Progress for fetching and generating (refs #195): one KnowledgeProgress record (Operation, Step, Done, Total, Message), replacing FetchProgress, that both the CLI and the coming MCP server consume through an IProgress<KnowledgeProgress>.
    • IReleaseInstaller reports each file of the metamodel, textual and, now, specification inputs; IApiInstaller.InstallAsync takes a reporter too and reports each of its three or four documents.
    • The loop that runs every generator in Order moved from the CLI into the library, as IKnowledgeBuilder<TGenerator> (KnowledgeBuilder), registered by AddHyphaKnowledge for the release generators and the API generators. It reports each artifact as it finishes, written or skipped, counting within its release, and stops at a generator that refuses, naming it. hypha generate, hypha api generate and move-window run through it.
    • hypha fetch, hypha api fetch, hypha generate and hypha api generate show a live progress display, one bar per step, when their output is a terminal, and nothing more when it is redirected, as for the VS Code extension. On a terminal the log is written above the bars, and the HTTP request and retry logging is held to warnings, as under --json, unless --log-level Debug or lower is asked for.
  • knowledge/<tag>/textual-notation/keywords.json (refs #205), written by a new keywords generator (hypha generate keywords), with knowledge/keywords.schema.json. Per grammar (kerml, sysml), every keyword and operator the release's own BNF writes, as reserved, contextual or operator (plain punctuation left out), with the productions that write it and the metaclasses whose syntax includes it: part introduces PartUsage and PartDefinition directly, and ref reaches the 41 usages through BasicUsagePrefix. A metaclass's syntax follows only bare calls, a reference that is not the value of an assignment, into productions that build nothing, the same metaclass or a supertype, so a selector handing over to a subtype and an assigned owned element do not count. A literal that is only ever an assigned value, such as private, or + in KerML, lists its productions and no metaclass. The SysML grammar calls six KerML productions without defining them (OwnedExpression and four more expressions, and MetadataFeature), so the sysml table also lists what they write, such as and, istype, true or +, with KerML's productions and syntaxFrom: "kerml" (schema 1.1.0); a literal SysML writes itself keeps its own entry. Only the clauses that define the called productions are followed, so KerML's declarations, which its expression bodies lead on to, do not count: true comes from BooleanValue, not Invariant.

Changed

  • Fewer GitHub API requests, and a warning before the anonymous limit runs out (refs #224):

    • Listing a repository's tags stops at a page with fewer than 100, instead of asking for an empty page after it, which halves what a check or an install of the newest release asks.
    • hypha serve keeps the tags it read for ten minutes and each tag's commit for as long as it runs, so a check followed by an install, or installing a release again, asks no more.
    • A check now makes about three requests, installing the newest release about five (it was six and seven).
    • When 20 or fewer of GitHub's 60 requests an hour without a token are left, hypha_check_releases and hypha_install_release carry a notice saying how many, until when, and to set GITHUB_TOKEN.
    • A request refused because the limit is used up says so, with when it resets, rather than as an upstream that cannot be reached.
  • The server's instructions stand on their own (refs #199): for a client without the skills, they now say what to do when nothing is installed, that a closure or a comparison is one call, what the model library does not resolve, how to check textual notation, what to give when the specification text is missing, and to confirm a removal, which cannot be undone.

  • The metamodel and model-library skills answer through the MCP server (refs #197): metamodel-lookup and model-library-lookup call the server's tools by their bare names (hypha_metaclass, hypha_feature, hypha_typed_by, hypha_package, hypha_syntax, hypha_lookup, hypha_search, ...), with no jq and no file paths, so they work in any client that starts the server. A question about a set, a closure or a comparison of metaclasses is one tool call. A test checks that every tool a skill, agent or command names is one the server has, and every question and argument it names one that tool accepts.

  • The specification-citation and validation skills answer through the MCP server (refs #197): spec-citation reads clauses with hypha_spec, finds them with hypha_search_spec, hypha_search and hypha_syntax, and names the governing clause, with its provenance, when the specification text was never generated. sysml-validation checks keywords, productions and feature assignments with hypha_syntax and reachability and multiplicities with hypha_metaclass, and names the release's worked examples of an element without reading them.

  • The version-management skill installs, switches and removes releases through the MCP server (refs #197): hypha_check_releases, hypha_install_release, hypha_use_release and hypha_remove_release replace the hypha commands it ran with --repository-root in the plugin's folder, so a release installed in one client answers in every other.

  • The API skill answers through the MCP server (refs #197): api-lookup reads PIM classes, how a PIM type lines up with its PSM schemas and the specification, service operations with their endpoints, and API specification clauses through hypha_api, with no jq and no file paths.

  • Installing the Claude plugin needs nothing else (refs #197): no Git for Windows, no new session for a hook to run, and no jq. The plugin starts the MCP server through its launcher, which downloads hypha the first time.

  • A relative HYPHA_HOME is refused (refs #196): it would be resolved against each process's working directory, so two clients started from different folders would not share one home or one lock. The error names the value and asks for an absolute path.

  • One knowledge location per user, HYPHA_HOME (refs #195). Run outside a source checkout without --repository-root, hypha now keeps sources/ and knowledge/ in the HYPHA_HOME folder, by default hypha in the per-user application data folder (%LOCALAPPDATA% on Windows, $XDG_DATA_HOME or ~/.local/share on Linux, ~/Library/Application Support on macOS), instead of failing to find a repository. In a source checkout nothing changes: the checkout above the working directory is still used, and --repository-root and --output still win. A set HYPHA_HOME wins over a checkout found only above the hypha program itself.

    • The managed toolchain (uv, its package cache and its Python) now lives in toolchain/ in that folder unless --toolchain-cache-root says otherwise, rather than uv in mycelium-hypha and its cache and Python in uv's own per-user locations. The first specification extraction after updating downloads uv and Python once more.
    • HyphaKnowledgeOptions.Home sets the folder in code; HyphaHome.Resolve is the default. UvProvisioner's constructor without a cache root, and UvProvisioner.ResolveCacheRoot, are removed.
    • The VS Code extension passes its own folder, as before. The Claude plugin reads HYPHA_HOME, through the MCP server its launcher starts.
  • metamodel.json 2.1.0: every owned attribute, operation, parameter, constraint and enumeration literal carries its xmiId (refs #206), so a diff between two releases recognizes a renamed member. Regenerate every installed release (hypha generate --tag <release>, and hypha api generate --tag <version> for an API version): a 2.0.0 document is refused with that advice.

  • metamodel.json 2.0.0: the generator writes the UML semantics, the query API reads them (fixes #208). uml4net already computed them; the query API had been working some of them out a second time. Regenerate every installed release (hypha generate --tag <release>, and hypha api generate --tag <version> for an API version): a 1.0.0 document is refused with that advice.

    • redefines and subsets name the feature's owner, { "class", "association", "feature" }, instead of a bare name, which several metaclasses share (66 of the 140 redefinitions in a release named such a feature). An end an association owns has association set instead of class.
    • New per attribute: opposite (the other association end; null when that end, or its association, has no name, as in the Systems Modeling API PIM), isDerivedUnion, isUnique, isReadOnly and defaultValue; per inherited attribute, redefinedBy, the feature that redefines it in that metaclass.
    • New per class: inheritedOperations and inheritedConstraints, as references to the declaring class's entry, each inherited operation with redefinedBy. Owned operations list what they redefines, and constraints their constrainedElements. The file grows from about 8 MB to about 16 MB; copying every inherited operation and constraint in full would have made it 26 MB.
    • Constraints and Operations read the inherited members from the document instead of walking the ancestors. Operations leaves out an inherited operation that the metaclass's context redefines, so it no longer lists two OCL bodies for one operation (such as namingFeature for a ConstraintUsage).
    • Redefinitions and Subsettings take an optional owner, after tag so a call written for the previous signature still means the release, and their results name the owner of the redefined or subsetted feature. Features returns the new facts. Specializes answers from the generated allAncestors (a metaclass conforms to itself) and returns Specializes as a field; the chain of generalizations stays as an explanation.
    • The metaclass pages link a redefined or subsetted feature to the page of the metaclass that owns it. A feature that redefines an inherited one of the same name used to link to itself.
    • The skills' and the metamodel-navigator agent's jq recipes follow the new shape.
  • Hypha.MetamodelGen is now Hypha.Knowledge.Metamodel (fixes #193), the first step of the MCP refactor. Its test project is Hypha.Knowledge.Metamodel.Tests, and AddHyphaMetamodelGen is now AddHyphaMetamodel. The tools/metamodel-gen/ folder keeps its name, and Hypha.Knowledge stays one library: reading and writing the knowledge are kept apart by namespace, not by project.

    • Every generated JSON document (the version manifests, cross-references, model library, the Systems Modeling API documents, metamodel.json and index.json) is written through a source-generated JsonSerializerContext beside its types, instead of reflection, and the documents the tools read back as typed objects are read through it too. metamodel.json and index.json are not read back as typed objects yet; that comes with the query API (#194).
    • The types metamodel.json and index.json are written in moved from the metamodel generator into Hypha.Knowledge (namespace Hypha.Knowledge.Metamodel), so code that reads them needs neither the generator nor uml4net.
    • knowledge/metamodel.schema.json describes metamodel.json, which until now was the one generated JSON document without a committed schema. MetamodelSchemaTests checks the produced document against it.
    • The file formats are unchanged: every generated document is written byte for byte as before.
  • Hypha.Tools on nuget.org has a proper package page (fixes #160): a package readme, the Mycelium icon, project and repository URLs, copyright, release notes that link to the tools-v<version> GitHub release, and a description and tags that cover the Systems Modeling API, lookup and the JSON output. The repository README adds the command-line install from NuGet.

  • CI and the publish workflow install the extension's dependencies with npm ci --ignore-scripts, so no dependency install script runs in a job that can publish.

  • CI runs once per pull-request commit (fixes #173): Build & Test & SonarQube runs on pull requests and on pushes to development and main only (and by hand), instead of on every push as well, which ran everything twice. Every action the workflows use is updated to its current major version, pinned to a release at least two weeks old, and the .NET tools the workflows install (dotnet-sonarscanner, dotnet-coverage, nuget-license) are pinned. Dependabot now proposes weekly updates for the workflows' actions, the NuGet packages, the extension's npm packages and tools/spec-extract, grouped per ecosystem and only for versions two weeks old.

Removed

  • The Hypha.Tools.Hook project (refs #200): the retired SessionStart hook's source and tests, which only shared the launcher's download code. The workflow that builds the launcher binaries is now launcher-binaries.yml (Launcher binaries), renamed from hook-binaries.yml.
  • The metamodel-navigator, spec-citation and sysml-validator agents (refs #197): their fan-out questions are single tool calls now. metamodel-lookup says which, and spec-citation and sysml-validation take over the other two, including a whole model to check.
  • The plugin's SessionStart hook (refs #197): hooks/native/, the hook entry and hyphaCliVersion in .claude-plugin/plugin.json, and the hook's build in the binaries workflow, which now builds only the launcher. Asking about releases runs hypha_check_releases instead, and installing one reports when the specification text was skipped.
  • jq (refs #197): no skill runs it any more, and the README no longer recommends it.

Fixed

  • The first specification search in a fresh release is fast (refs #224): hypha_search_spec took 18 to 33 seconds on its first call after an install, because it opened the release's 1,500 or so clause pages one after the other, and the virus scanner checks each newly written file the first time it is opened. The search now reads eight pages at a time: on Windows the first search takes under two seconds and the next ones under one.
  • A release the migration left out is named, and why (refs #224): a release or API version an earlier client had installed in an older format is not copied into HYPHA_HOME, and was reported only as a warning on standard error, which a client may never show, so hypha_release_status said nothing was installed without saying why. The migration now records each one with its reason in .migration-left-out.json, and hypha_release_status (leftOut), hypha list and hypha migrate name it until it is installed again.
  • A refusal is no longer logged as a failure (refs #224): a tool that refuses, such as removing the default release or asking about a release that is not installed, sent the client a proper message but was logged as [ERR] "<tool>" threw an unhandled exception. The server now answers it as a tool error itself and logs it at information level. A failure, a knowledge file that cannot be read or an upstream that cannot be reached, is answered the same way but logged as a warning with its exception; a protocol error and any other exception are reported by the SDK as before.
  • A project folder no longer captures the hypha server (refs #224): hypha serve used to answer from, and install releases into, any folder above its working directory that held both sources/ and knowledge/, and an AI client usually starts it in the user's project. It now ignores its working directory and uses HYPHA_HOME, the folder every client shares, unless given --repository-root. The other verbs still use a source checkout above the working directory, but only a real one: a folder that also holds mycelium-hypha.sln.
  • An install through hypha serve no longer hangs at the specification text (refs #237): the processes hypha starts (uv, and the Python it runs) inherited its standard input, which under hypha serve is the pipe the MCP client writes to, and on Windows the extractor's build never started, holding the release lock. Each child now gets an input of its own, closed at once.
  • The specification text is generated in HYPHA_HOME too (refs #237): the specification generators ran the Python extractor from tools/spec-extract under the knowledge folder, which only a source checkout or a plugin's own folder has, so an install through the MCP server, or a dotnet tool install, skipped the specification text. hypha now carries the extractor and unpacks it into toolchain/spec-extract/, next to uv, keeping it in step with the copy it carries; a source checkout still runs its own.
  • hypha serve keeps the MCP SDK's per-request log lines off standard error (refs #224): they are held to warnings and errors, as the HTTP request lines already were, so a client that never reads standard error cannot fill it. --log-level Debug still shows them.
  • The model-library resource says how far it reaches (refs #224): its description says a declaration's page is up to 160 lines of its package's source from the declaration on, and that hypha_lookup reads further, so a declaration longer than that is not taken for a whole one.
  • A prompt called without its argument names the argument (refs #224), rather than the SDK's generic "An error occurred.".
  • The migration into HYPHA_HOME leaves out a release generated in an older format (refs #224): a release or API version whose generated documents state an older schema version than this hypha reads is not copied, with a warning, so it is installed again rather than read wrongly.
  • A relative HYPHA_HOME is refused before any work (refs #224), also with --repository-root, rather than once a generation first needs the toolchain kept there. Giving --toolchain-cache-root as well leaves HYPHA_HOME unused, and unchecked.
  • The launcher refuses a relative HYPHA_BIN (refs #224): it would be resolved against the folder each client starts the server in. The model is told why, through hypha_status.
  • Installing into a folder that is not a source checkout generates the metamodel (refs #196): sources/PrimitiveTypes.xmi, the OMG UML primitives every release's metamodel refers to, is committed in a checkout but was nowhere else, so an install into HYPHA_HOME failed at the metamodel. Hypha.Knowledge now carries the file and the installer writes it when it is missing.
  • The repository README no longer says spec citation needs a source checkout: since the uv-based specification generation, hypha generate builds the text itself.
  • The extension's installed-VSIX smoke test finds VS Code's cli.js on Windows from 1.145 on, which keeps it under a folder named after the build's commit; it now asks the installation's own launcher (bin/code.cmd) for the path, and looks in both known layouts when it cannot.

[2.3.0] - 2026-11-07

Added

  • The Systems Modeling API & Services is part of the knowledge base (fixes #146), as a body of knowledge with a version of its own beside the language releases:
    • the PIM: every type of the Platform Independent Model, in the shape of the metamodel pages (attributes with multiplicity, derivation, subsetting and redefinition, the full effective attribute set, and the six services with their operations). The Data interface and the UUID, IRI and ISO8601DateTime data types get pages too.
    • the REST/HTTP PSM: one page per API schema of the OpenAPI document, with required and nullable members and whether the endpoints use it as a request or a response model, plus every endpoint.
    • the API specification text, clause by clause, quotable through spec citation on the same terms as the KerML and SysML texts (generated locally from the PDF, never committed).
    • cross-references.json: PIM type ↔ specification clause ↔ PSM schema, the PIM members a PSM model leaves out, the PSM-only members, and the endpoint each PIM service operation maps to. Every edge names the method that produced it.
    • a new api-lookup skill, and the spec-citation and version-management skills now cover the API.
  • hypha api discover | fetch | generate | list | use | remove install and manage an API version independently of the language releases, in sources/api/<version>/ and knowledge/api/<version>/ with a manifest of its own (knowledge/api/versions.json). An API version is a tag of Systems-Modeling/SysML-v2-API-Services that is also a language release, 2025-02 or later. The PIM model is the one input no repository carries; it is fetched from the OMG document server (ptc/25-02-29).
  • hypha api list --json reports every installed API version, the default, and which of its artifacts (PIM, OpenAPI, cross-references, specification text) have been generated, in the same shape as hypha list --json with versions in place of releases.
  • python -m spec_extract --api-version <version> extracts the API specification.
  • hypha lookup resolves a metamodel or model-library name in an installed release and prints one page of its generated file (fixes #153). A name resolves exactly first, then ignoring case, then by a trailing part of its qualified name (Real for ScalarValues::Real); names that only contain the request are offered as candidates, never picked. A model-library lookup starts at the declaration rather than at the top of its package page. Hosts such as an editor extension use it instead of reading the generated indexes themselves.
  • hypha list --json reports every installed release, the default, and which of its artifacts (metamodel, textual notation, model library, cross-references, specification text) have been generated.
  • --toolchain-cache-root keeps the uv executable, uv's package cache and the Python it installs under one folder.
  • A VS Code extension for GitHub Copilot (extensions/vscode/, fixes #151), a preview that is not yet on the Marketplace. A platform-specific VSIX bundles a self-contained hypha CLI, so nothing has to be installed by hand: on first use the CLI downloads uv, which provides the Python that specification extraction needs.
    • Commands: Show Installed Releases, Check Available Releases, Install a SysML v2 Release, Change Default Release and Remove a Release. Installing asks for consent first, reports progress and can be cancelled; a release becomes the default only once it has been generated.
    • Copilot tools: #hyphaReleaseStatus reports the installed releases and which of their artifacts are present; #hyphaLookup resolves a metamodel or model-library name through hypha lookup and answers with a release-qualified source link, the candidates when a name is ambiguous, and one page at a time.
    • Releases, generated knowledge and the toolchain live in the extension's global storage, shared by every workspace on the same host. A lock file in that storage keeps two VS Code windows from changing releases at the same time.
    • Specification PDFs and extracted text are never packaged; they are downloaded and generated locally. End-to-end validation has been done on Linux/WSL; the Windows and macOS packages build but are not yet validated end to end.
    • HYPHA_CLI_VERSION sets the version the bundled CLI reports, so a VSIX built for publication names the hypha tools release it carries; any other build reports 0.0.0-dev.

Changed

  • The SessionStart hook now provisions hypha tools 1.5.0 (hyphaCliVersion), which carries the CLI changes in this release.
  • Every --json document (check, list, lookup, api list) is one line on standard output with no banner; log lines go to standard error, and every failure (including one before the verb runs, such as cancellation or an unreachable upstream) is written as {"error": "..."}.
  • Bumped uml4net (uml4net.xmi, uml4net.Extensions, uml4net.Reporting) to 9.2.0, which provides QueryConstraintBody and QueryBodyConditionText itself. The generators now use those and hypha's own copies in ModelQueryExtensions are gone (fixes #145); the generated knowledge is byte-identical.

Fixed

  • uv is found in a wrapped archive. The Linux and macOS uv archives keep the executable in a uv-<target>/ folder, which the provisioner did not look in, so specification generation could not start there. Both the flat and the wrapped layout are now found, and an archive without the executable is no longer marked as verified.
  • hypha remove refuses a tag that is not a release, whatever knowledge/versions.json lists. The tag names a folder that is deleted recursively, and knowledge/api/ now sits beside the release folders, so a hand-edited manifest listing api could otherwise remove every installed API version.
  • The metamodel knowledge base now carries each operation's body OCL (fixes #143). An operation's bodyCondition is a constraint the operation owns, not one of its class's rules, so the class-level constraint walk never reached it and every derivation body was dropped. Each metamodel.json operation now has a body (the OCL of its bodyCondition, empty when it has none) and its documentation, and element pages gain an Operations section with each operation's signature, documentation and body. On release 2026-05 all 99 body conditions come through, on the 39 metaclasses that own operations.

[2.2.0] - 2026-10-05

Changed

  • The SessionStart hook now provisions hypha tools 1.4.0 (hyphaCliVersion), which carries the uml4net upgrade below.
  • Bumped uml4net (uml4net.xmi, uml4net.Extensions, uml4net.Reporting) to 9.1.0 (tools 1.4.0). Optional [0..1] enumeration properties are now nullable, so an unset visibility reads as public, the UML 2.5.1 default for a PackageableElement, and the generated metamodel keeps its exact shape. The only change to generated knowledge is in documentation text: every owned comment of an element is now used (8.x dropped all but one), and words on adjacent source lines are kept apart (e.g. Elements. Note instead of Elements.Note), which also changes three index summaries. Grammar references, textual notation, model library and cross-references are byte-identical.
  • ModelInspector now selects interesting classifiers; the metaclass golden fixtures take its classes, so that set moved (8 metaclasses added, 6 orphaned golden files removed).

[2.1.2] - 2026-09-07

Fixed

  • The SessionStart hook no longer throws a raw PowerShell parse error on Windows without Git Bash (fixes #139). Its dispatch shim is POSIX-shell-only (case/esac, uname), and Claude Code falls back to PowerShell for shell-form hooks when Git Bash isn't found, which can't parse it. The hook now pins "shell": "bash", so Claude Code either runs it under Git Bash or reports a clear, dedicated "shell not found" error instead. That makes the project's existing Git Bash dependency explicit rather than reimplementing the OS/arch dispatch in a second language. No behavior change on Linux/macOS/Windows-with-Git-Bash, where bash was already the default.

[2.1.1] - 2026-09-06

Fixed

  • /overview no longer tells users to manually download the OMG spec PDFs or manually run tools/spec-extract (fixes #135). Both are automatic now (hypha fetch/hypha generate's spec artifact, #129); the command's own instructions had gone stale.

[2.1.0] - 2026-09-06

Added

  • hypha generate's new spec artifact quotes verbatim OMG spec text without a maintainer source checkout (fixes #129, tools 1.3.0). SpecGenerator fetches and caches uv, which resolves or fetches a matching Python itself and runs tools/spec-extract (Python/pdfplumber) through it, with no pre-existing Python or provisioned .venv needed. A C# port of the pipeline was evaluated first (the PdfPig comparison spike, #128) and rejected: even after fixing a real bug, it still fell short of the mature Python pipeline's quality, and a port can at best tie Python, never beat it. tools/spec-extract also gained a real CLI entry point (python -m spec_extract) alongside its existing pytest-driven maintainer flow.

[2.0.0] - 2026-09-04

Removed

  • The committed knowledge floor (fixes #106). knowledge/2026-04/, knowledge/2026-05/, sources/2026-04/, sources/2026-05/ and knowledge/versions.json are no longer committed to git (2,120 files). Part 1 (hypha use/remove/check, below) landed the interactive mechanics while this floor still existed, so they could be verified before anything was deleted; this closes #106 by deleting it. A plugin install now fetches and generates every release identically, entirely on the user's own machine, on request, rather than two privileged releases pre-installed and everything else second-class.

Changed

  • .gitignore, CLAUDE.md, README.md, sources/README.md and knowledge/README.md rewritten for the no-committed-floor model (fixes #106): /sources/*/ and /knowledge/*/ are now root-anchored git-ignore patterns covering everything per-release, not just the OMG PDFs and their extracted text.
  • Hypha.MetamodelGen.Tests reads a committed test fixture instead of sources/<tag>/xmi/ (fixes #106): one real release's XMI is committed under tools/metamodel-gen/Hypha.MetamodelGen.Tests/Fixtures/xmi/, a fixture for this test project alone (tools/ is never shipped with the plugin), so the generators still have real regression coverage without a network fetch or a reintroduced distributed knowledge floor. The accepted consequence: only that one fixture release is exercised, not every installed release, since nothing per-release is committed to loop over any more.
  • KnowledgeRegenerationTests, MetamodelJsonGoldenTests, MetamodelJsonInvariantTests and PackageDiagramGoldenTests redesigned (fixes #106): with no committed knowledge/<tag>/ left to diff against, KnowledgeRegenerationTests now fetches one release fresh and asserts two independent regenerations are byte-identical to each other (self-consistency, not a match against a human-reviewed baseline; a real reduction in rigor, named as such in its own doc comment); the metamodel-gen golden tests moved to the same committed-Expected/-fixture pattern MetaclassFileGoldenTests already used.
  • hypha move-window (refs #106) is now documented and commented as the maintainer-only, source-checkout-only convenience it always functionally was, not a way to move a committed rolling window: its --keep count only ever governed which releases stay installed locally.

Added

  • hypha use, hypha remove and hypha check (refs #106) replace hypha sync: switching the default release, removing one no longer wanted, and comparing installed releases against what is offerable upstream are now separate, always-safe-to-run verbs instead of one verb that silently fetched and generated the newest release automatically.
    • The version-management skill gives Claude the vocabulary to list local vs. online releases, fetch a chosen tag with visible progress, switch the default, or remove one, always confirming with the user first, since fetching costs real time and removing is destructive.
    • hypha fetch downloads the OMG specification PDFs by default now (--no-specs to opt out): a fully local install needs everything a plain HTTP call can get it.

Changed

  • The plugin's SessionStart hook only ever compares now; it never fetches or generates anything itself (refs #106). Hypha.Tools.Hook runs hypha check --json synchronously (a couple of GitHub API calls, cheap enough that no background process is needed) and reports what it finds: nothing installed yet, a newer release available, or nothing to report, leaving the decision to fetch entirely to the user. The same hook also folds in what hooks/check-spec-pdfs.py used to do separately (naming missing OMG PDFs for the default release), so the plugin needs one SessionStart hook instead of two, and no longer depends on Python being present just to run it.
  • The SessionStart hook now also runs on resume, not only startup (refs #117). A resumed session (claude --resume/--continue) used to skip the check entirely; plugin.json's matcher is now startup|resume, so a long-running or resumed session still gets a fresh comparison against what's offerable upstream.

Removed

  • hypha sync and the background/lock/status-file machinery it needed (refs #106). Detached launching, a file lock, and a polled status file existed only because a hook-triggered fetch had to return immediately and report progress later; once fetching is something the user asks for and Claude runs in the foreground, none of that indirection is needed. hooks/check-spec-pdfs.py is retired, folded into Hypha.Tools.Hook.

Added

  • hypha, a distributable command-line tool, is now what generates the knowledge base (fixes #81). It ships as a dotnet tool for anyone with the .NET 10 SDK and as a self-contained executable per platform (win-x64, linux-x64, osx-x64, osx-arm64) for anyone with no toolchain at all, which is the answer #77 needed to the question of what happens when the toolchains are absent. NativeAOT is deliberately out of scope: Handlebars.Net compiles templates at runtime through expression trees, and uml4net is reflection-heavy over XMI.
    • Four verbs: discover (what the upstreams offer), fetch (download a release into sources/ and record it), generate (the knowledge base) and list (what this checkout carries).
    • generate takes an optional artifact name, and the names are not a list it holds: they are the Artifact of whatever IKnowledgeGenerator implementations are registered, so adding a generator adds its verb and generate nonsense reports the ones that exist.
    • ReleaseInstaller gives fetching the orchestration generation already had: it downloads a release's inputs, resolves both upstream commits and merges the result into versions.json. The manifest is written only once the downloads finish, so an interrupted fetch leaves a release unrecorded rather than recorded and half-present.
    • A Release workflow packs the tool, publishes the four self-contained builds, generates THIRD-PARTY-NOTICES.txt for the bundled closure and drafts a tools-vX.Y.Z release. The tool and the plugin version independently.

Changed

  • The tests no longer write the knowledge base; they verify it (fixes #81). Running dotnet test used to rewrite knowledge/, which made every test run a write to the repository and made "is the working tree clean afterwards?" a check you had to remember to perform. Generation is hypha generate's job now, and a test run leaves the working tree clean.
    • KnowledgeRegenerationTests regenerates the whole knowledge base into a scratch folder and compares it byte for byte against the committed files: the same determinism proof, without touching a tracked file. All 1,090 files match.
    • The seam is HyphaKnowledgeOptions.OutputRoot (the CLI's --output): inputs are still read from the repository, only the output moves. knowledge/<tag>/spec/ stays on the input side, because the Python PDF chain writes it and the cross-references read it.
    • Hypha.Knowledge.Tests went from 30s to 3s, having stopped doing the generation work twice.
  • Generation orchestration moved out of the test fixtures and into the library (refs #92). Each artifact is now an IKnowledgeGenerator (Artifact, Order, GenerateAsync(tag)), registered as a collection, so regenerating a release is a loop over Order rather than a list of calls each caller had to keep in step. The knowledge base comes out byte-identical.
    • KnowledgeLayout replaced three separate copies of the repository layout that had grown up in the test projects, one per project plus a private one inside a fixture.
    • Two fixtures now write the committed knowledge base instead of seven; the rest assert on scratch output, so changing one of them can no longer rewrite what ships.
    • Three invariants moved from assertions in tests into the generators, where they hold for every caller: a clause title must never reach the cross-references, two models must never slugify to the same example page, and the textual notation refuses to run before the metamodel index exists.
    • HyphaKnowledgeOptions replaces the optional parameters that were accumulating on AddHyphaKnowledge (token, API host, raw-content host, repository root, download concurrency), and is validated at registration rather than at first use. It is where the CLI's flags will land.
    • Every generator takes an ILogger and reports the same three messages, so a host can show progress without knowing which generator it is watching. That is the seam #77 needs.
    • ReleaseDiscovery, CommitResolver and ReleaseFetcher are resolved by interface like everything else.

Fixed

  • The cross-references no longer degrade silently on a new release tag (fixes #96). The PDF-free rebuild added in #88 carries title-matched clause edges forward from the committed document, which is lossless, except for a tag that has neither a clause catalog nor a previous document, where it wrote a file with roughly a third of its clause edges missing and nothing failing. Build now refuses that combination and names both ways out; AllowGrammarOnly states that a grammar-only document is intended.

Changed

  • The cross-references moved to .NET, and no longer need the OMG PDFs (fixes #88). Hypha.Knowledge.CrossReferences writes knowledge/<tag>/cross-references.json byte-identically to the Python it replaces, and this completes the port (fixes #82): .NET now produces every committed artifact.
    • cross-references.json can be rebuilt from committed sources alone. 351 of its 546 clause edges are stated outright by the grammar's own // Clause comments in the committed .kebnf; the remaining title-matched ones are carried forward from the committed document, which already holds them. A contributor without the specifications regenerates the file and gets the same bytes back; previously they could not regenerate it at all.
    • The licensing guarantee is unchanged and still tested: edges record clause identifiers, never clause text, which is what lets this file be committed while knowledge/<tag>/spec/ cannot be.
    • tools/spec-extract is now the PDF chain and nothing else, and its README says so.
  • The textual-notation knowledge base moved to .NET (fixes #87). Hypha.Knowledge.TextualNotation now writes knowledge/<tag>/textual-notation/: 309 example pages per release plus the index. All 618 committed example pages come out byte-identical; the only change is the line naming the generator in index.md.
    • Surface forms are still derived from the metamodel's own naming convention rather than curated (PartDefinition → part def, PartUsage → part), and still bounded by that release's metamodel index, so the mapping cannot invent an element.
    • The declaration match still refuses to fire inside an identifier or a quoted name: counterpart is not a part. Unlike the grammar patterns this one is deliberately left Unicode-aware, matching the Python it replaces: model text is user-written.
    • Example pages are ordered segment by segment and case-insensitively, which is what the committed index was generated with; an ordinal sort of the whole path would interleave folders with files.
  • BNF parsing and the grammar references moved to .NET (fixes #86). Hypha.Knowledge.Grammar now parses both the textual .kebnf and the graphical .kgbnf and writes knowledge/<tag>/textual-notation/grammar-{kerml,sysml,graphical}.md. The generated files are byte-identical to what the Python emitted, apart from the line naming the generator.
    • The porting hazards are guarded by tests rather than left to be rediscovered: \d and \w are written out as explicit ASCII classes, because Python compiled these patterns with re.ASCII while .NET's shorthands are Unicode-aware; and the possessive quantifier on the clause number becomes an atomic group, which .NET does have.
    • The exclusivity guard is unchanged and still the point: a helper production shared by two elements contributes to neither. 96 of the 190 referenced helpers are shared, so relaxing it would report more feature assignments and mean less.
  • Release handling moved from Python to .NET (fixes #83, fixes #84, fixes #85), into the new tools/knowledge-gen/Hypha.Knowledge library. spec_extract.versions and spec_extract.fetch are gone; spec-extract now does what it is best at (PDF extraction) and nothing else.
    • ReleaseTag, ReleaseCatalog, GitHubToken and ReleaseDiscovery offer the same 56 releases in the same order as the Python they replace; VersionManifest rewrites the committed knowledge/versions.json byte for byte.
    • ReleaseInputs decides what a release consists of as a pure function of a repository listing, so the selection rules are testable without the network; ReleaseFetcher downloads it.
    • Fetching is concurrent (6 at a time) over a pooled HttpClient. The Python fetcher opened a connection per file and was reset by the host after roughly 190 of a release's 314 files; a release now fetches whole in about 15 seconds.
  • Well-established NuGet packages are now welcome rather than avoided, and services are composed through Microsoft.Extensions.DependencyInjection. AddHyphaKnowledge() registers one resilient named client (Microsoft.Extensions.Http.Resilience, so retries are jittered, which matters once downloads run concurrently) and the services that share it. This is groundwork for the CLI (#81).

Added

  • Version awareness (fixes #67, fixes #74). The knowledge base is now generated per upstream release tag (YYYY-MM) instead of from a single snapshot, with a committed rolling window of the two most recent releases, currently 2026-05 (the default) and 2026-04.
    • knowledge/versions.json records the installed tags, the default, and the upstream commit each tag resolved to (traceability only; the tag is the identifier).
    • Release discovery offers a version only when the tag resolves in both upstreams: they are not in lockstep (2023-07.1 is Release-only; 2024-08, 2023-01, 2026-05-pre are Pilot-only). Tags are YYYY-MM with an optional point release; pre-releases, internal drops and letter revisions are excluded. 56 releases are currently offerable.
    • Fetching pulls a release's inputs from both upstreams, retrying transient connection resets with backoff and resuming a partial run.
    • Skills and subagents resolve the release from the manifest, answer from the default unless a tag is named, and state which release an answer came from.
    • hooks/check-spec-pdfs.py checks the default release and gives tagged download URLs.

Fixed

  • The previous inputs were not a coherent version: the PDFs resolved to Release tag 2026-03, the textual sources to 2026-04, and the metamodel XMI to an untagged master commit. Each release now comes from a single upstream point.
  • XmiModelReaderTests was silently skipping on a stale sources/xmi path; it runs again.
  • .gitignore gained a global *.pdf backstop. Moving the specs rule to the per-tag form stopped it matching a stale copy of the old layout, and three copyrighted OMG PDFs were very nearly committed.

Changed

  • sources/ and knowledge/ are laid out per tag: sources/<tag>/{xmi,textual,specs} and knowledge/<tag>/{metamodel,spec,cross-references.json}. knowledge/textual-notation/ stays shared (hand-curated), and sources/PrimitiveTypes.xmi is shared: it is the OMG UML primitives library, published by neither upstream and identical for every release.
  • The model URI inside the XMI (…/SysML/20250201) is no longer used anywhere as a version identifier. It tracks neither release nor content: the 2026-05 metamodel still declares a 2025 URI. The same model may appear under several tags, which is accepted rather than deduplicated.

Added

  • knowledge/cross-references.json (+ schema): edges from every metamodel element to the specification clauses that treat it, its BNF grammar production and any worked example. It records clause identifiers only, never clause text, so it ships even though knowledge/spec/ cannot; 185 of 187 elements resolve to at least one clause. Generated by the new spec_extract.crossrefs layer (fixes #68).
  • Provenance tiers (NORMATIVE / MODEL / DERIVED) documented in the skills and the README, and carried in the data itself via the provenanceTiers block, so every cross-reference edge says how it was obtained.
  • knowledge/metamodel/diagrams/<Package>.md: a Mermaid class diagram per package (41 files), generated from the XMI by the new PackageDiagramGenerator and linked from each package section of knowledge/metamodel/index.md. Each diagram carries the package's metaclasses (abstract ones marked), their generalizations, one-hop boundary nodes for supertypes owned elsewhere, and the structural owned features (fixes #69).
  • Two rules keep those diagrams legible: derived features are omitted (computed views rather than structure, and they outnumber the structural features roughly three to one), and only metaclass-typed features become edges; primitive- and enumeration-typed ones are drawn inside the class box, so String and Boolean never become hub nodes.

Fixed

  • Packages that share a name across the two metamodels (KerML::Kernel::Metadata and SysML::Systems::Metadata) are merged into one diagram. Treating them separately wrote two files to the same path, silently discarding one of them.

Changed

  • metamodel-lookup and the metamodel-navigator subagent now query knowledge/metamodel/metamodel.json for set, closure and fan-out questions instead of grepping the per-element markdown, which stays the citable surface for single-element answers. Matching a JSON field is also exact, where grepping markdown matches documentation prose too.
  • spec-citation degrades gracefully: without the OMG PDFs it now names the governing clause from the cross-references instead of refusing to answer, and says the reference is DERIVED.
  • sysml-validation grounds its reachability and multiplicity-bound checks in metamodel.json (inheritedAttributes / inheritedFrom, and the typed lower/upper integers) rather than reasoning from prose; the bad-multiplicity and redefines-nonexistent fixtures record how each is decided.
  • jq is now described as recommended rather than merely an accelerator, and the recommendation moved into the plugin-facing README; the previous note lived in tools/metamodel-gen/README.md, which is not shipped with the plugin.

[1.1.0] - 2026-07-01

Changed

  • Bumped uml4net (uml4net.xmi, uml4net.Extensions, uml4net.Reporting) 8.1.2 → 8.2.1, which reads the previously-missing subsetting information from the XMI. Regenerated the metamodel knowledge base accordingly (knowledge/metamodel/): several element files and metamodel.json now carry the complete Subsets sets (fixes #62).
  • Interesting-metaclass selection (used for the generator golden fixtures) now folds in operation argument/return-type variations, broadening test coverage (fixes #63).

[1.0.0] - 2026-06-29

Added

  • Initial Claude plugin scaffolding (.claude-plugin/plugin.json, marketplace manifest).
  • Skills: metamodel-lookup, spec-citation, sysml-validation.
  • Subagents: metamodel-navigator, spec-citation, sysml-validator.
  • Knowledge-base layout (knowledge/) for KerML/SysML v2 metamodel elements, normative spec excerpts, and textual-notation examples.
  • Source-document layout (sources/) for OMG XMI and PDF specifications.
  • Generation pipelines layout (tools/): C#/uml4net metamodel generator and Python PDF spec extractor.

Changed

  • Renamed the metamodel knowledge folder knowledge/sysml2/ → knowledge/metamodel/ (consistent content-type naming alongside spec/ and textual-notation/, and no longer overloaded with the knowledge/spec/sysml2/ clause folder).