# CAgneT Knowledge

Independent MCP server for querying a locally provisioned choir knowledge base,
proposing reviewable changes, and explicitly merging pending changes. This
repository contains the service implementation and Agent Skills only; it does
not contain the private business knowledge collection.

The service exposes:

- `cagnet_query`: grounded read-only work over the local collection.
- `cagnet_modify`: append a reviewable pending proposal without editing formal knowledge.
- `cagnet_merge`: explicitly merge all pending proposals with an audit log and recovery journal.

The validated IMBot integration restricts all three tools to root private
conversations. Another host must implement an equivalent deterministic policy.

## Platform and runtime requirements

The current isolation implementation requires macOS and
`/usr/bin/sandbox-exec`. It also requires Python 3.11 or newer, an `opencode`
executable, and a configured OpenCode provider. Other operating systems are not
currently supported and must not silently run without equivalent isolation.

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
BOT_CAGNET_TOKEN=replace-me \
BOT_CAGNET_OPENCODE_MODEL=provider/model \
./start.sh
```

`start.sh` loads `.env` when present. Stop with `./stop.sh`. Generated OpenCode
configuration, credentials, databases, caches, temporary files, PID files, and
logs remain under ignored `.data/` and `.run/` directories.

Configuration:

- `BOT_CAGNET_TOKEN` (required)
- `BOT_CAGNET_URL` (default `http://127.0.0.1:3121/mcp`)
- `BOT_AUTH_ISSUER_URL` (default `http://localhost/internal-auth`)
- `BOT_CAGNET_OPENCODE_BINARY` or `BOT_OPENCODE_BINARY`
- `BOT_CAGNET_OPENCODE_MODEL` or `BOT_OPENCODE_MODEL`
- `BOT_CAGNET_OPENCODE_VARIANT`
- `BOT_CAGNET_OPENCODE_TIMEOUT_SECONDS`
- `BOT_CAGNET_OPENCODE_CONFIG` and `BOT_CAGNET_OPENCODE_AUTH`
- `BOT_CAGNET_DATA_ROOT`
- `CAGNET_HOST`, `CAGNET_PORT`, and optional `PYTHON_BIN`

## Provision private knowledge

Place the private collection under:

```text
cagnet_knowledge/workspace/knowledge/
```

The directory is intentionally ignored except for `.gitkeep`. Never commit its
formal documents, `_pending_changes`, `_merge_logs`, recovery journals, or any
OpenCode auth/runtime data. An empty checkout has no business knowledge and is
not ready for meaningful queries until an authorized operator provisions it.

The internal role instructions are under
`cagnet_knowledge/workspace/skills/`. Outer-Agent tool and reply guidance is in
`skills/cagnet-knowledge/SKILL.md`; component metadata is in `addon.toml`.

## Integrating with IMBot

Give the Agent this repository URL. The Agent should install it, provision the
knowledge directory separately, configure an MCP URL and token, reproduce the
root-private permission mapping, install the outer Skill, and run both this
repository's tests and the host integration tests. Do not weaken the sandbox or
copy host credentials into the repository.

## Test

```bash
.venv/bin/python -m unittest discover -s tests
```

Unit tests use temporary knowledge trees and do not require or read the private
collection.