Metadata-Version: 2.4
Name: cadabby
Version: 0.4.0
Summary: Zero-dependency engine for Karpathy-style LLM Wiki vaults with OKF trust tiers
Keywords: llm-wiki,knowledge-base,mcp,okf,obsidian,sqlite
Author: Cadabby Contributors
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Text Processing :: Markup :: Markdown
Classifier: Topic :: Database
License-File: LICENSE
Project-URL: Documentation, https://github.com/naikoob/cadabby#readme
Project-URL: Issues, https://github.com/naikoob/cadabby/issues
Project-URL: Source, https://github.com/naikoob/cadabby

# Cadabby

> **Epistemically Auditable LLM Wiki Engine for Humans & AI Agents**

Cadabby is a zero-dependency, local-first engine and Model Context Protocol (MCP) server for maintaining living, high-density knowledge vaults. It enables AI agents (Claude Code, Google Antigravity, OpenHands, etc.) and humans (via Obsidian or CLI) to collaboratively build, cross-reference, and audit knowledge graphs anchored by Open Knowledge Foundation (OKF) epistemic trust tiers.

---

## Key Highlights

- **Zero Runtime Dependencies**: Built with 100% pure Python standard library (`CPython >= 3.11`). No pip dependencies.
- **Flat Canonical Synthesis**: `wiki/` is strictly flat (`wiki/*.md`); physical subdirectories in `wiki/` are forbidden. Navigation topology is editorial via Maps of Content (`type: moc`).
- **Autonomous Cognitive Domains**: Partition knowledge into independent cognitive domains (e.g., `customers/`, `projects/`) governed by localized `{domain}/AGENTS.md` manifests and arbitrary nested folder structures.
- **Disposable SQLite FTS5 Cache**: Ephemeral, high-performance full-text search and 1-hop graph traversals. Delete `.cadabby/cache.db` at any time with zero data loss.
- **Epistemic Trust Tiers**: Every note carries cryptographically bound attestation (`human-reviewed`, `machine-confirmed`, `stale-verified`, or `unverified`).
- **Drift-Induced Downgrade**: If an agent or user alters note prose without re-verification, its trust tier automatically downgrades to `stale-verified` (verification debt).
- **Deterministic Gap Report**: `index.md` is a focused worklist of entry points, unfiled notes, raw queue, and verification debt—never a bloated catalog.
- **Normative Six-Gate Linting**: Automated validation for schema, layout, link consistency, provenance, graph connectivity, and verification integrity.
- **Universal Harness Portability**: Works out-of-the-box with Claude Code (`.mcp.json`), Antigravity (native plugin & subagents), Gemini CLI, and Obsidian.

---

## 1. Installation

Cadabby is a command-line application, so install it as a tool rather than as a
library. Either of these puts `cadabby` on your `PATH` in its own isolated
environment, leaving your system Python untouched:

```bash
uv tool install cadabby    # recommended
pipx install cadabby       # equivalent
```

Verify:

```bash
cadabby --help
```

> **Why not `pip install`?** It works, but it drops Cadabby into whichever
> environment happens to be active, which makes the install easy to lose track of
> and easy to break with an unrelated upgrade. Nothing imports `cadabby` as a
> library, so there is no reason to put it on an interpreter's import path.

Cadabby has **zero runtime dependencies** (pure CPython >= 3.11 standard
library), so installation never pulls in a transitive dependency tree.

### Upgrading from 0.3.x

0.4.0 folds `vault_lint` into `vault_status` (`lint: true`) and adds
`vault_move_note`. The cache rebuilds itself; your vault needs two touches:

1. Run `cadabby install --all` in each vault to refresh the engine-owned skills,
   command shims and plugin.
2. In the vault's own `AGENTS.md` / `CLAUDE.md` (user-owned, never overwritten),
   replace `vault_lint` with `vault_status` with `lint: true`, and mention
   `vault_move_note` for renames and moves.

### Contributing

Working on Cadabby itself:

```bash
git clone https://github.com/naikoob/cadabby.git
cd cadabby
uv sync                    # or: pip install -e .

# Fast parallel test execution across all CPU cores (~25s, 536 tests):
python3 tests/run_parallel.py

# Canonical sequential test suite:
PYTHONPATH=src python3 -m unittest discover tests
```

---

## 2. Initializing a Vault

To scaffold a complete, production-ready knowledge vault:

```bash
# Initialize a new vault with Obsidian integration:
cadabby init --vault my-vault --name my-vault --obsidian
cd my-vault
```

This creates a standardized 3-layer vault layout:

