Metadata-Version: 2.4
Name: si-deckhand
Version: 0.1.0
Summary: Lightweight local agent that indexes, retrieves, and wikis the workspace. The crew member who knows where everything is.
Author: SuperInstance
License-Expression: MIT
Keywords: agent,retriever,wiki,index,exo-filed,local
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: vector
Requires-Dist: numpy>=1.20; extra == "vector"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# deckhand

*The crew member who knows where everything is.*

---

**deckhand** is a lightweight local agent that indexes, retrieves, and wikis your workspace. File-first (exo-filed). Human-readable. No hidden database.

## What it does

- **Indexes** every file in your workspace (code, docs, configs)
- **Builds wiki pages** that a human can `cat` — REPOS.md, CONNECTIONS.md, GLOSSARY.md, STATUS.md
- **Searches** via BM25 (pure Python, no dependencies)
- **Batches tasks** from PLANNER_QUEUE.md, OPEN_QUESTIONS.md, and recent file changes
- **Studies** repos off-watch — writes daily observation logs
- **Runs forever** in a loop: index → wiki → batch → study → sleep → repeat

## Install

```bash
pip install deckhand
```

## Use

```bash
# Index the workspace and generate wiki
deckhand index /path/to/workspace

# Search for something
deckhand search /path/to/workspace "conservation law"

# Generate just the wiki
deckhand wiki /path/to/workspace

# Collect tasks into a batch
deckhand batch /path/to/workspace

# Run the deckhand loop forever (index → wiki → batch → study → sleep)
deckhand run /path/to/workspace --sleep 300
```

## The wiki output

After indexing, deckhand writes to `deckhand-wiki/`:

- **REPOS.md** — table of every repo, one line each. Health indicators (✅ ok, ⚠️ untested, 🔩 stub, ❌ no-readme)
- **CONNECTIONS.md** — cross-reference graph. Which repos reference which.
- **GLOSSARY.md** — top 100 terms across the workspace
- **STATUS.md** — health summary. Lists repos that need tests, need READMEs, or may be abandoned
- **INDEX.md** — machine-readable JSON index
- **BATCH.md** — collected tasks from PLANNER_QUEUE + OPEN_QUESTIONS + recent changes
- **logs/YYYY-MM-DD.md** — daily study observations

## Why exo-filed?

A vector database is opaque. You can't `cat` it. You can't grep it. You can't diff it in git.

deckhand's index is markdown + JSON. A human can open REPOS.md and understand the fleet in 30 seconds. An agent can read CONNECTIONS.md instead of re-reading 4,000 repos.

When the corpus gets too large for file-based search (>10K files), build the optional vector twin:

```python
from deckhand.vector_twin import VectorTwin  # coming in v0.2
```

The vector twin is ALWAYS accompanied by its file-twin. You can always fall back to the human-readable version.

## The maritime metaphor

On a boat, the deckhand is the crew member who:
- Knows where every line, every shackle, every tool is stored
- Prepares tasks for the captain (batches)
- Maintains the logbook (study logs)
- Studies charts off-watch (studies repos when idle)
- Doesn't need to be told what to do — knows the direction of the voyage

The deckhand doesn't replace the captain (the director model). The deckhand makes the captain more efficient by pre-processing the workspace into a form the captain can act on in fewer calls.

## License

MIT

---

*Built by SuperInstance. The deckhand knows where everything is.*
