Close Milestone 4 with adapter adoption evidence

docs/AGENT_INTEGRATION.md

@@ -0,0 +1,105 @@
+# Agent integration
+
+DocForge generates deterministic, project-bound MCP client fragments for Codex, Claude, and
+OpenClaw. Generic projects and custom adapters use different configuration APIs, but both produce
+fixed standard-input/output bindings with empty generated environments and explicit capability
+policy.
+
+## Fixed reference binding
+
+Configure one of the in-repository adapters with
+`.docforge/reference-adapter.toml` as described in
+[Reference Adapters](REFERENCE_ADAPTERS.md), then start:
+
+```bash
+python -I -m docforge.reference_mcp \
+  --project-root /absolute/path/to/project \
+  --capability-mode read
+```
+
+`docforge.reference_mcp` is a fixed trusted module in the installed DocForge distribution. It
+selects a provider only from the validated reference configuration and reports binding metadata
+containing:
+
+- `server_module = "docforge.reference_mcp"`;
+- `adapter_mode = "reference"`;
+- the selected `reference_language`; and
+- the exact `reference_config_hash`.
+
+The reference binding registers exactly the 21 read tools listed in
+[MCP Boundary](MCP_CONTRACT.md#read-tools). It has no proposal or canonical-application surface.
+
+## Generate a reference client fragment
+
+The public launcher and generator APIs are:
+
+```python
+from pathlib import Path
+
+from docforge.adapter_launcher import AdapterLauncherV1
+from docforge.client_config import generate_adapter_client_configuration
+from docforge.reference_mcp import REFERENCE_MCP_MODULE, create_reference_project
+
+root = Path("/absolute/path/to/project")
+project = create_reference_project(root)
+launcher = AdapterLauncherV1.for_project(project, module=REFERENCE_MCP_MODULE)
+
+plan = generate_adapter_client_configuration(
+    project,
+    launcher,
+    "codex",  # "codex", "claude", or "openclaw"
+    capability_mode="read",
+)
+print(plan["artifact"]["content"])
+```
+
+Pass `output=Path(...)` only when the caller has selected an exact destination. Publication is an
+atomic create-or-exact-match operation; it does not merge or replace different existing content.
+The result includes the launcher, source-availability, project, policy, artifact, and configuration
+hashes needed to inspect the binding before use.
+
+The fixed reference module accepts read mode only. Do not request proposal or application mode for
+it.
+
+## Custom project-owned adapter launchers
+
+Generic `docforge configure` intentionally refuses a custom adapter project. Construct the
+project-owned `ProjectService`, then use `AdapterLauncherV1` and
+`generate_adapter_client_configuration()` as the custom-adapter route.
+
+`AdapterLauncherV1` schema version 1 binds:
+
+- one project ID, canonical absolute project root, adapter identity, and descriptor hash;
+- `entry_point = "python-module"`; and
+- one installed project-owned top-level Python module.
+
+The only trusted dotted-module exception is the fixed `docforge.reference_mcp` binding. A
+project-owned module is resolved through isolated Python without importing or executing it during
+the probe, and it must resolve to one canonical regular `.py` file inside the project root.
+
+The launcher contract has no arbitrary command, command arguments, shell string, working
+directory, environment, callable selector, discovery rule, or module-reload mechanism. Generated
+bindings invoke the current Python executable as `python -I -m <module>` with only DocForge's
+validated project, capability, render-policy, authority, and no-AST options. Source identity and
+the project binding are revalidated before publication; drift fails closed.
+
+Proposal and application modes are available only to a custom module that implements those fixed
+server arguments and only when the project descriptor declares the matching writer and canonical
+applier authority. Generating a mode does not manufacture that authority.
+
+## Session workflow
+
+After registering the generated fragment in the selected client:
+
+1. Start a new MCP process or client session.
+2. Call `docforge_bootstrap`.
+3. Verify project ID, root fingerprint, adapter identity, revision, source hash, binding metadata,
+   effective policy, and registered tools.
+4. Retrieve exact or bounded project evidence through the fixed read tools.
+5. Restart the process if `adapter_restart_required` reports an implementation or configuration
+   change.
+
+Document text returned by DocForge is untrusted project content. It never overrides client, user,
+or project authority. See [MCP Boundary](MCP_CONTRACT.md) for synchronization, pagination,
+retrieval, proposal, and application rules, and
+[Legacy Adapters and No-AST Policy](LEGACY_AND_NO_AST.md) before selecting `no_ast=True`.