Getting Started

Three ways in, by commitment level: run the demo (30 seconds, no install), install the CLI (one command), or connect your first project (the real loop). Alpha reality check: the demo is deterministic and works everywhere; real-fabric setup is the alpha part — expect rough edges, and file issues for anything that bites.

1. The 30-second proof (no install)

git clone https://github.com/hybridindie/wiki-fabric
cd wiki-fabric
bash scripts/demo.sh

The demo builds a throwaway fabric with one pattern, one anti-pattern, and one project decision — then compiles a task context showing the agent being told to avoid a banned approach before writing code. See the transcript on the homepage. Run bash scripts/demo.sh --json for the machine-checkable manifest.

2. Install the wf CLI

Recommended (packaged, atomic):

uv tool install wiki-fabric            # the tool + CLI
uv tool install wiki-fabric --with mcp # + the wf-mcp MCP server

Install/update are owned by uv (uv tool upgrade wiki-fabric) — no CLI/harness drift, no script copies. The packaged CLI works on Windows (pure-python dispatch); git hooks are POSIX-only — see Requirements.

Alternative (one-liner, dev mode):

# installs uv if missing, clones the harness to ~/.wiki-fabric, creates
# the fabric at ~/.local/share/wiki-fabric, installs the wf CLI at ~/.local/bin/
curl -fsSL https://raw.githubusercontent.com/hybridindie/wiki-fabric/main/scripts/wiki-fabric.sh | bash

Install flags:

Flag	Effect
--corpus <git-url>	Point the fabric at a team-shared corpus. Teammate join: if the remote already carries a corpus, it's pulled at install — the fabric carries the team's knowledge from the first command. Lead machine: publishes the initial corpus. See Team Sync
--vault <path>	Pin where the Obsidian vault shell lives (written to fabric.yaml so every later wf call resolves the same place)
--with-graphify	Enable the graphify integration (see Integrations)
--dir <path>	Harness clone location (default ~/.wiki-fabric)
--repo <url>	Install from a fork
--interactive	Walk through provider/model/routing config (prompts for everything — see Configuration)
--no-vault	Skip creating the Obsidian output vault

What the one-liner actually does: checks for uv (Astral's Python package manager) and installs it if missing, clones the harness (the code — this repo) to ~/.wiki-fabric (use --dir to choose another spot), creates the fabric (your content

• config) at ~/.local/share/wiki-fabric/ (XDG data dir), sets up the venv in the harness, and symlinks wf into ~/.local/bin/. Everything Python runs inside that venv — no system pip pollution, no version drift. If uv can't be installed, wf falls back to plain python3 (core CLI works; LLM features need a one-time pip install pyyaml openai anthropic (or any uv install). wf update re-syncs deps from pyproject.toml when it changes.

Harness vs fabric: the harness clone never holds your knowledge — it's a git clone of this public repo, refreshed by wf update (git pull). Your content (evidence/, projects/, patterns/, fabric.yaml, ...) lives in the fabric dir and syncs via Team Sync to a remote you own. Set WIKI_FABRIC_DIR to relocate the fabric.

All wf commands also work without any install — the scripts in scripts/ run with plain python3 from a clone (dev mode: a clone holding a fabric.yaml doubles as its own fabric).

Shell completions

wf <TAB> completes 45 verbs, their subcommands (wf mine chats|promotions, wf eval behavior|stability|…, wf sync resolve|commit-drift, …) and common flags per verb:

eval "$(wf completions bash)"                               # bash: .bashrc
wf completions zsh > "${fpath[1]}/_wf" && compinit          # zsh
wf completions fish > ~/.config/fish/completions/wf.fish    # fish

Static generation — works offline, degrades to verb-only completion if something's missing. See CLI & Scripts.

Manual installs

Packaged (same as the recommended path — pick your extras):

uv tool install wiki-fabric                 # CLI only
uv tool install wiki-fabric --with mcp      # + wf-mcp server
uv tool install wiki-fabric --with mcp --with fastembed
                                            # + semantic re-rank (embeddings tier)

