Get Started

Hosted-First Flow

Demiourgos Docs

Hosted-first, no-scan onboarding. Follow in order: login, create project, generate key, install CLI, init, configure auth, connect MCP client, run serve, then install skill and memory.

Setup

Overview

This is the canonical hosted flow. You do not need `demiourgos scan` for the docs-first path. MCP gets configured once, then each agent CLI auto-starts it.

Install Reference

Canonical install channels and quickstart.

Open Reference ↗

Skill Install Reference

Docs-sync installation commands for agent runtimes.

Open Reference ↗

Setup

Create Project

Create your first project from settings. This is the first required action before key generation.

Go To Create Project

Setup

Generate API Key

After project creation, open workspace settings and generate a project API key. Store it safely.

Go To Workspace

Local Setup

Install CLI (macOS + Linux)

Use one install channel consistently. Windows native docs are intentionally not published yet.

Windows support coming soon

Until native Windows docs land, use WSL prep and Python tooling references.

WSL Setup

Prepare Linux runtime on Windows.

Open Reference ↗

pipx Docs

Install Python CLI tooling cleanly.

Open Reference ↗

Homebrew

macOS install manager reference.

Open Reference ↗

macOS (Homebrew)

brew install sarveshdakhore/tap/demiourgos

Linux (pipx)

pipx install demiourgos

Linux (curl installer fallback)

curl -fsSL https://raw.githubusercontent.com/sarveshdakhore/demiourgos-client-dist/main/install.sh | sh

Local Setup

Init Project

Initialize Demiourgos in your project root. This creates config + local state. No scan step is required for hosted docs workflows.

Initialize config

demiourgos init --path .

Local Setup

Configure Project Auth

After init, bind your workspace to hosted control plane using project name, API key, and backend URL.

Set project auth

demiourgos project auth set --project-name "trial" --api-key "dpk_***" --backend-url "https://demiourgos-api.sarveshdakhore.in"

Verify project auth

demiourgos project auth show

Local Setup

Connect MCP Client

Register Demiourgos MCP with your agent CLI. This is one-time per project. After registration, the client auto-spawns MCP when needed.

1. Preferred (new CLI): run `demiourgos mcp setup --target <client>`.

2. If your installed CLI is old, use the direct fallback command shown above.

3. Reload/restart your active agent session so it picks up new MCP config.

4. MCP is auto-spawned by Gemini/Codex/Claude; do not keep a manual MCP terminal running for normal usage.

Gemini CLI

demiourgos mcp setup --target gemini

Codex CLI

demiourgos mcp setup --target codex

Claude Code

demiourgos mcp setup --target claude

If your CLI is older than 0.2.84 (Gemini)

gemini mcp add demiourgos -- demiourgos mcp --config .demiourgos.json --mode gateway

If your CLI is older than 0.2.84 (Codex)

codex mcp add demiourgos -- demiourgos mcp --config .demiourgos.json --mode gateway

If your CLI is older than 0.2.84 (Claude)

claude mcp add demiourgos -- demiourgos mcp --config .demiourgos.json --mode gateway

Local Setup

Run Serve (MCP Auto-Spawns)

Start `demiourgos serve` in your project. Keep it running while your agent uses Demiourgos tools. MCP starts automatically from agent config.

Run local serve API (required)

demiourgos serve --config .demiourgos.json --port 7788

Manual MCP only for debugging (normally auto-spawned)

demiourgos mcp --config .demiourgos.json --mode gateway

Local Setup

Single-Pass Truth Mode (Optional)

Use this only when you want a heavier one-shot docs ingestion pass. Normal hosted MCP workflows do not require it.

What it is: Single-pass truth mode runs a deeper pass over markdown/text docs to build a stronger first draft of L1/L2/L3 nodes.

When to use it: Initial project bootstrap, large docs imports, or when baseline node quality is weak and you want a stronger refresh.

