276 lines
9.3 KiB
Markdown
276 lines
9.3 KiB
Markdown
# 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.
|