From d83030afee958d52528223f3d050d7063f823114 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Fri, 3 Jul 2026 13:58:02 -0400
Subject: [PATCH 01/13] Package Core library as
 DemaConsulting.SysML2Tools.Core, rename Tool package to
 DemaConsulting.SysML2Tools.Tool

- Core.csproj: IsPackable=true, add packaging metadata (readme, icon, tags,
  NoWarn NU5104 for the pre-release Rendering.Layout dependency), and embed
  the internal (unpublished) Language/Stdlib assemblies directly into the
  package via CopyProjectReferencesToPackage instead of listing them as
  bogus NuGet dependencies.
- Tool.csproj: PackageId renamed from DemaConsulting.SysML2Tools to
  DemaConsulting.SysML2Tools.Tool (ToolCommandName/AssemblyName unchanged).
- build.yaml: dotnet pack now writes to a shared ./artifacts/packages
  folder; Upload packages step and integration-test's dotnet tool install
  updated accordingly.
- README.md, docs/design/introduction.md, docs/user_guide/introduction.md:
  updated NuGet package tables, install instructions, and badge/link URLs
  to reflect the two real packages (Core, Tool) instead of stale
  bare-named/Svg/Png references.
---
 .github/workflows/build.yaml                  |  7 ++--
 README.md                                     | 15 ++++-----
 docs/design/introduction.md                   |  2 +-
 docs/user_guide/introduction.md               | 20 ++++++------
 .../DemaConsulting.SysML2Tools.Core.csproj    | 32 +++++++++++++++++--
 .../DemaConsulting.SysML2Tools.Tool.csproj    |  2 +-
 6 files changed, 51 insertions(+), 27 deletions(-)

diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml
index ab8e699d..3d7c434e 100644
--- a/.github/workflows/build.yaml
+++ b/.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.
diff --git a/README.md b/README.md
index 79175912..86491bbe 100644
--- a/README.md
+++ b/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,11 @@ 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.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.
 
 ## Contributing
 
@@ -252,7 +251,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 +261,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
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
index 45597bb2..b19aa0b4 100644
--- a/docs/design/introduction.md
+++ b/docs/design/introduction.md
@@ -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:
diff --git a/docs/user_guide/introduction.md b/docs/user_guide/introduction.md
index e0b7fa74..98f6841c 100644
--- a/docs/user_guide/introduction.md
+++ b/docs/user_guide/introduction.md
@@ -36,7 +36,7 @@ This user guide covers:
 Install the tool globally using the .NET CLI:
 
 ```bash
-dotnet tool install -g DemaConsulting.SysML2Tools
+dotnet tool install -g DemaConsulting.SysML2Tools.Tool
 ```
 
 # Workspaces
@@ -263,19 +263,17 @@ sysml2tools --validate --depth 2
 
 # NuGet Library Packages
 
-SysML2Tools is structured as four NuGet packages. Library consumers can take individual
-packages without pulling in the full CLI tool or native graphics binaries:
+SysML2Tools is structured as two NuGet packages. Library consumers can take a dependency
+on the core library alone, without pulling in the full CLI tool:
 
 | Package | Contents |
 | --- | --- |
-| `DemaConsulting.SysML2Tools` | Core library: parser, semantic model, layout, `IRenderer` interface |
-| `DemaConsulting.SysML2Tools.Svg` | SVG renderer — zero external dependencies |
-| `DemaConsulting.SysML2Tools.Png` | PNG renderer — requires SkiaSharp native assets at publish time |
-| `DemaConsulting.SysML2Tools.Tool` | dotnet tool — references all three packages |
-
-Consumers who need only the parsed semantic model or `LayoutTree` take a dependency on
-`DemaConsulting.SysML2Tools` only. Consumers who need SVG or PNG output opt in to the
-respective renderer package explicitly.
+| `DemaConsulting.SysML2Tools.Core` | Library: parser, semantic model, layout, `IRenderer` interface |
+| `DemaConsulting.SysML2Tools.Tool` | CLI tool: `lint`, `render`, `query`, and `help` commands |
+
+Consumers who need only the parsed semantic model, `LayoutTree`, or rendering interfaces
+take a dependency on `DemaConsulting.SysML2Tools.Core` only. Consumers who need the CLI
+install `DemaConsulting.SysML2Tools.Tool` as a dotnet tool.
 
 # Continuous Compliance
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index c67689bf..02c9456b 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -6,7 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 
-    <IsPackable>false</IsPackable>
+    <IsPackable>true</IsPackable>
     <PackageId>DemaConsulting.SysML2Tools.Core</PackageId>
     <AssemblyName>DemaConsulting.SysML2Tools.Core</AssemblyName>
     <Version>0.0.0</Version>
@@ -16,6 +16,9 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/demaconsulting/SysML2Tools</PackageProjectUrl>
     <RepositoryUrl>https://github.com/demaconsulting/SysML2Tools</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>Icon.png</PackageIcon>
+    <PackageTags>sysml2;sysml;mbse;parser</PackageTags>
     <Copyright>Copyright DEMA Consulting</Copyright>
     <Title>SysML2 Tools</Title>
     <Product>DemaConsulting.SysML2Tools</Product>
@@ -33,6 +36,9 @@
     <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
+    <!-- Suppress NU5104: this library intentionally depends on the pre-release
+         DemaConsulting.Rendering.Layout package until it reaches a stable release. -->
+    <NoWarn>$(NoWarn);NU5104</NoWarn>
 
     <!-- SBOM Configuration -->
     <GenerateSBOM>true</GenerateSBOM>
@@ -47,15 +53,35 @@
     <PackageReference Include="DemaConsulting.Rendering.Layout" Version="0.1.0-beta.2" />
   </ItemGroup>
 
+  <!-- Language and Stdlib are internal (IsPackable=false) projects, so their PrivateAssets="all"
+       marking here prevents them from being emitted as NuGet package dependencies. Instead, the
+       CopyProjectReferencesToPackage target below embeds their compiled assemblies directly into
+       this package's lib folder (see docs/design/introduction.md for details). -->
   <ItemGroup>
-    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Language\DemaConsulting.SysML2Tools.Language.csproj" />
-    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Stdlib\DemaConsulting.SysML2Tools.Stdlib.csproj" />
+    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Language\DemaConsulting.SysML2Tools.Language.csproj" PrivateAssets="all" />
+    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Stdlib\DemaConsulting.SysML2Tools.Stdlib.csproj" PrivateAssets="all" />
   </ItemGroup>
 
+  <!-- Embed the Language and Stdlib assemblies (both IsPackable=false) directly into this
+       package's lib folder, since they cannot be resolved as separate NuGet dependencies. -->
+  <PropertyGroup>
+    <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);CopyProjectReferencesToPackage</TargetsForTfmSpecificBuildOutput>
+  </PropertyGroup>
+  <Target Name="CopyProjectReferencesToPackage" DependsOnTargets="ResolveReferences">
+    <ItemGroup>
+      <BuildOutputInPackage Include="@(ReferencePath)" Condition="'%(ReferencePath.ReferenceSourceTarget)' == 'ProjectReference'" />
+    </ItemGroup>
+  </Target>
+
   <ItemGroup>
     <InternalsVisibleTo Include="DemaConsulting.SysML2Tools.Tests" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="..\..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\..\Icon.png" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
   <!-- Code Analysis Dependencies -->
   <ItemGroup>
     <!-- Analyzer packages use child-element form to configure both PrivateAssets and IncludeAssets:
diff --git a/src/DemaConsulting.SysML2Tools.Tool/DemaConsulting.SysML2Tools.Tool.csproj b/src/DemaConsulting.SysML2Tools.Tool/DemaConsulting.SysML2Tools.Tool.csproj
index 0c322057..b2b1f25f 100644
--- a/src/DemaConsulting.SysML2Tools.Tool/DemaConsulting.SysML2Tools.Tool.csproj
+++ b/src/DemaConsulting.SysML2Tools.Tool/DemaConsulting.SysML2Tools.Tool.csproj
@@ -11,7 +11,7 @@
     <PackAsTool>true</PackAsTool>
     <ToolCommandName>sysml2tools</ToolCommandName>
     <AssemblyName>DemaConsulting.SysML2Tools</AssemblyName>
-    <PackageId>DemaConsulting.SysML2Tools</PackageId>
+    <PackageId>DemaConsulting.SysML2Tools.Tool</PackageId>
     <Version>0.0.0</Version>
     <Authors>DEMA Consulting</Authors>
     <Company>DEMA Consulting</Company>

From a9cc5369c7b77dd8719590c3eaf26f44dc3e1d80 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Fri, 3 Jul 2026 15:13:59 -0400
Subject: [PATCH 02/13] Wire ApiMark MSBuild integration into Core package for
 generated API docs

Add DemaConsulting.ApiMark.MSBuild 0.4.9 PackageReference and
ApiMarkPackDocs=true to DemaConsulting.SysML2Tools.Core.csproj so the
packable Core NuGet package ships generated Markdown API reference
documentation (from existing XML doc comments) alongside the assembly.

- Verified end-to-end: dotnet build generates src/.../Core/api/ on disk;
  dotnet pack + nupkg inspection confirms the api/ folder is included
  inside the .nupkg (PackagePath api/**).
- Add **/api/** ignore entries to .gitignore, .markdownlint-cli2.yaml,
  and .cspell.yaml so the regenerated-on-every-build ApiMark output is
  never committed or linted, following the existing **/generated/**
  convention.
- Add one-sentence mentions of the bundled generated API docs to
  README.md and docs/user_guide/introduction.md.
- Language.csproj/Stdlib.csproj intentionally untouched: Core's public
  API surface exposes no Language/Stdlib types, so ApiMark on Core alone
  is sufficient for baseline generation.

build.ps1: 100% green, same test counts as d83030a (275 + 166 tests).
fix.ps1 / lint.ps1: clean, no errors or warnings.
---
 .cspell.yaml                                                | 1 +
 .gitignore                                                  | 3 +++
 .markdownlint-cli2.yaml                                     | 1 +
 README.md                                                   | 3 ++-
 docs/user_guide/introduction.md                             | 3 ++-
 .../DemaConsulting.SysML2Tools.Core.csproj                  | 6 ++++++
 6 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/.cspell.yaml b/.cspell.yaml
index 6db788ea..ac88fcf0 100644
--- a/.cspell.yaml
+++ b/.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"
diff --git a/.gitignore b/.gitignore
index 05fd2949..20dd6627 100644
--- a/.gitignore
+++ b/.gitignore
@@ -91,6 +91,9 @@ __pycache__/
 **/generated/
 *.pdf
 
+# ApiMark-generated Markdown API reference documentation (regenerated on every build)
+**/api/
+
 # Test results
 TestResults/
 *.trx
diff --git a/.markdownlint-cli2.yaml b/.markdownlint-cli2.yaml
index 41435b54..8f8b86ce 100644
--- a/.markdownlint-cli2.yaml
+++ b/.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"
diff --git a/README.md b/README.md
index 86491bbe..9fcefa04 100644
--- a/README.md
+++ b/README.md
@@ -230,7 +230,8 @@ sysml2tools help [lint|render|query [<query-verb>]]
 | `DemaConsulting.SysML2Tools.Tool` | CLI tool: `lint`, `render`, and `query` commands |
 
 Library consumers can take a dependency on `DemaConsulting.SysML2Tools.Core` alone to access
-parsing, semantic model, and layout without pulling in the CLI tool.
+parsing, semantic model, and layout without pulling in the CLI tool. The `Core` package also
+bundles generated Markdown API reference documentation alongside the assembly.
 
 ## Contributing
 
diff --git a/docs/user_guide/introduction.md b/docs/user_guide/introduction.md
index 98f6841c..23178457 100644
--- a/docs/user_guide/introduction.md
+++ b/docs/user_guide/introduction.md
@@ -273,7 +273,8 @@ on the core library alone, without pulling in the full CLI tool:
 
 Consumers who need only the parsed semantic model, `LayoutTree`, or rendering interfaces
 take a dependency on `DemaConsulting.SysML2Tools.Core` only. Consumers who need the CLI
-install `DemaConsulting.SysML2Tools.Tool` as a dotnet tool.
+install `DemaConsulting.SysML2Tools.Tool` as a dotnet tool. The `DemaConsulting.SysML2Tools.Core`
+package also bundles generated Markdown API reference documentation alongside the assembly.
 
 # Continuous Compliance
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index 02c9456b..c67c5bd2 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -45,11 +45,17 @@
     <SBOMPackageName>$(Product)</SBOMPackageName>
     <SBOMPackageVersion>$(Version)</SBOMPackageVersion>
     <SBOMPackageSupplier>Organization: $(Company)</SBOMPackageSupplier>
+
+    <!-- ApiMark Configuration: generate Markdown API reference docs from the XML doc
+         comments (see GenerateDocumentationFile above) and bundle them into the NuGet
+         package alongside the assembly. -->
+    <ApiMarkPackDocs>true</ApiMarkPackDocs>
   </PropertyGroup>
 
   <ItemGroup>
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
     <PackageReference Include="DemaConsulting.Rendering.Layout" Version="0.1.0-beta.2" />
   </ItemGroup>
 

From 6f9d45682f7515ba6c3e42c0c81ef7b873d5e8b6 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Fri, 3 Jul 2026 16:16:30 -0400
Subject: [PATCH 03/13] Add namespace-level ApiMark docs and wire
 Language/Stdlib into Core's API reference

Wires DemaConsulting.ApiMark.MSBuild into Language.csproj and Stdlib.csproj (both
IsPackable=false) and adds a CopyLanguageAndStdlibApiDocsToPackage target to
Core.csproj that folds their generated api/ folders into Core's own package
api/ folder (excluding each project's own single-assembly api.md index to avoid
collisions), plus extends CopyProjectReferencesToPackage to also embed
Language.xml/Stdlib.xml alongside the DLLs in lib/{tfm}/ for IntelliSense.

Adds internal static NamespaceDoc sentinel classes (ApiMark's supported
namespace-summary convention) with <summary>/<remarks>/<example> content to:
- DemaConsulting.SysML2Tools.Rendering (Core)
- DemaConsulting.SysML2Tools.Semantic (Language)
- DemaConsulting.SysML2Tools.Semantic.Internal (Language)
- DemaConsulting.SysML2Tools.Parser (Language)
- DemaConsulting.SysML2Tools.Stdlib (Stdlib)

Also strengthens XML doc comments/examples on the key entry-point types:
DiagramRenderer.RenderWorkspace, ILayoutStrategy/ViewContext, WorkspaceLoader,
SysmlNode, and StdlibProvider.GetSymbolTable, grounded in real call sites from
RenderCommand.RunAsync and the WorkspaceLoaderTests/StdlibProviderTests/
RenderIntegrationTests test suites.

Updates .reviewmark.yaml to attach each new NamespaceDoc.cs to its subsystem's
existing review-set file lists.

Verified end-to-end with a real dotnet pack of Core: the extracted nupkg's
api/ folder now contains pages for Rendering, Parser, Semantic (with nested
Semantic/Internal), and Stdlib namespaces, and lib/{tfm}/ contains
Language.xml/Stdlib.xml alongside the embedded DLLs for all three TFMs.
---
 .reviewmark.yaml                              |  9 ++++
 .../DemaConsulting.SysML2Tools.Core.csproj    | 42 ++++++++++++++++-
 .../Rendering/DiagramRenderer.cs              | 14 ++++++
 .../Rendering/ILayoutStrategy.cs              | 19 +++++++-
 .../Rendering/NamespaceDoc.cs                 | 45 +++++++++++++++++++
 ...DemaConsulting.SysML2Tools.Language.csproj |  5 +++
 .../Parser/NamespaceDoc.cs                    | 24 ++++++++++
 .../Semantic/Internal/NamespaceDoc.cs         | 33 ++++++++++++++
 .../Semantic/Internal/SysmlNode.cs            | 13 ++++++
 .../Semantic/NamespaceDoc.cs                  | 36 +++++++++++++++
 .../Semantic/WorkspaceLoader.cs               | 21 +++++++++
 .../DemaConsulting.SysML2Tools.Stdlib.csproj  |  5 +++
 .../NamespaceDoc.cs                           | 26 +++++++++++
 .../StdlibProvider.cs                         |  6 +++
 14 files changed, 295 insertions(+), 3 deletions(-)
 create mode 100644 src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
 create mode 100644 src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
 create mode 100644 src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
 create mode 100644 src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
 create mode 100644 src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs

diff --git a/.reviewmark.yaml b/.reviewmark.yaml
index 41aac785..453c6eb5 100644
--- a/.reviewmark.yaml
+++ b/.reviewmark.yaml
@@ -146,13 +146,16 @@ 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/NamespaceDoc.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"
@@ -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,9 +357,11 @@ 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/NamespaceDoc.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"
@@ -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
@@ -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"
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index c67c5bd2..26c24e3d 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -69,16 +69,56 @@
   </ItemGroup>
 
   <!-- Embed the Language and Stdlib assemblies (both IsPackable=false) directly into this
-       package's lib folder, since they cannot be resolved as separate NuGet dependencies. -->
+       package's lib folder, since they cannot be resolved as separate NuGet dependencies. Also
+       embeds their XML doc-comment files alongside the assemblies so Visual Studio IntelliSense
+       resolves doc comments for types re-exported from Language/Stdlib (e.g. WorkspaceLoader,
+       StdlibProvider) when consumed through this package. -->
   <PropertyGroup>
     <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);CopyProjectReferencesToPackage</TargetsForTfmSpecificBuildOutput>
   </PropertyGroup>
   <Target Name="CopyProjectReferencesToPackage" DependsOnTargets="ResolveReferences">
     <ItemGroup>
       <BuildOutputInPackage Include="@(ReferencePath)" Condition="'%(ReferencePath.ReferenceSourceTarget)' == 'ProjectReference'" />
+      <_ProjectReferenceXmlDocs Include="@(ReferencePath->'%(RootDir)%(Directory)%(Filename).xml')"
+                                 Condition="'%(ReferencePath.ReferenceSourceTarget)' == 'ProjectReference'
+                                            and Exists('%(ReferencePath.RootDir)%(ReferencePath.Directory)%(ReferencePath.Filename).xml')" />
+      <BuildOutputInPackage Include="@(_ProjectReferenceXmlDocs)" />
     </ItemGroup>
   </Target>
 