When not to use it: Normal day-to-day MCP usage. Keep it off by default and enable it only for specific scan runs.

How defaults work: the default comes from `docs_sync.single_pass_truth_mode` in `.demiourgos.json`, and `demiourgos docs single-pass --enable/--disable` updates that default.

Check current default

demiourgos docs single-pass

Set default: single-pass ON

demiourgos docs single-pass --enable

Set default: single-pass OFF

demiourgos docs single-pass --disable

One run override: single-pass ON

demiourgos docs scan --single-pass-truth --limit-chunks 500

One run override: single-pass OFF

demiourgos docs scan --no-single-pass-truth --limit-chunks 500

Agent Setup

Install Docs-Sync Skill

Install docs-sync in your chosen agent environment using the exact command block for that CLI.

Codex

curl -fsSL https://raw.githubusercontent.com/sarveshdakhore/demiourgos-skills/main/scripts/install-skill.sh | bash -s -- --target codex --skill demiourgos-docs-sync-v1

Gemini CLI (project-local)

curl -fsSL https://raw.githubusercontent.com/sarveshdakhore/demiourgos-skills/main/scripts/install-skill.sh | bash -s -- --target gemini --project-root "$PWD" --skill demiourgos-docs-sync-v1

Claude Code / agents (project-local)

curl -fsSL https://raw.githubusercontent.com/sarveshdakhore/demiourgos-skills/main/scripts/install-skill.sh | bash -s -- --target agents --project-root "$PWD" --skill demiourgos-docs-sync-v1

If raw cache is stale once

curl -fsSL "https://raw.githubusercontent.com/sarveshdakhore/demiourgos-skills/main/scripts/install-skill.sh?t=$(date +%s)" | bash -s -- --target gemini --project-root "$PWD" --skill demiourgos-docs-sync-v1

Agent Setup

Paste Permanent Memory

Paste this full block into your LLM permanent memory, then fill project-specific fields. Keep skill_context minimal (skill_name + skill_version only).

Permanent Memory Template

memory_version: v2
project_root: <absolute path>
session_id: docs-sync-<timestamp>
checkpoint_id: <git head or "unknown">
mode: chat

skill_context:
  skill_name: demiourgos-docs-sync
  skill_version: v1

policy:
  mcp_only_writes: true
  internal_llm_enabled: false
  allow_alloy_scan_docs: false
  publish_default: draft
  taxonomy_source: references/docs_taxonomy_and_contract.md
  summary_plain_text_only: true
  summary_markdown_blocklist: ["#", "##", "###", "-", "*", "1.", "```", "`", "|", "[", "]", "(", ")"]
  summary_must_not_repeat_title: true

scope:
  domains: [root, backend, frontend]
  extensions: [.md, .txt]
  excluded: ["**/node_modules/**", "**/.git/**", "**/.venv/**", "**/venv/**", "**/dist/**", "**/build/**"]

index_state:
  loaded_layers: [l1, l2, l3]
  index_key: "(source_file, section_title, label)"
  last_feed_cursor:
    l1: ""
    l2: ""
    l3: ""

progress:
  files_scanned: 0
  files_changed: 0
  nodes_created: {l1: 0, l2: 0, l3: 0, l4: 0}
  nodes_updated: {l1: 0, l2: 0, l3: 0, l4: 0}
  nodes_archived: {l1: 0, l2: 0, l3: 0}
  edges_created: 0

quality:
  naming_weak_count: 0
  thin_content_count: 0
  missing_l4_evidence_count: 0
  needs_expansion_count: 0
  summary_markdown_violation_count: 0

queue:
  top_n_pending: []
  top_n_processed: []

decision_log:
  - ts: ""
    action: ""
    reason: ""
    confidence: 0.0

open_ambiguities: []
needs_expansion_nodes: []

Agent Setup

Retrieval Prompts

These prompts force tool-based retrieval (feed/search/read) so agents answer from MCP data instead of guessing.

Prompt: Top feed then answer

