Close Milestone 4 with adapter adoption evidence

docs/PROJECT_ONBOARDING.md

@@ -5,6 +5,11 @@ DocForge onboarding has two separate outcomes:
 1. A generic manual can be configured, indexed, rendered, visualized, and exposed through the MCP.
 2. A source graph additionally requires one validated language frontend per source language.
 
+DocForge ships narrow fixed references for Python, JavaScript, TypeScript, and C++. They are useful
+for syntax-scoped projects and adoption proof, but production semantic requirements may still
+require a project-owned compiler or language-service adapter. Review
+[Reference Adapters](REFERENCE_ADAPTERS.md) before selecting a frontend.
+
 The onboarding command never claims that source semantics exist merely because it found source
 files. It reports each detected language as `adapter_required` until a project integration supplies
 and proves that frontend.
@@ -64,6 +69,32 @@ immediately usable through the generic CLI, viewer, and MCP.
 The starter overview records detected languages and states that the source graph is unavailable
 until a language frontend passes the adapter proof. That limitation is deliberate.
 
+## Configure a fixed reference adapter
+
+The generic onboarding scaffold and fixed reference configuration are separate project routes.
+For a syntax-scoped reference project, create `.docforge/reference-adapter.toml`:
+
+```toml
+schema_version = 1
+project_id = "my-python-project"
+title = "My Python project"
+language = "python"
+source_roots = ["src"]
+```
+
+Then start the fixed read-only binding:
+
+```bash
+python -I -m docforge.reference_mcp \
+  --project-root /absolute/path/MyProject \
+  --capability-mode read
+```
+
+The configuration selects only a fixed in-repository provider and cannot name a command or custom
+module. JavaScript, TypeScript, and C++ require their respective optional extras; C++ also requires
+`compilation_database = "compile_commands.json"`. The complete configuration and supported-fact
+contract are in [Reference Adapters](REFERENCE_ADAPTERS.md).
+
 ## Complete onboarding checklist
 
 ### 1. Repository assessment
@@ -118,6 +149,13 @@ For every source language:
 - [ ] Define dependency discovery.
 - [ ] State unsupported semantic facts explicitly.
 
+Decide whether the project needs production semantic evidence or the narrower syntax-only
+reference scope. The Python reference publishes only project-local imports. JavaScript and
+TypeScript publish only project-local static relative imports and re-exports. The C++ reference
+publishes only directly resolvable project-local quoted includes and does not run a compiler. None
+of those references resolves calls, inheritance, types, symbols, runtime behavior, or semantic
+ownership.
+
 All frontends emit the same DocForge contracts:
 
 - `AdapterManifest` inventories fingerprinted extraction units and dependencies.
@@ -151,6 +189,11 @@ this checklist summarizes.
 - [ ] Assign shared symbols to one deterministic source contribution.
 - [ ] Record compiler-derived project include dependencies.
 
+These are production semantic-adapter expectations. The built-in C++ reference uses
+`compile_commands.json` only as bounded translation-unit inventory and fingerprint evidence. It
+parses commands and arguments as inert data, executes no command or compiler, and does not claim
+compiler include semantics, symbol ownership, or a Clang-derived graph.
+
 #### Rust
 
 - [ ] Read the Cargo workspace and package graph.
@@ -240,6 +283,10 @@ from filenames.
 Done when a new session can identify and retrieve the correct project without being told its file
 layout.
 
+The fixed reference server is read-only. Generic and custom-adapter client generation, including
+the immutable custom launcher boundary, is documented in
+[Agent Integration](AGENT_INTEGRATION.md).
+
 ### 10. Operating guide and maintenance
 
 - [ ] Record the authority and progressive-reading order.
@@ -286,14 +333,18 @@ to one configured project root.
 DocForge does not let an MCP call install dependencies, run project builds, modify Git, deploy, or
 publish. A project integration may use its own normal development workflow for those actions.
 
-## Frontend packaging direction
+## Reference and production frontend boundaries
 
-Reusable language frontends should be separate packages or project-owned adapters over the public
-DocForge contracts. They must not put language-specific rules into the graph, index, viewer, or MCP
-core.
+The public authoring namespace is `docforge.adapter_sdk`. Project-owned and separately distributed
+production frontends should build on that contract without putting language-specific rules into
+the graph, index, viewer, or MCP core.
 
-Worldforge is the first complete C++ reference integration. A reusable C++ package should be
-extracted only after that integration proves stable ownership, compiler dependency invalidation,
-and complete/incremental equivalence. Rust and Java frontends should then implement the same
-contract using their authoritative build and language tooling rather than copying C++ extraction
-rules.
+The in-repository Python, JavaScript, TypeScript, and C++ adapters are reference implementations.
+Their syntax-scoped behavior is useful without becoming a claim that every project in those
+languages has complete semantic coverage. A compiler-backed production C++ adapter may resolve
+build flags, calls, types, inheritance, include semantics, and ownership when it can prove those
+facts. The reference C++ adapter does none of that and is not a Clang semantic adapter.
+
+New Rust, Java, or other frontends should use their authoritative build and language tooling and
+must pass the graph-plus-Logic complete/incremental contract in the
+[Language Adapter Authoring Guide](ADAPTER_AUTHORING_GUIDE.md).