nodehammer 0.2.0rc3__tar.gz → 0.2.0rc6__tar.gz

nodehammer-0.2.0rc6/.agents/skills/nodehammer/SKILL.md

@@ -0,0 +1,249 @@
+---
+name: nodehammer
+description: Drive the nodehammer CLI — convert HEP detector geometry (DD4hep XML, ROOT TGeo, .nhb) to glTF/OBJ/JSON, inspect a scene as JSON, validate and flatten TOML/Lua scene configs, pack and publish .nhproj project archives, and render or serve the 3D viewer. Use for nodehammer, nhb, nhr, .nhproj, nodehammer.toml, "convert geometry", "tessellate", "detector geometry", "wedge cut", NH#### diagnostic codes, or `uvx nodehammer`.
+---
+
+# nodehammer
+
+A pipeline that imports detector geometry, applies a config that selects and
+styles parts of it, and writes it out — as a mesh (glTF/OBJ), as an intermediate
+scene, as a JSON report, or into an interactive viewer.
+
+Same program either way: the compiled `nodehammer` executable and the
+`nodehammer` command from the Python wheel are one implementation (`cli::run`
+inside `libnodehammer`), so every command here behaves identically under
+`uvx nodehammer`. Differences that do exist are noted as such.
+
+## The output contract — read this before parsing anything
+
+**stdout is the answer. stderr is everything about producing it.**
+
+stdout carries the thing you would substitute into the next command: the
+flattened document, the JSON report, the path to the archive that was written,
+the URL being served. stderr carries diagnostics, progress and summaries.
+
+```bash
+archive=$(nodehammer project pack -c scene.toml -i det.root -o det.nhproj)
+```
+
+That yields the archive path, not a report about one. Two consequences:
+
+- **Never parse stderr.** It is prose for a human and is not a stable format.
+- **`-q` silences narration only.** Diagnostics, and the line a failing command
+  prints before it exits non-zero, are never affected. A flag that hid errors
+  would be a trap. `-v` restores narration; `-q`/`-v` may be typed before or
+  after the subcommand.
+
+When calling `nodehammer` from a script, quiet is already the default for the
+library entry point; the executable defaults to narrating because a person typed
+it.
+
+## Commands
+
+Five groups. Every one takes `-h`.
+
+| | |
+|---|---|
+| `convert` | import → config → write. The **output extension decides how far the pipeline runs** |
+| `inspect summary\|tree\|tags` | report on a geometry file; `--output-format json` |
+| `config validate\|flatten` | check a config, or resolve it to one self-contained TOML |
+| `project pack\|publish\|info` | build, publish and read `.nhproj` archives |
+| `viewer open\|serve\|shot\|bench` | the 3D viewer, in four postures |
+
+Option spellings are consistent across the tree: `-i/--input`, `-c/--config`,
+`-o/--output`, `--input-format`, `--output-format`, `--color`, `--depth/-d`,
+`--filter/-f` mean the same thing everywhere they appear.
+
+### Commands that block — do not run these unprompted
+
+| Command | What it does | Use instead |
+|---|---|---|
+| `viewer open` | opens a **native window and blocks** until the user closes it | `viewer shot -o out.png` |
+| `viewer` (bare, with a path) | same — `open` is the default mode | `viewer shot` |
+| `viewer serve` | starts an HTTP server, **opens a browser, and blocks** | `viewer serve --no-browser` in a background job, or `project publish` for static output |
+| `viewer bench` | runs a GPU benchmark; needs a display | only when the user asked for numbers |
+
+To *see* what a scene looks like, `nodehammer viewer shot <project> -o shot.png
+--shot-width 1920` renders one PNG once the scene settles and quits. That is the
+agent-appropriate way to check a geometry visually. It still needs a working GPU
+context, so it will fail on a headless machine with no display.
+
+Everything else in the tree runs to completion and exits.
+
+### convert
+
+```bash
+nodehammer convert -i det.root -c scene.toml -o det.glb
+nodehammer convert -i det.root -o scene.nhb          # stop at the semantic scene
+nodehammer convert -i det.root -o a.glb -o b.obj     # several outputs, one import
+```
+
+The output extension picks the writer *and* the depth of the pipeline:
+
+- `.nhb`, `.json` — the **semantic** scene. No tessellation. Fast.
+- `.glb`/`.gltf`, `.obj`, `.nhr`, render-JSON — **tessellated** first.
+
+`--timing` prints per-step wall clock, `--size-report` a payload breakdown; both
+to stderr, and both survive `-q` because naming a report is asking for it.
+`--strict` turns warnings into errors. `--wedge-cut START END` performs a real
+Manifold boolean, removing the azimuthal sector from START to END degrees
+measured from +x counter-clockwise — this is geometry, not a display effect.
+
+### inspect — the machine-readable one
+
+```bash
+nodehammer inspect --output-format json summary -i det.root
+nodehammer inspect --output-format json tree -i det.root --depth 3 --filter '*/Pixel*'
+nodehammer inspect --output-format json tags -i det.root
+```
+
+**Text and JSON are not the same content in two skins.** The text view draws
+tree lines, samples a tag key down to five values once it passes ten, and
+appends a "(n shown, m filtered)" footer. Parse the JSON, which carries the
+whole set and no drawing. Every document is stamped `"schema": 1`.
+
+```jsonc
+// summary
+{ "schema": 1, "kind": "summary", "format": "tgeo",
+  "nodes": 12043, "shapes": { "Box": 900, ... },
+  "materials": ["Air", ...],                       // sorted
+  "diagnostics": { "warnings": 3, "errors": 0 } }
+
+// tree
+{ "schema": 1, "kind": "tree", "shown": 40, "filtered": 12003,
+  "maxDepth": 3,        // null when no limit applied — present, not absent
+  "filter": "*/Pixel*", // null when none
+  "nodes": [ { "path": "/World/Det", "name": "Det", "depth": 1,
+               "children": 4, "leaf": false, "tags": {...} } ] }
+
+// tags
+{ "schema": 1, "kind": "tags", "nodeCount": 12043, "nodesWithTags": 800,
+  "keys": { "subdetector": ["pixel", "strip"] } }   // every value, not a sample
+```
+
+`maxDepth` and `filter` are **present-and-null** rather than absent, so read them
+unconditionally. `tags` is absent from a tree node that has none.
+
+### config
+
+Configs come in two spellings, and the file decides which: `.toml` (with an
+`include` chain) or `.lua` (a script that is evaluated). Both commands take
+either — **do not look for a separate Lua command, there isn't one**.
+
+```bash
+nodehammer config validate -c scene.lua
+nodehammer config flatten  -c scene.toml -o flat.toml   # -o optional; stdout otherwise
+```
+
+`config flatten` is the tool to reach for whenever you need to know what a config
+*actually* says: it resolves the include tree (or runs the script) and emits one
+self-contained TOML that needs no companion files. Its output is round-trippable.
+
+### project — `.nhproj` archives
+
+A `.nhproj` is a ZIP holding a config, the geometry it names, and a manifest.
+
+```bash
+nodehammer project pack -c scene.toml -i det.root -o det.nhproj
+nodehammer project info det.nhproj
+nodehammer project publish det.nhproj -o site/     # static site, no server
+```
+
+**`nodehammer.toml` inside an archive is a reserved key.** It is the manifest
+naming the entry config and geometry. `project pack` refuses rather than
+overwriting when a config is actually named that, or an include resolves to it.
+Do not hand-write it, and do not unzip an archive, edit, and re-zip — repack from
+sources instead.
+
+`project publish` produces a directory you can serve with any static file server
+(GitHub Pages included). Prefer it over `viewer serve` for anything an agent
+produces, because it terminates.
+
+## Inherent limitations — not bugs to work around
+
+**The importable set is smaller than the file types people assume.** Built in
+unconditionally: `.nhb` / `.nhb.zst`, `.json` / `.json.zst`, and the synthetic
+generator. Compile-time gated: `.root` (TGeo) and DD4hep XML. There is **no GDML
+importer** — a `.gdml` path will not resolve however you spell `--input-format`.
+
+**Heavy importers are compile-time options, not runtime ones.** `NODEHAMMER_WITH_TGEO`,
+`NODEHAMMER_WITH_DD4HEP`, `NODEHAMMER_WITH_GEANT4`, `NODEHAMMER_WITH_GEOMODEL` are
+**off by default**, and the released Python wheel is built without them. So
+`cannot determine input format for 'det.root'` from a wheel install is the build
+configuration, not a broken file and not a bug — the fix is a build with the
+backend enabled, never a different flag. Check with
+`nodehammer convert -i x.root -o /dev/null` and read the code, not the extension.
+
+**DD4hep XML has no extension of its own.** It is recognised by sniffing for
+`<lccdd` in the first 512 bytes, or by `--input-format dd4hep` when the sniff
+fails. A generic `.xml` that is not DD4hep will not resolve.
+
+**`viewer serve` needs a wasm runtime this build cannot produce.** It comes from
+the separate `nodehammer-web` distribution, which the Python package depends on.
+`NH1000` means it was not found; the command prints the search ladder it walked.
+`--web-assets DIR` points at a locally built one.
+
+**A wasm build has no `project` or `viewer serve`.** There is no host to serve
+from — the wasm module *is* the viewer.
+
+## Diagnostics
+
+Every failure carries a stable `NH####` code, greppable and safe to match on.
+Ranges: `NH00xx` config · `NH01xx` import · `NH02xx` scene ops · `NH03xx` TGeo ·
+`NH04xx` selection · `NH05xx` tessellation · `NH06xx` export · `NH08xx` public
+API · `NH09xx` CLI usage · `NH10xx` web runtime · `NH11xx` project archives.
+
+The prefix in the code's *name* says how far it goes: fatal (the call could not
+deliver), error (the result exists and part of it is wrong), warning (complete,
+something was assumed).
+
+| You see | It means | Do |
+|---|---|---|
+| `NH0101 cannot determine input format for '…'` | extension unknown **or backend not compiled in** | check the limitations above before anything else |
+| `NH0900 positional path must be a .nhproj archive or a directory` | `viewer <path>` got something else | pass a `.nhproj` or a directory |
+| `NH0901 path not found` / `input file not found` | a typo, before any window opens | — |
+| `NH1000` | wasm runtime missing | `pip install nodehammer-web`, or `--web-assets DIR` |
+| `NH1001` | runtime and library disagree | rebuild both halves together |
+| `NH1100` | archive could not be assembled or read | `project info` on it; do not unzip by hand |
+| `NH0008 drop_coincident_faces … without merge_descendants` | the option is silently a no-op | enable `merge_descendants` in the same scope |
+
+## Recipes
+
+**"What is in this file?"** → `nodehammer inspect --output-format json summary -i FILE`
+
+**"What does this config actually do?"** → `nodehammer config flatten -c FILE`
+(resolves includes and Lua), then read the TOML.
+
+**"Show me the geometry."** → `nodehammer viewer shot FILE -o /tmp/shot.png
+--shot-width 1920`, then look at the PNG. Never `viewer open`.
+
+**"Make something I can share."** → `project pack` then `project publish -o site/`.
+
+**"Is this config valid?"** → `nodehammer config validate -c FILE`; exit code is
+the verdict, the report is on stderr.
+
+**"Convert for a web page."** → `-o out.glb` (glTF binary), not `.obj`.
+
+## Do not
+
+- **Do not run `viewer open`, bare `viewer <path>`, or `viewer serve` without
+  being asked.** They block until a human intervenes.
+- **Do not parse stderr**, or the text form of `inspect`. Use
+  `--output-format json`.
+- **Do not unzip, edit and re-zip a `.nhproj`.** Repack from sources.
+- **Do not hand-write `nodehammer.toml` inside an archive** — `project pack`
+  owns that key.
+- **Do not treat a missing importer as a broken file.** Check the compile-time
+  gates first.
+- **Do not add `-q` to make output parseable.** It only removes narration from
+  stderr; stdout was already clean.
+
+## Getting this skill
+
+It ships inside the binary and is installed with:
+
+```bash
+nodehammer skills install            # into ~/.agents/skills, linked from ~/.claude
+nodehammer skills install --scope project
+nodehammer skills list
+```

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc6}/.gitignore

