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.

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

```bash
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:

```bash
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:

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

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

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](ADAPTER_AUTHORING_GUIDE.md). 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.

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

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

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

## Frontend packaging direction

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.

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.