diff --git a/README.md b/README.md
index dea7593..6002ded 100644
--- a/README.md
+++ b/README.md
@@ -97,9 +97,12 @@ dotnet run --project src/ProjGraph.Mcp
### Analyze Project Dependencies
```bash
-# Tree format (default)
+# Mermaid format (default)
projgraph visualize ./MySolution.sln
+# ASCII tree format
+projgraph visualize ./MySolution.sln --format tree
+
# Mermaid format for documentation
projgraph visualize ./MySolution.slnx --format mermaid --output docs/dependencies.mmd
```
diff --git a/docfx/docfx.json b/docfx/docfx.json
index 0166f02..fe52007 100644
--- a/docfx/docfx.json
+++ b/docfx/docfx.json
@@ -20,14 +20,18 @@
"build": {
"content": [
{
- "files": ["api/*.yml"]
+ "files": [
+ "api/*.yml"
+ ]
},
{
"files": [
"index.md",
"license.md",
"toc.yml",
+ "guides/*.md",
"guides/toc.yml",
+ "samples/toc.yml",
"dev/toc.yml"
]
},
@@ -66,14 +70,21 @@
"dest": "_site",
"template": [
"default",
- "modern"
+ "modern",
+ "templates/projgraph"
],
"globalMetadata": {
"_appTitle": "ProjGraph",
- "_appFooter": "Made with DocFX.",
+ "_appFooter": "",
"_enableSearch": true,
"_appFaviconPath": "icon.png",
- "pdf": false
+ "pdf": false,
+ "_appName": "ProjGraph",
+ "_appLogoPath": "icon.png",
+ "_gitContribute": {
+ "repo": "https://github.com/HandyS11/ProjGraph",
+ "branch": "develop"
+ }
}
}
}
diff --git a/docfx/guides/getting-started.md b/docfx/guides/getting-started.md
new file mode 100644
index 0000000..bd57bf9
--- /dev/null
+++ b/docfx/guides/getting-started.md
@@ -0,0 +1,117 @@
+---
+title: Getting started
+---
+
+# Getting started
+
+Install ProjGraph, point it at code you already have, and read the diagram it
+gives back. This page takes you through the first run for both the CLI and the
+MCP server. For the full set of flags on each command, see the
+[CLI reference](../../src/ProjGraph.Cli/README.md).
+
+## Before you start
+
+You need the [.NET 10 SDK](https://dotnet.microsoft.com/download) or later.
+Check what you have:
+
+```bash
+dotnet --version
+```
+
+ProjGraph reads source files directly. You do not need to build the project you
+are analysing, run a database, or apply migrations first.
+
+## Install the CLI
+
+```bash
+dotnet tool install -g ProjGraph.Cli
+```
+
+Confirm the tool is on your path. This lists the four commands and their
+options:
+
+```bash
+projgraph --help
+```
+
+If the command is not found, your shell has not picked up the global tools
+directory yet. Open a new terminal, or see
+[Troubleshooting](troubleshooting.md#projgraph-command-not-found).
+
+## Draw your first diagram
+
+Start with the solution you are standing in, because it needs no arguments
+beyond a path:
+
+```bash
+projgraph visualize ./MySolution.slnx
+```
+
+That prints a Mermaid graph to stdout, wrapped in a fenced code block ready to
+paste into Markdown. To read it in the terminal instead, ask for the tree:
+
+```bash
+projgraph visualize ./MySolution.slnx --format tree
+```
+
+Both render the same graph. [Output formats](output-formats.md) covers when to
+reach for which.
+
+## Draw the rest
+
+Each command takes a path and writes to stdout, so you can redirect it anywhere:
+
+```bash
+# Database schema, from an EF Core DbContext
+projgraph erd ./Data/LibraryContext.cs
+
+# One class, with its base types and dependencies
+projgraph classdiagram ./Models/Book.cs --inheritance --dependencies
+
+# Architectural metrics for the whole solution
+projgraph stats ./MySolution.slnx
+```
+
+Use `--output` rather than a shell redirect when you want the file written for
+you, including any missing directories:
+
+```bash
+projgraph erd ./Data/LibraryContext.cs --output docs/database-schema.md
+```
+
+## Use it from an AI assistant
+
+The MCP server exposes the same four analyses as tools an assistant can call,
+so you can ask about your architecture instead of remembering command names.
+
+Add the server to your MCP client's configuration. Replace `x.x.x` with the
+current version from
+[NuGet](https://www.nuget.org/packages/ProjGraph.Mcp):
+
+```json
+{
+ "servers": {
+ "ProjGraph.Mcp": {
+ "type": "stdio",
+ "command": "dnx",
+ "args": ["ProjGraph.Mcp@x.x.x", "--yes"]
+ }
+ }
+}
+```
+
+Restart the client, then ask it something that needs the tools:
+
+```text
+Show me the entity relationships in my DbContext.
+Which projects in this solution are referenced the most?
+```
+
+The [MCP reference](../../src/ProjGraph.Mcp/README.md) documents every tool,
+prompt, and resource the server provides.
+
+## Where to go next
+
+- [Output formats](output-formats.md) — pick between Mermaid, tree, and Markdown.
+- [Showcase](../../samples/README.md) — real commands and the diagrams they produced.
+- [Troubleshooting](troubleshooting.md) — when a diagram comes back empty.
diff --git a/docfx/guides/output-formats.md b/docfx/guides/output-formats.md
new file mode 100644
index 0000000..20333f0
--- /dev/null
+++ b/docfx/guides/output-formats.md
@@ -0,0 +1,143 @@
+---
+title: Output formats
+---
+
+# Output formats
+
+Every ProjGraph command writes text to stdout. What that text *is* — a Mermaid
+diagram, an ASCII tree, or a fenced Markdown block — depends on the command, the
+`--format` flag, and whether you asked for a file. This page explains the
+choices so you can pick one deliberately.
+
+## The three renderings
+
+| Rendering | Available on | Shows | Renders as a picture in |
+| --- | --- | --- | --- |
+| `mermaid` | `visualize`, and always for `erd` / `classdiagram` | The whole graph, as diagram source | GitHub, GitLab, this site, VS Code |
+| `tree` | `visualize` | Each root expanded recursively through its whole chain | Nowhere — it is already the picture |
+| `flat` | `visualize` | Every project once, with its direct references only | Nowhere — it is already the picture |
+
+`erd` and `classdiagram` have no `--format` flag. Both always emit Mermaid,
+because an entity relationship diagram and a class diagram have no useful
+plain-text form.
+
+## Choosing between them
+
+`tree` and `flat` answer different questions, and the difference is not
+cosmetic.
+
+**Tracing what a project pulls in transitively? Use `tree`.** It starts from the
+projects nothing else references and expands each chain to its full depth. A
+project that appears more than once is expanded on first sight and marked
+`(see above)` afterwards, so the output stays finite:
+
+```bash
+projgraph visualize ./MySolution.slnx --format tree
+```
+
+```text
+🧪 ProjGraph.Tests.Contract
+└── ProjGraph.Mcp
+ └── ProjGraph.Lib
+ ├── ProjGraph.Lib.ClassDiagram
+ │ └── ProjGraph.Lib.Core
+ │ └── ProjGraph.Core
+ └── ProjGraph.Lib.Dependencies
+ └── ProjGraph.Lib.Core (see above)
+```
+
+**Auditing what each project references directly? Use `flat`.** Every project is
+listed exactly once, grouped by type, with only its immediate references. No
+chain is followed, so nothing is repeated and nothing is elided:
+
+```bash
+projgraph visualize ./MySolution.slnx --format flat
+```
+
+```text
+🔷 ProjGraph.Lib
+├── → ProjGraph.Lib.ClassDiagram
+├── → ProjGraph.Lib.Dependencies
+└── → ProjGraph.Lib.EntityFramework
+🔷 ProjGraph.Lib.ClassDiagram
+└── → ProjGraph.Lib.Core
+```
+
+**Committing to docs? Use `mermaid`,** which is the default for `visualize`:
+
+```bash
+projgraph visualize ./MySolution.slnx
+```
+
+The emoji mark the project type: 🔷 library, 🚀 executable, 🧪 test project.
+
+## Fenced or raw: what `--output` changes
+
+This is the part that surprises people. The same command produces two different
+things depending on where it is going:
+
+- **To stdout**, Mermaid arrives wrapped in a `mermaid` code fence, so you can
+ paste it straight into a Markdown file and have it render.
+- **To a file via `--output`**, the extension decides. Only `.mmd` suppresses
+ the fence — a `.mmd` file is already understood to contain nothing but a
+ diagram. Every other extension, `.md` included, keeps it.
+
+```bash
+# Fenced Markdown, ready to commit into a docs page
+projgraph visualize ./MySolution.slnx --output docs/dependencies.md
+
+# Raw Mermaid, for a tool that parses .mmd directly
+projgraph visualize ./MySolution.slnx --output docs/dependencies.mmd
+```
+
+Prefer `--output` over a shell redirect. It creates missing directories for you,
+and it is what selects the right fencing.
+
+## Piping the output
+
+`mermaid` keeps stdout clean: progress messages go to stderr, so a redirect
+captures the diagram and nothing else.
+
+`tree` and `flat` are written for a human at a terminal, and their progress
+header goes to stdout along with the graph. If you redirect them, that header
+lands in your file too. Use `--output`, which writes the rendered graph and
+leaves the progress message on the terminal where it belongs:
+
+```bash
+# Captures the header as well - probably not what you want
+projgraph visualize ./MySolution.slnx --format tree > deps.txt
+
+# Captures the graph, with its title block
+projgraph visualize ./MySolution.slnx --format tree --output deps.txt
+```
+
+The diagram's own title block is part of the render, so it is written to the
+file either way. Drop it with `--show-title false`.
+
+## Titles
+
+Every diagram carries a title block naming what was analysed. Drop it when you
+are embedding the diagram under a heading that already says the same thing:
+
+```bash
+projgraph erd ./Data/LibraryContext.cs --show-title false
+```
+
+`--show-title` is available on `visualize`, `erd`, and `classdiagram`.
+
+## What `stats` does instead
+
+`stats` is the exception: it reports numbers, not a graph, so it has no
+`--format` and no `--output`. It prints a formatted table to the terminal and
+nothing else.
+
+```bash
+projgraph stats ./MySolution.slnx --top 10
+```
+
+## Rendering Mermaid on this site
+
+The [showcase](../../samples/README.md) pages embed their Mermaid output
+directly, so you can see exactly what each command produces without running it.
+That is the same text the CLI writes — the pages are regenerated from the tool
+whenever it changes.
diff --git a/docfx/guides/toc.yml b/docfx/guides/toc.yml
index 6eadac2..14d7126 100644
--- a/docfx/guides/toc.yml
+++ b/docfx/guides/toc.yml
@@ -1,3 +1,12 @@
+- name: 🚀 Start here
+- name: Getting started
+ href: getting-started.md
+- name: Output formats
+ href: output-formats.md
+- name: Troubleshooting
+ href: troubleshooting.md
+
+- name: 📖 Reference
- name: CLI Guide
href: ../../src/ProjGraph.Cli/README.md
- name: MCP Guide
diff --git a/docfx/guides/troubleshooting.md b/docfx/guides/troubleshooting.md
new file mode 100644
index 0000000..db206a1
--- /dev/null
+++ b/docfx/guides/troubleshooting.md
@@ -0,0 +1,141 @@
+---
+title: Troubleshooting
+---
+
+# Troubleshooting
+
+ProjGraph reads source files rather than compiled assemblies, so when a diagram
+comes back empty it is almost always because it could not find the thing you
+meant, not because your code is wrong. This page maps the messages you might see
+onto what to do about them.
+
+## `projgraph` command not found
+
+The tool installed, but your shell has not picked up the .NET global tools
+directory. Open a new terminal first — that resolves it most of the time.
+
+If it persists, add the tools directory to your `PATH`:
+
+```bash
+# Linux and macOS
+export PATH="$PATH:$HOME/.dotnet/tools"
+
+# Windows (PowerShell)
+$env:PATH += ";$env:USERPROFILE\.dotnet\tools"
+```
+
+Add the same line to your shell profile to make it stick.
+
+## `File must be a .sln, .slnx, or .csproj file.`
+
+`visualize` and `stats` analyse a solution or a project, not a directory and not
+a source file. Point them at the file itself:
+
+```bash
+projgraph visualize ./MySolution.slnx
+projgraph stats ./src/MyApp/MyApp.csproj
+```
+
+## `No DbContext or ModelSnapshot .cs file found.`
+
+`erd` was given no path, and found nothing to analyse in the current directory.
+It looks for files whose names end in `DbContext.cs` or that contain a model
+snapshot.
+
+Give it the path explicitly:
+
+```bash
+projgraph erd ./Data/LibraryContext.cs
+```
+
+If your context does not follow the `*DbContext.cs` naming convention, name it
+directly with `--context`:
+
+```bash
+projgraph erd ./Data/Persistence.cs --context LibraryContext
+```
+
+## The ERD is empty, or entities are missing
+
+ProjGraph discovers entities from the `DbSet` properties on your context, so
+an entity that is not exposed as a `DbSet` will not appear unless something else
+references it.
+
+Work through these in order:
+
+1. **Is the context `public`?** A non-public class is skipped.
+2. **Are the entities reachable?** An entity registered only through
+ `modelBuilder.Entity()` in `OnModelCreating`, with no `DbSet`, is found
+ only if ProjGraph can resolve the type.
+3. **Do the entity types live in another project?** ProjGraph searches the
+ workspace for them, starting from the nearest `.sln`, `.slnx`, or `.csproj`.
+ If your context and your entities are in unrelated directories with no
+ solution file above them, it has nothing to search.
+
+If the model is already migrated, the snapshot is the more reliable source,
+because EF has already resolved the model in full:
+
+```bash
+projgraph erd ./Migrations/LibraryContextModelSnapshot.cs
+```
+
+## The class diagram shows one class and nothing else
+
+That is the default. Base types and dependencies are opt-in, because following
+them across a large workspace is expensive:
+
+```bash
+projgraph classdiagram ./Models/Book.cs --inheritance --dependencies
+```
+
+Still missing types? Discovery only follows one level by default. Raise it:
+
+```bash
+projgraph classdiagram ./Models/Book.cs -i -d --depth 5
+```
+
+## `stats` reports zero projects
+
+The solution file parsed, but none of the projects it lists could be read.
+Usually one of:
+
+- The `.csproj` files it references have moved or been deleted.
+- The solution genuinely contains no projects.
+- You pointed at a solution file in a different directory tree, so the relative
+ project paths inside it no longer resolve.
+
+Confirm the paths inside the solution file match what is on disk.
+
+## Parsing fails on newer C# syntax
+
+ProjGraph parses with Roslyn, and the version of Roslyn it ships with sets the
+syntax it understands. If you use a language feature newer than the tool,
+parsing that file can fail.
+
+Update the tool:
+
+```bash
+dotnet tool update -g ProjGraph.Cli
+```
+
+## The MCP server returns nothing, or the client will not start it
+
+The server speaks JSON-RPC over stdio, which means **anything else written to
+stdout corrupts the protocol**. If you are running a locally built copy, make
+sure nothing in your build writes to stdout on startup.
+
+Check these in order:
+
+1. **Is `dnx` available?** Run `dnx --help`. It ships with the .NET 10 SDK.
+2. **Is the version in your config real?** Replace `x.x.x` with a published
+ version from [NuGet](https://www.nuget.org/packages/ProjGraph.Mcp).
+3. **Did the client restart?** Most MCP clients only read their server
+ configuration at startup.
+4. **Can the server see your files?** The tools take paths, and the server can
+ only read what its process can reach.
+
+## Still stuck
+
+Open an issue at
+[github.com/HandyS11/ProjGraph/issues](https://github.com/HandyS11/ProjGraph/issues)
+with the command you ran and the output you got.
diff --git a/docfx/index.md b/docfx/index.md
index 32d26eb..4a055e0 100644
--- a/docfx/index.md
+++ b/docfx/index.md
@@ -1,5 +1,148 @@
---
title: ProjGraph
+layout: landing
---
-[!include[Welcome](../README.md)]
+
+
Your code already describes its architecture. ProjGraph draws it.
+
One command turns a solution, an EF Core DbContext, or a single class into a Mermaid diagram or an ASCII tree. Run it from your terminal, or let an AI assistant run it for you over MCP.
Nothing was annotated to produce this. ProjGraph reads the C# with Roslyn, resolves the navigation properties into relationships, and carries the constraints across — [MaxLength(300)] on the left becomes max:300 on the right. No build, no running database, no migration step.
+
+
+$
+dotnet tool install -g ProjGraph.Cli
+
+
+
+
+
What it draws
+
Four commands, each pointed at something you already have on disk.
+
+
projgraph visualize
Reads a .slnx, .sln, or .csproj and maps how the projects reference each other. Emits Mermaid by default, or an ASCII tree for the terminal.
+
projgraph erd
Turns an EF Core DbContext or a ModelSnapshot into an entity relationship diagram, including keys, constraints, owned types, and join tables.
+
projgraph classdiagram
Draws a class with its inheritance chain and dependencies, following related types across the workspace as deep as you ask it to.
+
projgraph stats
Reports project counts, type breakdown, dependency depth, and the hotspot projects that everything else references.
+
+
+
+
+
Two ways to run it
+
The same analysis, reached either by hand or by an assistant.