Refactor packaging to support independent Language and Stdlib NuGet packages

.cspell.yaml

@@ -191,6 +191,7 @@ ignorePaths:
   - "**/third-party/**"
   - "**/3rd-party/**"
   - "**/generated/**"
+  - "**/api/**"  # ApiMark-generated Markdown API reference docs
   - "**/Parser/Antlr/**"
   - "**/Stdlib/**"
   - "**/AGENT_REPORT_*.md"

.github/workflows/build.yaml

@@ -207,6 +207,7 @@ jobs:
           --no-restore
           --configuration Release
           --property:PackageVersion=${{ inputs.version }}
+          --output ./artifacts/packages
 
       # === UPLOAD ARTIFACTS ===
       # This section uploads all generated artifacts for use by downstream jobs.
@@ -223,8 +224,8 @@ jobs:
         with:
           name: packages-${{ matrix.os }}
           path: |
-            src/DemaConsulting.SysML2Tools.Tool/bin/Release/*.nupkg
-            src/DemaConsulting.SysML2Tools.Tool/bin/Release/*.snupkg
+            artifacts/packages/*.nupkg
+            artifacts/packages/*.snupkg
 
   # Runs CodeQL security and quality analysis, gathering results to include
   # in the code quality report.
@@ -348,7 +349,7 @@ jobs:
           dotnet tool install --global \
             --add-source packages \
             --version ${{ inputs.version }} \
-            DemaConsulting.SysML2Tools
+            DemaConsulting.SysML2Tools.Tool
 
       # === CAPTURE TOOL VERSIONS ===
       # This section captures the versions of all tools used in the integration tests.

.gitignore

@@ -91,6 +91,9 @@ __pycache__/
 **/generated/
 *.pdf
 
+# ApiMark-generated Markdown API reference documentation (regenerated on every build)
+**/api/
+
 # Test results
 TestResults/
 *.trx

.markdownlint-cli2.yaml

@@ -51,6 +51,7 @@ ignores:
   - "**/third-party/**"
   - "**/3rd-party/**"
   - "**/generated/**"
+  - "**/api/**"  # ApiMark-generated Markdown API reference docs
   - "**/AGENT_REPORT_*.md"
   - "**/.agent-logs/**"
   - "ROADMAP.md"

.reviewmark.yaml

@@ -146,22 +146,25 @@ reviews:
       - docs/design/sysml2-tools-language.md
     paths:
       - "src/DemaConsulting.SysML2Tools.Language/Parser/WorkspaceParser.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Parser/Internal/SysmlDiagnosticListener.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstBuilder.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SymbolTable.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/ReferenceResolver.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SupertypeWalker.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SerializedStdlib.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstSerializerContext.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlEdge.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SemanticIndex.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlAnnotation.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SymbolTable.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SupertypeWalker.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SerializedStdlib.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstSerializerContext.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlEdge.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SemanticIndex.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlAnnotation.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Parser/WorkspaceParserTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Parser/OmgModelsTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs"
@@ -216,6 +219,7 @@ reviews:
       - docs/design/sysml2-tools-stdlib.md
     paths:
       - "src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs"
+      - "src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs"
       - "src/Tools/StdlibGen/Program.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/StdlibProviderTests.cs"
 
@@ -229,6 +233,7 @@ reviews:
       - "docs/design/sysml2-tools-stdlib/stdlib-provider.md"
       - "docs/verification/sysml2-tools-stdlib/stdlib-provider.md"
       - "src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs"
+      - "src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/StdlibProviderTests.cs"
 
   # SysML2Tools Core Library
@@ -352,13 +357,15 @@ reviews:
       - docs/design/sysml2-tools-language.md
     paths:
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstBuilder.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SymbolTable.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/ReferenceResolver.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SupertypeWalker.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SymbolTable.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SupertypeWalker.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/SemanticOmgModelsTests.cs"
 
@@ -386,6 +393,7 @@ reviews:
       - "docs/design/sysml2-tools-language/parser/workspace-parser.md"
       - "docs/verification/sysml2-tools-language/parser/workspace-parser.md"
       - "src/DemaConsulting.SysML2Tools.Language/Parser/WorkspaceParser.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Parser/WorkspaceParserTests.cs"
 
   - id: SysML2Tools-Language-Parser-Internal-SysmlDiagnosticListener
@@ -414,8 +422,8 @@ reviews:
       - "docs/design/sysml2-tools-language/semantic/ast-serializer.md"
       - "docs/verification/sysml2-tools-language/semantic/ast-serializer.md"
       - "src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SerializedStdlib.cs"
