install: ship what the docs promise + close the smoke-test hole that hid it

[borisbat]

What

Audited cmake --install coverage against the tree and fixed the gaps. Seven of them broke workflows the shipped docs tell users to follow.

The worst: utils/mcp/setup.das has never been installed, while the installed utils/mcp/README.md (L175-192) and the shipped skills/mcp_tools.md (L73) both document running it. The MCP bootstrap was impossible from a bundle through 0.6.4. Its companion mcp_supervisor.py — which setup.das writes into .mcp.json — was missing too.

Root cause of the whole class: ci/smoke_test_bundle.sh compiled 9 of the 14 installed .das entry points, and setup.das sat in the gap, so nothing ever noticed. All 14 are covered now — 12 checks → 17.

Ship what was missing

Gap	Why it mattered
utils/mcp/setup.das + mcp_supervisor.py	The documented bootstrap, absent from every bundle
utils/mcp/tests/ non-.das fixtures	FILES_MATCHING PATTERN "*.das" dropped _fixture_cpp_outline.h and _pretend_root/.../.das_module, both required by the installed test_tools.das (L2130, L2611)
utils/lint/tests/ (77 files)	A bundle could not self-check the linter. Verified: 51 tests, 51 passed via dastest inside the install tree
examples/daStrudel/sfx_lab sounds/*.sfx (27) + .das_package	batch_drums.das:19, batch_synth.das:23, export_drums.das:12 read them via get_das_root() — shipping the scripts alone left them broken
examples/graphics per-example .das_package + .gitignore	Each subdir is a daspkg -project-root whose release_main points at the shared source one level up; the non-recursive glob dropped the load-bearing manifests
examples/benchmarks/	Documented in the installed examples/README.md:184-193, which also links its README
aot_testing / llvm_tune / perf_lint / style_lint skills	Cross-referenced by already-shipped skills, so they dangled in the SDK
tree-sitter-daslang/zed-daslang/	install/README.md points users at it
CHANGELIST.md	A versioned bundle shipped with no release notes
integration_cpp_23 in the standalone recipe	23_handle_registry.{cpp,das} shipped with no way to build it; handle_registry.h was already installed

tutorials.md deliberately stays repo-only — shipping it would drag in documentation_rst.md and onward — so the one reference to it (skills/xml.md) is reworded instead.

Decouple tutorial data install from DAS_TUTORIAL_DISABLED

The install rules for all 79 C/C++ integration tutorial sources lived inside the gated include(), so "don't build the tutorial executables" silently also meant "don't ship the tutorial sources." release.yml never sets the flag, so shipping was fine today — but the coupling was a trap. Verified by flipping the flag: 50 integration-source refs survive in the generated install script.

Hygiene

• Drop FLEX(utils/dasFsormatter/ds_lexer.lpp) — typo'd dir that does not exist, and dasFormatter has no .lpp at all. Inert only because no target consumed the output path (flex is found on some boxes, so this was not protected by FLEX_FOUND).
• examples/daspkg used a hardcoded DESTINATION instead of DAS_INSTALL_EXAMPLESDIR, and neither it nor examples/games excluded modules/ or build output — a dev tree would ship daspkg junk.
• file(STRINGS) on install/skills.list now passes ENCODING UTF-8. Without it, non-ASCII bytes act as separators: an em-dash in a comment splits the line and the tail is read as a skill filename, failing the guard with a nonsense path. (Hit this for real while writing the patch.)

dasHV tutorial artifact

tutorials/dasHV/_upload_test/_testfile.txt was committed because the server saves {upload_dir}/_testfile.txt (L279) but cleanup_upload_dir removed {dir}/testfile.txt (L158, no underscore) — the file survived, remove(dir) failed on a non-empty dir, and it landed in git. Fixed the name, untracked the file, gitignored the run dirs. Also corrected the Zed extension path in both READMEs (zed-daslang/, not editors/zed/).

Durable rules recorded

skills/install_instructions.md now carries the shipped-skill closure invariant (a shipped skill may only reference skills/<other>.md when that other ships; repo-only skills stay off the list and referring skills get reworded) with a copy-paste check script, plus the ASCII-only rule for skills.list.

Verification

• Release-flag bundle (ci/release_modules.txt) built and installed to a scratch prefix, then diffed against the pre-fix bundle: exactly 134 files added, nothing unintended.
• ci/smoke_test_bundle.sh: 17/17 passing.
• Shipped lint suite inside the bundle via dastest: 51 tests, 51 passed.
• Zero dangling skill→skill references across the 33 shipped skills.
• DAS_TUTORIAL_DISABLED=ON reconfigure: integration sources still install.
• Lint + format verified on the one changed .das.

Known follow-up (not in this PR)

The 33 shipped skills reference ~90 repo-only paths that can never exist in an SDK bundle — src/*.cpp, tests/**, doc/source/**/*.rst, benchmarks/**, modules/*/src/*.h — plus examples/{fatman,flatten,telegram/dictation,vulkan}, utils/watchdog, utils/dasllama-server. Rewriting those to daslang.io URLs vs. gating the paragraphs vs. accepting them is a product call about whether SDK-facing skills should read repo-internal at all, so it is left out deliberately. The skill→skill half of this class is fixed and guarded here.

Separately, the ten daslang -exe utils (aot, dascov, daspkg, detect-dupe, hygiene, jit, lint, benchctl, mcp, dastest) are built by add_custom_command, so install(TARGETS) cannot reach them and none ship — bundles run them from source. That is by design; this PR only corrects the stale comment in the smoke test that claimed otherwise.

---

Commit 2 — make the SDK self-contained (9cea6f157)

The audit above found the install rules broken. This second commit fixes the other half: shipped skills sent readers to 70 repo paths a bundle never contains. Two problems were tangled there, needing opposite fixes.

Where the skill relies on the content, the content now ships

One source file, as markdown. Sphinx learns to read markdown (myst-parser==2.0.0, the last line supporting Sphinx 7.2.6) and each .rst becomes a ~13-line pointer that includes the .md. daslang.io and the SDK then read the same bytes — nothing to drift, no generated artifact to keep in sync.

now ships as	was
skills/design_philosophy.md	reference/design_philosophy.rst
skills/tune.md	reference/tune.rst
skills/profiler.md	reference/utils/profiler.rst
skills/linq_fold_patterns.md	reference/linq_fold_patterns.rst
skills/detect_dupe_reference.md	reference/utils/detect_dupe.rst

Two of those RST pages share a stem with an existing shipped skill, because they are the same topic twice — and they are not the same case. memory_leak_detection.md said outright that its RST "covers the same material in docs style", so that pointer is reworded and nothing new ships; four of its five references now resolve to skills/profiler.md, inside the bundle. detect_dupe.rst is genuinely fuller than its skill (541 lines, five flag tables), so it ships under a non-colliding name.

Breadcrumbs in json.md / regex.md / das_macros.md ("RST companion at…", "generated stdlib reference at…" — two of them naming stdlib/generated files that don't exist in a fresh checkout) point at the published page instead.

Where the path is engine internals, the answer is the reverse

src/, tests/, benchmarks/, modules/*/src are never going into a bundle. So the line says so with a repo-only token and the reader skips it, instead of hunting a path that isn't there. 21 refs marked — two heading retitles cover 7 (cpp_integration's "C++ Codebase Notes", jobque_debugging's "Key files"), and 12 one-off prose mentions are marked inline so the sentence stays with the point it supports.

