ds4 wiki profile

1. Where it fits

ds4-server is the local model server used by Claude, Codex, Pi, or other clients. ds4-agent is different: it is a native terminal coding agent with its own tool loop. A wiki profile should use ds4-agent, not a bare chat client, because LLM Wiki workflows need file reads, targeted search, writes, edits, and shell checks.

Use ds4c-wiki as an opt-in side command. Do not replace a working Claude, Codex, OpenCode, or Pi profile until the native profile passes repeatable wiki fixtures and real repo tests.

2. Portable local defaults

Keep the public guide generic and put workstation-specific values in your private shell. Use placeholders like ~/src/ds4, ~/agent-workspace/llm-wiki, ~/models/model.gguf, and ~/wiki; override them locally with environment variables.

• Before sharing snippets, redact local usernames, hostnames, LAN or VPN IPs, SSH host fingerprints, tokens, trace files, and raw session transcripts.
• Keep ~/.config/llm-wiki/config.json portable: prefer hub_path with ~, not a machine-specific absolute path.
• Keep .sessions/ operational. Promote only distilled, redacted lessons into topic raw/notes/.

3. Inputs

The profile needs three local ingredients: a ds4 checkout, a model file, and an LLM Wiki instruction file. The examples below are intentionally generic.

mkdir -p ~/.config/llm-wiki
cat > ~/.config/llm-wiki/config.json <<'JSON'
{
  "hub_path": "~/wiki"
}
JSON

# Optional local overrides for this shell only.
export DS4_REPO="$HOME/src/ds4"
export DS4_MODEL="$HOME/models/deepseek-v4-flash-q2.gguf"
export LLM_WIKI_REPO="$HOME/agent-workspace/llm-wiki"

4. Profile script

This zsh profile builds a system prompt from a short DS4 role plus the LLM Wiki instruction file, then starts ds4-agent in the current workspace with --chdir. It keeps machine-specific paths in environment variables instead of hard-coding them into the guide.

mkdir -p ~/.config/ai
cat > ~/.config/ai/ds4-wiki.zsh <<'EOF'
# ds4c-wiki: native ds4-agent profile for LLM Wiki workflows.
# Public-safe defaults use generic paths. Override with env vars locally.

_wiki_instruction_file() {
  local explicit="${WIKI_INSTRUCTIONS:-}"
  if [[ -n "$explicit" ]]; then
    [[ -r "$explicit" ]] || { echo "WIKI_INSTRUCTIONS is not readable: $explicit" >&2; return 1; }
    printf '%s\n' "$explicit"
    return 0
  fi

  local checkout="${LLM_WIKI_REPO:-$HOME/agent-workspace/llm-wiki}"
  local candidate
  for candidate in \
    "$checkout/plugins/llm-wiki-opencode/skills/wiki-manager/SKILL.md" \
    "$checkout/AGENTS.md"; do
    [[ -r "$candidate" ]] && { printf '%s\n' "$candidate"; return 0; }
  done

  echo "No LLM Wiki instruction file found. Set LLM_WIKI_REPO or WIKI_INSTRUCTIONS." >&2
  return 1
}

_ds4_wiki_system_prompt() {
  local target_cwd="$1"
  local instruction_file
  instruction_file="$(_wiki_instruction_file)" || return 1

  {
    printf '%s\n' "You are ds4c-wiki, a native ds4-agent profile for LLM Wiki workflows."
    printf '%s\n' "Target workspace: $target_cwd"
    printf '%s\n' "Use --chdir/current workspace paths for project files; do not assume the ds4 source directory is the user project."
    printf '%s\n' "When the user says wiki, @wiki, /wiki, wiki research, wiki query, or similar, follow the LLM Wiki workflow."
    printf '%s\n' "Resolve the hub from ~/.config/llm-wiki/config.json, read indexes first, choose a topic, then use targeted reads/searches."
    printf '%s\n' "Do not broad-scan home directories, unrelated source trees, or dependency folders for wiki tasks."
    printf '%s\n' "Keep session memory and feedback candidates operational until the user explicitly promotes them into a topic."
    printf '%s\n\n' "The LLM Wiki instruction file follows: $instruction_file"
    cat "$instruction_file"
  }
}