Extras compose per machine: mcp (the MCP server), fastembed (the embeddings tier). The judgment tier doesn't need an extra: the local-first route runs on ollama decision models (ollama pull tev1:latest — the same System One wire, localhost, no key). Optional on-device judges: laya (cross-platform, typed heads) and laya-as-judge[mlx] (Apple Silicon's fastest). uv tool upgrade wiki-fabric keeps them.

Dev mode (run from a clone — for working on wiki-fabric itself):

git clone https://github.com/hybridindie/wiki-fabric wiki-fabric
cd wiki-fabric
uv venv && uv pip install -r pyproject.toml
mkdir -p ~/.local/bin
ln -sf "$PWD/scripts/wiki-fabric.sh" ~/.local/bin/wf
wf status

Dev mode runs the harness scripts directly (no package); a clone holding a fabric.yaml doubles as its own fabric.

Keeping up to date

wf update            # pull latest + rebuild index + re-sync deps
wf update --with-graphify   # also enable the graphify integration

3. Verify the install

wf status                            # fabric health + inventory
python3 -m pytest tests/ -m "not live" -q   # fast test suite
bash scripts/smoke-test.sh           # end-to-end CLI checks in a throwaway fabric
wf lint                              # fabric self-lint (0-error gate)

Tests marked live (run with plain pytest tests/ -q) exercise real on-device models and self-skip when the model isn't cached or the platform lacks the backend.

4. Connect your first project

# One-time: pick your LLM provider if Ollama isn't your choice
# (see Configuration — or run `wf install --interactive` to be prompted)

wf bootstrap /path/to/my-project      # connect a project (copies the decided model config
                                      # from fabric.yaml; routing via --extract/--synthesize/--dossier)
                                       # (hook installed automatically by bootstrap; --no-hook skips)
wf capture my-project                 # pull docs from upstream repos → evidence/raw/
wf capture chat my-project            # capture agent chat sessions → evidence/raw/my-project/chats/
wf ingest evidence/raw/my-project/docs/readme.md --extract-claims
wf query "Why does my code batch writes?"
wf log --project my-project --problem "..." --intervention "..." --outcomes "..."   # log an experience event: problem → what you did → measured outcome

wf context --task "..." --write-receipt   # what the agent receives before a task
wf gate                              # session-start: pending human decisions
wf review --auto-reverify            # clear the mechanical review debt (0 tokens)
wf freshness                         # pull the team cycle's refreshed evidence (or run it locally)
wf export wiki                       # generate the human wiki (topics, projects, staleness)
wf wiki-generate begin --project my-project   # writer/bookkeeper narrative generation
wf publish                           # Quartz static site → <vault>/site/public (serve or host it)
wf mine chats my-project             # distill chat transcripts into patterns/anti-patterns

The first agent session (what the harness actually runs)

With the fabric installed and the always-on block loaded, an agent's first session looks like this (each step is a real command with real output):

1. wf context --task "Add token rotation to the OAuth service" --write-receipt
   receipt: .../receipts/receipt-2d253c6d98c7.json (receipt-2d253c6d98c7)
   ## Selected
   - [[claim-...-git-issue-812-md-005]] — task evidence (claim): window
     *decided in: [[src-alpaca-agents-git-issue-812-md]]*   ← provenance: open the PR
   ## Excluded
   - patterns/pattern-stale.md — stale: review_after overdue 255 days
   (0 tokens; every inclusion AND exclusion carries a reason)

2. wf query "does anything ban caching tokens here?"       # 0 tokens