Enforced per-PR by ci/check_shipped_skill_refs.awk, run from ci/smoke_test_bundle.sh — that's build.yml's bundle_smoke job, which triggers on pull_request, so no new CI wiring. Smoke test 17 → 18 checks.

Exemption is section-scoped and resets at each heading. A trailing-marker rule would leak the exemption through the rest of the file, which is wrong for cpp_integration.md, whose internals section sits mid-file. Fenced blocks are exempt because they quote tool output verbatim — including a compiler warning that literally prints a doc/source path.

Verified, not assumed

• Docs built with CI's exact command (sphinx-build -W --keep-going): zero new warnings, six removed, against a 282-line baseline.
• The checker negative-tested: clean passes; an unmarked src/ path fails with file:line; the same line marked repo-only passes; a fenced path is ignored.
• doc/source citations from shipped skills: 9 → 1, and that one is the fenced compiler warning.
• Bundle reinstalled; 38 skills ship; zero dangling skill→skill references.

Two findings worth recording, both caught the hard way:

• A MyST (label)= target does not register in Sphinx's std domain when the markdown arrives via .. include:: … :parser:. Page labels therefore live in the .rst stub, and two bare :ref:s needed explicit link text once the title moved into the markdown. Each stub says so.
• file(STRINGS) treats non-ASCII bytes as separators, so an em-dash in an install/skills.list comment splits the line and the tail is read as a filename. Fixed with ENCODING UTF-8 plus an ASCII-only rule; the guard failing loudly is how it surfaced.

Deliberately not in this PR

tests/ — 53 refs, 24 of them in aot_testing.md. That class needs sorting into inline-the-snippet (where the code sample is the payload) vs quarantine, and it overlaps the question of splitting aot_testing.md / writing_tests.md, which are mixed-audience files. The awk carries a comment saying to add tests/ when it lands.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WiXc1jvihNmEnU7DDQidvt

[Copilot]

Pull request overview

This PR tightens the SDK/bundle install surface so cmake --install actually ships the files and fixtures that the shipped documentation and examples reference, and extends the bundle smoke test to compile every installed .das entry point to catch future install gaps.

