Every #include in README.md names a header that does not exist (flat morph/bridge.hpp etc.; real paths are morph/core/…), and the same stale spelling is in ARCHITECTURE.md, the registry spec and registry.hpp's own doc comment

[Yaraslaut]

Every #include line in README.md names a header that does not exist

include/morph/ has no flat headers — everything lives under a subsystem
directory (core/, forms/, util/, journal/, session/, offline/,
qt/, net/, render/). The only file directly under include/morph/ is
version.hpp.

README.md's copy-pasteable snippets use the flat spelling throughout:

README.md:71:#include <morph/registry.hpp>
README.md:88:#include <morph/bridge.hpp>
README.md:89:#include <morph/backend.hpp>
README.md:90:#include <morph/executor.hpp>
README.md:163:#include <morph/registry.hpp>
README.md:290:#include <morph/forms.hpp>   // pulls in quantity.hpp + rational.hpp

None of those resolve. The correct paths are morph/core/registry.hpp,
morph/core/bridge.hpp, morph/core/backend.hpp, morph/core/executor.hpp
and morph/forms/forms.hpp.

Verification status

Reproduced on 93a6168, macOS 15.6 (arm64), Homebrew clang 22.1.8.

The README's "The main idea" block, copied verbatim into a file and compiled
with nothing but morph's own include directory and Glaze on the path:

$ clang++ -std=c++23 -I<repo>/include -I<glaze>/include -fsyntax-only readme_snippet.cpp
readme_snippet.cpp:2:10: fatal error: 'morph/registry.hpp' file not found
    2 | #include <morph/registry.hpp>
      |          ^~~~~~~~~~~~~~~~~~~~
1 error generated.

It fails on line one — before reaching anything the snippet is trying to
teach.

That the corrected paths work is confirmed by the same program compiling and
running once the includes are fixed (this is what
examples/concepts/getting_started.cpp and every ladder rung already use).

Not confined to the README

docs/ARCHITECTURE.md:409:#include <morph/registry.hpp>
docs/spec/core/registry.md:572:  class is declared in `morph/bridge.hpp` in namespace `morph::bridge` …
docs/spec/core/registry.md:672:  must include `<morph/bridge.hpp>` (directly or transitively) because …
docs/spec/core/registry.md:1023: `ActionExecuteRegistry` … (declared in `<morph/bridge.hpp>`, not `registry.hpp`)
docs/spec/core/registry.md:1024: Explains the hard `#include <morph/bridge.hpp>` requirement
docs/spec/util/quantity_type.md:865:#include <morph/quantity.hpp>
examples/forms/README.md:99: see `BridgeHandler::executeJson` in `morph/bridge.hpp`

and in the code's own documentation — include/morph/core/registry.hpp's
BRIDGE_REGISTER_ACTION doc comment states the hard requirement as
<morph/bridge.hpp>, and include/morph/detail/quantity_equation.hpp:8 refers
to morph/quantity.hpp.

Note docs/spec/core/registry.md:672 is the authoritative statement of a
link-time hard requirement — "every translation unit invoking
BRIDGE_REGISTER_ACTION must include <morph/bridge.hpp>". A reader who
follows it literally gets a file-not-found; a reader who guesses core/
gets it right. The requirement itself is correct and load-bearing; only the
path is wrong.

README.md's "Subsystems" table has the same shorthand (executor.hpp,
strand.hpp, completion.hpp, registry.hpp, model.hpp, model_key.hpp,
backend.hpp, remote.hpp, bridge.hpp, wire.hpp, session.hpp,
journal.hpp, rational.hpp, quantity.hpp, datetime.hpp, forms.hpp,
choice.hpp). In a table that is arguably shorthand rather than an error, but
it is the same drift and it is what makes the snippets look plausible.

Not verified: whether the flat layout ever existed and this is post-move
drift, or whether the README always described an intended layout. Either way
the current tree is the one a reader compiles against.

Impact