3. ← the agent writes code (live evidence is the harness's job)

4. wf log --project auth-service --receipt receipt-2d253c6d98c7 \
      --problem "refresh tokens never rotated" \
      --intervention "rotation on refresh, reuse detects replay" \
      --outcomes "replay rejects live in staging"
   # receipt ↔ outcome: the delivery is now auditable — was it
   #   solved with what was known at session start?

5. wf gate                                                  # nothing pending → exit clean

Steps 1–2 and 5 cost zero LLM tokens; step 4 is file write. The LLM is spent only on extraction/synthesis when YOU capture new sources — the agent's session flow itself is free.

Optional: make it a team system

The fabric above is single-node by default. To make it a team system (teammates inherit the corpus from their first install):

wf sync setup    # gh CLI creates <owner>/wiki-fabric-corpus (private) and publishes
                 # your corpus; prints the teammate one-liner. See Team Sync.

Deterministic steps (capture, context, receipts, navigation) work fully offline before and after — the corpus sync is for teams, not for the loop.

wf bootstrap writes .wiki-overlay.md into the project, creates its namespace in the fabric, and additively merges agent config (never overwrites your MCP setup). Then Core Workflows takes over: capture → ingest → query, with scenarios for onboarding, dependency audits, and compiling PR history.

Automate the loop (opt-in)

wf harness install                 # configure every detected agent harness
                                   # (--all for the full matrix; --only claude,copilot)
wf hook install --extract-claims   # doc-drift commits auto-capture + auto-ingest

Requirements

Python	3.11+ (uv installs its own)
git	any recent version
LLM endpoint	anything OpenAI-compatible — Ollama (curl -fsSL https://ollama.com/install.sh | sh) is the zero-config default; see Configuration for OpenAI/OpenRouter/etc.
Local models (optional)	the judgment tier needs no extra — ollama pull tev1:latest (local-first default). On-device extraction weights: pip install -e ".[local]" (dev) or uv tool install --reinstall wiki-fabric --with laya — see Integrations
Git hooks	required for the freshness guarantee — wf hook install per project (drift-gated: unchanged docs cost 0 tokens; LLM only with --extract-claims)
Platform	macOS / Linux (Windows untested; git hooks are POSIX-verified only)

Agent harness support

wf harness install configures every agent tool it detects (or --all):

Harness	Always-on instructions	Skills	Session capture
Claude Code	CLAUDE.md + AGENTS.md	.claude/skills/ (native skills)	✅ ~/.claude/projects/ (JSONL)
opencode	AGENTS.md + opencode.json merge	.opencode/skill/ + plugin	✅ ~/.local/share/opencode/opencode.db (SQLite)
OpenAI Codex CLI	AGENTS.md (native)	—	✅ ~/.codex/sessions/ (JSONL, #113)
Gemini CLI	GEMINI.md	—	✅ ~/.gemini/tmp/*/chats/ (JSONL, #113)
GitHub Copilot	.github/copilot-instructions.md	—	—
Cursor	.cursor/rules/wiki-fabric.mdc	—	—
Pi	AGENTS.md / PI.md	—	—
Aider / Zed / Cline / Windsurf	CONVENTIONS.md / .rules / .clinerules/ / .windsurf/rules/	—	—

Session capture: wf capture chat <slug> reads installed harnesses' session stores (auto-detects what exists; --harness <name> to scope). Captured sessions carry the thread frontmatter (session id, files touched) that feeds the thread index (#102). Claude Code + opencode have native skill folders; others use the universal wf skill <name> on-demand procedures.

The instruction content is identical everywhere — the same always-on block, which includes the procedures pointer (wf skill <name>). Workflow procedures (ingest, promote, refresh) are printed on demand by wf skill <name> — a universal mechanism that works on every harness, no skill support required. Only Claude Code and opencode additionally get native skill folders (lazy-loaded, where that's a real feature). The conditional logic that used to live only in skill prose (graphify enrichment hints, anti-loop reminders) now lives in the commands themselves — wf tells you the next step when it matters.

Next steps

• Configuration — pick providers, set model tiers, route sensitive repos on-device
• Core Workflows — the full loop with scenarios
• Task Context — what the agent receives at task time
• Team Sync — share the corpus with a team