detect¶

Identifies your documentation framework from config files — the first step in every workflow.

Before your assistant or MCP client writes a documentation page, it needs to know which framework dialect to use. detect scans project_root for framework config files and returns the detected framework name, config path, and readiness status.

Modes¶

When to use it¶

Run detect first when you're unsure which framework owns a directory, or when debugging why another tool returned unexpected output. This is usually the first call in GitHub Copilot, Copilot CLI, Cursor, or any other MCP client. Use mode="readiness" in CI to gate deployment.

Parameters¶

How detection works¶

Detection scans project_root in priority order. The first config file found wins.

flowchart TD
    R["project_root"] --> Z["zensical.toml / mkdocs.yml?"]
    Z -->|found| OK["✓ Framework: zensical"]
    Z -->|not found| D["docusaurus.config.js / .ts?"]
    D -->|found| OK2["✓ Framework: docusaurus"]
    D -->|not found| V[".vitepress/config.*?"]
    V -->|found| OK3["✓ Framework: vitepress"]
    V -->|not found| A["astro.config.mjs / .ts?"]
    A -->|found| OK4["✓ Framework: starlight"]
    A -->|not found| FAIL["✗ No framework detected\n→ run onboard to initialise"]

Config files scanned¶

Examples¶

Detect a Zensical project

{
  "tool": "detect",
  "arguments": { "project_root": "/Users/alice/projects/my-site" }
}

Returns:

{
  "framework": "zensical",
  "config_path": "/Users/alice/projects/my-site/zensical.toml",
  "confidence": 0.99,
  "docs_root": "docs",
  "readiness": {
    "status": "ready",
    "gates_passed": 4,
    "gates_total": 4
  }
}

When detection fails

{
  "framework": null,
  "config_path": null,
  "confidence": 0.0,
  "readiness": {
    "status": "not_ready",
    "gates_passed": 0,
    "gates_total": 4,
    "missing": [
      "No docs framework config found. Expected one of: zensical.toml, mkdocs.yml, docusaurus.config.js, .vitepress/config.mts, astro.config.mjs",
      "docs/ directory does not exist",
      "No index.md found"
    ]
  }
}

Readiness check for CI

{
  "tool": "detect",
  "arguments": { "mode": "readiness", "project_root": "./my-project" }
}

Returns:

{
  "status": "ready",
  "framework": "docusaurus",
  "gates_passed": 4,
  "gates_total": 4,
  "checks": {
    "config_found": true,
    "docs_dir_exists": true,
    "index_page_exists": true,
    "nav_parseable": true
  }
}

Use mode="readiness" in CI to fail the build when the project isn't ready to publish.

What to read next¶