This is the very first thing a newcomer does — copy the README's headline
example — and it cannot compile. Nothing in CI notices, because every
first-party consumer (examples/**, tests/**) uses the real paths; the
broken spelling exists only in prose.

Found while writing docs/GETTING-STARTED.md (#170), whose section 7 has to
restate the BRIDGE_REGISTER_ACTION include requirement and could not simply
quote the spec's wording.

What would change the verdict

Close this when every #include <morph/...> in README.md,
docs/ARCHITECTURE.md, docs/spec/** and include/morph/** doc comments
names a path that exists on disk. A cheap guard worth adding in the same
change: a lint that extracts every morph/…\.hpp mentioned in tracked
markdown and header comments and asserts the file exists — the same shape as
scripts/check_spec_citations.sh, which already scans this prose for a
different class of drift.

[Yaraslaut]

Triage

Verdict: triage: valid. Well-framed, premise independently reproduced, proposed fix and reopen condition are both sound.

Empirical verification (independent of the issue's own repro)

Confirmed at d6690c56 (current master) that include/morph/ is entirely
subdirectory-based:

$ find include/morph -maxdepth 1 -type f
include/morph/version.hpp
$ find include/morph -maxdepth 1 -type d
include/morph/core include/morph/detail include/morph/forms
include/morph/journal include/morph/net include/morph/offline
include/morph/qt include/morph/render include/morph/session include/morph/util

version.hpp is the only flat header. Re-derived the mismatch list myself
rather than trusting the issue's:

README.md spells it	Real path
morph/registry.hpp (lines 66, 158)	morph/core/registry.hpp
morph/bridge.hpp (line 83)	morph/core/bridge.hpp
morph/backend.hpp (line 84)	morph/core/backend.hpp
morph/executor.hpp (line 85)	morph/core/executor.hpp
morph/forms.hpp (line 285)	morph/forms/forms.hpp

Same list the issue reports (line numbers differ slightly from 93a6168
because of unrelated intervening edits, content identical). Also independently
confirmed the other cited locations are still stale on current master:
docs/ARCHITECTURE.md:404, docs/spec/core/registry.md:572,672,1023-1024,
docs/spec/util/quantity_type.md:902, examples/forms/README.md:99, and the
doc comments in include/morph/core/registry.hpp:492,594-595 and
include/morph/detail/quantity_equation.hpp:8.

Root cause, confirmed via git history

git log --diff-filter=A -- include/morph/core/registry.hpp ... shows the
subdirectory layout was introduced in f0d54f6f ("refactor: group headers and
specs into sub-domain folders (#17)"). That commit's own message claims:

All in-repo includes, CMake header sets, Doxygen @file comments,
ARCHITECTURE.md header map, and inter-doc links updated.

But git show f0d54f6f -- README.md touches exactly two lines — both
cross-doc markdown links (docs/spec/journal.md → docs/spec/journal/journal.md,
same for session.md) — and never touches any of the six #include <morph/...>
code-fence lines. So this isn't vague "drift over time": it's a specific,
identifiable incomplete rename in a specific commit, four weeks old, that
missed every C++ #include line while fixing the markdown links in the same
file. Confirms the issue's own "not verified: whether the flat layout ever
existed" note — it did, and #17 is the commit that ended it without updating
these lines.

Invariants

Invariants 1-6 don't apply — no model/framework boundary, base-class
requirement, policy-vs-fact split, template-instantiation question, or
spec/code semantic disagreement is in play here; this is pure prose
inaccuracy. Invariant 7 ("would this still pass if the feature did nothing")
is the relevant one, and the issue already names the mechanism correctly.
Verified independently: neither drift-guard.yml's prose lint
(scripts/check_spec_citations.sh, which only checks that specific pinned
facts are still mentioned and that banned terminology doesn't reappear) nor
spec-sync.yml (which only checks that a include/morph/<sub>/** change has
a matching docs/spec/<sub>/** change) would ever catch a stale #include
path in prose — neither compiles anything or resolves a path against disk.
Grepped ci.yml and docs.yml for any README-snippet-compiling step: none
exists. So the proposed guard (extract every morph/…\.hpp mentioned in
tracked markdown/header comments, assert it resolves on disk) is a real,
currently-absent gate, not a duplicate of an existing one.

Overlap with #232

Not a duplicate, and not foldable into it. #232 is about whether
find_package(morph) works at all (install/export rules, morphConfig.cmake)
— i.e. how a consumer gets morph onto their toolchain in the first place.
#235 is about whether the #include spelling in the documentation is correct
once morph is on the include path, regardless of mechanism (-I,
add_subdirectory, or a future find_package). Fixing one doesn't fix the
other: #232 landing would still leave README.md telling a find_package
consumer to write #include <morph/bridge.hpp>, which still wouldn't resolve.
Orthogonal gaps in the same "does the documented consumption path actually
work" family as #228/#230, but none of the three share this issue's specific
defect (stale flat-vs-subdirectory include spelling).

Labels applied

triage: valid, area: docs

No new issue filed — this is a single well-scoped, already-fully-verified
finding with no separate problem hiding inside it.