```
my-vault/
├── .cadabby.json         # Vault configuration, trust multipliers & identities
├── .mcp.json             # Universal MCP server config (for Claude Code, Cursor, etc.)
├── AGENTS.md             # Canonical constitution / operational rules for all AI agents
├── CLAUDE.md             # Thin pointer delegating to AGENTS.md
├── GEMINI.md             # Thin pointer delegating to AGENTS.md
├── STYLE.md              # Vault-specific prose and citation guidelines
├── index.md              # Deterministic gap report (entry points, unfiled notes, raw queue, verification debt)
├── log.md                # Append-only activity ledger
│
├── raw/                  # Ground truth sources (PDFs, raw text, research papers)
│
├── wiki/                 # Flat canonical knowledge domain (strictly wiki/*.md)
│   ├── Architecture.md   # Concepts, entities, syntheses (typed via frontmatter)
│   └── Systems-MOC.md    # Maps of Content (type: moc) governing vault topology
│
├── customers/            # (Optional) Cognitive domain with autonomous AGENTS.md
│   ├── AGENTS.md         # Domain constitution & schema rules
│   └── acme-corp/        # Flexible, arbitrary nested subdirectory layout
│
├── templates/            # (Optional) Starter note templates, excluded from discovery
│
├── .agents/skills/       # Reusable skills: librarian and technician
├── .claude/commands/     # Claude Code slash commands (/ingest, /vault-status, /vault-lint)
└── .obsidian/            # (Optional) Pre-tuned Obsidian desktop settings
```

---

## 3. How to Use Cadabby

### Workflow A: Using AI Agents (Claude Code, Cursor, Windsurf)

1. **Drop a ground truth document** into `raw/`:
   ```bash
   cp ~/Downloads/attention-paper.pdf raw/attention-paper.pdf
   ```

2. **Start your agent inside the vault directory**:
   ```bash
   claude
   ```
   *Claude Code automatically reads `.mcp.json`, launches `cadabby mcp`, and reads `CLAUDE.md` $\rightarrow$ `AGENTS.md`.*

3. **Interact naturally using slash commands or chat**:
   ```
   > /ingest raw/attention-paper.pdf
   ```
   The agent will:
   - Call `vault_search` to check if related concepts already exist.
   - Call `vault_ground` to inspect existing notes and their 1-hop links.
   - Call `vault_scaffold_note` to draft `wiki/Flash-Attention.md` citing `raw/attention-paper.pdf`.
   - Add `[[wikilinks]]` to existing notes and suitable Maps of Content (`[[AI-Systems-MOC]]`).
   - Call `vault_verify_note` stamping the note with `agent:claude-code`.
   *(The `index.md` gap report and the `log.md` ledger are kept up to date implicitly; no manual sync needed).*

### Workflow B: Using Google Antigravity

1. **Install the Antigravity plugin**:
   ```bash
   cadabby install --antigravity
   ```
2. Open the vault in Antigravity. The plugin provides:
   - An MCP sidecar running `cadabby mcp`.
   - Two specialized personas:
     - **`@librarian`**: Researches raw sources, checks prior knowledge, scaffolds notes, and resolves links.
     - **`@technician`**: Runs `vault_status(lint=true)`, repairs links, moves misplaced notes, and tracks verification debt.

### Workflow C: Human Reading & Editing (Obsidian & CLI)

1. Open `my-vault/` in **Obsidian**:
   - Wikilinks `[[Note-Stem]]` resolve automatically across the flat wiki and nested cognitive domains.
   - `index.md` acts as your gap report, while Maps of Content (`type: moc`) curate navigation topology.
   - The **core Templates plugin** works as-is. Cadabby reads `.obsidian/templates.json`, skips the folder it names so your templates are never mistaken for notes, and can scaffold from them:
     ```bash
     cadabby scaffold "Flash-Attention" --type concept --desc "IO-aware attention" --template concept
     ```
     The template's body is used with `{{title}}` substituted; its frontmatter is discarded, because OKF frontmatter is engine-owned. Foam's `.foam/templates/` needs no configuration.
   - To start from Cadabby's own note shape, scaffold the starters once:
     ```bash
     cadabby init --vault my-vault --obsidian-templates
     ```
     This writes `templates/Concept.md` and `templates/MOC.md` and points Obsidian at them, so *Insert template* produces correct OKF frontmatter. It is opt-in because it reserves `templates/`, which would otherwise be a normal cognitive domain; an existing template folder is honored instead, and a `templates/` that already holds notes is refused rather than swallowed. Starters fill `title` but leave `description` empty — the plugin cannot prompt for it — so a fresh note fails `cadabby lint` with `FIELD_MISSING` until you write one. That is deliberate: a `TODO` placeholder would pass lint and quietly seed a field that feeds search ranking.
2. **Review and certify notes**:
   When a human inspects a note and certifies its accuracy:
   ```bash
   cadabby verify wiki/Flash-Attention --human
   ```
   *This binds the attestation to the exact `sha256` of the note body and upgrades its trust tier to `human-reviewed` ($2.0\times$ search boost).*