@@ -14,7 +14,7 @@
 # Project archives packed by the viewer / make_nhproj.py — always generated.
 *.nhproj
 
-# config-flatten output written to the repo root (generated from fixtures/).
+# `config flatten` output written to the repo root (generated from fixtures/).
 /*_flat.toml
 CMakeUserPresets.json
 

{nodehammer-0.2.0rc3 → nodehammer-0.2.0rc6}/CMakeLists.txt

@@ -10,6 +10,14 @@ project(nodehammer
     LANGUAGES C CXX
 )
 
+# This branch returns before discovering or configuring any processing,
+# application, Python, or viewer dependencies.
+option(NODEHAMMER_INGEST_ONLY "Build only the C++20 geometry ingestion library" OFF)
+if(NODEHAMMER_INGEST_ONLY)
+    include(cmake/IngestionOnly.cmake)
+    return()
+endif()
+
 set(CMAKE_CXX_STANDARD 23)
 set(CMAKE_CXX_STANDARD_REQUIRED ON)
 set(CMAKE_CXX_EXTENSIONS OFF)
@@ -133,10 +141,28 @@ include(cmake/CompilerOptions.cmake)
 # Included early: the core-library helper below bakes CMAKE_INSTALL_INCLUDEDIR
 # into the shared target's INSTALL_INTERFACE include path.
 include(GNUInstallDirs)
+include(cmake/PublicBackendHeaders.cmake)
+# Profiling flags are additive on top of any build type (Release, RelWithDebInfo,
+# Debug). Same interface across native and wasm; the flags differ per toolchain:
+# Clang/GCC get -g + frame pointers; MSVC gets /Zi + /Oy-; emscripten gets
+# --profiling-funcs on top so wasm function names survive the linker.
+if(NODEHAMMER_PROFILING)
+    if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
+        add_compile_options(-g -fno-omit-frame-pointer)
+    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
+        add_compile_options(/Zi /Oy-)
+        add_link_options(/DEBUG)
+    endif()
+    if(EMSCRIPTEN)
+        add_link_options(--profiling-funcs)
+    endif()
+endif()
+
+include(cmake/Ingestion.cmake)
 
 # ── The web runtime's contract ───────────────────────────────────────────────
 # The wasm viewer is delivered as a directory, not a program: a shell, a worker
-# script, three bundles and the stamp below. `nodehammer viewer --web` locates
+# script, three bundles and the stamp below. `nodehammer viewer serve` locates
 # one through a ladder of candidate directories (a flag, an environment
 # variable, this install path, later a download cache), which means it can be
 # handed a directory that nobody validated — an old checkout's build tree is
@@ -162,21 +188,12 @@ set(NH_WEB_RUNTIME_DIR "${CMAKE_INSTALL_DATADIR}/${PROJECT_NAME}/web")
 
 # ── FlatBuffers code generation ──────────────────────────────────────────────
 set(NH_FBS_SCHEMAS
-    ${CMAKE_CURRENT_SOURCE_DIR}/schemas/semantic.fbs
     ${CMAKE_CURRENT_SOURCE_DIR}/schemas/render.fbs
 )
 set(NH_FBS_GENERATED_DIR ${CMAKE_CURRENT_BINARY_DIR}/generated/flatbuffers)
 
-# Conan tool_requires exposes flatbuffers::flatc; FetchContent builds a plain
-# flatc target; a system install is on PATH. Resolve to whichever is present.
-if(TARGET flatbuffers::flatc)
-    set(NH_FLATC flatbuffers::flatc)
-elseif(TARGET flatc)
-    set(NH_FLATC flatc)
-else()
-    find_program(NH_FLATC_EXE flatc REQUIRED)
-    set(NH_FLATC "${NH_FLATC_EXE}")
-endif()
+# Use the same host schema compiler as the ingestion module.
+set(NH_FLATC ${NH_INGEST_FLATC})
 
 set(NH_FBS_GENERATED_HEADERS "")
 foreach(schema ${NH_FBS_SCHEMAS})
@@ -192,22 +209,7 @@ foreach(schema ${NH_FBS_SCHEMAS})
     list(APPEND NH_FBS_GENERATED_HEADERS ${out})
 endforeach()
 add_custom_target(flatbuffers_generate DEPENDS ${NH_FBS_GENERATED_HEADERS})
-
-# Profiling flags are additive on top of any build type (Release, RelWithDebInfo,
-# Debug). Same interface across native and wasm; the flags differ per toolchain:
-# Clang/GCC get -g + frame pointers; MSVC gets /Zi + /Oy-; emscripten gets
-# --profiling-funcs on top so wasm function names survive the linker.
-if(NODEHAMMER_PROFILING)
-    if(CMAKE_CXX_COMPILER_ID MATCHES "Clang|GNU")
-        add_compile_options(-g -fno-omit-frame-pointer)
-    elseif(CMAKE_CXX_COMPILER_ID STREQUAL "MSVC")
-        add_compile_options(/Zi /Oy-)
-        add_link_options(/DEBUG)
-    endif()
-    if(EMSCRIPTEN)
-        add_link_options(--profiling-funcs)
-    endif()
-endif()
+add_dependencies(flatbuffers_generate nodehammer_semantic_generate)
 
 # ── Core library configuration ────────────────────────────────────────────────
 # Pipeline core: IR + config + selection + tessellation + importers/exporters
@@ -228,9 +230,9 @@ endif()
 # packaging build describes the core once and builds it twice: the static
 # archive every in-tree target links, and the installed shared library. Anything
 # appended to *this* list reaches both — that is where the "describe once"
-# guarantee lives. NH_APP_SOURCES below is the deliberate exception.
+# guarantee lives. Ingestion sources are defined in Ingestion.cmake and reused
+# as objects; NH_APP_SOURCES below is the executable-only exception.
 set(NH_CORE_SOURCES
-    src/ir/semantic.cpp
     src/ir/semantic_json.cpp
     src/ir/render_json.cpp
     src/config/config_loader.cpp
@@ -241,8 +243,6 @@ set(NH_CORE_SOURCES
     src/ir/synthetic/semantic/importer.cpp
     src/ir/semantic/importer_registry.cpp
     src/ir/json/semantic/importer.cpp
-    src/ir/fb/semantic/importer.cpp
-    src/ir/fb/semantic/flatbuffer.cpp
     src/ir/fb/render/flatbuffer.cpp
     src/selection/predicate.cpp
     src/selection/selector.cpp
@@ -253,9 +253,12 @@ set(NH_CORE_SOURCES
     src/ir/gltf/render/exporter.cpp
     src/ir/obj/render/exporter.cpp
     src/ir/render/exporter_registry.cpp
+    src/ir/fb/render/exporter.cpp
+    src/ir/render/json_exporter.cpp
     src/ir/json/semantic/exporter.cpp
     src/ir/fb/semantic/exporter.cpp
     src/ir/semantic/exporter_registry.cpp
+    src/detail/env.cpp
     src/detail/markup.cpp
     # Host-side, despite the directory: locating and vetting the wasm runtime is
     # something the *serving* process does. src/web/'s other two TUs are the
@@ -264,12 +267,10 @@ set(NH_CORE_SOURCES
     src/web/executable_path.cpp
     src/scene_build.cpp
     src/export_resolve.cpp
-    src/version.cpp
     # The public API bridge: the only translation units that see both a public
-    # handle and its internals (src/api/handles.hpp is where the seam lives).
+    # handle and its internals (src/api/handles_semantic.hpp is where the seam lives).
     # Core, not app — these *are* what the installed library publishes.
-    src/api/diagnostics.cpp
-    src/api/semantic_scene.cpp
+    src/api/semantic_scene_formats.cpp
     src/api/config.cpp
     src/api/render_scene.cpp
     src/api/build.cpp
@@ -298,11 +299,7 @@ set(NH_CORE_SOURCES
     src/cli/pager.cpp
     src/cli/cmd_convert.cpp
     src/cli/cmd_inspect.cpp
-    src/cli/cmd_validate_config.cpp
-    src/cli/cmd_config_flatten.cpp
-    src/cli/cmd_dump_semantic.cpp
-    src/cli/cmd_dump_render.cpp
-    src/cli/cmd_config_lua.cpp
+    src/cli/cmd_config.cpp
 )
 
 # ── Application sources ───────────────────────────────────────────────────────
@@ -332,12 +329,6 @@ set(NH_APP_SOURCES
 set(NH_APP_DEPS "")
 set(NH_APP_DEFINES "")
 
-configure_file(
-    ${CMAKE_CURRENT_SOURCE_DIR}/include/nodehammer/version.hpp.in
-    ${CMAKE_CURRENT_BINARY_DIR}/include/nodehammer/version.hpp
-    @ONLY
-)
-
 # PUBLIC on the archive, because an internal header names the dependency where an
 # out-of-core target sees it. Each entry cites the header that justifies it;
 # remove one and the build fails. (Scope on the shared library is a different
@@ -419,23 +410,9 @@ list(APPEND NH_CORE_SOURCES src/lua/lua_config.cpp)
 # binding stay inside the core's implementation.
 list(APPEND NH_CORE_PRIVATE_DEPS lua::lua sol2::sol2)
 
-if(NODEHAMMER_WITH_TGEO OR NODEHAMMER_WITH_DD4HEP)
-    find_package(ROOT REQUIRED COMPONENTS Geom)
-    list(APPEND NH_CORE_SOURCES src/ir/tgeo/semantic/shape_dispatch.cpp)
-    list(APPEND NH_CORE_DEPS ROOT::Geom)
-    list(APPEND NH_CORE_DEFINES NH_WITH_TGEO=1)
-endif()
-
-if(NODEHAMMER_WITH_TGEO)
-    list(APPEND NH_CORE_SOURCES src/ir/tgeo/semantic/importer.cpp)
-endif()
-
-if(NODEHAMMER_WITH_DD4HEP)
-    find_package(DD4hep REQUIRED)
-    list(APPEND NH_CORE_SOURCES src/ir/dd4hep/semantic/importer.cpp)
-    list(APPEND NH_CORE_DEPS DD4hep::DDCore)
-    list(APPEND NH_CORE_DEFINES NH_WITH_DD4HEP=1)
-endif()
+# The ingestion module resolves the enabled experiment backends once.
+list(APPEND NH_CORE_DEPS ${NH_INGEST_BACKEND_DEPS})
+list(APPEND NH_CORE_DEFINES ${NH_INGEST_DEFINES})
 
 if(NODEHAMMER_WITH_GEANT4)
     find_package(Geant4 REQUIRED)
@@ -478,7 +455,11 @@ if(NOT EMSCRIPTEN)
         src/web/static_server.cpp
         src/web/stage.cpp
         src/web/open_browser.cpp
-        # `viewer --web` itself. Excluded here rather than #ifdef'd inside:
+        # Packing mounts a FilesystemProjectFs, so it is gated here rather than
+        # beside the ZipWorkingSet it builds -- that half *is* cross-platform.
+        src/project/pack.cpp
+        src/cli/cmd_project.cpp
+        # `viewer serve` itself. Excluded here rather than #ifdef'd inside:
         # every line of it calls something in the three files above, so a wasm
         # build of this TU would be a shell around a refusal. `run.cpp` skips
         # the registration to match, and a wasm module simply has no `viewer`
@@ -489,6 +470,37 @@ if(NOT EMSCRIPTEN)
     # least of all a header. Header-only, so the shared library gains no link
     # dependency and its package config gains no requirement.
     list(APPEND NH_CORE_PRIVATE_DEPS httplib::httplib)
+
+    # ── Agent skills, compiled in ─────────────────────────────────────────────
+    #
+    # `skills install` writes files into $HOME or a repo, which under Emscripten
+    # would mean a virtual filesystem that vanishes with the tab -- so the whole
+    # feature is native-only, and a wasm module carries none of the bytes.
+    #
+    # CONFIGURE_DEPENDS so that *adding* a skill re-globs on the next build
+    # rather than needing a manual configure; the explicit DEPENDS below is what
+    # makes *editing* one regenerate. Both are needed: the glob answers "which
+    # files", the dependency answers "have they changed".
+    file(GLOB_RECURSE NH_SKILL_FILES CONFIGURE_DEPENDS
+        ${CMAKE_CURRENT_SOURCE_DIR}/skills/*)
+    set(NH_SKILLS_DATA ${CMAKE_CURRENT_BINARY_DIR}/generated/skills/skills_data.cpp)
+    add_custom_command(
+        OUTPUT ${NH_SKILLS_DATA}
+        COMMAND ${CMAKE_COMMAND}
+            -DNH_SKILLS_DIR=${CMAKE_CURRENT_SOURCE_DIR}/skills
+            "-DNH_SKILLS_FILES=${NH_SKILL_FILES}"
+            -DNH_SKILLS_OUT=${NH_SKILLS_DATA}
+            -P ${CMAKE_CURRENT_SOURCE_DIR}/cmake/GenerateSkillsData.cmake
+        DEPENDS
+            ${NH_SKILL_FILES}
+            ${CMAKE_CURRENT_SOURCE_DIR}/cmake/GenerateSkillsData.cmake
+        COMMENT "Embedding agent skills"
+        VERBATIM
+    )
+    list(APPEND NH_CORE_SOURCES
+        ${NH_SKILLS_DATA}
+        src/cli/cmd_skills.cpp
+    )
 endif()
 
 # WatchedFilesystemProjectFs (strategy doc step 4) decorates FilesystemProjectFs
@@ -601,7 +613,8 @@ endif()
 # What every in-tree target links — CLI, viewer, tests, benchmarks. Core + app
 # sources. Never installed, so its dependencies are PUBLIC: in-tree targets reach
 # toml++, glm and nlohmann through this link.
-add_library(nodehammer_lib STATIC ${NH_CORE_INPUT} ${NH_APP_SOURCES})
+add_library(nodehammer_lib STATIC ${NH_CORE_INPUT} ${NH_APP_SOURCES}
+    $<TARGET_OBJECTS:nodehammer_ingest_objs>)
 nh_core_common(nodehammer_lib)
 
 target_link_libraries(nodehammer_lib PUBLIC ${NH_CORE_DEPS} ${NH_APP_DEPS})
@@ -641,7 +654,10 @@ if(NODEHAMMER_BUILD_SHARED)
 
     # Core only — no NH_APP_SOURCES. NH_CORE_INPUT is either the sources or the
     # shared objects, per the OBJECT block above.
-    add_library(nodehammer_shared SHARED ${NH_CORE_INPUT})
+    add_library(nodehammer_shared SHARED ${NH_CORE_INPUT}
+        $<TARGET_OBJECTS:${NH_INGEST_SHARED_OBJECTS}>)
+    add_library(nodehammer::shared ALIAS nodehammer_shared)
+    add_library(nodehammer::nodehammer ALIAS nodehammer_shared)
     nh_core_common(nodehammer_shared)
 
     # Plain PRIVATE is enough to keep the generated export empty, so a consumer
@@ -695,11 +711,10 @@ if(NODEHAMMER_BUILD_SHARED)
     # library itself; PRIVATE, since a consumer must see dllimport instead.
     target_compile_definitions(nodehammer_shared PRIVATE NH_EXPORTS)
 
-    # The exported name is `nodehammer`; the target cannot be, because the CLI
-    # executable already owns that target name.
+    # A consistent component target name in source and installed consumers.
     set_target_properties(nodehammer_shared PROPERTIES
         OUTPUT_NAME nodehammer
-        EXPORT_NAME nodehammer
+        EXPORT_NAME shared
     )
 
     # Version the library only when it is going to be installed as a system
@@ -868,7 +883,6 @@ if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
         src/scene_build.cpp
         src/selection/selector.cpp
         src/cli/cmd_convert.cpp
-        src/cli/cmd_dump_semantic.cpp
         PROPERTIES COMPILE_OPTIONS "-Wno-maybe-uninitialized"
     )
 endif()
@@ -877,6 +891,7 @@ endif()
 if(NODEHAMMER_BUILD_TESTS)
     enable_testing()
     add_subdirectory(tests)
+    add_subdirectory(tests/ingest)
 endif()
 
 # ── Python extension ───────────────────────────────────────────────────────────
@@ -912,7 +927,7 @@ if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
     # share/nodehammer/web is also the rung the asset ladder looks for relative
     # to the executable (docs/cli-and-web-viewer-plan.md Part 1), which is why
     # it is a datadir path and not an opaque one: a native install tree and a
-    # wasm install tree merge into one directory that `nodehammer viewer --web`
+    # wasm install tree merge into one directory that `nodehammer viewer serve`
     # can resolve without being told where anything is.
     install(TARGETS nodehammer-gles3 nodehammer-wgpu nodehammer-compute
         RUNTIME DESTINATION "${NH_WEB_RUNTIME_DIR}"
@@ -942,7 +957,7 @@ if(EMSCRIPTEN AND NODEHAMMER_WITH_VIEWER)
 
     # The stamp, written beside the bundles in the build tree so that a build
     # directory and an install tree are the same shape — `just wasm-serve` and
-    # `just pages-site` stage straight out of the former, and `viewer --web
+    # `just pages-site` stage straight out of the former, and `viewer serve
     # --web-assets build/emscripten/Release` is the first thing any developer
     # reaches for.
     file(GENERATE
@@ -1007,7 +1022,7 @@ if(NODEHAMMER_BUILD_SHARED)
     # linker resolving -lnodehammer reads it). Windows has no namelink; its
     # equivalent is .dll against .lib, stated by RUNTIME and ARCHIVE below.
     install(TARGETS nodehammer_shared
-        EXPORT nodehammer-targets
+        EXPORT nodehammer-shared-targets
         LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
                 COMPONENT Runtime
                 NAMELINK_COMPONENT Development
@@ -1045,59 +1060,12 @@ if(NODEHAMMER_BUILD_SHARED)
         COMPONENT Development
     )
 
-    install(EXPORT nodehammer-targets
-        FILE nodehammer-targets.cmake
+    install(EXPORT nodehammer-shared-targets
+        FILE nodehammer-shared-targets.cmake
         NAMESPACE nodehammer::
         DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/nodehammer"
         COMPONENT Development
     )
-
-    # Baked into the package config so a consumer's mismatched C runtime fails at
-    # configure time rather than as a segmentation fault on the first call that
-    # returns a container (see cmake/nodehammer-config.cmake.in).
-    #
-    # Evaluated by CMake rather than parsed by us. `CMAKE_MSVC_RUNTIME_LIBRARY`
-    # is normally a generator expression, and its shape varies by who set it —
-    # CMake's own default is "MultiThreaded$<$<CONFIG:Debug>:Debug>DLL" while
-    # Conan writes "$<$<CONFIG:Release>:MultiThreadedDLL>". A hand-rolled
-    # substitution for one of those spellings reported the other as a mismatch
-    # and blocked a legitimate build, which is worse than the failure it exists
-    # to catch. `file(GENERATE)` resolves whatever is there, exactly.
-    #
-    # The full runtime name, not a debug flag: /MT and /MD are different heaps
-    # even when neither is a debug runtime, so a static-CRT library and a
-    # dynamic-CRT consumer must not pass.
-    if(MSVC)
-        set(_nh_runtime_stamp "${CMAKE_CURRENT_BINARY_DIR}/nodehammer-msvc-runtime.txt")
-        file(GENERATE OUTPUT "${_nh_runtime_stamp}"
-             CONTENT "$<TARGET_PROPERTY:nodehammer_shared,MSVC_RUNTIME_LIBRARY>")
-        install(FILES "${_nh_runtime_stamp}"
-            DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/nodehammer"
-            COMPONENT Development
-        )
-    endif()
-
-    include(CMakePackageConfigHelpers)
-    configure_package_config_file(
-        "${CMAKE_CURRENT_SOURCE_DIR}/cmake/nodehammer-config.cmake.in"
-        "${CMAKE_CURRENT_BINARY_DIR}/nodehammer-config.cmake"
-        INSTALL_DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/nodehammer"
-    )
-    # SameMinorVersion, not the usual SameMajorVersion: pre-1.0, the major
-    # version conveys nothing, and treating every 0.x as interchangeable would
-    # promise compatibility across exactly the releases where the API is
-    # expected to move. Revisit at 1.0.
-    write_basic_package_version_file(
-        "${CMAKE_CURRENT_BINARY_DIR}/nodehammer-config-version.cmake"
-        VERSION ${PROJECT_VERSION}
-        COMPATIBILITY SameMinorVersion
-    )
-    install(FILES
-        "${CMAKE_CURRENT_BINARY_DIR}/nodehammer-config.cmake"
-        "${CMAKE_CURRENT_BINARY_DIR}/nodehammer-config-version.cmake"
-        DESTINATION "${CMAKE_INSTALL_LIBDIR}/cmake/nodehammer"
-        COMPONENT Development
-    )
 endif()
 
 # Reads the manifest produced by conanfile.py's generate(), assembles