ds4c-wiki() {
  emulate -L zsh

  local target_cwd="$PWD"
  local repo="${DS4_REPO:-$HOME/src/ds4}"
  local model="${DS4_MODEL_FILE:-${DS4_MODEL:-}}"
  local system_prompt
  local -a ds4_args agent_args

  [[ -x "$repo/ds4-agent" ]] || { echo "ds4-agent not found at $repo/ds4-agent" >&2; return 1; }

  if [[ -z "$model" ]]; then
    model="$(find "$repo" -name '*.gguf' -print -quit 2>/dev/null)"
  fi
  [[ -f "$model" ]] || { echo "No GGUF model found. Set DS4_MODEL to a model file." >&2; return 1; }

  system_prompt="$(_ds4_wiki_system_prompt "$target_cwd")" || return 1

  ds4_args=(-m "$model" -c "${DS4_CTX:-100000}" --chdir "$target_cwd" --nothink)
  agent_args=(-sys "$system_prompt")

  if [[ "${DS4C_WIKI_NON_INTERACTIVE:-}" == "1" || "${DS4C_WIKI_NON_INTERACTIVE:-}" == "true" ]]; then
    agent_args+=(--non-interactive)
  fi
  if (( $# )); then
    agent_args+=(-p "$*")
  fi

  "$repo/ds4-agent" "${ds4_args[@]}" "${agent_args[@]}"
}

alias dsa-wiki=ds4c-wiki
EOF

source ~/.config/ai/ds4-wiki.zsh

Optional personal alias after local testing:

# Optional: add this to your own shell after local testing passes.
alias dsw='ds4c-wiki'

# Keep the profile opt-in. Do not replace claude, codex, opencode, or pi.
# Keep DS4 traces and .sessions digests out of public repos unless redacted.

5. Smoke tests

First prove that the wrapper launches and that the wiki routing instructions are visible. The second command should report the hub it would use and stop; it should not scan your home directory.

source ~/.config/ai/ds4-wiki.zsh
DS4C_WIKI_NON_INTERACTIVE=1 ds4c-wiki "reply with exactly OK"
DS4C_WIKI_NON_INTERACTIVE=1 ds4c-wiki "wiki status: tell me which wiki hub you would use, then stop"

6. Disposable wiki fixture

Run the first real wiki task in a temporary directory and force a local .wiki/. The pass condition is structural: files are created under the fixture, the answer is grounded in the local note, and no real hub is touched.

fixture="$(mktemp -d)"
cd "$fixture"
git init
cat > AGENTS.md <<'EOF'
Use only the local .wiki/ tree in this fixture. Do not read or write a real user hub.
Keep all sample content fictional.
EOF

DS4C_WIKI_NON_INTERACTIVE=1 ds4c-wiki \
  "Initialize a local LLM Wiki in .wiki, add one raw note about a fictional tool named ExampleClamp, then answer what ExampleClamp is from the local wiki."

find .wiki -maxdepth 4 -type f | sort
git status --short

Inspect the result manually. A good run creates a local wiki tree, records a small raw note, updates indexes or logs if the instruction path calls for it, and answers with an honest source reference or limitation.

7. Promotion gates

Promote the profile from experiment to daily helper only after it passes the same fixture more than once. Track pass/fail before token speed.

• Routing: resolves ~/.config/llm-wiki/config.json, reads indexes first, and chooses the right topic or local wiki.
• Containment: avoids broad scans of home directories, unrelated source trees, and dependency folders.
• Writes: keeps raw sources immutable, appends logs, and does not treat .sessions/ as topic evidence without promotion.
• Answer quality: cites wiki files when it has evidence and says what is missing when it does not.
• Repeatability: passes the disposable fixture and at least one real backup-safe topic test across several fresh sessions.

8. Gotchas

• --non-interactive is best for one-shot tests. Use the interactive TUI only after the profile is routing correctly.
• The DS4 source directory is not necessarily the user project. Passing --chdir "$PWD" keeps file tools pointed at the workspace you launched from.
• Keep model paths, hub paths, and wiki checkout paths in your shell config; publish placeholders when sharing examples.
• If a long wiki research run stalls, reduce scope before changing models: query/status first, then one raw note, then local fixture research, then real topic work.