3. **If anyone edits the note body**:
   Cadabby automatically detects the SHA-256 mismatch and demotes the note to `stale-verified` (verification debt), prompting re-review.

---

## 4. Cognitive Domains & Domain Manifests

Cadabby supports modular, multi-domain knowledge architectures. While `wiki/` serves as the canonical knowledge base with a strictly flat layout governed by Maps of Content (MOCs), you can partition knowledge into independent **Cognitive Domains** simply by creating top-level directories (e.g. `customers/`, `projects/`, `research/`, `team/`). Custom domains fully support arbitrary nested directory structures.

### Creating a Cognitive Domain with `AGENTS.md`

Drop an `AGENTS.md` file into the root of any top-level domain folder to configure validation schemas and define agent directives:

```markdown
---
description: Customer accounts, CRM dossiers, and stakeholders
allowed_types:
  - account
  - stakeholder
  - interaction
require_sources: false
---

# Customers Domain Directives

1. Every customer note must include account tier and primary contact.
2. Link stakeholder profiles using `[[Stakeholder-Name]]`.
3. Do not store sensitive secrets or credentials in dossiers.
```

### Manifest Configuration Options

| Field | Type | Default | Purpose |
| :--- | :---: | :---: | :--- |
| `description` | string | `"<Domain> domain"` | Human-readable domain description. |
| `allowed_types` | list[str] | `null` (unrestricted) | Allowed `type:` values in frontmatter. Violations trigger `ENUM_INVALID` in `cadabby lint`. |
| `require_sources`| bool | `false` | When `true`, notes in this domain must specify non-empty `sources: [...]`. |

### Permissive vs. Strict Domains
- **Canonical `wiki/` Domain**: Strictly flat (`wiki/*.md`). Dynamic open typing by default (unless restricted by `wiki/AGENTS.md`). Governed by Maps of Content (`type: moc`).
- **Permissive Domains** (no `AGENTS.md` or `allowed_types: null`): Any non-empty note type and any folder hierarchy are allowed without triggering lint errors.
- **Strict Domains** (`allowed_types` specified): Linter enforces valid types, while allowing cross-domain wikilinks (`[[Note-Stem]]`) to resolve smoothly across all domains. Custom domains support nested folders.

> **Every discovered domain is searchable.** There is no per-domain opt-out: exclusion happens before discovery (reserved names, dot-prefixed directories, build folders), so anything that became a domain is knowledge you put in the vault deliberately. To narrow a query, pass `--domain` / `domain` at the call site rather than hiding content from every future search. See `SPECIFICATION.md` §2.2.

### Step-by-Step: Creating a New Cognitive Domain

1. **Choose a Top-Level Directory Name**: Pick a domain name at the vault root (e.g. `customers/`, `projects/`, `research/`). Ensure the name does not conflict with reserved engine directories (`raw/`, `log/`, `.cadabby/`, `.obsidian/`, `.git/`, `.agents/`, `.claude/`, or environment folders like `.venv/`).
2. **Create the Domain Manifest (Optional but Recommended)**: Create `{domain}/AGENTS.md` to define schema validation and operational directives:
   ```bash
   mkdir -p customers
   cat << 'EOF' > customers/AGENTS.md
   ---
   description: "Customer accounts and dossiers"
   allowed_types:
     - account
     - contact
   require_sources: false
   ---
   # Customer Directives
   Cross-link all accounts to primary contact notes.
   EOF
   ```
3. **Scaffold Notes in the Domain**:
   - **Via CLI**:
     ```bash
     cadabby scaffold "Acme-Corp" --domain customers --type account --description "Enterprise account dossier"
     ```
   - **Via MCP**:
     Call `vault_scaffold_note(title="Acme-Corp", domain="customers", type="account", description="Enterprise account dossier")`.
4. **Verify Domain Discovery & Epistemic Health**:
   ```bash
   cadabby status
   ```
   The status report displays registered domains, their note counts, and schema status.
5. **Validate Schemas & Integrity**:
   ```bash
   cadabby lint
   ```
   The linter validates note frontmatter against the domain's `allowed_types` and layout rules.

### How AI Agents Consume Domain Directives
- **MCP Resources**: Cadabby exposes `vault://domains` (inventory of all discovered domains) and `domain://{name}/directives` (the markdown body of `{domain}/AGENTS.md`).
- **Grounding Enrichment**: When an agent calls `vault_ground` on a note, Cadabby automatically embeds the note's domain definition and localized directives into the response payload.

---

## 5. MCP Architecture (7 Tools & 2 Resources)

Conforming to §5.1-§5.2 of the Technical Specification, Cadabby exposes exactly **7 atomic tools** and **2 dynamic resources** to AI agents:

### Atomic Tools