-      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstSerializerContext.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SerializedStdlib.cs"
+      - "src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstSerializerContext.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs"
 
   - id: SysML2Tools-Language-Semantic-AstDeserializer
@@ -629,6 +637,7 @@ reviews:
       - docs/design/sysml2-tools-core/rendering.md
     paths:
       - "src/DemaConsulting.SysML2Tools.Core/Rendering/ILayoutStrategy.cs"
+      - "src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs"
       - "src/DemaConsulting.SysML2Tools.Core/Rendering/Internal/StdlibFilter.cs"
       - "test/DemaConsulting.SysML2Tools.Tests/Rendering/RenderingTests.cs"
 

README.md

@@ -52,7 +52,7 @@ documentation, CI/CD pipelines, and AI-assisted modeling workflows.
 Install the tool globally using the .NET CLI:
 
 ```bash
-dotnet tool install -g DemaConsulting.SysML2Tools
+dotnet tool install -g DemaConsulting.SysML2Tools.Tool
 ```
 
 ## Usage
@@ -226,12 +226,15 @@ sysml2tools help [lint|render|query [<query-verb>]]
 
 | Package | Description |
 | --- | --- |
-| `DemaConsulting.SysML2Tools` | Core library: parser, semantic model, layout, `IRenderer` interface |
-| `DemaConsulting.SysML2Tools.Svg` | SVG renderer — zero external dependencies |
-| `DemaConsulting.SysML2Tools.Png` | PNG renderer — SkiaSharp (MIT), embedded Noto Sans font |
+| `DemaConsulting.SysML2Tools.Language` | Library: SysML v2/KerML parser, AST, semantic model |
+| `DemaConsulting.SysML2Tools.Stdlib` | Library: pre-compiled SysML v2 standard library |
+| `DemaConsulting.SysML2Tools.Core` | Library: parser, semantic model, layout, `IRenderer` interface |
+| `DemaConsulting.SysML2Tools.Tool` | CLI tool: `lint`, `render`, and `query` commands |
 
-Library consumers can take a dependency on `DemaConsulting.SysML2Tools` alone to access
-parsing, semantic model, and layout without pulling in any native graphics binaries.
+Library consumers can take a dependency on `DemaConsulting.SysML2Tools.Core` alone to access
+parsing, semantic model, and layout without pulling in the CLI tool; `Core` automatically pulls
+in `Language` and `Stdlib` as NuGet dependencies. Each package ships its own generated Markdown
+API reference documentation alongside its assembly.
 
 ## Contributing
 
@@ -252,7 +255,7 @@ By contributing to this project, you agree that your contributions will be licen
 [badge-build]: https://img.shields.io/github/actions/workflow/status/demaconsulting/SysML2Tools/build_on_push.yaml?style=plastic
 [badge-quality]: https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_SysML2Tools&metric=alert_status
 [badge-security]: https://sonarcloud.io/api/project_badges/measure?project=demaconsulting_SysML2Tools&metric=security_rating
-[badge-nuget]: https://img.shields.io/nuget/v/DemaConsulting.SysML2Tools?style=plastic
+[badge-nuget]: https://img.shields.io/nuget/v/DemaConsulting.SysML2Tools.Tool?style=plastic
 
 <!-- Link References -->
 [link-forks]: https://github.com/demaconsulting/SysML2Tools/network/members
@@ -262,4 +265,4 @@ By contributing to this project, you agree that your contributions will be licen
 [link-build]: https://github.com/demaconsulting/SysML2Tools/actions/workflows/build_on_push.yaml
 [link-quality]: https://sonarcloud.io/dashboard?id=demaconsulting_SysML2Tools
 [link-security]: https://sonarcloud.io/dashboard?id=demaconsulting_SysML2Tools
-[link-nuget]: https://www.nuget.org/packages/DemaConsulting.SysML2Tools
+[link-nuget]: https://www.nuget.org/packages/DemaConsulting.SysML2Tools.Tool

docs/design/definition.yaml

@@ -5,7 +5,7 @@ resource-path:
   - docs/design/sysml2-tools-language/parser
   - docs/design/sysml2-tools-language/parser/internal
   - docs/design/sysml2-tools-language/semantic
-  - docs/design/sysml2-tools-language/semantic/internal
+  - docs/design/sysml2-tools-language/semantic/model
   - docs/design/sysml2-tools-core
   - docs/design/sysml2-tools-core/layout
   - docs/design/sysml2-tools-core/layout/internal
@@ -31,12 +31,15 @@ input-files:
   - docs/design/sysml2-tools-language/semantic/workspace-loader.md
   - docs/design/sysml2-tools-language/semantic/ast-serializer.md
   - docs/design/sysml2-tools-language/semantic/ast-deserializer.md
