administrator/DocForge2
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions Pages
DocForge2/docs/NEW_PROJECT_QUICKSTART.md

9.3 KiB
Raw Blame History

New-project quickstart

This guide takes a new installation from an empty project binding to a validated generic manual or one of DocForge's fixed reference source graphs. For the complete operating reference, see the user manual.

1. Install DocForge

DocForge requires Python 3.12 or newer. A base installation includes the generic project service, the public adapter SDK, the Python reference integration, CLI, MCP server, renderers, and viewer assets. It does not install Tree-sitter.

From a source checkout:

git clone <repository-url> /absolute/path/DocForge
cd /absolute/path/DocForge
uv sync --group dev

DOCFORGE=/absolute/path/DocForge/.venv/bin/docforge
DOCFORGE_MCP=/absolute/path/DocForge/.venv/bin/docforge-mcp
DOCFORGE_PYTHON=/absolute/path/DocForge/.venv/bin/python

For an isolated consumer environment, install the checkout or a built wheel with uv pip install. Add only the language extras that project needs:

uv venv /absolute/path/docforge-env --python 3.12
uv pip install --python /absolute/path/docforge-env/bin/python /absolute/path/DocForge
uv pip install --python /absolute/path/docforge-env/bin/python \
  "/absolute/path/DocForge[javascript]"
uv pip install --python /absolute/path/docforge-env/bin/python \
  "/absolute/path/DocForge[typescript]"
uv pip install --python /absolute/path/docforge-env/bin/python \
  "/absolute/path/DocForge[cpp]"

The languages extra installs all three optional grammar families. JavaScript and TypeScript are separate extras because they use distinct grammars. The C++ extra supplies a syntax grammar, not a compiler or Clang semantic frontend.

Confirm the installation:

"$DOCFORGE" --help
"$DOCFORGE_MCP" --help

2. Choose a project route

Use a generic project when Markdown or TOML documentation is canonical. Use a fixed reference adapter when you want a bounded source inventory and syntax-level graph for Python, JavaScript, TypeScript, or C++. Use a project-owned adapter when the production contract must supply richer semantics.

Create a generic project

Set the absolute project root and assess it without writing:

PROJECT=/absolute/path/MyProject
"$DOCFORGE" --project-root "$PROJECT" onboard

The assessment reports detected languages, build evidence, documentation candidates, current configuration, and available capabilities. Detection never invents a source graph.

Create a generic starter explicitly:

"$DOCFORGE" --project-root "$PROJECT" onboard \
  --scaffold \
  --project-id my-project \
  --title "My Project"

Scaffolding is create-only and refuses existing target files. It creates:

  • .docforge/project.toml, the generic project descriptor;
  • docs/docforge/content/architecture-overview.md, one canonical node;
  • .docforge/templates/manual.html, one built-in-renderer template;
  • derived index, receipt, and rendered output below .docforge.

If a language was detected, source graph status remains adapter_required. The generic starter does not claim source semantics.

Validate and inspect it:

"$DOCFORGE" --project-root "$PROJECT" validate
"$DOCFORGE" --project-root "$PROJECT" reindex
"$DOCFORGE" --project-root "$PROJECT" search architecture
"$DOCFORGE" --project-root "$PROJECT" show architecture.overview
"$DOCFORGE" --project-root "$PROJECT" render-status

The descriptor is explained field by field in Project descriptor. Add canonical nodes only after choosing their authority, stable IDs, families, statuses, and allowed relationships; Core concepts and authority defines those terms.

Start a generic MCP binding

Start read-only first:

"$DOCFORGE_MCP" \
  --project-root "$PROJECT" \
  --capability-mode read

Call docforge_bootstrap before other tools. It reports the exact project identity, generation, effective policy, projection policy, available capabilities, and recommended first read.

To enable proposals, the descriptor must declare the writer and the process must select it:

