267 lines
11 KiB
Markdown
267 lines
11 KiB
Markdown
|
# 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.
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
### 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.
|