-  - docs/design/sysml2-tools-language/semantic/internal.md
-  - docs/design/sysml2-tools-language/semantic/internal/sysml-node.md
-  - docs/design/sysml2-tools-language/semantic/internal/ast-builder.md
-  - docs/design/sysml2-tools-language/semantic/internal/symbol-table.md
-  - docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md
-  - docs/design/sysml2-tools-language/semantic/internal/supertype-walker.md
+  - docs/design/sysml2-tools-language/semantic/model.md
+  - docs/design/sysml2-tools-language/semantic/model/sysml-node.md
+  - docs/design/sysml2-tools-language/semantic/model/sysml-edge.md
+  - docs/design/sysml2-tools-language/semantic/model/sysml-annotation.md
+  - docs/design/sysml2-tools-language/semantic/model/semantic-index.md
+  - docs/design/sysml2-tools-language/semantic/model/symbol-table.md
+  - docs/design/sysml2-tools-language/semantic/model/ast-builder.md
+  - docs/design/sysml2-tools-language/semantic/model/reference-resolver.md
+  - docs/design/sysml2-tools-language/semantic/model/supertype-walker.md
   - docs/design/sysml2-tools-stdlib.md
   - docs/design/sysml2-tools-stdlib/stdlib-provider.md
   - docs/design/sysml2-tools-core.md

docs/design/introduction.md

@@ -46,7 +46,7 @@ system, subsystem, and unit levels:
     - **WorkspaceLoader** (Unit) — public API: loads SysML/KerML files into a semantic workspace with optional seed
     - **AstSerializer** (Unit) — serializes SymbolTable + diagnostics to UTF-8 JSON bytes
     - **AstDeserializer** (Unit) — deserializes bytes back to SymbolTable + diagnostics
-    - **Internal** (Subsystem) — internal semantic implementation
+    - **Model** (Subsystem) — semantic model: public model types plus internal build/resolve implementation
       - **SysmlNode** (Unit) — public AST node hierarchy: nine types with JSON polymorphism
       - **AstBuilder** (Unit) — builds AST from ANTLR4 CST with qualified names and supertype lists
       - **SymbolTable** (Unit) — registry mapping qualified names to declaration nodes
@@ -67,7 +67,7 @@ system, subsystem, and unit levels:
 - **StdlibGen** (Build-time tool) — console tool that parses stdlib source files and writes stdlib.bin
   (build-time tooling; excluded from the software-items requirements/design/verification tree — see _Scope_)
   - **Program** (Unit) — entry point: parses stdlib, runs resolution, serializes to stdlib.bin
-- **DemaConsulting.SysML2Tools** (System) — core library: layout strategies, rendering
+- **DemaConsulting.SysML2Tools.Core** (System) — core library: layout strategies, rendering
   orchestration, and the SysML-coupled rendering pipeline
   - **Layout** (Subsystem) — maps the SysML semantic model onto the off-the-shelf `LayoutTree`
     intermediate representation and delegates geometric placement and routing to the off-the-shelf
