DocForge2/docs/NEW_PROJECT_QUICKSTART.md

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

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

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

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

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

- Generic manual: continue with [Create a generic project](#create-a-generic-project).
- Fixed source example: continue with [Use a reference adapter](#use-a-reference-adapter).
- Production language frontend: follow the [Adapter authoring guide](ADAPTER_AUTHORING_GUIDE.md).

## Create a generic project

Set the absolute project root and assess it without writing:

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

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

```bash
"$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](PROJECT_DESCRIPTOR.md). Add
canonical nodes only after choosing their authority, stable IDs, families, statuses, and allowed
relationships; [Core concepts and authority](CORE_CONCEPTS_AND_AUTHORITY.md) defines those terms.

### Start a generic MCP binding

Start read-only first:

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

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

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

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

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

Doctor is a bounded configuration inspector, not a connection test. See [Agent
integration](AGENT_INTEGRATION.md) 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:

```toml reference-adapter
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:

```toml reference-adapter
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:

```bash
"$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](COMMAND_REFERENCE.md).

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

```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/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](REFERENCE_ADAPTERS.md) 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:

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

Then start a project-bound snapshot:

```bash
"$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](RENDERING_AND_VISUALIZATION.md) for manual, portable, and live-viewer differences.

## 4. Verify the maintained checkout

Contributors can run:

```bash
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](PROJECT_ONBOARDING.md) for production integration,
[Policy precedence](POLICY_PRECEDENCE.md) before widening a binding, and [Security](SECURITY.md)
before exposing any MCP process.