DocForge2/docs/PROJECT_ONBOARDING.md

Project onboarding

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 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.

Start with a read-only assessment

docforge --project-root /absolute/path/MyProject onboard

The assessment:

• detects common source languages and build-system evidence;
• excludes version-control, dependency, generated, cache, and build directories;
• inventories likely documentation;
• reports whether the project is already configured;
• states which capabilities are ready and which still need an adapter;
• does not create or modify files.

Limit detection to one or more known profiles when automatic discovery is not appropriate:

docforge --project-root /absolute/path/MyProject onboard --language rust
docforge --project-root /absolute/path/MyProject onboard --language java
docforge --project-root /absolute/path/MyProject onboard \
  --language cpp \
  --language typescript

Current profile IDs are c, cpp, csharp, go, java, javascript, kotlin, lua, php, python, ruby, rust, scala, swift, and typescript. A profile recognizes project evidence. It is not itself a parser.

Scaffold a generic manual

After reviewing the assessment:

docforge --project-root /absolute/path/MyProject onboard \
  --scaffold \
  --project-id my-project \
  --title "My Project"

Scaffolding creates:

• .docforge/project.toml;
• .docforge/templates/manual.html;
• docs/docforge/content/project-overview.md;
• the derived SQLite index;
• the rendered starter manual.

The command refuses to replace any existing target. Canonical files are written before the descriptor, and a failed write removes files created by that attempt. The configured manual is 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:

schema_version = 1
project_id = "my-python-project"
title = "My Python project"
language = "python"
source_roots = ["src"]

Then start the fixed read-only binding:

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.

Complete onboarding checklist

1. Repository assessment

• Resolve one explicit project root.
• Detect version-control and worktree boundaries.
• Detect source languages and build systems.
• Find existing manuals, design notes, API references, plans, and proof records.
• Exclude vendored, generated, dependency, cache, and build trees.
• Estimate source, documentation, and expected graph size.
• Report missing tools without changing the repository.
• Review the assessment before scaffolding.

Done when authored source is distinguishable from disposable and external files.

2. Identity and authority

• Assign a stable project ID and title.
• Declare canonical content roots.
• Declare authority files.
• Declare derived cache, changeset, preview, template, and render roots.
• Define documentation families and allowed relationships.
• Define proposal writers and operations.
• Decide which views are public, internal, or restricted.
• Keep source mutation disabled unless separately designed and authorized.

Done when every durable documentation fact has one authoritative source and every derived output can be deleted without losing that fact.

3. Manual foundation

• Scaffold or adapt .docforge/project.toml.
• Create at least one authoritative overview node.
• Assign stable node IDs, families, authorities, statuses, tags, and summaries.
• Import existing documents without silently changing their meaning.
• Separate current implementation, approved plans, proposals, and history.
• Define bounded context profiles for common development tasks.
• Validate, index, render, and visualize the manual.

Done when every rendered passage can be traced to a canonical source.

4. Language frontend selection

For every source language:

• Select or implement one frontend.
• Record its frontend and extractor versions.
• Define source discovery from authoritative build information.
• Define stable symbol identities.
• Define ownership for shared or generated declarations.
• Define supported node kinds and relationships.
• 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.
• AdapterSourceProjection owns nodes, relationships, and optional function Logic for one unit.
• AdapterProjection provides the deterministic complete rebuild.
• AdapterAssembly optionally resolves overlapping raw evidence into the single published graph.

Language metadata may differ. Graph publication, indexing, querying, visualization, and MCP behavior do not.

Done when repeated extraction produces the same stable identities without inferred or guessed facts.

When compiler or language tooling repeats shared declarations across extraction units, use the optional assembly contract. Cache the raw source contributions through DocForge, then deterministically select or merge ownership from the complete contribution set. Do not hide a second extraction cache inside the project adapter.

Before implementing a frontend, read the Language Adapter Authoring Guide. It defines the complete extraction, identity, ownership, normalization, incremental-equivalence, troubleshooting, and proof route that this checklist summarizes.

5. Build-system evidence

C and C++

• Use an authoritative compilation database.
• Preserve target flags, definitions, language standards, and include paths.
• Resolve headers shared by multiple translation units.
• 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.
• Respect packages, targets, features, and conditional compilation.
• Model crates, modules, traits, implementations, functions, and supported macros.
• Treat expanded macro output as derived evidence.
• Record the exact toolchain and extraction backend.