Use mcp_demiourgos_alloy_docs_feed on layer l2 with view draft, limit 30.
From the top relevant nodes, answer: "What changed in auth + MCP setup recently?".
Cite node ids in your answer.

Prompt: Search then deep-read

Use mcp_demiourgos_alloy_search_nodes with query "single_pass_truth_mode".
Pick top 3 results, then call mcp_demiourgos_alloy_read_node for each node_id.
Return a concise summary with exact node ids.

Prompt: Structure retrieval

Use mcp_demiourgos_alloy_structure_list_nodes for domain "backend" and view "draft".
Then read the most relevant structure node with mcp_demiourgos_alloy_structure_read_node.
Summarize architecture in 5 bullets.

Agent Setup

Contribute Prompts & Skills

Prompt quality and taxonomy quality directly determine documentation quality. Contribute to skills/prompts to improve extraction precision, node quality, and repair proposals.

Skills Repository

Source of docs-sync skill behavior.

Open Reference ↗

Prompt Files

Router/execution/top-N prompt stack.

Open Reference ↗

Taxonomy Contract

Allowed labels, relations, and failure policy.

Open Reference ↗

Open Pull Request

Submit improvements with concrete examples.

Open Reference ↗

Contribution checklist

1) Fork demiourgos-skills
2) Update docs-sync prompts under demiourgos-docs-sync-v1/prompts/
3) Update taxonomy contract if needed: references/docs_taxonomy_and_contract.md
4) Keep error policy strict: retry once, then alloy_report_error
5) Open PR with before/after examples of node quality

Reinstall updated skill locally

curl -fsSL "https://raw.githubusercontent.com/sarveshdakhore/demiourgos-skills/main/scripts/install-skill.sh?t=$(date +%s)" | bash -s -- --target gemini --project-root "$PWD" --skill demiourgos-docs-sync-v1

Verify

Health Check

Validate project auth and confirm your local server health endpoint before advanced workflows.

Open Project Health

Check project auth

demiourgos project auth show

Run graph + health check

demiourgos serve --config .demiourgos.json --port 7788
curl -s http://127.0.0.1:7788/health

Verify

Submit Feedback Test

Use this test prompt in your agent chat to confirm MCP write tools can reach the backend and return success payload.

Agent Prompt (tool test)

Use the tool mcp_demiourgos_alloy_feedback_submit with:
- tool_name: "docs_sync_setup"
- feedback_type: "positive"
- title: "MCP feedback pipeline test"
- summary: "Testing hosted feedback ingest from MCP after setup."
- details: "Project auth is configured, MCP is connected, and this is a validation event from docs flow."
- severity: "low"
- source: "mcp:manual-test"
Then show the tool response JSON only.

Verify

Troubleshooting

If something fails, use this quick sequence to isolate where setup broke.

1. Re-run project auth check and verify project name, API key prefix, and backend URL.

2. Confirm `demiourgos serve` is running in that project root; retry `curl -s http://127.0.0.1:7788/health`.

3. If MCP tools are missing in-chat: Gemini `/mcp reload`, Codex restart session, Claude restart session.

4. If you see `invalid choice: 'remote'`, re-run `demiourgos mcp setup --target <agent>` (gateway mode only).

5. If `demiourgos mcp setup` is not recognized, upgrade CLI or use fallback `<agent> mcp add ...` command with `--mode gateway`.

6. If skill calls fail, reinstall skill package and restart the agent session.

7. For hosted access issues, verify account/trial/project status in Settings.

Overview

Login

Create Project

Generate API Key

Install CLI (macOS + Linux)

Init Project

Configure Project Auth

Connect MCP Client

Run Serve (MCP Auto-Spawns)

Single-Pass Truth Mode (Optional)

Install Docs-Sync Skill

Paste Permanent Memory

Retrieval Prompts

Contribute Prompts & Skills

Health Check

Submit Feedback Test

Troubleshooting