VI EN

## 📋 Before you start

Before you start, check these basics:

- ✅ Claude Code CLI or an installed IDE extension with login complete (verify by running `claude --version` in terminal, or by seeing the Claude icon in VS Code/JetBrains).
- ✅ Bash shell:
  - Linux/macOS: available by default (your standard terminal)
  - Windows: install Git for Windows (includes Git Bash) or enable WSL
- ✅ Git (verify: `git --version`)
- ⚪ Optional: Python ≥ 3.9 (only needed for `scripts/validate.py` and trace tools)

If you do NOT have Bash on Windows, see Common issues under "Windows without Bash".

## 📥 Easiest way: One command install (release URL via env)

Run one command to download + extract + install automatically from the latest GitHub release.

Linux / macOS one-liner

    curl -fsSL https://github.com/philngt/contextd/releases/latest/download/install.sh | sh

Windows PowerShell one-liner

    iwr https://github.com/philngt/contextd/releases/latest/download/install.ps1 -UseBasicParsing | iex

These URLs always point to the latest published installer assets.

Or download the zip manually if needed, then run the installer.

⬇️ Download contextd-latest.zip

This link works when opening files locally or when hosting a directory that includes `release/`.

1

#### Extract the zip

Extract to any folder — for example `~/wiki` on Linux/macOS or `D:\tool\wiki-template` on Windows.

    mkdir -p ~/wiki && unzip contextd-latest.zip -d ~/wiki
    # The zip contains root folder 'wiki-template' → unzip creates ~/wiki/wiki-template/
    cd ~/wiki/wiki-template

    # PowerShell
    Expand-Archive -Path contextd-latest.zip -DestinationPath D:\tool
    # Creates D:\tool\wiki-template\
    cd D:\tool\wiki-template

    # Or Git Bash
    unzip contextd-latest.zip -d /d/tool

Or right-click the zip file and choose "Extract All..." in File Explorer.

2

#### Run the installer

Same as Step 2 in the Git clone path — the file `scripts/install-to-claude.sh` is already in the zip:

    bash scripts/install-to-claude.sh

Verify the same way as Git install: `cat ~/.claude/wiki-global.json` should show `"wiki_root"` with your extracted path.

3

#### Setup codebase

Same as Step 3 below — run `/contextd-setup` in your codebase.

⚠️ Future updates: you must download a new zip for each update — there is no `git pull`. We recommend Git clone if you update often.
💡 For maintainers: create a new zip with `bash scripts/package-release.sh`. Output is written to `release/wiki-template-{version}.zip` + `release/contextd-latest.zip`. It automatically excludes `.git/`, raw evidence, workspaces other than `wiki/`, and runs/cache/log files. See `scripts/package-release.sh --help`.

## 🔧 Stable path for technical users: Git clone

If you have Git and want easier updates later, use this path.

1

## Download the repository

Choose any base folder — for example `~/wiki` on Linux/macOS or `D:\tool\wiki-template` on Windows.

    git clone https://github.com/philngt/contextd ~/contextd
    cd ~/contextd

    git clone https://github.com/philngt/contextd /d/tool/contextd
    cd /d/tool/contextd

