Verify README installation and setup instructions work end-to-end

[mfafore22]

Goal

Walk through the README installation and CLI workflow on a fresh clone to verify that all documented steps work as written. Identify and document any gaps, errors, or unclear instructions.

Motivation

The README documents a four-step workflow (crawl → parse → vectorize → tapio-app) and lists specific prerequisites. As a contributor onboarding to the project, I want to confirm everything works as described so new contributors don't hit blockers.

Verification checklist

Prerequisites

• Python 3.10+ check works
• uv installation instructions are sufficient
• Ollama installation works on Windows/macOS/Linux

Setup

• git clone works
• uv sync completes without errors and installs all dependencies
• ollama pull llama3.2 succeeds and model is available

CLI workflow

• uv run -m tapio.cli --help displays all commands
• uv run -m tapio.cli list-sites shows configured sites
• uv run -m tapio.cli list-sites --verbose shows detailed configs
• uv run -m tapio.cli crawl migri --depth 2 runs without errors
• uv run -m tapio.cli parse migri produces parsed Markdown
• uv run -m tapio.cli vectorize builds the vector store
• uv run -m tapio.cli tapio-app launches the chatbot UI

Tests

• uv run pytest runs and passes

What I'll deliver

After running through the checklist, I'll comment on this issue with:

1. Steps that worked as written
2. Steps that failed, with full error output
3. Any missing prerequisites or unclear instructions
4. Specific README sections that need updates

If problems are found, follow-up PR(s) to fix the documentation.

Environment

• OS: Windows (will note version)
• Python version: 3.12
• uv version: (will check)
• Ollama version: (will check)

[mfafore22]

Full verification complete

Environment

• OS: Linux (GitHub Codespaces)
• Python: 3.12.10
• uv: 0.11.25
• Ollama: installed at /usr/local/bin/ollama
• Model: llama3.2:latest (2.0 GB)

Verified working

• git clone and cd tapio
• uv sync installs all dependencies cleanly
• ollama pull llama3.2 downloads the model successfully
• uv run -m tapio.cli --help shows all commands
• uv run -m tapio.cli list-sites lists all 5 configured sites
• uv run -m tapio.cli crawl migri --depth 2 crawls and saves HTML files
• uv run -m tapio.cli parse migri converts HTML to Markdown (77 files processed)
• uv run -m tapio.cli vectorize builds ChromaDB store (78 files, 966 chunks)
• uv run -m tapio.cli tapio-app launches Gradio UI at http://127.0.0.1:7860
• App connects to Ollama and retrieves relevant documents
• uv run pytest all 176 tests pass

Issues found

1. Ollama installation step is incomplete

README links to https://ollama.ai/ but does not include install command.

2. LLM generation is too heavy for default Codespaces (OOM)

When sending a query through tapio-app:

[mfafore22]

llama3.2 (2GB) is too heavy for default Codespaces memory.

3. CLI has undocumented commands

info and dev exist in CLI but are not in README workflow.

Follow-up

Opened PR #53 to address items 1 and 2.
Item 3 will follow in a separate PR.