@@ -144,7 +144,7 @@ reviewers an explicit navigation aid from design to code:
       - **Antlr/** — ANTLR4-generated C# (committed; not hand-written)
       - **Internal/** — internal implementation (SysmlDiagnosticListener)
     - **Semantic/** — semantic model subsystem
-      - **Internal/** — internal implementation (SysmlNode, AstBuilder, SymbolTable,
+      - **Model/** — public semantic model types (SysmlNode, AstBuilder, SymbolTable,
         ReferenceResolver, SupertypeWalker, SysmlEdge, SemanticIndex, SysmlAnnotation,
         SerializedStdlib, AstSerializerContext)
   - **DemaConsulting.SysML2Tools.Stdlib/** — stdlib library
@@ -198,7 +198,7 @@ The four top-level systems map to these kebab-case folder names:
 | --- | --- |
 | `DemaConsulting.SysML2Tools.Language` | `sysml2-tools-language` |
 | `DemaConsulting.SysML2Tools.Stdlib` | `sysml2-tools-stdlib` |
-| `DemaConsulting.SysML2Tools` | `sysml2-tools-core` |
+| `DemaConsulting.SysML2Tools.Core` | `sysml2-tools-core` |
 | `DemaConsulting.SysML2Tools.Tool` | `sysml2-tools-tool` |
 
 OTS items have integration/usage design documentation parallel to system folders:

docs/design/sysml2-tools-core.md

@@ -79,6 +79,16 @@ flowchart TD
 - **DemaConsulting.SysML2Tools.Stdlib** — provides `StdlibProvider.GetSymbolTable()` used
   by `DiagramRenderer` to seed the semantic workspace with the pre-compiled standard library.
 
+## Packaging
+
+The `DemaConsulting.SysML2Tools.Core` NuGet package is built with `GenerateDocumentationFile`
+and `DemaConsulting.ApiMark.MSBuild` (`ApiMarkPackDocs=true`), so an `api/` folder of
+ApiMark-generated API reference documentation for this library's own public types is bundled
+into the package at pack time. `Language` and `Stdlib` are independent, separately packable
+NuGet packages that bundle their own API reference documentation the same way; Core references
+them via normal `<ProjectReference>`s that `dotnet pack` resolves to ordinary NuGet
+`<dependency>` entries (not embedded assemblies).
+
 ## Risk Control Measures
 
 N/A — not a safety-classified software item.

docs/design/sysml2-tools-language.md

@@ -11,9 +11,10 @@ The library contains two subsystems: **Parser** and **Semantic**. The Parser sub
 provides syntax-level parsing, while the Semantic subsystem builds a symbol table and performs
 reference resolution. The Parser subsystem contains the public API unit (`WorkspaceParser`)
 and an internal unit (`SysmlDiagnosticListener`). The Semantic subsystem contains the public
-`WorkspaceLoader` unit, serialization units (`AstSerializer`, `AstDeserializer`), and an
-internal subsystem with `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
-`SysmlNode`, `SerializedStdlib`, and `AstSerializerContext`.
+`WorkspaceLoader` unit, serialization units (`AstSerializer`, `AstDeserializer`), and the
+**Model** subsystem — a public API surface (not internal) with `AstBuilder`, `SymbolTable`,
+`ReferenceResolver`, `SupertypeWalker`, `SysmlNode` (and its subtypes), `SysmlEdge`,
+`SysmlAnnotation`, `SemanticIndex`, `SerializedStdlib`, and `AstSerializerContext`.
 Supporting data types (`SysmlLoadResult`, `SysmlWorkspace`) are declared at the `Semantic`
 namespace level. `DiagnosticSeverity`, `SysmlDiagnostic`, and `WorkspaceParseResult` remain
 in the `Parser` namespace.
@@ -33,6 +34,9 @@ flowchart TD
         ReferenceResolver
         SupertypeWalker
         SysmlNode
+        SysmlEdge
+        SysmlAnnotation
+        SemanticIndex
         SerializedStdlib
         AstSerializerContext
     end
@@ -101,8 +105,9 @@ and diagnostics.
 
 - *Type*: Public abstract class with JSON polymorphism attributes.
 - *Role*: Data model.
-- *Contract*: Six concrete subtypes: `SysmlPackageNode`, `SysmlDefinitionNode`, `SysmlFeatureNode`,
-  `SysmlImportNode`, `SysmlViewNode`, `SysmlViewpointNode`. All are public and JSON-serializable.
+- *Contract*: Nine concrete subtypes: `SysmlPackageNode`, `SysmlDefinitionNode`, `SysmlFeatureNode`,
+  `SysmlImportNode`, `SysmlViewNode`, `SysmlViewpointNode`, `SysmlConnectionNode`,
+  `SysmlTransitionNode`, `SysmlSatisfyNode`. All are public and JSON-serializable.
 
 **SysmlLoadResult**: Aggregate result record returned by `WorkspaceLoader.LoadAsync`.
 

docs/design/sysml2-tools-language/semantic.md

@@ -8,15 +8,15 @@ operates as a second layer above the Parser subsystem, consuming ANTLR4 CSTs pro
 
 ### Interfaces
 
-The Semantic subsystem contains one public unit (`WorkspaceLoader`) and an internal subsystem
-(`Internal`) containing `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
+The Semantic subsystem contains one public unit (`WorkspaceLoader`) and a Model subsystem
+(`Model`) containing `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
 `SysmlEdge`, `SemanticIndex`, and `SysmlAnnotation`.
 
 ```mermaid
 flowchart TD
     subgraph Semantic
         WorkspaceLoader
-        subgraph Internal
+        subgraph Model
             AstBuilder
             SymbolTable
             ReferenceResolver
@@ -58,7 +58,7 @@ optionally seeded with a pre-populated symbol table.
 - *Contract*: Exposes `IReadOnlyList<string> Files`, `IReadOnlySet<string> StdlibNames`,
   `IReadOnlyDictionary<string, SysmlNode> Declarations` mapping qualified names to declaration
   nodes, and `SemanticIndex Index` — a reverse-lookup index over resolved supertype, typing,
-  and import edges (see Semantic Internal Subsystem).
+  and import edges (see Semantic Model Subsystem).
 
 ### Design