Java

• Read Gradle, Maven, or explicit source-root configuration.
• Respect modules, source sets, language level, and classpath.
• Model packages, classes, interfaces, records, methods, fields, and supported annotations.
• Separate authored source from generated and annotation-processor output.
• Record inheritance and interface implementation.

Other languages follow the same rule: the language frontend translates authoritative build and source evidence into the common adapter contract.

Done when a clean machine can reproduce the same source inventory from declared configuration.

6. Complete reference projection

• Extract the complete supported source tree.
• Generate stable source and symbol nodes.
• Generate only evidence-backed relationships.
• Generate optional function-scoped Logic separately from the primary graph.
• Reject duplicate node or Logic ownership.
• Reject missing relationship endpoints.
• Reject unsafe source paths.
• Record project identity, source hash, counts, and duration.
• Repeat the build and compare exact output.

Done when two unchanged complete builds are identical.

7. Incremental compilation

• Fingerprint each extraction unit.
• Record extractor versions.
• Record direct source dependencies.
• Invalidate reverse dependents.
• Remove deleted-source contributions.
• Treat missing or corrupt caches as cache misses.
• Publish cache and graph generations atomically.
• Keep the complete projection as the equivalence oracle.

Required proof:

• cold build;
• unchanged warm build;
• implementation-file change;
• shared-header or shared-module change;
• added, renamed, and deleted source;
• build-feature or compiler-setting change;
• corrupt cache;
• interrupted extraction;
• complete-versus-incremental equivalence.

Done when incremental extraction produces exactly the complete projection.

8. Source and manual integration

• Link documented systems to their implementation.
• Link API reference nodes to extracted symbols.
• Link roadmap work to affected systems.
• Link relevant tests and proof artifacts.
• Report implemented but undocumented systems.
• Report documented systems without implementation.
• Keep uncertain links as proposals.
• Keep source and manual projections independently rebuildable.

Done when a developer can navigate from a decision to implementation and back without guessing from filenames.

9. Views and MCP

• Configure the generic graph browser.
• Configure manual, source, API, roadmap, and proof views as needed.
• Verify search, filters, backlinks, dependencies, impact, and Logic.
• Generate the exact project-bound MCP command.
• Select read, proposal, and application capabilities explicitly.
• Register and reload the client.
• Call docforge_bootstrap.
• Verify project ID, root fingerprint, adapter version, revision, source hash, and index health.
• Verify the MCP cannot switch projects or weaken project authority.

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.

10. Operating guide and maintenance

• Record the authority and progressive-reading order.
• Explain exact lookup, search, context, backlinks, and impact analysis.
• Explain proposal, review, approval, and application.
• Explain cache invalidation and recovery.
• Explain frontend and adapter version changes.
• Run complete/incremental equivalence in continuous integration.
• Add contract tests for newly supported language features.
• Never hand-resolve generated-output conflicts.
• Never convert an inferred relationship into canonical truth silently.

Done when a developer unfamiliar with the repository can use DocForge without loading the entire manual or inventing another documentation workflow.

11. Release-candidate documentation cadence

• Read the relevant canonical nodes during intake.
• Record the expected documentation impact in the working plan.
• Keep canonical sources and DocForge proposals unchanged during implementation and focused test loops.
• Freeze one release candidate after implementation stops changing.
• Run the complete project gate, deployment preflight, candidate deployment, live checks, and release-identity checks before proposing documentation updates.
• Return to implementation when candidate validation fails.
• Register one atomic changeset that covers every affected canonical node after the candidate is green.
• Inspect the exact diff and previews, then apply only the reviewed changeset hash.
• Run documentation-only validation and render checks after application.
• Permit at most one narrow evidence-only correction for facts that could not exist before deployment.
• Commit, tag, and publish the final revision only after implementation and canonical documentation agree.

Done when documentation describes the verified release candidate instead of intermediate attempts, and the project normally performs one canonical documentation write per release slice.

CLI and MCP boundary

Initial assessment and scaffolding belong to the CLI because an MCP server cannot be registered until the project exists. The MCP begins at docforge_bootstrap, after its process has been fixed 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.

Reference and production frontend boundaries

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.

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.