"$DOCFORGE_MCP" \
  --project-root "$PROJECT" \
  --capability-mode proposal \
  --proposal-writer project-editor

Canonical application is a separate startup gate. Do not add it to a read-only client:

"$DOCFORGE_MCP" \
  --project-root "$PROJECT" \
  --capability-mode application \
  --proposal-writer project-editor \
  --canonical-applier project-editor

Application accepts one exact reviewed changeset hash. It does not commit, push, build, deploy, or publish the project.

Generate a generic client fragment

Preview is side-effect free:

"$DOCFORGE" configure codex --project "$PROJECT"
"$DOCFORGE" configure claude --project "$PROJECT"
"$DOCFORGE" configure openclaw --project "$PROJECT"

Add --output /absolute/path/new-fragment to create one new private standalone file. Generation does not merge with or replace a different existing file. Diagnose an installed binding with:

"$DOCFORGE" doctor --client codex --project "$PROJECT"

Doctor is a bounded configuration inspector, not a connection test. See Agent integration for client-specific layouts and limitations.

Use a reference adapter

Reference adapters read one fixed descriptor: .docforge/reference-adapter.toml. The path is not selectable.

Create a Python project configuration:

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

JavaScript uses language = "javascript" and the javascript extra. TypeScript uses language = "typescript" and the typescript extra.

C++ additionally requires a confined compilation database:

schema_version = 1
project_id = "my-cpp-project"
title = "My C++ Project"
language = "cpp"
source_roots = ["src", "include"]
compilation_database = "compile_commands.json"

The C++ integration reads compile_commands.json only as bounded translation-unit inventory and fingerprint evidence. It never executes a recorded command or compiler.

Run the fixed read-only server through the same installed Python interpreter:

"$DOCFORGE_PYTHON" -I -m docforge.reference_mcp \
  --project-root "$PROJECT" \
  --capability-mode read

The binding chooses one in-package provider from the descriptor language. It accepts no provider module, command, argument list, working directory, environment, discovery rule, proposal writer, or canonical applier. Its MCP surface is the read subset documented in the generated command reference.

Generate a reference-adapter client fragment

Generic docforge configure intentionally refuses custom adapters. Construct the adapter project and immutable launcher, then call the custom-adapter generator:

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/MyProject").resolve(strict=True)
project = create_reference_project(root)
launcher = AdapterLauncherV1.for_project(project, module=REFERENCE_MCP_MODULE)

preview = generate_adapter_client_configuration(
    project,
    launcher,
    "codex",
    capability_mode="read",
)
print(preview["artifact"]["content"])

Use client="claude" or client="openclaw" for those formats. Pass an absolute output path only when creating a new standalone private fragment. The generated launch is bound to the selected project, descriptor hash, adapter identity, installed module, isolated interpreter, policy, and source availability evidence.

Read Reference adapters before relying on the graph. The Python example publishes local imports, the JavaScript and TypeScript examples publish project-local static relative imports and re-exports, and the C++ example publishes directly resolvable project-local quoted includes. None is a complete semantic compiler frontend.

3. Add visualization only when needed

Install the per-user viewer manager once:

/absolute/path/DocForge/.venv/bin/docforge-viewer-manager install-user-service

Then start a project-bound snapshot:

"$DOCFORGE" --project-root "$PROJECT" visualize
"$DOCFORGE" --project-root "$PROJECT" visualization-status

The listener is loopback-only and tokenized. The viewer is a derived snapshot, not canonical authority and not a continuously monitored filesystem view. Read Rendering and visualization for manual, portable, and live-viewer differences.

4. Verify the maintained checkout

Contributors can run:

make command-reference-check
make docs-check
make adoption-m4
make benchmark-m4-smoke

Run make gate before a release candidate. benchmark-m4-smoke is routine coverage; benchmark-m4 is the maintained full adapter workload.

Continue with Project onboarding for production integration, Policy precedence before widening a binding, and Security before exposing any MCP process.