# Curio
**A knowledge compiler and curation control plane for enterprise knowledge.** Git-native, multi-provider, and multi-workspace. Curio turns raw sources into a curated hierarchy and mirrors the result into Confluence for the humans who consume it.
[](CHANGELOG.md)
[](https://github.com/RyanMerlin/curio/actions/workflows/ci.yml)
[](#providers)
[](LICENSE)
---
## Why Curio
Most knowledge tools index documents. **Curio compiles them into governed knowledge, then mirrors the result into Confluence.**
Every intake source is judged against the existing tree, scored on seven dimensions, optionally rewritten, optionally consolidated with peers, and routed to `staged/`, `review/`, or `published/` with a proposal dossier that explains the decision. The Rust binary handles deterministic execution; the agent handles editorial judgment. Git is the system of record. Confluence is the read-only mirror your audience actually opens.
**Curio is not a page router. It is an information architect.**
Curio is the editorial control plane between source material and downstream
retrieval. The current product is deliberately proposal-first: agents make the
curation decisions, while `curio-rs` enforces deterministic filesystem, Git,
quality, and publication boundaries.
> "If a curation step cannot be explained as inference‑driven judgment, the step is too early."
> — `docs/design/operating-contract.md`
## What Curio does well
- **Hierarchy‑first synthesis.** The agent walks the existing tree's `index.md` summaries and peer pages near likely branches before proposing a path. Default bias is toward *deeper* placement, never the easiest shallow match.
- **Multi‑source consolidation.** Multiple sources from a single intake request can be consolidated into one curated proposal; the proposal dossier records every contributing source. Split workflows remain a future extension.
- **Agent‑authored bodies.** The agent ships a curated knowledge object, not a raw capture. Body rewrites land with a structured decision section explaining the scores, alternatives, and recommended action.
- **Continuous overlap detection.** Pages with high semantic overlap are flagged for merge or consolidation instead of becoming silent duplicates.
- **Self‑sharpening.** `curio sharpen --prepare` emits a manifest of restructure / merge / split candidates for the agent to act on.
- **Taxonomy mutations.** When no existing node fits, the agent proposes a new node against `NORTHSTAR.md`. Reviewers see a dedicated "Taxonomy mutation proposed" panel in Confluence before approving.
- **Deterministic safety boundaries.** Atomic registry writes, intake resume-after-crash, publish-time re-gate (quality + overlap + taxonomy validity rechecked at promotion), `--force` escape hatch with audit logging, JSON error envelopes, and a full `--dry-run` mode that **never** touches Confluence. Production Cloud Run hardening remains deferred.
## Why this holds up
A few things are deliberately concrete:
- **Deterministic core.** `curio-rs` makes no LLM calls and keeps the safety-sensitive pieces in Rust.
- **Explicit workspace boundaries.** Every command is scoped to a named workspace or KB path; the harness does not assume one global corpus.
- **Real quality gates.** Routing, publishing, and sync all re-check the corpus state instead of trusting stale inputs.
- **Automated verification.** The Rust suite runs under `cargo nextest`; CI exercises fmt, clippy, tests, and release builds.
- **Synthetic public fixtures.** The demo workspace and tracked examples are synthetic so the public repo stays safe to inspect and fork.
- **Deployment path is documented.** The GCP / Vertex AI path is described in-repo, with its current experimental status and production gaps called out explicitly.
## Enterprise knowledge posture
Curio follows the parts of enterprise knowledge management that remain useful
even when the retrieval model changes:
- **Trusted sources and provenance.** Every proposal retains source lineage,
alternatives, rationale, and the curation decision that produced it.
- **Explicit structure.** `NORTHSTAR.md` and the YAML taxonomy define an
inspectable ontology instead of relying on an opaque index or tags alone.
- **Human review for uncertainty.** Weak, stale, duplicative, or ambiguous
material is routed to `review/` rather than silently becoming canonical.
- **Freshness and maintenance.** Quality, overlap, freshness, and usability
are re-evaluated at publication; `sharpen` and `heal` provide proposal-only
maintenance loops.
- **Permission-aware deployment is still ahead.** A production service must
add authenticated identity, workspace-scoped credentials, and permission
trimming before it can safely ground enterprise users across multiple
repositories.
- **Published-only retrieval is deterministic and agent-ready.** The CLI
exposes a stable `retrieve --query ... --json` contract and a matching
`fetch --id ... --json` lookup, both with cited excerpts and provenance —
plus a local, read-only MCP server (`curio-mcp`) so any MCP-compatible
agent client can search and fetch curated knowledge directly. See
[Agent retrieval (MCP)](#agent-retrieval-mcp) below.
- **Adapters and page-level ACLs are roadmap work.** The adoption roadmap
sequences source adapters and permission-preserving retrieval before
enterprise connector claims. A first retrieval-quality baseline already
runs in CI — see
[`docs/design/retrieval-evaluation-baseline.md`](docs/design/retrieval-evaluation-baseline.md).
## The lifecycle
```
┌──────────┐ ┌───────────┐ ┌──────────┐ ┌──────────┐ ┌─────────────┐
│ intake │ -> │ process │ -> │ staged │ -> │ publish │ -> │ sync to │
│ wiki/ │ │ (agent) │ │ /review │ │ │ │ Confluence │
│ intake/ │ └───────────┘ └──────────┘ └──────────┘ └─────────────┘
└──────────┘ │ ▲
│ │ proposal, │ feedback signals
│ │ dossier, │ (👍 / 👎 / ❓ from
│ │ scores │ reviewers in Confluence)
│ ▼ │
│ ┌──────────┐ │
└────────> │ heal │ ────────────┘
│ sharpen │
└──────────┘
```
Every transition is git‑committed; every editorial decision lives in a `.proposal.json` dossier next to the page. The audit trail is the repo.
## Target use cases
| Use case | What Curio organizes | Why it fits |
|---|---|---|
| **Customer / account intelligence** | sanitized engagement notes, recurring patterns, post-engagement learnings | Keeps related accounts together and prevents duplicate lessons from scattering. |
| **Product knowledge bases** | install, configure, upgrade, troubleshoot per product / version | Deeper paths keep technical content discoverable as products evolve. |
| **Partner / channel knowledge** | partner programs, tiering, joint motions, partner-led playbooks | Confluence mirrors let partner-facing teams consume curated output without git literacy. |
| **FDE / SE use-case catalogs** | engagement patterns, solution recipes, anti-patterns | The sharpening loop turns failure analyses into reusable policy. |
| **Subject-matter references** | structured technical references with explicit taxonomy | NORTHSTAR.md is the editorial charter, and the agent enforces it. |
Each KB is a separate git repo with its own taxonomy, Confluence space, and credentials. A single Curio harness instance manages **N KBs** without cross-tenant leak.
## Get started
### First run: credential-free synthetic demo
The recommended public path needs no Confluence account, provider account, or
live enterprise data. It uses a temporary copy of the synthetic workspace and
verifies the full local lifecycle. Requires `bash`, `git`, `python3`, `perl`,
and a Rust toolchain (`cargo`) — the script builds `curio` from source on
first run if no binary is cached:
```sh
./scripts/show-hn-demo.sh
```
The demo exercises deterministic intake fixtures, agent-style routing, staged
and review lanes, proposal dossiers, publish re-gating, and the final
published tree. It never modifies `docs/wiki-demo/`.
For an agent-led setup intended for knowledge operators, see
[docs/agent-setup.md](docs/agent-setup.md).
You can also drive Curio four ways. Pick the path that matches your work.
### Option 0 — Download a release binary (no Rust toolchain)
```sh
# Linux (x86-64) — see the release page for macOS (aarch64-apple-darwin)
# and Windows (x86_64-pc-windows-msvc) archives
curl -LO https://github.com/RyanMerlin/curio/releases/latest/download/curio-x86_64-unknown-linux-gnu.tar.gz
curl -LO https://github.com/RyanMerlin/curio/releases/latest/download/SHA256SUMS
sha256sum --ignore-missing -c SHA256SUMS
tar -xzf curio-x86_64-unknown-linux-gnu.tar.gz # unpacks curio and curio-mcp
CURIO_BIN=./curio ./scripts/show-hn-demo.sh # run the credential-free demo, no cargo needed
```
Every release archive is built and packaged by CI from the tagged commit;
checksums are generated in the same run, not on a maintainer laptop.
### Option 1 — Service via Docker (local shared use)
This is the local service path for shared development. The Cloud Run deployment
files are an experimental staging path, not a claim that the hosted service is
ready for unrestricted enterprise production.
```sh
# from this repo
cd deploy/local
cp .env.example .env # paste your Confluence token
docker compose up -d --build
curl http://localhost:8080/healthz
./smoke-test.sh # exercises all 3 KBs end‑to‑end
```
Then post a job:
```sh
curl -X POST http://localhost:8080/v1/jobs \
-H 'Content-Type: application/json' \
-d '{"job_type":"intake","workspace_id":"demo-workspace","operation":"intake",
"actor":{"kind":"human","id":"you"},"trigger":{"kind":"manual"},
"write_mode":"direct_push",
"inputs":{"args":["--url","https://yourorg.atlassian.net/wiki/spaces/X/pages/123"]}}'
```
### Option 2 — CLI (local development and real KBs)
```sh
cd curio-rs && cargo build --release --bin curio
./target/release/curio --workspace