> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kiwifs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# FAQ

> Frequently asked questions about KiwiFS installation, agents, search, and deployment.

<AccordionGroup>
  <Accordion title="What is KiwiFS?">
    A markdown filesystem for agents and teams — a single Go binary with a web UI, git versioning, full-text and vector search, and access via REST, MCP, NFS, S3, WebDAV, and FUSE.
  </Accordion>

  <Accordion title="How is this different from Obsidian?">
    Obsidian is a desktop app. KiwiFS is a server with a web UI, agent APIs, git audit trail, and server-side search over the same markdown files.
  </Accordion>

  <Accordion title="How is this different from Notion or Confluence?">
    Those tools store content in proprietary databases. KiwiFS stores plain markdown. `cat page.md` and `git clone` always work.
  </Accordion>

  <Accordion title="Do I need to know Git?">
    No. Git runs under the hood; the API and web UI hide it. Git is the audit trail, not the primary interface.
  </Accordion>

  <Accordion title="Is KiwiFS production-ready?">
    KiwiFS is in active development (currently v0.19). Core features are stable in internal production use. Public APIs may evolve before v1.0.
  </Accordion>
</AccordionGroup>

## Installation

<AccordionGroup>
  <Accordion title="System requirements?">
    A single static Go binary. SQLite is embedded. The web UI is embedded via `go:embed`. Runs on macOS, Linux, and Docker.
  </Accordion>

  <Accordion title="How do I install?">
    ```bash theme={null}
    brew install kiwifs/tap/kiwifs
    # or
    curl -fsSL https://raw.githubusercontent.com/kiwifs/kiwifs/main/install.sh | sh
    # or
    go install github.com/kiwifs/kiwifs@latest
    ```
  </Accordion>

  <Accordion title="What is in .kiwi/?">
    Derived state — not your content. Safe to delete and rebuild with `kiwifs reindex`.

    ```text theme={null}
    .kiwi/
    ├── config.toml
    ├── playbook.md
    ├── state/search.db
    ├── comments/
    └── templates/
    ```
  </Accordion>
</AccordionGroup>

## Agents

<AccordionGroup>
  <Accordion title="How do agents write?">
    Three ways:

    1. **Filesystem** — NFS or FUSE mount: `cat`, `echo`, `grep`
    2. **REST** — `PUT /api/kiwi/file`
    3. **MCP** — `kiwifs mcp --root ~/knowledge` (60+ tools)
  </Accordion>

  <Accordion title="Can agents use KiwiFS without a running server?">
    Yes. `kiwifs mcp --root ~/knowledge` runs in-process against the directory. No HTTP needed.
  </Accordion>

  <Accordion title="How do I configure Cursor or Claude Desktop?">
    ```json theme={null}
    {
      "mcpServers": {
        "kiwifs": {
          "command": "kiwifs",
          "args": ["mcp", "--root", "/path/to/knowledge"]
        }
      }
    }
    ```

    See [MCP](/concepts/mcp).
  </Accordion>

  <Accordion title="How does provenance tracking work?">
    Send `X-Actor` and `X-Provenance` on writes. KiwiFS injects `derived-from` into frontmatter automatically.
  </Accordion>
</AccordionGroup>

## Search

<AccordionGroup>
  <Accordion title="What search backends exist?">
    | Tier | Engine                                |
    | ---- | ------------------------------------- |
    | 1    | `grep` (zero deps)                    |
    | 2    | `sqlite` (FTS5, BM25 — default)       |
    | 3    | Vector (`[search.vector]` — optional) |
  </Accordion>

  <Accordion title="Vector search without a cloud API key?">
    Use Ollama as the embedder and `sqlite-vec` as the store for fully local semantic search.
  </Accordion>

  <Accordion title="Rebuild the index?">
    ```bash theme={null}
    kiwifs reindex --root ./knowledge
    ```
  </Accordion>
</AccordionGroup>

## Protocols

<AccordionGroup>
  <Accordion title="NFS vs S3 vs WebDAV vs FUSE?">
    | Protocol | Best for                           |
    | -------- | ---------------------------------- |
    | NFS      | Docker / Kubernetes mounts         |
    | S3       | Backup tools, pipelines            |
    | WebDAV   | Desktop sync, mapped drives        |
    | FUSE     | Developer workstation remote mount |

    See [Alternate protocols](/guides/alternate-protocols).
  </Accordion>

  <Accordion title="Do all protocols share one pipeline?">
    Yes. Every write gets git commit, index update, and SSE broadcast regardless of entry protocol.
  </Accordion>
</AccordionGroup>

## Data

<AccordionGroup>
  <Accordion title="Crash mid-write?">
    Atomic writes (temp → fsync → rename). Git reflog aids recovery.
  </Accordion>

  <Accordion title="Backup?">
    * `git push` to any remote
    * `kiwifs backup` / `[backup]` in config
    * `kiwifs restore --from ... --to ...`
    * `rsync` the knowledge root
  </Accordion>

  <Accordion title="Migrate from Obsidian or Notion?">
    ```bash theme={null}
    kiwifs import --from obsidian --path ~/vault --root ./knowledge
    kiwifs import --from notion --api-key $KEY --database-id $ID --root ./knowledge
    ```
  </Accordion>
</AccordionGroup>

## License

<AccordionGroup>
  <Accordion title="Commercial use?">
    BSL 1.1 — self-host and embed freely. You cannot offer KiwiFS itself as a commercial hosted service. Each release converts to Apache 2.0 after four years.
  </Accordion>

  <Accordion title="Contribute?">
    See [CONTRIBUTING.md](https://github.com/kiwifs/docs/blob/main/CONTRIBUTING.md).
  </Accordion>
</AccordionGroup>