In Git Bash, Windows path `D:\tool\` is written as `/d/tool/` (forward slash).

This repo needs no build and no dependency install — it is markdown plus bash scripts.

2

## Run the installer

Run this command (safe to run multiple times):

    bash scripts/install-to-claude.sh

This command automatically does 3 things:

- Syncs slash commands + subagents to `~/.claude/commands/` and `~/.claude/agents/` — Claude Code reads these folders automatically
- Creates `~/.claude/wiki-global.json` and points `wiki_root` to your cloned repo
- Safe to run again: rerun after each `git pull` to refresh commands

#### Verify installation

Check that the config path is correct:

    cat ~/.claude/wiki-global.json

    # PowerShell
    type $env:USERPROFILE\.claude\wiki-global.json

    # Or Git Bash
    cat ~/.claude/wiki-global.json

You should see field `"wiki_root"` with an absolute path to your cloned repo. Example:

    {
      "wiki_root": "/home/user/wiki",
      "default_workspace": null,
      "obsidian": { ... }
    }

Open Claude Code and run `/contextd-setup` → if the slash command appears in autocomplete, setup is successful.

3

## Connect your first project

Go to the codebase folder where you want to use the wiki, open Claude Code (or the IDE extension) there, and run:

    /contextd-setup

The setup flow guides you step by step:

- Automatically detects project name + tech stack from `package.json` / `pom.xml` / `Cargo.toml` / ...
- Prompts you to choose an existing workspace — or create a new workspace via `/new-workspace {name}`
- Step 4.5 (Manage packs): shows checkboxes for all available packs; auto-detects and pre-selects based on stack
- Creates `<codebase>/.claude/wiki.json` with complete config + per-codebase pack overrides

💡 You only run this once per project. After that, the wiki just works — you can use slash commands normally (`/use-contextd`, `/find`, `/tool-design`, ...).

Next: open index.html and choose a persona path (PM / Engineer / Wiki Owner / Solo Builder).

## 🔧 Common issues

### Windows without Bash

If you do not have Git Bash or WSL, use these 4 manual steps:

1. Copy `templates\wiki-global.json` → `%USERPROFILE%\.claude\wiki-global.json`
2. Open the copied file in Notepad, change `"wiki_root"` to the absolute repo path, and use `\\` instead of `\`:

       {
         "wiki_root": "D:\\tool\\wiki-template",
         ...
       }

3. Copy folders `.claude\commands\` and `.claude\agents\` to `%USERPROFILE%\.claude\`:

       xcopy /E /I /Y .claude\commands %USERPROFILE%\.claude\commands
       xcopy /E /I /Y .claude\agents %USERPROFILE%\.claude\agents

4. Verify: `type %USERPROFILE%\.claude\wiki-global.json`

Recommended: install Git for Windows (free) to get Git Bash → installer runs with one simple command.

### Commands do not appear in Claude Code

- Check whether `~/.claude/commands/` contains `.md` files (e.g. `contextd-setup.md`)
- Restart Claude Code (CLI: run `/exit` then reopen; IDE: reload window)
- Re-run installer: `bash scripts/install-to-claude.sh`
- Check Claude Code logs for errors (CLI: stderr; IDE: Output panel)

### Error `wiki_root not found` when running slash commands

- Open `~/.claude/wiki-global.json` and confirm `"wiki_root"` is an absolute path (do NOT use `~` or relative paths)
- Path must point to the wiki-template repo root (the folder containing `CLAUDE.md`, `packs/`, `workspaces/`)
- Verify the path exists: `ls "$(jq -r .wiki_root ~/.claude/wiki-global.json)"`

### `/contextd-setup` shows "workspace not found"

- No workspace exists yet — run `/new-workspace {name}` first (e.g. `/new-workspace acme-corp`)
- Or list available workspaces: `/list-workspaces`

### Permission error when running installer

- Linux/macOS: `chmod +x scripts/install-to-claude.sh` then run again
- Or force with bash: `bash scripts/install-to-claude.sh` (no executable bit required)

## 🔄 Future updates

After each `git pull` in the wiki-template repo, re-run the installer to sync updated slash commands:

    cd ~/wiki
    git pull
    bash scripts/install-to-claude.sh   # idempotent — updates everything

💡 When should you update?

- The wiki-template repo has new slash commands (e.g. newly shipped `/tool-design`)
- New packs were added to `packs/`
- Engine constraints / coding-rules were updated (new validator rules)

Your workspaces (`workspaces/{your-ws}/`) are data — they are not affected by engine updates.

← Back to Onboarding QUICKSTART.md (text) README.md GitHub Repository