@dotdrelle/wiki-manager 0.6.17

package/wiki-workspace

@@ -0,0 +1,773 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_SOURCE="${BASH_SOURCE[0]}"
+while [[ -L "$SCRIPT_SOURCE" ]]; do
+  SCRIPT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+  SCRIPT_TARGET="$(readlink "$SCRIPT_SOURCE")"
+  if [[ "$SCRIPT_TARGET" = /* ]]; then
+    SCRIPT_SOURCE="$SCRIPT_TARGET"
+  else
+    SCRIPT_SOURCE="$SCRIPT_DIR/$SCRIPT_TARGET"
+  fi
+done
+ROOT_DIR="$(cd "$(dirname "$SCRIPT_SOURCE")" && pwd)"
+DEFAULT_MANAGER_DIR="$PWD"
+WORKSPACES_DIR="${WIKI_WORKSPACES_DIR:-$DEFAULT_MANAGER_DIR/workspaces}"
+MANAGER_ENV_FILE="${WIKI_MANAGER_ENV_FILE:-$DEFAULT_MANAGER_DIR/.env}"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  wiki-workspace config <workspace> [path]
+  wiki-workspace up <workspace>
+  wiki-workspace wiki <workspace> <command> [args...]
+  wiki-workspace list
+
+Commands:
+  config <workspace> [path]         Create workspace folder, auto-select ports, run wiki init
+  up <workspace> [--open]           Start workspace stack: wiki + production
+  list                              List configured workspaces
+
+  agents up [--pull]                Start all external agents (cme, documents, mailer)
+  agents down                       Stop all external agents
+  agents logs [args...]             Follow external agent logs
+  agents pull                       Pull latest external agent images
+  agents status                     Check reachability of configured MCP endpoints
+
+  wiki <workspace> init             Initialize the workspace with wiki init
+  wiki <workspace> up               Start llm-wiki serve + mcp-http + production-mcp
+  wiki <workspace> down             Stop all services for this workspace
+  wiki <workspace> logs [args...]   Follow workspace service logs (tail 100 by default)
+  wiki <workspace> serve [--open]   Start the web UI in foreground (--open launches browser)
+  wiki <workspace> doctor           Run wiki doctor
+  wiki <workspace> ingest           Run wiki ingest
+  wiki <workspace> build            Run wiki build
+  wiki <workspace> export           Run wiki export
+  wiki <workspace> run <args...>    Run arbitrary wiki CLI args
+
+Configuration:
+  workspaces/<workspace>/.env
+  Override directory: WIKI_WORKSPACES_DIR=/path/to/dir
+EOF
+}
+
+die() {
+  printf 'Error: %s\n' "$*" >&2
+  exit 1
+}
+
+normalize_path() {
+  local value="$1"
+  if command -v wslpath >/dev/null 2>&1 && [[ "$value" =~ ^[A-Za-z]:[\\/] ]]; then
+    wslpath -u "$value"
+    return
+  fi
+  printf '%s\n' "$value"
+}
+
+absolute_path() {
+  local value="$1"
+  local base="${2:-$ROOT_DIR}"
+  value="$(normalize_path "$value")"
+  if [[ "$value" = /* ]]; then
+    printf '%s\n' "$value"
+  else
+    printf '%s\n' "$base/$value"
+  fi
+}
+
+workspace_env_file() {
+  local workspace="$1"
+  printf '%s/%s/.env\n' "$WORKSPACES_DIR" "$workspace"
+}
+
+need_workspace_env() {
+  local workspace="$1"
+  local file
+  file="$(workspace_env_file "$workspace")"
+  [[ -f "$file" ]] || die "missing workspace env: $file — run: wiki-workspace config $workspace"
+}
+
+env_value() {
+  local file="$1"
+  local key="$2"
+  local default="${3-}"
+  local line value
+  [[ -f "$file" ]] || { printf '%s\n' "$default"; return 0; }
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    line="${line%$'\r'}"
+    [[ "$line" == "$key="* ]] || continue
+    value="${line#*=}"
+    if [[ "$value" == \"*\" && "$value" == *\" ]]; then
+      value="${value:1:${#value}-2}"
+    elif [[ "$value" == \'*\' && "$value" == *\' ]]; then
+      value="${value:1:${#value}-2}"
+    fi
+    printf '%s\n' "$value"
+    return 0
+  done < "$file"
+  printf '%s\n' "$default"
+}
+
+generate_token() {
+  if command -v openssl >/dev/null 2>&1; then
+    openssl rand -hex 32
+    return
+  fi
+  if [[ -r /dev/urandom ]]; then
+    od -An -N32 -tx1 /dev/urandom | tr -d ' \n'
+    printf '\n'
+    return
+  fi
+  die "cannot generate MCP auth token: openssl and /dev/urandom are unavailable"
+}
+
+set_env_value() {
+  local file="$1"
+  local key="$2"
+  local value="$3"
+  local tmp="${file}.tmp.$$"
+  local wrote=0 line
+
+  if [[ -f "$file" ]]; then
+    while IFS= read -r line || [[ -n "$line" ]]; do
+      line="${line%$'\r'}"
+      if [[ "$line" == "$key="* ]]; then
+        printf '%s=%s\n' "$key" "$value"
+        wrote=1
+      else
+        printf '%s\n' "$line"
+      fi
+    done < "$file" > "$tmp"
+  else
+    : > "$tmp"
+  fi
+
+  if [[ "$wrote" -eq 0 ]]; then
+    if [[ -s "$tmp" ]]; then
+      printf '\n' >> "$tmp"
+    fi
+    printf '%s=%s\n' "$key" "$value" >> "$tmp"
+  fi
+  mv "$tmp" "$file"
+}
+
+agents_compose() {
+  local subcommand="$1"
+  shift
+  ensure_manager_endpoints_file
+  local agents_compose_file="$ROOT_DIR/agents.docker-compose.yml"
+  [[ -f "$agents_compose_file" ]] || die "agents compose file not found: $agents_compose_file"
+
+  local agents_data_dir workspaces_root
+  agents_data_dir="$(absolute_path "${AGENTS_DATA_DIR:-.agents-data}" "$DEFAULT_MANAGER_DIR")"
+  workspaces_root="$(absolute_path "$WORKSPACES_DIR" "$DEFAULT_MANAGER_DIR")"
+
+  local compose_env_args=()
+  [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
+
+  _agents_dc() {
+    WORKSPACES_ROOT="$workspaces_root" AGENTS_DATA_DIR="$agents_data_dir" \
+      docker compose "${compose_env_args[@]}" -f "$agents_compose_file" -p wiki-agents "$@"
+  }
+
+  case "$subcommand" in
+    up)
+      local do_pull=false
+      if [[ "${1:-}" == "--pull" ]]; then
+        do_pull=true
+        shift
+      fi
+      [[ $# -eq 0 ]] || die "agents up accepts only --pull"
+      mkdir -p "$agents_data_dir/cme" "$agents_data_dir/documents/input" "$agents_data_dir/documents/output" "$agents_data_dir/documents/uploads"
+      mkdir -p "$workspaces_root"
+      $do_pull && _agents_dc pull
+      _agents_dc up -d
+      printf 'Workspaces root: %s\n' "$workspaces_root"
+      printf 'Agents data:     %s\n' "$agents_data_dir"
+      printf 'Agents: cme=:%s  documents=:%s  mailer=:%s\n' \
+        "${CME_MCP_PORT:-3336}" "${DOCUMENTS_MCP_PORT:-3337}" "${MAILER_MCP_PORT:-3335}"
+      ;;
+    down)
+      [[ $# -eq 0 ]] || die "agents down does not take arguments"
+      _agents_dc down
+      ;;
+    logs)
+      local log_args=()
+      read_lines_into_array log_args logs_args "$@"
+      _agents_dc logs "${log_args[@]}"
+      ;;
+    pull)
+      [[ $# -eq 0 ]] || die "agents pull does not take arguments"
+      _agents_dc pull
+      ;;
+    status)
+      [[ $# -eq 0 ]] || die "agents status does not take arguments"
+      local endpoints_file="$ROOT_DIR/mcp.endpoints.json"
+      if [[ ! -f "$endpoints_file" ]]; then
+        printf 'No mcp.endpoints.json found at %s\n' "$endpoints_file" >&2
+        exit 1
+      fi
+      command -v node >/dev/null 2>&1 || die "agents status requires node"
+      node - "$endpoints_file" "$MANAGER_ENV_FILE" <<'NODE'
+import fs from 'node:fs';
+
+const [, , endpointsFile, envFile] = process.argv;
+
+function parseEnvValue(value) {
+  const trimmed = value.trim();
+  if (trimmed.startsWith('"') && trimmed.endsWith('"')) return trimmed.slice(1, -1);
+  if (trimmed.startsWith("'") && trimmed.endsWith("'")) return trimmed.slice(1, -1);
+  return trimmed;
+}
+
+function loadEnv(filePath) {
+  const values = { ...process.env };
+  try {
+    for (const raw of fs.readFileSync(filePath, 'utf8').split(/\r?\n/)) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const index = line.indexOf('=');
+      if (index === -1) continue;
+      const key = line.slice(0, index).trim();
+      if (!(key in values)) values[key] = parseEnvValue(line.slice(index + 1));
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+  return values;
+}
+
+function interpolate(value, env) {
+  return String(value).replace(/\$\{([^}]+)\}/g, (_match, expr) => {
+    const sep = expr.indexOf(':-');
+    if (sep !== -1) return env[expr.slice(0, sep)] ?? expr.slice(sep + 2);
+    return env[expr] ?? '';
+  });
+}
+
+function runtimeUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.hostname === 'host.docker.internal') parsed.hostname = 'localhost';
+    return parsed.toString();
+  } catch {
+    return url;
+  }
+}
+
+function normalizeHeaders(headers, env) {
+  if (!headers || typeof headers !== 'object' || Array.isArray(headers)) return {};
+  return Object.fromEntries(
+    Object.entries(headers)
+      .filter(([key, value]) => key && typeof value === 'string' && value)
+      .map(([key, value]) => [key.toLowerCase(), interpolate(value, env)]),
+  );
+}
+
+async function check(url, headers) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 3000);
+  try {
+    const response = await fetch(runtimeUrl(url), {
+      method: 'POST',
+      signal: controller.signal,
+      headers: {
+        accept: 'application/json, text/event-stream',
+        'content-type': 'application/json',
+        ...headers,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: {
+          protocolVersion: '2025-06-18',
+          capabilities: {},
+          clientInfo: { name: 'wiki-workspace', version: 'status' },
+        },
+      }),
+    });
+    await response.text();
+    return response.ok;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+const env = loadEnv(envFile);
+const config = JSON.parse(fs.readFileSync(endpointsFile, 'utf8'));
+const servers = config.mcpServers ?? config.servers ?? {};
+
+for (const [name, endpoint] of Object.entries(servers)) {
+  const url = interpolate(endpoint?.url ?? '', env);
+  if (!url) continue;
+  const ok = await check(url, normalizeHeaders(endpoint.headers, env));
+  console.log(`${name.padEnd(14)} ${url}  ${ok ? 'ok' : 'unreachable'}`);
+}
+NODE
+      ;;
+    *)
+      die "unknown agents command: $subcommand (expected: up, down, logs, pull, status)"
+      ;;
+  esac
+}
+
+ensure_manager_endpoints_file() {
+  local endpoints_file="$ROOT_DIR/mcp.endpoints.json"
+  if [[ ! -f "$endpoints_file" && -f "$ROOT_DIR/mcp.endpoints.example.json" ]]; then
+    cp "$ROOT_DIR/mcp.endpoints.example.json" "$endpoints_file"
+    printf 'Created %s (from mcp.endpoints.example.json — add headers/tokens as needed)\n' "$endpoints_file"
+  fi
+}
+
+workspace_value() {
+  local workspace="$1"
+  local key="$2"
+  local default="${3-}"
+  env_value "$(workspace_env_file "$workspace")" "$key" "$default"
+}
+
+used_workspace_ports() {
+  local entry file key val
+  for entry in "$WORKSPACES_DIR"/*; do
+    [[ -d "$entry" ]] || continue
+    file="$entry/.env"
+    [[ -f "$file" ]] || continue
+    for key in WIKI_SERVE_PORT WIKI_MCP_PORT PRODUCTION_MCP_PORT; do
+      val="$(env_value "$file" "$key" "")"
+      [[ "$val" =~ ^[0-9]+$ ]] && printf '%s\n' "$val"
+    done
+  done
+}
+
+is_port_in_use() {
+  local port="$1"
+  if command -v ss >/dev/null 2>&1; then
+    ss -tln 2>/dev/null | grep -q ":${port} "
+  elif command -v lsof >/dev/null 2>&1; then
+    lsof -iTCP:"$port" -sTCP:LISTEN >/dev/null 2>&1
+  else
+    (echo >/dev/tcp/127.0.0.1/"$port") 2>/dev/null
+  fi
+}
+
+find_free_port() {
+  local start="${1:-3100}"
+  local port="$start"
+  local used_ports=()
+  read_lines_into_array used_ports used_workspace_ports
+  while true; do
+    local taken=0 p
+    if (( ${#used_ports[@]} > 0 )); then
+      for p in "${used_ports[@]}"; do
+        [[ "$p" == "$port" ]] && { taken=1; break; }
+      done
+    fi
+    if [[ "$taken" -eq 0 ]] && ! is_port_in_use "$port"; then
+      printf '%s\n' "$port"
+      return 0
+    fi
+    port=$((port + 1))
+  done
+}
+
+find_free_workspace_port_base() {
+  local base="${1:-3100}"
+  local used_ports=()
+  read_lines_into_array used_ports used_workspace_ports
+  while true; do
+    local taken=0 offset port p
+    for offset in 0 1 2; do
+      port=$((base + offset))
+      if (( ${#used_ports[@]} > 0 )); then
+        for p in "${used_ports[@]}"; do
+          [[ "$p" == "$port" ]] && { taken=1; break; }
+        done
+      fi
+      [[ "$taken" -eq 1 ]] && break
+      if is_port_in_use "$port"; then
+        taken=1
+        break
+      fi
+    done
+    if [[ "$taken" -eq 0 ]]; then
+      printf '%s\n' "$base"
+      return 0
+    fi
+    base=$((base + 100))
+  done
+}
+
+list_workspaces() {
+  mkdir -p "$WORKSPACES_DIR"
+  local found=0 entry file name path serve mcp prod
+
+  for entry in "$WORKSPACES_DIR"/*; do
+    [[ -d "$entry" ]] || continue
+    file="$entry/.env"
+    [[ -f "$file" ]] || continue
+    found=1
+    name="$(env_value "$file" WORKSPACE_NAME "$(basename "$entry")")"
+    path="$(env_value "$file" WIKI_WORKSPACE_PATH "-")"
+    serve="$(env_value "$file" WIKI_SERVE_PORT "-")"
+    mcp="$(env_value "$file" WIKI_MCP_PORT "-")"
+    prod="$(env_value "$file" PRODUCTION_MCP_PORT "-")"
+    printf '%s\tpath=%s\tserve=%s\tmcp=%s\tprod=%s\n' \
+      "$name" "$path" "$serve" "$mcp" "$prod"
+  done
+
+  [[ "$found" -eq 1 ]] || printf 'No workspaces configured in %s\n' "$WORKSPACES_DIR"
+}
+
+compose_project() {
+  local workspace="$1"
+  printf 'wiki-%s' "$workspace" | tr -c '[:alnum:]_-' '-'
+}
+
+compose_for_workspace() {
+  local workspace="$1"
+  shift
+  need_workspace_env "$workspace"
+  local workspace_env ws_path serve_port mcp_port prod_port project
+  workspace_env="$(workspace_env_file "$workspace")"
+  ws_path="$(normalize_path "$(workspace_value "$workspace" WIKI_WORKSPACE_PATH)")"
+  serve_port="$(workspace_value "$workspace" WIKI_SERVE_PORT 3100)"
+  mcp_port="$(workspace_value "$workspace" WIKI_MCP_PORT 3101)"
+  prod_port="$(workspace_value "$workspace" PRODUCTION_MCP_PORT 3102)"
+  project="$(compose_project "$workspace")"
+
+  local compose_env_args=()
+  [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
+  compose_env_args+=(--env-file "$workspace_env")
+
+  WIKI_WORKSPACE_PATH="$ws_path" \
+  WIKI_SERVE_PORT="$serve_port" \
+  WIKI_MCP_PORT="$mcp_port" \
+  PRODUCTION_MCP_PORT="$prod_port" \
+  docker compose "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" -p "$project" "$@"
+}
+
+logs_args() {
+  if [[ $# -eq 0 ]]; then
+    printf '%s\n' --tail=100 -f
+  else
+    printf '%s\n' "$@"
+  fi
+}
+
+
+read_lines_into_array() {
+  local array_name="$1"
+  shift
+  [[ "$array_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] || die "invalid array name: $array_name"
+
+  eval "$array_name=()"
+  local line
+  while IFS= read -r line; do
+    eval "$array_name+=(\"\$line\")"
+  done < <("$@")
+}
+
+run_wiki() {
+  local workspace="$1"
+  shift
+  local ws_path
+  ws_path="$(normalize_path "$(workspace_value "$workspace" WIKI_WORKSPACE_PATH)")"
+  ensure_workspace_dirs "$ws_path"
+  compose_for_workspace "$workspace" run --rm wiki "$@"
+}
+
+open_app_mode() {
+  local url="$1"
+  case "$(uname -s)" in
+    Darwin)
+      open -na "Google Chrome" --args "--app=${url}" 2>/dev/null \
+        || open -na "Microsoft Edge" --args "--app=${url}" 2>/dev/null \
+        || open -a Safari "${url}" 2>/dev/null \
+        || open "${url}"
+      ;;
+    Linux)
+      # WSL2: Windows browsers are not on PATH — probe known Windows paths via wslpath.
+      if command -v wslpath >/dev/null 2>&1; then
+        local wsl_candidate wsl_path
+        for wsl_candidate in \
+          "C:/Program Files/Google/Chrome/Application/chrome.exe" \
+          "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe" \
+          "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" \
+          "C:/Program Files/Microsoft/Edge/Application/msedge.exe"; do
+          wsl_path="$(wslpath -u "$wsl_candidate" 2>/dev/null)" || continue
+          [[ -f "$wsl_path" ]] || continue
+          "$wsl_path" "--app=${url}" &
+          return
+        done
+        for wsl_candidate in \
+          "C:/Program Files/Mozilla Firefox/firefox.exe"; do
+          wsl_path="$(wslpath -u "$wsl_candidate" 2>/dev/null)" || continue
+          [[ -f "$wsl_path" ]] || continue
+          "$wsl_path" "${url}" &
+          return
+        done
+      fi
+      for candidate in google-chrome google-chrome-stable chromium chromium-browser microsoft-edge microsoft-edge-stable; do
+        if command -v "$candidate" >/dev/null 2>&1; then
+          "$candidate" "--app=${url}" &
+          return
+        fi
+      done
+      xdg-open "${url}" 2>/dev/null || true
+      ;;
+    MINGW*|MSYS*|CYGWIN*)
+      for candidate in \
+        "C:/Program Files/Google/Chrome/Application/chrome.exe" \
+        "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe" \
+        "C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe" \
+        "C:/Program Files/Microsoft/Edge/Application/msedge.exe"; do
+        if [[ -f "$candidate" ]]; then
+          "$candidate" "--app=${url}" &
+          return
+        fi
+      done
+      for candidate in \
+        "C:/Program Files/Mozilla Firefox/firefox.exe"; do
+        if [[ -f "$candidate" ]]; then
+          "$candidate" "${url}" &
+          return
+        fi
+      done
+      start "" "${url}" || true
+      ;;
+  esac
+}
+
+wait_and_open() {
+  local url="$1"
+  local max_attempts=30
+  local i=0
+  while (( i < max_attempts )); do
+    sleep 1
+    if curl -sf "${url}" >/dev/null 2>&1; then
+      open_app_mode "${url}"
+      return
+    fi
+    (( i++ )) || true
+  done
+  printf 'wiki-workspace: server did not become ready at %s after %ds, opening anyway\n' "${url}" "$max_attempts" >&2
+  open_app_mode "${url}"
+}
+
+ensure_workspace_dirs() {
+  local ws_path="$1"
+  mkdir -p "$ws_path/.wiki/vector-index"
+  mkdir -p "$ws_path/raw/untracked"
+  # The llm-wiki container runs as the unprivileged `node` user. On WSL2,
+  # Rancher Desktop, and bind mounts created by the host, runtime folders can
+  # end up owned by a different UID and become read-only from the container.
+  chmod -R a+rwX "$ws_path/.wiki" "$ws_path/raw" 2>/dev/null || true
+}
+
+register_workspace_path() {
+  local workspace="$1"
+  local target_path="$2"
+  local registry_path registry_abs
+  registry_path="$WORKSPACES_DIR/$workspace"
+  registry_abs="$(absolute_path "$registry_path")"
+
+  [[ "$target_path" == "$registry_abs" ]] && return 0
+
+  mkdir -p "$WORKSPACES_DIR"
+  if [[ -e "$registry_path" || -L "$registry_path" ]]; then
+    die "workspace registry path already exists: $registry_path"
+  fi
+  ln -s "$target_path" "$registry_path"
+  printf 'Registered %s -> %s\n' "$registry_path" "$target_path"
+}
+
+config_workspace() {
+  local workspace="$1"
+  local target_path="${2:-$WORKSPACES_DIR/$workspace}"
+  target_path="$(absolute_path "$target_path")"
+  ensure_manager_endpoints_file
+
+  local env_file="$target_path/.env"
+  [[ -f "$env_file" ]] && die "workspace already configured: $env_file"
+
+  local port_base serve_port mcp_port prod_port wiki_token prod_token
+  port_base="$(find_free_workspace_port_base 3100)"
+  serve_port="$port_base"
+  mcp_port=$((port_base + 1))
+  prod_port=$((port_base + 2))
+  wiki_token="$(generate_token)"
+  prod_token="$(generate_token)"
+
+  mkdir -p "$target_path"
+  register_workspace_path "$workspace" "$target_path"
+  ensure_workspace_dirs "$target_path"
+  # Ensure the container (node, UID 1000) can write to the workspace.
+  # Needed on WSL2 when the host UID differs from the container UID.
+  chmod -R a+rwX "$target_path" 2>/dev/null || true
+
+  printf 'WORKSPACE_NAME=%s\nWIKI_WORKSPACE_PATH=%s\nWIKI_SERVE_PORT=%s\nWIKI_MCP_PORT=%s\nPRODUCTION_MCP_PORT=%s\nPRODUCTION_REQUIRE_CONFIRMATION=false\nWIKI_MCP_AUTH_TOKEN=%s\nPRODUCTION_MCP_AUTH_TOKEN=%s\n' \
+    "$workspace" "$target_path" "$serve_port" "$mcp_port" "$prod_port" "$wiki_token" "$prod_token" \
+    > "$env_file"
+
+  printf 'Created %s\n' "$env_file"
+  printf 'Ports  serve=%s  mcp=%s  production=%s\n' \
+    "$serve_port" "$mcp_port" "$prod_port"
+
+  local compose_env_args=()
+  [[ -f "$MANAGER_ENV_FILE" ]] && compose_env_args+=(--env-file "$MANAGER_ENV_FILE")
+  compose_env_args+=(--env-file "$env_file")
+
+  WIKI_WORKSPACE_PATH="$target_path" \
+  WIKI_SERVE_PORT="$serve_port" \
+  WIKI_MCP_PORT="$mcp_port" \
+    docker compose "${compose_env_args[@]}" -f "$ROOT_DIR/docker-compose.yml" run --rm wiki init
+
+  printf 'Workspace ready: %s\n' "$target_path"
+  printf 'Start with:      wiki-workspace up %s\n' "$workspace"
+}
+
+up_workspace() {
+  local workspace="$1"
+  local open_browser="${2:-0}"
+  need_workspace_env "$workspace"
+  local ws_path
+  ws_path="$(normalize_path "$(workspace_value "$workspace" WIKI_WORKSPACE_PATH)")"
+  ensure_workspace_dirs "$ws_path"
+
+  compose_for_workspace "$workspace" up -d serve mcp-http production-mcp
+
+  local serve_port prod_port
+  serve_port="$(workspace_value "$workspace" WIKI_SERVE_PORT 3100)"
+  prod_port="$(workspace_value "$workspace" PRODUCTION_MCP_PORT 3102)"
+  printf 'Workspace UI: http://localhost:%s\n' "$serve_port"
+  printf 'Chat:         http://localhost:%s/chat\n' "$serve_port"
+  printf 'Production:   http://localhost:%s/mcp/\n' "$prod_port"
+  printf 'External MCPs: see %s\n' "$ROOT_DIR/mcp.endpoints.json"
+
+  if [[ "$open_browser" == "1" ]]; then
+    wait_and_open "http://localhost:${serve_port}/chat" &
+  fi
+}
+
+main() {
+  if [[ $# -eq 1 && "$1" =~ ^(-h|--help|help)$ ]]; then
+    usage
+    exit 0
+  fi
+
+  if [[ $# -eq 1 && "$1" == "list" ]]; then
+    list_workspaces
+    exit 0
+  fi
+
+  # config <workspace> [path]
+  if [[ $# -ge 2 && "$1" == "config" ]]; then
+    local cfg_workspace="$2"
+    local cfg_path="${3:-}"
+    if [[ -n "$cfg_path" ]]; then
+      config_workspace "$cfg_workspace" "$cfg_path"
+    else
+      config_workspace "$cfg_workspace"
+    fi
+    exit 0
+  fi
+
+  # up <workspace> [--open]
+  if [[ $# -ge 2 && "$1" == "up" ]]; then
+    local up_open=0
+    [[ "${3:-}" == "--open" ]] && up_open=1
+    up_workspace "$2" "$up_open"
+    exit 0
+  fi
+
+  # agents <subcommand> [args...]
+  if [[ $# -ge 1 && "$1" == "agents" ]]; then
+    local agents_sub="${2:-up}"
+    if [[ $# -ge 2 ]]; then
+      shift 2
+    else
+      shift 1
+    fi
+    agents_compose "$agents_sub" "$@"
+    exit 0
+  fi
+
+  [[ $# -ge 2 ]] || { usage; exit 2; }
+
+  local scope="$1"
+  [[ "$scope" == "wiki" ]] || die "unknown scope: $scope (expected: wiki, agents, up, config, or list)"
+  shift
+  [[ $# -ge 2 ]] || die "wiki requires a workspace and a command"
+
+  local workspace="$1"
+  local command="$2"
+  shift 2
+
+  case "$command" in
+    init)
+      run_wiki "$workspace" init "$@"
+      ;;
+    up)
+      compose_for_workspace "$workspace" up -d serve mcp-http production-mcp
+      local serve_port production_port
+      serve_port="$(workspace_value "$workspace" WIKI_SERVE_PORT 3100)"
+      production_port="$(workspace_value "$workspace" PRODUCTION_MCP_PORT 3102)"
+      printf 'Workspace UI: http://localhost:%s\n' "$serve_port"
+      printf 'Chat MCP:     http://localhost:%s/chat\n' "$serve_port"
+      printf 'Production:   http://localhost:%s/mcp/\n' "$production_port"
+      ;;
+    down)
+      compose_for_workspace "$workspace" down
+      ;;
+    logs)
+      local log_args=()
+      read_lines_into_array log_args logs_args "$@"
+      compose_for_workspace "$workspace" logs "${log_args[@]}" serve mcp-http production-mcp
+      ;;
+    serve)
+      local open_browser=0
+      if [[ $# -eq 1 && "$1" == "--open" ]]; then
+        open_browser=1
+      elif [[ $# -ne 0 ]]; then
+        die "serve accepts only --open as optional flag; port is configured in the workspace .env"
+      fi
+
+      printf 'Starting mcp-http...\n'
+      compose_for_workspace "$workspace" up -d mcp-http
+      printf 'Starting production-mcp...\n'
+      compose_for_workspace "$workspace" up -d production-mcp
+      local serve_port production_port
+      serve_port="$(workspace_value "$workspace" WIKI_SERVE_PORT 3100)"
+      production_port="$(workspace_value "$workspace" PRODUCTION_MCP_PORT 3102)"
+      printf 'Workspace UI: http://localhost:%s\n' "$serve_port"
+      printf 'Chat MCP:     http://localhost:%s/chat\n' "$serve_port"
+      printf 'Production:   http://localhost:%s/mcp/\n' "$production_port"
+      printf 'Note: compose logs may show http://localhost:3000, which is the container port.\n'
+      if [[ $open_browser -eq 1 ]]; then
+        wait_and_open "http://localhost:${serve_port}" &
+      fi
+
+      compose_for_workspace "$workspace" up serve
+      ;;
+    doctor|ingest|build|export)
+      run_wiki "$workspace" "$command" "$@"
+      ;;
+    run)
+      [[ $# -gt 0 ]] || die "run requires wiki CLI args"
+      run_wiki "$workspace" "$@"
+      ;;
+    -h|--help|help)
+      usage
+      ;;
+    *)
+      die "unknown command: $command"
+      ;;
+  esac
+}
+
+main "$@"