+  <!-- Fold the Language and Stdlib projects' ApiMark-generated api/ folders into this package's
+       own api/ folder. Language and Stdlib are IsPackable=false and have no nupkg of their own
+       (see above), so this is the only way their "getting started" namespaces (Semantic, Parser,
+       Stdlib) reach a consumer's browsable API reference docs. Each project's own top-level
+       api.md index (a single-assembly summary table) is intentionally excluded from the copy —
+       it describes only that project's own namespaces and would collide with, or misleadingly
+       duplicate, this project's own api.md index; the per-namespace/per-type Markdown pages
+       (which do not collide, since namespaces differ) are copied as-is.
+       DependsOnTargets="ResolveReferences" is not required for correctness here (MSBuild already
+       guarantees Language/Stdlib finish building — including their own AfterTargets="Build"
+       ApiMark step — before this project's Build completes, since they are ProjectReferences),
+       but AfterTargets/BeforeTargets below pin this target's ordering relative to ApiMark's own
+       generation and pack-inclusion targets; verified end-to-end with a real `dotnet pack`. -->
+  <Target Name="CopyLanguageAndStdlibApiDocsToPackage"
+          Condition="'$(ApiMarkPackDocs)' == 'true'"
+          AfterTargets="GenerateApiMarkDocumentation"
+          BeforeTargets="_ApiMarkIncludeDocsInPackage">
+    <ItemGroup>
+      <_LanguageApiDocFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\**\*"
+                            Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\api.md" />
+      <_StdlibApiDocFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\**\*"
+                          Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\api.md" />
+    </ItemGroup>
+    <Copy SourceFiles="@(_LanguageApiDocFiles)"
+          DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
+          SkipUnchangedFiles="true"
+          Condition="'@(_LanguageApiDocFiles)' != ''" />
+    <Copy SourceFiles="@(_StdlibApiDocFiles)"
+          DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
+          SkipUnchangedFiles="true"
+          Condition="'@(_StdlibApiDocFiles)' != ''" />
+  </Target>
+
   <ItemGroup>
     <InternalsVisibleTo Include="DemaConsulting.SysML2Tools.Tests" />
   </ItemGroup>
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
index 34c7513f..1b479b85 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
@@ -86,6 +86,20 @@ public static IReadOnlyList<string> GetViewNames(SysmlWorkspace workspace)
     /// An ordered list of <see cref="RenderOutput"/> instances, one per view in declaration order.
     /// Returns an empty list when the workspace contains no view declarations.
     /// </returns>
+    /// <example>
+    /// <code>
+    /// var diagramRenderer = new DiagramRenderer();
+    /// var svgRenderer = new SvgRenderer();
+    /// var options = new RenderOptions(Themes.Light);
+    /// var outputs = diagramRenderer.RenderWorkspace(workspace, svgRenderer, options);
+    ///
+    /// foreach (var output in outputs)
+    /// {
+    ///     await using var file = File.Create(output.SuggestedFileName);
+    ///     await output.Data.CopyToAsync(file);
+    /// }
+    /// </code>
+    /// </example>
     // S2325: instance method — future phases will inject ILayoutStrategy via constructor making this non-static
 #pragma warning disable S2325
     public IReadOnlyList<RenderOutput> RenderWorkspace(
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/ILayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/ILayoutStrategy.cs
index 75aef746..0004c443 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/ILayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/ILayoutStrategy.cs
@@ -11,8 +11,16 @@ namespace DemaConsulting.SysML2Tools.Rendering;
 /// <summary>
 /// Context passed to an <see cref="ILayoutStrategy"/> describing the view to lay out.
 /// </summary>
-/// <param name="ViewName">Name of the view being rendered.</param>
-/// <param name="Workspace">The SysML workspace containing model elements.</param>
+/// <param name="ViewName">
+/// Name of the view being rendered — the display name resolved by
+/// <see cref="DiagramRenderer.RenderWorkspace"/> (the view's simple <c>Name</c> when set,
+/// otherwise its fully-qualified name).
+/// </param>
+/// <param name="Workspace">
+/// The loaded <see cref="SysmlWorkspace"/> containing all model elements, so the strategy can
+/// resolve the view's target element(s) and traverse related declarations while building the
+/// layout tree.
+/// </param>
 public sealed record ViewContext(
     string ViewName,
     SysmlWorkspace Workspace);
@@ -21,6 +29,13 @@ public sealed record ViewContext(
 /// Computes a <see cref="LayoutTree"/> from a <see cref="ViewContext"/>.
 /// Implementations are responsible for node placement and line routing (including A* path-finding).
 /// </summary>
+/// <remarks>
+/// Implement this interface to add support for a new diagram kind (e.g. a new SysML view
+/// keyword), or to swap in an alternative layout algorithm for an existing kind. Strategy
+/// selection for a given view is performed by <c>Internal.DiagramTypeRouter</c>, which
+/// <see cref="DiagramRenderer.RenderWorkspace"/> consults for each view declaration in the
+/// workspace.
+/// </remarks>
 public interface ILayoutStrategy
 {
     /// <summary>
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
new file mode 100644
index 00000000..c903deb6
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
@@ -0,0 +1,45 @@
+// <copyright file="NamespaceDoc.cs" company="DemaConsulting">
+// Copyright (c) DemaConsulting. All rights reserved.
+// </copyright>
+
+namespace DemaConsulting.SysML2Tools.Rendering;
+
+/// <summary>
+/// Renders a loaded SysML/KerML workspace's <c>view</c> declarations to SVG/PNG diagrams.
+/// </summary>
+/// <remarks>
+/// <see cref="DiagramRenderer"/> is the entry point: it iterates the view declarations in a
+/// <see cref="Semantic.SysmlWorkspace"/>, selects a layout strategy for each, and writes the
+/// resulting diagram through a caller-supplied <c>IRenderer</c> (e.g. <c>SvgRenderer</c>,
+/// <c>PngRenderer</c>, both from <c>DemaConsulting.Rendering.*</c>). Custom layout algorithms
+/// implement <see cref="ILayoutStrategy"/>, which receives a <see cref="ViewContext"/>
+/// identifying the view and workspace to lay out.
+/// <para>
+/// A workspace must be loaded before it can be rendered: seed the standard library via
+/// <c>StdlibProvider.GetSymbolTable()</c> (<see cref="Stdlib.StdlibProvider"/>) and load user
+/// files via <c>WorkspaceLoader.LoadAsync</c> (<see cref="Semantic.WorkspaceLoader"/>).
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
+/// var loadResult = await WorkspaceLoader.LoadAsync(["model.sysml"], stdlibTable);
+/// if (loadResult.Workspace is null)
+/// {
+///     return; // parse/resolution errors — see loadResult.Diagnostics
+/// }
+///
+/// var diagramRenderer = new DiagramRenderer();
+/// var options = new RenderOptions(Themes.Light);
+/// var outputs = diagramRenderer.RenderWorkspace(loadResult.Workspace, new SvgRenderer(), options);
+///
+/// foreach (var output in outputs)
+/// {
+///     await using var file = File.Create(output.SuggestedFileName);
+///     await output.Data.CopyToAsync(file);
+/// }
+/// </code>
+/// </example>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
index 97c4f75c..6228b6ce 100644
--- a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
+++ b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
@@ -48,6 +48,11 @@
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
     <PackageReference Include="Polyfill" Version="10.10.0" PrivateAssets="All" />
+    <!-- ApiMark: generate Markdown API reference docs from the XML doc comments (see
+         GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
+         of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
+         package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
new file mode 100644
index 00000000..6c829555
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
@@ -0,0 +1,24 @@
+// Copyright (c) DemaConsulting. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DemaConsulting.SysML2Tools.Parser;
+
+/// <summary>
+/// Low-level SysML/KerML syntax parsing (source text to concrete syntax tree).
+/// </summary>
+/// <remarks>
+/// This namespace performs syntax-only parsing: <c>WorkspaceParser.ParseSource</c> and
+/// <c>ParseSourceToCst</c> turn source text into diagnostics (and, for the latter, an
+/// ANTLR-generated concrete syntax tree). No symbol table, reference resolution, or
+/// specialization walking happens here.
+/// <para>
+/// Most consumers should not need this namespace directly — use
+/// <see cref="Semantic.WorkspaceLoader"/> instead, which wraps parsing together with symbol
+/// registration and reference resolution to produce a fully-resolved
+/// <see cref="Semantic.SysmlWorkspace"/>. This namespace is intended for lower-level scenarios
+/// such as syntax-only validation of a single file without loading the standard library.
+/// </para>
+/// </remarks>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
new file mode 100644
index 00000000..e2048cbe
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
@@ -0,0 +1,33 @@
+// Copyright (c) DemaConsulting. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+
+/// <summary>
+/// Defines the semantic-model AST node types produced by <see cref="WorkspaceLoader"/>.
+/// </summary>
+/// <remarks>
+/// Despite the "Internal" folder name, the types in this namespace are public because they are
+/// the concrete node types returned in <see cref="SysmlWorkspace.Declarations"/> — a consumer
+/// pattern-matching over a loaded workspace needs to see them. <see cref="SysmlNode"/> is the
+/// abstract base type; its subtypes include <c>SysmlDefinitionNode</c> ("part def", "attribute
+/// def", ...), <c>SysmlFeatureNode</c> ("part", "port", "attribute", ...), <c>SysmlViewNode</c>,
+/// <c>SysmlPackageNode</c>, and others. <see cref="SysmlEdge"/> and <see cref="SemanticIndex"/>
+/// expose the resolved supertype/typing/import graph via <see cref="SysmlWorkspace.Index"/>, and
+/// <see cref="SysmlAnnotation"/> captures <c>comment</c>/<c>documentation</c> members attached to
+/// a node.
+/// </remarks>
+/// <example>
+/// <code>
+/// foreach (var (qualifiedName, node) in workspace.Declarations)
+/// {
+///     if (node is SysmlDefinitionNode { DefinitionKeyword: "part def" } partDef)
+///     {
+///         Console.WriteLine($"{qualifiedName}: {partDef.Children.Count} member(s)");
+///     }
+/// }
+/// </code>
+/// </example>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs
index c8482c7a..2eace89c 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs
@@ -8,6 +8,19 @@ namespace DemaConsulting.SysML2Tools.Semantic.Internal;
 /// <summary>
 ///     Base class for all SysML/KerML AST nodes.
 /// </summary>
+/// <example>
+/// A consumer typically pattern-matches over <see cref="Semantic.SysmlWorkspace.Declarations"/>
+/// to find nodes of interest:
+/// <code>
+/// foreach (var (qualifiedName, node) in workspace.Declarations)
+/// {
+///     if (node is SysmlDefinitionNode { DefinitionKeyword: "part def" } partDef)
+///     {
+///         Console.WriteLine($"{qualifiedName}: {partDef.SupertypeNames.Count} supertype(s)");
+///     }
+/// }
+/// </code>
+/// </example>
 [JsonPolymorphic(TypeDiscriminatorPropertyName = "$type")]
 [JsonDerivedType(typeof(SysmlPackageNode), "package")]
 [JsonDerivedType(typeof(SysmlDefinitionNode), "definition")]
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
new file mode 100644
index 00000000..463fc003
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
@@ -0,0 +1,36 @@
+// Copyright (c) DemaConsulting. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DemaConsulting.SysML2Tools.Semantic;
+
+/// <summary>
+/// Loads SysML/KerML source files into a semantically-resolved workspace.
+/// </summary>
+/// <remarks>
+/// This is the primary "getting started" namespace for consumers of the library:
+/// <see cref="WorkspaceLoader"/> parses one or more source files, resolves references,
+/// walks specialization (supertype) chains, and returns a <see cref="SysmlWorkspace"/> whose
+/// <see cref="SysmlWorkspace.Declarations"/> map fully-qualified names to the resolved AST
+/// (see the <c>DemaConsulting.SysML2Tools.Semantic.Internal</c> namespace for the node types,
+/// e.g. <c>SysmlDefinitionNode</c>, <c>SysmlFeatureNode</c>, <c>SysmlViewNode</c>).
+/// <para>
+/// <see cref="WorkspaceLoader.LoadAsync"/> should always be seeded with the pre-compiled
+/// standard library symbol table from <c>StdlibProvider.GetSymbolTable()</c>
+/// (the Stdlib project's <c>StdlibProvider</c> class), so that user models can reference
+/// stdlib types (e.g. <c>ScalarValues::Real</c>) without re-parsing the library on every load.
+/// </para>
+/// </remarks>
+/// <example>
+/// <code>
+/// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
+/// var result = await WorkspaceLoader.LoadAsync([path], stdlibTable);
+///
+/// if (result.Workspace!.Declarations.ContainsKey("Foo"))
+/// {
+///     // "Foo" was declared in the loaded file(s)
+/// }
+/// </code>
+/// </example>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
index 4b514b79..46cd9fc4 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
@@ -9,6 +9,18 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 /// <summary>
 ///     Loads SysML/KerML files into a semantic workspace with symbol registration and reference resolution.
 /// </summary>
+/// <remarks>
+///     <see cref="LoadAsync"/> is the primary entry point for consuming this library: it parses
+///     all supplied files in parallel, registers every declaration in a symbol table, resolves
+///     supertype/typing/import references, and walks specialization chains — returning a fully
+///     resolved <see cref="SysmlWorkspace"/> plus the aggregated diagnostics from every phase.
+///     <para>
+///     Always seed the <c>seedSymbolTable</c> parameter with the pre-compiled standard library
+///     symbol table (<c>StdlibProvider.GetSymbolTable()</c>) unless the caller has a specific
+///     reason to load user files against an empty namespace; without the stdlib seed, references
+///     to standard-library types (e.g. <c>ScalarValues::Real</c>) fail to resolve.
+///     </para>
+/// </remarks>
 public static class WorkspaceLoader
 {
     /// <summary>
@@ -26,6 +38,15 @@ public static class WorkspaceLoader
     /// <returns>
     ///     A <see cref="SysmlLoadResult"/> containing the workspace and all diagnostics.
     /// </returns>
+    /// <example>
+    /// <code>
+    /// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
+    /// var result = await WorkspaceLoader.LoadAsync([tempFile], stdlibTable);
+    ///
+    /// Assert.NotNull(result.Workspace);
+    /// Assert.False(result.HasErrors);
+    /// </code>
+    /// </example>
     public static async Task<SysmlLoadResult> LoadAsync(
         IEnumerable<string> filePaths,
         SymbolTable? seedSymbolTable = null)
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
index 0be0758b..d3c8cfe0 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
@@ -85,6 +85,11 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
+    <!-- ApiMark: generate Markdown API reference docs from the XML doc comments (see
+         GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
+         of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
+         package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.301">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs
new file mode 100644
index 00000000..3a6f307b
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs
@@ -0,0 +1,26 @@
+// Copyright (c) DemaConsulting. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DemaConsulting.SysML2Tools.Stdlib;
+
+/// <summary>
+/// Provides the pre-compiled SysML v2 standard library symbol table.
+/// </summary>
+/// <remarks>
+/// <see cref="StdlibProvider.GetSymbolTable"/> returns the symbol table produced by
+/// pre-compiling the embedded KerML/SysML standard library at build time (see
+/// <c>StdlibGen</c>), so it is available on first call without re-parsing the library source.
+/// The returned symbol table is the required seed for
+/// <see cref="Semantic.WorkspaceLoader.LoadAsync"/> — without it, user models that reference
+/// standard-library types (e.g. <c>ScalarValues::Real</c>, <c>Base::Anything</c>) fail to
+/// resolve.
+/// </remarks>
+/// <example>
+/// <code>
+/// var (table, _) = StdlibProvider.GetSymbolTable();
+/// Assert.True(table.Symbols.Count > 0, "Stdlib symbol table should not be empty.");
+/// </code>
+/// </example>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs b/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
index 1a1c788e..c10b297e 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
@@ -24,6 +24,12 @@ public static class StdlibProvider
     /// <returns>
     ///     A tuple of the stdlib symbol table and any diagnostics produced during pre-compilation.
     /// </returns>
+    /// <example>
+    /// <code>
+    /// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
+    /// var result = await WorkspaceLoader.LoadAsync(options.Files, stdlibTable);
+    /// </code>
+    /// </example>
     public static (SymbolTable Table, IReadOnlyList<SysmlDiagnostic> Diagnostics) GetSymbolTable()
         => _cached.Value;
 

From cd2426ece1d12297b6aadacdbd1823f22230b990 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Fri, 3 Jul 2026 17:01:09 -0400
Subject: [PATCH 04/13] fix(core): link folded-in namespace docs from api.md
 index and fix MSB3026 race

- CopyLanguageAndStdlibApiDocsToPackage now carries the same TFM-restriction
  condition used by ApiMark's own GenerateApiMarkDocumentation and
  _ApiMarkIncludeDocsInPackage targets, so it runs exactly once per pack/build
  instead of once per inner per-TFM build. This eliminates the MSB3026
  'file is being used by another process' race previously masked only by
  MSBuild's automatic retry.
- Added a RoslynCodeTaskFactory inline task, MergeApiMarkNamespaceIndex, that
  appends Language's and Stdlib's own namespace-table rows into Core's
  generated api.md after the copy step. The packed api/api.md index now links
  to all folded-in namespace pages (Parser, Parser.Antlr, Semantic,
  Semantic.Internal, Stdlib) in addition to Core's own Rendering namespace,
  instead of leaving them as orphaned files only reachable by browsing the
  raw api/ folder tree.
- Reworded Parser/NamespaceDoc.cs's <remarks> to distinguish the public
  WorkspaceParser.ParseSource method from the internal ParseSourceToCst
  helper, so the prose no longer implies both are equally-accessible API
  surface.

Verified with a real dotnet pack + nupkg extraction (zero MSB3026 warnings,
all 6 namespace rows present and linking to existing files), build.ps1
(441 tests x 3 TFMs, all green), fix.ps1, and lint.ps1 (clean).
---
 .../DemaConsulting.SysML2Tools.Core.csproj    | 81 ++++++++++++++++++-
 .../Parser/NamespaceDoc.cs                    |  8 +-
 2 files changed, 82 insertions(+), 7 deletions(-)

diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index 26c24e3d..319fd2fa 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -86,6 +86,68 @@
     </ItemGroup>
   </Target>
 
+  <!-- Inline task used by CopyLanguageAndStdlibApiDocsToPackage (below) to merge the Language's
+       and Stdlib's own namespace-table rows into this project's own generated api.md index, so
+       that the folded-in namespace pages are discoverable/linked from the package's natural
+       entry point instead of being orphaned files in the api/ tree. Written to no-op safely
+       (skip the merge, leave TargetIndexFile unchanged) if the expected table separator or a
+       source file is missing, so a future ApiMark output-format change degrades gracefully
+       rather than breaking the build. -->
+  <UsingTask TaskName="MergeApiMarkNamespaceIndex" TaskFactory="RoslynCodeTaskFactory"
+             AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">
+    <ParameterGroup>
+      <TargetIndexFile ParameterType="System.String" Required="true" />
+      <SourceIndexFiles ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />
+    </ParameterGroup>
+    <Task>
+      <Using Namespace="System.IO" />
+      <Using Namespace="System.Collections.Generic" />
+      <Code Type="Fragment" Language="cs"><![CDATA[
+        if (!File.Exists(TargetIndexFile))
+        {
+            Log.LogMessage("MergeApiMarkNamespaceIndex: target index file not found, skipping merge: " + TargetIndexFile);
+            return true;
+        }
+
+        var lines = new List<string>(File.ReadAllLines(TargetIndexFile));
+        var separatorIndex = lines.FindIndex(l => l.Trim() == "| --- | --- | --- |");
+        if (separatorIndex < 0)
+        {
+            Log.LogMessage("MergeApiMarkNamespaceIndex: namespace table separator not found, skipping merge: " + TargetIndexFile);
+            return true;
+        }
+
+        var newRows = new List<string>();
+        foreach (var sourceItem in SourceIndexFiles)
+        {
+            var sourceFile = sourceItem.ItemSpec;
+            if (!File.Exists(sourceFile))
+            {
+                continue;
+            }
+
+            foreach (var line in File.ReadAllLines(sourceFile))
+            {
+                if (line.StartsWith("| [", StringComparison.Ordinal))
+                {
+                    newRows.Add(line);
+                }
+            }
+        }
+
+        if (newRows.Count == 0)
+        {
+            Log.LogMessage("MergeApiMarkNamespaceIndex: no namespace rows found in source index files, skipping merge.");
+            return true;
+        }
+
+        lines.InsertRange(separatorIndex + 1, newRows);
+        File.WriteAllLines(TargetIndexFile, lines);
+        Log.LogMessage("MergeApiMarkNamespaceIndex: merged " + newRows.Count + " namespace row(s) into " + TargetIndexFile);
+      ]]></Code>
+    </Task>
+  </UsingTask>
+
   <!-- Fold the Language and Stdlib projects' ApiMark-generated api/ folders into this package's
        own api/ folder. Language and Stdlib are IsPackable=false and have no nupkg of their own
        (see above), so this is the only way their "getting started" namespaces (Semantic, Parser,
@@ -93,14 +155,23 @@
        api.md index (a single-assembly summary table) is intentionally excluded from the copy —
        it describes only that project's own namespaces and would collide with, or misleadingly
        duplicate, this project's own api.md index; the per-namespace/per-type Markdown pages
-       (which do not collide, since namespaces differ) are copied as-is.
+       (which do not collide, since namespaces differ) are copied as-is. After copying, the
+       MergeApiMarkNamespaceIndex inline task (above) appends Language's and Stdlib's own
+       namespace-table rows into this project's own generated api.md, so that the copied-in
+       namespace pages are linked/discoverable from the package's natural entry point rather than
+       being orphaned files only reachable by browsing the raw api/ folder tree.
        DependsOnTargets="ResolveReferences" is not required for correctness here (MSBuild already
        guarantees Language/Stdlib finish building — including their own AfterTargets="Build"
        ApiMark step — before this project's Build completes, since they are ProjectReferences),
        but AfterTargets/BeforeTargets below pin this target's ordering relative to ApiMark's own
-       generation and pack-inclusion targets; verified end-to-end with a real `dotnet pack`. -->
+       generation and pack-inclusion targets; verified end-to-end with a real `dotnet pack`.
+       The TFM-restriction condition mirrors ApiMark's own GenerateApiMarkDocumentation/
+       _ApiMarkIncludeDocsInPackage targets so this target (copy + index-merge) runs exactly once
+       per pack/build, instead of once per inner per-TFM build (which would otherwise race
+       multiple concurrent copies/merges against the same destination files). -->
   <Target Name="CopyLanguageAndStdlibApiDocsToPackage"
-          Condition="'$(ApiMarkPackDocs)' == 'true'"
+          Condition="'$(ApiMarkPackDocs)' == 'true'
+                 and ('$(TargetFrameworks)' == '' or '$(TargetFramework)' == '$(_ApiMarkPackDocsTargetFramework)')"
           AfterTargets="GenerateApiMarkDocumentation"
           BeforeTargets="_ApiMarkIncludeDocsInPackage">
     <ItemGroup>
@@ -108,6 +179,8 @@
                             Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\api.md" />
       <_StdlibApiDocFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\**\*"
                           Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\api.md" />
+      <_ApiMarkSourceIndexFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\api.md" />
+      <_ApiMarkSourceIndexFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\api.md" />
     </ItemGroup>
     <Copy SourceFiles="@(_LanguageApiDocFiles)"
           DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
@@ -117,6 +190,8 @@
           DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
           SkipUnchangedFiles="true"
           Condition="'@(_StdlibApiDocFiles)' != ''" />
+    <MergeApiMarkNamespaceIndex TargetIndexFile="$(ApiMarkOutputDir)\api.md"
+                                SourceIndexFiles="@(_ApiMarkSourceIndexFiles)" />
   </Target>
 
   <ItemGroup>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
index 6c829555..1332ce2a 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Parser/NamespaceDoc.cs
@@ -7,10 +7,10 @@ namespace DemaConsulting.SysML2Tools.Parser;
 /// Low-level SysML/KerML syntax parsing (source text to concrete syntax tree).
 /// </summary>
 /// <remarks>
-/// This namespace performs syntax-only parsing: <c>WorkspaceParser.ParseSource</c> and
-/// <c>ParseSourceToCst</c> turn source text into diagnostics (and, for the latter, an
-/// ANTLR-generated concrete syntax tree). No symbol table, reference resolution, or
-/// specialization walking happens here.
+/// This namespace performs syntax-only parsing: the public <c>WorkspaceParser.ParseSource</c>
+/// method turns source text into diagnostics; an internal <c>ParseSourceToCst</c> helper
+/// additionally produces an ANTLR-generated concrete syntax tree for use elsewhere in this
+/// library. No symbol table, reference resolution, or specialization walking happens here.
 /// <para>
 /// Most consumers should not need this namespace directly — use
 /// <see cref="Semantic.WorkspaceLoader"/> instead, which wraps parsing together with symbol

From a5e40d7a90f4afe30a211a560ad3c79ba5985352 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 09:08:46 -0400
Subject: [PATCH 05/13] Exclude ANTLR4 codegen noise from ApiMark docs via
 0.4.10 native exclude

A dotnet pack of Core revealed its nupkg's api/ folder contained 8,657
ApiMark-generated Markdown files, of which 8,547 (98.7%) were pure
ANTLR4-codegen noise: one doc page per generated grammar-rule
visitor/listener method on the SysMLv2Lexer/SysMLv2Parser classes under
DemaConsulting.SysML2Tools.Language/Parser/Antlr. Nothing outside the
Language project references these generated types directly (the real
public entry point is WorkspaceParser), so this bloated the nupkg to
~7MB while providing zero value to consumers. The ANTLR-generated .cs
files themselves (per docs/design/ots/antlr4.md) must not be edited,
so the fix has to happen at the doc-generation/packaging layer.

DemaConsulting.ApiMark.MSBuild 0.4.10 adds a native exclusion feature
for exactly this: a repeatable `--exclude <wildcard>` CLI option and
its MSBuild equivalent, the `ApiMarkExclude` property, forwarded
verbatim to ApiMarkTask. This is applied at the Language project's own
ApiMark generation step - the true source of the noise - rather than
by post-hoc filtering copied files in Core's
CopyLanguageAndStdlibApiDocsToPackage target. Excluding at the source
means Language's own standalone generated api/ folder never contains
the noise in the first place, so nothing downstream (including Core's
copy/merge step) needs special-case handling for it. This is far
cleaner than a hand-rolled copy-time glob-exclusion or regex-based
dangling-link pruning approach, since the wildcard exclude is a
first-class supported feature of the tool with verified, correct
namespace-index handling (no dangling links left behind).

Changes:
- Bump DemaConsulting.ApiMark.MSBuild 0.4.9 -> 0.4.10 in Core, Language,
  and Stdlib csproj files.
- Add <ApiMarkExclude>DemaConsulting.SysML2Tools.Parser.Antlr*</ApiMarkExclude>
  to Language.csproj so its own ApiMark generation excludes the ANTLR
  namespace at the source.
- Core.csproj's CopyLanguageAndStdlibApiDocsToPackage target required
  no changes: it never contained an ANTLR-specific exclusion glob (its
  only Exclude= clauses target each project's own api.md index, which
  is unrelated and unaffected by this fix).

Verified via a clean dotnet pack of Core: api/ folder now contains 127
files (down from 8,657), no DemaConsulting.SysML2Tools.Parser.Antlr
files/folders present, real Parser namespace docs preserved
(DemaConsulting.SysML2Tools.Parser.md, WorkspaceParser.md,
WorkspaceParseResult.md, SysmlDiagnostic.md, DiagnosticSeverity.md),
no dangling links in api.md, and nupkg size down from ~7MB to ~2.6MB
(the api/ folder itself is only ~0.06MB uncompressed; the remaining
nupkg size is the embedded lib/ assemblies across 3 target frameworks,
unrelated to this fix). Full build.ps1 (build+tests), fix.ps1, and
lint.ps1 all pass clean with no production code changes.
---
 .../DemaConsulting.SysML2Tools.Core.csproj               | 2 +-
 .../DemaConsulting.SysML2Tools.Language.csproj           | 9 ++++++++-
 .../DemaConsulting.SysML2Tools.Stdlib.csproj             | 2 +-
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index 319fd2fa..eac19802 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -55,7 +55,7 @@
   <ItemGroup>
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
-    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.10" PrivateAssets="All" />
     <PackageReference Include="DemaConsulting.Rendering.Layout" Version="0.1.0-beta.2" />
   </ItemGroup>
 
diff --git a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
index 6228b6ce..29904826 100644
--- a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
+++ b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
@@ -36,6 +36,13 @@
     <!-- Suppress errors from ANTLR4-generated code: 1584/1658 (cref keyword syntax), 3021 (CLSCompliant) -->
     <NoWarn>1584;1658;3021</NoWarn>
 
+    <!-- Exclude the ANTLR4-generated grammar/parser/lexer/listener/visitor code-gen namespace
+         from ApiMark-generated docs. These thousands of near-duplicate generated-code doc files
+         (SysMLv2Lexer, SysMLv2Parser, listener/visitor classes, etc.) provide zero value to
+         consumers of the packaged API reference docs. Confirmed working with ApiMark.MSBuild
+         0.4.10's native exclude wildcard feature (equivalent to its CLI "exclude" option). -->
+    <ApiMarkExclude>DemaConsulting.SysML2Tools.Parser.Antlr*</ApiMarkExclude>
+
     <!-- SBOM Configuration -->
     <GenerateSBOM>true</GenerateSBOM>
     <SBOMPackageName>$(Product)</SBOMPackageName>
@@ -52,7 +59,7 @@
          GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
          of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
          package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
-    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.10" PrivateAssets="All" />
   </ItemGroup>
 
   <ItemGroup>
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
index d3c8cfe0..eacf3e87 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
@@ -89,7 +89,7 @@
          GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
          of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
          package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
-    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.9" PrivateAssets="All" />
+    <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.10" PrivateAssets="All" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.301">
       <PrivateAssets>all</PrivateAssets>
       <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>

From 35e64cb5dc40b7425a714ad0675d93d9330d2657 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 09:58:53 -0400
Subject: [PATCH 06/13] Docs/naming polish: rendering pkg refs, stale-comment
 cleanup, Semantic.Internal->Semantic.Model rename, examples, ctors

- FIX1: document DemaConsulting.Rendering.Svg/.Skia package requirements for renderer examples
- FIX2: remove stale 'added in later units' from SemanticIndex + design doc; sweep for similar artifacts
- FIX3: clarify SysmlLoadResult.Workspace null semantics, add diagnostic-loop example
- FIX4: add GetOutgoingEdges/GetIncomingEdges traversal example to SemanticIndex
- FIX5: rewrite SysmlWorkspace.Declarations doc to lead with stdlib+user content fact
- FIX6: add 'Inherited from SysmlNode' remarks to 9 concrete node subtypes
- FIX7: mark AstSerializer/AstDeserializer as stdlib pre-compilation infrastructure
- FIX8: rename namespace/folder Semantic.Internal -> Semantic.Model (pure rename)
- FIX9: strengthen stdlib-requirement framing in Semantic namespace doc
- FIX10: add explicit documented parameterless constructors to SysmlWorkspace/DiagramRenderer
- FIX11: investigate ApiMark file-naming section config (none available; no change)
- FIX12: replace xUnit-style example in WorkspaceLoader.LoadAsync with realistic app code
---
 .reviewmark.yaml                              |  38 ++---
 docs/design/introduction.md                   |   2 +-
 .../semantic/ast-serializer.md                |   2 +-
 .../semantic/internal/semantic-index.md       |   2 +-
 .../semantic/internal/sysml-annotation.md     |   2 +-
 .../semantic/internal/sysml-edge.md           |   2 +-
 .../semantic/internal/sysml-node.md           |   2 +-
 docs/design/sysml2-tools-tool/query.md        |   2 +-
 .../Internal/ActionFlowViewLayoutStrategy.cs  |   2 +-
 .../Internal/BrowserViewLayoutStrategy.cs     |   2 +-
 .../Internal/GeneralViewLayoutStrategy.cs     |   2 +-
 .../Layout/Internal/GridViewLayoutStrategy.cs |   2 +-
 .../InterconnectionViewLayoutStrategy.cs      |   2 +-
 .../Internal/SequenceViewLayoutStrategy.cs    |   2 +-
 .../StateTransitionViewLayoutStrategy.cs      |   2 +-
 .../Rendering/DiagramRenderer.cs              |  16 +-
 .../Rendering/Internal/DiagramTypeRouter.cs   |   2 +-
 .../Rendering/NamespaceDoc.cs                 |  12 ++
 .../Semantic/AstDeserializer.cs               |   7 +-
 .../Semantic/AstSerializer.cs                 |   8 +-
 .../Semantic/Internal/NamespaceDoc.cs         |  33 ----
 .../{Internal => Model}/AstBuilder.cs         |   2 +-
 .../AstSerializerContext.cs                   |   2 +-
 .../Semantic/Model/NamespaceDoc.cs            |  34 ++++
 .../{Internal => Model}/ReferenceResolver.cs  |   2 +-
 .../{Internal => Model}/SemanticIndex.cs      |  14 +-
 .../{Internal => Model}/SerializedStdlib.cs   |   2 +-
 .../{Internal => Model}/SupertypeWalker.cs    |   2 +-
 .../{Internal => Model}/SymbolTable.cs        |   2 +-
 .../{Internal => Model}/SysmlAnnotation.cs    |   2 +-
 .../Semantic/{Internal => Model}/SysmlEdge.cs |   2 +-
 .../Semantic/{Internal => Model}/SysmlNode.cs |  38 ++++-
 .../Semantic/NamespaceDoc.cs                  |  14 +-
 .../Semantic/SysmlLoadResult.cs               |  24 +++
 .../Semantic/SysmlWorkspace.cs                |  24 ++-
 .../Semantic/WorkspaceLoader.cs               |  14 +-
 .../StdlibProvider.cs                         |   2 +-
 .../Query/QueryCommand.cs                     |   2 +-
 .../Query/QueryEngine.cs                      |   2 +-
 .../Query/QueryResultSerializerContext.cs     |   2 +-
 src/Tools/StdlibGen/Program.cs                |   2 +-
 .../ActionFlowViewLayoutStrategyTests.cs      |   2 +-
 .../BrowserAndGridViewLayoutStrategyTests.cs  |   2 +-
 .../Layout/GeneralViewLayoutStrategyTests.cs  |   2 +-
 .../InterconnectionViewLayoutStrategyTests.cs |   2 +-
 .../Layout/SequenceViewLayoutStrategyTests.cs |   2 +-
 .../StateTransitionViewLayoutStrategyTests.cs |   2 +-
 .../Rendering/DiagramTypeRouterTests.cs       |   2 +-
 .../Semantic/AstSerializerTests.cs            |   2 +-
 .../Semantic/WorkspaceLoaderTests.cs          | 146 +++++++++---------
 50 files changed, 315 insertions(+), 179 deletions(-)
 delete mode 100644 src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/AstBuilder.cs (99%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/AstSerializerContext.cs (88%)
 create mode 100644 src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/ReferenceResolver.cs (99%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SemanticIndex.cs (87%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SerializedStdlib.cs (87%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SupertypeWalker.cs (98%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SymbolTable.cs (97%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SysmlAnnotation.cs (95%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SysmlEdge.cs (98%)
 rename src/DemaConsulting.SysML2Tools.Language/Semantic/{Internal => Model}/SysmlNode.cs (83%)

diff --git a/.reviewmark.yaml b/.reviewmark.yaml
index 453c6eb5..3fc1314e 100644
--- a/.reviewmark.yaml
+++ b/.reviewmark.yaml
@@ -154,17 +154,17 @@ reviews:
       - "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/NamespaceDoc.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"
@@ -360,12 +360,12 @@ reviews:
       - "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/NamespaceDoc.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"
 
@@ -422,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
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
index b19aa0b4..577fcfad 100644
--- a/docs/design/introduction.md
+++ b/docs/design/introduction.md
@@ -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/** — internal implementation (SysmlNode, AstBuilder, SymbolTable,
         ReferenceResolver, SupertypeWalker, SysmlEdge, SemanticIndex, SysmlAnnotation,
         SerializedStdlib, AstSerializerContext)
   - **DemaConsulting.SysML2Tools.Stdlib/** — stdlib library
diff --git a/docs/design/sysml2-tools-language/semantic/ast-serializer.md b/docs/design/sysml2-tools-language/semantic/ast-serializer.md
index bb404ecd..e9a45d5e 100644
--- a/docs/design/sysml2-tools-language/semantic/ast-serializer.md
+++ b/docs/design/sysml2-tools-language/semantic/ast-serializer.md
@@ -10,7 +10,7 @@ run time.
 #### Data Model
 
 `AstSerializer` is a static class with no instance state. It relies on two grouped internal types
-declared in the `Semantic/Internal` namespace:
+declared in the `Semantic/Model` namespace:
 
 - **`SerializedStdlib`** — an internal DTO record pairing the symbol dictionary
   (`Dictionary<string, SysmlNode>`) with the diagnostics list. It is the on-the-wire shape written
diff --git a/docs/design/sysml2-tools-language/semantic/internal/semantic-index.md b/docs/design/sysml2-tools-language/semantic/internal/semantic-index.md
index 763006c5..2cf08a8a 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/semantic-index.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/semantic-index.md
@@ -5,7 +5,7 @@
 `SemanticIndex` is a reverse-lookup index over the resolved `SysmlEdge` collection produced
 by `ReferenceResolver.ResolveAll`. It answers "what does X reference" (outgoing) and "what
 references X" (incoming) queries, forming the foundation for the `query` command's
-`uses`/`used-by`/`impact`/`hierarchy` verbs added in later units.
+`uses`/`used-by`/`impact`/`hierarchy` verbs.
 
 ##### Algorithm
 
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md b/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
index 6df8f3ed..4720c3cf 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
@@ -28,7 +28,7 @@ N/A — `SysmlAnnotation` is a pure data record with no logic or validation.
 
 ##### Dependencies
 
-- No external dependencies. Public types within the `Semantic.Internal` namespace.
+- No external dependencies. Public types within the `Semantic.Model` namespace.
 
 ##### Callers
 
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md b/docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md
index 3651c244..7a8f2857 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md
@@ -47,7 +47,7 @@ N/A — `SysmlEdge` is a pure data record with no logic or validation.
 
 ##### Dependencies
 
-- No external dependencies. Public types within the `Semantic.Internal` namespace.
+- No external dependencies. Public types within the `Semantic.Model` namespace.
 
 ##### Callers
 
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-node.md b/docs/design/sysml2-tools-language/semantic/internal/sysml-node.md
index 4c2ddef6..00464c7e 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/sysml-node.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/sysml-node.md
@@ -102,7 +102,7 @@ elements are filtered out by `AstBuilder` before a node is constructed.
 ##### Dependencies
 
 - No external dependencies. All node types are internal sealed classes or the abstract base class
-  within the `Semantic.Internal` namespace.
+  within the `Semantic.Model` namespace.
 
 ##### Callers
 
diff --git a/docs/design/sysml2-tools-tool/query.md b/docs/design/sysml2-tools-tool/query.md
index 95f6252d..fb02784e 100644
--- a/docs/design/sysml2-tools-tool/query.md
+++ b/docs/design/sysml2-tools-tool/query.md
@@ -26,7 +26,7 @@ cooperating types:
 
 #### Verb Semantics
 
-Every verb reads the semantic model built by the `Semantic`/`Semantic.Internal` types
+Every verb reads the semantic model built by the `Semantic`/`Semantic.Model` types
 (`SemanticIndex`, `SysmlNode.ResolvedEdges`, `SysmlNode.Children`) rather than re-parsing or
 re-resolving anything; `QueryEngine` is a pure read-only consumer of the workspace built by
 `WorkspaceLoader.LoadAsync`.
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/ActionFlowViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/ActionFlowViewLayoutStrategy.cs
index c99ca66d..78fc7ba3 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/ActionFlowViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/ActionFlowViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/BrowserViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/BrowserViewLayoutStrategy.cs
index 9014bf37..b9d75755 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/BrowserViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/BrowserViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GeneralViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GeneralViewLayoutStrategy.cs
index 4c0396ed..700ad5b5 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GeneralViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GeneralViewLayoutStrategy.cs
@@ -8,7 +8,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GridViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GridViewLayoutStrategy.cs
index fd06cd2e..d2bf73ed 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GridViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/GridViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/InterconnectionViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/InterconnectionViewLayoutStrategy.cs
index d86ebc16..cd2caebf 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/InterconnectionViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/InterconnectionViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/SequenceViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/SequenceViewLayoutStrategy.cs
index ad141ad3..69532f89 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/SequenceViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/SequenceViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/StateTransitionViewLayoutStrategy.cs b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/StateTransitionViewLayoutStrategy.cs
index b4dbbd37..20ec8b1d 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/StateTransitionViewLayoutStrategy.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Layout/Internal/StateTransitionViewLayoutStrategy.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Layout.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
index 1b479b85..db0e4ba0 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/DiagramRenderer.cs
@@ -5,7 +5,7 @@
 using DemaConsulting.Rendering;
 using DemaConsulting.Rendering.Abstractions;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Rendering;
 
@@ -20,9 +20,23 @@ namespace DemaConsulting.SysML2Tools.Rendering;
 /// It delegates layout selection to <see cref="Internal.DiagramTypeRouter"/> and collects
 /// one <see cref="RenderOutput"/> per view found in <see cref="SysmlWorkspace.Declarations"/>.
 /// Views whose type is not supported by any available strategy are silently skipped.
+/// <para>
+/// The <see cref="RenderWorkspace"/> example below requires a concrete <c>IRenderer</c>
+/// implementation from a renderer package — see the <c>DemaConsulting.SysML2Tools.Rendering</c>
+/// namespace remarks for the exact package reference(s) needed (e.g.
+/// <c>DemaConsulting.Rendering.Svg</c> for <c>SvgRenderer</c>).
+/// </para>
 /// </remarks>
 public sealed class DiagramRenderer
 {
+    /// <summary>
+    /// Initializes a new <see cref="DiagramRenderer"/> instance. The renderer is stateless; a
+    /// single instance may be reused across multiple <see cref="RenderWorkspace"/> calls.
+    /// </summary>
+    public DiagramRenderer()
+    {
+    }
+
     /// <summary>
     /// Returns the display names of all renderable user-defined views in the workspace,
     /// mirroring the filtering applied by <see cref="RenderWorkspace"/>.
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/Internal/DiagramTypeRouter.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/Internal/DiagramTypeRouter.cs
index 8a43f000..aa04d8b5 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/Internal/DiagramTypeRouter.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/Internal/DiagramTypeRouter.cs
@@ -4,7 +4,7 @@
 
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Rendering.Internal;
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
index c903deb6..f1c7a4ec 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
@@ -19,6 +19,18 @@ namespace DemaConsulting.SysML2Tools.Rendering;
 /// <c>StdlibProvider.GetSymbolTable()</c> (<see cref="Stdlib.StdlibProvider"/>) and load user
 /// files via <c>WorkspaceLoader.LoadAsync</c> (<see cref="Semantic.WorkspaceLoader"/>).
 /// </para>
+/// <para>
+/// The example below additionally requires a renderer package reference beyond what this project
+/// (<c>DemaConsulting.SysML2Tools.Core</c>) already brings in transitively via
+/// <c>DemaConsulting.Rendering.Layout</c> (which supplies <c>DemaConsulting.Rendering</c> and
+/// <c>DemaConsulting.Rendering.Abstractions</c> — the source of <c>RenderOptions</c>,
+/// <c>Themes</c>, and <c>RenderOutput</c> used below). Add a concrete renderer package for the
+/// output format you need:
+/// <code>
+/// dotnet add package DemaConsulting.Rendering.Svg   # for SvgRenderer
+/// dotnet add package DemaConsulting.Rendering.Skia  # for PngRenderer
+/// </code>
+/// </para>
 /// </remarks>
 /// <example>
 /// <code>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs
index 8f0a6454..3af802e0 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/AstDeserializer.cs
@@ -3,13 +3,18 @@
 
 using System.Text.Json;
 using DemaConsulting.SysML2Tools.Parser;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Semantic;
 
 /// <summary>
 ///     Deserializes a pre-compiled stdlib binary back to a <see cref="SymbolTable"/> and diagnostics.
 /// </summary>
+/// <remarks>
+///     Infrastructure used internally by <c>StdlibProvider.GetSymbolTable()</c> (the Stdlib
+///     project's <c>StdlibProvider</c> class) to reconstruct the symbol table from the embedded
+///     <c>stdlib.bin</c> resource. Application code does not normally call this directly.
+/// </remarks>
 public static class AstDeserializer
 {
     /// <summary>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs
index 23931265..f3de0023 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/AstSerializer.cs
@@ -3,13 +3,19 @@
 
 using System.Text.Json;
 using DemaConsulting.SysML2Tools.Parser;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Semantic;
 
 /// <summary>
 ///     Serializes a <see cref="SymbolTable"/> and diagnostics to a binary blob for embedding as a resource.
 /// </summary>
+/// <remarks>
+///     Infrastructure for the standard-library pre-compilation pipeline (used by the build-time
+///     <c>StdlibGen</c> tool to produce the embedded <c>stdlib.bin</c> resource). Application code
+///     does not normally call this directly — consume the pre-compiled stdlib symbol table via
+///     <c>StdlibProvider.GetSymbolTable()</c> (the Stdlib project's <c>StdlibProvider</c> class) instead.
+/// </remarks>
 public static class AstSerializer
 {
     /// <summary>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
deleted file mode 100644
index e2048cbe..00000000
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/NamespaceDoc.cs
+++ /dev/null
@@ -1,33 +0,0 @@
-// Copyright (c) DemaConsulting. All rights reserved.
-// Licensed under the MIT License.
-
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
-
-/// <summary>
-/// Defines the semantic-model AST node types produced by <see cref="WorkspaceLoader"/>.
-/// </summary>
-/// <remarks>
-/// Despite the "Internal" folder name, the types in this namespace are public because they are
-/// the concrete node types returned in <see cref="SysmlWorkspace.Declarations"/> — a consumer
-/// pattern-matching over a loaded workspace needs to see them. <see cref="SysmlNode"/> is the
-/// abstract base type; its subtypes include <c>SysmlDefinitionNode</c> ("part def", "attribute
-/// def", ...), <c>SysmlFeatureNode</c> ("part", "port", "attribute", ...), <c>SysmlViewNode</c>,
-/// <c>SysmlPackageNode</c>, and others. <see cref="SysmlEdge"/> and <see cref="SemanticIndex"/>
-/// expose the resolved supertype/typing/import graph via <see cref="SysmlWorkspace.Index"/>, and
-/// <see cref="SysmlAnnotation"/> captures <c>comment</c>/<c>documentation</c> members attached to
-/// a node.
-/// </remarks>
-/// <example>
-/// <code>
-/// foreach (var (qualifiedName, node) in workspace.Declarations)
-/// {
-///     if (node is SysmlDefinitionNode { DefinitionKeyword: "part def" } partDef)
-///     {
-///         Console.WriteLine($"{qualifiedName}: {partDef.Children.Count} member(s)");
-///     }
-/// }
-/// </code>
-/// </example>
-internal static class NamespaceDoc
-{
-}
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstBuilder.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs
similarity index 99%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstBuilder.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs
index be844900..dd4aacc0 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstBuilder.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstBuilder.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser.Antlr;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Builds a SysML/KerML AST from an ANTLR4 CST produced by <see cref="SysMLv2Parser"/>.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstSerializerContext.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstSerializerContext.cs
similarity index 88%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstSerializerContext.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstSerializerContext.cs
index b745012a..0d239211 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/AstSerializerContext.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/AstSerializerContext.cs
@@ -3,7 +3,7 @@
 
 using System.Text.Json.Serialization;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Source-generator context for serializing/deserializing the stdlib binary.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs
new file mode 100644
index 00000000..3f456b04
--- /dev/null
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/NamespaceDoc.cs
@@ -0,0 +1,34 @@
+// Copyright (c) DemaConsulting. All rights reserved.
+// Licensed under the MIT License.
+
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
+
+/// <summary>
+/// Defines the semantic-model AST node types produced by <see cref="WorkspaceLoader"/>.
+/// </summary>
+/// <remarks>
+/// This namespace holds the public concrete AST/semantic-graph node types and index returned by
+/// <see cref="SysmlWorkspace"/> — the concrete node types returned in
+/// <see cref="SysmlWorkspace.Declarations"/> that a consumer pattern-matches over when inspecting
+/// a loaded workspace. <see cref="SysmlNode"/> is the abstract base type; its subtypes include
+/// <c>SysmlDefinitionNode</c> ("part def", "attribute def", ...), <c>SysmlFeatureNode</c> ("part",
+/// "port", "attribute", ...), <c>SysmlViewNode</c>, <c>SysmlPackageNode</c>, and others.
+/// <see cref="SysmlEdge"/> and <see cref="SemanticIndex"/> expose the resolved
+/// supertype/typing/import graph via <see cref="SysmlWorkspace.Index"/>, and
+/// <see cref="SysmlAnnotation"/> captures <c>comment</c>/<c>documentation</c> members attached to
+/// a node.
+/// </remarks>
+/// <example>
+/// <code>
+/// foreach (var (qualifiedName, node) in workspace.Declarations)
+/// {
+///     if (node is SysmlDefinitionNode { DefinitionKeyword: "part def" } partDef)
+///     {
+///         Console.WriteLine($"{qualifiedName}: {partDef.Children.Count} member(s)");
+///     }
+/// }
+/// </code>
+/// </example>
+internal static class NamespaceDoc
+{
+}
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/ReferenceResolver.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs
similarity index 99%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/ReferenceResolver.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs
index 04513f80..d40bfb8c 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/ReferenceResolver.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/ReferenceResolver.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Resolves qualified name references and import chains across all loaded files.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SemanticIndex.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SemanticIndex.cs
similarity index 87%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SemanticIndex.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SemanticIndex.cs
index 448d4892..8d07c8da 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SemanticIndex.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SemanticIndex.cs
@@ -1,15 +1,23 @@
 // Copyright (c) DemaConsulting. All rights reserved.
 // Licensed under the MIT License.
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Reverse-lookup index over resolved semantic edges (supertype, typing, import), answering
 ///     "what does X reference" and "what references X" queries in O(1) average time. Built once
 ///     per <see cref="ReferenceResolver.ResolveAll"/> pass and exposed via
-///     <see cref="Semantic.SysmlWorkspace"/> for consumption by the <c>query</c> command
-///     (<c>uses</c>/<c>used-by</c>/<c>impact</c>/<c>hierarchy</c> verbs, added in later units).
+///     <see cref="Semantic.SysmlWorkspace.Index"/> for consumption by the <c>query</c> command's
+///     <c>uses</c>/<c>used-by</c>/<c>impact</c>/<c>hierarchy</c> verbs.
 /// </summary>
+/// <example>
+/// <code>
+/// foreach (var edge in workspace.Index.GetOutgoingEdges("Vehicles::Car"))
+/// {
+///     Console.WriteLine($"Car --{edge.Kind}--> {edge.TargetQualifiedName}");
+/// }
+/// </code>
+/// </example>
 public sealed class SemanticIndex
 {
     /// <summary>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SerializedStdlib.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SerializedStdlib.cs
similarity index 87%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SerializedStdlib.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SerializedStdlib.cs
index 09d833be..e9872fde 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SerializedStdlib.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SerializedStdlib.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Data-transfer object for serializing/deserializing the pre-compiled stdlib binary.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SupertypeWalker.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SupertypeWalker.cs
similarity index 98%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SupertypeWalker.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SupertypeWalker.cs
index 3cdcdd32..e4947e16 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SupertypeWalker.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SupertypeWalker.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Walks specialization chains to validate supertype references and detect cycles.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SymbolTable.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SymbolTable.cs
similarity index 97%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SymbolTable.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SymbolTable.cs
index 33c744f5..0513e01e 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SymbolTable.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SymbolTable.cs
@@ -1,7 +1,7 @@
 // Copyright (c) DemaConsulting. All rights reserved.
 // Licensed under the MIT License.
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Registry mapping fully-qualified SysML/KerML names to their declaration nodes.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlAnnotation.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlAnnotation.cs
similarity index 95%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlAnnotation.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlAnnotation.cs
index 747ca0e3..3958442f 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlAnnotation.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlAnnotation.cs
@@ -1,7 +1,7 @@
 // Copyright (c) DemaConsulting. All rights reserved.
 // Licensed under the MIT License.
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Classifies the kind of documentation text a <see cref="SysmlAnnotation"/> represents.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlEdge.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlEdge.cs
similarity index 98%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlEdge.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlEdge.cs
index c7579d48..85538a42 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlEdge.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlEdge.cs
@@ -1,7 +1,7 @@
 // Copyright (c) DemaConsulting. All rights reserved.
 // Licensed under the MIT License.
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Classifies the kind of resolved reference a <see cref="SysmlEdge"/> represents.
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
similarity index 83%
rename from src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs
rename to src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
index 2eace89c..6853e69b 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Internal/SysmlNode.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
@@ -3,7 +3,7 @@
 
 using System.Text.Json.Serialization;
 
-namespace DemaConsulting.SysML2Tools.Semantic.Internal;
+namespace DemaConsulting.SysML2Tools.Semantic.Model;
 
 /// <summary>
 ///     Base class for all SysML/KerML AST nodes.
@@ -100,6 +100,10 @@ public abstract class SysmlNode
 /// <summary>
 ///     AST node representing a SysML/KerML package or namespace.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlPackageNode : SysmlNode
 {
 }
@@ -107,6 +111,10 @@ public sealed class SysmlPackageNode : SysmlNode
 /// <summary>
 ///     AST node representing a definition element (part def, attribute def, etc.).
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlDefinitionNode : SysmlNode
 {
     /// <summary>
@@ -118,6 +126,10 @@ public sealed class SysmlDefinitionNode : SysmlNode
 /// <summary>
 ///     AST node representing a usage/feature element (part, attribute, etc.).
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlFeatureNode : SysmlNode
 {
     /// <summary>
@@ -139,6 +151,10 @@ public sealed class SysmlFeatureNode : SysmlNode
 /// <summary>
 ///     AST node representing an import declaration.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlImportNode : SysmlNode
 {
     /// <summary>
@@ -155,6 +171,10 @@ public sealed class SysmlImportNode : SysmlNode
 /// <summary>
 ///     AST node representing a view definition.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlViewNode : SysmlNode
 {
 }
@@ -162,6 +182,10 @@ public sealed class SysmlViewNode : SysmlNode
 /// <summary>
 ///     AST node representing a viewpoint definition.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlViewpointNode : SysmlNode
 {
 }
@@ -169,6 +193,10 @@ public sealed class SysmlViewpointNode : SysmlNode
 /// <summary>
 ///     AST node representing a connection/binding usage between two endpoints.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlConnectionNode : SysmlNode
 {
     /// <summary>
@@ -193,6 +221,10 @@ public sealed class SysmlConnectionNode : SysmlNode
 /// <summary>
 ///     AST node representing a state transition (source state, target state, optional guard).
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlTransitionNode : SysmlNode
 {
     /// <summary>
@@ -214,6 +246,10 @@ public sealed class SysmlTransitionNode : SysmlNode
 /// <summary>
 ///     AST node representing a <c>satisfy X by Y;</c> requirement-satisfaction usage.
 /// </summary>
+/// <remarks>
+///     Inherited from SysmlNode: Name, QualifiedName, Children, SupertypeNames, ImportedNames,
+///     VerifiedRequirementNames, ResolvedEdges, Annotations.
+/// </remarks>
 public sealed class SysmlSatisfyNode : SysmlNode
 {
     /// <summary>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
index 463fc003..94b06bc6 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/NamespaceDoc.cs
@@ -11,13 +11,17 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 /// <see cref="WorkspaceLoader"/> parses one or more source files, resolves references,
 /// walks specialization (supertype) chains, and returns a <see cref="SysmlWorkspace"/> whose
 /// <see cref="SysmlWorkspace.Declarations"/> map fully-qualified names to the resolved AST
-/// (see the <c>DemaConsulting.SysML2Tools.Semantic.Internal</c> namespace for the node types,
+/// (see the <c>DemaConsulting.SysML2Tools.Semantic.Model</c> namespace for the node types,
 /// e.g. <c>SysmlDefinitionNode</c>, <c>SysmlFeatureNode</c>, <c>SysmlViewNode</c>).
 /// <para>
-/// <see cref="WorkspaceLoader.LoadAsync"/> should always be seeded with the pre-compiled
-/// standard library symbol table from <c>StdlibProvider.GetSymbolTable()</c>
-/// (the Stdlib project's <c>StdlibProvider</c> class), so that user models can reference
-/// stdlib types (e.g. <c>ScalarValues::Real</c>) without re-parsing the library on every load.
+/// Real-world SysML v2 models almost universally reference standard-library types (e.g.
+/// <c>ScalarValues::Real</c>, <c>Base::Anything</c>) for primitive attribute types and common
+/// base definitions. <see cref="WorkspaceLoader.LoadAsync"/> should be seeded with
+/// <c>StdlibProvider.GetSymbolTable()</c> (the Stdlib project's <c>StdlibProvider</c> class) for
+/// any model exercising these; without the seed, such references resolve to unresolved-reference
+/// Warning diagnostics rather than a loaded declaration. Omitting the seed is only appropriate
+/// for isolated syntax-only checks (e.g. parser unit tests) that do not exercise reference
+/// resolution.
 /// </para>
 /// </remarks>
 /// <example>
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
index a82da942..9afc610c 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
@@ -10,6 +10,30 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 /// </summary>
 /// <param name="Workspace">The semantic workspace, or null if loading failed entirely.</param>
 /// <param name="Diagnostics">All diagnostics (parse errors, semantic warnings) from the load operation.</param>
+/// <remarks>
+///     <see cref="Workspace"/> is non-null for every result returned by
+///     <see cref="WorkspaceLoader.LoadAsync"/> today — even a workspace containing only parse
+///     errors still returns a (possibly empty) <see cref="SysmlWorkspace"/>. Check
+///     <see cref="HasErrors"/> (or filter <see cref="Diagnostics"/> by <c>Severity</c>) to detect
+///     problems; do not rely on <c>Workspace is null</c> as an error signal.
+/// </remarks>
+/// <example>
+/// <code>
+/// var result = await WorkspaceLoader.LoadAsync(["model.sysml"], stdlibTable);
+/// foreach (var diagnostic in result.Diagnostics)
+/// {
+///     Console.WriteLine($"{diagnostic.FilePath}:{diagnostic.Line}:{diagnostic.Column} " +
+///         $"{diagnostic.Severity}: {diagnostic.Message}");
+/// }
+///
+/// if (result.HasErrors)
+/// {
+///     return; // one or more error-severity diagnostics were reported
+/// }
+///
+/// // result.Workspace is safe to use here
+/// </code>
+/// </example>
 public sealed record SysmlLoadResult(
     SysmlWorkspace? Workspace,
     IReadOnlyList<SysmlDiagnostic> Diagnostics)
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs
index e3aa30f0..a447b4e8 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlWorkspace.cs
@@ -1,7 +1,7 @@
 // Copyright (c) DemaConsulting. All rights reserved.
 // Licensed under the MIT License.
 
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Semantic;
 
@@ -10,6 +10,17 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 /// </summary>
 public sealed class SysmlWorkspace
 {
+    /// <summary>
+    ///     Initializes a new, empty <see cref="SysmlWorkspace"/>.
+    /// </summary>
+    /// <remarks>
+    ///     In normal usage, prefer <see cref="WorkspaceLoader.LoadAsync"/>, which constructs and
+    ///     populates a workspace from source files.
+    /// </remarks>
+    public SysmlWorkspace()
+    {
+    }
+
     /// <summary>
     ///     Mutable backing store for <see cref="Declarations"/>; allows post-construction
     ///     injection of synthetic nodes (e.g., auto-generated views) without requiring a
@@ -36,11 +47,22 @@ public sealed class SysmlWorkspace
     ///     Gets the qualified-name registry mapping fully-qualified names to their declaration nodes.
     /// </summary>
     /// <remarks>
+    ///     Contains every declared element by fully-qualified name, including the standard-library
+    ///     seed (when <see cref="WorkspaceLoader"/> was called with a seed symbol table) as well as
+    ///     user-file declarations — use <see cref="StdlibNames"/> to distinguish the two.
+    ///     <para>
     ///     The property is backed by a mutable <see cref="Dictionary{TKey,TValue}"/> so that
     ///     <see cref="AddDeclaration"/> can inject synthetic nodes after the workspace is constructed.
     ///     The <c>init</c> accessor copies the supplied dictionary so that construction-time
     ///     collection expressions are fully supported.
+    ///     </para>
     /// </remarks>
+    /// <example>
+    /// <code>
+    /// var userDeclarations = workspace.Declarations
+    ///     .Where(kv => !workspace.StdlibNames.Contains(kv.Key));
+    /// </code>
+    /// </example>
     public IReadOnlyDictionary<string, SysmlNode> Declarations
     {
         get => _declarations;
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
index 46cd9fc4..88d97a2d 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/WorkspaceLoader.cs
@@ -2,7 +2,7 @@
 // Licensed under the MIT License.
 
 using DemaConsulting.SysML2Tools.Parser;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Semantic;
 
@@ -18,7 +18,8 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 ///     Always seed the <c>seedSymbolTable</c> parameter with the pre-compiled standard library
 ///     symbol table (<c>StdlibProvider.GetSymbolTable()</c>) unless the caller has a specific
 ///     reason to load user files against an empty namespace; without the stdlib seed, references
-///     to standard-library types (e.g. <c>ScalarValues::Real</c>) fail to resolve.
+///     to standard-library types (e.g. <c>ScalarValues::Real</c>) resolve to unresolved-reference
+///     Warning diagnostics rather than a loaded declaration.
 ///     </para>
 /// </remarks>
 public static class WorkspaceLoader
@@ -41,10 +42,13 @@ public static class WorkspaceLoader
     /// <example>
     /// <code>
     /// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
-    /// var result = await WorkspaceLoader.LoadAsync([tempFile], stdlibTable);
+    /// var result = await WorkspaceLoader.LoadAsync(["model.sysml"], stdlibTable);
+    /// if (result.HasErrors)
+    /// {
+    ///     return; // inspect result.Diagnostics for details
+    /// }
     ///
-    /// Assert.NotNull(result.Workspace);
-    /// Assert.False(result.HasErrors);
+    /// Console.WriteLine($"Loaded {result.Workspace!.Declarations.Count} declaration(s).");
     /// </code>
     /// </example>
     public static async Task<SysmlLoadResult> LoadAsync(
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs b/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
index c10b297e..1c9c8bb9 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/StdlibProvider.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Stdlib;
 
diff --git a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryCommand.cs b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryCommand.cs
index bd800bc8..62b7ac51 100644
--- a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryCommand.cs
+++ b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryCommand.cs
@@ -22,7 +22,7 @@
 using DemaConsulting.SysML2Tools.Cli;
 using DemaConsulting.SysML2Tools.Parser;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 using DemaConsulting.SysML2Tools.Stdlib;
 
 namespace DemaConsulting.SysML2Tools.Query;
diff --git a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryEngine.cs b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryEngine.cs
index 86141775..f5cad75b 100644
--- a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryEngine.cs
+++ b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryEngine.cs
@@ -19,7 +19,7 @@
 // SOFTWARE.
 
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Query;
 
diff --git a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryResultSerializerContext.cs b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryResultSerializerContext.cs
index 390e6341..c859f35a 100644
--- a/src/DemaConsulting.SysML2Tools.Tool/Query/QueryResultSerializerContext.cs
+++ b/src/DemaConsulting.SysML2Tools.Tool/Query/QueryResultSerializerContext.cs
@@ -25,7 +25,7 @@ namespace DemaConsulting.SysML2Tools.Query;
 /// <summary>
 ///     Source-generator context for serializing <see cref="QueryResult"/> to JSON, mirroring
 ///     the AOT-safe source-gen pattern used by
-///     <c>DemaConsulting.SysML2Tools.Semantic.Internal.AstSerializerContext</c> in the Language
+///     <c>DemaConsulting.SysML2Tools.Semantic.Model.AstSerializerContext</c> in the Language
 ///     project.
 /// </summary>
 [JsonSerializable(typeof(QueryResult))]
diff --git a/src/Tools/StdlibGen/Program.cs b/src/Tools/StdlibGen/Program.cs
index 28daf36c..223dc538 100644
--- a/src/Tools/StdlibGen/Program.cs
+++ b/src/Tools/StdlibGen/Program.cs
@@ -6,7 +6,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 // Parse arguments — extracted to keep the top-level program's cognitive complexity within limits
 var (stdlibDir, outputPath) = ParseArgs(args);
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/ActionFlowViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/ActionFlowViewLayoutStrategyTests.cs
index a3c2bfdd..41ceb6f4 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/ActionFlowViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/ActionFlowViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/BrowserAndGridViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/BrowserAndGridViewLayoutStrategyTests.cs
index 3ecb2e31..9c88acdf 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/BrowserAndGridViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/BrowserAndGridViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/GeneralViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/GeneralViewLayoutStrategyTests.cs
index 56a4539a..a02267af 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/GeneralViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/GeneralViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/InterconnectionViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/InterconnectionViewLayoutStrategyTests.cs
index 9e2463db..5d06a2e7 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/InterconnectionViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/InterconnectionViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/SequenceViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/SequenceViewLayoutStrategyTests.cs
index be08e85b..63cfb922 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/SequenceViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/SequenceViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Layout/StateTransitionViewLayoutStrategyTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Layout/StateTransitionViewLayoutStrategyTests.cs
index 07bb86cd..aa24225c 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Layout/StateTransitionViewLayoutStrategyTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Layout/StateTransitionViewLayoutStrategyTests.cs
@@ -7,7 +7,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Layout;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Rendering/DiagramTypeRouterTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Rendering/DiagramTypeRouterTests.cs
index b6a965a4..fa3634d9 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Rendering/DiagramTypeRouterTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Rendering/DiagramTypeRouterTests.cs
@@ -5,7 +5,7 @@
 using DemaConsulting.SysML2Tools.Layout.Internal;
 using DemaConsulting.SysML2Tools.Rendering.Internal;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Rendering;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs
index d76436b4..7bc7f974 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Semantic/AstSerializerTests.cs
@@ -3,7 +3,7 @@
 
 using DemaConsulting.SysML2Tools.Parser;
 using DemaConsulting.SysML2Tools.Semantic;
-using DemaConsulting.SysML2Tools.Semantic.Internal;
+using DemaConsulting.SysML2Tools.Semantic.Model;
 
 namespace DemaConsulting.SysML2Tools.Tests.Semantic;
 
diff --git a/test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs b/test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs
index 37dbb42b..7bf4ff1d 100644
--- a/test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs
+++ b/test/DemaConsulting.SysML2Tools.Tests/Semantic/WorkspaceLoaderTests.cs
@@ -532,10 +532,10 @@ part def Vehicle {
 
             // Assert: the Vehicle definition owns three feature children with the expected typing
             Assert.NotNull(result.Workspace);
-            var vehicle = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+            var vehicle = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
                 result.Workspace!.Declarations["Demo::Vehicle"]);
             var features = vehicle.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlFeatureNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlFeatureNode>()
                 .ToList();
 
             AssertFeature(features, "mass", "attribute", "Real");
@@ -577,10 +577,10 @@ part def Drivetrain {
 
             // Assert: the Drivetrain owns a connection node referencing both parts
             Assert.NotNull(result.Workspace);
-            var drivetrain = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+            var drivetrain = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
                 result.Workspace!.Declarations["Demo::Drivetrain"]);
             var connection = drivetrain.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlConnectionNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlConnectionNode>()
                 .Single();
             Assert.Equal("engine", connection.EndpointA);
             Assert.Equal("gearbox", connection.EndpointB);
@@ -619,16 +619,16 @@ state def Light {
 
             // Assert: the state def owns two state features and one transition
             Assert.NotNull(result.Workspace);
-            var light = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+            var light = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
                 result.Workspace!.Declarations["SM::Light"]);
             var states = light.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlFeatureNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlFeatureNode>()
                 .Where(f => f.FeatureKeyword == "state")
                 .ToList();
             Assert.Equal(2, states.Count);
 
             var transition = light.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlTransitionNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlTransitionNode>()
                 .Single();
             Assert.Equal("stop", transition.Source);
             Assert.Equal("go", transition.Target);
@@ -667,15 +667,15 @@ action def Flow {
 
             // Assert: the action def owns two action features and one succession
             Assert.NotNull(result.Workspace);
-            var flow = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+            var flow = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
                 result.Workspace!.Declarations["AF::Flow"]);
             var actions = flow.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlFeatureNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlFeatureNode>()
                 .Count(f => f.FeatureKeyword == "action");
             Assert.Equal(2, actions);
 
             var succession = flow.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlTransitionNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlTransitionNode>()
                 .Single();
             Assert.Equal("stepA", succession.Source);
             Assert.Equal("stepB", succession.Target);
@@ -713,10 +713,10 @@ part def Protocol {
 
             // Assert: the protocol owns a message connection with the expected endpoints
             Assert.NotNull(result.Workspace);
-            var protocol = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+            var protocol = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
                 result.Workspace!.Declarations["Seq::Protocol"]);
             var message = protocol.Children
-                .OfType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlConnectionNode>()
+                .OfType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlConnectionNode>()
                 .Single(c => c.ConnectionKeyword == "message");
             Assert.Equal("request", message.Name);
             Assert.Equal("client.s", message.EndpointA);
@@ -754,12 +754,12 @@ part def Child specializes Ancestor {}
             Assert.NotNull(result.Workspace);
             var outgoing = result.Workspace!.Index.GetOutgoingEdges("A::Child");
             Assert.Contains(outgoing,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Supertype &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Supertype &&
                      e.TargetQualifiedName == "A::Ancestor");
 
             var incoming = result.Workspace.Index.GetIncomingEdges("A::Ancestor");
             Assert.Contains(incoming,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Supertype &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Supertype &&
                      e.SourceQualifiedName == "A::Child");
         }
         finally
@@ -794,12 +794,12 @@ part def Car {
             Assert.NotNull(result.Workspace);
             var outgoing = result.Workspace!.Index.GetOutgoingEdges("Car::engine");
             Assert.Contains(outgoing,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Typing &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Typing &&
                      e.TargetQualifiedName == "Engine");
 
             var incoming = result.Workspace.Index.GetIncomingEdges("Engine");
             Assert.Contains(incoming,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Typing &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Typing &&
                      e.SourceQualifiedName == "Car::engine");
         }
         finally
@@ -838,7 +838,7 @@ part def X {
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("NonExistentType"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Typing &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Typing &&
                      e.TargetQualifiedName == "NonExistentType");
         }
         finally
@@ -850,7 +850,7 @@ part def X {
     /// <summary>
     ///     A wildcard import (<c>import Other::*;</c>) should be recorded as an <c>Import</c>
     ///     edge whose target is the imported namespace, queryable via
-    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Internal.SemanticIndex"/>'s
+    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Model.SemanticIndex"/>'s
     ///     incoming-edge lookup.
     /// </summary>
     [Fact]
@@ -874,7 +874,7 @@ package Consumer {
             // Assert
             Assert.NotNull(result.Workspace);
             var incoming = result.Workspace!.Index.GetIncomingEdges("Other");
-            Assert.Contains(incoming, e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Import);
+            Assert.Contains(incoming, e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Import);
         }
         finally
         {
@@ -907,7 +907,7 @@ package Consumer {
             // Assert
             Assert.NotNull(result.Workspace);
             var incoming = result.Workspace!.Index.GetIncomingEdges("Other::Thing");
-            Assert.Contains(incoming, e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Import);
+            Assert.Contains(incoming, e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Import);
         }
         finally
         {
@@ -942,7 +942,7 @@ part def Baz specializes Foo {}
             Assert.NotNull(result.Workspace);
             var outgoing = result.Workspace!.Index.GetOutgoingEdges("A::Baz");
             Assert.Contains(outgoing,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Supertype &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Supertype &&
                      e.TargetQualifiedName == "A::Foo");
         }
         finally
@@ -1020,23 +1020,23 @@ part def Gadget specializes Ancestor {
 
             // Supertype edge, both directions
             Assert.Contains(index.GetOutgoingEdges("App::Gadget"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Supertype &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Supertype &&
                      e.TargetQualifiedName == "Lib::Ancestor");
             Assert.Contains(index.GetIncomingEdges("Lib::Ancestor"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Supertype &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Supertype &&
                      e.SourceQualifiedName == "App::Gadget");
 
             // Typing edge, both directions
             Assert.Contains(index.GetOutgoingEdges("App::Gadget::core"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Typing &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Typing &&
                      e.TargetQualifiedName == "Lib::Widget");
             Assert.Contains(index.GetIncomingEdges("Lib::Widget"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Typing &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Typing &&
                      e.SourceQualifiedName == "App::Gadget::core");
 
             // Import edge, incoming direction (anonymous import node has no source)
             Assert.Contains(index.GetIncomingEdges("Lib"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Import &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Import &&
                      e.SourceQualifiedName == null);
         }
         finally
@@ -1074,7 +1074,7 @@ part def Q {}
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy &&
                      e.SourceQualifiedName == "P::subj" &&
                      e.TargetQualifiedName == "P::req");
         }
@@ -1113,7 +1113,7 @@ package P {
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("nonExistentSubject"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy);
         }
         finally
         {
@@ -1150,7 +1150,7 @@ part def Q {}
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("nonExistentReq"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy);
         }
         finally
         {
@@ -1192,7 +1192,7 @@ part def Q {
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("container.sub"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy);
         }
         finally
         {
@@ -1230,7 +1230,7 @@ requirement outer {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify &&
                      e.SourceQualifiedName == "P::outer" &&
                      e.TargetQualifiedName == "P::req");
         }
@@ -1268,7 +1268,7 @@ requirement outer {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify &&
                      e.SourceQualifiedName == "P::outer" &&
                      e.TargetQualifiedName == "P::R");
         }
@@ -1310,7 +1310,7 @@ objective obj {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify &&
                      e.SourceQualifiedName == "P::C" &&
                      e.TargetQualifiedName == "P::R");
         }
@@ -1351,7 +1351,7 @@ requirement outer {
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("nonExistentReq"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify);
         }
         finally
         {
@@ -1387,7 +1387,7 @@ part def Q {}
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Allocate &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Allocate &&
                      e.SourceQualifiedName == "P::a" &&
                      e.TargetQualifiedName == "P::b");
         }
@@ -1426,7 +1426,7 @@ part def Q {}
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("nonExistentEnd"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Allocate);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Allocate);
         }
         finally
         {
@@ -1476,26 +1476,26 @@ objective obj {
 
             // Satisfy edge, both directions
             Assert.Contains(index.GetOutgoingEdges("P::subj"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy &&
                      e.TargetQualifiedName == "P::req");
             Assert.Contains(index.GetIncomingEdges("P::req"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy &&
                      e.SourceQualifiedName == "P::subj");
 
             // Verify edge, both directions
             Assert.Contains(index.GetOutgoingEdges("P::C"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify &&
                      e.TargetQualifiedName == "P::R");
             Assert.Contains(index.GetIncomingEdges("P::R"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify &&
                      e.SourceQualifiedName == "P::C");
 
             // Allocate edge, both directions
             Assert.Contains(index.GetOutgoingEdges("P::a"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Allocate &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Allocate &&
                      e.TargetQualifiedName == "P::b");
             Assert.Contains(index.GetIncomingEdges("P::b"),
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Allocate &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Allocate &&
                      e.SourceQualifiedName == "P::a");
         }
         finally
@@ -1532,7 +1532,7 @@ part def Q {}
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::a" &&
                      e.TargetQualifiedName == "P::b");
         }
@@ -1577,7 +1577,7 @@ part transmission {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::vehicle::engine::fuelPort" &&
                      e.TargetQualifiedName == "P::vehicle::transmission::input");
         }
@@ -1622,7 +1622,7 @@ part vehicle {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::Engine::fuelCmdPort" &&
                      e.TargetQualifiedName == "P::Transmission::input");
         }
@@ -1667,7 +1667,7 @@ part rearAxle {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::HalfAxle::axleToWheelPort" &&
                      e.TargetQualifiedName == "P::Wheel::wheelToAxlePort");
         }
@@ -1711,7 +1711,7 @@ part def Wheel {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::AxleAssembly::shaftPort" &&
                      e.TargetQualifiedName == "P::Wheel::wheelToAxlePort");
         }
@@ -1755,7 +1755,7 @@ part def Transmission {}
                 d => d.Severity == DemaConsulting.SysML2Tools.Parser.DiagnosticSeverity.Warning &&
                      d.Message.Contains("transmission.nonExistentPort"));
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect);
         }
         finally
         {
@@ -1791,7 +1791,7 @@ part def Q {}
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect &&
                      e.SourceQualifiedName == "P::a" &&
                      e.TargetQualifiedName == "P::b");
         }
@@ -1829,7 +1829,7 @@ state def Behavior {
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.Contains(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Transition &&
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Transition &&
                      e.SourceQualifiedName == "P::Behavior::start" &&
                      e.TargetQualifiedName == "P::Behavior::off");
         }
@@ -1870,7 +1870,7 @@ accept Signal via requestPort
             // Assert
             Assert.NotNull(result.Workspace);
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Transition);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Transition);
         }
         finally
         {
@@ -1913,7 +1913,7 @@ part def Q {}
             var result = await loadTask;
             Assert.NotNull(result.Workspace);
             Assert.DoesNotContain(result.Workspace!.Index.AllEdges,
-                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect);
+                e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect);
         }
         finally
         {
@@ -1949,7 +1949,7 @@ public async Task WorkspaceLoader_LoadAsync_ConnectionsExampleFixture_RecordsCon
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect);
     }
 
     /// <summary>
@@ -1982,7 +1982,7 @@ public async Task WorkspaceLoader_LoadAsync_2aPartsInterconnectionFixture_Record
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect);
     }
 
     /// <summary>
@@ -2015,7 +2015,7 @@ public async Task WorkspaceLoader_LoadAsync_2cPartsInterconnectionFixture_Record
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Connect);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Connect);
     }
 
     /// <summary>
@@ -2047,7 +2047,7 @@ public async Task WorkspaceLoader_LoadAsync_StateDefinitionExampleFixture_Record
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Transition);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Transition);
     }
 
     /// <summary>
@@ -2081,7 +2081,7 @@ public async Task WorkspaceLoader_LoadAsync_RequirementSatisfactionFixture_Recor
         // pinned, since the fixture spans multiple files and packages)
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy);
     }
 
     /// <summary>
@@ -2113,7 +2113,7 @@ public async Task WorkspaceLoader_LoadAsync_8RequirementsFixture_RecordsSatisfyE
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Satisfy);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Satisfy);
     }
 
     /// <summary>
@@ -2145,7 +2145,7 @@ public async Task WorkspaceLoader_LoadAsync_12bAllocationFixture_RecordsAllocate
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Allocate);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Allocate);
     }
 
     /// <summary>
@@ -2179,12 +2179,12 @@ public async Task WorkspaceLoader_LoadAsync_9VerificationSimplifiedFixture_Recor
         // Assert
         Assert.NotNull(result.Workspace);
         Assert.Contains(result.Workspace!.Index.AllEdges,
-            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Internal.SysmlEdgeKind.Verify);
+            e => e.Kind == DemaConsulting.SysML2Tools.Semantic.Model.SysmlEdgeKind.Verify);
     }
 
     /// <summary>
     ///     An element with a single <c>comment</c> member and no <c>doc</c> captures one
-    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Comment"/>
+    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Comment"/>
     ///     annotation and no others.
     /// </summary>
     [Fact]
@@ -2208,7 +2208,7 @@ package P {
             Assert.NotNull(result.Workspace);
             var package = result.Workspace!.Declarations["P"];
             var annotation = Assert.Single(package.Annotations);
-            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Comment, annotation.Kind);
+            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Comment, annotation.Kind);
             Assert.Equal(" a note about P ", annotation.Text);
         }
         finally
@@ -2219,7 +2219,7 @@ package P {
 
     /// <summary>
     ///     An element with a single <c>doc</c> member and no <c>comment</c> captures one
-    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Documentation"/>
+    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Documentation"/>
     ///     annotation and no others.
     /// </summary>
     [Fact]
@@ -2243,7 +2243,7 @@ package P {
             Assert.NotNull(result.Workspace);
             var package = result.Workspace!.Declarations["P"];
             var annotation = Assert.Single(package.Annotations);
-            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Documentation, annotation.Kind);
+            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Documentation, annotation.Kind);
             Assert.Equal(" documentation about P ", annotation.Text);
         }
         finally
@@ -2278,9 +2278,9 @@ package P {
             Assert.NotNull(result.Workspace);
             var package = result.Workspace!.Declarations["P"];
             Assert.Equal(2, package.Annotations.Count);
-            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Comment, package.Annotations[0].Kind);
+            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Comment, package.Annotations[0].Kind);
             Assert.Equal(" first: a comment ", package.Annotations[0].Text);
-            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Documentation, package.Annotations[1].Kind);
+            Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Documentation, package.Annotations[1].Kind);
             Assert.Equal(" second: a doc ", package.Annotations[1].Text);
         }
         finally
@@ -2291,7 +2291,7 @@ package P {
 
     /// <summary>
     ///     An element with no <c>comment</c>/<c>doc</c> members has an empty (never null)
-    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Internal.SysmlNode.Annotations"/> list.
+    ///     <see cref="DemaConsulting.SysML2Tools.Semantic.Model.SysmlNode.Annotations"/> list.
     /// </summary>
     [Fact]
     public async Task WorkspaceLoader_LoadAsync_NoAnnotations_AnnotationsIsEmptyNotNull()
@@ -2379,18 +2379,18 @@ public async Task WorkspaceLoader_LoadAsync_DocumentationExampleFixture_Captures
 
         // Assert — package-level doc
         Assert.NotNull(result.Workspace);
-        var package = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlPackageNode>(
+        var package = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlPackageNode>(
             result.Workspace!.Declarations["'Documentation Example'"]);
         var packageDoc = Assert.Single(package.Annotations);
-        Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Documentation, packageDoc.Kind);
+        Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Documentation, packageDoc.Kind);
         Assert.Contains("This is documentation of the owning", packageDoc.Text);
         Assert.Contains("package.", packageDoc.Text);
 
         // Assert — part-def-level named doc
-        var automobile = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(
+        var automobile = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(
             result.Workspace!.Declarations["'Documentation Example'::Automobile"]);
         var automobileDoc = Assert.Single(automobile.Annotations);
-        Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Internal.SysmlAnnotationKind.Documentation, automobileDoc.Kind);
+        Assert.Equal(DemaConsulting.SysML2Tools.Semantic.Model.SysmlAnnotationKind.Documentation, automobileDoc.Kind);
         Assert.Equal(" This documentation of Automobile. ", automobileDoc.Text);
     }
 
@@ -2415,7 +2415,7 @@ public async Task WorkspaceLoader_LoadAsync_DocumentationExampleFixture_Captures
 
     /// <summary>Asserts that a feature with the given name has the expected keyword and typing.</summary>
     private static void AssertFeature(
-        IEnumerable<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlFeatureNode> features,
+        IEnumerable<DemaConsulting.SysML2Tools.Semantic.Model.SysmlFeatureNode> features,
         string name,
         string keyword,
         string typing)
@@ -2430,7 +2430,7 @@ private static void AssertFeature(
     private static void AssertKeyword(SysmlWorkspace workspace, string qualifiedName, string expectedKeyword)
     {
         Assert.True(workspace.Declarations.TryGetValue(qualifiedName, out var node), $"Missing {qualifiedName}");
-        var def = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Internal.SysmlDefinitionNode>(node);
+        var def = Assert.IsType<DemaConsulting.SysML2Tools.Semantic.Model.SysmlDefinitionNode>(node);
         Assert.Equal(expectedKeyword, def.DefinitionKeyword);
     }
 }

From 42c8b2379344bb8c2b10c350cc5f8c0586bc06d6 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 10:14:45 -0400
Subject: [PATCH 07/13] docs: fix stale 'internal implementation' label for
 Semantic/Model folder

The rename from Semantic/Internal to Semantic/Model was specifically because
these types (SysmlNode, SemanticIndex, SymbolTable, etc.) are public API, not
internal implementation. The folder-layout description still called them
'internal implementation' after the rename, reintroducing the same
contradiction the rename was meant to fix.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/design/introduction.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/design/introduction.md b/docs/design/introduction.md
index 577fcfad..320e3b2d 100644
--- a/docs/design/introduction.md
+++ b/docs/design/introduction.md
@@ -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
-      - **Model/** — 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

From ff8f0eda11a98f458f68508499c9ab7a59457ea8 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 10:23:53 -0400
Subject: [PATCH 08/13] docs: correct stale doc comments in SysmlLoadResult and
 SysmlNode

- Workspace param doc now states it is always non-null (matches WorkspaceLoader.LoadAsync and the property's own remarks), instead of the previous incorrect 'or null if loading failed entirely'.
- Annotations remarks now describe only current shipped behavior in present tense, removing sprint-planning language ('deferred to a future unit', 'not yet captured').
---
 .../Semantic/Model/SysmlNode.cs                           | 8 +++-----
 .../Semantic/SysmlLoadResult.cs                           | 5 ++++-
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
index 6853e69b..008aa7ff 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/Model/SysmlNode.cs
@@ -87,12 +87,10 @@ public abstract class SysmlNode
     ///     members nested directly in this element's body.
     /// </summary>
     /// <remarks>
-    ///     An annotation with an explicit <c>about X</c> target is still attached to its
-    ///     lexically enclosing node rather than to the referenced element <c>X</c>; resolving
-    ///     explicit <c>about</c> targets is deferred to a future unit. Comments/docs nested
+    ///     An annotation with an explicit <c>about X</c> target is attached to its lexically
+    ///     enclosing node rather than to the referenced element <c>X</c>. Comments/docs nested
     ///     inside a relationship body (e.g. <c>alias Car for Automobile { /* ... */ }</c>) are
-    ///     also not yet captured, since no <see cref="AstBuilder"/> visitor currently collects
-    ///     relationship bodies.
+    ///     not captured, since no <see cref="AstBuilder"/> visitor collects relationship bodies.
     /// </remarks>
     public IReadOnlyList<SysmlAnnotation> Annotations { get; init; } = Array.Empty<SysmlAnnotation>();
 }
diff --git a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
index 9afc610c..f598a36a 100644
--- a/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
+++ b/src/DemaConsulting.SysML2Tools.Language/Semantic/SysmlLoadResult.cs
@@ -8,7 +8,10 @@ namespace DemaConsulting.SysML2Tools.Semantic;
 /// <summary>
 ///     Result of loading a SysML/KerML workspace including semantic analysis.
 /// </summary>
-/// <param name="Workspace">The semantic workspace, or null if loading failed entirely.</param>
+/// <param name="Workspace">
+///     The semantic workspace. Always non-null when returned by <see cref="WorkspaceLoader.LoadAsync"/>;
+///     see the property's <c>remarks</c> below for details.
+/// </param>
 /// <param name="Diagnostics">All diagnostics (parse errors, semantic warnings) from the load operation.</param>
 /// <remarks>
 ///     <see cref="Workspace"/> is non-null for every result returned by

From 2f77dc975f955df2c49c44760ccecc7d4734e138 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 10:34:18 -0400
Subject: [PATCH 09/13] docs: remove sprint-planning language from design docs
 (quality retry 2)

Follow-up to clean-room review fixes: the previous retry cycle removed
'deferred to a future unit'/'added in later units' language from XML
doc comments (SysmlLoadResult.cs, SysmlNode.cs) but missed the same
phrasing duplicated in the corresponding design documentation pages
under docs/design/sysml2-tools-language/semantic/internal/. Rewritten
to describe current shipped behavior neutrally, consistent with the
corrected source doc comments.
---
 .../semantic/internal/reference-resolver.md                 | 4 ++--
 .../semantic/internal/sysml-annotation.md                   | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md b/docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md
index f55b738f..578b2fca 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md
@@ -92,8 +92,8 @@ walk always terminates.
 
 ##### Scope Boundary (Feature-Chain Resolution)
 
-- **`SysmlSatisfyNode` dotted subjects remain unresolved** — unchanged from unit 3; extending
-  chain resolution to `satisfy` subjects is left for a future unit.
+- **`SysmlSatisfyNode` dotted subjects remain unresolved** — unchanged from unit 3; chain
+  resolution is not currently extended to `satisfy` subjects.
 - **`"allocation"`-keyword endpoints remain single-segment-only** — unchanged from unit 3.
 - **Redefinition/subsetting compatibility is not validated** — a chain segment is matched by
   `Name` only; `:>>`/`:>`/`subsets` compatibility between the redefining and redefined feature is
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md b/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
index 4720c3cf..c622773f 100644
--- a/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
+++ b/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
@@ -38,9 +38,9 @@ N/A — `SysmlAnnotation` is a pure data record with no logic or validation.
 
 ##### Known Limitations
 
-- An annotating element with an explicit `about X` target is still attached to its lexically
-  enclosing node rather than to the referenced element `X`; resolving explicit `about` targets
-  is deferred to a future unit.
+- An annotating element with an explicit `about X` target is attached to its lexically
+  enclosing node rather than to the referenced element `X`; explicit `about` targets are not
+  currently resolved.
 - Comments/docs nested inside a relationship body (e.g.
   `alias Car for Automobile { /* ... */ }`) are not captured, since no `AstBuilder` visitor
   currently collects relationship bodies (`relationshipBody`).

From a6467dbb2c517d65f25f722581bce89775072b1b Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 13:02:36 -0400
Subject: [PATCH 10/13] docs: rename semantic 'internal' subsystem
 docs/reqstream to 'model' (public API, not internal)

Mirrors the earlier Semantic.Internal -> Semantic.Model C# namespace rename.
The folder groups the public semantic model types (SysmlNode/subtypes, SysmlEdge,
SemanticIndex, SysmlAnnotation, SymbolTable) together with a few internal
build/resolve helpers (AstBuilder, ReferenceResolver, SupertypeWalker) - calling
the whole subsystem 'Internal' was misleading. This rename completes the
migration by renaming the parallel design, verification, and reqstream doc
trees from semantic/internal to semantic/model, fixing subsystem-level heading
and prose ('Semantic Internal Subsystem' -> 'Semantic Model Subsystem'), and
renaming the '-Internal-' requirement ID token to '-Model-' across the affected
reqstream YAML files. Also adds the previously-missing semantic-index.md,
sysml-annotation.md, and sysml-edge.md entries to design/definition.yaml and
verification/definition.yaml input-files lists.
---
 docs/design/definition.yaml                     | 17 ++++++++++-------
 docs/design/introduction.md                     |  2 +-
 docs/design/sysml2-tools-language/semantic.md   |  8 ++++----
 .../semantic/{internal.md => model.md}          |  6 +++---
 .../semantic/{internal => model}/ast-builder.md |  0
 .../{internal => model}/reference-resolver.md   |  0
 .../{internal => model}/semantic-index.md       |  0
 .../{internal => model}/supertype-walker.md     |  0
 .../{internal => model}/symbol-table.md         |  0
 .../{internal => model}/sysml-annotation.md     |  0
 .../semantic/{internal => model}/sysml-edge.md  |  0
 .../semantic/{internal => model}/sysml-node.md  |  0
 .../semantic/{internal.yaml => model.yaml}      | 14 +++++++-------
 .../{internal => model}/ast-builder.yaml        |  8 ++++----
 .../{internal => model}/reference-resolver.yaml |  6 +++---
 .../{internal => model}/supertype-walker.yaml   |  4 ++--
 .../{internal => model}/symbol-table.yaml       |  6 +++---
 .../{internal => model}/sysml-node.yaml         |  4 ++--
 docs/verification/definition.yaml               | 17 ++++++++++-------
 .../semantic/{internal.md => model.md}          |  2 +-
 .../semantic/{internal => model}/ast-builder.md |  0
 .../{internal => model}/reference-resolver.md   |  0
 .../{internal => model}/semantic-index.md       |  0
 .../{internal => model}/supertype-walker.md     |  0
 .../{internal => model}/symbol-table.md         |  0
 .../{internal => model}/sysml-annotation.md     |  0
 .../semantic/{internal => model}/sysml-edge.md  |  0
 .../semantic/{internal => model}/sysml-node.md  |  0
 requirements.yaml                               | 12 ++++++------
 29 files changed, 56 insertions(+), 50 deletions(-)
 rename docs/design/sysml2-tools-language/semantic/{internal.md => model.md} (92%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/ast-builder.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/reference-resolver.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/semantic-index.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/supertype-walker.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/symbol-table.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/sysml-annotation.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/sysml-edge.md (100%)
 rename docs/design/sysml2-tools-language/semantic/{internal => model}/sysml-node.md (100%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal.yaml => model.yaml} (79%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal => model}/ast-builder.yaml (85%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal => model}/reference-resolver.yaml (81%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal => model}/supertype-walker.yaml (80%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal => model}/symbol-table.yaml (84%)
 rename docs/reqstream/sysml2-tools-language/semantic/{internal => model}/sysml-node.yaml (89%)
 rename docs/verification/sysml2-tools-language/semantic/{internal.md => model.md} (98%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/ast-builder.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/reference-resolver.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/semantic-index.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/supertype-walker.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/symbol-table.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/sysml-annotation.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/sysml-edge.md (100%)
 rename docs/verification/sysml2-tools-language/semantic/{internal => model}/sysml-node.md (100%)

diff --git a/docs/design/definition.yaml b/docs/design/definition.yaml
index fc512b67..643bb74e 100644
--- a/docs/design/definition.yaml
+++ b/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
diff --git a/docs/design/introduction.md b/docs/design/introduction.md
index 320e3b2d..37569cf3 100644
--- a/docs/design/introduction.md
+++ b/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
diff --git a/docs/design/sysml2-tools-language/semantic.md b/docs/design/sysml2-tools-language/semantic.md
index 989f3c72..ec118328 100644
--- a/docs/design/sysml2-tools-language/semantic.md
+++ b/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
 
diff --git a/docs/design/sysml2-tools-language/semantic/internal.md b/docs/design/sysml2-tools-language/semantic/model.md
similarity index 92%
rename from docs/design/sysml2-tools-language/semantic/internal.md
rename to docs/design/sysml2-tools-language/semantic/model.md
index b643f994..bf2d1264 100644
--- a/docs/design/sysml2-tools-language/semantic/internal.md
+++ b/docs/design/sysml2-tools-language/semantic/model.md
@@ -1,9 +1,9 @@
-### Semantic Internal Subsystem
+### Semantic Model Subsystem
 
 #### Overview
 
-The Semantic Internal subsystem provides the implementation details of the semantic loading pipeline.
-It contains seven units: `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
+The Semantic Model subsystem provides the semantic model types (public) and the internal
+build/resolve implementation of the semantic loading pipeline. It contains seven units: `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
 `SysmlEdge`, `SemanticIndex`, and `SysmlAnnotation`.
 
 #### Interfaces
diff --git a/docs/design/sysml2-tools-language/semantic/internal/ast-builder.md b/docs/design/sysml2-tools-language/semantic/model/ast-builder.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/ast-builder.md
rename to docs/design/sysml2-tools-language/semantic/model/ast-builder.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md b/docs/design/sysml2-tools-language/semantic/model/reference-resolver.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/reference-resolver.md
rename to docs/design/sysml2-tools-language/semantic/model/reference-resolver.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/semantic-index.md b/docs/design/sysml2-tools-language/semantic/model/semantic-index.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/semantic-index.md
rename to docs/design/sysml2-tools-language/semantic/model/semantic-index.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/supertype-walker.md b/docs/design/sysml2-tools-language/semantic/model/supertype-walker.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/supertype-walker.md
rename to docs/design/sysml2-tools-language/semantic/model/supertype-walker.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/symbol-table.md b/docs/design/sysml2-tools-language/semantic/model/symbol-table.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/symbol-table.md
rename to docs/design/sysml2-tools-language/semantic/model/symbol-table.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md b/docs/design/sysml2-tools-language/semantic/model/sysml-annotation.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/sysml-annotation.md
rename to docs/design/sysml2-tools-language/semantic/model/sysml-annotation.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md b/docs/design/sysml2-tools-language/semantic/model/sysml-edge.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/sysml-edge.md
rename to docs/design/sysml2-tools-language/semantic/model/sysml-edge.md
diff --git a/docs/design/sysml2-tools-language/semantic/internal/sysml-node.md b/docs/design/sysml2-tools-language/semantic/model/sysml-node.md
similarity index 100%
rename from docs/design/sysml2-tools-language/semantic/internal/sysml-node.md
rename to docs/design/sysml2-tools-language/semantic/model/sysml-node.md
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal.yaml b/docs/reqstream/sysml2-tools-language/semantic/model.yaml
similarity index 79%
rename from docs/reqstream/sysml2-tools-language/semantic/internal.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model.yaml
index a5df5bf4..f3a41a5c 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model.yaml
@@ -1,14 +1,14 @@
 ---
-# Semantic Internal Subsystem Requirements
+# Semantic Model Subsystem Requirements
 #
 # PURPOSE:
-# - Define requirements for the internal implementation of the Semantic subsystem
-# - Internal components: AstBuilder, SymbolTable, ReferenceResolver, SupertypeWalker
+# - Define requirements for the Semantic Model subsystem (AstBuilder, SymbolTable,
+#   ReferenceResolver, SupertypeWalker)
 
 sections:
-  - title: Semantic Internal Subsystem Requirements
+  - title: Semantic Model Subsystem Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-AstBuild
+      - id: SysML2Tools-Language-Semantic-Model-AstBuild
         title: >-
           The internal semantic components shall build an AST from the ANTLR4 CST and
           register all named elements in the symbol table.
@@ -20,7 +20,7 @@ sections:
           - WorkspaceLoader_LoadAsync_NestedPackages_RegistersQualifiedNames
           - WorkspaceLoader_LoadAsync_PartDef_RegistersDefinition
 
-      - id: SysML2Tools-Language-Semantic-Internal-ReferenceResolution
+      - id: SysML2Tools-Language-Semantic-Model-ReferenceResolution
         title: >-
           The ReferenceResolver shall resolve supertype references against the symbol table
           and produce Warning diagnostics for any unresolved names.
@@ -32,7 +32,7 @@ sections:
           - WorkspaceLoader_LoadAsync_UnresolvedReference_ProducesWarning
           - WorkspaceLoader_LoadAsync_SpecializesChain_Registered
 
-      - id: SysML2Tools-Language-Semantic-Internal-SupertypeWalking
+      - id: SysML2Tools-Language-Semantic-Model-SupertypeWalking
         title: >-
           The SupertypeWalker shall traverse specialization chains and detect cyclic
           specialization, producing a Warning diagnostic for each cycle.
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal/ast-builder.yaml b/docs/reqstream/sysml2-tools-language/semantic/model/ast-builder.yaml
similarity index 85%
rename from docs/reqstream/sysml2-tools-language/semantic/internal/ast-builder.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model/ast-builder.yaml
index fbe5321a..30d5741d 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal/ast-builder.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model/ast-builder.yaml
@@ -2,12 +2,12 @@
 # AstBuilder Requirements
 #
 # PURPOSE:
-# - Define requirements for the AstBuilder internal unit
+# - Define requirements for the AstBuilder unit (Semantic Model subsystem)
 
 sections:
   - title: AstBuilder Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-AstBuilder-Build
+      - id: SysML2Tools-Language-Semantic-Model-AstBuilder-Build
         title: >-
           AstBuilder shall visit the ANTLR4 CST produced by SysMLv2Parser and return a
           SysmlPackageNode representing the root namespace.
@@ -17,7 +17,7 @@ sections:
         tests:
           - WorkspaceLoader_LoadAsync_SinglePackage_RegistersDeclaration
 
-      - id: SysML2Tools-Language-Semantic-Internal-AstBuilder-QualifiedNames
+      - id: SysML2Tools-Language-Semantic-Model-AstBuilder-QualifiedNames
         title: >-
           AstBuilder shall compute fully-qualified names by joining ancestor names with
           the "::" separator as it descends into nested namespaces.
@@ -28,7 +28,7 @@ sections:
           - WorkspaceLoader_LoadAsync_NestedPackages_RegistersQualifiedNames
           - WorkspaceLoader_LoadAsync_PartDef_RegistersDefinition
 
-      - id: SysML2Tools-Language-Semantic-Internal-AstBuilder-Supertypes
+      - id: SysML2Tools-Language-Semantic-Model-AstBuilder-Supertypes
         title: >-
           AstBuilder shall extract supertype qualified names from subclassification and
           specialization parts and attach them to the corresponding AST node.
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal/reference-resolver.yaml b/docs/reqstream/sysml2-tools-language/semantic/model/reference-resolver.yaml
similarity index 81%
rename from docs/reqstream/sysml2-tools-language/semantic/internal/reference-resolver.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model/reference-resolver.yaml
index 45a7fdf6..859027a6 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal/reference-resolver.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model/reference-resolver.yaml
@@ -2,12 +2,12 @@
 # ReferenceResolver Requirements
 #
 # PURPOSE:
-# - Define requirements for the ReferenceResolver internal unit
+# - Define requirements for the ReferenceResolver unit (Semantic Model subsystem)
 
 sections:
   - title: ReferenceResolver Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-ReferenceResolver-Resolve
+      - id: SysML2Tools-Language-Semantic-Model-ReferenceResolver-Resolve
         title: >-
           ReferenceResolver.ResolveAll shall check each supertype name referenced by
           AST nodes against the symbol table and produce a Warning for any unresolved name.
@@ -17,7 +17,7 @@ sections:
         tests:
           - WorkspaceLoader_LoadAsync_UnresolvedReference_ProducesWarning
 
-      - id: SysML2Tools-Language-Semantic-Internal-ReferenceResolver-CircularImport
+      - id: SysML2Tools-Language-Semantic-Model-ReferenceResolver-CircularImport
         title: >-
           ReferenceResolver.ResolveAll shall detect circular import chains in the import
           graph and produce a Warning diagnostic for each detected cycle.
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal/supertype-walker.yaml b/docs/reqstream/sysml2-tools-language/semantic/model/supertype-walker.yaml
similarity index 80%
rename from docs/reqstream/sysml2-tools-language/semantic/internal/supertype-walker.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model/supertype-walker.yaml
index 7d289a4e..53d86566 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal/supertype-walker.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model/supertype-walker.yaml
@@ -2,12 +2,12 @@
 # SupertypeWalker Requirements
 #
 # PURPOSE:
-# - Define requirements for the SupertypeWalker internal unit
+# - Define requirements for the SupertypeWalker unit (Semantic Model subsystem)
 
 sections:
   - title: SupertypeWalker Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-SupertypeWalker-Walk
+      - id: SysML2Tools-Language-Semantic-Model-SupertypeWalker-Walk
         title: >-
           SupertypeWalker.WalkAll shall traverse the specialization chains of all
           registered symbols and detect cyclic specialization.
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal/symbol-table.yaml b/docs/reqstream/sysml2-tools-language/semantic/model/symbol-table.yaml
similarity index 84%
rename from docs/reqstream/sysml2-tools-language/semantic/internal/symbol-table.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model/symbol-table.yaml
index aea305a5..0022d1cd 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal/symbol-table.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model/symbol-table.yaml
@@ -2,12 +2,12 @@
 # SymbolTable Requirements
 #
 # PURPOSE:
-# - Define requirements for the SymbolTable internal unit
+# - Define requirements for the SymbolTable unit (Semantic Model subsystem)
 
 sections:
   - title: SymbolTable Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-SymbolTable-Register
+      - id: SysML2Tools-Language-Semantic-Model-SymbolTable-Register
         title: >-
           SymbolTable.RegisterAll shall recursively register all AST nodes with a non-null,
           non-empty QualifiedName into the symbol dictionary, keyed by qualified name.
@@ -18,7 +18,7 @@ sections:
           - WorkspaceLoader_LoadAsync_SinglePackage_RegistersDeclaration
           - WorkspaceLoader_LoadAsync_NestedPackages_RegistersQualifiedNames
 
-      - id: SysML2Tools-Language-Semantic-Internal-SymbolTable-Lookup
+      - id: SysML2Tools-Language-Semantic-Model-SymbolTable-Lookup
         title: >-
           SymbolTable.Lookup shall return the registered node for a given qualified name,
           or null if the name is not registered.
diff --git a/docs/reqstream/sysml2-tools-language/semantic/internal/sysml-node.yaml b/docs/reqstream/sysml2-tools-language/semantic/model/sysml-node.yaml
similarity index 89%
rename from docs/reqstream/sysml2-tools-language/semantic/internal/sysml-node.yaml
rename to docs/reqstream/sysml2-tools-language/semantic/model/sysml-node.yaml
index 414479f3..2ea9204d 100644
--- a/docs/reqstream/sysml2-tools-language/semantic/internal/sysml-node.yaml
+++ b/docs/reqstream/sysml2-tools-language/semantic/model/sysml-node.yaml
@@ -7,7 +7,7 @@
 sections:
   - title: SysmlNode Requirements
     requirements:
-      - id: SysML2Tools-Language-Semantic-Internal-SysmlNode-Hierarchy
+      - id: SysML2Tools-Language-Semantic-Model-SysmlNode-Hierarchy
         title: >-
           SysmlNode shall define an abstract base class with Name, QualifiedName, Children,
           SupertypeNames, and ImportedNames properties shared by all AST node types.
@@ -17,7 +17,7 @@ sections:
         tests:
           - WorkspaceLoader_LoadAsync_SinglePackage_RegistersDeclaration
 
-      - id: SysML2Tools-Language-Semantic-Internal-SysmlNode-Types
+      - id: SysML2Tools-Language-Semantic-Model-SysmlNode-Types
         title: >-
           The SysmlNode hierarchy shall include SysmlPackageNode, SysmlDefinitionNode,
           SysmlFeatureNode, SysmlImportNode, SysmlViewNode, SysmlViewpointNode,
diff --git a/docs/verification/definition.yaml b/docs/verification/definition.yaml
index 8f335aea..d41ea693 100644
--- a/docs/verification/definition.yaml
+++ b/docs/verification/definition.yaml
@@ -5,7 +5,7 @@ resource-path:
   - docs/verification/sysml2-tools-language/parser
   - docs/verification/sysml2-tools-language/parser/internal
   - docs/verification/sysml2-tools-language/semantic
-  - docs/verification/sysml2-tools-language/semantic/internal
+  - docs/verification/sysml2-tools-language/semantic/model
   - docs/verification/sysml2-tools-core
   - docs/verification/sysml2-tools-core/layout
   - docs/verification/sysml2-tools-core/layout/internal
@@ -31,12 +31,15 @@ input-files:
   - docs/verification/sysml2-tools-language/semantic/workspace-loader.md
   - docs/verification/sysml2-tools-language/semantic/ast-serializer.md
   - docs/verification/sysml2-tools-language/semantic/ast-deserializer.md
-  - docs/verification/sysml2-tools-language/semantic/internal.md
-  - docs/verification/sysml2-tools-language/semantic/internal/sysml-node.md
-  - docs/verification/sysml2-tools-language/semantic/internal/ast-builder.md
-  - docs/verification/sysml2-tools-language/semantic/internal/symbol-table.md
-  - docs/verification/sysml2-tools-language/semantic/internal/reference-resolver.md
-  - docs/verification/sysml2-tools-language/semantic/internal/supertype-walker.md
+  - docs/verification/sysml2-tools-language/semantic/model.md
+  - docs/verification/sysml2-tools-language/semantic/model/sysml-node.md
+  - docs/verification/sysml2-tools-language/semantic/model/sysml-edge.md
+  - docs/verification/sysml2-tools-language/semantic/model/sysml-annotation.md
+  - docs/verification/sysml2-tools-language/semantic/model/semantic-index.md
+  - docs/verification/sysml2-tools-language/semantic/model/symbol-table.md
+  - docs/verification/sysml2-tools-language/semantic/model/ast-builder.md
+  - docs/verification/sysml2-tools-language/semantic/model/reference-resolver.md
+  - docs/verification/sysml2-tools-language/semantic/model/supertype-walker.md
   - docs/verification/sysml2-tools-stdlib.md
   - docs/verification/sysml2-tools-stdlib/stdlib-provider.md
   - docs/verification/sysml2-tools-core.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal.md b/docs/verification/sysml2-tools-language/semantic/model.md
similarity index 98%
rename from docs/verification/sysml2-tools-language/semantic/internal.md
rename to docs/verification/sysml2-tools-language/semantic/model.md
index 55d9e895..f4a60f47 100644
--- a/docs/verification/sysml2-tools-language/semantic/internal.md
+++ b/docs/verification/sysml2-tools-language/semantic/model.md
@@ -1,4 +1,4 @@
-### Semantic Internal Subsystem Verification
+### Semantic Model Subsystem Verification
 
 #### Verification Approach
 
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/ast-builder.md b/docs/verification/sysml2-tools-language/semantic/model/ast-builder.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/ast-builder.md
rename to docs/verification/sysml2-tools-language/semantic/model/ast-builder.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/reference-resolver.md b/docs/verification/sysml2-tools-language/semantic/model/reference-resolver.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/reference-resolver.md
rename to docs/verification/sysml2-tools-language/semantic/model/reference-resolver.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/semantic-index.md b/docs/verification/sysml2-tools-language/semantic/model/semantic-index.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/semantic-index.md
rename to docs/verification/sysml2-tools-language/semantic/model/semantic-index.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/supertype-walker.md b/docs/verification/sysml2-tools-language/semantic/model/supertype-walker.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/supertype-walker.md
rename to docs/verification/sysml2-tools-language/semantic/model/supertype-walker.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/symbol-table.md b/docs/verification/sysml2-tools-language/semantic/model/symbol-table.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/symbol-table.md
rename to docs/verification/sysml2-tools-language/semantic/model/symbol-table.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/sysml-annotation.md b/docs/verification/sysml2-tools-language/semantic/model/sysml-annotation.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/sysml-annotation.md
rename to docs/verification/sysml2-tools-language/semantic/model/sysml-annotation.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/sysml-edge.md b/docs/verification/sysml2-tools-language/semantic/model/sysml-edge.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/sysml-edge.md
rename to docs/verification/sysml2-tools-language/semantic/model/sysml-edge.md
diff --git a/docs/verification/sysml2-tools-language/semantic/internal/sysml-node.md b/docs/verification/sysml2-tools-language/semantic/model/sysml-node.md
similarity index 100%
rename from docs/verification/sysml2-tools-language/semantic/internal/sysml-node.md
rename to docs/verification/sysml2-tools-language/semantic/model/sysml-node.md
diff --git a/requirements.yaml b/requirements.yaml
index e1548656..77ddb0a4 100644
--- a/requirements.yaml
+++ b/requirements.yaml
@@ -9,12 +9,12 @@ includes:
   - docs/reqstream/sysml2-tools-language/semantic/workspace-loader.yaml
   - docs/reqstream/sysml2-tools-language/semantic/ast-serializer.yaml
   - docs/reqstream/sysml2-tools-language/semantic/ast-deserializer.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal/sysml-node.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal/ast-builder.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal/symbol-table.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal/reference-resolver.yaml
-  - docs/reqstream/sysml2-tools-language/semantic/internal/supertype-walker.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model/sysml-node.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model/ast-builder.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model/symbol-table.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model/reference-resolver.yaml
+  - docs/reqstream/sysml2-tools-language/semantic/model/supertype-walker.yaml
   - docs/reqstream/sysml2-tools-stdlib.yaml
   - docs/reqstream/sysml2-tools-stdlib/stdlib-provider.yaml
   - docs/reqstream/sysml2-tools-core.yaml

From 3bb2c3f5a123e070cae9322b42089e4d6b45bce9 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 13:13:43 -0400
Subject: [PATCH 11/13] build: package Language and Stdlib as independent NuGet
 packages

Split the previous 2-package model (Core, Tool) into a 4-package model
by making Language and Stdlib independently packable:

- DemaConsulting.SysML2Tools.Language and .Stdlib now set IsPackable=true
  with full package metadata (matching Core/Tool conventions) and their
  own ApiMark-generated docs bundled into their own nupkg.
- Core.csproj no longer bundles Language/Stdlib DLLs via PrivateAssets=all
  ProjectReferences; it now uses plain ProjectReferences so dotnet pack
  emits normal <dependency> elements referencing the Language/Stdlib
  packages (transitive resolution via NuGet), matching standard SDK-style
  multi-package repo behavior.
- Removed the CopyLanguageAndStdlibApiDocsToPackage target, the
  MergeApiMarkNamespaceIndex inline RoslynCodeTaskFactory task, and all
  related namespace-index merge/prune logic from Core.csproj -- each
  package now ships only its own docs, eliminating the doc-merge hack.
- Updated README.md and docs/user_guide/introduction.md to describe the
  4-package model instead of the previous 2-package/bundled-docs model.

This is a packaging-only change; runtime behavior is unchanged (441/441
tests pass). Verified via dotnet build/test/pack: dotnet pack now
produces 4 nupkgs (+ 4 snupkgs), Core's nuspec correctly lists
<dependency> entries for Language and Stdlib instead of embedding their
DLLs, and Language/Stdlib's own api/ doc folders are bundled in their
own packages.
---
 README.md                                     |   7 +-
 docs/user_guide/introduction.md               |  12 +-
 .../DemaConsulting.SysML2Tools.Core.csproj    | 138 +-----------------
 ...DemaConsulting.SysML2Tools.Language.csproj |  20 ++-
 .../DemaConsulting.SysML2Tools.Stdlib.csproj  |  20 ++-
 5 files changed, 51 insertions(+), 146 deletions(-)

diff --git a/README.md b/README.md
index 9fcefa04..aac1f2b0 100644
--- a/README.md
+++ b/README.md
@@ -226,12 +226,15 @@ sysml2tools help [lint|render|query [<query-verb>]]
 
 | Package | Description |
 | --- | --- |
+| `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.Core` alone to access
-parsing, semantic model, and layout without pulling in the CLI tool. The `Core` package also
-bundles generated Markdown API reference documentation alongside the assembly.
+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
 
diff --git a/docs/user_guide/introduction.md b/docs/user_guide/introduction.md
index 23178457..5cee0bf1 100644
--- a/docs/user_guide/introduction.md
+++ b/docs/user_guide/introduction.md
@@ -263,18 +263,22 @@ sysml2tools --validate --depth 2
 
 # NuGet Library Packages
 
-SysML2Tools is structured as two NuGet packages. Library consumers can take a dependency
+SysML2Tools is structured as four NuGet packages. Library consumers can take a dependency
 on the core library alone, without pulling in the full CLI tool:
 
 | Package | Contents |
 | --- | --- |
+| `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`, `query`, and `help` commands |
 
 Consumers who need only the parsed semantic model, `LayoutTree`, or rendering interfaces
-take a dependency on `DemaConsulting.SysML2Tools.Core` only. Consumers who need the CLI
-install `DemaConsulting.SysML2Tools.Tool` as a dotnet tool. The `DemaConsulting.SysML2Tools.Core`
-package also bundles generated Markdown API reference documentation alongside the assembly.
+take a dependency on `DemaConsulting.SysML2Tools.Core` only, which automatically pulls in
+`DemaConsulting.SysML2Tools.Language` and `DemaConsulting.SysML2Tools.Stdlib` as NuGet
+dependencies. Consumers who need the CLI install `DemaConsulting.SysML2Tools.Tool` as a
+dotnet tool. Each package ships its own generated Markdown API reference documentation
+alongside its assembly.
 
 # Continuous Compliance
 
diff --git a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
index eac19802..8c08d6e4 100644
--- a/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
+++ b/src/DemaConsulting.SysML2Tools.Core/DemaConsulting.SysML2Tools.Core.csproj
@@ -59,141 +59,15 @@
     <PackageReference Include="DemaConsulting.Rendering.Layout" Version="0.1.0-beta.2" />
   </ItemGroup>
 
-  <!-- Language and Stdlib are internal (IsPackable=false) projects, so their PrivateAssets="all"
-       marking here prevents them from being emitted as NuGet package dependencies. Instead, the
-       CopyProjectReferencesToPackage target below embeds their compiled assemblies directly into
-       this package's lib folder (see docs/design/introduction.md for details). -->
+  <!-- Language and Stdlib are independently packable NuGet packages of their own
+       (DemaConsulting.SysML2Tools.Language, DemaConsulting.SysML2Tools.Stdlib), each bundling
+       their own ApiMark-generated docs. Plain ProjectReferences here let `dotnet pack` emit
+       <dependency> elements for them in this package's nuspec automatically. -->
   <ItemGroup>
-    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Language\DemaConsulting.SysML2Tools.Language.csproj" PrivateAssets="all" />
-    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Stdlib\DemaConsulting.SysML2Tools.Stdlib.csproj" PrivateAssets="all" />
+    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Language\DemaConsulting.SysML2Tools.Language.csproj" />
+    <ProjectReference Include="..\DemaConsulting.SysML2Tools.Stdlib\DemaConsulting.SysML2Tools.Stdlib.csproj" />
   </ItemGroup>
 
-  <!-- Embed the Language and Stdlib assemblies (both IsPackable=false) directly into this
-       package's lib folder, since they cannot be resolved as separate NuGet dependencies. Also
-       embeds their XML doc-comment files alongside the assemblies so Visual Studio IntelliSense
-       resolves doc comments for types re-exported from Language/Stdlib (e.g. WorkspaceLoader,
-       StdlibProvider) when consumed through this package. -->
-  <PropertyGroup>
-    <TargetsForTfmSpecificBuildOutput>$(TargetsForTfmSpecificBuildOutput);CopyProjectReferencesToPackage</TargetsForTfmSpecificBuildOutput>
-  </PropertyGroup>
-  <Target Name="CopyProjectReferencesToPackage" DependsOnTargets="ResolveReferences">
-    <ItemGroup>
-      <BuildOutputInPackage Include="@(ReferencePath)" Condition="'%(ReferencePath.ReferenceSourceTarget)' == 'ProjectReference'" />
-      <_ProjectReferenceXmlDocs Include="@(ReferencePath->'%(RootDir)%(Directory)%(Filename).xml')"
-                                 Condition="'%(ReferencePath.ReferenceSourceTarget)' == 'ProjectReference'
-                                            and Exists('%(ReferencePath.RootDir)%(ReferencePath.Directory)%(ReferencePath.Filename).xml')" />
-      <BuildOutputInPackage Include="@(_ProjectReferenceXmlDocs)" />
-    </ItemGroup>
-  </Target>
-
-  <!-- Inline task used by CopyLanguageAndStdlibApiDocsToPackage (below) to merge the Language's
-       and Stdlib's own namespace-table rows into this project's own generated api.md index, so
-       that the folded-in namespace pages are discoverable/linked from the package's natural
-       entry point instead of being orphaned files in the api/ tree. Written to no-op safely
-       (skip the merge, leave TargetIndexFile unchanged) if the expected table separator or a
-       source file is missing, so a future ApiMark output-format change degrades gracefully
-       rather than breaking the build. -->
-  <UsingTask TaskName="MergeApiMarkNamespaceIndex" TaskFactory="RoslynCodeTaskFactory"
-             AssemblyFile="$(MSBuildToolsPath)\Microsoft.Build.Tasks.Core.dll">
-    <ParameterGroup>
-      <TargetIndexFile ParameterType="System.String" Required="true" />
-      <SourceIndexFiles ParameterType="Microsoft.Build.Framework.ITaskItem[]" Required="true" />
-    </ParameterGroup>
-    <Task>
-      <Using Namespace="System.IO" />
-      <Using Namespace="System.Collections.Generic" />
-      <Code Type="Fragment" Language="cs"><![CDATA[
-        if (!File.Exists(TargetIndexFile))
-        {
-            Log.LogMessage("MergeApiMarkNamespaceIndex: target index file not found, skipping merge: " + TargetIndexFile);
-            return true;
-        }
-
-        var lines = new List<string>(File.ReadAllLines(TargetIndexFile));
-        var separatorIndex = lines.FindIndex(l => l.Trim() == "| --- | --- | --- |");
-        if (separatorIndex < 0)
-        {
-            Log.LogMessage("MergeApiMarkNamespaceIndex: namespace table separator not found, skipping merge: " + TargetIndexFile);
-            return true;
-        }
-
-        var newRows = new List<string>();
-        foreach (var sourceItem in SourceIndexFiles)
-        {
-            var sourceFile = sourceItem.ItemSpec;
-            if (!File.Exists(sourceFile))
-            {
-                continue;
-            }
-
-            foreach (var line in File.ReadAllLines(sourceFile))
-            {
-                if (line.StartsWith("| [", StringComparison.Ordinal))
-                {
-                    newRows.Add(line);
-                }
-            }
-        }
-
-        if (newRows.Count == 0)
-        {
-            Log.LogMessage("MergeApiMarkNamespaceIndex: no namespace rows found in source index files, skipping merge.");
-            return true;
-        }
-
-        lines.InsertRange(separatorIndex + 1, newRows);
-        File.WriteAllLines(TargetIndexFile, lines);
-        Log.LogMessage("MergeApiMarkNamespaceIndex: merged " + newRows.Count + " namespace row(s) into " + TargetIndexFile);
-      ]]></Code>
-    </Task>
-  </UsingTask>
-
-  <!-- Fold the Language and Stdlib projects' ApiMark-generated api/ folders into this package's
-       own api/ folder. Language and Stdlib are IsPackable=false and have no nupkg of their own
-       (see above), so this is the only way their "getting started" namespaces (Semantic, Parser,
-       Stdlib) reach a consumer's browsable API reference docs. Each project's own top-level
-       api.md index (a single-assembly summary table) is intentionally excluded from the copy —
-       it describes only that project's own namespaces and would collide with, or misleadingly
-       duplicate, this project's own api.md index; the per-namespace/per-type Markdown pages
-       (which do not collide, since namespaces differ) are copied as-is. After copying, the
-       MergeApiMarkNamespaceIndex inline task (above) appends Language's and Stdlib's own
-       namespace-table rows into this project's own generated api.md, so that the copied-in
-       namespace pages are linked/discoverable from the package's natural entry point rather than
-       being orphaned files only reachable by browsing the raw api/ folder tree.
-       DependsOnTargets="ResolveReferences" is not required for correctness here (MSBuild already
-       guarantees Language/Stdlib finish building — including their own AfterTargets="Build"
-       ApiMark step — before this project's Build completes, since they are ProjectReferences),
-       but AfterTargets/BeforeTargets below pin this target's ordering relative to ApiMark's own
-       generation and pack-inclusion targets; verified end-to-end with a real `dotnet pack`.
-       The TFM-restriction condition mirrors ApiMark's own GenerateApiMarkDocumentation/
-       _ApiMarkIncludeDocsInPackage targets so this target (copy + index-merge) runs exactly once
-       per pack/build, instead of once per inner per-TFM build (which would otherwise race
-       multiple concurrent copies/merges against the same destination files). -->
-  <Target Name="CopyLanguageAndStdlibApiDocsToPackage"
-          Condition="'$(ApiMarkPackDocs)' == 'true'
-                 and ('$(TargetFrameworks)' == '' or '$(TargetFramework)' == '$(_ApiMarkPackDocsTargetFramework)')"
-          AfterTargets="GenerateApiMarkDocumentation"
-          BeforeTargets="_ApiMarkIncludeDocsInPackage">
-    <ItemGroup>
-      <_LanguageApiDocFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\**\*"
-                            Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\api.md" />
-      <_StdlibApiDocFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\**\*"
-                          Exclude="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\api.md" />
-      <_ApiMarkSourceIndexFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Language\api\api.md" />
-      <_ApiMarkSourceIndexFiles Include="$(MSBuildThisFileDirectory)..\DemaConsulting.SysML2Tools.Stdlib\api\api.md" />
-    </ItemGroup>
-    <Copy SourceFiles="@(_LanguageApiDocFiles)"
-          DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
-          SkipUnchangedFiles="true"
-          Condition="'@(_LanguageApiDocFiles)' != ''" />
-    <Copy SourceFiles="@(_StdlibApiDocFiles)"
-          DestinationFolder="$(ApiMarkOutputDir)\%(RecursiveDir)"
-          SkipUnchangedFiles="true"
-          Condition="'@(_StdlibApiDocFiles)' != ''" />
-    <MergeApiMarkNamespaceIndex TargetIndexFile="$(ApiMarkOutputDir)\api.md"
-                                SourceIndexFiles="@(_ApiMarkSourceIndexFiles)" />
-  </Target>
-
   <ItemGroup>
     <InternalsVisibleTo Include="DemaConsulting.SysML2Tools.Tests" />
   </ItemGroup>
diff --git a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
index 29904826..17476515 100644
--- a/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
+++ b/src/DemaConsulting.SysML2Tools.Language/DemaConsulting.SysML2Tools.Language.csproj
@@ -6,7 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 
-    <IsPackable>false</IsPackable>
+    <IsPackable>true</IsPackable>
     <PackageId>DemaConsulting.SysML2Tools.Language</PackageId>
     <AssemblyName>DemaConsulting.SysML2Tools.Language</AssemblyName>
     <Version>0.0.0</Version>
@@ -16,6 +16,9 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/demaconsulting/SysML2Tools</PackageProjectUrl>
     <RepositoryUrl>https://github.com/demaconsulting/SysML2Tools</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>Icon.png</PackageIcon>
+    <PackageTags>sysml2;sysml;mbse;parser;kerml</PackageTags>
     <Copyright>Copyright DEMA Consulting</Copyright>
     <Title>SysML2 Tools Language</Title>
     <Product>DemaConsulting.SysML2Tools</Product>
@@ -43,6 +46,11 @@
          0.4.10's native exclude wildcard feature (equivalent to its CLI "exclude" option). -->
     <ApiMarkExclude>DemaConsulting.SysML2Tools.Parser.Antlr*</ApiMarkExclude>
 
+    <!-- ApiMark Configuration: generate Markdown API reference docs from the XML doc
+         comments (see GenerateDocumentationFile above) and bundle them into the NuGet
+         package alongside the assembly. -->
+    <ApiMarkPackDocs>true</ApiMarkPackDocs>
+
     <!-- SBOM Configuration -->
     <GenerateSBOM>true</GenerateSBOM>
     <SBOMPackageName>$(Product)</SBOMPackageName>
@@ -56,9 +64,8 @@
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
     <PackageReference Include="Polyfill" Version="10.10.0" PrivateAssets="All" />
     <!-- ApiMark: generate Markdown API reference docs from the XML doc comments (see
-         GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
-         of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
-         package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
+         GenerateDocumentationFile above) and bundle them into this project's own NuGet
+         package (see ApiMarkPackDocs above). -->
     <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.10" PrivateAssets="All" />
   </ItemGroup>
 
@@ -68,6 +75,11 @@
     <InternalsVisibleTo Include="StdlibGen" />
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="..\..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\..\Icon.png" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
   <!-- Code Analysis Dependencies -->
   <ItemGroup>
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.301">
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
index eacf3e87..9c9c1e9c 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/DemaConsulting.SysML2Tools.Stdlib.csproj
@@ -6,7 +6,7 @@
     <ImplicitUsings>enable</ImplicitUsings>
     <Nullable>enable</Nullable>
 
-    <IsPackable>false</IsPackable>
+    <IsPackable>true</IsPackable>
     <PackageId>DemaConsulting.SysML2Tools.Stdlib</PackageId>
     <AssemblyName>DemaConsulting.SysML2Tools.Stdlib</AssemblyName>
     <Version>0.0.0</Version>
@@ -16,6 +16,9 @@
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/demaconsulting/SysML2Tools</PackageProjectUrl>
     <RepositoryUrl>https://github.com/demaconsulting/SysML2Tools</RepositoryUrl>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
+    <PackageIcon>Icon.png</PackageIcon>
+    <PackageTags>sysml2;sysml;mbse;stdlib</PackageTags>
     <Copyright>Copyright DEMA Consulting</Copyright>
     <Title>SysML2 Tools Stdlib</Title>
     <Product>DemaConsulting.SysML2Tools</Product>
@@ -34,6 +37,11 @@
     <EnableNETAnalyzers>true</EnableNETAnalyzers>
     <AnalysisLevel>latest</AnalysisLevel>
 
+    <!-- ApiMark Configuration: generate Markdown API reference docs from the XML doc
+         comments (see GenerateDocumentationFile above) and bundle them into the NuGet
+         package alongside the assembly. -->
+    <ApiMarkPackDocs>true</ApiMarkPackDocs>
+
     <!-- SBOM Configuration -->
     <GenerateSBOM>true</GenerateSBOM>
     <SBOMPackageName>$(Product)</SBOMPackageName>
@@ -86,9 +94,8 @@
     <PackageReference Include="Microsoft.Sbom.Targets" Version="4.1.5" PrivateAssets="All" />
     <PackageReference Include="Microsoft.SourceLink.GitHub" Version="10.0.300" PrivateAssets="All" />
     <!-- ApiMark: generate Markdown API reference docs from the XML doc comments (see
-         GenerateDocumentationFile above). This project is IsPackable=false and has no nupkg
-         of its own; its generated api/ folder is folded into DemaConsulting.SysML2Tools.Core's
-         package by the CopyLanguageAndStdlibApiDocsToPackage target in Core.csproj. -->
+         GenerateDocumentationFile above) and bundle them into this project's own NuGet
+         package (see ApiMarkPackDocs above). -->
     <PackageReference Include="DemaConsulting.ApiMark.MSBuild" Version="0.4.10" PrivateAssets="All" />
     <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" Version="10.0.301">
       <PrivateAssets>all</PrivateAssets>
@@ -100,4 +107,9 @@
     </PackageReference>
   </ItemGroup>
 
+  <ItemGroup>
+    <None Include="..\..\README.md" Pack="true" PackagePath="\" />
+    <None Include="..\..\Icon.png" Pack="true" PackagePath="\" />
+  </ItemGroup>
+
 </Project>

From f48be24de791fedbede13a90b04bf76282e6821f Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 13:18:46 -0400
Subject: [PATCH 12/13] docs: fix MD013 line-length in semantic model.md
 overview

---
 docs/design/sysml2-tools-language/semantic/model.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/design/sysml2-tools-language/semantic/model.md b/docs/design/sysml2-tools-language/semantic/model.md
index bf2d1264..36f17ffb 100644
--- a/docs/design/sysml2-tools-language/semantic/model.md
+++ b/docs/design/sysml2-tools-language/semantic/model.md
@@ -3,8 +3,9 @@
 #### Overview
 
 The Semantic Model subsystem provides the semantic model types (public) and the internal
-build/resolve implementation of the semantic loading pipeline. It contains seven units: `AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`,
-`SysmlEdge`, `SemanticIndex`, and `SysmlAnnotation`.
+build/resolve implementation of the semantic loading pipeline. It contains seven units:
+`AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`, `SysmlEdge`,
+`SemanticIndex`, and `SysmlAnnotation`.
 
 #### Interfaces
 

From 77a4b9a9132d2fea4f9c5ee551db3997fecfc442 Mon Sep 17 00:00:00 2001
From: Malcolm Nixon <Malcolm.Nixon@hiarc.inc>
Date: Sat, 4 Jul 2026 14:10:12 -0400
Subject: [PATCH 13/13] docs: address code-review and formal-review findings on
 rename/packaging

From the full-branch code-review:
- Fix Core/Rendering/NamespaceDoc.cs example: replace a Workspace-is-null
  check (which can never trigger, per this branch's own documented
  always-non-null guarantee) with the correct HasErrors check, matching
  WorkspaceLoader.LoadAsync's own example.
- Fix Stdlib/NamespaceDoc.cs example: replace an xUnit Assert.True call
  (not valid application code) with realistic WorkspaceLoader.LoadAsync
  usage, matching the same cleanup already done elsewhere this branch.

From parallel formal-review agents (gpt-5.4-mini) against affected
.reviewmark.yaml review sets:
- docs/design/sysml2-tools-language.md: stop describing the renamed
  Semantic.Model subtree as 'internal', add the missing public
  SysmlEdge/SemanticIndex/SysmlAnnotation types to the subsystem
  inventory and diagram, and correct 'Six concrete subtypes' of
  SysmlNode to the real nine (add SysmlConnectionNode,
  SysmlTransitionNode, SysmlSatisfyNode).
- docs/design/sysml2-tools-language/semantic/model.md: correct the
  overview to describe SysmlNode/SysmlEdge/SysmlAnnotation/SemanticIndex
  as the public model API (not internal), and add the missing SysmlNode
  entry to the unit inventory table (8 units, not 7).
- docs/design/introduction.md: fix a naming inconsistency introduced by
  the earlier Core packaging rename -- the Software Structure list still
  named the core system 'DemaConsulting.SysML2Tools' instead of
  'DemaConsulting.SysML2Tools.Core', contradicting the NuGet package
  table added in the same file.
- docs/design/sysml2-tools-core.md, docs/design/sysml2-tools-stdlib.md:
  add a Packaging section documenting the ApiMark/GenerateDocumentationFile
  wiring and (for Stdlib) independent-package status added by this
  branch's packaging restructure -- both were previously undocumented.

Not fixed (pre-existing, out of scope for this branch, flagged for the
maintainer separately): stale 'six node types' wording in
ast-serializer.md/ast-deserializer.md verification docs, a missing
Error Handling section in ast-deserializer.md design doc, a Theme.Font
contract mismatch between sysml2-tools-core.md and rendering.md, a
heading-depth issue in stdlib-provider.md, a missing Query subsystem
entry in introduction.md, README relative-link-format and render --auto
behavior-documentation mismatches, and reqstream coverage gaps for
SysmlEdge/SemanticIndex/SysmlAnnotation/SerializedStdlib/
AstSerializerContext -- none of these were introduced or touched by
this branch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 docs/design/introduction.md                       |  2 +-
 docs/design/sysml2-tools-core.md                  | 10 ++++++++++
 docs/design/sysml2-tools-language.md              | 15 ++++++++++-----
 .../sysml2-tools-language/semantic/model.md       | 11 +++++++----
 docs/design/sysml2-tools-stdlib.md                |  9 +++++++++
 .../Rendering/NamespaceDoc.cs                     |  4 ++--
 .../NamespaceDoc.cs                               |  4 ++--
 7 files changed, 41 insertions(+), 14 deletions(-)

diff --git a/docs/design/introduction.md b/docs/design/introduction.md
index 37569cf3..29705969 100644
--- a/docs/design/introduction.md
+++ b/docs/design/introduction.md
@@ -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
diff --git a/docs/design/sysml2-tools-core.md b/docs/design/sysml2-tools-core.md
index da197cf4..321c7694 100644
--- a/docs/design/sysml2-tools-core.md
+++ b/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.
diff --git a/docs/design/sysml2-tools-language.md b/docs/design/sysml2-tools-language.md
index 5aa65939..fa7a0b2e 100644
--- a/docs/design/sysml2-tools-language.md
+++ b/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`.
 
diff --git a/docs/design/sysml2-tools-language/semantic/model.md b/docs/design/sysml2-tools-language/semantic/model.md
index 36f17ffb..d2f2e76f 100644
--- a/docs/design/sysml2-tools-language/semantic/model.md
+++ b/docs/design/sysml2-tools-language/semantic/model.md
@@ -2,10 +2,12 @@
 
 #### Overview
 
-The Semantic Model subsystem provides the semantic model types (public) and the internal
-build/resolve implementation of the semantic loading pipeline. It contains seven units:
-`AstBuilder`, `SymbolTable`, `ReferenceResolver`, `SupertypeWalker`, `SysmlEdge`,
-`SemanticIndex`, and `SysmlAnnotation`.
+The Semantic Model subsystem provides the public semantic model types (`SysmlNode` and its
+subtypes, `SysmlEdge`, `SysmlAnnotation`, `SemanticIndex`) alongside the internal build/resolve
+implementation of the semantic loading pipeline (`AstBuilder`, `SymbolTable`,
+`ReferenceResolver`, `SupertypeWalker`). It contains eight units: `AstBuilder`, `SymbolTable`,
+`ReferenceResolver`, `SupertypeWalker`, `SysmlNode`, `SysmlEdge`, `SemanticIndex`, and
+`SysmlAnnotation`.
 
 #### Interfaces
 
@@ -57,6 +59,7 @@ over resolved edges.
 | `SymbolTable` | Registry mapping fully-qualified names to their AST nodes |
 | `ReferenceResolver` | Resolves supertype/typing/import/satisfy/verify/allocate/connect/transition refs; builds index |
 | `SupertypeWalker` | Walks specialization chains; detects cyclic specialization |
+| `SysmlNode` | Public abstract base record (and subtypes) modeling one parsed AST element |
 | `SysmlEdge` | Public record modeling one resolved reference (Supertype/Typing/Import/Satisfy/Verify/Allocate/etc.) |
 | `SemanticIndex` | Public reverse-lookup index over resolved `SysmlEdge` instances |
 | `SysmlAnnotation` | Public record modeling one captured `comment`/`doc` annotation (Comment/Documentation) |
diff --git a/docs/design/sysml2-tools-stdlib.md b/docs/design/sysml2-tools-stdlib.md
index 1806b366..c393fd59 100644
--- a/docs/design/sysml2-tools-stdlib.md
+++ b/docs/design/sysml2-tools-stdlib.md
@@ -58,6 +58,15 @@ diagnostics produced during pre-compilation.
 
 N/A — not a safety-classified software item.
 
+## Packaging
+
+`DemaConsulting.SysML2Tools.Stdlib` is an independently packable NuGet package
+(`IsPackable=true`) with its own `GenerateDocumentationFile` and `DemaConsulting.ApiMark.MSBuild`
+(`ApiMarkPackDocs=true`) wiring, so it bundles its own `api/` folder of ApiMark-generated
+API reference documentation and the embedded `stdlib.bin` resource. Consumers of
+`DemaConsulting.SysML2Tools.Core` receive this package transitively via a normal NuGet
+`<dependency>` reference — it is not embedded into another package's assembly.
+
 ## Data Flow
 
 ### Build-Time Flow
diff --git a/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
index f1c7a4ec..dfe216cc 100644
--- a/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
+++ b/src/DemaConsulting.SysML2Tools.Core/Rendering/NamespaceDoc.cs
@@ -36,9 +36,9 @@ namespace DemaConsulting.SysML2Tools.Rendering;
 /// <code>
 /// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
 /// var loadResult = await WorkspaceLoader.LoadAsync(["model.sysml"], stdlibTable);
-/// if (loadResult.Workspace is null)
+/// if (loadResult.HasErrors)
 /// {
-///     return; // parse/resolution errors — see loadResult.Diagnostics
+///     return; // inspect loadResult.Diagnostics for details
 /// }
 ///
 /// var diagramRenderer = new DiagramRenderer();
diff --git a/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs b/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs
index 3a6f307b..d7f78546 100644
--- a/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs
+++ b/src/DemaConsulting.SysML2Tools.Stdlib/NamespaceDoc.cs
@@ -17,8 +17,8 @@ namespace DemaConsulting.SysML2Tools.Stdlib;
 /// </remarks>
 /// <example>
 /// <code>
-/// var (table, _) = StdlibProvider.GetSymbolTable();
-/// Assert.True(table.Symbols.Count > 0, "Stdlib symbol table should not be empty.");
+/// var (stdlibTable, _) = StdlibProvider.GetSymbolTable();
+/// var result = await WorkspaceLoader.LoadAsync(["model.sysml"], stdlibTable);
 /// </code>
 /// </example>
 internal static class NamespaceDoc