| Tool | Purpose |
| :--- | :--- |
| **`vault_search`** | Epistemic BM25 full-text search with trust tier boosts, domain filters, and status multipliers. |
| **`vault_ground`** | Retrieves full content, localized domain directives, and 1-hop graph neighborhood (links, backlinks, sources). |
| **`vault_status`** | Vault health check: tier counts, domain breakdown, verification debt, unprocessed `raw/` files, and `finding_counts` from the six lint gates; `lint=true` returns the findings themselves. |
| **`vault_scaffold_note`** | Scaffolds a new typed note in any domain with valid OKF frontmatter and generated attribution. |
| **`vault_update_note`** | Non-destructive frontmatter patch, section append, or section replace with optimistic lock. |
| **`vault_move_note`** | Moves or renames a note and repoints every link to it; dry-run by default, with each affected note's trust tier before and after and a `plan_token` that binds the apply to the plan shown. |
| **`vault_verify_note`** | Cryptographically binds an `agent:<client_id>` attestation to the body SHA-256 (refuses `human:*`). |

### Dynamic Resources

| Resource URI | MIME Type | Description |
| :--- | :--- | :--- |
| **`vault://domains`** | `application/json` | Real-time inventory of all discovered cognitive domains, descriptions, and schema flags. |
| **`domain://{domain}/directives`** | `text/markdown` | Localized operational instructions and guidelines from `{domain}/AGENTS.md`. |

---

## 6. CLI Command Reference

| Command | Description | Example |
| :--- | :--- | :--- |
| `cadabby init` | Scaffold a new vault with all config & skills, optionally with Obsidian starter templates (`--obsidian-templates`) | `cadabby init --vault my-vault --obsidian` |
| `cadabby sync` | Scan files, update SQLite cache & rebuild `index.md` | `cadabby sync` |
| `cadabby status` | Report note counts, trust tiers, and verification debt | `cadabby status` |
| `cadabby search` | Epistemic BM25 search with trust boosts & domain filters | `cadabby search "attention mechanism" --domain wiki` |
| `cadabby ground` | Retrieve note content and 1-hop neighborhood | `cadabby ground wiki/Attention` |
| `cadabby scaffold` | Scaffold a new typed note in any domain, optionally from an Obsidian template (`--template`) | `cadabby scaffold "Transformer" --type concept --domain wiki --desc "Attention model"` |
| `cadabby update` | Patch frontmatter or append/replace sections | `cadabby update wiki/Transformer --replace-section "Overview:New text"` |
| `cadabby move` | Move or rename a note and repoint its links (dry-run by default; `--apply --plan-token <t>` writes what the dry run showed; a trailing `/` moves into a folder) | `cadabby move wiki/Transformer customers/acme/ --apply --plan-token 3f9c…` |
| `cadabby verify` | Stamp cryptographic attestation on note | `cadabby verify wiki/Transformer --human` |
| `cadabby lint` | Run the six normative epistemic linting gates across all domains | `cadabby lint` |
| `cadabby audit` | Check Git blame provenance of human attestations | `cadabby audit --require-signed` |
| `cadabby graph` | Display 1-hop and 2-hop neighbors and co-citations for a note | `cadabby graph wiki/Attention` |
| `cadabby log` | Append a timestamped entry to the active `log.md` ledger | `cadabby log "Reviewed distributed consensus notes"` |
| `cadabby mcp` | Launch the JSON-RPC 2.0 stdio MCP server | `cadabby mcp` |
| `cadabby install` | Register MCP configs in Antigravity or Claude Code | `cadabby install --antigravity` |

---

## 7. Epistemic Trust Tiers

| Tier | Multiplier | Description |
| :--- | :---: | :--- |
| `human-reviewed` | **$2.0\times$** | Certified by a validated human reviewer. Body matches `sha256`. |
| `machine-confirmed` | **$1.0\times$** | Synthesized and verified by an automated AI agent. |
| `stale-verified` | **$0.8\times$** | Previously verified, but note prose drifted without re-review (verification debt). |
| `unverified` | **$0.5\times$** | Newly drafted or imported without verification. |

Status multipliers apply on top of trust tiers:
- `evergreen`: **$1.1\times$**
- `active`: **$1.0\times$**
- `draft`: **$0.7\times$**
- `deprecated`: **$0.3\times$**
- `stub`: **$0.2\times$**

---

## 8. Development & Testing

Cadabby uses standard-library `unittest` with **zero test dependencies**:

```bash
# Fast parallel test execution across all CPU cores (~25s, 536 tests):
python3 tests/run_parallel.py

# Parallel execution with verbose output or target filtering:
python3 tests/run_parallel.py -v
python3 tests/run_parallel.py test_cache

# Canonical sequential test suite:
PYTHONPATH=src python3 -m unittest discover tests
```