Changes:

• Move C/C++ integration tutorial source installation out of DAS_TUTORIAL_DISABLED-gated CMake includes so tutorial sources always ship, and extend the standalone tutorial recipe to include tutorial 23.
• Expand installed content for MCP + lint tooling and examples (fixtures/tests, Strudel sfx_lab data, benchmarks, tree-sitter Zed extension), and update docs to match shipped paths.
• Strengthen smoke-test coverage and clean up accidental tutorial artifacts via corrected cleanup + .gitignore rules.

Reviewed changes

Copilot reviewed 15 out of 16 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tutorials/integration/cpp/CMakeLists.txt	Removes local install rules and documents that tutorial-source installs live in tutorials/CMakeLists.txt.
tutorials/integration/cpp/CMakeLists.standalone.cmake	Adds standalone build recipe entry for integration_cpp_23.
tutorials/integration/c/CMakeLists.txt	Removes local install rules and explains why installs must be unconditional.
tutorials/dasHV/05_cookies_and_forms.das	Fixes cleanup to remove the correct uploaded test filename, preventing leftover artifacts.
tutorials/dasHV/_upload_test/_testfile.txt	Removes an accidentally committed runtime artifact.
tutorials/CMakeLists.txt	Adds unconditional install rules for C/C++ integration tutorial sources + standalone CMakeLists.
skills/xml.md	Rewords tutorial-data install guidance to avoid referencing a repo-only skill and to point at the actual globbing behavior.
skills/install_instructions.md	Documents shipped-skill closure and skills.list encoding constraints + a check script.
README.md	Fixes Zed extension path under tree-sitter-daslang/.
modules/dasAudio/CMakeLists.txt	Installs .sfx and .das_package for Strudel sfx_lab so shipped scripts can run.
install/skills.list	Adds shipped-skill closure invariant notes and ships additional cross-referenced skills.
install/README.md	Fixes Zed extension path under tree-sitter-daslang/.
install/CLAUDE.md	Adds entries for newly shipped skills in the SDK-facing skill table.
CMakeLists.txt	Adds missing installed files (e.g., MCP setup + supervisor, lint tests, examples/benchmarks, zed extension, CHANGELIST) and improves install hygiene/excludes.
ci/smoke_test_bundle.sh	Expands compile-only coverage to all installed .das entry points and clarifies bundle executable expectations.
.gitignore	Ignores tutorial runtime artifacts (dasHV upload/static dirs and dasAudio tutorial WAVs) to prevent re-commits.

Comments suppressed due to low confidence (2)

tutorials/CMakeLists.txt:144

• Same as above: add CONFIGURE_DEPENDS so newly added/removed C/C++ integration tutorial sources are picked up without requiring a manual CMake reconfigure, which helps keep install coverage correct over time.

file(GLOB CPP_INTEGRATION_TUTORIAL_SOURCES

CMakeLists.txt:2127

• Same concern as the graphics install: if the source tree contains daspkg/runtime artifacts (lock/log/tmp dirs, shared_module outputs, jitted_scripts, etc.), they will be copied into the installed SDK because they are not excluded here.

install(DIRECTORY ${PROJECT_SOURCE_DIR}/examples/benchmarks/
    DESTINATION ${DAS_INSTALL_EXAMPLESDIR}/benchmarks
    FILES_MATCHING
        PATTERN "*.das"
        PATTERN "*.md"
        PATTERN ".das_package"

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 45 out of 46 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 57 out of 58 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

skills/profiler.md:60

• For SDK users running from the bundle root, this command should use bin/daslang (not daslang on PATH). Also consider changing the code fence language to bash since this is a shell invocation.

[Copilot]

Pull request overview

Copilot reviewed 59 out of 60 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (3)

skills/daslang_live.md:34

• The code block now uses the cross-platform bin/daslang-live naming, but this comment still says daslang.exe. Since the goal here is bundle-friendly docs, it should refer to daslang (or bin/daslang) rather than a Windows-only filename.

# Standalone mode (same as daslang.exe — if script only has main())
bin/daslang-live path/to/main.das

skills/daslang_live.md:37

• This sentence says scripts can be run with bin/daslang ... but then refers to the non-live host as daslang.exe. For consistency (and to avoid implying a Windows-only binary), this should say bin/daslang.

Scripts can also run standalone with `bin/daslang path/to/main.das` — the same `main.das` works in both hosts. Under `daslang.exe`, `is_live_mode()` returns `false`, the REST API does not start, and `[before_reload]`/`[after_reload]` annotations are ignored.

skills/install_instructions.md:41

• This enforcement note is stale: it still points at the old awk checker and claims tests/ is not in the pattern. The new Python gate includes tests/ and is what ci/smoke_test_bundle.sh actually runs, so the instructions should match reality.